diff --git a/.github/CODEOWNERS b/.github/CODEOWNERS index 431d60ec7df6c98..479cbd5ad05e99d 100644 --- a/.github/CODEOWNERS +++ b/.github/CODEOWNERS @@ -37,7 +37,6 @@ # Templates and sidebars (rari) /files/jsondata/L10n-Template.json @mdn/core-dev -/files/sidebars/ @mdn/core-dev # ============================= CONTROL FILES ============================= # # The CODEOWNERS file must end with these matches: Any pull request changing diff --git a/.github/PULL_REQUEST_TEMPLATE b/.github/PULL_REQUEST_TEMPLATE index c261768bba0028d..6a92448db48b594 100644 --- a/.github/PULL_REQUEST_TEMPLATE +++ b/.github/PULL_REQUEST_TEMPLATE @@ -1,5 +1,19 @@ + + + + + + + +--- + ### Description @@ -17,6 +31,3 @@ - - - diff --git a/.github/labeler.yml b/.github/labeler.yml index c0359b97d8dc085..f542275c3258f7d 100644 --- a/.github/labeler.yml +++ b/.github/labeler.yml @@ -6,7 +6,6 @@ system: - package.json - yarn.lock - .github/** - - .husky/** - .vscode/** - .* - scripts/** diff --git a/.github/workflows/auto-cleanup-bot.yml b/.github/workflows/auto-cleanup-bot.yml index 073abcbec26324d..56b2f78a660b3fc 100644 --- a/.github/workflows/auto-cleanup-bot.yml +++ b/.github/workflows/auto-cleanup-bot.yml @@ -21,14 +21,13 @@ jobs: uses: actions/setup-node@v4 with: node-version-file: ".nvmrc" - cache: yarn - name: Install all yarn packages run: yarn --frozen-lockfile env: # https://github.com/microsoft/vscode-ripgrep#github-api-limit-note GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} - HUSKY: 0 + LEFTHOOK: 0 - name: Lint markdown files run: | @@ -47,7 +46,9 @@ jobs: author: mdn-bot <108879845+mdn-bot@users.noreply.github.com> committer: mdn-bot <108879845+mdn-bot@users.noreply.github.com> body: | - All issues auto-fixed + This PR was generated by [this run](https://github.com/${{ github.repository }}/actions/runs/${{ github.run_id }}) of the [`auto-cleanup-bot`](https://github.com/${{ github.repository }}/blob/${{ github.ref_name }}/.github/workflows/auto-cleanup-bot.yml) workflow. + + All issues were auto-fixed. labels: | automated pr token: ${{ secrets.AUTOMERGE_TOKEN }} @@ -62,8 +63,10 @@ jobs: author: mdn-bot <108879845+mdn-bot@users.noreply.github.com> committer: mdn-bot <108879845+mdn-bot@users.noreply.github.com> body: | + This PR was generated by the [`auto-cleanup-bot`](https://github.com/${{ github.repository }}/blob/${{ github.ref_name }}/.github/workflows/auto-cleanup-bot.yml) workflow. + Auto-fix was run, but additional issues found. - Please review the run log: https://github.com/mdn/content/actions/runs/${{ github.run_id }} + Please review the [run log](https://github.com/${{ github.repository }}/actions/runs/${{ github.run_id }}). labels: | automated pr token: ${{ secrets.AUTOMERGE_TOKEN }} diff --git a/.github/workflows/pr-check-lint_content.yml b/.github/workflows/pr-check-lint_content.yml index ecc094ba6733b39..28807a8d6eb4c1c 100644 --- a/.github/workflows/pr-check-lint_content.yml +++ b/.github/workflows/pr-check-lint_content.yml @@ -26,6 +26,7 @@ jobs: uses: actions/checkout@v4 - name: Get changed files + id: check env: GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} BASE_SHA: ${{ github.event.pull_request.base.sha }} @@ -37,17 +38,17 @@ jobs: --jq '.files | .[] | select(.status|IN("added", "modified", "renamed", "copied", "changed")) | .filename') # filter out files that are not markdown DIFF_DOCUMENTS=$(echo "${DIFF_DOCUMENTS}" | egrep -i "^files/.*\.md$" | xargs) - echo "DIFF_DOCUMENTS=${DIFF_DOCUMENTS}" >> $GITHUB_ENV + echo "DIFF_DOCUMENTS=${DIFF_DOCUMENTS}" >> "$GITHUB_OUTPUT" - name: Checkout HEAD - if: env.DIFF_DOCUMENTS + if: steps.check.outputs.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: steps.check.outputs.DIFF_DOCUMENTS run: | git config --global user.email "108879845+mdn-bot@users.noreply.github.com" git config --global user.name "mdn-bot" @@ -63,21 +64,24 @@ jobs: git commit -m "Code from PR head" - name: Setup Node.js environment - if: env.DIFF_DOCUMENTS + if: steps.check.outputs.DIFF_DOCUMENTS uses: actions/setup-node@v4 with: node-version-file: ".nvmrc" cache: yarn - name: Install all yarn packages - if: env.DIFF_DOCUMENTS + if: steps.check.outputs.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 + id: lint + if: steps.check.outputs.DIFF_DOCUMENTS + env: + DIFF_DOCUMENTS: ${{ steps.check.outputs.DIFF_DOCUMENTS }} run: | # Generate random delimiter # https://docs.github.com/en/actions/using-workflows/workflow-commands-for-github-actions#multiline-strings @@ -88,38 +92,38 @@ jobs: echo "crlf line ending check" CRLF_FAILED=true CRLF_LOG=$(git ls-files --eol ${files_to_lint} | grep -E 'w/(mixed|crlf)') || CRLF_FAILED=false - echo "CRLF_LOG<<${EOF}" >> $GITHUB_ENV - echo "${CRLF_LOG}" >> $GITHUB_ENV - echo "${EOF}" >> $GITHUB_ENV - echo "CRLF_FAILED=${CRLF_FAILED}" >> $GITHUB_ENV + echo "CRLF_LOG<<${EOF}" >> "$GITHUB_OUTPUT" + echo "${CRLF_LOG}" >> "$GITHUB_OUTPUT" + echo "${EOF}" >> "$GITHUB_OUTPUT" + echo "CRLF_FAILED=${CRLF_FAILED}" >> "$GITHUB_OUTPUT" echo "Running markdownlint --fix" MD_LINT_FAILED=false MD_LINT_LOG=$(yarn markdownlint-cli2 --fix ${files_to_lint} 2>&1) || MD_LINT_FAILED=true - echo "MD_LINT_LOG<<${EOF}" >> $GITHUB_ENV - echo "${MD_LINT_LOG}" >> $GITHUB_ENV - echo "${EOF}" >> $GITHUB_ENV - echo "MD_LINT_FAILED=${MD_LINT_FAILED}" >> $GITHUB_ENV + echo "MD_LINT_LOG<<${EOF}" >> "$GITHUB_OUTPUT" + echo "${MD_LINT_LOG}" >> "$GITHUB_OUTPUT" + echo "${EOF}" >> "$GITHUB_OUTPUT" + echo "MD_LINT_FAILED=${MD_LINT_FAILED}" >> "$GITHUB_OUTPUT" echo "Linting front-matter" FM_LINT_FAILED=false FM_LINT_LOG=$(node scripts/front-matter_linter.js --fix true ${files_to_lint} 2>&1) || FM_LINT_FAILED=true - echo "FM_LINT_LOG<<${EOF}" >> $GITHUB_ENV - echo "${FM_LINT_LOG}" >> $GITHUB_ENV - echo "${EOF}" >> $GITHUB_ENV - echo "FM_LINT_FAILED=${FM_LINT_FAILED}" >> $GITHUB_ENV + echo "FM_LINT_LOG<<${EOF}" >> "$GITHUB_OUTPUT" + echo "${FM_LINT_LOG}" >> "$GITHUB_OUTPUT" + echo "${EOF}" >> "$GITHUB_OUTPUT" + echo "FM_LINT_FAILED=${FM_LINT_FAILED}" >> "$GITHUB_OUTPUT" echo "Running Prettier" PRETTIER_FAILED=false PRETTIER_LOG=$(yarn prettier --check ${files_to_lint} 2>&1) || PRETTIER_FAILED=true - echo "PRETTIER_LOG<<${EOF}" >> $GITHUB_ENV - echo "${PRETTIER_LOG}" >> $GITHUB_ENV - echo "${EOF}" >> $GITHUB_ENV - echo "PRETTIER_FAILED=${PRETTIER_FAILED}" >> $GITHUB_ENV + echo "PRETTIER_LOG<<${EOF}" >> "$GITHUB_OUTPUT" + echo "${PRETTIER_LOG}" >> "$GITHUB_OUTPUT" + echo "${EOF}" >> "$GITHUB_OUTPUT" + echo "PRETTIER_FAILED=${PRETTIER_FAILED}" >> "$GITHUB_OUTPUT" yarn prettier -w ${files_to_lint} if [[ -n $(git diff) ]]; then - echo "FILES_MODIFIED=true" >> $GITHUB_ENV + echo "FILES_MODIFIED=true" >> "$GITHUB_OUTPUT" fi # info for troubleshooting @@ -130,13 +134,13 @@ jobs: git diff - name: Setup reviewdog - if: env.FILES_MODIFIED == 'true' || env.MD_LINT_FAILED == 'true' - uses: reviewdog/action-setup@3f401fe1d58fe77e10d665ab713057375e39b887 # v1.3.0 + if: steps.lint.outputs.FILES_MODIFIED == 'true' || steps.lint.outputs.MD_LINT_FAILED == 'true' + uses: reviewdog/action-setup@e04ffabe3898a0af8d0fb1af00c188831c4b5893 # v1.3.2 with: reviewdog_version: latest - name: Suggest changes using diff - if: env.FILES_MODIFIED == 'true' + if: steps.lint.outputs.FILES_MODIFIED == 'true' env: REVIEWDOG_GITHUB_API_TOKEN: ${{ secrets.GITHUB_TOKEN }} run: | @@ -151,8 +155,9 @@ jobs: -reporter=github-pr-review < "${TMPFILE}" - name: Add reviews for markdownlint errors - if: env.MD_LINT_FAILED == 'true' + if: steps.lint.outputs.MD_LINT_FAILED == 'true' env: + MD_LINT_LOG: ${{ steps.lint.outputs.MD_LINT_LOG }} REVIEWDOG_GITHUB_API_TOKEN: ${{ secrets.GITHUB_TOKEN }} run: | echo "${MD_LINT_LOG}" | \ @@ -164,16 +169,16 @@ jobs: -reporter="github-pr-review" - name: Fail if any issues pending - if: env.FILES_MODIFIED == 'true' || env.CRLF_FAILED == 'true' || env.MD_LINT_FAILED == 'true' || env.FM_LINT_FAILED == 'true' + if: steps.lint.outputs.FILES_MODIFIED == 'true' || steps.lint.outputs.CRLF_FAILED == 'true' || steps.lint.outputs.MD_LINT_FAILED == 'true' || steps.lint.outputs.FM_LINT_FAILED == 'true' env: - CRLF_FAILED: ${{ env.CRLF_FAILED }} - MD_LINT_FAILED: ${{ env.MD_LINT_FAILED }} - FM_LINT_FAILED: ${{ env.FM_LINT_FAILED }} - PRETTIER_FAILED: ${{ env.PRETTIER_FAILED }} - CRLF_LOG: ${{ env.CRLF_LOG }} - MD_LINT_LOG: ${{ env.MD_LINT_LOG }} - FM_LINT_LOG: ${{ env.FM_LINT_LOG }} - PRETTIER_LOG: ${{ env.PRETTIER_LOG }} + CRLF_FAILED: ${{ steps.lint.outputs.CRLF_FAILED }} + MD_LINT_FAILED: ${{ steps.lint.outputs.MD_LINT_FAILED }} + FM_LINT_FAILED: ${{ steps.lint.outputs.FM_LINT_FAILED }} + PRETTIER_FAILED: ${{ steps.lint.outputs.PRETTIER_FAILED }} + CRLF_LOG: ${{ steps.lint.outputs.CRLF_LOG }} + MD_LINT_LOG: ${{ steps.lint.outputs.MD_LINT_LOG }} + FM_LINT_LOG: ${{ steps.lint.outputs.FM_LINT_LOG }} + PRETTIER_LOG: ${{ steps.lint.outputs.PRETTIER_LOG }} run: | echo -e "\nPlease fix all the linting issues mentioned in the following logs and in the PR review comments." diff --git a/.github/workflows/pr-labeler.yml b/.github/workflows/pr-labeler.yml index 670de1643c2bf38..05ae142e15fb452 100644 --- a/.github/workflows/pr-labeler.yml +++ b/.github/workflows/pr-labeler.yml @@ -32,7 +32,7 @@ jobs: name: Label by size runs-on: ubuntu-latest steps: - - uses: codelytv/pr-size-labeler@1c3422395d899286d5ee2c809fd5aed264d5eb9b # v1.10.2 + - uses: codelytv/pr-size-labeler@4ec67706cd878fbc1c8db0a5dcd28b6bb412e85a # v1.10.3 with: GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} github_api_url: "https://api.github.com" diff --git a/.github/workflows/pr-rebase-needed.yml b/.github/workflows/pr-rebase-needed.yml index f44a7383c97f203..dfdc7d264dccfbd 100644 --- a/.github/workflows/pr-rebase-needed.yml +++ b/.github/workflows/pr-rebase-needed.yml @@ -1,4 +1,4 @@ -name: "PR Needs Rebase" +name: "PR conflicts" on: push: @@ -9,8 +9,12 @@ permissions: # Label pull requests. pull-requests: write +concurrency: + group: pr-rebase-needed-${{ github.event.pull_request.number }} + cancel-in-progress: true + jobs: - label-rebase-needed: + labeler: uses: mdn/workflows/.github/workflows/pr-rebase-needed.yml@main with: target-repo: "mdn/content" diff --git a/.github/workflows/pr-review-companion.yml b/.github/workflows/pr-review-companion.yml index 24d837dfcd844fb..a33e757ce7fdd5c 100644 --- a/.github/workflows/pr-review-companion.yml +++ b/.github/workflows/pr-review-companion.yml @@ -42,66 +42,16 @@ jobs: run-id: ${{ github.event.workflow_run.id }} - name: Check for artifacts + id: check if: hashFiles('build/') != '' run: | - echo "HAS_ARTIFACT=true" >> "$GITHUB_ENV" - PR_NUMBER=`cat build/NR` - echo "PREFIX=pr$PR_NUMBER" >> "$GITHUB_ENV" - - - uses: actions/checkout@v4 - if: env.HAS_ARTIFACT - with: - repository: mdn/yari - path: yari - - - name: Install Python - if: env.HAS_ARTIFACT - id: setup-python - uses: actions/setup-python@v5 - with: - python-version: "3.10" - - # See https://www.peterbe.com/plog/install-python-poetry-github-actions-faster - - name: Load cached ~/.local - if: env.HAS_ARTIFACT - uses: actions/cache@v4 - with: - path: ~/.local - # the trailing number is used to increase for getting - # a different cache key when this file changes - key: dotlocal-${{ runner.os }}-${{ steps.setup-python.outputs.python-version }}-0 - - - name: Install Python poetry - if: env.HAS_ARTIFACT - uses: snok/install-poetry@76e04a911780d5b312d89783f7b1cd627778900a # v1.4.1 - with: - virtualenvs-create: true - virtualenvs-in-project: true - - - name: Load cached venv - if: env.HAS_ARTIFACT - id: cached-poetry-dependencies - uses: actions/cache@v4 - with: - path: yari/deployer/.venv - # the trailing number is used to increase for getting - # a different cache key when this file changes - 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' - run: | - cd yari/deployer - poetry install --no-interaction --no-root - - - name: Install Deployer - if: env.HAS_ARTIFACT - run: | - cd yari/deployer - poetry install --no-interaction + echo "HAS_ARTIFACT=true" >> "$GITHUB_OUTPUT" + PR_NUMBER=`cat build/NR | tr -dc '0-9'` + echo "PR_NUMBER=$PR_NUMBER" >> "$GITHUB_OUTPUT" + echo "PREFIX=pr$PR_NUMBER" >> "$GITHUB_OUTPUT" - name: Authenticate with GCP - if: env.HAS_ARTIFACT + if: steps.check.outputs.HAS_ARTIFACT uses: google-github-actions/auth@v2 with: token_format: access_token @@ -109,49 +59,59 @@ jobs: workload_identity_provider: projects/${{ secrets.WIP_PROJECT_ID }}/locations/global/workloadIdentityPools/github-actions/providers/github-actions - name: Setup gcloud - if: env.HAS_ARTIFACT + if: steps.check.outputs.HAS_ARTIFACT uses: google-github-actions/setup-gcloud@v2 - name: Upload to GCS - if: env.HAS_ARTIFACT + if: steps.check.outputs.HAS_ARTIFACT uses: google-github-actions/upload-cloud-storage@v2 with: path: "build" - destination: "${{ vars.GCP_BUCKET_NAME }}/${{ env.PREFIX }}" + destination: "${{ vars.GCP_BUCKET_NAME }}/${{ steps.check.outputs.PREFIX }}" resumable: false - concurrency: 500 + headers: |- + cache-control: no-store parent: false + concurrency: 500 process_gcloudignore: false - - name: Deploy and analyze built content - if: env.HAS_ARTIFACT - env: - BUILD_OUT_ROOT: ${{ github.workspace }}/build + - name: Checkout (mdn/content) + uses: actions/checkout@v4 + if: steps.check.outputs.HAS_ARTIFACT + with: + path: content - DEPLOYER_BUCKET_NAME: mdn-content-dev - AWS_ACCESS_KEY_ID: ${{ secrets.DEPLOYER_DEV_AWS_ACCESS_KEY_ID }} - AWS_SECRET_ACCESS_KEY: ${{ secrets.DEPLOYER_DEV_AWS_SECRET_ACCESS_KEY }} - DEPLOYER_LOG_EACH_SUCCESSFUL_UPLOAD: false + - name: Setup (mdn/content) + uses: actions/setup-node@v4 + if: steps.check.outputs.HAS_ARTIFACT + with: + node-version-file: "content/.nvmrc" - run: | - PR_NUMBER=`cat build/NR` + - name: Install (mdn/content) + if: steps.check.outputs.HAS_ARTIFACT + env: + # https://github.com/microsoft/vscode-ripgrep#github-api-limit-note + GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} + working-directory: content + run: yarn --frozen-lockfile + - name: Analyze PR build + if: steps.check.outputs.HAS_ARTIFACT + env: + BUILD_OUT_ROOT: ${{ github.workspace }}/build + PREFIX: ${{ steps.check.outputs.PREFIX }} + PR_NUMBER: ${{ steps.check.outputs.PR_NUMBER }} + working-directory: content + run: | echo "Pull request:" echo "https://github.com/mdn/content/pull/$PR_NUMBER" - cd yari/deployer - - poetry run deployer upload \ - --prefix="pr$PR_NUMBER" \ - --default-cache-control 0 \ - "$BUILD_OUT_ROOT" - - poetry run deployer analyze-pr-build \ - --prefix="pr$PR_NUMBER" \ + node scripts/analyze-pr-build.js \ + --prefix="$PREFIX" \ --analyze-flaws \ --analyze-dangerous-content \ - --github-token="${{secrets.GITHUB_TOKEN}}" \ + --github-token="${{ secrets.GITHUB_TOKEN }}" \ --repo=$GITHUB_REPOSITORY \ - --pr-number=$PR_NUMBER \ + --pr-number="$PR_NUMBER" \ --diff-file=$BUILD_OUT_ROOT/DIFF \ $BUILD_OUT_ROOT diff --git a/.github/workflows/pr-test-legacy.yml b/.github/workflows/pr-test-legacy.yml deleted file mode 100644 index c3b5718c93b5309..000000000000000 --- a/.github/workflows/pr-test-legacy.yml +++ /dev/null @@ -1,135 +0,0 @@ -# This file tests more or less everything related to a pull request. All -# in one big job. At the end, if all the testing passes, it proceeds -# to upload all the files that were built to our Dev environment. -# This way, if the tests passed, you'll be able to review the built -# pages on a public URL. - -name: PR Test Legacy - -on: - pull_request: - branches: - - main - -permissions: - # Compare two commits. - contents: read - -jobs: - tests: - if: github.repository == 'mdn/content' - runs-on: ubuntu-latest - env: - BASE_SHA: ${{ github.event.pull_request.base.sha }} - HEAD_SHA: ${{ github.event.pull_request.head.sha }} - # This is the directory where the built files will be placed. - # It's also hardcoded in the `yarn build` command in package.json. - # If you change it here, you must also make the same change in - # package.json. - BUILD_OUT_ROOT: build - - steps: - - uses: actions/checkout@v4 - - - name: Get changed files - run: | - # Use the GitHub API to get the list of changed files - # documentation: https://docs.github.com/rest/commits/commits#compare-two-commits - DIFF_DOCUMENTS=$(gh api repos/{owner}/{repo}/compare/${BASE_SHA}...${HEAD_SHA} \ - --jq '.files | .[] | select(.status|IN("added", "modified", "renamed", "copied", "changed")) | .filename') - - # filter out files that are not markdown files - GIT_DIFF_CONTENT=$(echo "${DIFF_DOCUMENTS}" | egrep -i "^files/.*\.(md)$" | xargs) - echo "GIT_DIFF_CONTENT=${GIT_DIFF_CONTENT}" >> $GITHUB_ENV - - # filter out files that are not attachments - GIT_DIFF_FILES=$(echo "${DIFF_DOCUMENTS}" | egrep -i "^files/.*\.(png|jpeg|jpg|gif|svg|webp)$" | xargs) - echo "GIT_DIFF_FILES=${GIT_DIFF_FILES}" >> $GITHUB_ENV - env: - GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} - - - name: Setup Node.js environment - 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 - run: yarn --frozen-lockfile - env: - # https://github.com/microsoft/vscode-ripgrep#github-api-limit-note - GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} - - - name: Build changed content - id: build-content - if: env.GIT_DIFF_CONTENT - env: - CONTENT_ROOT: ${{ github.workspace }}/files - - # This is so that if there's a single 'unsafe_html' flaw, it - # completely fails the build. - # But all other flaws should be 'warn', so that we can include - # information about the flaws when we analyze the built PR. - BUILD_FLAW_LEVELS: "unsafe_html: error, *:warn" - - # Because we build these pages in a way that you get a toolbar, - # so the flaws can be displayed, but we don't want any of the - # other toolbar features like "Fix fixable flaws" or "Quick-edit" - # we set this to disable that stuff. - REACT_APP_CRUD_MODE_READONLY: true - - BUILD_LIVE_SAMPLES_BASE_URL: https://live.mdnyalp.dev - BUILD_LEGACY_LIVE_SAMPLES_BASE_URL: https://live-samples.mdn.allizom.net - - # In these builds, we never care for or need the ability to sign in. - # This environment variable will disable that functionality entirely. - REACT_APP_DISABLE_AUTH: true - - # TODO: This should be implicit when `CI=true` - BUILD_NO_PROGRESSBAR: true - - # Playground - REACT_APP_PLAYGROUND_BASE_HOST: mdnyalp.dev - - 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 "Disk usage size of the build" - du -sh $BUILD_OUT_ROOT - - # Save the PR number into the build - echo ${{ github.event.number }} > ${BUILD_OUT_ROOT}/NR - - # Download the raw diff blob and store that inside the build - # directory. - # The purpose of this is for the PR Review Companion to later - # be able to use this raw diff file for the benefit of analyzing. - 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 - 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 - # Show the final disk usage size of the build. - du -sh $BUILD_OUT_ROOT - - - uses: actions/upload-artifact@v4 - if: env.GIT_DIFF_CONTENT - with: - name: build - path: ${{ env.BUILD_OUT_ROOT }} - - - name: Check changed files - if: env.GIT_DIFF_FILES - run: | - echo $GIT_DIFF_FILES - - export CONTENT_ROOT=$(pwd)/files - yarn filecheck $GIT_DIFF_FILES diff --git a/.github/workflows/pr-test.yml b/.github/workflows/pr-test.yml index c4082cc0a483e00..adb08e887b476b2 100644 --- a/.github/workflows/pr-test.yml +++ b/.github/workflows/pr-test.yml @@ -32,6 +32,7 @@ jobs: - uses: actions/checkout@v4 - name: Get changed files + id: check run: | # Use the GitHub API to get the list of changed files # documentation: https://docs.github.com/rest/commits/commits#compare-two-commits @@ -40,23 +41,23 @@ jobs: # filter out files that are not markdown files GIT_DIFF_CONTENT=$(echo "${DIFF_DOCUMENTS}" | egrep -i "^files/.*\.(md)$" | xargs) - echo "GIT_DIFF_CONTENT=${GIT_DIFF_CONTENT}" >> $GITHUB_ENV + echo "GIT_DIFF_CONTENT=${GIT_DIFF_CONTENT}" >> "$GITHUB_OUTPUT" # filter out files that are not attachments GIT_DIFF_FILES=$(echo "${DIFF_DOCUMENTS}" | egrep -i "^files/.*\.(png|jpeg|jpg|gif|svg|webp)$" | xargs) - echo "GIT_DIFF_FILES=${GIT_DIFF_FILES}" >> $GITHUB_ENV + echo "GIT_DIFF_FILES=${GIT_DIFF_FILES}" >> "$GITHUB_OUTPUT" env: GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} - name: Setup Node.js environment - if: env.GIT_DIFF_CONTENT || env.GIT_DIFF_FILES + if: steps.check.outputs.GIT_DIFF_CONTENT || steps.check.outputs.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: steps.check.outputs.GIT_DIFF_CONTENT || steps.check.outputs.GIT_DIFF_FILES run: yarn --frozen-lockfile env: # https://github.com/microsoft/vscode-ripgrep#github-api-limit-note @@ -64,8 +65,10 @@ jobs: - name: Build changed content id: build-content - if: env.GIT_DIFF_CONTENT + if: steps.check.outputs.GIT_DIFF_CONTENT env: + GIT_DIFF_CONTENT: ${{ steps.check.outputs.GIT_DIFF_CONTENT }} + CONTENT_ROOT: ${{ github.workspace }}/files # This is so that if there's a single 'unsafe_html' flaw, it @@ -119,7 +122,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: steps.check.outputs.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 +130,15 @@ jobs: du -sh $BUILD_OUT_ROOT - uses: actions/upload-artifact@v4 - if: env.GIT_DIFF_CONTENT + if: steps.check.outputs.GIT_DIFF_CONTENT with: name: build path: ${{ env.BUILD_OUT_ROOT }} - name: Check changed files - if: env.GIT_DIFF_FILES + if: steps.check.outputs.GIT_DIFF_FILES + env: + GIT_DIFF_FILES: ${{ steps.check.outputs.GIT_DIFF_FILES }} run: | echo $GIT_DIFF_FILES diff --git a/.github/workflows/spelling-check-bot.yml b/.github/workflows/spelling-check-bot.yml index bdf920c38098f91..0e072994ff7a0b3 100644 --- a/.github/workflows/spelling-check-bot.yml +++ b/.github/workflows/spelling-check-bot.yml @@ -23,25 +23,31 @@ jobs: uses: actions/setup-node@v4 with: node-version-file: ".nvmrc" - cache: yarn + + - name: Install all yarn packages + run: yarn --frozen-lockfile + env: + # https://github.com/microsoft/vscode-ripgrep#github-api-limit-note + GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} - name: Run scripts + id: check run: | echo Running spelling check... - output=$(npx cspell --no-progress --gitignore --config .vscode/cspell.json "**/*.md" || exit 0) + output=$(yarn --silent lint:typos-group-by-file || exit 0) if [ -n "${output}" ]; then output=$(node scripts/linkify-logs.js "${output}") output=$(echo "$output" | sed 's/^/- /') echo "$output" - echo "OUTPUT<> $GITHUB_ENV - echo "$output" >> $GITHUB_ENV - echo "EOF" >> $GITHUB_ENV + echo "OUTPUT<> "$GITHUB_OUTPUT" + echo "$output" >> "$GITHUB_OUTPUT" + echo "EOF" >> "$GITHUB_OUTPUT" else echo "No typos found! 🎉" fi - name: Report spellcheck errors - if: env.OUTPUT != '' + if: steps.check.outputs.OUTPUT != '' run: | issue=$(gh issue create --title "$TITLE" --label "$LABELS" --body "$BODY") echo Issue URL ${issue} @@ -52,7 +58,7 @@ jobs: BODY: | Typos and unknown words: - ${{ env.OUTPUT }} + ${{ steps.check.outputs.OUTPUT }} > [!TIP] > If the word is actually valid or it is required to be ignored, consider adding it to one of the dictionaries under [`.vscode/dictionaries`](https://github.com/mdn/content/tree/main/.vscode/dictionaries). diff --git a/.github/workflows/system-file-changes.yml b/.github/workflows/system-file-changes.yml index b3b3dbbde3fde46..26e44f7f259760d 100644 --- a/.github/workflows/system-file-changes.yml +++ b/.github/workflows/system-file-changes.yml @@ -20,14 +20,26 @@ jobs: if: github.repository_owner == 'mdn' && github.event.pull_request.user.login != 'dependabot[bot]' runs-on: ubuntu-latest steps: - # - uses: hmarr/debug-action@v2 - - name: Stop anything and everything + - name: Block if author/actor is not an admin + env: + GH_TOKEN: ${{ github.token }} run: | - # It would be nice if we could disable this workflow if the PR - # was made from a branch within the origin repo. But it seems you - # can't do that :( - # See https://github.community/t/how-do-you-figure-out-if-a-pr-is-from-a-work-in-pull-request-target-workflows/170001 + # Check author. + AUTHOR="${{ github.event.pull_request.user.login }}" + AUTHOR_PERMISSION=$(gh api https://api.github.com/repos/${{ github.repository }}/collaborators/$AUTHOR/permission --jq .permission) - echo "If you're an admin, you have to use your admin privileges to override." - echo "If you're not an admin, please ping someone for a review." - exit 1 + if [ "$AUTHOR_PERMISSION" != "admin" ]; then + echo "PR author ($AUTHOR) is not an admin, please ping someone for a review." + exit 1 + fi + + # Check actor. + ACTOR="${{ github.actor }}" + if [ "$ACTOR" != "$AUTHOR" ]; then + ACTOR_PERMISSION=$(gh api https://api.github.com/repos/${{ github.repository }}/collaborators/$ACTOR/permission --jq .permission) + + if [ "$ACTOR_PERMISSION" != "admin" ]; then + echo "PR actor ($ACTOR) is not an admin, please ping someone for a review." + exit 1 + fi + fi diff --git a/.gitignore b/.gitignore index 1939b35615d81c0..c5a59591416bef3 100644 --- a/.gitignore +++ b/.gitignore @@ -6,3 +6,4 @@ yarn-error.log* _githistory.json .DS_Store .idea +*.log diff --git a/.husky/post-merge b/.husky/post-merge deleted file mode 100644 index 847276be20007da..000000000000000 --- a/.husky/post-merge +++ /dev/null @@ -1,15 +0,0 @@ -BRANCH="$(git rev-parse --abbrev-ref HEAD)" -if [ "$BRANCH" != "main" ]; then - exit 0 -fi - -if [ -f ".husky/_/history" ]; then - lastHash=$(cat ./.husky/_/history) - isUpdated=$(git diff $lastHash HEAD -- ./package.json) - if [ "$isUpdated" != "" ]; then - echo - echo "⚠🔥 'package.json' has changed. Please run 'yarn install'! 🔥" - fi -else - yarn install -fi diff --git a/.husky/pre-commit b/.husky/pre-commit deleted file mode 100755 index 2312dc587f61186..000000000000000 --- a/.husky/pre-commit +++ /dev/null @@ -1 +0,0 @@ -npx lint-staged diff --git a/.lefthook.yml b/.lefthook.yml new file mode 100644 index 000000000000000..bdb32dd0c9db9c9 --- /dev/null +++ b/.lefthook.yml @@ -0,0 +1,62 @@ +pre-commit: + parallel: true + jobs: + - name: Format sidebars + glob: "files/sidebars/*.yaml" + run: yarn content fmt-sidebars + stage_fixed: true + + - name: Fix redirects + glob: "files/en-us/_redirects.txt" + run: yarn content fix-redirects en-US && yarn content validate-redirects en-US + stage_fixed: true + + - name: Format non-markdown + glob: "*.{js,json,yml,yaml,css,html}" + run: yarn prettier --write --cache {staged_files} + stage_fixed: true + + - name: Sort cSpell dictionaries + glob: ".vscode/dictionaries/*.txt" + run: node scripts/sort_and_unique_file_lines.js {staged_files} + stage_fixed: true + + - name: Run 'yarn filecheck' + glob: "*.{svg,png,jpeg,jpg,gif}" + run: yarn filecheck {staged_files} + + - name: Check URL issues + glob: "files/**/*.md" + run: node scripts/log-url-issues.js + + - name: Front matter tests + glob: "tests/**/*.*" + run: yarn test:front-matter-linter + + - name: Fix markdown + glob: "*.md" + group: + parallel: true + jobs: + - name: Front matter + run: node scripts/front-matter_linter.js --fix true {staged_files} + stage_fixed: true + - name: Markdownlint + run: yarn markdownlint-cli2 --fix {staged_files} + stage_fixed: true + - name: Prettier + run: yarn prettier --write --cache {staged_files} + stage_fixed: true + - name: Check changed xrefs + run: yarn node scripts/update-moved-file-links.js --check + +post-merge: + only: + - ref: main + commands: + yarn-install: + run: yarn install + +output: + - summary + - failure diff --git a/.lintstagedrc.js b/.lintstagedrc.js deleted file mode 100644 index ad18175879ccc0f..000000000000000 --- a/.lintstagedrc.js +++ /dev/null @@ -1,24 +0,0 @@ -export default { - "files/en-us/_redirects.txt": (filenames) => [ - `yarn content fix-redirects en-US`, - `yarn content validate-redirects en-US`, - ], - "!*.md": (filenames) => [ - `prettier --ignore-unknown --write ${filenames.join(" ")}`, - ], - "*.md": (filenames) => [ - `markdownlint-cli2 --fix ${filenames.join(" ")}`, - `node scripts/front-matter_linter.js --fix true ${filenames.join(" ")}`, - `node scripts/update-moved-file-links.js --check`, - `prettier --write ${filenames.join(" ")}`, - ], - "tests/**/*.*": (filenames) => [`yarn test:front-matter-linter`], - "*.{svg,png,jpeg,jpg,gif}": (filenames) => [ - `yarn filecheck ${filenames.join(" ")}`, - ], - "*": (filenames) => [`node scripts/log-url-issues.js`], - ".vscode/dictionaries/*.txt": (filenames) => [ - `node scripts/sort_and_unique_file_lines.js ${filenames.join(" ")}`, - ], - "files/sidebars/*.yaml": (filenames) => [`yarn content fmt-sidebars`], -}; diff --git a/.markdownlint.jsonc b/.markdownlint.jsonc index 9d25f924cbc63f8..2090b220491920b 100644 --- a/.markdownlint.jsonc +++ b/.markdownlint.jsonc @@ -104,7 +104,59 @@ "no-bare-urls": false, // Produces too many false positives "no-space-in-emphasis": false, - "fenced-code-language": true, + "fenced-code-language": { + // Your language is not in this list? Please check https://github.com/orgs/mdn/discussions/170#discussioncomment-3404366 + "allowed_languages": [ + "apacheconf", + "bash", + "batch", + "c", + "cpp", + "cs", + "css", + "css-nolint", + "diff", + "django", + "glsl", + "hbs", + "hbs-nolint", + "html", + "html-nolint", + "http", + "ini", + "java", + "js", + "js-nolint", + "json", + "json-nolint", + "jsx", + "jsx-nolint", + "latex", + "md", + "md-nolint", + "nginx", + "php", + "plain", + "powershell", + "pug", + "python", + "regex", + "rust", + "scss", + "sh", + "sql", + "svelte", + "svg", + "toml", + "ts", + "url", + "vue", + "wat", + "webidl", + "xml", + "yaml", + ], + }, // See https://github.com/mdn/content/pull/20026, as macros currently break this "no-empty-links": false, "code-block-style": { @@ -118,6 +170,24 @@ }, // Disabled, as yari generates link fragments by replacing spaces with underscores, not dashes. "link-fragments": false, + "descriptive-link-text": { + "prohibited_texts": [ + "here", + "link", + "more", + "this", + "this link", + "this page", + "this site", + "this article", + "click here", + "click this link", + "see here", + "see this page", + "see this site", + "see this article", + ], + }, // https://github.com/OnkarRuikar/markdownlint-rule-search-replace "search-replace": { @@ -208,14 +278,7 @@ { "name": "un-closed-md-link", "message": "Missing closing bracket ')'", - "searchPattern": "/(\\[[^\\]]*?\\]\\(([^\\)\\n]|\\([^\\)\\n]\\)|\\s[\"'])+?)(\\n|\\s|[,:][\\s\\n])/gm", - "searchScope": "text", - }, - { - "name": "text-code-fence", - "message": "Use 'plain' tag", - "searchPattern": "/(^ *`{3,})(text|none|unix)/gm", - "replace": "$1plain", + "searchPattern": "/\\[.*?\\]\\([^ )\\n\"]+(?:[\\n\"]| [^\"']| [\"'].+?[\"'][^)])/gm", "searchScope": "text", }, { @@ -228,9 +291,30 @@ "name": "bad-gfm-alert", "message": "Use the correct GFM syntax: `> [!NOTE]`", // TODO this should use the modifier syntax; until it has better Node support - "searchPattern": "/^ *> !?\\[!?((?!NOTE)[Nn][Oo][Tt][Ee]|(?!WARNING)[Ww][Aa][Rr][Nn][Ii][Nn][Gg]|(?!CALLOUT)[Cc][Aa][Ll][Ll][Oo][Uu][Tt])\\]\\n|^ *> (?!\\[!)!?\\[!?(NOTE|WARNING|CALLOUT)\\]\\n/gm", + "searchPattern": "/^ *> !?\\[!?((?!NOTE)[Nn][Oo][Tt][Ee]|(?!WARNING)[Ww][Aa][Rr][Nn][Ii][Nn][Gg]|(?!CALLOUT)[Cc][Aa][Ll][Ll][Oo][Uu][Tt])\\]\\n|^ *> (?!\\[!)!?\\[!?(NOTE|WARNING|CALLOUT)\\]\\n|^ *> \\[!(NOTE|WARNING|CALLOUT)\\](?!\\n)/gm", + "searchScope": "text", + }, + { + "name": "comma-after-ie", + "message": "Add comma after 'i.e.'", + "searchPattern": "/\\bi\\.e\\. /g", + "replace": "i.e., ", + "searchScope": "text", + }, + { + "name": "comma-after-eg", + "message": "Add comma after 'e.g.'", + "searchPattern": "/\\be\\.g\\. /g", + "replace": "e.g., ", "searchScope": "text", }, + { + "name": "short-link", + "message": "Use shortened links for bug links", + "searchPattern": "/https:\\/\\/bugzilla\\.mozilla\\.org\\/show_bug\\.cgi\\?id=/g", + "replace": "https://bugzil.la/", + "searchScope": "all", + }, ], }, } diff --git a/.vscode/cspell.json b/.vscode/cspell.json index 16154a9e2b0f183..8024f6698b02e45 100644 --- a/.vscode/cspell.json +++ b/.vscode/cspell.json @@ -13,9 +13,6 @@ "ignore-list", "bash", "css", - "cpp", - "django", - "filetypes", "fonts", "fullstack", "html", @@ -26,7 +23,6 @@ "npm", "python", "softwareTerms", - "svelte", "typescript" ], "ignorePaths": [ @@ -41,6 +37,7 @@ "{{\\s*EmbedLiveSample\\(.*\\)\\s*}}", "{{\\s*EmbedYouTube\\(.*\\)\\s*}}", "{{\\s*EmbedGHLiveSample\\(.*\\)\\s*}}", + "live-sample___[\\w-]+", // Markdown links "\\]\\(\\S*\\)", // Website references diff --git a/.vscode/dictionaries/code-entities.txt b/.vscode/dictionaries/code-entities.txt index 4ac75eccbe9fd36..81681f917c754c9 100644 --- a/.vscode/dictionaries/code-entities.txt +++ b/.vscode/dictionaries/code-entities.txt @@ -1,25 +1,9 @@ -moz-activehyperlinktext --moz-buttondefault -moz-buttonhoverface -moz-buttonhovertext -moz-cellhighlight -moz-cellhighlighttext --moz-dragtargetzone --moz-fieldtext -moz-hyperlinktext --moz-lwtheme --moz-lwtheme-brighttext --moz-lwtheme-darktext --moz-mac-accentdarkestshadow --moz-mac-accentdarkshadow --moz-mac-accentface --moz-mac-accentlightesthighlight --moz-mac-accentlightshadow --moz-mac-accentregularhighlight --moz-mac-accentregularshadow --moz-mac-menuselect --moz-mac-menushadow --moz-mac-menutextselect -moz-maemo-classic -moz-menuhover -moz-menuhovertext @@ -29,13 +13,13 @@ -moz-samplesize -moz-styleeditor-transitioning -moz-visitedhyperlinktext --moz-win-communicationstext --moz-win-mediatext 3rdparty +__cplusplus accentcolor accentcolortext Accept-EncodXng accessibility.disablecache +accessibilitysidebar acodec activetitlebarcolor addstream @@ -46,9 +30,7 @@ afrc afterscriptexecute alaw allowdirs -allowdropevent allowevents -ALLOWFROM alternatingbackground ALTGR amssymb @@ -58,9 +40,9 @@ anonid apacheconf apachectl appcache +APPCOMMAND APPCOMMAND_MEDIA_PREVIOUSTRACK appinstalled -appium_logs_url appshell appversion appworld @@ -85,12 +67,9 @@ backgroundfetchsuccess BACKTAB Basetime bbaw -beforeevicted -beforeinput beforeinstallprompt beforematch beforescriptexecute -beforetoggle beforexrselect BGRX bhks @@ -105,12 +84,17 @@ browser.sessionhistory browsingtopics bstack buttondisabledaccept +bvec +byterange +byteranges CACHEDIR cakm +cand-type canmakepayment -canvas.hitregions cbcs +ccall cdylib +cenc certerror characterboundsupdate characteristicvaluechanged @@ -123,38 +107,38 @@ chromeos chws clipboardchange clon +closedby +closerequest cnonce colindextext +collectstatic color-CBDT color-colrv0 color-colrv1 color-sbix colorMaskiOES commandfor -compositionend -compositionstart -compositionupdate congres connectionavailable contentaccessible contentdelete contentvisibilityautostatechange -contextlost -contextrestored controlslist cookiechange cpanel-dcv cqmax cqmin +createsuperuser +creds cros crossdomain.xml Crsel cryptomining csiso csrfmiddlewaretoken -CSRFTOKEN CSS_RGBCOLOR csslint +cssref cssruleview ctron ctrz @@ -167,15 +151,8 @@ dangi deviceproximity devtools.aboutdebugging devtools.errorconsole -devtools.inspector.ruleview -devtools.netmonitor -devtools.webconsole diak -dialogheight -dialogleft dialogtext -dialogtop -dialogwidth diffe disablechrome disablefastfind @@ -183,14 +160,15 @@ disableiOES disablepictureinpicture disableremoteplayback dischargingtimechange +django.contrib.contenttypes docbook documentboundary dom.abortablepromise dom.closewatcher dom.element.customstateset dom.input.dirpicker -dom.keyboardevent dom.media.webcodecs +dom.performance.event_timing.enable_interactionid dom.screenorientation dom.shadowdom dom.webcomponents @@ -201,7 +179,7 @@ dom.webnotifications.requireuserinteraction dom.webshare domxref downdiagonalstrike -DPAD +downloadprogress DRAGDDROP dragdrop draggesture @@ -216,6 +194,7 @@ ehtml EISU elementname elementtiming +elems emailtracking emcc emconfigure @@ -236,16 +215,17 @@ Exsel externref fangsong fencedframe +fgets filecheck FILLMODE_FILL_WINDOW finishedtransferringdata +firefoxsidebar fiuv font.mathfont-family fontconfig fontobject fonts-lmodern forloop.last -formdata freearc fullpage fullscreenbutton @@ -266,6 +246,7 @@ gfx.offscreencanvas Glat globoff Gloc +glossarysidebar gonm GPOS Grek @@ -285,26 +266,32 @@ hmng hmnp horizontalstrike hsides +htdocs +htmlsidebar +htmlspecialchars HTMLWBRElement -HTTPWG +httpsidebar hvline iarc_rating_id -icccolor +icontains +idbversionchangeevent +idledetector IDOM +iexact +ifchanged ifequal ifnotequal -IIRFilter imageset imghp imgur implicit_jscontext importmap -imscjs inactivetitlebarcolor indexeddb-examples indexifembedded inputreport inputsourceschange +intitle intl.uidirection.locale intrinsicsize ipados @@ -349,6 +336,7 @@ KEY_dead_perispomeni KEY_dead_psili KEY_dead_semivoiced_sound keybase.txt +keyboardlock KEYCODE_ENDCALL KEYCODE_HEADSETHOOK KEYCODE_SYSRQ @@ -367,6 +355,7 @@ largeop latexmlc Latf layers.offmainthreadcomposition +learnsidebar leavepictureinpicture legacycaller lepc @@ -377,6 +366,7 @@ libvpx libwebp libwww lineboundary +lining-nums livescript loadingdone loadingerror @@ -388,11 +378,13 @@ lowdelay lowp lquote ltrh +makemigrations mathbb mathbold mathdbl mathit mathml +mathmlref mathmono mathrm mathsanb @@ -400,6 +392,7 @@ mathsans mathtt max-smbps maxplaybackrate +MD5-sess mdnsidebar media.autoplay.block-webaudio media.getusermedia @@ -407,9 +400,10 @@ media.mediasource media.peerconnection media.peerconnection.rtpsourcesapi media.rvfc -media.setsinkid +media.videocontrols.picture-in-picture media.webspeech mediaelement +mediasidebar mediastream mediummathspace mediump @@ -426,7 +420,6 @@ mlabeledtr mlym MMDD Mobi -mod_autoindex modif moof moov @@ -446,6 +439,7 @@ msvideo msword mtei mths +multistatus mymr mymrepka mymrpao @@ -463,7 +457,6 @@ negativeverythickmathspace negativeverythinmathspace negativeveryverythickmathspace negativeveryverythinmathspace -neterror network.http.referer.defaultPolicy.pbmode newtab nextslide @@ -476,6 +469,7 @@ nofullscreen noimageindex nolint noremoteplayback +nosniff notecard notif notificationbox @@ -493,7 +487,6 @@ nsIUDP nsIURI nsIURL nsIXSLT -nslookup nsPIDOMWindow nsresult OEM_CUSEL @@ -503,18 +496,17 @@ Okhsl Okhsv olck oldstyle +oldstyle-nums onao onbeforematch -onbeforetoggle oncanmakepayment oncharacterboundsupdate oncontentvisibilityautostatechange -oncontextlost -oncontextrestored oncurrententrychange oncurrentscreenchange ondequeue ondispose +ondownloadprogress onefive ongesturestart onnavigate @@ -524,27 +516,32 @@ onpagereveal onpageswap onpaymentrequest onpointerrawupdate +onprerenderingchange onrtctransform +onsamplebufferfull onscreenschange -onscrollend onscrollsnapchange onscrollsnapchanging onsinkchange ontextformatupdate ontextupdate onuncapturederror +onwebkitmouseforcewillbegin opendocument openidconnect openpgp4fpr opensearchdescription openxmlformats-officedocument operatorname +opsz org.mozilla.geckoview_example org.w3.clearkey ornm orya oscpu +osfile.jsm osma +otpcredential outbound-rtpp overlayinfo packetlossperc @@ -561,11 +558,13 @@ paymentmethodchange paymentrequest pcast peerjs +performancesidebar periodicsync permessage personaltoolbar phonebk PHPSESSID +pictureinpicturewindow PINGOTHER pjpeg PlatformNaclArch @@ -579,7 +578,9 @@ popovertargetaction postactivate postmkproject powerefficient +prefs prefwindow +preg_replace premkproject prerenderingchange presentationml @@ -592,14 +593,21 @@ privacy.clearsitedata privacy.globalprivacycontrol privacy.restrict3rdpartystorage privatebrowsingmode +propfind prophoto-rgb +proportional-nums +PROPPATCH +propstat PUNCHTHROUGH purgecaches PVRTC +pwasidebar pwid pythonanywhere pyxpidl +queryset quicktime +raddr rcap readingerror readwriteflush @@ -623,10 +631,13 @@ rspadd RTCICECandidatePairStats rtctransform rtpmap +runserver rustc rustup +s-maxage safariextz SAMEORIGIN +samplebufferfull samplerate samr sansserif @@ -635,13 +646,14 @@ saur scalethumbend scalethumbstart scalethumbtick +scanf screenschange -scrollend scrollsnapchange scrollsnapchanging scts sdcard sdch +sdrag searchjl searchplugins sectionhead @@ -651,6 +663,7 @@ seekforward seekto seeother selectchange +selectedcontent selectend seltype sentenceboundary @@ -658,6 +671,8 @@ SeparateiOES serialno serviceworker setenvif +SHA-256-sess +SHA-512-sess sharpyuv shrd shtm @@ -666,32 +681,40 @@ sinkchange sizemodechange skipad slnt -slotchange +smartcardconnection smpl smsto +snews SPACEBAR speculationrules +speechrecognition spreadsheetml sprop-parameter-sets squeezeend squeezestart srgba8 +sscanf stackoverflow_url +startapp +startproject +staticfiles +storageaccess +strcmp streamfilter +stripslashes stripsurroundingwhitespace +strncpy SUBDOCUMENT sund sunu superspeed -SVGDOMElement -SVGHKernElement SVGMPathElement -SVGVKernElement +svgref svgz -swsh tabbox tabbrowser tabs-closebutton +tabular-nums takr talu taml @@ -701,6 +724,7 @@ telu testingbot-api texlive texlive-fontsextra +text-autospace textformatupdate textupdate TEXTUREI @@ -738,10 +762,13 @@ unic unihan unixcksum unixsum +unorm updiagonalstrike -urange +urandom urlbar urlclassifier.trackingAnnotationTable +urlpatterns +urlsidebar urpmi usedtx useinbandfec @@ -749,6 +776,7 @@ usercontext-content userhash userproximity utterleft +uuencode uvec vaii validlink @@ -759,10 +787,12 @@ verythickmathspace verythinmathspace veryverythickmathspace veryverythinmathspace +vfprintf videooutput viewsource.css VIRTUALENVWRAPPER virtualkeyboardpolicy +virtuals VK_CRSEL VK_EREOF VK_EXSEL @@ -783,10 +813,12 @@ VK_WIN_OEM_FJ_MASSHOU VK_WIN_OEM_FJ_ROYA VK_WIN_OEM_FJ_TOUROKU VK_WIN_OEM_WSCTRL +vline vmatrix Vplugin vrml vsides +vsprintf wara wcho wdth @@ -800,6 +832,7 @@ webglcontextcreationerror webglcontextlost webglcontextrestored webgpu +webhid webidentity webidl webkitmouseforcechanged @@ -809,15 +842,16 @@ webkitmouseforcewillbegin webmv webrtc webRTCIPHandlingPolicy +webshare webshell webtransport WEBVTT webxr +webxrdevice wentaway wght wimax WM_MOUSEHWHEEL -WM_MOUSEWHEEL wordprocessingml workon WORKON_HOME @@ -829,6 +863,7 @@ x-ms-aria-flowfrom xbitmap xhgt xloc +xmlsidebar xpcnativewrappers xpidl xpinstall diff --git a/.vscode/dictionaries/cultural-words.txt b/.vscode/dictionaries/cultural-words.txt index 96c65b07fdbb1b6..712b92d838cedf0 100644 --- a/.vscode/dictionaries/cultural-words.txt +++ b/.vscode/dictionaries/cultural-words.txt @@ -13,6 +13,7 @@ Bopomofo Chakma Chiki Citi +Cloquet Côte d'Ivoire dakuten @@ -22,7 +23,6 @@ furigana Gannen Garay geng-zi -Gondi Gunjala Gurung Halloumi @@ -30,8 +30,8 @@ Hanifi Hankaku Henkan Hijri +Hinckley Hiroko -Hmong háček Jeonja Kayah @@ -39,6 +39,7 @@ Khema Khudawadi Kirat Kolkata +Kursha Laing Lepcha Limbu @@ -50,17 +51,18 @@ Meetei Mihret Minguo Minh +Miramichi Muhenkan Mundari Mundi Newa nosinė Nyiakeng -Ol Onal Osmanya Oyayubi Pahawh +Peshtigo Puachue Reiwa Reykjavík @@ -79,7 +81,6 @@ Tham Tirhuta Tlayolotl Totnes -Uruk Wancho Warang Zenkaku diff --git a/.vscode/dictionaries/ignore-list.txt b/.vscode/dictionaries/ignore-list.txt index ecad9b219cc5d51..b61b49a94c77729 100644 --- a/.vscode/dictionaries/ignore-list.txt +++ b/.vscode/dictionaries/ignore-list.txt @@ -33,7 +33,6 @@ apiscript Argh Asclepias aurl -Awwww AXQB azuki baaabaac @@ -41,14 +40,12 @@ baabac barfoo bbbc Beastify -Beetlejuice bfalse bgpicker bigcorp blaa blaaa blabla -Blahblah bleh BlYAJQFz bobsmith @@ -81,7 +78,9 @@ chatserver Clampin clita coegdfgfddffbgning +concedays Confecta +confs.tech consectetuer consetetur Consonantia @@ -93,7 +92,7 @@ cubetexture cycletracker data-ffo-opensans data-ffo-opensanslight -davidwalsh.name +dbar dbbd Decem demozilla @@ -138,7 +137,6 @@ fgrt46jfgd filteron finanzierungs flabada -flexy foobarbaz foobarfoo fooexamplefoo @@ -164,14 +162,13 @@ gubergren harborside hellonode HEXDIG -hexdigit -hiliteabeunti howtoplay HUD5767ghtyfyr4536dh45dg45dg3 idbkeyrange IHdhcyBncmVhdCE innerht.ml inquam +inquit insertx inserty insertz @@ -194,7 +191,6 @@ jícama kasd Khiresh kitchensink -lambdatest Latine latinmodern-math learntocodewith.me @@ -203,7 +199,6 @@ letmein libpkcs11testmodule librero livin -liZhYMsy8MGgxUny6Q8NCoH9xSiviwLFfK Llanfair LLLLLLLLLLLLLLLLRRRRRRRRRRRRRRRR locallibrary @@ -223,7 +218,6 @@ morethanwarm MYAGE mybooks myclass -Myco mynamespace myns mypassword @@ -232,6 +226,7 @@ mytestsite myusername Nada Ndeg +nomin nono79 nonummy nonumy @@ -259,13 +254,13 @@ privat proinde public-webapps pwllgwyngyll -PXHQTXP Quaaaack quandong quaxxor quickbrownfox quxyz rebum +reddes regelialia rheeeeet ricebean @@ -299,13 +294,13 @@ todomvc tomatillo topsecretpassword traa +truemark.dev TURO TUROPC Tweety UCCE ultricied updatebg -UQND urlscheme userconnect userdisconnect @@ -325,7 +320,6 @@ webvr weta Whereami Whereshire -wisen wisi Wookie xyzzy diff --git a/.vscode/dictionaries/non-english.txt b/.vscode/dictionaries/non-english.txt index a1d5a58527334ec..1f943412712f063 100644 --- a/.vscode/dictionaries/non-english.txt +++ b/.vscode/dictionaries/non-english.txt @@ -2,14 +2,15 @@ Accessibilità Allons Ashita Assemblée +Aéro bezje canadien -Català Ceci communiqué Congrès contenido couleur +czaszką dans demeure Deutsch @@ -42,6 +43,7 @@ ijsland indomable İstanbul JOURS +lepiej Mais Majestatis minuto @@ -49,6 +51,8 @@ minutos Moin Montag Musée +napisem +narysowaną nicht Nordamerikanische Normalzeit @@ -57,7 +61,6 @@ oscuro partes partout pasado -Português présenté puede quand @@ -66,7 +69,6 @@ quinto Repetitio resh réservé -résumé s'écrase schon Schonheit @@ -88,9 +90,13 @@ tslí uisce Umgebung warum +wchodzić Westküsten Westküstenzeit +widzimy Zitat +znak +środka ˈbraːˈvo ˈdeltɑ ˈtʃɑːli diff --git a/.vscode/dictionaries/proper-names.txt b/.vscode/dictionaries/proper-names.txt index 6ccf9c90cc88f6d..755c424fc6045e9 100644 --- a/.vscode/dictionaries/proper-names.txt +++ b/.vscode/dictionaries/proper-names.txt @@ -4,20 +4,20 @@ Academind Acrosync Addy Adham +Adhemar Adilah Akhgari alastairc Aldous Alexa -alispivak Alman Amit Amorim -AMPPS Amstelvar Amélie Anand ANDI +Andreas Andreessen Andrzej Anek @@ -25,7 +25,6 @@ Annonay Ansari Ansyari Apapou -Appelquist Aptana Arkanoid Artur @@ -43,7 +42,6 @@ Ayşe Azarath Aziz Balhetan -Barning bartaz Bartek belgin @@ -51,14 +49,14 @@ Benbadis Bento4 Berners Binaryen -Biraj Birtles bitsies Bitsov Bixa +Blackman Blackmoon +Blankers Bloggs -Bocoup Bodmin Boonie bottosson @@ -67,15 +65,12 @@ Brians Browserleaks Browsershots Browsersync -Bruant -BugZilla +Bubka Bundlesize Bunyakovsky -Burson Butterick Buzzcocks Bynens -Bézier Béziers caitmuenster Camino @@ -87,13 +82,13 @@ carinaanand Carle Cassini Caterina -Chadha +caugner Chakra Chamakh Chimero Chloé +Choyce chrisdavidmills -chrismills Chromecast Chromeo Cinepak @@ -108,13 +103,9 @@ coderprateek codingintrigue Codrops Colomb -ColorZilla Conde -Condei -COPPA Corber Cortana -Coursera Coyier Cratchit Crockford @@ -128,14 +119,12 @@ Dahlkemper Dailymotion Danilo Dannaway -Darmok Datumizer davbrito Dedalium Dedreux Deepti -Degit -DekiWiki +Deke Delaville Denicola DeSandro @@ -143,6 +132,7 @@ Desaulniers Desproges Devlin Dexie +Diffie Digga Digianswer DigiNotar @@ -150,14 +140,17 @@ Dijit Diridum Discogs Disqus +Dmitry Domenic dorey Dotclear Dottoro +Downey Dragomir Drasner -Dreamweaver Dutton +Dwan +Dwyane dynamis Dyno Dynos @@ -179,16 +172,15 @@ Envato Ephesis Eplepsia Erba -Erdös +ERCIM ericwbailey Esben -ethertank Eventbrite Exljbris +Exocoetidae +Fadeyev Fairchild FDCP -ffconf -FileZilla Firefogg Firesheep Firmata @@ -196,40 +188,37 @@ Firtman Flagfox Flavio Flickr -Florian flowplayer Fontsquirrel François Frederik Frida -Fujisawa Galinski Gandi Gayatri +Gebrselassie geckodriver Gedit Gerd -gifplayer -Gillenwater +Giancarlo Gitbash Golightly Googlebot +Gordo Grahl -Granado Grande-Dixence Graywolf9 Grigsby +Grissom Groff -groovecoder GSAP Guildford +Haile Hamish hamishwillee Haml Haverbeke -Hazael Headsight -Hermina Heydings Heydon Hickson @@ -238,7 +227,6 @@ Highrise Hildy hmatrjp Hobday -Hobson hochan Hochberg Hoenigswald @@ -246,69 +234,57 @@ Holborn Holdem Holzman Honigswald -hoosteeno Hoshi Hoth Hyperaudio Hönigswald Icecast idb-keyval -Igalia Imagify +Iniesta Inkscape intercooler -Invision Ionos -Isac +Irena ITCSS ITEC -Jalad Jalkhov jamiedoe Janc -Jannis Jarkko JasonLamv-t jasonren Jayla Jeni -Jeremie Jewett Jinping Jitsi -jmswisher Johansson Joomla -Jory Josiel Jost Joyo jpmedley JSCAMP jswebm -Jérémie +Junxia Júnior -Kadir Kadlec Kahlo Kaku Kaply -Karahalis -Kardell -Karmakar Kaspersky Katari Kazam -Kearney kenji-yamasaki Kerckhoffs +Kersee Kesteren -Kettner +Khronos Kinlan Kinnon kirsty Kirupa -Kitsune Klar Kleene Kligman @@ -317,19 +293,15 @@ Kneeland Knocky Knowbility Kobabe +Koen Kokoro -Komodo Konva -Koszuliński -Kulikov Kyouko Kütük -Lagerblad -Lanyrd Laravel Lauke -Leidel -Leithead +Leatherman +LeBron Leitura Lemieux Lempel @@ -339,6 +311,7 @@ Lesh Lexi Leyla Lianghekou +Libera.Chat Libertinus Lighttpd Lindenberg @@ -360,13 +333,11 @@ mapsort marcelozarate Marcotte Marijn -Martell Masayuki -Massieux Mathoid Matomo Matroska -Maxability +Matuzovic Maximiliano Mayank Mazur @@ -375,13 +346,10 @@ McLellan McNally McVerry Megalosaurus -Meggin Mercure Merkle -meyerweb mfuji Miata -Mickley Mielczarek Mihajlija Milica @@ -402,13 +370,10 @@ Montulli Moonrocks Mooog Morgawr -Morinigo Mork Mothman -Moussavi mozhacks Mufasa -Mullany Musa Musaceae Musicr @@ -419,12 +384,10 @@ Naeher Nakamura Nakano Nathália -Navara Nazarrudin Nazário Necko Neocities -Netbeans Nixpacks Noida Norah @@ -447,24 +410,20 @@ OptiPNG Orendorff Osmani Owlman +Paavo Paciello Pacman Pagella Paletton Parecki -Patonnier Pell Penadés Pereira Perlin Petrov -Pflug Phong -Photoshop Picryl -Pinia Pinterest -Piotrek Pissuti Pixabay Pixi.js @@ -491,35 +450,32 @@ Rapp Rauschmayer Realtek Recep -Reeza +Reis Rekapi Remy Resig -Rhiana -Riazhskikh Rigby +Robison Rocher Rohini Ronaldo Roselli Rossi +Rossum Roushan rsvg -rubentd Rumyra Ryuno -Régagnon Saionaro Salame Salva Sandrina sashasushko -Saurabh -Scarfone +Scarlett Schiff +Schirra Schmarsow Schola -Scholz Schwarz Scooby scottohara @@ -528,7 +484,6 @@ Scrimba Seamonkey Serpentina Shadeed -Sheppy Shilpa Shinoda Shireen @@ -542,6 +497,7 @@ Sivonen Skeletor Skywalker Slaght +Slayton SlimerJS Snackbars.jsm Softgames @@ -555,7 +511,6 @@ souphttpclientsink SpeciFISHity spip Spitzer -Spivak Squoosh Stalybridge Starcraft @@ -563,27 +518,23 @@ Starfleet Statcounter Stratford Stylo -Sukriti sunhpark42 sveltesociety SVGOMG Swooop Symfony +Szewinska Tabliss Tamaran Tanx Techopedia Tegra Telenor -Temba -teoli Termes Tetris TeXbook TeXmacs -TeXZilla Theora -Thierry Tidwell Tink tinypng @@ -591,8 +542,6 @@ Titilayo Tokopedia Tomayac Tonisha -Tooru -Topal Transcribear Transformiix Trekhleb @@ -601,13 +550,14 @@ Trish tristantheb Trustwave twgl -Updown +Usain usrsctp Vallejoanderson Vanderheiden Vandermonde Vash Vegur +Venkat Verou Vieno Vint @@ -626,18 +576,19 @@ Webopedia webref Weinstein Weyl -Whitlock Widevine Wikibooks Willee Willigers Winamp Winchelsea +Wireshark Wirfs wisedog Wolenetz Wrox XAMPP +Xavi Xiluodu Xiowan XITS @@ -650,7 +601,7 @@ Yoav Yoshi Yousafzai Yslow -Yubikey +YubiKey Yuki Yura Zakas @@ -658,7 +609,7 @@ Zakirt zantroke zantrokeregular Zaptec -Zartner +Zatopek Zehe Zenevich Zepto diff --git a/.vscode/dictionaries/terms-abbreviations.txt b/.vscode/dictionaries/terms-abbreviations.txt index 4d7333f313b596c..d6e4fef093d9519 100644 --- a/.vscode/dictionaries/terms-abbreviations.txt +++ b/.vscode/dictionaries/terms-abbreviations.txt @@ -1,16 +1,13 @@ AABB ABNF abspos -ACAO accname achromatopsia ACSS -ADHD ADPCM ADSR AEDT AEST -affordance aggregatable ALAC alphanumerals @@ -21,11 +18,11 @@ ANMF anonymization antialiasing antitracking -apideck APNG appcontent arcosh arcseconds +ARGB arsinh artanh ASCAP @@ -37,7 +34,6 @@ ATAG atlasing ATSC autoallocate -autobuffering autocapitalization autoconfig autocorrection @@ -49,9 +45,9 @@ autofocusing autogrow autogrowing autohide +automagically automaticity autoplace -autoplacement autoplaying autoplays AVPF @@ -62,10 +58,13 @@ backronym barcodes barebones bfcache +BGRA Bignums bikeshedding bilevel +bitfield bitmapped +bitness bitplanes bitrates bitstream @@ -83,8 +82,8 @@ bluify BMFF bootup botmaster +BPPmaxKb BPTC -Brotli browserless BSAC bytestream @@ -93,6 +92,7 @@ bytestring callsite catchable CAVLC +CCITT CCPA CCPL CELP @@ -102,22 +102,27 @@ checkboard checkedness checkmarks childlist +chipsets choosable +CIELAB CIPA +ciphertext CJKT CLDR +clickjacking clipspace clonable CLREQ codabar +codegen codepaths -codespace COEP colex colexographical collapser collectability collinearity +colorspaces COLR colubris columnset @@ -132,15 +137,19 @@ coprime CORB credentialled credentialless +CRSF cryptids +cryptosystem cryptosystems CSSWG CSWH -CTAP cubemap cubemaps +CWND Dangit +DARPA databinding +datagrams datalists datestamped DBFS @@ -150,6 +159,7 @@ decodability Deinonychus demi demultiplexing +demux demuxing deoptimize deprioritized @@ -161,17 +171,20 @@ destructures detuning deutan deuteranomaly -devrel -dezippering dinos +discardable +distros DLRR DLSR docshell docshells +doctypes doorhanger +dotless downsampled downsampling -downscaling +dragonfish +DSCP DTLSL dyscalculia EBNF @@ -182,16 +195,15 @@ encrypter engageable EOTF ephemerons -EPUB equirect equirectangular ESSL -ethnicities ETSI exfiltrating -exfiltration +EXIF expando EXSL +EXSLT extractability extradata extranet @@ -205,7 +217,7 @@ falsiness fangled fastload favoriting -FIFA +fieldsets findability findbar Finito @@ -219,7 +231,6 @@ fontface fontfaces footguns forgeable -FOSS FOUC Fourway FOUT @@ -228,18 +239,20 @@ foveated foveation fragmentainer fragmentainers +framebuffers frontmost Fullband fullscreened +fullwidth futexes Gamedev Gamedevs -gameplay gameworld gameworlds Gbps GCLI generatable +geofencing geolocate geolocated geolocating @@ -247,9 +260,9 @@ GEOSTD8 gifs GIFV glanceable +GLSL GPGPU GPII -GPIO GPRS grabbable Gradians @@ -277,6 +290,7 @@ hotspots hoverable HPKE HPKP +HSTS HTCPCP HVXC IACVT @@ -286,10 +300,13 @@ iconset idents IERS IMSC +Indo-Pacific inferencing infobar infobox infoboxes +inlinable +inlines inputtable insertable insideness @@ -299,6 +316,7 @@ interactable interarrival interceptable interdimensional +interframes internetworking interpupillary intrinsicness @@ -308,7 +326,6 @@ isoluminant jank janking janky -JavaScripters javascripting JFIF JLREQ @@ -317,6 +334,7 @@ JSON-ifiable jsonifier jumpless JXON +KACST Kbit Kbps keysyms @@ -328,7 +346,6 @@ Kona labelable laggy lazify -leaderboards leetspeak letterboxed letterboxing @@ -349,7 +366,6 @@ longhands longterm longwinded lookaheads -losslessly LPCM LSTM luma @@ -360,9 +376,9 @@ macroblock macroblocks mansplaining maplike -MATF MBASW -Metafile +Mbit +Mbps metalness metastring microcontrollers @@ -374,6 +390,7 @@ microsummaries microsummary microsyntax microsyntaxes +middlebox minifiers mirrorable misissuance @@ -386,7 +403,6 @@ modelessly Mojibake monkeypatch monoscopic -mouselook Mozillians MSAA MSISDN @@ -401,7 +417,7 @@ multisampled multisampling multiscreen multistream -multitouch +multiuser multivalued multiview muscaria @@ -415,11 +431,9 @@ naïvely NCBI NCLX netherbeasts -neuroscientists nightlies nomming nonbinary -nonceable nonliteral nonsparse nonstrict @@ -428,10 +442,12 @@ noteblocks NPAPI NPOT NSPR +NTLM NTSC OCSP OFCOM offsetted +ogonek old-timey Omnibox OMTA @@ -448,9 +464,9 @@ overlines overscript overscripts overscrolling +packetization packetizer packetizing -pageload paintable pantherina papermakers @@ -460,6 +476,7 @@ pathfinding paywalled PCMA PCMU +PCRE pedestaling performantly phasor @@ -467,6 +484,7 @@ phishable phonebook phonorecord phonorecords +pilcrow pillarboxed pingback pingbacks @@ -478,7 +496,6 @@ playout PLTE plumeria polyfilling -polylines polymarker polymarkers pomaceous @@ -488,7 +505,6 @@ posterization posterizing powerups preactivate -precache precached precaches precaching @@ -503,6 +519,7 @@ preflighting preflights preloaders premultiplication +preorder prepopulate prepopulating prerendered @@ -520,6 +537,7 @@ PSTN psychoacoustic psychoacoustics Pterothorax +Pthreads QCIF QCMS QPACK @@ -532,7 +550,6 @@ quicklinks quickmenu qvalues QWERTZ -randomizer rari rasterizes RDBMS @@ -551,6 +568,7 @@ renderable renderbuffers reparsed replayability +reportee repost reposted reposts @@ -559,19 +577,15 @@ reproject requirable rescan reselecting +resends resizability -resnapped respecified restartless retarget retargeted -retargeting retargetings -reviewdog RFCOMM RGTC -roadmaps -Rockhopper romcoms roundoff RSAOAEP @@ -581,20 +595,22 @@ RTMP RTMPE RTMPS RTMPT -ruleset -rulesets +RTSP run-throughs +résumé safelisted Saltasaurus sandboxing SAOC scanability +scancode scattergun schemeful scopable -screencast +scorpionfish screenful scriptable +scriptless scrollers scrollport SECAM @@ -618,6 +634,9 @@ side-scrollers sideload sideloaded SIDX +significand +singlecast +singlecasts Sino SISD SISR @@ -627,6 +646,7 @@ skipnav skybox skyboxes slabcraft +slablike slottables SMACSS SMARTPOSTER @@ -634,8 +654,6 @@ SMIL smoosh SMPTE snapport -snapshotted -snapshotting SNES spammy spatialization @@ -645,12 +663,16 @@ spatialized SPDY speedwalk spinbuttons +spinlocking +spinlocks spoofable spritesheet spritesheets SSML +ssthresh STIX strawman +streamable streamless streetdog strikethroughs @@ -659,16 +681,15 @@ stringifiers stringifying stringly strobing -styleable styracosaurus subarticle subarticles -subbuffer subcarrier subclassing subcollections subcomponent subcomponents +subexpression subfeature subformula subformulas @@ -686,7 +707,6 @@ submatch submatches subminor subminute -subpage subpages subpanels subpattern @@ -697,13 +717,17 @@ subprojects subproperty subrectangle subrectangles +subrequest +subrequests subresource subresources +subsampled +subsampling +subsecond subsentence subsetting substate substeps -substream substreams subtag subtags @@ -728,13 +752,12 @@ SVCB syncbase tablists tabstrip -tada Tanuki targetable taskbars taskboard -Techmakers teleporting +texels textboxes thenables thresholding @@ -744,20 +767,21 @@ thumbstick thumbsticks TIAS tickmarks -tiktok tilemap tilemaps tileset +timebox timecode timecodes -timeframe timerange timeslice timeslices timestep +tinyfill +TIPC toggletips +toolkits toolsets -touchpad touchpads touchpoint touchpoints @@ -781,21 +805,26 @@ tritanomaly TTFB TTML TTSI +tweened tweens UAAG ufrag -unabbreviate +UMTS unbookmark +unbundling uncacheable uncategorized unclickable unclipped +uncollapse uncollapsing +uncompiled unconfigurable unconfigure +unconfigured uncredentialed underflowing -underliner +underflows underlyingly underover underscript @@ -806,6 +835,8 @@ unergonomically unfiled unfilterable unforgeable +ungroup +ungrouping unguaranteed unhovered uninterpolated @@ -813,6 +844,7 @@ unintuitively unioned uniquify unlayered +unlocalized unmaps unminified unmuting @@ -823,6 +855,8 @@ unprefix unprefixing unprioritized unreadably +unregisters +unregistration unretrievable unrotated UNSC @@ -832,14 +866,14 @@ unsets unsponsored unstylable unstyling +unsupporting unsyntactic untaint untextured unthrottled untriaged unzoomed -upscaling -usecase +uppercasing userbase VDOM Velociraptor @@ -875,26 +909,27 @@ whitepoint whizzy WHOIS WICG -wireframe +wideband wireframed +wireframes wordmark wordmarks workgroups worklets workstreams +writability writemasks -WYSIYWG -XMLHTTP +WSGI XPCOM xrayed Xrays XRCPU +xsleaks XSSI yari yearless Zalgo zoomable ZQSD -Zstandard ZWNBSP ZWSP diff --git a/.vscode/extensions.json b/.vscode/extensions.json index 666ebd4f8bab12f..edcee35e6eaa76a 100644 --- a/.vscode/extensions.json +++ b/.vscode/extensions.json @@ -2,6 +2,7 @@ "recommendations": [ "davidanson.vscode-markdownlint", "esbenp.prettier-vscode", - "streetsidesoftware.code-spell-checker" + "streetsidesoftware.code-spell-checker", + "tyriar.lorem-ipsum" ] } diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 0ff32d85c4c4731..1cd2ad0a8b8f35f 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -32,7 +32,7 @@ There are a few things to keep in mind about content on MDN and how it is mainta - A document's `index.md` starts with "front-matter" described in [Front-matter](#front-matter). - Documents have corresponding folders (the JavaScript page's `index.md` is in [`files/en-us/web/javascript`](files/en-us/web/javascript), for example). - Document folders may contain images referenced by the `index.md` file in that folder. -- A document folder may contain child folders with child documents (e.g., [`files/en-us/web/javascript/closures/index.md`](files/en-us/web/javascript/closures/index.md)). +- A document folder may contain child folders with child documents (e.g., [`files/en-us/web/javascript/reference/index.md`](files/en-us/web/javascript/reference/index.md)). - Redirects are specified in [`_redirects.txt`](files/en-us/_redirects.txt). Do not edit this file manually! See [Moving documents](#moving-documents) for details. @@ -216,9 +216,9 @@ This will make it easier to submit a pull request for your changes. #### Linting edited files -To ensure that all MDN documents follow the same formatting, we use both [Prettier](https://www.prettier.io) and [MarkdownLint](https://github.com/DavidAnson/markdownlint) to format and lint Markdown files. This helps us enforce uniform styling across all documents with minimal reviewer intervention. +To ensure that all MDN documents follow the same formatting, we use both [Prettier](https://prettier.io/) and [MarkdownLint](https://github.com/DavidAnson/markdownlint) to format and lint Markdown files. This helps us enforce uniform styling across all documents with minimal reviewer intervention. -If you have a [local checkout](#forking-and-cloning-the-repository) of the repository and have [installed the dependencies](#preparing-the-project), or you are using [github.dev](https://github.dev), a pre-commit hook will be installed which automatically runs while making a commit. To save some headache and improve your work flow while authoring, you may wish to [configure your editor to automatically run Prettier](https://prettier.io/docs/en/editors.html). Alternatively, you may run `yarn fix:md` in the command line to manually format all Markdown files. +If you have a [local checkout](#forking-and-cloning-the-repository) of the repository and have [installed the dependencies](#preparing-the-project), or you are using [github.dev](https://github.dev/), a pre-commit hook will be installed which automatically runs while making a commit. To save some headache and improve your work flow while authoring, you may wish to [configure your editor to automatically run Prettier](https://prettier.io/docs/editors.html). Alternatively, you may run `yarn fix:md` in the command line to manually format all Markdown files. > [!NOTE] > Automatically formatting changes does not work for pull requests opened using the GitHub Web UI as described in the ["Simple changes" section](#simple-changes). @@ -251,7 +251,7 @@ yarn content move [locale] To use `yarn content move`, provide the slug of the document you'd like to move (e.g., `Learn/Accessibility`), and the slug of its new location (e.g., `Learn/A11y`). The locale of the existing document can be provided as an optional third argument (this defaults to `en-US`). For other locales, `CONTENT_TRANSLATED_ROOT` has to be set correctly in your environment. -If the document you'd like to move contains child documents (i.e. it represents a document tree), the `yarn content move` command will move the entire tree. +If the document you'd like to move contains child documents (i.e., it represents a document tree), the `yarn content move` command will move the entire tree. Let's say you want to move the entire `/en-US/Learn/Accessibility` tree to `/en-US/Learn/A11y`, you can do so as follows: @@ -391,7 +391,7 @@ Here are some things to keep in mind at this point: - Your pull request must be **reviewed and approved** before it's merged into the `main` branch. - **You do not need to request a review**; one or more reviewers will be selected for you automatically. -- **It can be up to 48 hours** for merged pull requests to have their changes published to [MDN Web Docs](https://developer.mozilla.org). +- **It can be up to 48 hours** for merged pull requests to have their changes published to [MDN Web Docs][]. During reviews, you may be asked to answer questions about your work or to make changes to your suggested edits. This is a common part of the process of making changes in open source projects. @@ -425,7 +425,7 @@ See https://github.com/mdn/content/pull/21432 and https://github.com/mdn/content It can be replaced with the normal links syntax after successfully closing https://github.com/DavidAnson/markdownlint/issues/673. --> -[mdn web docs]: https://developer.mozilla.org +[mdn web docs]: https://developer.mozilla.org/ [getting started with mdn web docs]: https://developer.mozilla.org/en-US/docs/MDN/Community/Getting_started [community resources]: https://developer.mozilla.org/en-US/docs/MDN/Community [writing guidelines]: https://developer.mozilla.org/en-US/docs/MDN/Writing_guidelines diff --git a/REVIEWING.md b/REVIEWING.md index cff352fe2ac6387..e41407f56e5f98c 100644 --- a/REVIEWING.md +++ b/REVIEWING.md @@ -23,7 +23,7 @@ out-of-date. This is being handled as follows: 1. Different MDN staff members and volunteers have been assigned as "topic review owners", meaning that when a pull request comes in related to a - particular topic area of the site (e.g. the CSS reference, or the learning + particular topic area of the site (e.g., the CSS reference, or the learning area), it will be assigned to that area's topic review owner(s) and they will receive an email notification asking for a review. This is being handled using a [CODEOWNERS](https://github.com/mdn/content/blob/main/.github/CODEOWNERS) diff --git a/files/en-us/_redirects.txt b/files/en-us/_redirects.txt index a325ab5658b00b0..13908676175d708 100644 --- a/files/en-us/_redirects.txt +++ b/files/en-us/_redirects.txt @@ -5,11 +5,11 @@ /en-US/docs/-moz-locale-dir(ltr) /en-US/docs/Web/CSS/:-moz-locale-dir_ltr /en-US/docs/-moz-locale-dir(rtl) /en-US/docs/Web/CSS/:-moz-locale-dir_rtl /en-US/docs/::file-selector-button /en-US/docs/Web/CSS/::file-selector-button -/en-US/docs/ /en-US/docs/Web/HTML/Element/img +/en-US/docs/ /en-US/docs/Web/HTML/Reference/Elements/img /en-US/docs/AJAX /en-US/docs/Learn_web_development/Core/Scripting/Network_requests /en-US/docs/AJAX/Community /en-US/docs/Learn_web_development/Core/Scripting/Network_requests /en-US/docs/AJAX/Getting_Started /en-US/docs/Learn_web_development/Core/Scripting/Network_requests -/en-US/docs/AJAX/WAI_ARIA_Live_Regions /en-US/docs/Web/Accessibility/ARIA/ARIA_Live_Regions +/en-US/docs/AJAX/WAI_ARIA_Live_Regions /en-US/docs/Web/Accessibility/ARIA/Guides/Live_regions /en-US/docs/AJAX/WAI_ARIA_Live_Regions_API_Support /en-US/docs/Mozilla/Firefox/Releases/3/WAI_ARIA_Live_Regions_API_Support /en-US/docs/AJAX:Community /en-US/docs/Learn_web_development/Core/Scripting/Network_requests /en-US/docs/AJAX:Getting_Started /en-US/docs/Learn_web_development/Core/Scripting/Network_requests @@ -31,98 +31,98 @@ /en-US/docs/API/navigationTiming/Using_Navigation_Timing /en-US/docs/Web/API/Performance_API/Navigation_timing /en-US/docs/API/window.performance/navigationTiming /en-US/docs/Web/API/Performance_API/Navigation_timing /en-US/docs/ARIA /en-US/docs/Web/Accessibility/ARIA -/en-US/docs/ARIA/ARIA_Guides /en-US/docs/Web/Accessibility/ARIA/ARIA_Guides -/en-US/docs/ARIA/ARIA_Live_Regions /en-US/docs/Web/Accessibility/ARIA/ARIA_Live_Regions -/en-US/docs/ARIA/ARIA_Screen_Reader_Implementors_Guide /en-US/docs/Web/Accessibility/ARIA/ARIA_Screen_Reader_Implementors_Guide -/en-US/docs/ARIA/ARIA_Techniques /en-US/docs/Web/Accessibility/ARIA/ARIA_Techniques -/en-US/docs/ARIA/ARIA_Techniques/Using_the_alert_role /en-US/docs/Web/Accessibility/ARIA/Roles/alert_role -/en-US/docs/ARIA/ARIA_Techniques/Using_the_alertdialog_role /en-US/docs/Web/Accessibility/ARIA/Roles/alertdialog_role -/en-US/docs/ARIA/ARIA_Techniques/Using_the_aria-activedescendant_attribute /en-US/docs/Web/Accessibility/ARIA/Attributes/aria-activedescendant -/en-US/docs/ARIA/ARIA_Techniques/Using_the_aria-labelledby_attribute /en-US/docs/Web/Accessibility/ARIA/Attributes/aria-labelledby -/en-US/docs/ARIA/ARIA_Techniques/Using_the_banner_role /en-US/docs/Web/Accessibility/ARIA/Roles/banner_role -/en-US/docs/ARIA/ARIA_Techniques/Using_the_button_role /en-US/docs/Web/Accessibility/ARIA/Roles/button_role -/en-US/docs/ARIA/ARIA_Techniques/Using_the_checkbox_role /en-US/docs/Web/Accessibility/ARIA/Roles/checkbox_role -/en-US/docs/ARIA/ARIA_Techniques/Using_the_dialog_role /en-US/docs/Web/Accessibility/ARIA/Roles/dialog_role -/en-US/docs/ARIA/ARIA_Techniques/Using_the_group_role /en-US/docs/Web/Accessibility/ARIA/Roles/group_role -/en-US/docs/ARIA/ARIA_Techniques/Using_the_listbox_role /en-US/docs/Web/Accessibility/ARIA/Roles/listbox_role -/en-US/docs/ARIA/ARIA_Techniques/Using_the_log_role /en-US/docs/Web/Accessibility/ARIA/Roles/log_role -/en-US/docs/ARIA/ARIA_Techniques/Using_the_presentation_role /en-US/docs/Web/Accessibility/ARIA/Roles/presentation_role -/en-US/docs/ARIA/ARIA_Techniques/Using_the_radio_role /en-US/docs/Web/Accessibility/ARIA/Roles/radio_role -/en-US/docs/ARIA/ARIA_Techniques/Using_the_status_role /en-US/docs/Web/Accessibility/ARIA/Roles/status_role -/en-US/docs/ARIA/ARIA_Techniques/Using_the_textbox_role /en-US/docs/Web/Accessibility/ARIA/Roles/textbox_role -/en-US/docs/ARIA/ARIA_Techniques/Using_the_toolbar_role /en-US/docs/Web/Accessibility/ARIA/Roles/toolbar_role +/en-US/docs/ARIA/ARIA_Guides /en-US/docs/Web/Accessibility/ARIA/Guides +/en-US/docs/ARIA/ARIA_Live_Regions /en-US/docs/Web/Accessibility/ARIA/Guides/Live_regions +/en-US/docs/ARIA/ARIA_Screen_Reader_Implementors_Guide /en-US/docs/Web/Accessibility/ARIA/Guides/Screen_Reader_Implementors +/en-US/docs/ARIA/ARIA_Techniques /en-US/docs/Web/Accessibility/ARIA/Guides/Techniques +/en-US/docs/ARIA/ARIA_Techniques/Using_the_alert_role /en-US/docs/Web/Accessibility/ARIA/Reference/Roles/alert_role +/en-US/docs/ARIA/ARIA_Techniques/Using_the_alertdialog_role /en-US/docs/Web/Accessibility/ARIA/Reference/Roles/alertdialog_role +/en-US/docs/ARIA/ARIA_Techniques/Using_the_aria-activedescendant_attribute /en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-activedescendant +/en-US/docs/ARIA/ARIA_Techniques/Using_the_aria-labelledby_attribute /en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-labelledby +/en-US/docs/ARIA/ARIA_Techniques/Using_the_banner_role /en-US/docs/Web/Accessibility/ARIA/Reference/Roles/banner_role +/en-US/docs/ARIA/ARIA_Techniques/Using_the_button_role /en-US/docs/Web/Accessibility/ARIA/Reference/Roles/button_role +/en-US/docs/ARIA/ARIA_Techniques/Using_the_checkbox_role /en-US/docs/Web/Accessibility/ARIA/Reference/Roles/checkbox_role +/en-US/docs/ARIA/ARIA_Techniques/Using_the_dialog_role /en-US/docs/Web/Accessibility/ARIA/Reference/Roles/dialog_role +/en-US/docs/ARIA/ARIA_Techniques/Using_the_group_role /en-US/docs/Web/Accessibility/ARIA/Reference/Roles/group_role +/en-US/docs/ARIA/ARIA_Techniques/Using_the_listbox_role /en-US/docs/Web/Accessibility/ARIA/Reference/Roles/listbox_role +/en-US/docs/ARIA/ARIA_Techniques/Using_the_log_role /en-US/docs/Web/Accessibility/ARIA/Reference/Roles/log_role +/en-US/docs/ARIA/ARIA_Techniques/Using_the_presentation_role /en-US/docs/Web/Accessibility/ARIA/Reference/Roles/presentation_role +/en-US/docs/ARIA/ARIA_Techniques/Using_the_radio_role /en-US/docs/Web/Accessibility/ARIA/Reference/Roles/radio_role +/en-US/docs/ARIA/ARIA_Techniques/Using_the_status_role /en-US/docs/Web/Accessibility/ARIA/Reference/Roles/status_role +/en-US/docs/ARIA/ARIA_Techniques/Using_the_textbox_role /en-US/docs/Web/Accessibility/ARIA/Reference/Roles/textbox_role +/en-US/docs/ARIA/ARIA_Techniques/Using_the_toolbar_role /en-US/docs/Web/Accessibility/ARIA/Reference/Roles/toolbar_role /en-US/docs/ARIA/Accessible_Rich_Internet_Applications /en-US/docs/Web/Accessibility/ARIA /en-US/docs/ARIA/Basic_form_hints /en-US/docs/Web/Accessibility/ARIA -/en-US/docs/ARIA/How_to_file_ARIA-related_bugs /en-US/docs/Web/Accessibility/ARIA/How_to_file_ARIA-related_bugs -/en-US/docs/ARIA/Live_Regions /en-US/docs/Web/Accessibility/ARIA/ARIA_Live_Regions +/en-US/docs/ARIA/How_to_file_ARIA-related_bugs /en-US/docs/Web/Accessibility/ARIA/How_to/File_ARIA-related_bugs +/en-US/docs/ARIA/Live_Regions /en-US/docs/Web/Accessibility/ARIA/Guides/Live_regions /en-US/docs/ARIA/examples /en-US/docs/Web/Accessibility/ARIA /en-US/docs/ARIA/widgets /en-US/docs/Web/Accessibility/ARIA /en-US/docs/ARIA/widgets/overview /en-US/docs/Web/Accessibility/ARIA -/en-US/docs/ARIA_Screen_Reader_Implementors_Guide /en-US/docs/Web/Accessibility/ARIA/ARIA_Screen_Reader_Implementors_Guide -/en-US/docs/A_re-introduction_to_JavaScript /en-US/docs/Web/JavaScript/Language_overview +/en-US/docs/ARIA_Screen_Reader_Implementors_Guide /en-US/docs/Web/Accessibility/ARIA/Guides/Screen_Reader_Implementors +/en-US/docs/A_re-introduction_to_JavaScript /en-US/docs/Web/JavaScript/Guide/Language_overview /en-US/docs/About_JavaScript /en-US/docs/Web/JavaScript /en-US/docs/About_WOFF /en-US/docs/Web/CSS/CSS_fonts/WOFF /en-US/docs/About_the_Document_Object_Model /en-US/docs/Web/API/Document_Object_Model /en-US/docs/Accessibility /en-US/docs/Web/Accessibility /en-US/docs/Accessibility/ARIA /en-US/docs/Web/Accessibility/ARIA /en-US/docs/Accessibility/ARIA/ARIA_Examples /en-US/docs/Web/Accessibility/ARIA -/en-US/docs/Accessibility/ARIA/ARIA_Guides /en-US/docs/Web/Accessibility/ARIA/ARIA_Guides -/en-US/docs/Accessibility/ARIA/ARIA_Live_Regions /en-US/docs/Web/Accessibility/ARIA/ARIA_Live_Regions -/en-US/docs/Accessibility/ARIA/ARIA_Screen_Reader_Implementors_Guide /en-US/docs/Web/Accessibility/ARIA/ARIA_Screen_Reader_Implementors_Guide -/en-US/docs/Accessibility/ARIA/ARIA_Techniques /en-US/docs/Web/Accessibility/ARIA/ARIA_Techniques -/en-US/docs/Accessibility/ARIA/ARIA_Techniques/Using_the_alert_role /en-US/docs/Web/Accessibility/ARIA/Roles/alert_role -/en-US/docs/Accessibility/ARIA/ARIA_Techniques/Using_the_alertdialog_role /en-US/docs/Web/Accessibility/ARIA/Roles/alertdialog_role -/en-US/docs/Accessibility/ARIA/ARIA_Techniques/Using_the_aria-activedescendant_attribute /en-US/docs/Web/Accessibility/ARIA/Attributes/aria-activedescendant -/en-US/docs/Accessibility/ARIA/ARIA_Techniques/Using_the_aria-describedby_attribute /en-US/docs/Web/Accessibility/ARIA/Attributes/aria-describedby -/en-US/docs/Accessibility/ARIA/ARIA_Techniques/Using_the_aria-invalid_attribute /en-US/docs/Web/Accessibility/ARIA/Attributes/aria-invalid -/en-US/docs/Accessibility/ARIA/ARIA_Techniques/Using_the_aria-invalid_property /en-US/docs/Web/Accessibility/ARIA/Attributes/aria-invalid -/en-US/docs/Accessibility/ARIA/ARIA_Techniques/Using_the_aria-label_attribute /en-US/docs/Web/Accessibility/ARIA/Attributes/aria-label -/en-US/docs/Accessibility/ARIA/ARIA_Techniques/Using_the_aria-labelledby_attribute /en-US/docs/Web/Accessibility/ARIA/Attributes/aria-labelledby -/en-US/docs/Accessibility/ARIA/ARIA_Techniques/Using_the_aria-orientation_attribute /en-US/docs/Web/Accessibility/ARIA/Attributes/aria-orientation -/en-US/docs/Accessibility/ARIA/ARIA_Techniques/Using_the_aria-required_attribute /en-US/docs/Web/Accessibility/ARIA/Attributes/aria-required -/en-US/docs/Accessibility/ARIA/ARIA_Techniques/Using_the_aria-required_property /en-US/docs/Web/Accessibility/ARIA/Attributes/aria-required -/en-US/docs/Accessibility/ARIA/ARIA_Techniques/Using_the_aria-valuemax_attribute /en-US/docs/Web/Accessibility/ARIA/Attributes/aria-valuemax -/en-US/docs/Accessibility/ARIA/ARIA_Techniques/Using_the_aria-valuemin_attribute /en-US/docs/Web/Accessibility/ARIA/Attributes/aria-valuemin -/en-US/docs/Accessibility/ARIA/ARIA_Techniques/Using_the_aria-valuenow_attribute /en-US/docs/Web/Accessibility/ARIA/Attributes/aria-valuenow -/en-US/docs/Accessibility/ARIA/ARIA_Techniques/Using_the_aria-valuetext_attribute /en-US/docs/Web/Accessibility/ARIA/Attributes/aria-valuetext -/en-US/docs/Accessibility/ARIA/ARIA_Techniques/Using_the_article_role /en-US/docs/Web/Accessibility/ARIA/Roles/article_role -/en-US/docs/Accessibility/ARIA/ARIA_Techniques/Using_the_banner_role /en-US/docs/Web/Accessibility/ARIA/Roles/banner_role -/en-US/docs/Accessibility/ARIA/ARIA_Techniques/Using_the_button_role /en-US/docs/Web/Accessibility/ARIA/Roles/button_role -/en-US/docs/Accessibility/ARIA/ARIA_Techniques/Using_the_checkbox_role /en-US/docs/Web/Accessibility/ARIA/Roles/checkbox_role -/en-US/docs/Accessibility/ARIA/ARIA_Techniques/Using_the_dialog_role /en-US/docs/Web/Accessibility/ARIA/Roles/dialog_role -/en-US/docs/Accessibility/ARIA/ARIA_Techniques/Using_the_group_role /en-US/docs/Web/Accessibility/ARIA/Roles/group_role -/en-US/docs/Accessibility/ARIA/ARIA_Techniques/Using_the_listbox_role /en-US/docs/Web/Accessibility/ARIA/Roles/listbox_role -/en-US/docs/Accessibility/ARIA/ARIA_Techniques/Using_the_log_role /en-US/docs/Web/Accessibility/ARIA/Roles/log_role -/en-US/docs/Accessibility/ARIA/ARIA_Techniques/Using_the_presentation_role /en-US/docs/Web/Accessibility/ARIA/Roles/presentation_role -/en-US/docs/Accessibility/ARIA/ARIA_Techniques/Using_the_radio_role /en-US/docs/Web/Accessibility/ARIA/Roles/radio_role -/en-US/docs/Accessibility/ARIA/ARIA_Techniques/Using_the_status_role /en-US/docs/Web/Accessibility/ARIA/Roles/status_role -/en-US/docs/Accessibility/ARIA/ARIA_Techniques/Using_the_textbox_role /en-US/docs/Web/Accessibility/ARIA/Roles/textbox_role -/en-US/docs/Accessibility/ARIA/ARIA_Techniques/Using_the_toolbar_role /en-US/docs/Web/Accessibility/ARIA/Roles/toolbar_role +/en-US/docs/Accessibility/ARIA/ARIA_Guides /en-US/docs/Web/Accessibility/ARIA/Guides +/en-US/docs/Accessibility/ARIA/ARIA_Live_Regions /en-US/docs/Web/Accessibility/ARIA/Guides/Live_regions +/en-US/docs/Accessibility/ARIA/ARIA_Screen_Reader_Implementors_Guide /en-US/docs/Web/Accessibility/ARIA/Guides/Screen_Reader_Implementors +/en-US/docs/Accessibility/ARIA/ARIA_Techniques /en-US/docs/Web/Accessibility/ARIA/Guides/Techniques +/en-US/docs/Accessibility/ARIA/ARIA_Techniques/Using_the_alert_role /en-US/docs/Web/Accessibility/ARIA/Reference/Roles/alert_role +/en-US/docs/Accessibility/ARIA/ARIA_Techniques/Using_the_alertdialog_role /en-US/docs/Web/Accessibility/ARIA/Reference/Roles/alertdialog_role +/en-US/docs/Accessibility/ARIA/ARIA_Techniques/Using_the_aria-activedescendant_attribute /en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-activedescendant +/en-US/docs/Accessibility/ARIA/ARIA_Techniques/Using_the_aria-describedby_attribute /en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-describedby +/en-US/docs/Accessibility/ARIA/ARIA_Techniques/Using_the_aria-invalid_attribute /en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-invalid +/en-US/docs/Accessibility/ARIA/ARIA_Techniques/Using_the_aria-invalid_property /en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-invalid +/en-US/docs/Accessibility/ARIA/ARIA_Techniques/Using_the_aria-label_attribute /en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-label +/en-US/docs/Accessibility/ARIA/ARIA_Techniques/Using_the_aria-labelledby_attribute /en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-labelledby +/en-US/docs/Accessibility/ARIA/ARIA_Techniques/Using_the_aria-orientation_attribute /en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-orientation +/en-US/docs/Accessibility/ARIA/ARIA_Techniques/Using_the_aria-required_attribute /en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-required +/en-US/docs/Accessibility/ARIA/ARIA_Techniques/Using_the_aria-required_property /en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-required +/en-US/docs/Accessibility/ARIA/ARIA_Techniques/Using_the_aria-valuemax_attribute /en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-valuemax +/en-US/docs/Accessibility/ARIA/ARIA_Techniques/Using_the_aria-valuemin_attribute /en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-valuemin +/en-US/docs/Accessibility/ARIA/ARIA_Techniques/Using_the_aria-valuenow_attribute /en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-valuenow +/en-US/docs/Accessibility/ARIA/ARIA_Techniques/Using_the_aria-valuetext_attribute /en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-valuetext +/en-US/docs/Accessibility/ARIA/ARIA_Techniques/Using_the_article_role /en-US/docs/Web/Accessibility/ARIA/Reference/Roles/article_role +/en-US/docs/Accessibility/ARIA/ARIA_Techniques/Using_the_banner_role /en-US/docs/Web/Accessibility/ARIA/Reference/Roles/banner_role +/en-US/docs/Accessibility/ARIA/ARIA_Techniques/Using_the_button_role /en-US/docs/Web/Accessibility/ARIA/Reference/Roles/button_role +/en-US/docs/Accessibility/ARIA/ARIA_Techniques/Using_the_checkbox_role /en-US/docs/Web/Accessibility/ARIA/Reference/Roles/checkbox_role +/en-US/docs/Accessibility/ARIA/ARIA_Techniques/Using_the_dialog_role /en-US/docs/Web/Accessibility/ARIA/Reference/Roles/dialog_role +/en-US/docs/Accessibility/ARIA/ARIA_Techniques/Using_the_group_role /en-US/docs/Web/Accessibility/ARIA/Reference/Roles/group_role +/en-US/docs/Accessibility/ARIA/ARIA_Techniques/Using_the_listbox_role /en-US/docs/Web/Accessibility/ARIA/Reference/Roles/listbox_role +/en-US/docs/Accessibility/ARIA/ARIA_Techniques/Using_the_log_role /en-US/docs/Web/Accessibility/ARIA/Reference/Roles/log_role +/en-US/docs/Accessibility/ARIA/ARIA_Techniques/Using_the_presentation_role /en-US/docs/Web/Accessibility/ARIA/Reference/Roles/presentation_role +/en-US/docs/Accessibility/ARIA/ARIA_Techniques/Using_the_radio_role /en-US/docs/Web/Accessibility/ARIA/Reference/Roles/radio_role +/en-US/docs/Accessibility/ARIA/ARIA_Techniques/Using_the_status_role /en-US/docs/Web/Accessibility/ARIA/Reference/Roles/status_role +/en-US/docs/Accessibility/ARIA/ARIA_Techniques/Using_the_textbox_role /en-US/docs/Web/Accessibility/ARIA/Reference/Roles/textbox_role +/en-US/docs/Accessibility/ARIA/ARIA_Techniques/Using_the_toolbar_role /en-US/docs/Web/Accessibility/ARIA/Reference/Roles/toolbar_role /en-US/docs/Accessibility/ARIA/ARIA_Test_Cases /en-US/docs/Web/Accessibility/ARIA /en-US/docs/Accessibility/ARIA/Basic_form_hints /en-US/docs/Web/Accessibility/ARIA -/en-US/docs/Accessibility/ARIA/How_to_file_ARIA-related_bugs /en-US/docs/Web/Accessibility/ARIA/How_to_file_ARIA-related_bugs +/en-US/docs/Accessibility/ARIA/How_to_file_ARIA-related_bugs /en-US/docs/Web/Accessibility/ARIA/How_to/File_ARIA-related_bugs /en-US/docs/Accessibility/ARIA/Web_applications_and_ARIA_FAQ /en-US/docs/Web/Accessibility/ARIA /en-US/docs/Accessibility/ARIA/examples /en-US/docs/Web/Accessibility/ARIA /en-US/docs/Accessibility/ARIA/forms /en-US/docs/Web/Accessibility/ARIA /en-US/docs/Accessibility/ARIA/forms/Basic_form_hints /en-US/docs/Web/Accessibility/ARIA -/en-US/docs/Accessibility/ARIA/forms/Multipart_labels /en-US/docs/Web/Accessibility/ARIA/Multipart_labels +/en-US/docs/Accessibility/ARIA/forms/Multipart_labels /en-US/docs/Web/Accessibility/ARIA/Guides/Multipart_labels /en-US/docs/Accessibility/ARIA/forms/alerts /en-US/docs/Web/Accessibility/ARIA /en-US/docs/Accessibility/ARIA/widgets /en-US/docs/Web/Accessibility/ARIA /en-US/docs/Accessibility/ARIA/widgets/overview /en-US/docs/Web/Accessibility/ARIA -/en-US/docs/Accessibility/Accessible_dynamic_content /en-US/docs/Web/Accessibility/An_overview_of_accessible_web_applications_and_widgets +/en-US/docs/Accessibility/Accessible_dynamic_content /en-US/docs/Web/Accessibility/Guides/Accessible_web_applications_and_widgets /en-US/docs/Accessibility/Accessible_forms/alerts /en-US/docs/Web/Accessibility/ARIA -/en-US/docs/Accessibility/An_overview_of_accessible_web_applications_and_widgets /en-US/docs/Web/Accessibility/An_overview_of_accessible_web_applications_and_widgets +/en-US/docs/Accessibility/An_overview_of_accessible_web_applications_and_widgets /en-US/docs/Web/Accessibility/Guides/Accessible_web_applications_and_widgets /en-US/docs/Accessibility/Community /en-US/docs/Web/Accessibility /en-US/docs/Accessibility/FAQ /en-US/docs/Web/Accessibility /en-US/docs/Accessibility/HTML_To_MSAA /en-US/docs/Web/Accessibility /en-US/docs/Accessibility/Implementing_MSAA_server /en-US/docs/Web/Accessibility /en-US/docs/Accessibility/Implementing_an_MSAA_Server /en-US/docs/Web/Accessibility -/en-US/docs/Accessibility/Keyboard-navigable_JavaScript_widgets /en-US/docs/Web/Accessibility/Keyboard-navigable_JavaScript_widgets +/en-US/docs/Accessibility/Keyboard-navigable_JavaScript_widgets /en-US/docs/Web/Accessibility/Guides/Keyboard-navigable_JavaScript_widgets /en-US/docs/Accessibility/Web_Development /en-US/docs/Web/Accessibility /en-US/docs/Accessibility/Web_applications_and_ARIA_FAQ /en-US/docs/Web/Accessibility/ARIA /en-US/docs/Accessibility:Community /en-US/docs/Web/Accessibility /en-US/docs/Accessibility_FAQ /en-US/docs/Web/Accessibility -/en-US/docs/Accessibility_Information_for_Web_Authors /en-US/docs/Web/Accessibility/Information_for_Web_authors +/en-US/docs/Accessibility_Information_for_Web_Authors /en-US/docs/Web/Accessibility/Guides/Information_for_Web_authors /en-US/docs/Accessible_DHTML /en-US/docs/Web/Accessibility/ARIA /en-US/docs/Adapting_XUL_Applications_for_Firefox_1.5 /en-US/docs/Mozilla/Firefox/Releases/1.5 /en-US/docs/Adding_2D_content_to_a_WebGL_context /en-US/docs/Web/API/WebGL_API/Tutorial/Adding_2D_content_to_a_WebGL_context @@ -134,8 +134,8 @@ /en-US/docs/Addons/Add-on_guidelines https://extensionworkshop.com/documentation/publish/add-on-policies/ /en-US/docs/Addons/Working_with_AMO /en-US/docs/Mozilla/Add-ons /en-US/docs/Advanced_styling_for_HTML_forms /en-US/docs/Learn_web_development/Extensions/Forms/Advanced_form_styling -/en-US/docs/Alternative_style_sheets /en-US/docs/Web/HTML/Attributes/rel/alternate_stylesheet -/en-US/docs/An_Overview_of_Accessible_Web_Applications_and_Widgets /en-US/docs/Web/Accessibility/An_overview_of_accessible_web_applications_and_widgets +/en-US/docs/Alternative_style_sheets /en-US/docs/Web/HTML/Reference/Attributes/rel/alternate_stylesheet +/en-US/docs/An_Overview_of_Accessible_Web_Applications_and_Widgets /en-US/docs/Web/Accessibility/Guides/Accessible_web_applications_and_widgets /en-US/docs/An_overview_of_NSS_Internals https://firefox-source-docs.mozilla.org/security/nss/index.html /en-US/docs/Animation /en-US/docs/Web/API/Animation /en-US/docs/Animation/currentTime /en-US/docs/Web/API/Animation/currentTime @@ -147,7 +147,7 @@ /en-US/docs/Animation/reverse /en-US/docs/Web/API/Animation/reverse /en-US/docs/Animation/startTime /en-US/docs/Web/API/Animation/startTime /en-US/docs/AppLinks/WebConsoleHelp https://firefox-source-docs.mozilla.org/devtools-user/web_console/helpers/index.html -/en-US/docs/Applying_SVG_effects_to_HTML_content /en-US/docs/Web/SVG/Applying_SVG_effects_to_HTML_content +/en-US/docs/Applying_SVG_effects_to_HTML_content /en-US/docs/Web/SVG/Guides/Applying_SVG_effects_to_HTML_content /en-US/docs/Base64_encoding_and_decoding /en-US/docs/Glossary/Base64 /en-US/docs/BeforeInstallPromptEvent.prompt /en-US/docs/Web/API/BeforeInstallPromptEvent/prompt /en-US/docs/BiquadFilterNode /en-US/docs/Web/API/BiquadFilterNode @@ -159,11 +159,11 @@ /en-US/docs/BluetoothRemoteGATTService/getIncludedServices /en-US/docs/Web/API/BluetoothRemoteGATTService /en-US/docs/BluetoothRemoteGATTService/isPrimary /en-US/docs/Web/API/BluetoothRemoteGATTService/isPrimary /en-US/docs/BluetoothRemoteGATTService/uuid /en-US/docs/Web/API/BluetoothRemoteGATTService/uuid -/en-US/docs/Browser_detection_using_the_user_agent /en-US/docs/Web/HTTP/Browser_detection_using_the_user_agent +/en-US/docs/Browser_detection_using_the_user_agent /en-US/docs/Web/HTTP/Guides/Browser_detection_using_the_user_agent /en-US/docs/Bugzilla_(external) https://bugzilla.mozilla.org/enter_bug.cgi?format=guided /en-US/docs/Building_an_Extension /en-US/docs/Mozilla/Add-ons /en-US/docs/CER_temp /en-US/docs/Web/API/Document -/en-US/docs/CORS_Enabled_Image /en-US/docs/Web/HTML/CORS_enabled_image +/en-US/docs/CORS_Enabled_Image /en-US/docs/Web/HTML/How_to/CORS_enabled_image /en-US/docs/CSS /en-US/docs/Web/CSS /en-US/docs/CSS-2_Quick_Reference /en-US/docs/Web/CSS /en-US/docs/CSS-2_Quick_Reference/All_in_a_page /en-US/docs/Web/CSS/Reference @@ -177,8 +177,8 @@ /en-US/docs/CSS-2_Quick_Reference/Units /en-US/docs/Web/CSS/length /en-US/docs/CSS-2_Quick_Reference/User_interface /en-US/docs/Web/CSS/Reference /en-US/docs/CSS-2_Quick_Reference/Visual_effects /en-US/docs/Web/CSS/Reference -/en-US/docs/CSS-2_Quick_Reference/Visual_formatting_details /en-US/docs/Web/CSS/Visual_formatting_model -/en-US/docs/CSS-2_Quick_Reference/Visual_formatting_model /en-US/docs/Web/CSS/Visual_formatting_model +/en-US/docs/CSS-2_Quick_Reference/Visual_formatting_details /en-US/docs/Web/CSS/CSS_display/Visual_formatting_model +/en-US/docs/CSS-2_Quick_Reference/Visual_formatting_model /en-US/docs/Web/CSS/CSS_display/Visual_formatting_model /en-US/docs/CSS-2_Quick_Reference:All_in_a_page /en-US/docs/Web/CSS/Reference /en-US/docs/CSS-2_Quick_Reference:Box_model /en-US/docs/Web/CSS/CSS_box_model/Introduction_to_the_CSS_box_model /en-US/docs/CSS-2_Quick_Reference:Color_and_Background /en-US/docs/Web/CSS/Reference @@ -190,8 +190,8 @@ /en-US/docs/CSS-2_Quick_Reference:Units /en-US/docs/Web/CSS/length /en-US/docs/CSS-2_Quick_Reference:User_interface /en-US/docs/Web/CSS/Reference /en-US/docs/CSS-2_Quick_Reference:Visual_effects /en-US/docs/Web/CSS/Reference -/en-US/docs/CSS-2_Quick_Reference:Visual_formatting_details /en-US/docs/Web/CSS/Visual_formatting_model -/en-US/docs/CSS-2_Quick_Reference:Visual_formatting_model /en-US/docs/Web/CSS/Visual_formatting_model +/en-US/docs/CSS-2_Quick_Reference:Visual_formatting_details /en-US/docs/Web/CSS/CSS_display/Visual_formatting_model +/en-US/docs/CSS-2_Quick_Reference:Visual_formatting_model /en-US/docs/Web/CSS/CSS_display/Visual_formatting_model /en-US/docs/CSS-redirect-1 /en-US/docs/Web/CSS /en-US/docs/CSS-redirect-2 /en-US/docs/Web/CSS /en-US/docs/CSS/-epub-caption-side /en-US/docs/Web/CSS/caption-side @@ -452,7 +452,7 @@ /en-US/docs/CSS/@supports /en-US/docs/Web/CSS/@supports /en-US/docs/CSS/Adjacent_sibling_selectors /en-US/docs/Web/CSS/Next-sibling_combinator /en-US/docs/CSS/Alias /en-US/docs/Web/CSS/cursor -/en-US/docs/CSS/Alternative_style_sheets /en-US/docs/Web/HTML/Attributes/rel/alternate_stylesheet +/en-US/docs/CSS/Alternative_style_sheets /en-US/docs/Web/HTML/Reference/Attributes/rel/alternate_stylesheet /en-US/docs/CSS/At-rule /en-US/docs/Web/CSS/CSS_syntax/At-rule /en-US/docs/CSS/Attribute_selectors /en-US/docs/Web/CSS/Attribute_selectors /en-US/docs/CSS/Aural /en-US/docs/Web/CSS/@media/aural @@ -495,8 +495,8 @@ /en-US/docs/CSS/Getting_Started/JavaScript /en-US/docs/Learn_web_development/Core/Scripting/DOM_scripting /en-US/docs/CSS/Getting_Started/Layout /en-US/docs/Learn_web_development/Core/CSS_layout /en-US/docs/CSS/Getting_Started/Lists /en-US/docs/Learn_web_development/Core/Text_styling/Styling_lists -/en-US/docs/CSS/Getting_Started/SVG_and_CSS /en-US/docs/Web/SVG/Tutorial/SVG_and_CSS -/en-US/docs/CSS/Getting_Started/SVG_graphics /en-US/docs/Web/SVG/Tutorial/SVG_and_CSS +/en-US/docs/CSS/Getting_Started/SVG_and_CSS /en-US/docs/Web/SVG/Tutorials/SVG_from_scratch/SVG_and_CSS +/en-US/docs/CSS/Getting_Started/SVG_graphics /en-US/docs/Web/SVG/Tutorials/SVG_from_scratch/SVG_and_CSS /en-US/docs/CSS/Getting_Started/Selectors /en-US/docs/Learn_web_development/Core/Styling_basics/Basic_selectors /en-US/docs/CSS/Getting_Started/Tables /en-US/docs/Learn_web_development/Core/Styling_basics/Tables /en-US/docs/CSS/Getting_Started/Text_styles /en-US/docs/Learn_web_development/Core/Text_styling/Fundamentals @@ -506,7 +506,7 @@ /en-US/docs/CSS/Getting_Started/Why_use_CSS? /en-US/docs/Learn_web_development/Core/Styling_basics/What_is_CSS /en-US/docs/CSS/ID_selectors /en-US/docs/Web/CSS/ID_selectors /en-US/docs/CSS/Interactive /en-US/docs/Web/CSS/@media -/en-US/docs/CSS/Layout_mode /en-US/docs/Web/CSS/Layout_mode +/en-US/docs/CSS/Layout_mode /en-US/docs/Glossary/Layout_mode /en-US/docs/CSS/List_of_Proprietary_CSS_Features /en-US/docs/Web/CSS/Reference /en-US/docs/CSS/Media/Bitmap /en-US/docs/Web/CSS/@media /en-US/docs/CSS/Media/TV /en-US/docs/Web/CSS/@media @@ -516,10 +516,10 @@ /en-US/docs/CSS/Multiple_backgrounds /en-US/docs/Web/CSS/CSS_backgrounds_and_borders/Using_multiple_backgrounds /en-US/docs/CSS/Other_Resources /en-US/docs/Web/CSS /en-US/docs/CSS/Paged_Media /en-US/docs/Web/CSS/CSS_paged_media -/en-US/docs/CSS/Privacy_and_the_:visited_selector /en-US/docs/Web/CSS/Privacy_and_the_:visited_selector +/en-US/docs/CSS/Privacy_and_the_:visited_selector /en-US/docs/Web/CSS/CSS_selectors/Privacy_and_the_visited_selector /en-US/docs/CSS/Pseudo-classes /en-US/docs/Web/CSS/Pseudo-classes /en-US/docs/CSS/Pseudo-elements /en-US/docs/Web/CSS/Pseudo-elements -/en-US/docs/CSS/Replaced_element /en-US/docs/Web/CSS/Replaced_element +/en-US/docs/CSS/Replaced_element /en-US/docs/Web/CSS/CSS_images/Replaced_element_properties /en-US/docs/CSS/Scaling_background_images /en-US/docs/Web/CSS/CSS_backgrounds_and_borders/Resizing_background_images /en-US/docs/CSS/Scaling_of_SVG_backgrounds /en-US/docs/Web/CSS/CSS_backgrounds_and_borders/Scaling_of_SVG_backgrounds /en-US/docs/CSS/Shorthand_properties /en-US/docs/Web/CSS/CSS_cascade/Shorthand_properties @@ -536,21 +536,21 @@ /en-US/docs/CSS/Tutorials/Using_CSS_transitions /en-US/docs/Web/CSS/CSS_transitions/Using_CSS_transitions /en-US/docs/CSS/Type_selectors /en-US/docs/Web/CSS/Type_selectors /en-US/docs/CSS/Understanding_CSS_z-index /en-US/docs/Web/CSS/CSS_positioned_layout/Understanding_z-index -/en-US/docs/CSS/Understanding_CSS_z-index/Adding_z-index /en-US/docs/Web/CSS/CSS_positioned_layout/Understanding_z-index/Using_z-index -/en-US/docs/CSS/Understanding_CSS_z-index/Stacking_and_float /en-US/docs/Web/CSS/CSS_positioned_layout/Understanding_z-index/Stacking_floating_elements -/en-US/docs/CSS/Understanding_CSS_z-index/Stacking_context_example_1 /en-US/docs/Web/CSS/CSS_positioned_layout/Understanding_z-index/Stacking_context_example_1 -/en-US/docs/CSS/Understanding_CSS_z-index/Stacking_context_example_2 /en-US/docs/Web/CSS/CSS_positioned_layout/Understanding_z-index/Stacking_context_example_2 -/en-US/docs/CSS/Understanding_CSS_z-index/Stacking_context_example_3 /en-US/docs/Web/CSS/CSS_positioned_layout/Understanding_z-index/Stacking_context_example_3 -/en-US/docs/CSS/Understanding_CSS_z-index/Stacking_without_z-index /en-US/docs/Web/CSS/CSS_positioned_layout/Understanding_z-index/Stacking_without_z-index -/en-US/docs/CSS/Understanding_CSS_z-index/The_stacking_context /en-US/docs/Web/CSS/CSS_positioned_layout/Understanding_z-index/Stacking_context +/en-US/docs/CSS/Understanding_CSS_z-index/Adding_z-index /en-US/docs/Web/CSS/CSS_positioned_layout/Using_z-index +/en-US/docs/CSS/Understanding_CSS_z-index/Stacking_and_float /en-US/docs/Web/CSS/CSS_positioned_layout/Stacking_floating_elements +/en-US/docs/CSS/Understanding_CSS_z-index/Stacking_context_example_1 /en-US/docs/Web/CSS/CSS_positioned_layout/Stacking_context/Stacking_context_example_1 +/en-US/docs/CSS/Understanding_CSS_z-index/Stacking_context_example_2 /en-US/docs/Web/CSS/CSS_positioned_layout/Stacking_context/Stacking_context_example_2 +/en-US/docs/CSS/Understanding_CSS_z-index/Stacking_context_example_3 /en-US/docs/Web/CSS/CSS_positioned_layout/Stacking_context/Stacking_context_example_3 +/en-US/docs/CSS/Understanding_CSS_z-index/Stacking_without_z-index /en-US/docs/Web/CSS/CSS_positioned_layout/Stacking_without_z-index +/en-US/docs/CSS/Understanding_CSS_z-index/The_stacking_context /en-US/docs/Web/CSS/CSS_positioned_layout/Stacking_context /en-US/docs/CSS/Understanding_z-index /en-US/docs/Web/CSS/CSS_positioned_layout/Understanding_z-index -/en-US/docs/CSS/Understanding_z-index/Adding_z-index /en-US/docs/Web/CSS/CSS_positioned_layout/Understanding_z-index/Using_z-index -/en-US/docs/CSS/Understanding_z-index/Stacking_and_float /en-US/docs/Web/CSS/CSS_positioned_layout/Understanding_z-index/Stacking_floating_elements -/en-US/docs/CSS/Understanding_z-index/Stacking_context_example_1 /en-US/docs/Web/CSS/CSS_positioned_layout/Understanding_z-index/Stacking_context_example_1 -/en-US/docs/CSS/Understanding_z-index/Stacking_context_example_2 /en-US/docs/Web/CSS/CSS_positioned_layout/Understanding_z-index/Stacking_context_example_2 -/en-US/docs/CSS/Understanding_z-index/Stacking_context_example_3 /en-US/docs/Web/CSS/CSS_positioned_layout/Understanding_z-index/Stacking_context_example_3 -/en-US/docs/CSS/Understanding_z-index/Stacking_without_z-index /en-US/docs/Web/CSS/CSS_positioned_layout/Understanding_z-index/Stacking_without_z-index -/en-US/docs/CSS/Understanding_z-index/The_stacking_context /en-US/docs/Web/CSS/CSS_positioned_layout/Understanding_z-index/Stacking_context +/en-US/docs/CSS/Understanding_z-index/Adding_z-index /en-US/docs/Web/CSS/CSS_positioned_layout/Using_z-index +/en-US/docs/CSS/Understanding_z-index/Stacking_and_float /en-US/docs/Web/CSS/CSS_positioned_layout/Stacking_floating_elements +/en-US/docs/CSS/Understanding_z-index/Stacking_context_example_1 /en-US/docs/Web/CSS/CSS_positioned_layout/Stacking_context/Stacking_context_example_1 +/en-US/docs/CSS/Understanding_z-index/Stacking_context_example_2 /en-US/docs/Web/CSS/CSS_positioned_layout/Stacking_context/Stacking_context_example_2 +/en-US/docs/CSS/Understanding_z-index/Stacking_context_example_3 /en-US/docs/Web/CSS/CSS_positioned_layout/Stacking_context/Stacking_context_example_3 +/en-US/docs/CSS/Understanding_z-index/Stacking_without_z-index /en-US/docs/Web/CSS/CSS_positioned_layout/Stacking_without_z-index +/en-US/docs/CSS/Understanding_z-index/The_stacking_context /en-US/docs/Web/CSS/CSS_positioned_layout/Stacking_context /en-US/docs/CSS/Universal_selectors /en-US/docs/Web/CSS/Universal_selectors /en-US/docs/CSS/Using_CSS_Columns /en-US/docs/Web/CSS/CSS_multicol_layout/Using_multicol_layouts /en-US/docs/CSS/Using_CSS_animations /en-US/docs/Web/CSS/CSS_animations/Using_CSS_animations @@ -565,8 +565,8 @@ /en-US/docs/CSS/Using_media_queries_from_code /en-US/docs/Web/CSS/CSS_media_queries/Testing_media_queries /en-US/docs/CSS/Using_the_CSS_multi-column_layout /en-US/docs/Web/CSS/CSS_multicol_layout/Using_multicol_layouts /en-US/docs/CSS/Value_definition_syntax /en-US/docs/Web/CSS/CSS_Values_and_Units/Value_definition_syntax -/en-US/docs/CSS/Visual_formatting_model /en-US/docs/Web/CSS/Visual_formatting_model -/en-US/docs/CSS/actual_value /en-US/docs/Web/CSS/CSS_cascade/actual_value +/en-US/docs/CSS/Visual_formatting_model /en-US/docs/Web/CSS/CSS_display/Visual_formatting_model +/en-US/docs/CSS/actual_value /en-US/docs/Web/CSS/CSS_cascade/Value_processing#actual_value /en-US/docs/CSS/align-content /en-US/docs/Web/CSS/align-content /en-US/docs/CSS/align-items /en-US/docs/Web/CSS/align-items /en-US/docs/CSS/align-self /en-US/docs/Web/CSS/align-self @@ -650,8 +650,8 @@ /en-US/docs/CSS/clip /en-US/docs/Web/CSS/clip /en-US/docs/CSS/clip-path /en-US/docs/Web/CSS/clip-path /en-US/docs/CSS/color /en-US/docs/Web/CSS/color -/en-US/docs/CSS/color-interpolation /en-US/docs/Web/SVG/Attribute/color-interpolation -/en-US/docs/CSS/color-interpolation-filters /en-US/docs/Web/SVG/Attribute/color-interpolation-filters +/en-US/docs/CSS/color-interpolation /en-US/docs/Web/SVG/Reference/Attribute/color-interpolation +/en-US/docs/CSS/color-interpolation-filters /en-US/docs/Web/SVG/Reference/Attribute/color-interpolation-filters /en-US/docs/CSS/color_value /en-US/docs/Web/CSS/color_value /en-US/docs/CSS/column-count /en-US/docs/Web/CSS/column-count /en-US/docs/CSS/column-fill /en-US/docs/Web/CSS/column-fill @@ -663,7 +663,7 @@ /en-US/docs/CSS/column-span /en-US/docs/Web/CSS/column-span /en-US/docs/CSS/column-width /en-US/docs/Web/CSS/column-width /en-US/docs/CSS/columns /en-US/docs/Web/CSS/columns -/en-US/docs/CSS/computed_value /en-US/docs/Web/CSS/CSS_cascade/computed_value +/en-US/docs/CSS/computed_value /en-US/docs/Web/CSS/CSS_cascade/Value_processing#computed_value /en-US/docs/CSS/content /en-US/docs/Web/CSS/content /en-US/docs/CSS/counter /en-US/docs/Web/CSS/counter /en-US/docs/CSS/counter-increment /en-US/docs/Web/CSS/counter-increment @@ -675,7 +675,7 @@ /en-US/docs/CSS/display /en-US/docs/Web/CSS/display /en-US/docs/CSS/document /en-US/docs/Web/CSS/@document /en-US/docs/CSS/document/@-moz-document /en-US/docs/Web/CSS/@document -/en-US/docs/CSS/dominant-baseline /en-US/docs/Web/SVG/Attribute/dominant-baseline +/en-US/docs/CSS/dominant-baseline /en-US/docs/Web/SVG/Reference/Attribute/dominant-baseline /en-US/docs/CSS/element /en-US/docs/Web/CSS/element /en-US/docs/CSS/empty-cells /en-US/docs/Web/CSS/empty-cells /en-US/docs/CSS/filter /en-US/docs/Web/CSS/filter @@ -716,7 +716,7 @@ /en-US/docs/CSS/inheritance /en-US/docs/Web/CSS/CSS_cascade/Inheritance /en-US/docs/CSS/inherited_and_non-inherited_properties /en-US/docs/Web/CSS/CSS_cascade/Inheritance /en-US/docs/CSS/initial /en-US/docs/Web/CSS/initial -/en-US/docs/CSS/initial_value /en-US/docs/Web/CSS/CSS_cascade/initial_value +/en-US/docs/CSS/initial_value /en-US/docs/Web/CSS/CSS_cascade/Value_processing#initial_value /en-US/docs/CSS/integer /en-US/docs/Web/CSS/integer /en-US/docs/CSS/justify-content /en-US/docs/Web/CSS/justify-content /en-US/docs/CSS/left /en-US/docs/Web/CSS/left @@ -734,9 +734,9 @@ /en-US/docs/CSS/margin-right /en-US/docs/Web/CSS/margin-right /en-US/docs/CSS/margin-top /en-US/docs/Web/CSS/margin-top /en-US/docs/CSS/margin_collapsing /en-US/docs/Web/CSS/CSS_box_model/Mastering_margin_collapsing -/en-US/docs/CSS/marker-end /en-US/docs/Web/SVG/Attribute/marker-end -/en-US/docs/CSS/marker-mid /en-US/docs/Web/SVG/Attribute/marker-mid -/en-US/docs/CSS/marker-start /en-US/docs/Web/SVG/Attribute/marker-start +/en-US/docs/CSS/marker-end /en-US/docs/Web/SVG/Reference/Attribute/marker-end +/en-US/docs/CSS/marker-mid /en-US/docs/Web/SVG/Reference/Attribute/marker-mid +/en-US/docs/CSS/marker-start /en-US/docs/Web/SVG/Reference/Attribute/marker-start /en-US/docs/CSS/mask /en-US/docs/Web/CSS/mask /en-US/docs/CSS/max-height /en-US/docs/Web/CSS/max-height /en-US/docs/CSS/max-width /en-US/docs/Web/CSS/max-width @@ -785,25 +785,25 @@ /en-US/docs/CSS/right /en-US/docs/Web/CSS/right /en-US/docs/CSS/scroll /en-US/docs/Web/CSS/overflow /en-US/docs/CSS/shape /en-US/docs/Web/CSS/shape -/en-US/docs/CSS/shape-rendering /en-US/docs/Web/SVG/Attribute/shape-rendering -/en-US/docs/CSS/specified_value /en-US/docs/Web/CSS/CSS_cascade/specified_value +/en-US/docs/CSS/shape-rendering /en-US/docs/Web/SVG/Reference/Attribute/shape-rendering +/en-US/docs/CSS/specified_value /en-US/docs/Web/CSS/CSS_cascade/Value_processing#specified_value /en-US/docs/CSS/static /en-US/docs/Web/CSS/position -/en-US/docs/CSS/stop-color /en-US/docs/Web/SVG/Attribute/stop-color -/en-US/docs/CSS/stop-opacity /en-US/docs/Web/SVG/Attribute/stop-opacity +/en-US/docs/CSS/stop-color /en-US/docs/Web/SVG/Reference/Attribute/stop-color +/en-US/docs/CSS/stop-opacity /en-US/docs/Web/SVG/Reference/Attribute/stop-opacity /en-US/docs/CSS/string /en-US/docs/Web/CSS/string -/en-US/docs/CSS/stroke /en-US/docs/Web/SVG/Attribute/stroke -/en-US/docs/CSS/stroke-dasharray /en-US/docs/Web/SVG/Attribute/stroke-dasharray -/en-US/docs/CSS/stroke-dashoffset /en-US/docs/Web/SVG/Attribute/stroke-dashoffset -/en-US/docs/CSS/stroke-linecap /en-US/docs/Web/SVG/Attribute/stroke-linecap -/en-US/docs/CSS/stroke-linejoin /en-US/docs/Web/SVG/Attribute/stroke-linejoin -/en-US/docs/CSS/stroke-miterlimit /en-US/docs/Web/SVG/Attribute/stroke-miterlimit -/en-US/docs/CSS/stroke-opacity /en-US/docs/Web/SVG/Attribute/stroke-opacity -/en-US/docs/CSS/stroke-width /en-US/docs/Web/SVG/Attribute/stroke-width +/en-US/docs/CSS/stroke /en-US/docs/Web/SVG/Reference/Attribute/stroke +/en-US/docs/CSS/stroke-dasharray /en-US/docs/Web/SVG/Reference/Attribute/stroke-dasharray +/en-US/docs/CSS/stroke-dashoffset /en-US/docs/Web/SVG/Reference/Attribute/stroke-dashoffset +/en-US/docs/CSS/stroke-linecap /en-US/docs/Web/SVG/Reference/Attribute/stroke-linecap +/en-US/docs/CSS/stroke-linejoin /en-US/docs/Web/SVG/Reference/Attribute/stroke-linejoin +/en-US/docs/CSS/stroke-miterlimit /en-US/docs/Web/SVG/Reference/Attribute/stroke-miterlimit +/en-US/docs/CSS/stroke-opacity /en-US/docs/Web/SVG/Reference/Attribute/stroke-opacity +/en-US/docs/CSS/stroke-width /en-US/docs/Web/SVG/Reference/Attribute/stroke-width /en-US/docs/CSS/tab-size /en-US/docs/Web/CSS/tab-size /en-US/docs/CSS/table-layout /en-US/docs/Web/CSS/table-layout /en-US/docs/CSS/text-align /en-US/docs/Web/CSS/text-align /en-US/docs/CSS/text-align-last /en-US/docs/Web/CSS/text-align-last -/en-US/docs/CSS/text-anchor /en-US/docs/Web/SVG/Attribute/text-anchor +/en-US/docs/CSS/text-anchor /en-US/docs/Web/SVG/Reference/Attribute/text-anchor /en-US/docs/CSS/text-decoration /en-US/docs/Web/CSS/text-decoration /en-US/docs/CSS/text-decoration-color /en-US/docs/Web/CSS/text-decoration-color /en-US/docs/CSS/text-decoration-line /en-US/docs/Web/CSS/text-decoration-line @@ -833,7 +833,7 @@ /en-US/docs/CSS/transition-timing-function /en-US/docs/Web/CSS/transition-timing-function /en-US/docs/CSS/unicode-bidi /en-US/docs/Web/CSS/unicode-bidi /en-US/docs/CSS/uri /en-US/docs/Web/CSS/url_value -/en-US/docs/CSS/used_value /en-US/docs/Web/CSS/CSS_cascade/used_value +/en-US/docs/CSS/used_value /en-US/docs/Web/CSS/CSS_cascade/Value_processing#used_value /en-US/docs/CSS/user-ident /en-US/docs/Web/CSS/custom-ident /en-US/docs/CSS/user-select /en-US/docs/Web/CSS/user-select /en-US/docs/CSS/vertical-align /en-US/docs/Web/CSS/vertical-align @@ -947,7 +947,7 @@ /en-US/docs/CSS:Getting_Started:JavaScript /en-US/docs/Learn_web_development/Core/Scripting/DOM_scripting /en-US/docs/CSS:Getting_Started:Layout /en-US/docs/Learn_web_development/Core/CSS_layout /en-US/docs/CSS:Getting_Started:Lists /en-US/docs/Learn_web_development/Core/Text_styling/Styling_lists -/en-US/docs/CSS:Getting_Started:SVG_graphics /en-US/docs/Web/SVG/Tutorial/SVG_and_CSS +/en-US/docs/CSS:Getting_Started:SVG_graphics /en-US/docs/Web/SVG/Tutorials/SVG_from_scratch/SVG_and_CSS /en-US/docs/CSS:Getting_Started:Selectors /en-US/docs/Learn_web_development/Core/Styling_basics/Basic_selectors /en-US/docs/CSS:Getting_Started:Tables /en-US/docs/Learn_web_development/Core/Styling_basics/Tables /en-US/docs/CSS:Getting_Started:Text_styles /en-US/docs/Learn_web_development/Core/Text_styling/Fundamentals @@ -997,7 +997,7 @@ /en-US/docs/CSS:clip /en-US/docs/Web/CSS/clip /en-US/docs/CSS:color /en-US/docs/Web/CSS/color /en-US/docs/CSS:color_value /en-US/docs/Web/CSS/color_value -/en-US/docs/CSS:computed_value /en-US/docs/Web/CSS/CSS_cascade/computed_value +/en-US/docs/CSS:computed_value /en-US/docs/Web/CSS/CSS_cascade/Value_processing#computed_value /en-US/docs/CSS:content /en-US/docs/Web/CSS/content /en-US/docs/CSS:counter /en-US/docs/Web/CSS/counter /en-US/docs/CSS:counter-increment /en-US/docs/Web/CSS/counter-increment @@ -1022,7 +1022,7 @@ /en-US/docs/CSS:inheritance /en-US/docs/Web/CSS/CSS_cascade/Inheritance /en-US/docs/CSS:inherited_and_non-inherited_properties /en-US/docs/Web/CSS/CSS_cascade/Inheritance /en-US/docs/CSS:initial /en-US/docs/Web/CSS/initial -/en-US/docs/CSS:initial_value /en-US/docs/Web/CSS/CSS_cascade/initial_value +/en-US/docs/CSS:initial_value /en-US/docs/Web/CSS/CSS_cascade/Value_processing#initial_value /en-US/docs/CSS:integer /en-US/docs/Web/CSS/integer /en-US/docs/CSS:left /en-US/docs/Web/CSS/left /en-US/docs/CSS:length /en-US/docs/Web/CSS/length @@ -1111,17 +1111,17 @@ /en-US/docs/Configuring_servers_for_Ogg_media /en-US/docs/Web/Media/Guides/Formats/Configuring_servers_for_Ogg_media /en-US/docs/Consistent_List_Indentation /en-US/docs/Web/CSS/CSS_lists/Consistent_list_indentation /en-US/docs/Const_statement /en-US/docs/Web/JavaScript/Reference/Statements/const -/en-US/docs/Content_negotiation /en-US/docs/Web/HTTP/Content_negotiation -/en-US/docs/Controlling_DNS_prefetching /en-US/docs/Web/HTTP/Headers/X-DNS-Prefetch-Control -/en-US/docs/Controlling_spell_checking_in_HTML /en-US/docs/Web/HTML/Global_attributes/spellcheck -/en-US/docs/Controlling_spell_checking_in_HTML_forms /en-US/docs/Web/HTML/Global_attributes/spellcheck +/en-US/docs/Content_negotiation /en-US/docs/Web/HTTP/Guides/Content_negotiation +/en-US/docs/Controlling_DNS_prefetching /en-US/docs/Web/HTTP/Reference/Headers/X-DNS-Prefetch-Control +/en-US/docs/Controlling_spell_checking_in_HTML /en-US/docs/Web/HTML/Reference/Global_attributes/spellcheck +/en-US/docs/Controlling_spell_checking_in_HTML_forms /en-US/docs/Web/HTML/Reference/Global_attributes/spellcheck /en-US/docs/Creating_OpenSearch_plugins_for_Firefox /en-US/docs/Web/XML/Guides/OpenSearch /en-US/docs/Creating_and_triggering_custom_events /en-US/docs/Web/Events/Creating_and_triggering_events /en-US/docs/CredentialsContainer.preventSilentAccess() /en-US/docs/Web/API/CredentialsContainer/preventSilentAccess /en-US/docs/Cryptanalysis /en-US/docs/Glossary/Cryptanalysis -/en-US/docs/Cryptographic_hash_function /en-US/docs/Glossary/Cryptographic_hash_function +/en-US/docs/Cryptographic_hash_function /en-US/docs/Glossary/Hash_function /en-US/docs/CustomElements /en-US/docs/Web/API/Web_components/Using_custom_elements -/en-US/docs/DASH_Adaptive_Streaming_for_HTML_5_Video /en-US/docs/Web/Media/Guides/DASH_Adaptive_Streaming_for_HTML_5_Video +/en-US/docs/DASH_Adaptive_Streaming_for_HTML_5_Video /en-US/docs/Web/API/Media_Source_Extensions_API/DASH_Adaptive_Streaming /en-US/docs/DOM /en-US/docs/Web/API/Document_Object_Model /en-US/docs/DOM/About_the_Document_Object_Model /en-US/docs/Web/API/Document_Object_Model /en-US/docs/DOM/AbstractView /en-US/docs/Web/API/Document/defaultView @@ -1586,23 +1586,23 @@ /en-US/docs/DOM/SVGAnimationElement /en-US/docs/Web/API/SVGAnimationElement /en-US/docs/DOM/SVGCircleElement /en-US/docs/Web/API/SVGCircleElement /en-US/docs/DOM/SVGClipPathElement /en-US/docs/Web/API/SVGClipPathElement -/en-US/docs/DOM/SVGCursorElement /en-US/docs/Web/API/SVGCursorElement +/en-US/docs/DOM/SVGCursorElement /en-US/docs/Web/API/SVGElement /en-US/docs/DOM/SVGDefsElement /en-US/docs/Web/API/SVGDefsElement /en-US/docs/DOM/SVGDescElement /en-US/docs/Web/API/SVGDescElement /en-US/docs/DOM/SVGElement /en-US/docs/Web/API/SVGElement /en-US/docs/DOM/SVGEllipseElement /en-US/docs/Web/API/SVGEllipseElement /en-US/docs/DOM/SVGFilterElement /en-US/docs/Web/API/SVGFilterElement -/en-US/docs/DOM/SVGFontElement /en-US/docs/Web/API/SVGFontElement -/en-US/docs/DOM/SVGFontFaceElement /en-US/docs/Web/API/SVGFontFaceElement -/en-US/docs/DOM/SVGFontFaceFormatElement /en-US/docs/Web/API/SVGFontFaceFormatElement -/en-US/docs/DOM/SVGFontFaceNameElement /en-US/docs/Web/API/SVGFontFaceNameElement -/en-US/docs/DOM/SVGFontFaceSrcElement /en-US/docs/Web/API/SVGFontFaceSrcElement -/en-US/docs/DOM/SVGFontFaceUriElement /en-US/docs/Web/API/SVGFontFaceUriElement +/en-US/docs/DOM/SVGFontElement /en-US/docs/Web/API/SVGElement +/en-US/docs/DOM/SVGFontFaceElement /en-US/docs/Web/API/SVGElement +/en-US/docs/DOM/SVGFontFaceFormatElement /en-US/docs/Web/API/SVGElement +/en-US/docs/DOM/SVGFontFaceNameElement /en-US/docs/Web/API/SVGElement +/en-US/docs/DOM/SVGFontFaceSrcElement /en-US/docs/Web/API/SVGElement +/en-US/docs/DOM/SVGFontFaceUriElement /en-US/docs/Web/API/SVGElement /en-US/docs/DOM/SVGForeignObjectElement /en-US/docs/Web/API/SVGForeignObjectElement /en-US/docs/DOM/SVGGElement /en-US/docs/Web/API/SVGGElement -/en-US/docs/DOM/SVGGlyphElement /en-US/docs/Web/API/SVGGlyphElement +/en-US/docs/DOM/SVGGlyphElement /en-US/docs/Web/API/SVGElement /en-US/docs/DOM/SVGGradientElement /en-US/docs/Web/API/SVGGradientElement -/en-US/docs/DOM/SVGHKernElement /en-US/docs/Web/API/SVGHKernElement +/en-US/docs/DOM/SVGHKernElement /en-US/docs/Web/API/SVGElement /en-US/docs/DOM/SVGImageElement /en-US/docs/Web/API/SVGImageElement /en-US/docs/DOM/SVGLength /en-US/docs/Web/API/SVGLength /en-US/docs/DOM/SVGLengthList /en-US/docs/Web/API/SVGLengthList @@ -1611,7 +1611,7 @@ /en-US/docs/DOM/SVGMPathElement /en-US/docs/Web/API/SVGMPathElement /en-US/docs/DOM/SVGMaskElement /en-US/docs/Web/API/SVGMaskElement /en-US/docs/DOM/SVGMatrix /en-US/docs/Web/API/DOMMatrix -/en-US/docs/DOM/SVGMissingGlyphElement /en-US/docs/Web/API/SVGMissingGlyphElement +/en-US/docs/DOM/SVGMissingGlyphElement /en-US/docs/Web/API/SVGElement /en-US/docs/DOM/SVGNumber /en-US/docs/Web/API/SVGNumber /en-US/docs/DOM/SVGNumberList /en-US/docs/Web/API/SVGNumberList /en-US/docs/DOM/SVGPathElement /en-US/docs/Web/API/SVGPathElement @@ -1632,7 +1632,7 @@ /en-US/docs/DOM/SVGStyleElement /en-US/docs/Web/API/SVGStyleElement /en-US/docs/DOM/SVGSwitchElement /en-US/docs/Web/API/SVGSwitchElement /en-US/docs/DOM/SVGSymbolElement /en-US/docs/Web/API/SVGSymbolElement -/en-US/docs/DOM/SVGTRefElement /en-US/docs/Web/API/SVGTRefElement +/en-US/docs/DOM/SVGTRefElement /en-US/docs/Web/API/SVGElement /en-US/docs/DOM/SVGTSpanElement /en-US/docs/Web/API/SVGTSpanElement /en-US/docs/DOM/SVGTextElement /en-US/docs/Web/API/SVGTextElement /en-US/docs/DOM/SVGTextPositioningElement /en-US/docs/Web/API/SVGTextPositioningElement @@ -1640,7 +1640,7 @@ /en-US/docs/DOM/SVGTransform /en-US/docs/Web/API/SVGTransform /en-US/docs/DOM/SVGTransformList /en-US/docs/Web/API/SVGTransformList /en-US/docs/DOM/SVGUseElement /en-US/docs/Web/API/SVGUseElement -/en-US/docs/DOM/SVGVKernElement /en-US/docs/Web/API/SVGVKernElement +/en-US/docs/DOM/SVGVKernElement /en-US/docs/Web/API/SVGElement /en-US/docs/DOM/SVGViewElement /en-US/docs/Web/API/SVGViewElement /en-US/docs/DOM/ScriptProcessorNode /en-US/docs/Web/API/ScriptProcessorNode /en-US/docs/DOM/Selection /en-US/docs/Web/API/Selection @@ -1890,8 +1890,8 @@ /en-US/docs/DOM/element.onblur /en-US/docs/Web/API/Window/blur_event /en-US/docs/DOM/element.onchange /en-US/docs/Web/API/HTMLElement/change_event /en-US/docs/DOM/element.onclick /en-US/docs/Web/API/Element/click_event -/en-US/docs/DOM/element.oncopy /en-US/docs/Web/API/HTMLElement/copy_event -/en-US/docs/DOM/element.oncut /en-US/docs/Web/API/HTMLElement/cut_event +/en-US/docs/DOM/element.oncopy /en-US/docs/Web/API/Element/copy_event +/en-US/docs/DOM/element.oncut /en-US/docs/Web/API/Element/cut_event /en-US/docs/DOM/element.ondblclick /en-US/docs/Web/API/Element/dblclick_event /en-US/docs/DOM/element.onfocus /en-US/docs/Web/API/Window/focus_event /en-US/docs/DOM/element.onkeydown /en-US/docs/Web/API/Element/keydown_event @@ -1901,7 +1901,7 @@ /en-US/docs/DOM/element.onmousemove /en-US/docs/Web/API/Element/mousemove_event /en-US/docs/DOM/element.onmouseout /en-US/docs/Web/API/Element/mouseout_event /en-US/docs/DOM/element.onmouseup /en-US/docs/Web/API/Element/mouseup_event -/en-US/docs/DOM/element.onpaste /en-US/docs/Web/API/HTMLElement/paste_event +/en-US/docs/DOM/element.onpaste /en-US/docs/Web/API/Element/paste_event /en-US/docs/DOM/element.onresize /en-US/docs/Web/API/Window/resize_event /en-US/docs/DOM/element.onscroll /en-US/docs/Web/API/Element/scroll_event /en-US/docs/DOM/element.onwheel /en-US/docs/Web/API/Element/wheel_event @@ -2064,7 +2064,7 @@ /en-US/docs/DOM/window.URL.revokeObjectURL /en-US/docs/Web/API/URL/revokeObjectURL_static /en-US/docs/DOM/window.alert /en-US/docs/Web/API/Window/alert /en-US/docs/DOM/window.atob /en-US/docs/Web/API/Window/atob -/en-US/docs/DOM/window.back /en-US/docs/Web/API/Window/back +/en-US/docs/DOM/window.back /en-US/docs/Web/API/History/back /en-US/docs/DOM/window.blur /en-US/docs/Web/API/Window/blur /en-US/docs/DOM/window.btoa /en-US/docs/Web/API/Window/btoa /en-US/docs/DOM/window.cancelAnimationFrame /en-US/docs/Web/API/Window/cancelAnimationFrame @@ -2083,7 +2083,7 @@ /en-US/docs/DOM/window.escape /en-US/docs/Web/JavaScript/Reference/Global_Objects/escape /en-US/docs/DOM/window.find /en-US/docs/Web/API/Window/find /en-US/docs/DOM/window.focus /en-US/docs/Web/API/Window/focus -/en-US/docs/DOM/window.forward /en-US/docs/Web/API/Window/forward +/en-US/docs/DOM/window.forward /en-US/docs/Web/API/History/forward /en-US/docs/DOM/window.frameElement /en-US/docs/Web/API/Window/frameElement /en-US/docs/DOM/window.frames /en-US/docs/Web/API/Window/frames /en-US/docs/DOM/window.fullScreen /en-US/docs/Web/API/Window/fullScreen @@ -2219,7 +2219,7 @@ /en-US/docs/DOM/window.setImmediate /en-US/docs/Web/API/Window/setImmediate /en-US/docs/DOM/window.setInterval /en-US/docs/Web/API/Window/setInterval /en-US/docs/DOM/window.setTimeout /en-US/docs/Web/API/Window/setTimeout -/en-US/docs/DOM/window.showModalDialog /en-US/docs/Web/API/Window/showModalDialog +/en-US/docs/DOM/window.showModalDialog /en-US/docs/Web/API/HTMLDialogElement/showModal /en-US/docs/DOM/window.sidebar /en-US/docs/Web/API/Window/external /en-US/docs/DOM/window.sizeToContent /en-US/docs/Web/API/Window/sizeToContent /en-US/docs/DOM/window.status /en-US/docs/Web/API/Window/status @@ -2380,8 +2380,8 @@ /en-US/docs/DOM:element.onblur /en-US/docs/Web/API/Window/blur_event /en-US/docs/DOM:element.onchange /en-US/docs/Web/API/HTMLElement/change_event /en-US/docs/DOM:element.onclick /en-US/docs/Web/API/Element/click_event -/en-US/docs/DOM:element.oncopy /en-US/docs/Web/API/HTMLElement/copy_event -/en-US/docs/DOM:element.oncut /en-US/docs/Web/API/HTMLElement/cut_event +/en-US/docs/DOM:element.oncopy /en-US/docs/Web/API/Element/copy_event +/en-US/docs/DOM:element.oncut /en-US/docs/Web/API/Element/cut_event /en-US/docs/DOM:element.ondblclick /en-US/docs/Web/API/Element/dblclick_event /en-US/docs/DOM:element.onfocus /en-US/docs/Web/API/Window/focus_event /en-US/docs/DOM:element.onkeydown /en-US/docs/Web/API/Element/keydown_event @@ -2391,7 +2391,7 @@ /en-US/docs/DOM:element.onmousemove /en-US/docs/Web/API/Element/mousemove_event /en-US/docs/DOM:element.onmouseout /en-US/docs/Web/API/Element/mouseout_event /en-US/docs/DOM:element.onmouseup /en-US/docs/Web/API/Element/mouseup_event -/en-US/docs/DOM:element.onpaste /en-US/docs/Web/API/HTMLElement/paste_event +/en-US/docs/DOM:element.onpaste /en-US/docs/Web/API/Element/paste_event /en-US/docs/DOM:element.onresize /en-US/docs/Web/API/Window/resize_event /en-US/docs/DOM:element.onscroll /en-US/docs/Web/API/Element/scroll_event /en-US/docs/DOM:element.ownerDocument /en-US/docs/Web/API/Node/ownerDocument @@ -2526,7 +2526,7 @@ /en-US/docs/DOM:window /en-US/docs/Web/API/Window /en-US/docs/DOM:window.alert /en-US/docs/Web/API/Window/alert /en-US/docs/DOM:window.atob /en-US/docs/Web/API/Window/atob -/en-US/docs/DOM:window.back /en-US/docs/Web/API/Window/back +/en-US/docs/DOM:window.back /en-US/docs/Web/API/History/back /en-US/docs/DOM:window.blur /en-US/docs/Web/API/Window/blur /en-US/docs/DOM:window.btoa /en-US/docs/Web/API/Window/btoa /en-US/docs/DOM:window.captureEvents /en-US/docs/Web/API/Window/captureEvents @@ -2542,7 +2542,7 @@ /en-US/docs/DOM:window.escape /en-US/docs/Web/JavaScript/Reference/Global_Objects/escape /en-US/docs/DOM:window.find /en-US/docs/Web/API/Window/find /en-US/docs/DOM:window.focus /en-US/docs/Web/API/Window/focus -/en-US/docs/DOM:window.forward /en-US/docs/Web/API/Window/forward +/en-US/docs/DOM:window.forward /en-US/docs/Web/API/History/forward /en-US/docs/DOM:window.frameElement /en-US/docs/Web/API/Window/frameElement /en-US/docs/DOM:window.frames /en-US/docs/Web/API/Window/frames /en-US/docs/DOM:window.fullScreen /en-US/docs/Web/API/Window/fullScreen @@ -2641,7 +2641,7 @@ /en-US/docs/DOM:window.self /en-US/docs/Web/API/Window/self /en-US/docs/DOM:window.setInterval /en-US/docs/Web/API/Window/setInterval /en-US/docs/DOM:window.setTimeout /en-US/docs/Web/API/Window/setTimeout -/en-US/docs/DOM:window.showModalDialog /en-US/docs/Web/API/Window/showModalDialog +/en-US/docs/DOM:window.showModalDialog /en-US/docs/Web/API/HTMLDialogElement/showModal /en-US/docs/DOM:window.sidebar /en-US/docs/Web/API/Window/external /en-US/docs/DOM:window.sizeToContent /en-US/docs/Web/API/Window/sizeToContent /en-US/docs/DOM:window.status /en-US/docs/Web/API/Window/status @@ -2902,22 +2902,22 @@ /en-US/docs/Document_Object_Model_(DOM)/SVGAnimationElement /en-US/docs/Web/API/SVGAnimationElement /en-US/docs/Document_Object_Model_(DOM)/SVGCircleElement /en-US/docs/Web/API/SVGCircleElement /en-US/docs/Document_Object_Model_(DOM)/SVGClipPathElement /en-US/docs/Web/API/SVGClipPathElement -/en-US/docs/Document_Object_Model_(DOM)/SVGCursorElement /en-US/docs/Web/API/SVGCursorElement +/en-US/docs/Document_Object_Model_(DOM)/SVGCursorElement /en-US/docs/Web/API/SVGElement /en-US/docs/Document_Object_Model_(DOM)/SVGDefsElement /en-US/docs/Web/API/SVGDefsElement /en-US/docs/Document_Object_Model_(DOM)/SVGDescElement /en-US/docs/Web/API/SVGDescElement /en-US/docs/Document_Object_Model_(DOM)/SVGElement /en-US/docs/Web/API/SVGElement /en-US/docs/Document_Object_Model_(DOM)/SVGEllipseElement /en-US/docs/Web/API/SVGEllipseElement -/en-US/docs/Document_Object_Model_(DOM)/SVGFontElement /en-US/docs/Web/API/SVGFontElement -/en-US/docs/Document_Object_Model_(DOM)/SVGFontFaceElement /en-US/docs/Web/API/SVGFontFaceElement -/en-US/docs/Document_Object_Model_(DOM)/SVGFontFaceFormatElement /en-US/docs/Web/API/SVGFontFaceFormatElement -/en-US/docs/Document_Object_Model_(DOM)/SVGFontFaceNameElement /en-US/docs/Web/API/SVGFontFaceNameElement -/en-US/docs/Document_Object_Model_(DOM)/SVGFontFaceSrcElement /en-US/docs/Web/API/SVGFontFaceSrcElement -/en-US/docs/Document_Object_Model_(DOM)/SVGFontFaceUriElement /en-US/docs/Web/API/SVGFontFaceUriElement +/en-US/docs/Document_Object_Model_(DOM)/SVGFontElement /en-US/docs/Web/API/SVGElement +/en-US/docs/Document_Object_Model_(DOM)/SVGFontFaceElement /en-US/docs/Web/API/SVGElement +/en-US/docs/Document_Object_Model_(DOM)/SVGFontFaceFormatElement /en-US/docs/Web/API/SVGElement +/en-US/docs/Document_Object_Model_(DOM)/SVGFontFaceNameElement /en-US/docs/Web/API/SVGElement +/en-US/docs/Document_Object_Model_(DOM)/SVGFontFaceSrcElement /en-US/docs/Web/API/SVGElement +/en-US/docs/Document_Object_Model_(DOM)/SVGFontFaceUriElement /en-US/docs/Web/API/SVGElement /en-US/docs/Document_Object_Model_(DOM)/SVGForeignObjectElement /en-US/docs/Web/API/SVGForeignObjectElement /en-US/docs/Document_Object_Model_(DOM)/SVGGElement /en-US/docs/Web/API/SVGGElement -/en-US/docs/Document_Object_Model_(DOM)/SVGGlyphElement /en-US/docs/Web/API/SVGGlyphElement +/en-US/docs/Document_Object_Model_(DOM)/SVGGlyphElement /en-US/docs/Web/API/SVGElement /en-US/docs/Document_Object_Model_(DOM)/SVGGradientElement /en-US/docs/Web/API/SVGGradientElement -/en-US/docs/Document_Object_Model_(DOM)/SVGHKernElement /en-US/docs/Web/API/SVGHKernElement +/en-US/docs/Document_Object_Model_(DOM)/SVGHKernElement /en-US/docs/Web/API/SVGElement /en-US/docs/Document_Object_Model_(DOM)/SVGImageElement /en-US/docs/Web/API/SVGImageElement /en-US/docs/Document_Object_Model_(DOM)/SVGLength /en-US/docs/Web/API/SVGLength /en-US/docs/Document_Object_Model_(DOM)/SVGLengthList /en-US/docs/Web/API/SVGLengthList @@ -2926,7 +2926,7 @@ /en-US/docs/Document_Object_Model_(DOM)/SVGMPathElement /en-US/docs/Web/API/SVGMPathElement /en-US/docs/Document_Object_Model_(DOM)/SVGMaskElement /en-US/docs/Web/API/SVGMaskElement /en-US/docs/Document_Object_Model_(DOM)/SVGMatrix /en-US/docs/Web/API/DOMMatrix -/en-US/docs/Document_Object_Model_(DOM)/SVGMissingGlyphElement /en-US/docs/Web/API/SVGMissingGlyphElement +/en-US/docs/Document_Object_Model_(DOM)/SVGMissingGlyphElement /en-US/docs/Web/API/SVGElement /en-US/docs/Document_Object_Model_(DOM)/SVGNumber /en-US/docs/Web/API/SVGNumber /en-US/docs/Document_Object_Model_(DOM)/SVGNumberList /en-US/docs/Web/API/SVGNumberList /en-US/docs/Document_Object_Model_(DOM)/SVGPathElement /en-US/docs/Web/API/SVGPathElement @@ -2946,7 +2946,7 @@ /en-US/docs/Document_Object_Model_(DOM)/SVGStyleElement /en-US/docs/Web/API/SVGStyleElement /en-US/docs/Document_Object_Model_(DOM)/SVGSwitchElement /en-US/docs/Web/API/SVGSwitchElement /en-US/docs/Document_Object_Model_(DOM)/SVGSymbolElement /en-US/docs/Web/API/SVGSymbolElement -/en-US/docs/Document_Object_Model_(DOM)/SVGTRefElement /en-US/docs/Web/API/SVGTRefElement +/en-US/docs/Document_Object_Model_(DOM)/SVGTRefElement /en-US/docs/Web/API/SVGElement /en-US/docs/Document_Object_Model_(DOM)/SVGTSpanElement /en-US/docs/Web/API/SVGTSpanElement /en-US/docs/Document_Object_Model_(DOM)/SVGTextElement /en-US/docs/Web/API/SVGTextElement /en-US/docs/Document_Object_Model_(DOM)/SVGTextPositioningElement /en-US/docs/Web/API/SVGTextPositioningElement @@ -2954,7 +2954,7 @@ /en-US/docs/Document_Object_Model_(DOM)/SVGTransform /en-US/docs/Web/API/SVGTransform /en-US/docs/Document_Object_Model_(DOM)/SVGTransformList /en-US/docs/Web/API/SVGTransformList /en-US/docs/Document_Object_Model_(DOM)/SVGUseElement /en-US/docs/Web/API/SVGUseElement -/en-US/docs/Document_Object_Model_(DOM)/SVGVKernElement /en-US/docs/Web/API/SVGVKernElement +/en-US/docs/Document_Object_Model_(DOM)/SVGVKernElement /en-US/docs/Web/API/SVGElement /en-US/docs/Document_Object_Model_(DOM)/SVGViewElement /en-US/docs/Web/API/SVGViewElement /en-US/docs/Document_Object_Model_(DOM)/SharedWorker /en-US/docs/Web/API/SharedWorker /en-US/docs/Document_Object_Model_(DOM)/StorageEvent /en-US/docs/Web/API/StorageEvent @@ -3117,8 +3117,8 @@ /en-US/docs/Document_Object_Model_(DOM)/element.onblur /en-US/docs/Web/API/Window/blur_event /en-US/docs/Document_Object_Model_(DOM)/element.onchange /en-US/docs/Web/API/HTMLElement/change_event /en-US/docs/Document_Object_Model_(DOM)/element.onclick /en-US/docs/Web/API/Element/click_event -/en-US/docs/Document_Object_Model_(DOM)/element.oncopy /en-US/docs/Web/API/HTMLElement/copy_event -/en-US/docs/Document_Object_Model_(DOM)/element.oncut /en-US/docs/Web/API/HTMLElement/cut_event +/en-US/docs/Document_Object_Model_(DOM)/element.oncopy /en-US/docs/Web/API/Element/copy_event +/en-US/docs/Document_Object_Model_(DOM)/element.oncut /en-US/docs/Web/API/Element/cut_event /en-US/docs/Document_Object_Model_(DOM)/element.ondblclick /en-US/docs/Web/API/Element/dblclick_event /en-US/docs/Document_Object_Model_(DOM)/element.onfocus /en-US/docs/Web/API/Window/focus_event /en-US/docs/Document_Object_Model_(DOM)/element.onkeydown /en-US/docs/Web/API/Element/keydown_event @@ -3128,7 +3128,7 @@ /en-US/docs/Document_Object_Model_(DOM)/element.onmousemove /en-US/docs/Web/API/Element/mousemove_event /en-US/docs/Document_Object_Model_(DOM)/element.onmouseout /en-US/docs/Web/API/Element/mouseout_event /en-US/docs/Document_Object_Model_(DOM)/element.onmouseup /en-US/docs/Web/API/Element/mouseup_event -/en-US/docs/Document_Object_Model_(DOM)/element.onpaste /en-US/docs/Web/API/HTMLElement/paste_event +/en-US/docs/Document_Object_Model_(DOM)/element.onpaste /en-US/docs/Web/API/Element/paste_event /en-US/docs/Document_Object_Model_(DOM)/element.onresize /en-US/docs/Web/API/Window/resize_event /en-US/docs/Document_Object_Model_(DOM)/element.onscroll /en-US/docs/Web/API/Element/scroll_event /en-US/docs/Document_Object_Model_(DOM)/element.outerHTML /en-US/docs/Web/API/Element/outerHTML @@ -3251,7 +3251,7 @@ /en-US/docs/Document_Object_Model_(DOM)/window.crypto.getRandomValues /en-US/docs/Web/API/Crypto/getRandomValues /en-US/docs/Document_Object_Model_(DOM)/window.document /en-US/docs/Web/API/Window/document /en-US/docs/Document_Object_Model_(DOM)/window.escape /en-US/docs/Web/JavaScript/Reference/Global_Objects/escape -/en-US/docs/Document_Object_Model_(DOM)/window.forward /en-US/docs/Web/API/Window/forward +/en-US/docs/Document_Object_Model_(DOM)/window.forward /en-US/docs/Web/API/History/forward /en-US/docs/Document_Object_Model_(DOM)/window.frameElement /en-US/docs/Web/API/Window/frameElement /en-US/docs/Document_Object_Model_(DOM)/window.frames /en-US/docs/Web/API/Window/frames /en-US/docs/Document_Object_Model_(DOM)/window.fullScreen /en-US/docs/Web/API/Window/fullScreen @@ -3360,7 +3360,7 @@ /en-US/docs/Document_Object_Model_(DOM)/window.setImmediate /en-US/docs/Web/API/Window/setImmediate /en-US/docs/Document_Object_Model_(DOM)/window.setInterval /en-US/docs/Web/API/Window/setInterval /en-US/docs/Document_Object_Model_(DOM)/window.setTimeout /en-US/docs/Web/API/Window/setTimeout -/en-US/docs/Document_Object_Model_(DOM)/window.showModalDialog /en-US/docs/Web/API/Window/showModalDialog +/en-US/docs/Document_Object_Model_(DOM)/window.showModalDialog /en-US/docs/Web/API/HTMLDialogElement/showModal /en-US/docs/Document_Object_Model_(DOM)/window.sidebar /en-US/docs/Web/API/Window/external /en-US/docs/Document_Object_Model_(DOM)/window.sizeToContent /en-US/docs/Web/API/Window/sizeToContent /en-US/docs/Document_Object_Model_(DOM)/window.status /en-US/docs/Web/API/Window/status @@ -3377,9 +3377,9 @@ /en-US/docs/DragDrop/Recommended_Drag_Types /en-US/docs/Web/API/HTML_Drag_and_Drop_API/Recommended_drag_types /en-US/docs/Drawing_Graphics_with_Canvas /en-US/docs/Web/API/Canvas_API/Tutorial /en-US/docs/Drawing_text_using_a_canvas /en-US/docs/Web/API/Canvas_API/Tutorial/Drawing_text -/en-US/docs/ECMA-262 /en-US/docs/Web/JavaScript/JavaScript_technologies_overview -/en-US/docs/ECMAScript /en-US/docs/Web/JavaScript/JavaScript_technologies_overview -/en-US/docs/ECMAScript_DontEnum_attribute /en-US/docs/Web/JavaScript/Data_structures#Properties +/en-US/docs/ECMA-262 /en-US/docs/Web/JavaScript/Reference/JavaScript_technologies_overview +/en-US/docs/ECMAScript /en-US/docs/Web/JavaScript/Reference/JavaScript_technologies_overview +/en-US/docs/ECMAScript_DontEnum_attribute /en-US/docs/Web/JavaScript/Guide/Data_structures#Properties /en-US/docs/ESLint https://firefox-source-docs.mozilla.org/code-quality/lint/index.html /en-US/docs/EXSLT /en-US/docs/Web/XML/EXSLT /en-US/docs/EXSLT/exsl /en-US/docs/Web/XML/EXSLT/Reference/exsl @@ -3425,7 +3425,7 @@ /en-US/docs/EXSLT:str:tokenize /en-US/docs/Web/XML/EXSLT/Reference/str/tokenize /en-US/docs/Edit_fonts https://firefox-source-docs.mozilla.org/devtools-user/page_inspector/how_to/edit_fonts/index.html /en-US/docs/Element.hasAttributes() /en-US/docs/Web/API/Element/hasAttributes -/en-US/docs/Enumerability_and_ownership_of_properties /en-US/docs/Web/JavaScript/Enumerability_and_ownership_of_properties +/en-US/docs/Enumerability_and_ownership_of_properties /en-US/docs/Web/JavaScript/Guide/Enumerability_and_ownership_of_properties /en-US/docs/Event.initEvent /en-US/docs/Web/API/Event/initEvent /en-US/docs/Extension_Library/Extensions /en-US/docs/Mozilla/Add-ons /en-US/docs/Extension_Library/Extensions/Firefox /en-US/docs/Mozilla/Add-ons @@ -3466,7 +3466,7 @@ /en-US/docs/Firefox_7_for_developers /en-US/docs/Mozilla/Firefox/Releases/7 /en-US/docs/Firefox_8_for_developers /en-US/docs/Mozilla/Firefox/Releases/8 /en-US/docs/Firefox_9_for_developers /en-US/docs/Mozilla/Firefox/Releases/9 -/en-US/docs/Firefox_User_Agent_String_Reference /en-US/docs/Web/HTTP/Headers/User-Agent/Firefox +/en-US/docs/Firefox_User_Agent_String_Reference /en-US/docs/Web/HTTP/Reference/Headers/User-Agent/Firefox /en-US/docs/Firefox_for_developers /en-US/docs/Mozilla/Firefox/Releases/20 /en-US/docs/Fixing_common_validation_problems /en-US/docs/Learn_web_development/Core/Structuring_content/Debugging_HTML /en-US/docs/Flexible_Box /en-US/docs/Web/CSS/CSS_flexible_box_layout/Basic_concepts_of_flexbox @@ -3479,8 +3479,9 @@ /en-US/docs/Games/Anatomy_of_a_vIdeo_game /en-US/docs/Games/Anatomy /en-US/docs/Games/Index /en-US/docs/Games /en-US/docs/Games/Introduction/Introduction_3D /en-US/docs/Games/Techniques/3D_on_the_web -/en-US/docs/Games/Introduction_to_HTML5_Game_Development_(summary) /en-US/docs/Games/Introduction_to_HTML5_Game_Development -/en-US/docs/Games/Introduction_to_HTML5_Game_Gevelopment_(summary) /en-US/docs/Games/Introduction_to_HTML5_Game_Development +/en-US/docs/Games/Introduction_to_HTML5_Game_Development /en-US/docs/Games/Tools +/en-US/docs/Games/Introduction_to_HTML5_Game_Development_(summary) /en-US/docs/Games/Tools +/en-US/docs/Games/Introduction_to_HTML5_Game_Gevelopment_(summary) /en-US/docs/Games/Tools /en-US/docs/Games/Techniques/3D_collision_detection/Bounding_boxes_with_THREE.js /en-US/docs/Games/Techniques/3D_collision_detection/Bounding_volume_collision_detection_with_THREE.js /en-US/docs/Games/Techniques/3D_on_the_web/WebVR /en-US/docs/Games/Techniques/3D_on_the_web/WebXR /en-US/docs/Games/Techniques/Crisp,_pixel_art_look_with_image-rendering /en-US/docs/Games/Techniques/Crisp_pixel_art_look @@ -3544,8 +3545,8 @@ /en-US/docs/Games/visual_typescript_game_engine /en-US/docs/Games /en-US/docs/Getting_Started_With_NSS https://firefox-source-docs.mozilla.org/security/nss/index.html /en-US/docs/Getting_started_on_MDN /en-US/docs/MDN/Community/Getting_started -/en-US/docs/Glossary/404 /en-US/docs/Web/HTTP/Status/404 -/en-US/docs/Glossary/502 /en-US/docs/Web/HTTP/Status/502 +/en-US/docs/Glossary/404 /en-US/docs/Web/HTTP/Reference/Status/404 +/en-US/docs/Glossary/502 /en-US/docs/Web/HTTP/Reference/Status/502 /en-US/docs/Glossary/AOM /en-US/docs/Glossary/Accessibility_tree /en-US/docs/Glossary/B2G /en-US/docs/Glossary/Firefox_OS /en-US/docs/Glossary/Block/Block_(CSS) /en-US/docs/Glossary/Block/CSS @@ -3556,22 +3557,24 @@ /en-US/docs/Glossary/CSS_property /en-US/docs/Glossary/Property/CSS /en-US/docs/Glossary/Cleartext /en-US/docs/Glossary/Plaintext /en-US/docs/Glossary/Clickjacking /en-US/docs/Web/Security/Attacks/Clickjacking -/en-US/docs/Glossary/Client_hints /en-US/docs/Web/HTTP/Client_hints +/en-US/docs/Glossary/Client_hints /en-US/docs/Web/HTTP/Guides/Client_hints /en-US/docs/Glossary/Condition /en-US/docs/Glossary/Conditional /en-US/docs/Glossary/Content_type /en-US/docs/Glossary/MIME_type +/en-US/docs/Glossary/Cryptographic_hash_function /en-US/docs/Glossary/Hash_function /en-US/docs/Glossary/DOS_attack /en-US/docs/Glossary/Denial_of_Service /en-US/docs/Glossary/DTD /en-US/docs/Glossary/Doctype /en-US/docs/Glossary/Descriptor_(CSS) /en-US/docs/Glossary/CSS_Descriptor +/en-US/docs/Glossary/Digest /en-US/docs/Glossary/Hash_function /en-US/docs/Glossary/Distributed_DenialofService /en-US/docs/Glossary/Distributed_Denial_of_Service /en-US/docs/Glossary/Empty_element /en-US/docs/Glossary/Void_element /en-US/docs/Glossary/Error /en-US/docs/Glossary/Exception /en-US/docs/Glossary/First_interactive /en-US/docs/Glossary/First_CPU_idle /en-US/docs/Glossary/Forbidden_header_name /en-US/docs/Glossary/Forbidden_request_header /en-US/docs/Glossary/GZip /en-US/docs/Glossary/gzip_compression -/en-US/docs/Glossary/Global_attribute /en-US/docs/Web/HTML/Global_attributes +/en-US/docs/Glossary/Global_attribute /en-US/docs/Web/HTML/Reference/Global_attributes /en-US/docs/Glossary/Grid_Rows /en-US/docs/Glossary/Grid_Row /en-US/docs/Glossary/Guard /en-US/docs/Web/API/Fetch_API/Using_Fetch -/en-US/docs/Glossary/Hash_function /en-US/docs/Glossary/Cryptographic_hash_function +/en-US/docs/Glossary/Hash /en-US/docs/Glossary/Hash_function /en-US/docs/Glossary/Header /en-US/docs/Glossary/HTTP_header /en-US/docs/Glossary/I18N /en-US/docs/Glossary/Internationalization /en-US/docs/Glossary/IMAP4 /en-US/docs/Glossary/IMAP @@ -3619,241 +3622,241 @@ /en-US/docs/Glossary/q_values /en-US/docs/Glossary/Quality_values /en-US/docs/Glossarybandwidth /en-US/docs/Glossary/Bandwidth /en-US/docs/Guide_to_Shorthand_CSS /en-US/docs/Web/CSS/CSS_cascade/Shorthand_properties -/en-US/docs/HTM/Attribute /en-US/docs/Web/HTML/Attributes +/en-US/docs/HTM/Attribute /en-US/docs/Web/HTML/Reference/Attributes /en-US/docs/HTML /en-US/docs/Web/HTML -/en-US/docs/HTML/Attributes /en-US/docs/Web/HTML/Attributes +/en-US/docs/HTML/Attributes /en-US/docs/Web/HTML/Reference/Attributes /en-US/docs/HTML/Bad_copy_pasting_habits /en-US/docs/Learn_web_development/Core/Structuring_content /en-US/docs/HTML/Block-level_elements /en-US/docs/Glossary/Block-level_content -/en-US/docs/HTML/CORS_Enabled_Image /en-US/docs/Web/HTML/CORS_enabled_image -/en-US/docs/HTML/CORS_settings_attributes /en-US/docs/Web/HTML/Attributes/crossorigin +/en-US/docs/HTML/CORS_Enabled_Image /en-US/docs/Web/HTML/How_to/CORS_enabled_image +/en-US/docs/HTML/CORS_settings_attributes /en-US/docs/Web/HTML/Reference/Attributes/crossorigin /en-US/docs/HTML/Canvas /en-US/docs/Web/API/Canvas_API /en-US/docs/HTML/Canvas/Drawing_Graphics_with_Canvas /en-US/docs/Web/API/Canvas_API/Tutorial /en-US/docs/HTML/Canvas/Pixel_manipulation_with_canvas /en-US/docs/Web/API/Canvas_API/Tutorial/Pixel_manipulation_with_canvas /en-US/docs/HTML/Canvas/Tutorial /en-US/docs/Web/API/Canvas_API/Tutorial /en-US/docs/HTML/Canvas/Tutorial/Basic_animations /en-US/docs/Web/API/Canvas_API/Tutorial/Basic_animations -/en-US/docs/HTML/Content_Editable /en-US/docs/Web/HTML/Global_attributes/contenteditable -/en-US/docs/HTML/Content_categories /en-US/docs/Web/HTML/Content_categories -/en-US/docs/HTML/Controlling_spell_checking_in_HTML_forms /en-US/docs/Web/HTML/Global_attributes/spellcheck -/en-US/docs/HTML/Element /en-US/docs/Web/HTML/Element +/en-US/docs/HTML/Content_Editable /en-US/docs/Web/HTML/Reference/Global_attributes/contenteditable +/en-US/docs/HTML/Content_categories /en-US/docs/Web/HTML/Guides/Content_categories +/en-US/docs/HTML/Controlling_spell_checking_in_HTML_forms /en-US/docs/Web/HTML/Reference/Global_attributes/spellcheck +/en-US/docs/HTML/Element /en-US/docs/Web/HTML/Reference/Elements /en-US/docs/HTML/Element/HTMLHeadElement /en-US/docs/Web/API/HTMLHeadElement -/en-US/docs/HTML/Element/Heading_Elements /en-US/docs/Web/HTML/Element/Heading_Elements -/en-US/docs/HTML/Element/Img /en-US/docs/Web/HTML/Element/img -/en-US/docs/HTML/Element/Img-redirect-1 /en-US/docs/Web/HTML/Element/img -/en-US/docs/HTML/Element/Input /en-US/docs/Web/HTML/Element/input -/en-US/docs/HTML/Element/Input-redirect-1 /en-US/docs/Web/HTML/Element/input -/en-US/docs/HTML/Element/a /en-US/docs/Web/HTML/Element/a -/en-US/docs/HTML/Element/abbr /en-US/docs/Web/HTML/Element/abbr -/en-US/docs/HTML/Element/abbr-redirect-1 /en-US/docs/Web/HTML/Element/abbr -/en-US/docs/HTML/Element/acronym /en-US/docs/Web/HTML/Element/acronym -/en-US/docs/HTML/Element/acronym-redirect-1 /en-US/docs/Web/HTML/Element/acronym -/en-US/docs/HTML/Element/acronym2 /en-US/docs/Web/HTML/Element/acronym -/en-US/docs/HTML/Element/address /en-US/docs/Web/HTML/Element/address -/en-US/docs/HTML/Element/area /en-US/docs/Web/HTML/Element/area -/en-US/docs/HTML/Element/area-redirect-1 /en-US/docs/Web/HTML/Element/area -/en-US/docs/HTML/Element/article /en-US/docs/Web/HTML/Element/article -/en-US/docs/HTML/Element/aside /en-US/docs/Web/HTML/Element/aside -/en-US/docs/HTML/Element/audio /en-US/docs/Web/HTML/Element/audio -/en-US/docs/HTML/Element/b /en-US/docs/Web/HTML/Element/b -/en-US/docs/HTML/Element/b-redirect-1 /en-US/docs/Web/HTML/Element/b -/en-US/docs/HTML/Element/base /en-US/docs/Web/HTML/Element/base -/en-US/docs/HTML/Element/base-redirect-1 /en-US/docs/Web/HTML/Element/base -/en-US/docs/HTML/Element/base-redirect-2 /en-US/docs/Web/HTML/Element/base -/en-US/docs/HTML/Element/base-redirect-3 /en-US/docs/Web/HTML/Element/base +/en-US/docs/HTML/Element/Heading_Elements /en-US/docs/Web/HTML/Reference/Elements/Heading_Elements +/en-US/docs/HTML/Element/Img /en-US/docs/Web/HTML/Reference/Elements/img +/en-US/docs/HTML/Element/Img-redirect-1 /en-US/docs/Web/HTML/Reference/Elements/img +/en-US/docs/HTML/Element/Input /en-US/docs/Web/HTML/Reference/Elements/input +/en-US/docs/HTML/Element/Input-redirect-1 /en-US/docs/Web/HTML/Reference/Elements/input +/en-US/docs/HTML/Element/a /en-US/docs/Web/HTML/Reference/Elements/a +/en-US/docs/HTML/Element/abbr /en-US/docs/Web/HTML/Reference/Elements/abbr +/en-US/docs/HTML/Element/abbr-redirect-1 /en-US/docs/Web/HTML/Reference/Elements/abbr +/en-US/docs/HTML/Element/acronym /en-US/docs/Web/HTML/Reference/Elements/acronym +/en-US/docs/HTML/Element/acronym-redirect-1 /en-US/docs/Web/HTML/Reference/Elements/acronym +/en-US/docs/HTML/Element/acronym2 /en-US/docs/Web/HTML/Reference/Elements/acronym +/en-US/docs/HTML/Element/address /en-US/docs/Web/HTML/Reference/Elements/address +/en-US/docs/HTML/Element/area /en-US/docs/Web/HTML/Reference/Elements/area +/en-US/docs/HTML/Element/area-redirect-1 /en-US/docs/Web/HTML/Reference/Elements/area +/en-US/docs/HTML/Element/article /en-US/docs/Web/HTML/Reference/Elements/article +/en-US/docs/HTML/Element/aside /en-US/docs/Web/HTML/Reference/Elements/aside +/en-US/docs/HTML/Element/audio /en-US/docs/Web/HTML/Reference/Elements/audio +/en-US/docs/HTML/Element/b /en-US/docs/Web/HTML/Reference/Elements/b +/en-US/docs/HTML/Element/b-redirect-1 /en-US/docs/Web/HTML/Reference/Elements/b +/en-US/docs/HTML/Element/base /en-US/docs/Web/HTML/Reference/Elements/base +/en-US/docs/HTML/Element/base-redirect-1 /en-US/docs/Web/HTML/Reference/Elements/base +/en-US/docs/HTML/Element/base-redirect-2 /en-US/docs/Web/HTML/Reference/Elements/base +/en-US/docs/HTML/Element/base-redirect-3 /en-US/docs/Web/HTML/Reference/Elements/base /en-US/docs/HTML/Element/basefont /en-US/docs/Web/CSS/CSS_fonts /en-US/docs/HTML/Element/basefont-redirect-1 /en-US/docs/Web/CSS/CSS_fonts -/en-US/docs/HTML/Element/bdi /en-US/docs/Web/HTML/Element/bdi -/en-US/docs/HTML/Element/bdi-redirect-1 /en-US/docs/Web/HTML/Element/bdi -/en-US/docs/HTML/Element/bdo /en-US/docs/Web/HTML/Element/bdo -/en-US/docs/HTML/Element/bdo-redirect-1 /en-US/docs/Web/HTML/Element/bdo -/en-US/docs/HTML/Element/bgcound /en-US/docs/Web/HTML/Element/audio -/en-US/docs/HTML/Element/bgsound /en-US/docs/Web/HTML/Element/audio -/en-US/docs/HTML/Element/big /en-US/docs/Web/HTML/Element/big -/en-US/docs/HTML/Element/blockquote /en-US/docs/Web/HTML/Element/blockquote -/en-US/docs/HTML/Element/blockquote-redirect-1 /en-US/docs/Web/HTML/Element/blockquote -/en-US/docs/HTML/Element/body /en-US/docs/Web/HTML/Element/body -/en-US/docs/HTML/Element/body-redirect-1 /en-US/docs/Web/HTML/Element/body -/en-US/docs/HTML/Element/br /en-US/docs/Web/HTML/Element/br -/en-US/docs/HTML/Element/br-redirect-1 /en-US/docs/Web/HTML/Element/br -/en-US/docs/HTML/Element/button /en-US/docs/Web/HTML/Element/button -/en-US/docs/HTML/Element/button-redirect-1 /en-US/docs/Web/HTML/Element/button -/en-US/docs/HTML/Element/canvas /en-US/docs/Web/HTML/Element/canvas -/en-US/docs/HTML/Element/canvas-redirect-1 /en-US/docs/Web/HTML/Element/canvas -/en-US/docs/HTML/Element/caption /en-US/docs/Web/HTML/Element/caption -/en-US/docs/HTML/Element/caption-redirect-1 /en-US/docs/Web/HTML/Element/caption -/en-US/docs/HTML/Element/center /en-US/docs/Web/HTML/Element/center -/en-US/docs/HTML/Element/cite /en-US/docs/Web/HTML/Element/cite -/en-US/docs/HTML/Element/cite-redirect-1 /en-US/docs/Web/HTML/Element/cite -/en-US/docs/HTML/Element/code /en-US/docs/Web/HTML/Element/code -/en-US/docs/HTML/Element/code-redirect-1 /en-US/docs/Web/HTML/Element/code -/en-US/docs/HTML/Element/col /en-US/docs/Web/HTML/Element/col -/en-US/docs/HTML/Element/col-redirect-1 /en-US/docs/Web/HTML/Element/col -/en-US/docs/HTML/Element/colgroup /en-US/docs/Web/HTML/Element/colgroup -/en-US/docs/HTML/Element/colgroup-redirect-1 /en-US/docs/Web/HTML/Element/colgroup -/en-US/docs/HTML/Element/data /en-US/docs/Web/HTML/Element/data -/en-US/docs/HTML/Element/data-redirect-1 /en-US/docs/Web/HTML/Element/data -/en-US/docs/HTML/Element/datalist /en-US/docs/Web/HTML/Element/datalist -/en-US/docs/HTML/Element/datalist-redirect-1 /en-US/docs/Web/HTML/Element/datalist -/en-US/docs/HTML/Element/dd /en-US/docs/Web/HTML/Element/dd -/en-US/docs/HTML/Element/dd-redirect-1 /en-US/docs/Web/HTML/Element/dd -/en-US/docs/HTML/Element/del /en-US/docs/Web/HTML/Element/del -/en-US/docs/HTML/Element/del-redirect-1 /en-US/docs/Web/HTML/Element/del -/en-US/docs/HTML/Element/details /en-US/docs/Web/HTML/Element/details -/en-US/docs/HTML/Element/details-redirect-1 /en-US/docs/Web/HTML/Element/details -/en-US/docs/HTML/Element/dfn /en-US/docs/Web/HTML/Element/dfn -/en-US/docs/HTML/Element/dfn-redirect-1 /en-US/docs/Web/HTML/Element/dfn -/en-US/docs/HTML/Element/dir /en-US/docs/Web/HTML/Element/dir -/en-US/docs/HTML/Element/div /en-US/docs/Web/HTML/Element/div -/en-US/docs/HTML/Element/div-redirect-1 /en-US/docs/Web/HTML/Element/div -/en-US/docs/HTML/Element/div-redirect-2 /en-US/docs/Web/HTML/Element/div -/en-US/docs/HTML/Element/div-redirect-3 /en-US/docs/Web/HTML/Element/div -/en-US/docs/HTML/Element/dl /en-US/docs/Web/HTML/Element/dl -/en-US/docs/HTML/Element/dl-redirect-1 /en-US/docs/Web/HTML/Element/dl -/en-US/docs/HTML/Element/dt /en-US/docs/Web/HTML/Element/dt -/en-US/docs/HTML/Element/dt-redirect-1 /en-US/docs/Web/HTML/Element/dt -/en-US/docs/HTML/Element/em /en-US/docs/Web/HTML/Element/em -/en-US/docs/HTML/Element/em-redirect-1 /en-US/docs/Web/HTML/Element/em -/en-US/docs/HTML/Element/embed /en-US/docs/Web/HTML/Element/embed -/en-US/docs/HTML/Element/embed-redirect-1 /en-US/docs/Web/HTML/Element/embed -/en-US/docs/HTML/Element/fieldset /en-US/docs/Web/HTML/Element/fieldset -/en-US/docs/HTML/Element/fieldset-redirect-1 /en-US/docs/Web/HTML/Element/fieldset -/en-US/docs/HTML/Element/figcaption /en-US/docs/Web/HTML/Element/figcaption -/en-US/docs/HTML/Element/figcaption-redirect-1 /en-US/docs/Web/HTML/Element/figcaption -/en-US/docs/HTML/Element/figure /en-US/docs/Web/HTML/Element/figure -/en-US/docs/HTML/Element/figure-redirect-1 /en-US/docs/Web/HTML/Element/figure -/en-US/docs/HTML/Element/font /en-US/docs/Web/HTML/Element/font -/en-US/docs/HTML/Element/font-redirect-1 /en-US/docs/Web/HTML/Element/font -/en-US/docs/HTML/Element/footer /en-US/docs/Web/HTML/Element/footer -/en-US/docs/HTML/Element/footer-redirect-1 /en-US/docs/Web/HTML/Element/footer -/en-US/docs/HTML/Element/form /en-US/docs/Web/HTML/Element/form -/en-US/docs/HTML/Element/form-redirect-1 /en-US/docs/Web/HTML/Element/form -/en-US/docs/HTML/Element/frame /en-US/docs/Web/HTML/Element/frame -/en-US/docs/HTML/Element/frame-redirect-1 /en-US/docs/Web/HTML/Element/frame -/en-US/docs/HTML/Element/frameset /en-US/docs/Web/HTML/Element/frameset -/en-US/docs/HTML/Element/frameset-redirect-1 /en-US/docs/Web/HTML/Element/frameset -/en-US/docs/HTML/Element/h1 /en-US/docs/Web/HTML/Element/Heading_Elements -/en-US/docs/HTML/Element/h1,h2,h3,h4,h5,h6 /en-US/docs/Web/HTML/Element/Heading_Elements -/en-US/docs/HTML/Element/h1-redirect-1 /en-US/docs/Web/HTML/Element/Heading_Elements -/en-US/docs/HTML/Element/h2 /en-US/docs/Web/HTML/Element/Heading_Elements -/en-US/docs/HTML/Element/h2-redirect-1 /en-US/docs/Web/HTML/Element/Heading_Elements -/en-US/docs/HTML/Element/h3 /en-US/docs/Web/HTML/Element/Heading_Elements -/en-US/docs/HTML/Element/h3-redirect-1 /en-US/docs/Web/HTML/Element/Heading_Elements -/en-US/docs/HTML/Element/h4 /en-US/docs/Web/HTML/Element/Heading_Elements -/en-US/docs/HTML/Element/h4-redirect-1 /en-US/docs/Web/HTML/Element/Heading_Elements -/en-US/docs/HTML/Element/h5 /en-US/docs/Web/HTML/Element/Heading_Elements -/en-US/docs/HTML/Element/h5-redirect-1 /en-US/docs/Web/HTML/Element/Heading_Elements -/en-US/docs/HTML/Element/h6 /en-US/docs/Web/HTML/Element/Heading_Elements -/en-US/docs/HTML/Element/h6-redirect-1 /en-US/docs/Web/HTML/Element/Heading_Elements -/en-US/docs/HTML/Element/head /en-US/docs/Web/HTML/Element/head -/en-US/docs/HTML/Element/head-redirect-1 /en-US/docs/Web/HTML/Element/head -/en-US/docs/HTML/Element/header /en-US/docs/Web/HTML/Element/header -/en-US/docs/HTML/Element/header-redirect-1 /en-US/docs/Web/HTML/Element/header -/en-US/docs/HTML/Element/hgroup /en-US/docs/Web/HTML/Element/hgroup -/en-US/docs/HTML/Element/hgroup-redirect-1 /en-US/docs/Web/HTML/Element/hgroup -/en-US/docs/HTML/Element/hr /en-US/docs/Web/HTML/Element/hr -/en-US/docs/HTML/Element/hr-redirect-1 /en-US/docs/Web/HTML/Element/hr -/en-US/docs/HTML/Element/html /en-US/docs/Web/HTML/Element/html -/en-US/docs/HTML/Element/html-redirect-1 /en-US/docs/Web/HTML/Element/html -/en-US/docs/HTML/Element/i /en-US/docs/Web/HTML/Element/i -/en-US/docs/HTML/Element/i-redirect-1 /en-US/docs/Web/HTML/Element/i -/en-US/docs/HTML/Element/iframe /en-US/docs/Web/HTML/Element/iframe -/en-US/docs/HTML/Element/iframe-redirect-1 /en-US/docs/Web/HTML/Element/iframe -/en-US/docs/HTML/Element/ins /en-US/docs/Web/HTML/Element/ins -/en-US/docs/HTML/Element/ins-redirect-1 /en-US/docs/Web/HTML/Element/ins -/en-US/docs/HTML/Element/kbd /en-US/docs/Web/HTML/Element/kbd -/en-US/docs/HTML/Element/kbd-redirect-1 /en-US/docs/Web/HTML/Element/kbd -/en-US/docs/HTML/Element/label /en-US/docs/Web/HTML/Element/label -/en-US/docs/HTML/Element/label-redirect-1 /en-US/docs/Web/HTML/Element/label -/en-US/docs/HTML/Element/legend /en-US/docs/Web/HTML/Element/legend -/en-US/docs/HTML/Element/legend-redirect-1 /en-US/docs/Web/HTML/Element/legend -/en-US/docs/HTML/Element/li /en-US/docs/Web/HTML/Element/li -/en-US/docs/HTML/Element/li-redirect-1 /en-US/docs/Web/HTML/Element/li -/en-US/docs/HTML/Element/link /en-US/docs/Web/HTML/Element/link -/en-US/docs/HTML/Element/link-redirect-1 /en-US/docs/Web/HTML/Element/link -/en-US/docs/HTML/Element/main /en-US/docs/Web/HTML/Element/main -/en-US/docs/HTML/Element/map /en-US/docs/Web/HTML/Element/map -/en-US/docs/HTML/Element/map-redirect-1 /en-US/docs/Web/HTML/Element/map -/en-US/docs/HTML/Element/mark /en-US/docs/Web/HTML/Element/mark -/en-US/docs/HTML/Element/mark-redirect-1 /en-US/docs/Web/HTML/Element/mark -/en-US/docs/HTML/Element/marquee /en-US/docs/Web/HTML/Element/marquee -/en-US/docs/HTML/Element/marquee-redirect-1 /en-US/docs/Web/HTML/Element/marquee -/en-US/docs/HTML/Element/menu /en-US/docs/Web/HTML/Element/menu -/en-US/docs/HTML/Element/menu-redirect-1 /en-US/docs/Web/HTML/Element/menu -/en-US/docs/HTML/Element/meta /en-US/docs/Web/HTML/Element/meta -/en-US/docs/HTML/Element/meta-redirect-1 /en-US/docs/Web/HTML/Element/meta +/en-US/docs/HTML/Element/bdi /en-US/docs/Web/HTML/Reference/Elements/bdi +/en-US/docs/HTML/Element/bdi-redirect-1 /en-US/docs/Web/HTML/Reference/Elements/bdi +/en-US/docs/HTML/Element/bdo /en-US/docs/Web/HTML/Reference/Elements/bdo +/en-US/docs/HTML/Element/bdo-redirect-1 /en-US/docs/Web/HTML/Reference/Elements/bdo +/en-US/docs/HTML/Element/bgcound /en-US/docs/Web/HTML/Reference/Elements/audio +/en-US/docs/HTML/Element/bgsound /en-US/docs/Web/HTML/Reference/Elements/audio +/en-US/docs/HTML/Element/big /en-US/docs/Web/HTML/Reference/Elements/big +/en-US/docs/HTML/Element/blockquote /en-US/docs/Web/HTML/Reference/Elements/blockquote +/en-US/docs/HTML/Element/blockquote-redirect-1 /en-US/docs/Web/HTML/Reference/Elements/blockquote +/en-US/docs/HTML/Element/body /en-US/docs/Web/HTML/Reference/Elements/body +/en-US/docs/HTML/Element/body-redirect-1 /en-US/docs/Web/HTML/Reference/Elements/body +/en-US/docs/HTML/Element/br /en-US/docs/Web/HTML/Reference/Elements/br +/en-US/docs/HTML/Element/br-redirect-1 /en-US/docs/Web/HTML/Reference/Elements/br +/en-US/docs/HTML/Element/button /en-US/docs/Web/HTML/Reference/Elements/button +/en-US/docs/HTML/Element/button-redirect-1 /en-US/docs/Web/HTML/Reference/Elements/button +/en-US/docs/HTML/Element/canvas /en-US/docs/Web/HTML/Reference/Elements/canvas +/en-US/docs/HTML/Element/canvas-redirect-1 /en-US/docs/Web/HTML/Reference/Elements/canvas +/en-US/docs/HTML/Element/caption /en-US/docs/Web/HTML/Reference/Elements/caption +/en-US/docs/HTML/Element/caption-redirect-1 /en-US/docs/Web/HTML/Reference/Elements/caption +/en-US/docs/HTML/Element/center /en-US/docs/Web/HTML/Reference/Elements/center +/en-US/docs/HTML/Element/cite /en-US/docs/Web/HTML/Reference/Elements/cite +/en-US/docs/HTML/Element/cite-redirect-1 /en-US/docs/Web/HTML/Reference/Elements/cite +/en-US/docs/HTML/Element/code /en-US/docs/Web/HTML/Reference/Elements/code +/en-US/docs/HTML/Element/code-redirect-1 /en-US/docs/Web/HTML/Reference/Elements/code +/en-US/docs/HTML/Element/col /en-US/docs/Web/HTML/Reference/Elements/col +/en-US/docs/HTML/Element/col-redirect-1 /en-US/docs/Web/HTML/Reference/Elements/col +/en-US/docs/HTML/Element/colgroup /en-US/docs/Web/HTML/Reference/Elements/colgroup +/en-US/docs/HTML/Element/colgroup-redirect-1 /en-US/docs/Web/HTML/Reference/Elements/colgroup +/en-US/docs/HTML/Element/data /en-US/docs/Web/HTML/Reference/Elements/data +/en-US/docs/HTML/Element/data-redirect-1 /en-US/docs/Web/HTML/Reference/Elements/data +/en-US/docs/HTML/Element/datalist /en-US/docs/Web/HTML/Reference/Elements/datalist +/en-US/docs/HTML/Element/datalist-redirect-1 /en-US/docs/Web/HTML/Reference/Elements/datalist +/en-US/docs/HTML/Element/dd /en-US/docs/Web/HTML/Reference/Elements/dd +/en-US/docs/HTML/Element/dd-redirect-1 /en-US/docs/Web/HTML/Reference/Elements/dd +/en-US/docs/HTML/Element/del /en-US/docs/Web/HTML/Reference/Elements/del +/en-US/docs/HTML/Element/del-redirect-1 /en-US/docs/Web/HTML/Reference/Elements/del +/en-US/docs/HTML/Element/details /en-US/docs/Web/HTML/Reference/Elements/details +/en-US/docs/HTML/Element/details-redirect-1 /en-US/docs/Web/HTML/Reference/Elements/details +/en-US/docs/HTML/Element/dfn /en-US/docs/Web/HTML/Reference/Elements/dfn +/en-US/docs/HTML/Element/dfn-redirect-1 /en-US/docs/Web/HTML/Reference/Elements/dfn +/en-US/docs/HTML/Element/dir /en-US/docs/Web/HTML/Reference/Elements/dir +/en-US/docs/HTML/Element/div /en-US/docs/Web/HTML/Reference/Elements/div +/en-US/docs/HTML/Element/div-redirect-1 /en-US/docs/Web/HTML/Reference/Elements/div +/en-US/docs/HTML/Element/div-redirect-2 /en-US/docs/Web/HTML/Reference/Elements/div +/en-US/docs/HTML/Element/div-redirect-3 /en-US/docs/Web/HTML/Reference/Elements/div +/en-US/docs/HTML/Element/dl /en-US/docs/Web/HTML/Reference/Elements/dl +/en-US/docs/HTML/Element/dl-redirect-1 /en-US/docs/Web/HTML/Reference/Elements/dl +/en-US/docs/HTML/Element/dt /en-US/docs/Web/HTML/Reference/Elements/dt +/en-US/docs/HTML/Element/dt-redirect-1 /en-US/docs/Web/HTML/Reference/Elements/dt +/en-US/docs/HTML/Element/em /en-US/docs/Web/HTML/Reference/Elements/em +/en-US/docs/HTML/Element/em-redirect-1 /en-US/docs/Web/HTML/Reference/Elements/em +/en-US/docs/HTML/Element/embed /en-US/docs/Web/HTML/Reference/Elements/embed +/en-US/docs/HTML/Element/embed-redirect-1 /en-US/docs/Web/HTML/Reference/Elements/embed +/en-US/docs/HTML/Element/fieldset /en-US/docs/Web/HTML/Reference/Elements/fieldset +/en-US/docs/HTML/Element/fieldset-redirect-1 /en-US/docs/Web/HTML/Reference/Elements/fieldset +/en-US/docs/HTML/Element/figcaption /en-US/docs/Web/HTML/Reference/Elements/figcaption +/en-US/docs/HTML/Element/figcaption-redirect-1 /en-US/docs/Web/HTML/Reference/Elements/figcaption +/en-US/docs/HTML/Element/figure /en-US/docs/Web/HTML/Reference/Elements/figure +/en-US/docs/HTML/Element/figure-redirect-1 /en-US/docs/Web/HTML/Reference/Elements/figure +/en-US/docs/HTML/Element/font /en-US/docs/Web/HTML/Reference/Elements/font +/en-US/docs/HTML/Element/font-redirect-1 /en-US/docs/Web/HTML/Reference/Elements/font +/en-US/docs/HTML/Element/footer /en-US/docs/Web/HTML/Reference/Elements/footer +/en-US/docs/HTML/Element/footer-redirect-1 /en-US/docs/Web/HTML/Reference/Elements/footer +/en-US/docs/HTML/Element/form /en-US/docs/Web/HTML/Reference/Elements/form +/en-US/docs/HTML/Element/form-redirect-1 /en-US/docs/Web/HTML/Reference/Elements/form +/en-US/docs/HTML/Element/frame /en-US/docs/Web/HTML/Reference/Elements/frame +/en-US/docs/HTML/Element/frame-redirect-1 /en-US/docs/Web/HTML/Reference/Elements/frame +/en-US/docs/HTML/Element/frameset /en-US/docs/Web/HTML/Reference/Elements/frameset +/en-US/docs/HTML/Element/frameset-redirect-1 /en-US/docs/Web/HTML/Reference/Elements/frameset +/en-US/docs/HTML/Element/h1 /en-US/docs/Web/HTML/Reference/Elements/Heading_Elements +/en-US/docs/HTML/Element/h1,h2,h3,h4,h5,h6 /en-US/docs/Web/HTML/Reference/Elements/Heading_Elements +/en-US/docs/HTML/Element/h1-redirect-1 /en-US/docs/Web/HTML/Reference/Elements/Heading_Elements +/en-US/docs/HTML/Element/h2 /en-US/docs/Web/HTML/Reference/Elements/Heading_Elements +/en-US/docs/HTML/Element/h2-redirect-1 /en-US/docs/Web/HTML/Reference/Elements/Heading_Elements +/en-US/docs/HTML/Element/h3 /en-US/docs/Web/HTML/Reference/Elements/Heading_Elements +/en-US/docs/HTML/Element/h3-redirect-1 /en-US/docs/Web/HTML/Reference/Elements/Heading_Elements +/en-US/docs/HTML/Element/h4 /en-US/docs/Web/HTML/Reference/Elements/Heading_Elements +/en-US/docs/HTML/Element/h4-redirect-1 /en-US/docs/Web/HTML/Reference/Elements/Heading_Elements +/en-US/docs/HTML/Element/h5 /en-US/docs/Web/HTML/Reference/Elements/Heading_Elements +/en-US/docs/HTML/Element/h5-redirect-1 /en-US/docs/Web/HTML/Reference/Elements/Heading_Elements +/en-US/docs/HTML/Element/h6 /en-US/docs/Web/HTML/Reference/Elements/Heading_Elements +/en-US/docs/HTML/Element/h6-redirect-1 /en-US/docs/Web/HTML/Reference/Elements/Heading_Elements +/en-US/docs/HTML/Element/head /en-US/docs/Web/HTML/Reference/Elements/head +/en-US/docs/HTML/Element/head-redirect-1 /en-US/docs/Web/HTML/Reference/Elements/head +/en-US/docs/HTML/Element/header /en-US/docs/Web/HTML/Reference/Elements/header +/en-US/docs/HTML/Element/header-redirect-1 /en-US/docs/Web/HTML/Reference/Elements/header +/en-US/docs/HTML/Element/hgroup /en-US/docs/Web/HTML/Reference/Elements/hgroup +/en-US/docs/HTML/Element/hgroup-redirect-1 /en-US/docs/Web/HTML/Reference/Elements/hgroup +/en-US/docs/HTML/Element/hr /en-US/docs/Web/HTML/Reference/Elements/hr +/en-US/docs/HTML/Element/hr-redirect-1 /en-US/docs/Web/HTML/Reference/Elements/hr +/en-US/docs/HTML/Element/html /en-US/docs/Web/HTML/Reference/Elements/html +/en-US/docs/HTML/Element/html-redirect-1 /en-US/docs/Web/HTML/Reference/Elements/html +/en-US/docs/HTML/Element/i /en-US/docs/Web/HTML/Reference/Elements/i +/en-US/docs/HTML/Element/i-redirect-1 /en-US/docs/Web/HTML/Reference/Elements/i +/en-US/docs/HTML/Element/iframe /en-US/docs/Web/HTML/Reference/Elements/iframe +/en-US/docs/HTML/Element/iframe-redirect-1 /en-US/docs/Web/HTML/Reference/Elements/iframe +/en-US/docs/HTML/Element/ins /en-US/docs/Web/HTML/Reference/Elements/ins +/en-US/docs/HTML/Element/ins-redirect-1 /en-US/docs/Web/HTML/Reference/Elements/ins +/en-US/docs/HTML/Element/kbd /en-US/docs/Web/HTML/Reference/Elements/kbd +/en-US/docs/HTML/Element/kbd-redirect-1 /en-US/docs/Web/HTML/Reference/Elements/kbd +/en-US/docs/HTML/Element/label /en-US/docs/Web/HTML/Reference/Elements/label +/en-US/docs/HTML/Element/label-redirect-1 /en-US/docs/Web/HTML/Reference/Elements/label +/en-US/docs/HTML/Element/legend /en-US/docs/Web/HTML/Reference/Elements/legend +/en-US/docs/HTML/Element/legend-redirect-1 /en-US/docs/Web/HTML/Reference/Elements/legend +/en-US/docs/HTML/Element/li /en-US/docs/Web/HTML/Reference/Elements/li +/en-US/docs/HTML/Element/li-redirect-1 /en-US/docs/Web/HTML/Reference/Elements/li +/en-US/docs/HTML/Element/link /en-US/docs/Web/HTML/Reference/Elements/link +/en-US/docs/HTML/Element/link-redirect-1 /en-US/docs/Web/HTML/Reference/Elements/link +/en-US/docs/HTML/Element/main /en-US/docs/Web/HTML/Reference/Elements/main +/en-US/docs/HTML/Element/map /en-US/docs/Web/HTML/Reference/Elements/map +/en-US/docs/HTML/Element/map-redirect-1 /en-US/docs/Web/HTML/Reference/Elements/map +/en-US/docs/HTML/Element/mark /en-US/docs/Web/HTML/Reference/Elements/mark +/en-US/docs/HTML/Element/mark-redirect-1 /en-US/docs/Web/HTML/Reference/Elements/mark +/en-US/docs/HTML/Element/marquee /en-US/docs/Web/HTML/Reference/Elements/marquee +/en-US/docs/HTML/Element/marquee-redirect-1 /en-US/docs/Web/HTML/Reference/Elements/marquee +/en-US/docs/HTML/Element/menu /en-US/docs/Web/HTML/Reference/Elements/menu +/en-US/docs/HTML/Element/menu-redirect-1 /en-US/docs/Web/HTML/Reference/Elements/menu +/en-US/docs/HTML/Element/meta /en-US/docs/Web/HTML/Reference/Elements/meta +/en-US/docs/HTML/Element/meta-redirect-1 /en-US/docs/Web/HTML/Reference/Elements/meta /en-US/docs/HTML/Element/meta/Meta /en-US/docs/Web/API/HTMLMetaElement -/en-US/docs/HTML/Element/meter /en-US/docs/Web/HTML/Element/meter -/en-US/docs/HTML/Element/meter-redirect-1 /en-US/docs/Web/HTML/Element/meter -/en-US/docs/HTML/Element/nav /en-US/docs/Web/HTML/Element/nav -/en-US/docs/HTML/Element/nav-redirect-1 /en-US/docs/Web/HTML/Element/nav -/en-US/docs/HTML/Element/nobr /en-US/docs/Web/HTML/Element/nobr -/en-US/docs/HTML/Element/nobr-redirect-1 /en-US/docs/Web/HTML/Element/nobr -/en-US/docs/HTML/Element/noframes /en-US/docs/Web/HTML/Element/noframes -/en-US/docs/HTML/Element/noframes-redirect-1 /en-US/docs/Web/HTML/Element/noframes -/en-US/docs/HTML/Element/noscript /en-US/docs/Web/HTML/Element/noscript -/en-US/docs/HTML/Element/noscript-redirect-1 /en-US/docs/Web/HTML/Element/noscript -/en-US/docs/HTML/Element/object /en-US/docs/Web/HTML/Element/object -/en-US/docs/HTML/Element/object-redirect-1 /en-US/docs/Web/HTML/Element/object -/en-US/docs/HTML/Element/ol /en-US/docs/Web/HTML/Element/ol -/en-US/docs/HTML/Element/ol-redirect-1 /en-US/docs/Web/HTML/Element/ol -/en-US/docs/HTML/Element/optgroup /en-US/docs/Web/HTML/Element/optgroup -/en-US/docs/HTML/Element/optgroup-redirect-1 /en-US/docs/Web/HTML/Element/optgroup -/en-US/docs/HTML/Element/option /en-US/docs/Web/HTML/Element/option -/en-US/docs/HTML/Element/option-redirect-1 /en-US/docs/Web/HTML/Element/option -/en-US/docs/HTML/Element/output /en-US/docs/Web/HTML/Element/output -/en-US/docs/HTML/Element/output-redirect-1 /en-US/docs/Web/HTML/Element/output -/en-US/docs/HTML/Element/p /en-US/docs/Web/HTML/Element/p -/en-US/docs/HTML/Element/p-redirect-1 /en-US/docs/Web/HTML/Element/p -/en-US/docs/HTML/Element/param /en-US/docs/Web/HTML/Element/param -/en-US/docs/HTML/Element/param-redirect-1 /en-US/docs/Web/HTML/Element/param -/en-US/docs/HTML/Element/plaintext /en-US/docs/Web/HTML/Element/plaintext -/en-US/docs/HTML/Element/pre /en-US/docs/Web/HTML/Element/pre -/en-US/docs/HTML/Element/progress /en-US/docs/Web/HTML/Element/progress -/en-US/docs/HTML/Element/q /en-US/docs/Web/HTML/Element/q -/en-US/docs/HTML/Element/rp /en-US/docs/Web/HTML/Element/rp -/en-US/docs/HTML/Element/rt /en-US/docs/Web/HTML/Element/rt -/en-US/docs/HTML/Element/ruby /en-US/docs/Web/HTML/Element/ruby -/en-US/docs/HTML/Element/s /en-US/docs/Web/HTML/Element/s -/en-US/docs/HTML/Element/s_ource /en-US/docs/Web/HTML/Element/source -/en-US/docs/HTML/Element/samp /en-US/docs/Web/HTML/Element/samp -/en-US/docs/HTML/Element/script /en-US/docs/Web/HTML/Element/script -/en-US/docs/HTML/Element/script-redirect-1 /en-US/docs/Web/HTML/Element/script -/en-US/docs/HTML/Element/section /en-US/docs/Web/HTML/Element/section -/en-US/docs/HTML/Element/section-redirect-1 /en-US/docs/Web/HTML/Element/section -/en-US/docs/HTML/Element/select /en-US/docs/Web/HTML/Element/select -/en-US/docs/HTML/Element/small /en-US/docs/Web/HTML/Element/small -/en-US/docs/HTML/Element/source /en-US/docs/Web/HTML/Element/source -/en-US/docs/HTML/Element/span /en-US/docs/Web/HTML/Element/span -/en-US/docs/HTML/Element/span-redirect-1 /en-US/docs/Web/HTML/Element/span -/en-US/docs/HTML/Element/span-redirect-2 /en-US/docs/Web/HTML/Element/span -/en-US/docs/HTML/Element/span-redirect-3 /en-US/docs/Web/HTML/Element/span -/en-US/docs/HTML/Element/strike /en-US/docs/Web/HTML/Element/strike -/en-US/docs/HTML/Element/strong /en-US/docs/Web/HTML/Element/strong -/en-US/docs/HTML/Element/style /en-US/docs/Web/HTML/Element/style -/en-US/docs/HTML/Element/sub /en-US/docs/Web/HTML/Element/sub -/en-US/docs/HTML/Element/summary /en-US/docs/Web/HTML/Element/summary -/en-US/docs/HTML/Element/sup /en-US/docs/Web/HTML/Element/sup -/en-US/docs/HTML/Element/table /en-US/docs/Web/HTML/Element/table -/en-US/docs/HTML/Element/table-redirect-1 /en-US/docs/Web/HTML/Element/table -/en-US/docs/HTML/Element/tbody /en-US/docs/Web/HTML/Element/tbody -/en-US/docs/HTML/Element/tbody-redirect-1 /en-US/docs/Web/HTML/Element/tbody -/en-US/docs/HTML/Element/td /en-US/docs/Web/HTML/Element/td -/en-US/docs/HTML/Element/td-redirect-1 /en-US/docs/Web/HTML/Element/td -/en-US/docs/HTML/Element/textarea /en-US/docs/Web/HTML/Element/textarea -/en-US/docs/HTML/Element/tfoot /en-US/docs/Web/HTML/Element/tfoot -/en-US/docs/HTML/Element/th /en-US/docs/Web/HTML/Element/th -/en-US/docs/HTML/Element/thead /en-US/docs/Web/HTML/Element/thead -/en-US/docs/HTML/Element/time /en-US/docs/Web/HTML/Element/time -/en-US/docs/HTML/Element/title /en-US/docs/Web/HTML/Element/title -/en-US/docs/HTML/Element/tr /en-US/docs/Web/HTML/Element/tr -/en-US/docs/HTML/Element/track /en-US/docs/Web/HTML/Element/track -/en-US/docs/HTML/Element/tt /en-US/docs/Web/HTML/Element/tt -/en-US/docs/HTML/Element/u /en-US/docs/Web/HTML/Element/u -/en-US/docs/HTML/Element/ul /en-US/docs/Web/HTML/Element/ul -/en-US/docs/HTML/Element/var /en-US/docs/Web/HTML/Element/var -/en-US/docs/HTML/Element/video /en-US/docs/Web/HTML/Element/video -/en-US/docs/HTML/Element/wbr /en-US/docs/Web/HTML/Element/wbr -/en-US/docs/HTML/Element/xmp /en-US/docs/Web/HTML/Element/xmp -/en-US/docs/HTML/Elements/time /en-US/docs/Web/HTML/Element/time +/en-US/docs/HTML/Element/meter /en-US/docs/Web/HTML/Reference/Elements/meter +/en-US/docs/HTML/Element/meter-redirect-1 /en-US/docs/Web/HTML/Reference/Elements/meter +/en-US/docs/HTML/Element/nav /en-US/docs/Web/HTML/Reference/Elements/nav +/en-US/docs/HTML/Element/nav-redirect-1 /en-US/docs/Web/HTML/Reference/Elements/nav +/en-US/docs/HTML/Element/nobr /en-US/docs/Web/HTML/Reference/Elements/nobr +/en-US/docs/HTML/Element/nobr-redirect-1 /en-US/docs/Web/HTML/Reference/Elements/nobr +/en-US/docs/HTML/Element/noframes /en-US/docs/Web/HTML/Reference/Elements/noframes +/en-US/docs/HTML/Element/noframes-redirect-1 /en-US/docs/Web/HTML/Reference/Elements/noframes +/en-US/docs/HTML/Element/noscript /en-US/docs/Web/HTML/Reference/Elements/noscript +/en-US/docs/HTML/Element/noscript-redirect-1 /en-US/docs/Web/HTML/Reference/Elements/noscript +/en-US/docs/HTML/Element/object /en-US/docs/Web/HTML/Reference/Elements/object +/en-US/docs/HTML/Element/object-redirect-1 /en-US/docs/Web/HTML/Reference/Elements/object +/en-US/docs/HTML/Element/ol /en-US/docs/Web/HTML/Reference/Elements/ol +/en-US/docs/HTML/Element/ol-redirect-1 /en-US/docs/Web/HTML/Reference/Elements/ol +/en-US/docs/HTML/Element/optgroup /en-US/docs/Web/HTML/Reference/Elements/optgroup +/en-US/docs/HTML/Element/optgroup-redirect-1 /en-US/docs/Web/HTML/Reference/Elements/optgroup +/en-US/docs/HTML/Element/option /en-US/docs/Web/HTML/Reference/Elements/option +/en-US/docs/HTML/Element/option-redirect-1 /en-US/docs/Web/HTML/Reference/Elements/option +/en-US/docs/HTML/Element/output /en-US/docs/Web/HTML/Reference/Elements/output +/en-US/docs/HTML/Element/output-redirect-1 /en-US/docs/Web/HTML/Reference/Elements/output +/en-US/docs/HTML/Element/p /en-US/docs/Web/HTML/Reference/Elements/p +/en-US/docs/HTML/Element/p-redirect-1 /en-US/docs/Web/HTML/Reference/Elements/p +/en-US/docs/HTML/Element/param /en-US/docs/Web/HTML/Reference/Elements/param +/en-US/docs/HTML/Element/param-redirect-1 /en-US/docs/Web/HTML/Reference/Elements/param +/en-US/docs/HTML/Element/plaintext /en-US/docs/Web/HTML/Reference/Elements/plaintext +/en-US/docs/HTML/Element/pre /en-US/docs/Web/HTML/Reference/Elements/pre +/en-US/docs/HTML/Element/progress /en-US/docs/Web/HTML/Reference/Elements/progress +/en-US/docs/HTML/Element/q /en-US/docs/Web/HTML/Reference/Elements/q +/en-US/docs/HTML/Element/rp /en-US/docs/Web/HTML/Reference/Elements/rp +/en-US/docs/HTML/Element/rt /en-US/docs/Web/HTML/Reference/Elements/rt +/en-US/docs/HTML/Element/ruby /en-US/docs/Web/HTML/Reference/Elements/ruby +/en-US/docs/HTML/Element/s /en-US/docs/Web/HTML/Reference/Elements/s +/en-US/docs/HTML/Element/s_ource /en-US/docs/Web/HTML/Reference/Elements/source +/en-US/docs/HTML/Element/samp /en-US/docs/Web/HTML/Reference/Elements/samp +/en-US/docs/HTML/Element/script /en-US/docs/Web/HTML/Reference/Elements/script +/en-US/docs/HTML/Element/script-redirect-1 /en-US/docs/Web/HTML/Reference/Elements/script +/en-US/docs/HTML/Element/section /en-US/docs/Web/HTML/Reference/Elements/section +/en-US/docs/HTML/Element/section-redirect-1 /en-US/docs/Web/HTML/Reference/Elements/section +/en-US/docs/HTML/Element/select /en-US/docs/Web/HTML/Reference/Elements/select +/en-US/docs/HTML/Element/small /en-US/docs/Web/HTML/Reference/Elements/small +/en-US/docs/HTML/Element/source /en-US/docs/Web/HTML/Reference/Elements/source +/en-US/docs/HTML/Element/span /en-US/docs/Web/HTML/Reference/Elements/span +/en-US/docs/HTML/Element/span-redirect-1 /en-US/docs/Web/HTML/Reference/Elements/span +/en-US/docs/HTML/Element/span-redirect-2 /en-US/docs/Web/HTML/Reference/Elements/span +/en-US/docs/HTML/Element/span-redirect-3 /en-US/docs/Web/HTML/Reference/Elements/span +/en-US/docs/HTML/Element/strike /en-US/docs/Web/HTML/Reference/Elements/strike +/en-US/docs/HTML/Element/strong /en-US/docs/Web/HTML/Reference/Elements/strong +/en-US/docs/HTML/Element/style /en-US/docs/Web/HTML/Reference/Elements/style +/en-US/docs/HTML/Element/sub /en-US/docs/Web/HTML/Reference/Elements/sub +/en-US/docs/HTML/Element/summary /en-US/docs/Web/HTML/Reference/Elements/summary +/en-US/docs/HTML/Element/sup /en-US/docs/Web/HTML/Reference/Elements/sup +/en-US/docs/HTML/Element/table /en-US/docs/Web/HTML/Reference/Elements/table +/en-US/docs/HTML/Element/table-redirect-1 /en-US/docs/Web/HTML/Reference/Elements/table +/en-US/docs/HTML/Element/tbody /en-US/docs/Web/HTML/Reference/Elements/tbody +/en-US/docs/HTML/Element/tbody-redirect-1 /en-US/docs/Web/HTML/Reference/Elements/tbody +/en-US/docs/HTML/Element/td /en-US/docs/Web/HTML/Reference/Elements/td +/en-US/docs/HTML/Element/td-redirect-1 /en-US/docs/Web/HTML/Reference/Elements/td +/en-US/docs/HTML/Element/textarea /en-US/docs/Web/HTML/Reference/Elements/textarea +/en-US/docs/HTML/Element/tfoot /en-US/docs/Web/HTML/Reference/Elements/tfoot +/en-US/docs/HTML/Element/th /en-US/docs/Web/HTML/Reference/Elements/th +/en-US/docs/HTML/Element/thead /en-US/docs/Web/HTML/Reference/Elements/thead +/en-US/docs/HTML/Element/time /en-US/docs/Web/HTML/Reference/Elements/time +/en-US/docs/HTML/Element/title /en-US/docs/Web/HTML/Reference/Elements/title +/en-US/docs/HTML/Element/tr /en-US/docs/Web/HTML/Reference/Elements/tr +/en-US/docs/HTML/Element/track /en-US/docs/Web/HTML/Reference/Elements/track +/en-US/docs/HTML/Element/tt /en-US/docs/Web/HTML/Reference/Elements/tt +/en-US/docs/HTML/Element/u /en-US/docs/Web/HTML/Reference/Elements/u +/en-US/docs/HTML/Element/ul /en-US/docs/Web/HTML/Reference/Elements/ul +/en-US/docs/HTML/Element/var /en-US/docs/Web/HTML/Reference/Elements/var +/en-US/docs/HTML/Element/video /en-US/docs/Web/HTML/Reference/Elements/video +/en-US/docs/HTML/Element/wbr /en-US/docs/Web/HTML/Reference/Elements/wbr +/en-US/docs/HTML/Element/xmp /en-US/docs/Web/HTML/Reference/Elements/xmp +/en-US/docs/HTML/Elements/time /en-US/docs/Web/HTML/Reference/Elements/time /en-US/docs/HTML/Focus_management_in_HTML /en-US/docs/Web/API/Document/hasFocus /en-US/docs/HTML/Forms /en-US/docs/Learn_web_development/Extensions/Forms /en-US/docs/HTML/Forms/Advanced_styling_for_HTML_forms /en-US/docs/Learn_web_development/Extensions/Forms/Advanced_form_styling @@ -3875,88 +3878,88 @@ /en-US/docs/HTML/Forms/The_native_form_widgets /en-US/docs/Learn_web_development/Extensions/Forms/Basic_native_form_controls /en-US/docs/HTML/Forms_in_HTML /en-US/docs/Learn_web_development/Extensions/Forms /en-US/docs/HTML/Forms_in_HTML5 /en-US/docs/Learn_web_development/Extensions/Forms -/en-US/docs/HTML/Global_attributes /en-US/docs/Web/HTML/Global_attributes -/en-US/docs/HTML/HTML5/Constraint_validation /en-US/docs/Web/HTML/Constraint_validation +/en-US/docs/HTML/Global_attributes /en-US/docs/Web/HTML/Reference/Global_attributes +/en-US/docs/HTML/HTML5/Constraint_validation /en-US/docs/Web/HTML/Guides/Constraint_validation /en-US/docs/HTML/HTML5/Forms_in_HTML5 /en-US/docs/Learn_web_development/Extensions/Forms /en-US/docs/HTML/HTML5/HTML5_Parser /en-US/docs/Learn_web_development/Core/Structuring_content -/en-US/docs/HTML/HTML5/HTML5_Tags_List /en-US/docs/Web/HTML/Element -/en-US/docs/HTML/HTML5/HTML5_element_list /en-US/docs/Web/HTML/Element +/en-US/docs/HTML/HTML5/HTML5_Tags_List /en-US/docs/Web/HTML/Reference/Elements +/en-US/docs/HTML/HTML5/HTML5_element_list /en-US/docs/Web/HTML/Reference/Elements /en-US/docs/HTML/HTML5/Optimizing_Your_Pages_for_Speculative_Parsing /en-US/docs/Glossary/Speculative_parsing -/en-US/docs/HTML/HTML_Elements /en-US/docs/Web/HTML/Element -/en-US/docs/HTML/HTML_Elements/textarea /en-US/docs/Web/HTML/Element/textarea -/en-US/docs/HTML/HTML_Elements/textarea-redirect-1 /en-US/docs/Web/HTML/Element/textarea -/en-US/docs/HTML/HTML_Elements/tfoot /en-US/docs/Web/HTML/Element/tfoot -/en-US/docs/HTML/HTML_Elements/tfoot-redirect-1 /en-US/docs/Web/HTML/Element/tfoot -/en-US/docs/HTML/HTML_Elements/th /en-US/docs/Web/HTML/Element/th -/en-US/docs/HTML/HTML_Elements/thead /en-US/docs/Web/HTML/Element/thead -/en-US/docs/HTML/HTML_Elements/time /en-US/docs/Web/HTML/Element/time -/en-US/docs/HTML/HTML_Elements/title /en-US/docs/Web/HTML/Element/title -/en-US/docs/HTML/HTML_Elements/tr /en-US/docs/Web/HTML/Element/tr -/en-US/docs/HTML/HTML_Elements/track /en-US/docs/Web/HTML/Element/track +/en-US/docs/HTML/HTML_Elements /en-US/docs/Web/HTML/Reference/Elements +/en-US/docs/HTML/HTML_Elements/textarea /en-US/docs/Web/HTML/Reference/Elements/textarea +/en-US/docs/HTML/HTML_Elements/textarea-redirect-1 /en-US/docs/Web/HTML/Reference/Elements/textarea +/en-US/docs/HTML/HTML_Elements/tfoot /en-US/docs/Web/HTML/Reference/Elements/tfoot +/en-US/docs/HTML/HTML_Elements/tfoot-redirect-1 /en-US/docs/Web/HTML/Reference/Elements/tfoot +/en-US/docs/HTML/HTML_Elements/th /en-US/docs/Web/HTML/Reference/Elements/th +/en-US/docs/HTML/HTML_Elements/thead /en-US/docs/Web/HTML/Reference/Elements/thead +/en-US/docs/HTML/HTML_Elements/time /en-US/docs/Web/HTML/Reference/Elements/time +/en-US/docs/HTML/HTML_Elements/title /en-US/docs/Web/HTML/Reference/Elements/title +/en-US/docs/HTML/HTML_Elements/tr /en-US/docs/Web/HTML/Reference/Elements/tr +/en-US/docs/HTML/HTML_Elements/track /en-US/docs/Web/HTML/Reference/Elements/track /en-US/docs/HTML/Historical_artifacts_to_avoid /en-US/docs/Learn_web_development/Core/Structuring_content /en-US/docs/HTML/Inline_elements /en-US/docs/Glossary/Inline-level_content /en-US/docs/HTML/Intro /en-US/docs/Learn_web_development/Core/Structuring_content /en-US/docs/HTML/Introduction /en-US/docs/Learn_web_development/Core/Structuring_content /en-US/docs/HTML/Introduction_to_HTML5 /en-US/docs/Learn_web_development/Core/Structuring_content -/en-US/docs/HTML/Link_types /en-US/docs/Web/HTML/Attributes/rel +/en-US/docs/HTML/Link_types /en-US/docs/Web/HTML/Reference/Attributes/rel /en-US/docs/HTML/Manipulating_video_using_canvas /en-US/docs/Web/API/Canvas_API/Manipulating_video_using_canvas /en-US/docs/HTML/Optimizing_Your_Pages_for_Speculative_Parsing /en-US/docs/Glossary/Speculative_parsing /en-US/docs/HTML/Supported_media_formats /en-US/docs/Web/Media/Guides/Formats /en-US/docs/HTML/The_Importance_of_Correct_Commenting /en-US/docs/Learn_web_development/Core/Structuring_content/Basic_HTML_syntax#HTML_comments -/en-US/docs/HTML/Tips_for_authoring_fast-loading_HTML_pages /en-US/docs/Learn_web_development/Howto/Solve_HTML_problems/Author_fast-loading_HTML_pages +/en-US/docs/HTML/Tips_for_authoring_fast-loading_HTML_pages /en-US/docs/Web/HTML/How_to/Author_fast-loading_HTML_pages /en-US/docs/HTML/Using_HTML5_audio_and_video /en-US/docs/Learn_web_development/Core/Structuring_content/HTML_video_and_audio /en-US/docs/HTML/WebVTT /en-US/docs/Web/API/WebVTT_API -/en-US/docs/HTML/aside /en-US/docs/Web/HTML/Element/aside -/en-US/docs/HTML/tag /en-US/docs/Web/HTML/Element +/en-US/docs/HTML/aside /en-US/docs/Web/HTML/Reference/Elements/aside +/en-US/docs/HTML/tag /en-US/docs/Web/HTML/Reference/Elements /en-US/docs/HTML:Block-level_elements /en-US/docs/Glossary/Block-level_content /en-US/docs/HTML:Canvas /en-US/docs/Web/API/Canvas_API -/en-US/docs/HTML:Element /en-US/docs/Web/HTML/Element -/en-US/docs/HTML:Element:a /en-US/docs/Web/HTML/Element/a -/en-US/docs/HTML:Element:abbr /en-US/docs/Web/HTML/Element/abbr -/en-US/docs/HTML:Element:acronym /en-US/docs/Web/HTML/Element/acronym -/en-US/docs/HTML:Element:address /en-US/docs/Web/HTML/Element/address -/en-US/docs/HTML:Element:area /en-US/docs/Web/HTML/Element/area -/en-US/docs/HTML:Element:b /en-US/docs/Web/HTML/Element/b -/en-US/docs/HTML:Element:base /en-US/docs/Web/HTML/Element/base +/en-US/docs/HTML:Element /en-US/docs/Web/HTML/Reference/Elements +/en-US/docs/HTML:Element:a /en-US/docs/Web/HTML/Reference/Elements/a +/en-US/docs/HTML:Element:abbr /en-US/docs/Web/HTML/Reference/Elements/abbr +/en-US/docs/HTML:Element:acronym /en-US/docs/Web/HTML/Reference/Elements/acronym +/en-US/docs/HTML:Element:address /en-US/docs/Web/HTML/Reference/Elements/address +/en-US/docs/HTML:Element:area /en-US/docs/Web/HTML/Reference/Elements/area +/en-US/docs/HTML:Element:b /en-US/docs/Web/HTML/Reference/Elements/b +/en-US/docs/HTML:Element:base /en-US/docs/Web/HTML/Reference/Elements/base /en-US/docs/HTML:Element:basefont /en-US/docs/Web/CSS/CSS_fonts -/en-US/docs/HTML:Element:bdo /en-US/docs/Web/HTML/Element/bdo -/en-US/docs/HTML:Element:bgcound /en-US/docs/Web/HTML/Element/audio -/en-US/docs/HTML:Element:bgsound /en-US/docs/Web/HTML/Element/audio -/en-US/docs/HTML:Element:big /en-US/docs/Web/HTML/Element/big -/en-US/docs/HTML:Element:blockquote /en-US/docs/Web/HTML/Element/blockquote -/en-US/docs/HTML:Element:br /en-US/docs/Web/HTML/Element/br -/en-US/docs/HTML:Element:center /en-US/docs/Web/HTML/Element/center -/en-US/docs/HTML:Element:cite /en-US/docs/Web/HTML/Element/cite -/en-US/docs/HTML:Element:code /en-US/docs/Web/HTML/Element/code -/en-US/docs/HTML:Element:col /en-US/docs/Web/HTML/Element/col -/en-US/docs/HTML:Element:colgroup /en-US/docs/Web/HTML/Element/colgroup -/en-US/docs/HTML:Element:dd /en-US/docs/Web/HTML/Element/dd -/en-US/docs/HTML:Element:dl /en-US/docs/Web/HTML/Element/dl -/en-US/docs/HTML:Element:dt /en-US/docs/Web/HTML/Element/dt -/en-US/docs/HTML:Element:em /en-US/docs/Web/HTML/Element/em -/en-US/docs/HTML:Element:h1,h2,h3,h4,h5,h6 /en-US/docs/Web/HTML/Element/Heading_Elements -/en-US/docs/HTML:Element:hr /en-US/docs/Web/HTML/Element/hr -/en-US/docs/HTML:Element:html /en-US/docs/Web/HTML/Element/html -/en-US/docs/HTML:Element:i /en-US/docs/Web/HTML/Element/i -/en-US/docs/HTML:Element:kbd /en-US/docs/Web/HTML/Element/kbd -/en-US/docs/HTML:Element:li /en-US/docs/Web/HTML/Element/li -/en-US/docs/HTML:Element:link /en-US/docs/Web/HTML/Element/link -/en-US/docs/HTML:Element:marquee /en-US/docs/Web/HTML/Element/marquee -/en-US/docs/HTML:Element:object /en-US/docs/Web/HTML/Element/object -/en-US/docs/HTML:Element:ol /en-US/docs/Web/HTML/Element/ol -/en-US/docs/HTML:Element:p /en-US/docs/Web/HTML/Element/p -/en-US/docs/HTML:Element:q /en-US/docs/Web/HTML/Element/q -/en-US/docs/HTML:Element:s /en-US/docs/Web/HTML/Element/s -/en-US/docs/HTML:Element:samp /en-US/docs/Web/HTML/Element/samp -/en-US/docs/HTML:Element:select /en-US/docs/Web/HTML/Element/select -/en-US/docs/HTML:Element:small /en-US/docs/Web/HTML/Element/small -/en-US/docs/HTML:Element:strong /en-US/docs/Web/HTML/Element/strong -/en-US/docs/HTML:Element:tt /en-US/docs/Web/HTML/Element/tt -/en-US/docs/HTML:Element:ul /en-US/docs/Web/HTML/Element/ul +/en-US/docs/HTML:Element:bdo /en-US/docs/Web/HTML/Reference/Elements/bdo +/en-US/docs/HTML:Element:bgcound /en-US/docs/Web/HTML/Reference/Elements/audio +/en-US/docs/HTML:Element:bgsound /en-US/docs/Web/HTML/Reference/Elements/audio +/en-US/docs/HTML:Element:big /en-US/docs/Web/HTML/Reference/Elements/big +/en-US/docs/HTML:Element:blockquote /en-US/docs/Web/HTML/Reference/Elements/blockquote +/en-US/docs/HTML:Element:br /en-US/docs/Web/HTML/Reference/Elements/br +/en-US/docs/HTML:Element:center /en-US/docs/Web/HTML/Reference/Elements/center +/en-US/docs/HTML:Element:cite /en-US/docs/Web/HTML/Reference/Elements/cite +/en-US/docs/HTML:Element:code /en-US/docs/Web/HTML/Reference/Elements/code +/en-US/docs/HTML:Element:col /en-US/docs/Web/HTML/Reference/Elements/col +/en-US/docs/HTML:Element:colgroup /en-US/docs/Web/HTML/Reference/Elements/colgroup +/en-US/docs/HTML:Element:dd /en-US/docs/Web/HTML/Reference/Elements/dd +/en-US/docs/HTML:Element:dl /en-US/docs/Web/HTML/Reference/Elements/dl +/en-US/docs/HTML:Element:dt /en-US/docs/Web/HTML/Reference/Elements/dt +/en-US/docs/HTML:Element:em /en-US/docs/Web/HTML/Reference/Elements/em +/en-US/docs/HTML:Element:h1,h2,h3,h4,h5,h6 /en-US/docs/Web/HTML/Reference/Elements/Heading_Elements +/en-US/docs/HTML:Element:hr /en-US/docs/Web/HTML/Reference/Elements/hr +/en-US/docs/HTML:Element:html /en-US/docs/Web/HTML/Reference/Elements/html +/en-US/docs/HTML:Element:i /en-US/docs/Web/HTML/Reference/Elements/i +/en-US/docs/HTML:Element:kbd /en-US/docs/Web/HTML/Reference/Elements/kbd +/en-US/docs/HTML:Element:li /en-US/docs/Web/HTML/Reference/Elements/li +/en-US/docs/HTML:Element:link /en-US/docs/Web/HTML/Reference/Elements/link +/en-US/docs/HTML:Element:marquee /en-US/docs/Web/HTML/Reference/Elements/marquee +/en-US/docs/HTML:Element:object /en-US/docs/Web/HTML/Reference/Elements/object +/en-US/docs/HTML:Element:ol /en-US/docs/Web/HTML/Reference/Elements/ol +/en-US/docs/HTML:Element:p /en-US/docs/Web/HTML/Reference/Elements/p +/en-US/docs/HTML:Element:q /en-US/docs/Web/HTML/Reference/Elements/q +/en-US/docs/HTML:Element:s /en-US/docs/Web/HTML/Reference/Elements/s +/en-US/docs/HTML:Element:samp /en-US/docs/Web/HTML/Reference/Elements/samp +/en-US/docs/HTML:Element:select /en-US/docs/Web/HTML/Reference/Elements/select +/en-US/docs/HTML:Element:small /en-US/docs/Web/HTML/Reference/Elements/small +/en-US/docs/HTML:Element:strong /en-US/docs/Web/HTML/Reference/Elements/strong +/en-US/docs/HTML:Element:tt /en-US/docs/Web/HTML/Reference/Elements/tt +/en-US/docs/HTML:Element:ul /en-US/docs/Web/HTML/Reference/Elements/ul /en-US/docs/HTML:Inline_elements /en-US/docs/Glossary/Inline-level_content /en-US/docs/HTML:The_Importance_of_Correct_Commenting /en-US/docs/Learn_web_development/Core/Structuring_content/Basic_HTML_syntax#HTML_comments -/en-US/docs/HTML:tag /en-US/docs/Web/HTML/Element -/en-US/docs/HTMLElement.forceSpellCheck /en-US/docs/Web/HTML/Global_attributes/spellcheck +/en-US/docs/HTML:tag /en-US/docs/Web/HTML/Reference/Elements +/en-US/docs/HTMLElement.forceSpellCheck /en-US/docs/Web/HTML/Reference/Global_attributes/spellcheck /en-US/docs/HTMLObjectElement.type /en-US/docs/Web/API/HTMLObjectElement/type /en-US/docs/HTMLOptionElement.Option /en-US/docs/Web/API/HTMLOptionElement/Option /en-US/docs/HTMLSpanElemen /en-US/docs/Web/API/HTMLSpanElement @@ -3966,21 +3969,21 @@ /en-US/docs/HTML_in_XMLHttpRequest /en-US/docs/Web/API/XMLHttpRequest_API/HTML_in_XMLHttpRequest /en-US/docs/HTML_intro /en-US/docs/Learn_web_development/Core/Structuring_content /en-US/docs/HTTP /en-US/docs/Web/HTTP -/en-US/docs/HTTP/Access_control_CORS /en-US/docs/Web/HTTP/CORS -/en-US/docs/HTTP/Content_negotiation /en-US/docs/Web/HTTP/Content_negotiation -/en-US/docs/HTTP/HTTP_response_codes /en-US/docs/Web/HTTP/Status -/en-US/docs/HTTP/Headers /en-US/docs/Web/HTTP/Headers -/en-US/docs/HTTP/Headers/Connection /en-US/docs/Web/HTTP/Headers/Connection -/en-US/docs/HTTP/Headers/WWW-Authenticate /en-US/docs/Web/HTTP/Headers/WWW-Authenticate -/en-US/docs/HTTP/Protocol_upgrade_mechanism /en-US/docs/Web/HTTP/Protocol_upgrade_mechanism -/en-US/docs/HTTP/Response_codes /en-US/docs/Web/HTTP/Status -/en-US/docs/HTTP/X-Frame-Options /en-US/docs/Web/HTTP/Headers/X-Frame-Options -/en-US/docs/HTTP_Caching_FAQ /en-US/docs/Web/HTTP/Caching +/en-US/docs/HTTP/Access_control_CORS /en-US/docs/Web/HTTP/Guides/CORS +/en-US/docs/HTTP/Content_negotiation /en-US/docs/Web/HTTP/Guides/Content_negotiation +/en-US/docs/HTTP/HTTP_response_codes /en-US/docs/Web/HTTP/Reference/Status +/en-US/docs/HTTP/Headers /en-US/docs/Web/HTTP/Reference/Headers +/en-US/docs/HTTP/Headers/Connection /en-US/docs/Web/HTTP/Reference/Headers/Connection +/en-US/docs/HTTP/Headers/WWW-Authenticate /en-US/docs/Web/HTTP/Reference/Headers/WWW-Authenticate +/en-US/docs/HTTP/Protocol_upgrade_mechanism /en-US/docs/Web/HTTP/Guides/Protocol_upgrade_mechanism +/en-US/docs/HTTP/Response_codes /en-US/docs/Web/HTTP/Reference/Status +/en-US/docs/HTTP/X-Frame-Options /en-US/docs/Web/HTTP/Reference/Headers/X-Frame-Options +/en-US/docs/HTTP_Caching_FAQ /en-US/docs/Web/HTTP/Guides/Caching /en-US/docs/HTTP_Debugging_(Capturing_a_HTTP_log) https://firefox-source-docs.mozilla.org/networking/http/logging.html /en-US/docs/HTTP_Logging https://firefox-source-docs.mozilla.org/networking/http/logging.html -/en-US/docs/HTTP_Pipelining_FAQ /en-US/docs/Web/HTTP/Connection_management_in_HTTP_1.x +/en-US/docs/HTTP_Pipelining_FAQ /en-US/docs/Web/HTTP/Guides/Connection_management_in_HTTP_1.x /en-US/docs/HTTP_Transaction_Model /en-US/docs/Web/HTTP -/en-US/docs/HTTP_access_control /en-US/docs/Web/HTTP/CORS +/en-US/docs/HTTP_access_control /en-US/docs/Web/HTTP/Guides/CORS /en-US/docs/How_to_Turn_Off_Form_Autocompletion /en-US/docs/Web/Security/Practical_implementation_guides/Turning_off_form_autocompletion /en-US/docs/How_to_check_the_security_state_of_an_XMLHTTPRequest_over_SSL /en-US/docs/Web/API/XMLHttpRequest /en-US/docs/How_to_create_a_DOM_tree /en-US/docs/Web/API/Document_Object_Model/Using_the_Document_Object_Model @@ -3992,7 +3995,7 @@ /en-US/docs/Inbox/Advanced_layouts_with_flexbox /en-US/docs/Glossary/Flexbox /en-US/docs/Inbox/Using_flexbox_to_lay_out_web_applications /en-US/docs/Web/CSS/CSS_flexible_box_layout/Typical_use_cases_of_flexbox /en-US/docs/Inbox/Writing_a_WebSocket_server_in_Java /en-US/docs/Web/API/WebSockets_API/Writing_a_WebSocket_server_in_Java -/en-US/docs/Incorrect_MIME_Type_for_CSS_Files /en-US/docs/Web/HTTP/MIME_types +/en-US/docs/Incorrect_MIME_Type_for_CSS_Files /en-US/docs/Web/HTTP/Guides/MIME_types /en-US/docs/IndexedDB /en-US/docs/Web/API/IndexedDB_API /en-US/docs/IndexedDB/Basic_Concepts_Behind_IndexedDB /en-US/docs/Web/API/IndexedDB_API/Basic_Terminology /en-US/docs/IndexedDB/Cursor /en-US/docs/Web/API/IDBCursor @@ -4022,7 +4025,7 @@ /en-US/docs/Intro_HTML3 /en-US/docs/Learn_web_development/Core/Structuring_content /en-US/docs/Intro_HTML4 /en-US/docs/Learn_web_development/Core/Structuring_content /en-US/docs/Intro_HTML5 /en-US/docs/Learn_web_development/Core/Structuring_content -/en-US/docs/Introducing_Content_Security_Policy /en-US/docs/Web/HTTP/CSP +/en-US/docs/Introducing_Content_Security_Policy /en-US/docs/Web/HTTP/Guides/CSP /en-US/docs/Introduction_to_Object-Oriented_JavaScript /en-US/docs/Learn_web_development/Extensions/Advanced_JavaScript_objects /en-US/docs/Introduction_to_using_XPath_in_JavaScript /en-US/docs/Web/XML/XPath/Guides/Introduction_to_using_XPath_in_JavaScript /en-US/docs/JS/Glossary /en-US/docs/Glossary @@ -4034,29 +4037,29 @@ /en-US/docs/JSAPIRegExp /en-US/docs/Web /en-US/docs/JSON /en-US/docs/Glossary/JSON /en-US/docs/JavaScript /en-US/docs/Web/JavaScript -/en-US/docs/JavaScript,_the_DOM_and_the_BOM /en-US/docs/Web/JavaScript/JavaScript_technologies_overview -/en-US/docs/JavaScript/A_re-introduction_to_JavaScript /en-US/docs/Web/JavaScript/Language_overview +/en-US/docs/JavaScript,_the_DOM_and_the_BOM /en-US/docs/Web/JavaScript/Reference/JavaScript_technologies_overview +/en-US/docs/JavaScript/A_re-introduction_to_JavaScript /en-US/docs/Web/JavaScript/Guide/Language_overview /en-US/docs/JavaScript/About_JavaScript /en-US/docs/Web/JavaScript -/en-US/docs/JavaScript/Data_structures /en-US/docs/Web/JavaScript/Data_structures +/en-US/docs/JavaScript/Data_structures /en-US/docs/Web/JavaScript/Guide/Data_structures /en-US/docs/JavaScript/DedicatedWorkerGlobalScope /en-US/docs/Web/API/DedicatedWorkerGlobalScope /en-US/docs/JavaScript/Getting_Started /en-US/docs/Learn_web_development/Getting_started/Your_first_website/Adding_interactivity /en-US/docs/JavaScript/Glossary /en-US/docs/Glossary /en-US/docs/JavaScript/Guide /en-US/docs/Web/JavaScript/Guide /en-US/docs/JavaScript/Guide/About /en-US/docs/Web/JavaScript/Guide/Introduction -/en-US/docs/JavaScript/Guide/Closures /en-US/docs/Web/JavaScript/Closures -/en-US/docs/JavaScript/Guide/Details_of_the_Object_Model /en-US/docs/Web/JavaScript/Inheritance_and_the_prototype_chain -/en-US/docs/JavaScript/Guide/EventLoop /en-US/docs/Web/JavaScript/Event_loop +/en-US/docs/JavaScript/Guide/Closures /en-US/docs/Web/JavaScript/Guide/Closures +/en-US/docs/JavaScript/Guide/Details_of_the_Object_Model /en-US/docs/Web/JavaScript/Guide/Inheritance_and_the_prototype_chain +/en-US/docs/JavaScript/Guide/EventLoop /en-US/docs/Web/JavaScript/Reference/Execution_model /en-US/docs/JavaScript/Guide/Expressions_and_Operators /en-US/docs/Web/JavaScript/Guide/Expressions_and_operators /en-US/docs/JavaScript/Guide/Functions /en-US/docs/Web/JavaScript/Guide/Functions -/en-US/docs/JavaScript/Guide/Inheritance_Revisited /en-US/docs/Web/JavaScript/Inheritance_and_the_prototype_chain -/en-US/docs/JavaScript/Guide/Inheritance_and_the_prototype_chain /en-US/docs/Web/JavaScript/Inheritance_and_the_prototype_chain -/en-US/docs/JavaScript/Guide/Inheritance_constructor_prototype /en-US/docs/Web/JavaScript/Inheritance_and_the_prototype_chain +/en-US/docs/JavaScript/Guide/Inheritance_Revisited /en-US/docs/Web/JavaScript/Guide/Inheritance_and_the_prototype_chain +/en-US/docs/JavaScript/Guide/Inheritance_and_the_prototype_chain /en-US/docs/Web/JavaScript/Guide/Inheritance_and_the_prototype_chain +/en-US/docs/JavaScript/Guide/Inheritance_constructor_prototype /en-US/docs/Web/JavaScript/Guide/Inheritance_and_the_prototype_chain /en-US/docs/JavaScript/Guide/Iterators_and_Generators /en-US/docs/Web/JavaScript/Guide/Iterators_and_generators /en-US/docs/JavaScript/Guide/JavaScript_Overview /en-US/docs/Web/JavaScript/Guide/Introduction /en-US/docs/JavaScript/Guide/Obsolete_Pages /en-US/docs/Web/JavaScript/Guide /en-US/docs/JavaScript/Guide/Obsolete_Pages/Block_Statement /en-US/docs/Web/JavaScript/Guide/Control_flow_and_error_handling /en-US/docs/JavaScript/Guide/Obsolete_Pages/Calling_Functions /en-US/docs/Web/JavaScript/Guide/Functions -/en-US/docs/JavaScript/Guide/Obsolete_Pages/Class-Based_vs._Prototype-Based_Languages /en-US/docs/Web/JavaScript/Inheritance_and_the_prototype_chain +/en-US/docs/JavaScript/Guide/Obsolete_Pages/Class-Based_vs._Prototype-Based_Languages /en-US/docs/Web/JavaScript/Guide/Inheritance_and_the_prototype_chain /en-US/docs/JavaScript/Guide/Obsolete_Pages/Comments /en-US/docs/Web/JavaScript/Guide/Control_flow_and_error_handling /en-US/docs/JavaScript/Guide/Obsolete_Pages/Conditional_Statements /en-US/docs/Web/JavaScript/Guide/Control_flow_and_error_handling /en-US/docs/JavaScript/Guide/Obsolete_Pages/Constants /en-US/docs/Web/JavaScript/Guide/Grammar_and_types @@ -4109,19 +4112,19 @@ /en-US/docs/JavaScript/Guide/Obsolete_Pages/Predefined_Functions/isFinite_Function /en-US/docs/Web/JavaScript/Guide/Functions /en-US/docs/JavaScript/Guide/Obsolete_Pages/Predefined_Functions/isNaN_Function /en-US/docs/Web/JavaScript/Guide/Functions /en-US/docs/JavaScript/Guide/Obsolete_Pages/Predefined_Functions/parseInt_and_parseFloat_Functions /en-US/docs/Web/JavaScript/Guide/Functions -/en-US/docs/JavaScript/Guide/Obsolete_Pages/Property_Inheritance_Revisited /en-US/docs/Web/JavaScript/Inheritance_and_the_prototype_chain -/en-US/docs/JavaScript/Guide/Obsolete_Pages/Property_Inheritance_Revisited/Determining_Instance_Relationships /en-US/docs/Web/JavaScript/Inheritance_and_the_prototype_chain -/en-US/docs/JavaScript/Guide/Obsolete_Pages/Property_Inheritance_Revisited/Global_Information_in_Constructors /en-US/docs/Web/JavaScript/Inheritance_and_the_prototype_chain -/en-US/docs/JavaScript/Guide/Obsolete_Pages/Property_Inheritance_Revisited/Local_versus_Inherited_Values /en-US/docs/Web/JavaScript/Inheritance_and_the_prototype_chain -/en-US/docs/JavaScript/Guide/Obsolete_Pages/Property_Inheritance_Revisited/No_Multiple_Inheritance /en-US/docs/Web/JavaScript/Inheritance_and_the_prototype_chain +/en-US/docs/JavaScript/Guide/Obsolete_Pages/Property_Inheritance_Revisited /en-US/docs/Web/JavaScript/Guide/Inheritance_and_the_prototype_chain +/en-US/docs/JavaScript/Guide/Obsolete_Pages/Property_Inheritance_Revisited/Determining_Instance_Relationships /en-US/docs/Web/JavaScript/Guide/Inheritance_and_the_prototype_chain +/en-US/docs/JavaScript/Guide/Obsolete_Pages/Property_Inheritance_Revisited/Global_Information_in_Constructors /en-US/docs/Web/JavaScript/Guide/Inheritance_and_the_prototype_chain +/en-US/docs/JavaScript/Guide/Obsolete_Pages/Property_Inheritance_Revisited/Local_versus_Inherited_Values /en-US/docs/Web/JavaScript/Guide/Inheritance_and_the_prototype_chain +/en-US/docs/JavaScript/Guide/Obsolete_Pages/Property_Inheritance_Revisited/No_Multiple_Inheritance /en-US/docs/Web/JavaScript/Guide/Inheritance_and_the_prototype_chain /en-US/docs/JavaScript/Guide/Obsolete_Pages/Table_of_Contents_1.0 /en-US/docs/Web/JavaScript/Guide /en-US/docs/JavaScript/Guide/Obsolete_Pages/Table_of_Contents_2.0 /en-US/docs/Web/JavaScript/Guide -/en-US/docs/JavaScript/Guide/Obsolete_Pages/The_Employee_Example /en-US/docs/Web/JavaScript/Inheritance_and_the_prototype_chain -/en-US/docs/JavaScript/Guide/Obsolete_Pages/The_Employee_Example/Creating_the_Hierarchy /en-US/docs/Web/JavaScript/Inheritance_and_the_prototype_chain -/en-US/docs/JavaScript/Guide/Obsolete_Pages/The_Employee_Example/More_Flexible_Constructors /en-US/docs/Web/JavaScript/Inheritance_and_the_prototype_chain -/en-US/docs/JavaScript/Guide/Obsolete_Pages/The_Employee_Example/Object_Properties /en-US/docs/Web/JavaScript/Inheritance_and_the_prototype_chain -/en-US/docs/JavaScript/Guide/Obsolete_Pages/The_Employee_Example/Object_Properties/Adding_Properties /en-US/docs/Web/JavaScript/Inheritance_and_the_prototype_chain -/en-US/docs/JavaScript/Guide/Obsolete_Pages/The_Employee_Example/Object_Properties/Inheriting_Properties /en-US/docs/Web/JavaScript/Inheritance_and_the_prototype_chain +/en-US/docs/JavaScript/Guide/Obsolete_Pages/The_Employee_Example /en-US/docs/Web/JavaScript/Guide/Inheritance_and_the_prototype_chain +/en-US/docs/JavaScript/Guide/Obsolete_Pages/The_Employee_Example/Creating_the_Hierarchy /en-US/docs/Web/JavaScript/Guide/Inheritance_and_the_prototype_chain +/en-US/docs/JavaScript/Guide/Obsolete_Pages/The_Employee_Example/More_Flexible_Constructors /en-US/docs/Web/JavaScript/Guide/Inheritance_and_the_prototype_chain +/en-US/docs/JavaScript/Guide/Obsolete_Pages/The_Employee_Example/Object_Properties /en-US/docs/Web/JavaScript/Guide/Inheritance_and_the_prototype_chain +/en-US/docs/JavaScript/Guide/Obsolete_Pages/The_Employee_Example/Object_Properties/Adding_Properties /en-US/docs/Web/JavaScript/Guide/Inheritance_and_the_prototype_chain +/en-US/docs/JavaScript/Guide/Obsolete_Pages/The_Employee_Example/Object_Properties/Inheriting_Properties /en-US/docs/Web/JavaScript/Guide/Inheritance_and_the_prototype_chain /en-US/docs/JavaScript/Guide/Obsolete_Pages/Unicode /en-US/docs/Web/JavaScript/Guide/Grammar_and_types /en-US/docs/JavaScript/Guide/Obsolete_Pages/Using_the_arguments_object /en-US/docs/Web/JavaScript/Guide/Functions /en-US/docs/JavaScript/Guide/Obsolete_Pages/Values /en-US/docs/Web/JavaScript/Guide/Grammar_and_types @@ -4142,10 +4145,10 @@ /en-US/docs/JavaScript/Guide/Working_with_Arrays /en-US/docs/Web/JavaScript/Guide /en-US/docs/JavaScript/Guide/Working_with_Objects /en-US/docs/Web/JavaScript/Guide/Working_with_objects /en-US/docs/JavaScript/Introduction_to_Object-Oriented_JavaScript /en-US/docs/Learn_web_development/Extensions/Advanced_JavaScript_objects -/en-US/docs/JavaScript/JavaScript_technologies_overview /en-US/docs/Web/JavaScript/JavaScript_technologies_overview +/en-US/docs/JavaScript/JavaScript_technologies_overview /en-US/docs/Web/JavaScript/Reference/JavaScript_technologies_overview /en-US/docs/JavaScript/Javascript_How_To_Tutorials /en-US/docs/Web/JavaScript/Guide -/en-US/docs/JavaScript/Language_Resources /en-US/docs/Web/JavaScript/JavaScript_technologies_overview -/en-US/docs/JavaScript/Memory_Management /en-US/docs/Web/JavaScript/Memory_management +/en-US/docs/JavaScript/Language_Resources /en-US/docs/Web/JavaScript/Reference/JavaScript_technologies_overview +/en-US/docs/JavaScript/Memory_Management /en-US/docs/Web/JavaScript/Guide/Memory_management /en-US/docs/JavaScript/Other_JavaScript_tools https://firefox-source-docs.mozilla.org/devtools-user/index.html /en-US/docs/JavaScript/Reference /en-US/docs/Web/JavaScript/Reference /en-US/docs/JavaScript/Reference/About /en-US/docs/Web/JavaScript/Reference @@ -4683,7 +4686,7 @@ /en-US/docs/JavaScript/Reference/default_parameters /en-US/docs/Web/JavaScript/Reference/Functions/Default_parameters /en-US/docs/JavaScript/Reference/rest_parameters /en-US/docs/Web/JavaScript/Reference/Functions/rest_parameters /en-US/docs/JavaScript/Same_origin_policy_for_JavaScript /en-US/docs/Web/Security/Same-origin_policy -/en-US/docs/JavaScript/Shells /en-US/docs/Web/JavaScript/JavaScript_technologies_overview +/en-US/docs/JavaScript/Shells /en-US/docs/Web/JavaScript/Reference/JavaScript_technologies_overview /en-US/docs/JavaScript/Strict_mode /en-US/docs/Web/JavaScript/Reference/Strict_mode /en-US/docs/JavaScript/Typed_arrays /en-US/docs/Web/JavaScript/Guide/Typed_arrays /en-US/docs/JavaScript/Typed_arrays/ArrayBuffer /en-US/docs/Web/JavaScript/Reference/Global_Objects/ArrayBuffer @@ -4703,25 +4706,25 @@ /en-US/docs/JavaScript_API/navigator.mozApps.mgmt.addEventListener /en-US/docs/Web/API/EventTarget/addEventListener /en-US/docs/JavaScript_API/navigator.mozApps.mgmt.removeEventListener /en-US/docs/Web/API/EventTarget/removeEventListener /en-US/docs/JavaScript_Documention /en-US/docs/Web/JavaScript -/en-US/docs/JavaScript_Documention/A_re-introduction_to_JavaScript /en-US/docs/Web/JavaScript/Language_overview +/en-US/docs/JavaScript_Documention/A_re-introduction_to_JavaScript /en-US/docs/Web/JavaScript/Guide/Language_overview /en-US/docs/JavaScript_Documention/About_JavaScript /en-US/docs/Web/JavaScript -/en-US/docs/JavaScript_Documention/Data_structures /en-US/docs/Web/JavaScript/Data_structures +/en-US/docs/JavaScript_Documention/Data_structures /en-US/docs/Web/JavaScript/Guide/Data_structures /en-US/docs/JavaScript_Documention/Getting_Started /en-US/docs/Learn_web_development/Getting_started/Your_first_website/Adding_interactivity /en-US/docs/JavaScript_Documention/Glossary /en-US/docs/Glossary /en-US/docs/JavaScript_Documention/Guide /en-US/docs/Web/JavaScript/Guide /en-US/docs/JavaScript_Documention/Guide/About /en-US/docs/Web/JavaScript/Guide/Introduction -/en-US/docs/JavaScript_Documention/Guide/Closures /en-US/docs/Web/JavaScript/Closures -/en-US/docs/JavaScript_Documention/Guide/Details_of_the_Object_Model /en-US/docs/Web/JavaScript/Inheritance_and_the_prototype_chain +/en-US/docs/JavaScript_Documention/Guide/Closures /en-US/docs/Web/JavaScript/Guide/Closures +/en-US/docs/JavaScript_Documention/Guide/Details_of_the_Object_Model /en-US/docs/Web/JavaScript/Guide/Inheritance_and_the_prototype_chain /en-US/docs/JavaScript_Documention/Guide/Expressions_and_Operators /en-US/docs/Web/JavaScript/Guide/Expressions_and_operators /en-US/docs/JavaScript_Documention/Guide/Functions /en-US/docs/Web/JavaScript/Guide/Functions -/en-US/docs/JavaScript_Documention/Guide/Inheritance_Revisited /en-US/docs/Web/JavaScript/Inheritance_and_the_prototype_chain -/en-US/docs/JavaScript_Documention/Guide/Inheritance_and_the_prototype_chain /en-US/docs/Web/JavaScript/Inheritance_and_the_prototype_chain +/en-US/docs/JavaScript_Documention/Guide/Inheritance_Revisited /en-US/docs/Web/JavaScript/Guide/Inheritance_and_the_prototype_chain +/en-US/docs/JavaScript_Documention/Guide/Inheritance_and_the_prototype_chain /en-US/docs/Web/JavaScript/Guide/Inheritance_and_the_prototype_chain /en-US/docs/JavaScript_Documention/Guide/Iterators_and_Generators /en-US/docs/Web/JavaScript/Guide/Iterators_and_generators /en-US/docs/JavaScript_Documention/Guide/JavaScript_Overview /en-US/docs/Web/JavaScript/Guide/Introduction /en-US/docs/JavaScript_Documention/Guide/Obsolete_Pages /en-US/docs/Web/JavaScript/Guide /en-US/docs/JavaScript_Documention/Guide/Obsolete_Pages/Block_Statement /en-US/docs/Web/JavaScript/Guide/Control_flow_and_error_handling /en-US/docs/JavaScript_Documention/Guide/Obsolete_Pages/Calling_Functions /en-US/docs/Web/JavaScript/Guide/Functions -/en-US/docs/JavaScript_Documention/Guide/Obsolete_Pages/Class-Based_vs._Prototype-Based_Languages /en-US/docs/Web/JavaScript/Inheritance_and_the_prototype_chain +/en-US/docs/JavaScript_Documention/Guide/Obsolete_Pages/Class-Based_vs._Prototype-Based_Languages /en-US/docs/Web/JavaScript/Guide/Inheritance_and_the_prototype_chain /en-US/docs/JavaScript_Documention/Guide/Obsolete_Pages/Comments /en-US/docs/Web/JavaScript/Guide/Control_flow_and_error_handling /en-US/docs/JavaScript_Documention/Guide/Obsolete_Pages/Conditional_Statements /en-US/docs/Web/JavaScript/Guide/Control_flow_and_error_handling /en-US/docs/JavaScript_Documention/Guide/Obsolete_Pages/Constants /en-US/docs/Web/JavaScript/Guide/Grammar_and_types @@ -4774,19 +4777,19 @@ /en-US/docs/JavaScript_Documention/Guide/Obsolete_Pages/Predefined_Functions/isFinite_Function /en-US/docs/Web/JavaScript/Guide/Functions /en-US/docs/JavaScript_Documention/Guide/Obsolete_Pages/Predefined_Functions/isNaN_Function /en-US/docs/Web/JavaScript/Guide/Functions /en-US/docs/JavaScript_Documention/Guide/Obsolete_Pages/Predefined_Functions/parseInt_and_parseFloat_Functions /en-US/docs/Web/JavaScript/Guide/Functions -/en-US/docs/JavaScript_Documention/Guide/Obsolete_Pages/Property_Inheritance_Revisited /en-US/docs/Web/JavaScript/Inheritance_and_the_prototype_chain -/en-US/docs/JavaScript_Documention/Guide/Obsolete_Pages/Property_Inheritance_Revisited/Determining_Instance_Relationships /en-US/docs/Web/JavaScript/Inheritance_and_the_prototype_chain -/en-US/docs/JavaScript_Documention/Guide/Obsolete_Pages/Property_Inheritance_Revisited/Global_Information_in_Constructors /en-US/docs/Web/JavaScript/Inheritance_and_the_prototype_chain -/en-US/docs/JavaScript_Documention/Guide/Obsolete_Pages/Property_Inheritance_Revisited/Local_versus_Inherited_Values /en-US/docs/Web/JavaScript/Inheritance_and_the_prototype_chain -/en-US/docs/JavaScript_Documention/Guide/Obsolete_Pages/Property_Inheritance_Revisited/No_Multiple_Inheritance /en-US/docs/Web/JavaScript/Inheritance_and_the_prototype_chain +/en-US/docs/JavaScript_Documention/Guide/Obsolete_Pages/Property_Inheritance_Revisited /en-US/docs/Web/JavaScript/Guide/Inheritance_and_the_prototype_chain +/en-US/docs/JavaScript_Documention/Guide/Obsolete_Pages/Property_Inheritance_Revisited/Determining_Instance_Relationships /en-US/docs/Web/JavaScript/Guide/Inheritance_and_the_prototype_chain +/en-US/docs/JavaScript_Documention/Guide/Obsolete_Pages/Property_Inheritance_Revisited/Global_Information_in_Constructors /en-US/docs/Web/JavaScript/Guide/Inheritance_and_the_prototype_chain +/en-US/docs/JavaScript_Documention/Guide/Obsolete_Pages/Property_Inheritance_Revisited/Local_versus_Inherited_Values /en-US/docs/Web/JavaScript/Guide/Inheritance_and_the_prototype_chain +/en-US/docs/JavaScript_Documention/Guide/Obsolete_Pages/Property_Inheritance_Revisited/No_Multiple_Inheritance /en-US/docs/Web/JavaScript/Guide/Inheritance_and_the_prototype_chain /en-US/docs/JavaScript_Documention/Guide/Obsolete_Pages/Table_of_Contents_1.0 /en-US/docs/Web/JavaScript/Guide /en-US/docs/JavaScript_Documention/Guide/Obsolete_Pages/Table_of_Contents_2.0 /en-US/docs/Web/JavaScript/Guide -/en-US/docs/JavaScript_Documention/Guide/Obsolete_Pages/The_Employee_Example /en-US/docs/Web/JavaScript/Inheritance_and_the_prototype_chain -/en-US/docs/JavaScript_Documention/Guide/Obsolete_Pages/The_Employee_Example/Creating_the_Hierarchy /en-US/docs/Web/JavaScript/Inheritance_and_the_prototype_chain -/en-US/docs/JavaScript_Documention/Guide/Obsolete_Pages/The_Employee_Example/More_Flexible_Constructors /en-US/docs/Web/JavaScript/Inheritance_and_the_prototype_chain -/en-US/docs/JavaScript_Documention/Guide/Obsolete_Pages/The_Employee_Example/Object_Properties /en-US/docs/Web/JavaScript/Inheritance_and_the_prototype_chain -/en-US/docs/JavaScript_Documention/Guide/Obsolete_Pages/The_Employee_Example/Object_Properties/Adding_Properties /en-US/docs/Web/JavaScript/Inheritance_and_the_prototype_chain -/en-US/docs/JavaScript_Documention/Guide/Obsolete_Pages/The_Employee_Example/Object_Properties/Inheriting_Properties /en-US/docs/Web/JavaScript/Inheritance_and_the_prototype_chain +/en-US/docs/JavaScript_Documention/Guide/Obsolete_Pages/The_Employee_Example /en-US/docs/Web/JavaScript/Guide/Inheritance_and_the_prototype_chain +/en-US/docs/JavaScript_Documention/Guide/Obsolete_Pages/The_Employee_Example/Creating_the_Hierarchy /en-US/docs/Web/JavaScript/Guide/Inheritance_and_the_prototype_chain +/en-US/docs/JavaScript_Documention/Guide/Obsolete_Pages/The_Employee_Example/More_Flexible_Constructors /en-US/docs/Web/JavaScript/Guide/Inheritance_and_the_prototype_chain +/en-US/docs/JavaScript_Documention/Guide/Obsolete_Pages/The_Employee_Example/Object_Properties /en-US/docs/Web/JavaScript/Guide/Inheritance_and_the_prototype_chain +/en-US/docs/JavaScript_Documention/Guide/Obsolete_Pages/The_Employee_Example/Object_Properties/Adding_Properties /en-US/docs/Web/JavaScript/Guide/Inheritance_and_the_prototype_chain +/en-US/docs/JavaScript_Documention/Guide/Obsolete_Pages/The_Employee_Example/Object_Properties/Inheriting_Properties /en-US/docs/Web/JavaScript/Guide/Inheritance_and_the_prototype_chain /en-US/docs/JavaScript_Documention/Guide/Obsolete_Pages/Unicode /en-US/docs/Web/JavaScript/Guide/Grammar_and_types /en-US/docs/JavaScript_Documention/Guide/Obsolete_Pages/Using_the_arguments_object /en-US/docs/Web/JavaScript/Guide/Functions /en-US/docs/JavaScript_Documention/Guide/Obsolete_Pages/Values /en-US/docs/Web/JavaScript/Guide/Grammar_and_types @@ -4804,8 +4807,8 @@ /en-US/docs/JavaScript_Documention/Guide/Working_with_Objects /en-US/docs/Web/JavaScript/Guide/Working_with_objects /en-US/docs/JavaScript_Documention/Introduction_to_Object-Oriented_JavaScript /en-US/docs/Learn_web_development/Extensions/Advanced_JavaScript_objects /en-US/docs/JavaScript_Documention/Javascript_How_To_Tutorials /en-US/docs/Web/JavaScript/Guide -/en-US/docs/JavaScript_Documention/Language_Resources /en-US/docs/Web/JavaScript/JavaScript_technologies_overview -/en-US/docs/JavaScript_Documention/Memory_Management /en-US/docs/Web/JavaScript/Memory_management +/en-US/docs/JavaScript_Documention/Language_Resources /en-US/docs/Web/JavaScript/Reference/JavaScript_technologies_overview +/en-US/docs/JavaScript_Documention/Memory_Management /en-US/docs/Web/JavaScript/Guide/Memory_management /en-US/docs/JavaScript_Documention/Other_JavaScript_tools https://firefox-source-docs.mozilla.org/devtools-user/index.html /en-US/docs/JavaScript_Documention/Reference /en-US/docs/Web/JavaScript/Reference /en-US/docs/JavaScript_Documention/Reference/About /en-US/docs/Web/JavaScript/Reference @@ -5122,13 +5125,13 @@ /en-US/docs/JavaScript_Documention/Reference/Statements/with /en-US/docs/Web/JavaScript/Reference/Statements/with /en-US/docs/JavaScript_Documention/Reference/Symbols /en-US/docs/Web/JavaScript/Reference/Global_Objects/Symbol /en-US/docs/JavaScript_Documention/Reference/rest_parameters /en-US/docs/Web/JavaScript/Reference/Functions/rest_parameters -/en-US/docs/JavaScript_Documention/Shells /en-US/docs/Web/JavaScript/JavaScript_technologies_overview -/en-US/docs/JavaScript_Language_Resources /en-US/docs/Web/JavaScript/JavaScript_technologies_overview +/en-US/docs/JavaScript_Documention/Shells /en-US/docs/Web/JavaScript/Reference/JavaScript_technologies_overview +/en-US/docs/JavaScript_Language_Resources /en-US/docs/Web/JavaScript/Reference/JavaScript_technologies_overview /en-US/docs/JavaScript_Methods_Index /en-US/docs/Web/JavaScript/Reference /en-US/docs/JavaScript_Methods_Index_(Alphabetical) /en-US/docs/Web/JavaScript/Reference /en-US/docs/JavaScript_Properties_Index /en-US/docs/Web/JavaScript/Reference -/en-US/docs/JavaScript_shells /en-US/docs/Web/JavaScript/JavaScript_technologies_overview -/en-US/docs/JavaScript_technologies_overview /en-US/docs/Web/JavaScript/JavaScript_technologies_overview +/en-US/docs/JavaScript_shells /en-US/docs/Web/JavaScript/Reference/JavaScript_technologies_overview +/en-US/docs/JavaScript_technologies_overview /en-US/docs/Web/JavaScript/Reference/JavaScript_technologies_overview /en-US/docs/JavaScript_templates /en-US/docs/Web/JavaScript/Reference/Template_literals /en-US/docs/JavaScript_typed_arrays /en-US/docs/Web/JavaScript/Guide/Typed_arrays /en-US/docs/JavaScript_typed_arrays/ArrayBuffer /en-US/docs/Web/JavaScript/Reference/Global_Objects/ArrayBuffer @@ -5146,13 +5149,13 @@ /en-US/docs/Learn/Accessibility /en-US/docs/Learn_web_development/Core/Accessibility /en-US/docs/Learn/Accessibility/Accessibility_troubleshooting /en-US/docs/Learn_web_development/Core/Accessibility/Accessibility_troubleshooting /en-US/docs/Learn/Accessibility/CSS_and_JavaScript /en-US/docs/Learn_web_development/Core/Accessibility/CSS_and_JavaScript -/en-US/docs/Learn/Accessibility/CSS_and_JavaScript/Test_your_skills:_CSS_and_JavaScript_accessibility /en-US/docs/Learn_web_development/Core/Accessibility/CSS_and_JavaScript/Test_your_skills:_CSS_and_JavaScript_accessibility +/en-US/docs/Learn/Accessibility/CSS_and_JavaScript/Test_your_skills:_CSS_and_JavaScript_accessibility /en-US/docs/Learn_web_development/Core/Accessibility/Test_your_skills/CSS_and_JavaScript /en-US/docs/Learn/Accessibility/HTML /en-US/docs/Learn_web_development/Core/Accessibility/HTML /en-US/docs/Learn/Accessibility/Mobile /en-US/docs/Learn_web_development/Core/Accessibility/Mobile /en-US/docs/Learn/Accessibility/Multimedia /en-US/docs/Learn_web_development/Core/Accessibility/Multimedia -/en-US/docs/Learn/Accessibility/Test_your_skills:_HTML_accessibility /en-US/docs/Learn_web_development/Core/Accessibility/Test_your_skills:_HTML_accessibility +/en-US/docs/Learn/Accessibility/Test_your_skills:_HTML_accessibility /en-US/docs/Learn_web_development/Core/Accessibility/Test_your_skills/HTML /en-US/docs/Learn/Accessibility/WAI-ARIA_basics /en-US/docs/Learn_web_development/Core/Accessibility/WAI-ARIA_basics -/en-US/docs/Learn/Accessibility/WAI-ARIA_basics/Test_your_skills:_WAI-ARIA /en-US/docs/Learn_web_development/Core/Accessibility/WAI-ARIA_basics/Test_your_skills:_WAI-ARIA +/en-US/docs/Learn/Accessibility/WAI-ARIA_basics/Test_your_skills:_WAI-ARIA /en-US/docs/Learn_web_development/Core/Accessibility/Test_your_skills/WAI-ARIA /en-US/docs/Learn/Accessibility/What_is_accessibility /en-US/docs/Learn_web_development/Core/Accessibility/What_is_accessibility /en-US/docs/Learn/Advanced_layouts_with_flexbox /en-US/docs/Glossary/Flexbox /en-US/docs/Learn/Anatomy_of_a_web_page /en-US/docs/Learn_web_development/Howto/Design_and_accessibility/Common_web_layouts @@ -5169,57 +5172,57 @@ /en-US/docs/Learn/CSS/Building_blocks/A_cool_looking_box /en-US/docs/Learn_web_development/Core/Styling_basics/Cool-looking_box /en-US/docs/Learn/CSS/Building_blocks/Advanced_styling_effects /en-US/docs/Learn_web_development/Core/Styling_basics/Advanced_styling_effects /en-US/docs/Learn/CSS/Building_blocks/Backgrounds_and_borders /en-US/docs/Learn_web_development/Core/Styling_basics/Backgrounds_and_borders -/en-US/docs/Learn/CSS/Building_blocks/Box_Model_Tasks /en-US/docs/Learn_web_development/Core/Styling_basics/Box_Model_Tasks +/en-US/docs/Learn/CSS/Building_blocks/Box_Model_Tasks /en-US/docs/Learn_web_development/Core/Styling_basics/Test_your_skills/Box_model /en-US/docs/Learn/CSS/Building_blocks/Cascade_and_inheritance /en-US/docs/Learn_web_development/Core/Styling_basics/Handling_conflicts /en-US/docs/Learn/CSS/Building_blocks/Cascade_layers /en-US/docs/Learn_web_development/Core/Styling_basics/Cascade_layers -/en-US/docs/Learn/CSS/Building_blocks/Cascade_tasks /en-US/docs/Learn_web_development/Core/Styling_basics/Cascade_tasks +/en-US/docs/Learn/CSS/Building_blocks/Cascade_tasks /en-US/docs/Learn_web_development/Core/Styling_basics/Test_your_skills/Cascade /en-US/docs/Learn/CSS/Building_blocks/Creating_fancy_letterheaded_paper /en-US/docs/Learn_web_development/Core/Styling_basics/Fancy_letterheaded_paper /en-US/docs/Learn/CSS/Building_blocks/Debugging_CSS /en-US/docs/Learn_web_development/Core/Styling_basics/Debugging_CSS /en-US/docs/Learn/CSS/Building_blocks/Fundamental_CSS_comprehension /en-US/docs/Learn_web_development/Core/Styling_basics/Fundamental_CSS_comprehension /en-US/docs/Learn/CSS/Building_blocks/Handling_different_text_directions /en-US/docs/Learn_web_development/Core/Styling_basics/Handling_different_text_directions /en-US/docs/Learn/CSS/Building_blocks/Images_media_form_elements /en-US/docs/Learn_web_development/Core/Styling_basics/Images_media_forms -/en-US/docs/Learn/CSS/Building_blocks/Images_tasks /en-US/docs/Learn_web_development/Core/Styling_basics/Images_tasks +/en-US/docs/Learn/CSS/Building_blocks/Images_tasks /en-US/docs/Learn_web_development/Core/Styling_basics/Test_your_skills/Images /en-US/docs/Learn/CSS/Building_blocks/Organizing /en-US/docs/Learn_web_development/Core/Styling_basics/Organizing -/en-US/docs/Learn/CSS/Building_blocks/Overflow_Tasks /en-US/docs/Learn_web_development/Core/Styling_basics/Overflow_Tasks +/en-US/docs/Learn/CSS/Building_blocks/Overflow_Tasks /en-US/docs/Learn_web_development/Core/Styling_basics/Test_your_skills/Overflow /en-US/docs/Learn/CSS/Building_blocks/Overflowing_content /en-US/docs/Learn_web_development/Core/Styling_basics/Overflow /en-US/docs/Learn/CSS/Building_blocks/Selectors /en-US/docs/Learn_web_development/Core/Styling_basics/Basic_selectors /en-US/docs/Learn/CSS/Building_blocks/Selectors/Attribute_selectors /en-US/docs/Learn_web_development/Core/Styling_basics/Attribute_selectors /en-US/docs/Learn/CSS/Building_blocks/Selectors/Combinators /en-US/docs/Learn_web_development/Core/Styling_basics/Combinators /en-US/docs/Learn/CSS/Building_blocks/Selectors/Pseudo-classes_and_pseudo-elements /en-US/docs/Learn_web_development/Core/Styling_basics/Pseudo_classes_and_elements /en-US/docs/Learn/CSS/Building_blocks/Selectors/Pseuso-classes_and_Pseudo-elements /en-US/docs/Learn_web_development/Core/Styling_basics/Pseudo_classes_and_elements -/en-US/docs/Learn/CSS/Building_blocks/Selectors/Selectors_Tasks /en-US/docs/Learn_web_development/Core/Styling_basics/Basic_selectors/Selectors_Tasks +/en-US/docs/Learn/CSS/Building_blocks/Selectors/Selectors_Tasks /en-US/docs/Learn_web_development/Core/Styling_basics/Test_your_skills/Selectors /en-US/docs/Learn/CSS/Building_blocks/Selectors/Type_Class_and_ID_Selectors /en-US/docs/Learn_web_development/Core/Styling_basics/Basic_selectors -/en-US/docs/Learn/CSS/Building_blocks/Selectors/Writing_Modes_Tasks /en-US/docs/Learn_web_development/Core/Styling_basics/Writing_Modes_Tasks +/en-US/docs/Learn/CSS/Building_blocks/Selectors/Writing_Modes_Tasks /en-US/docs/Learn_web_development/Core/Styling_basics/Test_your_skills/Writing_modes /en-US/docs/Learn/CSS/Building_blocks/Sizing_items_in_CSS /en-US/docs/Learn_web_development/Core/Styling_basics/Sizing -/en-US/docs/Learn/CSS/Building_blocks/Sizing_tasks /en-US/docs/Learn_web_development/Core/Styling_basics/Sizing_tasks +/en-US/docs/Learn/CSS/Building_blocks/Sizing_tasks /en-US/docs/Learn_web_development/Core/Styling_basics/Test_your_skills/Sizing /en-US/docs/Learn/CSS/Building_blocks/Styling_tables /en-US/docs/Learn_web_development/Core/Styling_basics/Tables -/en-US/docs/Learn/CSS/Building_blocks/Tables_tasks /en-US/docs/Learn_web_development/Core/Styling_basics/Tables_tasks -/en-US/docs/Learn/CSS/Building_blocks/Test_your_skills_backgrounds_and_borders /en-US/docs/Learn_web_development/Core/Styling_basics/Test_your_skills_backgrounds_and_borders +/en-US/docs/Learn/CSS/Building_blocks/Tables_tasks /en-US/docs/Learn_web_development/Core/Styling_basics/Test_your_skills/Tables +/en-US/docs/Learn/CSS/Building_blocks/Test_your_skills_backgrounds_and_borders /en-US/docs/Learn_web_development/Core/Styling_basics/Test_your_skills/Backgrounds_and_borders /en-US/docs/Learn/CSS/Building_blocks/The_box_model /en-US/docs/Learn_web_development/Core/Styling_basics/Box_model /en-US/docs/Learn/CSS/Building_blocks/Values_and_units /en-US/docs/Learn_web_development/Core/Styling_basics/Values_and_units -/en-US/docs/Learn/CSS/Building_blocks/Values_tasks /en-US/docs/Learn_web_development/Core/Styling_basics/Values_tasks -/en-US/docs/Learn/CSS/Building_blocks/Writing_Modes_Tasks /en-US/docs/Learn_web_development/Core/Styling_basics/Writing_Modes_Tasks +/en-US/docs/Learn/CSS/Building_blocks/Values_tasks /en-US/docs/Learn_web_development/Core/Styling_basics/Test_your_skills/Values +/en-US/docs/Learn/CSS/Building_blocks/Writing_Modes_Tasks /en-US/docs/Learn_web_development/Core/Styling_basics/Test_your_skills/Writing_modes /en-US/docs/Learn/CSS/CSS_layout /en-US/docs/Learn_web_development/Core/CSS_layout /en-US/docs/Learn/CSS/CSS_layout/Flexbox /en-US/docs/Learn_web_development/Core/CSS_layout/Flexbox -/en-US/docs/Learn/CSS/CSS_layout/Flexbox_skills /en-US/docs/Learn_web_development/Core/CSS_layout/Flexbox_skills +/en-US/docs/Learn/CSS/CSS_layout/Flexbox_skills /en-US/docs/Learn_web_development/Core/CSS_layout/Test_your_skills/Flexbox /en-US/docs/Learn/CSS/CSS_layout/Floats /en-US/docs/Learn_web_development/Core/CSS_layout/Floats -/en-US/docs/Learn/CSS/CSS_layout/Floats_skills /en-US/docs/Learn_web_development/Core/CSS_layout/Floats_skills +/en-US/docs/Learn/CSS/CSS_layout/Floats_skills /en-US/docs/Learn_web_development/Core/CSS_layout/Test_your_skills/Floats /en-US/docs/Learn/CSS/CSS_layout/Fundamental_Layout_Comprehension /en-US/docs/Learn_web_development/Core/CSS_layout/Fundamental_Layout_Comprehension -/en-US/docs/Learn/CSS/CSS_layout/Grid_skills /en-US/docs/Learn_web_development/Core/CSS_layout/Grid_skills +/en-US/docs/Learn/CSS/CSS_layout/Grid_skills /en-US/docs/Learn_web_development/Core/CSS_layout/Test_your_skills/Grid /en-US/docs/Learn/CSS/CSS_layout/Grids /en-US/docs/Learn_web_development/Core/CSS_layout/Grids /en-US/docs/Learn/CSS/CSS_layout/Introduction /en-US/docs/Learn_web_development/Core/CSS_layout/Introduction /en-US/docs/Learn/CSS/CSS_layout/Legacy_Layout_Methods /en-US/docs/Learn_web_development/Core/CSS_layout/Legacy_Layout_Methods /en-US/docs/Learn/CSS/CSS_layout/Media_queries /en-US/docs/Learn_web_development/Core/CSS_layout/Media_queries -/en-US/docs/Learn/CSS/CSS_layout/Multicol_skills /en-US/docs/Learn_web_development/Core/CSS_layout/Multicol_skills +/en-US/docs/Learn/CSS/CSS_layout/Multicol_skills /en-US/docs/Learn_web_development/Core/CSS_layout/Test_your_skills/Multicolumn /en-US/docs/Learn/CSS/CSS_layout/Multiple-column_Layout /en-US/docs/Learn_web_development/Core/CSS_layout/Multiple-column_Layout /en-US/docs/Learn/CSS/CSS_layout/Normal_Flow /en-US/docs/Learn_web_development/Core/CSS_layout/Introduction -/en-US/docs/Learn/CSS/CSS_layout/Position_skills /en-US/docs/Learn_web_development/Core/CSS_layout/Position_skills +/en-US/docs/Learn/CSS/CSS_layout/Position_skills /en-US/docs/Learn_web_development/Core/CSS_layout/Test_your_skills/Position /en-US/docs/Learn/CSS/CSS_layout/Positioning /en-US/docs/Learn_web_development/Core/CSS_layout/Positioning /en-US/docs/Learn/CSS/CSS_layout/Practical_positioning_examples /en-US/docs/Learn_web_development/Core/CSS_layout/Practical_positioning_examples /en-US/docs/Learn/CSS/CSS_layout/Responsive_Design /en-US/docs/Learn_web_development/Core/CSS_layout/Responsive_Design /en-US/docs/Learn/CSS/CSS_layout/Supporting_Older_Browsers /en-US/docs/Learn_web_development/Core/CSS_layout/Supporting_Older_Browsers /en-US/docs/Learn/CSS/CSS_layout/Using_Media_Queries /en-US/docs/Learn_web_development/Core/CSS_layout/Media_queries -/en-US/docs/Learn/CSS/CSS_layout/rwd_skills /en-US/docs/Learn_web_development/Core/CSS_layout/rwd_skills +/en-US/docs/Learn/CSS/CSS_layout/rwd_skills /en-US/docs/Learn_web_development/Core/CSS_layout/Test_your_skills/Responsive_design /en-US/docs/Learn/CSS/CSS_properties /en-US/docs/Learn_web_development/Core/Styling_basics/Basic_selectors /en-US/docs/Learn/CSS/First_steps /en-US/docs/Learn_web_development/Core/Styling_basics /en-US/docs/Learn/CSS/First_steps/Getting_started /en-US/docs/Learn_web_development/Core/Styling_basics/Getting_started @@ -5365,13 +5368,13 @@ /en-US/docs/Learn/Forms/Sending_forms_through_JavaScript /en-US/docs/Learn_web_development/Extensions/Forms/Sending_forms_through_JavaScript /en-US/docs/Learn/Forms/Styling_HTML_forms /en-US/docs/Learn_web_development/Extensions/Forms/Styling_web_forms /en-US/docs/Learn/Forms/Styling_web_forms /en-US/docs/Learn_web_development/Extensions/Forms/Styling_web_forms -/en-US/docs/Learn/Forms/Test_your_skills:_Advanced_styling /en-US/docs/Learn_web_development/Extensions/Forms/Test_your_skills:_Advanced_styling -/en-US/docs/Learn/Forms/Test_your_skills:_Basic_controls /en-US/docs/Learn_web_development/Extensions/Forms/Test_your_skills:_Basic_controls -/en-US/docs/Learn/Forms/Test_your_skills:_Form_structure /en-US/docs/Learn_web_development/Extensions/Forms/Test_your_skills:_Form_structure -/en-US/docs/Learn/Forms/Test_your_skills:_Form_validation /en-US/docs/Learn_web_development/Extensions/Forms/Test_your_skills:_Form_validation -/en-US/docs/Learn/Forms/Test_your_skills:_HTML5_controls /en-US/docs/Learn_web_development/Extensions/Forms/Test_your_skills:_HTML5_controls -/en-US/docs/Learn/Forms/Test_your_skills:_Other_controls /en-US/docs/Learn_web_development/Extensions/Forms/Test_your_skills:_Other_controls -/en-US/docs/Learn/Forms/Test_your_skills:_Styling_basics /en-US/docs/Learn_web_development/Extensions/Forms/Test_your_skills:_Styling_basics +/en-US/docs/Learn/Forms/Test_your_skills:_Advanced_styling /en-US/docs/Learn_web_development/Extensions/Forms/Test_your_skills/Advanced_styling +/en-US/docs/Learn/Forms/Test_your_skills:_Basic_controls /en-US/docs/Learn_web_development/Extensions/Forms/Test_your_skills/Basic_controls +/en-US/docs/Learn/Forms/Test_your_skills:_Form_structure /en-US/docs/Learn_web_development/Extensions/Forms/Test_your_skills/Form_structure +/en-US/docs/Learn/Forms/Test_your_skills:_Form_validation /en-US/docs/Learn_web_development/Extensions/Forms/Test_your_skills/Form_validation +/en-US/docs/Learn/Forms/Test_your_skills:_HTML5_controls /en-US/docs/Learn_web_development/Extensions/Forms/Test_your_skills/Input_types +/en-US/docs/Learn/Forms/Test_your_skills:_Other_controls /en-US/docs/Learn_web_development/Extensions/Forms/Test_your_skills/Other_controls +/en-US/docs/Learn/Forms/Test_your_skills:_Styling_basics /en-US/docs/Learn_web_development/Extensions/Forms/Test_your_skills/Styling_basics /en-US/docs/Learn/Forms/UI_pseudo-classes /en-US/docs/Learn_web_development/Extensions/Forms/UI_pseudo-classes /en-US/docs/Learn/Forms/User_input_methods /en-US/docs/Learn_web_development/Extensions/Forms/User_input_methods /en-US/docs/Learn/Forms/Your_first_HTML_form /en-US/docs/Learn_web_development/Extensions/Forms/Your_first_form @@ -5394,7 +5397,7 @@ /en-US/docs/Learn/Getting_started_with_the_web/What_will_your_website_look_like /en-US/docs/Learn_web_development/Getting_started/Your_first_website/What_will_your_website_look_like /en-US/docs/Learn/GitHub /en-US/docs/Learn_web_development/Core/Version_control /en-US/docs/Learn/HTML /en-US/docs/Learn_web_development/Core/Structuring_content -/en-US/docs/Learn/HTML/Cheatsheet /en-US/docs/Learn_web_development/Howto/Solve_HTML_problems/Cheatsheet +/en-US/docs/Learn/HTML/Cheatsheet /en-US/docs/Web/HTML/Guides/Cheatsheet /en-US/docs/Learn/HTML/Element /en-US/docs/Learn_web_development/Howto/Solve_HTML_problems /en-US/docs/Learn/HTML/Element/abbr /en-US/docs/Learn_web_development/Core/Structuring_content/Advanced_text_features#Abbreviations /en-US/docs/Learn/HTML/Forms /en-US/docs/Learn_web_development/Extensions/Forms @@ -5427,26 +5430,26 @@ /en-US/docs/Learn/HTML/HTML_tags /en-US/docs/Learn_web_development/Core/Structuring_content /en-US/docs/Learn/HTML/Howto /en-US/docs/Learn_web_development/Howto/Solve_HTML_problems /en-US/docs/Learn/HTML/Howto/Add_Flash_content_within_a_webpage /en-US/docs/Learn_web_development/Core/Structuring_content/General_embedding_technologies#The__and__elements -/en-US/docs/Learn/HTML/Howto/Add_a_hit_map_on_top_of_an_image /en-US/docs/Learn_web_development/Howto/Solve_HTML_problems/Add_a_hit_map_on_top_of_an_image +/en-US/docs/Learn/HTML/Howto/Add_a_hit_map_on_top_of_an_image /en-US/docs/Web/HTML/How_to/Add_a_hit_map_on_top_of_an_image /en-US/docs/Learn/HTML/Howto/Add_audio_or_video_content_to_a_webpage /en-US/docs/Learn_web_development/Core/Structuring_content/HTML_video_and_audio /en-US/docs/Learn/HTML/Howto/Add_citations_to_webpages /en-US/docs/Learn_web_development/Core/Structuring_content/Advanced_text_features#Quotations /en-US/docs/Learn/HTML/Howto/Add_images_to_a_webpage /en-US/docs/Learn_web_development/Core/Structuring_content/HTML_images#How_do_we_put_an_image_on_a_webpage -/en-US/docs/Learn/HTML/Howto/Add_responsive_image_to_a_webpage /en-US/docs/Web/HTML/Responsive_images +/en-US/docs/Learn/HTML/Howto/Add_responsive_image_to_a_webpage /en-US/docs/Web/HTML/Guides/Responsive_images /en-US/docs/Learn/HTML/Howto/Add_vector_image_to_a_webpage /en-US/docs/Learn_web_development/Core/Structuring_content/Including_vector_graphics_in_HTML /en-US/docs/Learn/HTML/Howto/Annotate_images_and_graphics /en-US/docs/Learn_web_development/Core/Structuring_content/HTML_images#Annotating_images_with_figures_and_figure_captions -/en-US/docs/Learn/HTML/Howto/Author_fast-loading_HTML_pages /en-US/docs/Learn_web_development/Howto/Solve_HTML_problems/Author_fast-loading_HTML_pages +/en-US/docs/Learn/HTML/Howto/Author_fast-loading_HTML_pages /en-US/docs/Web/HTML/How_to/Author_fast-loading_HTML_pages /en-US/docs/Learn/HTML/Howto/Create_a_basic_HTML_document /en-US/docs/Learn_web_development/Core/Structuring_content/Basic_HTML_syntax /en-US/docs/Learn/HTML/Howto/Create_a_hyperlink /en-US/docs/Learn_web_development/Core/Structuring_content/Creating_links /en-US/docs/Learn/HTML/Howto/Create_list_of_items_with_HTML /en-US/docs/Learn_web_development/Core/Structuring_content/Headings_and_paragraphs#Lists -/en-US/docs/Learn/HTML/Howto/Define_terms_with_HTML /en-US/docs/Learn_web_development/Howto/Solve_HTML_problems/Define_terms_with_HTML +/en-US/docs/Learn/HTML/Howto/Define_terms_with_HTML /en-US/docs/Web/HTML/How_to/Define_terms_with_HTML /en-US/docs/Learn/HTML/Howto/Display_computer_code_with_HTML /en-US/docs/Learn_web_development/Core/Structuring_content/Advanced_text_features#Representing_computer_code /en-US/docs/Learn/HTML/Howto/Divide_a_webpage_into_logical_sections /en-US/docs/Learn_web_development/Core/Structuring_content/Structuring_documents /en-US/docs/Learn/HTML/Howto/Embed_a_webpage_within_another_webpage /en-US/docs/Learn_web_development/Core/Structuring_content/General_embedding_technologies /en-US/docs/Learn/HTML/Howto/Emphasize_content_or_indicate_that_text_is_important /en-US/docs/Learn_web_development/Core/Structuring_content/Headings_and_paragraphs#Emphasis_and_importance /en-US/docs/Learn/HTML/Howto/Mark_abbreviations_and_make_them_understandable /en-US/docs/Learn_web_development/Core/Structuring_content/Advanced_text_features#Abbreviations /en-US/docs/Learn/HTML/Howto/Set_up_a_proper_title_hierarchy /en-US/docs/Learn_web_development/Core/Structuring_content/Headings_and_paragraphs -/en-US/docs/Learn/HTML/Howto/Use_JavaScript_within_a_webpage /en-US/docs/Learn_web_development/Howto/Solve_HTML_problems/Use_JavaScript_within_a_webpage -/en-US/docs/Learn/HTML/Howto/Use_data_attributes /en-US/docs/Learn_web_development/Howto/Solve_HTML_problems/Use_data_attributes +/en-US/docs/Learn/HTML/Howto/Use_JavaScript_within_a_webpage /en-US/docs/Web/HTML/How_to/Add_JavaScript_to_your_web_page +/en-US/docs/Learn/HTML/Howto/Use_data_attributes /en-US/docs/Web/HTML/How_to/Use_data_attributes /en-US/docs/Learn/HTML/Howto/abbr /en-US/docs/Learn_web_development/Core/Structuring_content/Advanced_text_features#Abbreviations /en-US/docs/Learn/HTML/Introduction_to_HTML /en-US/docs/Learn_web_development/Core/Structuring_content /en-US/docs/Learn/HTML/Introduction_to_HTML/Advanced_text_formatting /en-US/docs/Learn_web_development/Core/Structuring_content/Advanced_text_features @@ -5457,20 +5460,20 @@ /en-US/docs/Learn/HTML/Introduction_to_HTML/HTML_text_fundamentals /en-US/docs/Learn_web_development/Core/Structuring_content/Headings_and_paragraphs /en-US/docs/Learn/HTML/Introduction_to_HTML/Marking_up_a_letter /en-US/docs/Learn_web_development/Core/Structuring_content/Marking_up_a_letter /en-US/docs/Learn/HTML/Introduction_to_HTML/Structuring_a_page_of_content /en-US/docs/Learn_web_development/Core/Structuring_content/Structuring_a_page_of_content -/en-US/docs/Learn/HTML/Introduction_to_HTML/Test_your_skills:_Advanced_HTML_text /en-US/docs/Learn_web_development/Core/Structuring_content/Test_your_skills:_Advanced_HTML_text -/en-US/docs/Learn/HTML/Introduction_to_HTML/Test_your_skills:_HTML_text_basics /en-US/docs/Learn_web_development/Core/Structuring_content/Test_your_skills:_HTML_text_basics -/en-US/docs/Learn/HTML/Introduction_to_HTML/Test_your_skills:_Links /en-US/docs/Learn_web_development/Core/Structuring_content/Test_your_skills:_Links +/en-US/docs/Learn/HTML/Introduction_to_HTML/Test_your_skills:_Advanced_HTML_text /en-US/docs/Learn_web_development/Core/Structuring_content/Test_your_skills/Advanced_HTML_text +/en-US/docs/Learn/HTML/Introduction_to_HTML/Test_your_skills:_HTML_text_basics /en-US/docs/Learn_web_development/Core/Structuring_content/Test_your_skills/HTML_text_basics +/en-US/docs/Learn/HTML/Introduction_to_HTML/Test_your_skills:_Links /en-US/docs/Learn_web_development/Core/Structuring_content/Test_your_skills/Links /en-US/docs/Learn/HTML/Introduction_to_HTML/The_HTML_head /en-US/docs/Learn_web_development/Core/Structuring_content/Webpage_metadata /en-US/docs/Learn/HTML/Introduction_to_HTML/The_head_metadata_in_HTML /en-US/docs/Learn_web_development/Core/Structuring_content/Webpage_metadata /en-US/docs/Learn/HTML/Multimedia_and_embedding /en-US/docs/Learn_web_development/Core/Structuring_content /en-US/docs/Learn/HTML/Multimedia_and_embedding/Adding_vector_graphics_to_the_Web /en-US/docs/Learn_web_development/Core/Structuring_content/Including_vector_graphics_in_HTML /en-US/docs/Learn/HTML/Multimedia_and_embedding/Images_in_HTML /en-US/docs/Learn_web_development/Core/Structuring_content/HTML_images -/en-US/docs/Learn/HTML/Multimedia_and_embedding/Images_in_HTML/Test_your_skills:_HTML_images /en-US/docs/Learn_web_development/Core/Structuring_content/HTML_images/Test_your_skills:_HTML_images +/en-US/docs/Learn/HTML/Multimedia_and_embedding/Images_in_HTML/Test_your_skills:_HTML_images /en-US/docs/Learn_web_development/Core/Structuring_content/Test_your_skills/Images /en-US/docs/Learn/HTML/Multimedia_and_embedding/Mozilla_splash_page /en-US/docs/Learn_web_development/Core/Structuring_content/Mozilla_splash_page /en-US/docs/Learn/HTML/Multimedia_and_embedding/Other_embedding_technologies /en-US/docs/Learn_web_development/Core/Structuring_content/General_embedding_technologies -/en-US/docs/Learn/HTML/Multimedia_and_embedding/Responsive_images /en-US/docs/Web/HTML/Responsive_images +/en-US/docs/Learn/HTML/Multimedia_and_embedding/Responsive_images /en-US/docs/Web/HTML/Guides/Responsive_images /en-US/docs/Learn/HTML/Multimedia_and_embedding/Video_and_audio_content /en-US/docs/Learn_web_development/Core/Structuring_content/HTML_video_and_audio -/en-US/docs/Learn/HTML/Multimedia_and_embedding/Video_and_audio_content/Test_your_skills:_Multimedia_and_embedding /en-US/docs/Learn_web_development/Core/Structuring_content/HTML_video_and_audio/Test_your_skills:_Multimedia_and_embedding +/en-US/docs/Learn/HTML/Multimedia_and_embedding/Video_and_audio_content/Test_your_skills:_Multimedia_and_embedding /en-US/docs/Learn_web_development/Core/Structuring_content/Test_your_skills/Multimedia_and_embedding /en-US/docs/Learn/HTML/Tables /en-US/docs/Learn_web_development/Core/Structuring_content/HTML_table_basics /en-US/docs/Learn/HTML/Tables/Advanced /en-US/docs/Learn_web_development/Core/Structuring_content/Table_accessibility /en-US/docs/Learn/HTML/Tables/Basics /en-US/docs/Learn_web_development/Core/Structuring_content/HTML_table_basics @@ -5510,10 +5513,10 @@ /en-US/docs/Learn/JavaScript/Building_blocks/Image_gallery /en-US/docs/Learn_web_development/Core/Scripting/Image_gallery /en-US/docs/Learn/JavaScript/Building_blocks/Looping_code /en-US/docs/Learn_web_development/Core/Scripting/Loops /en-US/docs/Learn/JavaScript/Building_blocks/Return_values /en-US/docs/Learn_web_development/Core/Scripting/Return_values -/en-US/docs/Learn/JavaScript/Building_blocks/Test_your_skills:_Conditionals /en-US/docs/Learn_web_development/Core/Scripting/Test_your_skills:_Conditionals -/en-US/docs/Learn/JavaScript/Building_blocks/Test_your_skills:_Events /en-US/docs/Learn_web_development/Core/Scripting/Test_your_skills:_Events -/en-US/docs/Learn/JavaScript/Building_blocks/Test_your_skills:_Functions /en-US/docs/Learn_web_development/Core/Scripting/Test_your_skills:_Functions -/en-US/docs/Learn/JavaScript/Building_blocks/Test_your_skills:_Loops /en-US/docs/Learn_web_development/Core/Scripting/Test_your_skills:_Loops +/en-US/docs/Learn/JavaScript/Building_blocks/Test_your_skills:_Conditionals /en-US/docs/Learn_web_development/Core/Scripting/Test_your_skills/Conditionals +/en-US/docs/Learn/JavaScript/Building_blocks/Test_your_skills:_Events /en-US/docs/Learn_web_development/Core/Scripting/Test_your_skills/Events +/en-US/docs/Learn/JavaScript/Building_blocks/Test_your_skills:_Functions /en-US/docs/Learn_web_development/Core/Scripting/Test_your_skills/Functions +/en-US/docs/Learn/JavaScript/Building_blocks/Test_your_skills:_Loops /en-US/docs/Learn_web_development/Core/Scripting/Test_your_skills/Loops /en-US/docs/Learn/JavaScript/Building_blocks/conditionals /en-US/docs/Learn_web_development/Core/Scripting/Conditionals /en-US/docs/Learn/JavaScript/Client-side_web_APIs /en-US/docs/Learn_web_development/Extensions/Client-side_APIs /en-US/docs/Learn/JavaScript/Client-side_web_APIs/Client-side_storage /en-US/docs/Learn_web_development/Extensions/Client-side_APIs/Client-side_storage @@ -5530,10 +5533,10 @@ /en-US/docs/Learn/JavaScript/First_steps/Maths /en-US/docs/Learn_web_development/Core/Scripting/Math /en-US/docs/Learn/JavaScript/First_steps/Silly_story_generator /en-US/docs/Learn_web_development/Core/Scripting/Silly_story_generator /en-US/docs/Learn/JavaScript/First_steps/Strings /en-US/docs/Learn_web_development/Core/Scripting/Strings -/en-US/docs/Learn/JavaScript/First_steps/Test_your_skills:_Arrays /en-US/docs/Learn_web_development/Core/Scripting/Test_your_skills:_Arrays -/en-US/docs/Learn/JavaScript/First_steps/Test_your_skills:_Math /en-US/docs/Learn_web_development/Core/Scripting/Test_your_skills:_Math -/en-US/docs/Learn/JavaScript/First_steps/Test_your_skills:_Strings /en-US/docs/Learn_web_development/Core/Scripting/Test_your_skills:_Strings -/en-US/docs/Learn/JavaScript/First_steps/Test_your_skills:_variables /en-US/docs/Learn_web_development/Core/Scripting/Test_your_skills:_variables +/en-US/docs/Learn/JavaScript/First_steps/Test_your_skills:_Arrays /en-US/docs/Learn_web_development/Core/Scripting/Test_your_skills/Arrays +/en-US/docs/Learn/JavaScript/First_steps/Test_your_skills:_Math /en-US/docs/Learn_web_development/Core/Scripting/Test_your_skills/Math +/en-US/docs/Learn/JavaScript/First_steps/Test_your_skills:_Strings /en-US/docs/Learn_web_development/Core/Scripting/Test_your_skills/Strings +/en-US/docs/Learn/JavaScript/First_steps/Test_your_skills:_variables /en-US/docs/Learn_web_development/Core/Scripting/Test_your_skills/Variables /en-US/docs/Learn/JavaScript/First_steps/Useful_string_methods /en-US/docs/Learn_web_development/Core/Scripting/Useful_string_methods /en-US/docs/Learn/JavaScript/First_steps/Variables /en-US/docs/Learn_web_development/Core/Scripting/Variables /en-US/docs/Learn/JavaScript/First_steps/What_is_JavaScript /en-US/docs/Learn_web_development/Core/Scripting/What_is_JavaScript @@ -5564,18 +5567,18 @@ /en-US/docs/Learn/JavaScript/Objects/Object_building_practice /en-US/docs/Learn_web_development/Extensions/Advanced_JavaScript_objects/Object_building_practice /en-US/docs/Learn/JavaScript/Objects/Object_building_practise /en-US/docs/Learn_web_development/Extensions/Advanced_JavaScript_objects/Object_building_practice /en-US/docs/Learn/JavaScript/Objects/Object_prototypes /en-US/docs/Learn_web_development/Extensions/Advanced_JavaScript_objects/Object_prototypes -/en-US/docs/Learn/JavaScript/Objects/Test_your_skills:_JSON /en-US/docs/Learn_web_development/Core/Scripting/Test_your_skills:_JSON -/en-US/docs/Learn/JavaScript/Objects/Test_your_skills:_Object-oriented_JavaScript /en-US/docs/Learn_web_development/Extensions/Advanced_JavaScript_objects/Test_your_skills:_Object-oriented_JavaScript -/en-US/docs/Learn/JavaScript/Objects/Test_your_skills:_Object_basics /en-US/docs/Learn_web_development/Core/Scripting/Test_your_skills:_Object_basics +/en-US/docs/Learn/JavaScript/Objects/Test_your_skills:_JSON /en-US/docs/Learn_web_development/Core/Scripting/Test_your_skills/JSON +/en-US/docs/Learn/JavaScript/Objects/Test_your_skills:_Object-oriented_JavaScript /en-US/docs/Learn_web_development/Extensions/Advanced_JavaScript_objects/Test_your_skills/Object-oriented_JavaScript +/en-US/docs/Learn/JavaScript/Objects/Test_your_skills:_Object_basics /en-US/docs/Learn_web_development/Core/Scripting/Test_your_skills/Object_basics /en-US/docs/Learn/Learning_and_getting_help /en-US/docs/Learn_web_development/Getting_started/Soft_skills/Research_and_learning /en-US/docs/Learn/MathML /en-US/docs/Web/MathML /en-US/docs/Learn/MathML/First_steps /en-US/docs/Web/MathML/Guides -/en-US/docs/Learn/MathML/First_steps/Fractions_and_roots /en-US/docs/Web/MathML/Guides/Fractions_and_roots -/en-US/docs/Learn/MathML/First_steps/Getting_started /en-US/docs/Web/MathML/Guides/Getting_started -/en-US/docs/Learn/MathML/First_steps/Scripts /en-US/docs/Web/MathML/Guides/Scripts -/en-US/docs/Learn/MathML/First_steps/Tables /en-US/docs/Web/MathML/Guides/Tables -/en-US/docs/Learn/MathML/First_steps/Text_containers /en-US/docs/Web/MathML/Guides/Text_containers -/en-US/docs/Learn/MathML/First_steps/Three_famous_mathematical_formulas /en-US/docs/Web/MathML/Guides/Three_famous_mathematical_formulas +/en-US/docs/Learn/MathML/First_steps/Fractions_and_roots /en-US/docs/Web/MathML/Tutorials/For_beginners/Fractions_and_roots +/en-US/docs/Learn/MathML/First_steps/Getting_started /en-US/docs/Web/MathML/Tutorials/For_beginners/Getting_started +/en-US/docs/Learn/MathML/First_steps/Scripts /en-US/docs/Web/MathML/Tutorials/For_beginners/Scripts +/en-US/docs/Learn/MathML/First_steps/Tables /en-US/docs/Web/MathML/Tutorials/For_beginners/Tables +/en-US/docs/Learn/MathML/First_steps/Text_containers /en-US/docs/Web/MathML/Tutorials/For_beginners/Text_containers +/en-US/docs/Learn/MathML/First_steps/Three_famous_mathematical_formulas /en-US/docs/Web/MathML/Tutorials/For_beginners/Three_famous_mathematical_formulas /en-US/docs/Learn/Open_a_file_in_a_browser /en-US/docs/Learn_web_development/Getting_started/Environment_setup/Dealing_with_files /en-US/docs/Learn/Other_learning_material /en-US/docs/Learn_web_development /en-US/docs/Learn/Pages_sites_servers_and_search_engines /en-US/docs/Learn_web_development/Getting_started/Environment_setup/Browsing_the_web @@ -5755,36 +5758,89 @@ /en-US/docs/Learn/skills/Infrastructure/Undersanding_URLs /en-US/docs/Learn_web_development/Howto/Web_mechanics/What_is_a_URL /en-US/docs/Learn/tutorial /en-US/docs/Learn_web_development /en-US/docs/Learn/tutorial/How_to_build_a_web_site /en-US/docs/Learn_web_development +/en-US/docs/Learn_web_development/Core/Accessibility/CSS_and_JavaScript/Test_your_skills:_CSS_and_JavaScript_accessibility /en-US/docs/Learn_web_development/Core/Accessibility/Test_your_skills/CSS_and_JavaScript +/en-US/docs/Learn_web_development/Core/Accessibility/Test_your_skills:_HTML_accessibility /en-US/docs/Learn_web_development/Core/Accessibility/Test_your_skills/HTML +/en-US/docs/Learn_web_development/Core/Accessibility/WAI-ARIA_basics/Test_your_skills:_WAI-ARIA /en-US/docs/Learn_web_development/Core/Accessibility/Test_your_skills/WAI-ARIA +/en-US/docs/Learn_web_development/Core/CSS_layout/Flexbox_skills /en-US/docs/Learn_web_development/Core/CSS_layout/Test_your_skills/Flexbox +/en-US/docs/Learn_web_development/Core/CSS_layout/Floats_skills /en-US/docs/Learn_web_development/Core/CSS_layout/Test_your_skills/Floats +/en-US/docs/Learn_web_development/Core/CSS_layout/Grid_skills /en-US/docs/Learn_web_development/Core/CSS_layout/Test_your_skills/Grid +/en-US/docs/Learn_web_development/Core/CSS_layout/Multicol_skills /en-US/docs/Learn_web_development/Core/CSS_layout/Test_your_skills/Multicolumn +/en-US/docs/Learn_web_development/Core/CSS_layout/Position_skills /en-US/docs/Learn_web_development/Core/CSS_layout/Test_your_skills/Position +/en-US/docs/Learn_web_development/Core/CSS_layout/rwd_skills /en-US/docs/Learn_web_development/Core/CSS_layout/Test_your_skills/Responsive_design +/en-US/docs/Learn_web_development/Core/Scripting/Test_your_skills:_Arrays /en-US/docs/Learn_web_development/Core/Scripting/Test_your_skills/Arrays +/en-US/docs/Learn_web_development/Core/Scripting/Test_your_skills:_Conditionals /en-US/docs/Learn_web_development/Core/Scripting/Test_your_skills/Conditionals +/en-US/docs/Learn_web_development/Core/Scripting/Test_your_skills:_Events /en-US/docs/Learn_web_development/Core/Scripting/Test_your_skills/Events +/en-US/docs/Learn_web_development/Core/Scripting/Test_your_skills:_Functions /en-US/docs/Learn_web_development/Core/Scripting/Test_your_skills/Functions +/en-US/docs/Learn_web_development/Core/Scripting/Test_your_skills:_JSON /en-US/docs/Learn_web_development/Core/Scripting/Test_your_skills/JSON +/en-US/docs/Learn_web_development/Core/Scripting/Test_your_skills:_Loops /en-US/docs/Learn_web_development/Core/Scripting/Test_your_skills/Loops +/en-US/docs/Learn_web_development/Core/Scripting/Test_your_skills:_Math /en-US/docs/Learn_web_development/Core/Scripting/Test_your_skills/Math +/en-US/docs/Learn_web_development/Core/Scripting/Test_your_skills:_Object_basics /en-US/docs/Learn_web_development/Core/Scripting/Test_your_skills/Object_basics +/en-US/docs/Learn_web_development/Core/Scripting/Test_your_skills:_Strings /en-US/docs/Learn_web_development/Core/Scripting/Test_your_skills/Strings +/en-US/docs/Learn_web_development/Core/Scripting/Test_your_skills:_variables /en-US/docs/Learn_web_development/Core/Scripting/Test_your_skills/Variables /en-US/docs/Learn_web_development/Core/Structuring_content/Advanced_text_formatting /en-US/docs/Learn_web_development/Core/Structuring_content/Advanced_text_features /en-US/docs/Learn_web_development/Core/Structuring_content/Creating_hyperlinks /en-US/docs/Learn_web_development/Core/Structuring_content/Creating_links /en-US/docs/Learn_web_development/Core/Structuring_content/Document_and_website_structure /en-US/docs/Learn_web_development/Core/Structuring_content/Structuring_documents /en-US/docs/Learn_web_development/Core/Structuring_content/Getting_started /en-US/docs/Learn_web_development/Core/Structuring_content/Basic_HTML_syntax +/en-US/docs/Learn_web_development/Core/Structuring_content/HTML_images/Test_your_skills /en-US/docs/Learn_web_development/Core/Structuring_content/Test_your_skills/Images +/en-US/docs/Learn_web_development/Core/Structuring_content/HTML_images/Test_your_skills:_HTML_images /en-US/docs/Learn_web_development/Core/Structuring_content/Test_your_skills/Images /en-US/docs/Learn_web_development/Core/Structuring_content/HTML_text_fundamentals /en-US/docs/Learn_web_development/Core/Structuring_content/Headings_and_paragraphs +/en-US/docs/Learn_web_development/Core/Structuring_content/HTML_video_and_audio/Test_your_skills:_Multimedia_and_embedding /en-US/docs/Learn_web_development/Core/Structuring_content/Test_your_skills/Multimedia_and_embedding +/en-US/docs/Learn_web_development/Core/Structuring_content/Test_your_skills:_Advanced_HTML_text /en-US/docs/Learn_web_development/Core/Structuring_content/Test_your_skills/Advanced_HTML_text +/en-US/docs/Learn_web_development/Core/Structuring_content/Test_your_skills:_HTML_text_basics /en-US/docs/Learn_web_development/Core/Structuring_content/Test_your_skills/HTML_text_basics +/en-US/docs/Learn_web_development/Core/Structuring_content/Test_your_skills:_Links /en-US/docs/Learn_web_development/Core/Structuring_content/Test_your_skills/Links /en-US/docs/Learn_web_development/Core/Structuring_content/The_head_metadata_in_HTML /en-US/docs/Learn_web_development/Core/Structuring_content/Webpage_metadata /en-US/docs/Learn_web_development/Core/Styling_basics/A_cool_looking_box /en-US/docs/Learn_web_development/Core/Styling_basics/Cool-looking_box /en-US/docs/Learn_web_development/Core/Styling_basics/Basic_selectors/Attribute_selectors /en-US/docs/Learn_web_development/Core/Styling_basics/Attribute_selectors /en-US/docs/Learn_web_development/Core/Styling_basics/Basic_selectors/Combinators /en-US/docs/Learn_web_development/Core/Styling_basics/Combinators /en-US/docs/Learn_web_development/Core/Styling_basics/Basic_selectors/Pseudo-classes_and_pseudo-elements /en-US/docs/Learn_web_development/Core/Styling_basics/Pseudo_classes_and_elements +/en-US/docs/Learn_web_development/Core/Styling_basics/Basic_selectors/Selectors_Tasks /en-US/docs/Learn_web_development/Core/Styling_basics/Test_your_skills/Selectors +/en-US/docs/Learn_web_development/Core/Styling_basics/Box_Model_Tasks /en-US/docs/Learn_web_development/Core/Styling_basics/Test_your_skills/Box_model /en-US/docs/Learn_web_development/Core/Styling_basics/Cascade_and_inheritance /en-US/docs/Learn_web_development/Core/Styling_basics/Handling_conflicts +/en-US/docs/Learn_web_development/Core/Styling_basics/Cascade_tasks /en-US/docs/Learn_web_development/Core/Styling_basics/Test_your_skills/Cascade /en-US/docs/Learn_web_development/Core/Styling_basics/Creating_fancy_letterheaded_paper /en-US/docs/Learn_web_development/Core/Styling_basics/Fancy_letterheaded_paper /en-US/docs/Learn_web_development/Core/Styling_basics/Images_media_form_elements /en-US/docs/Learn_web_development/Core/Styling_basics/Images_media_forms +/en-US/docs/Learn_web_development/Core/Styling_basics/Images_tasks /en-US/docs/Learn_web_development/Core/Styling_basics/Test_your_skills/Images +/en-US/docs/Learn_web_development/Core/Styling_basics/Overflow_Tasks /en-US/docs/Learn_web_development/Core/Styling_basics/Test_your_skills/Overflow /en-US/docs/Learn_web_development/Core/Styling_basics/Overflowing_content /en-US/docs/Learn_web_development/Core/Styling_basics/Overflow /en-US/docs/Learn_web_development/Core/Styling_basics/Selectors /en-US/docs/Learn_web_development/Core/Styling_basics/Basic_selectors /en-US/docs/Learn_web_development/Core/Styling_basics/Selectors/Attribute_selectors /en-US/docs/Learn_web_development/Core/Styling_basics/Attribute_selectors /en-US/docs/Learn_web_development/Core/Styling_basics/Selectors/Combinators /en-US/docs/Learn_web_development/Core/Styling_basics/Combinators /en-US/docs/Learn_web_development/Core/Styling_basics/Selectors/Pseudo-classes_and_pseudo-elements /en-US/docs/Learn_web_development/Core/Styling_basics/Pseudo_classes_and_elements -/en-US/docs/Learn_web_development/Core/Styling_basics/Selectors/Selectors_Tasks /en-US/docs/Learn_web_development/Core/Styling_basics/Basic_selectors/Selectors_Tasks +/en-US/docs/Learn_web_development/Core/Styling_basics/Selectors/Selectors_Tasks /en-US/docs/Learn_web_development/Core/Styling_basics/Test_your_skills/Selectors /en-US/docs/Learn_web_development/Core/Styling_basics/Sizing_items_in_CSS /en-US/docs/Learn_web_development/Core/Styling_basics/Sizing +/en-US/docs/Learn_web_development/Core/Styling_basics/Sizing_tasks /en-US/docs/Learn_web_development/Core/Styling_basics/Test_your_skills/Sizing /en-US/docs/Learn_web_development/Core/Styling_basics/Styling_tables /en-US/docs/Learn_web_development/Core/Styling_basics/Tables +/en-US/docs/Learn_web_development/Core/Styling_basics/Tables_tasks /en-US/docs/Learn_web_development/Core/Styling_basics/Test_your_skills/Tables +/en-US/docs/Learn_web_development/Core/Styling_basics/Test_your_skills_backgrounds_and_borders /en-US/docs/Learn_web_development/Core/Styling_basics/Test_your_skills/Backgrounds_and_borders /en-US/docs/Learn_web_development/Core/Styling_basics/The_box_model /en-US/docs/Learn_web_development/Core/Styling_basics/Box_model +/en-US/docs/Learn_web_development/Core/Styling_basics/Values_tasks /en-US/docs/Learn_web_development/Core/Styling_basics/Test_your_skills/Values +/en-US/docs/Learn_web_development/Core/Styling_basics/Writing_Modes_Tasks /en-US/docs/Learn_web_development/Core/Styling_basics/Test_your_skills/Writing_modes +/en-US/docs/Learn_web_development/Extensions/Advanced_JavaScript_objects/Test_your_skills:_Object-oriented_JavaScript /en-US/docs/Learn_web_development/Extensions/Advanced_JavaScript_objects/Test_your_skills/Object-oriented_JavaScript /en-US/docs/Learn_web_development/Extensions/Forms/Property_compatibility_table_for_form_controls /en-US/docs/Learn_web_development/Extensions/Forms +/en-US/docs/Learn_web_development/Extensions/Forms/Test_your_skills/Form_controls /en-US/docs/Learn_web_development/Extensions/Forms/Test_your_skills/Input_types +/en-US/docs/Learn_web_development/Extensions/Forms/Test_your_skills:_Advanced_styling /en-US/docs/Learn_web_development/Extensions/Forms/Test_your_skills/Advanced_styling +/en-US/docs/Learn_web_development/Extensions/Forms/Test_your_skills:_Basic_controls /en-US/docs/Learn_web_development/Extensions/Forms/Test_your_skills/Basic_controls +/en-US/docs/Learn_web_development/Extensions/Forms/Test_your_skills:_Form_structure /en-US/docs/Learn_web_development/Extensions/Forms/Test_your_skills/Form_structure +/en-US/docs/Learn_web_development/Extensions/Forms/Test_your_skills:_Form_validation /en-US/docs/Learn_web_development/Extensions/Forms/Test_your_skills/Form_validation +/en-US/docs/Learn_web_development/Extensions/Forms/Test_your_skills:_HTML5_controls /en-US/docs/Learn_web_development/Extensions/Forms/Test_your_skills/Input_types +/en-US/docs/Learn_web_development/Extensions/Forms/Test_your_skills:_Other_controls /en-US/docs/Learn_web_development/Extensions/Forms/Test_your_skills/Other_controls +/en-US/docs/Learn_web_development/Extensions/Forms/Test_your_skills:_Styling_basics /en-US/docs/Learn_web_development/Extensions/Forms/Test_your_skills/Styling_basics +/en-US/docs/Learn_web_development/Extensions/Security_privacy /en-US/docs/Web/Security +/en-US/docs/Learn_web_development/Extensions/Transform_animate /en-US/docs/Learn_web_development/Extensions /en-US/docs/Learn_web_development/Getting_started/Basic_setup /en-US/docs/Learn_web_development/Getting_started/Environment_setup/Installing_software +/en-US/docs/Learn_web_development/Getting_started/Soft_skills/Job_interviews /en-US/docs/Learn_web_development/Getting_started/Soft_skills/Finding_a_job /en-US/docs/Learn_web_development/Getting_started/Soft_skills/Learning_and_getting_help /en-US/docs/Learn_web_development/Getting_started/Soft_skills/Research_and_learning /en-US/docs/Learn_web_development/Getting_started/Your_first_website/CSS_basics /en-US/docs/Learn_web_development/Getting_started/Your_first_website/Styling_the_content /en-US/docs/Learn_web_development/Getting_started/Your_first_website/HTML_basics /en-US/docs/Learn_web_development/Getting_started/Your_first_website/Creating_the_content /en-US/docs/Learn_web_development/Getting_started/Your_first_website/How_the_Web_works /en-US/docs/Learn_web_development/Getting_started/Web_standards/How_the_web_works /en-US/docs/Learn_web_development/Getting_started/Your_first_website/JavaScript_basics /en-US/docs/Learn_web_development/Getting_started/Your_first_website/Adding_interactivity /en-US/docs/Learn_web_development/Getting_started/Your_first_website/The_web_and_web_standards /en-US/docs/Learn_web_development/Getting_started/Web_standards/The_web_standards_model +/en-US/docs/Learn_web_development/Howto/Solve_HTML_problems/Add_a_hit_map_on_top_of_an_image /en-US/docs/Web/HTML/How_to/Add_a_hit_map_on_top_of_an_image +/en-US/docs/Learn_web_development/Howto/Solve_HTML_problems/Author_fast-loading_HTML_pages /en-US/docs/Web/HTML/How_to/Author_fast-loading_HTML_pages +/en-US/docs/Learn_web_development/Howto/Solve_HTML_problems/Cheatsheet /en-US/docs/Web/HTML/Guides/Cheatsheet +/en-US/docs/Learn_web_development/Howto/Solve_HTML_problems/Define_terms_with_HTML /en-US/docs/Web/HTML/How_to/Define_terms_with_HTML +/en-US/docs/Learn_web_development/Howto/Solve_HTML_problems/Use_JavaScript_within_a_webpage /en-US/docs/Web/HTML/How_to/Add_JavaScript_to_your_web_page +/en-US/docs/Learn_web_development/Howto/Solve_HTML_problems/Use_data_attributes /en-US/docs/Web/HTML/How_to/Use_data_attributes /en-US/docs/Liberty!_Equality!_Validity! /en-US/docs/Learn_web_development/Core/Structuring_content/Debugging_HTML /en-US/docs/Link_prefetching_FAQ /en-US/docs/Glossary/Prefetch /en-US/docs/Localization /en-US/docs/Glossary/Localization @@ -5796,16 +5852,17 @@ /en-US/docs/MDN/Changelog /en-US/docs/MDN/Writing_guidelines/Changelog /en-US/docs/MDN/Community/Contributing /en-US/docs/MDN/Community /en-US/docs/MDN/Community/Contributing/Getting_started /en-US/docs/MDN/Community/Getting_started -/en-US/docs/MDN/Community/Contributing/Security_vulnerability_response /en-US/docs/MDN/Community/Security_vulnerability_response +/en-US/docs/MDN/Community/Contributing/Security_vulnerability_response https://github.com/mdn/mdn/issues/45 /en-US/docs/MDN/Community/Contributing/Translated_content /en-US/docs/MDN/Community/Translated_content /en-US/docs/MDN/Community/Issues/Issue_triage /en-US/docs/MDN/Community/Issues /en-US/docs/MDN/Community/MDN_content /en-US/docs/MDN/Community/Getting_started /en-US/docs/MDN/Community/MDN_content/Issues /en-US/docs/MDN/Community/Issues /en-US/docs/MDN/Community/MDN_content/Pull_requests /en-US/docs/MDN/Community/Pull_requests +/en-US/docs/MDN/Community/Security_vulnerability_response https://github.com/mdn/mdn/issues/45 /en-US/docs/MDN/Community/Users_teams /en-US/docs/MDN/Community/Roles_teams /en-US/docs/MDN/Contribute /en-US/docs/MDN/Community/Getting_started /en-US/docs/MDN/Contribute/Changelog /en-US/docs/MDN/Writing_guidelines/Changelog -/en-US/docs/MDN/Contribute/Code_sample_guidelines /en-US/docs/MDN/Writing_guidelines/Writing_style_guide/Code_style_guide +/en-US/docs/MDN/Contribute/Code_sample_guidelines /en-US/docs/MDN/Writing_guidelines/Code_style_guide /en-US/docs/MDN/Contribute/Content /en-US/docs/MDN/Writing_guidelines /en-US/docs/MDN/Contribute/Content/Content_blocks /en-US/docs/MDN/Writing_guidelines/Howto/Markdown_in_MDN /en-US/docs/MDN/Contribute/Content/Custom_macros /en-US/docs/MDN/Writing_guidelines/Page_structures/Macros/Commonly_used_macros @@ -5829,13 +5886,13 @@ /en-US/docs/MDN/Contribute/Guidelines /en-US/docs/MDN/Writing_guidelines /en-US/docs/MDN/Contribute/Guidelines/Best_practices /en-US/docs/MDN/Writing_guidelines/Experimental_deprecated_obsolete /en-US/docs/MDN/Contribute/Guidelines/CSS_style_guide /en-US/docs/MDN/Writing_guidelines/Howto/Markdown_in_MDN -/en-US/docs/MDN/Contribute/Guidelines/Code_guidelines /en-US/docs/MDN/Writing_guidelines/Writing_style_guide/Code_style_guide -/en-US/docs/MDN/Contribute/Guidelines/Code_guidelines/CSS /en-US/docs/MDN/Writing_guidelines/Writing_style_guide/Code_style_guide/CSS -/en-US/docs/MDN/Contribute/Guidelines/Code_guidelines/General /en-US/docs/MDN/Writing_guidelines/Writing_style_guide/Code_style_guide -/en-US/docs/MDN/Contribute/Guidelines/Code_guidelines/HTML /en-US/docs/MDN/Writing_guidelines/Writing_style_guide/Code_style_guide/HTML -/en-US/docs/MDN/Contribute/Guidelines/Code_guidelines/JavaScript /en-US/docs/MDN/Writing_guidelines/Writing_style_guide/Code_style_guide/JavaScript -/en-US/docs/MDN/Contribute/Guidelines/Code_guidelines/Shell /en-US/docs/MDN/Writing_guidelines/Writing_style_guide/Code_style_guide/Shell -/en-US/docs/MDN/Contribute/Guidelines/Code_samples /en-US/docs/MDN/Writing_guidelines/Writing_style_guide/Code_style_guide +/en-US/docs/MDN/Contribute/Guidelines/Code_guidelines /en-US/docs/MDN/Writing_guidelines/Code_style_guide +/en-US/docs/MDN/Contribute/Guidelines/Code_guidelines/CSS /en-US/docs/MDN/Writing_guidelines/Code_style_guide/CSS +/en-US/docs/MDN/Contribute/Guidelines/Code_guidelines/General /en-US/docs/MDN/Writing_guidelines/Code_style_guide +/en-US/docs/MDN/Contribute/Guidelines/Code_guidelines/HTML /en-US/docs/MDN/Writing_guidelines/Code_style_guide/HTML +/en-US/docs/MDN/Contribute/Guidelines/Code_guidelines/JavaScript /en-US/docs/MDN/Writing_guidelines/Code_style_guide/JavaScript +/en-US/docs/MDN/Contribute/Guidelines/Code_guidelines/Shell /en-US/docs/MDN/Writing_guidelines/Code_style_guide/Shell +/en-US/docs/MDN/Contribute/Guidelines/Code_samples /en-US/docs/MDN/Writing_guidelines/Code_style_guide /en-US/docs/MDN/Contribute/Guidelines/Content /en-US/docs/MDN/Writing_guidelines/What_we_write /en-US/docs/MDN/Contribute/Guidelines/Content_blocks /en-US/docs/MDN/Writing_guidelines/Howto/Markdown_in_MDN /en-US/docs/MDN/Contribute/Guidelines/Conventions_definitions /en-US/docs/MDN/Writing_guidelines/Experimental_deprecated_obsolete @@ -5883,7 +5940,7 @@ /en-US/docs/MDN/Contribute/Processes/Matching_features_to_browser_versiosn https://github.com/mdn/browser-compat-data/blob/main/docs/matching-browser-releases/index.md /en-US/docs/MDN/Contribute/Processes/Short_surveys /en-US/docs/MDN/Community/Getting_started /en-US/docs/MDN/Contribute/Processes/Workstream_assessment_project /en-US/docs/MDN/Community/Getting_started -/en-US/docs/MDN/Contribute/Sample_app_coding_guidelines /en-US/docs/MDN/Writing_guidelines/Writing_style_guide/Code_style_guide +/en-US/docs/MDN/Contribute/Sample_app_coding_guidelines /en-US/docs/MDN/Writing_guidelines/Code_style_guide /en-US/docs/MDN/Contribute/Sample_server /en-US/docs/MDN /en-US/docs/MDN/Contribute/Structures /en-US/docs/MDN/Writing_guidelines/Page_structures /en-US/docs/MDN/Contribute/Structures/:-ms-input-placeholder_pseudo-class /en-US/docs/Web/CSS/:placeholder-shown @@ -5935,12 +5992,12 @@ /en-US/docs/MDN/Getting_started /en-US/docs/MDN/Community/Getting_started /en-US/docs/MDN/Guidelines /en-US/docs/MDN/Writing_guidelines /en-US/docs/MDN/Guidelines/CSS_style_guide /en-US/docs/MDN/Writing_guidelines/Howto/Markdown_in_MDN -/en-US/docs/MDN/Guidelines/Code_guidelines /en-US/docs/MDN/Writing_guidelines/Writing_style_guide/Code_style_guide -/en-US/docs/MDN/Guidelines/Code_guidelines/CSS /en-US/docs/MDN/Writing_guidelines/Writing_style_guide/Code_style_guide/CSS -/en-US/docs/MDN/Guidelines/Code_guidelines/General /en-US/docs/MDN/Writing_guidelines/Writing_style_guide/Code_style_guide -/en-US/docs/MDN/Guidelines/Code_guidelines/HTML /en-US/docs/MDN/Writing_guidelines/Writing_style_guide/Code_style_guide/HTML -/en-US/docs/MDN/Guidelines/Code_guidelines/JavaScript /en-US/docs/MDN/Writing_guidelines/Writing_style_guide/Code_style_guide/JavaScript -/en-US/docs/MDN/Guidelines/Code_guidelines/Shell /en-US/docs/MDN/Writing_guidelines/Writing_style_guide/Code_style_guide/Shell +/en-US/docs/MDN/Guidelines/Code_guidelines /en-US/docs/MDN/Writing_guidelines/Code_style_guide +/en-US/docs/MDN/Guidelines/Code_guidelines/CSS /en-US/docs/MDN/Writing_guidelines/Code_style_guide/CSS +/en-US/docs/MDN/Guidelines/Code_guidelines/General /en-US/docs/MDN/Writing_guidelines/Code_style_guide +/en-US/docs/MDN/Guidelines/Code_guidelines/HTML /en-US/docs/MDN/Writing_guidelines/Code_style_guide/HTML +/en-US/docs/MDN/Guidelines/Code_guidelines/JavaScript /en-US/docs/MDN/Writing_guidelines/Code_style_guide/JavaScript +/en-US/docs/MDN/Guidelines/Code_guidelines/Shell /en-US/docs/MDN/Writing_guidelines/Code_style_guide/Shell /en-US/docs/MDN/Guidelines/Content /en-US/docs/MDN/Writing_guidelines/What_we_write /en-US/docs/MDN/Guidelines/Conventions_definitions /en-US/docs/MDN/Writing_guidelines/Experimental_deprecated_obsolete /en-US/docs/MDN/Guidelines/Does_this_belong_on_MDN /en-US/docs/MDN/Writing_guidelines/What_we_write @@ -6005,7 +6062,13 @@ /en-US/docs/MDN/Writing_guidelines/Howto/Tag /en-US/docs/MDN/Writing_guidelines/Howto /en-US/docs/MDN/Writing_guidelines/Page_structures/Quicklinks /en-US/docs/MDN/Writing_guidelines/Page_structures/Sidebars /en-US/docs/MDN/Writing_guidelines/Research_technology /en-US/docs/MDN/Writing_guidelines/Howto/Research_technology -/en-US/docs/MDN/Writing_guidelines/What_we_write/Inclusion_criteria /en-US/docs/MDN/Writing_guidelines/What_we_write/Criteria_for_inclusion +/en-US/docs/MDN/Writing_guidelines/What_we_write/Criteria_for_inclusion /en-US/docs/MDN/Writing_guidelines/Criteria_for_inclusion +/en-US/docs/MDN/Writing_guidelines/What_we_write/Inclusion_criteria /en-US/docs/MDN/Writing_guidelines/Criteria_for_inclusion +/en-US/docs/MDN/Writing_guidelines/Writing_style_guide/Code_style_guide /en-US/docs/MDN/Writing_guidelines/Code_style_guide +/en-US/docs/MDN/Writing_guidelines/Writing_style_guide/Code_style_guide/CSS /en-US/docs/MDN/Writing_guidelines/Code_style_guide/CSS +/en-US/docs/MDN/Writing_guidelines/Writing_style_guide/Code_style_guide/HTML /en-US/docs/MDN/Writing_guidelines/Code_style_guide/HTML +/en-US/docs/MDN/Writing_guidelines/Writing_style_guide/Code_style_guide/JavaScript /en-US/docs/MDN/Writing_guidelines/Code_style_guide/JavaScript +/en-US/docs/MDN/Writing_guidelines/Writing_style_guide/Code_style_guide/Shell /en-US/docs/MDN/Writing_guidelines/Code_style_guide/Shell /en-US/docs/MDN/Yari https://github.com/mdn/yari/tree/main/docs /en-US/docs/MDN_at_ten https://developer.mozilla.org/en-US/about#our_journey /en-US/docs/MDN_at_ten/Contributing_to_MDN /en-US/docs/MDN/Community/Getting_started @@ -6015,44 +6078,44 @@ /en-US/docs/Managing_screen_orientation /en-US/docs/Web/API/CSS_Object_Model/Managing_screen_orientation /en-US/docs/Manipulating_video_using_canvas /en-US/docs/Web/API/Canvas_API/Manipulating_video_using_canvas /en-US/docs/MathML /en-US/docs/Web/MathML -/en-US/docs/MathML/Attributes /en-US/docs/Web/MathML/Attribute -/en-US/docs/MathML/Attributes/Values /en-US/docs/Web/MathML/Values -/en-US/docs/MathML/Element /en-US/docs/Web/MathML/Element -/en-US/docs/MathML/Element/maction /en-US/docs/Web/MathML/Element/maction -/en-US/docs/MathML/Element/math /en-US/docs/Web/MathML/Element/math -/en-US/docs/MathML/Element/menclose /en-US/docs/Web/MathML/Element/menclose -/en-US/docs/MathML/Element/menclosed /en-US/docs/Web/MathML/Element/menclose -/en-US/docs/MathML/Element/merror /en-US/docs/Web/MathML/Element/merror -/en-US/docs/MathML/Element/mfenced /en-US/docs/Web/MathML/Element/mfenced -/en-US/docs/MathML/Element/mfrac /en-US/docs/Web/MathML/Element/mfrac -/en-US/docs/MathML/Element/mi /en-US/docs/Web/MathML/Element/mi -/en-US/docs/MathML/Element/mmultiscripts /en-US/docs/Web/MathML/Element/mmultiscripts -/en-US/docs/MathML/Element/mn /en-US/docs/Web/MathML/Element/mn -/en-US/docs/MathML/Element/mo /en-US/docs/Web/MathML/Element/mo -/en-US/docs/MathML/Element/mover /en-US/docs/Web/MathML/Element/mover -/en-US/docs/MathML/Element/mpadded /en-US/docs/Web/MathML/Element/mpadded -/en-US/docs/MathML/Element/mphantom /en-US/docs/Web/MathML/Element/mphantom -/en-US/docs/MathML/Element/mroot /en-US/docs/Web/MathML/Element/mroot -/en-US/docs/MathML/Element/mrow /en-US/docs/Web/MathML/Element/mrow -/en-US/docs/MathML/Element/ms /en-US/docs/Web/MathML/Element/ms -/en-US/docs/MathML/Element/mspace /en-US/docs/Web/MathML/Element/mspace -/en-US/docs/MathML/Element/msqrt /en-US/docs/Web/MathML/Element/msqrt -/en-US/docs/MathML/Element/mstyle /en-US/docs/Web/MathML/Element/mstyle -/en-US/docs/MathML/Element/msub /en-US/docs/Web/MathML/Element/msub -/en-US/docs/MathML/Element/msubsup /en-US/docs/Web/MathML/Element/msubsup -/en-US/docs/MathML/Element/msup /en-US/docs/Web/MathML/Element/msup -/en-US/docs/MathML/Element/mtable /en-US/docs/Web/MathML/Element/mtable -/en-US/docs/MathML/Element/mtd /en-US/docs/Web/MathML/Element/mtd -/en-US/docs/MathML/Element/mtext /en-US/docs/Web/MathML/Element/mtext -/en-US/docs/MathML/Element/mtr /en-US/docs/Web/MathML/Element/mtr -/en-US/docs/MathML/Element/munder /en-US/docs/Web/MathML/Element/munder -/en-US/docs/MathML/Element/munderover /en-US/docs/Web/MathML/Element/munderover -/en-US/docs/MathML/Element/semantics /en-US/docs/Web/MathML/Element/semantics -/en-US/docs/MathML/Examples /en-US/docs/Web/MathML/Examples -/en-US/docs/MathML/Examples/Deriving_the_Quadratic_Formula /en-US/docs/Web/MathML/Examples/Deriving_the_Quadratic_Formula -/en-US/docs/MathML/Examples/MathML_Pythagorean_Theorem /en-US/docs/Web/MathML/Examples/MathML_Pythagorean_Theorem -/en-US/docs/Math_ML_Deriving_the_Quadratic_Formula /en-US/docs/Web/MathML/Examples/Deriving_the_Quadratic_Formula -/en-US/docs/Math_Rendering /en-US/docs/Web/MathML/Examples/MathML_Pythagorean_Theorem +/en-US/docs/MathML/Attributes /en-US/docs/Web/MathML/Reference/Attribute +/en-US/docs/MathML/Attributes/Values /en-US/docs/Web/MathML/Reference/Values +/en-US/docs/MathML/Element /en-US/docs/Web/MathML/Reference/Element +/en-US/docs/MathML/Element/maction /en-US/docs/Web/MathML/Reference/Element/maction +/en-US/docs/MathML/Element/math /en-US/docs/Web/MathML/Reference/Element/math +/en-US/docs/MathML/Element/menclose /en-US/docs/Web/MathML/Reference/Element/menclose +/en-US/docs/MathML/Element/menclosed /en-US/docs/Web/MathML/Reference/Element/menclose +/en-US/docs/MathML/Element/merror /en-US/docs/Web/MathML/Reference/Element/merror +/en-US/docs/MathML/Element/mfenced /en-US/docs/Web/MathML/Reference/Element/mfenced +/en-US/docs/MathML/Element/mfrac /en-US/docs/Web/MathML/Reference/Element/mfrac +/en-US/docs/MathML/Element/mi /en-US/docs/Web/MathML/Reference/Element/mi +/en-US/docs/MathML/Element/mmultiscripts /en-US/docs/Web/MathML/Reference/Element/mmultiscripts +/en-US/docs/MathML/Element/mn /en-US/docs/Web/MathML/Reference/Element/mn +/en-US/docs/MathML/Element/mo /en-US/docs/Web/MathML/Reference/Element/mo +/en-US/docs/MathML/Element/mover /en-US/docs/Web/MathML/Reference/Element/mover +/en-US/docs/MathML/Element/mpadded /en-US/docs/Web/MathML/Reference/Element/mpadded +/en-US/docs/MathML/Element/mphantom /en-US/docs/Web/MathML/Reference/Element/mphantom +/en-US/docs/MathML/Element/mroot /en-US/docs/Web/MathML/Reference/Element/mroot +/en-US/docs/MathML/Element/mrow /en-US/docs/Web/MathML/Reference/Element/mrow +/en-US/docs/MathML/Element/ms /en-US/docs/Web/MathML/Reference/Element/ms +/en-US/docs/MathML/Element/mspace /en-US/docs/Web/MathML/Reference/Element/mspace +/en-US/docs/MathML/Element/msqrt /en-US/docs/Web/MathML/Reference/Element/msqrt +/en-US/docs/MathML/Element/mstyle /en-US/docs/Web/MathML/Reference/Element/mstyle +/en-US/docs/MathML/Element/msub /en-US/docs/Web/MathML/Reference/Element/msub +/en-US/docs/MathML/Element/msubsup /en-US/docs/Web/MathML/Reference/Element/msubsup +/en-US/docs/MathML/Element/msup /en-US/docs/Web/MathML/Reference/Element/msup +/en-US/docs/MathML/Element/mtable /en-US/docs/Web/MathML/Reference/Element/mtable +/en-US/docs/MathML/Element/mtd /en-US/docs/Web/MathML/Reference/Element/mtd +/en-US/docs/MathML/Element/mtext /en-US/docs/Web/MathML/Reference/Element/mtext +/en-US/docs/MathML/Element/mtr /en-US/docs/Web/MathML/Reference/Element/mtr +/en-US/docs/MathML/Element/munder /en-US/docs/Web/MathML/Reference/Element/munder +/en-US/docs/MathML/Element/munderover /en-US/docs/Web/MathML/Reference/Element/munderover +/en-US/docs/MathML/Element/semantics /en-US/docs/Web/MathML/Reference/Element/semantics +/en-US/docs/MathML/Examples /en-US/docs/Web/MathML/Guides +/en-US/docs/MathML/Examples/Deriving_the_Quadratic_Formula /en-US/docs/Web/MathML/Guides/Deriving_the_quadratic_formula +/en-US/docs/MathML/Examples/MathML_Pythagorean_Theorem /en-US/docs/Web/MathML/Guides/Proving_the_Pythagorean_theorem +/en-US/docs/Math_ML_Deriving_the_Quadratic_Formula /en-US/docs/Web/MathML/Guides/Deriving_the_quadratic_formula +/en-US/docs/Math_Rendering /en-US/docs/Web/MathML/Guides/Proving_the_Pythagorean_theorem /en-US/docs/Media_Capabilities_API /en-US/docs/Web/API/Media_Capabilities_API /en-US/docs/Media_Capabilities_API/decodingInfo /en-US/docs/Web/API/MediaCapabilities/decodingInfo /en-US/docs/Media_Capabilities_API/encodingInfo /en-US/docs/Web/API/MediaCapabilities/encodingInfo @@ -6063,7 +6126,7 @@ /en-US/docs/Memory_Sanitizer https://firefox-source-docs.mozilla.org/tools/sanitizer/memory_sanitizer.html#memory-sanitizer /en-US/docs/Mobile/Mobile_Web_Development /en-US/docs/Learn_web_development/Core/CSS_layout/Responsive_Design /en-US/docs/MouseEvent.initMouseEvent /en-US/docs/Web/API/MouseEvent/initMouseEvent -/en-US/docs/Mozilla's_Quirks_Mode /en-US/docs/Web/HTML/Quirks_Mode_and_Standards_Mode +/en-US/docs/Mozilla's_Quirks_Mode /en-US/docs/Web/HTML/Guides/Quirks_mode_and_standards_mode /en-US/docs/Mozilla/Add-ons/AMO/Policy https://extensionworkshop.com/documentation/publish/add-on-policies/ /en-US/docs/Mozilla/Add-ons/Themes https://extensionworkshop.com/documentation/themes/ /en-US/docs/Mozilla/Add-ons/Themes/Theme_concepts https://extensionworkshop.com/documentation/themes/ @@ -6146,6 +6209,7 @@ /en-US/docs/Mozilla/Add-ons/WebExtensions/Alternative_methods_of_installing_add-ons/Sideloading_add-ons https://extensionworkshop.com/documentation/publish/distribute-sideloading/ /en-US/docs/Mozilla/Add-ons/WebExtensions/Browser_action /en-US/docs/Mozilla/Add-ons/WebExtensions/user_interface/Toolbar_button /en-US/docs/Mozilla/Add-ons/WebExtensions/Browser_actions /en-US/docs/Mozilla/Add-ons/WebExtensions/user_interface/Toolbar_button +/en-US/docs/Mozilla/Add-ons/WebExtensions/Browser_compatibility_for_manifest.json /en-US/docs/Mozilla/Add-ons/WebExtensions/manifest.json#browser_compatibility /en-US/docs/Mozilla/Add-ons/WebExtensions/Build_a_cross_browser_extension_ /en-US/docs/Mozilla/Add-ons/WebExtensions/Build_a_cross_browser_extension /en-US/docs/Mozilla/Add-ons/WebExtensions/Building_a_cross_browser_extension /en-US/docs/Mozilla/Add-ons/WebExtensions/Build_a_cross_browser_extension /en-US/docs/Mozilla/Add-ons/WebExtensions/Context_menu_items /en-US/docs/Mozilla/Add-ons/WebExtensions/user_interface/Context_menu_items @@ -6207,7 +6271,7 @@ /en-US/docs/Mozilla/Firefox/Releases/Firefox_41_for_developers /en-US/docs/Mozilla/Firefox/Releases/41 /en-US/docs/Mozilla/Firefox/Releases/Firefox_47_for_developers /en-US/docs/Mozilla/Firefox/Releases/47 /en-US/docs/Mozilla/Firefox/Releases/developers /en-US/docs/Mozilla/Firefox/Releases/63 -/en-US/docs/Mozilla/MathML_Project/Fonts /en-US/docs/Web/MathML/Fonts +/en-US/docs/Mozilla/MathML_Project/Fonts /en-US/docs/Web/MathML/Guides/Fonts /en-US/docs/Mozilla/Performance/Profiling_with_the_Built-in_Profiler https://firefox-source-docs.mozilla.org/devtools-user/performance/index.html /en-US/docs/Mozilla/Performance/Scroll-linked_effects https://firefox-source-docs.mozilla.org/performance/scroll-linked_effects.html /en-US/docs/Mozilla/Projects/NSPR https://firefox-source-docs.mozilla.org/nspr/index.html @@ -6610,8 +6674,8 @@ /en-US/docs/Mozilla/Thunderbird/Autoconfiguration/FileFormat/HowTo https://www.bucksch.org/1/projects/thunderbird/autoconfiguration/how-to-create-your-own-config-file.html /en-US/docs/Mozilla/Virtualenv https://github.com/mdn/archived-content/tree/main/files/en-us/mozilla/virtualenv /en-US/docs/Mozilla_CSS_Extensions /en-US/docs/Web/CSS/Mozilla_Extensions -/en-US/docs/Mozilla_MathML_Project/Authoring /en-US/docs/Web/MathML/Authoring -/en-US/docs/Mozilla_MathML_Project/Authoring_MathML /en-US/docs/Web/MathML/Authoring +/en-US/docs/Mozilla_MathML_Project/Authoring /en-US/docs/Web/MathML/Guides/Authoring +/en-US/docs/Mozilla_MathML_Project/Authoring_MathML /en-US/docs/Web/MathML/Guides/Authoring /en-US/docs/Mozilla_event_reference /en-US/docs/Web/Events /en-US/docs/Mozilla_event_reference/DOMContentLoaded_(event) /en-US/docs/Web/API/Document/DOMContentLoaded_event /en-US/docs/Mozilla_event_reference/DOMContentLoading (event) /en-US/docs/Web/API/Document/DOMContentLoaded_event @@ -6775,7 +6839,7 @@ /en-US/docs/NavigatorUserMedia /en-US/docs/Web/API/Navigator/getUserMedia /en-US/docs/NavigatorUserMedia.getUserMedia /en-US/docs/Web/API/Navigator/getUserMedia /en-US/docs/NavigatorUserMedia.mediaDevices /en-US/docs/Web/API/Navigator/mediaDevices -/en-US/docs/Netscape_Gecko_User_Agent_Strings /en-US/docs/Web/HTTP/Headers/User-Agent/Firefox +/en-US/docs/Netscape_Gecko_User_Agent_Strings /en-US/docs/Web/HTTP/Reference/Headers/User-Agent/Firefox /en-US/docs/Node_server_without_framework /en-US/docs/Learn_web_development/Extensions/Server-side/Node_server_without_framework /en-US/docs/Notable_bugs_fixed_in_Firefox_3 /en-US/docs/Mozilla/Firefox/Releases/3/Notable_bugs_fixed /en-US/docs/Online/Offline_Events /en-US/docs/Web/API/Navigator/onLine @@ -6829,9 +6893,9 @@ /en-US/docs/Python /en-US/docs/Learn_web_development/Extensions/Server-side/Django /en-US/docs/Python/Virtualenv https://github.com/mdn/archived-content/tree/main/files/en-us/mozilla/virtualenv /en-US/docs/Python_binding_for_NSS https://firefox-source-docs.mozilla.org/security/nss/index.html -/en-US/docs/Quirks_Mode_and_Standards_Mode /en-US/docs/Web/HTML/Quirks_Mode_and_Standards_Mode -/en-US/docs/Quirks_Mode_and_Standards_Mode/Quirks_Mode_and_Standards_Mode /en-US/docs/Web/HTML/Quirks_Mode_and_Standards_Mode -/en-US/docs/Quirks_Mode_and_Standards_Mode1/Quirks_Mode_and_Standards_Mode /en-US/docs/Web/HTML/Quirks_Mode_and_Standards_Mode +/en-US/docs/Quirks_Mode_and_Standards_Mode /en-US/docs/Web/HTML/Guides/Quirks_mode_and_standards_mode +/en-US/docs/Quirks_Mode_and_Standards_Mode/Quirks_Mode_and_Standards_Mode /en-US/docs/Web/HTML/Guides/Quirks_mode_and_standards_mode +/en-US/docs/Quirks_Mode_and_Standards_Mode1/Quirks_Mode_and_Standards_Mode /en-US/docs/Web/HTML/Guides/Quirks_mode_and_standards_mode /en-US/docs/RandomSource.getRandomValues /en-US/docs/Web/API/Crypto/getRandomValues /en-US/docs/Range /en-US/docs/Web/API/Range /en-US/docs/Range/Range /en-US/docs/Web/API/Range/Range @@ -6868,322 +6932,322 @@ /en-US/docs/Range/toString /en-US/docs/Web/API/Range/toString /en-US/docs/ReadableStream /en-US/docs/Web/API/ReadableStream /en-US/docs/Regexp/match /en-US/docs/Web/XML/EXSLT/Reference/regexp/match -/en-US/docs/Related/Criteria_for_inclusion /en-US/docs/MDN/Writing_guidelines/What_we_write/Criteria_for_inclusion +/en-US/docs/Related/Criteria_for_inclusion /en-US/docs/MDN/Writing_guidelines/Criteria_for_inclusion /en-US/docs/Related/IMSC/Layout_in_IMSC /en-US/docs/Related/IMSC/Subtitle_placement /en-US/docs/Related/IMSC/Mapping_Time_Code_to_IMSC /en-US/docs/Related/IMSC/Mapping_video_time_codes_to_IMSC /en-US/docs/Related/IMSC/Using_imscJS_as_polyfill /en-US/docs/Related/IMSC/Using_the_imscJS_polyfill -/en-US/docs/Related/Process_for_selection /en-US/docs/MDN/Writing_guidelines/What_we_write/Criteria_for_inclusion -/en-US/docs/Related/Project_guidelines /en-US/docs/MDN/Writing_guidelines/What_we_write/Criteria_for_inclusion +/en-US/docs/Related/Process_for_selection /en-US/docs/MDN/Writing_guidelines/Criteria_for_inclusion +/en-US/docs/Related/Project_guidelines /en-US/docs/MDN/Writing_guidelines/Criteria_for_inclusion /en-US/docs/Resource_Timing_API /en-US/docs/Web/API/Performance_API/Resource_timing /en-US/docs/SGML /en-US/docs/Glossary/SGML /en-US/docs/SMTP /en-US/docs/Glossary/SMTP /en-US/docs/SVG /en-US/docs/Web/SVG /en-US/docs/SVG-TEST /en-US/docs/Web/SVG -/en-US/docs/SVG/Attribute /en-US/docs/Web/SVG/Attribute -/en-US/docs/SVG/Attribute/From /en-US/docs/Web/SVG/Attribute/From -/en-US/docs/SVG/Attribute/To /en-US/docs/Web/SVG/Attribute/To -/en-US/docs/SVG/Attribute/accent-height /en-US/docs/Web/SVG/Attribute/accent-height -/en-US/docs/SVG/Attribute/accumulate /en-US/docs/Web/SVG/Attribute/accumulate -/en-US/docs/SVG/Attribute/additive /en-US/docs/Web/SVG/Attribute/additive -/en-US/docs/SVG/Attribute/alignment-baseline /en-US/docs/Web/SVG/Attribute/alignment-baseline -/en-US/docs/SVG/Attribute/ascent /en-US/docs/Web/SVG/Attribute/ascent -/en-US/docs/SVG/Attribute/attributeName /en-US/docs/Web/SVG/Attribute/attributeName -/en-US/docs/SVG/Attribute/attributeType /en-US/docs/Web/SVG/Attribute/attributeType -/en-US/docs/SVG/Attribute/azimuth /en-US/docs/Web/SVG/Attribute/azimuth -/en-US/docs/SVG/Attribute/baseFrequency /en-US/docs/Web/SVG/Attribute/baseFrequency -/en-US/docs/SVG/Attribute/baseline-shift /en-US/docs/Web/SVG/Attribute/baseline-shift -/en-US/docs/SVG/Attribute/begin /en-US/docs/Web/SVG/Attribute/begin -/en-US/docs/SVG/Attribute/bias /en-US/docs/Web/SVG/Attribute/bias -/en-US/docs/SVG/Attribute/calcMode /en-US/docs/Web/SVG/Attribute/calcMode -/en-US/docs/SVG/Attribute/class /en-US/docs/Web/SVG/Attribute/class -/en-US/docs/SVG/Attribute/clip /en-US/docs/Web/SVG/Attribute/clip -/en-US/docs/SVG/Attribute/clip-path /en-US/docs/Web/SVG/Attribute/clip-path -/en-US/docs/SVG/Attribute/clip-rule /en-US/docs/Web/SVG/Attribute/clip-rule -/en-US/docs/SVG/Attribute/clipPathUnits /en-US/docs/Web/SVG/Attribute/clipPathUnits -/en-US/docs/SVG/Attribute/color /en-US/docs/Web/SVG/Attribute/color -/en-US/docs/SVG/Attribute/color-interpolation /en-US/docs/Web/SVG/Attribute/color-interpolation -/en-US/docs/SVG/Attribute/color-interpolation-filters /en-US/docs/Web/SVG/Attribute/color-interpolation-filters -/en-US/docs/SVG/Attribute/cursor /en-US/docs/Web/SVG/Attribute/cursor -/en-US/docs/SVG/Attribute/cx /en-US/docs/Web/SVG/Attribute/cx -/en-US/docs/SVG/Attribute/cy /en-US/docs/Web/SVG/Attribute/cy -/en-US/docs/SVG/Attribute/d /en-US/docs/Web/SVG/Attribute/d -/en-US/docs/SVG/Attribute/diffuseConstant /en-US/docs/Web/SVG/Attribute/diffuseConstant -/en-US/docs/SVG/Attribute/direction /en-US/docs/Web/SVG/Attribute/direction -/en-US/docs/SVG/Attribute/display /en-US/docs/Web/SVG/Attribute/display -/en-US/docs/SVG/Attribute/divisor /en-US/docs/Web/SVG/Attribute/divisor -/en-US/docs/SVG/Attribute/dominant-baseline /en-US/docs/Web/SVG/Attribute/dominant-baseline -/en-US/docs/SVG/Attribute/dur /en-US/docs/Web/SVG/Attribute/dur -/en-US/docs/SVG/Attribute/dx /en-US/docs/Web/SVG/Attribute/dx -/en-US/docs/SVG/Attribute/dy /en-US/docs/Web/SVG/Attribute/dy -/en-US/docs/SVG/Attribute/edgeMode /en-US/docs/Web/SVG/Attribute/edgeMode -/en-US/docs/SVG/Attribute/elevation /en-US/docs/Web/SVG/Attribute/elevation -/en-US/docs/SVG/Attribute/end /en-US/docs/Web/SVG/Attribute/end -/en-US/docs/SVG/Attribute/fill /en-US/docs/Web/SVG/Attribute/fill -/en-US/docs/SVG/Attribute/fill-opacity /en-US/docs/Web/SVG/Attribute/fill-opacity -/en-US/docs/SVG/Attribute/fill-rule /en-US/docs/Web/SVG/Attribute/fill-rule -/en-US/docs/SVG/Attribute/filter /en-US/docs/Web/SVG/Attribute/filter -/en-US/docs/SVG/Attribute/filterUnits /en-US/docs/Web/SVG/Attribute/filterUnits -/en-US/docs/SVG/Attribute/flood-color /en-US/docs/Web/SVG/Attribute/flood-color -/en-US/docs/SVG/Attribute/flood-opacity /en-US/docs/Web/SVG/Attribute/flood-opacity -/en-US/docs/SVG/Attribute/font-family /en-US/docs/Web/SVG/Attribute/font-family -/en-US/docs/SVG/Attribute/font-size /en-US/docs/Web/SVG/Attribute/font-size -/en-US/docs/SVG/Attribute/font-size-adjust /en-US/docs/Web/SVG/Attribute/font-size-adjust -/en-US/docs/SVG/Attribute/font-stretch /en-US/docs/Web/SVG/Attribute/font-stretch -/en-US/docs/SVG/Attribute/font-style /en-US/docs/Web/SVG/Attribute/font-style -/en-US/docs/SVG/Attribute/font-variant /en-US/docs/Web/SVG/Attribute/font-variant -/en-US/docs/SVG/Attribute/font-weight /en-US/docs/Web/SVG/Attribute/font-weight -/en-US/docs/SVG/Attribute/gradientTransform /en-US/docs/Web/SVG/Attribute/gradientTransform -/en-US/docs/SVG/Attribute/gradientUnits /en-US/docs/Web/SVG/Attribute/gradientUnits -/en-US/docs/SVG/Attribute/height /en-US/docs/Web/SVG/Attribute/height -/en-US/docs/SVG/Attribute/image-rendering /en-US/docs/Web/SVG/Attribute/image-rendering -/en-US/docs/SVG/Attribute/in /en-US/docs/Web/SVG/Attribute/in -/en-US/docs/SVG/Attribute/in2 /en-US/docs/Web/SVG/Attribute/in2 -/en-US/docs/SVG/Attribute/k1 /en-US/docs/Web/SVG/Attribute/k1 -/en-US/docs/SVG/Attribute/k2 /en-US/docs/Web/SVG/Attribute/k2 -/en-US/docs/SVG/Attribute/k3 /en-US/docs/Web/SVG/Attribute/k3 -/en-US/docs/SVG/Attribute/k4 /en-US/docs/Web/SVG/Attribute/k4 -/en-US/docs/SVG/Attribute/kernelMatrix /en-US/docs/Web/SVG/Attribute/kernelMatrix -/en-US/docs/SVG/Attribute/kernelUnitLength /en-US/docs/Web/SVG/Attribute/kernelUnitLength +/en-US/docs/SVG/Attribute /en-US/docs/Web/SVG/Reference/Attribute +/en-US/docs/SVG/Attribute/From /en-US/docs/Web/SVG/Reference/Attribute/From +/en-US/docs/SVG/Attribute/To /en-US/docs/Web/SVG/Reference/Attribute/To +/en-US/docs/SVG/Attribute/accent-height /en-US/docs/Web/SVG/Reference/Attribute +/en-US/docs/SVG/Attribute/accumulate /en-US/docs/Web/SVG/Reference/Attribute/accumulate +/en-US/docs/SVG/Attribute/additive /en-US/docs/Web/SVG/Reference/Attribute/additive +/en-US/docs/SVG/Attribute/alignment-baseline /en-US/docs/Web/SVG/Reference/Attribute/alignment-baseline +/en-US/docs/SVG/Attribute/ascent /en-US/docs/Web/SVG/Reference/Attribute +/en-US/docs/SVG/Attribute/attributeName /en-US/docs/Web/SVG/Reference/Attribute/attributeName +/en-US/docs/SVG/Attribute/attributeType /en-US/docs/Web/SVG/Reference/Attribute/attributeType +/en-US/docs/SVG/Attribute/azimuth /en-US/docs/Web/SVG/Reference/Attribute/azimuth +/en-US/docs/SVG/Attribute/baseFrequency /en-US/docs/Web/SVG/Reference/Attribute/baseFrequency +/en-US/docs/SVG/Attribute/baseline-shift /en-US/docs/Web/SVG/Reference/Attribute/baseline-shift +/en-US/docs/SVG/Attribute/begin /en-US/docs/Web/SVG/Reference/Attribute/begin +/en-US/docs/SVG/Attribute/bias /en-US/docs/Web/SVG/Reference/Attribute/bias +/en-US/docs/SVG/Attribute/calcMode /en-US/docs/Web/SVG/Reference/Attribute/calcMode +/en-US/docs/SVG/Attribute/class /en-US/docs/Web/SVG/Reference/Attribute/class +/en-US/docs/SVG/Attribute/clip /en-US/docs/Web/SVG/Reference/Attribute/clip +/en-US/docs/SVG/Attribute/clip-path /en-US/docs/Web/SVG/Reference/Attribute/clip-path +/en-US/docs/SVG/Attribute/clip-rule /en-US/docs/Web/SVG/Reference/Attribute/clip-rule +/en-US/docs/SVG/Attribute/clipPathUnits /en-US/docs/Web/SVG/Reference/Attribute/clipPathUnits +/en-US/docs/SVG/Attribute/color /en-US/docs/Web/SVG/Reference/Attribute/color +/en-US/docs/SVG/Attribute/color-interpolation /en-US/docs/Web/SVG/Reference/Attribute/color-interpolation +/en-US/docs/SVG/Attribute/color-interpolation-filters /en-US/docs/Web/SVG/Reference/Attribute/color-interpolation-filters +/en-US/docs/SVG/Attribute/cursor /en-US/docs/Web/SVG/Reference/Attribute/cursor +/en-US/docs/SVG/Attribute/cx /en-US/docs/Web/SVG/Reference/Attribute/cx +/en-US/docs/SVG/Attribute/cy /en-US/docs/Web/SVG/Reference/Attribute/cy +/en-US/docs/SVG/Attribute/d /en-US/docs/Web/SVG/Reference/Attribute/d +/en-US/docs/SVG/Attribute/diffuseConstant /en-US/docs/Web/SVG/Reference/Attribute/diffuseConstant +/en-US/docs/SVG/Attribute/direction /en-US/docs/Web/SVG/Reference/Attribute/direction +/en-US/docs/SVG/Attribute/display /en-US/docs/Web/SVG/Reference/Attribute/display +/en-US/docs/SVG/Attribute/divisor /en-US/docs/Web/SVG/Reference/Attribute/divisor +/en-US/docs/SVG/Attribute/dominant-baseline /en-US/docs/Web/SVG/Reference/Attribute/dominant-baseline +/en-US/docs/SVG/Attribute/dur /en-US/docs/Web/SVG/Reference/Attribute/dur +/en-US/docs/SVG/Attribute/dx /en-US/docs/Web/SVG/Reference/Attribute/dx +/en-US/docs/SVG/Attribute/dy /en-US/docs/Web/SVG/Reference/Attribute/dy +/en-US/docs/SVG/Attribute/edgeMode /en-US/docs/Web/SVG/Reference/Attribute/edgeMode +/en-US/docs/SVG/Attribute/elevation /en-US/docs/Web/SVG/Reference/Attribute/elevation +/en-US/docs/SVG/Attribute/end /en-US/docs/Web/SVG/Reference/Attribute/end +/en-US/docs/SVG/Attribute/fill /en-US/docs/Web/SVG/Reference/Attribute/fill +/en-US/docs/SVG/Attribute/fill-opacity /en-US/docs/Web/SVG/Reference/Attribute/fill-opacity +/en-US/docs/SVG/Attribute/fill-rule /en-US/docs/Web/SVG/Reference/Attribute/fill-rule +/en-US/docs/SVG/Attribute/filter /en-US/docs/Web/SVG/Reference/Attribute/filter +/en-US/docs/SVG/Attribute/filterUnits /en-US/docs/Web/SVG/Reference/Attribute/filterUnits +/en-US/docs/SVG/Attribute/flood-color /en-US/docs/Web/SVG/Reference/Attribute/flood-color +/en-US/docs/SVG/Attribute/flood-opacity /en-US/docs/Web/SVG/Reference/Attribute/flood-opacity +/en-US/docs/SVG/Attribute/font-family /en-US/docs/Web/SVG/Reference/Attribute/font-family +/en-US/docs/SVG/Attribute/font-size /en-US/docs/Web/SVG/Reference/Attribute/font-size +/en-US/docs/SVG/Attribute/font-size-adjust /en-US/docs/Web/SVG/Reference/Attribute/font-size-adjust +/en-US/docs/SVG/Attribute/font-stretch /en-US/docs/Web/SVG/Reference/Attribute/font-stretch +/en-US/docs/SVG/Attribute/font-style /en-US/docs/Web/SVG/Reference/Attribute/font-style +/en-US/docs/SVG/Attribute/font-variant /en-US/docs/Web/SVG/Reference/Attribute/font-variant +/en-US/docs/SVG/Attribute/font-weight /en-US/docs/Web/SVG/Reference/Attribute/font-weight +/en-US/docs/SVG/Attribute/gradientTransform /en-US/docs/Web/SVG/Reference/Attribute/gradientTransform +/en-US/docs/SVG/Attribute/gradientUnits /en-US/docs/Web/SVG/Reference/Attribute/gradientUnits +/en-US/docs/SVG/Attribute/height /en-US/docs/Web/SVG/Reference/Attribute/height +/en-US/docs/SVG/Attribute/image-rendering /en-US/docs/Web/SVG/Reference/Attribute/image-rendering +/en-US/docs/SVG/Attribute/in /en-US/docs/Web/SVG/Reference/Attribute/in +/en-US/docs/SVG/Attribute/in2 /en-US/docs/Web/SVG/Reference/Attribute/in2 +/en-US/docs/SVG/Attribute/k1 /en-US/docs/Web/SVG/Reference/Attribute/k1 +/en-US/docs/SVG/Attribute/k2 /en-US/docs/Web/SVG/Reference/Attribute/k2 +/en-US/docs/SVG/Attribute/k3 /en-US/docs/Web/SVG/Reference/Attribute/k3 +/en-US/docs/SVG/Attribute/k4 /en-US/docs/Web/SVG/Reference/Attribute/k4 +/en-US/docs/SVG/Attribute/kernelMatrix /en-US/docs/Web/SVG/Reference/Attribute/kernelMatrix +/en-US/docs/SVG/Attribute/kernelUnitLength /en-US/docs/Web/SVG/Reference/Attribute/kernelUnitLength /en-US/docs/SVG/Attribute/kerning /en-US/docs/Web/CSS/font-kerning -/en-US/docs/SVG/Attribute/keySplines /en-US/docs/Web/SVG/Attribute/keySplines -/en-US/docs/SVG/Attribute/keyTimes /en-US/docs/Web/SVG/Attribute/keyTimes -/en-US/docs/SVG/Attribute/letter-spacing /en-US/docs/Web/SVG/Attribute/letter-spacing -/en-US/docs/SVG/Attribute/lighting-color /en-US/docs/Web/SVG/Attribute/lighting-color -/en-US/docs/SVG/Attribute/limitingConeAngle /en-US/docs/Web/SVG/Attribute/limitingConeAngle -/en-US/docs/SVG/Attribute/marker-end /en-US/docs/Web/SVG/Attribute/marker-end -/en-US/docs/SVG/Attribute/marker-mid /en-US/docs/Web/SVG/Attribute/marker-mid -/en-US/docs/SVG/Attribute/marker-start /en-US/docs/Web/SVG/Attribute/marker-start -/en-US/docs/SVG/Attribute/markerHeight /en-US/docs/Web/SVG/Attribute/markerHeight -/en-US/docs/SVG/Attribute/markerUnits /en-US/docs/Web/SVG/Attribute/markerUnits -/en-US/docs/SVG/Attribute/markerWidth /en-US/docs/Web/SVG/Attribute/markerWidth -/en-US/docs/SVG/Attribute/mask /en-US/docs/Web/SVG/Attribute/mask -/en-US/docs/SVG/Attribute/maskContentUnits /en-US/docs/Web/SVG/Attribute/maskContentUnits -/en-US/docs/SVG/Attribute/maskUnits /en-US/docs/Web/SVG/Attribute/maskUnits -/en-US/docs/SVG/Attribute/max /en-US/docs/Web/SVG/Attribute/max -/en-US/docs/SVG/Attribute/min /en-US/docs/Web/SVG/Attribute/min -/en-US/docs/SVG/Attribute/mode /en-US/docs/Web/SVG/Attribute/mode -/en-US/docs/SVG/Attribute/numOctaves /en-US/docs/Web/SVG/Attribute/numOctaves -/en-US/docs/SVG/Attribute/opacity /en-US/docs/Web/SVG/Attribute/opacity -/en-US/docs/SVG/Attribute/operator /en-US/docs/Web/SVG/Attribute/operator -/en-US/docs/SVG/Attribute/order /en-US/docs/Web/SVG/Attribute/order -/en-US/docs/SVG/Attribute/overflow /en-US/docs/Web/SVG/Attribute/overflow -/en-US/docs/SVG/Attribute/paint-order /en-US/docs/Web/SVG/Attribute/paint-order -/en-US/docs/SVG/Attribute/pathLength /en-US/docs/Web/SVG/Attribute/pathLength -/en-US/docs/SVG/Attribute/patternContentUnits /en-US/docs/Web/SVG/Attribute/patternContentUnits -/en-US/docs/SVG/Attribute/patternTransform /en-US/docs/Web/SVG/Attribute/patternTransform -/en-US/docs/SVG/Attribute/patternUnits /en-US/docs/Web/SVG/Attribute/patternUnits -/en-US/docs/SVG/Attribute/pointer-events /en-US/docs/Web/SVG/Attribute/pointer-events -/en-US/docs/SVG/Attribute/points /en-US/docs/Web/SVG/Attribute/points -/en-US/docs/SVG/Attribute/pointsAtX /en-US/docs/Web/SVG/Attribute/pointsAtX -/en-US/docs/SVG/Attribute/pointsAtY /en-US/docs/Web/SVG/Attribute/pointsAtY -/en-US/docs/SVG/Attribute/pointsAtZ /en-US/docs/Web/SVG/Attribute/pointsAtZ -/en-US/docs/SVG/Attribute/preserveAlpha /en-US/docs/Web/SVG/Attribute/preserveAlpha -/en-US/docs/SVG/Attribute/preserveAspectRatio /en-US/docs/Web/SVG/Attribute/preserveAspectRatio -/en-US/docs/SVG/Attribute/primitiveUnits /en-US/docs/Web/SVG/Attribute/primitiveUnits -/en-US/docs/SVG/Attribute/r /en-US/docs/Web/SVG/Attribute/r -/en-US/docs/SVG/Attribute/radius /en-US/docs/Web/SVG/Attribute/radius -/en-US/docs/SVG/Attribute/repeatCount /en-US/docs/Web/SVG/Attribute/repeatCount -/en-US/docs/SVG/Attribute/repeatDur /en-US/docs/Web/SVG/Attribute/repeatDur -/en-US/docs/SVG/Attribute/requiredFeatures /en-US/docs/Web/SVG/Attribute/requiredFeatures -/en-US/docs/SVG/Attribute/restart /en-US/docs/Web/SVG/Attribute/restart -/en-US/docs/SVG/Attribute/result /en-US/docs/Web/SVG/Attribute/result -/en-US/docs/SVG/Attribute/rx /en-US/docs/Web/SVG/Attribute/rx -/en-US/docs/SVG/Attribute/ry /en-US/docs/Web/SVG/Attribute/ry -/en-US/docs/SVG/Attribute/scale /en-US/docs/Web/SVG/Attribute/scale -/en-US/docs/SVG/Attribute/seed /en-US/docs/Web/SVG/Attribute/seed -/en-US/docs/SVG/Attribute/shape-rendering /en-US/docs/Web/SVG/Attribute/shape-rendering -/en-US/docs/SVG/Attribute/specularConstant /en-US/docs/Web/SVG/Attribute/specularConstant -/en-US/docs/SVG/Attribute/specularExponent /en-US/docs/Web/SVG/Attribute/specularExponent -/en-US/docs/SVG/Attribute/stdDeviation /en-US/docs/Web/SVG/Attribute/stdDeviation -/en-US/docs/SVG/Attribute/stitchTiles /en-US/docs/Web/SVG/Attribute/stitchTiles -/en-US/docs/SVG/Attribute/stop-color /en-US/docs/Web/SVG/Attribute/stop-color -/en-US/docs/SVG/Attribute/stop-opacity /en-US/docs/Web/SVG/Attribute/stop-opacity -/en-US/docs/SVG/Attribute/stroke /en-US/docs/Web/SVG/Attribute/stroke -/en-US/docs/SVG/Attribute/stroke-dasharray /en-US/docs/Web/SVG/Attribute/stroke-dasharray -/en-US/docs/SVG/Attribute/stroke-dashoffset /en-US/docs/Web/SVG/Attribute/stroke-dashoffset -/en-US/docs/SVG/Attribute/stroke-linecap /en-US/docs/Web/SVG/Attribute/stroke-linecap -/en-US/docs/SVG/Attribute/stroke-linejoin /en-US/docs/Web/SVG/Attribute/stroke-linejoin -/en-US/docs/SVG/Attribute/stroke-miterlimit /en-US/docs/Web/SVG/Attribute/stroke-miterlimit -/en-US/docs/SVG/Attribute/stroke-opacity /en-US/docs/Web/SVG/Attribute/stroke-opacity -/en-US/docs/SVG/Attribute/stroke-width /en-US/docs/Web/SVG/Attribute/stroke-width -/en-US/docs/SVG/Attribute/style /en-US/docs/Web/SVG/Attribute/style -/en-US/docs/SVG/Attribute/surfaceScale /en-US/docs/Web/SVG/Attribute/surfaceScale -/en-US/docs/SVG/Attribute/targetX /en-US/docs/Web/SVG/Attribute/targetX -/en-US/docs/SVG/Attribute/targetY /en-US/docs/Web/SVG/Attribute/targetY -/en-US/docs/SVG/Attribute/text-anchor /en-US/docs/Web/SVG/Attribute/text-anchor -/en-US/docs/SVG/Attribute/text-decoration /en-US/docs/Web/SVG/Attribute/text-decoration -/en-US/docs/SVG/Attribute/text-rendering /en-US/docs/Web/SVG/Attribute/text-rendering -/en-US/docs/SVG/Attribute/transform /en-US/docs/Web/SVG/Attribute/transform -/en-US/docs/SVG/Attribute/type /en-US/docs/Web/SVG/Attribute/type -/en-US/docs/SVG/Attribute/values /en-US/docs/Web/SVG/Attribute/values -/en-US/docs/SVG/Attribute/viewBox /en-US/docs/Web/SVG/Attribute/viewBox -/en-US/docs/SVG/Attribute/visibility /en-US/docs/Web/SVG/Attribute/visibility -/en-US/docs/SVG/Attribute/width /en-US/docs/Web/SVG/Attribute/width -/en-US/docs/SVG/Attribute/word-spacing /en-US/docs/Web/SVG/Attribute/word-spacing -/en-US/docs/SVG/Attribute/writing-mode /en-US/docs/Web/SVG/Attribute/writing-mode -/en-US/docs/SVG/Attribute/x /en-US/docs/Web/SVG/Attribute/x -/en-US/docs/SVG/Attribute/x1 /en-US/docs/Web/SVG/Attribute/x1 -/en-US/docs/SVG/Attribute/x2 /en-US/docs/Web/SVG/Attribute/x2 -/en-US/docs/SVG/Attribute/xChannelSelector /en-US/docs/Web/SVG/Attribute/xChannelSelector -/en-US/docs/SVG/Attribute/xlink:href /en-US/docs/Web/SVG/Attribute/xlink:href -/en-US/docs/SVG/Attribute/xlink:title /en-US/docs/Web/SVG/Attribute/xlink:title -/en-US/docs/SVG/Attribute/xml:space /en-US/docs/Web/SVG/Attribute/xml:space -/en-US/docs/SVG/Attribute/y /en-US/docs/Web/SVG/Attribute/y -/en-US/docs/SVG/Attribute/y1 /en-US/docs/Web/SVG/Attribute/y1 -/en-US/docs/SVG/Attribute/y2 /en-US/docs/Web/SVG/Attribute/y2 -/en-US/docs/SVG/Attribute/yChannelSelector /en-US/docs/Web/SVG/Attribute/yChannelSelector -/en-US/docs/SVG/Attribute/z /en-US/docs/Web/SVG/Attribute/z +/en-US/docs/SVG/Attribute/keySplines /en-US/docs/Web/SVG/Reference/Attribute/keySplines +/en-US/docs/SVG/Attribute/keyTimes /en-US/docs/Web/SVG/Reference/Attribute/keyTimes +/en-US/docs/SVG/Attribute/letter-spacing /en-US/docs/Web/SVG/Reference/Attribute/letter-spacing +/en-US/docs/SVG/Attribute/lighting-color /en-US/docs/Web/SVG/Reference/Attribute/lighting-color +/en-US/docs/SVG/Attribute/limitingConeAngle /en-US/docs/Web/SVG/Reference/Attribute/limitingConeAngle +/en-US/docs/SVG/Attribute/marker-end /en-US/docs/Web/SVG/Reference/Attribute/marker-end +/en-US/docs/SVG/Attribute/marker-mid /en-US/docs/Web/SVG/Reference/Attribute/marker-mid +/en-US/docs/SVG/Attribute/marker-start /en-US/docs/Web/SVG/Reference/Attribute/marker-start +/en-US/docs/SVG/Attribute/markerHeight /en-US/docs/Web/SVG/Reference/Attribute/markerHeight +/en-US/docs/SVG/Attribute/markerUnits /en-US/docs/Web/SVG/Reference/Attribute/markerUnits +/en-US/docs/SVG/Attribute/markerWidth /en-US/docs/Web/SVG/Reference/Attribute/markerWidth +/en-US/docs/SVG/Attribute/mask /en-US/docs/Web/SVG/Reference/Attribute/mask +/en-US/docs/SVG/Attribute/maskContentUnits /en-US/docs/Web/SVG/Reference/Attribute/maskContentUnits +/en-US/docs/SVG/Attribute/maskUnits /en-US/docs/Web/SVG/Reference/Attribute/maskUnits +/en-US/docs/SVG/Attribute/max /en-US/docs/Web/SVG/Reference/Attribute/max +/en-US/docs/SVG/Attribute/min /en-US/docs/Web/SVG/Reference/Attribute/min +/en-US/docs/SVG/Attribute/mode /en-US/docs/Web/SVG/Reference/Attribute/mode +/en-US/docs/SVG/Attribute/numOctaves /en-US/docs/Web/SVG/Reference/Attribute/numOctaves +/en-US/docs/SVG/Attribute/opacity /en-US/docs/Web/SVG/Reference/Attribute/opacity +/en-US/docs/SVG/Attribute/operator /en-US/docs/Web/SVG/Reference/Attribute/operator +/en-US/docs/SVG/Attribute/order /en-US/docs/Web/SVG/Reference/Attribute/order +/en-US/docs/SVG/Attribute/overflow /en-US/docs/Web/SVG/Reference/Attribute/overflow +/en-US/docs/SVG/Attribute/paint-order /en-US/docs/Web/SVG/Reference/Attribute/paint-order +/en-US/docs/SVG/Attribute/pathLength /en-US/docs/Web/SVG/Reference/Attribute/pathLength +/en-US/docs/SVG/Attribute/patternContentUnits /en-US/docs/Web/SVG/Reference/Attribute/patternContentUnits +/en-US/docs/SVG/Attribute/patternTransform /en-US/docs/Web/SVG/Reference/Attribute/patternTransform +/en-US/docs/SVG/Attribute/patternUnits /en-US/docs/Web/SVG/Reference/Attribute/patternUnits +/en-US/docs/SVG/Attribute/pointer-events /en-US/docs/Web/SVG/Reference/Attribute/pointer-events +/en-US/docs/SVG/Attribute/points /en-US/docs/Web/SVG/Reference/Attribute/points +/en-US/docs/SVG/Attribute/pointsAtX /en-US/docs/Web/SVG/Reference/Attribute/pointsAtX +/en-US/docs/SVG/Attribute/pointsAtY /en-US/docs/Web/SVG/Reference/Attribute/pointsAtY +/en-US/docs/SVG/Attribute/pointsAtZ /en-US/docs/Web/SVG/Reference/Attribute/pointsAtZ +/en-US/docs/SVG/Attribute/preserveAlpha /en-US/docs/Web/SVG/Reference/Attribute/preserveAlpha +/en-US/docs/SVG/Attribute/preserveAspectRatio /en-US/docs/Web/SVG/Reference/Attribute/preserveAspectRatio +/en-US/docs/SVG/Attribute/primitiveUnits /en-US/docs/Web/SVG/Reference/Attribute/primitiveUnits +/en-US/docs/SVG/Attribute/r /en-US/docs/Web/SVG/Reference/Attribute/r +/en-US/docs/SVG/Attribute/radius /en-US/docs/Web/SVG/Reference/Attribute/radius +/en-US/docs/SVG/Attribute/repeatCount /en-US/docs/Web/SVG/Reference/Attribute/repeatCount +/en-US/docs/SVG/Attribute/repeatDur /en-US/docs/Web/SVG/Reference/Attribute/repeatDur +/en-US/docs/SVG/Attribute/requiredFeatures /en-US/docs/Web/SVG/Reference/Attribute/requiredFeatures +/en-US/docs/SVG/Attribute/restart /en-US/docs/Web/SVG/Reference/Attribute/restart +/en-US/docs/SVG/Attribute/result /en-US/docs/Web/SVG/Reference/Attribute/result +/en-US/docs/SVG/Attribute/rx /en-US/docs/Web/SVG/Reference/Attribute/rx +/en-US/docs/SVG/Attribute/ry /en-US/docs/Web/SVG/Reference/Attribute/ry +/en-US/docs/SVG/Attribute/scale /en-US/docs/Web/SVG/Reference/Attribute/scale +/en-US/docs/SVG/Attribute/seed /en-US/docs/Web/SVG/Reference/Attribute/seed +/en-US/docs/SVG/Attribute/shape-rendering /en-US/docs/Web/SVG/Reference/Attribute/shape-rendering +/en-US/docs/SVG/Attribute/specularConstant /en-US/docs/Web/SVG/Reference/Attribute/specularConstant +/en-US/docs/SVG/Attribute/specularExponent /en-US/docs/Web/SVG/Reference/Attribute/specularExponent +/en-US/docs/SVG/Attribute/stdDeviation /en-US/docs/Web/SVG/Reference/Attribute/stdDeviation +/en-US/docs/SVG/Attribute/stitchTiles /en-US/docs/Web/SVG/Reference/Attribute/stitchTiles +/en-US/docs/SVG/Attribute/stop-color /en-US/docs/Web/SVG/Reference/Attribute/stop-color +/en-US/docs/SVG/Attribute/stop-opacity /en-US/docs/Web/SVG/Reference/Attribute/stop-opacity +/en-US/docs/SVG/Attribute/stroke /en-US/docs/Web/SVG/Reference/Attribute/stroke +/en-US/docs/SVG/Attribute/stroke-dasharray /en-US/docs/Web/SVG/Reference/Attribute/stroke-dasharray +/en-US/docs/SVG/Attribute/stroke-dashoffset /en-US/docs/Web/SVG/Reference/Attribute/stroke-dashoffset +/en-US/docs/SVG/Attribute/stroke-linecap /en-US/docs/Web/SVG/Reference/Attribute/stroke-linecap +/en-US/docs/SVG/Attribute/stroke-linejoin /en-US/docs/Web/SVG/Reference/Attribute/stroke-linejoin +/en-US/docs/SVG/Attribute/stroke-miterlimit /en-US/docs/Web/SVG/Reference/Attribute/stroke-miterlimit +/en-US/docs/SVG/Attribute/stroke-opacity /en-US/docs/Web/SVG/Reference/Attribute/stroke-opacity +/en-US/docs/SVG/Attribute/stroke-width /en-US/docs/Web/SVG/Reference/Attribute/stroke-width +/en-US/docs/SVG/Attribute/style /en-US/docs/Web/SVG/Reference/Attribute/style +/en-US/docs/SVG/Attribute/surfaceScale /en-US/docs/Web/SVG/Reference/Attribute/surfaceScale +/en-US/docs/SVG/Attribute/targetX /en-US/docs/Web/SVG/Reference/Attribute/targetX +/en-US/docs/SVG/Attribute/targetY /en-US/docs/Web/SVG/Reference/Attribute/targetY +/en-US/docs/SVG/Attribute/text-anchor /en-US/docs/Web/SVG/Reference/Attribute/text-anchor +/en-US/docs/SVG/Attribute/text-decoration /en-US/docs/Web/SVG/Reference/Attribute/text-decoration +/en-US/docs/SVG/Attribute/text-rendering /en-US/docs/Web/SVG/Reference/Attribute/text-rendering +/en-US/docs/SVG/Attribute/transform /en-US/docs/Web/SVG/Reference/Attribute/transform +/en-US/docs/SVG/Attribute/type /en-US/docs/Web/SVG/Reference/Attribute/type +/en-US/docs/SVG/Attribute/values /en-US/docs/Web/SVG/Reference/Attribute/values +/en-US/docs/SVG/Attribute/viewBox /en-US/docs/Web/SVG/Reference/Attribute/viewBox +/en-US/docs/SVG/Attribute/visibility /en-US/docs/Web/SVG/Reference/Attribute/visibility +/en-US/docs/SVG/Attribute/width /en-US/docs/Web/SVG/Reference/Attribute/width +/en-US/docs/SVG/Attribute/word-spacing /en-US/docs/Web/SVG/Reference/Attribute/word-spacing +/en-US/docs/SVG/Attribute/writing-mode /en-US/docs/Web/SVG/Reference/Attribute/writing-mode +/en-US/docs/SVG/Attribute/x /en-US/docs/Web/SVG/Reference/Attribute/x +/en-US/docs/SVG/Attribute/x1 /en-US/docs/Web/SVG/Reference/Attribute/x1 +/en-US/docs/SVG/Attribute/x2 /en-US/docs/Web/SVG/Reference/Attribute/x2 +/en-US/docs/SVG/Attribute/xChannelSelector /en-US/docs/Web/SVG/Reference/Attribute/xChannelSelector +/en-US/docs/SVG/Attribute/xlink:href /en-US/docs/Web/SVG/Reference/Attribute/xlink:href +/en-US/docs/SVG/Attribute/xlink:title /en-US/docs/Web/SVG/Reference/Attribute/xlink:title +/en-US/docs/SVG/Attribute/xml:space /en-US/docs/Web/SVG/Reference/Attribute/xml:space +/en-US/docs/SVG/Attribute/y /en-US/docs/Web/SVG/Reference/Attribute/y +/en-US/docs/SVG/Attribute/y1 /en-US/docs/Web/SVG/Reference/Attribute/y1 +/en-US/docs/SVG/Attribute/y2 /en-US/docs/Web/SVG/Reference/Attribute/y2 +/en-US/docs/SVG/Attribute/yChannelSelector /en-US/docs/Web/SVG/Reference/Attribute/yChannelSelector +/en-US/docs/SVG/Attribute/z /en-US/docs/Web/SVG/Reference/Attribute/z /en-US/docs/SVG/Compatibility_sources /en-US/docs/Web/SVG /en-US/docs/SVG/Content_type /en-US/docs/Web/SVG -/en-US/docs/SVG/Element /en-US/docs/Web/SVG/Element -/en-US/docs/SVG/Element/a /en-US/docs/Web/SVG/Element/a -/en-US/docs/SVG/Element/animate /en-US/docs/Web/SVG/Element/animate -/en-US/docs/SVG/Element/animateColor /en-US/docs/Web/SVG/Element/animate -/en-US/docs/SVG/Element/animateMotion /en-US/docs/Web/SVG/Element/animateMotion -/en-US/docs/SVG/Element/animateTransform /en-US/docs/Web/SVG/Element/animateTransform -/en-US/docs/SVG/Element/circle /en-US/docs/Web/SVG/Element/circle -/en-US/docs/SVG/Element/clipPath /en-US/docs/Web/SVG/Element/clipPath -/en-US/docs/SVG/Element/cursor /en-US/docs/Web/SVG/Element/cursor -/en-US/docs/SVG/Element/defs /en-US/docs/Web/SVG/Element/defs -/en-US/docs/SVG/Element/desc /en-US/docs/Web/SVG/Element/desc -/en-US/docs/SVG/Element/ellipse /en-US/docs/Web/SVG/Element/ellipse -/en-US/docs/SVG/Element/feBlend /en-US/docs/Web/SVG/Element/feBlend -/en-US/docs/SVG/Element/feColorMatrix /en-US/docs/Web/SVG/Element/feColorMatrix -/en-US/docs/SVG/Element/feComponentTransfer /en-US/docs/Web/SVG/Element/feComponentTransfer -/en-US/docs/SVG/Element/feComposite /en-US/docs/Web/SVG/Element/feComposite -/en-US/docs/SVG/Element/feConvolveMatrix /en-US/docs/Web/SVG/Element/feConvolveMatrix -/en-US/docs/SVG/Element/feDiffuseLighting /en-US/docs/Web/SVG/Element/feDiffuseLighting -/en-US/docs/SVG/Element/feDisplacementMap /en-US/docs/Web/SVG/Element/feDisplacementMap -/en-US/docs/SVG/Element/feDistantLight /en-US/docs/Web/SVG/Element/feDistantLight -/en-US/docs/SVG/Element/feFlood /en-US/docs/Web/SVG/Element/feFlood -/en-US/docs/SVG/Element/feFuncA /en-US/docs/Web/SVG/Element/feFuncA -/en-US/docs/SVG/Element/feFuncB /en-US/docs/Web/SVG/Element/feFuncB -/en-US/docs/SVG/Element/feFuncG /en-US/docs/Web/SVG/Element/feFuncG -/en-US/docs/SVG/Element/feFuncR /en-US/docs/Web/SVG/Element/feFuncR -/en-US/docs/SVG/Element/feGaussianBlur /en-US/docs/Web/SVG/Element/feGaussianBlur -/en-US/docs/SVG/Element/feImage /en-US/docs/Web/SVG/Element/feImage -/en-US/docs/SVG/Element/feMerge /en-US/docs/Web/SVG/Element/feMerge -/en-US/docs/SVG/Element/feMergeNode /en-US/docs/Web/SVG/Element/feMergeNode -/en-US/docs/SVG/Element/feMorphology /en-US/docs/Web/SVG/Element/feMorphology -/en-US/docs/SVG/Element/feOffset /en-US/docs/Web/SVG/Element/feOffset -/en-US/docs/SVG/Element/fePointLight /en-US/docs/Web/SVG/Element/fePointLight -/en-US/docs/SVG/Element/feSpecularLighting /en-US/docs/Web/SVG/Element/feSpecularLighting -/en-US/docs/SVG/Element/feSpotLight /en-US/docs/Web/SVG/Element/feSpotLight -/en-US/docs/SVG/Element/feTile /en-US/docs/Web/SVG/Element/feTile -/en-US/docs/SVG/Element/feTurbulence /en-US/docs/Web/SVG/Element/feTurbulence -/en-US/docs/SVG/Element/filter /en-US/docs/Web/SVG/Element/filter -/en-US/docs/SVG/Element/font /en-US/docs/Web/SVG/Element/font -/en-US/docs/SVG/Element/font-face /en-US/docs/Web/SVG/Element/font-face -/en-US/docs/SVG/Element/font-face-format /en-US/docs/Web/SVG/Element/font-face-format -/en-US/docs/SVG/Element/font-face-name /en-US/docs/Web/SVG/Element/font-face-name -/en-US/docs/SVG/Element/font-face-src /en-US/docs/Web/SVG/Element/font-face-src -/en-US/docs/SVG/Element/font-face-uri /en-US/docs/Web/SVG/Element/font-face-uri -/en-US/docs/SVG/Element/foreignObject /en-US/docs/Web/SVG/Element/foreignObject -/en-US/docs/SVG/Element/g /en-US/docs/Web/SVG/Element/g -/en-US/docs/SVG/Element/glyph /en-US/docs/Web/SVG/Element/glyph -/en-US/docs/SVG/Element/glyphRef /en-US/docs/Web/SVG/Element/glyphRef -/en-US/docs/SVG/Element/hkern /en-US/docs/Web/SVG/Element/hkern -/en-US/docs/SVG/Element/image /en-US/docs/Web/SVG/Element/image -/en-US/docs/SVG/Element/line /en-US/docs/Web/SVG/Element/line -/en-US/docs/SVG/Element/linearGradient /en-US/docs/Web/SVG/Element/linearGradient -/en-US/docs/SVG/Element/marker /en-US/docs/Web/SVG/Element/marker -/en-US/docs/SVG/Element/mask /en-US/docs/Web/SVG/Element/mask -/en-US/docs/SVG/Element/metadata /en-US/docs/Web/SVG/Element/metadata -/en-US/docs/SVG/Element/missing-glyph /en-US/docs/Web/SVG/Element/missing-glyph -/en-US/docs/SVG/Element/mpath /en-US/docs/Web/SVG/Element/mpath -/en-US/docs/SVG/Element/path /en-US/docs/Web/SVG/Element/path -/en-US/docs/SVG/Element/pattern /en-US/docs/Web/SVG/Element/pattern -/en-US/docs/SVG/Element/polygon /en-US/docs/Web/SVG/Element/polygon -/en-US/docs/SVG/Element/polyline /en-US/docs/Web/SVG/Element/polyline -/en-US/docs/SVG/Element/radialGradient /en-US/docs/Web/SVG/Element/radialGradient -/en-US/docs/SVG/Element/rect /en-US/docs/Web/SVG/Element/rect -/en-US/docs/SVG/Element/script /en-US/docs/Web/SVG/Element/script -/en-US/docs/SVG/Element/set /en-US/docs/Web/SVG/Element/set -/en-US/docs/SVG/Element/stop /en-US/docs/Web/SVG/Element/stop -/en-US/docs/SVG/Element/style /en-US/docs/Web/SVG/Element/style -/en-US/docs/SVG/Element/svg /en-US/docs/Web/SVG/Element/svg -/en-US/docs/SVG/Element/switch /en-US/docs/Web/SVG/Element/switch -/en-US/docs/SVG/Element/symbol /en-US/docs/Web/SVG/Element/symbol -/en-US/docs/SVG/Element/text /en-US/docs/Web/SVG/Element/text -/en-US/docs/SVG/Element/textPath /en-US/docs/Web/SVG/Element/textPath -/en-US/docs/SVG/Element/title /en-US/docs/Web/SVG/Element/title -/en-US/docs/SVG/Element/tref /en-US/docs/Web/SVG/Element/tref -/en-US/docs/SVG/Element/tspan /en-US/docs/Web/SVG/Element/tspan -/en-US/docs/SVG/Element/use /en-US/docs/Web/SVG/Element/use -/en-US/docs/SVG/Element/view /en-US/docs/Web/SVG/Element/view -/en-US/docs/SVG/Element/vkern /en-US/docs/Web/SVG/Element/vkern -/en-US/docs/SVG/Linking /en-US/docs/Web/SVG/Linking -/en-US/docs/SVG/Namespaces_Crash_Course /en-US/docs/Web/SVG/Namespaces_Crash_Course -/en-US/docs/SVG/Namespaces_Crash_Course/Example /en-US/docs/Web/SVG/Namespaces_Crash_Course/Example -/en-US/docs/SVG/SVG_animation_with_SMIL /en-US/docs/Web/SVG/SVG_animation_with_SMIL -/en-US/docs/SVG/SVG_as_an_Image /en-US/docs/Web/SVG/SVG_as_an_Image -/en-US/docs/SVG/Scripting /en-US/docs/Web/SVG/Scripting +/en-US/docs/SVG/Element /en-US/docs/Web/SVG/Reference/Element +/en-US/docs/SVG/Element/a /en-US/docs/Web/SVG/Reference/Element/a +/en-US/docs/SVG/Element/animate /en-US/docs/Web/SVG/Reference/Element/animate +/en-US/docs/SVG/Element/animateColor /en-US/docs/Web/SVG/Reference/Element/animate +/en-US/docs/SVG/Element/animateMotion /en-US/docs/Web/SVG/Reference/Element/animateMotion +/en-US/docs/SVG/Element/animateTransform /en-US/docs/Web/SVG/Reference/Element/animateTransform +/en-US/docs/SVG/Element/circle /en-US/docs/Web/SVG/Reference/Element/circle +/en-US/docs/SVG/Element/clipPath /en-US/docs/Web/SVG/Reference/Element/clipPath +/en-US/docs/SVG/Element/cursor /en-US/docs/Web/CSS/cursor +/en-US/docs/SVG/Element/defs /en-US/docs/Web/SVG/Reference/Element/defs +/en-US/docs/SVG/Element/desc /en-US/docs/Web/SVG/Reference/Element/desc +/en-US/docs/SVG/Element/ellipse /en-US/docs/Web/SVG/Reference/Element/ellipse +/en-US/docs/SVG/Element/feBlend /en-US/docs/Web/SVG/Reference/Element/feBlend +/en-US/docs/SVG/Element/feColorMatrix /en-US/docs/Web/SVG/Reference/Element/feColorMatrix +/en-US/docs/SVG/Element/feComponentTransfer /en-US/docs/Web/SVG/Reference/Element/feComponentTransfer +/en-US/docs/SVG/Element/feComposite /en-US/docs/Web/SVG/Reference/Element/feComposite +/en-US/docs/SVG/Element/feConvolveMatrix /en-US/docs/Web/SVG/Reference/Element/feConvolveMatrix +/en-US/docs/SVG/Element/feDiffuseLighting /en-US/docs/Web/SVG/Reference/Element/feDiffuseLighting +/en-US/docs/SVG/Element/feDisplacementMap /en-US/docs/Web/SVG/Reference/Element/feDisplacementMap +/en-US/docs/SVG/Element/feDistantLight /en-US/docs/Web/SVG/Reference/Element/feDistantLight +/en-US/docs/SVG/Element/feFlood /en-US/docs/Web/SVG/Reference/Element/feFlood +/en-US/docs/SVG/Element/feFuncA /en-US/docs/Web/SVG/Reference/Element/feFuncA +/en-US/docs/SVG/Element/feFuncB /en-US/docs/Web/SVG/Reference/Element/feFuncB +/en-US/docs/SVG/Element/feFuncG /en-US/docs/Web/SVG/Reference/Element/feFuncG +/en-US/docs/SVG/Element/feFuncR /en-US/docs/Web/SVG/Reference/Element/feFuncR +/en-US/docs/SVG/Element/feGaussianBlur /en-US/docs/Web/SVG/Reference/Element/feGaussianBlur +/en-US/docs/SVG/Element/feImage /en-US/docs/Web/SVG/Reference/Element/feImage +/en-US/docs/SVG/Element/feMerge /en-US/docs/Web/SVG/Reference/Element/feMerge +/en-US/docs/SVG/Element/feMergeNode /en-US/docs/Web/SVG/Reference/Element/feMergeNode +/en-US/docs/SVG/Element/feMorphology /en-US/docs/Web/SVG/Reference/Element/feMorphology +/en-US/docs/SVG/Element/feOffset /en-US/docs/Web/SVG/Reference/Element/feOffset +/en-US/docs/SVG/Element/fePointLight /en-US/docs/Web/SVG/Reference/Element/fePointLight +/en-US/docs/SVG/Element/feSpecularLighting /en-US/docs/Web/SVG/Reference/Element/feSpecularLighting +/en-US/docs/SVG/Element/feSpotLight /en-US/docs/Web/SVG/Reference/Element/feSpotLight +/en-US/docs/SVG/Element/feTile /en-US/docs/Web/SVG/Reference/Element/feTile +/en-US/docs/SVG/Element/feTurbulence /en-US/docs/Web/SVG/Reference/Element/feTurbulence +/en-US/docs/SVG/Element/filter /en-US/docs/Web/SVG/Reference/Element/filter +/en-US/docs/SVG/Element/font /en-US/docs/Web/CSS/@font-face +/en-US/docs/SVG/Element/font-face /en-US/docs/Web/CSS/@font-face +/en-US/docs/SVG/Element/font-face-format /en-US/docs/Web/CSS/@font-face +/en-US/docs/SVG/Element/font-face-name /en-US/docs/Web/CSS/@font-face +/en-US/docs/SVG/Element/font-face-src /en-US/docs/Web/CSS/@font-face +/en-US/docs/SVG/Element/font-face-uri /en-US/docs/Web/CSS/@font-face +/en-US/docs/SVG/Element/foreignObject /en-US/docs/Web/SVG/Reference/Element/foreignObject +/en-US/docs/SVG/Element/g /en-US/docs/Web/SVG/Reference/Element/g +/en-US/docs/SVG/Element/glyph /en-US/docs/Web/CSS/@font-face +/en-US/docs/SVG/Element/glyphRef /en-US/docs/Web/CSS/@font-face +/en-US/docs/SVG/Element/hkern /en-US/docs/Web/CSS/@font-face +/en-US/docs/SVG/Element/image /en-US/docs/Web/SVG/Reference/Element/image +/en-US/docs/SVG/Element/line /en-US/docs/Web/SVG/Reference/Element/line +/en-US/docs/SVG/Element/linearGradient /en-US/docs/Web/SVG/Reference/Element/linearGradient +/en-US/docs/SVG/Element/marker /en-US/docs/Web/SVG/Reference/Element/marker +/en-US/docs/SVG/Element/mask /en-US/docs/Web/SVG/Reference/Element/mask +/en-US/docs/SVG/Element/metadata /en-US/docs/Web/SVG/Reference/Element/metadata +/en-US/docs/SVG/Element/missing-glyph /en-US/docs/Web/CSS/@font-face +/en-US/docs/SVG/Element/mpath /en-US/docs/Web/SVG/Reference/Element/mpath +/en-US/docs/SVG/Element/path /en-US/docs/Web/SVG/Reference/Element/path +/en-US/docs/SVG/Element/pattern /en-US/docs/Web/SVG/Reference/Element/pattern +/en-US/docs/SVG/Element/polygon /en-US/docs/Web/SVG/Reference/Element/polygon +/en-US/docs/SVG/Element/polyline /en-US/docs/Web/SVG/Reference/Element/polyline +/en-US/docs/SVG/Element/radialGradient /en-US/docs/Web/SVG/Reference/Element/radialGradient +/en-US/docs/SVG/Element/rect /en-US/docs/Web/SVG/Reference/Element/rect +/en-US/docs/SVG/Element/script /en-US/docs/Web/SVG/Reference/Element/script +/en-US/docs/SVG/Element/set /en-US/docs/Web/SVG/Reference/Element/set +/en-US/docs/SVG/Element/stop /en-US/docs/Web/SVG/Reference/Element/stop +/en-US/docs/SVG/Element/style /en-US/docs/Web/SVG/Reference/Element/style +/en-US/docs/SVG/Element/svg /en-US/docs/Web/SVG/Reference/Element/svg +/en-US/docs/SVG/Element/switch /en-US/docs/Web/SVG/Reference/Element/switch +/en-US/docs/SVG/Element/symbol /en-US/docs/Web/SVG/Reference/Element/symbol +/en-US/docs/SVG/Element/text /en-US/docs/Web/SVG/Reference/Element/text +/en-US/docs/SVG/Element/textPath /en-US/docs/Web/SVG/Reference/Element/textPath +/en-US/docs/SVG/Element/title /en-US/docs/Web/SVG/Reference/Element/title +/en-US/docs/SVG/Element/tref /en-US/docs/Web/CSS/@font-face +/en-US/docs/SVG/Element/tspan /en-US/docs/Web/SVG/Reference/Element/tspan +/en-US/docs/SVG/Element/use /en-US/docs/Web/SVG/Reference/Element/use +/en-US/docs/SVG/Element/view /en-US/docs/Web/SVG/Reference/Element/view +/en-US/docs/SVG/Element/vkern /en-US/docs/Web/CSS/@font-face +/en-US/docs/SVG/Linking /en-US/docs/Web/SVG/Guides/Linking +/en-US/docs/SVG/Namespaces_Crash_Course /en-US/docs/Web/SVG/Guides/Namespaces_crash_course +/en-US/docs/SVG/Namespaces_Crash_Course/Example /en-US/docs/Web/SVG/Guides/Namespaces_crash_course/Example +/en-US/docs/SVG/SVG_animation_with_SMIL /en-US/docs/Web/SVG/Guides/SVG_animation_with_SMIL +/en-US/docs/SVG/SVG_as_an_Image /en-US/docs/Web/SVG/Guides/SVG_as_an_image +/en-US/docs/SVG/Scripting /en-US/docs/Web/SVG/Guides/Scripting /en-US/docs/SVG/Server-configuration https://www.w3.org/services/svg-server/ /en-US/docs/SVG/Specification_Deviations /en-US/docs/Web/SVG -/en-US/docs/SVG/Tutorial /en-US/docs/Web/SVG/Tutorial -/en-US/docs/SVG/Tutorial/Basic_Shapes /en-US/docs/Web/SVG/Tutorial/Basic_Shapes -/en-US/docs/SVG/Tutorial/Basic_Transformations /en-US/docs/Web/SVG/Tutorial/Basic_Transformations -/en-US/docs/SVG/Tutorial/Clipping_and_masking /en-US/docs/Web/SVG/Tutorial/Clipping_and_masking -/en-US/docs/SVG/Tutorial/Fill_Stroke_and_Gradients /en-US/docs/Web/SVG/Tutorial/Fills_and_Strokes -/en-US/docs/SVG/Tutorial/Fills_and_Strokes /en-US/docs/Web/SVG/Tutorial/Fills_and_Strokes -/en-US/docs/SVG/Tutorial/Filter_effects /en-US/docs/Web/SVG/Tutorial/Filter_effects -/en-US/docs/SVG/Tutorial/Getting_Started /en-US/docs/Web/SVG/Tutorial/Getting_Started -/en-US/docs/SVG/Tutorial/Gradients /en-US/docs/Web/SVG/Tutorial/Gradients -/en-US/docs/SVG/Tutorial/Introduction /en-US/docs/Web/SVG/Tutorial/Introduction -/en-US/docs/SVG/Tutorial/Other_content_in_SVG /en-US/docs/Web/SVG/Tutorial/Other_content_in_SVG -/en-US/docs/SVG/Tutorial/Paths /en-US/docs/Web/SVG/Tutorial/Paths -/en-US/docs/SVG/Tutorial/Patterns /en-US/docs/Web/SVG/Tutorial/Patterns -/en-US/docs/SVG/Tutorial/Positions /en-US/docs/Web/SVG/Tutorial/Positions -/en-US/docs/SVG/Tutorial/SVG_Image_Tag /en-US/docs/Web/SVG/Tutorial/SVG_Image_Tag -/en-US/docs/SVG/Tutorial/SVG_fonts /en-US/docs/Web/SVG/Tutorial/SVG_fonts -/en-US/docs/SVG/Tutorial/Texts /en-US/docs/Web/SVG/Tutorial/Texts -/en-US/docs/SVG/Tutorial/Tools_for_SVG /en-US/docs/Web/SVG/Tutorial/Tools_for_SVG -/en-US/docs/SVG/circle /en-US/docs/Web/SVG/Element/circle -/en-US/docs/SVG/ellipse /en-US/docs/Web/SVG/Element/ellipse +/en-US/docs/SVG/Tutorial /en-US/docs/Web/SVG/Tutorials/SVG_from_scratch +/en-US/docs/SVG/Tutorial/Basic_Shapes /en-US/docs/Web/SVG/Tutorials/SVG_from_scratch/Basic_shapes +/en-US/docs/SVG/Tutorial/Basic_Transformations /en-US/docs/Web/SVG/Tutorials/SVG_from_scratch/Basic_transformations +/en-US/docs/SVG/Tutorial/Clipping_and_masking /en-US/docs/Web/SVG/Tutorials/SVG_from_scratch/Clipping_and_masking +/en-US/docs/SVG/Tutorial/Fill_Stroke_and_Gradients /en-US/docs/Web/SVG/Tutorials/SVG_from_scratch/Fills_and_strokes +/en-US/docs/SVG/Tutorial/Fills_and_Strokes /en-US/docs/Web/SVG/Tutorials/SVG_from_scratch/Fills_and_strokes +/en-US/docs/SVG/Tutorial/Filter_effects /en-US/docs/Web/SVG/Tutorials/SVG_from_scratch/Filter_effects +/en-US/docs/SVG/Tutorial/Getting_Started /en-US/docs/Web/SVG/Tutorials/SVG_from_scratch/Getting_started +/en-US/docs/SVG/Tutorial/Gradients /en-US/docs/Web/SVG/Tutorials/SVG_from_scratch/Gradients +/en-US/docs/SVG/Tutorial/Introduction /en-US/docs/Web/SVG/Tutorials/SVG_from_scratch/Introduction +/en-US/docs/SVG/Tutorial/Other_content_in_SVG /en-US/docs/Web/SVG/Tutorials/SVG_from_scratch/Other_content_in_SVG +/en-US/docs/SVG/Tutorial/Paths /en-US/docs/Web/SVG/Tutorials/SVG_from_scratch/Paths +/en-US/docs/SVG/Tutorial/Patterns /en-US/docs/Web/SVG/Tutorials/SVG_from_scratch/Patterns +/en-US/docs/SVG/Tutorial/Positions /en-US/docs/Web/SVG/Tutorials/SVG_from_scratch/Positions +/en-US/docs/SVG/Tutorial/SVG_Image_Tag /en-US/docs/Web/SVG/Tutorials/SVG_from_scratch/Image_element +/en-US/docs/SVG/Tutorial/SVG_fonts /en-US/docs/Web/SVG/Tutorials/SVG_from_scratch/Using_fonts +/en-US/docs/SVG/Tutorial/Texts /en-US/docs/Web/SVG/Tutorials/SVG_from_scratch/Texts +/en-US/docs/SVG/Tutorial/Tools_for_SVG /en-US/docs/Web/SVG/Tutorials/SVG_from_scratch/Tools_for_SVG +/en-US/docs/SVG/circle /en-US/docs/Web/SVG/Reference/Element/circle +/en-US/docs/SVG/ellipse /en-US/docs/Web/SVG/Reference/Element/ellipse /en-US/docs/SVG/filter /en-US/docs/Web/CSS/filter -/en-US/docs/SVG/g /en-US/docs/Web/SVG/Element/g -/en-US/docs/SVG/line /en-US/docs/Web/SVG/Element/line -/en-US/docs/SVG/polyline /en-US/docs/Web/SVG/Element/polyline -/en-US/docs/SVG/rect /en-US/docs/Web/SVG/Element/rect -/en-US/docs/SVG/use /en-US/docs/Web/SVG/Element/use -/en-US/docs/SVG:Linking /en-US/docs/Web/SVG/Linking -/en-US/docs/SVG:Namespaces_Crash_Course /en-US/docs/Web/SVG/Namespaces_Crash_Course -/en-US/docs/SVG:Namespaces_Crash_Course:Example /en-US/docs/Web/SVG/Namespaces_Crash_Course/Example -/en-US/docs/SVG:Scripting /en-US/docs/Web/SVG/Scripting +/en-US/docs/SVG/g /en-US/docs/Web/SVG/Reference/Element/g +/en-US/docs/SVG/line /en-US/docs/Web/SVG/Reference/Element/line +/en-US/docs/SVG/polyline /en-US/docs/Web/SVG/Reference/Element/polyline +/en-US/docs/SVG/rect /en-US/docs/Web/SVG/Reference/Element/rect +/en-US/docs/SVG/use /en-US/docs/Web/SVG/Reference/Element/use +/en-US/docs/SVG:Linking /en-US/docs/Web/SVG/Guides/Linking +/en-US/docs/SVG:Namespaces_Crash_Course /en-US/docs/Web/SVG/Guides/Namespaces_crash_course +/en-US/docs/SVG:Namespaces_Crash_Course:Example /en-US/docs/Web/SVG/Guides/Namespaces_crash_course/Example +/en-US/docs/SVG:Scripting /en-US/docs/Web/SVG/Guides/Scripting /en-US/docs/SVG:Specification_Deviations /en-US/docs/Web/SVG -/en-US/docs/SVG:Tutorial /en-US/docs/Web/SVG/Tutorial -/en-US/docs/SVG:Tutorial:Basic_Shapes /en-US/docs/Web/SVG/Tutorial/Basic_Shapes -/en-US/docs/SVG:Tutorial:Fill_Stroke_and_Gradients /en-US/docs/Web/SVG/Tutorial/Fills_and_Strokes -/en-US/docs/SVG:Tutorial:Getting_Started /en-US/docs/Web/SVG/Tutorial/Getting_Started -/en-US/docs/SVG:Tutorial:Introduction /en-US/docs/Web/SVG/Tutorial/Introduction -/en-US/docs/SVG:Tutorial:Paths /en-US/docs/Web/SVG/Tutorial/Paths -/en-US/docs/SVG:circle /en-US/docs/Web/SVG/Element/circle -/en-US/docs/SVG:ellipse /en-US/docs/Web/SVG/Element/ellipse -/en-US/docs/SVG:g /en-US/docs/Web/SVG/Element/g -/en-US/docs/SVG:line /en-US/docs/Web/SVG/Element/line -/en-US/docs/SVG:polyline /en-US/docs/Web/SVG/Element/polyline -/en-US/docs/SVG:rect /en-US/docs/Web/SVG/Element/rect -/en-US/docs/SVG:use /en-US/docs/Web/SVG/Element/use +/en-US/docs/SVG:Tutorial /en-US/docs/Web/SVG/Tutorials/SVG_from_scratch +/en-US/docs/SVG:Tutorial:Basic_Shapes /en-US/docs/Web/SVG/Tutorials/SVG_from_scratch/Basic_shapes +/en-US/docs/SVG:Tutorial:Fill_Stroke_and_Gradients /en-US/docs/Web/SVG/Tutorials/SVG_from_scratch/Fills_and_strokes +/en-US/docs/SVG:Tutorial:Getting_Started /en-US/docs/Web/SVG/Tutorials/SVG_from_scratch/Getting_started +/en-US/docs/SVG:Tutorial:Introduction /en-US/docs/Web/SVG/Tutorials/SVG_from_scratch/Introduction +/en-US/docs/SVG:Tutorial:Paths /en-US/docs/Web/SVG/Tutorials/SVG_from_scratch/Paths +/en-US/docs/SVG:circle /en-US/docs/Web/SVG/Reference/Element/circle +/en-US/docs/SVG:ellipse /en-US/docs/Web/SVG/Reference/Element/ellipse +/en-US/docs/SVG:g /en-US/docs/Web/SVG/Reference/Element/g +/en-US/docs/SVG:line /en-US/docs/Web/SVG/Reference/Element/line +/en-US/docs/SVG:polyline /en-US/docs/Web/SVG/Reference/Element/polyline +/en-US/docs/SVG:rect /en-US/docs/Web/SVG/Reference/Element/rect +/en-US/docs/SVG:use /en-US/docs/Web/SVG/Reference/Element/use /en-US/docs/SVGFEBlendElement /en-US/docs/Web/API/SVGFEBlendElement /en-US/docs/SVGFEComponentTransferElement /en-US/docs/Web/API/SVGFEComponentTransferElement -/en-US/docs/SVG_In_HTML_Introduction /en-US/docs/Web/SVG/Tutorial/SVG_In_HTML_Introduction -/en-US/docs/SVG_Namespace_Tips_(external) /en-US/docs/Web/SVG/Namespaces_Crash_Course -/en-US/docs/SVG_Reference /en-US/docs/Web/SVG/Element -/en-US/docs/SVG_Tutorial /en-US/docs/Web/SVG/Tutorial -/en-US/docs/SVG_animation_(SMIL)_in_Firefox /en-US/docs/Web/SVG/SVG_animation_with_SMIL +/en-US/docs/SVG_In_HTML_Introduction /en-US/docs/Web/SVG/Guides/SVG_in_HTML +/en-US/docs/SVG_Namespace_Tips_(external) /en-US/docs/Web/SVG/Guides/Namespaces_crash_course +/en-US/docs/SVG_Reference /en-US/docs/Web/SVG/Reference/Element +/en-US/docs/SVG_Tutorial /en-US/docs/Web/SVG/Tutorials/SVG_from_scratch +/en-US/docs/SVG_animation_(SMIL)_in_Firefox /en-US/docs/Web/SVG/Guides/SVG_animation_with_SMIL /en-US/docs/SVG_improvements_in_Firefox_3 /en-US/docs/Mozilla/Firefox/Releases/3/SVG_improvements /en-US/docs/Same_origin_policy_for_JavaScript /en-US/docs/Web/Security/Same-origin_policy /en-US/docs/Sample_.htaccess_file /en-US/docs/Learn_web_development/Extensions/Server-side/Apache_Configuration_htaccess /en-US/docs/Scripting_plugins /en-US/docs/Glossary/Plugin -/en-US/docs/Security/CSP /en-US/docs/Web/HTTP/CSP -/en-US/docs/Security/CSP/CSP_policy_directives /en-US/docs/Web/HTTP/Headers/Content-Security-Policy -/en-US/docs/Security/CSP/Default_CSP_restrictions /en-US/docs/Web/HTTP/Headers/Content-Security-Policy -/en-US/docs/Security/CSP/Introducing_Content_Security_Policy /en-US/docs/Web/HTTP/CSP -/en-US/docs/Security/CSP/Using_CSP_reports /en-US/docs/Web/HTTP/CSP -/en-US/docs/Security/CSP/Using_CSP_violation_reports /en-US/docs/Web/HTTP/CSP -/en-US/docs/Security/CSP/Using_Content_Security_Policy /en-US/docs/Web/HTTP/CSP +/en-US/docs/Security/CSP /en-US/docs/Web/HTTP/Guides/CSP +/en-US/docs/Security/CSP/CSP_policy_directives /en-US/docs/Web/HTTP/Reference/Headers/Content-Security-Policy +/en-US/docs/Security/CSP/Default_CSP_restrictions /en-US/docs/Web/HTTP/Reference/Headers/Content-Security-Policy +/en-US/docs/Security/CSP/Introducing_Content_Security_Policy /en-US/docs/Web/HTTP/Guides/CSP +/en-US/docs/Security/CSP/Using_CSP_reports /en-US/docs/Web/HTTP/Guides/CSP +/en-US/docs/Security/CSP/Using_CSP_violation_reports /en-US/docs/Web/HTTP/Guides/CSP +/en-US/docs/Security/CSP/Using_Content_Security_Policy /en-US/docs/Web/HTTP/Guides/CSP /en-US/docs/Security/Firefox_Security_Guidelines /en-US/docs/Web/Security/Firefox_Security_Guidelines -/en-US/docs/Security/HTTP_Strict_Transport_Security /en-US/docs/Web/HTTP/Headers/Strict-Transport-Security +/en-US/docs/Security/HTTP_Strict_Transport_Security /en-US/docs/Web/HTTP/Reference/Headers/Strict-Transport-Security /en-US/docs/Security/InsecurePasswords /en-US/docs/Web/Security/Insecure_passwords /en-US/docs/Security/Insecure_passwords /en-US/docs/Web/Security/Insecure_passwords /en-US/docs/Security/MixedContent /en-US/docs/Web/Security/Mixed_content @@ -7198,7 +7262,7 @@ /en-US/docs/Security_in_Firefox_2 /en-US/docs/Mozilla/Firefox/Releases/2/Security_changes /en-US/docs/Series/Gecko_Plugin_API_Reference /en-US/docs/Glossary/Plugin /en-US/docs/Series:Gecko_Plugin_API_Reference /en-US/docs/Glossary/Plugin -/en-US/docs/Server-Side_Access_Control /en-US/docs/Web/HTTP/CORS +/en-US/docs/Server-Side_Access_Control /en-US/docs/Web/HTTP/Guides/CORS /en-US/docs/Server-sent_events /en-US/docs/Web/API/Server-sent_events /en-US/docs/Server-sent_events/EventSource /en-US/docs/Web/API/EventSource /en-US/docs/Server-sent_events/Using_server-sent_events /en-US/docs/Web/API/Server-sent_events/Using_server-sent_events @@ -7214,33 +7278,33 @@ /en-US/docs/StyleSheet/parentStyleSheet /en-US/docs/Web/API/StyleSheet/parentStyleSheet /en-US/docs/StyleSheet/title /en-US/docs/Web/API/StyleSheet/title /en-US/docs/StyleSheet/type /en-US/docs/Web/API/StyleSheet/type -/en-US/docs/The_DOM_and_JavaScript /en-US/docs/Web/JavaScript/JavaScript_technologies_overview -/en-US/docs/The_Do_Not_Track_Field_Guide /en-US/docs/Web/HTTP/Headers/DNT -/en-US/docs/The_Do_Not_Track_Field_Guide/Additional_resources /en-US/docs/Web/HTTP/Headers/DNT -/en-US/docs/The_Do_Not_Track_Field_Guide/Case_studies /en-US/docs/Web/HTTP/Headers/DNT -/en-US/docs/The_Do_Not_Track_Field_Guide/Case_studies/1_Advertising_company /en-US/docs/Web/HTTP/Headers/DNT -/en-US/docs/The_Do_Not_Track_Field_Guide/Case_studies/2_Technology_provider /en-US/docs/Web/HTTP/Headers/DNT -/en-US/docs/The_Do_Not_Track_Field_Guide/Case_studies/3_Media_company /en-US/docs/Web/HTTP/Headers/DNT -/en-US/docs/The_Do_Not_Track_Field_Guide/Case_studies/4_Software_company /en-US/docs/Web/HTTP/Headers/DNT -/en-US/docs/The_Do_Not_Track_Field_Guide/Case_studies/Additional_issues_to_consider /en-US/docs/Web/HTTP/Headers/DNT -/en-US/docs/The_Do_Not_Track_Field_Guide/Case_studies/Case_studies/Additional_issues_to_consider /en-US/docs/Web/HTTP/Headers/DNT -/en-US/docs/The_Do_Not_Track_Field_Guide/Case_studies/Case_studies/Case_studies_flow_chart /en-US/docs/Web/HTTP/Headers/DNT -/en-US/docs/The_Do_Not_Track_Field_Guide/Case_studies/Case_studies_flow_chart /en-US/docs/Web/HTTP/Headers/DNT -/en-US/docs/The_Do_Not_Track_Field_Guide/Case_studies/DNT_case_studies_flow_chart /en-US/docs/Web/HTTP/Headers/DNT -/en-US/docs/The_Do_Not_Track_Field_Guide/Case_studies/Flow_chart /en-US/docs/Web/HTTP/Headers/DNT -/en-US/docs/The_Do_Not_Track_Field_Guide/Introduction /en-US/docs/Web/HTTP/Headers/DNT -/en-US/docs/The_Do_Not_Track_Field_Guide/Introduction/Background /en-US/docs/Web/HTTP/Headers/DNT -/en-US/docs/The_Do_Not_Track_Field_Guide/Introduction/How_Do_Not_Track_works /en-US/docs/Web/HTTP/Headers/DNT -/en-US/docs/The_Do_Not_Track_Field_Guide/Introduction/Privacy_techniques_and_Do_Not_Track /en-US/docs/Web/HTTP/Headers/DNT -/en-US/docs/The_Do_Not_Track_Field_Guide/Introduction/What_does_tracking_mean /en-US/docs/Web/HTTP/Headers/DNT -/en-US/docs/The_Do_Not_Track_Field_Guide/Tutorials /en-US/docs/Web/HTTP/Headers/DNT -/en-US/docs/The_Do_Not_Track_Field_Guide/Tutorials/1_Reading_the_DNT_header /en-US/docs/Web/HTTP/Headers/DNT -/en-US/docs/The_Do_Not_Track_Field_Guide/Tutorials/2_Displaying_DNT_status_with_caching /en-US/docs/Web/HTTP/Headers/DNT -/en-US/docs/The_Do_Not_Track_Field_Guide/Tutorials/3_Collecting_aggregate_data_based_on_DNT /en-US/docs/Web/HTTP/Headers/DNT -/en-US/docs/The_Do_Not_Track_Field_Guide/Tutorials/Additional_resources /en-US/docs/Web/HTTP/Headers/DNT +/en-US/docs/The_DOM_and_JavaScript /en-US/docs/Web/JavaScript/Reference/JavaScript_technologies_overview +/en-US/docs/The_Do_Not_Track_Field_Guide /en-US/docs/Web/HTTP/Reference/Headers/DNT +/en-US/docs/The_Do_Not_Track_Field_Guide/Additional_resources /en-US/docs/Web/HTTP/Reference/Headers/DNT +/en-US/docs/The_Do_Not_Track_Field_Guide/Case_studies /en-US/docs/Web/HTTP/Reference/Headers/DNT +/en-US/docs/The_Do_Not_Track_Field_Guide/Case_studies/1_Advertising_company /en-US/docs/Web/HTTP/Reference/Headers/DNT +/en-US/docs/The_Do_Not_Track_Field_Guide/Case_studies/2_Technology_provider /en-US/docs/Web/HTTP/Reference/Headers/DNT +/en-US/docs/The_Do_Not_Track_Field_Guide/Case_studies/3_Media_company /en-US/docs/Web/HTTP/Reference/Headers/DNT +/en-US/docs/The_Do_Not_Track_Field_Guide/Case_studies/4_Software_company /en-US/docs/Web/HTTP/Reference/Headers/DNT +/en-US/docs/The_Do_Not_Track_Field_Guide/Case_studies/Additional_issues_to_consider /en-US/docs/Web/HTTP/Reference/Headers/DNT +/en-US/docs/The_Do_Not_Track_Field_Guide/Case_studies/Case_studies/Additional_issues_to_consider /en-US/docs/Web/HTTP/Reference/Headers/DNT +/en-US/docs/The_Do_Not_Track_Field_Guide/Case_studies/Case_studies/Case_studies_flow_chart /en-US/docs/Web/HTTP/Reference/Headers/DNT +/en-US/docs/The_Do_Not_Track_Field_Guide/Case_studies/Case_studies_flow_chart /en-US/docs/Web/HTTP/Reference/Headers/DNT +/en-US/docs/The_Do_Not_Track_Field_Guide/Case_studies/DNT_case_studies_flow_chart /en-US/docs/Web/HTTP/Reference/Headers/DNT +/en-US/docs/The_Do_Not_Track_Field_Guide/Case_studies/Flow_chart /en-US/docs/Web/HTTP/Reference/Headers/DNT +/en-US/docs/The_Do_Not_Track_Field_Guide/Introduction /en-US/docs/Web/HTTP/Reference/Headers/DNT +/en-US/docs/The_Do_Not_Track_Field_Guide/Introduction/Background /en-US/docs/Web/HTTP/Reference/Headers/DNT +/en-US/docs/The_Do_Not_Track_Field_Guide/Introduction/How_Do_Not_Track_works /en-US/docs/Web/HTTP/Reference/Headers/DNT +/en-US/docs/The_Do_Not_Track_Field_Guide/Introduction/Privacy_techniques_and_Do_Not_Track /en-US/docs/Web/HTTP/Reference/Headers/DNT +/en-US/docs/The_Do_Not_Track_Field_Guide/Introduction/What_does_tracking_mean /en-US/docs/Web/HTTP/Reference/Headers/DNT +/en-US/docs/The_Do_Not_Track_Field_Guide/Tutorials /en-US/docs/Web/HTTP/Reference/Headers/DNT +/en-US/docs/The_Do_Not_Track_Field_Guide/Tutorials/1_Reading_the_DNT_header /en-US/docs/Web/HTTP/Reference/Headers/DNT +/en-US/docs/The_Do_Not_Track_Field_Guide/Tutorials/2_Displaying_DNT_status_with_caching /en-US/docs/Web/HTTP/Reference/Headers/DNT +/en-US/docs/The_Do_Not_Track_Field_Guide/Tutorials/3_Collecting_aggregate_data_based_on_DNT /en-US/docs/Web/HTTP/Reference/Headers/DNT +/en-US/docs/The_Do_Not_Track_Field_Guide/Tutorials/Additional_resources /en-US/docs/Web/HTTP/Reference/Headers/DNT /en-US/docs/The_Importance_of_Correct_Commenting /en-US/docs/Learn_web_development/Core/Structuring_content/Basic_HTML_syntax#HTML_comments /en-US/docs/The_Importance_of_Correct_HTML_Commenting /en-US/docs/Learn_web_development/Core/Structuring_content/Basic_HTML_syntax#HTML_comments -/en-US/docs/The_X-FRAME-OPTIONS_response_header /en-US/docs/Web/HTTP/Headers/X-Frame-Options +/en-US/docs/The_X-FRAME-OPTIONS_response_header /en-US/docs/Web/HTTP/Reference/Headers/X-Frame-Options /en-US/docs/The_XSLT /en-US/docs/Web/XML/XSLT /en-US/docs/The_XSLT/JavaScript_Interface_in_Gecko /en-US/docs/Web/API/XSLTProcessor /en-US/docs/The_XSLT/JavaScript_Interface_in_Gecko:Advanced_Example /en-US/docs/Web/API/XSLTProcessor @@ -7269,7 +7333,7 @@ /en-US/docs/Thunderbird/Autoconfiguration https://www.bucksch.org/1/projects/thunderbird/autoconfiguration/ /en-US/docs/Thunderbird/Autoconfiguration/FileFormat/Definition https://www.bucksch.org/1/projects/thunderbird/autoconfiguration/config-file-format.html /en-US/docs/Thunderbird/Autoconfiguration/FileFormat/HowTo https://www.bucksch.org/1/projects/thunderbird/autoconfiguration/how-to-create-your-own -/en-US/docs/Tips_for_Authoring_Fast-loading_HTML_Pages /en-US/docs/Learn_web_development/Howto/Solve_HTML_problems/Author_fast-loading_HTML_pages +/en-US/docs/Tips_for_Authoring_Fast-loading_HTML_Pages /en-US/docs/Web/HTML/How_to/Author_fast-loading_HTML_pages /en-US/docs/Toolbox https://firefox-source-docs.mozilla.org/devtools-user/tools_toolbox/index.html /en-US/docs/Tools https://firefox-source-docs.mozilla.org/devtools-user/index.html /en-US/docs/Tools/3D_View https://firefox-source-docs.mozilla.org/devtools-user/3d_view/index.html @@ -7474,8 +7538,8 @@ /en-US/docs/Tools:Validators https://firefox-source-docs.mozilla.org/devtools-user/validators/index.html /en-US/docs/Tools_Toolbox https://firefox-source-docs.mozilla.org/devtools-user/tools_toolbox/index.html /en-US/docs/Transforming_XML_with_XSLT /en-US/docs/Web/XML/XSLT/Guides/Transforming_XML_with_XSLT -/en-US/docs/Transforming_XML_with_XSLT/An_Overview /en-US/docs/Web/XML/XSLT/Guides/Transforming_XML_with_XSLT/An_Overview -/en-US/docs/Transforming_XML_with_XSLT/For_Further_Reading /en-US/docs/Web/XML/XSLT/Guides/Transforming_XML_with_XSLT/For_Further_Reading +/en-US/docs/Transforming_XML_with_XSLT/An_Overview /en-US/docs/Web/XML/XSLT/Guides/Transforming_XML_with_XSLT +/en-US/docs/Transforming_XML_with_XSLT/For_Further_Reading /en-US/docs/Web/XML/XSLT/Guides/Transforming_XML_with_XSLT /en-US/docs/Transforming_XML_with_XSLT/Mozilla_XSLT_XPath_Reference /en-US/docs/Web/XML/XSLT/Guides/Transforming_XML_with_XSLT /en-US/docs/Transforming_XML_with_XSLT/Mozilla_XSLT_XPath_Reference/Axes /en-US/docs/Web/XML/XPath/Reference/Axes /en-US/docs/Transforming_XML_with_XSLT/Mozilla_XSLT_XPath_Reference/Axes/ancestor /en-US/docs/Web/XML/XPath/Reference/Axes#ancestor @@ -7547,8 +7611,8 @@ /en-US/docs/Transforming_XML_with_XSLT/The_Netscape_XSLT_XPath_Reference/Elements/xsl/decimal-format /en-US/docs/Web/XML/XSLT/Reference/Element/decimal-format /en-US/docs/Transforming_XML_with_XSLT/The_Netscape_XSLT_XPath_Reference/Elements/xsl/element /en-US/docs/Web/XML/XSLT/Reference/Element/element /en-US/docs/Transforming_XML_with_XSLT/The_Netscape_XSLT_XPath_Reference/Functions /en-US/docs/Web/XML/XPath/Reference/Functions -/en-US/docs/Transforming_XML_with_XSLT:An_Overview /en-US/docs/Web/XML/XSLT/Guides/Transforming_XML_with_XSLT/An_Overview -/en-US/docs/Transforming_XML_with_XSLT:For_Further_Reading /en-US/docs/Web/XML/XSLT/Guides/Transforming_XML_with_XSLT/For_Further_Reading +/en-US/docs/Transforming_XML_with_XSLT:An_Overview /en-US/docs/Web/XML/XSLT/Guides/Transforming_XML_with_XSLT +/en-US/docs/Transforming_XML_with_XSLT:For_Further_Reading /en-US/docs/Web/XML/XSLT/Guides/Transforming_XML_with_XSLT /en-US/docs/Transforming_XML_with_XSLT:Mozilla_XSLT/XPath_Reference /en-US/docs/Web/XML/XSLT/Guides/Transforming_XML_with_XSLT /en-US/docs/Transforming_XML_with_XSLT:Mozilla_XSLT/XPath_Reference:Axes /en-US/docs/Web/XML/XPath/Reference/Axes /en-US/docs/Transforming_XML_with_XSLT:Mozilla_XSLT/XPath_Reference:Axes:ancestor /en-US/docs/Web/XML/XPath/Reference/Axes#ancestor @@ -7699,20 +7763,20 @@ /en-US/docs/USA /en-US/docs/Web/Progressive_web_apps /en-US/docs/USA-redirect-1 /en-US/docs/Web/Progressive_web_apps /en-US/docs/Understanding_CSS_z-index /en-US/docs/Web/CSS/CSS_positioned_layout/Understanding_z-index -/en-US/docs/Understanding_CSS_z-index/Adding_z-index /en-US/docs/Web/CSS/CSS_positioned_layout/Understanding_z-index/Using_z-index -/en-US/docs/Understanding_CSS_z-index/Stacking_and_float /en-US/docs/Web/CSS/CSS_positioned_layout/Understanding_z-index/Stacking_floating_elements -/en-US/docs/Understanding_CSS_z-index/Stacking_context_example_1 /en-US/docs/Web/CSS/CSS_positioned_layout/Understanding_z-index/Stacking_context_example_1 -/en-US/docs/Understanding_CSS_z-index/Stacking_context_example_2 /en-US/docs/Web/CSS/CSS_positioned_layout/Understanding_z-index/Stacking_context_example_2 -/en-US/docs/Understanding_CSS_z-index/Stacking_context_example_3 /en-US/docs/Web/CSS/CSS_positioned_layout/Understanding_z-index/Stacking_context_example_3 -/en-US/docs/Understanding_CSS_z-index/Stacking_without_z-index /en-US/docs/Web/CSS/CSS_positioned_layout/Understanding_z-index/Stacking_without_z-index -/en-US/docs/Understanding_CSS_z-index/The_stacking_context /en-US/docs/Web/CSS/CSS_positioned_layout/Understanding_z-index/Stacking_context -/en-US/docs/Understanding_CSS_z-index:Adding_z-index /en-US/docs/Web/CSS/CSS_positioned_layout/Understanding_z-index/Using_z-index -/en-US/docs/Understanding_CSS_z-index:Stacking_and_float /en-US/docs/Web/CSS/CSS_positioned_layout/Understanding_z-index/Stacking_floating_elements -/en-US/docs/Understanding_CSS_z-index:Stacking_context_example_1 /en-US/docs/Web/CSS/CSS_positioned_layout/Understanding_z-index/Stacking_context_example_1 -/en-US/docs/Understanding_CSS_z-index:Stacking_context_example_2 /en-US/docs/Web/CSS/CSS_positioned_layout/Understanding_z-index/Stacking_context_example_2 -/en-US/docs/Understanding_CSS_z-index:Stacking_context_example_3 /en-US/docs/Web/CSS/CSS_positioned_layout/Understanding_z-index/Stacking_context_example_3 -/en-US/docs/Understanding_CSS_z-index:Stacking_without_z-index /en-US/docs/Web/CSS/CSS_positioned_layout/Understanding_z-index/Stacking_without_z-index -/en-US/docs/Understanding_CSS_z-index:The_stacking_context /en-US/docs/Web/CSS/CSS_positioned_layout/Understanding_z-index/Stacking_context +/en-US/docs/Understanding_CSS_z-index/Adding_z-index /en-US/docs/Web/CSS/CSS_positioned_layout/Using_z-index +/en-US/docs/Understanding_CSS_z-index/Stacking_and_float /en-US/docs/Web/CSS/CSS_positioned_layout/Stacking_floating_elements +/en-US/docs/Understanding_CSS_z-index/Stacking_context_example_1 /en-US/docs/Web/CSS/CSS_positioned_layout/Stacking_context/Stacking_context_example_1 +/en-US/docs/Understanding_CSS_z-index/Stacking_context_example_2 /en-US/docs/Web/CSS/CSS_positioned_layout/Stacking_context/Stacking_context_example_2 +/en-US/docs/Understanding_CSS_z-index/Stacking_context_example_3 /en-US/docs/Web/CSS/CSS_positioned_layout/Stacking_context/Stacking_context_example_3 +/en-US/docs/Understanding_CSS_z-index/Stacking_without_z-index /en-US/docs/Web/CSS/CSS_positioned_layout/Stacking_without_z-index +/en-US/docs/Understanding_CSS_z-index/The_stacking_context /en-US/docs/Web/CSS/CSS_positioned_layout/Stacking_context +/en-US/docs/Understanding_CSS_z-index:Adding_z-index /en-US/docs/Web/CSS/CSS_positioned_layout/Using_z-index +/en-US/docs/Understanding_CSS_z-index:Stacking_and_float /en-US/docs/Web/CSS/CSS_positioned_layout/Stacking_floating_elements +/en-US/docs/Understanding_CSS_z-index:Stacking_context_example_1 /en-US/docs/Web/CSS/CSS_positioned_layout/Stacking_context/Stacking_context_example_1 +/en-US/docs/Understanding_CSS_z-index:Stacking_context_example_2 /en-US/docs/Web/CSS/CSS_positioned_layout/Stacking_context/Stacking_context_example_2 +/en-US/docs/Understanding_CSS_z-index:Stacking_context_example_3 /en-US/docs/Web/CSS/CSS_positioned_layout/Stacking_context/Stacking_context_example_3 +/en-US/docs/Understanding_CSS_z-index:Stacking_without_z-index /en-US/docs/Web/CSS/CSS_positioned_layout/Stacking_without_z-index +/en-US/docs/Understanding_CSS_z-index:The_stacking_context /en-US/docs/Web/CSS/CSS_positioned_layout/Stacking_context /en-US/docs/Understanding_URLS /en-US/docs/Learn_web_development/Howto/Web_mechanics/What_is_a_URL /en-US/docs/Understanding_Underlines /en-US/docs/Learn_web_development/Core/Text_styling/Fundamentals#Font_style_font_weight_text_transform_and_text_decoration /en-US/docs/Updating_Extensions_for_Firefox_4 /en-US/docs/Mozilla/Firefox/Releases/4/Updating_extensions_for_Firefox_4 @@ -7733,7 +7797,7 @@ /en-US/docs/Useful_CSS_tips:Color_and_Background /en-US/docs/Web/CSS/color_value /en-US/docs/Useful_CSS_tips:Links /en-US/docs/Web/CSS/Pseudo-classes /en-US/docs/Useful_CSS_tips:Tables /en-US/docs/Web/CSS/border-collapse -/en-US/docs/User_Agent_Strings_Reference /en-US/docs/Web/HTTP/Headers/User-Agent/Firefox +/en-US/docs/User_Agent_Strings_Reference /en-US/docs/Web/HTTP/Reference/Headers/User-Agent/Firefox /en-US/docs/Using_DOM_workers /en-US/docs/Web/API/Web_Workers_API/Using_web_workers /en-US/docs/Using_Deviceorientation_In_3D_Transforms /en-US/docs/Web/API/Device_orientation_events/Using_device_orientation_with_3D_transforms /en-US/docs/Using_Firefox_1.5_caching /en-US/docs/Mozilla/Firefox/Releases/1.5/Using_Firefox_1.5_caching @@ -8336,7 +8400,7 @@ /en-US/docs/Web/API/Document.scripts /en-US/docs/Web/API/Document/scripts /en-US/docs/Web/API/Document.xmlEncoding /en-US/docs/Web/API/Document/xmlEncoding /en-US/docs/Web/API/Document/Document:_DOMContentLoaded_event /en-US/docs/Web/API/Document/DOMContentLoaded_event -/en-US/docs/Web/API/Document/Document:_paste_event /en-US/docs/Web/API/Document/paste_event +/en-US/docs/Web/API/Document/Document:_paste_event /en-US/docs/Web/API/Element/paste_event /en-US/docs/Web/API/Document/animationcancel_event /en-US/docs/Web/API/Element/animationcancel_event /en-US/docs/Web/API/Document/animationend_event /en-US/docs/Web/API/Element/animationend_event /en-US/docs/Web/API/Document/animationiteration_event /en-US/docs/Web/API/Element/animationiteration_event @@ -8345,7 +8409,9 @@ /en-US/docs/Web/API/Document/baseURI /en-US/docs/Web/API/Node/baseURI /en-US/docs/Web/API/Document/cancelFullscreen /en-US/docs/Web/API/Document/exitFullscreen /en-US/docs/Web/API/Document/charset /en-US/docs/Web/API/Document/characterSet +/en-US/docs/Web/API/Document/copy_event /en-US/docs/Web/API/Element/copy_event /en-US/docs/Web/API/Document/createEntityReference /en-US/docs/Web/API/Document +/en-US/docs/Web/API/Document/cut_event /en-US/docs/Web/API/Element/cut_event /en-US/docs/Web/API/Document/defaultView/popstate_event /en-US/docs/Web/API/Window/popstate_event /en-US/docs/Web/API/Document/defaultView/resize_event /en-US/docs/Web/API/Window/resize_event /en-US/docs/Web/API/Document/defaultView/storage_event /en-US/docs/Web/API/Window/storage_event @@ -8401,6 +8467,7 @@ /en-US/docs/Web/API/Document/onsubmit /en-US/docs/Web/API/HTMLFormElement/submit_event /en-US/docs/Web/API/Document/onvisibilitychange /en-US/docs/Web/API/Document/visibilitychange_event /en-US/docs/Web/API/Document/origin /en-US/docs/Web/API/Window/origin +/en-US/docs/Web/API/Document/paste_event /en-US/docs/Web/API/Element/paste_event /en-US/docs/Web/API/Document/pointercancel_event /en-US/docs/Web/API/Element/pointercancel_event /en-US/docs/Web/API/Document/pointerdown_event /en-US/docs/Web/API/Element/pointerdown_event /en-US/docs/Web/API/Document/pointerenter_event /en-US/docs/Web/API/Element/pointerenter_event @@ -8832,8 +8899,8 @@ /en-US/docs/Web/API/HTMLElement.dataset /en-US/docs/Web/API/HTMLElement/dataset /en-US/docs/Web/API/HTMLElement.dir /en-US/docs/Web/API/HTMLElement/dir /en-US/docs/Web/API/HTMLElement.focus /en-US/docs/Web/API/HTMLElement/focus -/en-US/docs/Web/API/HTMLElement.forceSpellCheck /en-US/docs/Web/HTML/Global_attributes/spellcheck -/en-US/docs/Web/API/HTMLElement.forceSpellCheck() /en-US/docs/Web/HTML/Global_attributes/spellcheck +/en-US/docs/Web/API/HTMLElement.forceSpellCheck /en-US/docs/Web/HTML/Reference/Global_attributes/spellcheck +/en-US/docs/Web/API/HTMLElement.forceSpellCheck() /en-US/docs/Web/HTML/Reference/Global_attributes/spellcheck /en-US/docs/Web/API/HTMLElement.isContentEditable /en-US/docs/Web/API/HTMLElement/isContentEditable /en-US/docs/Web/API/HTMLElement.lang /en-US/docs/Web/API/HTMLElement/lang /en-US/docs/Web/API/HTMLElement.offsetHeight /en-US/docs/Web/API/HTMLElement/offsetHeight @@ -8841,9 +8908,9 @@ /en-US/docs/Web/API/HTMLElement.offsetParent /en-US/docs/Web/API/HTMLElement/offsetParent /en-US/docs/Web/API/HTMLElement.offsetTop /en-US/docs/Web/API/HTMLElement/offsetTop /en-US/docs/Web/API/HTMLElement.offsetWidth /en-US/docs/Web/API/HTMLElement/offsetWidth -/en-US/docs/Web/API/HTMLElement.oncopy /en-US/docs/Web/API/HTMLElement/copy_event -/en-US/docs/Web/API/HTMLElement.oncut /en-US/docs/Web/API/HTMLElement/cut_event -/en-US/docs/Web/API/HTMLElement.onpaste /en-US/docs/Web/API/HTMLElement/paste_event +/en-US/docs/Web/API/HTMLElement.oncopy /en-US/docs/Web/API/Element/copy_event +/en-US/docs/Web/API/HTMLElement.oncut /en-US/docs/Web/API/Element/cut_event +/en-US/docs/Web/API/HTMLElement.onpaste /en-US/docs/Web/API/Element/paste_event /en-US/docs/Web/API/HTMLElement.style /en-US/docs/Web/API/HTMLElement/style /en-US/docs/Web/API/HTMLElement.tabIndex /en-US/docs/Web/API/HTMLElement/tabIndex /en-US/docs/Web/API/HTMLElement.title /en-US/docs/Web/API/HTMLElement/title @@ -8853,7 +8920,9 @@ /en-US/docs/Web/API/HTMLElement/animationiteration_event /en-US/docs/Web/API/Element/animationiteration_event /en-US/docs/Web/API/HTMLElement/animationstart_event /en-US/docs/Web/API/Element/animationstart_event /en-US/docs/Web/API/HTMLElement/beforeinput_event /en-US/docs/Web/API/Element/beforeinput_event -/en-US/docs/Web/API/HTMLElement/forceSpellCheck /en-US/docs/Web/HTML/Global_attributes/spellcheck +/en-US/docs/Web/API/HTMLElement/copy_event /en-US/docs/Web/API/Element/copy_event +/en-US/docs/Web/API/HTMLElement/cut_event /en-US/docs/Web/API/Element/cut_event +/en-US/docs/Web/API/HTMLElement/forceSpellCheck /en-US/docs/Web/HTML/Reference/Global_attributes/spellcheck /en-US/docs/Web/API/HTMLElement/gotpointercapture_event /en-US/docs/Web/API/Element/gotpointercapture_event /en-US/docs/Web/API/HTMLElement/input_event /en-US/docs/Web/API/Element/input_event /en-US/docs/Web/API/HTMLElement/invalid_event /en-US/docs/Web/API/HTMLInputElement/invalid_event @@ -8866,8 +8935,8 @@ /en-US/docs/Web/API/HTMLElement/onchange /en-US/docs/Web/API/HTMLElement/change_event /en-US/docs/Web/API/HTMLElement/onclick /en-US/docs/Web/API/Element/click_event /en-US/docs/Web/API/HTMLElement/oncontextmenu /en-US/docs/Web/API/Element/contextmenu_event -/en-US/docs/Web/API/HTMLElement/oncopy /en-US/docs/Web/API/HTMLElement/copy_event -/en-US/docs/Web/API/HTMLElement/oncut /en-US/docs/Web/API/HTMLElement/cut_event +/en-US/docs/Web/API/HTMLElement/oncopy /en-US/docs/Web/API/Element/copy_event +/en-US/docs/Web/API/HTMLElement/oncut /en-US/docs/Web/API/Element/cut_event /en-US/docs/Web/API/HTMLElement/ondblclick /en-US/docs/Web/API/Element/dblclick_event /en-US/docs/Web/API/HTMLElement/onfocus /en-US/docs/Web/API/Window/focus_event /en-US/docs/Web/API/HTMLElement/oninput /en-US/docs/Web/API/Element/input_event @@ -8880,12 +8949,13 @@ /en-US/docs/Web/API/HTMLElement/onmouseout /en-US/docs/Web/API/Element/mouseout_event /en-US/docs/Web/API/HTMLElement/onmouseover /en-US/docs/Web/API/Element/mouseover_event /en-US/docs/Web/API/HTMLElement/onmouseup /en-US/docs/Web/API/Element/mouseup_event -/en-US/docs/Web/API/HTMLElement/onpaste /en-US/docs/Web/API/HTMLElement/paste_event +/en-US/docs/Web/API/HTMLElement/onpaste /en-US/docs/Web/API/Element/paste_event /en-US/docs/Web/API/HTMLElement/onreset /en-US/docs/Web/API/HTMLFormElement/reset_event /en-US/docs/Web/API/HTMLElement/onresize /en-US/docs/Web/API/HTMLFormElement/reset_event /en-US/docs/Web/API/HTMLElement/onscroll /en-US/docs/Web/API/Element/scroll_event /en-US/docs/Web/API/HTMLElement/onselect /en-US/docs/Web/API/HTMLInputElement/select_event /en-US/docs/Web/API/HTMLElement/onsubmit /en-US/docs/Web/API/HTMLFormElement/submit_event +/en-US/docs/Web/API/HTMLElement/paste_event /en-US/docs/Web/API/Element/paste_event /en-US/docs/Web/API/HTMLElement/pointercancel_event /en-US/docs/Web/API/Element/pointercancel_event /en-US/docs/Web/API/HTMLElement/pointerdown_event /en-US/docs/Web/API/Element/pointerdown_event /en-US/docs/Web/API/HTMLElement/pointerenter_event /en-US/docs/Web/API/Element/pointerenter_event @@ -8957,7 +9027,7 @@ /en-US/docs/Web/API/HTMLMediaElement/onerror /en-US/docs/Web/API/HTMLMediaElement/error_event /en-US/docs/Web/API/HTMLMediaElement/onwaitingforkey /en-US/docs/Web/API/HTMLMediaElement /en-US/docs/Web/API/HTMLMenuItemElement /en-US/docs/Web/API/HTMLMenuElement -/en-US/docs/Web/API/HTMLMetaElement/charset /en-US/docs/Web/HTML/Element/meta#charset +/en-US/docs/Web/API/HTMLMetaElement/charset /en-US/docs/Web/HTML/Reference/Elements/meta#charset /en-US/docs/Web/API/HTMLObjectElement/tabIndex /en-US/docs/Web/API/HTMLObjectElement/type /en-US/docs/Web/API/HTMLOptionElement.Option /en-US/docs/Web/API/HTMLOptionElement/Option /en-US/docs/Web/API/HTMLOrForeignElement/blur /en-US/docs/Web/API/HTMLElement/blur @@ -9232,7 +9302,7 @@ /en-US/docs/Web/API/KeyboardEvent.code /en-US/docs/Web/API/KeyboardEvent/code /en-US/docs/Web/API/KeyboardEvent.ctrlKey /en-US/docs/Web/API/KeyboardEvent/ctrlKey /en-US/docs/Web/API/KeyboardEvent.getModifierState /en-US/docs/Web/API/KeyboardEvent/getModifierState -/en-US/docs/Web/API/KeyboardEvent.initKeyEvent /en-US/docs/Web/API/KeyboardEvent/initKeyEvent +/en-US/docs/Web/API/KeyboardEvent.initKeyEvent /en-US/docs/Web/API/KeyboardEvent/KeyboardEvent /en-US/docs/Web/API/KeyboardEvent.initKeyboardEvent /en-US/docs/Web/API/KeyboardEvent/initKeyboardEvent /en-US/docs/Web/API/KeyboardEvent.isComposing /en-US/docs/Web/API/KeyboardEvent/isComposing /en-US/docs/Web/API/KeyboardEvent.key /en-US/docs/Web/API/KeyboardEvent/key @@ -9242,6 +9312,7 @@ /en-US/docs/Web/API/KeyboardEvent.shiftKey /en-US/docs/Web/API/KeyboardEvent/shiftKey /en-US/docs/Web/API/KeyboardEvent.which /en-US/docs/Web/API/UIEvent/which /en-US/docs/Web/API/KeyboardEvent/code/code_values /en-US/docs/Web/API/UI_Events/Keyboard_event_code_values +/en-US/docs/Web/API/KeyboardEvent/initKeyEvent /en-US/docs/Web/API/KeyboardEvent/KeyboardEvent /en-US/docs/Web/API/KeyboardEvent/key/Key_Values /en-US/docs/Web/API/UI_Events/Keyboard_event_key_values /en-US/docs/Web/API/KeyboardEvent/which /en-US/docs/Web/API/UIEvent/which /en-US/docs/Web/API/KeyframeEffect/KeyframeEffect.getKeyframes() /en-US/docs/Web/API/KeyframeEffect/getKeyframes @@ -9415,7 +9486,7 @@ /en-US/docs/Web/API/MessagePort.start /en-US/docs/Web/API/MessagePort/start /en-US/docs/Web/API/MessagePort/onmessage /en-US/docs/Web/API/MessagePort/message_event /en-US/docs/Web/API/MessagePort/onmessageerror /en-US/docs/Web/API/MessagePort/messageerror_event -/en-US/docs/Web/API/Microdata_DOM_API /en-US/docs/Web/HTML/Microdata +/en-US/docs/Web/API/Microdata_DOM_API /en-US/docs/Web/HTML/Guides/Microdata /en-US/docs/Web/API/MouseEvent.MouseEvent /en-US/docs/Web/API/MouseEvent/MouseEvent /en-US/docs/Web/API/MouseEvent.altKey /en-US/docs/Web/API/MouseEvent/altKey /en-US/docs/Web/API/MouseEvent.button /en-US/docs/Web/API/MouseEvent/button @@ -9874,7 +9945,7 @@ /en-US/docs/Web/API/RTCIceCandidateInit/usernameFragment /en-US/docs/Web/API/RTCIceCandidate/usernameFragment /en-US/docs/Web/API/RTCIceCandidatePairStats/bytesReceieved /en-US/docs/Web/API/RTCIceCandidatePairStats/bytesReceived /en-US/docs/Web/API/RTCIceCandidateStats/ip /en-US/docs/Web/API/RTCIceCandidateStats/address -/en-US/docs/Web/API/RTCIceCandidateStats/mozLocalTransport /en-US/docs/Web/API/RTCIceCandidateStats/relayProtocol +/en-US/docs/Web/API/RTCIceCandidateStats/mozLocalTransport /en-US/docs/Web/API/RTCIceCandidateStats /en-US/docs/Web/API/RTCIceCandidateType /en-US/docs/Web/API/RTCIceCandidate/type /en-US/docs/Web/API/RTCIceComponent /en-US/docs/Web/API/RTCIceCandidate/component /en-US/docs/Web/API/RTCIceConnectionState /en-US/docs/Web/API/RTCPeerConnection/iceConnectionState @@ -10038,6 +10109,7 @@ /en-US/docs/Web/API/SVGAnimationElement/onbegin /en-US/docs/Web/API/SVGAnimationElement/beginEvent_event /en-US/docs/Web/API/SVGAnimationElement/onend /en-US/docs/Web/API/SVGAnimationElement/endEvent_event /en-US/docs/Web/API/SVGAnimationElement/onrepeat /en-US/docs/Web/API/SVGAnimationElement/repeatEvent_event +/en-US/docs/Web/API/SVGCursorElement /en-US/docs/Web/API/SVGElement /en-US/docs/Web/API/SVGElement/onabort /en-US/docs/Web/API/HTMLMediaElement/abort_event /en-US/docs/Web/API/SVGElement/onblur /en-US/docs/Web/API/Window/blur_event /en-US/docs/Web/API/SVGElement/onchange /en-US/docs/Web/API/HTMLElement/change_event @@ -10060,15 +10132,28 @@ /en-US/docs/Web/API/SVGElement/onscroll /en-US/docs/Web/API/Element/scroll_event /en-US/docs/Web/API/SVGElement/onselect /en-US/docs/Web/API/HTMLInputElement/select_event /en-US/docs/Web/API/SVGElement/onsubmit /en-US/docs/Web/API/HTMLFormElement/submit_event +/en-US/docs/Web/API/SVGEvent /en-US/docs/Web/API/Event +/en-US/docs/Web/API/SVGFontElement /en-US/docs/Web/API/SVGElement +/en-US/docs/Web/API/SVGFontFaceElement /en-US/docs/Web/API/SVGElement +/en-US/docs/Web/API/SVGFontFaceFormatElement /en-US/docs/Web/API/SVGElement +/en-US/docs/Web/API/SVGFontFaceNameElement /en-US/docs/Web/API/SVGElement +/en-US/docs/Web/API/SVGFontFaceSrcElement /en-US/docs/Web/API/SVGElement +/en-US/docs/Web/API/SVGFontFaceUriElement /en-US/docs/Web/API/SVGElement /en-US/docs/Web/API/SVGGeometryElement/getTotalPathLength /en-US/docs/Web/API/SVGGeometryElement/pathLength -/en-US/docs/Web/API/SVGGraphicsElement/SVGGraphicsElement:_cut_event /en-US/docs/Web/API/SVGGraphicsElement/cut_event +/en-US/docs/Web/API/SVGGlyphElement /en-US/docs/Web/API/SVGElement +/en-US/docs/Web/API/SVGGlyphRefElement /en-US/docs/Web/API/SVGElement +/en-US/docs/Web/API/SVGGraphicsElement/SVGGraphicsElement:_cut_event /en-US/docs/Web/API/Element/cut_event +/en-US/docs/Web/API/SVGGraphicsElement/copy_event /en-US/docs/Web/API/Element/copy_event +/en-US/docs/Web/API/SVGGraphicsElement/cut_event /en-US/docs/Web/API/Element/cut_event +/en-US/docs/Web/API/SVGGraphicsElement/paste_event /en-US/docs/Web/API/Element/paste_event +/en-US/docs/Web/API/SVGHKernElement /en-US/docs/Web/API/SVGElement /en-US/docs/Web/API/SVGMatrix /en-US/docs/Web/API/DOMMatrix -/en-US/docs/Web/API/SVGPathElement/getPointAtLength /en-US/docs/Web/API/SVGGeometryElement/getPointAtLength -/en-US/docs/Web/API/SVGPathElement/getTotalLength /en-US/docs/Web/API/SVGGeometryElement/getTotalLength -/en-US/docs/Web/API/SVGPathElement/pathLength /en-US/docs/Web/API/SVGGeometryElement/pathLength +/en-US/docs/Web/API/SVGMissingGlyphElement /en-US/docs/Web/API/SVGElement /en-US/docs/Web/API/SVGRect/The__X__property /en-US/docs/Web/API/SVGRect/x /en-US/docs/Web/API/SVGStylable /en-US/docs/Web/API/SVGElement -/en-US/docs/Web/API/SVGURIReference /en-US/docs/Web/SVG/Attribute/href +/en-US/docs/Web/API/SVGTRefElement /en-US/docs/Web/API/SVGElement +/en-US/docs/Web/API/SVGURIReference /en-US/docs/Web/SVG/Reference/Attribute/href +/en-US/docs/Web/API/SVGVKernElement /en-US/docs/Web/API/SVGElement /en-US/docs/Web/API/Screen.availHeight /en-US/docs/Web/API/Screen/availHeight /en-US/docs/Web/API/Screen.availLeft /en-US/docs/Web/API/ScreenDetailed/availLeft /en-US/docs/Web/API/Screen.availTop /en-US/docs/Web/API/ScreenDetailed/availTop @@ -10141,8 +10226,9 @@ /en-US/docs/Web/API/ServiceWorkerContainer.controller /en-US/docs/Web/API/ServiceWorkerContainer/controller /en-US/docs/Web/API/ServiceWorkerContainer.getRegistration([scope]) /en-US/docs/Web/API/ServiceWorkerContainer/getRegistration /en-US/docs/Web/API/ServiceWorkerContainer.register /en-US/docs/Web/API/ServiceWorkerContainer/register +/en-US/docs/Web/API/ServiceWorkerContainer/error_event /en-US/docs/Web/API/ServiceWorker/error_event /en-US/docs/Web/API/ServiceWorkerContainer/oncontrollerchange /en-US/docs/Web/API/ServiceWorkerContainer/controllerchange_event -/en-US/docs/Web/API/ServiceWorkerContainer/onerror /en-US/docs/Web/API/ServiceWorkerContainer/error_event +/en-US/docs/Web/API/ServiceWorkerContainer/onerror /en-US/docs/Web/API/ServiceWorker/error_event /en-US/docs/Web/API/ServiceWorkerContainer/onmessage /en-US/docs/Web/API/ServiceWorkerContainer/message_event /en-US/docs/Web/API/ServiceWorkerGlobalScope.skipWaiting /en-US/docs/Web/API/ServiceWorkerGlobalScope/skipWaiting /en-US/docs/Web/API/ServiceWorkerGlobalScope/ServiceWorkerGlobalScope.onfetch /en-US/docs/Web/API/ServiceWorkerGlobalScope/fetch_event @@ -10403,7 +10489,7 @@ /en-US/docs/Web/API/VRPositionState/position /en-US/docs/Web/API/VRPose/position /en-US/docs/Web/API/VRPositionState/timeStamp /en-US/docs/Web/API/VRPose /en-US/docs/Web/API/ValidityState/ValidityState.patternMismatch /en-US/docs/Web/API/ValidityState/patternMismatch -/en-US/docs/Web/API/ValidityState/pattern /en-US/docs/Web/HTML/Attributes/pattern +/en-US/docs/Web/API/ValidityState/pattern /en-US/docs/Web/HTML/Reference/Attributes/pattern /en-US/docs/Web/API/ValidityState/underUnderflow /en-US/docs/Web/API/ValidityState/rangeUnderflow /en-US/docs/Web/API/VideoConfiguration /en-US/docs/Web/API/Media_Capabilities_API /en-US/docs/Web/API/VideoDecoder/isConfigSupported /en-US/docs/Web/API/VideoDecoder/isConfigSupported_static @@ -10569,10 +10655,14 @@ /en-US/docs/Web/API/Window/animationend_event /en-US/docs/Web/API/Element/animationend_event /en-US/docs/Web/API/Window/animationiteration_event /en-US/docs/Web/API/Element/animationiteration_event /en-US/docs/Web/API/Window/animationstart_event /en-US/docs/Web/API/Element/animationstart_event +/en-US/docs/Web/API/Window/back /en-US/docs/Web/API/History/back /en-US/docs/Web/API/Window/console /en-US/docs/Web/API/console /en-US/docs/Web/API/Window/content /en-US/docs/Web/API/Window /en-US/docs/Web/API/Window/convertPointFromNodeToPage /en-US/docs/Web/API/Window/webkitConvertPointFromNodeToPage /en-US/docs/Web/API/Window/convertPointFromPageToNode /en-US/docs/Web/API/Window/webkitConvertPointFromPageToNode +/en-US/docs/Web/API/Window/copy_event /en-US/docs/Web/API/Element/copy_event +/en-US/docs/Web/API/Window/cut_event /en-US/docs/Web/API/Element/cut_event +/en-US/docs/Web/API/Window/forward /en-US/docs/Web/API/History/forward /en-US/docs/Web/API/Window/minimize /en-US/docs/Web/API/Window /en-US/docs/Web/API/Window/mozAnimationStartTime /en-US/docs/Web/API/Animation/startTime /en-US/docs/Web/API/Window/mozPaintCount /en-US/docs/Web/API/Window @@ -10630,9 +10720,11 @@ /en-US/docs/Web/API/Window/openDialog /en-US/docs/Web/API/Window /en-US/docs/Web/API/Window/pageXOffset /en-US/docs/Web/API/Window/scrollX /en-US/docs/Web/API/Window/pageYOffset /en-US/docs/Web/API/Window/scrollY +/en-US/docs/Web/API/Window/paste_event /en-US/docs/Web/API/Element/paste_event /en-US/docs/Web/API/Window/removeEventListener /en-US/docs/Web/API/EventTarget/removeEventListener /en-US/docs/Web/API/Window/resolveLocalFileSystemURL /en-US/docs/Web/API/File_and_Directory_Entries_API#resolvelocalfilesystemurl() /en-US/docs/Web/API/Window/restore /en-US/docs/Web/API/Window/moveTo +/en-US/docs/Web/API/Window/showModalDialog /en-US/docs/Web/API/HTMLDialogElement/showModal /en-US/docs/Web/API/Window/sidebar /en-US/docs/Web/API/Window/external /en-US/docs/Web/API/Window/sidebar/Adding_search_engines_from_Web_pages /en-US/docs/Web/XML/Guides/OpenSearch /en-US/docs/Web/API/Window/transitioncancel_event /en-US/docs/Web/API/Element/transitioncancel_event @@ -10748,6 +10840,10 @@ /en-US/docs/Web/API/XMLHttpRequest/Using_XMLHttpRequest /en-US/docs/Web/API/XMLHttpRequest_API/Using_XMLHttpRequest /en-US/docs/Web/API/XMLHttpRequest/Using_XMLHttpRequest_in_IE6 /en-US/docs/Web/API/XMLHttpRequest_API/Using_XMLHttpRequest /en-US/docs/Web/API/XMLHttpRequest/XMLHttpRequest.response /en-US/docs/Web/API/XMLHttpRequest/response +/en-US/docs/Web/API/XMLHttpRequest/channel /en-US/docs/Web/API/XMLHttpRequest +/en-US/docs/Web/API/XMLHttpRequest/mozAnon /en-US/docs/Web/API/XMLHttpRequest +/en-US/docs/Web/API/XMLHttpRequest/mozBackgroundRequest /en-US/docs/Web/API/XMLHttpRequest +/en-US/docs/Web/API/XMLHttpRequest/mozSystem /en-US/docs/Web/API/XMLHttpRequest /en-US/docs/Web/API/XMLHttpRequest/onreadystatechange /en-US/docs/Web/API/XMLHttpRequest/readystatechange_event /en-US/docs/Web/API/XMLHttpRequest/responseresponseText /en-US/docs/Web/API/XMLHttpRequest/responseText /en-US/docs/Web/API/XMLHttpRequestEventTarget/onabort /en-US/docs/Web/API/XMLHttpRequest/abort_event @@ -10757,6 +10853,8 @@ /en-US/docs/Web/API/XMLHttpRequestEventTarget/onprogress /en-US/docs/Web/API/XMLHttpRequest/progress_event /en-US/docs/Web/API/XMLHttpRequestResponseType /en-US/docs/Web/API/XMLHttpRequest/responseType /en-US/docs/Web/API/XPathEvaluator/XPathEvaluator.createExpression() /en-US/docs/Web/API/XPathEvaluator/createExpression +/en-US/docs/Web/API/XPathException /en-US/docs/Web/API/DOMException +/en-US/docs/Web/API/XPathException/code /en-US/docs/Web/API/DOMException/code /en-US/docs/Web/API/XPathNSResolver /en-US/docs/Web/API/Node/lookupNamespaceURI /en-US/docs/Web/API/XPathNSResolver/lookupNamespaceURI /en-US/docs/Web/API/Node/lookupNamespaceURI /en-US/docs/Web/API/XPathResult/XPathResult.booleanValue /en-US/docs/Web/API/XPathResult/booleanValue @@ -10997,8 +11095,8 @@ /en-US/docs/Web/API/element.onblur /en-US/docs/Web/API/Window/blur_event /en-US/docs/Web/API/element.onchange /en-US/docs/Web/API/HTMLElement/change_event /en-US/docs/Web/API/element.onclick /en-US/docs/Web/API/Element/click_event -/en-US/docs/Web/API/element.oncopy /en-US/docs/Web/API/HTMLElement/copy_event -/en-US/docs/Web/API/element.oncut /en-US/docs/Web/API/HTMLElement/cut_event +/en-US/docs/Web/API/element.oncopy /en-US/docs/Web/API/Element/copy_event +/en-US/docs/Web/API/element.oncut /en-US/docs/Web/API/Element/cut_event /en-US/docs/Web/API/element.ondblclick /en-US/docs/Web/API/Element/dblclick_event /en-US/docs/Web/API/element.onfocus /en-US/docs/Web/API/Window/focus_event /en-US/docs/Web/API/element.onkeydown /en-US/docs/Web/API/Element/keydown_event @@ -11008,7 +11106,7 @@ /en-US/docs/Web/API/element.onmousemove /en-US/docs/Web/API/Element/mousemove_event /en-US/docs/Web/API/element.onmouseout /en-US/docs/Web/API/Element/mouseout_event /en-US/docs/Web/API/element.onmouseup /en-US/docs/Web/API/Element/mouseup_event -/en-US/docs/Web/API/element.onpaste /en-US/docs/Web/API/HTMLElement/paste_event +/en-US/docs/Web/API/element.onpaste /en-US/docs/Web/API/Element/paste_event /en-US/docs/Web/API/element.onresize /en-US/docs/Web/API/Window/resize_event /en-US/docs/Web/API/element.onscroll /en-US/docs/Web/API/Element/scroll_event /en-US/docs/Web/API/element.onwheel /en-US/docs/Web/API/Element/wheel_event @@ -11045,7 +11143,7 @@ /en-US/docs/Web/API/event.eventPhase /en-US/docs/Web/API/Event/eventPhase /en-US/docs/Web/API/event.explicitOriginalTarget /en-US/docs/Web/API/Event/explicitOriginalTarget /en-US/docs/Web/API/event.initEvent /en-US/docs/Web/API/Event/initEvent -/en-US/docs/Web/API/event.initKeyEvent /en-US/docs/Web/API/KeyboardEvent/initKeyEvent +/en-US/docs/Web/API/event.initKeyEvent /en-US/docs/Web/API/KeyboardEvent/KeyboardEvent /en-US/docs/Web/API/event.initMouseEvent /en-US/docs/Web/API/MouseEvent/initMouseEvent /en-US/docs/Web/API/event.initUIEvent /en-US/docs/Web/API/UIEvent/initUIEvent /en-US/docs/Web/API/event.isTrusted /en-US/docs/Web/API/Event/isTrusted @@ -11205,7 +11303,7 @@ /en-US/docs/Web/API/window.URL.revokeObjectURL /en-US/docs/Web/API/URL/revokeObjectURL_static /en-US/docs/Web/API/window.alert /en-US/docs/Web/API/Window/alert /en-US/docs/Web/API/window.atob /en-US/docs/Web/API/Window/atob -/en-US/docs/Web/API/window.back /en-US/docs/Web/API/Window/back +/en-US/docs/Web/API/window.back /en-US/docs/Web/API/History/back /en-US/docs/Web/API/window.blur /en-US/docs/Web/API/Window/blur /en-US/docs/Web/API/window.btoa /en-US/docs/Web/API/Window/btoa /en-US/docs/Web/API/window.cancelAnimationFrame /en-US/docs/Web/API/Window/cancelAnimationFrame @@ -11224,7 +11322,7 @@ /en-US/docs/Web/API/window.escape /en-US/docs/Web/JavaScript/Reference/Global_Objects/escape /en-US/docs/Web/API/window.find /en-US/docs/Web/API/Window/find /en-US/docs/Web/API/window.focus /en-US/docs/Web/API/Window/focus -/en-US/docs/Web/API/window.forward /en-US/docs/Web/API/Window/forward +/en-US/docs/Web/API/window.forward /en-US/docs/Web/API/History/forward /en-US/docs/Web/API/window.frameElement /en-US/docs/Web/API/Window/frameElement /en-US/docs/Web/API/window.frames /en-US/docs/Web/API/Window/frames /en-US/docs/Web/API/window.fullScreen /en-US/docs/Web/API/Window/fullScreen @@ -11362,7 +11460,7 @@ /en-US/docs/Web/API/window.setImmediate /en-US/docs/Web/API/Window/setImmediate /en-US/docs/Web/API/window.setInterval /en-US/docs/Web/API/Window/setInterval /en-US/docs/Web/API/window.setTimeout /en-US/docs/Web/API/Window/setTimeout -/en-US/docs/Web/API/window.showModalDialog /en-US/docs/Web/API/Window/showModalDialog +/en-US/docs/Web/API/window.showModalDialog /en-US/docs/Web/API/HTMLDialogElement/showModal /en-US/docs/Web/API/window.sidebar /en-US/docs/Web/API/Window/external /en-US/docs/Web/API/window.sizeToContent /en-US/docs/Web/API/Window/sizeToContent /en-US/docs/Web/API/window.status /en-US/docs/Web/API/Window/status @@ -11379,68 +11477,235 @@ /en-US/docs/Web/APIWwindow.sidebar /en-US/docs/Web/API/Window/external /en-US/docs/Web/APIr /en-US/docs/Web/API/Document/dir /en-US/docs/Web/Accessibility/ARIA/ARIA_Examples /en-US/docs/Web/Accessibility/ARIA -/en-US/docs/Web/Accessibility/ARIA/ARIA_Techniques/Complementary_role /en-US/docs/Web/Accessibility/ARIA/Roles/complementary_role -/en-US/docs/Web/Accessibility/ARIA/ARIA_Techniques/Using_the_alert_role /en-US/docs/Web/Accessibility/ARIA/Roles/alert_role -/en-US/docs/Web/Accessibility/ARIA/ARIA_Techniques/Using_the_alertdialog_role /en-US/docs/Web/Accessibility/ARIA/Roles/alertdialog_role -/en-US/docs/Web/Accessibility/ARIA/ARIA_Techniques/Using_the_aria-activedescendant_attribute /en-US/docs/Web/Accessibility/ARIA/Attributes/aria-activedescendant -/en-US/docs/Web/Accessibility/ARIA/ARIA_Techniques/Using_the_aria-describedby_attribute/ /en-US/docs/Web/Accessibility/ARIA/Attributes/aria-describedby -/en-US/docs/Web/Accessibility/ARIA/ARIA_Techniques/Using_the_aria-hidden_attribute/ /en-US/docs/Web/Accessibility/ARIA/Attributes/aria-hidden -/en-US/docs/Web/Accessibility/ARIA/ARIA_Techniques/Using_the_aria-invalid_attribute/ /en-US/docs/Web/Accessibility/ARIA/Attributes/aria-invalid -/en-US/docs/Web/Accessibility/ARIA/ARIA_Techniques/Using_the_aria-invalid_property /en-US/docs/Web/Accessibility/ARIA/Attributes/aria-invalid -/en-US/docs/Web/Accessibility/ARIA/ARIA_Techniques/Using_the_aria-label_attribute/ /en-US/docs/Web/Accessibility/ARIA/Attributes/aria-label -/en-US/docs/Web/Accessibility/ARIA/ARIA_Techniques/Using_the_aria-labelledby_attribute/ /en-US/docs/Web/Accessibility/ARIA/Attributes/aria-labelledby -/en-US/docs/Web/Accessibility/ARIA/ARIA_Techniques/Using_the_aria-orientation_attribute/ /en-US/docs/Web/Accessibility/ARIA/Attributes/aria-orientation -/en-US/docs/Web/Accessibility/ARIA/ARIA_Techniques/Using_the_aria-relevant_attribute/ /en-US/docs/Web/Accessibility/ARIA/Attributes/aria-relevant -/en-US/docs/Web/Accessibility/ARIA/ARIA_Techniques/Using_the_aria-required_attribute/ /en-US/docs/Web/Accessibility/ARIA/Attributes/aria-required -/en-US/docs/Web/Accessibility/ARIA/ARIA_Techniques/Using_the_aria-required_property /en-US/docs/Web/Accessibility/ARIA/Attributes/aria-required -/en-US/docs/Web/Accessibility/ARIA/ARIA_Techniques/Using_the_aria-valuemax_attribute/ /en-US/docs/Web/Accessibility/ARIA/Attributes/aria-valuemax -/en-US/docs/Web/Accessibility/ARIA/ARIA_Techniques/Using_the_aria-valuemin_attribute/ /en-US/docs/Web/Accessibility/ARIA/Attributes/aria-valuemin -/en-US/docs/Web/Accessibility/ARIA/ARIA_Techniques/Using_the_aria-valuenow_attribute/ /en-US/docs/Web/Accessibility/ARIA/Attributes/aria-valuenow -/en-US/docs/Web/Accessibility/ARIA/ARIA_Techniques/Using_the_aria-valuetext_attribute/ /en-US/docs/Web/Accessibility/ARIA/Attributes/aria-valuetext -/en-US/docs/Web/Accessibility/ARIA/ARIA_Techniques/Using_the_article_role /en-US/docs/Web/Accessibility/ARIA/Roles/article_role -/en-US/docs/Web/Accessibility/ARIA/ARIA_Techniques/Using_the_banner_role /en-US/docs/Web/Accessibility/ARIA/Roles/banner_role -/en-US/docs/Web/Accessibility/ARIA/ARIA_Techniques/Using_the_button_role /en-US/docs/Web/Accessibility/ARIA/Roles/button_role -/en-US/docs/Web/Accessibility/ARIA/ARIA_Techniques/Using_the_checkbox_role /en-US/docs/Web/Accessibility/ARIA/Roles/checkbox_role -/en-US/docs/Web/Accessibility/ARIA/ARIA_Techniques/Using_the_dialog_role /en-US/docs/Web/Accessibility/ARIA/Roles/dialog_role -/en-US/docs/Web/Accessibility/ARIA/ARIA_Techniques/Using_the_group_role /en-US/docs/Web/Accessibility/ARIA/Roles/group_role -/en-US/docs/Web/Accessibility/ARIA/ARIA_Techniques/Using_the_link_role /en-US/docs/Web/Accessibility/ARIA/Roles/link_role -/en-US/docs/Web/Accessibility/ARIA/ARIA_Techniques/Using_the_listbox_role /en-US/docs/Web/Accessibility/ARIA/Roles/listbox_role -/en-US/docs/Web/Accessibility/ARIA/ARIA_Techniques/Using_the_log_role /en-US/docs/Web/Accessibility/ARIA/Roles/log_role -/en-US/docs/Web/Accessibility/ARIA/ARIA_Techniques/Using_the_presentation_role /en-US/docs/Web/Accessibility/ARIA/Roles/presentation_role -/en-US/docs/Web/Accessibility/ARIA/ARIA_Techniques/Using_the_progressbar_role /en-US/docs/Web/Accessibility/ARIA/Roles/progressbar_role -/en-US/docs/Web/Accessibility/ARIA/ARIA_Techniques/Using_the_radio_role /en-US/docs/Web/Accessibility/ARIA/Roles/radio_role -/en-US/docs/Web/Accessibility/ARIA/ARIA_Techniques/Using_the_slider_role /en-US/docs/Web/Accessibility/ARIA/Roles/slider_role -/en-US/docs/Web/Accessibility/ARIA/ARIA_Techniques/Using_the_status_role /en-US/docs/Web/Accessibility/ARIA/Roles/status_role -/en-US/docs/Web/Accessibility/ARIA/ARIA_Techniques/Using_the_switch_role /en-US/docs/Web/Accessibility/ARIA/Roles/switch_role -/en-US/docs/Web/Accessibility/ARIA/ARIA_Techniques/Using_the_textbox_role /en-US/docs/Web/Accessibility/ARIA/Roles/textbox_role -/en-US/docs/Web/Accessibility/ARIA/ARIA_Techniques/Using_the_toolbar_role /en-US/docs/Web/Accessibility/ARIA/Roles/toolbar_role +/en-US/docs/Web/Accessibility/ARIA/ARIA_Guides /en-US/docs/Web/Accessibility/ARIA/Guides +/en-US/docs/Web/Accessibility/ARIA/ARIA_Live_Regions /en-US/docs/Web/Accessibility/ARIA/Guides/Live_regions +/en-US/docs/Web/Accessibility/ARIA/ARIA_Screen_Reader_Implementors_Guide /en-US/docs/Web/Accessibility/ARIA/Guides/Screen_Reader_Implementors +/en-US/docs/Web/Accessibility/ARIA/ARIA_Techniques /en-US/docs/Web/Accessibility/ARIA/Guides/Techniques +/en-US/docs/Web/Accessibility/ARIA/ARIA_Techniques/Complementary_role /en-US/docs/Web/Accessibility/ARIA/Reference/Roles/complementary_role +/en-US/docs/Web/Accessibility/ARIA/ARIA_Techniques/Using_the_alert_role /en-US/docs/Web/Accessibility/ARIA/Reference/Roles/alert_role +/en-US/docs/Web/Accessibility/ARIA/ARIA_Techniques/Using_the_alertdialog_role /en-US/docs/Web/Accessibility/ARIA/Reference/Roles/alertdialog_role +/en-US/docs/Web/Accessibility/ARIA/ARIA_Techniques/Using_the_aria-activedescendant_attribute /en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-activedescendant +/en-US/docs/Web/Accessibility/ARIA/ARIA_Techniques/Using_the_aria-describedby_attribute/ /en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-describedby +/en-US/docs/Web/Accessibility/ARIA/ARIA_Techniques/Using_the_aria-hidden_attribute/ /en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-hidden +/en-US/docs/Web/Accessibility/ARIA/ARIA_Techniques/Using_the_aria-invalid_attribute/ /en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-invalid +/en-US/docs/Web/Accessibility/ARIA/ARIA_Techniques/Using_the_aria-invalid_property /en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-invalid +/en-US/docs/Web/Accessibility/ARIA/ARIA_Techniques/Using_the_aria-label_attribute/ /en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-label +/en-US/docs/Web/Accessibility/ARIA/ARIA_Techniques/Using_the_aria-labelledby_attribute/ /en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-labelledby +/en-US/docs/Web/Accessibility/ARIA/ARIA_Techniques/Using_the_aria-orientation_attribute/ /en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-orientation +/en-US/docs/Web/Accessibility/ARIA/ARIA_Techniques/Using_the_aria-relevant_attribute/ /en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-relevant +/en-US/docs/Web/Accessibility/ARIA/ARIA_Techniques/Using_the_aria-required_attribute/ /en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-required +/en-US/docs/Web/Accessibility/ARIA/ARIA_Techniques/Using_the_aria-required_property /en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-required +/en-US/docs/Web/Accessibility/ARIA/ARIA_Techniques/Using_the_aria-valuemax_attribute/ /en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-valuemax +/en-US/docs/Web/Accessibility/ARIA/ARIA_Techniques/Using_the_aria-valuemin_attribute/ /en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-valuemin +/en-US/docs/Web/Accessibility/ARIA/ARIA_Techniques/Using_the_aria-valuenow_attribute/ /en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-valuenow +/en-US/docs/Web/Accessibility/ARIA/ARIA_Techniques/Using_the_aria-valuetext_attribute/ /en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-valuetext +/en-US/docs/Web/Accessibility/ARIA/ARIA_Techniques/Using_the_article_role /en-US/docs/Web/Accessibility/ARIA/Reference/Roles/article_role +/en-US/docs/Web/Accessibility/ARIA/ARIA_Techniques/Using_the_banner_role /en-US/docs/Web/Accessibility/ARIA/Reference/Roles/banner_role +/en-US/docs/Web/Accessibility/ARIA/ARIA_Techniques/Using_the_button_role /en-US/docs/Web/Accessibility/ARIA/Reference/Roles/button_role +/en-US/docs/Web/Accessibility/ARIA/ARIA_Techniques/Using_the_checkbox_role /en-US/docs/Web/Accessibility/ARIA/Reference/Roles/checkbox_role +/en-US/docs/Web/Accessibility/ARIA/ARIA_Techniques/Using_the_dialog_role /en-US/docs/Web/Accessibility/ARIA/Reference/Roles/dialog_role +/en-US/docs/Web/Accessibility/ARIA/ARIA_Techniques/Using_the_group_role /en-US/docs/Web/Accessibility/ARIA/Reference/Roles/group_role +/en-US/docs/Web/Accessibility/ARIA/ARIA_Techniques/Using_the_link_role /en-US/docs/Web/Accessibility/ARIA/Reference/Roles/link_role +/en-US/docs/Web/Accessibility/ARIA/ARIA_Techniques/Using_the_listbox_role /en-US/docs/Web/Accessibility/ARIA/Reference/Roles/listbox_role +/en-US/docs/Web/Accessibility/ARIA/ARIA_Techniques/Using_the_log_role /en-US/docs/Web/Accessibility/ARIA/Reference/Roles/log_role +/en-US/docs/Web/Accessibility/ARIA/ARIA_Techniques/Using_the_presentation_role /en-US/docs/Web/Accessibility/ARIA/Reference/Roles/presentation_role +/en-US/docs/Web/Accessibility/ARIA/ARIA_Techniques/Using_the_progressbar_role /en-US/docs/Web/Accessibility/ARIA/Reference/Roles/progressbar_role +/en-US/docs/Web/Accessibility/ARIA/ARIA_Techniques/Using_the_radio_role /en-US/docs/Web/Accessibility/ARIA/Reference/Roles/radio_role +/en-US/docs/Web/Accessibility/ARIA/ARIA_Techniques/Using_the_slider_role /en-US/docs/Web/Accessibility/ARIA/Reference/Roles/slider_role +/en-US/docs/Web/Accessibility/ARIA/ARIA_Techniques/Using_the_status_role /en-US/docs/Web/Accessibility/ARIA/Reference/Roles/status_role +/en-US/docs/Web/Accessibility/ARIA/ARIA_Techniques/Using_the_switch_role /en-US/docs/Web/Accessibility/ARIA/Reference/Roles/switch_role +/en-US/docs/Web/Accessibility/ARIA/ARIA_Techniques/Using_the_textbox_role /en-US/docs/Web/Accessibility/ARIA/Reference/Roles/textbox_role +/en-US/docs/Web/Accessibility/ARIA/ARIA_Techniques/Using_the_toolbar_role /en-US/docs/Web/Accessibility/ARIA/Reference/Roles/toolbar_role /en-US/docs/Web/Accessibility/ARIA/ARIA_Techniques/x-ms-aria-flowfrom /en-US/docs/Web/Accessibility/ARIA /en-US/docs/Web/Accessibility/ARIA/ARIA_Test_Cases /en-US/docs/Web/Accessibility/ARIA /en-US/docs/Web/Accessibility/ARIA/Annotations /en-US/docs/Web/Accessibility/ARIA +/en-US/docs/Web/Accessibility/ARIA/Attributes /en-US/docs/Web/Accessibility/ARIA/Reference/Attributes +/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-activedescendant /en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-activedescendant +/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-atomic /en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-atomic +/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-autocomplete /en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-autocomplete +/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-braillelabel /en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-braillelabel +/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-brailleroledescription /en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-brailleroledescription +/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-busy /en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-busy +/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-checked /en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-checked +/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-colcount /en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-colcount +/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-colindex /en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-colindex +/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-colindextext /en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-colindextext +/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-colspan /en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-colspan +/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-controls /en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-controls +/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-current /en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-current +/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-describedby /en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-describedby +/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-description /en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-description +/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-details /en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-details +/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-disabled /en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-disabled +/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-dropeffect /en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-dropeffect +/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-errormessage /en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-errormessage +/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-expanded /en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-expanded +/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-flowto /en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-flowto +/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-grabbed /en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-grabbed +/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-haspopup /en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-haspopup +/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-hidden /en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-hidden +/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-invalid /en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-invalid +/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-keyshortcuts /en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-keyshortcuts +/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-label /en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-label +/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-labelledby /en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-labelledby +/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-level /en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-level +/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-live /en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-live +/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-modal /en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-modal +/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-multiline /en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-multiline +/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-multiselectable /en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-multiselectable +/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-orientation /en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-orientation +/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-owns /en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-owns +/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-placeholder /en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-placeholder +/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-posinset /en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-posinset +/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-pressed /en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-pressed +/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-readonly /en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-readonly +/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-relevant /en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-relevant +/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-required /en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-required +/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-roledescription /en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-roledescription +/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-rowcount /en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-rowcount +/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-rowindex /en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-rowindex +/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-rowindextext /en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-rowindextext +/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-rowspan /en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-rowspan +/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-selected /en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-selected +/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-setsize /en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-setsize +/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-sort /en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-sort +/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-valuemax /en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-valuemax +/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-valuemin /en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-valuemin +/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-valuenow /en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-valuenow +/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-valuetext /en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-valuetext /en-US/docs/Web/Accessibility/ARIA/Basic_form_hints /en-US/docs/Web/Accessibility/ARIA -/en-US/docs/Web/Accessibility/ARIA/Roles/ARIA:_tabpanel_role /en-US/docs/Web/Accessibility/ARIA/Roles/tabpanel_role -/en-US/docs/Web/Accessibility/ARIA/Roles/ARIA:_timer_role /en-US/docs/Web/Accessibility/ARIA/Roles/timer_role -/en-US/docs/Web/Accessibility/ARIA/Roles/aria_timer_role /en-US/docs/Web/Accessibility/ARIA/Roles/timer_role -/en-US/docs/Web/Accessibility/ARIA/Roles/checkbox /en-US/docs/Web/Accessibility/ARIA/Roles/checkbox_role -/en-US/docs/Web/Accessibility/ARIA/Roles/dialog /en-US/docs/Web/Accessibility/ARIA/Roles/dialog_role +/en-US/docs/Web/Accessibility/ARIA/How_to_file_ARIA-related_bugs /en-US/docs/Web/Accessibility/ARIA/How_to/File_ARIA-related_bugs +/en-US/docs/Web/Accessibility/ARIA/Multipart_labels /en-US/docs/Web/Accessibility/ARIA/Guides/Multipart_labels +/en-US/docs/Web/Accessibility/ARIA/Roles /en-US/docs/Web/Accessibility/ARIA/Reference/Roles +/en-US/docs/Web/Accessibility/ARIA/Roles/ARIA:_tabpanel_role /en-US/docs/Web/Accessibility/ARIA/Reference/Roles/tabpanel_role +/en-US/docs/Web/Accessibility/ARIA/Roles/ARIA:_timer_role /en-US/docs/Web/Accessibility/ARIA/Reference/Roles/timer_role +/en-US/docs/Web/Accessibility/ARIA/Roles/alert_role /en-US/docs/Web/Accessibility/ARIA/Reference/Roles/alert_role +/en-US/docs/Web/Accessibility/ARIA/Roles/alertdialog_role /en-US/docs/Web/Accessibility/ARIA/Reference/Roles/alertdialog_role +/en-US/docs/Web/Accessibility/ARIA/Roles/application_role /en-US/docs/Web/Accessibility/ARIA/Reference/Roles/application_role +/en-US/docs/Web/Accessibility/ARIA/Roles/aria_timer_role /en-US/docs/Web/Accessibility/ARIA/Reference/Roles/timer_role +/en-US/docs/Web/Accessibility/ARIA/Roles/article_role /en-US/docs/Web/Accessibility/ARIA/Reference/Roles/article_role +/en-US/docs/Web/Accessibility/ARIA/Roles/banner_role /en-US/docs/Web/Accessibility/ARIA/Reference/Roles/banner_role +/en-US/docs/Web/Accessibility/ARIA/Roles/button_role /en-US/docs/Web/Accessibility/ARIA/Reference/Roles/button_role +/en-US/docs/Web/Accessibility/ARIA/Roles/cell_role /en-US/docs/Web/Accessibility/ARIA/Reference/Roles/cell_role +/en-US/docs/Web/Accessibility/ARIA/Roles/checkbox /en-US/docs/Web/Accessibility/ARIA/Reference/Roles/checkbox_role +/en-US/docs/Web/Accessibility/ARIA/Roles/checkbox_role /en-US/docs/Web/Accessibility/ARIA/Reference/Roles/checkbox_role +/en-US/docs/Web/Accessibility/ARIA/Roles/columnheader_role /en-US/docs/Web/Accessibility/ARIA/Reference/Roles/columnheader_role +/en-US/docs/Web/Accessibility/ARIA/Roles/combobox_role /en-US/docs/Web/Accessibility/ARIA/Reference/Roles/combobox_role +/en-US/docs/Web/Accessibility/ARIA/Roles/command_role /en-US/docs/Web/Accessibility/ARIA/Reference/Roles/command_role +/en-US/docs/Web/Accessibility/ARIA/Roles/comment_role /en-US/docs/Web/Accessibility/ARIA/Reference/Roles/comment_role +/en-US/docs/Web/Accessibility/ARIA/Roles/complementary_role /en-US/docs/Web/Accessibility/ARIA/Reference/Roles/complementary_role +/en-US/docs/Web/Accessibility/ARIA/Roles/composite_role /en-US/docs/Web/Accessibility/ARIA/Reference/Roles/composite_role +/en-US/docs/Web/Accessibility/ARIA/Roles/contentinfo_role /en-US/docs/Web/Accessibility/ARIA/Reference/Roles/contentinfo_role +/en-US/docs/Web/Accessibility/ARIA/Roles/definition_role /en-US/docs/Web/Accessibility/ARIA/Reference/Roles/definition_role +/en-US/docs/Web/Accessibility/ARIA/Roles/dialog /en-US/docs/Web/Accessibility/ARIA/Reference/Roles/dialog_role +/en-US/docs/Web/Accessibility/ARIA/Roles/dialog_role /en-US/docs/Web/Accessibility/ARIA/Reference/Roles/dialog_role +/en-US/docs/Web/Accessibility/ARIA/Roles/directory_role /en-US/docs/Web/Accessibility/ARIA/Reference/Roles/directory_role +/en-US/docs/Web/Accessibility/ARIA/Roles/document_role /en-US/docs/Web/Accessibility/ARIA/Reference/Roles/document_role +/en-US/docs/Web/Accessibility/ARIA/Roles/feed_role /en-US/docs/Web/Accessibility/ARIA/Reference/Roles/feed_role +/en-US/docs/Web/Accessibility/ARIA/Roles/figure_role /en-US/docs/Web/Accessibility/ARIA/Reference/Roles/figure_role +/en-US/docs/Web/Accessibility/ARIA/Roles/form_role /en-US/docs/Web/Accessibility/ARIA/Reference/Roles/form_role +/en-US/docs/Web/Accessibility/ARIA/Roles/generic_role /en-US/docs/Web/Accessibility/ARIA/Reference/Roles/generic_role +/en-US/docs/Web/Accessibility/ARIA/Roles/grid_role /en-US/docs/Web/Accessibility/ARIA/Reference/Roles/grid_role +/en-US/docs/Web/Accessibility/ARIA/Roles/gridcell_role /en-US/docs/Web/Accessibility/ARIA/Reference/Roles/gridcell_role +/en-US/docs/Web/Accessibility/ARIA/Roles/group_role /en-US/docs/Web/Accessibility/ARIA/Reference/Roles/group_role +/en-US/docs/Web/Accessibility/ARIA/Roles/heading_role /en-US/docs/Web/Accessibility/ARIA/Reference/Roles/heading_role +/en-US/docs/Web/Accessibility/ARIA/Roles/img_role /en-US/docs/Web/Accessibility/ARIA/Reference/Roles/img_role +/en-US/docs/Web/Accessibility/ARIA/Roles/input_role /en-US/docs/Web/Accessibility/ARIA/Reference/Roles/input_role +/en-US/docs/Web/Accessibility/ARIA/Roles/landmark_role /en-US/docs/Web/Accessibility/ARIA/Reference/Roles/landmark_role +/en-US/docs/Web/Accessibility/ARIA/Roles/link_role /en-US/docs/Web/Accessibility/ARIA/Reference/Roles/link_role +/en-US/docs/Web/Accessibility/ARIA/Roles/list_role /en-US/docs/Web/Accessibility/ARIA/Reference/Roles/list_role +/en-US/docs/Web/Accessibility/ARIA/Roles/listbox_role /en-US/docs/Web/Accessibility/ARIA/Reference/Roles/listbox_role +/en-US/docs/Web/Accessibility/ARIA/Roles/listitem_role /en-US/docs/Web/Accessibility/ARIA/Reference/Roles/listitem_role +/en-US/docs/Web/Accessibility/ARIA/Roles/log_role /en-US/docs/Web/Accessibility/ARIA/Reference/Roles/log_role +/en-US/docs/Web/Accessibility/ARIA/Roles/main_role /en-US/docs/Web/Accessibility/ARIA/Reference/Roles/main_role +/en-US/docs/Web/Accessibility/ARIA/Roles/mark_role /en-US/docs/Web/Accessibility/ARIA/Reference/Roles/mark_role +/en-US/docs/Web/Accessibility/ARIA/Roles/marquee_role /en-US/docs/Web/Accessibility/ARIA/Reference/Roles/marquee_role +/en-US/docs/Web/Accessibility/ARIA/Roles/math_role /en-US/docs/Web/Accessibility/ARIA/Reference/Roles/math_role +/en-US/docs/Web/Accessibility/ARIA/Roles/menu_role /en-US/docs/Web/Accessibility/ARIA/Reference/Roles/menu_role +/en-US/docs/Web/Accessibility/ARIA/Roles/menubar_role /en-US/docs/Web/Accessibility/ARIA/Reference/Roles/menubar_role +/en-US/docs/Web/Accessibility/ARIA/Roles/menuitem_role /en-US/docs/Web/Accessibility/ARIA/Reference/Roles/menuitem_role +/en-US/docs/Web/Accessibility/ARIA/Roles/menuitemcheckbox_role /en-US/docs/Web/Accessibility/ARIA/Reference/Roles/menuitemcheckbox_role +/en-US/docs/Web/Accessibility/ARIA/Roles/menuitemradio_role /en-US/docs/Web/Accessibility/ARIA/Reference/Roles/menuitemradio_role +/en-US/docs/Web/Accessibility/ARIA/Roles/meter_role /en-US/docs/Web/Accessibility/ARIA/Reference/Roles/meter_role +/en-US/docs/Web/Accessibility/ARIA/Roles/navigation_role /en-US/docs/Web/Accessibility/ARIA/Reference/Roles/navigation_role +/en-US/docs/Web/Accessibility/ARIA/Roles/none_role /en-US/docs/Web/Accessibility/ARIA/Reference/Roles/none_role +/en-US/docs/Web/Accessibility/ARIA/Roles/note_role /en-US/docs/Web/Accessibility/ARIA/Reference/Roles/note_role +/en-US/docs/Web/Accessibility/ARIA/Roles/option_role /en-US/docs/Web/Accessibility/ARIA/Reference/Roles/option_role +/en-US/docs/Web/Accessibility/ARIA/Roles/presentation_role /en-US/docs/Web/Accessibility/ARIA/Reference/Roles/presentation_role +/en-US/docs/Web/Accessibility/ARIA/Roles/progressbar_role /en-US/docs/Web/Accessibility/ARIA/Reference/Roles/progressbar_role +/en-US/docs/Web/Accessibility/ARIA/Roles/radio_role /en-US/docs/Web/Accessibility/ARIA/Reference/Roles/radio_role +/en-US/docs/Web/Accessibility/ARIA/Roles/radiogroup_role /en-US/docs/Web/Accessibility/ARIA/Reference/Roles/radiogroup_role +/en-US/docs/Web/Accessibility/ARIA/Roles/range_role /en-US/docs/Web/Accessibility/ARIA/Reference/Roles/range_role +/en-US/docs/Web/Accessibility/ARIA/Roles/region_role /en-US/docs/Web/Accessibility/ARIA/Reference/Roles/region_role +/en-US/docs/Web/Accessibility/ARIA/Roles/roletype_role /en-US/docs/Web/Accessibility/ARIA/Reference/Roles/roletype_role +/en-US/docs/Web/Accessibility/ARIA/Roles/row_role /en-US/docs/Web/Accessibility/ARIA/Reference/Roles/row_role +/en-US/docs/Web/Accessibility/ARIA/Roles/rowgroup_role /en-US/docs/Web/Accessibility/ARIA/Reference/Roles/rowgroup_role +/en-US/docs/Web/Accessibility/ARIA/Roles/rowheader_role /en-US/docs/Web/Accessibility/ARIA/Reference/Roles/rowheader_role +/en-US/docs/Web/Accessibility/ARIA/Roles/scrollbar_role /en-US/docs/Web/Accessibility/ARIA/Reference/Roles/scrollbar_role +/en-US/docs/Web/Accessibility/ARIA/Roles/search_role /en-US/docs/Web/Accessibility/ARIA/Reference/Roles/search_role +/en-US/docs/Web/Accessibility/ARIA/Roles/searchbox_role /en-US/docs/Web/Accessibility/ARIA/Reference/Roles/searchbox_role +/en-US/docs/Web/Accessibility/ARIA/Roles/section_role /en-US/docs/Web/Accessibility/ARIA/Reference/Roles/section_role +/en-US/docs/Web/Accessibility/ARIA/Roles/sectionhead_role /en-US/docs/Web/Accessibility/ARIA/Reference/Roles/sectionhead_role +/en-US/docs/Web/Accessibility/ARIA/Roles/select_role /en-US/docs/Web/Accessibility/ARIA/Reference/Roles/select_role +/en-US/docs/Web/Accessibility/ARIA/Roles/separator_role /en-US/docs/Web/Accessibility/ARIA/Reference/Roles/separator_role +/en-US/docs/Web/Accessibility/ARIA/Roles/slider_role /en-US/docs/Web/Accessibility/ARIA/Reference/Roles/slider_role +/en-US/docs/Web/Accessibility/ARIA/Roles/spinbutton_role /en-US/docs/Web/Accessibility/ARIA/Reference/Roles/spinbutton_role +/en-US/docs/Web/Accessibility/ARIA/Roles/status_role /en-US/docs/Web/Accessibility/ARIA/Reference/Roles/status_role +/en-US/docs/Web/Accessibility/ARIA/Roles/structural_roles /en-US/docs/Web/Accessibility/ARIA/Reference/Roles/structural_roles +/en-US/docs/Web/Accessibility/ARIA/Roles/structure_role /en-US/docs/Web/Accessibility/ARIA/Reference/Roles/structure_role +/en-US/docs/Web/Accessibility/ARIA/Roles/suggestion_role /en-US/docs/Web/Accessibility/ARIA/Reference/Roles/suggestion_role +/en-US/docs/Web/Accessibility/ARIA/Roles/switch_role /en-US/docs/Web/Accessibility/ARIA/Reference/Roles/switch_role +/en-US/docs/Web/Accessibility/ARIA/Roles/tab_role /en-US/docs/Web/Accessibility/ARIA/Reference/Roles/tab_role +/en-US/docs/Web/Accessibility/ARIA/Roles/table_role /en-US/docs/Web/Accessibility/ARIA/Reference/Roles/table_role +/en-US/docs/Web/Accessibility/ARIA/Roles/tablist_role /en-US/docs/Web/Accessibility/ARIA/Reference/Roles/tablist_role +/en-US/docs/Web/Accessibility/ARIA/Roles/tabpanel_role /en-US/docs/Web/Accessibility/ARIA/Reference/Roles/tabpanel_role +/en-US/docs/Web/Accessibility/ARIA/Roles/term_role /en-US/docs/Web/Accessibility/ARIA/Reference/Roles/term_role +/en-US/docs/Web/Accessibility/ARIA/Roles/textbox_role /en-US/docs/Web/Accessibility/ARIA/Reference/Roles/textbox_role +/en-US/docs/Web/Accessibility/ARIA/Roles/timer_role /en-US/docs/Web/Accessibility/ARIA/Reference/Roles/timer_role +/en-US/docs/Web/Accessibility/ARIA/Roles/toolbar_role /en-US/docs/Web/Accessibility/ARIA/Reference/Roles/toolbar_role +/en-US/docs/Web/Accessibility/ARIA/Roles/tooltip_role /en-US/docs/Web/Accessibility/ARIA/Reference/Roles/tooltip_role +/en-US/docs/Web/Accessibility/ARIA/Roles/tree_role /en-US/docs/Web/Accessibility/ARIA/Reference/Roles/tree_role +/en-US/docs/Web/Accessibility/ARIA/Roles/treegrid_role /en-US/docs/Web/Accessibility/ARIA/Reference/Roles/treegrid_role +/en-US/docs/Web/Accessibility/ARIA/Roles/treeitem_role /en-US/docs/Web/Accessibility/ARIA/Reference/Roles/treeitem_role +/en-US/docs/Web/Accessibility/ARIA/Roles/widget_role /en-US/docs/Web/Accessibility/ARIA/Reference/Roles/widget_role +/en-US/docs/Web/Accessibility/ARIA/Roles/window_role /en-US/docs/Web/Accessibility/ARIA/Reference/Roles/window_role /en-US/docs/Web/Accessibility/ARIA/Web_applications_and_ARIA_FAQ /en-US/docs/Web/Accessibility/ARIA /en-US/docs/Web/Accessibility/ARIA/examples /en-US/docs/Web/Accessibility/ARIA /en-US/docs/Web/Accessibility/ARIA/forms /en-US/docs/Web/Accessibility/ARIA /en-US/docs/Web/Accessibility/ARIA/forms/Basic_form_hints /en-US/docs/Web/Accessibility/ARIA -/en-US/docs/Web/Accessibility/ARIA/forms/Multipart_labels /en-US/docs/Web/Accessibility/ARIA/Multipart_labels +/en-US/docs/Web/Accessibility/ARIA/forms/Multipart_labels /en-US/docs/Web/Accessibility/ARIA/Guides/Multipart_labels /en-US/docs/Web/Accessibility/ARIA/forms/alerts /en-US/docs/Web/Accessibility/ARIA /en-US/docs/Web/Accessibility/ARIA/widgets /en-US/docs/Web/Accessibility/ARIA /en-US/docs/Web/Accessibility/ARIA/widgets/overview /en-US/docs/Web/Accessibility/ARIA -/en-US/docs/Web/Accessibility/Accessible_dynamic_content /en-US/docs/Web/Accessibility/An_overview_of_accessible_web_applications_and_widgets +/en-US/docs/Web/Accessibility/Accessibility:_What_users_can_to_to_browse_safely /en-US/docs/Web/Accessibility/Guides/Browsing_safely +/en-US/docs/Web/Accessibility/Accessibility_and_Spacial_Patterns /en-US/docs/Web/Accessibility/Guides/Accessibility_and_Spatial_Patterns +/en-US/docs/Web/Accessibility/Accessible_dynamic_content /en-US/docs/Web/Accessibility/Guides/Accessible_web_applications_and_widgets /en-US/docs/Web/Accessibility/Accessible_forms/alerts /en-US/docs/Web/Accessibility/ARIA +/en-US/docs/Web/Accessibility/An_overview_of_accessible_web_applications_and_widgets /en-US/docs/Web/Accessibility/Guides/Accessible_web_applications_and_widgets +/en-US/docs/Web/Accessibility/Cognitive_accessibility /en-US/docs/Web/Accessibility/Guides/Cognitive_accessibility /en-US/docs/Web/Accessibility/Community /en-US/docs/Web/Accessibility /en-US/docs/Web/Accessibility/FAQ /en-US/docs/Web/Accessibility +/en-US/docs/Web/Accessibility/Guides/Accessibility_and_Spacial_Patterns /en-US/docs/Web/Accessibility/Guides/Accessibility_and_Spatial_Patterns /en-US/docs/Web/Accessibility/HTML_To_MSAA /en-US/docs/Web/Accessibility /en-US/docs/Web/Accessibility/Implementing_MSAA_server /en-US/docs/Web/Accessibility /en-US/docs/Web/Accessibility/Implementing_an_MSAA_Server /en-US/docs/Web/Accessibility /en-US/docs/Web/Accessibility/Index /en-US/docs/Web/Accessibility -/en-US/docs/Web/Accessibility/Seizure_disorders/Accessibility_and_Spacial_Patterns /en-US/docs/Web/Accessibility/Accessibility_and_Spacial_Patterns -/en-US/docs/Web/Accessibility/Understanding_WCAG/Understandable/Text_labels_and_names /en-US/docs/Web/Accessibility/Understanding_WCAG/Text_labels_and_names +/en-US/docs/Web/Accessibility/Information_for_Web_authors /en-US/docs/Web/Accessibility/Guides/Information_for_Web_authors +/en-US/docs/Web/Accessibility/Keyboard-navigable_JavaScript_widgets /en-US/docs/Web/Accessibility/Guides/Keyboard-navigable_JavaScript_widgets +/en-US/docs/Web/Accessibility/Mobile_accessibility_checklist /en-US/docs/Web/Accessibility/Guides/Mobile_accessibility_checklist +/en-US/docs/Web/Accessibility/Seizure_disorders /en-US/docs/Web/Accessibility/Guides/Seizure_disorders +/en-US/docs/Web/Accessibility/Seizure_disorders/Accessibility_and_Spacial_Patterns /en-US/docs/Web/Accessibility/Guides/Accessibility_and_Spatial_Patterns +/en-US/docs/Web/Accessibility/Understanding_Colors_and_Luminance /en-US/docs/Web/Accessibility/Guides/Colors_and_Luminance +/en-US/docs/Web/Accessibility/Understanding_WCAG /en-US/docs/Web/Accessibility/Guides/Understanding_WCAG +/en-US/docs/Web/Accessibility/Understanding_WCAG/Keyboard /en-US/docs/Web/Accessibility/Guides/Understanding_WCAG/Keyboard +/en-US/docs/Web/Accessibility/Understanding_WCAG/Operable /en-US/docs/Web/Accessibility/Guides/Understanding_WCAG/Operable +/en-US/docs/Web/Accessibility/Understanding_WCAG/Perceivable /en-US/docs/Web/Accessibility/Guides/Understanding_WCAG/Perceivable +/en-US/docs/Web/Accessibility/Understanding_WCAG/Perceivable/Color_contrast /en-US/docs/Web/Accessibility/Guides/Understanding_WCAG/Perceivable/Color_contrast +/en-US/docs/Web/Accessibility/Understanding_WCAG/Perceivable/Use_of_color /en-US/docs/Web/Accessibility/Guides/Understanding_WCAG/Perceivable/Use_of_color +/en-US/docs/Web/Accessibility/Understanding_WCAG/Robust /en-US/docs/Web/Accessibility/Guides/Understanding_WCAG/Robust +/en-US/docs/Web/Accessibility/Understanding_WCAG/Text_labels_and_names /en-US/docs/Web/Accessibility/Guides/Understanding_WCAG/Text_labels_and_names +/en-US/docs/Web/Accessibility/Understanding_WCAG/Understandable /en-US/docs/Web/Accessibility/Guides/Understanding_WCAG/Understandable +/en-US/docs/Web/Accessibility/Understanding_WCAG/Understandable/Text_labels_and_names /en-US/docs/Web/Accessibility/Guides/Understanding_WCAG/Text_labels_and_names /en-US/docs/Web/Accessibility/Web_Development /en-US/docs/Web/Accessibility /en-US/docs/Web/Accessibility/Web_applications_and_ARIA_FAQ /en-US/docs/Web/Accessibility/ARIA /en-US/docs/Web/Apps /en-US/docs/Web/Progressive_web_apps @@ -11825,7 +12090,7 @@ /en-US/docs/Web/CSS/Adjacent_sibling_selectors /en-US/docs/Web/CSS/Next-sibling_combinator /en-US/docs/Web/CSS/Alias /en-US/docs/Web/CSS/cursor /en-US/docs/Web/CSS/All_About_The_Containing_Block /en-US/docs/Web/CSS/CSS_display/Containing_block -/en-US/docs/Web/CSS/Alternative_style_sheets /en-US/docs/Web/HTML/Attributes/rel/alternate_stylesheet +/en-US/docs/Web/CSS/Alternative_style_sheets /en-US/docs/Web/HTML/Reference/Attributes/rel/alternate_stylesheet /en-US/docs/Web/CSS/At-rule /en-US/docs/Web/CSS/CSS_syntax/At-rule /en-US/docs/Web/CSS/At-rule-functions /en-US/docs/Web/CSS/CSS_syntax/At-rule_functions /en-US/docs/Web/CSS/Aural /en-US/docs/Web/CSS/@media/aural @@ -11880,6 +12145,7 @@ /en-US/docs/Web/CSS/CSS_Grid_Layout/Realizing_common_layouts_using_CSS_Grid_Layout /en-US/docs/Web/CSS/CSS_grid_layout/Realizing_common_layouts_using_grids /en-US/docs/Web/CSS/CSS_Grid_Layout/Realizing_common_layouts_using_CSS_Grid_Layout_ /en-US/docs/Web/CSS/CSS_grid_layout/Realizing_common_layouts_using_grids /en-US/docs/Web/CSS/CSS_Grid_Layout/Relationship_of_Grid_Layout /en-US/docs/Web/CSS/CSS_grid_layout/Relationship_of_grid_layout_with_other_layout_methods +/en-US/docs/Web/CSS/CSS_Houdini /en-US/docs/Web/CSS/CSS_properties_and_values_API/Houdini /en-US/docs/Web/CSS/CSS_Lists_and_Counters /en-US/docs/Web/CSS/CSS_lists /en-US/docs/Web/CSS/CSS_Lists_and_Counters/Consistent_list_indentation /en-US/docs/Web/CSS/CSS_lists/Consistent_list_indentation /en-US/docs/Web/CSS/CSS_Lists_and_Counters/Using_CSS_counters /en-US/docs/Web/CSS/CSS_counter_styles/Using_CSS_counters @@ -11896,24 +12162,24 @@ /en-US/docs/Web/CSS/CSS_Pages /en-US/docs/Web/CSS/CSS_paged_media /en-US/docs/Web/CSS/CSS_Positioning /en-US/docs/Web/CSS/CSS_positioned_layout /en-US/docs/Web/CSS/CSS_Positioning/Understanding_z-index /en-US/docs/Web/CSS/CSS_positioned_layout/Understanding_z-index -/en-US/docs/Web/CSS/CSS_Positioning/Understanding_z-index/Stacking_context /en-US/docs/Web/CSS/CSS_positioned_layout/Understanding_z-index/Stacking_context -/en-US/docs/Web/CSS/CSS_Positioning/Understanding_z-index/Stacking_context_example_1 /en-US/docs/Web/CSS/CSS_positioned_layout/Understanding_z-index/Stacking_context_example_1 -/en-US/docs/Web/CSS/CSS_Positioning/Understanding_z-index/Stacking_context_example_2 /en-US/docs/Web/CSS/CSS_positioned_layout/Understanding_z-index/Stacking_context_example_2 -/en-US/docs/Web/CSS/CSS_Positioning/Understanding_z-index/Stacking_context_example_3 /en-US/docs/Web/CSS/CSS_positioned_layout/Understanding_z-index/Stacking_context_example_3 -/en-US/docs/Web/CSS/CSS_Positioning/Understanding_z-index/Stacking_floating_elements /en-US/docs/Web/CSS/CSS_positioned_layout/Understanding_z-index/Stacking_floating_elements -/en-US/docs/Web/CSS/CSS_Positioning/Understanding_z-index/Stacking_without_z-index /en-US/docs/Web/CSS/CSS_positioned_layout/Understanding_z-index/Stacking_without_z-index -/en-US/docs/Web/CSS/CSS_Positioning/Understanding_z-index/Using_z-index /en-US/docs/Web/CSS/CSS_positioned_layout/Understanding_z-index/Using_z-index +/en-US/docs/Web/CSS/CSS_Positioning/Understanding_z-index/Stacking_context /en-US/docs/Web/CSS/CSS_positioned_layout/Stacking_context +/en-US/docs/Web/CSS/CSS_Positioning/Understanding_z-index/Stacking_context_example_1 /en-US/docs/Web/CSS/CSS_positioned_layout/Stacking_context/Stacking_context_example_1 +/en-US/docs/Web/CSS/CSS_Positioning/Understanding_z-index/Stacking_context_example_2 /en-US/docs/Web/CSS/CSS_positioned_layout/Stacking_context/Stacking_context_example_2 +/en-US/docs/Web/CSS/CSS_Positioning/Understanding_z-index/Stacking_context_example_3 /en-US/docs/Web/CSS/CSS_positioned_layout/Stacking_context/Stacking_context_example_3 +/en-US/docs/Web/CSS/CSS_Positioning/Understanding_z-index/Stacking_floating_elements /en-US/docs/Web/CSS/CSS_positioned_layout/Stacking_floating_elements +/en-US/docs/Web/CSS/CSS_Positioning/Understanding_z-index/Stacking_without_z-index /en-US/docs/Web/CSS/CSS_positioned_layout/Stacking_without_z-index +/en-US/docs/Web/CSS/CSS_Positioning/Understanding_z-index/Using_z-index /en-US/docs/Web/CSS/CSS_positioned_layout/Using_z-index /en-US/docs/Web/CSS/CSS_Positioning/Understanding_z_index /en-US/docs/Web/CSS/CSS_positioned_layout/Understanding_z-index -/en-US/docs/Web/CSS/CSS_Positioning/Understanding_z_index/Adding_z-index /en-US/docs/Web/CSS/CSS_positioned_layout/Understanding_z-index/Using_z-index -/en-US/docs/Web/CSS/CSS_Positioning/Understanding_z_index/Stacking_and_float /en-US/docs/Web/CSS/CSS_positioned_layout/Understanding_z-index/Stacking_floating_elements -/en-US/docs/Web/CSS/CSS_Positioning/Understanding_z_index/Stacking_context /en-US/docs/Web/CSS/CSS_positioned_layout/Understanding_z-index/Stacking_context -/en-US/docs/Web/CSS/CSS_Positioning/Understanding_z_index/Stacking_context_example_1 /en-US/docs/Web/CSS/CSS_positioned_layout/Understanding_z-index/Stacking_context_example_1 -/en-US/docs/Web/CSS/CSS_Positioning/Understanding_z_index/Stacking_context_example_2 /en-US/docs/Web/CSS/CSS_positioned_layout/Understanding_z-index/Stacking_context_example_2 -/en-US/docs/Web/CSS/CSS_Positioning/Understanding_z_index/Stacking_context_example_3 /en-US/docs/Web/CSS/CSS_positioned_layout/Understanding_z-index/Stacking_context_example_3 -/en-US/docs/Web/CSS/CSS_Positioning/Understanding_z_index/Stacking_floating_elements /en-US/docs/Web/CSS/CSS_positioned_layout/Understanding_z-index/Stacking_floating_elements -/en-US/docs/Web/CSS/CSS_Positioning/Understanding_z_index/Stacking_without_z-index /en-US/docs/Web/CSS/CSS_positioned_layout/Understanding_z-index/Stacking_without_z-index -/en-US/docs/Web/CSS/CSS_Positioning/Understanding_z_index/The_stacking_context /en-US/docs/Web/CSS/CSS_positioned_layout/Understanding_z-index/Stacking_context -/en-US/docs/Web/CSS/CSS_Positioning/Understanding_z_index/Using_z-index /en-US/docs/Web/CSS/CSS_positioned_layout/Understanding_z-index/Using_z-index +/en-US/docs/Web/CSS/CSS_Positioning/Understanding_z_index/Adding_z-index /en-US/docs/Web/CSS/CSS_positioned_layout/Using_z-index +/en-US/docs/Web/CSS/CSS_Positioning/Understanding_z_index/Stacking_and_float /en-US/docs/Web/CSS/CSS_positioned_layout/Stacking_floating_elements +/en-US/docs/Web/CSS/CSS_Positioning/Understanding_z_index/Stacking_context /en-US/docs/Web/CSS/CSS_positioned_layout/Stacking_context +/en-US/docs/Web/CSS/CSS_Positioning/Understanding_z_index/Stacking_context_example_1 /en-US/docs/Web/CSS/CSS_positioned_layout/Stacking_context/Stacking_context_example_1 +/en-US/docs/Web/CSS/CSS_Positioning/Understanding_z_index/Stacking_context_example_2 /en-US/docs/Web/CSS/CSS_positioned_layout/Stacking_context/Stacking_context_example_2 +/en-US/docs/Web/CSS/CSS_Positioning/Understanding_z_index/Stacking_context_example_3 /en-US/docs/Web/CSS/CSS_positioned_layout/Stacking_context/Stacking_context_example_3 +/en-US/docs/Web/CSS/CSS_Positioning/Understanding_z_index/Stacking_floating_elements /en-US/docs/Web/CSS/CSS_positioned_layout/Stacking_floating_elements +/en-US/docs/Web/CSS/CSS_Positioning/Understanding_z_index/Stacking_without_z-index /en-US/docs/Web/CSS/CSS_positioned_layout/Stacking_without_z-index +/en-US/docs/Web/CSS/CSS_Positioning/Understanding_z_index/The_stacking_context /en-US/docs/Web/CSS/CSS_positioned_layout/Stacking_context +/en-US/docs/Web/CSS/CSS_Positioning/Understanding_z_index/Using_z-index /en-US/docs/Web/CSS/CSS_positioned_layout/Using_z-index /en-US/docs/Web/CSS/CSS_Properties_Reference /en-US/docs/Web/CSS/Reference#index /en-US/docs/Web/CSS/CSS_Reference /en-US/docs/Web/CSS/Reference /en-US/docs/Web/CSS/CSS_Reference/Mozilla_Extensions /en-US/docs/Web/CSS/Mozilla_Extensions @@ -11935,6 +12201,11 @@ /en-US/docs/Web/CSS/CSS_Variables /en-US/docs/Web/CSS/CSS_cascading_variables /en-US/docs/Web/CSS/CSS_Viewport /en-US/docs/Web/CSS /en-US/docs/Web/CSS/CSS_animations/Tips /en-US/docs/Web/API/Web_Animations_API/Tips +/en-US/docs/Web/CSS/CSS_cascade/actual_value /en-US/docs/Web/CSS/CSS_cascade/Value_processing#actual_value +/en-US/docs/Web/CSS/CSS_cascade/computed_value /en-US/docs/Web/CSS/CSS_cascade/Value_processing#computed_value +/en-US/docs/Web/CSS/CSS_cascade/initial_value /en-US/docs/Web/CSS/CSS_cascade/Value_processing#initial_value +/en-US/docs/Web/CSS/CSS_cascade/specified_value /en-US/docs/Web/CSS/CSS_cascade/Value_processing#specified_value +/en-US/docs/Web/CSS/CSS_cascade/used_value /en-US/docs/Web/CSS/CSS_cascade/Value_processing#used_value /en-US/docs/Web/CSS/CSS_charsets /en-US/docs/Web/CSS/CSS_syntax /en-US/docs/Web/CSS/CSS_container_queries /en-US/docs/Web/CSS/CSS_containment/Container_queries /en-US/docs/Web/CSS/CSS_descriptor_definition /en-US/docs/Web/CSS @@ -11956,6 +12227,13 @@ /en-US/docs/Web/CSS/CSS_grid_layout/Layout_using_named_grid_lines /en-US/docs/Web/CSS/CSS_grid_layout/Grid_layout_using_named_grid_lines /en-US/docs/Web/CSS/CSS_miscellaneous /en-US/docs/Web/CSS /en-US/docs/Web/CSS/CSS_percentage_values /en-US/docs/Web/CSS +/en-US/docs/Web/CSS/CSS_positioned_layout/Understanding_z-index/Stacking_context /en-US/docs/Web/CSS/CSS_positioned_layout/Stacking_context +/en-US/docs/Web/CSS/CSS_positioned_layout/Understanding_z-index/Stacking_context_example_1 /en-US/docs/Web/CSS/CSS_positioned_layout/Stacking_context/Stacking_context_example_1 +/en-US/docs/Web/CSS/CSS_positioned_layout/Understanding_z-index/Stacking_context_example_2 /en-US/docs/Web/CSS/CSS_positioned_layout/Stacking_context/Stacking_context_example_2 +/en-US/docs/Web/CSS/CSS_positioned_layout/Understanding_z-index/Stacking_context_example_3 /en-US/docs/Web/CSS/CSS_positioned_layout/Stacking_context/Stacking_context_example_3 +/en-US/docs/Web/CSS/CSS_positioned_layout/Understanding_z-index/Stacking_floating_elements /en-US/docs/Web/CSS/CSS_positioned_layout/Stacking_floating_elements +/en-US/docs/Web/CSS/CSS_positioned_layout/Understanding_z-index/Stacking_without_z-index /en-US/docs/Web/CSS/CSS_positioned_layout/Stacking_without_z-index +/en-US/docs/Web/CSS/CSS_positioned_layout/Understanding_z-index/Using_z-index /en-US/docs/Web/CSS/CSS_positioned_layout/Using_z-index /en-US/docs/Web/CSS/CSS_ruby /en-US/docs/Web/CSS/CSS_ruby_layout /en-US/docs/Web/CSS/CSS_special_properties /en-US/docs/Web/CSS /en-US/docs/Web/CSS/CSS_transform_functions /en-US/docs/Web/CSS/transform @@ -11979,8 +12257,10 @@ /en-US/docs/Web/CSS/General_sibling_selectors /en-US/docs/Web/CSS/Subsequent-sibling_combinator /en-US/docs/Web/CSS/Grouping_selectors /en-US/docs/Web/CSS/Selector_list /en-US/docs/Web/CSS/Inheritance /en-US/docs/Web/CSS/CSS_cascade/Inheritance +/en-US/docs/Web/CSS/Inline_formatting_context /en-US/docs/Web/CSS/CSS_inline_layout/Inline_formatting_context /en-US/docs/Web/CSS/Interactive /en-US/docs/Web/CSS/@media /en-US/docs/Web/CSS/Layout_cookbook/Recipe:_Media_Objects /en-US/docs/Web/CSS/Layout_cookbook/Media_objects +/en-US/docs/Web/CSS/Layout_mode /en-US/docs/Glossary/Layout_mode /en-US/docs/Web/CSS/List_of_Proprietary_CSS_Features /en-US/docs/Web/CSS/Reference /en-US/docs/Web/CSS/Media_Queries /en-US/docs/Web/CSS/CSS_media_queries /en-US/docs/Web/CSS/Media_Queries/Testing_media_queries /en-US/docs/Web/CSS/CSS_media_queries/Testing_media_queries @@ -11989,9 +12269,11 @@ /en-US/docs/Web/CSS/Motion_Path /en-US/docs/Web/CSS/CSS_motion_path /en-US/docs/Web/CSS/Other_Resources /en-US/docs/Web/CSS /en-US/docs/Web/CSS/Paged_Media /en-US/docs/Web/CSS/CSS_paged_media +/en-US/docs/Web/CSS/Privacy_and_the_:visited_selector /en-US/docs/Web/CSS/CSS_selectors/Privacy_and_the_visited_selector /en-US/docs/Web/CSS/Reference/Mozilla_Extensions /en-US/docs/Web/CSS/Mozilla_Extensions /en-US/docs/Web/CSS/Reference/Webkit_Extensions /en-US/docs/Web/CSS/WebKit_Extensions /en-US/docs/Web/CSS/Reference/object-position /en-US/docs/Web/CSS/object-position +/en-US/docs/Web/CSS/Replaced_element /en-US/docs/Web/CSS/CSS_images/Replaced_element_properties /en-US/docs/Web/CSS/Scaling_of_SVG_backgrounds /en-US/docs/Web/CSS/CSS_backgrounds_and_borders/Scaling_of_SVG_backgrounds /en-US/docs/Web/CSS/Selector_lists /en-US/docs/Web/CSS/Selector_list /en-US/docs/Web/CSS/Selectors /en-US/docs/Web/CSS/CSS_selectors @@ -12005,13 +12287,13 @@ /en-US/docs/Web/CSS/Tools/Box-shadow_generator /en-US/docs/Web/CSS/CSS_backgrounds_and_borders/Box-shadow_generator /en-US/docs/Web/CSS/Tools/ColorPicker_Tool /en-US/docs/Web/CSS/CSS_colors/Color_picker_tool /en-US/docs/Web/CSS/Understanding_CSS_z-index /en-US/docs/Web/CSS/CSS_positioned_layout/Understanding_z-index -/en-US/docs/Web/CSS/Understanding_CSS_z-index/Adding_z-index /en-US/docs/Web/CSS/CSS_positioned_layout/Understanding_z-index/Using_z-index -/en-US/docs/Web/CSS/Understanding_CSS_z-index/Stacking_and_float /en-US/docs/Web/CSS/CSS_positioned_layout/Understanding_z-index/Stacking_floating_elements -/en-US/docs/Web/CSS/Understanding_CSS_z-index/Stacking_context_example_1 /en-US/docs/Web/CSS/CSS_positioned_layout/Understanding_z-index/Stacking_context_example_1 -/en-US/docs/Web/CSS/Understanding_CSS_z-index/Stacking_context_example_2 /en-US/docs/Web/CSS/CSS_positioned_layout/Understanding_z-index/Stacking_context_example_2 -/en-US/docs/Web/CSS/Understanding_CSS_z-index/Stacking_context_example_3 /en-US/docs/Web/CSS/CSS_positioned_layout/Understanding_z-index/Stacking_context_example_3 -/en-US/docs/Web/CSS/Understanding_CSS_z-index/Stacking_without_z-index /en-US/docs/Web/CSS/CSS_positioned_layout/Understanding_z-index/Stacking_without_z-index -/en-US/docs/Web/CSS/Understanding_CSS_z-index/The_stacking_context /en-US/docs/Web/CSS/CSS_positioned_layout/Understanding_z-index/Stacking_context +/en-US/docs/Web/CSS/Understanding_CSS_z-index/Adding_z-index /en-US/docs/Web/CSS/CSS_positioned_layout/Using_z-index +/en-US/docs/Web/CSS/Understanding_CSS_z-index/Stacking_and_float /en-US/docs/Web/CSS/CSS_positioned_layout/Stacking_floating_elements +/en-US/docs/Web/CSS/Understanding_CSS_z-index/Stacking_context_example_1 /en-US/docs/Web/CSS/CSS_positioned_layout/Stacking_context/Stacking_context_example_1 +/en-US/docs/Web/CSS/Understanding_CSS_z-index/Stacking_context_example_2 /en-US/docs/Web/CSS/CSS_positioned_layout/Stacking_context/Stacking_context_example_2 +/en-US/docs/Web/CSS/Understanding_CSS_z-index/Stacking_context_example_3 /en-US/docs/Web/CSS/CSS_positioned_layout/Stacking_context/Stacking_context_example_3 +/en-US/docs/Web/CSS/Understanding_CSS_z-index/Stacking_without_z-index /en-US/docs/Web/CSS/CSS_positioned_layout/Stacking_without_z-index +/en-US/docs/Web/CSS/Understanding_CSS_z-index/The_stacking_context /en-US/docs/Web/CSS/CSS_positioned_layout/Stacking_context /en-US/docs/Web/CSS/Using_CSS_Columns /en-US/docs/Web/CSS/CSS_multicol_layout/Using_multicol_layouts /en-US/docs/Web/CSS/Using_CSS_custom_properties /en-US/docs/Web/CSS/CSS_cascading_variables/Using_CSS_custom_properties /en-US/docs/Web/CSS/Using_CSS_media_queries /en-US/docs/Web/CSS/CSS_media_queries/Using_media_queries @@ -12020,9 +12302,10 @@ /en-US/docs/Web/CSS/Using_the_CSS_multi-column_layout /en-US/docs/Web/CSS/CSS_multicol_layout/Using_multicol_layouts /en-US/docs/Web/CSS/Value_definition_syntax /en-US/docs/Web/CSS/CSS_Values_and_Units/Value_definition_syntax /en-US/docs/Web/CSS/Viewport_concepts /en-US/docs/Web/CSS/CSSOM_view/Viewport_concepts +/en-US/docs/Web/CSS/Visual_formatting_model /en-US/docs/Web/CSS/CSS_display/Visual_formatting_model /en-US/docs/Web/CSS/_image /en-US/docs/Web/CSS/image/image /en-US/docs/Web/CSS/abs() /en-US/docs/Web/CSS/abs -/en-US/docs/Web/CSS/actual_value /en-US/docs/Web/CSS/CSS_cascade/actual_value +/en-US/docs/Web/CSS/actual_value /en-US/docs/Web/CSS/CSS_cascade/Value_processing#actual_value /en-US/docs/Web/CSS/additive-symbols /en-US/docs/Web/CSS/@counter-style/additive-symbols /en-US/docs/Web/CSS/align-tracks /en-US/docs/Web/CSS/CSS_grid_layout/Masonry_layout /en-US/docs/Web/CSS/attr() /en-US/docs/Web/CSS/attr @@ -12056,7 +12339,7 @@ /en-US/docs/Web/CSS/color_value/rgba() /en-US/docs/Web/CSS/color_value/rgb /en-US/docs/Web/CSS/color_value/system-color /en-US/docs/Web/CSS/system-color /en-US/docs/Web/CSS/color_value/system_color_keywords /en-US/docs/Web/CSS/system-color -/en-US/docs/Web/CSS/computed_value /en-US/docs/Web/CSS/CSS_cascade/computed_value +/en-US/docs/Web/CSS/computed_value /en-US/docs/Web/CSS/CSS_cascade/Value_processing#computed_value /en-US/docs/Web/CSS/conic-gradient /en-US/docs/Web/CSS/gradient/conic-gradient /en-US/docs/Web/CSS/conic-gradient() /en-US/docs/Web/CSS/gradient/conic-gradient /en-US/docs/Web/CSS/counter() /en-US/docs/Web/CSS/counter @@ -12109,7 +12392,7 @@ /en-US/docs/Web/CSS/image/paint() /en-US/docs/Web/CSS/image/paint /en-US/docs/Web/CSS/imagefunction /en-US/docs/Web/CSS/image/image /en-US/docs/Web/CSS/inherited_and_non-inherited_properties /en-US/docs/Web/CSS/CSS_cascade/Inheritance -/en-US/docs/Web/CSS/initial_value /en-US/docs/Web/CSS/CSS_cascade/initial_value +/en-US/docs/Web/CSS/initial_value /en-US/docs/Web/CSS/CSS_cascade/Value_processing#initial_value /en-US/docs/Web/CSS/inset-area /en-US/docs/Web/CSS/position-area /en-US/docs/Web/CSS/inset-area_value /en-US/docs/Web/CSS/position-area_value /en-US/docs/Web/CSS/justify-tracks /en-US/docs/Web/CSS/CSS_grid_layout/Masonry_layout @@ -12141,6 +12424,7 @@ /en-US/docs/Web/CSS/offset-inline-start /en-US/docs/Web/CSS/inset-inline-start /en-US/docs/Web/CSS/offset-rotation /en-US/docs/Web/CSS/offset-rotate /en-US/docs/Web/CSS/orient /en-US/docs/Web/CSS/-moz-orient +/en-US/docs/Web/CSS/overflow-anchor/Guide_to_scroll_anchoring /en-US/docs/Web/CSS/CSS_scroll_anchoring/Scroll_anchoring /en-US/docs/Web/CSS/overflow-x2 /en-US/docs/Web/CSS/overflow-x /en-US/docs/Web/CSS/pad /en-US/docs/Web/CSS/@counter-style/pad /en-US/docs/Web/CSS/paint /en-US/docs/Web/CSS/image/paint @@ -12158,6 +12442,7 @@ /en-US/docs/Web/CSS/repeating-linear-gradient() /en-US/docs/Web/CSS/gradient/repeating-linear-gradient /en-US/docs/Web/CSS/repeating-radial-gradient /en-US/docs/Web/CSS/gradient/repeating-radial-gradient /en-US/docs/Web/CSS/repeating-radial-gradient() /en-US/docs/Web/CSS/gradient/repeating-radial-gradient +/en-US/docs/Web/CSS/resolved_value /en-US/docs/Web/CSS/CSS_cascade/Value_processing#resolved_value /en-US/docs/Web/CSS/rgb /en-US/docs/Web/CSS/color_value/rgb /en-US/docs/Web/CSS/scroll /en-US/docs/Web/CSS/overflow /en-US/docs/Web/CSS/scrollbar-track-color /en-US/docs/Web/CSS/scrollbar-color @@ -12165,7 +12450,7 @@ /en-US/docs/Web/CSS/sign() /en-US/docs/Web/CSS/sign /en-US/docs/Web/CSS/sign_function /en-US/docs/Web/CSS/sign /en-US/docs/Web/CSS/single-transition-timing-function /en-US/docs/Web/CSS/easing-function -/en-US/docs/Web/CSS/specified_value /en-US/docs/Web/CSS/CSS_cascade/specified_value +/en-US/docs/Web/CSS/specified_value /en-US/docs/Web/CSS/CSS_cascade/Value_processing#specified_value /en-US/docs/Web/CSS/static /en-US/docs/Web/CSS/position /en-US/docs/Web/CSS/suffix /en-US/docs/Web/CSS/@counter-style/suffix /en-US/docs/Web/CSS/symbols() /en-US/docs/Web/CSS/symbols @@ -12199,7 +12484,7 @@ /en-US/docs/Web/CSS/uri /en-US/docs/Web/CSS/url_value /en-US/docs/Web/CSS/url /en-US/docs/Web/CSS/url_value /en-US/docs/Web/CSS/url() /en-US/docs/Web/CSS/url_function -/en-US/docs/Web/CSS/used_value /en-US/docs/Web/CSS/CSS_cascade/used_value +/en-US/docs/Web/CSS/used_value /en-US/docs/Web/CSS/CSS_cascade/Value_processing#used_value /en-US/docs/Web/CSS/user-ident /en-US/docs/Web/CSS/custom-ident /en-US/docs/Web/CSS/var() /en-US/docs/Web/CSS/var /en-US/docs/Web/CSS/visible /en-US/docs/Web/CSS/visibility @@ -12485,7 +12770,7 @@ /en-US/docs/Web/Guide/AJAX /en-US/docs/Learn_web_development/Core/Scripting/Network_requests /en-US/docs/Web/Guide/AJAX/Community /en-US/docs/Learn_web_development/Core/Scripting/Network_requests /en-US/docs/Web/Guide/AJAX/Getting_Started /en-US/docs/Learn_web_development/Core/Scripting/Network_requests -/en-US/docs/Web/Guide/AJAX/WAI_ARIA_Live_Regions /en-US/docs/Web/Accessibility/ARIA/ARIA_Live_Regions +/en-US/docs/Web/Guide/AJAX/WAI_ARIA_Live_Regions /en-US/docs/Web/Accessibility/ARIA/Guides/Live_regions /en-US/docs/Web/Guide/AJAX/WAI_ARIA_Live_Regions_API_Support /en-US/docs/Mozilla/Firefox/Releases/3/WAI_ARIA_Live_Regions_API_Support /en-US/docs/Web/Guide/API /en-US/docs/Web/API /en-US/docs/Web/Guide/API/DOM /en-US/docs/Web/API/Document_Object_Model @@ -12542,8 +12827,8 @@ /en-US/docs/Web/Guide/CSS/Getting_started/JavaScript /en-US/docs/Learn_web_development/Core/Scripting/DOM_scripting /en-US/docs/Web/Guide/CSS/Getting_started/Layout /en-US/docs/Learn_web_development/Core/CSS_layout /en-US/docs/Web/Guide/CSS/Getting_started/Lists /en-US/docs/Learn_web_development/Core/Text_styling/Styling_lists -/en-US/docs/Web/Guide/CSS/Getting_started/SVG_and_CSS /en-US/docs/Web/SVG/Tutorial/SVG_and_CSS -/en-US/docs/Web/Guide/CSS/Getting_started/SVG_graphics /en-US/docs/Web/SVG/Tutorial/SVG_and_CSS +/en-US/docs/Web/Guide/CSS/Getting_started/SVG_and_CSS /en-US/docs/Web/SVG/Tutorials/SVG_from_scratch/SVG_and_CSS +/en-US/docs/Web/Guide/CSS/Getting_started/SVG_graphics /en-US/docs/Web/SVG/Tutorials/SVG_from_scratch/SVG_and_CSS /en-US/docs/Web/Guide/CSS/Getting_started/Selectors /en-US/docs/Learn_web_development/Core/Styling_basics/Basic_selectors /en-US/docs/Web/Guide/CSS/Getting_started/Tables /en-US/docs/Learn_web_development/Core/Styling_basics/Tables /en-US/docs/Web/Guide/CSS/Getting_started/Text_styles /en-US/docs/Learn_web_development/Core/Text_styling/Fundamentals @@ -12554,13 +12839,13 @@ /en-US/docs/Web/Guide/CSS/Scaling_background_images /en-US/docs/Web/CSS/CSS_backgrounds_and_borders/Resizing_background_images /en-US/docs/Web/Guide/CSS/Testing_media_queries /en-US/docs/Web/CSS/CSS_media_queries/Testing_media_queries /en-US/docs/Web/Guide/CSS/Understanding_z_index /en-US/docs/Web/CSS/CSS_positioned_layout/Understanding_z-index -/en-US/docs/Web/Guide/CSS/Understanding_z_index/Adding_z-index /en-US/docs/Web/CSS/CSS_positioned_layout/Understanding_z-index/Using_z-index -/en-US/docs/Web/Guide/CSS/Understanding_z_index/Stacking_and_float /en-US/docs/Web/CSS/CSS_positioned_layout/Understanding_z-index/Stacking_floating_elements -/en-US/docs/Web/Guide/CSS/Understanding_z_index/Stacking_context_example_1 /en-US/docs/Web/CSS/CSS_positioned_layout/Understanding_z-index/Stacking_context_example_1 -/en-US/docs/Web/Guide/CSS/Understanding_z_index/Stacking_context_example_2 /en-US/docs/Web/CSS/CSS_positioned_layout/Understanding_z-index/Stacking_context_example_2 -/en-US/docs/Web/Guide/CSS/Understanding_z_index/Stacking_context_example_3 /en-US/docs/Web/CSS/CSS_positioned_layout/Understanding_z-index/Stacking_context_example_3 -/en-US/docs/Web/Guide/CSS/Understanding_z_index/Stacking_without_z-index /en-US/docs/Web/CSS/CSS_positioned_layout/Understanding_z-index/Stacking_without_z-index -/en-US/docs/Web/Guide/CSS/Understanding_z_index/The_stacking_context /en-US/docs/Web/CSS/CSS_positioned_layout/Understanding_z-index/Stacking_context +/en-US/docs/Web/Guide/CSS/Understanding_z_index/Adding_z-index /en-US/docs/Web/CSS/CSS_positioned_layout/Using_z-index +/en-US/docs/Web/Guide/CSS/Understanding_z_index/Stacking_and_float /en-US/docs/Web/CSS/CSS_positioned_layout/Stacking_floating_elements +/en-US/docs/Web/Guide/CSS/Understanding_z_index/Stacking_context_example_1 /en-US/docs/Web/CSS/CSS_positioned_layout/Stacking_context/Stacking_context_example_1 +/en-US/docs/Web/Guide/CSS/Understanding_z_index/Stacking_context_example_2 /en-US/docs/Web/CSS/CSS_positioned_layout/Stacking_context/Stacking_context_example_2 +/en-US/docs/Web/Guide/CSS/Understanding_z_index/Stacking_context_example_3 /en-US/docs/Web/CSS/CSS_positioned_layout/Stacking_context/Stacking_context_example_3 +/en-US/docs/Web/Guide/CSS/Understanding_z_index/Stacking_without_z-index /en-US/docs/Web/CSS/CSS_positioned_layout/Stacking_without_z-index +/en-US/docs/Web/Guide/CSS/Understanding_z_index/The_stacking_context /en-US/docs/Web/CSS/CSS_positioned_layout/Stacking_context /en-US/docs/Web/Guide/CSS/Using_CSS_animations /en-US/docs/Web/CSS/CSS_animations/Using_CSS_animations /en-US/docs/Web/Guide/CSS/Using_CSS_gradients /en-US/docs/Web/CSS/CSS_images/Using_CSS_gradients /en-US/docs/Web/Guide/CSS/Using_CSS_transforms /en-US/docs/Web/CSS/CSS_transforms/Using_CSS_transforms @@ -12569,7 +12854,7 @@ /en-US/docs/Web/Guide/CSS/Using_multi-column_layouts /en-US/docs/Web/CSS/CSS_multicol_layout/Using_multicol_layouts /en-US/docs/Web/Guide/CSS/Using_multiple_backgrounds /en-US/docs/Web/CSS/CSS_backgrounds_and_borders/Using_multiple_backgrounds /en-US/docs/Web/Guide/CSS/Using_the_:target_selector /en-US/docs/Web/CSS/CSS_selectors/Using_the_:target_pseudo-class_in_selectors -/en-US/docs/Web/Guide/CSS/Visual_formatting_model /en-US/docs/Web/CSS/Visual_formatting_model +/en-US/docs/Web/Guide/CSS/Visual_formatting_model /en-US/docs/Web/CSS/CSS_display/Visual_formatting_model /en-US/docs/Web/Guide/DOM /en-US/docs/Web/API/Document_Object_Model /en-US/docs/Web/Guide/DOM/Events/Creating_and_triggering_events /en-US/docs/Web/Events/Creating_and_triggering_events /en-US/docs/Web/Guide/DOM/Events/Event_dispatching_example /en-US/docs/Web/Events/Creating_and_triggering_events @@ -12613,12 +12898,12 @@ /en-US/docs/Web/Guide/HTML/Canvas_tutorial/Pixel_manipulation_with_canvas /en-US/docs/Web/API/Canvas_API/Tutorial/Pixel_manipulation_with_canvas /en-US/docs/Web/Guide/HTML/Canvas_tutorial/Transformations /en-US/docs/Web/API/Canvas_API/Tutorial/Transformations /en-US/docs/Web/Guide/HTML/Canvas_tutorial/Using_images /en-US/docs/Web/API/Canvas_API/Tutorial/Using_images -/en-US/docs/Web/Guide/HTML/Constraint_validation /en-US/docs/Web/HTML/Constraint_validation -/en-US/docs/Web/Guide/HTML/Content_Editable /en-US/docs/Web/HTML/Global_attributes/contenteditable -/en-US/docs/Web/Guide/HTML/Content_categories /en-US/docs/Web/HTML/Content_categories +/en-US/docs/Web/Guide/HTML/Constraint_validation /en-US/docs/Web/HTML/Guides/Constraint_validation +/en-US/docs/Web/Guide/HTML/Content_Editable /en-US/docs/Web/HTML/Reference/Global_attributes/contenteditable +/en-US/docs/Web/Guide/HTML/Content_categories /en-US/docs/Web/HTML/Guides/Content_categories /en-US/docs/Web/Guide/HTML/Drag_and_drop /en-US/docs/Web/API/HTML_Drag_and_Drop_API /en-US/docs/Web/Guide/HTML/Drag_operations /en-US/docs/Web/API/HTML_Drag_and_Drop_API/Drag_operations -/en-US/docs/Web/Guide/HTML/Editable_content /en-US/docs/Web/HTML/Global_attributes/contenteditable +/en-US/docs/Web/Guide/HTML/Editable_content /en-US/docs/Web/HTML/Reference/Global_attributes/contenteditable /en-US/docs/Web/Guide/HTML/Element /en-US/docs/Learn_web_development/Core/Structuring_content/Basic_HTML_syntax /en-US/docs/Web/Guide/HTML/Email_links /en-US/docs/Learn_web_development/Core/Structuring_content/Creating_links#email_links /en-US/docs/Web/Guide/HTML/Event_attributes /en-US/docs/Learn_web_development/Core/Scripting/Events#Inline_event_handlers_—_don't_use_these @@ -12642,11 +12927,11 @@ /en-US/docs/Web/Guide/HTML/Forms/The_native_form_widgets /en-US/docs/Learn_web_development/Extensions/Forms/Basic_native_form_controls /en-US/docs/Web/Guide/HTML/Forms_in_HTML /en-US/docs/Learn_web_development/Extensions/Forms /en-US/docs/Web/Guide/HTML/HTML5 /en-US/docs/Glossary/HTML5 -/en-US/docs/Web/Guide/HTML/HTML5/Constraint_validation /en-US/docs/Web/HTML/Constraint_validation +/en-US/docs/Web/Guide/HTML/HTML5/Constraint_validation /en-US/docs/Web/HTML/Guides/Constraint_validation /en-US/docs/Web/Guide/HTML/HTML5/Forms_in_HTML5 /en-US/docs/Learn_web_development/Extensions/Forms /en-US/docs/Web/Guide/HTML/HTML5/HTML5_Parser /en-US/docs/Learn_web_development/Core/Structuring_content -/en-US/docs/Web/Guide/HTML/HTML5/HTML5_Tags_List /en-US/docs/Web/HTML/Element -/en-US/docs/Web/Guide/HTML/HTML5/HTML5_element_list /en-US/docs/Web/HTML/Element +/en-US/docs/Web/Guide/HTML/HTML5/HTML5_Tags_List /en-US/docs/Web/HTML/Reference/Elements +/en-US/docs/Web/Guide/HTML/HTML5/HTML5_element_list /en-US/docs/Web/HTML/Reference/Elements /en-US/docs/Web/Guide/HTML/HTML5/Introduction_to_HTML5 /en-US/docs/Learn_web_development/Core/Structuring_content /en-US/docs/Web/Guide/HTML/HTML5/Optimizing_Your_Pages_for_Speculative_Parsing /en-US/docs/Glossary/Speculative_parsing /en-US/docs/Web/Guide/HTML/Hyperlink /en-US/docs/Learn_web_development/Core/Structuring_content/Creating_links @@ -12655,10 +12940,10 @@ /en-US/docs/Web/Guide/HTML/Obsolete_things_to_avoid /en-US/docs/Learn_web_development/Core/Structuring_content /en-US/docs/Web/Guide/HTML/Recommended_Drag_Types /en-US/docs/Web/API/HTML_Drag_and_Drop_API/Recommended_drag_types /en-US/docs/Web/Guide/HTML/The_Importance_of_Correct_HTML_Commenting /en-US/docs/Learn_web_development/Core/Structuring_content/Basic_HTML_syntax#HTML_comments -/en-US/docs/Web/Guide/HTML/Tips_for_authoring_fast-loading_HTML_pages /en-US/docs/Learn_web_development/Howto/Solve_HTML_problems/Author_fast-loading_HTML_pages +/en-US/docs/Web/Guide/HTML/Tips_for_authoring_fast-loading_HTML_pages /en-US/docs/Web/HTML/How_to/Author_fast-loading_HTML_pages /en-US/docs/Web/Guide/HTML/Using_HTML5_audio_and_video /en-US/docs/Learn_web_development/Core/Structuring_content/HTML_video_and_audio -/en-US/docs/Web/Guide/HTML/Using_HTML_sections_and_outlines /en-US/docs/Web/HTML/Element/Heading_Elements -/en-US/docs/Web/Guide/HTML/Using_data_attributes /en-US/docs/Learn_web_development/Howto/Solve_HTML_problems/Use_data_attributes +/en-US/docs/Web/Guide/HTML/Using_HTML_sections_and_outlines /en-US/docs/Web/HTML/Reference/Elements/Heading_Elements +/en-US/docs/Web/Guide/HTML/Using_data_attributes /en-US/docs/Web/HTML/How_to/Use_data_attributes /en-US/docs/Web/Guide/HTML/XHTML /en-US/docs/Glossary/XHTML /en-US/docs/Web/Guide/Houdini /en-US/docs/Web/API/Houdini_APIs /en-US/docs/Web/Guide/Index /en-US/docs/MDN/Guides @@ -12684,44 +12969,235 @@ /en-US/docs/Web/Guide/WOFF /en-US/docs/Web/CSS/CSS_fonts/WOFF /en-US/docs/Web/Guide/Writing_forward-compatible_websites /en-US/docs/Learn_web_development/Core/Scripting/Debugging_JavaScript /en-US/docs/Web/HTML/Applying_color /en-US/docs/Web/CSS/CSS_colors/Applying_color +/en-US/docs/Web/HTML/Attributes /en-US/docs/Web/HTML/Reference/Attributes +/en-US/docs/Web/HTML/Attributes/accept /en-US/docs/Web/HTML/Reference/Attributes/accept +/en-US/docs/Web/HTML/Attributes/autocomplete /en-US/docs/Web/HTML/Reference/Attributes/autocomplete +/en-US/docs/Web/HTML/Attributes/capture /en-US/docs/Web/HTML/Reference/Attributes/capture +/en-US/docs/Web/HTML/Attributes/crossorigin /en-US/docs/Web/HTML/Reference/Attributes/crossorigin +/en-US/docs/Web/HTML/Attributes/dirname /en-US/docs/Web/HTML/Reference/Attributes/dirname +/en-US/docs/Web/HTML/Attributes/disabled /en-US/docs/Web/HTML/Reference/Attributes/disabled +/en-US/docs/Web/HTML/Attributes/elementtiming /en-US/docs/Web/HTML/Reference/Attributes/elementtiming +/en-US/docs/Web/HTML/Attributes/for /en-US/docs/Web/HTML/Reference/Attributes/for +/en-US/docs/Web/HTML/Attributes/max /en-US/docs/Web/HTML/Reference/Attributes/max +/en-US/docs/Web/HTML/Attributes/maxlength /en-US/docs/Web/HTML/Reference/Attributes/maxlength +/en-US/docs/Web/HTML/Attributes/min /en-US/docs/Web/HTML/Reference/Attributes/min +/en-US/docs/Web/HTML/Attributes/minlength /en-US/docs/Web/HTML/Reference/Attributes/minlength +/en-US/docs/Web/HTML/Attributes/multiple /en-US/docs/Web/HTML/Reference/Attributes/multiple +/en-US/docs/Web/HTML/Attributes/pattern /en-US/docs/Web/HTML/Reference/Attributes/pattern +/en-US/docs/Web/HTML/Attributes/placeholder /en-US/docs/Web/HTML/Reference/Attributes/placeholder +/en-US/docs/Web/HTML/Attributes/readonly /en-US/docs/Web/HTML/Reference/Attributes/readonly +/en-US/docs/Web/HTML/Attributes/rel /en-US/docs/Web/HTML/Reference/Attributes/rel +/en-US/docs/Web/HTML/Attributes/rel/alternate_stylesheet /en-US/docs/Web/HTML/Reference/Attributes/rel/alternate_stylesheet +/en-US/docs/Web/HTML/Attributes/rel/compression-dictionary /en-US/docs/Web/HTML/Reference/Attributes/rel/compression-dictionary +/en-US/docs/Web/HTML/Attributes/rel/dns-prefetch /en-US/docs/Web/HTML/Reference/Attributes/rel/dns-prefetch +/en-US/docs/Web/HTML/Attributes/rel/manifest /en-US/docs/Web/HTML/Reference/Attributes/rel/manifest +/en-US/docs/Web/HTML/Attributes/rel/me /en-US/docs/Web/HTML/Reference/Attributes/rel/me +/en-US/docs/Web/HTML/Attributes/rel/modulepreload /en-US/docs/Web/HTML/Reference/Attributes/rel/modulepreload +/en-US/docs/Web/HTML/Attributes/rel/noopener /en-US/docs/Web/HTML/Reference/Attributes/rel/noopener +/en-US/docs/Web/HTML/Attributes/rel/noreferrer /en-US/docs/Web/HTML/Reference/Attributes/rel/noreferrer +/en-US/docs/Web/HTML/Attributes/rel/preconnect /en-US/docs/Web/HTML/Reference/Attributes/rel/preconnect +/en-US/docs/Web/HTML/Attributes/rel/prefetch /en-US/docs/Web/HTML/Reference/Attributes/rel/prefetch +/en-US/docs/Web/HTML/Attributes/rel/preload /en-US/docs/Web/HTML/Reference/Attributes/rel/preload +/en-US/docs/Web/HTML/Attributes/rel/prerender /en-US/docs/Web/HTML/Reference/Attributes/rel/prerender +/en-US/docs/Web/HTML/Attributes/required /en-US/docs/Web/HTML/Reference/Attributes/required +/en-US/docs/Web/HTML/Attributes/size /en-US/docs/Web/HTML/Reference/Attributes/size +/en-US/docs/Web/HTML/Attributes/step /en-US/docs/Web/HTML/Reference/Attributes/step /en-US/docs/Web/HTML/Block-level_elements /en-US/docs/Glossary/Block-level_content -/en-US/docs/Web/HTML/CORS_settings_attributes /en-US/docs/Web/HTML/Attributes/crossorigin +/en-US/docs/Web/HTML/CORS_enabled_image /en-US/docs/Web/HTML/How_to/CORS_enabled_image +/en-US/docs/Web/HTML/CORS_settings_attributes /en-US/docs/Web/HTML/Reference/Attributes/crossorigin /en-US/docs/Web/HTML/Canvas /en-US/docs/Web/API/Canvas_API /en-US/docs/Web/HTML/Canvas/Drawing_graphics_with_canvas /en-US/docs/Web/API/Canvas_API/Tutorial /en-US/docs/Web/HTML/Canvas/Tutorial /en-US/docs/Web/API/Canvas_API/Tutorial /en-US/docs/Web/HTML/Canvas/Tutorial/Basic_animations /en-US/docs/Web/API/Canvas_API/Tutorial/Basic_animations -/en-US/docs/Web/HTML/Content_Editable /en-US/docs/Web/HTML/Global_attributes/contenteditable -/en-US/docs/Web/HTML/Controlling_spell_checking_in_HTML_forms /en-US/docs/Web/HTML/Global_attributes/spellcheck -/en-US/docs/Web/HTML/Controlling_spell_checking_in_HTML_formsControlling_spell_checking_in_HTML_forms /en-US/docs/Web/HTML/Global_attributes/spellcheck -/en-US/docs/Web/HTML/DASH_Adaptive_Streaming_for_HTML_5_Video /en-US/docs/Web/Media/Guides/DASH_Adaptive_Streaming_for_HTML_5_Video -/en-US/docs/Web/HTML/Element/:_The_Ruby_Base_element /en-US/docs/Web/HTML/Element/rb -/en-US/docs/Web/HTML/Element/Input/ /en-US/docs/Web/HTML/Element/input/checkbox -/en-US/docs/Web/HTML/Element/Input/ /en-US/docs/Web/HTML/Element/input/color -/en-US/docs/Web/HTML/Element/Input/ /en-US/docs/Web/HTML/Element/input/datetime-local -/en-US/docs/Web/HTML/Element/Input/ /en-US/docs/Web/HTML/Element/input/image -/en-US/docs/Web/HTML/Element/Input/datetime /en-US/docs/Web/HTML/Element/input/datetime-local -/en-US/docs/Web/HTML/Element/The__element /en-US/docs/Web/HTML/Element/noembed +/en-US/docs/Web/HTML/Comments /en-US/docs/Web/HTML/Guides/Comments +/en-US/docs/Web/HTML/Constraint_validation /en-US/docs/Web/HTML/Guides/Constraint_validation +/en-US/docs/Web/HTML/Content_Editable /en-US/docs/Web/HTML/Reference/Global_attributes/contenteditable +/en-US/docs/Web/HTML/Content_categories /en-US/docs/Web/HTML/Guides/Content_categories +/en-US/docs/Web/HTML/Controlling_spell_checking_in_HTML_forms /en-US/docs/Web/HTML/Reference/Global_attributes/spellcheck +/en-US/docs/Web/HTML/Controlling_spell_checking_in_HTML_formsControlling_spell_checking_in_HTML_forms /en-US/docs/Web/HTML/Reference/Global_attributes/spellcheck +/en-US/docs/Web/HTML/DASH_Adaptive_Streaming_for_HTML_5_Video /en-US/docs/Web/API/Media_Source_Extensions_API/DASH_Adaptive_Streaming +/en-US/docs/Web/HTML/Date_and_time_formats /en-US/docs/Web/HTML/Guides/Date_and_time_formats +/en-US/docs/Web/HTML/Element /en-US/docs/Web/HTML/Reference/Elements +/en-US/docs/Web/HTML/Element/<rb>:_The_Ruby_Base_element /en-US/docs/Web/HTML/Reference/Elements/rb +/en-US/docs/Web/HTML/Element/Heading_Elements /en-US/docs/Web/HTML/Reference/Elements/Heading_Elements +/en-US/docs/Web/HTML/Element/Input/<input_type=_checkbox_> /en-US/docs/Web/HTML/Reference/Elements/input/checkbox +/en-US/docs/Web/HTML/Element/Input/<input_type=_color_> /en-US/docs/Web/HTML/Reference/Elements/input/color +/en-US/docs/Web/HTML/Element/Input/<input_type=_datetime_> /en-US/docs/Web/HTML/Reference/Elements/input/datetime-local +/en-US/docs/Web/HTML/Element/Input/<input_type=_image_> /en-US/docs/Web/HTML/Reference/Elements/input/image +/en-US/docs/Web/HTML/Element/Input/datetime /en-US/docs/Web/HTML/Reference/Elements/input/datetime-local +/en-US/docs/Web/HTML/Element/The_<noembed>_element /en-US/docs/Web/HTML/Reference/Elements/noembed /en-US/docs/Web/HTML/Element/Video/emptied_event /en-US/docs/Web/API/HTMLMediaElement/emptied_event /en-US/docs/Web/HTML/Element/Video/ended_event /en-US/docs/Web/API/HTMLMediaElement/ended_event /en-US/docs/Web/HTML/Element/Video/loadeddata_event /en-US/docs/Web/API/HTMLMediaElement/loadeddata_event +/en-US/docs/Web/HTML/Element/a /en-US/docs/Web/HTML/Reference/Elements/a +/en-US/docs/Web/HTML/Element/abbr /en-US/docs/Web/HTML/Reference/Elements/abbr +/en-US/docs/Web/HTML/Element/acronym /en-US/docs/Web/HTML/Reference/Elements/acronym +/en-US/docs/Web/HTML/Element/address /en-US/docs/Web/HTML/Reference/Elements/address +/en-US/docs/Web/HTML/Element/area /en-US/docs/Web/HTML/Reference/Elements/area +/en-US/docs/Web/HTML/Element/article /en-US/docs/Web/HTML/Reference/Elements/article +/en-US/docs/Web/HTML/Element/aside /en-US/docs/Web/HTML/Reference/Elements/aside +/en-US/docs/Web/HTML/Element/audio /en-US/docs/Web/HTML/Reference/Elements/audio /en-US/docs/Web/HTML/Element/audio/playing_event /en-US/docs/Web/API/HTMLMediaElement/playing_event +/en-US/docs/Web/HTML/Element/b /en-US/docs/Web/HTML/Reference/Elements/b +/en-US/docs/Web/HTML/Element/base /en-US/docs/Web/HTML/Reference/Elements/base /en-US/docs/Web/HTML/Element/basefont /en-US/docs/Web/CSS/CSS_fonts -/en-US/docs/Web/HTML/Element/bgsound /en-US/docs/Web/HTML/Element/audio -/en-US/docs/Web/HTML/Element/h1 /en-US/docs/Web/HTML/Element/Heading_Elements -/en-US/docs/Web/HTML/Element/h1–h6 /en-US/docs/Web/HTML/Element/Heading_Elements -/en-US/docs/Web/HTML/Element/h2 /en-US/docs/Web/HTML/Element/Heading_Elements -/en-US/docs/Web/HTML/Element/h3 /en-US/docs/Web/HTML/Element/Heading_Elements -/en-US/docs/Web/HTML/Element/h4 /en-US/docs/Web/HTML/Element/Heading_Elements -/en-US/docs/Web/HTML/Element/h5 /en-US/docs/Web/HTML/Element/Heading_Elements -/en-US/docs/Web/HTML/Element/h6 /en-US/docs/Web/HTML/Element/Heading_Elements +/en-US/docs/Web/HTML/Element/bdi /en-US/docs/Web/HTML/Reference/Elements/bdi +/en-US/docs/Web/HTML/Element/bdo /en-US/docs/Web/HTML/Reference/Elements/bdo +/en-US/docs/Web/HTML/Element/bgsound /en-US/docs/Web/HTML/Reference/Elements/audio +/en-US/docs/Web/HTML/Element/big /en-US/docs/Web/HTML/Reference/Elements/big +/en-US/docs/Web/HTML/Element/blockquote /en-US/docs/Web/HTML/Reference/Elements/blockquote +/en-US/docs/Web/HTML/Element/body /en-US/docs/Web/HTML/Reference/Elements/body +/en-US/docs/Web/HTML/Element/br /en-US/docs/Web/HTML/Reference/Elements/br +/en-US/docs/Web/HTML/Element/button /en-US/docs/Web/HTML/Reference/Elements/button +/en-US/docs/Web/HTML/Element/canvas /en-US/docs/Web/HTML/Reference/Elements/canvas +/en-US/docs/Web/HTML/Element/caption /en-US/docs/Web/HTML/Reference/Elements/caption +/en-US/docs/Web/HTML/Element/center /en-US/docs/Web/HTML/Reference/Elements/center +/en-US/docs/Web/HTML/Element/cite /en-US/docs/Web/HTML/Reference/Elements/cite +/en-US/docs/Web/HTML/Element/code /en-US/docs/Web/HTML/Reference/Elements/code +/en-US/docs/Web/HTML/Element/col /en-US/docs/Web/HTML/Reference/Elements/col +/en-US/docs/Web/HTML/Element/colgroup /en-US/docs/Web/HTML/Reference/Elements/colgroup +/en-US/docs/Web/HTML/Element/data /en-US/docs/Web/HTML/Reference/Elements/data +/en-US/docs/Web/HTML/Element/datalist /en-US/docs/Web/HTML/Reference/Elements/datalist +/en-US/docs/Web/HTML/Element/dd /en-US/docs/Web/HTML/Reference/Elements/dd +/en-US/docs/Web/HTML/Element/del /en-US/docs/Web/HTML/Reference/Elements/del +/en-US/docs/Web/HTML/Element/details /en-US/docs/Web/HTML/Reference/Elements/details +/en-US/docs/Web/HTML/Element/dfn /en-US/docs/Web/HTML/Reference/Elements/dfn +/en-US/docs/Web/HTML/Element/dialog /en-US/docs/Web/HTML/Reference/Elements/dialog +/en-US/docs/Web/HTML/Element/dir /en-US/docs/Web/HTML/Reference/Elements/dir +/en-US/docs/Web/HTML/Element/div /en-US/docs/Web/HTML/Reference/Elements/div +/en-US/docs/Web/HTML/Element/dl /en-US/docs/Web/HTML/Reference/Elements/dl +/en-US/docs/Web/HTML/Element/dt /en-US/docs/Web/HTML/Reference/Elements/dt +/en-US/docs/Web/HTML/Element/em /en-US/docs/Web/HTML/Reference/Elements/em +/en-US/docs/Web/HTML/Element/embed /en-US/docs/Web/HTML/Reference/Elements/embed +/en-US/docs/Web/HTML/Element/fencedframe /en-US/docs/Web/HTML/Reference/Elements/fencedframe +/en-US/docs/Web/HTML/Element/fieldset /en-US/docs/Web/HTML/Reference/Elements/fieldset +/en-US/docs/Web/HTML/Element/figcaption /en-US/docs/Web/HTML/Reference/Elements/figcaption +/en-US/docs/Web/HTML/Element/figure /en-US/docs/Web/HTML/Reference/Elements/figure +/en-US/docs/Web/HTML/Element/font /en-US/docs/Web/HTML/Reference/Elements/font +/en-US/docs/Web/HTML/Element/footer /en-US/docs/Web/HTML/Reference/Elements/footer +/en-US/docs/Web/HTML/Element/form /en-US/docs/Web/HTML/Reference/Elements/form +/en-US/docs/Web/HTML/Element/frame /en-US/docs/Web/HTML/Reference/Elements/frame +/en-US/docs/Web/HTML/Element/frameset /en-US/docs/Web/HTML/Reference/Elements/frameset +/en-US/docs/Web/HTML/Element/h1 /en-US/docs/Web/HTML/Reference/Elements/Heading_Elements +/en-US/docs/Web/HTML/Element/h1–h6 /en-US/docs/Web/HTML/Reference/Elements/Heading_Elements +/en-US/docs/Web/HTML/Element/h2 /en-US/docs/Web/HTML/Reference/Elements/Heading_Elements +/en-US/docs/Web/HTML/Element/h3 /en-US/docs/Web/HTML/Reference/Elements/Heading_Elements +/en-US/docs/Web/HTML/Element/h4 /en-US/docs/Web/HTML/Reference/Elements/Heading_Elements +/en-US/docs/Web/HTML/Element/h5 /en-US/docs/Web/HTML/Reference/Elements/Heading_Elements +/en-US/docs/Web/HTML/Element/h6 /en-US/docs/Web/HTML/Reference/Elements/Heading_Elements +/en-US/docs/Web/HTML/Element/head /en-US/docs/Web/HTML/Reference/Elements/head +/en-US/docs/Web/HTML/Element/header /en-US/docs/Web/HTML/Reference/Elements/header +/en-US/docs/Web/HTML/Element/hgroup /en-US/docs/Web/HTML/Reference/Elements/hgroup +/en-US/docs/Web/HTML/Element/hr /en-US/docs/Web/HTML/Reference/Elements/hr +/en-US/docs/Web/HTML/Element/html /en-US/docs/Web/HTML/Reference/Elements/html /en-US/docs/Web/HTML/Element/html/manifest /en-US/docs/Web/Progressive_web_apps/Manifest -/en-US/docs/Web/HTML/Element/image /en-US/docs/Web/HTML/Element/img -/en-US/docs/Web/HTML/Element/input/<input_type=_col_> /en-US/docs/Web/HTML/Element/col -/en-US/docs/Web/HTML/Element/input/<input_type=_colgroup_> /en-US/docs/Web/HTML/Element/colgroup -/en-US/docs/Web/HTML/Element/input/Date_and_time_formats /en-US/docs/Web/HTML/Date_and_time_formats -/en-US/docs/Web/HTML/Element/math /en-US/docs/Web/MathML/Element/math -/en-US/docs/Web/HTML/Element/menuitem /en-US/docs/Web/HTML/Element -/en-US/docs/Web/HTML/Element/s_ource /en-US/docs/Web/HTML/Element/source +/en-US/docs/Web/HTML/Element/i /en-US/docs/Web/HTML/Reference/Elements/i +/en-US/docs/Web/HTML/Element/iframe /en-US/docs/Web/HTML/Reference/Elements/iframe +/en-US/docs/Web/HTML/Element/image /en-US/docs/Web/HTML/Reference/Elements/img +/en-US/docs/Web/HTML/Element/img /en-US/docs/Web/HTML/Reference/Elements/img +/en-US/docs/Web/HTML/Element/input /en-US/docs/Web/HTML/Reference/Elements/input +/en-US/docs/Web/HTML/Element/input/<input_type=_col_> /en-US/docs/Web/HTML/Reference/Elements/col +/en-US/docs/Web/HTML/Element/input/<input_type=_colgroup_> /en-US/docs/Web/HTML/Reference/Elements/colgroup +/en-US/docs/Web/HTML/Element/input/Date_and_time_formats /en-US/docs/Web/HTML/Guides/Date_and_time_formats +/en-US/docs/Web/HTML/Element/input/button /en-US/docs/Web/HTML/Reference/Elements/input/button +/en-US/docs/Web/HTML/Element/input/checkbox /en-US/docs/Web/HTML/Reference/Elements/input/checkbox +/en-US/docs/Web/HTML/Element/input/color /en-US/docs/Web/HTML/Reference/Elements/input/color +/en-US/docs/Web/HTML/Element/input/date /en-US/docs/Web/HTML/Reference/Elements/input/date +/en-US/docs/Web/HTML/Element/input/datetime-local /en-US/docs/Web/HTML/Reference/Elements/input/datetime-local +/en-US/docs/Web/HTML/Element/input/email /en-US/docs/Web/HTML/Reference/Elements/input/email +/en-US/docs/Web/HTML/Element/input/file /en-US/docs/Web/HTML/Reference/Elements/input/file +/en-US/docs/Web/HTML/Element/input/hidden /en-US/docs/Web/HTML/Reference/Elements/input/hidden +/en-US/docs/Web/HTML/Element/input/image /en-US/docs/Web/HTML/Reference/Elements/input/image +/en-US/docs/Web/HTML/Element/input/month /en-US/docs/Web/HTML/Reference/Elements/input/month +/en-US/docs/Web/HTML/Element/input/number /en-US/docs/Web/HTML/Reference/Elements/input/number +/en-US/docs/Web/HTML/Element/input/password /en-US/docs/Web/HTML/Reference/Elements/input/password +/en-US/docs/Web/HTML/Element/input/radio /en-US/docs/Web/HTML/Reference/Elements/input/radio +/en-US/docs/Web/HTML/Element/input/range /en-US/docs/Web/HTML/Reference/Elements/input/range +/en-US/docs/Web/HTML/Element/input/reset /en-US/docs/Web/HTML/Reference/Elements/input/reset +/en-US/docs/Web/HTML/Element/input/search /en-US/docs/Web/HTML/Reference/Elements/input/search +/en-US/docs/Web/HTML/Element/input/submit /en-US/docs/Web/HTML/Reference/Elements/input/submit +/en-US/docs/Web/HTML/Element/input/tel /en-US/docs/Web/HTML/Reference/Elements/input/tel +/en-US/docs/Web/HTML/Element/input/text /en-US/docs/Web/HTML/Reference/Elements/input/text +/en-US/docs/Web/HTML/Element/input/time /en-US/docs/Web/HTML/Reference/Elements/input/time +/en-US/docs/Web/HTML/Element/input/url /en-US/docs/Web/HTML/Reference/Elements/input/url +/en-US/docs/Web/HTML/Element/input/week /en-US/docs/Web/HTML/Reference/Elements/input/week +/en-US/docs/Web/HTML/Element/ins /en-US/docs/Web/HTML/Reference/Elements/ins +/en-US/docs/Web/HTML/Element/kbd /en-US/docs/Web/HTML/Reference/Elements/kbd +/en-US/docs/Web/HTML/Element/label /en-US/docs/Web/HTML/Reference/Elements/label +/en-US/docs/Web/HTML/Element/legend /en-US/docs/Web/HTML/Reference/Elements/legend +/en-US/docs/Web/HTML/Element/li /en-US/docs/Web/HTML/Reference/Elements/li +/en-US/docs/Web/HTML/Element/link /en-US/docs/Web/HTML/Reference/Elements/link +/en-US/docs/Web/HTML/Element/main /en-US/docs/Web/HTML/Reference/Elements/main +/en-US/docs/Web/HTML/Element/map /en-US/docs/Web/HTML/Reference/Elements/map +/en-US/docs/Web/HTML/Element/mark /en-US/docs/Web/HTML/Reference/Elements/mark +/en-US/docs/Web/HTML/Element/marquee /en-US/docs/Web/HTML/Reference/Elements/marquee +/en-US/docs/Web/HTML/Element/math /en-US/docs/Web/MathML/Reference/Element/math +/en-US/docs/Web/HTML/Element/menu /en-US/docs/Web/HTML/Reference/Elements/menu +/en-US/docs/Web/HTML/Element/menuitem /en-US/docs/Web/HTML/Reference/Elements +/en-US/docs/Web/HTML/Element/meta /en-US/docs/Web/HTML/Reference/Elements/meta +/en-US/docs/Web/HTML/Element/meta/name /en-US/docs/Web/HTML/Reference/Elements/meta/name +/en-US/docs/Web/HTML/Element/meta/name/theme-color /en-US/docs/Web/HTML/Reference/Elements/meta/name/theme-color +/en-US/docs/Web/HTML/Element/meter /en-US/docs/Web/HTML/Reference/Elements/meter +/en-US/docs/Web/HTML/Element/nav /en-US/docs/Web/HTML/Reference/Elements/nav +/en-US/docs/Web/HTML/Element/nobr /en-US/docs/Web/HTML/Reference/Elements/nobr +/en-US/docs/Web/HTML/Element/noembed /en-US/docs/Web/HTML/Reference/Elements/noembed +/en-US/docs/Web/HTML/Element/noframes /en-US/docs/Web/HTML/Reference/Elements/noframes +/en-US/docs/Web/HTML/Element/noscript /en-US/docs/Web/HTML/Reference/Elements/noscript +/en-US/docs/Web/HTML/Element/object /en-US/docs/Web/HTML/Reference/Elements/object +/en-US/docs/Web/HTML/Element/ol /en-US/docs/Web/HTML/Reference/Elements/ol +/en-US/docs/Web/HTML/Element/optgroup /en-US/docs/Web/HTML/Reference/Elements/optgroup +/en-US/docs/Web/HTML/Element/option /en-US/docs/Web/HTML/Reference/Elements/option +/en-US/docs/Web/HTML/Element/output /en-US/docs/Web/HTML/Reference/Elements/output +/en-US/docs/Web/HTML/Element/p /en-US/docs/Web/HTML/Reference/Elements/p +/en-US/docs/Web/HTML/Element/param /en-US/docs/Web/HTML/Reference/Elements/param +/en-US/docs/Web/HTML/Element/picture /en-US/docs/Web/HTML/Reference/Elements/picture +/en-US/docs/Web/HTML/Element/plaintext /en-US/docs/Web/HTML/Reference/Elements/plaintext +/en-US/docs/Web/HTML/Element/pre /en-US/docs/Web/HTML/Reference/Elements/pre +/en-US/docs/Web/HTML/Element/progress /en-US/docs/Web/HTML/Reference/Elements/progress +/en-US/docs/Web/HTML/Element/q /en-US/docs/Web/HTML/Reference/Elements/q +/en-US/docs/Web/HTML/Element/rb /en-US/docs/Web/HTML/Reference/Elements/rb +/en-US/docs/Web/HTML/Element/rp /en-US/docs/Web/HTML/Reference/Elements/rp +/en-US/docs/Web/HTML/Element/rt /en-US/docs/Web/HTML/Reference/Elements/rt +/en-US/docs/Web/HTML/Element/rtc /en-US/docs/Web/HTML/Reference/Elements/rtc +/en-US/docs/Web/HTML/Element/ruby /en-US/docs/Web/HTML/Reference/Elements/ruby +/en-US/docs/Web/HTML/Element/s /en-US/docs/Web/HTML/Reference/Elements/s +/en-US/docs/Web/HTML/Element/s_ource /en-US/docs/Web/HTML/Reference/Elements/source +/en-US/docs/Web/HTML/Element/samp /en-US/docs/Web/HTML/Reference/Elements/samp +/en-US/docs/Web/HTML/Element/script /en-US/docs/Web/HTML/Reference/Elements/script +/en-US/docs/Web/HTML/Element/script/type /en-US/docs/Web/HTML/Reference/Elements/script/type +/en-US/docs/Web/HTML/Element/script/type/importmap /en-US/docs/Web/HTML/Reference/Elements/script/type/importmap +/en-US/docs/Web/HTML/Element/script/type/speculationrules /en-US/docs/Web/HTML/Reference/Elements/script/type/speculationrules +/en-US/docs/Web/HTML/Element/search /en-US/docs/Web/HTML/Reference/Elements/search +/en-US/docs/Web/HTML/Element/section /en-US/docs/Web/HTML/Reference/Elements/section +/en-US/docs/Web/HTML/Element/select /en-US/docs/Web/HTML/Reference/Elements/select +/en-US/docs/Web/HTML/Element/selectedcontent /en-US/docs/Web/HTML/Reference/Elements/selectedcontent +/en-US/docs/Web/HTML/Element/slot /en-US/docs/Web/HTML/Reference/Elements/slot +/en-US/docs/Web/HTML/Element/small /en-US/docs/Web/HTML/Reference/Elements/small +/en-US/docs/Web/HTML/Element/source /en-US/docs/Web/HTML/Reference/Elements/source +/en-US/docs/Web/HTML/Element/span /en-US/docs/Web/HTML/Reference/Elements/span +/en-US/docs/Web/HTML/Element/strike /en-US/docs/Web/HTML/Reference/Elements/strike +/en-US/docs/Web/HTML/Element/strong /en-US/docs/Web/HTML/Reference/Elements/strong +/en-US/docs/Web/HTML/Element/style /en-US/docs/Web/HTML/Reference/Elements/style +/en-US/docs/Web/HTML/Element/sub /en-US/docs/Web/HTML/Reference/Elements/sub +/en-US/docs/Web/HTML/Element/summary /en-US/docs/Web/HTML/Reference/Elements/summary +/en-US/docs/Web/HTML/Element/sup /en-US/docs/Web/HTML/Reference/Elements/sup +/en-US/docs/Web/HTML/Element/table /en-US/docs/Web/HTML/Reference/Elements/table +/en-US/docs/Web/HTML/Element/tbody /en-US/docs/Web/HTML/Reference/Elements/tbody +/en-US/docs/Web/HTML/Element/td /en-US/docs/Web/HTML/Reference/Elements/td +/en-US/docs/Web/HTML/Element/template /en-US/docs/Web/HTML/Reference/Elements/template +/en-US/docs/Web/HTML/Element/textarea /en-US/docs/Web/HTML/Reference/Elements/textarea +/en-US/docs/Web/HTML/Element/tfoot /en-US/docs/Web/HTML/Reference/Elements/tfoot +/en-US/docs/Web/HTML/Element/th /en-US/docs/Web/HTML/Reference/Elements/th +/en-US/docs/Web/HTML/Element/thead /en-US/docs/Web/HTML/Reference/Elements/thead +/en-US/docs/Web/HTML/Element/time /en-US/docs/Web/HTML/Reference/Elements/time +/en-US/docs/Web/HTML/Element/title /en-US/docs/Web/HTML/Reference/Elements/title +/en-US/docs/Web/HTML/Element/tr /en-US/docs/Web/HTML/Reference/Elements/tr +/en-US/docs/Web/HTML/Element/track /en-US/docs/Web/HTML/Reference/Elements/track +/en-US/docs/Web/HTML/Element/tt /en-US/docs/Web/HTML/Reference/Elements/tt +/en-US/docs/Web/HTML/Element/u /en-US/docs/Web/HTML/Reference/Elements/u +/en-US/docs/Web/HTML/Element/ul /en-US/docs/Web/HTML/Reference/Elements/ul +/en-US/docs/Web/HTML/Element/var /en-US/docs/Web/HTML/Reference/Elements/var +/en-US/docs/Web/HTML/Element/video /en-US/docs/Web/HTML/Reference/Elements/video /en-US/docs/Web/HTML/Element/video/canplay_event /en-US/docs/Web/API/HTMLMediaElement/canplay_event /en-US/docs/Web/HTML/Element/video/durationchange_event /en-US/docs/Web/API/HTMLMediaElement/durationchange_event /en-US/docs/Web/HTML/Element/video/pause_event /en-US/docs/Web/API/HTMLMediaElement/pause_event @@ -12734,126 +13210,501 @@ /en-US/docs/Web/HTML/Element/video/suspend_event /en-US/docs/Web/API/HTMLMediaElement/suspend_event /en-US/docs/Web/HTML/Element/video/timeupdate_event /en-US/docs/Web/API/HTMLMediaElement/timeupdate_event /en-US/docs/Web/HTML/Element/video/volumechange_event /en-US/docs/Web/API/HTMLMediaElement/volumechange_event +/en-US/docs/Web/HTML/Element/wbr /en-US/docs/Web/HTML/Reference/Elements/wbr /en-US/docs/Web/HTML/Element/webkit-meter-even-less-good-value /en-US/docs/Web/CSS/::-webkit-meter-even-less-good-value /en-US/docs/Web/HTML/Element/webkit-meter-optimum-value /en-US/docs/Web/CSS/::-webkit-meter-optimum-value -/en-US/docs/Web/HTML/Elements/textarea /en-US/docs/Web/HTML/Element/textarea +/en-US/docs/Web/HTML/Element/xmp /en-US/docs/Web/HTML/Reference/Elements/xmp +/en-US/docs/Web/HTML/Elements/textarea /en-US/docs/Web/HTML/Reference/Elements/textarea /en-US/docs/Web/HTML/Focus_management_in_HTML /en-US/docs/Web/API/Document/hasFocus /en-US/docs/Web/HTML/Forms_in_HTML /en-US/docs/Learn_web_development/Extensions/Forms -/en-US/docs/Web/HTML/Global_attributes/contextmenu /en-US/docs/Web/HTML/Element/menu +/en-US/docs/Web/HTML/Global_attributes /en-US/docs/Web/HTML/Reference/Global_attributes +/en-US/docs/Web/HTML/Global_attributes/accesskey /en-US/docs/Web/HTML/Reference/Global_attributes/accesskey +/en-US/docs/Web/HTML/Global_attributes/anchor /en-US/docs/Web/HTML/Reference/Global_attributes/anchor +/en-US/docs/Web/HTML/Global_attributes/autocapitalize /en-US/docs/Web/HTML/Reference/Global_attributes/autocapitalize +/en-US/docs/Web/HTML/Global_attributes/autocorrect /en-US/docs/Web/HTML/Reference/Global_attributes/autocorrect +/en-US/docs/Web/HTML/Global_attributes/autofocus /en-US/docs/Web/HTML/Reference/Global_attributes/autofocus +/en-US/docs/Web/HTML/Global_attributes/class /en-US/docs/Web/HTML/Reference/Global_attributes/class +/en-US/docs/Web/HTML/Global_attributes/contenteditable /en-US/docs/Web/HTML/Reference/Global_attributes/contenteditable +/en-US/docs/Web/HTML/Global_attributes/contextmenu /en-US/docs/Web/HTML/Reference/Elements/menu +/en-US/docs/Web/HTML/Global_attributes/data-* /en-US/docs/Web/HTML/Reference/Global_attributes/data-* +/en-US/docs/Web/HTML/Global_attributes/dir /en-US/docs/Web/HTML/Reference/Global_attributes/dir +/en-US/docs/Web/HTML/Global_attributes/draggable /en-US/docs/Web/HTML/Reference/Global_attributes/draggable +/en-US/docs/Web/HTML/Global_attributes/enterkeyhint /en-US/docs/Web/HTML/Reference/Global_attributes/enterkeyhint +/en-US/docs/Web/HTML/Global_attributes/exportparts /en-US/docs/Web/HTML/Reference/Global_attributes/exportparts +/en-US/docs/Web/HTML/Global_attributes/hidden /en-US/docs/Web/HTML/Reference/Global_attributes/hidden +/en-US/docs/Web/HTML/Global_attributes/id /en-US/docs/Web/HTML/Reference/Global_attributes/id +/en-US/docs/Web/HTML/Global_attributes/inert /en-US/docs/Web/HTML/Reference/Global_attributes/inert +/en-US/docs/Web/HTML/Global_attributes/inputmode /en-US/docs/Web/HTML/Reference/Global_attributes/inputmode +/en-US/docs/Web/HTML/Global_attributes/is /en-US/docs/Web/HTML/Reference/Global_attributes/is +/en-US/docs/Web/HTML/Global_attributes/itemid /en-US/docs/Web/HTML/Reference/Global_attributes/itemid +/en-US/docs/Web/HTML/Global_attributes/itemprop /en-US/docs/Web/HTML/Reference/Global_attributes/itemprop +/en-US/docs/Web/HTML/Global_attributes/itemref /en-US/docs/Web/HTML/Reference/Global_attributes/itemref +/en-US/docs/Web/HTML/Global_attributes/itemscope /en-US/docs/Web/HTML/Reference/Global_attributes/itemscope +/en-US/docs/Web/HTML/Global_attributes/itemtype /en-US/docs/Web/HTML/Reference/Global_attributes/itemtype +/en-US/docs/Web/HTML/Global_attributes/lang /en-US/docs/Web/HTML/Reference/Global_attributes/lang +/en-US/docs/Web/HTML/Global_attributes/nonce /en-US/docs/Web/HTML/Reference/Global_attributes/nonce +/en-US/docs/Web/HTML/Global_attributes/part /en-US/docs/Web/HTML/Reference/Global_attributes/part +/en-US/docs/Web/HTML/Global_attributes/popover /en-US/docs/Web/HTML/Reference/Global_attributes/popover +/en-US/docs/Web/HTML/Global_attributes/slot /en-US/docs/Web/HTML/Reference/Global_attributes/slot +/en-US/docs/Web/HTML/Global_attributes/spellcheck /en-US/docs/Web/HTML/Reference/Global_attributes/spellcheck +/en-US/docs/Web/HTML/Global_attributes/style /en-US/docs/Web/HTML/Reference/Global_attributes/style +/en-US/docs/Web/HTML/Global_attributes/tabindex /en-US/docs/Web/HTML/Reference/Global_attributes/tabindex +/en-US/docs/Web/HTML/Global_attributes/title /en-US/docs/Web/HTML/Reference/Global_attributes/title +/en-US/docs/Web/HTML/Global_attributes/translate /en-US/docs/Web/HTML/Reference/Global_attributes/translate +/en-US/docs/Web/HTML/Global_attributes/virtualkeyboardpolicy /en-US/docs/Web/HTML/Reference/Global_attributes/virtualkeyboardpolicy +/en-US/docs/Web/HTML/Global_attributes/writingsuggestions /en-US/docs/Web/HTML/Reference/Global_attributes/writingsuggestions /en-US/docs/Web/HTML/Index /en-US/docs/Web/HTML /en-US/docs/Web/HTML/Inline_elemente /en-US/docs/Glossary/Inline-level_content /en-US/docs/Web/HTML/Inline_elements /en-US/docs/Glossary/Inline-level_content /en-US/docs/Web/HTML/Inline_elmements /en-US/docs/Glossary/Inline-level_content /en-US/docs/Web/HTML/Introduction /en-US/docs/Learn_web_development/Core/Structuring_content -/en-US/docs/Web/HTML/Kinds_of_HTML_content /en-US/docs/Web/HTML/Content_categories -/en-US/docs/Web/HTML/Link_types /en-US/docs/Web/HTML/Attributes/rel -/en-US/docs/Web/HTML/Link_types/Link_types:_noopener /en-US/docs/Web/HTML/Attributes/rel/noopener -/en-US/docs/Web/HTML/Link_types/dns-prefetch /en-US/docs/Web/HTML/Attributes/rel/dns-prefetch -/en-US/docs/Web/HTML/Link_types/manifest /en-US/docs/Web/HTML/Attributes/rel/manifest -/en-US/docs/Web/HTML/Link_types/me /en-US/docs/Web/HTML/Attributes/rel/me -/en-US/docs/Web/HTML/Link_types/modulepreload /en-US/docs/Web/HTML/Attributes/rel/modulepreload -/en-US/docs/Web/HTML/Link_types/noopener /en-US/docs/Web/HTML/Attributes/rel/noopener -/en-US/docs/Web/HTML/Link_types/noreferrer /en-US/docs/Web/HTML/Attributes/rel/noreferrer -/en-US/docs/Web/HTML/Link_types/preconnect /en-US/docs/Web/HTML/Attributes/rel/preconnect -/en-US/docs/Web/HTML/Link_types/prefetch /en-US/docs/Web/HTML/Attributes/rel/prefetch -/en-US/docs/Web/HTML/Link_types/preload /en-US/docs/Web/HTML/Attributes/rel/preload -/en-US/docs/Web/HTML/Link_types/prerender /en-US/docs/Web/HTML/Attributes/rel/prerender +/en-US/docs/Web/HTML/Kinds_of_HTML_content /en-US/docs/Web/HTML/Guides/Content_categories +/en-US/docs/Web/HTML/Link_types /en-US/docs/Web/HTML/Reference/Attributes/rel +/en-US/docs/Web/HTML/Link_types/Link_types:_noopener /en-US/docs/Web/HTML/Reference/Attributes/rel/noopener +/en-US/docs/Web/HTML/Link_types/dns-prefetch /en-US/docs/Web/HTML/Reference/Attributes/rel/dns-prefetch +/en-US/docs/Web/HTML/Link_types/manifest /en-US/docs/Web/HTML/Reference/Attributes/rel/manifest +/en-US/docs/Web/HTML/Link_types/me /en-US/docs/Web/HTML/Reference/Attributes/rel/me +/en-US/docs/Web/HTML/Link_types/modulepreload /en-US/docs/Web/HTML/Reference/Attributes/rel/modulepreload +/en-US/docs/Web/HTML/Link_types/noopener /en-US/docs/Web/HTML/Reference/Attributes/rel/noopener +/en-US/docs/Web/HTML/Link_types/noreferrer /en-US/docs/Web/HTML/Reference/Attributes/rel/noreferrer +/en-US/docs/Web/HTML/Link_types/preconnect /en-US/docs/Web/HTML/Reference/Attributes/rel/preconnect +/en-US/docs/Web/HTML/Link_types/prefetch /en-US/docs/Web/HTML/Reference/Attributes/rel/prefetch +/en-US/docs/Web/HTML/Link_types/preload /en-US/docs/Web/HTML/Reference/Attributes/rel/preload +/en-US/docs/Web/HTML/Link_types/prerender /en-US/docs/Web/HTML/Reference/Attributes/rel/prerender /en-US/docs/Web/HTML/Manipulating_video_using_canvas /en-US/docs/Web/API/Canvas_API/Manipulating_video_using_canvas +/en-US/docs/Web/HTML/Microdata /en-US/docs/Web/HTML/Guides/Microdata /en-US/docs/Web/HTML/Optimizing_your_pages_for_speculative_parsing /en-US/docs/Glossary/Speculative_parsing -/en-US/docs/Web/HTML/Preloading_content /en-US/docs/Web/HTML/Attributes/rel/preload +/en-US/docs/Web/HTML/Preloading_content /en-US/docs/Web/HTML/Reference/Attributes/rel/preload +/en-US/docs/Web/HTML/Quirks_Mode_and_Standards_Mode /en-US/docs/Web/HTML/Guides/Quirks_mode_and_standards_mode +/en-US/docs/Web/HTML/Responsive_images /en-US/docs/Web/HTML/Guides/Responsive_images /en-US/docs/Web/HTML/Supported_media_formats /en-US/docs/Web/Media/Guides/Formats /en-US/docs/Web/HTML/The_Importance_of_Correct_HTML_Commenting /en-US/docs/Learn_web_development/Core/Structuring_content/Basic_HTML_syntax#HTML_comments /en-US/docs/Web/HTML/Using_HTML5_audio_and_video /en-US/docs/Learn_web_development/Core/Structuring_content/HTML_video_and_audio -/en-US/docs/Web/HTML/element/content /en-US/docs/Web/HTML/Element/slot -/en-US/docs/Web/HTTP/Access_control_CORS /en-US/docs/Web/HTTP/CORS -/en-US/docs/Web/HTTP/Basic_access_authentication /en-US/docs/Web/HTTP/Authentication +/en-US/docs/Web/HTML/Viewport_meta_tag /en-US/docs/Web/HTML/Guides/Viewport_meta_element +/en-US/docs/Web/HTML/element/content /en-US/docs/Web/HTML/Reference/Elements/slot +/en-US/docs/Web/HTML/microformats /en-US/docs/Web/HTML/Guides/Microformats +/en-US/docs/Web/HTTP/Access_control_CORS /en-US/docs/Web/HTTP/Guides/CORS +/en-US/docs/Web/HTTP/Authentication /en-US/docs/Web/HTTP/Guides/Authentication +/en-US/docs/Web/HTTP/Basic_access_authentication /en-US/docs/Web/HTTP/Guides/Authentication /en-US/docs/Web/HTTP/Basics_of_HTTP /en-US/docs/Web/HTTP /en-US/docs/Web/HTTP/Basics_of_HTTP/Choosing_between_www_and_non-www_URLs /en-US/docs/Web/URI/Guides/Choosing_between_www_and_non-www_URLs /en-US/docs/Web/HTTP/Basics_of_HTTP/Data_URIs /en-US/docs/Web/URI/Reference/Schemes/data /en-US/docs/Web/HTTP/Basics_of_HTTP/Data_URLs /en-US/docs/Web/URI/Reference/Schemes/data -/en-US/docs/Web/HTTP/Basics_of_HTTP/Evolution_of_HTTP /en-US/docs/Web/HTTP/Evolution_of_HTTP +/en-US/docs/Web/HTTP/Basics_of_HTTP/Evolution_of_HTTP /en-US/docs/Web/HTTP/Guides/Evolution_of_HTTP /en-US/docs/Web/HTTP/Basics_of_HTTP/Introduction_to_www_and_non-www_URLs /en-US/docs/Web/URI/Guides/Choosing_between_www_and_non-www_URLs -/en-US/docs/Web/HTTP/Basics_of_HTTP/MIME_types /en-US/docs/Web/HTTP/MIME_types -/en-US/docs/Web/HTTP/Basics_of_HTTP/MIME_types/Common_types /en-US/docs/Web/HTTP/MIME_types/Common_types -/en-US/docs/Web/HTTP/Basics_of_HTTP/MIME_types/Complete_list_of_MIME_types /en-US/docs/Web/HTTP/MIME_types/Common_types +/en-US/docs/Web/HTTP/Basics_of_HTTP/MIME_types /en-US/docs/Web/HTTP/Guides/MIME_types +/en-US/docs/Web/HTTP/Basics_of_HTTP/MIME_types/Common_types /en-US/docs/Web/HTTP/Guides/MIME_types/Common_types +/en-US/docs/Web/HTTP/Basics_of_HTTP/MIME_types/Complete_list_of_MIME_types /en-US/docs/Web/HTTP/Guides/MIME_types/Common_types /en-US/docs/Web/HTTP/Basics_of_HTTP/Resource_URLs /en-US/docs/Web/URI/Reference/Schemes/resource -/en-US/docs/Web/HTTP/CORS/Errors/Reason:_CORS_header_‘Origin’_cannot_be_added /en-US/docs/Web/HTTP/CORS/Errors/CORSOriginHeaderNotAdded -/en-US/docs/Web/HTTP/Caching_FAQ /en-US/docs/Web/HTTP/Caching +/en-US/docs/Web/HTTP/Browser_detection_using_the_user_agent /en-US/docs/Web/HTTP/Guides/Browser_detection_using_the_user_agent +/en-US/docs/Web/HTTP/CORS /en-US/docs/Web/HTTP/Guides/CORS +/en-US/docs/Web/HTTP/CORS/Errors /en-US/docs/Web/HTTP/Guides/CORS/Errors +/en-US/docs/Web/HTTP/CORS/Errors/CORSAllowOriginNotMatchingOrigin /en-US/docs/Web/HTTP/Guides/CORS/Errors/CORSAllowOriginNotMatchingOrigin +/en-US/docs/Web/HTTP/CORS/Errors/CORSDidNotSucceed /en-US/docs/Web/HTTP/Guides/CORS/Errors/CORSDidNotSucceed +/en-US/docs/Web/HTTP/CORS/Errors/CORSDisabled /en-US/docs/Web/HTTP/Guides/CORS/Errors/CORSDisabled +/en-US/docs/Web/HTTP/CORS/Errors/CORSExternalRedirectNotAllowed /en-US/docs/Web/HTTP/Guides/CORS/Errors/CORSExternalRedirectNotAllowed +/en-US/docs/Web/HTTP/CORS/Errors/CORSInvalidAllowHeader /en-US/docs/Web/HTTP/Guides/CORS/Errors/CORSInvalidAllowHeader +/en-US/docs/Web/HTTP/CORS/Errors/CORSInvalidAllowMethod /en-US/docs/Web/HTTP/Guides/CORS/Errors/CORSInvalidAllowMethod +/en-US/docs/Web/HTTP/CORS/Errors/CORSMIssingAllowCredentials /en-US/docs/Web/HTTP/Guides/CORS/Errors/CORSMIssingAllowCredentials +/en-US/docs/Web/HTTP/CORS/Errors/CORSMethodNotFound /en-US/docs/Web/HTTP/Guides/CORS/Errors/CORSMethodNotFound +/en-US/docs/Web/HTTP/CORS/Errors/CORSMissingAllowHeaderFromPreflight /en-US/docs/Web/HTTP/Guides/CORS/Errors/CORSMissingAllowHeaderFromPreflight +/en-US/docs/Web/HTTP/CORS/Errors/CORSMissingAllowOrigin /en-US/docs/Web/HTTP/Guides/CORS/Errors/CORSMissingAllowOrigin +/en-US/docs/Web/HTTP/CORS/Errors/CORSMultipleAllowOriginNotAllowed /en-US/docs/Web/HTTP/Guides/CORS/Errors/CORSMultipleAllowOriginNotAllowed +/en-US/docs/Web/HTTP/CORS/Errors/CORSNotSupportingCredentials /en-US/docs/Web/HTTP/Guides/CORS/Errors/CORSNotSupportingCredentials +/en-US/docs/Web/HTTP/CORS/Errors/CORSOriginHeaderNotAdded /en-US/docs/Web/HTTP/Guides/CORS/Errors/CORSOriginHeaderNotAdded +/en-US/docs/Web/HTTP/CORS/Errors/CORSPreflightDidNotSucceed /en-US/docs/Web/HTTP/Guides/CORS/Errors/CORSPreflightDidNotSucceed +/en-US/docs/Web/HTTP/CORS/Errors/CORSRequestNotHttp /en-US/docs/Web/HTTP/Guides/CORS/Errors/CORSRequestNotHttp +/en-US/docs/Web/HTTP/CORS/Errors/Reason:_CORS_header_‘Origin’_cannot_be_added /en-US/docs/Web/HTTP/Guides/CORS/Errors/CORSOriginHeaderNotAdded +/en-US/docs/Web/HTTP/CSP /en-US/docs/Web/HTTP/Guides/CSP +/en-US/docs/Web/HTTP/CSP/Errors /en-US/docs/Web/HTTP/Guides/CSP/Errors +/en-US/docs/Web/HTTP/CSP/Errors/CSPViolation /en-US/docs/Web/HTTP/Guides/CSP/Errors/CSPViolation +/en-US/docs/Web/HTTP/Caching /en-US/docs/Web/HTTP/Guides/Caching +/en-US/docs/Web/HTTP/Caching_FAQ /en-US/docs/Web/HTTP/Guides/Caching +/en-US/docs/Web/HTTP/Client_hints /en-US/docs/Web/HTTP/Guides/Client_hints +/en-US/docs/Web/HTTP/Compression /en-US/docs/Web/HTTP/Guides/Compression +/en-US/docs/Web/HTTP/Conditional_requests /en-US/docs/Web/HTTP/Guides/Conditional_requests /en-US/docs/Web/HTTP/Configuring_servers_for_Ogg_media /en-US/docs/Web/Media/Guides/Formats/Configuring_servers_for_Ogg_media -/en-US/docs/Web/HTTP/Controlling_DNS_prefetching /en-US/docs/Web/HTTP/Headers/X-DNS-Prefetch-Control -/en-US/docs/Web/HTTP/Cookies/Cookie_Prefixes /en-US/docs/Web/HTTP/Cookies#Cookie_prefixes -/en-US/docs/Web/HTTP/Cross-Origin_Resource_Policy_(CORP) /en-US/docs/Web/HTTP/Cross-Origin_Resource_Policy -/en-US/docs/Web/HTTP/Feature_Policy /en-US/docs/Web/HTTP/Permissions_Policy -/en-US/docs/Web/HTTP/Gecko_user_agent_string_reference /en-US/docs/Web/HTTP/Headers/User-Agent/Firefox -/en-US/docs/Web/HTTP/HTTP_response_codes /en-US/docs/Web/HTTP/Status -/en-US/docs/Web/HTTP/Headers/Accept-Charset /en-US/docs/Web/HTTP/Headers -/en-US/docs/Web/HTTP/Headers/Cache-Disposition /en-US/docs/Web/HTTP/Headers/Content-Disposition -/en-US/docs/Web/HTTP/Headers/Content-Security-Policy/Sources /en-US/docs/Web/HTTP/Headers/Content-Security-Policy#fetch_directive_syntax -/en-US/docs/Web/HTTP/Headers/Content-Security-Policy/navigate-to /en-US/docs/Web/HTTP/Headers/Content-Security-Policy -/en-US/docs/Web/HTTP/Headers/Content-Security-Policy/referrer /en-US/docs/Web/HTTP/Headers/Referrer-Policy -/en-US/docs/Web/HTTP/Headers/Content-Security-Policy/require-sri-for /en-US/docs/Web/HTTP/Headers/Content-Security-Policy -/en-US/docs/Web/HTTP/Headers/Cookie2 /en-US/docs/Web/HTTP/Headers/Cookie -/en-US/docs/Web/HTTP/Headers/Digest /en-US/docs/Web/HTTP/Headers/Content-Digest -/en-US/docs/Web/HTTP/Headers/Feature-Policy /en-US/docs/Web/HTTP/Headers/Permissions-Policy -/en-US/docs/Web/HTTP/Headers/Feature-Policy/accelerometer /en-US/docs/Web/HTTP/Headers/Permissions-Policy/accelerometer -/en-US/docs/Web/HTTP/Headers/Feature-Policy/ambient-light-sensor /en-US/docs/Web/HTTP/Headers/Permissions-Policy/ambient-light-sensor -/en-US/docs/Web/HTTP/Headers/Feature-Policy/autoplay /en-US/docs/Web/HTTP/Headers/Permissions-Policy/autoplay -/en-US/docs/Web/HTTP/Headers/Feature-Policy/camera /en-US/docs/Web/HTTP/Headers/Permissions-Policy/camera -/en-US/docs/Web/HTTP/Headers/Feature-Policy/display-capture /en-US/docs/Web/HTTP/Headers/Permissions-Policy/display-capture -/en-US/docs/Web/HTTP/Headers/Feature-Policy/document-domain /en-US/docs/Web/HTTP/Headers/Permissions-Policy/document-domain -/en-US/docs/Web/HTTP/Headers/Feature-Policy/encrypted-media /en-US/docs/Web/HTTP/Headers/Permissions-Policy/encrypted-media -/en-US/docs/Web/HTTP/Headers/Feature-Policy/fullscreen /en-US/docs/Web/HTTP/Headers/Permissions-Policy/fullscreen -/en-US/docs/Web/HTTP/Headers/Feature-Policy/gamepad /en-US/docs/Web/HTTP/Headers/Permissions-Policy/gamepad -/en-US/docs/Web/HTTP/Headers/Feature-Policy/geolocation /en-US/docs/Web/HTTP/Headers/Permissions-Policy/geolocation -/en-US/docs/Web/HTTP/Headers/Feature-Policy/gyroscope /en-US/docs/Web/HTTP/Headers/Permissions-Policy/gyroscope -/en-US/docs/Web/HTTP/Headers/Feature-Policy/layout-animations /en-US/docs/Web/HTTP/Headers/Permissions-Policy -/en-US/docs/Web/HTTP/Headers/Feature-Policy/legacy-image-formats /en-US/docs/Web/HTTP/Headers/Permissions-Policy -/en-US/docs/Web/HTTP/Headers/Feature-Policy/magnetometer /en-US/docs/Web/HTTP/Headers/Permissions-Policy/magnetometer -/en-US/docs/Web/HTTP/Headers/Feature-Policy/microphone /en-US/docs/Web/HTTP/Headers/Permissions-Policy/microphone -/en-US/docs/Web/HTTP/Headers/Feature-Policy/midi /en-US/docs/Web/HTTP/Headers/Permissions-Policy/midi -/en-US/docs/Web/HTTP/Headers/Feature-Policy/oversized-images /en-US/docs/Web/HTTP/Headers/Permissions-Policy -/en-US/docs/Web/HTTP/Headers/Feature-Policy/payment /en-US/docs/Web/HTTP/Headers/Permissions-Policy/payment -/en-US/docs/Web/HTTP/Headers/Feature-Policy/picture-in-picture /en-US/docs/Web/HTTP/Headers/Permissions-Policy/picture-in-picture -/en-US/docs/Web/HTTP/Headers/Feature-Policy/publickey-credentials /en-US/docs/Web/HTTP/Headers/Permissions-Policy/publickey-credentials-get -/en-US/docs/Web/HTTP/Headers/Feature-Policy/publickey-credentials-get /en-US/docs/Web/HTTP/Headers/Permissions-Policy/publickey-credentials-get -/en-US/docs/Web/HTTP/Headers/Feature-Policy/screen-wake-lock /en-US/docs/Web/HTTP/Headers/Permissions-Policy/screen-wake-lock -/en-US/docs/Web/HTTP/Headers/Feature-Policy/speaker-selection /en-US/docs/Web/HTTP/Headers/Permissions-Policy/speaker-selection -/en-US/docs/Web/HTTP/Headers/Feature-Policy/sync-xhr /en-US/docs/Web/HTTP/Headers/Permissions-Policy -/en-US/docs/Web/HTTP/Headers/Feature-Policy/unoptimized-images /en-US/docs/Web/HTTP/Headers/Permissions-Policy -/en-US/docs/Web/HTTP/Headers/Feature-Policy/unsized-media /en-US/docs/Web/HTTP/Headers/Permissions-Policy -/en-US/docs/Web/HTTP/Headers/Feature-Policy/usb /en-US/docs/Web/HTTP/Headers/Permissions-Policy/usb -/en-US/docs/Web/HTTP/Headers/Feature-Policy/vr /en-US/docs/Web/HTTP/Headers/Permissions-Policy/xr-spatial-tracking -/en-US/docs/Web/HTTP/Headers/Feature-Policy/wake-lock /en-US/docs/Web/HTTP/Headers/Permissions-Policy/screen-wake-lock -/en-US/docs/Web/HTTP/Headers/Feature-Policy/web-share /en-US/docs/Web/HTTP/Headers/Permissions-Policy/web-share -/en-US/docs/Web/HTTP/Headers/Feature-Policy/webauthn /en-US/docs/Web/HTTP/Headers/Permissions-Policy/publickey-credentials-get -/en-US/docs/Web/HTTP/Headers/Feature-Policy/xr /en-US/docs/Web/HTTP/Headers/Permissions-Policy/xr-spatial-tracking -/en-US/docs/Web/HTTP/Headers/Feature-Policy/xr-spatial-tracking /en-US/docs/Web/HTTP/Headers/Permissions-Policy/xr-spatial-tracking -/en-US/docs/Web/HTTP/Headers/Permissions-Policy/layout-animations /en-US/docs/Web/HTTP/Headers/Permissions-Policy -/en-US/docs/Web/HTTP/Headers/Permissions-Policy/legacy-image-formats /en-US/docs/Web/HTTP/Headers/Permissions-Policy -/en-US/docs/Web/HTTP/Headers/Permissions-Policy/oversized-images /en-US/docs/Web/HTTP/Headers/Permissions-Policy -/en-US/docs/Web/HTTP/Headers/Permissions-Policy/sync-xhr /en-US/docs/Web/HTTP/Headers/Permissions-Policy -/en-US/docs/Web/HTTP/Headers/Permissions-Policy/unoptimized-images /en-US/docs/Web/HTTP/Headers/Permissions-Policy -/en-US/docs/Web/HTTP/Headers/Permissions-Policy/unsized-media /en-US/docs/Web/HTTP/Headers/Permissions-Policy -/en-US/docs/Web/HTTP/Headers/Public-Key-Pins /en-US/docs/Web/HTTP/Headers/Expect-CT -/en-US/docs/Web/HTTP/Headers/Public-Key-Pins-Report-Only /en-US/docs/Web/HTTP/Headers/Expect-CT -/en-US/docs/Web/HTTP/Headers/Ranges /en-US/docs/Web/HTTP/Headers/Range -/en-US/docs/Web/HTTP/Headers/Set-Cookie/SameSite /en-US/docs/Web/HTTP/Headers/Set-Cookie#samesitesamesite-value -/en-US/docs/Web/HTTP/Headers/Set-Cookie2 /en-US/docs/Web/HTTP/Headers/Set-Cookie -/en-US/docs/Web/HTTP/Headers/Want-Digest /en-US/docs/Web/HTTP/Headers/Want-Content-Digest -/en-US/docs/Web/HTTP/History_of_HTTP_versions /en-US/docs/Web/HTTP/Evolution_of_HTTP +/en-US/docs/Web/HTTP/Connection_management_in_HTTP_1.x /en-US/docs/Web/HTTP/Guides/Connection_management_in_HTTP_1.x +/en-US/docs/Web/HTTP/Content_negotiation /en-US/docs/Web/HTTP/Guides/Content_negotiation +/en-US/docs/Web/HTTP/Content_negotiation/List_of_default_Accept_values /en-US/docs/Web/HTTP/Guides/Content_negotiation/List_of_default_Accept_values +/en-US/docs/Web/HTTP/Controlling_DNS_prefetching /en-US/docs/Web/HTTP/Reference/Headers/X-DNS-Prefetch-Control +/en-US/docs/Web/HTTP/Cookies /en-US/docs/Web/HTTP/Guides/Cookies +/en-US/docs/Web/HTTP/Cookies/Cookie_Prefixes /en-US/docs/Web/HTTP/Guides/Cookies#Cookie_prefixes +/en-US/docs/Web/HTTP/Cross-Origin_Resource_Policy /en-US/docs/Web/HTTP/Guides/Cross-Origin_Resource_Policy +/en-US/docs/Web/HTTP/Cross-Origin_Resource_Policy_(CORP) /en-US/docs/Web/HTTP/Guides/Cross-Origin_Resource_Policy +/en-US/docs/Web/HTTP/Evolution_of_HTTP /en-US/docs/Web/HTTP/Guides/Evolution_of_HTTP +/en-US/docs/Web/HTTP/Feature_Policy /en-US/docs/Web/HTTP/Guides/Permissions_Policy +/en-US/docs/Web/HTTP/Gecko_user_agent_string_reference /en-US/docs/Web/HTTP/Reference/Headers/User-Agent/Firefox +/en-US/docs/Web/HTTP/HTTP_response_codes /en-US/docs/Web/HTTP/Reference/Status +/en-US/docs/Web/HTTP/Headers /en-US/docs/Web/HTTP/Reference/Headers +/en-US/docs/Web/HTTP/Headers/Accept /en-US/docs/Web/HTTP/Reference/Headers/Accept +/en-US/docs/Web/HTTP/Headers/Accept-CH /en-US/docs/Web/HTTP/Reference/Headers/Accept-CH +/en-US/docs/Web/HTTP/Headers/Accept-Charset /en-US/docs/Web/HTTP/Reference/Headers +/en-US/docs/Web/HTTP/Headers/Accept-Encoding /en-US/docs/Web/HTTP/Reference/Headers/Accept-Encoding +/en-US/docs/Web/HTTP/Headers/Accept-Language /en-US/docs/Web/HTTP/Reference/Headers/Accept-Language +/en-US/docs/Web/HTTP/Headers/Accept-Patch /en-US/docs/Web/HTTP/Reference/Headers/Accept-Patch +/en-US/docs/Web/HTTP/Headers/Accept-Post /en-US/docs/Web/HTTP/Reference/Headers/Accept-Post +/en-US/docs/Web/HTTP/Headers/Accept-Ranges /en-US/docs/Web/HTTP/Reference/Headers/Accept-Ranges +/en-US/docs/Web/HTTP/Headers/Access-Control-Allow-Credentials /en-US/docs/Web/HTTP/Reference/Headers/Access-Control-Allow-Credentials +/en-US/docs/Web/HTTP/Headers/Access-Control-Allow-Headers /en-US/docs/Web/HTTP/Reference/Headers/Access-Control-Allow-Headers +/en-US/docs/Web/HTTP/Headers/Access-Control-Allow-Methods /en-US/docs/Web/HTTP/Reference/Headers/Access-Control-Allow-Methods +/en-US/docs/Web/HTTP/Headers/Access-Control-Allow-Origin /en-US/docs/Web/HTTP/Reference/Headers/Access-Control-Allow-Origin +/en-US/docs/Web/HTTP/Headers/Access-Control-Expose-Headers /en-US/docs/Web/HTTP/Reference/Headers/Access-Control-Expose-Headers +/en-US/docs/Web/HTTP/Headers/Access-Control-Max-Age /en-US/docs/Web/HTTP/Reference/Headers/Access-Control-Max-Age +/en-US/docs/Web/HTTP/Headers/Access-Control-Request-Headers /en-US/docs/Web/HTTP/Reference/Headers/Access-Control-Request-Headers +/en-US/docs/Web/HTTP/Headers/Access-Control-Request-Method /en-US/docs/Web/HTTP/Reference/Headers/Access-Control-Request-Method +/en-US/docs/Web/HTTP/Headers/Age /en-US/docs/Web/HTTP/Reference/Headers/Age +/en-US/docs/Web/HTTP/Headers/Allow /en-US/docs/Web/HTTP/Reference/Headers/Allow +/en-US/docs/Web/HTTP/Headers/Alt-Svc /en-US/docs/Web/HTTP/Reference/Headers/Alt-Svc +/en-US/docs/Web/HTTP/Headers/Alt-Used /en-US/docs/Web/HTTP/Reference/Headers/Alt-Used +/en-US/docs/Web/HTTP/Headers/Attribution-Reporting-Eligible /en-US/docs/Web/HTTP/Reference/Headers/Attribution-Reporting-Eligible +/en-US/docs/Web/HTTP/Headers/Attribution-Reporting-Register-Source /en-US/docs/Web/HTTP/Reference/Headers/Attribution-Reporting-Register-Source +/en-US/docs/Web/HTTP/Headers/Attribution-Reporting-Register-Trigger /en-US/docs/Web/HTTP/Reference/Headers/Attribution-Reporting-Register-Trigger +/en-US/docs/Web/HTTP/Headers/Authorization /en-US/docs/Web/HTTP/Reference/Headers/Authorization +/en-US/docs/Web/HTTP/Headers/Cache-Control /en-US/docs/Web/HTTP/Reference/Headers/Cache-Control +/en-US/docs/Web/HTTP/Headers/Cache-Disposition /en-US/docs/Web/HTTP/Reference/Headers/Content-Disposition +/en-US/docs/Web/HTTP/Headers/Clear-Site-Data /en-US/docs/Web/HTTP/Reference/Headers/Clear-Site-Data +/en-US/docs/Web/HTTP/Headers/Connection /en-US/docs/Web/HTTP/Reference/Headers/Connection +/en-US/docs/Web/HTTP/Headers/Content-DPR /en-US/docs/Web/HTTP/Reference/Headers/Content-DPR +/en-US/docs/Web/HTTP/Headers/Content-Digest /en-US/docs/Web/HTTP/Reference/Headers/Content-Digest +/en-US/docs/Web/HTTP/Headers/Content-Disposition /en-US/docs/Web/HTTP/Reference/Headers/Content-Disposition +/en-US/docs/Web/HTTP/Headers/Content-Encoding /en-US/docs/Web/HTTP/Reference/Headers/Content-Encoding +/en-US/docs/Web/HTTP/Headers/Content-Language /en-US/docs/Web/HTTP/Reference/Headers/Content-Language +/en-US/docs/Web/HTTP/Headers/Content-Length /en-US/docs/Web/HTTP/Reference/Headers/Content-Length +/en-US/docs/Web/HTTP/Headers/Content-Location /en-US/docs/Web/HTTP/Reference/Headers/Content-Location +/en-US/docs/Web/HTTP/Headers/Content-Range /en-US/docs/Web/HTTP/Reference/Headers/Content-Range +/en-US/docs/Web/HTTP/Headers/Content-Security-Policy /en-US/docs/Web/HTTP/Reference/Headers/Content-Security-Policy +/en-US/docs/Web/HTTP/Headers/Content-Security-Policy-Report-Only /en-US/docs/Web/HTTP/Reference/Headers/Content-Security-Policy-Report-Only +/en-US/docs/Web/HTTP/Headers/Content-Security-Policy/Sources /en-US/docs/Web/HTTP/Reference/Headers/Content-Security-Policy#fetch_directive_syntax +/en-US/docs/Web/HTTP/Headers/Content-Security-Policy/base-uri /en-US/docs/Web/HTTP/Reference/Headers/Content-Security-Policy/base-uri +/en-US/docs/Web/HTTP/Headers/Content-Security-Policy/block-all-mixed-content /en-US/docs/Web/HTTP/Reference/Headers/Content-Security-Policy/block-all-mixed-content +/en-US/docs/Web/HTTP/Headers/Content-Security-Policy/child-src /en-US/docs/Web/HTTP/Reference/Headers/Content-Security-Policy/child-src +/en-US/docs/Web/HTTP/Headers/Content-Security-Policy/connect-src /en-US/docs/Web/HTTP/Reference/Headers/Content-Security-Policy/connect-src +/en-US/docs/Web/HTTP/Headers/Content-Security-Policy/default-src /en-US/docs/Web/HTTP/Reference/Headers/Content-Security-Policy/default-src +/en-US/docs/Web/HTTP/Headers/Content-Security-Policy/fenced-frame-src /en-US/docs/Web/HTTP/Reference/Headers/Content-Security-Policy/fenced-frame-src +/en-US/docs/Web/HTTP/Headers/Content-Security-Policy/font-src /en-US/docs/Web/HTTP/Reference/Headers/Content-Security-Policy/font-src +/en-US/docs/Web/HTTP/Headers/Content-Security-Policy/form-action /en-US/docs/Web/HTTP/Reference/Headers/Content-Security-Policy/form-action +/en-US/docs/Web/HTTP/Headers/Content-Security-Policy/frame-ancestors /en-US/docs/Web/HTTP/Reference/Headers/Content-Security-Policy/frame-ancestors +/en-US/docs/Web/HTTP/Headers/Content-Security-Policy/frame-src /en-US/docs/Web/HTTP/Reference/Headers/Content-Security-Policy/frame-src +/en-US/docs/Web/HTTP/Headers/Content-Security-Policy/img-src /en-US/docs/Web/HTTP/Reference/Headers/Content-Security-Policy/img-src +/en-US/docs/Web/HTTP/Headers/Content-Security-Policy/manifest-src /en-US/docs/Web/HTTP/Reference/Headers/Content-Security-Policy/manifest-src +/en-US/docs/Web/HTTP/Headers/Content-Security-Policy/media-src /en-US/docs/Web/HTTP/Reference/Headers/Content-Security-Policy/media-src +/en-US/docs/Web/HTTP/Headers/Content-Security-Policy/navigate-to /en-US/docs/Web/HTTP/Reference/Headers/Content-Security-Policy +/en-US/docs/Web/HTTP/Headers/Content-Security-Policy/object-src /en-US/docs/Web/HTTP/Reference/Headers/Content-Security-Policy/object-src +/en-US/docs/Web/HTTP/Headers/Content-Security-Policy/prefetch-src /en-US/docs/Web/HTTP/Reference/Headers/Content-Security-Policy/prefetch-src +/en-US/docs/Web/HTTP/Headers/Content-Security-Policy/referrer /en-US/docs/Web/HTTP/Reference/Headers/Referrer-Policy +/en-US/docs/Web/HTTP/Headers/Content-Security-Policy/report-to /en-US/docs/Web/HTTP/Reference/Headers/Content-Security-Policy/report-to +/en-US/docs/Web/HTTP/Headers/Content-Security-Policy/report-uri /en-US/docs/Web/HTTP/Reference/Headers/Content-Security-Policy/report-uri +/en-US/docs/Web/HTTP/Headers/Content-Security-Policy/require-sri-for /en-US/docs/Web/HTTP/Reference/Headers/Content-Security-Policy +/en-US/docs/Web/HTTP/Headers/Content-Security-Policy/require-trusted-types-for /en-US/docs/Web/HTTP/Reference/Headers/Content-Security-Policy/require-trusted-types-for +/en-US/docs/Web/HTTP/Headers/Content-Security-Policy/sandbox /en-US/docs/Web/HTTP/Reference/Headers/Content-Security-Policy/sandbox +/en-US/docs/Web/HTTP/Headers/Content-Security-Policy/script-src /en-US/docs/Web/HTTP/Reference/Headers/Content-Security-Policy/script-src +/en-US/docs/Web/HTTP/Headers/Content-Security-Policy/script-src-attr /en-US/docs/Web/HTTP/Reference/Headers/Content-Security-Policy/script-src-attr +/en-US/docs/Web/HTTP/Headers/Content-Security-Policy/script-src-elem /en-US/docs/Web/HTTP/Reference/Headers/Content-Security-Policy/script-src-elem +/en-US/docs/Web/HTTP/Headers/Content-Security-Policy/style-src /en-US/docs/Web/HTTP/Reference/Headers/Content-Security-Policy/style-src +/en-US/docs/Web/HTTP/Headers/Content-Security-Policy/style-src-attr /en-US/docs/Web/HTTP/Reference/Headers/Content-Security-Policy/style-src-attr +/en-US/docs/Web/HTTP/Headers/Content-Security-Policy/style-src-elem /en-US/docs/Web/HTTP/Reference/Headers/Content-Security-Policy/style-src-elem +/en-US/docs/Web/HTTP/Headers/Content-Security-Policy/trusted-types /en-US/docs/Web/HTTP/Reference/Headers/Content-Security-Policy/trusted-types +/en-US/docs/Web/HTTP/Headers/Content-Security-Policy/upgrade-insecure-requests /en-US/docs/Web/HTTP/Reference/Headers/Content-Security-Policy/upgrade-insecure-requests +/en-US/docs/Web/HTTP/Headers/Content-Security-Policy/worker-src /en-US/docs/Web/HTTP/Reference/Headers/Content-Security-Policy/worker-src +/en-US/docs/Web/HTTP/Headers/Content-Type /en-US/docs/Web/HTTP/Reference/Headers/Content-Type +/en-US/docs/Web/HTTP/Headers/Cookie /en-US/docs/Web/HTTP/Reference/Headers/Cookie +/en-US/docs/Web/HTTP/Headers/Cookie2 /en-US/docs/Web/HTTP/Reference/Headers/Cookie +/en-US/docs/Web/HTTP/Headers/Critical-CH /en-US/docs/Web/HTTP/Reference/Headers/Critical-CH +/en-US/docs/Web/HTTP/Headers/Cross-Origin-Embedder-Policy /en-US/docs/Web/HTTP/Reference/Headers/Cross-Origin-Embedder-Policy +/en-US/docs/Web/HTTP/Headers/Cross-Origin-Opener-Policy /en-US/docs/Web/HTTP/Reference/Headers/Cross-Origin-Opener-Policy +/en-US/docs/Web/HTTP/Headers/Cross-Origin-Resource-Policy /en-US/docs/Web/HTTP/Reference/Headers/Cross-Origin-Resource-Policy +/en-US/docs/Web/HTTP/Headers/DNT /en-US/docs/Web/HTTP/Reference/Headers/DNT +/en-US/docs/Web/HTTP/Headers/DPR /en-US/docs/Web/HTTP/Reference/Headers/DPR +/en-US/docs/Web/HTTP/Headers/Date /en-US/docs/Web/HTTP/Reference/Headers/Date +/en-US/docs/Web/HTTP/Headers/Device-Memory /en-US/docs/Web/HTTP/Reference/Headers/Device-Memory +/en-US/docs/Web/HTTP/Headers/Digest /en-US/docs/Web/HTTP/Reference/Headers/Content-Digest +/en-US/docs/Web/HTTP/Headers/Downlink /en-US/docs/Web/HTTP/Reference/Headers/Downlink +/en-US/docs/Web/HTTP/Headers/ECT /en-US/docs/Web/HTTP/Reference/Headers/ECT +/en-US/docs/Web/HTTP/Headers/ETag /en-US/docs/Web/HTTP/Reference/Headers/ETag +/en-US/docs/Web/HTTP/Headers/Early-Data /en-US/docs/Web/HTTP/Reference/Headers/Early-Data +/en-US/docs/Web/HTTP/Headers/Expect /en-US/docs/Web/HTTP/Reference/Headers/Expect +/en-US/docs/Web/HTTP/Headers/Expect-CT /en-US/docs/Web/HTTP/Reference/Headers/Expect-CT +/en-US/docs/Web/HTTP/Headers/Expires /en-US/docs/Web/HTTP/Reference/Headers/Expires +/en-US/docs/Web/HTTP/Headers/Feature-Policy /en-US/docs/Web/HTTP/Reference/Headers/Permissions-Policy +/en-US/docs/Web/HTTP/Headers/Feature-Policy/accelerometer /en-US/docs/Web/HTTP/Reference/Headers/Permissions-Policy/accelerometer +/en-US/docs/Web/HTTP/Headers/Feature-Policy/ambient-light-sensor /en-US/docs/Web/HTTP/Reference/Headers/Permissions-Policy/ambient-light-sensor +/en-US/docs/Web/HTTP/Headers/Feature-Policy/autoplay /en-US/docs/Web/HTTP/Reference/Headers/Permissions-Policy/autoplay +/en-US/docs/Web/HTTP/Headers/Feature-Policy/camera /en-US/docs/Web/HTTP/Reference/Headers/Permissions-Policy/camera +/en-US/docs/Web/HTTP/Headers/Feature-Policy/display-capture /en-US/docs/Web/HTTP/Reference/Headers/Permissions-Policy/display-capture +/en-US/docs/Web/HTTP/Headers/Feature-Policy/document-domain /en-US/docs/Web/HTTP/Reference/Headers/Permissions-Policy +/en-US/docs/Web/HTTP/Headers/Feature-Policy/encrypted-media /en-US/docs/Web/HTTP/Reference/Headers/Permissions-Policy/encrypted-media +/en-US/docs/Web/HTTP/Headers/Feature-Policy/fullscreen /en-US/docs/Web/HTTP/Reference/Headers/Permissions-Policy/fullscreen +/en-US/docs/Web/HTTP/Headers/Feature-Policy/gamepad /en-US/docs/Web/HTTP/Reference/Headers/Permissions-Policy/gamepad +/en-US/docs/Web/HTTP/Headers/Feature-Policy/geolocation /en-US/docs/Web/HTTP/Reference/Headers/Permissions-Policy/geolocation +/en-US/docs/Web/HTTP/Headers/Feature-Policy/gyroscope /en-US/docs/Web/HTTP/Reference/Headers/Permissions-Policy/gyroscope +/en-US/docs/Web/HTTP/Headers/Feature-Policy/layout-animations /en-US/docs/Web/HTTP/Reference/Headers/Permissions-Policy +/en-US/docs/Web/HTTP/Headers/Feature-Policy/legacy-image-formats /en-US/docs/Web/HTTP/Reference/Headers/Permissions-Policy +/en-US/docs/Web/HTTP/Headers/Feature-Policy/magnetometer /en-US/docs/Web/HTTP/Reference/Headers/Permissions-Policy/magnetometer +/en-US/docs/Web/HTTP/Headers/Feature-Policy/microphone /en-US/docs/Web/HTTP/Reference/Headers/Permissions-Policy/microphone +/en-US/docs/Web/HTTP/Headers/Feature-Policy/midi /en-US/docs/Web/HTTP/Reference/Headers/Permissions-Policy/midi +/en-US/docs/Web/HTTP/Headers/Feature-Policy/oversized-images /en-US/docs/Web/HTTP/Reference/Headers/Permissions-Policy +/en-US/docs/Web/HTTP/Headers/Feature-Policy/payment /en-US/docs/Web/HTTP/Reference/Headers/Permissions-Policy/payment +/en-US/docs/Web/HTTP/Headers/Feature-Policy/picture-in-picture /en-US/docs/Web/HTTP/Reference/Headers/Permissions-Policy/picture-in-picture +/en-US/docs/Web/HTTP/Headers/Feature-Policy/publickey-credentials /en-US/docs/Web/HTTP/Reference/Headers/Permissions-Policy/publickey-credentials-get +/en-US/docs/Web/HTTP/Headers/Feature-Policy/publickey-credentials-get /en-US/docs/Web/HTTP/Reference/Headers/Permissions-Policy/publickey-credentials-get +/en-US/docs/Web/HTTP/Headers/Feature-Policy/screen-wake-lock /en-US/docs/Web/HTTP/Reference/Headers/Permissions-Policy/screen-wake-lock +/en-US/docs/Web/HTTP/Headers/Feature-Policy/speaker-selection /en-US/docs/Web/HTTP/Reference/Headers/Permissions-Policy/speaker-selection +/en-US/docs/Web/HTTP/Headers/Feature-Policy/sync-xhr /en-US/docs/Web/HTTP/Reference/Headers/Permissions-Policy +/en-US/docs/Web/HTTP/Headers/Feature-Policy/unoptimized-images /en-US/docs/Web/HTTP/Reference/Headers/Permissions-Policy +/en-US/docs/Web/HTTP/Headers/Feature-Policy/unsized-media /en-US/docs/Web/HTTP/Reference/Headers/Permissions-Policy +/en-US/docs/Web/HTTP/Headers/Feature-Policy/usb /en-US/docs/Web/HTTP/Reference/Headers/Permissions-Policy/usb +/en-US/docs/Web/HTTP/Headers/Feature-Policy/vr /en-US/docs/Web/HTTP/Reference/Headers/Permissions-Policy/xr-spatial-tracking +/en-US/docs/Web/HTTP/Headers/Feature-Policy/wake-lock /en-US/docs/Web/HTTP/Reference/Headers/Permissions-Policy/screen-wake-lock +/en-US/docs/Web/HTTP/Headers/Feature-Policy/web-share /en-US/docs/Web/HTTP/Reference/Headers/Permissions-Policy/web-share +/en-US/docs/Web/HTTP/Headers/Feature-Policy/webauthn /en-US/docs/Web/HTTP/Reference/Headers/Permissions-Policy/publickey-credentials-get +/en-US/docs/Web/HTTP/Headers/Feature-Policy/xr /en-US/docs/Web/HTTP/Reference/Headers/Permissions-Policy/xr-spatial-tracking +/en-US/docs/Web/HTTP/Headers/Feature-Policy/xr-spatial-tracking /en-US/docs/Web/HTTP/Reference/Headers/Permissions-Policy/xr-spatial-tracking +/en-US/docs/Web/HTTP/Headers/Forwarded /en-US/docs/Web/HTTP/Reference/Headers/Forwarded +/en-US/docs/Web/HTTP/Headers/From /en-US/docs/Web/HTTP/Reference/Headers/From +/en-US/docs/Web/HTTP/Headers/Host /en-US/docs/Web/HTTP/Reference/Headers/Host +/en-US/docs/Web/HTTP/Headers/If-Match /en-US/docs/Web/HTTP/Reference/Headers/If-Match +/en-US/docs/Web/HTTP/Headers/If-Modified-Since /en-US/docs/Web/HTTP/Reference/Headers/If-Modified-Since +/en-US/docs/Web/HTTP/Headers/If-None-Match /en-US/docs/Web/HTTP/Reference/Headers/If-None-Match +/en-US/docs/Web/HTTP/Headers/If-Range /en-US/docs/Web/HTTP/Reference/Headers/If-Range +/en-US/docs/Web/HTTP/Headers/If-Unmodified-Since /en-US/docs/Web/HTTP/Reference/Headers/If-Unmodified-Since +/en-US/docs/Web/HTTP/Headers/Keep-Alive /en-US/docs/Web/HTTP/Reference/Headers/Keep-Alive +/en-US/docs/Web/HTTP/Headers/Last-Modified /en-US/docs/Web/HTTP/Reference/Headers/Last-Modified +/en-US/docs/Web/HTTP/Headers/Link /en-US/docs/Web/HTTP/Reference/Headers/Link +/en-US/docs/Web/HTTP/Headers/Location /en-US/docs/Web/HTTP/Reference/Headers/Location +/en-US/docs/Web/HTTP/Headers/Max-Forwards /en-US/docs/Web/HTTP/Reference/Headers/Max-Forwards +/en-US/docs/Web/HTTP/Headers/NEL /en-US/docs/Web/HTTP/Reference/Headers/NEL +/en-US/docs/Web/HTTP/Headers/No-Vary-Search /en-US/docs/Web/HTTP/Reference/Headers/No-Vary-Search +/en-US/docs/Web/HTTP/Headers/Observe-Browsing-Topics /en-US/docs/Web/HTTP/Reference/Headers/Observe-Browsing-Topics +/en-US/docs/Web/HTTP/Headers/Origin /en-US/docs/Web/HTTP/Reference/Headers/Origin +/en-US/docs/Web/HTTP/Headers/Origin-Agent-Cluster /en-US/docs/Web/HTTP/Reference/Headers/Origin-Agent-Cluster +/en-US/docs/Web/HTTP/Headers/Permissions-Policy /en-US/docs/Web/HTTP/Reference/Headers/Permissions-Policy +/en-US/docs/Web/HTTP/Headers/Permissions-Policy/accelerometer /en-US/docs/Web/HTTP/Reference/Headers/Permissions-Policy/accelerometer +/en-US/docs/Web/HTTP/Headers/Permissions-Policy/ambient-light-sensor /en-US/docs/Web/HTTP/Reference/Headers/Permissions-Policy/ambient-light-sensor +/en-US/docs/Web/HTTP/Headers/Permissions-Policy/attribution-reporting /en-US/docs/Web/HTTP/Reference/Headers/Permissions-Policy/attribution-reporting +/en-US/docs/Web/HTTP/Headers/Permissions-Policy/autoplay /en-US/docs/Web/HTTP/Reference/Headers/Permissions-Policy/autoplay +/en-US/docs/Web/HTTP/Headers/Permissions-Policy/bluetooth /en-US/docs/Web/HTTP/Reference/Headers/Permissions-Policy/bluetooth +/en-US/docs/Web/HTTP/Headers/Permissions-Policy/browsing-topics /en-US/docs/Web/HTTP/Reference/Headers/Permissions-Policy/browsing-topics +/en-US/docs/Web/HTTP/Headers/Permissions-Policy/camera /en-US/docs/Web/HTTP/Reference/Headers/Permissions-Policy/camera +/en-US/docs/Web/HTTP/Headers/Permissions-Policy/compute-pressure /en-US/docs/Web/HTTP/Reference/Headers/Permissions-Policy/compute-pressure +/en-US/docs/Web/HTTP/Headers/Permissions-Policy/cross-origin-isolated /en-US/docs/Web/HTTP/Reference/Headers/Permissions-Policy/cross-origin-isolated +/en-US/docs/Web/HTTP/Headers/Permissions-Policy/display-capture /en-US/docs/Web/HTTP/Reference/Headers/Permissions-Policy/display-capture +/en-US/docs/Web/HTTP/Headers/Permissions-Policy/document-domain /en-US/docs/Web/HTTP/Reference/Headers/Permissions-Policy +/en-US/docs/Web/HTTP/Headers/Permissions-Policy/encrypted-media /en-US/docs/Web/HTTP/Reference/Headers/Permissions-Policy/encrypted-media +/en-US/docs/Web/HTTP/Headers/Permissions-Policy/fullscreen /en-US/docs/Web/HTTP/Reference/Headers/Permissions-Policy/fullscreen +/en-US/docs/Web/HTTP/Headers/Permissions-Policy/gamepad /en-US/docs/Web/HTTP/Reference/Headers/Permissions-Policy/gamepad +/en-US/docs/Web/HTTP/Headers/Permissions-Policy/geolocation /en-US/docs/Web/HTTP/Reference/Headers/Permissions-Policy/geolocation +/en-US/docs/Web/HTTP/Headers/Permissions-Policy/gyroscope /en-US/docs/Web/HTTP/Reference/Headers/Permissions-Policy/gyroscope +/en-US/docs/Web/HTTP/Headers/Permissions-Policy/hid /en-US/docs/Web/HTTP/Reference/Headers/Permissions-Policy/hid +/en-US/docs/Web/HTTP/Headers/Permissions-Policy/identity-credentials-get /en-US/docs/Web/HTTP/Reference/Headers/Permissions-Policy/identity-credentials-get +/en-US/docs/Web/HTTP/Headers/Permissions-Policy/idle-detection /en-US/docs/Web/HTTP/Reference/Headers/Permissions-Policy/idle-detection +/en-US/docs/Web/HTTP/Headers/Permissions-Policy/layout-animations /en-US/docs/Web/HTTP/Reference/Headers/Permissions-Policy +/en-US/docs/Web/HTTP/Headers/Permissions-Policy/legacy-image-formats /en-US/docs/Web/HTTP/Reference/Headers/Permissions-Policy +/en-US/docs/Web/HTTP/Headers/Permissions-Policy/local-fonts /en-US/docs/Web/HTTP/Reference/Headers/Permissions-Policy/local-fonts +/en-US/docs/Web/HTTP/Headers/Permissions-Policy/magnetometer /en-US/docs/Web/HTTP/Reference/Headers/Permissions-Policy/magnetometer +/en-US/docs/Web/HTTP/Headers/Permissions-Policy/microphone /en-US/docs/Web/HTTP/Reference/Headers/Permissions-Policy/microphone +/en-US/docs/Web/HTTP/Headers/Permissions-Policy/midi /en-US/docs/Web/HTTP/Reference/Headers/Permissions-Policy/midi +/en-US/docs/Web/HTTP/Headers/Permissions-Policy/otp-credentials /en-US/docs/Web/HTTP/Reference/Headers/Permissions-Policy/otp-credentials +/en-US/docs/Web/HTTP/Headers/Permissions-Policy/oversized-images /en-US/docs/Web/HTTP/Reference/Headers/Permissions-Policy +/en-US/docs/Web/HTTP/Headers/Permissions-Policy/payment /en-US/docs/Web/HTTP/Reference/Headers/Permissions-Policy/payment +/en-US/docs/Web/HTTP/Headers/Permissions-Policy/picture-in-picture /en-US/docs/Web/HTTP/Reference/Headers/Permissions-Policy/picture-in-picture +/en-US/docs/Web/HTTP/Headers/Permissions-Policy/publickey-credentials-create /en-US/docs/Web/HTTP/Reference/Headers/Permissions-Policy/publickey-credentials-create +/en-US/docs/Web/HTTP/Headers/Permissions-Policy/publickey-credentials-get /en-US/docs/Web/HTTP/Reference/Headers/Permissions-Policy/publickey-credentials-get +/en-US/docs/Web/HTTP/Headers/Permissions-Policy/screen-wake-lock /en-US/docs/Web/HTTP/Reference/Headers/Permissions-Policy/screen-wake-lock +/en-US/docs/Web/HTTP/Headers/Permissions-Policy/serial /en-US/docs/Web/HTTP/Reference/Headers/Permissions-Policy/serial +/en-US/docs/Web/HTTP/Headers/Permissions-Policy/speaker-selection /en-US/docs/Web/HTTP/Reference/Headers/Permissions-Policy/speaker-selection +/en-US/docs/Web/HTTP/Headers/Permissions-Policy/storage-access /en-US/docs/Web/HTTP/Reference/Headers/Permissions-Policy/storage-access +/en-US/docs/Web/HTTP/Headers/Permissions-Policy/sync-xhr /en-US/docs/Web/HTTP/Reference/Headers/Permissions-Policy +/en-US/docs/Web/HTTP/Headers/Permissions-Policy/unoptimized-images /en-US/docs/Web/HTTP/Reference/Headers/Permissions-Policy +/en-US/docs/Web/HTTP/Headers/Permissions-Policy/unsized-media /en-US/docs/Web/HTTP/Reference/Headers/Permissions-Policy +/en-US/docs/Web/HTTP/Headers/Permissions-Policy/usb /en-US/docs/Web/HTTP/Reference/Headers/Permissions-Policy/usb +/en-US/docs/Web/HTTP/Headers/Permissions-Policy/web-share /en-US/docs/Web/HTTP/Reference/Headers/Permissions-Policy/web-share +/en-US/docs/Web/HTTP/Headers/Permissions-Policy/window-management /en-US/docs/Web/HTTP/Reference/Headers/Permissions-Policy/window-management +/en-US/docs/Web/HTTP/Headers/Permissions-Policy/xr-spatial-tracking /en-US/docs/Web/HTTP/Reference/Headers/Permissions-Policy/xr-spatial-tracking +/en-US/docs/Web/HTTP/Headers/Pragma /en-US/docs/Web/HTTP/Reference/Headers/Pragma +/en-US/docs/Web/HTTP/Headers/Priority /en-US/docs/Web/HTTP/Reference/Headers/Priority +/en-US/docs/Web/HTTP/Headers/Proxy-Authenticate /en-US/docs/Web/HTTP/Reference/Headers/Proxy-Authenticate +/en-US/docs/Web/HTTP/Headers/Proxy-Authorization /en-US/docs/Web/HTTP/Reference/Headers/Proxy-Authorization +/en-US/docs/Web/HTTP/Headers/Public-Key-Pins /en-US/docs/Web/HTTP/Reference/Headers/Expect-CT +/en-US/docs/Web/HTTP/Headers/Public-Key-Pins-Report-Only /en-US/docs/Web/HTTP/Reference/Headers/Expect-CT +/en-US/docs/Web/HTTP/Headers/RTT /en-US/docs/Web/HTTP/Reference/Headers/RTT +/en-US/docs/Web/HTTP/Headers/Range /en-US/docs/Web/HTTP/Reference/Headers/Range +/en-US/docs/Web/HTTP/Headers/Ranges /en-US/docs/Web/HTTP/Reference/Headers/Range +/en-US/docs/Web/HTTP/Headers/Referer /en-US/docs/Web/HTTP/Reference/Headers/Referer +/en-US/docs/Web/HTTP/Headers/Referrer-Policy /en-US/docs/Web/HTTP/Reference/Headers/Referrer-Policy +/en-US/docs/Web/HTTP/Headers/Refresh /en-US/docs/Web/HTTP/Reference/Headers/Refresh +/en-US/docs/Web/HTTP/Headers/Report-To /en-US/docs/Web/HTTP/Reference/Headers/Report-To +/en-US/docs/Web/HTTP/Headers/Reporting-Endpoints /en-US/docs/Web/HTTP/Reference/Headers/Reporting-Endpoints +/en-US/docs/Web/HTTP/Headers/Repr-Digest /en-US/docs/Web/HTTP/Reference/Headers/Repr-Digest +/en-US/docs/Web/HTTP/Headers/Retry-After /en-US/docs/Web/HTTP/Reference/Headers/Retry-After +/en-US/docs/Web/HTTP/Headers/Save-Data /en-US/docs/Web/HTTP/Reference/Headers/Save-Data +/en-US/docs/Web/HTTP/Headers/Sec-Browsing-Topics /en-US/docs/Web/HTTP/Reference/Headers/Sec-Browsing-Topics +/en-US/docs/Web/HTTP/Headers/Sec-CH-Prefers-Color-Scheme /en-US/docs/Web/HTTP/Reference/Headers/Sec-CH-Prefers-Color-Scheme +/en-US/docs/Web/HTTP/Headers/Sec-CH-Prefers-Reduced-Motion /en-US/docs/Web/HTTP/Reference/Headers/Sec-CH-Prefers-Reduced-Motion +/en-US/docs/Web/HTTP/Headers/Sec-CH-Prefers-Reduced-Transparency /en-US/docs/Web/HTTP/Reference/Headers/Sec-CH-Prefers-Reduced-Transparency +/en-US/docs/Web/HTTP/Headers/Sec-CH-UA /en-US/docs/Web/HTTP/Reference/Headers/Sec-CH-UA +/en-US/docs/Web/HTTP/Headers/Sec-CH-UA-Arch /en-US/docs/Web/HTTP/Reference/Headers/Sec-CH-UA-Arch +/en-US/docs/Web/HTTP/Headers/Sec-CH-UA-Bitness /en-US/docs/Web/HTTP/Reference/Headers/Sec-CH-UA-Bitness +/en-US/docs/Web/HTTP/Headers/Sec-CH-UA-Form-Factors /en-US/docs/Web/HTTP/Reference/Headers/Sec-CH-UA-Form-Factors +/en-US/docs/Web/HTTP/Headers/Sec-CH-UA-Full-Version /en-US/docs/Web/HTTP/Reference/Headers/Sec-CH-UA-Full-Version +/en-US/docs/Web/HTTP/Headers/Sec-CH-UA-Full-Version-List /en-US/docs/Web/HTTP/Reference/Headers/Sec-CH-UA-Full-Version-List +/en-US/docs/Web/HTTP/Headers/Sec-CH-UA-Mobile /en-US/docs/Web/HTTP/Reference/Headers/Sec-CH-UA-Mobile +/en-US/docs/Web/HTTP/Headers/Sec-CH-UA-Model /en-US/docs/Web/HTTP/Reference/Headers/Sec-CH-UA-Model +/en-US/docs/Web/HTTP/Headers/Sec-CH-UA-Platform /en-US/docs/Web/HTTP/Reference/Headers/Sec-CH-UA-Platform +/en-US/docs/Web/HTTP/Headers/Sec-CH-UA-Platform-Version /en-US/docs/Web/HTTP/Reference/Headers/Sec-CH-UA-Platform-Version +/en-US/docs/Web/HTTP/Headers/Sec-CH-UA-WoW64 /en-US/docs/Web/HTTP/Reference/Headers/Sec-CH-UA-WoW64 +/en-US/docs/Web/HTTP/Headers/Sec-Fetch-Dest /en-US/docs/Web/HTTP/Reference/Headers/Sec-Fetch-Dest +/en-US/docs/Web/HTTP/Headers/Sec-Fetch-Mode /en-US/docs/Web/HTTP/Reference/Headers/Sec-Fetch-Mode +/en-US/docs/Web/HTTP/Headers/Sec-Fetch-Site /en-US/docs/Web/HTTP/Reference/Headers/Sec-Fetch-Site +/en-US/docs/Web/HTTP/Headers/Sec-Fetch-User /en-US/docs/Web/HTTP/Reference/Headers/Sec-Fetch-User +/en-US/docs/Web/HTTP/Headers/Sec-GPC /en-US/docs/Web/HTTP/Reference/Headers/Sec-GPC +/en-US/docs/Web/HTTP/Headers/Sec-Purpose /en-US/docs/Web/HTTP/Reference/Headers/Sec-Purpose +/en-US/docs/Web/HTTP/Headers/Sec-WebSocket-Accept /en-US/docs/Web/HTTP/Reference/Headers/Sec-WebSocket-Accept +/en-US/docs/Web/HTTP/Headers/Sec-WebSocket-Extensions /en-US/docs/Web/HTTP/Reference/Headers/Sec-WebSocket-Extensions +/en-US/docs/Web/HTTP/Headers/Sec-WebSocket-Key /en-US/docs/Web/HTTP/Reference/Headers/Sec-WebSocket-Key +/en-US/docs/Web/HTTP/Headers/Sec-WebSocket-Protocol /en-US/docs/Web/HTTP/Reference/Headers/Sec-WebSocket-Protocol +/en-US/docs/Web/HTTP/Headers/Sec-WebSocket-Version /en-US/docs/Web/HTTP/Reference/Headers/Sec-WebSocket-Version +/en-US/docs/Web/HTTP/Headers/Server /en-US/docs/Web/HTTP/Reference/Headers/Server +/en-US/docs/Web/HTTP/Headers/Server-Timing /en-US/docs/Web/HTTP/Reference/Headers/Server-Timing +/en-US/docs/Web/HTTP/Headers/Service-Worker /en-US/docs/Web/HTTP/Reference/Headers/Service-Worker +/en-US/docs/Web/HTTP/Headers/Service-Worker-Allowed /en-US/docs/Web/HTTP/Reference/Headers/Service-Worker-Allowed +/en-US/docs/Web/HTTP/Headers/Service-Worker-Navigation-Preload /en-US/docs/Web/HTTP/Reference/Headers/Service-Worker-Navigation-Preload +/en-US/docs/Web/HTTP/Headers/Set-Cookie /en-US/docs/Web/HTTP/Reference/Headers/Set-Cookie +/en-US/docs/Web/HTTP/Headers/Set-Cookie/SameSite /en-US/docs/Web/HTTP/Reference/Headers/Set-Cookie#samesitesamesite-value +/en-US/docs/Web/HTTP/Headers/Set-Cookie2 /en-US/docs/Web/HTTP/Reference/Headers/Set-Cookie +/en-US/docs/Web/HTTP/Headers/Set-Login /en-US/docs/Web/HTTP/Reference/Headers/Set-Login +/en-US/docs/Web/HTTP/Headers/SourceMap /en-US/docs/Web/HTTP/Reference/Headers/SourceMap +/en-US/docs/Web/HTTP/Headers/Speculation-Rules /en-US/docs/Web/HTTP/Reference/Headers/Speculation-Rules +/en-US/docs/Web/HTTP/Headers/Strict-Transport-Security /en-US/docs/Web/HTTP/Reference/Headers/Strict-Transport-Security +/en-US/docs/Web/HTTP/Headers/Supports-Loading-Mode /en-US/docs/Web/HTTP/Reference/Headers/Supports-Loading-Mode +/en-US/docs/Web/HTTP/Headers/TE /en-US/docs/Web/HTTP/Reference/Headers/TE +/en-US/docs/Web/HTTP/Headers/Timing-Allow-Origin /en-US/docs/Web/HTTP/Reference/Headers/Timing-Allow-Origin +/en-US/docs/Web/HTTP/Headers/Tk /en-US/docs/Web/HTTP/Reference/Headers/Tk +/en-US/docs/Web/HTTP/Headers/Trailer /en-US/docs/Web/HTTP/Reference/Headers/Trailer +/en-US/docs/Web/HTTP/Headers/Transfer-Encoding /en-US/docs/Web/HTTP/Reference/Headers/Transfer-Encoding +/en-US/docs/Web/HTTP/Headers/Upgrade /en-US/docs/Web/HTTP/Reference/Headers/Upgrade +/en-US/docs/Web/HTTP/Headers/Upgrade-Insecure-Requests /en-US/docs/Web/HTTP/Reference/Headers/Upgrade-Insecure-Requests +/en-US/docs/Web/HTTP/Headers/User-Agent /en-US/docs/Web/HTTP/Reference/Headers/User-Agent +/en-US/docs/Web/HTTP/Headers/User-Agent/Firefox /en-US/docs/Web/HTTP/Reference/Headers/User-Agent/Firefox +/en-US/docs/Web/HTTP/Headers/Vary /en-US/docs/Web/HTTP/Reference/Headers/Vary +/en-US/docs/Web/HTTP/Headers/Via /en-US/docs/Web/HTTP/Reference/Headers/Via +/en-US/docs/Web/HTTP/Headers/Viewport-Width /en-US/docs/Web/HTTP/Reference/Headers/Viewport-Width +/en-US/docs/Web/HTTP/Headers/WWW-Authenticate /en-US/docs/Web/HTTP/Reference/Headers/WWW-Authenticate +/en-US/docs/Web/HTTP/Headers/Want-Content-Digest /en-US/docs/Web/HTTP/Reference/Headers/Want-Content-Digest +/en-US/docs/Web/HTTP/Headers/Want-Digest /en-US/docs/Web/HTTP/Reference/Headers/Want-Content-Digest +/en-US/docs/Web/HTTP/Headers/Want-Repr-Digest /en-US/docs/Web/HTTP/Reference/Headers/Want-Repr-Digest +/en-US/docs/Web/HTTP/Headers/Warning /en-US/docs/Web/HTTP/Reference/Headers/Warning +/en-US/docs/Web/HTTP/Headers/Width /en-US/docs/Web/HTTP/Reference/Headers/Width +/en-US/docs/Web/HTTP/Headers/X-Content-Type-Options /en-US/docs/Web/HTTP/Reference/Headers/X-Content-Type-Options +/en-US/docs/Web/HTTP/Headers/X-DNS-Prefetch-Control /en-US/docs/Web/HTTP/Reference/Headers/X-DNS-Prefetch-Control +/en-US/docs/Web/HTTP/Headers/X-Forwarded-For /en-US/docs/Web/HTTP/Reference/Headers/X-Forwarded-For +/en-US/docs/Web/HTTP/Headers/X-Forwarded-Host /en-US/docs/Web/HTTP/Reference/Headers/X-Forwarded-Host +/en-US/docs/Web/HTTP/Headers/X-Forwarded-Proto /en-US/docs/Web/HTTP/Reference/Headers/X-Forwarded-Proto +/en-US/docs/Web/HTTP/Headers/X-Frame-Options /en-US/docs/Web/HTTP/Reference/Headers/X-Frame-Options +/en-US/docs/Web/HTTP/Headers/X-Permitted-Cross-Domain-Policies /en-US/docs/Web/HTTP/Reference/Headers/X-Permitted-Cross-Domain-Policies +/en-US/docs/Web/HTTP/Headers/X-Powered-By /en-US/docs/Web/HTTP/Reference/Headers/X-Powered-By +/en-US/docs/Web/HTTP/Headers/X-Robots-Tag /en-US/docs/Web/HTTP/Reference/Headers/X-Robots-Tag +/en-US/docs/Web/HTTP/Headers/X-XSS-Protection /en-US/docs/Web/HTTP/Reference/Headers/X-XSS-Protection +/en-US/docs/Web/HTTP/History_of_HTTP_versions /en-US/docs/Web/HTTP/Guides/Evolution_of_HTTP /en-US/docs/Web/HTTP/Index /en-US/docs/Web/HTTP /en-US/docs/Web/HTTP/Link_prefetching_FAQ /en-US/docs/Glossary/Prefetch -/en-US/docs/Web/HTTP/Pipelining_FAQ /en-US/docs/Web/HTTP/Connection_management_in_HTTP_1.x -/en-US/docs/Web/HTTP/Proxy_servers_and_tunneling/Proxy_Auto-Configuration_(PAC)_file /en-US/docs/Web/HTTP/Proxy_servers_and_tunneling/Proxy_Auto-Configuration_PAC_file +/en-US/docs/Web/HTTP/MIME_types /en-US/docs/Web/HTTP/Guides/MIME_types +/en-US/docs/Web/HTTP/MIME_types/Common_types /en-US/docs/Web/HTTP/Guides/MIME_types/Common_types +/en-US/docs/Web/HTTP/Messages /en-US/docs/Web/HTTP/Guides/Messages +/en-US/docs/Web/HTTP/Methods /en-US/docs/Web/HTTP/Reference/Methods +/en-US/docs/Web/HTTP/Methods/CONNECT /en-US/docs/Web/HTTP/Reference/Methods/CONNECT +/en-US/docs/Web/HTTP/Methods/DELETE /en-US/docs/Web/HTTP/Reference/Methods/DELETE +/en-US/docs/Web/HTTP/Methods/GET /en-US/docs/Web/HTTP/Reference/Methods/GET +/en-US/docs/Web/HTTP/Methods/HEAD /en-US/docs/Web/HTTP/Reference/Methods/HEAD +/en-US/docs/Web/HTTP/Methods/OPTIONS /en-US/docs/Web/HTTP/Reference/Methods/OPTIONS +/en-US/docs/Web/HTTP/Methods/PATCH /en-US/docs/Web/HTTP/Reference/Methods/PATCH +/en-US/docs/Web/HTTP/Methods/POST /en-US/docs/Web/HTTP/Reference/Methods/POST +/en-US/docs/Web/HTTP/Methods/PUT /en-US/docs/Web/HTTP/Reference/Methods/PUT +/en-US/docs/Web/HTTP/Methods/TRACE /en-US/docs/Web/HTTP/Reference/Methods/TRACE +/en-US/docs/Web/HTTP/Network_Error_Logging /en-US/docs/Web/HTTP/Guides/Network_Error_Logging +/en-US/docs/Web/HTTP/Overview /en-US/docs/Web/HTTP/Guides/Overview +/en-US/docs/Web/HTTP/Permissions_Policy /en-US/docs/Web/HTTP/Guides/Permissions_Policy +/en-US/docs/Web/HTTP/Pipelining_FAQ /en-US/docs/Web/HTTP/Guides/Connection_management_in_HTTP_1.x +/en-US/docs/Web/HTTP/Protocol_upgrade_mechanism /en-US/docs/Web/HTTP/Guides/Protocol_upgrade_mechanism +/en-US/docs/Web/HTTP/Proxy_servers_and_tunneling /en-US/docs/Web/HTTP/Guides/Proxy_servers_and_tunneling +/en-US/docs/Web/HTTP/Proxy_servers_and_tunneling/Proxy_Auto-Configuration_(PAC)_file /en-US/docs/Web/HTTP/Guides/Proxy_servers_and_tunneling/Proxy_Auto-Configuration_PAC_file +/en-US/docs/Web/HTTP/Proxy_servers_and_tunneling/Proxy_Auto-Configuration_PAC_file /en-US/docs/Web/HTTP/Guides/Proxy_servers_and_tunneling/Proxy_Auto-Configuration_PAC_file /en-US/docs/Web/HTTP/Public_Key_Pinning /en-US/docs/Web/Security/Certificate_Transparency -/en-US/docs/Web/HTTP/Resources_and_URIs /en-US/docs/Web/HTTP/MIME_types -/en-US/docs/Web/HTTP/Response_codes /en-US/docs/Web/HTTP/Status -/en-US/docs/Web/HTTP/Server-Side_Access_Control /en-US/docs/Web/HTTP/CORS -/en-US/docs/Web/HTTP/Status/416_Range_Not_Satisfiable /en-US/docs/Web/HTTP/Status/416 -/en-US/docs/Web/HTTP/Status/418_I_m_a_teapot /en-US/docs/Web/HTTP/Status/418 -/en-US/docs/Web/HTTP/Status/506_Variant_Also_Negotiates /en-US/docs/Web/HTTP/Status/506 -/en-US/docs/Web/HTTP/Status/510_Not_Extended /en-US/docs/Web/HTTP/Status/510 -/en-US/docs/Web/HTTP/X-Frame-Options /en-US/docs/Web/HTTP/Headers/X-Frame-Options +/en-US/docs/Web/HTTP/Range_requests /en-US/docs/Web/HTTP/Guides/Range_requests +/en-US/docs/Web/HTTP/Redirections /en-US/docs/Web/HTTP/Guides/Redirections +/en-US/docs/Web/HTTP/Reference/Headers/Permissions-Policy/document-domain /en-US/docs/Web/HTTP/Reference/Headers/Permissions-Policy +/en-US/docs/Web/HTTP/Resources_and_URIs /en-US/docs/Web/HTTP/Guides/MIME_types +/en-US/docs/Web/HTTP/Resources_and_specifications /en-US/docs/Web/HTTP/Reference/Resources_and_specifications +/en-US/docs/Web/HTTP/Response_codes /en-US/docs/Web/HTTP/Reference/Status +/en-US/docs/Web/HTTP/Server-Side_Access_Control /en-US/docs/Web/HTTP/Guides/CORS +/en-US/docs/Web/HTTP/Session /en-US/docs/Web/HTTP/Guides/Session +/en-US/docs/Web/HTTP/Status /en-US/docs/Web/HTTP/Reference/Status +/en-US/docs/Web/HTTP/Status/100 /en-US/docs/Web/HTTP/Reference/Status/100 +/en-US/docs/Web/HTTP/Status/101 /en-US/docs/Web/HTTP/Reference/Status/101 +/en-US/docs/Web/HTTP/Status/102 /en-US/docs/Web/HTTP/Reference/Status/102 +/en-US/docs/Web/HTTP/Status/103 /en-US/docs/Web/HTTP/Reference/Status/103 +/en-US/docs/Web/HTTP/Status/200 /en-US/docs/Web/HTTP/Reference/Status/200 +/en-US/docs/Web/HTTP/Status/201 /en-US/docs/Web/HTTP/Reference/Status/201 +/en-US/docs/Web/HTTP/Status/202 /en-US/docs/Web/HTTP/Reference/Status/202 +/en-US/docs/Web/HTTP/Status/203 /en-US/docs/Web/HTTP/Reference/Status/203 +/en-US/docs/Web/HTTP/Status/204 /en-US/docs/Web/HTTP/Reference/Status/204 +/en-US/docs/Web/HTTP/Status/205 /en-US/docs/Web/HTTP/Reference/Status/205 +/en-US/docs/Web/HTTP/Status/206 /en-US/docs/Web/HTTP/Reference/Status/206 +/en-US/docs/Web/HTTP/Status/207 /en-US/docs/Web/HTTP/Reference/Status/207 +/en-US/docs/Web/HTTP/Status/208 /en-US/docs/Web/HTTP/Reference/Status/208 +/en-US/docs/Web/HTTP/Status/226 /en-US/docs/Web/HTTP/Reference/Status/226 +/en-US/docs/Web/HTTP/Status/300 /en-US/docs/Web/HTTP/Reference/Status/300 +/en-US/docs/Web/HTTP/Status/301 /en-US/docs/Web/HTTP/Reference/Status/301 +/en-US/docs/Web/HTTP/Status/302 /en-US/docs/Web/HTTP/Reference/Status/302 +/en-US/docs/Web/HTTP/Status/303 /en-US/docs/Web/HTTP/Reference/Status/303 +/en-US/docs/Web/HTTP/Status/304 /en-US/docs/Web/HTTP/Reference/Status/304 +/en-US/docs/Web/HTTP/Status/307 /en-US/docs/Web/HTTP/Reference/Status/307 +/en-US/docs/Web/HTTP/Status/308 /en-US/docs/Web/HTTP/Reference/Status/308 +/en-US/docs/Web/HTTP/Status/400 /en-US/docs/Web/HTTP/Reference/Status/400 +/en-US/docs/Web/HTTP/Status/401 /en-US/docs/Web/HTTP/Reference/Status/401 +/en-US/docs/Web/HTTP/Status/402 /en-US/docs/Web/HTTP/Reference/Status/402 +/en-US/docs/Web/HTTP/Status/403 /en-US/docs/Web/HTTP/Reference/Status/403 +/en-US/docs/Web/HTTP/Status/404 /en-US/docs/Web/HTTP/Reference/Status/404 +/en-US/docs/Web/HTTP/Status/405 /en-US/docs/Web/HTTP/Reference/Status/405 +/en-US/docs/Web/HTTP/Status/406 /en-US/docs/Web/HTTP/Reference/Status/406 +/en-US/docs/Web/HTTP/Status/407 /en-US/docs/Web/HTTP/Reference/Status/407 +/en-US/docs/Web/HTTP/Status/408 /en-US/docs/Web/HTTP/Reference/Status/408 +/en-US/docs/Web/HTTP/Status/409 /en-US/docs/Web/HTTP/Reference/Status/409 +/en-US/docs/Web/HTTP/Status/410 /en-US/docs/Web/HTTP/Reference/Status/410 +/en-US/docs/Web/HTTP/Status/411 /en-US/docs/Web/HTTP/Reference/Status/411 +/en-US/docs/Web/HTTP/Status/412 /en-US/docs/Web/HTTP/Reference/Status/412 +/en-US/docs/Web/HTTP/Status/413 /en-US/docs/Web/HTTP/Reference/Status/413 +/en-US/docs/Web/HTTP/Status/414 /en-US/docs/Web/HTTP/Reference/Status/414 +/en-US/docs/Web/HTTP/Status/415 /en-US/docs/Web/HTTP/Reference/Status/415 +/en-US/docs/Web/HTTP/Status/416 /en-US/docs/Web/HTTP/Reference/Status/416 +/en-US/docs/Web/HTTP/Status/416_Range_Not_Satisfiable /en-US/docs/Web/HTTP/Reference/Status/416 +/en-US/docs/Web/HTTP/Status/417 /en-US/docs/Web/HTTP/Reference/Status/417 +/en-US/docs/Web/HTTP/Status/418 /en-US/docs/Web/HTTP/Reference/Status/418 +/en-US/docs/Web/HTTP/Status/418_I_m_a_teapot /en-US/docs/Web/HTTP/Reference/Status/418 +/en-US/docs/Web/HTTP/Status/421 /en-US/docs/Web/HTTP/Reference/Status/421 +/en-US/docs/Web/HTTP/Status/422 /en-US/docs/Web/HTTP/Reference/Status/422 +/en-US/docs/Web/HTTP/Status/423 /en-US/docs/Web/HTTP/Reference/Status/423 +/en-US/docs/Web/HTTP/Status/424 /en-US/docs/Web/HTTP/Reference/Status/424 +/en-US/docs/Web/HTTP/Status/425 /en-US/docs/Web/HTTP/Reference/Status/425 +/en-US/docs/Web/HTTP/Status/426 /en-US/docs/Web/HTTP/Reference/Status/426 +/en-US/docs/Web/HTTP/Status/428 /en-US/docs/Web/HTTP/Reference/Status/428 +/en-US/docs/Web/HTTP/Status/429 /en-US/docs/Web/HTTP/Reference/Status/429 +/en-US/docs/Web/HTTP/Status/431 /en-US/docs/Web/HTTP/Reference/Status/431 +/en-US/docs/Web/HTTP/Status/451 /en-US/docs/Web/HTTP/Reference/Status/451 +/en-US/docs/Web/HTTP/Status/500 /en-US/docs/Web/HTTP/Reference/Status/500 +/en-US/docs/Web/HTTP/Status/501 /en-US/docs/Web/HTTP/Reference/Status/501 +/en-US/docs/Web/HTTP/Status/502 /en-US/docs/Web/HTTP/Reference/Status/502 +/en-US/docs/Web/HTTP/Status/503 /en-US/docs/Web/HTTP/Reference/Status/503 +/en-US/docs/Web/HTTP/Status/504 /en-US/docs/Web/HTTP/Reference/Status/504 +/en-US/docs/Web/HTTP/Status/505 /en-US/docs/Web/HTTP/Reference/Status/505 +/en-US/docs/Web/HTTP/Status/506 /en-US/docs/Web/HTTP/Reference/Status/506 +/en-US/docs/Web/HTTP/Status/506_Variant_Also_Negotiates /en-US/docs/Web/HTTP/Reference/Status/506 +/en-US/docs/Web/HTTP/Status/507 /en-US/docs/Web/HTTP/Reference/Status/507 +/en-US/docs/Web/HTTP/Status/508 /en-US/docs/Web/HTTP/Reference/Status/508 +/en-US/docs/Web/HTTP/Status/510 /en-US/docs/Web/HTTP/Reference/Status/510 +/en-US/docs/Web/HTTP/Status/510_Not_Extended /en-US/docs/Web/HTTP/Reference/Status/510 +/en-US/docs/Web/HTTP/Status/511 /en-US/docs/Web/HTTP/Reference/Status/511 +/en-US/docs/Web/HTTP/X-Frame-Options /en-US/docs/Web/HTTP/Reference/Headers/X-Frame-Options /en-US/docs/Web/HTTP/data_URIs /en-US/docs/Web/URI/Reference/Schemes/data /en-US/docs/Web/HTTP/www_and_non-www_URLs /en-US/docs/Web/URI/Guides/Choosing_between_www_and_non-www_URLs /en-US/docs/Web/Houdini /en-US/docs/Web/API/Houdini_APIs @@ -12862,27 +13713,30 @@ /en-US/docs/Web/Houdini/Learn/CSS_Painting_API /en-US/docs/Web/API/CSS_Painting_API/Guide /en-US/docs/Web/Houdini/learn/CSS_Typed_OM /en-US/docs/Web/API/CSS_Typed_OM_API/Guide /en-US/docs/Web/Houdini/learn/Houdini:_CSS_Painting_API /en-US/docs/Web/API/CSS_Painting_API/Guide -/en-US/docs/Web/JavaScript/A_re-introduction_to_JavaScript /en-US/docs/Web/JavaScript/Language_overview +/en-US/docs/Web/JavaScript/A_re-introduction_to_JavaScript /en-US/docs/Web/JavaScript/Guide/Language_overview /en-US/docs/Web/JavaScript/About_JavaScript /en-US/docs/Web/JavaScript /en-US/docs/Web/JavaScript/Base64_encoding_and_decoding /en-US/docs/Glossary/Base64 +/en-US/docs/Web/JavaScript/Closures /en-US/docs/Web/JavaScript/Guide/Closures +/en-US/docs/Web/JavaScript/Data_structures /en-US/docs/Web/JavaScript/Guide/Data_structures /en-US/docs/Web/JavaScript/DedicatedWorkerGlobalScope /en-US/docs/Web/API/DedicatedWorkerGlobalScope -/en-US/docs/Web/JavaScript/Equality_comparisons_and_when_to_use_them /en-US/docs/Web/JavaScript/Equality_comparisons_and_sameness -/en-US/docs/Web/JavaScript/EventLoop /en-US/docs/Web/JavaScript/Event_loop +/en-US/docs/Web/JavaScript/Enumerability_and_ownership_of_properties /en-US/docs/Web/JavaScript/Guide/Enumerability_and_ownership_of_properties +/en-US/docs/Web/JavaScript/Equality_comparisons_and_sameness /en-US/docs/Web/JavaScript/Guide/Equality_comparisons_and_sameness +/en-US/docs/Web/JavaScript/Equality_comparisons_and_when_to_use_them /en-US/docs/Web/JavaScript/Guide/Equality_comparisons_and_sameness +/en-US/docs/Web/JavaScript/EventLoop /en-US/docs/Web/JavaScript/Reference/Execution_model +/en-US/docs/Web/JavaScript/Event_loop /en-US/docs/Web/JavaScript/Reference/Execution_model /en-US/docs/Web/JavaScript/Getting_Started /en-US/docs/Learn_web_development/Getting_started/Your_first_website/Adding_interactivity /en-US/docs/Web/JavaScript/Glossary /en-US/docs/Glossary /en-US/docs/Web/JavaScript/Guide/About /en-US/docs/Web/JavaScript/Guide/Introduction -/en-US/docs/Web/JavaScript/Guide/Closures /en-US/docs/Web/JavaScript/Closures -/en-US/docs/Web/JavaScript/Guide/Details_of_the_Object_Model /en-US/docs/Web/JavaScript/Inheritance_and_the_prototype_chain -/en-US/docs/Web/JavaScript/Guide/Equality_comparisons_and_when_to_use_them /en-US/docs/Web/JavaScript/Equality_comparisons_and_sameness -/en-US/docs/Web/JavaScript/Guide/EventLoop /en-US/docs/Web/JavaScript/Event_loop -/en-US/docs/Web/JavaScript/Guide/Inheritance_Revisited /en-US/docs/Web/JavaScript/Inheritance_and_the_prototype_chain -/en-US/docs/Web/JavaScript/Guide/Inheritance_and_the_prototype_chain /en-US/docs/Web/JavaScript/Inheritance_and_the_prototype_chain +/en-US/docs/Web/JavaScript/Guide/Details_of_the_Object_Model /en-US/docs/Web/JavaScript/Guide/Inheritance_and_the_prototype_chain +/en-US/docs/Web/JavaScript/Guide/Equality_comparisons_and_when_to_use_them /en-US/docs/Web/JavaScript/Guide/Equality_comparisons_and_sameness +/en-US/docs/Web/JavaScript/Guide/EventLoop /en-US/docs/Web/JavaScript/Reference/Execution_model +/en-US/docs/Web/JavaScript/Guide/Inheritance_Revisited /en-US/docs/Web/JavaScript/Guide/Inheritance_and_the_prototype_chain /en-US/docs/Web/JavaScript/Guide/JavaScript_Overview /en-US/docs/Web/JavaScript/Guide/Introduction /en-US/docs/Web/JavaScript/Guide/Numbers_and_dates /en-US/docs/Web/JavaScript/Guide/Numbers_and_strings /en-US/docs/Web/JavaScript/Guide/Obsolete_Pages /en-US/docs/Web/JavaScript/Guide /en-US/docs/Web/JavaScript/Guide/Obsolete_Pages/Block_Statement /en-US/docs/Web/JavaScript/Guide/Control_flow_and_error_handling /en-US/docs/Web/JavaScript/Guide/Obsolete_Pages/Calling_Functions /en-US/docs/Web/JavaScript/Guide/Functions -/en-US/docs/Web/JavaScript/Guide/Obsolete_Pages/Class-Based_vs._Prototype-Based_Languages /en-US/docs/Web/JavaScript/Inheritance_and_the_prototype_chain +/en-US/docs/Web/JavaScript/Guide/Obsolete_Pages/Class-Based_vs._Prototype-Based_Languages /en-US/docs/Web/JavaScript/Guide/Inheritance_and_the_prototype_chain /en-US/docs/Web/JavaScript/Guide/Obsolete_Pages/Comments /en-US/docs/Web/JavaScript/Guide/Control_flow_and_error_handling /en-US/docs/Web/JavaScript/Guide/Obsolete_Pages/Conditional_Statements /en-US/docs/Web/JavaScript/Guide/Control_flow_and_error_handling /en-US/docs/Web/JavaScript/Guide/Obsolete_Pages/Constants /en-US/docs/Web/JavaScript/Guide/Grammar_and_types @@ -12935,19 +13789,19 @@ /en-US/docs/Web/JavaScript/Guide/Obsolete_Pages/Predefined_Functions/isFinite_Function /en-US/docs/Web/JavaScript/Guide/Functions /en-US/docs/Web/JavaScript/Guide/Obsolete_Pages/Predefined_Functions/isNaN_Function /en-US/docs/Web/JavaScript/Guide/Functions /en-US/docs/Web/JavaScript/Guide/Obsolete_Pages/Predefined_Functions/parseInt_and_parseFloat_Functions /en-US/docs/Web/JavaScript/Guide/Functions -/en-US/docs/Web/JavaScript/Guide/Obsolete_Pages/Property_Inheritance_Revisited /en-US/docs/Web/JavaScript/Inheritance_and_the_prototype_chain -/en-US/docs/Web/JavaScript/Guide/Obsolete_Pages/Property_Inheritance_Revisited/Determining_Instance_Relationships /en-US/docs/Web/JavaScript/Inheritance_and_the_prototype_chain -/en-US/docs/Web/JavaScript/Guide/Obsolete_Pages/Property_Inheritance_Revisited/Global_Information_in_Constructors /en-US/docs/Web/JavaScript/Inheritance_and_the_prototype_chain -/en-US/docs/Web/JavaScript/Guide/Obsolete_Pages/Property_Inheritance_Revisited/Local_versus_Inherited_Values /en-US/docs/Web/JavaScript/Inheritance_and_the_prototype_chain -/en-US/docs/Web/JavaScript/Guide/Obsolete_Pages/Property_Inheritance_Revisited/No_Multiple_Inheritance /en-US/docs/Web/JavaScript/Inheritance_and_the_prototype_chain +/en-US/docs/Web/JavaScript/Guide/Obsolete_Pages/Property_Inheritance_Revisited /en-US/docs/Web/JavaScript/Guide/Inheritance_and_the_prototype_chain +/en-US/docs/Web/JavaScript/Guide/Obsolete_Pages/Property_Inheritance_Revisited/Determining_Instance_Relationships /en-US/docs/Web/JavaScript/Guide/Inheritance_and_the_prototype_chain +/en-US/docs/Web/JavaScript/Guide/Obsolete_Pages/Property_Inheritance_Revisited/Global_Information_in_Constructors /en-US/docs/Web/JavaScript/Guide/Inheritance_and_the_prototype_chain +/en-US/docs/Web/JavaScript/Guide/Obsolete_Pages/Property_Inheritance_Revisited/Local_versus_Inherited_Values /en-US/docs/Web/JavaScript/Guide/Inheritance_and_the_prototype_chain +/en-US/docs/Web/JavaScript/Guide/Obsolete_Pages/Property_Inheritance_Revisited/No_Multiple_Inheritance /en-US/docs/Web/JavaScript/Guide/Inheritance_and_the_prototype_chain /en-US/docs/Web/JavaScript/Guide/Obsolete_Pages/Table_of_Contents_1.0 /en-US/docs/Web/JavaScript/Guide /en-US/docs/Web/JavaScript/Guide/Obsolete_Pages/Table_of_Contents_2.0 /en-US/docs/Web/JavaScript/Guide -/en-US/docs/Web/JavaScript/Guide/Obsolete_Pages/The_Employee_Example /en-US/docs/Web/JavaScript/Inheritance_and_the_prototype_chain -/en-US/docs/Web/JavaScript/Guide/Obsolete_Pages/The_Employee_Example/Creating_the_Hierarchy /en-US/docs/Web/JavaScript/Inheritance_and_the_prototype_chain -/en-US/docs/Web/JavaScript/Guide/Obsolete_Pages/The_Employee_Example/More_Flexible_Constructors /en-US/docs/Web/JavaScript/Inheritance_and_the_prototype_chain -/en-US/docs/Web/JavaScript/Guide/Obsolete_Pages/The_Employee_Example/Object_Properties /en-US/docs/Web/JavaScript/Inheritance_and_the_prototype_chain -/en-US/docs/Web/JavaScript/Guide/Obsolete_Pages/The_Employee_Example/Object_Properties/Adding_Properties /en-US/docs/Web/JavaScript/Inheritance_and_the_prototype_chain -/en-US/docs/Web/JavaScript/Guide/Obsolete_Pages/The_Employee_Example/Object_Properties/Inheriting_Properties /en-US/docs/Web/JavaScript/Inheritance_and_the_prototype_chain +/en-US/docs/Web/JavaScript/Guide/Obsolete_Pages/The_Employee_Example /en-US/docs/Web/JavaScript/Guide/Inheritance_and_the_prototype_chain +/en-US/docs/Web/JavaScript/Guide/Obsolete_Pages/The_Employee_Example/Creating_the_Hierarchy /en-US/docs/Web/JavaScript/Guide/Inheritance_and_the_prototype_chain +/en-US/docs/Web/JavaScript/Guide/Obsolete_Pages/The_Employee_Example/More_Flexible_Constructors /en-US/docs/Web/JavaScript/Guide/Inheritance_and_the_prototype_chain +/en-US/docs/Web/JavaScript/Guide/Obsolete_Pages/The_Employee_Example/Object_Properties /en-US/docs/Web/JavaScript/Guide/Inheritance_and_the_prototype_chain +/en-US/docs/Web/JavaScript/Guide/Obsolete_Pages/The_Employee_Example/Object_Properties/Adding_Properties /en-US/docs/Web/JavaScript/Guide/Inheritance_and_the_prototype_chain +/en-US/docs/Web/JavaScript/Guide/Obsolete_Pages/The_Employee_Example/Object_Properties/Inheriting_Properties /en-US/docs/Web/JavaScript/Guide/Inheritance_and_the_prototype_chain /en-US/docs/Web/JavaScript/Guide/Obsolete_Pages/Unicode /en-US/docs/Web/JavaScript/Guide/Grammar_and_types /en-US/docs/Web/JavaScript/Guide/Obsolete_Pages/Using_the_arguments_object /en-US/docs/Web/JavaScript/Guide/Functions /en-US/docs/Web/JavaScript/Guide/Obsolete_Pages/Values /en-US/docs/Web/JavaScript/Guide/Grammar_and_types @@ -12962,7 +13816,7 @@ /en-US/docs/Web/JavaScript/Guide/Regular_Expressions/Boundaries /en-US/docs/Web/JavaScript/Guide/Regular_expressions/Assertions /en-US/docs/Web/JavaScript/Guide/Regular_Expressions/Groups_and_Ranges /en-US/docs/Web/JavaScript/Guide/Regular_expressions/Groups_and_backreferences /en-US/docs/Web/JavaScript/Guide/Regular_expressions/Unicode_property_escapes /en-US/docs/Web/JavaScript/Reference/Regular_expressions/Unicode_character_class_escape -/en-US/docs/Web/JavaScript/Guide/Sameness /en-US/docs/Web/JavaScript/Equality_comparisons_and_sameness +/en-US/docs/Web/JavaScript/Guide/Sameness /en-US/docs/Web/JavaScript/Guide/Equality_comparisons_and_sameness /en-US/docs/Web/JavaScript/Guide/Statements /en-US/docs/Web/JavaScript/Guide/Control_flow_and_error_handling /en-US/docs/Web/JavaScript/Guide/Text_formatting /en-US/docs/Web/JavaScript/Guide/Numbers_and_strings /en-US/docs/Web/JavaScript/Guide/The_Iterator_protocol /en-US/docs/Web/JavaScript/Reference/Iteration_protocols @@ -12971,22 +13825,26 @@ /en-US/docs/Web/JavaScript/Guide/Values,_variables,_and_literals /en-US/docs/Web/JavaScript/Guide/Grammar_and_types /en-US/docs/Web/JavaScript/Guide/Working_With_Private_Class_Features /en-US/docs/Web/JavaScript/Guide/Using_classes#private_fields /en-US/docs/Web/JavaScript/Guide/iterable /en-US/docs/Web/JavaScript/Reference/Iteration_protocols +/en-US/docs/Web/JavaScript/Inheritance_and_the_prototype_chain /en-US/docs/Web/JavaScript/Guide/Inheritance_and_the_prototype_chain /en-US/docs/Web/JavaScript/Introduction_to_Object-Oriented_JavaScript /en-US/docs/Learn_web_development/Extensions/Advanced_JavaScript_objects /en-US/docs/Web/JavaScript/Introduction_to_using_XPath_in_JavaScript /en-US/docs/Web/XML/XPath/Guides/Introduction_to_using_XPath_in_JavaScript +/en-US/docs/Web/JavaScript/JavaScript_technologies_overview /en-US/docs/Web/JavaScript/Reference/JavaScript_technologies_overview /en-US/docs/Web/JavaScript/JavaScript_templates /en-US/docs/Web/JavaScript/Reference/Template_literals /en-US/docs/Web/JavaScript/Javascript_How_To_Tutorials /en-US/docs/Web/JavaScript/Guide -/en-US/docs/Web/JavaScript/Language_Resources /en-US/docs/Web/JavaScript/JavaScript_technologies_overview +/en-US/docs/Web/JavaScript/Language_Resources /en-US/docs/Web/JavaScript/Reference/JavaScript_technologies_overview +/en-US/docs/Web/JavaScript/Language_overview /en-US/docs/Web/JavaScript/Guide/Language_overview +/en-US/docs/Web/JavaScript/Memory_management /en-US/docs/Web/JavaScript/Guide/Memory_management /en-US/docs/Web/JavaScript/Microsoft_Extensions/debugger /en-US/docs/Web/JavaScript/Reference/Statements/debugger /en-US/docs/Web/JavaScript/Microsoft_JavaScript_extensions/debugger /en-US/docs/Web/JavaScript/Reference/Statements/debugger /en-US/docs/Web/JavaScript/Other_JavaScript_tools https://firefox-source-docs.mozilla.org/devtools-user/index.html -/en-US/docs/Web/JavaScript/Proxy_Auto-Configuration_(PAC)_file /en-US/docs/Web/HTTP/Proxy_servers_and_tunneling/Proxy_Auto-Configuration_PAC_file +/en-US/docs/Web/JavaScript/Proxy_Auto-Configuration_(PAC)_file /en-US/docs/Web/HTTP/Guides/Proxy_servers_and_tunneling/Proxy_Auto-Configuration_PAC_file /en-US/docs/Web/JavaScript/Reference/About /en-US/docs/Web/JavaScript/Reference /en-US/docs/Web/JavaScript/Reference/Classes/Class_elements /en-US/docs/Web/JavaScript/Reference/Classes/Public_class_fields /en-US/docs/Web/JavaScript/Reference/Classes/Class_fields /en-US/docs/Web/JavaScript/Reference/Classes/Public_class_fields /en-US/docs/Web/JavaScript/Reference/Classes/Class_static_initialization_blocks /en-US/docs/Web/JavaScript/Reference/Classes/Static_initialization_blocks /en-US/docs/Web/JavaScript/Reference/Classes/Private_class_fields /en-US/docs/Web/JavaScript/Reference/Classes/Private_properties /en-US/docs/Web/JavaScript/Reference/Code_comments /en-US/docs/Web/JavaScript/Reference/Lexical_grammar#Comments -/en-US/docs/Web/JavaScript/Reference/Data_types /en-US/docs/Web/JavaScript/Data_structures +/en-US/docs/Web/JavaScript/Reference/Data_types /en-US/docs/Web/JavaScript/Guide/Data_structures /en-US/docs/Web/JavaScript/Reference/Deprecated_and_obsolete_features/The_legacy_Iterator_protocol /en-US/docs/Web/JavaScript/Reference/Deprecated_and_obsolete_features /en-US/docs/Web/JavaScript/Reference/Errors/Bad_octal /en-US/docs/Web/JavaScript/Reference/Errors/Deprecated_octal_literal /en-US/docs/Web/JavaScript/Reference/Errors/Bad_return_or_yield /en-US/docs/Web/JavaScript/Reference/Errors/Bad_return @@ -13257,7 +14115,8 @@ /en-US/docs/Web/JavaScript/Reference/Operators/Assignment_Operators /en-US/docs/Web/JavaScript/Reference/Operators#Assignment_operators /en-US/docs/Web/JavaScript/Reference/Operators/Bitwise_Operators /en-US/docs/Web/JavaScript/Reference/Operators /en-US/docs/Web/JavaScript/Reference/Operators/Comparison_Operators /en-US/docs/Web/JavaScript/Reference/Operators -/en-US/docs/Web/JavaScript/Reference/Operators/Destructing_assignment /en-US/docs/Web/JavaScript/Reference/Operators/Destructuring_assignment +/en-US/docs/Web/JavaScript/Reference/Operators/Destructing_assignment /en-US/docs/Web/JavaScript/Reference/Operators/Destructuring +/en-US/docs/Web/JavaScript/Reference/Operators/Destructuring_assignment /en-US/docs/Web/JavaScript/Reference/Operators/Destructuring /en-US/docs/Web/JavaScript/Reference/Operators/Generator_comprehensions /en-US/docs/Web/JavaScript/Reference/Deprecated_and_obsolete_features /en-US/docs/Web/JavaScript/Reference/Operators/Legacy_generator_function /en-US/docs/Web/JavaScript/Reference/Deprecated_and_obsolete_features /en-US/docs/Web/JavaScript/Reference/Operators/Logical_Operators /en-US/docs/Web/JavaScript/Reference/Operators @@ -13286,7 +14145,7 @@ /en-US/docs/Web/JavaScript/Reference/rest_parameters /en-US/docs/Web/JavaScript/Reference/Functions/rest_parameters /en-US/docs/Web/JavaScript/Reference/template_strings /en-US/docs/Web/JavaScript/Reference/Template_literals /en-US/docs/Web/JavaScript/Same_origin_policy_for_JavaScript /en-US/docs/Web/Security/Same-origin_policy -/en-US/docs/Web/JavaScript/Shells /en-US/docs/Web/JavaScript/JavaScript_technologies_overview +/en-US/docs/Web/JavaScript/Shells /en-US/docs/Web/JavaScript/Reference/JavaScript_technologies_overview /en-US/docs/Web/JavaScript/The_performance_hazards_of__[[Prototype]]_mutation /en-US/docs/Web/JavaScript/Reference/Global_Objects/Object/setPrototypeOf /en-US/docs/Web/JavaScript/The_performance_hazards_of_prototype_mutation /en-US/docs/Web/JavaScript/Reference/Global_Objects/Object/setPrototypeOf /en-US/docs/Web/JavaScript/Tutorials /en-US/docs/Web/JavaScript @@ -13353,12 +14212,74 @@ /en-US/docs/Web/Manifest/shortcuts /en-US/docs/Web/Progressive_web_apps/Manifest/Reference/shortcuts /en-US/docs/Web/Manifest/start_url /en-US/docs/Web/Progressive_web_apps/Manifest/Reference/start_url /en-US/docs/Web/Manifest/theme_color /en-US/docs/Web/Progressive_web_apps/Manifest/Reference/theme_color -/en-US/docs/Web/MathML/Attribute/Values /en-US/docs/Web/MathML/Values -/en-US/docs/Web/MathML/Element/menclosed /en-US/docs/Web/MathML/Element/menclose -/en-US/docs/Web/MathML/Element/none /en-US/docs/Web/MathML/Element/mmultiscripts -/en-US/docs/Web/MathML/Fonts/Test /en-US/docs/Web/MathML/Fonts -/en-US/docs/Web/MathML/Global_attributes/mathvariant /en-US/docs/Web/MathML/Element/mi#mathvariant +/en-US/docs/Web/MathML/Attribute /en-US/docs/Web/MathML/Reference/Attribute +/en-US/docs/Web/MathML/Attribute/Values /en-US/docs/Web/MathML/Reference/Values +/en-US/docs/Web/MathML/Authoring /en-US/docs/Web/MathML/Guides/Authoring +/en-US/docs/Web/MathML/Element /en-US/docs/Web/MathML/Reference/Element +/en-US/docs/Web/MathML/Element/annotation /en-US/docs/Web/MathML/Reference/Element/annotation +/en-US/docs/Web/MathML/Element/annotation-xml /en-US/docs/Web/MathML/Reference/Element/annotation-xml +/en-US/docs/Web/MathML/Element/maction /en-US/docs/Web/MathML/Reference/Element/maction +/en-US/docs/Web/MathML/Element/math /en-US/docs/Web/MathML/Reference/Element/math +/en-US/docs/Web/MathML/Element/menclose /en-US/docs/Web/MathML/Reference/Element/menclose +/en-US/docs/Web/MathML/Element/menclosed /en-US/docs/Web/MathML/Reference/Element/menclose +/en-US/docs/Web/MathML/Element/merror /en-US/docs/Web/MathML/Reference/Element/merror +/en-US/docs/Web/MathML/Element/mfenced /en-US/docs/Web/MathML/Reference/Element/mfenced +/en-US/docs/Web/MathML/Element/mfrac /en-US/docs/Web/MathML/Reference/Element/mfrac +/en-US/docs/Web/MathML/Element/mi /en-US/docs/Web/MathML/Reference/Element/mi +/en-US/docs/Web/MathML/Element/mmultiscripts /en-US/docs/Web/MathML/Reference/Element/mmultiscripts +/en-US/docs/Web/MathML/Element/mn /en-US/docs/Web/MathML/Reference/Element/mn +/en-US/docs/Web/MathML/Element/mo /en-US/docs/Web/MathML/Reference/Element/mo +/en-US/docs/Web/MathML/Element/mover /en-US/docs/Web/MathML/Reference/Element/mover +/en-US/docs/Web/MathML/Element/mpadded /en-US/docs/Web/MathML/Reference/Element/mpadded +/en-US/docs/Web/MathML/Element/mphantom /en-US/docs/Web/MathML/Reference/Element/mphantom +/en-US/docs/Web/MathML/Element/mprescripts /en-US/docs/Web/MathML/Reference/Element/mprescripts +/en-US/docs/Web/MathML/Element/mroot /en-US/docs/Web/MathML/Reference/Element/mroot +/en-US/docs/Web/MathML/Element/mrow /en-US/docs/Web/MathML/Reference/Element/mrow +/en-US/docs/Web/MathML/Element/ms /en-US/docs/Web/MathML/Reference/Element/ms +/en-US/docs/Web/MathML/Element/mspace /en-US/docs/Web/MathML/Reference/Element/mspace +/en-US/docs/Web/MathML/Element/msqrt /en-US/docs/Web/MathML/Reference/Element/msqrt +/en-US/docs/Web/MathML/Element/mstyle /en-US/docs/Web/MathML/Reference/Element/mstyle +/en-US/docs/Web/MathML/Element/msub /en-US/docs/Web/MathML/Reference/Element/msub +/en-US/docs/Web/MathML/Element/msubsup /en-US/docs/Web/MathML/Reference/Element/msubsup +/en-US/docs/Web/MathML/Element/msup /en-US/docs/Web/MathML/Reference/Element/msup +/en-US/docs/Web/MathML/Element/mtable /en-US/docs/Web/MathML/Reference/Element/mtable +/en-US/docs/Web/MathML/Element/mtd /en-US/docs/Web/MathML/Reference/Element/mtd +/en-US/docs/Web/MathML/Element/mtext /en-US/docs/Web/MathML/Reference/Element/mtext +/en-US/docs/Web/MathML/Element/mtr /en-US/docs/Web/MathML/Reference/Element/mtr +/en-US/docs/Web/MathML/Element/munder /en-US/docs/Web/MathML/Reference/Element/munder +/en-US/docs/Web/MathML/Element/munderover /en-US/docs/Web/MathML/Reference/Element/munderover +/en-US/docs/Web/MathML/Element/none /en-US/docs/Web/MathML/Reference/Element/mmultiscripts +/en-US/docs/Web/MathML/Element/semantics /en-US/docs/Web/MathML/Reference/Element/semantics +/en-US/docs/Web/MathML/Examples /en-US/docs/Web/MathML/Guides +/en-US/docs/Web/MathML/Examples/Deriving_the_Quadratic_Formula /en-US/docs/Web/MathML/Guides/Deriving_the_quadratic_formula +/en-US/docs/Web/MathML/Examples/MathML_Pythagorean_Theorem /en-US/docs/Web/MathML/Guides/Proving_the_Pythagorean_theorem +/en-US/docs/Web/MathML/Fonts /en-US/docs/Web/MathML/Guides/Fonts +/en-US/docs/Web/MathML/Fonts/Test /en-US/docs/Web/MathML/Guides/Fonts +/en-US/docs/Web/MathML/Global_attributes /en-US/docs/Web/MathML/Reference/Global_attributes +/en-US/docs/Web/MathML/Global_attributes/dir /en-US/docs/Web/MathML/Reference/Global_attributes/dir +/en-US/docs/Web/MathML/Global_attributes/displaystyle /en-US/docs/Web/MathML/Reference/Global_attributes/displaystyle +/en-US/docs/Web/MathML/Global_attributes/href /en-US/docs/Web/MathML/Reference/Global_attributes/href +/en-US/docs/Web/MathML/Global_attributes/mathbackground /en-US/docs/Web/MathML/Reference/Global_attributes/mathbackground +/en-US/docs/Web/MathML/Global_attributes/mathcolor /en-US/docs/Web/MathML/Reference/Global_attributes/mathcolor +/en-US/docs/Web/MathML/Global_attributes/mathsize /en-US/docs/Web/MathML/Reference/Global_attributes/mathsize +/en-US/docs/Web/MathML/Global_attributes/mathvariant /en-US/docs/Web/MathML/Reference/Element/mi#mathvariant +/en-US/docs/Web/MathML/Global_attributes/scriptlevel /en-US/docs/Web/MathML/Reference/Global_attributes/scriptlevel +/en-US/docs/Web/MathML/Guides/Fractions_and_roots /en-US/docs/Web/MathML/Tutorials/For_beginners/Fractions_and_roots +/en-US/docs/Web/MathML/Guides/Getting_started /en-US/docs/Web/MathML/Tutorials/For_beginners/Getting_started +/en-US/docs/Web/MathML/Guides/Scripts /en-US/docs/Web/MathML/Tutorials/For_beginners/Scripts +/en-US/docs/Web/MathML/Guides/Tables /en-US/docs/Web/MathML/Tutorials/For_beginners/Tables +/en-US/docs/Web/MathML/Guides/Text_containers /en-US/docs/Web/MathML/Tutorials/For_beginners/Text_containers +/en-US/docs/Web/MathML/Guides/Three_famous_mathematical_formulas /en-US/docs/Web/MathML/Tutorials/For_beginners/Three_famous_mathematical_formulas /en-US/docs/Web/MathML/Index /en-US/docs/Web/MathML +/en-US/docs/Web/MathML/Reference/Attributes /en-US/docs/Web/MathML/Reference/Attribute +/en-US/docs/Web/MathML/Tutorials/Fractions_and_roots /en-US/docs/Web/MathML/Tutorials/For_beginners/Fractions_and_roots +/en-US/docs/Web/MathML/Tutorials/Getting started /en-US/docs/Web/MathML/Tutorials/For_beginners/Getting_started +/en-US/docs/Web/MathML/Tutorials/Getting_started /en-US/docs/Web/MathML/Tutorials/For_beginners/Getting_started +/en-US/docs/Web/MathML/Tutorials/Scripts /en-US/docs/Web/MathML/Tutorials/For_beginners/Scripts +/en-US/docs/Web/MathML/Tutorials/Tables /en-US/docs/Web/MathML/Tutorials/For_beginners/Tables +/en-US/docs/Web/MathML/Tutorials/Text_containers /en-US/docs/Web/MathML/Tutorials/For_beginners/Text_containers +/en-US/docs/Web/MathML/Tutorials/Three_famous_mathematical_formulas /en-US/docs/Web/MathML/Tutorials/For_beginners/Three_famous_mathematical_formulas +/en-US/docs/Web/MathML/Values /en-US/docs/Web/MathML/Reference/Values /en-US/docs/Web/Media/Audio_and_video_delivery /en-US/docs/Web/Media/Guides/Audio_and_video_delivery /en-US/docs/Web/Media/Audio_and_video_delivery/Adding_captions_and_subtitles_to_HTML5_video /en-US/docs/Web/Media/Guides/Audio_and_video_delivery/Adding_captions_and_subtitles_to_HTML5_video /en-US/docs/Web/Media/Audio_and_video_delivery/Cross-browser_audio_basics /en-US/docs/Web/Media/Guides/Audio_and_video_delivery/Cross-browser_audio_basics @@ -13370,7 +14291,7 @@ /en-US/docs/Web/Media/Audio_and_video_delivery/cross_browser_video_player /en-US/docs/Web/Media/Guides/Audio_and_video_delivery/cross_browser_video_player /en-US/docs/Web/Media/Audio_and_video_manipulation /en-US/docs/Web/Media/Guides/Audio_and_video_manipulation /en-US/docs/Web/Media/Autoplay_guide /en-US/docs/Web/Media/Guides/Autoplay -/en-US/docs/Web/Media/DASH_Adaptive_Streaming_for_HTML_5_Video /en-US/docs/Web/Media/Guides/DASH_Adaptive_Streaming_for_HTML_5_Video +/en-US/docs/Web/Media/DASH_Adaptive_Streaming_for_HTML_5_Video /en-US/docs/Web/API/Media_Source_Extensions_API/DASH_Adaptive_Streaming /en-US/docs/Web/Media/Formats /en-US/docs/Web/Media/Guides/Formats /en-US/docs/Web/Media/Formats/Audio_codecs /en-US/docs/Web/Media/Guides/Formats/Audio_codecs /en-US/docs/Web/Media/Formats/Audio_concepts /en-US/docs/Web/Media/Guides/Formats/Audio_concepts @@ -13383,6 +14304,7 @@ /en-US/docs/Web/Media/Formats/Video_concepts /en-US/docs/Web/Media/Guides/Formats/Video_concepts /en-US/docs/Web/Media/Formats/WebRTC_codecs /en-US/docs/Web/Media/Guides/Formats/WebRTC_codecs /en-US/docs/Web/Media/Formats/codecs_parameter /en-US/docs/Web/Media/Guides/Formats/codecs_parameter +/en-US/docs/Web/Media/Guides/DASH_Adaptive_Streaming_for_HTML_5_Video /en-US/docs/Web/API/Media_Source_Extensions_API/DASH_Adaptive_Streaming /en-US/docs/Web/Media/HTML_media /en-US/docs/Web/Media/Guides/Audio_and_video_delivery /en-US/docs/Web/Media/Streaming /en-US/docs/Web/Media/Guides/Streaming /en-US/docs/Web/Media/images /en-US/docs/Web/Media/Guides/Images @@ -13596,63 +14518,477 @@ /en-US/docs/Web/Reference/File_System_API /en-US/docs/Web/API/File_and_Directory_Entries_API /en-US/docs/Web/Reference/Functions_and classes_available_to_workers /en-US/docs/Web/API/Web_Workers_API/Functions_and_classes_available_to_workers /en-US/docs/Web/Reference/Functions_and_classes_available_to_workers /en-US/docs/Web/API/Web_Workers_API/Functions_and_classes_available_to_workers -/en-US/docs/Web/SVG/Attribute/Conditional_Processing /en-US/docs/Web/SVG/Attribute -/en-US/docs/Web/SVG/Attribute/Core /en-US/docs/Web/SVG/Attribute -/en-US/docs/Web/SVG/Attribute/Events /en-US/docs/Web/SVG/Attribute -/en-US/docs/Web/SVG/Attribute/Presentation /en-US/docs/Web/SVG/Attribute -/en-US/docs/Web/SVG/Attribute/Styling /en-US/docs/Web/SVG/Attribute +/en-US/docs/Web/SVG/Applying_SVG_effects_to_HTML_content /en-US/docs/Web/SVG/Guides/Applying_SVG_effects_to_HTML_content +/en-US/docs/Web/SVG/Attribute /en-US/docs/Web/SVG/Reference/Attribute +/en-US/docs/Web/SVG/Attribute/Conditional_Processing /en-US/docs/Web/SVG/Reference/Attribute +/en-US/docs/Web/SVG/Attribute/Core /en-US/docs/Web/SVG/Reference/Attribute +/en-US/docs/Web/SVG/Attribute/Events /en-US/docs/Web/SVG/Reference/Attribute +/en-US/docs/Web/SVG/Attribute/From /en-US/docs/Web/SVG/Reference/Attribute/From +/en-US/docs/Web/SVG/Attribute/Presentation /en-US/docs/Web/SVG/Reference/Attribute +/en-US/docs/Web/SVG/Attribute/Styling /en-US/docs/Web/SVG/Reference/Attribute +/en-US/docs/Web/SVG/Attribute/To /en-US/docs/Web/SVG/Reference/Attribute/To +/en-US/docs/Web/SVG/Attribute/accent-height /en-US/docs/Web/SVG/Reference/Attribute +/en-US/docs/Web/SVG/Attribute/accumulate /en-US/docs/Web/SVG/Reference/Attribute/accumulate +/en-US/docs/Web/SVG/Attribute/additive /en-US/docs/Web/SVG/Reference/Attribute/additive +/en-US/docs/Web/SVG/Attribute/alignment-baseline /en-US/docs/Web/SVG/Reference/Attribute/alignment-baseline +/en-US/docs/Web/SVG/Attribute/alphabetic /en-US/docs/Web/SVG/Reference/Attribute +/en-US/docs/Web/SVG/Attribute/amplitude /en-US/docs/Web/SVG/Reference/Attribute/amplitude +/en-US/docs/Web/SVG/Attribute/arabic-form /en-US/docs/Web/SVG/Reference/Attribute +/en-US/docs/Web/SVG/Attribute/ascent /en-US/docs/Web/SVG/Reference/Attribute +/en-US/docs/Web/SVG/Attribute/attributeName /en-US/docs/Web/SVG/Reference/Attribute/attributeName +/en-US/docs/Web/SVG/Attribute/attributeType /en-US/docs/Web/SVG/Reference/Attribute/attributeType +/en-US/docs/Web/SVG/Attribute/azimuth /en-US/docs/Web/SVG/Reference/Attribute/azimuth +/en-US/docs/Web/SVG/Attribute/baseFrequency /en-US/docs/Web/SVG/Reference/Attribute/baseFrequency +/en-US/docs/Web/SVG/Attribute/baseProfile /en-US/docs/Web/SVG/Reference/Attribute/baseProfile +/en-US/docs/Web/SVG/Attribute/baseline-shift /en-US/docs/Web/SVG/Reference/Attribute/baseline-shift +/en-US/docs/Web/SVG/Attribute/bbox /en-US/docs/Web/SVG/Reference/Attribute +/en-US/docs/Web/SVG/Attribute/begin /en-US/docs/Web/SVG/Reference/Attribute/begin +/en-US/docs/Web/SVG/Attribute/bias /en-US/docs/Web/SVG/Reference/Attribute/bias +/en-US/docs/Web/SVG/Attribute/by /en-US/docs/Web/SVG/Reference/Attribute/by +/en-US/docs/Web/SVG/Attribute/calcMode /en-US/docs/Web/SVG/Reference/Attribute/calcMode +/en-US/docs/Web/SVG/Attribute/cap-height /en-US/docs/Web/SVG/Reference/Attribute +/en-US/docs/Web/SVG/Attribute/class /en-US/docs/Web/SVG/Reference/Attribute/class +/en-US/docs/Web/SVG/Attribute/clip /en-US/docs/Web/SVG/Reference/Attribute/clip +/en-US/docs/Web/SVG/Attribute/clip-path /en-US/docs/Web/SVG/Reference/Attribute/clip-path +/en-US/docs/Web/SVG/Attribute/clip-rule /en-US/docs/Web/SVG/Reference/Attribute/clip-rule +/en-US/docs/Web/SVG/Attribute/clipPathUnits /en-US/docs/Web/SVG/Reference/Attribute/clipPathUnits +/en-US/docs/Web/SVG/Attribute/color /en-US/docs/Web/SVG/Reference/Attribute/color +/en-US/docs/Web/SVG/Attribute/color-interpolation /en-US/docs/Web/SVG/Reference/Attribute/color-interpolation +/en-US/docs/Web/SVG/Attribute/color-interpolation-filters /en-US/docs/Web/SVG/Reference/Attribute/color-interpolation-filters +/en-US/docs/Web/SVG/Attribute/crossorigin /en-US/docs/Web/SVG/Reference/Attribute/crossorigin +/en-US/docs/Web/SVG/Attribute/cursor /en-US/docs/Web/SVG/Reference/Attribute/cursor +/en-US/docs/Web/SVG/Attribute/cx /en-US/docs/Web/SVG/Reference/Attribute/cx +/en-US/docs/Web/SVG/Attribute/cy /en-US/docs/Web/SVG/Reference/Attribute/cy +/en-US/docs/Web/SVG/Attribute/d /en-US/docs/Web/SVG/Reference/Attribute/d +/en-US/docs/Web/SVG/Attribute/data-* /en-US/docs/Web/SVG/Reference/Attribute/data-* /en-US/docs/Web/SVG/Attribute/dataset /en-US/docs/Web/API/SVGElement/dataset +/en-US/docs/Web/SVG/Attribute/decoding /en-US/docs/Web/SVG/Reference/Attribute/decoding +/en-US/docs/Web/SVG/Attribute/descent /en-US/docs/Web/SVG/Reference/Attribute +/en-US/docs/Web/SVG/Attribute/diffuseConstant /en-US/docs/Web/SVG/Reference/Attribute/diffuseConstant +/en-US/docs/Web/SVG/Attribute/direction /en-US/docs/Web/SVG/Reference/Attribute/direction +/en-US/docs/Web/SVG/Attribute/display /en-US/docs/Web/SVG/Reference/Attribute/display +/en-US/docs/Web/SVG/Attribute/divisor /en-US/docs/Web/SVG/Reference/Attribute/divisor +/en-US/docs/Web/SVG/Attribute/dominant-baseline /en-US/docs/Web/SVG/Reference/Attribute/dominant-baseline +/en-US/docs/Web/SVG/Attribute/dur /en-US/docs/Web/SVG/Reference/Attribute/dur +/en-US/docs/Web/SVG/Attribute/dx /en-US/docs/Web/SVG/Reference/Attribute/dx +/en-US/docs/Web/SVG/Attribute/dy /en-US/docs/Web/SVG/Reference/Attribute/dy +/en-US/docs/Web/SVG/Attribute/edgeMode /en-US/docs/Web/SVG/Reference/Attribute/edgeMode +/en-US/docs/Web/SVG/Attribute/elevation /en-US/docs/Web/SVG/Reference/Attribute/elevation +/en-US/docs/Web/SVG/Attribute/end /en-US/docs/Web/SVG/Reference/Attribute/end +/en-US/docs/Web/SVG/Attribute/exponent /en-US/docs/Web/SVG/Reference/Attribute/exponent +/en-US/docs/Web/SVG/Attribute/fill /en-US/docs/Web/SVG/Reference/Attribute/fill +/en-US/docs/Web/SVG/Attribute/fill-opacity /en-US/docs/Web/SVG/Reference/Attribute/fill-opacity +/en-US/docs/Web/SVG/Attribute/fill-rule /en-US/docs/Web/SVG/Reference/Attribute/fill-rule +/en-US/docs/Web/SVG/Attribute/filter /en-US/docs/Web/SVG/Reference/Attribute/filter +/en-US/docs/Web/SVG/Attribute/filterUnits /en-US/docs/Web/SVG/Reference/Attribute/filterUnits +/en-US/docs/Web/SVG/Attribute/flood-color /en-US/docs/Web/SVG/Reference/Attribute/flood-color +/en-US/docs/Web/SVG/Attribute/flood-opacity /en-US/docs/Web/SVG/Reference/Attribute/flood-opacity +/en-US/docs/Web/SVG/Attribute/font-family /en-US/docs/Web/SVG/Reference/Attribute/font-family +/en-US/docs/Web/SVG/Attribute/font-size /en-US/docs/Web/SVG/Reference/Attribute/font-size +/en-US/docs/Web/SVG/Attribute/font-size-adjust /en-US/docs/Web/SVG/Reference/Attribute/font-size-adjust +/en-US/docs/Web/SVG/Attribute/font-stretch /en-US/docs/Web/SVG/Reference/Attribute/font-stretch +/en-US/docs/Web/SVG/Attribute/font-style /en-US/docs/Web/SVG/Reference/Attribute/font-style +/en-US/docs/Web/SVG/Attribute/font-variant /en-US/docs/Web/SVG/Reference/Attribute/font-variant +/en-US/docs/Web/SVG/Attribute/font-weight /en-US/docs/Web/SVG/Reference/Attribute/font-weight +/en-US/docs/Web/SVG/Attribute/fr /en-US/docs/Web/SVG/Reference/Attribute/fr +/en-US/docs/Web/SVG/Attribute/fx /en-US/docs/Web/SVG/Reference/Attribute/fx +/en-US/docs/Web/SVG/Attribute/fy /en-US/docs/Web/SVG/Reference/Attribute/fy +/en-US/docs/Web/SVG/Attribute/g1 /en-US/docs/Web/SVG/Reference/Attribute +/en-US/docs/Web/SVG/Attribute/g2 /en-US/docs/Web/SVG/Reference/Attribute +/en-US/docs/Web/SVG/Attribute/glyph-name /en-US/docs/Web/SVG/Reference/Attribute +/en-US/docs/Web/SVG/Attribute/glyph-orientation-horizontal /en-US/docs/Web/SVG/Reference/Attribute/glyph-orientation-horizontal +/en-US/docs/Web/SVG/Attribute/glyph-orientation-vertical /en-US/docs/Web/SVG/Reference/Attribute/glyph-orientation-vertical +/en-US/docs/Web/SVG/Attribute/gradientTransform /en-US/docs/Web/SVG/Reference/Attribute/gradientTransform +/en-US/docs/Web/SVG/Attribute/gradientUnits /en-US/docs/Web/SVG/Reference/Attribute/gradientUnits +/en-US/docs/Web/SVG/Attribute/hanging /en-US/docs/Web/SVG/Reference/Attribute +/en-US/docs/Web/SVG/Attribute/height /en-US/docs/Web/SVG/Reference/Attribute/height +/en-US/docs/Web/SVG/Attribute/horiz-adv-x /en-US/docs/Web/SVG/Reference/Attribute +/en-US/docs/Web/SVG/Attribute/horiz-origin-x /en-US/docs/Web/SVG/Reference/Attribute +/en-US/docs/Web/SVG/Attribute/horiz-origin-y /en-US/docs/Web/SVG/Reference/Attribute +/en-US/docs/Web/SVG/Attribute/href /en-US/docs/Web/SVG/Reference/Attribute/href +/en-US/docs/Web/SVG/Attribute/id /en-US/docs/Web/SVG/Reference/Attribute/id +/en-US/docs/Web/SVG/Attribute/ideographic /en-US/docs/Web/SVG/Reference/Attribute +/en-US/docs/Web/SVG/Attribute/image-rendering /en-US/docs/Web/SVG/Reference/Attribute/image-rendering +/en-US/docs/Web/SVG/Attribute/in /en-US/docs/Web/SVG/Reference/Attribute/in +/en-US/docs/Web/SVG/Attribute/in2 /en-US/docs/Web/SVG/Reference/Attribute/in2 +/en-US/docs/Web/SVG/Attribute/intercept /en-US/docs/Web/SVG/Reference/Attribute/intercept +/en-US/docs/Web/SVG/Attribute/k /en-US/docs/Web/SVG/Reference/Attribute +/en-US/docs/Web/SVG/Attribute/k1 /en-US/docs/Web/SVG/Reference/Attribute/k1 +/en-US/docs/Web/SVG/Attribute/k2 /en-US/docs/Web/SVG/Reference/Attribute/k2 +/en-US/docs/Web/SVG/Attribute/k3 /en-US/docs/Web/SVG/Reference/Attribute/k3 +/en-US/docs/Web/SVG/Attribute/k4 /en-US/docs/Web/SVG/Reference/Attribute/k4 +/en-US/docs/Web/SVG/Attribute/kernelMatrix /en-US/docs/Web/SVG/Reference/Attribute/kernelMatrix +/en-US/docs/Web/SVG/Attribute/kernelUnitLength /en-US/docs/Web/SVG/Reference/Attribute/kernelUnitLength /en-US/docs/Web/SVG/Attribute/kerning /en-US/docs/Web/CSS/font-kerning +/en-US/docs/Web/SVG/Attribute/keyPoints /en-US/docs/Web/SVG/Reference/Attribute/keyPoints +/en-US/docs/Web/SVG/Attribute/keySplines /en-US/docs/Web/SVG/Reference/Attribute/keySplines +/en-US/docs/Web/SVG/Attribute/keyTimes /en-US/docs/Web/SVG/Reference/Attribute/keyTimes +/en-US/docs/Web/SVG/Attribute/lang /en-US/docs/Web/SVG/Reference/Attribute/lang +/en-US/docs/Web/SVG/Attribute/lengthAdjust /en-US/docs/Web/SVG/Reference/Attribute/lengthAdjust +/en-US/docs/Web/SVG/Attribute/letter-spacing /en-US/docs/Web/SVG/Reference/Attribute/letter-spacing +/en-US/docs/Web/SVG/Attribute/lighting-color /en-US/docs/Web/SVG/Reference/Attribute/lighting-color +/en-US/docs/Web/SVG/Attribute/limitingConeAngle /en-US/docs/Web/SVG/Reference/Attribute/limitingConeAngle +/en-US/docs/Web/SVG/Attribute/marker-end /en-US/docs/Web/SVG/Reference/Attribute/marker-end +/en-US/docs/Web/SVG/Attribute/marker-mid /en-US/docs/Web/SVG/Reference/Attribute/marker-mid +/en-US/docs/Web/SVG/Attribute/marker-start /en-US/docs/Web/SVG/Reference/Attribute/marker-start +/en-US/docs/Web/SVG/Attribute/markerHeight /en-US/docs/Web/SVG/Reference/Attribute/markerHeight +/en-US/docs/Web/SVG/Attribute/markerUnits /en-US/docs/Web/SVG/Reference/Attribute/markerUnits +/en-US/docs/Web/SVG/Attribute/markerWidth /en-US/docs/Web/SVG/Reference/Attribute/markerWidth +/en-US/docs/Web/SVG/Attribute/mask /en-US/docs/Web/SVG/Reference/Attribute/mask +/en-US/docs/Web/SVG/Attribute/maskContentUnits /en-US/docs/Web/SVG/Reference/Attribute/maskContentUnits +/en-US/docs/Web/SVG/Attribute/maskUnits /en-US/docs/Web/SVG/Reference/Attribute/maskUnits +/en-US/docs/Web/SVG/Attribute/mathematical /en-US/docs/Web/SVG/Reference/Attribute +/en-US/docs/Web/SVG/Attribute/max /en-US/docs/Web/SVG/Reference/Attribute/max +/en-US/docs/Web/SVG/Attribute/media /en-US/docs/Web/SVG/Reference/Attribute/media +/en-US/docs/Web/SVG/Attribute/method /en-US/docs/Web/SVG/Reference/Attribute/method +/en-US/docs/Web/SVG/Attribute/min /en-US/docs/Web/SVG/Reference/Attribute/min +/en-US/docs/Web/SVG/Attribute/mode /en-US/docs/Web/SVG/Reference/Attribute/mode +/en-US/docs/Web/SVG/Attribute/name /en-US/docs/Web/SVG/Reference/Attribute +/en-US/docs/Web/SVG/Attribute/numOctaves /en-US/docs/Web/SVG/Reference/Attribute/numOctaves +/en-US/docs/Web/SVG/Attribute/opacity /en-US/docs/Web/SVG/Reference/Attribute/opacity +/en-US/docs/Web/SVG/Attribute/operator /en-US/docs/Web/SVG/Reference/Attribute/operator +/en-US/docs/Web/SVG/Attribute/order /en-US/docs/Web/SVG/Reference/Attribute/order +/en-US/docs/Web/SVG/Attribute/orient /en-US/docs/Web/SVG/Reference/Attribute/orient +/en-US/docs/Web/SVG/Attribute/orientation /en-US/docs/Web/SVG/Reference/Attribute +/en-US/docs/Web/SVG/Attribute/origin /en-US/docs/Web/SVG/Reference/Attribute/origin +/en-US/docs/Web/SVG/Attribute/overflow /en-US/docs/Web/SVG/Reference/Attribute/overflow +/en-US/docs/Web/SVG/Attribute/overline-position /en-US/docs/Web/SVG/Reference/Attribute +/en-US/docs/Web/SVG/Attribute/overline-thickness /en-US/docs/Web/SVG/Reference/Attribute +/en-US/docs/Web/SVG/Attribute/paint-order /en-US/docs/Web/SVG/Reference/Attribute/paint-order +/en-US/docs/Web/SVG/Attribute/panose-1 /en-US/docs/Web/SVG/Reference/Attribute +/en-US/docs/Web/SVG/Attribute/path /en-US/docs/Web/SVG/Reference/Attribute/path +/en-US/docs/Web/SVG/Attribute/pathLength /en-US/docs/Web/SVG/Reference/Attribute/pathLength +/en-US/docs/Web/SVG/Attribute/patternContentUnits /en-US/docs/Web/SVG/Reference/Attribute/patternContentUnits +/en-US/docs/Web/SVG/Attribute/patternTransform /en-US/docs/Web/SVG/Reference/Attribute/patternTransform +/en-US/docs/Web/SVG/Attribute/patternUnits /en-US/docs/Web/SVG/Reference/Attribute/patternUnits +/en-US/docs/Web/SVG/Attribute/pointer-events /en-US/docs/Web/SVG/Reference/Attribute/pointer-events +/en-US/docs/Web/SVG/Attribute/points /en-US/docs/Web/SVG/Reference/Attribute/points +/en-US/docs/Web/SVG/Attribute/pointsAtX /en-US/docs/Web/SVG/Reference/Attribute/pointsAtX +/en-US/docs/Web/SVG/Attribute/pointsAtY /en-US/docs/Web/SVG/Reference/Attribute/pointsAtY +/en-US/docs/Web/SVG/Attribute/pointsAtZ /en-US/docs/Web/SVG/Reference/Attribute/pointsAtZ +/en-US/docs/Web/SVG/Attribute/preserveAlpha /en-US/docs/Web/SVG/Reference/Attribute/preserveAlpha +/en-US/docs/Web/SVG/Attribute/preserveAspectRatio /en-US/docs/Web/SVG/Reference/Attribute/preserveAspectRatio +/en-US/docs/Web/SVG/Attribute/primitiveUnits /en-US/docs/Web/SVG/Reference/Attribute/primitiveUnits +/en-US/docs/Web/SVG/Attribute/r /en-US/docs/Web/SVG/Reference/Attribute/r +/en-US/docs/Web/SVG/Attribute/radius /en-US/docs/Web/SVG/Reference/Attribute/radius +/en-US/docs/Web/SVG/Attribute/refX /en-US/docs/Web/SVG/Reference/Attribute/refX +/en-US/docs/Web/SVG/Attribute/refY /en-US/docs/Web/SVG/Reference/Attribute/refY +/en-US/docs/Web/SVG/Attribute/repeatCount /en-US/docs/Web/SVG/Reference/Attribute/repeatCount +/en-US/docs/Web/SVG/Attribute/repeatDur /en-US/docs/Web/SVG/Reference/Attribute/repeatDur +/en-US/docs/Web/SVG/Attribute/requiredFeatures /en-US/docs/Web/SVG/Reference/Attribute/requiredFeatures +/en-US/docs/Web/SVG/Attribute/restart /en-US/docs/Web/SVG/Reference/Attribute/restart +/en-US/docs/Web/SVG/Attribute/result /en-US/docs/Web/SVG/Reference/Attribute/result +/en-US/docs/Web/SVG/Attribute/rotate /en-US/docs/Web/SVG/Reference/Attribute/rotate +/en-US/docs/Web/SVG/Attribute/rx /en-US/docs/Web/SVG/Reference/Attribute/rx +/en-US/docs/Web/SVG/Attribute/ry /en-US/docs/Web/SVG/Reference/Attribute/ry +/en-US/docs/Web/SVG/Attribute/scale /en-US/docs/Web/SVG/Reference/Attribute/scale +/en-US/docs/Web/SVG/Attribute/seed /en-US/docs/Web/SVG/Reference/Attribute/seed +/en-US/docs/Web/SVG/Attribute/shape-rendering /en-US/docs/Web/SVG/Reference/Attribute/shape-rendering +/en-US/docs/Web/SVG/Attribute/side /en-US/docs/Web/SVG/Reference/Attribute/side +/en-US/docs/Web/SVG/Attribute/slope /en-US/docs/Web/SVG/Reference/Attribute/slope +/en-US/docs/Web/SVG/Attribute/spacing /en-US/docs/Web/SVG/Reference/Attribute/spacing +/en-US/docs/Web/SVG/Attribute/specularConstant /en-US/docs/Web/SVG/Reference/Attribute/specularConstant +/en-US/docs/Web/SVG/Attribute/specularExponent /en-US/docs/Web/SVG/Reference/Attribute/specularExponent +/en-US/docs/Web/SVG/Attribute/spreadMethod /en-US/docs/Web/SVG/Reference/Attribute/spreadMethod +/en-US/docs/Web/SVG/Attribute/startOffset /en-US/docs/Web/SVG/Reference/Attribute/startOffset +/en-US/docs/Web/SVG/Attribute/stdDeviation /en-US/docs/Web/SVG/Reference/Attribute/stdDeviation +/en-US/docs/Web/SVG/Attribute/stemh /en-US/docs/Web/SVG/Reference/Attribute +/en-US/docs/Web/SVG/Attribute/stemv /en-US/docs/Web/SVG/Reference/Attribute +/en-US/docs/Web/SVG/Attribute/stitchTiles /en-US/docs/Web/SVG/Reference/Attribute/stitchTiles +/en-US/docs/Web/SVG/Attribute/stop-color /en-US/docs/Web/SVG/Reference/Attribute/stop-color +/en-US/docs/Web/SVG/Attribute/stop-opacity /en-US/docs/Web/SVG/Reference/Attribute/stop-opacity +/en-US/docs/Web/SVG/Attribute/strikethrough-position /en-US/docs/Web/SVG/Reference/Attribute +/en-US/docs/Web/SVG/Attribute/strikethrough-thickness /en-US/docs/Web/SVG/Reference/Attribute +/en-US/docs/Web/SVG/Attribute/string /en-US/docs/Web/SVG/Reference/Attribute +/en-US/docs/Web/SVG/Attribute/stroke /en-US/docs/Web/SVG/Reference/Attribute/stroke +/en-US/docs/Web/SVG/Attribute/stroke-dasharray /en-US/docs/Web/SVG/Reference/Attribute/stroke-dasharray +/en-US/docs/Web/SVG/Attribute/stroke-dashoffset /en-US/docs/Web/SVG/Reference/Attribute/stroke-dashoffset +/en-US/docs/Web/SVG/Attribute/stroke-linecap /en-US/docs/Web/SVG/Reference/Attribute/stroke-linecap +/en-US/docs/Web/SVG/Attribute/stroke-linejoin /en-US/docs/Web/SVG/Reference/Attribute/stroke-linejoin +/en-US/docs/Web/SVG/Attribute/stroke-miterlimit /en-US/docs/Web/SVG/Reference/Attribute/stroke-miterlimit +/en-US/docs/Web/SVG/Attribute/stroke-opacity /en-US/docs/Web/SVG/Reference/Attribute/stroke-opacity +/en-US/docs/Web/SVG/Attribute/stroke-width /en-US/docs/Web/SVG/Reference/Attribute/stroke-width +/en-US/docs/Web/SVG/Attribute/style /en-US/docs/Web/SVG/Reference/Attribute/style +/en-US/docs/Web/SVG/Attribute/surfaceScale /en-US/docs/Web/SVG/Reference/Attribute/surfaceScale +/en-US/docs/Web/SVG/Attribute/systemLanguage /en-US/docs/Web/SVG/Reference/Attribute/systemLanguage +/en-US/docs/Web/SVG/Attribute/tabindex /en-US/docs/Web/SVG/Reference/Attribute/tabindex +/en-US/docs/Web/SVG/Attribute/tableValues /en-US/docs/Web/SVG/Reference/Attribute/tableValues +/en-US/docs/Web/SVG/Attribute/target /en-US/docs/Web/SVG/Reference/Attribute/target +/en-US/docs/Web/SVG/Attribute/targetX /en-US/docs/Web/SVG/Reference/Attribute/targetX +/en-US/docs/Web/SVG/Attribute/targetY /en-US/docs/Web/SVG/Reference/Attribute/targetY +/en-US/docs/Web/SVG/Attribute/text-anchor /en-US/docs/Web/SVG/Reference/Attribute/text-anchor +/en-US/docs/Web/SVG/Attribute/text-decoration /en-US/docs/Web/SVG/Reference/Attribute/text-decoration +/en-US/docs/Web/SVG/Attribute/text-rendering /en-US/docs/Web/SVG/Reference/Attribute/text-rendering +/en-US/docs/Web/SVG/Attribute/textLength /en-US/docs/Web/SVG/Reference/Attribute/textLength +/en-US/docs/Web/SVG/Attribute/transform /en-US/docs/Web/SVG/Reference/Attribute/transform +/en-US/docs/Web/SVG/Attribute/transform-origin /en-US/docs/Web/SVG/Reference/Attribute/transform-origin +/en-US/docs/Web/SVG/Attribute/type /en-US/docs/Web/SVG/Reference/Attribute/type +/en-US/docs/Web/SVG/Attribute/u1 /en-US/docs/Web/SVG/Reference/Attribute +/en-US/docs/Web/SVG/Attribute/u2 /en-US/docs/Web/SVG/Reference/Attribute +/en-US/docs/Web/SVG/Attribute/underline-position /en-US/docs/Web/SVG/Reference/Attribute +/en-US/docs/Web/SVG/Attribute/underline-thickness /en-US/docs/Web/SVG/Reference/Attribute +/en-US/docs/Web/SVG/Attribute/unicode /en-US/docs/Web/SVG/Reference/Attribute +/en-US/docs/Web/SVG/Attribute/unicode-bidi /en-US/docs/Web/SVG/Reference/Attribute/unicode-bidi +/en-US/docs/Web/SVG/Attribute/unicode-range /en-US/docs/Web/SVG/Reference/Attribute +/en-US/docs/Web/SVG/Attribute/units-per-em /en-US/docs/Web/SVG/Reference/Attribute +/en-US/docs/Web/SVG/Attribute/v-alphabetic /en-US/docs/Web/SVG/Reference/Attribute +/en-US/docs/Web/SVG/Attribute/v-hanging /en-US/docs/Web/SVG/Reference/Attribute +/en-US/docs/Web/SVG/Attribute/v-ideographic /en-US/docs/Web/SVG/Reference/Attribute +/en-US/docs/Web/SVG/Attribute/v-mathematical /en-US/docs/Web/SVG/Reference/Attribute +/en-US/docs/Web/SVG/Attribute/values /en-US/docs/Web/SVG/Reference/Attribute/values +/en-US/docs/Web/SVG/Attribute/vector-effect /en-US/docs/Web/SVG/Reference/Attribute/vector-effect +/en-US/docs/Web/SVG/Attribute/version /en-US/docs/Web/SVG/Reference/Attribute/version +/en-US/docs/Web/SVG/Attribute/vert-adv-y /en-US/docs/Web/SVG/Reference/Attribute +/en-US/docs/Web/SVG/Attribute/vert-origin-x /en-US/docs/Web/SVG/Reference/Attribute +/en-US/docs/Web/SVG/Attribute/vert-origin-y /en-US/docs/Web/SVG/Reference/Attribute +/en-US/docs/Web/SVG/Attribute/viewBox /en-US/docs/Web/SVG/Reference/Attribute/viewBox +/en-US/docs/Web/SVG/Attribute/visibility /en-US/docs/Web/SVG/Reference/Attribute/visibility +/en-US/docs/Web/SVG/Attribute/width /en-US/docs/Web/SVG/Reference/Attribute/width +/en-US/docs/Web/SVG/Attribute/widths /en-US/docs/Web/SVG/Reference/Attribute +/en-US/docs/Web/SVG/Attribute/word-spacing /en-US/docs/Web/SVG/Reference/Attribute/word-spacing +/en-US/docs/Web/SVG/Attribute/writing-mode /en-US/docs/Web/SVG/Reference/Attribute/writing-mode +/en-US/docs/Web/SVG/Attribute/x /en-US/docs/Web/SVG/Reference/Attribute/x +/en-US/docs/Web/SVG/Attribute/x-height /en-US/docs/Web/SVG/Reference/Attribute +/en-US/docs/Web/SVG/Attribute/x1 /en-US/docs/Web/SVG/Reference/Attribute/x1 +/en-US/docs/Web/SVG/Attribute/x2 /en-US/docs/Web/SVG/Reference/Attribute/x2 +/en-US/docs/Web/SVG/Attribute/xChannelSelector /en-US/docs/Web/SVG/Reference/Attribute/xChannelSelector +/en-US/docs/Web/SVG/Attribute/xlink:arcrole /en-US/docs/Web/SVG/Reference/Attribute/xlink:arcrole +/en-US/docs/Web/SVG/Attribute/xlink:href /en-US/docs/Web/SVG/Reference/Attribute/xlink:href +/en-US/docs/Web/SVG/Attribute/xlink:show /en-US/docs/Web/SVG/Reference/Attribute/xlink:show +/en-US/docs/Web/SVG/Attribute/xlink:title /en-US/docs/Web/SVG/Reference/Attribute/xlink:title +/en-US/docs/Web/SVG/Attribute/xlink:type /en-US/docs/Web/SVG/Reference/Attribute/xlink:type +/en-US/docs/Web/SVG/Attribute/xml:lang /en-US/docs/Web/SVG/Reference/Attribute/xml:lang +/en-US/docs/Web/SVG/Attribute/xml:space /en-US/docs/Web/SVG/Reference/Attribute/xml:space +/en-US/docs/Web/SVG/Attribute/y /en-US/docs/Web/SVG/Reference/Attribute/y +/en-US/docs/Web/SVG/Attribute/y1 /en-US/docs/Web/SVG/Reference/Attribute/y1 +/en-US/docs/Web/SVG/Attribute/y2 /en-US/docs/Web/SVG/Reference/Attribute/y2 +/en-US/docs/Web/SVG/Attribute/yChannelSelector /en-US/docs/Web/SVG/Reference/Attribute/yChannelSelector +/en-US/docs/Web/SVG/Attribute/z /en-US/docs/Web/SVG/Reference/Attribute/z +/en-US/docs/Web/SVG/Attribute/zoomAndPan /en-US/docs/Web/SVG/Reference/Attribute/zoomAndPan /en-US/docs/Web/SVG/Compatibility_sources /en-US/docs/Web/SVG -/en-US/docs/Web/SVG/Element/animateColor /en-US/docs/Web/SVG/Element/animate +/en-US/docs/Web/SVG/Content_type /en-US/docs/Web/SVG/Guides/Content_type +/en-US/docs/Web/SVG/Element /en-US/docs/Web/SVG/Reference/Element +/en-US/docs/Web/SVG/Element/a /en-US/docs/Web/SVG/Reference/Element/a +/en-US/docs/Web/SVG/Element/animate /en-US/docs/Web/SVG/Reference/Element/animate +/en-US/docs/Web/SVG/Element/animateColor /en-US/docs/Web/SVG/Reference/Element/animate +/en-US/docs/Web/SVG/Element/animateMotion /en-US/docs/Web/SVG/Reference/Element/animateMotion +/en-US/docs/Web/SVG/Element/animateTransform /en-US/docs/Web/SVG/Reference/Element/animateTransform +/en-US/docs/Web/SVG/Element/circle /en-US/docs/Web/SVG/Reference/Element/circle +/en-US/docs/Web/SVG/Element/clipPath /en-US/docs/Web/SVG/Reference/Element/clipPath +/en-US/docs/Web/SVG/Element/cursor /en-US/docs/Web/CSS/cursor +/en-US/docs/Web/SVG/Element/defs /en-US/docs/Web/SVG/Reference/Element/defs +/en-US/docs/Web/SVG/Element/desc /en-US/docs/Web/SVG/Reference/Element/desc +/en-US/docs/Web/SVG/Element/discard /en-US/docs/Web/SVG/Reference/Element +/en-US/docs/Web/SVG/Element/ellipse /en-US/docs/Web/SVG/Reference/Element/ellipse +/en-US/docs/Web/SVG/Element/feBlend /en-US/docs/Web/SVG/Reference/Element/feBlend +/en-US/docs/Web/SVG/Element/feColorMatrix /en-US/docs/Web/SVG/Reference/Element/feColorMatrix +/en-US/docs/Web/SVG/Element/feComponentTransfer /en-US/docs/Web/SVG/Reference/Element/feComponentTransfer +/en-US/docs/Web/SVG/Element/feComposite /en-US/docs/Web/SVG/Reference/Element/feComposite +/en-US/docs/Web/SVG/Element/feConvolveMatrix /en-US/docs/Web/SVG/Reference/Element/feConvolveMatrix +/en-US/docs/Web/SVG/Element/feDiffuseLighting /en-US/docs/Web/SVG/Reference/Element/feDiffuseLighting +/en-US/docs/Web/SVG/Element/feDisplacementMap /en-US/docs/Web/SVG/Reference/Element/feDisplacementMap +/en-US/docs/Web/SVG/Element/feDistantLight /en-US/docs/Web/SVG/Reference/Element/feDistantLight +/en-US/docs/Web/SVG/Element/feDropShadow /en-US/docs/Web/SVG/Reference/Element/feDropShadow +/en-US/docs/Web/SVG/Element/feFlood /en-US/docs/Web/SVG/Reference/Element/feFlood +/en-US/docs/Web/SVG/Element/feFuncA /en-US/docs/Web/SVG/Reference/Element/feFuncA +/en-US/docs/Web/SVG/Element/feFuncB /en-US/docs/Web/SVG/Reference/Element/feFuncB +/en-US/docs/Web/SVG/Element/feFuncG /en-US/docs/Web/SVG/Reference/Element/feFuncG +/en-US/docs/Web/SVG/Element/feFuncR /en-US/docs/Web/SVG/Reference/Element/feFuncR +/en-US/docs/Web/SVG/Element/feGaussianBlur /en-US/docs/Web/SVG/Reference/Element/feGaussianBlur +/en-US/docs/Web/SVG/Element/feImage /en-US/docs/Web/SVG/Reference/Element/feImage +/en-US/docs/Web/SVG/Element/feMerge /en-US/docs/Web/SVG/Reference/Element/feMerge +/en-US/docs/Web/SVG/Element/feMergeNode /en-US/docs/Web/SVG/Reference/Element/feMergeNode +/en-US/docs/Web/SVG/Element/feMorphology /en-US/docs/Web/SVG/Reference/Element/feMorphology +/en-US/docs/Web/SVG/Element/feOffset /en-US/docs/Web/SVG/Reference/Element/feOffset +/en-US/docs/Web/SVG/Element/fePointLight /en-US/docs/Web/SVG/Reference/Element/fePointLight +/en-US/docs/Web/SVG/Element/feSpecularLighting /en-US/docs/Web/SVG/Reference/Element/feSpecularLighting +/en-US/docs/Web/SVG/Element/feSpotLight /en-US/docs/Web/SVG/Reference/Element/feSpotLight +/en-US/docs/Web/SVG/Element/feTile /en-US/docs/Web/SVG/Reference/Element/feTile +/en-US/docs/Web/SVG/Element/feTurbulence /en-US/docs/Web/SVG/Reference/Element/feTurbulence +/en-US/docs/Web/SVG/Element/filter /en-US/docs/Web/SVG/Reference/Element/filter +/en-US/docs/Web/SVG/Element/font /en-US/docs/Web/CSS/@font-face +/en-US/docs/Web/SVG/Element/font-face /en-US/docs/Web/CSS/@font-face +/en-US/docs/Web/SVG/Element/font-face-format /en-US/docs/Web/CSS/@font-face +/en-US/docs/Web/SVG/Element/font-face-name /en-US/docs/Web/CSS/@font-face +/en-US/docs/Web/SVG/Element/font-face-src /en-US/docs/Web/CSS/@font-face +/en-US/docs/Web/SVG/Element/font-face-uri /en-US/docs/Web/CSS/@font-face +/en-US/docs/Web/SVG/Element/foreignObject /en-US/docs/Web/SVG/Reference/Element/foreignObject +/en-US/docs/Web/SVG/Element/g /en-US/docs/Web/SVG/Reference/Element/g +/en-US/docs/Web/SVG/Element/glyph /en-US/docs/Web/CSS/@font-face +/en-US/docs/Web/SVG/Element/glyphRef /en-US/docs/Web/CSS/@font-face +/en-US/docs/Web/SVG/Element/hkern /en-US/docs/Web/CSS/@font-face +/en-US/docs/Web/SVG/Element/image /en-US/docs/Web/SVG/Reference/Element/image +/en-US/docs/Web/SVG/Element/line /en-US/docs/Web/SVG/Reference/Element/line +/en-US/docs/Web/SVG/Element/linearGradient /en-US/docs/Web/SVG/Reference/Element/linearGradient +/en-US/docs/Web/SVG/Element/marker /en-US/docs/Web/SVG/Reference/Element/marker +/en-US/docs/Web/SVG/Element/mask /en-US/docs/Web/SVG/Reference/Element/mask +/en-US/docs/Web/SVG/Element/metadata /en-US/docs/Web/SVG/Reference/Element/metadata +/en-US/docs/Web/SVG/Element/missing-glyph /en-US/docs/Web/CSS/@font-face +/en-US/docs/Web/SVG/Element/mpath /en-US/docs/Web/SVG/Reference/Element/mpath +/en-US/docs/Web/SVG/Element/path /en-US/docs/Web/SVG/Reference/Element/path +/en-US/docs/Web/SVG/Element/pattern /en-US/docs/Web/SVG/Reference/Element/pattern +/en-US/docs/Web/SVG/Element/polygon /en-US/docs/Web/SVG/Reference/Element/polygon +/en-US/docs/Web/SVG/Element/polyline /en-US/docs/Web/SVG/Reference/Element/polyline +/en-US/docs/Web/SVG/Element/radialGradient /en-US/docs/Web/SVG/Reference/Element/radialGradient +/en-US/docs/Web/SVG/Element/rect /en-US/docs/Web/SVG/Reference/Element/rect +/en-US/docs/Web/SVG/Element/script /en-US/docs/Web/SVG/Reference/Element/script +/en-US/docs/Web/SVG/Element/set /en-US/docs/Web/SVG/Reference/Element/set +/en-US/docs/Web/SVG/Element/stop /en-US/docs/Web/SVG/Reference/Element/stop +/en-US/docs/Web/SVG/Element/style /en-US/docs/Web/SVG/Reference/Element/style +/en-US/docs/Web/SVG/Element/svg /en-US/docs/Web/SVG/Reference/Element/svg +/en-US/docs/Web/SVG/Element/switch /en-US/docs/Web/SVG/Reference/Element/switch +/en-US/docs/Web/SVG/Element/symbol /en-US/docs/Web/SVG/Reference/Element/symbol +/en-US/docs/Web/SVG/Element/text /en-US/docs/Web/SVG/Reference/Element/text +/en-US/docs/Web/SVG/Element/textPath /en-US/docs/Web/SVG/Reference/Element/textPath +/en-US/docs/Web/SVG/Element/title /en-US/docs/Web/SVG/Reference/Element/title +/en-US/docs/Web/SVG/Element/tref /en-US/docs/Web/CSS/@font-face +/en-US/docs/Web/SVG/Element/tspan /en-US/docs/Web/SVG/Reference/Element/tspan +/en-US/docs/Web/SVG/Element/use /en-US/docs/Web/SVG/Reference/Element/use +/en-US/docs/Web/SVG/Element/view /en-US/docs/Web/SVG/Reference/Element/view +/en-US/docs/Web/SVG/Element/vkern /en-US/docs/Web/CSS/@font-face /en-US/docs/Web/SVG/Index /en-US/docs/Web/SVG +/en-US/docs/Web/SVG/Linking /en-US/docs/Web/SVG/Guides/Linking +/en-US/docs/Web/SVG/Namespaces_Crash_Course /en-US/docs/Web/SVG/Guides/Namespaces_crash_course +/en-US/docs/Web/SVG/Namespaces_Crash_Course/Example /en-US/docs/Web/SVG/Guides/Namespaces_crash_course/Example +/en-US/docs/Web/SVG/Reference/Attribute/accent-height /en-US/docs/Web/SVG/Reference/Attribute +/en-US/docs/Web/SVG/Reference/Attribute/alphabetic /en-US/docs/Web/SVG/Reference/Attribute +/en-US/docs/Web/SVG/Reference/Attribute/arabic-form /en-US/docs/Web/SVG/Reference/Attribute +/en-US/docs/Web/SVG/Reference/Attribute/ascent /en-US/docs/Web/SVG/Reference/Attribute +/en-US/docs/Web/SVG/Reference/Attribute/bbox /en-US/docs/Web/SVG/Reference/Attribute +/en-US/docs/Web/SVG/Reference/Attribute/cap-height /en-US/docs/Web/SVG/Reference/Attribute +/en-US/docs/Web/SVG/Reference/Attribute/descent /en-US/docs/Web/SVG/Reference/Attribute +/en-US/docs/Web/SVG/Reference/Attribute/g1 /en-US/docs/Web/SVG/Reference/Attribute +/en-US/docs/Web/SVG/Reference/Attribute/g2 /en-US/docs/Web/SVG/Reference/Attribute +/en-US/docs/Web/SVG/Reference/Attribute/glyph-name /en-US/docs/Web/SVG/Reference/Attribute +/en-US/docs/Web/SVG/Reference/Attribute/hanging /en-US/docs/Web/SVG/Reference/Attribute +/en-US/docs/Web/SVG/Reference/Attribute/horiz-adv-x /en-US/docs/Web/SVG/Reference/Attribute +/en-US/docs/Web/SVG/Reference/Attribute/horiz-origin-x /en-US/docs/Web/SVG/Reference/Attribute +/en-US/docs/Web/SVG/Reference/Attribute/horiz-origin-y /en-US/docs/Web/SVG/Reference/Attribute +/en-US/docs/Web/SVG/Reference/Attribute/ideographic /en-US/docs/Web/SVG/Reference/Attribute +/en-US/docs/Web/SVG/Reference/Attribute/k /en-US/docs/Web/SVG/Reference/Attribute +/en-US/docs/Web/SVG/Reference/Attribute/mathematical /en-US/docs/Web/SVG/Reference/Attribute +/en-US/docs/Web/SVG/Reference/Attribute/name /en-US/docs/Web/SVG/Reference/Attribute +/en-US/docs/Web/SVG/Reference/Attribute/orientation /en-US/docs/Web/SVG/Reference/Attribute +/en-US/docs/Web/SVG/Reference/Attribute/overline-position /en-US/docs/Web/SVG/Reference/Attribute +/en-US/docs/Web/SVG/Reference/Attribute/overline-thickness /en-US/docs/Web/SVG/Reference/Attribute +/en-US/docs/Web/SVG/Reference/Attribute/panose-1 /en-US/docs/Web/SVG/Reference/Attribute +/en-US/docs/Web/SVG/Reference/Attribute/stemh /en-US/docs/Web/SVG/Reference/Attribute +/en-US/docs/Web/SVG/Reference/Attribute/stemv /en-US/docs/Web/SVG/Reference/Attribute +/en-US/docs/Web/SVG/Reference/Attribute/strikethrough-position /en-US/docs/Web/SVG/Reference/Attribute +/en-US/docs/Web/SVG/Reference/Attribute/strikethrough-thickness /en-US/docs/Web/SVG/Reference/Attribute +/en-US/docs/Web/SVG/Reference/Attribute/string /en-US/docs/Web/SVG/Reference/Attribute +/en-US/docs/Web/SVG/Reference/Attribute/u1 /en-US/docs/Web/SVG/Reference/Attribute +/en-US/docs/Web/SVG/Reference/Attribute/u2 /en-US/docs/Web/SVG/Reference/Attribute +/en-US/docs/Web/SVG/Reference/Attribute/underline-position /en-US/docs/Web/SVG/Reference/Attribute +/en-US/docs/Web/SVG/Reference/Attribute/underline-thickness /en-US/docs/Web/SVG/Reference/Attribute +/en-US/docs/Web/SVG/Reference/Attribute/unicode /en-US/docs/Web/SVG/Reference/Attribute +/en-US/docs/Web/SVG/Reference/Attribute/unicode-range /en-US/docs/Web/SVG/Reference/Attribute +/en-US/docs/Web/SVG/Reference/Attribute/units-per-em /en-US/docs/Web/SVG/Reference/Attribute +/en-US/docs/Web/SVG/Reference/Attribute/v-alphabetic /en-US/docs/Web/SVG/Reference/Attribute +/en-US/docs/Web/SVG/Reference/Attribute/v-hanging /en-US/docs/Web/SVG/Reference/Attribute +/en-US/docs/Web/SVG/Reference/Attribute/v-ideographic /en-US/docs/Web/SVG/Reference/Attribute +/en-US/docs/Web/SVG/Reference/Attribute/v-mathematical /en-US/docs/Web/SVG/Reference/Attribute +/en-US/docs/Web/SVG/Reference/Attribute/vert-adv-y /en-US/docs/Web/SVG/Reference/Attribute +/en-US/docs/Web/SVG/Reference/Attribute/vert-origin-x /en-US/docs/Web/SVG/Reference/Attribute +/en-US/docs/Web/SVG/Reference/Attribute/vert-origin-y /en-US/docs/Web/SVG/Reference/Attribute +/en-US/docs/Web/SVG/Reference/Attribute/widths /en-US/docs/Web/SVG/Reference/Attribute +/en-US/docs/Web/SVG/Reference/Attribute/x-height /en-US/docs/Web/SVG/Reference/Attribute +/en-US/docs/Web/SVG/Reference/Element/cursor /en-US/docs/Web/CSS/cursor +/en-US/docs/Web/SVG/Reference/Element/discard /en-US/docs/Web/SVG/Reference/Element +/en-US/docs/Web/SVG/Reference/Element/font /en-US/docs/Web/CSS/@font-face +/en-US/docs/Web/SVG/Reference/Element/font-face /en-US/docs/Web/CSS/@font-face +/en-US/docs/Web/SVG/Reference/Element/font-face-format /en-US/docs/Web/CSS/@font-face +/en-US/docs/Web/SVG/Reference/Element/font-face-name /en-US/docs/Web/CSS/@font-face +/en-US/docs/Web/SVG/Reference/Element/font-face-src /en-US/docs/Web/CSS/@font-face +/en-US/docs/Web/SVG/Reference/Element/font-face-uri /en-US/docs/Web/CSS/@font-face +/en-US/docs/Web/SVG/Reference/Element/glyph /en-US/docs/Web/CSS/@font-face +/en-US/docs/Web/SVG/Reference/Element/glyphRef /en-US/docs/Web/CSS/@font-face +/en-US/docs/Web/SVG/Reference/Element/hkern /en-US/docs/Web/CSS/@font-face +/en-US/docs/Web/SVG/Reference/Element/missing-glyph /en-US/docs/Web/CSS/@font-face +/en-US/docs/Web/SVG/Reference/Element/tref /en-US/docs/Web/CSS/@font-face +/en-US/docs/Web/SVG/Reference/Element/vkern /en-US/docs/Web/CSS/@font-face +/en-US/docs/Web/SVG/SVG_animation_with_SMIL /en-US/docs/Web/SVG/Guides/SVG_animation_with_SMIL +/en-US/docs/Web/SVG/SVG_as_an_Image /en-US/docs/Web/SVG/Guides/SVG_as_an_image +/en-US/docs/Web/SVG/Scripting /en-US/docs/Web/SVG/Guides/Scripting /en-US/docs/Web/SVG/Server-configuration https://www.w3.org/services/svg-server/ /en-US/docs/Web/SVG/Specification_Deviations /en-US/docs/Web/SVG -/en-US/docs/Web/SVG/Tutorial/Fill_Stroke_and_Gradients /en-US/docs/Web/SVG/Tutorial/Fills_and_Strokes -/en-US/docs/Web/SVG/circle /en-US/docs/Web/SVG/Element/circle -/en-US/docs/Web/SVG/ellipse /en-US/docs/Web/SVG/Element/ellipse +/en-US/docs/Web/SVG/Tutorial /en-US/docs/Web/SVG/Tutorials/SVG_from_scratch +/en-US/docs/Web/SVG/Tutorial/Basic_Shapes /en-US/docs/Web/SVG/Tutorials/SVG_from_scratch/Basic_shapes +/en-US/docs/Web/SVG/Tutorial/Basic_Transformations /en-US/docs/Web/SVG/Tutorials/SVG_from_scratch/Basic_transformations +/en-US/docs/Web/SVG/Tutorial/Clipping_and_masking /en-US/docs/Web/SVG/Tutorials/SVG_from_scratch/Clipping_and_masking +/en-US/docs/Web/SVG/Tutorial/Fill_Stroke_and_Gradients /en-US/docs/Web/SVG/Tutorials/SVG_from_scratch/Fills_and_strokes +/en-US/docs/Web/SVG/Tutorial/Fills_and_Strokes /en-US/docs/Web/SVG/Tutorials/SVG_from_scratch/Fills_and_strokes +/en-US/docs/Web/SVG/Tutorial/Filter_effects /en-US/docs/Web/SVG/Tutorials/SVG_from_scratch/Filter_effects +/en-US/docs/Web/SVG/Tutorial/Getting_Started /en-US/docs/Web/SVG/Tutorials/SVG_from_scratch/Getting_started +/en-US/docs/Web/SVG/Tutorial/Gradients /en-US/docs/Web/SVG/Tutorials/SVG_from_scratch/Gradients +/en-US/docs/Web/SVG/Tutorial/Introduction /en-US/docs/Web/SVG/Tutorials/SVG_from_scratch/Introduction +/en-US/docs/Web/SVG/Tutorial/Other_content_in_SVG /en-US/docs/Web/SVG/Tutorials/SVG_from_scratch/Other_content_in_SVG +/en-US/docs/Web/SVG/Tutorial/Paths /en-US/docs/Web/SVG/Tutorials/SVG_from_scratch/Paths +/en-US/docs/Web/SVG/Tutorial/Patterns /en-US/docs/Web/SVG/Tutorials/SVG_from_scratch/Patterns +/en-US/docs/Web/SVG/Tutorial/Positions /en-US/docs/Web/SVG/Tutorials/SVG_from_scratch/Positions +/en-US/docs/Web/SVG/Tutorial/SVG_Filters_Tutorial /en-US/docs/Web/SVG/Guides/SVG_filters +/en-US/docs/Web/SVG/Tutorial/SVG_Image_Tag /en-US/docs/Web/SVG/Tutorials/SVG_from_scratch/Image_element +/en-US/docs/Web/SVG/Tutorial/SVG_In_HTML_Introduction /en-US/docs/Web/SVG/Guides/SVG_in_HTML +/en-US/docs/Web/SVG/Tutorial/SVG_and_CSS /en-US/docs/Web/SVG/Tutorials/SVG_from_scratch/SVG_and_CSS +/en-US/docs/Web/SVG/Tutorial/SVG_fonts /en-US/docs/Web/SVG/Tutorials/SVG_from_scratch/Using_fonts +/en-US/docs/Web/SVG/Tutorial/SVG_image_element /en-US/docs/Web/SVG/Tutorials/SVG_from_scratch/Image_element +/en-US/docs/Web/SVG/Tutorial/Texts /en-US/docs/Web/SVG/Tutorials/SVG_from_scratch/Texts +/en-US/docs/Web/SVG/Tutorial/Tools_for_SVG /en-US/docs/Web/SVG/Tutorials/SVG_from_scratch/Tools_for_SVG +/en-US/docs/Web/SVG/Tutorials/SVG_from_scratch/Basic_shapes_ /en-US/docs/Web/SVG/Tutorials/SVG_from_scratch/Basic_shapes +/en-US/docs/Web/SVG/Tutorials/SVG_from_scratch/Basic_transformations_ /en-US/docs/Web/SVG/Tutorials/SVG_from_scratch/Basic_transformations +/en-US/docs/Web/SVG/Tutorials/SVG_from_scratch/Fills_and_strokes_ /en-US/docs/Web/SVG/Tutorials/SVG_from_scratch/Fills_and_strokes +/en-US/docs/Web/SVG/Tutorials/SVG_from_scratch/Getting_started_ /en-US/docs/Web/SVG/Tutorials/SVG_from_scratch/Getting_started +/en-US/docs/Web/SVG/Tutorials/SVG_from_scratch/SVG_Filters_Tutorial /en-US/docs/Web/SVG/Guides/SVG_filters +/en-US/docs/Web/SVG/Tutorials/SVG_from_scratch/SVG_In_HTML_Introduction /en-US/docs/Web/SVG/Guides/SVG_in_HTML +/en-US/docs/Web/SVG/Tutorials/SVG_from_scratch/SVG_fonts /en-US/docs/Web/SVG/Tutorials/SVG_from_scratch/Using_fonts +/en-US/docs/Web/SVG/Tutorials/SVG_from_scratch/SVG_image_element /en-US/docs/Web/SVG/Tutorials/SVG_from_scratch/Image_element +/en-US/docs/Web/SVG/circle /en-US/docs/Web/SVG/Reference/Element/circle +/en-US/docs/Web/SVG/ellipse /en-US/docs/Web/SVG/Reference/Element/ellipse /en-US/docs/Web/SVG/filter /en-US/docs/Web/CSS/filter -/en-US/docs/Web/SVG/g /en-US/docs/Web/SVG/Element/g -/en-US/docs/Web/SVG/line /en-US/docs/Web/SVG/Element/line -/en-US/docs/Web/SVG/polyline /en-US/docs/Web/SVG/Element/polyline -/en-US/docs/Web/SVG/rect /en-US/docs/Web/SVG/Element/rect -/en-US/docs/Web/SVG/use /en-US/docs/Web/SVG/Element/use -/en-US/docs/Web/Security/CSP /en-US/docs/Web/HTTP/CSP -/en-US/docs/Web/Security/CSP/CSP_policy_directives /en-US/docs/Web/HTTP/Headers/Content-Security-Policy -/en-US/docs/Web/Security/CSP/Default_CSP_restrictions /en-US/docs/Web/HTTP/Headers/Content-Security-Policy -/en-US/docs/Web/Security/CSP/Introducing_Content_Security_Policy /en-US/docs/Web/HTTP/CSP -/en-US/docs/Web/Security/CSP/Using_CSP_reports /en-US/docs/Web/HTTP/CSP -/en-US/docs/Web/Security/CSP/Using_CSP_violation_reports /en-US/docs/Web/HTTP/CSP -/en-US/docs/Web/Security/CSP/Using_Content_Security_Policy /en-US/docs/Web/HTTP/CSP -/en-US/docs/Web/Security/Do_not_track_field_guide /en-US/docs/Web/HTTP/Headers/DNT -/en-US/docs/Web/Security/Do_not_track_field_guide/Additional_resources /en-US/docs/Web/HTTP/Headers/DNT -/en-US/docs/Web/Security/Do_not_track_field_guide/Case_studies /en-US/docs/Web/HTTP/Headers/DNT -/en-US/docs/Web/Security/Do_not_track_field_guide/Case_studies/1_Advertising_company /en-US/docs/Web/HTTP/Headers/DNT -/en-US/docs/Web/Security/Do_not_track_field_guide/Case_studies/2_Technology_provider /en-US/docs/Web/HTTP/Headers/DNT -/en-US/docs/Web/Security/Do_not_track_field_guide/Case_studies/3_Media_company /en-US/docs/Web/HTTP/Headers/DNT -/en-US/docs/Web/Security/Do_not_track_field_guide/Case_studies/4_Software_company /en-US/docs/Web/HTTP/Headers/DNT -/en-US/docs/Web/Security/Do_not_track_field_guide/Case_studies/Additional_issues_to_consider /en-US/docs/Web/HTTP/Headers/DNT -/en-US/docs/Web/Security/Do_not_track_field_guide/Case_studies/Case_studies/Additional_issues_to_consider /en-US/docs/Web/HTTP/Headers/DNT -/en-US/docs/Web/Security/Do_not_track_field_guide/Case_studies/Case_studies/Case_studies_flow_chart /en-US/docs/Web/HTTP/Headers/DNT -/en-US/docs/Web/Security/Do_not_track_field_guide/Case_studies/Case_studies_flow_chart /en-US/docs/Web/HTTP/Headers/DNT -/en-US/docs/Web/Security/Do_not_track_field_guide/Case_studies/DNT_case_studies_flow_chart /en-US/docs/Web/HTTP/Headers/DNT -/en-US/docs/Web/Security/Do_not_track_field_guide/Case_studies/Flow_chart /en-US/docs/Web/HTTP/Headers/DNT -/en-US/docs/Web/Security/Do_not_track_field_guide/Introduction /en-US/docs/Web/HTTP/Headers/DNT -/en-US/docs/Web/Security/Do_not_track_field_guide/Introduction/Background /en-US/docs/Web/HTTP/Headers/DNT -/en-US/docs/Web/Security/Do_not_track_field_guide/Introduction/How_Do_Not_Track_works /en-US/docs/Web/HTTP/Headers/DNT -/en-US/docs/Web/Security/Do_not_track_field_guide/Introduction/Privacy_techniques_and_Do_Not_Track /en-US/docs/Web/HTTP/Headers/DNT -/en-US/docs/Web/Security/Do_not_track_field_guide/Introduction/What_does_tracking_mean /en-US/docs/Web/HTTP/Headers/DNT -/en-US/docs/Web/Security/Do_not_track_field_guide/Tutorials /en-US/docs/Web/HTTP/Headers/DNT -/en-US/docs/Web/Security/Do_not_track_field_guide/Tutorials/1_Reading_the_DNT_header /en-US/docs/Web/HTTP/Headers/DNT -/en-US/docs/Web/Security/Do_not_track_field_guide/Tutorials/2_Displaying_DNT_status_with_caching /en-US/docs/Web/HTTP/Headers/DNT -/en-US/docs/Web/Security/Do_not_track_field_guide/Tutorials/3_Collecting_aggregate_data_based_on_DNT /en-US/docs/Web/HTTP/Headers/DNT -/en-US/docs/Web/Security/Do_not_track_field_guide/Tutorials/Additional_resources /en-US/docs/Web/HTTP/Headers/DNT -/en-US/docs/Web/Security/HTTP_strict_transport_security /en-US/docs/Web/HTTP/Headers/Strict-Transport-Security +/en-US/docs/Web/SVG/g /en-US/docs/Web/SVG/Reference/Element/g +/en-US/docs/Web/SVG/line /en-US/docs/Web/SVG/Reference/Element/line +/en-US/docs/Web/SVG/polyline /en-US/docs/Web/SVG/Reference/Element/polyline +/en-US/docs/Web/SVG/rect /en-US/docs/Web/SVG/Reference/Element/rect +/en-US/docs/Web/SVG/use /en-US/docs/Web/SVG/Reference/Element/use +/en-US/docs/Web/Security/CSP /en-US/docs/Web/HTTP/Guides/CSP +/en-US/docs/Web/Security/CSP/CSP_policy_directives /en-US/docs/Web/HTTP/Reference/Headers/Content-Security-Policy +/en-US/docs/Web/Security/CSP/Default_CSP_restrictions /en-US/docs/Web/HTTP/Reference/Headers/Content-Security-Policy +/en-US/docs/Web/Security/CSP/Introducing_Content_Security_Policy /en-US/docs/Web/HTTP/Guides/CSP +/en-US/docs/Web/Security/CSP/Using_CSP_reports /en-US/docs/Web/HTTP/Guides/CSP +/en-US/docs/Web/Security/CSP/Using_CSP_violation_reports /en-US/docs/Web/HTTP/Guides/CSP +/en-US/docs/Web/Security/CSP/Using_Content_Security_Policy /en-US/docs/Web/HTTP/Guides/CSP +/en-US/docs/Web/Security/Do_not_track_field_guide /en-US/docs/Web/HTTP/Reference/Headers/DNT +/en-US/docs/Web/Security/Do_not_track_field_guide/Additional_resources /en-US/docs/Web/HTTP/Reference/Headers/DNT +/en-US/docs/Web/Security/Do_not_track_field_guide/Case_studies /en-US/docs/Web/HTTP/Reference/Headers/DNT +/en-US/docs/Web/Security/Do_not_track_field_guide/Case_studies/1_Advertising_company /en-US/docs/Web/HTTP/Reference/Headers/DNT +/en-US/docs/Web/Security/Do_not_track_field_guide/Case_studies/2_Technology_provider /en-US/docs/Web/HTTP/Reference/Headers/DNT +/en-US/docs/Web/Security/Do_not_track_field_guide/Case_studies/3_Media_company /en-US/docs/Web/HTTP/Reference/Headers/DNT +/en-US/docs/Web/Security/Do_not_track_field_guide/Case_studies/4_Software_company /en-US/docs/Web/HTTP/Reference/Headers/DNT +/en-US/docs/Web/Security/Do_not_track_field_guide/Case_studies/Additional_issues_to_consider /en-US/docs/Web/HTTP/Reference/Headers/DNT +/en-US/docs/Web/Security/Do_not_track_field_guide/Case_studies/Case_studies/Additional_issues_to_consider /en-US/docs/Web/HTTP/Reference/Headers/DNT +/en-US/docs/Web/Security/Do_not_track_field_guide/Case_studies/Case_studies/Case_studies_flow_chart /en-US/docs/Web/HTTP/Reference/Headers/DNT +/en-US/docs/Web/Security/Do_not_track_field_guide/Case_studies/Case_studies_flow_chart /en-US/docs/Web/HTTP/Reference/Headers/DNT +/en-US/docs/Web/Security/Do_not_track_field_guide/Case_studies/DNT_case_studies_flow_chart /en-US/docs/Web/HTTP/Reference/Headers/DNT +/en-US/docs/Web/Security/Do_not_track_field_guide/Case_studies/Flow_chart /en-US/docs/Web/HTTP/Reference/Headers/DNT +/en-US/docs/Web/Security/Do_not_track_field_guide/Introduction /en-US/docs/Web/HTTP/Reference/Headers/DNT +/en-US/docs/Web/Security/Do_not_track_field_guide/Introduction/Background /en-US/docs/Web/HTTP/Reference/Headers/DNT +/en-US/docs/Web/Security/Do_not_track_field_guide/Introduction/How_Do_Not_Track_works /en-US/docs/Web/HTTP/Reference/Headers/DNT +/en-US/docs/Web/Security/Do_not_track_field_guide/Introduction/Privacy_techniques_and_Do_Not_Track /en-US/docs/Web/HTTP/Reference/Headers/DNT +/en-US/docs/Web/Security/Do_not_track_field_guide/Introduction/What_does_tracking_mean /en-US/docs/Web/HTTP/Reference/Headers/DNT +/en-US/docs/Web/Security/Do_not_track_field_guide/Tutorials /en-US/docs/Web/HTTP/Reference/Headers/DNT +/en-US/docs/Web/Security/Do_not_track_field_guide/Tutorials/1_Reading_the_DNT_header /en-US/docs/Web/HTTP/Reference/Headers/DNT +/en-US/docs/Web/Security/Do_not_track_field_guide/Tutorials/2_Displaying_DNT_status_with_caching /en-US/docs/Web/HTTP/Reference/Headers/DNT +/en-US/docs/Web/Security/Do_not_track_field_guide/Tutorials/3_Collecting_aggregate_data_based_on_DNT /en-US/docs/Web/HTTP/Reference/Headers/DNT +/en-US/docs/Web/Security/Do_not_track_field_guide/Tutorials/Additional_resources /en-US/docs/Web/HTTP/Reference/Headers/DNT +/en-US/docs/Web/Security/HTTP_strict_transport_security /en-US/docs/Web/HTTP/Reference/Headers/Strict-Transport-Security /en-US/docs/Web/Security/Mixed_content/How_to_fix_website_with_mixed_content /en-US/docs/Web/Security/Mixed_content#developer_console +/en-US/docs/Web/Security/Practical_implementation_guides/CSRF_prevention /en-US/docs/Web/Security/Attacks/CSRF +/en-US/docs/Web/Security/Practical_implementation_guides/Clickjacking /en-US/docs/Web/Security/Attacks/Clickjacking /en-US/docs/Web/Security/Public_Key_Pinning /en-US/docs/Web/Security/Certificate_Transparency /en-US/docs/Web/Security/Securing_your_site /en-US/docs/Web/Security/Practical_implementation_guides /en-US/docs/Web/Security/Securing_your_site/Configuring_server_MIME_types /en-US/docs/Learn_web_development/Extensions/Server-side/Configuring_server_MIME_types /en-US/docs/Web/Security/Securing_your_site/Turning_off_form_autocompletion /en-US/docs/Web/Security/Practical_implementation_guides/Turning_off_form_autocompletion +/en-US/docs/Web/Security/Types_of_attacks /en-US/docs/Web/Security/Attacks /en-US/docs/Web/Text_fragments /en-US/docs/Web/URI/Reference/Fragment/Text_fragments /en-US/docs/Web/Tutorials /en-US/docs/MDN/Tutorials /en-US/docs/Web/URI/Authority /en-US/docs/Web/URI/Reference/Authority @@ -13744,6 +15080,8 @@ /en-US/docs/Web/XML/Index /en-US/docs/Web/XML /en-US/docs/Web/XML/Parsing_and_serializing_XML /en-US/docs/Web/XML/Guides/Parsing_and_serializing_XML /en-US/docs/Web/XML/XML_introduction /en-US/docs/Web/XML/Guides/XML_introduction +/en-US/docs/Web/XML/XSLT/Guides/Transforming_XML_with_XSLT/An_Overview /en-US/docs/Web/XML/XSLT/Guides/Transforming_XML_with_XSLT +/en-US/docs/Web/XML/XSLT/Guides/Transforming_XML_with_XSLT/For_Further_Reading /en-US/docs/Web/XML/XSLT/Guides/Transforming_XML_with_XSLT /en-US/docs/Web/XML/xml:base /en-US/docs/Web/API/Node/baseURI /en-US/docs/Web/XPath /en-US/docs/Web/XML/XPath /en-US/docs/Web/XPath/Axes /en-US/docs/Web/XML/XPath/Reference/Axes @@ -13891,8 +15229,8 @@ /en-US/docs/Web/XSLT/Guides/Common_errors /en-US/docs/Web/XML/XSLT/Guides/Common_errors /en-US/docs/Web/XSLT/Guides/PI_Parameters /en-US/docs/Web/XML/XSLT/Guides/PI_Parameters /en-US/docs/Web/XSLT/Guides/Transforming_XML_with_XSLT /en-US/docs/Web/XML/XSLT/Guides/Transforming_XML_with_XSLT -/en-US/docs/Web/XSLT/Guides/Transforming_XML_with_XSLT/An_Overview /en-US/docs/Web/XML/XSLT/Guides/Transforming_XML_with_XSLT/An_Overview -/en-US/docs/Web/XSLT/Guides/Transforming_XML_with_XSLT/For_Further_Reading /en-US/docs/Web/XML/XSLT/Guides/Transforming_XML_with_XSLT/For_Further_Reading +/en-US/docs/Web/XSLT/Guides/Transforming_XML_with_XSLT/An_Overview /en-US/docs/Web/XML/XSLT/Guides/Transforming_XML_with_XSLT +/en-US/docs/Web/XSLT/Guides/Transforming_XML_with_XSLT/For_Further_Reading /en-US/docs/Web/XML/XSLT/Guides/Transforming_XML_with_XSLT /en-US/docs/Web/XSLT/Index /en-US/docs/Web/XML/XSLT /en-US/docs/Web/XSLT/PI_Parameters /en-US/docs/Web/XML/XSLT/Guides/PI_Parameters /en-US/docs/Web/XSLT/Reference /en-US/docs/Web/XML/XSLT/Reference @@ -13933,8 +15271,8 @@ /en-US/docs/Web/XSLT/Reference/Element/when /en-US/docs/Web/XML/XSLT/Reference/Element/when /en-US/docs/Web/XSLT/Reference/Element/with-param /en-US/docs/Web/XML/XSLT/Reference/Element/with-param /en-US/docs/Web/XSLT/Transforming_XML_with_XSLT /en-US/docs/Web/XML/XSLT/Guides/Transforming_XML_with_XSLT -/en-US/docs/Web/XSLT/Transforming_XML_with_XSLT/An_Overview /en-US/docs/Web/XML/XSLT/Guides/Transforming_XML_with_XSLT/An_Overview -/en-US/docs/Web/XSLT/Transforming_XML_with_XSLT/For_Further_Reading /en-US/docs/Web/XML/XSLT/Guides/Transforming_XML_with_XSLT/For_Further_Reading +/en-US/docs/Web/XSLT/Transforming_XML_with_XSLT/An_Overview /en-US/docs/Web/XML/XSLT/Guides/Transforming_XML_with_XSLT +/en-US/docs/Web/XSLT/Transforming_XML_with_XSLT/For_Further_Reading /en-US/docs/Web/XML/XSLT/Guides/Transforming_XML_with_XSLT /en-US/docs/Web/XSLT/Transforming_XML_with_XSLT/Mozilla_XSLT_XPath_Reference /en-US/docs/Web/XML/XSLT/Guides/Transforming_XML_with_XSLT /en-US/docs/Web/XSLT/Transforming_XML_with_XSLT/Mozilla_XSLT_XPath_Reference/Axes /en-US/docs/Web/XML/XPath/Reference/Axes /en-US/docs/Web/XSLT/Transforming_XML_with_XSLT/Mozilla_XSLT_XPath_Reference/Axes/ancestor /en-US/docs/Web/XML/XPath/Reference/Axes#ancestor @@ -14145,7 +15483,7 @@ /en-US/docs/Web_Audio_API/Porting_webkitAudioContext_code_to_standards_based_AudioContext /en-US/docs/Web/API/Web_Audio_API /en-US/docs/Web_Audio_API/Using_Web_Audio_API /en-US/docs/Web/API/Web_Audio_API/Using_Web_Audio_API /en-US/docs/Web_Development /en-US/docs/MDN/Guides -/en-US/docs/Web_Development/HTTP_cookies /en-US/docs/Web/HTTP/Cookies +/en-US/docs/Web_Development/HTTP_cookies /en-US/docs/Web/HTTP/Guides/Cookies /en-US/docs/Web_Development/Introduction_to_Web_development /en-US/docs/Learn_web_development /en-US/docs/Web_Development/Mobile /en-US/docs/Learn_web_development/Core/CSS_layout/Responsive_Design /en-US/docs/Web_Development/Mobile/A_hybrid_approach /en-US/docs/Learn_web_development/Core/CSS_layout/Responsive_Design @@ -14161,7 +15499,7 @@ /en-US/docs/Web_development/Writing_Forward_Compatible_Websites /en-US/docs/Learn_web_development/Core/Scripting/Debugging_JavaScript /en-US/docs/Web_development/Writing_forward-compatible_websites /en-US/docs/Learn_web_development/Core/Scripting/Debugging_JavaScript /en-US/docs/What's_New_in_Deer_Park_Alpha /en-US/docs/Mozilla/Firefox/Releases/1.5/What_s_new_in_1.5_alpha -/en-US/docs/What_does_tracking_mean /en-US/docs/Web/HTTP/Headers/DNT +/en-US/docs/What_does_tracking_mean /en-US/docs/Web/HTTP/Reference/Headers/DNT /en-US/docs/Whitespace_in_the_DOM /en-US/docs/Web/API/Document_Object_Model/Whitespace /en-US/docs/WindowEventHandlers.onbeforeprint /en-US/docs/Web/API/Window/beforeprint_event /en-US/docs/WindowEventHandlers.onbeforeunload /en-US/docs/Web/API/Window/beforeunload_event @@ -14404,7 +15742,7 @@ /en-US/docs/aria/Enhancing_form_accessibility_with_WAI-ARIA /en-US/docs/Web/Accessibility/ARIA /en-US/docs/aria/Form_hints/Enhancing_form_accessibility_with_ARIA /en-US/docs/Web/Accessibility/ARIA /en-US/docs/aria/forms /en-US/docs/Web/Accessibility/ARIA -/en-US/docs/aria/forms/Multipart_labels /en-US/docs/Web/Accessibility/ARIA/Multipart_labels +/en-US/docs/aria/forms/Multipart_labels /en-US/docs/Web/Accessibility/ARIA/Guides/Multipart_labels /en-US/docs/aria/forms/alerts /en-US/docs/Web/Accessibility/ARIA /en-US/docs/arrow_functions /en-US/docs/Web/JavaScript/Reference/Functions/Arrow_functions /en-US/docs/attributes /en-US/docs/Web/API/Element/attributes @@ -14412,9 +15750,9 @@ /en-US/docs/bfcache /en-US/docs/Mozilla/Firefox/Releases/1.5/Using_Firefox_1.5_caching /en-US/docs/bgColor /en-US/docs/Web/API/HTMLTableElement/bgColor /en-US/docs/bubbles /en-US/docs/Web/API/Event/bubbles -/en-US/docs/button_role /en-US/docs/Web/Accessibility/ARIA/Roles/button_role +/en-US/docs/button_role /en-US/docs/Web/Accessibility/ARIA/Reference/Roles/button_role /en-US/docs/cancelable /en-US/docs/Web/API/Event/cancelable -/en-US/docs/caption /en-US/docs/Web/HTML/Element/caption +/en-US/docs/caption /en-US/docs/Web/HTML/Reference/Elements/caption /en-US/docs/caret_temp /en-US/docs/Web/API/Document/caretPositionFromPoint /en-US/docs/ccs_temp /en-US/docs/Web/API/Document/createCDATASection /en-US/docs/cellPadding /en-US/docs/Web/API/HTMLTableElement/cellPadding @@ -14583,7 +15921,7 @@ /en-US/docs/onresize /en-US/docs/Web/API/Window/resize_event /en-US/docs/ownerDocument /en-US/docs/Web/API/Node/ownerDocument /en-US/docs/ownerNode /en-US/docs/Web/API/StyleSheet/ownerNode -/en-US/docs/paint-order /en-US/docs/Web/SVG/Attribute/paint-order +/en-US/docs/paint-order /en-US/docs/Web/SVG/Reference/Attribute/paint-order /en-US/docs/parentNode /en-US/docs/Web/API/Node/parentNode /en-US/docs/parentStyleSheet /en-US/docs/Web/API/CSSRule/parentStyleSheet /en-US/docs/prefix /en-US/docs/Web/API/Element/prefix @@ -14625,24 +15963,24 @@ /en-US/docs/tagName /en-US/docs/Web/API/Element/tagName /en-US/docs/timeStamp /en-US/docs/Web/API/Event/timeStamp /en-US/docs/timing-function /en-US/docs/Web/CSS/easing-function -/en-US/docs/title /en-US/docs/Web/HTML/Element/title +/en-US/docs/title /en-US/docs/Web/HTML/Reference/Elements/title /en-US/docs/toLowerCase /en-US/docs/Web/JavaScript/Reference/Global_Objects/String/toLowerCase /en-US/docs/toSource /en-US/docs/Web/JavaScript/Reference/Global_Objects/Object/toString /en-US/docs/toString /en-US/docs/Web/JavaScript/Reference/Global_Objects/Date/toString /en-US/docs/transform /en-US/docs/Web/CSS/transform /en-US/docs/typeof /en-US/docs/Web/JavaScript/Reference/Operators/typeof /en-US/docs/var /en-US/docs/Web/CSS/var -/en-US/docs/web/accessibility/aria/aria_techniques/using_the_alertdialog_role/ /en-US/docs/Web/Accessibility/ARIA/Roles/alertdialog_role -/en-US/docs/web/accessibility/aria/aria_techniques/using_the_article_role/ /en-US/docs/Web/Accessibility/ARIA/Roles/article_role -/en-US/docs/web/accessibility/aria/aria_techniques/using_the_group_role/ /en-US/docs/Web/Accessibility/ARIA/Roles/group_role -/en-US/docs/web/accessibility/aria/aria_techniques/using_the_link_role/ /en-US/docs/Web/Accessibility/ARIA/Roles/link_role -/en-US/docs/web/accessibility/aria/aria_techniques/using_the_log_role/ /en-US/docs/Web/Accessibility/ARIA/Roles/log_role -/en-US/docs/web/accessibility/aria/aria_techniques/using_the_presentation_role/ /en-US/docs/Web/Accessibility/ARIA/Roles/presentation_role -/en-US/docs/web/accessibility/aria/aria_techniques/using_the_progressbar_role/ /en-US/docs/Web/Accessibility/ARIA/Roles/progressbar_role -/en-US/docs/web/accessibility/aria/aria_techniques/using_the_radio_role/ /en-US/docs/Web/Accessibility/ARIA/Roles/radio_role -/en-US/docs/web/accessibility/aria/aria_techniques/using_the_slider_role/ /en-US/docs/Web/Accessibility/ARIA/Roles/slider_role -/en-US/docs/web/accessibility/aria/aria_techniques/using_the_status_role/ /en-US/docs/Web/Accessibility/ARIA/Roles/status_role -/en-US/docs/web/accessibility/aria/aria_techniques/using_the_toolbar_role/ /en-US/docs/Web/Accessibility/ARIA/Roles/toolbar_role +/en-US/docs/web/accessibility/aria/aria_techniques/using_the_alertdialog_role/ /en-US/docs/Web/Accessibility/ARIA/Reference/Roles/alertdialog_role +/en-US/docs/web/accessibility/aria/aria_techniques/using_the_article_role/ /en-US/docs/Web/Accessibility/ARIA/Reference/Roles/article_role +/en-US/docs/web/accessibility/aria/aria_techniques/using_the_group_role/ /en-US/docs/Web/Accessibility/ARIA/Reference/Roles/group_role +/en-US/docs/web/accessibility/aria/aria_techniques/using_the_link_role/ /en-US/docs/Web/Accessibility/ARIA/Reference/Roles/link_role +/en-US/docs/web/accessibility/aria/aria_techniques/using_the_log_role/ /en-US/docs/Web/Accessibility/ARIA/Reference/Roles/log_role +/en-US/docs/web/accessibility/aria/aria_techniques/using_the_presentation_role/ /en-US/docs/Web/Accessibility/ARIA/Reference/Roles/presentation_role +/en-US/docs/web/accessibility/aria/aria_techniques/using_the_progressbar_role/ /en-US/docs/Web/Accessibility/ARIA/Reference/Roles/progressbar_role +/en-US/docs/web/accessibility/aria/aria_techniques/using_the_radio_role/ /en-US/docs/Web/Accessibility/ARIA/Reference/Roles/radio_role +/en-US/docs/web/accessibility/aria/aria_techniques/using_the_slider_role/ /en-US/docs/Web/Accessibility/ARIA/Reference/Roles/slider_role +/en-US/docs/web/accessibility/aria/aria_techniques/using_the_status_role/ /en-US/docs/Web/Accessibility/ARIA/Reference/Roles/status_role +/en-US/docs/web/accessibility/aria/aria_techniques/using_the_toolbar_role/ /en-US/docs/Web/Accessibility/ARIA/Reference/Roles/toolbar_role /en-US/docs/web/api/DOMPoint/fromPoint /en-US/docs/Web/API/DOMPoint/fromPoint_static /en-US/docs/width /en-US/docs/Web/CSS/width /en-US/docs/window.captureEvents /en-US/docs/Web/API/Window/captureEvents @@ -14655,7 +15993,7 @@ /en-US/docs/window.document /en-US/docs/Web/API/Window/document /en-US/docs/window.dump /en-US/docs/Web/API/Window/dump /en-US/docs/window.escape /en-US/docs/Web/JavaScript/Reference/Global_Objects/escape -/en-US/docs/window.forward /en-US/docs/Web/API/Window/forward +/en-US/docs/window.forward /en-US/docs/Web/API/History/forward /en-US/docs/window.frames /en-US/docs/Web/API/Window/frames /en-US/docs/window.getSelection /en-US/docs/Web/API/Window/getSelection /en-US/docs/window.history /en-US/docs/Web/API/Window/history diff --git a/files/en-us/_wikihistory.json b/files/en-us/_wikihistory.json index 026f719c511d3ff..abdd0fb272bd373 100644 --- a/files/en-us/_wikihistory.json +++ b/files/en-us/_wikihistory.json @@ -73,22 +73,6 @@ "Sheppy" ] }, - "Games/Introduction_to_HTML5_Game_Development": { - "modified": "2020-10-27T19:24:21.503Z", - "contributors": [ - "escattone", - "chrisdavidmills", - "lexi1111", - "jswisher", - "wbamberg", - "fscholz", - "gauravrox", - "aamiryan23", - "jsx", - "Maijied", - "MakisMouzakitis" - ] - }, "Games/Publishing_games": { "modified": "2019-01-16T21:43:32.470Z", "contributors": ["wbamberg", "chrisdavidmills", "end3r"] @@ -1827,19 +1811,6 @@ "teoli" ] }, - "Glossary/Cryptographic_hash_function": { - "modified": "2019-12-08T08:53:55.136Z", - "contributors": [ - "mfuji09", - "wbamberg", - "sebastien-bartoli", - "marumari", - "lpiot", - "Andrew_Pfeiffer", - "kscarfone", - "teoli" - ] - }, "Glossary/Cryptography": { "modified": "2020-02-21T15:01:36.818Z", "contributors": [ @@ -1953,18 +1924,6 @@ "modified": "2019-03-23T22:10:49.789Z", "contributors": ["LaAzteca", "Sebastianz"] }, - "Glossary/Digest": { - "modified": "2019-03-23T23:04:10.174Z", - "contributors": [ - "joshuaptfan", - "Sodan", - "marumari", - "Andrew_Pfeiffer", - "hbloomer", - "kscarfone", - "teoli" - ] - }, "Glossary/Digital_certificate": { "modified": "2019-03-23T22:57:42.093Z", "contributors": [ @@ -3183,6 +3142,23 @@ "modified": "2019-05-31T08:14:09.470Z", "contributors": ["Sheppy", "chrisdavidmills", "andystevensname", "estelle"] }, + "Glossary/Layout_mode": { + "modified": "2020-07-07T12:36:23.002Z", + "contributors": [ + "wbamberg", + "lcchueri", + "chrisdavidmills", + "rachelandrew", + "mfluehr", + "Sebastianz", + "markg", + "evalica", + "velvel53", + "Sheppy", + "FredB", + "teoli" + ] + }, "Glossary/Layout_viewport": { "modified": "2020-03-27T15:15:46.041Z", "contributors": ["RafeyIqbalRahman", "Sheppy"] @@ -5771,10 +5747,6 @@ "unused" ] }, - "Learn_web_development/Core/Accessibility/CSS_and_JavaScript/Test_your_skills:_CSS_and_JavaScript_accessibility": { - "modified": "2020-07-16T22:40:20.219Z", - "contributors": ["chrisdavidmills"] - }, "Learn_web_development/Core/Accessibility/HTML": { "modified": "2020-11-20T01:54:13.621Z", "contributors": [ @@ -5840,10 +5812,18 @@ "qdirks" ] }, - "Learn_web_development/Core/Accessibility/Test_your_skills:_HTML_accessibility": { + "Learn_web_development/Core/Accessibility/Test_your_skills/CSS_and_JavaScript": { + "modified": "2020-07-16T22:40:20.219Z", + "contributors": ["chrisdavidmills"] + }, + "Learn_web_development/Core/Accessibility/Test_your_skills/HTML": { "modified": "2020-07-16T22:40:37.539Z", "contributors": ["chrisdavidmills"] }, + "Learn_web_development/Core/Accessibility/Test_your_skills/WAI-ARIA": { + "modified": "2020-11-13T16:57:24.326Z", + "contributors": ["BassOfBass", "chrisdavidmills"] + }, "Learn_web_development/Core/Accessibility/Tooling": { "modified": "2020-11-20T02:03:56.749Z", "contributors": [ @@ -5883,10 +5863,6 @@ "joshbader" ] }, - "Learn_web_development/Core/Accessibility/WAI-ARIA_basics/Test_your_skills:_WAI-ARIA": { - "modified": "2020-11-13T16:57:24.326Z", - "contributors": ["BassOfBass", "chrisdavidmills"] - }, "Learn_web_development/Core/Accessibility/What_is_accessibility": { "modified": "2020-10-04T01:37:18.886Z", "contributors": [ @@ -5954,15 +5930,6 @@ "Sebastianz" ] }, - "Learn_web_development/Core/CSS_layout/Flexbox_skills": { - "modified": "2020-07-16T22:27:33.630Z", - "contributors": [ - "chrisdavidmills", - "soham1sawant", - "vinaya22", - "rachelandrew" - ] - }, "Learn_web_development/Core/CSS_layout/Floats": { "modified": "2020-07-16T22:26:35.746Z", "contributors": [ @@ -5995,33 +5962,10 @@ "richardzacur" ] }, - "Learn_web_development/Core/CSS_layout/Floats_skills": { - "modified": "2020-11-08T17:35:30.832Z", - "contributors": [ - "ohaver", - "mjibrower", - "jpfkd", - "MelchiorIm3Tal", - "chrisdavidmills", - "kyonlee", - "rachelandrew" - ] - }, "Learn_web_development/Core/CSS_layout/Fundamental_Layout_Comprehension": { "modified": "2020-07-16T22:27:23.817Z", "contributors": ["chrisdavidmills", "rachelandrew"] }, - "Learn_web_development/Core/CSS_layout/Grid_skills": { - "modified": "2020-10-20T06:22:56.547Z", - "contributors": [ - "Oeekker", - "MelchiorIm3Tal", - "arjenlgill", - "santimirandarp", - "chrisdavidmills", - "rachelandrew" - ] - }, "Learn_web_development/Core/CSS_layout/Grids": { "modified": "2020-10-28T07:33:10.063Z", "contributors": [ @@ -6093,15 +6037,6 @@ "kruschk" ] }, - "Learn_web_development/Core/CSS_layout/Multicol_skills": { - "modified": "2020-07-16T22:27:35.746Z", - "contributors": [ - "jpfkd", - "MelchiorIm3Tal", - "chrisdavidmills", - "rachelandrew" - ] - }, "Learn_web_development/Core/CSS_layout/Multiple-column_Layout": { "modified": "2020-07-16T22:27:08.953Z", "contributors": [ @@ -6126,15 +6061,6 @@ "rachelandrew" ] }, - "Learn_web_development/Core/CSS_layout/Position_skills": { - "modified": "2020-07-16T22:27:34.985Z", - "contributors": [ - "jpfkd", - "MelchiorIm3Tal", - "chrisdavidmills", - "rachelandrew" - ] - }, "Learn_web_development/Core/CSS_layout/Positioning": { "modified": "2020-08-01T23:51:55.099Z", "contributors": [ @@ -6210,7 +6136,57 @@ "rachelandrew" ] }, - "Learn_web_development/Core/CSS_layout/rwd_skills": { + "Learn_web_development/Core/CSS_layout/Test_your_skills/Flexbox": { + "modified": "2020-07-16T22:27:33.630Z", + "contributors": [ + "chrisdavidmills", + "soham1sawant", + "vinaya22", + "rachelandrew" + ] + }, + "Learn_web_development/Core/CSS_layout/Test_your_skills/Floats": { + "modified": "2020-11-08T17:35:30.832Z", + "contributors": [ + "ohaver", + "mjibrower", + "jpfkd", + "MelchiorIm3Tal", + "chrisdavidmills", + "kyonlee", + "rachelandrew" + ] + }, + "Learn_web_development/Core/CSS_layout/Test_your_skills/Grid": { + "modified": "2020-10-20T06:22:56.547Z", + "contributors": [ + "Oeekker", + "MelchiorIm3Tal", + "arjenlgill", + "santimirandarp", + "chrisdavidmills", + "rachelandrew" + ] + }, + "Learn_web_development/Core/CSS_layout/Test_your_skills/Multicolumn": { + "modified": "2020-07-16T22:27:35.746Z", + "contributors": [ + "jpfkd", + "MelchiorIm3Tal", + "chrisdavidmills", + "rachelandrew" + ] + }, + "Learn_web_development/Core/CSS_layout/Test_your_skills/Position": { + "modified": "2020-07-16T22:27:34.985Z", + "contributors": [ + "jpfkd", + "MelchiorIm3Tal", + "chrisdavidmills", + "rachelandrew" + ] + }, + "Learn_web_development/Core/CSS_layout/Test_your_skills/Responsive_design": { "modified": "2020-07-16T22:27:36.041Z", "contributors": ["MelchiorIm3Tal", "chrisdavidmills", "rachelandrew"] }, @@ -6879,43 +6855,43 @@ "fscholz" ] }, - "Learn_web_development/Core/Scripting/Test_your_skills:_Arrays": { + "Learn_web_development/Core/Scripting/Test_your_skills/Arrays": { "modified": "2020-07-16T22:31:05.831Z", "contributors": ["vgiffin", "chrisdavidmills"] }, - "Learn_web_development/Core/Scripting/Test_your_skills:_Conditionals": { + "Learn_web_development/Core/Scripting/Test_your_skills/Conditionals": { "modified": "2020-07-16T22:31:45.710Z", "contributors": ["jpfkd", "jmliu", "chrisdavidmills"] }, - "Learn_web_development/Core/Scripting/Test_your_skills:_Events": { + "Learn_web_development/Core/Scripting/Test_your_skills/Events": { "modified": "2020-07-16T22:31:46.881Z", "contributors": ["chrisdavidmills"] }, - "Learn_web_development/Core/Scripting/Test_your_skills:_Functions": { + "Learn_web_development/Core/Scripting/Test_your_skills/Functions": { "modified": "2020-07-16T22:31:46.557Z", "contributors": ["chrisdavidmills"] }, - "Learn_web_development/Core/Scripting/Test_your_skills:_JSON": { + "Learn_web_development/Core/Scripting/Test_your_skills/JSON": { "modified": "2020-07-16T22:32:38.003Z", "contributors": ["chrisdavidmills", "blueblots"] }, - "Learn_web_development/Core/Scripting/Test_your_skills:_Loops": { + "Learn_web_development/Core/Scripting/Test_your_skills/Loops": { "modified": "2020-07-16T22:31:46.034Z", "contributors": ["neuroptera", "chrisdavidmills"] }, - "Learn_web_development/Core/Scripting/Test_your_skills:_Math": { + "Learn_web_development/Core/Scripting/Test_your_skills/Math": { "modified": "2020-07-31T08:15:10.749Z", "contributors": ["chrisdavidmills", "AJMcDee"] }, - "Learn_web_development/Core/Scripting/Test_your_skills:_Object_basics": { + "Learn_web_development/Core/Scripting/Test_your_skills/Object_basics": { "modified": "2020-12-11T06:18:00.445Z", "contributors": ["chrisdavidmills", "iJacKP", "neuroptera"] }, - "Learn_web_development/Core/Scripting/Test_your_skills:_Strings": { + "Learn_web_development/Core/Scripting/Test_your_skills/Strings": { "modified": "2020-07-16T22:31:05.493Z", "contributors": ["chrisdavidmills"] }, - "Learn_web_development/Core/Scripting/Test_your_skills:_variables": { + "Learn_web_development/Core/Scripting/Test_your_skills/Variables": { "modified": "2020-07-16T22:31:04.800Z", "contributors": ["neuroptera", "chrisdavidmills"] }, @@ -7303,10 +7279,6 @@ "richardzacur" ] }, - "Learn_web_development/Core/Structuring_content/HTML_images/Test_your_skills:_HTML_images": { - "modified": "2020-10-18T19:47:17.929Z", - "contributors": ["gdsimoes", "chrisdavidmills"] - }, "Learn_web_development/Core/Structuring_content/HTML_table_basics": { "modified": "2020-07-16T22:25:17.858Z", "contributors": [ @@ -7372,10 +7344,6 @@ "richardzacur" ] }, - "Learn_web_development/Core/Structuring_content/HTML_video_and_audio/Test_your_skills:_Multimedia_and_embedding": { - "modified": "2020-11-20T14:20:14.413Z", - "contributors": ["philou", "gdsimoes", "chrisdavidmills"] - }, "Learn_web_development/Core/Structuring_content/Headings_and_paragraphs": { "modified": "2020-10-29T23:24:18.960Z", "contributors": [ @@ -7539,18 +7507,26 @@ "npusr" ] }, - "Learn_web_development/Core/Structuring_content/Test_your_skills:_Advanced_HTML_text": { + "Learn_web_development/Core/Structuring_content/Test_your_skills/Advanced_HTML_text": { "modified": "2020-08-29T02:34:36.621Z", "contributors": ["SnakeWhisperer", "onurbasturk", "chrisdavidmills"] }, - "Learn_web_development/Core/Structuring_content/Test_your_skills:_HTML_text_basics": { + "Learn_web_development/Core/Structuring_content/Test_your_skills/HTML_text_basics": { "modified": "2020-08-27T05:38:52.761Z", "contributors": ["SnakeWhisperer", "chrisdavidmills"] }, - "Learn_web_development/Core/Structuring_content/Test_your_skills:_Links": { + "Learn_web_development/Core/Structuring_content/Test_your_skills/Images": { + "modified": "2020-10-18T19:47:17.929Z", + "contributors": ["gdsimoes", "chrisdavidmills"] + }, + "Learn_web_development/Core/Structuring_content/Test_your_skills/Links": { "modified": "2020-08-28T04:26:18.208Z", "contributors": ["SnakeWhisperer", "chrisdavidmills", "onurbasturk"] }, + "Learn_web_development/Core/Structuring_content/Test_your_skills/Multimedia_and_embedding": { + "modified": "2020-11-20T14:20:14.413Z", + "contributors": ["philou", "gdsimoes", "chrisdavidmills"] + }, "Learn_web_development/Core/Structuring_content/Webpage_metadata": { "modified": "2020-09-28T22:06:13.983Z", "contributors": [ @@ -7650,18 +7626,6 @@ "ExE-Boss" ] }, - "Learn_web_development/Core/Styling_basics/Basic_selectors/Selectors_Tasks": { - "modified": "2020-11-10T09:07:22.974Z", - "contributors": [ - "Re9iNee", - "impossibleshadow", - "chrisdavidmills", - "HenningTimm", - "blueblots", - "RafeyIqbalRahman", - "rachelandrew" - ] - }, "Learn_web_development/Core/Styling_basics/Basic_selectors/Type_Class_and_ID_Selectors": { "modified": "2020-10-15T19:45:39.626Z", "contributors": [ @@ -7702,10 +7666,6 @@ "gumchum" ] }, - "Learn_web_development/Core/Styling_basics/Cascade_tasks": { - "modified": "2020-07-16T22:29:36.222Z", - "contributors": ["blueblots", "RafeyIqbalRahman", "rachelandrew"] - }, "Learn_web_development/Core/Styling_basics/Combinators": { "modified": "2020-07-16T22:28:51.504Z", "contributors": [ @@ -7804,10 +7764,6 @@ "xp44mm" ] }, - "Learn_web_development/Core/Styling_basics/Images_tasks": { - "modified": "2020-07-16T22:29:35.047Z", - "contributors": ["avivmu", "blueblots", "RafeyIqbalRahman", "rachelandrew"] - }, "Learn_web_development/Core/Styling_basics/Organizing": { "modified": "2020-07-16T22:29:30.920Z", "contributors": [ @@ -7833,10 +7789,6 @@ "Gxz-NGU" ] }, - "Learn_web_development/Core/Styling_basics/Overflow_Tasks": { - "modified": "2020-07-16T22:29:33.802Z", - "contributors": ["avivmu", "blueblots", "RafeyIqbalRahman", "rachelandrew"] - }, "Learn_web_development/Core/Styling_basics/Pseudo_classes_and_elements": { "modified": "2020-07-16T22:28:42.196Z", "contributors": [ @@ -7864,10 +7816,6 @@ "mbrasseau" ] }, - "Learn_web_development/Core/Styling_basics/Sizing_tasks": { - "modified": "2020-07-16T22:29:34.677Z", - "contributors": ["jpfkd", "sakthivelsekar33", "blueblots", "rachelandrew"] - }, "Learn_web_development/Core/Styling_basics/Styling_a_bio_page": { "modified": "2020-11-20T01:07:05.733Z", "contributors": [ @@ -7898,13 +7846,49 @@ "richardzacur" ] }, - "Learn_web_development/Core/Styling_basics/Tables_tasks": { + "Learn_web_development/Core/Styling_basics/Test_your_skills/Backgrounds_and_borders": { + "modified": "2020-10-20T11:48:06.920Z", + "contributors": ["chrisdavidmills", "rachelandrew"] + }, + "Learn_web_development/Core/Styling_basics/Test_your_skills/Cascade": { + "modified": "2020-07-16T22:29:36.222Z", + "contributors": ["blueblots", "RafeyIqbalRahman", "rachelandrew"] + }, + "Learn_web_development/Core/Styling_basics/Test_your_skills/Images": { + "modified": "2020-07-16T22:29:35.047Z", + "contributors": ["avivmu", "blueblots", "RafeyIqbalRahman", "rachelandrew"] + }, + "Learn_web_development/Core/Styling_basics/Test_your_skills/Overflow": { + "modified": "2020-07-16T22:29:33.802Z", + "contributors": ["avivmu", "blueblots", "RafeyIqbalRahman", "rachelandrew"] + }, + "Learn_web_development/Core/Styling_basics/Test_your_skills/Selectors": { + "modified": "2020-11-10T09:07:22.974Z", + "contributors": [ + "Re9iNee", + "impossibleshadow", + "chrisdavidmills", + "HenningTimm", + "blueblots", + "RafeyIqbalRahman", + "rachelandrew" + ] + }, + "Learn_web_development/Core/Styling_basics/Test_your_skills/Sizing": { + "modified": "2020-07-16T22:29:34.677Z", + "contributors": ["jpfkd", "sakthivelsekar33", "blueblots", "rachelandrew"] + }, + "Learn_web_development/Core/Styling_basics/Test_your_skills/Tables": { "modified": "2020-10-03T15:51:56.524Z", "contributors": ["JennyDC", "blueblots", "rachelandrew"] }, - "Learn_web_development/Core/Styling_basics/Test_your_skills_backgrounds_and_borders": { - "modified": "2020-10-20T11:48:06.920Z", - "contributors": ["chrisdavidmills", "rachelandrew"] + "Learn_web_development/Core/Styling_basics/Test_your_skills/Values": { + "modified": "2020-10-03T15:56:43.195Z", + "contributors": ["JennyDC", "blueblots", "rachelandrew"] + }, + "Learn_web_development/Core/Styling_basics/Test_your_skills/Writing_modes": { + "modified": "2020-07-16T22:29:33.477Z", + "contributors": ["blueblots", "rachelandrew"] }, "Learn_web_development/Core/Styling_basics/Values_and_units": { "modified": "2020-09-27T15:04:48.072Z", @@ -7924,10 +7908,6 @@ "zbjornson" ] }, - "Learn_web_development/Core/Styling_basics/Values_tasks": { - "modified": "2020-10-03T15:56:43.195Z", - "contributors": ["JennyDC", "blueblots", "rachelandrew"] - }, "Learn_web_development/Core/Styling_basics/What_is_CSS": { "modified": "2020-11-20T01:04:49.095Z", "contributors": [ @@ -7939,10 +7919,6 @@ "MyNameIsBond" ] }, - "Learn_web_development/Core/Styling_basics/Writing_Modes_Tasks": { - "modified": "2020-07-16T22:29:33.477Z", - "contributors": ["blueblots", "rachelandrew"] - }, "Learn_web_development/Core/Text_styling": { "modified": "2020-07-16T22:25:57.072Z", "contributors": [ @@ -8151,7 +8127,7 @@ "ZeroUnderscoreOu" ] }, - "Learn_web_development/Extensions/Advanced_JavaScript_objects/Test_your_skills:_Object-oriented_JavaScript": { + "Learn_web_development/Extensions/Advanced_JavaScript_objects/Test_your_skills/Object-oriented_JavaScript": { "modified": "2020-08-12T12:48:24.778Z", "contributors": ["A.Faturechi", "abinashLin", "chrisdavidmills"] }, @@ -8771,31 +8747,31 @@ "notabene" ] }, - "Learn_web_development/Extensions/Forms/Test_your_skills:_Advanced_styling": { + "Learn_web_development/Extensions/Forms/Test_your_skills/Advanced_styling": { "modified": "2020-07-16T22:22:12.770Z", "contributors": ["chrisdavidmills"] }, - "Learn_web_development/Extensions/Forms/Test_your_skills:_Basic_controls": { + "Learn_web_development/Extensions/Forms/Test_your_skills/Basic_controls": { "modified": "2020-07-16T22:22:10.786Z", "contributors": ["chrisdavidmills"] }, - "Learn_web_development/Extensions/Forms/Test_your_skills:_Form_structure": { + "Learn_web_development/Extensions/Forms/Test_your_skills/Form_structure": { "modified": "2020-07-16T22:22:10.470Z", "contributors": ["chrisdavidmills"] }, - "Learn_web_development/Extensions/Forms/Test_your_skills:_Form_validation": { + "Learn_web_development/Extensions/Forms/Test_your_skills/Form_validation": { "modified": "2020-07-16T22:22:13.092Z", "contributors": ["chrisdavidmills"] }, - "Learn_web_development/Extensions/Forms/Test_your_skills:_HTML5_controls": { + "Learn_web_development/Extensions/Forms/Test_your_skills/Input_types": { "modified": "2020-07-16T22:22:11.117Z", "contributors": ["chrisdavidmills"] }, - "Learn_web_development/Extensions/Forms/Test_your_skills:_Other_controls": { + "Learn_web_development/Extensions/Forms/Test_your_skills/Other_controls": { "modified": "2020-07-16T22:22:11.804Z", "contributors": ["chrisdavidmills"] }, - "Learn_web_development/Extensions/Forms/Test_your_skills:_Styling_basics": { + "Learn_web_development/Extensions/Forms/Test_your_skills/Styling_basics": { "modified": "2020-07-16T22:22:12.453Z", "contributors": ["chrisdavidmills"] }, @@ -10816,135 +10792,6 @@ "Andrew_Pfeiffer" ] }, - "Learn_web_development/Howto/Solve_HTML_problems/Add_a_hit_map_on_top_of_an_image": { - "modified": "2020-07-16T22:22:42.758Z", - "contributors": ["ezrinjaz", "hbloomer", "Andrew_Pfeiffer"] - }, - "Learn_web_development/Howto/Solve_HTML_problems/Author_fast-loading_HTML_pages": { - "modified": "2020-07-16T22:22:31.788Z", - "contributors": [ - "Sheppy", - "estelle", - "sideshowbarker", - "karimos129", - "spencercorwin", - "SphinxKnight", - "chrisdavidmills", - "ziyadElon", - "Harinderpreet", - "stuartharvie", - "RafeyIqbalRahman", - "ishan123456789", - "abt8601", - "xfq", - "andygongea", - "rfc791", - "fscholz", - "Jeremie", - "kscarfone", - "dbs", - "gmerencio", - "gbrown", - "haboqueferus", - "brunoais", - "teoli", - "ethertank", - "tolbon", - "leo89", - "tw2113", - "inma_610", - "xaky", - "Shz", - "JaredWBurt", - "alicethomas222", - "peterson.victor222", - "Mgjbot", - "Carrie zhxj", - "Ptak82", - "Satyr-wayfarer", - "NickolayBot", - "Dria", - "Yworfg", - "cbiesinger", - "Nerf", - "Grauw", - "CitizenK", - "Jens.B" - ] - }, - "Learn_web_development/Howto/Solve_HTML_problems/Cheatsheet": { - "modified": "2020-07-16T22:22:43.887Z", - "contributors": [ - "Yel-Martinez-Consultor-Seo", - "sideshowbarker", - "verde79", - "sksankarraj", - "Quantzilla", - "Johanancuriel", - "SethClydesdale", - "arkanciscan", - "khalid32", - "jswisher", - "fachrulrazy", - "Andrew_Pfeiffer", - "SphinxKnight", - "dvincent", - "hbloomer", - "chadsansing", - "Jeremie" - ] - }, - "Learn_web_development/Howto/Solve_HTML_problems/Define_terms_with_HTML": { - "modified": "2020-07-16T22:22:41.646Z", - "contributors": [ - "AlexK89", - "jnegara", - "Jeremie", - "Andrew_Pfeiffer", - "Sheppy", - "MohammedAdam", - "hbloomer" - ] - }, - "Learn_web_development/Howto/Solve_HTML_problems/Use_JavaScript_within_a_webpage": { - "modified": "2020-07-16T22:22:39.990Z", - "contributors": ["RomainLanz", "Jeremie", "Andrew_Pfeiffer"] - }, - "Learn_web_development/Howto/Solve_HTML_problems/Use_data_attributes": { - "modified": "2020-07-16T22:22:34.241Z", - "contributors": [ - "vnctdj", - "LoVo666", - "jmstfv", - "mfuji09", - "kenny-evitt", - "Enrico_Polanski", - "ryanve", - "calebmosher", - "chrisdavidmills", - "rnacken", - "Sheppy", - "prusse-martin", - "torazaburo", - "jacksonrayhamilton", - "drj11", - "Manojkr", - "Speich", - "sam_eaton", - "bcruddy", - "teckno101", - "lieuwex", - "robinpokorny", - "rvighne", - "andrew.carpenter", - "Jeremie", - "magnetikonline", - "jswisher", - "kscarfone", - "teoli", - "groovecoder" - ] - }, "Learn_web_development/Howto/Solve_JavaScript_problems": { "modified": "2020-07-16T22:33:08.616Z", "contributors": [ @@ -15080,10 +14927,6 @@ "ccarruitero" ] }, - "Mozilla/Add-ons/WebExtensions/Browser_compatibility_for_manifest.json": { - "modified": "2020-11-03T15:02:11.613Z", - "contributors": ["9999472", "wbamberg", "marcoscaceres", "ExE-Boss"] - }, "Mozilla/Add-ons/WebExtensions/Browser_support_for_JavaScript_APIs": { "modified": "2020-10-15T20:55:17.532Z", "contributors": [ @@ -27322,10 +27165,6 @@ "JesseW" ] }, - "Web/API/Document/copy_event": { - "modified": "2020-10-15T22:16:12.053Z", - "contributors": ["mfuji09", "wbamberg"] - }, "Web/API/Document/createAttribute": { "modified": "2020-10-15T21:04:22.086Z", "contributors": [ @@ -27762,10 +27601,6 @@ "sicking" ] }, - "Web/API/Document/cut_event": { - "modified": "2020-10-15T22:16:11.993Z", - "contributors": ["mfuji09", "wbamberg"] - }, "Web/API/Document/defaultView": { "modified": "2020-10-15T21:04:28.447Z", "contributors": [ @@ -28860,10 +28695,6 @@ "JesseW" ] }, - "Web/API/Document/paste_event": { - "modified": "2020-10-15T22:16:13.117Z", - "contributors": ["mfuji09", "wbamberg"] - }, "Web/API/Document/pictureInPictureElement": { "modified": "2020-10-25T11:04:35.581Z", "contributors": ["chrisdavidmills", "germain"] @@ -37614,40 +37445,6 @@ "McGurk" ] }, - "Web/API/HTMLElement/copy_event": { - "modified": "2020-10-15T21:03:53.270Z", - "contributors": [ - "mfuji09", - "hoang4", - "mfluehr", - "fscholz", - "valtlai", - "teoli", - "kscarfone", - "nairakhil13", - "Sheppy", - "ethertank", - "ziyunfei", - "Mgjbot", - "Potappo" - ] - }, - "Web/API/HTMLElement/cut_event": { - "modified": "2020-10-15T21:03:56.356Z", - "contributors": [ - "mfluehr", - "fscholz", - "valtlai", - "teoli", - "kscarfone", - "nairakhil13", - "Sheppy", - "ethertank", - "ziyunfei", - "Mgjbot", - "Potappo" - ] - }, "Web/API/HTMLElement/dataset": { "modified": "2020-11-29T09:53:07.128Z", "contributors": [ @@ -38042,25 +37839,6 @@ "cvrebert" ] }, - "Web/API/HTMLElement/paste_event": { - "modified": "2020-10-15T21:03:50.733Z", - "contributors": [ - "mfluehr", - "Mooocraft", - "fscholz", - "mfuji09", - "depthdev", - "valtlai", - "teoli", - "kscarfone", - "nairakhil13", - "Sheppy", - "ethertank", - "ziyunfei", - "Mgjbot", - "Potappo" - ] - }, "Web/API/HTMLElement/tabIndex": { "modified": "2020-10-15T21:06:27.399Z", "contributors": [ @@ -43934,27 +43712,6 @@ "Masayuki" ] }, - "Web/API/KeyboardEvent/initKeyEvent": { - "modified": "2019-03-24T00:10:53.315Z", - "contributors": [ - "mfluehr", - "fscholz", - "Noitidart", - "teoli", - "MHasan", - "willlma", - "kscarfone", - "Sheppy", - "mcomella", - "Jorend", - "Nickolay", - "Ynvich", - "Ptak82", - "Mgjbot", - "DBaron", - "Gary.johnson.53" - ] - }, "Web/API/KeyboardEvent/initKeyboardEvent": { "modified": "2019-03-23T23:04:44.260Z", "contributors": ["mfluehr", "wbamberg", "fscholz", "teoli"] @@ -46296,6 +46053,28 @@ "NickDesaulniers" ] }, + "Web/API/Media_Source_Extensions_API/DASH_Adaptive_Streaming": { + "modified": "2020-11-09T07:34:43.578Z", + "contributors": [ + "mfuji09", + "Sidewinder53", + "DeividasBakanas", + "formatkaka", + "chrysn", + "LeroyScandal", + "wbamberg", + "jswisher", + "wyrewolwerowany", + "anotherkabab", + "rogerxas", + "teoli", + "gmarty", + "Kinetik", + "kscarfone", + "sworkman", + "joshmoz" + ] + }, "Web/API/Media_Source_Extensions_API/Transcoding_assets_for_MSE": { "modified": "2019-11-17T06:14:01.055Z", "contributors": [ @@ -53707,10 +53486,6 @@ "modified": "2020-10-15T22:13:26.613Z", "contributors": ["Sheppy"] }, - "Web/API/RTCIceCandidateStats/deleted": { - "modified": "2020-10-15T22:15:50.914Z", - "contributors": ["Sheppy"] - }, "Web/API/RTCIceCandidateStats/port": { "modified": "2020-10-15T22:15:52.213Z", "contributors": ["Sheppy"] @@ -53723,18 +53498,10 @@ "modified": "2020-10-15T22:12:42.943Z", "contributors": ["Sheppy"] }, - "Web/API/RTCIceCandidateStats/relayProtocol": { - "modified": "2020-10-15T22:12:42.881Z", - "contributors": ["Sheppy"] - }, "Web/API/RTCIceCandidateStats/transportId": { "modified": "2020-10-15T22:15:52.263Z", "contributors": ["sideshowbarker", "Sheppy"] }, - "Web/API/RTCIceCandidateStats/url": { - "modified": "2020-10-15T22:15:52.214Z", - "contributors": ["guo-sun", "Sheppy"] - }, "Web/API/RTCIceParameters": { "modified": "2020-10-15T22:06:42.205Z", "contributors": ["Sheppy"] @@ -56154,18 +55921,6 @@ "modified": "2020-10-15T21:53:51.528Z", "contributors": ["fscholz", "Sebastianz"] }, - "Web/API/SVGCursorElement": { - "modified": "2020-10-15T21:08:58.922Z", - "contributors": [ - "krosylight", - "fscholz", - "jpmedley", - "Sebastianz", - "kscarfone", - "Sheppy", - "Jeremie" - ] - }, "Web/API/SVGDefsElement": { "modified": "2020-10-15T21:10:22.009Z", "contributors": [ @@ -56239,16 +55994,6 @@ "Jeremie" ] }, - "Web/API/SVGEvent": { - "modified": "2019-04-04T19:07:39.265Z", - "contributors": [ - "chrisdavidmills", - "pcat", - "kscarfone", - "fscholz", - "rabimba" - ] - }, "Web/API/SVGFEBlendElement": { "modified": "2020-10-15T21:53:39.956Z", "contributors": ["fscholz", "Sebastianz"] @@ -56360,37 +56105,6 @@ "Jeremie" ] }, - "Web/API/SVGFontElement": { - "modified": "2020-10-15T21:10:05.890Z", - "contributors": [ - "fscholz", - "Sebastianz", - "kscarfone", - "Sheppy", - "ethertank", - "Jeremie" - ] - }, - "Web/API/SVGFontFaceElement": { - "modified": "2020-10-15T21:10:09.511Z", - "contributors": ["fscholz", "Sebastianz", "kscarfone", "Sheppy", "Jeremie"] - }, - "Web/API/SVGFontFaceFormatElement": { - "modified": "2020-10-15T21:10:11.216Z", - "contributors": ["fscholz", "Sebastianz", "kscarfone", "Sheppy", "Jeremie"] - }, - "Web/API/SVGFontFaceNameElement": { - "modified": "2020-10-15T21:10:11.254Z", - "contributors": ["fscholz", "Sebastianz", "kscarfone", "Sheppy", "Jeremie"] - }, - "Web/API/SVGFontFaceSrcElement": { - "modified": "2020-10-15T21:10:07.275Z", - "contributors": ["fscholz", "Sebastianz", "kscarfone", "Sheppy", "Jeremie"] - }, - "Web/API/SVGFontFaceUriElement": { - "modified": "2020-10-15T21:10:06.547Z", - "contributors": ["fscholz", "Sebastianz", "kscarfone", "Sheppy", "Jeremie"] - }, "Web/API/SVGForeignObjectElement": { "modified": "2020-10-15T21:10:09.694Z", "contributors": [ @@ -56437,14 +56151,6 @@ "modified": "2020-10-15T21:51:18.963Z", "contributors": ["fscholz", "jpmedley", "Sebastianz"] }, - "Web/API/SVGGlyphElement": { - "modified": "2020-10-15T21:10:10.039Z", - "contributors": ["fscholz", "Sebastianz", "kscarfone", "Sheppy", "Jeremie"] - }, - "Web/API/SVGGlyphRefElement": { - "modified": "2020-10-15T21:53:39.561Z", - "contributors": ["fscholz", "Sebastianz"] - }, "Web/API/SVGGradientElement": { "modified": "2020-10-15T21:09:23.191Z", "contributors": [ @@ -56461,26 +56167,10 @@ "modified": "2020-10-15T21:51:27.873Z", "contributors": ["mfuji09", "fscholz", "libbymc", "Sebastianz"] }, - "Web/API/SVGGraphicsElement/copy_event": { - "modified": "2020-10-15T22:23:53.813Z", - "contributors": ["Sebastianz"] - }, - "Web/API/SVGGraphicsElement/cut_event": { - "modified": "2020-10-15T22:23:54.745Z", - "contributors": ["Sebastianz"] - }, "Web/API/SVGGraphicsElement/getBBox": { "modified": "2020-08-08T13:10:10.615Z", "contributors": ["Zearin_Galaurum", "mfuji09", "voxspox", "maxzeroedge"] }, - "Web/API/SVGGraphicsElement/paste_event": { - "modified": "2020-10-15T22:23:54.359Z", - "contributors": ["Sebastianz"] - }, - "Web/API/SVGHKernElement": { - "modified": "2020-10-15T21:10:07.953Z", - "contributors": ["fscholz", "Sebastianz", "kscarfone", "Sheppy", "Jeremie"] - }, "Web/API/SVGImageElement": { "modified": "2020-10-15T21:09:22.741Z", "contributors": [ @@ -56589,10 +56279,6 @@ "modified": "2020-10-15T21:53:39.187Z", "contributors": ["sideshowbarker", "fscholz", "Sebastianz"] }, - "Web/API/SVGMissingGlyphElement": { - "modified": "2020-10-15T21:10:07.770Z", - "contributors": ["fscholz", "Sebastianz", "kscarfone", "Sheppy", "Jeremie"] - }, "Web/API/SVGNumber": { "modified": "2020-10-15T21:10:49.852Z", "contributors": [ @@ -56820,10 +56506,6 @@ "Jeremie" ] }, - "Web/API/SVGTRefElement": { - "modified": "2020-10-15T21:10:10.455Z", - "contributors": ["fscholz", "Sebastianz", "kscarfone", "Sheppy", "Jeremie"] - }, "Web/API/SVGTSpanElement": { "modified": "2020-10-15T21:10:08.952Z", "contributors": [ @@ -56923,10 +56605,6 @@ "Jeremie" ] }, - "Web/API/SVGVKernElement": { - "modified": "2020-10-15T21:10:07.746Z", - "contributors": ["fscholz", "Sebastianz", "kscarfone", "Sheppy", "Jeremie"] - }, "Web/API/SVGViewElement": { "modified": "2020-10-15T21:11:01.118Z", "contributors": [ @@ -58115,19 +57793,6 @@ "kscarfone" ] }, - "Web/API/ServiceWorkerContainer/error_event": { - "modified": "2020-10-15T21:33:32.607Z", - "contributors": [ - "Wind1808", - "anlex-N", - "daniel.z.tg", - "sideshowbarker", - "fscholz", - "jpmedley", - "chrisdavidmills", - "kscarfone" - ] - }, "Web/API/ServiceWorkerContainer/getRegistration": { "modified": "2020-10-15T21:32:19.814Z", "contributors": [ @@ -65833,24 +65498,6 @@ "alecananian" ] }, - "Web/API/Window/back": { - "modified": "2020-02-23T02:06:28.448Z", - "contributors": [ - "mfuji09", - "bershanskiy", - "Bzbarsky", - "Sheppy", - "Ac1521", - "fscholz", - "teoli", - "kohei.yoshino", - "ethertank", - "Mgjbot", - "Dria", - "Callek", - "JesseW" - ] - }, "Web/API/Window/beforeinstallprompt_event": { "modified": "2020-10-15T21:36:30.007Z", "contributors": [ @@ -66237,10 +65884,6 @@ "JesseW" ] }, - "Web/API/Window/copy_event": { - "modified": "2020-10-15T22:16:13.286Z", - "contributors": ["mfuji09", "wbamberg"] - }, "Web/API/Window/createImageBitmap": { "modified": "2020-10-15T21:37:56.407Z", "contributors": [ @@ -66310,10 +65953,6 @@ "arthurevans" ] }, - "Web/API/Window/cut_event": { - "modified": "2020-10-15T22:16:14.635Z", - "contributors": ["mfuji09", "wbamberg"] - }, "Web/API/Window/devicePixelRatio": { "modified": "2020-10-15T21:28:17.748Z", "contributors": [ @@ -66567,22 +66206,6 @@ "modified": "2020-10-15T22:15:43.366Z", "contributors": ["wbamberg", "mfuji09"] }, - "Web/API/Window/forward": { - "modified": "2020-02-23T02:09:05.828Z", - "contributors": [ - "mfuji09", - "bershanskiy", - "Bzbarsky", - "Sheppy", - "SphinxKnight", - "fscholz", - "teoli", - "kohei.yoshino", - "Mgjbot", - "Dria", - "JesseW" - ] - }, "Web/API/Window/frameElement": { "modified": "2020-10-15T21:08:57.575Z", "contributors": [ @@ -67658,10 +67281,6 @@ "JesseW" ] }, - "Web/API/Window/paste_event": { - "modified": "2020-10-15T22:16:14.230Z", - "contributors": ["mfuji09", "wbamberg"] - }, "Web/API/Window/performance": { "modified": "2020-10-15T21:22:10.802Z", "contributors": [ @@ -68668,30 +68287,6 @@ "modified": "2020-12-12T15:32:04.243Z", "contributors": ["Rumyra"] }, - "Web/API/Window/showModalDialog": { - "modified": "2020-10-15T21:10:51.525Z", - "contributors": [ - "mfuji09", - "Tigt", - "SphinxKnight", - "lucian95", - "chrisdavidmills", - "teoli", - "cvrebert", - "jpmedley", - "fscholz", - "dhodder", - "jain.arpit.r", - "Rugby", - "kohei.yoshino", - "iamanupmenon", - "ethertank", - "Sheppy", - "Neil", - "George3", - "Mgjbot" - ] - }, "Web/API/Window/showOpenFilePicker": { "modified": "2020-12-12T15:22:58.168Z", "contributors": ["Rumyra"] @@ -69663,10 +69258,6 @@ "louisremi" ] }, - "Web/API/XMLHttpRequest/channel": { - "modified": "2019-04-01T10:07:55.290Z", - "contributors": ["Sheppy", "teoli", "MashKao"] - }, "Web/API/XMLHttpRequest/error_event": { "modified": "2020-10-15T21:19:53.429Z", "contributors": [ @@ -69756,18 +69347,6 @@ "louisremi" ] }, - "Web/API/XMLHttpRequest/mozAnon": { - "modified": "2019-03-23T22:32:59.152Z", - "contributors": ["Sheppy", "david_ross", "MashKao"] - }, - "Web/API/XMLHttpRequest/mozBackgroundRequest": { - "modified": "2019-03-23T22:32:48.788Z", - "contributors": ["Sheppy", "david_ross", "MashKao"] - }, - "Web/API/XMLHttpRequest/mozSystem": { - "modified": "2019-03-23T22:32:57.199Z", - "contributors": ["Sheppy", "david_ross", "MashKao"] - }, "Web/API/XMLHttpRequest/open": { "modified": "2020-10-15T21:40:00.147Z", "contributors": [ @@ -70290,14 +69869,6 @@ "modified": "2020-10-15T22:12:44.902Z", "contributors": ["Sebastianz"] }, - "Web/API/XPathException": { - "modified": "2020-10-15T22:12:44.764Z", - "contributors": ["Sebastianz"] - }, - "Web/API/XPathException/code": { - "modified": "2020-10-15T22:12:44.730Z", - "contributors": ["Sebastianz"] - }, "Web/API/XPathExpression": { "modified": "2020-10-15T21:03:49.074Z", "contributors": [ @@ -71360,11 +70931,11 @@ "fscholz" ] }, - "Web/Accessibility/ARIA/ARIA_Guides": { + "Web/Accessibility/ARIA/Guides": { "modified": "2019-03-24T00:13:12.236Z", "contributors": ["SphinxKnight", "sidgan", "Sheppy", "hhillen"] }, - "Web/Accessibility/ARIA/ARIA_Live_Regions": { + "Web/Accessibility/ARIA/Guides/Live_regions": { "modified": "2020-08-04T14:52:30.693Z", "contributors": [ "chrisdavidmills", @@ -71386,7 +70957,21 @@ "Aaronlev" ] }, - "Web/Accessibility/ARIA/ARIA_Screen_Reader_Implementors_Guide": { + "Web/Accessibility/ARIA/Guides/Multipart_labels": { + "modified": "2019-08-06T19:47:32.075Z", + "contributors": [ + "Tigt", + "dkocho4", + "david_ross", + "kscarfone", + "StephenKelly", + "Kritz", + "Fredchat", + "Sheppy", + "Aaronlev" + ] + }, + "Web/Accessibility/ARIA/Guides/Screen_Reader_Implementors": { "modified": "2019-03-23T23:59:09.827Z", "contributors": [ "Fredchat", @@ -71396,7 +70981,7 @@ "Aaronlev" ] }, - "Web/Accessibility/ARIA/ARIA_Techniques": { + "Web/Accessibility/ARIA/Guides/Techniques": { "modified": "2020-12-08T23:20:53.939Z", "contributors": [ "skkiennhtg2327", @@ -71431,7 +71016,7 @@ "SteveLee" ] }, - "Web/Accessibility/ARIA/How_to_file_ARIA-related_bugs": { + "Web/Accessibility/ARIA/How_to/File_ARIA-related_bugs": { "modified": "2019-03-24T00:12:10.850Z", "contributors": [ "chrisdavidmills", @@ -71441,21 +71026,7 @@ "Aaronlev" ] }, - "Web/Accessibility/ARIA/Multipart_labels": { - "modified": "2019-08-06T19:47:32.075Z", - "contributors": [ - "Tigt", - "dkocho4", - "david_ross", - "kscarfone", - "StephenKelly", - "Kritz", - "Fredchat", - "Sheppy", - "Aaronlev" - ] - }, - "Web/Accessibility/ARIA/Roles": { + "Web/Accessibility/ARIA/Reference/Roles": { "modified": "2020-04-01T14:49:41.249Z", "contributors": [ "chrisdavidmills", @@ -71469,7 +71040,7 @@ "irenesmith" ] }, - "Web/Accessibility/ARIA/Roles/alert_role": { + "Web/Accessibility/ARIA/Reference/Roles/alert_role": { "modified": "2019-06-12T10:04:04.447Z", "contributors": [ "chrisdavidmills", @@ -71479,7 +71050,7 @@ "ShaneHudson" ] }, - "Web/Accessibility/ARIA/Roles/application_role": { + "Web/Accessibility/ARIA/Reference/Roles/application_role": { "modified": "2019-06-12T10:03:49.630Z", "contributors": [ "chrisdavidmills", @@ -71489,7 +71060,7 @@ "MarcoZ" ] }, - "Web/Accessibility/ARIA/Roles/article_role": { + "Web/Accessibility/ARIA/Reference/Roles/article_role": { "modified": "2019-06-12T10:03:27.779Z", "contributors": [ "chrisdavidmills", @@ -71499,7 +71070,7 @@ "MarcoZ" ] }, - "Web/Accessibility/ARIA/Roles/banner_role": { + "Web/Accessibility/ARIA/Reference/Roles/banner_role": { "modified": "2019-09-05T17:08:19.123Z", "contributors": [ "seizo3", @@ -71515,7 +71086,7 @@ "hhillen" ] }, - "Web/Accessibility/ARIA/Roles/button_role": { + "Web/Accessibility/ARIA/Reference/Roles/button_role": { "modified": "2019-12-18T11:28:09.249Z", "contributors": [ "brennanyoung", @@ -71554,7 +71125,7 @@ "hhillen" ] }, - "Web/Accessibility/ARIA/Roles/cell_role": { + "Web/Accessibility/ARIA/Reference/Roles/cell_role": { "modified": "2019-06-12T10:02:32.719Z", "contributors": [ "chrisdavidmills", @@ -71564,7 +71135,7 @@ "estelle" ] }, - "Web/Accessibility/ARIA/Roles/checkbox_role": { + "Web/Accessibility/ARIA/Reference/Roles/checkbox_role": { "modified": "2019-06-12T10:02:22.486Z", "contributors": [ "chrisdavidmills", @@ -71586,15 +71157,15 @@ "hhillen" ] }, - "Web/Accessibility/ARIA/Roles/comment_role": { + "Web/Accessibility/ARIA/Reference/Roles/comment_role": { "modified": "2020-04-01T14:51:41.375Z", "contributors": ["chrisdavidmills"] }, - "Web/Accessibility/ARIA/Roles/complementary_role": { + "Web/Accessibility/ARIA/Reference/Roles/complementary_role": { "modified": "2019-12-02T12:34:26.730Z", "contributors": ["jendowns", "chrisdavidmills", "estelle", "ericwbailey"] }, - "Web/Accessibility/ARIA/Roles/contentinfo_role": { + "Web/Accessibility/ARIA/Reference/Roles/contentinfo_role": { "modified": "2019-06-12T10:01:20.155Z", "contributors": [ "chrisdavidmills", @@ -71604,7 +71175,7 @@ "ericwbailey" ] }, - "Web/Accessibility/ARIA/Roles/dialog_role": { + "Web/Accessibility/ARIA/Reference/Roles/dialog_role": { "modified": "2020-06-09T09:40:48.789Z", "contributors": [ "Coogie", @@ -71633,7 +71204,7 @@ "hhillen" ] }, - "Web/Accessibility/ARIA/Roles/document_role": { + "Web/Accessibility/ARIA/Reference/Roles/document_role": { "modified": "2019-06-12T10:01:04.740Z", "contributors": [ "chrisdavidmills", @@ -71643,7 +71214,7 @@ "MarcoZ" ] }, - "Web/Accessibility/ARIA/Roles/feed_role": { + "Web/Accessibility/ARIA/Reference/Roles/feed_role": { "modified": "2020-09-14T07:43:36.672Z", "contributors": [ "Chudesnov", @@ -71655,7 +71226,7 @@ "MarcoZ" ] }, - "Web/Accessibility/ARIA/Roles/figure_role": { + "Web/Accessibility/ARIA/Reference/Roles/figure_role": { "modified": "2019-06-12T10:00:34.077Z", "contributors": [ "chrisdavidmills", @@ -71666,7 +71237,7 @@ "jswisher" ] }, - "Web/Accessibility/ARIA/Roles/form_role": { + "Web/Accessibility/ARIA/Reference/Roles/form_role": { "modified": "2020-02-07T21:01:35.975Z", "contributors": [ "scottaohara", @@ -71679,7 +71250,7 @@ "ericwbailey" ] }, - "Web/Accessibility/ARIA/Roles/grid_role": { + "Web/Accessibility/ARIA/Reference/Roles/grid_role": { "modified": "2020-07-10T14:08:20.874Z", "contributors": [ "ypaulsussman", @@ -71696,11 +71267,11 @@ "ericwbailey" ] }, - "Web/Accessibility/ARIA/Roles/gridcell_role": { + "Web/Accessibility/ARIA/Reference/Roles/gridcell_role": { "modified": "2019-06-12T10:00:04.480Z", "contributors": ["chrisdavidmills", "estelle", "ericwbailey"] }, - "Web/Accessibility/ARIA/Roles/heading_role": { + "Web/Accessibility/ARIA/Reference/Roles/heading_role": { "modified": "2019-06-12T09:59:56.555Z", "contributors": [ "chrisdavidmills", @@ -71710,11 +71281,11 @@ "MarcoZ" ] }, - "Web/Accessibility/ARIA/Roles/list_role": { + "Web/Accessibility/ARIA/Reference/Roles/list_role": { "modified": "2020-09-04T07:02:34.267Z", "contributors": ["beheh", "chrisdavidmills", "estelle"] }, - "Web/Accessibility/ARIA/Roles/listbox_role": { + "Web/Accessibility/ARIA/Reference/Roles/listbox_role": { "modified": "2019-10-05T04:29:01.082Z", "contributors": [ "HiEv", @@ -71733,11 +71304,11 @@ "hhillen" ] }, - "Web/Accessibility/ARIA/Roles/listitem_role": { + "Web/Accessibility/ARIA/Reference/Roles/listitem_role": { "modified": "2019-07-18T02:57:19.880Z", "contributors": ["SphinxKnight", "spadgos", "chrisdavidmills", "estelle"] }, - "Web/Accessibility/ARIA/Roles/main_role": { + "Web/Accessibility/ARIA/Reference/Roles/main_role": { "modified": "2019-06-12T09:58:41.790Z", "contributors": [ "chrisdavidmills", @@ -71747,11 +71318,11 @@ "yatil" ] }, - "Web/Accessibility/ARIA/Roles/mark_role": { + "Web/Accessibility/ARIA/Reference/Roles/mark_role": { "modified": "2020-04-01T14:51:51.749Z", "contributors": ["chrisdavidmills"] }, - "Web/Accessibility/ARIA/Roles/navigation_role": { + "Web/Accessibility/ARIA/Reference/Roles/navigation_role": { "modified": "2019-07-16T09:09:44.653Z", "contributors": [ "KevinBatdorf", @@ -71763,7 +71334,7 @@ "ericwbailey" ] }, - "Web/Accessibility/ARIA/Roles/region_role": { + "Web/Accessibility/ARIA/Reference/Roles/region_role": { "modified": "2019-06-12T09:58:16.194Z", "contributors": [ "chrisdavidmills", @@ -71775,11 +71346,11 @@ "ericwbailey" ] }, - "Web/Accessibility/ARIA/Roles/row_role": { + "Web/Accessibility/ARIA/Reference/Roles/row_role": { "modified": "2019-06-12T09:58:08.990Z", "contributors": ["chrisdavidmills", "PickensC", "estelle"] }, - "Web/Accessibility/ARIA/Roles/rowgroup_role": { + "Web/Accessibility/ARIA/Reference/Roles/rowgroup_role": { "modified": "2019-06-12T09:57:58.382Z", "contributors": [ "chrisdavidmills", @@ -71789,7 +71360,7 @@ "yatil" ] }, - "Web/Accessibility/ARIA/Roles/search_role": { + "Web/Accessibility/ARIA/Reference/Roles/search_role": { "modified": "2020-11-23T13:49:53.129Z", "contributors": [ "mrevan", @@ -71802,11 +71373,11 @@ "ericwbailey" ] }, - "Web/Accessibility/ARIA/Roles/suggestion_role": { + "Web/Accessibility/ARIA/Reference/Roles/suggestion_role": { "modified": "2020-04-01T14:51:19.762Z", "contributors": ["chrisdavidmills"] }, - "Web/Accessibility/ARIA/Roles/switch_role": { + "Web/Accessibility/ARIA/Reference/Roles/switch_role": { "modified": "2020-02-20T12:46:20.003Z", "contributors": [ "matijs", @@ -71825,7 +71396,7 @@ "teoli" ] }, - "Web/Accessibility/ARIA/Roles/tab_role": { + "Web/Accessibility/ARIA/Reference/Roles/tab_role": { "modified": "2020-09-10T16:46:20.967Z", "contributors": [ "ericboesch", @@ -71836,7 +71407,7 @@ "Moiety" ] }, - "Web/Accessibility/ARIA/Roles/table_role": { + "Web/Accessibility/ARIA/Reference/Roles/table_role": { "modified": "2019-11-26T15:18:30.558Z", "contributors": [ "karlgroves", @@ -71846,11 +71417,11 @@ "estelle" ] }, - "Web/Accessibility/ARIA/Roles/tabpanel_role": { + "Web/Accessibility/ARIA/Reference/Roles/tabpanel_role": { "modified": "2019-06-12T09:57:18.481Z", "contributors": ["chrisdavidmills", "estelle"] }, - "Web/Accessibility/ARIA/Roles/textbox_role": { + "Web/Accessibility/ARIA/Reference/Roles/textbox_role": { "modified": "2019-09-12T06:49:59.056Z", "contributors": [ "RobinBrons", @@ -71870,15 +71441,11 @@ "hhillen" ] }, - "Web/Accessibility/Accessibility:_What_users_can_to_to_browse_safely": { - "modified": "2019-12-31T18:58:55.559Z", - "contributors": ["andrewpyper", "austin-2019", "estelle"] - }, - "Web/Accessibility/Accessibility_and_Spacial_Patterns": { + "Web/Accessibility/Guides/Accessibility_and_Spatial_Patterns": { "modified": "2019-11-07T11:39:44.805Z", "contributors": ["austin-2019", "estelle"] }, - "Web/Accessibility/An_overview_of_accessible_web_applications_and_widgets": { + "Web/Accessibility/Guides/Accessible_web_applications_and_widgets": { "modified": "2019-06-19T20:00:17.673Z", "contributors": [ "RubyDo", @@ -71902,15 +71469,23 @@ "peterbraden" ] }, - "Web/Accessibility/Cognitive_accessibility": { + "Web/Accessibility/Guides/Browsing_safely": { + "modified": "2019-12-31T18:58:55.559Z", + "contributors": ["andrewpyper", "austin-2019", "estelle"] + }, + "Web/Accessibility/Guides/Cognitive_accessibility": { "modified": "2019-11-18T16:53:41.344Z", "contributors": ["Igor-Sangin", "ericwbailey", "estelle", "jswisher"] }, - "Web/Accessibility/Information_for_Web_authors": { + "Web/Accessibility/Guides/Colors_and_Luminance": { + "modified": "2020-03-12T12:20:18.540Z", + "contributors": ["Koavf", "austin-2019", "estelle"] + }, + "Web/Accessibility/Guides/Information_for_Web_authors": { "modified": "2019-03-23T23:27:44.949Z", "contributors": ["fscholz", "Fredchat", "Sheppy", "openjck"] }, - "Web/Accessibility/Keyboard-navigable_JavaScript_widgets": { + "Web/Accessibility/Guides/Keyboard-navigable_JavaScript_widgets": { "modified": "2019-07-04T06:51:41.901Z", "contributors": [ "fuzzbomb", @@ -71934,7 +71509,7 @@ "peterbraden" ] }, - "Web/Accessibility/Mobile_accessibility_checklist": { + "Web/Accessibility/Guides/Mobile_accessibility_checklist": { "modified": "2020-09-26T18:24:33.135Z", "contributors": [ "m5rdi822", @@ -71947,7 +71522,7 @@ "Tanaguru" ] }, - "Web/Accessibility/Seizure_disorders": { + "Web/Accessibility/Guides/Seizure_disorders": { "modified": "2020-03-20T00:45:18.694Z", "contributors": [ "MarjaE2", @@ -71961,11 +71536,7 @@ "tealdev" ] }, - "Web/Accessibility/Understanding_Colors_and_Luminance": { - "modified": "2020-03-12T12:20:18.540Z", - "contributors": ["Koavf", "austin-2019", "estelle"] - }, - "Web/Accessibility/Understanding_WCAG": { + "Web/Accessibility/Guides/Understanding_WCAG": { "modified": "2019-03-23T22:16:56.489Z", "contributors": [ "christopherwilson1", @@ -71975,7 +71546,7 @@ "SherrieQuinn" ] }, - "Web/Accessibility/Understanding_WCAG/Keyboard": { + "Web/Accessibility/Guides/Understanding_WCAG/Keyboard": { "modified": "2019-12-17T12:47:14.337Z", "contributors": [ "chrisdavidmills", @@ -71985,7 +71556,7 @@ "yzen" ] }, - "Web/Accessibility/Understanding_WCAG/Operable": { + "Web/Accessibility/Guides/Understanding_WCAG/Operable": { "modified": "2020-06-03T15:45:12.511Z", "contributors": [ "garrettbsettles", @@ -71994,7 +71565,7 @@ "chrisdavidmills" ] }, - "Web/Accessibility/Understanding_WCAG/Perceivable": { + "Web/Accessibility/Guides/Understanding_WCAG/Perceivable": { "modified": "2020-08-09T17:59:52.698Z", "contributors": [ "trebuchet", @@ -72004,19 +71575,19 @@ "goodwitch" ] }, - "Web/Accessibility/Understanding_WCAG/Perceivable/Color_contrast": { + "Web/Accessibility/Guides/Understanding_WCAG/Perceivable/Color_contrast": { "modified": "2019-08-26T18:39:02.448Z", "contributors": ["jswisher", "chrisdavidmills", "tacsipacsi", "iamvector"] }, - "Web/Accessibility/Understanding_WCAG/Perceivable/Use_of_color": { + "Web/Accessibility/Guides/Understanding_WCAG/Perceivable/Use_of_color": { "modified": "2019-08-28T15:52:36.498Z", "contributors": ["jswisher"] }, - "Web/Accessibility/Understanding_WCAG/Robust": { + "Web/Accessibility/Guides/Understanding_WCAG/Robust": { "modified": "2019-03-23T22:10:37.177Z", "contributors": ["estelle", "goodwitch", "chrisdavidmills"] }, - "Web/Accessibility/Understanding_WCAG/Text_labels_and_names": { + "Web/Accessibility/Guides/Understanding_WCAG/Text_labels_and_names": { "modified": "2020-08-26T15:28:32.618Z", "contributors": [ "jswisher", @@ -72028,7 +71599,7 @@ "yzen" ] }, - "Web/Accessibility/Understanding_WCAG/Understandable": { + "Web/Accessibility/Guides/Understanding_WCAG/Understandable": { "modified": "2020-06-03T18:07:53.888Z", "contributors": [ "garrettbsettles", @@ -76324,114 +75895,6 @@ "jwalker" ] }, - "Web/CSS/CSS_cascade/actual_value": { - "modified": "2020-07-14T09:14:02.638Z", - "contributors": [ - "mfuji09", - "wbamberg", - "mfluehr", - "sergio-vb", - "Sebastianz", - "teoli", - "kscarfone", - "ethertank", - "Sheppy", - "FredB", - "ziyunfei", - "McGurk" - ] - }, - "Web/CSS/CSS_cascade/computed_value": { - "modified": "2020-08-10T14:01:43.680Z", - "contributors": [ - "mfuji09", - "wbamberg", - "hinell", - "mfluehr", - "Cath_kb", - "Sebastianz", - "Sheppy", - "Urgot", - "Dholbert", - "kscarfone", - "ethertank", - "trevorh", - "mmjyu", - "FredB", - "teoli", - "Jürgen Jeka", - "Mgjbot", - "Marsf", - "Fredchat", - "DBaron" - ] - }, - "Web/CSS/CSS_cascade/initial_value": { - "modified": "2020-07-07T12:36:02.958Z", - "contributors": [ - "wbamberg", - "gerfolder", - "mfluehr", - "CannedYerins", - "kscarfone", - "Sheppy", - "FredB", - "teoli", - "ethertank", - "kyleb", - "Marsf", - "Mgjbot", - "Kohei", - "Pastelgrim", - "Killerowski", - "Bedi", - "Fredchat", - "DBaron" - ] - }, - "Web/CSS/CSS_cascade/specified_value": { - "modified": "2020-08-10T14:28:31.353Z", - "contributors": [ - "mfuji09", - "wbamberg", - "hinell", - "mfluehr", - "asteroidb612", - "Sheppy", - "BychekRU", - "Sebastianz", - "McGurk" - ] - }, - "Web/CSS/CSS_cascade/used_value": { - "modified": "2020-07-07T12:48:07.054Z", - "contributors": [ - "wbamberg", - "mfuji09", - "myf", - "hinell", - "FumiyaShibusawa", - "Tuman", - "shogunsea", - "mfluehr", - "Loadmaster", - "Mori", - "david_ross", - "DecadeCode", - "azoorob3", - "fcard", - "Syle91", - "kscarfone", - "phil_nist", - "Kritz", - "Dholbert", - "teoli", - "ethertank", - "Sheppy", - "FredB", - "yonathan" - ] - }, "Web/CSS/CSS_cascading_variables": { "modified": "2020-07-07T12:03:44.891Z", "contributors": ["wbamberg", "mfluehr"] @@ -77178,6 +76641,30 @@ "Luke314" ] }, + "Web/CSS/CSS_images/Replaced_element_properties": { + "modified": "2020-07-07T12:38:37.398Z", + "contributors": [ + "wbamberg", + "Sheppy", + "SelenIT", + "Nisarg-Shah", + "TotalAMD", + "Konrud", + "yisibl", + "mfluehr", + "Dholbert", + "AdrianSandu", + "josketres", + "cris-luz-07", + "RosevearDev", + "Alrashel", + "atesgoral", + "FredB", + "peb", + "ethertank", + "teoli" + ] + }, "Web/CSS/CSS_images/Using_CSS_gradients": { "modified": "2020-11-09T14:36:47.079Z", "contributors": [ @@ -77226,6 +76713,10 @@ "BenoitL" ] }, + "Web/CSS/CSS_inline_layout/Inline_formatting_context": { + "modified": "2020-04-27T22:33:13.546Z", + "contributors": ["pans9", "chrisdavidmills", "rachelandrew"] + }, "Web/CSS/CSS_lists": { "modified": "2020-07-07T12:20:22.683Z", "contributors": [ @@ -77613,26 +77104,7 @@ "teoli" ] }, - "Web/CSS/CSS_positioned_layout/Understanding_z-index": { - "modified": "2020-08-24T12:47:16.738Z", - "contributors": [ - "mfuji09", - "mfluehr", - "teoli", - "Jeremie", - "kscarfone", - "Sheppy", - "tregagnon", - "Jürgen Jeka", - "Fredchat", - "Dria", - "Nickolay", - "bradipao", - "Rod Whiteley", - "Wladimir_Palant" - ] - }, - "Web/CSS/CSS_positioned_layout/Understanding_z-index/Stacking_context": { + "Web/CSS/CSS_positioned_layout/Stacking_context": { "modified": "2020-08-24T11:51:33.626Z", "contributors": [ "mfuji09", @@ -77683,7 +77155,7 @@ "bradipao" ] }, - "Web/CSS/CSS_positioned_layout/Understanding_z-index/Stacking_context_example_1": { + "Web/CSS/CSS_positioned_layout/Stacking_context/Stacking_context_example_1": { "modified": "2020-08-24T12:16:56.733Z", "contributors": [ "mfuji09", @@ -77701,7 +77173,7 @@ "bradipao" ] }, - "Web/CSS/CSS_positioned_layout/Understanding_z-index/Stacking_context_example_2": { + "Web/CSS/CSS_positioned_layout/Stacking_context/Stacking_context_example_2": { "modified": "2020-08-24T12:22:25.104Z", "contributors": [ "mfuji09", @@ -77720,7 +77192,7 @@ "bradipao" ] }, - "Web/CSS/CSS_positioned_layout/Understanding_z-index/Stacking_context_example_3": { + "Web/CSS/CSS_positioned_layout/Stacking_context/Stacking_context_example_3": { "modified": "2020-08-24T12:36:52.767Z", "contributors": [ "mfuji09", @@ -77742,7 +77214,7 @@ "bradipao" ] }, - "Web/CSS/CSS_positioned_layout/Understanding_z-index/Stacking_floating_elements": { + "Web/CSS/CSS_positioned_layout/Stacking_floating_elements": { "modified": "2020-09-10T08:45:49.713Z", "contributors": [ "hata6502", @@ -77763,7 +77235,7 @@ "bradipao" ] }, - "Web/CSS/CSS_positioned_layout/Understanding_z-index/Stacking_without_z-index": { + "Web/CSS/CSS_positioned_layout/Stacking_without_z-index": { "modified": "2020-08-24T11:01:07.302Z", "contributors": [ "mfuji09", @@ -77789,7 +77261,26 @@ "bradipao" ] }, - "Web/CSS/CSS_positioned_layout/Understanding_z-index/Using_z-index": { + "Web/CSS/CSS_positioned_layout/Understanding_z-index": { + "modified": "2020-08-24T12:47:16.738Z", + "contributors": [ + "mfuji09", + "mfluehr", + "teoli", + "Jeremie", + "kscarfone", + "Sheppy", + "tregagnon", + "Jürgen Jeka", + "Fredchat", + "Dria", + "Nickolay", + "bradipao", + "Rod Whiteley", + "Wladimir_Palant" + ] + }, + "Web/CSS/CSS_positioned_layout/Using_z-index": { "modified": "2020-08-24T11:23:24.372Z", "contributors": [ "mfuji09", @@ -77822,6 +77313,18 @@ "teoli" ] }, + "Web/CSS/CSS_scroll_anchoring/Scroll_anchoring": { + "modified": "2020-10-15T22:15:56.258Z", + "contributors": [ + "mfuji09", + "rachelandrew", + "emilio_", + "mfluehr", + "steveluscher", + "bensoibj", + "chrisdavidmills" + ] + }, "Web/CSS/CSS_scroll_snap": { "modified": "2020-12-06T20:56:34.162Z", "contributors": [ @@ -77862,6 +77365,20 @@ "ExE-Boss" ] }, + "Web/CSS/CSS_selectors/Privacy_and_the_visited_selector": { + "modified": "2020-05-05T20:20:41.094Z", + "contributors": [ + "jswisher", + "wbamberg", + "mfluehr", + "una", + "Sheppy", + "DBaron", + "Dholbert", + "gavenkoa", + "fscholz" + ] + }, "Web/CSS/CSS_shapes": { "modified": "2020-07-07T12:26:26.279Z", "contributors": [ @@ -78272,10 +77789,6 @@ "miken32" ] }, - "Web/CSS/Inline_formatting_context": { - "modified": "2020-04-27T22:33:13.546Z", - "contributors": ["pans9", "chrisdavidmills", "rachelandrew"] - }, "Web/CSS/Layout_cookbook": { "modified": "2020-07-07T12:18:05.178Z", "contributors": [ @@ -78340,23 +77853,6 @@ "modified": "2020-10-15T22:08:03.870Z", "contributors": ["wbamberg", "chrisdavidmills", "rachelandrew"] }, - "Web/CSS/Layout_mode": { - "modified": "2020-07-07T12:36:23.002Z", - "contributors": [ - "wbamberg", - "lcchueri", - "chrisdavidmills", - "rachelandrew", - "mfluehr", - "Sebastianz", - "markg", - "evalica", - "velvel53", - "Sheppy", - "FredB", - "teoli" - ] - }, "Web/CSS/Mozilla_Extensions": { "modified": "2020-08-09T13:09:17.030Z", "contributors": [ @@ -78450,20 +77946,6 @@ "Wjjohnst" ] }, - "Web/CSS/Privacy_and_the_:visited_selector": { - "modified": "2020-05-05T20:20:41.094Z", - "contributors": [ - "jswisher", - "wbamberg", - "mfluehr", - "una", - "Sheppy", - "DBaron", - "Dholbert", - "gavenkoa", - "fscholz" - ] - }, "Web/CSS/Pseudo-classes": { "modified": "2020-12-04T07:53:29.269Z", "contributors": [ @@ -78620,30 +78102,6 @@ "Dria" ] }, - "Web/CSS/Replaced_element": { - "modified": "2020-07-07T12:38:37.398Z", - "contributors": [ - "wbamberg", - "Sheppy", - "SelenIT", - "Nisarg-Shah", - "TotalAMD", - "Konrud", - "yisibl", - "mfluehr", - "Dholbert", - "AdrianSandu", - "josketres", - "cris-luz-07", - "RosevearDev", - "Alrashel", - "atesgoral", - "FredB", - "peb", - "ethertank", - "teoli" - ] - }, "Web/CSS/Selector_list": { "modified": "2020-10-15T22:23:36.353Z", "contributors": [ @@ -87150,18 +86608,6 @@ "krosylight" ] }, - "Web/CSS/overflow-anchor/Guide_to_scroll_anchoring": { - "modified": "2020-10-15T22:15:56.258Z", - "contributors": [ - "mfuji09", - "rachelandrew", - "emilio_", - "mfluehr", - "steveluscher", - "bensoibj", - "chrisdavidmills" - ] - }, "Web/CSS/overflow-block": { "modified": "2020-10-15T22:17:41.903Z", "contributors": [ @@ -88095,16 +87541,6 @@ "Jürgen Jeka" ] }, - "Web/CSS/resolved_value": { - "modified": "2020-07-07T12:38:43.332Z", - "contributors": [ - "wbamberg", - "mfluehr", - "BychekRU", - "Sebastianz", - "Dholbert" - ] - }, "Web/CSS/revert": { "modified": "2020-12-01T01:19:10.242Z", "contributors": [ @@ -91137,7 +90573,344 @@ "omercier67" ] }, - "Web/HTML/Attributes": { + "Web/HTML/Guides/Cheatsheet": { + "modified": "2020-07-16T22:22:43.887Z", + "contributors": [ + "Yel-Martinez-Consultor-Seo", + "sideshowbarker", + "verde79", + "sksankarraj", + "Quantzilla", + "Johanancuriel", + "SethClydesdale", + "arkanciscan", + "khalid32", + "jswisher", + "fachrulrazy", + "Andrew_Pfeiffer", + "SphinxKnight", + "dvincent", + "hbloomer", + "chadsansing", + "Jeremie" + ] + }, + "Web/HTML/Guides/Content_categories": { + "modified": "2020-10-18T10:42:38.994Z", + "contributors": [ + "mfuji09", + "arshadrr", + "alattalatta", + "kenj115188", + "andryanmiller", + "madmadi", + "chrisdavidmills", + "instructorc", + "unclesamnumberone", + "Tigt", + "Sheppy", + "VynceMontgomery", + "SphinxKnight", + "lovefield", + "vichavens", + "Fizco", + "anubes19", + "knod", + "marie-ototoi", + "teoli", + "Aleksej", + "markg", + "Aslam.Sayyed", + "Jeremie", + "systemovich", + "kscarfone", + "ethertank", + "moreati", + "Potappo", + "keoki.zee", + "bashkas", + "MatrixFrog", + "xaky", + "fscholz", + "jswisher" + ] + }, + "Web/HTML/Guides/Date_and_time_formats": { + "modified": "2020-09-28T12:25:10.223Z", + "contributors": [ + "mfuji09", + "John-Page", + "pranavkp", + "sideshowbarker", + "black_white2018", + "jswisher", + "Sheppy" + ] + }, + "Web/HTML/Guides/Microdata": { + "modified": "2020-09-06T05:55:47.630Z", + "contributors": [ + "mfuji09", + "alattalatta", + "Tantek", + "germain", + "evan-brass", + "sideshowbarker", + "Annevk", + "fscholz", + "stevenwdv", + "getschomp", + "teoli", + "rolfedh", + "duncanmcdonald" + ] + }, + "Web/HTML/Guides/Microformats": { + "modified": "2019-10-10T12:40:00.802Z", + "contributors": [ + "Tantek", + "SphinxKnight", + "sknebel", + "schmarty", + "jgmac1106", + "mfluehr", + "ExE-Boss", + "PushpitaPikuDey", + "jsx", + "jenifferhomes", + "Seta00", + "codeforuk", + "RenRen", + "teoli", + "marie-ototoi", + "rogerxas", + "mehmetaergun", + "xfq", + "Akilan_Arasu", + "barnabywalters" + ] + }, + "Web/HTML/Guides/Quirks_mode_and_standards_mode": { + "modified": "2020-10-03T02:40:04.174Z", + "contributors": [ + "mfuji09", + "darby", + "erhan35", + "cRAN_cg", + "chrisdavidmills", + "matrimonio", + "JeremyPDonahue", + "Aleksey-Danchin", + "luke@mozilla.com", + "kscarfone", + "ethertank", + "nekretnine", + "Sheppy", + "jswisher", + "Dikrib", + "ziyunfei", + "George3", + "cesar_ortizg", + "kohei.yoshino", + "BenoitL", + "NickolayBot", + "DBaron", + "Dria", + "Mcaruso" + ] + }, + "Web/HTML/Guides/Responsive_images": { + "modified": "2020-10-19T20:26:21.787Z", + "contributors": [ + "hamishwillee", + "sideshowbarker", + "thjbd", + "chrisdavidmills", + "atd30", + "jpfkd", + "ramiy", + "JonDevOps", + "choudh70", + "tayyabalishan", + "Blacktodreamlight", + "Koavf", + "clairealyssa", + "eremis101", + "MNizam0802", + "oyenirat", + "Flimm", + "thenoelman", + "chelBot", + "dharkness", + "demont93", + "akshat12", + "imi-tating", + "msufa", + "Audaciter", + "stephaniehobson", + "dtrueman", + "goto.prototype", + "richardzacur", + "Sheppy", + "Jeremie", + "hbloomer", + "Andrew_Pfeiffer" + ] + }, + "Web/HTML/How_to/Add_JavaScript_to_your_web_page": { + "modified": "2020-07-16T22:22:39.990Z", + "contributors": ["RomainLanz", "Jeremie", "Andrew_Pfeiffer"] + }, + "Web/HTML/How_to/Add_a_hit_map_on_top_of_an_image": { + "modified": "2020-07-16T22:22:42.758Z", + "contributors": ["ezrinjaz", "hbloomer", "Andrew_Pfeiffer"] + }, + "Web/HTML/How_to/Author_fast-loading_HTML_pages": { + "modified": "2020-07-16T22:22:31.788Z", + "contributors": [ + "Sheppy", + "estelle", + "sideshowbarker", + "karimos129", + "spencercorwin", + "SphinxKnight", + "chrisdavidmills", + "ziyadElon", + "Harinderpreet", + "stuartharvie", + "RafeyIqbalRahman", + "ishan123456789", + "abt8601", + "xfq", + "andygongea", + "rfc791", + "fscholz", + "Jeremie", + "kscarfone", + "dbs", + "gmerencio", + "gbrown", + "haboqueferus", + "brunoais", + "teoli", + "ethertank", + "tolbon", + "leo89", + "tw2113", + "inma_610", + "xaky", + "Shz", + "JaredWBurt", + "alicethomas222", + "peterson.victor222", + "Mgjbot", + "Carrie zhxj", + "Ptak82", + "Satyr-wayfarer", + "NickolayBot", + "Dria", + "Yworfg", + "cbiesinger", + "Nerf", + "Grauw", + "CitizenK", + "Jens.B" + ] + }, + "Web/HTML/How_to/CORS_enabled_image": { + "modified": "2020-11-03T13:26:20.578Z", + "contributors": [ + "germain", + "mfuji09", + "Sheppy", + "fscholz", + "mfluehr", + "markg", + "teoli", + "groovecoder", + "anotherkabab", + "Jeremie", + "cesy", + "rogerxas", + "alrra", + "teoliTest2", + "paul.irish", + "kscarfone", + "enderandpeter", + "ziyunfei", + "myakura", + "Sephr", + "louisremi" + ] + }, + "Web/HTML/How_to/Define_terms_with_HTML": { + "modified": "2020-07-16T22:22:41.646Z", + "contributors": [ + "AlexK89", + "jnegara", + "Jeremie", + "Andrew_Pfeiffer", + "Sheppy", + "MohammedAdam", + "hbloomer" + ] + }, + "Web/HTML/How_to/Use_data_attributes": { + "modified": "2020-07-16T22:22:34.241Z", + "contributors": [ + "vnctdj", + "LoVo666", + "jmstfv", + "mfuji09", + "kenny-evitt", + "Enrico_Polanski", + "ryanve", + "calebmosher", + "chrisdavidmills", + "rnacken", + "Sheppy", + "prusse-martin", + "torazaburo", + "jacksonrayhamilton", + "drj11", + "Manojkr", + "Speich", + "sam_eaton", + "bcruddy", + "teckno101", + "lieuwex", + "robinpokorny", + "rvighne", + "andrew.carpenter", + "Jeremie", + "magnetikonline", + "jswisher", + "kscarfone", + "teoli", + "groovecoder" + ] + }, + "Web/HTML/Reference": { + "modified": "2019-09-05T20:19:46.189Z", + "contributors": [ + "wbamberg", + "JCodeg", + "Sheppy", + "sideshowbarker", + "julio-elipse", + "mfuji09", + "dolorismachina", + "mfluehr", + "jswisher", + "greatdevaks", + "stingyong", + "rogerxas", + "Tee37", + "teoli", + "codemetro" + ] + }, + "Web/HTML/Reference/Attributes": { "modified": "2020-11-18T22:39:41.849Z", "contributors": [ "horuskol", @@ -91200,11 +90973,11 @@ "garann" ] }, - "Web/HTML/Attributes/accept": { + "Web/HTML/Reference/Attributes/accept": { "modified": "2020-12-05T11:17:40.105Z", "contributors": ["mfuji09", "mattd", "hardik-singhal", "estelle"] }, - "Web/HTML/Attributes/autocomplete": { + "Web/HTML/Reference/Attributes/autocomplete": { "modified": "2020-10-15T22:06:23.258Z", "contributors": [ "em_te", @@ -91220,11 +90993,11 @@ "Sheppy" ] }, - "Web/HTML/Attributes/capture": { + "Web/HTML/Reference/Attributes/capture": { "modified": "2020-10-15T22:25:05.353Z", "contributors": ["estelle", "pans9"] }, - "Web/HTML/Attributes/crossorigin": { + "Web/HTML/Reference/Attributes/crossorigin": { "modified": "2020-12-04T01:11:19.194Z", "contributors": [ "sideshowbarker", @@ -91258,11 +91031,11 @@ "BYK" ] }, - "Web/HTML/Attributes/disabled": { + "Web/HTML/Reference/Attributes/disabled": { "modified": "2020-10-15T22:24:45.850Z", "contributors": ["Menno_vdH", "dominicegginton", "estelle"] }, - "Web/HTML/Attributes/max": { + "Web/HTML/Reference/Attributes/max": { "modified": "2020-11-12T07:31:09.216Z", "contributors": [ "chrisdavidmills", @@ -91272,11 +91045,11 @@ "estelle" ] }, - "Web/HTML/Attributes/maxlength": { + "Web/HTML/Reference/Attributes/maxlength": { "modified": "2020-10-19T11:04:05.219Z", "contributors": ["mattd", "mfuji09", "dominicegginton", "estelle"] }, - "Web/HTML/Attributes/min": { + "Web/HTML/Reference/Attributes/min": { "modified": "2020-10-19T11:04:15.608Z", "contributors": [ "mattd", @@ -91286,15 +91059,15 @@ "estelle" ] }, - "Web/HTML/Attributes/minlength": { + "Web/HTML/Reference/Attributes/minlength": { "modified": "2020-10-19T11:02:38.145Z", "contributors": ["mattd", "mfuji09", "valtlai", "fredj", "estelle"] }, - "Web/HTML/Attributes/multiple": { + "Web/HTML/Reference/Attributes/multiple": { "modified": "2020-11-10T05:11:00.190Z", "contributors": ["mfuji09", "mattd", "estelle"] }, - "Web/HTML/Attributes/pattern": { + "Web/HTML/Reference/Attributes/pattern": { "modified": "2020-11-08T15:04:02.028Z", "contributors": [ "mfuji09", @@ -91305,11 +91078,11 @@ "estelle" ] }, - "Web/HTML/Attributes/readonly": { + "Web/HTML/Reference/Attributes/readonly": { "modified": "2020-10-15T22:24:43.179Z", "contributors": ["vaxul", "dominicegginton", "estelle"] }, - "Web/HTML/Attributes/rel": { + "Web/HTML/Reference/Attributes/rel": { "modified": "2020-11-06T05:34:40.505Z", "contributors": [ "rachelandrew", @@ -91322,64 +91095,43 @@ "perfmattersconf" ] }, - "Web/HTML/Attributes/rel/Alternate_stylesheet": { - "modified": "2020-10-15T21:15:55.661Z", - "contributors": [ - "wbamberg", - "mfuji09", - "sideshowbarker", - "chrisdavidmills", - "mfluehr", - "Nickolay", - "r-o-b", - "Sebastianz", - "teoli", - "Sheppy", - "justinpotts", - "minitech", - "Mgjbot", - "Kohei", - "Sevenspade", - "DBaron" - ] - }, - "Web/HTML/Attributes/rel/dns-prefetch": { + "Web/HTML/Reference/Attributes/rel/dns-prefetch": { "modified": "2020-10-15T22:29:03.654Z", "contributors": ["sideshowbarker"] }, - "Web/HTML/Attributes/rel/manifest": { + "Web/HTML/Reference/Attributes/rel/manifest": { "modified": "2020-10-15T22:29:03.916Z", "contributors": ["sideshowbarker"] }, - "Web/HTML/Attributes/rel/modulepreload": { + "Web/HTML/Reference/Attributes/rel/modulepreload": { "modified": "2020-10-15T22:29:02.735Z", "contributors": ["sideshowbarker"] }, - "Web/HTML/Attributes/rel/noopener": { + "Web/HTML/Reference/Attributes/rel/noopener": { "modified": "2020-10-15T22:29:03.663Z", "contributors": ["sideshowbarker"] }, - "Web/HTML/Attributes/rel/noreferrer": { + "Web/HTML/Reference/Attributes/rel/noreferrer": { "modified": "2020-10-15T22:29:06.663Z", "contributors": ["sideshowbarker"] }, - "Web/HTML/Attributes/rel/preconnect": { + "Web/HTML/Reference/Attributes/rel/preconnect": { "modified": "2020-10-15T22:29:05.087Z", "contributors": ["sideshowbarker"] }, - "Web/HTML/Attributes/rel/prefetch": { + "Web/HTML/Reference/Attributes/rel/prefetch": { "modified": "2020-10-15T22:29:05.730Z", "contributors": ["sideshowbarker"] }, - "Web/HTML/Attributes/rel/preload": { + "Web/HTML/Reference/Attributes/rel/preload": { "modified": "2020-10-15T22:29:04.820Z", "contributors": ["sideshowbarker"] }, - "Web/HTML/Attributes/rel/prerender": { + "Web/HTML/Reference/Attributes/rel/prerender": { "modified": "2020-10-15T22:29:04.645Z", "contributors": ["sideshowbarker"] }, - "Web/HTML/Attributes/required": { + "Web/HTML/Reference/Attributes/required": { "modified": "2020-11-09T13:04:56.530Z", "contributors": [ "mfuji09", @@ -91389,11 +91141,11 @@ "estelle" ] }, - "Web/HTML/Attributes/size": { + "Web/HTML/Reference/Attributes/size": { "modified": "2020-10-15T22:25:14.384Z", "contributors": ["mfuji09", "estelle"] }, - "Web/HTML/Attributes/step": { + "Web/HTML/Reference/Attributes/step": { "modified": "2020-09-28T04:18:28.027Z", "contributors": [ "mfuji09", @@ -91403,85 +91155,7 @@ "estelle" ] }, - "Web/HTML/CORS_enabled_image": { - "modified": "2020-11-03T13:26:20.578Z", - "contributors": [ - "germain", - "mfuji09", - "Sheppy", - "fscholz", - "mfluehr", - "markg", - "teoli", - "groovecoder", - "anotherkabab", - "Jeremie", - "cesy", - "rogerxas", - "alrra", - "teoliTest2", - "paul.irish", - "kscarfone", - "enderandpeter", - "ziyunfei", - "myakura", - "Sephr", - "louisremi" - ] - }, - "Web/HTML/Content_categories": { - "modified": "2020-10-18T10:42:38.994Z", - "contributors": [ - "mfuji09", - "arshadrr", - "alattalatta", - "kenj115188", - "andryanmiller", - "madmadi", - "chrisdavidmills", - "instructorc", - "unclesamnumberone", - "Tigt", - "Sheppy", - "VynceMontgomery", - "SphinxKnight", - "lovefield", - "vichavens", - "Fizco", - "anubes19", - "knod", - "marie-ototoi", - "teoli", - "Aleksej", - "markg", - "Aslam.Sayyed", - "Jeremie", - "systemovich", - "kscarfone", - "ethertank", - "moreati", - "Potappo", - "keoki.zee", - "bashkas", - "MatrixFrog", - "xaky", - "fscholz", - "jswisher" - ] - }, - "Web/HTML/Date_and_time_formats": { - "modified": "2020-09-28T12:25:10.223Z", - "contributors": [ - "mfuji09", - "John-Page", - "pranavkp", - "sideshowbarker", - "black_white2018", - "jswisher", - "Sheppy" - ] - }, - "Web/HTML/Element": { + "Web/HTML/Reference/Elements": { "modified": "2020-12-14T06:30:07.337Z", "contributors": [ "chrisdavidmills", @@ -91566,7 +91240,7 @@ "Charles" ] }, - "Web/HTML/Element/Heading_Elements": { + "Web/HTML/Reference/Elements/Heading_Elements": { "modified": "2020-12-03T13:47:52.077Z", "contributors": [ "mfuji09", @@ -91612,7 +91286,7 @@ "PablO" ] }, - "Web/HTML/Element/a": { + "Web/HTML/Reference/Elements/a": { "modified": "2020-12-14T11:37:18.454Z", "contributors": [ "Jason0", @@ -91741,7 +91415,7 @@ "Ptak82" ] }, - "Web/HTML/Element/abbr": { + "Web/HTML/Reference/Elements/abbr": { "modified": "2020-10-15T21:07:37.707Z", "contributors": [ "chrisdavidmills", @@ -91787,7 +91461,7 @@ "alecananian" ] }, - "Web/HTML/Element/acronym": { + "Web/HTML/Reference/Elements/acronym": { "modified": "2020-10-15T21:11:38.003Z", "contributors": [ "jswisher", @@ -91816,7 +91490,7 @@ "alecananian" ] }, - "Web/HTML/Element/address": { + "Web/HTML/Reference/Elements/address": { "modified": "2020-10-15T21:05:10.561Z", "contributors": [ "alattalatta", @@ -91856,7 +91530,7 @@ "alecananian" ] }, - "Web/HTML/Element/area": { + "Web/HTML/Reference/Elements/area": { "modified": "2020-11-09T11:29:48.831Z", "contributors": [ "mfuji09", @@ -91914,7 +91588,7 @@ "PablO" ] }, - "Web/HTML/Element/article": { + "Web/HTML/Reference/Elements/article": { "modified": "2020-11-08T08:36:31.840Z", "contributors": [ "mfuji09", @@ -91951,7 +91625,7 @@ "Ms2ger" ] }, - "Web/HTML/Element/aside": { + "Web/HTML/Reference/Elements/aside": { "modified": "2020-10-15T21:02:24.705Z", "contributors": [ "mfuji09", @@ -91990,7 +91664,7 @@ "jswisher" ] }, - "Web/HTML/Element/audio": { + "Web/HTML/Reference/Elements/audio": { "modified": "2020-10-15T21:03:08.733Z", "contributors": [ "mfuji09", @@ -92065,7 +91739,7 @@ "Ms2ger" ] }, - "Web/HTML/Element/b": { + "Web/HTML/Reference/Elements/b": { "modified": "2020-10-15T21:09:56.169Z", "contributors": [ "mfuji09", @@ -92111,7 +91785,7 @@ "Charles" ] }, - "Web/HTML/Element/base": { + "Web/HTML/Reference/Elements/base": { "modified": "2020-10-15T21:03:55.628Z", "contributors": [ "alattalatta", @@ -92168,7 +91842,7 @@ "Victory" ] }, - "Web/HTML/Element/bdi": { + "Web/HTML/Reference/Elements/bdi": { "modified": "2020-10-15T21:06:40.392Z", "contributors": [ "mfuji09", @@ -92195,7 +91869,7 @@ "avsaro" ] }, - "Web/HTML/Element/bdo": { + "Web/HTML/Reference/Elements/bdo": { "modified": "2020-10-15T21:10:17.382Z", "contributors": [ "chrisdavidmills", @@ -92231,7 +91905,7 @@ "Ptak82" ] }, - "Web/HTML/Element/big": { + "Web/HTML/Reference/Elements/big": { "modified": "2020-10-15T21:02:25.097Z", "contributors": [ "Sheppy", @@ -92256,7 +91930,7 @@ "Charles" ] }, - "Web/HTML/Element/blockquote": { + "Web/HTML/Reference/Elements/blockquote": { "modified": "2020-10-15T21:03:48.107Z", "contributors": [ "mfuji09", @@ -92288,7 +91962,7 @@ "alecananian" ] }, - "Web/HTML/Element/body": { + "Web/HTML/Reference/Elements/body": { "modified": "2020-10-15T21:02:42.774Z", "contributors": [ "JamesCatt", @@ -92320,7 +91994,7 @@ "Brettz9" ] }, - "Web/HTML/Element/br": { + "Web/HTML/Reference/Elements/br": { "modified": "2020-10-15T21:05:10.462Z", "contributors": [ "mfuji09", @@ -92360,7 +92034,7 @@ "alecananian" ] }, - "Web/HTML/Element/button": { + "Web/HTML/Reference/Elements/button": { "modified": "2020-10-15T21:09:45.567Z", "contributors": [ "JamesCatt", @@ -92424,7 +92098,7 @@ "Gryllida" ] }, - "Web/HTML/Element/canvas": { + "Web/HTML/Reference/Elements/canvas": { "modified": "2020-10-15T21:06:45.056Z", "contributors": [ "mfuji09", @@ -92469,7 +92143,7 @@ "Jürgen Jeka" ] }, - "Web/HTML/Element/caption": { + "Web/HTML/Reference/Elements/caption": { "modified": "2020-10-15T21:12:13.409Z", "contributors": [ "mfuji09", @@ -92501,7 +92175,7 @@ "McGurk" ] }, - "Web/HTML/Element/center": { + "Web/HTML/Reference/Elements/center": { "modified": "2020-10-15T21:09:40.424Z", "contributors": [ "robertjlooby", @@ -92519,7 +92193,7 @@ "Jscher2000" ] }, - "Web/HTML/Element/cite": { + "Web/HTML/Reference/Elements/cite": { "modified": "2020-10-15T21:12:13.665Z", "contributors": [ "mfuji09", @@ -92562,7 +92236,7 @@ "PablO" ] }, - "Web/HTML/Element/code": { + "Web/HTML/Reference/Elements/code": { "modified": "2020-11-09T08:41:20.993Z", "contributors": [ "mfuji09", @@ -92603,7 +92277,7 @@ "alecananian" ] }, - "Web/HTML/Element/col": { + "Web/HTML/Reference/Elements/col": { "modified": "2020-11-09T06:45:25.816Z", "contributors": [ "mfuji09", @@ -92643,7 +92317,7 @@ "Ptak82" ] }, - "Web/HTML/Element/colgroup": { + "Web/HTML/Reference/Elements/colgroup": { "modified": "2020-11-08T13:28:47.990Z", "contributors": [ "mfuji09", @@ -92685,7 +92359,7 @@ "Jonata" ] }, - "Web/HTML/Element/data": { + "Web/HTML/Reference/Elements/data": { "modified": "2020-10-15T21:20:13.808Z", "contributors": [ "karlstolley", @@ -92716,7 +92390,7 @@ "rblancarte" ] }, - "Web/HTML/Element/datalist": { + "Web/HTML/Reference/Elements/datalist": { "modified": "2020-10-15T21:05:43.807Z", "contributors": [ "chrisdavidmills", @@ -92764,7 +92438,7 @@ "osdm" ] }, - "Web/HTML/Element/dd": { + "Web/HTML/Reference/Elements/dd": { "modified": "2020-10-15T21:12:12.976Z", "contributors": [ "JamesCatt", @@ -92798,7 +92472,7 @@ "alecananian" ] }, - "Web/HTML/Element/del": { + "Web/HTML/Reference/Elements/del": { "modified": "2020-10-15T21:05:06.241Z", "contributors": [ "realityforge", @@ -92831,7 +92505,7 @@ "jswisher" ] }, - "Web/HTML/Element/details": { + "Web/HTML/Reference/Elements/details": { "modified": "2020-10-15T21:09:40.878Z", "contributors": [ "JamesCatt", @@ -92880,7 +92554,7 @@ "hobophobe" ] }, - "Web/HTML/Element/dfn": { + "Web/HTML/Reference/Elements/dfn": { "modified": "2020-10-15T21:12:09.718Z", "contributors": [ "JamesCatt", @@ -92915,7 +92589,7 @@ "jswisher" ] }, - "Web/HTML/Element/dialog": { + "Web/HTML/Reference/Elements/dialog": { "modified": "2020-10-15T21:29:05.708Z", "contributors": [ "mfuji09", @@ -92948,7 +92622,7 @@ "Akilan_Arasu" ] }, - "Web/HTML/Element/dir": { + "Web/HTML/Reference/Elements/dir": { "modified": "2020-10-18T09:39:53.444Z", "contributors": [ "mfuji09", @@ -92964,7 +92638,7 @@ "cers" ] }, - "Web/HTML/Element/div": { + "Web/HTML/Reference/Elements/div": { "modified": "2020-12-06T07:57:30.172Z", "contributors": [ "chrisdavidmills", @@ -92991,7 +92665,7 @@ "McGurk" ] }, - "Web/HTML/Element/dl": { + "Web/HTML/Reference/Elements/dl": { "modified": "2020-10-15T21:09:55.313Z", "contributors": [ "gnclmorais", @@ -93034,7 +92708,7 @@ "alecananian" ] }, - "Web/HTML/Element/dt": { + "Web/HTML/Reference/Elements/dt": { "modified": "2020-10-15T21:11:36.883Z", "contributors": [ "JamesCatt", @@ -93066,7 +92740,7 @@ "PablO" ] }, - "Web/HTML/Element/em": { + "Web/HTML/Reference/Elements/em": { "modified": "2020-12-04T14:30:22.644Z", "contributors": [ "mfuji09", @@ -93106,7 +92780,7 @@ "Jinexile" ] }, - "Web/HTML/Element/embed": { + "Web/HTML/Reference/Elements/embed": { "modified": "2020-10-15T21:12:09.635Z", "contributors": [ "mfuji09", @@ -93136,7 +92810,7 @@ "McGurk" ] }, - "Web/HTML/Element/fieldset": { + "Web/HTML/Reference/Elements/fieldset": { "modified": "2020-11-09T13:17:54.263Z", "contributors": [ "mfuji09", @@ -93193,7 +92867,7 @@ "jswisher" ] }, - "Web/HTML/Element/figcaption": { + "Web/HTML/Reference/Elements/figcaption": { "modified": "2020-10-15T21:05:08.464Z", "contributors": [ "JamesCatt", @@ -93219,7 +92893,7 @@ "jswisher" ] }, - "Web/HTML/Element/figure": { + "Web/HTML/Reference/Elements/figure": { "modified": "2020-10-15T21:02:26.941Z", "contributors": [ "JamesCatt", @@ -93262,7 +92936,7 @@ "McGurk" ] }, - "Web/HTML/Element/font": { + "Web/HTML/Reference/Elements/font": { "modified": "2020-10-15T21:04:55.217Z", "contributors": [ "garrettbsettles", @@ -93281,7 +92955,7 @@ "p858snake" ] }, - "Web/HTML/Element/footer": { + "Web/HTML/Reference/Elements/footer": { "modified": "2020-10-16T11:06:02.375Z", "contributors": [ "mfuji09", @@ -93312,7 +92986,7 @@ "serator+" ] }, - "Web/HTML/Element/form": { + "Web/HTML/Reference/Elements/form": { "modified": "2020-10-15T21:06:44.243Z", "contributors": [ "CaselIT", @@ -93370,7 +93044,7 @@ "McGurk" ] }, - "Web/HTML/Element/frame": { + "Web/HTML/Reference/Elements/frame": { "modified": "2020-10-15T21:09:18.322Z", "contributors": [ "mfuji09", @@ -93387,7 +93061,7 @@ "jswisher" ] }, - "Web/HTML/Element/frameset": { + "Web/HTML/Reference/Elements/frameset": { "modified": "2020-10-15T21:09:02.435Z", "contributors": [ "mfuji09", @@ -93404,7 +93078,7 @@ "avsaro" ] }, - "Web/HTML/Element/head": { + "Web/HTML/Reference/Elements/head": { "modified": "2020-10-15T21:03:01.189Z", "contributors": [ "JamesCatt", @@ -93435,7 +93109,7 @@ "jswisher" ] }, - "Web/HTML/Element/header": { + "Web/HTML/Reference/Elements/header": { "modified": "2020-11-05T04:16:35.196Z", "contributors": [ "SphinxKnight", @@ -93475,7 +93149,7 @@ "trevorh" ] }, - "Web/HTML/Element/hgroup": { + "Web/HTML/Reference/Elements/hgroup": { "modified": "2020-10-15T21:06:41.175Z", "contributors": [ "JamesCatt", @@ -93506,7 +93180,7 @@ "McGurk" ] }, - "Web/HTML/Element/hr": { + "Web/HTML/Reference/Elements/hr": { "modified": "2020-10-15T21:02:25.861Z", "contributors": [ "JamesCatt", @@ -93543,7 +93217,7 @@ "alecananian" ] }, - "Web/HTML/Element/html": { + "Web/HTML/Reference/Elements/html": { "modified": "2020-10-15T21:03:06.361Z", "contributors": [ "JamesCatt", @@ -93582,7 +93256,7 @@ "alecananian" ] }, - "Web/HTML/Element/i": { + "Web/HTML/Reference/Elements/i": { "modified": "2020-10-15T21:11:43.020Z", "contributors": [ "Sheppy", @@ -93627,7 +93301,7 @@ "Charles" ] }, - "Web/HTML/Element/iframe": { + "Web/HTML/Reference/Elements/iframe": { "modified": "2020-11-08T12:55:24.842Z", "contributors": [ "mfuji09", @@ -93730,7 +93404,7 @@ "jorh" ] }, - "Web/HTML/Element/img": { + "Web/HTML/Reference/Elements/img": { "modified": "2020-12-03T01:54:55.358Z", "contributors": [ "transparent-room", @@ -93833,7 +93507,7 @@ "Softwayer" ] }, - "Web/HTML/Element/input": { + "Web/HTML/Reference/Elements/input": { "modified": "2020-12-09T21:40:28.857Z", "contributors": [ "pchicken", @@ -94019,7 +93693,7 @@ "osdm" ] }, - "Web/HTML/Element/input/button": { + "Web/HTML/Reference/Elements/input/button": { "modified": "2020-10-15T21:33:05.814Z", "contributors": [ "mfuji09", @@ -94044,7 +93718,7 @@ "kscarfone" ] }, - "Web/HTML/Element/input/checkbox": { + "Web/HTML/Reference/Elements/input/checkbox": { "modified": "2020-11-18T13:21:44.572Z", "contributors": [ "trezy", @@ -94090,7 +93764,7 @@ "sidgan" ] }, - "Web/HTML/Element/input/color": { + "Web/HTML/Reference/Elements/input/color": { "modified": "2020-10-15T21:33:12.951Z", "contributors": [ "sideshowbarker", @@ -94119,7 +93793,7 @@ "sidgan" ] }, - "Web/HTML/Element/input/date": { + "Web/HTML/Reference/Elements/input/date": { "modified": "2020-11-10T12:27:28.479Z", "contributors": [ "isherwood91", @@ -94158,7 +93832,7 @@ "hbloomer" ] }, - "Web/HTML/Element/input/datetime-local": { + "Web/HTML/Reference/Elements/input/datetime-local": { "modified": "2020-10-15T21:53:48.461Z", "contributors": [ "mfuji09", @@ -94180,7 +93854,7 @@ "JonRimmer" ] }, - "Web/HTML/Element/input/email": { + "Web/HTML/Reference/Elements/input/email": { "modified": "2020-10-15T21:53:21.665Z", "contributors": [ "mfuji09", @@ -94201,7 +93875,7 @@ "rolfedh" ] }, - "Web/HTML/Element/input/file": { + "Web/HTML/Reference/Elements/input/file": { "modified": "2020-10-15T21:54:01.153Z", "contributors": [ "mfuji09", @@ -94229,7 +93903,7 @@ "gauravmahto" ] }, - "Web/HTML/Element/input/hidden": { + "Web/HTML/Reference/Elements/input/hidden": { "modified": "2020-10-15T21:53:47.747Z", "contributors": [ "mfuji09", @@ -94241,7 +93915,7 @@ "jurasadam" ] }, - "Web/HTML/Element/input/image": { + "Web/HTML/Reference/Elements/input/image": { "modified": "2020-10-15T21:33:36.830Z", "contributors": [ "mfuji09", @@ -94264,7 +93938,7 @@ "sidgan" ] }, - "Web/HTML/Element/input/month": { + "Web/HTML/Reference/Elements/input/month": { "modified": "2020-10-20T10:47:43.179Z", "contributors": [ "stevenfowler16", @@ -94278,7 +93952,7 @@ "schalkneethling" ] }, - "Web/HTML/Element/input/number": { + "Web/HTML/Reference/Elements/input/number": { "modified": "2020-11-23T12:58:07.465Z", "contributors": [ "nfortuin", @@ -94300,7 +93974,7 @@ "vaindil" ] }, - "Web/HTML/Element/input/password": { + "Web/HTML/Reference/Elements/input/password": { "modified": "2020-12-11T07:02:39.791Z", "contributors": [ "bershanskiy", @@ -94321,7 +93995,7 @@ "JJMC" ] }, - "Web/HTML/Element/input/radio": { + "Web/HTML/Reference/Elements/input/radio": { "modified": "2020-11-29T21:36:12.632Z", "contributors": [ "brianjenkins94", @@ -94347,7 +94021,7 @@ "ku3nsting" ] }, - "Web/HTML/Element/input/range": { + "Web/HTML/Reference/Elements/input/range": { "modified": "2020-10-15T21:53:48.471Z", "contributors": [ "mfuji09", @@ -94367,7 +94041,7 @@ "mltsy" ] }, - "Web/HTML/Element/input/reset": { + "Web/HTML/Reference/Elements/input/reset": { "modified": "2020-10-15T21:55:49.545Z", "contributors": [ "mfuji09", @@ -94378,7 +94052,7 @@ "chrisdavidmills" ] }, - "Web/HTML/Element/input/search": { + "Web/HTML/Reference/Elements/input/search": { "modified": "2020-10-15T21:55:50.406Z", "contributors": [ "mfuji09", @@ -94397,7 +94071,7 @@ "nmunro" ] }, - "Web/HTML/Element/input/submit": { + "Web/HTML/Reference/Elements/input/submit": { "modified": "2020-10-15T21:55:49.488Z", "contributors": [ "mfuji09", @@ -94410,7 +94084,7 @@ "chrisdavidmills" ] }, - "Web/HTML/Element/input/tel": { + "Web/HTML/Reference/Elements/input/tel": { "modified": "2020-10-15T21:57:05.528Z", "contributors": [ "mfuji09", @@ -94425,7 +94099,7 @@ "chrisdavidmills" ] }, - "Web/HTML/Element/input/text": { + "Web/HTML/Reference/Elements/input/text": { "modified": "2020-10-15T21:57:06.458Z", "contributors": [ "mfuji09", @@ -94438,7 +94112,7 @@ "chrisdavidmills" ] }, - "Web/HTML/Element/input/time": { + "Web/HTML/Reference/Elements/input/time": { "modified": "2020-10-15T21:56:35.773Z", "contributors": [ "mfuji09", @@ -94458,7 +94132,7 @@ "zacharydenton" ] }, - "Web/HTML/Element/input/url": { + "Web/HTML/Reference/Elements/input/url": { "modified": "2020-10-15T21:57:05.073Z", "contributors": [ "mfuji09", @@ -94471,7 +94145,7 @@ "crosscompile" ] }, - "Web/HTML/Element/input/week": { + "Web/HTML/Reference/Elements/input/week": { "modified": "2020-10-15T21:56:36.014Z", "contributors": [ "mfuji09", @@ -94484,7 +94158,7 @@ "jnetterf" ] }, - "Web/HTML/Element/ins": { + "Web/HTML/Reference/Elements/ins": { "modified": "2020-10-15T21:02:25.619Z", "contributors": [ "realityforge", @@ -94512,7 +94186,7 @@ "McGurk" ] }, - "Web/HTML/Element/kbd": { + "Web/HTML/Reference/Elements/kbd": { "modified": "2020-10-15T21:11:48.713Z", "contributors": [ "mfuji09", @@ -94549,7 +94223,7 @@ "Jscher2000" ] }, - "Web/HTML/Element/label": { + "Web/HTML/Reference/Elements/label": { "modified": "2020-10-15T21:09:51.433Z", "contributors": [ "thelovekesh", @@ -94606,7 +94280,7 @@ "Crash" ] }, - "Web/HTML/Element/legend": { + "Web/HTML/Reference/Elements/legend": { "modified": "2020-10-15T21:11:50.103Z", "contributors": [ "mfuji09", @@ -94636,7 +94310,7 @@ "McGurk" ] }, - "Web/HTML/Element/li": { + "Web/HTML/Reference/Elements/li": { "modified": "2020-12-02T05:38:35.783Z", "contributors": [ "mfuji09", @@ -94673,7 +94347,7 @@ "PablO" ] }, - "Web/HTML/Element/link": { + "Web/HTML/Reference/Elements/link": { "modified": "2020-11-30T16:48:55.422Z", "contributors": [ "Malvoz", @@ -94745,7 +94419,7 @@ "PablO" ] }, - "Web/HTML/Element/main": { + "Web/HTML/Reference/Elements/main": { "modified": "2020-12-14T11:23:08.419Z", "contributors": [ "mfuji09", @@ -94791,7 +94465,7 @@ "ccarruitero" ] }, - "Web/HTML/Element/map": { + "Web/HTML/Reference/Elements/map": { "modified": "2020-10-15T21:11:47.532Z", "contributors": [ "mfuji09", @@ -94825,7 +94499,7 @@ "McGurk" ] }, - "Web/HTML/Element/mark": { + "Web/HTML/Reference/Elements/mark": { "modified": "2020-10-15T21:06:15.476Z", "contributors": [ "JamesCatt", @@ -94867,7 +94541,7 @@ "sicking" ] }, - "Web/HTML/Element/marquee": { + "Web/HTML/Reference/Elements/marquee": { "modified": "2020-10-15T21:05:17.534Z", "contributors": [ "Koavf", @@ -94904,7 +94578,7 @@ "Judodudo" ] }, - "Web/HTML/Element/menu": { + "Web/HTML/Reference/Elements/menu": { "modified": "2020-10-15T21:05:00.029Z", "contributors": [ "JamesCatt", @@ -94951,7 +94625,7 @@ "Yann Dìnendal" ] }, - "Web/HTML/Element/meta": { + "Web/HTML/Reference/Elements/meta": { "modified": "2020-10-15T21:07:10.507Z", "contributors": [ "MrDOS", @@ -95041,15 +94715,15 @@ "Ms2ger" ] }, - "Web/HTML/Element/meta/name": { + "Web/HTML/Reference/Elements/meta/name": { "modified": "2020-10-15T22:29:26.188Z", "contributors": ["sideshowbarker", "mfuji09", "brandonlazarre"] }, - "Web/HTML/Element/meta/name/theme-color": { + "Web/HTML/Reference/Elements/meta/name/theme-color": { "modified": "2020-10-15T22:29:24.383Z", "contributors": ["sideshowbarker"] }, - "Web/HTML/Element/meter": { + "Web/HTML/Reference/Elements/meter": { "modified": "2020-10-15T21:07:37.041Z", "contributors": [ "williamwisdom", @@ -95084,7 +94758,7 @@ "hobophobe" ] }, - "Web/HTML/Element/nav": { + "Web/HTML/Reference/Elements/nav": { "modified": "2020-10-15T21:05:05.849Z", "contributors": [ "JamesCatt", @@ -95109,7 +94783,7 @@ "jswisher" ] }, - "Web/HTML/Element/nobr": { + "Web/HTML/Reference/Elements/nobr": { "modified": "2020-10-15T21:09:48.402Z", "contributors": [ "sideshowbarker", @@ -95131,7 +94805,7 @@ "thomasbilk" ] }, - "Web/HTML/Element/noembed": { + "Web/HTML/Reference/Elements/noembed": { "modified": "2020-10-15T21:27:00.422Z", "contributors": [ "alattalatta", @@ -95149,7 +94823,7 @@ "amylynn" ] }, - "Web/HTML/Element/noframes": { + "Web/HTML/Reference/Elements/noframes": { "modified": "2020-10-15T21:20:19.276Z", "contributors": [ "sideshowbarker", @@ -95165,7 +94839,7 @@ "avsaro" ] }, - "Web/HTML/Element/noscript": { + "Web/HTML/Reference/Elements/noscript": { "modified": "2020-12-03T07:26:47.512Z", "contributors": [ "mfuji09", @@ -95190,7 +94864,7 @@ "bradleymeck" ] }, - "Web/HTML/Element/object": { + "Web/HTML/Reference/Elements/object": { "modified": "2020-11-09T12:25:25.442Z", "contributors": [ "mfuji09", @@ -95229,7 +94903,7 @@ "jswisher" ] }, - "Web/HTML/Element/ol": { + "Web/HTML/Reference/Elements/ol": { "modified": "2020-10-15T21:04:03.701Z", "contributors": [ "mfuji09", @@ -95272,7 +94946,7 @@ "PablO" ] }, - "Web/HTML/Element/optgroup": { + "Web/HTML/Reference/Elements/optgroup": { "modified": "2020-10-15T21:11:51.006Z", "contributors": [ "escattone", @@ -95299,7 +94973,7 @@ "bradleymeck" ] }, - "Web/HTML/Element/option": { + "Web/HTML/Reference/Elements/option": { "modified": "2020-10-15T21:07:05.097Z", "contributors": [ "silvasur", @@ -95336,7 +95010,7 @@ "jswisher" ] }, - "Web/HTML/Element/output": { + "Web/HTML/Reference/Elements/output": { "modified": "2020-10-15T21:11:08.434Z", "contributors": [ "mfuji09", @@ -95378,7 +95052,7 @@ "Crash" ] }, - "Web/HTML/Element/p": { + "Web/HTML/Reference/Elements/p": { "modified": "2020-10-15T21:03:02.869Z", "contributors": [ "JamesCatt", @@ -95418,7 +95092,7 @@ "PablO" ] }, - "Web/HTML/Element/param": { + "Web/HTML/Reference/Elements/param": { "modified": "2020-10-15T21:11:44.660Z", "contributors": [ "JamesCatt", @@ -95438,7 +95112,7 @@ "McGurk" ] }, - "Web/HTML/Element/picture": { + "Web/HTML/Reference/Elements/picture": { "modified": "2020-10-19T20:23:06.118Z", "contributors": [ "hamishwillee", @@ -95477,7 +95151,7 @@ "realityking" ] }, - "Web/HTML/Element/plaintext": { + "Web/HTML/Reference/Elements/plaintext": { "modified": "2020-10-15T21:11:47.089Z", "contributors": [ "Tigt", @@ -95494,7 +95168,7 @@ "cers" ] }, - "Web/HTML/Element/pre": { + "Web/HTML/Reference/Elements/pre": { "modified": "2020-10-15T21:03:05.813Z", "contributors": [ "wendko", @@ -95524,7 +95198,7 @@ "osdm" ] }, - "Web/HTML/Element/progress": { + "Web/HTML/Reference/Elements/progress": { "modified": "2020-10-15T21:04:12.774Z", "contributors": [ "JamesCatt", @@ -95578,7 +95252,7 @@ "Yann Dìnendal" ] }, - "Web/HTML/Element/q": { + "Web/HTML/Reference/Elements/q": { "modified": "2020-12-04T14:23:50.601Z", "contributors": [ "mfuji09", @@ -95615,7 +95289,7 @@ "PablO" ] }, - "Web/HTML/Element/rb": { + "Web/HTML/Reference/Elements/rb": { "modified": "2020-10-15T22:06:47.131Z", "contributors": [ "mfuji09", @@ -95625,7 +95299,7 @@ "fscholz" ] }, - "Web/HTML/Element/rp": { + "Web/HTML/Reference/Elements/rp": { "modified": "2020-10-15T21:20:21.978Z", "contributors": [ "JamesCatt", @@ -95650,7 +95324,7 @@ "avsaro" ] }, - "Web/HTML/Element/rt": { + "Web/HTML/Reference/Elements/rt": { "modified": "2020-10-15T21:20:23.609Z", "contributors": [ "JamesCatt", @@ -95678,7 +95352,7 @@ "avsaro" ] }, - "Web/HTML/Element/rtc": { + "Web/HTML/Reference/Elements/rtc": { "modified": "2020-10-15T21:33:42.272Z", "contributors": [ "escattone", @@ -95699,7 +95373,7 @@ "Inkbug" ] }, - "Web/HTML/Element/ruby": { + "Web/HTML/Reference/Elements/ruby": { "modified": "2020-10-15T21:20:20.619Z", "contributors": [ "mfuji09", @@ -95731,7 +95405,7 @@ "avsaro" ] }, - "Web/HTML/Element/s": { + "Web/HTML/Reference/Elements/s": { "modified": "2020-12-10T00:49:54.220Z", "contributors": [ "12Me21", @@ -95770,7 +95444,7 @@ "alecananian" ] }, - "Web/HTML/Element/samp": { + "Web/HTML/Reference/Elements/samp": { "modified": "2020-10-15T21:06:13.039Z", "contributors": [ "JamesCatt", @@ -95803,7 +95477,7 @@ "Jscher2000" ] }, - "Web/HTML/Element/script": { + "Web/HTML/Reference/Elements/script": { "modified": "2020-10-15T21:08:40.530Z", "contributors": [ "mar77i", @@ -95905,7 +95579,7 @@ "PGaries" ] }, - "Web/HTML/Element/section": { + "Web/HTML/Reference/Elements/section": { "modified": "2020-10-15T21:10:46.489Z", "contributors": [ "JamesCatt", @@ -95940,7 +95614,7 @@ "jswisher" ] }, - "Web/HTML/Element/select": { + "Web/HTML/Reference/Elements/select": { "modified": "2020-11-23T07:47:15.858Z", "contributors": [ "chrisdavidmills", @@ -96001,7 +95675,7 @@ "volkmar" ] }, - "Web/HTML/Element/slot": { + "Web/HTML/Reference/Elements/slot": { "modified": "2020-10-15T21:51:35.826Z", "contributors": [ "JamesCatt", @@ -96017,7 +95691,7 @@ "Hfmanson" ] }, - "Web/HTML/Element/small": { + "Web/HTML/Reference/Elements/small": { "modified": "2020-10-15T21:03:02.458Z", "contributors": [ "wendko", @@ -96055,7 +95729,7 @@ "Charles" ] }, - "Web/HTML/Element/source": { + "Web/HTML/Reference/Elements/source": { "modified": "2020-11-19T22:10:57.243Z", "contributors": [ "brianjenkins94", @@ -96098,7 +95772,7 @@ "Ms2ger" ] }, - "Web/HTML/Element/span": { + "Web/HTML/Reference/Elements/span": { "modified": "2020-10-15T21:05:12.193Z", "contributors": [ "JamesCatt", @@ -96135,7 +95809,7 @@ "osdm" ] }, - "Web/HTML/Element/strike": { + "Web/HTML/Reference/Elements/strike": { "modified": "2020-11-19T03:10:03.810Z", "contributors": [ "sideshowbarker", @@ -96155,7 +95829,7 @@ "fscholz" ] }, - "Web/HTML/Element/strong": { + "Web/HTML/Reference/Elements/strong": { "modified": "2020-10-15T21:02:27.743Z", "contributors": [ "JamesCatt", @@ -96186,7 +95860,7 @@ "Jinexile" ] }, - "Web/HTML/Element/style": { + "Web/HTML/Reference/Elements/style": { "modified": "2020-10-15T21:04:01.063Z", "contributors": [ "JamesCatt", @@ -96238,7 +95912,7 @@ "osdm" ] }, - "Web/HTML/Element/sub": { + "Web/HTML/Reference/Elements/sub": { "modified": "2020-10-15T21:11:45.969Z", "contributors": [ "JamesCatt", @@ -96261,7 +95935,7 @@ "hobophobe" ] }, - "Web/HTML/Element/summary": { + "Web/HTML/Reference/Elements/summary": { "modified": "2020-10-15T21:09:40.441Z", "contributors": [ "JamesCatt", @@ -96293,7 +95967,7 @@ "ethertank" ] }, - "Web/HTML/Element/sup": { + "Web/HTML/Reference/Elements/sup": { "modified": "2020-10-15T21:11:42.946Z", "contributors": [ "JamesCatt", @@ -96318,7 +95992,7 @@ "hobophobe" ] }, - "Web/HTML/Element/table": { + "Web/HTML/Reference/Elements/table": { "modified": "2020-11-09T06:42:19.667Z", "contributors": [ "chrisdavidmills", @@ -96378,7 +96052,7 @@ "osdm" ] }, - "Web/HTML/Element/tbody": { + "Web/HTML/Reference/Elements/tbody": { "modified": "2020-12-04T13:21:47.704Z", "contributors": [ "mfuji09", @@ -96408,7 +96082,7 @@ "McGurk" ] }, - "Web/HTML/Element/td": { + "Web/HTML/Reference/Elements/td": { "modified": "2020-10-15T21:10:48.720Z", "contributors": [ "RainSlide", @@ -96451,7 +96125,7 @@ "McGurk" ] }, - "Web/HTML/Element/template": { + "Web/HTML/Reference/Elements/template": { "modified": "2020-10-15T21:25:50.327Z", "contributors": [ "danielrozenberg", @@ -96490,7 +96164,7 @@ "kscarfone" ] }, - "Web/HTML/Element/textarea": { + "Web/HTML/Reference/Elements/textarea": { "modified": "2020-11-19T22:27:58.934Z", "contributors": [ "brianjenkins94", @@ -96545,7 +96219,7 @@ "Ms2ger" ] }, - "Web/HTML/Element/tfoot": { + "Web/HTML/Reference/Elements/tfoot": { "modified": "2020-11-09T13:46:43.461Z", "contributors": [ "mfuji09", @@ -96573,7 +96247,7 @@ "McGurk" ] }, - "Web/HTML/Element/th": { + "Web/HTML/Reference/Elements/th": { "modified": "2020-10-15T21:10:49.348Z", "contributors": [ "mfuji09", @@ -96608,7 +96282,7 @@ "McGurk" ] }, - "Web/HTML/Element/thead": { + "Web/HTML/Reference/Elements/thead": { "modified": "2020-10-15T21:11:41.734Z", "contributors": [ "mfuji09", @@ -96635,7 +96309,7 @@ "McGurk" ] }, - "Web/HTML/Element/time": { + "Web/HTML/Reference/Elements/time": { "modified": "2020-10-15T21:08:03.433Z", "contributors": [ "JamesCatt", @@ -96682,7 +96356,7 @@ "hobophobe" ] }, - "Web/HTML/Element/title": { + "Web/HTML/Reference/Elements/title": { "modified": "2020-10-15T21:02:27.983Z", "contributors": [ "fscholz", @@ -96715,7 +96389,7 @@ "Ms2ger" ] }, - "Web/HTML/Element/tr": { + "Web/HTML/Reference/Elements/tr": { "modified": "2020-11-29T17:16:30.129Z", "contributors": [ "antoineveldhoven", @@ -96746,7 +96420,7 @@ "Ms2ger" ] }, - "Web/HTML/Element/track": { + "Web/HTML/Reference/Elements/track": { "modified": "2020-10-15T21:09:12.957Z", "contributors": [ "Pablo-No", @@ -96782,7 +96456,7 @@ "ethertank" ] }, - "Web/HTML/Element/tt": { + "Web/HTML/Reference/Elements/tt": { "modified": "2020-10-15T21:11:49.771Z", "contributors": [ "mfuji09", @@ -96802,7 +96476,7 @@ "Jscher2000" ] }, - "Web/HTML/Element/u": { + "Web/HTML/Reference/Elements/u": { "modified": "2020-10-15T21:05:44.278Z", "contributors": [ "Software202", @@ -96831,7 +96505,7 @@ "Ms2ger" ] }, - "Web/HTML/Element/ul": { + "Web/HTML/Reference/Elements/ul": { "modified": "2020-11-09T04:45:55.661Z", "contributors": [ "sideshowbarker", @@ -96863,7 +96537,7 @@ "PablO" ] }, - "Web/HTML/Element/var": { + "Web/HTML/Reference/Elements/var": { "modified": "2020-10-15T21:02:28.136Z", "contributors": [ "JamesCatt", @@ -96887,7 +96561,7 @@ "Ms2ger" ] }, - "Web/HTML/Element/video": { + "Web/HTML/Reference/Elements/video": { "modified": "2020-10-15T21:04:09.453Z", "contributors": [ "sideshowbarker", @@ -96974,7 +96648,7 @@ "BenoitL" ] }, - "Web/HTML/Element/wbr": { + "Web/HTML/Reference/Elements/wbr": { "modified": "2020-10-15T21:06:42.089Z", "contributors": [ "wendko", @@ -97007,7 +96681,7 @@ "jswisher" ] }, - "Web/HTML/Element/xmp": { + "Web/HTML/Reference/Elements/xmp": { "modified": "2020-10-15T21:12:02.224Z", "contributors": [ "teoli", @@ -97021,7 +96695,7 @@ "Ms2ger" ] }, - "Web/HTML/Global_attributes": { + "Web/HTML/Reference/Global_attributes": { "modified": "2020-11-30T07:20:59.253Z", "contributors": [ "mfuji09", @@ -97092,7 +96766,7 @@ "Ms2ger" ] }, - "Web/HTML/Global_attributes/accesskey": { + "Web/HTML/Reference/Global_attributes/accesskey": { "modified": "2020-10-15T21:31:57.595Z", "contributors": [ "compulim", @@ -97120,7 +96794,7 @@ "fscholz" ] }, - "Web/HTML/Global_attributes/autocapitalize": { + "Web/HTML/Reference/Global_attributes/autocapitalize": { "modified": "2020-11-09T15:34:48.028Z", "contributors": [ "mfuji09", @@ -97133,7 +96807,7 @@ "fscholz" ] }, - "Web/HTML/Global_attributes/class": { + "Web/HTML/Reference/Global_attributes/class": { "modified": "2020-10-15T21:31:59.267Z", "contributors": [ "estelle", @@ -97152,7 +96826,7 @@ "teoli" ] }, - "Web/HTML/Global_attributes/contenteditable": { + "Web/HTML/Reference/Global_attributes/contenteditable": { "modified": "2020-12-10T12:48:29.139Z", "contributors": [ "lukkea", @@ -97174,7 +96848,7 @@ "teoli" ] }, - "Web/HTML/Global_attributes/data-*": { + "Web/HTML/Reference/Global_attributes/data-*": { "modified": "2020-10-15T21:31:58.132Z", "contributors": [ "mfuji09", @@ -97191,7 +96865,7 @@ "teoli" ] }, - "Web/HTML/Global_attributes/dir": { + "Web/HTML/Reference/Global_attributes/dir": { "modified": "2020-10-15T21:32:00.377Z", "contributors": [ "mfuji09", @@ -97208,7 +96882,7 @@ "teoli" ] }, - "Web/HTML/Global_attributes/draggable": { + "Web/HTML/Reference/Global_attributes/draggable": { "modified": "2020-10-15T21:31:58.837Z", "contributors": [ "alattalatta", @@ -97226,7 +96900,7 @@ "teoli" ] }, - "Web/HTML/Global_attributes/hidden": { + "Web/HTML/Reference/Global_attributes/hidden": { "modified": "2020-10-19T23:34:29.844Z", "contributors": [ "h-h", @@ -97244,7 +96918,7 @@ "teoli" ] }, - "Web/HTML/Global_attributes/id": { + "Web/HTML/Reference/Global_attributes/id": { "modified": "2020-10-15T21:31:58.083Z", "contributors": [ "chrisdavidmills", @@ -97262,7 +96936,7 @@ "teoli" ] }, - "Web/HTML/Global_attributes/inputmode": { + "Web/HTML/Reference/Global_attributes/inputmode": { "modified": "2020-10-15T22:10:55.245Z", "contributors": [ "krosylight", @@ -97276,7 +96950,7 @@ "Sheppy" ] }, - "Web/HTML/Global_attributes/is": { + "Web/HTML/Reference/Global_attributes/is": { "modified": "2020-10-15T22:01:12.186Z", "contributors": [ "mfuji09", @@ -97287,7 +96961,7 @@ "ExE-Boss" ] }, - "Web/HTML/Global_attributes/itemid": { + "Web/HTML/Reference/Global_attributes/itemid": { "modified": "2020-10-15T21:43:26.830Z", "contributors": [ "alattalatta", @@ -97302,7 +96976,7 @@ "duncanmcdonald" ] }, - "Web/HTML/Global_attributes/itemprop": { + "Web/HTML/Reference/Global_attributes/itemprop": { "modified": "2020-10-15T21:40:03.790Z", "contributors": [ "Julix", @@ -97319,7 +96993,7 @@ "neotam" ] }, - "Web/HTML/Global_attributes/itemref": { + "Web/HTML/Reference/Global_attributes/itemref": { "modified": "2020-10-15T21:43:24.406Z", "contributors": [ "mfuji09", @@ -97334,7 +97008,7 @@ "duncanmcdonald" ] }, - "Web/HTML/Global_attributes/itemscope": { + "Web/HTML/Reference/Global_attributes/itemscope": { "modified": "2020-11-09T08:24:25.326Z", "contributors": [ "mfuji09", @@ -97359,7 +97033,7 @@ "neotam" ] }, - "Web/HTML/Global_attributes/itemtype": { + "Web/HTML/Reference/Global_attributes/itemtype": { "modified": "2020-10-15T21:43:26.706Z", "contributors": [ "mfuji09", @@ -97372,7 +97046,7 @@ "duncanmcdonald" ] }, - "Web/HTML/Global_attributes/lang": { + "Web/HTML/Reference/Global_attributes/lang": { "modified": "2020-11-28T10:00:31.590Z", "contributors": [ "Malvoz", @@ -97391,11 +97065,11 @@ "teoli" ] }, - "Web/HTML/Global_attributes/part": { + "Web/HTML/Reference/Global_attributes/part": { "modified": "2020-10-15T22:24:19.906Z", "contributors": ["mfuji09", "chrisdavidmills"] }, - "Web/HTML/Global_attributes/slot": { + "Web/HTML/Reference/Global_attributes/slot": { "modified": "2020-10-15T21:51:30.117Z", "contributors": [ "mfuji09", @@ -97405,7 +97079,7 @@ "sideshowbarker" ] }, - "Web/HTML/Global_attributes/spellcheck": { + "Web/HTML/Reference/Global_attributes/spellcheck": { "modified": "2020-11-30T07:59:03.762Z", "contributors": [ "mfuji09", @@ -97418,7 +97092,7 @@ "teoli" ] }, - "Web/HTML/Global_attributes/style": { + "Web/HTML/Reference/Global_attributes/style": { "modified": "2020-10-19T23:35:34.645Z", "contributors": [ "h-h", @@ -97431,7 +97105,7 @@ "teoli" ] }, - "Web/HTML/Global_attributes/tabindex": { + "Web/HTML/Reference/Global_attributes/tabindex": { "modified": "2020-12-09T12:37:03.390Z", "contributors": [ "Riah", @@ -97471,7 +97145,7 @@ "teoli" ] }, - "Web/HTML/Global_attributes/title": { + "Web/HTML/Reference/Global_attributes/title": { "modified": "2020-12-02T07:33:20.169Z", "contributors": [ "mfuji09", @@ -97492,7 +97166,7 @@ "teoli" ] }, - "Web/HTML/Global_attributes/translate": { + "Web/HTML/Reference/Global_attributes/translate": { "modified": "2020-11-28T10:01:33.906Z", "contributors": [ "Malvoz", @@ -97508,136 +97182,6 @@ "linfestus" ] }, - "Web/HTML/Microdata": { - "modified": "2020-09-06T05:55:47.630Z", - "contributors": [ - "mfuji09", - "alattalatta", - "Tantek", - "germain", - "evan-brass", - "sideshowbarker", - "Annevk", - "fscholz", - "stevenwdv", - "getschomp", - "teoli", - "rolfedh", - "duncanmcdonald" - ] - }, - "Web/HTML/Quirks_Mode_and_Standards_Mode": { - "modified": "2020-10-03T02:40:04.174Z", - "contributors": [ - "mfuji09", - "darby", - "erhan35", - "cRAN_cg", - "chrisdavidmills", - "matrimonio", - "JeremyPDonahue", - "Aleksey-Danchin", - "luke@mozilla.com", - "kscarfone", - "ethertank", - "nekretnine", - "Sheppy", - "jswisher", - "Dikrib", - "ziyunfei", - "George3", - "cesar_ortizg", - "kohei.yoshino", - "BenoitL", - "NickolayBot", - "DBaron", - "Dria", - "Mcaruso" - ] - }, - "Web/HTML/Reference": { - "modified": "2019-09-05T20:19:46.189Z", - "contributors": [ - "wbamberg", - "JCodeg", - "Sheppy", - "sideshowbarker", - "julio-elipse", - "mfuji09", - "dolorismachina", - "mfluehr", - "jswisher", - "greatdevaks", - "stingyong", - "rogerxas", - "Tee37", - "teoli", - "codemetro" - ] - }, - "Web/HTML/Responsive_images": { - "modified": "2020-10-19T20:26:21.787Z", - "contributors": [ - "hamishwillee", - "sideshowbarker", - "thjbd", - "chrisdavidmills", - "atd30", - "jpfkd", - "ramiy", - "JonDevOps", - "choudh70", - "tayyabalishan", - "Blacktodreamlight", - "Koavf", - "clairealyssa", - "eremis101", - "MNizam0802", - "oyenirat", - "Flimm", - "thenoelman", - "chelBot", - "dharkness", - "demont93", - "akshat12", - "imi-tating", - "msufa", - "Audaciter", - "stephaniehobson", - "dtrueman", - "goto.prototype", - "richardzacur", - "Sheppy", - "Jeremie", - "hbloomer", - "Andrew_Pfeiffer" - ] - }, - "Web/HTML/microformats": { - "modified": "2019-10-10T12:40:00.802Z", - "contributors": [ - "Tantek", - "SphinxKnight", - "sknebel", - "schmarty", - "jgmac1106", - "mfluehr", - "ExE-Boss", - "PushpitaPikuDey", - "jsx", - "jenifferhomes", - "Seta00", - "codeforuk", - "RenRen", - "teoli", - "marie-ototoi", - "rogerxas", - "mehmetaergun", - "xfq", - "Akilan_Arasu", - "barnabywalters" - ] - }, "Web/HTTP": { "modified": "2020-12-10T17:35:24.571Z", "contributors": [ @@ -97698,7 +97242,7 @@ "jreschke" ] }, - "Web/HTTP/Authentication": { + "Web/HTTP/Guides/Authentication": { "modified": "2020-07-22T12:14:27.800Z", "contributors": [ "cpmsmith", @@ -97724,7 +97268,7 @@ "teoli" ] }, - "Web/HTTP/Browser_detection_using_the_user_agent": { + "Web/HTTP/Guides/Browser_detection_using_the_user_agent": { "modified": "2020-07-11T11:53:53.804Z", "contributors": [ "Audaciter", @@ -97768,7 +97312,7 @@ "Sheppy" ] }, - "Web/HTTP/CORS": { + "Web/HTTP/Guides/CORS": { "modified": "2020-11-28T13:53:57.122Z", "contributors": [ "alcar", @@ -97910,15 +97454,15 @@ "aruner" ] }, - "Web/HTTP/CORS/Errors": { + "Web/HTTP/Guides/CORS/Errors": { "modified": "2019-03-18T21:32:10.250Z", "contributors": ["nchevobbe", "Sheppy", "fscholz"] }, - "Web/HTTP/CORS/Errors/CORSAllowOriginNotMatchingOrigin": { + "Web/HTTP/Guides/CORS/Errors/CORSAllowOriginNotMatchingOrigin": { "modified": "2019-03-18T20:41:55.080Z", "contributors": ["Cyllos42", "sideshowbarker", "Llamaless", "Sheppy"] }, - "Web/HTTP/CORS/Errors/CORSDidNotSucceed": { + "Web/HTTP/Guides/CORS/Errors/CORSDidNotSucceed": { "modified": "2019-09-18T04:32:54.888Z", "contributors": [ "chrisdavidmills", @@ -97930,39 +97474,39 @@ "Sheppy" ] }, - "Web/HTTP/CORS/Errors/CORSDisabled": { + "Web/HTTP/Guides/CORS/Errors/CORSDisabled": { "modified": "2019-03-18T21:30:26.108Z", "contributors": ["oyenirat", "sideshowbarker", "Sheppy"] }, - "Web/HTTP/CORS/Errors/CORSExternalRedirectNotAllowed": { + "Web/HTTP/Guides/CORS/Errors/CORSExternalRedirectNotAllowed": { "modified": "2019-03-18T21:30:24.369Z", "contributors": ["Sheppy"] }, - "Web/HTTP/CORS/Errors/CORSInvalidAllowHeader": { + "Web/HTTP/Guides/CORS/Errors/CORSInvalidAllowHeader": { "modified": "2019-01-17T03:18:44.378Z", "contributors": ["Llamaless", "Sheppy"] }, - "Web/HTTP/CORS/Errors/CORSInvalidAllowMethod": { + "Web/HTTP/Guides/CORS/Errors/CORSInvalidAllowMethod": { "modified": "2019-03-18T21:30:23.468Z", "contributors": ["Sheppy"] }, - "Web/HTTP/CORS/Errors/CORSMIssingAllowCredentials": { + "Web/HTTP/Guides/CORS/Errors/CORSMIssingAllowCredentials": { "modified": "2019-03-18T21:30:24.552Z", "contributors": ["Sheppy"] }, - "Web/HTTP/CORS/Errors/CORSMethodNotFound": { + "Web/HTTP/Guides/CORS/Errors/CORSMethodNotFound": { "modified": "2019-03-18T21:30:20.526Z", "contributors": ["Sheppy"] }, - "Web/HTTP/CORS/Errors/CORSMissingAllowHeaderFromPreflight": { + "Web/HTTP/Guides/CORS/Errors/CORSMissingAllowHeaderFromPreflight": { "modified": "2019-08-28T05:31:53.287Z", "contributors": ["mfuji09", "Sheppy"] }, - "Web/HTTP/CORS/Errors/CORSMissingAllowOrigin": { + "Web/HTTP/Guides/CORS/Errors/CORSMissingAllowOrigin": { "modified": "2019-12-06T11:22:11.534Z", "contributors": ["Lily418", "mfuji09", "nfagerlund", "jogoodma", "Sheppy"] }, - "Web/HTTP/CORS/Errors/CORSMultipleAllowOriginNotAllowed": { + "Web/HTTP/Guides/CORS/Errors/CORSMultipleAllowOriginNotAllowed": { "modified": "2019-03-18T21:30:03.639Z", "contributors": [ "sideshowbarker", @@ -97971,23 +97515,23 @@ "Sheppy" ] }, - "Web/HTTP/CORS/Errors/CORSNotSupportingCredentials": { + "Web/HTTP/Guides/CORS/Errors/CORSNotSupportingCredentials": { "modified": "2019-03-18T21:30:15.781Z", "contributors": ["Sheppy"] }, - "Web/HTTP/CORS/Errors/CORSOriginHeaderNotAdded": { + "Web/HTTP/Guides/CORS/Errors/CORSOriginHeaderNotAdded": { "modified": "2019-03-18T21:30:18.218Z", "contributors": ["MarinusSwan", "Sheppy"] }, - "Web/HTTP/CORS/Errors/CORSPreflightDidNotSucceed": { + "Web/HTTP/Guides/CORS/Errors/CORSPreflightDidNotSucceed": { "modified": "2019-03-18T21:30:19.809Z", "contributors": ["Sheppy"] }, - "Web/HTTP/CORS/Errors/CORSRequestNotHttp": { + "Web/HTTP/Guides/CORS/Errors/CORSRequestNotHttp": { "modified": "2019-07-15T18:12:14.537Z", "contributors": ["JeffersonScher", "Sheppy"] }, - "Web/HTTP/CSP": { + "Web/HTTP/Guides/CSP": { "modified": "2020-10-15T21:03:35.914Z", "contributors": [ "jswisher", @@ -98029,15 +97573,15 @@ "fryn" ] }, - "Web/HTTP/CSP/Errors": { + "Web/HTTP/Guides/CSP/Errors": { "modified": "2020-06-04T09:22:48.583Z", "contributors": ["Sheppy", "jswisher"] }, - "Web/HTTP/CSP/Errors/CSPViolation": { + "Web/HTTP/Guides/CSP/Errors/CSPViolation": { "modified": "2020-06-04T09:22:06.779Z", "contributors": ["Sheppy"] }, - "Web/HTTP/Caching": { + "Web/HTTP/Guides/Caching": { "modified": "2020-11-29T09:39:31.522Z", "contributors": [ "chrisdavidmills", @@ -98067,11 +97611,11 @@ "kohei.yoshino" ] }, - "Web/HTTP/Client_hints": { + "Web/HTTP/Guides/Client_hints": { "modified": "2019-07-01T18:32:07.538Z", "contributors": ["Malvoz", "jswisher", "estelle"] }, - "Web/HTTP/Compression": { + "Web/HTTP/Guides/Compression": { "modified": "2019-08-11T18:16:36.073Z", "contributors": [ "mozdevcontrib", @@ -98089,7 +97633,7 @@ "teoli" ] }, - "Web/HTTP/Conditional_requests": { + "Web/HTTP/Guides/Conditional_requests": { "modified": "2020-04-24T09:34:11.535Z", "contributors": [ "hyunchel", @@ -98103,7 +97647,7 @@ "teoli" ] }, - "Web/HTTP/Connection_management_in_HTTP_1.x": { + "Web/HTTP/Guides/Connection_management_in_HTTP_1.x": { "modified": "2019-11-27T11:05:48.174Z", "contributors": [ "leela52452", @@ -98121,7 +97665,7 @@ "teoli" ] }, - "Web/HTTP/Content_negotiation": { + "Web/HTTP/Guides/Content_negotiation": { "modified": "2020-11-05T20:33:02.045Z", "contributors": [ "hamishwillee", @@ -98149,7 +97693,7 @@ "Kennyluck" ] }, - "Web/HTTP/Content_negotiation/List_of_default_Accept_values": { + "Web/HTTP/Guides/Content_negotiation/List_of_default_Accept_values": { "modified": "2020-10-19T00:51:57.056Z", "contributors": [ "hamishwillee", @@ -98165,7 +97709,7 @@ "teoli" ] }, - "Web/HTTP/Cookies": { + "Web/HTTP/Guides/Cookies": { "modified": "2020-11-29T23:19:59.809Z", "contributors": [ "hamishwillee", @@ -98217,7 +97761,7 @@ "dbruant" ] }, - "Web/HTTP/Cross-Origin_Resource_Policy": { + "Web/HTTP/Guides/Cross-Origin_Resource_Policy": { "modified": "2020-10-15T22:16:18.437Z", "contributors": [ "dd-pardal", @@ -98228,7 +97772,7 @@ "fscholz" ] }, - "Web/HTTP/Evolution_of_HTTP": { + "Web/HTTP/Guides/Evolution_of_HTTP": { "modified": "2020-09-25T15:02:32.165Z", "contributors": [ "mfuji09", @@ -98252,7 +97796,246 @@ "teoli" ] }, - "Web/HTTP/Headers": { + "Web/HTTP/Guides/MIME_types": { + "modified": "2019-11-03T12:37:56.527Z", + "contributors": [ + "mfuji09", + "Sheppy", + "Alhadis", + "awwright", + "sideshowbarker", + "ExE-Boss", + "Dzonny", + "Tigt", + "tribak", + "amitgupta15", + "nakkurt", + "MicroJes", + "snuggs", + "d4nyll", + "xgqfrms-GitHub", + "dawsonbotsford", + "g-patel", + "strattadb", + "david_ross", + "DJ-Leith", + "teoli", + "fscholz" + ] + }, + "Web/HTTP/Guides/MIME_types/Common_types": { + "modified": "2020-05-01T18:32:40.232Z", + "contributors": [ + "broofa", + "sideshowbarker", + "chrisdavidmills", + "charj", + "SphinxKnight", + "mathiasbynens", + "Dorward", + "igorskyflyer", + "rctgamer3", + "mfuji09", + "Coder-Arjun", + "joeyparrish", + "devex23", + "ignaloidas", + "aadityataparia", + "dunglas", + "gabriele.bernuzzi", + "evilpie", + "xiaopanke", + "Loadmaster", + "iamakidilam", + "snuggs", + "Sheppy", + "Thw0rted", + "Krenair", + "Vikaash", + "Naesten", + "dave.shaheen", + "alettieri", + "NaveenDA", + "AbsoluteZERO", + "BrienA", + "kyrylkov", + "choury", + "david_ross", + "fscholz", + "teoli" + ] + }, + "Web/HTTP/Guides/Messages": { + "modified": "2020-12-03T23:53:07.614Z", + "contributors": [ + "hamishwillee", + "sideshowbarker", + "summerwinter201517", + "Martin.Winkler", + "s.m.mirismaili", + "lewislbr", + "samvk", + "msobanjo", + "Librazy", + "mfuji09", + "jamrocha", + "camille347", + "Youmoo", + "stephaniehobson", + "zhitaoh", + "david_ross", + "smalllong", + "DarrenLester", + "fscholz", + "teoli" + ] + }, + "Web/HTTP/Guides/Network_Error_Logging": { + "modified": "2020-10-15T22:29:13.638Z", + "contributors": ["sideshowbarker", "lol768"] + }, + "Web/HTTP/Guides/Overview": { + "modified": "2020-09-15T11:32:01.897Z", + "contributors": [ + "WenJuWu", + "chrisdavidmills", + "CPMoviePHil", + "estelle", + "drivasperez", + "jswisher", + "segmentationfaulter", + "mfuji09", + "yackSpillsaps", + "ronny-macmaster", + "dcrouch79", + "Sheppy", + "fscholz", + "michaelbaxter", + "Sergio_Gonzalez_Collado", + "danielgormly", + "aaronArinder", + "SpikePy", + "arssonist", + "protopatterns", + "derick-montague", + "zhitaoh", + "Jeremie", + "david_ross", + "arosenberg01", + "tanya-marfel", + "teoli" + ] + }, + "Web/HTTP/Guides/Permissions_Policy": { + "modified": "2020-10-18T22:29:08.695Z", + "contributors": [ + "hamishwillee", + "mfuji09", + "Malvoz", + "old_morfey13", + "Sheppy", + "jpchase", + "leela52452", + "bershanskiy", + "ashleybooniphone", + "fscholz", + "jpmedley" + ] + }, + "Web/HTTP/Guides/Protocol_upgrade_mechanism": { + "modified": "2020-11-29T09:42:13.104Z", + "contributors": [ + "chrisdavidmills", + "Bilal", + "mfuji09", + "zambini", + "mnottingham", + "aymericbeaumet", + "himanshub16", + "noahbenham", + "Sheppy", + "TheT0dd", + "teoli" + ] + }, + "Web/HTTP/Guides/Proxy_servers_and_tunneling": { + "modified": "2020-10-13T12:48:38.648Z", + "contributors": ["jwerre", "mfuji09", "r-thomps", "teoli", "fscholz"] + }, + "Web/HTTP/Guides/Proxy_servers_and_tunneling/Proxy_Auto-Configuration_PAC_file": { + "modified": "2020-10-12T08:18:46.998Z", + "contributors": [ + "SphinxKnight", + "jibonmobileq", + "mfuji09", + "lewisje", + "Artoria2e5", + "RainSlide", + "Gizeta", + "erosman", + "fscholz", + "orisano", + "Sheppy", + "GeneralFailer", + "teoli", + "GabrielCorona", + "galejwnaylor", + "xeonchen", + "rolfedh", + "duncanmcdonald" + ] + }, + "Web/HTTP/Guides/Range_requests": { + "modified": "2019-11-13T09:33:18.325Z", + "contributors": [ + "tkutz", + "Alexis Wilke1", + "thierry.henrio", + "momijimimiga", + "BaderSur", + "fscholz" + ] + }, + "Web/HTTP/Guides/Redirections": { + "modified": "2020-11-23T11:01:59.977Z", + "contributors": [ + "sideshowbarker", + "alessiogasparini02", + "mfuji09", + "avi-levy", + "Tigt", + "ptletski", + "fmonjalet", + "cypressf", + "zonidjan", + "dnafication", + "rileym7", + "VladPavel15", + "HTMLValidator", + "WayneCui", + "lmsteffan", + "nackman", + "oxfist", + "fscholz", + "teoli" + ] + }, + "Web/HTTP/Guides/Session": { + "modified": "2019-07-31T02:53:01.366Z", + "contributors": [ + "vriojtg", + "witaly-iwanow", + "SphinxKnight", + "AranGarcia", + "stephaniehobson", + "rickwest", + "david_ross", + "DarrenLester", + "fscholz", + "groovecoder" + ] + }, + "Web/HTTP/Reference/Headers": { "modified": "2020-11-16T08:22:37.817Z", "contributors": [ "chrisdavidmills", @@ -98290,7 +98073,7 @@ "dbruant" ] }, - "Web/HTTP/Headers/Accept": { + "Web/HTTP/Reference/Headers/Accept": { "modified": "2020-10-15T21:48:47.067Z", "contributors": [ "mfuji09", @@ -98303,11 +98086,11 @@ "teoli" ] }, - "Web/HTTP/Headers/Accept-CH": { + "Web/HTTP/Reference/Headers/Accept-CH": { "modified": "2020-10-15T22:23:14.705Z", "contributors": ["j9t", "Malvoz", "bershanskiy"] }, - "Web/HTTP/Headers/Accept-Encoding": { + "Web/HTTP/Reference/Headers/Accept-Encoding": { "modified": "2020-12-04T01:30:23.076Z", "contributors": [ "mfuji09", @@ -98321,7 +98104,7 @@ "teoli" ] }, - "Web/HTTP/Headers/Accept-Language": { + "Web/HTTP/Reference/Headers/Accept-Language": { "modified": "2020-10-15T21:48:48.993Z", "contributors": [ "xec", @@ -98338,7 +98121,7 @@ "teoli" ] }, - "Web/HTTP/Headers/Accept-Patch": { + "Web/HTTP/Reference/Headers/Accept-Patch": { "modified": "2020-11-16T20:29:25.583Z", "contributors": [ "hamishwillee", @@ -98348,15 +98131,15 @@ "jswisher" ] }, - "Web/HTTP/Headers/Accept-Post": { + "Web/HTTP/Reference/Headers/Accept-Post": { "modified": "2020-11-16T20:26:48.212Z", "contributors": ["hamishwillee", "chrisdavidmills"] }, - "Web/HTTP/Headers/Accept-Ranges": { + "Web/HTTP/Reference/Headers/Accept-Ranges": { "modified": "2020-10-15T21:48:44.122Z", "contributors": ["andryanmiller", "mfuji09", "ExE-Boss", "fscholz", "teoli"] }, - "Web/HTTP/Headers/Access-Control-Allow-Credentials": { + "Web/HTTP/Reference/Headers/Access-Control-Allow-Credentials": { "modified": "2020-10-15T21:49:51.584Z", "contributors": [ "mfuji09", @@ -98367,7 +98150,7 @@ "alex-pollan" ] }, - "Web/HTTP/Headers/Access-Control-Allow-Headers": { + "Web/HTTP/Reference/Headers/Access-Control-Allow-Headers": { "modified": "2020-11-11T23:32:48.910Z", "contributors": [ "sideshowbarker", @@ -98383,11 +98166,11 @@ "teoli" ] }, - "Web/HTTP/Headers/Access-Control-Allow-Methods": { + "Web/HTTP/Reference/Headers/Access-Control-Allow-Methods": { "modified": "2020-10-15T21:49:51.878Z", "contributors": ["mfuji09", "fscholz", "teoli"] }, - "Web/HTTP/Headers/Access-Control-Allow-Origin": { + "Web/HTTP/Reference/Headers/Access-Control-Allow-Origin": { "modified": "2020-10-15T21:49:52.372Z", "contributors": [ "mfuji09", @@ -98406,7 +98189,7 @@ "teoli" ] }, - "Web/HTTP/Headers/Access-Control-Expose-Headers": { + "Web/HTTP/Reference/Headers/Access-Control-Expose-Headers": { "modified": "2020-10-21T13:18:54.517Z", "contributors": [ "bulk88", @@ -98418,7 +98201,7 @@ "Sebsonic" ] }, - "Web/HTTP/Headers/Access-Control-Max-Age": { + "Web/HTTP/Reference/Headers/Access-Control-Max-Age": { "modified": "2020-10-15T21:49:50.541Z", "contributors": [ "mfuji09", @@ -98430,7 +98213,7 @@ "teoli" ] }, - "Web/HTTP/Headers/Access-Control-Request-Headers": { + "Web/HTTP/Reference/Headers/Access-Control-Request-Headers": { "modified": "2020-11-28T12:17:27.584Z", "contributors": [ "bulk88", @@ -98443,19 +98226,19 @@ "teoli" ] }, - "Web/HTTP/Headers/Access-Control-Request-Method": { + "Web/HTTP/Reference/Headers/Access-Control-Request-Method": { "modified": "2020-10-15T21:49:53.333Z", "contributors": ["sideshowbarker", "fscholz", "teoli"] }, - "Web/HTTP/Headers/Age": { + "Web/HTTP/Reference/Headers/Age": { "modified": "2020-10-15T21:48:42.760Z", "contributors": ["fscholz"] }, - "Web/HTTP/Headers/Allow": { + "Web/HTTP/Reference/Headers/Allow": { "modified": "2020-09-29T09:50:02.889Z", "contributors": ["mfuji09", "jxub", "GabrielHautclocq", "fscholz"] }, - "Web/HTTP/Headers/Alt-Svc": { + "Web/HTTP/Reference/Headers/Alt-Svc": { "modified": "2020-10-15T22:09:34.585Z", "contributors": [ "Wind1808", @@ -98465,11 +98248,11 @@ "ExE-Boss" ] }, - "Web/HTTP/Headers/Authorization": { + "Web/HTTP/Reference/Headers/Authorization": { "modified": "2020-02-23T03:18:18.182Z", "contributors": ["snuggs", "mfuji09", "zachvalenta", "teoli", "fscholz"] }, - "Web/HTTP/Headers/Cache-Control": { + "Web/HTTP/Reference/Headers/Cache-Control": { "modified": "2020-11-24T21:54:28.716Z", "contributors": [ "iwanaga", @@ -98502,7 +98285,7 @@ "Life777" ] }, - "Web/HTTP/Headers/Clear-Site-Data": { + "Web/HTTP/Reference/Headers/Clear-Site-Data": { "modified": "2020-10-15T22:06:55.345Z", "contributors": [ "mfuji09", @@ -98513,7 +98296,7 @@ "fscholz" ] }, - "Web/HTTP/Headers/Connection": { + "Web/HTTP/Reference/Headers/Connection": { "modified": "2020-10-15T21:31:56.480Z", "contributors": [ "sideshowbarker", @@ -98527,7 +98310,7 @@ "mindscratch" ] }, - "Web/HTTP/Headers/Content-Disposition": { + "Web/HTTP/Reference/Headers/Content-Disposition": { "modified": "2020-11-09T01:15:54.576Z", "contributors": [ "hamishwillee", @@ -98547,7 +98330,7 @@ "teoli" ] }, - "Web/HTTP/Headers/Content-Encoding": { + "Web/HTTP/Reference/Headers/Content-Encoding": { "modified": "2020-10-15T21:39:34.035Z", "contributors": [ "mfuji09", @@ -98561,15 +98344,15 @@ "teoli" ] }, - "Web/HTTP/Headers/Content-Language": { + "Web/HTTP/Reference/Headers/Content-Language": { "modified": "2020-10-15T21:48:01.396Z", "contributors": ["mfuji09", "xec", "fscholz", "Malvoz", "sposhe", "Jeremie"] }, - "Web/HTTP/Headers/Content-Length": { + "Web/HTTP/Reference/Headers/Content-Length": { "modified": "2020-10-15T21:48:03.752Z", "contributors": ["mfuji09", "kevinAlbs", "dwright213", "fscholz"] }, - "Web/HTTP/Headers/Content-Location": { + "Web/HTTP/Reference/Headers/Content-Location": { "modified": "2020-10-15T21:48:08.587Z", "contributors": [ "mfuji09", @@ -98580,11 +98363,11 @@ "teoli" ] }, - "Web/HTTP/Headers/Content-Range": { + "Web/HTTP/Reference/Headers/Content-Range": { "modified": "2020-10-15T21:51:40.727Z", "contributors": ["corehacker", "fscholz", "teoli"] }, - "Web/HTTP/Headers/Content-Security-Policy": { + "Web/HTTP/Reference/Headers/Content-Security-Policy": { "modified": "2020-10-15T21:31:59.287Z", "contributors": [ "jswisher", @@ -98611,7 +98394,7 @@ "kscarfone" ] }, - "Web/HTTP/Headers/Content-Security-Policy-Report-Only": { + "Web/HTTP/Reference/Headers/Content-Security-Policy-Report-Only": { "modified": "2020-10-15T21:50:30.058Z", "contributors": [ "mfuji09", @@ -98624,11 +98407,11 @@ "stilliard" ] }, - "Web/HTTP/Headers/Content-Security-Policy/base-uri": { + "Web/HTTP/Reference/Headers/Content-Security-Policy/base-uri": { "modified": "2020-12-09T19:34:26.665Z", "contributors": ["bershanskiy", "Tigt", "nhoizey", "fscholz"] }, - "Web/HTTP/Headers/Content-Security-Policy/block-all-mixed-content": { + "Web/HTTP/Reference/Headers/Content-Security-Policy/block-all-mixed-content": { "modified": "2020-12-12T05:41:17.770Z", "contributors": [ "sideshowbarker", @@ -98641,7 +98424,7 @@ "teoli" ] }, - "Web/HTTP/Headers/Content-Security-Policy/child-src": { + "Web/HTTP/Reference/Headers/Content-Security-Policy/child-src": { "modified": "2020-10-15T21:50:26.651Z", "contributors": [ "sideshowbarker", @@ -98652,7 +98435,7 @@ "teoli" ] }, - "Web/HTTP/Headers/Content-Security-Policy/connect-src": { + "Web/HTTP/Reference/Headers/Content-Security-Policy/connect-src": { "modified": "2020-10-15T21:50:28.717Z", "contributors": [ "Malvoz", @@ -98665,7 +98448,7 @@ "teoli" ] }, - "Web/HTTP/Headers/Content-Security-Policy/default-src": { + "Web/HTTP/Reference/Headers/Content-Security-Policy/default-src": { "modified": "2020-11-02T03:52:42.787Z", "contributors": [ "hamishwillee", @@ -98685,15 +98468,15 @@ "sergiferran" ] }, - "Web/HTTP/Headers/Content-Security-Policy/font-src": { + "Web/HTTP/Reference/Headers/Content-Security-Policy/font-src": { "modified": "2020-10-15T21:50:29.286Z", "contributors": ["Sheppy", "vrana", "fscholz", "teoli"] }, - "Web/HTTP/Headers/Content-Security-Policy/form-action": { + "Web/HTTP/Reference/Headers/Content-Security-Policy/form-action": { "modified": "2020-10-15T21:50:25.278Z", "contributors": ["ldv8434", "Sheppy", "Changaco", "fscholz", "teoli"] }, - "Web/HTTP/Headers/Content-Security-Policy/frame-ancestors": { + "Web/HTTP/Reference/Headers/Content-Security-Policy/frame-ancestors": { "modified": "2020-10-15T21:50:28.117Z", "contributors": [ "mfuji09", @@ -98710,7 +98493,7 @@ "teoli" ] }, - "Web/HTTP/Headers/Content-Security-Policy/frame-src": { + "Web/HTTP/Reference/Headers/Content-Security-Policy/frame-src": { "modified": "2020-10-15T21:50:28.864Z", "contributors": [ "mfuji09", @@ -98723,27 +98506,27 @@ "teoli" ] }, - "Web/HTTP/Headers/Content-Security-Policy/img-src": { + "Web/HTTP/Reference/Headers/Content-Security-Policy/img-src": { "modified": "2020-11-02T03:53:29.750Z", "contributors": ["mfuji09", "Sheppy", "fscholz", "teoli"] }, - "Web/HTTP/Headers/Content-Security-Policy/manifest-src": { + "Web/HTTP/Reference/Headers/Content-Security-Policy/manifest-src": { "modified": "2020-10-15T21:50:28.225Z", "contributors": ["mfuji09", "Sheppy", "vrana", "fscholz", "teoli"] }, - "Web/HTTP/Headers/Content-Security-Policy/media-src": { + "Web/HTTP/Reference/Headers/Content-Security-Policy/media-src": { "modified": "2020-10-15T21:50:29.782Z", "contributors": ["mfuji09", "Sheppy", "vrana", "fscholz", "teoli"] }, - "Web/HTTP/Headers/Content-Security-Policy/object-src": { + "Web/HTTP/Reference/Headers/Content-Security-Policy/object-src": { "modified": "2020-10-15T21:50:32.476Z", "contributors": ["mfuji09", "Sheppy", "vrana", "Malvoz", "fscholz"] }, - "Web/HTTP/Headers/Content-Security-Policy/prefetch-src": { + "Web/HTTP/Reference/Headers/Content-Security-Policy/prefetch-src": { "modified": "2020-10-15T22:21:20.756Z", "contributors": ["mfuji09", "bershanskiy"] }, - "Web/HTTP/Headers/Content-Security-Policy/report-to": { + "Web/HTTP/Reference/Headers/Content-Security-Policy/report-to": { "modified": "2020-10-15T22:03:06.085Z", "contributors": [ "andrewbluepiano", @@ -98755,7 +98538,7 @@ "venkat_reddy" ] }, - "Web/HTTP/Headers/Content-Security-Policy/report-uri": { + "Web/HTTP/Reference/Headers/Content-Security-Policy/report-uri": { "modified": "2020-10-15T21:50:37.343Z", "contributors": [ "Sheppy", @@ -98767,15 +98550,15 @@ "teoli" ] }, - "Web/HTTP/Headers/Content-Security-Policy/require-trusted-types-for": { + "Web/HTTP/Reference/Headers/Content-Security-Policy/require-trusted-types-for": { "modified": "2020-12-11T06:46:59.679Z", "contributors": ["bershanskiy", "koto", "chrisdavidmills"] }, - "Web/HTTP/Headers/Content-Security-Policy/sandbox": { + "Web/HTTP/Reference/Headers/Content-Security-Policy/sandbox": { "modified": "2020-10-15T21:50:25.282Z", "contributors": ["Tigt", "mfuji09", "Malvoz", "Sheppy", "fscholz", "teoli"] }, - "Web/HTTP/Headers/Content-Security-Policy/script-src": { + "Web/HTTP/Reference/Headers/Content-Security-Policy/script-src": { "modified": "2020-10-15T21:50:30.405Z", "contributors": [ "mfuji09", @@ -98796,15 +98579,15 @@ "teoli" ] }, - "Web/HTTP/Headers/Content-Security-Policy/script-src-attr": { + "Web/HTTP/Reference/Headers/Content-Security-Policy/script-src-attr": { "modified": "2020-10-15T22:21:29.344Z", "contributors": ["bershanskiy"] }, - "Web/HTTP/Headers/Content-Security-Policy/script-src-elem": { + "Web/HTTP/Reference/Headers/Content-Security-Policy/script-src-elem": { "modified": "2020-10-15T22:21:16.538Z", "contributors": ["mfuji09", "bershanskiy"] }, - "Web/HTTP/Headers/Content-Security-Policy/style-src": { + "Web/HTTP/Reference/Headers/Content-Security-Policy/style-src": { "modified": "2020-10-30T09:37:56.510Z", "contributors": [ "mikoMK", @@ -98819,15 +98602,15 @@ "fscholz" ] }, - "Web/HTTP/Headers/Content-Security-Policy/style-src-attr": { + "Web/HTTP/Reference/Headers/Content-Security-Policy/style-src-attr": { "modified": "2020-10-15T22:21:27.718Z", "contributors": ["bershanskiy"] }, - "Web/HTTP/Headers/Content-Security-Policy/style-src-elem": { + "Web/HTTP/Reference/Headers/Content-Security-Policy/style-src-elem": { "modified": "2020-10-15T22:21:28.238Z", "contributors": ["bershanskiy"] }, - "Web/HTTP/Headers/Content-Security-Policy/trusted-types": { + "Web/HTTP/Reference/Headers/Content-Security-Policy/trusted-types": { "modified": "2020-10-19T13:44:23.065Z", "contributors": [ "koto", @@ -98837,11 +98620,11 @@ "bershanskiy" ] }, - "Web/HTTP/Headers/Content-Security-Policy/upgrade-insecure-requests": { + "Web/HTTP/Reference/Headers/Content-Security-Policy/upgrade-insecure-requests": { "modified": "2020-10-15T21:50:38.585Z", "contributors": ["Sheppy", "Malvoz", "borisschapira", "fscholz", "teoli"] }, - "Web/HTTP/Headers/Content-Security-Policy/worker-src": { + "Web/HTTP/Reference/Headers/Content-Security-Policy/worker-src": { "modified": "2020-10-15T21:50:29.883Z", "contributors": [ "Sheppy", @@ -98856,7 +98639,7 @@ "teoli" ] }, - "Web/HTTP/Headers/Content-Type": { + "Web/HTTP/Reference/Headers/Content-Type": { "modified": "2020-11-09T00:10:45.824Z", "contributors": [ "hamishwillee", @@ -98876,7 +98659,7 @@ "Jeremie" ] }, - "Web/HTTP/Headers/Cookie": { + "Web/HTTP/Reference/Headers/Cookie": { "modified": "2020-11-26T19:58:21.862Z", "contributors": [ "hamishwillee", @@ -98888,27 +98671,27 @@ "teoli" ] }, - "Web/HTTP/Headers/Cross-Origin-Embedder-Policy": { + "Web/HTTP/Reference/Headers/Cross-Origin-Embedder-Policy": { "modified": "2020-10-15T22:31:47.379Z", "contributors": ["dhritzkiv", "fscholz"] }, - "Web/HTTP/Headers/Cross-Origin-Opener-Policy": { + "Web/HTTP/Reference/Headers/Cross-Origin-Opener-Policy": { "modified": "2020-10-15T22:31:44.344Z", "contributors": ["fscholz"] }, - "Web/HTTP/Headers/Cross-Origin-Resource-Policy": { + "Web/HTTP/Reference/Headers/Cross-Origin-Resource-Policy": { "modified": "2020-10-15T22:16:18.531Z", "contributors": ["mfuji09", "lol768", "Malvoz", "fscholz", "Annevk"] }, - "Web/HTTP/Headers/DNT": { + "Web/HTTP/Reference/Headers/DNT": { "modified": "2020-10-15T21:50:18.809Z", "contributors": ["jswisher", "darby", "fscholz", "gavdaddy27"] }, - "Web/HTTP/Headers/DPR": { + "Web/HTTP/Reference/Headers/DPR": { "modified": "2020-10-15T22:23:16.017Z", "contributors": ["mfuji09", "bershanskiy"] }, - "Web/HTTP/Headers/Date": { + "Web/HTTP/Reference/Headers/Date": { "modified": "2020-10-15T21:48:40.265Z", "contributors": [ "WangZimei", @@ -98918,11 +98701,11 @@ "favalos989" ] }, - "Web/HTTP/Headers/Device-Memory": { + "Web/HTTP/Reference/Headers/Device-Memory": { "modified": "2020-10-15T22:23:16.957Z", "contributors": ["mfuji09", "darby", "bershanskiy"] }, - "Web/HTTP/Headers/ETag": { + "Web/HTTP/Reference/Headers/ETag": { "modified": "2020-10-15T21:48:49.703Z", "contributors": [ "mfuji09", @@ -98933,7 +98716,7 @@ "teoli" ] }, - "Web/HTTP/Headers/Early-Data": { + "Web/HTTP/Reference/Headers/Early-Data": { "modified": "2020-10-15T22:08:43.950Z", "contributors": [ "mfuji09", @@ -98943,7 +98726,7 @@ "chrisdavidmills" ] }, - "Web/HTTP/Headers/Expect": { + "Web/HTTP/Reference/Headers/Expect": { "modified": "2020-10-15T21:52:20.664Z", "contributors": [ "dizel3d", @@ -98954,7 +98737,7 @@ "zbjornson" ] }, - "Web/HTTP/Headers/Expect-CT": { + "Web/HTTP/Reference/Headers/Expect-CT": { "modified": "2020-10-15T22:00:19.349Z", "contributors": [ "jonathan-rosa", @@ -98973,11 +98756,11 @@ "jpmedley" ] }, - "Web/HTTP/Headers/Expires": { + "Web/HTTP/Reference/Headers/Expires": { "modified": "2020-10-15T21:48:40.215Z", "contributors": ["mfuji09", "fscholz", "Malvoz", "AndrzejSala", "meridius"] }, - "Web/HTTP/Headers/Forwarded": { + "Web/HTTP/Reference/Headers/Forwarded": { "modified": "2020-10-15T21:51:50.833Z", "contributors": [ "mvasin", @@ -98989,15 +98772,15 @@ "teoli" ] }, - "Web/HTTP/Headers/From": { + "Web/HTTP/Reference/Headers/From": { "modified": "2020-10-15T21:48:00.317Z", "contributors": ["fscholz", "Jeremie"] }, - "Web/HTTP/Headers/Host": { + "Web/HTTP/Reference/Headers/Host": { "modified": "2020-10-15T21:48:16.649Z", "contributors": ["mfuji09", "sideshowbarker", "SphinxKnight", "fscholz"] }, - "Web/HTTP/Headers/If-Match": { + "Web/HTTP/Reference/Headers/If-Match": { "modified": "2020-10-15T21:48:45.009Z", "contributors": [ "dwabece", @@ -99010,7 +98793,7 @@ "teoli" ] }, - "Web/HTTP/Headers/If-Modified-Since": { + "Web/HTTP/Reference/Headers/If-Modified-Since": { "modified": "2020-10-15T21:48:42.688Z", "contributors": [ "mfuji09", @@ -99020,7 +98803,7 @@ "teoli" ] }, - "Web/HTTP/Headers/If-None-Match": { + "Web/HTTP/Reference/Headers/If-None-Match": { "modified": "2020-10-15T21:48:43.146Z", "contributors": [ "mfuji09", @@ -99034,15 +98817,15 @@ "teoli" ] }, - "Web/HTTP/Headers/If-Range": { + "Web/HTTP/Reference/Headers/If-Range": { "modified": "2020-10-15T21:48:42.885Z", "contributors": ["fscholz", "teoli"] }, - "Web/HTTP/Headers/If-Unmodified-Since": { + "Web/HTTP/Reference/Headers/If-Unmodified-Since": { "modified": "2020-10-15T21:48:41.327Z", "contributors": ["mfuji09", "ExE-Boss", "zbjornson", "fscholz", "teoli"] }, - "Web/HTTP/Headers/Keep-Alive": { + "Web/HTTP/Reference/Headers/Keep-Alive": { "modified": "2020-12-05T09:58:55.455Z", "contributors": [ "mfuji09", @@ -99057,7 +98840,7 @@ "teoli" ] }, - "Web/HTTP/Headers/Last-Modified": { + "Web/HTTP/Reference/Headers/Last-Modified": { "modified": "2020-10-15T21:48:43.337Z", "contributors": [ "fscholz", @@ -99068,7 +98851,7 @@ "teoli" ] }, - "Web/HTTP/Headers/Link": { + "Web/HTTP/Reference/Headers/Link": { "modified": "2020-10-15T22:18:25.087Z", "contributors": [ "Malvoz", @@ -99079,7 +98862,7 @@ "ExE-Boss" ] }, - "Web/HTTP/Headers/Location": { + "Web/HTTP/Reference/Headers/Location": { "modified": "2020-10-15T21:48:47.797Z", "contributors": [ "sideshowbarker", @@ -99089,11 +98872,11 @@ "teoli" ] }, - "Web/HTTP/Headers/NEL": { + "Web/HTTP/Reference/Headers/NEL": { "modified": "2020-12-09T19:33:34.788Z", "contributors": ["bershanskiy", "sideshowbarker", "lol768"] }, - "Web/HTTP/Headers/Origin": { + "Web/HTTP/Reference/Headers/Origin": { "modified": "2020-10-15T21:49:48.638Z", "contributors": [ "AviKav", @@ -99104,7 +98887,7 @@ "teoli" ] }, - "Web/HTTP/Headers/Permissions-Policy": { + "Web/HTTP/Reference/Headers/Permissions-Policy": { "modified": "2020-10-15T22:07:47.010Z", "contributors": [ "hamishwillee", @@ -99119,35 +98902,31 @@ "jpmedley" ] }, - "Web/HTTP/Headers/Permissions-Policy/accelerometer": { + "Web/HTTP/Reference/Headers/Permissions-Policy/accelerometer": { "modified": "2020-10-15T22:20:16.702Z", "contributors": ["bershanskiy"] }, - "Web/HTTP/Headers/Permissions-Policy/ambient-light-sensor": { + "Web/HTTP/Reference/Headers/Permissions-Policy/ambient-light-sensor": { "modified": "2020-10-15T22:20:15.626Z", "contributors": ["verde79", "bershanskiy"] }, - "Web/HTTP/Headers/Permissions-Policy/autoplay": { + "Web/HTTP/Reference/Headers/Permissions-Policy/autoplay": { "modified": "2020-10-15T22:10:28.577Z", "contributors": ["bershanskiy", "Sheppy", "fscholz"] }, - "Web/HTTP/Headers/Permissions-Policy/camera": { + "Web/HTTP/Reference/Headers/Permissions-Policy/camera": { "modified": "2020-10-15T22:10:24.420Z", "contributors": ["bershanskiy", "Sheppy", "fscholz"] }, - "Web/HTTP/Headers/Permissions-Policy/display-capture": { + "Web/HTTP/Reference/Headers/Permissions-Policy/display-capture": { "modified": "2020-10-15T22:18:20.836Z", "contributors": ["sideshowbarker", "bershanskiy", "Sheppy"] }, - "Web/HTTP/Headers/Permissions-Policy/document-domain": { - "modified": "2020-10-15T22:11:41.981Z", - "contributors": ["bershanskiy", "chrisdavidmills", "sideshowbarker"] - }, - "Web/HTTP/Headers/Permissions-Policy/encrypted-media": { + "Web/HTTP/Reference/Headers/Permissions-Policy/encrypted-media": { "modified": "2020-10-15T22:10:28.002Z", "contributors": ["mfuji09", "bershanskiy", "fscholz"] }, - "Web/HTTP/Headers/Permissions-Policy/fullscreen": { + "Web/HTTP/Reference/Headers/Permissions-Policy/fullscreen": { "modified": "2020-10-15T22:07:59.873Z", "contributors": [ "chrisdavidmills", @@ -99157,35 +98936,35 @@ "jpmedley" ] }, - "Web/HTTP/Headers/Permissions-Policy/geolocation": { + "Web/HTTP/Reference/Headers/Permissions-Policy/geolocation": { "modified": "2020-10-15T22:07:59.720Z", "contributors": ["fscholz", "mfuji09", "jpmedley", "jpchase"] }, - "Web/HTTP/Headers/Permissions-Policy/gyroscope": { + "Web/HTTP/Reference/Headers/Permissions-Policy/gyroscope": { "modified": "2020-10-15T22:20:17.468Z", "contributors": ["bershanskiy"] }, - "Web/HTTP/Headers/Permissions-Policy/magnetometer": { + "Web/HTTP/Reference/Headers/Permissions-Policy/magnetometer": { "modified": "2020-10-15T22:20:14.856Z", "contributors": ["bershanskiy"] }, - "Web/HTTP/Headers/Permissions-Policy/microphone": { + "Web/HTTP/Reference/Headers/Permissions-Policy/microphone": { "modified": "2020-10-15T22:08:02.300Z", "contributors": ["fscholz", "mfuji09", "jpmedley"] }, - "Web/HTTP/Headers/Permissions-Policy/midi": { + "Web/HTTP/Reference/Headers/Permissions-Policy/midi": { "modified": "2020-10-15T22:10:24.122Z", "contributors": ["mfuji09", "bershanskiy", "fscholz"] }, - "Web/HTTP/Headers/Permissions-Policy/payment": { + "Web/HTTP/Reference/Headers/Permissions-Policy/payment": { "modified": "2020-10-15T22:10:32.310Z", "contributors": ["mfuji09", "bershanskiy", "equalsJeffH", "fscholz"] }, - "Web/HTTP/Headers/Permissions-Policy/picture-in-picture": { + "Web/HTTP/Reference/Headers/Permissions-Policy/picture-in-picture": { "modified": "2020-10-15T22:20:13.631Z", "contributors": ["bershanskiy"] }, - "Web/HTTP/Headers/Permissions-Policy/publickey-credentials-get": { + "Web/HTTP/Reference/Headers/Permissions-Policy/publickey-credentials-get": { "modified": "2020-10-15T22:21:51.682Z", "contributors": [ "sideshowbarker", @@ -99196,15 +98975,15 @@ "Malvoz" ] }, - "Web/HTTP/Headers/Permissions-Policy/screen-wake-lock": { + "Web/HTTP/Reference/Headers/Permissions-Policy/screen-wake-lock": { "modified": "2020-10-15T22:31:49.481Z", "contributors": ["bershanskiy"] }, - "Web/HTTP/Headers/Permissions-Policy/usb": { + "Web/HTTP/Reference/Headers/Permissions-Policy/usb": { "modified": "2020-10-15T22:20:16.110Z", "contributors": ["bershanskiy"] }, - "Web/HTTP/Headers/Permissions-Policy/web-share": { + "Web/HTTP/Reference/Headers/Permissions-Policy/web-share": { "modified": "2020-12-10T15:06:45.009Z", "contributors": [ "bershanskiy", @@ -99213,23 +98992,23 @@ "ericwilligers" ] }, - "Web/HTTP/Headers/Permissions-Policy/xr-spatial-tracking": { + "Web/HTTP/Reference/Headers/Permissions-Policy/xr-spatial-tracking": { "modified": "2020-10-15T22:24:55.820Z", "contributors": ["Manishearth", "sideshowbarker", "bershanskiy"] }, - "Web/HTTP/Headers/Pragma": { + "Web/HTTP/Reference/Headers/Pragma": { "modified": "2020-10-15T21:48:41.171Z", "contributors": ["fscholz", "teoli"] }, - "Web/HTTP/Headers/Proxy-Authenticate": { + "Web/HTTP/Reference/Headers/Proxy-Authenticate": { "modified": "2020-10-15T21:52:16.550Z", "contributors": ["fscholz", "abhinay2891", "teoli"] }, - "Web/HTTP/Headers/Proxy-Authorization": { + "Web/HTTP/Reference/Headers/Proxy-Authorization": { "modified": "2019-03-23T22:18:12.882Z", "contributors": ["teoli", "fscholz"] }, - "Web/HTTP/Headers/Range": { + "Web/HTTP/Reference/Headers/Range": { "modified": "2020-10-15T21:51:40.546Z", "contributors": [ "mfuji09", @@ -99242,7 +99021,7 @@ "teoli" ] }, - "Web/HTTP/Headers/Referer": { + "Web/HTTP/Reference/Headers/Referer": { "modified": "2020-10-15T21:48:18.408Z", "contributors": [ "carlin-scott", @@ -99258,7 +99037,7 @@ "Jeremie" ] }, - "Web/HTTP/Headers/Referrer-Policy": { + "Web/HTTP/Reference/Headers/Referrer-Policy": { "modified": "2020-11-24T02:55:05.698Z", "contributors": [ "bluezery", @@ -99284,11 +99063,11 @@ "pox" ] }, - "Web/HTTP/Headers/Retry-After": { + "Web/HTTP/Reference/Headers/Retry-After": { "modified": "2020-10-15T21:48:41.258Z", "contributors": ["afaulconbridge", "Onkar316", "pixeleffect", "fscholz"] }, - "Web/HTTP/Headers/Save-Data": { + "Web/HTTP/Reference/Headers/Save-Data": { "modified": "2020-10-15T22:17:44.630Z", "contributors": [ "Malvoz", @@ -99299,23 +99078,23 @@ "chrisdavidmills" ] }, - "Web/HTTP/Headers/Sec-Fetch-Dest": { + "Web/HTTP/Reference/Headers/Sec-Fetch-Dest": { "modified": "2020-11-28T19:27:09.575Z", "contributors": ["TimothyGu", "bershanskiy"] }, - "Web/HTTP/Headers/Sec-Fetch-Mode": { + "Web/HTTP/Reference/Headers/Sec-Fetch-Mode": { "modified": "2020-11-28T19:25:30.700Z", "contributors": ["TimothyGu", "bershanskiy"] }, - "Web/HTTP/Headers/Sec-Fetch-Site": { + "Web/HTTP/Reference/Headers/Sec-Fetch-Site": { "modified": "2020-11-28T19:28:05.323Z", "contributors": ["TimothyGu", "bershanskiy"] }, - "Web/HTTP/Headers/Sec-Fetch-User": { + "Web/HTTP/Reference/Headers/Sec-Fetch-User": { "modified": "2020-11-28T19:28:41.084Z", "contributors": ["TimothyGu", "bershanskiy"] }, - "Web/HTTP/Headers/Sec-WebSocket-Accept": { + "Web/HTTP/Reference/Headers/Sec-WebSocket-Accept": { "modified": "2020-10-15T22:07:13.576Z", "contributors": [ "Geobomatic", @@ -99325,15 +99104,15 @@ "neotam" ] }, - "Web/HTTP/Headers/Server": { + "Web/HTTP/Reference/Headers/Server": { "modified": "2020-10-15T21:48:09.504Z", "contributors": ["mfuji09", "Tigt", "fscholz"] }, - "Web/HTTP/Headers/Server-Timing": { + "Web/HTTP/Reference/Headers/Server-Timing": { "modified": "2020-10-15T22:05:37.811Z", "contributors": ["kronthto", "cvazac", "fscholz"] }, - "Web/HTTP/Headers/Set-Cookie": { + "Web/HTTP/Reference/Headers/Set-Cookie": { "modified": "2020-11-29T22:38:47.400Z", "contributors": [ "hamishwillee", @@ -99370,11 +99149,11 @@ "teoli" ] }, - "Web/HTTP/Headers/SourceMap": { + "Web/HTTP/Reference/Headers/SourceMap": { "modified": "2020-10-27T15:47:02.484Z", "contributors": ["Splaktar", "fscholz"] }, - "Web/HTTP/Headers/Strict-Transport-Security": { + "Web/HTTP/Reference/Headers/Strict-Transport-Security": { "modified": "2020-10-15T21:10:41.825Z", "contributors": [ "mfuji09", @@ -99418,7 +99197,7 @@ "sidstamm" ] }, - "Web/HTTP/Headers/TE": { + "Web/HTTP/Reference/Headers/TE": { "modified": "2020-10-15T21:48:01.125Z", "contributors": [ "Uplink03", @@ -99429,19 +99208,19 @@ "Jeremie" ] }, - "Web/HTTP/Headers/Timing-Allow-Origin": { + "Web/HTTP/Reference/Headers/Timing-Allow-Origin": { "modified": "2020-12-02T07:13:17.436Z", "contributors": ["mfuji09", "sideshowbarker", "baileylo", "chrisdavidmills"] }, - "Web/HTTP/Headers/Tk": { + "Web/HTTP/Reference/Headers/Tk": { "modified": "2020-10-15T21:50:18.248Z", "contributors": ["fscholz"] }, - "Web/HTTP/Headers/Trailer": { + "Web/HTTP/Reference/Headers/Trailer": { "modified": "2020-10-15T21:48:00.093Z", "contributors": ["fscholz", "Jeremie"] }, - "Web/HTTP/Headers/Transfer-Encoding": { + "Web/HTTP/Reference/Headers/Transfer-Encoding": { "modified": "2020-10-15T21:47:56.618Z", "contributors": [ "mfuji09", @@ -99455,15 +99234,15 @@ "Jeremie" ] }, - "Web/HTTP/Headers/Upgrade": { + "Web/HTTP/Reference/Headers/Upgrade": { "modified": "2020-12-13T19:17:49.497Z", "contributors": ["hamishwillee", "bershanskiy", "chrisdavidmills"] }, - "Web/HTTP/Headers/Upgrade-Insecure-Requests": { + "Web/HTTP/Reference/Headers/Upgrade-Insecure-Requests": { "modified": "2020-10-15T21:50:38.740Z", "contributors": ["mfuji09", "stevea1", "fscholz", "teoli"] }, - "Web/HTTP/Headers/User-Agent": { + "Web/HTTP/Reference/Headers/User-Agent": { "modified": "2020-11-11T03:37:37.848Z", "contributors": [ "gregbrich", @@ -99476,7 +99255,7 @@ "an_editor" ] }, - "Web/HTTP/Headers/User-Agent/Firefox": { + "Web/HTTP/Reference/Headers/User-Agent/Firefox": { "modified": "2019-09-25T15:32:54.363Z", "contributors": [ "Sheppy", @@ -99521,15 +99300,15 @@ "user01" ] }, - "Web/HTTP/Headers/Vary": { + "Web/HTTP/Reference/Headers/Vary": { "modified": "2020-10-15T21:48:47.420Z", "contributors": ["Malvoz", "fscholz", "teoli"] }, - "Web/HTTP/Headers/Via": { + "Web/HTTP/Reference/Headers/Via": { "modified": "2020-10-15T21:48:01.362Z", "contributors": ["fscholz"] }, - "Web/HTTP/Headers/WWW-Authenticate": { + "Web/HTTP/Reference/Headers/WWW-Authenticate": { "modified": "2020-10-15T21:52:16.554Z", "contributors": [ "rwv", @@ -99543,11 +99322,11 @@ "teoli" ] }, - "Web/HTTP/Headers/Warning": { + "Web/HTTP/Reference/Headers/Warning": { "modified": "2020-10-15T21:48:41.051Z", "contributors": ["chrisdavidmills", "janslow", "PotHix", "fscholz"] }, - "Web/HTTP/Headers/X-Content-Type-Options": { + "Web/HTTP/Reference/Headers/X-Content-Type-Options": { "modified": "2020-10-15T21:48:48.081Z", "contributors": [ "jswisher", @@ -99560,7 +99339,7 @@ "teoli" ] }, - "Web/HTTP/Headers/X-DNS-Prefetch-Control": { + "Web/HTTP/Reference/Headers/X-DNS-Prefetch-Control": { "modified": "2020-10-15T21:13:24.539Z", "contributors": [ "mozdevcontrib", @@ -99579,19 +99358,19 @@ "Sheppy" ] }, - "Web/HTTP/Headers/X-Forwarded-For": { + "Web/HTTP/Reference/Headers/X-Forwarded-For": { "modified": "2020-10-15T21:51:52.081Z", "contributors": ["fscholz", "teoli"] }, - "Web/HTTP/Headers/X-Forwarded-Host": { + "Web/HTTP/Reference/Headers/X-Forwarded-Host": { "modified": "2020-10-15T21:51:53.445Z", "contributors": ["fscholz", "teoli"] }, - "Web/HTTP/Headers/X-Forwarded-Proto": { + "Web/HTTP/Reference/Headers/X-Forwarded-Proto": { "modified": "2020-10-15T21:51:51.792Z", "contributors": ["fscholz"] }, - "Web/HTTP/Headers/X-Frame-Options": { + "Web/HTTP/Reference/Headers/X-Frame-Options": { "modified": "2020-10-15T21:08:01.129Z", "contributors": [ "Naesten", @@ -99647,7 +99426,7 @@ "Psz" ] }, - "Web/HTTP/Headers/X-XSS-Protection": { + "Web/HTTP/Reference/Headers/X-XSS-Protection": { "modified": "2020-10-15T21:50:40.404Z", "contributors": [ "hostmaster", @@ -99661,101 +99440,7 @@ "fscholz" ] }, - "Web/HTTP/MIME_types": { - "modified": "2019-11-03T12:37:56.527Z", - "contributors": [ - "mfuji09", - "Sheppy", - "Alhadis", - "awwright", - "sideshowbarker", - "ExE-Boss", - "Dzonny", - "Tigt", - "tribak", - "amitgupta15", - "nakkurt", - "MicroJes", - "snuggs", - "d4nyll", - "xgqfrms-GitHub", - "dawsonbotsford", - "g-patel", - "strattadb", - "david_ross", - "DJ-Leith", - "teoli", - "fscholz" - ] - }, - "Web/HTTP/MIME_types/Common_types": { - "modified": "2020-05-01T18:32:40.232Z", - "contributors": [ - "broofa", - "sideshowbarker", - "chrisdavidmills", - "charj", - "SphinxKnight", - "mathiasbynens", - "Dorward", - "igorskyflyer", - "rctgamer3", - "mfuji09", - "Coder-Arjun", - "joeyparrish", - "devex23", - "ignaloidas", - "aadityataparia", - "dunglas", - "gabriele.bernuzzi", - "evilpie", - "xiaopanke", - "Loadmaster", - "iamakidilam", - "snuggs", - "Sheppy", - "Thw0rted", - "Krenair", - "Vikaash", - "Naesten", - "dave.shaheen", - "alettieri", - "NaveenDA", - "AbsoluteZERO", - "BrienA", - "kyrylkov", - "choury", - "david_ross", - "fscholz", - "teoli" - ] - }, - "Web/HTTP/Messages": { - "modified": "2020-12-03T23:53:07.614Z", - "contributors": [ - "hamishwillee", - "sideshowbarker", - "summerwinter201517", - "Martin.Winkler", - "s.m.mirismaili", - "lewislbr", - "samvk", - "msobanjo", - "Librazy", - "mfuji09", - "jamrocha", - "camille347", - "Youmoo", - "stephaniehobson", - "zhitaoh", - "david_ross", - "smalllong", - "DarrenLester", - "fscholz", - "teoli" - ] - }, - "Web/HTTP/Methods": { + "Web/HTTP/Reference/Methods": { "modified": "2020-12-02T07:02:59.603Z", "contributors": [ "mfuji09", @@ -99769,7 +99454,7 @@ "teoli" ] }, - "Web/HTTP/Methods/CONNECT": { + "Web/HTTP/Reference/Methods/CONNECT": { "modified": "2020-10-15T21:51:51.581Z", "contributors": [ "mfuji09", @@ -99781,7 +99466,7 @@ "teoli" ] }, - "Web/HTTP/Methods/DELETE": { + "Web/HTTP/Reference/Methods/DELETE": { "modified": "2020-10-15T21:52:28.585Z", "contributors": [ "BenzaitenS", @@ -99793,7 +99478,7 @@ "teoli" ] }, - "Web/HTTP/Methods/GET": { + "Web/HTTP/Reference/Methods/GET": { "modified": "2020-11-30T01:29:03.782Z", "contributors": [ "hamishwillee", @@ -99805,7 +99490,7 @@ "teoli" ] }, - "Web/HTTP/Methods/HEAD": { + "Web/HTTP/Reference/Methods/HEAD": { "modified": "2020-10-15T21:47:54.910Z", "contributors": [ "Tigt", @@ -99816,7 +99501,7 @@ "teoli" ] }, - "Web/HTTP/Methods/OPTIONS": { + "Web/HTTP/Reference/Methods/OPTIONS": { "modified": "2020-10-15T21:49:53.805Z", "contributors": [ "Tigt", @@ -99831,7 +99516,7 @@ "teoli" ] }, - "Web/HTTP/Methods/PATCH": { + "Web/HTTP/Reference/Methods/PATCH": { "modified": "2020-10-04T20:14:37.851Z", "contributors": [ "hamishwillee", @@ -99846,7 +99531,7 @@ "fscholz" ] }, - "Web/HTTP/Methods/POST": { + "Web/HTTP/Reference/Methods/POST": { "modified": "2020-10-15T21:47:54.153Z", "contributors": [ "mfuji09", @@ -99868,7 +99553,7 @@ "PudparK" ] }, - "Web/HTTP/Methods/PUT": { + "Web/HTTP/Reference/Methods/PUT": { "modified": "2020-10-15T21:52:25.200Z", "contributors": [ "chrisdavidmills", @@ -99879,7 +99564,7 @@ "natashaward" ] }, - "Web/HTTP/Methods/TRACE": { + "Web/HTTP/Reference/Methods/TRACE": { "modified": "2020-10-27T06:20:32.902Z", "contributors": [ "gabryon", @@ -99889,151 +99574,7 @@ "chrisdavidmills" ] }, - "Web/HTTP/Network_Error_Logging": { - "modified": "2020-10-15T22:29:13.638Z", - "contributors": ["sideshowbarker", "lol768"] - }, - "Web/HTTP/Overview": { - "modified": "2020-09-15T11:32:01.897Z", - "contributors": [ - "WenJuWu", - "chrisdavidmills", - "CPMoviePHil", - "estelle", - "drivasperez", - "jswisher", - "segmentationfaulter", - "mfuji09", - "yackSpillsaps", - "ronny-macmaster", - "dcrouch79", - "Sheppy", - "fscholz", - "michaelbaxter", - "Sergio_Gonzalez_Collado", - "danielgormly", - "aaronArinder", - "SpikePy", - "arssonist", - "protopatterns", - "derick-montague", - "zhitaoh", - "Jeremie", - "david_ross", - "arosenberg01", - "tanya-marfel", - "teoli" - ] - }, - "Web/HTTP/Permissions_Policy": { - "modified": "2020-10-18T22:29:08.695Z", - "contributors": [ - "hamishwillee", - "mfuji09", - "Malvoz", - "old_morfey13", - "Sheppy", - "jpchase", - "leela52452", - "bershanskiy", - "ashleybooniphone", - "fscholz", - "jpmedley" - ] - }, - "Web/HTTP/Permissions_Policy/Using_Feature_Policy": { - "modified": "2020-10-01T23:00:16.945Z", - "contributors": [ - "hamishwillee", - "Malvoz", - "Sheppy", - "chrisdavidmills", - "clelland", - "jpchase", - "fscholz", - "mfuji09", - "jpmedley" - ] - }, - "Web/HTTP/Protocol_upgrade_mechanism": { - "modified": "2020-11-29T09:42:13.104Z", - "contributors": [ - "chrisdavidmills", - "Bilal", - "mfuji09", - "zambini", - "mnottingham", - "aymericbeaumet", - "himanshub16", - "noahbenham", - "Sheppy", - "TheT0dd", - "teoli" - ] - }, - "Web/HTTP/Proxy_servers_and_tunneling": { - "modified": "2020-10-13T12:48:38.648Z", - "contributors": ["jwerre", "mfuji09", "r-thomps", "teoli", "fscholz"] - }, - "Web/HTTP/Proxy_servers_and_tunneling/Proxy_Auto-Configuration_PAC_file": { - "modified": "2020-10-12T08:18:46.998Z", - "contributors": [ - "SphinxKnight", - "jibonmobileq", - "mfuji09", - "lewisje", - "Artoria2e5", - "RainSlide", - "Gizeta", - "erosman", - "fscholz", - "orisano", - "Sheppy", - "GeneralFailer", - "teoli", - "GabrielCorona", - "galejwnaylor", - "xeonchen", - "rolfedh", - "duncanmcdonald" - ] - }, - "Web/HTTP/Range_requests": { - "modified": "2019-11-13T09:33:18.325Z", - "contributors": [ - "tkutz", - "Alexis Wilke1", - "thierry.henrio", - "momijimimiga", - "BaderSur", - "fscholz" - ] - }, - "Web/HTTP/Redirections": { - "modified": "2020-11-23T11:01:59.977Z", - "contributors": [ - "sideshowbarker", - "alessiogasparini02", - "mfuji09", - "avi-levy", - "Tigt", - "ptletski", - "fmonjalet", - "cypressf", - "zonidjan", - "dnafication", - "rileym7", - "VladPavel15", - "HTMLValidator", - "WayneCui", - "lmsteffan", - "nackman", - "oxfist", - "fscholz", - "teoli" - ] - }, - "Web/HTTP/Resources_and_specifications": { + "Web/HTTP/Reference/Resources_and_specifications": { "modified": "2019-07-29T05:42:08.432Z", "contributors": [ "dilyanpalauzov", @@ -100043,22 +99584,7 @@ "teoli" ] }, - "Web/HTTP/Session": { - "modified": "2019-07-31T02:53:01.366Z", - "contributors": [ - "vriojtg", - "witaly-iwanow", - "SphinxKnight", - "AranGarcia", - "stephaniehobson", - "rickwest", - "david_ross", - "DarrenLester", - "fscholz", - "groovecoder" - ] - }, - "Web/HTTP/Status": { + "Web/HTTP/Reference/Status": { "modified": "2020-11-08T17:39:17.746Z", "contributors": [ "MostafaNawara", @@ -100103,11 +99629,11 @@ "fusionchess" ] }, - "Web/HTTP/Status/100": { + "Web/HTTP/Reference/Status/100": { "modified": "2020-10-15T21:47:41.718Z", "contributors": ["fscholz"] }, - "Web/HTTP/Status/101": { + "Web/HTTP/Reference/Status/101": { "modified": "2020-11-16T02:53:43.840Z", "contributors": [ "lobsterhands", @@ -100118,11 +99644,11 @@ "fscholz" ] }, - "Web/HTTP/Status/103": { + "Web/HTTP/Reference/Status/103": { "modified": "2020-10-15T22:18:25.418Z", "contributors": ["ExE-Boss"] }, - "Web/HTTP/Status/200": { + "Web/HTTP/Reference/Status/200": { "modified": "2020-11-28T19:48:51.027Z", "contributors": [ "Denvery", @@ -100132,7 +99658,7 @@ "teoli" ] }, - "Web/HTTP/Status/201": { + "Web/HTTP/Reference/Status/201": { "modified": "2020-10-15T21:48:46.445Z", "contributors": [ "mfuji09", @@ -100143,7 +99669,7 @@ "teoli" ] }, - "Web/HTTP/Status/202": { + "Web/HTTP/Reference/Status/202": { "modified": "2020-05-07T06:00:53.876Z", "contributors": [ "chrisdavidmills", @@ -100152,19 +99678,19 @@ "fscholz" ] }, - "Web/HTTP/Status/203": { + "Web/HTTP/Reference/Status/203": { "modified": "2020-01-04T09:32:15.829Z", "contributors": ["mfuji09", "anirudh24seven", "teoli", "fscholz"] }, - "Web/HTTP/Status/204": { + "Web/HTTP/Reference/Status/204": { "modified": "2020-10-15T21:48:42.476Z", "contributors": ["alex.chao", "jugglinmike", "fscholz", "teoli"] }, - "Web/HTTP/Status/205": { + "Web/HTTP/Reference/Status/205": { "modified": "2019-03-23T22:17:00.001Z", "contributors": ["jugglinmike", "fscholz"] }, - "Web/HTTP/Status/206": { + "Web/HTTP/Reference/Status/206": { "modified": "2020-10-15T21:48:44.415Z", "contributors": [ "mfuji09", @@ -100174,11 +99700,11 @@ "teoli" ] }, - "Web/HTTP/Status/300": { + "Web/HTTP/Reference/Status/300": { "modified": "2019-11-06T22:59:47.998Z", "contributors": ["dd-pardal", "teoli", "fscholz"] }, - "Web/HTTP/Status/301": { + "Web/HTTP/Reference/Status/301": { "modified": "2020-10-15T21:48:45.918Z", "contributors": [ "mfuji09", @@ -100192,7 +99718,7 @@ "teoli" ] }, - "Web/HTTP/Status/302": { + "Web/HTTP/Reference/Status/302": { "modified": "2020-10-15T21:48:44.544Z", "contributors": [ "mfuji09", @@ -100206,7 +99732,7 @@ "teoli" ] }, - "Web/HTTP/Status/303": { + "Web/HTTP/Reference/Status/303": { "modified": "2020-10-15T21:48:47.834Z", "contributors": [ "SphinxKnight", @@ -100222,7 +99748,7 @@ "teoli" ] }, - "Web/HTTP/Status/304": { + "Web/HTTP/Reference/Status/304": { "modified": "2020-10-15T21:48:44.787Z", "contributors": [ "bef0re", @@ -100233,7 +99759,7 @@ "teoli" ] }, - "Web/HTTP/Status/307": { + "Web/HTTP/Reference/Status/307": { "modified": "2020-10-15T21:48:48.152Z", "contributors": [ "mfuji09", @@ -100248,7 +99774,7 @@ "teoli" ] }, - "Web/HTTP/Status/308": { + "Web/HTTP/Reference/Status/308": { "modified": "2020-10-15T21:48:48.335Z", "contributors": [ "ExE-Boss", @@ -100258,7 +99784,7 @@ "teoli" ] }, - "Web/HTTP/Status/400": { + "Web/HTTP/Reference/Status/400": { "modified": "2020-10-26T00:58:04.147Z", "contributors": [ "sideshowbarker", @@ -100277,15 +99803,15 @@ "fscholz" ] }, - "Web/HTTP/Status/401": { + "Web/HTTP/Reference/Status/401": { "modified": "2020-10-15T21:52:18.174Z", "contributors": ["fscholz"] }, - "Web/HTTP/Status/402": { + "Web/HTTP/Reference/Status/402": { "modified": "2020-10-15T22:19:20.329Z", "contributors": ["mfuji09", "SphinxKnight", "xhesh", "bershanskiy"] }, - "Web/HTTP/Status/403": { + "Web/HTTP/Reference/Status/403": { "modified": "2020-10-15T21:52:16.126Z", "contributors": [ "mfuji09", @@ -100296,7 +99822,7 @@ "teoli" ] }, - "Web/HTTP/Status/404": { + "Web/HTTP/Reference/Status/404": { "modified": "2020-10-15T21:47:40.827Z", "contributors": [ "mfuji09", @@ -100310,7 +99836,7 @@ "Jeremie" ] }, - "Web/HTTP/Status/405": { + "Web/HTTP/Reference/Status/405": { "modified": "2020-09-18T20:31:11.898Z", "contributors": [ "sideshowbarker", @@ -100326,7 +99852,7 @@ "fscholz" ] }, - "Web/HTTP/Status/406": { + "Web/HTTP/Reference/Status/406": { "modified": "2020-10-15T21:48:49.513Z", "contributors": [ "jchook", @@ -100337,11 +99863,11 @@ "teoli" ] }, - "Web/HTTP/Status/407": { + "Web/HTTP/Reference/Status/407": { "modified": "2020-10-15T21:52:17.415Z", "contributors": ["fscholz", "teoli"] }, - "Web/HTTP/Status/408": { + "Web/HTTP/Reference/Status/408": { "modified": "2019-03-23T22:17:44.804Z", "contributors": [ "RayannTedds", @@ -100351,11 +99877,11 @@ "fscholz" ] }, - "Web/HTTP/Status/409": { + "Web/HTTP/Reference/Status/409": { "modified": "2020-12-09T19:14:44.486Z", "contributors": ["bershanskiy", "ocket8888", "fscholz"] }, - "Web/HTTP/Status/410": { + "Web/HTTP/Reference/Status/410": { "modified": "2020-10-15T21:48:03.106Z", "contributors": [ "bobo.debila", @@ -100367,11 +99893,11 @@ "Jeremie" ] }, - "Web/HTTP/Status/411": { + "Web/HTTP/Reference/Status/411": { "modified": "2019-06-30T16:42:16.182Z", "contributors": ["RayannTedds", "haroldfredshort", "fscholz"] }, - "Web/HTTP/Status/412": { + "Web/HTTP/Reference/Status/412": { "modified": "2020-10-15T21:48:41.490Z", "contributors": [ "mfuji09", @@ -100384,19 +99910,19 @@ "teoli" ] }, - "Web/HTTP/Status/413": { + "Web/HTTP/Reference/Status/413": { "modified": "2020-08-21T12:58:45.582Z", "contributors": ["mfuji09", "sideshowbarker", "scompo", "fscholz"] }, - "Web/HTTP/Status/414": { + "Web/HTTP/Reference/Status/414": { "modified": "2020-05-24T03:52:54.422Z", "contributors": ["emoryeddie1", "Tigt", "fscholz"] }, - "Web/HTTP/Status/415": { + "Web/HTTP/Reference/Status/415": { "modified": "2019-03-23T22:16:51.619Z", "contributors": ["fscholz"] }, - "Web/HTTP/Status/416": { + "Web/HTTP/Reference/Status/416": { "modified": "2020-10-15T21:51:41.359Z", "contributors": [ "mfuji09", @@ -100409,11 +99935,11 @@ "teoli" ] }, - "Web/HTTP/Status/417": { + "Web/HTTP/Reference/Status/417": { "modified": "2019-03-23T22:16:56.284Z", "contributors": ["fscholz"] }, - "Web/HTTP/Status/418": { + "Web/HTTP/Reference/Status/418": { "modified": "2020-10-24T09:31:06.225Z", "contributors": [ "Ravenclaw-OIer", @@ -100429,23 +99955,23 @@ "iigmir" ] }, - "Web/HTTP/Status/422": { + "Web/HTTP/Reference/Status/422": { "modified": "2019-03-18T21:35:42.377Z", "contributors": ["mfuji09", "chrisdavidmills", "dylanegan"] }, - "Web/HTTP/Status/425": { + "Web/HTTP/Reference/Status/425": { "modified": "2020-10-15T22:08:44.754Z", "contributors": ["chrisdavidmills", "mfuji09"] }, - "Web/HTTP/Status/426": { + "Web/HTTP/Reference/Status/426": { "modified": "2019-03-23T22:16:51.238Z", "contributors": ["mfuji09", "haizaar", "teoli", "fscholz"] }, - "Web/HTTP/Status/428": { + "Web/HTTP/Reference/Status/428": { "modified": "2019-03-23T22:17:36.692Z", "contributors": ["fscholz"] }, - "Web/HTTP/Status/429": { + "Web/HTTP/Reference/Status/429": { "modified": "2020-08-21T13:13:46.663Z", "contributors": [ "mfuji09", @@ -100456,11 +99982,11 @@ "fscholz" ] }, - "Web/HTTP/Status/431": { + "Web/HTTP/Reference/Status/431": { "modified": "2019-09-01T02:24:58.716Z", "contributors": ["mfuji09", "Tigt", "dregin", "teoli", "fscholz"] }, - "Web/HTTP/Status/451": { + "Web/HTTP/Reference/Status/451": { "modified": "2020-10-15T21:48:04.725Z", "contributors": [ "mfuji09", @@ -100474,7 +100000,7 @@ "Jeremie" ] }, - "Web/HTTP/Status/500": { + "Web/HTTP/Reference/Status/500": { "modified": "2020-10-15T21:48:13.175Z", "contributors": [ "mfuji09", @@ -100488,7 +100014,7 @@ "AlexeyVasilievE" ] }, - "Web/HTTP/Status/501": { + "Web/HTTP/Reference/Status/501": { "modified": "2020-10-15T21:48:08.086Z", "contributors": [ "mfuji09", @@ -100500,7 +100026,7 @@ "Jeremie" ] }, - "Web/HTTP/Status/502": { + "Web/HTTP/Reference/Status/502": { "modified": "2020-10-15T21:48:05.520Z", "contributors": [ "sideshowbarker", @@ -100519,7 +100045,7 @@ "fscholz" ] }, - "Web/HTTP/Status/503": { + "Web/HTTP/Reference/Status/503": { "modified": "2020-10-26T14:59:27.523Z", "contributors": [ "sideshowbarker", @@ -100535,7 +100061,7 @@ "fscholz" ] }, - "Web/HTTP/Status/504": { + "Web/HTTP/Reference/Status/504": { "modified": "2020-10-15T21:48:15.981Z", "contributors": [ "sideshowbarker", @@ -100554,27 +100080,27 @@ "fscholz" ] }, - "Web/HTTP/Status/505": { + "Web/HTTP/Reference/Status/505": { "modified": "2019-03-23T22:17:54.032Z", "contributors": ["RayannTedds", "haroldfredshort", "fscholz"] }, - "Web/HTTP/Status/506": { + "Web/HTTP/Reference/Status/506": { "modified": "2020-08-21T12:48:18.084Z", "contributors": ["mfuji09", "wbamberg"] }, - "Web/HTTP/Status/507": { + "Web/HTTP/Reference/Status/507": { "modified": "2020-08-21T12:52:24.033Z", "contributors": ["mfuji09", "wbamberg"] }, - "Web/HTTP/Status/508": { + "Web/HTTP/Reference/Status/508": { "modified": "2019-09-16T14:03:58.839Z", "contributors": ["mfuji09", "wbamberg"] }, - "Web/HTTP/Status/510": { + "Web/HTTP/Reference/Status/510": { "modified": "2019-11-27T21:02:48.168Z", "contributors": ["wbamberg"] }, - "Web/HTTP/Status/511": { + "Web/HTTP/Reference/Status/511": { "modified": "2019-03-23T22:17:37.220Z", "contributors": ["fscholz"] }, @@ -100886,7 +100412,75 @@ "stav" ] }, - "Web/JavaScript/Closures": { + "Web/JavaScript/Guide": { + "modified": "2020-11-18T15:14:01.581Z", + "contributors": [ + "chrisdavidmills", + "SphinxKnight", + "ioannis221", + "jinbeomhong", + "FlyingCatZ", + "DannGutierres", + "dontdomilk", + "Cthutq1", + "gauravgoyal1911", + "jswisher", + "jppcel", + "fscholz", + "hardcodeprogrammer", + "x2357", + "pasalog", + "teoli", + "ensars53", + "slippyten", + "LoTD", + "Minat", + "Penny", + "jensen", + "morello", + "jscape", + "shneeple", + "KelvinS", + "Sheppy", + "Nanaya_Kuro", + "sebkilimo", + "nagendra08cs", + "natebunnyfield", + "Seb_dur", + "ethertank", + "iwo", + "radh", + "lmorchard", + "user01", + "happysadman", + "cruciatus", + "Yuichirou", + "dazzledesign", + "misha6603", + "Silviubogan", + "Cnmahj", + "Potappo", + "Lenatis", + "Simon", + "Mgjbot", + "Wafe", + "Nickolay", + "Spooty", + "Momoass", + "Major Small", + "electrolysis", + "Takenbot", + "Dria", + "Bkimman", + "Quarkcool", + "Cosinus", + "JesseW", + "Maian", + "Callek", + "JdeValk" + ] + }, + "Web/JavaScript/Guide/Closures": { "modified": "2020-12-11T05:04:54.583Z", "contributors": [ "bershanskiy", @@ -101013,265 +100607,6 @@ "Simon" ] }, - "Web/JavaScript/Data_structures": { - "modified": "2020-10-27T14:40:24.836Z", - "contributors": [ - "redrambles", - "chrisdavidmills", - "prashantydv25", - "wentout", - "Sadu_Bala_Krishna", - "Zearin_Galaurum", - "sideshowbarker", - "howardbdev", - "backbencher.dev", - "antonk52", - "titouandk", - "js100cc", - "mhjacobson", - "cogpark", - "wbamberg", - "fscholz", - "dcompcoder", - "Baka9k", - "metarmask", - "sachalifs", - "alattalatta", - "egigoka", - "iulia", - "OliverJAsh2", - "SphinxKnight", - "Uniqcoda", - "ofedoruk", - "aetonsi", - "fkling42", - "lap00zza", - "plug-n-play", - "AlfiMDN", - "achun", - "Sajag", - "kdex", - "flaviofj", - "chafic", - "utkarshbhatt12", - "stephaniehobson", - "sonirajesh", - "Pointy", - "noorgrewal", - "hxyoo1990", - "safinaskar", - "PyroLagus", - "nmve", - "mikkelrd", - "natterca", - "sometimesalready", - "itamark", - "jontejada", - "witart", - "Nickolay", - "Ende93", - "brianchaan", - "Sheppy", - "darrenmeehan", - "cardo1983", - "spiegelp", - "xfq", - "7anshuai", - "Delapouite", - "Jeremie", - "santiagolizardo", - "teoli", - "geniusSrj", - "Monmohan", - "noahcollins", - "techlivezheng", - "kamathln", - "gelenbaas@gmail.com", - "yongkek@gmail.com", - "saneyuki_s", - "dbruant", - "ellenfieldn", - "jswisher" - ] - }, - "Web/JavaScript/Enumerability_and_ownership_of_properties": { - "modified": "2020-03-12T19:38:04.705Z", - "contributors": [ - "fscholz", - "Nozomi3", - "NoInkling", - "Jannaee", - "robinpokorny", - "Ende93", - "nmve", - "whinc", - "amZotti", - "leobalter", - "tjcrowder", - "stiliyan", - "manish.jethani", - "Shhac", - "Brettz9" - ] - }, - "Web/JavaScript/Equality_comparisons_and_sameness": { - "modified": "2020-08-04T07:52:38.323Z", - "contributors": [ - "moshfeu", - "fscholz", - "SphinxKnight", - "Kaleem", - "Konrud", - "mfuji09", - "jahzielv", - "gregprice", - "samim", - "blin4444", - "wisgh", - "fxa", - "LayZeeDK", - "maxvu", - "koninos", - "fcheslack", - "Dirwu", - "focusaurus", - "nmve", - "AnthonySendra", - "whoacowboy", - "oksana-khristenko", - "Seairth", - "stevemao", - "Sevenspade", - "bergus", - "FrankHassanabad", - "Jeremie", - "mikeonthemoon", - "Sheppy", - "Waldo" - ] - }, - "Web/JavaScript/Event_loop": { - "modified": "2020-03-12T19:37:56.273Z", - "contributors": [ - "fscholz", - "BoQsc", - "vegerot", - "wbamberg", - "PierBover", - "Zearin_Galaurum", - "Sheppy", - "divyanshu013", - "SphinxKnight", - "AnkitaSood", - "olegolegoleg", - "eyalChistik", - "metasean", - "MadEmperorYuri", - "harminho", - "Peiren", - "pirtleshell", - "antunmagdic", - "adrianosmond", - "doubleOrt", - "utkarshbhatt12", - "Jun711", - "aminoche", - "stephaniehobson", - "sautumn", - "sturmer", - "coolarun", - "perryjiang", - "broAhmed", - "roryokane", - "nmve", - "Martin-Ting", - "onurtemizkan", - "keshvari", - "jxjj", - "mprogers", - "nikjohn", - "raeesiqbal", - "masthandev", - "amilajack", - "inglor", - "hanu412", - "jswisher", - "PortableStick", - "suhajdab", - "kscarfone", - "chakkakuru", - "EddieFloresLive", - "dbruant" - ] - }, - "Web/JavaScript/Guide": { - "modified": "2020-11-18T15:14:01.581Z", - "contributors": [ - "chrisdavidmills", - "SphinxKnight", - "ioannis221", - "jinbeomhong", - "FlyingCatZ", - "DannGutierres", - "dontdomilk", - "Cthutq1", - "gauravgoyal1911", - "jswisher", - "jppcel", - "fscholz", - "hardcodeprogrammer", - "x2357", - "pasalog", - "teoli", - "ensars53", - "slippyten", - "LoTD", - "Minat", - "Penny", - "jensen", - "morello", - "jscape", - "shneeple", - "KelvinS", - "Sheppy", - "Nanaya_Kuro", - "sebkilimo", - "nagendra08cs", - "natebunnyfield", - "Seb_dur", - "ethertank", - "iwo", - "radh", - "lmorchard", - "user01", - "happysadman", - "cruciatus", - "Yuichirou", - "dazzledesign", - "misha6603", - "Silviubogan", - "Cnmahj", - "Potappo", - "Lenatis", - "Simon", - "Mgjbot", - "Wafe", - "Nickolay", - "Spooty", - "Momoass", - "Major Small", - "electrolysis", - "Takenbot", - "Dria", - "Bkimman", - "Quarkcool", - "Cosinus", - "JesseW", - "Maian", - "Callek", - "JdeValk" - ] - }, "Web/JavaScript/Guide/Control_flow_and_error_handling": { "modified": "2020-06-02T11:28:45.080Z", "contributors": [ @@ -101336,6 +100671,143 @@ "JesseW" ] }, + "Web/JavaScript/Guide/Data_structures": { + "modified": "2020-10-27T14:40:24.836Z", + "contributors": [ + "redrambles", + "chrisdavidmills", + "prashantydv25", + "wentout", + "Sadu_Bala_Krishna", + "Zearin_Galaurum", + "sideshowbarker", + "howardbdev", + "backbencher.dev", + "antonk52", + "titouandk", + "js100cc", + "mhjacobson", + "cogpark", + "wbamberg", + "fscholz", + "dcompcoder", + "Baka9k", + "metarmask", + "sachalifs", + "alattalatta", + "egigoka", + "iulia", + "OliverJAsh2", + "SphinxKnight", + "Uniqcoda", + "ofedoruk", + "aetonsi", + "fkling42", + "lap00zza", + "plug-n-play", + "AlfiMDN", + "achun", + "Sajag", + "kdex", + "flaviofj", + "chafic", + "utkarshbhatt12", + "stephaniehobson", + "sonirajesh", + "Pointy", + "noorgrewal", + "hxyoo1990", + "safinaskar", + "PyroLagus", + "nmve", + "mikkelrd", + "natterca", + "sometimesalready", + "itamark", + "jontejada", + "witart", + "Nickolay", + "Ende93", + "brianchaan", + "Sheppy", + "darrenmeehan", + "cardo1983", + "spiegelp", + "xfq", + "7anshuai", + "Delapouite", + "Jeremie", + "santiagolizardo", + "teoli", + "geniusSrj", + "Monmohan", + "noahcollins", + "techlivezheng", + "kamathln", + "gelenbaas@gmail.com", + "yongkek@gmail.com", + "saneyuki_s", + "dbruant", + "ellenfieldn", + "jswisher" + ] + }, + "Web/JavaScript/Guide/Enumerability_and_ownership_of_properties": { + "modified": "2020-03-12T19:38:04.705Z", + "contributors": [ + "fscholz", + "Nozomi3", + "NoInkling", + "Jannaee", + "robinpokorny", + "Ende93", + "nmve", + "whinc", + "amZotti", + "leobalter", + "tjcrowder", + "stiliyan", + "manish.jethani", + "Shhac", + "Brettz9" + ] + }, + "Web/JavaScript/Guide/Equality_comparisons_and_sameness": { + "modified": "2020-08-04T07:52:38.323Z", + "contributors": [ + "moshfeu", + "fscholz", + "SphinxKnight", + "Kaleem", + "Konrud", + "mfuji09", + "jahzielv", + "gregprice", + "samim", + "blin4444", + "wisgh", + "fxa", + "LayZeeDK", + "maxvu", + "koninos", + "fcheslack", + "Dirwu", + "focusaurus", + "nmve", + "AnthonySendra", + "whoacowboy", + "oksana-khristenko", + "Seairth", + "stevemao", + "Sevenspade", + "bergus", + "FrankHassanabad", + "Jeremie", + "mikeonthemoon", + "Sheppy", + "Waldo" + ] + }, "Web/JavaScript/Guide/Expressions_and_operators": { "modified": "2020-11-19T11:36:18.318Z", "contributors": [ @@ -101714,6 +101186,107 @@ "kscarfone" ] }, + "Web/JavaScript/Guide/Inheritance_and_the_prototype_chain": { + "modified": "2020-10-19T22:27:25.681Z", + "contributors": [ + "krankj", + "PiersZhang", + "SphinxKnight", + "MinimalistYing", + "gredin", + "mikedotexe", + "AndrewPardoe", + "nitinB", + "debugabhi", + "ZhenWang-Jen", + "tchebb", + "Shaderpixel", + "DianochkaMyQueen", + "MoTTs", + "jackmeagher", + "levani", + "aniketkudale", + "alexccl", + "mohanrajoria", + "BunnyWong", + "aru", + "ilPikachu", + "chrisdavidmills", + "SebastienParis", + "tourniquet", + "Nisarg-Shah", + "jruota", + "khaled-hossain-code", + "Akiq2016", + "arseniew", + "sayedhabib", + "utkarshbhatt12", + "omeid", + "thwee-alchemist", + "stephaniehobson", + "kshirish", + "willshowell", + "fscholz", + "psibi", + "sumanvyj", + "mobiusnz", + "JonathanPool", + "mkutny", + "PyroLagus", + "nmve", + "pencilsmcfour", + "charleshypk", + "shogunsea", + "Ende93", + "kdex", + "MaureenKole", + "amZotti", + "leoo", + "404_username_notfound", + "Anand_N", + "jakubsadura", + "cciker", + "RileyTomasek", + "rocco", + "artificiala", + "Ephapox", + "not-an-aardvark", + "zanetu", + "mykongee", + "chmanie", + "teoli", + "billyeh", + "Swanidhi", + "BrianDiPalma", + "jpmedley", + "SimeonJM", + "ro-savage", + "xfq", + "dhimes", + "anirudh_venkatesh", + "Delapouite", + "jeteon", + "Jeremie", + "mistral01", + "Narasimman", + "kscarfone", + "Nick_Pershin", + "Sheppy", + "safjanowski", + "bigbossSNK", + "ziyunfei", + "enderandpeter", + "alex.w.y", + "berkerpeksag", + "dbruant", + "-TNO-", + "krofdrakula", + "romanco", + "vbfox", + "BYK", + "Johnjbarton" + ] + }, "Web/JavaScript/Guide/Introduction": { "modified": "2020-11-20T01:09:38.373Z", "contributors": [ @@ -101895,6 +101468,55 @@ "yadlapalli" ] }, + "Web/JavaScript/Guide/Memory_management": { + "modified": "2020-03-12T19:35:21.425Z", + "contributors": [ + "fscholz", + "SphinxKnight", + "stefkiourk", + "TomLavenziano", + "jlvallelonga", + "msilvavieira", + "mxschumacher", + "collinklippel", + "kp2017", + "utkarshbhatt12", + "stephaniehobson", + "ra4ul", + "chrisdavidmills", + "iharmanpannu", + "JasonRammoray", + "jasdevsidhu12", + "cloverharvest", + "PyroLagus", + "jswisher", + "md.unicorn", + "nmve", + "wolenskyatwork", + "lleaff", + "rudolfo", + "beytek", + "jontejada", + "mbjordan", + "ronyeh", + "mishra", + "macinnir", + "RogerPoon", + "xfq", + "bigperm", + "anirudh_venkatesh", + "Agamemnus", + "velvel53", + "hectorsan68", + "Nick_Pershin", + "Sheppy", + "RichardC", + "ethertank", + "maxatwork", + "iskitz", + "dbruant" + ] + }, "Web/JavaScript/Guide/Meta_programming": { "modified": "2020-03-12T19:40:57.053Z", "contributors": [ @@ -102377,189 +101999,6 @@ "JesseW" ] }, - "Web/JavaScript/Inheritance_and_the_prototype_chain": { - "modified": "2020-10-19T22:27:25.681Z", - "contributors": [ - "krankj", - "PiersZhang", - "SphinxKnight", - "MinimalistYing", - "gredin", - "mikedotexe", - "AndrewPardoe", - "nitinB", - "debugabhi", - "ZhenWang-Jen", - "tchebb", - "Shaderpixel", - "DianochkaMyQueen", - "MoTTs", - "jackmeagher", - "levani", - "aniketkudale", - "alexccl", - "mohanrajoria", - "BunnyWong", - "aru", - "ilPikachu", - "chrisdavidmills", - "SebastienParis", - "tourniquet", - "Nisarg-Shah", - "jruota", - "khaled-hossain-code", - "Akiq2016", - "arseniew", - "sayedhabib", - "utkarshbhatt12", - "omeid", - "thwee-alchemist", - "stephaniehobson", - "kshirish", - "willshowell", - "fscholz", - "psibi", - "sumanvyj", - "mobiusnz", - "JonathanPool", - "mkutny", - "PyroLagus", - "nmve", - "pencilsmcfour", - "charleshypk", - "shogunsea", - "Ende93", - "kdex", - "MaureenKole", - "amZotti", - "leoo", - "404_username_notfound", - "Anand_N", - "jakubsadura", - "cciker", - "RileyTomasek", - "rocco", - "artificiala", - "Ephapox", - "not-an-aardvark", - "zanetu", - "mykongee", - "chmanie", - "teoli", - "billyeh", - "Swanidhi", - "BrianDiPalma", - "jpmedley", - "SimeonJM", - "ro-savage", - "xfq", - "dhimes", - "anirudh_venkatesh", - "Delapouite", - "jeteon", - "Jeremie", - "mistral01", - "Narasimman", - "kscarfone", - "Nick_Pershin", - "Sheppy", - "safjanowski", - "bigbossSNK", - "ziyunfei", - "enderandpeter", - "alex.w.y", - "berkerpeksag", - "dbruant", - "-TNO-", - "krofdrakula", - "romanco", - "vbfox", - "BYK", - "Johnjbarton" - ] - }, - "Web/JavaScript/JavaScript_technologies_overview": { - "modified": "2020-03-13T20:42:53.018Z", - "contributors": [ - "wbamberg", - "fscholz", - "CyberdineSystems", - "alattalatta", - "sigoa", - "kdex", - "x2357", - "kentcdodds", - "cmasekar", - "lunix01", - "Andrew_Pfeiffer", - "dbruant", - "xfq", - "openjck", - "Jeremie", - "Nickolay", - "velvel53", - "ChaitanyaGSNR", - "Sheppy", - "Norbert", - "teoli", - "yongkek@gmail.com", - "phpguru", - "ethertank", - "terkjard", - "syssgx", - "brtk", - "Ms2ger" - ] - }, - "Web/JavaScript/Memory_management": { - "modified": "2020-03-12T19:35:21.425Z", - "contributors": [ - "fscholz", - "SphinxKnight", - "stefkiourk", - "TomLavenziano", - "jlvallelonga", - "msilvavieira", - "mxschumacher", - "collinklippel", - "kp2017", - "utkarshbhatt12", - "stephaniehobson", - "ra4ul", - "chrisdavidmills", - "iharmanpannu", - "JasonRammoray", - "jasdevsidhu12", - "cloverharvest", - "PyroLagus", - "jswisher", - "md.unicorn", - "nmve", - "wolenskyatwork", - "lleaff", - "rudolfo", - "beytek", - "jontejada", - "mbjordan", - "ronyeh", - "mishra", - "macinnir", - "RogerPoon", - "xfq", - "bigperm", - "anirudh_venkatesh", - "Agamemnus", - "velvel53", - "hectorsan68", - "Nick_Pershin", - "Sheppy", - "RichardC", - "ethertank", - "maxatwork", - "iskitz", - "dbruant" - ] - }, "Web/JavaScript/Reference": { "modified": "2020-11-18T15:06:49.831Z", "contributors": [ @@ -103277,6 +102716,60 @@ "nbp" ] }, + "Web/JavaScript/Reference/Execution_model": { + "modified": "2020-03-12T19:37:56.273Z", + "contributors": [ + "fscholz", + "BoQsc", + "vegerot", + "wbamberg", + "PierBover", + "Zearin_Galaurum", + "Sheppy", + "divyanshu013", + "SphinxKnight", + "AnkitaSood", + "olegolegoleg", + "eyalChistik", + "metasean", + "MadEmperorYuri", + "harminho", + "Peiren", + "pirtleshell", + "antunmagdic", + "adrianosmond", + "doubleOrt", + "utkarshbhatt12", + "Jun711", + "aminoche", + "stephaniehobson", + "sautumn", + "sturmer", + "coolarun", + "perryjiang", + "broAhmed", + "roryokane", + "nmve", + "Martin-Ting", + "onurtemizkan", + "keshvari", + "jxjj", + "mprogers", + "nikjohn", + "raeesiqbal", + "masthandev", + "amilajack", + "inglor", + "hanu412", + "jswisher", + "PortableStick", + "suhajdab", + "kscarfone", + "chakkakuru", + "EddieFloresLive", + "dbruant" + ] + }, "Web/JavaScript/Reference/Functions": { "modified": "2020-10-15T21:04:49.009Z", "contributors": [ @@ -118233,6 +117726,39 @@ "Havvy" ] }, + "Web/JavaScript/Reference/JavaScript_technologies_overview": { + "modified": "2020-03-13T20:42:53.018Z", + "contributors": [ + "wbamberg", + "fscholz", + "CyberdineSystems", + "alattalatta", + "sigoa", + "kdex", + "x2357", + "kentcdodds", + "cmasekar", + "lunix01", + "Andrew_Pfeiffer", + "dbruant", + "xfq", + "openjck", + "Jeremie", + "Nickolay", + "velvel53", + "ChaitanyaGSNR", + "Sheppy", + "Norbert", + "teoli", + "yongkek@gmail.com", + "phpguru", + "ethertank", + "terkjard", + "syssgx", + "brtk", + "Ms2ger" + ] + }, "Web/JavaScript/Reference/Lexical_grammar": { "modified": "2020-10-15T21:28:00.571Z", "contributors": [ @@ -118446,7 +117972,7 @@ "modified": "2020-10-15T22:30:30.567Z", "contributors": ["fscholz", "wbamberg"] }, - "Web/JavaScript/Reference/Operators/Destructuring_assignment": { + "Web/JavaScript/Reference/Operators/Destructuring": { "modified": "2020-10-15T21:27:55.696Z", "contributors": [ "chrisdavidmills", @@ -121150,17 +120676,7 @@ "Sheppy" ] }, - "Web/MathML/Attribute": { - "modified": "2020-10-23T04:07:29.622Z", - "contributors": [ - "rachelandrew", - "fscholz", - "doersino", - "Draussenduscher", - "Sheppy" - ] - }, - "Web/MathML/Authoring": { + "Web/MathML/Guides/Authoring": { "modified": "2020-11-28T13:32:39.862Z", "contributors": [ "mfuji09", @@ -121184,7 +120700,51 @@ "christianlerch" ] }, - "Web/MathML/Element": { + "Web/MathML/Guides/Deriving_the_quadratic_formula": { + "modified": "2019-11-21T15:09:18.981Z", + "contributors": [ + "NewtSalamander", + "maryannetpdx", + "SphinxKnight", + "aseijo1", + "fred.wang", + "Darbicus", + "jonny_dedpahn", + "kscarfone", + "fscholz", + "Paul_Mollomo" + ] + }, + "Web/MathML/Guides/Proving_the_Pythagorean_theorem": { + "modified": "2019-04-19T17:22:32.633Z", + "contributors": [ + "asmeurer", + "grzegorz-zur", + "hbelay", + "maryannetpdx", + "Tao", + "nielsdg", + "SphinxKnight", + "mouse-karaganda", + "rohspeed", + "Sheppy", + "bfontecc", + "fscholz", + "Paul_Mollomo", + "ethertank" + ] + }, + "Web/MathML/Reference/Attribute": { + "modified": "2020-10-23T04:07:29.622Z", + "contributors": [ + "rachelandrew", + "fscholz", + "doersino", + "Draussenduscher", + "Sheppy" + ] + }, + "Web/MathML/Reference/Element": { "modified": "2020-08-24T00:21:20.916Z", "contributors": [ "fscholz", @@ -121195,11 +120755,11 @@ "teoli" ] }, - "Web/MathML/Element/maction": { + "Web/MathML/Reference/Element/maction": { "modified": "2020-12-08T06:14:58.548Z", "contributors": ["rachelandrew", "lucian95", "Yaffle", "fscholz", "Sheppy"] }, - "Web/MathML/Element/math": { + "Web/MathML/Reference/Element/math": { "modified": "2020-10-15T21:07:40.546Z", "contributors": [ "LucasLarson", @@ -121211,7 +120771,7 @@ "teoli" ] }, - "Web/MathML/Element/menclose": { + "Web/MathML/Reference/Element/menclose": { "modified": "2020-10-23T04:20:01.310Z", "contributors": [ "rachelandrew", @@ -121223,11 +120783,11 @@ "jswisher" ] }, - "Web/MathML/Element/merror": { + "Web/MathML/Reference/Element/merror": { "modified": "2020-12-08T06:39:00.520Z", "contributors": ["rachelandrew", "lucian95", "fscholz", "Sheppy"] }, - "Web/MathML/Element/mfenced": { + "Web/MathML/Reference/Element/mfenced": { "modified": "2020-10-15T21:07:18.297Z", "contributors": [ "fscholz", @@ -121239,7 +120799,7 @@ "jswisher" ] }, - "Web/MathML/Element/mfrac": { + "Web/MathML/Reference/Element/mfrac": { "modified": "2020-12-08T06:57:45.695Z", "contributors": [ "rachelandrew", @@ -121251,7 +120811,7 @@ "jswisher" ] }, - "Web/MathML/Element/mi": { + "Web/MathML/Reference/Element/mi": { "modified": "2020-12-08T06:58:12.774Z", "contributors": [ "rachelandrew", @@ -121262,7 +120822,7 @@ "jswisher" ] }, - "Web/MathML/Element/mmultiscripts": { + "Web/MathML/Reference/Element/mmultiscripts": { "modified": "2020-12-08T06:58:29.201Z", "contributors": [ "rachelandrew", @@ -121272,7 +120832,7 @@ "Sheppy" ] }, - "Web/MathML/Element/mn": { + "Web/MathML/Reference/Element/mn": { "modified": "2020-12-08T06:58:45.386Z", "contributors": [ "rachelandrew", @@ -121283,7 +120843,7 @@ "jswisher" ] }, - "Web/MathML/Element/mo": { + "Web/MathML/Reference/Element/mo": { "modified": "2020-12-08T06:58:55.815Z", "contributors": [ "rachelandrew", @@ -121294,7 +120854,7 @@ "jswisher" ] }, - "Web/MathML/Element/mover": { + "Web/MathML/Reference/Element/mover": { "modified": "2020-12-08T06:59:16.606Z", "contributors": [ "rachelandrew", @@ -121305,7 +120865,7 @@ "jswisher" ] }, - "Web/MathML/Element/mpadded": { + "Web/MathML/Reference/Element/mpadded": { "modified": "2020-12-08T06:59:27.492Z", "contributors": [ "rachelandrew", @@ -121316,7 +120876,7 @@ "jswisher" ] }, - "Web/MathML/Element/mphantom": { + "Web/MathML/Reference/Element/mphantom": { "modified": "2020-12-08T06:59:46.396Z", "contributors": [ "rachelandrew", @@ -121327,7 +120887,7 @@ "jswisher" ] }, - "Web/MathML/Element/mroot": { + "Web/MathML/Reference/Element/mroot": { "modified": "2020-12-08T06:59:59.854Z", "contributors": [ "rachelandrew", @@ -121338,7 +120898,7 @@ "jswisher" ] }, - "Web/MathML/Element/mrow": { + "Web/MathML/Reference/Element/mrow": { "modified": "2020-12-08T07:00:13.818Z", "contributors": [ "rachelandrew", @@ -121349,7 +120909,7 @@ "jswisher" ] }, - "Web/MathML/Element/ms": { + "Web/MathML/Reference/Element/ms": { "modified": "2020-12-08T07:00:30.106Z", "contributors": [ "rachelandrew", @@ -121359,11 +120919,11 @@ "jswisher" ] }, - "Web/MathML/Element/mspace": { + "Web/MathML/Reference/Element/mspace": { "modified": "2020-12-08T07:00:44.851Z", "contributors": ["rachelandrew", "fscholz", "Sheppy", "jswisher"] }, - "Web/MathML/Element/msqrt": { + "Web/MathML/Reference/Element/msqrt": { "modified": "2020-12-08T07:00:57.848Z", "contributors": [ "rachelandrew", @@ -121374,7 +120934,7 @@ "jswisher" ] }, - "Web/MathML/Element/mstyle": { + "Web/MathML/Reference/Element/mstyle": { "modified": "2020-12-08T07:01:10.016Z", "contributors": [ "rachelandrew", @@ -121386,7 +120946,7 @@ "Sheppy" ] }, - "Web/MathML/Element/msub": { + "Web/MathML/Reference/Element/msub": { "modified": "2020-12-08T07:01:23.829Z", "contributors": [ "rachelandrew", @@ -121397,7 +120957,7 @@ "jswisher" ] }, - "Web/MathML/Element/msubsup": { + "Web/MathML/Reference/Element/msubsup": { "modified": "2020-12-08T07:01:50.272Z", "contributors": [ "rachelandrew", @@ -121409,7 +120969,7 @@ "jswisher" ] }, - "Web/MathML/Element/msup": { + "Web/MathML/Reference/Element/msup": { "modified": "2020-12-08T07:02:01.978Z", "contributors": [ "rachelandrew", @@ -121420,7 +120980,7 @@ "jswisher" ] }, - "Web/MathML/Element/mtable": { + "Web/MathML/Reference/Element/mtable": { "modified": "2020-12-08T07:04:03.214Z", "contributors": [ "rachelandrew", @@ -121431,7 +120991,7 @@ "Sheppy" ] }, - "Web/MathML/Element/mtd": { + "Web/MathML/Reference/Element/mtd": { "modified": "2020-12-08T07:04:36.899Z", "contributors": [ "rachelandrew", @@ -121442,7 +121002,7 @@ "Sheppy" ] }, - "Web/MathML/Element/mtext": { + "Web/MathML/Reference/Element/mtext": { "modified": "2020-12-08T07:05:09.077Z", "contributors": [ "rachelandrew", @@ -121453,7 +121013,7 @@ "jswisher" ] }, - "Web/MathML/Element/mtr": { + "Web/MathML/Reference/Element/mtr": { "modified": "2020-12-08T07:05:31.494Z", "contributors": [ "rachelandrew", @@ -121463,7 +121023,7 @@ "Sheppy" ] }, - "Web/MathML/Element/munder": { + "Web/MathML/Reference/Element/munder": { "modified": "2020-12-08T07:05:44.621Z", "contributors": [ "rachelandrew", @@ -121475,7 +121035,7 @@ "jswisher" ] }, - "Web/MathML/Element/munderover": { + "Web/MathML/Reference/Element/munderover": { "modified": "2020-12-08T07:05:56.617Z", "contributors": [ "rachelandrew", @@ -121488,57 +121048,11 @@ "jswisher" ] }, - "Web/MathML/Element/semantics": { + "Web/MathML/Reference/Element/semantics": { "modified": "2020-12-08T07:06:26.029Z", "contributors": ["rachelandrew", "fscholz", "Sheppy", "jswisher"] }, - "Web/MathML/Examples": { - "modified": "2019-03-23T23:33:29.196Z", - "contributors": [ - "maryannetpdx", - "SphinxKnight", - "nielsdg", - "ethertank", - "ChaitanyaGSNR", - "Sheppy", - "fscholz" - ] - }, - "Web/MathML/Examples/Deriving_the_Quadratic_Formula": { - "modified": "2019-11-21T15:09:18.981Z", - "contributors": [ - "NewtSalamander", - "maryannetpdx", - "SphinxKnight", - "aseijo1", - "fred.wang", - "Darbicus", - "jonny_dedpahn", - "kscarfone", - "fscholz", - "Paul_Mollomo" - ] - }, - "Web/MathML/Examples/MathML_Pythagorean_Theorem": { - "modified": "2019-04-19T17:22:32.633Z", - "contributors": [ - "asmeurer", - "grzegorz-zur", - "hbelay", - "maryannetpdx", - "Tao", - "nielsdg", - "SphinxKnight", - "mouse-karaganda", - "rohspeed", - "Sheppy", - "bfontecc", - "fscholz", - "Paul_Mollomo", - "ethertank" - ] - }, - "Web/MathML/Values": { + "Web/MathML/Reference/Values": { "modified": "2019-10-25T11:46:38.660Z", "contributors": ["fscholz", "maryannetpdx", "Sheppy"] }, @@ -121673,28 +121187,6 @@ "modified": "2020-10-11T23:21:36.266Z", "contributors": ["Malvoz", "scunliffe", "MrAlexWeber", "Sheppy"] }, - "Web/Media/Guides/DASH_Adaptive_Streaming_for_HTML_5_Video": { - "modified": "2020-11-09T07:34:43.578Z", - "contributors": [ - "mfuji09", - "Sidewinder53", - "DeividasBakanas", - "formatkaka", - "chrysn", - "LeroyScandal", - "wbamberg", - "jswisher", - "wyrewolwerowany", - "anotherkabab", - "rogerxas", - "teoli", - "gmarty", - "Kinetik", - "kscarfone", - "sworkman", - "joshmoz" - ] - }, "Web/Media/Guides/Formats": { "modified": "2019-11-15T11:45:09.792Z", "contributors": ["Sheppy", "jswisher", "Havi Hoffman"] @@ -122314,7 +121806,7 @@ "Afri" ] }, - "Web/SVG/Applying_SVG_effects_to_HTML_content": { + "Web/SVG/Guides/Applying_SVG_effects_to_HTML_content": { "modified": "2019-09-30T02:31:08.961Z", "contributors": [ "kadfak", @@ -122335,7 +121827,148 @@ "brianblakely" ] }, - "Web/SVG/Attribute": { + "Web/SVG/Guides/Content_type": { + "modified": "2020-04-08T21:33:47.459Z", + "contributors": [ + "Zearin_Galaurum", + "Sheppy", + "Sebastianz", + "lcmando05", + "RafalNiewinski", + "kscarfone", + "Jeremie", + "ethertank" + ] + }, + "Web/SVG/Guides/Linking": { + "modified": "2019-03-23T23:48:55.443Z", + "contributors": ["ExE-Boss", "Jeremie", "Kohei", "Jonathan_Watt"] + }, + "Web/SVG/Guides/Namespaces_crash_course": { + "modified": "2019-11-27T04:18:41.153Z", + "contributors": [ + "RicardsVeveris", + "somascope", + "octopusinvitro", + "Tigt", + "zabbarob", + "trevorh", + "Jeremie", + "Sheppy", + "Dholbert", + "Taken", + "Jonathan_Watt", + "Nickolay", + "Nickjohnson", + "Takenbot", + "NickolayBot", + "Darobin" + ] + }, + "Web/SVG/Guides/Namespaces_crash_course/Example": { + "modified": "2019-03-23T23:41:20.286Z", + "contributors": [ + "ethertank", + "Jeremie", + "Nickolay", + "Mgjbot", + "Taken", + "Jonathan_Watt" + ] + }, + "Web/SVG/Guides/SVG_animation_with_SMIL": { + "modified": "2019-11-07T08:50:12.574Z", + "contributors": [ + "hoang4", + "a-mt", + "fscholz", + "myf", + "SphinxKnight", + "pipcet", + "teropa", + "Longsonr", + "sanderd17", + "jpmedley", + "dbruenig", + "shakyjake", + "Jeremie", + "Sheppy", + "Nilam", + "yyss", + "Brettz9", + "jswisher", + "sebmozilla" + ] + }, + "Web/SVG/Guides/SVG_as_an_image": { + "modified": "2019-03-24T00:12:58.786Z", + "contributors": [ + "fscholz", + "Yukulele.", + "david_ross", + "pudymody", + "arai", + "elatllat", + "Zcorpan", + "Sebastianz", + "Barbrousse", + "Jeremie", + "ethertank", + "mtmotoki@gmail.com", + "fusionchess", + "jswisher", + "Sephr", + "Dholbert" + ] + }, + "Web/SVG/Guides/SVG_filters": { + "modified": "2020-10-24T07:46:48.631Z", + "contributors": ["chrisdavidmills", "amized", "teoli", "curacao"] + }, + "Web/SVG/Guides/SVG_in_HTML": { + "modified": "2020-04-20T03:12:49.575Z", + "contributors": [ + "sideshowbarker", + "chrisdavidmills", + "stephaniehobson", + "Jeremie", + "vuldin", + "ethertank", + "Neformal.lviv", + "tomchen1989", + "Brettz9", + "Gfldex", + "Sheppy", + "Jonathan_Watt", + "Nickolay", + "Nickjohnson", + "Takenbot", + "NickolayBot", + "Chbok", + "Dria", + "Marcoos", + "Jeff Schiller", + "Roc" + ] + }, + "Web/SVG/Guides/Scripting": { + "modified": "2019-03-24T00:15:31.968Z", + "contributors": [ + "ZiroKyl", + "Sheppy", + "Gowan", + "Sole", + "Jeremie", + "bwm", + "Jonathan_Watt", + "Nobodyman", + "Ptak82", + "Taken", + "Dria", + "NickolayBot" + ] + }, + "Web/SVG/Reference/Attribute": { "modified": "2020-06-10T08:32:45.989Z", "contributors": [ "mfuji09", @@ -122361,11 +121994,11 @@ "sebmozilla" ] }, - "Web/SVG/Attribute/From": { + "Web/SVG/Reference/Attribute/From": { "modified": "2020-10-15T21:13:01.508Z", "contributors": ["Sebastianz", "SueSmith", "Jeremie", "sebmozilla"] }, - "Web/SVG/Attribute/To": { + "Web/SVG/Reference/Attribute/To": { "modified": "2019-07-04T18:01:27.376Z", "contributors": [ "Sebastianz", @@ -122375,19 +122008,15 @@ "sebmozilla" ] }, - "Web/SVG/Attribute/accent-height": { - "modified": "2020-10-15T21:08:31.444Z", - "contributors": ["Sebastianz", "SphinxKnight", "Jeremie", "lmorchard"] - }, - "Web/SVG/Attribute/accumulate": { + "Web/SVG/Reference/Attribute/accumulate": { "modified": "2019-04-20T11:26:46.650Z", "contributors": ["Sebastianz", "Jeremie"] }, - "Web/SVG/Attribute/additive": { + "Web/SVG/Reference/Attribute/additive": { "modified": "2019-04-20T16:52:45.053Z", "contributors": ["Sebastianz", "Jeremie"] }, - "Web/SVG/Attribute/alignment-baseline": { + "Web/SVG/Reference/Attribute/alignment-baseline": { "modified": "2020-10-16T10:40:25.367Z", "contributors": [ "mfuji09", @@ -122400,23 +122029,11 @@ "Jeremie" ] }, - "Web/SVG/Attribute/alphabetic": { - "modified": "2020-10-15T22:17:46.501Z", - "contributors": ["Sebastianz"] - }, - "Web/SVG/Attribute/amplitude": { + "Web/SVG/Reference/Attribute/amplitude": { "modified": "2019-04-20T17:09:45.401Z", "contributors": ["Sebastianz"] }, - "Web/SVG/Attribute/arabic-form": { - "modified": "2020-10-15T22:20:57.813Z", - "contributors": ["Sebastianz"] - }, - "Web/SVG/Attribute/ascent": { - "modified": "2020-10-15T21:08:32.115Z", - "contributors": ["Sebastianz", "Jeremie"] - }, - "Web/SVG/Attribute/attributeName": { + "Web/SVG/Reference/Attribute/attributeName": { "modified": "2019-05-12T18:11:03.779Z", "contributors": [ "Sebastianz", @@ -122426,19 +122043,19 @@ "sebmozilla" ] }, - "Web/SVG/Attribute/attributeType": { + "Web/SVG/Reference/Attribute/attributeType": { "modified": "2019-05-12T18:25:48.802Z", "contributors": ["Sebastianz", "Jeremie"] }, - "Web/SVG/Attribute/azimuth": { + "Web/SVG/Reference/Attribute/azimuth": { "modified": "2020-10-15T21:20:15.852Z", "contributors": ["Sebastianz", "Jeremie"] }, - "Web/SVG/Attribute/baseFrequency": { + "Web/SVG/Reference/Attribute/baseFrequency": { "modified": "2020-10-15T21:20:52.777Z", "contributors": ["Sebastianz", "Jeremie"] }, - "Web/SVG/Attribute/baseProfile": { + "Web/SVG/Reference/Attribute/baseProfile": { "modified": "2019-07-09T18:53:57.322Z", "contributors": [ "Sebastianz", @@ -122447,7 +122064,7 @@ "liyongleihf2006" ] }, - "Web/SVG/Attribute/baseline-shift": { + "Web/SVG/Reference/Attribute/baseline-shift": { "modified": "2020-10-15T21:18:44.156Z", "contributors": [ "chrisdavidmills", @@ -122458,11 +122075,7 @@ "Jeremie" ] }, - "Web/SVG/Attribute/bbox": { - "modified": "2020-10-15T22:17:46.809Z", - "contributors": ["Sebastianz"] - }, - "Web/SVG/Attribute/begin": { + "Web/SVG/Reference/Attribute/begin": { "modified": "2020-04-27T02:09:36.601Z", "contributors": [ "SphinxKnight", @@ -122474,23 +122087,19 @@ "Sheppy" ] }, - "Web/SVG/Attribute/bias": { + "Web/SVG/Reference/Attribute/bias": { "modified": "2020-10-15T21:21:07.958Z", "contributors": ["Sebastianz", "Jeremie"] }, - "Web/SVG/Attribute/by": { + "Web/SVG/Reference/Attribute/by": { "modified": "2020-10-15T22:20:57.471Z", "contributors": ["Sebastianz"] }, - "Web/SVG/Attribute/calcMode": { + "Web/SVG/Reference/Attribute/calcMode": { "modified": "2019-05-12T18:34:57.256Z", "contributors": ["Sebastianz", "Jeremie"] }, - "Web/SVG/Attribute/cap-height": { - "modified": "2020-10-15T22:18:48.442Z", - "contributors": ["Sebastianz"] - }, - "Web/SVG/Attribute/class": { + "Web/SVG/Reference/Attribute/class": { "modified": "2020-10-15T21:09:24.628Z", "contributors": [ "Sebastianz", @@ -122505,11 +122114,11 @@ "Sheppy" ] }, - "Web/SVG/Attribute/clip": { + "Web/SVG/Reference/Attribute/clip": { "modified": "2020-10-15T21:18:38.224Z", "contributors": ["Sebastianz", "Jeremie", "connorshea"] }, - "Web/SVG/Attribute/clip-path": { + "Web/SVG/Reference/Attribute/clip-path": { "modified": "2020-10-15T21:13:00.824Z", "contributors": [ "Sebastianz", @@ -122523,15 +122132,15 @@ "trevorh" ] }, - "Web/SVG/Attribute/clip-rule": { + "Web/SVG/Reference/Attribute/clip-rule": { "modified": "2020-10-15T21:09:09.390Z", "contributors": ["Sebastianz", "a-mt", "connorshea", "Longsonr", "Jeremie"] }, - "Web/SVG/Attribute/clipPathUnits": { + "Web/SVG/Reference/Attribute/clipPathUnits": { "modified": "2019-04-17T18:18:35.468Z", "contributors": ["Sebastianz", "Jeremie"] }, - "Web/SVG/Attribute/color": { + "Web/SVG/Reference/Attribute/color": { "modified": "2020-10-15T21:05:04.343Z", "contributors": [ "valtlai", @@ -122543,7 +122152,7 @@ "Jeremie" ] }, - "Web/SVG/Attribute/color-interpolation": { + "Web/SVG/Reference/Attribute/color-interpolation": { "modified": "2020-10-31T11:06:15.442Z", "contributors": [ "cdoublev", @@ -122558,7 +122167,7 @@ "ratcliffe_mike" ] }, - "Web/SVG/Attribute/color-interpolation-filters": { + "Web/SVG/Reference/Attribute/color-interpolation-filters": { "modified": "2020-10-31T11:06:43.497Z", "contributors": [ "cdoublev", @@ -122568,7 +122177,7 @@ "ratcliffe_mike" ] }, - "Web/SVG/Attribute/cursor": { + "Web/SVG/Reference/Attribute/cursor": { "modified": "2020-10-15T21:18:37.523Z", "contributors": [ "Sebastianz", @@ -122579,7 +122188,7 @@ "Jeremie" ] }, - "Web/SVG/Attribute/cx": { + "Web/SVG/Reference/Attribute/cx": { "modified": "2019-07-21T01:19:01.318Z", "contributors": [ "estelle", @@ -122591,11 +122200,11 @@ "rshetty" ] }, - "Web/SVG/Attribute/cy": { + "Web/SVG/Reference/Attribute/cy": { "modified": "2019-03-24T00:13:31.665Z", "contributors": ["Jeremie", "FredrikHemsen", "rshetty"] }, - "Web/SVG/Attribute/d": { + "Web/SVG/Reference/Attribute/d": { "modified": "2020-09-17T04:06:22.865Z", "contributors": [ "sdli", @@ -122638,23 +122247,19 @@ "Nilam" ] }, - "Web/SVG/Attribute/data-*": { + "Web/SVG/Reference/Attribute/data-*": { "modified": "2020-10-15T21:50:24.662Z", "contributors": ["fscholz", "Tigt", "hasalex", "Sheppy"] }, - "Web/SVG/Attribute/descent": { - "modified": "2020-10-15T22:18:45.731Z", - "contributors": ["Sebastianz"] - }, - "Web/SVG/Attribute/diffuseConstant": { + "Web/SVG/Reference/Attribute/diffuseConstant": { "modified": "2020-10-15T21:20:13.552Z", "contributors": ["Sebastianz", "Jeremie"] }, - "Web/SVG/Attribute/direction": { + "Web/SVG/Reference/Attribute/direction": { "modified": "2020-10-15T21:02:23.276Z", "contributors": ["Sebastianz", "connorshea", "Jeremie"] }, - "Web/SVG/Attribute/display": { + "Web/SVG/Reference/Attribute/display": { "modified": "2020-10-15T21:07:32.250Z", "contributors": [ "Sebastianz", @@ -122665,11 +122270,11 @@ "Sheppy" ] }, - "Web/SVG/Attribute/divisor": { + "Web/SVG/Reference/Attribute/divisor": { "modified": "2020-10-15T21:21:08.035Z", "contributors": ["Sebastianz", "Jeremie"] }, - "Web/SVG/Attribute/dominant-baseline": { + "Web/SVG/Reference/Attribute/dominant-baseline": { "modified": "2020-10-31T11:07:03.201Z", "contributors": [ "cdoublev", @@ -122685,11 +122290,11 @@ "ratcliffe_mike" ] }, - "Web/SVG/Attribute/dur": { + "Web/SVG/Reference/Attribute/dur": { "modified": "2020-10-15T21:13:03.944Z", "contributors": ["Sebastianz", "___", "Jeremie", "sebmozilla"] }, - "Web/SVG/Attribute/dx": { + "Web/SVG/Reference/Attribute/dx": { "modified": "2020-04-23T07:32:06.135Z", "contributors": [ "jamesgrubb", @@ -122699,7 +122304,7 @@ "kscarfone" ] }, - "Web/SVG/Attribute/dy": { + "Web/SVG/Reference/Attribute/dy": { "modified": "2019-03-18T20:40:26.589Z", "contributors": [ "jalbertbowden", @@ -122709,23 +122314,23 @@ "kscarfone" ] }, - "Web/SVG/Attribute/edgeMode": { + "Web/SVG/Reference/Attribute/edgeMode": { "modified": "2019-06-01T19:29:26.887Z", "contributors": ["Sebastianz", "kydrost", "Jeremie"] }, - "Web/SVG/Attribute/elevation": { + "Web/SVG/Reference/Attribute/elevation": { "modified": "2020-10-15T21:20:22.181Z", "contributors": ["Sebastianz", "Jeremie"] }, - "Web/SVG/Attribute/end": { + "Web/SVG/Reference/Attribute/end": { "modified": "2020-03-17T14:16:54.678Z", "contributors": ["mfuji09", "VictorJanin", "Sebastianz", "Jeremie"] }, - "Web/SVG/Attribute/exponent": { + "Web/SVG/Reference/Attribute/exponent": { "modified": "2019-05-13T18:45:24.121Z", "contributors": ["Sebastianz"] }, - "Web/SVG/Attribute/fill": { + "Web/SVG/Reference/Attribute/fill": { "modified": "2020-10-15T21:12:58.007Z", "contributors": [ "TrevorKarjanis", @@ -122741,7 +122346,7 @@ "Daniel Hug" ] }, - "Web/SVG/Attribute/fill-opacity": { + "Web/SVG/Reference/Attribute/fill-opacity": { "modified": "2020-10-15T21:09:40.644Z", "contributors": [ "cdoublev", @@ -122752,7 +122357,7 @@ "ratcliffe_mike" ] }, - "Web/SVG/Attribute/fill-rule": { + "Web/SVG/Reference/Attribute/fill-rule": { "modified": "2020-10-31T11:07:34.809Z", "contributors": [ "cdoublev", @@ -122767,7 +122372,7 @@ "ratcliffe_mike" ] }, - "Web/SVG/Attribute/filter": { + "Web/SVG/Reference/Attribute/filter": { "modified": "2020-10-15T21:19:05.985Z", "contributors": [ "MarleDK", @@ -122777,19 +122382,19 @@ "Jeremie" ] }, - "Web/SVG/Attribute/filterUnits": { + "Web/SVG/Reference/Attribute/filterUnits": { "modified": "2020-10-15T21:08:01.201Z", "contributors": ["Sebastianz", "Jeremie"] }, - "Web/SVG/Attribute/flood-color": { + "Web/SVG/Reference/Attribute/flood-color": { "modified": "2020-10-15T21:09:40.877Z", "contributors": ["Sebastianz", "connorshea", "Jeremie", "ratcliffe_mike"] }, - "Web/SVG/Attribute/flood-opacity": { + "Web/SVG/Reference/Attribute/flood-opacity": { "modified": "2020-10-15T21:09:47.401Z", "contributors": ["Sebastianz", "connorshea", "Jeremie", "ratcliffe_mike"] }, - "Web/SVG/Attribute/font-family": { + "Web/SVG/Reference/Attribute/font-family": { "modified": "2020-10-15T21:04:26.927Z", "contributors": [ "Sebastianz", @@ -122799,19 +122404,19 @@ "Jeremie" ] }, - "Web/SVG/Attribute/font-size": { + "Web/SVG/Reference/Attribute/font-size": { "modified": "2020-10-15T21:04:23.473Z", "contributors": ["Sebastianz", "connorshea", "thnidu", "dhaval", "Jeremie"] }, - "Web/SVG/Attribute/font-size-adjust": { + "Web/SVG/Reference/Attribute/font-size-adjust": { "modified": "2020-10-15T21:04:15.917Z", "contributors": ["Sebastianz", "connorshea", "Jeremie"] }, - "Web/SVG/Attribute/font-stretch": { + "Web/SVG/Reference/Attribute/font-stretch": { "modified": "2020-10-15T21:03:52.454Z", "contributors": ["Sebastianz", "connorshea", "Jeremie"] }, - "Web/SVG/Attribute/font-style": { + "Web/SVG/Reference/Attribute/font-style": { "modified": "2020-10-15T21:03:42.507Z", "contributors": [ "katherincorredor", @@ -122823,11 +122428,11 @@ "Jeremie" ] }, - "Web/SVG/Attribute/font-variant": { + "Web/SVG/Reference/Attribute/font-variant": { "modified": "2020-10-15T21:02:55.801Z", "contributors": ["Sebastianz", "connorshea", "Jeremie"] }, - "Web/SVG/Attribute/font-weight": { + "Web/SVG/Reference/Attribute/font-weight": { "modified": "2020-10-15T21:02:30.424Z", "contributors": [ "Sebastianz", @@ -122838,11 +122443,11 @@ "Jeremie" ] }, - "Web/SVG/Attribute/fr": { + "Web/SVG/Reference/Attribute/fr": { "modified": "2020-10-15T21:54:40.575Z", "contributors": ["Sebastianz", "chrisdavidmills"] }, - "Web/SVG/Attribute/fx": { + "Web/SVG/Reference/Attribute/fx": { "modified": "2020-10-15T21:32:47.074Z", "contributors": [ "Sebastianz", @@ -122852,43 +122457,27 @@ "Nagababu" ] }, - "Web/SVG/Attribute/fy": { + "Web/SVG/Reference/Attribute/fy": { "modified": "2020-10-15T21:33:03.760Z", "contributors": ["Sebastianz", "jhpratt", "kscarfone", "neotam"] }, - "Web/SVG/Attribute/g1": { - "modified": "2020-10-15T22:21:13.671Z", - "contributors": ["Sebastianz"] - }, - "Web/SVG/Attribute/g2": { - "modified": "2020-10-15T22:21:11.999Z", - "contributors": ["Sebastianz"] - }, - "Web/SVG/Attribute/glyph-name": { - "modified": "2020-10-15T22:20:57.826Z", - "contributors": ["Sebastianz"] - }, - "Web/SVG/Attribute/glyph-orientation-horizontal": { + "Web/SVG/Reference/Attribute/glyph-orientation-horizontal": { "modified": "2020-10-15T22:21:17.738Z", "contributors": ["Sebastianz"] }, - "Web/SVG/Attribute/glyph-orientation-vertical": { + "Web/SVG/Reference/Attribute/glyph-orientation-vertical": { "modified": "2020-10-15T22:21:17.154Z", "contributors": ["Sebastianz"] }, - "Web/SVG/Attribute/gradientTransform": { + "Web/SVG/Reference/Attribute/gradientTransform": { "modified": "2020-10-15T21:08:37.162Z", "contributors": ["Sebastianz", "chrisdavidmills", "cvsguimaraes", "Jeremie"] }, - "Web/SVG/Attribute/gradientUnits": { + "Web/SVG/Reference/Attribute/gradientUnits": { "modified": "2019-07-05T17:32:46.527Z", "contributors": ["Sebastianz", "Jeremie"] }, - "Web/SVG/Attribute/hanging": { - "modified": "2020-10-15T22:21:23.200Z", - "contributors": ["Sebastianz"] - }, - "Web/SVG/Attribute/height": { + "Web/SVG/Reference/Attribute/height": { "modified": "2020-06-04T09:13:03.919Z", "contributors": [ "brennanyoung", @@ -122900,35 +122489,19 @@ "Delapouite" ] }, - "Web/SVG/Attribute/horiz-adv-x": { - "modified": "2020-10-15T22:21:40.757Z", - "contributors": ["Sebastianz"] - }, - "Web/SVG/Attribute/horiz-origin-x": { - "modified": "2020-10-15T22:21:39.620Z", - "contributors": ["Sebastianz"] - }, - "Web/SVG/Attribute/horiz-origin-y": { - "modified": "2020-10-15T22:21:38.891Z", - "contributors": ["Sebastianz"] - }, - "Web/SVG/Attribute/href": { + "Web/SVG/Reference/Attribute/href": { "modified": "2020-10-15T21:49:17.049Z", "contributors": ["estelle", "Sebastianz", "fscholz", "Longsonr"] }, - "Web/SVG/Attribute/id": { + "Web/SVG/Reference/Attribute/id": { "modified": "2020-10-15T22:17:46.125Z", "contributors": ["LMLB", "Sebastianz"] }, - "Web/SVG/Attribute/ideographic": { - "modified": "2020-10-15T22:21:50.983Z", - "contributors": ["Sebastianz"] - }, - "Web/SVG/Attribute/image-rendering": { + "Web/SVG/Reference/Attribute/image-rendering": { "modified": "2020-10-15T21:02:23.777Z", "contributors": ["Sebastianz", "mfluehr", "connorshea", "Jeremie"] }, - "Web/SVG/Attribute/in": { + "Web/SVG/Reference/Attribute/in": { "modified": "2019-06-29T18:13:28.323Z", "contributors": [ "Sebastianz", @@ -122941,63 +122514,59 @@ "Jeremie" ] }, - "Web/SVG/Attribute/in2": { + "Web/SVG/Reference/Attribute/in2": { "modified": "2019-07-16T17:42:41.565Z", "contributors": ["jswisher", "loklaan", "Sebastianz", "Jeremie"] }, - "Web/SVG/Attribute/intercept": { + "Web/SVG/Reference/Attribute/intercept": { "modified": "2019-06-29T19:05:07.875Z", "contributors": ["Sebastianz"] }, - "Web/SVG/Attribute/k": { - "modified": "2020-10-15T22:21:17.478Z", - "contributors": ["Sebastianz"] - }, - "Web/SVG/Attribute/k1": { + "Web/SVG/Reference/Attribute/k1": { "modified": "2020-10-15T21:20:08.517Z", "contributors": ["Sebastianz", "Jeremie"] }, - "Web/SVG/Attribute/k2": { + "Web/SVG/Reference/Attribute/k2": { "modified": "2020-10-15T21:20:09.242Z", "contributors": ["Sebastianz", "Jeremie"] }, - "Web/SVG/Attribute/k3": { + "Web/SVG/Reference/Attribute/k3": { "modified": "2020-10-15T21:20:11.989Z", "contributors": ["Sebastianz", "Jeremie"] }, - "Web/SVG/Attribute/k4": { + "Web/SVG/Reference/Attribute/k4": { "modified": "2020-10-15T21:20:10.467Z", "contributors": ["Sebastianz", "Jeremie"] }, - "Web/SVG/Attribute/kernelMatrix": { + "Web/SVG/Reference/Attribute/kernelMatrix": { "modified": "2020-10-15T21:21:07.949Z", "contributors": ["Sebastianz", "Markus Prokott", "Jeremie"] }, - "Web/SVG/Attribute/kernelUnitLength": { + "Web/SVG/Reference/Attribute/kernelUnitLength": { "modified": "2019-06-30T15:02:41.242Z", "contributors": ["Sebastianz", "Jeremie"] }, - "Web/SVG/Attribute/keyPoints": { + "Web/SVG/Reference/Attribute/keyPoints": { "modified": "2020-10-15T22:20:10.730Z", "contributors": ["Sebastianz"] }, - "Web/SVG/Attribute/keySplines": { + "Web/SVG/Reference/Attribute/keySplines": { "modified": "2020-10-15T21:09:37.025Z", "contributors": ["Sebastianz", "MegaMatt3", "Jeremie"] }, - "Web/SVG/Attribute/keyTimes": { + "Web/SVG/Reference/Attribute/keyTimes": { "modified": "2020-10-15T21:09:33.238Z", "contributors": ["Sebastianz", "trevorh", "Jeremie"] }, - "Web/SVG/Attribute/lang": { + "Web/SVG/Reference/Attribute/lang": { "modified": "2020-10-15T22:21:58.579Z", "contributors": ["Sebastianz"] }, - "Web/SVG/Attribute/lengthAdjust": { + "Web/SVG/Reference/Attribute/lengthAdjust": { "modified": "2020-10-15T21:50:19.901Z", "contributors": ["Sebastianz", "H1Gdev", "krosylight", "david_ross", "y6nH"] }, - "Web/SVG/Attribute/letter-spacing": { + "Web/SVG/Reference/Attribute/letter-spacing": { "modified": "2020-10-15T21:06:40.471Z", "contributors": [ "rachelandrew", @@ -123011,15 +122580,15 @@ "Jeremie" ] }, - "Web/SVG/Attribute/lighting-color": { + "Web/SVG/Reference/Attribute/lighting-color": { "modified": "2020-10-15T21:09:36.789Z", "contributors": ["Sebastianz", "connorshea", "Jeremie", "ratcliffe_mike"] }, - "Web/SVG/Attribute/limitingConeAngle": { + "Web/SVG/Reference/Attribute/limitingConeAngle": { "modified": "2020-10-15T21:20:47.643Z", "contributors": ["Sebastianz", "Jeremie"] }, - "Web/SVG/Attribute/marker-end": { + "Web/SVG/Reference/Attribute/marker-end": { "modified": "2020-10-31T11:07:53.559Z", "contributors": [ "cdoublev", @@ -123031,7 +122600,7 @@ "ratcliffe_mike" ] }, - "Web/SVG/Attribute/marker-mid": { + "Web/SVG/Reference/Attribute/marker-mid": { "modified": "2020-10-31T11:08:11.033Z", "contributors": [ "cdoublev", @@ -123044,7 +122613,7 @@ "ratcliffe_mike" ] }, - "Web/SVG/Attribute/marker-start": { + "Web/SVG/Reference/Attribute/marker-start": { "modified": "2020-10-31T11:08:26.124Z", "contributors": [ "cdoublev", @@ -123054,19 +122623,19 @@ "ratcliffe_mike" ] }, - "Web/SVG/Attribute/markerHeight": { + "Web/SVG/Reference/Attribute/markerHeight": { "modified": "2020-10-15T21:08:37.116Z", "contributors": ["Sebastianz", "Jeremie"] }, - "Web/SVG/Attribute/markerUnits": { + "Web/SVG/Reference/Attribute/markerUnits": { "modified": "2020-10-15T21:08:36.409Z", "contributors": ["Sebastianz", "Jeremie", "Sheppy"] }, - "Web/SVG/Attribute/markerWidth": { + "Web/SVG/Reference/Attribute/markerWidth": { "modified": "2020-10-15T21:08:31.952Z", "contributors": ["vertika", "Sebastianz", "Jeremie"] }, - "Web/SVG/Attribute/mask": { + "Web/SVG/Reference/Attribute/mask": { "modified": "2020-10-15T21:13:02.699Z", "contributors": [ "y6nH", @@ -123077,11 +122646,11 @@ "ziyunfei" ] }, - "Web/SVG/Attribute/maskContentUnits": { + "Web/SVG/Reference/Attribute/maskContentUnits": { "modified": "2020-10-15T21:08:55.712Z", "contributors": ["Sebastianz", "Jeremie", "alecazam", "Sheppy"] }, - "Web/SVG/Attribute/maskUnits": { + "Web/SVG/Reference/Attribute/maskUnits": { "modified": "2020-10-15T21:08:54.844Z", "contributors": [ "Sebastianz", @@ -123091,39 +122660,31 @@ "Sheppy" ] }, - "Web/SVG/Attribute/mathematical": { - "modified": "2020-10-15T22:21:20.913Z", - "contributors": ["Sebastianz"] - }, - "Web/SVG/Attribute/max": { + "Web/SVG/Reference/Attribute/max": { "modified": "2020-10-15T21:13:04.122Z", "contributors": ["Sebastianz", "Jeremie"] }, - "Web/SVG/Attribute/media": { + "Web/SVG/Reference/Attribute/media": { "modified": "2020-10-15T22:21:38.403Z", "contributors": ["Sebastianz"] }, - "Web/SVG/Attribute/method": { + "Web/SVG/Reference/Attribute/method": { "modified": "2020-10-15T22:17:36.293Z", "contributors": ["Sebastianz"] }, - "Web/SVG/Attribute/min": { + "Web/SVG/Reference/Attribute/min": { "modified": "2020-10-15T21:13:01.379Z", "contributors": ["Sebastianz", "Jeremie"] }, - "Web/SVG/Attribute/mode": { + "Web/SVG/Reference/Attribute/mode": { "modified": "2020-10-15T21:20:11.850Z", "contributors": ["Sebastianz", "Jeremie", "jswisher"] }, - "Web/SVG/Attribute/name": { - "modified": "2019-07-28T17:38:43.814Z", - "contributors": ["Sebastianz"] - }, - "Web/SVG/Attribute/numOctaves": { + "Web/SVG/Reference/Attribute/numOctaves": { "modified": "2020-10-15T21:20:48.485Z", "contributors": ["Sebastianz", "Jeremie"] }, - "Web/SVG/Attribute/opacity": { + "Web/SVG/Reference/Attribute/opacity": { "modified": "2020-10-15T21:07:02.287Z", "contributors": [ "sonyarianto", @@ -123133,27 +122694,23 @@ "Jeremie" ] }, - "Web/SVG/Attribute/operator": { + "Web/SVG/Reference/Attribute/operator": { "modified": "2020-10-18T02:55:46.853Z", "contributors": ["timkay", "Sebastianz", "Jeremie"] }, - "Web/SVG/Attribute/order": { + "Web/SVG/Reference/Attribute/order": { "modified": "2020-10-15T21:21:11.764Z", "contributors": ["Sebastianz", "Jeremie"] }, - "Web/SVG/Attribute/orient": { + "Web/SVG/Reference/Attribute/orient": { "modified": "2020-10-15T22:23:29.247Z", "contributors": ["Sebastianz"] }, - "Web/SVG/Attribute/orientation": { - "modified": "2020-10-15T22:21:18.103Z", - "contributors": ["Sebastianz"] - }, - "Web/SVG/Attribute/origin": { + "Web/SVG/Reference/Attribute/origin": { "modified": "2019-09-07T19:58:52.648Z", "contributors": ["Sebastianz"] }, - "Web/SVG/Attribute/overflow": { + "Web/SVG/Reference/Attribute/overflow": { "modified": "2020-12-04T06:32:09.752Z", "contributors": [ "AJamesPhillips", @@ -123163,15 +122720,7 @@ "Jeremie" ] }, - "Web/SVG/Attribute/overline-position": { - "modified": "2019-03-23T23:07:04.588Z", - "contributors": ["kscarfone", "alicebeckett"] - }, - "Web/SVG/Attribute/overline-thickness": { - "modified": "2019-03-23T23:07:16.090Z", - "contributors": ["kscarfone", "alicebeckett"] - }, - "Web/SVG/Attribute/paint-order": { + "Web/SVG/Reference/Attribute/paint-order": { "modified": "2020-10-31T11:08:40.540Z", "contributors": [ "cdoublev", @@ -123187,15 +122736,11 @@ "Heycam" ] }, - "Web/SVG/Attribute/panose-1": { - "modified": "2020-10-15T22:21:41.324Z", - "contributors": ["Sebastianz"] - }, - "Web/SVG/Attribute/path": { + "Web/SVG/Reference/Attribute/path": { "modified": "2019-07-03T17:35:54.651Z", "contributors": ["Sebastianz"] }, - "Web/SVG/Attribute/pathLength": { + "Web/SVG/Reference/Attribute/pathLength": { "modified": "2019-03-24T00:09:00.253Z", "contributors": [ "arkhi", @@ -123206,19 +122751,19 @@ "Sheppy" ] }, - "Web/SVG/Attribute/patternContentUnits": { + "Web/SVG/Reference/Attribute/patternContentUnits": { "modified": "2020-10-15T21:08:37.110Z", "contributors": ["Sebastianz", "scottastrophic", "Jeremie"] }, - "Web/SVG/Attribute/patternTransform": { + "Web/SVG/Reference/Attribute/patternTransform": { "modified": "2020-10-15T21:08:31.560Z", "contributors": ["Sebastianz", "Jeremie"] }, - "Web/SVG/Attribute/patternUnits": { + "Web/SVG/Reference/Attribute/patternUnits": { "modified": "2020-10-15T21:08:39.422Z", "contributors": ["aplaice", "Sebastianz", "scottastrophic", "Jeremie"] }, - "Web/SVG/Attribute/pointer-events": { + "Web/SVG/Reference/Attribute/pointer-events": { "modified": "2020-10-15T21:08:38.591Z", "contributors": [ "aliot", @@ -123230,7 +122775,7 @@ "jarkko" ] }, - "Web/SVG/Attribute/points": { + "Web/SVG/Reference/Attribute/points": { "modified": "2019-04-25T19:22:23.048Z", "contributors": [ "Sebastianz", @@ -123241,23 +122786,23 @@ "rshetty" ] }, - "Web/SVG/Attribute/pointsAtX": { + "Web/SVG/Reference/Attribute/pointsAtX": { "modified": "2020-10-15T21:20:49.394Z", "contributors": ["Sebastianz", "Jeremie"] }, - "Web/SVG/Attribute/pointsAtY": { + "Web/SVG/Reference/Attribute/pointsAtY": { "modified": "2020-10-15T21:20:49.285Z", "contributors": ["Sebastianz", "Jeremie"] }, - "Web/SVG/Attribute/pointsAtZ": { + "Web/SVG/Reference/Attribute/pointsAtZ": { "modified": "2020-10-15T21:20:52.001Z", "contributors": ["Sebastianz", "Jeremie"] }, - "Web/SVG/Attribute/preserveAlpha": { + "Web/SVG/Reference/Attribute/preserveAlpha": { "modified": "2020-10-15T21:21:07.621Z", "contributors": ["Sebastianz", "Jeremie"] }, - "Web/SVG/Attribute/preserveAspectRatio": { + "Web/SVG/Reference/Attribute/preserveAspectRatio": { "modified": "2019-09-17T16:42:46.959Z", "contributors": [ "chrisdavidmills", @@ -123271,67 +122816,67 @@ "fscholz" ] }, - "Web/SVG/Attribute/primitiveUnits": { + "Web/SVG/Reference/Attribute/primitiveUnits": { "modified": "2020-10-15T21:08:01.126Z", "contributors": ["Sebastianz", "Dholbert", "Thomas-Brierley", "Jeremie"] }, - "Web/SVG/Attribute/r": { + "Web/SVG/Reference/Attribute/r": { "modified": "2019-03-24T00:13:32.791Z", "contributors": ["Jeremie", "rshetty", "Sheppy"] }, - "Web/SVG/Attribute/radius": { + "Web/SVG/Reference/Attribute/radius": { "modified": "2020-10-15T21:20:13.989Z", "contributors": ["Sebastianz", "Jeremie"] }, - "Web/SVG/Attribute/refX": { + "Web/SVG/Reference/Attribute/refX": { "modified": "2019-04-19T20:34:52.612Z", "contributors": ["Sebastianz", "PushpitaPikuDey", "Onkar316", "yochannah"] }, - "Web/SVG/Attribute/refY": { + "Web/SVG/Reference/Attribute/refY": { "modified": "2019-04-19T20:33:31.537Z", "contributors": ["Sebastianz"] }, - "Web/SVG/Attribute/repeatCount": { + "Web/SVG/Reference/Attribute/repeatCount": { "modified": "2020-10-15T21:13:08.234Z", "contributors": ["Sebastianz", "Jeremie", "sebmozilla"] }, - "Web/SVG/Attribute/repeatDur": { + "Web/SVG/Reference/Attribute/repeatDur": { "modified": "2020-10-15T21:13:06.804Z", "contributors": ["Sebastianz", "Jeremie"] }, - "Web/SVG/Attribute/requiredFeatures": { + "Web/SVG/Reference/Attribute/requiredFeatures": { "modified": "2020-10-15T21:13:02.874Z", "contributors": ["Sebastianz", "wbamberg", "ExE-Boss", "Jeremie", "Sheppy"] }, - "Web/SVG/Attribute/restart": { + "Web/SVG/Reference/Attribute/restart": { "modified": "2020-10-15T21:13:05.550Z", "contributors": ["Sebastianz", "Jeremie"] }, - "Web/SVG/Attribute/result": { + "Web/SVG/Reference/Attribute/result": { "modified": "2019-07-04T21:03:30.927Z", "contributors": ["Sebastianz", "Jeremie"] }, - "Web/SVG/Attribute/rotate": { + "Web/SVG/Reference/Attribute/rotate": { "modified": "2019-09-24T03:55:07.478Z", "contributors": ["chrisdavidmills", "mMerlin", "y6nH"] }, - "Web/SVG/Attribute/rx": { + "Web/SVG/Reference/Attribute/rx": { "modified": "2019-03-24T00:07:39.688Z", "contributors": ["Jeremie", "Sheppy"] }, - "Web/SVG/Attribute/ry": { + "Web/SVG/Reference/Attribute/ry": { "modified": "2019-03-24T00:07:38.765Z", "contributors": ["Jeremie", "Sheppy"] }, - "Web/SVG/Attribute/scale": { + "Web/SVG/Reference/Attribute/scale": { "modified": "2020-10-15T21:20:12.934Z", "contributors": ["Sebastianz", "Jeremie"] }, - "Web/SVG/Attribute/seed": { + "Web/SVG/Reference/Attribute/seed": { "modified": "2020-10-15T21:20:45.994Z", "contributors": ["Sebastianz", "BrianSipple", "Jeremie"] }, - "Web/SVG/Attribute/shape-rendering": { + "Web/SVG/Reference/Attribute/shape-rendering": { "modified": "2020-10-31T11:08:54.864Z", "contributors": [ "cdoublev", @@ -123343,51 +122888,43 @@ "ratcliffe_mike" ] }, - "Web/SVG/Attribute/side": { + "Web/SVG/Reference/Attribute/side": { "modified": "2020-10-15T22:20:51.017Z", "contributors": ["Sebastianz"] }, - "Web/SVG/Attribute/slope": { + "Web/SVG/Reference/Attribute/slope": { "modified": "2020-10-15T22:21:51.446Z", "contributors": ["Sebastianz"] }, - "Web/SVG/Attribute/spacing": { + "Web/SVG/Reference/Attribute/spacing": { "modified": "2020-10-15T22:21:41.151Z", "contributors": ["Sebastianz"] }, - "Web/SVG/Attribute/specularConstant": { + "Web/SVG/Reference/Attribute/specularConstant": { "modified": "2020-10-15T21:20:46.441Z", "contributors": ["Sebastianz", "kscarfone", "Jeremie"] }, - "Web/SVG/Attribute/specularExponent": { + "Web/SVG/Reference/Attribute/specularExponent": { "modified": "2019-06-17T17:07:34.464Z", "contributors": ["Sebastianz", "Jeremie"] }, - "Web/SVG/Attribute/spreadMethod": { + "Web/SVG/Reference/Attribute/spreadMethod": { "modified": "2020-10-15T22:09:16.653Z", "contributors": ["Sebastianz", "chrisdavidmills", "y6nH"] }, - "Web/SVG/Attribute/startOffset": { + "Web/SVG/Reference/Attribute/startOffset": { "modified": "2020-10-15T22:21:50.702Z", "contributors": ["Sebastianz"] }, - "Web/SVG/Attribute/stdDeviation": { + "Web/SVG/Reference/Attribute/stdDeviation": { "modified": "2020-10-15T21:20:07.672Z", "contributors": ["Sebastianz", "Jeremie"] }, - "Web/SVG/Attribute/stemh": { - "modified": "2020-10-15T22:21:39.157Z", - "contributors": ["Sebastianz"] - }, - "Web/SVG/Attribute/stemv": { - "modified": "2020-10-15T22:21:37.701Z", - "contributors": ["Sebastianz"] - }, - "Web/SVG/Attribute/stitchTiles": { + "Web/SVG/Reference/Attribute/stitchTiles": { "modified": "2020-10-15T21:20:54.449Z", "contributors": ["Sebastianz", "kscarfone", "Jeremie"] }, - "Web/SVG/Attribute/stop-color": { + "Web/SVG/Reference/Attribute/stop-color": { "modified": "2020-10-15T21:09:33.713Z", "contributors": [ "valtlai", @@ -123398,23 +122935,11 @@ "ratcliffe_mike" ] }, - "Web/SVG/Attribute/stop-opacity": { + "Web/SVG/Reference/Attribute/stop-opacity": { "modified": "2020-10-15T21:09:43.425Z", "contributors": ["Sebastianz", "connorshea", "Jeremie", "ratcliffe_mike"] }, - "Web/SVG/Attribute/strikethrough-position": { - "modified": "2019-03-23T23:07:09.400Z", - "contributors": ["kscarfone", "alicebeckett"] - }, - "Web/SVG/Attribute/strikethrough-thickness": { - "modified": "2019-03-23T23:07:04.781Z", - "contributors": ["kscarfone", "alicebeckett"] - }, - "Web/SVG/Attribute/string": { - "modified": "2020-10-15T22:21:49.130Z", - "contributors": ["Sebastianz"] - }, - "Web/SVG/Attribute/stroke": { + "Web/SVG/Reference/Attribute/stroke": { "modified": "2020-10-15T21:13:00.419Z", "contributors": [ "aplaice", @@ -123429,7 +122954,7 @@ "netsurfer912" ] }, - "Web/SVG/Attribute/stroke-dasharray": { + "Web/SVG/Reference/Attribute/stroke-dasharray": { "modified": "2020-10-15T21:12:56.442Z", "contributors": [ "Zearin_Galaurum", @@ -123440,7 +122965,7 @@ "trevorh" ] }, - "Web/SVG/Attribute/stroke-dashoffset": { + "Web/SVG/Reference/Attribute/stroke-dashoffset": { "modified": "2020-10-15T21:09:39.049Z", "contributors": [ "aplaice", @@ -123453,7 +122978,7 @@ "ratcliffe_mike" ] }, - "Web/SVG/Attribute/stroke-linecap": { + "Web/SVG/Reference/Attribute/stroke-linecap": { "modified": "2020-10-31T11:09:15.628Z", "contributors": [ "cdoublev", @@ -123464,7 +122989,7 @@ "trevorh" ] }, - "Web/SVG/Attribute/stroke-linejoin": { + "Web/SVG/Reference/Attribute/stroke-linejoin": { "modified": "2020-10-31T11:09:32.882Z", "contributors": [ "cdoublev", @@ -123478,7 +123003,7 @@ "Elli_Ryc" ] }, - "Web/SVG/Attribute/stroke-miterlimit": { + "Web/SVG/Reference/Attribute/stroke-miterlimit": { "modified": "2020-10-15T21:09:36.842Z", "contributors": [ "Neil_Haskins", @@ -123490,7 +123015,7 @@ "ratcliffe_mike" ] }, - "Web/SVG/Attribute/stroke-opacity": { + "Web/SVG/Reference/Attribute/stroke-opacity": { "modified": "2020-10-15T21:13:03.921Z", "contributors": [ "aplaice", @@ -123500,7 +123025,7 @@ "asmedrano" ] }, - "Web/SVG/Attribute/stroke-width": { + "Web/SVG/Reference/Attribute/stroke-width": { "modified": "2020-10-15T21:12:57.860Z", "contributors": [ "jpaugh", @@ -123510,7 +123035,7 @@ "jalbertbowden" ] }, - "Web/SVG/Attribute/style": { + "Web/SVG/Reference/Attribute/style": { "modified": "2020-10-15T21:09:18.692Z", "contributors": [ "Sebastianz", @@ -123521,15 +123046,15 @@ "pa7" ] }, - "Web/SVG/Attribute/surfaceScale": { + "Web/SVG/Reference/Attribute/surfaceScale": { "modified": "2019-06-09T20:26:20.171Z", "contributors": ["Sebastianz", "Jeremie"] }, - "Web/SVG/Attribute/systemLanguage": { + "Web/SVG/Reference/Attribute/systemLanguage": { "modified": "2020-10-15T22:17:47.009Z", "contributors": ["Sebastianz"] }, - "Web/SVG/Attribute/tabindex": { + "Web/SVG/Reference/Attribute/tabindex": { "modified": "2020-10-15T21:49:12.567Z", "contributors": [ "SphinxKnight", @@ -123540,23 +123065,23 @@ "ReliefCrew" ] }, - "Web/SVG/Attribute/tableValues": { + "Web/SVG/Reference/Attribute/tableValues": { "modified": "2019-08-02T19:50:20.871Z", "contributors": ["Sebastianz"] }, - "Web/SVG/Attribute/target": { + "Web/SVG/Reference/Attribute/target": { "modified": "2020-10-15T22:20:38.730Z", "contributors": ["Sebastianz"] }, - "Web/SVG/Attribute/targetX": { + "Web/SVG/Reference/Attribute/targetX": { "modified": "2020-10-15T21:21:08.411Z", "contributors": ["Sebastianz", "Jeremie"] }, - "Web/SVG/Attribute/targetY": { + "Web/SVG/Reference/Attribute/targetY": { "modified": "2020-10-15T21:21:08.913Z", "contributors": ["Sebastianz", "Jeremie"] }, - "Web/SVG/Attribute/text-anchor": { + "Web/SVG/Reference/Attribute/text-anchor": { "modified": "2020-10-31T11:09:47.991Z", "contributors": [ "cdoublev", @@ -123570,7 +123095,7 @@ "syssgx" ] }, - "Web/SVG/Attribute/text-decoration": { + "Web/SVG/Reference/Attribute/text-decoration": { "modified": "2020-10-15T21:13:03.210Z", "contributors": [ "jswisher", @@ -123580,11 +123105,11 @@ "Jeremie" ] }, - "Web/SVG/Attribute/text-rendering": { + "Web/SVG/Reference/Attribute/text-rendering": { "modified": "2020-10-31T11:10:03.182Z", "contributors": ["cdoublev", "Sebastianz", "connorshea", "BaNru", "Jeremie"] }, - "Web/SVG/Attribute/textLength": { + "Web/SVG/Reference/Attribute/textLength": { "modified": "2020-10-15T21:40:14.684Z", "contributors": [ "hallb9", @@ -123599,7 +123124,7 @@ "Tigt" ] }, - "Web/SVG/Attribute/transform": { + "Web/SVG/Reference/Attribute/transform": { "modified": "2020-04-18T13:10:34.779Z", "contributors": [ "mfuji09", @@ -123625,67 +123150,23 @@ "shingress" ] }, - "Web/SVG/Attribute/transform-origin": { + "Web/SVG/Reference/Attribute/transform-origin": { "modified": "2020-12-14T06:46:36.244Z", "contributors": ["cdoublev", "sideshowbarker", "jswisher"] }, - "Web/SVG/Attribute/type": { + "Web/SVG/Reference/Attribute/type": { "modified": "2019-04-21T20:43:05.752Z", "contributors": ["Sebastianz", "ExE-Boss", "Jeremie", "jswisher"] }, - "Web/SVG/Attribute/u1": { - "modified": "2020-10-15T22:21:14.510Z", - "contributors": ["Sebastianz"] - }, - "Web/SVG/Attribute/u2": { - "modified": "2020-10-15T22:21:14.994Z", - "contributors": ["Sebastianz"] - }, - "Web/SVG/Attribute/underline-position": { - "modified": "2019-03-23T23:07:15.452Z", - "contributors": ["kscarfone", "alicebeckett"] - }, - "Web/SVG/Attribute/underline-thickness": { - "modified": "2019-03-23T23:07:13.677Z", - "contributors": ["kscarfone", "alicebeckett"] - }, - "Web/SVG/Attribute/unicode": { - "modified": "2020-10-15T22:21:17.410Z", - "contributors": ["Sebastianz"] - }, - "Web/SVG/Attribute/unicode-bidi": { + "Web/SVG/Reference/Attribute/unicode-bidi": { "modified": "2020-10-15T22:22:52.773Z", "contributors": ["Sebastianz"] }, - "Web/SVG/Attribute/unicode-range": { - "modified": "2020-10-15T22:21:22.976Z", - "contributors": ["Sebastianz"] - }, - "Web/SVG/Attribute/units-per-em": { - "modified": "2020-10-15T22:21:36.026Z", - "contributors": ["Sebastianz"] - }, - "Web/SVG/Attribute/v-alphabetic": { - "modified": "2020-10-15T22:21:20.995Z", - "contributors": ["Sebastianz"] - }, - "Web/SVG/Attribute/v-hanging": { - "modified": "2020-10-15T22:21:22.617Z", - "contributors": ["Sebastianz"] - }, - "Web/SVG/Attribute/v-ideographic": { - "modified": "2020-10-15T22:21:35.010Z", - "contributors": ["Sebastianz"] - }, - "Web/SVG/Attribute/v-mathematical": { - "modified": "2020-10-15T22:21:36.125Z", - "contributors": ["Sebastianz"] - }, - "Web/SVG/Attribute/values": { + "Web/SVG/Reference/Attribute/values": { "modified": "2019-07-04T18:42:19.371Z", "contributors": ["Sebastianz", "mfluehr", "Jeremie"] }, - "Web/SVG/Attribute/vector-effect": { + "Web/SVG/Reference/Attribute/vector-effect": { "modified": "2020-10-31T11:10:17.986Z", "contributors": [ "cdoublev", @@ -123695,23 +123176,11 @@ "cuixiping" ] }, - "Web/SVG/Attribute/version": { + "Web/SVG/Reference/Attribute/version": { "modified": "2020-10-15T21:40:14.125Z", "contributors": ["Sebastianz", "PushpitaPikuDey", "Tigt"] }, - "Web/SVG/Attribute/vert-adv-y": { - "modified": "2020-10-15T22:21:41.073Z", - "contributors": ["Sebastianz"] - }, - "Web/SVG/Attribute/vert-origin-x": { - "modified": "2020-10-15T22:21:40.880Z", - "contributors": ["Sebastianz"] - }, - "Web/SVG/Attribute/vert-origin-y": { - "modified": "2020-10-15T22:21:40.078Z", - "contributors": ["Sebastianz"] - }, - "Web/SVG/Attribute/viewBox": { + "Web/SVG/Reference/Attribute/viewBox": { "modified": "2020-08-19T15:01:12.990Z", "contributors": [ "escattone", @@ -123730,7 +123199,7 @@ "Mogglewump" ] }, - "Web/SVG/Attribute/visibility": { + "Web/SVG/Reference/Attribute/visibility": { "modified": "2020-10-15T21:07:30.330Z", "contributors": [ "Sebastianz", @@ -123741,7 +123210,7 @@ "Sheppy" ] }, - "Web/SVG/Attribute/width": { + "Web/SVG/Reference/Attribute/width": { "modified": "2020-06-04T09:10:59.885Z", "contributors": [ "brennanyoung", @@ -123754,11 +123223,7 @@ "Bzbarsky" ] }, - "Web/SVG/Attribute/widths": { - "modified": "2020-10-15T22:21:37.858Z", - "contributors": ["Sebastianz"] - }, - "Web/SVG/Attribute/word-spacing": { + "Web/SVG/Reference/Attribute/word-spacing": { "modified": "2020-10-15T21:06:32.843Z", "contributors": [ "rachelandrew", @@ -123768,7 +123233,7 @@ "Jeremie" ] }, - "Web/SVG/Attribute/writing-mode": { + "Web/SVG/Reference/Attribute/writing-mode": { "modified": "2020-12-03T14:40:52.614Z", "contributors": [ "mfuji09", @@ -123779,7 +123244,7 @@ "Jeremie" ] }, - "Web/SVG/Attribute/x": { + "Web/SVG/Reference/Attribute/x": { "modified": "2019-05-12T17:50:32.054Z", "contributors": [ "Sebastianz", @@ -123790,47 +123255,43 @@ "Marinolinderhof" ] }, - "Web/SVG/Attribute/x-height": { - "modified": "2020-10-15T22:21:19.327Z", - "contributors": ["Sebastianz"] - }, - "Web/SVG/Attribute/x1": { + "Web/SVG/Reference/Attribute/x1": { "modified": "2019-03-24T00:08:16.559Z", "contributors": ["Jeremie", "Sheppy"] }, - "Web/SVG/Attribute/x2": { + "Web/SVG/Reference/Attribute/x2": { "modified": "2019-03-24T00:08:17.776Z", "contributors": ["Jeremie", "Ede123"] }, - "Web/SVG/Attribute/xChannelSelector": { + "Web/SVG/Reference/Attribute/xChannelSelector": { "modified": "2020-10-15T21:20:13.060Z", "contributors": ["Sebastianz", "Jeremie"] }, - "Web/SVG/Attribute/xlink:arcrole": { + "Web/SVG/Reference/Attribute/xlink:arcrole": { "modified": "2020-10-15T22:22:50.527Z", "contributors": ["Sebastianz"] }, - "Web/SVG/Attribute/xlink:href": { + "Web/SVG/Reference/Attribute/xlink:href": { "modified": "2020-04-15T04:33:14.539Z", "contributors": ["Sebastianz", "ExE-Boss", "dunnbobcat", "Jeremie"] }, - "Web/SVG/Attribute/xlink:show": { + "Web/SVG/Reference/Attribute/xlink:show": { "modified": "2020-10-15T21:39:41.602Z", "contributors": ["Sebastianz", "ExE-Boss", "rolfedh", "Tigt"] }, - "Web/SVG/Attribute/xlink:title": { + "Web/SVG/Reference/Attribute/xlink:title": { "modified": "2020-10-15T21:09:04.013Z", "contributors": ["Sebastianz", "ExE-Boss", "Jeremie"] }, - "Web/SVG/Attribute/xlink:type": { + "Web/SVG/Reference/Attribute/xlink:type": { "modified": "2020-10-15T22:22:53.536Z", "contributors": ["Sebastianz"] }, - "Web/SVG/Attribute/xml:lang": { + "Web/SVG/Reference/Attribute/xml:lang": { "modified": "2020-10-15T21:39:53.145Z", "contributors": ["Sebastianz", "ExE-Boss", "rolfedh", "Tigt"] }, - "Web/SVG/Attribute/xml:space": { + "Web/SVG/Reference/Attribute/xml:space": { "modified": "2020-10-15T21:07:58.170Z", "contributors": [ "Sebastianz", @@ -123842,44 +123303,31 @@ "Jeremie" ] }, - "Web/SVG/Attribute/y": { + "Web/SVG/Reference/Attribute/y": { "modified": "2019-05-12T17:53:04.601Z", "contributors": ["Sebastianz", "Jeremie", "essymo", "Tigt"] }, - "Web/SVG/Attribute/y1": { + "Web/SVG/Reference/Attribute/y1": { "modified": "2019-03-24T00:08:13.013Z", "contributors": ["Jeremie"] }, - "Web/SVG/Attribute/y2": { + "Web/SVG/Reference/Attribute/y2": { "modified": "2019-03-24T00:08:12.853Z", "contributors": ["Jeremie"] }, - "Web/SVG/Attribute/yChannelSelector": { + "Web/SVG/Reference/Attribute/yChannelSelector": { "modified": "2020-10-15T21:20:12.073Z", "contributors": ["Sebastianz", "Jeremie"] }, - "Web/SVG/Attribute/z": { + "Web/SVG/Reference/Attribute/z": { "modified": "2019-05-10T19:56:54.236Z", "contributors": ["Sebastianz", "HTMLValidator", "tmartin2089", "Jeremie"] }, - "Web/SVG/Attribute/zoomAndPan": { + "Web/SVG/Reference/Attribute/zoomAndPan": { "modified": "2020-10-15T22:22:41.390Z", "contributors": ["Sebastianz"] }, - "Web/SVG/Content_type": { - "modified": "2020-04-08T21:33:47.459Z", - "contributors": [ - "Zearin_Galaurum", - "Sheppy", - "Sebastianz", - "lcmando05", - "RafalNiewinski", - "kscarfone", - "Jeremie", - "ethertank" - ] - }, - "Web/SVG/Element": { + "Web/SVG/Reference/Element": { "modified": "2020-06-30T16:21:31.739Z", "contributors": [ "mfuji09", @@ -123899,7 +123347,7 @@ "Wjjohnst" ] }, - "Web/SVG/Element/a": { + "Web/SVG/Reference/Element/a": { "modified": "2020-10-15T21:11:01.339Z", "contributors": [ "mfuji09", @@ -123920,7 +123368,7 @@ "Manuel_Strehl" ] }, - "Web/SVG/Element/animate": { + "Web/SVG/Reference/Element/animate": { "modified": "2020-10-15T21:04:09.201Z", "contributors": [ "mfuji09", @@ -123943,7 +123391,7 @@ "sebmozilla" ] }, - "Web/SVG/Element/animateMotion": { + "Web/SVG/Reference/Element/animateMotion": { "modified": "2020-11-12T07:10:31.812Z", "contributors": [ "mfuji09", @@ -123956,7 +123404,7 @@ "trevorh" ] }, - "Web/SVG/Element/animateTransform": { + "Web/SVG/Reference/Element/animateTransform": { "modified": "2020-10-15T21:13:08.797Z", "contributors": [ "Tigt", @@ -123967,7 +123415,7 @@ "Jeremie" ] }, - "Web/SVG/Element/circle": { + "Web/SVG/Reference/Element/circle": { "modified": "2020-10-15T21:11:04.446Z", "contributors": [ "Tigt", @@ -123989,7 +123437,7 @@ "Wjjohnst" ] }, - "Web/SVG/Element/clipPath": { + "Web/SVG/Reference/Element/clipPath": { "modified": "2020-10-15T21:10:56.044Z", "contributors": [ "Zearin_Galaurum", @@ -124007,19 +123455,7 @@ "Manuel_Strehl" ] }, - "Web/SVG/Element/cursor": { - "modified": "2020-10-15T21:09:15.177Z", - "contributors": [ - "ExE-Boss", - "fscholz", - "Sebastianz", - "kscarfone", - "Jeremie", - "trevorh", - "Manuel_Strehl" - ] - }, - "Web/SVG/Element/defs": { + "Web/SVG/Reference/Element/defs": { "modified": "2020-10-15T21:11:02.560Z", "contributors": [ "chrisdavidmills", @@ -124033,7 +123469,7 @@ "Manuel_Strehl" ] }, - "Web/SVG/Element/desc": { + "Web/SVG/Reference/Element/desc": { "modified": "2020-10-15T21:11:04.077Z", "contributors": [ "Tigt", @@ -124047,7 +123483,7 @@ "Manuel_Strehl" ] }, - "Web/SVG/Element/ellipse": { + "Web/SVG/Reference/Element/ellipse": { "modified": "2020-10-15T21:11:04.607Z", "contributors": [ "alattalatta", @@ -124065,7 +123501,7 @@ "Wjjohnst" ] }, - "Web/SVG/Element/feBlend": { + "Web/SVG/Reference/Element/feBlend": { "modified": "2020-10-15T21:11:36.531Z", "contributors": [ "kudlav", @@ -124078,7 +123514,7 @@ "Manuel_Strehl" ] }, - "Web/SVG/Element/feColorMatrix": { + "Web/SVG/Reference/Element/feColorMatrix": { "modified": "2020-12-06T03:22:26.355Z", "contributors": [ "mfuji09", @@ -124095,7 +123531,7 @@ "Manuel_Strehl" ] }, - "Web/SVG/Element/feComponentTransfer": { + "Web/SVG/Reference/Element/feComponentTransfer": { "modified": "2020-10-18T03:36:15.184Z", "contributors": [ "timkay", @@ -124108,7 +123544,7 @@ "Manuel_Strehl" ] }, - "Web/SVG/Element/feComposite": { + "Web/SVG/Reference/Element/feComposite": { "modified": "2020-10-15T21:11:32.915Z", "contributors": [ "mfluehr", @@ -124122,7 +123558,7 @@ "Manuel_Strehl" ] }, - "Web/SVG/Element/feConvolveMatrix": { + "Web/SVG/Reference/Element/feConvolveMatrix": { "modified": "2020-10-15T21:11:35.771Z", "contributors": [ "Sebastianz", @@ -124135,7 +123571,7 @@ "Manuel_Strehl" ] }, - "Web/SVG/Element/feDiffuseLighting": { + "Web/SVG/Reference/Element/feDiffuseLighting": { "modified": "2020-10-15T21:11:34.785Z", "contributors": [ "fscholz", @@ -124146,7 +123582,7 @@ "Manuel_Strehl" ] }, - "Web/SVG/Element/feDisplacementMap": { + "Web/SVG/Reference/Element/feDisplacementMap": { "modified": "2020-10-15T21:11:32.607Z", "contributors": [ "fscholz", @@ -124158,7 +123594,7 @@ "Manuel_Strehl" ] }, - "Web/SVG/Element/feDistantLight": { + "Web/SVG/Reference/Element/feDistantLight": { "modified": "2020-10-15T21:12:01.559Z", "contributors": [ "fscholz", @@ -124170,7 +123606,7 @@ "Manuel_Strehl" ] }, - "Web/SVG/Element/feDropShadow": { + "Web/SVG/Reference/Element/feDropShadow": { "modified": "2020-12-06T04:49:53.578Z", "contributors": [ "mfuji09", @@ -124182,7 +123618,7 @@ "Sebastianz" ] }, - "Web/SVG/Element/feFlood": { + "Web/SVG/Reference/Element/feFlood": { "modified": "2020-10-15T21:11:32.117Z", "contributors": [ "fscholz", @@ -124193,7 +123629,7 @@ "Manuel_Strehl" ] }, - "Web/SVG/Element/feFuncA": { + "Web/SVG/Reference/Element/feFuncA": { "modified": "2020-10-15T21:11:44.016Z", "contributors": [ "Sebastianz", @@ -124204,7 +123640,7 @@ "Manuel_Strehl" ] }, - "Web/SVG/Element/feFuncB": { + "Web/SVG/Reference/Element/feFuncB": { "modified": "2020-10-15T21:11:44.059Z", "contributors": [ "fscholz", @@ -124215,7 +123651,7 @@ "Manuel_Strehl" ] }, - "Web/SVG/Element/feFuncG": { + "Web/SVG/Reference/Element/feFuncG": { "modified": "2020-10-15T21:11:46.167Z", "contributors": [ "fscholz", @@ -124226,7 +123662,7 @@ "Manuel_Strehl" ] }, - "Web/SVG/Element/feFuncR": { + "Web/SVG/Reference/Element/feFuncR": { "modified": "2020-10-15T21:11:43.009Z", "contributors": [ "fscholz", @@ -124237,7 +123673,7 @@ "Manuel_Strehl" ] }, - "Web/SVG/Element/feGaussianBlur": { + "Web/SVG/Reference/Element/feGaussianBlur": { "modified": "2020-10-15T21:11:42.397Z", "contributors": [ "fscholz", @@ -124250,7 +123686,7 @@ "Manuel_Strehl" ] }, - "Web/SVG/Element/feImage": { + "Web/SVG/Reference/Element/feImage": { "modified": "2020-10-15T21:11:39.310Z", "contributors": [ "fscholz", @@ -124264,7 +123700,7 @@ "Manuel_Strehl" ] }, - "Web/SVG/Element/feMerge": { + "Web/SVG/Reference/Element/feMerge": { "modified": "2020-10-15T21:11:35.003Z", "contributors": [ "jrmuizel", @@ -124280,7 +123716,7 @@ "Manuel_Strehl" ] }, - "Web/SVG/Element/feMergeNode": { + "Web/SVG/Reference/Element/feMergeNode": { "modified": "2020-10-15T21:11:32.837Z", "contributors": [ "fscholz", @@ -124293,7 +123729,7 @@ "Manuel_Strehl" ] }, - "Web/SVG/Element/feMorphology": { + "Web/SVG/Reference/Element/feMorphology": { "modified": "2020-10-15T21:11:37.646Z", "contributors": [ "Zearin_Galaurum", @@ -124307,7 +123743,7 @@ "Manuel_Strehl" ] }, - "Web/SVG/Element/feOffset": { + "Web/SVG/Reference/Element/feOffset": { "modified": "2020-10-15T21:11:35.928Z", "contributors": [ "fscholz", @@ -124319,7 +123755,7 @@ "Manuel_Strehl" ] }, - "Web/SVG/Element/fePointLight": { + "Web/SVG/Reference/Element/fePointLight": { "modified": "2020-10-15T21:12:02.605Z", "contributors": [ "a-mt", @@ -124334,7 +123770,7 @@ "Manuel_Strehl" ] }, - "Web/SVG/Element/feSpecularLighting": { + "Web/SVG/Reference/Element/feSpecularLighting": { "modified": "2020-10-15T21:12:05.376Z", "contributors": [ "Jeremie", @@ -124346,7 +123782,7 @@ "Manuel_Strehl" ] }, - "Web/SVG/Element/feSpotLight": { + "Web/SVG/Reference/Element/feSpotLight": { "modified": "2020-10-15T21:11:59.601Z", "contributors": [ "a-mt", @@ -124359,7 +123795,7 @@ "Manuel_Strehl" ] }, - "Web/SVG/Element/feTile": { + "Web/SVG/Reference/Element/feTile": { "modified": "2020-10-15T21:11:35.417Z", "contributors": [ "mor10", @@ -124371,7 +123807,7 @@ "Manuel_Strehl" ] }, - "Web/SVG/Element/feTurbulence": { + "Web/SVG/Reference/Element/feTurbulence": { "modified": "2020-10-15T21:11:30.085Z", "contributors": [ "fscholz", @@ -124384,7 +123820,7 @@ "Manuel_Strehl" ] }, - "Web/SVG/Element/filter": { + "Web/SVG/Reference/Element/filter": { "modified": "2020-11-09T04:52:08.747Z", "contributors": [ "sideshowbarker", @@ -124404,63 +123840,7 @@ "Manuel_Strehl" ] }, - "Web/SVG/Element/font": { - "modified": "2020-10-15T21:12:03.138Z", - "contributors": [ - "HTMLValidator", - "fscholz", - "Sebastianz", - "iwarui", - "kscarfone", - "Jeremie", - "Manuel_Strehl" - ] - }, - "Web/SVG/Element/font-face": { - "modified": "2020-10-15T21:12:06.840Z", - "contributors": ["Jeremie", "Sebastianz", "kscarfone", "Manuel_Strehl"] - }, - "Web/SVG/Element/font-face-format": { - "modified": "2020-10-15T21:12:02.053Z", - "contributors": [ - "fscholz", - "Sebastianz", - "kscarfone", - "Jeremie", - "Manuel_Strehl" - ] - }, - "Web/SVG/Element/font-face-name": { - "modified": "2020-10-15T21:12:06.607Z", - "contributors": [ - "fscholz", - "Sebastianz", - "kscarfone", - "Jeremie", - "Manuel_Strehl" - ] - }, - "Web/SVG/Element/font-face-src": { - "modified": "2020-10-15T21:12:08.877Z", - "contributors": [ - "fscholz", - "Sebastianz", - "kscarfone", - "Jeremie", - "Manuel_Strehl" - ] - }, - "Web/SVG/Element/font-face-uri": { - "modified": "2020-10-15T21:12:10.715Z", - "contributors": [ - "fscholz", - "Sebastianz", - "kscarfone", - "Jeremie", - "Manuel_Strehl" - ] - }, - "Web/SVG/Element/foreignObject": { + "Web/SVG/Reference/Element/foreignObject": { "modified": "2020-10-15T21:09:05.974Z", "contributors": [ "Tigt", @@ -124473,7 +123853,7 @@ "Sheppy" ] }, - "Web/SVG/Element/g": { + "Web/SVG/Reference/Element/g": { "modified": "2020-10-15T21:09:33.075Z", "contributors": [ "Tigt", @@ -124492,40 +123872,7 @@ "Wjjohnst" ] }, - "Web/SVG/Element/glyph": { - "modified": "2020-10-15T21:12:02.815Z", - "contributors": [ - "fscholz", - "Longsonr", - "Sebastianz", - "kscarfone", - "Jeremie", - "jiangr", - "Manuel_Strehl" - ] - }, - "Web/SVG/Element/glyphRef": { - "modified": "2020-10-15T21:10:58.881Z", - "contributors": [ - "fscholz", - "Sebastianz", - "Jeremie", - "kscarfone", - "Manuel_Strehl" - ] - }, - "Web/SVG/Element/hkern": { - "modified": "2020-10-15T21:11:23.391Z", - "contributors": [ - "fscholz", - "Sebastianz", - "kscarfone", - "Jeremie", - "syssgx", - "Manuel_Strehl" - ] - }, - "Web/SVG/Element/image": { + "Web/SVG/Reference/Element/image": { "modified": "2020-10-15T21:10:18.833Z", "contributors": [ "mfuji09", @@ -124552,7 +123899,7 @@ "Manuel_Strehl" ] }, - "Web/SVG/Element/line": { + "Web/SVG/Reference/Element/line": { "modified": "2020-10-15T21:11:07.514Z", "contributors": [ "mfuji09", @@ -124573,7 +123920,7 @@ "Wjjohnst" ] }, - "Web/SVG/Element/linearGradient": { + "Web/SVG/Reference/Element/linearGradient": { "modified": "2020-10-15T21:09:02.664Z", "contributors": [ "anastasialanz", @@ -124586,7 +123933,7 @@ "Sheppy" ] }, - "Web/SVG/Element/marker": { + "Web/SVG/Reference/Element/marker": { "modified": "2020-10-15T21:11:01.969Z", "contributors": [ "gerardo-rodriguez", @@ -124599,7 +123946,7 @@ "Manuel_Strehl" ] }, - "Web/SVG/Element/mask": { + "Web/SVG/Reference/Element/mask": { "modified": "2020-10-15T21:13:03.414Z", "contributors": [ "Jeremie", @@ -124610,7 +123957,7 @@ "kscarfone" ] }, - "Web/SVG/Element/metadata": { + "Web/SVG/Reference/Element/metadata": { "modified": "2020-10-15T21:11:04.604Z", "contributors": [ "Tigt", @@ -124623,21 +123970,11 @@ "Manuel_Strehl" ] }, - "Web/SVG/Element/missing-glyph": { - "modified": "2020-10-15T21:12:06.314Z", - "contributors": [ - "fscholz", - "Sebastianz", - "kscarfone", - "Jeremie", - "Manuel_Strehl" - ] - }, - "Web/SVG/Element/mpath": { + "Web/SVG/Reference/Element/mpath": { "modified": "2020-10-15T21:13:07.702Z", "contributors": ["fscholz", "Sebastianz", "kscarfone", "Jeremie"] }, - "Web/SVG/Element/path": { + "Web/SVG/Reference/Element/path": { "modified": "2020-10-15T21:11:05.536Z", "contributors": [ "CoderPi", @@ -124653,7 +123990,7 @@ "Manuel_Strehl" ] }, - "Web/SVG/Element/pattern": { + "Web/SVG/Reference/Element/pattern": { "modified": "2020-10-15T21:13:08.816Z", "contributors": [ "Zearin_Galaurum", @@ -124667,7 +124004,7 @@ "kscarfone" ] }, - "Web/SVG/Element/polygon": { + "Web/SVG/Reference/Element/polygon": { "modified": "2020-10-15T21:11:03.927Z", "contributors": [ "Zearin_Galaurum", @@ -124683,7 +124020,7 @@ "Manuel_Strehl" ] }, - "Web/SVG/Element/polyline": { + "Web/SVG/Reference/Element/polyline": { "modified": "2020-10-15T21:11:05.485Z", "contributors": [ "Jeremie", @@ -124699,7 +124036,7 @@ "Wjjohnst" ] }, - "Web/SVG/Element/radialGradient": { + "Web/SVG/Reference/Element/radialGradient": { "modified": "2020-10-15T21:10:59.784Z", "contributors": [ "chrisdavidmills", @@ -124716,7 +124053,7 @@ "Sheppy" ] }, - "Web/SVG/Element/rect": { + "Web/SVG/Reference/Element/rect": { "modified": "2020-10-15T21:09:37.379Z", "contributors": [ "Tigt", @@ -124732,7 +124069,7 @@ "Wjjohnst" ] }, - "Web/SVG/Element/script": { + "Web/SVG/Reference/Element/script": { "modified": "2020-10-15T21:09:13.492Z", "contributors": [ "Jeremie", @@ -124746,11 +124083,11 @@ "syssgx" ] }, - "Web/SVG/Element/set": { + "Web/SVG/Reference/Element/set": { "modified": "2020-10-15T21:13:03.676Z", "contributors": ["Jeremie", "fscholz", "Sebastianz", "kscarfone"] }, - "Web/SVG/Element/stop": { + "Web/SVG/Reference/Element/stop": { "modified": "2020-10-15T21:11:00.995Z", "contributors": [ "valtlai", @@ -124762,7 +124099,7 @@ "Sheppy" ] }, - "Web/SVG/Element/style": { + "Web/SVG/Reference/Element/style": { "modified": "2020-10-15T21:11:03.174Z", "contributors": [ "Jeremie", @@ -124772,7 +124109,7 @@ "Manuel_Strehl" ] }, - "Web/SVG/Element/svg": { + "Web/SVG/Reference/Element/svg": { "modified": "2020-10-15T21:09:47.294Z", "contributors": [ "nlhlong", @@ -124798,7 +124135,7 @@ "fusionchess" ] }, - "Web/SVG/Element/switch": { + "Web/SVG/Reference/Element/switch": { "modified": "2020-10-15T21:09:14.543Z", "contributors": [ "escattone", @@ -124816,7 +124153,7 @@ "Longsonr" ] }, - "Web/SVG/Element/symbol": { + "Web/SVG/Reference/Element/symbol": { "modified": "2020-10-15T21:11:00.059Z", "contributors": [ "mfluehr", @@ -124833,7 +124170,7 @@ "Manuel_Strehl" ] }, - "Web/SVG/Element/text": { + "Web/SVG/Reference/Element/text": { "modified": "2020-10-15T21:09:32.662Z", "contributors": [ "olibre", @@ -124853,7 +124190,7 @@ "Manuel_Strehl" ] }, - "Web/SVG/Element/textPath": { + "Web/SVG/Reference/Element/textPath": { "modified": "2020-10-15T21:13:04.174Z", "contributors": [ "Tigt", @@ -124867,7 +124204,7 @@ "kscarfone" ] }, - "Web/SVG/Element/title": { + "Web/SVG/Reference/Element/title": { "modified": "2020-10-15T21:09:36.744Z", "contributors": [ "Tigt", @@ -124885,18 +124222,7 @@ "Manuel_Strehl" ] }, - "Web/SVG/Element/tref": { - "modified": "2020-10-15T21:13:00.689Z", - "contributors": [ - "fscholz", - "Sebastianz", - "KyleDavidE", - "kscarfone", - "Dholbert", - "Jeremie" - ] - }, - "Web/SVG/Element/tspan": { + "Web/SVG/Reference/Element/tspan": { "modified": "2020-12-06T04:00:31.571Z", "contributors": [ "mfuji09", @@ -124911,7 +124237,7 @@ "Manuel_Strehl" ] }, - "Web/SVG/Element/use": { + "Web/SVG/Reference/Element/use": { "modified": "2020-12-06T04:35:15.913Z", "contributors": [ "mfuji09", @@ -124944,7 +124270,7 @@ "Wjjohnst" ] }, - "Web/SVG/Element/view": { + "Web/SVG/Reference/Element/view": { "modified": "2020-10-15T21:11:06.004Z", "contributors": [ "uebayasi", @@ -124957,115 +124283,7 @@ "Manuel_Strehl" ] }, - "Web/SVG/Element/vkern": { - "modified": "2020-10-15T21:11:32.787Z", - "contributors": [ - "fscholz", - "Sebastianz", - "kscarfone", - "Jeremie", - "Manuel_Strehl" - ] - }, - "Web/SVG/Linking": { - "modified": "2019-03-23T23:48:55.443Z", - "contributors": ["ExE-Boss", "Jeremie", "Kohei", "Jonathan_Watt"] - }, - "Web/SVG/Namespaces_Crash_Course": { - "modified": "2019-11-27T04:18:41.153Z", - "contributors": [ - "RicardsVeveris", - "somascope", - "octopusinvitro", - "Tigt", - "zabbarob", - "trevorh", - "Jeremie", - "Sheppy", - "Dholbert", - "Taken", - "Jonathan_Watt", - "Nickolay", - "Nickjohnson", - "Takenbot", - "NickolayBot", - "Darobin" - ] - }, - "Web/SVG/Namespaces_Crash_Course/Example": { - "modified": "2019-03-23T23:41:20.286Z", - "contributors": [ - "ethertank", - "Jeremie", - "Nickolay", - "Mgjbot", - "Taken", - "Jonathan_Watt" - ] - }, - "Web/SVG/SVG_animation_with_SMIL": { - "modified": "2019-11-07T08:50:12.574Z", - "contributors": [ - "hoang4", - "a-mt", - "fscholz", - "myf", - "SphinxKnight", - "pipcet", - "teropa", - "Longsonr", - "sanderd17", - "jpmedley", - "dbruenig", - "shakyjake", - "Jeremie", - "Sheppy", - "Nilam", - "yyss", - "Brettz9", - "jswisher", - "sebmozilla" - ] - }, - "Web/SVG/SVG_as_an_Image": { - "modified": "2019-03-24T00:12:58.786Z", - "contributors": [ - "fscholz", - "Yukulele.", - "david_ross", - "pudymody", - "arai", - "elatllat", - "Zcorpan", - "Sebastianz", - "Barbrousse", - "Jeremie", - "ethertank", - "mtmotoki@gmail.com", - "fusionchess", - "jswisher", - "Sephr", - "Dholbert" - ] - }, - "Web/SVG/Scripting": { - "modified": "2019-03-24T00:15:31.968Z", - "contributors": [ - "ZiroKyl", - "Sheppy", - "Gowan", - "Sole", - "Jeremie", - "bwm", - "Jonathan_Watt", - "Nobodyman", - "Ptak82", - "Taken", - "Dria", - "NickolayBot" - ] - }, - "Web/SVG/Tutorial": { + "Web/SVG/Tutorials/SVG_from_scratch": { "modified": "2019-03-18T20:53:00.828Z", "contributors": [ "chrisdavidmills", @@ -125089,7 +124307,7 @@ "Jonathan_Watt" ] }, - "Web/SVG/Tutorial/Basic_Shapes": { + "Web/SVG/Tutorials/SVG_from_scratch/Basic_shapes": { "modified": "2020-04-30T18:35:44.969Z", "contributors": [ "Zearin_Galaurum", @@ -125115,7 +124333,7 @@ "Wjjohnst" ] }, - "Web/SVG/Tutorial/Basic_Transformations": { + "Web/SVG/Tutorials/SVG_from_scratch/Basic_transformations": { "modified": "2019-03-24T00:17:16.153Z", "contributors": [ "Baltasarq", @@ -125133,7 +124351,7 @@ "Sheppy" ] }, - "Web/SVG/Tutorial/Clipping_and_masking": { + "Web/SVG/Tutorials/SVG_from_scratch/Clipping_and_masking": { "modified": "2019-03-18T20:46:50.265Z", "contributors": [ "jrmuizel", @@ -125151,7 +124369,7 @@ "Sheppy" ] }, - "Web/SVG/Tutorial/Fills_and_Strokes": { + "Web/SVG/Tutorials/SVG_from_scratch/Fills_and_strokes": { "modified": "2020-04-30T18:40:29.453Z", "contributors": [ "Zearin_Galaurum", @@ -125172,7 +124390,7 @@ "Wjjohnst" ] }, - "Web/SVG/Tutorial/Filter_effects": { + "Web/SVG/Tutorials/SVG_from_scratch/Filter_effects": { "modified": "2019-03-24T00:10:30.512Z", "contributors": [ "rezof", @@ -125185,7 +124403,7 @@ "Manuel_Strehl" ] }, - "Web/SVG/Tutorial/Getting_Started": { + "Web/SVG/Tutorials/SVG_from_scratch/Getting_started": { "modified": "2020-03-26T05:28:01.340Z", "contributors": [ "mfuji09", @@ -125219,7 +124437,7 @@ "Jonathan_Watt" ] }, - "Web/SVG/Tutorial/Gradients": { + "Web/SVG/Tutorials/SVG_from_scratch/Gradients": { "modified": "2019-05-10T08:57:19.114Z", "contributors": [ "r-i-c-h", @@ -125236,7 +124454,24 @@ "Manuel_Strehl" ] }, - "Web/SVG/Tutorial/Introduction": { + "Web/SVG/Tutorials/SVG_from_scratch/Image_element": { + "modified": "2020-12-14T11:30:39.212Z", + "contributors": [ + "Zearin_Galaurum", + "yoscheherazade", + "pamelahicks", + "rousan", + "sm1215", + "Delapouite", + "trevorh", + "chrisdoble", + "Jeremie", + "kscarfone", + "jswisher", + "kperch" + ] + }, + "Web/SVG/Tutorials/SVG_from_scratch/Introduction": { "modified": "2019-03-18T20:53:00.633Z", "contributors": [ "devinea2", @@ -125269,7 +124504,7 @@ "Jonathan_Watt" ] }, - "Web/SVG/Tutorial/Other_content_in_SVG": { + "Web/SVG/Tutorials/SVG_from_scratch/Other_content_in_SVG": { "modified": "2019-03-28T17:25:42.724Z", "contributors": [ "jwhitlock", @@ -125280,7 +124515,7 @@ "Sheppy" ] }, - "Web/SVG/Tutorial/Paths": { + "Web/SVG/Tutorials/SVG_from_scratch/Paths": { "modified": "2020-08-15T09:04:44.596Z", "contributors": [ "chrisdavidmills", @@ -125341,7 +124576,7 @@ "Wjjohnst" ] }, - "Web/SVG/Tutorial/Patterns": { + "Web/SVG/Tutorials/SVG_from_scratch/Patterns": { "modified": "2020-04-30T18:44:44.601Z", "contributors": [ "Zearin_Galaurum", @@ -125356,7 +124591,7 @@ "Manuel_Strehl" ] }, - "Web/SVG/Tutorial/Positions": { + "Web/SVG/Tutorials/SVG_from_scratch/Positions": { "modified": "2019-08-22T10:03:43.320Z", "contributors": [ "kmgreg", @@ -125377,54 +124612,7 @@ "Manuel_Strehl" ] }, - "Web/SVG/Tutorial/SVG_Filters_Tutorial": { - "modified": "2020-10-24T07:46:48.631Z", - "contributors": ["chrisdavidmills", "amized", "teoli", "curacao"] - }, - "Web/SVG/Tutorial/SVG_Image_Tag": { - "modified": "2020-12-14T11:30:39.212Z", - "contributors": [ - "Zearin_Galaurum", - "yoscheherazade", - "pamelahicks", - "rousan", - "sm1215", - "Delapouite", - "trevorh", - "chrisdoble", - "Jeremie", - "kscarfone", - "jswisher", - "kperch" - ] - }, - "Web/SVG/Tutorial/SVG_In_HTML_Introduction": { - "modified": "2020-04-20T03:12:49.575Z", - "contributors": [ - "sideshowbarker", - "chrisdavidmills", - "stephaniehobson", - "Jeremie", - "vuldin", - "ethertank", - "Neformal.lviv", - "tomchen1989", - "Brettz9", - "Gfldex", - "Sheppy", - "Jonathan_Watt", - "Nickolay", - "Nickjohnson", - "Takenbot", - "NickolayBot", - "Chbok", - "Dria", - "Marcoos", - "Jeff Schiller", - "Roc" - ] - }, - "Web/SVG/Tutorial/SVG_and_CSS": { + "Web/SVG/Tutorials/SVG_from_scratch/SVG_and_CSS": { "modified": "2019-10-31T09:48:22.366Z", "contributors": [ "leela52452", @@ -125452,23 +124640,7 @@ "Waldo" ] }, - "Web/SVG/Tutorial/SVG_fonts": { - "modified": "2020-12-14T11:30:40.083Z", - "contributors": [ - "stephaniehobson", - "chrisdavidmills", - "LC43", - "Bumxu", - "trevorh", - "chrisdoble", - "Jeremie", - "kperch", - "Ecmanaut", - "yyss", - "Manuel_Strehl" - ] - }, - "Web/SVG/Tutorial/Texts": { + "Web/SVG/Tutorials/SVG_from_scratch/Texts": { "modified": "2020-04-30T18:47:40.940Z", "contributors": [ "Zearin_Galaurum", @@ -125488,7 +124660,7 @@ "Manuel_Strehl" ] }, - "Web/SVG/Tutorial/Tools_for_SVG": { + "Web/SVG/Tutorials/SVG_from_scratch/Tools_for_SVG": { "modified": "2019-05-23T11:54:38.315Z", "contributors": [ "stephaniehobson", @@ -125503,6 +124675,22 @@ "Telanor" ] }, + "Web/SVG/Tutorials/SVG_from_scratch/Using_fonts": { + "modified": "2020-12-14T11:30:40.083Z", + "contributors": [ + "stephaniehobson", + "chrisdavidmills", + "LC43", + "Bumxu", + "trevorh", + "chrisdoble", + "Jeremie", + "kperch", + "Ecmanaut", + "yyss", + "Manuel_Strehl" + ] + }, "Web/Security": { "modified": "2020-12-14T09:30:29.083Z", "contributors": [ @@ -125834,10 +125022,6 @@ "adithya_mani" ] }, - "Web/Security/Types_of_attacks": { - "modified": "2020-05-29T13:56:47.726Z", - "contributors": ["jswisher"] - }, "Web/Security/Weak_Signature_Algorithm": { "modified": "2019-03-23T23:07:20.873Z", "contributors": [ @@ -127025,33 +126209,6 @@ "CitizenK" ] }, - "Web/XML/XSLT/Guides/Transforming_XML_with_XSLT/An_Overview": { - "modified": "2019-03-23T23:43:18.530Z", - "contributors": [ - "SphinxKnight", - "chrisdavidmills", - "Fredchat", - "jswisher", - "trevorh", - "Dria", - "CitizenK" - ] - }, - "Web/XML/XSLT/Guides/Transforming_XML_with_XSLT/For_Further_Reading": { - "modified": "2019-03-23T23:43:15.921Z", - "contributors": [ - "SphinxKnight", - "chrisdavidmills", - "ethertank", - "jswisher", - "Fredchat", - "Major Small", - "Nickolay", - "Ptak82", - "Dria", - "CitizenK" - ] - }, "Web/XML/XSLT/Reference/Element": { "modified": "2019-03-24T00:14:46.715Z", "contributors": [ diff --git a/files/en-us/games/anatomy/index.md b/files/en-us/games/anatomy/index.md index ee5fee68589152d..a8266e7f977efe9 100644 --- a/files/en-us/games/anatomy/index.md +++ b/files/en-us/games/anatomy/index.md @@ -114,7 +114,7 @@ The key to programming a main loop, in JavaScript, is to attach it to whatever e ## Building a more optimized main loop in JavaScript -Ultimately, in JavaScript, the browser is running its own main loop and your code exists in some of its stages. The above sections describe main loops which try not to wrestle away control from the browser. These main methods attach themselves to `window.requestAnimationFrame()`, which asks the browser for control over the upcoming frame. It is up to the browser how to relate these requests to their main loop. The [W3C spec for requestAnimationFrame](https://www.w3.org/TR/animation-timing/) does not really define exactly when the browsers must perform the requestAnimationFrame callbacks. This can be a benefit because it leaves browser vendors free to experiment with the solutions that they feel are best and tweak it over time. +Ultimately, in JavaScript, the browser is running its own main loop and your code exists in some of its stages. The above sections describe main loops that avoid taking control away from the browser. These main methods attach themselves to `window.requestAnimationFrame()`, which asks the browser for control over the upcoming frame. It is up to the browser how to relate these requests to its main loop. The [HTML spec](https://html.spec.whatwg.org/multipage/imagebitmap-and-animations.html#dom-animationframeprovider-requestanimationframe) does not really define exactly when the browsers must perform the `requestAnimationFrame` callbacks. This can be a benefit because it leaves browser vendors free to experiment with the solutions that they feel are best and tweak them over time. Modern versions of Firefox and Google Chrome (and probably others) _attempt_ to connect `requestAnimationFrame` callbacks to their main thread at the very beginning of a frame's timeslice. The browser's main thread thus _tries_ to look like the following: diff --git a/files/en-us/games/index.md b/files/en-us/games/index.md index 41272c331fe4301..7014be8b57bd098 100644 --- a/files/en-us/games/index.md +++ b/files/en-us/games/index.md @@ -17,15 +17,9 @@ We've also included a reference section so you can easily find information about > [!NOTE] > Creating games on the web draws on a number of core web technologies such as HTML, CSS, and JavaScript. The [Learn web development](/en-US/docs/Learn_web_development) section is a good place to go to get started with the basics. -## Port native games to the Web +## Guides -If you are a native developer (for example writing games in C++), and you are interested in how you can port your games over to the Web, you should learn more about our [Emscripten](https://emscripten.org/index.html) tool — this is an LLVM to JavaScript compiler, which takes LLVM bytecode (e.g. generated from C/C++ using Clang, or from another language) and compiles that into [asm.js](/en-US/docs/Games/Tools/asm.js), which can be run on the Web. - -To get started, see: - -- [About Emscripten](https://emscripten.org/docs/introducing_emscripten/about_emscripten.html) for an introduction including high-level details. -- [Download and Install](https://emscripten.org/docs/getting_started/downloads.html) for installing the toolchain. -- [Emscripten Tutorial](https://emscripten.org/docs/getting_started/Tutorial.html) for a tutorial to teach you how to get started. +{{SubpagesWithSummaries}} ## Examples diff --git a/files/en-us/games/introduction/index.md b/files/en-us/games/introduction/index.md index 08e4827a978f3f0..e0b4be98f8880ec 100644 --- a/files/en-us/games/introduction/index.md +++ b/files/en-us/games/introduction/index.md @@ -6,7 +6,7 @@ page-type: guide {{GamesSidebar}} -The modern web has quickly become a viable platform not only for creating stunning, high quality games, but also for distributing those games. +The modern web has quickly become a viable platform not only for creating stunning, high quality games, but also for distributing those games. This article introduces you to the advantages of using the Web as a game platform, and the technologies that make it possible. The range of games that can be created is on par with desktop and native OS counterparts. With modern Web technologies and a recent browser, it's entirely possible to make stunning, top-notch games for the Web. And we're not talking about simple card games or multiplayer social games that have in the olden days been done using Flash®. We're talking about 3D action shooters, RPGs, and more. Thanks to massive performance improvements in [JavaScript](/en-US/docs/Web/JavaScript) just-in-time compiler technology and new APIs, you can build games that run in the browser (or on [HTML5](/en-US/docs/Glossary/HTML5)-powered devices) without making compromises. @@ -103,7 +103,7 @@ For the tech folks, let's dig into the APIs the Web brings to the table that cat - : If you want your users to be able to use gamepads or other game controllers to work your game, you'll need this API. - [HTML](/en-US/docs/Web/HTML) and [CSS](/en-US/docs/Web/CSS) - : Together, these two technologies let you build, style, and lay out your game's user interface. Part of HTML is the {{HTMLElement("canvas")}} element, which provides one way to do 2D graphics. -- [HTML audio](/en-US/docs/Web/HTML/Element/audio) +- [HTML audio](/en-US/docs/Web/HTML/Reference/Elements/audio) - : The {{HTMLElement("audio")}} element lets you easily play simple sound effects and music. If your needs are more involved, check out the [Web Audio API](/en-US/docs/Web/API/Web_Audio_API) for real audio processing power! - [IndexedDB](/en-US/docs/Web/API/IndexedDB_API) - : A powerful data storage API for maintaining user data on their own computer or device. A great way to save game state and other information locally so it doesn't have to be downloaded every time it's needed. Also useful to help make your game playable even when the user isn't connected to the Web (such as when they're stuck on an airplane for hours on end). diff --git a/files/en-us/games/introduction_to_html5_game_development/index.md b/files/en-us/games/introduction_to_html5_game_development/index.md deleted file mode 100644 index c46ec12547f4a6e..000000000000000 --- a/files/en-us/games/introduction_to_html5_game_development/index.md +++ /dev/null @@ -1,117 +0,0 @@ ---- -title: Introduction to HTML Game Development -slug: Games/Introduction_to_HTML5_Game_Development -page-type: guide ---- - -{{GamesSidebar}} - -## Advantages - -1. Games built with HTML work on smartphones, tablets, PCs and Smart TVs. -2. Advertise and promote your game all over the Web as well as other media. -3. Payments. Charge what you want and use whatever payment processing service you like. -4. Update your game whenever you want. -5. Collect your own analytics! -6. Connect with your customers more closely, -7. Players can play the game anywhere, anytime. - -## Web Technologies - -<table class="no-markdown standard-table"> - <caption>Web technologies in game development and their function</caption> - <thead> - <tr> - <th scope="col"><strong>Function</strong></th> - <th scope="col"><strong>Technology</strong></th> - </tr> - </thead> - <tbody> - <tr> - <td><strong>Audio</strong></td> - <td><a href="/en-US/docs/Web/API/Web_Audio_API">Web Audio API</a></td> - </tr> - <tr> - <td><strong>Graphics</strong></td> - <td> - <a href="/en-US/docs/Web/API/WebGL_API">WebGL</a> (<a - href="https://www.khronos.org/opengles/" - >OpenGL ES</a - > - 2.0) - </td> - </tr> - <tr> - <td><strong>Input</strong></td> - <td> - <a href="/en-US/docs/Web/API/Touch_events">Touch events</a>, - <a href="/en-US/docs/Web/API/Gamepad_API/Using_the_Gamepad_API" - >Gamepad API</a - >, device sensors, <a href="/en-US/docs/Web/API/WebRTC_API">WebRTC</a>, - <a href="/en-US/docs/Web/API/Fullscreen_API">Full Screen API</a>, - <a href="/en-US/docs/Web/API/Pointer_Lock_API">Pointer Lock API</a> - </td> - </tr> - <tr> - <td><strong>Language</strong></td> - <td> - <a href="/en-US/docs/Web/JavaScript">JavaScript</a> (or C/C++ using - <a href="https://github.com/emscripten-core/emscripten/wiki">Emscripten</a> to - compile to JavaScript) - </td> - </tr> - <tr> - <td><strong>Networking</strong></td> - <td> - <a href="/en-US/docs/Web/API/WebRTC_API">WebRTC</a> and/or - <a href="/en-US/docs/Web/API/WebSockets_API">WebSockets</a> - </td> - </tr> - <tr> - <td><strong>Storage</strong></td> - <td> - <a href="/en-US/docs/Web/API/IndexedDB_API">IndexedDB</a> or the "cloud" - </td> - </tr> - <tr> - <td><strong>Web</strong></td> - <td> - <a href="/en-US/docs/Web/HTML">HTML</a>, - <a href="/en-US/docs/Web/CSS">CSS</a>, - <a href="/en-US/docs/Web/SVG">SVG</a> (and much more!) - </td> - </tr> - </tbody> -</table> - -- [Fetch API](/en-US/docs/Web/API/Fetch_API) - - : Send and receive any kind of data you want from a Web server like downloading new game levels and artwork to transmitting non-real-time game status information back and forth. -- [Full Screen API](/en-US/docs/Web/API/Fullscreen_API) - - : Full screen gameplay. -- [Gamepad API](/en-US/docs/Web/API/Gamepad_API/Using_the_Gamepad_API) - - : Use gamepads or other game controllers. -- [HTML](/en-US/docs/Web/HTML) and [CSS](/en-US/docs/Web/CSS) - - : Build, style, and lay out your game's user interface. -- [HTML audio](/en-US/docs/Web/HTML/Element/audio) - - : Easily play simple sound effects and music. -- [IndexedDB](/en-US/docs/Web/API/IndexedDB_API) - - : Store user data on their own computer or device. -- [JavaScript](/en-US/docs/Web/JavaScript) - - : Fast web programming language to write the code for your game. - To easily port your existing games [Emscripten](https://github.com/emscripten-core/emscripten/wiki) or [Asm.js](http://asmjs.org/spec/latest/) -- [Pointer Lock API](/en-US/docs/Web/API/Pointer_Lock_API) - - : Lock the mouse or other pointing device within your game's interface. -- [SVG](/en-US/docs/Web/SVG) (Scalable Vector Graphics) - - : Build vector graphics that scale smoothly regardless of the size or resolution of the user's display. -- [Typed Arrays](/en-US/docs/Web/JavaScript/Guide/Typed_arrays) - - : Access raw binary data from within JavaScript; Manipulate GL textures, game data, or anything else. -- [Web Audio API](/en-US/docs/Web/API/Web_Audio_API) - - : Control the playback, synthesis, and manipulation of audio in real time. -- [WebGL](/en-US/docs/Web/API/WebGL_API) - - : Create high-performance, hardware-accelerated 3D (and 2D) graphics. [OpenGL ES](https://www.khronos.org/opengles/) 2.0. -- [WebRTC](/en-US/docs/Web/API/WebRTC_API) - - : Real-Time Communications to control audio and video data, including teleconferencing and transmitting other application data back and forth between two users like chat. -- [WebSockets](/en-US/docs/Web/API/WebSockets_API) - - : Connect your app or site to a server to transmit data back and forth in real-time. Perfect for multiplayer gaming action, chat services, and so forth. -- [Web Workers](/en-US/docs/Web/API/Web_Workers_API/Using_web_workers) - - : Spawn background threads running their own JavaScript code for multicore processors. diff --git a/files/en-us/games/publishing_games/game_distribution/index.md b/files/en-us/games/publishing_games/game_distribution/index.md index 5654bc8ce97455a..072e8d90b986cd5 100644 --- a/files/en-us/games/publishing_games/game_distribution/index.md +++ b/files/en-us/games/publishing_games/game_distribution/index.md @@ -30,7 +30,7 @@ You don't have to tell people to search for your game in an app store with HTML The vast majority of the traffic we are interested in — people playing HTML games — comes from mobile devices so that's something you will have to focus on if you truly want to succeed. Mobile devices are where HTML technology can truly shine and show its advantages. There's no Flash, and HTML is fully multiplatform. -Trying to compete with desktop games directly is very difficult. You can put your HTML games into the same arena (see [Native desktop](#native_desktop), later on) and you should because it's good to diversify the platforms you support, but you have to remember that developers creating desktop games have years of experience, great tools and stable distribution channels. Many HTML games will target different market segments than native desktop games, e.g. simple time killer games to be played while on the move rather than huge immersive experiences. Such games are often designed to be played with two, or even one finger, so you can hold the device, play the game and be able to use the second hand for whatever you currently need. +Trying to compete with desktop games directly is very difficult. You can put your HTML games into the same arena (see [Native desktop](#native_desktop), later on) and you should because it's good to diversify the platforms you support, but you have to remember that developers creating desktop games have years of experience, great tools and stable distribution channels. Many HTML games will target different market segments than native desktop games, e.g., simple time killer games to be played while on the move rather than huge immersive experiences. Such games are often designed to be played with two, or even one finger, so you can hold the device, play the game and be able to use the second hand for whatever you currently need. Saying this, desktop platforms can be used for distribution quite easily with the availability of wrappers that can help you prepare native builds of your game see [Packaging games](#packaging_games). It's also nice to provide desktop controls for your games even if you're mostly targeting mobile. Players are enjoying your games on any platform available, and desktop is one of them. Plus, it is usually easier to build and test the game first on desktop, and then move on to debugging mobile. @@ -50,7 +50,7 @@ If you are a front-end developer, you may already know what to do. An HTML game If you want to make money out of game dev, you should secure your source code one way or another against people who could easily take it and sell it as their own. You can concatenate and minify the code to make it smaller and uglify it so it's a lot harder to reverse engineer your game. Another good measure to take is to provide an online demo if you're planning on packaging it and selling it in a closed store like iTunes or Steam. -If you're working on a side project just for fun, then leaving the source open will benefit those who would like to learn from what you've created. You don't even have to worry about looking for a hosting provider as it's possible to [host games on GitHub Pages](https://end3r.com/blog/2014/02/host-your-html5-games-on-github-pages/). You'll get free hosting, version control and possible contributors if your project is interesting enough. +If you're working on a side project just for fun, then leaving the source open will benefit those who would like to learn from what you've created. You don't even have to worry about looking for a hosting provider as it's possible to [host games on GitHub Pages](https://end3r.com/blog/host-your-html5-games-on-github-pages). You'll get free hosting, version control and possible contributors if your project is interesting enough. ### Publishers and portals diff --git a/files/en-us/games/publishing_games/game_monetization/index.md b/files/en-us/games/publishing_games/game_monetization/index.md index 6c3f248f7a4bc17..5723dfcaace67d2 100644 --- a/files/en-us/games/publishing_games/game_monetization/index.md +++ b/files/en-us/games/publishing_games/game_monetization/index.md @@ -6,7 +6,7 @@ page-type: guide {{GamesSidebar}} -When you've spent your time building a game, [distributing](/en-US/docs/Games/Publishing_games/Game_distribution) it and [promoting](/en-US/docs/Games/Publishing_games/Game_promotion) it you should consider earning some money out of it. If your work is a serious endeavour on the path to becoming an independent game developer able to make a living, read on and see what your options are. The technology is mature enough; now it's just about choosing the right approach. +When you've spent your time building a game, [distributing](/en-US/docs/Games/Publishing_games/Game_distribution) it and [promoting](/en-US/docs/Games/Publishing_games/Game_promotion) it you should consider earning some money out of it. If your work is a serious endeavor on the path to becoming an independent game developer able to make a living, read on and see what your options are. The technology is mature enough; now it's just about choosing the right approach. ## Paid games diff --git a/files/en-us/games/publishing_games/game_promotion/index.md b/files/en-us/games/publishing_games/game_promotion/index.md index d795f788be4dad3..37450fca8332389 100644 --- a/files/en-us/games/publishing_games/game_promotion/index.md +++ b/files/en-us/games/publishing_games/game_promotion/index.md @@ -18,7 +18,7 @@ Many great games get started as a quick, sloppy demo submitted to a competition. You should definitely create your own website containing all the information about your games, so people can see what you've worked on. The more information you can include the better — you should include screenshots, description, trailer, press kit, requirements, available platforms, support details and more. You'll get bonus points for allowing your users to directly play your games online — at least in demo form. Also, you should do some work on SEO to allow people to find your games more easily. -You should also blog about everything related to your gamedev activities. Write about your development process, nasty bugs you encounter, funny stories, lessons learned, and the ups and downs of being a game developer. Continually publishing information about your games will help educate others, increase your reputation in the community, and further improve SEO. A further option is to publish [monthly reports](https://end3r.com/blog/?s=monthly+report) that summarize all your progress — it helps you see what you've accomplished throughout the month and what's still left to do, and it keeps reminding people that your game is coming out soon — building buzz is always good. +You should also blog about everything related to your gamedev activities. Write about your development process, nasty bugs you encounter, funny stories, lessons learned, and the ups and downs of being a game developer. Continually publishing information about your games will help educate others, increase your reputation in the community, and further improve SEO. A further option is to publish [monthly reports](https://end3r.com/blog?s=monthly+report) that summarize all your progress — it helps you see what you've accomplished throughout the month and what's still left to do, and it keeps reminding people that your game is coming out soon — building buzz is always good. While you can create your website from scratch, there are also tools that can help make the process easier. [ManaKeep](https://manakeep.com/) is a website builder made for indie game developers and provides a great starting point to create your website. [Presskit()](https://dopresskit.com/) is a press kit builder that helps you create a press page to share with the media. diff --git a/files/en-us/games/publishing_games/index.md b/files/en-us/games/publishing_games/index.md index d47084895f323cc..7f76d33f662ed6f 100644 --- a/files/en-us/games/publishing_games/index.md +++ b/files/en-us/games/publishing_games/index.md @@ -18,4 +18,4 @@ Developing and finishing the game is not enough. You have to let the world know ## Game monetization -When you spend your time building, publishing and promoting your game, you will at some point consider earning money out of it. [Game monetization](/en-US/docs/Games/Publishing_games/Game_monetization) is essential to anyone who considers their game development work a serious endeavour on the path to becoming an independent game developer able to make a living, so read on and see what your options are. The technology is mature enough; it's just a matter of choosing the right approach. +When you spend your time building, publishing and promoting your game, you will at some point consider earning money out of it. [Game monetization](/en-US/docs/Games/Publishing_games/Game_monetization) is essential to anyone who considers their game development work a serious endeavor on the path to becoming an independent game developer able to make a living, so read on and see what your options are. The technology is mature enough; it's just a matter of choosing the right approach. diff --git a/files/en-us/games/techniques/2d_collision_detection/index.md b/files/en-us/games/techniques/2d_collision_detection/index.md index a9e53f8130e1474..50b9735aad898df 100644 --- a/files/en-us/games/techniques/2d_collision_detection/index.md +++ b/files/en-us/games/techniques/2d_collision_detection/index.md @@ -6,9 +6,9 @@ page-type: guide {{GamesSidebar}} -Algorithms to detect collision in 2D games depend on the type of shapes that can collide (e.g. Rectangle to Rectangle, Rectangle to Circle, Circle to Circle). Generally you will have a simple generic shape that covers the entity known as a "hitbox" so even though collision may not be pixel perfect, it will look good enough and be performant across multiple entities. This article provides a review of the most common techniques used to provide collision detection in 2D games. +Algorithms to detect collision in 2D games depend on the type of shapes that can collide (e.g., Rectangle to Rectangle, Rectangle to Circle, Circle to Circle). Generally you will have a simple generic shape that covers the entity known as a "hitbox" so even though collision may not be pixel perfect, it will look good enough and be performant across multiple entities. This article provides a review of the most common techniques used to provide collision detection in 2D games. -## Axis-Aligned Bounding Box +## Axis-aligned bounding box One of the simpler forms of collision detection is between two rectangles that are axis aligned — meaning no rotation. The algorithm works by ensuring there is no gap between any of the 4 sides of the rectangles. Any gap means a collision does not exist. @@ -54,7 +54,7 @@ rect2.bind("EnterFrame", function () { > **Note:** [Another example without Canvas or external libraries](https://jsfiddle.net/jlr7245/217jrozd/3/). -## Circle Collision +## Circle collision Another simple shape for collision detection is between two circles. This algorithm works by taking the center points of the two circles and ensuring the distance between the center points are less than the two radii added together. @@ -116,8 +116,8 @@ const circle2 = Crafty.e("2D, Canvas, Circle, Fourway") .circle(20, "blue"); circle2.bind("EnterFrame", function () { - const dx = circle1.x - circle2.x; - const dy = circle1.y - circle2.y; + const dx = circle1.x + circle1.radius - (circle2.x + circle2.radius); + const dy = circle1.y + circle1.radius - (circle2.y + circle2.radius); const distance = Math.sqrt(dx * dx + dy * dy); const colliding = distance < circle1.radius + circle2.radius; @@ -127,6 +127,9 @@ circle2.bind("EnterFrame", function () { {{ EmbedLiveSample('Circle_Collision', '700', '300') }} +> [!NOTE] +> The circles' `x` and `y` coordinates refer to their top left corners, so we need to add the radius to compare their centers. + > **Note:** [Here is another example without Canvas or external libraries.](https://jsfiddle.net/jlr7245/teb4znk0/20/) ## Separating Axis Theorem @@ -141,14 +144,14 @@ Implementing SAT is out of scope for this page so see the recommended tutorials 4. [SAT (Separating Axis Theorem)](https://dyn4j.org/2010/01/sat/) 5. [Separating Axis Theorem](https://programmerart.weebly.com/separating-axis-theorem.html) -## Collision Performance +## Collision performance While some of these algorithms for collision detection are simple enough to calculate, it can be a waste of cycles to test _every_ entity with every other entity. Usually games will split collision into two phases, broad and narrow. -### Broad Phase +### Broad phase Broad phase should give you a list of entities that _could_ be colliding. This can be implemented with a spatial data structure that will give you a rough idea of where the entity exists and what exist around it. Some examples of spatial data structures are Quad Trees, R-Trees or a Spatial Hashmap. -### Narrow Phase +### Narrow phase When you have a small list of entities to check you will want to use a narrow phase algorithm (like the ones listed above) to provide a certain answer as to whether there is a collision or not. diff --git a/files/en-us/games/techniques/3d_collision_detection/index.md b/files/en-us/games/techniques/3d_collision_detection/index.md index 868338e34eb135a..a63eba916653a5e 100644 --- a/files/en-us/games/techniques/3d_collision_detection/index.md +++ b/files/en-us/games/techniques/3d_collision_detection/index.md @@ -77,7 +77,7 @@ function intersect(a, b) { ## Bounding spheres -Using bounding spheres to detect collisions is a bit more complex than AABB, but still fairly quick to test. The main advantage of spheres is that they are invariant to rotation, so if the wrapped entity rotates, the bounding sphere would still be the same. Their main disadvantage is that unless the entity they are wrapping is actually spherical, the wrapping is usually not a good fit (i.e. wrapping a person with a bounding sphere will cause a lot of false positives, whereas an AABB would be a better match). +Using bounding spheres to detect collisions is a bit more complex than AABB, but still fairly quick to test. The main advantage of spheres is that they are invariant to rotation, so if the wrapped entity rotates, the bounding sphere would still be the same. Their main disadvantage is that unless the entity they are wrapping is actually spherical, the wrapping is usually not a good fit (i.e., wrapping a person with a bounding sphere will cause a lot of false positives, whereas an AABB would be a better match). ### Point vs. sphere diff --git a/files/en-us/games/techniques/3d_on_the_web/building_up_a_basic_demo_with_a-frame/cube.png b/files/en-us/games/techniques/3d_on_the_web/building_up_a_basic_demo_with_a-frame/cube.png deleted file mode 100644 index d63147c9dbc745c..000000000000000 Binary files a/files/en-us/games/techniques/3d_on_the_web/building_up_a_basic_demo_with_a-frame/cube.png and /dev/null differ diff --git a/files/en-us/games/techniques/3d_on_the_web/building_up_a_basic_demo_with_a-frame/index.md b/files/en-us/games/techniques/3d_on_the_web/building_up_a_basic_demo_with_a-frame/index.md index ba6478c4296ae6c..fac7f8597568415 100644 --- a/files/en-us/games/techniques/3d_on_the_web/building_up_a_basic_demo_with_a-frame/index.md +++ b/files/en-us/games/techniques/3d_on_the_web/building_up_a_basic_demo_with_a-frame/index.md @@ -74,7 +74,7 @@ Adding the cube to the scene is done by adding a simple [`<a-box>`](https://afra ``` It contains a few parameters already defined: `color`, `position` and `rotation` — these are fairly obvious, and define the base color of the cube, the position inside the 3D scene, and the rotation of the cube. -The distance values (e.g. for the cube y position) are unitless, and can basically be anything you deem suitable for your scene — millimeters, meters, feet, or miles — it's up to you. +The distance values (e.g., for the cube y position) are unitless, and can basically be anything you deem suitable for your scene — millimeters, meters, feet, or miles — it's up to you. ### Adding a background: Sky box @@ -288,23 +288,6 @@ Everything is rendered properly and animating — congratulations on building yo dur: 2000; loop: true; easing: linear;"> </a-entity> </a-scene> - -<script> - const scene = document.querySelector("a-scene"); - const cylinder = document.createElement("a-cylinder"); - cylinder.setAttribute("color", "#FF9500"); - cylinder.setAttribute("height", "2"); - cylinder.setAttribute("radius", "0.75"); - cylinder.setAttribute("position", "3 1 0"); - scene.appendChild(cylinder); - let t = 0; - function render() { - t += 0.01; - requestAnimationFrame(render); - cylinder.setAttribute("position", "3 " + (Math.sin(t * 2) + 1) + " 0"); - } - render(); -</script> ``` ```css hidden live-sample___a-frame-animation @@ -317,6 +300,23 @@ body { } ``` +```js live-sample___a-frame-animation +const scene = document.querySelector("a-scene"); +const cylinder = document.createElement("a-cylinder"); +cylinder.setAttribute("color", "#FF9500"); +cylinder.setAttribute("height", "2"); +cylinder.setAttribute("radius", "0.75"); +cylinder.setAttribute("position", "3 1 0"); +scene.appendChild(cylinder); +let t = 0; +function render() { + t += 0.01; + requestAnimationFrame(render); + cylinder.setAttribute("position", `3 ${Math.sin(t * 2) + 1} 0`); +} +render(); +``` + {{embedlivesample("a-frame-animation", "", "400px")}} ## Summary diff --git a/files/en-us/games/techniques/3d_on_the_web/building_up_a_basic_demo_with_a-frame/shapes.png b/files/en-us/games/techniques/3d_on_the_web/building_up_a_basic_demo_with_a-frame/shapes.png deleted file mode 100644 index bbb010e0b82de18..000000000000000 Binary files a/files/en-us/games/techniques/3d_on_the_web/building_up_a_basic_demo_with_a-frame/shapes.png and /dev/null differ diff --git a/files/en-us/games/techniques/3d_on_the_web/building_up_a_basic_demo_with_babylon.js/cube.png b/files/en-us/games/techniques/3d_on_the_web/building_up_a_basic_demo_with_babylon.js/cube.png deleted file mode 100644 index 50d04e3e31d430f..000000000000000 Binary files a/files/en-us/games/techniques/3d_on_the_web/building_up_a_basic_demo_with_babylon.js/cube.png and /dev/null differ diff --git a/files/en-us/games/techniques/3d_on_the_web/building_up_a_basic_demo_with_babylon.js/index.md b/files/en-us/games/techniques/3d_on_the_web/building_up_a_basic_demo_with_babylon.js/index.md index 612de14e9c19ad4..3bb61f2ee844951 100644 --- a/files/en-us/games/techniques/3d_on_the_web/building_up_a_basic_demo_with_babylon.js/index.md +++ b/files/en-us/games/techniques/3d_on_the_web/building_up_a_basic_demo_with_babylon.js/index.md @@ -205,9 +205,9 @@ const boxMaterial = new BABYLON.StandardMaterial("material", scene); boxMaterial.emissiveColor = new BABYLON.Color3(0, 0.58, 0.86); box.material = boxMaterial; -const renderLoop = function () { +function renderLoop() { scene.render(); -}; +} engine.runRenderLoop(renderLoop); ``` @@ -367,13 +367,13 @@ cylinderMaterial.emissiveColor = new BABYLON.Color3(1, 0.58, 0); cylinder.material = cylinderMaterial; let t = 0; -const renderLoop = function () { +function renderLoop() { scene.render(); t -= 0.01; box.rotation.y = t * 2; torus.scaling.z = Math.abs(Math.sin(t * 2)) + 0.5; cylinder.position.y = Math.sin(t * 3); -}; +} engine.runRenderLoop(renderLoop); ``` diff --git a/files/en-us/games/techniques/3d_on_the_web/building_up_a_basic_demo_with_babylon.js/shapes.png b/files/en-us/games/techniques/3d_on_the_web/building_up_a_basic_demo_with_babylon.js/shapes.png deleted file mode 100644 index 855d4e53f7c4a63..000000000000000 Binary files a/files/en-us/games/techniques/3d_on_the_web/building_up_a_basic_demo_with_babylon.js/shapes.png and /dev/null differ diff --git a/files/en-us/games/techniques/3d_on_the_web/building_up_a_basic_demo_with_playcanvas/editor/index.md b/files/en-us/games/techniques/3d_on_the_web/building_up_a_basic_demo_with_playcanvas/editor/index.md index d44ce90accda428..0fdcfdb49a08e8b 100644 --- a/files/en-us/games/techniques/3d_on_the_web/building_up_a_basic_demo_with_playcanvas/editor/index.md +++ b/files/en-us/games/techniques/3d_on_the_web/building_up_a_basic_demo_with_playcanvas/editor/index.md @@ -110,7 +110,7 @@ Animating 3D models might be considered an [advanced](https://developer.playcanv If you double click on it, you'll be moved to a code editor. As you can see, the file contains some boilerplate code already: ```js -pc.script.create("boxAnimation", function (app) { +pc.script.create("boxAnimation", (app) => { class BoxAnimation { constructor(entity) { this.entity = entity; diff --git a/files/en-us/games/techniques/3d_on_the_web/building_up_a_basic_demo_with_playcanvas/engine/cube-playcanvas.png b/files/en-us/games/techniques/3d_on_the_web/building_up_a_basic_demo_with_playcanvas/engine/cube-playcanvas.png deleted file mode 100644 index 09fe944ef049a6b..000000000000000 Binary files a/files/en-us/games/techniques/3d_on_the_web/building_up_a_basic_demo_with_playcanvas/engine/cube-playcanvas.png and /dev/null differ diff --git a/files/en-us/games/techniques/3d_on_the_web/building_up_a_basic_demo_with_playcanvas/engine/index.md b/files/en-us/games/techniques/3d_on_the_web/building_up_a_basic_demo_with_playcanvas/engine/index.md index 4815cc9ba185561..c24ae4040f753ba 100644 --- a/files/en-us/games/techniques/3d_on_the_web/building_up_a_basic_demo_with_playcanvas/engine/index.md +++ b/files/en-us/games/techniques/3d_on_the_web/building_up_a_basic_demo_with_playcanvas/engine/index.md @@ -148,7 +148,7 @@ The code above assign a dark grey ambient light for the whole scene. The box loo ## Material -This example uses a material called [Standard material](https://api.playcanvas.com/classes/Engine.StandardMaterial.html), which is the main, general purpose material that is most often used for rendering. +This example uses a material called [Standard material](https://api.playcanvas.com/engine/classes/StandardMaterial.html), which is the main, general purpose material that is most often used for rendering. Add the following lines to your code: ```js @@ -208,7 +208,7 @@ boxMaterial.diffuse.set(0, 0.58, 0.86); boxMaterial.update(); box.model.model.meshInstances[0].material = boxMaterial; -window.addEventListener("resize", function () { +window.addEventListener("resize", () => { app.resizeCanvas(canvas.width, canvas.height); }); ``` @@ -393,7 +393,7 @@ cone.model.model.meshInstances[0].material = coneMaterial; // Animate shapes let timer = 0; -app.on("update", function (deltaTime) { +app.on("update", (deltaTime) => { timer += deltaTime; box.rotate(deltaTime * 10, deltaTime * 20, deltaTime * 3); cylinder.setLocalScale(1, Math.abs(Math.sin(timer)), 1); diff --git a/files/en-us/games/techniques/3d_on_the_web/building_up_a_basic_demo_with_playcanvas/engine/playcanvas-github.png b/files/en-us/games/techniques/3d_on_the_web/building_up_a_basic_demo_with_playcanvas/engine/playcanvas-github.png deleted file mode 100644 index ec4463681ebc535..000000000000000 Binary files a/files/en-us/games/techniques/3d_on_the_web/building_up_a_basic_demo_with_playcanvas/engine/playcanvas-github.png and /dev/null differ diff --git a/files/en-us/games/techniques/3d_on_the_web/building_up_a_basic_demo_with_playcanvas/engine/shapes-playcanvas.png b/files/en-us/games/techniques/3d_on_the_web/building_up_a_basic_demo_with_playcanvas/engine/shapes-playcanvas.png deleted file mode 100644 index cdae89f2a032cf2..000000000000000 Binary files a/files/en-us/games/techniques/3d_on_the_web/building_up_a_basic_demo_with_playcanvas/engine/shapes-playcanvas.png and /dev/null differ diff --git a/files/en-us/games/techniques/3d_on_the_web/building_up_a_basic_demo_with_playcanvas/index.md b/files/en-us/games/techniques/3d_on_the_web/building_up_a_basic_demo_with_playcanvas/index.md index c1109889768fd25..a456dbf365285e3 100644 --- a/files/en-us/games/techniques/3d_on_the_web/building_up_a_basic_demo_with_playcanvas/index.md +++ b/files/en-us/games/techniques/3d_on_the_web/building_up_a_basic_demo_with_playcanvas/index.md @@ -6,7 +6,7 @@ page-type: guide {{GamesSidebar}} -**PlayCanvas** is a popular 3D WebGL game engine, originally created by Will Eastcott and Dave Evans. It is [open sourced on GitHub](https://github.com/playcanvas/engine), with an [editor](https://developer.playcanvas.com/en/user-manual/designer/) available online and good [documentation](https://developer.playcanvas.com/en/). The online editor is free for public projects with up to two team members, but there are also [paid plans](https://playcanvas.com/plans) if you'd like to run a commercial private project with more developers. +**PlayCanvas** is a popular 3D WebGL game engine, originally created by Will Eastcott and Dave Evans. It is [open sourced on GitHub](https://github.com/playcanvas/engine), with an [editor](https://developer.playcanvas.com/user-manual/editor/) available online and good [documentation](https://developer.playcanvas.com/en/). The online editor is free for public projects with up to two team members, but there are also [paid plans](https://playcanvas.com/plans) if you'd like to run a commercial private project with more developers. ![PlayCanvas website.](playcanvas-cover.png) diff --git a/files/en-us/games/techniques/3d_on_the_web/building_up_a_basic_demo_with_three.js/cube.png b/files/en-us/games/techniques/3d_on_the_web/building_up_a_basic_demo_with_three.js/cube.png deleted file mode 100644 index f4ab5d0ff6c9e21..000000000000000 Binary files a/files/en-us/games/techniques/3d_on_the_web/building_up_a_basic_demo_with_three.js/cube.png and /dev/null differ diff --git a/files/en-us/games/techniques/3d_on_the_web/building_up_a_basic_demo_with_three.js/index.md b/files/en-us/games/techniques/3d_on_the_web/building_up_a_basic_demo_with_three.js/index.md index 57541c1be4d272a..1c0d3d12b42309d 100644 --- a/files/en-us/games/techniques/3d_on_the_web/building_up_a_basic_demo_with_three.js/index.md +++ b/files/en-us/games/techniques/3d_on_the_web/building_up_a_basic_demo_with_three.js/index.md @@ -122,7 +122,7 @@ There are other types of camera available (Cube, Orthographic), but the simplest - The `z` position, with the value of 50 units, is the distance between the camera and the center of the scene on the `z` axis. Here we're moving the camera back, so the objects in the scene can be viewed. 50 feels about right. It's not too near, or too far, and the sizes of the objects allow them to stay on the scene, within the given field of view. The `x` and `y` values, if not specified, will default to 0. You should experiment with these values and see how they change what you see in the scene. -The distance values (e.g. for the camera z position) are unitless, and can be anything you deem suitable for your scene: millimeters, meters, feet, or miles. It's up to you. +The distance values (e.g., for the camera z position) are unitless, and can be anything you deem suitable for your scene: millimeters, meters, feet, or miles. It's up to you. ## Rendering the scene diff --git a/files/en-us/games/techniques/3d_on_the_web/building_up_a_basic_demo_with_three.js/shapes.png b/files/en-us/games/techniques/3d_on_the_web/building_up_a_basic_demo_with_three.js/shapes.png deleted file mode 100644 index 56cfc99d9e85c85..000000000000000 Binary files a/files/en-us/games/techniques/3d_on_the_web/building_up_a_basic_demo_with_three.js/shapes.png and /dev/null differ diff --git a/files/en-us/games/techniques/3d_on_the_web/glsl_shaders/index.md b/files/en-us/games/techniques/3d_on_the_web/glsl_shaders/index.md index d99bbe3c545d205..2e552fc0bb0b47e 100644 --- a/files/en-us/games/techniques/3d_on_the_web/glsl_shaders/index.md +++ b/files/en-us/games/techniques/3d_on_the_web/glsl_shaders/index.md @@ -1,5 +1,5 @@ --- -title: GLSL Shaders +title: GLSL shaders slug: Games/Techniques/3D_on_the_web/GLSL_Shaders page-type: guide --- @@ -50,14 +50,14 @@ Here's the HTML structure we will use. <meta charset="utf-8" /> <title>MDN Games: Shaders demo</title> <style> - body { + html, + body, + canvas { margin: 0; padding: 0; - font-size: 0; - } - canvas { width: 100%; height: 100%; + font-size: 0; } </style> <script src="three.min.js"></script> diff --git a/files/en-us/games/techniques/3d_on_the_web/webxr/index.md b/files/en-us/games/techniques/3d_on_the_web/webxr/index.md index faad651185c7077..da11e229fa21f4d 100644 --- a/files/en-us/games/techniques/3d_on_the_web/webxr/index.md +++ b/files/en-us/games/techniques/3d_on_the_web/webxr/index.md @@ -17,11 +17,6 @@ With the popularity of existing VR headsets such as Meta Quest, Valve Index, and ![Three different VR devices: the Meta Quest 3, the Valve Index, and the Sony PSVR2.](hmds.jpg) -### Development of WebVR - -The [WebVR spec](https://mozvr.github.io/webvr-spec/webvr.html) is being replaced by the [WebXR Device API](/en-US/docs/Web/API/WebXR_Device_API). WebVR may still be available in some browsers while WebXR is finalized. -For more info, see the [WebVR.info](https://webvr.info/) website. - ## The WebXR API The core of any WebXR experience is built on top of two foundational concepts: diff --git a/files/en-us/games/techniques/async_scripts/index.md b/files/en-us/games/techniques/async_scripts/index.md index df6346cf8a2ea41..9499c1f53a22f9b 100644 --- a/files/en-us/games/techniques/async_scripts/index.md +++ b/files/en-us/games/techniques/async_scripts/index.md @@ -32,7 +32,7 @@ Two common situations in which a script is _not_ async (as [defined by the HTML ```html <script async> - code(); + // Inline JavaScript code </script> ``` @@ -40,7 +40,7 @@ and ```js const script = document.createElement("script"); -script.textContent = "code()"; +script.textContent = "// Inline JavaScript code"; document.body.appendChild(script); ``` diff --git a/files/en-us/games/techniques/audio_for_web_games/index.md b/files/en-us/games/techniques/audio_for_web_games/index.md index d2593d6b52808bd..f305223640916f8 100644 --- a/files/en-us/games/techniques/audio_for_web_games/index.md +++ b/files/en-us/games/techniques/audio_for_web_games/index.md @@ -432,7 +432,7 @@ This is especially useful in a three-dimensional environment rendered using WebG ## See also - [Web Audio API on MDN](/en-US/docs/Web/API/Web_Audio_API) -- [`<audio>` on MDN](/en-US/docs/Web/HTML/Element/audio) +- [`<audio>` on MDN](/en-US/docs/Web/HTML/Reference/Elements/audio) - [Songs of Diridum: Pushing the Web Audio API to Its Limits](https://hacks.mozilla.org/2013/10/songs-of-diridum-pushing-the-web-audio-api-to-its-limits/) - [Making HTML5 Audio Actually Work on Mobile](https://pupunzi.open-lab.com/2013/03/13/making-html5-audio-actually-work-on-mobile/) - [Audio Sprites (and fixes for iOS)](https://remysharp.com/2010/12/23/audio-sprites/) diff --git a/files/en-us/games/techniques/control_mechanisms/desktop_with_gamepad/index.md b/files/en-us/games/techniques/control_mechanisms/desktop_with_gamepad/index.md index f75e1fb5aa5bdf8..e09a293077a6c5a 100644 --- a/files/en-us/games/techniques/control_mechanisms/desktop_with_gamepad/index.md +++ b/files/en-us/games/techniques/control_mechanisms/desktop_with_gamepad/index.md @@ -14,7 +14,7 @@ The Gamepad API gives you the ability to connect a gamepad to your computer and ## API status, browser and hardware support -The [Gamepad API](/en-US/docs/Web/API/Gamepad_API) is still in Working Draft status, although browser support is already quite good — around 63% global coverage, according to [caniuse.com](https://caniuse.com/#search=gamepad). The list of supported devices is also quite extensive — most popular gamepads (e.g. XBox 360 or PS3) should be suitable for web implementations. +The [Gamepad API](/en-US/docs/Web/API/Gamepad_API) is still in Working Draft status, although browser support is already quite good — around 63% global coverage, according to [caniuse.com](https://caniuse.com/#search=gamepad). The list of supported devices is also quite extensive — most popular gamepads (e.g., XBox 360 or PS3) should be suitable for web implementations. ## Pure JavaScript approach @@ -47,9 +47,9 @@ To update the state of the gamepad's currently pressed buttons we will need a fu function gamepadUpdateHandler() { buttonsPressed = []; if (controller.buttons) { - for (let b = 0; b < controller.buttons.length; b++) { - if (controller.buttons[b].pressed) { - buttonsPressed.push(b); + for (const [i, button] of controller.buttons.entries()) { + if (button.pressed) { + buttonsPressed.push(i); } } } @@ -60,17 +60,11 @@ We first reset the `buttonsPressed` array to get it ready to store the latest in ```js function gamepadButtonPressedHandler(button) { - let press = false; - for (let i = 0; i < buttonsPressed.length; i++) { - if (buttonsPressed[i] === button) { - press = true; - } - } - return press; + return buttonsPressed.includes(button); } ``` -The function takes a button as a parameter; in the loop it checks if the given button's number is among the currently pressed buttons available in the `buttonsPressed` array. If it is, then the function returns `true`; `false` otherwise. +The function takes a button index as a parameter; it checks if `buttonsPressed` contains the button we are looking for, and returns `true` if it does. This checks if a button is pressed or not. Next, in the `draw()` function we do two things — execute the `gamepadUpdateHandler()` function to get the current state of pressed buttons on every frame, and use the `gamepadButtonPressedHandler()` function to check the buttons we are interested to see whether they are pressed, and do something if they are: @@ -105,7 +99,7 @@ function draw() { In this case, we are checking the four D-Pad buttons (0-3) and the A button (11). > [!NOTE] -> Please remember that different devices may have different key mappings, i.e. the D-Pad Right button have an index of 3 on the wireless XBox 360, but may have a different one on another device. +> Please remember that different devices may have different key mappings, i.e., the D-Pad Right button have an index of 3 on the wireless XBox 360, but may have a different one on another device. You could also create a helper function that would assign proper names to the listed buttons, so for example instead of checking out if `gamepadButtonPressedHandler(3)` is pressed, you could do a more descriptive check: `gamepadButtonPressedHandler('DPad-Right')`. @@ -152,49 +146,60 @@ The `pressed()` function gets the input data and sets the information about it i After the gamepad is connected, the information about the controller is stored in the object: ```js -connect(event) { +const GamepadAPI = { + // … + connect(event) { GamepadAPI.controller = event.gamepad; GamepadAPI.active = true; -}, + }, + // … +}; ``` The `disconnect` function removes the information from the object: ```js -disconnect(event) { +const GamepadAPI = { + // … + disconnect(event) { delete GamepadAPI.controller; GamepadAPI.active = false; -}, + }, +}; ``` The `update()` function is executed in the update loop of the game on every frame, so it contains the latest information on the pressed buttons: ```js -update() { - GamepadAPI.buttons.cache = []; - for (let k = 0; k < GamepadAPI.buttons.status.length; k++) { - GamepadAPI.buttons.cache[k] = GamepadAPI.buttons.status[k]; - } - GamepadAPI.buttons.status = []; - const c = GamepadAPI.controller || {}; - const pressed = []; - if (c.buttons) { - for (let b = 0; b < c.buttons.length; b++) { - if (c.buttons[b].pressed) { - pressed.push(GamepadAPI.buttons.layout[b]); +const GamepadAPI = { + // … + update() { + GamepadAPI.buttons.cache = []; + for (let k = 0; k < GamepadAPI.buttons.status.length; k++) { + GamepadAPI.buttons.cache[k] = GamepadAPI.buttons.status[k]; + } + GamepadAPI.buttons.status = []; + const c = GamepadAPI.controller || {}; + const pressed = []; + if (c.buttons) { + for (let b = 0; b < c.buttons.length; b++) { + if (c.buttons[b].pressed) { + pressed.push(GamepadAPI.buttons.layout[b]); + } } } - } - const axes = []; - if (c.axes) { - for (let a = 0; a < c.axes.length; a++) { - axes.push(c.axes[a].toFixed(2)); + const axes = []; + if (c.axes) { + for (const ax of c.axes) { + axes.push(ax.toFixed(2)); + } } - } - GamepadAPI.axes.status = axes; - GamepadAPI.buttons.status = pressed; - return pressed; -}, + GamepadAPI.axes.status = axes; + GamepadAPI.buttons.status = pressed; + return pressed; + }, + // … +}; ``` The function above clears the buttons cache, and copies their status from the previous frame to the cache. Next, the button status is cleared and the new information is added. The same goes for the axes' information — looping through axes adds the values to the array. Received values are assigned to the proper objects and returns the pressed info for debugging purposes. @@ -202,25 +207,27 @@ The function above clears the buttons cache, and copies their status from the pr The `button.pressed()` function detects the actual button presses: ```js -pressed(button, hold) { - let newPress = false; - for (let i = 0; i < GamepadAPI.buttons.status.length; i++) { - if (GamepadAPI.buttons.status[i] === button) { - newPress = true; - if (!hold) { - for (let j = 0; j < GamepadAPI.buttons.cache.length; j++) { - if (GamepadAPI.buttons.cache[j] === button) { - newPress = false; - } - } +const GamepadAPI = { + // … + buttons: { + // … + pressed(button, hold) { + let newPress = false; + if (GamepadAPI.buttons.status.includes(button)) { + newPress = true; } - } - } - return newPress; -}, + if (!hold && GamepadAPI.buttons.cache.includes(button)) { + newPress = false; + } + return newPress; + }, + // … + }, + // … +}; ``` -It loops through pressed buttons and if the button we're looking for is pressed, then the corresponding boolean variable is set to `true`. If we want to check the button is not held already (so it's a new press), then looping through the cached states from the previous frame does the job — if the button was already pressed, then we ignore the new press and set it to `false`. +It checks if the button we're looking for is pressed, and if so, the corresponding boolean variable is set to `true`. If we want to check the button is not held already (so it's a new press), then checking the cached states from the previous frame does the job — if the button was already pressed, then we ignore the new press and set it to `false`. ## Implementation @@ -229,9 +236,9 @@ We now know what the `GamepadAPI` object looks like and what variables and funct The `textGamepad` object holds the text saying a gamepad has been connected, and is hidden by default. Here's the code we've prepared in the `create()` function that is executed once when the new state is created: ```js -create() { +function create() { // … - const message = 'Gamepad connected! Press Y for controls'; + const message = "Gamepad connected! Press Y for controls"; const textGamepad = this.add.text(0, 0, message); textGamepad.visible = false; } @@ -240,20 +247,20 @@ create() { In the `update()` function, which is executed every frame, we can wait until the controller is actually connected, so the proper text can be shown. Then we can keep the track of the information about pressed buttons by using the `Gamepad.update()` method, and react to the given information: ```js -update() { +function update() { // … if (GamepadAPI.active) { this.textGamepad.visible = true; GamepadAPI.update(); - if (GamepadAPI.buttons.pressed('Start')) { + if (GamepadAPI.buttons.pressed("Start")) { // start the game } - if (GamepadAPI.buttons.pressed('X')) { + if (GamepadAPI.buttons.pressed("X")) { // turn on/off the sounds } - this.screenGamepadHelp.visible = GamepadAPI.buttons.pressed('Y', 'hold'); + this.screenGamepadHelp.visible = GamepadAPI.buttons.pressed("Y", "hold"); } } ``` @@ -267,19 +274,19 @@ When pressing the `Start` button the relevant function will be called to begin t When the game is started, some introductory text is shown that shows you available controls — we are already detecting if the game is launched on desktop or mobile then showing a relevant message for the device, but we can go even further, to allow for the presence of a gamepad: ```js -create() { +function create() { // … if (this.game.device.desktop) { if (GamepadAPI.active) { - moveText = 'DPad or left Stick\nto move'; - shootText = 'A to shoot,\nY for controls'; + moveText = "DPad or left Stick\nto move"; + shootText = "A to shoot,\nY for controls"; } else { - moveText = 'Arrow keys\nor WASD to move'; - shootText = 'X or Space\nto shoot'; + moveText = "Arrow keys\nor WASD to move"; + shootText = "X or Space\nto shoot"; } } else { - moveText = 'Tap and hold to move'; - shootText = 'Tap to shoot'; + moveText = "Tap and hold to move"; + shootText = "Tap to shoot"; } } ``` diff --git a/files/en-us/games/techniques/control_mechanisms/index.md b/files/en-us/games/techniques/control_mechanisms/index.md index bb382b8cc33a29e..7ceea97eadf459d 100644 --- a/files/en-us/games/techniques/control_mechanisms/index.md +++ b/files/en-us/games/techniques/control_mechanisms/index.md @@ -31,9 +31,15 @@ Every state has its own default methods: `preload()`, `create()`, and `update()` For example, you can define a button in the `create()` function: ```js -create() { +function create() { // … - const buttonEnclave = this.add.button(10, 10, 'logo-enclave', this.clickEnclave, this); + const buttonEnclave = this.add.button( + 10, + 10, + "logo-enclave", + this.clickEnclave, + this, + ); // … } ``` @@ -41,10 +47,10 @@ create() { It will be created once at the start of the game, and will execute `this.clickEnclave()` action assigned to it when clicked, but you can also use the mouse's pointer value in the `update()` function to make an action: ```js -update() { +function update() { // … if (this.game.input.mousePointer.isDown) { - // do something + // do something } // … } diff --git a/files/en-us/games/techniques/control_mechanisms/other/index.md b/files/en-us/games/techniques/control_mechanisms/other/index.md index 463c0375a3bbde1..fc73802eb270b8c 100644 --- a/files/en-us/games/techniques/control_mechanisms/other/index.md +++ b/files/en-us/games/techniques/control_mechanisms/other/index.md @@ -170,6 +170,7 @@ There's even a [Cylon.js-supported Makey Button functionality](https://cylonjs.c ```js const Cylon = require("cylon"); + Cylon.robot({ connections: { arduino: { adaptor: "firmata", port: "/dev/ttyACM0" }, diff --git a/files/en-us/games/techniques/controls_gamepad_api/index.md b/files/en-us/games/techniques/controls_gamepad_api/index.md index a390fedfe9fad0b..6be6b16cb6e9a6c 100644 --- a/files/en-us/games/techniques/controls_gamepad_api/index.md +++ b/files/en-us/games/techniques/controls_gamepad_api/index.md @@ -1,5 +1,6 @@ --- title: Implementing controls using the Gamepad API +short-title: Using the Gamepad API slug: Games/Techniques/Controls_Gamepad_API page-type: guide --- @@ -56,12 +57,16 @@ const gamepadAPI = { The `buttons` array contains the Xbox 360 button layout: -```js -buttons: [ - 'DPad-Up','DPad-Down','DPad-Left','DPad-Right', - 'Start','Back','Axis-Left','Axis-Right', - 'LB','RB','Power','A','B','X','Y', -], +```js-nolint +const gamepadAPI = { + // … + buttons: [ + "DPad-Up", "DPad-Down", "DPad-Left", "DPad-Right", + "Start", "Back", "Axis-Left", "Axis-Right", + "LB", "RB", "Power", "A", "B", "X", "Y", + ], + // … +}; ``` This can be different for other types of gamepads like the PS3 controller (or a no-name, generic one), so you have to be careful and not just assume the button you're expecting will be the same button you'll actually get. Next, we set up two event listeners to get the data: @@ -76,21 +81,27 @@ Due to security policy, you have to interact with the controller first while the Both functions are fairly simple: ```js -connect(evt) { - gamepadAPI.controller = evt.gamepad; - gamepadAPI.turbo = true; - console.log('Gamepad connected.'); -}, +const gamepadAPI = { + // … + connect(evt) { + gamepadAPI.controller = evt.gamepad; + gamepadAPI.turbo = true; + console.log("Gamepad connected."); + }, +}; ``` The `connect()` function takes the event as a parameter and assigns the `gamepad` object to the `gamepadAPI.controller` variable. We are using only one gamepad for this game, so it's a single object instead of an array of gamepads. We then set the `turbo` property to `true`. (We could use the `gamepad.connected` boolean for this purpose, but we wanted to have a separate variable for turning on Turbo mode without needing to have a gamepad connected, for reasons explained above.) ```js -disconnect(evt) { - gamepadAPI.turbo = false; - delete gamepadAPI.controller; - console.log('Gamepad disconnected.'); -}, +const gamepadAPI = { + // … + disconnect(evt) { + gamepadAPI.turbo = false; + delete gamepadAPI.controller; + console.log("Gamepad disconnected."); + }, +}; ``` The `disconnect` function sets the `gamepad.turbo property` to `false` and removes the variable containing the gamepad object. @@ -113,46 +124,49 @@ The `index` variable is useful if we're connecting more than one controller and Beside `connect()` and `disconnect()`, there are two more methods in the `gamepadAPI` object: `update()` and `buttonPressed()`. `update()` is executed on every frame inside the game loop, to update the actual status of the gamepad object regularly: ```js -update() { - // Clear the buttons cache - gamepadAPI.buttonsCache = []; - - // Move the buttons status from the previous frame to the cache - for (let k = 0; k < gamepadAPI.buttonsStatus.length; k++) { - gamepadAPI.buttonsCache[k] = gamepadAPI.buttonsStatus[k]; - } +const gamepadAPI = { + // … + update() { + // Clear the buttons cache + gamepadAPI.buttonsCache = []; + + // Move the buttons status from the previous frame to the cache + for (let k = 0; k < gamepadAPI.buttonsStatus.length; k++) { + gamepadAPI.buttonsCache[k] = gamepadAPI.buttonsStatus[k]; + } - // Clear the buttons status - gamepadAPI.buttonsStatus = []; + // Clear the buttons status + gamepadAPI.buttonsStatus = []; - // Get the gamepad object - const c = gamepadAPI.controller || {}; + // Get the gamepad object + const c = gamepadAPI.controller || {}; - // Loop through buttons and push the pressed ones to the array - const pressed = []; - if (c.buttons) { - for (let b = 0; b < c.buttons.length; b++) { - if (c.buttons[b].pressed) { - pressed.push(gamepadAPI.buttons[b]); + // Loop through buttons and push the pressed ones to the array + const pressed = []; + if (c.buttons) { + for (let b = 0; b < c.buttons.length; b++) { + if (c.buttons[b].pressed) { + pressed.push(gamepadAPI.buttons[b]); + } } } - } - // Loop through axes and push their values to the array - const axes = []; - if (c.axes) { - for (let a = 0; a < c.axes.length; a++) { - axes.push(c.axes[a].toFixed(2)); + // Loop through axes and push their values to the array + const axes = []; + if (c.axes) { + for (const ax of c.axes) { + axes.push(ax.toFixed(2)); + } } - } - // Assign received values - gamepadAPI.axesStatus = axes; - gamepadAPI.buttonsStatus = pressed; + // Assign received values + gamepadAPI.axesStatus = axes; + gamepadAPI.buttonsStatus = pressed; - // Return buttons for debugging purposes - return pressed; -}, + // Return buttons for debugging purposes + return pressed; + }, +}; ``` On every frame, `update()` saves buttons pressed during the previous frame to the `buttonsCache` array and takes fresh ones from the `gamepadAPI.controller` object. Then it loops through buttons and axes to get their actual states and values. @@ -162,31 +176,22 @@ On every frame, `update()` saves buttons pressed during the previous frame to th The `buttonPressed()` method is also placed in the main game loop to listen for button presses. It takes two parameters — the button we want to listen to and the (optional) way to tell the game that holding the button is accepted. Without it you'd have to release the button and press it again to have the desired effect. ```js -buttonPressed(button, hold) { - let newPress = false; - - // Loop through pressed buttons - for (let i = 0; i < gamepadAPI.buttonsStatus.length; i++) { - // If we found the button we're looking for - if (gamepadAPI.buttonsStatus[i] === button) { - // Set the boolean variable to true +const gamepadAPI = { + // … + buttonPressed(button, hold) { + let newPress = false; + if (GamepadAPI.buttons.status.includes(button)) { newPress = true; - - // If we want to check the single press - if (!hold) { - // Loop through the cached states from the previous frame - for (let j = 0; j < gamepadAPI.buttonsCache.length; j++) { - // If the button was already pressed, ignore new press - newPress = (gamepadAPI.buttonsCache[j] !== button); - } - } } - } - return newPress; -}, + if (!hold && GamepadAPI.buttons.cache.includes(button)) { + newPress = false; + } + return newPress; + }, +}; ``` -There are two types of action to consider for a button: a single press and a hold. The `newPress` boolean variable will indicate whether there's a new press of a button or not. Next, we loop through the array of pressed buttons — if the given button is the same as the one we're looking for, the `newPress` variable is set to `true`. To check if the press is a new one, so the player is not holding the key, we loop through the cached states of the buttons from the previous frame of the game loop. If we find it there it means that the button is being held, so there's no new press. In the end the `newPress` variable is returned. The `buttonPressed` function is used in the update loop of the game like this: +There are two types of action to consider for a button: a single press and a hold. The `newPress` boolean variable will indicate whether there's a new press of a button or not. Next, we check the array of pressed buttons — if the given button is in here, the `newPress` variable is set to `true`. To check if the press is a new one, so the player is not holding the key, we check the cached states of the buttons from the previous frame of the game loop. If we find it there it means that the button is being held, so there's no new press. In the end the `newPress` variable is returned. The `buttonPressed` function is used in the update loop of the game like this: ```js if (gamepadAPI.turbo) { @@ -228,7 +233,7 @@ The {{domxref("Navigator.getGamepads()")}} method has been updated with [a longe The mapping type is now an enumerable object instead of a string: -```ts +```webidl enum GamepadMappingType { "", "standard", diff --git a/files/en-us/games/techniques/crisp_pixel_art_look/index.md b/files/en-us/games/techniques/crisp_pixel_art_look/index.md index 2bad74c4f892853..683e126c1a332ae 100644 --- a/files/en-us/games/techniques/crisp_pixel_art_look/index.md +++ b/files/en-us/games/techniques/crisp_pixel_art_look/index.md @@ -1,5 +1,6 @@ --- title: Crisp pixel art look with image-rendering +short-title: Image rendering for pixel art slug: Games/Techniques/Crisp_pixel_art_look page-type: guide --- @@ -88,4 +89,4 @@ This code used together produces the following result: {{ EmbedLiveSample('An_example', '100%', 520) }} > [!NOTE] -> Canvas content is not accessible to screen readers. Include descriptive text as the value of the [`aria-label`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-label) attribute directly on the canvas element itself or include fallback content placed within the opening and closing canvas tag. Canvas content is not part of the DOM, but nested fallback content is. +> Canvas content is not accessible to screen readers. Include descriptive text as the value of the [`aria-label`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-label) attribute directly on the canvas element itself or include fallback content placed within the opening and closing canvas tag. Canvas content is not part of the DOM, but nested fallback content is. diff --git a/files/en-us/games/techniques/index.md b/files/en-us/games/techniques/index.md index 0472d80f6ef5a8f..20d1731a0e56736 100644 --- a/files/en-us/games/techniques/index.md +++ b/files/en-us/games/techniques/index.md @@ -8,15 +8,4 @@ page-type: landing-page This page lists essential core techniques for anyone wanting to develop games using open web technologies. -- [Using async scripts for asm.js](/en-US/docs/Games/Techniques/Async_scripts) - - : Especially when creating medium to large-sized games, async scripts are an essential technique to take advantage of, so that your game's JavaScript can be compiled off the main thread and be cached for future game running, resulting in a significant performance improvement for your users. This article explains how. -- [Optimizing startup performance](/en-US/docs/Web/Performance/Guides/Optimizing_startup_performance) - - : How to make sure your game starts up quickly, smoothly, and without appearing to lock up the user's browser or device. -- [Using WebRTC peer-to-peer data channels](/en-US/docs/Games/Techniques/WebRTC_data_channels) - - : In addition to providing support for audio and video communication, WebRTC lets you set up peer-to-peer data channels to exchange text or binary data actively between your players. This article explains what this can do for you, and shows how to use libraries that make this easy. -- [Audio for Web Games](/en-US/docs/Games/Techniques/Audio_for_Web_Games) - - : Audio is an important part of any game — it adds feedback and atmosphere. Web-based audio is maturing fast, but there are still many browser differences to negotiate. This article provides a detailed guide to implementing audio for web games, looking at what works currently across as wide a range of platforms as possible. -- [2D collision detection](/en-US/docs/Games/Techniques/2D_collision_detection) - - : A concise introduction to collision detection in 2D games. -- [Tilemaps](/en-US/docs/Games/Techniques/Tilemaps) - - : Tiles are a very popular technique in 2D games for building the game world. These articles provide an introduction to tilemaps and how to implement them with the Canvas API. +{{SubpagesWithSummaries}} diff --git a/files/en-us/games/techniques/tilemaps/square_tilemaps_implementation_colon__static_maps/index.md b/files/en-us/games/techniques/tilemaps/square_tilemaps_implementation_colon__static_maps/index.md index fa36a0b03ec3b1e..04b2f5474fb0024 100644 --- a/files/en-us/games/techniques/tilemaps/square_tilemaps_implementation_colon__static_maps/index.md +++ b/files/en-us/games/techniques/tilemaps/square_tilemaps_implementation_colon__static_maps/index.md @@ -37,7 +37,7 @@ To store that map data, we can use a plain object or a custom class. For the sak - `tiles`: A 1-dimensional array containing the visual grid. - `getTile()`: A helper method that gets the tile index in a certain position. -`tiles` contains the actual visual map data. We are representing the tiles with indices, assigned to the tiles dependent on their position in the atlas (e.g. `0` for the left-most tile.) However, we must account for **empty tiles**, since they are crucial for implementing layers — empty tiles are usually assigned a negative index value, `0`, or a null value. In these examples, empty tiles will be represented by index `0`, so we will shift the indices of the atlases by one (and thus the first tile of the atlas will be assigned index `1`, the second index `2`, etc.) +`tiles` contains the actual visual map data. We are representing the tiles with indices, assigned to the tiles dependent on their position in the atlas (e.g., `0` for the left-most tile.) However, we must account for **empty tiles**, since they are crucial for implementing layers — empty tiles are usually assigned a negative index value, `0`, or a null value. In these examples, empty tiles will be represented by index `0`, so we will shift the indices of the atlases by one (and thus the first tile of the atlas will be assigned index `1`, the second index `2`, etc.) The `getTile()` helper method returns the tile contained at the specified column and row. If `tiles` were a 2D matrix, then the returned value would just be `tiles[column][row]`. However, it's usually more common to represent the grid with a 1-dimensional array. In this case, we need to map the column and row to an array index: diff --git a/files/en-us/games/tools/index.md b/files/en-us/games/tools/index.md index 134d21bd8ebe69c..8314e40fb8b7ef1 100644 --- a/files/en-us/games/tools/index.md +++ b/files/en-us/games/tools/index.md @@ -21,3 +21,113 @@ On this page, you can find links to our game development tools articles, which e - Basic tools overview - [Shader editor](https://firefox-source-docs.mozilla.org/devtools-user/shader_editor/index.html) - Performance tools (still in production, estimated early 2014) + +## Web Technologies + +<table class="no-markdown standard-table"> + <caption>Web technologies in game development and their function</caption> + <thead> + <tr> + <th scope="col"><strong>Function</strong></th> + <th scope="col"><strong>Technology</strong></th> + </tr> + </thead> + <tbody> + <tr> + <td><strong>Audio</strong></td> + <td><a href="/en-US/docs/Web/API/Web_Audio_API">Web Audio API</a></td> + </tr> + <tr> + <td><strong>Graphics</strong></td> + <td> + <a href="/en-US/docs/Web/API/WebGL_API">WebGL</a> (<a + href="https://www.khronos.org/opengles/" + >OpenGL ES</a + > + 2.0) + </td> + </tr> + <tr> + <td><strong>Input</strong></td> + <td> + <a href="/en-US/docs/Web/API/Touch_events">Touch events</a>, + <a href="/en-US/docs/Web/API/Gamepad_API/Using_the_Gamepad_API" + >Gamepad API</a + >, device sensors, <a href="/en-US/docs/Web/API/WebRTC_API">WebRTC</a>, + <a href="/en-US/docs/Web/API/Fullscreen_API">Full Screen API</a>, + <a href="/en-US/docs/Web/API/Pointer_Lock_API">Pointer Lock API</a> + </td> + </tr> + <tr> + <td><strong>Language</strong></td> + <td> + <a href="/en-US/docs/Web/JavaScript">JavaScript</a> (or C/C++ using + <a href="https://github.com/emscripten-core/emscripten/wiki">Emscripten</a> to + compile to JavaScript) + </td> + </tr> + <tr> + <td><strong>Networking</strong></td> + <td> + <a href="/en-US/docs/Web/API/WebRTC_API">WebRTC</a> and/or + <a href="/en-US/docs/Web/API/WebSockets_API">WebSockets</a> + </td> + </tr> + <tr> + <td><strong>Storage</strong></td> + <td> + <a href="/en-US/docs/Web/API/IndexedDB_API">IndexedDB</a> or the "cloud" + </td> + </tr> + <tr> + <td><strong>Web</strong></td> + <td> + <a href="/en-US/docs/Web/HTML">HTML</a>, + <a href="/en-US/docs/Web/CSS">CSS</a>, + <a href="/en-US/docs/Web/SVG">SVG</a> (and much more!) + </td> + </tr> + </tbody> +</table> + +- [Fetch API](/en-US/docs/Web/API/Fetch_API) + - : Send and receive any kind of data you want from a Web server like downloading new game levels and artwork to transmitting non-real-time game status information back and forth. +- [Full Screen API](/en-US/docs/Web/API/Fullscreen_API) + - : Full screen gameplay. +- [Gamepad API](/en-US/docs/Web/API/Gamepad_API/Using_the_Gamepad_API) + - : Use gamepads or other game controllers. +- [HTML](/en-US/docs/Web/HTML) and [CSS](/en-US/docs/Web/CSS) + - : Build, style, and lay out your game's user interface. +- [HTML audio](/en-US/docs/Web/HTML/Reference/Elements/audio) + - : Easily play simple sound effects and music. +- [IndexedDB](/en-US/docs/Web/API/IndexedDB_API) + - : Store user data on their own computer or device. +- [JavaScript](/en-US/docs/Web/JavaScript) + - : Fast web programming language to write the code for your game. + To easily port your existing games [Emscripten](https://github.com/emscripten-core/emscripten/wiki) or [Asm.js](http://asmjs.org/spec/latest/) +- [Pointer Lock API](/en-US/docs/Web/API/Pointer_Lock_API) + - : Lock the mouse or other pointing device within your game's interface. +- [SVG](/en-US/docs/Web/SVG) (Scalable Vector Graphics) + - : Build vector graphics that scale smoothly regardless of the size or resolution of the user's display. +- [Typed Arrays](/en-US/docs/Web/JavaScript/Guide/Typed_arrays) + - : Access raw binary data from within JavaScript; Manipulate GL textures, game data, or anything else. +- [Web Audio API](/en-US/docs/Web/API/Web_Audio_API) + - : Control the playback, synthesis, and manipulation of audio in real time. +- [WebGL](/en-US/docs/Web/API/WebGL_API) + - : Create high-performance, hardware-accelerated 3D (and 2D) graphics. [OpenGL ES](https://www.khronos.org/opengles/) 2.0. +- [WebRTC](/en-US/docs/Web/API/WebRTC_API) + - : Real-Time Communications to control audio and video data, including teleconferencing and transmitting other application data back and forth between two users like chat. +- [WebSockets](/en-US/docs/Web/API/WebSockets_API) + - : Connect your app or site to a server to transmit data back and forth in real-time. Perfect for multiplayer gaming action, chat services, and so forth. +- [Web Workers](/en-US/docs/Web/API/Web_Workers_API/Using_web_workers) + - : Spawn background threads running their own JavaScript code for multicore processors. + +## Port native games to the Web + +If you are a native developer (for example writing games in C++), and you are interested in how you can port your games over to the Web, you should learn more about our [Emscripten](https://emscripten.org/index.html) tool — this is an LLVM to JavaScript compiler, which takes LLVM bytecode (e.g., generated from C/C++ using Clang, or from another language) and compiles that into [asm.js](/en-US/docs/Games/Tools/asm.js), which can be run on the Web. + +To get started, see: + +- [About Emscripten](https://emscripten.org/docs/introducing_emscripten/about_emscripten.html) for an introduction including high-level details. +- [Download and Install](https://emscripten.org/docs/getting_started/downloads.html) for installing the toolchain. +- [Emscripten Tutorial](https://emscripten.org/docs/getting_started/Tutorial.html) for a tutorial to teach you how to get started. diff --git a/files/en-us/games/tutorials/2d_breakout_game_phaser/win_the_game/index.md b/files/en-us/games/tutorials/2d_breakout_game_phaser/win_the_game/index.md index 6d774556e7978d1..5c6238d3ff14fab 100644 --- a/files/en-us/games/tutorials/2d_breakout_game_phaser/win_the_game/index.md +++ b/files/en-us/games/tutorials/2d_breakout_game_phaser/win_the_game/index.md @@ -22,20 +22,15 @@ function ballHitBrick(ball, brick) { score += 10; scoreText.setText(`Points: ${score}`); - let count_alive = 0; - for (let i = 0; i < bricks.children.length; i++) { - if (bricks.children[i].alive) { - count_alive++; - } - } - if (count_alive === 0) { + const countAlive = bricks.children.filter((b) => b.alive).length; + if (countAlive === 0) { alert("You won the game, congratulations!"); location.reload(); } } ``` -We loop through the bricks in the group using `bricks.children`, checking for the aliveness of each with each brick's `.alive()` method. If there are no more bricks left alive, then we show a winning message, restarting the game once the alert is dismissed. +We loop through the bricks in the group using `bricks.children`, checking for the aliveness of each with each brick's `.alive` property. If there are no more bricks left alive, then we show a winning message, restarting the game once the alert is dismissed. ## Compare your code diff --git a/files/en-us/games/tutorials/2d_breakout_game_pure_javascript/bounce_off_the_walls/index.md b/files/en-us/games/tutorials/2d_breakout_game_pure_javascript/bounce_off_the_walls/index.md index c5eb9d8612637d0..b778e72aab01314 100644 --- a/files/en-us/games/tutorials/2d_breakout_game_pure_javascript/bounce_off_the_walls/index.md +++ b/files/en-us/games/tutorials/2d_breakout_game_pure_javascript/bounce_off_the_walls/index.md @@ -149,9 +149,10 @@ function startGame() { setInterval(draw, 10); } -document.getElementById("runButton").addEventListener("click", function () { +const runButton = document.getElementById("runButton"); +runButton.addEventListener("click", () => { startGame(); - this.disabled = true; + runButton.disabled = true; }); ``` diff --git a/files/en-us/games/tutorials/2d_breakout_game_pure_javascript/build_the_brick_field/index.md b/files/en-us/games/tutorials/2d_breakout_game_pure_javascript/build_the_brick_field/index.md index 00cc07661732299..482ad609ae741d9 100644 --- a/files/en-us/games/tutorials/2d_breakout_game_pure_javascript/build_the_brick_field/index.md +++ b/files/en-us/games/tutorials/2d_breakout_game_pure_javascript/build_the_brick_field/index.md @@ -157,17 +157,17 @@ document.addEventListener("keydown", keyDownHandler, false); document.addEventListener("keyup", keyUpHandler, false); function keyDownHandler(e) { - if (e.key == "Right" || e.key == "ArrowRight") { + if (e.key === "Right" || e.key === "ArrowRight") { rightPressed = true; - } else if (e.key == "Left" || e.key == "ArrowLeft") { + } else if (e.key === "Left" || e.key === "ArrowLeft") { leftPressed = true; } } function keyUpHandler(e) { - if (e.key == "Right" || e.key == "ArrowRight") { + if (e.key === "Right" || e.key === "ArrowRight") { rightPressed = false; - } else if (e.key == "Left" || e.key == "ArrowLeft") { + } else if (e.key === "Left" || e.key === "ArrowLeft") { leftPressed = false; } } @@ -215,7 +215,7 @@ function draw() { dy = -dy; } else if (y + dy > canvas.height - ballRadius) { if (x > paddleX && x < paddleX + paddleWidth) { - if ((y = y - paddleHeight)) { + if ((y -= paddleHeight)) { dy = -dy; } } else { @@ -239,9 +239,10 @@ function startGame() { interval = setInterval(draw, 10); } -document.getElementById("runButton").addEventListener("click", function () { +const runButton = document.getElementById("runButton"); +runButton.addEventListener("click", () => { startGame(); - this.disabled = true; + runButton.disabled = true; }); ``` diff --git a/files/en-us/games/tutorials/2d_breakout_game_pure_javascript/collision_detection/index.md b/files/en-us/games/tutorials/2d_breakout_game_pure_javascript/collision_detection/index.md index 8ab33f0dc8f9f74..9a28f614d1ab4f0 100644 --- a/files/en-us/games/tutorials/2d_breakout_game_pure_javascript/collision_detection/index.md +++ b/files/en-us/games/tutorials/2d_breakout_game_pure_javascript/collision_detection/index.md @@ -180,17 +180,17 @@ document.addEventListener("keydown", keyDownHandler, false); document.addEventListener("keyup", keyUpHandler, false); function keyDownHandler(e) { - if (e.key == "Right" || e.key == "ArrowRight") { + if (e.key === "Right" || e.key === "ArrowRight") { rightPressed = true; - } else if (e.key == "Left" || e.key == "ArrowLeft") { + } else if (e.key === "Left" || e.key === "ArrowLeft") { leftPressed = true; } } function keyUpHandler(e) { - if (e.key == "Right" || e.key == "ArrowRight") { + if (e.key === "Right" || e.key === "ArrowRight") { rightPressed = false; - } else if (e.key == "Left" || e.key == "ArrowLeft") { + } else if (e.key === "Left" || e.key === "ArrowLeft") { leftPressed = false; } } @@ -198,7 +198,7 @@ function collisionDetection() { for (let c = 0; c < brickColumnCount; c++) { for (let r = 0; r < brickRowCount; r++) { let b = bricks[c][r]; - if (b.status == 1) { + if (b.status === 1) { if ( x > b.x && x < b.x + brickWidth && @@ -229,7 +229,7 @@ function drawPaddle() { function drawBricks() { for (let c = 0; c < brickColumnCount; c++) { for (let r = 0; r < brickRowCount; r++) { - if (bricks[c][r].status == 1) { + if (bricks[c][r].status === 1) { let brickX = c * (brickWidth + brickPadding) + brickOffsetLeft; let brickY = r * (brickHeight + brickPadding) + brickOffsetTop; bricks[c][r].x = brickX; @@ -258,7 +258,7 @@ function draw() { dy = -dy; } else if (y + dy > canvas.height - ballRadius) { if (x > paddleX && x < paddleX + paddleWidth) { - if ((y = y - paddleHeight)) { + if ((y -= paddleHeight)) { dy = -dy; } } else { @@ -282,9 +282,10 @@ function startGame() { interval = setInterval(draw, 10); } -document.getElementById("runButton").addEventListener("click", function () { +const runButton = document.getElementById("runButton"); +runButton.addEventListener("click", () => { startGame(); - this.disabled = true; + runButton.disabled = true; }); ``` diff --git a/files/en-us/games/tutorials/2d_breakout_game_pure_javascript/finishing_up/index.md b/files/en-us/games/tutorials/2d_breakout_game_pure_javascript/finishing_up/index.md index 784579b62e6c891..75d606b84ba4c2b 100644 --- a/files/en-us/games/tutorials/2d_breakout_game_pure_javascript/finishing_up/index.md +++ b/files/en-us/games/tutorials/2d_breakout_game_pure_javascript/finishing_up/index.md @@ -153,17 +153,17 @@ document.addEventListener("keyup", keyUpHandler, false); document.addEventListener("mousemove", mouseMoveHandler, false); function keyDownHandler(e) { - if (e.key == "Right" || e.key == "ArrowRight") { + if (e.key === "Right" || e.key === "ArrowRight") { rightPressed = true; - } else if (e.key == "Left" || e.key == "ArrowLeft") { + } else if (e.key === "Left" || e.key === "ArrowLeft") { leftPressed = true; } } function keyUpHandler(e) { - if (e.key == "Right" || e.key == "ArrowRight") { + if (e.key === "Right" || e.key === "ArrowRight") { rightPressed = false; - } else if (e.key == "Left" || e.key == "ArrowLeft") { + } else if (e.key === "Left" || e.key === "ArrowLeft") { leftPressed = false; } } @@ -178,7 +178,7 @@ function collisionDetection() { for (let c = 0; c < brickColumnCount; c++) { for (let r = 0; r < brickRowCount; r++) { let b = bricks[c][r]; - if (b.status == 1) { + if (b.status === 1) { if ( x > b.x && x < b.x + brickWidth && @@ -188,7 +188,7 @@ function collisionDetection() { dy = -dy; b.status = 0; score++; - if (score == brickRowCount * brickColumnCount) { + if (score === brickRowCount * brickColumnCount) { alert("YOU WIN, CONGRATS!"); document.location.reload(); } @@ -215,7 +215,7 @@ function drawPaddle() { function drawBricks() { for (let c = 0; c < brickColumnCount; c++) { for (let r = 0; r < brickRowCount; r++) { - if (bricks[c][r].status == 1) { + if (bricks[c][r].status === 1) { const brickX = r * (brickWidth + brickPadding) + brickOffsetLeft; const brickY = c * (brickHeight + brickPadding) + brickOffsetTop; bricks[c][r].x = brickX; @@ -232,12 +232,12 @@ function drawBricks() { function drawScore() { ctx.font = "16px Arial"; ctx.fillStyle = "#0095DD"; - ctx.fillText("Score: " + score, 8, 20); + ctx.fillText(`Score: ${score}`, 8, 20); } function drawLives() { ctx.font = "16px Arial"; ctx.fillStyle = "#0095DD"; - ctx.fillText("Lives: " + lives, canvas.width - 65, 20); + ctx.fillText(`Lives: ${lives}`, canvas.width - 65, 20); } function draw() { @@ -283,9 +283,10 @@ function draw() { requestAnimationFrame(draw); } -document.getElementById("runButton").addEventListener("click", function () { - draw(); - this.disabled = true; +const runButton = document.getElementById("runButton"); +runButton.addEventListener("click", () => { + startGame(); + runButton.disabled = true; }); ``` diff --git a/files/en-us/games/tutorials/2d_breakout_game_pure_javascript/game_over/index.md b/files/en-us/games/tutorials/2d_breakout_game_pure_javascript/game_over/index.md index 449395763b1a311..00070b9ec5a03ac 100644 --- a/files/en-us/games/tutorials/2d_breakout_game_pure_javascript/game_over/index.md +++ b/files/en-us/games/tutorials/2d_breakout_game_pure_javascript/game_over/index.md @@ -119,17 +119,17 @@ document.addEventListener("keydown", keyDownHandler, false); document.addEventListener("keyup", keyUpHandler, false); function keyDownHandler(e) { - if (e.key == "Right" || e.key == "ArrowRight") { + if (e.key === "Right" || e.key === "ArrowRight") { rightPressed = true; - } else if (e.key == "Left" || e.key == "ArrowLeft") { + } else if (e.key === "Left" || e.key === "ArrowLeft") { leftPressed = true; } } function keyUpHandler(e) { - if (e.key == "Right" || e.key == "ArrowRight") { + if (e.key === "Right" || e.key === "ArrowRight") { rightPressed = false; - } else if (e.key == "Left" || e.key == "ArrowLeft") { + } else if (e.key === "Left" || e.key === "ArrowLeft") { leftPressed = false; } } @@ -183,9 +183,10 @@ function startGame() { interval = setInterval(draw, 10); } -document.getElementById("runButton").addEventListener("click", function () { +const runButton = document.getElementById("runButton"); +runButton.addEventListener("click", () => { startGame(); - this.disabled = true; + runButton.disabled = true; }); ``` diff --git a/files/en-us/games/tutorials/2d_breakout_game_pure_javascript/mouse_controls/index.md b/files/en-us/games/tutorials/2d_breakout_game_pure_javascript/mouse_controls/index.md index 924586ebb77824f..8c0cc7841c230f7 100644 --- a/files/en-us/games/tutorials/2d_breakout_game_pure_javascript/mouse_controls/index.md +++ b/files/en-us/games/tutorials/2d_breakout_game_pure_javascript/mouse_controls/index.md @@ -97,17 +97,17 @@ document.addEventListener("keyup", keyUpHandler, false); document.addEventListener("mousemove", mouseMoveHandler, false); function keyDownHandler(e) { - if (e.key == "Right" || e.key == "ArrowRight") { + if (e.key === "Right" || e.key === "ArrowRight") { rightPressed = true; - } else if (e.key == "Left" || e.key == "ArrowLeft") { + } else if (e.key === "Left" || e.key === "ArrowLeft") { leftPressed = true; } } function keyUpHandler(e) { - if (e.key == "Right" || e.key == "ArrowRight") { + if (e.key === "Right" || e.key === "ArrowRight") { rightPressed = false; - } else if (e.key == "Left" || e.key == "ArrowLeft") { + } else if (e.key === "Left" || e.key === "ArrowLeft") { leftPressed = false; } } @@ -122,7 +122,7 @@ function collisionDetection() { for (let c = 0; c < brickColumnCount; c++) { for (let r = 0; r < brickRowCount; r++) { let b = bricks[c][r]; - if (b.status == 1) { + if (b.status === 1) { if ( x > b.x && x < b.x + brickWidth && @@ -132,7 +132,7 @@ function collisionDetection() { dy = -dy; b.status = 0; score++; - if (score == brickRowCount * brickColumnCount) { + if (score === brickRowCount * brickColumnCount) { alert("YOU WIN, CONGRATS!"); document.location.reload(); clearInterval(interval); // Needed for Chrome to end game @@ -160,7 +160,7 @@ function drawPaddle() { function drawBricks() { for (let c = 0; c < brickColumnCount; c++) { for (let r = 0; r < brickRowCount; r++) { - if (bricks[c][r].status == 1) { + if (bricks[c][r].status === 1) { const brickX = r * (brickWidth + brickPadding) + brickOffsetLeft; const brickY = c * (brickHeight + brickPadding) + brickOffsetTop; bricks[c][r].x = brickX; @@ -177,7 +177,7 @@ function drawBricks() { function drawScore() { ctx.font = "16px Arial"; ctx.fillStyle = "#0095DD"; - ctx.fillText("Score: " + score, 8, 20); + ctx.fillText(`Score: ${score}`, 8, 20); } function draw() { @@ -217,8 +217,10 @@ function startGame() { interval = setInterval(draw, 10); } -document.getElementById("runButton").addEventListener("click", function () { +const runButton = document.getElementById("runButton"); +runButton.addEventListener("click", () => { startGame(); + runButton.disabled = true; }); ``` diff --git a/files/en-us/games/tutorials/2d_breakout_game_pure_javascript/move_the_ball/index.md b/files/en-us/games/tutorials/2d_breakout_game_pure_javascript/move_the_ball/index.md index ba224eac8fdfd62..c7584b16ffa9d44 100644 --- a/files/en-us/games/tutorials/2d_breakout_game_pure_javascript/move_the_ball/index.md +++ b/files/en-us/games/tutorials/2d_breakout_game_pure_javascript/move_the_ball/index.md @@ -179,9 +179,10 @@ function startGame() { setInterval(draw, 10); } -document.getElementById("runButton").addEventListener("click", function () { +const runButton = document.getElementById("runButton"); +runButton.addEventListener("click", () => { startGame(); - this.disabled = true; + runButton.disabled = true; }); ``` diff --git a/files/en-us/games/tutorials/2d_breakout_game_pure_javascript/paddle_and_keyboard_controls/index.md b/files/en-us/games/tutorials/2d_breakout_game_pure_javascript/paddle_and_keyboard_controls/index.md index e52007595c6d312..f6ee8515acb4f03 100644 --- a/files/en-us/games/tutorials/2d_breakout_game_pure_javascript/paddle_and_keyboard_controls/index.md +++ b/files/en-us/games/tutorials/2d_breakout_game_pure_javascript/paddle_and_keyboard_controls/index.md @@ -149,17 +149,17 @@ document.addEventListener("keydown", keyDownHandler, false); document.addEventListener("keyup", keyUpHandler, false); function keyDownHandler(e) { - if (e.key == "Right" || e.key == "ArrowRight") { + if (e.key === "Right" || e.key === "ArrowRight") { rightPressed = true; - } else if (e.key == "Left" || e.key == "ArrowLeft") { + } else if (e.key === "Left" || e.key === "ArrowLeft") { leftPressed = true; } } function keyUpHandler(e) { - if (e.key == "Right" || e.key == "ArrowRight") { + if (e.key === "Right" || e.key === "ArrowRight") { rightPressed = false; - } else if (e.key == "Left" || e.key == "ArrowLeft") { + } else if (e.key === "Left" || e.key === "ArrowLeft") { leftPressed = false; } } @@ -211,9 +211,10 @@ function startGame() { setInterval(draw, 10); } -document.getElementById("runButton").addEventListener("click", function () { +const runButton = document.getElementById("runButton"); +runButton.addEventListener("click", () => { startGame(); - this.disabled = true; + runButton.disabled = true; }); ``` diff --git a/files/en-us/games/tutorials/2d_breakout_game_pure_javascript/track_the_score_and_win/index.md b/files/en-us/games/tutorials/2d_breakout_game_pure_javascript/track_the_score_and_win/index.md index b91664057a937fb..45c4a0a2cc882e8 100644 --- a/files/en-us/games/tutorials/2d_breakout_game_pure_javascript/track_the_score_and_win/index.md +++ b/files/en-us/games/tutorials/2d_breakout_game_pure_javascript/track_the_score_and_win/index.md @@ -148,17 +148,17 @@ document.addEventListener("keydown", keyDownHandler, false); document.addEventListener("keyup", keyUpHandler, false); function keyDownHandler(e) { - if (e.key == "Right" || e.key == "ArrowRight") { + if (e.key === "Right" || e.key === "ArrowRight") { rightPressed = true; - } else if (e.key == "Left" || e.key == "ArrowLeft") { + } else if (e.key === "Left" || e.key === "ArrowLeft") { leftPressed = true; } } function keyUpHandler(e) { - if (e.key == "Right" || e.key == "ArrowRight") { + if (e.key === "Right" || e.key === "ArrowRight") { rightPressed = false; - } else if (e.key == "Left" || e.key == "ArrowLeft") { + } else if (e.key === "Left" || e.key === "ArrowLeft") { leftPressed = false; } } @@ -166,7 +166,7 @@ function collisionDetection() { for (let c = 0; c < brickColumnCount; c++) { for (let r = 0; r < brickRowCount; r++) { let b = bricks[c][r]; - if (b.status == 1) { + if (b.status === 1) { if ( x > b.x && x < b.x + brickWidth && @@ -176,7 +176,7 @@ function collisionDetection() { dy = -dy; b.status = 0; score++; - if (score == brickRowCount * brickColumnCount) { + if (score === brickRowCount * brickColumnCount) { alert("YOU WIN, CONGRATS!"); document.location.reload(); clearInterval(interval); // Needed for Chrome to end game @@ -204,7 +204,7 @@ function drawPaddle() { function drawBricks() { for (let c = 0; c < brickColumnCount; c++) { for (let r = 0; r < brickRowCount; r++) { - if (bricks[c][r].status == 1) { + if (bricks[c][r].status === 1) { const brickX = r * (brickWidth + brickPadding) + brickOffsetLeft; const brickY = c * (brickHeight + brickPadding) + brickOffsetTop; bricks[c][r].x = brickX; @@ -221,7 +221,7 @@ function drawBricks() { function drawScore() { ctx.font = "16px Arial"; ctx.fillStyle = "#0095DD"; - ctx.fillText("Score: " + score, 8, 20); + ctx.fillText(`Score: ${score}`, 8, 20); } function draw() { @@ -261,8 +261,10 @@ function startGame() { interval = setInterval(draw, 10); } -document.getElementById("runButton").addEventListener("click", function () { +const runButton = document.getElementById("runButton"); +runButton.addEventListener("click", () => { startGame(); + runButton.disabled = true; }); ``` diff --git a/files/en-us/games/tutorials/html5_gamedev_phaser_device_orientation/index.md b/files/en-us/games/tutorials/html5_gamedev_phaser_device_orientation/index.md index 9c3107f91442f32..606b60dbbbbb457 100644 --- a/files/en-us/games/tutorials/html5_gamedev_phaser_device_orientation/index.md +++ b/files/en-us/games/tutorials/html5_gamedev_phaser_device_orientation/index.md @@ -20,7 +20,7 @@ By the end of the tutorial you will have a fully functional demo game: [Cyber Or ## Starting with the project -You can see [Cyber Orb source code](https://github.com/EnclaveGames/Cyber-Orb) on GitHub. The folder structure is quite straightforward: the starting point is the `index.html` file where we initialize the framework and set up an {{htmlelement("canvas")}} to render the game on. +You can see [Cyber Orb source code](https://github.com/EnclaveGames/Cyber-Orb) on GitHub. The folder structure is quite straightforward: the starting point is the `index.html` file where we initialize the framework and set up a {{htmlelement("canvas")}} to render the game on. ![Screenshot of the GitHub repository with the Cyber Orb game code, listing the folders and the files in the main structure.](cyber-orb-github.png) @@ -313,12 +313,16 @@ window.addEventListener("deviceorientation", this.handleOrientation, true); We're adding an event listener to the `"deviceorientation"` event and binding the `handleOrientation` function which looks like this: ```js -handleOrientation(e) { - const x = e.gamma; - const y = e.beta; - Ball._player.body.velocity.x += x; - Ball._player.body.velocity.y += y; -}, +Ball.Game.prototype = { + // … + handleOrientation(e) { + const x = e.gamma; + const y = e.beta; + Ball._player.body.velocity.x += x; + Ball._player.body.velocity.y += y; + }, + // … +}; ``` The more you tilt the device, the more force is applied to the ball, therefore the faster it moves (the velocity is higher). @@ -363,8 +367,7 @@ for (let i = 0; i < this.maxLevels; i++) { const newLevel = this.add.group(); newLevel.enableBody = true; newLevel.physicsBodyType = Phaser.Physics.ARCADE; - for (let e = 0; e < this.levelData[i].length; e++) { - const item = this.levelData[i][e]; + for (const item of this.levelData[i]) { newLevel.create(item.x, item.y, `element-${item.t}`); } newLevel.setAll("body.immovable", true); @@ -378,13 +381,17 @@ First, `add.group()` is used to create a new group of items. Then the `ARCADE` b The objects are stored in the `this.levels` array, which is by default invisible. To load specific levels, we make sure the previous levels are hidden, and show the current one: ```js -showLevel(level) { - const lvl = level | this.level; - if (this.levels[lvl - 2]) { - this.levels[lvl - 2].visible = false; - } - this.levels[lvl - 1].visible = true; -} +Ball.Game.prototype = { + // … + showLevel(level) { + const lvl = level | this.level; + if (this.levels[lvl - 2]) { + this.levels[lvl - 2].visible = false; + } + this.levels[lvl - 1].visible = true; + }, + // … +}; ``` Thanks to that the game gives the player a challenge - now they have to roll the ball across the play area and guide it through the labyrinth built from the blocks. It's just an example of loading the levels, and there are only 5 of them just to showcase the idea, but you can work on expanding that on your own. @@ -481,11 +488,15 @@ this.time.events.loop(Phaser.Timer.SECOND, this.updateCounter, this); This loop, also in the `create` function, will execute the `updateCounter` function every single second from the beginning of the game, so we can apply the changes accordingly. This is how the complete `updateCounter` function looks: ```js -updateCounter() { - this.timer++; - this.timerText.setText(`Time: ${this.timer}`); - this.totalTimeText.setText(`Total time: ${this.totalTimer+this.timer}`); -}, +Ball.Game.prototype = { + // … + updateCounter() { + this.timer++; + this.timerText.setText(`Time: ${this.timer}`); + this.totalTimeText.setText(`Total time: ${this.totalTimer + this.timer}`); + }, + // … +}; ``` As you can see we're incrementing the `this.timer` variable and updating the content of the text objects with the current values on each iteration, so the player sees the elapsed time. @@ -501,26 +512,32 @@ this.physics.arcade.overlap(this.ball, this.hole, this.finishLevel, null, this); This works similarly to the `collide` method explained earlier. When the ball overlaps with the hole (instead of colliding), the `finishLevel` function is executed: ```js -finishLevel() { - if (this.level >= this.maxLevels) { - this.totalTimer += this.timer; - alert(`Congratulations, game completed!\nTotal time of play: ${this.totalTimer} seconds!`); - this.game.state.start('MainMenu'); - } else { - alert(`Congratulations, level ${this.level} completed!`); - this.totalTimer += this.timer; - this.timer = 0; - this.level++; - this.timerText.setText(`Time: ${this.timer}`); - this.totalTimeText.setText(`Total time: ${this.totalTimer}`); - this.levelText.setText(`Level: ${this.level} / ${this.maxLevels}`); - this.ball.body.x = this.ballStartPos.x; - this.ball.body.y = this.ballStartPos.y; - this.ball.body.velocity.x = 0; - this.ball.body.velocity.y = 0; - this.showLevel(); - } -}, +Ball.Game.prototype = { + // … + finishLevel() { + if (this.level >= this.maxLevels) { + this.totalTimer += this.timer; + alert( + `Congratulations, game completed!\nTotal time of play: ${this.totalTimer} seconds!`, + ); + this.game.state.start("MainMenu"); + } else { + alert(`Congratulations, level ${this.level} completed!`); + this.totalTimer += this.timer; + this.timer = 0; + this.level++; + this.timerText.setText(`Time: ${this.timer}`); + this.totalTimeText.setText(`Total time: ${this.totalTimer}`); + this.levelText.setText(`Level: ${this.level} / ${this.maxLevels}`); + this.ball.body.x = this.ballStartPos.x; + this.ball.body.y = this.ballStartPos.y; + this.ball.body.velocity.x = 0; + this.ball.body.velocity.y = 0; + this.showLevel(); + } + }, + // … +}; ``` If the current level is equal to the maximum number of levels (in this case 5), then the game is finished — you'll get a congratulations message along with the number of seconds elapsed through the whole game, and a button to press that takes you to the main menu. diff --git a/files/en-us/glossary/accent/index.md b/files/en-us/glossary/accent/index.md index a945f63c022316d..f41091e4c6acc35 100644 --- a/files/en-us/glossary/accent/index.md +++ b/files/en-us/glossary/accent/index.md @@ -8,7 +8,7 @@ page-type: glossary-definition An **accent** is a typically bright color that contrasts with the more utilitarian background and foreground colors within a color scheme. These are present in the visual style of many platforms (though not all). -On the web, an accent is sometimes used in {{HTMLElement("input")}} elements for the active portion of the control, for instance, the background of a checked [checkbox](/en-US/docs/Web/HTML/Element/input/checkbox). +On the web, an accent is sometimes used in {{HTMLElement("input")}} elements for the active portion of the control, for instance, the background of a checked [checkbox](/en-US/docs/Web/HTML/Reference/Elements/input/checkbox). ## See also diff --git a/files/en-us/glossary/accessibility_tree/index.md b/files/en-us/glossary/accessibility_tree/index.md index e52b64c59c2a74d..917c63cc49bda1d 100644 --- a/files/en-us/glossary/accessibility_tree/index.md +++ b/files/en-us/glossary/accessibility_tree/index.md @@ -16,10 +16,10 @@ There are four properties in an accessibility tree object: - : How can we refer to this thing? For instance, a link with the text "Read more" will have "Read more" as its name (find more on how names are computed in the [Accessible Name and Description Computation spec](https://www.w3.org/TR/accname-1.1/)). - **description** - : How do we describe this thing, if we want to provide more description beyond the name? The description of a table could explain what kind of information the table contains. -- [**role**](/en-US/docs/Web/Accessibility/ARIA/Roles) +- [**role**](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles) - : What kind of thing is it? For example, is it a button, a nav bar, or a list of items? -- [**state**](/en-US/docs/Web/Accessibility/ARIA/Attributes) - - : Does it have a state? Examples include checked or unchecked checkbox states and collapsed or expanded states for the [`<summary>`](/en-US/docs/Web/HTML/Element/summary) element. +- [**state**](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes) + - : Does it have a state? Examples include checked or unchecked checkbox states and collapsed or expanded states for the [`<summary>`](/en-US/docs/Web/HTML/Reference/Elements/summary) element. Additionally, the accessibility tree often contains information on what can be done with an element: a link can be _followed_, a text input can be _typed into_, etc. diff --git a/files/en-us/glossary/accessible_description/index.md b/files/en-us/glossary/accessible_description/index.md index cca7a93980d19fb..a7e6ada4261f226 100644 --- a/files/en-us/glossary/accessible_description/index.md +++ b/files/en-us/glossary/accessible_description/index.md @@ -8,7 +8,7 @@ page-type: glossary-definition An **accessible description** is the description of a user interface element that provides additional information to help users of assistive technology understand the UI element and its context. It's associated with an HTML or SVG element and gives users additional context about its purpose beyond what is provided by the element's {{glossary("accessible name")}}. This is particularly important for users who rely on assistive technologies like {{glossary("Screen_reader", "screen readers")}}. An element's accessible description is part of the {{glossary("accessibility tree")}}. -For example, the accessible name of a {{htmlelement("table")}} is provided by its first {{htmlelement("caption")}}. In the case of complex data tables, a sentence or two describing the table can provide a description. This can be a paragraph right before or after the table, both visually and in source code order. If elsewhere in source order, or to make the associate explicit, the [`aria-describedby`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-describedby) attribute can be used to associate the table with its description. +For example, the accessible name of a {{htmlelement("table")}} is provided by its first {{htmlelement("caption")}}. In the case of complex data tables, a sentence or two describing the table can provide a description. This can be a paragraph right before or after the table, both visually and in source code order. If elsewhere in source order, or to make the associate explicit, the [`aria-describedby`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-describedby) attribute can be used to associate the table with its description. Similarly, when a user is asked to create a password, the `<label>` for the {{htmlelement("input")}} of type `password` provides its accessible name. A good accessible description includes the requirements for the password is a way that is visible to all users. It can be explicitly associated with the input via it's `aria-describedby` attribute, which adds it to the accessibility tree as the 'description' for that node. @@ -20,17 +20,17 @@ You can inspect the accessible description for any element on your page: look at For HTML elements, if an element doesn't have an accessible description, the description needs to be programmatically associated with the related element. The accessibility object model (AOM) computes the accessible description by checking this features, in order, until it is defined: -1. [`aria-describedby`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-describedby) attribute. +1. [`aria-describedby`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-describedby) attribute. -2. [`aria-description`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-description) attribute. +2. [`aria-description`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-description) attribute. 3. Language-specific features that participate in the description computation if the feature is not already being used to define the {{glossary("accessible name")}}. For example: - A {{htmlelement("summary")}} is described by the content of {{htmlelement("details")}} it is nested in. - {{htmlelement("input")}} buttons (with type attribute `button`, `submit` or `reset`) are described by their `value` attribute's value. - - In SVG, the content of the [`<desc>`](/en-US/docs/Web/SVG/Element/desc) element, if present, otherwise, the text contained in descendant text container elements (i.e. [`<text>`](/en-US/docs/Web/SVG/Element/text)), if they are not already used for the {{glossary("accessible name")}} + - In SVG, the content of the [`<desc>`](/en-US/docs/Web/SVG/Reference/Element/desc) element, if present, otherwise, the text contained in descendant text container elements (i.e., [`<text>`](/en-US/docs/Web/SVG/Reference/Element/text)), if they are not already used for the {{glossary("accessible name")}} -4. If none of the above provide a description, the [`title`](/en-US/docs/Web/HTML/Global_attributes/title) attribute is used, if the `title` is not the {{glossary("accessible name")}} for that element. +4. If none of the above provide a description, the [`title`](/en-US/docs/Web/HTML/Reference/Global_attributes/title) attribute is used, if the `title` is not the {{glossary("accessible name")}} for that element. 5. If none of the above defines an accessible description, the accessible description is empty. diff --git a/files/en-us/glossary/accessible_name/index.md b/files/en-us/glossary/accessible_name/index.md index a958f138a2c367a..0dc2eb1dc5da0ca 100644 --- a/files/en-us/glossary/accessible_name/index.md +++ b/files/en-us/glossary/accessible_name/index.md @@ -18,16 +18,16 @@ Other elements get their accessible name from the content of associated elements For some elements, the accessible name comes from the element's attributes; for example, the `alt` attribute in the case of {{HTMLElement("img")}}. Given `<img src="grape.jpg" alt="banana"/>`, the image's accessible name is "banana." -To create an association between visible content and an element or multiple text nodes and an element, the [`aria-labelledby`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-labelledby) attribute can be used. If there is no visible text to associate with a UI element needing an accessible name, the [`aria-label`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-label) attribute can be used. Names should not be added to elements marking up inline text, like {{HTMLElement("code")}}, {{HTMLElement("del")}}, and {{HTMLElement("mark")}}. +To create an association between visible content and an element or multiple text nodes and an element, the [`aria-labelledby`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-labelledby) attribute can be used. If there is no visible text to associate with a UI element needing an accessible name, the [`aria-label`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-label) attribute can be used. Names should not be added to elements marking up inline text, like {{HTMLElement("code")}}, {{HTMLElement("del")}}, and {{HTMLElement("mark")}}. Many elements, such as sections of textual content, don't need an accessible name. All controls should have an accessible name. All images that convey information and aren't purely presentational do too. -Assistive technologies provide users with the accessibility name property, which includes the accessible name along with the element's role. While many elements don't need an accessible name, it's necessary to provide an accessible name to override or supplement the content of elements with specified [roles](/en-US/docs/Web/Accessibility/ARIA/Roles). For example, a [`tabpanel`](/en-US/docs/Web/Accessibility/ARIA/Roles/tabpanel_role) is a section of content that appears after a user activates the associated element with a [`tab`](/en-US/docs/Web/Accessibility/ARIA/Roles/tab_role) role. This role can be set on an element with no needed name, like the {{HTMLElement("div")}} element. The `tab` is the control and must have an accessible name. The `tabpanel` is the child (content section) of the `tab`. Adding `aria-labelledby` to the `tabpanel` is a best practice. +Assistive technologies provide users with the accessibility name property, which includes the accessible name along with the element's role. While many elements don't need an accessible name, it's necessary to provide an accessible name to override or supplement the content of elements with specified [roles](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles). For example, a [`tabpanel`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/tabpanel_role) is a section of content that appears after a user activates the associated element with a [`tab`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/tab_role) role. This role can be set on an element with no needed name, like the {{HTMLElement("div")}} element. The `tab` is the control and must have an accessible name. The `tabpanel` is the child (content section) of the `tab`. Adding `aria-labelledby` to the `tabpanel` is a best practice. ## See also -- [ARIA roles](/en-US/docs/Web/Accessibility/ARIA/Roles) -- [ARIA attribute](/en-US/docs/Web/Accessibility/ARIA/Attributes) +- [ARIA roles](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles) +- [ARIA attribute](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes) - [Accessible Name and Description Computation 1.2 (accname)](https://w3c.github.io/accname/#mapping_additional_nd_description) - [Accessibility](/en-US/docs/Web/Accessibility) - [Learn accessibility](/en-US/docs/Learn_web_development/Core/Accessibility) diff --git a/files/en-us/glossary/api/index.md b/files/en-us/glossary/api/index.md index 581c173fa6255e4..287ad8f1fcaa380 100644 --- a/files/en-us/glossary/api/index.md +++ b/files/en-us/glossary/api/index.md @@ -8,12 +8,12 @@ page-type: glossary-definition An **API** (Application Programming Interface) is a set of features and rules that exist inside a software program (the application) enabling interaction with it through software - as opposed to a human user interface. The API can be seen as a simple contract (the interface) between the application offering it and other items, such as third-party software or hardware. -In Web development, an API is generally a set of code features (e.g. {{glossary("method","methods")}}, {{Glossary("property","properties")}}, events, and {{Glossary("URL","URLs")}}) that a developer can use in their apps for interacting with components of a user's web browser, other software/hardware on the user's computer, or third-party websites and services. +In Web development, an API is generally a set of code features (e.g., {{glossary("method","methods")}}, {{Glossary("property","properties")}}, events, and {{Glossary("URL","URLs")}}) that a developer can use in their apps for interacting with components of a user's web browser, other software/hardware on the user's computer, or third-party websites and services. For example: - The [getUserMedia](/en-US/docs/Web/API/MediaDevices/getUserMedia) API can be used to grab audio and video from a user's webcam, which is then available to the developer, for example, recording video and audio, broadcasting it to another user in a conference call, or capturing image stills from the video. -- The [Geolocation API](/en-US/docs/Web/API/Geolocation) can be used to retrieve location information from services the user has available on their device (e.g. GPS), which can then be used in conjunction with other services, such as the [Google Maps APIs](https://developers.google.com/maps/), to plot the user's location on a custom map and show them what tourist attractions are in their area. +- The [Geolocation API](/en-US/docs/Web/API/Geolocation) can be used to retrieve location information from services the user has available on their device (e.g., GPS), which can then be used in conjunction with other services, such as the [Google Maps APIs](https://developers.google.com/maps/), to plot the user's location on a custom map and show them what tourist attractions are in their area. - The [Web Animations API](/en-US/docs/Web/API/Web_Animations_API) can be used to animate parts of a web page — for example, to programmatically move or rotate images. ## See also diff --git a/files/en-us/glossary/aspect_ratio/index.md b/files/en-us/glossary/aspect_ratio/index.md index d79062177906315..311cc9f37a5049f 100644 --- a/files/en-us/glossary/aspect_ratio/index.md +++ b/files/en-us/glossary/aspect_ratio/index.md @@ -21,7 +21,7 @@ In CSS, the {{cssxref("ratio")}} data type is written as `width / height` (e.g., } ``` -In SVG, the aspect ratio is defined by the a four-value [`viewBox`](/en-US/docs/Web/SVG/Attribute/viewBox) attribute. The first two values the smallest X and Y origin coordinates the SVG can have, and the second two values are the width and height which set the aspect ratio of the SVG. +In SVG, the aspect ratio is defined by the a four-value [`viewBox`](/en-US/docs/Web/SVG/Reference/Attribute/viewBox) attribute. The first two values the smallest X and Y origin coordinates the SVG can have, and the second two values are the width and height which set the aspect ratio of the SVG. ```svg <svg viewBox="0 0 300 100" xmlns="http://www.w3.org/2000/svg"></svg> diff --git a/files/en-us/glossary/attribute/index.md b/files/en-us/glossary/attribute/index.md index 280a85df09376e3..2a808317898d588 100644 --- a/files/en-us/glossary/attribute/index.md +++ b/files/en-us/glossary/attribute/index.md @@ -15,34 +15,17 @@ A number of HTML attributes are {{Glossary("Boolean/HTML", "boolean attributes") ## Reflection of an attribute Attributes may be _reflected_ into a particular property of the specific interface. -It means that the value of the attribute can be read by accessing the property, -and can be modified by setting the property to a different value. -For example, the `placeholder` below is reflected into {{domxref("HTMLInputElement.placeholder")}}. +This means that the value of the attribute can be read or written directly in JavaScript through a property on the corresponding interface, and vice versa. +The reflected properties offer a more natural programming approach than getting and setting attributes using the {{domxref("Element.getAttribute()","getAttribute()")}} and {{domxref("Element.setAttribute()","setAttribute()")}} methods of the {{domxref("Element")}} interface. -Considering the following HTML: - -```html -<input placeholder="Original placeholder" /> -``` - -We can check the reflection between {{domxref("HTMLInputElement.placeholder")}} and the attribute using: - -```js -const input = document.querySelector("input"); -const attr = input.getAttributeNode("placeholder"); -console.log(attr.value); -console.log(input.placeholder); // Prints the same value as `attr.value` - -// Changing placeholder value will also change the value of the reflected attribute. -input.placeholder = "Modified placeholder"; -console.log(attr.value); // Prints `Modified placeholder` -``` +For more information see [Attribute reflection](/en-US/docs/Web/API/Document_Object_Model/Reflected_attributes). ## See also -- [HTML attribute reference](/en-US/docs/Web/HTML/Attributes) -- Information about HTML's [global attributes](/en-US/docs/Web/HTML/Global_attributes) +- [HTML attribute reference](/en-US/docs/Web/HTML/Reference/Attributes) +- [Attribute reflection](/en-US/docs/Web/API/Document_Object_Model/Reflected_attributes) +- Information about HTML's [global attributes](/en-US/docs/Web/HTML/Reference/Global_attributes) - XML StartTag Attribute Recommendation in [W3C XML Recommendation](https://www.w3.org/TR/xml#sec-starttags) - Related glossary terms: - {{Glossary("Element")}} diff --git a/files/en-us/glossary/base64/index.md b/files/en-us/glossary/base64/index.md index f7536d517349543..09d2f73cf102b57 100644 --- a/files/en-us/glossary/base64/index.md +++ b/files/en-us/glossary/base64/index.md @@ -24,7 +24,7 @@ Base64 encoding schemes are commonly used to encode binary data for storage or t ## Encoded size increase -Each Base64 digit represents 6 bits of data. So, three 8-bit bytes of the input string/binary file (3×8 bits = 24 bits) can be represented by four 6-bit Base64 digits (4×6 = 24 bits). +Each Base64 digit represents 6 bits of data (64 = 2<sup>6</sup>). So, three 8-bit bytes of the input string/binary file (3×8 bits = 24 bits) can be represented by four 6-bit Base64 digits (4×6 = 24 bits). This means that the Base64 version of a string or file is typically roughly a third larger than its source (the exact size increase depends on various factors, such as the absolute length of the string, its length modulo 3, and whether padding characters are used). diff --git a/files/en-us/glossary/bigint/index.md b/files/en-us/glossary/bigint/index.md index 9f81a35c5ba9ef9..c8eb7d8f693f1f0 100644 --- a/files/en-us/glossary/bigint/index.md +++ b/files/en-us/glossary/bigint/index.md @@ -11,5 +11,5 @@ In {{Glossary("JavaScript")}}, **BigInt** is a numeric data type that can repres ## See also - [Numeric types](https://en.wikipedia.org/wiki/Data_type#Numeric_types) on Wikipedia -- The JavaScript type: [`BigInt`](/en-US/docs/Web/JavaScript/Data_structures#bigint_type) +- The JavaScript type: [`BigInt`](/en-US/docs/Web/JavaScript/Guide/Data_structures#bigint_type) - The JavaScript global object {{jsxref("BigInt")}} diff --git a/files/en-us/glossary/bitwise_flags/index.md b/files/en-us/glossary/bitwise_flags/index.md index 3b74db1d872d98e..9bf8d617e6d9203 100644 --- a/files/en-us/glossary/bitwise_flags/index.md +++ b/files/en-us/glossary/bitwise_flags/index.md @@ -6,12 +6,14 @@ page-type: glossary-definition {{GlossarySidebar}} -**Bitwise flags** are sets of variables, usually simple number values, which can be used to enable or disable specific usages or features of a method or other code structure. They can do this quickly and efficiently because they operate at the bit level. Related flags in the same group are generally given complementary values representing different bit positions in a single value (e.g. hexadecimal), so that multiple flag settings can be represented by a single value. +**Bitwise flags** are sets of variables, usually simple number values, which can be used to enable or disable specific usages or features of a method or other code structure. They can do this quickly and efficiently because they operate at the bit level. Related flags in the same group are generally given complementary values representing different bit positions in a single value (e.g., hexadecimal), so that multiple flag settings can be represented by a single value. For example, in the {{domxref("WebGPU API", "WebGPU API", "", "nocode")}}, a {{domxref("GPUBuffer")}} object instance is created using the {{domxref("GPUDevice.createBuffer()")}} method. When invoking this method, you define a `usage` property in the descriptor containing one or more flags that enable different allowed usages of that buffer. ```js -usage: GPUBufferUsage.COPY_SRC | GPUBufferUsage.MAP_WRITE; +const descriptor = { + usage: GPUBufferUsage.COPY_SRC | GPUBufferUsage.MAP_WRITE, +}; ``` These values are defined inside the same namespace, and each one has a hexadecimal value: diff --git a/files/en-us/glossary/blink_element/index.md b/files/en-us/glossary/blink_element/index.md index 2f2a6f75887b0fb..d7e4df41b69d619 100644 --- a/files/en-us/glossary/blink_element/index.md +++ b/files/en-us/glossary/blink_element/index.md @@ -8,25 +8,23 @@ page-type: glossary-definition The **`<blink>` element** (blink tag) is an obsolete HTML feature no longer supported by web browsers and no longer documented on MDN. It was used to make text content blink on and off (flash) continually. +The `<blink>` element was used like this: + +```html example-bad +<blink>In ancient browsers, I may have blinked</blink> +``` + ## Brief history In the early days of the web (the early- to mid-90s), there were not many features available for styling web pages. The [CSS](/en-US/docs/Web/CSS) specification (version 1) was first released in 1996 and not adopted consistently by browsers until much later. Before CSS, browsers experimented with several features to make particular text sections stand out and grab the user's attention. The `<blink>` element was one of these, introduced in early versions of [Netscape Navigator](/en-US/docs/Glossary/Netscape_Navigator); [Internet Explorer's](/en-US/docs/Glossary/Microsoft_Internet_Explorer) {{htmlelement("marquee")}} element was another. The `<blink>` element was apparently created after a conversation in a bar in Mountain View between Netscape engineer [Lou Montulli](https://en.wikipedia.org/wiki/Lou_Montulli) and colleagues. When he went into the office the next morning, he found that one of his fellow engineers had stayed up all night and implemented it ([read the story here](https://web.archive.org/web/20220331020029/http://www.montulli.org/theoriginofthe%3Cblink%3Etag)). -While initially popular, `<blink>` became much maligned because of overuse; many people found it annoying. More importantly, it degrades readability and can be particularly problematic for users with visual impairments or [cognitive disorders](/en-US/docs/Web/Accessibility/Cognitive_accessibility) such as epilepsy or ADHD. It can be disorienting or, in the worst cases, even [trigger seizures](/en-US/docs/Web/Accessibility/Seizure_disorders). +While initially popular, `<blink>` became much maligned because of overuse; many people found it annoying. More importantly, it degrades readability and can be particularly problematic for users with visual impairments or [cognitive disorders](/en-US/docs/Web/Accessibility/Guides/Cognitive_accessibility) such as epilepsy or ADHD. It can be disorienting or, in the worst cases, even [trigger seizures](/en-US/docs/Web/Accessibility/Guides/Seizure_disorders). `<blink>` was never properly specified and never achieved significant cross-browser support. It can be considered a piece of web history. -## Syntax - -The `<blink>` element was used like this: - -```html example-bad -<blink>In ancient browsers, I may have blinked</blink> -``` - -### Alternatives +## Alternatives - The CSS {{cssxref("text-decoration-line")}} property has a `blink` value that should have the same effect, but most modern browsers ignore it. - The JavaScript {{jsxref("String.blink()")}} method wraps a text string in `<blink></blink>` tags but, as discussed earlier, this element is no longer supported anywhere. diff --git a/files/en-us/glossary/block/css/index.md b/files/en-us/glossary/block/css/index.md index daf3b5cb2500e4e..d549fc11bdd41cc 100644 --- a/files/en-us/glossary/block/css/index.md +++ b/files/en-us/glossary/block/css/index.md @@ -6,10 +6,10 @@ page-type: glossary-definition {{GlossarySidebar}} -A **block** on a webpage is an {{glossary("HTML")}} {{glossary("element")}} that appears on a new line, i.e. underneath the preceding element in a horizontal writing mode, and above the following element (commonly known as a _block-level element_). For example, {{htmlelement("p")}} is by default a block-level element, whereas {{htmlelement("a")}} is an _inline element_ — you can put several links next to one another in your HTML source and they will sit on the same line as one another in the rendered output. +A **block** on a webpage is an {{glossary("HTML")}} {{glossary("element")}} that appears on a new line, i.e., underneath the preceding element in a horizontal writing mode, and above the following element (commonly known as a _block-level element_). For example, {{htmlelement("p")}} is by default a block-level element, whereas {{htmlelement("a")}} is an _inline element_ — you can put several links next to one another in your HTML source and they will sit on the same line as one another in the rendered output. Using the {{cssxref("display")}} property you can change whether an element displays inline or as a block (among many other options); **blocks** are also subject to the effects of positioning schemes and use of the {{cssxref("position")}} property. ## See also -- [Visual formatting model](/en-US/docs/Web/CSS/Visual_formatting_model) +- [Visual formatting model](/en-US/docs/Web/CSS/CSS_display/Visual_formatting_model) diff --git a/files/en-us/glossary/boolean/html/index.md b/files/en-us/glossary/boolean/html/index.md index 06577fcf0b8c0de..6845a355cd3b8ad 100644 --- a/files/en-us/glossary/boolean/html/index.md +++ b/files/en-us/glossary/boolean/html/index.md @@ -32,7 +32,7 @@ Here's an example of a HTML boolean attribute `checked`: ## See also -- [Boolean attributes](/en-US/docs/Web/HTML/Attributes#boolean_attributes) +- [Boolean attributes](/en-US/docs/Web/HTML/Reference/Attributes#boolean_attributes) - [Boolean attributes](https://html.spec.whatwg.org/#boolean-attributes) in HTML specification - Related glossary terms: - {{Glossary("Attribute")}} diff --git a/files/en-us/glossary/boolean/index.md b/files/en-us/glossary/boolean/index.md index 5e8271823490022..b0268d44d666082 100644 --- a/files/en-us/glossary/boolean/index.md +++ b/files/en-us/glossary/boolean/index.md @@ -12,7 +12,7 @@ For example, in JavaScript, Boolean conditionals are often used to decide which Below is some JavaScript pseudocode (it's not truly executable code) demonstrating this concept. -```js +```js-nolint /* JavaScript if statement */ if (boolean conditional) { // code to execute if the conditional is true diff --git a/files/en-us/glossary/boolean/javascript/index.md b/files/en-us/glossary/boolean/javascript/index.md index b4922159a41274b..d20679724270c4d 100644 --- a/files/en-us/glossary/boolean/javascript/index.md +++ b/files/en-us/glossary/boolean/javascript/index.md @@ -13,4 +13,4 @@ A {{jsxref("Boolean")}} object is a {{Glossary("wrapper")}} around a Boolean pri ## See also - [The JavaScript global object](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Boolean) -- [JavaScript data types and data structures](/en-US/docs/Web/JavaScript/Data_structures) +- [JavaScript data types and data structures](/en-US/docs/Web/JavaScript/Guide/Data_structures) diff --git a/files/en-us/glossary/browser/index.md b/files/en-us/glossary/browser/index.md index ab1570a6c56d8d1..c9809d15a24cd18 100644 --- a/files/en-us/glossary/browser/index.md +++ b/files/en-us/glossary/browser/index.md @@ -21,7 +21,7 @@ Common browsers include: - [Web browser](https://en.wikipedia.org/wiki/Web_browser) on Wikipedia - {{HTTPHeader("User-agent")}} (HTTP Header) - Download a browser - - [Mozilla Firefox](https://www.mozilla.org/en-US/firefox/) + - [Mozilla Firefox](https://www.mozilla.org/en-US/firefox/new/) - [Google Chrome](https://www.google.com/chrome/) - [Microsoft Edge](https://www.microsoft.com/en-us/edge) - [Opera Browser](https://www.opera.com/) diff --git a/files/en-us/glossary/camel_case/index.md b/files/en-us/glossary/camel_case/index.md index 1062982a3e34118..0609d1cb1b9326e 100644 --- a/files/en-us/glossary/camel_case/index.md +++ b/files/en-us/glossary/camel_case/index.md @@ -10,6 +10,8 @@ page-type: glossary-definition Camel casing is often used as a variable naming convention. The following variables are in camel case: {{domxref("console")}}, {{jsxref("encodeURIComponent")}}, {{jsxref("ArrayBuffer")}}, and {{domxref("HTMLElement")}}. +<!-- cSpell:ignore XMLHTTP --> + Note that if the phrase contains acronyms (such as `URI` and `HTML`), camel casing practices vary. Some prefer to keep all of them capitalized, such as `encodeURIComponent` above. This may sometimes lead to ambiguity with multiple consecutive acronyms, such as `XMLHTTPRequest`. Others prefer to only capitalize the first letter, as `XmlHttpRequest`. The actual global variable, {{domxref("XMLHttpRequest")}}, uses a mix of both. When the first letter of the entire phrase is upper case, it is called _upper camel case_ or _Pascal case_. Otherwise, it is called _lower camel case_. diff --git a/files/en-us/glossary/caret/index.md b/files/en-us/glossary/caret/index.md index ed449abbe4bf7e5..c755bafa504189d 100644 --- a/files/en-us/glossary/caret/index.md +++ b/files/en-us/glossary/caret/index.md @@ -10,7 +10,7 @@ A **caret** (sometimes called a "text cursor") is an indicator displayed on the Most user interfaces represent the caret using a thin vertical line or a character-sized box that flashes, but this can vary. This point in the text is called the **insertion point**. The word "caret" differentiates the text insertion point from the mouse cursor. -On the web, a caret is used to represent the insertion point in {{HTMLElement("input")}} and {{HTMLElement("textarea")}} elements, as well as any elements whose [`contenteditable`](/en-US/docs/Web/HTML/Global_attributes/contenteditable) attribute is set, thereby allowing the contents of the element to be edited by the user. +On the web, a caret is used to represent the insertion point in {{HTMLElement("input")}} and {{HTMLElement("textarea")}} elements, as well as any elements whose [`contenteditable`](/en-US/docs/Web/HTML/Reference/Global_attributes/contenteditable) attribute is set, thereby allowing the contents of the element to be edited by the user. ## See also @@ -24,11 +24,11 @@ You can set the color of the caret for a given element's editable content by set These elements provide text entry fields or boxes and therefore make use of the caret. -- [`<input type="text">`](/en-US/docs/Web/HTML/Element/input/text) -- [`<input type="password">`](/en-US/docs/Web/HTML/Element/input/password) -- [`<input type="search">`](/en-US/docs/Web/HTML/Element/input/search) -- [`<input type="date">`](/en-US/docs/Web/HTML/Element/input/date), [`<input type="time">`](/en-US/docs/Web/HTML/Element/input/time), and [`<input type="datetime-local">`](/en-US/docs/Web/HTML/Element/input/datetime-local) -- [`<input type="number">`](/en-US/docs/Web/HTML/Element/input/number), [`<input type="range">`](/en-US/docs/Web/HTML/Element/input/range) -- [`<input type="email">`](/en-US/docs/Web/HTML/Element/input/email), [`<input type="tel">`](/en-US/docs/Web/HTML/Element/input/tel), and [`<input type="url">`](/en-US/docs/Web/HTML/Element/input/url) +- [`<input type="text">`](/en-US/docs/Web/HTML/Reference/Elements/input/text) +- [`<input type="password">`](/en-US/docs/Web/HTML/Reference/Elements/input/password) +- [`<input type="search">`](/en-US/docs/Web/HTML/Reference/Elements/input/search) +- [`<input type="date">`](/en-US/docs/Web/HTML/Reference/Elements/input/date), [`<input type="time">`](/en-US/docs/Web/HTML/Reference/Elements/input/time), and [`<input type="datetime-local">`](/en-US/docs/Web/HTML/Reference/Elements/input/datetime-local) +- [`<input type="number">`](/en-US/docs/Web/HTML/Reference/Elements/input/number), [`<input type="range">`](/en-US/docs/Web/HTML/Reference/Elements/input/range) +- [`<input type="email">`](/en-US/docs/Web/HTML/Reference/Elements/input/email), [`<input type="tel">`](/en-US/docs/Web/HTML/Reference/Elements/input/tel), and [`<input type="url">`](/en-US/docs/Web/HTML/Reference/Elements/input/url) - {{HTMLElement("textarea")}} -- Any element with its [`contenteditable`](/en-US/docs/Web/HTML/Global_attributes/contenteditable) attribute set +- Any element with its [`contenteditable`](/en-US/docs/Web/HTML/Reference/Global_attributes/contenteditable) attribute set diff --git a/files/en-us/glossary/cdn/index.md b/files/en-us/glossary/cdn/index.md index 5033459a8b233ad..626d7db5c5a0ef5 100644 --- a/files/en-us/glossary/cdn/index.md +++ b/files/en-us/glossary/cdn/index.md @@ -20,7 +20,7 @@ There are also downsides to using CDNs, compared to self-hosting static assets: - It introduces an additional dependency on a third-party service. If the CDN goes down, is blocked in a region, or is permanently shut down, your website will malfunction. - It introduces an extra attack vector. Attackers can compromise the CDN and serve malicious content to your users. This necessitates countermeasures like [Subresource Integrity (SRI)](/en-US/docs/Web/Security/Practical_implementation_guides/SRI). -- Contrary to popular belief, CDN may actually _reduce_ performance. By establishing connection with a third-party website, the user's browser has to go through more rounds of DNS lookup, content negotiation, and so on. In addition, modern browsers do not share cache between different origins for the same resource for privacy reasons, so the user has to download the same asset (e.g. jQuery) multiple times on different websites anyway. +- Contrary to popular belief, CDN may actually _reduce_ performance. By establishing connection with a third-party website, the user's browser has to go through more rounds of DNS lookup, content negotiation, and so on. In addition, modern browsers do not share cache between different origins for the same resource for privacy reasons, so the user has to download the same asset (e.g., jQuery) multiple times on different websites anyway. ## See also diff --git a/files/en-us/glossary/certificate_authority/index.md b/files/en-us/glossary/certificate_authority/index.md index d9daca4bbd41553..ea7b8a644d17e83 100644 --- a/files/en-us/glossary/certificate_authority/index.md +++ b/files/en-us/glossary/certificate_authority/index.md @@ -13,7 +13,7 @@ For a website digital certificate, this information minimally includes the name Certificate authorities are the part of the Internet [public key infrastructure](https://en.wikipedia.org/wiki/Public_key_infrastructure) that allows browsers to verify website identity and securely connect over TLS (thus HTTPS). > [!NOTE] -> Web browsers come preloaded with a list of "root certificates". The browser can use these to reliably check that the website certificate was signed by a certificate authority that "chains back" to the root certificate (i.e. was trusted by the owner of the root certificate or an intermediate CA). Ultimately this process relies on every CA performing adequate identity checks before signing a certificate! +> Web browsers come preloaded with a list of "root certificates". The browser can use these to reliably check that the website certificate was signed by a certificate authority that "chains back" to the root certificate (i.e., was trusted by the owner of the root certificate or an intermediate CA). Ultimately this process relies on every CA performing adequate identity checks before signing a certificate! ## See also diff --git a/files/en-us/glossary/challenge/index.md b/files/en-us/glossary/challenge/index.md index 89ade8ad4f337df..620ecdb4fde96c9 100644 --- a/files/en-us/glossary/challenge/index.md +++ b/files/en-us/glossary/challenge/index.md @@ -8,7 +8,7 @@ page-type: glossary-definition In security protocols, a **challenge** is some data sent to the client by the server in order to generate a different response each time. Challenge-response protocols are one way to fight against {{glossary("replay attack", "replay attacks")}} where an attacker listens to the previous messages and resends them at a later time to get the same credentials as the original message. -The [HTTP authentication protocol](/en-US/docs/Web/HTTP/Authentication) is challenge-response based, though the "Basic" protocol isn't using a real challenge (the realm is always the same). +The [HTTP authentication protocol](/en-US/docs/Web/HTTP/Guides/Authentication) is challenge-response based, though the "Basic" protocol isn't using a real challenge (the realm is always the same). ## See also diff --git a/files/en-us/glossary/character_reference/index.md b/files/en-us/glossary/character_reference/index.md index 26e40214fa3f89c..a599c30b9ecdbfd 100644 --- a/files/en-us/glossary/character_reference/index.md +++ b/files/en-us/glossary/character_reference/index.md @@ -24,7 +24,7 @@ There are three types of character references: - : These references start with `&#`, followed by one or more ASCII digits representing the base-ten integer that corresponds to the character's {{glossary("Unicode")}} {{glossary("code point")}}, and ending with `;`. For example, the decimal character reference for `<` is `&#60;`, because the Unicode code point for the symbol is `U+0003C`, and `3C` hexadecimal is 60 in decimal. -- **Hexadecimal numeric character reference** +- **Hexadecimal numeric character references** - : These references start with `&#x` or `&#X`, followed by one or more ASCII hex digits, representing the hexadecimal integer that corresponds to the character's Unicode code point, and ending with `;`. For example, the hexadecimal character reference for `<` is `&#x3C;` or `&#X3C;`, because the Unicode code point for the symbol is `U+0003C`. diff --git a/files/en-us/glossary/character_set/index.md b/files/en-us/glossary/character_set/index.md index 4de0d4fbad6e9b9..e4c748f3420d3b9 100644 --- a/files/en-us/glossary/character_set/index.md +++ b/files/en-us/glossary/character_set/index.md @@ -8,7 +8,7 @@ page-type: glossary-definition A **character set** is an encoding system to let computers know how to recognize {{Glossary("Character")}}, including letters, numbers, punctuation marks, and whitespace. -In earlier times, countries developed their own character sets due to their different languages used, such as Kanji JIS codes (e.g. Shift-JIS, EUC-JP, etc.) for Japanese, Big5 for traditional Chinese, and KOI8-R for Russian. However, {{Glossary("Unicode")}} gradually became most acceptable character set for its universal language support. +In earlier times, countries developed their own character sets due to their different languages used, such as Kanji JIS codes (e.g., Shift-JIS, EUC-JP, etc.) for Japanese, Big5 for traditional Chinese, and KOI8-R for Russian. However, {{Glossary("Unicode")}} gradually became most acceptable character set for its universal language support. If a character set is used incorrectly (For example, Unicode for an article encoded in Big5), you may see nothing but broken characters, which are called [Mojibake](https://en.wikipedia.org/wiki/Mojibake). diff --git a/files/en-us/glossary/cipher_suite/index.md b/files/en-us/glossary/cipher_suite/index.md index 2e4c379764bae9d..900c44bb585c788 100644 --- a/files/en-us/glossary/cipher_suite/index.md +++ b/files/en-us/glossary/cipher_suite/index.md @@ -10,7 +10,7 @@ page-type: glossary-definition In a crypto system like {{Glossary("TLS")}}, the client and server must agree on a cipher suite before they can begin communicating securely. A typical cipher suite looks like ECDHE_RSA_WITH_AES_128_GCM_SHA256 or ECDHE-RSA-AES128-GCM-SHA256, indicating: -- ECDHE (elliptic curve Diffie-Hellman ephemeral) for key exchange +- ECDHE (elliptic curve Diffie–Hellman ephemeral) for key exchange - RSA for authentication - AES-128 as the cipher, with Galois/Counter Mode (GCM) as the block cipher mode of operation - SHA-256 as the hash-based message authentication code (HMAC) diff --git a/files/en-us/glossary/class/index.md b/files/en-us/glossary/class/index.md index 318db895801055b..a6937bca0f92ec7 100644 --- a/files/en-us/glossary/class/index.md +++ b/files/en-us/glossary/class/index.md @@ -11,6 +11,6 @@ In {{glossary("OOP","object-oriented programming")}}, a **class** defines an {{g ## See also - [Classes in JavaScript](/en-US/docs/Learn_web_development/Extensions/Advanced_JavaScript_objects/Classes_in_JavaScript) -- [Inheritance and the prototype chain](/en-US/docs/Web/JavaScript/Inheritance_and_the_prototype_chain) +- [Inheritance and the prototype chain](/en-US/docs/Web/JavaScript/Guide/Inheritance_and_the_prototype_chain) - [Class-based programming](https://en.wikipedia.org/wiki/Class-based_programming) on Wikipedia - [Object-oriented programming](https://en.wikipedia.org/wiki/Object-oriented_programming) on Wikipedia diff --git a/files/en-us/glossary/closure/index.md b/files/en-us/glossary/closure/index.md index 32379bc8fab0908..adeed5b4f410967 100644 --- a/files/en-us/glossary/closure/index.md +++ b/files/en-us/glossary/closure/index.md @@ -10,5 +10,5 @@ In computer programming, a **closure** is a technique for implementing lexically ## See also -- [Closures in JavaScript](/en-US/docs/Web/JavaScript/Closures) +- [Closures in JavaScript](/en-US/docs/Web/JavaScript/Guide/Closures) - [Closure](https://en.wikipedia.org/wiki/Closure_%28computer_programming%29) on Wikipedia diff --git a/files/en-us/glossary/compression_dictionary_transport/index.md b/files/en-us/glossary/compression_dictionary_transport/index.md new file mode 100644 index 000000000000000..27274b570e2429e --- /dev/null +++ b/files/en-us/glossary/compression_dictionary_transport/index.md @@ -0,0 +1,26 @@ +--- +title: Compression Dictionary Transport +slug: Glossary/Compression_dictionary_transport +page-type: glossary-definition +--- + +{{GlossarySidebar}} + +**Compression Dictionary Transport** is a way of using a shared compression dictionary, rather than the standard static dictionary in {{glossary("Brotli compression")}} or {{glossary("Zstandard compression")}}, to dramatically reduce the transport size of HTTP responses. + +For example, when downloading `app.v2.js`, if the client already has `app.v1.js` then they can reference text from that by using it as a dictionary and effectively only download the delta and a small amount of references to the `v1` file. + +See the [Compression Dictionary Transport guide](/en-US/docs/Web/HTTP/Guides/Compression_dictionary_transport) for more information. + +## See also + +- [Compression Dictionary Transport guide](/en-US/docs/Web/HTTP/Guides/Compression_dictionary_transport) +- Related glossary terms: + - {{Glossary("Brotli compression")}} + - {{Glossary("Zstandard compression")}} +- [&lt;link rel=&quot;compression-dictionary&quot;&gt;](/en-US/docs/Web/HTML/Reference/Attributes/rel/compression-dictionary)- {{HTTPHeader("Accept-encoding")}} +- {{HTTPHeader("Content-encoding")}} +- {{HTTPHeader("Available-Dictionary")}} +- {{HTTPHeader("Dictionary-ID")}} +- {{HTTPHeader("Use-As-Dictionary")}} +- [Draft specification](https://datatracker.ietf.org/doc/draft-ietf-httpbis-compression-dictionary/) diff --git a/files/en-us/glossary/constructor/index.md b/files/en-us/glossary/constructor/index.md index 69e1cdd1870d304..a01e091b202c155 100644 --- a/files/en-us/glossary/constructor/index.md +++ b/files/en-us/glossary/constructor/index.md @@ -6,28 +6,9 @@ page-type: glossary-definition {{GlossarySidebar}} -A **constructor** belongs to a particular class {{glossary("object")}} that is instantiated. The constructor initializes this object and can provide access to its private information. The concept of a constructor can be applied to most {{glossary("OOP","object-oriented programming")}} languages. Essentially, a constructor in {{glossary("JavaScript")}} is usually declared at the instance of a {{glossary("class")}}. +A **constructor** is a specialized {{glossary("function")}} that generates {{glossary("object", "objects")}} with the same shape and behavior. The constructor initializes this object with some data specific to the object. The concept of a constructor can be applied to most {{glossary("OOP","object-oriented programming")}} languages. -## Syntax - -```js -// This is a generic default constructor class Default -function Default() {} - -// This is an overloaded constructor class Overloaded -// with parameter arguments -function Overloaded(arg1, arg2, /* …, */ argN) {} -``` - -To call the constructor of the class in JavaScript, use a `new` operator to assign a new {{glossary("object reference")}} to a {{glossary("variable")}}. - -```js -function Default() {} - -// A new reference of a Default object assigned to a -// local variable defaultReference -const defaultReference = new Default(); -``` +In {{glossary("JavaScript")}}, a constructor is usually declared within a [class](/en-US/docs/Web/JavaScript/Reference/Classes), but it can also be declared as a [function](/en-US/docs/Web/JavaScript/Reference/Functions). In fact, any function that can be called with the [`new`](/en-US/docs/Web/JavaScript/Reference/Operators/new) operator is a constructor. ## See also diff --git a/files/en-us/glossary/content_header/index.md b/files/en-us/glossary/content_header/index.md index 3edeeb169bbf030..671e563a70df32f 100644 --- a/files/en-us/glossary/content_header/index.md +++ b/files/en-us/glossary/content_header/index.md @@ -6,7 +6,7 @@ page-type: glossary-definition {{GlossarySidebar}} -**Content headers** are the group of [HTTP headers](/en-US/docs/Web/HTTP/Headers) that describe the content of the body of an HTTP message, after any message framing in the body has been removed. +**Content headers** are the group of [HTTP headers](/en-US/docs/Web/HTTP/Reference/Headers) that describe the content of the body of an HTTP message, after any message framing in the body has been removed. They specifically describe the properties of the {{Glossary("HTTP Content", "message content")}} that is conveyed in a particular message _as it is transported_, such as the length of the content, the transport encoding, which part of the resource is carried in the data (for multi-part messages), and message integrity checks. They differ from the {{Glossary("Representation header", "Representation headers")}}, which describe the encoding, media type, language, and other characteristics of the resource, and allow the underlying data to be interpreted. @@ -27,7 +27,7 @@ These headers may be present in both HTTP request and response messages and incl ## See also -- [HTTP headers](/en-US/docs/Web/HTTP/Headers) +- [HTTP headers](/en-US/docs/Web/HTTP/Reference/Headers) - Related glossary terms: - {{Glossary("Representation header")}} - {{Glossary("HTTP Content")}} diff --git a/files/en-us/glossary/cookie/index.md b/files/en-us/glossary/cookie/index.md index 853f584b5e39efd..e2734a003b06166 100644 --- a/files/en-us/glossary/cookie/index.md +++ b/files/en-us/glossary/cookie/index.md @@ -10,7 +10,7 @@ A **cookie** is a small piece of information left on a visitor's computer by a w Cookies are used to personalize a user's web experience with a website. It may contain the user's preferences or inputs when accessing that website. A user can customize their web browser to accept, reject, or delete cookies. -Cookies can be set and modified at the server level using the `Set-Cookie` [HTTP header](/en-US/docs/Web/HTTP/Cookies), or with JavaScript using [`document.cookie`](/en-US/docs/Web/API/Document/cookie). +Cookies can be set and modified at the server level using the `Set-Cookie` [HTTP header](/en-US/docs/Web/HTTP/Guides/Cookies), or with JavaScript using [`document.cookie`](/en-US/docs/Web/API/Document/cookie). ## See also diff --git a/files/en-us/glossary/cors-safelisted_request_header/index.md b/files/en-us/glossary/cors-safelisted_request_header/index.md index ae475bc3065483c..f8ae234770f7a19 100644 --- a/files/en-us/glossary/cors-safelisted_request_header/index.md +++ b/files/en-us/glossary/cors-safelisted_request_header/index.md @@ -6,7 +6,7 @@ page-type: glossary-definition {{GlossarySidebar}} -A [**CORS-safelisted request header**](https://fetch.spec.whatwg.org/#cors-safelisted-request-header) (also known as "simple header") is one of the following [HTTP headers](/en-US/docs/Web/HTTP/Headers): +A [**CORS-safelisted request header**](https://fetch.spec.whatwg.org/#cors-safelisted-request-header) (also known as "simple header") is one of the following [HTTP headers](/en-US/docs/Web/HTTP/Reference/Headers): - {{HTTPHeader("Accept")}} - {{HTTPHeader("Accept-Language")}} diff --git a/files/en-us/glossary/cors-safelisted_response_header/index.md b/files/en-us/glossary/cors-safelisted_response_header/index.md index 7fb6b7783e906a7..799302ebb4cc407 100644 --- a/files/en-us/glossary/cors-safelisted_response_header/index.md +++ b/files/en-us/glossary/cors-safelisted_response_header/index.md @@ -6,7 +6,7 @@ page-type: glossary-definition {{GlossarySidebar}} -A **CORS-safelisted response header** (also known as "simple response header") is an [HTTP header](/en-US/docs/Web/HTTP/Headers) in a [CORS](/en-US/docs/Web/HTTP/CORS) response that it is considered _safe_ to expose to client scripts. Only safelisted response headers are made available to web pages. +A **CORS-safelisted response header** (also known as "simple response header") is an [HTTP header](/en-US/docs/Web/HTTP/Reference/Headers) in a [CORS](/en-US/docs/Web/HTTP/Guides/CORS) response that it is considered _safe_ to expose to client scripts. Only safelisted response headers are made available to web pages. By default, the safelist includes the following response headers: @@ -20,8 +20,6 @@ By default, the safelist includes the following response headers: Additional headers can be added to the safelist using {{HTTPHeader("Access-Control-Expose-Headers")}}. -> **Note:** {{HTTPHeader("Content-Length")}} was not part of the original set of safelisted response headers \[[ref](https://github.com/whatwg/fetch/pull/626)] - ## Examples ### Extending the safelist @@ -35,7 +33,7 @@ Access-Control-Expose-Headers: X-Custom-Header, Content-Encoding ## See also - [HTTP](/en-US/docs/Web/HTTP) -- [HTTP headers](/en-US/docs/Web/HTTP/Headers) +- [HTTP headers](/en-US/docs/Web/HTTP/Reference/Headers) - {{HTTPHeader("Access-Control-Expose-Headers")}} - Related glossary terms: - {{Glossary("CORS")}} diff --git a/files/en-us/glossary/cors/index.md b/files/en-us/glossary/cors/index.md index 2303159f9bbed17..dd2bf1c83f886a2 100644 --- a/files/en-us/glossary/cors/index.md +++ b/files/en-us/glossary/cors/index.md @@ -27,7 +27,7 @@ The [same-origin security policy](/en-US/docs/Web/Security/Same-origin_policy) f - {{HTTPHeader("Access-Control-Request-Headers")}} - : Used when issuing a preflight request to let the server know which HTTP headers will be used when the actual request is made. - {{HTTPHeader("Access-Control-Request-Method")}} - - : Used when issuing a preflight request to let the server know which [HTTP method](/en-US/docs/Web/HTTP/Methods) will be used when the actual request is made. + - : Used when issuing a preflight request to let the server know which [HTTP method](/en-US/docs/Web/HTTP/Reference/Methods) will be used when the actual request is made. - {{HTTPHeader("Origin")}} - : Indicates where a fetch originates from. - {{HTTPHeader("Timing-Allow-Origin")}} @@ -35,6 +35,6 @@ The [same-origin security policy](/en-US/docs/Web/Security/Same-origin_policy) f ## See also -- [Cross-Origin Resource Sharing (CORS)](/en-US/docs/Web/HTTP/CORS) +- [Cross-Origin Resource Sharing (CORS)](/en-US/docs/Web/HTTP/Guides/CORS) - [Cross-origin resource sharing](https://en.wikipedia.org/wiki/Cross-origin_resource_sharing) on Wikipedia - [Fetch specification](https://fetch.spec.whatwg.org/) diff --git a/files/en-us/glossary/crawler/index.md b/files/en-us/glossary/crawler/index.md index 54998756bbab960..b5d26078e5ce702 100644 --- a/files/en-us/glossary/crawler/index.md +++ b/files/en-us/glossary/crawler/index.md @@ -6,7 +6,7 @@ page-type: glossary-definition {{GlossarySidebar}} -A **web crawler** is a program, often called a bot or robot, which systematically browses the {{glossary("World Wide Web","Web")}} to collect data from webpages. Typically search engines (e.g. Google, Bing, etc.) use crawlers to build indexes. +A **web crawler** is a program, often called a bot or robot, which systematically browses the {{glossary("World Wide Web","Web")}} to collect data from webpages. Typically search engines (e.g., Google, Bing, etc.) use crawlers to build indexes. ## See also diff --git a/files/en-us/glossary/cross-site_scripting/index.md b/files/en-us/glossary/cross-site_scripting/index.md index 0fd20009dbf4098..948d6d3d4742d74 100644 --- a/files/en-us/glossary/cross-site_scripting/index.md +++ b/files/en-us/glossary/cross-site_scripting/index.md @@ -6,13 +6,17 @@ page-type: glossary-definition {{GlossarySidebar}} -**Cross-site scripting** (XSS) is a security exploit which allows an attacker to inject into a website malicious client-side code. This code is executed by the victims and lets the attackers bypass access controls and impersonate users. According to the Open Web Application Security Project, XSS was the [seventh most common Web app vulnerability](<https://owasp.org/www-project-top-ten/OWASP_Top_Ten_2017/Top_10-2017_A7-Cross-Site_Scripting_(XSS)>) in 2017. +A **cross-site scripting** (XSS) attack is one in which an attacker is able to get a target site to execute malicious code as though it was part of the website. The code can then do anything that the site's own code can do. For example, the attacker could: -These attacks succeed if the Web app does not employ enough validation or encoding. The user's browser cannot detect the malicious script is untrustworthy, and so gives it access to any cookies, session tokens, or other sensitive site-specific information, or lets the malicious script rewrite the {{glossary("HTML")}} content. +- Access and modify all the content of the site's loaded pages, and any content in local storage +- Make HTTP requests with the user's credentials, enabling them to impersonate the user or access sensitive data + +All XSS attacks depend on a website doing two things: + +1. Accepting some input that could have been crafted by an attacker +2. Including this input in a page without sanitizing it: that is, without ensuring that it won't be executable as JavaScript ## See also -- [Type of Attacks: Cross-site scripting (XSS)](/en-US/docs/Web/Security/Types_of_attacks#cross-site_scripting_xss) -- [Cross-site scripting](https://en.wikipedia.org/wiki/Cross-site_scripting) on Wikipedia +- [Cross-site scripting (XSS)](/en-US/docs/Web/Security/Attacks/XSS) - [Cross-site scripting on OWASP](https://owasp.org/www-community/attacks/xss/) -- [Another article about Cross-site scripting](https://www.acunetix.com/blog/articles/dom-xss-explained/) diff --git a/files/en-us/glossary/cryptographic_hash_function/index.md b/files/en-us/glossary/cryptographic_hash_function/index.md deleted file mode 100644 index 5e1a2c2c65e3f96..000000000000000 --- a/files/en-us/glossary/cryptographic_hash_function/index.md +++ /dev/null @@ -1,24 +0,0 @@ ---- -title: Cryptographic hash function -slug: Glossary/Cryptographic_hash_function -page-type: glossary-definition ---- - -{{GlossarySidebar}} - -A **cryptographic hash function**, also sometimes called a _digest function_, is a {{glossary("cryptography", "cryptographic")}} primitive transforming a message of arbitrary size into a message of fixed size, called a {{glossary("digest")}}. Cryptographic hash functions are used for authentication, {{Glossary("digital signature", "digital signatures")}}, and {{Glossary("HMAC", "message authentication codes")}}. - -To be used for cryptography, a hash function must have these qualities: - -- quick to compute (because they are generated frequently) -- not invertible (each digest could come from a very large number of messages, and only brute-force can generate a message that leads to a given digest) -- tamper-resistant (any change to a message leads to a different digest) -- collision-resistant (it should be impossible to find two different messages that produce the same digest) - -Cryptographic hash functions such as MD5 and SHA-1 are considered broken, as attacks have been found that significantly reduce their collision resistance. - -## See also - -- [Cryptographic hash function](https://en.wikipedia.org/wiki/Cryptographic_hash_function) on Wikipedia -- Related glossary terms: - - {{Glossary("Symmetric-key cryptography")}} diff --git a/files/en-us/glossary/csp/index.md b/files/en-us/glossary/csp/index.md index cdcde736beff1ac..0eef1b8a5487a7b 100644 --- a/files/en-us/glossary/csp/index.md +++ b/files/en-us/glossary/csp/index.md @@ -6,11 +6,11 @@ page-type: glossary-definition {{GlossarySidebar}} -A **CSP** ([Content Security Policy](/en-US/docs/Web/HTTP/CSP)) is used to detect and mitigate certain types of website related attacks like {{Glossary("Cross-site_scripting")}}, [clickjacking](/en-US/docs/Web/Security/Attacks/Clickjacking) and data injections. +A **CSP** ([Content Security Policy](/en-US/docs/Web/HTTP/Guides/CSP)) is used to detect and mitigate certain types of website related attacks like {{Glossary("Cross-site_scripting")}}, [clickjacking](/en-US/docs/Web/Security/Attacks/Clickjacking) and data injections. The implementation is based on an {{Glossary("HTTP")}} header called {{HTTPHeader("Content-Security-Policy")}}. ## See also -- [Content Security Policy documentation](/en-US/docs/Web/HTTP/CSP) +- [Content Security Policy documentation](/en-US/docs/Web/HTTP/Guides/CSP) - [Content Security Policy on Wikipedia](https://en.wikipedia.org/wiki/Content_Security_Policy) diff --git a/files/en-us/glossary/csrf/index.md b/files/en-us/glossary/csrf/index.md index e94de29e2d41bb1..9f8d54152cbbec3 100644 --- a/files/en-us/glossary/csrf/index.md +++ b/files/en-us/glossary/csrf/index.md @@ -1,24 +1,22 @@ --- -title: CSRF +title: Cross-site request forgery (CSRF) slug: Glossary/CSRF page-type: glossary-definition --- {{GlossarySidebar}} -**CSRF** (Cross-Site Request Forgery) is an attack that impersonates a trusted user and sends a website unwanted commands. +In a **cross-site request forgery** (CSRF) attack, an attacker tricks the browser into making an HTTP request to the target site from a malicious site. The request includes the user's credentials and causes the server to carry out some harmful action, thinking that the user intended it. -This can be done, for example, by including malicious parameters in a {{glossary("URL")}} behind a link that purports to go somewhere else: +A CSRF attack is possible if a website: -```html -<img src="https://www.example.com/index.php?action=delete&id=123" /> -``` +- Uses HTTP requests to change some state on the server +- Uses only cookies to validate that the request came from an authenticated user +- Uses only parameters in the request that an attacker can predict -For users who have modification permissions on `https://www.example.com`, the `<img>` element executes action on `https://www.example.com` without their noticing, even if the element is not at `https://www.example.com`. - -There are many ways to prevent CSRF, such as implementing {{glossary("REST", "RESTful API")}}, adding secure tokens, etc. +There are several defenses against CSRF attacks, including [CSRF tokens](/en-US/docs/Web/Security/Attacks/CSRF#csrf_tokens), using [fetch metadata](/en-US/docs/Web/Security/Attacks/CSRF#fetch_metadata) to block certain cross-site requests, and [setting the `SameSite` attribute](/en-US/docs/Web/Security/Attacks/CSRF#defense_in_depth_samesite_cookies) on cookies used to authenticate sensitive requests. ## See also -- [Cross-site request forgery](https://en.wikipedia.org/wiki/Cross-site_request_forgery) on Wikipedia -- [Prevention measures](https://cheatsheetseries.owasp.org/cheatsheets/Cross-Site_Request_Forgery_Prevention_Cheat_Sheet.html) +- [Cross-site request forgery](/en-US/docs/Web/Security/Attacks/CSRF) +- [Cross-Site Request Forgery Prevention Cheat Sheet](https://cheatsheetseries.owasp.org/cheatsheets/Cross-Site_Request_Forgery_Prevention_Cheat_Sheet.html) at [owasp.org](https://owasp.org/) diff --git a/files/en-us/glossary/css_selector/index.md b/files/en-us/glossary/css_selector/index.md index a9741c444874a73..068ef64565644d7 100644 --- a/files/en-us/glossary/css_selector/index.md +++ b/files/en-us/glossary/css_selector/index.md @@ -34,7 +34,7 @@ div.warning { } ``` -The selectors here are `"p"` (which applies the color green to the text inside any {{HTMLElement("p")}} element), `"div.warning"` (which makes any {{HTMLElement("div")}} element with the [class](/en-US/docs/Web/HTML/Global_attributes/class) `"warning"` look like a warning box), and `"#customized"`, which sets the base font of the element with the ID `"customized"` to 16-pixel tall Lucida Grande or one of a few fallback fonts. +The selectors here are `"p"` (which applies the color green to the text inside any {{HTMLElement("p")}} element), `"div.warning"` (which makes any {{HTMLElement("div")}} element with the [class](/en-US/docs/Web/HTML/Reference/Global_attributes/class) `"warning"` look like a warning box), and `"#customized"`, which sets the base font of the element with the ID `"customized"` to 16-pixel tall Lucida Grande or one of a few fallback fonts. We can then apply this CSS to some HTML, such as: diff --git a/files/en-us/glossary/deserialization/index.md b/files/en-us/glossary/deserialization/index.md index e844bb9f3e9c534..ec7b99f42b03f38 100644 --- a/files/en-us/glossary/deserialization/index.md +++ b/files/en-us/glossary/deserialization/index.md @@ -6,7 +6,7 @@ page-type: glossary-definition {{GlossarySidebar}} -**Deserialization** is the process whereby a lower-level format (e.g. that has been transferred over a network, or stored in a data store) is translated into a readable object or other data structure. +**Deserialization** is the process whereby a lower-level format (e.g., that has been transferred over a network, or stored in a data store) is translated into a readable object or other data structure. In {{Glossary("JavaScript")}}, for example, you can deserialize a {{Glossary("JSON")}} {{Glossary("string")}} to an object by calling the {{Glossary("function")}} {{jsxref("JSON.parse()")}}. diff --git a/files/en-us/glossary/device_pixel/index.md b/files/en-us/glossary/device_pixel/index.md index 16834c649e2d886..eb8bc753b67ac48 100644 --- a/files/en-us/glossary/device_pixel/index.md +++ b/files/en-us/glossary/device_pixel/index.md @@ -15,4 +15,4 @@ A device pixel is density-dependent, varying based on the display resolution. Th - CSS {{cssxref("&lt;resolution&gt;")}} data type - CSS {{cssxref("@media/resolution", "resolution")}} @media feature - CSS {{cssxref("image-resolution")}} property -- {{domxref("devicePixelRatio")}} API +- {{domxref("Window.devicePixelRatio")}} API diff --git a/files/en-us/glossary/digest/index.md b/files/en-us/glossary/digest/index.md deleted file mode 100644 index 94f2d52c92f3616..000000000000000 --- a/files/en-us/glossary/digest/index.md +++ /dev/null @@ -1,24 +0,0 @@ ---- -title: Digest -slug: Glossary/Digest -page-type: glossary-definition ---- - -{{GlossarySidebar}} - -A **digest** is a small value generated by a {{glossary("cryptographic hash function", "hash function")}} from a whole message. Ideally, a digest is quick to calculate, irreversible, and unpredictable, and therefore indicates whether someone has tampered with a given message. - -A digest can be used to perform several tasks: - -- in non-cryptographic applications (e.g., the index of hash tables, or a fingerprint used to detect duplicate data or to uniquely identify files) -- verify message integrity (a tampered message will have a different hash) -- store passwords so that they can't be retrieved, but can still be checked (To do this securely, you also need to salt the password.) -- generate pseudo-random numbers -- generate {{glossary("key","keys")}} - -It is critical to choose the proper hash function for your use case to avoid collisions and predictability. - -## See also - -- See {{glossary("Cryptographic hash function")}} -- [Hash function](https://en.wikipedia.org/wiki/Cryptographic_hash_function) on Wikipedia diff --git a/files/en-us/glossary/digital_signature/index.md b/files/en-us/glossary/digital_signature/index.md index bde863c28e3cbbd..a34ebb65846955d 100644 --- a/files/en-us/glossary/digital_signature/index.md +++ b/files/en-us/glossary/digital_signature/index.md @@ -10,7 +10,7 @@ A **digital signature** is an object that can be used to {{glossary("authenticat Digital signatures are usually based on {{glossary("public-key cryptography")}}, in which a key is created as a pair of keys, with the property that, if some input is encrypted with one key, it can only be decrypted with the other key, and vice versa. -The creator of the key pair makes one of the keys public and keeps the other one private. To sign a document, the key pair's owner creates a {{glossary("hash")}} of the document and encrypts it with the private key. +The creator of the key pair makes one of the keys public and keeps the other one private. To sign a document, the key pair's owner creates a {{glossary("hash function", "hash")}} of the document and encrypts it with the private key. The document and signature are sent to the verifier, who hashes the document, retrieves the public key, and decrypts the signature: if this matches the hash, then the signature has been verified, and the verifier can be confident that it was created by an entity with access to the private key. @@ -26,5 +26,5 @@ Verifiers often use {{glossary("digital certificate", "digital certificates")}} - Related glossary terms: - {{glossary("Digital certificate")}} - - {{glossary("Hash")}} + - {{glossary("Hash function")}} - {{glossary("Public-key cryptography")}} diff --git a/files/en-us/glossary/doctype/index.md b/files/en-us/glossary/doctype/index.md index 18ba29e8af42019..0c40d4336510148 100644 --- a/files/en-us/glossary/doctype/index.md +++ b/files/en-us/glossary/doctype/index.md @@ -6,12 +6,12 @@ page-type: glossary-definition {{GlossarySidebar}} -In {{Glossary("HTML")}}, the **doctype** is the required `<!doctype html>` preamble found at the top of all documents. Its sole purpose is to prevent a {{Glossary("browser")}} from switching into so-called ["quirks mode"](/en-US/docs/Web/HTML/Quirks_Mode_and_Standards_Mode) when rendering a document; that is, the `<!doctype html>` doctype ensures that the browser makes a best-effort attempt at following the relevant specifications, rather than using a different rendering mode that is incompatible with some specifications. +In {{Glossary("HTML")}}, the **doctype** is the required `<!doctype html>` preamble found at the top of all documents. Its sole purpose is to prevent a {{Glossary("browser")}} from switching into so-called ["quirks mode"](/en-US/docs/Web/HTML/Guides/Quirks_mode_and_standards_mode) when rendering a document; that is, the `<!doctype html>` doctype ensures that the browser makes a best-effort attempt at following the relevant specifications, rather than using a different rendering mode that is incompatible with some specifications. The doctype is case-insensitive. The convention of MDN code examples is to use lowercase, but it's also common to write it as `<!DOCTYPE html>`. ## See also - [Definition of the DOCTYPE in the HTML specification](https://html.spec.whatwg.org/multipage/syntax.html#the-doctype) -- [Quirks Mode and Standards Mode](/en-US/docs/Web/HTML/Quirks_Mode_and_Standards_Mode) +- [Quirks Mode and Standards Mode](/en-US/docs/Web/HTML/Guides/Quirks_mode_and_standards_mode) - [Document.doctype](/en-US/docs/Web/API/Document/doctype), a JavaScript method that returns the doctype diff --git a/files/en-us/glossary/document_directive/index.md b/files/en-us/glossary/document_directive/index.md index 02a084228bf6229..b6e05136c12f9b5 100644 --- a/files/en-us/glossary/document_directive/index.md +++ b/files/en-us/glossary/document_directive/index.md @@ -10,7 +10,7 @@ In {{Glossary("CSP")}}, **document directives** are used in a {{HTTPHeader("Cont Document directives don't fall back to the {{CSP("default-src")}} directive. -See [Document directives](/en-US/docs/Web/HTTP/Headers/Content-Security-Policy#document_directives) for a complete list. +See [Document directives](/en-US/docs/Web/HTTP/Reference/Headers/Content-Security-Policy#document_directives) for a complete list. ## See also diff --git a/files/en-us/glossary/dom/index.md b/files/en-us/glossary/dom/index.md index 46d069114308669..5361c917a073082 100644 --- a/files/en-us/glossary/dom/index.md +++ b/files/en-us/glossary/dom/index.md @@ -6,7 +6,7 @@ page-type: glossary-definition {{GlossarySidebar}} -The **DOM** (Document Object Model) is an {{glossary("API")}} that represents and interacts with any {{glossary("HTML")}} or {{glossary("XML")}}-based markup language document. The DOM is a document model loaded in the {{glossary("browser")}} and representing the document as a {{Glossary("Node/DOM","node")}} tree, or **DOM tree**, where each node represents part of the document (e.g. an {{Glossary("element")}}, text string, or comment). +The **DOM** (Document Object Model) is an {{glossary("API")}} that represents and interacts with any {{glossary("HTML")}} or {{glossary("XML")}}-based markup language document. The DOM is a document model loaded in the {{glossary("browser")}} and representing the document as a {{Glossary("Node/DOM","node")}} tree, or **DOM tree**, where each node represents part of the document (e.g., an {{Glossary("element")}}, text string, or comment). The DOM is one of the most-used {{Glossary("API")}}s on the {{glossary("World Wide Web","Web")}} because it allows code running in a browser to access and interact with every node in the document. Nodes can be created, moved, and changed. Event listeners can be added to nodes and triggered on the occurrence of a given event. diff --git a/files/en-us/glossary/dominator/index.md b/files/en-us/glossary/dominator/index.md index 2150eecaf6686a0..56b7a946d35e302 100644 --- a/files/en-us/glossary/dominator/index.md +++ b/files/en-us/glossary/dominator/index.md @@ -14,4 +14,4 @@ This concept is important for {{Glossary("garbage collection")}} because it mean - [Dominator](<https://en.wikipedia.org/wiki/Dominator_(graph_theory)>) on Wikipedia - [Dominators](https://firefox-source-docs.mozilla.org/devtools-user/memory/dominators/index.html) -- [Garbage collection](/en-US/docs/Web/JavaScript/Memory_management#garbage_collection) +- [Garbage collection](/en-US/docs/Web/JavaScript/Guide/Memory_management#garbage_collection) diff --git a/files/en-us/glossary/dynamic_typing/index.md b/files/en-us/glossary/dynamic_typing/index.md index e5f86a2a8825692..71a07c228d3eda0 100644 --- a/files/en-us/glossary/dynamic_typing/index.md +++ b/files/en-us/glossary/dynamic_typing/index.md @@ -10,5 +10,5 @@ page-type: glossary-definition ## See also -- [JavaScript data types and data structures](/en-US/docs/Web/JavaScript/Data_structures) +- [JavaScript data types and data structures](/en-US/docs/Web/JavaScript/Guide/Data_structures) - [Type system](https://en.wikipedia.org/wiki/Type_system#DYNAMIC) on Wikipedia diff --git a/files/en-us/glossary/endianness/index.md b/files/en-us/glossary/endianness/index.md index 80ecb7a2aa52c85..397ca93c45443ce 100644 --- a/files/en-us/glossary/endianness/index.md +++ b/files/en-us/glossary/endianness/index.md @@ -8,11 +8,11 @@ page-type: glossary-definition **Endian** and **endianness** (or "byte-order") describe how computers organize the bytes that make up numbers. -Each memory storage location has an index or address. Every byte can store an 8-bit number (i.e. between `0x00` and `0xff`), so you must reserve more than one byte to store a larger number. By far the most common _ordering_ of multiple bytes in one number is the **little-endian**, which is used on all Intel processors. Little-endian means storing bytes in order of least-to-most-significant (where the least significant byte takes the first or lowest address), comparable to a common European way of writing dates (e.g., 31 December 2050). +Each memory storage location has an index or address. Every byte can store an 8-bit number (i.e., between `0x00` and `0xff`), so you must reserve more than one byte to store a larger number. By far the most common _ordering_ of multiple bytes in one number is the **little-endian**, which is used on all Intel processors. Little-endian means storing bytes in order of least-to-most-significant (where the least significant byte takes the first or lowest address), comparable to a common European way of writing dates (e.g., 31 December 2050). Naturally, **big-endian** is the opposite order, comparable to an ISO date (2050-12-31). Big-endian is also often called "network byte order", because Internet standards usually require data to be stored big-endian, starting at the standard UNIX socket level and going all the way up to standardized Web binary data structures. Also, older Mac computers using 68000-series and PowerPC microprocessors formerly used big-endian. -Examples with the number `0x12345678` (i.e. 305 419 896 in decimal): +Examples with the number `0x12345678` (i.e., 305 419 896 in decimal): - _little-endian_: `0x78 0x56 0x34 0x12` - _big-endian_: `0x12 0x34 0x56 0x78` diff --git a/files/en-us/glossary/engine/javascript/index.md b/files/en-us/glossary/engine/javascript/index.md index cf49b0d53991494..c923e686ec30c47 100644 --- a/files/en-us/glossary/engine/javascript/index.md +++ b/files/en-us/glossary/engine/javascript/index.md @@ -21,7 +21,7 @@ Common JavaScript engines include: ## See also - [JavaScript engine](https://en.wikipedia.org/wiki/JavaScript_engine) on Wikipedia -- [JavaScript implementations](/en-US/docs/Web/JavaScript/JavaScript_technologies_overview#javascript_implementations) +- [JavaScript implementations](/en-US/docs/Web/JavaScript/Reference/JavaScript_technologies_overview#javascript_implementations) - Related glossary terms: - {{glossary("Engine")}} - {{glossary("JavaScript")}} diff --git a/files/en-us/glossary/entity_header/index.md b/files/en-us/glossary/entity_header/index.md index d8d80d70fd26478..f7eed7d3cbd04d5 100644 --- a/files/en-us/glossary/entity_header/index.md +++ b/files/en-us/glossary/entity_header/index.md @@ -9,7 +9,7 @@ page-type: glossary-definition > [!WARNING] > The current HTTP/1.1 specification no longer refers to entities, entity headers or entity-body. Some of the fields are now referred to as {{glossary("Representation header")}} fields. -An entity header is an {{glossary("HTTP_header", "HTTP header")}} that describes the {{Glossary("HTTP content", "content")}} of an HTTP message (i.e. metadata about the message body). Entity headers include: {{HTTPHeader("Content-Length")}}, {{HTTPHeader("Content-Language")}}, {{HTTPHeader("Content-Encoding")}}, {{HTTPHeader("Content-Type")}}, {{HTTPHeader("Expires")}}, etc. Entity headers may be present in both HTTP request and response messages. +An entity header is an {{glossary("HTTP_header", "HTTP header")}} that describes the {{Glossary("HTTP content", "content")}} of an HTTP message (i.e., metadata about the message body). Entity headers include: {{HTTPHeader("Content-Length")}}, {{HTTPHeader("Content-Language")}}, {{HTTPHeader("Content-Encoding")}}, {{HTTPHeader("Content-Type")}}, {{HTTPHeader("Expires")}}, etc. Entity headers may be present in both HTTP request and response messages. In the following example, {{HTTPHeader("Content-Length")}} is an entity header, while {{HTTPHeader("Host")}} and {{HTTPHeader("User-Agent")}} are requests headers: diff --git a/files/en-us/glossary/enumerated/index.md b/files/en-us/glossary/enumerated/index.md index f0581074480e35a..3d1831032cedc05 100644 --- a/files/en-us/glossary/enumerated/index.md +++ b/files/en-us/glossary/enumerated/index.md @@ -10,9 +10,9 @@ In computer science, an **enumerated** type is a data type consisting of a limit ## HTML enumerated attributes -In HTML, [enumerated attributes](https://html.spec.whatwg.org/multipage/common-microsyntaxes.html#enumerated-attribute) are attributes with a limited, predefined set of text values. For example, the global HTML [`dir`](/en-US/docs/Web/HTML/Global_attributes/dir) attribute has three valid values: `ltr`, `rtl`, and `auto`. +In HTML, [enumerated attributes](https://html.spec.whatwg.org/multipage/common-microsyntaxes.html#enumerated-attribute) are attributes with a limited, predefined set of text values. For example, the global HTML [`dir`](/en-US/docs/Web/HTML/Reference/Global_attributes/dir) attribute has three valid values: `ltr`, `rtl`, and `auto`. -Each enumerated attribute has a default value for when the attribute is present without a value (the value is missing), and a default value for when the attribute is assigned an invalid value. Unlike {{Glossary("Boolean/HTML", "Boolean attribute")}} HTML attributes — which are always true when the attribute is present whether the value is present, omitted, or invalid — with enumerated HTML attributes, the default for an omitted value may be different from the default for invalid values. For example, the global HTML [`contenteditable`](/en-US/docs/Web/HTML/Global_attributes/contenteditable) attribute has two valid keywords: `true` and `false`. If the attribute is present but no value is set, the value is `true`. If a value is set, but is invalid, such as `contenteditable="contenteditable"`, the value maps to a third state, `inherit`. +Each enumerated attribute has a default value for when the attribute is present without a value (the value is missing), and a default value for when the attribute is assigned an invalid value. Unlike {{Glossary("Boolean/HTML", "Boolean attribute")}} HTML attributes — which are always true when the attribute is present whether the value is present, omitted, or invalid — with enumerated HTML attributes, the default for an omitted value may be different from the default for invalid values. For example, the global HTML [`contenteditable`](/en-US/docs/Web/HTML/Reference/Global_attributes/contenteditable) attribute has two valid keywords: `true` and `false`. If the attribute is present but no value is set, the value is `true`. If a value is set, but is invalid, such as `contenteditable="contenteditable"`, the value maps to a third state, `inherit`. ## ARIA enumerated attributes @@ -27,5 +27,5 @@ In JavaScript, enumerable properties are those properties whose internal enumera ## See also - {{Glossary("Boolean")}} -- [JavaScript data types and data structures](/en-US/docs/Web/JavaScript/Data_structures) +- [JavaScript data types and data structures](/en-US/docs/Web/JavaScript/Guide/Data_structures) - [enumerated attributes](https://html.spec.whatwg.org/multipage/common-microsyntaxes.html#enumerated-attribute) in the HTML Standard diff --git a/files/en-us/glossary/favicon/index.md b/files/en-us/glossary/favicon/index.md index dfef5a21be64485..f169898abecd917 100644 --- a/files/en-us/glossary/favicon/index.md +++ b/files/en-us/glossary/favicon/index.md @@ -17,7 +17,7 @@ They are used to improve user experience and enforce brand consistency. When a f ## See also - [Favicon](https://en.wikipedia.org/wiki/Favicon) on Wikipedia -- The [link rel="icon"](/en-US/docs/Web/HTML/Attributes/rel#icon) element documentation, used to add a favicon to a page. +- The [link rel="icon"](/en-US/docs/Web/HTML/Reference/Attributes/rel#icon) element documentation, used to add a favicon to a page. - Tools - [Free favicon generator](https://favicon.io/) diff --git a/files/en-us/glossary/federated_identity/index.md b/files/en-us/glossary/federated_identity/index.md index dada45ffcd73adc..ecd39581635b098 100644 --- a/files/en-us/glossary/federated_identity/index.md +++ b/files/en-us/glossary/federated_identity/index.md @@ -8,7 +8,7 @@ page-type: glossary-definition A **federated identity** system is one in which an {{glossary("identity provider", "identity provider (IdP)")}} acts as an intermediary between users and {{glossary("relying party", "relying parties")}}, enabling a user to use a single set of {{glossary("credential", "credentials")}} to authenticate with a number of different relying parties. -Traditionally, on the web, a user will sign into a website with a username and a password, and the password is verified by the website against a (properly {{glossary("hash", "hashed")}} and {{glossary("salt", "salted")}}) copy stored on the website's backend. +Traditionally, on the web, a user will sign into a website with a username and a password, and the password is verified by the website against a (properly {{glossary("hash function", "hashed")}} and {{glossary("salt", "salted")}}) copy stored on the website's backend. In this model, if users have multiple accounts with different websites, they have to remember many passwords, and this encourages bad password practices such as using the same password for multiple accounts. diff --git a/files/en-us/glossary/fetch_directive/index.md b/files/en-us/glossary/fetch_directive/index.md index 849d942b1ab6228..2e1046bb65af777 100644 --- a/files/en-us/glossary/fetch_directive/index.md +++ b/files/en-us/glossary/fetch_directive/index.md @@ -10,7 +10,7 @@ page-type: glossary-definition All fetch directives fall back to {{CSP("default-src")}}. That means, if a fetch directive is absent in the CSP header, the user agent will look for the `default-src` directive. -See [Fetch directives](/en-US/docs/Web/HTTP/Headers/Content-Security-Policy#fetch_directives) for a complete list. +See [Fetch directives](/en-US/docs/Web/HTTP/Reference/Headers/Content-Security-Policy#fetch_directives) for a complete list. ## See also diff --git a/files/en-us/glossary/fetch_metadata_request_header/index.md b/files/en-us/glossary/fetch_metadata_request_header/index.md index b0298dd13192d2e..6c06dd422a03307 100644 --- a/files/en-us/glossary/fetch_metadata_request_header/index.md +++ b/files/en-us/glossary/fetch_metadata_request_header/index.md @@ -29,8 +29,8 @@ A server might use them to modify its caching behavior, or the information that - [Protect your resources from web attacks with Fetch Metadata](https://web.dev/articles/fetch-metadata) (web.dev) - [Fetch Metadata Request Headers playground](https://secmetadata.appspot.com/) (secmetadata.appspot.com) -- [List of all HTTP headers](/en-US/docs/Web/HTTP/Headers) -- [List of all HTTP headers > Fetch metadata request headers](/en-US/docs/Web/HTTP/Headers#fetch_metadata_request_headers) +- [List of all HTTP headers](/en-US/docs/Web/HTTP/Reference/Headers) +- [List of all HTTP headers > Fetch metadata request headers](/en-US/docs/Web/HTTP/Reference/Headers#fetch_metadata_request_headers) - Related glossary terms: - {{Glossary("Representation header")}} - {{Glossary("HTTP_header","HTTP header")}} diff --git a/files/en-us/glossary/forbidden_request_header/index.md b/files/en-us/glossary/forbidden_request_header/index.md index c022d732070d6e9..52e857c611c790d 100644 --- a/files/en-us/glossary/forbidden_request_header/index.md +++ b/files/en-us/glossary/forbidden_request_header/index.md @@ -6,7 +6,7 @@ page-type: glossary-definition {{GlossarySidebar}} -A **forbidden request header** is an [HTTP header](/en-US/docs/Web/HTTP/Headers) name-value pair that cannot be set or modified programmatically in a request. For headers forbidden to be modified in responses, see {{Glossary("forbidden response header name")}}. +A **forbidden request header** is an [HTTP header](/en-US/docs/Web/HTTP/Reference/Headers) name-value pair that cannot be set or modified programmatically in a request. For headers forbidden to be modified in responses, see {{Glossary("forbidden response header name")}}. Modifying such headers is forbidden because the user agent retains full control over them. For example, the {{HTTPHeader("Date")}} header is a forbidden request header, so this code cannot set the message `Date` field: @@ -22,7 +22,7 @@ fetch("https://httpbin.org/get", { Names starting with `Sec-` are reserved for creating new headers safe from {{glossary("API","APIs")}} that grant developers control over headers, such as {{domxref("Window/fetch", "fetch()")}}. Forbidden headers are one of the following: -- {{HTTPHeader("Accept-Charset")}} +- `Accept-Charset` - {{HTTPHeader("Accept-Encoding")}} - {{HTTPHeader("Access-Control-Request-Headers")}} - {{HTTPHeader("Access-Control-Request-Method")}} diff --git a/files/en-us/glossary/forbidden_response_header_name/index.md b/files/en-us/glossary/forbidden_response_header_name/index.md index 9d532f8cda5f2f4..45e7ab64939780d 100644 --- a/files/en-us/glossary/forbidden_response_header_name/index.md +++ b/files/en-us/glossary/forbidden_response_header_name/index.md @@ -6,7 +6,7 @@ page-type: glossary-definition {{GlossarySidebar}} -A _forbidden response header name_ is an [HTTP header](/en-US/docs/Web/HTTP/Headers) name (`Set-Cookie`) that cannot be modified programmatically. +A _forbidden response header name_ is an [HTTP header](/en-US/docs/Web/HTTP/Reference/Headers) name (`Set-Cookie`) that cannot be modified programmatically. ## See also diff --git a/files/en-us/glossary/ftu/index.md b/files/en-us/glossary/ftu/index.md index 9b8a33c04192e42..c1ef74528d38654 100644 --- a/files/en-us/glossary/ftu/index.md +++ b/files/en-us/glossary/ftu/index.md @@ -8,4 +8,4 @@ page-type: glossary-definition FTU (First Time Use) is the app that loads when you run a newly-installed version of {{glossary("Gecko")}} on a {{glossary("Firefox OS")}} device. -You can use FTU to set many important options (e.g. timezone, Wi-Fi details, default language, importing contacts), or take the "Phone Tour" to find out more about your device. +You can use FTU to set many important options (e.g., timezone, Wi-Fi details, default language, importing contacts), or take the "Phone Tour" to find out more about your device. diff --git a/files/en-us/glossary/function/index.md b/files/en-us/glossary/function/index.md index 47759a56beb1a8b..6af5486f9b15105 100644 --- a/files/en-us/glossary/function/index.md +++ b/files/en-us/glossary/function/index.md @@ -87,9 +87,9 @@ Function expressions, named or anonymous, can be called immediately. Declared functions can't be called immediately this way, because IIFEs must be function _expressions_. -```js example-bad +```js-nolint example-bad function foo() { - console.log('Hello Foo'); + console.log("Hello Foo"); }(); ``` diff --git a/files/en-us/glossary/garbage_collection/index.md b/files/en-us/glossary/garbage_collection/index.md index 3aed10fc8c533db..9aa39f7cf31a76f 100644 --- a/files/en-us/glossary/garbage_collection/index.md +++ b/files/en-us/glossary/garbage_collection/index.md @@ -6,13 +6,13 @@ page-type: glossary-definition {{GlossarySidebar}} -**[Garbage collection](/en-US/docs/Web/JavaScript/Memory_management#garbage_collection)** is a term used in {{Glossary("computer programming")}} to describe the process of finding and deleting {{Glossary("object", "objects")}} which are no longer being {{Glossary("object reference", "referenced")}} by other objects. +**[Garbage collection](/en-US/docs/Web/JavaScript/Guide/Memory_management#garbage_collection)** is a term used in {{Glossary("computer programming")}} to describe the process of finding and deleting {{Glossary("object", "objects")}} which are no longer being {{Glossary("object reference", "referenced")}} by other objects. -In other words, garbage collection is the process of removing any objects which are not being used by any other objects. Often abbreviated "GC," garbage collection is a fundamental component of the [memory management](/en-US/docs/Web/JavaScript/Memory_management) system used by {{Glossary("JavaScript")}}. +In other words, garbage collection is the process of removing any objects which are not being used by any other objects. Often abbreviated "GC," garbage collection is a fundamental component of the [memory management](/en-US/docs/Web/JavaScript/Guide/Memory_management) system used by {{Glossary("JavaScript")}}. ## See also - [Memory management](https://en.wikipedia.org/wiki/Memory_management) on Wikipedia - [Garbage collection (computer science)](<https://en.wikipedia.org/wiki/Garbage_collection_(computer_science)>) on Wikipedia -- [Garbage collection](/en-US/docs/Web/JavaScript/Memory_management#garbage_collection) in the MDN JavaScript guide. -- [Memory management in JavaScript](/en-US/docs/Web/JavaScript/Memory_management) +- [Garbage collection](/en-US/docs/Web/JavaScript/Guide/Memory_management#garbage_collection) in the MDN JavaScript guide. +- [Memory management in JavaScript](/en-US/docs/Web/JavaScript/Guide/Memory_management) diff --git a/files/en-us/glossary/general_header/index.md b/files/en-us/glossary/general_header/index.md index acf786ab11c18e5..af0f89844bb6d80 100644 --- a/files/en-us/glossary/general_header/index.md +++ b/files/en-us/glossary/general_header/index.md @@ -6,7 +6,7 @@ page-type: glossary-definition {{GlossarySidebar}} -**General header** is an outdated term used to refer to an {{glossary('HTTP_header', 'HTTP header')}} that can be used in both request and response messages, but which doesn't apply to the content itself (a header that applied to the content was called an {{glossary("entity header")}}). Depending on the context they are used in, general headers might either be {{glossary("Response header", "response")}} or {{glossary("request header", "request headers")}} (e.g. {{HTTPheader("Cache-Control")}}). +**General header** is an outdated term used to refer to an {{glossary('HTTP_header', 'HTTP header')}} that can be used in both request and response messages, but which doesn't apply to the content itself (a header that applied to the content was called an {{glossary("entity header")}}). Depending on the context they are used in, general headers might either be {{glossary("Response header", "response")}} or {{glossary("request header", "request headers")}} (e.g., {{HTTPheader("Cache-Control")}}). > [!NOTE] > Current versions of the HTTP/1.1 specification do not specifically categorize headers as "general headers". These are now simply referred to as {{glossary("Response header", "response")}} or {{glossary("request header", "request headers")}} depending on context. diff --git a/files/en-us/glossary/hash/index.md b/files/en-us/glossary/hash/index.md deleted file mode 100644 index aa20f975176823c..000000000000000 --- a/files/en-us/glossary/hash/index.md +++ /dev/null @@ -1,13 +0,0 @@ ---- -title: Hash -slug: Glossary/Hash -page-type: glossary-definition ---- - -{{GlossarySidebar}} - -The hash function takes a variable-length message input and produces a fixed-length hash output. It is commonly in the form of a 128-bit "fingerprint" or "message digest". Hashes are very useful for {{glossary("cryptography")}} — they ensure the integrity of transmitted data, and provide the basis for {{glossary("HMAC")}}, which enables message authentication. - -## See also - -- [Hash function](https://en.wikipedia.org/wiki/Hash_function) on Wikipedia diff --git a/files/en-us/glossary/hash_function/index.md b/files/en-us/glossary/hash_function/index.md new file mode 100644 index 000000000000000..82de9aed868c59e --- /dev/null +++ b/files/en-us/glossary/hash_function/index.md @@ -0,0 +1,36 @@ +--- +title: Hash function +slug: Glossary/Hash_function +page-type: glossary-definition +--- + +{{GlossarySidebar}} + +A hash function is a function that takes a variable-length input and produces a fixed-length output, also called a _digest_ (or just a "hash"). Hash functions should be quick to compute, and different inputs should as far as possible produce different outputs (this is called _collision-resistance_). + +Hash functions have both {{glossary("cryptography", "cryptographic")}} and non-cryptographic uses. Outside cryptography, for example, hash functions can be used to generate the keys for an associative array such as a map or a dictionary. + +The {{domxref("SubtleCrypto.digest()", "digest()")}} function of the {{domxref("SubtleCrypto")}} interface makes various hash functions available to web applications. + +## Cryptographic hash functions + +In cryptography, hash functions have many applications, including {{Glossary("digital signature", "digital signatures")}}, and {{Glossary("HMAC", "message authentication codes")}}. + +Not all hash functions are appropriate for cryptography. To be used for cryptography, a hash function must be: + +- quick to compute +- one-way: given the output, it should be impractical or impossible to regenerate the original input +- tamper-resistant: any change to the input leads to a different output +- collision-resistant: it should be impractical to find two different inputs that produce the same output + +The hash functions most commonly used in cryptography are from the _SHA-2_ (Secure Hash Algorithm 2) family, whose names are `"SHA-"` followed by the length of the output digest in bits: for example, `"SHA-256"` and `"SHA-512"`. + +SHA-2 is the successor to the SHA-1 algorithm, which is no longer considered secure and should not be used in cryptography. Note that the MD5 algorithm is also considered insecure. + +## See also + +- {{domxref("SubtleCrypto.digest()")}} +- [Hash function](https://en.wikipedia.org/wiki/Hash_function) on Wikipedia +- [Cryptographic hash function](https://en.wikipedia.org/wiki/Cryptographic_hash_function) on Wikipedia +- Related glossary terms: + - {{Glossary("Symmetric-key cryptography")}} diff --git a/files/en-us/glossary/head/index.md b/files/en-us/glossary/head/index.md index 4fca48ef5736f2d..172cc83c3e5f40f 100644 --- a/files/en-us/glossary/head/index.md +++ b/files/en-us/glossary/head/index.md @@ -11,4 +11,4 @@ The **Head** is the part of an {{glossary("HTML")}} document that contains {{glo ## See also - {{htmlelement("head")}} element reference on MDN -- [What's in the head? Webpage metadata](/en-US/docs/Learn_web_development/Core/Structuring_content/Webpage_metadata) on the MDN Learning Area +- [What's in the head? Web page metadata](/en-US/docs/Learn_web_development/Core/Structuring_content/Webpage_metadata) on the MDN Learning Area diff --git a/files/en-us/glossary/hmac/index.md b/files/en-us/glossary/hmac/index.md index 0d5c5c374b2aae1..ba99bc7d0d620e0 100644 --- a/files/en-us/glossary/hmac/index.md +++ b/files/en-us/glossary/hmac/index.md @@ -6,9 +6,9 @@ page-type: glossary-definition {{GlossarySidebar}} -**Hash-based message authentication code**(_HMAC_) is a protocol used for {{Glossary("cryptography", "cryptographically")}} authenticating messages. +**Hash-based message authentication code**(_HMAC_) is a mechanism used for {{Glossary("cryptography", "cryptographically")}} authenticating messages. -It can use any kind of {{Glossary("Cryptographic hash function", "cryptographic functions")}}, and its strength depends on the underlying function (SHA1 or MD5 for instance), and the chosen secret key. With such a combination, the HMAC verification {{Glossary("Algorithm", "algorithm")}} is then known with a compound name such as HMAC-SHA1. +It can use any kind of {{Glossary("Hash function", "cryptographic hash function")}}. Its strength depends on the underlying hash function and the chosen secret key. With such a combination, the HMAC verification {{Glossary("Algorithm", "algorithm")}} is then known with a compound name such as HMAC-SHA2. HMAC is used to ensure both integrity and authentication. diff --git a/files/en-us/glossary/html5/index.md b/files/en-us/glossary/html5/index.md index 2e96fc776bfc20f..c47177b6b319f10 100644 --- a/files/en-us/glossary/html5/index.md +++ b/files/en-us/glossary/html5/index.md @@ -10,7 +10,7 @@ The term HTML5 is essentially a buzzword that refers to a set of modern web tech You may sometimes hear about "new HTML5 elements", or find HTML5 described as a new version of HTML. HTML5 was the successor to previous HTML versions and introduced new elements and capabilities to the language on top of the previous version, HTML 4.01, as well as improving or removing some existing functionality. However, as a Living Standard HTML now has no version. The up-to-date specification can be found at [html.spec.whatwg.org/](https://html.spec.whatwg.org/). -Any modern site should use the [HTML doctype](/en-US/docs/MDN/Writing_guidelines/Writing_style_guide/Code_style_guide/HTML#doctype) — this will ensure that you are using the latest version of HTML. +Any modern site should use the [HTML doctype](/en-US/docs/MDN/Writing_guidelines/Code_style_guide/HTML#doctype) — this will ensure that you are using the latest version of HTML. > [!NOTE] > Until 2019, the {{glossary("W3C")}} published a competing HTML5 standard with version numbers. Since [28 May 2019](https://www.w3.org/blog/news/archives/7753), the WHATWG Living Standard was announced by the W3C as the sole version of HTML. diff --git a/files/en-us/glossary/http_2/index.md b/files/en-us/glossary/http_2/index.md index 7446d8dc907a269..f74eb110f87b728 100644 --- a/files/en-us/glossary/http_2/index.md +++ b/files/en-us/glossary/http_2/index.md @@ -12,7 +12,7 @@ The primary goals for HTTP/2 are to reduce {{glossary("latency")}} and {{glossar HTTP/2 also introduced a mechanism called Server Push, which allowed a server to send resources to a client in anticipation that the client would need them very soon. Server Push proved tricky to implement in practice, and has been removed from most major browser engines. -It has been replaced by alternative methods such as [`rel="preload"`](/en-US/docs/Web/HTML/Attributes/rel/preload) and {{HTTPStatus("103", "103 Early hints")}}. +It has been replaced by alternative methods such as [`rel="preload"`](/en-US/docs/Web/HTML/Reference/Attributes/rel/preload) and {{HTTPStatus("103", "103 Early hints")}}. HTTP/2 does not modify the semantics of HTTP, meaning the core concepts found in HTTP/1.1, such as methods, status codes, URIs, and header fields, remain the same. Instead, HTTP/2 modifies how the data is formatted (framed) and transported between the client and server, both of which manage the entire process, and hides protocol complexity within a framing layer. diff --git a/files/en-us/glossary/http_header/index.md b/files/en-us/glossary/http_header/index.md index 36585e5930a3b55..07f1fedc79fb73f 100644 --- a/files/en-us/glossary/http_header/index.md +++ b/files/en-us/glossary/http_header/index.md @@ -12,8 +12,8 @@ The HTTP and Fetch specifications refer to a number of header categories, includ - {{Glossary("Request header")}}: Headers containing more information about the resource to be fetched or about the client itself. - {{Glossary("Response header")}}: Headers with additional information about the response, like its location or about the server itself (name, version, …). -- {{Glossary("Representation header")}}: metadata about the resource in the message body (e.g. encoding, media type, etc.). -- {{Glossary("Fetch metadata request header")}}: Headers with metadata about the resource in the message body (e.g. encoding, media type, etc.). +- {{Glossary("Representation header")}}: metadata about the resource in the message body (e.g., encoding, media type, etc.). +- {{Glossary("Fetch metadata request header")}}: Headers with metadata about the resource in the message body (e.g., encoding, media type, etc.). A basic request with one header: @@ -55,7 +55,7 @@ X-Cache-Info: cached ## See also -- [List of all HTTP headers](/en-US/docs/Web/HTTP/Headers) +- [List of all HTTP headers](/en-US/docs/Web/HTTP/Reference/Headers) - Syntax of [headers](https://datatracker.ietf.org/doc/html/rfc7230#section-3.2) in the HTTP specification - Related glossary terms: - {{Glossary("Request header")}} diff --git a/files/en-us/glossary/hyperlink/index.md b/files/en-us/glossary/hyperlink/index.md index 0dfbcc2f4d1dcab..1ab95b53b80d48b 100644 --- a/files/en-us/glossary/hyperlink/index.md +++ b/files/en-us/glossary/hyperlink/index.md @@ -12,5 +12,5 @@ Hyperlinks connect webpages or data items to one another. In HTML, {{HTMLElement - [Hyperlink](https://en.wikipedia.org/wiki/Hyperlink) on Wikipedia - [Creating links](/en-US/docs/Learn_web_development/Core/Structuring_content/Creating_links) -- [`<a>` on MDN](/en-US/docs/Web/HTML/Element/a) -- [`<link>` on MDN](/en-US/docs/Web/HTML/Element/link) +- [`<a>` on MDN](/en-US/docs/Web/HTML/Reference/Elements/a) +- [`<link>` on MDN](/en-US/docs/Web/HTML/Reference/Elements/link) diff --git a/files/en-us/glossary/identifier/index.md b/files/en-us/glossary/identifier/index.md index 4bef18b22570c66..8de07b791d9a4b0 100644 --- a/files/en-us/glossary/identifier/index.md +++ b/files/en-us/glossary/identifier/index.md @@ -10,7 +10,7 @@ An **identifier** is a sequence of characters in the code that identifies a {{gl In {{glossary("JavaScript")}}, identifiers can contain {{glossary("Unicode")}} letters, `$`, `_`, and digits (0-9), but may not start with a digit. An identifier differs from a string in that a {{glossary("string")}} is data, while an identifier is part of the code. In JavaScript, there is no way to convert identifiers to strings, but sometimes it is possible to parse strings into identifiers. -In {{glossary("CSS")}}, there are two identifier data types: {{cssxref("custom-ident")}} and {{cssxref("dashed-ident")}}. The CSS {{cssxref("ident")}} can start with a digit and can contain almost any character, but non-letter/digit ASCII characters such as `"`, `\`, and `*` need to be escaped. Emojis, which are valid as identifiers, do not need to be escaped. +In {{glossary("CSS")}}, there are two identifier data types: {{cssxref("custom-ident")}} and {{cssxref("dashed-ident")}}. The CSS {{cssxref("ident")}} can contain almost any character, but non-letter/digit ASCII characters such as `"`, `\`, and `*` must be escaped, it must not start with a digit, and emojis are valid as identifiers that do not require escaping. ## See also diff --git a/files/en-us/glossary/idl/index.md b/files/en-us/glossary/idl/index.md index a8baecb7f11557c..4cbf591d5380f3e 100644 --- a/files/en-us/glossary/idl/index.md +++ b/files/en-us/glossary/idl/index.md @@ -25,5 +25,5 @@ IDL attributes can [reflect other types](https://html.spec.whatwg.org/multipage/ ## See also - [IDL](https://en.wikipedia.org/wiki/Interface_description_language) on Wikipedia -- [HTML attribute reference](/en-US/docs/Web/HTML/Attributes) +- [HTML attribute reference](/en-US/docs/Web/HTML/Reference/Attributes) - [Interface Definition Language](https://people.eecs.berkeley.edu/~messer/netappc/Supplements/10-idl.pdf) diff --git a/files/en-us/glossary/index.md b/files/en-us/glossary/index.md index 9f840a382ac2b3d..3acae7cad441f92 100644 --- a/files/en-us/glossary/index.md +++ b/files/en-us/glossary/index.md @@ -1,5 +1,5 @@ --- -title: "MDN Web Docs Glossary: Definitions of Web-related terms" +title: Glossary of web terms short-title: Glossary slug: Glossary page-type: landing-page @@ -7,9 +7,9 @@ page-type: landing-page {{GlossarySidebar}} -Web technologies contain long lists of jargon and abbreviations that are used in documentation and coding. This glossary provides definitions of words and abbreviations you need to know to successfully understand and build for the web. +Web technologies use many types of jargon, acronyms, and abbreviations in documentation, code, and other contexts. +This glossary provides definitions of words and abbreviations you need to know to successfully understand and build for the web. -Glossary terms can be selected from the sidebar. +Use the sidebar to browse through or jump to specific glossary terms. You can also use the search "Filter" at the top of the sidebar to quickly look for a term. -> [!NOTE] -> This glossary is a never-ending work in progress. You can help improve it by [writing new entries](/en-US/docs/MDN/Writing_guidelines/Howto/Write_a_new_entry_in_the_glossary) or by making the existing ones better. +You can help by contributing [new terms](/en-US/docs/MDN/Writing_guidelines/Howto/Write_a_new_entry_in_the_glossary) or improving the existing definitions. diff --git a/files/en-us/glossary/inheritance/index.md b/files/en-us/glossary/inheritance/index.md index efb6951ee2331bb..1fa2ccf49e0877c 100644 --- a/files/en-us/glossary/inheritance/index.md +++ b/files/en-us/glossary/inheritance/index.md @@ -12,4 +12,4 @@ As an app developer, you can choose which of the superclass's {{glossary("attrib ## See also -- [Inheritance and the prototype chain](/en-US/docs/Web/JavaScript/Inheritance_and_the_prototype_chain) +- [Inheritance and the prototype chain](/en-US/docs/Web/JavaScript/Guide/Inheritance_and_the_prototype_chain) diff --git a/files/en-us/glossary/ink_overflow/index.md b/files/en-us/glossary/ink_overflow/index.md index e8683f08cfa97a0..50c0503fe26828d 100644 --- a/files/en-us/glossary/ink_overflow/index.md +++ b/files/en-us/glossary/ink_overflow/index.md @@ -10,7 +10,7 @@ The **ink overflow** of a box refers to the part of the box and its contents tha Ink overflow is the overflow of painting effects such as [box shadows](/en-US/docs/Web/CSS/box-shadow), [border images](/en-US/docs/Web/CSS/CSS_backgrounds_and_borders), [text decoration](/en-US/docs/Web/CSS/CSS_text_decoration), [outlines](/en-US/docs/Web/CSS/outline), etc. that do not affect layout or otherwise extend the scrollable overflow area. Ink overflow is also the overhanging of glyphs, such as ascenders and descenders extending outside the em box. -As [replaced elements](/en-US/docs/Web/CSS/Replaced_element) always establish an independent [formatting context](/en-US/docs/Web/CSS/CSS_display/Introduction_to_formatting_contexts), any overflow of replaced content is always ink overflow (as opposed to [scrollable overflow](/en-US/docs/Learn_web_development/Core/Styling_basics/Overflow)). +As {{ glossary("replaced elements")}} always establish an independent [formatting context](/en-US/docs/Web/CSS/CSS_display/Introduction_to_formatting_contexts), any overflow of replaced content is always ink overflow (as opposed to [scrollable overflow](/en-US/docs/Learn_web_development/Core/Styling_basics/Overflow)). ## See also diff --git a/files/en-us/glossary/inline-level_content/index.md b/files/en-us/glossary/inline-level_content/index.md index ec9d9351e3c0b68..11aa63bcade445f 100644 --- a/files/en-us/glossary/inline-level_content/index.md +++ b/files/en-us/glossary/inline-level_content/index.md @@ -8,7 +8,7 @@ page-type: glossary-definition In CSS, content that participates in inline layout is called **inline-level content**. Most text sequences, replaced elements, and generated content are inline-level by default. -In inline layout, a mixed stream of text, [replaced elements](/en-US/docs/Web/CSS/Replaced_element), and other inline boxes are laid out by fragmenting them into a stack of line boxes. Within each line box, inline-level boxes are aligned to each other vertically or horizontally, depending on the writing mode. Typically, they are aligned by the baselines of their text. This can be changed with CSS. +In inline layout, a mixed stream of text, {{ glossary("replaced elements")}}, and other inline boxes are laid out by fragmenting them into a stack of line boxes. Within each line box, inline-level boxes are aligned to each other vertically or horizontally, depending on the writing mode. Typically, they are aligned by the baselines of their text. This can be changed with CSS. ![inline layout](inline_layout.png) @@ -46,5 +46,5 @@ body { - Related glossary terms: - {{Glossary("Block-level content")}} -- [Inline formatting context](/en-US/docs/Web/CSS/Inline_formatting_context) +- [Inline formatting context](/en-US/docs/Web/CSS/CSS_inline_layout/Inline_formatting_context) - {{cssxref("display")}} diff --git a/files/en-us/glossary/interaction_to_next_paint/index.md b/files/en-us/glossary/interaction_to_next_paint/index.md index a40d5578b0ff421..07707f03ddbb7ee 100644 --- a/files/en-us/glossary/interaction_to_next_paint/index.md +++ b/files/en-us/glossary/interaction_to_next_paint/index.md @@ -24,5 +24,5 @@ The longer the delay, the worse the user experience. The [Long Animation Frames - [Long animation frame timing](/en-US/docs/Web/API/Performance_API/Long_animation_frame_timing) - [PerformanceEventTiming](/en-US/docs/Web/API/PerformanceEventTiming) - [INP](https://web.dev/articles/inp) on web.dev (2023) -- [Optimizing INP](https://web.dev/articles/optimizing-inp) on web.dev (2023) +- [Optimize Interaction to Next Paint](https://web.dev/articles/optimize-inp) on web.dev (2023) - [Interaction to Next Paint is officially a Core Web Vital](https://web.dev/blog/inp-cwv-launch) on web.dev (2024) diff --git a/files/en-us/glossary/intrinsic_size/index.md b/files/en-us/glossary/intrinsic_size/index.md index 4568d2714989f52..fbcdf3908b9bf83 100644 --- a/files/en-us/glossary/intrinsic_size/index.md +++ b/files/en-us/glossary/intrinsic_size/index.md @@ -14,7 +14,7 @@ For example, the minimum intrinsic size of the inline {{htmlelement("span")}} el Intrinsic size has the same meaning for images as for text — the size at which the images are displayed if no CSS is applied to change the rendering. -Pixel density and resolution affect intrinsic size. By default, images are assumed to have a "1x" pixel density (1 device pixel = 1 CSS pixel), in which case the intrinsic size is simply the pixel height and width. An image's intrinsic size and resolution can be explicitly specified in its {{Glossary("EXIF")}} data. Image pixel density may also be set for images using the [`srcset`](/en-US/docs/Web/HTML/Element/img#srcset) attribute. Note that, if both mechanisms are used, the `srcset` value is applied "over" the EXIF value. +Pixel density and resolution affect intrinsic size. By default, images are assumed to have a "1x" pixel density (1 device pixel = 1 CSS pixel), in which case the intrinsic size is simply the pixel height and width. An image's intrinsic size and resolution can be explicitly specified in its {{Glossary("EXIF")}} data. Image pixel density may also be set for images using the [`srcset`](/en-US/docs/Web/HTML/Reference/Elements/img#srcset) attribute. Note that, if both mechanisms are used, the `srcset` value is applied "over" the EXIF value. Intrinsic sizes and how they are calculated are defined in the [CSS sizing module](/en-US/docs/Web/CSS/CSS_box_sizing). diff --git a/files/en-us/glossary/javascript/index.md b/files/en-us/glossary/javascript/index.md index 7cadd825af71bd1..f1b0c89a5706cb5 100644 --- a/files/en-us/glossary/javascript/index.md +++ b/files/en-us/glossary/javascript/index.md @@ -16,7 +16,7 @@ JavaScript is primarily used in the browser, enabling developers to manipulate w Conceived as a server-side language by Brendan Eich (then employed by the Netscape Corporation), JavaScript soon came to Netscape Navigator 2.0 in September 1995. JavaScript enjoyed immediate success and {{glossary("Microsoft Internet Explorer", "Internet Explorer 3.0")}} introduced JavaScript support under the name JScript in August 1996. -In November 1996, Netscape began working with Ecma International to make JavaScript an industry standard. Since then, the standardized JavaScript is called ECMAScript and specified under ECMA-262, whose latest (fourteenth, ES2023) edition is available as of June 2023. +In November 1996, Netscape began working with Ecma International to make JavaScript an industry standard. Since then, the standardized JavaScript is called ECMAScript and specified under ECMA-262. The standard is constantly updated and implemented (a _living standard_). Recently, JavaScript's popularity has expanded even further through the successful [Node.js](https://nodejs.org/en) platform—the most popular cross-platform JavaScript runtime environment outside the browser. Node.js - built using [Chrome's V8 JavaScript Engine](<https://en.wikipedia.org/wiki/V8_(JavaScript_engine)>) - allows developers to use JavaScript as a scripting language to automate things on a computer and build fully functional {{Glossary("HTTP")}} and {{Glossary("WebSockets")}} servers. diff --git a/files/en-us/glossary/kebab_case/index.md b/files/en-us/glossary/kebab_case/index.md index d61a1cc4c5a0560..96cf58745456825 100644 --- a/files/en-us/glossary/kebab_case/index.md +++ b/files/en-us/glossary/kebab_case/index.md @@ -8,7 +8,7 @@ page-type: glossary-definition **Kebab case** is a way of writing phrases without spaces, where spaces are replaced with hyphens `-`, and the words are typically all lower case. The name comes from the similarity of the words to meat on a kebab skewer. It's often stylized as "kebab-case" to remind the reader of its appearance. -Kebab casing is often used as a variable naming convention. However, in many languages, hyphens represent subtraction, so kebab casing is not an option. CSS properties such as {{cssxref("background-color")}} and {{cssxref("font-family")}} are in kebab case, and so are HTML attributes such as [`aria-label`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-label) and [`data-*`](/en-US/docs/Web/HTML/Global_attributes/data-*). +Kebab casing is often used as a variable naming convention. However, in many languages, hyphens represent subtraction, so kebab casing is not an option. CSS properties such as {{cssxref("background-color")}} and {{cssxref("font-family")}} are in kebab case, and so are HTML attributes such as [`aria-label`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-label) and [`data-*`](/en-US/docs/Web/HTML/Reference/Global_attributes/data-*). Kebab-cased words are often simply referred to as _hyphenated_. diff --git a/files/en-us/glossary/largest_contentful_paint/index.md b/files/en-us/glossary/largest_contentful_paint/index.md index 4f7822537eea273..8b86c4ca9966452 100644 --- a/files/en-us/glossary/largest_contentful_paint/index.md +++ b/files/en-us/glossary/largest_contentful_paint/index.md @@ -11,7 +11,7 @@ The **Largest Contentful Paint** (LCP) performance metric provides the render ti The following elements are considered when determining the LCP: - {{HTMLElement("img")}} elements. -- [`<image>`](/en-US/docs/Web/SVG/Element/image) elements inside an SVG. +- [`<image>`](/en-US/docs/Web/SVG/Reference/Element/image) elements inside an SVG. - The poster images of {{HTMLElement("video")}} elements. - Elements with a {{cssxref("background-image")}}. - Groups of text nodes, such as {{HTMLElement("p")}}. diff --git a/files/en-us/glossary/layout_mode/index.md b/files/en-us/glossary/layout_mode/index.md new file mode 100644 index 000000000000000..fbf78dd06cbd400 --- /dev/null +++ b/files/en-us/glossary/layout_mode/index.md @@ -0,0 +1,41 @@ +--- +title: Layout mode +slug: Glossary/Layout_mode +page-type: glossary-definition +--- + +{{GlossarySidebar}} + +A **layout mode**, sometimes called _layout_, is a [CSS](/en-US/docs/Web/CSS) algorithm that determines the position and size of element boxes based on the way they interact with their sibling and ancestor boxes. + +There are several layout modes: + +- **[Flow layout or normal flow](/en-US/docs/Web/CSS/CSS_display/Flow_layout)** + + - : All elements are part of normal flow until you do something to take them out of it.Normal flow includes: + + - **[Block layout](/en-US/docs/Web/CSS/CSS_display/Block_and_inline_layout_in_normal_flow)** + - : Designed for laying out boxes such as paragraphs. + - **[Inline layout](/en-US/docs/Web/CSS/CSS_inline_layout)** + - : Designed for laying out inline items such as text. + +- **[Table layout](/en-US/docs/Web/CSS/CSS_table)** + - : Designed for laying out tables. +- **Float layout** + - : Designed to cause an item to position itself left or right with the rest of the content in normal flow wrapping around it. +- **[Positioned layout](/en-US/docs/Web/CSS/CSS_positioned_layout)** + - : Designed for positioning elements without much interaction with other elements. +- **[Multi-column layout](/en-US/docs/Web/CSS/CSS_multicol_layout)** + - : Designed for laying content out in columns as in a newspaper. +- **[Flexible box layout](/en-US/docs/Web/CSS/CSS_flexible_box_layout)** + - : Designed for laying out complex pages that can be resized smoothly. +- **[Grid layout](/en-US/docs/Web/CSS/CSS_grid_layout)** + - : Designed for laying out elements relative to a fixed grid. + +> [!NOTE] +> Not all [CSS properties](/en-US/docs/Web/CSS/Reference) apply to all _layout modes_. Most of them apply to one or two of them and have no effect if they are set on an element participating in another layout mode. + +## See also + +- [Visual formatting model](/en-US/docs/Web/CSS/CSS_display/Visual_formatting_model) +- [CSS display](/en-US/docs/Web/CSS/CSS_display) module diff --git a/files/en-us/glossary/lossy_compression/index.md b/files/en-us/glossary/lossy_compression/index.md index 004f1997b50971f..6d7f49c3c75c2eb 100644 --- a/files/en-us/glossary/lossy_compression/index.md +++ b/files/en-us/glossary/lossy_compression/index.md @@ -8,7 +8,7 @@ page-type: glossary-definition **Lossy compression**, or irreversible compression, is a data-compression method that uses inexact approximations and partial-data discarding to represent content. In simpler terms: lossy compression causes data from the initial file to be lost, possibly causing degradation in quality. The process of such compression is irreversible; once lossy compression of the content has been performed, the content cannot be restored to its original state. Therefore, content that has undergone lossy compression should generally not be further edited. -Lossy compression is widely used in image formats such as {{glossary("JPEG")}}, {{glossary("WebP")}}, and audio and video formats such as [MP3, MP4, H.264 and others](/en-US/docs/Web/HTTP/MIME_types/Common_types). +Lossy compression is widely used in image formats such as {{glossary("JPEG")}}, {{glossary("WebP")}}, and audio and video formats such as [MP3, MP4, H.264 and others](/en-US/docs/Web/HTTP/Guides/MIME_types/Common_types). Compression methods such as {{glossary("WebP")}} are capable of [both lossy and lossless compression](https://developers.google.com/speed/webp/docs/compression) depending on the compression level or the options you want to use during encoding. ![Lossy compression image](2019-11-18.png) diff --git a/files/en-us/glossary/ltr/index.md b/files/en-us/glossary/ltr/index.md index e1b9ce9aebe4b57..a6778ff4174feac 100644 --- a/files/en-us/glossary/ltr/index.md +++ b/files/en-us/glossary/ltr/index.md @@ -19,9 +19,9 @@ The opposite of LTR, {{Glossary("RTL")}} (Right To Left) is used in other common - {{Glossary("Localization")}} - {{Glossary("RTL")}} - {{Glossary("BiDi")}} -- [HTML global attributes](/en-US/docs/Web/HTML/Global_attributes) - - [dir](/en-US/docs/Web/HTML/Global_attributes/dir) - - [lang](/en-US/docs/Web/HTML/Global_attributes/lang) +- [HTML global attributes](/en-US/docs/Web/HTML/Reference/Global_attributes) + - [dir](/en-US/docs/Web/HTML/Reference/Global_attributes/dir) + - [lang](/en-US/docs/Web/HTML/Reference/Global_attributes/lang) - [CSS](/en-US/docs/Web/CSS) - {{cssxref(":dir")}} - {{cssxref("direction")}} diff --git a/files/en-us/glossary/main_axis/index.md b/files/en-us/glossary/main_axis/index.md index 2878f8566c3a137..d088bc9bf63529b 100644 --- a/files/en-us/glossary/main_axis/index.md +++ b/files/en-us/glossary/main_axis/index.md @@ -19,7 +19,7 @@ Should you choose `row` or `row-reverse` then your main axis will run along the Choose `column` or `column-reverse` and your main axis will run top to bottom of the page in the block direction. -![Three flex items taking up the full width of the container, displayed one below the other in code order. Flex-direction is set to column. The main axis is vertical i.e. from top to bottom](basics2.png) +![Three flex items taking up the full width of the container, displayed one below the other in code order. Flex-direction is set to column. The main axis is vertical i.e., from top to bottom](basics2.png) On the main axis you can control the sizing of flex items by adding any available space to the items themselves, by way of `flex` properties on the items. Or, you can control the space between and around items by using the `justify-content` property. diff --git a/files/en-us/glossary/mathml/index.md b/files/en-us/glossary/mathml/index.md index 3ceae45a8a64479..5fbd1a489fd02c5 100644 --- a/files/en-us/glossary/mathml/index.md +++ b/files/en-us/glossary/mathml/index.md @@ -12,5 +12,5 @@ page-type: glossary-definition - [MathML](https://en.wikipedia.org/wiki/MathML) on Wikipedia - [MathML](/en-US/docs/Web/MathML) -- [Authoring MathML](/en-US/docs/Web/MathML/Authoring) +- [Authoring MathML](/en-US/docs/Web/MathML/Guides/Authoring) - [What is MathML](https://www.w3.org/Math/whatIsMathML.html) diff --git a/files/en-us/glossary/media_query/index.md b/files/en-us/glossary/media_query/index.md index 6535a1398369a47..1f00d126172e311 100644 --- a/files/en-us/glossary/media_query/index.md +++ b/files/en-us/glossary/media_query/index.md @@ -8,7 +8,7 @@ page-type: glossary-definition A **media query** is a logical expression that is a method for CSS, JavaScript, HTML, and other web languages, to check aspects of the user agent or device that the document is being displayed in, independent of the document contents, to determine whether the associated code block or feature should be applied. -Media queries are used to conditionally apply CSS styles with the CSS {{cssxref("@media")}} and {{cssxref("@import")}} at-rules and in JavaScript to test and monitor media states such as with the {{DOMxRef("Window.matchMedia", "matchMedia()")}} method, {{DOMxRef("MediaQueryList.matches", "matches")}} property, and {{DOMxRef("MediaQueryList.change_event", "change")}} event. Media queries are used as values of the [`<link>`](/en-US/docs/Web/HTML/Element/link#media), [`<source>`](/en-US/docs/Web/HTML/Element/source#media), and [`<style>`](/en-US/docs/Web/HTML/Element/style#media) [HTML](/en-US/docs/Web/HTML) element `media` attributes, conditionally applying the link, source, or style if the media query is true. When a `media` attribute is omitted, it defaults to `true`. Media queries are also used as the value of the [`sizes`](/en-US/docs/Web/API/HTMLImageElement/sizes) attribute of the {{HTMLElement("img")}} element. +Media queries are used to conditionally apply CSS styles with the CSS {{cssxref("@media")}} and {{cssxref("@import")}} at-rules and in JavaScript to test and monitor media states such as with the {{DOMxRef("Window.matchMedia", "matchMedia()")}} method, {{DOMxRef("MediaQueryList.matches", "matches")}} property, and {{DOMxRef("MediaQueryList.change_event", "change")}} event. Media queries are used as values of the [`<link>`](/en-US/docs/Web/HTML/Reference/Elements/link#media), [`<source>`](/en-US/docs/Web/HTML/Reference/Elements/source#media), and [`<style>`](/en-US/docs/Web/HTML/Reference/Elements/style#media) [HTML](/en-US/docs/Web/HTML) element `media` attributes, conditionally applying the link, source, or style if the media query is true. When a `media` attribute is omitted, it defaults to `true`. Media queries are also used as the value of the [`sizes`](/en-US/docs/Web/API/HTMLImageElement/sizes) attribute of the {{HTMLElement("img")}} element. Media queries are made up of optional media query modifiers and media types, and zero or more media conditions, along with logical operators. diff --git a/files/en-us/glossary/mime_type/index.md b/files/en-us/glossary/mime_type/index.md index bfc33c966d44ac2..7d3fba9b4b1ab50 100644 --- a/files/en-us/glossary/mime_type/index.md +++ b/files/en-us/glossary/mime_type/index.md @@ -16,6 +16,6 @@ The name originates from the {{glossary("mime","MIME")}} standard originally use - [Internet media type](https://en.wikipedia.org/wiki/Internet_media_type) on Wikipedia - [List of MIME types](https://www.iana.org/assignments/media-types/media-types.xhtml) - [Properly Configuring Server MIME Types](/en-US/docs/Learn_web_development/Extensions/Server-side/Configuring_server_MIME_types) -- Details information about the usage of [MIME Types](/en-US/docs/Web/HTTP/MIME_types) in a Web context. -- [Incomplete list of MIME types](/en-US/docs/Web/HTTP/MIME_types/Common_types) +- Details information about the usage of [MIME Types](/en-US/docs/Web/HTTP/Guides/MIME_types) in a Web context. +- [Incomplete list of MIME types](/en-US/docs/Web/HTTP/Guides/MIME_types/Common_types) - [MediaRecorder.mimeType](/en-US/docs/Web/API/MediaRecorder/mimeType) diff --git a/files/en-us/glossary/mozilla_firefox/index.md b/files/en-us/glossary/mozilla_firefox/index.md index 5c9936b3d958ae2..0e9aea128c103b1 100644 --- a/files/en-us/glossary/mozilla_firefox/index.md +++ b/files/en-us/glossary/mozilla_firefox/index.md @@ -12,5 +12,5 @@ First released in November 2004, Firefox is completely customizable with themes, ## See also -- [Mozilla Firefox official website](https://www.mozilla.org/en-US/firefox/) +- [Mozilla Firefox official website](https://www.mozilla.org/en-US/firefox/new/) - [Firefox developer documentations](/en-US/docs/Mozilla/Firefox) on MDN diff --git a/files/en-us/glossary/namespace/index.md b/files/en-us/glossary/namespace/index.md index 05ac87ed8d771b8..ad71cf2c0b7f081 100644 --- a/files/en-us/glossary/namespace/index.md +++ b/files/en-us/glossary/namespace/index.md @@ -14,7 +14,7 @@ In HTML, CSS, and XML-based languages, a namespace is the explicitly declared or ## See also -- [Namespaces crash course](/en-US/docs/Web/SVG/Namespaces_Crash_Course) +- [Namespaces crash course](/en-US/docs/Web/SVG/Guides/Namespaces_crash_course) - [CSS namespaces](/en-US/docs/Web/CSS/CSS_namespaces) module - CSS {{CSSXref("@namespace")}} - [`Document.createElementNS()`](/en-US/docs/Web/API/Document/createElementNS) method diff --git a/files/en-us/glossary/navigation_directive/index.md b/files/en-us/glossary/navigation_directive/index.md index dd013aa9ef81299..08056cd6d6eab0a 100644 --- a/files/en-us/glossary/navigation_directive/index.md +++ b/files/en-us/glossary/navigation_directive/index.md @@ -10,7 +10,7 @@ page-type: glossary-definition Navigation directives don't fall back to the {{CSP("default-src")}} directive. -See [Navigation directives](/en-US/docs/Web/HTTP/Headers/Content-Security-Policy#navigation_directives) for a complete list. +See [Navigation directives](/en-US/docs/Web/HTTP/Reference/Headers/Content-Security-Policy#navigation_directives) for a complete list. ## See also @@ -20,8 +20,8 @@ See [Navigation directives](/en-US/docs/Web/HTTP/Headers/Content-Security-Policy - {{Glossary("Fetch directive")}} - {{Glossary("Document directive")}} - {{Glossary("Reporting directive")}} - - [`block-all-mixed-content`](/en-US/docs/Web/HTTP/Headers/Content-Security-Policy/block-all-mixed-content) - - [`upgrade-insecure-requests`](/en-US/docs/Web/HTTP/Headers/Content-Security-Policy/upgrade-insecure-requests) - - [`trusted-types`](/en-US/docs/Web/HTTP/Headers/Content-Security-Policy/trusted-types) + - [`block-all-mixed-content`](/en-US/docs/Web/HTTP/Reference/Headers/Content-Security-Policy/block-all-mixed-content) + - [`upgrade-insecure-requests`](/en-US/docs/Web/HTTP/Reference/Headers/Content-Security-Policy/upgrade-insecure-requests) + - [`trusted-types`](/en-US/docs/Web/HTTP/Reference/Headers/Content-Security-Policy/trusted-types) - {{HTTPHeader("Content-Security-Policy")}} diff --git a/files/en-us/glossary/network_throttling/index.md b/files/en-us/glossary/network_throttling/index.md index 8b48d4a3193fd0f..1f3da2b9330c2a9 100644 --- a/files/en-us/glossary/network_throttling/index.md +++ b/files/en-us/glossary/network_throttling/index.md @@ -10,7 +10,7 @@ page-type: glossary-definition It's important not to overlook network conditions users experience on mobile. The internet speeds for developers creating web applications in a corporate office building on a powerful computer are generally very fast. As a developer, tech writer, or designer, this is likely your experience. The network speeds of a mobile user accessing that web application, possibly while traveling or in a remote area with poor data plan coverage, will likely be very slow, if they are able to get online at all. Network throttling enables a developer to emulate an experience of a user. Most browser developer tools, such as the browser inspector, provide a function to emulate different network conditions. By emulating your user's experience via network throttling, you can more readily identify and fix load time issues. -Browser developer tools generally have network throttling options, to allow you to test your app under slow network conditions. Firefox's developer tools for example have a drop-down menu available in both the [Network Monitor](https://firefox-source-docs.mozilla.org/devtools-user/network_monitor/index.html) and [Responsive Design Mode](https://firefox-source-docs.mozilla.org/devtools-user/responsive_design_mode/index.html) containing network speed options (e.g. Wi-Fi, good 3G, 2G) +Browser developer tools generally have network throttling options, to allow you to test your app under slow network conditions. Firefox's developer tools for example have a drop-down menu available in both the [Network Monitor](https://firefox-source-docs.mozilla.org/devtools-user/network_monitor/index.html) and [Responsive Design Mode](https://firefox-source-docs.mozilla.org/devtools-user/responsive_design_mode/index.html) containing network speed options (e.g., Wi-Fi, good 3G, 2G) ## See also diff --git a/files/en-us/glossary/null/index.md b/files/en-us/glossary/null/index.md index 9ab1aab839bf793..b00e31ee2138268 100644 --- a/files/en-us/glossary/null/index.md +++ b/files/en-us/glossary/null/index.md @@ -18,7 +18,7 @@ This is considered [a bug](/en-US/docs/Web/JavaScript/Reference/Operators/typeof ## See also -- [JavaScript data types](/en-US/docs/Web/JavaScript/Data_structures) +- [JavaScript data types](/en-US/docs/Web/JavaScript/Guide/Data_structures) - The JavaScript global object: [`null`](/en-US/docs/Web/JavaScript/Reference/Operators/null) - [Null pointer](https://en.wikipedia.org/wiki/Null_pointer) on Wikipedia - Related glossary terms: diff --git a/files/en-us/glossary/number/index.md b/files/en-us/glossary/number/index.md index e5828de8009d232..c3e1349e88fefc1 100644 --- a/files/en-us/glossary/number/index.md +++ b/files/en-us/glossary/number/index.md @@ -11,7 +11,7 @@ In {{Glossary("JavaScript")}}, **Number** is a numeric data type in the [double- ## See also - [Numeric types](https://en.wikipedia.org/wiki/Data_type#Numeric_types) on Wikipedia -- The JavaScript type: [`Number`](/en-US/docs/Web/JavaScript/Data_structures#number_type) +- The JavaScript type: [`Number`](/en-US/docs/Web/JavaScript/Guide/Data_structures#number_type) - The JavaScript global object {{jsxref("Number")}} - Related glossary terms: - {{Glossary("JavaScript")}} diff --git a/files/en-us/glossary/object/index.md b/files/en-us/glossary/object/index.md index 527834a0a162dff..69af49590fd959a 100644 --- a/files/en-us/glossary/object/index.md +++ b/files/en-us/glossary/object/index.md @@ -8,12 +8,12 @@ page-type: glossary-definition In JavaScript, objects can be seen as a collection of properties. With the [object literal syntax](/en-US/docs/Web/JavaScript/Guide/Grammar_and_types#object_literals), a limited set of properties are initialized; then properties can be added and removed. Property values can be values of any type, including other objects, which enables building complex data structures. Properties are identified using _key_ values. A _key_ value is either a {{Glossary("String", "String value")}} or a [Symbol value](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Symbol). -There are two types of object properties: The [_data_ property](/en-US/docs/Web/JavaScript/Data_structures#data_property) and the [_accessor_ property](/en-US/docs/Web/JavaScript/Data_structures#accessor_property). +There are two types of object properties: The [_data_ property](/en-US/docs/Web/JavaScript/Guide/Data_structures#data_property) and the [_accessor_ property](/en-US/docs/Web/JavaScript/Guide/Data_structures#accessor_property). > [!NOTE] > It's important to recognize it's accessor _property_ — not accessor _method_. We can give a JavaScript object class-_like_ accessors by using a function as a value — but that doesn't make the object a class. ## See also -- [Detailed explanation of JavaScript objects](/en-US/docs/Web/JavaScript/Data_structures#objects) in the [JavaScript data types and data structures](/en-US/docs/Web/JavaScript/Data_structures) article +- [Detailed explanation of JavaScript objects](/en-US/docs/Web/JavaScript/Guide/Data_structures#objects) in the [JavaScript data types and data structures](/en-US/docs/Web/JavaScript/Guide/Data_structures) article - {{jsxref("Object")}} in the [JavaScript reference](/en-US/docs/Web/JavaScript/Reference) diff --git a/files/en-us/glossary/oop/index.md b/files/en-us/glossary/oop/index.md index cd2f0c1d8a93126..abe529d9839052e 100644 --- a/files/en-us/glossary/oop/index.md +++ b/files/en-us/glossary/oop/index.md @@ -8,10 +8,10 @@ page-type: glossary-definition **OOP** (Object-Oriented Programming) is an approach in programming in which data is encapsulated within **{{glossary("object","objects")}}** and the object itself is operated on, rather than its component parts. -{{glossary("JavaScript")}} is heavily object-oriented. It follows a [**prototype**-based model](/en-US/docs/Web/JavaScript/Inheritance_and_the_prototype_chain), but it also offers a [class syntax](/en-US/docs/Web/JavaScript/Guide/Using_classes) to enable typical OOP paradigms. +{{glossary("JavaScript")}} is heavily object-oriented. It follows a [**prototype**-based model](/en-US/docs/Web/JavaScript/Guide/Inheritance_and_the_prototype_chain), but it also offers a [class syntax](/en-US/docs/Web/JavaScript/Guide/Using_classes) to enable typical OOP paradigms. ## See also - [Object-oriented programming](https://en.wikipedia.org/wiki/Object-oriented_programming) on Wikipedia - [Introduction to object-oriented JavaScript](/en-US/docs/Learn_web_development/Extensions/Advanced_JavaScript_objects) -- [Inheritance and the prototype chain](/en-US/docs/Web/JavaScript/Inheritance_and_the_prototype_chain) +- [Inheritance and the prototype chain](/en-US/docs/Web/JavaScript/Guide/Inheritance_and_the_prototype_chain) diff --git a/files/en-us/glossary/ota/index.md b/files/en-us/glossary/ota/index.md index b3d165c5ff09cd3..d3d1431bf17c068 100644 --- a/files/en-us/glossary/ota/index.md +++ b/files/en-us/glossary/ota/index.md @@ -6,7 +6,7 @@ page-type: glossary-definition {{GlossarySidebar}} -_Over The Air_ (**OTA**) refers to automatic updating of software on connected devices from a central server. All device owners receiving a given set of updates are on the same "channel", and each device often can access several channels (e.g. for production or engineering builds). +_Over The Air_ (**OTA**) refers to automatic updating of software on connected devices from a central server. All device owners receiving a given set of updates are on the same "channel", and each device often can access several channels (e.g., for production or engineering builds). ## See also diff --git a/files/en-us/glossary/pac/index.md b/files/en-us/glossary/pac/index.md index d0ce854ce84f6a5..1266c9f3c23361f 100644 --- a/files/en-us/glossary/pac/index.md +++ b/files/en-us/glossary/pac/index.md @@ -16,9 +16,9 @@ function FindProxyForURL(url, host) { ret = FindProxyForURL(url, host); ``` -See [Proxy Auto-Configuration (PAC) file](/en-US/docs/Web/HTTP/Proxy_servers_and_tunneling/Proxy_Auto-Configuration_PAC_file) for details about how these are used and how to create new ones. +See [Proxy Auto-Configuration (PAC) file](/en-US/docs/Web/HTTP/Guides/Proxy_servers_and_tunneling/Proxy_Auto-Configuration_PAC_file) for details about how these are used and how to create new ones. ## See also - [PAC](https://en.wikipedia.org/wiki/Proxy_auto-config) on Wikipedia -- [Proxy Auto-Configuration file](/en-US/docs/Web/HTTP/Proxy_servers_and_tunneling/Proxy_Auto-Configuration_PAC_file) on MDN +- [Proxy Auto-Configuration file](/en-US/docs/Web/HTTP/Guides/Proxy_servers_and_tunneling/Proxy_Auto-Configuration_PAC_file) on MDN diff --git a/files/en-us/glossary/parent_object/index.md b/files/en-us/glossary/parent_object/index.md index 573b7946fa86a7c..550e8d216a05bd9 100644 --- a/files/en-us/glossary/parent_object/index.md +++ b/files/en-us/glossary/parent_object/index.md @@ -10,4 +10,4 @@ The {{glossary("object")}} to which a given {{glossary("property")}} or {{glossa ## See also -- [Discussion of Inheritance and prototypes in JavaScript](/en-US/docs/Web/JavaScript/Inheritance_and_the_prototype_chain) +- [Discussion of Inheritance and prototypes in JavaScript](/en-US/docs/Web/JavaScript/Guide/Inheritance_and_the_prototype_chain) diff --git a/files/en-us/glossary/payload_body/index.md b/files/en-us/glossary/payload_body/index.md index 0f011e3eb86a254..66d1e2997f39a22 100644 --- a/files/en-us/glossary/payload_body/index.md +++ b/files/en-us/glossary/payload_body/index.md @@ -6,7 +6,7 @@ page-type: glossary-definition {{GlossarySidebar}} -In HTTP messages, the **payload body** or **payload** was the resource representation transferred in a message body, stripped of any [transfer encoding](/en-US/docs/Web/HTTP/Headers/Transfer-Encoding). With no transfer encoding, the _payload body_ and _message body_ are identical. Representation data could also be transferred in HTTP headers, but such data would not be considered a "payload". +In HTTP messages, the **payload body** or **payload** was the resource representation transferred in a message body, stripped of any [transfer encoding](/en-US/docs/Web/HTTP/Reference/Headers/Transfer-Encoding). With no transfer encoding, the _payload body_ and _message body_ are identical. Representation data could also be transferred in HTTP headers, but such data would not be considered a "payload". Since {{RFC("9110")}}, the word **content** replaces the word **payload**. See [**HTTP content**](/en-US/docs/Glossary/HTTP_Content). diff --git a/files/en-us/glossary/payload_header/index.md b/files/en-us/glossary/payload_header/index.md index bfb4868cc8a1629..ae9d1295e11ad55 100644 --- a/files/en-us/glossary/payload_header/index.md +++ b/files/en-us/glossary/payload_header/index.md @@ -8,13 +8,13 @@ page-type: glossary-definition A **payload header** is an {{Glossary("HTTP_header", "HTTP header")}} that describes the payload information related to safe transport and reconstruction of the original resource {{Glossary("Representation header", "representation")}}, from one or more messages. This includes information like the length of the message payload, which part of the resource is carried in this payload (for a multi-part message), any encoding applied for transport, message integrity checks, etc. -Payload headers may be present in both HTTP request and response messages (i.e. in any message that is carrying payload data). +Payload headers may be present in both HTTP request and response messages (i.e., in any message that is carrying payload data). The payload headers include: {{HTTPHeader("Content-Length")}}, {{HTTPHeader("Content-Range")}}, {{HTTPHeader("Trailer")}}, and {{HTTPHeader("Transfer-Encoding")}}. ## See also -- [List of all HTTP headers](/en-US/docs/Web/HTTP/Headers) +- [List of all HTTP headers](/en-US/docs/Web/HTTP/Reference/Headers) - {{HTTPHeader("Content-Length")}} - {{HTTPHeader("Content-Range")}} diff --git a/files/en-us/glossary/prefetch/index.md b/files/en-us/glossary/prefetch/index.md index 782d5f7f1a74367..3c4cce6b5dec9ff 100644 --- a/files/en-us/glossary/prefetch/index.md +++ b/files/en-us/glossary/prefetch/index.md @@ -14,7 +14,7 @@ Prefetching might be used, for example, to fetch the page linked by a "Next" but Resources should be prefetched based on how likely it is that they will be needed in a future navigation. Browsers can infer this automatically for some resources, such as the current URL in the address bar. -This can be done using [`<link rel="prefetch">`](/en-US/docs/Web/HTML/Attributes/rel/prefetch) (the [Speculation Rules API](/en-US/docs/Web/API/Speculation_Rules_API) only handles document prefetches for navigations): +This can be done using [`<link rel="prefetch">`](/en-US/docs/Web/HTML/Reference/Attributes/rel/prefetch) (the [Speculation Rules API](/en-US/docs/Web/API/Speculation_Rules_API) only handles document prefetches for navigations): ```html <link rel="prefetch" href="next.html" /> @@ -24,7 +24,7 @@ This can be done using [`<link rel="prefetch">`](/en-US/docs/Web/HTML/Attributes Developers can provide hints to the browser of navigations that should be prefetched in a couple of different ways: -[`<link rel="prefetch">`](/en-US/docs/Web/HTML/Attributes/rel/prefetch): +[`<link rel="prefetch">`](/en-US/docs/Web/HTML/Reference/Attributes/rel/prefetch): ```html <link rel="prefetch" href="next.html" /> @@ -45,11 +45,11 @@ Developers can provide hints to the browser of navigations that should be prefet </script> ``` -The Speculation Rules API handles document prefetches for navigations much better than `<link rel="prefetch">`; the former was designed specifically for that purpose whereas the latter has a number of limitations; see [`<link rel="prefetch">`](/en-US/docs/Web/HTML/Attributes/rel/prefetch) for details. +The Speculation Rules API handles document prefetches for navigations much better than `<link rel="prefetch">`; the former was designed specifically for that purpose whereas the latter has a number of limitations; see [`<link rel="prefetch">`](/en-US/docs/Web/HTML/Reference/Attributes/rel/prefetch) for details. ### DNS prefetching -[DNS prefetching](/en-US/docs/Web/HTML/Attributes/rel/dns-prefetch) resolves domain names in advance, speeding up load times by reducing the time associated with domain lookup at request time. +[DNS prefetching](/en-US/docs/Web/HTML/Reference/Attributes/rel/dns-prefetch) resolves domain names in advance, speeding up load times by reducing the time associated with domain lookup at request time. ```html <link rel="dns-prefetch" href="https://example.com/" /> diff --git a/files/en-us/glossary/preflight_request/index.md b/files/en-us/glossary/preflight_request/index.md index b9954a8866da04e..b4633270e1dba49 100644 --- a/files/en-us/glossary/preflight_request/index.md +++ b/files/en-us/glossary/preflight_request/index.md @@ -10,7 +10,7 @@ A CORS preflight request is a {{Glossary("CORS")}} request that checks to see if It is an {{HTTPMethod("OPTIONS")}} request, using two or three HTTP request headers: {{HTTPHeader("Access-Control-Request-Method")}}, {{HTTPHeader("Origin")}}, and optionally {{HTTPHeader("Access-Control-Request-Headers")}}. -A preflight request is automatically issued by a browser and in normal cases, front-end developers don't need to craft such requests themselves. It appears when request is qualified as ["to be preflighted"](/en-US/docs/Web/HTTP/CORS#preflighted_requests) and omitted for [simple requests](/en-US/docs/Web/HTTP/CORS#simple_requests). +A preflight request is automatically issued by a browser and in normal cases, front-end developers don't need to craft such requests themselves. It appears when request is qualified as ["to be preflighted"](/en-US/docs/Web/HTTP/Guides/CORS#preflighted_requests) and omitted for [simple requests](/en-US/docs/Web/HTTP/Guides/CORS#simple_requests). For example, a client might be asking a server if it would allow a {{HTTPMethod("DELETE")}} request, before sending a `DELETE` request, by using a preflight request: diff --git a/files/en-us/glossary/primitive/index.md b/files/en-us/glossary/primitive/index.md index b01c105cc16ae29..91fd1946e96da4a 100644 --- a/files/en-us/glossary/primitive/index.md +++ b/files/en-us/glossary/primitive/index.md @@ -24,7 +24,7 @@ Primitives have no methods but still behave as if they do. When properties are a ## See also -- [JavaScript data types](/en-US/docs/Web/JavaScript/Data_structures) +- [JavaScript data types](/en-US/docs/Web/JavaScript/Guide/Data_structures) - [Primitive data type](https://en.wikipedia.org/wiki/Primitive_data_type) (Wikipedia) - Related glossary terms: - {{Glossary("JavaScript")}} diff --git a/files/en-us/glossary/property/javascript/index.md b/files/en-us/glossary/property/javascript/index.md index d1a55f01f307a93..9f921f0403f4299 100644 --- a/files/en-us/glossary/property/javascript/index.md +++ b/files/en-us/glossary/property/javascript/index.md @@ -6,7 +6,7 @@ page-type: glossary-definition {{GlossarySidebar}} -A **JavaScript property** is a member of an [object](/en-US/docs/Web/JavaScript/Data_structures#objects) that associates a key with a value. A JavaScript object is a data structure that stores a collection of properties. +A **JavaScript property** is a member of an [object](/en-US/docs/Web/JavaScript/Guide/Data_structures#objects) that associates a key with a value. A JavaScript object is a data structure that stores a collection of properties. A property consists of the following parts: @@ -14,7 +14,7 @@ A property consists of the following parts: - A _value_, which can be any JavaScript value. A property that has a function as its value may also be called a {{Glossary("method")}}. - Some _attributes_, which specify how the property can be read and written. A property may have the `configurable`, `enumerable`, and `writable` attributes. -[Accessor properties](/en-US/docs/Web/JavaScript/Data_structures#accessor_property) do not have an actual "value". The value is represented indirectly through a pair of functions, one (the getter) invoked when reading the value and one (the setter) invoked when setting the value. However, accessor properties behave like regular data properties on the surface, because the getter and setter functions are invoked automatically and are typically transparent to JavaScript code. +[Accessor properties](/en-US/docs/Web/JavaScript/Guide/Data_structures#accessor_property) do not have an actual "value". The value is represented indirectly through a pair of functions, one (the getter) invoked when reading the value and one (the setter) invoked when setting the value. However, accessor properties behave like regular data properties on the surface, because the getter and setter functions are invoked automatically and are typically transparent to JavaScript code. The property's value (including the getter and setter) and its attributes are stored in a data record called the _property descriptor_. Many methods, such as {{jsxref("Object.getOwnPropertyDescriptor()")}} and {{jsxref("Object.defineProperty()")}}, work with property descriptors. @@ -29,7 +29,7 @@ const obj = { The object `obj` has two properties. The first one has `"a"` as the key and `1` as the value. The second one has `"b"` as the key and a function as the value (using the [method syntax](/en-US/docs/Web/JavaScript/Reference/Functions/Method_definitions)). The `"a"` – `1`, `"b"` – `function` associations are the properties of the object. -In the context of [classes](/en-US/docs/Web/JavaScript/Reference/Classes), properties can be divided into _instance properties_, which are owned by each instance, and _static properties_, which are owned by the class and hold data common to all instances. In the context of [inheritance](/en-US/docs/Web/JavaScript/Inheritance_and_the_prototype_chain), properties can also be divided into _own properties_, which are owned by the object itself, and _inherited properties_, which are owned by objects in the prototype chain of the object. +In the context of [classes](/en-US/docs/Web/JavaScript/Reference/Classes), properties can be divided into _instance properties_, which are owned by each instance, and _static properties_, which are owned by the class and hold data common to all instances. In the context of [inheritance](/en-US/docs/Web/JavaScript/Guide/Inheritance_and_the_prototype_chain), properties can also be divided into _own properties_, which are owned by the object itself, and _inherited properties_, which are owned by objects in the prototype chain of the object. For more information about reading and writing properties, see [working with objects](/en-US/docs/Web/JavaScript/Guide/Working_with_objects). @@ -37,5 +37,5 @@ For more information about reading and writing properties, see [working with obj - [Property (programming)](<https://en.wikipedia.org/wiki/Property_(programming)>) on Wikipedia - [Introduction to object-oriented JavaScript](/en-US/docs/Learn_web_development/Extensions/Advanced_JavaScript_objects) -- [Object properties](/en-US/docs/Web/JavaScript/Data_structures#properties) -- [Enumerability and ownership of properties](/en-US/docs/Web/JavaScript/Enumerability_and_ownership_of_properties) +- [Object properties](/en-US/docs/Web/JavaScript/Guide/Data_structures#properties) +- [Enumerability and ownership of properties](/en-US/docs/Web/JavaScript/Guide/Enumerability_and_ownership_of_properties) diff --git a/files/en-us/glossary/protocol/index.md b/files/en-us/glossary/protocol/index.md index 2ef9bc6e256be97..92f632857f42089 100644 --- a/files/en-us/glossary/protocol/index.md +++ b/files/en-us/glossary/protocol/index.md @@ -12,7 +12,7 @@ A **protocol** is a system of rules that define how data is exchanged within or - [Communications protocol](https://en.wikipedia.org/wiki/Communications_protocol) on Wikipedia - [RFC Official Internet Protocol Standards](https://www.rfc-editor.org/standards) -- [HTTP overview](/en-US/docs/Web/HTTP/Overview) +- [HTTP overview](/en-US/docs/Web/HTTP/Guides/Overview) - Related glossary terms: - {{glossary("TCP")}} - {{glossary("Packet")}} diff --git a/files/en-us/glossary/prototype/index.md b/files/en-us/glossary/prototype/index.md index ada53e7ef3db6dd..bd27bf0043dff7d 100644 --- a/files/en-us/glossary/prototype/index.md +++ b/files/en-us/glossary/prototype/index.md @@ -8,7 +8,7 @@ page-type: glossary-definition A prototype is a model that displays the appearance and behavior of an application or product early in the development lifecycle. -See [Inheritance and the prototype chain](/en-US/docs/Web/JavaScript/Inheritance_and_the_prototype_chain) +See [Inheritance and the prototype chain](/en-US/docs/Web/JavaScript/Guide/Inheritance_and_the_prototype_chain) ## See also diff --git a/files/en-us/glossary/proxy_server/index.md b/files/en-us/glossary/proxy_server/index.md index 35e6d1121323f19..e7185125a433097 100644 --- a/files/en-us/glossary/proxy_server/index.md +++ b/files/en-us/glossary/proxy_server/index.md @@ -15,5 +15,5 @@ A proxy can be on the user's local computer, or anywhere between the user's comp ## See also -- [Proxy servers and tunneling](/en-US/docs/Web/HTTP/Proxy_servers_and_tunneling) +- [Proxy servers and tunneling](/en-US/docs/Web/HTTP/Guides/Proxy_servers_and_tunneling) - [Proxy server](https://en.wikipedia.org/wiki/Proxy_server) on Wikipedia diff --git a/files/en-us/glossary/public-key_cryptography/index.md b/files/en-us/glossary/public-key_cryptography/index.md index e642b903a408794..07344d40d0ce7c1 100644 --- a/files/en-us/glossary/public-key_cryptography/index.md +++ b/files/en-us/glossary/public-key_cryptography/index.md @@ -14,7 +14,7 @@ When used for encryption, the public key is used to encrypt and the private key As a result, it's common for an encryption system to use a symmetric algorithm to encrypt the message, then a public-key system to encrypt the symmetric key. This arrangement can confer the benefits of both systems. -Commonly used public-key cryptosystems are RSA (for both signing and encryption), DSA (for signing) and Diffie-Hellman (for key agreement). +Commonly used public-key cryptosystems are RSA (for both signing and encryption), DSA (for signing) and Diffie–Hellman (for key agreement). Elliptic-curve cryptography offers an alternative approach to these cryptographic systems with the benefit of using comparatively smaller key sizes, faster operations, and smaller storage and transmission. Popular elliptic-curve algorithms include [Elliptic-curve Diffie–Hellman](https://en.wikipedia.org/wiki/Elliptic-curve_Diffie–Hellman) and [Elliptic Curve Digital Signature Algorithm](https://en.wikipedia.org/wiki/Elliptic_Curve_Digital_Signature_Algorithm), which developers will often encounter abbreviated as **ECDH** and **ECDSA**. diff --git a/files/en-us/glossary/quality_values/index.md b/files/en-us/glossary/quality_values/index.md index 9bf79e2aeeaf791..4db8f1f4c786cde 100644 --- a/files/en-us/glossary/quality_values/index.md +++ b/files/en-us/glossary/quality_values/index.md @@ -6,7 +6,7 @@ page-type: glossary-definition {{GlossarySidebar}} -**Quality values**, or _q-values_ and _q-factors_, are used to describe the order of priority of values in a comma-separated list. It is a special syntax allowed in some [HTTP headers](/en-US/docs/Web/HTTP/Headers) and in HTML. +**Quality values**, or _q-values_ and _q-factors_, are used to describe the order of priority of values in a comma-separated list. It is a special syntax allowed in some [HTTP headers](/en-US/docs/Web/HTTP/Reference/Headers) and in HTML. The importance of a value is marked by the suffix `';q='` immediately followed by a value between `0` and `1` included, with up to three decimal digits, the highest value denoting the highest priority. When not present, the default value is `1`. @@ -42,5 +42,5 @@ Some syntax, like the one of {{HTTPHeader("Accept")}}, allow additional specifie ## More information -- [HTTP headers](/en-US/docs/Web/HTTP/Headers) using q-values in their syntax: {{HTTPHeader("Accept")}}, {{HTTPHeader("Accept-Encoding")}}, {{HTTPHeader("Accept-Language")}}, {{HTTPHeader("TE")}}. +- [HTTP headers](/en-US/docs/Web/HTTP/Reference/Headers) using q-values in their syntax: {{HTTPHeader("Accept")}}, {{HTTPHeader("Accept-Encoding")}}, {{HTTPHeader("Accept-Language")}}, {{HTTPHeader("TE")}}. - [Header field definitions.](https://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html) diff --git a/files/en-us/glossary/reading_order/index.md b/files/en-us/glossary/reading_order/index.md new file mode 100644 index 000000000000000..48d7afcc49a3eb1 --- /dev/null +++ b/files/en-us/glossary/reading_order/index.md @@ -0,0 +1,32 @@ +--- +title: Reading order +slug: Glossary/Reading_order +page-type: glossary-definition +--- + +{{GlossarySidebar}} + +**Reading order** refers to the order in which content is accessed, for example when read out by a {{glossary("screen reader")}}, or navigated to using sequential navigation methods such as tabbing through links or buttons. By default, the reading order of a webpage is defined by the document source order. + +Generally, the source order should express a sensible reading order for the content, and this should also be reflected by the visual order of the content layout. However, sometimes the visual order goes out of sync with the source order. For example, you might apply different layouts to a document based on [media queries](/en-US/docs/Web/CSS/CSS_media_queries/Using_media_queries) to suit various device or user requirements, or adjust tabbing order via [`tabindex`](/en-US/docs/Web/HTML/Reference/Global_attributes/tabindex). + +These updates can cause accessibility issues. For example, when a sighted screen reader user tabs through content, and the screen reader order differs from the visual order, this is bad user experience and can be inaccessible. The reading order should make sense to all users no matter how they access the content. + +## Modifying reading order in CSS + +An element's reading order can be modified via the {{cssxref("reading-flow")}} property, and tweaked further by setting {{cssxref("reading-order")}} values on child items of the element. + +The following definitions are significant in understanding modified reading order: + +- Reading flow container + - : An element with a modified reading order resulting from the values set for its {{cssxref("reading-flow")}} and {{cssxref("reading-order")}} properties. +- Reading flow + - : The modified reading order of a reading flow container's child elements. + +## See also + +- {{cssxref("reading-flow")}} +- {{cssxref("reading-order")}} +- {{cssxref("flex-direction")}} +- {{cssxref("order")}} +- [`tabindex`](/en-US/docs/Web/HTML/Reference/Global_attributes/tabindex) diff --git a/files/en-us/glossary/recursion/index.md b/files/en-us/glossary/recursion/index.md index c64cc5d740cced5..ce294bf714e5592 100644 --- a/files/en-us/glossary/recursion/index.md +++ b/files/en-us/glossary/recursion/index.md @@ -14,7 +14,7 @@ The act of a function calling itself, recursion is used to solve problems that c The following Python code defines a function that takes a number, prints it, and then calls itself again with the number's value -1. It keeps going until the number is equal to 0, in which case it stops. -```py +```python def recurse(x): if x > 0: print(x) @@ -25,6 +25,7 @@ recurse(10) The output will look like this: +```plain 10 9 8 @@ -35,6 +36,7 @@ The output will look like this: 3 2 1 +``` ### Recursion is limited by stack size @@ -58,9 +60,8 @@ console.log(getMaxCallStackSize(0)); const factorial = (n) => { if (n === 0) { return 1; - } else { - return n * factorial(n - 1); } + return n * factorial(n - 1); }; console.log(factorial(10)); // 3628800 diff --git a/files/en-us/glossary/replaced_elements/index.md b/files/en-us/glossary/replaced_elements/index.md new file mode 100644 index 000000000000000..ae616ab9dcf32b1 --- /dev/null +++ b/files/en-us/glossary/replaced_elements/index.md @@ -0,0 +1,35 @@ +--- +title: Replaced elements +slug: Glossary/Replaced_elements +page-type: glossary-definition +--- + +{{GlossarySidebar}} + +In web development, **replaced elements** are HTML elements whose content are replaced by external resources or content defined outside of the document structure, and are not considered in the CSS rendering model. They are external objects whose representation is independent of the CSS formatting model. + +The following can be replaced elements: + +- {{HTMLElement("img")}} +- {{HTMLElement("video")}} +- {{HTMLElement("iframe")}} +- {{HTMLElement("embed")}} +- {{HTMLElement("fencedframe")}} + +The following are treated as replaced elements only in specific cases: + +- {{HTMLElement("audio")}} +- {{HTMLElement("canvas")}} +- {{HTMLElement("object")}} +- {{HTMLElement("input")}} (`image` input types only) + +Replaced elements often have an {{glossary("intrinsic size", "intrinsic dimensions")}} and {{glossary("aspect ratio", "intrinsic ratio")}}. For example, the content of an `<img>` element is generally replaced by the image defined by its `src` attribute. That image has an intrinsic width and an intrinsic height specified in absolute units, which determines the aspect ratio. + +Form controls are generally non-replaced _widgets_, except for `<input type="image">`, which is replaced with an image. Objects inserted using the CSS {{cssxref("content")}} property are _anonymous replaced elements_. They are "anonymous" because they don't exist in the HTML markup. + +## See also + +- {{glossary("void element", "Void elements")}} +- {{glossary("Inline-level content")}} +- [Replaced elements in CSS display specification](https://drafts.csswg.org/css-display/#replaced-element) +- [Replaced elements in HTML specification](https://html.spec.whatwg.org/multipage/rendering.html#replaced-elements)s diff --git a/files/en-us/glossary/repo/index.md b/files/en-us/glossary/repo/index.md index 441cf63098f8217..49020ede1bd6ce6 100644 --- a/files/en-us/glossary/repo/index.md +++ b/files/en-us/glossary/repo/index.md @@ -6,7 +6,7 @@ page-type: glossary-definition {{GlossarySidebar}} -In a revision control system like {{Glossary("Git")}} or {{Glossary("SVN")}}, a repo (i.e. "repository") is a place that hosts an application's code source, together with various metadata. +In a revision control system like {{Glossary("Git")}} or {{Glossary("SVN")}}, a repo (i.e., "repository") is a place that hosts an application's code source, together with various metadata. ## See also diff --git a/files/en-us/glossary/reporting_directive/index.md b/files/en-us/glossary/reporting_directive/index.md index 666c55e6ce32184..c89d92f13e47155 100644 --- a/files/en-us/glossary/reporting_directive/index.md +++ b/files/en-us/glossary/reporting_directive/index.md @@ -8,7 +8,7 @@ page-type: glossary-definition **{{Glossary("CSP")}} reporting directives** are used in a {{HTTPHeader("Content-Security-Policy")}} header and control the reporting process of CSP violations. -See [Reporting directives](/en-US/docs/Web/HTTP/Headers/Content-Security-Policy#reporting_directives) for a complete list. +See [Reporting directives](/en-US/docs/Web/HTTP/Reference/Headers/Content-Security-Policy#reporting_directives) for a complete list. ## See also diff --git a/files/en-us/glossary/representation_header/index.md b/files/en-us/glossary/representation_header/index.md index 423ee9f172bcb45..3ad94e09ecdff27 100644 --- a/files/en-us/glossary/representation_header/index.md +++ b/files/en-us/glossary/representation_header/index.md @@ -14,7 +14,7 @@ The underlying resource is semantically the same in each case, but its represent While representations are different forms of resources, representations can themselves also be transmitted in various forms: an HTTP message frames (cf., e.g., HTTP/1.1's {{HTTPHeader("Transfer-Encoding")}}), a particular stream of octets (cf., e.g., {{HTTPHeader("Content-Range")}}) derived from the _selected representation_. -Clients specify the formats that they prefer to be sent during [Content Negotiation](/en-US/docs/Web/HTTP/Content_negotiation) (using `Accept-*` headers), and the representation headers tell the client the format of the _selected representation_ they received. +Clients specify the formats that they prefer to be sent during [Content Negotiation](/en-US/docs/Web/HTTP/Guides/Content_negotiation) (using `Accept-*` headers), and the representation headers tell the client the format of the _selected representation_ they received. Representation headers may be present in both HTTP request and response messages with various methods. If sent as a response to a `HEAD` request, they describe the body content representation that _would_ be selected if the resource was requested with a `GET` request. @@ -28,7 +28,7 @@ Representation headers include: - {{HTTPHeader("Content-Location")}} - {{HTTPHeader("Content-Language")}} -- Validators used in [conditional requests](/en-US/docs/Web/HTTP/Conditional_requests), such as: +- Validators used in [conditional requests](/en-US/docs/Web/HTTP/Guides/Conditional_requests), such as: - {{HTTPHeader("Last-Modified")}} - {{HTTPHeader("ETag")}} @@ -39,6 +39,6 @@ Representation headers are not mutually exclusive with {{Glossary("Content heade - Related glossary terms: - {{Glossary("Content header")}} - [RFC 9110, section 3.2: Representations](https://httpwg.org/specs/rfc9110.html#representations) -- [List of all HTTP headers](/en-US/docs/Web/HTTP/Headers) +- [List of all HTTP headers](/en-US/docs/Web/HTTP/Reference/Headers) - {{HTTPHeader("Repr-Digest")}}, {{HTTPHeader("Want-Repr-Digest")}} - {{HTTPHeader("Content-Digest")}}, {{HTTPHeader("Want-Content-Digest")}} diff --git a/files/en-us/glossary/request_header/index.md b/files/en-us/glossary/request_header/index.md index 4d3a84cca482461..d35af4af7ad129d 100644 --- a/files/en-us/glossary/request_header/index.md +++ b/files/en-us/glossary/request_header/index.md @@ -6,7 +6,7 @@ page-type: glossary-definition {{GlossarySidebar}} -A **request header** is an {{glossary("HTTP header")}} that can be used in an HTTP request to provide information about the request context, so that the server can tailor the response. For example, the {{HTTPHeader("Accept", "Accept-*")}} headers indicate the allowed and preferred formats of the response. Other headers can be used to supply authentication credentials (e.g. {{HTTPHeader("Authorization")}}), to control caching, or to get information about the user agent or referrer, etc. +A **request header** is an {{glossary("HTTP header")}} that can be used in an HTTP request to provide information about the request context, so that the server can tailor the response. For example, the {{HTTPHeader("Accept", "Accept-*")}} headers indicate the allowed and preferred formats of the response. Other headers can be used to supply authentication credentials (e.g., {{HTTPHeader("Authorization")}}), to control caching, or to get information about the user agent or referrer, etc. Not all headers that can appear in a request are referred to as _request headers_ by the specification. For example, the {{HTTPHeader("Content-Type")}} header is referred to as a {{glossary("representation header")}}. @@ -31,5 +31,5 @@ Cache-Control: max-age=0 ## See also -- [List of all HTTP headers](/en-US/docs/Web/HTTP/Headers) +- [List of all HTTP headers](/en-US/docs/Web/HTTP/Reference/Headers) - [RFC 9110, section 6.3: Header Fields](https://httpwg.org/specs/rfc9110.html#header.fields) diff --git a/files/en-us/glossary/resource_timing/index.md b/files/en-us/glossary/resource_timing/index.md index 5f7d656cf88e5f7..91a0db1913e2ed6 100644 --- a/files/en-us/glossary/resource_timing/index.md +++ b/files/en-us/glossary/resource_timing/index.md @@ -11,4 +11,4 @@ Diagnosing performance issues requires performance data at the granularity of th ## See also - [Using the resource timing API](/en-US/docs/Web/API/Performance_API/Resource_timing) -- [Server Timing](https://www.w3.org/TR/server-timing/) +- [Server Timing](https://w3c.github.io/server-timing/) diff --git a/files/en-us/glossary/response_header/index.md b/files/en-us/glossary/response_header/index.md index 7a272a0910d653a..aa3daad14f0210f 100644 --- a/files/en-us/glossary/response_header/index.md +++ b/files/en-us/glossary/response_header/index.md @@ -34,7 +34,7 @@ x-frame-options: DENY ## See also -- [List of all HTTP headers](/en-US/docs/Web/HTTP/Headers) +- [List of all HTTP headers](/en-US/docs/Web/HTTP/Reference/Headers) - Related glossary terms: - {{Glossary("Representation header")}} - {{Glossary("HTTP header")}} diff --git a/files/en-us/glossary/rest/index.md b/files/en-us/glossary/rest/index.md index 7475a2748e7f246..090609163f6207e 100644 --- a/files/en-us/glossary/rest/index.md +++ b/files/en-us/glossary/rest/index.md @@ -8,7 +8,7 @@ page-type: glossary-definition **REST** (Representational State Transfer) refers to a group of software architecture design constraints that bring about efficient, reliable and scalable distributed systems. -The basic idea of REST is that a resource, e.g. a document, is transferred via well-recognized, language-agnostic, and reliably standardized client/server interactions. Services are deemed RESTful when they adhere to these constraints. +The basic idea of REST is that a resource, e.g., a document, is transferred via well-recognized, language-agnostic, and reliably standardized client/server interactions. Services are deemed RESTful when they adhere to these constraints. HTTP APIs in general are sometimes colloquially referred to as RESTful APIs, RESTful services, or REST services, although they don't necessarily adhere to all REST constraints. Beginners can assume a REST API means an HTTP service that can be called using standard web libraries and tools. diff --git a/files/en-us/glossary/robots.txt/index.md b/files/en-us/glossary/robots.txt/index.md index 0f8d22c657c6f32..8838c0cca46e2ec 100644 --- a/files/en-us/glossary/robots.txt/index.md +++ b/files/en-us/glossary/robots.txt/index.md @@ -13,7 +13,7 @@ A restrictive `robots.txt` file can prevent bandwidth consumption by crawlers. A site owner can forbid crawlers to detect a certain path (and all files in that path) or a specific file. This is often done to prevent these resources from being indexed or served by search engines. -If a crawler is allowed to access resources, you can define [indexing rules](/en-US/docs/Web/HTTP/Headers/X-Robots-Tag#directives) for those resources via `<meta name="robots">` elements and {{HTTPHeader("X-Robots-Tag")}} HTTP headers. +If a crawler is allowed to access resources, you can define [indexing rules](/en-US/docs/Web/HTTP/Reference/Headers/X-Robots-Tag#directives) for those resources via `<meta name="robots">` elements and {{HTTPHeader("X-Robots-Tag")}} HTTP headers. Search-related crawlers use these rules to determine how to index and serve resources in search results, or to adjust the crawl rate for specific resources over time. ## See also diff --git a/files/en-us/glossary/safe/http/index.md b/files/en-us/glossary/safe/http/index.md index 447fc0dda3cdee1..427f8bf3297d501 100644 --- a/files/en-us/glossary/safe/http/index.md +++ b/files/en-us/glossary/safe/http/index.md @@ -8,7 +8,7 @@ page-type: glossary-definition An HTTP method is **safe** if it doesn't alter the state of the server. In other words, a method is safe if it leads to a read-only operation. Several common HTTP methods are safe: {{HTTPMethod("GET")}}, {{HTTPMethod("HEAD")}}, or {{HTTPMethod("OPTIONS")}}. All safe methods are also {{glossary("idempotent")}}, but not all idempotent methods are safe. For example, {{HTTPMethod("PUT")}} and {{HTTPMethod("DELETE")}} are both idempotent but unsafe. -Even if safe methods have a read-only semantic, servers can alter their state: e.g. they can log or keep statistics. What is important here is that by calling a safe method, the client doesn't request any server change itself, and therefore won't create an unnecessary load or burden for the server. Browsers can call safe methods without fearing to cause any harm to the server; this allows them to perform activities like pre-fetching without risk. Web crawlers also rely on calling safe methods. +Even if safe methods have a read-only semantic, servers can alter their state: e.g., they can log or keep statistics. What is important here is that by calling a safe method, the client doesn't request any server change itself, and therefore won't create an unnecessary load or burden for the server. Browsers can call safe methods without fearing to cause any harm to the server; this allows them to perform activities like pre-fetching without risk. Web crawlers also rely on calling safe methods. Safe methods don't need to serve static files only; a server can generate an answer to a safe method on-the-fly, as long as the generating script guarantees safety: it should not trigger external effects, like triggering an order in an e-commerce website. diff --git a/files/en-us/glossary/salt/index.md b/files/en-us/glossary/salt/index.md index a368f2257d13273..38721fa72755a8b 100644 --- a/files/en-us/glossary/salt/index.md +++ b/files/en-us/glossary/salt/index.md @@ -6,7 +6,7 @@ page-type: glossary-definition {{GlossarySidebar}} -In cryptography, **salt** is random data added to a password before it is {{glossary("hash", "hashed")}}. This makes it impossible for an attacker to derive passwords from their hashes using precomputed tables of passwords and the corresponding hashes. +In cryptography, **salt** is random data added to a password before it is {{glossary("hash function", "hashed")}}. This makes it impossible for an attacker to derive passwords from their hashes using precomputed tables of passwords and the corresponding hashes. Passwords should never be stored in their plaintext form, because of the risk that an attacker might break into the database where they are stored. Typically, the password is hashed, and the resulting hash is stored. If the hash function is cryptographically secure, then even if an attacker can get access to the stored hashes, it is impractical for them to reverse the function. diff --git a/files/en-us/glossary/script-supporting_element/index.md b/files/en-us/glossary/script-supporting_element/index.md index 02ba85912162af1..28512665c6635b1 100644 --- a/files/en-us/glossary/script-supporting_element/index.md +++ b/files/en-us/glossary/script-supporting_element/index.md @@ -14,4 +14,4 @@ There are only two script-supporting elements: {{HTMLElement("script")}} and {{H ## See also -[Script-supporting elements](/en-US/docs/Web/HTML/Content_categories#script-supporting_elements) +[Script-supporting elements](/en-US/docs/Web/HTML/Guides/Content_categories#script-supporting_elements) diff --git a/files/en-us/glossary/scroll_boundary/index.md b/files/en-us/glossary/scroll_boundary/index.md index 2c22bfa67e96faf..81f80a3902093af 100644 --- a/files/en-us/glossary/scroll_boundary/index.md +++ b/files/en-us/glossary/scroll_boundary/index.md @@ -26,3 +26,4 @@ Boundary default actions can be local or non-local. - [CSS overflow](/en-US/docs/Web/CSS/CSS_overflow) module - [CSS overscroll behavior](/en-US/docs/Web/CSS/CSS_overscroll_behavior) module - [CSS scroll snap](/en-US/docs/Web/CSS/CSS_scroll_snap) module +- [CSS scroll anchoring](/en-US/docs/Web/CSS/CSS_scroll_anchoring) module diff --git a/files/en-us/glossary/scroll_chaining/index.md b/files/en-us/glossary/scroll_chaining/index.md index 65c6c1fa131e02c..9e0e9a5caa536a6 100644 --- a/files/en-us/glossary/scroll_chaining/index.md +++ b/files/en-us/glossary/scroll_chaining/index.md @@ -18,3 +18,4 @@ A **scroll chain** is the order of scrollable elements where the scrolling actio - [CSS overflow](/en-US/docs/Web/CSS/CSS_overflow) module - [CSS overscroll behavior](/en-US/docs/Web/CSS/CSS_overscroll_behavior) module - [CSS scroll snap](/en-US/docs/Web/CSS/CSS_scroll_snap) module +- [CSS scroll anchoring](/en-US/docs/Web/CSS/CSS_scroll_anchoring) module diff --git a/files/en-us/glossary/scroll_snap/index.md b/files/en-us/glossary/scroll_snap/index.md index 8fd59588aa48a54..498efc3f8c454f2 100644 --- a/files/en-us/glossary/scroll_snap/index.md +++ b/files/en-us/glossary/scroll_snap/index.md @@ -10,16 +10,14 @@ page-type: glossary-definition Scroll snapping is a well-controlled scrolling experience, whereby developers define an element as a [scroll container](/en-US/docs/Glossary/Scroll_container) with boundaries for scroll operations. Scroll operations then finish at these snap position boundaries, with the scrolled to content snapping into place. In the above carousel example, as the user finishes scrolling the carousel, its visible image will snap into place. -- `Scroll snap container` - +- Scroll snap container - : The **scroll snap container** is a scroll container with scroll snapping applied. For example, if a box has overflowing content and a {{CSSXref("scroll-snap-type")}} set to a value other than `none`, then the box captures snap positions. A box's scroll snap container is the element's nearest snap-position capturing scroll container ancestor. If a box has no scroll snap container, its snap positions, if any, will not trigger snapping. - -- `Snapport` - +- Snapport - : The **snapport** ​is the area of the [scrollport](/en-US/docs/Glossary/Scroll_container#scrollport) that is used as the alignment container for the scroll snap areas when calculating snap positions. By default, it is the same as the scroll container's visual viewport, but is the area of the scrollport defined by the {{CSSXref("scroll-padding")}} property. The [snap areas](#snap_area) are aligned to the scrollport. - -- `Snap area` +- Snap area - : The **snap area** of an element in a scroll container is the area defined using {{CSSXref("scroll-margin")}} outsets specified on the element. The snap area is used to snap the element to its snapport. +- Snap target + - : A descendant element inside a scroll snap container that is snapped to when the container scrolls. The {{CSSXref("scroll-snap-align")}} property defines the snap position of each snap target. ## See also diff --git a/files/en-us/glossary/semantics/index.md b/files/en-us/glossary/semantics/index.md index 421f5a3c8bd8342..32371f9e9177e8d 100644 --- a/files/en-us/glossary/semantics/index.md +++ b/files/en-us/glossary/semantics/index.md @@ -48,7 +48,7 @@ When approaching which markup to use, ask yourself, "What element(s) best descri ## Semantic elements -These are _some_ of the roughly 100 semantic [elements](/en-US/docs/Web/HTML/Element) available: +These are _some_ of the roughly 100 semantic [elements](/en-US/docs/Web/HTML/Reference/Elements) available: - {{htmlelement("article")}} - {{htmlelement("aside")}} @@ -67,8 +67,8 @@ These are _some_ of the roughly 100 semantic [elements](/en-US/docs/Web/HTML/Ele ## See also -- [HTML element reference](/en-US/docs/Web/HTML/Element#inline_text_semantics) on MDN -- [Using HTML sections and outlines](/en-US/docs/Web/HTML/Element/Heading_Elements#usage_notes) on MDN +- [HTML element reference](/en-US/docs/Web/HTML/Reference/Elements#inline_text_semantics) on MDN +- [Using HTML sections and outlines](/en-US/docs/Web/HTML/Reference/Elements/Heading_Elements#usage_notes) on MDN - [The meaning of semantics in computer science](https://en.wikipedia.org/wiki/Semantics#Computer_science) on Wikipedia - Related glossary terms: - {{Glossary("SEO")}} diff --git a/files/en-us/glossary/serialization/index.md b/files/en-us/glossary/serialization/index.md index 4e6dd97f2990470..4216e5f7c3f517c 100644 --- a/files/en-us/glossary/serialization/index.md +++ b/files/en-us/glossary/serialization/index.md @@ -6,7 +6,7 @@ page-type: glossary-definition {{GlossarySidebar}} -The process whereby an object or data structure is translated into a format suitable for transfer over a network, or storage (e.g. in an array buffer or file format). +The process whereby an object or data structure is translated into a format suitable for transfer over a network, or storage (e.g., in an array buffer or file format). In {{Glossary("JavaScript")}}, for example, you can serialize an object to a {{Glossary("JSON")}} {{Glossary("string")}} by calling the {{Glossary("function")}} {{jsxref("JSON.stringify()")}}. diff --git a/files/en-us/glossary/server_timing/index.md b/files/en-us/glossary/server_timing/index.md index 87b92b434accdea..aae53620ac9860a 100644 --- a/files/en-us/glossary/server_timing/index.md +++ b/files/en-us/glossary/server_timing/index.md @@ -10,5 +10,5 @@ The [Server Timing specification](https://www.w3.org/TR/server-timing/) enables ## See also -- <https://www.w3.org/TR/server-timing/> -- [Resource Timing](https://www.w3.org/TR/resource-timing/) +- [Server Timing specification](https://w3c.github.io/server-timing/) +- [Resource Timing specification](https://w3c.github.io/resource-timing/) diff --git a/files/en-us/glossary/shadow_tree/index.md b/files/en-us/glossary/shadow_tree/index.md index 314804bfdd3d9b0..814aa38fb82fcdc 100644 --- a/files/en-us/glossary/shadow_tree/index.md +++ b/files/en-us/glossary/shadow_tree/index.md @@ -21,5 +21,7 @@ The hidden DOM nodes of a shadow tree are generally not affected by anything app - {{domxref("Element.shadowRoot")}} and {{domxref("Element.attachShadow()")}} - {{domxref("ShadowRoot")}} - {{HTMLElement("slot")}} +- [CSS shadow parts](/en-US/docs/Web/CSS/CSS_shadow_parts) module +- [CSS scoping](/en-US/docs/Web/CSS/CSS_scoping) module - Related glossary terms: - {{Glossary("Accessibility tree")}} diff --git a/files/en-us/glossary/signature/security/index.md b/files/en-us/glossary/signature/security/index.md index ef71f3a7a1f748d..b7a7ce85b8855a1 100644 --- a/files/en-us/glossary/signature/security/index.md +++ b/files/en-us/glossary/signature/security/index.md @@ -8,7 +8,7 @@ page-type: glossary-definition A **signature**, or _digital signature_, is a {{glossary("protocol")}} showing that a message is authentic. -From the {{glossary("hash")}} of a given message, the **signing process** first generates a digital signature linked to the signing entity, using the entity's private {{glossary("key")}}. +From the {{glossary("hash function", "hash")}} of a given message, the **signing process** first generates a digital signature linked to the signing entity, using the entity's private {{glossary("key")}}. On receiving the message, the **verification process** @@ -23,5 +23,5 @@ Digital signatures rely on asymmetric cryptography, also known as [public-key cr - [Digital signature](https://en.wikipedia.org/wiki/Digital_signature) on Wikipedia - Related glossary terms: - - {{glossary("digest")}} - - {{glossary("encryption")}} + - {{glossary("Hash function")}} + - {{glossary("Encryption")}} diff --git a/files/en-us/glossary/site/index.md b/files/en-us/glossary/site/index.md index 1cdc96e4624f81d..bd49f9ad02e29bd 100644 --- a/files/en-us/glossary/site/index.md +++ b/files/en-us/glossary/site/index.md @@ -8,13 +8,13 @@ page-type: glossary-definition Informally, a _site_ is a website, which is a collection of web pages, served from the same domain, and maintained by a single organization. -Browsers sometimes need to distinguish precisely between different sites. For example, the browser must only send [`SameSite`](/en-US/docs/Web/HTTP/Headers/Set-Cookie#samesitesamesite-value) cookies to the same site that set them. +Browsers sometimes need to distinguish precisely between different sites. For example, the browser must only send [`SameSite`](/en-US/docs/Web/HTTP/Reference/Headers/Set-Cookie#samesitesamesite-value) cookies to the same site that set them. For this more precise definition a site is determined by the _registrable domain_ portion of the domain name. The registrable domain consists of an entry in the [Public Suffix List](https://publicsuffix.org/list/) plus the portion of the domain name just before it. This means that, for example, `theguardian.co.uk`, `sussex.ac.uk`, and `bookshop.org` are all registrable domains. According to this definition, `support.mozilla.org` and `developer.mozilla.org` are part of the same site, because `mozilla.org` is a registrable domain. -In some contexts, the scheme is also considered when differentiating sites. This would make `http://vpl.ca` and `https://vpl.ca` different sites. Including the scheme prevents an insecure (HTTP) site from being treated as the same site as a secure (HTTPS) site. A definition that considers the scheme is sometimes called a _schemeful same-site_. This stricter definition is applied in the rules for handling [`SameSite`](/en-US/docs/Web/HTTP/Headers/Set-Cookie#samesitesamesite-value) cookies. +In some contexts, the scheme is also considered when differentiating sites. This would make `http://vpl.ca` and `https://vpl.ca` different sites. Including the scheme prevents an insecure (HTTP) site from being treated as the same site as a secure (HTTPS) site. A definition that considers the scheme is sometimes called a _schemeful same-site_. This stricter definition is applied in the rules for handling [`SameSite`](/en-US/docs/Web/HTTP/Reference/Headers/Set-Cookie#samesitesamesite-value) cookies. > [!NOTE] > Browsers sometimes make security decisions (for example, deciding which resources a script can access) based on the {{Glossary("Origin")}} of a resource. This is a more restrictive concept than the site, encompassing the scheme, the whole domain, and the port. See also [same-origin policy](/en-US/docs/Web/Security/Same-origin_policy). diff --git a/files/en-us/glossary/snap_positions/index.md b/files/en-us/glossary/snap_positions/index.md index 02470a286eccbc6..5be8b04f0510889 100644 --- a/files/en-us/glossary/snap_positions/index.md +++ b/files/en-us/glossary/snap_positions/index.md @@ -9,3 +9,7 @@ page-type: glossary-definition Snap positions are points where the {{Glossary("scroll container", "scrollport")}} stops moving after the scrolling operation completes. Setting up snap positions allows to create a scrolling experience of paging through content instead of needing to drag content into view. Snap positions are set up on a {{Glossary("scroll container")}}. See the [CSS Scroll Snap](/en-US/docs/Web/CSS/CSS_scroll_snap) properties. + +## See also + +- {{glossary("Scroll snap")}} diff --git a/files/en-us/glossary/sql_injection/index.md b/files/en-us/glossary/sql_injection/index.md index ede2e140f5cc96c..6e8c8460cd1409c 100644 --- a/files/en-us/glossary/sql_injection/index.md +++ b/files/en-us/glossary/sql_injection/index.md @@ -56,10 +56,10 @@ The password is not 'anything', hence password=anything results in FALSE, but '1 Before executing the queries for the user credentials, make some changes like the following: -```sql -$id = $_GET['id'] +```php +$id = $_GET["id"] -(1) $id = Stripslashes($id) +(1) $id = stripslashes($id) (2) $id = mysql_real_escape_String($id) ``` diff --git a/files/en-us/glossary/stacking_context/index.md b/files/en-us/glossary/stacking_context/index.md index 33f23d291ed3af8..744a0f0db392dff 100644 --- a/files/en-us/glossary/stacking_context/index.md +++ b/files/en-us/glossary/stacking_context/index.md @@ -10,4 +10,4 @@ page-type: glossary-definition ## See also -- [Explanation and example of the stacking context](/en-US/docs/Web/CSS/CSS_positioned_layout/Understanding_z-index/Stacking_context) +- [Explanation and example of the stacking context](/en-US/docs/Web/CSS/CSS_positioned_layout/Stacking_context) diff --git a/files/en-us/glossary/string/index.md b/files/en-us/glossary/string/index.md index 54147b0306822d0..e31f1d9289d460f 100644 --- a/files/en-us/glossary/string/index.md +++ b/files/en-us/glossary/string/index.md @@ -13,4 +13,4 @@ In {{Glossary("JavaScript")}}, a String is one of the {{Glossary("Primitive", "p ## See also - [String (computer science)](<https://en.wikipedia.org/wiki/String_(computer_science)>) on Wikipedia -- [JavaScript data types and data structures](/en-US/docs/Web/JavaScript/Data_structures#string_type) +- [JavaScript data types and data structures](/en-US/docs/Web/JavaScript/Guide/Data_structures#string_type) diff --git a/files/en-us/glossary/submit_button/index.md b/files/en-us/glossary/submit_button/index.md index 429b37606636110..85f572a32a67abc 100644 --- a/files/en-us/glossary/submit_button/index.md +++ b/files/en-us/glossary/submit_button/index.md @@ -18,17 +18,17 @@ In addition to submitting a form, a submit button can affect the form's behavior Submit buttons can override the form's submission behavior through various attributes: -- `{{HtmlElement("button#formaction", "formaction")}}`: Override the [`action`](/en-US/docs/Web/HTML/Element/form#action) attribute of the form. -- `{{HtmlElement("button#formenctype", "formenctype")}}`: Override the [`enctype`](/en-US/docs/Web/HTML/Element/form#enctype) attribute of the form. -- `{{HtmlElement("button#formmethod", "formmethod")}}`: Override the [`method`](/en-US/docs/Web/HTML/Element/form#method) attribute of the form. -- `{{HtmlElement("button#formnovalidate", "formnovalidate")}}`: Override the [`novalidate`](/en-US/docs/Web/HTML/Element/form#novalidate) attribute of the form. -- `{{HtmlElement("button#formtarget", "formtarget")}}`: Override the [`target`](/en-US/docs/Web/HTML/Element/form#target) attribute of the form. +- `{{HtmlElement("button#formaction", "formaction")}}`: Override the [`action`](/en-US/docs/Web/HTML/Reference/Elements/form#action) attribute of the form. +- `{{HtmlElement("button#formenctype", "formenctype")}}`: Override the [`enctype`](/en-US/docs/Web/HTML/Reference/Elements/form#enctype) attribute of the form. +- `{{HtmlElement("button#formmethod", "formmethod")}}`: Override the [`method`](/en-US/docs/Web/HTML/Reference/Elements/form#method) attribute of the form. +- `{{HtmlElement("button#formnovalidate", "formnovalidate")}}`: Override the [`novalidate`](/en-US/docs/Web/HTML/Reference/Elements/form#novalidate) attribute of the form. +- `{{HtmlElement("button#formtarget", "formtarget")}}`: Override the [`target`](/en-US/docs/Web/HTML/Reference/Elements/form#target) attribute of the form. ## Form data entries If the submit button is a {{HtmlElement("button")}} or `{{HtmlElement('input/submit', '&lt;input type="submit"&gt;')}}` and has a `name` attribute, the form data set will include an entry for its `name` and `value`. -If the submit button is an `{{HtmlElement('input/image', '&lt;input type="image"&gt;')}}`, the form data set will include entries for the X and Y coordinates that the user clicked on (e.g. `x=100&y=200` or `buttonName.x=123&buttonName.y=234`). +If the submit button is an `{{HtmlElement('input/image', '&lt;input type="image"&gt;')}}`, the form data set will include entries for the X and Y coordinates that the user clicked on (e.g., `x=100&y=200` or `buttonName.x=123&buttonName.y=234`). ## See also diff --git a/files/en-us/glossary/symmetric-key_cryptography/index.md b/files/en-us/glossary/symmetric-key_cryptography/index.md index 33cb93917f4439d..639cf80eb0efc68 100644 --- a/files/en-us/glossary/symmetric-key_cryptography/index.md +++ b/files/en-us/glossary/symmetric-key_cryptography/index.md @@ -21,4 +21,4 @@ Most symmetric-key algorithms currently in use are block {{Glossary("Cipher", "c - Related glossary terms: - {{Glossary("Block cipher mode of operation")}} - {{Glossary("Cryptography")}} - - {{Glossary("Cryptographic hash function")}} + - {{Glossary("Hash function")}} diff --git a/files/en-us/glossary/tcp/index.md b/files/en-us/glossary/tcp/index.md index ee431f35def8e70..7000c0a1d710ce0 100644 --- a/files/en-us/glossary/tcp/index.md +++ b/files/en-us/glossary/tcp/index.md @@ -13,7 +13,7 @@ TCP's role is to ensure the packets are reliably delivered, and error-free. TCP ## See also - [Transmission Control Protocol](https://en.wikipedia.org/wiki/Transmission_Control_Protocol) (Wikipedia) -- [HTTP Overview](/en-US/docs/Web/HTTP/Overview) +- [HTTP Overview](/en-US/docs/Web/HTTP/Guides/Overview) - [How browsers work](/en-US/docs/Web/Performance/Guides/How_browsers_work) - Related glossary terms: - {{Glossary("IPv4")}} diff --git a/files/en-us/glossary/tcp_slow_start/index.md b/files/en-us/glossary/tcp_slow_start/index.md index f3e17b5074d5338..04f430425bc7869 100644 --- a/files/en-us/glossary/tcp_slow_start/index.md +++ b/files/en-us/glossary/tcp_slow_start/index.md @@ -17,4 +17,4 @@ Congestion itself is a state that happens within a network layer when the messag ## See also - [Populating the page: how browsers work](/en-US/docs/Web/Performance/Guides/How_browsers_work) -- [http overview](/en-US/docs/Web/HTTP/Overview) +- [http overview](/en-US/docs/Web/HTTP/Guides/Overview) 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 76f6eccbcc6fede..bb709eccd2d063b 100644 --- a/files/en-us/glossary/time_to_first_byte/index.md +++ b/files/en-us/glossary/time_to_first_byte/index.md @@ -8,17 +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. This can be measured using the `{{domxref("PerformanceResourceTiming.requestStart", "requestStart")}}` attribute of {{domxref("PerformanceNavigationTiming")}}: +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.responseStart", "responseStart")}} attribute of {{domxref("PerformanceNavigationTiming")}}: -```javascript +```js 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. +> 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) +- [A typical HTTP session](/en-US/docs/Web/HTTP/Guides/Session) - [PerformanceResourceTiming](/en-US/docs/Web/API/PerformanceResourceTiming) - [PerformanceNavigationTiming](/en-US/docs/Web/API/PerformanceNavigationTiming) diff --git a/files/en-us/glossary/top_layer/index.md b/files/en-us/glossary/top_layer/index.md index c617a8ae4d9163d..709bb49fbd68ad8 100644 --- a/files/en-us/glossary/top_layer/index.md +++ b/files/en-us/glossary/top_layer/index.md @@ -8,11 +8,11 @@ page-type: glossary-definition The **top layer** is a specific layer that spans the entire width and height of the viewport and sits on top of all other layers displayed in a web document. It is created by the browser to contain elements that should appear on top of all other content on the page. -Elements placed in the top layer generate a new [stacking context](/en-US/docs/Web/CSS/CSS_positioned_layout/Understanding_z-index/Stacking_context), as do their corresponding {{cssxref("::backdrop")}} pseudo-elements. +Elements placed in the top layer generate a new [stacking context](/en-US/docs/Web/CSS/CSS_positioned_layout/Stacking_context), as do their corresponding {{cssxref("::backdrop")}} pseudo-elements. Elements that will appear in the top layer include: -- Fullscreen elements, i.e. elements that have been caused to display in fullscreen mode by a successful {{domxref("Element.requestFullscreen()")}} call. +- Fullscreen elements, i.e., elements that have been caused to display in fullscreen mode by a successful {{domxref("Element.requestFullscreen()")}} call. - {{htmlelement("dialog")}} elements displayed as a modal via a successful {{domxref("HTMLDialogElement.showModal()")}} call. - Popover elements shown via a successful {{domxref("HTMLElement.showPopover()")}} call. @@ -24,7 +24,7 @@ Note that the top layer is an internal browser concept and cannot be directly ma ## See also -- [The stacking context](/en-US/docs/Web/CSS/CSS_positioned_layout/Understanding_z-index/Stacking_context) +- [The stacking context](/en-US/docs/Web/CSS/CSS_positioned_layout/Stacking_context) - [Fullscreen API](/en-US/docs/Web/API/Fullscreen_API) - {{htmlelement("dialog")}} element, {{domxref("HTMLDialogElement")}} interface - [Popover API](/en-US/docs/Web/API/Popover_API) diff --git a/files/en-us/glossary/truthy/index.md b/files/en-us/glossary/truthy/index.md index ac9ac25f149ab75..1f5f140a0f53631 100644 --- a/files/en-us/glossary/truthy/index.md +++ b/files/en-us/glossary/truthy/index.md @@ -13,19 +13,19 @@ In {{Glossary("JavaScript")}}, a **truthy** value is a value that is considered Examples of _truthy_ values in JavaScript (which will be coerced to `true` in boolean contexts, and thus execute the `if` block): ```js -if (true) -if ({}) -if ([]) -if (42) -if ("0") -if ("false") -if (new Date()) -if (-42) -if (12n) -if (3.14) -if (-3.14) -if (Infinity) -if (-Infinity) +if (true); +if ({}); +if ([]); +if (42); +if ("0"); +if ("false"); +if (new Date()); +if (-42); +if (12n); +if (3.14); +if (-3.14); +if (Infinity); +if (-Infinity); ``` ### The logical AND operator, && @@ -33,10 +33,10 @@ if (-Infinity) If the first operand is truthy, the [logical AND operator](/en-US/docs/Web/JavaScript/Reference/Operators/Logical_AND) returns the second operand: ```js -true && "dog" +true && "dog"; // returns "dog" -[] && "dog" +[] && "dog"; // returns "dog" ``` diff --git a/files/en-us/glossary/type/index.md b/files/en-us/glossary/type/index.md index 824f78c4628f399..f5f47f71a8bdd6a 100644 --- a/files/en-us/glossary/type/index.md +++ b/files/en-us/glossary/type/index.md @@ -6,18 +6,18 @@ page-type: glossary-definition {{GlossarySidebar}} -**Type** is a characteristic of a {{glossary("value")}} affecting what kind of data it can store, and the structure that the data will adhere to. For example, a {{Glossary("boolean")}} [Data Type](/en-US/docs/Web/JavaScript/Data_structures) can hold only a `true` or `false` value at any given time, whereas a {{Glossary("string")}} has the ability to hold a string or a sequence of characters, a {{Glossary("number")}} can hold numerical values of any kind, and so on. +**Type** is a characteristic of a {{glossary("value")}} affecting what kind of data it can store, and the structure that the data will adhere to. For example, a {{Glossary("boolean")}} [Data Type](/en-US/docs/Web/JavaScript/Guide/Data_structures) can hold only a `true` or `false` value at any given time, whereas a {{Glossary("string")}} has the ability to hold a string or a sequence of characters, a {{Glossary("number")}} can hold numerical values of any kind, and so on. A value's data type also affects the operations that are valid on that value. For example, a value of type number can be multiplied by another number, but not by a string - even if that string contains _only_ a number, such as the string "2". -Types also provides us with useful knowledge about the comparison between different values. Comparison between structured types is not always an easy assumption, as even if the previous data structure is the same, there could be inherited structures inside of the [Prototype Chain](/en-US/docs/Web/JavaScript/Inheritance_and_the_prototype_chain). +Types also provides us with useful knowledge about the comparison between different values. Comparison between structured types is not always an easy assumption, as even if the previous data structure is the same, there could be inherited structures inside of the [Prototype Chain](/en-US/docs/Web/JavaScript/Guide/Inheritance_and_the_prototype_chain). If you are unsure of the type of a value, you can use the [`typeof`](/en-US/docs/Web/JavaScript/Reference/Operators/typeof) operator. ## See also - [Data type](https://en.wikipedia.org/wiki/Data_type) on Wikipedia -- [JavaScript data types](/en-US/docs/Web/JavaScript/Data_structures) +- [JavaScript data types](/en-US/docs/Web/JavaScript/Guide/Data_structures) - Related glossary terms: - {{Glossary("JavaScript")}} - {{Glossary("string")}} diff --git a/files/en-us/glossary/undefined/index.md b/files/en-us/glossary/undefined/index.md index 28a6b4ece745459..1908c2c7fe587da 100644 --- a/files/en-us/glossary/undefined/index.md +++ b/files/en-us/glossary/undefined/index.md @@ -11,12 +11,12 @@ page-type: glossary-definition ## Example ```js -let x; //create a variable but assign it no value +let x; // create a variable but assign it no value -console.log(`x's value is ${x}`); //logs "x's value is undefined" +console.log(`x's value is ${x}`); // logs "x's value is undefined" ``` ## See also - [Undefined value](https://en.wikipedia.org/wiki/Undefined_value) on Wikipedia -- [JavaScript data types and data structures](/en-US/docs/Web/JavaScript/Data_structures) +- [JavaScript data types and data structures](/en-US/docs/Web/JavaScript/Guide/Data_structures) diff --git a/files/en-us/glossary/user_agent/index.md b/files/en-us/glossary/user_agent/index.md index f3c84f62a01381d..ec3a6b754bb4440 100644 --- a/files/en-us/glossary/user_agent/index.md +++ b/files/en-us/glossary/user_agent/index.md @@ -20,7 +20,7 @@ A typical user agent string looks like this: `"Mozilla/5.0 (Windows NT 10.0; Win - [User agent](https://en.wikipedia.org/wiki/User_agent) on Wikipedia - {{domxref("navigator.userAgent")}} -- [Browser detection using the user agent](/en-US/docs/Web/HTTP/Browser_detection_using_the_user_agent) +- [Browser detection using the user agent](/en-US/docs/Web/HTTP/Guides/Browser_detection_using_the_user_agent) - {{RFC(2616, "", "14.43")}}: The `User-Agent` header - Related glossary terms: - {{Glossary("Browser")}} diff --git a/files/en-us/glossary/value/index.md b/files/en-us/glossary/value/index.md index 3d915f6dacfc4fa..f692441833e77c8 100644 --- a/files/en-us/glossary/value/index.md +++ b/files/en-us/glossary/value/index.md @@ -8,7 +8,7 @@ page-type: glossary-definition In the context of data or an object **{{Glossary("Wrapper", "wrapper")}}** around that data, the value is the **{{Glossary("Primitive","primitive value")}}** that the object wrapper contains. In the context of a **{{Glossary("Variable","variable")}}** or **{{Glossary("Property","property")}}**, the value can be either a primitive or an **{{Glossary("Object reference","object reference")}}**. -In the context of CSS property values, there are specified, computed, and actual values. The final value for every CSS property applied to every element and pseudo-element is the result of a four-step calculation: the value is determined through specification (the "[specified value](/en-US/docs/Web/CSS/CSS_cascade/specified_value)", then resolved into a value that is used for inheritance (the "[computed value](/en-US/docs/Web/CSS/CSS_cascade/computed_value)"), then converted into an absolute value if necessary (the "[used value](/en-US/docs/Web/CSS/CSS_cascade/used_value)"), and finally transformed according to the limitations of the local environment (the "[actual value](/en-US/docs/Web/CSS/CSS_cascade/actual_value)"). +In the context of CSS property values, there are specified, computed, and actual values. The final value for every CSS property applied to every element and pseudo-element is the result of a four-step calculation: the value is determined through specification (the "[specified value](/en-US/docs/Web/CSS/CSS_cascade/Value_processing#specified_value)", then resolved into a value that is used for inheritance (the "[computed value](/en-US/docs/Web/CSS/CSS_cascade/Value_processing#computed_value)"), then converted into an absolute value if necessary (the "[used value](/en-US/docs/Web/CSS/CSS_cascade/Value_processing#used_value)"), and finally transformed according to the limitations of the local environment (the "[actual value](/en-US/docs/Web/CSS/CSS_cascade/Value_processing#actual_value)"). For CSS data types, see [CSS values and units](/en-US/docs/Web/CSS/CSS_Values_and_Units). diff --git a/files/en-us/glossary/viewport/index.md b/files/en-us/glossary/viewport/index.md index 2c1e8c0b45a7d71..857e6d0b9621747 100644 --- a/files/en-us/glossary/viewport/index.md +++ b/files/en-us/glossary/viewport/index.md @@ -12,7 +12,7 @@ In web browser terms, it refers to the part of the document being viewed in the The portion of the viewport that is currently visible is called the **{{Glossary("visual viewport")}}**. This can be smaller than the layout viewport, such as when the user has pinched-zoomed. The {{Glossary("layout viewport")}} remains the same, but the visual viewport became smaller. -The visual viewport of an {{htmlelement("iframe")}}, {{htmlelement("svg")}}, or {{htmlelement("object")}} element is the size of the inner width and height of the respective element, rather than the parent document. For content rendered inside the element, the visual viewport and layout viewport are the same. +The visual viewport of an {{htmlelement("iframe")}}, {{svgelement("svg")}}, or {{htmlelement("object")}} element is the size of the inner width and height of the respective element, rather than the parent document. For content rendered inside the element, the visual viewport and layout viewport are the same. ## See also diff --git a/files/en-us/glossary/void_element/index.md b/files/en-us/glossary/void_element/index.md index 62910e605cd9375..dd1c8afb2ef5f0f 100644 --- a/files/en-us/glossary/void_element/index.md +++ b/files/en-us/glossary/void_element/index.md @@ -48,4 +48,4 @@ In SVG and MathML, elements that cannot have any child nodes are allowed to be m ## See also -- [Replaced elements](/en-US/docs/Web/CSS/Replaced_element) +- {{glossary("Replaced elements")}} diff --git a/files/en-us/glossary/wcag/index.md b/files/en-us/glossary/wcag/index.md index 9fab7cd3edc1cdd..a3b8896183488e7 100644 --- a/files/en-us/glossary/wcag/index.md +++ b/files/en-us/glossary/wcag/index.md @@ -20,7 +20,7 @@ WCAG 2 uses three levels of conformance: ## See also -- [Understanding the Web Content Accessibility Guidelines](/en-US/docs/Web/Accessibility/Understanding_WCAG) +- [Understanding the Web Content Accessibility Guidelines](/en-US/docs/Web/Accessibility/Guides/Understanding_WCAG) - [WCAG](https://en.wikipedia.org/wiki/Web_Content_Accessibility_Guidelines) on Wikipedia - [Web Content Accessibility Guidelines (WCAG) 2.2: Recommendation](https://www.w3.org/TR/WCAG22/) - [W3C Accessibility Guidelines (WCAG) 3.0: Working Draft](https://www.w3.org/TR/wcag-3.0/) diff --git a/files/en-us/glossary/webdav/index.md b/files/en-us/glossary/webdav/index.md index d7d43570e4f1359..dc99cbdebae7772 100644 --- a/files/en-us/glossary/webdav/index.md +++ b/files/en-us/glossary/webdav/index.md @@ -12,7 +12,7 @@ WebDAV is rarely used alone, but two extensions are very common: {{Glossary("Cal WebDAV allows clients to -- add, delete, and retrieve webpage metadata (e.g. author or creation date) +- add, delete, and retrieve webpage metadata (e.g., author or creation date) - link pages of any media type to related pages - create sets of documents and retrieve hierarchical list - copy and move webpages diff --git a/files/en-us/glossary/webgl/index.md b/files/en-us/glossary/webgl/index.md index 041c77fa7b2a871..a00924dccc49fe9 100644 --- a/files/en-us/glossary/webgl/index.md +++ b/files/en-us/glossary/webgl/index.md @@ -12,7 +12,7 @@ The [Khronos Group](https://www.khronos.org/) maintains WebGL, which is based on You can invoke WebGL within the {{Glossary("HTML")}} {{HTMLElement("canvas")}} element, which provides a rendering surface. -All major {{Glossary("Browser","browsers")}} now support WebGL, but its availability depends also on external factors (e.g. GPU support). +All major {{Glossary("Browser","browsers")}} now support WebGL, but its availability depends also on external factors (e.g., GPU support). ## See also diff --git a/files/en-us/glossary/webvtt/index.md b/files/en-us/glossary/webvtt/index.md index 0cf78526f2f81bf..c84080873ebd811 100644 --- a/files/en-us/glossary/webvtt/index.md +++ b/files/en-us/glossary/webvtt/index.md @@ -14,4 +14,4 @@ WebVTT files provide metadata that is time-aligned with audio or video content l - [WebVTT](https://en.wikipedia.org/wiki/WebVTT) on Wikipedia - [WebVTT](/en-US/docs/Web/API/WebVTT_API) on MDN -- [Specification](https://www.w3.org/TR/webvtt1/) +- [Specification](https://w3c.github.io/webvtt/) diff --git a/files/en-us/glossary/zstandard_compression/index.md b/files/en-us/glossary/zstandard_compression/index.md index a0af3df48a14de5..178f6246121b62d 100644 --- a/files/en-us/glossary/zstandard_compression/index.md +++ b/files/en-us/glossary/zstandard_compression/index.md @@ -10,7 +10,7 @@ page-type: glossary-definition Zstandard, or `zstd` as short version, is a fast lossless compression algorithm, targeting real-time compression scenarios at zlib-level and better compression ratios. It's backed by a very fast entropy stage, provided by [Huff0 and FSE library](https://github.com/Cyan4973/FiniteStateEntropy). It often offers better compression ratios than {{glossary("Brotli_compression", "brotli")}} at equivalent CPU costs, or better CPU costs at equivalent compression ratios. -For browser support, see [Content-Encoding: Browser compatibility](/en-US/docs/Web/HTTP/Headers/Content-Encoding#browser_compatibility). +For browser support, see [Content-Encoding: Browser compatibility](/en-US/docs/Web/HTTP/Reference/Headers/Content-Encoding#browser_compatibility). ## See also diff --git a/files/en-us/learn_web_development/about/index.md b/files/en-us/learn_web_development/about/index.md index de93de18d24719b..dd8efd391ae2fa5 100644 --- a/files/en-us/learn_web_development/about/index.md +++ b/files/en-us/learn_web_development/about/index.md @@ -2,10 +2,9 @@ title: About Learn web development slug: Learn_web_development/About page-type: landing-page +sidebar: learnsidebar --- -{{LearnSidebar}} - MDN Learn web development aims to teach the fundamental skills and knowledge that a front-end web developer should have for employability and longevity in today's web industry. It embodies the values we think the web should have — accessibility, sustainability, usability, performance, and community. We would love educators, developers, and students to use this resource and champion these values in their work, in their teachings, and in the products they build. This content has been created by the MDN community with review and feedback from experts within Mozilla and throughout the wider web community. Thank you for your valuable input; you know who you are! @@ -23,7 +22,7 @@ In addition, Mozilla talks to industry professionals every day, and we regularly - Gaps in the knowledge of how browsers fundamentally work, how they surface information, and the interactivity you get for free. This causes solutions to be overcomplicated and often inaccessible. - Limited problem-solving, teamwork, research, and other vital soft skills. -As a result, we created a curriculum to help guide people towards learning a better skillset, making them more employable, and enabling them to build a better, more accessible, more responsible web of tomorrow. We want them to have the best possible chance of success. We [launched the MDN Curriculum in early 2024](/en-US/blog/mdn-curriculum-launch/). +As a result, we created a curriculum to help guide people towards learning a better skill set, making them more employable, and enabling them to build a better, more accessible, more responsible web of tomorrow. We want them to have the best possible chance of success. We [launched the MDN Curriculum in early 2024](/en-US/blog/mdn-curriculum-launch/). However, we quickly received feedback that users found it confusing having two learning resources on MDN, with the curriculum/learning pathway in one place and the learning content in another place. as a result, we [merged the Curriculum into the learning area in December 2024](/en-US/docs/Learn_web_development/Changelog#december_2024). @@ -79,7 +78,7 @@ The topics presented are covered in differing levels of detail. There are also several areas that we explicitly don't cover in this curriculum, namely: - Exhaustive coverage of back-end languages/platforms. We do provide a brief introduction in [Node.js (Express)](/en-US/docs/Learn_web_development/Extensions/Server-side/Express_Nodejs) and [Python (Django)](/en-US/docs/Learn_web_development/Extensions/Server-side/Django) as it is useful to every web developer to understand how HTTP and server-side technologies work. However, we don't provide exhaustive coverage across multiple platforms; that would be out of scope for MDN. -- In-depth coverage of traditional relational databases (for example, [MySQL](https://dev.mysql.com/doc/) or [Postgres](https://www.postgresql.org/)) and other server-side datastores (for example, cloud databases such as [MongoDB](https://www.mongodb.com/) or [Google Cloud Datastore](https://cloud.google.com/datastore/)). We provide a brief introduction to such technologies in our [Server-side website programming](/en-US/docs/Learn_web_development/Extensions/Server-side) modules. +- In-depth coverage of traditional relational databases (for example, [MySQL](https://dev.mysql.com/doc/) or [Postgres](https://www.postgresql.org/)) and other server-side datastores (for example, cloud databases such as [MongoDB](https://www.mongodb.com/) or [Google Cloud Datastore](https://cloud.google.com/products/datastore)). We provide a brief introduction to such technologies in our [Server-side website programming](/en-US/docs/Learn_web_development/Extensions/Server-side) modules. - Deep-dive DevOps topics such as cloud platforms for provisioning and automation (for example, [Amazon AWS](https://aws.amazon.com/), [Google Cloud Platform](https://console.cloud.google.com/), and [Microsoft Azure](https://azure.microsoft.com/)) and containerization tools (for example, [Kubernetes](https://kubernetes.io/) and [Docker](https://www.docker.com/)). We lightly touch upon some tools that are considered to be in the DevOps space — like GitHub and automated testing tools — but these have distinct crossover into the front-end developer space. - Graphic design beyond the basic knowledge outlined in [Design for developers](/en-US/docs/Learn_web_development/Core/Design_for_developers). - Skills related to roles such as product and program management (for example, organization, research, and planning). @@ -116,7 +115,7 @@ We intend to do this in Q2 each year, to give educators time over Q2/Q3 to imple #### How does MDN know Scrimba's courses are high quality and follow best practices? -Scrimba already had a great reputation before we started talking to them about a partnership. However, we didn't just take the community's word for it. We did an extensive review of Scrimba's [Frontend Developer Career Path](https://v2.scrimba.com/the-frontend-developer-career-path-c0j:details?via=mdn) (FDCP) and provided them with feedback on possible improvements, focusing on increasing coverage of best practices and conformance to our [Core modules](/en-US/docs/Learn_web_development/Core). Scrimba implemented all of our feedback, and the FDCP is even better than it was before. Now that it conforms to our Curriculum Core, we are confident it aligns with MDN standards. +Scrimba already had a great reputation before we started talking to them about a partnership. However, we didn't just take the community's word for it. We did an extensive review of Scrimba's [Frontend Developer Career Path](https://scrimba.com/the-frontend-developer-career-path-c0j:details?via=mdn) (FDCP) and provided them with feedback on possible improvements, focusing on increasing coverage of best practices and conformance to our [Core modules](/en-US/docs/Learn_web_development/Core). Scrimba implemented all of our feedback, and the FDCP is even better than it was before. Now that it conforms to our Curriculum Core, we are confident it aligns with MDN standards. #### Is MDN sharing user data with Scrimba? diff --git a/files/en-us/learn_web_development/changelog/index.md b/files/en-us/learn_web_development/changelog/index.md index 22adf8a1d7cd95d..917971fe6112c41 100644 --- a/files/en-us/learn_web_development/changelog/index.md +++ b/files/en-us/learn_web_development/changelog/index.md @@ -2,10 +2,9 @@ title: Changelog slug: Learn_web_development/Changelog page-type: landing-page +sidebar: learnsidebar --- -{{LearnSidebar}} - ## December 2024 A major update to the Learn web development section was started in November 2024 and finally published in December 2024. To summarize, the MDN Curriculum has been merged into Learn web development. diff --git a/files/en-us/learn_web_development/core/accessibility/accessibility_troubleshooting/index.md b/files/en-us/learn_web_development/core/accessibility/accessibility_troubleshooting/index.md index 3bace7f0cfa0424..48726a662184e0b 100644 --- a/files/en-us/learn_web_development/core/accessibility/accessibility_troubleshooting/index.md +++ b/files/en-us/learn_web_development/core/accessibility/accessibility_troubleshooting/index.md @@ -1,11 +1,11 @@ --- title: "Challenge: Accessibility troubleshooting" +short-title: "Challenge: A11y debugging" slug: Learn_web_development/Core/Accessibility/Accessibility_troubleshooting page-type: learn-module-assessment +sidebar: learnsidebar --- -{{LearnSidebar}} - {{PreviousMenuNext("Learn_web_development/Core/Accessibility/Mobile","Learn_web_development/Core/Design_for_developers", "Learn_web_development/Core/Accessibility")}} In the challenge for this module, we present to you a simple site with a number of accessibility issues that you need to diagnose and fix. diff --git a/files/en-us/learn_web_development/core/accessibility/css_and_javascript/index.md b/files/en-us/learn_web_development/core/accessibility/css_and_javascript/index.md index 743a1d084869d66..ee04dc2558f5610 100644 --- a/files/en-us/learn_web_development/core/accessibility/css_and_javascript/index.md +++ b/files/en-us/learn_web_development/core/accessibility/css_and_javascript/index.md @@ -1,11 +1,11 @@ --- title: CSS and JavaScript accessibility best practices +short-title: Accessible CSS and JS slug: Learn_web_development/Core/Accessibility/CSS_and_JavaScript page-type: learn-module-chapter +sidebar: learnsidebar --- -{{LearnSidebar}} - {{PreviousMenuNext("Learn_web_development/Core/Accessibility/HTML","Learn_web_development/Core/Accessibility/WAI-ARIA_basics", "Learn_web_development/Core/Accessibility")}} CSS and JavaScript, when used properly, also have the potential to allow for accessible web experiences, or they can significantly harm accessibility if misused. This article outlines some CSS and JavaScript best practices that should be considered to ensure even complex content is as accessible as possible. @@ -158,7 +158,7 @@ a:active { } ``` -The standard link conventions are underlined and a different color (default: blue) in their standard state, another color variation when the link has previously been visited (default: purple), and yet another color when the link is activated (default: red). In addition, the mouse pointer changes to a pointer icon when links are moused over, and the link receives a highlight when focused (e.g. via tabbing) or activated. The following image shows the highlight in both Firefox (a dotted outline) and Chrome (a blue outline): +The standard link conventions are underlined and a different color (default: blue) in their standard state, another color variation when the link has previously been visited (default: purple), and yet another color when the link is activated (default: red). In addition, the mouse pointer changes to a pointer icon when links are moused over, and the link receives a highlight when focused (e.g., via tabbing) or activated. The following image shows the highlight in both Firefox (a dotted outline) and Chrome (a blue outline): ![Screenshot of a list of links in Firefox browser. The list contains 4 items. The second list item is highlighted using a blue dotted outline when it is focussed via tabbing.](focus-highlight-firefox.png) @@ -232,7 +232,7 @@ Modern JavaScript is a powerful language, and we can do so much with it these da Simple content and functionality is arguably easy to make accessible — for example text, images, tables, forms and push button that activate functions. As we looked at in our [HTML: A good basis for accessibility](/en-US/docs/Learn_web_development/Core/Accessibility/HTML) article, the key considerations are: - Good semantics: Using the right element for the right job. For example, making sure you use headings and paragraphs, and {{htmlelement("button")}} and {{htmlelement("a")}} elements -- Making sure content is available as text, either directly as text content, good text labels for form elements, or [text alternatives](/en-US/docs/Learn_web_development/Core/Accessibility/HTML#text_alternatives), e.g. alt text for images. +- Making sure content is available as text, either directly as text content, good text labels for form elements, or [text alternatives](/en-US/docs/Learn_web_development/Core/Accessibility/HTML#text_alternatives), e.g., alt text for images. We also looked at an example of how to use JavaScript to build in functionality where it is missing — see [Building keyboard accessibility back in](/en-US/docs/Learn_web_development/Core/Accessibility/HTML#building_keyboard_accessibility_back_in). This is not ideal — really you should just use the right element for the right job — but it shows that it is possible in situations where for some reason you can't control the markup that is used. Another way to improve accessibility for non-semantic JavaScript-powered widgets is to use WAI-ARIA to provide extra semantics for screen reader users. The next article will also cover this in detail. @@ -274,8 +274,7 @@ form.onsubmit = validate; function validate(e) { errorList.textContent = ""; - for (let i = 0; i < formItems.length; i++) { - const testItem = formItems[i]; + for (const testItem of formItems) { if (testItem.input.value === "") { errorField.style.left = "360px"; createLink(testItem); @@ -291,7 +290,7 @@ function validate(e) { > [!NOTE] > In this example, we are hiding and showing the error message box using absolute positioning rather than another method such as visibility or display, because it doesn't interfere with the screen reader being able to read content from it. -Real form validation would be much more complex than this — you'd want to check that the entered name actually looks like a name, the entered age is actually a number and is realistic (e.g. nonnegative and less than 4 digits). Here we've just implemented a simple check that a value has been filled in to each input field (`if (testItem.input.value === '')`). +Real form validation would be much more complex than this — you'd want to check that the entered name actually looks like a name, the entered age is actually a number and is realistic (e.g., nonnegative and less than 4 digits). Here we've just implemented a simple check that a value has been filled in to each input field (`if (testItem.input.value === '')`). When the validation has been performed, if the tests pass then the form is submitted. If there are errors (`if (errorList.hasChildNodes())`) then we stop the form submitting (using [`preventDefault()`](/en-US/docs/Web/API/Event/preventDefault)), and display any error messages that have been created (see below). This mechanism means that the errors will only be shown if there are errors, which is better for usability. @@ -358,7 +357,7 @@ The [click](/en-US/docs/Web/API/Element/click_event) event is interesting — it ## Test your skills! -You've reached the end of this article, but can you remember the most important information? You can find some further tests to verify that you've retained this information before you move on — see [Test your skills: CSS and JavaScript accessibility](/en-US/docs/Learn_web_development/Core/Accessibility/CSS_and_JavaScript/Test_your_skills:_CSS_and_JavaScript_accessibility). +You've reached the end of this article, but can you remember the most important information? You can find some further tests to verify that you've retained this information before you move on — see [Test your skills: CSS and JavaScript accessibility](/en-US/docs/Learn_web_development/Core/Accessibility/Test_your_skills/CSS_and_JavaScript). ## Summary diff --git a/files/en-us/learn_web_development/core/accessibility/css_and_javascript/test_your_skills_colon__css_and_javascript_accessibility/index.md b/files/en-us/learn_web_development/core/accessibility/css_and_javascript/test_your_skills_colon__css_and_javascript_accessibility/index.md deleted file mode 100644 index 5ad20fdc562413c..000000000000000 --- a/files/en-us/learn_web_development/core/accessibility/css_and_javascript/test_your_skills_colon__css_and_javascript_accessibility/index.md +++ /dev/null @@ -1,55 +0,0 @@ ---- -title: "Test your skills: CSS and JavaScript accessibility" -slug: Learn_web_development/Core/Accessibility/CSS_and_JavaScript/Test_your_skills:_CSS_and_JavaScript_accessibility -page-type: learn-module-assessment ---- - -{{learnsidebar}} - -The aim of this skill test is to assess whether you've understood our [CSS and JavaScript accessibility best practices](/en-US/docs/Learn_web_development/Core/Accessibility/CSS_and_JavaScript) article. - -> [!NOTE] -> You can try solutions in the interactive editors on this page or in an online editor such as [CodePen](https://codepen.io/), [JSFiddle](https://jsfiddle.net/), or [Glitch](https://glitch.com/). -> -> If you get stuck, you can reach out to us in one of our [communication channels](/en-US/docs/MDN/Community/Communication_channels). - -## CSS accessibility 1 - -In the first task you are presented with a list of links. However, their accessibility is pretty bad — there is no way to really tell that they are links, or to tell which one the user is focussed on. - -We'd like you to assume that the existing ruleset with the `a` selector is supplied by some CMS, and that you can't change it — instead, you need to create new rules to make the links look and behave like links, and for the user to be able to tell where they are in the list. - -Try updating the live code below to recreate the finished example: - -{{EmbedGHLiveSample("learning-area/accessibility/tasks/html-css/css/css-a11y1.html", '100%', 700)}} - -> [!CALLOUT] -> -> [Download the starting point for this task](https://github.com/mdn/learning-area/blob/main/accessibility/tasks/html-css/css/css-a11y1-download.html) to work in your own editor or in an online editor. - -## CSS accessibility 2 - -In this next task you are presented with a simple bit of content — just headings and paragraphs. There are accessibility issues with the colors and sizing of the text; we'd like you to: - -1. Explain what the problems are, and what the guidelines are that state the acceptable values for color and sizing. -2. Select new values for the color and font-size that fix the problem. -3. Update the CSS with these new values to fix the problem. -4. Test the code to make sure the problem is now fixed. Explain what tools or methods you used to select the new values and test the code. - -Try updating the live code below to recreate the finished example: - -{{EmbedGHLiveSample("learning-area/accessibility/tasks/html-css/css/css-a11y2.html", '100%', 700)}} - -> [!CALLOUT] -> -> [Download the starting point for this task](https://github.com/mdn/learning-area/blob/main/accessibility/tasks/html-css/css/css-a11y2-download.html) to work in your own editor or in an online editor. - -## JavaScript accessibility 1 - -In our final task here, you have some JavaScripting to do. We have an app that presents a list of animal names. Clicking one of the animal names causes a further description of that animal to appear in a box below the list. - -But it is not very accessible — in its current state you can only operate it with the mouse. We'd like you to add to the HTML and JavaScript to make it keyboard accessible too. - -> [!CALLOUT] -> -> [Download the starting point for this task](https://github.com/mdn/learning-area/blob/main/accessibility/tasks/js/js/js1-download.html) to work in your own editor or in an online editor. 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 080ea658d3043c6..df15d09a34fe248 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 @@ -1,11 +1,11 @@ --- title: "HTML: A good basis for accessibility" +short-title: Accessible HTML slug: Learn_web_development/Core/Accessibility/HTML page-type: learn-module-chapter +sidebar: learnsidebar --- -{{LearnSidebar}} - {{PreviousMenuNext("Learn_web_development/Core/Accessibility/Tooling","Learn_web_development/Core/Accessibility/CSS_and_JavaScript", "Learn_web_development/Core/Accessibility")}} A great deal of web content can be made accessible just by making sure the correct Hypertext Markup Language elements are used for the correct purpose at all times. This article looks in detail at how HTML can be used to ensure maximum accessibility. @@ -61,15 +61,15 @@ Let's get on and look at accessible HTML in more detail. We've already talked about the importance of proper semantics, and why we should use the right HTML element for the job. This cannot be ignored, as it is one of the main places that accessibility is badly broken if not handled properly. -Out there on the web, the truth is that people do some very strange things with HTML markup. Some abuses of HTML are due to legacy practices that have not been completely forgotten, and some are just plain ignorance. Whatever the case, you should replace such bad code. +Out there on the web, the truth is that people do some very strange things with HTML markup. Often, misuse of HTML is because of legacy practices that haven't gone away yet, but sometimes it occurs because authors don't know any better. Whatever the case, you should replace bad code with good semantic markup wherever possible, in both static HTML pages and dynamically-generated HTML from [server-side](/en-US/docs/Learn_web_development/Extensions/Server-side) code or [client-side JavaScript frameworks](/en-US/docs/Learn_web_development/Core/Frameworks_libraries) such as React. -Sometimes you are not in the position to get rid of lousy markup — your pages might be generated by some kind of server-side framework over which you don't have full control, or you might have third party content on your page (such as ad banners) over which you have no control. +Sometimes you are not in a position to get rid of lousy markup — your pages might be dependant on server-side code or web/framework components that you have no control over, or you might have third-party content on your page (such as ad banners). The goal isn't "all or nothing"; every improvement you can make will help the cause of accessibility. -### Text content +### Use well-structured text content -One of the best accessibility aids a screen reader user can have is an excellent content structure with headings, paragraphs, lists, etc. An excellent semantic example might look something like the following: +One of the best accessibility aids a screen reader user can have is an excellent text structure with headings, paragraphs, lists, etc. A good semantic example might look something like the following: ```html example-good <h1>My heading</h1> @@ -135,89 +135,19 @@ If you try our longer version out with a screen reader (see [bad-semantics.html] There are other issues too beyond accessibility — it is harder to style the content using CSS, or manipulate it with JavaScript, for example, because there are no elements to use as selectors. -#### Using clear language +### Use clear language The language you use can also affect accessibility. In general, you should use clear language that is not overly complex and doesn't use unnecessary jargon or slang terms. This not only benefits people with cognitive or other disabilities; it benefits readers for whom the text is not written in their first language, younger people…, everyone, in fact! Apart from this, you should try to avoid using language and characters that don't get read out clearly by the screen reader. For example: - Don't use dashes if you can avoid it. Instead of writing 5–7, write 5 to 7. - Expand abbreviations — instead of writing Jan, write January. -- Expand acronyms, at least once or twice, then use the [`<abbr>`](/en-US/docs/Web/HTML/Element/abbr) tag to describe them. +- Expand acronyms, at least once or twice, then use the [`<abbr>`](/en-US/docs/Web/HTML/Reference/Elements/abbr) tag to describe them. -### Page layouts +### Structure page sections logically -In the bad old days, people used to create page layouts using HTML tables — using different table cells to contain the header, footer, sidebar, main content column, etc. This is not a good idea because a screen reader will likely give out confusing readouts, especially if the layout is complex and has many nested tables. +You should use appropriate [sectioning elements](/en-US/docs/Web/HTML/Reference/Elements#content_sectioning) to structure your webpages, for example navigation ({{htmlelement("nav")}}), footer ({{htmlelement("footer")}}), and repeating content units ({{htmlelement("article")}}). These provide extra semantics for screen readers (and other tools) to give users extra clues about the content they are navigating. -Try our example [table-layout.html](https://mdn.github.io/learning-area/accessibility/html/table-layout.html) example, which looks something like this: - -```html -<table width="1200"> - <!-- main heading row --> - <tr id="heading"> - <td colspan="6"> - <h1 align="center">Header</h1> - </td> - </tr> - <!-- nav menu row --> - <tr id="nav" bgcolor="#ffffff"> - <td width="200"> - <a href="#" align="center">Home</a> - </td> - <td width="200"> - <a href="#" align="center">Our team</a> - </td> - <td width="200"> - <a href="#" align="center">Projects</a> - </td> - <td width="200"> - <a href="#" align="center">Contact</a> - </td> - <td width="300"> - <form width="300"> - <label - >Search - <input - type="search" - name="q" - placeholder="Search query" - width="300" /> - </label> - </form> - </td> - <td width="100"> - <button width="100">Go!</button> - </td> - </tr> - <!-- spacer row --> - <tr id="spacer" height="10"> - <td></td> - </tr> - <!-- main content and aside row --> - <tr id="main"> - <td id="content" colspan="4"> - <!-- main content goes here --> - </td> - <td id="aside" colspan="2" valign="top"> - <h2>Related</h2> - - <!-- aside content goes here --> - </td> - </tr> - <!-- spacer row --> - <tr id="spacer" height="10"> - <td></td> - </tr> - <!-- footer row --> - <tr id="footer"> - <td colspan="6"> - <p>©Copyright 1996 by nobody. All rights reversed.</p> - </td> - </tr> -</table> -``` - -If you try to navigate this using a screen reader, it will probably tell you that there's a table to be looked at (although some screen readers can guess the difference between table layouts and data tables). You'll then likely (depending on which screen reader you're using) have to go down into the table as an object and look at its features separately, then get out of the table again to carry on navigating the content. - -Table layouts are a relic of the past — they made sense back when CSS support was not widespread in browsers, but now they just create confusion for screen reader users. Additionally, their source code requires more markup, which makes them less flexible and more difficult to maintain. You can verify these claims by comparing your previous experience with a [more modern website structure example](https://mdn.github.io/learning-area/html/introduction-to-html/document_and_website_structure/), which could look something like this: +For example, a modern content structure could look something like this: ```html <header> @@ -251,14 +181,11 @@ Table layouts are a relic of the past — they made sense back when CSS support </footer> ``` -If you try our more modern structure example with a screen reader, you'll notice that the layout markup no longer interferes with or causes confusion in the content readout. It is also much leaner and smaller in terms of code size, which means the code is easier to maintain and requires less bandwidth for users to download, making it particularly beneficial for those on slow connections. - -Another consideration when creating layouts is using HTML semantic elements as seen in the above example (see [content sectioning](/en-US/docs/Web/HTML/Element#content_sectioning)) — you can create a layout using only nested {{htmlelement("div")}} elements, but it is better to use appropriate sectioning elements to wrap your main navigation ({{htmlelement("nav")}}), footer ({{htmlelement("footer")}}), repeating content units ({{htmlelement("article")}}), etc. These provide extra semantics for screen readers (and other tools) to give users extra clues about the content they are navigating (see [Screen Reader Support for new HTML5 Section Elements](https://www.accessibilityoz.com/2020/02/html5-sectioning-elements-and-screen-readers/) for an idea of what screen reader support is like). +You can find a [full example here](https://mdn.github.io/learning-area/html/introduction-to-html/document_and_website_structure/). -> [!NOTE] -> In addition to having good semantics and an attractive layout, your content should make logical sense in its source order — you can always place it where you want using CSS later on, but you should get the source order right to start with, so what screen reader users get read out to them will make sense. +In addition to having good semantics and an attractive layout, your content should make logical sense in its source order — you can always place it where you want using CSS later on, but you should get the source order right to start with, so what screen reader users get read out to them will make sense. -### UI controls +### Use semantic UI controls where possible By UI controls, we mean the main parts of web documents that users interact with — most commonly buttons, links, and form controls. In this section, we'll look at the basic accessibility concerns to be aware of when creating such controls. Later articles on WAI-ARIA and multimedia will look at other aspects of UI accessibility. @@ -271,7 +198,7 @@ One key aspect of the accessibility of UI controls is that by default, browsers You can then press Enter/Return to follow a focused link or press a button (we've included some JavaScript to make the buttons alert a message), or start typing to enter text in a text input. Other form elements have different controls; for example, the {{htmlelement("select")}} element can have its options displayed and cycled between using the up and down arrow keys. -You essentially get this behavior for free, just by using the appropriate elements, e.g. +You essentially get this behavior for free, just by using the appropriate elements, for example: ```html example-good <h1>Links</h1> @@ -316,7 +243,7 @@ You essentially get this behavior for free, just by using the appropriate elemen This means using links, buttons, form elements, and labels appropriately (including the {{htmlelement("label")}} element for form controls). -However, it is again the case that people sometimes do strange things with HTML. For example, you sometimes see buttons marked up using {{htmlelement("div")}}s, for example: +However, this is another case where people sometimes do strange things with HTML. For example, you sometimes see buttons marked up using {{htmlelement("div")}}s, for example: ```html example-bad <div data-message="This is from the first button">Click me!</div> @@ -324,7 +251,7 @@ However, it is again the case that people sometimes do strange things with HTML. <div data-message="This is from the third button">And me!</div> ``` -But using such code is not advised — you immediately lose the native keyboard accessibility you would have had if you'd just used {{htmlelement("button")}} elements, plus you don't get any of the default CSS styling that buttons get. In the rare to non-existent case when you need to use a non-button element for a button, use the [`button` role](/en-US/docs/Web/Accessibility/ARIA/Roles/button_role) and implement all the default button behaviors, including keyboard and mouse button support. +But using such code is not advised — you immediately lose the native keyboard accessibility you would have had if you'd just used {{htmlelement("button")}} elements, plus you don't get any of the default CSS styling that buttons get. In the rare to non-existent case when you need to use a non-button element for a button, use the [`button` role](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/button_role) and implement all the default button behaviors, including keyboard and mouse button support. #### Building keyboard accessibility back in @@ -342,12 +269,12 @@ Adding such advantages back in takes a bit of work (you can see an example in ou </div> ``` -Basically, the [`tabindex`](/en-US/docs/Web/HTML/Global_attributes/tabindex) attribute is primarily intended to allow tabbable elements to have a custom tab order (specified in positive numerical order), instead of just being tabbed through in their default source order. This is nearly always a bad idea, as it can cause major confusion. Use it only if you really need to, for example, if the layout shows things in a very different visual order to the source code, and you want to make things work more logically. There are two other options for `tabindex`: +Basically, the [`tabindex`](/en-US/docs/Web/HTML/Reference/Global_attributes/tabindex) attribute is primarily intended to allow tabbable elements to have a custom tab order (specified in positive numerical order), instead of just being tabbed through in their default source order. This is nearly always a bad idea, as it can cause major confusion. Use it only if you really need to, for example, if the layout shows things in a very different visual order to the source code, and you want to make things work more logically. There are two other options for `tabindex`: - `tabindex="0"` — as indicated above, this value allows elements that are not normally tabbable to become tabbable. This is the most useful value of `tabindex`. - `tabindex="-1"` — this allows not normally tabbable elements to receive focus programmatically, e.g., via JavaScript, or as the target of links. -While the above addition allows us to tab to the buttons, it does not allow us to activate them via the <kbd>Enter</kbd>/<kbd>Return</kbd> key. To do that, we had to add the following bit of JavaScript trickery: +While the above addition allows us to tab to the buttons, it does not allow us to activate them via the <kbd>Enter</kbd>/<kbd>Return</kbd> key. To do that, we had to add the following bit of JavaScript: ```js document.onkeydown = (e) => { @@ -362,7 +289,7 @@ Here we add a listener to the `document` object to detect when a button has been This is a lot of extra hassle to build the functionality back in. And there's bound to be other problems with it. **Better to just use the right element for the right job in the first place.** -#### Meaningful text labels +#### Use meaningful text labels UI control text labels are very useful to all users, but getting them right is particularly important to users with disabilities. @@ -486,7 +413,7 @@ We have a simple example written up, [accessible-image.html](https://mdn.github. </p> ``` -The first image, when viewed by a screen reader, doesn't really offer the user much help — VoiceOver for example reads out "/dinosaur.png, image". It reads out the filename to try to provide some help. In this example the user will at least know it is a dinosaur of some kind, but often files may be uploaded with machine-generated file names (e.g. from a digital camera) and these file names would likely provide no context to the image's content. +The first image, when viewed by a screen reader, doesn't really offer the user much help — VoiceOver for example reads out "/dinosaur.png, image". It reads out the filename to try to provide some help. In this example the user will at least know it is a dinosaur of some kind, but often files may be uploaded with machine-generated file names (e.g., from a digital camera) and these file names would likely provide no context to the image's content. > [!NOTE] > This is why you should never include text content inside an image — screen readers can't access it. There are other disadvantages too — you can't select it and copy/paste it. Just don't do it! @@ -504,7 +431,7 @@ Any personal knowledge or extra description shouldn't be included here, as it is 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. > [!NOTE] -> Read [HTML images](/en-US/docs/Learn_web_development/Core/Structuring_content/HTML_images) and [Responsive images](/en-US/docs/Web/HTML/Responsive_images) for a lot more information about image implementation and best practices. +> Read [HTML images](/en-US/docs/Learn_web_development/Core/Structuring_content/HTML_images) and [Responsive images](/en-US/docs/Web/HTML/Guides/Responsive_images) for a lot more information about image implementation and best practices. > You can also check [An alt Decision Tree](https://www.w3.org/WAI/tutorials/images/decision-tree/) to learn how to use an alt attribute for images in various situations. If you do want to provide extra contextual information, you should put it in the text surrounding the image, or inside a `title` attribute, as shown above. In this case, most screen readers will read out the alt text, the title attribute, and the filename. In addition, browsers display title text as tooltips when moused over. @@ -521,7 +448,7 @@ Let's have another quick look at the fourth method: In this case, we are not using the `alt` attribute at all — instead, we have presented our description of the image as a regular text paragraph, given it an `id`, and then used the `aria-labelledby` attribute to refer to that `id`, which causes screen readers to use that paragraph as the alt text/label for that image. This is especially useful if you want to use the same text as a label for multiple images — something that isn't possible with `alt`. -> **Note:** [`aria-labelledby`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-labelledby) is part of the [WAI-ARIA](https://www.w3.org/TR/wai-aria-1.1/) spec, which allows developers to add in extra semantics to their markup to improve screen reader accessibility where needed. +> **Note:** [`aria-labelledby`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-labelledby) is part of the [WAI-ARIA](https://www.w3.org/TR/wai-aria-1.1/) spec, which allows developers to add in extra semantics to their markup to improve screen reader accessibility where needed. ### Figures and figure captions @@ -540,7 +467,7 @@ HTML includes two elements — {{htmlelement("figure")}} and {{htmlelement("figc </figure> ``` -While there is mixed screen reader support of associating figure captions with their figures, including [`aria-labelledby`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-labelledby) or [`aria-describedby`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-describedby) creates the association if none is present. That said, the element structure is useful for CSS styling, plus it provides a way to place a description of the image next to it in the source. +While there is mixed screen reader support of associating figure captions with their figures, including [`aria-labelledby`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-labelledby) or [`aria-describedby`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-describedby) creates the association if none is present. That said, the element structure is useful for CSS styling, plus it provides a way to place a description of the image next to it in the source. ### Empty alt attributes @@ -553,20 +480,20 @@ While there is mixed screen reader support of associating figure captions with t There may be times where an image is included in a page's design, but its primary purpose is for visual decoration. You'll notice in the code example above that the image's `alt` attribute is empty — this is to make screen readers recognize the image, but not attempt to describe the image (instead they'd just say "image", or similar). -The reason to use an empty `alt` instead of not including it is because many screen readers announce the whole image URL if no `alt` is provided. In the above example, the image is acting as a visual decoration to the heading it's associated with. In cases like this, and in cases where an image is only decoration and has no content value, you should include an empty `alt` in your `img` elements. Another alternative is to use the aria [`role`](/en-US/docs/Web/Accessibility/ARIA/Roles) attribute [`role="presentation"`](/en-US/docs/Web/Accessibility/ARIA/Roles/presentation_role) as this also stops screen readers from reading out alternative text. +The reason to use an empty `alt` instead of not including it is because many screen readers announce the whole image URL if no `alt` is provided. In the above example, the image is acting as a visual decoration to the heading it's associated with. In cases like this, and in cases where an image is only decoration and has no content value, you should include an empty `alt` in your `img` elements. Another alternative is to use the aria [`role`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles) attribute [`role="presentation"`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/presentation_role) as this also stops screen readers from reading out alternative text. > [!NOTE] > If possible you should use CSS to display images that are only decorative. ## More on links -Links (the [`<a>`](/en-US/docs/Web/HTML/Element/a) element with an `href` attribute), depending on how they are used, can help or harm accessibility. By default, links are accessible in appearance. They can improve accessibility by helping a user quickly navigate to different sections of a document. They can also harm accessibility if their accessible styling is removed or if JavaScript causes them to behave in unexpected ways. +Links (the [`<a>`](/en-US/docs/Web/HTML/Reference/Elements/a) element with an `href` attribute), depending on how they are used, can help or harm accessibility. By default, links are accessible in appearance. They can improve accessibility by helping a user quickly navigate to different sections of a document. They can also harm accessibility if their accessible styling is removed or if JavaScript causes them to behave in unexpected ways. ### Link styling By default, links are visually different from other text in both color and [text-decoration](/en-US/docs/Web/CSS/text-decoration), with links being blue and underlined by default, purple and underlined if visited, and with a [focus-ring](/en-US/docs/Web/CSS/:focus) when they receive keyboard focus. -Color should not be used as the sole method of distinguishing links from non-linking content. Link text color, like all text, has to be significantly different from the background color ([a 4.5:1 contrast](/en-US/docs/Web/Accessibility/Understanding_WCAG/Perceivable/Color_contrast)). In addition, links should visually be significantly different from non-linking text, with a minimum contrast requirement of 3:1 between link text and surrounding text and between default, visited, and focus/active states and a 4.5:1 contrast between all those state colors and the background color. +Color should not be used as the sole method of distinguishing links from non-linking content. Link text color, like all text, has to be significantly different from the background color ([a 4.5:1 contrast](/en-US/docs/Web/Accessibility/Guides/Understanding_WCAG/Perceivable/Color_contrast)). In addition, links should visually be significantly different from non-linking text, with a minimum contrast requirement of 3:1 between link text and surrounding text and between default, visited, and focus/active states and a 4.5:1 contrast between all those state colors and the background color. ### `onclick` events @@ -596,10 +523,10 @@ People experiencing low vision conditions, who are navigating with the aid of sc > ``` -If an icon is used in place of text to signify this kind of links behavior, make sure it includes an [alternate description](/en-US/docs/Web/HTML/Element/img#alt). +If an icon is used in place of text to signify this kind of links behavior, make sure it includes an [alternate description](/en-US/docs/Web/HTML/Reference/Elements/img#alt). - [WebAIM: Links and Hypertext - Hypertext Links](https://webaim.org/techniques/hypertext/hypertext_links) -- [MDN Understanding WCAG, Guideline 3.2 explanations](/en-US/docs/Web/Accessibility/Understanding_WCAG/Understandable#guideline_3.2_—_predictable_make_web_pages_appear_and_operate_in_predictable_ways) +- [MDN Understanding WCAG, Guideline 3.2 explanations](/en-US/docs/Web/Accessibility/Guides/Understanding_WCAG/Understandable#guideline_3.2_—_predictable_make_web_pages_appear_and_operate_in_predictable_ways) - [G200: Opening new windows and tabs from a link only when necessary | W3C Techniques for WCAG 2.0](https://www.w3.org/TR/WCAG20-TECHS/G200.html) - [G201: Giving users advanced warning when opening a new window | W3C Techniques for WCAG 2.0](https://www.w3.org/TR/WCAG20-TECHS/G201.html) @@ -611,7 +538,7 @@ Skip links are especially useful for people who navigate with the aid of assisti - [WebAIM: "Skip Navigation" Links](https://webaim.org/techniques/skipnav/) - [How–to: Use Skip Navigation links - The A11Y Project](https://www.a11yproject.com/posts/skip-nav-links/) -- [MDN Understanding WCAG, Guideline 2.4 explanations](/en-US/docs/Web/Accessibility/Understanding_WCAG/Operable#guideline_2.4_%e2%80%94_navigable_provide_ways_to_help_users_navigate_find_content_and_determine_where_they_are) +- [MDN Understanding WCAG, Guideline 2.4 explanations](/en-US/docs/Web/Accessibility/Guides/Understanding_WCAG/Operable#guideline_2.4_%e2%80%94_navigable_provide_ways_to_help_users_navigate_find_content_and_determine_where_they_are) - [Understanding Success Criterion 2.4.1 | W3C Understanding WCAG 2.0](https://www.w3.org/TR/UNDERSTANDING-WCAG20/navigation-mechanisms-skip.html) ### Proximity @@ -624,7 +551,7 @@ Spacing may be created using CSS properties such as {{CSSxRef("margin")}}. ## Test your skills -You've reached the end of this article, but can you remember the most important information? See [Test your skills: HTML Accessibility](/en-US/docs/Learn_web_development/Core/Accessibility/Test_your_skills:_HTML_accessibility) to verify that you've retained this information before you move on. +You've reached the end of this article, but can you remember the most important information? See [Test your skills: HTML Accessibility](/en-US/docs/Learn_web_development/Core/Accessibility/Test_your_skills/HTML) to verify that you've retained this information before you move on. ## Summary diff --git a/files/en-us/learn_web_development/core/accessibility/index.md b/files/en-us/learn_web_development/core/accessibility/index.md index 55f0f97efc5f0e5..a8208877f810eb8 100644 --- a/files/en-us/learn_web_development/core/accessibility/index.md +++ b/files/en-us/learn_web_development/core/accessibility/index.md @@ -1,11 +1,11 @@ --- -title: Accessibility +title: Accessibility on the web +short-title: Accessibility slug: Learn_web_development/Core/Accessibility page-type: learn-module +sidebar: learnsidebar --- -{{LearnSidebar}} - {{NextMenu("Learn_web_development/Core/Accessibility/What_is_accessibility", "Learn_web_development/Core")}} Access to web content such as public services, education, e-commerce sites, and entertainment is a human right. No one should be excluded based on disability, race, geography, or other human characteristics. This module discusses the best practices and techniques you should learn to make your websites as accessible as possible. @@ -46,7 +46,7 @@ You should be familiar with [HTML](/en-US/docs/Learn_web_development/Core/Struct - : Includes guides, checklists, tools, and more. - [Web Accessibility Evaluation Tools List](https://www.w3.org/WAI/ER/tools/) - : Includes a list of web accessibility evaluation tools. -- [Learn Accessible Web Design](https://v2.scrimba.com/learn-accessible-web-design-c031?via=mdn) <sup>_MDN learning partner_</sup> - - : [Scrimba's](https://scrimba.com?via=mdn) _Learn Accessible Web Design_ course teaches you how to write accessible HTML by solving interactive coding challenges and fixing a real-world website. +- [Learn Accessible Web Design](https://scrimba.com/learn-accessible-web-design-c031?via=mdn) <sup>[_MDN learning partner_](/en-US/docs/MDN/Writing_guidelines/Learning_content#partner_links_and_embeds)</sup> + - : [Scrimba's](https://scrimba.com/?via=mdn) _Learn Accessible Web Design_ course teaches you how to write accessible HTML by solving interactive coding challenges and fixing a real-world website. {{NextMenu("Learn_web_development/Core/Accessibility/What_is_accessibility", "Learn_web_development/Core")}} diff --git a/files/en-us/learn_web_development/core/accessibility/mobile/index.md b/files/en-us/learn_web_development/core/accessibility/mobile/index.md index 7d200cad608a264..4195da6e5291401 100644 --- a/files/en-us/learn_web_development/core/accessibility/mobile/index.md +++ b/files/en-us/learn_web_development/core/accessibility/mobile/index.md @@ -2,10 +2,9 @@ title: Mobile accessibility slug: Learn_web_development/Core/Accessibility/Mobile page-type: learn-module-chapter +sidebar: learnsidebar --- -{{LearnSidebar}} - {{PreviousMenuNext("Learn_web_development/Core/Accessibility/Multimedia","Learn_web_development/Core/Accessibility/Accessibility_troubleshooting", "Learn_web_development/Core/Accessibility")}} With web access on mobile devices being so popular and renowned platforms such as iOS and Android having full-fledged accessibility tools, it is important to consider the accessibility of your web content on these platforms. This article looks at mobile-specific accessibility considerations. @@ -54,7 +53,7 @@ Let's look at the main two: TalkBack on Android and VoiceOver on iOS. The TalkBack screen reader is built into the Android operating system. -To turn it on, look up what phone model and Android version you have, and then look up where the TalkBack menu is. It tends to differ widely between Android versions and even between different phone models. Some phone manufacturers (e.g. Samsung) don't even have TalkBack in newer phones, and instead opted for their own screen reader. +To turn it on, look up what phone model and Android version you have, and then look up where the TalkBack menu is. It tends to differ widely between Android versions and even between different phone models. Some phone manufacturers (e.g., Samsung) don't even have TalkBack in newer phones, and instead opted for their own screen reader. When you've found the TalkBack menu, press the slider switch to turn TalkBack on. Follow any additional on-screen prompts that you are presented with. @@ -226,8 +225,8 @@ We've provided a simple example that shows how to use the mouse and touch events In particular, the most common problems that need to be addressed for mobile are: -- Suitability of layouts for mobile devices. A multi-column layout won't work as well on a narrow screen, for example, and the text size may need to be increased so it is legible. Such issues can be solved by creating a responsive layout using technologies such as [media queries](/en-US/docs/Web/CSS/CSS_media_queries), [viewport](/en-US/docs/Web/HTML/Viewport_meta_tag), and [flexbox](/en-US/docs/Learn_web_development/Core/CSS_layout/Flexbox). -- Conserving image sizes downloaded. In general, small-screen devices won't need images that are as large as their desktop counterparts, and they are more likely to be on slow network connections. Therefore, it is wise to serve smaller images to narrow screen devices as appropriate. You can handle this using [responsive image techniques](/en-US/docs/Web/HTML/Responsive_images). +- Suitability of layouts for mobile devices. A multi-column layout won't work as well on a narrow screen, for example, and the text size may need to be increased so it is legible. Such issues can be solved by creating a responsive layout using technologies such as [media queries](/en-US/docs/Web/CSS/CSS_media_queries), [viewport](/en-US/docs/Web/HTML/Guides/Viewport_meta_element), and [flexbox](/en-US/docs/Learn_web_development/Core/CSS_layout/Flexbox). +- Conserving image sizes downloaded. In general, small-screen devices won't need images that are as large as their desktop counterparts, and they are more likely to be on slow network connections. Therefore, it is wise to serve smaller images to narrow screen devices as appropriate. You can handle this using [responsive image techniques](/en-US/docs/Web/HTML/Guides/Responsive_images). - Thinking about high resolutions. Many mobile devices have high-resolution screens, and therefore need higher-resolution images so that the display can continue to look crisp and sharp. Again, you can serve images as appropriate using responsive image techniques. In addition, many image requirements can be fulfilled using the SVG vector images format, which is well-supported across browsers today. SVG has a small file size and will stay sharp regardless of whatever size is being displayed (see [Including vector graphics in HTML](/en-US/docs/Learn_web_development/Core/Structuring_content/Including_vector_graphics_in_HTML) for more details). > [!NOTE] @@ -239,7 +238,7 @@ There are other important issues to consider when making sites more accessible o #### Not disabling zoom -Using [viewport](/en-US/docs/Web/HTML/Viewport_meta_tag), it is possible to disable zoom. Always ensure resizing is enabled, and set the width to the device's width in the {{htmlelement("head")}}: +Using [viewport](/en-US/docs/Web/HTML/Guides/Viewport_meta_element), it is possible to disable zoom. Always ensure resizing is enabled, and set the width to the device's width in the {{htmlelement("head")}}: ```html <meta name="viewport" content="width=device-width; user-scalable=yes" /> @@ -266,7 +265,7 @@ It is also worth considering the use of HTML form input types such as the date o - Types `number`, `tel`, and `email` display suitable virtual keyboards for entering numbers/telephone numbers. - Types `time` and `date` display suitable pickers for selecting times and dates. -If you want to provide a different solution for desktops, you could always serve different markup to your mobile devices using feature detection. See [input types](https://diveinto.html5doctor.com/detect.html#input-types) for raw information on detecting different input types, and also check out our [feature detection article](/en-US/docs/Learn_web_development/Extensions/Testing/Feature_detection) for much more information. +If you want to provide a different solution for desktops, you could always serve different markup to your mobile devices using feature detection. Check out our [feature detection article](/en-US/docs/Learn_web_development/Extensions/Testing/Feature_detection) for more information. ## Summary diff --git a/files/en-us/learn_web_development/core/accessibility/multimedia/index.md b/files/en-us/learn_web_development/core/accessibility/multimedia/index.md index c1653e88009933e..e18f73a17ff558e 100644 --- a/files/en-us/learn_web_development/core/accessibility/multimedia/index.md +++ b/files/en-us/learn_web_development/core/accessibility/multimedia/index.md @@ -2,10 +2,9 @@ title: Accessible multimedia slug: Learn_web_development/Core/Accessibility/Multimedia page-type: learn-module-chapter +sidebar: learnsidebar --- -{{LearnSidebar}} - {{PreviousMenuNext("Learn_web_development/Core/Accessibility/WAI-ARIA_basics","Learn_web_development/Core/Accessibility/Mobile", "Learn_web_development/Core/Accessibility")}} Another category of content that can create accessibility problems is multimedia. Video, audio, and image content need to be given proper textual alternatives so that they can be understood by assistive technologies and their users. This article shows how. @@ -86,7 +85,7 @@ The controls attribute provides play/pause buttons, seek bar, etc. — the basic However, there are problems with these controls: -- They are not keyboard-accessible in most browsers, i.e. you can't tab between the controls inside the native player. Opera and Chrome provide this to some degree, but it still isn't ideal. +- They are not keyboard-accessible in most browsers, i.e., you can't tab between the controls inside the native player. Opera and Chrome provide this to some degree, but it still isn't ideal. - Different browsers give the native controls differing styling and functionality, and they aren't stylable, meaning that they can't be easily made to follow a site style guide. To remedy this, we can create our own custom controls. Let's look at how. @@ -307,7 +306,7 @@ This is the second. To get this displayed along with the HTML media playback, you need to: - Save it as a .vtt file in a sensible place. -- Link to the .vtt file with the {{htmlelement("track")}} element. `<track>` should be placed within `<audio>` or `<video>`, but after all `<source>` elements. Use the [`kind`](/en-US/docs/Web/HTML/Element/track#kind) attribute to specify whether the cues are subtitles, captions, or descriptions. Furthermore, use [`srclang`](/en-US/docs/Web/HTML/Element/track#srclang) to tell the browser what language you have written the subtitles in. +- Link to the .vtt file with the {{htmlelement("track")}} element. `<track>` should be placed within `<audio>` or `<video>`, but after all `<source>` elements. Use the [`kind`](/en-US/docs/Web/HTML/Reference/Elements/track#kind) attribute to specify whether the cues are subtitles, captions, or descriptions. Furthermore, use [`srclang`](/en-US/docs/Web/HTML/Reference/Elements/track#srclang) to tell the browser what language you have written the subtitles in. Here's an example: diff --git a/files/en-us/learn_web_development/core/accessibility/test_your_skills/css_and_javascript/index.md b/files/en-us/learn_web_development/core/accessibility/test_your_skills/css_and_javascript/index.md new file mode 100644 index 000000000000000..3a512326c041d49 --- /dev/null +++ b/files/en-us/learn_web_development/core/accessibility/test_your_skills/css_and_javascript/index.md @@ -0,0 +1,55 @@ +--- +title: "Test your skills: CSS and JavaScript accessibility" +short-title: CSS and JavaScript +slug: Learn_web_development/Core/Accessibility/Test_your_skills/CSS_and_JavaScript +page-type: learn-module-assessment +sidebar: learnsidebar +--- + +The aim of this skill test is to assess whether you've understood our [CSS and JavaScript accessibility best practices](/en-US/docs/Learn_web_development/Core/Accessibility/CSS_and_JavaScript) article. + +> [!NOTE] +> You can try solutions in the interactive editors on this page or in an online editor such as [CodePen](https://codepen.io/), [JSFiddle](https://jsfiddle.net/), or [Glitch](https://glitch.com/). +> +> If you get stuck, you can reach out to us in one of our [communication channels](/en-US/docs/MDN/Community/Communication_channels). + +## CSS accessibility 1 + +In the first task you are presented with a list of links. However, their accessibility is pretty bad — there is no way to really tell that they are links, or to tell which one the user is focussed on. + +We'd like you to assume that the existing ruleset with the `a` selector is supplied by some CMS, and that you can't change it — instead, you need to create new rules to make the links look and behave like links, and for the user to be able to tell where they are in the list. + +Try updating the live code below to recreate the finished example: + +{{EmbedGHLiveSample("learning-area/accessibility/tasks/html-css/css/css-a11y1.html", '100%', 700)}} + +> [!CALLOUT] +> +> [Download the starting point for this task](https://github.com/mdn/learning-area/blob/main/accessibility/tasks/html-css/css/css-a11y1-download.html) to work in your own editor or in an online editor. + +## CSS accessibility 2 + +In this next task you are presented with a simple bit of content — just headings and paragraphs. There are accessibility issues with the colors and sizing of the text; we'd like you to: + +1. Explain what the problems are, and what the guidelines are that state the acceptable values for color and sizing. +2. Select new values for the color and font-size that fix the problem. +3. Update the CSS with these new values to fix the problem. +4. Test the code to make sure the problem is now fixed. Explain what tools or methods you used to select the new values and test the code. + +Try updating the live code below to recreate the finished example: + +{{EmbedGHLiveSample("learning-area/accessibility/tasks/html-css/css/css-a11y2.html", '100%', 700)}} + +> [!CALLOUT] +> +> [Download the starting point for this task](https://github.com/mdn/learning-area/blob/main/accessibility/tasks/html-css/css/css-a11y2-download.html) to work in your own editor or in an online editor. + +## JavaScript accessibility 1 + +In our final task here, you have some JavaScripting to do. We have an app that presents a list of animal names. Clicking one of the animal names causes a further description of that animal to appear in a box below the list. + +But it is not very accessible — in its current state you can only operate it with the mouse. We'd like you to add to the HTML and JavaScript to make it keyboard accessible too. + +> [!CALLOUT] +> +> [Download the starting point for this task](https://github.com/mdn/learning-area/blob/main/accessibility/tasks/js/js/js1-download.html) to work in your own editor or in an online editor. diff --git a/files/en-us/learn_web_development/core/accessibility/test_your_skills/html/index.md b/files/en-us/learn_web_development/core/accessibility/test_your_skills/html/index.md new file mode 100644 index 000000000000000..2e027a73995bcc3 --- /dev/null +++ b/files/en-us/learn_web_development/core/accessibility/test_your_skills/html/index.md @@ -0,0 +1,75 @@ +--- +title: "Test your skills: HTML accessibility" +short-title: HTML +slug: Learn_web_development/Core/Accessibility/Test_your_skills/HTML +page-type: learn-module-assessment +sidebar: learnsidebar +--- + +The aim of this skill test is to assess whether you've understood our [HTML: A good basis for accessibility](/en-US/docs/Learn_web_development/Core/Accessibility/HTML) article. + +> [!NOTE] +> You can try solutions in the interactive editors on this page or in an online editor such as [CodePen](https://codepen.io/), [JSFiddle](https://jsfiddle.net/), or [Glitch](https://glitch.com/). +> +> If you get stuck, you can reach out to us in one of our [communication channels](/en-US/docs/MDN/Community/Communication_channels). + +## HTML accessibility 1 + +In this task we will test your understanding of text semantics, and why they are good for accessibility. The given text is an information panel with action buttons, but the HTML is really bad. + +We want you to update it use appropriate semantic HTML. You don't need to worry too much about recreating the _exact_ same look and text sizing, as long as the semantics are good. + +Try updating the live code below to recreate the finished example: + +{{EmbedGHLiveSample("learning-area/accessibility/tasks/html-css/html/html-a11y1.html", '100%', 1100)}} + +> [!CALLOUT] +> +> [Download the starting point for this task](https://github.com/mdn/learning-area/blob/main/accessibility/tasks/html-css/html/html-a11y1-download.html) to work in your own editor or in an online editor. + +## HTML accessibility 2 + +In the second task, you have a form containing three input fields. You need to: + +- Semantically associate the input with their labels. +- Assume that these inputs will be part of a larger form, and wrap them in an element that associates them all together as a single related group. +- Give the group a description/title that summarizes all of the information as personal data. + +Try updating the live code below to recreate the finished example: + +{{EmbedGHLiveSample("learning-area/accessibility/tasks/html-css/html/html-a11y2.html", '100%', 700)}} + +> [!CALLOUT] +> +> [Download the starting point for this task](https://github.com/mdn/learning-area/blob/main/accessibility/tasks/html-css/html/html-a11y2-download.html) to work in your own editor or in an online editor. + +## HTML accessibility 3 + +In this task you are required to turn all the information links in the paragraph into good, accessible links. + +- The first two links just go to regular web pages. +- The third link goes to a PDF, and it's large — 8MB. +- The fourth link goes to a Word document, so the user will need some kind of application installed that can handle that. + +Try updating the live code below to recreate the finished example: + +{{EmbedGHLiveSample("learning-area/accessibility/tasks/html-css/html/html-a11y3.html", '100%', 700)}} + +> [!CALLOUT] +> +> [Download the starting point for this task](https://github.com/mdn/learning-area/blob/main/accessibility/tasks/html-css/html/html-a11y3-download.html) to work in your own editor or in an online editor. + +## HTML accessibility 4 + +In our final HTML accessibility task, you are given an image gallery, which has some accessibility problems. Can you fix them? + +- The header image has an accessibility issue, and so do the gallery images. +- You could take the header image further and implement it using CSS for arguably better accessibility. Why is this better, and what would a solution look like? + +Try updating the live code below to recreate the finished example: + +{{EmbedGHLiveSample("learning-area/accessibility/tasks/html-css/html/html-a11y4.html", '100%', 1100)}} + +> [!CALLOUT] +> +> [Download the starting point for this task](https://github.com/mdn/learning-area/blob/main/accessibility/tasks/html-css/html/html-a11y4-download.html) to work in your own editor or in an online editor. diff --git a/files/en-us/learn_web_development/core/accessibility/test_your_skills/index.md b/files/en-us/learn_web_development/core/accessibility/test_your_skills/index.md new file mode 100644 index 000000000000000..74bd42f9c9c9cff --- /dev/null +++ b/files/en-us/learn_web_development/core/accessibility/test_your_skills/index.md @@ -0,0 +1,17 @@ +--- +title: "Test your skills: Accessibility" +short-title: Test your skills +slug: Learn_web_development/Core/Accessibility/Test_your_skills +page-type: learn-module-assessment +sidebar: learnsidebar +--- + +This page lists Accessibility tests you can try so you can verify if you've understood the content in this module. + +## Test your Accessibility skills by topic + +{{SubpagesWithSummaries}} + +## See also + +- [Accessibility on the web](/en-US/docs/Learn_web_development/Core/Accessibility) diff --git a/files/en-us/learn_web_development/core/accessibility/test_your_skills/wai-aria/index.md b/files/en-us/learn_web_development/core/accessibility/test_your_skills/wai-aria/index.md new file mode 100644 index 000000000000000..9b7506f5e8d2cb3 --- /dev/null +++ b/files/en-us/learn_web_development/core/accessibility/test_your_skills/wai-aria/index.md @@ -0,0 +1,52 @@ +--- +title: "Test your skills: WAI-ARIA" +short-title: WAI-ARIA +slug: Learn_web_development/Core/Accessibility/Test_your_skills/WAI-ARIA +page-type: learn-module-assessment +sidebar: learnsidebar +--- + +The aim of this skill test is to assess whether you've understood our [WAI-ARIA basics](/en-US/docs/Learn_web_development/Core/Accessibility/WAI-ARIA_basics) article. + +> [!NOTE] +> You can try solutions in the interactive editors on this page or in an online editor such as [CodePen](https://codepen.io/), [JSFiddle](https://jsfiddle.net/), or [Glitch](https://glitch.com/). +> +> If you get stuck, you can reach out to us in one of our [communication channels](/en-US/docs/MDN/Community/Communication_channels). + +## WAI-ARIA 1 + +In our first ARIA task, we present you with a section of non-semantic markup, which is obviously meant to be a list. Assuming you are not able to change the elements used, how can you allow screen reader users to recognize this as a list? + +Try updating the live code below to recreate the finished example: + +{{EmbedGHLiveSample("learning-area/accessibility/tasks/html-css/aria/aria1.html", '100%', 700)}} + +> [!CALLOUT] +> +> [Download the starting point for this task](https://github.com/mdn/learning-area/blob/main/accessibility/tasks/html-css/aria/aria1-download.html) to work in your own editor or in an online editor. + +## WAI-ARIA 2 + +In our second WAI-ARIA task, we present a simple search form, and we want you to add in a couple of WAI-ARIA features to improve its accessibility: + +1. How can you allow the search form to be called out as a separate landmark on the page by screen readers, to make it easily findable? +2. How can you give the search input a suitable label, without explicitly adding a visible text label to the DOM? + +Try updating the live code below to recreate the finished example: + +{{EmbedGHLiveSample("learning-area/accessibility/tasks/html-css/aria/aria2.html", '100%', 700)}} + +> [!CALLOUT] +> +> [Download the starting point for this task](https://github.com/mdn/learning-area/blob/main/accessibility/tasks/html-css/aria/aria2-download.html) to work in your own editor or in an online editor. + +## WAI-ARIA 3 + +For this final WAI-ARIA task, we return to an example we previously saw in the [CSS and JavaScript skill test](/en-US/docs/Learn_web_development/Core/Accessibility/Test_your_skills/CSS_and_JavaScript). +As before, we have an app that presents a list of animal names. Clicking one of the animal names causes a further description of that animal to appear in a box below the list. Here, we are starting with a mouse- and keyboard-accessible version. + +The problem we have now is that when the DOM changes to show a new description, screen readers cannot see what has changed. Can you update it so that description changes are announced by the screen reader? + +> [!CALLOUT] +> +> [Download the starting point for this task](https://github.com/mdn/learning-area/blob/main/accessibility/tasks/js/aria/aria-js1-download.html) to work in your own editor or in an online editor. diff --git a/files/en-us/learn_web_development/core/accessibility/test_your_skills_colon__html_accessibility/index.md b/files/en-us/learn_web_development/core/accessibility/test_your_skills_colon__html_accessibility/index.md deleted file mode 100644 index 030531d4ad418c7..000000000000000 --- a/files/en-us/learn_web_development/core/accessibility/test_your_skills_colon__html_accessibility/index.md +++ /dev/null @@ -1,75 +0,0 @@ ---- -title: "Test your skills: HTML accessibility" -slug: Learn_web_development/Core/Accessibility/Test_your_skills:_HTML_accessibility -page-type: learn-module-assessment ---- - -{{learnsidebar}} - -The aim of this skill test is to assess whether you've understood our [HTML: A good basis for accessibility](/en-US/docs/Learn_web_development/Core/Accessibility/HTML) article. - -> [!NOTE] -> You can try solutions in the interactive editors on this page or in an online editor such as [CodePen](https://codepen.io/), [JSFiddle](https://jsfiddle.net/), or [Glitch](https://glitch.com/). -> -> If you get stuck, you can reach out to us in one of our [communication channels](/en-US/docs/MDN/Community/Communication_channels). - -## HTML accessibility 1 - -In this task we will test your understanding of text semantics, and why they are good for accessibility. The given text is an information panel with action buttons, but the HTML is really bad. - -We want you to update it use appropriate semantic HTML. You don't need to worry too much about recreating the _exact_ same look and text sizing, as long as the semantics are good. - -Try updating the live code below to recreate the finished example: - -{{EmbedGHLiveSample("learning-area/accessibility/tasks/html-css/html/html-a11y1.html", '100%', 1100)}} - -> [!CALLOUT] -> -> [Download the starting point for this task](https://github.com/mdn/learning-area/blob/main/accessibility/tasks/html-css/html/html-a11y1-download.html) to work in your own editor or in an online editor. - -## HTML accessibility 2 - -In the second task, you have a form containing three input fields. You need to: - -- Semantically associate the input with their labels. -- Assume that these inputs will be part of a larger form, and wrap them in an element that associates them all together as a single related group. -- Give the group a description/title that summarizes all of the information as personal data. - -Try updating the live code below to recreate the finished example: - -{{EmbedGHLiveSample("learning-area/accessibility/tasks/html-css/html/html-a11y2.html", '100%', 700)}} - -> [!CALLOUT] -> -> [Download the starting point for this task](https://github.com/mdn/learning-area/blob/main/accessibility/tasks/html-css/html/html-a11y2-download.html) to work in your own editor or in an online editor. - -## HTML accessibility 3 - -In this task you are required to turn all the information links in the paragraph into good, accessible links. - -- The first two links just go to regular web pages. -- The third link goes to a PDF, and it's large — 8MB. -- The fourth link goes to a Word document, so the user will need some kind of application installed that can handle that. - -Try updating the live code below to recreate the finished example: - -{{EmbedGHLiveSample("learning-area/accessibility/tasks/html-css/html/html-a11y3.html", '100%', 700)}} - -> [!CALLOUT] -> -> [Download the starting point for this task](https://github.com/mdn/learning-area/blob/main/accessibility/tasks/html-css/html/html-a11y3-download.html) to work in your own editor or in an online editor. - -## HTML accessibility 4 - -In our final HTML accessibility task, you are given an image gallery, which has some accessibility problems. Can you fix them? - -- The header image has an accessibility issue, and so do the gallery images. -- You could take the header image further and implement it using CSS for arguably better accessibility. Why is this better, and what would a solution look like? - -Try updating the live code below to recreate the finished example: - -{{EmbedGHLiveSample("learning-area/accessibility/tasks/html-css/html/html-a11y4.html", '100%', 1100)}} - -> [!CALLOUT] -> -> [Download the starting point for this task](https://github.com/mdn/learning-area/blob/main/accessibility/tasks/html-css/html/html-a11y4-download.html) to work in your own editor or in an online editor. diff --git a/files/en-us/learn_web_development/core/accessibility/tooling/index.md b/files/en-us/learn_web_development/core/accessibility/tooling/index.md index feddfbf6b280013..19a162366136939 100644 --- a/files/en-us/learn_web_development/core/accessibility/tooling/index.md +++ b/files/en-us/learn_web_development/core/accessibility/tooling/index.md @@ -1,17 +1,14 @@ --- title: Accessibility tooling and assistive technology +short-title: Accessibility tools slug: Learn_web_development/Core/Accessibility/Tooling page-type: learn-module-chapter +sidebar: learnsidebar --- -{{LearnSidebar}} - {{PreviousMenuNext("Learn_web_development/Core/Accessibility/What_is_Accessibility","Learn_web_development/Core/Accessibility/HTML", "Learn_web_development/Core/Accessibility")}} -> [!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. - -Next we turn our attention to accessibility tooling, providing information on the kinds of tools you can use to help solve accessibility issues, and the assistive technologies used by people with disabilities as they browse the web. You'll be using these tools throughout subsequent articles. +Next, we turn our attention to accessibility tooling, providing information on the kinds of tools you can use to help solve accessibility issues, and helping you understand the **assistive technologies** used by people with disabilities to help them browse the web. You'll be using the tools described here throughout subsequent articles. <table> <tbody> @@ -25,7 +22,7 @@ Next we turn our attention to accessibility tooling, providing information on th <ul> <li>Familiarity with the kind of tooling you can use to help solve accessibility issues, for example auditing tools.</li> <li>Setting up screen readers and using them to test websites on desktop and mobile.</li> - <li>Other assistive technology such as large text or braille keyboards, alternative pointing devices, and screen magnifiers.</li> + <li>Familiarity with other types of assistive technology such as large text or braille keyboards, alternative pointing devices, and screen magnifiers.</li> <li>The importance of user testing alongside automated testing.</li> </ul> </td> @@ -35,47 +32,44 @@ Next we turn our attention to accessibility tooling, providing information on th ## Accessibility tools -Let's have a look at the tools can make use of when implementing accessible websites and fixing accessibility issues. +Let's have a look at the tools and techniques you can use for testing website accessibility and fixing the issues you uncover. ### Testing source order -Your content should make logical sense in its source order — you can always place it where you want using CSS later on, but you should get the source order right to start with. +Your content should make logical sense in its source order — you can always display it differently with CSS later on, but you should get the underlying structure correct to begin with. This is because assistive technologies read website content based on the order of the source, and disabled people often modify or turn off parts of the CSS to make content more legible (common examples are increasing font size and applying high contrast color schemes). -As a test, you can turn off a site's CSS and see how understandable it is without it. You could do this manually by just removing the CSS from your code, but the easiest way is to use browser features, for example: +To test source order, you can turn off a site's CSS and see how understandable it is without it. You could do this manually by just removing the CSS from your code, but the easiest way is to use browser features, for example: - Firefox: Select _View > Page Style > No Style_ from the main menu. -- Safari: Select _Develop > Disable Styles_ from the main menu (to enable the _Develop_ menu, choose _Safari > Preferences > Advanced > Show Develop menu in menu bar_). -- Chrome: Install the Web Developer Toolbar extension, then restart the browser. Click the gear icon that will appear, then select _CSS > Disable All Styles_. -- Edge: Select _View > Style > No Style_ from the main menu. +- Safari: [Open the browser developer tools](/en-US/docs/Learn_web_development/Howto/Tools_and_setup/What_are_browser_developer_tools#how_to_open_the_devtools_in_your_browser), click the _Device Settings_ button near the top-left of the developer tools panel (looks like a computer monitor), then check the "Disable CSS" checkbox in the panel that appears. +- Chrome/Edge: Install the [Web Developer Toolbar](https://chromewebstore.google.com/detail/web-developer/bfbameneiokkgbdmiekhjnmfkcnldhhm) extension, then restart the browser. Click the "Web Developer" gear icon that should now be available in your extensions menu, then select _CSS > Disable All Styles_. ### Color contrast checkers -When choosing a color scheme for your website, you should make sure that the text (foreground) color contrasts well with the background color. Your design might look cool, but it is no good if people with visual impairments like color blindness can't read your content. Use a tool like WebAIM's [Color Contrast Checker](https://webaim.org/resources/contrastchecker/) to check whether your scheme is contrasting enough. +When choosing a color scheme for your website, you should make sure that the text (foreground) color contrasts well with the background color. Your design might look cool, but it is no good if people can't read your content. Use a tool like WebAIM's [Color Contrast Checker](https://webaim.org/resources/contrastchecker/) to check whether your scheme is contrasting enough. -Another tip is to not rely on color alone for signposts/information, as this will be no good for those who can't see the color. Instead of marking required form fields in red, for example, mark them with an asterisk and in red. +Another tip is to avoid using only color for signposts or highlighting important information, as this might be missed by people with visual impairments like color blindness. Instead of marking required form fields in red, for example, mark them with an asterisk and in red. > [!NOTE] > A high contrast ratio will also allow anyone using a smartphone or tablet with a glossy screen to better read pages when in a bright environment, such as sunlight. ### Auditing tools -There are a number of auditing tools available that you can feed your web pages into. They will look over them and return a list of accessibility issues present on the page. Let's look at an example, using [Wave](https://wave.webaim.org/), an online accessibility testing tool that accepts a web address and returns an annotated view of that page with accessibility problems highlighted. +There are several auditing tools available that you can feed your web pages into. They will look over them and return a list of accessibility issues present on the page. Let's look at [Wave](https://wave.webaim.org/) as an example, an online accessibility testing tool that accepts a web address and returns an annotated view of that page with accessibility problems highlighted. 1. Go to the [Wave homepage](https://wave.webaim.org/). -2. Enter the URL of our [bad-semantics.html](https://mdn.github.io/learning-area/accessibility/html/bad-semantics.html) example into the text input box near the top of the page. Then press enter or click/tap the arrow at the far right edge of the input box. -3. The site should respond with a description of the accessibility problems. Click the icons displayed to see more information about each of the issues identified by Wave's evaluation. +2. Enter the URL of our [bad-form.html](https://mdn.github.io/learning-area/accessibility/html/bad-form.html) example into the text input box near the top of the page. Then press enter or click/tap the arrow at the far right edge of the input box. +3. The site should highlight the accessibility problems present. Click the displayed icons to see more information about each of the issues identified by Wave's evaluation. Other auditing tools that are worth checking out: - [Firefox Accessibility Inspector](https://firefox-source-docs.mozilla.org/devtools-user/accessibility_inspector/index.html) - [ANDI bookmarklet](https://www.ssa.gov/accessibility/andi/help/install.html) -- [Google Lighthouse accessibility audits](https://developer.chrome.com/docs/lighthouse/accessibility/) +- [Google Lighthouse accessibility audits](https://developer.chrome.com/docs/lighthouse/accessibility/scoring) > [!NOTE] > Such tools aren't good enough to solve all your accessibility problems on their own. You'll need a combination of these, knowledge and experience, user testing, etc. to get a full picture. -### Automation tools - [Deque's aXe tool](https://www.deque.com/axe/) goes a bit further than the auditing tools we mentioned above. Like the others, it checks pages and returns accessibility errors. Its most immediately useful form is probably the browser extensions: - [aXe for Chrome](https://chromewebstore.google.com/detail/axe-devtools-web-accessib/lhdoppojpmngadmnindnejefpokejbdd) @@ -89,24 +83,34 @@ aXe is also installable using `npm`, and can be integrated with task runners lik ## Screen readers -It is definitely worth testing with a screen reader to get used to how severely visually impaired people use the Web. There are a number of screen readers available: +One of the most common types of assistive technology (AT) that disabled people use — and one of the most common ones you'll use to test the accessibility of your webpages — is **screen readers**. These are pieces of software that read out webpage content or content from other apps installed on someone's operating system. Screen readers enable people to use computers without having to see any visual content. + +Web browsers expose information about the page's content for screen readers (and other AT) to communicate to the user through a representation called the [accessibility tree](/en-US/docs/Glossary/Accessibility_tree). This provides semantic information such as names and descriptions of elements, what their purpose or role is (is it a button, or an input field?), and whether they are in a particular state (for example, is a dialog box open or closed?). + +This information might be trivial in the case of a paragraph of text, which sounds pretty much how it is written, but it can get complicated when it comes to user interface features such as a drop-down menu or a video player. This is why it's very important to use semantic HTML correctly, which you'll look at in detail in the next article in this module. If you mark up content using the wrong element, it can confuse screen reader users. + +Make sure you have a screen reader or two installed on your development machine, and try using your favorite websites via a screen reader, as discussed below. Understanding how visually impaired people use the web is key to designing products that work better for everyone. + +### What screen readers are available? + +There are several screen readers available: - Some are paid-for commercial products, like [JAWS](https://www.freedomscientific.com/Products/software/JAWS/) (Windows). - Some are free products, like [NVDA](https://www.nvaccess.org/) (Windows), [ChromeVox](https://support.google.com/chromebook/answer/7031755) (Chrome, Windows, and macOS), and [Orca](https://wiki.gnome.org/Projects/Orca) (Linux). -- Some are built into the operating system, like [VoiceOver](https://www.apple.com/accessibility/vision/) (macOS and iOS), [ChromeVox](https://support.google.com/chromebook/answer/7031755) (on Chromebooks), and [TalkBack](https://play.google.com/store/apps/details?id=com.google.android.marvin.talkback) (Android). +- Some are built into the operating system, like [VoiceOver](https://www.apple.com/accessibility/features/?vision) (macOS and iOS), [ChromeVox](https://support.google.com/chromebook/answer/7031755) (on Chromebooks), and [TalkBack](https://play.google.com/store/apps/details?id=com.google.android.marvin.talkback) (Android). -Generally, screen readers are separate apps that run on the host operating system and can read not only web pages, but text in other apps as well. This is not always the case (ChromeVox is a browser extension), but usually, screen readers tend to act in slightly different ways and have different controls, so you'll have to consult the documentation for your chosen screen reader to get all the details — saying that, they all work in basically the same sort of way. +Generally, screen readers are separate apps that run on the host operating system and can read web pages and content in other apps as well (this is not always the case; ChromeVox for example is a browser extension). Screen readers tend to have some differences in exact behavior and controls, so you'll have to consult the documentation for your chosen screen reader to get all the details. Saying that, they all work in basically the same sort of way. -Let's go through some tests with a couple of different screen readers to give you a general idea of how they work and how to test with them. +In the next couple of sections, we'll go through some tests with a couple of different screen readers to give you a general idea of how they work and how to test with them. > [!NOTE] -> WebAIM's [Designing for Screen Reader Compatibility](https://webaim.org/techniques/screenreader/) provides some useful information about screen reader usage and what works best for screen readers. Also see [Screen Reader User Survey #9 Results](https://webaim.org/projects/screenreadersurvey9/#used) for some interesting screen reader usage statistics. +> WebAIM's [Designing for Screen Reader Compatibility](https://webaim.org/techniques/screenreader/) provides some useful information about screen reader usage and what works best for screen readers. Also see [Screen Reader User Survey #10 Results](https://webaim.org/projects/screenreadersurvey10/#used) for some interesting screen reader usage statistics. -### VoiceOver +#### VoiceOver -VoiceOver (VO) comes free with your Mac/iPhone/iPad, so it's useful for testing on desktop/mobile if you use Apple products. We'll be testing it on macOS on a MacBook Pro. +VoiceOver (VO) comes free with Apple mac/iPhone/iPad, so it's useful for testing on desktop/mobile if you use Apple products. We tested it on macOS on a MacBook Pro. -To turn it on, press Cmd + F5. If you've not used VO before, you will be given a welcome screen where you can choose to start VO or not, and run through a rather useful tutorial to learn how to use it. To turn it off again, press Cmd + F5 again. +To turn it on, press <kbd>Cmd</kbd> + <kbd>F5</kbd>. If you've not used VO before, you will be given a welcome screen where you can choose to start VO or not, and run through a rather useful tutorial to learn how to use it. To turn it off, press <kbd>Cmd</kbd> + <kbd>F5</kbd> again. > [!NOTE] > You should go through the tutorial at least once — it is a really useful way to learn VO. @@ -115,13 +119,13 @@ When VO is on, the display will look mostly the same, but you'll see a black box ![A sample screenshot demonstrating accessibility testing using VoiceOver on the MDN homepage. The bottom left of the image is a highlight of the information selected on the webpage.](voiceover.png) -To use VO, you will make a lot of use of the "VO modifier" — this is a key or key combination that you need to press in addition to the actual VO keyboard shortcuts to get them to work. Using a modifier like this is common with screen readers, to enable them to keep their commands from clashing with other commands. In the case of VO, the modifier can either be CapsLock, or Ctrl + Option. +To use VO, you will make a lot of use of the "VO modifier" — this is a key or key combination that you need to press in addition to the actual VO keyboard shortcuts to get them to work. Using a modifier like this is common with screen readers, to enable them to keep their commands from clashing with other commands. In the case of VO, the modifier can either be <kbd>CapsLock</kbd>, or <kbd>Ctrl</kbd> + <kbd>Option</kbd>. VO has many keyboard commands, and we won't list them all here. The basic ones you'll need for web page testing are in the following table. In the keyboard shortcuts, "VO" means "the VoiceOver modifier". <table class="standard-table no-markdown"> <caption> - Most common VoiceOver keyboard shortcuts + Common VoiceOver keyboard shortcuts </caption> <thead> <tr> @@ -142,33 +146,33 @@ VO has many keyboard commands, and we won't list them all here. The basic ones y </td> </tr> <tr> - <td>VO + Shift + down cursor</td> + <td>VO + <kbd>Shift</kbd> + down cursor</td> <td> - Move into a group of items (such as an HTML table, or a form, etc.) Once - inside a group you can move around and select items inside that group + Move into a group of items such as an HTML table or form. Once + inside a group, you can move around and select items inside that group using the above commands as normal. </td> </tr> <tr> - <td>VO + Shift + up cursor</td> + <td>VO + <kbd>Shift</kbd> + up cursor</td> <td>Move out of a group.</td> </tr> <tr> - <td>VO + C</td> + <td>VO + <kbd>C</kbd></td> <td>(when inside a table) Read the header of the current column.</td> </tr> <tr> - <td>VO + R</td> + <td>VO + <kbd>R</kbd></td> <td>(when inside a table) Read the header of the current row.</td> </tr> <tr> - <td>VO + C + C (two Cs in succession)</td> + <td>VO + <kbd>C</kbd> + <kbd>C</kbd> (two Cs in succession)</td> <td> (when inside a table) Read the entire current column, including header. </td> </tr> <tr> - <td>VO + R + R (two Rs in succession)</td> + <td>VO + <kbd>R</kbd> + <kbd>R</kbd> (two Rs in succession)</td> <td> (when inside a table) Read the entire current row, including the headers that correspond to each cell. @@ -177,21 +181,21 @@ VO has many keyboard commands, and we won't list them all here. The basic ones y <tr> <td>VO + left cursor, VO + right cursor</td> <td> - (when inside some horizontal options, such as a date or time picker) + (when inside some horizontal options, such as a date picker) Move between options. </td> </tr> <tr> <td>VO + up cursor, VO + down cursor</td> <td> - (when inside some horizontal options, such as a date or time picker) + (when inside some horizontal options, such as a date picker) Change the current option. </td> </tr> <tr> - <td>VO + U</td> + <td>VO + <kbd>U</kbd></td> <td> - Use the Rotor, which displays lists of headings, links, form controls, + Open the Rotor, which displays lists of headings, links, form controls, etc. for easy navigation. </td> </tr> @@ -209,37 +213,36 @@ VO has many keyboard commands, and we won't list them all here. The basic ones y </td> </tr> <tr> - <td>Esc</td> + <td><kbd>Esc</kbd></td> <td>(when inside Rotor) Exit Rotor.</td> </tr> <tr> - <td>Ctrl</td> + <td><kbd>Ctrl</kbd></td> <td>(when VO is speaking) Pause/Resume speech.</td> </tr> <tr> - <td>VO + Z</td> + <td>VO + <kbd>Z</kbd></td> <td>Restart the last bit of speech.</td> </tr> <tr> - <td>VO + D</td> - <td>Go into the Mac's Dock, so you can select apps to run inside it.</td> + <td>VO + <kbd>D</kbd></td> + <td>Go into the mac's Dock, so you can select apps to run inside it.</td> </tr> </tbody> </table> This seems like a lot of commands, but it isn't so bad when you get used to it, and VO regularly gives you reminders of what commands to use in certain places. Have a play with VO now; you can then go on to play with some of our examples in the [Screen reader testing](#screen_reader_testing) section. -### NVDA +#### NVDA NVDA is Windows-only, and you'll need to install it. -1. Download it from [nvaccess.org](https://www.nvaccess.org/). You can choose whether to make a donation or download it for free; you'll also need to give them your email address before you can download it. -2. Once downloaded, install it — you double-click the installer, accept the license and follow the prompts. -3. To start NVDA, double-click on the program file/shortcut, or use the keyboard shortcut Ctrl + Alt + N. You'll see the NVDA welcome dialog when you start it. Here you can choose from a couple of options, then press the _OK_ button to get going. +1. Download NVDA from [nvaccess.org](https://www.nvaccess.org/), then install it. You can choose whether to make a donation or download it for free; you'll also need to give them your email address before you can download it. +2. To start NVDA once installed, double-click on the program file/shortcut, or use the keyboard shortcut <kbd>Ctrl</kbd> + <kbd>Alt</kbd> + <kbd>N</kbd>. You'll see the NVDA welcome dialog when you start it. Here you can choose from a couple of options, then press the _OK_ button to get going. NVDA will now be active on your computer. -To use NVDA, you will make a lot of use of the "NVDA modifier" — this is a key that you need to press in addition to the actual NVDA keyboard shortcuts to get them to work. Using a modifier like this is common with screen readers, to enable them to keep their commands from clashing with other commands. In the case of NVDA, the modifier can either be Insert (the default), or CapsLock (can be chosen by checking the first checkbox in the NVDA welcome dialog before pressing _OK_). +To use NVDA, you will make a lot of use of the "NVDA modifier" — the key that you need to press in addition to the actual NVDA keyboard shortcuts to get them to work. The NVDA modifier can either be <kbd>Insert</kbd> (the default), or <kbd>CapsLock</kbd> (can be chosen by checking the first checkbox in the NVDA welcome dialog before pressing _OK_). > [!NOTE] > NVDA is more subtle than VoiceOver in terms of how it highlights where it is and what it is doing. When you are scrolling through headings, lists, etc., items you are selected on will generally be highlighted with a subtle outline, but this is not always the case for all things. If you get completely lost, you can press Ctrl + F5 to refresh the current page and begin from the top again. @@ -258,7 +261,7 @@ NVDA has many keyboard commands, and we won't list them all here. The basic ones </thead> <tbody> <tr> - <td>NVDA + Q</td> + <td>NVDA + <kbd>Q</kbd></td> <td>Turn NVDA off again after you've started it.</td> </tr> <tr> @@ -270,82 +273,82 @@ NVDA has many keyboard commands, and we won't list them all here. The basic ones <td>Start reading at the current position.</td> </tr> <tr> - <td>Up cursor and down cursor, or Shift + Tab and Tab</td> - <td>Move to previous/next item on page and read it.</td> + <td>Up cursor and down cursor, or <kbd>Shift</kbd> + <kbd>Tab</kbd> and <kbd>Tab</kbd></td> + <td>Move to the previous/next item on page and read it.</td> </tr> <tr> <td>Left cursor and right cursor</td> - <td>Move to previous/next character in current item and read it.</td> + <td>Move to the previous/next character in current item and read it.</td> </tr> <tr> - <td>Shift + H and H</td> - <td>Move to previous/next heading and read it.</td> + <td><kbd>Shift</kbd> + <kbd>H</kbd> and <kbd>H</kbd></td> + <td>Move to the previous/next heading and read it.</td> </tr> <tr> - <td>Shift + K and K</td> - <td>Move to previous/next link and read it.</td> + <td><kbd>Shift</kbd> + <kbd>K</kbd> and <kbd>K</kbd></td> + <td>Move to the previous/next link and read it.</td> </tr> <tr> - <td>Shift + D and D</td> + <td><kbd>Shift</kbd> + <kbd>D</kbd> and <kbd>D</kbd></td> <td> - Move to previous/next document landmark (e.g. <code>&#x3C;nav></code>) + Move to the previous/next document landmark (e.g., <code>&#x3C;nav></code>) and read it. </td> </tr> <tr> - <td>Shift + 1–6 and 1–6</td> - <td>Move to previous/next heading (level 1–6) and read it.</td> + <td><kbd>Shift</kbd> + <kbd>1</kbd>–<kbd>6</kbd> and <kbd>1</kbd>–<kbd>6</kbd></td> + <td>Move to the previous/next heading (level 1–6) and read it.</td> </tr> <tr> - <td>Shift + F and F</td> - <td>Move to previous/next form input and focus on it.</td> + <td><kbd>Shift</kbd> + <kbd>F</kbd> and <kbd>F</kbd></td> + <td>Move to the previous/next form input and focus on it.</td> </tr> <tr> - <td>Shift + T and T</td> - <td>Move to previous/next data table and focus on it.</td> + <td><kbd>Shift</kbd> + <kbd>T</kbd> and <kbd>T</kbd></td> + <td>Move to the previous/next data table and focus on it.</td> </tr> <tr> - <td>Shift + B and B</td> - <td>Move to previous/next button and read its label.</td> + <td><kbd>Shift</kbd> + <kbd>B</kbd> and <kbd>B</kbd></td> + <td>Move to the previous/next button and read its label.</td> </tr> <tr> - <td>Shift + L and L</td> - <td>Move to previous/next list and read its first list item.</td> + <td><kbd>Shift</kbd> + <kbd>L</kbd> and <kbd>L</kbd></td> + <td>Move to the previous/next list and read its first list item.</td> </tr> <tr> - <td>Shift + I and I</td> - <td>Move to previous/next list item and read it.</td> + <td><kbd>Shift</kbd> + <kbd>I</kbd> and <kbd>I</kbd></td> + <td>Move to the previous/next list item and read it.</td> </tr> <tr> - <td>Enter/Return</td> + <td><kbd>Enter</kbd>/<kbd>Return</kbd></td> <td> (when link/button or other activatable item is selected) Activate item. </td> </tr> <tr> - <td>NVDA + Space</td> + <td>NVDA + <kbd>Spacebar</kbd></td> <td> (when form is selected) Enter form so individual items can be selected, or leave form if you are already in it. </td> </tr> <tr> - <td>Shift Tab and Tab</td> + <td><kbd>Shift</kbd> + <kbd>Tab</kbd> and <kbd>Tab</kbd></td> <td>(when inside form) Move between form inputs.</td> </tr> <tr> <td>Up cursor and down cursor</td> <td> - (when inside form) Change form input values (in the case of things like + (when inside form) Change form input values (in the case of controls like select boxes). </td> </tr> <tr> - <td>Spacebar</td> + <td><kbd>Spacebar</kbd></td> <td>(when inside form) Select chosen value.</td> </tr> <tr> - <td>Ctrl + Alt + cursor keys</td> + <td><kbd>Ctrl</kbd> + <kbd>Alt</kbd> + cursor keys</td> <td>(when a table is selected) Move between table cells.</td> </tr> </tbody> @@ -356,24 +359,68 @@ NVDA has many keyboard commands, and we won't list them all here. The basic ones Now you've gotten used to using a screen reader, we'd like you to use it to do some quick accessibility tests, to get an idea of how screen readers deal with good and bad webpage features: - Look at [good-semantics.html](https://mdn.github.io/learning-area/accessibility/html/good-semantics.html), and note how the headers are found by the screen reader and available to use for navigation. Now look at [bad-semantics.html](https://mdn.github.io/learning-area/accessibility/html/bad-semantics.html), and note how the screen reader gets none of this information. Imagine how annoying this would be when trying to navigate a really long page of text. -- Look at [good-links.html](https://mdn.github.io/learning-area/accessibility/html/good-links.html), and note how they make sense when viewed out of context. This is not the case with [bad-links.html](https://mdn.github.io/learning-area/accessibility/html/bad-links.html) — they are all just "click here". -- Look at [good-form.html](https://mdn.github.io/learning-area/accessibility/html/good-form.html), and note how the form inputs are described using their labels because we've used `<label>` elements properly. In [bad-form.html](https://mdn.github.io/learning-area/accessibility/html/bad-form.html), they get an unhelpful label along the lines of "blank". -- Look at our [punk-bands-complete.html](https://mdn.github.io/learning-area/css/styling-boxes/styling-tables/punk-bands-complete.html) example, and see how the screen reader is able to associate columns and rows of content and read them out all together because we've defined headers properly. In [bad-table.html](https://mdn.github.io/learning-area/accessibility/html/bad-table.html), none of the cells can be associated at all. Note that NVDA seems to behave slightly strangely when you've only got a single table on a page; you could try [WebAIM's table test page](https://webaim.org/articles/nvda/tables.htm) instead. -- Have a look at the [WAI-ARIA live regions example](https://www.freedomscientific.com/SurfsUp/AriaLiveRegions.htm) we saw earlier, and note how the screen reader will keep reading out the constantly updating section as it updates. +- Look at [good-links.html](https://mdn.github.io/learning-area/accessibility/html/good-links.html), and note how they make sense when viewed out of context, for example in the VoiceOver Rotor. This is not the case with [bad-links.html](https://mdn.github.io/learning-area/accessibility/html/bad-links.html) — they are all just "click here". +- Look at [good-form.html](https://mdn.github.io/learning-area/accessibility/html/good-form.html), and note how the form inputs are described using their labels because we've added appropriate {{htmlelement("label")}} elements. In [bad-form.html](https://mdn.github.io/learning-area/accessibility/html/bad-form.html), they get an unhelpful label along the lines of "blank". +- Look at our [punk-bands-complete.html](https://mdn.github.io/learning-area/css/styling-boxes/styling-tables/punk-bands-complete.html) example, and see how the screen reader is able to associate columns and rows of content and read them out all together because we've defined the table headers properly. In [bad-table.html](https://mdn.github.io/learning-area/accessibility/html/bad-table.html), none of the cells can be associated at all. Note that NVDA seems to behave slightly strangely when you've only got a single table on a page; you could try [WebAIM's table test page](https://webaim.org/articles/nvda/tables.htm) instead. +- Have a look at [WAI-ARIA live regions example](https://www.freedomscientific.com/SurfsUp/AriaLiveRegions.htm), and note how the screen reader will keep reading out the constantly updating section as it updates. -## User testing +## Other tooling -As mentioned above, you can't rely on automated tools alone for determining accessibility problems on your site. It is recommended that when you draw up your testing plan, you should include some accessibility user groups if at all possible. Try to get some screen reader users involved, some keyboard-only users, some non-hearing users, and perhaps other groups too, as suits your requirements. +Screen readers are one of the most common types of assistive technology that you'll encounter as a web developer, but other AT types exist, and it is useful to be familiar with what users are potentially using to access your content. This section summarizes some of them. -## Other tooling +### Large text or braille keyboards + +It is possible to get large text keyboards designed for use by visually impaired or older users, and braille keyboards designed to be usable by blind and severely visually impaired people. + +### Alternative pointing devices + +When you think of pointing devices, mice are the obvious example, but there are other pointing devices designed to allow users with differing mobility impairments to navigate user interfaces more easily: + +- Trackballs: Kind of like upside-down mice, trackballs consist of a mounted ball that stays stationary on your desk, which you can roll to move the pointer around. They are considered more precise and easier to handle than mice, especially for people with limited hand movement. +- Joysticks: A control stick that can be moved to move the pointer around. Joysticks are less precise than trackballs but usable by people with a wide range of physical impairments, even severe disabilities. +- Touchpads: Most modern laptops have a touchpad (sometimes called a trackpad) — a flat tactile sensor allowing you to move the pointer around with a finger, as well as performing multi-finger gestures in the same way as mobile gestures. You can buy external touchpads for devices that don't have internal ones. Some people find them to be more precise than mice. + +### Screen magnifiers + +Screen magnifiers provide partially-sighted users with a magnified view of their device's display to enable them to understand and interact with device content more easily, as well as providing other features such as color adjustment to help with color blindness, and adjusting the size of mouse pointers and text cursors to make them easier to see. + +Software and hardware screen magnifiers are available: + +- Most modern operating systems have a built-in app for magnifying all or part of the screen, for example Zoom on mac or Magnifier on Windows. They also tend to provide options for universally increasing the text size, mouse cursor size, etc. Third-party options are available as well. +- Hardware screen magnifiers tend to consist of a separate screen that sits next to or in front of your device's screen and projects a larger version of it, or a zoomed version of part of it. + +### Voice recognition software + +Voice (or speech) recognition software allows you to speak commands to control your device and/or speak the text of emails or documents and have the computer write the text for you. This is very useful for people who are unable to use a keyboard or other control mechanisms. + +Modern operating systems have features built in to enable this (for example Dictation on mac, or Voice Access on Windows), and there are third-party apps available too, from desktop apps to browser extensions. + +### Switch controls + +Switch controls provide a mechanism for interacting with devices for users with very limited mobility or [cognitive impairment](/en-US/docs/Web/Accessibility/Guides/Cognitive_accessibility). + +A switch control setup usually involves two parts: + +- A physical switch or button for activating options on the device. You can also assign switch functionality to regular device buttons (such as volume controls) or keys on a keyboard. +- A device mode or third-party software add-on that makes the device compatible with the switch or button control. For example, Switch Access on Android is a mode whereby the different options in various situations (for example, apps on the home screen) are cycled through and then the one you want can be selected with a button or switch when reached. + +## Planing for accessibility + +You should think carefully about accessibility near the start of each project. Make sure accessibility is considered during the initial design phase, so that you can: + +- Get the basics right, for example using [good document structure](/en-US/docs/Learn_web_development/Core/Accessibility/HTML#use_well-structured_text_content) and providing [alternative text](/en-US/docs/Learn_web_development/Core/Accessibility/HTML#text_alternatives) for images. +- Carefully consider the best approach for features that are likely to have accessibility issues. For example, audio and video will definitely be inaccessible to some people, so you should provide alternatives such as [transcripts](/en-US/docs/Learn_web_development/Core/Accessibility/Multimedia#audio_transcripts) and [text tracks](/en-US/docs/Learn_web_development/Core/Accessibility/Multimedia#video_text_tracks). +- Avoid costly mistakes later on. Issues uncovered near the end of a project tend to be far more time consuming and expensive to fix than issues caught early on. + +## User testing + +You can't rely on automated tools alone for determining accessibility problems on your site. Every website project needs a [user testing strategy](/en-US/docs/Learn_web_development/Extensions/Testing/Testing_strategies#user_testing), and it is highly recommended that you include some accessibility user groups: -Many other assistive technology types exist, such as: +- Try to get some screen reader users involved, some keyboard-only users, some non-hearing users, users with mobility impairments, etc. +- Get each group to try using the website generally, starting with looking at the home page and other major pages, and trying out some of the primary functionality. Typical examples include buying a product or making a booking. Ask them what their impressions were, and what problems they ran into. +- Next, get them to focus on features or workflows that you have specific accessibility concerns with, such as complex form controls or video players. Ask them what is lacking for them in terms of user experience, and what they'd like to see changed. -- Large text or braille keyboards. -- Alternative pointing devices such as trackballs, joysticks, and touchpads. -- Screen magnifiers. -- Voice recognition software. -- Switch controls. +Some projects will have a budget to pay testing groups, whereas others will rely on unpaid volunteers or even colleagues and friends. ## Accessibility testing checklist @@ -381,7 +428,7 @@ The following list provides a checklist for you to follow to make sure you've ca 1. Make sure your HTML is as semantically correct as possible. [Validating it](/en-US/docs/Learn_web_development/Core/Structuring_content/Debugging_HTML#html_validation) is a good start, as is using an [auditing tool](#auditing_tools). 2. Check that your content makes sense when the CSS is turned off. -3. Make sure your functionality is keyboard accessible (see [UI controls](/en-US/docs/Learn_web_development/Core/Accessibility/HTML#ui_controls) for more details). Test using Tab, Return/Enter, etc. +3. Make sure your functionality is keyboard accessible (see [Use semantic UI controls where possible](/en-US/docs/Learn_web_development/Core/Accessibility/HTML#use_semantic_ui_controls_where_possible) for more details). Test using Tab, Return/Enter, etc. 4. Make sure your non-text content has [text alternatives](/en-US/docs/Learn_web_development/Core/Accessibility/HTML#text_alternatives). An [auditing tool](#auditing_tools) is good for catching such problems. 5. Make sure your site's [color contrast](/en-US/docs/Learn_web_development/Core/Accessibility/CSS_and_JavaScript#color_and_color_contrast) is acceptable, using a suitable checking tool. 6. Make sure [hidden content](/en-US/docs/Learn_web_development/Core/Accessibility/CSS_and_JavaScript#hiding_things) is visible by screen readers. diff --git a/files/en-us/learn_web_development/core/accessibility/wai-aria_basics/index.md b/files/en-us/learn_web_development/core/accessibility/wai-aria_basics/index.md index 614e9befcf4907b..f91b637ab89f355 100644 --- a/files/en-us/learn_web_development/core/accessibility/wai-aria_basics/index.md +++ b/files/en-us/learn_web_development/core/accessibility/wai-aria_basics/index.md @@ -1,11 +1,11 @@ --- title: WAI-ARIA basics +short-title: WAI-ARIA slug: Learn_web_development/Core/Accessibility/WAI-ARIA_basics page-type: learn-module-chapter +sidebar: learnsidebar --- -{{LearnSidebar}} - {{PreviousMenuNext("Learn_web_development/Core/Accessibility/CSS_and_JavaScript","Learn_web_development/Core/Accessibility/Multimedia", "Learn_web_development/Core/Accessibility")}} Following on from the previous article, sometimes making complex UI controls that involve unsemantic HTML and dynamic JavaScript-updated content can be difficult. WAI-ARIA is a technology that can help with such problems by adding in further semantics that browsers and assistive technologies can recognize and use to let users know what is going on. Here we'll show how to use it at a basic level to improve accessibility. @@ -39,7 +39,7 @@ Let's start by looking at what WAI-ARIA is, and what it can do for us. As web apps started to get more complex and dynamic, a new set of accessibility features and problems started to appear. -For example, HTML introduced a number of semantic elements to define common page features ({{htmlelement("nav")}}, {{htmlelement("footer")}}, etc.). Before these were available, developers would use {{htmlelement("div")}}s with IDs or classes, e.g. `<div class="nav">`, but these were problematic, as there was no easy way to easily find a specific page feature such as the main navigation programmatically. +For example, HTML introduced a number of semantic elements to define common page features ({{htmlelement("nav")}}, {{htmlelement("footer")}}, etc.). Before these were available, developers would use {{htmlelement("div")}}s with IDs or classes, e.g., `<div class="nav">`, but these were problematic, as there was no easy way to easily find a specific page feature such as the main navigation programmatically. The initial solution was to add one or more hidden links at the top of the page to link to the navigation (or whatever else), for example: @@ -63,7 +63,7 @@ The problem here is that visually they work, but screen readers can't make any s [WAI-ARIA](https://www.w3.org/TR/wai-aria/) (Web Accessibility Initiative - Accessible Rich Internet Applications) is a specification written by the W3C, defining a set of additional HTML attributes that can be applied to elements to provide additional semantics and improve accessibility wherever it is lacking. There are three main features defined in the spec: -- [Roles](/en-US/docs/Web/Accessibility/ARIA/Roles) +- [Roles](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles) - : These define what an element is or does. Many of these are so-called landmark roles, which largely duplicate the semantic value of structural elements, such as `role="navigation"` ({{htmlelement("nav")}}), `role="banner"` (document {{htmlelement("header")}}), `role="complementary"` ({{htmlelement("aside")}}) or , `role="search"` ({{htmlelement("search")}}). Some other roles describe different page structures that do not have elements with that match those roles, such as `role="tablist"`, and `role="tabpanel"`, which are commonly found in UIs. - Properties - : These define properties of elements, which can be used to give them extra meaning or semantics. As an example, `aria-required="true"` specifies that a form input needs to be filled in order to be valid, whereas `aria-labelledby="label"` allows you to put an ID on an element, then reference it as being the label for anything else on the page, including multiple elements, which is not possible using `<label for="input">`. As an example, you could use `aria-labelledby` to specify that a key description contained in a {{htmlelement("div")}} is the label for multiple table cells, or you could use it as an alternative to image alt text — specify existing information on the page as an image's alt text, rather than having to repeat it inside the `alt` attribute. You can see an example of this at [Text alternatives](/en-US/docs/Learn_web_development/Core/Accessibility/HTML#text_alternatives). @@ -73,7 +73,7 @@ The problem here is that visually they work, but screen readers can't make any s An important point about WAI-ARIA attributes is that they don't affect anything about the web page, except for the information exposed by the browser's accessibility APIs (where screen readers get their information from). WAI-ARIA doesn't affect webpage structure, the DOM, etc., although the attributes can be useful for selecting elements by CSS. > [!NOTE] -> You can find a useful list of all the ARIA roles and their uses, with links to further information, in the WAI-ARIA spec — see [Definition of Roles](https://www.w3.org/TR/wai-aria-1.1/#role_definitions) — on this site — see [ARIA roles](/en-US/docs/Web/Accessibility/ARIA/Roles). +> You can find a useful list of all the ARIA roles and their uses, with links to further information, in the WAI-ARIA spec — see [Definition of Roles](https://www.w3.org/TR/wai-aria-1.1/#role_definitions) — on this site — see [ARIA roles](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles). > > The spec also contains a list of all the properties and states, with links to further information — see [Definitions of States and Properties (all `aria-*` attributes)](https://www.w3.org/TR/wai-aria-1.1/#state_prop_def). @@ -101,7 +101,7 @@ In this article, we won't attempt to cover every WAI-ARIA feature, and its exact We talked about some of the problems that prompted WAI-ARIA to be created earlier on, but essentially, there are four main areas that WAI-ARIA is useful in: - Signposts/Landmarks - - : ARIA's [`role`](/en-US/docs/Web/Accessibility/ARIA/Roles) attribute values can act as landmarks that either replicate the semantics of HTML elements (e.g., {{htmlelement("nav")}}), or go beyond HTML semantics to provide signposts to different functional areas, for example, `search`, `tablist`, `tab`, `listbox`, etc. + - : ARIA's [`role`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles) attribute values can act as landmarks that either replicate the semantics of HTML elements (e.g., {{htmlelement("nav")}}), or go beyond HTML semantics to provide signposts to different functional areas, for example, `search`, `tablist`, `tab`, `listbox`, etc. - Dynamic content updates - : Screen readers tend to have difficulty with reporting constantly changing content; with ARIA we can use `aria-live` to inform screen reader users when an area of content is updated dynamically: for example, by JavaScript in the page [fetching new content from the server and updating the DOM](/en-US/docs/Learn_web_development/Core/Scripting/Network_requests). - Enhancing keyboard accessibility @@ -270,7 +270,7 @@ footer { } nav { - background-color: ff80ff; + background-color: #ff80ff; display: flex; gap: 2vw; @media (width <= 650px) { @@ -523,7 +523,7 @@ footer { } nav { - background-color: ff80ff; + background-color: #ff80ff; display: flex; gap: 2vw; @media (width <= 650px) { @@ -606,7 +606,7 @@ footer { {{EmbedLiveSample("aria-website-roles", "100", "850")}} -Most importantly, we have used semantic HTML that gives meaning and roles to the structure of the page without adding unnecessary [`role`](/en-US/docs/Web/Accessibility/ARIA/Roles) attributes to our HTML structure, which has a structure like this: +Most importantly, we have used semantic HTML that gives meaning and roles to the structure of the page without adding unnecessary [`role`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles) attributes to our HTML structure, which has a structure like this: ```html <header> @@ -631,7 +631,7 @@ Most importantly, we have used semantic HTML that gives meaning and roles to the <footer>…</footer> ``` -We've also given you a bonus feature in this example — the {{htmlelement("input")}} element has been given the attribute [`aria-label`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-label), which gives it a descriptive label to be read out by a screen reader, even though we haven't included a {{htmlelement("label")}} element. In cases like these, this is very useful — a search form like this one is a very common, easily recognized feature, and adding a visual label would spoil the page design. +We've also given you a bonus feature in this example — the {{htmlelement("input")}} element has been given the attribute [`aria-label`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-label), which gives it a descriptive label to be read out by a screen reader, even though we haven't included a {{htmlelement("label")}} element. In cases like these, this is very useful — a search form like this one is a very common, easily recognized feature, and adding a visual label would spoil the page design. ```html <input @@ -723,7 +723,7 @@ function showQuote() { This works OK, but it is not good for accessibility — the content update is not detected by screen readers, so their users would not know what is going on. This is a fairly trivial example, but just imagine if you were creating a complex UI with lots of constantly updating content, like a chat room, or a strategy game UI, or a live updating shopping cart display — it would be impossible to use the app in any effective way without some kind of way of alerting the user to the updates. -WAI-ARIA, fortunately, provides a useful mechanism to provide these alerts — the [`aria-live`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-live) property. Applying this to an element causes screen readers to read out the content that is updated. How urgently the content is read out depends on the attribute value: +WAI-ARIA, fortunately, provides a useful mechanism to provide these alerts — the [`aria-live`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-live) property. Applying this to an element causes screen readers to read out the content that is updated. How urgently the content is read out depends on the attribute value: - `off` - : The default. Updates should not be announced. @@ -740,7 +740,7 @@ Here we update the `<section>` opening tag as follows: This will cause a screen reader to read out the content as it is updated. -There is an additional consideration here — only the bit of text that updates is read out. It might be nice if we always read out the heading too, so the user can remember what is being read out. To do this, we can add the [`aria-atomic`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-atomic) property to the section. Update your `<section>` opening tag again, like so: +There is an additional consideration here — only the bit of text that updates is read out. It might be nice if we always read out the heading too, so the user can remember what is being read out. To do this, we can add the [`aria-atomic`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-atomic) property to the section. Update your `<section>` opening tag again, like so: ```html <section aria-live="assertive" aria-atomic="true">…</section> @@ -814,7 +814,7 @@ function showQuote() { {{EmbedLiveSample("aria-live", "100", "180")}} > [!NOTE] -> The [`aria-relevant`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-relevant) property is also quite useful for controlling what gets read out when a live region is updated. You can for example only get content additions or removals read out. +> The [`aria-relevant`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-relevant) property is also quite useful for controlling what gets read out when a live region is updated. You can for example only get content additions or removals read out. ### Enhancing keyboard accessibility @@ -825,7 +825,7 @@ However, sometimes you will end up having to write code that either uses non-sem In terms of making non-focusable code focusable, WAI-ARIA extends the `tabindex` attribute with some new values: - `tabindex="0"` — as indicated above, this value allows elements that are not normally tabbable to become tabbable. This is the most useful value of `tabindex`. -- `tabindex="-1"` — this allows not normally tabbable elements to receive focus programmatically, e.g. via JavaScript, or as the target of links. +- `tabindex="-1"` — this allows not normally tabbable elements to receive focus programmatically, e.g., via JavaScript, or as the target of links. We discussed this in more detail and showed a typical implementation back in our HTML accessibility article — see [Building keyboard accessibility back in](/en-US/docs/Learn_web_development/Core/Accessibility/HTML#building_keyboard_accessibility_back_in). @@ -843,8 +843,8 @@ First of all, let's revisit the form example we first looked at in our CSS and J </div> ``` -- [`role="alert"`](/en-US/docs/Web/Accessibility/ARIA/Roles/alert_role) automatically turns the element it is applied to into a live region, so changes to it are read out; it also semantically identifies it as an alert message (important time/context-sensitive information), and represents a better, more accessible way of delivering an alert to a user (modal dialogs like [`alert()`](/en-US/docs/Web/API/Window/alert) calls have a number of accessibility problems; see [Popup Windows](https://webaim.org/techniques/javascript/other#popups) by WebAIM). -- An [`aria-relevant`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-relevant) value of `all` instructs the screen reader to read out the contents of the error list when any changes are made to it — i.e., when errors are added or removed. This is useful because the user will want to know what errors are left, not just what has been added or removed from the list. +- [`role="alert"`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/alert_role) automatically turns the element it is applied to into a live region, so changes to it are read out; it also semantically identifies it as an alert message (important time/context-sensitive information), and represents a better, more accessible way of delivering an alert to a user (modal dialogs like [`alert()`](/en-US/docs/Web/API/Window/alert) calls have a number of accessibility problems; see [Popup Windows](https://webaim.org/techniques/javascript/other#popups) by WebAIM). +- An [`aria-relevant`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-relevant) value of `all` instructs the screen reader to read out the contents of the error list when any changes are made to it — i.e., when errors are added or removed. This is useful because the user will want to know what errors are left, not just what has been added or removed from the list. We could go further with our ARIA usage, and provide some more validation help. How about indicating whether fields are required in the first place, and what range the age should be? @@ -856,7 +856,7 @@ We could go further with our ARIA usage, and provide some more validation help. <p>Fields marked with an asterisk (*) are required.</p> ``` -4. This makes visual sense, but it isn't as easy to understand for screen reader users. Fortunately, WAI-ARIA provides the [`aria-required`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-required) attribute to give screen readers hints that they should tell users that form inputs need to be filled in. Update the `<input>` elements like so: +4. This makes visual sense, but it isn't as easy to understand for screen reader users. Fortunately, WAI-ARIA provides the [`aria-required`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-required) attribute to give screen readers hints that they should tell users that form inputs need to be filled in. Update the `<input>` elements like so: ```html <input type="text" name="name" id="name" aria-required="true" /> @@ -865,7 +865,7 @@ We could go further with our ARIA usage, and provide some more validation help. ``` 5. If you save the example now and test it with a screen reader, you should hear something like "Enter your name star, required, edit text". -6. It might also be useful if we give screen reader users and sighted users an idea of what the age value should be. This is often presented as a tooltip or placeholder inside the form field. WAI-ARIA does include [`aria-valuemin`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-valuemin) and [`aria-valuemax`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-valuemax) properties to specify min and max values, and screen readers support the native `min` and `max` attributes. Another well-supported feature is the HTML `placeholder` attribute, which can contain a message that is shown in the input when no value is entered and is read out by a few screen readers. Update your number input like this: +6. It might also be useful if we give screen reader users and sighted users an idea of what the age value should be. This is often presented as a tooltip or placeholder inside the form field. WAI-ARIA does include [`aria-valuemin`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-valuemin) and [`aria-valuemax`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-valuemax) properties to specify min and max values, and screen readers support the native `min` and `max` attributes. Another well-supported feature is the HTML `placeholder` attribute, which can contain a message that is shown in the input when no value is entered and is read out by a few screen readers. Update your number input like this: ```html <label for="age">Your age:</label> @@ -878,12 +878,12 @@ We could go further with our ARIA usage, and provide some more validation help. aria-required="true" /> ``` -Always include a {{HTMLelement('label')}} for every input. While some screen readers announce the placeholder text, most do not. Acceptable substitutions for providing form controls with an accessible name include [`aria-label`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-label) and [`aria-labelledby`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-labelledby). But the `<label>` element with a `for` attribute is the preferred method as it provides usability for all users, including mouse users. +Always include a {{HTMLelement('label')}} for every input. While some screen readers announce the placeholder text, most do not. Acceptable substitutions for providing form controls with an accessible name include [`aria-label`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-label) and [`aria-labelledby`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-labelledby). But the `<label>` element with a `for` attribute is the preferred method as it provides usability for all users, including mouse users. > [!NOTE] > You can see the finished example live at [`form-validation-updated.html`](https://mdn.github.io/learning-area/accessibility/aria/form-validation-updated.html). -WAI-ARIA also enables some advanced form labelling techniques, beyond the classic {{htmlelement("label")}} element. We already talked about using the [`aria-label`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-label) property to provide a label where we don't want the label to be visible to sighted users (see the [Signposts/Landmarks](#signpostslandmarks) section, above). Some other labeling techniques use other properties such as [`aria-labelledby`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-labelledby) if you want to designate a non-`<label>` element as a label or label multiple form inputs with the same label, and [`aria-describedby`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-describedby), if you want to associate other information with a form input and have it read out as well. See [WebAIM's Advanced Form Labeling article](https://webaim.org/techniques/forms/advanced) for more details. +WAI-ARIA also enables some advanced form labelling techniques, beyond the classic {{htmlelement("label")}} element. We already talked about using the [`aria-label`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-label) property to provide a label where we don't want the label to be visible to sighted users (see the [Signposts/Landmarks](#signpostslandmarks) section, above). Some other labeling techniques use other properties such as [`aria-labelledby`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-labelledby) if you want to designate a non-`<label>` element as a label or label multiple form inputs with the same label, and [`aria-describedby`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-describedby), if you want to associate other information with a form input and have it read out as well. See [WebAIM's Advanced Form Labeling article](https://webaim.org/techniques/forms/advanced) for more details. There are many other useful properties and states too, for indicating the status of form elements. For example, `aria-disabled="true"` can be used to indicate that a form field is disabled. Many browsers will skip past disabled form fields which leads to them not being read out by screen readers. In some cases, a disabled element will be perceived, so it is a good idea to include this attribute to let the screen reader know that a disabled form control is in fact disabled. @@ -916,11 +916,11 @@ function toggleMusician(bool) { #### Describing non-semantic buttons as buttons -A few times in this course already, we've mentioned the native accessibility of (and the accessibility issues behind using other elements to fake) buttons, links, or form elements (see [UI controls](/en-US/docs/Learn_web_development/Core/Accessibility/HTML#ui_controls) in the HTML accessibility article, and [Enhancing keyboard accessibility](#enhancing_keyboard_accessibility), above). Basically, you can add keyboard accessibility back in without too much trouble in many cases, using `tabindex` and a bit of JavaScript. +A few times in this course already, we've mentioned the native accessibility of (and the accessibility issues behind using other elements to fake) buttons, links, or form elements (see [Use semantic UI controls where possible](/en-US/docs/Learn_web_development/Core/Accessibility/HTML#use_semantic_ui_controls_where_possible) in the HTML accessibility article, and [Enhancing keyboard accessibility](#enhancing_keyboard_accessibility), above). Basically, you can add keyboard accessibility back in without too much trouble in many cases, using `tabindex` and a bit of JavaScript. But what about screen readers? They still won't see the elements as buttons. If we test our [`fake-div-buttons.html`](https://mdn.github.io/learning-area/tools-testing/cross-browser-testing/accessibility/fake-div-buttons.html) example in a screen reader, our fake buttons will be reported using phrases like "Click me!, group", which is obviously confusing. -We can fix this using a WAI-ARIA role. Make a local copy of [`fake-div-buttons.html`](https://github.com/mdn/learning-area/blob/main/tools-testing/cross-browser-testing/accessibility/fake-div-buttons.html), and add [`role="button"`](/en-US/docs/Web/Accessibility/ARIA/Roles/button_role) to each button `<div>`, for example: +We can fix this using a WAI-ARIA role. Make a local copy of [`fake-div-buttons.html`](https://github.com/mdn/learning-area/blob/main/tools-testing/cross-browser-testing/accessibility/fake-div-buttons.html), and add [`role="button"`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/button_role) to each button `<div>`, for example: ```html <div data-message="This is from the first button" tabindex="0" role="button"> @@ -928,14 +928,14 @@ We can fix this using a WAI-ARIA role. Make a local copy of [`fake-div-buttons.h </div> ``` -Now when you try this using a screen reader, you'll have buttons be reported using phrases like "Click me!, button". While this is much better, you still have to add in all the native button features users expect, like handling <kbd>enter</kbd> and click events, as explained in the [`button` role documentation](/en-US/docs/Web/Accessibility/ARIA/Roles/button_role). +Now when you try this using a screen reader, you'll have buttons be reported using phrases like "Click me!, button". While this is much better, you still have to add in all the native button features users expect, like handling <kbd>enter</kbd> and click events, as explained in the [`button` role documentation](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/button_role). > [!NOTE] > Don't forget however that using the correct semantic element where possible is always better. If you want to create a button, and can use a {{htmlelement("button")}} element, you should use a {{htmlelement("button")}} element! #### Guiding users through complex widgets -There are a whole host of other [roles](/en-US/docs/Web/Accessibility/ARIA/Roles) that can identify non-semantic element structures as common UI features that go beyond what's available in standard HTML, for example [`combobox`](/en-US/docs/Web/Accessibility/ARIA/Roles/combobox_role), [`slider`](/en-US/docs/Web/Accessibility/ARIA/Roles/slider_role), [`tabpanel`](/en-US/docs/Web/Accessibility/ARIA/Roles/tabpanel_role), [`tree`](/en-US/docs/Web/Accessibility/ARIA/Roles/tree_role). You can see several useful examples in the [Deque university code library](https://dequeuniversity.com/library/) to give you an idea of how such controls can be made accessible. +There are a whole host of other [roles](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles) that can identify non-semantic element structures as common UI features that go beyond what's available in standard HTML, for example [`combobox`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/combobox_role), [`slider`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/slider_role), [`tabpanel`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/tabpanel_role), [`tree`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/tree_role). You can see several useful examples in the [Deque university code library](https://dequeuniversity.com/library/) to give you an idea of how such controls can be made accessible. Let's go through an example of our own. We'll return to our simple absolutely-positioned tabbed interface (see [Hiding things](/en-US/docs/Learn_web_development/Core/Accessibility/CSS_and_JavaScript#hiding_things) in our CSS and JavaScript accessibility article), which you can find at [Tabbed info box example](/en-US/docs/Learn_web_development/Core/CSS_layout/Practical_positioning_examples#a_tabbed_info-box). @@ -1088,8 +1088,7 @@ class TabsManual { this.tabs = Array.from(this.tablistNode.querySelectorAll("[role=tab]")); this.tabpanels = []; - for (let i = 0; i < this.tabs.length; i += 1) { - const tab = this.tabs[i]; + for (const tab of this.tabs) { const tabpanel = document.getElementById( tab.getAttribute("aria-controls"), ); @@ -1101,9 +1100,7 @@ class TabsManual { tab.addEventListener("keydown", this.onKeydown.bind(this)); tab.addEventListener("click", this.onClick.bind(this)); - if (!this.firstTab) { - this.firstTab = tab; - } + this.firstTab ??= tab; this.lastTab = tab; } @@ -1111,8 +1108,7 @@ class TabsManual { } setSelectedTab(currentTab) { - for (let i = 0; i < this.tabs.length; i += 1) { - const tab = this.tabs[i]; + for (const tab of this.tabs.length) { if (currentTab === tab) { tab.setAttribute("aria-selected", "true"); tab.removeAttribute("tabindex"); @@ -1197,10 +1193,10 @@ class TabsManual { // Initialize tablist -window.addEventListener("load", function () { +window.addEventListener("load", () => { const tablists = document.querySelectorAll("[role=tablist].manual"); - for (let i = 0; i < tablists.length; i++) { - new TabsManual(tablists[i]); + for (const tablist of tablists) { + new TabsManual(tablist); } }); ``` @@ -1211,24 +1207,24 @@ In this example we have used a combination of semantic elements, aria roles and ARIA features used include: -- New roles — [`tablist`](/en-US/docs/Web/Accessibility/ARIA/Roles/tablist_role), [`tab`](/en-US/docs/Web/Accessibility/ARIA/Roles/tab_role), [`tabpanel`](/en-US/docs/Web/Accessibility/ARIA/Roles/tabpanel_role) +- New roles — [`tablist`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/tablist_role), [`tab`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/tab_role), [`tabpanel`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/tabpanel_role) - : These identify the important areas of the tabbed interface — the container for the tabs, the tabs themselves, and the corresponding tabpanels. -- [`aria-selected`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-selected) +- [`aria-selected`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-selected) - : Defines which tab is currently selected. As different tabs are selected by the user, the value of this attribute on the different tabs is updated via JavaScript. - `tabindex="-1"` - : `tabindex="-1"` takes the element out of the tab order. As we are using JavaScript to allow the user to control the tabs via keyboard or mouse we do not want the user to be able to use the tab key to navigate to the buttons. -- [`aria-labelledby`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-labelledby) +- [`aria-labelledby`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-labelledby) - : This attribute identifies an element (by its `id`) that labels the element, in this example the `<article>` is labelled by the corresponding tab or `<button>`. -- [`aria-controls`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-controls) +- [`aria-controls`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-controls) - : This attribute identifies an element (by its `id`) that is controlled the element, in this example the `<article>` is controlled by the corresponding tab or `<button>`. We could have used `aria-hidden` to hide the content of the tabpanels from assistive technologies but if that content contained focusable content, such as links, the user would still be able to tab to that content even when aria-hidden=true is set for the non-active panels. In this example we have applied `class="is-hidden"` to tabpanels that correspond to the tabs with `aria-selected="false"` and using CSS to `display: none;` which prevents the hidden content from being tabbed to. -In our tests, this new structure did serve to improve things overall. The `<button>`s are now recognized as tabs (e.g. "tab" is spoken by the screen reader), the selected tab is indicated by "selected" being read out with the tab name and any content that is not shown can not be tabbed to. The user can also navigate the tabs with keyboard or mouse. +In our tests, this new structure did serve to improve things overall. The `<button>`s are now recognized as tabs (e.g., "tab" is spoken by the screen reader), the selected tab is indicated by "selected" being read out with the tab name and any content that is not shown can not be tabbed to. The user can also navigate the tabs with keyboard or mouse. ## Test your skills! -You've reached the end of this article, but can you remember the most important information? You can find some further tests to verify that you've retained this information before you move on — see [Test your skills: WAI-ARIA](/en-US/docs/Learn_web_development/Core/Accessibility/WAI-ARIA_basics/Test_your_skills:_WAI-ARIA). +You've reached the end of this article, but can you remember the most important information? You can find some further tests to verify that you've retained this information before you move on — see [Test your skills: WAI-ARIA](/en-US/docs/Learn_web_development/Core/Accessibility/Test_your_skills/WAI-ARIA). ## Summary @@ -1236,8 +1232,8 @@ This article has by no means covered all that's available in WAI-ARIA, but it sh ## See also -- [Aria states and properties](/en-US/docs/Web/Accessibility/ARIA/Attributes): All `aria-*` attributes -- [WAI-ARIA roles](/en-US/docs/Web/Accessibility/ARIA/Roles): Categories of ARIA roles and the roles covered on MDN +- [Aria states and properties](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes): All `aria-*` attributes +- [WAI-ARIA roles](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles): Categories of ARIA roles and the roles covered on MDN - [ARIA in HTML](https://www.w3.org/TR/html-aria/) on W3C: A specification that defines, for each HTML feature, the accessibility (ARIA) semantics implicitly applied on it by the browser and the WAI-ARIA features you may set on it if extra semantics are required - [Deque university code library](https://dequeuniversity.com/library/): A library of really useful and practical examples showing complex UI controls made accessible using WAI-ARIA features - [WAI-ARIA authoring practices](https://www.w3.org/WAI/ARIA/apg/) on W3C: A very detailed design pattern from the W3C, explaining how to implement different types of complex UI control whilst making them accessible using WAI-ARIA features diff --git a/files/en-us/learn_web_development/core/accessibility/wai-aria_basics/test_your_skills_colon__wai-aria/index.md b/files/en-us/learn_web_development/core/accessibility/wai-aria_basics/test_your_skills_colon__wai-aria/index.md deleted file mode 100644 index b2fa52a6aaf190d..000000000000000 --- a/files/en-us/learn_web_development/core/accessibility/wai-aria_basics/test_your_skills_colon__wai-aria/index.md +++ /dev/null @@ -1,52 +0,0 @@ ---- -title: "Test your skills: WAI-ARIA" -slug: Learn_web_development/Core/Accessibility/WAI-ARIA_basics/Test_your_skills:_WAI-ARIA -page-type: learn-module-assessment ---- - -{{learnsidebar}} - -The aim of this skill test is to assess whether you've understood our [WAI-ARIA basics](/en-US/docs/Learn_web_development/Core/Accessibility/WAI-ARIA_basics) article. - -> [!NOTE] -> You can try solutions in the interactive editors on this page or in an online editor such as [CodePen](https://codepen.io/), [JSFiddle](https://jsfiddle.net/), or [Glitch](https://glitch.com/). -> -> If you get stuck, you can reach out to us in one of our [communication channels](/en-US/docs/MDN/Community/Communication_channels). - -## WAI-ARIA 1 - -In our first ARIA task, we present you with a section of non-semantic markup, which is obviously meant to be a list. Assuming you are not able to change the elements used, how can you allow screen reader users to recognize this as a list? - -Try updating the live code below to recreate the finished example: - -{{EmbedGHLiveSample("learning-area/accessibility/tasks/html-css/aria/aria1.html", '100%', 700)}} - -> [!CALLOUT] -> -> [Download the starting point for this task](https://github.com/mdn/learning-area/blob/main/accessibility/tasks/html-css/aria/aria1-download.html) to work in your own editor or in an online editor. - -## WAI-ARIA 2 - -In our second WAI-ARIA task, we present a simple search form, and we want you to add in a couple of WAI-ARIA features to improve its accessibility: - -1. How can you allow the search form to be called out as a separate landmark on the page by screen readers, to make it easily findable? -2. How can you give the search input a suitable label, without explicitly adding a visible text label to the DOM? - -Try updating the live code below to recreate the finished example: - -{{EmbedGHLiveSample("learning-area/accessibility/tasks/html-css/aria/aria2.html", '100%', 700)}} - -> [!CALLOUT] -> -> [Download the starting point for this task](https://github.com/mdn/learning-area/blob/main/accessibility/tasks/html-css/aria/aria2-download.html) to work in your own editor or in an online editor. - -## WAI-ARIA 3 - -For this final WAI-ARIA task, we return to an example we previously saw in the [CSS and JavaScript skill test](/en-US/docs/Learn_web_development/Core/Accessibility/CSS_and_JavaScript/Test_your_skills:_CSS_and_JavaScript_accessibility). -As before, we have an app that presents a list of animal names. Clicking one of the animal names causes a further description of that animal to appear in a box below the list. Here, we are starting with a mouse- and keyboard-accessible version. - -The problem we have now is that when the DOM changes to show a new description, screen readers cannot see what has changed. Can you update it so that description changes are announced by the screen reader? - -> [!CALLOUT] -> -> [Download the starting point for this task](https://github.com/mdn/learning-area/blob/main/accessibility/tasks/js/aria/aria-js1-download.html) to work in your own editor or in an online editor. diff --git a/files/en-us/learn_web_development/core/accessibility/what_is_accessibility/index.md b/files/en-us/learn_web_development/core/accessibility/what_is_accessibility/index.md index 58c10b32c36d642..23aa8232d4493a4 100644 --- a/files/en-us/learn_web_development/core/accessibility/what_is_accessibility/index.md +++ b/files/en-us/learn_web_development/core/accessibility/what_is_accessibility/index.md @@ -2,10 +2,9 @@ title: What is accessibility? slug: Learn_web_development/Core/Accessibility/What_is_accessibility page-type: learn-module-chapter +sidebar: learnsidebar --- -{{LearnSidebar}} - {{NextMenu("Learn_web_development/Core/Accessibility/Tooling", "Learn_web_development/Core/Accessibility")}} This article starts the module off with a good look at what accessibility is — this overview includes what groups of people we need to consider and why, what tools different people use to interact with the web, and how we can make accessibility part of our web development workflow. @@ -59,7 +58,7 @@ People with visual impairments include people with blindness, low-level vision, - Paid commercial products, like [JAWS](https://www.freedomscientific.com/Products/software/JAWS/) (Windows) and [Dolphin Screen Reader](https://yourdolphin.com/ScreenReader) (Windows). - Free products, like [NVDA](https://www.nvaccess.org/) (Windows), [ChromeVox](https://support.google.com/chromebook/answer/7031755) (Chrome), and [Orca](https://wiki.gnome.org/Projects/Orca) (Linux). -- Software built into the operating system, like [VoiceOver](https://www.apple.com/accessibility/vision/) (macOS, iPadOS, iOS), [Narrator](https://support.microsoft.com/en-us/windows/complete-guide-to-narrator-e4397a0d-ef4f-b386-d8ae-c172f109bdb1) (Windows), [ChromeVox](https://support.google.com/chromebook/answer/7031755) (on ChromeOS), and [TalkBack](https://play.google.com/store/apps/details?id=com.google.android.marvin.talkback) (Android). +- Software built into the operating system, like [VoiceOver](https://www.apple.com/accessibility/features/?vision) (macOS, iPadOS, iOS), [Narrator](https://support.microsoft.com/en-us/windows/complete-guide-to-narrator-e4397a0d-ef4f-b386-d8ae-c172f109bdb1) (Windows), [ChromeVox](https://support.google.com/chromebook/answer/7031755) (on ChromeOS), and [TalkBack](https://play.google.com/store/apps/details?id=com.google.android.marvin.talkback) (Android). It is a good idea to familiarize yourself with screen readers; you should also set up a screen reader and play around with it, to get an idea of how it works. See our [screen reader tutorials](/en-US/docs/Learn_web_development/Core/Accessibility/Tooling#screen_readers) for more details on using them. The below video also provides a brief example of what the experience is like. @@ -81,13 +80,13 @@ These people have disabilities concerning movement, which might involve purely p This kind of disability can also be a result of old age, rather than any specific trauma or condition, and it could also result from hardware limitations — some users might not have a mouse. -The way this usually affects web development work is the requirement that controls be accessible by the keyboard — we'll discuss keyboard accessibility in later articles in the module, but it is a good idea to try out some websites using just the keyboard to see how you get on. Can you use the Tab key to move between the different controls of a web form, for example? You can find more details about keyboard controls in our [UI controls](/en-US/docs/Learn_web_development/Core/Accessibility/HTML#ui_controls) section. +The way this usually affects web development work is the requirement that controls be accessible by the keyboard — we'll discuss keyboard accessibility in later articles in the module, but it is a good idea to try out some websites using just the keyboard to see how you get on. Can you use the Tab key to move between the different controls of a web form, for example? You can find more details about keyboard controls in our [Use semantic UI controls where possible](/en-US/docs/Learn_web_development/Core/Accessibility/HTML#use_semantic_ui_controls_where_possible) section. In terms of statistics, a significant number of people have mobility impairments. The US Centers for Disease Control and Prevention [Disability and Functioning (Non-institutionalized Adults 18 Years and Over)](https://www.cdc.gov/nchs/fastats/disability.htm) reports the USA "Percent of adults with any physical functioning difficulty: 16.1%". ### People with cognitive impairments -Cognitive impairment refers to a broad range of disabilities, from people with intellectual disabilities who have the most-limited capabilities, to all of us as we age and have difficulty thinking and remembering. The range includes people with mental illnesses, such as [depression](https://www.nimh.nih.gov/health/topics/depression) and [schizophrenia](https://www.nimh.nih.gov/health/topics/schizophrenia). It also includes people with learning disabilities, such as [dyslexia](https://www.ninds.nih.gov/health-information/disorders/learning-disabilities) and [attention deficit hyperactivity disorder](https://www.nimh.nih.gov/health/topics/attention-deficit-hyperactivity-disorder-adhd). Importantly, though there is a lot of diversity within clinical definitions of cognitive impairments, people with them experience a common set of functional problems. These include difficulty with understanding content, remembering how to complete tasks, and confusion caused by inconsistent webpage layouts. +Cognitive impairment refers to a broad range of disabilities, from people with intellectual disabilities who have the most-limited capabilities, to all of us as we age and have difficulty thinking and remembering. The range includes people with mental illnesses, such as [depression](https://www.nimh.nih.gov/health/topics/depression) and [schizophrenia](https://www.nimh.nih.gov/health/topics/schizophrenia). It also includes people with learning disabilities, such as [dyslexia](https://www.nichd.nih.gov/health/topics/learningdisabilities) and [attention deficit hyperactivity disorder](https://www.nimh.nih.gov/health/topics/attention-deficit-hyperactivity-disorder-adhd). Importantly, though there is a lot of diversity within clinical definitions of cognitive impairments, people with them experience a common set of functional problems. These include difficulty with understanding content, remembering how to complete tasks, and confusion caused by inconsistent webpage layouts. A good foundation of accessibility for people with cognitive impairments includes: @@ -103,8 +102,8 @@ A good foundation of accessibility for people with cognitive impairments include ### Notes -- Designing with [cognitive accessibility](/en-US/docs/Web/Accessibility/Cognitive_accessibility) will lead to good design practices. They will benefit everyone. -- Many people with cognitive impairments also have physical disabilities. Websites must conform to the W3C's [Web Content Accessibility Guidelines](https://www.w3.org/WAI/standards-guidelines/wcag/), including [cognitive accessibility guidelines](/en-US/docs/Web/Accessibility/Cognitive_accessibility#wcag_guidelines). +- Designing with [cognitive accessibility](/en-US/docs/Web/Accessibility/Guides/Cognitive_accessibility) will lead to good design practices. They will benefit everyone. +- Many people with cognitive impairments also have physical disabilities. Websites must conform to the W3C's [Web Content Accessibility Guidelines](https://www.w3.org/WAI/standards-guidelines/wcag/), including [cognitive accessibility guidelines](/en-US/docs/Web/Accessibility/Guides/Cognitive_accessibility#wcag_guidelines). - The W3C's [Cognitive and Learning Disabilities Accessibility Task Force](https://www.w3.org/WAI/GL/task-forces/coga/) produces web accessibility guidelines for people with cognitive impairments. - WebAIM has a [Cognitive page](https://webaim.org/articles/cognitive/) of relevant information and resources. - The United States Centers for Disease Control estimate that, as of 2018, 1 in 4 US citizens have a disability and, of them, [cognitive impairment is the most common for young people](https://archive.cdc.gov/www_cdc_gov/media/releases/2018/p0816-disability.html). @@ -120,7 +119,7 @@ A common accessibility myth is that accessibility is an expensive "added extra" If however, you consider accessibility from the start of a project, the cost of making most content accessible should be fairly minimal. -When planning your project, factor accessibility testing into your testing regime, just like testing for any other important target audience segment (e.g., target desktop or mobile browsers). Test early and often, ideally running automated tests to pick up on programmatically detectable missing features (such as missing image [alternative text](/en-US/docs/Learn_web_development/Core/Accessibility/HTML#text_alternatives) or bad link text — see [Meaningful text labels](/en-US/docs/Learn_web_development/Core/Accessibility/HTML#meaningful_text_labels)) and doing some testing with disabled user groups to see how well more complex site features work for them. For example: +When planning your project, factor accessibility testing into your testing regime, just like testing for any other important target audience segment (e.g., target desktop or mobile browsers). Test early and often, ideally running automated tests to pick up on programmatically detectable missing features (such as missing image [alternative text](/en-US/docs/Learn_web_development/Core/Accessibility/HTML#text_alternatives) or bad link text — see [Use meaningful text labels](/en-US/docs/Learn_web_development/Core/Accessibility/HTML#use_meaningful_text_labels)) and doing some testing with disabled user groups to see how well more complex site features work for them. For example: - Is my date picker widget usable by people using screen readers? - If content updates dynamically, do visually impaired people know about it? @@ -145,7 +144,7 @@ To summarize: There are numerous checklists and sets of guidelines available for basing accessibility tests on, which might seem overwhelming at first glance. Our advice is to familiarize yourself with the basic areas in which you need to take care, as well as understanding the high-level structures of the guidelines that are most relevant to you. - For a start, the W3C has published a large and very detailed document that includes very precise, technology-agnostic criteria for accessibility conformance. These are called the [Web Content Accessibility Guidelines](https://www.w3.org/WAI/standards-guidelines/wcag/) (WCAG), and they are not a short read by any means. The criteria are split up into four main categories, which specify how implementations can be made perceivable, operable, understandable, and robust. The best place to get a light introduction and start learning is [WCAG at a Glance](https://www.w3.org/WAI/standards-guidelines/wcag/glance/). There is no need to learn all of the WCAG criteria — be aware of the major areas of concern, and use a variety of techniques and tools to highlight any areas that don't conform to the WCAG criteria (see below for more). -- Your country may also have specific legislation governing the need for websites serving their population to be accessible — for example [EN 301 549](https://www.etsi.org/deliver/etsi_en/301500_301599/301549/02.01.02_60/en_301549v020102p.pdf) in the EU, [Section 508 of the Rehabilitation Act](https://www.section508.gov/training/) in the US, [Federal Ordinance on Barrier-Free Information Technology](https://www.aktion-mensch.de/inklusion/barrierefreiheit/barrierefreie-website) in Germany, the [Accessibility Regulations 2018](https://www.legislation.gov.uk/uksi/2018/952/introduction/made) in the UK, [Accessibilità](https://www.agid.gov.it/it/ambiti-intervento/accessibilita-usabilita) in Italy, the [Disability Discrimination Act](https://humanrights.gov.au/our-work/disability-rights/world-wide-web-access-disability-discrimination-act-advisory-notes-ver) in Australia, etc. The W3C keeps a list of [Web Accessibility Laws & Policies](https://www.w3.org/WAI/policies/) by country. +- Your country may also have specific legislation governing the need for websites serving their population to be accessible — for example [EN 301 549](https://www.etsi.org/deliver/etsi_en/301500_301599/301549/02.01.02_60/en_301549v020102p.pdf) in the EU, [Section 508 of the Rehabilitation Act](https://www.section508.gov/training/) in the US, [Federal Ordinance on Barrier-Free Information Technology](https://www.aktion-mensch.de/inklusion/barrierefreiheit/barrierefreie-website) in Germany, the [Accessibility Regulations 2018](https://www.legislation.gov.uk/uksi/2018/952/introduction/made) in the UK, [Accessibilità](https://www.agid.gov.it/it/ambiti-intervento/accessibilita-usabilita) in Italy, the [Disability Discrimination Act](https://humanrights.gov.au/our-work/disability-rights/publications/guidelines-equal-access-digital-goods-and-services) in Australia, etc. The W3C keeps a list of [Web Accessibility Laws & Policies](https://www.w3.org/WAI/policies/) by country. So while the WCAG is a set of guidelines, your country will probably have laws governing web accessibility, or at least the accessibility of services available to the public (which could include websites, television, physical spaces, etc.) It is a good idea to find out what your laws are. If you make no effort to check that your content is accessible, you could be legally liable if people complain. @@ -171,12 +170,12 @@ This article should have given you a useful high-level overview of accessibility ## See also -- [WCAG](/en-US/docs/Web/Accessibility/Understanding_WCAG) +- [WCAG](/en-US/docs/Web/Accessibility/Guides/Understanding_WCAG) - - [Perceivable](/en-US/docs/Web/Accessibility/Understanding_WCAG/Perceivable) - - [Operable](/en-US/docs/Web/Accessibility/Understanding_WCAG/Operable) - - [Understandable](/en-US/docs/Web/Accessibility/Understanding_WCAG/Understandable) - - [Robust](/en-US/docs/Web/Accessibility/Understanding_WCAG/Robust) + - [Perceivable](/en-US/docs/Web/Accessibility/Guides/Understanding_WCAG/Perceivable) + - [Operable](/en-US/docs/Web/Accessibility/Guides/Understanding_WCAG/Operable) + - [Understandable](/en-US/docs/Web/Accessibility/Guides/Understanding_WCAG/Understandable) + - [Robust](/en-US/docs/Web/Accessibility/Guides/Understanding_WCAG/Robust) - [Google Chrome released an auto-captioning extension](https://blog.google/products/chrome/live-caption-chrome/) diff --git a/files/en-us/learn_web_development/core/challenges/index.md b/files/en-us/learn_web_development/core/challenges/index.md index 5eeed80daf5a2a8..e815858a13b727e 100644 --- a/files/en-us/learn_web_development/core/challenges/index.md +++ b/files/en-us/learn_web_development/core/challenges/index.md @@ -2,6 +2,7 @@ title: Challenge solutions slug: Learn_web_development/Core/Challenges page-type: guide +sidebar: learnsidebar --- This page provides solutions to the challenges posed in the [CSS Styling basics](/en-US/docs/Learn_web_development/Core/Styling_basics) module. These are not the only possible solutions. The sections below correspond to the titles of the tutorial sections. diff --git a/files/en-us/learn_web_development/core/css_layout/flexbox/flexbox-example6.png b/files/en-us/learn_web_development/core/css_layout/flexbox/flexbox-example6.png deleted file mode 100644 index d0479daa9257dc4..000000000000000 Binary files a/files/en-us/learn_web_development/core/css_layout/flexbox/flexbox-example6.png and /dev/null differ diff --git a/files/en-us/learn_web_development/core/css_layout/flexbox/index.md b/files/en-us/learn_web_development/core/css_layout/flexbox/index.md index 2c82ff3a8e576c4..4cb602fb770c3b5 100644 --- a/files/en-us/learn_web_development/core/css_layout/flexbox/index.md +++ b/files/en-us/learn_web_development/core/css_layout/flexbox/index.md @@ -2,10 +2,9 @@ title: Flexbox slug: Learn_web_development/Core/CSS_layout/Flexbox page-type: learn-module-chapter +sidebar: learnsidebar --- -{{LearnSidebar}} - {{PreviousMenuNext("Learn_web_development/Core/CSS_layout/Positioning", "Learn_web_development/Core/CSS_layout/Grids", "Learn_web_development/Core/CSS_layout")}} [Flexbox](/en-US/docs/Web/CSS/CSS_flexible_box_layout) is a one-dimensional layout method for arranging items in rows or columns. Items _flex_ (expand) to fill additional space or shrink to fit into smaller spaces. This article explains all the fundamentals. @@ -49,6 +48,9 @@ CSS flexible box layout enables you to: Flexbox features may be the perfect solution for your one dimensional layout needs. Let's dig in and find out! +> [!NOTE] +> Scrimba's introductory [Flexbox](https://scrimba.com/learn-html-and-css-c0p/~017?via=mdn) <sup>[_MDN learning partner_](/en-US/docs/MDN/Writing_guidelines/Learning_content#partner_links_and_embeds)</sup> scrim provides an interactive guide covering how common flexbox is on the web and therefore why it is so important to learn, and walks you through a typical use case that demonstrates the power of flexbox. + ## Introducing a simple example In this article, you'll work through a series of exercises to help you understand how flexbox works. To get started, you should make a local copy of the HTML and CSS. Load it in a modern browser (like Firefox or Chrome) and have a look at the code in your code editor. Alternatively open the example in {{LiveSampleLink("flexbox_0", "open the playground")}}. @@ -333,7 +335,7 @@ You'll see that the layout looks much better with this included: {{EmbedLiveSample("flex-wrap_1", "100", "430")}} -We now have multiple rows. Each row has as many flexbox children fitted into it as is sensible. Any overflow is moved down to the next line. The `flex: 200px` declaration set on the articles means that each will be at least `200px` wide. We'll discuss this property in more detail later on. You might also notice that the last few children on the last row are each made wider so that the entire row is still filled. +We now have multiple rows. Each row has as many flexbox children fitted into it as is sensible. Any overflow is moved down to the next line. But there's more we can do here. First of all, try changing your {{cssxref("flex-direction")}} property value to `row-reverse`. Now you'll see that you still have your multiple row layout, but it starts from the opposite corner of the browser window and flows in reverse. @@ -872,7 +874,7 @@ button { ## Test your skills! -You've reached the end of this article, but can you remember the most important information? You can find some further tests to verify that you've retained this information before you move on — see [Test your skills: Flexbox](/en-US/docs/Learn_web_development/Core/CSS_layout/Flexbox_skills). +You've reached the end of this article, but can you remember the most important information? You can find some further tests to verify that you've retained this information before you move on — see [Test your skills: Flexbox](/en-US/docs/Learn_web_development/Core/CSS_layout/Test_your_skills/Flexbox). ## Summary diff --git a/files/en-us/learn_web_development/core/css_layout/flexbox_skills/index.md b/files/en-us/learn_web_development/core/css_layout/flexbox_skills/index.md deleted file mode 100644 index 5bb1cc7efc85a61..000000000000000 --- a/files/en-us/learn_web_development/core/css_layout/flexbox_skills/index.md +++ /dev/null @@ -1,292 +0,0 @@ ---- -title: "Test your skills: Flexbox" -slug: Learn_web_development/Core/CSS_layout/Flexbox_skills -page-type: learn-module-assessment ---- - -{{LearnSidebar}} - -The aim of this skill test is to assess whether you understand how [flexbox and flex items](/en-US/docs/Learn_web_development/Core/CSS_layout/Flexbox) behave. Below are four common design patterns that you might use flexbox to create. Your task is to build them. - -> [!NOTE] -> Click **"Play"** in the code blocks below to edit the examples in the MDN Playground. -> You can also copy the code (click the clipboard icon) and paste it into an online editor such as [CodePen](https://codepen.io/), [JSFiddle](https://jsfiddle.net/), or [Glitch](https://glitch.com/). -> If you get stuck, you can reach out to us in one of our [communication channels](/en-US/docs/MDN/Community/Communication_channels). - -## Task 1 - -In this task, the list items are the navigation for a site. They should be laid out as a row, with an equal amount of space between each item. - -Your final result should look like the image below: - -![Flex items laid out as a row with space between them.](flex-task1.png) - -Try to update the code below to recreate the finished example: - -```html live-sample___flexbox1 -<nav> - <ul> - <li><a href="/">Home</a></li> - <li><a href="/about">About Us</a></li> - <li><a href="/products">Our Products</a></li> - <li><a href="/contact">Contact Us</a></li> - </ul> -</nav> -``` - -```css hidden live-sample___flexbox1 -body { - font: 1.2em / 1.5 sans-serif; -} -nav ul { - max-width: 700px; - list-style: none; - padding: 0; - margin: 0; -} -nav a:link, -nav a:visited { - background-color: #4d7298; - border: 2px solid #77a6b6; - border-radius: 0.5em; - color: #fff; - padding: 0.5em; - display: inline-block; - text-decoration: none; -} -``` - -```css live-sample___flexbox1 -nav ul { -} -``` - -{{EmbedLiveSample("flexbox1", "", "240px")}} - -<details> -<summary>Click here to show the solution</summary> - -You can apply `display: flex` and control spacing using the `justify-content` property: - -```css -nav ul { - display: flex; - justify-content: space-between; -} -``` - -</details> - -## Task 2 - -In this task, the list items are all different sizes, but we want them to be displayed as three equal sized columns, no matter what content is in each item. - -Your final result should look like the image below: - -![Flex items laid out as three equal size columns with different amounts of content.](flex-task2.png) - -**Bonus question:** Can you now make the first item twice the size of the other items? - -Try to update the code below to recreate the finished example: - -```html live-sample___flexbox2 -<ul> - <li>I am small</li> - <li>I have more content than the very small item.</li> - <li> - I have lots of content. So much content that I don't know where it is all - going to go. I'm glad that CSS is pretty good at dealing with situations - where we end up with more words than expected! - </li> -</ul> -``` - -```css hidden live-sample___flexbox2 -body { - font: 1.2em / 1.5 sans-serif; -} -ul { - max-width: 700px; - list-style: none; - padding: 0; - margin: 0; -} - -li { - background-color: #4d7298; - border: 2px solid #77a6b6; - border-radius: 0.5em; - color: #fff; - padding: 0.5em; -} -``` - -```css live-sample___flexbox2 -ul { -} - -li { -} -``` - -{{EmbedLiveSample("flexbox2", "", "240px")}} - -<details> -<summary>Click here to show the solution</summary> - -It's best to use shorthands, so in this scenario `flex: 1` is probably the best answer, and so the most optimal result would be: - -```css -ul { - display: flex; -} - -li { - flex: 1; -} -``` - -For the bonus question, add a selector that targets the first element and sets `flex: 2;` (or `flex: 2 0 0;` or `flex-grow: 2`): - -```css -li:first-child { - flex: 2; -} -``` - -</details> - -## Task 3 - -In this task, there are two elements in the HTML below, a `<div>` element with a class of `parent` which contains another `<div>` element with a class of `child`. Use flexbox to center the child inside the parent. There is more than one possible solution here. - -Your final result should look like the image below: - -![A box centered inside another box.](flex-task3.png) - -Try to update the code below to recreate the finished example: - -```html live-sample___flexbox3 -<div class="parent"> - <div class="child">Center me.</div> -</div> -``` - -```css hidden live-sample___flexbox3 -body { - font: 1.2em / 1.5 sans-serif; -} -.parent { - border: 2px solid #77a6b6; - border-radius: 0.5em; - height: 200px; -} - -.child { - background-color: #4d7298; - color: #fff; - padding: 0.5em; - width: 150px; -} -``` - -```css hidden live-sample___flexbox3 -.parent { -} - -.child { -} -``` - -{{EmbedLiveSample("flexbox3", "", "210px")}} - -<details> -<summary>Click here to show the solution</summary> - -It's only necessary to change the parent styles to center an item horizontally and vertically: - -```css -.parent { - display: flex; - justify-content: center; - align-items: center; -} -``` - -</details> - -## Task 4 - -In this task, we want you to arrange these items into rows as in the image below: - -![A set of items displayed as rows.](flex-task4.png) - -Try to update the code below to recreate the finished example: - -```html live-sample___flexbox4 -<ul> - <li>Turnip</li> - <li>greens</li> - <li>yarrow</li> - <li>ricebean</li> - <li>rutabaga</li> - <li>endive</li> - <li>cauliflower</li> - <li>sea lettuce</li> - <li>kohlrabi</li> - <li>amaranth</li> -</ul> -``` - -```css hidden live-sample___flexbox4 -body { - font: 1.2em / 1.5 sans-serif; -} -ul { - width: 450px; - list-style: none; - padding: 0; - margin: 0; -} - -li { - background-color: #4d7298; - border: 2px solid #77a6b6; - border-radius: 0.5em; - color: #fff; - padding: 0.5em; - margin: 0.5em; -} -``` - -```css live-sample___flexbox4 -ul { -} - -li { -} -``` - -{{EmbedLiveSample("flexbox4", "", "260px")}} - -<details> -<summary>Click here to show the solution</summary> - -This task requires an understanding of the `flex-wrap` property to wrap flex lines. In addition, to ensure that you end up with something that looks like the example, you need to set `flex: auto` on the child (or `flex: 1 1 auto;`). - -```css -ul { - display: flex; - flex-wrap: wrap; -} - -li { - flex: auto; -} -``` - -</details> - -## See also - -- [CSS styling basics](/en-US/docs/Learn_web_development/Core/Styling_basics) diff --git a/files/en-us/learn_web_development/core/css_layout/floats/index.md b/files/en-us/learn_web_development/core/css_layout/floats/index.md index 209e12f390cc0f9..87225131b4c13eb 100644 --- a/files/en-us/learn_web_development/core/css_layout/floats/index.md +++ b/files/en-us/learn_web_development/core/css_layout/floats/index.md @@ -2,10 +2,9 @@ title: Floats slug: Learn_web_development/Core/CSS_layout/Floats page-type: learn-module-chapter +sidebar: learnsidebar --- -{{LearnSidebar}} - {{PreviousMenuNext("Learn_web_development/Core/CSS_layout/Introduction", "Learn_web_development/Core/CSS_layout/Positioning", "Learn_web_development/Core/CSS_layout")}} Originally for floating images inside blocks of text, the {{cssxref("float")}} property became one of the most commonly used tools for creating multiple column layouts on webpages. With the advent of flexbox and grid it's now returned to its original purpose, as this article explains. @@ -238,7 +237,7 @@ body { {{EmbedLiveSample('Visualizing_the_float', '100%', 500)}} -The [line boxes](/en-US/docs/Web/CSS/Visual_formatting_model#line_boxes) of our following element have been shortened so the text runs around the float, but due to the float being removed from normal flow the box around the paragraph still remains full width. +The [line boxes](/en-US/docs/Web/CSS/CSS_display/Visual_formatting_model#line_boxes) of our following element have been shortened so the text runs around the float, but due to the float being removed from normal flow the box around the paragraph still remains full width. ## Clearing floats @@ -485,7 +484,7 @@ body { ## Test your skills! -You've reached the end of this article, but can you remember the most important information? You can find some further tests to verify that you've retained this information before you move on — see [Test your skills: Floats](/en-US/docs/Learn_web_development/Core/CSS_layout/Floats_skills). +You've reached the end of this article, but can you remember the most important information? You can find some further tests to verify that you've retained this information before you move on — see [Test your skills: Floats](/en-US/docs/Learn_web_development/Core/CSS_layout/Test_your_skills/Floats). ## Summary diff --git a/files/en-us/learn_web_development/core/css_layout/floats_skills/index.md b/files/en-us/learn_web_development/core/css_layout/floats_skills/index.md deleted file mode 100644 index 66329ab863a5be6..000000000000000 --- a/files/en-us/learn_web_development/core/css_layout/floats_skills/index.md +++ /dev/null @@ -1,217 +0,0 @@ ---- -title: "Test your skills: Floats" -slug: Learn_web_development/Core/CSS_layout/Floats_skills -page-type: learn-module-assessment ---- - -{{LearnSidebar}} - -The aim of this skill test is to assess whether you understand [floats in CSS](/en-US/docs/Learn_web_development/Core/CSS_layout/Floats) using the {{CSSxRef("float")}} and {{CSSxRef("clear")}} properties and values as well as other methods for clearing floats. You will be working through three small tasks that use different elements of the material you have just covered. - -> [!NOTE] -> Click **"Play"** in the code blocks below to edit the examples in the MDN Playground. -> You can also copy the code (click the clipboard icon) and paste it into an online editor such as [CodePen](https://codepen.io/), [JSFiddle](https://jsfiddle.net/), or [Glitch](https://glitch.com/). -> If you get stuck, you can reach out to us in one of our [communication channels](/en-US/docs/MDN/Community/Communication_channels). - -## Task 1 - -In this task, you need to float the two elements with a class of `float1` and `float2` left and right, respectively. The text should then appear between the two boxes, as in the image below: - -![Two blocks displaying left and right of some text.](float-task1.png) - -Try to update the code below to recreate the finished example: - -```html live-sample___float1 -<div class="box"> - <div class="float float1">One</div> - <div class="float float2">Two</div> - <p>The two boxes should float to either side of this text.</p> -</div> -``` - -```css hidden live-sample___float1 -body { - font: 1.2em / 1.5 sans-serif; -} -* { - box-sizing: border-box; -} -.box { - padding: 0.5em; -} -.float { - margin: 15px; - width: 150px; - height: 150px; - border-radius: 5px; - background-color: rebeccapurple; - color: #fff; - padding: 1em; -} -``` - -```css live-sample___float1 -.float1 { -} - -.float2 { -} -``` - -{{EmbedLiveSample("float1", "", "210px")}} - -<details> -<summary>Click here to show the solution</summary> - -You can use `float` for both boxes: - -```css -.float1 { - float: left; -} - -.float2 { - float: right; -} -``` - -</details> - -## Task 2 - -In this task, the element with a class of `float` should be floated left. Then we want the first line of text to display next to that element, but the following line of text (which has a class of `below`) to display underneath it. - -Your final result should look like the image below: - -![A box displayed to the left of a line of text, with some more text below.](float-task2.png) - -Try to update the code below to recreate the finished example: - -```html live-sample___float2 -<div class="box"> - <div class="float">Float</div> - <p>This sentence appears next to the float.</p> - <p class="below">Make this sentence appear below the float.</p> -</div> -``` - -```css hidden live-sample___float2 -body { - font: 1.2em / 1.5 sans-serif; -} -* { - box-sizing: border-box; -} -.box { - padding: 0.5em; -} -.float { - margin: 15px; - width: 150px; - height: 150px; - border-radius: 5px; - background-color: rebeccapurple; - color: #fff; - padding: 1em; -} -``` - -```css live-sample___float2 -.float { -} - -.below { -} -``` - -{{EmbedLiveSample("float2", "", "300px")}} - -<details> -<summary>Click here to show the solution</summary> - -You need to flow the item left, then add `clear: left` to the class for the second paragraph: - -```css -.float { - float: left; -} - -.below { - clear: left; -} -``` - -</details> - -## Task 3 - -In this task, we have a floated element. The box wrapping the float and text is displaying behind the float. Use the most up-to-date method available to cause the box background to extend to below the float, as in the image below: - -![A block displayed to the right of some text both wrapped by a box with a background color.](float-task3.png) - -Try to update the code below to recreate the finished example: - -```html live-sample___float3 -<div class="box"> - <div class="float">Float</div> - <p>This sentence appears next to the float.</p> -</div> -``` - -```css hidden live-sample___float3 -body { - font: 1.2em / 1.5 sans-serif; -} -* { - box-sizing: border-box; -} - -.box { - padding: 0.5em; -} - -.float { - margin: 15px; - width: 150px; - height: 150px; - border-radius: 5px; - background-color: rgb(207 232 220); - padding: 1em; - color: #fff; -} - -.box { - background-color: rebeccapurple; - padding: 10px; - color: #fff; -} -``` - -```css live-sample___float3 -.float { - float: right; -} - -.box { -} -``` - -{{EmbedLiveSample("float3", "", "300px")}} - -<details> -<summary>Click here to show the solution</summary> - -Clear the box underneath the floated item by adding `display: flow-root` to the class for `.box`. -Other methods might be to use `overflow` or a clearfix hack, however the learning materials detail the `flow-root` method as the modern way to achieve this. - -```css -.box { - display: flow-root; -} -``` - -</details> - -## See also - -- [CSS styling basics](/en-US/docs/Learn_web_development/Core/Styling_basics) diff --git a/files/en-us/learn_web_development/core/css_layout/fundamental_layout_comprehension/index.md b/files/en-us/learn_web_development/core/css_layout/fundamental_layout_comprehension/index.md index 9eea1c412854408..d2af28f805f608a 100644 --- a/files/en-us/learn_web_development/core/css_layout/fundamental_layout_comprehension/index.md +++ b/files/en-us/learn_web_development/core/css_layout/fundamental_layout_comprehension/index.md @@ -1,18 +1,18 @@ --- title: "Challenge: Fundamental layout comprehension" +short-title: "Challenge: Fundamental layout" slug: Learn_web_development/Core/CSS_layout/Fundamental_Layout_Comprehension page-type: learn-module-assessment +sidebar: learnsidebar --- -{{LearnSidebar}} - {{PreviousMenuNext("Learn_web_development/Core/CSS_layout/Media_queries", "Learn_web_development/Core/Scripting", "Learn_web_development/Core/CSS_layout")}} If you have worked through this module then you will have already covered the basics of what you need to know to do CSS layout today, and to work with older CSS as well. This task will test some of your knowledge by the way of developing a simple webpage layout using a variety of techniques. ## Starting point -You can download the HTML, CSS, and a set of six images [here](https://github.com/mdn/learning-area/tree/main/css/css-layout/fundamental-layout-comprehension). +You can download the HTML, CSS, and a set of six images [in our learning-area repo](https://github.com/mdn/learning-area/tree/main/css/css-layout/fundamental-layout-comprehension). Save the HTML document and stylesheet into a directory on your computer, and add the images into a folder named `images`. Opening the `index.html` file in a browser should give you a page with basic styling but no layout, which should look something like the image below. diff --git a/files/en-us/learn_web_development/core/css_layout/grid_skills/index.md b/files/en-us/learn_web_development/core/css_layout/grid_skills/index.md deleted file mode 100644 index 9c175eb2b82da2b..000000000000000 --- a/files/en-us/learn_web_development/core/css_layout/grid_skills/index.md +++ /dev/null @@ -1,362 +0,0 @@ ---- -title: "Test your skills: Grid" -slug: Learn_web_development/Core/CSS_layout/Grid_skills -page-type: learn-module-assessment ---- - -{{LearnSidebar}} - -The aim of this skill test is to assess whether you understand how a [grid and grid items](/en-US/docs/Learn_web_development/Core/CSS_layout/Grids) behave. You will be working through several small tasks that use different elements of the material you have just covered. - -> [!NOTE] -> Click **"Play"** in the code blocks below to edit the examples in the MDN Playground. -> You can also copy the code (click the clipboard icon) and paste it into an online editor such as [CodePen](https://codepen.io/), [JSFiddle](https://jsfiddle.net/), or [Glitch](https://glitch.com/). -> If you get stuck, you can reach out to us in one of our [communication channels](/en-US/docs/MDN/Community/Communication_channels). - -## Task 1 - -In this task, you should create a grid into which the four child elements will auto-place. The grid should have three columns sharing the available space equally and a 20 pixel gap between the column and row tracks. After that, try adding more child containers inside the parent container with the class of `grid` and see how they behave by default. - -Your final result should look like the image below: - -![A three column grid with four items placed into it.](grid-task1.png) - -Try to update the code below to recreate the finished example: - -```html live-sample___grid1 -<div class="grid"> - <div>One</div> - <div>Two</div> - <div>Three</div> - <div>Four</div> -</div> -``` - -```css hidden live-sample___grid1 -body { - font: 1.2em / 1.5 sans-serif; -} -.grid > * { - background-color: #4d7298; - border: 2px solid #77a6b6; - border-radius: 0.5em; - color: #fff; - padding: 0.5em; -} -``` - -```css live-sample___grid1 -.grid { -} -``` - -{{EmbedLiveSample("grid1", "", "200px")}} - -<details> -<summary>Click here to show the solution</summary> - -Create a grid using `display: grid` with three columns using `grid-template-columns` and a `gap` between the items: - -```css -.grid { - display: grid; - grid-template-columns: 1fr 1fr 1fr; - gap: 20px; -} -``` - -</details> - -## Task 2 - -In this task, we already have a grid defined. By editing the CSS rules for the two child elements, cause them to span over several grid tracks each. The second item should overlay the first as in the image below: - -![A box with two items inside one overlaying the other.](grid-task2.png) - -**Bonus question:** Can you now cause the first item to display on top without changing the order of items in the source? - -Try to update the code below to recreate the finished example: - -```html live-sample___grid2 -<div class="grid"> - <div class="item1">One</div> - <div class="item2">Two</div> -</div> -``` - -```css hidden live-sample___grid2 -body { - font: 1.2em / 1.5 sans-serif; -} -.grid > * { - border-radius: 0.5em; - color: #fff; - padding: 0.5em; -} - -.item1 { - background-color: rgb(74 102 112 / 70%); - border: 5px solid rgb(74 102 112 / 100%); -} - -.item2 { - background-color: rgb(214 162 173 / 70%); - border: 5px solid rgb(214 162 173 / 100%); -} -``` - -```css live-sample___grid2 -.grid { - display: grid; - grid-template-columns: 1fr 1fr 1fr 1fr; - grid-template-rows: 100px 100px 100px; - gap: 10px; -} - -.item1 { -} - -.item2 { -} -``` - -{{EmbedLiveSample("grid2", "", "340px")}} - -<details> -<summary>Click here to show the solution</summary> - -It is possible to layer items by way of them occupying the same grid cells. -One option is to use the shorthands below, however it would be correct to use the longhand `grid-row-start` for example. - -```css -.item1 { - grid-column: 1 / 4; - grid-row: 1 / 3; -} - -.item2 { - grid-column: 2 / 5; - grid-row: 2 / 4; -} -``` - -For the bonus question, one way of achieving this would be to use `order`, which we've encountered in the flexbox tutorial. - -```css -.item1 { - order: 1; -} -``` - -Another valid solution is to use `z-index`: - -```css -.item1 { - z-index: 1; -} -``` - -</details> - -## Task 3 - -In this task, there are four direct children in this grid. The starting point has them displayed using auto-placement. Use the grid-area and grid-template-areas properties to lay the items out as shown in the image below: - -![Four items displayed in a grid.](grid-task3.png) - -Try to update the code below to recreate the finished example: - -```html live-sample___grid3 -<div class="grid"> - <div class="one">One</div> - <div class="two">Two</div> - <div class="three">Three</div> - <div class="four">Four</div> -</div> -``` - -```css hidden live-sample___grid3 -body { - font: 1.2em / 1.5 sans-serif; -} -.grid > * { - background-color: #4d7298; - border: 2px solid #77a6b6; - border-radius: 0.5em; - color: #fff; - padding: 0.5em; -} -``` - -```css live-sample___grid3 -.grid { - display: grid; - grid-template-columns: 1fr 2fr; - gap: 10px; -} -``` - -{{EmbedLiveSample("grid3", "", "200px")}} - -<details> -<summary>Click here to show the solution</summary> - -Each part of the layout needs a name using the `grid-area` property and `grid-template-areas` to lay them out. Possible areas of confusion would be not realizing you should place a `.` to leave a cell empty, or that you should repeat the name to cause an element to span more than one track: - -```css -.grid { - display: grid; - gap: 20px; - grid-template-columns: 1fr 2fr; - grid-template-areas: - "aa aa" - "bb cc" - ". dd"; -} - -.one { - grid-area: aa; -} - -.two { - grid-area: bb; -} - -.three { - grid-area: cc; -} - -.four { - grid-area: dd; -} -``` - -</details> - -## Task 4 - -In this task, you will need to use both grid layout and flexbox to recreate the example as seen in the image below. The gap between the column and row tracks should be 10px. You do not need to make any changes to the HTML in order to achieve this. - -![Two rows of cards, each with an image and a set of tags.](grid-task4.png) - -Try to update the code below to recreate the finished example: - -```html live-sample___grid4 -<div class="container"> - <div class="card"> - <img - alt="a single red balloon" - src="https://mdn.github.io/shared-assets/images/examples/balloons1.jpg" /> - <ul class="tags"> - <li>balloon</li> - <li>red</li> - <li>sky</li> - <li>blue</li> - <li>Hot air balloon</li> - </ul> - </div> - <div class="card"> - <img - alt="balloons over some houses" - src="https://mdn.github.io/shared-assets/images/examples/balloons2.jpg" /> - <ul class="tags"> - <li>balloons</li> - <li>houses</li> - <li>train</li> - <li>harborside</li> - </ul> - </div> - <div class="card"> - <img - alt="close-up of balloons inflating" - src="https://mdn.github.io/shared-assets/images/examples/balloons3.jpg" /> - <ul class="tags"> - <li>balloons</li> - <li>inflating</li> - <li>green</li> - <li>blue</li> - </ul> - </div> - <div class="card"> - <img - alt="a balloon in the sun" - src="https://mdn.github.io/shared-assets/images/examples/balloons4.jpg" /> - <ul class="tags"> - <li>balloon</li> - <li>sun</li> - <li>sky</li> - <li>summer</li> - <li>bright</li> - </ul> - </div> -</div> -``` - -```css hidden live-sample___grid4 -body { - font: 1.2em / 1.5 sans-serif; -} -.card { - display: grid; - grid-template-rows: 200px min-content; -} - -.card > img { - width: 100%; - height: 100%; - object-fit: cover; -} - -.tags { - margin: 0; - padding: 0; - list-style: none; -} - -.tags > * { - background-color: #999; - color: #fff; - padding: 0.2em 0.8em; - border-radius: 0.2em; - font-size: 80%; - margin: 5px; -} -``` - -```css live-sample___grid4 -.container { -} - -.tags { -} -``` - -{{EmbedLiveSample("grid4", "", "400px")}} - -<details> -<summary>Click here to show the solution</summary> - -The container will need to be a grid layout, as we have alignment in rows and columns - two-dimensional. -The `<ul>` needs to be a flex container as tags (`<li>` elements) are not lined up in columns, only in rows and they are centered in the space with the alignment property `justify-content` set to `center`. - -You may try to use flexbox on the container and restrict the cards with percentage values. You may also try to make the items into a grid layout in which case, note that the items are not aligned in two dimensions so flexbox isn't the best choice. - -```css -.container { - display: grid; - gap: 10px; - grid-template-columns: 1fr 1fr 1fr; -} - -.tags { - display: flex; - flex-wrap: wrap; - justify-content: center; -} -``` - -</details> - -## See also - -- [CSS styling basics](/en-US/docs/Learn_web_development/Core/Styling_basics) diff --git a/files/en-us/learn_web_development/core/css_layout/grids/index.md b/files/en-us/learn_web_development/core/css_layout/grids/index.md index 194afca2925f9b9..ff44f4ecb838e9d 100644 --- a/files/en-us/learn_web_development/core/css_layout/grids/index.md +++ b/files/en-us/learn_web_development/core/css_layout/grids/index.md @@ -2,10 +2,9 @@ title: CSS grid layout slug: Learn_web_development/Core/CSS_layout/Grids page-type: learn-module-chapter +sidebar: learnsidebar --- -{{LearnSidebar}} - {{PreviousMenuNext("Learn_web_development/Core/CSS_layout/Flexbox", "Learn_web_development/Core/CSS_layout/Responsive_design", "Learn_web_development/Core/CSS_layout")}} CSS grid layout is a two-dimensional layout system for the web. It lets you organize content into rows and columns and offers many features to simplify the creation of complex layouts. This article will explain all you need to know to get started with grid layout. @@ -71,7 +70,7 @@ Let's try out grid layouts, here is an example with a container, which has some ```css live-sample___simple-grid_0 body { - font: sans-serif; + font-family: sans-serif; } .container > div { border-radius: 5px; @@ -99,7 +98,7 @@ Similar to how you define flexbox, you define a grid layout by setting the value ```css hidden live-sample___simple-grid_1 body { - font: sans-serif; + font-family: sans-serif; } .container > div { border-radius: 5px; @@ -135,7 +134,7 @@ To see something that looks more grid-like, we'll need to add some columns to th ```css hidden live-sample___simple-grid_2 body { - font: sans-serif; + font-family: sans-serif; } .container > div { border-radius: 5px; @@ -174,7 +173,7 @@ In addition to creating grids using lengths and percentages, we can use [`fr`](/ ```css hidden live-sample___grid-fr-unit_0 body { - font: sans-serif; + font-family: sans-serif; } .container > div { border-radius: 5px; @@ -195,7 +194,9 @@ Here we change the track listing to the following definition, creating three `1f {{EmbedLiveSample('grid-fr-unit_0', '100%', "130") }} -You now have flexible tracks. The `fr` unit distributes space proportionally. You can specify different positive values for your tracks like so: +You now have flexible tracks. +The `fr` unit distributes space proportionally, so you can specify different positive values for your tracks. +Change your track listing to the following definition, creating one `2fr` track and two `1fr` tracks: ```html hidden live-sample___grid-fr-unit_1 <div class="container"> @@ -211,7 +212,7 @@ You now have flexible tracks. The `fr` unit distributes space proportionally. Yo ```css hidden live-sample___grid-fr-unit_1 body { - font: sans-serif; + font-family: sans-serif; } .container > div { border-radius: 5px; @@ -221,8 +222,6 @@ body { } ``` -Now change your track listing to the following definition, creating one `2fr` two `1fr` tracks: - ```css live-sample___grid-fr-unit_1 .container { display: grid; @@ -259,7 +258,7 @@ To create gaps between tracks, we use the properties: ```css hidden live-sample___grid-gap body { - font: sans-serif; + font-family: sans-serif; } .container > div { border-radius: 5px; @@ -269,7 +268,7 @@ body { } ``` -Here we add the `gap` property to create gaps between the tracks with a value of `20px: +Here we add the `gap` property to create gaps between the tracks with a value of `20px`: ```css live-sample___grid-gap .container { @@ -302,7 +301,7 @@ Here we change the track listing to the following: ```css hidden live-sample___grid-repeat body { - font: sans-serif; + font-family: sans-serif; } .container > div { border-radius: 5px; @@ -348,7 +347,7 @@ By default, tracks created in the implicit grid are `auto` sized, which in gener ```css hidden live-sample___grid-auto body { - font: sans-serif; + font-family: sans-serif; } .container > div { border-radius: 5px; @@ -389,7 +388,7 @@ The {{cssxref("minmax", "minmax()")}} function lets us set a minimum and maximum ```css hidden live-sample___grid-minmax_0 body { - font: sans-serif; + font-family: sans-serif; } .container > div { border-radius: 5px; @@ -430,7 +429,7 @@ We can combine some of the lessons we've learned about track listing, repeat not ```css hidden live-sample___grid-minmax_1 body { - font: sans-serif; + font-family: sans-serif; } .container > div { border-radius: 5px; @@ -505,7 +504,7 @@ aside { } ``` -With out the placement defined, you can see that _auto-placement_ is placing each item into its own cell in the grid. The {{htmlelement("header")}} is taking up `1fr` (one quarter) and the {{htmlelement("main")}} is taking up `3fr` (three quarters). +Without the placement defined, you can see that _auto-placement_ is placing each item into its own cell in the grid. The {{htmlelement("header")}} is taking up `1fr` (one quarter) and the {{htmlelement("main")}} is taking up `3fr` (three quarters). {{EmbedLiveSample('grid-placement_0', '100%', "230") }} @@ -862,7 +861,7 @@ If you use the [Firefox grid inspector](https://firefox-source-docs.mozilla.org/ ## Test your skills! -You've reached the end of this article, but can you remember the most important information? You can find some further tests to verify that you've retained this information before you move on — see [Test your skills: Grid](/en-US/docs/Learn_web_development/Core/CSS_layout/Grid_skills). +You've reached the end of this article, but can you remember the most important information? You can find some further tests to verify that you've retained this information before you move on — see [Test your skills: Grid](/en-US/docs/Learn_web_development/Core/CSS_layout/Test_your_skills/Grid). ## Summary diff --git a/files/en-us/learn_web_development/core/css_layout/index.md b/files/en-us/learn_web_development/core/css_layout/index.md index 11b402619fb8cf2..984bbd88d0b7591 100644 --- a/files/en-us/learn_web_development/core/css_layout/index.md +++ b/files/en-us/learn_web_development/core/css_layout/index.md @@ -2,10 +2,9 @@ title: CSS layout slug: Learn_web_development/Core/CSS_layout page-type: learn-module +sidebar: learnsidebar --- -{{LearnSidebar}} - {{NextMenu("Learn_web_development/Core/CSS_layout/Introduction", "Learn_web_development/Core")}} In previous modules we looked at how to style and manipulate the boxes that your content sits inside. Now it's time to look at how to correctly lay out your boxes in relation to one another, and the browser viewport. This module looks at floats, positioning, other modern layout tools, and building responsive designs that will adapt to different devices, screen sizes, and resolutions. @@ -43,7 +42,7 @@ These tutorials are not part of the learning pathway, but they are interesting n - [Multiple-column layout](/en-US/docs/Learn_web_development/Core/CSS_layout/Multiple-column_Layout) - : The multiple-column layout specification provides you with a method for laying content out in columns, as you might see in a newspaper. This article explains how to use this feature. - [Legacy layout methods](/en-US/docs/Learn_web_development/Core/CSS_layout/Legacy_Layout_Methods) - - : Grid systems are a very common feature used in CSS layouts, and before CSS grid layout they tended to be implemented using floats or other layout features. You imagine your layout as a set number of columns (e.g. 4, 6, or 12), and then fit your content columns inside these imaginary columns. In this article we'll explore how these older methods work, in order that you understand how they were used if you work on an older project. + - : Grid systems are a very common feature used in CSS layouts, and before CSS grid layout they tended to be implemented using floats or other layout features. You imagine your layout as a set number of columns (e.g., 4, 6, or 12), and then fit your content columns inside these imaginary columns. In this article we'll explore how these older methods work, in order that you understand how they were used if you work on an older project. - [Supporting older browsers](/en-US/docs/Learn_web_development/Core/CSS_layout/Supporting_Older_Browsers) - : Visitors to your website may include users who either use older browsers or use browsers that do not support the CSS features you've implemented. This is a common scenario on the web, where new features are continuously being added to CSS. Browsers differ in their support for these features because different browsers tend to prioritize implementing different features. This article explains how you as a web developer can use modern web techniques to ensure that your website remains accessible to users with older technology. diff --git a/files/en-us/learn_web_development/core/css_layout/introduction/index.md b/files/en-us/learn_web_development/core/css_layout/introduction/index.md index 46fdbe23a5d40cc..4baf5f94d95eac5 100644 --- a/files/en-us/learn_web_development/core/css_layout/introduction/index.md +++ b/files/en-us/learn_web_development/core/css_layout/introduction/index.md @@ -1,11 +1,11 @@ --- title: Introduction to CSS layout +short-title: Introduction slug: Learn_web_development/Core/CSS_layout/Introduction page-type: learn-module-chapter +sidebar: learnsidebar --- -{{LearnSidebar}} - {{NextMenu("Learn_web_development/Core/CSS_layout/Floats", "Learn_web_development/Core/CSS_layout")}} This lesson recaps some of the CSS layout features we've already touched upon in previous modules, such as different {{cssxref("display")}} values, as well as introducing some of the concepts we'll be covering throughout this module. It also covers the concept of normal flow in depth. @@ -26,7 +26,7 @@ This lesson recaps some of the CSS layout features we've already touched upon in <th scope="row">Learning outcomes:</th> <td> <ul> - <li>Recognise the methods used to implement modern page layouts.</li> + <li>Recognize the methods used to implement modern page layouts.</li> <li>Understand that normal flow is the default way a browser lays out block and inline content.</li> <li>Know that properties such as <code>display</code>, <code>float</code>, and <code>position</code> are intended to change how the browser lays out content.</li> </ul> diff --git a/files/en-us/learn_web_development/core/css_layout/legacy_layout_methods/index.md b/files/en-us/learn_web_development/core/css_layout/legacy_layout_methods/index.md index 4d5c122aac8029d..24708a065de872c 100644 --- a/files/en-us/learn_web_development/core/css_layout/legacy_layout_methods/index.md +++ b/files/en-us/learn_web_development/core/css_layout/legacy_layout_methods/index.md @@ -2,11 +2,10 @@ title: Legacy layout methods slug: Learn_web_development/Core/CSS_layout/Legacy_Layout_Methods page-type: learn-module-chapter +sidebar: learnsidebar --- -{{LearnSidebar}} - -Grid systems are a very common feature used in CSS layouts, and before CSS grid layout they tended to be implemented using floats or other layout features. You imagine your layout as a set number of columns (e.g. 4, 6, or 12), and then fit your content columns inside these imaginary columns. In this article we'll explore how these older methods work, in order that you understand how they were used if you work on an older project. +Grid systems are a very common feature used in CSS layouts, and before CSS grid layout they tended to be implemented using floats or other layout features. You imagine your layout as a set number of columns (e.g., 4, 6, or 12), and then fit your content columns inside these imaginary columns. In this article we'll explore how these older methods work, in order that you understand how they were used if you work on an older project. <table> <tbody> diff --git a/files/en-us/learn_web_development/core/css_layout/media_queries/index.md b/files/en-us/learn_web_development/core/css_layout/media_queries/index.md index a217f2670a589c8..24c189a2e6a50c5 100644 --- a/files/en-us/learn_web_development/core/css_layout/media_queries/index.md +++ b/files/en-us/learn_web_development/core/css_layout/media_queries/index.md @@ -1,11 +1,11 @@ --- title: Media query fundamentals +short-title: Media queries slug: Learn_web_development/Core/CSS_layout/Media_queries page-type: learn-module-chapter +sidebar: learnsidebar --- -{{learnsidebar}} - {{PreviousMenuNext("Learn_web_development/Core/CSS_layout/Responsive_design", "Learn_web_development/Core/CSS_layout/Fundamental_layout_comprehension", "Learn_web_development/Core/CSS_layout")}} The **CSS Media Query** gives you a way to apply CSS only when the browser and device environment matches a rule that you specify, for example "viewport is wider than 480 pixels". Media queries are a key part of responsive web design, as they allow you to create different layouts depending on the size of the viewport, but they can also be used to detect other things about the environment your site is running on, for example whether the user is using a touchscreen rather than a mouse. @@ -52,7 +52,7 @@ The simplest media query syntax looks like this: It consists of: -- A media type, which tells the browser what kind of media this code is for (e.g. print, or screen). +- A media type, which tells the browser what kind of media this code is for (e.g., print, or screen). - A media expression, which is a rule, or test that must be passed for the contained CSS to be applied. - A set of CSS rules that will be applied if the test passes and the media type is correct. @@ -544,13 +544,13 @@ If you look at the HTML source in the above example, you'll see the following el <meta name="viewport" content="width=device-width,initial-scale=1" /> ``` -This is the [viewport meta tag](/en-US/docs/Web/HTML/Viewport_meta_tag) — it exists as a way to control how mobile browsers render content. This is needed because by default, most mobile browsers lie about their viewport width. Non-responsive sites commonly look really bad when rendered in a narrow viewport, so mobile browsers usually render the site with a viewport width wider than the real device width by default (usually 980 pixels), and then shrink the rendered result so that it fits in the display. +This is the [viewport meta tag](/en-US/docs/Web/HTML/Guides/Viewport_meta_element) — it exists as a way to control how mobile browsers render content. This is needed because by default, most mobile browsers lie about their viewport width. Non-responsive sites commonly look really bad when rendered in a narrow viewport, so mobile browsers usually render the site with a viewport width wider than the real device width by default (usually 980 pixels), and then shrink the rendered result so that it fits in the display. This is all well and good, but it means that responsive sites are not going to work as expected. If the viewport width is reported as 980 pixels, then mobile layouts (for example created using a media query of `@media screen and (max-width: 600px) { }`) are not going to render as expected. To remedy this, including a viewport meta tag like the one above on your page tells the browser "don't render the content with a 980 pixel viewport — render it using the real device width instead, and set a default initial scale level for better consistency." The media queries will then kick in as expected. -There are a number of other options you can put inside the `content` attribute of the viewport meta tag — see [Using the viewport meta tag to control layout on mobile browsers](/en-US/docs/Web/HTML/Viewport_meta_tag) for more details. +There are a number of other options you can put inside the `content` attribute of the viewport meta tag — see [Using the viewport meta tag to control layout on mobile browsers](/en-US/docs/Web/HTML/Guides/Viewport_meta_element) for more details. ## Do you really need a media query? @@ -608,7 +608,7 @@ Make the screen wider and narrower to see the number of column tracks change. Th ## Test your skills -You've reached the end of this article, but can you remember the most important information? You can find a test to verify that you've retained this information before you move on — see [Test your skills: Responsive web design and media queries](/en-US/docs/Learn_web_development/Core/CSS_layout/rwd_skills). +You've reached the end of this article, but can you remember the most important information? You can find a test to verify that you've retained this information before you move on — see [Test your skills: Responsive web design and media queries](/en-US/docs/Learn_web_development/Core/CSS_layout/Test_your_skills/Responsive_design). ## Summary diff --git a/files/en-us/learn_web_development/core/css_layout/multicol_skills/index.md b/files/en-us/learn_web_development/core/css_layout/multicol_skills/index.md deleted file mode 100644 index 73e047b983293d7..000000000000000 --- a/files/en-us/learn_web_development/core/css_layout/multicol_skills/index.md +++ /dev/null @@ -1,233 +0,0 @@ ---- -title: "Test your skills: Multicol" -slug: Learn_web_development/Core/CSS_layout/Multicol_skills -page-type: learn-module-assessment ---- - -{{LearnSidebar}} - -The aim of this skill test is to assess whether you understand [CSS multiple-column layout](/en-US/docs/Learn_web_development/Core/CSS_layout/Multiple-column_Layout), including the {{CSSxRef("column-count")}}, {{CSSxRef("column-width")}}, {{CSSxRef("column-gap")}}, {{CSSxRef("column-span")}} and {{CSSxRef("column-rule")}} properties and values. You will be working through three small tasks that use different elements of the material you have just covered. - -> [!NOTE] -> Click **"Play"** in the code blocks below to edit the examples in the MDN Playground. -> You can also copy the code (click the clipboard icon) and paste it into an online editor such as [CodePen](https://codepen.io/), [JSFiddle](https://jsfiddle.net/), or [Glitch](https://glitch.com/). -> If you get stuck, you can reach out to us in one of our [communication channels](/en-US/docs/MDN/Community/Communication_channels). - -## Task 1 - -In this task, we want you to create three columns, with a 50px gap between each column. - -Your final result should look like the image below: - -![Three columns of text](multicol-task1.png) - -Try updating the live code below to recreate the finished example: - -```html live-sample___multicol1 -<div class="container"> - <p> - Veggies es bonus vobis, proinde vos postulo essum magis kohlrabi welsh onion - daikon amaranth tatsoi tomatillo melon azuki bean garlic. - </p> - - <p> - Gumbo beet greens corn soko endive gumbo gourd. Parsley shallot courgette - tatsoi pea sprouts fava bean collard greens dandelion okra wakame tomato. - Dandelion cucumber earthnut pea peanut soko zucchini. - </p> - - <p> - Turnip greens yarrow ricebean rutabaga endive cauliflower sea lettuce - kohlrabi amaranth water spinach avocado daikon napa cabbage asparagus winter - purslane kale. Celery potato scallion desert raisin horseradish spinach - carrot soko. Lotus root water spinach fennel kombu maize bamboo shoot green - bean swiss chard seakale pumpkin onion chickpea gram corn pea. - </p> -</div> -``` - -```css live-sample___multicol1 -body { - font: 1.2em / 1.5 sans-serif; -} -.container { -} -``` - -{{EmbedLiveSample("multicol1", "", "300px")}} - -<details> -<summary>Click here to show the solution</summary> - -For this task, you need to use `column-count` and `column-gap`: - -```css -.container { - column-count: 3; - column-gap: 50px; -} -``` - -</details> - -## Task 2 - -In this task, we want you to create columns which have a minimum width of 200px. Then, add a 5px grey rule between each column, ensuring there is 10px of space between the edge of the rule and the column content. - -Your final result should look like the image below: - -![Three columns of text with a grey rule between them.](multicol-task2.png) - -Try updating the live code below to recreate the finished example: - -```html live-sample___multicol2 -<div class="container"> - <p> - Veggies es bonus vobis, proinde vos postulo essum magis kohlrabi welsh onion - daikon amaranth tatsoi tomatillo melon azuki bean garlic. - </p> - - <p> - Gumbo beet greens corn soko endive gumbo gourd. Parsley shallot courgette - tatsoi pea sprouts fava bean collard greens dandelion okra wakame tomato. - Dandelion cucumber earthnut pea peanut soko zucchini. - </p> - - <p> - Turnip greens yarrow ricebean rutabaga endive cauliflower sea lettuce - kohlrabi amaranth water spinach avocado daikon napa cabbage asparagus winter - purslane kale. Celery potato scallion desert raisin horseradish spinach - carrot soko. Lotus root water spinach fennel kombu maize bamboo shoot green - bean swiss chard seakale pumpkin onion chickpea gram corn pea. - </p> -</div> -``` - -```css live-sample___multicol2 -body { - font: 1.2em / 1.5 sans-serif; -} -.container { -} -``` - -{{EmbedLiveSample("multicol2", "", "300px")}} - -<details> -<summary>Click here to show the solution</summary> - -You will need to use the `column-width` and `column-rule` properties. -You could use the longhand `column-rule-*` properties instead of the shorthand, though there is no benefit to doing so. -The key thing with the use of `column-gap` is that you have understood that the rule does not add 5px of space to the gap. To have 10px either side of the rule they need a 25px gap as the rule is laid over it. - -```css -.container { - column-width: 200px; - column-rule: 5px solid #ccc; - column-gap: 25px; -} -``` - -</details> - -## Task 3 - -In this task, we want you to cause the element containing the heading and subheading to span across all columns so it looks like the image below: - -![Three columns of text with a heading and subheading spanning all three in the middle.](multicol-task3.png) - -Try updating the live code below to recreate the finished example: - -```html live-sample___multicol3 -<div class="container"> - <p> - Veggies es bonus vobis, proinde vos postulo essum magis kohlrabi welsh onion - daikon amaranth tatsoi tomatillo melon azuki bean garlic. - </p> - <p> - Gumbo beet greens corn soko endive gumbo gourd. Parsley shallot courgette - tatsoi pea sprouts fava bean collard greens dandelion okra wakame tomato. - Dandelion cucumber earthnut pea peanut soko zucchini. - </p> - <div class="box"> - <h2>I am a level 2 heading</h2> - <div class="subhead">Lotus root water spinach fennel</div> - </div> - <p> - Turnip greens yarrow ricebean rutabaga endive cauliflower sea lettuce - kohlrabi amaranth water spinach avocado daikon napa cabbage asparagus winter - purslane kale. Celery potato scallion desert raisin horseradish spinach - carrot soko. Lotus root water spinach fennel kombu maize bamboo shoot green - bean swiss chard seakale pumpkin onion chickpea gram corn pea. - </p> -</div> -``` - -```css hidden live-sample___multicol3 -body { - font: 1.2em / 1.5 sans-serif; -} -* { - box-sizing: border-box; -} - -.box { - text-align: center; - margin: 1em 0; -} - -.box h2 { - margin: 0; - display: grid; - grid-template-columns: 1fr auto 1fr; - column-gap: 0.5em; - align-items: center; -} - -.box h2::before { - content: ""; - border-bottom: 5px dotted #ccc; -} - -.box h2::after { - content: ""; - border-bottom: 5px dotted #ccc; -} - -.subhead { - font-style: italic; -} -``` - -```css live-sample___multicol3 -.container { - column-count: 3; -} - -.box { -} - -h2 { -} -``` - -{{EmbedLiveSample("multicol3", "", "400px")}} - -<details> -<summary>Click here to show the solution</summary> - -In this task, we test for understanding of the `column-span` property. -All you need to do is set the element with a class of `.box` to `column-span: all`. -This is mostly a task of checking that you select the right element. - -```css -.box { - column-span: all; -} -``` - -</details> - -## See also - -- [CSS styling basics](/en-US/docs/Learn_web_development/Core/Styling_basics) diff --git a/files/en-us/learn_web_development/core/css_layout/multiple-column_layout/index.md b/files/en-us/learn_web_development/core/css_layout/multiple-column_layout/index.md index 9ee9bb8f43323b1..6c0b8d730cde0d1 100644 --- a/files/en-us/learn_web_development/core/css_layout/multiple-column_layout/index.md +++ b/files/en-us/learn_web_development/core/css_layout/multiple-column_layout/index.md @@ -2,10 +2,9 @@ title: Multiple-column layout slug: Learn_web_development/Core/CSS_layout/Multiple-column_Layout page-type: learn-module-chapter +sidebar: learnsidebar --- -{{LearnSidebar}} - The multiple-column layout specification provides you with a method for laying content out in columns, as you might see in a newspaper. This article explains how to use this feature. <table> @@ -246,18 +245,32 @@ h2 { <div class="container"> <h1>Simple multicol example</h1> - <p>Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nulla luctus aliquam dolor, eu lacinia lorem placerat vulputate. - Duis felis orci, pulvinar id metus ut, rutrum luctus orci. Cras porttitor imperdiet nunc, at ultricies tellus laoreet sit amet. Sed auctor cursus massa at porta. Integer ligula ipsum, tristique sit amet orci vel, viverra egestas ligula. + <p> + Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nulla luctus + aliquam dolor, eu lacinia lorem placerat vulputate. Duis felis orci, + pulvinar id metus ut, rutrum luctus orci. Cras porttitor imperdiet nunc, at + ultricies tellus laoreet sit amet. Sed auctor cursus massa at porta. Integer + ligula ipsum, tristique sit amet orci vel, viverra egestas ligula. + </p> <h2>Spanning subhead</h2> - Curabitur vehicula tellus neque, ac ornare ex malesuada et. In vitae convallis lacus. Aliquam erat volutpat. Suspendisse - ac imperdiet turpis. Aenean finibus sollicitudin eros pharetra congue. Duis ornare egestas augue ut luctus. Proin blandit - quam nec lacus varius commodo et a urna. Ut id ornare felis, eget fermentum sapien.</p> - - <p>Nam vulputate diam nec tempor bibendum. Donec luctus augue eget malesuada ultrices. Phasellus turpis est, posuere sit amet dapibus ut, facilisis sed est. Nam id risus quis ante semper consectetur eget aliquam lorem. Vivamus tristique - elit dolor, sed pretium metus suscipit vel. Mauris ultricies lectus sed lobortis finibus. Vivamus eu urna eget velit - cursus viverra quis vestibulum sem. Aliquam tincidunt eget purus in interdum. Cum sociis natoque penatibus et magnis - dis parturient montes, nascetur ridiculus mus.</p> + <p> + Curabitur vehicula tellus neque, ac ornare ex malesuada et. In vitae + convallis lacus. Aliquam erat volutpat. Suspendisse ac imperdiet turpis. + Aenean finibus sollicitudin eros pharetra congue. Duis ornare egestas augue + ut luctus. Proin blandit quam nec lacus varius commodo et a urna. Ut id + ornare felis, eget fermentum sapien. + </p> + + <p> + Nam vulputate diam nec tempor bibendum. Donec luctus augue eget malesuada + ultrices. Phasellus turpis est, posuere sit amet dapibus ut, facilisis sed + est. Nam id risus quis ante semper consectetur eget aliquam lorem. Vivamus + tristique elit dolor, sed pretium metus suscipit vel. Mauris ultricies + lectus sed lobortis finibus. Vivamus eu urna eget velit cursus viverra quis + vestibulum sem. Aliquam tincidunt eget purus in interdum. Cum sociis natoque + penatibus et magnis dis parturient montes, nascetur ridiculus mus. + </p> </div> ``` @@ -498,7 +511,7 @@ body { ## Test your skills! -You've reached the end of this article, but can you remember the most important information? You can find some further tests to verify that you've retained this information before you move on — see [Test your skills: Multicol](/en-US/docs/Learn_web_development/Core/CSS_layout/Multicol_skills). +You've reached the end of this article, but can you remember the most important information? You can find some further tests to verify that you've retained this information before you move on — see [Test your skills: Multicol](/en-US/docs/Learn_web_development/Core/CSS_layout/Test_your_skills/Multicolumn). ## Summary diff --git a/files/en-us/learn_web_development/core/css_layout/position_skills/index.md b/files/en-us/learn_web_development/core/css_layout/position_skills/index.md deleted file mode 100644 index 685621c01c26555..000000000000000 --- a/files/en-us/learn_web_development/core/css_layout/position_skills/index.md +++ /dev/null @@ -1,191 +0,0 @@ ---- -title: "Test your skills: Positioning" -slug: Learn_web_development/Core/CSS_layout/Position_skills -page-type: learn-module-assessment ---- - -{{LearnSidebar}} - -The aim of this skill test is to assess whether you understand [positioning in CSS](/en-US/docs/Learn_web_development/Core/CSS_layout/Positioning) using the CSS {{CSSxRef("position")}} property and values. You will be working through two small tasks that use different elements of the material you have just covered. - -> [!NOTE] -> Click **"Play"** in the code blocks below to edit the examples in the MDN Playground. -> You can also copy the code (click the clipboard icon) and paste it into an online editor such as [CodePen](https://codepen.io/), [JSFiddle](https://jsfiddle.net/), or [Glitch](https://glitch.com/). -> If you get stuck, you can reach out to us in one of our [communication channels](/en-US/docs/MDN/Community/Communication_channels). - -## Task 1 - -In this task, we want you to position the item with a class of `target` to the top and right of the container, which has the 5px grey border. - -Your final result should look like the image below: - -![The green box is at the top right of a container with a grey border.](position-task1.png) - -**Bonus question:** Can you change the target to display underneath the text? - -Try to update the code below to recreate the finished example: - -```html live-sample___position1 -<div class="container"> - <p> - Veggies es bonus vobis, proinde vos postulo essum magis kohlrabi welsh onion - daikon amaranth tatsoi tomatillo melon azuki bean garlic. - </p> - <div class="target">Target</div> - <p> - Gumbo beet greens corn soko endive gumbo gourd. Parsley shallot courgette - tatsoi pea sprouts fava bean collard greens dandelion okra wakame tomato. - Dandelion cucumber earthnut pea peanut soko zucchini. - </p> -</div> -``` - -```css hidden live-sample___position1 -body { - font: 1.2em / 1.5 sans-serif; -} -* { - box-sizing: border-box; -} - -.container { - padding: 0.5em; - border: 5px solid #ccc; -} - -.target { - width: 150px; - height: 150px; - border-radius: 5px; - background-color: #663398; - padding: 1em; - color: white; -} -``` - -```css live-sample___position1 -.container { -} - -.target { -} -``` - -{{EmbedLiveSample("position1", "", "400px")}} - -<details> -<summary>Click here to show the solution</summary> - -This requires `position: relative` and `position: absolute` and understanding how they relate to each other in terms of relative positioning creating a new positioning context. -A likely issue could be that you add `position: absolute` to the child without applying `position: relative` to the container. In that case, the target will end up being positioned according to the viewport. - -```css -.container { - position: relative; -} - -.target { - position: absolute; - top: 0; - right: 0; -} -``` - -For the bonus question, you need to add a negative `z-index` to the target, for example `z-index: -2`. - -</details> - -## Task 2 - -In this task, if you scroll the box in the example below, the sidebar scrolls with the content. Change it so that the sidebar (`<div class="sidebar">`) stays in place and only the content scrolls. - -![The content is scrolled but the sidebar has stayed in place.](position-task2.png) - -Try to update the code below to recreate the finished example: - -```html live-sample___position2 -<div class="container"> - <div class="sidebar"> - <p> - This is the sidebar. It should remain in position as the content scrolls. - </p> - </div> - <div class="content"> - <p> - Veggies es bonus vobis, proinde vos postulo essum magis kohlrabi welsh - onion daikon amaranth tatsoi tomatillo melon azuki bean garlic. - </p> - <p> - Gumbo beet greens corn soko endive gumbo gourd. Parsley shallot courgette - tatsoi pea sprouts fava bean collard greens dandelion okra wakame tomato. - Dandelion cucumber earthnut pea peanut soko zucchini. - </p> - <p> - Turnip greens yarrow ricebean rutabaga endive cauliflower sea lettuce - kohlrabi amaranth water spinach avocado daikon napa cabbage asparagus - winter purslane kale. Celery potato scallion desert raisin horseradish - spinach carrot soko. Lotus root water spinach fennel kombu maize bamboo - shoot green bean swiss chard seakale pumpkin onion chickpea gram corn pea. - Brussels sprout coriander water chestnut gourd swiss chard wakame kohlrabi - beetroot carrot watercress. Corn amaranth salsify bunya nuts nori azuki - bean chickweed potato bell pepper artichoke. - </p> - </div> -</div> -``` - -```css hidden live-sample___position2 -body { - font: 1.2em / 1.5 sans-serif; -} -* { - box-sizing: border-box; -} - -.container { - height: 400px; - padding: 0.5em; - border: 5px solid #ccc; - overflow: auto; -} - -.sidebar { - color: white; - background-color: #663398; - padding: 1em; - float: left; - width: 150px; -} - -.content { - padding: 1em; - margin-left: 160px; -} -``` - -```css live-sample___position2 -.container { -} - -.sidebar { -} -``` - -{{EmbedLiveSample("position2", "", "400px")}} - -<details> -<summary>Click here to show the solution</summary> - -We're testing your understanding of `position: fixed` with a slightly different example to the ones in the learning materials. - -```css -.sidebar { - position: fixed; -} -``` - -</details> - -## See also - -- [CSS styling basics](/en-US/docs/Learn_web_development/Core/Styling_basics) diff --git a/files/en-us/learn_web_development/core/css_layout/positioning/index.md b/files/en-us/learn_web_development/core/css_layout/positioning/index.md index 1d9b21e269c63df..e9eb02c338f8958 100644 --- a/files/en-us/learn_web_development/core/css_layout/positioning/index.md +++ b/files/en-us/learn_web_development/core/css_layout/positioning/index.md @@ -2,10 +2,9 @@ title: Positioning slug: Learn_web_development/Core/CSS_layout/Positioning page-type: learn-module-chapter +sidebar: learnsidebar --- -{{LearnSidebar}} - {{PreviousMenuNext("Learn_web_development/Core/CSS_layout/Floats", "Learn_web_development/Core/CSS_layout/Flexbox", "Learn_web_development/Core/CSS_layout")}} Positioning allows you to take elements out of normal document flow and make them behave differently, for example, sitting on top of one another or always remaining in the same place inside the browser viewport. This article explains the different {{cssxref("position")}} values and how to use them. @@ -667,7 +666,7 @@ Sticky elements are "sticky" relative to the nearest ancestor with a "scrolling ## Test your skills! -You've reached the end of this article, but can you remember the most important information? You can find some further tests to verify that you've retained this information before you move on — see [Test your skills: Positioning](/en-US/docs/Learn_web_development/Core/CSS_layout/Position_skills). +You've reached the end of this article, but can you remember the most important information? You can find some further tests to verify that you've retained this information before you move on — see [Test your skills: Positioning](/en-US/docs/Learn_web_development/Core/CSS_layout/Test_your_skills/Position). ## Summary diff --git a/files/en-us/learn_web_development/core/css_layout/practical_positioning_examples/index.md b/files/en-us/learn_web_development/core/css_layout/practical_positioning_examples/index.md index 9c75a2b7bc772d8..b085fadab7ed195 100644 --- a/files/en-us/learn_web_development/core/css_layout/practical_positioning_examples/index.md +++ b/files/en-us/learn_web_development/core/css_layout/practical_positioning_examples/index.md @@ -2,10 +2,9 @@ title: Practical positioning examples slug: Learn_web_development/Core/CSS_layout/Practical_positioning_examples page-type: guide +sidebar: learnsidebar --- -{{LearnSidebar}} - This article shows how to build some real-world examples to illustrate what kinds of things you can do with positioning. <table> @@ -184,7 +183,7 @@ Next, we'll set the `:focus` and `:hover` states of the tabs to look different w } ``` -Then we'll set a rule that highlights one of the tabs when [`aria-selected`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-selected) property is set to `true` on it. We will set this using JavaScript when a tab is clicked on. Place the following CSS below your other styles: +Then we'll set a rule that highlights one of the tabs when [`aria-selected`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-selected) property is set to `true` on it. We will set this using JavaScript when a tab is clicked on. Place the following CSS below your other styles: ```css .info-box [role="tab"][aria-selected="true"] { @@ -231,7 +230,7 @@ The second rule we'll add here makes it so that a panel with a class of `is-hidd ### JavaScript -The final part that makes this feature work is the JavaScript code. The `tabs-manual.js` file has been included using the [`<script>`](/en-US/docs/Web/HTML/Element/script) tag: +The final part that makes this feature work is the JavaScript code. The `tabs-manual.js` file has been included using the [`<script>`](/en-US/docs/Web/HTML/Reference/Elements/script) tag: ```html <script src="tabs-manual.js"></script> @@ -363,7 +362,7 @@ As a starting point, make a local copy of [hidden-info-panel-start.html](https:/ </aside> ``` -To start with here we've got a {{htmlelement("button")}} element with a special question mark character as the button text. The button will be pressed to show/hide the [`aside`](/en-US/docs/Web/HTML/Element/aside) info panel. In the below sections we'll explain how this all works. +To start with here we've got a {{htmlelement("button")}} element with a special question mark character as the button text. The button will be pressed to show/hide the [`aside`](/en-US/docs/Web/HTML/Reference/Elements/aside) info panel. In the below sections we'll explain how this all works. ### Styling the button @@ -445,7 +444,7 @@ button.addEventListener("click", () => { ``` The code adds a click event handler to the button. The click handler toggles the `open` class on the info-box panel which slides the panel in or out of the view. -The event handler also sets [`aria-expanded`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-expanded) property on the button to improve accessibility. +The event handler also sets [`aria-expanded`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-expanded) property on the button to improve accessibility. So there you have it — the easiest way to create a toggling info panel effect. diff --git a/files/en-us/learn_web_development/core/css_layout/responsive_design/index.md b/files/en-us/learn_web_development/core/css_layout/responsive_design/index.md index 63fb1effba1c1e2..46183d2838683a8 100644 --- a/files/en-us/learn_web_development/core/css_layout/responsive_design/index.md +++ b/files/en-us/learn_web_development/core/css_layout/responsive_design/index.md @@ -2,10 +2,9 @@ title: Responsive design slug: Learn_web_development/Core/CSS_layout/Responsive_Design page-type: learn-module-chapter +sidebar: learnsidebar --- -{{learnsidebar}} - {{PreviousMenuNext("Learn_web_development/Core/CSS_layout/Grids", "Learn_web_development/Core/CSS_layout/Media_queries", "Learn_web_development/Core/CSS_layout")}} _Responsive web design_ (RWD) is a web design approach to make web pages render well on all screen sizes and resolutions while ensuring good usability. It is the way to design for a multi-device web. In this article, we'll help you understand some techniques that can be used to master it. @@ -95,6 +94,9 @@ There are different approaches to the styles defined within a media query block; Media queries can help with RWD, but are not a requirement. Flexible grids, relative units, and minimum and maximum unit values can be used without media queries. +> [!NOTE] +> Scrimba has a tutorial called [Aside: Media queries](https://scrimba.com/frontend-path-c0j/~0j3?via=mdn) <sup>[_MDN learning partner_](/en-US/docs/MDN/Writing_guidelines/Learning_content#partner_links_and_embeds)</sup>, which provides an interactive introduction to media queries plus a challenge to test that you understand the basics. + ## Responsive layout technologies Responsive sites are built on flexible grids, meaning you don't need to target every possible device size with pixel perfect layouts. @@ -270,7 +272,7 @@ video { This scales media to ensure they never overflow their containers. > [!NOTE] -> Using a single large image and scaling it down to fit small devices wastes bandwidth by downloading images larger than required. It can also look bad — a landscape image for example might look good on a widescreen monitor, but it might be hard to see on a mobile device, which would suit a portrait image better. Such problems can be solved using the {{htmlelement("picture")}} element and the {{htmlelement("img")}} `srcset` and `sizes` attributes. These are advanced features that are beyond the scope of this course, but you can find a detailed guide at [Responsive images](/en-US/docs/Web/HTML/Responsive_images). +> Using a single large image and scaling it down to fit small devices wastes bandwidth by downloading images larger than required. It can also look bad — a landscape image for example might look good on a widescreen monitor, but it might be hard to see on a mobile device, which would suit a portrait image better. Such problems can be solved using the {{htmlelement("picture")}} element and the {{htmlelement("img")}} `srcset` and `sizes` attributes. These are advanced features that are beyond the scope of this course, but you can find a detailed guide at [Responsive images](/en-US/docs/Web/HTML/Guides/Responsive_images). Other useful tips: @@ -465,7 +467,7 @@ If you look at the HTML source of a responsive page, you will usually see the fo <meta name="viewport" content="width=device-width,initial-scale=1" /> ``` -This [viewport](/en-US/docs/Web/HTML/Viewport_meta_tag) meta tag tells mobile browsers that they should set the width of the viewport to the device width, and scale the document to 100% of its intended size, which shows the document at the mobile-optimized size that you intended. +This [viewport](/en-US/docs/Web/HTML/Guides/Viewport_meta_element) meta tag tells mobile browsers that they should set the width of the viewport to the device width, and scale the document to 100% of its intended size, which shows the document at the mobile-optimized size that you intended. Why is this needed? Because mobile browsers tend to lie about their viewport width. @@ -489,5 +491,6 @@ Next, we will study media queries in more detail and show how to use them to sol - [Touch events](/en-US/docs/Web/API/Touch_events) provide the ability to interpret finger (or stylus) activity on touch screens or trackpads, enabling quality support for complex touch-based user interfaces. - Use the [pointer](/en-US/docs/Web/CSS/@media/pointer) or [any-pointer](/en-US/docs/Web/CSS/@media/any-pointer) media queries to load different CSS on touch-enabled devices. - [CSS-Tricks guide to media queries](https://css-tricks.com/a-complete-guide-to-css-media-queries/) +- [The Frontend Developer Career Path](https://scrimba.com/the-frontend-developer-career-path-c0j?via=mdn) <sup>[_MDN learning partner_](/en-US/docs/MDN/Writing_guidelines/Learning_content#partner_links_and_embeds)</sup> from Scrimba teaches all you need to know to be a competent front-end web developer, with fun interactive lessons and challenges, knowledgeable teachers, and a supportive community. Go from zero to landing your first front-end job! Many of the course components are available as standalone free versions. This includes a module on responsive design. {{PreviousMenuNext("Learn_web_development/Core/CSS_layout/Grids", "Learn_web_development/Core/CSS_layout/Media_queries", "Learn_web_development/Core/CSS_layout")}} diff --git a/files/en-us/learn_web_development/core/css_layout/rwd_skills/index.md b/files/en-us/learn_web_development/core/css_layout/rwd_skills/index.md deleted file mode 100644 index f6148cb03fc630b..000000000000000 --- a/files/en-us/learn_web_development/core/css_layout/rwd_skills/index.md +++ /dev/null @@ -1,25 +0,0 @@ ---- -title: "Test your skills: Responsive web design and media queries" -slug: Learn_web_development/Core/CSS_layout/rwd_skills -page-type: learn-module-assessment ---- - -{{LearnSidebar}} - -The aim of this skill test is to assess whether you understand [how to use media queries](/en-US/docs/Learn_web_development/Core/CSS_layout/Media_queries) and get you working with responsive web design with a practical task. Everything you need to know to complete this task is covered in the layout lessons in the [CSS layout module](/en-US/docs/Learn_web_development/Core/CSS_layout). - -> [!NOTE] -> Because you need to test your design in multiple screen sizes, we do not have interactive editors on this page. -> Download the code and work locally, or use an online editor such as [CodePen](https://codepen.io/), [JSFiddle](https://jsfiddle.net/), or [Glitch](https://glitch.com/). -> -> If you get stuck, you can reach out to us in one of our [communication channels](/en-US/docs/MDN/Community/Communication_channels). - -## Task - -[Download the starting point for this task](https://github.com/mdn/css-examples/blob/main/learn/tasks/rwd/rwd-download.html). Open the downloaded HTML file in your browser and you will find a wireframed site which will load in a mobile device in a readable manner. You can drag your window smaller or use the [responsive design view in Firefox DevTools](https://firefox-source-docs.mozilla.org/devtools-user/index.html#responsive-design-mode) to view this as if on a phone. - -Your task is to create a desktop version of this layout which displays when there is enough screen width to accommodate it. Your final result should look like the image below: - -![A two column wireframed layout.](rwd-task.png) - -There are a number of ways that you could create the desktop layout, enjoy experimenting. You could also add a second breakpoint perhaps creating a layout that would work well on a tablet in portrait mode. diff --git a/files/en-us/learn_web_development/core/css_layout/supporting_older_browsers/index.md b/files/en-us/learn_web_development/core/css_layout/supporting_older_browsers/index.md index 867a17da92e7d06..498f3621321314c 100644 --- a/files/en-us/learn_web_development/core/css_layout/supporting_older_browsers/index.md +++ b/files/en-us/learn_web_development/core/css_layout/supporting_older_browsers/index.md @@ -3,10 +3,9 @@ title: Supporting older browsers slug: Learn_web_development/Core/CSS_layout/Supporting_Older_Browsers page-type: learn-module-chapter browser-compat: css.properties.grid-template-columns +sidebar: learnsidebar --- -{{LearnSidebar}} - Visitors to your website may include users who either use older browsers or use browsers that do not support the CSS features you've implemented. This is a common scenario on the web, where new features are continuously being added to CSS. Browsers differ in their support for these features because different browsers tend to prioritize implementing different features. This article explains how you as a web developer can use modern web techniques to ensure that your website remains accessible to users with older technology. <table> diff --git a/files/en-us/learn_web_development/core/css_layout/flexbox_skills/flex-task1.png b/files/en-us/learn_web_development/core/css_layout/test_your_skills/flexbox/flex-task1.png similarity index 100% rename from files/en-us/learn_web_development/core/css_layout/flexbox_skills/flex-task1.png rename to files/en-us/learn_web_development/core/css_layout/test_your_skills/flexbox/flex-task1.png diff --git a/files/en-us/learn_web_development/core/css_layout/flexbox_skills/flex-task2.png b/files/en-us/learn_web_development/core/css_layout/test_your_skills/flexbox/flex-task2.png similarity index 100% rename from files/en-us/learn_web_development/core/css_layout/flexbox_skills/flex-task2.png rename to files/en-us/learn_web_development/core/css_layout/test_your_skills/flexbox/flex-task2.png diff --git a/files/en-us/learn_web_development/core/css_layout/flexbox_skills/flex-task3.png b/files/en-us/learn_web_development/core/css_layout/test_your_skills/flexbox/flex-task3.png similarity index 100% rename from files/en-us/learn_web_development/core/css_layout/flexbox_skills/flex-task3.png rename to files/en-us/learn_web_development/core/css_layout/test_your_skills/flexbox/flex-task3.png diff --git a/files/en-us/learn_web_development/core/css_layout/flexbox_skills/flex-task4.png b/files/en-us/learn_web_development/core/css_layout/test_your_skills/flexbox/flex-task4.png similarity index 100% rename from files/en-us/learn_web_development/core/css_layout/flexbox_skills/flex-task4.png rename to files/en-us/learn_web_development/core/css_layout/test_your_skills/flexbox/flex-task4.png diff --git a/files/en-us/learn_web_development/core/css_layout/test_your_skills/flexbox/index.md b/files/en-us/learn_web_development/core/css_layout/test_your_skills/flexbox/index.md new file mode 100644 index 000000000000000..e9a090b80fe81ae --- /dev/null +++ b/files/en-us/learn_web_development/core/css_layout/test_your_skills/flexbox/index.md @@ -0,0 +1,292 @@ +--- +title: "Test your skills: Flexbox" +short-title: Flexbox +slug: Learn_web_development/Core/CSS_layout/Test_your_skills/Flexbox +page-type: learn-module-assessment +sidebar: learnsidebar +--- + +The aim of this skill test is to assess whether you understand how [flexbox and flex items](/en-US/docs/Learn_web_development/Core/CSS_layout/Flexbox) behave. Below are four common design patterns that you might use flexbox to create. Your task is to build them. + +> [!NOTE] +> Click **"Play"** in the code blocks below to edit the examples in the MDN Playground. +> You can also copy the code (click the clipboard icon) and paste it into an online editor such as [CodePen](https://codepen.io/), [JSFiddle](https://jsfiddle.net/), or [Glitch](https://glitch.com/). +> If you get stuck, you can reach out to us in one of our [communication channels](/en-US/docs/MDN/Community/Communication_channels). + +## Task 1 + +In this task, the list items are the navigation for a site. They should be laid out as a row, with an equal amount of space between each item. + +Your final result should look like the image below: + +![Flex items laid out as a row with space between them.](flex-task1.png) + +Try to update the code below to recreate the finished example: + +```html live-sample___flexbox1 +<nav> + <ul> + <li><a href="/">Home</a></li> + <li><a href="/about">About Us</a></li> + <li><a href="/products">Our Products</a></li> + <li><a href="/contact">Contact Us</a></li> + </ul> +</nav> +``` + +```css hidden live-sample___flexbox1 +body { + font: 1.2em / 1.5 sans-serif; +} +nav ul { + max-width: 700px; + list-style: none; + padding: 0; + margin: 0; +} +nav a:link, +nav a:visited { + background-color: #4d7298; + border: 2px solid #77a6b6; + border-radius: 0.5em; + color: #fff; + padding: 0.5em; + display: inline-block; + text-decoration: none; +} +``` + +```css live-sample___flexbox1 +nav ul { +} +``` + +{{EmbedLiveSample("flexbox1", "", "240px")}} + +<details> +<summary>Click here to show the solution</summary> + +You can apply `display: flex` and control spacing using the `justify-content` property: + +```css +nav ul { + display: flex; + justify-content: space-between; +} +``` + +</details> + +## Task 2 + +In this task, the list items are all different sizes, but we want them to be displayed as three equal sized columns, no matter what content is in each item. + +Your final result should look like the image below: + +![Flex items laid out as three equal size columns with different amounts of content.](flex-task2.png) + +**Bonus question:** Can you now make the first item twice the size of the other items? + +Try to update the code below to recreate the finished example: + +```html live-sample___flexbox2 +<ul> + <li>I am small</li> + <li>I have more content than the very small item.</li> + <li> + I have lots of content. So much content that I don't know where it is all + going to go. I'm glad that CSS is pretty good at dealing with situations + where we end up with more words than expected! + </li> +</ul> +``` + +```css hidden live-sample___flexbox2 +body { + font: 1.2em / 1.5 sans-serif; +} +ul { + max-width: 700px; + list-style: none; + padding: 0; + margin: 0; +} + +li { + background-color: #4d7298; + border: 2px solid #77a6b6; + border-radius: 0.5em; + color: #fff; + padding: 0.5em; +} +``` + +```css live-sample___flexbox2 +ul { +} + +li { +} +``` + +{{EmbedLiveSample("flexbox2", "", "240px")}} + +<details> +<summary>Click here to show the solution</summary> + +It's best to use shorthands, so in this scenario `flex: 1` is probably the best answer, and so the most optimal result would be: + +```css +ul { + display: flex; +} + +li { + flex: 1; +} +``` + +For the bonus question, add a selector that targets the first element and sets `flex: 2;` (or `flex: 2 0 0;` or `flex-grow: 2`): + +```css +li:first-child { + flex: 2; +} +``` + +</details> + +## Task 3 + +In this task, there are two elements in the HTML below, a `<div>` element with a class of `parent` which contains another `<div>` element with a class of `child`. Use flexbox to center the child inside the parent. There is more than one possible solution here. + +Your final result should look like the image below: + +![A box centered inside another box.](flex-task3.png) + +Try to update the code below to recreate the finished example: + +```html live-sample___flexbox3 +<div class="parent"> + <div class="child">Center me.</div> +</div> +``` + +```css hidden live-sample___flexbox3 +body { + font: 1.2em / 1.5 sans-serif; +} +.parent { + border: 2px solid #77a6b6; + border-radius: 0.5em; + height: 200px; +} + +.child { + background-color: #4d7298; + color: #fff; + padding: 0.5em; + width: 150px; +} +``` + +```css hidden live-sample___flexbox3 +.parent { +} + +.child { +} +``` + +{{EmbedLiveSample("flexbox3", "", "210px")}} + +<details> +<summary>Click here to show the solution</summary> + +It's only necessary to change the parent styles to center an item horizontally and vertically: + +```css +.parent { + display: flex; + justify-content: center; + align-items: center; +} +``` + +</details> + +## Task 4 + +In this task, we want you to arrange these items into rows as in the image below: + +![A set of items displayed as rows.](flex-task4.png) + +Try to update the code below to recreate the finished example: + +```html live-sample___flexbox4 +<ul> + <li>Turnip</li> + <li>greens</li> + <li>yarrow</li> + <li>ricebean</li> + <li>rutabaga</li> + <li>endive</li> + <li>cauliflower</li> + <li>sea lettuce</li> + <li>kohlrabi</li> + <li>amaranth</li> +</ul> +``` + +```css hidden live-sample___flexbox4 +body { + font: 1.2em / 1.5 sans-serif; +} +ul { + width: 450px; + list-style: none; + padding: 0; + margin: 0; +} + +li { + background-color: #4d7298; + border: 2px solid #77a6b6; + border-radius: 0.5em; + color: #fff; + padding: 0.5em; + margin: 0.5em; +} +``` + +```css live-sample___flexbox4 +ul { +} + +li { +} +``` + +{{EmbedLiveSample("flexbox4", "", "260px")}} + +<details> +<summary>Click here to show the solution</summary> + +This task requires an understanding of the `flex-wrap` property to wrap flex lines. In addition, to ensure that you end up with something that looks like the example, you need to set `flex: auto` on the child (or `flex: 1 1 auto;`). + +```css +ul { + display: flex; + flex-wrap: wrap; +} + +li { + flex: auto; +} +``` + +</details> + +## See also + +- [CSS styling basics](/en-US/docs/Learn_web_development/Core/Styling_basics) diff --git a/files/en-us/learn_web_development/core/css_layout/floats_skills/float-task1.png b/files/en-us/learn_web_development/core/css_layout/test_your_skills/floats/float-task1.png similarity index 100% rename from files/en-us/learn_web_development/core/css_layout/floats_skills/float-task1.png rename to files/en-us/learn_web_development/core/css_layout/test_your_skills/floats/float-task1.png diff --git a/files/en-us/learn_web_development/core/css_layout/floats_skills/float-task2.png b/files/en-us/learn_web_development/core/css_layout/test_your_skills/floats/float-task2.png similarity index 100% rename from files/en-us/learn_web_development/core/css_layout/floats_skills/float-task2.png rename to files/en-us/learn_web_development/core/css_layout/test_your_skills/floats/float-task2.png diff --git a/files/en-us/learn_web_development/core/css_layout/floats_skills/float-task3.png b/files/en-us/learn_web_development/core/css_layout/test_your_skills/floats/float-task3.png similarity index 100% rename from files/en-us/learn_web_development/core/css_layout/floats_skills/float-task3.png rename to files/en-us/learn_web_development/core/css_layout/test_your_skills/floats/float-task3.png diff --git a/files/en-us/learn_web_development/core/css_layout/test_your_skills/floats/index.md b/files/en-us/learn_web_development/core/css_layout/test_your_skills/floats/index.md new file mode 100644 index 000000000000000..830c2b614818d11 --- /dev/null +++ b/files/en-us/learn_web_development/core/css_layout/test_your_skills/floats/index.md @@ -0,0 +1,217 @@ +--- +title: "Test your skills: Floats" +short-title: Floats +slug: Learn_web_development/Core/CSS_layout/Test_your_skills/Floats +page-type: learn-module-assessment +sidebar: learnsidebar +--- + +The aim of this skill test is to assess whether you understand [floats in CSS](/en-US/docs/Learn_web_development/Core/CSS_layout/Floats) using the {{CSSxRef("float")}} and {{CSSxRef("clear")}} properties and values as well as other methods for clearing floats. You will be working through three small tasks that use different elements of the material you have just covered. + +> [!NOTE] +> Click **"Play"** in the code blocks below to edit the examples in the MDN Playground. +> You can also copy the code (click the clipboard icon) and paste it into an online editor such as [CodePen](https://codepen.io/), [JSFiddle](https://jsfiddle.net/), or [Glitch](https://glitch.com/). +> If you get stuck, you can reach out to us in one of our [communication channels](/en-US/docs/MDN/Community/Communication_channels). + +## Task 1 + +In this task, you need to float the two elements with a class of `float1` and `float2` left and right, respectively. The text should then appear between the two boxes, as in the image below: + +![Two blocks displaying left and right of some text.](float-task1.png) + +Try to update the code below to recreate the finished example: + +```html live-sample___float1 +<div class="box"> + <div class="float float1">One</div> + <div class="float float2">Two</div> + <p>The two boxes should float to either side of this text.</p> +</div> +``` + +```css hidden live-sample___float1 +body { + font: 1.2em / 1.5 sans-serif; +} +* { + box-sizing: border-box; +} +.box { + padding: 0.5em; +} +.float { + margin: 15px; + width: 150px; + height: 150px; + border-radius: 5px; + background-color: rebeccapurple; + color: #fff; + padding: 1em; +} +``` + +```css live-sample___float1 +.float1 { +} + +.float2 { +} +``` + +{{EmbedLiveSample("float1", "", "210px")}} + +<details> +<summary>Click here to show the solution</summary> + +You can use `float` for both boxes: + +```css +.float1 { + float: left; +} + +.float2 { + float: right; +} +``` + +</details> + +## Task 2 + +In this task, the element with a class of `float` should be floated left. Then we want the first line of text to display next to that element, but the following line of text (which has a class of `below`) to display underneath it. + +Your final result should look like the image below: + +![A box displayed to the left of a line of text, with some more text below.](float-task2.png) + +Try to update the code below to recreate the finished example: + +```html live-sample___float2 +<div class="box"> + <div class="float">Float</div> + <p>This sentence appears next to the float.</p> + <p class="below">Make this sentence appear below the float.</p> +</div> +``` + +```css hidden live-sample___float2 +body { + font: 1.2em / 1.5 sans-serif; +} +* { + box-sizing: border-box; +} +.box { + padding: 0.5em; +} +.float { + margin: 15px; + width: 150px; + height: 150px; + border-radius: 5px; + background-color: rebeccapurple; + color: #fff; + padding: 1em; +} +``` + +```css live-sample___float2 +.float { +} + +.below { +} +``` + +{{EmbedLiveSample("float2", "", "300px")}} + +<details> +<summary>Click here to show the solution</summary> + +You need to flow the item left, then add `clear: left` to the class for the second paragraph: + +```css +.float { + float: left; +} + +.below { + clear: left; +} +``` + +</details> + +## Task 3 + +In this task, we have a floated element. The box wrapping the float and text is displaying behind the float. Use the most up-to-date method available to cause the box background to extend to below the float, as in the image below: + +![A block displayed to the right of some text both wrapped by a box with a background color.](float-task3.png) + +Try to update the code below to recreate the finished example: + +```html live-sample___float3 +<div class="box"> + <div class="float">Float</div> + <p>This sentence appears next to the float.</p> +</div> +``` + +```css hidden live-sample___float3 +body { + font: 1.2em / 1.5 sans-serif; +} +* { + box-sizing: border-box; +} + +.box { + padding: 0.5em; +} + +.float { + margin: 15px; + width: 150px; + height: 150px; + border-radius: 5px; + background-color: rgb(207 232 220); + padding: 1em; + color: #fff; +} + +.box { + background-color: rebeccapurple; + padding: 10px; + color: #fff; +} +``` + +```css live-sample___float3 +.float { + float: right; +} + +.box { +} +``` + +{{EmbedLiveSample("float3", "", "300px")}} + +<details> +<summary>Click here to show the solution</summary> + +Clear the box underneath the floated item by adding `display: flow-root` to the class for `.box`. +Other methods might be to use `overflow` or a clearfix hack, however the learning materials detail the `flow-root` method as the modern way to achieve this. + +```css +.box { + display: flow-root; +} +``` + +</details> + +## See also + +- [CSS styling basics](/en-US/docs/Learn_web_development/Core/Styling_basics) diff --git a/files/en-us/learn_web_development/core/css_layout/grid_skills/grid-task1.png b/files/en-us/learn_web_development/core/css_layout/test_your_skills/grid/grid-task1.png similarity index 100% rename from files/en-us/learn_web_development/core/css_layout/grid_skills/grid-task1.png rename to files/en-us/learn_web_development/core/css_layout/test_your_skills/grid/grid-task1.png diff --git a/files/en-us/learn_web_development/core/css_layout/grid_skills/grid-task2.png b/files/en-us/learn_web_development/core/css_layout/test_your_skills/grid/grid-task2.png similarity index 100% rename from files/en-us/learn_web_development/core/css_layout/grid_skills/grid-task2.png rename to files/en-us/learn_web_development/core/css_layout/test_your_skills/grid/grid-task2.png diff --git a/files/en-us/learn_web_development/core/css_layout/grid_skills/grid-task3.png b/files/en-us/learn_web_development/core/css_layout/test_your_skills/grid/grid-task3.png similarity index 100% rename from files/en-us/learn_web_development/core/css_layout/grid_skills/grid-task3.png rename to files/en-us/learn_web_development/core/css_layout/test_your_skills/grid/grid-task3.png diff --git a/files/en-us/learn_web_development/core/css_layout/grid_skills/grid-task4.png b/files/en-us/learn_web_development/core/css_layout/test_your_skills/grid/grid-task4.png similarity index 100% rename from files/en-us/learn_web_development/core/css_layout/grid_skills/grid-task4.png rename to files/en-us/learn_web_development/core/css_layout/test_your_skills/grid/grid-task4.png diff --git a/files/en-us/learn_web_development/core/css_layout/test_your_skills/grid/index.md b/files/en-us/learn_web_development/core/css_layout/test_your_skills/grid/index.md new file mode 100644 index 000000000000000..874c8ce25d01e70 --- /dev/null +++ b/files/en-us/learn_web_development/core/css_layout/test_your_skills/grid/index.md @@ -0,0 +1,362 @@ +--- +title: "Test your skills: Grid" +short-title: Grid +slug: Learn_web_development/Core/CSS_layout/Test_your_skills/Grid +page-type: learn-module-assessment +sidebar: learnsidebar +--- + +The aim of this skill test is to assess whether you understand how a [grid and grid items](/en-US/docs/Learn_web_development/Core/CSS_layout/Grids) behave. You will be working through several small tasks that use different elements of the material you have just covered. + +> [!NOTE] +> Click **"Play"** in the code blocks below to edit the examples in the MDN Playground. +> You can also copy the code (click the clipboard icon) and paste it into an online editor such as [CodePen](https://codepen.io/), [JSFiddle](https://jsfiddle.net/), or [Glitch](https://glitch.com/). +> If you get stuck, you can reach out to us in one of our [communication channels](/en-US/docs/MDN/Community/Communication_channels). + +## Task 1 + +In this task, you should create a grid into which the four child elements will auto-place. The grid should have three columns sharing the available space equally and a 20 pixel gap between the column and row tracks. After that, try adding more child containers inside the parent container with the class of `grid` and see how they behave by default. + +Your final result should look like the image below: + +![A three column grid with four items placed into it.](grid-task1.png) + +Try to update the code below to recreate the finished example: + +```html live-sample___grid1 +<div class="grid"> + <div>One</div> + <div>Two</div> + <div>Three</div> + <div>Four</div> +</div> +``` + +```css hidden live-sample___grid1 +body { + font: 1.2em / 1.5 sans-serif; +} +.grid > * { + background-color: #4d7298; + border: 2px solid #77a6b6; + border-radius: 0.5em; + color: #fff; + padding: 0.5em; +} +``` + +```css live-sample___grid1 +.grid { +} +``` + +{{EmbedLiveSample("grid1", "", "200px")}} + +<details> +<summary>Click here to show the solution</summary> + +Create a grid using `display: grid` with three columns using `grid-template-columns` and a `gap` between the items: + +```css +.grid { + display: grid; + grid-template-columns: 1fr 1fr 1fr; + gap: 20px; +} +``` + +</details> + +## Task 2 + +In this task, we already have a grid defined. By editing the CSS rules for the two child elements, cause them to span over several grid tracks each. The second item should overlay the first as in the image below: + +![A box with two items inside one overlaying the other.](grid-task2.png) + +**Bonus question:** Can you now cause the first item to display on top without changing the order of items in the source? + +Try to update the code below to recreate the finished example: + +```html live-sample___grid2 +<div class="grid"> + <div class="item1">One</div> + <div class="item2">Two</div> +</div> +``` + +```css hidden live-sample___grid2 +body { + font: 1.2em / 1.5 sans-serif; +} +.grid > * { + border-radius: 0.5em; + color: #fff; + padding: 0.5em; +} + +.item1 { + background-color: rgb(74 102 112 / 70%); + border: 5px solid rgb(74 102 112 / 100%); +} + +.item2 { + background-color: rgb(214 162 173 / 70%); + border: 5px solid rgb(214 162 173 / 100%); +} +``` + +```css live-sample___grid2 +.grid { + display: grid; + grid-template-columns: 1fr 1fr 1fr 1fr; + grid-template-rows: 100px 100px 100px; + gap: 10px; +} + +.item1 { +} + +.item2 { +} +``` + +{{EmbedLiveSample("grid2", "", "340px")}} + +<details> +<summary>Click here to show the solution</summary> + +It is possible to layer items by way of them occupying the same grid cells. +One option is to use the shorthands below, however it would be correct to use the longhand `grid-row-start` for example. + +```css +.item1 { + grid-column: 1 / 4; + grid-row: 1 / 3; +} + +.item2 { + grid-column: 2 / 5; + grid-row: 2 / 4; +} +``` + +For the bonus question, one way of achieving this would be to use `order`, which we've encountered in the flexbox tutorial. + +```css +.item1 { + order: 1; +} +``` + +Another valid solution is to use `z-index`: + +```css +.item1 { + z-index: 1; +} +``` + +</details> + +## Task 3 + +In this task, there are four direct children in this grid. The starting point has them displayed using auto-placement. Use the grid-area and grid-template-areas properties to lay the items out as shown in the image below: + +![Four items displayed in a grid.](grid-task3.png) + +Try to update the code below to recreate the finished example: + +```html live-sample___grid3 +<div class="grid"> + <div class="one">One</div> + <div class="two">Two</div> + <div class="three">Three</div> + <div class="four">Four</div> +</div> +``` + +```css hidden live-sample___grid3 +body { + font: 1.2em / 1.5 sans-serif; +} +.grid > * { + background-color: #4d7298; + border: 2px solid #77a6b6; + border-radius: 0.5em; + color: #fff; + padding: 0.5em; +} +``` + +```css live-sample___grid3 +.grid { + display: grid; + grid-template-columns: 1fr 2fr; + gap: 10px; +} +``` + +{{EmbedLiveSample("grid3", "", "200px")}} + +<details> +<summary>Click here to show the solution</summary> + +Each part of the layout needs a name using the `grid-area` property and `grid-template-areas` to lay them out. Possible areas of confusion would be not realizing you should place a `.` to leave a cell empty, or that you should repeat the name to cause an element to span more than one track: + +```css +.grid { + display: grid; + gap: 20px; + grid-template-columns: 1fr 2fr; + grid-template-areas: + "aa aa" + "bb cc" + ". dd"; +} + +.one { + grid-area: aa; +} + +.two { + grid-area: bb; +} + +.three { + grid-area: cc; +} + +.four { + grid-area: dd; +} +``` + +</details> + +## Task 4 + +In this task, you will need to use both grid layout and flexbox to recreate the example as seen in the image below. The gap between the column and row tracks should be 10px. You do not need to make any changes to the HTML in order to achieve this. + +![Two rows of cards, each with an image and a set of tags.](grid-task4.png) + +Try to update the code below to recreate the finished example: + +```html live-sample___grid4 +<div class="container"> + <div class="card"> + <img + alt="a single red balloon" + src="https://mdn.github.io/shared-assets/images/examples/balloons1.jpg" /> + <ul class="tags"> + <li>balloon</li> + <li>red</li> + <li>sky</li> + <li>blue</li> + <li>Hot air balloon</li> + </ul> + </div> + <div class="card"> + <img + alt="balloons over some houses" + src="https://mdn.github.io/shared-assets/images/examples/balloons2.jpg" /> + <ul class="tags"> + <li>balloons</li> + <li>houses</li> + <li>train</li> + <li>harborside</li> + </ul> + </div> + <div class="card"> + <img + alt="close-up of balloons inflating" + src="https://mdn.github.io/shared-assets/images/examples/balloons3.jpg" /> + <ul class="tags"> + <li>balloons</li> + <li>inflating</li> + <li>green</li> + <li>blue</li> + </ul> + </div> + <div class="card"> + <img + alt="a balloon in the sun" + src="https://mdn.github.io/shared-assets/images/examples/balloons4.jpg" /> + <ul class="tags"> + <li>balloon</li> + <li>sun</li> + <li>sky</li> + <li>summer</li> + <li>bright</li> + </ul> + </div> +</div> +``` + +```css hidden live-sample___grid4 +body { + font: 1.2em / 1.5 sans-serif; +} +.card { + display: grid; + grid-template-rows: 200px min-content; +} + +.card > img { + width: 100%; + height: 100%; + object-fit: cover; +} + +.tags { + margin: 0; + padding: 0; + list-style: none; +} + +.tags > * { + background-color: #999; + color: #fff; + padding: 0.2em 0.8em; + border-radius: 0.2em; + font-size: 80%; + margin: 5px; +} +``` + +```css live-sample___grid4 +.container { +} + +.tags { +} +``` + +{{EmbedLiveSample("grid4", "", "400px")}} + +<details> +<summary>Click here to show the solution</summary> + +The container will need to be a grid layout, as we have alignment in rows and columns - two-dimensional. +The `<ul>` needs to be a flex container as tags (`<li>` elements) are not lined up in columns, only in rows and they are centered in the space with the alignment property `justify-content` set to `center`. + +You may try to use flexbox on the container and restrict the cards with percentage values. You may also try to make the items into a grid layout in which case, note that the items are not aligned in two dimensions so flexbox isn't the best choice. + +```css +.container { + display: grid; + gap: 10px; + grid-template-columns: 1fr 1fr 1fr; +} + +.tags { + display: flex; + flex-wrap: wrap; + justify-content: center; +} +``` + +</details> + +## See also + +- [CSS styling basics](/en-US/docs/Learn_web_development/Core/Styling_basics) diff --git a/files/en-us/learn_web_development/core/css_layout/test_your_skills/index.md b/files/en-us/learn_web_development/core/css_layout/test_your_skills/index.md new file mode 100644 index 000000000000000..fd971564105e054 --- /dev/null +++ b/files/en-us/learn_web_development/core/css_layout/test_your_skills/index.md @@ -0,0 +1,17 @@ +--- +title: "Test your skills: CSS layout" +short-title: Test your skills +slug: Learn_web_development/Core/CSS_layout/Test_your_skills +page-type: learn-module-assessment +sidebar: learnsidebar +--- + +This page lists CSS layout tests you can try so you can verify if you've understood the content in this module. + +## Test your CSS layout skills by topic + +{{SubpagesWithSummaries}} + +## See also + +- [CSS layout](/en-US/docs/Learn_web_development/Core/CSS_layout) diff --git a/files/en-us/learn_web_development/core/css_layout/test_your_skills/multicolumn/index.md b/files/en-us/learn_web_development/core/css_layout/test_your_skills/multicolumn/index.md new file mode 100644 index 000000000000000..040d9999b78313f --- /dev/null +++ b/files/en-us/learn_web_development/core/css_layout/test_your_skills/multicolumn/index.md @@ -0,0 +1,233 @@ +--- +title: "Test your skills: Multicol" +short-title: Multicol +slug: Learn_web_development/Core/CSS_layout/Test_your_skills/Multicolumn +page-type: learn-module-assessment +sidebar: learnsidebar +--- + +The aim of this skill test is to assess whether you understand [CSS multiple-column layout](/en-US/docs/Learn_web_development/Core/CSS_layout/Multiple-column_Layout), including the {{CSSxRef("column-count")}}, {{CSSxRef("column-width")}}, {{CSSxRef("column-gap")}}, {{CSSxRef("column-span")}} and {{CSSxRef("column-rule")}} properties and values. You will be working through three small tasks that use different elements of the material you have just covered. + +> [!NOTE] +> Click **"Play"** in the code blocks below to edit the examples in the MDN Playground. +> You can also copy the code (click the clipboard icon) and paste it into an online editor such as [CodePen](https://codepen.io/), [JSFiddle](https://jsfiddle.net/), or [Glitch](https://glitch.com/). +> If you get stuck, you can reach out to us in one of our [communication channels](/en-US/docs/MDN/Community/Communication_channels). + +## Task 1 + +In this task, we want you to create three columns, with a 50px gap between each column. + +Your final result should look like the image below: + +![Three columns of text](multicol-task1.png) + +Try updating the live code below to recreate the finished example: + +```html live-sample___multicol1 +<div class="container"> + <p> + Veggies es bonus vobis, proinde vos postulo essum magis kohlrabi welsh onion + daikon amaranth tatsoi tomatillo melon azuki bean garlic. + </p> + + <p> + Gumbo beet greens corn soko endive gumbo gourd. Parsley shallot courgette + tatsoi pea sprouts fava bean collard greens dandelion okra wakame tomato. + Dandelion cucumber earthnut pea peanut soko zucchini. + </p> + + <p> + Turnip greens yarrow ricebean rutabaga endive cauliflower sea lettuce + kohlrabi amaranth water spinach avocado daikon napa cabbage asparagus winter + purslane kale. Celery potato scallion desert raisin horseradish spinach + carrot soko. Lotus root water spinach fennel kombu maize bamboo shoot green + bean swiss chard seakale pumpkin onion chickpea gram corn pea. + </p> +</div> +``` + +```css live-sample___multicol1 +body { + font: 1.2em / 1.5 sans-serif; +} +.container { +} +``` + +{{EmbedLiveSample("multicol1", "", "300px")}} + +<details> +<summary>Click here to show the solution</summary> + +For this task, you need to use `column-count` and `column-gap`: + +```css +.container { + column-count: 3; + column-gap: 50px; +} +``` + +</details> + +## Task 2 + +In this task, we want you to create columns which have a minimum width of 200px. Then, add a 5px grey rule between each column, ensuring there is 10px of space between the edge of the rule and the column content. + +Your final result should look like the image below: + +![Three columns of text with a grey rule between them.](multicol-task2.png) + +Try updating the live code below to recreate the finished example: + +```html live-sample___multicol2 +<div class="container"> + <p> + Veggies es bonus vobis, proinde vos postulo essum magis kohlrabi welsh onion + daikon amaranth tatsoi tomatillo melon azuki bean garlic. + </p> + + <p> + Gumbo beet greens corn soko endive gumbo gourd. Parsley shallot courgette + tatsoi pea sprouts fava bean collard greens dandelion okra wakame tomato. + Dandelion cucumber earthnut pea peanut soko zucchini. + </p> + + <p> + Turnip greens yarrow ricebean rutabaga endive cauliflower sea lettuce + kohlrabi amaranth water spinach avocado daikon napa cabbage asparagus winter + purslane kale. Celery potato scallion desert raisin horseradish spinach + carrot soko. Lotus root water spinach fennel kombu maize bamboo shoot green + bean swiss chard seakale pumpkin onion chickpea gram corn pea. + </p> +</div> +``` + +```css live-sample___multicol2 +body { + font: 1.2em / 1.5 sans-serif; +} +.container { +} +``` + +{{EmbedLiveSample("multicol2", "", "300px")}} + +<details> +<summary>Click here to show the solution</summary> + +You will need to use the `column-width` and `column-rule` properties. +You could use the longhand `column-rule-*` properties instead of the shorthand, though there is no benefit to doing so. +The key thing with the use of `column-gap` is that you have understood that the rule does not add 5px of space to the gap. To have 10px either side of the rule they need a 25px gap as the rule is laid over it. + +```css +.container { + column-width: 200px; + column-rule: 5px solid #ccc; + column-gap: 25px; +} +``` + +</details> + +## Task 3 + +In this task, we want you to cause the element containing the heading and subheading to span across all columns so it looks like the image below: + +![Three columns of text with a heading and subheading spanning all three in the middle.](multicol-task3.png) + +Try updating the live code below to recreate the finished example: + +```html live-sample___multicol3 +<div class="container"> + <p> + Veggies es bonus vobis, proinde vos postulo essum magis kohlrabi welsh onion + daikon amaranth tatsoi tomatillo melon azuki bean garlic. + </p> + <p> + Gumbo beet greens corn soko endive gumbo gourd. Parsley shallot courgette + tatsoi pea sprouts fava bean collard greens dandelion okra wakame tomato. + Dandelion cucumber earthnut pea peanut soko zucchini. + </p> + <div class="box"> + <h2>I am a level 2 heading</h2> + <div class="subhead">Lotus root water spinach fennel</div> + </div> + <p> + Turnip greens yarrow ricebean rutabaga endive cauliflower sea lettuce + kohlrabi amaranth water spinach avocado daikon napa cabbage asparagus winter + purslane kale. Celery potato scallion desert raisin horseradish spinach + carrot soko. Lotus root water spinach fennel kombu maize bamboo shoot green + bean swiss chard seakale pumpkin onion chickpea gram corn pea. + </p> +</div> +``` + +```css hidden live-sample___multicol3 +body { + font: 1.2em / 1.5 sans-serif; +} +* { + box-sizing: border-box; +} + +.box { + text-align: center; + margin: 1em 0; +} + +.box h2 { + margin: 0; + display: grid; + grid-template-columns: 1fr auto 1fr; + column-gap: 0.5em; + align-items: center; +} + +.box h2::before { + content: ""; + border-bottom: 5px dotted #ccc; +} + +.box h2::after { + content: ""; + border-bottom: 5px dotted #ccc; +} + +.subhead { + font-style: italic; +} +``` + +```css live-sample___multicol3 +.container { + column-count: 3; +} + +.box { +} + +h2 { +} +``` + +{{EmbedLiveSample("multicol3", "", "400px")}} + +<details> +<summary>Click here to show the solution</summary> + +In this task, we test for understanding of the `column-span` property. +All you need to do is set the element with a class of `.box` to `column-span: all`. +This is mostly a task of checking that you select the right element. + +```css +.box { + column-span: all; +} +``` + +</details> + +## See also + +- [CSS styling basics](/en-US/docs/Learn_web_development/Core/Styling_basics) diff --git a/files/en-us/learn_web_development/core/css_layout/multicol_skills/multicol-task1.png b/files/en-us/learn_web_development/core/css_layout/test_your_skills/multicolumn/multicol-task1.png similarity index 100% rename from files/en-us/learn_web_development/core/css_layout/multicol_skills/multicol-task1.png rename to files/en-us/learn_web_development/core/css_layout/test_your_skills/multicolumn/multicol-task1.png diff --git a/files/en-us/learn_web_development/core/css_layout/multicol_skills/multicol-task2.png b/files/en-us/learn_web_development/core/css_layout/test_your_skills/multicolumn/multicol-task2.png similarity index 100% rename from files/en-us/learn_web_development/core/css_layout/multicol_skills/multicol-task2.png rename to files/en-us/learn_web_development/core/css_layout/test_your_skills/multicolumn/multicol-task2.png diff --git a/files/en-us/learn_web_development/core/css_layout/multicol_skills/multicol-task3.png b/files/en-us/learn_web_development/core/css_layout/test_your_skills/multicolumn/multicol-task3.png similarity index 100% rename from files/en-us/learn_web_development/core/css_layout/multicol_skills/multicol-task3.png rename to files/en-us/learn_web_development/core/css_layout/test_your_skills/multicolumn/multicol-task3.png diff --git a/files/en-us/learn_web_development/core/css_layout/test_your_skills/position/index.md b/files/en-us/learn_web_development/core/css_layout/test_your_skills/position/index.md new file mode 100644 index 000000000000000..89afc90358fdcf9 --- /dev/null +++ b/files/en-us/learn_web_development/core/css_layout/test_your_skills/position/index.md @@ -0,0 +1,191 @@ +--- +title: "Test your skills: Positioning" +short-title: Positioning +slug: Learn_web_development/Core/CSS_layout/Test_your_skills/Position +page-type: learn-module-assessment +sidebar: learnsidebar +--- + +The aim of this skill test is to assess whether you understand [positioning in CSS](/en-US/docs/Learn_web_development/Core/CSS_layout/Positioning) using the CSS {{CSSxRef("position")}} property and values. You will be working through two small tasks that use different elements of the material you have just covered. + +> [!NOTE] +> Click **"Play"** in the code blocks below to edit the examples in the MDN Playground. +> You can also copy the code (click the clipboard icon) and paste it into an online editor such as [CodePen](https://codepen.io/), [JSFiddle](https://jsfiddle.net/), or [Glitch](https://glitch.com/). +> If you get stuck, you can reach out to us in one of our [communication channels](/en-US/docs/MDN/Community/Communication_channels). + +## Task 1 + +In this task, we want you to position the item with a class of `target` to the top and right of the container, which has the 5px grey border. + +Your final result should look like the image below: + +![The green box is at the top right of a container with a grey border.](position-task1.png) + +**Bonus question:** Can you change the target to display underneath the text? + +Try to update the code below to recreate the finished example: + +```html live-sample___position1 +<div class="container"> + <p> + Veggies es bonus vobis, proinde vos postulo essum magis kohlrabi welsh onion + daikon amaranth tatsoi tomatillo melon azuki bean garlic. + </p> + <div class="target">Target</div> + <p> + Gumbo beet greens corn soko endive gumbo gourd. Parsley shallot courgette + tatsoi pea sprouts fava bean collard greens dandelion okra wakame tomato. + Dandelion cucumber earthnut pea peanut soko zucchini. + </p> +</div> +``` + +```css hidden live-sample___position1 +body { + font: 1.2em / 1.5 sans-serif; +} +* { + box-sizing: border-box; +} + +.container { + padding: 0.5em; + border: 5px solid #ccc; +} + +.target { + width: 150px; + height: 150px; + border-radius: 5px; + background-color: #663398; + padding: 1em; + color: white; +} +``` + +```css live-sample___position1 +.container { +} + +.target { +} +``` + +{{EmbedLiveSample("position1", "", "400px")}} + +<details> +<summary>Click here to show the solution</summary> + +This requires `position: relative` and `position: absolute` and understanding how they relate to each other in terms of relative positioning creating a new positioning context. +A likely issue could be that you add `position: absolute` to the child without applying `position: relative` to the container. In that case, the target will end up being positioned according to the viewport. + +```css +.container { + position: relative; +} + +.target { + position: absolute; + top: 0; + right: 0; +} +``` + +For the bonus question, you need to add a negative `z-index` to the target, for example `z-index: -2`. + +</details> + +## Task 2 + +In this task, if you scroll the box in the example below, the sidebar scrolls with the content. Change it so that the sidebar (`<div class="sidebar">`) stays in place and only the content scrolls. + +![The content is scrolled but the sidebar has stayed in place.](position-task2.png) + +Try to update the code below to recreate the finished example: + +```html live-sample___position2 +<div class="container"> + <div class="sidebar"> + <p> + This is the sidebar. It should remain in position as the content scrolls. + </p> + </div> + <div class="content"> + <p> + Veggies es bonus vobis, proinde vos postulo essum magis kohlrabi welsh + onion daikon amaranth tatsoi tomatillo melon azuki bean garlic. + </p> + <p> + Gumbo beet greens corn soko endive gumbo gourd. Parsley shallot courgette + tatsoi pea sprouts fava bean collard greens dandelion okra wakame tomato. + Dandelion cucumber earthnut pea peanut soko zucchini. + </p> + <p> + Turnip greens yarrow ricebean rutabaga endive cauliflower sea lettuce + kohlrabi amaranth water spinach avocado daikon napa cabbage asparagus + winter purslane kale. Celery potato scallion desert raisin horseradish + spinach carrot soko. Lotus root water spinach fennel kombu maize bamboo + shoot green bean swiss chard seakale pumpkin onion chickpea gram corn pea. + Brussels sprout coriander water chestnut gourd swiss chard wakame kohlrabi + beetroot carrot watercress. Corn amaranth salsify bunya nuts nori azuki + bean chickweed potato bell pepper artichoke. + </p> + </div> +</div> +``` + +```css hidden live-sample___position2 +body { + font: 1.2em / 1.5 sans-serif; +} +* { + box-sizing: border-box; +} + +.container { + height: 400px; + padding: 0.5em; + border: 5px solid #ccc; + overflow: auto; +} + +.sidebar { + color: white; + background-color: #663398; + padding: 1em; + float: left; + width: 150px; +} + +.content { + padding: 1em; + margin-left: 160px; +} +``` + +```css live-sample___position2 +.container { +} + +.sidebar { +} +``` + +{{EmbedLiveSample("position2", "", "400px")}} + +<details> +<summary>Click here to show the solution</summary> + +We're testing your understanding of `position: fixed` with a slightly different example to the ones in the learning materials. + +```css +.sidebar { + position: fixed; +} +``` + +</details> + +## See also + +- [CSS styling basics](/en-US/docs/Learn_web_development/Core/Styling_basics) diff --git a/files/en-us/learn_web_development/core/css_layout/position_skills/position-task1.png b/files/en-us/learn_web_development/core/css_layout/test_your_skills/position/position-task1.png similarity index 100% rename from files/en-us/learn_web_development/core/css_layout/position_skills/position-task1.png rename to files/en-us/learn_web_development/core/css_layout/test_your_skills/position/position-task1.png diff --git a/files/en-us/learn_web_development/core/css_layout/position_skills/position-task2.png b/files/en-us/learn_web_development/core/css_layout/test_your_skills/position/position-task2.png similarity index 100% rename from files/en-us/learn_web_development/core/css_layout/position_skills/position-task2.png rename to files/en-us/learn_web_development/core/css_layout/test_your_skills/position/position-task2.png diff --git a/files/en-us/learn_web_development/core/css_layout/test_your_skills/responsive_design/index.md b/files/en-us/learn_web_development/core/css_layout/test_your_skills/responsive_design/index.md new file mode 100644 index 000000000000000..b648be52f20dd55 --- /dev/null +++ b/files/en-us/learn_web_development/core/css_layout/test_your_skills/responsive_design/index.md @@ -0,0 +1,25 @@ +--- +title: "Test your skills: Responsive web design and media queries" +short-title: Responsive design and media queries +slug: Learn_web_development/Core/CSS_layout/Test_your_skills/Responsive_design +page-type: learn-module-assessment +sidebar: learnsidebar +--- + +The aim of this skill test is to assess whether you understand [how to use media queries](/en-US/docs/Learn_web_development/Core/CSS_layout/Media_queries) and get you working with responsive web design with a practical task. Everything you need to know to complete this task is covered in the layout lessons in the [CSS layout module](/en-US/docs/Learn_web_development/Core/CSS_layout). + +> [!NOTE] +> Because you need to test your design in multiple screen sizes, we do not have interactive editors on this page. +> Download the code and work locally, or use an online editor such as [CodePen](https://codepen.io/), [JSFiddle](https://jsfiddle.net/), or [Glitch](https://glitch.com/). +> +> If you get stuck, you can reach out to us in one of our [communication channels](/en-US/docs/MDN/Community/Communication_channels). + +## Task + +[Download the starting point for this task](https://github.com/mdn/css-examples/blob/main/learn/tasks/rwd/rwd-download.html). Open the downloaded HTML file in your browser and you will find a wireframed site which will load in a mobile device in a readable manner. You can drag your window smaller or use the [responsive design view in Firefox DevTools](https://firefox-source-docs.mozilla.org/devtools-user/index.html#responsive-design-mode) to view this as if on a phone. + +Your task is to create a desktop version of this layout which displays when there is enough screen width to accommodate it. Your final result should look like the image below: + +![A two column wireframed layout.](rwd-task.png) + +There are a number of ways that you could create the desktop layout, enjoy experimenting. You could also add a second breakpoint perhaps creating a layout that would work well on a tablet in portrait mode. diff --git a/files/en-us/learn_web_development/core/css_layout/rwd_skills/rwd-task.png b/files/en-us/learn_web_development/core/css_layout/test_your_skills/responsive_design/rwd-task.png similarity index 100% rename from files/en-us/learn_web_development/core/css_layout/rwd_skills/rwd-task.png rename to files/en-us/learn_web_development/core/css_layout/test_your_skills/responsive_design/rwd-task.png diff --git a/files/en-us/learn_web_development/core/design_for_developers/index.md b/files/en-us/learn_web_development/core/design_for_developers/index.md index 9359f78678d2691..337d9fb7efe5883 100644 --- a/files/en-us/learn_web_development/core/design_for_developers/index.md +++ b/files/en-us/learn_web_development/core/design_for_developers/index.md @@ -2,10 +2,9 @@ title: Design for developers slug: Learn_web_development/Core/Design_for_developers page-type: learn-module +sidebar: learnsidebar --- -{{LearnSidebar}} - {{NextMenu("Learn_web_development/Core/Version_control", "Learn_web_development/Core")}} > [!NOTE] @@ -71,19 +70,17 @@ Learning outcomes: - Speaking design language, to communicate with designers. - Interpreting design brief requirements to produce an implementation. -- Typical tools designers use to get their message across to developers (e.g. Figma). +- Typical tools designers use to get their message across to developers (e.g., Figma). ## See also -- [Learn UI Design Fundamentals](https://scrimba.com/learn/design?via=mdn), Scrimba <sup>Course Partner</sup> +- [Learn UI Design Fundamentals](https://scrimba.com/intro-to-ui-design-fundamentals-c0q?via=mdn), Scrimba <sup>Course Partner</sup> - [The Shape of Design](https://shapeofdesignbook.com/chapters/00-introduction/), Frank Chimero - [Designing for the Web](https://designingfortheweb.co.uk/), Mark Boulton -- [Design for web](https://designforweb.org/), Prisca Schmarsow + other contributors. Highlights include: - - [Design trampoline: Learn design theory basics](https://designforweb.org/vis/chapter1-design-principles/designTrampoline-by-AnnaRiazhskikh/), Anna Riazhskikh - - [Web typography made simple](https://designforweb.org/vis/chapter2-typography/typelab-by-HannahBoom/), Hannah Boom +- [Design for web](https://designforweb.org/), Prisca Schmarsow + other contributors - [Practical Typography](https://practicaltypography.com/), Matthew Butterick - [Web Style Guide](https://webstyleguide.com/), Patrick J. Lynch and Sarah Horton - [Visual design rules you can safely follow every time](https://anthonyhobday.com/sideprojects/saferules/), Anthony Hobday -- [16 little UI design rules that make a big impact](https://www.adhamdannaway.com/blog/ui-design/16-ui-design-rules), Adham Dannaway +- [16 little UI design rules that make a big impact](https://www.adhamdannaway.com/blog/ui-design/ui-design-tips), Adham Dannaway {{NextMenu("Learn_web_development/Core/Version_control", "Learn_web_development/Core")}} diff --git a/files/en-us/learn_web_development/core/frameworks_libraries/angular_building/index.md b/files/en-us/learn_web_development/core/frameworks_libraries/angular_building/index.md index 49e15ddf12a3faf..696fb00289eb23a 100644 --- a/files/en-us/learn_web_development/core/frameworks_libraries/angular_building/index.md +++ b/files/en-us/learn_web_development/core/frameworks_libraries/angular_building/index.md @@ -2,10 +2,9 @@ title: Building Angular applications and further resources slug: Learn_web_development/Core/Frameworks_libraries/Angular_building page-type: learn-module-chapter +sidebar: learnsidebar --- -{{LearnSidebar}} - {{PreviousMenu("Learn_web_development/Core/Frameworks_libraries/Angular_filtering", "Learn_web_development/Core/Frameworks_libraries")}} This final Angular article covers how to build an app ready for production, and provides further resources for you to continue your learning journey. diff --git a/files/en-us/learn_web_development/core/frameworks_libraries/angular_filtering/index.md b/files/en-us/learn_web_development/core/frameworks_libraries/angular_filtering/index.md index 251b05adb72f103..1200e796b56d7ce 100644 --- a/files/en-us/learn_web_development/core/frameworks_libraries/angular_filtering/index.md +++ b/files/en-us/learn_web_development/core/frameworks_libraries/angular_filtering/index.md @@ -2,9 +2,10 @@ title: Filtering our to-do items slug: Learn_web_development/Core/Frameworks_libraries/Angular_filtering page-type: learn-module-chapter +sidebar: learnsidebar --- -{{LearnSidebar}}{{PreviousMenuNext("Learn_web_development/Core/Frameworks_libraries/Angular_item_component","Learn_web_development/Core/Frameworks_libraries/Angular_building", "Learn_web_development/Core/Frameworks_libraries")}} +{{PreviousMenuNext("Learn_web_development/Core/Frameworks_libraries/Angular_item_component","Learn_web_development/Core/Frameworks_libraries/Angular_building", "Learn_web_development/Core/Frameworks_libraries")}} Now let's move on to adding functionality to allow users to filter their to-do items, so they can view active, completed, or all items. @@ -35,7 +36,11 @@ Now let's move on to adding functionality to allow users to filter their to-do i Filtering items builds on the `filter` property, which you previously added to `app.component.ts`: ```ts -filter: 'all' | 'active' | 'done' = 'all'; +export class AppComponent { + // … + filter: "all" | "active" | "done" = "all"; + // … +} ``` The default value for filter is `all`, but it can also be `active` or `done`. @@ -53,21 +58,21 @@ In the following snippet, the existing sections in your HTML are in comments so <div class="btn-wrapper"> <button class="btn btn-menu" - [class.active]="filter == 'all'" + [class.active]="filter === 'all'" (click)="filter = 'all'"> All </button> <button class="btn btn-menu" - [class.active]="filter == 'active'" + [class.active]="filter === 'active'" (click)="filter = 'active'"> To Do </button> <button class="btn btn-menu" - [class.active]="filter == 'done'" + [class.active]="filter === 'done'" (click)="filter = 'done'"> Done </button> @@ -85,7 +90,7 @@ Clicking the buttons changes the `filter` values, which determines the `items` t A class attribute binding, using square brackets, `[]`, controls the text color of the buttons. The class binding, `[class.active]`, applies the `active` class when the value of `filter` matches the expression. -For example, when the user clicks the **Done** button, which sets the `filter` value to `done`, the class binding expression of `filter == 'done'` evaluates to `true`. +For example, when the user clicks the **Done** button, which sets the `filter` value to `done`, the class binding expression of `filter === 'done'` evaluates to `true`. When the `filter` value is `done`, Angular applies the `active` class to the **Done** button to make the text color green. As soon as the user clicks on one of the other buttons, the value a `filter` is no longer `done`, so the green text color no longer applies. diff --git a/files/en-us/learn_web_development/core/frameworks_libraries/angular_getting_started/index.md b/files/en-us/learn_web_development/core/frameworks_libraries/angular_getting_started/index.md index 1d6df5b77bb91fe..29f4a4467cdb3d2 100644 --- a/files/en-us/learn_web_development/core/frameworks_libraries/angular_getting_started/index.md +++ b/files/en-us/learn_web_development/core/frameworks_libraries/angular_getting_started/index.md @@ -2,10 +2,9 @@ title: Getting started with Angular slug: Learn_web_development/Core/Frameworks_libraries/Angular_getting_started page-type: learn-module-chapter +sidebar: learnsidebar --- -{{LearnSidebar}} - {{NextMenu("Learn_web_development/Core/Frameworks_libraries/Angular_todo_list_beginning", "Learn_web_development/Core/Frameworks_libraries")}} It is now time to look at Google's Angular framework, another popular option that you'll come across often. In this article we look at what Angular has to offer, install the prerequisites and set up a sample app, and look at Angular's basic architecture. @@ -72,7 +71,7 @@ To install Angular on your local system, you need the following: Angular requires a [active LTS or maintenance LTS](https://nodejs.org/en/about/previous-releases) version of Node.js. For information about specific version requirements, see the [Version compatibility](https://angular.dev/reference/versions) page. - For more information on installing Node.js, see [nodejs.org](https://nodejs.org/en/download/package-manager). + For more information on installing Node.js, see [nodejs.org](https://nodejs.org/en/download). If you are unsure what version of Node.js runs on your system, run `node -v` in a terminal window. - **npm package manager** @@ -173,7 +172,7 @@ So, you could have files with names such as `header.component.ts`, `signup.compo You create a component with a `@Component()` decorator that has metadata that tells Angular where to find the HTML and CSS. A typical component is as follows: -```js +```ts import { Component } from "@angular/core"; @Component({ @@ -190,7 +189,7 @@ export class ItemComponent { ``` This component is called `ItemComponent`, and its selector is `app-item`. -You use a selector just like regular HTML tags by placing it within other templates, i.e. `<app-item></app-item>`. +You use a selector just like regular HTML tags by placing it within other templates, i.e., `<app-item></app-item>`. When a selector is in a template, the browser renders the template of that component whenever an instance of the selector is encountered. This tutorial guides you through creating two components and using one within the other. @@ -208,7 +207,7 @@ You can define this template either inline or by file path. To refer to an external HTML file, use the `templateUrl` property: -```js +```ts @Component({ selector: "app-root", templateUrl: "./app.component.html", @@ -220,7 +219,7 @@ export class AppComponent { To write inline HTML, use the `template` property and write your HTML within backticks: -```js +```ts @Component({ selector: "app-root", template: `<h1>To do application</h1>`, @@ -241,7 +240,7 @@ One use of this feature is inserting dynamic text, as shown in the following exa The double curly braces instruct Angular to interpolate the contents within them. The value for `title` comes from the component class: -```js-nolint +```ts import { Component } from "@angular/core"; @Component({ @@ -269,23 +268,29 @@ You can write component-specific styles directly in the `@Component()` decorator To include the styles directly in the component decorator, use the `styles` property: -```js +```ts @Component({ - selector: 'app-root', - templateUrl: './app.component.html', - styles: ['h1 { color: red; }'] + selector: "app-root", + templateUrl: "./app.component.html", + styles: ["h1 { color: red; }"], }) +export class AppComponent { + // … +} ``` Typically, a component uses styles in a separate file. You can use the `styleUrl` property with the path to the CSS file as a string or `styleUrls` with an array of strings if there are multiple CSS stylesheets you want to include: -```js +```ts @Component({ - selector: 'app-root', - templateUrl: './app.component.html', - styleUrl: './app.component.css' + selector: "app-root", + templateUrl: "./app.component.html", + styleUrl: "./app.component.css", }) +export class AppComponent { + // … +} ``` With component-specific styles, you can organize your CSS so that it is easily maintainable and portable. @@ -297,17 +302,20 @@ This tutorial uses [standalone components](https://angular.dev/guide/components/ It's common to import [`CommonModule`](https://angular.dev/api/common/CommonModule) so that your component can make use of common [directives](https://angular.dev/guide/directives) and [pipes](https://angular.dev/guide/pipes). -```js +```ts import { Component } from "@angular/core"; -import { CommonModule } from '@angular/common'; +import { CommonModule } from "@angular/common"; @Component({ standalone: true, - selector: 'app-root', - templateUrl: './app.component.html', - styleUrl: './app.component.css', + selector: "app-root", + templateUrl: "./app.component.html", + styleUrl: "./app.component.css", imports: [CommonModule], }) +export class AppComponent { + // … +} ``` ## Summary diff --git a/files/en-us/learn_web_development/core/frameworks_libraries/angular_item_component/index.md b/files/en-us/learn_web_development/core/frameworks_libraries/angular_item_component/index.md index 0cd8d907c01c68e..09848bfa651f2a6 100644 --- a/files/en-us/learn_web_development/core/frameworks_libraries/angular_item_component/index.md +++ b/files/en-us/learn_web_development/core/frameworks_libraries/angular_item_component/index.md @@ -2,9 +2,10 @@ title: Creating an item component slug: Learn_web_development/Core/Frameworks_libraries/Angular_item_component page-type: learn-module-chapter +sidebar: learnsidebar --- -{{LearnSidebar}}{{PreviousMenuNext("Learn_web_development/Core/Frameworks_libraries/Angular_styling","Learn_web_development/Core/Frameworks_libraries/Angular_filtering", "Learn_web_development/Core/Frameworks_libraries")}} +{{PreviousMenuNext("Learn_web_development/Core/Frameworks_libraries/Angular_styling","Learn_web_development/Core/Frameworks_libraries/Angular_filtering", "Learn_web_development/Core/Frameworks_libraries")}} Components provide a way for you to organize your application. This article walks you through creating a component to handle the individual items in the list, and adding check, edit, and delete functionality. The Angular event model is covered here. @@ -62,14 +63,17 @@ Just as with the `AppComponent`, the `ItemComponent` is made up of the following You can see a reference to the HTML and CSS files in the `@Component()` decorator metadata in `item.component.ts`. -```js +```ts @Component({ - selector: 'app-item', + selector: "app-item", standalone: true, imports: [], - templateUrl: './item.component.html', - styleUrl: './item.component.css' + templateUrl: "./item.component.html", + styleUrl: "./item.component.css", }) +export class ItemComponent { + // … +} ``` ## Add HTML for the ItemComponent @@ -186,9 +190,13 @@ import { ItemComponent } from "./item/item.component"; Then, configure the AppComponent by adding the following to the same file's class: -```js -remove(item: Item) { - this.allItems.splice(this.allItems.indexOf(item), 1); +```ts +export class AppComponent { + // … + remove(item: Item) { + this.allItems.splice(this.allItems.indexOf(item), 1); + } + // … } ``` @@ -201,7 +209,7 @@ For more information on the `splice()` method, see the [`Array.prototype.splice( To use the `ItemComponent` UI, you must add logic to the component such as functions, and ways for data to go in and out. In `item.component.ts`, edit the JavaScript imports as follows: -```js +```ts import { Component, Input, Output, EventEmitter } from "@angular/core"; import { CommonModule } from "@angular/common"; import { Item } from "../item"; @@ -211,21 +219,23 @@ The addition of `Input`, `Output`, and `EventEmitter` allows `ItemComponent` to By importing `Item`, the `ItemComponent` can understand what an `item` is. You can update the `@Component` to use [`CommonModule`](https://angular.dev/api/common/CommonModule) in `app/item/item.component.ts` so that we can use the `@if` blocks: -```js +```ts @Component({ - selector: 'app-item', + selector: "app-item", standalone: true, imports: [CommonModule], - templateUrl: './item.component.html', - styleUrl: './item.component.css', + templateUrl: "./item.component.html", + styleUrl: "./item.component.css", }) +export class ItemComponent { + // … +} ``` Further down `item.component.ts`, replace the generated `ItemComponent` class with the following: -```js +```ts export class ItemComponent { - editable = false; @Input() item!: Item; @@ -275,10 +285,14 @@ To use the `ItemComponent` in `AppComponent`, put the `ItemComponent` selector i Angular specifies the selector of a component in the metadata of the `@Component()` decorator. In this example, we've defined the selector as `app-item`: -```js +```ts @Component({ - selector: 'app-item', - // ... + selector: "app-item", + // … +}) +export class ItemComponent { + // … +} ``` To use the `ItemComponent` selector within the `AppComponent`, you add the element, `<app-item>`, which corresponds to the selector you defined for the component class to `app.component.html`. @@ -301,14 +315,17 @@ Replace the current unordered list `<ul>` in `app.component.html` with the follo Change the `imports` in `app.component.ts` to include `ItemComponent` as well as `CommonModule`: -```js +```ts @Component({ standalone: true, - selector: 'app-root', - templateUrl: './app.component.html', - styleUrl: './app.component.css', + selector: "app-root", + templateUrl: "./app.component.html", + styleUrl: "./app.component.css", imports: [CommonModule, ItemComponent], }) +export class AppComponent { + // … +} ``` The double curly brace syntax, `\{{}}`, in the `<h2>` interpolates the length of the `items` array and displays the number. diff --git a/files/en-us/learn_web_development/core/frameworks_libraries/angular_styling/index.md b/files/en-us/learn_web_development/core/frameworks_libraries/angular_styling/index.md index 115bf046cdcd92c..c8fc80f3023f2a8 100644 --- a/files/en-us/learn_web_development/core/frameworks_libraries/angular_styling/index.md +++ b/files/en-us/learn_web_development/core/frameworks_libraries/angular_styling/index.md @@ -2,9 +2,10 @@ title: Styling our Angular app slug: Learn_web_development/Core/Frameworks_libraries/Angular_styling page-type: learn-module-chapter +sidebar: learnsidebar --- -{{LearnSidebar}}{{PreviousMenuNext("Learn_web_development/Core/Frameworks_libraries/Angular_todo_list_beginning","Learn_web_development/Core/Frameworks_libraries/Angular_item_component", "Learn_web_development/Core/Frameworks_libraries")}} +{{PreviousMenuNext("Learn_web_development/Core/Frameworks_libraries/Angular_todo_list_beginning","Learn_web_development/Core/Frameworks_libraries/Angular_item_component", "Learn_web_development/Core/Frameworks_libraries")}} Now that we've got our basic application structure set up and started displaying something useful, let's switch gears and spend an article looking at how Angular handles styling of applications. diff --git a/files/en-us/learn_web_development/core/frameworks_libraries/angular_todo_list_beginning/index.md b/files/en-us/learn_web_development/core/frameworks_libraries/angular_todo_list_beginning/index.md index a9dab0de399a0e6..8fae7a23735b82c 100644 --- a/files/en-us/learn_web_development/core/frameworks_libraries/angular_todo_list_beginning/index.md +++ b/files/en-us/learn_web_development/core/frameworks_libraries/angular_todo_list_beginning/index.md @@ -2,9 +2,10 @@ title: Beginning our Angular todo list app slug: Learn_web_development/Core/Frameworks_libraries/Angular_todo_list_beginning page-type: learn-module-chapter +sidebar: learnsidebar --- -{{LearnSidebar}}{{PreviousMenuNext("Learn_web_development/Core/Frameworks_libraries/Angular_getting_started","Learn_web_development/Core/Frameworks_libraries/Angular_styling", "Learn_web_development/Core/Frameworks_libraries")}} +{{PreviousMenuNext("Learn_web_development/Core/Frameworks_libraries/Angular_getting_started","Learn_web_development/Core/Frameworks_libraries/Angular_styling", "Learn_web_development/Core/Frameworks_libraries")}} At this point, we are ready to start creating our to-do list application using Angular. The finished application will display a list of to-do items and includes editing, deleting, and adding features. In this article you will get to know your application structure, and work up to displaying a basic list of to-do items. @@ -100,15 +101,15 @@ You won't use this file until [later](/en-US/docs/Learn_web_development/Core/Fra Now that you know what an `item` is, you can give your application some items by adding them to the app. In `app.component.ts`, replace the contents with the following: -```js +```ts import { Component } from "@angular/core"; import { CommonModule } from "@angular/common"; @Component({ standalone: true, - selector: 'app-root', - templateUrl: './app.component.html', - styleUrl: './app.component.css', + selector: "app-root", + templateUrl: "./app.component.html", + styleUrl: "./app.component.css", imports: [CommonModule], }) export class AppComponent { @@ -128,7 +129,7 @@ export class AppComponent { return this.allItems; } return this.allItems.filter((item) => - this.filter === "done" ? item.done : !item.done + this.filter === "done" ? item.done : !item.done, ); } } @@ -200,13 +201,17 @@ A to-do list needs a way to add items, so let's get started. In `app.component.ts`, add the following method to the class after the `allItems` array: ```ts -addItem(description: string) { - if (!description) return; - - this.allItems.unshift({ - description, - done: false - }); +export class AppComponent { + // … + addItem(description: string) { + if (!description) return; + + this.allItems.unshift({ + description, + done: false, + }); + } + // … } ``` diff --git a/files/en-us/learn_web_development/core/frameworks_libraries/ember_conditional_footer/index.md b/files/en-us/learn_web_development/core/frameworks_libraries/ember_conditional_footer/index.md index fd00fc193e9c676..c3da654508e53d8 100644 --- a/files/en-us/learn_web_development/core/frameworks_libraries/ember_conditional_footer/index.md +++ b/files/en-us/learn_web_development/core/frameworks_libraries/ember_conditional_footer/index.md @@ -2,12 +2,12 @@ title: "Ember Interactivity: Footer functionality, conditional rendering" slug: Learn_web_development/Core/Frameworks_libraries/Ember_conditional_footer page-type: learn-module-chapter +sidebar: learnsidebar --- -{{LearnSidebar}} {{PreviousMenuNext("Learn_web_development/Core/Frameworks_libraries/Ember_interactivity_events_state","Learn_web_development/Core/Frameworks_libraries/Ember_routing", "Learn_web_development/Core/Frameworks_libraries")}} -Now it's time to start tackling the footer functionality in our app. Here we'll get the todo counter to update to show the correct number of todos still to complete, and correctly apply styling to completed todos (i.e. where the checkbox has been checked). We'll also wire up our "Clear completed" button. Along the way, we'll learn about using conditional rendering in our templates. +Now it's time to start tackling the footer functionality in our app. Here we'll get the todo counter to update to show the correct number of todos still to complete, and correctly apply styling to completed todos (i.e., where the checkbox has been checked). We'll also wire up our "Clear completed" button. Along the way, we'll learn about using conditional rendering in our templates. <table> <tbody> @@ -58,7 +58,7 @@ To get the footer working, we need to implement the following three areas of fun 2. Next, go and find the newly-created `todomvc/app/components/footer.js` file and update it to the following: - ```js + ```ts import Component from "@glimmer/component"; import { inject as service } from "@ember/service"; @@ -71,9 +71,13 @@ To get the footer working, we need to implement the following three areas of fun In `todo-data.js`, add the following getter underneath the existing `all()` getter to define what the incomplete todos actually are: - ```js - get incomplete() { - return this.todos.filter((todo) => !todo.isCompleted); + ```ts + export default class TodoDataService extends Service { + // … + get incomplete() { + return this.todos.filter((todo) => !todo.isCompleted); + } + // … } ``` @@ -81,10 +85,14 @@ To get the footer working, we need to implement the following three areas of fun 4. Next, add the following action underneath the existing `add(text)` action: - ```js - @action - clearCompleted() { - this.todos = this.incomplete; + ```ts + export default class TodoDataService extends Service { + // … + @action + clearCompleted() { + this.todos = this.incomplete; + } + // … } ``` @@ -146,11 +154,15 @@ with the following: This will give us an error, however — in Ember, these simple if statements can currently only test for a truthy/falsy value, not a more complex expression such as a comparison. To fix this, we'll have to add a getter to `todo-data.js` to return the result of `this.incomplete.length === 1`, and then call that in our template. -Add the following new getter to `todo-data.js`, just below the existing getters. Note that here we need `this.incomplete.length`, not `this.todos.incomplete.length`, because we are doing this inside the service, where the `incomplete()` getter is available directly (in the template, the contents of the service has been made available as `todos` via the `@service('todo-data') todos;` line inside the footer class, hence it being `this.todos.incomplete.length` there). +Add the following new getter to `todo-data.js`, just below the existing getters. Note that here we need `this.incomplete.length`, not `this.todos.incomplete.length`, because we are doing this inside the service, where the `incomplete()` getter is available directly (in the template, the contents of the service has been made available as `todos` via the `@service("todo-data") todos;` line inside the footer class, hence it being `this.todos.incomplete.length` there). -```js -get todoCountIsOne() { - return this.incomplete.length === 1; +```ts +export default class TodoDataService extends Service { + // … + get todoCountIsOne() { + return this.incomplete.length === 1; + } + // … } ``` @@ -183,7 +195,7 @@ As with the other components, we need a class to access the service. 2. Now go to the newly-created `todomvc/app/components/todo.js` file and update the contents to look like so, to give the todo component access to the service: - ```js + ```ts import Component from "@glimmer/component"; import { inject as service } from "@ember/service"; @@ -194,10 +206,14 @@ As with the other components, we need a class to access the service. 3. Next, go back again to our `todo-data.js` service file and add the following action just below the previous ones, which will allow us to toggle a completion state for each todo: - ```js - @action - toggleCompletion(todo) { - todo.isCompleted = !todo.isCompleted; + ```ts + export default class TodoDataService extends Service { + // … + @action + toggleCompletion(todo) { + todo.isCompleted = !todo.isCompleted; + } + // … } ``` diff --git a/files/en-us/learn_web_development/core/frameworks_libraries/ember_getting_started/index.md b/files/en-us/learn_web_development/core/frameworks_libraries/ember_getting_started/index.md index ec6d9709741007e..5bfafe03246671c 100644 --- a/files/en-us/learn_web_development/core/frameworks_libraries/ember_getting_started/index.md +++ b/files/en-us/learn_web_development/core/frameworks_libraries/ember_getting_started/index.md @@ -2,10 +2,9 @@ title: Getting started with Ember slug: Learn_web_development/Core/Frameworks_libraries/Ember_getting_started page-type: learn-module-chapter +sidebar: learnsidebar --- -{{LearnSidebar}} - {{NextMenu("Learn_web_development/Core/Frameworks_libraries/Ember_structure_componentization", "Learn_web_development/Core/Frameworks_libraries")}} In our first Ember article we will look at how Ember works and what it's useful for, install the Ember toolchain locally, create a sample app, and then do some initial setup to get it ready for development. diff --git a/files/en-us/learn_web_development/core/frameworks_libraries/ember_interactivity_events_state/index.md b/files/en-us/learn_web_development/core/frameworks_libraries/ember_interactivity_events_state/index.md index dec53cc6541218a..bc690a309f60233 100644 --- a/files/en-us/learn_web_development/core/frameworks_libraries/ember_interactivity_events_state/index.md +++ b/files/en-us/learn_web_development/core/frameworks_libraries/ember_interactivity_events_state/index.md @@ -2,9 +2,9 @@ title: "Ember interactivity: Events, classes and state" slug: Learn_web_development/Core/Frameworks_libraries/Ember_interactivity_events_state page-type: learn-module-chapter +sidebar: learnsidebar --- -{{LearnSidebar}} {{PreviousMenuNext("Learn_web_development/Core/Frameworks_libraries/Ember_structure_componentization","Learn_web_development/Core/Frameworks_libraries/Ember_conditional_footer", "Learn_web_development/Core/Frameworks_libraries")}} At this point we'll start adding some interactivity to our app, providing the ability to add and display new todo items. Along the way, we'll look at using events in Ember, creating component classes to contain JavaScript code to control interactive features, and setting up a service to keep track of the data state of our app. @@ -208,7 +208,10 @@ import { inject as service } from "@ember/service"; With this import in place, we can now make the `todo-data` service available inside the `HeaderComponent` class via the `todos` object, using the `@service` decorator. Add the following line just below the opening `export…` line: ```js -@service('todo-data') todos; +export default class HeaderComponent extends Component { + @service("todo-data") todos; + // … +} ``` Now the placeholder `alert(text);` line can be replaced with a call to our new `add()` function. Replace it with the following: @@ -249,8 +252,13 @@ One issue here is that our service is called `todos`, but the list of todos is a To do this, go back to your `todo-data.js` file and add the following below the `@tracked todos = [];` line: ```js -get all() { - return this.todos; +export default class TodoDataService extends Service { + @tracked todos = []; + + get all() { + return this.todos; + } + // … } ``` diff --git a/files/en-us/learn_web_development/core/frameworks_libraries/ember_resources/index.md b/files/en-us/learn_web_development/core/frameworks_libraries/ember_resources/index.md index 82f8dcf3cf72fc0..b1bb897eabeb87e 100644 --- a/files/en-us/learn_web_development/core/frameworks_libraries/ember_resources/index.md +++ b/files/en-us/learn_web_development/core/frameworks_libraries/ember_resources/index.md @@ -2,10 +2,9 @@ title: Ember resources and troubleshooting slug: Learn_web_development/Core/Frameworks_libraries/Ember_resources page-type: learn-module-chapter +sidebar: learnsidebar --- -{{LearnSidebar}} - {{PreviousMenu("Learn_web_development/Core/Frameworks_libraries/Ember_routing", "Learn_web_development/Core/Frameworks_libraries")}} Our final Ember article provides you with a list of resources that you can use to go further in your learning, plus some useful troubleshooting and other information. diff --git a/files/en-us/learn_web_development/core/frameworks_libraries/ember_routing/index.md b/files/en-us/learn_web_development/core/frameworks_libraries/ember_routing/index.md index ccfed2cc17b6abf..28a7a630b590cfb 100644 --- a/files/en-us/learn_web_development/core/frameworks_libraries/ember_routing/index.md +++ b/files/en-us/learn_web_development/core/frameworks_libraries/ember_routing/index.md @@ -2,9 +2,9 @@ title: Routing in Ember slug: Learn_web_development/Core/Frameworks_libraries/Ember_routing page-type: learn-module-chapter +sidebar: learnsidebar --- -{{LearnSidebar}} {{PreviousMenuNext("Learn_web_development/Core/Frameworks_libraries/Ember_conditional_footer","Learn_web_development/Core/Frameworks_libraries/Ember_resources", "Learn_web_development/Core/Frameworks_libraries")}} In this article we learn about **routing**, or URL-based filtering as it is sometimes referred to. We'll use it to provide a unique URL for each of the three todo views — "All", "Active", and "Completed". @@ -119,8 +119,12 @@ But now we need a way to differentiate between each of these routes, so that the First of all, return once more to our `todo-data.js` file. It already contains a getter that returns all todos, and a getter that returns incomplete todos. The getter we are missing is one to return just the completed todos. Add the following below the existing getters: ```js -get completed() { - return this.todos.filter((todo) => todo.isCompleted); +export default class TodoDataService extends Service { + // … + get completed() { + return this.todos.filter((todo) => todo.isCompleted); + } + // … } ``` diff --git a/files/en-us/learn_web_development/core/frameworks_libraries/ember_structure_componentization/index.md b/files/en-us/learn_web_development/core/frameworks_libraries/ember_structure_componentization/index.md index c0eee50ca711fb1..319e77ca0af6438 100644 --- a/files/en-us/learn_web_development/core/frameworks_libraries/ember_structure_componentization/index.md +++ b/files/en-us/learn_web_development/core/frameworks_libraries/ember_structure_componentization/index.md @@ -2,9 +2,9 @@ title: Ember app structure and componentization slug: Learn_web_development/Core/Frameworks_libraries/Ember_structure_componentization page-type: learn-module-chapter +sidebar: learnsidebar --- -{{LearnSidebar}} {{PreviousMenuNext("Learn_web_development/Core/Frameworks_libraries/Ember_getting_started","Learn_web_development/Core/Frameworks_libraries/Ember_interactivity_events_state", "Learn_web_development/Core/Frameworks_libraries")}} In this article we'll get right on with planning out the structure of our TodoMVC Ember app, adding in the HTML for it, and then breaking that HTML structure into components. @@ -71,7 +71,7 @@ However, we don't want this. Instead, we want it to contain the TodoMVC app stru </section> ``` -> **Note:** [`aria-label`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-label) provides a label for assistive technology to make use of — for example, for a screen reader to read out. This is useful in such cases where we have an [`<input>`](/en-US/docs/Web/HTML/Element/input) being used with no corresponding HTML text that could be turned into a label. +> **Note:** [`aria-label`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-label) provides a label for assistive technology to make use of — for example, for a screen reader to read out. This is useful in such cases where we have an [`<input>`](/en-US/docs/Web/HTML/Reference/Elements/input) being used with no corresponding HTML text that could be turned into a label. When you save `application.hbs`, the development server you started earlier will automatically rebuild the app and refresh the browser. The rendered output should now look like this: diff --git a/files/en-us/learn_web_development/core/frameworks_libraries/index.md b/files/en-us/learn_web_development/core/frameworks_libraries/index.md index 6914a73a87d0a24..71a4c99429620d0 100644 --- a/files/en-us/learn_web_development/core/frameworks_libraries/index.md +++ b/files/en-us/learn_web_development/core/frameworks_libraries/index.md @@ -2,10 +2,9 @@ title: JavaScript frameworks and libraries slug: Learn_web_development/Core/Frameworks_libraries page-type: learn-module +sidebar: learnsidebar --- -{{LearnSidebar}} - {{NextMenu("Learn_web_development/Core/Frameworks_libraries/Introduction", "Learn_web_development/Core")}} JavaScript frameworks are an essential part of modern front-end web development, providing developers with tried and tested tools for building scalable, interactive web applications. Many modern companies use frameworks as a standard part of their tooling, so many front-end development jobs now require framework experience. In this set of articles, we are aiming to give you a comfortable starting point to help you begin learning frameworks. @@ -23,6 +22,9 @@ After that, we'll provide some tutorials covering the essentials React, a popula We also provide some tutorials covering the basics of other framework choices, for those who want to make a different choice to React. +> [!NOTE] +> Scrimba's [Libraries/Frameworks](https://scrimba.com/learn-react-c0e/~033a?via=mdn) <sup>[_MDN learning partner_](/en-US/docs/MDN/Writing_guidelines/Learning_content#partner_links_and_embeds)</sup> interactive tutorial provides a useful summary of frameworks versus libraries, a brief history of libraries and frameworks on the web, and some background information specifically on React. + ## Prerequisites You should really learn the basics of the core web languages first before attempting to move on to learning client-side frameworks — [HTML](/en-US/docs/Learn_web_development/Core/Structuring_content), [CSS](/en-US/docs/Learn_web_development/Core/Styling_basics), and especially [JavaScript](/en-US/docs/Learn_web_development/Core/Scripting). @@ -45,7 +47,7 @@ Your code will be richer and more professional as a result, and you'll be able t - [Getting started with React](/en-US/docs/Learn_web_development/Core/Frameworks_libraries/React_getting_started) - : In this article we will say hello to React. We'll discover a little bit of detail about its background and use cases, set up a basic React toolchain on our local computer, and create and play with a simple starter app, learning a bit about how React works in the process. -- [Beginning our React todo list](/en-US/docs/Learn_web_development/Core/Frameworks_libraries/React_todo_list_beginning) +- [Beginning our React ToDo app](/en-US/docs/Learn_web_development/Core/Frameworks_libraries/React_todo_list_beginning) - : Let's say that we've been tasked with creating a proof-of-concept in React – an app that allows users to add, edit, and delete tasks they want to work on, and also mark tasks as complete without deleting them. This article will walk you through putting the basic `App` component structure and styling in place, ready for individual component definition and interactivity, which we'll add later. - [Componentizing our React app](/en-US/docs/Learn_web_development/Core/Frameworks_libraries/React_components) - : At this point, our app is a monolith. Before we can make it do things, we need to break it apart into manageable, descriptive components. React doesn't have any hard rules for what is and isn't a component – that's up to you! In this article, we will show you a sensible way to break our app up into components. @@ -74,7 +76,7 @@ Your code will be richer and more professional as a result, and you'll be able t - [Ember interactivity: Events, classes and state](/en-US/docs/Learn_web_development/Core/Frameworks_libraries/Ember_interactivity_events_state) - : At this point we'll start adding some interactivity to our app, providing the ability to add and display new todo items. Along the way, we'll look at using events in Ember, creating component classes to contain JavaScript code to control interactive features, and setting up a service to keep track of the data state of our app. - [Ember Interactivity: Footer functionality, conditional rendering](/en-US/docs/Learn_web_development/Core/Frameworks_libraries/Ember_conditional_footer) - - : Now it's time to start tackling the footer functionality in our app. Here we'll get the todo counter to update to show the correct number of todos still to complete, and correctly apply styling to completed todos (i.e. where the checkbox has been checked). We'll also wire up our "Clear completed" button. Along the way, we'll learn about using conditional rendering in our templates. + - : Now it's time to start tackling the footer functionality in our app. Here we'll get the todo counter to update to show the correct number of todos still to complete, and correctly apply styling to completed todos (i.e., where the checkbox has been checked). We'll also wire up our "Clear completed" button. Along the way, we'll learn about using conditional rendering in our templates. - [Routing in Ember](/en-US/docs/Learn_web_development/Core/Frameworks_libraries/Ember_routing) - : In this article we learn about routing or URL-based filtering as it is sometimes referred to. We'll use it to provide a unique URL for each of the three todo views — "All", "Active", and "Completed". - [Ember resources and troubleshooting](/en-US/docs/Learn_web_development/Core/Frameworks_libraries/Ember_resources) diff --git a/files/en-us/learn_web_development/core/frameworks_libraries/introduction/index.md b/files/en-us/learn_web_development/core/frameworks_libraries/introduction/index.md index 0616ef5992dabd3..c90d9f5cd925358 100644 --- a/files/en-us/learn_web_development/core/frameworks_libraries/introduction/index.md +++ b/files/en-us/learn_web_development/core/frameworks_libraries/introduction/index.md @@ -1,11 +1,11 @@ --- title: Introduction to client-side frameworks +short-title: Introduction slug: Learn_web_development/Core/Frameworks_libraries/Introduction page-type: learn-module-chapter +sidebar: learnsidebar --- -{{LearnSidebar}} - {{NextMenu("Learn_web_development/Core/Frameworks_libraries/Main_features", "Learn_web_development/Core/Frameworks_libraries")}} We begin our look at frameworks with a general overview of the area, looking at a brief history of JavaScript and frameworks, why frameworks exist and what they give us, how to start thinking about choosing a framework to learn, and what alternatives there are to client-side frameworks. @@ -93,7 +93,7 @@ const state = [ ]; ``` -How do we show one of those tasks to our users? We want to represent each task as a list item – an HTML [`<li>`](/en-US/docs/Web/HTML/Element/li) element inside of an unordered list element (a [`<ul>`](/en-US/docs/Web/HTML/Element/ul)). How do we make it? That could look something like this: +How do we show one of those tasks to our users? We want to represent each task as a list item – an HTML [`<li>`](/en-US/docs/Web/HTML/Reference/Elements/li) element inside of an unordered list element (a [`<ul>`](/en-US/docs/Web/HTML/Reference/Elements/ul)). How do we make it? That could look something like this: ```js function buildTodoItemEl(id, name) { @@ -229,7 +229,7 @@ Frameworks are not the source of our problems. With the wrong priorities, any ap ## Accessibility on a framework-driven web -Let's build on what we said in the previous section, and talk a bit more about accessibility. Making user interfaces accessible always requires some thought and effort, and frameworks can complicate that process. You often have to employ advanced framework APIs to access native browser features like ARIA [live regions](/en-US/docs/Web/Accessibility/ARIA/ARIA_Live_Regions) or focus management. +Let's build on what we said in the previous section, and talk a bit more about accessibility. Making user interfaces accessible always requires some thought and effort, and frameworks can complicate that process. You often have to employ advanced framework APIs to access native browser features like ARIA [live regions](/en-US/docs/Web/Accessibility/ARIA/Guides/Live_regions) or focus management. In some cases, framework applications create accessibility barriers that do not exist for traditional websites. The biggest example of this is in client-side routing, as mentioned earlier. @@ -287,7 +287,7 @@ If you're looking for tools to expedite the web development process, and you kno **Content-management systems** (**CMSes**) are any tools that allow a user to create content for the web without directly writing code themselves. They're a good solution for large projects, especially projects that require input from content writers who have limited coding ability, or for programmers who want to save time. They do, however, require a significant amount of time to set up, and utilizing a CMS means that you surrender at least some measure of control over the final output of your website. For example: if your chosen CMS doesn't author accessible content by default, it's often difficult to improve this. -A few popular CMS systems include [WordPress](https://wordpress.com/), [Joomla](https://www.joomla.org/), and [Drupal](https://www.drupal.org/). +A few popular CMS systems include [WordPress](https://wordpress.com/), [Joomla](https://www.joomla.org/), and [Drupal](https://new.drupal.org/). ### Server-side rendering diff --git a/files/en-us/learn_web_development/core/frameworks_libraries/main_features/index.md b/files/en-us/learn_web_development/core/frameworks_libraries/main_features/index.md index f53f4673e368568..f45484eab5e33b5 100644 --- a/files/en-us/learn_web_development/core/frameworks_libraries/main_features/index.md +++ b/files/en-us/learn_web_development/core/frameworks_libraries/main_features/index.md @@ -1,12 +1,12 @@ --- title: Framework main features +short-title: Framework features slug: Learn_web_development/Core/Frameworks_libraries/Main_features page-type: learn-module-chapter +sidebar: learnsidebar --- -{{LearnSidebar}} - -{{PreviousMenuNext("Learn_web_development/Core/Frameworks_libraries/Main_features","Learn_web_development/Core/Frameworks_libraries/React_getting_started", "Learn_web_development/Core/Frameworks_libraries")}} +{{PreviousMenuNext("Learn_web_development/Core/Frameworks_libraries/Introduction","Learn_web_development/Core/Frameworks_libraries/React_getting_started", "Learn_web_development/Core/Frameworks_libraries")}} Each major JavaScript framework has a different approach to updating the DOM, handling browser events, and providing an enjoyable developer experience. This article will explore the main features of "the big 4" frameworks, looking at how frameworks tend to work from a high level, and the differences between them. @@ -50,7 +50,7 @@ const header = ( ); ``` -This expression represents an HTML [`<header>`](/en-US/docs/Web/HTML/Element/header) element with an [`<h1>`](/en-US/docs/Web/HTML/Element/Heading_Elements) element inside. The curly braces around `{subject}` tell the application to read the value of the `subject` constant and insert it into our `<h1>`. +This expression represents an HTML [`<header>`](/en-US/docs/Web/HTML/Reference/Elements/header) element with an [`<h1>`](/en-US/docs/Web/HTML/Reference/Elements/Heading_Elements) element inside. The curly braces around `{subject}` tell the application to read the value of the `subject` constant and insert it into our `<h1>`. When used with React, the JSX from the previous snippet would be compiled into this: @@ -87,9 +87,9 @@ Given this Handlebars template: And this data: -```js +```json { - subject: "World"; + "subject": "World" } ``` @@ -158,7 +158,7 @@ function AuthorCredit(props) { /> ``` -This will ultimately render the following [`<figure>`](/en-US/docs/Web/HTML/Element/figure) element in the browser, with its structure as defined in the `AuthorCredit` component, and its content as defined in the props included on the `AuthorCredit` component call: +This will ultimately render the following [`<figure>`](/en-US/docs/Web/HTML/Reference/Elements/figure) element in the browser, with its structure as defined in the `AuthorCredit` component, and its content as defined in the props included on the `AuthorCredit` component call: ```html <figure> @@ -320,4 +320,4 @@ it("Increments the count when clicked", () => { At this point you should have more of an idea about the actual languages, features, and tools you'll be using as you create applications with frameworks. I'm sure you're enthusiastic to get going and actually do some coding, and that's what you are going to do next! -{{PreviousMenuNext("Learn_web_development/Core/Frameworks_libraries/Main_features","Learn_web_development/Core/Frameworks_libraries/React_getting_started", "Learn_web_development/Core/Frameworks_libraries")}} +{{PreviousMenuNext("Learn_web_development/Core/Frameworks_libraries/Introduction","Learn_web_development/Core/Frameworks_libraries/React_getting_started", "Learn_web_development/Core/Frameworks_libraries")}} diff --git a/files/en-us/learn_web_development/core/frameworks_libraries/react_accessibility/index.md b/files/en-us/learn_web_development/core/frameworks_libraries/react_accessibility/index.md index fc7a758136d2501..acd2177dbbd7b02 100644 --- a/files/en-us/learn_web_development/core/frameworks_libraries/react_accessibility/index.md +++ b/files/en-us/learn_web_development/core/frameworks_libraries/react_accessibility/index.md @@ -1,11 +1,11 @@ --- title: Accessibility in React +short-title: React accessibility slug: Learn_web_development/Core/Frameworks_libraries/React_accessibility page-type: learn-module-chapter +sidebar: learnsidebar --- -{{LearnSidebar}} - {{PreviousMenuNext("Learn_web_development/Core/Frameworks_libraries/React_interactivity_filtering_conditional_rendering","Learn_web_development/Core/Frameworks_libraries/React_resources", "Learn_web_development/Core/Frameworks_libraries")}} In our final tutorial article, we'll focus on (pun intended) accessibility, including focus management in React, which can improve usability and reduce confusion for both keyboard-only and screen reader users. @@ -283,7 +283,7 @@ const listHeadingRef = useRef(null); ### Prepare the heading -Heading elements like our `<h2>` are not usually focusable. This isn't a problem — we can make any element programmatically focusable by adding the attribute [`tabindex="-1"`](/en-US/docs/Web/HTML/Global_attributes/tabindex) to it. This means _only focusable with JavaScript_. You can't press <kbd>Tab</kbd> to focus on an element with a tabindex of `-1` the same way you could do with a [`<button>`](/en-US/docs/Web/HTML/Element/button) or [`<a>`](/en-US/docs/Web/HTML/Element/a) element (this can be done using `tabindex="0"`, but that's not appropriate in this case). +Heading elements like our `<h2>` are not usually focusable. This isn't a problem — we can make any element programmatically focusable by adding the attribute [`tabindex="-1"`](/en-US/docs/Web/HTML/Reference/Global_attributes/tabindex) to it. This means _only focusable with JavaScript_. You can't press <kbd>Tab</kbd> to focus on an element with a tabindex of `-1` the same way you could do with a [`<button>`](/en-US/docs/Web/HTML/Reference/Elements/button) or [`<a>`](/en-US/docs/Web/HTML/Reference/Elements/a) element (this can be done using `tabindex="0"`, but that's not appropriate in this case). Let's add the `tabindex` attribute — written as `tabIndex` in JSX — to the heading above our list of tasks, along with our `listHeadingRef`: diff --git a/files/en-us/learn_web_development/core/frameworks_libraries/react_components/index.md b/files/en-us/learn_web_development/core/frameworks_libraries/react_components/index.md index ed899a6c0f5242e..af46c26951bfd0c 100644 --- a/files/en-us/learn_web_development/core/frameworks_libraries/react_components/index.md +++ b/files/en-us/learn_web_development/core/frameworks_libraries/react_components/index.md @@ -1,11 +1,11 @@ --- title: Componentizing our React app +short-title: React components slug: Learn_web_development/Core/Frameworks_libraries/React_components page-type: learn-module-chapter +sidebar: learnsidebar --- -{{LearnSidebar}} - {{PreviousMenuNext("Learn_web_development/Core/Frameworks_libraries/React_todo_list_beginning","Learn_web_development/Core/Frameworks_libraries/React_interactivity_events_state", "Learn_web_development/Core/Frameworks_libraries")}} At this point, our app is a monolith. Before we can make it do things, we need to break it apart into manageable, descriptive components. React doesn't have any hard rules for what is and isn't a component – that's up to you! In this article we will show you a sensible way to break our app up into components. @@ -59,7 +59,7 @@ function Todo() {} export default Todo; ``` -This is OK so far, but our component should return something useful! Go back to `src/App.jsx`, copy the first [`<li>`](/en-US/docs/Web/HTML/Element/li) from inside the unordered list, and paste it into `Todo.jsx` so that it reads like this: +This is OK so far, but our component should return something useful! Go back to `src/App.jsx`, copy the first [`<li>`](/en-US/docs/Web/HTML/Reference/Elements/li) from inside the unordered list, and paste it into `Todo.jsx` so that it reads like this: ```jsx function Todo() { @@ -122,9 +122,14 @@ In order to track the names of tasks we want to complete, we should ensure that In `App.jsx`, give each `<Todo />` a name prop. Let's use the names of our tasks that we had before: ```jsx -<Todo name="Eat" /> -<Todo name="Sleep" /> -<Todo name="Repeat" /> +<ul + role="list" + className="todo-list stack-large stack-exception" + aria-labelledby="list-heading"> + <Todo name="Eat" /> + <Todo name="Sleep" /> + <Todo name="Repeat" /> +</ul> ``` When your browser refreshes, you will see… the exact same thing as before. We gave our `<Todo />` some props, but we aren't using them yet. Let's go back to `Todo.jsx` and remedy that. @@ -169,9 +174,14 @@ _Now_ your browser should show three unique tasks. Another problem remains thoug In our original static list, only `Eat` was checked. Once again, we want to reuse _most_ of the UI that makes up a `<Todo />` component, but change one thing. That's a good job for another prop! Give your first `<Todo />` call a boolean prop of `completed`, and leave the other two as they are. ```jsx -<Todo name="Eat" completed /> -<Todo name="Sleep" /> -<Todo name="Repeat" /> +<ul + role="list" + className="todo-list stack-large stack-exception" + aria-labelledby="list-heading"> + <Todo name="Eat" completed /> + <Todo name="Sleep" /> + <Todo name="Repeat" /> +</ul> ``` As before, we must go back to `Todo.jsx` to actually use these props. Change the `defaultChecked` attribute on the `<input />` so that its value is equal to the `completed` prop. Once you're done, the Todo component's `<input />` element will read like this: @@ -190,17 +200,22 @@ If you change each `<Todo />` component's `completed` prop, your browser will ch We have still _another_ problem: our `<Todo />` component gives every task an `id` attribute of `todo-0`. This is bad for a couple of reasons: -- [`id` attributes](/en-US/docs/Web/HTML/Global_attributes/id) must be unique (they are used as unique identifiers for document fragments, by CSS, JavaScript, etc.). -- When `id`s are not unique, the functionality of [label elements](/en-US/docs/Web/HTML/Element/label) can break. +- [`id` attributes](/en-US/docs/Web/HTML/Reference/Global_attributes/id) must be unique (they are used as unique identifiers for document fragments, by CSS, JavaScript, etc.). +- When `id`s are not unique, the functionality of [label elements](/en-US/docs/Web/HTML/Reference/Elements/label) can break. The second problem is affecting our app right now. If you click on the word "Sleep" next to the second checkbox, you'll notice the "Eat" checkbox toggles instead of the "Sleep" checkbox. This is because every checkbox's `<label>` element has an `htmlFor` attribute of `todo-0`. The `<label>`s only acknowledge the first element with a given `id` attribute, which causes the problem you see when clicking on the other labels. We had unique `id` attributes before we created the `<Todo />` component. Let's bring them back, following the format of `todo-i`, where `i` gets larger by one every time. Update the `Todo` component instances inside `App.jsx` to add in `id` props, as follows: ```jsx -<Todo name="Eat" id="todo-0" completed /> -<Todo name="Sleep" id="todo-1" /> -<Todo name="Repeat" id="todo-2" /> +<ul + role="list" + className="todo-list stack-large stack-exception" + aria-labelledby="list-heading"> + <Todo name="Eat" id="todo-0" completed /> + <Todo name="Sleep" id="todo-1" /> + <Todo name="Repeat" id="todo-2" /> +</ul> ``` > [!NOTE] diff --git a/files/en-us/learn_web_development/core/frameworks_libraries/react_getting_started/index.md b/files/en-us/learn_web_development/core/frameworks_libraries/react_getting_started/index.md index f39eb7b6474e2d8..ba9c8384ee77aaf 100644 --- a/files/en-us/learn_web_development/core/frameworks_libraries/react_getting_started/index.md +++ b/files/en-us/learn_web_development/core/frameworks_libraries/react_getting_started/index.md @@ -1,11 +1,11 @@ --- title: Getting started with React +short-title: React getting started slug: Learn_web_development/Core/Frameworks_libraries/React_getting_started page-type: learn-module-chapter +sidebar: learnsidebar --- -{{LearnSidebar}} - {{PreviousMenuNext("Learn_web_development/Core/Frameworks_libraries/Main_features","Learn_web_development/Core/Frameworks_libraries/React_todo_list_beginning", "Learn_web_development/Core/Frameworks_libraries")}} In this article we will say hello to React. We'll discover a little bit of detail about its background and use cases, set up a basic React toolchain on our local computer, and create and play with a simple starter app — learning a bit about how React works in the process. @@ -56,9 +56,9 @@ React utilizes features of modern JavaScript for many of its patterns. Its bigge const heading = <h1>Mozilla Developer Network</h1>; ``` -This heading constant is known as a **JSX expression**. React can use it to render that [`<h1>`](/en-US/docs/Web/HTML/Element/Heading_Elements) tag in our app. +This heading constant is known as a **JSX expression**. React can use it to render that [`<h1>`](/en-US/docs/Web/HTML/Reference/Elements/Heading_Elements) tag in our app. -Suppose we wanted to wrap our heading in a [`<header>`](/en-US/docs/Web/HTML/Element/header) tag, for semantic reasons? The JSX approach allows us to nest our elements within each other, just like we do with HTML: +Suppose we wanted to wrap our heading in a [`<header>`](/en-US/docs/Web/HTML/Reference/Elements/header) tag, for semantic reasons? The JSX approach allows us to nest our elements within each other, just like we do with HTML: ```jsx const header = ( @@ -77,7 +77,7 @@ const header = ( > </header>; > ``` > -> However, this looks kind of awkward, because the [`<header>`](/en-US/docs/Web/HTML/Element/header) tag that starts the expression is not indented to the same position as its corresponding closing tag. +> However, this looks kind of awkward, because the [`<header>`](/en-US/docs/Web/HTML/Reference/Elements/header) tag that starts the expression is not indented to the same position as its corresponding closing tag. Of course, your browser can't read JSX without help. When compiled (using a tool like [Babel](https://babeljs.io/) or [Parcel](https://parceljs.org/)), our header expression would look like this: @@ -99,7 +99,11 @@ To read more about JSX, check out the React team's [Writing Markup with JSX](htt There are many ways to create a new React application. We're going to use Vite to create a new application via the command line. -It's possible to [add React to an existing project](https://react.dev/learn/add-react-to-an-existing-project) by copying some [`<script>`](/en-US/docs/Web/HTML/Element/script) elements into an HTML file, but using Vite will allow you to spend more time building your app and less time fussing with setup. +It's possible to [add React to an existing project](https://react.dev/learn/add-react-to-an-existing-project) by copying some [`<script>`](/en-US/docs/Web/HTML/Reference/Elements/script) elements into an HTML file, but using Vite will allow you to spend more time building your app and less time fussing with setup. + +> [!NOTE] +> You can start writing React code without doing _any_ local setup by working through Scrimba's [First React Code](https://scrimba.com/learn-react-c0e/~03uo?via=mdn) <sup>[_MDN learning partner_](/en-US/docs/MDN/Writing_guidelines/Learning_content#partner_links_and_embeds)</sup> scrim. +> Feel free to give it a try before continuing. ### Requirements @@ -179,7 +183,7 @@ moz-todo-react └── vite.config.js ``` -**`index.html`** is the most important top-level file. Vite injects your code into this file so that your browser can run it. You won't need to edit this file during our tutorial, but you should change the text inside the [`<title>`](/en-US/docs/Web/HTML/Element/title) element in this file to reflect the title of your application. Accurate page titles are important for accessibility. +**`index.html`** is the most important top-level file. Vite injects your code into this file so that your browser can run it. You won't need to edit this file during our tutorial, but you should change the text inside the [`<title>`](/en-US/docs/Web/HTML/Reference/Elements/title) element in this file to reflect the title of your application. Accurate page titles are important for accessibility. The **`public`** directory contains static files that will be served directly to your browser without being processed by Vite's build tooling. Right now, it only contains a Vite logo. @@ -209,8 +213,8 @@ Let's open `src/App.jsx`, since our browser is prompting us to edit it. This fil ```jsx import { useState } from "react"; -import reactLogo from "./assets/react.svg"; import viteLogo from "/vite.svg"; +import reactLogo from "./assets/react.svg"; import "./App.css"; function App() { @@ -253,8 +257,8 @@ The `import` statements at the top of the file allow `App.jsx` to use code that ```jsx import { useState } from "react"; -import reactLogo from "./assets/react.svg"; import viteLogo from "/vite.svg"; +import reactLogo from "./assets/react.svg"; import "./App.css"; ``` @@ -320,25 +324,25 @@ This export statement makes our `App()` function available to other modules. We' Let's open `src/main.jsx`, because that's where the `<App />` component is being used. This file is the entry point for our app, and it initially looks like this: ```jsx -import React from "react"; -import ReactDOM from "react-dom/client"; -import App from "./App.jsx"; +import { StrictMode } from "react"; +import { createRoot } from "react-dom/client"; import "./index.css"; +import App from "./App.jsx"; -ReactDOM.createRoot(document.getElementById("root")).render( - <React.StrictMode> +createRoot(document.getElementById("root")).render( + <StrictMode> <App /> - </React.StrictMode>, + </StrictMode>, ); ``` -As with `App.jsx`, the file starts by importing all the JS modules and other assets it needs to run. +As with `App.jsx`, the file starts by importing all the JavaScript modules and other assets it needs to run. -The first two statements import the `React` and `ReactDOM` libraries because they are referenced later in the file. We don't write a path or extension when importing these libraries because they are not local files. In fact, they are listed as dependencies in our `package.json` file. Be careful of this distinction as you work through this lesson! +The first two statements import `StrictMode` and `createRoot` from the `react` and `react-dom` libraries because they are referenced later in the file. We don't write a path or extension when importing these libraries because they are not local files. In fact, they are listed as dependencies in our `package.json` file. Be careful of this distinction as you work through this lesson! We then import our `App()` function and `index.css`, which holds global styles that are applied to our whole app. -We then call the `ReactDOM.createRoot()` function, which defines the root node of our application. This takes as an argument the DOM element inside which we want our React app to be rendered. In this case, that's the DOM element with an ID of `root`. Finally, we chain the `render()` method onto the `createRoot()` call, passing it the JSX expression that we want to render inside our root. By writing `<App />` as this JSX expression, we're telling React to call the `App()` _function_ which renders the `App` _component_ inside the root node. +We then call the `createRoot()` function, which defines the root node of our application. This takes as an argument the DOM element inside which we want our React app to be rendered. In this case, that's the DOM element with an ID of `root`. Finally, we chain the `render()` method onto the `createRoot()` call, passing it the JSX expression that we want to render inside our root. By writing `<App />` as this JSX expression, we're telling React to call the `App()` _function_, which renders the `App` _component_ inside the root node. > **Note:** `<App />` is rendered inside a special `<React.StrictMode>` component. This component helps developers catch potential problems in their code. @@ -351,7 +355,7 @@ You can read up on these React APIs, if you'd like: Before we start building our app, we're going to delete some of the boilerplate code that Vite provided for us. -First, as an experiment, change the [`<h1>`](/en-US/docs/Web/HTML/Element/Heading_Elements) element in `App.jsx` so that it reads "Hello, World!", then save your file. You'll notice that this change is immediately rendered in the development server running at `http://localhost:3000` in your browser. Bear this in mind as you work on your app. +First, as an experiment, change the [`<h1>`](/en-US/docs/Web/HTML/Reference/Elements/Heading_Elements) element in `App.jsx` so that it reads "Hello, World!", then save your file. You'll notice that this change is immediately rendered in the development server running at `http://localhost:3000` in your browser. Bear this in mind as you work on your app. We won't be using the rest of the code! Replace the contents of `App.jsx` with the following: @@ -395,7 +399,7 @@ Some attributes are different than their HTML counterparts. For example, the `cl ### JavaScript expressions as content -Unlike HTML, JSX allows us to write variables and other JavaScript expressions right alongside our other content. Let's declare a variable called `subject` just above the `App()` function: +Unlike HTML, JSX allows us to write variables and other JavaScript expressions right alongside our other content. Let's declare a variable called `subject` just above the `App()` function in your `App.jsx` file: ```jsx const subject = "React"; @@ -416,14 +420,14 @@ The curly braces around `subject` are another feature of JSX's syntax. The curly ```jsx-nolint {/* Hello, React :)! */} -<h1>Hello, {subject + ' :)'}!</h1> +<h1>Hello, {`${subject} :)`}!</h1> {/* Hello, REACT */} <h1>Hello, {subject.toUpperCase()}</h1> {/* Hello, 4! */} <h1>Hello, {2 + 2}!</h1> ``` -Even comments in JSX are written inside curly braces! This is because comments, too, are technically JavaScript expressions. The `/* block comment syntax */` is necessary for your program to know where the comment starts and ends. +Even comments in JSX are written inside curly braces! This is because curly braces can contain a single JavaScript expression, and comments are valid as part of a JavaScript expression (and get ignored). You can use both `/* block comment syntax */` and `// line comment syntax` (with a trailing new line) inside curly braces. ### Component props @@ -445,7 +449,11 @@ Back in `App.jsx`, let's revisit the `App()` function. Change the signature of ` function App(props) { console.log(props); return ( - // code omitted for brevity + <> + { + // code omitted for brevity + } + </> ); } ``` @@ -499,7 +507,7 @@ In React: ## See also -- [Learn React](https://v2.scrimba.com/learn-react-c0e?via=mdn) <sup>_MDN learning partner_</sup> - - : [Scrimba's](https://scrimba.com?via=mdn) _Learn React_ course is the ultimate React 101 — the perfect starting point for any React beginner. Learn the basics of modern React by solving 140+ interactive coding challenges and building eight fun projects. +- [Learn React](https://scrimba.com/learn-react-c0e?via=mdn) <sup>[_MDN learning partner_](/en-US/docs/MDN/Writing_guidelines/Learning_content#partner_links_and_embeds)</sup> + - : [Scrimba's](https://scrimba.com/?via=mdn) _Learn React_ course is the ultimate React 101 — the perfect starting point for any React beginner. Learn the basics of modern React by solving 140+ interactive coding challenges and building eight fun projects. {{PreviousMenuNext("Learn_web_development/Core/Frameworks_libraries/Main_features","Learn_web_development/Core/Frameworks_libraries/React_todo_list_beginning", "Learn_web_development/Core/Frameworks_libraries")}} diff --git a/files/en-us/learn_web_development/core/frameworks_libraries/react_interactivity_events_state/index.md b/files/en-us/learn_web_development/core/frameworks_libraries/react_interactivity_events_state/index.md index 4b69cf8b31cd8e6..392c98ce6b9249e 100644 --- a/files/en-us/learn_web_development/core/frameworks_libraries/react_interactivity_events_state/index.md +++ b/files/en-us/learn_web_development/core/frameworks_libraries/react_interactivity_events_state/index.md @@ -1,11 +1,11 @@ --- title: "React interactivity: Events and state" +short-title: React events and state slug: Learn_web_development/Core/Frameworks_libraries/React_interactivity_events_state page-type: learn-module-chapter +sidebar: learnsidebar --- -{{LearnSidebar}} - {{PreviousMenuNext("Learn_web_development/Core/Frameworks_libraries/React_components","Learn_web_development/Core/Frameworks_libraries/React_interactivity_filtering_conditional_rendering", "Learn_web_development/Core/Frameworks_libraries")}} With our component plan worked out, it's now time to start updating our app from a completely static UI to one that actually allows us to interact and change things. In this article we'll do this, digging into events and state along the way, and ending up with an app in which we can successfully add and delete tasks, and toggle tasks as completed. @@ -76,10 +76,10 @@ function handleSubmit(event) { } ``` -To use this function, add an `onSubmit` attribute to the [`<form>`](/en-US/docs/Web/HTML/Element/form) element, and set its value to the `handleSubmit` function: +To use this function, add an `onSubmit` attribute to the [`<form>`](/en-US/docs/Web/HTML/Reference/Elements/form) element, and set its value to the `handleSubmit` function: ```jsx -<form onSubmit={handleSubmit}> +<form onSubmit={handleSubmit}>{/* … */}</form> ``` Now if you head back to your browser and click on the "Add" button, your browser will show you an alert dialog with the words "Hello, world!" — or whatever you chose to write there. @@ -110,7 +110,7 @@ To use this prop, we must change the signature of the `Form()` function in `Form ```jsx function Form(props) { - // ... + // … } ``` @@ -182,7 +182,7 @@ Several things are happening in this line of code: - We are defining a `name` constant with the value `"Learn React"`. - We are defining a function whose job it is to modify `name`, called `setName()`. -- `useState()` returns these two things in an array, so we are using [array destructuring](/en-US/docs/Web/JavaScript/Reference/Operators/Destructuring_assignment) to capture them both in separate variables. +- `useState()` returns these two things in an array, so we are using [array destructuring](/en-US/docs/Web/JavaScript/Reference/Operators/Destructuring) to capture them both in separate variables. ### Reading state @@ -215,7 +215,7 @@ function handleChange() { console.log("Typing!"); } -... +// … // Down in the return statement <input diff --git a/files/en-us/learn_web_development/core/frameworks_libraries/react_interactivity_filtering_conditional_rendering/index.md b/files/en-us/learn_web_development/core/frameworks_libraries/react_interactivity_filtering_conditional_rendering/index.md index 43a6c2ce52eceb9..30efae54eafc727 100644 --- a/files/en-us/learn_web_development/core/frameworks_libraries/react_interactivity_filtering_conditional_rendering/index.md +++ b/files/en-us/learn_web_development/core/frameworks_libraries/react_interactivity_filtering_conditional_rendering/index.md @@ -1,11 +1,11 @@ --- title: "React interactivity: Editing, filtering, conditional rendering" +short-title: React editing, filtering, conditional UI slug: Learn_web_development/Core/Frameworks_libraries/React_interactivity_filtering_conditional_rendering page-type: learn-module-chapter +sidebar: learnsidebar --- -{{LearnSidebar}} - {{PreviousMenuNext("Learn_web_development/Core/Frameworks_libraries/React_interactivity_events_state","Learn_web_development/Core/Frameworks_libraries/React_accessibility", "Learn_web_development/Core/Frameworks_libraries")}} As we near the end of our React journey (for now at least), we'll add the finishing touches to the main areas of functionality in our Todo list app. This includes allowing you to edit existing tasks, and filtering the list of tasks between all, completed, and incomplete tasks. We'll look at conditional UI rendering along the way. @@ -234,6 +234,8 @@ Bind this function to the form's `submit` event by adding the following `onSubmi ```jsx <form className="stack-small" onSubmit={handleSubmit}> + {/* … */} +</form> ``` You should now be able to edit a task in your browser. At this point, your `Todo.jsx` file should look like this: @@ -386,15 +388,17 @@ const filterList = FILTER_NAMES.map((name) => ( Now we'll replace the three repeated `<FilterButton />`s in `App.jsx` with this `filterList`. Replace the following: ```jsx -<FilterButton /> -<FilterButton /> -<FilterButton /> +<div className="filters btn-group stack-exception"> + <FilterButton /> + <FilterButton /> + <FilterButton /> +</div> ``` With this: -```jsx-nolint -{filterList} +```jsx +<div className="filters btn-group stack-exception">{filterList}</div> ``` This won't work yet. We've got a bit more work to do first. diff --git a/files/en-us/learn_web_development/core/frameworks_libraries/react_resources/index.md b/files/en-us/learn_web_development/core/frameworks_libraries/react_resources/index.md index 4915d02d7e285a2..fb63b5cfc6c9eab 100644 --- a/files/en-us/learn_web_development/core/frameworks_libraries/react_resources/index.md +++ b/files/en-us/learn_web_development/core/frameworks_libraries/react_resources/index.md @@ -2,10 +2,9 @@ title: React resources slug: Learn_web_development/Core/Frameworks_libraries/React_resources page-type: learn-module-chapter +sidebar: learnsidebar --- -{{LearnSidebar}} - {{PreviousMenuNext("Learn_web_development/Core/Frameworks_libraries/React_accessibility","Learn_web_development/Core/Accessibility", "Learn_web_development/Core/Frameworks_libraries")}} Our final article provides you with a list of React resources that you can use to go further in your learning. diff --git a/files/en-us/learn_web_development/core/frameworks_libraries/react_todo_list_beginning/index.md b/files/en-us/learn_web_development/core/frameworks_libraries/react_todo_list_beginning/index.md index 7f37b220015b996..f02b98a719c2e53 100644 --- a/files/en-us/learn_web_development/core/frameworks_libraries/react_todo_list_beginning/index.md +++ b/files/en-us/learn_web_development/core/frameworks_libraries/react_todo_list_beginning/index.md @@ -1,11 +1,11 @@ --- -title: Beginning our React todo list +title: Beginning our React ToDo app +short-title: React ToDo app slug: Learn_web_development/Core/Frameworks_libraries/React_todo_list_beginning page-type: learn-module-chapter +sidebar: learnsidebar --- -{{LearnSidebar}} - {{PreviousMenuNext("Learn_web_development/Core/Frameworks_libraries/React_getting_started","Learn_web_development/Core/Frameworks_libraries/React_components", "Learn_web_development/Core/Frameworks_libraries")}} Let's say that we've been tasked with creating a proof-of-concept in React – an app that allows users to add, edit, and delete tasks they want to work on, and also mark tasks as complete without deleting them. This article will walk you through the basic structure and styling of such an application, ready for individual component definition and interactivity, which we'll add later. @@ -174,7 +174,7 @@ function App(props) { export default App; ``` -Now open `index.html` and change the [`<title>`](/en-US/docs/Web/HTML/Element/title) element's text to `TodoMatic`. This way, it will match the [`<h1>`](/en-US/docs/Web/HTML/Element/Heading_Elements) at the top of our app. +Now open `index.html` and change the [`<title>`](/en-US/docs/Web/HTML/Reference/Elements/title) element's text to `TodoMatic`. This way, it will match the [`<h1>`](/en-US/docs/Web/HTML/Reference/Elements/Heading_Elements) at the top of our app. ```html <title>TodoMatic</title> @@ -186,10 +186,10 @@ When your browser refreshes, you should see something like this: It's ugly, and doesn't function yet, but that's okay — we'll style it in a moment. First, consider the JSX we have, and how it corresponds to our user stories: -- We have a [`<form>`](/en-US/docs/Web/HTML/Element/form) element, with an [`<input type="text">`](/en-US/docs/Web/HTML/Element/input/text) for writing out a new task, and a button to submit the form. +- We have a [`<form>`](/en-US/docs/Web/HTML/Reference/Elements/form) element, with an [`<input type="text">`](/en-US/docs/Web/HTML/Reference/Elements/input/text) for writing out a new task, and a button to submit the form. - We have an array of buttons that will be used to filter our tasks. - We have a heading that tells us how many tasks remain. -- We have our 3 tasks, arranged in an unordered list. Each task is a list item ([`<li>`](/en-US/docs/Web/HTML/Element/li)), and has buttons to edit and delete it and a checkbox to check it off as done. +- We have our 3 tasks, arranged in an unordered list. Each task is a list item ([`<li>`](/en-US/docs/Web/HTML/Reference/Elements/li)), and has buttons to edit and delete it and a checkbox to check it off as done. The form will allow us to _make_ tasks; the buttons will let us _filter_ them; the heading and list are our way to _read_ them. The UI for _editing_ a task is conspicuously absent for now. That's okay – we'll write that later. @@ -209,7 +209,7 @@ Here, `aria-pressed` tells assistive technology (like screen readers) that the b The class `visually-hidden` has no effect yet, because we have not included any CSS. Once we have put our styles in place, though, any element with this class will be hidden from sighted users and still available to assistive technology users — this is because these words are not needed by sighted users; they are there to provide more information about what the button does for assistive technology users that do not have the extra visual context to help them. -Further down, you can find our [`<ul>`](/en-US/docs/Web/HTML/Element/ul) element: +Further down, you can find our [`<ul>`](/en-US/docs/Web/HTML/Reference/Elements/ul) element: ```html <ul @@ -227,10 +227,12 @@ The `aria-labelledby` attribute tells assistive technologies that we're treating Finally, the labels and inputs in our list items have some attributes unique to JSX: ```jsx -<input id="todo-0" type="checkbox" defaultChecked /> -<label className="todo-label" htmlFor="todo-0"> - Eat -</label> +<div className="c-cb"> + <input id="todo-0" type="checkbox" defaultChecked /> + <label className="todo-label" htmlFor="todo-0"> + Eat + </label> +</div> ``` The `defaultChecked` attribute in the `<input />` tag tells React to check this checkbox initially. If we were to use `checked`, as we would in regular HTML, React would log some warnings into our browser console relating to handling events on the checkbox, which we want to avoid. Don't worry too much about this for now — we will cover this later on when we get to using events. @@ -243,7 +245,7 @@ The `defaultChecked` attribute in the previous section is a boolean attribute Because JSX is JavaScript, there's a gotcha to be aware of with boolean attributes: writing `defaultChecked="false"` will set a _string_ value of `"false"` rather than a _boolean_ value. Non-empty strings are [truthy](/en-US/docs/Glossary/Truthy), so React will consider `defaultChecked` to be `true` and check the checkbox by default. This is not what we want, so we should avoid it. -If you'd like, you can practice writing boolean attributes with another attribute you may have seen before, [`hidden`](/en-US/docs/Web/HTML/Global_attributes/hidden), which prevents elements from being rendered on the page. Try adding `hidden` to the `<h1>` element in `App.jsx` to see what happens, then try explicitly setting its value to `{false}`. Note, again, that writing `hidden="false"` results in a truthy value so the `<h1>` _will_ hide. Don't forget to remove this code when you're done. +If you'd like, you can practice writing boolean attributes with another attribute you may have seen before, [`hidden`](/en-US/docs/Web/HTML/Reference/Global_attributes/hidden), which prevents elements from being rendered on the page. Try adding `hidden` to the `<h1>` element in `App.jsx` to see what happens, then try explicitly setting its value to `{false}`. Note, again, that writing `hidden="false"` results in a truthy value so the `<h1>` _will_ hide. Don't forget to remove this code when you're done. > [!NOTE] > The `aria-pressed` attribute used in our earlier code snippet has a value of `"true"` because `aria-pressed` is not a true boolean attribute in the way `checked` is. @@ -372,7 +374,6 @@ body { text-align: center; } .visually-hidden { - clip: rect(1px 1px 1px 1px); clip: rect(1px, 1px, 1px, 1px); height: 1px; overflow: hidden; diff --git a/files/en-us/learn_web_development/core/frameworks_libraries/svelte_components/index.md b/files/en-us/learn_web_development/core/frameworks_libraries/svelte_components/index.md index 6b96de5062bb52b..8d9a14d9e186d43 100644 --- a/files/en-us/learn_web_development/core/frameworks_libraries/svelte_components/index.md +++ b/files/en-us/learn_web_development/core/frameworks_libraries/svelte_components/index.md @@ -2,9 +2,9 @@ title: Componentizing our Svelte app slug: Learn_web_development/Core/Frameworks_libraries/Svelte_components page-type: learn-module-chapter +sidebar: learnsidebar --- -{{LearnSidebar}} {{PreviousMenuNext("Learn_web_development/Core/Frameworks_libraries/Svelte_variables_props","Learn_web_development/Core/Frameworks_libraries/Svelte_reactivity_lifecycle_accessibility", "Learn_web_development/Core/Frameworks_libraries")}} In the last article we started developing our to-do list app. The central objective of this article is to look at how to break our app into manageable components and share information between them. We'll componentize our app, then add more functionality to allow users to update existing components. @@ -283,6 +283,7 @@ We'll edit our `Todo` component to emit a `remove` event, passing the to-do bein ```js import { createEventDispatcher } from "svelte"; + const dispatch = createEventDispatcher(); ``` diff --git a/files/en-us/learn_web_development/core/frameworks_libraries/svelte_deployment_next/index.md b/files/en-us/learn_web_development/core/frameworks_libraries/svelte_deployment_next/index.md index 62be1237a99caa0..818bbc7c63ef97e 100644 --- a/files/en-us/learn_web_development/core/frameworks_libraries/svelte_deployment_next/index.md +++ b/files/en-us/learn_web_development/core/frameworks_libraries/svelte_deployment_next/index.md @@ -2,10 +2,9 @@ title: Deployment and next steps slug: Learn_web_development/Core/Frameworks_libraries/Svelte_deployment_next page-type: learn-module-chapter +sidebar: learnsidebar --- -{{LearnSidebar}} - {{PreviousMenu("Learn_web_development/Core/Frameworks_libraries/Svelte_TypeScript", "Learn_web_development/Core/Frameworks_libraries")}} In the previous article we learned about Svelte's TypeScript support, and how to use it to make your application more robust. In this final article we will look at how to deploy your application and get it online, and also share some of the resources that you should go on to, to continue your Svelte learning journey. @@ -112,19 +111,19 @@ In the `dev` script we are passing the `-w` argument, which tells rollup to watc If we have a look at the `rollup.config.js` file, we can see that the Svelte compiler is just a rollup plugin: ```js -import svelte from 'rollup-plugin-svelte'; +import svelte from "rollup-plugin-svelte"; // … -import { terser } from 'rollup-plugin-terser'; +import { terser } from "rollup-plugin-terser"; const production = !process.env.ROLLUP_WATCH; export default { - input: 'src/main.js', + input: "src/main.js", output: { sourcemap: true, - format: 'iife', - name: 'app', - file: 'public/build/bundle.js' + format: "iife", + name: "app", + file: "public/build/bundle.js", }, plugins: [ svelte({ @@ -132,27 +131,37 @@ export default { dev: !production, // we'll extract any component CSS out into // a separate file - better for performance - css: (css) => { - css.write('public/build/bundle.css'); - } + css(css) { + css.write("public/build/bundle.css"); + }, }), + // More plugins… + ], + // … +}; ``` Later on in the same file you'll also see how rollup minimizes our scripts in production mode and launches a local server in development mode: ```js +export default { + // … + plugins: [ + // … // In dev mode, call `npm run start` once // the bundle has been generated !production && serve(), // Watch the `public` directory and refresh the // browser on changes when not in production - !production && livereload('public'), + !production && livereload("public"), // If we're building for production (npm run build // instead of npm run dev), minify - production && terser() + production && terser(), ], + // … +}; ``` There are [many plugins for rollup](https://github.com/rollup/awesome) that allow you to customize its behavior. A particularly useful plugin which is also maintained by the Svelte team is [svelte-preprocess](https://github.com/sveltejs/svelte-preprocess), which pre-processes many different languages in Svelte files such as PostCSS, SCSS, Less, CoffeeScript, SASS, and TypeScript. @@ -209,7 +218,7 @@ You can also [import a Svelte git project](https://vercel.com/import/svelte) int For hosting static files there are several online services that allow you to automatically deploy your site whenever you push changes to a git repository. Most of them involve setting up a deployment pipeline that gets triggered on every `git push`, and takes care of building and deploying your website. -To demonstrate this, we will deploy our todos app to [GitLab Pages](https://docs.gitlab.com/ee/user/project/pages/). +To demonstrate this, we will deploy our todos app to [GitLab Pages](https://docs.gitlab.com/user/project/pages/). 1. First you'll have to [register at GitLab](https://gitlab.com/users/sign_up) and then [create a new project](https://gitlab.com/projects/new). Give you new project a short, easy name like "mdn-svelte-todo". You will have a remote URL that points to your new GitLab git repository, like `git@gitlab.com:[your-user]/[your-project].git`. 2. Before you start to upload content to your git repository, it is a good practice to add a `.gitignore` file to tell git which files to exclude from source control. In our case we will tell git to exclude files in the `node_modules` directory by creating a `.gitignore` file in the root folder of your local project, with the following content: @@ -230,7 +239,7 @@ To demonstrate this, we will deploy our todos app to [GitLab Pages](https://docs ``` > [!NOTE] - > You could use [the `git` protocol](https://git-scm.com/book/en/v2/Git-on-the-Server-The-Protocols#_the_git_protocol) instead of `https`, which is faster and saves you from typing your username and password every time you access your origin repo. To use it you'll have to [create an SSH key pair](https://docs.gitlab.com/ee/user/ssh.html#generate-an-ssh-key-pair). Your origin URL will be like this: `git@gitlab.com:[your-user]/mdn-svelte-todo.git`. + > You could use [the `git` protocol](https://git-scm.com/book/en/v2/Git-on-the-Server-The-Protocols#_the_git_protocol) instead of `https`, which is faster and saves you from typing your username and password every time you access your origin repo. To use it you'll have to [create an SSH key pair](https://docs.gitlab.com/user/ssh/#generate-an-ssh-key-pair). Your origin URL will be like this: `git@gitlab.com:[your-user]/mdn-svelte-todo.git`. With these instructions we initialize a local git repository, then set our remote origin (where we will push our code to) as our repo on GitLab. Next we commit all the files to the local git repo, and then push those to the remote origin on GitLab. @@ -308,7 +317,7 @@ To understand the motivations behind Svelte, you should read [Rich Harris](https There are other projects related to Svelte that are worth checking out: - [Sapper](https://sapper.svelte.dev/): An application framework powered by Svelte that provides server-side rendering (SSR), code splitting, file-based routing and offline support, and more. Think of it as [Next.js](https://nextjs.org/) for Svelte. If you are planning to develop a fairly complex web application you should definitely have a look at this project. -- [Svelte Native](https://svelte-native.technology/): A mobile application framework powered by Svelte. Think of it as [React Native](https://reactnative.dev/) for Svelte. +- [Svelte Native](https://svelte.nativescript.org/): A mobile application framework powered by Svelte. Think of it as [React Native](https://reactnative.dev/) for Svelte. - [Svelte for VS Code](https://marketplace.visualstudio.com/items?itemName=svelte.svelte-vscode): The officially supported VS Code plugin for working with `.svelte` files, which we looked at in our [TypeScript article](/en-US/docs/Learn_web_development/Core/Frameworks_libraries/Svelte_TypeScript). ### Other learning resources diff --git a/files/en-us/learn_web_development/core/frameworks_libraries/svelte_getting_started/index.md b/files/en-us/learn_web_development/core/frameworks_libraries/svelte_getting_started/index.md index 6a4f8791d389182..fad18a97719326a 100644 --- a/files/en-us/learn_web_development/core/frameworks_libraries/svelte_getting_started/index.md +++ b/files/en-us/learn_web_development/core/frameworks_libraries/svelte_getting_started/index.md @@ -2,10 +2,9 @@ title: Getting started with Svelte slug: Learn_web_development/Core/Frameworks_libraries/Svelte_getting_started page-type: learn-module-chapter +sidebar: learnsidebar --- -{{LearnSidebar}} - {{NextMenu("Learn_web_development/Core/Frameworks_libraries/Svelte_todo_list_beginning", "Learn_web_development/Core/Frameworks_libraries")}} In this article we'll provide a quick introduction to the [Svelte framework](https://svelte.dev/). We will see how Svelte works and what sets it apart from the rest of the frameworks and tools we've seen so far. Then we will learn how to set up our development environment, create a sample app, understand the structure of the project, and see how to run it locally and build it for production. @@ -70,7 +69,7 @@ Nevertheless, Svelte is particularly appropriate to tackle the following situati The Svelte team launched [SvelteKit](https://kit.svelte.dev/), a framework for building web applications using Svelte. It contains features found in modern web frameworks, such as filesystem-based routing, server-side rendering (SSR), page-specific rendering modes, offline support, and more. For more information about SvelteKit, see the [official tutorial](https://learn.svelte.dev/) and [documentation](https://kit.svelte.dev/docs/introduction). -Svelte is also available for mobile development via [Svelte Native](https://svelte-native.technology/). +Svelte is also available for mobile development via [Svelte Native](https://svelte.nativescript.org/). ## How does Svelte work? @@ -175,7 +174,7 @@ Components are the building blocks of Svelte applications. They are written into All three sections — `<script>`, `<style>`, and markup — are optional, and can appear in any order you like. -```html +```svelte <script> // logic goes here </script> @@ -192,7 +191,7 @@ All three sections — `<script>`, `<style>`, and markup — are optional, and c With this in mind, let's have a look at the `src/App.svelte` file that came with the starter template. You should see something like the following: -```html +```svelte <script> export let name; </script> @@ -232,19 +231,19 @@ With this in mind, let's have a look at the `src/App.svelte` file that came with The `<script>` block contains JavaScript that runs when a component instance is created. Variables declared (or imported) at the top level are 'visible' from the component's markup. Top-level variables are the way Svelte handles the component state, and they are reactive by default. We will explain in detail what this means later on. -```html +```svelte <script> export let name; </script> ``` -Svelte uses the [`export`](/en-US/docs/Web/JavaScript/Reference/Statements/export) keyword to mark a variable declaration as a property (or prop), which means it becomes accessible to consumers of the component (e.g. other components). This is one example of Svelte extending JavaScript syntax to make it more useful, while keeping it familiar. +Svelte uses the [`export`](/en-US/docs/Web/JavaScript/Reference/Statements/export) keyword to mark a variable declaration as a property (or prop), which means it becomes accessible to consumers of the component (e.g., other components). This is one example of Svelte extending JavaScript syntax to make it more useful, while keeping it familiar. ### The markup section In the markup section you can insert any HTML you like, and in addition you can insert valid JavaScript expressions inside single curly braces (`{}`). In this case we are embedding the value of the `name` prop right after the `Hello` text. -```html +```svelte <main> <h1>Hello {name}!</h1> <p> @@ -260,7 +259,7 @@ Svelte also supports tags like `{#if}`, `{#each}`, and `{#await}` — these exam If you have experience working with CSS, the following snippet should make sense: -```html +```svelte <style> main { text-align: center; @@ -284,7 +283,7 @@ If you have experience working with CSS, the following snippet should make sense </style> ``` -We are applying a style to our [`<h1>`](/en-US/docs/Web/HTML/Element/Heading_Elements) element. What will happen to other components with `<h1>` elements in them? +We are applying a style to our [`<h1>`](/en-US/docs/Web/HTML/Reference/Elements/Heading_Elements) element. What will happen to other components with `<h1>` elements in them? In Svelte, CSS inside a component's `<style>` block will be scoped only to that component. This works by adding a class to selected elements, which is based on a hash of the component styles. @@ -302,7 +301,7 @@ When compiling the app, Svelte changes our `h1` styles definition to `h1.svelte- Now that we have a general idea of how it all fits together, we can start making a few changes. At this point you can try updating your `App.svelte` component — for example change the `<h1>` element in `App.svelte` so that it reads like this: -```html +```svelte <h1>Hello {name} from MDN!</h1> ``` @@ -316,7 +315,7 @@ In Svelte, reactivity is triggered by assigning a new value to any top-level var Try updating your `<script>` and markup sections like so: -```html +```svelte <script> export let name; @@ -467,7 +466,7 @@ Whenever you change any file on the REPL, Svelte will recompile the app and upda We will provide a REPL at the beginning and end of each article so that you can start coding with us right away. > [!NOTE] -> At the moment the REPL can't handle folder names properly. If you are following the tutorial on the REPL, just create all your components inside the root folder. Then when you see a path in the code, for example `import Todos from './components/Todos.svelte'`, just replace it with a flat URL, e.g. `import Todos from './Todos.svelte'`. +> At the moment the REPL can't handle folder names properly. If you are following the tutorial on the REPL, just create all your components inside the root folder. Then when you see a path in the code, for example `import Todos from './components/Todos.svelte'`, just replace it with a flat URL, e.g., `import Todos from './Todos.svelte'`. ## The code so far diff --git a/files/en-us/learn_web_development/core/frameworks_libraries/svelte_reactivity_lifecycle_accessibility/index.md b/files/en-us/learn_web_development/core/frameworks_libraries/svelte_reactivity_lifecycle_accessibility/index.md index a7967d6a76f9dcc..b18b12261b1a8e0 100644 --- a/files/en-us/learn_web_development/core/frameworks_libraries/svelte_reactivity_lifecycle_accessibility/index.md +++ b/files/en-us/learn_web_development/core/frameworks_libraries/svelte_reactivity_lifecycle_accessibility/index.md @@ -2,9 +2,9 @@ title: "Advanced Svelte: Reactivity, lifecycle, accessibility" slug: Learn_web_development/Core/Frameworks_libraries/Svelte_reactivity_lifecycle_accessibility page-type: learn-module-chapter +sidebar: learnsidebar --- -{{LearnSidebar}} {{PreviousMenuNext("Learn_web_development/Core/Frameworks_libraries/Svelte_components","Learn_web_development/Core/Frameworks_libraries/Svelte_stores", "Learn_web_development/Core/Frameworks_libraries")}} In the last article we added more features to our to-do list and started to organize our app into components. In this article we will add the app's final features and further componentize our app. We will learn how to deal with reactivity issues related to updating objects and arrays. To avoid common pitfalls, we'll have to dig a little deeper into Svelte's reactivity system. We'll also look at solving some accessibility focus issues, and more besides. @@ -94,6 +94,7 @@ Now we'll tackle the _Check All_ and _Remove Completed_ buttons. Let's create a ```svelte <script> import { createEventDispatcher } from "svelte"; + const dispatch = createEventDispatcher(); let completed = true; @@ -214,7 +215,7 @@ const checkAllTodos = (completed) => { }; ``` -Assignments to properties of arrays and objects — e.g. `obj.foo += 1` or `array[i] = x` — work the same way as assignments to the values themselves. When Svelte analyzes this code, it can detect that the `todos` array is being modified. +Assignments to properties of arrays and objects — e.g., `obj.foo += 1` or `array[i] = x` — work the same way as assignments to the values themselves. When Svelte analyzes this code, it can detect that the `todos` array is being modified. Another solution is to assign a new array to `todos` containing a copy of all the to-dos with the `completed` property updated accordingly, like this: @@ -333,7 +334,7 @@ Let's begin by extracting our new to-do form out to its own component. With what </form> ``` - Here we are binding the `<input>` to the `name` variable with `bind:value={name}` and disabling the _Add_ button when it is empty (i.e. no text content) using `disabled={!name}`. We are also taking care of the <kbd>Escape</kbd> key with `on:keydown={(e) => e.key === 'Escape' && onCancel()}`. Whenever the <kbd>Escape</kbd> key is pressed we run `onCancel()`, which just clears up the `name` variable. + Here we are binding the `<input>` to the `name` variable with `bind:value={name}` and disabling the _Add_ button when it is empty (i.e., no text content) using `disabled={!name}`. We are also taking care of the <kbd>Escape</kbd> key with `on:keydown={(e) => e.key === 'Escape' && onCancel()}`. Whenever the <kbd>Escape</kbd> key is pressed we run `onCancel()`, which just clears up the `name` variable. 3. Now we have to `import` and use it from inside the `Todos` component, and update the `addTodo()` function to receive the name of the new todo. diff --git a/files/en-us/learn_web_development/core/frameworks_libraries/svelte_stores/index.md b/files/en-us/learn_web_development/core/frameworks_libraries/svelte_stores/index.md index dc7163806d3c2bd..bef527ace7f5216 100644 --- a/files/en-us/learn_web_development/core/frameworks_libraries/svelte_stores/index.md +++ b/files/en-us/learn_web_development/core/frameworks_libraries/svelte_stores/index.md @@ -2,9 +2,9 @@ title: Working with Svelte stores slug: Learn_web_development/Core/Frameworks_libraries/Svelte_stores page-type: learn-module-chapter +sidebar: learnsidebar --- -{{LearnSidebar}} {{PreviousMenuNext("Learn_web_development/Core/Frameworks_libraries/Svelte_reactivity_lifecycle_accessibility","Learn_web_development/Core/Frameworks_libraries/Svelte_TypeScript", "Learn_web_development/Core/Frameworks_libraries")}} In the last article we completed the development of our app, finished organizing it into components, and discussed some advanced techniques for dealing with reactivity, working with DOM nodes, and exposing component functionality. In this article we will show another way to handle state management in Svelte: [Stores](https://learn.svelte.dev/tutorial/writable-stores). Stores are global data repositories that hold values. Components can subscribe to stores and receive notifications when their values change. @@ -121,18 +121,18 @@ Let's now create our `Alert` component and see how we can read values from the s ```svelte <script> - import { alert } from '../stores.js' - import { onDestroy } from 'svelte' + import { alert } from "../stores.js"; + import { onDestroy } from "svelte"; - let alertContent = '' + let alertContent = ""; - const unsubscribe = alert.subscribe((value) => alertContent = value) + const unsubscribe = alert.subscribe((value) => (alertContent = value)); - onDestroy(unsubscribe) + onDestroy(unsubscribe); </script> {#if alertContent} - <div on:click={() => alertContent = ''}> + <div on:click={() => (alertContent = "")}> <p>{ alertContent }</p> </div> {/if} @@ -236,11 +236,11 @@ And `$myStore` will be fully reactive. This also applies to your own custom stor ```svelte <script> - import { alert } from '../stores.js' + import { alert } from "../stores.js"; </script> {#if $alert} - <div on:click={() => $alert = ''}> + <div on:click={() => $alert = ""}> <p>{ $alert }</p> </div> {/if} @@ -386,7 +386,7 @@ We also added an SVG icon above the alert paragraph, to make it look a bit nicer ## Making our Alert component accessible -Our `Alert` component is working fine, but it's not very friendly to assistive technologies. The problem is elements that are dynamically added and removed from the page. While visually evident to users who can see the page, they may not be so obvious to users of assistive technologies, like screen readers. To handle those situations, we can take advantage of [ARIA live regions](/en-US/docs/Web/Accessibility/ARIA/ARIA_Live_Regions), which provide a way to programmatically expose dynamic content changes so that they can be detected and announced by assistive technologies. +Our `Alert` component is working fine, but it's not very friendly to assistive technologies. The problem is elements that are dynamically added and removed from the page. While visually evident to users who can see the page, they may not be so obvious to users of assistive technologies, like screen readers. To handle those situations, we can take advantage of [ARIA live regions](/en-US/docs/Web/Accessibility/ARIA/Guides/Live_regions), which provide a way to programmatically expose dynamic content changes so that they can be detected and announced by assistive technologies. We can declare a region that contains dynamic content that should be announced by assistive technologies with the `aria-live` property followed by the politeness setting, which is used to set the priority with which screen readers should handle updates to that regions. The possible settings are `off`, `polite`, or `assertive`. @@ -398,7 +398,7 @@ In our case, just adding a `role="alert"` to the `<div>` container will do the t <div role="alert" on:click={() => visible = false}> ``` -In general, testing your applications using screen readers is a good idea, not only to discover accessibility issues but also to get used to how visually impaired people use the Web. You have several options, like [NVDA](https://www.nvaccess.org/) for Windows, [ChromeVox](https://support.google.com/chromebook/answer/7031755) for Chrome, [Orca](https://wiki.gnome.org/Projects/Orca) on Linux, and [VoiceOver](https://www.apple.com/accessibility/vision/) for macOS and iOS, among other options. +In general, testing your applications using screen readers is a good idea, not only to discover accessibility issues but also to get used to how visually impaired people use the Web. You have several options, like [NVDA](https://www.nvaccess.org/) for Windows, [ChromeVox](https://support.google.com/chromebook/answer/7031755) for Chrome, [Orca](https://wiki.gnome.org/Projects/Orca) on Linux, and [VoiceOver](https://www.apple.com/accessibility/features/?vision) for macOS and iOS, among other options. To learn more about detecting and fixing accessibility issues, check out our [Accessibility](/en-US/docs/Learn_web_development/Core/Accessibility) module. @@ -451,7 +451,7 @@ So let's start by using a regular writable store to save our to-dos. $todos = [ { id: 1, name: "Create a Svelte starter app", completed: true }, { id: 2, name: "Create your first component", completed: true }, - { id: 3, name: "Complete the rest of the tutorial", completed: false } + { id: 3, name: "Complete the rest of the tutorial", completed: false }, ]; </script> @@ -515,6 +515,7 @@ Usually you don't implement stores from scratch; instead you'd use the writable ```js import { writable } from "svelte/store"; + function myStore() { const { subscribe, set, update } = writable(0); @@ -567,7 +568,7 @@ Moreover, because web storage only supports saving string values, we will have t return { subscribe, - set: (value) => { + set(value) { localStorage.setItem(key, toString(value)); // save also to local storage as a string return set(value); }, @@ -608,10 +609,10 @@ Moreover, because web storage only supports saving string values, we will have t ```svelte <script> - import Todos from './components/Todos.svelte' - import Alert from './components/Alert.svelte' + import Todos from "./components/Todos.svelte"; + import Alert from "./components/Alert.svelte"; - import { todos } from './stores.js' + import { todos } from "./stores.js"; </script> <Alert /> @@ -632,7 +633,7 @@ Svelte stores provide a very simple and lightweight, but extremely powerful, way Let's change the subject now and do something fun and different: add an animation to our alerts. Svelte provides a whole module to define [transitions](https://learn.svelte.dev/tutorial/transition) and [animations](https://learn.svelte.dev/tutorial/animate) so we can make our user interfaces more appealing. -A transition is applied with the [transition:fn](https://svelte.dev/docs/element-directives#transition-fn) directive, and is triggered by an element entering or leaving the DOM as a result of a state change. The `svelte/transition` module exports seven functions: `fade`, `blur`, `fly`, `slide`, `scale`, `draw`, and `crossfade`. +A transition is applied with the [transition:fn](https://svelte.dev/docs/element-directives#transition-fn) directive, and is triggered by an element entering or leaving the DOM as a result of a state change. Let's give our `Alert` component a fly `transition`. We'll open the `Alert.svelte` file and import the `fly` function from the `svelte/transition` module. diff --git a/files/en-us/learn_web_development/core/frameworks_libraries/svelte_todo_list_beginning/index.md b/files/en-us/learn_web_development/core/frameworks_libraries/svelte_todo_list_beginning/index.md index fc4653b30ee09d7..eb5c00a1e8cd23c 100644 --- a/files/en-us/learn_web_development/core/frameworks_libraries/svelte_todo_list_beginning/index.md +++ b/files/en-us/learn_web_development/core/frameworks_libraries/svelte_todo_list_beginning/index.md @@ -2,9 +2,9 @@ title: Starting our Svelte to-do list app slug: Learn_web_development/Core/Frameworks_libraries/Svelte_Todo_list_beginning page-type: learn-module-chapter +sidebar: learnsidebar --- -{{LearnSidebar}} {{PreviousMenuNext("Learn_web_development/Core/Frameworks_libraries/Svelte_getting_started","Learn_web_development/Core/Frameworks_libraries/Svelte_variables_props", "Learn_web_development/Core/Frameworks_libraries")}} Now that we have a basic understanding of how things work in Svelte, we can start building our example app: a to-do list. In this article we will first have a look at the desired functionality of our app, and then we'll create a `Todos.svelte` component and put static markup and styles in place, leaving everything ready to start developing our to-do list app features, which we'll go on to in subsequent articles. @@ -354,28 +354,32 @@ You can tell Svelte to ignore this warning for the next block of markup with a [ If you want to globally disable this warning, you can add this `onwarn` handler to your `rollup.config.js` file inside the configuration for the `Svelte` plugin, like this: ```js -plugins: [ - svelte({ - dev: !production, - css: (css) => { - css.write("public/build/bundle.css"); - }, - // Warnings are normally passed straight to Rollup. You can - // optionally handle them here, for example to squelch - // warnings with a particular code - onwarn: (warning, handler) => { - // e.g. I don't care about screen readers -> please DON'T DO THIS!!! - if (warning.code === "a11y-missing-attribute") { - return; - } - - // let Rollup handle all other warnings normally - handler(warning); - }, - }), - +export default { + // … + plugins: [ + svelte({ + dev: !production, + css(css) { + css.write("public/build/bundle.css"); + }, + // Warnings are normally passed straight to Rollup. You can + // optionally handle them here, for example to squelch + // warnings with a particular code + onwarn(warning, handler) { + // e.g. I don't care about screen readers -> please DON'T DO THIS!!! + if (warning.code === "a11y-missing-attribute") { + return; + } + + // let Rollup handle all other warnings normally + handler(warning); + }, + }), + + // … + ], // … -]; +}; ``` By design, these warnings are implemented in the compiler itself, and not as a plug-in that you may choose to add to your project. The idea is to check for a11y issues in your markup by default and let you opt out of specific warnings. @@ -518,7 +522,6 @@ body { height: 1px; width: 1px; overflow: hidden; - clip: rect(1px 1px 1px 1px); clip: rect(1px, 1px, 1px, 1px); white-space: nowrap; } @@ -604,7 +607,7 @@ body { } .filters { width: 100%; - margin: unset auto; + margin: unset; } /* Todo item styles */ .todo { diff --git a/files/en-us/learn_web_development/core/frameworks_libraries/svelte_typescript/index.md b/files/en-us/learn_web_development/core/frameworks_libraries/svelte_typescript/index.md index f752d05a4f1551a..be779bf58297e7c 100644 --- a/files/en-us/learn_web_development/core/frameworks_libraries/svelte_typescript/index.md +++ b/files/en-us/learn_web_development/core/frameworks_libraries/svelte_typescript/index.md @@ -2,9 +2,9 @@ title: TypeScript support in Svelte slug: Learn_web_development/Core/Frameworks_libraries/Svelte_TypeScript page-type: learn-module-chapter +sidebar: learnsidebar --- -{{LearnSidebar}} {{PreviousMenuNext("Learn_web_development/Core/Frameworks_libraries/Svelte_stores","Learn_web_development/Core/Frameworks_libraries/Svelte_deployment_next", "Learn_web_development/Core/Frameworks_libraries")}} In the last article we learned about Svelte stores and even implemented our own custom store to persist the app's information to Web Storage. We also had a look at using the transition directive to implement animations on DOM elements in Svelte. @@ -71,7 +71,7 @@ Remember to run `npm install && npm run dev` to start your app in development mo ### REPL -Unfortunately, [TypeScript support is not yet available in the REPL](https://github.com/sveltejs/sites/issues/156). +Unfortunately, [TypeScript support is not yet available in the REPL](https://github.com/sveltejs/svelte.dev/issues/853). ## TypeScript: optional static typing for JavaScript @@ -345,14 +345,19 @@ Let's start with our `Alert.svelte` component. 2. You can fix these by specifying the corresponding types, like so: ```ts - export let ms = 3000 + export let ms = 3000; - let visible: boolean - let timeout: number + let visible: boolean; + let timeout: number; - const onMessageChange = (message: string, ms: number) => { - clearTimeout(timeout) - if (!message) { // hide Alert if message is empty + const onMessageChange = (message: string, ms: number) => { + clearTimeout(timeout); + if (!message) { + // hide Alert if message is empty + // … + } + // … + }; ``` > [!NOTE] @@ -494,7 +499,7 @@ We will also use the `Filter` enum in the `Todos.svelte` component. import Todo from "./Todo.svelte"; import MoreActions from "./MoreActions.svelte"; import NewTodo from "./NewTodo.svelte"; - import TodosStatus from "./TodosStatus.svelte"; + import type TodosStatus from "./TodosStatus.svelte"; import { alert } from "../stores"; import { Filter } from "../types/filter.enum"; @@ -779,7 +784,7 @@ import { localStore } from "./localStore"; return { subscribe, - set: (value: JsonValue) => { + set(value: JsonValue) { localStorage.setItem(key, toString(value)); // save also to local storage as a string return set(value); }, @@ -934,7 +939,9 @@ export const alert = writable<string>("Welcome to the To-Do list app!"); Now we'll make our `localStore` store support generics. Remember that we defined the `JsonValue` type to prevent the usage of our `localStore` store with values that cannot be persisted using `JSON.stringify()`. Now we want the consumers of `localStore` to be able to specify the type of data to persist, but instead of working with any type, they should comply with the `JsonValue` type. We'll specify that with a Generic constraint, like this: ```ts -export const localStore = <T extends JsonValue>(key: string, initial: T) +export const localStore = <T extends JsonValue>(key: string, initial: T) => { + // … +}; ``` We define a generic type `T` and specify that it must be compatible with the `JsonValue` type. Then we'll use the `T` type appropriately. @@ -964,7 +971,7 @@ export const localStore = <T extends JsonValue>(key: string, initial: T) => { return { subscribe, - set: (value: T) => { + set(value: T) { localStorage.setItem(key, toString(value)); // save also to local storage as a string return set(value); }, diff --git a/files/en-us/learn_web_development/core/frameworks_libraries/svelte_variables_props/index.md b/files/en-us/learn_web_development/core/frameworks_libraries/svelte_variables_props/index.md index f6b7707a394633d..96e766559182b4e 100644 --- a/files/en-us/learn_web_development/core/frameworks_libraries/svelte_variables_props/index.md +++ b/files/en-us/learn_web_development/core/frameworks_libraries/svelte_variables_props/index.md @@ -2,9 +2,9 @@ title: "Dynamic behavior in Svelte: working with variables and props" slug: Learn_web_development/Core/Frameworks_libraries/Svelte_variables_props page-type: learn-module-chapter +sidebar: learnsidebar --- -{{LearnSidebar}} {{PreviousMenuNext("Learn_web_development/Core/Frameworks_libraries/Svelte_Todo_list_beginning","Learn_web_development/Core/Frameworks_libraries/Svelte_components", "Learn_web_development/Core/Frameworks_libraries")}} Now that we have our markup and styles ready, we can start developing the required features for our Svelte to-do list app. In this article we'll be using variables and props to make our app dynamic, allowing us to add and delete to-dos, mark them as complete, and filter them by status. diff --git a/files/en-us/learn_web_development/core/frameworks_libraries/vue_computed_properties/index.md b/files/en-us/learn_web_development/core/frameworks_libraries/vue_computed_properties/index.md index 85d247b7916c9cc..5ddf28189132361 100644 --- a/files/en-us/learn_web_development/core/frameworks_libraries/vue_computed_properties/index.md +++ b/files/en-us/learn_web_development/core/frameworks_libraries/vue_computed_properties/index.md @@ -2,9 +2,10 @@ title: Using Vue computed properties slug: Learn_web_development/Core/Frameworks_libraries/Vue_computed_properties page-type: learn-module-chapter +sidebar: learnsidebar --- -{{LearnSidebar}}{{PreviousMenuNext("Learn_web_development/Core/Frameworks_libraries/Vue_styling","Learn_web_development/Core/Frameworks_libraries/Vue_conditional_rendering", "Learn_web_development/Core/Frameworks_libraries")}} +{{PreviousMenuNext("Learn_web_development/Core/Frameworks_libraries/Vue_styling","Learn_web_development/Core/Frameworks_libraries/Vue_conditional_rendering", "Learn_web_development/Core/Frameworks_libraries")}} In this article we'll add a counter that displays the number of completed todo items, using a feature of Vue called computed properties. These work similarly to methods, but only re-run when one of their dependencies changes. @@ -61,12 +62,18 @@ To create a computed property, we need to add a `computed` property to our compo Add the following code to your `App` component object, below the `methods` property. The list summary method will get the number of finished `ToDoItems`, and return a string reporting this. ```js -computed: { - listSummary() { - const numberFinishedItems = this.ToDoItems.filter((item) =>item.done).length - return `${numberFinishedItems} out of ${this.ToDoItems.length} items completed` - } -} +export default { + // … + computed: { + listSummary() { + const numberFinishedItems = this.ToDoItems.filter( + (item) => item.done, + ).length; + return `${numberFinishedItems} out of ${this.ToDoItems.length} items completed`; + }, + }, + // … +}; ``` Now we can add `\{{listSummary}}` directly to our template; we'll add this inside an `<h2>` element, just above our `<ul>`. We'll also add an `id` and an `aria-labelledby` attribute to assign the `<h2>` contents to be a label for the `<ul>` element. @@ -109,10 +116,18 @@ Since all we need to do is emit that the checkbox was checked, we can include th In `App.vue`, add a new method called `updateDoneStatus()`, below your `addToDo()` method. This method should take one parameter: the todo item _id_. We want to find the item with the matching `id` and update its `done` status to be the opposite of its current status: ```js -updateDoneStatus(toDoId) { - const toDoToUpdate = this.ToDoItems.find((item) => item.id === toDoId) - toDoToUpdate.done = !toDoToUpdate.done -} +export default { + // … + methods: { + // … + updateDoneStatus(toDoId) { + const toDoToUpdate = this.ToDoItems.find((item) => item.id === toDoId); + toDoToUpdate.done = !toDoToUpdate.done; + }, + // … + }, + // … +}; ``` We want to run this method whenever a `ToDoItem` emits a `checkbox-changed` event, and pass in its `item.id` as the parameter. Update your `<to-do-item></to-do-item>` call as follows: diff --git a/files/en-us/learn_web_development/core/frameworks_libraries/vue_conditional_rendering/index.md b/files/en-us/learn_web_development/core/frameworks_libraries/vue_conditional_rendering/index.md index 5238b62f9e41ee8..313eee10e852289 100644 --- a/files/en-us/learn_web_development/core/frameworks_libraries/vue_conditional_rendering/index.md +++ b/files/en-us/learn_web_development/core/frameworks_libraries/vue_conditional_rendering/index.md @@ -2,9 +2,10 @@ title: "Vue conditional rendering: editing existing todos" slug: Learn_web_development/Core/Frameworks_libraries/Vue_conditional_rendering page-type: learn-module-chapter +sidebar: learnsidebar --- -{{LearnSidebar}}{{PreviousMenuNext("Learn_web_development/Core/Frameworks_libraries/Vue_computed_properties","Learn_web_development/Core/Frameworks_libraries/Vue_refs_focus_management", "Learn_web_development/Core/Frameworks_libraries")}} +{{PreviousMenuNext("Learn_web_development/Core/Frameworks_libraries/Vue_computed_properties","Learn_web_development/Core/Frameworks_libraries/Vue_refs_focus_management", "Learn_web_development/Core/Frameworks_libraries")}} Now it is time to add one of the major parts of functionality that we're still missing — the ability to edit existing todo items. To do this, we will take advantage of Vue's conditional rendering capabilities — namely `v-if` and `v-else` — to allow us to toggle between the existing todo item view, and an edit view where you can update todo item labels. We'll also look at adding functionality to delete todo items. @@ -43,11 +44,11 @@ Now it is time to add one of the major parts of functionality that we're still m We can start by creating a separate component to handle the editing functionality. In your `components` directory, create a new file called `ToDoItemEditForm.vue`. Copy the following code into that file: -```html +```vue <template> <form class="stack-small" @submit.prevent="onSubmit"> <div> - <label class="edit-label">Edit Name for &quot;\{{label}}&quot;</label> + <label class="edit-label">Edit Name for &quot;\{{ label }}&quot;</label> <input :id="id" type="text" @@ -57,69 +58,69 @@ We can start by creating a separate component to handle the editing functionalit <div class="btn-group"> <button type="button" class="btn" @click="onCancel"> Cancel - <span class="visually-hidden">editing \{{label}}</span> + <span class="visually-hidden">editing \{{ label }}</span> </button> <button type="submit" class="btn btn__primary"> Save - <span class="visually-hidden">edit for \{{label}}</span> + <span class="visually-hidden">edit for \{{ label }}</span> </button> </div> </form> </template> <script> - export default { - props: { - label: { - type: String, - required: true, - }, - id: { - type: String, - required: true, - }, +export default { + props: { + label: { + type: String, + required: true, + }, + id: { + type: String, + required: true, }, - data() { - return { - newLabel: this.label, - }; + }, + data() { + return { + newLabel: this.label, + }; + }, + methods: { + onSubmit() { + if (this.newLabel && this.newLabel !== this.label) { + this.$emit("item-edited", this.newLabel); + } }, - methods: { - onSubmit() { - if (this.newLabel && this.newLabel !== this.label) { - this.$emit("item-edited", this.newLabel); - } - }, - onCancel() { - this.$emit("edit-cancelled"); - }, + onCancel() { + this.$emit("edit-cancelled"); }, - }; + }, +}; </script> <style scoped> - .edit-label { - font-family: Arial, sans-serif; - -webkit-font-smoothing: antialiased; - -moz-osx-font-smoothing: grayscale; - color: #0b0c0c; - display: block; - margin-bottom: 5px; - } - input { - display: inline-block; - margin-top: 0.4rem; - width: 100%; - min-height: 4.4rem; - padding: 0.4rem 0.8rem; - border: 2px solid #565656; - } - form { - display: flex; - flex-direction: row; - flex-wrap: wrap; - } - form > * { - flex: 0 0 100%; - } +.edit-label { + font-family: Arial, sans-serif; + -webkit-font-smoothing: antialiased; + -moz-osx-font-smoothing: grayscale; + color: #0b0c0c; + display: block; + margin-bottom: 5px; +} +input { + display: inline-block; + margin-top: 0.4rem; + width: 100%; + min-height: 4.4rem; + padding: 0.4rem 0.8rem; + border: 2px solid #565656; +} +form { + display: flex; + flex-direction: row; + flex-wrap: wrap; +} +form > * { + flex: 0 0 100%; +} </style> ``` @@ -139,7 +140,7 @@ Before we can add `ToDoItemEditForm` to our app, we need to make a few modificat Update your `ToDoItem`'s template as shown below. -```html +```vue <template> <div class="stack-small"> <div class="custom-checkbox"> @@ -149,14 +150,14 @@ Update your `ToDoItem`'s template as shown below. :id="id" :checked="isDone" @change="$emit('checkbox-changed')" /> - <label :for="id" class="checkbox-label">\{{label}}</label> + <label :for="id" class="checkbox-label">\{{ label }}</label> </div> <div class="btn-group"> <button type="button" class="btn" @click="toggleToItemEditForm"> - Edit <span class="visually-hidden">\{{label}}</span> + Edit <span class="visually-hidden">\{{ label }}</span> </button> <button type="button" class="btn btn__danger" @click="deleteToDo"> - Delete <span class="visually-hidden">\{{label}}</span> + Delete <span class="visually-hidden">\{{ label }}</span> </button> </div> </div> @@ -175,25 +176,33 @@ Let's define our click handlers, and the necessary `isEditing` flag. Add `isEditing` below your existing `isDone` data point: ```js -data() { - return { - isDone: this.done, - isEditing: false - }; -} +export default { + // … + data() { + return { + isDone: this.done, + isEditing: false, + }; + }, + // … +}; ``` Now add your methods inside a methods property, right below your `data()` property: ```js -methods: { +export default { + // … + methods: { deleteToDo() { - this.$emit('item-deleted'); + this.$emit("item-deleted"); }, toggleToItemEditForm() { this.isEditing = true; - } - } + }, + }, + // … +}; ``` ## Conditionally displaying components via v-if and v-else @@ -208,13 +217,13 @@ Lastly, you can use a `v-if` + `v-else` at the root of your component to display First of all add `v-if="!isEditing"` to the root `<div>` in your `ToDoItem` component, -```html +```vue <div class="stack-small" v-if="!isEditing"></div> ``` Next, below that `<div>`'s closing tag add the following line: -```html +```vue <to-do-item-edit-form v-else :id="id" :label="label"></to-do-item-edit-form> ``` @@ -227,9 +236,13 @@ import ToDoItemEditForm from "./ToDoItemEditForm"; And add a `components` property above the `props` property inside the component object: ```js -components: { - ToDoItemEditForm -}, +export default { + // … + components: { + ToDoItemEditForm, + }, + // … +}; ``` Now, if you go to your app and click a todo item's "Edit" button, you should see the checkbox replaced with the edit form. @@ -245,25 +258,41 @@ First, we need to add an `itemEdited()` method to our `ToDoItem` component's `me Add it now, below your existing methods: ```js -itemEdited(newLabel) { - this.$emit('item-edited', newLabel); - this.isEditing = false; -} +export default { + // … + methods: { + // … + itemEdited(newLabel) { + this.$emit("item-edited", newLabel); + this.isEditing = false; + }, + // … + }, + // … +}; ``` Next, we'll need an `editCancelled()` method. This method will take no arguments and just serve to set `isEditing` back to `false`. Add this method below the previous one: ```js -editCancelled() { - this.isEditing = false; -} +export default { + // … + methods: { + // … + editCancelled() { + this.isEditing = false; + }, + // … + }, + // … +}; ``` Last for this section, we'll add event handlers for the events emitted by the `ToDoItemEditForm` component, and attach the appropriate methods to each event. Update your `<to-do-item-edit-form></to-do-item-edit-form>` call to look like so: -```html +```vue <to-do-item-edit-form v-else :id="id" @@ -280,14 +309,22 @@ Now we can toggle between the edit form and the checkbox. However, we haven't ac Add the following new methods to your `App.vue`'s component object, below the existing methods inside the `methods` property: ```js -deleteToDo(toDoId) { - const itemIndex = this.ToDoItems.findIndex((item) => item.id === toDoId); - this.ToDoItems.splice(itemIndex, 1); -}, -editToDo(toDoId, newLabel) { - const toDoToEdit = this.ToDoItems.find((item) => item.id === toDoId); - toDoToEdit.label = newLabel; -} +export default { + // … + methods: { + // … + deleteToDo(toDoId) { + const itemIndex = this.ToDoItems.findIndex((item) => item.id === toDoId); + this.ToDoItems.splice(itemIndex, 1); + }, + editToDo(toDoId, newLabel) { + const toDoToEdit = this.ToDoItems.find((item) => item.id === toDoId); + toDoToEdit.label = newLabel; + }, + // … + }, + // … +}; ``` Next, we'll add the event listeners for the `item-deleted` and `item-edited` events: @@ -297,7 +334,7 @@ Next, we'll add the event listeners for the `item-deleted` and `item-edited` eve Update the `<to-do-item></to-do-item>` call inside the `App.vue` template to look like this: -```html +```vue <to-do-item :label="item.label" :done="item.done" @@ -327,17 +364,25 @@ So, let's implement the fix in `ToDoItem.vue`: 1. Remove the following line from inside our `data()` property: ```js - isDone: this.done, + export default { + // … + isDone: this.done, + // … + }; ``` -2. Add the following block below the data() { } block: +2. Add the following block below the `data() {}` block: ```js - computed: { - isDone() { - return this.done; - } - }, + export default { + // … + computed: { + isDone() { + return this.done; + }, + }, + // … + }; ``` Now when you save and reload, you'll find that the problem is solved — the checkbox state is now preserved when you switch between todo item templates. diff --git a/files/en-us/learn_web_development/core/frameworks_libraries/vue_first_component/index.md b/files/en-us/learn_web_development/core/frameworks_libraries/vue_first_component/index.md index c372576f13eff96..a6bdc28462cacc2 100644 --- a/files/en-us/learn_web_development/core/frameworks_libraries/vue_first_component/index.md +++ b/files/en-us/learn_web_development/core/frameworks_libraries/vue_first_component/index.md @@ -2,9 +2,10 @@ title: Creating our first Vue component slug: Learn_web_development/Core/Frameworks_libraries/Vue_first_component page-type: learn-module-chapter +sidebar: learnsidebar --- -{{LearnSidebar}}{{PreviousMenuNext("Learn_web_development/Core/Frameworks_libraries/Vue_getting_started","Learn_web_development/Core/Frameworks_libraries/Vue_rendering_lists", "Learn_web_development/Core/Frameworks_libraries")}} +{{PreviousMenuNext("Learn_web_development/Core/Frameworks_libraries/Vue_getting_started","Learn_web_development/Core/Frameworks_libraries/Vue_rendering_lists", "Learn_web_development/Core/Frameworks_libraries")}} Now it's time to dive deeper into Vue, and create our own custom component — we'll start by creating a component to represent each item in the todo list. Along the way, we'll learn about a few important concepts such as calling components inside other components, passing data to them via props, and saving data state. @@ -33,7 +34,7 @@ Now it's time to dive deeper into Vue, and create our own custom component — w more advanced features of Vue (like Single File Components or render functions), you'll need a terminal with <a - href="https://nodejs.org/en/download/package-manager" + href="https://nodejs.org/en/download" rel="noopener noreferrer" target="_blank" >Node</a @@ -76,7 +77,7 @@ export default {}; </script> ``` -We can now begin to add actual content to our `ToDoItem`. Vue templates are currently only allowed a single root element — one element needs to wrap everything inside the template section (this will change when Vue 3 comes out). We'll use a [`<div>`](/en-US/docs/Web/HTML/Element/div) for that root element. +We can now begin to add actual content to our `ToDoItem`. Vue templates are currently only allowed a single root element — one element needs to wrap everything inside the template section (this will change when Vue 3 comes out). We'll use a [`<div>`](/en-US/docs/Web/HTML/Reference/Elements/div) for that root element. 1. Add an empty `<div>` inside your component template now. 2. Inside that `<div>`, let's add a checkbox and a corresponding label. Add an `id` to the checkbox, and a `for` attribute mapping the checkbox to the label, as shown below. @@ -118,10 +119,10 @@ export default { This is the same way that the `HelloWorld` component was registered by the Vue CLI earlier. -To actually render the `ToDoItem` component in the app, you need to go up into your `<template>` element and call it as a `<to-do-item></to-do-item>` element. Note that the component file name and its representation in JavaScript is in PascalCase (e.g. `ToDoList`), and the equivalent custom element is in {{Glossary("kebab_case", "kebab-case")}} (e.g. `<to-do-list>`). +To actually render the `ToDoItem` component in the app, you need to go up into your `<template>` element and call it as a `<to-do-item></to-do-item>` element. Note that the component file name and its representation in JavaScript is in PascalCase (e.g., `ToDoList`), and the equivalent custom element is in {{Glossary("kebab_case", "kebab-case")}} (e.g., `<to-do-list>`). It's necessary to use this casing style if you're writing Vue templates [in the DOM directly](https://vuejs.org/guide/essentials/component-basics.html#dom-template-parsing-caveats) -1. Underneath the [`<h1>`](/en-US/docs/Web/HTML/Element/Heading_Elements), create an unordered list ([`<ul>`](/en-US/docs/Web/HTML/Element/ul)) containing a single list item ([`<li>`](/en-US/docs/Web/HTML/Element/li)). +1. Underneath the [`<h1>`](/en-US/docs/Web/HTML/Reference/Elements/Heading_Elements), create an unordered list ([`<ul>`](/en-US/docs/Web/HTML/Reference/Elements/ul)) containing a single list item ([`<li>`](/en-US/docs/Web/HTML/Reference/Elements/li)). 2. Inside the list item add `<to-do-item></to-do-item>`. The `<template>` section of your `App.vue` file should now look something like this: @@ -230,16 +231,20 @@ So that's props in a nutshell. Next we'll move on to how Vue persists data state If you change the value of the `label` prop passed into the `<to-do-item></to-do-item>` call in your `App` component, you should see it update. This is great. We have a checkbox, with an updatable label. However, we're currently not doing anything with the "done" prop — we can check the checkboxes in the UI, but nowhere in the app are we recording whether a todo item is actually done. -To achieve this, we want to bind the component's `done` prop to the `checked` attribute on the [`<input>`](/en-US/docs/Web/HTML/Element/input) element, so that it can serve as a record of whether the checkbox is checked or not. However, it's important that props serve as one-way data binding — a component should never alter the value of its own props. There are a lot of reasons for this. In part, components editing props can make debugging a challenge. If a value is passed to multiple children, it could be hard to track where the changes to that value were coming from. In addition, changing props can cause components to re-render. So mutating props in a component would trigger the component to rerender, which may in-turn trigger the mutation again. +To achieve this, we want to bind the component's `done` prop to the `checked` attribute on the [`<input>`](/en-US/docs/Web/HTML/Reference/Elements/input) element, so that it can serve as a record of whether the checkbox is checked or not. However, it's important that props serve as one-way data binding — a component should never alter the value of its own props. There are a lot of reasons for this. In part, components editing props can make debugging a challenge. If a value is passed to multiple children, it could be hard to track where the changes to that value were coming from. In addition, changing props can cause components to re-render. So mutating props in a component would trigger the component to rerender, which may in-turn trigger the mutation again. To work around this, we can manage the `done` state using Vue's `data` property. The `data` property is where you can manage local state in a component, it lives inside the component object alongside the `props` property and has the following structure: ```js -data() { - return { - key: value - } -} +export default { + // … + data() { + return { + key: value, + }; + }, + // … +}; ``` You'll note that the `data` property is a function. This is to keep the data values unique for each instance of a component at runtime — the function is invoked separately for each component instance. If you declared data as just an object, all instances of that component would share the same values. This is a side-effect of the way Vue registers components and something you do not want. @@ -323,7 +328,7 @@ export default { data() { return { isDone: this.done, - id: "todo-" + crypto.randomUUID(), + id: `todo-${crypto.randomUUID()}`, }; }, }; diff --git a/files/en-us/learn_web_development/core/frameworks_libraries/vue_getting_started/index.md b/files/en-us/learn_web_development/core/frameworks_libraries/vue_getting_started/index.md index d778175c804301b..7b1b0069ba4e09f 100644 --- a/files/en-us/learn_web_development/core/frameworks_libraries/vue_getting_started/index.md +++ b/files/en-us/learn_web_development/core/frameworks_libraries/vue_getting_started/index.md @@ -2,10 +2,9 @@ title: Getting started with Vue slug: Learn_web_development/Core/Frameworks_libraries/Vue_getting_started page-type: learn-module-chapter +sidebar: learnsidebar --- -{{LearnSidebar}} - {{NextMenu("Learn_web_development/Core/Frameworks_libraries/Vue_first_component", "Learn_web_development/Core/Frameworks_libraries")}} Now let's introduce Vue, the third of our frameworks. In this article we'll look at a little bit of Vue background, learn how to install it and create a new project, study the high-level structure of the whole project and an individual component, see how to run the project locally, and get it prepared to start building our example. @@ -59,7 +58,7 @@ As you work through this tutorial, you might want to keep the [Vue guide](https: ## Installation -To use Vue in an existing site, you can drop one of the following [`<script>`](/en-US/docs/Web/HTML/Element/script) elements onto a page. This allows you to start using Vue on existing sites, which is why Vue prides itself on being a progressive framework. This is a great option when migrating an existing project using a library like jQuery to Vue. With this method, you can use a lot of the core features of Vue, such as the attributes, custom components, and data-management. +To use Vue in an existing site, you can drop one of the following [`<script>`](/en-US/docs/Web/HTML/Reference/Elements/script) elements onto a page. This allows you to start using Vue on existing sites, which is why Vue prides itself on being a progressive framework. This is a great option when migrating an existing project using a library like jQuery to Vue. With this method, you can use a lot of the core features of Vue, such as the attributes, custom components, and data-management. - Development Script (not optimized, but includes console warnings which is great for development.) @@ -206,7 +205,7 @@ If you navigate to the "localhost" address in a new browser tab you should see y ## Making a couple of changes -Let's make our first change to the app — we'll delete the Vue logo. Open the `App.vue` file, and delete the [`<img>`](/en-US/docs/Web/HTML/Element/img) element from the template section: +Let's make our first change to the app — we'll delete the Vue logo. Open the `App.vue` file, and delete the [`<img>`](/en-US/docs/Web/HTML/Reference/Elements/img) element from the template section: ```vue <img diff --git a/files/en-us/learn_web_development/core/frameworks_libraries/vue_methods_events_models/index.md b/files/en-us/learn_web_development/core/frameworks_libraries/vue_methods_events_models/index.md index c3a6bb9013ec155..7bc8e011b88aede 100644 --- a/files/en-us/learn_web_development/core/frameworks_libraries/vue_methods_events_models/index.md +++ b/files/en-us/learn_web_development/core/frameworks_libraries/vue_methods_events_models/index.md @@ -2,9 +2,10 @@ title: "Adding a new todo form: Vue events, methods, and models" slug: Learn_web_development/Core/Frameworks_libraries/Vue_methods_events_models page-type: learn-module-chapter +sidebar: learnsidebar --- -{{LearnSidebar}}{{PreviousMenuNext("Learn_web_development/Core/Frameworks_libraries/Vue_rendering_lists","Learn_web_development/Core/Frameworks_libraries/Vue_styling", "Learn_web_development/Core/Frameworks_libraries")}} +{{PreviousMenuNext("Learn_web_development/Core/Frameworks_libraries/Vue_rendering_lists","Learn_web_development/Core/Frameworks_libraries/Vue_styling", "Learn_web_development/Core/Frameworks_libraries")}} We now have sample data in place, and a loop that takes each bit of data and renders it inside a `ToDoItem` in our app. What we really need next is the ability to allow our users to enter their own todo items into the app, and for that we'll need a text `<input>`, an event to fire when the data is submitted, a method to fire upon submission to add the data and rerender the list, and a model to control the data. This is what we'll cover in this article. @@ -49,17 +50,17 @@ We now have an app that displays a list of to-do items. However, we can't update 1. In your components folder, create a new file called `ToDoForm.vue`. 2. Add a blank `<template>` and a `<script>` tag like before: - ```html + ```vue <template></template> <script> - export default {}; + export default {}; </script> ``` -3. Let's add in an HTML form that lets you enter a new todo item and submit it into the app. We need a [`<form>`](/en-US/docs/Web/HTML/Element/form) with a [`<label>`](/en-US/docs/Web/HTML/Element/label), an [`<input>`](/en-US/docs/Web/HTML/Element/input), and a [`<button>`](/en-US/docs/Web/HTML/Element/button). Update your template as follows: +3. Let's add in an HTML form that lets you enter a new todo item and submit it into the app. We need a [`<form>`](/en-US/docs/Web/HTML/Reference/Elements/form) with a [`<label>`](/en-US/docs/Web/HTML/Reference/Elements/label), an [`<input>`](/en-US/docs/Web/HTML/Reference/Elements/input), and a [`<button>`](/en-US/docs/Web/HTML/Reference/Elements/button). Update your template as follows: - ```html + ```vue <template> <form> <label for="new-todo-input"> What needs to be done? </label> @@ -84,14 +85,19 @@ We now have an app that displays a list of to-do items. However, we can't update 5. You also need to register the new component in your `App` component — update the `components` property of the component object so that it looks like this: ```js - components: { - ToDoItem, ToDoForm, - } + export default { + // … + components: { + ToDoItem, + ToDoForm, + }, + // … + }; ``` 6. Finally for this section, render your `ToDoForm` component inside your app by adding the `<to-do-form />` element inside your `App`'s `<template>`, like so: - ```html + ```vue <template> <div id="app"> <h1>My To-Do List</h1> @@ -136,7 +142,7 @@ To make a method available to the `ToDoForm` component, we need to add it to the We'll use the shorthand syntax here for consistency. Add the `submit` handler to your `<form>` element like so: - ```html + ```vue <form @submit="onSubmit">…</form> ``` @@ -147,7 +153,7 @@ To make a method available to the `ToDoForm` component, we need to add it to the - `.stop`: Stops the event from propagating. Equivalent to [`Event.stopPropagation()`](/en-US/docs/Web/API/Event/stopPropagation) in regular JavaScript events. - `.prevent`: Prevents the event's default behavior. Equivalent to [`Event.preventDefault()`](/en-US/docs/Web/API/Event/preventDefault). - `.self`: Triggers the handler only if the event was dispatched from this exact element. - - `{.key}`: Triggers the event handler only via the specified key. [MDN has a list of valid key values](/en-US/docs/Web/API/UI_Events/Keyboard_event_key_values); multi-word keys just need to be converted to {{Glossary("kebab_case", "kebab-case")}} (e.g. `page-down`). + - `{.key}`: Triggers the event handler only via the specified key. [MDN has a list of valid key values](/en-US/docs/Web/API/UI_Events/Keyboard_event_key_values); multi-word keys just need to be converted to {{Glossary("kebab_case", "kebab-case")}} (e.g., `page-down`). - `.native`: Listens for a native event on the root (outer-most wrapping) element on your component. - `.once`: Listens for the event until it's been triggered once, and then no more. - `.left`: Only triggers the handler via the left mouse button event. @@ -157,7 +163,7 @@ To make a method available to the `ToDoForm` component, we need to add it to the In this case, we need to use the `.prevent` modifier to stop the browser's default submit action. Add `.prevent` to the `@submit` handler in your template like so: - ```html + ```vue <form @submit.prevent="onSubmit">…</form> ``` @@ -192,7 +198,7 @@ The first thing we need is a `data` property in our form to track the value of t So in our case, we would add it to our `new-todo-input` field as seen below. Do this now: - ```html + ```vue <input type="text" id="new-todo-input" @@ -209,11 +215,13 @@ The first thing we need is a `data` property in our form to track the value of t Update your `onSubmit()` method to look like this: ```js - methods: { - onSubmit() { - console.log('Label value: ', this.label); - } - }, + export default { + methods: { + onSubmit() { + console.log("Label value: ", this.label); + }, + }, + }; ``` 4. Now go back to your running app, add some text to the `<input>` field, and click the "Add" button. You should see the value you entered logged to your console, for example: @@ -228,7 +236,7 @@ In a similar fashion to event modifiers, we can also add modifiers to change the The second modifier we should consider is called `.lazy`. This modifier changes when `v-model` syncs the value for text inputs. As mentioned earlier, `v-model` syncing works by updating the variable using events. For text inputs, this sync happens using the [`input` event](/en-US/docs/Web/API/Element/input_event). Often, this means that Vue is syncing the data after every keystroke. The `.lazy` modifier causes `v-model` to use the [`change` event](/en-US/docs/Web/API/HTMLElement/change_event) instead. This means that Vue will only sync data when the input loses focus or the form is submitted. For our purposes, this is much more reasonable since we only need the final data. -To use both the `.lazy` modifier and the `.trim` modifier together, we can chain them, e.g. `v-model.lazy.trim="label"`. +To use both the `.lazy` modifier and the `.trim` modifier together, we can chain them, e.g., `v-model.lazy.trim="label"`. Update your `v-model` attribute to chain `lazy` and `trim` as shown above, and then test your app again. Try for example, submitting a value with whitespace at each end. @@ -256,15 +264,15 @@ In the `onSubmit` event handler of our `ToDoForm`, let's add a `todo-added` even data() { return { ToDoItems: [ - { id: "todo-" + nanoid(), label: "Learn Vue", done: false }, + { id: `todo-${nanoid()}`, label: "Learn Vue", done: false }, { - id: "todo-" + nanoid(), + id: `todo-${nanoid()}`, label: "Create a Vue project with the CLI", done: true, }, - { id: "todo-" + nanoid(), label: "Have fun", done: true }, + { id: `todo-${nanoid()}`, label: "Have fun", done: true }, { - id: "todo-" + nanoid(), + id: `todo-${nanoid()}`, label: "Create a to-do list", done: false, }, @@ -281,7 +289,7 @@ In the `onSubmit` event handler of our `ToDoForm`, let's add a `todo-added` even 3. Next, add an event listener for the `todo-added` event to the `<to-do-form></to-do-form>`, which calls the `addToDo()` method when the event fires. Using the `@` shorthand, the listener would look like this: `@todo-added="addToDo"`: - ```html + ```vue <to-do-form @todo-added="addToDo"></to-do-form> ``` @@ -292,9 +300,17 @@ In the `onSubmit` event handler of our `ToDoForm`, let's add a `todo-added` even Update your `onSubmit()` method like so: ```js - onSubmit() { - this.$emit('todo-added', this.label) - } + export default { + // … + methods: { + // … + onSubmit() { + this.$emit("todo-added", this.label); + }, + // … + }, + // … + }; ``` 5. To actually pick up this data inside `App.vue`, we need to add a parameter to our `addToDo()` method that includes the `label` of the new to-do item. @@ -302,11 +318,17 @@ In the `onSubmit` event handler of our `ToDoForm`, let's add a `todo-added` even Go back to `App.vue` and update this now: ```js - methods: { - addToDo(toDoLabel) { - console.log('To-do added:', toDoLabel); - } - } + export default { + // … + methods: { + // … + addToDo(toDoLabel) { + console.log("To-do added:", toDoLabel); + }, + // … + }, + // … + }; ``` If you test your form again, you'll see whatever text you enter logged in your console upon submission. Vue automatically passes the arguments after the event name in `this.$emit()` to your event handler. @@ -318,9 +340,21 @@ Now that we have the data from `ToDoForm` available in `App.vue`, we need to add 1. Update your `addToDo()` method like so: ```js - addToDo(toDoLabel) { - this.ToDoItems.push({id: "todo-" + nanoid(), label: toDoLabel, done: false}); - } + export default { + // … + methods: { + // … + addToDo(toDoLabel) { + this.ToDoItems.push({ + id: `todo-${nanoid()}`, + label: toDoLabel, + done: false, + }); + }, + // … + }, + // … + }; ``` 2. Try testing your form again, and you should see new to-do items get appended to the end of the list. @@ -329,12 +363,20 @@ Now that we have the data from `ToDoForm` available in `App.vue`, we need to add Go back to your `ToDoForm` component, and update the `onSubmit()` method like so. If the label value is empty, let's not emit the `todo-added` event. ```js - onSubmit() { - if (this.label === "") { - return; - } - this.$emit('todo-added', this.label); - } + export default { + // … + methods: { + // … + onSubmit() { + if (this.label === "") { + return; + } + this.$emit("todo-added", this.label); + }, + // … + }, + // … + }; ``` 4. Try your form again. Now you will not be able to add empty items to the to-do list. @@ -348,13 +390,21 @@ There's one more thing to fix in our `ToDoForm` component — after submitting, Update your `ToDoForm` component's `onSubmit()` method to this: ```js -onSubmit() { - if (this.label === "") { - return; - } - this.$emit('todo-added', this.label); - this.label = ""; -} +export default { + // … + methods: { + // … + onSubmit() { + if (this.label === "") { + return; + } + this.$emit("todo-added", this.label); + this.label = ""; + }, + // … + }, + // … +}; ``` Now when you click the "Add" button, the "new-todo-input" will clear itself. diff --git a/files/en-us/learn_web_development/core/frameworks_libraries/vue_refs_focus_management/index.md b/files/en-us/learn_web_development/core/frameworks_libraries/vue_refs_focus_management/index.md index 2b54374d206f4f0..0a360fa040fafe5 100644 --- a/files/en-us/learn_web_development/core/frameworks_libraries/vue_refs_focus_management/index.md +++ b/files/en-us/learn_web_development/core/frameworks_libraries/vue_refs_focus_management/index.md @@ -2,9 +2,10 @@ title: Vue refs and lifecycle methods for focus management slug: Learn_web_development/Core/Frameworks_libraries/Vue_refs_focus_management page-type: learn-module-chapter +sidebar: learnsidebar --- -{{LearnSidebar}}{{PreviousMenuNext("Learn_web_development/Core/Frameworks_libraries/Vue_conditional_rendering","Learn_web_development/Core/Frameworks_libraries/Vue_resources", "Learn_web_development/Core/Frameworks_libraries")}} +{{PreviousMenuNext("Learn_web_development/Core/Frameworks_libraries/Vue_conditional_rendering","Learn_web_development/Core/Frameworks_libraries/Vue_resources", "Learn_web_development/Core/Frameworks_libraries")}} We are nearly done with Vue. The last bit of functionality to look at is focus management, or put another way, how we can improve our app's keyboard accessibility. We'll look at using **Vue refs** to handle this — an advanced feature that allows you to have direct access to the underlying DOM nodes below the virtual DOM, or direct access from one component to the internal DOM structure of a child component. @@ -71,7 +72,7 @@ To use a ref in a component, you add a `ref` attribute to the element that you w So, let's attach a ref to our "Edit" button in `ToDoItem.vue`. Update it like this: -```html +```vue <button type="button" class="btn" @@ -85,10 +86,18 @@ So, let's attach a ref to our "Edit" button in `ToDoItem.vue`. Update it like th To access the value associated with our ref, we use the `$refs` property provided on our component instance. To see the value of the ref when we click our "Edit" button, add a `console.log()` to our `toggleToItemEditForm()` method, like so: ```js -toggleToItemEditForm() { - console.log(this.$refs.editButton); - this.isEditing = true; -} +export default { + // … + methods: { + // … + toggleToItemEditForm() { + console.log(this.$refs.editButton); + this.isEditing = true; + }, + // … + }, + // … +}; ``` If you activate the "Edit" button at this point, you should see an HTML `<button>` element referenced in your console. @@ -100,24 +109,40 @@ We want to set focus on the "Edit" button when a user saves or cancels their edi For convenience, create a new method which takes no arguments called `focusOnEditButton()`. Inside it, assign your `ref` to a variable, and then call the `focus()` method on the ref. ```js -focusOnEditButton() { - const editButtonRef = this.$refs.editButton; - editButtonRef.focus(); -} +export default { + // … + methods: { + // … + focusOnEditButton() { + const editButtonRef = this.$refs.editButton; + editButtonRef.focus(); + }, + // … + }, + // … +}; ``` Next, add a call to `this.focusOnEditButton()` at the end of the `itemEdited()` and `editCancelled()` methods: ```js -itemEdited(newItemName) { - this.$emit("item-edited", newItemName); - this.isEditing = false; - this.focusOnEditButton(); -}, -editCancelled() { - this.isEditing = false; - this.focusOnEditButton(); -}, +export default { + // … + methods: { + // … + itemEdited(newItemName) { + this.$emit("item-edited", newItemName); + this.isEditing = false; + this.focusOnEditButton(); + }, + editCancelled() { + this.isEditing = false; + this.focusOnEditButton(); + }, + // … + }, + // … +}; ``` Try editing and then saving/cancelling a to-do item via your keyboard. You'll notice that focus isn't being set, so we still have a problem to solve. If you open your console, you'll see an error raised along the lines of _"can't access property "focus", editButtonRef is undefined"_. This seems weird. Your button ref was defined when you activated the "Edit" button, but now it's not. What is going on? @@ -131,12 +156,20 @@ Instead, we need to wait until after Vue undergoes the next DOM update cycle. To Since the `focusOnEditButton()` method needs to be invoked after the DOM has updated, we can wrap the existing function body inside a `$nextTick()` call. ```js -focusOnEditButton() { - this.$nextTick(() => { - const editButtonRef = this.$refs.editButton; - editButtonRef.focus(); - }); -} +export default { + // … + methods: { + // … + focusOnEditButton() { + this.$nextTick(() => { + const editButtonRef = this.$refs.editButton; + editButtonRef.focus(); + }); + }, + // … + }, + // … +}; ``` Now when you activate the "Edit" button and then cancel or save your changes via the keyboard, focus should be returned to the "Edit" button. Success! @@ -167,7 +200,7 @@ Now that we've gone over the lifecycle methods, let's use one to trigger focus w In `ToDoItemEditForm.vue`, attach `ref="labelInput"` to the `<input>` element, like so: -```html +```vue <input :id="id" ref="labelInput" @@ -179,18 +212,24 @@ In `ToDoItemEditForm.vue`, attach `ref="labelInput"` to the `<input>` element, l Next, add a `mounted()` property just inside your component object — **note that this should not be put inside the `methods` property, but rather at the same hierarchy level as `props`, `data()`, and `methods`.** Lifecycle methods are special methods that sit on their own, not alongside the user-defined methods. This should take no inputs. Note that you cannot use an arrow function here since we need access to `this` to access our `labelInput` ref. ```js -mounted() { - -} +export default { + // … + mounted() {}, + // … +}; ``` Inside your `mounted()` method, assign your `labelInput` ref to a variable, and then call the `focus()` function of the ref. You don't have to use `$nextTick()` here because the component has already been added to the DOM when `mounted()` is called. ```js -mounted() { - const labelInputRef = this.$refs.labelInput; - labelInputRef.focus(); -} +export default { + // … + mounted() { + const labelInputRef = this.$refs.labelInput; + labelInputRef.focus(); + }, + // … +}; ``` Now when you activate the "Edit" button with your keyboard, focus should immediately be moved to the edit `<input>`. @@ -203,24 +242,32 @@ However, unlike with the edit form, we don't have a clear location for focus to We're already tracking the number of elements in our list heading — the `<h2>` in `App.vue` — and it's associated with our list of to-do items. This makes it a reasonable place to move focus to when we delete a node. -First, we need to add a ref to our list heading. We also need to add a `tabindex="-1"` to it — this makes the element programmatically focusable (i.e. it can be focused via JavaScript), when by default it is not. +First, we need to add a ref to our list heading. We also need to add a `tabindex="-1"` to it — this makes the element programmatically focusable (i.e., it can be focused via JavaScript), when by default it is not. Inside `App.vue`, update your `<h2>` as follows: -```html +```vue <h2 id="list-summary" ref="listSummary" tabindex="-1">\{{listSummary}}</h2> ``` -> **Note:** [`tabindex`](/en-US/docs/Web/HTML/Global_attributes/tabindex) is a really powerful tool for handling certain accessibility problems. However, it should be used with caution. Over-using `tabindex="-1"` can cause problems for all sorts of users, so only use it exactly where you need to. You should also almost never use `tabindex` > = `0`, as it can cause problems for users since it can make the DOM flow and the tab-order mismatch, and/or add non-interactive elements to the tab order. This can be confusing to users, especially those using screen readers and other assistive technology. +> **Note:** [`tabindex`](/en-US/docs/Web/HTML/Reference/Global_attributes/tabindex) is a really powerful tool for handling certain accessibility problems. However, it should be used with caution. Over-using `tabindex="-1"` can cause problems for all sorts of users, so only use it exactly where you need to. You should also almost never use `tabindex` > = `0`, as it can cause problems for users since it can make the DOM flow and the tab-order mismatch, and/or add non-interactive elements to the tab order. This can be confusing to users, especially those using screen readers and other assistive technology. Now that we have a `ref` and have let browsers know that we can programmatically focus the `<h2>`, we need to set focus on it. At the end of `deleteToDo()`, use the `listSummary` ref to set focus on the `<h2>`. Since the `<h2>` is always rendered in the app, you do not need to worry about using `$nextTick()` or lifecycle methods to handle focusing it. ```js -deleteToDo(toDoId) { - const itemIndex = this.ToDoItems.findIndex((item) => item.id === toDoId); - this.ToDoItems.splice(itemIndex, 1); - this.$refs.listSummary.focus(); -} +export default { + // … + methods: { + // … + deleteToDo(toDoId) { + const itemIndex = this.ToDoItems.findIndex((item) => item.id === toDoId); + this.ToDoItems.splice(itemIndex, 1); + this.$refs.listSummary.focus(); + }, + // … + }, + // … +}; ``` Now, when you delete an item from your list, focus should be moved up to the list heading. This should provide a reasonable focus experience for all of our users. diff --git a/files/en-us/learn_web_development/core/frameworks_libraries/vue_rendering_lists/index.md b/files/en-us/learn_web_development/core/frameworks_libraries/vue_rendering_lists/index.md index 52f4b0916ad74ea..b49b7a51df41375 100644 --- a/files/en-us/learn_web_development/core/frameworks_libraries/vue_rendering_lists/index.md +++ b/files/en-us/learn_web_development/core/frameworks_libraries/vue_rendering_lists/index.md @@ -2,9 +2,10 @@ title: Rendering a list of Vue components slug: Learn_web_development/Core/Frameworks_libraries/Vue_rendering_lists page-type: learn-module-chapter +sidebar: learnsidebar --- -{{LearnSidebar}}{{PreviousMenuNext("Learn_web_development/Core/Frameworks_libraries/Vue_first_component","Learn_web_development/Core/Frameworks_libraries/Vue_methods_events_models", "Learn_web_development/Core/Frameworks_libraries")}} +{{PreviousMenuNext("Learn_web_development/Core/Frameworks_libraries/Vue_first_component","Learn_web_development/Core/Frameworks_libraries/Vue_methods_events_models", "Learn_web_development/Core/Frameworks_libraries")}} At this point we've got a fully working component; we're now ready to add multiple `ToDoItem` components to our app. In this article we'll look at adding a set of todo item data to our `App.vue` component, which we'll then loop through and display inside `ToDoItem` components using the `v-for` directive. @@ -87,13 +88,13 @@ To make sure that Vue can accurately compare the `key` attributes, they need to import { nanoid } from "nanoid"; ``` -2. Next, add an `id` field to each element in your `ToDoItems` array, and assign each of them a value of `"todo-" + nanoid()`. +2. Next, add an `id` field to each element in your `ToDoItems` array, and assign each of them a value of `` `todo-${nanoid()}` ``. The `<script>` element in `App.vue` should now have the following contents: ```js - import ToDoItem from "./components/ToDoItem.vue"; import { nanoid } from "nanoid"; + import ToDoItem from "./components/ToDoItem.vue"; export default { name: "app", @@ -103,15 +104,15 @@ To make sure that Vue can accurately compare the `key` attributes, they need to data() { return { ToDoItems: [ - { id: "todo-" + nanoid(), label: "Learn Vue", done: false }, + { id: `todo-${nanoid()}`, label: "Learn Vue", done: false }, { - id: "todo-" + nanoid(), + id: `todo-${nanoid()}`, label: "Create a Vue project with the CLI", done: true, }, - { id: "todo-" + nanoid(), label: "Have fun", done: true }, + { id: `todo-${nanoid()}`, label: "Have fun", done: true }, { - id: "todo-" + nanoid(), + id: `todo-${nanoid()}`, label: "Create a to-do list", done: false, }, diff --git a/files/en-us/learn_web_development/core/frameworks_libraries/vue_resources/index.md b/files/en-us/learn_web_development/core/frameworks_libraries/vue_resources/index.md index c006a0dc7daba9f..eeaa48ee49c2923 100644 --- a/files/en-us/learn_web_development/core/frameworks_libraries/vue_resources/index.md +++ b/files/en-us/learn_web_development/core/frameworks_libraries/vue_resources/index.md @@ -2,10 +2,9 @@ title: Vue resources slug: Learn_web_development/Core/Frameworks_libraries/Vue_resources page-type: learn-module-chapter +sidebar: learnsidebar --- -{{LearnSidebar}} - {{PreviousMenu("Learn_web_development/Core/Frameworks_libraries/Vue_refs_focus_management", "Learn_web_development/Core/Frameworks_libraries")}} Now we'll round off our study of Vue by giving you a list of resources that you can use to go further in your learning, plus some other useful tips. diff --git a/files/en-us/learn_web_development/core/frameworks_libraries/vue_styling/index.md b/files/en-us/learn_web_development/core/frameworks_libraries/vue_styling/index.md index 854c2df090aa33f..fd852d1d46a2152 100644 --- a/files/en-us/learn_web_development/core/frameworks_libraries/vue_styling/index.md +++ b/files/en-us/learn_web_development/core/frameworks_libraries/vue_styling/index.md @@ -2,9 +2,10 @@ title: Styling Vue components with CSS slug: Learn_web_development/Core/Frameworks_libraries/Vue_styling page-type: learn-module-chapter +sidebar: learnsidebar --- -{{LearnSidebar}}{{PreviousMenuNext("Learn_web_development/Core/Frameworks_libraries/Vue_methods_events_models","Learn_web_development/Core/Frameworks_libraries/Vue_computed_properties", "Learn_web_development/Core/Frameworks_libraries")}} +{{PreviousMenuNext("Learn_web_development/Core/Frameworks_libraries/Vue_methods_events_models","Learn_web_development/Core/Frameworks_libraries/Vue_computed_properties", "Learn_web_development/Core/Frameworks_libraries")}} The time has finally come to make our app look a bit nicer. In this article we'll explore the different ways of styling Vue components with CSS. @@ -167,118 +168,117 @@ There are already some styles present in the file. Let's remove those and replac Update your `App.vue` file's `<style>` element so it looks like so: -```html +```vue <style> - /* Global styles */ - .btn { - padding: 0.8rem 1rem 0.7rem; - border: 0.2rem solid #4d4d4d; - cursor: pointer; - text-transform: capitalize; - } - .btn__danger { - color: #fff; - background-color: #ca3c3c; - border-color: #bd2130; - } - .btn__filter { - border-color: lightgrey; - } - .btn__danger:focus { - outline-color: #c82333; - } - .btn__primary { - color: #fff; - background-color: #000; - } - .btn-group { - display: flex; - justify-content: space-between; - } - .btn-group > * { - flex: 1 1 auto; - } - .btn-group > * + * { - margin-left: 0.8rem; - } - .label-wrapper { - margin: 0; - flex: 0 0 100%; - text-align: center; - } +/* Global styles */ +.btn { + padding: 0.8rem 1rem 0.7rem; + border: 0.2rem solid #4d4d4d; + cursor: pointer; + text-transform: capitalize; +} +.btn__danger { + color: #fff; + background-color: #ca3c3c; + border-color: #bd2130; +} +.btn__filter { + border-color: lightgrey; +} +.btn__danger:focus { + outline-color: #c82333; +} +.btn__primary { + color: #fff; + background-color: #000; +} +.btn-group { + display: flex; + justify-content: space-between; +} +.btn-group > * { + flex: 1 1 auto; +} +.btn-group > * + * { + margin-left: 0.8rem; +} +.label-wrapper { + margin: 0; + flex: 0 0 100%; + text-align: center; +} +[class*="__lg"] { + display: inline-block; + width: 100%; + font-size: 1.9rem; +} +[class*="__lg"]:not(:last-child) { + margin-bottom: 1rem; +} +@media screen and (min-width: 620px) { [class*="__lg"] { - display: inline-block; - width: 100%; - font-size: 1.9rem; - } - [class*="__lg"]:not(:last-child) { - margin-bottom: 1rem; - } - @media screen and (min-width: 620px) { - [class*="__lg"] { - font-size: 2.4rem; - } - } - .visually-hidden { - position: absolute; - height: 1px; - width: 1px; - overflow: hidden; - clip: rect(1px 1px 1px 1px); - clip: rect(1px, 1px, 1px, 1px); - clip-path: rect(1px, 1px, 1px, 1px); - white-space: nowrap; - } - [class*="stack"] > * { - margin-top: 0; - margin-bottom: 0; + font-size: 2.4rem; } +} +.visually-hidden { + position: absolute; + height: 1px; + width: 1px; + overflow: hidden; + clip: rect(1px, 1px, 1px, 1px); + clip-path: rect(1px 1px 1px 1px); + white-space: nowrap; +} +[class*="stack"] > * { + margin-top: 0; + margin-bottom: 0; +} +.stack-small > * + * { + margin-top: 1.25rem; +} +.stack-large > * + * { + margin-top: 2.5rem; +} +@media screen and (min-width: 550px) { .stack-small > * + * { - margin-top: 1.25rem; + margin-top: 1.4rem; } .stack-large > * + * { - margin-top: 2.5rem; + margin-top: 2.8rem; } - @media screen and (min-width: 550px) { - .stack-small > * + * { - margin-top: 1.4rem; - } - .stack-large > * + * { - margin-top: 2.8rem; - } - } - /* End global styles */ +} +/* End global styles */ +#app { + background: #fff; + margin: 2rem 0 4rem 0; + padding: 1rem; + padding-top: 0; + position: relative; + box-shadow: + 0 2px 4px 0 rgb(0 0 0 / 20%), + 0 2.5rem 5rem 0 rgb(0 0 0 / 10%); +} +@media screen and (min-width: 550px) { #app { - background: #fff; - margin: 2rem 0 4rem 0; - padding: 1rem; - padding-top: 0; - position: relative; - box-shadow: - 0 2px 4px 0 rgb(0 0 0 / 20%), - 0 2.5rem 5rem 0 rgb(0 0 0 / 10%); - } - @media screen and (min-width: 550px) { - #app { - padding: 4rem; - } - } - #app > * { - max-width: 50rem; - margin-left: auto; - margin-right: auto; - } - #app > form { - max-width: 100%; - } - #app h1 { - display: block; - min-width: 100%; - width: 100%; - text-align: center; - margin: 0; - margin-bottom: 1rem; + padding: 4rem; } +} +#app > * { + max-width: 50rem; + margin-left: auto; + margin-right: auto; +} +#app > form { + max-width: 100%; +} +#app h1 { + display: block; + min-width: 100%; + width: 100%; + text-align: center; + margin: 0; + margin-bottom: 1rem; +} </style> ``` @@ -336,9 +336,9 @@ The last component we want to style is our `ToDoItem` component. To keep the sty To use the `scoped` modifier, create a `<style>` element inside `ToDoItem.vue`, at the bottom of the file, and give it a `scoped` attribute: -```html +```vue <style scoped> - /* … */ +/* … */ </style> ``` @@ -350,7 +350,6 @@ Next, copy the following CSS into the newly created `<style>` element: -webkit-font-smoothing: antialiased; -moz-osx-font-smoothing: grayscale; font-weight: 400; - font-size: 16px; font-size: 1rem; line-height: 1.25; color: #0b0c0c; @@ -362,12 +361,10 @@ Next, copy the following CSS into the newly created `<style>` element: -webkit-font-smoothing: antialiased; -moz-osx-font-smoothing: grayscale; font-weight: 400; - font-size: 16px; font-size: 1rem; line-height: 1.25; box-sizing: border-box; width: 100%; - height: 40px; height: 2.5rem; margin-top: 0; padding: 5px; @@ -452,7 +449,6 @@ Next, copy the following CSS into the newly created `<style>` element: label, input, .custom-checkbox { - font-size: 19px; font-size: 1.9rem; line-height: 1.31579; } diff --git a/files/en-us/learn_web_development/core/index.md b/files/en-us/learn_web_development/core/index.md index 2ddf84528141e14..7a8657c24f6bb4c 100644 --- a/files/en-us/learn_web_development/core/index.md +++ b/files/en-us/learn_web_development/core/index.md @@ -2,10 +2,9 @@ title: Core learning modules slug: Learn_web_development/Core page-type: landing-page +sidebar: learnsidebar --- -{{LearnSidebar}} - Our **Core modules** cover topics that we feel every web developer should have a good grounding in. This includes all the information they need to design and build a basic, accessible web app that follows modern best practices, and manage and deploy their code using appropriate tools. ## Prerequisites @@ -37,5 +36,5 @@ In particular, if you've never done any coding before, we'd recommend the [Your ## See also -- [The Frontend Developer Career Path](https://v2.scrimba.com/the-frontend-developer-career-path-c0j?via=mdn) <sup>_MDN learning partner_</sup> - - : [Scrimba's](https://scrimba.com?via=mdn) _Frontend Developer Career Path_ teaches all you need to know to be a competent front-end web developer, with fun interactive lessons and challenges, knowledgeable teachers, and a supportive community. Go from zero to landing your first front-end job! Many of the course components are available as standalone free versions. +- [The Frontend Developer Career Path](https://scrimba.com/the-frontend-developer-career-path-c0j?via=mdn) <sup>[_MDN learning partner_](/en-US/docs/MDN/Writing_guidelines/Learning_content#partner_links_and_embeds)</sup> + - : [Scrimba's](https://scrimba.com/?via=mdn) _Frontend Developer Career Path_ teaches all you need to know to be a competent front-end web developer, with fun interactive lessons and challenges, knowledgeable teachers, and a supportive community. Go from zero to landing your first front-end job! Many of the course components are available as standalone free versions. diff --git a/files/en-us/learn_web_development/core/scripting/a_first_splash/index.md b/files/en-us/learn_web_development/core/scripting/a_first_splash/index.md index 0848c76450a49d4..0989709ea0ac064 100644 --- a/files/en-us/learn_web_development/core/scripting/a_first_splash/index.md +++ b/files/en-us/learn_web_development/core/scripting/a_first_splash/index.md @@ -1,11 +1,11 @@ --- title: A first splash into JavaScript +short-title: JavaScript walkthrough slug: Learn_web_development/Core/Scripting/A_first_splash page-type: learn-module-chapter +sidebar: learnsidebar --- -{{LearnSidebar}} - {{PreviousMenuNext("Learn_web_development/Core/Scripting/What_is_JavaScript", "Learn_web_development/Core/Scripting/What_went_wrong", "Learn_web_development/Core/Scripting")}} Now you've learned something about the theory of JavaScript and what you can do with it, we are going to give you an idea of what the process of creating a simple JavaScript program is like, by guiding you through a practical tutorial. Here you'll build up a simple "Guess the number" game, step by step. @@ -322,7 +322,7 @@ function checkGuess() { This is a lot of code — phew! Let's go through each section and explain what it does. - The first line declares a variable called `userGuess` and sets its value to the current value entered inside the text field. We also run this value through the built-in `Number()` constructor, just to make sure the value is definitely a number. Since we're not changing this variable, we'll declare it using `const`. -- Next, we encounter our first conditional code block. A conditional code block allows you to run code selectively, depending on whether a certain condition is true or not. It looks a bit like a function, but it isn't. The simplest form of conditional block starts with the keyword `if`, then some parentheses, then some curly braces. Inside the parentheses, we include a test. If the test returns `true`, we run the code inside the curly braces. If not, we don't, and move on to the next bit of code. In this case, the test is testing whether the `guessCount` variable is equal to `1` (i.e. whether this is the player's first go or not): +- Next, we encounter our first conditional code block. A conditional code block allows you to run code selectively, depending on whether a certain condition is true or not. It looks a bit like a function, but it isn't. The simplest form of conditional block starts with the keyword `if`, then some parentheses, then some curly braces. Inside the parentheses, we include a test. If the test returns `true`, we run the code inside the curly braces. If not, we don't, and move on to the next bit of code. In this case, the test is testing whether the `guessCount` variable is equal to `1` (i.e., whether this is the player's first go or not): ```js guessCount === 1; @@ -335,7 +335,7 @@ This is a lot of code — phew! Let's go through each section and explain what i - The first `if (){ }` checks whether the user's guess is equal to the `randomNumber` set at the top of our JavaScript. If it is, the player has guessed correctly and the game is won, so we show the player a congratulations message with a nice green color, clear the contents of the Low/High guess information box, and run a function called `setGameOver()`, which we'll discuss later. - Now we've chained another test onto the end of the last one using an `else if (){ }` structure. This one checks whether this turn is the user's last turn. If it is, the program does the same thing as in the previous block, except with a game over message instead of a congratulations message. - - The final block chained onto the end of this code (the `else { }`) contains code that is only run if neither of the other two tests returns true (i.e. the player didn't guess right, but they have more guesses left). In this case we tell them they are wrong, then we perform another conditional test to check whether the guess was higher or lower than the answer, displaying a further message as appropriate to tell them higher or lower. + - The final block chained onto the end of this code (the `else { }`) contains code that is only run if neither of the other two tests returns true (i.e., the player didn't guess right, but they have more guesses left). In this case we tell them they are wrong, then we perform another conditional test to check whether the guess was higher or lower than the answer, displaying a further message as appropriate to tell them higher or lower. - The last three lines in the function get us ready for the next guess to be submitted. We add 1 to the `guessCount` variable so the player uses up their turn (`++` is an increment operation — increase by 1), and empty the value out of the form text field and focus it again, ready for the next guess to be entered. diff --git a/files/en-us/learn_web_development/core/scripting/arrays/index.md b/files/en-us/learn_web_development/core/scripting/arrays/index.md index 78f439a1ade1146..82eb815bf21a1e0 100644 --- a/files/en-us/learn_web_development/core/scripting/arrays/index.md +++ b/files/en-us/learn_web_development/core/scripting/arrays/index.md @@ -2,13 +2,12 @@ title: Arrays slug: Learn_web_development/Core/Scripting/Arrays page-type: learn-module-chapter +sidebar: learnsidebar --- -{{LearnSidebar}} - {{PreviousMenuNext("Learn_web_development/Core/Scripting/Useful_string_methods", "Learn_web_development/Core/Scripting/Silly_story_generator", "Learn_web_development/Core/Scripting")}} -In this lesson we'll look at arrays — a neat way of storing a list of data items under a single variable name. Here we look at why this is useful, then explore how to create an array, retrieve, add, and remove items stored in an array, and more besides. +In this lesson we'll look at arrays — a neat way of storing a list of data items under a single variable name. Here we look at why this is useful, then explore how to create an [array](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array), retrieve, add, and remove items stored in an array, and more besides. <table> <tbody> @@ -39,6 +38,9 @@ If we didn't have arrays, we'd have to store every item in a separate variable, As in previous articles, let's learn about the real basics of arrays by entering some examples into [browser developer console](/en-US/docs/Learn_web_development/Howto/Tools_and_setup/What_are_browser_developer_tools). +> [!NOTE] +> Scrimba's [Aside: Intro to arrays](https://scrimba.com/the-frontend-developer-career-path-c0j/~06e?via=mdn) scrim <sup>[_MDN learning partner_](/en-US/docs/MDN/Writing_guidelines/Learning_content#partner_links_and_embeds)</sup> provides a useful interactive introduction to arrays with example walkthroughs and a challenge to test your knowledge. + ## Creating arrays Arrays consist of square brackets and items that are separated by commas. @@ -70,7 +72,7 @@ console.log(shopping.length); // 5 ## Accessing and modifying array items -Items in an array are numbered, starting from zero. This number is called the item's _index_. So the first item has index 0, the second has index 1, and so on. You can access individual items in the array using bracket notation and supplying the item's index, in the same way that you [accessed the letters in a string](/en-US/docs/Learn_web_development/Core/Scripting/Useful_string_methods#retrieving_a_specific_string_character). +Arrays are [indexed collections](/en-US/docs/Web/JavaScript/Guide/Indexed_collections). Items in an array are numbered, starting from zero. This number is called the item's _index_. So the first item has index 0, the second has index 1, and so on. You can access individual items in the array using bracket notation and supplying the item's index, in the same way that you [accessed the letters in a string](/en-US/docs/Learn_web_development/Core/Scripting/Useful_string_methods#retrieving_a_specific_string_character). 1. Enter the following into your console: @@ -676,7 +678,7 @@ textarea.onkeyup = () => { ## Test your skills! -You've reached the end of this article, but can you remember the most important information? You can find some further tests to verify that you've retained this information before you move on — see [Test your skills: Arrays](/en-US/docs/Learn_web_development/Core/Scripting/Test_your_skills:_Arrays). +You've reached the end of this article, but can you remember the most important information? You can find some further tests to verify that you've retained this information before you move on — see [Test your skills: Arrays](/en-US/docs/Learn_web_development/Core/Scripting/Test_your_skills/Arrays). ## Conclusion @@ -686,11 +688,7 @@ In the next article we're giving you a challenge to test your understanding of t ## See also -- [Indexed collections](/en-US/docs/Web/JavaScript/Guide/Indexed_collections) - - : An advanced level guide to arrays and their cousins, typed arrays. - {{jsxref("Array")}} - - : The `Array` object reference page — for a detailed reference guide to the features discussed in this page, and many more. -- [Aside: Intro to arrays](https://v2.scrimba.com/the-frontend-developer-career-path-c0j/~06e?via=mdn), Scrimba <sup>_MDN learning partner_</sup> - - : An interactive lesson providing an introduction to arrays. + - : The `Array` object reference page provides a detailed reference guide to the features discussed in this page, and many other `Array` features. {{PreviousMenuNext("Learn_web_development/Core/Scripting/Useful_string_methods", "Learn_web_development/Core/Scripting/Silly_story_generator", "Learn_web_development/Core/Scripting")}} diff --git a/files/en-us/learn_web_development/core/scripting/build_your_own_function/index.md b/files/en-us/learn_web_development/core/scripting/build_your_own_function/index.md index 8bb429eaf05bb67..701c53c6b6fa54b 100644 --- a/files/en-us/learn_web_development/core/scripting/build_your_own_function/index.md +++ b/files/en-us/learn_web_development/core/scripting/build_your_own_function/index.md @@ -2,10 +2,9 @@ title: Build your own function slug: Learn_web_development/Core/Scripting/Build_your_own_function page-type: learn-module-chapter +sidebar: learnsidebar --- -{{LearnSidebar}} - {{PreviousMenuNext("Learn_web_development/Core/Scripting/Functions","Learn_web_development/Core/Scripting/Return_values", "Learn_web_development/Core/Scripting")}} With most of the essential theory dealt with in the previous article, this article provides practical experience. Here you will get some practice building your own, custom function. Along the way, we'll also explain some useful details of dealing with functions. @@ -54,9 +53,9 @@ To begin with, let's put together a basic function. 1. Start by accessing the [function-start.html](https://github.com/mdn/learning-area/blob/main/javascript/building-blocks/functions/function-start.html) file and making a local copy. You'll see that the HTML is simple — the body contains just a single button. We've also provided some basic CSS to style the custom message box, and an empty {{htmlelement("script")}} element to put our JavaScript in. 2. Next, add the following inside the `<script>` element: - ```js-nolint + ```js function displayMessage() { - ... + // … } ``` @@ -293,7 +292,7 @@ On to the next parameter. This one is going to involve slightly more work — we ## Test your skills! -You've reached the end of this article, but can you remember the most important information? You can find some further tests to verify that you've retained this information before you move on — see [Test your skills: Functions](/en-US/docs/Learn_web_development/Core/Scripting/Building_blocks/Test_your_skills:_Functions). These tests require skills that are covered in the next article, so you might want to read that first before trying the test. +You've reached the end of this article, but can you remember the most important information? You can find some further tests to verify that you've retained this information before you move on — see [Test your skills: Functions](/en-US/docs/Learn_web_development/Core/Scripting/Test_your_skills/Functions). These tests require skills that are covered in the next article, so you might want to read that first before trying the test. ## Summary diff --git a/files/en-us/learn_web_development/core/scripting/conditionals/index.md b/files/en-us/learn_web_development/core/scripting/conditionals/index.md index e4b14acddc35b47..6b732c6c8142738 100644 --- a/files/en-us/learn_web_development/core/scripting/conditionals/index.md +++ b/files/en-us/learn_web_development/core/scripting/conditionals/index.md @@ -1,11 +1,11 @@ --- title: Making decisions in your code — conditionals +short-title: Conditionals slug: Learn_web_development/Core/Scripting/Conditionals page-type: learn-module-chapter +sidebar: learnsidebar --- -{{LearnSidebar}} - {{PreviousMenuNext("Learn_web_development/Core/Scripting/Silly_story_generator", "Learn_web_development/Core/Scripting/Loops", "Learn_web_development/Core/Scripting")}} In any programming language, the code needs to make decisions and carry out actions accordingly depending on different inputs. For example, in a game, if the player's number of lives is 0, then it's game over. In a weather app, if it is being looked at in the morning, show a sunrise graphic; show stars and a moon if it is nighttime. In this article, we'll explore how so-called conditional statements work in JavaScript. @@ -81,8 +81,8 @@ However, you need to be careful here — in this case, the second block of code As a final point, while not recommended, you may sometimes see `if...else` statements written without the curly braces: ```js example-bad -if (condition) /* code to run if condition is true */ -else /* run some other code instead */ +if (condition) doSomething(); +else doSomethingElse(); ``` This syntax is perfectly valid, but it is much easier to understand the code if you use the curly braces to delimit the blocks of code, and use multiple lines and indentation. @@ -93,12 +93,12 @@ To understand this syntax better, let's consider a real example. Imagine a child ```js let shoppingDone = false; -let childsAllowance; +let childAllowance; if (shoppingDone === true) { - childsAllowance = 10; + childAllowance = 10; } else { - childsAllowance = 5; + childAllowance = 5; } ``` @@ -187,13 +187,13 @@ And, returning to our previous example about the child doing a chore for their p ```js let shoppingDone = false; -let childsAllowance; +let childAllowance; // We don't need to explicitly specify 'shoppingDone === true' if (shoppingDone) { - childsAllowance = 10; + childAllowance = 10; } else { - childsAllowance = 5; + childAllowance = 5; } ``` @@ -872,7 +872,7 @@ function insertAtCaret(text) { ## Test your skills! -You've reached the end of this article, but can you remember the most important information? You can find some further tests to verify that you've retained this information before you move on — see [Test your skills: Conditionals](/en-US/docs/Learn_web_development/Core/Scripting/Test_your_skills:_Conditionals). +You've reached the end of this article, but can you remember the most important information? You can find some further tests to verify that you've retained this information before you move on — see [Test your skills: Conditionals](/en-US/docs/Learn_web_development/Core/Scripting/Test_your_skills/Conditionals). ## Summary diff --git a/files/en-us/learn_web_development/core/scripting/debugging_javascript/fetch-image.jpg b/files/en-us/learn_web_development/core/scripting/debugging_javascript/fetch-image.jpg deleted file mode 100644 index 184346dbf2c7e5a..000000000000000 Binary files a/files/en-us/learn_web_development/core/scripting/debugging_javascript/fetch-image.jpg and /dev/null differ diff --git a/files/en-us/learn_web_development/core/scripting/debugging_javascript/index.md b/files/en-us/learn_web_development/core/scripting/debugging_javascript/index.md index b127c397965531a..684556dbd9d9188 100644 --- a/files/en-us/learn_web_development/core/scripting/debugging_javascript/index.md +++ b/files/en-us/learn_web_development/core/scripting/debugging_javascript/index.md @@ -1,16 +1,13 @@ --- -title: Debugging JavaScript and handling errors +title: JavaScript debugging and error handling +short-title: Debugging and error handling slug: Learn_web_development/Core/Scripting/Debugging_JavaScript page-type: learn-module-chapter +sidebar: learnsidebar --- -{{LearnSidebar}} - {{PreviousMenuNext("Learn_web_development/Core/Scripting/JSON","Learn_web_development/Core/Frameworks_libraries", "Learn_web_development/Core/Scripting")}} -> [!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. - In this lesson, we will return to the subject of debugging JavaScript (which we first looked at in [What went wrong?](/en-US/docs/Learn_web_development/Core/Scripting/What_went_wrong)). Here we will delve deeper into techniques for tracking down errors, but also look at how to code defensively and handle errors in your code, avoiding problems in the first place. <table> @@ -25,8 +22,8 @@ In this lesson, we will return to the subject of debugging JavaScript (which we <ul> <li>Using browser developer tools to inspect the JavaScript running on your page and see what errors it is generating.</li> <li>Using <code>console.log()</code> and <code>console.error()</code> for debugging.</li> + <li>Advanced JavaScript debugging with browser devtools.</li> <li>Error handling with <code>conditionals</code>, <code>try...catch</code>, and <code>throw</code>.</li> - <li>Advanced JavaScript debugging with breakpoints, watchers, etc.</li> </ul> </td> </tr> @@ -53,7 +50,7 @@ There are a number of common JavaScript problems that you will want to be mindfu - Basic syntax and logic problems (again, check out [Troubleshooting JavaScript](/en-US/docs/Learn_web_development/Core/Scripting/What_went_wrong)). - Making sure variables, etc. are defined in the correct scope, and you are not running into conflicts between items declared in different places (see [Function scope and conflicts](/en-US/docs/Learn_web_development/Core/Scripting/Functions#function_scope_and_conflicts)). -- Confusion about [this](/en-US/docs/Web/JavaScript/Reference/Operators/this), in terms of what scope it applies to, and therefore if its value is what you intended. You can read [What is "this"?](/en-US/docs/Learn_web_development/Core/Scripting/Object_basics#what_is_this) for a light introduction; you should also study examples like [this one](https://github.com/mdn/learning-area/blob/7ed039d17e820c93cafaff541aa65d874dde8323/javascript/oojs/assessment/main.js#L143), which shows a typical pattern of saving a `this` scope to a separate variable, then using that variable in nested functions so you can be sure you are applying functionality to the correct `this` scope. +- Confusion about [`this`](/en-US/docs/Web/JavaScript/Reference/Operators/this), in terms of what scope it applies to, and therefore if its value is what you intended. You can read [What is "this"?](/en-US/docs/Learn_web_development/Core/Scripting/Object_basics#what_is_this) for a light introduction; you should also study examples like [this one](https://github.com/mdn/learning-area/blob/7ed039d17e820c93cafaff541aa65d874dde8323/javascript/oojs/assessment/main.js#L143), which shows a typical pattern of saving a `this` scope to a separate variable, then using that variable in nested functions so you can be sure you are applying functionality to the correct `this` scope. - Incorrectly using functions inside loops that iterate with a global variable (more generally "getting the scope wrong"). > [!CALLOUT] @@ -78,7 +75,7 @@ function showHeroes(jsonObj) { const heroes = jsonObj["members"]; for (const hero of heroes) { - // ... + // … } } ``` @@ -108,9 +105,8 @@ const requestURL = const response = fetch(requestURL); console.log(`Response value: ${response}`); -const superHeroes = response; -populateHeader(superHeroes); -showHeroes(superHeroes); +populateHeader(response); +showHeroes(response); ``` Refresh the page in the browser. This time, before the error message, you'll see a new message logged to the console: @@ -121,7 +117,34 @@ Response value: [object Promise] The `console.log()` output shows that the return value of `fetch()` is not the JSON data, it's a {{jsxref("Promise")}}. The `fetch()` function is asynchronous: it returns a `Promise` that is fulfilled only when the actual response has been received from the network. Before we can use the response, we have to wait for the `Promise` to be fulfilled. -We can do this by putting the code that uses the response inside the {{jsxref("Promise.prototype.then()", "then()")}} method of the returned `Promise`, like this: +### `console.error()` and call stacks + +As a brief digression, lets try using a different console method to report the error — {{domxref("console.error()")}}. In your code, replace + +```js +console.log(`Response value: ${response}`); +``` + +with + +```js +console.error(`Response value: ${response}`); +``` + +Save your code and refresh the browser and you'll now see the message reported as an error, with the same color and icon as the uncaught error below it. In addition, there will now be a expand/collapse arrow next to the message. If you press this, you'll see a single line telling you the line in the JavaScript file the error originated from. In fact, the uncaught error line _also_ has this, but it has two lines: + +```plain +showHeroes http://localhost:7800/js-debug-test/index.js:25 +<anonymous> http://localhost:7800/js-debug-test/index.js:10 +``` + +This means that the error is coming from the `showHeroes()` function, line 25, as we noted earlier. If you look at your code, you'll see that the anonymous call on line 10 is the line that is calling `showHeroes()`. These lines are referred to as a **call stack**, and can be really useful when trying to track down the source of an error involving lots of different locations in your code. + +The `console.error()` call isn't all that useful in this case, but it can be useful for generating a call stack if one is not already available. + +### Fixing the error + +Anyway, let's get back to trying to fix our error. We can access the response from the fulfilled `Promise` by chaining the {{jsxref("Promise.prototype.then()", "then()")}} method onto the end of the `fetch()` call. We can then pass the resulting response value into the functions that accept it, like this: ```js fetch(requestURL).then((response) => { @@ -130,11 +153,14 @@ fetch(requestURL).then((response) => { }); ``` -To summarize, anytime something is not working and a value does not appear to be what it is meant to be at some point in your code, you can use `console.log()` to print it out and see what is happening. +Save and refresh, and see if your code is working. Spoiler alert — the above change has not fixed the problem. Unfortunately, we **still have the same error**! + +> [!NOTE] +> To summarize, any time something is not working and a value does not appear to be what it is meant to be at some point in your code, you can use `console.log()`, `console.error()`, or another similar function to print out the value and see what is happening. ## Using the JavaScript debugger -Unfortunately, we still have the same error — the problem has not gone away. Let's investigate this now, using a more sophisticated feature of browser developer tools: the [JavaScript debugger](https://firefox-source-docs.mozilla.org/devtools-user/debugger/index.html) as it is called in Firefox. +Let's investigate this problem further using a more sophisticated feature of browser developer tools: the [JavaScript debugger](https://firefox-source-docs.mozilla.org/devtools-user/debugger/index.html) as it is called in Firefox. > [!NOTE] > Similar tools are available in other browsers; the [Sources tab](https://developer.chrome.com/docs/devtools/#sources) in Chrome, Debugger in Safari (see [Safari Web Development Tools](https://developer.apple.com/safari/tools/)), etc. @@ -149,15 +175,18 @@ In Firefox, the Debugger tab looks like this: The main feature of such tools is the ability to add breakpoints to code — these are points where the execution of the code stops, and at that point you can examine the environment in its current state and see what is going on. -Let's get to work. The error is now being thrown at line 26. Click on line number 26 in the center panel to add a breakpoint to it (you'll see a blue arrow appear over the top of it). Now refresh the page (Cmd/Ctrl + R) — the browser will pause execution of the code at line 26. At this point, the right-hand side will update to show some very useful information. +Let's explore using breakpoints: + +1. The error is being thrown at the same line as before — `for (const hero of heroes) {` — line 26 in the screenshot below. Click on this line in the center panel to add a breakpoint to it (you'll see a blue arrow appear over the top of it). +2. Now refresh the page (<kbd>Cmd</kbd>/<kbd>Ctrl</kbd> + <kbd>R</kbd>) — the browser will pause execution of the code on that line. At this point, the right-hand side will update to show the following: ![Firefox debugger with a breakpoint](breakpoint.png) -- Under _Breakpoints_, you'll see the details of the break-point you have set. -- Under _Call Stack_, you'll see a few entries — this is basically a list of the series of functions that were invoked to cause the current function to be invoked. At the top, we have `showHeroes()` the function we are currently in, and second we have `onload`, which stores the event handler function containing the call to `showHeroes()`. +- Under _Breakpoints_, you'll see the details of the breakpoint you have set. +- Under _Call Stack_, you'll see a few entries — this is basically the same as the callstack we looked at earlier in the `console.error()` section. _Call Stack_ shows a list of the functions that were invoked to cause the current function to be invoked. At the top, we have `showHeroes()`, the function we are currently in, and second we have `onload`, which stores the event handler function containing the call to `showHeroes()`. - Under _Scopes_, you'll see the currently active scope for the function we are looking at. We only have three — `showHeroes`, `block`, and `Window` (the global scope). Each scope can be expanded to show the values of variables inside the scope when execution of the code was stopped. -We can find out some very useful information in here. +We can find out some very useful information in here: 1. Expand the `showHeroes` scope — you can see from this that the heroes variable is `undefined`, indicating that accessing the `members` property of `jsonObj` (first line of the function) didn't work. 2. You can also see that the `jsonObj` variable is storing a {{domxref("Response")}} object, not a JSON object. @@ -171,25 +200,141 @@ We'd like you to try fixing this problem yourself. To get you started, see the d ## Handling JavaScript errors in your code -HTML and CSS are permissive — errors and unrecognized features can often be handled due to the nature of the languages. For example, CSS will ignore unrecognized properties, and the rest of the code will often just work. JavaScript is not as permissive as HTML and CSS however — if the JavaScript engine encounters mistakes or unrecognized syntax, more often than not it will throw errors. - -There are a few strategies for handling JavaScript errors in your code; let's explore the most common ones. +HTML and CSS are permissive — errors and unrecognized features can often be handled due to the nature of the languages. For example, CSS will ignore unrecognized properties, and the rest of the code will often just work. JavaScript is not as permissive as HTML and CSS however — if the JavaScript engine encounters mistakes or unrecognized syntax, it will often throw errors. + +Let's explore a common strategy for handling JavaScript errors in your code. The following sections are designed to be followed by making a copy of the below template file as `handling-errors.html` on your local machine, adding the code snippets in between the opening and closing `<script>` and `</script>` tags, then opening the file in a browser and looking at the output in the devtools JavaScript console. + +```html-nolint +<!DOCTYPE html> +<html lang="en-US"> + <head> + <meta charset="utf-8" /> + <meta name="viewport" content="width=device-width" /> + <title>Handling JS errors</title> + </head> + <body> + <script> + // Code goes below this line + + </script> + </body> +</html> +``` ### Conditionals -TODO +A common use of [JavaScript conditionals](/en-US/docs/Learn_web_development/Core/Scripting/Conditionals) is to handle errors. Conditionals allow you to run different code depending on the value of a variable. Often you will want to use this defensively, to avoid throwing an error if the value does not exist or is of the wrong type, or to capture an error if the value would cause an incorrect result to be returned, which could cause problems later on. + +Let's look at an example. Say we have a function that takes as an argument equal to the user's height in inches and returns their height in meters, to 2 decimal places. This could look like so: + +```js +function inchesToMeters(num) { + const mVal = (num * 2.54) / 100; + const m2dp = mVal.toFixed(2); + return m2dp; +} +``` + +1. In your example file's `<script>` element, declare a `const` called `height` and assign it a value of `70`: + + ```js + const height = 70; + ``` + +2. Copy the above function below the previous line. + +3. Call the function, passing it the `height` constant as its argument, and log the return value to the console: + + ```js + console.log(inchesToMeters(height)); + ``` + +4. Load the example in a browser and look at the devtools JavaScript console. You should see a value of `1.78` logged to it. + +5. So this works fine in isolation. But what happens if the provided data is missing or not correct? Try out these scenarios: + + - If you change the `height` value to `"70"` (that is, `70` expressed as a string), the example should ... still work fine. This is because the calculation on the first line of the string coerces the value into a number data type. This is OK in a simple case like this, but in more complex code the wrong data can lead to all kind of bugs, some of them subtle and hard to detect! + - If you change `height` to a value that can't be coerced to a number, like `"70 inches"` or `["Bob", 70]`, or {{jsxref("NaN")}}, the example should return the result as `NaN`. This could cause all kind of problems, for example if you want to include the user's height somewhere in the website user interface. + - If you remove the `height` value altogether (comment it out by adding `//` at the start of the line), the console will show an error along the lines of "Uncaught ReferenceError: height is not defined", the likes of which could bring your application grinding to a halt. + + Obviously, none of these outcomes are great. How do we defend against bad data? + +6. Let's add a conditional inside our function to test whether the data is good before we try to do the calculation. Try replacing your current function with the following: + + ```js + function inchesToMeters(num) { + if (typeof num === "number" && !isNaN(num)) { + const mVal = (num * 2.54) / 100; + const m2dp = mVal.toFixed(2); + return m2dp; + } else { + console.log("A number was not provided. Please correct the input."); + } + } + ``` + +7. Now if you try the first two scenarios again, you'll see our slightly more useful message returned, to give you an idea of what needs to be done to fix the problem. You could put anything in there that you like, including trying to run code to correct the value of `num`, but this is not advised — this function has one simple purpose, and you should handle correcting the value somewhere else in the system. + + > [!NOTE] + > In the `if()` statement, we first test whether the data type of `num` is `"number"` using the [`typeof`](/en-US/docs/Web/JavaScript/Reference/Operators/typeof) operator, but we also test whether {{jsxref("isNaN()", "!isNaN(num)")}} returns `false`. We have to do this to defend against the specific case of `num` being set to `NaN`, as weirdly, `typeof NaN` returns `"number"`! + +8. However, if you try the third scenario again, you will still get the "Uncaught ReferenceError: height is not defined" error thrown at you. You can't fix the fact that a value is not available from inside a function that is trying to use the value. + +How do we handle this? Well, it's probably better to get our function to return a custom error when it doesn't receive the correct data. We'll look at how to do that first, then we'll handle all the errors together. + +### Throwing custom errors + +You can throw a custom error at any point in your code using the [`throw`](/en-US/docs/Web/JavaScript/Reference/Statements/throw) statement, coupled with the {{jsxref("Error.Error", "Error()")}} constructor. Let's see this in action. + +1. In your function, replace the `console.log()` line inside the `else` block of your function with the following line: + + ```js + throw new Error("A number was not provided. Please correct the input."); + ``` + +2. Run your example again, but make sure `num` is set to a bad (that is, non-number) value. This time, you should see your custom error thrown, along with a useful call stack to help you locate the source of the error (although note that the message still tells us that the error is "uncaught", or "unhandled"). OK, so errors are annoying, but this is way more useful than running the function successfully and returning a non-number value that could cause problems later on. + +So, how do we handle all those errors then? ### try...catch -TODO +The [`try...catch`](/en-US/docs/Web/JavaScript/Reference/Statements/try...catch) statement is specially designed to handle errors. It has the following structure: + +```js +try { + // Run some code +} catch (error) { + // Handle any errors +} +``` + +Inside the `try` block, you try running some code. If this code runs without an error being thrown, all is well, and the `catch` block is ignored. However, if an error is thrown the `catch` block is run, which provides access to the {{jsxref("Error")}} object representing the error, and allows you to run code to handle it. + +Let's use `try...catch` in our code. + +1. Replace the `console.log()` line that calls the `inchesToMeters()` function at the end of your script with the following block. We are now running our `console.log()` line inside a `try` block, and handling any errors that it returns inside a corresponding `catch` block. -### Throwing errors + ```js + try { + console.log(inchesToMeters(height)); + } catch (error) { + console.error(error); + console.log("Insert code to handle the error"); + } + ``` -TODO +2. Save and refresh, and you should now see two things: + + - The error message and call stack as before, but this time, without a label of "uncaught", or "unhandled". + - The logged message "Insert code to handle the error". + +3. Now try updating `num` to a good (number) value, and you'll see the result of the calculation logged, with no error message. + +This is significant — any thrown errors are no longer unhandled, so they won't bring the application crashing to a halt. You can run whatever code you like to handle the error. Above we are just logging a message, but for example you could call whatever function was run earlier to ask the user to enter their height, this time asking them to correct the input error. You could even use an `if...else` statement to run different error handling code depending on what type of error is returned. ### Feature detection -Feature detection is useful when you are planning to use new JavaScript features that might not be supported in all browsers. Test for the feature, and then conditionally run code to provide an acceptable experience both in browsers that do and don't support the feature. As a quick example, the [Geolocation API](/en-US/docs/Web/API/Geolocation_API) (which exposes available location data for the device the web browser is running on) has a main entry point for its use — a `geolocation` property available on the global [Navigator](/en-US/docs/Web/API/Navigator) object. Therefore, you can detect whether the browser supports geolocation or not by using something like the following: +Feature detection is useful when you are planning to use new JavaScript features that might not be supported in all browsers. Test for the feature, and then conditionally run code to provide an acceptable experience both in browsers that do and don't support the feature. As a quick example, the [Geolocation API](/en-US/docs/Web/API/Geolocation_API) (which exposes available location data for the device the web browser is running on) has a main entry point for its use — a `geolocation` property available on the global [Navigator](/en-US/docs/Web/API/Navigator) object. Therefore, you can detect whether the browser supports geolocation or not by using a similar `if()` structure to what we saw earlier: ```js if ("geolocation" in navigator) { @@ -201,6 +346,8 @@ if ("geolocation" in navigator) { } ``` +You can find some more feature detection examples in [Alternatives to UA sniffing](/en-US/docs/Web/HTTP/Guides/Browser_detection_using_the_user_agent#alternatives_to_ua_sniffing). + ## Finding help There are many other issues you'll encounter with JavaScript (and HTML and CSS!), making knowledge of how to find answers online invaluable. diff --git a/files/en-us/learn_web_development/core/scripting/debugging_javascript/js-hint-commandline.png b/files/en-us/learn_web_development/core/scripting/debugging_javascript/js-hint-commandline.png deleted file mode 100644 index 21ddfa18014ebdf..000000000000000 Binary files a/files/en-us/learn_web_development/core/scripting/debugging_javascript/js-hint-commandline.png and /dev/null differ diff --git a/files/en-us/learn_web_development/core/scripting/debugging_javascript/jshint-online.png b/files/en-us/learn_web_development/core/scripting/debugging_javascript/jshint-online.png deleted file mode 100644 index 188f93eebf4364f..000000000000000 Binary files a/files/en-us/learn_web_development/core/scripting/debugging_javascript/jshint-online.png and /dev/null differ diff --git a/files/en-us/learn_web_development/core/scripting/dom_scripting/index.md b/files/en-us/learn_web_development/core/scripting/dom_scripting/index.md index bbd34c156e47970..c7787075349c656 100644 --- a/files/en-us/learn_web_development/core/scripting/dom_scripting/index.md +++ b/files/en-us/learn_web_development/core/scripting/dom_scripting/index.md @@ -1,11 +1,11 @@ --- title: DOM scripting introduction +short-title: DOM scripting slug: Learn_web_development/Core/Scripting/DOM_scripting page-type: learn-module-chapter +sidebar: learnsidebar --- -{{LearnSidebar}} - {{PreviousMenuNext("Learn_web_development/Core/Scripting/Object_basics","Learn_web_development/Core/Scripting/Network_requests", "Learn_web_development/Core/Scripting")}} When writing web pages and apps, one of the most common things you'll want to do is change the document structure in some way. This is usually done by manipulating the Document Object Model (DOM) via a set of built-in browser APIs for controlling HTML and styling information. In this article we'll introduce you to **DOM scripting**. @@ -40,7 +40,7 @@ Despite the limitations, Web APIs still give us access to a lot of functionality ![Important parts of web browser; the document is the web page. The window includes the entire document and also the tab. The navigator is the browser, which includes the window (which includes the document) and all other windows.](document-window-navigator.png) - The window is the browser tab that a web page is loaded into; this is represented in JavaScript by the {{domxref("Window")}} object. Using methods available on this object you can do things like return the window's size (see {{domxref("Window.innerWidth")}} and {{domxref("Window.innerHeight")}}), manipulate the document loaded into that window, store data specific to that document on the client-side (for example using a local database or other storage mechanism), attach an [event handler](/en-US/docs/Learn_web_development/Core/Scripting/Events) to the current window, and more. -- The navigator represents the state and identity of the browser (i.e. the user-agent) as it exists on the web. In JavaScript, this is represented by the {{domxref("Navigator")}} object. You can use this object to retrieve things like the user's preferred language, a media stream from the user's webcam, etc. +- The navigator represents the state and identity of the browser (i.e., the user-agent) as it exists on the web. In JavaScript, this is represented by the {{domxref("Navigator")}} object. You can use this object to retrieve things like the user's preferred language, a media stream from the user's webcam, etc. - The document (represented by the DOM in browsers) is the actual page loaded into the window, and is represented in JavaScript by the {{domxref("Document")}} object. You can use this object to return and manipulate information on the HTML and CSS that comprises the document, for example get a reference to an element in the DOM, change its text content, apply new styles to it, create new elements and add them to the current element as children, or even delete it altogether. In this article we'll focus mostly on manipulating the document, but we'll show a few other useful bits besides. @@ -49,6 +49,9 @@ In this article we'll focus mostly on manipulating the document, but we'll show Let's provide a brief recap on the Document Object Model (DOM), which we also looked at earlier in the course. The document currently loaded in each one of your browser tabs is represented by a DOM. This is a "tree structure" representation created by the browser that enables the HTML structure to be easily accessed by programming languages — for example the browser itself uses it to apply styling and other information to the correct elements as it renders a page, and developers like you can manipulate the DOM with JavaScript after the page has been rendered. +> [!NOTE] +> Scrimba's [The Document Object Model](https://scrimba.com/learn-javascript-c0v/~0g?via=mdn) <sup>[_MDN learning partner_](/en-US/docs/MDN/Writing_guidelines/Learning_content#partner_links_and_embeds)</sup> provides a handy walkthrough of the "DOM" term and what it means. + We have created an example page at [dom-example.html](https://github.com/mdn/learning-area/blob/main/javascript/apis/document-manipulation/dom-example.html) ([see it live also](https://mdn.github.io/learning-area/javascript/apis/document-manipulation/dom-example.html)). Try opening this up in your browser — it is a very simple page containing a {{htmlelement("section")}} element inside which you can find an image, and a paragraph with a link inside. The HTML source code looks like this: ```html @@ -89,7 +92,7 @@ Nodes are also referred to by their position in the tree relative to other nodes - **Parent node**: A node which has another node inside it. For example, `BODY` is the parent node of `SECTION` in the above example. - **Sibling nodes**: Nodes that sit on the same level under the same parent node in the DOM tree. For example, `IMG` and `P` are siblings in the above example. -It is useful to familiarize yourself with this terminology before working with the DOM, as a number of the code terms you'll come across make use of them. You'll also come across them in CSS (e.g. descendant selector, child selector). +It is useful to familiarize yourself with this terminology before working with the DOM, as a number of the code terms you'll come across make use of them. You'll also come across them in CSS (e.g., descendant selector, child selector). ## Active learning: Basic DOM manipulation @@ -119,8 +122,8 @@ Note that, as with many things in JavaScript, there are many ways to select an e There are older methods available for grabbing element references, such as: -- {{domxref("Document.getElementById()")}}, which selects an element with a given `id` attribute value, e.g. `<p id="myId">My paragraph</p>`. The ID is passed to the function as a parameter, i.e. `const elementRef = document.getElementById('myId')`. -- {{domxref("Document.getElementsByTagName()")}}, which returns an array-like object containing all the elements on the page of a given type, for example `<p>`s, `<a>`s, etc. The element type is passed to the function as a parameter, i.e. `const elementRefArray = document.getElementsByTagName('p')`. +- {{domxref("Document.getElementById()")}}, which selects an element with a given `id` attribute value, e.g., `<p id="myId">My paragraph</p>`. The ID is passed to the function as a parameter, i.e., `const elementRef = document.getElementById('myId')`. +- {{domxref("Document.getElementsByTagName()")}}, which returns an array-like object containing all the elements on the page of a given type, for example `<p>`s, `<a>`s, etc. The element type is passed to the function as a parameter, i.e., `const elementRefArray = document.getElementsByTagName('p')`. These two work better in older browsers than the modern methods like `querySelector()`, but are not as convenient. Have a look and see what others you can find! @@ -200,7 +203,7 @@ Have a go at adding the above lines to your code. It is possible to manipulate CSS styles via JavaScript in a variety of ways. -To start with, you can get a list of all the stylesheets attached to a document using {{domxref("Document.stylesheets")}}, which returns an array-like object with {{domxref("CSSStyleSheet")}} objects. You can then add/remove styles as wished. However, we're not going to expand on those features because they are a somewhat archaic and difficult way to manipulate style. There are much easier ways. +To start with, you can get a list of all the stylesheets attached to a document using {{domxref("Document.styleSheets")}}, which returns an array-like object with {{domxref("CSSStyleSheet")}} objects. You can then add/remove styles as wished. However, we're not going to expand on those features because they are a somewhat archaic and difficult way to manipulate style. There are much easier ways. The first way is to add inline styles directly onto elements you want to dynamically style. This is done with the {{domxref("HTMLElement.style")}} property, which contains inline styling information for each element in the document. You can set properties of this object to directly update element styles. @@ -224,7 +227,7 @@ The first way is to add inline styles directly onto elements you want to dynamic ``` > [!NOTE] -> Notice how the JavaScript property versions of the CSS styles are written in {{Glossary("camel_case", "lower camel case")}} whereas the CSS versions are hyphenated ({{Glossary("kebab_case", "kebab-case")}}) (e.g. `backgroundColor` versus `background-color`). Make sure you don't get these mixed up, otherwise it won't work. +> Notice how the JavaScript property versions of the CSS styles are written in {{Glossary("camel_case", "lower camel case")}} whereas the CSS versions are hyphenated ({{Glossary("kebab_case", "kebab-case")}}) (e.g., `backgroundColor` versus `background-color`). Make sure you don't get these mixed up, otherwise it won't work. There is another common way to dynamically manipulate styles on your document, which we'll look at now. diff --git a/files/en-us/learn_web_development/core/scripting/event_bubbling/index.md b/files/en-us/learn_web_development/core/scripting/event_bubbling/index.md index 5e4a02b686dc9f1..7738e88d82b2ee7 100644 --- a/files/en-us/learn_web_development/core/scripting/event_bubbling/index.md +++ b/files/en-us/learn_web_development/core/scripting/event_bubbling/index.md @@ -2,10 +2,9 @@ title: Event bubbling slug: Learn_web_development/Core/Scripting/Event_bubbling page-type: learn-module-chapter +sidebar: learnsidebar --- -{{LearnSidebar}} - {{PreviousMenuNext("Learn_web_development/Core/Scripting/Events","Learn_web_development/Core/Scripting/Image_gallery", "Learn_web_development/Core/Scripting")}} We've seen that a web page is composed of _elements_ — headings, paragraphs of text, images, buttons, and so on — and that you can listen for events that happen to these elements. For example, you could add a listener to a button, and it will run when the user clicks the button. @@ -134,9 +133,7 @@ The HTML looks like this: <div class="hidden"> <video> - <source - src="https://interactive-examples.mdn.mozilla.net/media/cc0-videos/flower.webm" - type="video/webm" /> + <source src="/shared-assets/videos/flower.webm" type="video/webm" /> <p> Your browser doesn't support HTML video. Here is a <a href="rabbit320.mp4">link to the video</a> instead. @@ -229,9 +226,7 @@ All we're doing here is calling `stopPropagation()` on the event object in the h <div class="hidden"> <video> - <source - src="https://interactive-examples.mdn.mozilla.net/media/cc0-videos/flower.webm" - type="video/webm" /> + <source src="/shared-assets/videos/flower.webm" type="video/webm" /> <p> Your browser doesn't support HTML video. Here is a <a href="rabbit320.mp4">link to the video</a> instead. @@ -417,7 +412,7 @@ The `target` property is commonly used in event delegation, as in our [Event del ## Test your skills! -You've reached the end of this article, but can you remember the most important information? To verify you've retained this information before you move on — see [Test your skills: Events](/en-US/docs/Learn_web_development/Core/Scripting/Building_blocks/Test_your_skills:_Events). +You've reached the end of this article, but can you remember the most important information? To verify you've retained this information before you move on — see [Test your skills: Events](/en-US/docs/Learn_web_development/Core/Scripting/Test_your_skills/Events). ## Summary diff --git a/files/en-us/learn_web_development/core/scripting/events/index.md b/files/en-us/learn_web_development/core/scripting/events/index.md index 00de0f10cb3434c..fa2eaee9f70c302 100644 --- a/files/en-us/learn_web_development/core/scripting/events/index.md +++ b/files/en-us/learn_web_development/core/scripting/events/index.md @@ -1,11 +1,11 @@ --- title: Introduction to events +short-title: Events slug: Learn_web_development/Core/Scripting/Events page-type: learn-module-chapter +sidebar: learnsidebar --- -{{LearnSidebar}} - {{PreviousMenuNext("Learn_web_development/Core/Scripting/Return_values","Learn_web_development/Core/Scripting/Event_bubbling", "Learn_web_development/Core/Scripting")}} Events are things that happen in the system you are programming, which the system tells you about so your code can react to them. @@ -113,7 +113,7 @@ btn.addEventListener("click", () => { The HTML {{HTMLElement("button")}} element will fire an event when the user clicks the button. So it defines an `addEventListener()` function, which we are calling here. We're passing in two parameters: - the string `"click"`, to indicate that we want to listen to the click event. Buttons can fire lots of other events, such as [`"mouseover"`](/en-US/docs/Web/API/Element/mouseover_event) when the user moves their mouse over the button, or [`"keydown"`](/en-US/docs/Web/API/Element/keydown_event) when the user presses a key and the button is focused. -- a function to call when the event happens. In our case, the function generates a random RGB color and sets the [`background-color`](/en-US/docs/Web/CSS/background-color) of the page [`<body>`](/en-US/docs/Web/HTML/Element/body) to that color. +- a function to call when the event happens. In our case, the function generates a random RGB color and sets the [`background-color`](/en-US/docs/Web/CSS/background-color) of the page [`<body>`](/en-US/docs/Web/HTML/Reference/Elements/body) to that color. It is fine to make the handler function a separate named function, like this: @@ -259,7 +259,7 @@ function bgChange() { } ``` -The earliest method of registering event handlers found on the Web involved [_event handler HTML attributes_](/en-US/docs/Web/HTML/Attributes#event_handler_attributes) (or _inline event handlers_) like the one shown above — the attribute value is literally the JavaScript code you want to run when the event occurs. +The earliest method of registering event handlers found on the Web involved [_event handler HTML attributes_](/en-US/docs/Web/HTML/Reference/Attributes#event_handler_attributes) (or _inline event handlers_) like the one shown above — the attribute value is literally the JavaScript code you want to run when the event occurs. The above example invokes a function defined inside a {{htmlelement("script")}} element on the same page, but you could also insert JavaScript directly inside the attribute, for example: ```html 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 71238b33f40208e..83e19d6de2e5aee 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 @@ -1,11 +1,11 @@ --- title: Functions — reusable blocks of code +short-title: Functions slug: Learn_web_development/Core/Scripting/Functions page-type: learn-module-chapter +sidebar: learnsidebar --- -{{LearnSidebar}} - {{PreviousMenuNext("Learn_web_development/Core/Scripting/Loops","Learn_web_development/Core/Scripting/Build_your_own_function", "Learn_web_development/Core/Scripting")}} Another essential concept in coding is **functions**, which allow you to store a piece of code that does a single task inside a defined block, and then call that code whenever you need it using a single short command — rather than having to type out the same code multiple times. In this article we'll explore fundamental concepts behind functions such as basic syntax, how to invoke and define them, scope, and parameters. @@ -87,7 +87,7 @@ Bear in mind that some built-in browser functions are not part of the core JavaS **Functions** that are part of objects are called **methods**; you'll learn about objects later in the module. For now, we just wanted to clear up any possible confusion about method versus function — you are likely to meet both terms as you look at the available related resources across the Web. -The built-in code we've made use of so far comes in both forms: **functions** and **methods.** You can check the full list of the built-in functions, as well as the built-in objects and their corresponding methods [here](/en-US/docs/Web/JavaScript/Reference/Global_Objects). +The built-in code we've made use of so far comes in both forms: **functions** and **methods.** You can check the full list of the built-in functions, as well as the built-in objects and their corresponding methods [in our JavaScript reference](/en-US/docs/Web/JavaScript/Reference/Global_Objects). You've also seen a lot of **custom functions** in the course so far — functions defined in your code, not inside the browser. Anytime you saw a custom name with parentheses straight after it, you were using a custom function. In our [random-canvas-circles.html](https://mdn.github.io/learning-area/javascript/building-blocks/loops/random-canvas-circles.html) example (see also the full [source code](https://github.com/mdn/learning-area/blob/main/javascript/building-blocks/loops/random-canvas-circles.html)) from our [loops article](/en-US/docs/Learn_web_development/Core/Scripting/Loops), we included a custom `draw()` function that looked like this: @@ -464,14 +464,14 @@ Let's look at a real example to demonstrate scoping. This time the `a()` and `b()` calls will throw that annoying [ReferenceError: _variable name_ is not defined](/en-US/docs/Web/JavaScript/Reference/Errors/Not_defined) error into the console — this is because the `output()` calls and the variables they are trying to print are not in the same function scopes — the variables are effectively invisible to those function calls. > [!NOTE] -> The same scoping rules do not apply to loop (e.g. `for() { }`) and conditional blocks (e.g. `if () { }`) — they look very similar, but they are not the same thing! Take care not to get these confused. +> The same scoping rules do not apply to loop (e.g., `for() { }`) and conditional blocks (e.g., `if () { }`) — they look very similar, but they are not the same thing! Take care not to get these confused. > [!NOTE] > The [ReferenceError: "x" is not defined](/en-US/docs/Web/JavaScript/Reference/Errors/Not_defined) error is one of the most common you'll encounter. If you get this error and you are sure that you have defined the variable in question, check what scope it is in. ## Test your skills! -You've reached the end of this article, but can you remember the most important information? You can find some further tests to verify that you've retained this information before you move on — see [Test your skills: Functions](/en-US/docs/Learn_web_development/Core/Scripting/Test_your_skills:_Functions). These tests require skills that are covered in the next two articles, so you might want to read those first before trying them. +You've reached the end of this article, but can you remember the most important information? You can find some further tests to verify that you've retained this information before you move on — see [Test your skills: Functions](/en-US/docs/Learn_web_development/Core/Scripting/Test_your_skills/Functions). These tests require skills that are covered in the next two articles, so you might want to read those first before trying them. ## Summary @@ -481,7 +481,6 @@ This article has explored the fundamental concepts behind functions, paving the - [Functions detailed guide](/en-US/docs/Web/JavaScript/Guide/Functions) — covers some advanced features not included here. - [Functions reference](/en-US/docs/Web/JavaScript/Reference/Functions) -- [Using functions to write less code](https://v2.scrimba.com/the-frontend-developer-career-path-c0j/~04g?via=mdn), Scrimba <sup>_MDN learning partner_</sup> - - : An interactive lesson providing a useful functions introduction. +- [Using functions to write less code](https://scrimba.com/the-frontend-developer-career-path-c0j/~04g?via=mdn), Scrimba <sup>[_MDN learning partner_](/en-US/docs/MDN/Writing_guidelines/Learning_content#partner_links_and_embeds)</sup> - An interactive lesson providing a useful functions introduction. {{PreviousMenuNext("Learn_web_development/Core/Scripting/Loops","Learn_web_development/Core/Scripting/Build_your_own_function", "Learn_web_development/Core/Scripting")}} diff --git a/files/en-us/learn_web_development/core/scripting/image_gallery/index.md b/files/en-us/learn_web_development/core/scripting/image_gallery/index.md index 490ccfca67f65d3..24285c75a69e66d 100644 --- a/files/en-us/learn_web_development/core/scripting/image_gallery/index.md +++ b/files/en-us/learn_web_development/core/scripting/image_gallery/index.md @@ -2,10 +2,9 @@ title: "Challenge: Image gallery" slug: Learn_web_development/Core/Scripting/Image_gallery page-type: learn-module-assessment +sidebar: learnsidebar --- -{{LearnSidebar}} - {{PreviousMenuNext("Learn_web_development/Core/Scripting/Event_bubbling","Learn_web_development/Core/Scripting/Object_basics", "Learn_web_development/Core/Scripting")}} Now that we've looked at the fundamental building blocks of JavaScript, we'll test your knowledge of loops, functions, conditionals and events by getting you to build a fairly common item you'll see on a lot of websites — a JavaScript-powered image gallery. 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 c71bd44da7f0d1f..0178404ecb1f858 100644 --- a/files/en-us/learn_web_development/core/scripting/index.md +++ b/files/en-us/learn_web_development/core/scripting/index.md @@ -1,11 +1,11 @@ --- title: Dynamic scripting with JavaScript +short-title: JavaScript slug: Learn_web_development/Core/Scripting page-type: learn-module +sidebar: learnsidebar --- -{{LearnSidebar}} - {{NextMenu("Learn_web_development/Core/Scripting/What_is_JavaScript", "Learn_web_development/Core")}} JavaScript is a huge topic, with so many different features, styles, and techniques to learn, and so many APIs and tools built on top of it. This module focuses mostly on the essentials of the core language, plus some key surrounding topics — learning these topics will give you a solid basis to work from. @@ -60,16 +60,16 @@ Before starting this module, you don't need any previous JavaScript knowledge, b - [Making network requests with JavaScript](/en-US/docs/Learn_web_development/Core/Scripting/Network_requests) - : Another very common task in modern websites and applications is making network requests to retrieve individual data items from the server to update sections of a webpage without having to load an entire new page. This seemingly small detail has had a huge impact on the performance and behavior of sites, so in this article, we'll explain the concept and look at technologies that make it possible. - [Working with JSON](/en-US/docs/Learn_web_development/Core/Scripting/JSON) - - : JavaScript Object Notation (JSON) is a standard text-based format for representing structured data based on JavaScript object syntax. It is commonly used for transmitting data in web applications (e.g., sending some data from the server to the client, so it can be displayed on a web page, or vice versa). You'll come across it quite often, so in this article, we give you all you need to work with JSON using JavaScript, including parsing JSON so you can access data within it, and creating JSON. - -- [Debugging JavaScript and handling errors](/en-US/docs/Learn_web_development/Core/Scripting/Debugging_JavaScript) +- [JavaScript debugging and error handling](/en-US/docs/Learn_web_development/Core/Scripting/Debugging_JavaScript) - : In this lesson, we will return to the subject of debugging JavaScript (which we first looked at in [What went wrong?](/en-US/docs/Learn_web_development/Core/Scripting/What_went_wrong)). Here we will delve deeper into techniques for tracking down errors, but also look at how to code defensively and handle errors in your code, avoiding problems in the first place. +- [Test your skills: JavaScript](/en-US/docs/Learn_web_development/Core/Scripting/Test_your_skills) + - : This page lists JavaScript tests you can try so you can verify if you've understood the content in this module. ## See also -- [Scrimba: Learn JavaScript](https://v2.scrimba.com/learn-javascript-c0v?via=mdn) <sup>_MDN learning partner_</sup> - - : [Scrimba's](https://scrimba.com?via=mdn) _Learn JavaScript_ course teaches you JavaScript through solving 140+ interactive coding challenges, building projects including a game, a browser extension, and even a mobile app. Scrimba features fun interactive lessons taught by knowledgeable teachers. +- [Scrimba: Learn JavaScript](https://scrimba.com/learn-javascript-c0v?via=mdn) <sup>[_MDN learning partner_](/en-US/docs/MDN/Writing_guidelines/Learning_content#partner_links_and_embeds)</sup> + - : [Scrimba's](https://scrimba.com/?via=mdn) _Learn JavaScript_ course teaches you JavaScript through solving 140+ interactive coding challenges, building projects including a game, a browser extension, and even a mobile app. Scrimba features fun interactive lessons taught by knowledgeable teachers. - [Learn JavaScript](https://learnjavascript.online/) - : An excellent resource for aspiring web developers — Learn JavaScript in an interactive environment, with short lessons and interactive tests, guided by automated assessment. The first 40 lessons are free, and the complete course is available for a small one-time payment. diff --git a/files/en-us/learn_web_development/core/scripting/json/index.md b/files/en-us/learn_web_development/core/scripting/json/index.md index 14f26b59d2f7b6f..fddebc181bd6cf5 100644 --- a/files/en-us/learn_web_development/core/scripting/json/index.md +++ b/files/en-us/learn_web_development/core/scripting/json/index.md @@ -1,11 +1,11 @@ --- title: Working with JSON +short-title: JSON slug: Learn_web_development/Core/Scripting/JSON page-type: learn-module-chapter +sidebar: learnsidebar --- -{{LearnSidebar}} - {{PreviousMenuNext("Learn_web_development/Core/Scripting/Network_requests","Learn_web_development/Core/Scripting/Debugging_JavaScript", "Learn_web_development/Core/Scripting")}} JavaScript Object Notation (JSON) is a standard text-based format for representing structured data based on JavaScript object syntax. It is commonly used for transmitting data in web applications (e.g., sending some data from the server to the client, so it can be displayed on a web page, or vice versa). You'll come across it quite often, so in this article, we give you all you need to work with JSON using JavaScript, including parsing JSON so you can access data within it, and creating JSON. @@ -33,12 +33,10 @@ JavaScript Object Notation (JSON) is a standard text-based format for representi ## No, really, what is JSON? -{{glossary("JSON")}} is a text-based data format following JavaScript object syntax, which was popularized by [Douglas Crockford](https://en.wikipedia.org/wiki/Douglas_Crockford). -Even though it closely resembles JavaScript object literal syntax, it can be used independently from JavaScript, and many programming environments feature the ability to read (parse) and generate JSON. - -JSON exists as a string — useful when you want to transmit data across a network. -It needs to be converted to a native JavaScript object when you want to access the data. -This is not a big issue — JavaScript provides a global [JSON](/en-US/docs/Web/JavaScript/Reference/Global_Objects/JSON) object that has methods available for converting between the two. +{{glossary("JSON")}} is a text-based data format following JavaScript object syntax. +It represents structured data as a string, which is useful when you want to transmit data across a network. +Even though it closely resembles JavaScript object literal syntax, it can be used independently from JavaScript. Many programming environments feature the ability to read (parse) and generate JSON. +In JavaScript, the methods for parsing and generating JSON are provided by the [`JSON`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/JSON) object. > [!NOTE] > Converting a string to a native object is called _deserialization_, while converting a native object to a string so it can be transmitted across the network is called _serialization_. @@ -48,8 +46,8 @@ A JSON string can be stored in its own file, which is basically just a text file ### JSON structure As described above, JSON is a string whose format very much resembles JavaScript object literal format. -You can include the same basic data types inside JSON as you can in a standard JavaScript object — strings, numbers, arrays, booleans, and other object literals. -This allows you to construct a data hierarchy, like so: +The following is a valid JSON string representing an object. +Note how it is also a valid JavaScript object literal — just with some more [syntax restrictions](#json_syntax_restrictions). ```json { @@ -91,26 +89,22 @@ This allows you to construct a data hierarchy, like so: } ``` -If we loaded this string into a JavaScript program and parsed it into a variable called `superHeroes` for example, we could then access the data inside it using the same dot/bracket notation we looked at in the [JavaScript object basics](/en-US/docs/Learn_web_development/Core/Scripting/Object_basics) article. +If you load this JSON in your JavaScript program as a string, you can parse it into a normal object and then access the data inside it using the same dot/bracket notation we looked at in the [JavaScript object basics](/en-US/docs/Learn_web_development/Core/Scripting/Object_basics) article. For example: ```js superHeroes.homeTown; -superHeroes["active"]; -``` - -To access data further down the hierarchy, you have to chain the required property names and array indexes together. For example, to access the third superpower of the second hero listed in the members list, you'd do this: - -```js -superHeroes["members"][1]["powers"][2]; +superHeroes.members[1].powers[2]; ``` 1. First, we have the variable name — `superHeroes`. -2. Inside that, we want to access the `members` property, so we use `["members"]`. +2. Inside that, we want to access the `members` property, so we use `.members`. 3. `members` contains an array populated by objects. We want to access the second object inside the array, so we use `[1]`. -4. Inside this object, we want to access the `powers` property, so we use `["powers"]`. +4. Inside this object, we want to access the `powers` property, so we use `.powers`. 5. Inside the `powers` property is an array containing the selected hero's superpowers. We want the third one, so we use `[2]`. +The key takeaway is that there's really nothing special about working with JSON; after you've parsed it into a JavaScript object, you work with it just like you would with an object declared using the same object literal syntax. + > [!NOTE] > We've made the JSON seen above available inside a variable in our [JSONTest.html](https://mdn.github.io/learning-area/javascript/oojs/json/JSONTest.html) example (see the [source code](https://github.com/mdn/learning-area/blob/main/javascript/oojs/json/JSONTest.html)). > Try loading this up and then accessing data inside the variable via your browser's JavaScript console. @@ -141,19 +135,29 @@ We can also convert arrays to/from JSON. The below example is perfectly valid JS ] ``` -You have to access array items (in its parsed version) by starting with an array index, for example `[0]["powers"][0]`. +You have to access array items (in its parsed version) by starting with an array index, for example `superHeroes[0].powers[0]`. -### Other notes +The JSON can also contain a single primitive. For example, `29`, `"Dan Jukes"`, or `true` are all valid JSON. -- JSON is purely a string with a specified data format — it contains only properties, no methods. -- JSON requires double quotes to be used around strings and property names. - Single quotes are not valid other than surrounding the entire JSON string. -- Even a single misplaced comma or colon can cause a JSON file to go wrong, and not work. - You should be careful to validate any data you are attempting to use (although computer-generated JSON is less likely to include errors, as long as the generator program is working correctly). - You can validate JSON using an application like [JSONLint](https://jsonlint.com/). -- JSON can actually take the form of any data type that is valid for inclusion inside JSON, not just arrays or objects. - So for example, a single string or number would be valid JSON. -- Unlike in JavaScript code in which object properties may be unquoted, in JSON only quoted strings may be used as properties. +### JSON syntax restrictions + +As mentioned earlier, any JSON is a valid JavaScript literal (object, array, number, etc.). The converse is not true, though—not all JavaScript object literals are valid JSON. + +- JSON can only contain _serializable_ data types. This means: + - For primitives, JSON can contain string literals, number literals, `true`, `false`, and `null`. Notably, it cannot contain `undefined`, `NaN`, or `Infinity`. + - For non-primitives, JSON can contain object literals and arrays, but not functions or any other object types, such as `Date`, `Set`, and `Map`. The objects and arrays inside JSON need to further contain valid JSON data types. +- Strings must be enclosed in double quotes, not single quotes. +- Numbers must be written in decimal notation. +- Each property of an object must be in the form of `"key": value`. Property names must be string literals enclosed in double quotes. Special JavaScript syntax, such as methods, is not allowed because methods are functions, and functions are not valid JSON data types. +- Objects and arrays cannot contain [trailing commas](/en-US/docs/Web/JavaScript/Reference/Trailing_commas). +- Comments are not allowed in JSON. + +Even a single misplaced comma or colon can make a JSON file invalid and cause it to fail. +You should be careful to validate any data you are attempting to use (although computer-generated JSON is less likely to include errors, as long as the generator program is working correctly). +You can validate JSON using an application like [JSONLint](https://jsonlint.com/) or [JSON-validate](https://www.json-validate.com/) + +> [!NOTE] +> Now you've read through this section, you might also want to supplement your learning with Scrimba's [JSON review](https://scrimba.com/frontend-path-c0j/~0lt?via=mdn) <sup>[_MDN learning partner_](/en-US/docs/MDN/Writing_guidelines/Learning_content#partner_links_and_embeds)</sup> interactive tutorial, which provide some useful guidance around basic JSON syntax and how to view JSON request data inside your browser's devtools. ## Active learning: Working through a JSON example @@ -174,7 +178,7 @@ The latter contains some simple CSS to style our page, while the former contains </section> <script> -... +// JavaScript goes here </script> ``` @@ -203,7 +207,7 @@ async function populate() { ``` To obtain the JSON, we use an API called [Fetch](/en-US/docs/Web/API/Fetch_API). -This API allows us to make network requests to retrieve resources from a server via JavaScript (e.g. images, text, JSON, even HTML snippets), meaning that we can update small sections of content without having to reload the entire page. +This API allows us to make network requests to retrieve resources from a server via JavaScript (e.g., images, text, JSON, even HTML snippets), meaning that we can update small sections of content without having to reload the entire page. In our function, the first four lines use the Fetch API to fetch the JSON from the server: @@ -346,7 +350,7 @@ Here we're creating a JavaScript object, then checking what it contains, then co ## Test your skills! -You've reached the end of this article, but can you remember the most important information? You can find some further tests to verify that you've retained this information before you move on — see [Test your skills: JSON](/en-US/docs/Learn_web_development/Core/Scripting/Test_your_skills:_JSON). +You've reached the end of this article, but can you remember the most important information? You can find some further tests to verify that you've retained this information before you move on — see [Test your skills: JSON](/en-US/docs/Learn_web_development/Core/Scripting/Test_your_skills/JSON). ## Summary @@ -357,6 +361,6 @@ In this lesson, we've introduced you to using JSON in your programs, including h - [JSON reference](/en-US/docs/Web/JavaScript/Reference/Global_Objects/JSON) - [Fetch API overview](/en-US/docs/Web/API/Fetch_API) - [Using Fetch](/en-US/docs/Web/API/Fetch_API/Using_Fetch) -- [HTTP request methods](/en-US/docs/Web/HTTP/Methods) +- [HTTP request methods](/en-US/docs/Web/HTTP/Reference/Methods) {{PreviousMenuNext("Learn_web_development/Core/Scripting/Network_requests","Learn_web_development/Core/Scripting/Debugging_JavaScript", "Learn_web_development/Core/Scripting")}} diff --git a/files/en-us/learn_web_development/core/scripting/loops/index.md b/files/en-us/learn_web_development/core/scripting/loops/index.md index 9401b2da342a422..3717d623dba9048 100644 --- a/files/en-us/learn_web_development/core/scripting/loops/index.md +++ b/files/en-us/learn_web_development/core/scripting/loops/index.md @@ -1,11 +1,11 @@ --- title: Looping code +short-title: Loops slug: Learn_web_development/Core/Scripting/Loops page-type: learn-module-chapter +sidebar: learnsidebar --- -{{LearnSidebar}} - {{PreviousMenuNext("Learn_web_development/Core/Scripting/Conditionals","Learn_web_development/Core/Scripting/Functions", "Learn_web_development/Core/Scripting")}} Programming languages are very useful for rapidly completing repetitive tasks, from multiple basic calculations to just about any other situation where you've got a lot of similar items of work to complete. Here we'll look at the loop structures available in JavaScript that handle such needs. @@ -670,7 +670,7 @@ function updateCode() { eval(textarea.value); } -reset.addEventListener("click", function () { +reset.addEventListener("click", () => { textarea.value = code; userEntry = textarea.value; solutionEntry = jsSolution; @@ -678,7 +678,7 @@ reset.addEventListener("click", function () { updateCode(); }); -solution.addEventListener("click", function () { +solution.addEventListener("click", () => { if (solution.value === "Show solution") { textarea.value = solutionEntry; solution.value = "Hide solution"; @@ -851,7 +851,7 @@ function updateCode() { eval(textarea.value); } -reset.addEventListener("click", function () { +reset.addEventListener("click", () => { textarea.value = code; userEntry = textarea.value; solutionEntry = jsSolution; @@ -859,7 +859,7 @@ reset.addEventListener("click", function () { updateCode(); }); -solution.addEventListener("click", function () { +solution.addEventListener("click", () => { if (solution.value === "Show solution") { textarea.value = solutionEntry; solution.value = "Hide solution"; @@ -996,7 +996,7 @@ do { ## Test your skills! -You've reached the end of this article, but can you remember the most important information? You can find some further tests to verify that you've retained this information before you move on — see [Test your skills: Loops](/en-US/docs/Learn_web_development/Core/Scripting/Test_your_skills:_Loops). +You've reached the end of this article, but can you remember the most important information? You can find some further tests to verify that you've retained this information before you move on — see [Test your skills: Loops](/en-US/docs/Learn_web_development/Core/Scripting/Test_your_skills/Loops). ## Summary diff --git a/files/en-us/learn_web_development/core/scripting/math/index.md b/files/en-us/learn_web_development/core/scripting/math/index.md index 816315c3ae72519..772873fd6144ba4 100644 --- a/files/en-us/learn_web_development/core/scripting/math/index.md +++ b/files/en-us/learn_web_development/core/scripting/math/index.md @@ -1,11 +1,11 @@ --- title: Basic math in JavaScript — numbers and operators +short-title: Numbers and operators slug: Learn_web_development/Core/Scripting/Math page-type: learn-module-chapter +sidebar: learnsidebar --- -{{LearnSidebar}} - {{PreviousMenuNext("Learn_web_development/Core/Scripting/Variables", "Learn_web_development/Core/Scripting/Strings", "Learn_web_development/Core/Scripting")}} At this point in the course, we discuss math in JavaScript — how we can use {{Glossary("Operator","operators")}} and other features to successfully manipulate numbers to do our bidding. @@ -43,7 +43,7 @@ This article discusses only the basic parts that you need to know now. In programming, even the humble decimal number system that we all know so well is more complicated than you might think. We use different terms to describe different types of decimal numbers, for example: -- **Integers** are numbers without a fractional part. They can either be positive or negative, e.g. 10, 400, or -5. +- **Integers** are numbers without a fractional part. They can either be positive or negative, e.g., 10, 400, or -5. - **Floating point numbers** (floats) have decimal points and decimal places, for example 12.5, and 56.7786543. We even have different types of number systems! Decimal is base 10 (meaning it uses 0–9 in each digit), but we also have things like: @@ -89,7 +89,7 @@ The [`Number`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number) objec For example, to round your number to a fixed number of decimal places, use the [`toFixed()`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number/toFixed) method. Type the following lines into your browser's [console](https://firefox-source-docs.mozilla.org/devtools-user/web_console/index.html): ```js -const lotsOfDecimal = 1.766584958675746364; +const lotsOfDecimal = 1.7665849587; lotsOfDecimal; const twoDecimalPlaces = lotsOfDecimal.toFixed(2); twoDecimalPlaces; @@ -97,7 +97,7 @@ twoDecimalPlaces; ### Converting to number data types -Sometimes you might end up with a number that is stored as a string type, which makes it difficult to perform calculations with it. This most commonly happens when data is entered into a [form](/en-US/docs/Learn_web_development/Extensions/Forms) input, and the [input type is text](/en-US/docs/Web/HTML/Element/input/text). There is a way to solve this problem — passing the string value into the [`Number()`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number/Number) constructor to return a number version of the same value. +Sometimes you might end up with a number that is stored as a string type, which makes it difficult to perform calculations with it. This most commonly happens when data is entered into a [form](/en-US/docs/Learn_web_development/Extensions/Forms) input, and the [input type is text](/en-US/docs/Web/HTML/Reference/Elements/input/text). There is a way to solve this problem — passing the string value into the [`Number()`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number/Number) constructor to return a number version of the same value. For example, try typing these lines into your console: @@ -379,12 +379,13 @@ In this exercise, you will manipulate some numbers and operators to change the s In the editable code box above, there are two lines marked with a comment that we'd like you to update to make the box grow/shrink to certain sizes, using certain operators and/or values in each case. Let's try the following: -- Change the line that calculates x so the box is still 50px wide, but the 50 is calculated using the numbers 43 and 7 and an arithmetic operator. -- Change the line that calculates y so the box is 75px high, but the 75 is calculated using the numbers 25 and 3 and an arithmetic operator. -- Change the line that calculates x so the box is 250px wide, but the 250 is calculated using two numbers and the remainder (modulo) operator. -- Change the line that calculates y so the box is 150px high, but the 150 is calculated using three numbers and the subtraction and division operators. -- Change the line that calculates x so the box is 200px wide, but the 200 is calculated using the number 4 and an assignment operator. -- Change the line that calculates y so the box is 200px high, but the 200 is calculated using the numbers 50 and 3, the multiplication operator, and the addition assignment operator. +- Change the line that calculates `x` so the box is still 50px wide, but the 50 is calculated using the numbers 43 and 7 and an arithmetic operator. +- Change the line that calculates `y` so the box is 75px high, but the 75 is calculated using the numbers 25 and 3 and an arithmetic operator. +- Change the line that calculates `x` so the box is 250px wide, but the 250 is calculated using two numbers and the remainder (modulo) operator. +- Change the line that calculates `y` so the box is 150px high, but the 150 is calculated using three numbers and the subtraction and division operators. +- Change the line that calculates `x` so the box is 200px wide, but the 200 is calculated using the number 4 and an assignment operator. +- Change the line that calculates `y` so the box is 200px high, but the 200 is calculated using the numbers 50 and 3, the multiplication operator, and the addition assignment operator. + Don't forget to first assign a default value to `y` (in a separate line), so the addition works as expected. Don't worry if you totally mess the code up. You can always press the Reset button to get things working again. After you've answered all the above questions correctly, feel free to play with the code some more or create your own challenges. @@ -446,7 +447,7 @@ You can see the equality operator being used just inside the `updateBtn()` funct ## Test your skills! -You've reached the end of this article, but can you remember the most important information? You can find some further tests to verify that you've retained this information before you move on — see [Test your skills: Math](/en-US/docs/Learn_web_development/Core/Scripting/Test_your_skills:_Math). +You've reached the end of this article, but can you remember the most important information? You can find some further tests to verify that you've retained this information before you move on — see [Test your skills: Math](/en-US/docs/Learn_web_development/Core/Scripting/Test_your_skills/Math). ## Summary diff --git a/files/en-us/learn_web_development/core/scripting/network_requests/index.md b/files/en-us/learn_web_development/core/scripting/network_requests/index.md index d0d72489bd8759c..591c2f0c2841b7d 100644 --- a/files/en-us/learn_web_development/core/scripting/network_requests/index.md +++ b/files/en-us/learn_web_development/core/scripting/network_requests/index.md @@ -1,11 +1,11 @@ --- title: Making network requests with JavaScript +short-title: Network requests slug: Learn_web_development/Core/Scripting/Network_requests page-type: learn-module-chapter +sidebar: learnsidebar --- -{{LearnSidebar}} - {{PreviousMenuNext("Learn_web_development/Core/Scripting/DOM_scripting","Learn_web_development/Core/Scripting/JSON", "Learn_web_development/Core/Scripting")}} Another very common task in modern websites and applications is making network requests to retrieve individual data items from the server to update sections of a webpage without having to load an entire new page. This seemingly small detail has had a huge impact on the performance and behavior of sites, so in this article, we'll explain the concept and look at technologies that make it possible: in particular, the [Fetch API](/en-US/docs/Web/API/Fetch_API). @@ -57,7 +57,9 @@ To speed things up even further, some sites also store assets and data on the us ## The Fetch API -Let's walk through a couple of examples of the Fetch API. +In this section we'll walk through a couple of examples of the Fetch API. + +The examples below are of a certain level of complexity, and show how to use the Fetch API in some real world contexts. If you have never used fetch before, you might want to start by working through Scrimba's [First fetch](https://scrimba.com/frontend-path-c0j/~0lu?via=mdn) <sup>[_MDN learning partner_](/en-US/docs/MDN/Writing_guidelines/Learning_content#partner_links_and_embeds)</sup> interactive tutorial, which provides a very simple intro walkthrough. ### Fetching text content @@ -180,7 +182,7 @@ The `fetch()` function returns a promise. If this completes successfully, the fu Inside this function we: -- check that the server didn't return an error (such as [`404 Not Found`](/en-US/docs/Web/HTTP/Status/404)). If it did, we throw the error. +- check that the server didn't return an error (such as [`404 Not Found`](/en-US/docs/Web/HTTP/Reference/Status/404)). If it did, we throw the error. - call {{domxref("Response.json","json()")}} on the response. This will retrieve the data as a [JSON object](/en-US/docs/Learn_web_development/Core/Scripting/JSON). We return the promise returned by `response.json()`. Next we pass a function into the `then()` method of that returned promise. This function will be passed an object containing the response data as JSON, which we pass into the `initialize()` function. It is `initialize()` which starts the process of displaying all the products in the user interface. @@ -260,7 +262,7 @@ There are however a lot of different subjects discussed in this article, which h - [Using Fetch](/en-US/docs/Web/API/Fetch_API/Using_Fetch) - [Promises](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise) - [Working with JSON data](/en-US/docs/Learn_web_development/Core/Scripting/JSON) -- [An overview of HTTP](/en-US/docs/Web/HTTP/Overview) +- [An overview of HTTP](/en-US/docs/Web/HTTP/Guides/Overview) - [Server-side website programming](/en-US/docs/Learn_web_development/Extensions/Server-side) {{PreviousMenuNext("Learn_web_development/Core/Scripting/DOM_scripting","Learn_web_development/Core/Scripting/JSON", "Learn_web_development/Core/Scripting")}} diff --git a/files/en-us/learn_web_development/core/scripting/object_basics/index.md b/files/en-us/learn_web_development/core/scripting/object_basics/index.md index 96732c6d956f63c..0f13b728248be8a 100644 --- a/files/en-us/learn_web_development/core/scripting/object_basics/index.md +++ b/files/en-us/learn_web_development/core/scripting/object_basics/index.md @@ -1,11 +1,11 @@ --- title: JavaScript object basics +short-title: Objects slug: Learn_web_development/Core/Scripting/Object_basics page-type: learn-module-chapter +sidebar: learnsidebar --- -{{LearnSidebar}} - {{PreviousMenuNext("Learn_web_development/Core/Scripting/Image_gallery","Learn_web_development/Core/Scripting/DOM_scripting", "Learn_web_development/Core/Scripting")}} In this article, we'll look at fundamental JavaScript object syntax, and revisit some JavaScript features that we've already seen earlier in the course, reiterating the fact that many of the features you've already dealt with are objects. @@ -82,7 +82,7 @@ person.introduceSelf(); You have now got some data and functionality inside your object, and are now able to access them with some nice simple syntax! -So what is going on here? Well, an object is made up of multiple members, each of which has a name (e.g. `name` and `age` above), and a value (e.g. `['Bob', 'Smith']` and `32`). Each name/value pair must be separated by a comma, and the name and value in each case are separated by a colon. The syntax always follows this pattern: +So what is going on here? Well, an object is made up of multiple members, each of which has a name (e.g., `name` and `age` above), and a value (e.g., `['Bob', 'Smith']` and `32`). Each name/value pair must be separated by a comma, and the name and value in each case are separated by a colon. The syntax always follows this pattern: ```js const objectName = { @@ -278,9 +278,12 @@ Adding a property to an object using the method above isn't possible with dot no You may have noticed something slightly strange in our methods. Look at this one for example: ```js -introduceSelf() { - console.log(`Hi! I'm ${this.name[0]}.`); -} +const person = { + // … + introduceSelf() { + console.log(`Hi! I'm ${this.name[0]}.`); + }, +}; ``` You are probably wondering what "this" is. The `this` keyword typically refers to the current object the code is being executed in. In the context of an object method, `this` refers to the object that the method was called on. @@ -406,7 +409,7 @@ const myNotification = new Notification("Hello!"); ## Test your skills! -You've reached the end of this article, but can you remember the most important information? You can find some further tests to verify that you've retained this information before you move on — see [Test your skills: Object basics](/en-US/docs/Learn_web_development/Core/Scripting/Test_your_skills:_Object_basics). +You've reached the end of this article, but can you remember the most important information? You can find some further tests to verify that you've retained this information before you move on — see [Test your skills: Object basics](/en-US/docs/Learn_web_development/Core/Scripting/Test_your_skills/Object_basics). ## Summary diff --git a/files/en-us/learn_web_development/core/scripting/return_values/index.md b/files/en-us/learn_web_development/core/scripting/return_values/index.md index bc511d4a7593406..36ca7edaea59c43 100644 --- a/files/en-us/learn_web_development/core/scripting/return_values/index.md +++ b/files/en-us/learn_web_development/core/scripting/return_values/index.md @@ -2,10 +2,9 @@ title: Function return values slug: Learn_web_development/Core/Scripting/Return_values page-type: learn-module-chapter +sidebar: learnsidebar --- -{{LearnSidebar}} - {{PreviousMenuNext("Learn_web_development/Core/Scripting/Build_your_own_function","Learn_web_development/Core/Scripting/Events", "Learn_web_development/Core/Scripting")}} There's one last essential concept about functions for us to discuss — return values. Some functions don't return a significant value, but others do. It's important to understand what their values are, how to use them in your code, and how to make functions return useful values. We'll cover all of these below. @@ -22,7 +21,7 @@ There's one last essential concept about functions for us to discuss — return <ul> <li>What returns values are.</li> <li>How to use the return values of existing functions.</li> - <li>Adding return values to your own fuctions.</li> + <li>Adding return values to your own functions.</li> </ul> </td> </tr> @@ -176,7 +175,7 @@ Some extra function-related tips: ## Test your skills! -You've reached the end of this article, but can you remember the most important information? You can find some further tests to verify that you've retained this information before you move on — see [Test your skills: Functions](/en-US/docs/Learn_web_development/Core/Scripting/Building_blocks/Test_your_skills:_Functions). +You've reached the end of this article, but can you remember the most important information? You can find some further tests to verify that you've retained this information before you move on — see [Test your skills: Functions](/en-US/docs/Learn_web_development/Core/Scripting/Test_your_skills/Functions). ## Conclusion diff --git a/files/en-us/learn_web_development/core/scripting/silly_story_generator/index.md b/files/en-us/learn_web_development/core/scripting/silly_story_generator/index.md index 9ab7d224b2f042a..7a5a00db008d309 100644 --- a/files/en-us/learn_web_development/core/scripting/silly_story_generator/index.md +++ b/files/en-us/learn_web_development/core/scripting/silly_story_generator/index.md @@ -1,11 +1,11 @@ --- title: "Challenge: Silly story generator" +short-title: "Challenge: Story generator" slug: Learn_web_development/Core/Scripting/Silly_story_generator page-type: learn-module-assessment +sidebar: learnsidebar --- -{{LearnSidebar}} - {{PreviousMenuNext("Learn_web_development/Core/Scripting/Arrays", "Learn_web_development/Core/Scripting/Conditionals", "Learn_web_development/Core/Scripting")}} In this challenge you'll be tasked with taking some of the knowledge you've picked up in this module's articles and applying it to creating a fun app that generates random silly stories. Have fun! diff --git a/files/en-us/learn_web_development/core/scripting/strings/index.md b/files/en-us/learn_web_development/core/scripting/strings/index.md index 399b9e9a9cc1fbf..9e6335650371c66 100644 --- a/files/en-us/learn_web_development/core/scripting/strings/index.md +++ b/files/en-us/learn_web_development/core/scripting/strings/index.md @@ -1,11 +1,11 @@ --- title: Handling text — strings in JavaScript +short-title: Strings slug: Learn_web_development/Core/Scripting/Strings page-type: learn-module-chapter +sidebar: learnsidebar --- -{{LearnSidebar}} - {{PreviousMenuNext("Learn_web_development/Core/Scripting/Math", "Learn_web_development/Core/Scripting/Useful_string_methods", "Learn_web_development/Core/Scripting")}} Next, we'll turn our attention to strings — this is what pieces of text are called in programming. In this article, we'll look at all the common things that you really ought to know about strings when learning JavaScript, such as creating strings, escaping quotes in strings, and joining strings together. diff --git a/files/en-us/learn_web_development/core/scripting/test_your_skills/arrays/index.md b/files/en-us/learn_web_development/core/scripting/test_your_skills/arrays/index.md new file mode 100644 index 000000000000000..abeacdb7fb6b0fe --- /dev/null +++ b/files/en-us/learn_web_development/core/scripting/test_your_skills/arrays/index.md @@ -0,0 +1,76 @@ +--- +title: "Test your skills: Arrays" +short-title: Arrays +slug: Learn_web_development/Core/Scripting/Test_your_skills/Arrays +page-type: learn-module-assessment +sidebar: learnsidebar +--- + +The aim of this skill test is to assess whether you've understood our [Arrays](/en-US/docs/Learn_web_development/Core/Scripting/Arrays) article. + +> [!NOTE] +> You can try solutions in the interactive editors on this page or in an online editor such as [CodePen](https://codepen.io/), [JSFiddle](https://jsfiddle.net/), or [Glitch](https://glitch.com/). +> +> If you get stuck, you can reach out to us in one of our [communication channels](/en-US/docs/MDN/Community/Communication_channels). + +## Arrays 1 + +Let's start off with some basic array practice. In this task we'd like you to create an array of three items, stored inside a variable called `myArray`. The items can be anything you want — how about your favorite foods or bands? + +Next, modify the first two items in the array using simple bracket notation and assignment. Then add a new item to the beginning of the array. + +Try updating the live code below to recreate the finished example: + +{{EmbedGHLiveSample("learning-area/javascript/introduction-to-js-1/tasks/arrays/arrays1.html", '100%', 400)}} + +> [!CALLOUT] +> +> [Download the starting point for this task](https://github.com/mdn/learning-area/blob/main/javascript/introduction-to-js-1/tasks/arrays/arrays1-download.html) to work in your own editor or in an online editor. + +## Arrays 2 + +Now let's move on to another task. Here you are provided with a string to work with. We'd like you to: + +1. Convert the string into an array, removing the `+` characters in the process. Save the result in a variable called `myArray`. +2. Store the length of the array in a variable called `arrayLength`. +3. Store the last item in the array in a variable called `lastItem`. + +Try updating the live code below to recreate the finished example: + +{{EmbedGHLiveSample("learning-area/javascript/introduction-to-js-1/tasks/arrays/arrays2.html", '100%', 400)}} + +> [!CALLOUT] +> +> [Download the starting point for this task](https://github.com/mdn/learning-area/blob/main/javascript/introduction-to-js-1/tasks/arrays/arrays2-download.html) to work in your own editor or in an online editor. + +## Arrays 3 + +For this array task, we provide you with a starting array, and you will work in somewhat the opposite direction. You need to: + +1. Remove the last item in the array. +2. Add two new names to the end of the array. +3. Go over each item in the array and add its index number after the name inside parentheses, for example `Ryu (0)`. Note that we don't teach how to do this in the Arrays article, so you'll have to do some research. +4. Finally, join the array items together in a single string called `myString`, with a separator of `"-"`. + +Try updating the live code below to recreate the finished example: + +{{EmbedGHLiveSample("learning-area/javascript/introduction-to-js-1/tasks/arrays/arrays3.html", '100%', 400)}} + +> [!CALLOUT] +> +> [Download the starting point for this task](https://github.com/mdn/learning-area/blob/main/javascript/introduction-to-js-1/tasks/arrays/arrays3-download.html) to work in your own editor or in an online editor. + +## Arrays 4 + +For this array task, we provide you with a starting array listing the names of some birds. + +- Find the index of the `"Eagles"` item, and use that to remove the `"Eagles"` item. +- Make a new array from this one, called `eBirds`, that contains only birds from the original array whose names begin with the letter "E". Note that {{jsxref("String.prototype.startsWith()", "startsWith()")}} is a great way to check whether a string starts with a given character. + +If it works, you should see `"Emus,Egrets"` appear in the page. + +{{EmbedGHLiveSample("learning-area/javascript/introduction-to-js-1/tasks/arrays/arrays4.html", '100%', 400)}} + +> [!CALLOUT] +> +> [Download the starting point for this task](https://github.com/mdn/learning-area/blob/main/javascript/introduction-to-js-1/tasks/arrays/arrays4-download.html) to work in your own editor or in an online editor. diff --git a/files/en-us/learn_web_development/core/scripting/test_your_skills/conditionals/index.md b/files/en-us/learn_web_development/core/scripting/test_your_skills/conditionals/index.md new file mode 100644 index 000000000000000..462485d826f9c78 --- /dev/null +++ b/files/en-us/learn_web_development/core/scripting/test_your_skills/conditionals/index.md @@ -0,0 +1,83 @@ +--- +title: "Test your skills: Conditionals" +short-title: Conditionals +slug: Learn_web_development/Core/Scripting/Test_your_skills/Conditionals +page-type: learn-module-assessment +sidebar: learnsidebar +--- + +The aim of this skill test is to assess whether you've understood our [Making decisions in your code — conditionals](/en-US/docs/Learn_web_development/Core/Scripting/Conditionals) article. + +> [!NOTE] +> You can try solutions by downloading the code and putting it in an online editor such as [CodePen](https://codepen.io/), [JSFiddle](https://jsfiddle.net/), or [Glitch](https://glitch.com/). +> If there is an error, it will be logged in the results panel on the page or into the browser's JavaScript console to help you. +> +> If you get stuck, you can reach out to us in one of our [communication channels](/en-US/docs/MDN/Community/Communication_channels). + +## Conditionals 1 + +In this task you are provided with two variables: + +- `season` — contains a string that says what the current season is. +- `response` — begins uninitialized, but is later used to store a response that will be printed to the output panel. + +We want you to create a conditional that checks whether `season` contains the string "summer", and if so assigns a string to `response` that gives the user an appropriate message about the season. If not, it should assign a generic string to `response` that tells the user we don't know what season it is. + +To finish off, you should then add another test that checks whether `season` contains the string "winter", and again assigns an appropriate string to `response`. + +Try updating the live code below to recreate the finished example: + +{{EmbedGHLiveSample("learning-area/javascript/building-blocks/tasks/conditionals/conditionals1.html", '100%', 400)}} + +> [!CALLOUT] +> +> [Download the starting point for this task](https://github.com/mdn/learning-area/blob/main/javascript/building-blocks/tasks/conditionals/conditionals1-download.html) to work in your own editor or in an online editor. + +## Conditionals 2 + +For this task you are given three variables: + +- `machineActive` — contains an indicator of whether the answer machine is switched on or not (`true`/`false`) +- `score` — Contains your score in an imaginary game. This score is fed into the answer machine, which provides a response to indicate how well you did. +- `response` — begins uninitialized, but is later used to store a response that will be printed to the output panel. + +You need to create an `if...else` structure that checks whether the machine is switched on and puts a message into the `response` variable if it isn't, telling the user to switch the machine on. + +Inside the first `if...else`, you need to nest another `if...else` that puts appropriate messages into the `response` variable depending on what the value of score is — if the machine is turned on. The different conditional tests (and resulting responses) are as follows: + +- Score of less than 0 or more than 100 — "This is not possible, an error has occurred." +- Score of 0 to 19 — "That was a terrible score — total fail!" +- Score of 20 to 39 — "You know some things, but it\\'s a pretty bad score. Needs improvement." +- Score of 40 to 69 — "You did a passable job, not bad!" +- Score of 70 to 89 — "That\\'s a great score, you really know your stuff." +- Score of 90 to 100 — "What an amazing score! Did you cheat? Are you for real?" + +Try updating the live code below to recreate the finished example. After you've entered your code, try changing `machineActive` to `true`, to see if it works. +Please note that, for the scope of this exercise, the `Your score is __` statement will remain on the screen regardless of the `machineActive`'s value. + +{{EmbedGHLiveSample("learning-area/javascript/building-blocks/tasks/conditionals/conditionals2.html", '100%', 400)}} + +> [!CALLOUT] +> +> [Download the starting point for this task](https://github.com/mdn/learning-area/blob/main/javascript/building-blocks/tasks/conditionals/conditionals2-download.html) to work in your own editor or in an online editor. + +## Conditionals 3 + +For the final task you are given four variables: + +- `machineActive` — contains an indicator of whether the login machine is switched on or not (`true`/`false`). +- `pwd` — Contains the user's login password. +- `machineResult` — begins uninitialized, but is later used to store a response that will be printed to the output panel, letting the user know whether the machine is switched on. +- `pwdResult` — begins uninitialized, but is later used to store a response that will be printed to the output panel, letting the user know whether their login attempt was successful. + +We'd like you to create an `if...else` structure that checks whether the machine is switched on and puts a message into the `machineResult` variable telling the user whether it is on or off. + +If the machine is on, we also want a second conditional to run that checks whether the `pwd` is equal to `cheese`. If so, it should assign a string to `pwdResult` telling the user they logged in successfully. If not, it should assign a different string to `pwdResult` telling the user their login attempt was not successful. We'd like you to do this in a single line, using something that isn't an `if...else` structure. + +Try updating the live code below to recreate the finished example: + +{{EmbedGHLiveSample("learning-area/javascript/building-blocks/tasks/conditionals/conditionals3.html", '100%', 400)}} + +> [!CALLOUT] +> +> [Download the starting point for this task](https://github.com/mdn/learning-area/blob/main/javascript/building-blocks/tasks/conditionals/conditionals3-download.html) to work in your own editor or in an online editor. diff --git a/files/en-us/learn_web_development/core/scripting/test_your_skills/events/index.md b/files/en-us/learn_web_development/core/scripting/test_your_skills/events/index.md new file mode 100644 index 000000000000000..e29646aaf276e83 --- /dev/null +++ b/files/en-us/learn_web_development/core/scripting/test_your_skills/events/index.md @@ -0,0 +1,65 @@ +--- +title: "Test your skills: Events" +short-title: Events +slug: Learn_web_development/Core/Scripting/Test_your_skills/Events +page-type: learn-module-assessment +sidebar: learnsidebar +--- + +The aim of this skill test is to assess whether you've understood our [Introduction to events](/en-US/docs/Learn_web_development/Core/Scripting/Events) article. + +> [!NOTE] +> You can try solutions by downloading the code and putting it in an online editor such as [CodePen](https://codepen.io/), [JSFiddle](https://jsfiddle.net/), or [Glitch](https://glitch.com/). +> If there is an error, it will be logged in the results panel on the page or into the browser's JavaScript console to help you. +> +> If you get stuck, you can reach out to us in one of our [communication channels](/en-US/docs/MDN/Community/Communication_channels). + +## DOM manipulation: considered useful + +Some of the questions below require you to write some [DOM](/en-US/docs/Glossary/DOM) manipulation code to complete them — such as creating new HTML elements, setting their text contents to equal specific string values, and nesting them inside existing elements on the page — all via JavaScript. + +We haven't explicitly taught this yet in the course, but you'll have seen some examples that make use of it, and we'd like you to do some research into what DOM APIs you need to successfully answer the questions. A good starting place is our [DOM scripting introduction](/en-US/docs/Learn_web_development/Core/Scripting/DOM_scripting) tutorial. + +## Events 1 + +In our first events-related task, you need to create an event handler that causes the text inside the button (`btn`) to change when it is clicked on, and change back when it is clicked again. + +The HTML should not be changed; just the JavaScript. + +Try updating the live code below to recreate the finished example: + +{{EmbedGHLiveSample("learning-area/javascript/building-blocks/tasks/events/events1.html", '100%', 400)}} + +> [!CALLOUT] +> +> [Download the starting point for this task](https://github.com/mdn/learning-area/blob/main/javascript/building-blocks/tasks/events/events1-download.html) to work in your own editor or in an online editor. + +## Events 2 + +Now we'll look at keyboard events. To pass this assessment you need to build an event handler that moves the circle around the provided canvas when the WASD keys are pressed on the keyboard. The circle is drawn with the function `drawCircle()`, which takes the following parameters as inputs: + +- `x` — the x coordinate of the circle. +- `y` — the y coordinate of the circle. +- `size` — the radius of the circle. + +Try updating the live code below to recreate the finished example: + +{{EmbedGHLiveSample("learning-area/javascript/building-blocks/tasks/events/events2.html", '100%', 650)}} + +> [!CALLOUT] +> +> [Download the starting point for this task](https://github.com/mdn/learning-area/blob/main/javascript/building-blocks/tasks/events/events2-download.html) to work in your own editor or in an online editor. + +## Events 3 + +In the next events-related task, you need to set an event listener on the `<button>`s' parent element (`<div class="button-bar"> … </div>`), which when invoked by clicking any of the buttons will set the background of the `button-bar` to the color contained in the button's `data-color` attribute. + +We want you to solve this without looping through all the buttons and giving each one their own event listener. + +Try updating the live code below to recreate the finished example: + +{{EmbedGHLiveSample("learning-area/javascript/building-blocks/tasks/events/events3.html", '100%', 600)}} + +> [!CALLOUT] +> +> [Download the starting point for this task](https://github.com/mdn/learning-area/blob/main/javascript/building-blocks/tasks/events/events3-download.html) to work in your own editor or in an online editor. diff --git a/files/en-us/learn_web_development/core/scripting/test_your_skills/functions/index.md b/files/en-us/learn_web_development/core/scripting/test_your_skills/functions/index.md new file mode 100644 index 000000000000000..ed9827bd943d575 --- /dev/null +++ b/files/en-us/learn_web_development/core/scripting/test_your_skills/functions/index.md @@ -0,0 +1,81 @@ +--- +title: "Test your skills: Functions" +short-title: Functions +slug: Learn_web_development/Core/Scripting/Test_your_skills/Functions +page-type: learn-module-assessment +sidebar: learnsidebar +--- + +The aim of this skill test is to assess whether you've understood our [Functions — reusable blocks of code](/en-US/docs/Learn_web_development/Core/Scripting/Functions), [Build your own function](/en-US/docs/Learn_web_development/Core/Scripting/Build_your_own_function), and [Function return values](/en-US/docs/Learn_web_development/Core/Scripting/Return_values) articles. + +> [!NOTE] +> You can try solutions by downloading the code and putting it in an online editor such as [CodePen](https://codepen.io/), [JSFiddle](https://jsfiddle.net/), or [Glitch](https://glitch.com/). +> If there is an error, it will be logged in the results panel on the page or into the browser's JavaScript console to help you. +> +> If you get stuck, you can reach out to us in one of our [communication channels](/en-US/docs/MDN/Community/Communication_channels). + +## DOM manipulation: considered useful + +Some of the questions below require you to write some [DOM](/en-US/docs/Glossary/DOM) manipulation code to complete them — such as creating new HTML elements, setting their text contents to equal specific string values, and nesting them inside existing elements on the page — all via JavaScript. + +We haven't explicitly taught this yet in the course, but you'll have seen some examples that make use of it, and we'd like you to do some research into what DOM APIs you need to successfully answer the questions. A good starting place is our [DOM scripting introduction](/en-US/docs/Learn_web_development/Core/Scripting/DOM_scripting) tutorial. + +## Functions 1 + +For the first task, you have to create a simple function — `chooseName()` — that prints a random name from the provided array (`names`) to the provided paragraph (`para`), and then run it once. + +Try updating the live code below to recreate the finished example: + +{{EmbedGHLiveSample("learning-area/javascript/building-blocks/tasks/functions/functions1.html", '100%', 400)}} + +> [!CALLOUT] +> +> [Download the starting point for this task](https://github.com/mdn/learning-area/blob/main/javascript/building-blocks/tasks/functions/functions1-download.html) to work in your own editor or in an online editor. + +## Functions 2 + +For our second functions-related task, you need to create a function that draws a rectangle on the provided `<canvas>` (reference variable `canvas`, context available in `ctx`), based on the five provided input variables: + +- `x` — the x coordinate of the rectangle. +- `y` — the y coordinate of the rectangle. +- `width` — the width of the rectangle. +- `height` — the height of the rectangle. +- `color` — the color of the rectangle. + +You'll want to clear the canvas before drawing, so that when the code is updated in the case of the live version, you don't get lots of rectangles drawn on top of one another. + +Try updating the live code below to recreate the finished example: + +{{EmbedGHLiveSample("learning-area/javascript/building-blocks/tasks/functions/functions2.html", '100%', 700)}} + +> [!CALLOUT] +> +> [Download the starting point for this task](https://github.com/mdn/learning-area/blob/main/javascript/building-blocks/tasks/functions/functions2-download.html) to work in your own editor or in an online editor. + +## Functions 3 + +In this task, you return to the problem posed in Task 1, with the aim of improving it. The three improvements we want you to make are: + +1. Refactor the code that generates the random number into a separate function called `random()`, which takes as parameters two generic bounds that the random number should be between, and returns the result. +2. Update the `chooseName()` function so that it makes use of the random number function, takes the array to choose from as a parameter (making it more flexible), and returns the result. +3. Print the returned result into the paragraph (`para`)'s `textContent`. + +Try updating the live code below to recreate the finished example: + +{{EmbedGHLiveSample("learning-area/javascript/building-blocks/tasks/functions/functions3.html", '100%', 400)}} + +> [!CALLOUT] +> +> [Download the starting point for this task](https://github.com/mdn/learning-area/blob/main/javascript/building-blocks/tasks/functions/functions3-download.html) to work in your own editor or in an online editor. + +## Functions 4 + +In this task, we have an array of names, and we're using {{jsxref("Array.filter()")}} to get an array of only names shorter than 5 characters. The filter is currently being passed a named function `isShort()` which checks the length of the name, returning `true` if the name is less than 5 characters long, and `false` otherwise. + +We'd like you to change this into an arrow function. See how compact you can make it. + +{{EmbedGHLiveSample("learning-area/javascript/building-blocks/tasks/functions/functions4.html", '100%', 400)}} + +> [!CALLOUT] +> +> [Download the starting point for this task](https://github.com/mdn/learning-area/blob/main/javascript/building-blocks/tasks/functions/functions4-download.html) to work in your own editor or in an online editor. diff --git a/files/en-us/learn_web_development/core/scripting/test_your_skills/index.md b/files/en-us/learn_web_development/core/scripting/test_your_skills/index.md new file mode 100644 index 000000000000000..f770778a590c1a0 --- /dev/null +++ b/files/en-us/learn_web_development/core/scripting/test_your_skills/index.md @@ -0,0 +1,17 @@ +--- +title: "Test your skills: JavaScript" +short-title: Test your skills +slug: Learn_web_development/Core/Scripting/Test_your_skills +page-type: learn-module-assessment +sidebar: learnsidebar +--- + +This page lists JavaScript tests you can try so you can verify if you've understood the content in this module. + +## Test your JavaScript skills by topic + +{{SubpagesWithSummaries}} + +## See also + +- [Dynamic scripting with JavaScript](/en-US/docs/Learn_web_development/Core/Scripting) diff --git a/files/en-us/learn_web_development/core/scripting/test_your_skills/json/index.md b/files/en-us/learn_web_development/core/scripting/test_your_skills/json/index.md new file mode 100644 index 000000000000000..52eef00d572dba0 --- /dev/null +++ b/files/en-us/learn_web_development/core/scripting/test_your_skills/json/index.md @@ -0,0 +1,39 @@ +--- +title: "Test your skills: JSON" +short-title: JSON +slug: Learn_web_development/Core/Scripting/Test_your_skills/JSON +page-type: learn-module-assessment +sidebar: learnsidebar +--- + +The aim of this skill test is to assess whether you've understood our [Working with JSON](/en-US/docs/Learn_web_development/Core/Scripting/JSON) article. + +> [!NOTE] +> You can try solutions by downloading the code and putting it in an online editor such as [CodePen](https://codepen.io/), [JSFiddle](https://jsfiddle.net/), or [Glitch](https://glitch.com/). +> If there is an error, it will be logged in the results panel on the page or into the browser's JavaScript console to help you. +> +> If you get stuck, you can reach out to us in one of our [communication channels](/en-US/docs/MDN/Community/Communication_channels). + +## JSON 1 + +The one and only task in this article concerns accessing JSON data and using it in your page. JSON data about some mother cats and their kittens is available in [sample.json](https://github.com/mdn/learning-area/blob/main/javascript/oojs/tasks/json/sample.json). The JSON is loaded into the page as a text string and made available in the `catString` parameter of the `displayCatInfo()` function. Your task is to fill in the missing parts of the `displayCatInfo()` function to store: + +- The names of the three mother cats, separated by commas, in the `motherInfo` variable. +- The total number of kittens, and how many are male and female, in the `kittenInfo` variable. + +The values of these variables are then printed to the screen inside paragraphs. + +Some hints/questions: + +- The JSON data is provided as text inside the `displayCatInfo()` function. You'll need to parse it into JSON before you can get any data out of it. +- You'll probably want to use an outer loop to loop through the cats and add their names to the `motherInfo` variable string, and an inner loop to loop through all the kittens, add up the total of all/male/female kittens, and add those details to the `kittenInfo` variable string. +- The last mother cat name should have an "and" before it, and a full stop after it. How do you make sure this can work, no matter how many cats are in the JSON? +- Why are the `para1.textContent = motherInfo;` and `para2.textContent = kittenInfo;` lines inside the `displayCatInfo()` function, and not at the end of the script? This has something to do with async code. + +Try updating the live code below to recreate the finished example: + +{{EmbedGHLiveSample("learning-area/javascript/oojs/tasks/json/json1.html", '100%', 400)}} + +> [!CALLOUT] +> +> [Download the starting point for this task](https://github.com/mdn/learning-area/blob/main/javascript/oojs/tasks/json/json1-download.html) to work in your own editor or in an online editor. diff --git a/files/en-us/learn_web_development/core/scripting/test_your_skills/loops/index.md b/files/en-us/learn_web_development/core/scripting/test_your_skills/loops/index.md new file mode 100644 index 000000000000000..7958862abb0b1da --- /dev/null +++ b/files/en-us/learn_web_development/core/scripting/test_your_skills/loops/index.md @@ -0,0 +1,62 @@ +--- +title: "Test your skills: Loops" +short-title: Loops +slug: Learn_web_development/Core/Scripting/Test_your_skills/Loops +page-type: learn-module-assessment +sidebar: learnsidebar +--- + +The aim of this skill test is to assess whether you've understood our [Looping code](/en-US/docs/Learn_web_development/Core/Scripting/Loops) article. + +> [!NOTE] +> You can try solutions by downloading the code and putting it in an online editor such as [CodePen](https://codepen.io/), [JSFiddle](https://jsfiddle.net/), or [Glitch](https://glitch.com/). +> +> If you get stuck, you can reach out to us in one of our [communication channels](/en-US/docs/MDN/Community/Communication_channels). + +## DOM manipulation: considered useful + +Some of the questions below require you to write some [DOM](/en-US/docs/Glossary/DOM) manipulation code to complete them — such as creating new HTML elements, setting their text contents to equal specific string values, and nesting them inside existing elements on the page — all via JavaScript. + +We haven't explicitly taught this yet in the course, but you'll have seen some examples that make use of it, and we'd like you to do some research into what DOM APIs you need to successfully answer the questions. A good starting place is our [DOM scripting introduction](/en-US/docs/Learn_web_development/Core/Scripting/DOM_scripting) tutorial. + +## Loops 1 + +In our first looping task we want you to start by creating a simple loop that goes through all the items in the provided `myArray` and prints them out on the screen inside list items (i.e., [`<li>`](/en-US/docs/Web/HTML/Reference/Elements/li) elements), which are appended to the provided `list`. + +> [!CALLOUT] +> +> [Download the starting point for this task](https://github.com/mdn/learning-area/blob/main/javascript/building-blocks/tasks/loops/loops1-download.html) to work in your own editor or in an online editor. + +## Loops 2 + +In this next task, we want you to write a simple program that, given a name, searches an array of [objects](/en-US/docs/Glossary/Object) containing names and phone numbers (`phonebook`) and, if it finds the name, outputs the name and phone number into the paragraph (`para`) and then exits the loop before it has run its course. + +If you haven't read about objects yet, don't worry! For now, all you need to know is how to access a member-value pair. You can read up on objects in the [JavaScript object basics](/en-US/docs/Learn_web_development/Core/Scripting/Object_basics) tutorial. + +You are given three variables to begin with: + +- `name` — contains a name to search for +- `para` — contains a reference to a paragraph, which will be used to report the results +- `phonebook` - contains the phonebook entries to search. + +You should use a type of loop that you've not used in the previous task. + +> [!CALLOUT] +> +> [Download the starting point for this task](https://github.com/mdn/learning-area/blob/main/javascript/building-blocks/tasks/loops/loops2-download.html) to work in your own editor or in an online editor. + +## Loops 3 + +In this final task, you are provided with the following: + +- `i` — starts off with a value of 500; intended to be used as an iterator. +- `para` — contains a reference to a paragraph, which will be used to report the results. +- `isPrime()` — a function that, when passed a number, returns `true` if the number is a prime number, and `false` if not. + +You need to use a loop to go through the numbers 2 to 500 backwards (1 is not counted as a prime number), and run the provided `isPrime()` function on them. For each number that isn't a prime number, continue on to the next loop iteration. For each one that is a prime number, add it to the paragraph's `textContent` along with some kind of separator. + +You should use a type of loop that you've not used in the previous two tasks. + +> [!CALLOUT] +> +> [Download the starting point for this task](https://github.com/mdn/learning-area/blob/main/javascript/building-blocks/tasks/loops/loops3-download.html) to work in your own editor or in an online editor. diff --git a/files/en-us/learn_web_development/core/scripting/test_your_skills/math/index.md b/files/en-us/learn_web_development/core/scripting/test_your_skills/math/index.md new file mode 100644 index 000000000000000..002f90d13d89611 --- /dev/null +++ b/files/en-us/learn_web_development/core/scripting/test_your_skills/math/index.md @@ -0,0 +1,69 @@ +--- +title: "Test your skills: Math" +short-title: Math +slug: Learn_web_development/Core/Scripting/Test_your_skills/Math +page-type: learn-module-assessment +sidebar: learnsidebar +--- + +The aim of the tests on this page is to assess whether you've understood the [Basic math in JavaScript — numbers and operators](/en-US/docs/Learn_web_development/Core/Scripting/Math) article. + +> [!NOTE] +> You can try solutions in the interactive editors on this page or in an online editor such as [CodePen](https://codepen.io/), [JSFiddle](https://jsfiddle.net/), or [Glitch](https://glitch.com/). +> If there is an error in your code, it will be logged into the results panel on this page or in the JavaScript console. +> +> If you get stuck, you can reach out to us in one of our [communication channels](/en-US/docs/MDN/Community/Communication_channels). + +## Math 1 + +Let's start out by testing your knowledge of basic math operators. +You will create four numeric values, add two together, subtract one from another, then multiply the results. +Finally, we need to write a check that proves that this value is an even number. + +Try updating the live code below to recreate the finished example by following these steps: + +1. Create four variables that contain numbers. Call the variables something sensible. +2. Add the first two variables together and store the result in another variable. +3. Subtract the fourth variable from the third and store the result in another variable. +4. Multiply the results from steps **2** and **3** and store the result in a variable called `finalResult`. +5. Check if `finalResult` is an even number using one of the [arithmetic operators](/en-US/docs/Learn_web_development/Core/Scripting/Math#arithmetic_operators). Store the result (`0` for even, `1` for odd) in a variable called `evenOddResult`. + +To pass this test, `finalResult` should have a value of `48` and `evenOddResult` should have a value of `0`. + +{{EmbedGHLiveSample("learning-area/javascript/introduction-to-js-1/tasks/math/math1.html", '100%', 400)}} + +> [!CALLOUT] +> +> [Download the starting point for this task](https://github.com/mdn/learning-area/blob/main/javascript/introduction-to-js-1/tasks/math/math1-download.html) to work in your own editor or in an online editor. + +## Math 2 + +In the second task, you are provided with two calculations with the results stored in the variables `result` and `result2`. +You need to take the calculations, multiply them, and format the result to two decimal places. + +Try updating the live code below to recreate the finished example by following these steps: + +1. Multiply `result` and `result2` and assign the result back to `result` (use assignment shorthand). +2. Format `result` so that it has two decimal places and store it in a variable called `finalResult`. +3. Check the data type of `finalResult` using `typeof`. If it's a `string`, convert it to a `number` type and store the result in a variable called `finalNumber`. + +To pass this test, `finalNumber` should have a result of `4633.33`. + +{{EmbedGHLiveSample("learning-area/javascript/introduction-to-js-1/tasks/math/math2.html", '100%', 400)}} + +> [!CALLOUT] +> +> [Download the starting point for this task](https://github.com/mdn/learning-area/blob/main/javascript/introduction-to-js-1/tasks/math/math2-download.html) to work in your own editor or in an online editor. + +## Math 3 + +In the final task for this article, we want you to write some tests. +There are three groups, each consisting of a statement and two variables. +For each one, write a test that proves or disproves the statement made. +Store the results of those tests in variables called `weightComparison`, `heightComparison`, and `pwdMatch`, respectively. + +{{EmbedGHLiveSample("learning-area/javascript/introduction-to-js-1/tasks/math/math3.html", '100%', 550)}} + +> [!CALLOUT] +> +> [Download the starting point for this task](https://github.com/mdn/learning-area/blob/main/javascript/introduction-to-js-1/tasks/math/math3-download.html) to work in your own editor or in an online editor. diff --git a/files/en-us/learn_web_development/core/scripting/test_your_skills/object_basics/index.md b/files/en-us/learn_web_development/core/scripting/test_your_skills/object_basics/index.md new file mode 100644 index 000000000000000..2e618c77b11e344 --- /dev/null +++ b/files/en-us/learn_web_development/core/scripting/test_your_skills/object_basics/index.md @@ -0,0 +1,88 @@ +--- +title: "Test your skills: Object basics" +short-title: Objects +slug: Learn_web_development/Core/Scripting/Test_your_skills/Object_basics +page-type: learn-module-assessment +sidebar: learnsidebar +--- + +The aim of this skill test is to assess whether you've understood our [JavaScript object basics](/en-US/docs/Learn_web_development/Core/Scripting/Object_basics) article. + +> [!NOTE] +> You can try solutions in the interactive editors on this page or in an online editor such as [CodePen](https://codepen.io/), [JSFiddle](https://jsfiddle.net/), or [Glitch](https://glitch.com/). +> If there is an error in your code, it will be logged into the results panel on this page or in the JavaScript console. +> +> If you get stuck, you can reach out to us in one of our [communication channels](/en-US/docs/MDN/Community/Communication_channels). + +## Object basics 1 + +In this task you are provided with an object literal, and your tasks are to + +- Store the value of the `name` property inside the `catName` variable, using bracket notation. +- Run the `greeting()` method using dot notation (it will log the greeting to the browser's console). +- Update the `color` property value to `black`. + +Try updating the live code below to recreate the finished example: + +{{EmbedGHLiveSample("learning-area/javascript/oojs/tasks/object-basics/object-basics1.html", '100%', 400)}} + +> [!CALLOUT] +> +> [Download the starting point for this task](https://github.com/mdn/learning-area/blob/main/javascript/oojs/tasks/object-basics/object-basics1-download.html) to work in your own editor or in an online editor. + +## Object basics 2 + +In our next task, we want you to have a go at creating your own object literal to represent one of your favorite bands. The required properties are: + +- `name`: A string representing the band name. +- `nationality`: A string representing the country the band comes from. +- `genre`: What type of music the band plays. +- `members`: A number representing the number of members the band has. +- `formed`: A number representing the year the band formed. +- `split`: A number representing the year the band split up, or `false` if they are still together. +- `albums`: An array representing the albums released by the band. Each array item should be an object containing the following members: + + - `name`: A string representing the name of the album. + - `released`: A number representing the year the album was released. + +Include at least two albums in the `albums` array. + +Once you've done this, you should then write a string to the variable `bandInfo`, which will contain a small biography detailing their name, nationality, years active, and style, and the title and release date of their first album. + +Try updating the live code below to recreate the finished example: + +{{EmbedGHLiveSample("learning-area/javascript/oojs/tasks/object-basics/object-basics2.html", '100%', 400)}} + +> [!CALLOUT] +> +> [Download the starting point for this task](https://github.com/mdn/learning-area/blob/main/javascript/oojs/tasks/object-basics/object-basics2-download.html) to work in your own editor or in an online editor. + +## Object basics 3 + +In this task, we want you to return to the `cat` object literal from Task 1. We want you to rewrite the `greeting()` method so that it logs `"Hello, said Bertie the Cymric."` to the browser's console, but in a way that will work across _any_ cat object of the same structure, regardless of its name or breed. + +When you are done, write your own object called `cat2`, which has the same structure, exactly the same `greeting()` method, but a different `name`, `breed`, and `color`. + +Call both `greeting()` methods to check that they log appropriate greetings to the console. + +Try updating the live code below to recreate the finished example: + +{{EmbedGHLiveSample("learning-area/javascript/oojs/tasks/object-basics/object-basics3.html", '100%', 400)}} + +> [!CALLOUT] +> +> [Download the starting point for this task](https://github.com/mdn/learning-area/blob/main/javascript/oojs/tasks/object-basics/object-basics3-download.html) to work in your own editor or in an online editor. + +## Object basics 4 + +In the code you wrote for Task 3, the `greeting()` method is defined twice, once for each cat. This isn't ideal (specifically, it violates a principle in programming sometimes called [DRY](https://en.wikipedia.org/wiki/Don%27t_repeat_yourself) or "Don't Repeat Yourself"). + +In this task we want you to improve the code so `greeting()` is only defined once, and every `cat` instance gets its own `greeting()` method. Hint: you should use a JavaScript constructor to create `cat` instances. + +Try updating the live code below to recreate the finished example: + +{{EmbedGHLiveSample("learning-area/javascript/oojs/tasks/object-basics/object-basics4.html", '100%', 400)}} + +> [!CALLOUT] +> +> [Download the starting point for this task](https://github.com/mdn/learning-area/blob/main/javascript/oojs/tasks/object-basics/object-basics4-download.html) to work in your own editor or in an online editor. diff --git a/files/en-us/learn_web_development/core/scripting/test_your_skills/strings/index.md b/files/en-us/learn_web_development/core/scripting/test_your_skills/strings/index.md new file mode 100644 index 000000000000000..afdfa76f4de3b41 --- /dev/null +++ b/files/en-us/learn_web_development/core/scripting/test_your_skills/strings/index.md @@ -0,0 +1,85 @@ +--- +title: "Test your skills: Strings" +short-title: Strings +slug: Learn_web_development/Core/Scripting/Test_your_skills/Strings +page-type: learn-module-assessment +sidebar: learnsidebar +--- + +The aim of this skill test is to assess whether you've understood our [Handling text — strings in JavaScript](/en-US/docs/Learn_web_development/Core/Scripting/Strings) and [Useful string methods](/en-US/docs/Learn_web_development/Core/Scripting/Useful_string_methods) articles. + +> [!NOTE] +> You can try solutions in the interactive editors on this page or in an online editor such as [CodePen](https://codepen.io/), [JSFiddle](https://jsfiddle.net/), or [Glitch](https://glitch.com/). +> +> If you get stuck, you can reach out to us in one of our [communication channels](/en-US/docs/MDN/Community/Communication_channels). + +> [!NOTE] +> In the examples below, if there is an error in your code it will be outputted into the results panel on the page, to help you try to figure out the answer (or into the browser's JavaScript console, in the case of the downloadable version). + +## Strings 1 + +In our first strings task, we start off small. You already have half of a famous quote inside a variable called `quoteStart`; we would like you to: + +1. Look up the other half of the quote, and add it to the example inside a variable called `quoteEnd`. +2. Concatenate the two strings together to make a single string containing the complete quote. Save the result inside a variable called `finalQuote`. + +You'll find that you get an error at this point. Can you fix the problem with `quoteStart`, so that the full quote displays correctly? + +Try updating the live code below to recreate the finished example: + +{{EmbedGHLiveSample("learning-area/javascript/introduction-to-js-1/tasks/strings/strings1.html", '100%', 400)}} + +> [!CALLOUT] +> +> [Download the starting point for this task](https://github.com/mdn/learning-area/blob/main/javascript/introduction-to-js-1/tasks/strings/strings1-download.html) to work in your own editor or in an online editor. + +## Strings 2 + +In this task you are provided with two variables, `quote` and `substring`, which contain two strings. We would like you to: + +1. Retrieve the length of the quote, and store it in a variable called `quoteLength`. +2. Find the index position where `substring` appears in `quote`, and store that value in a variable called `index`. +3. Use a combination of the variables you have and available string properties/methods to trim down the original quote to "I do not like green eggs and ham.", and store it in a variable called `revisedQuote`. + +Try updating the live code below to recreate the finished example: + +{{EmbedGHLiveSample("learning-area/javascript/introduction-to-js-1/tasks/strings/strings2.html", '100%', 400)}} + +> [!CALLOUT] +> +> [Download the starting point for this task](https://github.com/mdn/learning-area/blob/main/javascript/introduction-to-js-1/tasks/strings/strings2-download.html) to work in your own editor or in an online editor. + +## Strings 3 + +In the next string task, you are given the same quote that you ended up with in the previous task, but it is somewhat broken! We want you to fix and update it, like so: + +1. Change the casing to correct sentence case (all lowercase, except for upper case first letter). Store the new quote in a variable called `fixedQuote`. +2. In `fixedQuote`, replace "green eggs and ham" with another food that you really don't like. +3. There is one more small fix to do — add a period to the end of the quote, and save the final version in a variable called `finalQuote`. + +Try updating the live code below to recreate the finished example: + +{{EmbedGHLiveSample("learning-area/javascript/introduction-to-js-1/tasks/strings/strings3.html", '100%', 400)}} + +> [!CALLOUT] +> +> [Download the starting point for this task](https://github.com/mdn/learning-area/blob/main/javascript/introduction-to-js-1/tasks/strings/strings3-download.html) to work in your own editor or in an online editor. + +## Strings 4 + +In the final string task, we have given you the name of a theorem, two numeric values, and an incomplete string (the bits that need adding are marked with asterisks (`*`)). We want you to change the value of the string as follows: + +1. Change it from a regular string literal into a template literal. +2. Replace the four asterisks with four template literal placeholders. These should be: + + 1. The name of the theorem. + 2. The two number values we have. + 3. The length of the hypotenuse of a right-angled triangle, given that the two other side lengths are the same as the two values we have. You'll need to look up how to calculate this from what you have. Do the calculation inside the placeholder. + +Try updating the live code below to recreate the finished example: + +{{EmbedGHLiveSample("learning-area/javascript/introduction-to-js-1/tasks/strings/strings4.html", '100%', 400)}} + +> [!CALLOUT] +> +> [Download the starting point for this task](https://github.com/mdn/learning-area/blob/main/javascript/introduction-to-js-1/tasks/strings/strings4-download.html) to work in your own editor or in an online editor. diff --git a/files/en-us/learn_web_development/core/scripting/test_your_skills/variables/index.md b/files/en-us/learn_web_development/core/scripting/test_your_skills/variables/index.md new file mode 100644 index 000000000000000..d6facf74b2d3ea9 --- /dev/null +++ b/files/en-us/learn_web_development/core/scripting/test_your_skills/variables/index.md @@ -0,0 +1,55 @@ +--- +title: "Test your skills: Variables" +short-title: Variables +slug: Learn_web_development/Core/Scripting/Test_your_skills/Variables +page-type: learn-module-assessment +sidebar: learnsidebar +--- + +The aim of this skill test is to assess whether you've understood our [Storing the information you need — Variables](/en-US/docs/Learn_web_development/Core/Scripting/Variables) article. + +> [!NOTE] +> You can try solutions in the interactive editors on this page or in an online editor such as [CodePen](https://codepen.io/), [JSFiddle](https://jsfiddle.net/), or [Glitch](https://glitch.com/). +> If there is an error in your code, it will be logged into the results panel on this page or in the JavaScript console. +> +> If you get stuck, you can reach out to us in one of our [communication channels](/en-US/docs/MDN/Community/Communication_channels). + +## Variables 1 + +In this task we want you to: + +- Declare a variable called `myName`. +- Initialize `myName` with a suitable value, on a separate line (you can use your actual name, or something else). +- Declare a variable called `myAge` and initialize it with a value, on the same line. + +Try updating the live code below to recreate the finished example: + +{{EmbedGHLiveSample("learning-area/javascript/introduction-to-js-1/tasks/variables/variables1.html", '100%', 400)}} + +> [!CALLOUT] +> +> [Download the starting point for this task](https://github.com/mdn/learning-area/blob/main/javascript/introduction-to-js-1/tasks/variables/variables1-download.html) to work in your own editor or in an online editor. + +## Variables 2 + +In this task you need to add a new line to correct the value stored in the existing `myName` variable to your own name. + +Try updating the live code below to recreate the finished example: + +{{EmbedGHLiveSample("learning-area/javascript/introduction-to-js-1/tasks/variables/variables2.html", '100%', 400)}} + +> [!CALLOUT] +> +> [Download the starting point for this task](https://github.com/mdn/learning-area/blob/main/javascript/introduction-to-js-1/tasks/variables/variables2-download.html) to work in your own editor or in an online editor. + +## Variables 3 + +The final task for now — in this case you are provided with some existing code, which has two errors present in it. The results panel should be outputting the name `Chris`, and a statement about how old Chris will be in 20 years' time. How can you fix the problem and correct the output? + +Try updating the live code below to recreate the finished example: + +{{EmbedGHLiveSample("learning-area/javascript/introduction-to-js-1/tasks/variables/variables3.html", '100%', 400)}} + +> [!CALLOUT] +> +> [Download the starting point for this task](https://github.com/mdn/learning-area/blob/main/javascript/introduction-to-js-1/tasks/variables/variables3-download.html) to work in your own editor or in an online editor. diff --git a/files/en-us/learn_web_development/core/scripting/test_your_skills_colon__arrays/index.md b/files/en-us/learn_web_development/core/scripting/test_your_skills_colon__arrays/index.md deleted file mode 100644 index f2293b3073656ed..000000000000000 --- a/files/en-us/learn_web_development/core/scripting/test_your_skills_colon__arrays/index.md +++ /dev/null @@ -1,76 +0,0 @@ ---- -title: "Test your skills: Arrays" -slug: Learn_web_development/Core/Scripting/Test_your_skills:_Arrays -page-type: learn-module-assessment ---- - -{{learnsidebar}} - -The aim of this skill test is to assess whether you've understood our [Arrays](/en-US/docs/Learn_web_development/Core/Scripting/Arrays) article. - -> [!NOTE] -> You can try solutions in the interactive editors on this page or in an online editor such as [CodePen](https://codepen.io/), [JSFiddle](https://jsfiddle.net/), or [Glitch](https://glitch.com/). -> -> If you get stuck, you can reach out to us in one of our [communication channels](/en-US/docs/MDN/Community/Communication_channels). - -## Arrays 1 - -Let's start off with some basic array practice. In this task we'd like you to create an array of three items, stored inside a variable called `myArray`. The items can be anything you want — how about your favorite foods or bands? - -Next, modify the first two items in the array using simple bracket notation and assignment. Then add a new item to the beginning of the array. - -Try updating the live code below to recreate the finished example: - -{{EmbedGHLiveSample("learning-area/javascript/introduction-to-js-1/tasks/arrays/arrays1.html", '100%', 400)}} - -> [!CALLOUT] -> -> [Download the starting point for this task](https://github.com/mdn/learning-area/blob/main/javascript/introduction-to-js-1/tasks/arrays/arrays1-download.html) to work in your own editor or in an online editor. - -## Arrays 2 - -Now let's move on to another task. Here you are provided with a string to work with. We'd like you to: - -1. Convert the string into an array, removing the `+` characters in the process. Save the result in a variable called `myArray`. -2. Store the length of the array in a variable called `arrayLength`. -3. Store the last item in the array in a variable called `lastItem`. - -Try updating the live code below to recreate the finished example: - -{{EmbedGHLiveSample("learning-area/javascript/introduction-to-js-1/tasks/arrays/arrays2.html", '100%', 400)}} - -> [!CALLOUT] -> -> [Download the starting point for this task](https://github.com/mdn/learning-area/blob/main/javascript/introduction-to-js-1/tasks/arrays/arrays2-download.html) to work in your own editor or in an online editor. - -## Arrays 3 - -For this array task, we provide you with a starting array, and you will work in somewhat the opposite direction. You need to: - -1. Remove the last item in the array. -2. Add two new names to the end of the array. -3. Go over each item in the array and add its index number after the name inside parentheses, for example `Ryu (0)`. Note that we don't teach how to do this in the Arrays article, so you'll have to do some research. -4. Finally, join the array items together in a single string called `myString`, with a separator of `"-"`. - -Try updating the live code below to recreate the finished example: - -{{EmbedGHLiveSample("learning-area/javascript/introduction-to-js-1/tasks/arrays/arrays3.html", '100%', 400)}} - -> [!CALLOUT] -> -> [Download the starting point for this task](https://github.com/mdn/learning-area/blob/main/javascript/introduction-to-js-1/tasks/arrays/arrays3-download.html) to work in your own editor or in an online editor. - -## Arrays 4 - -For this array task, we provide you with a starting array listing the names of some birds. - -- Find the index of the `"Eagles"` item, and use that to remove the `"Eagles"` item. -- Make a new array from this one, called `eBirds`, that contains only birds from the original array whose names begin with the letter "E". Note that {{jsxref("String.prototype.startsWith()", "startsWith()")}} is a great way to check whether a string starts with a given character. - -If it works, you should see `"Emus,Egrets"` appear in the page. - -{{EmbedGHLiveSample("learning-area/javascript/introduction-to-js-1/tasks/arrays/arrays4.html", '100%', 400)}} - -> [!CALLOUT] -> -> [Download the starting point for this task](https://github.com/mdn/learning-area/blob/main/javascript/introduction-to-js-1/tasks/arrays/arrays4-download.html) to work in your own editor or in an online editor. diff --git a/files/en-us/learn_web_development/core/scripting/test_your_skills_colon__conditionals/index.md b/files/en-us/learn_web_development/core/scripting/test_your_skills_colon__conditionals/index.md deleted file mode 100644 index e531aa108d87676..000000000000000 --- a/files/en-us/learn_web_development/core/scripting/test_your_skills_colon__conditionals/index.md +++ /dev/null @@ -1,83 +0,0 @@ ---- -title: "Test your skills: Conditionals" -slug: Learn_web_development/Core/Scripting/Test_your_skills:_Conditionals -page-type: learn-module-assessment ---- - -{{learnsidebar}} - -The aim of this skill test is to assess whether you've understood our [Making decisions in your code — conditionals](/en-US/docs/Learn_web_development/Core/Scripting/Conditionals) article. - -> [!NOTE] -> You can try solutions by downloading the code and putting it in an online editor such as [CodePen](https://codepen.io/), [JSFiddle](https://jsfiddle.net/), or [Glitch](https://glitch.com/). -> If there is an error, it will be logged in the results panel on the page or into the browser's JavaScript console to help you. -> -> If you get stuck, you can reach out to us in one of our [communication channels](/en-US/docs/MDN/Community/Communication_channels). - -## Conditionals 1 - -In this task you are provided with two variables: - -- `season` — contains a string that says what the current season is. -- `response` — begins uninitialized, but is later used to store a response that will be printed to the output panel. - -We want you to create a conditional that checks whether `season` contains the string "summer", and if so assigns a string to `response` that gives the user an appropriate message about the season. If not, it should assign a generic string to `response` that tells the user we don't know what season it is. - -To finish off, you should then add another test that checks whether `season` contains the string "winter", and again assigns an appropriate string to `response`. - -Try updating the live code below to recreate the finished example: - -{{EmbedGHLiveSample("learning-area/javascript/building-blocks/tasks/conditionals/conditionals1.html", '100%', 400)}} - -> [!CALLOUT] -> -> [Download the starting point for this task](https://github.com/mdn/learning-area/blob/main/javascript/building-blocks/tasks/conditionals/conditionals1-download.html) to work in your own editor or in an online editor. - -## Conditionals 2 - -For this task you are given three variables: - -- `machineActive` — contains an indicator of whether the answer machine is switched on or not (`true`/`false`) -- `score` — Contains your score in an imaginary game. This score is fed into the answer machine, which provides a response to indicate how well you did. -- `response` — begins uninitialized, but is later used to store a response that will be printed to the output panel. - -You need to create an `if...else` structure that checks whether the machine is switched on and puts a message into the `response` variable if it isn't, telling the user to switch the machine on. - -Inside the first `if...else`, you need to nest another `if...else` that puts appropriate messages into the `response` variable depending on what the value of score is — if the machine is turned on. The different conditional tests (and resulting responses) are as follows: - -- Score of less than 0 or more than 100 — "This is not possible, an error has occurred." -- Score of 0 to 19 — "That was a terrible score — total fail!" -- Score of 20 to 39 — "You know some things, but it\\'s a pretty bad score. Needs improvement." -- Score of 40 to 69 — "You did a passable job, not bad!" -- Score of 70 to 89 — "That\\'s a great score, you really know your stuff." -- Score of 90 to 100 — "What an amazing score! Did you cheat? Are you for real?" - -Try updating the live code below to recreate the finished example. After you've entered your code, try changing `machineActive` to `true`, to see if it works. -Please note that, for the scope of this exercise, the `Your score is __` statement will remain on the screen regardless of the `machineActive`'s value. - -{{EmbedGHLiveSample("learning-area/javascript/building-blocks/tasks/conditionals/conditionals2.html", '100%', 400)}} - -> [!CALLOUT] -> -> [Download the starting point for this task](https://github.com/mdn/learning-area/blob/main/javascript/building-blocks/tasks/conditionals/conditionals2-download.html) to work in your own editor or in an online editor. - -## Conditionals 3 - -For the final task you are given four variables: - -- `machineActive` — contains an indicator of whether the login machine is switched on or not (`true`/`false`). -- `pwd` — Contains the user's login password. -- `machineResult` — begins uninitialized, but is later used to store a response that will be printed to the output panel, letting the user know whether the machine is switched on. -- `pwdResult` — begins uninitialized, but is later used to store a response that will be printed to the output panel, letting the user know whether their login attempt was successful. - -We'd like you to create an `if...else` structure that checks whether the machine is switched on and puts a message into the `machineResult` variable telling the user whether it is on or off. - -If the machine is on, we also want a second conditional to run that checks whether the `pwd` is equal to `cheese`. If so, it should assign a string to `pwdResult` telling the user they logged in successfully. If not, it should assign a different string to `pwdResult` telling the user their login attempt was not successful. We'd like you to do this in a single line, using something that isn't an `if...else` structure. - -Try updating the live code below to recreate the finished example: - -{{EmbedGHLiveSample("learning-area/javascript/building-blocks/tasks/conditionals/conditionals3.html", '100%', 400)}} - -> [!CALLOUT] -> -> [Download the starting point for this task](https://github.com/mdn/learning-area/blob/main/javascript/building-blocks/tasks/conditionals/conditionals3-download.html) to work in your own editor or in an online editor. diff --git a/files/en-us/learn_web_development/core/scripting/test_your_skills_colon__events/index.md b/files/en-us/learn_web_development/core/scripting/test_your_skills_colon__events/index.md deleted file mode 100644 index 29ca31c720c736d..000000000000000 --- a/files/en-us/learn_web_development/core/scripting/test_your_skills_colon__events/index.md +++ /dev/null @@ -1,65 +0,0 @@ ---- -title: "Test your skills: Events" -slug: Learn_web_development/Core/Scripting/Test_your_skills:_Events -page-type: learn-module-assessment ---- - -{{learnsidebar}} - -The aim of this skill test is to assess whether you've understood our [Introduction to events](/en-US/docs/Learn_web_development/Core/Scripting/Events) article. - -> [!NOTE] -> You can try solutions by downloading the code and putting it in an online editor such as [CodePen](https://codepen.io/), [JSFiddle](https://jsfiddle.net/), or [Glitch](https://glitch.com/). -> If there is an error, it will be logged in the results panel on the page or into the browser's JavaScript console to help you. -> -> If you get stuck, you can reach out to us in one of our [communication channels](/en-US/docs/MDN/Community/Communication_channels). - -## DOM manipulation: considered useful - -Some of the questions below require you to write some [DOM](/en-US/docs/Glossary/DOM) manipulation code to complete them — such as creating new HTML elements, setting their text contents to equal specific string values, and nesting them inside existing elements on the page — all via JavaScript. - -We haven't explicitly taught this yet in the course, but you'll have seen some examples that make use of it, and we'd like you to do some research into what DOM APIs you need to successfully answer the questions. A good starting place is our [DOM scripting introduction](/en-US/docs/Learn_web_development/Core/Scripting/DOM_scripting) tutorial. - -## Events 1 - -In our first events-related task, you need to create an event handler that causes the text inside the button (`btn`) to change when it is clicked on, and change back when it is clicked again. - -The HTML should not be changed; just the JavaScript. - -Try updating the live code below to recreate the finished example: - -{{EmbedGHLiveSample("learning-area/javascript/building-blocks/tasks/events/events1.html", '100%', 400)}} - -> [!CALLOUT] -> -> [Download the starting point for this task](https://github.com/mdn/learning-area/blob/main/javascript/building-blocks/tasks/events/events1-download.html) to work in your own editor or in an online editor. - -## Events 2 - -Now we'll look at keyboard events. To pass this assessment you need to build an event handler that moves the circle around the provided canvas when the WASD keys are pressed on the keyboard. The circle is drawn with the function `drawCircle()`, which takes the following parameters as inputs: - -- `x` — the x coordinate of the circle. -- `y` — the y coordinate of the circle. -- `size` — the radius of the circle. - -Try updating the live code below to recreate the finished example: - -{{EmbedGHLiveSample("learning-area/javascript/building-blocks/tasks/events/events2.html", '100%', 650)}} - -> [!CALLOUT] -> -> [Download the starting point for this task](https://github.com/mdn/learning-area/blob/main/javascript/building-blocks/tasks/events/events2-download.html) to work in your own editor or in an online editor. - -## Events 3 - -In the next events-related task, you need to set an event listener on the `<button>`s' parent element (`<div class="button-bar"> … </div>`), which when invoked by clicking any of the buttons will set the background of the `button-bar` to the color contained in the button's `data-color` attribute. - -We want you to solve this without looping through all the buttons and giving each one their own event listener. - -Try updating the live code below to recreate the finished example: - -{{EmbedGHLiveSample("learning-area/javascript/building-blocks/tasks/events/events3.html", '100%', 600)}} - -> [!CALLOUT] -> -> [Download the starting point for this task](https://github.com/mdn/learning-area/blob/main/javascript/building-blocks/tasks/events/events3-download.html) to work in your own editor or in an online editor. diff --git a/files/en-us/learn_web_development/core/scripting/test_your_skills_colon__functions/index.md b/files/en-us/learn_web_development/core/scripting/test_your_skills_colon__functions/index.md deleted file mode 100644 index 9bbfcf7c22813d3..000000000000000 --- a/files/en-us/learn_web_development/core/scripting/test_your_skills_colon__functions/index.md +++ /dev/null @@ -1,81 +0,0 @@ ---- -title: "Test your skills: Functions" -slug: Learn_web_development/Core/Scripting/Test_your_skills:_Functions -page-type: learn-module-assessment ---- - -{{learnsidebar}} - -The aim of this skill test is to assess whether you've understood our [Functions — reusable blocks of code](/en-US/docs/Learn_web_development/Core/Scripting/Functions), [Build your own function](/en-US/docs/Learn_web_development/Core/Scripting/Build_your_own_function), and [Function return values](/en-US/docs/Learn_web_development/Core/Scripting/Return_values) articles. - -> [!NOTE] -> You can try solutions by downloading the code and putting it in an online editor such as [CodePen](https://codepen.io/), [JSFiddle](https://jsfiddle.net/), or [Glitch](https://glitch.com/). -> If there is an error, it will be logged in the results panel on the page or into the browser's JavaScript console to help you. -> -> If you get stuck, you can reach out to us in one of our [communication channels](/en-US/docs/MDN/Community/Communication_channels). - -## DOM manipulation: considered useful - -Some of the questions below require you to write some [DOM](/en-US/docs/Glossary/DOM) manipulation code to complete them — such as creating new HTML elements, setting their text contents to equal specific string values, and nesting them inside existing elements on the page — all via JavaScript. - -We haven't explicitly taught this yet in the course, but you'll have seen some examples that make use of it, and we'd like you to do some research into what DOM APIs you need to successfully answer the questions. A good starting place is our [DOM scripting introduction](/en-US/docs/Learn_web_development/Core/Scripting/DOM_scripting) tutorial. - -## Functions 1 - -For the first task, you have to create a simple function — `chooseName()` — that prints a random name from the provided array (`names`) to the provided paragraph (`para`), and then run it once. - -Try updating the live code below to recreate the finished example: - -{{EmbedGHLiveSample("learning-area/javascript/building-blocks/tasks/functions/functions1.html", '100%', 400)}} - -> [!CALLOUT] -> -> [Download the starting point for this task](https://github.com/mdn/learning-area/blob/main/javascript/building-blocks/tasks/functions/functions1-download.html) to work in your own editor or in an online editor. - -## Functions 2 - -For our second functions-related task, you need to create a function that draws a rectangle on the provided `<canvas>` (reference variable `canvas`, context available in `ctx`), based on the five provided input variables: - -- `x` — the x coordinate of the rectangle. -- `y` — the y coordinate of the rectangle. -- `width` — the width of the rectangle. -- `height` — the height of the rectangle. -- `color` — the color of the rectangle. - -You'll want to clear the canvas before drawing, so that when the code is updated in the case of the live version, you don't get lots of rectangles drawn on top of one another. - -Try updating the live code below to recreate the finished example: - -{{EmbedGHLiveSample("learning-area/javascript/building-blocks/tasks/functions/functions2.html", '100%', 700)}} - -> [!CALLOUT] -> -> [Download the starting point for this task](https://github.com/mdn/learning-area/blob/main/javascript/building-blocks/tasks/functions/functions2-download.html) to work in your own editor or in an online editor. - -## Functions 3 - -In this task, you return to the problem posed in Task 1, with the aim of improving it. The three improvements we want you to make are: - -1. Refactor the code that generates the random number into a separate function called `random()`, which takes as parameters two generic bounds that the random number should be between, and returns the result. -2. Update the `chooseName()` function so that it makes use of the random number function, takes the array to choose from as a parameter (making it more flexible), and returns the result. -3. Print the returned result into the paragraph (`para`)'s `textContent`. - -Try updating the live code below to recreate the finished example: - -{{EmbedGHLiveSample("learning-area/javascript/building-blocks/tasks/functions/functions3.html", '100%', 400)}} - -> [!CALLOUT] -> -> [Download the starting point for this task](https://github.com/mdn/learning-area/blob/main/javascript/building-blocks/tasks/functions/functions3-download.html) to work in your own editor or in an online editor. - -## Functions 4 - -In this task, we have an array of names, and we're using {{jsxref("Array.filter()")}} to get an array of only names shorter than 5 characters. The filter is currently being passed a named function `isShort()` which checks the length of the name, returning `true` if the name is less than 5 characters long, and `false` otherwise. - -We'd like you to change this into an arrow function. See how compact you can make it. - -{{EmbedGHLiveSample("learning-area/javascript/building-blocks/tasks/functions/functions4.html", '100%', 400)}} - -> [!CALLOUT] -> -> [Download the starting point for this task](https://github.com/mdn/learning-area/blob/main/javascript/building-blocks/tasks/functions/functions4-download.html) to work in your own editor or in an online editor. diff --git a/files/en-us/learn_web_development/core/scripting/test_your_skills_colon__json/index.md b/files/en-us/learn_web_development/core/scripting/test_your_skills_colon__json/index.md deleted file mode 100644 index 84aa1322e9551c6..000000000000000 --- a/files/en-us/learn_web_development/core/scripting/test_your_skills_colon__json/index.md +++ /dev/null @@ -1,39 +0,0 @@ ---- -title: "Test your skills: JSON" -slug: Learn_web_development/Core/Scripting/Test_your_skills:_JSON -page-type: learn-module-assessment ---- - -{{learnsidebar}} - -The aim of this skill test is to assess whether you've understood our [Working with JSON](/en-US/docs/Learn_web_development/Core/Scripting/JSON) article. - -> [!NOTE] -> You can try solutions by downloading the code and putting it in an online editor such as [CodePen](https://codepen.io/), [JSFiddle](https://jsfiddle.net/), or [Glitch](https://glitch.com/). -> If there is an error, it will be logged in the results panel on the page or into the browser's JavaScript console to help you. -> -> If you get stuck, you can reach out to us in one of our [communication channels](/en-US/docs/MDN/Community/Communication_channels). - -## JSON 1 - -The one and only task in this article concerns accessing JSON data and using it in your page. JSON data about some mother cats and their kittens is available in [sample.json](https://github.com/mdn/learning-area/blob/main/javascript/oojs/tasks/json/sample.json). The JSON is loaded into the page as a text string and made available in the `catString` parameter of the `displayCatInfo()` function. Your task is to fill in the missing parts of the `displayCatInfo()` function to store: - -- The names of the three mother cats, separated by commas, in the `motherInfo` variable. -- The total number of kittens, and how many are male and female, in the `kittenInfo` variable. - -The values of these variables are then printed to the screen inside paragraphs. - -Some hints/questions: - -- The JSON data is provided as text inside the `displayCatInfo()` function. You'll need to parse it into JSON before you can get any data out of it. -- You'll probably want to use an outer loop to loop through the cats and add their names to the `motherInfo` variable string, and an inner loop to loop through all the kittens, add up the total of all/male/female kittens, and add those details to the `kittenInfo` variable string. -- The last mother cat name should have an "and" before it, and a full stop after it. How do you make sure this can work, no matter how many cats are in the JSON? -- Why are the `para1.textContent = motherInfo;` and `para2.textContent = kittenInfo;` lines inside the `displayCatInfo()` function, and not at the end of the script? This has something to do with async code. - -Try updating the live code below to recreate the finished example: - -{{EmbedGHLiveSample("learning-area/javascript/oojs/tasks/json/json1.html", '100%', 400)}} - -> [!CALLOUT] -> -> [Download the starting point for this task](https://github.com/mdn/learning-area/blob/main/javascript/oojs/tasks/json/json1-download.html) to work in your own editor or in an online editor. diff --git a/files/en-us/learn_web_development/core/scripting/test_your_skills_colon__loops/index.md b/files/en-us/learn_web_development/core/scripting/test_your_skills_colon__loops/index.md deleted file mode 100644 index ff4e29559364350..000000000000000 --- a/files/en-us/learn_web_development/core/scripting/test_your_skills_colon__loops/index.md +++ /dev/null @@ -1,62 +0,0 @@ ---- -title: "Test your skills: Loops" -slug: Learn_web_development/Core/Scripting/Test_your_skills:_Loops -page-type: learn-module-assessment ---- - -{{learnsidebar}} - -The aim of this skill test is to assess whether you've understood our [Looping code](/en-US/docs/Learn_web_development/Core/Scripting/Loops) article. - -> [!NOTE] -> You can try solutions by downloading the code and putting it in an online editor such as [CodePen](https://codepen.io/), [JSFiddle](https://jsfiddle.net/), or [Glitch](https://glitch.com/). -> -> If you get stuck, you can reach out to us in one of our [communication channels](/en-US/docs/MDN/Community/Communication_channels). - -## DOM manipulation: considered useful - -Some of the questions below require you to write some [DOM](/en-US/docs/Glossary/DOM) manipulation code to complete them — such as creating new HTML elements, setting their text contents to equal specific string values, and nesting them inside existing elements on the page — all via JavaScript. - -We haven't explicitly taught this yet in the course, but you'll have seen some examples that make use of it, and we'd like you to do some research into what DOM APIs you need to successfully answer the questions. A good starting place is our [DOM scripting introduction](/en-US/docs/Learn_web_development/Core/Scripting/DOM_scripting) tutorial. - -## Loops 1 - -In our first looping task we want you to start by creating a simple loop that goes through all the items in the provided `myArray` and prints them out on the screen inside list items (i.e., [`<li>`](/en-US/docs/Web/HTML/Element/li) elements), which are appended to the provided `list`. - -> [!CALLOUT] -> -> [Download the starting point for this task](https://github.com/mdn/learning-area/blob/main/javascript/building-blocks/tasks/loops/loops1-download.html) to work in your own editor or in an online editor. - -## Loops 2 - -In this next task, we want you to write a simple program that, given a name, searches an array of [objects](/en-US/docs/Glossary/Object) containing names and phone numbers (`phonebook`) and, if it finds the name, outputs the name and phone number into the paragraph (`para`) and then exits the loop before it has run its course. - -If you haven't read about objects yet, don't worry! For now, all you need to know is how to access a member-value pair. You can read up on objects in the [JavaScript object basics](/en-US/docs/Learn_web_development/Core/Scripting/Object_basics) tutorial. - -You are given three variables to begin with: - -- `name` — contains a name to search for -- `para` — contains a reference to a paragraph, which will be used to report the results -- `phonebook` - contains the phonebook entries to search. - -You should use a type of loop that you've not used in the previous task. - -> [!CALLOUT] -> -> [Download the starting point for this task](https://github.com/mdn/learning-area/blob/main/javascript/building-blocks/tasks/loops/loops2-download.html) to work in your own editor or in an online editor. - -## Loops 3 - -In this final task, you are provided with the following: - -- `i` — starts off with a value of 500; intended to be used as an iterator. -- `para` — contains a reference to a paragraph, which will be used to report the results. -- `isPrime()` — a function that, when passed a number, returns `true` if the number is a prime number, and `false` if not. - -You need to use a loop to go through the numbers 2 to 500 backwards (1 is not counted as a prime number), and run the provided `isPrime()` function on them. For each number that isn't a prime number, continue on to the next loop iteration. For each one that is a prime number, add it to the paragraph's `textContent` along with some kind of separator. - -You should use a type of loop that you've not used in the previous two tasks. - -> [!CALLOUT] -> -> [Download the starting point for this task](https://github.com/mdn/learning-area/blob/main/javascript/building-blocks/tasks/loops/loops3-download.html) to work in your own editor or in an online editor. diff --git a/files/en-us/learn_web_development/core/scripting/test_your_skills_colon__math/index.md b/files/en-us/learn_web_development/core/scripting/test_your_skills_colon__math/index.md deleted file mode 100644 index c3bf7a7b0a7b00f..000000000000000 --- a/files/en-us/learn_web_development/core/scripting/test_your_skills_colon__math/index.md +++ /dev/null @@ -1,69 +0,0 @@ ---- -title: "Test your skills: Math" -slug: Learn_web_development/Core/Scripting/Test_your_skills:_Math -page-type: learn-module-assessment ---- - -{{learnsidebar}} - -The aim of the tests on this page is to assess whether you've understood the [Basic math in JavaScript — numbers and operators](/en-US/docs/Learn_web_development/Core/Scripting/Math) article. - -> [!NOTE] -> You can try solutions in the interactive editors on this page or in an online editor such as [CodePen](https://codepen.io/), [JSFiddle](https://jsfiddle.net/), or [Glitch](https://glitch.com/). -> If there is an error in your code, it will be logged into the results panel on this page or in the JavaScript console. -> -> If you get stuck, you can reach out to us in one of our [communication channels](/en-US/docs/MDN/Community/Communication_channels). - -## Math 1 - -Let's start out by testing your knowledge of basic math operators. -You will create four numeric values, add two together, subtract one from another, then multiply the results. -Finally, we need to write a check that proves that this value is an even number. - -Try updating the live code below to recreate the finished example by following these steps: - -1. Create four variables that contain numbers. Call the variables something sensible. -2. Add the first two variables together and store the result in another variable. -3. Subtract the fourth variable from the third and store the result in another variable. -4. Multiply the results from steps **2** and **3** and store the result in a variable called `finalResult`. -5. Check if `finalResult` is an even number using one of the [arithmetic operators](/en-US/docs/Learn_web_development/Core/Scripting/Math#arithmetic_operators). Store the result (`0` for even, `1` for odd) in a variable called `evenOddResult`. - -To pass this test, `finalResult` should have a value of `48` and `evenOddResult` should have a value of `0`. - -{{EmbedGHLiveSample("learning-area/javascript/introduction-to-js-1/tasks/math/math1.html", '100%', 400)}} - -> [!CALLOUT] -> -> [Download the starting point for this task](https://github.com/mdn/learning-area/blob/main/javascript/introduction-to-js-1/tasks/math/math1-download.html) to work in your own editor or in an online editor. - -## Math 2 - -In the second task, you are provided with two calculations with the results stored in the variables `result` and `result2`. -You need to take the calculations, multiply them, and format the result to two decimal places. - -Try updating the live code below to recreate the finished example by following these steps: - -1. Multiply `result` and `result2` and assign the result back to `result` (use assignment shorthand). -2. Format `result` so that it has two decimal places and store it in a variable called `finalResult`. -3. Check the data type of `finalResult` using `typeof`. If it's a `string`, convert it to a `number` type and store the result in a variable called `finalNumber`. - -To pass this test, `finalNumber` should have a result of `4633.33`. - -{{EmbedGHLiveSample("learning-area/javascript/introduction-to-js-1/tasks/math/math2.html", '100%', 400)}} - -> [!CALLOUT] -> -> [Download the starting point for this task](https://github.com/mdn/learning-area/blob/main/javascript/introduction-to-js-1/tasks/math/math2-download.html) to work in your own editor or in an online editor. - -## Math 3 - -In the final task for this article, we want you to write some tests. -There are three groups, each consisting of a statement and two variables. -For each one, write a test that proves or disproves the statement made. -Store the results of those tests in variables called `weightComparison`, `heightComparison`, and `pwdMatch`, respectively. - -{{EmbedGHLiveSample("learning-area/javascript/introduction-to-js-1/tasks/math/math3.html", '100%', 550)}} - -> [!CALLOUT] -> -> [Download the starting point for this task](https://github.com/mdn/learning-area/blob/main/javascript/introduction-to-js-1/tasks/math/math3-download.html) to work in your own editor or in an online editor. diff --git a/files/en-us/learn_web_development/core/scripting/test_your_skills_colon__object_basics/index.md b/files/en-us/learn_web_development/core/scripting/test_your_skills_colon__object_basics/index.md deleted file mode 100644 index 9fffa1b0e8db305..000000000000000 --- a/files/en-us/learn_web_development/core/scripting/test_your_skills_colon__object_basics/index.md +++ /dev/null @@ -1,88 +0,0 @@ ---- -title: "Test your skills: Object basics" -slug: Learn_web_development/Core/Scripting/Test_your_skills:_Object_basics -page-type: learn-module-assessment ---- - -{{learnsidebar}} - -The aim of this skill test is to assess whether you've understood our [JavaScript object basics](/en-US/docs/Learn_web_development/Core/Scripting/Object_basics) article. - -> [!NOTE] -> You can try solutions in the interactive editors on this page or in an online editor such as [CodePen](https://codepen.io/), [JSFiddle](https://jsfiddle.net/), or [Glitch](https://glitch.com/). -> If there is an error in your code, it will be logged into the results panel on this page or in the JavaScript console. -> -> If you get stuck, you can reach out to us in one of our [communication channels](/en-US/docs/MDN/Community/Communication_channels). - -## Object basics 1 - -In this task you are provided with an object literal, and your tasks are to - -- Store the value of the `name` property inside the `catName` variable, using bracket notation. -- Run the `greeting()` method using dot notation (it will log the greeting to the browser's console). -- Update the `color` property value to `black`. - -Try updating the live code below to recreate the finished example: - -{{EmbedGHLiveSample("learning-area/javascript/oojs/tasks/object-basics/object-basics1.html", '100%', 400)}} - -> [!CALLOUT] -> -> [Download the starting point for this task](https://github.com/mdn/learning-area/blob/main/javascript/oojs/tasks/object-basics/object-basics1-download.html) to work in your own editor or in an online editor. - -## Object basics 2 - -In our next task, we want you to have a go at creating your own object literal to represent one of your favorite bands. The required properties are: - -- `name`: A string representing the band name. -- `nationality`: A string representing the country the band comes from. -- `genre`: What type of music the band plays. -- `members`: A number representing the number of members the band has. -- `formed`: A number representing the year the band formed. -- `split`: A number representing the year the band split up, or `false` if they are still together. -- `albums`: An array representing the albums released by the band. Each array item should be an object containing the following members: - - - `name`: A string representing the name of the album. - - `released`: A number representing the year the album was released. - -Include at least two albums in the `albums` array. - -Once you've done this, you should then write a string to the variable `bandInfo`, which will contain a small biography detailing their name, nationality, years active, and style, and the title and release date of their first album. - -Try updating the live code below to recreate the finished example: - -{{EmbedGHLiveSample("learning-area/javascript/oojs/tasks/object-basics/object-basics2.html", '100%', 400)}} - -> [!CALLOUT] -> -> [Download the starting point for this task](https://github.com/mdn/learning-area/blob/main/javascript/oojs/tasks/object-basics/object-basics2-download.html) to work in your own editor or in an online editor. - -## Object basics 3 - -In this task, we want you to return to the `cat` object literal from Task 1. We want you to rewrite the `greeting()` method so that it logs `"Hello, said Bertie the Cymric."` to the browser's console, but in a way that will work across _any_ cat object of the same structure, regardless of its name or breed. - -When you are done, write your own object called `cat2`, which has the same structure, exactly the same `greeting()` method, but a different `name`, `breed`, and `color`. - -Call both `greeting()` methods to check that they log appropriate greetings to the console. - -Try updating the live code below to recreate the finished example: - -{{EmbedGHLiveSample("learning-area/javascript/oojs/tasks/object-basics/object-basics3.html", '100%', 400)}} - -> [!CALLOUT] -> -> [Download the starting point for this task](https://github.com/mdn/learning-area/blob/main/javascript/oojs/tasks/object-basics/object-basics3-download.html) to work in your own editor or in an online editor. - -## Object basics 4 - -In the code you wrote for Task 3, the `greeting()` method is defined twice, once for each cat. This isn't ideal (specifically, it violates a principle in programming sometimes called [DRY](https://en.wikipedia.org/wiki/Don%27t_repeat_yourself) or "Don't Repeat Yourself"). - -In this task we want you to improve the code so `greeting()` is only defined once, and every `cat` instance gets its own `greeting()` method. Hint: you should use a JavaScript constructor to create `cat` instances. - -Try updating the live code below to recreate the finished example: - -{{EmbedGHLiveSample("learning-area/javascript/oojs/tasks/object-basics/object-basics4.html", '100%', 400)}} - -> [!CALLOUT] -> -> [Download the starting point for this task](https://github.com/mdn/learning-area/blob/main/javascript/oojs/tasks/object-basics/object-basics4-download.html) to work in your own editor or in an online editor. diff --git a/files/en-us/learn_web_development/core/scripting/test_your_skills_colon__strings/index.md b/files/en-us/learn_web_development/core/scripting/test_your_skills_colon__strings/index.md deleted file mode 100644 index 67a186ea2b615ad..000000000000000 --- a/files/en-us/learn_web_development/core/scripting/test_your_skills_colon__strings/index.md +++ /dev/null @@ -1,85 +0,0 @@ ---- -title: "Test your skills: Strings" -slug: Learn_web_development/Core/Scripting/Test_your_skills:_Strings -page-type: learn-module-assessment ---- - -{{learnsidebar}} - -The aim of this skill test is to assess whether you've understood our [Handling text — strings in JavaScript](/en-US/docs/Learn_web_development/Core/Scripting/Strings) and [Useful string methods](/en-US/docs/Learn_web_development/Core/Scripting/Useful_string_methods) articles. - -> [!NOTE] -> You can try solutions in the interactive editors on this page or in an online editor such as [CodePen](https://codepen.io/), [JSFiddle](https://jsfiddle.net/), or [Glitch](https://glitch.com/). -> -> If you get stuck, you can reach out to us in one of our [communication channels](/en-US/docs/MDN/Community/Communication_channels). - -> [!NOTE] -> In the examples below, if there is an error in your code it will be outputted into the results panel on the page, to help you try to figure out the answer (or into the browser's JavaScript console, in the case of the downloadable version). - -## Strings 1 - -In our first strings task, we start off small. You already have half of a famous quote inside a variable called `quoteStart`; we would like you to: - -1. Look up the other half of the quote, and add it to the example inside a variable called `quoteEnd`. -2. Concatenate the two strings together to make a single string containing the complete quote. Save the result inside a variable called `finalQuote`. - -You'll find that you get an error at this point. Can you fix the problem with `quoteStart`, so that the full quote displays correctly? - -Try updating the live code below to recreate the finished example: - -{{EmbedGHLiveSample("learning-area/javascript/introduction-to-js-1/tasks/strings/strings1.html", '100%', 400)}} - -> [!CALLOUT] -> -> [Download the starting point for this task](https://github.com/mdn/learning-area/blob/main/javascript/introduction-to-js-1/tasks/strings/strings1-download.html) to work in your own editor or in an online editor. - -## Strings 2 - -In this task you are provided with two variables, `quote` and `substring`, which contain two strings. We would like you to: - -1. Retrieve the length of the quote, and store it in a variable called `quoteLength`. -2. Find the index position where `substring` appears in `quote`, and store that value in a variable called `index`. -3. Use a combination of the variables you have and available string properties/methods to trim down the original quote to "I do not like green eggs and ham.", and store it in a variable called `revisedQuote`. - -Try updating the live code below to recreate the finished example: - -{{EmbedGHLiveSample("learning-area/javascript/introduction-to-js-1/tasks/strings/strings2.html", '100%', 400)}} - -> [!CALLOUT] -> -> [Download the starting point for this task](https://github.com/mdn/learning-area/blob/main/javascript/introduction-to-js-1/tasks/strings/strings2-download.html) to work in your own editor or in an online editor. - -## Strings 3 - -In the next string task, you are given the same quote that you ended up with in the previous task, but it is somewhat broken! We want you to fix and update it, like so: - -1. Change the casing to correct sentence case (all lowercase, except for upper case first letter). Store the new quote in a variable called `fixedQuote`. -2. In `fixedQuote`, replace "green eggs and ham" with another food that you really don't like. -3. There is one more small fix to do — add a period to the end of the quote, and save the final version in a variable called `finalQuote`. - -Try updating the live code below to recreate the finished example: - -{{EmbedGHLiveSample("learning-area/javascript/introduction-to-js-1/tasks/strings/strings3.html", '100%', 400)}} - -> [!CALLOUT] -> -> [Download the starting point for this task](https://github.com/mdn/learning-area/blob/main/javascript/introduction-to-js-1/tasks/strings/strings3-download.html) to work in your own editor or in an online editor. - -## Strings 4 - -In the final string task, we have given you the name of a theorem, two numeric values, and an incomplete string (the bits that need adding are marked with asterisks (`*`)). We want you to change the value of the string as follows: - -1. Change it from a regular string literal into a template literal. -2. Replace the four asterisks with four template literal placeholders. These should be: - - 1. The name of the theorem. - 2. The two number values we have. - 3. The length of the hypotenuse of a right-angled triangle, given that the two other side lengths are the same as the two values we have. You'll need to look up how to calculate this from what you have. Do the calculation inside the placeholder. - -Try updating the live code below to recreate the finished example: - -{{EmbedGHLiveSample("learning-area/javascript/introduction-to-js-1/tasks/strings/strings4.html", '100%', 400)}} - -> [!CALLOUT] -> -> [Download the starting point for this task](https://github.com/mdn/learning-area/blob/main/javascript/introduction-to-js-1/tasks/strings/strings4-download.html) to work in your own editor or in an online editor. diff --git a/files/en-us/learn_web_development/core/scripting/test_your_skills_colon__variables/index.md b/files/en-us/learn_web_development/core/scripting/test_your_skills_colon__variables/index.md deleted file mode 100644 index 06b78550910523a..000000000000000 --- a/files/en-us/learn_web_development/core/scripting/test_your_skills_colon__variables/index.md +++ /dev/null @@ -1,55 +0,0 @@ ---- -title: "Test your skills: variables" -slug: Learn_web_development/Core/Scripting/Test_your_skills:_variables -page-type: learn-module-assessment ---- - -{{learnsidebar}} - -The aim of this skill test is to assess whether you've understood our [Storing the information you need — Variables](/en-US/docs/Learn_web_development/Core/Scripting/Variables) article. - -> [!NOTE] -> You can try solutions in the interactive editors on this page or in an online editor such as [CodePen](https://codepen.io/), [JSFiddle](https://jsfiddle.net/), or [Glitch](https://glitch.com/). -> If there is an error in your code, it will be logged into the results panel on this page or in the JavaScript console. -> -> If you get stuck, you can reach out to us in one of our [communication channels](/en-US/docs/MDN/Community/Communication_channels). - -## Variables 1 - -In this task we want you to: - -- Declare a variable called `myName`. -- Initialize `myName` with a suitable value, on a separate line (you can use your actual name, or something else). -- Declare a variable called `myAge` and initialize it with a value, on the same line. - -Try updating the live code below to recreate the finished example: - -{{EmbedGHLiveSample("learning-area/javascript/introduction-to-js-1/tasks/variables/variables1.html", '100%', 400)}} - -> [!CALLOUT] -> -> [Download the starting point for this task](https://github.com/mdn/learning-area/blob/main/javascript/introduction-to-js-1/tasks/variables/variables1-download.html) to work in your own editor or in an online editor. - -## Variables 2 - -In this task you need to add a new line to correct the value stored in the existing `myName` variable to your own name. - -Try updating the live code below to recreate the finished example: - -{{EmbedGHLiveSample("learning-area/javascript/introduction-to-js-1/tasks/variables/variables2.html", '100%', 400)}} - -> [!CALLOUT] -> -> [Download the starting point for this task](https://github.com/mdn/learning-area/blob/main/javascript/introduction-to-js-1/tasks/variables/variables2-download.html) to work in your own editor or in an online editor. - -## Variables 3 - -The final task for now — in this case you are provided with some existing code, which has two errors present in it. The results panel should be outputting the name `Chris`, and a statement about how old Chris will be in 20 years' time. How can you fix the problem and correct the output? - -Try updating the live code below to recreate the finished example: - -{{EmbedGHLiveSample("learning-area/javascript/introduction-to-js-1/tasks/variables/variables3.html", '100%', 400)}} - -> [!CALLOUT] -> -> [Download the starting point for this task](https://github.com/mdn/learning-area/blob/main/javascript/introduction-to-js-1/tasks/variables/variables3-download.html) to work in your own editor or in an online editor. diff --git a/files/en-us/learn_web_development/core/scripting/useful_string_methods/index.md b/files/en-us/learn_web_development/core/scripting/useful_string_methods/index.md index d99fc51b5a001e9..934148f69b92caa 100644 --- a/files/en-us/learn_web_development/core/scripting/useful_string_methods/index.md +++ b/files/en-us/learn_web_development/core/scripting/useful_string_methods/index.md @@ -1,10 +1,12 @@ --- title: Useful string methods +short-title: String methods slug: Learn_web_development/Core/Scripting/Useful_string_methods page-type: learn-module-chapter +sidebar: learnsidebar --- -{{LearnSidebar}}{{PreviousMenuNext("Learn_web_development/Core/Scripting/Strings", "Learn_web_development/Core/Scripting/Arrays", "Learn_web_development/Core/Scripting")}} +{{PreviousMenuNext("Learn_web_development/Core/Scripting/Strings", "Learn_web_development/Core/Scripting/Arrays", "Learn_web_development/Core/Scripting")}} Now that we've looked at the very basics of strings, let's move up a gear and start thinking about what useful operations we can do on strings with built-in methods, such as finding the length of a text string, joining and splitting strings, substituting one character in a string for another, and more. @@ -460,7 +462,7 @@ function updateCode() { eval(textarea.value); } -reset.addEventListener("click", function () { +reset.addEventListener("click", () => { textarea.value = code; userEntry = textarea.value; solutionEntry = jsSolution; @@ -468,7 +470,7 @@ reset.addEventListener("click", function () { updateCode(); }); -solution.addEventListener("click", function () { +solution.addEventListener("click", () => { if (solution.value === "Show solution") { textarea.value = solutionEntry; solution.value = "Hide solution"; @@ -639,7 +641,7 @@ function updateCode() { eval(textarea.value); } -reset.addEventListener("click", function () { +reset.addEventListener("click", () => { textarea.value = code; userEntry = textarea.value; solutionEntry = jsSolution; @@ -647,7 +649,7 @@ reset.addEventListener("click", function () { updateCode(); }); -solution.addEventListener("click", function () { +solution.addEventListener("click", () => { if (solution.value === "Show solution") { textarea.value = solutionEntry; solution.value = "Hide solution"; @@ -732,7 +734,7 @@ textarea.onkeyup = function () { ## Test your skills! -You've reached the end of this article, but can you remember the most important information? You can find some further tests to verify that you've retained this information before you move on — see [Test your skills: Strings](/en-US/docs/Learn_web_development/Core/Scripting/Test_your_skills:_Strings). +You've reached the end of this article, but can you remember the most important information? You can find some further tests to verify that you've retained this information before you move on — see [Test your skills: Strings](/en-US/docs/Learn_web_development/Core/Scripting/Test_your_skills/Strings). ## Conclusion diff --git a/files/en-us/learn_web_development/core/scripting/variables/index.md b/files/en-us/learn_web_development/core/scripting/variables/index.md index 01edd9a2decdae7..77d3642331a0f8e 100644 --- a/files/en-us/learn_web_development/core/scripting/variables/index.md +++ b/files/en-us/learn_web_development/core/scripting/variables/index.md @@ -1,11 +1,11 @@ --- title: Storing the information you need — Variables +short-title: Variables slug: Learn_web_development/Core/Scripting/Variables page-type: learn-module-chapter +sidebar: learnsidebar --- -{{LearnSidebar}} - {{PreviousMenuNext("Learn_web_development/Core/Scripting/What_went_wrong", "Learn_web_development/Core/Scripting/Math", "Learn_web_development/Core/Scripting")}} After reading the last couple of articles you should now know what JavaScript is, what it can do for you, how you use it alongside other web technologies, and what its main features look like from a high level. In this article, we will get down to the real basics, looking at how to work with the most basic building blocks of JavaScript — Variables. @@ -87,7 +87,7 @@ buttonB.onclick = () => { {{ EmbedLiveSample('Without_a_variable', '100%', 120) }} -You may not fully understand the syntax we are using (yet!), but you should be able to get the idea. Without a variable, we don't have a way of knowing how many times the button have been clicked. The message to the user will quickly be irrelevant when no information can be remembered. +You may not fully understand the syntax we are using (yet!), but you should be able to get the idea. Without a variable, we don't have a way of knowing how many times the button has been clicked. The message to the user will quickly be irrelevant when no information can be remembered. Variables just make sense, and as you learn more about JavaScript they will start to become second nature. @@ -371,7 +371,7 @@ Try entering the four lines above into your console one by one, and see what the As well as variables, you can declare constants. These are like variables, except that: -- you must initialize them when you declare them +- you must initialize them when you declare them. - you can't assign them a new value after you've initialized them. For example, using `let` you can declare a variable without initializing it: @@ -426,7 +426,9 @@ This means that if you can initialize a variable when you declare it, and don't ## Test your skills! -You've reached the end of this article, but can you remember the most important information? You can find some further tests to verify that you've retained this information before you move on — see [Test your skills: variables](/en-US/docs/Learn_web_development/Core/Scripting/Test_your_skills:_variables). +You've reached the end of this article, but can you remember the most important information? You can find some further tests to verify that you've retained this information before you move on — see [Test your skills: variables](/en-US/docs/Learn_web_development/Core/Scripting/Test_your_skills/Variables). + +Also check out [Practice time - Part 3: let and const](https://scrimba.com/learn-javascript-c0v/~059?via=mdn) <sup>[_MDN learning partner_](/en-US/docs/MDN/Writing_guidelines/Learning_content#partner_links_and_embeds)</sup> from Scrimba: An interactive challenge providing multiple tests concerning `let` and `const`. ## Summary diff --git a/files/en-us/learn_web_development/core/scripting/what_is_javascript/index.md b/files/en-us/learn_web_development/core/scripting/what_is_javascript/index.md index 37844dc60b22afb..df63b5cc35aa32f 100644 --- a/files/en-us/learn_web_development/core/scripting/what_is_javascript/index.md +++ b/files/en-us/learn_web_development/core/scripting/what_is_javascript/index.md @@ -2,10 +2,9 @@ title: What is JavaScript? slug: Learn_web_development/Core/Scripting/What_is_JavaScript page-type: learn-module-chapter +sidebar: learnsidebar --- -{{LearnSidebar}} - {{NextMenu("Learn_web_development/Core/Scripting/A_first_splash", "Learn_web_development/Core/Scripting")}} Welcome to the MDN beginner's JavaScript course! @@ -89,12 +88,15 @@ Try clicking on the text label to see what happens. JavaScript can do a lot more than that — let's explore what in more detail. +> [!NOTE] +> Before moving on, why not jump in and get your hands dirty with a challenge from Scrimba at this early stage? Check out [Render a welcome message](https://scrimba.com/learn-javascript-c0v/~0n?via=mdn) <sup>[_MDN learning partner_](/en-US/docs/MDN/Writing_guidelines/Learning_content#partner_links_and_embeds)</sup>. If you don't know how to write this code, don't worry at all; you could try doing some web searches to find some answers, or view the solution at the end of the scrim. + ## So what can it really do? The core client-side JavaScript language consists of some common programming features that allow you to do things like: - Store useful values inside variables. In the above example for instance, we ask for a new name to be entered then store that name in a variable called `name`. -- Operations on pieces of text (known as "strings" in programming). In the above example we take the string "Player 1: " and join it to the `name` variable to create the complete text label, e.g. "Player 1: Chris". +- Operations on pieces of text (known as "strings" in programming). In the above example we take the string "Player 1: " and join it to the `name` variable to create the complete text label, e.g., "Player 1: Chris". - Running code in response to certain events occurring on a web page. We used a {{domxref("Element/click_event", "click")}} event in our example above to detect when the label is clicked and then run the code that updates the text label. - And much more! @@ -119,7 +121,7 @@ They generally fall into two categories. **Third party APIs** are not built into the browser by default, and you generally have to grab their code and information from somewhere on the Web. For example: -- The [Twitter API](https://developer.x.com/en/docs) allows you to do things like displaying your latest tweets on your website. +- The [Bluesky API](https://docs.bsky.app/) allows you to do things like displaying your latest posts on your website. - The [Google Maps API](https://developers.google.com/maps/) and [OpenStreetMap API](https://wiki.openstreetmap.org/wiki/API) allows you to embed custom maps into your website, and other such functionality. > [!NOTE] @@ -201,7 +203,7 @@ JavaScript can also be used as a server-side language, for example in the popula ### Dynamic versus static code The word **dynamic** is used to describe both client-side JavaScript, and server-side languages — it refers to the ability to update the display of a web page/app to show different things in different circumstances, generating new content as required. -Server-side code dynamically generates new content on the server, e.g. pulling data from a database, whereas client-side JavaScript dynamically generates new content inside the browser on the client, e.g. creating a new HTML table, filling it with data requested from the server, then displaying the table in a web page shown to the user. +Server-side code dynamically generates new content on the server, e.g., pulling data from a database, whereas client-side JavaScript dynamically generates new content inside the browser on the client, e.g., creating a new HTML table, filling it with data requested from the server, then displaying the table in a web page shown to the user. The meaning is slightly different in the two contexts, but related, and both approaches (server-side and client-side) usually work together. A web page with no dynamically updating content is referred to as **static** — it just shows the same content all the time. @@ -211,6 +213,9 @@ A web page with no dynamically updating content is referred to as **static** — JavaScript is applied to your HTML page in a similar manner to CSS. Whereas CSS uses {{htmlelement("link")}} elements to apply external stylesheets and {{htmlelement("style")}} elements to apply internal stylesheets to HTML, JavaScript only needs one friend in the world of HTML — the {{htmlelement("script")}} element. Let's learn how this works. +> [!NOTE] +> Scrimba's [Setting up our JavaScript file](https://scrimba.com/learn-javascript-c0v/~03?via=mdn) <sup>[_MDN learning partner_](/en-US/docs/MDN/Writing_guidelines/Learning_content#partner_links_and_embeds)</sup> interactive tutorial walks through a couple of different ways to add JavaScript to your HTML. + ### Internal JavaScript 1. First of all, make a local copy of our example file [apply-javascript.html](https://github.com/mdn/learning-area/blob/main/javascript/introduction-to-js-1/what-is-js/apply-javascript.html). Save it in a directory somewhere sensible. 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 b62bb416046297d..09082b3397c3752 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 @@ -1,11 +1,11 @@ --- title: What went wrong? Troubleshooting JavaScript +short-title: Troubleshooting slug: Learn_web_development/Core/Scripting/What_went_wrong page-type: learn-module-chapter +sidebar: learnsidebar --- -{{LearnSidebar}} - {{PreviousMenuNext("Learn_web_development/Core/Scripting/A_first_splash", "Learn_web_development/Core/Scripting/Variables", "Learn_web_development/Core/Scripting")}} When you built up the "Guess the number" game in the previous article, you may have found that it didn't work. Never fear — this article aims to save you from tearing your hair out over such problems by providing you with some tips on how to find and fix errors in JavaScript programs. @@ -167,7 +167,7 @@ There's definitely a problem in the game logic somewhere — the game is not ret ### Working through the logic -To fix this, let's consider how this line is working. First, we invoke [`Math.random()`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Math/random), which generates a random decimal number between 0 and 1, e.g. 0.5675493843. +To fix this, let's consider how this line is working. First, we invoke [`Math.random()`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Math/random), which generates a random decimal number between 0 and 1, e.g., 0.5675493843. ```js Math.random(); diff --git a/files/en-us/learn_web_development/core/structuring_content/advanced_text_features/index.md b/files/en-us/learn_web_development/core/structuring_content/advanced_text_features/index.md index c014a71af2b3738..05bfe740f3632a3 100644 --- a/files/en-us/learn_web_development/core/structuring_content/advanced_text_features/index.md +++ b/files/en-us/learn_web_development/core/structuring_content/advanced_text_features/index.md @@ -2,13 +2,12 @@ title: Advanced text features slug: Learn_web_development/Core/Structuring_content/Advanced_text_features page-type: tutorial-chapter +sidebar: learnsidebar --- -{{LearnSidebar}} - {{PreviousMenuNext("Learn_web_development/Core/Structuring_content/Structuring_documents", "Learn_web_development/Core/Structuring_content/Creating_links", "Learn_web_development/Core/Structuring_content")}} -There are many other elements in HTML for defining text semantics, which we didn't get to in the [Emphasis and importance](/en-US/docs/Learn_web_development/Core/Structuring_content/Emphasis_and_importance) article. The elements described in this article are less known, but still useful to know about (and this is still not a complete list by any means). Here you'll learn about marking up quotations, description lists, computer code and other related text, subscript and superscript, contact information, and more. +There are many other elements in HTML for defining text semantics, which we didn't get to in the [Emphasis and importance](/en-US/docs/Learn_web_development/Core/Structuring_content/Emphasis_and_importance) article. The elements described in this article are less known, but still useful to know about (and this is still not a complete list by any means). Here you'll learn about marking up quotations, computer code and other related text, subscript and superscript, contact information, and more. <table> <tbody> @@ -46,7 +45,7 @@ HTML contains features available for marking up quotations; which element you us ### Blockquotes -If a section of block level content (be it a paragraph, multiple paragraphs, a list, etc.) is quoted from somewhere else, you should wrap it inside a {{htmlelement("blockquote")}} element to signify this, and include a URL pointing to the source of the quote inside a [`cite`](/en-US/docs/Web/HTML/Element/blockquote#cite) attribute. For example, the following markup is taken from the MDN `<blockquote>` element page: +If a section of block level content (be it a paragraph, multiple paragraphs, a list, etc.) is quoted from somewhere else, you should wrap it inside a {{htmlelement("blockquote")}} element to signify this, and include a URL pointing to the source of the quote inside a [`cite`](/en-US/docs/Web/HTML/Reference/Elements/blockquote#cite) attribute. For example, the following markup is taken from the MDN `<blockquote>` element page: ```html <p> @@ -61,7 +60,7 @@ To turn this into a block quote, we would just do this: ```html <p>Here is a blockquote:</p> <blockquote - cite="https://developer.mozilla.org/en-US/docs/Web/HTML/Element/blockquote"> + cite="https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/Elements/blockquote"> <p> The <strong>HTML <code>&lt;blockquote&gt;</code> Element</strong> (or <em>HTML Block Quotation Element</em>) indicates that the enclosed text is @@ -81,7 +80,8 @@ Inline quotations work in exactly the same way, except that they use the {{htmle ```html <p> The quote element — <code>&lt;q&gt;</code> — is - <q cite="https://developer.mozilla.org/en-US/docs/Web/HTML/Element/q"> + <q + cite="https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/Elements/q"> intended for short quotations that don't require paragraph breaks. </q> </p> @@ -93,19 +93,19 @@ Browser default styling will render this as normal text put in quotes to indicat ### Citations -The content of the [`cite`](/en-US/docs/Web/HTML/Element/blockquote#cite) attribute sounds useful, but unfortunately browsers, screen readers, etc. don't really do much with it. There is no way to get the browser to display the contents of `cite`, without writing your own solution using JavaScript or CSS. If you want to make the source of the quotation available on the page you need to make it available in the text via a link or some other appropriate way. +The content of the [`cite`](/en-US/docs/Web/HTML/Reference/Elements/blockquote#cite) attribute sounds useful, but unfortunately browsers, screen readers, etc. don't really do much with it. There is no way to get the browser to display the contents of `cite`, without writing your own solution using JavaScript or CSS. If you want to make the source of the quotation available on the page you need to make it available in the text via a link or some other appropriate way. -There is a {{htmlelement("cite")}} element, but this is meant to contain the title of the resource being quoted, e.g. the name of the book. There is no reason, however, why you couldn't link the text inside `<cite>` to the quote source in some way: +There is a {{htmlelement("cite")}} element, but this is meant to contain the title of the resource being quoted, e.g., the name of the book. There is no reason, however, why you couldn't link the text inside `<cite>` to the quote source in some way: ```html-nolint <p> According to the - <a href="/en-US/docs/Web/HTML/Element/blockquote"> + <a href="/en-US/docs/Web/HTML/Reference/Elements/blockquote"> <cite>MDN blockquote page</cite></a>: </p> <blockquote - cite="https://developer.mozilla.org/en-US/docs/Web/HTML/Element/blockquote"> + cite="https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/Elements/blockquote"> <p> The <strong>HTML <code>&lt;blockquote&gt;</code> Element</strong> (or <em>HTML Block Quotation Element</em>) indicates that the enclosed text is @@ -115,10 +115,10 @@ There is a {{htmlelement("cite")}} element, but this is meant to contain the tit <p> The quote element — <code>&lt;q&gt;</code> — is - <q cite="https://developer.mozilla.org/en-US/docs/Web/HTML/Element/q"> + <q cite="https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/Elements/q"> intended for short quotations that don't require paragraph breaks. </q> - — <a href="/en-US/docs/Web/HTML/Element/q"><cite>MDN q page</cite></a>. + — <a href="/en-US/docs/Web/HTML/Reference/Elements/q"><cite>MDN q page</cite></a>. </p> ``` @@ -274,7 +274,7 @@ textarea.onkeyup = () => { Another fairly common element you'll meet when looking around the Web is {{htmlelement("abbr")}} — this is used to wrap around an abbreviation or acronym. When including either, provide a full expansion of the term in plain text on first use, along with the `<abbr>` to mark up the abbreviation. This provides a hint to user agents on how to announce/display the content while informing all users what the abbreviation means. -If providing the expansion in addition to the abbreviation makes little sense, and the abbreviation or acronym is a fairly shortened term, provide the full expansion of the term as the value of [`title`](/en-US/docs/Web/HTML/Global_attributes/title) attribute: +If providing the expansion in addition to the abbreviation makes little sense, and the abbreviation or acronym is a fairly shortened term, provide the full expansion of the term as the value of [`title`](/en-US/docs/Web/HTML/Reference/Global_attributes/title) attribute: ### Abbreviation example @@ -577,7 +577,7 @@ The basic example above just provides a simple machine readable date, but there ## Test your skills! -You've reached the end of this article, but can you remember the most important information? You can find some further tests to verify that you've retained this information before you move on — see [Test your skills: Advanced HTML text](/en-US/docs/Learn_web_development/Core/Structuring_content/Test_your_skills:_Advanced_HTML_text). +You've reached the end of this article, but can you remember the most important information? You can find some further tests to verify that you've retained this information before you move on — see [Test your skills: Advanced HTML text](/en-US/docs/Learn_web_development/Core/Structuring_content/Test_your_skills/Advanced_HTML_text). ## Summary diff --git a/files/en-us/learn_web_development/core/structuring_content/basic_html_syntax/index.md b/files/en-us/learn_web_development/core/structuring_content/basic_html_syntax/index.md index 943e0a5f7adb60b..8db282413579d06 100644 --- a/files/en-us/learn_web_development/core/structuring_content/basic_html_syntax/index.md +++ b/files/en-us/learn_web_development/core/structuring_content/basic_html_syntax/index.md @@ -2,10 +2,9 @@ title: Basic HTML syntax slug: Learn_web_development/Core/Structuring_content/Basic_HTML_syntax page-type: tutorial-chapter +sidebar: learnsidebar --- -{{LearnSidebar}} - {{NextMenu("Learn_web_development/Core/Structuring_content/Webpage_metadata", "Learn_web_development/Core/Structuring_content")}} In this article, we cover the absolute basics of HTML. To get you started, this article defines elements, attributes, and all the other important terms you may have heard. It also explains where these fit into HTML. You will learn how HTML elements are structured, how a typical HTML page is structured, and other important basic language features. Along the way, there will be an opportunity to play with HTML too! @@ -68,9 +67,12 @@ The anatomy of our element is: The element is the opening tag, followed by content, followed by the closing tag. +> [!NOTE] +> Head on over to our learning partner Scrimba's [HTML tags](https://scrimba.com/learn-html-and-css-c0p/~02?via=mdn) <sup>[_MDN learning partner_](/en-US/docs/MDN/Writing_guidelines/Learning_content#partner_links_and_embeds)</sup> scrim for an interactive explanation of HTML tags. + ### Active learning: creating your first HTML element -Edit the line below in the "Editable code" area by wrapping it with the tags `<em>` and `</em>.` To _open the element_, put the opening tag `<em>` at the start of the line. To _close the element_, put the closing tag `</em>` at the end of the line. Doing this should give the line italic text formatting! See your changes update live in the _Output_ area. +Edit the line below in the "Editable code" area by wrapping it with the tags `<em>` and `</em>`. To _open the element_, put the opening tag `<em>` at the start of the line. To _close the element_, put the closing tag `</em>` at the end of the line. Doing this should give the line italic text formatting! See your changes update live in the _Output_ area. If you make a mistake, you can clear your work using the _Reset_ button. If you get really stuck, press the _Show solution_ button to see the answer. @@ -402,7 +404,7 @@ textarea.onkeyup = () => { ### Boolean attributes -Sometimes you will see attributes written without values. This is entirely acceptable. These are called [Boolean attributes](/en-US/docs/Glossary/Boolean/HTML). When a boolean attribute is written without a value, or with any value, even like `"false"`, the boolean attribute is always set to true. Otherwise, if the attribute is not written in an HTML tag, the attribute is set to false. The spec requires the attribute's value to either be the empty string (including when the attribute has no value explicitly specified) or the same as the attribute's name, but other values work the same. For example, consider the [`disabled`](/en-US/docs/Web/HTML/Element/input#disabled) attribute, which you can assign to form input elements. (You use this to _disable_ the form input elements so the user can't make entries. The disabled elements typically have a grayed-out appearance.) For example: +Sometimes you will see attributes written without values. This is entirely acceptable. These are called [Boolean attributes](/en-US/docs/Glossary/Boolean/HTML). When a boolean attribute is written without a value, or with any value, even like `"false"`, the boolean attribute is always set to true. Otherwise, if the attribute is not written in an HTML tag, the attribute is set to false. The spec requires the attribute's value to either be the empty string (including when the attribute has no value explicitly specified) or the same as the attribute's name, but other values work the same. For example, consider the [`disabled`](/en-US/docs/Web/HTML/Reference/Elements/input#disabled) attribute, which you can assign to form input elements. (You use this to _disable_ the form input elements so the user can't make entries. The disabled elements typically have a grayed-out appearance.) For example: ```html <input type="text" disabled="disabled" /> @@ -508,7 +510,7 @@ Here we have: 2. `<html></html>`: The {{htmlelement("html")}} element. This element wraps all the content on the page. It is sometimes known as the root element. 3. `<head></head>`: The {{htmlelement("head")}} element. This element acts as a container for everything you want to include on the HTML page, **that isn't the content** the page will show to viewers. This includes keywords and a page description that would appear in search results, CSS to style content, character set declarations, and more. You will learn more about this in the next article of the series. -4. `<meta charset="utf-8">`: The {{htmlelement("meta")}} element. This element represents metadata that cannot be represented by other HTML meta-related elements, like {{htmlelement("base")}}, {{htmlelement("link")}}, {{htmlelement("script")}}, {{htmlelement("style")}} or {{htmlelement("title")}}. The [`charset`](/en-US/docs/Web/HTML/Element/meta#charset) attribute specifies the character encoding for your document as UTF-8, which includes most characters from the vast majority of human written languages. With this setting, the page can now handle any textual content it might contain. There is no reason not to set this, and it can help avoid some problems later. +4. `<meta charset="utf-8">`: The {{htmlelement("meta")}} element. This element represents metadata that cannot be represented by other HTML meta-related elements, like {{htmlelement("base")}}, {{htmlelement("link")}}, {{htmlelement("script")}}, {{htmlelement("style")}} or {{htmlelement("title")}}. The [`charset`](/en-US/docs/Web/HTML/Reference/Elements/meta#charset) attribute specifies the character encoding for your document as UTF-8, which includes most characters from the vast majority of human written languages. With this setting, the page can now handle any textual content it might contain. There is no reason not to set this, and it can help avoid some problems later. 5. `<title></title>`: The {{htmlelement("title")}} element. This sets the title of the page, which is the title that appears in the browser tab the page is loaded in. The page title is also used to describe the page when it is bookmarked. 6. `<body></body>`: The {{htmlelement("body")}} element. This contains _all_ the content that displays on the page, including text, images, videos, games, playable audio tracks, or whatever else. @@ -601,7 +603,7 @@ function updateCode() { } const htmlSolution = - '<h1>Some music</h1><p>I really enjoy <strong>playing the drums</strong>. One of my favorite drummers is Neal Peart, who plays in the band <a href="https://en.wikipedia.org/wiki/Rush_%28band%29" title="Rush Wikipedia article">Rush</a>. My favorite Rush album is currently <a href="http://www.deezer.com/album/942295">Moving Pictures</a>.</p> <img src="http://www.cygnus-x1.net/links/rush/images/albums/sectors/sector2-movingpictures-cover-s.jpg" alt="Rush Moving Pictures album cover">'; + '<h1>Some music</h1><p>I really enjoy <strong>playing the drums</strong>. One of my favorite drummers is Neal Peart, who plays in the band <a href="https://en.wikipedia.org/wiki/Rush_%28band%29" title="Rush Wikipedia article">Rush</a>. My favorite Rush album is currently <a href="https://www.deezer.com/album/942295">Moving Pictures</a>.</p> <img src="https://www.cygnus-x1.net/links/rush/images/albums/sectors/sector2-movingpictures-cover-s.jpg" alt="Rush Moving Pictures album cover">'; let solutionEntry = htmlSolution; reset.addEventListener("click", () => { diff --git a/files/en-us/learn_web_development/core/structuring_content/creating_links/index.md b/files/en-us/learn_web_development/core/structuring_content/creating_links/index.md index 481f9d229a70881..7988f60431f914c 100644 --- a/files/en-us/learn_web_development/core/structuring_content/creating_links/index.md +++ b/files/en-us/learn_web_development/core/structuring_content/creating_links/index.md @@ -2,10 +2,9 @@ title: Creating links slug: Learn_web_development/Core/Structuring_content/Creating_links page-type: tutorial-chapter +sidebar: learnsidebar --- -{{LearnSidebar}} - {{PreviousMenuNext("Learn_web_development/Core/Structuring_content/Advanced_text_features", "Learn_web_development/Core/Structuring_content/Marking_up_a_letter", "Learn_web_development/Core/Structuring_content")}} Links (also known as hyperlinks) are really important — they are what makes the Web _a web_. @@ -60,7 +59,7 @@ For example, the BBC homepage contains many links that point not only to multipl ## Anatomy of a link -A basic link is created by wrapping the text or other content inside an {{htmlelement("a")}} element and using the [`href`](/en-US/docs/Web/HTML/Element/a#href) attribute, also known as a **Hypertext Reference**, or **target**, that contains the web address. +A basic link is created by wrapping the text or other content inside an {{htmlelement("a")}} element and using the [`href`](/en-US/docs/Web/HTML/Reference/Elements/a#href) attribute, also known as a **Hypertext Reference**, or **target**, that contains the web address. ```html <p> @@ -73,6 +72,12 @@ This gives us the following result: I'm creating a link to [the Mozilla homepage](https://www.mozilla.org/en-US/). +> [!CALLOUT] +> +> **Try it out** +> +> Scrimba's [Anchor tags](https://scrimba.com/learn-html-and-css-c0p/~0a?via=mdn) <sup>[_MDN learning partner_](/en-US/docs/MDN/Writing_guidelines/Learning_content#partner_links_and_embeds)</sup> scrim provides an interactive demonstration of how to create links using HTML, plus a challenge to get you creating your own links. + ### Block level links As mentioned before, almost any content can be made into a link, even {{Glossary("Block/CSS", "block-level elements")}}. @@ -92,7 +97,7 @@ This turns the heading into a link: ### Image links -If you have an image you want to make into a link, use the {{htmlelement("a")}} element to wrap the image file referenced with the {{htmlelement("img")}} element. The example below uses a relative path to reference a locally stored SVG image file. +To turn an image into a link, wrap the {{htmlelement("img")}} element with an {{htmlelement("a")}} element. The example below uses a relative path to reference a locally stored SVG image file. ```css hidden img { @@ -191,7 +196,7 @@ Let's look at some examples of links between some different files in this direct ### Document fragments It's possible to link to a specific part of an HTML document, known as a **document fragment**, rather than just to the top of the document. -To do this you first have to assign an [`id`](/en-US/docs/Web/HTML/Global_attributes/id) attribute to the element you want to link to. +To do this you first have to assign an [`id`](/en-US/docs/Web/HTML/Reference/Global_attributes/id) attribute to the element you want to link to. It normally makes sense to link to a specific heading, so this would look something like the following: ```html @@ -249,18 +254,22 @@ Let's look at a specific example: **Good** link text: [Download Firefox](https://www.mozilla.org/en-US/firefox/new/?redirect_source=firefox-com) ```html example-good -<p><a href="https://www.mozilla.org/en-US/firefox/">Download Firefox</a></p> +<p><a href="https://www.mozilla.org/en-US/firefox/new/">Download Firefox</a></p> ``` -**Bad** link text: [Click here](https://www.mozilla.org/en-US/firefox/) to download Firefox +<!-- markdownlint-disable descriptive-link-text --> + +**Bad** link text: [Click here](https://www.mozilla.org/en-US/firefox/new/) to download Firefox ```html example-bad <p> - <a href="https://www.mozilla.org/en-US/firefox/">Click here</a> to download - Firefox + <a href="https://www.mozilla.org/en-US/firefox/new/">Click here</a> to + download Firefox </p> ``` +<!-- markdownlint-enable descriptive-link-text --> + Other tips: - Don't repeat the URL as part of the link text — URLs look ugly, and sound even uglier when a screen reader reads them out letter by letter. @@ -304,7 +313,7 @@ When you are linking to a resource that's to be downloaded rather than opened in ### When to open links in a new tab -Links by default open in the same tab as the page they are on, which allows the user to navigate back to the previous page using the browser's back button. However, many sites (including MDN) choose to open certain links, especially external links, in a new tab. This is done by setting the [`target`](/en-US/docs/Web/HTML/Element/a#target) attribute to `"_blank"`. +Links by default open in the same tab as the page they are on, which allows the user to navigate back to the previous page using the browser's back button. However, many sites (including MDN) choose to open certain links, especially external links, in a new tab. This is done by setting the [`target`](/en-US/docs/Web/HTML/Reference/Elements/a#target) attribute to `"_blank"`. ```html Firefox is developed by the @@ -362,7 +371,7 @@ In its most basic and commonly used form, a `mailto:` link indicates the email a This results in a link that looks like this: [Send email to nowhere](mailto:nowhere@mozilla.org). -In fact, the email address is optional. If you omit it and your [`href`](/en-US/docs/Web/HTML/Element/a#href) is "mailto:", a new outgoing email window will be opened by the user's email client with no destination address. +In fact, the email address is optional. If you omit it and your [`href`](/en-US/docs/Web/HTML/Reference/Elements/a#href) is "mailto:", a new outgoing email window will be opened by the user's email client with no destination address. This is often useful as "Share" links that users can click to send an email to an address of their choosing. ### Specifying details @@ -396,7 +405,7 @@ Here are a few other sample `mailto` URLs: ## Test your skills! -You've reached the end of this article, but can you remember the most important information? You can find some further tests to verify that you've retained this information before you move on — see [Test your skills: Links](/en-US/docs/Learn_web_development/Core/Structuring_content/Test_your_skills:_Links). +You've reached the end of this article, but can you remember the most important information? You can find some further tests to verify that you've retained this information before you move on — see [Test your skills: Links](/en-US/docs/Learn_web_development/Core/Structuring_content/Test_your_skills/Links). ## Summary diff --git a/files/en-us/learn_web_development/core/structuring_content/debugging_html/index.md b/files/en-us/learn_web_development/core/structuring_content/debugging_html/index.md index ba791980b0238ce..5f0fdf22c369d0a 100644 --- a/files/en-us/learn_web_development/core/structuring_content/debugging_html/index.md +++ b/files/en-us/learn_web_development/core/structuring_content/debugging_html/index.md @@ -2,15 +2,11 @@ title: Debugging HTML slug: Learn_web_development/Core/Structuring_content/Debugging_HTML page-type: learn-module-chapter +sidebar: learnsidebar --- -{{LearnSidebar}} - {{PreviousMenuNext("Learn_web_development/Core/Structuring_content/HTML_forms", "Learn_web_development/Core/Styling_basics", "Learn_web_development/Core/Structuring_content")}} -> [!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. - Writing HTML is fine, but what if something goes wrong, and you can't work out where the error in the code is? This article will introduce you to some tools that can help you find and fix errors in HTML. <table> @@ -30,12 +26,13 @@ Writing HTML is fine, but what if something goes wrong, and you can't work out w </td> </tr> <tr> - <th scope="row">Objective:</th> + <th scope="row">Learning outcomes:</th> <td> <ul> - <li>The concept of permissive code, and what this means for HTML debugging.</li> - <li>Using the <a href="https://validator.w3.org/">HTML validator</a> to detect markup errors.</li> - <li>Using the DOM inspector in your browser DevTools to dive deeper into your markup.</li> + <li>The key background around debugging HTML</li> + <li>Using the DOM inspector in your browser DevTools to dive deeper into your HTML code.</li> + <li>Exploring common HTML error types.</li> + <li>Using the <a href="https://validator.w3.org/">HTML validator</a> to detect HTML errors.</li> </ul> </td> </tr> @@ -44,35 +41,91 @@ Writing HTML is fine, but what if something goes wrong, and you can't work out w ## Debugging isn't scary -When writing code of some kind, everything is usually fine, until that dreaded moment when an error occurs — you've done something wrong, so your code doesn't work — either not at all, or not quite how you wanted it to. For example, the following shows an error reported when trying to {{glossary("compile")}} a simple program written in the [Rust](https://www.rust-lang.org/) language. +When writing code of some kind, everything is fine, until that dreaded moment when an error occurs — you've done something wrong, so your code doesn't work — either not at all, or not quite how you wanted it to. For example, the following shows an error reported when trying to {{glossary("compile")}} a simple program written in the [Rust](https://www.rust-lang.org/) language. ![A console window showing the result of trying to compile a rust program with a missing quote around a string in a print statement. The error message reported is error: unterminated double quote string.](error-message.png) Here, the error message is relatively easy to understand — "unterminated double quote string". If you look at the listing, you can probably see how `println!(Hello, world!");` might logically be missing a double quote. However, error messages can quickly get more complicated and less easy to interpret as programs get bigger, and even simple cases can look a little intimidating to someone who doesn't know anything about Rust. -Debugging doesn't have to be scary though — the key to being comfortable with writing and debugging any programming language or code is familiarity with both the language and the tools. +Debugging doesn't have to be scary though — the key to being comfortable with writing and debugging any code is familiarity with both the language and the associated tools. ## HTML and debugging -HTML is not as complicated to understand as Rust. HTML is not compiled into a different form before the browser parses it and shows the result (it is _interpreted_, not _compiled_). And HTML's {{glossary("element")}} syntax is arguably a lot easier to understand than a "real programming language" like Rust, {{glossary("JavaScript")}}, or {{glossary("Python")}}. The way that browsers parse HTML is a lot more **permissive** than how programming languages are run, which is both a good and a bad thing. +HTML is not as complicated to understand as Rust. HTML is not compiled into a different form before parsing (it is _interpreted_, not _compiled_). And HTML's {{glossary("element")}} syntax is arguably a lot easier to understand than a "real programming language" like Rust, {{glossary("JavaScript")}}, or {{glossary("Python")}}. + +The way that browsers parse HTML is a lot more **permissive** than how most programming languages are parsed, which is both a good and a bad thing. + +But first of all, what do we mean by permissive? Well, generally when you do something wrong in code, there are two main types of error that you'll come across: + +- **Syntax errors**: These are typos in your code that cause the program not to run, like the Rust error shown earlier. These are usually easy to fix as long as you are familiar with the language's syntax and know what the error messages mean. +- **Logic errors**: These are errors where the syntax is actually correct, but the code is not doing what you intended it to, meaning that the program runs incorrectly. These are often harder to fix than syntax errors, as there isn't an error message to direct you to the source of the error. -## Permissive code +HTML itself doesn't suffer from syntax errors because browsers parse it permissively, meaning that the page still displays even if there are syntax errors in the source code. Browsers have built-in rules to state how to interpret incorrectly-written HTML markup (often called **invalid** or **badly-formed** markup), changing it automatically to some valid markup. -So what do we mean by permissive? Well, generally when you do something wrong in code, there are two main types of error that you'll come across: +For example, the following HTML snippet contains incorrectly nested elements: -- **Syntax errors**: These are spelling or punctuation errors in your code that actually cause the program not to run, like the Rust error shown above. These are usually easy to fix as long as you are familiar with the language's syntax 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 the program runs incorrectly. These are often harder to fix than syntax errors, as there isn't an error message to direct you to the source of the error. +```html example-bad +<p>I didn't expect to find the <em>next-door neighbor's <strong>cat</em></strong> here!</p> +``` -HTML itself doesn't suffer from syntax errors because browsers parse it permissively, meaning that the page still displays even if there are syntax errors. Browsers have built-in rules to state how to interpret incorrectly written markup, so you'll get something running, even if it is not what you expected. This, of course, can still be a problem! +The closing `</strong>` tag should be before the closing `</em>` tag, but it is not — it is after it. + +If you load this HTML into a browser then look at the [rendered DOM](/en-US/docs/Learn_web_development/Getting_started/Web_standards/How_browsers_load_websites#handling_html), you'll see that the nesting has been corrected by the browser: + +```html example-good +<p> + I didn't expect to find the + <em>next-door neighbor's <strong>cat</strong></em> here! +</p> +``` + +So why is this both good and bad? Well, in this case the browser has created the intended result, but as you'll see [later on](#active_learning_studying_html_using_the_dom_inspector), this is not always the case. You'll always get _something_ running, but the browser doesn't always get it right, which can cause problems. It is better to write correct markup in the first place. > [!NOTE] -> HTML is parsed permissively because when the web was first created, it was decided that allowing people to get their content published was more important than making sure the syntax was absolutely correct. The web would probably not be as popular as it is today, if it had been more strict from the very beginning. +> HTML is parsed permissively because when the web was first created, it was decided that getting content published was more important than making sure the syntax was absolutely correct. The web would probably not be as popular as it is today if it had been more strict from the very beginning. + +So how do you find markup errors? Later on we will show you how to find errors in HTML using a tool called the [HTML validator](#html_validation), but first we will show you how to inspect your HTML manually using a **DOM inspector**, and then explore what kinds of markup errors you might be looking for, and how the browser might interpret those. + +## Using a DOM inspector -### Active learning: Studying permissive code +All modern browsers have a set of [developer tools](/en-US/docs/Learn_web_development/Howto/Tools_and_setup/What_are_browser_developer_tools) (devtools) built into them, which provide a set of functionality for examining the webpage loaded into the current tab. These can show you what HTML is rendered in the page, what CSS is applied to each DOM node, what JavaScript is running in the page, and more. They also allow you to edit the currently-running code and see the effect live on the page. -It's time to study the permissive nature of HTML code. +You can open the devtools in a similar way in each browser — see [How to open the devtools in your browser](/en-US/docs/Learn_web_development/Howto/Tools_and_setup/What_are_browser_developer_tools#how_to_open_the_devtools_in_your_browser) to learn how. + +For this article, the only relevant devtools function is the **DOM inspector**, which shows the currently-rendered HTML DOM and allows you to edit it. Let's look at this now: + +1. Open the devtools in your browser. +2. Open the DOM inspector. It is in the same place in each browser — the first tab in the devtools at the start of the row. In Firefox it is labelled _Inspector_, while in Safari, Edge, and Chrome it is labeled _Elements_. This should be the tab selected by default when you first open the devtools, but select it if it isn't. +3. Examine the DOM tree structure shown in the tab, and note how you can click the little expansion arrows at the start of each DOM node to expand and collapse them and reveal their descendant nodes. You can also use the up and down cursor keys to move up and down the nodes, and the right and left cursor keys to expand and collapse the nodes. +4. Also try hovering over the nodes (or selecting them with the cursor keys) and note how the currently-hovered (or selected) element is highlighted in the viewport. +5. You can also edit the rendered DOM. We won't use the editing functionality in this article, but take some time to look up how to do this if you are curious. + +## Active learning: Studying HTML using the DOM inspector + +It's time to study some HTML code using the DOM inspector, and see how the browser handles common markup errors. + +1. First, save the following HTML file listing as `debug-example.html`, somewhere on your local machine. This demo is deliberately written with some built-in errors for us to explore. + + ```html-nolint + <!DOCTYPE html> + <html lang="en-US"> + <head> + <meta charset="utf-8"> + <title>HTML debugging examples</title> + </head> + + <body> + <h1>HTML debugging examples</h1> + <p>What causes errors in HTML? + <ul> + <li>Unclosed elements: If an element is <strong>not closed properly,then its effect can spread to areas you didn't intend + <li>Badly nested elements: Nesting elements properly is also very important for code behaving correctly. <strong>strong <em>strong emphasized?</strong> what is this?</em> + <li>Unclosed attributes: Another common source of HTML problems. Let's look at an example: <a href="https://www.mozilla.org/>link to Mozilla homepage</a> + </ul> + </body> + </html> + ``` -1. First, download our [debug-example demo](https://github.com/mdn/learning-area/blob/main/html/introduction-to-html/debugging-html/debug-example.html) and save it locally. This demo is deliberately written with some built-in errors for us to explore (the HTML markup is said to be **badly-formed**, as opposed to **well-formed**). 2. Next, open it in a browser. You will see something like this:![A simple HTML document with a title of HTML debugging examples, and some information about common HTML errors, such as unclosed elements, badly nested elements, and unclosed attributes. ](badly-formed-html.png) 3. This immediately doesn't look great; let's look at the source code to see if we can work out why (only the body contents are shown): @@ -98,16 +151,15 @@ It's time to study the permissive nature of HTML code. 4. Let's review the problems: - The {{htmlelement("p","paragraph")}} and {{htmlelement("li","list item")}} elements have no closing tags. Looking at the image above, this doesn't seem to have affected the markup rendering too badly, as it is easy to infer where one element should end and another should begin. - - The first {{htmlelement("strong")}} element has no closing tag. This is a bit more problematic, as it isn't easy to tell where the element is supposed to end. In fact, the whole of the rest of the text has been strongly emphasized. + - The first {{htmlelement("strong")}} element has no closing tag. This is a bit more problematic, as it isn't easy to tell where the element is supposed to end. In fact, the whole of the rest of the text has been rendered in bold. - This section is badly nested: `<strong>strong <em>strong emphasized?</strong> what is this?</em>`. It is not easy to tell how this has been interpreted because of the previous problem. - - The [`href`](/en-US/docs/Web/HTML/Element/a#href) attribute value is missing a closing double quote. This seems to have caused the biggest problem — the link has not rendered at all. + - The [`href`](/en-US/docs/Web/HTML/Reference/Elements/a#href) attribute value is missing a closing double quote. This seems to have caused the biggest problem — the link has not been rendered at all. -5. Now let's look at the markup the browser has rendered, as opposed to the markup in the source code. To do this, we can use the browser developer tools. If you are not familiar with how to use your browser's developer tools, take a few minutes to review [Discover browser developer tools](/en-US/docs/Learn_web_development/Howto/Tools_and_setup/What_are_browser_developer_tools). -6. In the DOM inspector, you can see what the rendered markup looks like: ![The HTML inspector in Firefox, with our example's paragraph highlighted, showing the text "What causes errors in HTML?" Here you can see that the paragraph element has been closed by the browser.](html-inspector.png) -7. Using the DOM inspector, let's explore our code in detail to see how the browser has tried to fix our HTML errors (we did the review in Firefox; other modern browsers _should_ give the same result): +5. Now let's examine the rendered DOM, as opposed to the source code. To do this, open your browser's DOM inspector. You will see a representation of the rendered markup: ![The HTML inspector in Firefox, with our example's paragraph highlighted, showing the text "What causes errors in HTML?" Here you can see that the paragraph element has been closed by the browser.](html-inspector.png) +6. Look at how the browser has tried to fix our HTML errors (we did the review in Firefox; other modern browsers _should_ give the same result): - The paragraphs and list items have been given closing tags. - - It isn't clear where the first `<strong>` element should be closed, so the browser has wrapped each separate block of text with its own strong tag, right down to the bottom of the document! + - It isn't clear where the first `<strong>` element should be closed, so the browser has wrapped each separate block of text in its own `<strong>` element, right down to the bottom of the document! - The incorrect nesting has been fixed by the browser as shown here: ```html @@ -131,19 +183,19 @@ It's time to study the permissive nature of HTML code. ## HTML validation -So you can see from the above example that you really want to make sure your HTML is well-formed! But how? In a small example like the one seen above, it is easy to search through the lines and find the errors, but what about a huge, complex HTML document? +You can see from the above example that you really want to make sure your HTML is well-formed! But how? In a small example like the one seen above, it is easy to search through the lines and find the errors, but what about a huge, complex HTML document? -The best strategy is to start by running your HTML page through the [Markup Validation Service](https://validator.w3.org/) — created and maintained by the W3C, the organization that looks after the specifications that define HTML, CSS, and other web technologies. This webpage takes an HTML document as an input, goes through it, and gives you a report to tell you what is wrong with your HTML. +The tool for this job is the [Markup Validation Service](https://validator.w3.org/) (or **HTML validator**), which is created and maintained by the W3C (which you learned about in [The web standards model](/en-US/docs/Learn_web_development/Getting_started/Web_standards/The_web_standards_model)). The validator takes an HTML document as an input, goes through it, and gives you a report to tell you what is wrong with your HTML. ![The HTML validator homepage](validator.png) To specify the HTML to validate, you can provide a web address, upload an HTML file, or directly input some HTML code. -### Active learning: Validating an HTML document +## Active learning: Validating an HTML document Let's try this with our [sample document](https://github.com/mdn/learning-area/blob/main/html/introduction-to-html/debugging-html/debug-example.html). -1. First, load the [Markup Validation Service](https://validator.w3.org/) in one browser tab, if it isn't already open. +1. First, load the [Markup Validation Service](https://validator.w3.org/) in a new browser tab, if it isn't already open. 2. Switch to the [Validate by Direct Input](https://validator.w3.org/#validate_by_input) tab. 3. Copy all of the sample document's code (not just the body) and paste it into the large text area shown in the Markup Validation Service. 4. Press the _Check_ button. @@ -154,7 +206,7 @@ This should give you a list of errors and other information. ### Interpreting the error messages -The error messages are usually helpful, but sometimes they are not so helpful; with a bit of practice you can work out how to interpret these to fix your code. Let's go through the error messages and see what they mean. You'll see that each message comes with a line and column number to help you to locate the error easily. +The error messages are usually helpful, but sometimes they are not so easy to understand. With a bit of practice, you can work out how to interpret these to fix your code. Let's go through the error messages and see what they mean. You'll see that each message comes with a line and column number to help you to locate the error easily. - "End tag `li` implied, but there were open elements" (2 instances): These messages indicate that an element is open that should be closed. The ending tag is implied, but not actually there. The line/column information points to the first line after the line where the closing tag should really be, but this is a good enough clue to see what is wrong. - "Unclosed element `strong`": This is really easy to understand — a {{htmlelement("strong")}} element is unclosed, and the line/column information points right to where it is. @@ -169,20 +221,14 @@ The error messages are usually helpful, but sometimes they are not so helpful; w > [!NOTE] > An attribute missing a closing quote can result in an open element because the rest of the document is interpreted as the attribute's content. -- "Unclosed element `ul`": This is not very helpful, as the {{htmlelement("ul")}} element _is_ closed correctly. This error comes up because the {{htmlelement("a")}} element is not closed, due to the missing closing quote mark. - -If you can't work out what every error message means, don't worry about it — a good idea is to try fixing a few errors at a time. Then try revalidating your HTML to show what errors are left. Sometimes fixing an earlier error will also get rid of other error messages — several errors can often be caused by a single problem, in a domino effect. +- "Unclosed element `ul`": This is not very helpful, as the {{htmlelement("ul")}} element _is_ closed correctly. This error occurs because the {{htmlelement("a")}} element is not closed, due to the missing closing quote mark. -You will know when all your errors are fixed when you see the following banner in your output: - -![Banner that reads "The document validates according to the specified schema(s) and to additional constraints checked by the validator."](valid-html-banner.png) - -## Using a DOM inspector +If you can't work out what every error message means, don't worry about it. A good strategy is to fix a few errors at a time, then revalidate your HTML after each set of fixes to show what errors are left. Sometimes, fixing an earlier error will also get rid of other error messages — several errors can often be caused by a single problem, in a domino effect. -TODO +You will know when all your errors are fixed when you see a nice little green banner telling you there are no errors to report. At the time of writing, it said "Document checking completed. No errors or warnings to show." ## Summary -So there we have it, an introduction to debugging HTML, which should give you some useful skills to count on when you start to debug CSS, JavaScript, and other types of code later on in your career. This also marks the end of the Introduction to HTML module learning articles — now you can go on to testing yourself with our assessments: the first one is linked below. +So there we have it, an introduction to debugging HTML, which should give you some useful skills to count on when debugging HTML, but also CSS and JavaScript code later on in the course. This also marks the end of the _Structuring content with HTML_ module. {{PreviousMenuNext("Learn_web_development/Core/Structuring_content/HTML_forms", "Learn_web_development/Core/Styling_basics", "Learn_web_development/Core/Structuring_content")}} diff --git a/files/en-us/learn_web_development/core/structuring_content/debugging_html/valid-html-banner.png b/files/en-us/learn_web_development/core/structuring_content/debugging_html/valid-html-banner.png deleted file mode 100644 index e05c56d2d34a906..000000000000000 Binary files a/files/en-us/learn_web_development/core/structuring_content/debugging_html/valid-html-banner.png and /dev/null differ diff --git a/files/en-us/learn_web_development/core/structuring_content/emphasis_and_importance/index.md b/files/en-us/learn_web_development/core/structuring_content/emphasis_and_importance/index.md index dcd372d68d94ed6..12895d2ef4e44d0 100644 --- a/files/en-us/learn_web_development/core/structuring_content/emphasis_and_importance/index.md +++ b/files/en-us/learn_web_development/core/structuring_content/emphasis_and_importance/index.md @@ -2,10 +2,9 @@ title: Emphasis and importance slug: Learn_web_development/Core/Structuring_content/Emphasis_and_importance page-type: tutorial-chapter +sidebar: learnsidebar --- -{{LearnSidebar}} - {{PreviousMenuNext("Learn_web_development/Core/Structuring_content/Headings_and_paragraphs", "Learn_web_development/Core/Structuring_content/Lists", "Learn_web_development/Core/Structuring_content")}} The previous article looked at why semantics are important in HTML, and focused on headings and paragraphs. This article continues on the theme of semantics, looking at HTML elements that apply emphasis and importance to text (parallel to italics and bold text in print media). @@ -26,8 +25,8 @@ The previous article looked at why semantics are important in HTML, and focused <td> <ul> <li>The meaning of emphasis and importance, and the basic elements that apply them in HTML, such as <code>&lt;em&gt;</code> and <code>&lt;strong&gt;</code>.</li> - <li>Identify presentational markup that should no longer be used at all (e.g. <code>&lt;big&gt;</code> and <code>&lt;font&gt;</code>); it is deprecated.</li> - <li>Identify presentational markup that has been repurposed to have new semantic meaning (e.g. <code>&lt;i&gt;</code> and <code>&lt;b&gt;</code>).</li> + <li>Identify presentational markup that should no longer be used at all (e.g., <code>&lt;big&gt;</code> and <code>&lt;font&gt;</code>); it is deprecated.</li> + <li>Identify presentational markup that has been repurposed to have new semantic meaning (e.g., <code>&lt;i&gt;</code> and <code>&lt;b&gt;</code>).</li> </ul> </td> </tr> diff --git a/files/en-us/learn_web_development/core/structuring_content/general_embedding_technologies/index.md b/files/en-us/learn_web_development/core/structuring_content/general_embedding_technologies/index.md index 67cd0125f76ceb5..f13e95b855eb902 100644 --- a/files/en-us/learn_web_development/core/structuring_content/general_embedding_technologies/index.md +++ b/files/en-us/learn_web_development/core/structuring_content/general_embedding_technologies/index.md @@ -1,11 +1,11 @@ --- title: From object to iframe — general embedding technologies +short-title: Embedding technologies slug: Learn_web_development/Core/Structuring_content/General_embedding_technologies page-type: learn-module-chapter +sidebar: learnsidebar --- -{{LearnSidebar}} - Developers commonly think of embedding media such as images, video and audio into web pages. In this article we take somewhat of a sideways step, looking at some elements that allow you to embed a wide variety of content types into your webpages: the {{htmlelement("iframe")}}, {{htmlelement("embed")}} and {{htmlelement("object")}} elements. `<iframe>`s are for embedding other web pages, and the other two allow you to embed external resources such as PDF files. <table> @@ -119,7 +119,7 @@ function updateCode() { output.innerHTML = textarea.value; } -reset.addEventListener("click", function () { +reset.addEventListener("click", () => { textarea.value = code; userEntry = textarea.value; solutionEntry = htmlSolution; @@ -127,7 +127,7 @@ reset.addEventListener("click", function () { updateCode(); }); -solution.addEventListener("click", function () { +solution.addEventListener("click", () => { if (solution.value === "Show solution") { textarea.value = solutionEntry; solution.value = "Hide solution"; @@ -237,14 +237,14 @@ The example includes the bare essentials needed to use an `<iframe>`: - [`border: none`](/en-US/docs/Web/CSS/border) - : If used, the `<iframe>` is displayed without a surrounding border. Otherwise, by default, browsers display the `<iframe>` with a surrounding border (which is generally undesirable). -- [`allowfullscreen`](/en-US/docs/Web/HTML/Element/iframe#allowfullscreen) +- [`allowfullscreen`](/en-US/docs/Web/HTML/Reference/Elements/iframe#allowfullscreen) - : If set, the `<iframe>` is able to be placed in fullscreen mode using the [Fullscreen API](/en-US/docs/Web/API/Fullscreen_API) (somewhat beyond the scope of this article). -- [`src`](/en-US/docs/Web/HTML/Element/iframe#src) +- [`src`](/en-US/docs/Web/HTML/Reference/Elements/iframe#src) - : This attribute, as with {{htmlelement("video")}}/{{htmlelement("img")}}, contains a path pointing to the URL of the document to be embedded. -- [`width`](/en-US/docs/Web/HTML/Element/iframe#width) and [`height`](/en-US/docs/Web/HTML/Element/iframe#height) +- [`width`](/en-US/docs/Web/HTML/Reference/Elements/iframe#width) and [`height`](/en-US/docs/Web/HTML/Reference/Elements/iframe#height) - : These attributes specify the width and height you want the iframe to be. -- [`sandbox`](/en-US/docs/Web/HTML/Element/iframe#sandbox) - - : This attribute, which works in slightly more modern browsers than the rest of the `<iframe>` features (e.g. IE 10 and above) requests heightened security settings; we'll say more about this in the next section. +- [`sandbox`](/en-US/docs/Web/HTML/Reference/Elements/iframe#sandbox) + - : This attribute, which works in slightly more modern browsers than the rest of the `<iframe>` features (e.g., IE 10 and above) requests heightened security settings; we'll say more about this in the next section. > [!NOTE] > In order to improve speed, it's a good idea to set the iframe's `src` attribute with JavaScript after the main content is done with loading. This makes your page usable sooner and decreases your official page load time (an important {{glossary("SEO")}} metric.) @@ -285,14 +285,14 @@ You want to give attackers as little power as you can to do bad things on your w Content that's not sandboxed may be able to execute JavaScript, submit forms, trigger popup windows, etc. By default, you should impose all available restrictions by using the `sandbox` attribute with no parameters, as shown in our previous example. -If absolutely required, you can add permissions back one by one (inside the `sandbox=""` attribute value) — see the [`sandbox`](/en-US/docs/Web/HTML/Element/iframe#sandbox) reference entry for all the available options. One important note is that you should _never_ add both `allow-scripts` and `allow-same-origin` to your `sandbox` attribute — in that case, the embedded content could bypass the [Same-origin policy](/en-US/docs/Glossary/Same-origin_policy) that stops sites from executing scripts, and use JavaScript to turn off sandboxing altogether. +If absolutely required, you can add permissions back one by one (inside the `sandbox=""` attribute value) — see the [`sandbox`](/en-US/docs/Web/HTML/Reference/Elements/iframe#sandbox) reference entry for all the available options. One important note is that you should _never_ add both `allow-scripts` and `allow-same-origin` to your `sandbox` attribute — in that case, the embedded content could bypass the [Same-origin policy](/en-US/docs/Glossary/Same-origin_policy) that stops sites from executing scripts, and use JavaScript to turn off sandboxing altogether. > [!NOTE] > Sandboxing provides no protection if attackers can fool people into visiting malicious content directly (outside an `iframe`). If there's any chance that certain content may be malicious (e.g., user-generated content), please serve it from a different {{glossary("domain")}} to your main site. #### Configure CSP directives -{{Glossary("CSP")}} stands for **[content security policy](/en-US/docs/Web/HTTP/CSP)** and provides [a set of HTTP Headers](/en-US/docs/Web/HTTP/Headers/Content-Security-Policy) (metadata sent along with your web pages when they are served from a web server) designed to improve the security of your HTML document. When it comes to securing `<iframe>`s, you can _[configure your server to send an appropriate `X-Frame-Options` header.](/en-US/docs/Web/HTTP/Headers/X-Frame-Options)_ This can prevent other websites from embedding your content in their web pages (which would enable [clickjacking](/en-US/docs/Web/Security/Attacks/Clickjacking) and a host of other attacks), which is exactly what the MDN developers have done, as we saw earlier on. +{{Glossary("CSP")}} stands for **[content security policy](/en-US/docs/Web/HTTP/Guides/CSP)** and provides [a set of HTTP Headers](/en-US/docs/Web/HTTP/Reference/Headers/Content-Security-Policy) (metadata sent along with your web pages when they are served from a web server) designed to improve the security of your HTML document. When it comes to securing `<iframe>`s, you can _[configure your server to send an appropriate `X-Frame-Options` header.](/en-US/docs/Web/HTTP/Reference/Headers/X-Frame-Options)_ This can prevent other websites from embedding your content in their web pages (which would enable [clickjacking](/en-US/docs/Web/Security/Attacks/Clickjacking) and a host of other attacks), which is exactly what the MDN developers have done, as we saw earlier on. > [!NOTE] > You can read Frederik Braun's post [On the X-Frame-Options Security Header](https://blog.mozilla.org/security/2013/12/12/on-the-x-frame-options-security-header/) for more background information on this topic. Obviously, it's rather out of scope for a full explanation in this article. @@ -318,26 +318,26 @@ If you find yourself needing to embed plugin content, this is the kind of inform <tbody> <tr> <td>{{glossary("URL")}} of the embedded content</td> - <td><a href="/en-US/docs/Web/HTML/Element/embed#src"><code>src</code></a></td> - <td><a href="/en-US/docs/Web/HTML/Element/object#data"><code>data</code></a></td> + <td><a href="/en-US/docs/Web/HTML/Reference/Elements/embed#src"><code>src</code></a></td> + <td><a href="/en-US/docs/Web/HTML/Reference/Elements/object#data"><code>data</code></a></td> </tr> <tr> <td> <em>Accurate </em>{{glossary("MIME type", "media type")}} of the embedded content </td> - <td><a href="/en-US/docs/Web/HTML/Element/embed#type"><code>type</code></a></td> - <td><a href="/en-US/docs/Web/HTML/Element/object#type"><code>type</code></a></td> + <td><a href="/en-US/docs/Web/HTML/Reference/Elements/embed#type"><code>type</code></a></td> + <td><a href="/en-US/docs/Web/HTML/Reference/Elements/object#type"><code>type</code></a></td> </tr> <tr> <td> Height and width (in CSS pixels) of the box controlled by the plugin </td> <td> - <a href="/en-US/docs/Web/HTML/Element/embed#height"><code>height</code></a><br /><a href="/en-US/docs/Web/HTML/Element/embed#width"><code>width</code></a> + <a href="/en-US/docs/Web/HTML/Reference/Elements/embed#height"><code>height</code></a><br /><a href="/en-US/docs/Web/HTML/Reference/Elements/embed#width"><code>width</code></a> </td> <td> - <a href="/en-US/docs/Web/HTML/Element/object#height"><code>height</code></a><br /><a href="/en-US/docs/Web/HTML/Element/object#width"><code>width</code></a> + <a href="/en-US/docs/Web/HTML/Reference/Elements/object#height"><code>height</code></a><br /><a href="/en-US/docs/Web/HTML/Reference/Elements/object#width"><code>width</code></a> </td> </tr> <tr> diff --git a/files/en-us/learn_web_development/core/structuring_content/headings_and_paragraphs/index.md b/files/en-us/learn_web_development/core/structuring_content/headings_and_paragraphs/index.md index abfdb75fe2c7568..35645553f99f7a3 100644 --- a/files/en-us/learn_web_development/core/structuring_content/headings_and_paragraphs/index.md +++ b/files/en-us/learn_web_development/core/structuring_content/headings_and_paragraphs/index.md @@ -1,11 +1,10 @@ --- -title: Headings and paragraphs in HTML +title: Headings and paragraphs slug: Learn_web_development/Core/Structuring_content/Headings_and_paragraphs page-type: tutorial-chapter +sidebar: learnsidebar --- -{{LearnSidebar}} - {{PreviousMenuNext("Learn_web_development/Core/Structuring_content/Webpage_metadata", "Learn_web_development/Core/Structuring_content/Emphasis_and_importance", "Learn_web_development/Core/Structuring_content")}} One of HTML's main jobs is to give text structure so that a browser can display an HTML document the way its developer intends. This article explains how {{glossary("HTML")}} can be used to provide fundamental page structure by defining headings and paragraphs. @@ -24,11 +23,13 @@ One of HTML's main jobs is to give text structure so that a browser can display <tr> <th scope="row">Learning outcomes:</th> <td> - <li>How to create a good document structure with headings and content beneath those headings.</li> - <li>Using semantic HTML rather than presentational HTML, and why this is important.</li> - <li>The need for heading levels to be used logically, i.e. no skipping levels or using them arbitrarily because you want to achieve a certain font size (that's a job for CSS).</li> - <li>SEO benefits: for example, keywords are boosted in headings.</li> - <li>Accessibility benefits: Assistive technology (AT) such as screen readers use headings (and other landmarks) as signposts to navigate content. HTML documents are very difficult for AT users to use without headings.</li> + <ul> + <li>How to create a good document structure with headings and content beneath those headings.</li> + <li>Using semantic HTML rather than presentational HTML, and why this is important.</li> + <li>The need for heading levels to be used logically, i.e., no skipping levels or using them arbitrarily because you want to achieve a certain font size (that's a job for CSS).</li> + <li>SEO benefits: for example, keywords are boosted in headings.</li> + <li>Accessibility benefits: Assistive technology (AT) such as screen readers use headings (and other landmarks) as signposts to navigate content. HTML documents are very difficult for AT users to use without headings.</li> + </ul> </td> </tr> </tbody> diff --git a/files/en-us/learn_web_development/core/structuring_content/html_forms/index.md b/files/en-us/learn_web_development/core/structuring_content/html_forms/index.md index 7388c403ee2ef33..2f47695a7b55919 100644 --- a/files/en-us/learn_web_development/core/structuring_content/html_forms/index.md +++ b/files/en-us/learn_web_development/core/structuring_content/html_forms/index.md @@ -1,11 +1,11 @@ --- title: Forms and buttons in HTML +short-title: Forms and buttons slug: Learn_web_development/Core/Structuring_content/HTML_forms page-type: tutorial-chapter +sidebar: learnsidebar --- -{{LearnSidebar}} - {{PreviousMenuNext("Learn_web_development/Core/Structuring_content/Planet_data_table", "Learn_web_development/Core/Structuring_content/Debugging_HTML", "Learn_web_development/Core/Structuring_content")}} HTML forms and buttons are powerful tools for interacting with a website's users. Most commonly, they provide users with controls to manipulate a user interface (UI) or input data when required. @@ -145,7 +145,7 @@ Because of the way MDN works, you can enter text into the input fields, but you As we said earlier, the {{htmlelement("form")}} element acts as the outer wrapper for the form, grouping together all the form controls inside it. When the `<button>` is pressed, all the data represented by the form controls will be submitted to the server. The `<form>` element can take many attributes, but the two most important ones, which we've included here, are as follows: - `action`: Contains a path to the page that we want to send the submitted form data to, to be processed. Later on, after you submit the form, you'll see `/submit_page` included in the URL. You'll also get a {{HTTPStatus("404")}} error response because the page doesn't actually exist, but that's fine for now. -- `method`: Specifies the data transmission [method](/en-US/docs/Web/HTTP/Methods) you want to use for sending the form data to the server. Don't worry about this too much for now; the `get` value causes the data to be sent as parameters attached to the end of the URL. +- `method`: Specifies the data transmission [method](/en-US/docs/Web/HTTP/Reference/Methods) you want to use for sending the form data to the server. Don't worry about this too much for now; the `get` value causes the data to be sent as parameters attached to the end of the URL. > [!CALLOUT] > @@ -161,11 +161,11 @@ As we said earlier, the {{htmlelement("form")}} element acts as the outer wrappe You can include any HTML elements you like inside a `<form>` element to structure the form elements themselves and provide containers to target with CSS for styling, etc. -In our example, we've included a [heading element](/en-US/docs/Web/HTML/Element/Heading_Elements) (`<h2>`) to describe the purpose of the form. +In our example, we've included a [heading element](/en-US/docs/Web/HTML/Reference/Elements/Heading_Elements) (`<h2>`) to describe the purpose of the form. We've also put each input/label pair and the submit button inside a separate {{htmlelement("p")}}, so that each will appear on a separate line. These elements are all inline by default, meaning that if we didn't do this, they would all sit on the same line. -This is a common pattern for form structuring. Some people use `<p>` elements to separate out their form elements, some use {{htmlelement("div")}}, {{htmlelement("section")}}, or even {{htmlelement("li")}} elements. It doesn't matter a great deal, as long as the elements used make semantic sense. For example, it makes sense to divide form element groups up into separate paragraphs or sections of content, or even items in a list. It would make less sense to represent them as [blockquotes](/en-US/docs/Web/HTML/Element/blockquote), [asides](/en-US/docs/Web/HTML/Element/aside), or [addresses](/en-US/docs/Web/HTML/Element/address). +This is a common pattern for form structuring. Some people use `<p>` elements to separate out their form elements, some use {{htmlelement("div")}}, {{htmlelement("section")}}, or even {{htmlelement("li")}} elements. It doesn't matter a great deal, as long as the elements used make semantic sense. For example, it makes sense to divide form element groups up into separate paragraphs or sections of content, or even items in a list. It would make less sense to represent them as [blockquotes](/en-US/docs/Web/HTML/Reference/Elements/blockquote), [asides](/en-US/docs/Web/HTML/Reference/Elements/aside), or [addresses](/en-US/docs/Web/HTML/Reference/Elements/address). There is a specialized element for grouping form elements together called {{htmlelement("fieldset")}}. This is useful in certain circumstances, such as in complex forms, and when grouping together multiple checkboxes and radio buttons. We'll look at a couple of `<fieldset>` examples later on. @@ -184,7 +184,7 @@ The attributes are as follows: - `id`: Specifies an ID that can be used to identify the element. In this case, it is used to associate the form control with its `<label>`. - `required`: Specifies that a value has to be entered into the form element before the form can be submitted. This should only be set on inputs that you require, not on optional fields. -You should be aware that some input types usually don't get their values from text entered into a field. For example, [`<input type="color">`](/en-US/docs/Web/HTML/Element/input/color) renders a color picker widget that you choose a color from, whereas [`<input type="radio">`](/en-US/docs/Web/HTML/Element/input/radio) renders a radio button control that can be selected, or not. +You should be aware that some input types usually don't get their values from text entered into a field. For example, [`<input type="color">`](/en-US/docs/Web/HTML/Reference/Elements/input/color) renders a color picker widget that you choose a color from, whereas [`<input type="radio">`](/en-US/docs/Web/HTML/Reference/Elements/input/radio) renders a radio button control that can be selected, or not. In the case of radio buttons, you generally need to provide the value that would be submitted if it is selected inside a specific `value` attribute. Note that you _can_ specify a `value` attribute on input types like `text` and `color` — the effect is that the value is pre-filled into the form field when it is first rendered. @@ -198,13 +198,13 @@ In the case of radio buttons, you generally need to provide the value that would #### Specialized text field inputs -The second exercise above raises an interesting point. The second input field specifically expects an email address, and validates entered values as such. If you look at the form code again, you'll see why — the second `<input>` has a `type` of `email`. There are several specialized text field input types designed to handle specific types of data — [`<input type="number">`](/en-US/docs/Web/HTML/Element/input/number), [`<input type="password">`](/en-US/docs/Web/HTML/Element/input/password), [`<input type="tel">`](/en-US/docs/Web/HTML/Element/input/tel), etc. +The second exercise above raises an interesting point. The second input field specifically expects an email address, and validates entered values as such. If you look at the form code again, you'll see why — the second `<input>` has a `type` of `email`. There are several specialized text field input types designed to handle specific types of data — [`<input type="number">`](/en-US/docs/Web/HTML/Reference/Elements/input/number), [`<input type="password">`](/en-US/docs/Web/HTML/Reference/Elements/input/password), [`<input type="tel">`](/en-US/docs/Web/HTML/Reference/Elements/input/tel), etc. > [!CALLOUT] > > **Try it out** > -> Follow some of the links above to find out what these input types are used for. Have a look around our [`<input>`](/en-US/docs/Web/HTML/Element/input) reference and see if you can find any more specialized text field input types. +> Follow some of the links above to find out what these input types are used for. Have a look around our [`<input>`](/en-US/docs/Web/HTML/Reference/Elements/input) reference and see if you can find any more specialized text field input types. ### `<label>` elements @@ -250,7 +250,7 @@ There are other button behaviors that can be specified via the `<button>` elemen - `<button type="button">` creates a button with the same behavior as buttons specified outside of `<form>` elements. As we saw earlier, they do absolutely nothing by default, and JavaScript is needed to give them functionality. > [!NOTE] -> You can also create the above button types using an `<input>` element with the same `type` values specified — [`<input type="submit">`](/en-US/docs/Web/HTML/Element/input/submit), [`<input type="reset">`](/en-US/docs/Web/HTML/Element/input/reset), and [`<input type="button">`](/en-US/docs/Web/HTML/Element/input/button). However, these have many disadvantages compared to their `<button>` counterparts. You should use `<button>` instead. +> You can also create the above button types using an `<input>` element with the same `type` values specified — [`<input type="submit">`](/en-US/docs/Web/HTML/Reference/Elements/input/submit), [`<input type="reset">`](/en-US/docs/Web/HTML/Reference/Elements/input/reset), and [`<input type="button">`](/en-US/docs/Web/HTML/Reference/Elements/input/button). However, these have many disadvantages compared to their `<button>` counterparts. You should use `<button>` instead. ## An aside on accessibility @@ -276,36 +276,42 @@ There are many other control types you can use to collect data in a form. Let's ```html live-sample___form-other-controls <form action="./payment_page" method="get"> <h2>Register for the meetup</h2> - <p> - <fieldset> - <legend>Choose hotel room type (required):</legend> - <div> - <input type="radio" id="hotelChoice1" name="hotel" value="economy" checked /> - <label for="hotelChoice1">Economy (+$0)</label> - - <input type="radio" id="hotelChoice2" name="hotel" value="superior" /> - <label for="hotelChoice2">Superior (+$50)</label> - - <input type="radio" id="hotelChoice3" name="hotel" value="penthouse" disabled /> - <label for="hotelChoice3">Penthouse (+$150)</label> - </div> - </fieldset> - </p> - <p> - <fieldset> - <legend>Choose classes to attend:</legend> - <div> - <input type="checkbox" id="yoga" name="yoga" /> - <label for="yoga">Yoga (+$10)</label> - - <input type="checkbox" id="coffee" name="coffee" /> - <label for="coffee">Coffee roasting (+$20)</label> - - <input type="checkbox" id="balloon" name="balloon" /> - <label for="balloon">Balloon animal art (+$5)</label> - </div> - </fieldset> - </p> + <fieldset> + <legend>Choose hotel room type (required):</legend> + <div> + <input + type="radio" + id="hotelChoice1" + name="hotel" + value="economy" + checked /> + <label for="hotelChoice1">Economy (+$0)</label> + + <input type="radio" id="hotelChoice2" name="hotel" value="superior" /> + <label for="hotelChoice2">Superior (+$50)</label> + + <input + type="radio" + id="hotelChoice3" + name="hotel" + value="penthouse" + disabled /> + <label for="hotelChoice3">Penthouse (+$150)</label> + </div> + </fieldset> + <fieldset> + <legend>Choose classes to attend:</legend> + <div> + <input type="checkbox" id="yoga" name="yoga" /> + <label for="yoga">Yoga (+$10)</label> + + <input type="checkbox" id="coffee" name="coffee" /> + <label for="coffee">Coffee roasting (+$20)</label> + + <input type="checkbox" id="balloon" name="balloon" /> + <label for="balloon">Balloon animal art (+$5)</label> + </div> + </fieldset> <p> <label for="transport">How are you getting here:</label> <select name="transport" id="transport"> @@ -342,21 +348,31 @@ We'd recommend that you open this example in a separate browser tab as you work ### Radio buttons -The "Choose hotel room type" buttons are implemented using [`<input type="radio">`](/en-US/docs/Web/HTML/Element/input/radio) controls. These render as a set of push button controls where only one of the set can be selected at any one time — you can't select more than one at once. They are named after the buttons found on old-fashioned radios, where you press one button and the previously-selected one pops out again. +The "Choose hotel room type" buttons are implemented using [`<input type="radio">`](/en-US/docs/Web/HTML/Reference/Elements/input/radio) controls. These render as a set of push button controls where only one of the set can be selected at any one time — you can't select more than one at once. They are named after the buttons found on old-fashioned radios, where you press one button and the previously-selected one pops out again. Our example code look looks like this: -```html-nolint +```html <fieldset> <legend>Choose hotel room type (required):</legend> <div> - <input type="radio" id="hotelChoice1" name="hotel" value="economy" checked /> + <input + type="radio" + id="hotelChoice1" + name="hotel" + value="economy" + checked /> <label for="hotelChoice1">Economy (+$0)</label> <input type="radio" id="hotelChoice2" name="hotel" value="superior" /> <label for="hotelChoice2">Superior (+$50)</label> - <input type="radio" id="hotelChoice3" name="hotel" value="penthouse" disabled /> + <input + type="radio" + id="hotelChoice3" + name="hotel" + value="penthouse" + disabled /> <label for="hotelChoice3">Penthouse (+$150)</label> </div> </fieldset> @@ -393,9 +409,9 @@ You can set the `disabled` attribute on any form control, including `<button>` e ### Checkboxes -Our "classes to attend" selectors are implemented using [`<input type="checkbox">`](/en-US/docs/Web/HTML/Element/input/checkbox) controls. these render as a set of on/off state checkboxes. Unlike radio buttons, you can select more than one at once. +Our "classes to attend" selectors are implemented using [`<input type="checkbox">`](/en-US/docs/Web/HTML/Reference/Elements/input/checkbox) controls. these render as a set of on/off state checkboxes. Unlike radio buttons, you can select more than one at once. -```html-nolint +```html <fieldset> <legend>Choose classes to attend:</legend> <div> @@ -422,7 +438,7 @@ The main difference (apart from the `type` value!) is that each checkbox has a d Drop-down menus, for example the "How are you getting here" selection control in our example, are implemented not with an `<input>` type, but with the {{htmlelement("select")}} and {{htmlelement("option")}} elements: -```html-nolint +```html <label for="transport">How are you getting here:</label> <select name="transport" id="transport"> <option value="">--Please choose an option--</option> @@ -446,7 +462,7 @@ Each possible value for the data item is represented by an `<option>` element, n Multi-line text input fields are created using {{htmlelement("textarea")}} elements: -```html-nolint +```html <label for="comments">Any other comments:</label> <textarea id="comments" name="comments" rows="5" cols="33"></textarea> ``` diff --git a/files/en-us/learn_web_development/core/structuring_content/html_images/index.md b/files/en-us/learn_web_development/core/structuring_content/html_images/index.md index 27e806577b751ee..c94d04644ed2bb4 100644 --- a/files/en-us/learn_web_development/core/structuring_content/html_images/index.md +++ b/files/en-us/learn_web_development/core/structuring_content/html_images/index.md @@ -1,11 +1,11 @@ --- title: HTML images +short-title: Images slug: Learn_web_development/Core/Structuring_content/HTML_images page-type: tutorial-chapter +sidebar: learnsidebar --- -{{LearnSidebar}} - {{PreviousMenuNext("Learn_web_development/Core/Structuring_content/Structuring_a_page_of_content", "Learn_web_development/Core/Structuring_content/HTML_video_and_audio", "Learn_web_development/Core/Structuring_content")}} In the beginning, the web was just text, and it was really quite boring. Fortunately, it wasn't too long before the ability to embed images (and other more interesting types of content) inside web pages was added. In this article we'll look at how to use the {{htmlelement("img")}} element in depth, including the basics, annotating it with captions using {{htmlelement("figure")}}, and detailing how it relates to {{glossary("CSS")}} background images. @@ -84,7 +84,7 @@ The previous code snippet, either with the absolute or the relative URL, will gi ![A basic image of a dinosaur, embedded in a browser, with "Images in HTML" written above it](basic-image.png) > [!NOTE] -> Elements like {{htmlelement("img")}} and {{htmlelement("video")}} are sometimes referred to as **replaced elements**. This is because the element's content and size are defined by an external resource (like an image or video file), not by the contents of the element itself. You can read more about them at [Replaced elements](/en-US/docs/Web/CSS/Replaced_element). +> Elements like {{htmlelement("img")}} and {{htmlelement("video")}} are sometimes referred to as **replaced elements**. This is because the element's content and size are defined by an external resource (like an image or video file), not by the contents of the element itself. You can read more about them at {{ glossary("replaced elements")}}. > [!NOTE] > You can find the finished example from this section [running on GitHub](https://mdn.github.io/learning-area/html/multimedia-and-embedding/images-in-html/index.html) (see the [source code](https://github.com/mdn/learning-area/blob/main/html/multimedia-and-embedding/images-in-html/index.html) too.) @@ -126,7 +126,7 @@ Essentially, the key is to deliver a usable experience, even when the images can ### Width and height -You can use the [`width`](/en-US/docs/Web/HTML/Element/img#width) and [`height`](/en-US/docs/Web/HTML/Element/img#height) attributes to specify the width and height of your image. They are given as integers without a unit, and represent the image's width and height in pixels. +You can use the [`width`](/en-US/docs/Web/HTML/Reference/Elements/img#width) and [`height`](/en-US/docs/Web/HTML/Reference/Elements/img#height) attributes to specify the width and height of your image. They are given as integers without a unit, and represent the image's width and height in pixels. You can find your image's width and height in a number of ways. For example, on the Mac you can use <kbd>Cmd</kbd> + <kbd>I</kbd> to get the display information for the image file. Returning to our example, we could do this: @@ -206,7 +206,7 @@ This gives us a tooltip on mouse hover, just like link titles: ![The dinosaur image, with a tooltip title on top of it that reads A T-Rex on display at the Manchester University Museum](image-with-title.png) -However, this is not recommended — `title` has a number of accessibility problems, mainly based around the fact that screen reader support is very unpredictable and most browsers won't show it unless you are hovering with a mouse (so e.g. no access to keyboard users). If you are interested in more information about this, read [The Trials and Tribulations of the Title Attribute](https://www.24a11y.com/2017/the-trials-and-tribulations-of-the-title-attribute/) by Scott O'Hara. +However, this is not recommended — `title` has a number of accessibility problems, mainly based around the fact that screen reader support is very unpredictable and most browsers won't show it unless you are hovering with a mouse (so e.g., no access to keyboard users). If you are interested in more information about this, read [The Trials and Tribulations of the Title Attribute](https://www.24a11y.com/2017/the-trials-and-tribulations-of-the-title-attribute/) by Scott O'Hara. It is better to include such supporting information in the main article text, rather than attached to the image. @@ -376,7 +376,7 @@ Authors are not required to include a copyright notice or license terms with the #### Permissive -If the image is released under a permissive license, such as [MIT](https://mit-license.org/), [BSD](https://opensource.org/license/BSD-3-clause), or a suitable [Creative Commons (CC) license](https://chooser-beta.creativecommons.org/), you do not need to pay a license fee or seek permission to use it. Still, there are various licensing conditions you will have to fulfill, which vary by license. +If the image is released under a permissive license, such as [MIT](https://mit-license.org/), [BSD](https://opensource.org/license/BSD-3-clause), or a suitable [Creative Commons (CC) license](https://creativecommons.org/chooser/), you do not need to pay a license fee or seek permission to use it. Still, there are various licensing conditions you will have to fulfill, which vary by license. For example, you might have to: @@ -455,7 +455,7 @@ A better solution, is to use the HTML {{htmlelement("figure")}} and {{htmlelemen The {{htmlelement("figcaption")}} element tells browsers, and assistive technology that the caption describes the other content of the {{htmlelement("figure")}} element. > [!NOTE] -> From an accessibility viewpoint, captions and [`alt`](/en-US/docs/Web/HTML/Element/img#alt) text have distinct roles. Captions benefit even people who can see the image, whereas [`alt`](/en-US/docs/Web/HTML/Element/img#alt) text provides the same functionality as an absent image. Therefore, captions and `alt` text shouldn't just say the same thing, because they both appear when the image is gone. Try turning images off in your browser and see how it looks. +> From an accessibility viewpoint, captions and [`alt`](/en-US/docs/Web/HTML/Reference/Elements/img#alt) text have distinct roles. Captions benefit even people who can see the image, whereas [`alt`](/en-US/docs/Web/HTML/Reference/Elements/img#alt) text provides the same functionality as an absent image. Therefore, captions and `alt` text shouldn't just say the same thing, because they both appear when the image is gone. Try turning images off in your browser and see how it looks. A figure doesn't have to be an image. It is an independent unit of content that: @@ -619,7 +619,7 @@ Summing up: if an image has meaning, in terms of your content, you should use an ## Test your skills! -You've reached the end of this article, but can you remember the most important information? You can find some further tests to verify that you've retained this information before you move on — see [Test your skills: HTML images](/en-US/docs/Learn_web_development/Core/Structuring_content/HTML_images/Test_your_skills:_HTML_images). +You've reached the end of this article, but can you remember the most important information? You can find some further tests to verify that you've retained this information before you move on — see [Test your skills: HTML images](/en-US/docs/Learn_web_development/Core/Structuring_content/Test_your_skills/Images). ## Summary diff --git a/files/en-us/learn_web_development/core/structuring_content/html_images/test_your_skills_colon__html_images/index.md b/files/en-us/learn_web_development/core/structuring_content/html_images/test_your_skills_colon__html_images/index.md deleted file mode 100644 index ee4610940f62b6f..000000000000000 --- a/files/en-us/learn_web_development/core/structuring_content/html_images/test_your_skills_colon__html_images/index.md +++ /dev/null @@ -1,54 +0,0 @@ ---- -title: "Test your skills: HTML images" -slug: Learn_web_development/Core/Structuring_content/HTML_images/Test_your_skills:_HTML_images -page-type: learn-module-assessment ---- - -{{learnsidebar}} - -The aim of this skill test is to assess whether you understand [images and how to embed them in HTML](/en-US/docs/Learn_web_development/Core/Structuring_content/HTML_images). - -> [!NOTE] -> You can try solutions in the interactive editors on this page or in an online editor such as [CodePen](https://codepen.io/), [JSFiddle](https://jsfiddle.net/), or [Glitch](https://glitch.com/). -> -> If you get stuck, you can reach out to us in one of our [communication channels](/en-US/docs/MDN/Community/Communication_channels). - -## Task 1 - -In this task, we want you to embed an image of some Blueberries into the page. You need to: - -- Add the path to the image to an appropriate attribute to embed it on the page. The image is called `blueberries.jpg`, and it is in a folder inside the current folder called `images`. -- Add some alternative text to an appropriate attribute to describe the image, for people that cannot see it. -- Give the `<img>` element an appropriate `width` and `height` so that it displays at the correct {{glossary("aspect ratio")}}, and enough space is left on the page to display it. The image's {{glossary("intrinsic size")}} is 615 x 419 pixels. - -Try updating the live code below to recreate the finished example: - -{{EmbedGHLiveSample("learning-area/html/multimedia-and-embedding/tasks/images/images1.html", '100%', 700)}} - -> [!CALLOUT] -> -> [Download the starting point for this task](https://github.com/mdn/learning-area/blob/main/html/multimedia-and-embedding/tasks/images/images1-download.html) to work in your own editor or in an online editor. - -## Task 2 - -In this task, you already have a full-featured image, but we'd like you to add a tooltip that appears when the image is moused over. You should put some appropriate information into the tooltip. - -Try updating the live code below to recreate the finished example: - -{{EmbedGHLiveSample("learning-area/html/multimedia-and-embedding/tasks/images/images2.html", '100%', 1000)}} - -> [!CALLOUT] -> -> [Download the starting point for this task](https://github.com/mdn/learning-area/blob/main/html/multimedia-and-embedding/tasks/images/images2-download.html) to work in your own editor or in an online editor. - -## Task 3 - -In this task, you are provided with both a full-featured image and some caption text. What you need to do here is add elements that will associate the image with the caption. - -Try updating the live code below to recreate the finished example: - -{{EmbedGHLiveSample("learning-area/html/multimedia-and-embedding/tasks/images/images3.html", '100%', 1000)}} - -> [!CALLOUT] -> -> [Download the starting point for this task](https://github.com/mdn/learning-area/blob/main/html/multimedia-and-embedding/tasks/images/images3-download.html) to work in your own editor or in an online editor. diff --git a/files/en-us/learn_web_development/core/structuring_content/html_table_basics/index.md b/files/en-us/learn_web_development/core/structuring_content/html_table_basics/index.md index 3fa5f623b3a7da4..c0f1b43d75f4c01 100644 --- a/files/en-us/learn_web_development/core/structuring_content/html_table_basics/index.md +++ b/files/en-us/learn_web_development/core/structuring_content/html_table_basics/index.md @@ -1,11 +1,11 @@ --- title: HTML table basics +short-title: Table basics slug: Learn_web_development/Core/Structuring_content/HTML_table_basics page-type: learn-module-chapter +sidebar: learnsidebar --- -{{LearnSidebar}} - {{PreviousMenuNext("Learn_web_development/Core/Structuring_content/Mozilla_splash_page", "Learn_web_development/Core/Structuring_content/Table_accessibility", "Learn_web_development/Core/Structuring_content")}} This article gets you started with HTML tables, covering the very basics such as rows, cells, headings, making cells span multiple columns and rows, and how to group together all the cells in a column for styling purposes. @@ -226,9 +226,9 @@ Be under no illusion; for tables to be effective on the web, you need to provide We won't focus on CSS in this module, but we have provided a minimal CSS stylesheet for you to use that will make your tables more readable than the default you get without any styling. You can find the [stylesheet here](https://github.com/mdn/learning-area/blob/main/html/tables/basic/minimal-table.css), and you can also find an [HTML template](https://github.com/mdn/learning-area/blob/main/html/tables/basic/blank-template.html) that applies the stylesheet — these together will give you a good starting point for experimenting with HTML tables. -### When should you NOT use HTML tables? +### When should you avoid HTML tables? -HTML tables should be used for tabular data — this is what they are designed for. Unfortunately, a lot of people used to use HTML tables to lay out web pages, e.g. one row to contain the header, one row to contain the content columns, one row to contain the footer, etc. You can find more details and an example at [Page Layouts](/en-US/docs/Learn_web_development/Core/Accessibility/HTML#page_layouts) in our [Accessibility Learning Module](/en-US/docs/Learn_web_development/Core/Accessibility). This was commonly used because CSS support across browsers used to be terrible; table layouts are much less common nowadays, but you might still see them in some corners of the web. +HTML tables should be used for tabular data (information that's easy to work with in rows and columns) — this is what they are designed for. Unfortunately, a lot of people used to use HTML tables to lay out web pages, for example one row to contain a page header, a row to contain each content column, one row to contain the footer, etc. This technique was used because CSS support across browsers used to be a lot more limited. Modern browsers have solid CSS support so table-based layouts are now extremely rare, but you might still see them in some corners of the web. In short, using tables for layout rather than [CSS layout techniques](/en-US/docs/Learn_web_development/Core/CSS_layout) is a bad idea. The main reasons are as follows: @@ -241,8 +241,8 @@ In short, using tables for layout rather than [CSS layout techniques](/en-US/doc We've talked table theory enough, so, let's dive into a practical example and build up a simple table. 1. First of all, make a local copy of [blank-template.html](https://github.com/mdn/learning-area/blob/main/html/tables/basic/blank-template.html) and [minimal-table.css](https://github.com/mdn/learning-area/blob/main/html/tables/basic/minimal-table.css) in a new directory on your local machine. -2. The content of every table is enclosed by these two tags: **[`<table></table>`](/en-US/docs/Web/HTML/Element/table)**. Add these inside the body of your HTML. -3. The smallest container inside a table is a table cell, which is created by a **[`<td>`](/en-US/docs/Web/HTML/Element/td)** element ('td' stands for 'table data'). Add the following inside your table tags: +2. The content of every table is enclosed by these two tags: **[`<table></table>`](/en-US/docs/Web/HTML/Reference/Elements/table)**. Add these inside the body of your HTML. +3. The smallest container inside a table is a table cell, which is created by a **[`<td>`](/en-US/docs/Web/HTML/Reference/Elements/td)** element ('td' stands for 'table data'). Add the following inside your table tags: ```html <td>Hi, I'm your first cell.</td> @@ -259,7 +259,7 @@ We've talked table theory enough, so, let's dive into a practical example and bu As you will see, the cells are not placed underneath each other, rather they are automatically aligned with each other on the same row. Each `<td>` element creates a single cell and together they make up the first row. Every cell we add makes the row grow longer. -To stop this row from growing and start placing subsequent cells on a second row, we need to use the **[`<tr>`](/en-US/docs/Web/HTML/Element/tr)** element ('tr' stands for 'table row'). Let's investigate this now. +To stop this row from growing and start placing subsequent cells on a second row, we need to use the **[`<tr>`](/en-US/docs/Web/HTML/Reference/Elements/tr)** element ('tr' stands for 'table row'). Let's investigate this now. 1. Place the four cells you've already created inside `<tr>` tags, like so: @@ -378,7 +378,7 @@ The problem here is that, while you can kind of make out what's going on, it is Let's have a go at improving this table. 1. First, make a local copy of our [dogs-table.html](https://github.com/mdn/learning-area/blob/main/html/tables/basic/dogs-table.html) and [minimal-table.css](https://github.com/mdn/learning-area/blob/main/html/tables/basic/minimal-table.css) files in a new directory on your local machine. The HTML contains the same Dogs example as you saw above. -2. To recognize the table headers as headers, both visually and semantically, you can use the **[`<th>`](/en-US/docs/Web/HTML/Element/th)** element ('th' stands for 'table header'). This works in exactly the same way as a `<td>`, except that it denotes a header, not a normal cell. Go into your HTML, and change all the `<td>` elements surrounding the table headers into `<th>` elements. +2. To recognize the table headers as headers, both visually and semantically, you can use the **[`<th>`](/en-US/docs/Web/HTML/Reference/Elements/th)** element ('th' stands for 'table header'). This works in exactly the same way as a `<td>`, except that it denotes a header, not a normal cell. Go into your HTML, and change all the `<td>` elements surrounding the table headers into `<th>` elements. 3. Save your HTML and load it in a browser, and you should see that the headers now look like headers. > [!NOTE] diff --git a/files/en-us/learn_web_development/core/structuring_content/html_video_and_audio/index.md b/files/en-us/learn_web_development/core/structuring_content/html_video_and_audio/index.md index 21221da3e2f3ca1..153744e7799f0af 100644 --- a/files/en-us/learn_web_development/core/structuring_content/html_video_and_audio/index.md +++ b/files/en-us/learn_web_development/core/structuring_content/html_video_and_audio/index.md @@ -1,11 +1,11 @@ --- title: HTML video and audio +short-title: Video and audio slug: Learn_web_development/Core/Structuring_content/HTML_video_and_audio page-type: tutorial-chapter +sidebar: learnsidebar --- -{{LearnSidebar}} - {{PreviousMenuNext("Learn_web_development/Core/Structuring_content/HTML_images", "Learn_web_development/Core/Structuring_content/Mozilla_splash_page", "Learn_web_development/Core/Structuring_content")}} Now that we are comfortable with adding simple images to a webpage, the next step is to start adding video and audio players to your HTML documents! In this article we'll look at doing just that with the {{htmlelement("video")}} and {{htmlelement("audio")}} elements; we'll then finish off by looking at how to add captions/subtitles to your videos. @@ -63,9 +63,9 @@ The {{htmlelement("video")}} element allows you to embed a video very easily. A The features to note are: -- [`src`](/en-US/docs/Web/HTML/Element/video#src) +- [`src`](/en-US/docs/Web/HTML/Reference/Elements/video#src) - : In the same way as for the {{htmlelement("img")}} element, the `src` (source) attribute contains a path to the video you want to embed. It works in exactly the same way. -- [`controls`](/en-US/docs/Web/HTML/Element/video#controls) +- [`controls`](/en-US/docs/Web/HTML/Reference/Elements/video#controls) - : Users must be able to control video and audio playback (it's especially critical for people who have [epilepsy](https://en.wikipedia.org/wiki/Epilepsy#Epidemiology).) You must either use the `controls` attribute to include the browser's own control interface, or build your interface using the appropriate [JavaScript API](/en-US/docs/Web/API/HTMLMediaElement). At a minimum, the interface must include a way to start and stop the media, and to adjust the volume. - The paragraph inside the `<video>` tags - : This is called **fallback content** — this will be displayed if the browser accessing the page doesn't support the `<video>` element, allowing us to provide a fallback for older browsers. This can be anything you like; in this case, we've provided a direct link to the video file, so the user can at least access it some way regardless of what browser they are using. @@ -82,13 +82,13 @@ There's a problem with the above example. It is possible that the video might no ### Contents of a media file -First, let's go through the terminology quickly. Formats like MP3, MP4 and WebM are called **[container formats](/en-US/docs/Web/Media/Guides/Formats/Containers)**. They define a structure in which the audio and/or video tracks that make up the media are stored, along with metadata describing the media, what codecs are used to encode its channels, and so forth. +First, let's go through the terminology quickly. Formats like OGG, WAV, MP4 and WebM are called **[container formats](/en-US/docs/Web/Media/Guides/Formats/Containers)**. They define a structure in which the audio and/or video tracks that make up the media are stored, along with metadata describing the media, what codecs are used to encode its channels, and so forth. A WebM file containing a movie which has a main video track and one alternate angle track, plus audio for both English and Spanish, in addition to audio for an English commentary track can be conceptualized as shown in the diagram below. Also included are text tracks containing closed captions for the feature film, Spanish subtitles for the film, and English captions for the commentary. ![Diagram conceptualizing the contents of a media file at the track level.](containersandtracks.png) -The audio and video tracks within the container hold data in the appropriate format for the codec used to encode that media. Different formats are used for audio tracks versus video tracks. Each audio track is encoded using an [audio codec](/en-US/docs/Web/Media/Guides/Formats/Audio_codecs), while video tracks are encoded using (as you probably have guessed) [a video codec](/en-US/docs/Web/Media/Guides/Formats/Video_codecs). As we talked about before, different browsers support different video and audio formats, and different container formats (like MP3, MP4, and WebM, which in turn can contain different types of video and audio). +The audio and video tracks within the container hold data in the appropriate format for the codec used to encode that media. Different formats are used for audio tracks versus video tracks. Each audio track is encoded using an [audio codec](/en-US/docs/Web/Media/Guides/Formats/Audio_codecs), while video tracks are encoded using (as you probably have guessed) [a video codec](/en-US/docs/Web/Media/Guides/Formats/Video_codecs). As we talked about before, different browsers support different video and audio formats, and different container formats (like OGG, MP4, and WebM, which in turn can contain different types of video and audio). For example: @@ -98,9 +98,9 @@ For example: There are some special cases. For example, for some types of audio, a codec's data is often stored without a container, or with a simplified container. One such instance is the FLAC codec, which is stored most commonly in FLAC files, which are just raw FLAC tracks. -Another such situation is the always-popular MP3 file. An "MP3 file" is actually an MPEG-1 Audio Layer III (MP3) audio track stored within an MPEG or MPEG-2 container. This is especially interesting since while most browsers don't support using MPEG media in the {{HTMLElement("video")}} and {{HTMLElement("audio")}} elements, they may still support MP3 due to its popularity. +Another example is the ever-popular "MP3 file". An "MP3 file" is an audio file encoded using MPEG-1 Audio Layer III compression. While it can include metadata, it is not encapsulated within a separate MPEG or MPEG-2 container. Its widespread support in the {{htmlelement("audio")}} and {{htmlelement("video")}} elements is largely a testament to its enduring popularity. -An audio player will tend to play an audio track directly, e.g. an MP3 or Ogg file. These don't need containers. +An audio player will tend to play an audio track directly, e.g., an MP3 or Ogg file. These don't need containers. ### Media file support in browsers @@ -132,7 +132,7 @@ So how do we do this? Take a look at the following [updated example](https://git Here we've taken the `src` attribute out of the actual {{HTMLElement("video")}} tag, and instead included separate {{htmlelement("source")}} elements that point to their own sources. In this case the browser will go through the {{HTMLElement("source")}} elements and play the first one that it has the codec to support. Including WebM and MP4 sources should be enough to play your video on most platforms and browsers these days. -Each `<source>` element also has a [`type`](/en-US/docs/Web/HTML/Element/source#type) attribute. This is optional, but it is advised that you include it. The `type` attribute contains the {{glossary("MIME type")}} of the file specified by the `<source>`, and browsers can use the `type` to immediately skip videos they don't understand. If `type` isn't included, browsers will load and try to play each file until they find one that works, which obviously takes time and is an unnecessary use of resources. +Each `<source>` element also has a [`type`](/en-US/docs/Web/HTML/Reference/Elements/source#type) attribute. This is optional, but it is advised that you include it. The `type` attribute contains the {{glossary("MIME type")}} of the file specified by the `<source>`, and browsers can use the `type` to immediately skip videos they don't understand. If `type` isn't included, browsers will load and try to play each file until they find one that works, which obviously takes time and is an unnecessary use of resources. Refer to our [guide to media types and formats](/en-US/docs/Web/Media/Guides/Formats) for help selecting the best containers and codecs for your needs, as well as to look up the right MIME types to specify for each. @@ -165,17 +165,17 @@ The resulting UI looks something like this: Features include: -- [`width`](/en-US/docs/Web/HTML/Element/video#width) and [`height`](/en-US/docs/Web/HTML/Element/video#height) +- [`width`](/en-US/docs/Web/HTML/Reference/Elements/video#width) and [`height`](/en-US/docs/Web/HTML/Reference/Elements/video#height) - : You can control the video size either with these attributes or with {{Glossary("CSS")}}. In both cases, videos maintain their native width-height ratio — known as the **aspect ratio**. If the aspect ratio is not maintained by the sizes you set, the video will grow to fill the space horizontally, and the unfilled space will just be given a solid background color by default. -- [`autoplay`](/en-US/docs/Web/HTML/Element/video#autoplay) +- [`autoplay`](/en-US/docs/Web/HTML/Reference/Elements/video#autoplay) - : Makes the audio or video start playing right away, while the rest of the page is loading. You are advised not to use autoplaying video (or audio) on your sites, because users can find it really annoying. -- [`loop`](/en-US/docs/Web/HTML/Element/video#loop) +- [`loop`](/en-US/docs/Web/HTML/Reference/Elements/video#loop) - : Makes the video (or audio) start playing again whenever it finishes. This can also be annoying, so only use if really necessary. -- [`muted`](/en-US/docs/Web/HTML/Element/video#muted) +- [`muted`](/en-US/docs/Web/HTML/Reference/Elements/video#muted) - : Causes the media to play with the sound turned off by default. -- [`poster`](/en-US/docs/Web/HTML/Element/video#poster) +- [`poster`](/en-US/docs/Web/HTML/Reference/Elements/video#poster) - : The URL of an image which will be displayed before the video is played. It is intended to be used for a splash screen or advertising screen. -- [`preload`](/en-US/docs/Web/HTML/Element/video#preload) +- [`preload`](/en-US/docs/Web/HTML/Reference/Elements/video#preload) - : Used for buffering large files; it can take one of three values: @@ -256,7 +256,7 @@ This is the second. To get this displayed along with the HTML media playback, you need to: 1. Save it as a `.vtt` file somewhere the server can serve (see below), such as in the same directory as the HTML file. -2. Link to the `.vtt` file with the {{htmlelement("track")}} element. `<track>` should be placed within `<audio>` or `<video>`, but after all `<source>` elements. Use the [`kind`](/en-US/docs/Web/HTML/Element/track#kind) attribute to specify whether the cues are `subtitles`, `captions`, or `descriptions`. Further, use [`srclang`](/en-US/docs/Web/HTML/Element/track#srclang) to tell the browser what language you have written the subtitles in. Finally, add [`label`](/en-US/docs/Web/HTML/Element/track#label) to help readers identify the language they are searching for. +2. Link to the `.vtt` file with the {{htmlelement("track")}} element. `<track>` should be placed within `<audio>` or `<video>`, but after all `<source>` elements. Use the [`kind`](/en-US/docs/Web/HTML/Reference/Elements/track#kind) attribute to specify whether the cues are `subtitles`, `captions`, or `descriptions`. Further, use [`srclang`](/en-US/docs/Web/HTML/Reference/Elements/track#srclang) to tell the browser what language you have written the subtitles in. Finally, add [`label`](/en-US/docs/Web/HTML/Reference/Elements/track#label) to help readers identify the language they are searching for. Here's an example: @@ -288,14 +288,14 @@ We would like you to: 1. Save your audio and video files in a new directory on your computer. 2. Create a new HTML file in the same directory, called `index.html`. 3. Add {{HTMLElement("audio")}} and {{HTMLElement("video")}} elements to the page; make them display the default browser controls. -4. Give both of them {{HTMLElement("source")}} elements so that browsers will find the audio format they support best and load it. These should include [`type`](/en-US/docs/Web/HTML/Element/source#type) attributes. +4. Give both of them {{HTMLElement("source")}} elements so that browsers will find the audio format they support best and load it. These should include [`type`](/en-US/docs/Web/HTML/Reference/Elements/source#type) attributes. 5. Give the `<video>` element a poster that will be displayed before the video starts to be played. Have fun creating your own poster graphic. For an added bonus, you could try researching text tracks, and work out how to add some captions to your video. ## Test your skills! -You've reached the end of this article, but can you remember the most important information? You can find some further tests to verify that you've retained this information before you move on — see [Test your skills: Multimedia and embedding](/en-US/docs/Learn_web_development/Core/Structuring_content/HTML_video_and_audio/Test_your_skills:_Multimedia_and_embedding). +You've reached the end of this article, but can you remember the most important information? You can find some further tests to verify that you've retained this information before you move on — see [Test your skills: Multimedia and embedding](/en-US/docs/Learn_web_development/Core/Structuring_content/Test_your_skills/Multimedia_and_embedding). ## Summary diff --git a/files/en-us/learn_web_development/core/structuring_content/html_video_and_audio/test_your_skills_colon__multimedia_and_embedding/index.md b/files/en-us/learn_web_development/core/structuring_content/html_video_and_audio/test_your_skills_colon__multimedia_and_embedding/index.md deleted file mode 100644 index 1eea08b0ae0cc2b..000000000000000 --- a/files/en-us/learn_web_development/core/structuring_content/html_video_and_audio/test_your_skills_colon__multimedia_and_embedding/index.md +++ /dev/null @@ -1,51 +0,0 @@ ---- -title: "Test your skills: Multimedia and embedding" -slug: Learn_web_development/Core/Structuring_content/HTML_video_and_audio/Test_your_skills:_Multimedia_and_embedding -page-type: learn-module-assessment ---- - -{{learnsidebar}} - -The aim of this skill test is to assess whether you understand how to [embed video and audio content in HTML](/en-US/docs/Learn_web_development/Core/Structuring_content/HTML_video_and_audio). - -> [!NOTE] -> You can try solutions in the interactive editors on this page or in an online editor such as [CodePen](https://codepen.io/), [JSFiddle](https://jsfiddle.net/), or [Glitch](https://glitch.com/). -> -> If you get stuck, you can reach out to us in one of our [communication channels](/en-US/docs/MDN/Community/Communication_channels). - -## Task 1 - -In this task, we want you to embed an audio file onto the page. You need to: - -- Add the path to the audio file to an appropriate attribute to embed it on the page. The audio is called `audio.mp3`, and it is in a folder inside the current folder called `media`. -- Add an attribute to make browsers display some default controls. -- Add some appropriate fallback text for browsers that don't support `<audio>`. - -Try updating the live code below to recreate the finished example: - -{{EmbedGHLiveSample("learning-area/html/multimedia-and-embedding/tasks/media-embed/mediaembed1.html", '100%', 700)}} - -> [!CALLOUT] -> -> [Download the starting point for this task](https://github.com/mdn/learning-area/blob/main/html/multimedia-and-embedding/tasks/media-embed/mediaembed1-download.html) to work in your own editor or in an online editor. - -## Task 2 - -In this task, we want you to mark up a slightly more complex video player, with multiple sources, subtitles, and other features besides. You need to: - -- Add an attribute to make browsers display some default controls. -- Add some appropriate fallback text for browsers that don't support `<video>`. -- Add multiple sources, containing the paths to the video files. The files are called `video.mp4` and `video.webm`, and are in a folder inside the current folder called `media`. -- Let the browser know in advance what video formats the sources point to, so it can make an informed choice of which one to download ahead of time. -- Give the `<video>` a width and height equal to its intrinsic size (320 by 240 pixels). -- Make the video muted by default. -- Display the text tracks contained in the `media` folder, in a file called `subtitles_en.vtt`, when the video is playing. You must explicitly set the type as subtitles, and the subtitle language to English. -- Make sure the readers can identify the subtitle language when they use the default controls. - -Try updating the live code below to recreate the finished example: - -{{EmbedGHLiveSample("learning-area/html/multimedia-and-embedding/tasks/media-embed/mediaembed2.html", '100%', 700)}} - -> [!CALLOUT] -> -> [Download the starting point for this task](https://github.com/mdn/learning-area/blob/main/html/multimedia-and-embedding/tasks/media-embed/mediaembed2-download.html) to work in your own editor or in an online editor. diff --git a/files/en-us/learn_web_development/core/structuring_content/including_vector_graphics_in_html/index.md b/files/en-us/learn_web_development/core/structuring_content/including_vector_graphics_in_html/index.md index 97061aecdc85fe6..5135c795b1841c1 100644 --- a/files/en-us/learn_web_development/core/structuring_content/including_vector_graphics_in_html/index.md +++ b/files/en-us/learn_web_development/core/structuring_content/including_vector_graphics_in_html/index.md @@ -1,11 +1,11 @@ --- title: Including vector graphics in HTML +short-title: Vector graphics slug: Learn_web_development/Core/Structuring_content/Including_vector_graphics_in_HTML page-type: learn-module-chapter +sidebar: learnsidebar --- -{{LearnSidebar}} - Vector graphics are very useful in many circumstances — they have small file sizes and are highly scalable, so they don't pixelate when zoomed in or blown up to a large size. In this article we'll show you how to include one in your webpage. <table> @@ -120,7 +120,7 @@ To embed an SVG via an {{htmlelement("img")}} element, you just need to referenc ### Troubleshooting and cross-browser support -For browsers that don't support SVG (IE 8 and below, Android 2.3 and below), you could reference a PNG or JPG from your `src` attribute and use a [`srcset`](/en-US/docs/Web/HTML/Element/img#srcset) attribute (which only recent browsers recognize) to reference the SVG. This being the case, only supporting browsers will load the SVG — older browsers will load the PNG instead: +For browsers that don't support SVG (IE 8 and below, Android 2.3 and below), you could reference a PNG or JPG from your `src` attribute and use a [`srcset`](/en-US/docs/Web/HTML/Reference/Elements/img#srcset) attribute (which only recent browsers recognize) to reference the SVG. This being the case, only supporting browsers will load the SVG — older browsers will load the PNG instead: ```html <img @@ -139,7 +139,7 @@ background-size: contain; Like the `<img>` method described above, inserting SVGs using CSS background images means that the SVG can't be manipulated with JavaScript, and is also subject to the same CSS limitations. -If your SVGs aren't showing up at all, it might be because your server isn't set up properly. If that's the problem, this [article will point you in the right direction](/en-US/docs/Web/SVG/Tutorial/Getting_Started#a_word_on_web_servers_for_.svgz_files). +If your SVGs aren't showing up at all, it might be because your server isn't set up properly. If that's the problem, this [article will point you in the right direction](/en-US/docs/Web/SVG/Tutorials/SVG_from_scratch/Getting_started#a_word_on_web_servers_for_.svgz_files). ### How to include SVG code inside your HTML @@ -154,7 +154,7 @@ You can also open up the SVG file in a text editor, copy the SVG code, and paste #### Pros - Putting your SVG inline saves an HTTP request, and therefore can reduce your loading time a bit. -- You can assign `class`es and `id`s to SVG elements and style them with CSS, either within the SVG or wherever you put the CSS style rules for your HTML document. In fact, you can use any [SVG presentation attribute](/en-US/docs/Web/SVG/Attribute#presentation_attributes) as a CSS property. +- You can assign `class`es and `id`s to SVG elements and style them with CSS, either within the SVG or wherever you put the CSS style rules for your HTML document. In fact, you can use any [SVG presentation attribute](/en-US/docs/Web/SVG/Reference/Attribute#presentation_attributes) as a CSS property. - Inlining SVG is the only approach that lets you use CSS interactions (like `:focus`) and CSS animations on your SVG image (even in your regular stylesheet.) - You can make SVG markup into a hyperlink by wrapping it in an {{htmlelement("a")}} element. @@ -186,7 +186,7 @@ This is definitely not the best method to choose: ## Active Learning: Playing with SVG -In this active learning section we'd like you to have a go at playing with some SVG for fun. In the _Input_ section below you'll see that we've already provided you with some samples to get you started. You can also go to the [SVG Element Reference](/en-US/docs/Web/SVG/Element), find out more details about other toys you can use in SVG, and try those out too. This section is all about practising your research skills, and having some fun. +In this active learning section we'd like you to have a go at playing with some SVG for fun. In the _Input_ section below you'll see that we've already provided you with some samples to get you started. You can also go to the [SVG Element Reference](/en-US/docs/Web/SVG/Reference/Element), find out more details about other toys you can use in SVG, and try those out too. This section is all about practising your research skills, and having some fun. If you get stuck and can't get your code working, you can always reset it using the _Reset_ button. @@ -252,7 +252,7 @@ function updateCode() { output.innerHTML = textarea.value; } -reset.addEventListener("click", function () { +reset.addEventListener("click", () => { textarea.value = code; userEntry = textarea.value; solutionEntry = htmlSolution; @@ -260,7 +260,7 @@ reset.addEventListener("click", function () { updateCode(); }); -solution.addEventListener("click", function () { +solution.addEventListener("click", () => { if (solution.value === "Show solution") { textarea.value = solutionEntry; solution.value = "Hide solution"; @@ -280,7 +280,7 @@ window.addEventListener("load", updateCode); // stop tab key tabbing out of textarea and // make it write a tab at the caret position instead -textarea.onkeydown = function (e) { +textarea.onkeydown = (e) => { if (e.code === "Tab") { e.preventDefault(); insertAtCaret("\t"); @@ -310,7 +310,7 @@ function insertAtCaret(text) { // Update the saved userCode every time the user updates the text area code -textarea.onkeyup = function () { +textarea.onkeyup = () => { // We only want to save the state when the user code is being shown, // not the solution, so that solution is not saved over the user code if (solution.value === "Show solution") { @@ -331,7 +331,7 @@ This article has provided you with a quick tour of what vector graphics and SVG ## See also -- [SVG tutorial](/en-US/docs/Web/SVG/Tutorial/Getting_Started) on MDN +- [SVG tutorial](/en-US/docs/Web/SVG/Tutorials/SVG_from_scratch/Getting_started) on MDN - [Sara Soueidan's tutorial on responsive SVG images](https://tympanus.net/codrops/2014/08/19/making-svgs-responsive-with-css/) - [Accessibility benefits of SVG](https://www.w3.org/TR/SVG-access/) - [SVG Properties and CSS](https://css-tricks.com/svg-properties-and-css/) diff --git a/files/en-us/learn_web_development/core/structuring_content/index.md b/files/en-us/learn_web_development/core/structuring_content/index.md index a3d8a4d55227712..30a8beda819235e 100644 --- a/files/en-us/learn_web_development/core/structuring_content/index.md +++ b/files/en-us/learn_web_development/core/structuring_content/index.md @@ -1,11 +1,11 @@ --- title: Structuring content with HTML +short-title: HTML slug: Learn_web_development/Core/Structuring_content page-type: landing-page +sidebar: learnsidebar --- -{{LearnSidebar}} - {{NextMenu("Learn_web_development/Core/Structuring_content/Basic_HTML_syntax", "Learn_web_development/Core")}} HTML is the technology that defines the content and structure of any website. Written properly, it should also define the semantics (meaning) of the content in a machine-readable way, which is vital for accessibility, search engine optimization, and making use of the built-in features browsers provide for content to work optimally. This module covers the basics of the language, before looking at key areas such as document structure, links, lists, images, forms, and more. @@ -21,7 +21,7 @@ Before starting this module, you don't need any previous HTML knowledge, but you - [Basic HTML syntax](/en-US/docs/Learn_web_development/Core/Structuring_content/Basic_HTML_syntax) - : Covers the absolute basics of {{glossary("HTML")}}, to get you started — we define elements, attributes, and other important terms, and show where they fit in the language. We also show how a typical HTML page is structured and how an HTML element is structured, and explain other important basic language features. Along the way, we'll play with some HTML to get you interested! -- [What's in the head? Webpage metadata](/en-US/docs/Learn_web_development/Core/Structuring_content/Webpage_metadata) +- [What's in the head? Web page metadata](/en-US/docs/Learn_web_development/Core/Structuring_content/Webpage_metadata) - : The {{Glossary("Head","head")}} of an HTML document is the part that **is not** displayed in the web browser when the page is loaded. It contains metadata information such as the page {{htmlelement("title")}}, links to {{glossary("CSS")}} (if you want to style your HTML content with CSS), links to custom favicons, and metadata (data about the HTML, such as who wrote it, and important keywords that describe the document). - [Headings and paragraphs](/en-US/docs/Learn_web_development/Core/Structuring_content/Headings_and_paragraphs) - : One of HTML's main jobs is to give text structure so that a browser can display an HTML document the way its developer intends. This article explains how HTML can be used to provide fundamental page structure by defining headings and paragraphs. @@ -32,7 +32,7 @@ Before starting this module, you don't need any previous HTML knowledge, but you - [Structuring documents](/en-US/docs/Learn_web_development/Core/Structuring_content/Structuring_documents) - : In addition to defining individual parts of your page (such as "a paragraph" or "an image"), HTML also boasts a number of block level elements used to define areas of your website (such as "the header", "the navigation menu", "the main content column"). This article looks into how to plan a basic website structure, and write the HTML to represent this structure. - [Advanced text features](/en-US/docs/Learn_web_development/Core/Structuring_content/Advanced_text_features) - - : There are many other elements in HTML for defining text semantics, which we didn't get to in the [Emphasis and importance](/en-US/docs/Learn_web_development/Core/Structuring_content/Emphasis_and_importance) article. The elements described in this article are less known, but still useful to know about (and this is still not a complete list by any means). Here you'll learn about marking up quotations, description lists, computer code and other related text, subscript and superscript, contact information, and more. + - : There are many other elements in HTML for defining text semantics, which we didn't get to in the [Emphasis and importance](/en-US/docs/Learn_web_development/Core/Structuring_content/Emphasis_and_importance) article. The elements described in this article are less known, but still useful to know about (and this is still not a complete list by any means). Here you'll learn about marking up quotations, computer code and other related text, subscript and superscript, contact information, and more. - [Creating links](/en-US/docs/Learn_web_development/Core/Structuring_content/Creating_links) - : Links (also known as hyperlinks) are really important — they are what makes the Web _a web_. This article shows the syntax required to make a link, and discusses link best practices. - [Marking up a letter](/en-US/docs/Learn_web_development/Core/Structuring_content/Marking_up_a_letter) <sup>Challenge</sup> @@ -55,6 +55,8 @@ Before starting this module, you don't need any previous HTML knowledge, but you - : HTML forms and buttons are powerful tools for interacting with users — most commonly they are used for collecting data from users or allowing them to control a user interface. In this article we provide an introduction to the basics of forms and buttons. - [Debugging HTML](/en-US/docs/Learn_web_development/Core/Structuring_content/Debugging_HTML) - : Writing HTML is fine, but what if something goes wrong, and you can't work out where the error in the code is? This article will introduce you to some tools that can help you find and fix errors in HTML. +- [Test your skills: HTML](/en-US/docs/Learn_web_development/Core/Structuring_content/Test_your_skills) + - : This page lists HTML tests you can try so you can verify if you've understood the content in this module. ## Additional tutorials @@ -67,11 +69,11 @@ These tutorials are not part of the learning pathway, but they are interesting n ## See also -- [Learn HTML](https://www.codecademy.com/learn/learn-html), Codecademy - - : A useful (and free resource) for learning HTML basics. -- [Learn HTML and CSS](https://v2.scrimba.com/learn-html-and-css-c0p?via=mdn), Scrimba <sup>_MDN learning partner_</sup> +- [Learn HTML and CSS](https://scrimba.com/learn-html-and-css-c0p?via=mdn), Scrimba <sup>[_MDN learning partner_](/en-US/docs/MDN/Writing_guidelines/Learning_content#partner_links_and_embeds)</sup> - : [Scrimba's](https://scrimba.com?via=mdn) _Learn HTML and CSS_ course teaches you HTML and CSS through building and deploying five awesome projects, with fun interactive lessons and challenges taught by knowledgeable teachers. -- [The basics of semantic HTML](https://v2.scrimba.com/the-frontend-developer-career-path-c0j/~0xid?via=mdn), Scrimba <sup>_MDN learning partner_</sup> +- [Learn HTML](https://www.codecademy.com/learn/learn-html), Codecademy + - : Another useful resource for learning HTML basics. +- [The basics of semantic HTML](https://scrimba.com/the-frontend-developer-career-path-c0j/~0xid?via=mdn), Scrimba <sup>[_MDN learning partner_](/en-US/docs/MDN/Writing_guidelines/Learning_content#partner_links_and_embeds)</sup> - : This interactive lesson provides a useful description of HTML, with particular emphasis on why the _semantic_ aspect of it is important. {{NextMenu("Learn_web_development/Core/Structuring_content/Basic_HTML_syntax", "Learn_web_development/Core")}} diff --git a/files/en-us/learn_web_development/core/structuring_content/lists/index.md b/files/en-us/learn_web_development/core/structuring_content/lists/index.md index b236954696a3cae..b43140862ba1c6a 100644 --- a/files/en-us/learn_web_development/core/structuring_content/lists/index.md +++ b/files/en-us/learn_web_development/core/structuring_content/lists/index.md @@ -2,10 +2,9 @@ title: Lists slug: Learn_web_development/Core/Structuring_content/Lists page-type: tutorial-chapter +sidebar: learnsidebar --- -{{LearnSidebar}} - {{PreviousMenuNext("Learn_web_development/Core/Structuring_content/Emphasis_and_importance", "Learn_web_development/Core/Structuring_content/Structuring_documents", "Learn_web_development/Core/Structuring_content")}} Now let's turn our attention to lists. Lists are everywhere in life—from your shopping list to the list of directions you subconsciously follow to get to your house every day, to the lists of instructions you are following in these tutorials! It may not surprise you that HTML has a convenient set of elements that allows us to define different types of list. On the web, we have three types of lists: unordered, ordered, and description lists. This lesson shows you how to use the different types. @@ -36,7 +35,7 @@ Now let's turn our attention to lists. Lists are everywhere in life—from your ## Unordered lists -Unordered lists are used to mark up lists of items for which the order of the items doesn't matter. Let's take a shopping list as an example: +Unordered lists are used to mark up lists of items for which the order of the items doesn't matter. Let's take a grocery shopping list as an example: ```plain milk @@ -45,18 +44,8 @@ bread hummus ``` -Every unordered list starts off with a {{htmlelement("ul")}} element—this wraps around all the list items: - -```html-nolint -<ul> - milk - eggs - bread - hummus -</ul> -``` - -The last step is to wrap each list item in a {{htmlelement("li")}} (list item) element: +In this example, the items can be in any order. To create this list in HTML, we first wrap the whole list in a {{htmlelement("ul")}} (unordered list) element. +Then, we wrap each item in a {{htmlelement("li")}} (list item) element: ```html <ul> @@ -769,7 +758,7 @@ textarea.onkeyup = () => { ## Test your skills! -You've reached the end of this set of three articles about basic HTML semantic elements, but can you remember the most important information? You can find some further tests to verify that you've retained this information before you move on — see [Test your skills: HTML text basics](/en-US/docs/Learn_web_development/Core/Structuring_content/Test_your_skills:_HTML_text_basics). +You've reached the end of this set of three articles about basic HTML semantic elements, but can you remember the most important information? You can find some further tests to verify that you've retained this information before you move on — see [Test your skills: HTML text basics](/en-US/docs/Learn_web_development/Core/Structuring_content/Test_your_skills/HTML_text_basics). ## Summary diff --git a/files/en-us/learn_web_development/core/structuring_content/marking_up_a_letter/index.md b/files/en-us/learn_web_development/core/structuring_content/marking_up_a_letter/index.md index a462be8e230ee48..e5c868405d4a419 100644 --- a/files/en-us/learn_web_development/core/structuring_content/marking_up_a_letter/index.md +++ b/files/en-us/learn_web_development/core/structuring_content/marking_up_a_letter/index.md @@ -1,11 +1,11 @@ --- title: "Challenge: Marking up a letter" +short-title: "Challenge: Letter markup" slug: Learn_web_development/Core/Structuring_content/Marking_up_a_letter page-type: learn-module-assessment +sidebar: learnsidebar --- -{{LearnSidebar}} - {{PreviousMenuNext("Learn_web_development/Core/Structuring_content/Creating_links", "Learn_web_development/Core/Structuring_content/Structuring_a_page_of_content", "Learn_web_development/Core/Structuring_content")}} We all learn to write a letter sooner or later; it is also a useful example to test our text formatting skills. In this challenge, you'll have a letter to mark up as a test for your HTML text formatting skills, as well as hyperlinks and proper use of the HTML `<head>` element. diff --git a/files/en-us/learn_web_development/core/structuring_content/mozilla_splash_page/index.md b/files/en-us/learn_web_development/core/structuring_content/mozilla_splash_page/index.md index fa95d93551846b6..70f654022e43cd5 100644 --- a/files/en-us/learn_web_development/core/structuring_content/mozilla_splash_page/index.md +++ b/files/en-us/learn_web_development/core/structuring_content/mozilla_splash_page/index.md @@ -2,10 +2,9 @@ title: "Challenge: Mozilla splash page" slug: Learn_web_development/Core/Structuring_content/Mozilla_splash_page page-type: learn-module-assessment +sidebar: learnsidebar --- -{{LearnSidebar}} - {{PreviousMenuNext("Learn_web_development/Core/Structuring_content/HTML_video_and_audio", "Learn_web_development/Core/Structuring_content/HTML_table_basics", "Learn_web_development/Core/Structuring_content")}} In this challenge, we'll test your knowledge of some of the techniques discussed in the last couple of lessons, getting you to add some images and video to a funky splash page all about Mozilla! diff --git a/files/en-us/learn_web_development/core/structuring_content/mozilla_splash_page/narrow-shot.png b/files/en-us/learn_web_development/core/structuring_content/mozilla_splash_page/narrow-shot.png deleted file mode 100644 index ee9a7f817dd1de5..000000000000000 Binary files a/files/en-us/learn_web_development/core/structuring_content/mozilla_splash_page/narrow-shot.png and /dev/null differ diff --git a/files/en-us/learn_web_development/core/structuring_content/planet_data_table/index.md b/files/en-us/learn_web_development/core/structuring_content/planet_data_table/index.md index cba0852bb4456fb..76eefce6dd73589 100644 --- a/files/en-us/learn_web_development/core/structuring_content/planet_data_table/index.md +++ b/files/en-us/learn_web_development/core/structuring_content/planet_data_table/index.md @@ -1,11 +1,11 @@ --- title: "Challenge: Structuring a planet data table" +short-title: "Challenge: Planet data table" slug: Learn_web_development/Core/Structuring_content/Planet_data_table page-type: learn-module-assessment +sidebar: learnsidebar --- -{{LearnSidebar}} - {{PreviousMenuNext("Learn_web_development/Core/Structuring_content/Table_accessibility", "Learn_web_development/Core/Structuring_content/HTML_forms", "Learn_web_development/Core/Structuring_content")}} In this challenge, we provide you with some data on the planets in our solar system. Your job is to structure it into an accessible HTML table. @@ -38,7 +38,7 @@ The following steps describe what you need to do to complete the table example. ## Hints and tips - The first cell of the header row needs to be blank, and span two columns. -- The group row headings (e.g. _Jovian planets_) that sit to the left of the planet name row headings (e.g. _Saturn_) are a little tricky to sort out — you need to make sure each one spans the correct number of rows and columns. +- The group row headings (e.g., _Jovian planets_) that sit to the left of the planet name row headings (e.g., _Saturn_) are a little tricky to sort out — you need to make sure each one spans the correct number of rows and columns. - One way of associating headers with their rows/columns is a lot easier than the other way. ## Example diff --git a/files/en-us/learn_web_development/core/structuring_content/structuring_a_page_of_content/index.md b/files/en-us/learn_web_development/core/structuring_content/structuring_a_page_of_content/index.md index bfa2d67d4d26c0f..4d0c105e294561a 100644 --- a/files/en-us/learn_web_development/core/structuring_content/structuring_a_page_of_content/index.md +++ b/files/en-us/learn_web_development/core/structuring_content/structuring_a_page_of_content/index.md @@ -1,11 +1,11 @@ --- title: "Challenge: Structuring a page of content" +short-title: "Challenge: Bird watching site" slug: Learn_web_development/Core/Structuring_content/Structuring_a_page_of_content page-type: learn-module-assessment +sidebar: learnsidebar --- -{{LearnSidebar}} - {{PreviousMenuNext("Learn_web_development/Core/Structuring_content/Marking_up_a_letter", "Learn_web_development/Core/Structuring_content/HTML_images", "Learn_web_development/Core/Structuring_content")}} Structuring a page of content ready for laying it out using CSS is a very important skill to master, so in this challenge you'll be tested on your ability to think about how a page might end up looking, and choose appropriate structural semantics to build a layout on top of. diff --git a/files/en-us/learn_web_development/core/structuring_content/structuring_documents/index.md b/files/en-us/learn_web_development/core/structuring_content/structuring_documents/index.md index 2725a0cb7becce7..a2a5cc5230bda90 100644 --- a/files/en-us/learn_web_development/core/structuring_content/structuring_documents/index.md +++ b/files/en-us/learn_web_development/core/structuring_content/structuring_documents/index.md @@ -2,10 +2,9 @@ title: Structuring documents slug: Learn_web_development/Core/Structuring_content/Structuring_documents page-type: tutorial-chapter +sidebar: learnsidebar --- -{{LearnSidebar}} - {{PreviousMenuNext("Learn_web_development/Core/Structuring_content/Lists", "Learn_web_development/Core/Structuring_content/Advanced_text_features", "Learn_web_development/Core/Structuring_content")}} In addition to defining individual parts of your page (such as "a paragraph" or "an image"), {{glossary("HTML")}} also boasts a number of block level elements used to define areas of your website (such as "the header", "the navigation menu", "the main content column"). This article looks into how to plan a basic website structure, and write the HTML to represent this structure. @@ -196,7 +195,7 @@ Take some time to look over the code and understand it — the comments inside t ## HTML layout elements in more detail -It's good to understand the overall meaning of all the HTML sectioning elements in detail — this is something you'll work on gradually as you start to get more experience with web development. You can find a lot of detail by reading our [HTML element reference](/en-US/docs/Web/HTML/Element). For now, these are the main definitions that you should try to understand: +It's good to understand the overall meaning of all the HTML sectioning elements in detail — this is something you'll work on gradually as you start to get more experience with web development. You can find a lot of detail by reading our [HTML element reference](/en-US/docs/Web/HTML/Reference/Elements). For now, these are the main definitions that you should try to understand: - {{HTMLElement('main')}} is for content _unique to this page._ Use `<main>` only _once_ per page, and put it directly inside {{HTMLElement('body')}}. Ideally this shouldn't be nested within other elements. - {{HTMLElement('article')}} encloses a block of related content that makes sense on its own without the rest of the page (e.g., a single blog post). @@ -210,7 +209,7 @@ Each of the aforementioned elements can be clicked on to read the corresponding ### Non-semantic wrappers -Sometimes you'll come across a situation where you can't find an ideal semantic element to group some items together or wrap some content. Sometimes you might want to just group a set of elements together to affect them all as a single entity with some {{glossary("CSS")}} or {{glossary("JavaScript")}}. For cases like these, HTML provides the {{HTMLElement("div")}} and {{HTMLElement("span")}} elements. You should use these preferably with a suitable [`class`](/en-US/docs/Web/HTML/Global_attributes/class) attribute, to provide some kind of label for them so they can be easily targeted. +Sometimes you'll come across a situation where you can't find an ideal semantic element to group some items together or wrap some content. Sometimes you might want to just group a set of elements together to affect them all as a single entity with some {{glossary("CSS")}} or {{glossary("JavaScript")}}. For cases like these, HTML provides the {{HTMLElement("div")}} and {{HTMLElement("span")}} elements. You should use these preferably with a suitable [`class`](/en-US/docs/Web/HTML/Reference/Global_attributes/class) attribute, to provide some kind of label for them so they can be easily targeted. {{HTMLElement("span")}} is an inline non-semantic element, which you should only use if you can't think of a better semantic text element to wrap your content, or don't want to add any specific meaning. For example: @@ -249,6 +248,12 @@ This isn't really an `<aside>`, as it doesn't necessarily relate to the main con > [!WARNING] > Divs are so convenient to use that it's easy to use them too much. As they carry no semantic value, they just clutter your HTML code. Take care to use them only when there is no better semantic solution and try to reduce their usage to the minimum otherwise you'll have a hard time updating and maintaining your documents. +> [!CALLOUT] +> +> **Try it out** +> +> Scrimba's [Semantic HTML](https://scrimba.com/learn-accessible-web-design-c031/~0b?via=mdn) <sup>[_MDN learning partner_](/en-US/docs/MDN/Writing_guidelines/Learning_content#partner_links_and_embeds)</sup> interactive tutorial provides a useful recap of semantic markup and why you should use it, plus a challenge that tests your ability to improve an HTML codebase with semantic elements. + ### Line breaks and horizontal rules Two elements that you'll use occasionally and will want to know about are {{htmlelement("br")}} and {{htmlelement("hr")}}. diff --git a/files/en-us/learn_web_development/core/structuring_content/table_accessibility/index.md b/files/en-us/learn_web_development/core/structuring_content/table_accessibility/index.md index 25532a930ea49b3..b5a4990c4acc075 100644 --- a/files/en-us/learn_web_development/core/structuring_content/table_accessibility/index.md +++ b/files/en-us/learn_web_development/core/structuring_content/table_accessibility/index.md @@ -1,14 +1,14 @@ --- title: HTML table accessibility +short-title: Table accessibility slug: Learn_web_development/Core/Structuring_content/Table_accessibility page-type: learn-module-chapter +sidebar: learnsidebar --- -{{LearnSidebar}} - {{PreviousMenuNext("Learn_web_development/Core/Structuring_content/HTML_table_basics", "Learn_web_development/Core/Structuring_content/Planet_data_table", "Learn_web_development/Core/Structuring_content")}} -In the previous article, we looked at one of the most important features for making HTML tables accessible to visually impaired users — the {{htmlelement("th")}} element. In this article we continue down this path, looking at more HTML table accessibility features such as captions/summaries, grouping your rows into table head, body and footer sections, and scoping columns and rows. +In the previous article, we looked at one of the most important features for making HTML tables accessible to visually impaired users — the {{htmlelement("th")}} element. In this article, we continue down this path, looking at more HTML table accessibility features such as captions/summaries, grouping your rows into table head, body and footer sections, and scoping columns and rows. <table> <tbody> @@ -37,7 +37,7 @@ In the previous article, we looked at one of the most important features for mak ## Recap: Tables for visually impaired users -Let's recap briefly on how we use data tables. A table can be a handy tool, for giving us quick access to data and allowing us to look up different values. For example, it takes only a short glance at the table below to find out how many rings were sold in Gent during August 2016. To understand its information we make visual associations between the data in this table and its column and/or row headers. +Let's recap briefly on how we use data tables. A table can be a handy tool, for giving us quick access to data and allowing us to look up different values. For example, it takes only a short glance at the table below to find out how many rings were sold in Gent during August 2016. To understand its information, we make visual associations between the data in this table and its column and/or row headers. <table> <caption>Items Sold August 2016</caption> @@ -133,7 +133,7 @@ As you can infer from the brief example above, the caption is meant to contain a A caption is placed directly beneath the `<table>` tag. > [!NOTE] -> The [`summary`](/en-US/docs/Web/HTML/Element/table#summary) attribute can also be used on the `<table>` element to provide a description — this is also read out by screen readers. We'd recommend using the `<caption>` element instead, however, as `summary` is deprecated and can't be read by sighted users (it doesn't appear on the page). +> The [`summary`](/en-US/docs/Web/HTML/Reference/Elements/table#summary) attribute can also be used on the `<table>` element to provide a description — this is also read out by screen readers. We'd recommend using the `<caption>` element instead, however, as `summary` is deprecated and can't be read by sighted users (it doesn't appear on the page). ### Active learning: Adding a caption @@ -166,7 +166,7 @@ Let's put these new elements into action. 1. First of all, make a local copy of [spending-record.html](https://github.com/mdn/learning-area/blob/main/html/tables/advanced/spending-record.html) and [minimal-table.css](https://github.com/mdn/learning-area/blob/main/html/tables/advanced/minimal-table.css) in a new folder. 2. Try putting the obvious headers row inside a `<thead>` element, the "SUM" row inside a `<tfoot>` element, and the rest of the content inside a `<tbody>` element. -3. Next, add a [`colspan`](/en-US/docs/Web/HTML/Element/td#colspan) attribute to make the "SUM" cell span across the first four columns, so the actual number appears at the bottom of the "Cost" column. +3. Next, add a [`colspan`](/en-US/docs/Web/HTML/Reference/Elements/td#colspan) attribute to make the "SUM" cell span across the first four columns, so the actual number appears at the bottom of the "Cost" column. 4. Let's add some simple extra styling to the table, to give you an idea of how useful these elements are for applying CSS. Inside the head of your HTML document, you'll see an empty {{htmlelement("style")}} element. Inside this element, add the following lines of CSS code: ```css @@ -190,11 +190,11 @@ Your finished table should look something like the following: {{ EmbedGHLiveSample('learning-area/html/tables/advanced/spending-record-finished.html', '100%', 400) }} > [!NOTE] -> You can also find it on GitHub as [spending-record-finished.html](https://github.com/mdn/learning-area/blob/main/html/tables/advanced/spending-record-finished.html). +> You can also find it on GitHub as [spending-record-finished.html](https://github.com/mdn/learning-area/blob/main/html/tables/advanced/spending-record-finished.html) ([see it live here](https://mdn.github.io/learning-area/html/tables/advanced/spending-record-finished.html)). ## The `scope` attribute -The [`scope`](/en-US/docs/Web/HTML/Element/th#scope) attribute can be added to the `<th>` element to tell screen readers exactly what cells the header is a header for — is it a header for the row it is in, or the column, for example? Looking back to our spending record example from earlier on, you could unambiguously define the column headers as column headers like this: +The [`scope`](/en-US/docs/Web/HTML/Reference/Elements/th#scope) attribute can be added to the `<th>` element to tell screen readers exactly what cells the header is a header for — is it a header for the row it is in, or the column, for example? Looking back to our spending record example from earlier on, you could unambiguously define the column headers as column headers like this: ```html <thead> @@ -255,26 +255,32 @@ The same applies to headers for multiple grouped rows. Take another look at the </tr> ``` -## The id and headers attributes +## The `id` and `headers` attributes + +An alternative to using the `scope` attribute is to use [`id`](/en-US/docs/Web/HTML/Reference/Global_attributes/id) and [`headers`](/en-US/docs/Web/HTML/Reference/Elements/td#headers) attributes to create associations between data cells and header cells. -An alternative to using the `scope` attribute is to use [`id`](/en-US/docs/Web/HTML/Global_attributes/id) and [`headers`](/en-US/docs/Web/HTML/Element/td#headers) attributes to create associations between headers and cells. +A `<th>` element can provide a heading for either a data cell (`<td>`) or, in more complex tables, for another header cell (`<th>`). This allows you to create layered or grouped headers, where one header describes several others. -The `headers` attribute takes a list of unordered, space-separated {{Glossary("string", "strings")}}, each corresponding to the unique `id` of the `<th>` elements that provide headings for either a data cell (`<td>` element) or another header cell (`<th>` element). +The `headers` attribute is used to link a cell, `<td>` or `<th>`, to one or more header cells. It takes a space-separated list of {{Glossary("string", "strings")}}; the order of strings does not matter. Each string must match the unique `id` of a `<th>` element that the cell is associated with. -This gives your HTML table an explicit definition of the position of each cell in the table, defined by the header(s) for each column and row it is part of, kind of like a spreadsheet. For it to work well, the table really needs both column and row headers. +This method gives your HTML table a more explicit definition of the position of each cell, based on the headers for the column and the row it belongs to, kind of like a spreadsheet. For this to work well, your table should include both column and row headers. -Returning to our "Items Sold August 2016" example, we can use the `id` and `headers` attributes as follows: +Let's look at a portion of the "Items Sold August 2016" example to see how to use the `id` and `headers` attributes: 1. Add a unique `id` to each `<th>` element in the table. -2. Add a `headers` attribute to each `<th>` element that acts as a subheading, i.e., has a header element above it. The value is the `id` of the heading that sits over the top and defines the subheadings, which is `"clothes"` for the column headers and `"belgium"` for the row header in our example. -3. Add a `headers` attribute to each `<td>` element and add the `id`s of the associated `<th>` element(s) in form of a space-separated list. You can proceed as you would in a spreadsheet: Find the data cell and search for the corresponding headings for the row and column. The order of the specified `id`s doesn't matter, but you should be consistent to keep it organized. +2. For the header cells: Add a `headers` attribute to each `<th>` element that acts as a subheading, that is, a header cell with another header above it. The value is the `id` of the high-level heading. In our example, that's `"clothes"` for the column headers and `"belgium"` for the row header. +3. For the data cells: Add a `headers` attribute to each `<td>` element, and add the `id`s of the associated `<th>` element(s) as a space-separated list. You can proceed as you would in a spreadsheet: Find the data cell, then locate the row and column headers that describe it. The order of the specified `id`s doesn't matter, but keeping it consistent helps to keep it organized and improves readability of the code. ```html <thead> <tr> + <th></th> + <th></th> <th id="clothes" colspan="3">Clothes</th> </tr> <tr> + <th></th> + <th></th> <th id="trousers" headers="clothes">Trousers</th> <th id="skirts" headers="clothes">Skirts</th> <th id="dresses" headers="clothes">Dresses</th> @@ -282,15 +288,27 @@ Returning to our "Items Sold August 2016" example, we can use the `id` and `head </thead> <tbody> <tr> - <th id="belgium" rowspan="3">Belgium</th> + <th id="belgium" rowspan="2">Belgium</th> <th id="antwerp" headers="belgium">Antwerp</th> - <td headers="antwerp belgium clothes trousers">56</td> - <td headers="antwerp belgium clothes skirts">22</td> - <td headers="antwerp belgium clothes dresses">43</td> + <td headers="belgium antwerp clothes trousers">56</td> + <td headers="belgium antwerp clothes skirts">22</td> + <td headers="belgium antwerp clothes dresses">43</td> + </tr> + <tr> + <th id="ghent" headers="belgium">Ghent</th> + <td headers="belgium ghent clothes trousers">41</td> + <td headers="belgium ghent clothes skirts">17</td> + <td headers="belgium ghent clothes dresses">35</td> </tr> </tbody> ``` +In this example: + +- The `<th>` for `"Belgium"` uses `rowspan="2"` to span both `"Antwerp"` and `"Ghent"`. +- The city header cells (`"Antwerp"` and `"Ghent"`) use the `headers` attribute to reference `"belgium"` to show they belong to the Belgium group. +- Each `<td>` includes a `headers` attribute for country (`belgium`), city (`antwerp` or `ghent`), group (`clothes`), and the specific clothing item (`trousers`, `skirts`, or `dresses`). + > [!NOTE] > This method creates very precise associations between headers and data cells but it uses **a lot** more markup and does not leave any room for errors. The `scope` approach is usually sufficient for most tables. diff --git a/files/en-us/learn_web_development/core/structuring_content/test_your_skills/advanced_html_text/index.md b/files/en-us/learn_web_development/core/structuring_content/test_your_skills/advanced_html_text/index.md new file mode 100644 index 000000000000000..b33fd19f2f3ef62 --- /dev/null +++ b/files/en-us/learn_web_development/core/structuring_content/test_your_skills/advanced_html_text/index.md @@ -0,0 +1,35 @@ +--- +title: "Test your skills: Advanced HTML text" +short-title: Advanced HTML text +slug: Learn_web_development/Core/Structuring_content/Test_your_skills/Advanced_HTML_text +page-type: learn-module-assessment +sidebar: learnsidebar +--- + +The aim of this skill test is to assess whether you understand how to use [lesser-known HTML elements to mark up advanced semantic features](/en-US/docs/Learn_web_development/Core/Structuring_content/Advanced_text_features). + +> [!NOTE] +> You can try solutions in the interactive editors on this page or in an online editor such as [CodePen](https://codepen.io/), [JSFiddle](https://jsfiddle.net/), or [Glitch](https://glitch.com/). +> +> If you get stuck, you can reach out to us in one of our [communication channels](/en-US/docs/MDN/Community/Communication_channels). + +## Task 1 + +In this task, we want you to add some semantics to the provided HTML as follows: + +- Turn the second paragraph into a block-level quote, and semantically indicate that the quote is taken from [Accessibility](/en-US/docs/Learn_web_development/Core/Accessibility). +- Semantically mark up "HTML" and "CSS" as acronyms, providing expansions as tooltips. +- Use subscript and superscript to provide correct semantics for the chemical formulae and dates, and make them display correctly. +- Semantically associate machine-readable dates with the dates in the text. + +The finished example should look like this: + +{{EmbedGHLiveSample("learning-area/html/introduction-to-html/tasks/advanced-text/advanced-text2-finished.html", '100%', 300)}} + +Try updating the live code below to recreate the finished example: + +{{EmbedGHLiveSample("learning-area/html/introduction-to-html/tasks/advanced-text/advanced-text2.html", '100%', 700)}} + +> [!CALLOUT] +> +> [Download the starting point for this task](https://github.com/mdn/learning-area/blob/main/html/introduction-to-html/tasks/advanced-text/advanced-text2-download.html) to work in your own editor or in an online editor. diff --git a/files/en-us/learn_web_development/core/structuring_content/test_your_skills/html_text_basics/index.md b/files/en-us/learn_web_development/core/structuring_content/test_your_skills/html_text_basics/index.md new file mode 100644 index 000000000000000..82759b86b2b090a --- /dev/null +++ b/files/en-us/learn_web_development/core/structuring_content/test_your_skills/html_text_basics/index.md @@ -0,0 +1,78 @@ +--- +title: "Test your skills: HTML text basics" +short-title: HTML text basics +slug: Learn_web_development/Core/Structuring_content/Test_your_skills/HTML_text_basics +page-type: learn-module-assessment +sidebar: learnsidebar +--- + +The aim of this skill test is to assess whether you understand how to mark up text in HTML to give it structure and meaning. + +> [!NOTE] +> You can try solutions in the interactive editors on this page or in an online editor such as [CodePen](https://codepen.io/), [JSFiddle](https://jsfiddle.net/), or [Glitch](https://glitch.com/). +> +> If you get stuck, you can reach out to us in one of our [communication channels](/en-US/docs/MDN/Community/Communication_channels). + +## Task 1 + +In this task, we want you to mark up the provided HTML using semantic heading and paragraph elements. + +The finished example should look like this: + +{{EmbedGHLiveSample("learning-area/html/introduction-to-html/tasks/basic-text/basic-text1-finished.html", '100%', 300)}} + +Try updating the live code below to recreate the finished example: + +{{EmbedGHLiveSample("learning-area/html/introduction-to-html/tasks/basic-text/basic-text1.html", '100%', 700)}} + +> [!CALLOUT] +> +> [Download the starting point for this task](https://github.com/mdn/learning-area/blob/main/html/introduction-to-html/tasks/basic-text/basic-text1-download.html) to work in your own editor or in an online editor. + +## Task 2 + +In this task, we want you to turn the first un-marked up list into an unordered list, and the second one into an ordered list. + +The finished example should look like this: + +{{EmbedGHLiveSample("learning-area/html/introduction-to-html/tasks/basic-text/basic-text2-finished.html", '100%', 400)}} + +Try updating the live code below to recreate the finished example: + +{{EmbedGHLiveSample("learning-area/html/introduction-to-html/tasks/basic-text/basic-text2.html", '100%', 700)}} + +> [!CALLOUT] +> +> [Download the starting point for this task](https://github.com/mdn/learning-area/blob/main/html/introduction-to-html/tasks/basic-text/basic-text2-download.html) to work in your own editor or in an online editor. + +## Task 3 + +In this task, we want you to turn the provided animals and their definitions into a description list. + +The finished example should look like this: + +{{EmbedGHLiveSample("learning-area/html/introduction-to-html/tasks/advanced-text/advanced-text1-finished.html", '100%', 250)}} + +Try updating the live code below to recreate the finished example: + +{{EmbedGHLiveSample("learning-area/html/introduction-to-html/tasks/advanced-text/advanced-text1.html", '100%', 700)}} + +> [!CALLOUT] +> +> [Download the starting point for this task](https://github.com/mdn/learning-area/blob/main/html/introduction-to-html/tasks/advanced-text/advanced-text1-download.html) to work in your own editor or in an online editor. + +## Task 4 + +In this task, you are provided with a paragraph, and your aim is to use some inline elements to mark up a couple of appropriate words with strong importance, and a couple with emphasis. + +The finished example should look like this: + +{{EmbedGHLiveSample("learning-area/html/introduction-to-html/tasks/basic-text/basic-text3-finished.html", '100%', 120)}} + +Try updating the live code below to recreate the finished example: + +{{EmbedGHLiveSample("learning-area/html/introduction-to-html/tasks/basic-text/basic-text3.html", '100%', 700)}} + +> [!CALLOUT] +> +> [Download the starting point for this task](https://github.com/mdn/learning-area/blob/main/html/introduction-to-html/tasks/basic-text/basic-text3-download.html) to work in your own editor or in an online editor. diff --git a/files/en-us/learn_web_development/core/structuring_content/test_your_skills/images/index.md b/files/en-us/learn_web_development/core/structuring_content/test_your_skills/images/index.md new file mode 100644 index 000000000000000..362c0818358935b --- /dev/null +++ b/files/en-us/learn_web_development/core/structuring_content/test_your_skills/images/index.md @@ -0,0 +1,54 @@ +--- +title: "Test your skills: HTML images" +short-title: Images +slug: Learn_web_development/Core/Structuring_content/Test_your_skills/Images +page-type: learn-module-assessment +sidebar: learnsidebar +--- + +The aim of this skill test is to assess whether you understand [images and how to embed them in HTML](/en-US/docs/Learn_web_development/Core/Structuring_content/HTML_images). + +> [!NOTE] +> You can try solutions in the interactive editors on this page or in an online editor such as [CodePen](https://codepen.io/), [JSFiddle](https://jsfiddle.net/), or [Glitch](https://glitch.com/). +> +> If you get stuck, you can reach out to us in one of our [communication channels](/en-US/docs/MDN/Community/Communication_channels). + +## Task 1 + +In this task, we want you to embed an image of some Blueberries into the page. You need to: + +- Add the path to the image to an appropriate attribute to embed it on the page. The image is called `blueberries.jpg`, and it is in a folder inside the current folder called `images`. +- Add some alternative text to an appropriate attribute to describe the image, for people that cannot see it. +- Give the `<img>` element an appropriate `width` and `height` so that it displays at the correct {{glossary("aspect ratio")}}, and enough space is left on the page to display it. The image's {{glossary("intrinsic size")}} is 615 x 419 pixels. + +Try updating the live code below to recreate the finished example: + +{{EmbedGHLiveSample("learning-area/html/multimedia-and-embedding/tasks/images/images1.html", '100%', 700)}} + +> [!CALLOUT] +> +> [Download the starting point for this task](https://github.com/mdn/learning-area/blob/main/html/multimedia-and-embedding/tasks/images/images1-download.html) to work in your own editor or in an online editor. + +## Task 2 + +In this task, you already have a full-featured image, but we'd like you to add a tooltip that appears when the image is moused over. You should put some appropriate information into the tooltip. + +Try updating the live code below to recreate the finished example: + +{{EmbedGHLiveSample("learning-area/html/multimedia-and-embedding/tasks/images/images2.html", '100%', 1000)}} + +> [!CALLOUT] +> +> [Download the starting point for this task](https://github.com/mdn/learning-area/blob/main/html/multimedia-and-embedding/tasks/images/images2-download.html) to work in your own editor or in an online editor. + +## Task 3 + +In this task, you are provided with both a full-featured image and some caption text. What you need to do here is add elements that will associate the image with the caption. + +Try updating the live code below to recreate the finished example: + +{{EmbedGHLiveSample("learning-area/html/multimedia-and-embedding/tasks/images/images3.html", '100%', 1000)}} + +> [!CALLOUT] +> +> [Download the starting point for this task](https://github.com/mdn/learning-area/blob/main/html/multimedia-and-embedding/tasks/images/images3-download.html) to work in your own editor or in an online editor. diff --git a/files/en-us/learn_web_development/core/structuring_content/test_your_skills/index.md b/files/en-us/learn_web_development/core/structuring_content/test_your_skills/index.md new file mode 100644 index 000000000000000..fc5d851a272cfaa --- /dev/null +++ b/files/en-us/learn_web_development/core/structuring_content/test_your_skills/index.md @@ -0,0 +1,17 @@ +--- +title: "Test your skills: Structuring content with HTML" +short-title: Test your skills +slug: Learn_web_development/Core/Structuring_content/Test_your_skills +page-type: learn-module-assessment +sidebar: learnsidebar +--- + +This page lists HTML tests you can try so you can verify you've understood the content in this module. + +## Test your HTML skills by topic + +{{SubpagesWithSummaries}} + +## See also + +- [Structuring content with HTML](/en-US/docs/Learn_web_development/Core/Structuring_content) diff --git a/files/en-us/learn_web_development/core/structuring_content/test_your_skills/links/index.md b/files/en-us/learn_web_development/core/structuring_content/test_your_skills/links/index.md new file mode 100644 index 000000000000000..2eae90a874b9304 --- /dev/null +++ b/files/en-us/learn_web_development/core/structuring_content/test_your_skills/links/index.md @@ -0,0 +1,72 @@ +--- +title: "Test your skills: Links" +short-title: Links +slug: Learn_web_development/Core/Structuring_content/Test_your_skills/Links +page-type: learn-module-assessment +sidebar: learnsidebar +--- + +The aim of this skill test is to assess whether you understand how to [implement links in HTML](/en-US/docs/Learn_web_development/Core/Structuring_content/Creating_links). + +> [!NOTE] +> You can try solutions in the interactive editors on this page or in an online editor such as [CodePen](https://codepen.io/), [JSFiddle](https://jsfiddle.net/), or [Glitch](https://glitch.com/). +> +> If you get stuck, you can reach out to us in one of our [communication channels](/en-US/docs/MDN/Community/Communication_channels). + +## Task 1 + +In this task, we want you to help fill in the links on our Whales information page: + +- The first link should be linked to a page called `whales.html`, which is in the same directory as the current page. +- We'd also like you to give it a tooltip when moused over that tells the user that the page includes information on Blue Whales and Sperm Whales. +- The second link should be turned into a link you can click to open up an email in the user's default mail application, with the recipient set as "whales\@example.com". +- You'll get a bonus point if you also set it so that the subject line of the email is automatically filled in as "Question about Whales". + +> [!NOTE] +> The two links in the example have the `target="_blank"` attribute set on them. This is not strictly best practice, but we've done it here so that the links don't open in the embedded `<iframe>`, getting rid of your example code in the process! + +Try updating the live code below to recreate the finished example: + +{{EmbedGHLiveSample("learning-area/html/introduction-to-html/tasks/links/links1.html", '100%', 700)}} + +> [!CALLOUT] +> +> [Download the starting point for this task](https://github.com/mdn/learning-area/blob/main/html/introduction-to-html/tasks/links/links1-download.html) to work in your own editor or in an online editor. + +## Task 2 + +In this task, we want you to fill in the four links so that they link to the appropriate places: + +- The first link should link to an image called `blue-whale.jpg`, which is located in a directory called `blue` inside the current directory. +- The second link should link to an image called `narwhal.jpg`, which is located in a directory called `narwhal`, which is located one directory level above the current directory. +- The third link should link to the UK Google Image search. The base URL is `https://www.google.co.uk`, and the image search is located in a subdirectory called `imghp`. +- The fourth link should link to the paragraph at the very bottom of the current page. It has an ID of `bottom`. + +> [!NOTE] +> The first three links in the example have the `target="_blank"` attribute set on them, so that when you click on them, they open the linked page in a new tab. This is not strictly best practice, but we've done it here so that the pages don't open in the embedded `<iframe>`, getting rid of your example code in the process! + +Try updating the live code below to recreate the finished example: + +{{EmbedGHLiveSample("learning-area/html/introduction-to-html/tasks/links/links2.html", '100%', 800)}} + +> [!CALLOUT] +> +> [Download the starting point for this task](https://github.com/mdn/learning-area/blob/main/html/introduction-to-html/tasks/links/links2-download.html) to work in your own editor or in an online editor. + +## Task 3 + +The following links link to an info page about Narwhals, a support email address, and a PDF factfile that is 4MB in size. In this task, we want you to: + +- Take the existing paragraphs with poorly-written link text, and rewrite them so that they have good link text. +- Add a warning to any links that need a warning added. + +> [!NOTE] +> The first and third links in the example have the `target="_blank"` attribute set on them, so that when you click on them, they open the linked page in a new tab. This is not strictly best practice, but we've done it here so that the pages don't open in the embedded `<iframe>`, getting rid of your example code in the process! + +Try updating the live code below to recreate the finished example: + +{{EmbedGHLiveSample("learning-area/html/introduction-to-html/tasks/links/links3.html", '100%', 700)}} + +> [!CALLOUT] +> +> [Download the starting point for this task](https://github.com/mdn/learning-area/blob/main/html/introduction-to-html/tasks/links/links3-download.html) to work in your own editor or in an online editor. diff --git a/files/en-us/learn_web_development/core/structuring_content/test_your_skills/multimedia_and_embedding/index.md b/files/en-us/learn_web_development/core/structuring_content/test_your_skills/multimedia_and_embedding/index.md new file mode 100644 index 000000000000000..9d36212bacf6192 --- /dev/null +++ b/files/en-us/learn_web_development/core/structuring_content/test_your_skills/multimedia_and_embedding/index.md @@ -0,0 +1,51 @@ +--- +title: "Test your skills: Multimedia and embedding" +short-title: Audio and video +slug: Learn_web_development/Core/Structuring_content/Test_your_skills/Multimedia_and_embedding +page-type: learn-module-assessment +sidebar: learnsidebar +--- + +The aim of this skill test is to assess whether you understand how to [embed video and audio content in HTML](/en-US/docs/Learn_web_development/Core/Structuring_content/HTML_video_and_audio). + +> [!NOTE] +> You can try solutions in the interactive editors on this page or in an online editor such as [CodePen](https://codepen.io/), [JSFiddle](https://jsfiddle.net/), or [Glitch](https://glitch.com/). +> +> If you get stuck, you can reach out to us in one of our [communication channels](/en-US/docs/MDN/Community/Communication_channels). + +## Task 1 + +In this task, we want you to embed an audio file onto the page. You need to: + +- Add the path to the audio file to an appropriate attribute to embed it on the page. The audio is called `audio.mp3`, and it is in a folder inside the current folder called `media`. +- Add an attribute to make browsers display some default controls. +- Add some appropriate fallback text for browsers that don't support `<audio>`. + +Try updating the live code below to recreate the finished example: + +{{EmbedGHLiveSample("learning-area/html/multimedia-and-embedding/tasks/media-embed/mediaembed1.html", '100%', 700)}} + +> [!CALLOUT] +> +> [Download the starting point for this task](https://github.com/mdn/learning-area/blob/main/html/multimedia-and-embedding/tasks/media-embed/mediaembed1-download.html) to work in your own editor or in an online editor. + +## Task 2 + +In this task, we want you to mark up a slightly more complex video player, with multiple sources, subtitles, and other features besides. You need to: + +- Add an attribute to make browsers display some default controls. +- Add some appropriate fallback text for browsers that don't support `<video>`. +- Add multiple sources, containing the paths to the video files. The files are called `video.mp4` and `video.webm`, and are in a folder inside the current folder called `media`. +- Let the browser know in advance what video formats the sources point to, so it can make an informed choice of which one to download ahead of time. +- Give the `<video>` a width and height equal to its intrinsic size (320 by 240 pixels). +- Make the video muted by default. +- Display the text tracks contained in the `media` folder, in a file called `subtitles_en.vtt`, when the video is playing. You must explicitly set the type as subtitles, and the subtitle language to English. +- Make sure the readers can identify the subtitle language when they use the default controls. + +Try updating the live code below to recreate the finished example: + +{{EmbedGHLiveSample("learning-area/html/multimedia-and-embedding/tasks/media-embed/mediaembed2.html", '100%', 700)}} + +> [!CALLOUT] +> +> [Download the starting point for this task](https://github.com/mdn/learning-area/blob/main/html/multimedia-and-embedding/tasks/media-embed/mediaembed2-download.html) to work in your own editor or in an online editor. diff --git a/files/en-us/learn_web_development/core/structuring_content/test_your_skills_colon__advanced_html_text/index.md b/files/en-us/learn_web_development/core/structuring_content/test_your_skills_colon__advanced_html_text/index.md deleted file mode 100644 index f75dbd7ab269448..000000000000000 --- a/files/en-us/learn_web_development/core/structuring_content/test_your_skills_colon__advanced_html_text/index.md +++ /dev/null @@ -1,35 +0,0 @@ ---- -title: "Test your skills: Advanced HTML text" -slug: Learn_web_development/Core/Structuring_content/Test_your_skills:_Advanced_HTML_text -page-type: learn-module-assessment ---- - -{{learnsidebar}} - -The aim of this skill test is to assess whether you understand how to use [lesser-known HTML elements to mark up advanced semantic features](/en-US/docs/Learn_web_development/Core/Structuring_content/Advanced_text_features). - -> [!NOTE] -> You can try solutions in the interactive editors on this page or in an online editor such as [CodePen](https://codepen.io/), [JSFiddle](https://jsfiddle.net/), or [Glitch](https://glitch.com/). -> -> If you get stuck, you can reach out to us in one of our [communication channels](/en-US/docs/MDN/Community/Communication_channels). - -## Task 1 - -In this task, we want you to add some semantics to the provided HTML as follows: - -- Turn the second paragraph into a block-level quote, and semantically indicate that the quote is taken from [Accessibility](/en-US/docs/Learn_web_development/Core/Accessibility). -- Semantically mark up "HTML" and "CSS" as acronyms, providing expansions as tooltips. -- Use subscript and superscript to provide correct semantics for the chemical formulae and dates, and make them display correctly. -- Semantically associate machine-readable dates with the dates in the text. - -The finished example should look like this: - -{{EmbedGHLiveSample("learning-area/html/introduction-to-html/tasks/advanced-text/advanced-text2-finished.html", '100%', 300)}} - -Try updating the live code below to recreate the finished example: - -{{EmbedGHLiveSample("learning-area/html/introduction-to-html/tasks/advanced-text/advanced-text2.html", '100%', 700)}} - -> [!CALLOUT] -> -> [Download the starting point for this task](https://github.com/mdn/learning-area/blob/main/html/introduction-to-html/tasks/advanced-text/advanced-text2-download.html) to work in your own editor or in an online editor. diff --git a/files/en-us/learn_web_development/core/structuring_content/test_your_skills_colon__html_text_basics/index.md b/files/en-us/learn_web_development/core/structuring_content/test_your_skills_colon__html_text_basics/index.md deleted file mode 100644 index ec64a5a3e1c6476..000000000000000 --- a/files/en-us/learn_web_development/core/structuring_content/test_your_skills_colon__html_text_basics/index.md +++ /dev/null @@ -1,78 +0,0 @@ ---- -title: "Test your skills: HTML text basics" -slug: Learn_web_development/Core/Structuring_content/Test_your_skills:_HTML_text_basics -page-type: learn-module-assessment ---- - -{{learnsidebar}} - -The aim of this skill test is to assess whether you understand how to mark up text in HTML to give it structure and meaning. - -> [!NOTE] -> You can try solutions in the interactive editors on this page or in an online editor such as [CodePen](https://codepen.io/), [JSFiddle](https://jsfiddle.net/), or [Glitch](https://glitch.com/). -> -> If you get stuck, you can reach out to us in one of our [communication channels](/en-US/docs/MDN/Community/Communication_channels). - -## Task 1 - -In this task, we want you to mark up the provided HTML using semantic heading and paragraph elements. - -The finished example should look like this: - -{{EmbedGHLiveSample("learning-area/html/introduction-to-html/tasks/basic-text/basic-text1-finished.html", '100%', 300)}} - -Try updating the live code below to recreate the finished example: - -{{EmbedGHLiveSample("learning-area/html/introduction-to-html/tasks/basic-text/basic-text1.html", '100%', 700)}} - -> [!CALLOUT] -> -> [Download the starting point for this task](https://github.com/mdn/learning-area/blob/main/html/introduction-to-html/tasks/basic-text/basic-text1-download.html) to work in your own editor or in an online editor. - -## Task 2 - -In this task, we want you to turn the first un-marked up list into an unordered list, and the second one into an ordered list. - -The finished example should look like this: - -{{EmbedGHLiveSample("learning-area/html/introduction-to-html/tasks/basic-text/basic-text2-finished.html", '100%', 400)}} - -Try updating the live code below to recreate the finished example: - -{{EmbedGHLiveSample("learning-area/html/introduction-to-html/tasks/basic-text/basic-text2.html", '100%', 700)}} - -> [!CALLOUT] -> -> [Download the starting point for this task](https://github.com/mdn/learning-area/blob/main/html/introduction-to-html/tasks/basic-text/basic-text2-download.html) to work in your own editor or in an online editor. - -## Task 3 - -In this task, we want you to turn the provided animals and their definitions into a description list. - -The finished example should look like this: - -{{EmbedGHLiveSample("learning-area/html/introduction-to-html/tasks/advanced-text/advanced-text1-finished.html", '100%', 250)}} - -Try updating the live code below to recreate the finished example: - -{{EmbedGHLiveSample("learning-area/html/introduction-to-html/tasks/advanced-text/advanced-text1.html", '100%', 700)}} - -> [!CALLOUT] -> -> [Download the starting point for this task](https://github.com/mdn/learning-area/blob/main/html/introduction-to-html/tasks/advanced-text/advanced-text1-download.html) to work in your own editor or in an online editor. - -## Task 4 - -In this task, you are provided with a paragraph, and your aim is to use some inline elements to mark up a couple of appropriate words with strong importance, and a couple with emphasis. - -The finished example should look like this: - -{{EmbedGHLiveSample("learning-area/html/introduction-to-html/tasks/basic-text/basic-text3-finished.html", '100%', 120)}} - -Try updating the live code below to recreate the finished example: - -{{EmbedGHLiveSample("learning-area/html/introduction-to-html/tasks/basic-text/basic-text3.html", '100%', 700)}} - -> [!CALLOUT] -> -> [Download the starting point for this task](https://github.com/mdn/learning-area/blob/main/html/introduction-to-html/tasks/basic-text/basic-text3-download.html) to work in your own editor or in an online editor. diff --git a/files/en-us/learn_web_development/core/structuring_content/test_your_skills_colon__links/index.md b/files/en-us/learn_web_development/core/structuring_content/test_your_skills_colon__links/index.md deleted file mode 100644 index 4e87311c8fa228f..000000000000000 --- a/files/en-us/learn_web_development/core/structuring_content/test_your_skills_colon__links/index.md +++ /dev/null @@ -1,72 +0,0 @@ ---- -title: "Test your skills: Links" -slug: Learn_web_development/Core/Structuring_content/Test_your_skills:_Links -page-type: learn-module-assessment ---- - -{{learnsidebar}} - -The aim of this skill test is to assess whether you understand how to [implement links in HTML](/en-US/docs/Learn_web_development/Core/Structuring_content/Creating_links). - -> [!NOTE] -> You can try solutions in the interactive editors on this page or in an online editor such as [CodePen](https://codepen.io/), [JSFiddle](https://jsfiddle.net/), or [Glitch](https://glitch.com/). -> -> If you get stuck, you can reach out to us in one of our [communication channels](/en-US/docs/MDN/Community/Communication_channels). - -## Task 1 - -In this task, we want you to help fill in the links on our Whales information page: - -- The first link should be linked to a page called `whales.html`, which is in the same directory as the current page. -- We'd also like you to give it a tooltip when moused over that tells the user that the page includes information on Blue Whales and Sperm Whales. -- The second link should be turned into a link you can click to open up an email in the user's default mail application, with the recipient set as "whales\@example.com". -- You'll get a bonus point if you also set it so that the subject line of the email is automatically filled in as "Question about Whales". - -> [!NOTE] -> The two links in the example have the `target="_blank"` attribute set on them. This is not strictly best practice, but we've done it here so that the links don't open in the embedded `<iframe>`, getting rid of your example code in the process! - -Try updating the live code below to recreate the finished example: - -{{EmbedGHLiveSample("learning-area/html/introduction-to-html/tasks/links/links1.html", '100%', 700)}} - -> [!CALLOUT] -> -> [Download the starting point for this task](https://github.com/mdn/learning-area/blob/main/html/introduction-to-html/tasks/links/links1-download.html) to work in your own editor or in an online editor. - -## Task 2 - -In this task, we want you to fill in the four links so that they link to the appropriate places: - -- The first link should link to an image called `blue-whale.jpg`, which is located in a directory called `blue` inside the current directory. -- The second link should link to an image called `narwhal.jpg`, which is located in a directory called `narwhal`, which is located one directory level above the current directory. -- The third link should link to the UK Google Image search. The base URL is `https://www.google.co.uk`, and the image search is located in a subdirectory called `imghp`. -- The fourth link should link to the paragraph at the very bottom of the current page. It has an ID of `bottom`. - -> [!NOTE] -> The first three links in the example have the `target="_blank"` attribute set on them, so that when you click on them, they open the linked page in a new tab. This is not strictly best practice, but we've done it here so that the pages don't open in the embedded `<iframe>`, getting rid of your example code in the process! - -Try updating the live code below to recreate the finished example: - -{{EmbedGHLiveSample("learning-area/html/introduction-to-html/tasks/links/links2.html", '100%', 800)}} - -> [!CALLOUT] -> -> [Download the starting point for this task](https://github.com/mdn/learning-area/blob/main/html/introduction-to-html/tasks/links/links2-download.html) to work in your own editor or in an online editor. - -## Task 3 - -The following links link to an info page about Narwhals, a support email address, and a PDF factfile that is 4MB in size. In this task, we want you to: - -- Take the existing paragraphs with poorly-written link text, and rewrite them so that they have good link text. -- Add a warning to any links that need a warning added. - -> [!NOTE] -> The first and third links in the example have the `target="_blank"` attribute set on them, so that when you click on them, they open the linked page in a new tab. This is not strictly best practice, but we've done it here so that the pages don't open in the embedded `<iframe>`, getting rid of your example code in the process! - -Try updating the live code below to recreate the finished example: - -{{EmbedGHLiveSample("learning-area/html/introduction-to-html/tasks/links/links3.html", '100%', 700)}} - -> [!CALLOUT] -> -> [Download the starting point for this task](https://github.com/mdn/learning-area/blob/main/html/introduction-to-html/tasks/links/links3-download.html) to work in your own editor or in an online editor. diff --git a/files/en-us/learn_web_development/core/structuring_content/webpage_metadata/index.md b/files/en-us/learn_web_development/core/structuring_content/webpage_metadata/index.md index 75d4a0c4697c2bc..3fa56154b0d3393 100644 --- a/files/en-us/learn_web_development/core/structuring_content/webpage_metadata/index.md +++ b/files/en-us/learn_web_development/core/structuring_content/webpage_metadata/index.md @@ -1,11 +1,11 @@ --- -title: What's in the head? Webpage metadata +title: What's in the head? Web page metadata +short-title: Web page metadata slug: Learn_web_development/Core/Structuring_content/Webpage_metadata page-type: tutorial-chapter +sidebar: learnsidebar --- -{{LearnSidebar}} - {{PreviousMenuNext("Learn_web_development/Core/Structuring_content/Basic_HTML_syntax", "Learn_web_development/Core/Structuring_content/Headings_and_paragraphs", "Learn_web_development/Core/Structuring_content")}} The {{glossary("Head", "head")}} of an HTML document is the part that is not displayed in the web browser when the page is loaded. It contains metadata information such as the page {{htmlelement("title")}}, links to {{glossary("CSS")}} (if you choose to style your HTML content with CSS), links to custom favicons, and other metadata (data about the HTML, such as the author, and important keywords that describe the document). @@ -249,7 +249,7 @@ The comments explain what each icon is used for — these elements cover things Don't worry too much about implementing all these types of icon right now — this is a fairly advanced feature, and you won't be expected to have knowledge of this to progress through the course. The main purpose here is to let you know what such things are, in case you come across them while browsing other websites' source code. If you do want to learn more about all these values and how to choose them, read the {{HTMLElement("link")}} element's reference page. > [!NOTE] -> If your site uses a Content Security Policy (CSP) to enhance its security, the policy applies to the favicon. If you encounter problems with the favicon not loading, verify that the {{HTTPHeader("Content-Security-Policy")}} header's [`img-src` directive](/en-US/docs/Web/HTTP/Headers/Content-Security-Policy/img-src) is not preventing access to it. +> If your site uses a Content Security Policy (CSP) to enhance its security, the policy applies to the favicon. If you encounter problems with the favicon not loading, verify that the {{HTTPHeader("Content-Security-Policy")}} header's [`img-src` directive](/en-US/docs/Web/HTTP/Reference/Headers/Content-Security-Policy/img-src) is not preventing access to it. ## Applying CSS and JavaScript to HTML @@ -261,7 +261,7 @@ Just about all websites you'll use in the modern day will employ {{glossary("CSS <link rel="stylesheet" href="my-css-file.css" /> ``` -- The {{htmlelement("script")}} element should also go into the head, and should include a `src` attribute containing the path to the JavaScript you want to load, and `defer`, which basically instructs the browser to load the JavaScript after the page has finished parsing the HTML. This is useful as it makes sure that the HTML is all loaded before the JavaScript runs, so that you don't get errors resulting from JavaScript trying to access an HTML element that doesn't exist on the page yet. There are actually a number of ways to handle loading JavaScript on your page, but this is the most reliable one to use for modern browsers (for others, read [Script loading strategies](/en-US/docs/Learn_web_development/Core/Scripting/What_is_JavaScript#script_loading_strategies)). +- The {{htmlelement("script")}} element should also go into the head, and should include a `src` attribute containing the path to the JavaScript you want to load, and `defer` (a [boolean attribute](/en-US/docs/Learn_web_development/Core/Structuring_content/Basic_HTML_syntax#boolean_attributes)), which instructs the browser to load the JavaScript after the page has finished parsing the HTML. The `defer` attribute is useful as it guarantees the HTML is all loaded before the JavaScript runs so that you don't get errors due to JavaScript trying to access an HTML element that doesn't exist on the page yet. There are [several ways](/en-US/docs/Learn_web_development/Core/Scripting/What_is_JavaScript#script_loading_strategies) to handle loading JavaScript on your page, but this is the most reliable one to use for modern browsers. ```html <script src="my-js-file.js" defer></script> @@ -288,7 +288,7 @@ If done correctly, when you save your HTML and refresh your browser you should b ## Setting the primary language of the document -Finally, it's worth mentioning that you can (and really should) set the language of your page. This can be done by adding the [lang attribute](/en-US/docs/Web/HTML/Global_attributes/lang) to the opening HTML tag (as seen in the [meta-example.html](https://github.com/mdn/learning-area/blob/main/html/introduction-to-html/the-html-head/meta-example.html) and shown below.) +Finally, it's worth mentioning that you can (and really should) set the language of your page. This can be done by adding the [lang attribute](/en-US/docs/Web/HTML/Reference/Global_attributes/lang) to the opening HTML tag (as seen in the [meta-example.html](https://github.com/mdn/learning-area/blob/main/html/introduction-to-html/the-html-head/meta-example.html) and shown below.) ```html <html lang="en-US"> diff --git a/files/en-us/learn_web_development/core/styling_basics/advanced_styling_effects/index.md b/files/en-us/learn_web_development/core/styling_basics/advanced_styling_effects/index.md index cf48ebcf52a4fab..d031580de19f990 100644 --- a/files/en-us/learn_web_development/core/styling_basics/advanced_styling_effects/index.md +++ b/files/en-us/learn_web_development/core/styling_basics/advanced_styling_effects/index.md @@ -2,10 +2,9 @@ title: Advanced styling effects slug: Learn_web_development/Core/Styling_basics/Advanced_styling_effects page-type: guide +sidebar: learnsidebar --- -{{LearnSidebar}} - This article acts as a box of tricks, providing an introduction to some interesting advanced styling features such as box shadows, blend modes, and filters. <table> diff --git a/files/en-us/learn_web_development/core/styling_basics/attribute_selectors/index.md b/files/en-us/learn_web_development/core/styling_basics/attribute_selectors/index.md index eaab3dd06b00a96..41f2c6e89d56198 100644 --- a/files/en-us/learn_web_development/core/styling_basics/attribute_selectors/index.md +++ b/files/en-us/learn_web_development/core/styling_basics/attribute_selectors/index.md @@ -2,10 +2,9 @@ title: Attribute selectors slug: Learn_web_development/Core/Styling_basics/Attribute_selectors page-type: learn-module-chapter +sidebar: learnsidebar --- -{{LearnSidebar}} - {{PreviousMenuNext("Learn_web_development/Core/Styling_basics/Basic_selectors", "Learn_web_development/Core/Styling_basics/Pseudo_classes_and_elements", "Learn_web_development/Core/Styling_basics")}} As you know from your study of HTML, elements can have attributes that give further detail about the element being marked up. In CSS you can use attribute selectors to target elements with certain attributes. This lesson will show you how to use these very useful selectors. @@ -18,7 +17,7 @@ As you know from your study of HTML, elements can have attributes that give furt HTML basics (study <a href="/en-US/docs/Learn_web_development/Core/Structuring_content/Basic_HTML_syntax" >Basic HTML syntax</a - >), <a href="/en-US/docs/Learn_web_development/Core/Styling_basics/Basic_selectors">Basic CSS selectors<a>. + >), <a href="/en-US/docs/Learn_web_development/Core/Styling_basics/Basic_selectors">Basic CSS selectors</a>. </td> </tr> <tr> @@ -38,12 +37,12 @@ As you know from your study of HTML, elements can have attributes that give furt These selectors enable the selection of an element based on the presence of an attribute alone (for example `href`), or on various different matches against the value of the attribute. -| Selector | Example | Description | -| -------------------- | ------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------- | -| `[*attr*]` | `a[title]` | Matches elements with an _attr_ attribute (whose name is the value in square brackets). | -| `[*attr*=*value*]` | `a[href="https://example.com"]` | Matches elements with an _attr_ attribute whose value is exactly _value_ — the string inside the quotes. | -| `[*attr*~=*value*]` | `p[class~="special"]` | Matches elements with an _attr_ attribute whose value is exactly _value_, or contains _value_ in its (space-separated) list of values. | -| `[*attr*\|=*value*]` | `div[lang\|="zh"]` | Matches elements with an _attr_ attribute whose value is exactly _value_ or begins with _value_ immediately followed by a hyphen. | +| Selector | Example | Description | +| ---------------- | ------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------- | +| `[attr]` | `a[title]` | Matches elements with an _attr_ attribute (whose name is the value in square brackets). | +| `[attr=value]` | `a[href="https://example.com"]` | Matches elements with an _attr_ attribute whose value is exactly _value_ — the string inside the quotes. | +| `[attr~=value]` | `p[class~="special"]` | Matches elements with an _attr_ attribute whose value is exactly _value_, or contains _value_ in its (space-separated) list of values. | +| `[attr\|=value]` | `div[lang\|="zh"]` | Matches elements with an _attr_ attribute whose value is exactly _value_ or begins with _value_ immediately followed by a hyphen. | In the example below you can see these selectors being used. diff --git a/files/en-us/learn_web_development/core/styling_basics/backgrounds_and_borders/index.md b/files/en-us/learn_web_development/core/styling_basics/backgrounds_and_borders/index.md index d7e9975dd564508..668841f24debd2c 100644 --- a/files/en-us/learn_web_development/core/styling_basics/backgrounds_and_borders/index.md +++ b/files/en-us/learn_web_development/core/styling_basics/backgrounds_and_borders/index.md @@ -2,10 +2,9 @@ title: Backgrounds and borders slug: Learn_web_development/Core/Styling_basics/Backgrounds_and_borders page-type: learn-module-chapter +sidebar: learnsidebar --- -{{LearnSidebar}} - {{PreviousMenuNext("Learn_web_development/Core/Styling_basics/Sizing", "Learn_web_development/Core/Styling_basics/Overflow", "Learn_web_development/Core/Styling_basics")}} In this lesson, we will take a look at some of the creative things you can do with CSS backgrounds and borders. From adding gradients, background images, and rounded corners, backgrounds and borders are the answer to a lot of styling questions in CSS. @@ -431,7 +430,7 @@ Take a look at the MDN page for {{cssxref("background")}} to see all of the cons ## Accessibility considerations with backgrounds -When placing text on top of a background image or color, you should take care that you have enough [contrast](/en-US/docs/Web/Accessibility/Understanding_WCAG/Perceivable/Color_contrast) for the text to be legible for your visitors. If specifying an image, and if text will be placed on top of that image, you should also specify a `background-color` that will allow the text to be legible if the image does not load. +When placing text on top of a background image or color, you should take care that you have enough [contrast](/en-US/docs/Web/Accessibility/Guides/Understanding_WCAG/Perceivable/Color_contrast) for the text to be legible for your visitors. If specifying an image, and if text will be placed on top of that image, you should also specify a `background-color` that will allow the text to be legible if the image does not load. Screen readers cannot parse background images; therefore, they should be purely decoration. Any important content should be part of the HTML page and not contained in a background. @@ -476,7 +475,7 @@ There are longhand properties for width, style, and color for each of the four s ``` > [!NOTE] -> These top, right, bottom, and left border properties also have mapped [_logical_ border properties](/en-US/docs/Web/CSS/CSS_logical_properties_and_values#properties) that relate to the writing mode of the document (e.g. left-to-right or right-to-left text, or top-to-bottom). We will explore these in the lesson on [handling different text directions](/en-US/docs/Learn_web_development/Core/Styling_basics/Handling_different_text_directions). +> These top, right, bottom, and left border properties also have mapped [_logical_ border properties](/en-US/docs/Web/CSS/CSS_logical_properties_and_values#properties) that relate to the writing mode of the document (e.g., left-to-right or right-to-left text, or top-to-bottom). We will explore these in the lesson on [handling different text directions](/en-US/docs/Learn_web_development/Core/Styling_basics/Handling_different_text_directions). There are a variety of styles that you can use for borders. In the example below, we have used two different border styles for the box and two different border styles for the heading. Play with the border style, width, and color to see how borders work. @@ -554,7 +553,7 @@ We have set all four corners in the example below and then changed the values fo ## Test your skills! -You've reached the end of this article, but can you remember the most important information? You can find some further tests to verify that you've retained this information before you move on — see [Test your skills: Backgrounds and borders](/en-US/docs/Learn_web_development/Core/Styling_basics/Test_your_skills_backgrounds_and_borders). +You've reached the end of this article, but can you remember the most important information? You can find some further tests to verify that you've retained this information before you move on — see [Test your skills: Backgrounds and borders](/en-US/docs/Learn_web_development/Core/Styling_basics/Test_your_skills/Backgrounds_and_borders). ## Summary diff --git a/files/en-us/learn_web_development/core/styling_basics/basic_selectors/index.md b/files/en-us/learn_web_development/core/styling_basics/basic_selectors/index.md index a2f304d8147bc6d..dfe242861b24832 100644 --- a/files/en-us/learn_web_development/core/styling_basics/basic_selectors/index.md +++ b/files/en-us/learn_web_development/core/styling_basics/basic_selectors/index.md @@ -1,11 +1,11 @@ --- title: Basic CSS selectors +short-title: Basic selectors slug: Learn_web_development/Core/Styling_basics/Basic_selectors page-type: learn-module-chapter +sidebar: learnsidebar --- -{{LearnSidebar}} - {{PreviousMenuNext("Learn_web_development/Core/Styling_basics/Styling_a_bio_page", "Learn_web_development/Core/Styling_basics/Attribute_selectors", "Learn_web_development/Core/Styling_basics")}} You've already seen how, in {{Glossary("CSS")}}, selectors are used to target the {{glossary("HTML")}} elements on our web pages that we want to style. There are a wide variety of CSS selectors available, allowing for fine-grained precision when selecting elements to style, and in the next few articles we'll look at the different types in depth. In this article we'll recap some selector fundamentals, including the basic type, class, and ID selectors, and selector lists. We'll also introduce the universal selector. @@ -401,7 +401,7 @@ In this article we've recapped CSS selectors, which enable you to target particu ## See also -- [CSS classes](https://v2.scrimba.com/the-frontend-developer-career-path-c0j/~01d?via=mdn), Scrimba <sup>_MDN learning partner_</sup> +- [CSS classes](https://scrimba.com/the-frontend-developer-career-path-c0j/~01d?via=mdn), Scrimba <sup>[_MDN learning partner_](/en-US/docs/MDN/Writing_guidelines/Learning_content#partner_links_and_embeds)</sup> - : An interactive lesson that provides some guidance on CSS classes. {{PreviousMenuNext("Learn_web_development/Core/Styling_basics/Styling_a_bio_page", "Learn_web_development/Core/Styling_basics/Attribute_selectors", "Learn_web_development/Core/Styling_basics")}} diff --git a/files/en-us/learn_web_development/core/styling_basics/basic_selectors/selectors_tasks/index.md b/files/en-us/learn_web_development/core/styling_basics/basic_selectors/selectors_tasks/index.md deleted file mode 100644 index b8394a86be8664e..000000000000000 --- a/files/en-us/learn_web_development/core/styling_basics/basic_selectors/selectors_tasks/index.md +++ /dev/null @@ -1,407 +0,0 @@ ---- -title: "Test your skills: Selectors" -slug: Learn_web_development/Core/Styling_basics/Basic_selectors/Selectors_Tasks -page-type: learn-module-assessment ---- - -{{LearnSidebar}} - -The aim of this skill test is to assess whether you understand [CSS selectors](/en-US/docs/Learn_web_development/Core/Styling_basics/Basic_selectors). - -> [!NOTE] -> Click **"Play"** in the code blocks below to edit the examples in the MDN Playground. -> You can also copy the code (click the clipboard icon) and paste it into an online editor such as [CodePen](https://codepen.io/), [JSFiddle](https://jsfiddle.net/), or [Glitch](https://glitch.com/). -> If you get stuck, you can reach out to us in one of our [communication channels](/en-US/docs/MDN/Community/Communication_channels). - -## Task 1 - -In this task, use CSS to do the following things, without changing the HTML: - -- Make `<h1>` headings blue. -- Give `<h2>` headings a blue background and white text. -- Cause text wrapped in a `<span>` to have a font-size of 200%. - -Your final result should look like the image below: - -![Text with the CSS applied for the solution to task 1.](selectors1.jpg) - -Try to update the code below to recreate the finished example: - -```html live-sample___type -<div class="container"> - <h1>This is a heading</h1> - <p> - Veggies es <span>bonus vobis</span>, proinde vos postulo essum magis - kohlrabi welsh onion daikon amaranth tatsoi tomatillo melon azuki bean - garlic. - </p> - <h2>A level 2 heading</h2> - <p> - Gumbo beet greens corn soko endive gumbo gourd. Parsley shallot courgette - tatsoi pea sprouts fava bean collard greens dandelion okra wakame tomato. - Dandelion cucumber earthnut pea peanut soko zucchini. - </p> -</div> -``` - -```css live-sample___type -body { - font: 1.2em / 1.5 sans-serif; -} -/* Add styles here */ -``` - -{{EmbedLiveSample("type", "", "260px")}} - -<details> -<summary>Click here to show the solution</summary> - -You need to target the `h1`, `h2` and `span` selectors to change their color or size. - -```css -h1 { - color: blue; -} - -h2 { - background-color: blue; - color: white; -} - -span { - font-size: 200%; -} -``` - -</details> - -## Task 2 - -In this task, we want you to make the following changes to the look of the content in this example, without changing the HTML: - -- Give the element with an id of `special` a yellow background. -- Give the element with a class of `alert` a 2px grey border. -- If the element with a class of `alert` also has a class of `stop`, make the background red. -- If the element with a class of `alert` also has a class of `go`, make the background green. - -Your final result should look like the image below: - -![Text with the CSS applied for the solution to task 2.](selectors2.jpg) - -Try to update the code below to recreate the finished example: - -```html live-sample___class-id -<div class="container"> - <h1>This is a heading</h1> - <p> - Veggies es <span class="alert">bonus vobis</span>, proinde vos postulo - <span class="alert stop">essum magis</span> kohlrabi welsh onion daikon - amaranth tatsoi tomatillo melon azuki bean garlic. - </p> - <h2 id="special">A level 2 heading</h2> - <p>Gumbo beet greens corn soko endive gumbo gourd.</p> - <h2>Another level 2 heading</h2> - <p> - <span class="alert go">Parsley shallot</span> courgette tatsoi pea sprouts - fava bean collard greens dandelion okra wakame tomato. Dandelion cucumber - earthnut pea peanut soko zucchini. - </p> -</div> -``` - -```css live-sample___class-id -body { - font: 1.2em / 1.5 sans-serif; -} -/* Add styles here */ -``` - -{{EmbedLiveSample("class-id", "", "320px")}} - -<details> -<summary>Click here to show the solution</summary> - -This tests that you understand the difference between class and id selectors and also how to target multiple classes on an item. - -```css -#special { - background-color: yellow; -} - -.alert { - border: 2px solid grey; -} - -.alert.stop { - background-color: red; -} - -.alert.go { - background-color: green; -} -``` - -</details> - -## Task 3 - -In this task, we want you to make the following changes without changing the HTML: - -- Style links, making the link-state orange, visited links green, and remove the underline on hover. -- Make the first element inside the container `font-size: 150%` and the first line of that element red. -- Stripe every other row in the table by selecting these rows and giving them a background color of `#333` and foreground white. - -Your final result should look like the image below: - -![Text with the CSS applied for the solution to task 3.](selectors3.jpg) - -Try to update the code below to recreate the finished example: - -```html live-sample___pseudo -<div class="container"> - <p> - Veggies es <a href="http://example.com">bonus vobis</a>, proinde vos postulo - essum magis kohlrabi welsh onion daikon amaranth tatsoi tomatillo melon - azuki bean garlic. - </p> - <p> - Gumbo beet greens corn soko endive gumbo gourd. Parsley shallot courgette - tatsoi pea sprouts fava bean collard greens dandelion okra wakame tomato. - Dandelion cucumber earthnut pea peanut soko zucchini. - </p> - <table> - <tbody> - <tr> - <th>Fruits</th> - <th>Vegetables</th> - </tr> - <tr> - <td>Apple</td> - <td>Potato</td> - </tr> - <tr> - <td>Orange</td> - <td>Carrot</td> - </tr> - <tr> - <td>Tomato</td> - <td>Parsnip</td> - </tr> - <tr> - <td>Kiwi</td> - <td>Onion</td> - </tr> - <tr> - <td>Banana</td> - <td>Beet</td> - </tr> - </tbody> - </table> -</div> -``` - -```css hidden live-sample___pseudo -body { - font: 1.2em / 1.5 sans-serif; -} -* { - box-sizing: border-box; -} - -table { - border-collapse: collapse; - width: 300px; -} - -td, -th { - padding: 0.2em; - text-align: left; -} -``` - -```css live-sample___pseudo -/* Add styles here */ -``` - -{{EmbedLiveSample("pseudo", "", "320px")}} - -<details> -<summary>Click here to show the solution</summary> - -Apply a pseudo-class (`:first-child`) and pseudo-element (`::first-line`) to the content. -Style the `:link`, `:visited`, and `:hover` states of the `a` element, and create striped table rows using the `:nth-child` pseudo-class. - -```css -.container p:first-child { - font-size: 150%; -} - -.container p:first-child::first-line { - color: red; -} - -a:link { - color: orange; -} - -a:visited { - color: green; -} - -a:hover { - text-decoration: none; -} - -tr:nth-child(even) { - background-color: #333; - color: #fff; -} -``` - -</details> - -## Task 4 - -In this task, we want you to do the following: - -- Make any paragraph that directly follows an `<h2>` element red. -- Remove the bullets and add a 1px grey bottom border only to list items that are a direct child of the ul with a class of `list`. - -Your final result should look like the image below: - -![Text with the CSS applied for the solution to task 4.](selectors4.jpg) - -Try to update the code below to recreate the finished example: - -```html live-sample___combinators -<div class="container"> - <h2>This is a heading</h2> - <p>This paragraph comes after the heading.</p> - <p>This is the second paragraph.</p> - - <h2>Another heading</h2> - <p>This paragraph comes after the heading.</p> - <ul class="list"> - <li>One</li> - <li> - Two - <ul> - <li>2.1</li> - <li>2.2</li> - </ul> - </li> - <li>Three</li> - </ul> -</div> -``` - -```css live-sample___combinators -body { - font: 1.2em / 1.5 sans-serif; -} -/* Add styles here */ -``` - -{{EmbedLiveSample("combinators", "", "350px")}} - -<details> -<summary>Click here to show the solution</summary> - -This task checks that you understand how to use different combinators. -Here's an appropriate solution: - -```css -h2 + p { - color: red; -} - -.list > li { - list-style: none; - border-bottom: 1px solid #ccc; -} -``` - -</details> - -## Task 5 - -In this task, add CSS using attribute selectors to do the following: - -- Target the `<a>` element with a `title` attribute and make the border pink (`border-color: pink`). -- Target the `<a>` element with an `href` attribute that contains the word `contact` somewhere in its value and make the border orange (`border-color: orange`). -- Target the `<a>` element with an `href` value starting with `https` and give it a green border (`border-color: green`). - -Your final result should look like the image below: - -![Four links with different color borders.](selectors-attribute.png) - -Try to update the code below to recreate the finished example: - -```html live-sample___attribute-links -<ul> - <li><a href="https://example.com">Link 1</a></li> - <li><a href="http://example.com" title="Visit example.com">Link 2</a></li> - <li><a href="/contact">Link 3</a></li> - <li><a href="../contact/index.html">Link 4</a></li> -</ul> -``` - -```css hidden live-sample___attribute-links -body { - font: 1.2em / 1.5 sans-serif; -} - -ul { - list-style: none; - margin: 0; - padding: 0; -} - -li { - margin: 0 0 0.5em 0; -} - -a { - display: block; - padding: 0.5em; -} -``` - -```css live-sample___attribute-links -a { - border: 5px solid grey; -} -/* Add styles here */ -``` - -{{EmbedLiveSample("attribute-links", "", "300px")}} - -<details> -<summary>Click here to show the solution</summary> - -- To select elements with a title attribute we can add title inside the square brackets (`a[title]`), which will select the second link, which is the only one with a title attribute. - -- Target the `<a>` element with an `href` attribute which contains the word "contact" anywhere in its value and make the border orange (`border-color: orange`). - There are two things we want to match here, the href value `/contact` and also `../contact`. So we need to match the string "contact" anywhere in the value using `*=`. This will select the third and fourth links. - -- Target the `<a>` element with an href value starting with `https` and give it a green border (`border-color: green`). - Look for an `href` value which starts with "https", so use `^=` to only select the first link. - -```css -a[title] { - border-color: pink; -} -a[href*="contact"] { - border-color: orange; -} -a[href^="https"] { - border-color: green; -} -``` - -</details> - -## See also - -- [CSS styling basics](/en-US/docs/Learn_web_development/Core/Styling_basics) diff --git a/files/en-us/learn_web_development/core/styling_basics/box_model/index.md b/files/en-us/learn_web_development/core/styling_basics/box_model/index.md index 658816d5c6a492e..1d6aac965fdf967 100644 --- a/files/en-us/learn_web_development/core/styling_basics/box_model/index.md +++ b/files/en-us/learn_web_development/core/styling_basics/box_model/index.md @@ -1,11 +1,11 @@ --- title: The box model +short-title: Box model slug: Learn_web_development/Core/Styling_basics/Box_model page-type: learn-module-chapter +sidebar: learnsidebar --- -{{LearnSidebar}} - {{PreviousMenuNext("Learn_web_development/Core/Styling_basics/Combinators", "Learn_web_development/Core/Styling_basics/Handling_conflicts", "Learn_web_development/Core/Styling_basics")}} Everything in CSS has a box around it, and understanding these boxes is key to being able to create more complex layouts with CSS, or to align items with other items. In this lesson, we will take a look at the CSS _Box model_. You'll get an understanding of how it works and the terminology that relates to it. @@ -290,7 +290,7 @@ Can you change the size of the second box (by adding CSS to the `.alternate` cla {{EmbedLiveSample("box-models", "", "400px")}} > [!NOTE] -> You can find a solution for this task [here](https://github.com/mdn/css-examples/blob/main/learn/solutions.md#the-box-model). +> You can find a solution for this task [in our css-examples repo](https://github.com/mdn/css-examples/blob/main/learn/solutions.md#the-box-model). ### Use browser DevTools to view the box model @@ -616,7 +616,7 @@ li { ## Test your skills! -You've reached the end of this article, but can you remember the most important information? You can find some further tests to verify that you've retained this information before you move on — see [Test your skills: The box model](/en-US/docs/Learn_web_development/Core/Styling_basics/Box_Model_Tasks). +You've reached the end of this article, but can you remember the most important information? You can find some further tests to verify that you've retained this information before you move on — see [Test your skills: The box model](/en-US/docs/Learn_web_development/Core/Styling_basics/Test_your_skills/Box_model). ## Summary diff --git a/files/en-us/learn_web_development/core/styling_basics/box_model_tasks/index.md b/files/en-us/learn_web_development/core/styling_basics/box_model_tasks/index.md deleted file mode 100644 index 114d570c404f8c6..000000000000000 --- a/files/en-us/learn_web_development/core/styling_basics/box_model_tasks/index.md +++ /dev/null @@ -1,172 +0,0 @@ ---- -title: "Test your skills: The box model" -slug: Learn_web_development/Core/Styling_basics/Box_Model_Tasks -page-type: learn-module-assessment ---- - -{{LearnSidebar}} - -The aim of this skill test is to assess whether you understand the [CSS box model](/en-US/docs/Learn_web_development/Core/Styling_basics/Box_model). - -> [!NOTE] -> Click **"Play"** in the code blocks below to edit the examples in the MDN Playground. -> You can also copy the code (click the clipboard icon) and paste it into an online editor such as [CodePen](https://codepen.io/), [JSFiddle](https://jsfiddle.net/), or [Glitch](https://glitch.com/). -> If you get stuck, you can reach out to us in one of our [communication channels](/en-US/docs/MDN/Community/Communication_channels). - -## Task 1 - -In this task, there are two boxes below, one is using the standard box model, the other the alternate box model. Change the width of the second box by adding declarations to the `.alternate` class, so that it matches the visual width of the first box. - -Your final result should look like the image below: - -![Two boxes of the same size](mdn-box-model1.png) - -Try to update the code below to recreate the finished example: - -```html live-sample___box-models -<div class="box">I use the standard box model.</div> -<div class="box alternate">I use the alternate box model.</div> -``` - -```css live-sample___box-models -body { - font: 1.2em / 1.5 sans-serif; -} -.box { - border: 5px solid rebeccapurple; - background-color: lightgray; - padding: 40px; - margin: 40px; - width: 300px; - height: 150px; -} - -.alternate { - box-sizing: border-box; -} -``` - -{{EmbedLiveSample("box-models", "", "540px")}} - -<details> -<summary>Click here to show the solution</summary> - -You will need to increase the width of the second block, to add the size of the padding and border: - -```css -.alternate { - box-sizing: border-box; - width: 390px; -} -``` - -</details> - -## Task 2 - -In this task, add the following things to the box: - -- A 5px, black, dotted border. -- A top margin of 20px. -- A right margin of 1em. -- A bottom margin of 40px. -- A left margin of 2em. -- Padding on all sides of 1em. - -Your final result should look like the image below: - -![A box with a dotted border](mdn-box-model2.png) - -Try to update the code below to recreate the finished example: - -```html live-sample___mbp -<div class="box">I use the standard box model.</div> -``` - -```css live-sample___mbp -body { - font: 1.2em / 1.5 sans-serif; -} - -.box { -} -``` - -{{EmbedLiveSample("mbp")}} - -<details> -<summary>Click here to show the solution</summary> - -This task involves using the margin, border and padding properties correctly. -You might choose to use the longhand properties ({{cssxref("margin-top")}}, {{cssxref("margin-right")}}, etc.), however when setting a margin and padding on all sides, the shorthand is probably the better choice: - -```css -.box { - border: 5px dotted black; - margin: 20px 1em 40px 2em; - padding: 1em; -} -``` - -</details> - -## Task 3 - -In this task, the inline element has a margin, padding and border. However, the lines above and below are overlapping it. What can you add to your CSS to cause the size of the margin, padding, and border to be respected by the other lines, while still keeping the element inline? - -Your final result should look like the image below: - -![An inline box with space between it and the text around it.](mdn-box-model3.png) - -Try to update the code below to recreate the finished example: - -```html live-sample___inline-block -<div class="box"> - <p> - Veggies es bonus vobis, <span>proinde vos postulo</span> essum magis - kohlrabi welsh onion daikon amaranth tatsoi tomatillo melon azuki bean - garlic. - </p> - - <p> - Gumbo beet greens corn soko endive gumbo gourd. Parsley shallot courgette - tatsoi pea sprouts fava bean collard greens dandelion okra wakame tomato. - Dandelion cucumber earthnut pea peanut soko zucchini. - </p> -</div> -``` - -```css live-sample___inline-block -body { - font: 1.2em / 1.5 sans-serif; -} - -.box span { - background-color: pink; - border: 5px solid black; - padding: 1em; -} -``` - -{{EmbedLiveSample("inline-block")}} - -<details> -<summary>Click here to show the solution</summary> - -Solving this task requires that you understand when to use different {{cssxref("display")}} values. -After adding `display: inline-block`, the block direction margin, border and padding will cause the other lines to be pushed away from the element: - -```css -.box span { - background-color: pink; - border: 5px solid black; - padding: 1em; - display: inline-block; -} -``` - -</details> - -## See also - -- [CSS styling basics](/en-US/docs/Learn_web_development/Core/Styling_basics) diff --git a/files/en-us/learn_web_development/core/styling_basics/cascade_layers/index.md b/files/en-us/learn_web_development/core/styling_basics/cascade_layers/index.md index 5f0b61e23fec946..395af0e6c4ea86c 100644 --- a/files/en-us/learn_web_development/core/styling_basics/cascade_layers/index.md +++ b/files/en-us/learn_web_development/core/styling_basics/cascade_layers/index.md @@ -2,10 +2,9 @@ title: Cascade layers slug: Learn_web_development/Core/Styling_basics/Cascade_layers page-type: learn-module-chapter +sidebar: learnsidebar --- -{{LearnSidebar}} - This lesson aims to introduce you to [cascade layers](/en-US/docs/Web/CSS/@layer), a more advanced feature that builds on the fundamental concepts of the [CSS cascade](/en-US/docs/Web/CSS/CSS_cascade/Cascade) and [CSS specificity](/en-US/docs/Web/CSS/CSS_cascade/Specificity). If you are new to CSS, working through this lesson may seem less relevant immediately and a little more academic than some other parts of the course. However, knowing the basics of what cascade layers are should you encounter them in your projects is helpful. The more you work with CSS, understanding cascade layers and knowing how to leverage their power will save you from a lot of pain managing a code base with CSS from different parties, plugins, and development teams. @@ -398,7 +397,7 @@ Normal styles declared inside layers receive the lowest priority and are sorted Next up are any styles declared outside of layers. The styles in `C.css` were not imported into a layer and will override any conflicting styles from `firstLayer` and `secondLayer`. Styles not declared in a layer always have higher precedence than styles that _are_ declared inside a layer (with the exception of important styles). -Inline styles are declared using the [`style` attribute](/en-US/docs/Web/HTML/Global_attributes/style). Normal styles declared in this way will take precedence over normal styles found in the unlayered and layered style sheets (`firstLayer – A.css`, `secondLayer – B.css`, and `C.css`). +Inline styles are declared using the [`style` attribute](/en-US/docs/Web/HTML/Reference/Global_attributes/style). Normal styles declared in this way will take precedence over normal styles found in the unlayered and layered style sheets (`firstLayer – A.css`, `secondLayer – B.css`, and `C.css`). Animating styles have higher precedence than all normal styles, including inline normal styles. @@ -544,7 +543,7 @@ Here's a summary of the properties that are used and why each declaration is app ## Test your skills! -You've reached the end of this article, but can you remember the most important information? You can find some further tests to verify that you've retained this information before you move on — see [Test your skills: The Cascade, Task 2](/en-US/docs/Learn_web_development/Core/Styling_basics/Cascade_tasks#task_2). +You've reached the end of this article, but can you remember the most important information? You can find some further tests to verify that you've retained this information before you move on — see [Test your skills: The Cascade, Task 2](/en-US/docs/Learn_web_development/Core/Styling_basics/Test_your_skills/Cascade#task_2). ## Summary diff --git a/files/en-us/learn_web_development/core/styling_basics/cascade_tasks/index.md b/files/en-us/learn_web_development/core/styling_basics/cascade_tasks/index.md deleted file mode 100644 index 95a0b07bc9c5c14..000000000000000 --- a/files/en-us/learn_web_development/core/styling_basics/cascade_tasks/index.md +++ /dev/null @@ -1,133 +0,0 @@ ---- -title: "Test your skills: The Cascade" -slug: Learn_web_development/Core/Styling_basics/Cascade_tasks -page-type: learn-module-assessment ---- - -{{LearnSidebar}} - -The aim of this skill test is to assess whether you understand universal property values for [controlling inheritance in CSS](/en-US/docs/Learn_web_development/Core/Styling_basics/Handling_conflicts). - -> [!NOTE] -> Click **"Play"** in the code blocks below to edit the examples in the MDN Playground. -> You can also copy the code (click the clipboard icon) and paste it into an online editor such as [CodePen](https://codepen.io/), [JSFiddle](https://jsfiddle.net/), or [Glitch](https://glitch.com/). -> If you get stuck, you can reach out to us in one of our [communication channels](/en-US/docs/MDN/Community/Communication_channels). - -## Task 1 - -In this task, we want you to use one of the special values we looked at in the [controlling inheritance](/en-US/docs/Learn_web_development/Core/Styling_basics/Handling_conflicts#controlling_inheritance) section. To write a declaration in a new rule that will reset the background color back to white, without using an actual color value. - -Your final result should look like the image below: - -![Barely visible yellow links on a white background.](mdn-cascade.png) - -Try to update the code below to recreate the finished example: - -```html live-sample___cascade -<div class="container" id="outer"> - <div class="container" id="inner"> - <ul> - <li class="nav"><a href="#">One</a></li> - <li class="nav"><a href="#">Two</a></li> - </ul> - </div> -</div> -``` - -```css live-sample___cascade -#outer div ul .nav a { - background-color: powderblue; - padding: 5px; - display: inline-block; - margin-bottom: 10px; -} - -div div li a { - color: rebeccapurple; -} -``` - -{{EmbedLiveSample("cascade")}} - -<details> -<summary>Click here to show the solution</summary> - -One possible solution is as follows: - -```css -#outer #inner a { - background-color: initial; -} -``` - -There are two things you need to do in this task. First, write a selector for the `a` element which is more specific than the selector used to turn the background powderblue. In this solution, this is achieved by using the `id` selector, which has very high specificity. - -Then you need to remember there are special keyword values for all properties. In this case, using `inherit` sets the background color back to be the same as its parent element. - -</details> - -## Task 2 - -In this task, we want you to manipulate the cascade layer order to color the links `rebeccapurple`. No editing the `lightgreen` declaration! - -This task is a stretch goal — it requires knowledge of cascade layers, which we didn't cover in the [Handling conflicts](/en-US/docs/Learn_web_development/Core/Styling_basics/Handling_conflicts) article. You can find the information you need to attempt this task at [Cascade layers > Determining the precedence based on the order of layers](/en-US/docs/Learn_web_development/Core/Styling_basics/Cascade_layers#determining_the_precedence_based_on_the_order_of_layers). - -Your final result should look like the image below: - -![Barely visible yellow links on a white background.](mdn-cascade.png) - -Try to update the code below to recreate the finished example: - -```html live-sample___cascade-layer -<div class="container" id="outer"> - <div class="container" id="inner"> - <ul> - <li class="nav"><a href="#">One</a></li> - <li class="nav"><a href="#">Two</a></li> - </ul> - </div> -</div> -``` - -```css live-sample___cascade-layer -@layer yellow, purple, green; - -@layer yellow { - #outer div ul .nav a { - padding: 5px; - display: inline-block; - margin-bottom: 10px; - } -} -@layer purple { - div div li a { - color: rebeccapurple; - } -} -@layer green { - a { - color: lightgreen; - } -} -``` - -{{EmbedLiveSample("cascade-layer")}} - -<details> -<summary>Click here to show the solution</summary> - -One possible solution is as follows: - -```css -@layer yellow, green, purple; -``` - -There is one thing you need to do in this task: change the order of precedence so the declaration for the desired color is in the last declared layer, which is what his solution shows. - -You need to remember that unlayered normal styles take precedence over layered normal styles. But, if all styles are within layers — as in the case of this task — styles in later declared layers take precedence over styles declared in earlier layers. Moving the purple layer to the end means it has precedence over the green and yellow layers. - -</details> - -## See also - -- [CSS styling basics](/en-US/docs/Learn_web_development/Core/Styling_basics) diff --git a/files/en-us/learn_web_development/core/styling_basics/combinators/index.md b/files/en-us/learn_web_development/core/styling_basics/combinators/index.md index e8f09a86a4e6f69..15978f638ff4c8d 100644 --- a/files/en-us/learn_web_development/core/styling_basics/combinators/index.md +++ b/files/en-us/learn_web_development/core/styling_basics/combinators/index.md @@ -2,10 +2,9 @@ title: Combinators slug: Learn_web_development/Core/Styling_basics/Combinators page-type: learn-module-chapter +sidebar: learnsidebar --- -{{LearnSidebar}} - {{PreviousMenuNext("Learn_web_development/Core/Styling_basics/Pseudo_classes_and_elements", "Learn_web_development/Core/Styling_basics/Box_model", "Learn_web_development/Core/Styling_basics")}} The final selectors we will look at are called combinators. Combinators are used to combine other selectors in a way that allows us to select elements based on their location in the DOM relative to other elements (for example, child or sibling). @@ -18,7 +17,7 @@ The final selectors we will look at are called combinators. Combinators are used HTML basics (study <a href="/en-US/docs/Learn_web_development/Core/Structuring_content/Basic_HTML_syntax" >Basic HTML syntax</a - >), <a href="/en-US/docs/Learn_web_development/Core/Styling_basics/Basic_selectors">Basic CSS selectors<a>. + >), <a href="/en-US/docs/Learn_web_development/Core/Styling_basics/Basic_selectors">Basic CSS selectors</a>. </td> </tr> <tr> @@ -65,7 +64,9 @@ In the example below, we are matching only the `<p>` element which is inside an The **child combinator** (`>`) is placed between two CSS selectors. It matches only those elements matched by the second selector that are the direct children of elements matched by the first. Descendant elements further down the hierarchy don't match. For example, to select only `<p>` elements that are direct children of `<article>` elements: ```css -article > p +article > p { + /* … */ +} ``` In this next example, we have an ordered list ({{htmlelement("ol")}}) nested inside an unordered list ({{htmlelement("ul")}}). The child combinator selects only those `<li>` elements which are direct children of a `<ul>`, and styles them with a top border. @@ -98,7 +99,9 @@ ul > li { The **next-sibling combinator** (`+`) is placed between two CSS selectors. It matches only those elements matched by the second selector that come right after the element matched by the first selector. For example, to select all `<img>` elements that are immediately preceded by a `<p>` element: ```css -p + img +p + img { + /* … */ +} ``` A common use case is to do something with a paragraph that follows a heading, as in the example below. In that example, we are looking for any paragraph which shares a parent element with an `<h1>`, and immediately follows that `<h1>`. @@ -141,7 +144,9 @@ h1 + p { If you want to select siblings of an element even if they are not directly adjacent, then you can use the **subsequent-sibling combinator** (`~`). To select all `<img>` elements that come _anywhere_ after `<p>` elements, we'd do this: ```css -p ~ img +p ~ img { + /* … */ +} ``` In the example below we are selecting all `<p>` elements that come after the `<h1>`, and even though there is a `<div>` in the document as well, the `<p>` that comes after it is selected. @@ -243,7 +248,7 @@ It is often better to create a simple class and apply that to the element in que ## Test your skills! -You've reached the end of our set of lessons about selectors, but can you remember the most important information? You can find some further tests to verify that you've retained this information before you move on — see [Test your skills: Selectors](/en-US/docs/Learn_web_development/Core/Styling_basics/Basic_selectors/Selectors_Tasks). +You've reached the end of our set of lessons about selectors, but can you remember the most important information? You can find some further tests to verify that you've retained this information before you move on — see [Test your skills: Selectors](/en-US/docs/Learn_web_development/Core/Styling_basics/Test_your_skills/Selectors). ## Summary diff --git a/files/en-us/learn_web_development/core/styling_basics/cool-looking_box/index.md b/files/en-us/learn_web_development/core/styling_basics/cool-looking_box/index.md index d69f49b9487921b..74cc431df3f9a49 100644 --- a/files/en-us/learn_web_development/core/styling_basics/cool-looking_box/index.md +++ b/files/en-us/learn_web_development/core/styling_basics/cool-looking_box/index.md @@ -1,11 +1,11 @@ --- title: "Challenge: A cool-looking box" +short-title: "Challenge: Fancy box styles" slug: Learn_web_development/Core/Styling_basics/Cool-looking_box page-type: learn-module-assessment +sidebar: learnsidebar --- -{{LearnSidebar}} - {{PreviousMenuNext("Learn_web_development/Core/Styling_basics/Fancy_letterheaded_paper", "Learn_web_development/Core/Text_styling", "Learn_web_development/Core/Styling_basics")}} In this assessment, you'll get some more practice in creating cool-looking boxes by trying to create an eye-catching box. diff --git a/files/en-us/learn_web_development/core/styling_basics/debugging_css/index.md b/files/en-us/learn_web_development/core/styling_basics/debugging_css/index.md index eb068c677db2742..636b885e8b73b0f 100644 --- a/files/en-us/learn_web_development/core/styling_basics/debugging_css/index.md +++ b/files/en-us/learn_web_development/core/styling_basics/debugging_css/index.md @@ -2,10 +2,9 @@ title: Debugging CSS slug: Learn_web_development/Core/Styling_basics/Debugging_CSS page-type: learn-module-chapter +sidebar: learnsidebar --- -{{LearnSidebar}} - {{PreviousMenuNext("Learn_web_development/Core/Styling_basics/Tables", "Learn_web_development/Core/Styling_basics/Fundamental_CSS_comprehension", "Learn_web_development/Core/Styling_basics")}} Sometimes when writing CSS you will encounter an issue where your CSS doesn't seem to be doing what you expect. Perhaps you believe that a certain selector should match an element, but nothing happens, or a box is a different size than you expected. This article will give you guidance on how to go about debugging a CSS problem, and show you how the DevTools included in all modern browsers can help you to find out what is going on. @@ -171,7 +170,7 @@ In the process of doing this, you may discover what is causing the problem, or a If you are still struggling to fix the problem then having a reduced test case gives you something to ask for help with, by posting to a forum, or showing to a co-worker. You are much more likely to get help if you can show that you have done the work of reducing the problem and identifying exactly where it happens, before asking for help. A more experienced developer might be able to quickly spot the problem and point you in the right direction, and even if not, your reduced test case will enable them to have a quick look and hopefully be able to offer at least some help. -In the instance that your problem is actually a bug in a browser, then a reduced test case can also be used to file a bug report with the relevant browser vendor (e.g. on Mozilla's [bugzilla site](https://bugzilla.mozilla.org/)). +In the instance that your problem is actually a bug in a browser, then a reduced test case can also be used to file a bug report with the relevant browser vendor (e.g., on Mozilla's [bugzilla site](https://bugzilla.mozilla.org/)). As you become more experienced with CSS, you will find that you get faster at figuring out issues. However, even the most experienced of us sometimes find ourselves wondering what on earth is going on. Taking a methodical approach, making a reduced test case, and explaining the issue to someone else will usually result in a fix being found. diff --git a/files/en-us/learn_web_development/core/styling_basics/fancy_letterheaded_paper/index.md b/files/en-us/learn_web_development/core/styling_basics/fancy_letterheaded_paper/index.md index 0f75e6af2d4dbb3..dbd18a75033f4c0 100644 --- a/files/en-us/learn_web_development/core/styling_basics/fancy_letterheaded_paper/index.md +++ b/files/en-us/learn_web_development/core/styling_basics/fancy_letterheaded_paper/index.md @@ -1,11 +1,11 @@ --- title: "Challenge: Creating fancy letterheaded paper" +short-title: "Challenge: Fancy letterhead" slug: Learn_web_development/Core/Styling_basics/Fancy_letterheaded_paper page-type: learn-module-assessment +sidebar: learnsidebar --- -{{LearnSidebar}} - {{PreviousMenuNext("Learn_web_development/Core/Styling_basics/Fundamental_CSS_comprehension", "Learn_web_development/Core/Styling_basics/Cool-looking_box", "Learn_web_development/Core/Styling_basics")}} If you want to make the right impression, writing a letter on nice letterheaded paper can be a really good start. In this challenge you will create an online template to achieve such a look. diff --git a/files/en-us/learn_web_development/core/styling_basics/fundamental_css_comprehension/index.md b/files/en-us/learn_web_development/core/styling_basics/fundamental_css_comprehension/index.md index c90dd3a485ba282..2bde561b7493c18 100644 --- a/files/en-us/learn_web_development/core/styling_basics/fundamental_css_comprehension/index.md +++ b/files/en-us/learn_web_development/core/styling_basics/fundamental_css_comprehension/index.md @@ -1,11 +1,11 @@ --- title: "Challenge: Fundamental CSS comprehension" +short-title: "Challenge: Business card" slug: Learn_web_development/Core/Styling_basics/Fundamental_CSS_comprehension page-type: learn-module-assessment +sidebar: learnsidebar --- -{{LearnSidebar}} - {{PreviousMenuNext("Learn_web_development/Core/Styling_basics/Debugging_CSS", "Learn_web_development/Core/Styling_basics/Fancy_letterheaded_paper", "Learn_web_development/Core/Styling_basics")}} This challenge provides a number of related exercises that must be completed in order to create the final design — a business card/gamer card/social media profile. diff --git a/files/en-us/learn_web_development/core/styling_basics/getting_started/index.md b/files/en-us/learn_web_development/core/styling_basics/getting_started/index.md index e7dc62f123d3948..533d370eaa1193a 100644 --- a/files/en-us/learn_web_development/core/styling_basics/getting_started/index.md +++ b/files/en-us/learn_web_development/core/styling_basics/getting_started/index.md @@ -1,11 +1,11 @@ --- title: Getting started with CSS +short-title: CSS getting started slug: Learn_web_development/Core/Styling_basics/Getting_started page-type: learn-module-chapter +sidebar: learnsidebar --- -{{LearnSidebar}} - {{PreviousMenuNext("Learn_web_development/Core/Styling_basics/What_is_CSS", "Learn_web_development/Core/Styling_basics/Styling_a_bio_page", "Learn_web_development/Core/Styling_basics")}} In this article, we will take a simple HTML document and apply CSS to it, learning some practical details of the language along the way. We will also review the CSS syntax features you've not looked at yet. @@ -215,7 +215,7 @@ li { So far, we have styled elements based on their HTML element names. This works as long as you want all of the elements of that type in your document to look the same. To select a subset of the elements without changing the others, you can add a `class` to your HTML element and target that class in your CSS. -1. In your HTML document, add a [class attribute](/en-US/docs/Web/HTML/Global_attributes/class) to the second list item. Your list will now look like this: +1. In your HTML document, add a [class attribute](/en-US/docs/Web/HTML/Reference/Global_attributes/class) to the second list item. Your list will now look like this: ```html <ul> @@ -298,7 +298,7 @@ h1 + p { ### Styling things based on state -The final type of styling we shall take a look at in this tutorial is the ability to style things based on their state. A straightforward example of this is when styling links. When we style a link, we need to target the [`<a>`](/en-US/docs/Web/HTML/Element/a) (anchor) element. This has different states depending on whether it is unvisited, visited, being hovered over, focused via the keyboard, or in the process of being clicked (activated). You can use CSS to target these different states — the CSS below styles unvisited links pink and visited links green. +The final type of styling we shall take a look at in this tutorial is the ability to style things based on their state. A straightforward example of this is when styling links. When we style a link, we need to target the [`<a>`](/en-US/docs/Web/HTML/Reference/Elements/a) (anchor) element. This has different states depending on whether it is unvisited, visited, being hovered over, focused via the keyboard, or in the process of being clicked (activated). You can use CSS to target these different states — the CSS below styles unvisited links pink and visited links green. ```css a:link { diff --git a/files/en-us/learn_web_development/core/styling_basics/handling_conflicts/index.md b/files/en-us/learn_web_development/core/styling_basics/handling_conflicts/index.md index d1e2327bd43c64d..78ec0eaa8bfdb49 100644 --- a/files/en-us/learn_web_development/core/styling_basics/handling_conflicts/index.md +++ b/files/en-us/learn_web_development/core/styling_basics/handling_conflicts/index.md @@ -2,10 +2,9 @@ title: Handling conflicts slug: Learn_web_development/Core/Styling_basics/Handling_conflicts page-type: learn-module-chapter +sidebar: learnsidebar --- -{{LearnSidebar}} - {{PreviousMenuNext("Learn_web_development/Core/Styling_basics/Box_model", "Learn_web_development/Core/Styling_basics/Values_and_units", "Learn_web_development/Core/Styling_basics")}} The aim of this lesson is to develop your understanding of some of the most fundamental concepts of CSS — the cascade, specificity, and inheritance — which control how CSS is applied to HTML and how conflicts between style declarations are resolved. @@ -191,7 +190,7 @@ CSS provides five special universal property values for controlling inheritance. - {{cssxref("inherit")}} - : Sets the property value applied to a selected element to be the same as that of its parent element. Effectively, this "turns on inheritance". - {{cssxref("initial")}} - - : Sets the property value applied to a selected element to the [initial value](/en-US/docs/Web/CSS/CSS_cascade/initial_value) of that property. + - : Sets the property value applied to a selected element to the [initial value](/en-US/docs/Web/CSS/CSS_cascade/Value_processing#initial_value) of that property. - {{cssxref("revert")}} - : Resets the property value applied to a selected element to the browser's default styling rather than the defaults applied to that property. This value acts like {{cssxref("unset")}} in many cases. - {{cssxref("revert-layer")}} @@ -435,7 +434,7 @@ If using the ID is the only way to target the element — perhaps because you do ### Inline styles -Inline styles, that is, the style declaration inside a [`style`](/en-US/docs/Web/HTML/Global_attributes/style) attribute, take precedence over all normal styles, no matter the specificity. Such declarations don't have selectors, but their specificity can be construed as 1-0-0-0; always more than any other specificity weight no matter how many IDs are in the selectors. +Inline styles, that is, the style declaration inside a [`style`](/en-US/docs/Web/HTML/Reference/Global_attributes/style) attribute, take precedence over all normal styles, no matter the specificity. Such declarations don't have selectors, but their specificity can be construed as 1-0-0-0; always more than any other specificity weight no matter how many IDs are in the selectors. ### !important @@ -475,7 +474,7 @@ Let's walk through this to see what's happening — try removing some of the pro 1. You'll see that the third rule's {{cssxref("color")}} and {{cssxref("padding")}} values have been applied, but the {{cssxref("background-color")}} hasn't. Why? Really, all three should surely apply because rules later in the source order generally override earlier rules. 2. However, the rules above it win because class selectors have higher specificity than element selectors. -3. Both elements have a [`class`](/en-US/docs/Web/HTML/Global_attributes/class) of `better`, but the 2nd one has an [`id`](/en-US/docs/Web/HTML/Global_attributes/id) of `winning` too. Since IDs have an _even higher_ specificity than classes (you can only have one element with each unique ID on a page, but many elements with the same class — ID selectors are _very specific_ in what they target), the red background color and the 1px black border should both be applied to the 2nd element, with the first element getting the gray background color, and no border, as specified by the class. +3. Both elements have a [`class`](/en-US/docs/Web/HTML/Reference/Global_attributes/class) of `better`, but the 2nd one has an [`id`](/en-US/docs/Web/HTML/Reference/Global_attributes/id) of `winning` too. Since IDs have an _even higher_ specificity than classes (you can only have one element with each unique ID on a page, but many elements with the same class — ID selectors are _very specific_ in what they target), the red background color and the 1px black border should both be applied to the 2nd element, with the first element getting the gray background color, and no border, as specified by the class. 4. The 2nd element _does_ get the red background color, but no border. Why? Because of the `!important` flag in the second rule. Adding the `!important` flag after `border: none` means that this declaration will win over the `border` value in the previous rule, even though the ID selector has higher specificity. > [!NOTE] @@ -505,7 +504,7 @@ Conflicting declarations will be applied in the following order, with later ones ## Test your skills! -You've reached the end of this article, but can you remember the most important information? You can find some further tests to verify that you've retained this information before you move on — see [Test your skills: The Cascade](/en-US/docs/Learn_web_development/Core/Styling_basics/Cascade_tasks). +You've reached the end of this article, but can you remember the most important information? You can find some further tests to verify that you've retained this information before you move on — see [Test your skills: The Cascade](/en-US/docs/Learn_web_development/Core/Styling_basics/Test_your_skills/Cascade). ## Summary diff --git a/files/en-us/learn_web_development/core/styling_basics/handling_different_text_directions/index.md b/files/en-us/learn_web_development/core/styling_basics/handling_different_text_directions/index.md index fd5f0c7251c5476..cad40930e3eb440 100644 --- a/files/en-us/learn_web_development/core/styling_basics/handling_different_text_directions/index.md +++ b/files/en-us/learn_web_development/core/styling_basics/handling_different_text_directions/index.md @@ -1,12 +1,12 @@ --- title: Handling different text directions +short-title: Multiple text directions slug: Learn_web_development/Core/Styling_basics/Handling_different_text_directions page-type: learn-module-chapter +sidebar: learnsidebar --- -{{LearnSidebar}} - -Many of the properties and values that we have encountered so far in our CSS learning have been tied to the physical dimensions of our screen. We create borders on the top, right, bottom, and left of a box, for example. These physical dimensions map very neatly to content that is viewed horizontally, and by default the web tends to support left-to-right languages (e.g. English or French) better than right-to-left languages (such as Arabic). +Many of the properties and values that we have encountered so far in our CSS learning have been tied to the physical dimensions of our screen. We create borders on the top, right, bottom, and left of a box, for example. These physical dimensions map very neatly to content that is viewed horizontally, and by default the web tends to support left-to-right languages (e.g., English or French) better than right-to-left languages (such as Arabic). In recent years however, CSS has evolved in order to better support different directionality of content, including right-to-left but also top-to-bottom content (such as Japanese) — these different directionalities are called **writing modes**. As you progress in your study and begin to work with layout, an understanding of writing modes will be very helpful to you, therefore we will introduce them now. @@ -342,7 +342,7 @@ The logical properties and values are newer than their physical equivalents, and ## Test your skills! -You've reached the end of this article, but can you remember the most important information? You can find some further tests to verify that you've retained this information before you move on — see [Test your skills: Writing modes and logical properties](/en-US/docs/Learn_web_development/Core/Styling_basics/Writing_Modes_Tasks). +You've reached the end of this article, but can you remember the most important information? You can find some further tests to verify that you've retained this information before you move on — see [Test your skills: Writing modes and logical properties](/en-US/docs/Learn_web_development/Core/Styling_basics/Test_your_skills/Writing_modes). ## Summary diff --git a/files/en-us/learn_web_development/core/styling_basics/images_media_forms/index.md b/files/en-us/learn_web_development/core/styling_basics/images_media_forms/index.md index 451edcce056702d..1925dee32800876 100644 --- a/files/en-us/learn_web_development/core/styling_basics/images_media_forms/index.md +++ b/files/en-us/learn_web_development/core/styling_basics/images_media_forms/index.md @@ -1,11 +1,11 @@ --- title: Images, media, and form elements +short-title: Images, media, forms slug: Learn_web_development/Core/Styling_basics/Images_media_forms page-type: learn-module-chapter +sidebar: learnsidebar --- -{{LearnSidebar}} - {{PreviousMenuNext("Learn_web_development/Core/Styling_basics/Overflow", "Learn_web_development/Core/Styling_basics/Tables", "Learn_web_development/Core/Styling_basics")}} In this lesson we will take a look at how certain special elements are treated in CSS. Images, other media, and form elements behave a little differently from regular boxes in terms of your ability to style them with CSS. Understanding what is and isn't possible can save some frustration, and this lesson will highlight some of the main things that you need to know. @@ -40,7 +40,7 @@ In this lesson we will take a look at how certain special elements are treated i ## Replaced elements -Images and video are described as **[replaced elements](/en-US/docs/Web/CSS/Replaced_element)**. This means that CSS cannot affect the internal layout of these elements — only their position on the page amongst other elements. As we will see however, there are various things that CSS can do with an image. +Images and video are described as **{{ glossary("replaced elements")}}**. This means that CSS cannot affect the internal layout of these elements — only their position on the page amongst other elements. As we will see however, there are various things that CSS can do with an image. Certain replaced elements, such as images and video, are also described as having an **{{glossary("aspect ratio")}}**. This means that it has a size in both the horizontal (x) and vertical (y) dimensions, and will be displayed using the intrinsic dimensions of the file by default. @@ -91,7 +91,7 @@ img { So what can we do about the overflowing issue? -As we learned in [Sizing items in CSS](/en-US/docs/Learn_web_development/Core/Styling_basics/Sizing), a common technique is to make the {{cssxref("max-width")}} of an image 100%. This will enable the image to become smaller in size than the box but not larger. This technique will also work with other replaced elements such as [`<video>`](/en-US/docs/Web/HTML/Element/video)s, or [`<iframe>`](/en-US/docs/Web/HTML/Element/iframe)s. +As we learned in [Sizing items in CSS](/en-US/docs/Learn_web_development/Core/Styling_basics/Sizing), a common technique is to make the {{cssxref("max-width")}} of an image 100%. This will enable the image to become smaller in size than the box but not larger. This technique will also work with other replaced elements such as [`<video>`](/en-US/docs/Web/HTML/Reference/Elements/video)s, or [`<iframe>`](/en-US/docs/Web/HTML/Reference/Elements/iframe)s. Try adding `max-width: 100%` to the `<img>` element rule in the example above. You will see that the smaller image remains unchanged, but the larger one becomes smaller to fit into the box. @@ -191,7 +191,7 @@ You won't study layout until a later module. For now, just keep in mind that rep Form elements can be a tricky issue when it comes to styling with CSS. The [Web Forms extensions module](/en-US/docs/Learn_web_development/Extensions/Forms) covers the trickier aspects of styling certain form input types, which we will not go into here. There are, however, a few key basics worth highlighting in this section. -Many form controls are added to your page by way of the [`<input>`](/en-US/docs/Web/HTML/Element/input) element — this defines simple form fields such as text inputs, through to more complex fields such as color and date pickers. There are some additional elements, such as [`<textarea>`](/en-US/docs/Web/HTML/Element/textarea) for multiline text input, and also elements used to contain and label parts of forms such as [`<fieldset>`](/en-US/docs/Web/HTML/Element/fieldset) and [`<legend>`](/en-US/docs/Web/HTML/Element/legend). +Many form controls are added to your page by way of the [`<input>`](/en-US/docs/Web/HTML/Reference/Elements/input) element — this defines simple form fields such as text inputs, through to more complex fields such as color and date pickers. There are some additional elements, such as [`<textarea>`](/en-US/docs/Web/HTML/Reference/Elements/textarea) for multiline text input, and also elements used to contain and label parts of forms such as [`<fieldset>`](/en-US/docs/Web/HTML/Reference/Elements/fieldset) and [`<legend>`](/en-US/docs/Web/HTML/Reference/Elements/legend). HTML also contains attributes that enable web developers to indicate which fields are required, and even the type of content that needs to be entered. If the user enters something unexpected, or leaves a required field blank, the browser can show an error message. Different browsers vary with one another in how much styling and customization they allow for such items. @@ -329,7 +329,7 @@ textarea { ## Test your skills! -You've reached the end of this article, but can you remember the most important information? You can find some further tests to verify that you've retained this information before you move on — see [Test your skills: Images and form elements](/en-US/docs/Learn_web_development/Core/Styling_basics/Images_tasks). +You've reached the end of this article, but can you remember the most important information? You can find some further tests to verify that you've retained this information before you move on — see [Test your skills: Images and form elements](/en-US/docs/Learn_web_development/Core/Styling_basics/Test_your_skills/Images). ## Summary diff --git a/files/en-us/learn_web_development/core/styling_basics/images_tasks/index.md b/files/en-us/learn_web_development/core/styling_basics/images_tasks/index.md deleted file mode 100644 index 0b95161d8692e05..000000000000000 --- a/files/en-us/learn_web_development/core/styling_basics/images_tasks/index.md +++ /dev/null @@ -1,131 +0,0 @@ ---- -title: "Test your skills: Images and form elements" -slug: Learn_web_development/Core/Styling_basics/Images_tasks -page-type: learn-module-assessment ---- - -{{LearnSidebar}} - -The aim of this skill test is to assess whether you understand how special elements like [images, media and form elements are treated in CSS](/en-US/docs/Learn_web_development/Core/Styling_basics/Images_media_forms). - -> [!NOTE] -> Click **"Play"** in the code blocks below to edit the examples in the MDN Playground. -> You can also copy the code (click the clipboard icon) and paste it into an online editor such as [CodePen](https://codepen.io/), [JSFiddle](https://jsfiddle.net/), or [Glitch](https://glitch.com/). -> If you get stuck, you can reach out to us in one of our [communication channels](/en-US/docs/MDN/Community/Communication_channels). - -## Task 1 - -In this task, you have an image that is overflowing the box. We want the image to scale down to fit inside the box without any extra white space, but we do not mind if some part of the image is cropped. - -Your final result should look like the image below: - -![An image in a box](mdn-images-object-fit.png) - -Try to update the code below to recreate the finished example so that the image doesn't overflow the box: - -```html live-sample___object-fit -<div class="box"> - <img - alt="Hot air balloons flying in clear sky, and a crowd of people in the foreground" - src="https://mdn.github.io/shared-assets/images/examples/balloons.jpg" /> -</div> -``` - -```css live-sample___object-fit -.box { - border: 5px solid #000; - width: 400px; - height: 200px; -} - -img { - /* Add styles here */ -} -``` - -{{EmbedLiveSample("object-fit", "", "400px")}} - -<details> -<summary>Click here to show the solution</summary> - -It is ok if some parts of the image are cropped. -Using `object-fit: cover` is the best choice, you also need to set the width and height to `100%`: - -```css -img { - height: 100%; - width: 100%; - object-fit: cover; -} -``` - -</details> - -## Task 2 - -In this task, you have a basic form. Your task is to make the following changes: - -- Use attribute selectors to target the search field and button inside `.my-form`. -- Make the form field and button use the same text size as the rest of the form. -- Give the form field and button 10px of padding. -- Give the button a background of `rebeccapurple`, white foreground, no border and rounded corners of 5px. - -Your final result should look like the image below: - -![A single line form](mdn-images-form.png) - -Try to update the code below to recreate the finished example: - -```html live-sample___form -<form action="" class="my-form" method="post"> - <div> - <label for="fldSearch">Keywords</label> - <input id="fldSearch" name="keywords" type="search" /> - <input name="btnSubmit" type="submit" value="Search" /> - </div> -</form> -``` - -```css live-sample___form -body { - font: 1.2em / 1.5 sans-serif; -} -.my-form { - border: 2px solid #000; - padding: 5px; -} -``` - -{{EmbedLiveSample("form")}} - -<details> -<summary>Click here to show the solution</summary> - -Here's an example solution for the task: - -```css -.my-form { - border: 2px solid #000; - padding: 5px; -} - -.my-form input[type="search"] { - padding: 10px; - font-size: inherit; -} - -.my-form input[type="submit"] { - padding: 10px; - font-size: inherit; - background-color: rebeccapurple; - color: white; - border: 0; - border-radius: 5px; -} -``` - -</details> - -## See also - -- [CSS styling basics](/en-US/docs/Learn_web_development/Core/Styling_basics) diff --git a/files/en-us/learn_web_development/core/styling_basics/index.md b/files/en-us/learn_web_development/core/styling_basics/index.md index eec989bdc5a10a4..07db3956021cd32 100644 --- a/files/en-us/learn_web_development/core/styling_basics/index.md +++ b/files/en-us/learn_web_development/core/styling_basics/index.md @@ -2,10 +2,9 @@ title: CSS styling basics slug: Learn_web_development/Core/Styling_basics page-type: learn-module +sidebar: learnsidebar --- -{{LearnSidebar}} - {{NextMenu("Learn_web_development/Core/Styling_basics/What_is_CSS", "Learn_web_development/Core")}} CSS (Cascading Style Sheets) is used to style and layout web pages — for example, to alter the font, color, size, and spacing of your content, split it into multiple columns, or add animations and other decorative features. This module provides all the CSS fundamentals you'll need for now, including syntax, features, and techniques. @@ -63,7 +62,7 @@ Before starting this module, you should have a basic work environment set up (as These tutorials are not part of the learning pathway, but they are interesting nonetheless — you should consider these as stretch goals, to optionally study when you are done with the main Core articles. - [Advanced styling effects](/en-US/docs/Learn_web_development/Core/Styling_basics/Advanced_styling_effects) - - : This article will give you guidance on how to go about debugging a CSS problem, and show you how the DevTools included in all modern browsers can help you to find out what is going on. + - : This article acts as a box of tricks, providing an introduction to some interesting advanced styling features such as box shadows, blend modes, and filters. - [Cascade layers](/en-US/docs/Learn_web_development/Core/Styling_basics/Cascade_layers) - : This lesson aims to introduce you to [cascade layers](/en-US/docs/Web/CSS/@layer), a more advanced feature that builds on the fundamental concepts of the [CSS cascade](/en-US/docs/Web/CSS/CSS_cascade/Cascade) and [CSS specificity](/en-US/docs/Web/CSS/CSS_cascade/Specificity). - [Handling different text directions](/en-US/docs/Learn_web_development/Core/Styling_basics/Handling_different_text_directions) @@ -73,9 +72,9 @@ These tutorials are not part of the learning pathway, but they are interesting n ## See also -- [Learn HTML and CSS](https://v2.scrimba.com/learn-html-and-css-c0p?via=mdn), Scrimba <sup>_MDN learning partner_</sup> - - : [Scrimba's](https://scrimba.com?via=mdn) _Learn HTML and CSS_ course teaches you HTML and CSS through building and deploying five awesome projects, with fun interactive lessons and challenges taught by knowledgeable teachers. -- [Write your first lines of CSS!](https://v2.scrimba.com/the-frontend-developer-career-path-c0j/~015?via=mdn), Scrimba <sup>_MDN learning partner_</sup> +- [Learn HTML and CSS](https://scrimba.com/learn-html-and-css-c0p?via=mdn), Scrimba <sup>[_MDN learning partner_](/en-US/docs/MDN/Writing_guidelines/Learning_content#partner_links_and_embeds)</sup> + - : [Scrimba's](https://scrimba.com/?via=mdn) _Learn HTML and CSS_ course teaches you HTML and CSS through building and deploying five awesome projects, with fun interactive lessons and challenges taught by knowledgeable teachers. +- [Write your first lines of CSS!](https://scrimba.com/the-frontend-developer-career-path-c0j/~015?via=mdn), Scrimba <sup>[_MDN learning partner_](/en-US/docs/MDN/Writing_guidelines/Learning_content#partner_links_and_embeds)</sup> - : This interactive lesson provides a useful introduction to CSS syntax. {{NextMenu("Learn_web_development/Core/Styling_basics/What_is_CSS", "Learn_web_development/Core")}} diff --git a/files/en-us/learn_web_development/core/styling_basics/organizing/index.md b/files/en-us/learn_web_development/core/styling_basics/organizing/index.md index d289a992227fc54..d5b299cb4cf7b9e 100644 --- a/files/en-us/learn_web_development/core/styling_basics/organizing/index.md +++ b/files/en-us/learn_web_development/core/styling_basics/organizing/index.md @@ -2,10 +2,9 @@ title: Organizing your CSS slug: Learn_web_development/Core/Styling_basics/Organizing page-type: learn-module-chapter +sidebar: learnsidebar --- -{{LearnSidebar}} - As you start to work on larger stylesheets and big projects you will discover that maintaining a huge CSS file can be challenging. In this article we will take a brief look at some best practices for writing your CSS to make it easily maintainable, and some of the solutions you will find in use by others to help improve maintainability. <table> @@ -46,7 +45,7 @@ Here are some general suggestions for ways to keep your stylesheets organized an If you are working with a team on an existing project, the first thing to check is whether the project has an existing style guide for CSS. The team style guide should always win over your own personal preferences. There often isn't a right or wrong way to do things, but consistency is important. -For example, have a look at the [CSS guidelines for MDN code examples](/en-US/docs/MDN/Writing_guidelines/Writing_style_guide/Code_style_guide/CSS). +For example, have a look at the [CSS guidelines for MDN code examples](/en-US/docs/MDN/Writing_guidelines/Code_style_guide/CSS). ### Keep it consistent diff --git a/files/en-us/learn_web_development/core/styling_basics/overflow/index.md b/files/en-us/learn_web_development/core/styling_basics/overflow/index.md index c7fc8f8f04d6db6..f853fce67965965 100644 --- a/files/en-us/learn_web_development/core/styling_basics/overflow/index.md +++ b/files/en-us/learn_web_development/core/styling_basics/overflow/index.md @@ -1,11 +1,11 @@ --- title: Overflowing content +short-title: Overflow slug: Learn_web_development/Core/Styling_basics/Overflow page-type: learn-module-chapter +sidebar: learnsidebar --- -{{LearnSidebar}} - {{PreviousMenuNext("Learn_web_development/Core/Styling_basics/Backgrounds_and_borders", "Learn_web_development/Core/Styling_basics/Images_media_forms", "Learn_web_development/Core/Styling_basics")}} Overflow is what happens when there is too much content to fit inside an element box. In this lesson, you will learn how to manage overflow using CSS. @@ -227,7 +227,7 @@ When developing a site, always keep overflow in mind. Test designs with large an ## Test your skills! -You've reached the end of this article, but can you remember the most important information? You can find some further tests to verify that you've retained this information before you move on — see [Test your skills: Overflow](/en-US/docs/Learn_web_development/Core/Styling_basics/Overflow_Tasks). +You've reached the end of this article, but can you remember the most important information? You can find some further tests to verify that you've retained this information before you move on — see [Test your skills: Overflow](/en-US/docs/Learn_web_development/Core/Styling_basics/Test_your_skills/Overflow). ## Summary diff --git a/files/en-us/learn_web_development/core/styling_basics/overflow_tasks/index.md b/files/en-us/learn_web_development/core/styling_basics/overflow_tasks/index.md deleted file mode 100644 index 9e2999a4c2ad207..000000000000000 --- a/files/en-us/learn_web_development/core/styling_basics/overflow_tasks/index.md +++ /dev/null @@ -1,113 +0,0 @@ ---- -title: "Test your skills: Overflow" -slug: Learn_web_development/Core/Styling_basics/Overflow_Tasks -page-type: learn-module-assessment ---- - -{{LearnSidebar}} - -The aim of this skill test is to assess whether you understand [overflow in CSS and how to manage it](/en-US/docs/Learn_web_development/Core/Styling_basics/Overflow). - -> [!NOTE] -> Click **"Play"** in the code blocks below to edit the examples in the MDN Playground. -> You can also copy the code (click the clipboard icon) and paste it into an online editor such as [CodePen](https://codepen.io/), [JSFiddle](https://jsfiddle.net/), or [Glitch](https://glitch.com/). -> If you get stuck, you can reach out to us in one of our [communication channels](/en-US/docs/MDN/Community/Communication_channels). - -## Task 1 - -In this task, the content is overflowing the box because it has a fixed height. Keep the height but cause the box to have scrollbars only if there is enough text to cause an overflow. Test by removing some of the text from the HTML, that if there is only a small amount of text that does not overflow, no scrollbar appears. - -![A small box with a border and a vertical scrollbar.](mdn-overflow1.png) - -Try to update the code below to recreate the finished example: - -```html live-sample___overflow-scroll -<div class="box"> - <p> - Veggies es bonus vobis, proinde vos postulo essum magis kohlrabi welsh onion - daikon amaranth tatsoi tomatillo melon azuki bean garlic. - </p> - - <p> - Gumbo beet greens corn soko endive gumbo gourd. Parsley shallot courgette - tatsoi pea sprouts fava bean collard greens dandelion okra wakame tomato. - Dandelion cucumber earthnut pea peanut soko zucchini. - </p> -</div> -``` - -```css live-sample___overflow-scroll -body { - font: 1.2em / 1.5 sans-serif; -} - -.box { - border: 5px solid black; - padding: 1em; - height: 200px; - width: 300px; -} -``` - -{{EmbedLiveSample("overflow-scroll", "", "450px")}} - -<details> -<summary>Click here to show the solution</summary> - -You should add `overflow: auto` so that the box will only gain scrollbars when the content is too large: - -```css -.box { - overflow: auto; -} -``` - -</details> - -## Task 2 - -In this task, there is an image in the box that is bigger than the dimensions of the box so that it overflows visibly. Change it so that any image outside of the box is hidden. - -Your final result should look like the image below: - -![A box with an image which fills the box but does not spill out the edges.](mdn-overflow2.png) - -Try to update the code below to recreate the finished example: - -```html live-sample___overflow-hidden -<div class="box"> - <img - alt="flowers" - src="https://mdn.github.io/shared-assets/images/examples/flowers.jpg" /> -</div> -``` - -```css live-sample___overflow-hidden -body { - font: 1.2em / 1.5 sans-serif; -} -.box { - border: 5px solid black; - height: 200px; - width: 300px; -} -``` - -{{EmbedLiveSample("overflow-hidden", "", "300px")}} - -<details> -<summary>Click here to show the solution</summary> - -You should add `overflow: hidden` to the `.box` selector: - -```css -.box { - overflow: hidden; -} -``` - -</details> - -## See also - -- [CSS styling basics](/en-US/docs/Learn_web_development/Core/Styling_basics) diff --git a/files/en-us/learn_web_development/core/styling_basics/pseudo_classes_and_elements/index.md b/files/en-us/learn_web_development/core/styling_basics/pseudo_classes_and_elements/index.md index f000837f0a8b600..4d1060d074dcbe7 100644 --- a/files/en-us/learn_web_development/core/styling_basics/pseudo_classes_and_elements/index.md +++ b/files/en-us/learn_web_development/core/styling_basics/pseudo_classes_and_elements/index.md @@ -1,11 +1,11 @@ --- title: Pseudo-classes and pseudo-elements +short-title: Pseudo-classes and elements slug: Learn_web_development/Core/Styling_basics/Pseudo_classes_and_elements page-type: learn-module-chapter +sidebar: learnsidebar --- -{{LearnSidebar}} - {{PreviousMenuNext("Learn_web_development/Core/Styling_basics/Attribute_selectors", "Learn_web_development/Core/Styling_basics/Combinators", "Learn_web_development/Core/Styling_basics")}} The next set of selectors we will look at are referred to as **pseudo-classes** and **pseudo-elements**. There are a large number of these, and they often serve quite specific purposes. Once you know how to use them, you can look through the different types to see if there is something which works for the task you are trying to achieve. @@ -18,7 +18,7 @@ The next set of selectors we will look at are referred to as **pseudo-classes** HTML basics (study <a href="/en-US/docs/Learn_web_development/Core/Structuring_content/Basic_HTML_syntax" >Basic HTML syntax</a - >), <a href="/en-US/docs/Learn_web_development/Core/Styling_basics/Basic_selectors">Basic CSS selectors<a>. + >), <a href="/en-US/docs/Learn_web_development/Core/Styling_basics/Basic_selectors">Basic CSS selectors</a>. </td> </tr> <tr> @@ -37,7 +37,7 @@ The next set of selectors we will look at are referred to as **pseudo-classes** ## What is a pseudo-class? -A pseudo-class is a selector that selects elements that are in a specific state, e.g. they are the first element of their type, or they are being hovered over by the mouse pointer. They tend to act as if you had applied a class to some part of your document, often helping you cut down on excess classes in your markup, and giving you more flexible, maintainable code. +A pseudo-class is a selector that selects elements that are in a specific state, e.g., they are the first element of their type, or they are being hovered over by the mouse pointer. They tend to act as if you had applied a class to some part of your document, often helping you cut down on excess classes in your markup, and giving you more flexible, maintainable code. Pseudo-classes are keywords that start with a colon. For example, `:hover` is a pseudo-class. diff --git a/files/en-us/learn_web_development/core/styling_basics/sizing/index.md b/files/en-us/learn_web_development/core/styling_basics/sizing/index.md index 910fc9ed06af317..83ef3f4eb633115 100644 --- a/files/en-us/learn_web_development/core/styling_basics/sizing/index.md +++ b/files/en-us/learn_web_development/core/styling_basics/sizing/index.md @@ -1,11 +1,11 @@ --- title: Sizing items in CSS +short-title: Sizing slug: Learn_web_development/Core/Styling_basics/Sizing page-type: learn-module-chapter +sidebar: learnsidebar --- -{{LearnSidebar}} - {{PreviousMenuNext("Learn_web_development/Core/Styling_basics/Values_and_units", "Learn_web_development/Core/Styling_basics/Backgrounds_and_borders", "Learn_web_development/Core/Styling_basics")}} In the various lessons so far, you have come across a number of ways to size items on a web page using CSS. Understanding how big the different features in your design will be is important. So, in this lesson we will summarize the various ways elements get a size via CSS and define a few terms about sizing that will help you in the future. @@ -295,7 +295,7 @@ Sizing things according to the viewport can be useful in your designs. For examp ## Test your skills! -You've reached the end of this article, but can you remember the most important information? You can find some further tests to verify that you've retained this information before you move on — see [Test your skills: Sizing](/en-US/docs/Learn_web_development/Core/Styling_basics/Sizing_tasks). +You've reached the end of this article, but can you remember the most important information? You can find some further tests to verify that you've retained this information before you move on — see [Test your skills: Sizing](/en-US/docs/Learn_web_development/Core/Styling_basics/Test_your_skills/Sizing). ## Summary diff --git a/files/en-us/learn_web_development/core/styling_basics/sizing_tasks/index.md b/files/en-us/learn_web_development/core/styling_basics/sizing_tasks/index.md deleted file mode 100644 index 0dc372b451ada20..000000000000000 --- a/files/en-us/learn_web_development/core/styling_basics/sizing_tasks/index.md +++ /dev/null @@ -1,208 +0,0 @@ ---- -title: "Test your skills: Sizing" -slug: Learn_web_development/Core/Styling_basics/Sizing_tasks -page-type: learn-module-assessment ---- - -{{LearnSidebar}} - -The aim of this skill test is to assess whether you understand the different ways of [sizing items in CSS](/en-US/docs/Learn_web_development/Core/Styling_basics/Sizing). - -> [!NOTE] -> Click **"Play"** in the code blocks below to edit the examples in the MDN Playground. -> You can also copy the code (click the clipboard icon) and paste it into an online editor such as [CodePen](https://codepen.io/), [JSFiddle](https://jsfiddle.net/), or [Glitch](https://glitch.com/). -> If you get stuck, you can reach out to us in one of our [communication channels](/en-US/docs/MDN/Community/Communication_channels). - -## Task 1 - -In this task, you have two boxes. The first should be sized so that the height will be at least 100 pixels tall, even if there is less content that would cause it to grow to that height. However, the content should not overflow if there is more content than fits in 100 pixels. Test this box by removing the content from the HTML to make sure you still get a 100 pixel tall box even with no content. - -The second box should be fixed at 100 pixels tall, so that content will overflow if there is too much. - -![Two boxes one with overflowing content](mdn-sizing-height-min-height.png) - -Try to update the code below to recreate the finished example: - -```html live-sample___height-min-height -<div class="box box1"> - <p> - Veggies es bonus vobis, proinde vos postulo essum magis kohlrabi welsh onion - daikon amaranth tatsoi tomatillo melon azuki bean garlic. Gumbo beet greens - corn soko endive gumbo gourd. - </p> -</div> - -<div class="box box2"> - <p> - Veggies es bonus vobis, proinde vos postulo essum magis kohlrabi welsh onion - daikon amaranth tatsoi tomatillo melon azuki bean garlic. Gumbo beet greens - corn soko endive gumbo gourd. - </p> -</div> -``` - -```css hidden live-sample___height-min-height -body { - font: 1.2em / 1.5 sans-serif; - padding: 1em; -} - -.box { - border: 5px solid #000; - width: 400px; - margin-bottom: 1em; -} -``` - -```css live-sample___height-min-height -.box1 { - /* Add styles here */ -} - -.box2 { - /* Add styles here */ -} -``` - -{{EmbedLiveSample("height-min-height", "", "500px")}} - -<details> -<summary>Click here to show the solution</summary> - -There are two boxes, the first should be given a minimum height, in which case it will expand to take the additional content but if you remove some content, the box will be at least as tall as the `min-height`. The second is given a fixed height which will cause content to overflow. - -```css -.box1 { - min-height: 100px; -} - -.box2 { - height: 100px; -} -``` - -</details> - -## Task 2 - -In this task, you have a box, which contains another box. Your task is to make the inner box 60% of the width of the outer box. The value of the {{cssxref("box-sizing")}} property is set to `border-box`, which means that the total width includes any padding and border. You should also give the inner box padding of 10% using the width (or inline size) as the size from which that percentage is calculated. - -Your final result should look like the image below: - -![A box with another box nested inside](mdn-sizing-percentages.png) - -Try to update the code below to recreate the finished example: - -```html live-sample___percentages -<div class="box"> - <div class="inner">Make me 60% of my parent's width.</div> -</div> -``` - -```css hidden live-sample___percentages -body { - font: 1.2em / 1.5 sans-serif; - padding: 1em; -} -.box { - border: 5px solid #000; - width: 400px; - margin-bottom: 1em; -} - -.inner { - background-color: rebeccapurple; - color: white; - border-radius: 5px; -} -``` - -```css live-sample___percentages -* { - box-sizing: border-box; -} -.inner { - /* Add styles here */ -} -``` - -{{EmbedLiveSample("percentages", "", "250px")}} - -<details> -<summary>Click here to show the solution</summary> - -Make the box 60% of the container and give it 10% of padding on all sides. -All elements already have `box-sizing: border-box` to save you from worrying about which width you are using: - -```css -* { - box-sizing: border-box; -} -.inner { - width: 60%; - padding: 10%; -} -``` - -</details> - -## Task 3 - -In this task, you have two images in boxes. One image is smaller than the box, the other is larger and breaking out of the box. If you imagine that the box is responsive and therefore could grow and shrink, which property would you apply to the image so that the large image shrinks down into the box but the small image does not stretch. - -Your final result should look like the images below: - -![Two boxes with images in](mdn-sizing-max-width.png) - -Try to update the code below to recreate the finished example: - -```html live-sample___max-width -<div class="box"> - <img - alt="A pink star" - src="https://mdn.github.io/shared-assets/images/examples/star-pink_256x256.png" /> -</div> - -<div class="box"> - <img - alt="Hot air balloons flying in clear sky, and a crowd of people in the foreground" - src="https://mdn.github.io/shared-assets/images/examples/balloons.jpg" /> -</div> -``` - -```css hidden live-sample___max-width -body { - font: 1.2em / 1.5 sans-serif; - padding: 1em; -} -.box { - border: 5px solid #000; - margin-bottom: 1em; - width: 500px; -} -``` - -```css live-sample___max-width -img { - /* Add styles here */ -} -``` - -{{EmbedLiveSample("max-width", "", "700px")}} - -<details> -<summary>Click here to show the solution</summary> - -The example has an image which is breaking out of the box and one which is smaller than the box, you need to use `max-width` set to 100% to cause the larger image to grow only as large as the box. If you use `width: 100%`, the small image will stretch. - -```css -img { - max-width: 100%; -} -``` - -</details> - -## See also - -- [CSS styling basics](/en-US/docs/Learn_web_development/Core/Styling_basics) diff --git a/files/en-us/learn_web_development/core/styling_basics/styling_a_bio_page/index.md b/files/en-us/learn_web_development/core/styling_basics/styling_a_bio_page/index.md index 652314d29afed12..f33b76a98ca0cc3 100644 --- a/files/en-us/learn_web_development/core/styling_basics/styling_a_bio_page/index.md +++ b/files/en-us/learn_web_development/core/styling_basics/styling_a_bio_page/index.md @@ -1,11 +1,11 @@ --- title: "Challenge: Styling a biography page" +short-title: "Challenge: Biography page" slug: Learn_web_development/Core/Styling_basics/Styling_a_bio_page page-type: learn-module-assessment +sidebar: learnsidebar --- -{{LearnSidebar}} - {{PreviousMenuNext("Learn_web_development/Core/Styling_basics/Getting_started", "Learn_web_development/Core/Styling_basics/Basic_selectors", "Learn_web_development/Core/Styling_basics")}} In this challenge you will style a simple bio page, testing you on some of the skills you learned in the last couple of lessons including writing selectors and text styling. diff --git a/files/en-us/learn_web_development/core/styling_basics/tables/index.md b/files/en-us/learn_web_development/core/styling_basics/tables/index.md index b497a98ada8e932..ea42e29929c876c 100644 --- a/files/en-us/learn_web_development/core/styling_basics/tables/index.md +++ b/files/en-us/learn_web_development/core/styling_basics/tables/index.md @@ -2,10 +2,9 @@ title: Styling tables slug: Learn_web_development/Core/Styling_basics/Tables page-type: learn-module-chapter +sidebar: learnsidebar --- -{{LearnSidebar}} - {{PreviousMenuNext("Learn_web_development/Core/Styling_basics/Images_media_forms", "Learn_web_development/Core/Styling_basics/Debugging_CSS", "Learn_web_development/Core/Styling_basics")}} Styling an HTML table isn't the most glamorous job in the world, but sometimes we all have to do it. This article explains how to make HTML tables look good, with some specific table styling techniques highlighted. @@ -84,7 +83,7 @@ Let's start by looking at a typical HTML table. Well, I say typical — most HTM </table> ``` -The table is nicely marked up, easily stylable, and accessible, thanks to features such as [`scope`](/en-US/docs/Web/HTML/Element/th#scope), {{htmlelement("caption")}}, {{htmlelement("thead")}}, {{htmlelement("tbody")}}, etc. Unfortunately, it doesn't look good when rendered on the screen (see it live at [punk-bands-unstyled.html](https://mdn.github.io/learning-area/css/styling-boxes/styling-tables/punk-bands-unstyled.html)): +The table is nicely marked up, easily stylable, and accessible, thanks to features such as [`scope`](/en-US/docs/Web/HTML/Reference/Elements/th#scope), {{htmlelement("caption")}}, {{htmlelement("thead")}}, {{htmlelement("tbody")}}, etc. Unfortunately, it doesn't look good when rendered on the screen (see it live at [punk-bands-unstyled.html](https://mdn.github.io/learning-area/css/styling-boxes/styling-tables/punk-bands-unstyled.html)): ![an unstyled table showing a summary of Uk's famous punk bands](table-unstyled.png) @@ -299,7 +298,7 @@ There is nothing remarkable here, except for the {{cssxref("caption-side")}} pro Before moving on, we thought we'd provide you with a quick list of the most useful points illustrated above: -- Make your table markup as simple as possible, and keep things flexible, e.g. by using percentages, so the design is more responsive. +- Make your table markup as simple as possible, and keep things flexible, e.g., by using percentages, so the design is more responsive. - Use {{cssxref("table-layout", "table-layout: fixed")}} to create a more predictable table layout that allows you to easily set column widths by setting {{cssxref("width")}} on their headings ({{htmlelement("th")}}). - Use {{cssxref("border-collapse", "border-collapse: collapse")}} to make table elements borders collapse into each other, producing a neater and easier to control look. - Use {{htmlelement("thead")}}, {{htmlelement("tbody")}}, and {{htmlelement("tfoot")}} to break up your table into logical chunks and provide extra places to apply CSS to, so it is easier to layer styles on top of one another if required. @@ -308,7 +307,7 @@ Before moving on, we thought we'd provide you with a quick list of the most usef ## Test your skills! -You've reached the end of this article, but can you remember the most important information? You can find some further tests to verify that you've retained this information before you move on — see [Test your skills: Tables](/en-US/docs/Learn_web_development/Core/Styling_basics/Tables_tasks). +You've reached the end of this article, but can you remember the most important information? You can find some further tests to verify that you've retained this information before you move on — see [Test your skills: Tables](/en-US/docs/Learn_web_development/Core/Styling_basics/Test_your_skills/Tables). ## Summary diff --git a/files/en-us/learn_web_development/core/styling_basics/tables_tasks/index.md b/files/en-us/learn_web_development/core/styling_basics/tables_tasks/index.md deleted file mode 100644 index 455387b80f4c37d..000000000000000 --- a/files/en-us/learn_web_development/core/styling_basics/tables_tasks/index.md +++ /dev/null @@ -1,183 +0,0 @@ ---- -title: "Test your skills: Tables" -slug: Learn_web_development/Core/Styling_basics/Tables_tasks -page-type: learn-module-assessment ---- - -{{LearnSidebar}} - -The aim of this skill test is to assess whether you understand how to [style HTML tables in CSS](/en-US/docs/Learn_web_development/Core/Styling_basics/Tables). - -> [!NOTE] -> Click **"Play"** in the code blocks below to edit the examples in the MDN Playground. -> You can also copy the code (click the clipboard icon) and paste it into an online editor such as [CodePen](https://codepen.io/), [JSFiddle](https://jsfiddle.net/), or [Glitch](https://glitch.com/). -> If you get stuck, you can reach out to us in one of our [communication channels](/en-US/docs/MDN/Community/Communication_channels). - -## Task - -In the lesson on [styling tables](/en-US/docs/Learn_web_development/Core/Styling_basics/Tables), we styled up a table in a rather garish manner. In this task, we are going to style the same table, but using some good practices for table design as outlined in the external article [Web Typography: designing tables to be read not looked at](https://alistapart.com/article/web-typography-tables/). - -Our finished table will look like the image below. There are a number of ways that you can achieve this, but we suggest you follow similar patterns as used in the tutorial to do the following things: - -- Add padding of `0.3em` to the table headings and data and align them at the top of their cells. -- Align headings and data for columns containing numbers right. -- Align headings and data for columns containing text left. -- Align the heading of the table footer right. -- Align the data of the table footer left. -- Add a 1px top and bottom solid border with the hex color `#999` to the table. -- Add a 1px top solid border with the hex color `#999` to the footer. -- Remove the default spacing between the table elements borders to get the expected result. -- Stripe every odd row of the main table with the hex color `#eee`. - -![A table with striped rows.](mdn-table-bands.png) - -**Bonus question:** What can you do to make the table layout behave a bit more predictably? Think of how table columns are sized by default and how we can change this behavior to size the columns according to the width of their headings. - -Try to update the code below to recreate the finished example: - -```html live-sample___table -<table> - <caption> - A summary of the UK's most famous punk bands - </caption> - <thead> - <tr> - <th scope="col">Band</th> - <th scope="col">Year formed</th> - <th scope="col">No. of Albums</th> - <th scope="col">Most famous song</th> - </tr> - </thead> - <tbody> - <tr> - <th scope="row">Buzzcocks</th> - <td>1976</td> - <td>9</td> - <td>Ever fallen in love (with someone you shouldn't've)</td> - </tr> - <tr> - <th scope="row">The Clash</th> - <td>1976</td> - <td>6</td> - <td>London Calling</td> - </tr> - <tr> - <th scope="row">The Damned</th> - <td>1976</td> - <td>10</td> - <td>Smash it up</td> - </tr> - <tr> - <th scope="row">Sex Pistols</th> - <td>1975</td> - <td>1</td> - <td>Anarchy in the UK</td> - </tr> - <tr> - <th scope="row">Sham 69</th> - <td>1976</td> - <td>13</td> - <td>If the kids are united</td> - </tr> - <tr> - <th scope="row">Siouxsie and the Banshees</th> - <td>1976</td> - <td>11</td> - <td>Hong Kong Garden</td> - </tr> - <tr> - <th scope="row">Stiff Little Fingers</th> - <td>1977</td> - <td>10</td> - <td>Suspect Device</td> - </tr> - <tr> - <th scope="row">The Stranglers</th> - <td>1974</td> - <td>17</td> - <td>No More Heroes</td> - </tr> - </tbody> - <tfoot> - <tr> - <th colspan="2" scope="row">Total albums</th> - <td colspan="2">77</td> - </tr> - </tfoot> -</table> -``` - -```css hidden live-sample___table -body { - padding: 1em; - font: 1.2em / 1.5 sans-serif; - font-size: 80%; -} -``` - -```css live-sample___table -/* Add styles here */ -``` - -{{EmbedLiveSample("table", "", "400px")}} - -<details> -<summary>Click here to show the solution</summary> - -The below is a sample of how the end result could be achieved, using similar techniques to the lesson. However there are a number of ways that would be perfectly correct, perhaps slightly more verbose. - -```css -table { - border-top: 1px solid #999; - border-bottom: 1px solid #999; - border-collapse: collapse; -} - -th, -td { - vertical-align: top; - padding: 0.3em; -} - -tr :nth-child(2), -tr :nth-child(3) { - text-align: right; -} - -tr :nth-child(1), -tr :nth-child(4) { - text-align: left; -} - -tbody tr:nth-child(odd) { - background-color: #eee; -} - -tfoot { - border-top: 1px solid #999; -} - -tfoot tr :nth-child(1) { - text-align: right; -} - -tfoot tr :nth-child(2) { - text-align: left; -} -``` - -For the bonus question, you can make the table layout more predictable by adding {{cssxref("table-layout")}} with a value of [`fixed`](/en-US/docs/Web/CSS/table-layout#fixed) and an explicit `width`: - -```css -table { - table-layout: fixed; - width: 100%; -} -``` - -</details> - -## See also - -- [CSS styling basics](/en-US/docs/Learn_web_development/Core/Styling_basics) -- [Web Typography: Designing Tables to be Read, Not Looked At](https://alistapart.com/article/web-typography-tables) on alistapart.com (2017) diff --git a/files/en-us/learn_web_development/core/styling_basics/test_your_skills_backgrounds_and_borders/backgrounds-task1.png b/files/en-us/learn_web_development/core/styling_basics/test_your_skills/backgrounds_and_borders/backgrounds-task1.png similarity index 100% rename from files/en-us/learn_web_development/core/styling_basics/test_your_skills_backgrounds_and_borders/backgrounds-task1.png rename to files/en-us/learn_web_development/core/styling_basics/test_your_skills/backgrounds_and_borders/backgrounds-task1.png diff --git a/files/en-us/learn_web_development/core/styling_basics/test_your_skills_backgrounds_and_borders/backgrounds-task2.png b/files/en-us/learn_web_development/core/styling_basics/test_your_skills/backgrounds_and_borders/backgrounds-task2.png similarity index 100% rename from files/en-us/learn_web_development/core/styling_basics/test_your_skills_backgrounds_and_borders/backgrounds-task2.png rename to files/en-us/learn_web_development/core/styling_basics/test_your_skills/backgrounds_and_borders/backgrounds-task2.png diff --git a/files/en-us/learn_web_development/core/styling_basics/test_your_skills/backgrounds_and_borders/index.md b/files/en-us/learn_web_development/core/styling_basics/test_your_skills/backgrounds_and_borders/index.md new file mode 100644 index 000000000000000..69da3c2c72dcb2b --- /dev/null +++ b/files/en-us/learn_web_development/core/styling_basics/test_your_skills/backgrounds_and_borders/index.md @@ -0,0 +1,167 @@ +--- +title: "Test your skills: Backgrounds and borders" +short-title: Backgrounds and borders +slug: Learn_web_development/Core/Styling_basics/Test_your_skills/Backgrounds_and_borders +page-type: learn-module-assessment +sidebar: learnsidebar +--- + +The aim of this skill test is to assess whether you understand [backgrounds and borders of boxes in CSS](/en-US/docs/Learn_web_development/Core/Styling_basics/Backgrounds_and_borders). + +> [!NOTE] +> Click **"Play"** in the code blocks below to edit the examples in the MDN Playground. +> You can also copy the code (click the clipboard icon) and paste it into an online editor such as [CodePen](https://codepen.io/), [JSFiddle](https://jsfiddle.net/), or [Glitch](https://glitch.com/). +> If you get stuck, you can reach out to us in one of our [communication channels](/en-US/docs/MDN/Community/Communication_channels). + +## Task 1 + +In this task, we want you to add a background, border, and some basic styles to a page header: + +1. Give the box a 5px black solid border, with rounded corners of 10px. +2. Give the `<h2>` a semi-transparent black background color, and make the text white. +3. Add a background image and size it so that it covers the box. You can use the following image: + + ```plain + https://mdn.github.io/shared-assets/images/examples/balloons.jpg + ``` + +Your final result should look like the image below: + +![Images shows a box with a photograph background, rounded border and white text on a semi-transparent black background.](backgrounds-task1.png) + +Try to update the code below to recreate the finished example: + +```html live-sample___backgrounds1 +<div class="box"> + <h2>Backgrounds & Borders</h2> +</div> +``` + +```css hidden live-sample___backgrounds1 +body { + padding: 1em; + font: 1.2em / 1.5 sans-serif; +} +* { + box-sizing: border-box; +} +.box { + padding: 0.5em; +} +``` + +```css live-sample___backgrounds1 +.box { + /* Add styles here */ +} + +h2 { + /* Add styles here */ +} +``` + +{{EmbedLiveSample("backgrounds1", "", "200px")}} + +<details> +<summary>Click here to show the solution</summary> + +You should use `border`, `border-radius`, `background-image`, and `background-size` and understand how to use RGB colors to make a background color partly transparent: + +```css +.box { + border: 5px solid #000; + border-radius: 10px; + background-image: url(https://mdn.github.io/shared-assets/images/examples/balloons.jpg); + background-size: cover; +} + +h2 { + background-color: rgb(0 0 0 / 50%); + color: #fff; +} +``` + +</details> + +## Task 2 + +In this task, we want you to add background images, a border, and some other styling to a decorative box: + +1. Give the box a 5px lightblue border and round the top left corner 20px and the bottom right corner 40px. + +2. The heading uses the `star.png` image as a background image, with a single centered star on the left and a repeating pattern of stars on the right. + You can use the following image: + + ```plain + https://mdn.github.io/shared-assets/images/examples/star.png + ``` + +3. Make sure that the heading text does not overlay the image, and that it is centered — you will need to use techniques learned in previous lessons to achieve this. + +Your final result should look like the image below: + +![Images shows a box with a blue border rounded at the top left and bottom right corners. On the left of the text is a single star, on the right 3 stars.](backgrounds-task2.png) + +Try to update the code below to recreate the finished example: + +```html live-sample___backgrounds2 +<div class="box"> + <h2>Backgrounds & Borders</h2> +</div> +``` + +```css hidden live-sample___backgrounds2 +body { + padding: 1em; + font: 1.2em / 1.5 sans-serif; +} +* { + box-sizing: border-box; +} +.box { + width: 300px; + padding: 0.5em; +} +``` + +```css live-sample___backgrounds2 +.box { + /* Add styles here */ +} + +h2 { + /* Add styles here */ +} +``` + +{{EmbedLiveSample("backgrounds2", "", "220px")}} + +<details> +<summary>Click here to show the solution</summary> + +You need to add padding to the heading so that it doesn't overlay the star image - this links back to learning from the earlier [Box Model lesson](/en-US/docs/Learn_web_development/Core/Styling_basics/Box_model). +The text should be aligned with the `text-align` property: + +```css +.box { + border: 5px solid lightblue; + border-top-left-radius: 20px; + border-bottom-right-radius: 40px; +} + +h2 { + padding: 0 40px; + text-align: center; + background: + url(https://mdn.github.io/shared-assets/images/examples/star.png) no-repeat + left center, + url(https://mdn.github.io/shared-assets/images/examples/star.png) repeat-y + right center; +} +``` + +</details> + +## See also + +- [CSS styling basics](/en-US/docs/Learn_web_development/Core/Styling_basics) diff --git a/files/en-us/learn_web_development/core/styling_basics/test_your_skills/box_model/index.md b/files/en-us/learn_web_development/core/styling_basics/test_your_skills/box_model/index.md new file mode 100644 index 000000000000000..570dd7c55a88877 --- /dev/null +++ b/files/en-us/learn_web_development/core/styling_basics/test_your_skills/box_model/index.md @@ -0,0 +1,172 @@ +--- +title: "Test your skills: The box model" +short-title: Box model +slug: Learn_web_development/Core/Styling_basics/Test_your_skills/Box_model +page-type: learn-module-assessment +sidebar: learnsidebar +--- + +The aim of this skill test is to assess whether you understand the [CSS box model](/en-US/docs/Learn_web_development/Core/Styling_basics/Box_model). + +> [!NOTE] +> Click **"Play"** in the code blocks below to edit the examples in the MDN Playground. +> You can also copy the code (click the clipboard icon) and paste it into an online editor such as [CodePen](https://codepen.io/), [JSFiddle](https://jsfiddle.net/), or [Glitch](https://glitch.com/). +> If you get stuck, you can reach out to us in one of our [communication channels](/en-US/docs/MDN/Community/Communication_channels). + +## Task 1 + +In this task, there are two boxes below, one is using the standard box model, the other the alternate box model. Change the width of the second box by adding declarations to the `.alternate` class, so that it matches the visual width of the first box. + +Your final result should look like the image below: + +![Two boxes of the same size](mdn-box-model1.png) + +Try to update the code below to recreate the finished example: + +```html live-sample___box-models +<div class="box">I use the standard box model.</div> +<div class="box alternate">I use the alternate box model.</div> +``` + +```css live-sample___box-models +body { + font: 1.2em / 1.5 sans-serif; +} +.box { + border: 5px solid rebeccapurple; + background-color: lightgray; + padding: 40px; + margin: 40px; + width: 300px; + height: 150px; +} + +.alternate { + box-sizing: border-box; +} +``` + +{{EmbedLiveSample("box-models", "", "540px")}} + +<details> +<summary>Click here to show the solution</summary> + +You will need to increase the width of the second block, to add the size of the padding and border: + +```css +.alternate { + box-sizing: border-box; + width: 390px; +} +``` + +</details> + +## Task 2 + +In this task, add the following things to the box: + +- A 5px, black, dotted border. +- A top margin of 20px. +- A right margin of 1em. +- A bottom margin of 40px. +- A left margin of 2em. +- Padding on all sides of 1em. + +Your final result should look like the image below: + +![A box with a dotted border](mdn-box-model2.png) + +Try to update the code below to recreate the finished example: + +```html live-sample___mbp +<div class="box">I use the standard box model.</div> +``` + +```css live-sample___mbp +body { + font: 1.2em / 1.5 sans-serif; +} + +.box { +} +``` + +{{EmbedLiveSample("mbp")}} + +<details> +<summary>Click here to show the solution</summary> + +This task involves using the margin, border and padding properties correctly. +You might choose to use the longhand properties ({{cssxref("margin-top")}}, {{cssxref("margin-right")}}, etc.), however when setting a margin and padding on all sides, the shorthand is probably the better choice: + +```css +.box { + border: 5px dotted black; + margin: 20px 1em 40px 2em; + padding: 1em; +} +``` + +</details> + +## Task 3 + +In this task, the inline element has a margin, padding and border. However, the lines above and below are overlapping it. What can you add to your CSS to cause the size of the margin, padding, and border to be respected by the other lines, while still keeping the element inline? + +Your final result should look like the image below: + +![An inline box with space between it and the text around it.](mdn-box-model3.png) + +Try to update the code below to recreate the finished example: + +```html live-sample___inline-block +<div class="box"> + <p> + Veggies es bonus vobis, <span>proinde vos postulo</span> essum magis + kohlrabi welsh onion daikon amaranth tatsoi tomatillo melon azuki bean + garlic. + </p> + + <p> + Gumbo beet greens corn soko endive gumbo gourd. Parsley shallot courgette + tatsoi pea sprouts fava bean collard greens dandelion okra wakame tomato. + Dandelion cucumber earthnut pea peanut soko zucchini. + </p> +</div> +``` + +```css live-sample___inline-block +body { + font: 1.2em / 1.5 sans-serif; +} + +.box span { + background-color: pink; + border: 5px solid black; + padding: 1em; +} +``` + +{{EmbedLiveSample("inline-block")}} + +<details> +<summary>Click here to show the solution</summary> + +Solving this task requires that you understand when to use different {{cssxref("display")}} values. +After adding `display: inline-block`, the block direction margin, border and padding will cause the other lines to be pushed away from the element: + +```css +.box span { + background-color: pink; + border: 5px solid black; + padding: 1em; + display: inline-block; +} +``` + +</details> + +## See also + +- [CSS styling basics](/en-US/docs/Learn_web_development/Core/Styling_basics) diff --git a/files/en-us/learn_web_development/core/styling_basics/box_model_tasks/mdn-box-model1.png b/files/en-us/learn_web_development/core/styling_basics/test_your_skills/box_model/mdn-box-model1.png similarity index 100% rename from files/en-us/learn_web_development/core/styling_basics/box_model_tasks/mdn-box-model1.png rename to files/en-us/learn_web_development/core/styling_basics/test_your_skills/box_model/mdn-box-model1.png diff --git a/files/en-us/learn_web_development/core/styling_basics/box_model_tasks/mdn-box-model2.png b/files/en-us/learn_web_development/core/styling_basics/test_your_skills/box_model/mdn-box-model2.png similarity index 100% rename from files/en-us/learn_web_development/core/styling_basics/box_model_tasks/mdn-box-model2.png rename to files/en-us/learn_web_development/core/styling_basics/test_your_skills/box_model/mdn-box-model2.png diff --git a/files/en-us/learn_web_development/core/styling_basics/box_model_tasks/mdn-box-model3.png b/files/en-us/learn_web_development/core/styling_basics/test_your_skills/box_model/mdn-box-model3.png similarity index 100% rename from files/en-us/learn_web_development/core/styling_basics/box_model_tasks/mdn-box-model3.png rename to files/en-us/learn_web_development/core/styling_basics/test_your_skills/box_model/mdn-box-model3.png diff --git a/files/en-us/learn_web_development/core/styling_basics/test_your_skills/cascade/index.md b/files/en-us/learn_web_development/core/styling_basics/test_your_skills/cascade/index.md new file mode 100644 index 000000000000000..20159cfb2b4da25 --- /dev/null +++ b/files/en-us/learn_web_development/core/styling_basics/test_your_skills/cascade/index.md @@ -0,0 +1,133 @@ +--- +title: "Test your skills: The Cascade" +short-title: Cascade +slug: Learn_web_development/Core/Styling_basics/Test_your_skills/Cascade +page-type: learn-module-assessment +sidebar: learnsidebar +--- + +The aim of this skill test is to assess whether you understand universal property values for [controlling inheritance in CSS](/en-US/docs/Learn_web_development/Core/Styling_basics/Handling_conflicts). + +> [!NOTE] +> Click **"Play"** in the code blocks below to edit the examples in the MDN Playground. +> You can also copy the code (click the clipboard icon) and paste it into an online editor such as [CodePen](https://codepen.io/), [JSFiddle](https://jsfiddle.net/), or [Glitch](https://glitch.com/). +> If you get stuck, you can reach out to us in one of our [communication channels](/en-US/docs/MDN/Community/Communication_channels). + +## Task 1 + +In this task, we want you to use one of the special values we looked at in the [controlling inheritance](/en-US/docs/Learn_web_development/Core/Styling_basics/Handling_conflicts#controlling_inheritance) section. To write a declaration in a new rule that will reset the background color back to white, without using an actual color value. + +Your final result should look like the image below: + +![Barely visible yellow links on a white background.](mdn-cascade.png) + +Try to update the code below to recreate the finished example: + +```html live-sample___cascade +<div class="container" id="outer"> + <div class="container" id="inner"> + <ul> + <li class="nav"><a href="#">One</a></li> + <li class="nav"><a href="#">Two</a></li> + </ul> + </div> +</div> +``` + +```css live-sample___cascade +#outer div ul .nav a { + background-color: powderblue; + padding: 5px; + display: inline-block; + margin-bottom: 10px; +} + +div div li a { + color: rebeccapurple; +} +``` + +{{EmbedLiveSample("cascade")}} + +<details> +<summary>Click here to show the solution</summary> + +One possible solution is as follows: + +```css +#outer #inner a { + background-color: inherit; +} +``` + +There are two things you need to do in this task. First, write a selector for the `a` element which is more specific than the selector used to turn the background powderblue. In this solution, this is achieved by using the `id` selector, which has very high specificity. + +Then you need to remember there are special keyword values for all properties. In this case, using `inherit` sets the background color back to be the same as its parent element. + +</details> + +## Task 2 + +In this task, we want you to manipulate the cascade layer order to color the links `rebeccapurple`. No editing the `lightgreen` declaration! + +This task is a stretch goal — it requires knowledge of cascade layers, which we didn't cover in the [Handling conflicts](/en-US/docs/Learn_web_development/Core/Styling_basics/Handling_conflicts) article. You can find the information you need to attempt this task at [Cascade layers > Determining the precedence based on the order of layers](/en-US/docs/Learn_web_development/Core/Styling_basics/Cascade_layers#determining_the_precedence_based_on_the_order_of_layers). + +Your final result should look like the image below: + +![Barely visible yellow links on a white background.](mdn-cascade.png) + +Try to update the code below to recreate the finished example: + +```html live-sample___cascade-layer +<div class="container" id="outer"> + <div class="container" id="inner"> + <ul> + <li class="nav"><a href="#">One</a></li> + <li class="nav"><a href="#">Two</a></li> + </ul> + </div> +</div> +``` + +```css live-sample___cascade-layer +@layer yellow, purple, green; + +@layer yellow { + #outer div ul .nav a { + padding: 5px; + display: inline-block; + margin-bottom: 10px; + } +} +@layer purple { + div div li a { + color: rebeccapurple; + } +} +@layer green { + a { + color: lightgreen; + } +} +``` + +{{EmbedLiveSample("cascade-layer")}} + +<details> +<summary>Click here to show the solution</summary> + +One possible solution is as follows: + +```css +@layer yellow, green, purple; +``` + +There is one thing you need to do in this task: change the order of precedence so the declaration for the desired color is in the last declared layer, which is what this solution shows. + +You need to remember that unlayered normal styles take precedence over layered normal styles. But, if all styles are within layers — as in the case of this task — styles in later declared layers take precedence over styles declared in earlier layers. Moving the purple layer to the end means it has precedence over the green and yellow layers. + +</details> + +## See also + +- [CSS styling basics](/en-US/docs/Learn_web_development/Core/Styling_basics) diff --git a/files/en-us/learn_web_development/core/styling_basics/cascade_tasks/mdn-cascade.png b/files/en-us/learn_web_development/core/styling_basics/test_your_skills/cascade/mdn-cascade.png similarity index 100% rename from files/en-us/learn_web_development/core/styling_basics/cascade_tasks/mdn-cascade.png rename to files/en-us/learn_web_development/core/styling_basics/test_your_skills/cascade/mdn-cascade.png diff --git a/files/en-us/learn_web_development/core/styling_basics/test_your_skills/images/index.md b/files/en-us/learn_web_development/core/styling_basics/test_your_skills/images/index.md new file mode 100644 index 000000000000000..914ae4410740405 --- /dev/null +++ b/files/en-us/learn_web_development/core/styling_basics/test_your_skills/images/index.md @@ -0,0 +1,131 @@ +--- +title: "Test your skills: Images and form elements" +short-title: Images and forms +slug: Learn_web_development/Core/Styling_basics/Test_your_skills/Images +page-type: learn-module-assessment +sidebar: learnsidebar +--- + +The aim of this skill test is to assess whether you understand how special elements like [images, media and form elements are treated in CSS](/en-US/docs/Learn_web_development/Core/Styling_basics/Images_media_forms). + +> [!NOTE] +> Click **"Play"** in the code blocks below to edit the examples in the MDN Playground. +> You can also copy the code (click the clipboard icon) and paste it into an online editor such as [CodePen](https://codepen.io/), [JSFiddle](https://jsfiddle.net/), or [Glitch](https://glitch.com/). +> If you get stuck, you can reach out to us in one of our [communication channels](/en-US/docs/MDN/Community/Communication_channels). + +## Task 1 + +In this task, you have an image that is overflowing the box. We want the image to scale down to fit inside the box without any extra white space, but we do not mind if some part of the image is cropped. + +Your final result should look like the image below: + +![An image in a box](mdn-images-object-fit.png) + +Try to update the code below to recreate the finished example so that the image doesn't overflow the box: + +```html live-sample___object-fit +<div class="box"> + <img + alt="Hot air balloons flying in clear sky, and a crowd of people in the foreground" + src="https://mdn.github.io/shared-assets/images/examples/balloons.jpg" /> +</div> +``` + +```css live-sample___object-fit +.box { + border: 5px solid #000; + width: 400px; + height: 200px; +} + +img { + /* Add styles here */ +} +``` + +{{EmbedLiveSample("object-fit", "", "400px")}} + +<details> +<summary>Click here to show the solution</summary> + +It is ok if some parts of the image are cropped. +Using `object-fit: cover` is the best choice, you also need to set the width and height to `100%`: + +```css +img { + height: 100%; + width: 100%; + object-fit: cover; +} +``` + +</details> + +## Task 2 + +In this task, you have a basic form. Your task is to make the following changes: + +- Use attribute selectors to target the search field and button inside `.my-form`. +- Make the form field and button use the same text size as the rest of the form. +- Give the form field and button 10px of padding. +- Give the button a background of `rebeccapurple`, white foreground, no border and rounded corners of 5px. + +Your final result should look like the image below: + +![A single line form](mdn-images-form.png) + +Try to update the code below to recreate the finished example: + +```html live-sample___form +<form action="" class="my-form" method="post"> + <div> + <label for="fldSearch">Keywords</label> + <input id="fldSearch" name="keywords" type="search" /> + <input name="btnSubmit" type="submit" value="Search" /> + </div> +</form> +``` + +```css live-sample___form +body { + font: 1.2em / 1.5 sans-serif; +} +.my-form { + border: 2px solid #000; + padding: 5px; +} +``` + +{{EmbedLiveSample("form")}} + +<details> +<summary>Click here to show the solution</summary> + +Here's an example solution for the task: + +```css +.my-form { + border: 2px solid #000; + padding: 5px; +} + +.my-form input[type="search"] { + padding: 10px; + font-size: inherit; +} + +.my-form input[type="submit"] { + padding: 10px; + font-size: inherit; + background-color: rebeccapurple; + color: white; + border: 0; + border-radius: 5px; +} +``` + +</details> + +## See also + +- [CSS styling basics](/en-US/docs/Learn_web_development/Core/Styling_basics) diff --git a/files/en-us/learn_web_development/core/styling_basics/images_tasks/mdn-images-form.png b/files/en-us/learn_web_development/core/styling_basics/test_your_skills/images/mdn-images-form.png similarity index 100% rename from files/en-us/learn_web_development/core/styling_basics/images_tasks/mdn-images-form.png rename to files/en-us/learn_web_development/core/styling_basics/test_your_skills/images/mdn-images-form.png diff --git a/files/en-us/learn_web_development/core/styling_basics/images_tasks/mdn-images-object-fit.png b/files/en-us/learn_web_development/core/styling_basics/test_your_skills/images/mdn-images-object-fit.png similarity index 100% rename from files/en-us/learn_web_development/core/styling_basics/images_tasks/mdn-images-object-fit.png rename to files/en-us/learn_web_development/core/styling_basics/test_your_skills/images/mdn-images-object-fit.png diff --git a/files/en-us/learn_web_development/core/styling_basics/test_your_skills/index.md b/files/en-us/learn_web_development/core/styling_basics/test_your_skills/index.md new file mode 100644 index 000000000000000..7e17bd29e91311f --- /dev/null +++ b/files/en-us/learn_web_development/core/styling_basics/test_your_skills/index.md @@ -0,0 +1,17 @@ +--- +title: "Test your skills: CSS styling basics" +short-title: Test your skills +slug: Learn_web_development/Core/Styling_basics/Test_your_skills +page-type: learn-module-assessment +sidebar: learnsidebar +--- + +This page lists CSS styling basics tests you can try so you can verify if you've understood the content in this module. + +## Test your CSS styling basics skills by topic + +{{SubpagesWithSummaries}} + +## See also + +- [CSS styling basics](/en-US/docs/Learn_web_development/Core/Styling_basics) diff --git a/files/en-us/learn_web_development/core/styling_basics/test_your_skills/overflow/index.md b/files/en-us/learn_web_development/core/styling_basics/test_your_skills/overflow/index.md new file mode 100644 index 000000000000000..6961fceee18b336 --- /dev/null +++ b/files/en-us/learn_web_development/core/styling_basics/test_your_skills/overflow/index.md @@ -0,0 +1,113 @@ +--- +title: "Test your skills: Overflow" +short-title: Overflow +slug: Learn_web_development/Core/Styling_basics/Test_your_skills/Overflow +page-type: learn-module-assessment +sidebar: learnsidebar +--- + +The aim of this skill test is to assess whether you understand [overflow in CSS and how to manage it](/en-US/docs/Learn_web_development/Core/Styling_basics/Overflow). + +> [!NOTE] +> Click **"Play"** in the code blocks below to edit the examples in the MDN Playground. +> You can also copy the code (click the clipboard icon) and paste it into an online editor such as [CodePen](https://codepen.io/), [JSFiddle](https://jsfiddle.net/), or [Glitch](https://glitch.com/). +> If you get stuck, you can reach out to us in one of our [communication channels](/en-US/docs/MDN/Community/Communication_channels). + +## Task 1 + +In this task, the content is overflowing the box because it has a fixed height. Keep the height but cause the box to have scrollbars only if there is enough text to cause an overflow. Test by removing some of the text from the HTML, that if there is only a small amount of text that does not overflow, no scrollbar appears. + +![A small box with a border and a vertical scrollbar.](mdn-overflow1.png) + +Try to update the code below to recreate the finished example: + +```html live-sample___overflow-scroll +<div class="box"> + <p> + Veggies es bonus vobis, proinde vos postulo essum magis kohlrabi welsh onion + daikon amaranth tatsoi tomatillo melon azuki bean garlic. + </p> + + <p> + Gumbo beet greens corn soko endive gumbo gourd. Parsley shallot courgette + tatsoi pea sprouts fava bean collard greens dandelion okra wakame tomato. + Dandelion cucumber earthnut pea peanut soko zucchini. + </p> +</div> +``` + +```css live-sample___overflow-scroll +body { + font: 1.2em / 1.5 sans-serif; +} + +.box { + border: 5px solid black; + padding: 1em; + height: 200px; + width: 300px; +} +``` + +{{EmbedLiveSample("overflow-scroll", "", "450px")}} + +<details> +<summary>Click here to show the solution</summary> + +You should add `overflow: auto` so that the box will only gain scrollbars when the content is too large: + +```css +.box { + overflow: auto; +} +``` + +</details> + +## Task 2 + +In this task, there is an image in the box that is bigger than the dimensions of the box so that it overflows visibly. Change it so that any image outside of the box is hidden. + +Your final result should look like the image below: + +![A box with an image which fills the box but does not spill out the edges.](mdn-overflow2.png) + +Try to update the code below to recreate the finished example: + +```html live-sample___overflow-hidden +<div class="box"> + <img + alt="flowers" + src="https://mdn.github.io/shared-assets/images/examples/flowers.jpg" /> +</div> +``` + +```css live-sample___overflow-hidden +body { + font: 1.2em / 1.5 sans-serif; +} +.box { + border: 5px solid black; + height: 200px; + width: 300px; +} +``` + +{{EmbedLiveSample("overflow-hidden", "", "300px")}} + +<details> +<summary>Click here to show the solution</summary> + +You should add `overflow: hidden` to the `.box` selector: + +```css +.box { + overflow: hidden; +} +``` + +</details> + +## See also + +- [CSS styling basics](/en-US/docs/Learn_web_development/Core/Styling_basics) diff --git a/files/en-us/learn_web_development/core/styling_basics/overflow_tasks/mdn-overflow1.png b/files/en-us/learn_web_development/core/styling_basics/test_your_skills/overflow/mdn-overflow1.png similarity index 100% rename from files/en-us/learn_web_development/core/styling_basics/overflow_tasks/mdn-overflow1.png rename to files/en-us/learn_web_development/core/styling_basics/test_your_skills/overflow/mdn-overflow1.png diff --git a/files/en-us/learn_web_development/core/styling_basics/overflow_tasks/mdn-overflow2.png b/files/en-us/learn_web_development/core/styling_basics/test_your_skills/overflow/mdn-overflow2.png similarity index 100% rename from files/en-us/learn_web_development/core/styling_basics/overflow_tasks/mdn-overflow2.png rename to files/en-us/learn_web_development/core/styling_basics/test_your_skills/overflow/mdn-overflow2.png diff --git a/files/en-us/learn_web_development/core/styling_basics/test_your_skills/selectors/index.md b/files/en-us/learn_web_development/core/styling_basics/test_your_skills/selectors/index.md new file mode 100644 index 000000000000000..4e5b9a6a4e9f956 --- /dev/null +++ b/files/en-us/learn_web_development/core/styling_basics/test_your_skills/selectors/index.md @@ -0,0 +1,407 @@ +--- +title: "Test your skills: Selectors" +short-title: Selectors +slug: Learn_web_development/Core/Styling_basics/Test_your_skills/Selectors +page-type: learn-module-assessment +sidebar: learnsidebar +--- + +The aim of this skill test is to assess whether you understand [CSS selectors](/en-US/docs/Learn_web_development/Core/Styling_basics/Basic_selectors). + +> [!NOTE] +> Click **"Play"** in the code blocks below to edit the examples in the MDN Playground. +> You can also copy the code (click the clipboard icon) and paste it into an online editor such as [CodePen](https://codepen.io/), [JSFiddle](https://jsfiddle.net/), or [Glitch](https://glitch.com/). +> If you get stuck, you can reach out to us in one of our [communication channels](/en-US/docs/MDN/Community/Communication_channels). + +## Task 1 + +In this task, use CSS to do the following things, without changing the HTML: + +- Make `<h1>` headings blue. +- Give `<h2>` headings a blue background and white text. +- Cause text wrapped in a `<span>` to have a font-size of 200%. + +Your final result should look like the image below: + +![Text with the CSS applied for the solution to task 1.](selectors1.jpg) + +Try to update the code below to recreate the finished example: + +```html live-sample___type +<div class="container"> + <h1>This is a heading</h1> + <p> + Veggies es <span>bonus vobis</span>, proinde vos postulo essum magis + kohlrabi welsh onion daikon amaranth tatsoi tomatillo melon azuki bean + garlic. + </p> + <h2>A level 2 heading</h2> + <p> + Gumbo beet greens corn soko endive gumbo gourd. Parsley shallot courgette + tatsoi pea sprouts fava bean collard greens dandelion okra wakame tomato. + Dandelion cucumber earthnut pea peanut soko zucchini. + </p> +</div> +``` + +```css live-sample___type +body { + font: 1.2em / 1.5 sans-serif; +} +/* Add styles here */ +``` + +{{EmbedLiveSample("type", "", "260px")}} + +<details> +<summary>Click here to show the solution</summary> + +You need to target the `h1`, `h2` and `span` selectors to change their color or size. + +```css +h1 { + color: blue; +} + +h2 { + background-color: blue; + color: white; +} + +span { + font-size: 200%; +} +``` + +</details> + +## Task 2 + +In this task, we want you to make the following changes to the look of the content in this example, without changing the HTML: + +- Give the element with an id of `special` a yellow background. +- Give the element with a class of `alert` a 2px grey border. +- If the element with a class of `alert` also has a class of `stop`, make the background red. +- If the element with a class of `alert` also has a class of `go`, make the background green. + +Your final result should look like the image below: + +![Text with the CSS applied for the solution to task 2.](selectors2.jpg) + +Try to update the code below to recreate the finished example: + +```html live-sample___class-id +<div class="container"> + <h1>This is a heading</h1> + <p> + Veggies es <span class="alert">bonus vobis</span>, proinde vos postulo + <span class="alert stop">essum magis</span> kohlrabi welsh onion daikon + amaranth tatsoi tomatillo melon azuki bean garlic. + </p> + <h2 id="special">A level 2 heading</h2> + <p>Gumbo beet greens corn soko endive gumbo gourd.</p> + <h2>Another level 2 heading</h2> + <p> + <span class="alert go">Parsley shallot</span> courgette tatsoi pea sprouts + fava bean collard greens dandelion okra wakame tomato. Dandelion cucumber + earthnut pea peanut soko zucchini. + </p> +</div> +``` + +```css live-sample___class-id +body { + font: 1.2em / 1.5 sans-serif; +} +/* Add styles here */ +``` + +{{EmbedLiveSample("class-id", "", "320px")}} + +<details> +<summary>Click here to show the solution</summary> + +This tests that you understand the difference between class and id selectors and also how to target multiple classes on an item. + +```css +#special { + background-color: yellow; +} + +.alert { + border: 2px solid grey; +} + +.alert.stop { + background-color: red; +} + +.alert.go { + background-color: green; +} +``` + +</details> + +## Task 3 + +In this task, we want you to make the following changes without changing the HTML: + +- Style links, making the link-state orange, visited links green, and remove the underline on hover. +- Make the first element inside the container `font-size: 150%` and the first line of that element red. +- Stripe every other row in the table by selecting these rows and giving them a background color of `#333` and foreground white. + +Your final result should look like the image below: + +![Text with the CSS applied for the solution to task 3.](selectors3.jpg) + +Try to update the code below to recreate the finished example: + +```html live-sample___pseudo +<div class="container"> + <p> + Veggies es <a href="http://example.com">bonus vobis</a>, proinde vos postulo + essum magis kohlrabi welsh onion daikon amaranth tatsoi tomatillo melon + azuki bean garlic. + </p> + <p> + Gumbo beet greens corn soko endive gumbo gourd. Parsley shallot courgette + tatsoi pea sprouts fava bean collard greens dandelion okra wakame tomato. + Dandelion cucumber earthnut pea peanut soko zucchini. + </p> + <table> + <tbody> + <tr> + <th>Fruits</th> + <th>Vegetables</th> + </tr> + <tr> + <td>Apple</td> + <td>Potato</td> + </tr> + <tr> + <td>Orange</td> + <td>Carrot</td> + </tr> + <tr> + <td>Tomato</td> + <td>Parsnip</td> + </tr> + <tr> + <td>Kiwi</td> + <td>Onion</td> + </tr> + <tr> + <td>Banana</td> + <td>Beet</td> + </tr> + </tbody> + </table> +</div> +``` + +```css hidden live-sample___pseudo +body { + font: 1.2em / 1.5 sans-serif; +} +* { + box-sizing: border-box; +} + +table { + border-collapse: collapse; + width: 300px; +} + +td, +th { + padding: 0.2em; + text-align: left; +} +``` + +```css live-sample___pseudo +/* Add styles here */ +``` + +{{EmbedLiveSample("pseudo", "", "320px")}} + +<details> +<summary>Click here to show the solution</summary> + +Apply a pseudo-class (`:first-child`) and pseudo-element (`::first-line`) to the content. +Style the `:link`, `:visited`, and `:hover` states of the `a` element, and create striped table rows using the `:nth-child` pseudo-class. + +```css +.container p:first-child { + font-size: 150%; +} + +.container p:first-child::first-line { + color: red; +} + +a:link { + color: orange; +} + +a:visited { + color: green; +} + +a:hover { + text-decoration: none; +} + +tr:nth-child(even) { + background-color: #333; + color: #fff; +} +``` + +</details> + +## Task 4 + +In this task, we want you to do the following: + +- Make any paragraph that directly follows an `<h2>` element red. +- Remove the bullets and add a 1px grey bottom border only to list items that are a direct child of the ul with a class of `list`. + +Your final result should look like the image below: + +![Text with the CSS applied for the solution to task 4.](selectors4.jpg) + +Try to update the code below to recreate the finished example: + +```html live-sample___combinators +<div class="container"> + <h2>This is a heading</h2> + <p>This paragraph comes after the heading.</p> + <p>This is the second paragraph.</p> + + <h2>Another heading</h2> + <p>This paragraph comes after the heading.</p> + <ul class="list"> + <li>One</li> + <li> + Two + <ul> + <li>2.1</li> + <li>2.2</li> + </ul> + </li> + <li>Three</li> + </ul> +</div> +``` + +```css live-sample___combinators +body { + font: 1.2em / 1.5 sans-serif; +} +/* Add styles here */ +``` + +{{EmbedLiveSample("combinators", "", "350px")}} + +<details> +<summary>Click here to show the solution</summary> + +This task checks that you understand how to use different combinators. +Here's an appropriate solution: + +```css +h2 + p { + color: red; +} + +.list > li { + list-style: none; + border-bottom: 1px solid #ccc; +} +``` + +</details> + +## Task 5 + +In this task, add CSS using attribute selectors to do the following: + +- Target the `<a>` element with a `title` attribute and make the border pink (`border-color: pink`). +- Target the `<a>` element with an `href` attribute that contains the word `contact` somewhere in its value and make the border orange (`border-color: orange`). +- Target the `<a>` element with an `href` value starting with `https` and give it a green border (`border-color: green`). + +Your final result should look like the image below: + +![Four links with different color borders.](selectors-attribute.png) + +Try to update the code below to recreate the finished example: + +```html live-sample___attribute-links +<ul> + <li><a href="https://example.com">Link 1</a></li> + <li><a href="http://example.com" title="Visit example.com">Link 2</a></li> + <li><a href="/contact">Link 3</a></li> + <li><a href="../contact/index.html">Link 4</a></li> +</ul> +``` + +```css hidden live-sample___attribute-links +body { + font: 1.2em / 1.5 sans-serif; +} + +ul { + list-style: none; + margin: 0; + padding: 0; +} + +li { + margin: 0 0 0.5em 0; +} + +a { + display: block; + padding: 0.5em; +} +``` + +```css live-sample___attribute-links +a { + border: 5px solid grey; +} +/* Add styles here */ +``` + +{{EmbedLiveSample("attribute-links", "", "300px")}} + +<details> +<summary>Click here to show the solution</summary> + +- To select elements with a title attribute we can add title inside the square brackets (`a[title]`), which will select the second link, which is the only one with a title attribute. + +- Target the `<a>` element with an `href` attribute which contains the word "contact" anywhere in its value and make the border orange (`border-color: orange`). + There are two things we want to match here, the href value `/contact` and also `../contact`. So we need to match the string "contact" anywhere in the value using `*=`. This will select the third and fourth links. + +- Target the `<a>` element with an href value starting with `https` and give it a green border (`border-color: green`). + Look for an `href` value which starts with "https", so use `^=` to only select the first link. + +```css +a[title] { + border-color: pink; +} +a[href*="contact"] { + border-color: orange; +} +a[href^="https"] { + border-color: green; +} +``` + +</details> + +## See also + +- [CSS styling basics](/en-US/docs/Learn_web_development/Core/Styling_basics) diff --git a/files/en-us/learn_web_development/core/styling_basics/basic_selectors/selectors_tasks/selectors-attribute.png b/files/en-us/learn_web_development/core/styling_basics/test_your_skills/selectors/selectors-attribute.png similarity index 100% rename from files/en-us/learn_web_development/core/styling_basics/basic_selectors/selectors_tasks/selectors-attribute.png rename to files/en-us/learn_web_development/core/styling_basics/test_your_skills/selectors/selectors-attribute.png diff --git a/files/en-us/learn_web_development/core/styling_basics/basic_selectors/selectors_tasks/selectors1.jpg b/files/en-us/learn_web_development/core/styling_basics/test_your_skills/selectors/selectors1.jpg similarity index 100% rename from files/en-us/learn_web_development/core/styling_basics/basic_selectors/selectors_tasks/selectors1.jpg rename to files/en-us/learn_web_development/core/styling_basics/test_your_skills/selectors/selectors1.jpg diff --git a/files/en-us/learn_web_development/core/styling_basics/basic_selectors/selectors_tasks/selectors2.jpg b/files/en-us/learn_web_development/core/styling_basics/test_your_skills/selectors/selectors2.jpg similarity index 100% rename from files/en-us/learn_web_development/core/styling_basics/basic_selectors/selectors_tasks/selectors2.jpg rename to files/en-us/learn_web_development/core/styling_basics/test_your_skills/selectors/selectors2.jpg diff --git a/files/en-us/learn_web_development/core/styling_basics/basic_selectors/selectors_tasks/selectors3.jpg b/files/en-us/learn_web_development/core/styling_basics/test_your_skills/selectors/selectors3.jpg similarity index 100% rename from files/en-us/learn_web_development/core/styling_basics/basic_selectors/selectors_tasks/selectors3.jpg rename to files/en-us/learn_web_development/core/styling_basics/test_your_skills/selectors/selectors3.jpg diff --git a/files/en-us/learn_web_development/core/styling_basics/basic_selectors/selectors_tasks/selectors4.jpg b/files/en-us/learn_web_development/core/styling_basics/test_your_skills/selectors/selectors4.jpg similarity index 100% rename from files/en-us/learn_web_development/core/styling_basics/basic_selectors/selectors_tasks/selectors4.jpg rename to files/en-us/learn_web_development/core/styling_basics/test_your_skills/selectors/selectors4.jpg diff --git a/files/en-us/learn_web_development/core/styling_basics/test_your_skills/sizing/index.md b/files/en-us/learn_web_development/core/styling_basics/test_your_skills/sizing/index.md new file mode 100644 index 000000000000000..ed929e5d26ca2a4 --- /dev/null +++ b/files/en-us/learn_web_development/core/styling_basics/test_your_skills/sizing/index.md @@ -0,0 +1,208 @@ +--- +title: "Test your skills: Sizing" +short-title: Sizing +slug: Learn_web_development/Core/Styling_basics/Test_your_skills/Sizing +page-type: learn-module-assessment +sidebar: learnsidebar +--- + +The aim of this skill test is to assess whether you understand the different ways of [sizing items in CSS](/en-US/docs/Learn_web_development/Core/Styling_basics/Sizing). + +> [!NOTE] +> Click **"Play"** in the code blocks below to edit the examples in the MDN Playground. +> You can also copy the code (click the clipboard icon) and paste it into an online editor such as [CodePen](https://codepen.io/), [JSFiddle](https://jsfiddle.net/), or [Glitch](https://glitch.com/). +> If you get stuck, you can reach out to us in one of our [communication channels](/en-US/docs/MDN/Community/Communication_channels). + +## Task 1 + +In this task, you have two boxes. The first should be sized so that the height will be at least 100 pixels tall, even if there is less content that would cause it to grow to that height. However, the content should not overflow if there is more content than fits in 100 pixels. Test this box by removing the content from the HTML to make sure you still get a 100 pixel tall box even with no content. + +The second box should be fixed at 100 pixels tall, so that content will overflow if there is too much. + +![Two boxes one with overflowing content](mdn-sizing-height-min-height.png) + +Try to update the code below to recreate the finished example: + +```html live-sample___height-min-height +<div class="box box1"> + <p> + Veggies es bonus vobis, proinde vos postulo essum magis kohlrabi welsh onion + daikon amaranth tatsoi tomatillo melon azuki bean garlic. Gumbo beet greens + corn soko endive gumbo gourd. + </p> +</div> + +<div class="box box2"> + <p> + Veggies es bonus vobis, proinde vos postulo essum magis kohlrabi welsh onion + daikon amaranth tatsoi tomatillo melon azuki bean garlic. Gumbo beet greens + corn soko endive gumbo gourd. + </p> +</div> +``` + +```css hidden live-sample___height-min-height +body { + font: 1.2em / 1.5 sans-serif; + padding: 1em; +} + +.box { + border: 5px solid #000; + width: 400px; + margin-bottom: 1em; +} +``` + +```css live-sample___height-min-height +.box1 { + /* Add styles here */ +} + +.box2 { + /* Add styles here */ +} +``` + +{{EmbedLiveSample("height-min-height", "", "500px")}} + +<details> +<summary>Click here to show the solution</summary> + +There are two boxes, the first should be given a minimum height, in which case it will expand to take the additional content but if you remove some content, the box will be at least as tall as the `min-height`. The second is given a fixed height which will cause content to overflow. + +```css +.box1 { + min-height: 100px; +} + +.box2 { + height: 100px; +} +``` + +</details> + +## Task 2 + +In this task, you have a box, which contains another box. Your task is to make the inner box 60% of the width of the outer box. The value of the {{cssxref("box-sizing")}} property is set to `border-box`, which means that the total width includes any padding and border. You should also give the inner box padding of 10% using the width (or inline size) as the size from which that percentage is calculated. + +Your final result should look like the image below: + +![A box with another box nested inside](mdn-sizing-percentages.png) + +Try to update the code below to recreate the finished example: + +```html live-sample___percentages +<div class="box"> + <div class="inner">Make me 60% of my parent's width.</div> +</div> +``` + +```css hidden live-sample___percentages +body { + font: 1.2em / 1.5 sans-serif; + padding: 1em; +} +.box { + border: 5px solid #000; + width: 400px; + margin-bottom: 1em; +} + +.inner { + background-color: rebeccapurple; + color: white; + border-radius: 5px; +} +``` + +```css live-sample___percentages +* { + box-sizing: border-box; +} +.inner { + /* Add styles here */ +} +``` + +{{EmbedLiveSample("percentages", "", "250px")}} + +<details> +<summary>Click here to show the solution</summary> + +Make the box 60% of the container and give it 10% of padding on all sides. +All elements already have `box-sizing: border-box` to save you from worrying about which width you are using: + +```css +* { + box-sizing: border-box; +} +.inner { + width: 60%; + padding: 10%; +} +``` + +</details> + +## Task 3 + +In this task, you have two images in boxes. One image is smaller than the box, the other is larger and breaking out of the box. If you imagine that the box is responsive and therefore could grow and shrink, which property would you apply to the image so that the large image shrinks down into the box but the small image does not stretch. + +Your final result should look like the images below: + +![Two boxes with images in](mdn-sizing-max-width.png) + +Try to update the code below to recreate the finished example: + +```html live-sample___max-width +<div class="box"> + <img + alt="A pink star" + src="https://mdn.github.io/shared-assets/images/examples/star-pink_256x256.png" /> +</div> + +<div class="box"> + <img + alt="Hot air balloons flying in clear sky, and a crowd of people in the foreground" + src="https://mdn.github.io/shared-assets/images/examples/balloons.jpg" /> +</div> +``` + +```css hidden live-sample___max-width +body { + font: 1.2em / 1.5 sans-serif; + padding: 1em; +} +.box { + border: 5px solid #000; + margin-bottom: 1em; + width: 500px; +} +``` + +```css live-sample___max-width +img { + /* Add styles here */ +} +``` + +{{EmbedLiveSample("max-width", "", "700px")}} + +<details> +<summary>Click here to show the solution</summary> + +The example has an image which is breaking out of the box and one which is smaller than the box, you need to use `max-width` set to 100% to cause the larger image to grow only as large as the box. If you use `width: 100%`, the small image will stretch. + +```css +img { + max-width: 100%; +} +``` + +</details> + +## See also + +- [CSS styling basics](/en-US/docs/Learn_web_development/Core/Styling_basics) diff --git a/files/en-us/learn_web_development/core/styling_basics/sizing_tasks/mdn-sizing-height-min-height.png b/files/en-us/learn_web_development/core/styling_basics/test_your_skills/sizing/mdn-sizing-height-min-height.png similarity index 100% rename from files/en-us/learn_web_development/core/styling_basics/sizing_tasks/mdn-sizing-height-min-height.png rename to files/en-us/learn_web_development/core/styling_basics/test_your_skills/sizing/mdn-sizing-height-min-height.png diff --git a/files/en-us/learn_web_development/core/styling_basics/sizing_tasks/mdn-sizing-max-width.png b/files/en-us/learn_web_development/core/styling_basics/test_your_skills/sizing/mdn-sizing-max-width.png similarity index 100% rename from files/en-us/learn_web_development/core/styling_basics/sizing_tasks/mdn-sizing-max-width.png rename to files/en-us/learn_web_development/core/styling_basics/test_your_skills/sizing/mdn-sizing-max-width.png diff --git a/files/en-us/learn_web_development/core/styling_basics/sizing_tasks/mdn-sizing-percentages.png b/files/en-us/learn_web_development/core/styling_basics/test_your_skills/sizing/mdn-sizing-percentages.png similarity index 100% rename from files/en-us/learn_web_development/core/styling_basics/sizing_tasks/mdn-sizing-percentages.png rename to files/en-us/learn_web_development/core/styling_basics/test_your_skills/sizing/mdn-sizing-percentages.png diff --git a/files/en-us/learn_web_development/core/styling_basics/test_your_skills/tables/index.md b/files/en-us/learn_web_development/core/styling_basics/test_your_skills/tables/index.md new file mode 100644 index 000000000000000..d94c4017aeb7786 --- /dev/null +++ b/files/en-us/learn_web_development/core/styling_basics/test_your_skills/tables/index.md @@ -0,0 +1,183 @@ +--- +title: "Test your skills: Tables" +short-title: Tables +slug: Learn_web_development/Core/Styling_basics/Test_your_skills/Tables +page-type: learn-module-assessment +sidebar: learnsidebar +--- + +The aim of this skill test is to assess whether you understand how to [style HTML tables in CSS](/en-US/docs/Learn_web_development/Core/Styling_basics/Tables). + +> [!NOTE] +> Click **"Play"** in the code blocks below to edit the examples in the MDN Playground. +> You can also copy the code (click the clipboard icon) and paste it into an online editor such as [CodePen](https://codepen.io/), [JSFiddle](https://jsfiddle.net/), or [Glitch](https://glitch.com/). +> If you get stuck, you can reach out to us in one of our [communication channels](/en-US/docs/MDN/Community/Communication_channels). + +## Task + +In the lesson on [styling tables](/en-US/docs/Learn_web_development/Core/Styling_basics/Tables), we styled up a table in a rather garish manner. In this task, we are going to style the same table, but using some good practices for table design as outlined in the external article [Web Typography: designing tables to be read not looked at](https://alistapart.com/article/web-typography-tables/). + +Our finished table will look like the image below. There are a number of ways that you can achieve this, but we suggest you follow similar patterns as used in the tutorial to do the following things: + +- Add padding of `0.3em` to the table headings and data and align them at the top of their cells. +- Align headings and data for columns containing numbers right. +- Align headings and data for columns containing text left. +- Align the heading of the table footer right. +- Align the data of the table footer left. +- Add a 1px top and bottom solid border with the hex color `#999` to the table. +- Add a 1px top solid border with the hex color `#999` to the footer. +- Remove the default spacing between the table elements borders to get the expected result. +- Stripe every odd row of the main table with the hex color `#eee`. + +![A table with striped rows.](mdn-table-bands.png) + +**Bonus question:** What can you do to make the table layout behave a bit more predictably? Think of how table columns are sized by default and how we can change this behavior to size the columns according to the width of their headings. + +Try to update the code below to recreate the finished example: + +```html live-sample___table +<table> + <caption> + A summary of the UK's most famous punk bands + </caption> + <thead> + <tr> + <th scope="col">Band</th> + <th scope="col">Year formed</th> + <th scope="col">No. of Albums</th> + <th scope="col">Most famous song</th> + </tr> + </thead> + <tbody> + <tr> + <th scope="row">Buzzcocks</th> + <td>1976</td> + <td>9</td> + <td>Ever fallen in love (with someone you shouldn't've)</td> + </tr> + <tr> + <th scope="row">The Clash</th> + <td>1976</td> + <td>6</td> + <td>London Calling</td> + </tr> + <tr> + <th scope="row">The Damned</th> + <td>1976</td> + <td>10</td> + <td>Smash it up</td> + </tr> + <tr> + <th scope="row">Sex Pistols</th> + <td>1975</td> + <td>1</td> + <td>Anarchy in the UK</td> + </tr> + <tr> + <th scope="row">Sham 69</th> + <td>1976</td> + <td>13</td> + <td>If the kids are united</td> + </tr> + <tr> + <th scope="row">Siouxsie and the Banshees</th> + <td>1976</td> + <td>11</td> + <td>Hong Kong Garden</td> + </tr> + <tr> + <th scope="row">Stiff Little Fingers</th> + <td>1977</td> + <td>10</td> + <td>Suspect Device</td> + </tr> + <tr> + <th scope="row">The Stranglers</th> + <td>1974</td> + <td>17</td> + <td>No More Heroes</td> + </tr> + </tbody> + <tfoot> + <tr> + <th colspan="2" scope="row">Total albums</th> + <td colspan="2">77</td> + </tr> + </tfoot> +</table> +``` + +```css hidden live-sample___table +body { + padding: 1em; + font: 1.2em / 1.5 sans-serif; + font-size: 80%; +} +``` + +```css live-sample___table +/* Add styles here */ +``` + +{{EmbedLiveSample("table", "", "400px")}} + +<details> +<summary>Click here to show the solution</summary> + +The below is a sample of how the end result could be achieved, using similar techniques to the lesson. However there are a number of ways that would be perfectly correct, perhaps slightly more verbose. + +```css +table { + border-top: 1px solid #999; + border-bottom: 1px solid #999; + border-collapse: collapse; +} + +th, +td { + vertical-align: top; + padding: 0.3em; +} + +tr :nth-child(2), +tr :nth-child(3) { + text-align: right; +} + +tr :nth-child(1), +tr :nth-child(4) { + text-align: left; +} + +tbody tr:nth-child(odd) { + background-color: #eee; +} + +tfoot { + border-top: 1px solid #999; +} + +tfoot tr :nth-child(1) { + text-align: right; +} + +tfoot tr :nth-child(2) { + text-align: left; +} +``` + +For the bonus question, you can make the table layout more predictable by adding {{cssxref("table-layout")}} with a value of [`fixed`](/en-US/docs/Web/CSS/table-layout#fixed) and an explicit `width`: + +```css +table { + table-layout: fixed; + width: 100%; +} +``` + +</details> + +## See also + +- [CSS styling basics](/en-US/docs/Learn_web_development/Core/Styling_basics) +- [Web Typography: Designing Tables to be Read, Not Looked At](https://alistapart.com/article/web-typography-tables/) on alistapart.com (2017) diff --git a/files/en-us/learn_web_development/core/styling_basics/tables_tasks/mdn-table-bands.png b/files/en-us/learn_web_development/core/styling_basics/test_your_skills/tables/mdn-table-bands.png similarity index 100% rename from files/en-us/learn_web_development/core/styling_basics/tables_tasks/mdn-table-bands.png rename to files/en-us/learn_web_development/core/styling_basics/test_your_skills/tables/mdn-table-bands.png diff --git a/files/en-us/learn_web_development/core/styling_basics/test_your_skills/values/index.md b/files/en-us/learn_web_development/core/styling_basics/test_your_skills/values/index.md new file mode 100644 index 000000000000000..0d3b238de2dfc14 --- /dev/null +++ b/files/en-us/learn_web_development/core/styling_basics/test_your_skills/values/index.md @@ -0,0 +1,213 @@ +--- +title: "Test your skills: Values and units" +short-title: Values and units +slug: Learn_web_development/Core/Styling_basics/Test_your_skills/Values +page-type: learn-module-assessment +sidebar: learnsidebar +--- + +The aim of this skill test is to assess whether you understand different types of [values and units used in CSS properties](/en-US/docs/Learn_web_development/Core/Styling_basics/Values_and_units). + +> [!NOTE] +> Click **"Play"** in the code blocks below to edit the examples in the MDN Playground. +> You can also copy the code (click the clipboard icon) and paste it into an online editor such as [CodePen](https://codepen.io/), [JSFiddle](https://jsfiddle.net/), or [Glitch](https://glitch.com/). +> If you get stuck, you can reach out to us in one of our [communication channels](/en-US/docs/MDN/Community/Communication_channels). + +## Task 1 + +In this task, the first list item has been given a background color using a hex color code. Your task is to complete the CSS using the same color in different formats, plus a final list item where you should make the background semi-opaque. + +- The second list item should use RGB color. +- The third should use HSL color. +- The fourth should use RGB color but with the alpha channel set to `0.6`. + +You [can convert the hex color at convertingcolors.com](https://convertingcolors.com/hex-color-86DEFA.html). You need to figure out how to use the values in CSS. Your final result should look like the image below: + +![Four list items. The first three with the same background color and the last with a lighter background.](mdn-value-color.png) + +Try to update the code below to recreate the finished example: + +```html live-sample___color +<ul> + <li class="hex">hex color</li> + <li class="rgb">RGB color</li> + <li class="hsl">HSL color</li> + <li class="transparency">Alpha value 0.6</li> +</ul> +``` + +```css hidden live-sample___color +body { + font: 1.2em / 1.5 sans-serif; +} +ul { + list-style: none; + margin: 0; + padding: 0; +} + +li { + margin: 1em; + padding: 0.5em; +} +``` + +```css live-sample___color +.hex { + background-color: #86defa; +} + +/* Add styles here */ +``` + +{{EmbedLiveSample("color", "", "300px")}} + +<details> +<summary>Click here to show the solution</summary> + +By using [a color conversion tool](https://convertingcolors.com/hex-color-86DEFA.html), you should be equipped to use different [color functions](/en-US/docs/Web/CSS/color_value#syntax) to define the same color in different ways: + +```css +.hex { + background-color: #86defa; +} + +.rgb { + background-color: rgb(134 222 250); +} + +.hsl { + background-color: hsl(194 92% 75%); +} + +.transparency { + background-color: rgb(134 222 250 / 60%); +} +``` + +</details> + +## Task 2 + +In this task, we want you to set the size of various items of text, as described below: + +- The `<h1>` element should be 50 pixels. +- The `<h2>` element should be 2em. +- All `<p>` elements should be 16 pixels. +- A `<p>` element that is directly after an `<h1>` should be 120%. + +Your final result should look like the image below: + +![Some text at varying sizes.](mdn-value-length.png) + +Try to update the code below to recreate the finished example: + +```html live-sample___length +<h1>Level 1 heading</h1> +<p> + Veggies es bonus vobis, proinde vos postulo essum magis kohlrabi welsh onion + daikon amaranth tatsoi tomatillo melon azuki bean garlic. +</p> +<h2>Level 2 heading</h2> +<p> + Gumbo beet greens corn soko endive gumbo gourd. Parsley shallot courgette + tatsoi pea sprouts fava bean collard greens dandelion okra wakame tomato. + Dandelion cucumber earthnut pea peanut soko zucchini. +</p> +``` + +```css hidden live-sample___length +body { + font: 1.2em / 1.5 sans-serif; +} +``` + +```css live-sample___length +h1 { +} + +h2 { +} + +p { +} + +h1 + p { +} +``` + +{{EmbedLiveSample("length", "", "420px")}} + +<details> +<summary>Click here to show the solution</summary> + +You can use the following length values: + +```css +h1 { + font-size: 50px; +} + +h2 { + font-size: 2em; +} + +p { + font-size: 16px; +} + +h1 + p { + font-size: 120%; +} +``` + +</details> + +## Task 3 + +In this task, we want you to move the background image so that it is centered horizontally and is 20% from the top of the box. + +Your final result should look like the image below: + +![A stat centered horizontally in a box and a short distance from the top of the box.](mdn-value-position.png) + +Try to update the code below to recreate the finished example: + +```html live-sample___position +<div class="box"></div> +``` + +```css hidden live-sample___position +.box { + border: 5px solid #000; + height: 350px; +} +``` + +```css live-sample___position +.box { + background-image: url(https://mdn.github.io/shared-assets/images/examples/purple-star.png); + background-repeat: no-repeat; +} +``` + +{{EmbedLiveSample("position", "", "400px")}} + +<details> +<summary>Click here to show the solution</summary> + +Use `background-position` with the `center` keyword and a percentage: + +```css +.box { + background-image: url(https://mdn.github.io/shared-assets/images/examples/purple-star.png); + background-repeat: no-repeat; + background-position: center 20%; +} +``` + +</details> + +## See also + +- [CSS styling basics](/en-US/docs/Learn_web_development/Core/Styling_basics) diff --git a/files/en-us/learn_web_development/core/styling_basics/values_tasks/mdn-value-color.png b/files/en-us/learn_web_development/core/styling_basics/test_your_skills/values/mdn-value-color.png similarity index 100% rename from files/en-us/learn_web_development/core/styling_basics/values_tasks/mdn-value-color.png rename to files/en-us/learn_web_development/core/styling_basics/test_your_skills/values/mdn-value-color.png diff --git a/files/en-us/learn_web_development/core/styling_basics/values_tasks/mdn-value-length.png b/files/en-us/learn_web_development/core/styling_basics/test_your_skills/values/mdn-value-length.png similarity index 100% rename from files/en-us/learn_web_development/core/styling_basics/values_tasks/mdn-value-length.png rename to files/en-us/learn_web_development/core/styling_basics/test_your_skills/values/mdn-value-length.png diff --git a/files/en-us/learn_web_development/core/styling_basics/values_tasks/mdn-value-position.png b/files/en-us/learn_web_development/core/styling_basics/test_your_skills/values/mdn-value-position.png similarity index 100% rename from files/en-us/learn_web_development/core/styling_basics/values_tasks/mdn-value-position.png rename to files/en-us/learn_web_development/core/styling_basics/test_your_skills/values/mdn-value-position.png diff --git a/files/en-us/learn_web_development/core/styling_basics/test_your_skills/writing_modes/index.md b/files/en-us/learn_web_development/core/styling_basics/test_your_skills/writing_modes/index.md new file mode 100644 index 000000000000000..f0d7d1634a14e7e --- /dev/null +++ b/files/en-us/learn_web_development/core/styling_basics/test_your_skills/writing_modes/index.md @@ -0,0 +1,183 @@ +--- +title: "Test your skills: Writing modes and logical properties" +short-title: Writing modes +slug: Learn_web_development/Core/Styling_basics/Test_your_skills/Writing_modes +page-type: learn-module-assessment +sidebar: learnsidebar +--- + +The aim of this skill test is to assess whether you understand how to [handle different text directions using writing modes and logical properties in CSS](/en-US/docs/Learn_web_development/Core/Styling_basics/Handling_different_text_directions). + +> [!NOTE] +> Click **"Play"** in the code blocks below to edit the examples in the MDN Playground. +> You can also copy the code (click the clipboard icon) and paste it into an online editor such as [CodePen](https://codepen.io/), [JSFiddle](https://jsfiddle.net/), or [Glitch](https://glitch.com/). +> If you get stuck, you can reach out to us in one of our [communication channels](/en-US/docs/MDN/Community/Communication_channels). + +## Task 1 + +In this task, the box is displayed with a horizontal writing mode. Can you add a line of CSS to change it so it uses a vertical writing mode with right to left text? + +Your final result should look like the image below: + +![A box with a vertical writing mode](mdn-writing-modes1.png) + +Try to update the code below to recreate the finished example: + +```html live-sample___writing-mode +<div class="box">Turn me on my side.</div> +``` + +```css hidden live-sample___writing-mode +body { + font: 1.2em / 1.5 sans-serif; +} +``` + +```css live-sample___writing-mode +.box { + border: 5px solid rebeccapurple; + background-color: lightgray; + padding: 40px; + margin: 40px; +} +``` + +{{EmbedLiveSample("writing-mode", "", "250px")}} + +<details> +<summary>Click here to show the solution</summary> + +You should use the `writing-mode` property with a value of `vertical-rl` for vertical right-to-left script: + +```css +.box { + border: 5px solid rebeccapurple; + background-color: lightgray; + padding: 40px; + margin: 40px; + writing-mode: vertical-rl; +} +``` + +</details> + +## Task 2 + +In this task, we want you to use logical properties to replace `width` and `height` in order to maintain the {{glossary("aspect ratio")}} of the box as it is turned vertically. + +Your final result should look like the image below: + +![Two boxes one horizontal the other vertical](mdn-writing-modes2.png) + +Try to update the code below to recreate the finished example: + +```html live-sample___logical-width-height +<div class="box">Horizontal.</div> +<div class="box vertical">Vertical.</div> +``` + +```css hidden live-sample___logical-width-height +body { + font: 1.2em / 1.5 sans-serif; +} +``` + +```css live-sample___logical-width-height +.box { + border: 5px solid rebeccapurple; + background-color: lightgray; + padding: 40px; + margin: 40px; + width: 200px; + height: 100px; +} +``` + +{{EmbedLiveSample("logical-width-height", "", "500px")}} + +<details> +<summary>Click here to show the solution</summary> + +As well as setting `writing-mode: vertical-rl` on the `.vertical` box, you need to apply the `inline-size` and `block-size` properties to replace `width` and `height`: + +```css +.box { + border: 5px solid rebeccapurple; + background-color: lightgray; + padding: 40px; + margin: 40px; + inline-size: 200px; + block-size: 100px; +} +.vertical { + writing-mode: vertical-rl; +} +``` + +</details> + +## Task 3 + +In this task, we want you to use logical versions of the margin, border, and padding properties so that the edges of the box relate to the text rather than following top, left, bottom and right. + +Your final result should look like the image below: + +![Two boxes one horizontal one vertical with different margin, border and padding](mdn-writing-modes3.png) + +Try to update the code below to recreate the finished example: + +```html live-sample___logical-mbp +<div class="box">Horizontal.</div> +<div class="box vertical">Vertical.</div> +``` + +```css hidden live-sample___logical-mbp +body { + font: 1.2em / 1.5 sans-serif; +} +``` + +```css hidden live-sample___logical-mbp +.vertical { + writing-mode: vertical-rl; +} +``` + +```css live-sample___logical-mbp +.box { + width: 150px; + height: 150px; + border-top: 5px solid rebeccapurple; + border-right: 5px solid grey; + border-bottom: 5px dotted red; + border-left: 5px dotted blue; + padding-top: 40px; + margin-bottom: 30px; +} +``` + +{{EmbedLiveSample("logical-mbp", "", "500px")}} + +<details> +<summary>Click here to show the solution</summary> + +To solve this, you need an understanding of the logical, flow relative mappings for margin, border and padding physical properties: + +```css +.box { + width: 150px; + height: 150px; + border-block-start: 5px solid rebeccapurple; + border-inline-end: 5px solid grey; + border-block-end: 5px dotted red; + border-inline-start: 5px dotted blue; + padding-block-start: 40px; + margin-block-end: 30px; +} +``` + +</details> + +## See also + +- [CSS styling basics](/en-US/docs/Learn_web_development/Core/Styling_basics) diff --git a/files/en-us/learn_web_development/core/styling_basics/writing_modes_tasks/mdn-writing-modes1.png b/files/en-us/learn_web_development/core/styling_basics/test_your_skills/writing_modes/mdn-writing-modes1.png similarity index 100% rename from files/en-us/learn_web_development/core/styling_basics/writing_modes_tasks/mdn-writing-modes1.png rename to files/en-us/learn_web_development/core/styling_basics/test_your_skills/writing_modes/mdn-writing-modes1.png diff --git a/files/en-us/learn_web_development/core/styling_basics/writing_modes_tasks/mdn-writing-modes2.png b/files/en-us/learn_web_development/core/styling_basics/test_your_skills/writing_modes/mdn-writing-modes2.png similarity index 100% rename from files/en-us/learn_web_development/core/styling_basics/writing_modes_tasks/mdn-writing-modes2.png rename to files/en-us/learn_web_development/core/styling_basics/test_your_skills/writing_modes/mdn-writing-modes2.png diff --git a/files/en-us/learn_web_development/core/styling_basics/writing_modes_tasks/mdn-writing-modes3.png b/files/en-us/learn_web_development/core/styling_basics/test_your_skills/writing_modes/mdn-writing-modes3.png similarity index 100% rename from files/en-us/learn_web_development/core/styling_basics/writing_modes_tasks/mdn-writing-modes3.png rename to files/en-us/learn_web_development/core/styling_basics/test_your_skills/writing_modes/mdn-writing-modes3.png diff --git a/files/en-us/learn_web_development/core/styling_basics/test_your_skills_backgrounds_and_borders/index.md b/files/en-us/learn_web_development/core/styling_basics/test_your_skills_backgrounds_and_borders/index.md deleted file mode 100644 index 56f4eac45816228..000000000000000 --- a/files/en-us/learn_web_development/core/styling_basics/test_your_skills_backgrounds_and_borders/index.md +++ /dev/null @@ -1,167 +0,0 @@ ---- -title: "Test your skills: Backgrounds and borders" -slug: Learn_web_development/Core/Styling_basics/Test_your_skills_backgrounds_and_borders -page-type: learn-module-assessment ---- - -{{learnsidebar}} - -The aim of this skill test is to assess whether you understand [backgrounds and borders of boxes in CSS](/en-US/docs/Learn_web_development/Core/Styling_basics/Backgrounds_and_borders). - -> [!NOTE] -> Click **"Play"** in the code blocks below to edit the examples in the MDN Playground. -> You can also copy the code (click the clipboard icon) and paste it into an online editor such as [CodePen](https://codepen.io/), [JSFiddle](https://jsfiddle.net/), or [Glitch](https://glitch.com/). -> If you get stuck, you can reach out to us in one of our [communication channels](/en-US/docs/MDN/Community/Communication_channels). - -## Task 1 - -In this task, we want you to add a background, border, and some basic styles to a page header: - -1. Give the box a 5px black solid border, with rounded corners of 10px. -2. Give the `<h2>` a semi-transparent black background color, and make the text white. -3. Add a background image and size it so that it covers the box. You can use the following image: - - ```plain - https://mdn.github.io/shared-assets/images/examples/balloons.jpg - ``` - -Your final result should look like the image below: - -![Images shows a box with a photograph background, rounded border and white text on a semi-transparent black background.](backgrounds-task1.png) - -Try to update the code below to recreate the finished example: - -```html live-sample___backgrounds1 -<div class="box"> - <h2>Backgrounds & Borders</h2> -</div> -``` - -```css hidden live-sample___backgrounds1 -body { - padding: 1em; - font: 1.2em / 1.5 sans-serif; -} -* { - box-sizing: border-box; -} -.box { - padding: 0.5em; -} -``` - -```css live-sample___backgrounds1 -.box { - /* Add styles here */ -} - -h2 { - /* Add styles here */ -} -``` - -{{EmbedLiveSample("backgrounds1", "", "200px")}} - -<details> -<summary>Click here to show the solution</summary> - -You should use `border`, `border-radius`, `background-image`, and `background-size` and understand how to use RGB colors to make a background color partly transparent: - -```css -.box { - border: 5px solid #000; - border-radius: 10px; - background-image: url(https://mdn.github.io/shared-assets/images/examples/balloons.jpg); - background-size: cover; -} - -h2 { - background-color: rgb(0 0 0 / 50%); - color: #fff; -} -``` - -</details> - -## Task 2 - -In this task, we want you to add background images, a border, and some other styling to a decorative box: - -1. Give the box a 5px lightblue border and round the top left corner 20px and the bottom right corner 40px. - -2. The heading uses the `star.png` image as a background image, with a single centered star on the left and a repeating pattern of stars on the right. - You can use the following image: - - ```plain - https://mdn.github.io/shared-assets/images/examples/star.png - ``` - -3. Make sure that the heading text does not overlay the image, and that it is centered — you will need to use techniques learned in previous lessons to achieve this. - -Your final result should look like the image below: - -![Images shows a box with a blue border rounded at the top left and bottom right corners. On the left of the text is a single star, on the right 3 stars.](backgrounds-task2.png) - -Try to update the code below to recreate the finished example: - -```html live-sample___backgrounds2 -<div class="box"> - <h2>Backgrounds & Borders</h2> -</div> -``` - -```css hidden live-sample___backgrounds2 -body { - padding: 1em; - font: 1.2em / 1.5 sans-serif; -} -* { - box-sizing: border-box; -} -.box { - width: 300px; - padding: 0.5em; -} -``` - -```css live-sample___backgrounds2 -.box { - /* Add styles here */ -} - -h2 { - /* Add styles here */ -} -``` - -{{EmbedLiveSample("backgrounds2", "", "220px")}} - -<details> -<summary>Click here to show the solution</summary> - -You need to add padding to the heading so that it doesn't overlay the star image - this links back to learning from the earlier [Box Model lesson](/en-US/docs/Learn_web_development/Core/Styling_basics/Box_model). -The text should be aligned with the `text-align` property: - -```css -.box { - border: 5px solid lightblue; - border-top-left-radius: 20px; - border-bottom-right-radius: 40px; -} - -h2 { - padding: 0 40px; - text-align: center; - background: - url(https://mdn.github.io/shared-assets/images/examples/star.png) no-repeat - left center, - url(https://mdn.github.io/shared-assets/images/examples/star.png) repeat-y - right center; -} -``` - -</details> - -## See also - -- [CSS styling basics](/en-US/docs/Learn_web_development/Core/Styling_basics) diff --git a/files/en-us/learn_web_development/core/styling_basics/values_and_units/index.md b/files/en-us/learn_web_development/core/styling_basics/values_and_units/index.md index 7695910a7d62718..132ede7d63ba95c 100644 --- a/files/en-us/learn_web_development/core/styling_basics/values_and_units/index.md +++ b/files/en-us/learn_web_development/core/styling_basics/values_and_units/index.md @@ -1,11 +1,11 @@ --- title: CSS values and units +short-title: Values and units slug: Learn_web_development/Core/Styling_basics/Values_and_units page-type: learn-module-chapter +sidebar: learnsidebar --- -{{LearnSidebar}} - {{PreviousMenuNext("Learn_web_development/Core/Styling_basics/Handling_conflicts", "Learn_web_development/Core/Styling_basics/Sizing", "Learn_web_development/Core/Styling_basics")}} CSS rules contain [declarations](/en-US/docs/Web/CSS/CSS_syntax/Syntax#css_declarations), which in turn are composed of properties and values. @@ -158,7 +158,7 @@ In this section we'll explore some of the most common relative units. In the example below, you can see how some relative and absolute length units behave. The first box has a {{cssxref("width")}} set in pixels. As an absolute unit, this width will remain the same no matter what else changes. -The second box has a width set in `vw` (viewport width) units. This value is relative to the viewport width, and so 10vw is 10 percent of the width of the viewport. If you change the width of your browser window, the size of the box should change. However this example is embedded into the page using an [`<iframe>`](/en-US/docs/Web/HTML/Element/iframe), so this won't work. To see this in action you'll have to [try the example after opening it in its own browser tab](https://mdn.github.io/css-examples/learn/values-units/length.html). +The second box has a width set in `vw` (viewport width) units. This value is relative to the viewport width, and so 10vw is 10 percent of the width of the viewport. If you change the width of your browser window, the size of the box should change. However this example is embedded into the page using an [`<iframe>`](/en-US/docs/Web/HTML/Reference/Elements/iframe), so this won't work. To see this in action you'll have to [try the example after opening it in its own browser tab](https://mdn.github.io/css-examples/learn/values-units/length.html). The third box uses `em` units. These are relative to the element's font size. I've set a font size of `1em` on the containing {{htmlelement("div")}}, which has a class of `.wrapper`. Change this value to `1.5em` and you will see that the font size of all the elements increases, but only the last item will get wider, as its width is relative to that font size. @@ -303,16 +303,24 @@ p { transparent 2px 1lh ); } + +.lh-2 { + line-height: 2em; +} + +.lh-4 { + line-height: 4em; +} ``` ```html -<p style="line-height: 2em"> +<p class="lh-2"> Summer is a time for adventure, and this year was no exception. I had many exciting experiences, but two of my favorites were my trip to the beach and my week at summer camp. </p> -<p style="line-height: 4em"> +<p class="lh-4"> At the beach, I spent my days swimming, collecting shells, and building sandcastles. I also went on a boat ride and saw dolphins swimming alongside us. @@ -444,7 +452,7 @@ You can mix and match color models, but it's usually best if your entire project ### Color keywords -You will see the color keywords (or 'named colors') used in many MDN code examples. As the [`<named-color>`s](/en-US/docs/Web/CSS/named-color) data type contains a very finite number of color values, these are not commonly used on production websites. As the keyword represents the color as a human-readable text value, named colors are used in code examples to clearly tell the user what color is expected so the learner can focus on the content being taught. +You will see the color keywords (or "named colors") used in many MDN code examples. Because the [`<named-color>`](/en-US/docs/Web/CSS/named-color) data type contains a very finite number of color values, they are not commonly used on production websites with a sophisticated design language. On the other hand, named colors are used in code examples to clearly tell the user what color is expected so the learner can focus on the content being taught. Try playing with different color values in the live examples below, to get more of an idea how they work: @@ -845,7 +853,7 @@ Knowing about CSS functions is useful so you recognize them when you see them. Y ## Test your skills! -You've reached the end of this article, but can you remember the most important information? You can find some further tests to verify that you've retained this information before you move on — see [Test your skills: Values and units](/en-US/docs/Learn_web_development/Core/Styling_basics/Values_tasks). +You've reached the end of this article, but can you remember the most important information? You can find some further tests to verify that you've retained this information before you move on — see [Test your skills: Values and units](/en-US/docs/Learn_web_development/Core/Styling_basics/Test_your_skills/Values). ## Summary diff --git a/files/en-us/learn_web_development/core/styling_basics/values_tasks/index.md b/files/en-us/learn_web_development/core/styling_basics/values_tasks/index.md deleted file mode 100644 index bdabf7bad553513..000000000000000 --- a/files/en-us/learn_web_development/core/styling_basics/values_tasks/index.md +++ /dev/null @@ -1,213 +0,0 @@ ---- -title: "Test your skills: Values and units" -slug: Learn_web_development/Core/Styling_basics/Values_tasks -page-type: learn-module-assessment ---- - -{{LearnSidebar}} - -The aim of this skill test is to assess whether you understand different types of [values and units used in CSS properties](/en-US/docs/Learn_web_development/Core/Styling_basics/Values_and_units). - -> [!NOTE] -> Click **"Play"** in the code blocks below to edit the examples in the MDN Playground. -> You can also copy the code (click the clipboard icon) and paste it into an online editor such as [CodePen](https://codepen.io/), [JSFiddle](https://jsfiddle.net/), or [Glitch](https://glitch.com/). -> If you get stuck, you can reach out to us in one of our [communication channels](/en-US/docs/MDN/Community/Communication_channels). - -## Task 1 - -In this task, the first list item has been given a background color using a hex color code. Your task is to complete the CSS using the same color in different formats, plus a final list item where you should make the background semi-opaque. - -- The second list item should use RGB color. -- The third should use HSL color. -- The fourth should use RGB color but with the alpha channel set to `0.6`. - -You [can convert the hex color at convertingcolors.com](https://convertingcolors.com/hex-color-86DEFA.html). You need to figure out how to use the values in CSS. Your final result should look like the image below: - -![Four list items. The first three with the same background color and the last with a lighter background.](mdn-value-color.png) - -Try to update the code below to recreate the finished example: - -```html live-sample___color -<ul> - <li class="hex">hex color</li> - <li class="rgb">RGB color</li> - <li class="hsl">HSL color</li> - <li class="transparency">Alpha value 0.6</li> -</ul> -``` - -```css hidden live-sample___color -body { - font: 1.2em / 1.5 sans-serif; -} -ul { - list-style: none; - margin: 0; - padding: 0; -} - -li { - margin: 1em; - padding: 0.5em; -} -``` - -```css live-sample___color -.hex { - background-color: #86defa; -} - -/* Add styles here */ -``` - -{{EmbedLiveSample("color", "", "300px")}} - -<details> -<summary>Click here to show the solution</summary> - -By using [a color conversion tool](https://convertingcolors.com/hex-color-86DEFA.html), you should be equipped to use different [color functions](/en-US/docs/Web/CSS/color_value#syntax) to define the same color in different ways: - -```css -.hex { - background-color: #86defa; -} - -.rgb { - background-color: rgb(134 222 250); -} - -.hsl { - background-color: hsl(194 92% 75%); -} - -.transparency { - background-color: rgb(134 222 250 / 60%); -} -``` - -</details> - -## Task 2 - -In this task, we want you to set the size of various items of text, as described below: - -- The `<h1>` element should be 50 pixels. -- The `<h2>` element should be 2em. -- All `<p>` elements should be 16 pixels. -- A `<p>` element that is directly after an `<h1>` should be 120%. - -Your final result should look like the image below: - -![Some text at varying sizes.](mdn-value-length.png) - -Try to update the code below to recreate the finished example: - -```html live-sample___length -<h1>Level 1 heading</h1> -<p> - Veggies es bonus vobis, proinde vos postulo essum magis kohlrabi welsh onion - daikon amaranth tatsoi tomatillo melon azuki bean garlic. -</p> -<h2>Level 2 heading</h2> -<p> - Gumbo beet greens corn soko endive gumbo gourd. Parsley shallot courgette - tatsoi pea sprouts fava bean collard greens dandelion okra wakame tomato. - Dandelion cucumber earthnut pea peanut soko zucchini. -</p> -``` - -```css hidden live-sample___length -body { - font: 1.2em / 1.5 sans-serif; -} -``` - -```css live-sample___length -h1 { -} - -h2 { -} - -p { -} - -h1 + p { -} -``` - -{{EmbedLiveSample("length", "", "420px")}} - -<details> -<summary>Click here to show the solution</summary> - -You can use the following length values: - -```css -h1 { - font-size: 50px; -} - -h2 { - font-size: 2em; -} - -p { - font-size: 16px; -} - -h1 + p { - font-size: 120%; -} -``` - -</details> - -## Task 3 - -In this task, we want you to move the background image so that it is centered horizontally and is 20% from the top of the box. - -Your final result should look like the image below: - -![A stat centered horizontally in a box and a short distance from the top of the box.](mdn-value-position.png) - -Try to update the code below to recreate the finished example: - -```html live-sample___position -<div class="box"></div> -``` - -```css hidden live-sample___position -.box { - border: 5px solid #000; - height: 350px; -} -``` - -```css live-sample___position -.box { - background-image: url(https://mdn.github.io/shared-assets/images/examples/purple-star.png); - background-repeat: no-repeat; -} -``` - -{{EmbedLiveSample("position", "", "400px")}} - -<details> -<summary>Click here to show the solution</summary> - -Use `background-position` with the `center` keyword and a percentage: - -```css -.box { - background-image: url(https://mdn.github.io/shared-assets/images/examples/purple-star.png); - background-repeat: no-repeat; - background-position: center 20%; -} -``` - -</details> - -## See also - -- [CSS styling basics](/en-US/docs/Learn_web_development/Core/Styling_basics) diff --git a/files/en-us/learn_web_development/core/styling_basics/what_is_css/index.md b/files/en-us/learn_web_development/core/styling_basics/what_is_css/index.md index e7ca7a0b43480d4..277ebce2c96400e 100644 --- a/files/en-us/learn_web_development/core/styling_basics/what_is_css/index.md +++ b/files/en-us/learn_web_development/core/styling_basics/what_is_css/index.md @@ -2,10 +2,9 @@ title: What is CSS? slug: Learn_web_development/Core/Styling_basics/What_is_CSS page-type: learn-module-chapter +sidebar: learnsidebar --- -{{LearnSidebar}} - {{NextMenu("Learn_web_development/Core/Styling_basics/Getting_started", "Learn_web_development/Core/Styling_basics")}} **{{Glossary("CSS")}}** (Cascading Style Sheets) allows you to create great-looking web pages, but how does it work under the hood? This article explains what CSS, what the basic syntax looks like, and how your browser applies CSS to HTML to style it. @@ -160,6 +159,8 @@ When the CSS is applied to the HTML, the rendered output is as follows: > 1. Add another paragraph of text below the two existing ones, and note how the second CSS rule is automatically applied to the new paragraph. > 2. Add an `<h2>` subheading somewhere below the `<h1>`, maybe after one of the paragraphs. Try giving it a different color by adding a new rule to the CSS. Make a copy of the `h1` rule, change the selector to `h2`, and change the `color` value from `red` to `purple`, for example. > 3. If you are feeling adventurous, try looking up some new CSS properties and values in the MDN [CSS reference](/en-US/docs/Web/CSS/Reference) to add to your rules! +> +> For some additional practice with CSS basics, see [Write your first lines of CSS!](https://scrimba.com/learn-html-and-css-c0p/~0j?via=mdn) from Scrimba <sup>[_MDN learning partner_](/en-US/docs/MDN/Writing_guidelines/Learning_content#partner_links_and_embeds)</sup>. This scrim gives a useful rundown of basic CSS syntax, and provides an interactive challenge where you can get some more practice with writing CSS declarations. ## Summary diff --git a/files/en-us/learn_web_development/core/styling_basics/what_is_css/rendering.svg b/files/en-us/learn_web_development/core/styling_basics/what_is_css/rendering.svg deleted file mode 100644 index d2cc2b525ed9c56..000000000000000 --- a/files/en-us/learn_web_development/core/styling_basics/what_is_css/rendering.svg +++ /dev/null @@ -1 +0,0 @@ -<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 635 245"><style>@font-face{font-family:&apos;open_sanssemibold&apos;;src:url(data:application/x-font-opentype;charset=utf-8;base64,AAEAAAATAQAABAAwRkZUTWfOXwkAAAE8AAAAHEdERUYAZgAEAAABWAAAACBHUE9TECH6YwAAAXgAAALSR1NVQpM8gksAAARMAAAAUE9TLzKhy73TAAAEnAAAAGBjbWFwpkuXDgAABPwAAAFiY3Z0IBPbDf4AAAZgAAAAOmZwZ21TtC+nAAAGnAAAAmVnYXNwAAAAEAAACQQAAAAIZ2x5ZgLNdmwAAAkMAAAgVGhlYWQKowZEAAApYAAAADZoaGVhD04FGwAAKZgAAAAkaG10eAUXFaoAACm8AAAA5GxvY2HTnN0QAAAqoAAAAHRtYXhwAVQBRAAAKxQAAAAgbmFtZWTusSEAACs0AAAE+nBvc3TOYv/WAAAwMAAAAKtwcmVwjm2IcAAAMNwAAADzd2ViZiE+Vh4AADHQAAAABgAAAAEAAAAAzD2izwAAAADJTOp9AAAAANJD0bwAAQAAAA4AAAAYAAAAAAACAAEAAQA4AAEABAAAAAIAAAABAAAACgBUAGIABERGTFQAGmN5cmwAJmdyZWsAMmxhdG4APgAEAAAAAP//AAEAAAAEAAAAAP//AAEAAAAEAAAAAP//AAEAAAAEAAAAAP//AAEAAAABa2VybgAIAAAAAQAAAAEABAACAAAAAQAIAAECLgAEAAAAGQA8AGIAgABiAJIAmACAAJ4AYgDEAGIA0gE0AToBOgCAAYQB0gHkAeQB+gHkAeQCEAH6AAkABv/XAAr/1wANAQoAEv/XABT/1wAX/3EAGf+uABr/rgAc/4UABwAE/9cAF//DABn/7AAa/+wAG//XABz/7AAd/+wABAAG/9cACv/XABL/1wAU/9cAAQANAHsAAQAE/9cACQAG/9cACv/XABL/1wAU/9cAF//XABj/7AAZ/9cAGv/XABz/wwADAAT/mgAb/9cAHf/sABgABP9xAAb/1wAK/9cAEv/XABT/1wAXACkAHv9cACD/cQAh/3EAIv9xACT/cQAq/5oAK/+aACz/cQAt/5oALv9xAC//mgAw/4UAMv+aADP/1wA0/9cANf/XADb/1wA3/64AAQAE/+wAEgAE/64ABv/sAAr/7AAS/+wAFP/sAB7/1wAg/9cAIf/XACL/1wAk/+wAKv/sACv/7AAs/9cALf/sAC7/1wAv/+wAMP/sADL/7AATAAT/hQAG/9cACv/XABL/1wAU/9cAHv+aACD/mgAh/5oAIv+aACT/1wAq/8MAK//DACz/mgAt/8MALv+aAC//wwAw/64AMv/DADf/1wAEAAb/7AAK/+wAEv/sABT/7AAFADP/1wA0/9cANf/XADb/1wA3/+wABQAg/9cAIf/XACL/1wAs/9cALv/XAAcAHv/XACD/1wAh/9cAIv/XACT/7AAs/9cALv/XAAEAGQAEAAUABgAHAAgACQAOAA8AEgATABQAFwAYABkAGgAbABwAHQAfACIAKAAsAC0ALwA1AAAAAQAAAAoATABOAARERkxUABpjeXJsACRncmVrAC5sYXRuADgABAAAAAD//wAAAAQAAAAA//8AAAAEAAAAAP//AAAABAAAAAD//wAAAAAAAAADBLECWAAFAAQFmgUzAAABHwWaBTMAAAPRAGYB9gAAAgsHBgMIBAICBOAAAu9AACBbAAAAKAAAAAAxQVNDACAADSX8Bmb+ZgAACGQCaiAAAZ8AAAAABFIFtgAAACAAAgAAAAMAAAADAAAAHAABAAAAAABcAAMAAQAAABwABABAAAAADAAIAAIABAANACAAWgB6Jfz//wAAAA0AIABBAGEl/P////X/4//D/73aPAABAAAAAAAAAAAAAAAAAAABBgAAAQAAAAAAAAABAgAAAAIAAAAAAAAAAAAAAAAAAAABAAADAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAEBQYHCAkKCwwNDg8QERITFBUWFxgZGhscHQAAAAAAAB4fICEiIyQlJicoKSorLC0uLzAxMjM0NTY3AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAEUgW2AM0AgwCXAKIAqgC0ALoAwADEAMgA2QEEAOsA6wDvAKwA4QDVANAA6ADkAKQAlAC3AEQFEQAAsAAssAATS7BMUFiwSnZZsAAjPxiwBitYPVlLsExQWH1ZINSwARMuGC2wASwg2rAMKy2wAixLUlhFI1khLbADLGkYILBAUFghsEBZLbAELLAGK1ghIyF6WN0bzVkbS1JYWP0b7VkbIyGwBStYsEZ2WVjdG81ZWVkYLbAFLA1cWi2wBiyxIgGIUFiwIIhcXBuwAFktsAcssSQBiFBYsECIXFwbsABZLbAILBIRIDkvLbAJLCB9sAYrWMQbzVkgsAMlSSMgsAQmSrAAUFiKZYphILAAUFg4GyEhWRuKimEgsABSWDgbISFZWRgtsAossAYrWCEQGxAhWS2wCywg0rAMKy2wDCwgL7AHK1xYICBHI0ZhaiBYIGRiOBshIVkbIVktsA0sEhEgIDkvIIogR4pGYSOKIIojSrAAUFgjsABSWLBAOBshWRsjsABQWLBAZTgbIVlZLbAOLLAGK1g91hghIRsg1opLUlggiiNJILAAVVg4GyEhWRshIVlZLbAPLCMg1iAvsAcrXFgjIFhLUxshsAFZWIqwBCZJI4ojIIpJiiNhOBshISEhWRshISEhIVktsBAsINqwEistsBEsINKwEistsBIsIC+wBytcWCAgRyNGYWqKIEcjRiNhamAgWCBkYjgbISFZGyEhWS2wEywgiiCKhyCwAyVKZCOKB7AgUFg8G8BZLbAULLMAQAFAQkIBS7gQAGMAS7gQAGMgiiCKVVggiiCKUlgjYiCwACNCG2IgsAEjQlkgsEBSWLIAIABDY0KyASABQ2NCsCBjsBllHCFZGyEhWS2wFSywAUNjI7AAQ2MjLQAAAAABAAH//wAPAAIARAAAAmQFVQADAAcALrEBAC88sgcEG+0ysQYF3DyyAwIb7TIAsQMALzyyBQQb7TKyBwYc/DyyAQIb7TIzESERJSERIUQCIP4kAZj+aAVV+qtEBM0AAAACAAAAAAVKBbwABwAPACwAsgAAACuwAzOyAQIAK7QGCAABDSuxBgPpAbAQL7ERASsAsQEIERKwDTkwMTEBIQEjAyEDEyEDLgEnBgcCIwEEAiP+kv3Rj9UBqokPNQobNAW8+kQBlv5qAmQBjiisKHuSAAAAAAMAwQAABNkFtgAPABgAIQBnALIAAAArsRAM6bICAgArsSEM6bQZGAACDSuxGQrpAbAiL7AA1rEQEemwGTKwEBCxFAErsQwR6bAdINYRsQUR6bEjASuxHRARErEJCDk5ALEYEBESsAw5sBkRsQgJOTmwIRKwBTkwMTMRISAEFRQGBxUeARUUBCMlMzI2NTQmKwE1MzI2NTQmKwHBAbIBLgENhHyakf7t9f7f/paZnJ/y5paKlaLPBbawvoCqFgodq5LF38lzfHJuwl9yZ1wAAAABAHn/7ATPBcsAGAA9ALIWAAArsRAD6bIEAgArsQoD6QGwGS+wANaxDRHpsRoBKwCxEBYRErAUObAKEbIABxM5OTmwBBKwBjkwMRM0EiQzMhcHLgEjIgIREBIzMjY3FQYjIAB5pwE81eC+VkqlW87s49ddrl6s2v6//qgC2+QBVrZexyM1/tz+//7z/uwlHc1BAYUAAgDBAAAFZgW2AAgADwA4ALIIAAArsQkM6bICAgArsQ8M6QGwEC+wANaxCRHpsAkQsQwBK7EFEemxEQErALEPCRESsAU5MDEzESEgABEQACEnMyARECEjwQHEAV0BhP5u/oaqqgIQ/hXPBbb+iP6r/pb+gckCGAINAAAAAAEAwQAAA/wFtgALAEcAsgAAACuxCQPpsgECACuxBAzptAUIAAENK7EFDOkBsAwvsADWsQkR6bAEMrIJAAors0AJCwkrsAIys0AJBwkrsQ0BKwAwMTMRIRUhESEVIREhFcEDO/20Aif92QJMBbbK/nLI/jXLAAAAAAEAwQAAA/oFtgAJAEAAsgAAACuyAQIAK7EEDOm0CAUAAQ0rsQgD6QGwCi+wANaxCQ/psAQysgkACiuzQAkDCSuzQAkHCSuxCwErADAxMxEhFSERIRUhEcEDOf20Aif92QW2yv43y/2oAAAAAAEAef/sBTEFywAaAHgAshgAACuxDgzpsgMCACuxCAPptBITGAMNK7ESA+kBsBsvsADWsQsR6bALELEQASuxFQ/pshAVCiuzQBASCSuxHAErsRALERKyAwgYOTk5sBURsQYFOTkAsQ4YERKwFTmxExIRErEACzk5sAgRsAY5sAMSsAU5MDETEAAhMhcHJiMiABUQEjMyNxEhNSERDgEjIAB5AZYBZOXNVLKy6v7w9eZ0hP7RAhqE843+tP6YAtsBYQGPWMdS/tr//vT+6R0Bec39IiskAYkAAAEAwQAABUIFtgALAD8AsgAAACuwBzOyAQIAK7AFM7QDCgABDSuxAwPpAbAML7AA1rELEemwAjKwCxCxCAErsAQysQcR6bENASsAMDEzETMRIREzESMRIRHB7wKi8PD9XgW2/aoCVvpKApP9bQAAAAABAMEAAAGwBbYAAwAhALIAAAArsgECACsBsAQvsADWsQMR6bEDEemxBQErADAxMxEzEcHvBbb6SgAAAAAB/2T+aAGqBbYADAAtALIFAgArsAovsQID6QGwDS+wBNaxBxHpsQ4BKwCxAgoRErAMObAFEbAAOTAxBxYzMjURMxEUBiMiJ5xUPsTw1c1iQrYV+AWJ+n/g7RkAAAEAwQAABR0FtgAOADAAsgAAACuwCjOyAQIAK7AGMwGwDy+wANaxDhHpsAIysRABKwCxAQARErEDDDk5MDEzETMRNjcBIQAHASEBBxHB72JhAYsBEP6BpgI0/uv+NY0Ftv1GeG8B0/4+v/zLApZz/d0AAAAAAQDBAAAEGwW2AAUALACyAAAAK7EDA+myAQIAKwGwBi+wANaxAxHpsgMACiuzQAMFCSuxBwErADAxMxEzESEVwe8CawW2+xfNAAAAAAEAwQAABqIFtgAUAF4AsgAAACuxBw4zM7IBAgArsAUzAbAVL7AA1rEUD+m0EQ8AKAQrsBQQsQgBK7EHD+mxFgErsRQRERKwEDmwCBGzAgUODyQXObAHErEMDTk5ALEBABESsgMMEDk5OTAxMxEhATMBIREjETQSNyMBIwEjEhURwQFRAZYGAaIBUuYLBAj+SdP+WAgRBbb7dQSL+koC020BXiX7PQTF/vDu/TkAAAAAAQDBAAAFgwW2ABEAUgCyAAAAK7AKM7IBAgArsAgzAbASL7AA1rERD+mwERCxBwErsQoP6bETASuxEQARErEMDTk5sAcRsQILOTmwChKxAwQ5OQCxAQARErEDDDk5MDEzESEBMyYCNREzESEBIxcWFRHBASICzQYCDNv+2/0xCAUOBbb7eRcBIVEC/vpKBI1Bupr9CAAAAAACAHn/7AXTBc0ACwAXAEQAsgkAACuxDwPpsgMCACuxFQPpAbAYL7AA1rEMEemwDBCxEgErsQYR6bEZASuxEgwRErEDCTk5ALEVDxESsQAGOTkwMRMQACEgABEQACEgABMQEjMyEhEQAiMiAnkBZQFLAUYBZP6b/rn+tf6d/trW1dnX1dfbAt8BagGE/nb+mv6b/nQBiQFo/vL+6QEUAREBDQEW/uoAAAACAMEAAASJBbYACgATAEIAsgAAACuyAgIAK7ETDOm0CQsAAg0rsQkM6QGwFC+wANaxChHpsAsysAoQsQ8BK7EFEemxFQErALETCxESsAU5MDEzESEgBBUUBCEjGQEzMjY1NCYrAcEBpQESARH+1P7rmH+4rJqjpgW24Nrl9P3dAuyAiH58AAAAAgB5/qQF0wXNAA8AGwBTALINAAArsRMD6bIDAgArsRkD6QGwHC+wANaxEBHpsBAQsRYBK7EGEemxHQErsRYQERKzAwsMCSQXObAGEbAKOQCxEw0RErAJObAZEbEABjk5MDETEAAhIAAREAIHASEBIyAAExASMzISERACIyICeQFlAUsBRgFky8IBXv6+/uwn/rX+nf7a1tXZ19XX2wLfAWoBhP52/pr+9v6USv6HAUgBiQFo/vL+6QEUAREBDQEW/uoAAAIAwQAABQoFtgAMABUAWwCyAAAAK7AIM7ICAgArsRUM6bQLDQACDSuxCwvpAbAWL7AA1rEMEemwDTKwDBCxEQErsQUR6bEXASuxEQwRErEKBzk5sAURsAk5ALENCxESsAc5sBURsAU5MDEzESEgBBUQBQEhASMZATMyNjU0JisBwQGdARsBEP7kAZ3+8P6i7KanlqKjngW21Nb+73T9eQJI/bgDDnx6fGwAAAABAGT/7AQMBcsAJABoALIjAAArsQQM6bIQAgArsRUD6QGwJS+wDdaxGA/psBgQsQcBK7EgD+mxJgErsRgNERKwCzmwBxG1BAoQFRwjJBc5sCASshITHTk5OQCxBCMRErAAObAVEbMBDRMgJBc5sBASsBI5MDE3NR4BMzI2NTQmJy4BNTQkMzIXByYjIgYVFB4BFx4CFRQEIyJkZOFhjod8wsikAQTb0tBMw5l0eDBuj6GWRv7m+Pg54i82bFtSck5R0JK30lzDUmVTOVFIO0N0kmPD3gAAAAABAB0AAARoBbYABwA6ALIGAAArsgECACuxAAPpsAMyAbAIL7AG1rEFEemyBQYKK7NABQMJK7IGBQors0AGAAkrsQkBKwAwMRM1IRUhESMRHQRL/lLvBOnNzfsXBOkAAAABALT/7AU7BbYAEQA3ALIPAAArsQYD6bIBAgArsAkzAbASL7AA1rEDEemwAxCxCAErsQsR6bETASuxCAMRErAPOQAwMRMRMxEUFjMgGQEzERQGBCMgALTwqK4BUu+L/vm3/vD+0gIIA678Y7WsAWMDm/xOovODASAAAAAAAQAAAAAE+gW2AAwAIQCyDAAAK7IAAgArsAkzAbANL7EOASsAsQAMERKwBTkwMREzAR4BFz4BNwEzASP2ATEYNggNNhEBMfj+APwFtvxzQc0yTMgwA4n6SgAAAAABAAwAAAeDBbYAHAD8ALIbAAArsBEzsgACACuzAQgJDyQXMwGwHS+wANaxARHpsAEQsQ8BK7EQEemxHgErsDYausHY8MEAFSsKDrAAELAcwLABELACwLo+APAfABUrCgWwCC4OsAfAsRcU+bAZwLrCce5+ABUrCgWwCS4OsArAsRUV+bATwLMUFRMTK7o+SfFJABUrC7AZELMYGRcTK7IYGRcgiiCKIwYOERI5shQVEyCKIIojBg4REjkAQAoCBwoTGRwUFRcYLi4uLi4uLi4uLgFADAIHCAkKExkcFBUXGC4uLi4uLi4uLi4uLrBAGgGxDwERErERGzk5ALEAGxESsgQMFjk5OTAxEzMTFhc+ATcTMxMWFzY3EzMBIQMuAScOAQcDIQMM9NExFQssEu7t9CMnDznQ8v6D/vz4EDAFCi0P8v78vQW2/KzNnVXSQQNW/KZ37Y/dA1L6SgNoOdcqQMwy/JwC3AABAAQAAAT2BbYACwAmALIAAAArsAgzsgICACuwBTMBsAwvsQ0BKwCxAgARErEECjk5MDEzCQEhCQEhCQEhCQEEAeX+OgEKAVIBUgEC/jcB7P7t/pL+jwL2AsD91wIp/Tz9DgJW/aoAAAEAAAAABLwFtgAIADAAsgcAACuyAAIAK7ADMwGwCS+wB9axBhHpsQoBK7EGBxESsAI5ALEABxESsAI5MDERIQkBIQERIxEBBAFaAVoBBP4Z8AW2/WUCm/yB/ckCLwAAAAEAQgAABFgFtgAJAC4AsgAAACuxBwPpsgQCACuxAwPpAbAKL7ELASsAsQcAERKwATmxBAMRErAGOTAxMzUBITUhFQEhFUIC4f0zA+79HAL4pgRDzaj7v80AAAAAAgBa/+wEBARmABsAJgB/ALIUAAArshkAACuxHwjpsg8BACuxCAjptAMkGQ8NK7EDBekBsCcvsADWsRwR6bAcELEiASuwBDKxEg/psSgBK7EcABESsQsMOTmwIhGyDxkIOTk5sBISsBY5ALEfFBESsRUWOTmwJBGwADmwAxKwAjmwCBGwCzmwDxKwDDkwMRM0NiU3NTQmIyIGByc+ATMyFhURIycjDgEjIiY3FBYzMjY9AQcOAVr+AQS/Y2hVnEhMWtZf09eoLwhQon+jt/RYWICbjqaXAT2rrggGO2ppMiKoLzG4xf0XmmVJsJ9KUY+BYAYGYwAAAAACAKj/7ASTBhQAEwAfAGMAsgAAACuyDwAAK7EXCumyCQEAK7EcCumwAS8BsCAvsADWsRQP6bACMrAUELEaASuxDBHpsSEBK7EUABESsgYHETk5ObAaEbEJDzk5ALEXABESsBE5sBwRsAw5sAkSsAY5MDEzETMRFAYHMzYzMhIREAIjIicjBxMUFjMyNjUQISIGB6jrCAIKcNrP5+rQ0nQQKzuAkX2B/v6OfQIGFP6OKaIWpf7U/vH+8P7Rl4MCK8q1xrsBeafEAAEAZv/sA7QEZgAVAD0AshMAACuxDQvpsgMBACuxCAvpAbAWL7AA1rEKEemxFwErALENExESsBA5sAgRsgAGDzk5ObADErAFOTAxExAAITIXByYjIBEUFjMyNxUOASMiAGYBEQECr4xHlWH+4Y+KnYw/j2b7/vsCIwEXASxBvTr+g7q7Ts0lIAElAAAAAgBm/+wEVAYUABIAHwBrALIMAAArshAAACuxFgrpsgMBACuxHQrpsAkvAbAgL7AA1rETEemwExCxCAErsBkysQoP6bEhASuxCBMRErQDDhAWHSQXObAKEbIFBhg5OTkAsRYMERKxDQ45ObAdEbAAObADErEFBjk5MDETEBIzMhczJjURMxEjJyMGIyICExQWMzI2NzU0JiMiBmbr0NpyDBHsuCkLcdrP6PKCgpGEAoiRfIYCJwEQAS+hd0UBk/nskaUBLAELuMGjtyHRsMkAAAIAZv/sBDkEZgAUABsAZgCyEgAAK7ELCemyAwEAK7EZCOm0FQgSAw0rsRUH6QGwHC+wANaxCBHpsBUysAgQsRYBK7EGD+mxHQErsRYIERKyAwsSOTk5sAYRsQ4POTkAsQsSERKwDzmwCBGwDjmwFRKwADkwMRMQADMyEh0BIR4BMzI2NxUOASMgABMhLgEjIgZmAQ7s2/79HwWklWKpYVawcf7+/t32AfYCgHBwhwIhAQ8BNv726X+hrSUrvykiAS0BhYmNjgAAAQAjAAADQgYfABUAYACyFAAAK7IPAQArsRII6bAAMrICAQArsAsvsQYK6QGwFi+wFNawAjKxEw/psA4yshMUCiuzQBMRCSuyFBMKK7NAFAAJK7EXASsAsQ8SERKwATmwCxGwCTmwBhKwCDkwMRM1NzU0NjMyFwcmIyIGHQEhFSERIxEjtri9fHg+V09QSQEO/vLsA6BuSEjEvSmyHGNjSLL8YAOgAAAAAwAX/hQETgRmACsAOABDAMQAshIBACuxQQTpsBQysg8BACuxQQXpsCkvsS8G6bA2L7EiDOmwGy+xPAXpAbBEL7AM1rE5D+mwACDWEbQsDwAwBCuwORCwHyDWEbQGDwAfBCuwBi+0Hw8AHwQrsDkQsT4BK7EYD+mzMhg+CCuxJg/psUUBK7E5LBESsQkDOTmxPh8RErcSGw8jKS88QSQXObEYMhESsBU5ALE2LxESsSYAOTmwIhGwAzmwGxKxBh85ObA8EbEJHTk5sEESshUYDDk5OTAxFzQ2Ny4BNTQ2Ny4BNTQ2MzIWFyEVBx4BFRQGIyInBhUUFjsBMhYVFAQhIiY3FBYzMjY1NCYrASIGExQWMzI1NCYjIgYXgXQvPUZFVmvj0i9nGgF/vRoi7M81K0xHX8G3vv7K/tvi7tKJfMC8Z4yyZXdla2TMZWdmabhmixsUWTE+Violp3C0xg0HgSMjZjmrxAgvPyYmnJO8zKCgTFJuW0g9XwNHaHDabHV0AAAAAAEAqAAABHUGFAAVAE0AsgAAACuwDDOyCQEAK7ERCumwAS8BsBYvsADWsRUP6bACMrAVELENASuxDA/psRcBK7EVABESsAU5sA0RsQYJOTkAsQkRERKwBTkwMTMRMxEUBzM+ATMgGQEjETQmIyIGFRGo6wwPMKtyAZLsZ3CUiwYU/nVfbFBY/mv9LwKogH6x0P3bAAACAJoAAAGiBfoACwAPADkAsgwAACuyDQEAK7AJL7EDDukBsBAvsADWsAwysQYR6bEPD+mxBhHpsREBK7EPABESsQMJOTkAMDETNDYzMhYVFAYjIiYTETMRmkVAPkVFPkBFDusFdz9ERD88RUX6xQRS+64AAAL/h/4UAaIF+gAMABgARQCyBQEAK7AKL7ECCumwFi+xEA7pAbAZL7AE1rANMrEHD+mxExHpsRoBK7EHBBESsRAWOTkAsQIKERKwDDmwBRGwADkwMQMWMzI1ETMRFAYjIicBNDYzMhYVFAYjIiZ5REeW67OpakYBE0VAPkVFPkBF/ucSqgTT+x2rsBkHSj9ERD88RUUAAAAAAQCoAAAEiQYUAA4AOgCyAAAAK7AKM7IHAQArsAEvAbAPL7AA1rEOD+mwAjKxEAErsQ4AERKxBAU5OQCxBwARErEEDDk5MDEzETMRBzM3ASEJASEBBxGo6QwGhQFOAQ/+QwHZ/uz+nYEGFP0J1aYBZP4l/YkB5Wr+hQAAAAEAqAAAAZMGFAADAB8AsgAAACuwAS8BsAQvsADWsQMP6bEDD+mxBQErADAxMxEzEajrBhT57AAAAQCoAAAHBgRmACMAcACyAAAAK7ERGjMzsgEBACuyBwEAK7ANM7EfCumwFjIBsCQvsADWsSMP6bAjELEbASuxGg/psBoQsRIBK7ERD+mxJQErsSMAERKwBDmwGxGwBzmwGhKxCgk5ObASEbANOQCxAR8RErMDBAkKJBc5MDEzETMXMz4BMyAXMz4BMzIWFREjETQmIyIGFREjETQmIyIGFRGouCEMLq9pAP9TEDGyc8a162FmiX/sYGaIfwRSkU9WrlJcyM39LwKqf32rsf22Aqp/fbHO/dkAAQCoAAAEdQRmABMATACyAAAAK7AKM7IBAQArsgcBACuxDwrpAbAUL7AA1rETD+mwExCxCwErsQoP6bEVASuxEwARErAEObALEbAHOQCxAQ8RErEDBDk5MDEzETMXMz4BMyAZASMRNCYjIgYVEai4IQwyuHABjuxncJWKBFKRT1b+a/0vAqiAfrDP/dkAAAAAAgBm/+wEfQRmAAwAFQBEALIJAAArsQ8K6bIDAQArsRMK6QGwFi+wANaxDRHpsA0QsREBK7EGEemxFwErsRENERKxAwk5OQCxEw8RErEGADk5MDETEAAzMgAREAAjIiYCNxAhIBEQISIGZgEU+/ABGP7q+JvugPIBGwEY/uaUhQIrAQ0BLv7L/vr+8f7QjAEGrf6BAX8Be8QAAAAAAgCo/hQEkwRmABMAIABuALINAAArsRcK6bIBAQArsgcBACuxHQrpsAAvAbAhL7AA1rETD+mwFDK0Ag8AHwQrsBMQsRoBK7EKEemxIgErsRMCERKyBQ8QOTk5sBoRsQcNOTkAsRcNERKxDxA5ObAdEbAKObABErEEBTk5MDETETMWFzM2MzISERACIyInIxYVGQEUFjMyNjU0JiMiBhWovggZDG7cz+frz9J0Dg6AkXqEg3+Mgf4UBj4fdaj+1P7x/vH+0JeMHv47BBfKtci5ur+ktAACAGb+FARUBGYAFAAgAHIAshIAACuxFwnpsggBACuyAwEAK7EeCumwCy8BsCEvsADWsRUR6bAVELELASuwGjKxCg/psAoQtAgPAB8EK7AIL7EiASuxCxURErQDEBIXHiQXObAIEbEGDzk5ALEXEhESsA85sB4RsAA5sAgSsAY5MDETEBIzMhYXMzczESMRNDY3IwYjIgITECEyNj0BNCYjIgZm7M9opUEIGsPsCAMNaOPN6PIBBpSBhZR+hAInAQ4BMU1YkfnCAdUsYhqlAS0BCv6Fq60lzbTIAAAAAQCoAAADTgRmABAAPwCyAAAAK7IBAQArsgcBACuxDA3pAbARL7AA1rEQD+m0Ag8AFgQrsRIBK7EQAhESsAQ5ALEBDBESsQMEOTkwMTMRMxczPgEzMhcHJiMiBhURqLgfDDexZkcuFzI2ja8EUsNjdArbDLiT/b4AAQBi/+wDjwRmACEAawCyFAAAK7EZCOmyAwEAK7EICOkBsCIvsADWsBYysQoP6bAKELEbASuxEQ/psSMBK7EKABESsCA5sBsRtQMIDRQZHyQXObARErIGDgU5OTkAsRkUERKwFjmwCBGzAAYRFyQXObADErAFOTAxEzQ2MzIXByYjIhUUFhceAhUUBiMiJzUWMzI1NC4BJy4BYuXFw65Ms3q6YaOJfDzs3N2Gw6jZMG5iv4cDO46dT7FKajRIPzVYc1CirUPLWoMqODwmSpQAAAEAJ//sAvAFSAAVAHAAshIAACuxDArpsgUBACuxCAjpsAAysgUICiuzQAUDCSuyAgEAKwGwFi+wFNaxCQ/psAQysgkUCiuzQAkHCSuwDjKyFAkKK7NAFAAJK7EXASuxCRQRErACOQCxDBIRErAPObAIEbAOObAFErABOTAxEzU/ATMVIRUhERQWMzI3FQ4BIyAZASeiUJEBO/7FVUVWVid7Qv6yA6BoVur2sv2wVVEbsREXAWACVAABAJ7/7ARtBFIAFABMALINAAArshIAACuxBgrpsgEBACuwCjMBsBUvsADWsQMP6bADELEJASuxCw/psRYBK7EJAxESsBI5sAsRsA85ALEGDRESsQ4POTkwMRMRMxEUFjMyNjURMxEjJyMOASMiJp7taG+Ui+y5IQwxtXTJxgF/AtP9Vn9/sdACJ/uukU1YyAABAAAAAARIBFIACwAhALILAAArsgABACuwCDMBsAwvsQ0BKwCxAAsRErAEOTAxETMTFhczNjcTMwEj+OE6DAgJPeH6/lr+BFL9faJkSL4Cg/uuAAABABQAAAZzBFIAHQC5ALIdAAArsBQzsgABACuyAQoSMzMzAbAeL7AA1rEBEemwARCxEgErsRMP6bEfASuwNhq6wgrv+AAVKwqwABCwHcAOsAEQsALAusJf7r0AFSsKBbAKLg6wDcCxGAr5sBbAsAoQswsKDRMrswwKDRMrsgsKDSCKIIojBg4REjmwDDkAtQILFhgMDS4uLi4uLgG3AgoLFhgdDA0uLi4uLi4uLrBAGgGxEgERErAUOQCxAB0RErEEDjk5MDETMxMWFzM+ATcTIRMeARczNjcTMwEhAyYDIwIHAyEU8I0wFAYKKQ+oAQKjDy0ECA83j+z+yP74jxpECToik/78BFL938qQSb0vAkb9ujHKOHvdAiH7rgIEUgEr/vJx/f4AAAEAGQAABE4EUgALACYAsgAAACuwCDOyAgEAK7AFMwGwDC+xDQErALECABESsQQKOTkwMTMJASEbASEJASEJARkBhf6NAQz8/gEK/owBh/72/u/+8AI1Ah3+fQGD/eP9ywGe/mIAAAAAAQAA/hQESgRSABQAKwCyAAEAK7AIM7AML7ERCukBsBUvsRYBKwCxEQwRErAOObAAEbEEDzk5MDERIRMWFzM+ARMzAQIhIic1FjMyPwEBAOEzEQgJMOb+/ieB/tNOSjVEqkUpBFL9jYZ2N50Cm/sb/qcRugzFaAAAAQBEAAADiwRSAAkALgCyAAAAK7EHCOmyBAEAK7EDCOkBsAovsQsBKwCxBwARErABObEEAxESsAY5MDEzNQEhNSEVASEVRAIv/fMDFf3dAjORAw20pP0GtAAAAAABAAAAAARRBFEAAwAnALIAAAArsgEBACsBsAQvsADWtAMRAAcEK7QDEQAHBCuxBQErADAxMREhEQRRBFH7rwAAAQAAAAEZmkZDfmNfDzz1AB8IAAAAAADSQ9G9AAAAANJD0b3/ZP4UB4MGHwABAAgAAgAAAAAAAAABAAAIZP2WAAAHpv9k/6UHgwABAAAAAAAAAAAAAAAAAAAAOQLsAEQAAAAABBQAAAIUAAAFSgAABUgAwQUSAHkF3wDBBHcAwQRCAMEFzwB5BgIAwQJxAMECZP9kBR0AwQRWAMEHYgDBBkQAwQZMAHkE7ADBBkwAeQUdAMEEZgBkBIcAHQXwALQE+gAAB5EADAT6AAQEvAAABJoAQgSkAFoE/ACoA/YAZgT8AGYEnABmAucAIwRzABcFFACoAjsAmgI7/4cEkwCoAjsAqAemAKgFFACoBOMAZgT8AKgE/ABmA3MAqAPlAGIDJQAnBRQAngRIAAAGiQAUBGgAGQRKAAAD0wBEBFEAAAAAACwALAAsACwAZgDOARgBVgGSAcgCNAJsAooCuALyAxgDcAO8BBAEVAS2BQwFeAWoBeYGFAbIBvwHLAdaB9YIOgiACOgJTAmgCmIKrArmCzILcAuMC/gMQAyODPgNZg2iDgoOZg6uDtgPbA+gD9wQChAqAAEAAAA5AEQAAwAAAAAAAgABAAIAFgAAAQAA/AAAAAAAAAAUAPYAAwABBAkAAABoAAAAAwABBAkAAQAkAGgAAwABBAkAAgAOAIwAAwABBAkAAwBOAJoAAwABBAkABAA0AOgAAwABBAkABQAYARwAAwABBAkABgAiATQAAwABBAkABwCkAVYAAwABBAkACAAoAfoAAwABBAkACwA4AiIAAwABBAkADABcAloAAwABBAkADQBcArYAAwABBAkADgBUAxIAAwABBAkAEAASA2YAAwABBAkAEQAQA3gAAwABBAkAyAAWA4gAAwABBAkAyQAwA54AAwABBAkAygAOA84AAwABBAkAywAOA9wAAwABBAnZAwAaA+oARABpAGcAaQB0AGkAegBlAGQAIABkAGEAdABhACAAYwBvAHAAeQByAGkAZwBoAHQAIACpACAAMgAwADEAMQAsACAARwBvAG8AZwBsAGUAIABDAG8AcgBwAG8AcgBhAHQAaQBvAG4ALgBPAHAAZQBuACAAUwBhAG4AcwAgAFMAZQBtAGkAYgBvAGwAZABSAGUAZwB1AGwAYQByAEEAcwBjAGUAbgBkAGUAcgAgAC0AIABPAHAAZQBuACAAUwBhAG4AcwAgAFMAZQBtAGkAYgBvAGwAZAAgAEIAdQBpAGwAZAAgADEAMAAwAE8AcABlAG4AIABTAGEAbgBzACAAUwBlAG0AaQBiAG8AbABkACAAUgBlAGcAdQBsAGEAcgBWAGUAcgBzAGkAbwBuACAAMQAuADEAMABPAHAAZQBuAFMAYQBuAHMALQBTAGUAbQBpAGIAbwBsAGQATwBwAGUAbgAgAFMAYQBuAHMAIABpAHMAIABhACAAdAByAGEAZABlAG0AYQByAGsAIABvAGYAIABHAG8AbwBnAGwAZQAgAGEAbgBkACAAbQBhAHkAIABiAGUAIAByAGUAZwBpAHMAdABlAHIAZQBkACAAaQBuACAAYwBlAHIAdABhAGkAbgAgAGoAdQByAGkAcwBkAGkAYwB0AGkAbwBuAHMALgBBAHMAYwBlAG4AZABlAHIAIABDAG8AcgBwAG8AcgBhAHQAaQBvAG4AaAB0AHQAcAA6AC8ALwB3AHcAdwAuAGEAcwBjAGUAbgBkAGUAcgBjAG8AcgBwAC4AYwBvAG0ALwBoAHQAdABwADoALwAvAHcAdwB3AC4AYQBzAGMAZQBuAGQAZQByAGMAbwByAHAALgBjAG8AbQAvAHQAeQBwAGUAZABlAHMAaQBnAG4AZQByAHMALgBoAHQAbQBsAEwAaQBjAGUAbgBzAGUAZAAgAHUAbgBkAGUAcgAgAHQAaABlACAAQQBwAGEAYwBoAGUAIABMAGkAYwBlAG4AcwBlACwAIABWAGUAcgBzAGkAbwBuACAAMgAuADAAaAB0AHQAcAA6AC8ALwB3AHcAdwAuAGEAcABhAGMAaABlAC4AbwByAGcALwBsAGkAYwBlAG4AcwBlAHMALwBMAEkAQwBFAE4AUwBFAC0AMgAuADAATwBwAGUAbgAgAFMAYQBuAHMAUwBlAG0AaQBiAG8AbABkAFcAZQBiAGYAbwBuAHQAIAAxAC4AMABXAGUAZAAgAE8AYwB0ACAAMQA0ACAAMAA1ADoAMwAyADoANAA1ACAAMgAwADEANQBkAGUAZgBhAHUAbAB0AHAAZQByAHMAZQB1AHMARgBvAG4AdAAgAFMAcQB1AGkAcgByAGUAbAAAAAIAAAAAAAD/ZgBmAAAAAAAAAAAAAAAAAAAAAAAAAAAAOQAAAQIBAwADACQAJQAmACcAKAApACoAKwAsAC0ALgAvADAAMQAyADMANAA1ADYANwA4ADkAOgA7ADwAPQBEAEUARgBHAEgASQBKAEsATABNAE4ATwBQAFEAUgBTAFQAVQBWAFcAWABZAFoAWwBcAF0BBAZnbHlwaDEHdW5pMDAwRAd1bmkyNUZDALgB/4WwAY0AS7AIUFixAQGOWbFGBitYIbAQWUuwFFJYIbCAWR2wBitcWACwAyBFsAMrRLAMIEWyA9cCK7ADK0SwCyBFsgxzAiuwAytEsAogRbILVQIrsAMrRLAJIEWyCjcCK7ADK0SwCCBFsgktAiuwAytEsAcgRbIIIwIrsAMrRLAGIEWyBxkCK7ADK0SwBSBFsgZfAiuwAytEsAQgRbIFDwIrsAMrRLANIEWyA2gCK7ADK0SwDiBFsg0YAiuwAytEAbAPIEWwAytEsBAgRboAD3//AAIrsQNGditEsBEgRboAEAEbAAIrsQNGditEWbAUKwAAAVYeIT0AAA==) format(&apos;truetype&apos;);font-weight:400;font-style:normal}@font-face{font-family:&apos;open_sansbold&apos;;src:url(data:application/x-font-opentype;charset=utf-8;base64,AAEAAAATAQAABAAwRkZUTWfDjC0AAAE8AAAAHEdERUYAZgAEAAABWAAAACBHUE9TECH6YwAAAXgAAALSR1NVQpM8gksAAARMAAAAUE9TLzKiSMcwAAAEnAAAAGBjbWFwpkuXDgAABPwAAAFiY3Z0IA7uE6oAAAZgAAAAMGZwZ21TtC+nAAAGkAAAAmVnYXNwAAAAEAAACPgAAAAIZ2x5Zgv3uGQAAAkAAAAg/GhlYWQK4AZGAAAp/AAAADZoaGVhD7QFOQAAKjQAAAAkaG10eA1SFGkAACpYAAAA5GxvY2HYvuKCAAArPAAAAHRtYXhwAVQBWwAAK7AAAAAgbmFtZVLIniEAACvQAAAEinBvc3TOYv/WAAAwXAAAAKtwcmVw5S0OXwAAMQgAAACId2ViZiE/Vh4AADGQAAAABgAAAAEAAAAAzD2izwAAAADJQhegAAAAANJD0b0AAQAAAA4AAAAYAAAAAAACAAEAAQA4AAEABAAAAAIAAAABAAAACgBUAGIABERGTFQAGmN5cmwAJmdyZWsAMmxhdG4APgAEAAAAAP//AAEAAAAEAAAAAP//AAEAAAAEAAAAAP//AAEAAAAEAAAAAP//AAEAAAABa2VybgAIAAAAAQAAAAEABAACAAAAAQAIAAECLgAEAAAAGQA8AGIAgABiAJIAmACAAJ4AYgDEAGIA0gE0AToBOgCAAYQB0gHkAeQB+gHkAeQCEAH6AAkABv/XAAr/1wANAQoAEv/XABT/1wAX/3EAGf+uABr/rgAc/4UABwAE/9cAF//DABn/7AAa/+wAG//XABz/7AAd/+wABAAG/9cACv/XABL/1wAU/9cAAQANAHsAAQAE/9cACQAG/9cACv/XABL/1wAU/9cAF//XABj/7AAZ/9cAGv/XABz/wwADAAT/mgAb/9cAHf/sABgABP9xAAb/1wAK/9cAEv/XABT/1wAXACkAHv9cACD/cQAh/3EAIv9xACT/cQAq/5oAK/+aACz/cQAt/5oALv9xAC//mgAw/4UAMv+aADP/1wA0/9cANf/XADb/1wA3/64AAQAE/+wAEgAE/64ABv/sAAr/7AAS/+wAFP/sAB7/1wAg/9cAIf/XACL/1wAk/+wAKv/sACv/7AAs/9cALf/sAC7/1wAv/+wAMP/sADL/7AATAAT/hQAG/9cACv/XABL/1wAU/9cAHv+aACD/mgAh/5oAIv+aACT/1wAq/8MAK//DACz/mgAt/8MALv+aAC//wwAw/64AMv/DADf/1wAEAAb/7AAK/+wAEv/sABT/7AAFADP/1wA0/9cANf/XADb/1wA3/+wABQAg/9cAIf/XACL/1wAs/9cALv/XAAcAHv/XACD/1wAh/9cAIv/XACT/7AAs/9cALv/XAAEAGQAEAAUABgAHAAgACQAOAA8AEgATABQAFwAYABkAGgAbABwAHQAfACIAKAAsAC0ALwA1AAAAAQAAAAoATABOAARERkxUABpjeXJsACRncmVrAC5sYXRuADgABAAAAAD//wAAAAQAAAAA//8AAAAEAAAAAP//AAAABAAAAAD//wAAAAAAAAADBNcCvAAFAAQFmgUzAAABHwWaBTMAAAPRAGYB/AgCAgsIBgMFBAICBOAAAu9AACBbAAAAKAAAAAAxQVNDACAADSX8Bmb+ZgAACI0CgCAAAZ8AAAAABF4FtgAAACAAAgAAAAMAAAADAAAAHAABAAAAAABcAAMAAQAAABwABABAAAAADAAIAAIABAANACAAWgB6Jfz//wAAAA0AIABBAGEl/P////X/4//D/73aPAABAAAAAAAAAAAAAAAAAAABBgAAAQAAAAAAAAABAgAAAAIAAAAAAAAAAAAAAAAAAAABAAADAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAEBQYHCAkKCwwNDg8QERITFBUWFxgZGhscHQAAAAAAAB4fICEiIyQlJicoKSorLC0uLzAxMjM0NTY3AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAEXgW2AQIA4gD2AP4BMQExATYA1AD0APwBLAEmAQ0AyQERARwBFwEIAIcARAURsAAssAATS7BMUFiwSnZZsAAjPxiwBitYPVlLsExQWH1ZINSwARMuGC2wASwg2rAMKy2wAixLUlhFI1khLbADLGkYILBAUFghsEBZLbAELLAGK1ghIyF6WN0bzVkbS1JYWP0b7VkbIyGwBStYsEZ2WVjdG81ZWVkYLbAFLA1cWi2wBiyxIgGIUFiwIIhcXBuwAFktsAcssSQBiFBYsECIXFwbsABZLbAILBIRIDkvLbAJLCB9sAYrWMQbzVkgsAMlSSMgsAQmSrAAUFiKZYphILAAUFg4GyEhWRuKimEgsABSWDgbISFZWRgtsAossAYrWCEQGxAhWS2wCywg0rAMKy2wDCwgL7AHK1xYICBHI0ZhaiBYIGRiOBshIVkbIVktsA0sEhEgIDkvIIogR4pGYSOKIIojSrAAUFgjsABSWLBAOBshWRsjsABQWLBAZTgbIVlZLbAOLLAGK1g91hghIRsg1opLUlggiiNJILAAVVg4GyEhWRshIVlZLbAPLCMg1iAvsAcrXFgjIFhLUxshsAFZWIqwBCZJI4ojIIpJiiNhOBshISEhWRshISEhIVktsBAsINqwEistsBEsINKwEistsBIsIC+wBytcWCAgRyNGYWqKIEcjRiNhamAgWCBkYjgbISFZGyEhWS2wEywgiiCKhyCwAyVKZCOKB7AgUFg8G8BZLbAULLMAQAFAQkIBS7gQAGMAS7gQAGMgiiCKVVggiiCKUlgjYiCwACNCG2IgsAEjQlkgsEBSWLIAIABDY0KyASABQ2NCsCBjsBllHCFZGyEhWS2wFSywAUNjI7AAQ2MjLQAAAAABAAH//wAPAAIARAAAAmQFVQADAAcALrEBAC88sgcEFu0ysQYF3DyyAwIW7TIAsQMALzyyBQQW7TKyBwYX/DyyAQIW7TIzESERJSERIUQCIP4kAZj+aAVV+qtEBM0AAAACAAAAAAWFBbwABwANAEsAsgAAACuwAzOyAQIAK7QGCAABDSuxBgPpAbAOL7AA1rEHCemwBxCxBAErsQMJ6bEPASuxBAcRErMBAggJJBc5ALEBCBESsAw5MDExASEBIQMhAxMhAiYnBgIEAXsCBv6yav3rargBfZMlCCEFvPpEAVz+pAJgAdl8JIAAAAMAuAAABPQFtgAPABcAIABnALIPAAArsRAD6bICAgArsSAG6bQYFw8CDSuxGAXpAbAhL7AA1rEQCemwGDKwEBCxFAErsQwJ6bAcINYRsQUJ6bEiASuxBRQRErEICTk5ALEXEBESsAw5sBgRsQgJOTmwIBKwBTkwMTMRISAEFRQGBxUeARUUBCMDMzI2NTQhIzUzMjY1NCYrAbgBxwE3ARl7Zot7/t/47cqAev78wLR+cXuFowW2scGDqBEKH6qNyOABAGJltvZOWlRJAAEAd//sBNEFywAWAEUAshQAACuxDwPpsgQCACuxCgPpswcUBAgrAbAXL7AA1rENCemxGAErALEPFBESsBI5sAcRsgANETk5ObEEChESsAY5MDETNBIkMzIXBy4BIyICFRAhMjcRBiMgAHemATfR1ddkUqZQr8ABb5rbtN7+wf6uAtnkAVe3Z/wnOv756/4XTf78SwGDAAAAAgC4AAAFdQW2AAgADwA4ALIIAAArsQkD6bICAgArsQ8G6QGwEC+wANaxCQnpsAkQsQwBK7EFCemxEQErALEPCRESsAU5MDEzESEgABEQACEDMyARECEjuAHLAWYBjP5l/nxohQHA/mClBbb+hv6t/pf+gAEAAeEB1wAAAAEAuAAABAIFtgALAEcAsgAAACuxCQPpsgECACuxBAbptAUIAAENK7EFBukBsAwvsADWsQkJ6bAEMrIJAAors0AJCwkrsAIys0AJBwkrsQ0BKwAwMTMRIRUhESEVIREhEbgDSv3sAe/+EQIUBbb+/r/+/of/AAAAAAEAuAAAA/4FtgAJAEAAsgAAACuyAQIAK7EEBum0CAUAAQ0rsQgG6QGwCi+wANaxCQfpsAQysgkACiuzQAkDCSuzQAkHCSuxCwErADAxMxEhFSERIRUhEbgDRv3rAfD+EAW2/v6H/f2+AAAAAAEAd//sBScFywAaAHkAshgAACuxDgPpsgMCACuxCAPptBITGAMNK7ESA+kBsBsvsADWsQsJ6bALELEQASuxFQfpsAUyshAVCiuzQBASCSuxHAErsRALERKyAwgYOTk5sBURsAY5ALEOGBESsBU5sRMSERKxAAs5ObAIEbAGObADErAFOTAxExAAITIXByYjIgIVFBYzMjcRIREhEQ4BIyAAdwGVAWfh0Wegrcnyw7phZP7rAkSN+YL+tf6jAt0BYgGMWvhQ/vLk7vsUATEBAv0KLiUBhQAAAAEAuAAABWYFtgALAD8AsgAAACuwBzOyAQIAK7AFM7QDCgABDSuxAwPpAbAML7AA1rELCemwAjKwCxCxCAErsAQysQcJ6bENASsAMDEzESERIREhESERIRG4ATYCQwE1/sv9vQW2/cMCPfpKAnf9iQABALgAAAHuBbYAAwAhALIAAAArsgECACsBsAQvsADWsQMJ6bEDCemxBQErADAxMxEhEbgBNgW2+koAAAAB/2j+UgHuBbYADQAtALIGAgArsAsvsQID6QGwDi+wBdaxCAnpsQ8BKwCxAgsRErANObAGEbAAOTAxBxYzMjY1ESEREAIjIieYUEJmWAE26uVpTpYUf4cFWvqo/wD+9BYAAAAAAQC4AAAFUAW2AAwAMACyAAAAK7AIM7IBAgArsAUzAbANL7AA1rEMCemwAjKxDgErALEBABESsQMKOTkwMTMRIRE3ASEJASEBBxG4ATZ6AYwBWP4CAgL+oP6BgwW2/WOsAfH9efzRAmhe/fYAAQC4AAAEPwW2AAUALACyAAAAK7EDA+myAQIAKwGwBi+wANaxAwnpsgMACiuzQAMFCSuxBwErADAxMxEhESERuAE2AlEFtvtK/wAAAAEAuAAABtQFtgAUAIoAsgAAACuxBw8zM7IBAgArsQIFMzMBsBUvsADWsRQH6bQRBwAfBCuwFBCxCwErsQYH6bAGELEMB+mwDC+xFgErsDYausLc7RQAFSsKsA8uDrAQwLEDC/kFsALAAwCxAxAuLgGzAgMPEC4uLi6wQBqxCxQRErEFDjk5sAwRsA05ALEBABESsAw5MDEzESEBMwEhESERNDYTIwEhASMSFRG4AaYBWgYBbwGn/t4DDAn+h/7k/qAJEwW2+6IEXvpKArQxgAEU+4cEe/6idf1YAAABALgAAAXJBbYADwBdALIAAAArsAkzsgECACuwBzMBsBAvsADWsQ8H6bAPELEGASuxCAfpsAgQtAQHAB8EK7AEL7ERASuxDwARErELDDk5sAYRsQIKOTmwBBKwAzkAsQEAERKxAws5OTAxMxEhATMCNREhESEBIxIVEbgBhwJ7Bw8BF/52/YQJEwW2+7kBHXYCtPpKBFL+2339UAACAHf/7AXnBc0ACwAVAEQAsgkAACuxDwPpsgMCACuxEwPpAbAWL7AA1rEMCemwDBCxEQErsQYJ6bEXASuxEQwRErEDCTk5ALETDxESsQAGOTkwMRMQACEgABEQACEgAAEUFjMgERAhIgZ3AWkBUQFRAWX+mP6w/rD+mAFFurkBc/6PubwC3wFtAYH+fP6U/pX+egGGAWv1+AHtAe75AAAAAgC4AAAEqgW2AAoAEwBCALIAAAArsgICACuxEwbptAkLAAINK7EJBukBsBQvsADWsQoJ6bALMrAKELEPASuxBQnpsRUBKwCxEwsRErAFOTAxMxEhIAQVFAQhIxkBMzI2NTQmKwG4AdMBCgEV/tn+8IVmj453f40FtuXj7Pr9+AMGcWxtaAAAAAIAd/6kBecFzQAPABkAXgCyDQAAK7ETA+myDRMKK7NADQsJK7IDAgArsRcD6QGwGi+wANaxEAnpsBAQsRUBK7EGCemxGwErsRUQERKzAwsMCSQXObAGEbAKOQCxEw0RErAJObAXEbEABjk5MDETEAAhIAAREAIHASEBIyAAARQWMyARECEiBncBaQFRAVEBZbexAWD+c/70F/6w/pgBRbq5AXP+j7m8At8BbQGB/nz+lP7+/qNR/ncBSAGGAWv1+AHtAe75AAAAAgC4AAAFSAW2AA4AFwBbALIAAAArsAozsgICACuxFwbptA0PAAINK7ENBukBsBgvsADWsQ4J6bAPMrAOELETASuxBQnpsRkBK7ETDhESsAw5sAURsQgLOTkAsQ8NERKwCDmwFxGwBTkwMTMRISAEFRQGBwAXIQEjGQEzMjY1NCYrAbgBqgEqAR6OggFKZP6o/qOlZJOMj5ZeBbbZ3YHJOf4TkAIx/c8DLWJpaFgAAAABAF7/7AQXBcsAJwBxALImAAArsQQD6bISAgArsRkD6bMWJhIIKwGwKC+wD9axHAfpsBwQsQcBK7EjB+mwFTKxKQErsRwPERKwDDmwBxG1BAsSGSAmJBc5sCMSsRYhOTkAsQQmERKwADmwFhGzAQ8cIyQXObESGRESsBU5MDE3ER4BMzI2NTQuAScuAjU0JDMyFhcHLgEjIgYVFB4BFx4BFRQEIyJelM1VZm0wXY+GhlABB+hyz3FkdZlKWF4mU5vNmP7j/upEASBCNk5NK0M+RD90mmfC3jYx8TAmUkIpPTlKYsWPxuQAAQApAAAEeQW2AAcAOgCyBgAAK7IBAgArsQAD6bADMgGwCC+wBtaxBQnpsgUGCiuzQAUDCSuyBgUKK7NABgAJK7EJASsAMDETESERIREhESkEUP5z/soEtAEC/v77TAS0AAAAAAEArv/sBV4FtgASADcAshAAACuxBgPpsgECACuwCjMBsBMvsADWsQMJ6bADELEJASuxDAnpsRQBK7EJAxESsBA5ADAxExEhERQWMzI2NREhERQGBCMgAK4BNYidmIkBNZH+7rv+5v7IAggDrvyBqZ6fqgN9/E6i9IIBIQABAAAAAAUzBbYACwA9ALILAAArsgACACuwCDMBsAwvsADWsQEJ6bABELEIASuxCQnpsQ0BK7EIARESsQoLOTkAsQALERKwBTkwMREhAR4BFzY3ASEBIQE5ARMXMQYLQAEVATn+D/6uBbb8mk3NKFzmA2b6SgAAAAABAAAAAAe8BbYAHQEWALIdAAArsBMzsgACACuxCBEzMwGwHi+wANaxAQfpsAEQsREBK7ESB+mxHwErsDYauj4Q8F8AFSsKDrAFELAHwLEbDPmwGcC6wLX2hgAVKwoOsBgQsBbAsQsN+bANwLo+uPNAABUrC7AFELMGBQcTK7rA7/UdABUrC7ALELMMCw0TK7AYELMXGBYTK7o+ofLUABUrC7AbELMaGxkTK7IGBQcgiiCKIwYOERI5shobGRESObIMCw0giiCKIwYOERI5shcYFhESOQBADAcNGBsFBgsMFhcZGi4uLi4uLi4uLi4uLgFADAcNGBsFBgsMFhcZGi4uLi4uLi4uLi4uLrBAGgGxEQERErETHTk5ALEAHRESsAQ5MDERIRMWFz4BNxMhEx4BFz4BNxMhASEDJgInDgEHAyEBMbsxFgYrE9UBJdUOKgsKLBK6ATH+jP6fxgs1BAYwDcX+oAW2/OLdojnvQgMz/M034lFO6UgDHvpKAwApAQEsNu8z/QIAAAEAAAAABVYFtgALACYAsgAAACuwCDOyAgIAK7AFMwGwDC+xDQErALECABESsQQKOTkwMTEJASEJASEJASEJAQHl/joBVgE7ATUBTv41Ae7+nv6s/qwC8gLE/fICDv0r/R8CKf3XAAAAAQAAAAAE/gW2AAgAMACyBwAAK7IAAgArsAMzAbAJL7AH1rEGCemxCgErsQYHERKwAjkAsQAHERKwAjkwMREhCQEhAREhEQFQAS8BMQFO/hv+zAW2/aYCWvyD/ccCLwAAAQAxAAAEcQW2AAkALgCyAAAAK7EHA+myBAIAK7EDA+kBsAovsQsBKwCxBwARErABObEEAxESsAY5MDEzNQEhESEVASERMQK9/VYEGv1EAs/JA+0BAMj8Ev8AAAACAFb/7AQ7BHUAGAAiAIIAshEAACuyFgAAK7EbBOmyDAEAK7EHBOm0AyAWDA0rtAMEABQEKwGwIy+wANaxGQnpsBkQsR4BK7AEMrEPB+mxJAErsRkAERKxCQo5ObAeEbIHDBY5OTmwDxKwEzkAsRsRERKxEhM5ObAgEbAAObADErACObAHEbAJObAMErAKOTAxEzQ2PwE1NCMiByc2MzIWFREjJyMOASMiJiUUMzI2PQEHDgFW+fvCroa1ZcHr4fDVOwhNo4OhuQE5lGp/doWCAU6yqQkGMapRzmXEyP0XmGFLuKiBemVcBARYAAIAoP/sBLQGFAASAB8AYwCyAAAAK7IOAAArsRYF6bIIAQArsRwF6bABLwGwIC+wANaxEwfpsAIysBMQsRkBK7ELCemxIQErsRMAERKyBQYQOTk5sBkRsQgOOTkAsRYAERKwEDmwHBGwCzmwCBKwBTkwMTMRIREUBzM2MzISERACIyInIwcTFBYzMjY1NCYjIgYHoAExDAxr0sbg58fFcBUzSGt0Xm9wYXFoAgYU/pZFmKb+y/7z/uv+0I97AjO0nK2lpaWLoAAAAQBc/+wD3QRzABUAPQCyFAAAK7ENBemyAwEAK7EJBekBsBYvsADWsQsJ6bEXASsAsQ0UERKwETmwCRGyAAYQOTk5sAMSsAU5MDETEAAhMhcHLgEjIhEQMzI2NxEOASMgXAEcAQnCmlpIfD7u7liWS0qXc/32AikBHQEtTOwdJf6u/rgvMv77LyQAAAACAFz/7ARxBhQAEgAfAGIAsgwAACuyDwAAK7AJLwGwIC+wANaxEwnpsBMQsQgBK7EKB+mwChCxGQfpsBkvsAYzsSEBK7EIExEStAMOEBYdJBc5sBkRsQUNOTmwChKwDDkAsQkMERK0AA0OFh0kFzkwMRMQEjMyFzMmNREhESMnIwYjIgIBFBYzMjY3NTQmIyIGXOXJ028KFwEy6jsNaNXF4QE1cmp1bQVvfWZxAi0BEwEzpH1iAWb57JGlATIBC6WliKMhtJytAAIAXP/sBGIEcwAUABsAaQCyEgAAK7ELBOmyAwEAK7EZBOm0FQgSAw0rtBUEABQEKwGwHC+wANaxCAnpsBUysAgQsRYBK7EGB+mxHQErsRYIERKyAwsSOTk5sAYRsQ4POTkAsQsSERKwDzmwCBGwDjmwFRKwADkwMRMQADMyAB0BIR4BMzI2NxUOASMgAAEhLgEjIgZcARn47QEI/S8FkIJltGJQtoP+8v7QATwBrAJyYWFuAicBGQEz/vLulIKSKi7sKCcBKgGYcXt7AAEAKQAAA3UGHwAVAFoAshQAACuyDwEAK7ESBOmwADKyAgEAK7ALL7EGBekBsBYvsBTWsAIysRMH6bAOMrITFAors0ATEQkrshQTCiuzQBQACSuxFwErALELDxESsAk5sAYRsAg5MDETNTc1NDYzMhcHJiMiBh0BIRUhESERKai8z557TlxOQToBCP74/s8DeZNSUr+wL+AdTTxG5fyHA3kAAAAAAwAG/hQEbQRzACkANgBAAN8AsjQAACuxIAXpshIBACu0PwQADAQrsBQysg8BACu0PwQAFAQrsCcvtC0EABQEK7QaOjQPDSu0GgQAFAQrAbBBL7AM1rE3B+mwHjKwACDWEbQqBwAfBCuwNxC0BgcAGAQrsAYvsDcQsT0BK7EXB+mwFxCwJCDWEbQwBwAlBCuwMC+0JAcAJQQrsUIBK7EqBhESsAM5sDcRsAk5sD0StBwPICctJBc5sDARsCE5sBcSsBU5ALE0LRESsSQAOTmwIBGwAzmwGhKxBh45ObA6EbEJHDk5sD8SshUXDDk5OTAxFzQ2Ny4BNTQ2Ny4BNTQ2MzIWFyEVBxYVFAYjLwEGFRQ7ATIWFRQEISImJRQWMzI2NTQmKwEiBhMUFjMyNjU0IyIGfnovRkpGWGfu3S+BEgGGrzD73zctL6i+uMH+uf7O6vcBCHltpLpuc55UcW9TVVZQpqi2ZYgdFFszQFUpJqhyt8gRBJstS120yQMFJCxCnpnE2KOrP0haTj8wTwNNW2pqW8oAAAAAAQCgAAAEqAYUABUARACyAAAAK7ANM7ABLwGwFi+wANaxFQfpsAIysBUQsQ4BK7ENB+mxFwErsRUAERKwBjmwDhGxBwk5OQCxAQARErAROTAxMxEhERQPATM2MzIWFREhETQjIgYVEaABMQcHEGbexcz+z7SAcgYU/sMliVqk1Mb9JwKN8q7D/fIAAAACAJMAAAHfBhQACAAMADcAsgkAACuyCgEAK7AHL7QCAwAjBCsBsA0vsAnWsAAysQwH6bAEMrEOASuxDAkRErEHAjk5ADAxEzQzMhUUBiMiExEhEZOmplNTpg0BMQV/lZVHT/sXBF77ogAAAAAC/33+FAHfBhQADQAWAEcAsgYBACuwCy+xAgXpsBUvtBADACMEKwGwFy+wBdawDjKxCAfpsBIysRgBK7EIBRESsRAVOTkAsQILERKwDTmwBhGwADkwMQcWMzI2NREhERQGIyInATQzMhUUBiMig0ZJTUcBMc69dVQBFqamU1Om4xNWVASq+ymywRkHUpWVR08AAAAAAQCgAAAE9gYUAA4AOgCyAAAAK7AKM7IHAQArsAEvAbAPL7AA1rEOB+mwAjKxEAErsQ4AERKxBAU5OQCxBwARErEEDDk5MDEzESERBzM3ASEJASEBBxGgATEQBIUBOQFY/kQB1/6g/r6DBhT9Sv6qAVT+G/2HAcVp/qQAAAEAoAAAAdEGFAADAB8AsgAAACuwAS8BsAQvsADWsQMH6bEDB+mxBQErADAxMxEhEaABMQYU+ewAAQCgAAAHQgRzACMAcACyAAAAK7ERGjMzsgEBACuyBwEAK7ANM7EfBemwFjIBsCQvsADWsSMH6bAjELEbASuxGgfpsBoQsRIBK7ERB+mxJQErsSMAERKwBDmwGxGwBzmwGhKxCgk5ObASEbANOQCxAR8RErMDBAkKJBc5MDEzETMXMz4BMzIXMz4BMzIWFREhETQmIyIGFREhETQmIyIGFRGg6SkRLapu+1kbLa9uvsP+zlFXcG/+z1FXdWoEXo9NV6ROVsPX/ScCjXl5oK79zwKNeXmsxf3yAAAAAAEAoAAABKgEcwAUAEwAsgAAACuwCzOyAQEAK7IHAQArsRAF6QGwFS+wANaxFAfpsBQQsQwBK7ELB+mxFgErsRQAERKwBDmwDBGwBzkAsQEQERKxAwQ5OTAxMxEzFzM+ATMyFhURIRE0JiMiBhURoOkpETOzcsPK/s9WXoByBF6PUVPTx/0nAo15eavG/fIAAAIAXP/sBJgEcwANABkARACyCgAAK7ERBemyAwEAK7EXBekBsBovsADWsQ4J6bAOELEUASuxBwnpsRsBK7EUDhESsQMKOTkAsRcRERKxBwA5OTAxExAAITIWEhUQACEiJgIlFBYzMjY1NCYjIgZcAR4BA6H2hP7g/v+h9oQBN217emtse3psAjEBEgEwjP76sP7v/syNAQiwpqqpp6ampQACAKD+FAS0BHMAEwAfAGcAsg0AACuxFwXpsgEBACuyBgEAK7EcBemwAC8BsCAvsADWsRMH6bAUMrATELEZASuxCQnpsSEBK7ETABESsgQPEDk5ObAZEbEGDTk5ALEXDRESsQ8QOTmwHBGwCTmwARKxAwQ5OTAxExEzFzM2MzISERQCBiMiJyMWFRkBFBYzMhE0JiMiBgeg+CsOa9LG4GnCg8VwEBBrdM1lbHFoAv4UBkqRpv7O/vCz/viKj4wW/jsEH7ScAVKlpYugAAACAFz+FARxBHMAFAAgAFoAsggBACuyAgEAK7ALLwGwIS+wANaxFQnpsBUQsRsBK7EJB+mwCRCxCwfpsAsvsSIBK7ELFREStAMPEhgfJBc5sBsRsgcGDjk5OQCxCAsRErMABhgfJBc5MDETEBIzMhYXMzchESERNDcjDgEjIgIBFBYzMjY3NTQmIyJc5cdqnjwIGwEC/s4NDTGiasbgATdrcXRsBW971wItARIBNFBUj/m2AdU9a1FUATEBDKimhaYltJwAAQCgAAADdwRzABAAOACyAAAAK7IBAQArsgcBACuxDAPpAbARL7AA1rEQB+mxEgErsRAAERKwBDkAsQEMERKxAwQ5OTAxMxEzFzM+ATMyFwMmIyIGFRGg5y0PNLFoPikXJTWSowRevF5zCf7iCpaH/ccAAAABAFz/7AOsBHMAJQBrALIVAAArsRwE6bIDAQArsQkE6QGwJi+wANawGDKxCwfpsAsQsR4BK7ESB+mxJwErsQsAERKwIzmwHhG1AwkOFRwiJBc5sBISsgYPBTk5OQCxHBURErAYObAJEbMABhIZJBc5sAMSsAU5MDETNDYzMhcHLgEjIhUUFhceAhUUBiMiJic1HgEzMjU0LgEnLgJc59TKv1xUkkyHV5ODejrv7nqsS1XVUaYsbFqBeTcDO5WjWNwkLkkpPDs1XHhTrLQhIPwoNmAkLTkmNlx3AAAAAQAv/+wDNwVMABUAcACyEQAAK7EMBemyBQEAK7EIBOmwADKyBQgKK7NABQQJK7ICAQArAbAWL7AU1rEJB+mwBDKyCRQKK7NACQcJK7AOMrIUCQors0AUAAkrsRcBK7EJFBESsAI5ALEMERESsA85sAgRsA45sAUSsAE5MDETNT8BMxUhFSERFBYzMjcVBiMiJjURL6hYwwE5/sdJPFBwcqa3pwN5gWbs7uX95UE+I+MzubkCGwAAAAEAmv/sBKIEXgAUAEwAsg0AACuyEgAAK7EGBemyAQEAK7AKMwGwFS+wANaxAwfpsAMQsQkBK7ELB+mxFgErsQkDERKwEjmwCxGwDzkAsQYNERKxDg85OTAxExEhERQWMzI2NREhESMnIw4BIyImmgExVl6AcgEx6ikQMbRzxcgBhQLZ/XN5eavGAg77oo9OVdMAAAABAAAAAASNBF4ACwAhALILAAArsgABACuwCDMBsAwvsQ0BKwCxAAsRErAEOTAxESETFhczNjcTIQEhAT/YJAkGBSjXAT/+Vv7HBF79g3lsYIUCffuiAAAAAQAUAAAGxQReAB0A5gCyHQAAK7AXM7IAAQArswEKFRYkFzMBsB4vsADWsQEH6bABELEVASuxFgfpsR8BK7A2GrrCEu/cABUrCrAAELAdwA6wARCwAsC6wdTwzgAVKwoFsAouDrAOwLEaBPmwGcC6PcfvRwAVKwoOsBUQsBTABbAWELAXwLrBlvHZABUrC7AKELMLCg4TK7MMCg4TK7MNCg4TK7ILCg4giiCKIwYOERI5sAw5sA05ALcCCxQZGgwNDi4uLi4uLi4uAUALAgoLFBcZGh0MDQ4uLi4uLi4uLi4uLrBAGgEAsQAdERKxBBA5OTAxEyETFhczNj8BEyETHgMXMz4BNxMhASELASMDIRQBMIEfIAYEHxCKAVCDBBEQDQEGCS4KhgEr/r7+tFZ0B8z+uARe/hGF6kylVQIY/egWVmFdHEj7LAHv+6IBhwHu/IsAAAEACgAABJYEXgALACYAsgAAACuwCDOyAgEAK7AFMwGwDC+xDQErALECABESsQQKOTkwMTMJASEbASEJASELAQoBe/6YAVrZ2wFa/pQBff6l6+wCOwIj/pwBZP3d/cUBf/6BAAABAAD+FASNBF4AFgArALIAAQArsAgzsA0vsRIF6QGwFy+xGAErALESDRESsA85sAARsQQQOTkwMREhExYXMzY3EyEBDgEjIic1FjMyNj8BAU7TGwoGCyDPAUf+J0HxoU9MN0FReSISBF79i1JwZ1sCdfsTr64R8g1jZDcAAQA3AAADqgReAAkALgCyAAAAK7EHBOmyBAEAK7EDBOkBsAovsQsBKwCxBwARErABObEEAxESsAY5MDEzNQEhNSEVASEVNwIG/hkDQv4IAgq0AsHpxv1R6QAAAAABAAAAAARgBGAAAwAnALIAAAArsgEBACsBsAQvsADWtAMJAAcEK7QDCQAHBCuxBQErADAxMREhEQRgBGD7oAAAAQAAAAEZmpevkAxfDzz1AB8IAAAAAADSQ9G+AAAAANJD0b7/aP4UB7wGHwABAAgAAgAAAAAAAAABAAAIjf2AAAAH2/9o/6QHvAABAAAAAAAAAAAAAAAAAAAAOQLsAEQAAAAABBQAAAIUAAAFhQAABWAAuAUZAHcF7AC4BHsAuARkALgFywB3Bh8AuAKmALgCpv9oBVAAuASFALgHiwC4BoEAuAZeAHcFBgC4Bl4AdwVIALgEaABeBKIAKQYMAK4FMwAAB7wAAAVWAAAE/gAABKIAMQTVAFYFEACgBB0AXAUQAFwEugBcAxkAKQSFAAYFQgCgAnEAkwJx/30E9gCgAnEAoAfbAKAFQgCgBPQAXAUQAKAFEABcA6IAoAP6AFwDeQAvBUIAmgSNAAAG2QAUBKAACgSNAAAD5wA3BGAAAAAAACwALAAsACwAcgDYASQBYgGeAdQCQAJ4ApYCyAL+AyQDkgPgBDAEdATYBTAFpAXWBhQGUAcUB0gHeAemCBwIgAjGCSoJkAniCq4K9AsqC3QLsgvODDwMhAzUDToNnA3WDkQOoA7qDxYPwA/yEDAQXhB+AAEAAAA5AEEAAwAAAAAAAgABAAIAFgAAAQABFgAAAAAAAAASAN4AAwABBAkAAAByAAAAAwABBAkAAQASAHIAAwABBAkAAgAIAIQAAwABBAkAAwBGAIwAAwABBAkABAAcANIAAwABBAkABQAYAO4AAwABBAkABgAaAQYAAwABBAkABwCkASAAAwABBAkACAAoAcQAAwABBAkACwA4AewAAwABBAkADABcAiQAAwABBAkADQBcAoAAAwABBAkADgBUAtwAAwABBAkAyAAWAzAAAwABBAkAyQAwA0YAAwABBAkAygAOA3YAAwABBAkAywAOA4QAAwABBAnZAwAaA5IARABpAGcAaQB0AGkAegBlAGQAIABkAGEAdABhACAAYwBvAHAAeQByAGkAZwBoAHQAIACpACAAMgAwADEAMAAtADIAMAAxADEALAAgAEcAbwBvAGcAbABlACAAQwBvAHIAcABvAHIAYQB0AGkAbwBuAC4ATwBwAGUAbgAgAFMAYQBuAHMAQgBvAGwAZABBAHMAYwBlAG4AZABlAHIAIAAtACAATwBwAGUAbgAgAFMAYQBuAHMAIABCAG8AbABkACAAQgB1AGkAbABkACAAMQAwADAATwBwAGUAbgAgAFMAYQBuAHMAIABCAG8AbABkAFYAZQByAHMAaQBvAG4AIAAxAC4AMQAwAE8AcABlAG4AUwBhAG4AcwAtAEIAbwBsAGQATwBwAGUAbgAgAFMAYQBuAHMAIABpAHMAIABhACAAdAByAGEAZABlAG0AYQByAGsAIABvAGYAIABHAG8AbwBnAGwAZQAgAGEAbgBkACAAbQBhAHkAIABiAGUAIAByAGUAZwBpAHMAdABlAHIAZQBkACAAaQBuACAAYwBlAHIAdABhAGkAbgAgAGoAdQByAGkAcwBkAGkAYwB0AGkAbwBuAHMALgBBAHMAYwBlAG4AZABlAHIAIABDAG8AcgBwAG8AcgBhAHQAaQBvAG4AaAB0AHQAcAA6AC8ALwB3AHcAdwAuAGEAcwBjAGUAbgBkAGUAcgBjAG8AcgBwAC4AYwBvAG0ALwBoAHQAdABwADoALwAvAHcAdwB3AC4AYQBzAGMAZQBuAGQAZQByAGMAbwByAHAALgBjAG8AbQAvAHQAeQBwAGUAZABlAHMAaQBnAG4AZQByAHMALgBoAHQAbQBsAEwAaQBjAGUAbgBzAGUAZAAgAHUAbgBkAGUAcgAgAHQAaABlACAAQQBwAGEAYwBoAGUAIABMAGkAYwBlAG4AcwBlACwAIABWAGUAcgBzAGkAbwBuACAAMgAuADAAaAB0AHQAcAA6AC8ALwB3AHcAdwAuAGEAcABhAGMAaABlAC4AbwByAGcALwBsAGkAYwBlAG4AcwBlAHMALwBMAEkAQwBFAE4AUwBFAC0AMgAuADAAVwBlAGIAZgBvAG4AdAAgADEALgAwAFcAZQBkACAATwBjAHQAIAAxADQAIAAwADUAOgAzADIAOgA0ADYAIAAyADAAMQA1AGQAZQBmAGEAdQBsAHQAcABlAHIAcwBlAHUAcwBGAG8AbgB0ACAAUwBxAHUAaQByAHIAZQBsAAAAAgAAAAAAAP9mAGYAAAAAAAAAAAAAAAAAAAAAAAAAAAA5AAABAgEDAAMAJAAlACYAJwAoACkAKgArACwALQAuAC8AMAAxADIAMwA0ADUANgA3ADgAOQA6ADsAPAA9AEQARQBGAEcASABJAEoASwBMAE0ATgBPAFAAUQBSAFMAVABVAFYAVwBYAFkAWgBbAFwAXQEEBmdseXBoMQd1bmkwMDBEB3VuaTI1RkMAuAH/hbABjQBLsAhQWLEBAY5ZsUYGK1ghsBBZS7AUUlghsIBZHbAGK1xYALADIEWwAytEsAYgRbID+gIrsAMrRLAFIEWyBmwCK7ADK0SwBCBFsgUkAiuwAytEAbAHIEWwAytEsAggRboAB3//AAIrsQNGditEsAkgRbII2gIrsQNGditEWbAUKwABVh4hPgAA) format(&apos;truetype&apos;);font-weight:400;font-style:normal}@font-face{font-family:&apos;open_sansitalic&apos;;src:url(data:application/x-font-opentype;charset=utf-8;base64,AAEAAAATAQAABAAwRkZUTWfkvbYAAAE8AAAAHEdERUYAZgAEAAABWAAAACBHUE9TECH6YwAAAXgAAALSR1NVQpM8gksAAARMAAAAUE9TLzKg7bwzAAAEnAAAAGBjbWFwpkuXDgAABPwAAAFiY3Z0IA9XE2wAAAZgAAAATGZwZ21TtC+nAAAGrAAAAmVnYXNwAAAAEAAACRQAAAAIZ2x5ZhZeU88AAAkcAAAnVGhlYWQJ/wcYAAAwcAAAADZoaGVhDrwESAAAMKgAAAAkaG10eOvmCl0AADDMAAAA5GxvY2EIDRLaAAAxsAAAAHRtYXhwAVQBPgAAMiQAAAAgbmFtZVUun4gAADJEAAAEmHBvc3TOVv/WAAA23AAAAKtwcmVw6lkVVgAAN4gAAAFSd2ViZiGoVh4AADjcAAAABgAAAAEAAAAAzD2izwAAAADJY0jAAAAAANJD0iYAAQAAAA4AAAAYAAAAAAACAAEAAQA4AAEABAAAAAIAAAABAAAACgBUAGIABERGTFQAGmN5cmwAJmdyZWsAMmxhdG4APgAEAAAAAP//AAEAAAAEAAAAAP//AAEAAAAEAAAAAP//AAEAAAAEAAAAAP//AAEAAAABa2VybgAIAAAAAQAAAAEABAACAAAAAQAIAAECLgAEAAAAGQA8AGIAgABiAJIAmACAAJ4AYgDEAGIA0gE0AToBOgCAAYQB0gHkAeQB+gHkAeQCEAH6AAkABv/XAAr/1wANAQoAEv/XABT/1wAX/3EAGf+uABr/rgAc/4UABwAE/9cAF//DABn/7AAa/+wAG//XABz/7AAd/+wABAAG/9cACv/XABL/1wAU/9cAAQANAHsAAQAE/9cACQAG/9cACv/XABL/1wAU/9cAF//XABj/7AAZ/9cAGv/XABz/wwADAAT/mgAb/9cAHf/sABgABP9xAAb/1wAK/9cAEv/XABT/1wAXACkAHv9cACD/cQAh/3EAIv9xACT/cQAq/5oAK/+aACz/cQAt/5oALv9xAC//mgAw/4UAMv+aADP/1wA0/9cANf/XADb/1wA3/64AAQAE/+wAEgAE/64ABv/sAAr/7AAS/+wAFP/sAB7/1wAg/9cAIf/XACL/1wAk/+wAKv/sACv/7AAs/9cALf/sAC7/1wAv/+wAMP/sADL/7AATAAT/hQAG/9cACv/XABL/1wAU/9cAHv+aACD/mgAh/5oAIv+aACT/1wAq/8MAK//DACz/mgAt/8MALv+aAC//wwAw/64AMv/DADf/1wAEAAb/7AAK/+wAEv/sABT/7AAFADP/1wA0/9cANf/XADb/1wA3/+wABQAg/9cAIf/XACL/1wAs/9cALv/XAAcAHv/XACD/1wAh/9cAIv/XACT/7AAs/9cALv/XAAEAGQAEAAUABgAHAAgACQAOAA8AEgATABQAFwAYABkAGgAbABwAHQAfACIAKAAsAC0ALwA1AAAAAQAAAAoATABOAARERkxUABpjeXJsACRncmVrAC5sYXRuADgABAAAAAD//wAAAAQAAAAA//8AAAAEAAAAAP//AAAABAAAAAD//wAAAAAAAAADBDwBkAAFAAQFmgUzAAABHwWaBTMAAAPRAGYCAAAAAgsGBgMFBAICBOAAAu9AACBbAAAAKAAAAAAxQVNDAAEADSX8Bmb+ZgAACGICTSAAAZ8AAAAABEgFtgAAACAAAgAAAAMAAAADAAAAHAABAAAAAABcAAMAAQAAABwABABAAAAADAAIAAIABAANACAAWgB6Jfz//wAAAA0AIABBAGEl/P////X/4//D/73aPAABAAAAAAAAAAAAAAAAAAABBgAAAQAAAAAAAAABAgAAAAIAAAAAAAAAAAAAAAAAAAABAAADAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAEBQYHCAkKCwwNDg8QERITFBUWFxgZGhscHQAAAAAAAB4fICEiIyQlJicoKSorLC0uLzAxMjM0NTY3AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAESAW2AJgAQwBpAHUAfQCCAIsAjwCTAJwA3QCqAIMAiwCaAKIApgCqALAAtgDLAH8AqACfAJEApAB4AJYAjQCsAK4AewBwAIYFEbAALLAAE0uwTFBYsEp2WbAAIz8YsAYrWD1ZS7BMUFh9WSDUsAETLhgtsAEsINqwDCstsAIsS1JYRSNZIS2wAyxpGCCwQFBYIbBAWS2wBCywBitYISMheljdG81ZG0tSWFj9G+1ZGyMhsAUrWLBGdllY3RvNWVlZGC2wBSwNXFotsAYssSIBiFBYsCCIXFwbsABZLbAHLLEkAYhQWLBAiFxcG7AAWS2wCCwSESA5Ly2wCSwgfbAGK1jEG81ZILADJUkjILAEJkqwAFBYimWKYSCwAFBYOBshIVkbiophILAAUlg4GyEhWVkYLbAKLLAGK1ghEBsQIVktsAssINKwDCstsAwsIC+wBytcWCAgRyNGYWogWCBkYjgbISFZGyFZLbANLBIRICA5LyCKIEeKRmEjiiCKI0qwAFBYI7AAUliwQDgbIVkbI7AAUFiwQGU4GyFZWS2wDiywBitYPdYYISEbINaKS1JYIIojSSCwAFVYOBshIVkbISFZWS2wDywjINYgL7AHK1xYIyBYS1MbIbABWViKsAQmSSOKIyCKSYojYTgbISEhIVkbISEhISFZLbAQLCDasBIrLbARLCDSsBIrLbASLCAvsAcrXFggIEcjRmFqiiBHI0YjYWpgIFggZGI4GyEhWRshIVktsBMsIIogiocgsAMlSmQjigewIFBYPBvAWS2wFCyzAEABQEJCAUu4EABjAEu4EABjIIogilVYIIogilJYI2IgsAAjQhtiILABI0JZILBAUliyACAAQ2NCsgEgAUNjQrAgY7AZZRwhWRshIVktsBUssAFDYyOwAENjIy0AAAAAAQAB//8ADwACAEQAAAJkBVUAAwAHAC6xAQAvPLIHBATtMrEGBdw8sgMCBO0yALEDAC88sgUEBO0ysgcGJfw8sgECBO0yMxEhESUhESFEAiD+JAGY/mgFVfqrRATNAAAAAv+LAAAEEAW2AAcADgB5ALIAAAArsQMEMzOyAQIAK7ACM7QGCAABDSuwCTOxBgzpsAUyAbAPL7AE1rEDDumxEAErsDYausB6+DcAFSsKDrAEELAKwAWwAxCwAsCwChCzBQoEEyuzCQoEEysDALAKLgGzAgUJCi4uLi6wQBoAsQEIERKwDDkwMSMBMxMjAyEDASEDJicOAXUDH664qjn+EPUBSQGKIxgFJVcFtvpKAdH+LwJtASuzq1iuAAADAFYAAASyBbYADgAXACAAkACyAAAAK7EPCumyAQIAK7EgC+m0GBcAAQ0rsRgK6QGwIS+wE9axCxbpsxwLEwgrsQQV6bEiASuwNhq6PpzyuQAVKwqwAC6wIC6wABCxDxP5sCAQsQET+bAPELMXDyATK7MYDyATKwO1AAEPFxggLi4uLi4usEAaALEXDxESsAs5sBgRsQgHOTmwIBKwBDkwMTMBISARFAYHFR4BFRQEIyUhMjY1NCYrATczMjY1NCYrAVYBNQF3AbCunnN7/tD//voBCrXClYzsH/icuoWP0wW2/rCNwh0KIJ1u1PGRoZN0e5CSfmhnAAEAlv/sBQoFywAYAD0AshYAACuxEAPpsgQCACuxCQPpAbAZL7AA1rENFumxGgErALEQFhESsBM5sAkRsgAHEjk5ObAEErAGOTAxExASJDMyFwcmIyIEAhUUFjMyNxUOASMiAJbTAWThxZdFio2u/u2hw6uLt1acbvL+7AIZAQUBwexQjUXC/ondu985lR8cASsAAAACAFYAAAUUBbYACQATAF0AsgkAACuwADOxCgvpsgECACuxEwvpAbAUL7AP1rEFFumxFQErsDYauj6V8psAFSsKsAAusBMusAAQsQoT+bATELEBE/kDswABChMuLi4usEAaALETChESsAU5MDEzASEgABEQAgQhJzMyJBI1NCYrAVYBNQFWARQBH9L+ev76l6LKATKjzseyBbb+1f7i/vv+cNiTtwFO19fdAAAAAQBWAAAEagW2AAsAaQCyAAAAK7EJA+myAQIAK7EEA+m0BQgAAQ0rsQUD6QGwDC+xDQErsDYauj6m8ukAFSsKsAAusAQusAAQsQkT+bAEELEBE/mwCRCzBQkEEyuzCAkEEysDtQABBAUICS4uLi4uLrBAGgAwMTMBIQchAyEHIQMhB1YBNQLfIP3KYgIPHf3vcgI1IQW2mf4rmP3omAAAAAEAVgAABGoFtgAJAGAAsgAAACuwCTOyAQIAK7EEA+m0CAUAAQ0rsQgD6QGwCi+wANaxCQ7psQsBK7A2Gro+ofLVABUrCrAAELABwLAJELAEwLMFCQQTK7MICQQTKwOzAQQFCC4uLi6wQBoAMDEzASEHIQMhByEDVgE1At8e/chuAhAg/e+DBbaZ/euZ/ZEAAAEAlv/sBU4FywAdAH4AshsAACuxEgPpsgQCACuxCwPptBYXGwQNK7AYM7EWA+mwFTIBsB4vsADWsQ8W6bEfASuwNhq6Po7yegAVKwqwFS4OsBTABbEYE/kOsBnAALEUGS4uAbMUFRgZLi4uLrBAGgEAsRYSERKxDwA5ObELFxESsAg5sAQRsAc5MDETEBIkMzIWFwcuASMiBAIVFBYzMjcTITchAwYjIACWywFo23XNaEJNsWqp/uuazbiaamD+3yEBy5rYy/74/tsCEAENAbn1KCyYIjLL/pThvtonAbyY/TlLASEAAAABAFYAAAVzBbYACwCgALIAAAArsgcICzMzM7IBAgArsgIFBjMzM7QDCgABDSuwCTOxAwPpsAQyAbAML7AA1rELDumwCxCxAQErsQIO6bACELEIASuxBxPpsAcQsQUBK7EGDumxDQErsDYauj6g8s0AFSsKuj6W8p4AFSsKsAsQswMLAhMrsAgQswQIBRMrswkIBRMrsAsQswoLAhMrA7MDBAkKLi4uLrBAGgAwMTMBMwMhEzMBIxMhA1YBNaqDApSFqP7Kp4/9bJEFtv2SAm76SgKw/VAAAAABAFYAAAI1BbYAAwA/ALIAAAArsAMzsgECACuwAjMBsAQvsADWsQMO6bADELEBASuxAg7psQUBK7A2Gro+mfKvABUrCgMBsEAaADAxMwEzAVYBN6j+yQW2+koAAAH+wf5/AjUFtgAMAFkAsgcCACuwCDOwCy+xAwPpAbANL7AH1rEIDumxDgErsDYauj6d8r4AFSsKDrAHELAGwLAIELAJwACxBgkuLgGxBgkuLrBAGgEAsQMLERKwADmwBxGwATkwMQE3FjMyNjcBMwECISL+wQZFTGSDGQEzqv7LT/6paf6YkxR9eAWq+kT+hQAAAAABAFYAAAUrBbYADQCHALIAAAArsQcNMzOyAQIAK7ECBDMzAbAOL7AA1rENDumwDRCxAQErsQIO6bEPASuwNhq6Pp7yxAAVKwq6Pp7yxAAVKwuwDRCzAw0CEyuzDA0CEyuyDA0CIIogiiMGDhESObADOQCxAwwuLgGxAwwuLrBAGgGxAgERErALOQCxAQARErALOTAxMwEzAwEzCQEjJgInBwNWATWqlwK80f2BAV66SJVIrn0Ftv06Asb9g/zHtQFlt4P9sgAAAAEAVgAAA1YFtgAFAEUAsgAAACuxAwPpsgECACuwAjMBsAYvsAHWsQIO6bEHASuwNhq6Pp/yyQAVKwqwARCwAMCwAhCwA8ADsQADLi6wQBoAMDEzATMBIQdWATWq/uwCNSEFtvrkmgAAAQBUAAAGuAW2ABQA9gCyAAAAK7MHCA4UJBczsgECACuxAgYzMwGwFS+wANaxFBLpsBQQsQgBK7EHFemxFgErsDYauj6e8sQAFSsKsAAQsAHADrAUELARwLrAfPgkABUrCgWwDi4OsA/AsQMJ+QWwAsC6PqvzAwAVKwoOsAgQsArABbAHELAGwLo+mfKsABUrC7AIELMJCAoTK7AUELMSFBETK7MTFBETK7ITFBEgiiCKIwYOERI5sBI5sgkIChESOQC2Aw8TCQoREi4uLi4uLi4BQAsBAgMGDg8TCQoREi4uLi4uLi4uLi4usEAaAbEIFBESsQQNOTkAsQEAERKwCzkwMTMBMxMzASEBIxoBNyMBIwMjDgEHA1QBNfSVCQKTAQr+0a5+hhsG/TODpggHKxC+Bbb7TAS0+koCTgJ3TfruBRBI+0r8fQAAAAABAFQAAAWoBbYADwB/ALIAAAArsQkPMzOyAQIAK7EHCDMzAbAQL7AA1rEPEumwDxCxBwErsQgS6bERASuwNhq6Pp7yxAAVKwqwABCwAcAOsA8QsA7Auj6s8wcAFSsKsAcQsAbABbAIELAJwAMAsQYOLi4BswEGCQ4uLi4usEAaALEBABESsQMLOTkwMTMBMwEzNjcTMwEjASMGBwNUATW0AcsGHiqupP7Ltf40BiAqrAW2+zzgtQMv+koEx93F/NsAAAAAAgCW/+wFgwXNAA0AGwBEALILAAArsRED6bIEAgArsRgD6QGwHC+wANaxDhbpsA4QsRUBK7EHFumxHQErsRUOERKxBAs5OQCxGBERErEABzk5MDETEBIkMzIAERACBCMgABMUFjMyNhI1NCYjIgYClsABT9L0ARiw/rjX/wD+4rbEqJjxjLynnfiJAiUBCAG07P7M/vL+8/5X6QErARLH38MBbN3H38r+mAAAAAIAVgAABIcFtgAKABMAcwCyAAAAK7AKM7IBAgArsRML6bQJCwABDSuxCQvpAbAUL7AA1rEKDumwChCxDwErsQUV6bEVASuwNhq6Pp7yxAAVKwqwABCwAcCwChCwE8CzCQoTEyuzCwoTEysDswEJCxMuLi4usEAaALETCxESsAU5MDEzASEyFhUUACEjAxMzMjY1NCYrAVYBNQFK1tz+uP7Dh3uahdjgi5CjBba9vPj++v3BAtG2sH1vAAAAAgCW/qQFgwXNABEAHwBNALIPAAArsRUD6bIEAgArsRwD6QGwIC+wANaxEhbpsBIQsRkBK7EHFumxIQErsRkSERKzBAsOCiQXOQCxFQ8RErAKObAcEbEABzk5MDETEBIkMzIAERAABwEjAwcjIAATFBYzMjYSNTQmIyIGApbAAU/S9AEY/ursARLb4xEQ/wD+4rbEqJ7yhbynnfiJAiUBCAG07P7M/vL+s/4aTv6aAUoCASsBEsffyAFp28ffyv6YAAAAAAIAVgAABIkFtgALABUAiwCyAAAAK7EHCzMzsgECACuxFAvptAoMAAENK7EKC+kBsBYvsADWsQsO6bALELEQASuxBBXpsRcBK7A2Gro+nvLEABUrCrAAELABwLALELAUwLMKCxQTK7MMCxQTKwOzAQoMFC4uLi6wQBqxEAsRErEGCDk5sAQRsAc5ALEMChESsAY5sBQRsAQ5MDEzASEgERAFEyMDIwMTMzI2NTQmKwECVgE1AUABvv6Q77rR/IGgqMHQh5imZgW2/pL+pGX9eQJg/aAC8qqfeW3+EgABACf/7AQjBcsAJgBmALIkAAArsQML6bIPAgArsRYD6QGwJy+wDNaxGRbpsBkQsQYBK7EhFumxKAErsRkMERKyCgMkOTk5sAYRswkPFh0kFzmwIRKwHjkAsQMkERKwADmwFhGzAQwTISQXObAPErASOTAxNzUWMzI2NTQmJy4BNTQkMzIWFwcuASMiBhUUHgEXHgIVFAQjIiYnorKivmmPl3UBCNdjq19CQqRFhqMiSmmTZzX+5/9qoSuqVJeETndRVap0u+smLpYmLIt3Nk1EPVhkeVDT6R0AAAAAAQC6AAAEtAW2AAcASgCyBgAAK7AFM7IBAgArsQAD6bEEBzIyAbAIL7AG1rEFDumxCQErsDYauj6Z8q4AFSsKsAYQsAfAsAUQsATAA7EEBy4usEAaADAxEzchByEBIwG6IQPZHv5o/umsARUFH5eX+uEFHwABAKT/7AV/BbYAFQB3ALITAAArsQoD6bIDAgArsQ4PMzMBsBYvsADWsQcO6bAHELEDASuxBA7psAQQsQ4BK7EPDumxFwErsDYauj6J8mEAFSsKDrAOELANwLAPELAQwACxDRAuLgGxDRAuLrBAGgGxDgQRErEKEzk5ALEDChESsAA5MDETNDcTMwMGFRQWMzI2NxMzAwIEIyImpBi9qr8WkpGsvyzNqs03/uP25t4Bf1F4A278hWpSdYevygO6/Dr++f3QAAAAAAEAvAAABR8FtgALAFEAsgsAACuyAAIAK7EBCDMzAbAML7AA1rEBDumxDQErsDYausBY+VwAFSsKsAAQsAvADrABELACwACwAi4BsQILLi6wQBoBALEACxESsAQ5MDETMxMWFTM2NwEzASO8qmEUBD1lAd+//PO0Bbb8XsSLkMIDn/pKAAEA3wAAB4EFtgAdAGcAsh0AACuwFDOyAAIAK7EJEjMzAbAeL7AA1rEBDumwARCwAyDWEbEdEOmwHS+xAxDpsAEQsRgBK7EKD+mxHwErsQMBERKxBQY5ObAYEbEJHDk5sAoSsBU5ALEAHRESsgUOGDk5OTAxEzMTFxQHMzY3ATMTFhUHMzY3ATMBIwMmNSMOAQEj36ofAgoGWUMBlbIrCQEJSzgBg7b9aKoxCAYZSP4srgW2/HtYYqDzjANg/KSZl1PgggN9+koDxYiSSKX8DgAB/5gAAATRBbYACwAmALIAAAArsAgzsgICACuwBTMBsAwvsQ0BKwCxAgARErEECjk5MDEjCQEzEwEzCQEjAwFoAlT++azLAbu6/dUBFrTV/h8DCAKu/c0CM/1K/QACgf1/AAAAAQC8AAAEwwW2AAgAfQCyBwAAK7AGM7IAAgArsQEDMzMBsAkvsAfWsQYO6bMBBgcIK7EADumwAC+xAQ7psQoBK7A2Gro+pvLqABUrCg6wBxCwCMCwBhCwBcC6wcPxFgAVKwqxBwgIsAAQsAjADrABELACwACyAgUILi4uAbICBQguLi6wQBoBADAxEzMTATMBAyMTvKqzAenB/Y1xrHcFtv0VAuv8Z/3jAiUAAAH/8AAABJMFtgAJAC4AsgAAACuxBwPpsgQCACuxAwzpAbAKL7ELASsAsQcAERKwATmxBAMRErAGOTAxIzcBITchBwEhBxAcA5z9cSADWhr8ZAK5IYkEkpuL+2+aAAAAAAIAYv/sBGAEXAASACAAXwCyDAAAK7IQAAArsRYJ6bIJAQArsgQBACuxHQnpAbAhL7AA1rETDumwExCxDAErsQsP6bEiASuxDBMRErMEEBYdJBc5sAsRsg0OGjk5OQCxHRYRErQACAcODSQXOTAxEzQSNjMyFhczNzMDIzcjBiMiJjcUFjMyNhI1NCYjIgYCYo76lVyQKAtDf+mFGgizxouerF5VYcB4cFtos2YBXtABZMpjXaz7uNHlxqhycbkBKZVneqz+2gAAAgA7/+wEOQYUABUAIgBbALIAAAArshAAACuxGQnpsgkBACuxHwnpsAEvAbAjL7AB1rECDumwAhCxHQErsQwO6bEkASuxAgERErMFBhAZJBc5sB0RsQkfOTkAsR8ZERK0BgwTFAUkFzkwMTMBMwYCBzM+ATMyFhUUAgYjIiYnIwcTFBYzMjYSNTQjIgYCOwFKqDM3MAldtWCNnon1mmGTJQpGh29pY6tosmDHdQYU8v7/rHZvxq3R/p3HZliqAVpudaIBK6jjvv7gAAAAAQBi/+wDqgRcABgAPQCyFgAAK7EQCemyBAEAK7EJCekBsBkvsADWsQ0O6bEaASsAsRAWERKwFDmwCRGyAAcTOTk5sAQSsAY5MDETNBIkMzIXByYjIgYCFRQWMzI2NxUGIyImYpQBBaOJgy94Y3C5aYV1SIA+fJjC1gGFyAFSvTONM5n+76CAjigbjz/WAAAAAgBi/+wEwwYUABQAIQBuALINAAArshIAACuxFwnpsgQBACuxHgnpsAovAbAiL7AA1rEVDumwFRCxDQErsQwQ6bAMELEKASuxCxPpsSMBK7ENFRESswQSFx4kFzmwDBGyDg8bOTk5sAoSsAY5ALEeFxEStAAHBg8OJBc5MDETNBI2MzIXMzY3EzMBIzcjDgEjIiY3FDMyNhI1NCYjIgYCYpD1mMJXChEcTqb+tosWCGWwXoucrLNeyHVsZ2WtaQFe1gFkwr6bdwFm+ezRfWjEquO7ASOXb3Sl/tUAAAIAYv/sA7QEXAAYACIAaACyFgAAK7EPCemyBAEAK7EgCum0GQoWBA0rsRkJ6QGwIy+wANaxDA7psAwQsR0BK7EHE+mxJAErsR0MERKzBA8WGSQXObAHEbESEzk5ALEPFhESsBM5sAoRsQASOTmxIBkRErAHOTAxEzQSNjMyFhUUBCEjBxQWMzI2NxUOASMiJhMzMjY1NCYjIgZilfaUmZr+tP7LIQR7gT+FY16QV7jSyQzk80lOZ7UBh7wBWcCFd7TNUIOTJDCSLCPaAaR3cTVGvAAAAf8b/hQDgwYfACAApwCyFwEAK7EaB+mwBjKwGhCxCATpsgkBACuwHi+xAgnpsBMvsQ0J6QGwIS+xIgErsDYauj6j8twAFSsKDrAFELAKwLEbEvmwFsAFsAUQswYFChMrswkFChMrsBsQsxcbFhMrsxobFhMrAwCzBQoWGy4uLi4BtwUGCQoWFxobLi4uLi4uLi6wQBoAsQIeERKwIDmwGhGwADmxExcRErARObANEbAQOTAxAxYzMjY3EyM/Aj4BMzIWFwcmIyIGDwEzByMDDgEjIiflQDBMUhnjwQ3OFy6joCh0ICtMPVddHRnuGe3oJ6KERTj+thZ8cwQ6Q0JkyKUXDoEdYYFsf/u2va4VAAAD/4H+FARMBFwAKAA1AEMA8QCyEAEAK7FABemwEjKyDgEAK7FAB+mwJi+xLAjpsBgvsTkG6QGwRC+wANaxKRLpsCkQsQsBK7E2EumwBSDWEbEcEemwNhCxPQErsRUS6bAVELAjINYRsS8S6bAvL7EjEumxRQErsDYauvhlwHQAFSsKDrAzELAywLEfA/mwIcCzIB8hEyuyIB8hIIogiiMGDhESOQCzHyAyMy4uLi4Bsx8gMjMuLi4usEAaAbEcCxESsAM5sDYRsggmLDk5ObAvErQOGhg5QCQXObEVIxESsBM5ALEYLBESswAFHCMkFzmwORGxCBo5ObBAErELFTk5MDEHNDY3JjU0NjcuATU0NjMyFyEPARYVFAYjIicGFRQWHwEeARUUBCEiJjcUFjMyNjU0Ji8BDgEBFBYzMj4BNTQmIyIOAX+QoU5mWz9Q77pOTAFzGdMp6cM3HYtCP3W1o/7c/vfC3KKCgLbNbIKfeIABFlpQT3Y/WFJOdUHTaZo2KVBFYysgfVPC+BRrGD5gv+MINU4pGwgOFoSAuMqTlk1af3Q+SA4QGX4DElVZVJNWUlZRkQAAAAEAOwAABCkGFAAdAOgAsgAAACuxEh0zM7ILAQArsRgJ6bABL7ACMwGwHi+wANaxHQ7psB0QsRYBK7EODumzEg4WCCuxEw7psBMvsRIO6bEfASuwNhq6PpzyuQAVKwqwABCwAcCwHRCwAsC6PpzyuQAVKwuzAx0CEyuzBB0CEyuzBR0CEyuzBh0CEyuzBx0CEyuzHB0CEyuyHB0CIIogiiMGDhESObAHObAFObAGObAEObADOQC1BxwDBAUGLi4uLi4uAbcBAgccAwQFBi4uLi4uLi4usEAaAbETHRESsAg5sBIRsQsYOTkAsRgAERKxCA45OTAxMwEzDgMHMz4BMzIWFRQHBgMjEzY1NCMiDgEHAzsBSqgSISMpGwtet2SDjxcnaqiUEpNZqYEhZQYUUpqfrmZ7apCEPmjB/iECtF4plHbhn/4nAAACADsAAAIfBd8AAwAOAFkAsgAAACuwAzOyAQEAK7ACM7AML7EHDekBsA8vsADWsQMO6bADELEBASuxAg7psAQg1hGxCRfpsRABK7A2Gro+l/KjABUrCgMBsEAasQIEERKxBww5OQAwMTMTMwMTNDYzMhUUBiMiJjvqqOpxQDNYQywoNARI+7gFYDhHWjdMMQAC/v7+FAIdBd8ADAAXAHMAsgUBACuwBjOwCi+xAgnpsBUvsRAN6QGwGC+wBdaxBhPpsA0g1hGxEhfpsRkBK7A2Gro+o/LdABUrCg6wBRCwBMCwBhCwB8AAsQQHLi4BsQQHLi6wQBoBsQYNERKxEBU5OQCxAgoRErAMObAFEbAAOTAxARYzMjcBMwEOASMiJwE0NjMyFRQGIyIm/v49On0rAQim/vYknYdFNgJWQDNWQywmNP62Fs0E2/sWq58VBzc4R1o3TDEAAAEAOQAABCEGFAAOAJ8AsgAAACuxCg4zM7IHAQArsAEvsAIzAbAPL7AA1rEODumwDhCxAQErsQIO6bEQASuwNhq6PrTzLgAVKwq6PpzyuQAVKwuwDhCzAw4CEyuzBA4CEyuzDQ4CEyuyDQ4CIIogiiMGDhESObADObAEOQCyDQMELi4uAbINAwQuLi6wQBoBsQEOERKxBQY5ObACEbAMOQCxBwARErEFDDk5MDEzATMKAQczATMJASMDBwM5AUqqSHItBAIOyf4rASe765hSBhT+sP3sgQIZ/i39iwIMe/5vAAAAAAEAOQAAAi0GFAADAD0AsgAAACuwAzOwAS+wAjMBsAQvsADWsQMO6bADELEBASuxAg7psQUBK7A2Gro+l/KlABUrCgMBsEAaADAxMwEzATkBTKj+tAYU+ewAAAAAAQA7AAAGhwRcACwAwACyAAAAK7IUICEzMzOyAQEAK7IHAQArsA4zsScJ6bAbMgGwLS+wANaxLA7psCwQsQEBK7ECEOmwAhCxIQErsSAO6bAgELEYASuxEQ7psxQRGAgrsRUO6bAVL7EUDumxLgErsDYauj6V8psAFSsKDrAhELAiwLAgELAfwACxHyIuLgGxHyIuLrBAGgGxAgERErEDBDk5sSAhERKxByc5ObAVEbEKCzk5sBQSsQ4bOTkAsScAERK0AwQKCxEkFzkwMTMTMwczPgEzMhYXMz4BMzIWFRQHAyMTNjU0JiMiDgEHAyMTNjU0JiMiDgEHAzvqixYKV61ccXoLCFbCY3+LFpCqlBRFSlGedx9rqJQSPktUn3khZQRIy3dognR9eYiCRG79YAK0aCo+S3TVkv4MArReKUZOeN+d/iUAAAEAOwAABCkEXAAZAJsAsgAAACuxDQ4zM7IBAQArsgcBACuxFAnpAbAaL7AA1rEZDumwGRCxAQErsQIQ6bACELERASuxCg7psw0KEQgrsQ4O6bAOL7ENDumxGwErsDYauj7o9DkAFSsKDrAOELAPwLANELAMwACxDA8uLgGxDA8uLrBAGgGxAgERErEDBDk5sQ0OERKxBxQ5OQCxFAARErIDBAo5OTkwMTMTMwczPgEzMhYVFAcDIxM2NTQmIyIOAQcDO+qLFgpgs2B/kxePqpQUR05ZqYEhZQRIy3pli31PZf1gArRoKD9MeN6e/iUAAAIAYv/wBB0EVgANABsARACyCwAAK7ERCemyBAEAK7EYCekBsBwvsADWsQ4O6bAOELEVASuxBxXpsR0BK7EVDhESsQQLOTkAsRgRERKxBwA5OTAxEzQSNjMyFhUUAgYjIiY3FBYzMjYSNTQmIyIGAmKS+Je+3JD2m8DarH93aKZdfWttrV8Blr4BT7Phxbz+srbiu4OPkgENrXOPlP75AAAC/9X+FAQ5BFoAFQAiAG4Asg0AACuxGQnpsgEBACuyBgEAK7EfCemwAC8BsCMvsADWsRUT6bAVELEBASuxAhDpsAIQsR0BK7EJDumxJAErsQEVERKwEDmwAhGyAwQWOTk5sB0SswYNGR8kFzkAsR8ZERK0BAkQEQMkFzkwMQMBMwczNjMyFhUUAgYjIiYnIwcOAQMTFBYzMjYSNTQjIgYCKwFQixoIs8GJnor0mmGSKAoEAw9rxG9pY6tosmDHdf4UBjTR48Ow1P6exWRaJhla/gMDRm51ogErqOO+/uAAAAIAYv4UBGAEXAAVACIAWwCyEwAAK7EYCemyCQEAK7IEAQArsR8J6bAMLwGwIy+wANaxFg7psBYQsQwBK7ELE+mxJAErsQwWERKxExg5ObALEbMEDxAfJBc5ALEfGBEStAAIBxAPJBc5MDETNBI2MzIWFzM3MwEjEzY3Iw4BIyImNxQzMjYSNTQmIyIGAmKR95dejyUNQ33+sKZlCTAIX7RgjJ+ss1zEeW1iZbBoAV7UAWjCZVus+cwB4C2weWzDq+O4ASKbaXqp/tcAAAEAOwAAA2gEXAASAEwAsgAAACuyAQEAK7ENCOmyCAEAK7ENA+mwCzIBsBMvsADWsRIO6bASELEBASuxAhDpsRQBK7ECARESsQMEOTkAsQ0AERKxAwQ5OTAxMxMzBzM+AjMyFwcmIyIOAQcDO+qLFgpIXmc/RTMkNTRbn3ccawRIy19TLQ6WDXjVgv4KAAAAAAEACP/sA0QEXAAkAGQAsiMAACuxBAnpshABACuxFgrpAbAlL7AN1rEZDumwGRCxBwErsSAO6bEmASuxGQ0RErALObAHEbUEChAWHCMkFzmwIBKwHTkAsQQjERKwADmwFhGzAQ0TICQXObAQErASOTAxNzUeATMyNjU0JicuATU0NjMyFwcnJiMiBhUUFhceAhUUBiMiCEaiRX6ARnSCbMqlq582OGV3XWpHb2tdLt3JqTGeKi5kTjlOREmMYIqpSokZK1dFOFA/PFZjPpyvAAABAFr/7ALbBUQAGgB5ALIUAAArsQ4J6bIFAQArsQgH6bAaMrIFCAors0AFAwkrAbAbL7AX1rELDumxHAErsDYauj6X8qIAFSsKsBouDrAZwAWxCBP5DrAJwACxCRkuLgGzCAkZGi4uLi6wQBoBALEOFBESsBE5sAgRsRAXOTmwBRKwATkwMRM/AjMHIQchAwYVFBYzMjcVDgEjIiY1NDcTWg65fWI3ARIa/u+BEjo0N1kiZB59hRJ/A8lJTuT8f/2kVy04PBqBDhR3dkJUAloAAQBx/+wEXgRIABgAaQCyEQAAK7IWAAArsQkJ6bIDAQArsA4zAbAZL7AA1rEHDumzAwcACCuxBA7psAcQsREBK7EQEOmwEBCxDgErsQ8T6bEaASuxBAcRErEJFjk5sRARERKxEhM5OQCxAwkRErIAEhM5OTkwMTc0NxMzAwYVFDMyPgE3EzMDIzcjDgEjIiZxFpKqlhKTWKqCImSm54sWDGKyX4CS+D5uAqT9SVkyj3jgngHb+7jLfWKLAAABAGIAAAQSBEgACwBRALILAAArsgABACuxAQgzMwGwDC+wANaxAQ7psQ0BK7A2GrrAWflbABUrCrAAELALwA6wARCwAsAAsAIuAbECCy4usEAaAQCxAAsRErAEOTAxEzMTEhUzEjcBMwEjYqhAGAZ/NAFFsv2x5ARI/Zv+/mgBE2ACXPu4AAAAAQB1AAAGBgRIAB8AbACyHgAAK7AVM7EFCumwDzKyAAEAK7EJEzMzAbAgL7AA1rEBEumwARCwAyDWEbEfEOmwHy+xAxDpsAEQsRkBK7EOEumxIQErsQMBERKwBjmwGRGxCR45ObAOErEKFjk5ALEABRESsRobOTkwMRMzExUUBzM2NwEzExYdAQczNhIBMwEjAyY9ASMPAQEjdaQSCAYvWgEntiUGAgYcbgEMsv4GzSAECTJT/t3KBEj9rliTenzGAnX9rqheNSpWAQkCWPu4AlpeTpx2vf2RAAAAAAH/tgAABAYESAALACYAsgAAACuwCDOyAgEAK7AFMwGwDC+xDQErALECABESsQQKOTkwMSMBAzMTATMBEyMDAUoB2++qrgFKwv45/KjA/qYCNQIT/mQBnP3l/dMBsv5OAAH/O/4UBBIESAAYAF0AsgcBACuxCBEzM7AWL7ECCekBsBkvsAfWsQgO6bEaASuwNhq6wJX3ZAAVKwoOsAcQsAbAsAgQsAnAALEGCS4uAbEGCS4usEAaAQCxAhYRErAYObAHEbEADDk5MDEDFjMyNj8BAzMTFhIVMz4BNwEzAQ4BIyInxT9EUnU3TKaoSgoTBiNoGQFFsv1IXbaASET+sBJlY4gEWv3fRf7zUlfiKwJh+v6shhUAAAAB/+MAAAN9BEgACQAsALIAAAArsQcH6bIEAQArsQMH6QGwCi+xCwErALEHABESsAE5sAMRsAY5MDEjNwEhNyEHASEHHRcCtv4hGwKRHf1YAhMZdQNWfYz8wX0AAAEAAAAABEcERwADACcAsgAAACuyAQEAKwGwBC+wANa0AxcABwQrtAMXAAcEK7EFASsAMDExESERBEcER/u5AAABAAAAARmaXJNtGl8PPPUAHwgAAAAAANJD0icAAAAA0kPSJ/7B/hQHgQYfAAIACAACAAAAAAAAAAEAAAhi/bMAAAb6/sH+/geBAGQAFQAAAAAAAAAAAAAAAAA5AuwARAAAAAAEFAAAAhQAAARx/4sEyQBWBK4AlgVUAFYEFwBWA8cAVgVqAJYFbQBWAi8AVgIj/sEEdQBWA8sAVgayAFQFngBUBcMAlgSHAFYFwwCWBI0AVgQEACcD/AC6BWgApARiALwG0QDfBCf/mAQGALwEP//wBIUAYgSeADsDmgBiBJ4AYgPyAGICgf8bBAL/gQSeADsCCAA7Agj+/gPnADkCCAA5BvoAOwSeADsEfQBiBJ7/1QSeAGIDKwA7A20ACAKYAFoEngBxA7IAYgW8AHUD0/+2A7L/OwON/+MERwAAAAAALAAsACwALACKAQYBUAGmAfYCPgKyAx4DTAOWA/oELgTUBTYFjAXqBkwGugcoB2IHxggICHAIogj4CSgJjAnyCjoKqAsSC5oMdg0aDWINxg44DmYPCg+CD9IQQhCoEPARWBHAEh4SYhLQEwATXBOKE6oAAQAAADkARAADAAAAAAACAAEAAgAWAAABAAD2AAAAAAAAABIA3gADAAEECQAAAHIAAAADAAEECQABABIAcgADAAEECQACAAwAhAADAAEECQADAEoAkAADAAEECQAEACAA2gADAAEECQAFABgA+gADAAEECQAGAB4BEgADAAEECQAHAKQBMAADAAEECQAIACgB1AADAAEECQALADgB/AADAAEECQAMAFwCNAADAAEECQANAFwCkAADAAEECQAOAFQC7AADAAEECQDIABYDQAADAAEECQDJADADVgADAAEECQDKAA4DhgADAAEECQDLAAwDlAADAAEECdkDABoDoABEAGkAZwBpAHQAaQB6AGUAZAAgAGQAYQB0AGEAIABjAG8AcAB5AHIAaQBnAGgAdAAgAKkAIAAyADAAMQAwAC0AMgAwADEAMQAsACAARwBvAG8AZwBsAGUAIABDAG8AcgBwAG8AcgBhAHQAaQBvAG4ALgBPAHAAZQBuACAAUwBhAG4AcwBJAHQAYQBsAGkAYwBBAHMAYwBlAG4AZABlAHIAIAAtACAATwBwAGUAbgAgAFMAYQBuAHMAIABJAHQAYQBsAGkAYwAgAEIAdQBpAGwAZAAgADEAMAAwAE8AcABlAG4AIABTAGEAbgBzACAASQB0AGEAbABpAGMAVgBlAHIAcwBpAG8AbgAgADEALgAxADAATwBwAGUAbgBTAGEAbgBzAC0ASQB0AGEAbABpAGMATwBwAGUAbgAgAFMAYQBuAHMAIABpAHMAIABhACAAdAByAGEAZABlAG0AYQByAGsAIABvAGYAIABHAG8AbwBnAGwAZQAgAGEAbgBkACAAbQBhAHkAIABiAGUAIAByAGUAZwBpAHMAdABlAHIAZQBkACAAaQBuACAAYwBlAHIAdABhAGkAbgAgAGoAdQByAGkAcwBkAGkAYwB0AGkAbwBuAHMALgBBAHMAYwBlAG4AZABlAHIAIABDAG8AcgBwAG8AcgBhAHQAaQBvAG4AaAB0AHQAcAA6AC8ALwB3AHcAdwAuAGEAcwBjAGUAbgBkAGUAcgBjAG8AcgBwAC4AYwBvAG0ALwBoAHQAdABwADoALwAvAHcAdwB3AC4AYQBzAGMAZQBuAGQAZQByAGMAbwByAHAALgBjAG8AbQAvAHQAeQBwAGUAZABlAHMAaQBnAG4AZQByAHMALgBoAHQAbQBsAEwAaQBjAGUAbgBzAGUAZAAgAHUAbgBkAGUAcgAgAHQAaABlACAAQQBwAGEAYwBoAGUAIABMAGkAYwBlAG4AcwBlACwAIABWAGUAcgBzAGkAbwBuACAAMgAuADAAaAB0AHQAcAA6AC8ALwB3AHcAdwAuAGEAcABhAGMAaABlAC4AbwByAGcALwBsAGkAYwBlAG4AcwBlAHMALwBMAEkAQwBFAE4AUwBFAC0AMgAuADAAVwBlAGIAZgBvAG4AdAAgADEALgAwAFcAZQBkACAATwBjAHQAIAAxADQAIAAwADUAOgAzADQAOgAzADEAIAAyADAAMQA1AGQAZQBmAGEAdQBsAHQAdABhAHUAcgB1AHMARgBvAG4AdAAgAFMAcQB1AGkAcgByAGUAbAACAAD/9AAA/2YAZgAAAAAAAAAAAAAAAAAAAAAAAAAAADkAAAECAQMAAwAkACUAJgAnACgAKQAqACsALAAtAC4ALwAwADEAMgAzADQANQA2ADcAOAA5ADoAOwA8AD0ARABFAEYARwBIAEkASgBLAEwATQBOAE8AUABRAFIAUwBUAFUAVgBXAFgAWQBaAFsAXABdAQQGZ2x5cGgxB3VuaTAwMEQHdW5pMjVGQwC4Af+FsAGNAEuwCFBYsQEBjlmxRgYrWCGwEFlLsBRSWCGwgFkdsAYrXFgAsAMgRbADK0SwCyBFsgPRAiuwAytEsAogRbILgAIrsAMrRLAJIEWyClgCK7ADK0SwCCBFsgk9AiuwAytEsAcgRbIIMAIrsAMrRLAGIEWyByICK7ADK0SwBSBFsgZhAiuwAytEsAQgRbIFFQIrsAMrRLAMIEW6AAMBFAACK7ADK0SwDSBFsgwTAiuwAytEAbAOIEWwAytEsBMgRboADgEDAAIrsQNGditEsBIgRbITiwIrsQNGditEsBEgRbISTwIrsQNGditEsBAgRbIRKwIrsQNGditEsA8gRbIQHwIrsQNGditEsBQgRboADn//AAIrsQNGditEsBUgRbIUxgIrsQNGditEsBYgRbIVWgIrsQNGditEsBcgRbIWKQIrsQNGditEWbAUKwAAAAFWHiGnAAA=) format(&apos;truetype&apos;);font-weight:400;font-style:normal}.st1{fill:#c6dd7f}.st2{fill:#e9ddb7}.st3{fill:#a6d0e4}.st4{fill:#e6e6e6;stroke:#000;stroke-miterlimit:10}.st5{font-family:&apos;open_sanssemibold&apos;,sans-serif}.st6{font-size:16px}.st7{fill:#bef0f0;stroke:#000;stroke-miterlimit:10}.st11{font-family:&apos;open_sansitalic&apos;,sans-serif}</style><pattern width="144.13" height="138.362" patternUnits="userSpaceOnUse" id="Alysse" viewBox="99.963 -216.829 144.13 138.362" overflow="visible"><path fill="none" d="M99.963-216.829h144.13v138.362H99.963z"/><path class="st1" d="M311.036-58.307c-11.76-1.384-19.369.346-22.654 3.113-3.02 2.543-4.955 5.405-2.248 11.932 2.939 7.091 1.533 14.732-5.535 15.91-6.225 1.037-10.895-4.842-11.24-12.278-.24-5.183-1.902-8.301-5.533-7.608-3.633.691-4.629 5.9-3.633 11.759 1.385 8.128 5.535 11.76 6.227 20.233.494 6.055-2.939 13.662-12.451 15.045-9.301 1.354-15.91-4.322-16.602-10.549-.732-6.588 3.631-10.894 3.111-17.639-.518-6.745-4.012-10.172-5.879-17.294-2.768-10.549 1.211-19.022 7.781-22.654 14.746-8.148 22.832 3.642 35.971 1.556 10.897-1.729 23.348-18.157 33.031-19.541 8.227-1.175 13.834 4.669 15.045 14.008 1.211 9.338-4.74 15.261-15.391 14.007zm-42.195.519a4.15 4.15 0 10-8.301.001 4.15 4.15 0 008.301-.001zM318.3-73.179a1.728 1.728 0 10-3.458 0 1.728 1.728 0 103.458 0z"/><path class="st2" d="M148.796-77.494c0 7.166 4.588 13.813-1 16.333-8.5 3.833-28-14.333-28-36.167 0-12 8.668-19 17.834-19 12.334 0 18 8.167 18 17.5 0 9.332-6.834 13.139-6.834 21.334zm-5.409-5.37a2.075 2.075 0 10-4.15 0 2.075 2.075 0 004.15 0z"/><path class="st3" d="M223.494-54c-7.871 2.737-19.439-15.297-17.67-27.019 1.24-8.228 7.123-13.189 13.088-14.217 7.525-1.297 12.898 2.601 13.299 7.243.547 6.309-3.633 7.518-4.223 14.958-.562 7.135 3.692 16.186-4.494 19.035zm-3.789-27.508a2.594 2.594 0 10-5.189-.001 2.594 2.594 0 005.189.001z"/><path class="st2" d="M119.35-76.465a2.594 2.594 0 11-5.188 0 2.594 2.594 0 015.188 0z"/><path class="st3" d="M184.573-84.189c.74 8.101 12.671 7.017 17.904 14.214 10.52 14.475-1.219 46.365-21.63 46.365-11.74 0-24.217-9.719-24.217-29.219 0-15.834 10.166-21.5 8.25-42.166-1.006-10.834-12.5-20.343-12.5-34.75 0-5.922 3.586-13.447 11.553-13.447 7.055 0 10.822 5.953 10.822 12.9 0 6.798-5.381 15.74 1.375 19.047 5.242 2.565 13.211-4.77 19.499-6.75 5.191-1.636 12.389.225 14.75 8.5 2.531 8.876-3.252 14.745-11.592 16.693-6.318 1.477-14.802 2.172-14.214 8.613zm-15.984-30.558a3.286 3.286 0 10-6.573-.001 3.286 3.286 0 006.573.001zm25.983 9.695a2.33 2.33 0 10-.003-4.659 2.33 2.33 0 00.003 4.659zM174.589-45.38a3.287 3.287 0 10-6.574 0 3.287 3.287 0 006.574 0z"/><path class="st1" d="M166.907-58.307c-11.76-1.384-19.369.346-22.654 3.113-3.02 2.543-4.955 5.405-2.248 11.932 2.939 7.091 1.533 14.732-5.535 15.91-6.225 1.037-10.895-4.842-11.24-12.278-.24-5.183-1.902-8.301-5.533-7.608-3.633.691-4.629 5.9-3.633 11.759 1.385 8.128 5.535 11.76 6.227 20.233.494 6.055-2.939 13.662-12.451 15.045-9.301 1.354-15.91-4.322-16.602-10.549-.732-6.588 3.631-10.894 3.111-17.639-.517-6.745-4.012-10.172-5.879-17.294-2.768-10.549 1.211-19.022 7.781-22.654 14.746-8.148 22.832 3.642 35.971 1.556 10.896-1.729 23.348-18.157 33.031-19.541 8.227-1.175 13.834 4.669 15.045 14.008 1.21 9.338-4.741 15.261-15.391 14.007zm-42.196.519a4.15 4.15 0 10-8.301.001 4.15 4.15 0 008.301-.001zm49.46-15.391a1.73 1.73 0 10-3.461.001 1.73 1.73 0 003.461-.001z"/><path class="st3" d="M290.284-104.841c0 6.227-4.15 10.721-8.646 11.586-4.496.865-8.318-1.281-12.971 1.211-4.842 2.594-7.09 11.068-16.775 11.068-7.955 0-15.217-7.955-15.217-18.85 0-20.234 13.143-29.226 25.594-29.226 16.601 0 28.015 12.625 28.015 24.211zm-19.714-14.354c0-2.1-1.703-3.803-3.805-3.803a3.804 3.804 0 100 7.608 3.805 3.805 0 003.805-3.805z"/><path class="st1" d="M311.036-196.669c-11.76-1.384-19.369.346-22.654 3.113-3.02 2.543-4.955 5.405-2.248 11.932 2.939 7.091 1.533 14.732-5.535 15.91-6.225 1.037-10.895-4.842-11.24-12.278-.24-5.183-1.902-8.301-5.533-7.608-3.633.691-4.629 5.9-3.633 11.759 1.385 8.128 5.535 11.76 6.227 20.233.494 6.055-2.939 13.662-12.451 15.045-9.301 1.354-15.91-4.322-16.602-10.549-.732-6.588 3.631-10.895 3.111-17.639-.518-6.745-4.012-10.172-5.879-17.294-2.768-10.549 1.211-19.023 7.781-22.654 14.746-8.148 22.832 3.642 35.971 1.556 10.897-1.729 23.348-18.157 33.031-19.541 8.227-1.175 13.834 4.669 15.045 14.008 1.211 9.338-4.74 15.261-15.391 14.007zm-42.195.518a4.15 4.15 0 10-8.301.001 4.15 4.15 0 008.301-.001zm49.459-15.39a1.728 1.728 0 10-3.458 0 1.728 1.728 0 103.458 0z"/><path class="st3" d="M131.796-133.191c-13.957 1.988-21.166-13.332-17.666-20.332 3.666-7.334 12.119-4.168 19.5-4.168 9.666 0 16.367-7.568 20.416-2.25 4.25 5.584-5.01 24.295-22.25 26.75zm.523-17.478a2.249 2.249 0 10-4.497.001 2.249 2.249 0 004.497-.001z"/><path class="st2" d="M148.796-215.857c0 7.166 4.588 13.813-1 16.333-8.5 3.833-28-14.333-28-36.167 0-12 8.668-19 17.834-19 12.334 0 18 8.167 18 17.5 0 9.332-6.834 13.14-6.834 21.334zm-5.409-5.369a2.075 2.075 0 10-4.15 0 2.075 2.075 0 004.15 0z"/><path class="st3" d="M146.155-104.841c0 6.227-4.15 10.721-8.646 11.586-4.496.865-8.318-1.281-12.971 1.211-4.842 2.594-7.09 11.068-16.775 11.068-7.955 0-15.217-7.955-15.217-18.85 0-20.234 13.143-29.226 25.594-29.226 16.601 0 28.015 12.625 28.015 24.211zm-19.715-14.354c0-2.1-1.703-3.803-3.805-3.803a3.804 3.804 0 100 7.608 3.804 3.804 0 003.805-3.805z"/><path class="st1" d="M145.464-128.533a2.421 2.421 0 11-4.842-.002 2.421 2.421 0 014.842.002z"/><path class="st3" d="M229.162-147.037c-3.191 4.68 1.039 10.721-1.383 15.217-2.422 4.498-6.744 5.016-9.857 2.596-3.635-2.828-3.41-6.643-8.301-8.82-5.529-2.465-17.984 2.248-19.714-7.264-.875-4.811 2.375-8.566 7.263-9.684 6.053-1.383 9.352-.18 15.391-3.113 6.053-2.939 11.242-8.993 22.137-12.105 10.406-2.975 16.072 1.557 16.602 5.879 1.036 8.474-17.128 9.949-22.138 17.294zm-2.248-7.437a2.249 2.249 0 10-4.497.001 2.249 2.249 0 004.497-.001z"/><path class="st2" d="M256.129-107.857c0 17.166-14.5 25.5-27 22.832-10.264-2.19-12.834-17.332-16.668-26.166-3.713-8.557-8.832-22.5-20.165-22.5-11.197 0-12.832 14.5-23.666 14.5-11 0-24.5-15.666-24.5-39.666 0-14.667 9.799-31.455 20.834-30.667 11.666.833 4.5 19.667 15.332 19.667 9.5 0 7.857-16.259 9.168-23.334 1.666-9 6.831-14.166 18.497-13.166 14.443 1.237 22.334 13.5 18.871 23.344-4.029 11.451-23.869 17.322-21.537 30.49 1.346 7.592 13 11.998 26 16.166 14.529 4.656 24.834 11.332 24.834 28.5zM211.178-183.7a3.286 3.286 0 106.571 0 3.286 3.286 0 00-6.571 0zm-46.693 24.904a1.73 1.73 0 10-3.458-.002 1.73 1.73 0 003.458.002zm17.467 10.72a3.804 3.804 0 10-7.61 0 3.806 3.806 0 007.61 0zm19.888-15.563a1.557 1.557 0 10-3.113.001 1.557 1.557 0 003.113-.001zm29.642 54.694a3.174 3.174 0 10-6.348 0 3.174 3.174 0 006.348 0z"/><path class="st3" d="M223.494-192.363c-7.871 2.737-19.439-15.297-17.67-27.018 1.24-8.228 7.123-13.189 13.088-14.217 7.525-1.297 12.898 2.6 13.299 7.243.547 6.309-3.633 7.518-4.223 14.958-.562 7.135 3.692 16.186-4.494 19.034zm-3.789-27.508a2.594 2.594 0 10-5.189-.001 2.594 2.594 0 005.189.001z"/><path class="st2" d="M119.35-214.828a2.594 2.594 0 11-5.188 0 2.594 2.594 0 015.188 0zm133.998 86.737c0-8.41-5.078-15.227-11.34-15.227s-11.34 6.816-11.34 15.227c0 8.408 5.078 12.441 11.34 12.441s11.34-4.033 11.34-12.441z"/><path class="st3" d="M184.573-222.551c.74 8.101 12.671 7.017 17.904 14.214 10.52 14.475-1.219 46.365-21.63 46.365-11.74 0-24.217-9.719-24.217-29.219 0-15.834 10.166-21.5 8.25-42.166-1.006-10.834-12.5-20.343-12.5-34.75 0-5.922 3.586-13.447 11.553-13.447 7.055 0 10.822 5.953 10.822 12.9 0 6.798-5.381 15.74 1.375 19.047 5.242 2.565 13.211-4.77 19.499-6.75 5.191-1.636 12.389.225 14.75 8.5 2.531 8.876-3.252 14.745-11.592 16.693-6.318 1.477-14.802 2.171-14.214 8.613zm-15.984-30.559a3.286 3.286 0 10-6.573-.001 3.286 3.286 0 006.573.001zm25.983 9.695a2.33 2.33 0 10-.003-4.659 2.33 2.33 0 00.003 4.659zm-19.983 59.672a3.287 3.287 0 10-6.574 0 3.287 3.287 0 006.574 0z"/><path class="st1" d="M166.907-196.669c-11.76-1.384-19.369.346-22.654 3.113-3.02 2.543-4.955 5.405-2.248 11.932 2.939 7.091 1.533 14.732-5.535 15.91-6.225 1.037-10.895-4.842-11.24-12.278-.24-5.183-1.902-8.301-5.533-7.608-3.633.691-4.629 5.9-3.633 11.759 1.385 8.128 5.535 11.76 6.227 20.233.494 6.055-2.939 13.662-12.451 15.045-9.301 1.354-15.91-4.322-16.602-10.549-.732-6.588 3.631-10.895 3.111-17.639-.517-6.745-4.012-10.172-5.879-17.294-2.768-10.549 1.211-19.023 7.781-22.654 14.746-8.148 22.832 3.642 35.971 1.556 10.896-1.729 23.348-18.157 33.031-19.541 8.227-1.175 13.834 4.669 15.045 14.008 1.21 9.338-4.741 15.261-15.391 14.007zm-42.196.518a4.15 4.15 0 10-8.301.001 4.15 4.15 0 008.301-.001zm49.46-15.39a1.73 1.73 0 10-3.461.001 1.73 1.73 0 003.461-.001zm56.03 37.18a1.384 1.384 0 11-2.768 0 1.384 1.384 0 012.768 0z"/><path class="st2" d="M235.734-212.752a2.248 2.248 0 11-4.497.001 2.248 2.248 0 014.497-.001z"/><path class="st3" d="M152.208-189.58a1.212 1.212 0 01-2.422 0 1.212 1.212 0 012.422 0zm-3.633 68.483c0 .764-.619 1.385-1.383 1.385a1.384 1.384 0 010-2.768c.764 0 1.383.619 1.383 1.383z"/><path class="st2" d="M233.141-143.06a1.21 1.21 0 11-2.42.001 1.21 1.21 0 012.42-.001z"/><path class="st1" d="M195.852-125.134a3.408 3.408 0 11-6.816 0 3.408 3.408 0 016.816 0z"/><path class="st2" d="M200.832-85.283a2.097 2.097 0 11-4.193-.001 2.097 2.097 0 014.193.001zm-38.802-6.293a1.573 1.573 0 11-3.147-.001 1.573 1.573 0 013.147.001z"/><path class="st1" d="M235.701-205.623a2.622 2.622 0 11-5.243-.001 2.622 2.622 0 015.243.001z"/><path class="st3" d="M225.477-170.754a2.36 2.36 0 11-4.719 0 2.36 2.36 0 014.719 0z"/><path class="st2" d="M127.686-164.2a2.622 2.622 0 11-5.245 0 2.622 2.622 0 015.245 0z"/><path class="st3" d="M122.704-171.279a1.31 1.31 0 11-2.62.001 1.31 1.31 0 012.62-.001z"/><path class="st2" d="M186.938-119.367a1.573 1.573 0 11-3.145-.001 1.573 1.573 0 013.145.001z"/><path class="st3" d="M85.033-147.037c-3.191 4.68 1.039 10.721-1.383 15.217-2.422 4.498-6.744 5.016-9.857 2.596-3.635-2.828-3.41-6.643-8.301-8.82-5.529-2.465-17.984 2.248-19.714-7.264-.875-4.811 2.375-8.566 7.263-9.684 6.053-1.383 9.352-.18 15.391-3.113 6.053-2.939 11.242-8.993 22.137-12.105 10.406-2.975 16.072 1.557 16.601 5.879 1.036 8.474-17.128 9.949-22.137 17.294zm-2.248-7.437a2.249 2.249 0 10-4.497.001 2.249 2.249 0 004.497-.001z"/><path class="st2" d="M111.999-107.857c0 17.166-14.5 25.5-27 22.832-10.264-2.19-12.834-17.332-16.668-26.166-3.713-8.557-8.832-22.5-20.165-22.5-11.197 0-12.832 14.5-23.666 14.5-11 0-24.5-15.666-24.5-39.666 0-14.667 9.799-31.455 20.834-30.667 11.666.833 4.5 19.667 15.332 19.667 9.5 0 7.857-16.259 9.168-23.334 1.666-9 6.832-14.166 18.497-13.166 14.443 1.237 22.334 13.5 18.871 23.344-4.029 11.451-23.869 17.322-21.537 30.49 1.346 7.592 13 11.998 26 16.166 14.53 4.656 24.834 11.332 24.834 28.5zM67.048-183.7a3.286 3.286 0 106.571 0 3.286 3.286 0 00-6.571 0zm-46.693 24.904a1.73 1.73 0 10-3.458-.002 1.73 1.73 0 003.458.002zm17.467 10.72a3.804 3.804 0 10-7.61 0 3.806 3.806 0 007.61 0zm19.888-15.563a1.557 1.557 0 10-3.113.001 1.557 1.557 0 003.113-.001zm29.643 54.694a3.174 3.174 0 10-6.348 0 3.174 3.174 0 006.348 0z"/><path class="st2" d="M109.218-128.091c0-8.41-5.078-15.227-11.34-15.227s-11.34 6.816-11.34 15.227c0 8.408 5.078 12.441 11.34 12.441s11.34-4.033 11.34-12.441z"/></pattern><path class="st4" d="M100 105H10a5 5 0 01-5-5V10a5 5 0 015-5h90a5 5 0 015 5v90a5 5 0 01-5 5z"/><text transform="translate(36.152 51.322)"><tspan x="0" y="0" class="st5 st6">Load</tspan><tspan x="-3.406" y="19.2" class="st5 st6">HTML</tspan></text><path class="st7" d="M235 105h-90a5 5 0 01-5-5V10a5 5 0 015-5h90a5 5 0 015 5v90a5 5 0 01-5 5z"/><text transform="translate(168.484 51.322)"><tspan x="0" y="0" class="st5 st6">Parse</tspan><tspan x="-.738" y="19.2" class="st5 st6">HTML</tspan></text><path class="st4" d="M235 240h-90a5 5 0 01-5-5v-90a5 5 0 015-5h90a5 5 0 015 5v90a5 5 0 01-5 5z"/><text transform="translate(171.152 186.322)"><tspan x="0" y="0" class="st5 st6">Load</tspan><tspan x="4.98" y="19.2" class="st5 st6">CSS</tspan></text><path class="st7" d="M370 240h-90a5 5 0 01-5-5v-90a5 5 0 015-5h90a5 5 0 015 5v90a5 5 0 01-5 5z"/><text transform="translate(303.484 186.322)"><tspan x="0" y="0" class="st5 st6">Parse</tspan><tspan x="7.648" y="19.2" class="st5 st6">CSS</tspan></text><path d="M490 105H280a5 5 0 01-5-5V10a5 5 0 015-5h210a5 5 0 015 5v90a5 5 0 01-5 5z" fill="#f0c8b4" stroke="#000" stroke-miterlimit="10"/><text transform="translate(359.477 51.322)"><tspan x="0" y="0" class="st5 st6">Create</tspan><tspan x="-11.918" y="19.2" class="st5 st6">DOM tree</tspan></text><path d="M625 105h-90a5 5 0 01-5-5V10a5 5 0 015-5h90a5 5 0 015 5v90a5 5 0 01-5 5z" fill="url(#Alysse)" stroke="#000" stroke-miterlimit="10"/><text transform="translate(550.773 59.597)" class="st6" font-family="'open_sansbold',sans-serif">Display</text><path d="M145 53.33l-11.25-6.495A2.502 2.502 0 00130 49v4h-25v5h25v3.99a2.502 2.502 0 003.75 2.165L145 57.66a2.502 2.502 0 000-4.33zm135 0l-11.25-6.495A2.502 2.502 0 00265 49v4h-25v5h25v3.99a2.502 2.502 0 003.75 2.165L280 57.66a2.502 2.502 0 000-4.33zm255 0l-11.25-6.495A2.502 2.502 0 00520 49v4h-25v5h25v3.99a2.502 2.502 0 003.75 2.165L535 57.66a2.502 2.502 0 000-4.33zm-336.84 77.92a2.502 2.502 0 00-2.165-1.25H192v-25h-5v25h-3.995a2.502 2.502 0 00-2.165 3.75l6.495 11.25a2.502 2.502 0 004.33 0l6.495-11.25a2.498 2.498 0 000-2.5zM280 188.33l-11.25-6.495A2.502 2.502 0 00265 184v4h-25v5h25v3.99a2.502 2.502 0 003.75 2.165L280 192.66a2.502 2.502 0 000-4.33zm173.28-78.08L446.785 99a2.5 2.5 0 00-4.33 0l-6.495 11.25a2.5 2.5 0 002.165 3.75h4.149c-1.272 24.495-8.289 43.332-20.947 56.042C409.952 181.463 393.933 187.5 375 187.5v5c20.291 0 37.535-6.546 49.869-18.93 13.599-13.655 21.105-33.68 22.407-59.57h3.839a2.5 2.5 0 002.165-3.75z"/><text transform="translate(446.363 159)"><tspan x="0" y="0" class="st11 st6">Attach style</tspan><tspan x="-9.98" y="19.2" class="st11 st6">to DOM nodes</tspan></text></svg> \ No newline at end of file diff --git a/files/en-us/learn_web_development/core/styling_basics/writing_modes_tasks/index.md b/files/en-us/learn_web_development/core/styling_basics/writing_modes_tasks/index.md deleted file mode 100644 index 574028d4a2af239..000000000000000 --- a/files/en-us/learn_web_development/core/styling_basics/writing_modes_tasks/index.md +++ /dev/null @@ -1,183 +0,0 @@ ---- -title: "Test your skills: Writing modes and logical properties" -slug: Learn_web_development/Core/Styling_basics/Writing_Modes_Tasks -page-type: learn-module-assessment ---- - -{{LearnSidebar}} - -The aim of this skill test is to assess whether you understand how to [handle different text directions using writing modes and logical properties in CSS](/en-US/docs/Learn_web_development/Core/Styling_basics/Handling_different_text_directions). - -> [!NOTE] -> Click **"Play"** in the code blocks below to edit the examples in the MDN Playground. -> You can also copy the code (click the clipboard icon) and paste it into an online editor such as [CodePen](https://codepen.io/), [JSFiddle](https://jsfiddle.net/), or [Glitch](https://glitch.com/). -> If you get stuck, you can reach out to us in one of our [communication channels](/en-US/docs/MDN/Community/Communication_channels). - -## Task 1 - -In this task, the box is displayed with a horizontal writing mode. Can you add a line of CSS to change it so it uses a vertical writing mode with right to left text? - -Your final result should look like the image below: - -![A box with a vertical writing mode](mdn-writing-modes1.png) - -Try to update the code below to recreate the finished example: - -```html live-sample___writing-mode -<div class="box">Turn me on my side.</div> -``` - -```css hidden live-sample___writing-mode -body { - font: 1.2em / 1.5 sans-serif; -} -``` - -```css live-sample___writing-mode -.box { - border: 5px solid rebeccapurple; - background-color: lightgray; - padding: 40px; - margin: 40px; -} -``` - -{{EmbedLiveSample("writing-mode", "", "250px")}} - -<details> -<summary>Click here to show the solution</summary> - -You should use the `writing-mode` property with a value of `vertical-rl` for vertical right-to-left script: - -```css -.box { - border: 5px solid rebeccapurple; - background-color: lightgray; - padding: 40px; - margin: 40px; - writing-mode: vertical-rl; -} -``` - -</details> - -## Task 2 - -In this task, we want you to use logical properties to replace `width` and `height` in order to maintain the {{glossary("aspect ratio")}} of the box as it is turned vertically. - -Your final result should look like the image below: - -![Two boxes one horizontal the other vertical](mdn-writing-modes2.png) - -Try to update the code below to recreate the finished example: - -```html live-sample___logical-width-height -<div class="box">Horizontal.</div> -<div class="box vertical">Vertical.</div> -``` - -```css hidden live-sample___logical-width-height -body { - font: 1.2em / 1.5 sans-serif; -} -``` - -```css live-sample___logical-width-height -.box { - border: 5px solid rebeccapurple; - background-color: lightgray; - padding: 40px; - margin: 40px; - width: 200px; - height: 100px; -} -``` - -{{EmbedLiveSample("logical-width-height", "", "500px")}} - -<details> -<summary>Click here to show the solution</summary> - -As well as setting `writing-mode: vertical-rl` on the `.vertical` box, you need to apply the `inline-size` and `block-size` properties to replace `width` and `height`: - -```css -.box { - border: 5px solid rebeccapurple; - background-color: lightgray; - padding: 40px; - margin: 40px; - inline-size: 200px; - block-size: 100px; -} -.vertical { - writing-mode: vertical-rl; -} -``` - -</details> - -## Task 3 - -In this task, we want you to use logical versions of the margin, border, and padding properties so that the edges of the box relate to the text rather than following top, left, bottom and right. - -Your final result should look like the image below: - -![Two boxes one horizontal one vertical with different margin, border and padding](mdn-writing-modes3.png) - -Try to update the code below to recreate the finished example: - -```html live-sample___logical-mbp -<div class="box">Horizontal.</div> -<div class="box vertical">Vertical.</div> -``` - -```css hidden live-sample___logical-mbp -body { - font: 1.2em / 1.5 sans-serif; -} -``` - -```css hidden live-sample___logical-mbp -.vertical { - writing-mode: vertical-rl; -} -``` - -```css live-sample___logical-mbp -.box { - width: 150px; - height: 150px; - border-top: 5px solid rebeccapurple; - border-right: 5px solid grey; - border-bottom: 5px dotted red; - border-left: 5px dotted blue; - padding-top: 40px; - margin-bottom: 30px; -} -``` - -{{EmbedLiveSample("logical-mbp", "", "500px")}} - -<details> -<summary>Click here to show the solution</summary> - -To solve this, you need an understanding of the logical, flow relative mappings for margin, border and padding physical properties: - -```css -.box { - width: 150px; - height: 150px; - border-block-start: 5px solid rebeccapurple; - border-inline-end: 5px solid grey; - border-block-end: 5px dotted red; - border-inline-start: 5px dotted blue; - padding-block-start: 40px; - margin-block-end: 30px; -} -``` - -</details> - -## See also - -- [CSS styling basics](/en-US/docs/Learn_web_development/Core/Styling_basics) diff --git a/files/en-us/learn_web_development/core/text_styling/fundamentals/index.md b/files/en-us/learn_web_development/core/text_styling/fundamentals/index.md index d1b2d55afa17074..2478883fb4f811a 100644 --- a/files/en-us/learn_web_development/core/text_styling/fundamentals/index.md +++ b/files/en-us/learn_web_development/core/text_styling/fundamentals/index.md @@ -1,11 +1,11 @@ --- title: Fundamental text and font styling +short-title: Text and font fundamentals slug: Learn_web_development/Core/Text_styling/Fundamentals page-type: learn-module-chapter +sidebar: learnsidebar --- -{{LearnSidebar}} - {{NextMenu("Learn_web_development/Core/Text_styling/Styling_lists", "Learn_web_development/Core/Text_styling")}} In this article we'll start you on your journey towards mastering text styling with {{glossary("CSS")}}. Here we'll go through all the basic fundamentals of text/font styling in detail, including setting font weight, family and style, font shorthand, text alignment and other effects, and line and letter spacing. @@ -113,6 +113,9 @@ p { This would make all paragraphs on a page adopt the arial font, which is found on any computer. +> [!NOTE] +> Scrimba's [Web-safe fonts](https://scrimba.com/learn-html-and-css-c0p/~01r?via=mdn) <sup>[_MDN learning partner_](/en-US/docs/MDN/Writing_guidelines/Learning_content#partner_links_and_embeds)</sup> scrim provides an interactive guide to why fonts are important, web-safe fonts, and how to specify fonts in CSS — along with a challenge to test your knowledge. + #### Web safe fonts Speaking of font availability, there are only a certain number of fonts that are generally available across all systems and can therefore be used without much worry. These are the so-called **web safe fonts**. @@ -334,7 +337,7 @@ In our previous module's [CSS values and units](/en-US/docs/Learn_web_developmen - `px` (pixels): The number of pixels high you want the text to be. This is an absolute unit — it results in the same final computed value for the font on the page in pretty much any situation. - `em`s: 1 `em` is equal to the font size set on the parent element of the current element we are styling (more specifically, the width of a capital letter M contained inside the parent element). This can become tricky to work out if you have a lot of nested elements with different font sizes set, but it is doable, as you'll see below. Why bother? It is quite natural once you get used to it, and you can use `em` to size everything, not just text. You can have an entire website sized using `em`, which makes maintenance easy. -- `rem`s: These work just like `em`, except that 1 `rem` is equal to the font size set on the root element of the document (i.e. {{htmlelement("html")}}), not the parent element. This makes doing the maths to work out your font sizes much easier. +- `rem`s: These work just like `em`, except that 1 `rem` is equal to the font size set on the root element of the document (i.e., {{htmlelement("html")}}), not the parent element. This makes doing the maths to work out your font sizes much easier. The `font-size` of an element is inherited from that element's parent element. This all starts with the root element of the entire document — {{htmlelement("html")}} — the standard `font-size` of which is set to `16px` across browsers. Any paragraph (or another element that doesn't have a different size set by the browser) inside the root element will have a final size of `16px`. Other elements may have different default sizes. For example, an {{htmlelement("Heading_Elements", "h1")}} element has a size of `2em` set by default, so it will have a final size of `32px`. @@ -438,7 +441,7 @@ The four properties are as follows: 1. The horizontal offset of the shadow from the original text — this can take most available CSS [length and size units](/en-US/docs/Learn_web_development/Core/Styling_basics/Values_and_units#lengths), but you'll most commonly use `px`; positive values move the shadow right, and negative values left. This value has to be included. 2. The vertical offset of the shadow from the original text. This behaves similarly to the horizontal offset, except that it moves the shadow up/down, not left/right. This value has to be included. 3. The blur radius: a higher value means the shadow is dispersed more widely. If this value is not included, it defaults to 0, which means no blur. This can take most available CSS [length and size units](/en-US/docs/Learn_web_development/Core/Styling_basics/Values_and_units#lengths). -4. The base color of the shadow, which can take any [CSS color unit](/en-US/docs/Learn_web_development/Core/Styling_basics/Values_and_units#color). If not included, it defaults to [`currentcolor`](/en-US/docs/Web/CSS/color_value#currentcolor_keyword), i.e. the shadow's color is taken from the element's [`color`](/en-US/docs/Web/CSS/color) property. +4. The base color of the shadow, which can take any [CSS color unit](/en-US/docs/Learn_web_development/Core/Styling_basics/Values_and_units#color). If not included, it defaults to [`currentcolor`](/en-US/docs/Web/CSS/color_value#currentcolor_keyword), i.e., the shadow's color is taken from the element's [`color`](/en-US/docs/Web/CSS/color) property. #### Multiple shadows @@ -793,6 +796,6 @@ We hope you enjoyed playing with text in this article! The next article will pro ## See also - [All about the CSS font-family property](https://explainers.dev/font-family/), explainers.dev -- [Web-safe fonts](https://v2.scrimba.com/the-frontend-developer-career-path-c0j/~02b?via=mdn), Scrimba <sup>_MDN learning partner_</sup> +- [Web-safe fonts](https://scrimba.com/the-frontend-developer-career-path-c0j/~02b?via=mdn), Scrimba <sup>[_MDN learning partner_](/en-US/docs/MDN/Writing_guidelines/Learning_content#partner_links_and_embeds)</sup> {{NextMenu("Learn_web_development/Core/Text_styling/Styling_lists", "Learn_web_development/Core/Text_styling")}} diff --git a/files/en-us/learn_web_development/core/text_styling/index.md b/files/en-us/learn_web_development/core/text_styling/index.md index 3ae2cb7d983a6b8..9f8547651233ebb 100644 --- a/files/en-us/learn_web_development/core/text_styling/index.md +++ b/files/en-us/learn_web_development/core/text_styling/index.md @@ -2,10 +2,9 @@ title: CSS text styling slug: Learn_web_development/Core/Text_styling page-type: learn-module +sidebar: learnsidebar --- -{{LearnSidebar}} - {{NextMenu("Learn_web_development/Core/Text_styling/Fundamentals", "Learn_web_development/Core")}} With the basics of the CSS language covered, the next CSS topic for you to concentrate on is styling text — one of the most common things you'll do with CSS. Here we look at fundamentals including setting font, boldness, italics, line and letter spacing, drop shadows, and other text features. We round off the module by looking at applying custom fonts to your page, and styling lists and links. diff --git a/files/en-us/learn_web_development/core/text_styling/styling_links/index.md b/files/en-us/learn_web_development/core/text_styling/styling_links/index.md index 3246798b68150c2..fdff71206963841 100644 --- a/files/en-us/learn_web_development/core/text_styling/styling_links/index.md +++ b/files/en-us/learn_web_development/core/text_styling/styling_links/index.md @@ -2,10 +2,9 @@ title: Styling links slug: Learn_web_development/Core/Text_styling/Styling_links page-type: learn-module-chapter +sidebar: learnsidebar --- -{{LearnSidebar}} - {{PreviousMenuNext("Learn_web_development/Core/Text_styling/Styling_lists", "Learn_web_development/Core/Text_styling/Web_fonts", "Learn_web_development/Core/Text_styling")}} When styling [links](/en-US/docs/Learn_web_development/Core/Structuring_content/Creating_links), it is important to understand why default link styles are important, how to use pseudo-classes to style link states effectively, and how to style links for use in common varied interface features such as navigation menus and tabs. We'll look at all these topics in this article. @@ -38,7 +37,7 @@ When styling [links](/en-US/docs/Learn_web_development/Core/Structuring_content/ ## Link states -The first thing to understand is the concept of link states — different states that links can exist in. These can be styled using different [pseudo-classes](/en-US/docs/Learn_web_development/Core/Styling_basics/Basic_selectors#pseudo-classes_and_pseudo-elements): +The first thing to understand is the concept of link states — different states that links can exist in. These can be styled using different [pseudo-classes](/en-US/docs/Learn_web_development/Core/Styling_basics/Pseudo_classes_and_elements): - **Link**: A link that has a destination (i.e., not just a named anchor), styled using the {{cssxref(":link")}} pseudo class. - **Visited**: A link that has already been visited (exists in the browser's history), styled using the {{cssxref(":visited")}} pseudo class. @@ -361,7 +360,7 @@ So what's going on here? We'll skip over most of the CSS, as it's just the same We've used a [relative unit](/en-US/docs/Learn_web_development/Core/Styling_basics/Values_and_units#relative_length_units) `em`. It sizes the icon in proportion to the anchor's text size. If the text size of the anchor changes the icon size also adjusts accordingly. -A final word: how did we select just external links? Well, if you are writing your [HTML links](/en-US/docs/Learn_web_development/Core/Structuring_content/Creating_links) properly, you should only be using absolute URLs for external links — it is more efficient to use relative links to link to other parts of your own site (as with the first link). The text "http" should therefore only appear in external links (like the second and third ones), and we can select this with an [attribute selector](/en-US/docs/Learn_web_development/Core/Styling_basics/Basic_selectors#attribute_selectors): `a[href^="http"]` selects {{htmlelement("a")}} elements, but only if they have an [`href`](/en-US/docs/Web/HTML/Element/a#href) attribute with a value that begins with "http". +A final word: how did we select just external links? Well, if you are writing your [HTML links](/en-US/docs/Learn_web_development/Core/Structuring_content/Creating_links) properly, you should only be using absolute URLs for external links — it is more efficient to use relative links to link to other parts of your own site (as with the first link). The text "http" should therefore only appear in external links (like the second and third ones), and we can select this with an [attribute selector](/en-US/docs/Learn_web_development/Core/Styling_basics/Attribute_selectors): `a[href^="http"]` selects {{htmlelement("a")}} elements, but only if they have an [`href`](/en-US/docs/Web/HTML/Reference/Elements/a#href) attribute with a value that begins with "http". So that's it. Try revisiting the active learning section above and trying this new technique out! diff --git a/files/en-us/learn_web_development/core/text_styling/styling_lists/index.md b/files/en-us/learn_web_development/core/text_styling/styling_lists/index.md index 01c2e7a374f2b12..9b7cff0c0817aa1 100644 --- a/files/en-us/learn_web_development/core/text_styling/styling_lists/index.md +++ b/files/en-us/learn_web_development/core/text_styling/styling_lists/index.md @@ -2,10 +2,9 @@ title: Styling lists slug: Learn_web_development/Core/Text_styling/Styling_lists page-type: learn-module-chapter +sidebar: learnsidebar --- -{{LearnSidebar}} - {{PreviousMenuNext("Learn_web_development/Core/Text_styling/Fundamentals", "Learn_web_development/Core/Text_styling/Styling_links", "Learn_web_development/Core/Text_styling")}} [Lists](/en-US/docs/Learn_web_development/Core/Structuring_content/Lists) behave like any other text for the most part, but there are some CSS properties specific to lists that you need to know about, as well as some best practices to consider. This article explains all. @@ -97,7 +96,7 @@ The HTML for our list example looks like so: If you go to the live example now and investigate the list elements using [browser developer tools](/en-US/docs/Learn_web_development/Howto/Tools_and_setup/What_are_browser_developer_tools), you'll notice a couple of styling defaults: -- The {{htmlelement("ul")}} and {{htmlelement("ol")}} elements have a top and bottom {{cssxref("margin")}} of `16px` (`1em`) and a {{cssxref("padding-left")}} of `40px` (`2.5em`). If the directionality attribute [`dir`](/en-US/docs/Web/HTML/Global_attributes/dir) is set to right-to-left (`rtl`) for `ul` and `ol` elements, in that case {{cssxref("padding-right")}} comes into effect and its default value is `40px` (`2.5em`). +- The {{htmlelement("ul")}} and {{htmlelement("ol")}} elements have a top and bottom {{cssxref("margin")}} of `16px` (`1em`) and a {{cssxref("padding-left")}} of `40px` (`2.5em`). If the directionality attribute [`dir`](/en-US/docs/Web/HTML/Reference/Global_attributes/dir) is set to right-to-left (`rtl`) for `ul` and `ol` elements, in that case {{cssxref("padding-right")}} comes into effect and its default value is `40px` (`2.5em`). - The list items ({{htmlelement("li")}} elements) have no set defaults for spacing. - The {{htmlelement("dl")}} element has a top and bottom {{cssxref("margin")}} of `16px` (`1em`), but no padding set. - The {{htmlelement("dd")}} elements have {{cssxref("margin-left")}} of `40px` (`2.5em`). @@ -261,7 +260,7 @@ Sometimes you might want to count differently on an ordered list — e.g., start ### start -The [`start`](/en-US/docs/Web/HTML/Element/ol#start) attribute allows you to start the list counting from a number other than 1. The following example: +The [`start`](/en-US/docs/Web/HTML/Reference/Elements/ol#start) attribute allows you to start the list counting from a number other than 1. The following example: ```html <ol start="4"> @@ -280,7 +279,7 @@ Gives you this output: ### reversed -The [`reversed`](/en-US/docs/Web/HTML/Element/ol#reversed) attribute will start the list counting down instead of up. The following example: +The [`reversed`](/en-US/docs/Web/HTML/Reference/Elements/ol#reversed) attribute will start the list counting down instead of up. The following example: ```html <ol start="4" reversed> @@ -302,7 +301,7 @@ Gives you this output: ### value -The [`value`](/en-US/docs/Web/HTML/Element/li#value) attribute allows you to set your list items to specific numerical values. The following example: +The [`value`](/en-US/docs/Web/HTML/Reference/Elements/li#value) attribute allows you to set your list items to specific numerical values. The following example: ```html <ol> diff --git a/files/en-us/learn_web_development/core/text_styling/typesetting_a_homepage/index.md b/files/en-us/learn_web_development/core/text_styling/typesetting_a_homepage/index.md index 234334d4745c517..d5f7ff2a7a91124 100644 --- a/files/en-us/learn_web_development/core/text_styling/typesetting_a_homepage/index.md +++ b/files/en-us/learn_web_development/core/text_styling/typesetting_a_homepage/index.md @@ -1,11 +1,11 @@ --- title: "Challenge: Typesetting a community school homepage" +short-title: "Challenge: Community school homepage" slug: Learn_web_development/Core/Text_styling/Typesetting_a_homepage page-type: learn-module-assessment +sidebar: learnsidebar --- -{{LearnSidebar}} - {{PreviousMenuNext("Learn_web_development/Core/Text_styling/Web_fonts", "Learn_web_development/Core/CSS_layout", "Learn_web_development/Core/Text_styling")}} In this challenge, we'll test your understanding of all the text styling techniques we've covered throughout this module by getting you to style the text for a community school's homepage. You might just have some fun along the way. diff --git a/files/en-us/learn_web_development/core/text_styling/web_fonts/index.md b/files/en-us/learn_web_development/core/text_styling/web_fonts/index.md index 819212ab8c9ef6e..75ac519a1b930bb 100644 --- a/files/en-us/learn_web_development/core/text_styling/web_fonts/index.md +++ b/files/en-us/learn_web_development/core/text_styling/web_fonts/index.md @@ -2,10 +2,9 @@ title: Web fonts slug: Learn_web_development/Core/Text_styling/Web_fonts page-type: learn-module-chapter +sidebar: learnsidebar --- -{{LearnSidebar}} - {{PreviousMenuNext("Learn_web_development/Core/Text_styling/Styling_links", "Learn_web_development/Core/Text_styling/Typesetting_a_homepage", "Learn_web_development/Core/Text_styling")}} In the first article of the module, we explored the basic CSS features available for styling fonts and text. In this article we will go further, exploring web fonts in detail. We'll see how to use custom fonts with your web page to allow for more varied, custom text styling. diff --git a/files/en-us/learn_web_development/core/version_control/index.md b/files/en-us/learn_web_development/core/version_control/index.md index 8fb838923b3c330..9bcc6ffa016dc89 100644 --- a/files/en-us/learn_web_development/core/version_control/index.md +++ b/files/en-us/learn_web_development/core/version_control/index.md @@ -2,82 +2,53 @@ title: Version control slug: Learn_web_development/Core/Version_control page-type: learn-module +sidebar: learnsidebar --- -{{LearnSidebar}} - {{PreviousMenu("Learn_web_development/Core/Design_for_developers", "Learn_web_development/Core")}} -Version control tools (often called **Version Control Systems**, or **VCS**) are an essential part of modern workflows, for backing up and collaborating on codebases. This module takes you through the essentials of version control using Git and GitHub. - -## Overview +Version control tools (often called **Version Control Systems** or **VCS**) are an essential part of modern coding workflows–for backing up code, collaborating on codebases, and rolling back to earlier versions if required. -Version control tools are essential for software development: +[Git](https://git-scm.com/) is an example of a version control tool. [GitHub](https://github.com/), on the other hand, is a website and infrastructure that provides a Git server plus a number of useful tools for working with Git repositories, both individually and in teams. GitHub lets you report issues with the code, review code collaboratively, and offers project management features such as triaging issues, assigning tasks, planning projects, and more. -- It is rare that you will work on a project completely on your own, and as soon as you start working with other people you start to run the risk of conflicting with each other's work — this is when both of you try to update the same piece of code at the same time. You need to have some kind of mechanism in place to manage the occurrences, and help avoid loss of work as a result. -- When working on a project on your own or with others, you'll want to be able to back up the code in a central place, so it is not lost if your computer breaks. -- You will also want to be able to roll back to earlier versions if a problem is later discovered. You might have started doing this in your own work by creating different versions of the same file, e.g. `myCode.js`, `myCode_v2.js`, `myCode_v3.js`, `myCode_final.js`, `myCode_really_really_final.js`, etc., but this is really error-prone and unreliable. -- Different team members will commonly want to create their own separate versions of the code (called **branches** in Git), work on a new feature in that version, and then get it merged in a controlled manner (in GitHub we use **pull requests**) with the master version when they are done with it. - -Version control tools meet the above needs. [Git](https://git-scm.com/) is an example of a version control tool, and [GitHub](https://github.com/) is a website + infrastructure that provides a Git server plus a number of really useful tools for working with git repositories individually or in teams, such as reporting issues with the code, reviewing tools, project management features such as assigning tasks and task statuses, and more. - -> [!NOTE] -> Git is actually a _distributed_ version control tools, meaning that a complete copy of the repository containing the codebase is made on your computer (and everyone else's). You make changes to your own copy and then push those changes back up to the server, where an administrator will decide whether to merge your changes with the master copy. +This module takes you through the essentials of version control using Git and GitHub. ## Prerequisites -To use Git and GitHub, you need: - - A desktop computer with Git installed on it (see the [Git downloads page](https://git-scm.com/downloads)). -- A tool to use Git. Depending on how you like to work, you could use a [Git GUI client](https://git-scm.com/downloads/guis/) (we'd recommend [GitHub Desktop](https://desktop.github.com/download/), [SourceTree](https://www.sourcetreeapp.com/) or [Git Kraken](https://www.gitkraken.com/)) or just stick to using a terminal window. In fact, it is probably useful for you to get to know at least the basics of git terminal commands, even if you intend to use a GUI. +- A tool to use Git. Depending on how you like to work, you could use: + - A [Git GUI client](https://git-scm.com/downloads/guis/) (we'd recommend [GitHub Desktop](https://desktop.github.com/download/), [SourceTree](https://www.sourcetreeapp.com/) or [Git Kraken](https://www.gitkraken.com/)). + - A command line/terminal window (check out our [Command line crash course](/en-US/docs/Learn_web_development/Getting_started/Environment_setup/Command_line) for an introduction). - A [GitHub account](https://github.com/signup). If you haven't already got one, sign up now using the provided link. -In terms of prerequisite knowledge, you don't need to know anything about web development, Git/GitHub, or version control to start this module. However, it is recommended that you know some coding so that you have reasonable computer literacy, and some code to store in your repositories! - -It is also preferable that you have some basic terminal knowledge, so for example moving between directories and creating files. You can find out all the basics in our [Command line crash course](/en-US/docs/Learn_web_development/Getting_started/Environment_setup/Command_line). - -> [!NOTE] -> GitHub is not the only site/toolset you can use with Git. There are other alternatives such as [GitLab](https://about.gitlab.com/) that you could try, and you could also try setting your own Git server up and using it instead of GitHub. We've only stuck with GitHub in this course to provide a single way that works. - -## Learning outcomes - -- Why version control systems are necessary. -- The difference between Git, and websites like GitHub and GitLab. -- Understand that websites such as GitHub and GitLab enable teamwork and collaboration that isn't so easy just with plain Git. -- Basic setup — installing git, signing up for an account for your chosen social coding site. -- Handling security requirements, like SSH/GPG keys. -- Creating a repo and pushing changes to it. -- Contributing to others' repos: forking, creating a new branch, creating a PR, and review flow. -- Good housekeeping: - - Regularly updating local repos so that they are in sync with their remote counterparts. - - Using `.gitignore` to ignore all the stuff you don't want to commit. - - Deleting branches you have finished with. -- Handling merge conflicts. - ## Guides -Note that the links below take you to resources on external sites. Eventually, we are aiming to have our own dedicated Git/GitHub course, but for now, these will help you get to grips with the subject at hand. - +- [About GitHub and Git (from GitHub)](https://docs.github.com/en/get-started/start-your-journey/about-github-and-git) + - : This covers what Git and GitHub are, how they work together, and how to get started. - [Hello, World (from GitHub)](https://docs.github.com/en/get-started/start-your-journey/hello-world) - - : This is a good place to start — this practical guide gets you to jump right into using GitHub, learning the basics of Git such as creating repositories and branches, making commits, and opening and merging pull requests. -- [Git Handbook (from GitHub)](https://docs.github.com/en/get-started/using-git/about-git) - - : This Git Handbook goes into a little more depth, explaining what a version control tool is, what a repository is, how the basic GitHub model works, Git commands and examples, and more. -- [Forking Projects (from GitHub)](https://docs.github.com/en/get-started/exploring-projects-on-github/contributing-to-a-project) + - : This practical guide jumps right into using GitHub, teaching the basics of Git such as creating repositories and branches, making commits, and opening and merging pull requests. +- [Using Git (from GitHub)](https://docs.github.com/en/get-started/using-git) + - : The Git Handbook goes into a little more depth, explaining what a version control tool is, what a repository is, how the basic GitHub model works, Git commands and examples, and more. +- [Contributing to a project (from GitHub)](https://docs.github.com/en/get-started/exploring-projects-on-github/contributing-to-a-project) - : Forking projects is essential when you want to contribute to someone else's code. This guide explains how. - [About Pull Requests (from GitHub)](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/about-pull-requests) - - : A useful guide to managing pull requests, the way that your suggested code changes are delivered to people's repositories for consideration. -- [Mastering issues (from GitHub)](https://docs.github.com/en/issues/tracking-your-work-with-issues/about-issues) + - : A useful guide to managing pull requests. These requests are how you propose code changes to someone else's repository so they can review and potentially merge them into the main codebase. +- [About issues (from GitHub)](https://docs.github.com/en/issues/tracking-your-work-with-issues/about-issues) - : Issues are like a forum for your GitHub project, where people can ask questions and report problems, and you can manage updates (for example assigning people to fix issues, clarifying the issue, letting people know things are fixed). This article tells you what you need to know about issues. > [!NOTE] -> There is **a lot more** that you can do with Git and GitHub, but we feel that the above represents the minimum you need to know to start using Git effectively. As you get deeper into Git, you'll start to realize that it is easy to go wrong when you start using more complicated commands. Don't worry, even professional web developers find Git confusing sometimes, and often solve problems by searching for solutions on the web, or consulting sites like [Flight rules for Git](https://github.com/k88hudson/git-flight-rules) and [Dangit, git!](https://dangitgit.com/) +> As you get deeper into Git, you'll start to realize that it is easy to go wrong when you start using more complicated commands. Don't worry, even professional web developers find Git confusing sometimes, and often solve problems by searching for solutions on the web, or consulting sites like [Flight rules for Git](https://github.com/k88hudson/git-flight-rules) and [Dangit, git!](https://dangitgit.com/). ## See also -- [Understanding the GitHub flow](https://docs.github.com/en/get-started/using-github/github-flow) +- Other useful topics covered in GitHub Docs include: + - [Understanding the GitHub flow](https://docs.github.com/en/get-started/using-github/github-flow) + - [Addressing merge conflicts](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/addressing-merge-conflicts) + - [Ignoring files with .gitignore](https://docs.github.com/en/get-started/git-basics/ignoring-files) + - [Authentication to GitHub](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/about-authentication-to-github) + - [Mastering markdown](https://docs.github.com/en/get-started/writing-on-github/getting-started-with-writing-and-formatting-on-github/basic-writing-and-formatting-syntax) (the text format you write in on PR, issue comments, and `.md` files). + - [Getting Started with GitHub Pages](https://docs.github.com/en/pages/quickstart) (how to publish demos and websites on GitHub). - [Git command list](https://git-scm.com/docs) -- [Mastering markdown](https://docs.github.com/en/get-started/writing-on-github/getting-started-with-writing-and-formatting-on-github/basic-writing-and-formatting-syntax) (the text format you write in on PR, issue comments, and `.md` files). -- [Getting Started with GitHub Pages](https://docs.github.com/en/pages/quickstart) (how to publish demos and websites on GitHub). - [Learn Git branching](https://learngitbranching.js.org/) - [Flight rules for Git](https://github.com/k88hudson/git-flight-rules) (a very useful compendium of ways to achieve specific things in Git, including how to correct things when you went wrong). - [Dangit, git!](https://dangitgit.com/) (another useful compendium, specifically of ways to correct things when you went wrong). diff --git a/files/en-us/learn_web_development/educators/index.md b/files/en-us/learn_web_development/educators/index.md index ebbcb962bb38c2f..3cf9ad51cff7d8a 100644 --- a/files/en-us/learn_web_development/educators/index.md +++ b/files/en-us/learn_web_development/educators/index.md @@ -2,10 +2,9 @@ title: Resources for educators slug: Learn_web_development/Educators page-type: landing-page +sidebar: learnsidebar --- -{{LearnSidebar}} - Educators can use MDN's "Learn web development" section as a guide when creating programs, units, and assessment specifications for a web-related university degree, college course, coding school course, or similar. Each article includes a "Learning outcomes" section at the top detailing the topics taught in that article. The MDN team is committed to reviewing the material contained within "Learn web development" annually to ensure it remains current with front-end development best practices. By basing their courses on it, educators can ensure their teaching is up-to-date. @@ -33,10 +32,10 @@ You could take your students through the provided pathway as-is, or you may wish - Grouping the learning outcomes differently. For example, you may wish to start with the basics of HTML document structure, then follow up quickly with some CSS fundamentals such as box model and text styling. In the next step, you might introduce more complex HTML features such as images and form fields, ramp up the CSS with some flexbox and media queries, and introduce some rudimentary DOM scripting. - Providing students with a repository containing their project work that can be published as a portfolio to demonstrate proof of their skills to prospective employers. -You could also consider using an advanced turnkey solution such as an interactive video course. We would recommend [The Frontend Developer Career Path](https://v2.scrimba.com/the-frontend-developer-career-path-c0j?via=mdn) from our learning partner, [Scrimba](https://scrimba.com/?via=mdn), which teaches all of the learning outcomes in the MDN Curriculum Core and more. +You could also consider using an advanced turnkey solution such as an interactive video course. We would recommend [The Frontend Developer Career Path](https://scrimba.com/the-frontend-developer-career-path-c0j?via=mdn) from our learning partner, [Scrimba](https://scrimba.com/?via=mdn), which teaches all of the learning outcomes in the MDN Curriculum Core and more. > [!NOTE] -> Scrimba offers multiple license deals — see [Scrimba for Teams](https://v2.scrimba.com/teams?via=mdn-edu). +> Scrimba offers multiple license deals — see [Scrimba for Teams](https://scrimba.com/teams?via=mdn-edu). The Frontend Developer Career Path features fun interactive lessons and challenges, knowledgeable teachers, and a supportive community; it aims to give students all they need to land their first junior developer job. Many of the course components are available as standalone free versions. diff --git a/files/en-us/learn_web_development/extensions/advanced_javascript_objects/adding_bouncing_balls_features/index.md b/files/en-us/learn_web_development/extensions/advanced_javascript_objects/adding_bouncing_balls_features/index.md index cfdbc023d6a7603..5dcc04992da0439 100644 --- a/files/en-us/learn_web_development/extensions/advanced_javascript_objects/adding_bouncing_balls_features/index.md +++ b/files/en-us/learn_web_development/extensions/advanced_javascript_objects/adding_bouncing_balls_features/index.md @@ -1,11 +1,11 @@ --- title: "Challenge: Adding features to our bouncing balls demo" +short-title: "Challenge: Bouncing balls features" slug: Learn_web_development/Extensions/Advanced_JavaScript_objects/Adding_bouncing_balls_features page-type: learn-module-assessment +sidebar: learnsidebar --- -{{LearnSidebar}} - {{PreviousMenu("Learn_web_development/Extensions/Advanced_JavaScript_objects/Object_building_practice", "Learn_web_development/Extensions/Advanced_JavaScript_objects")}} In this challenge, you are expected to use the bouncing balls demo from the previous article as a starting point, and add some new and interesting features to it. @@ -58,18 +58,22 @@ The `Ball` constructor should define a new property called `exists`, which is us The `collisionDetect()` method of the `Ball` class needs a small update. A ball needs to be considered for collision detection only if the `exists` property is `true`. So, replace the existing `collisionDetect()` code with the following code: ```js -collisionDetect() { - for (const ball of balls) { - if (!(this === ball) && ball.exists) { - const dx = this.x - ball.x; - const dy = this.y - ball.y; - const distance = Math.sqrt(dx * dx + dy * dy); - - if (distance < this.size + ball.size) { - ball.color = this.color = randomRGB(); +class Ball { + // … + collisionDetect() { + for (const ball of balls) { + if (!(this === ball) && ball.exists) { + const dx = this.x - ball.x; + const dy = this.y - ball.y; + const distance = Math.sqrt(dx * dx + dy * dy); + + if (distance < this.size + ball.size) { + ball.color = this.color = randomRGB(); + } } } } + // … } ``` diff --git a/files/en-us/learn_web_development/extensions/advanced_javascript_objects/classes_in_javascript/index.md b/files/en-us/learn_web_development/extensions/advanced_javascript_objects/classes_in_javascript/index.md index 05bb28d3ad39cc3..1b3ddfa32b7a845 100644 --- a/files/en-us/learn_web_development/extensions/advanced_javascript_objects/classes_in_javascript/index.md +++ b/files/en-us/learn_web_development/extensions/advanced_javascript_objects/classes_in_javascript/index.md @@ -2,10 +2,9 @@ title: Classes in JavaScript slug: Learn_web_development/Extensions/Advanced_JavaScript_objects/Classes_in_JavaScript page-type: learn-module-chapter +sidebar: learnsidebar --- -{{LearnSidebar}} - {{PreviousMenuNext("Learn_web_development/Extensions/Advanced_JavaScript_objects/Object-oriented_programming", "Learn_web_development/Extensions/Advanced_JavaScript_objects/Object_building_practice", "Learn_web_development/Extensions/Advanced_JavaScript_objects")}} In the last article, we introduced some basic concepts of object-oriented programming (OOP), and discussed an example where we used OOP principles to model professors and students in a school. @@ -209,7 +208,7 @@ myExample.#somePrivateMethod(); // SyntaxError ## Test your skills! -You've reached the end of this article, but can you remember the most important information? You can find some further tests to verify that you've retained this information before you move on — see [Test your skills: Object-oriented JavaScript](/en-US/docs/Learn_web_development/Extensions/Advanced_JavaScript_objects/Test_your_skills:_Object-oriented_JavaScript). +You've reached the end of this article, but can you remember the most important information? You can find some further tests to verify that you've retained this information before you move on — see [Test your skills: Object-oriented JavaScript](/en-US/docs/Learn_web_development/Extensions/Advanced_JavaScript_objects/Test_your_skills/Object-oriented_JavaScript). ## Summary diff --git a/files/en-us/learn_web_development/extensions/advanced_javascript_objects/index.md b/files/en-us/learn_web_development/extensions/advanced_javascript_objects/index.md index 6bc02ba9cf3223d..bdf432dea2b6d61 100644 --- a/files/en-us/learn_web_development/extensions/advanced_javascript_objects/index.md +++ b/files/en-us/learn_web_development/extensions/advanced_javascript_objects/index.md @@ -2,10 +2,9 @@ title: Advanced JavaScript objects slug: Learn_web_development/Extensions/Advanced_JavaScript_objects page-type: learn-module +sidebar: learnsidebar --- -{{LearnSidebar}} - {{NextMenu("Learn_web_development/Extensions/Advanced_JavaScript_objects/Object_prototypes", "Learn_web_development/Extensions")}} In JavaScript, most things are objects, from core JavaScript features like arrays to the browser {{Glossary("API", "APIs")}} built on top of JavaScript. You can also create your own objects to encapsulate related functions and variables into efficient packages and act as handy data containers. diff --git a/files/en-us/learn_web_development/extensions/advanced_javascript_objects/object-oriented_programming/index.md b/files/en-us/learn_web_development/extensions/advanced_javascript_objects/object-oriented_programming/index.md index e56fa1f5efd94bd..450ea8509c63ebe 100644 --- a/files/en-us/learn_web_development/extensions/advanced_javascript_objects/object-oriented_programming/index.md +++ b/files/en-us/learn_web_development/extensions/advanced_javascript_objects/object-oriented_programming/index.md @@ -2,10 +2,9 @@ title: Object-oriented programming slug: Learn_web_development/Extensions/Advanced_JavaScript_objects/Object-oriented_programming page-type: learn-module-chapter +sidebar: learnsidebar --- -{{LearnSidebar}} - {{PreviousMenuNext("Learn_web_development/Extensions/Advanced_JavaScript_objects/Object_prototypes", "Learn_web_development/Extensions/Advanced_JavaScript_objects/Classes_in_JavaScript", "Learn_web_development/Extensions/Advanced_JavaScript_objects")}} Object-oriented programming (OOP) is a programming paradigm fundamental to many programming languages, including Java and C++. In this article, we'll provide an overview of the basic concepts of OOP. We'll describe three main concepts: **classes and instances**, **inheritance**, and **encapsulation**. For now, we'll describe these concepts without reference to JavaScript in particular, so all the examples are given in {{Glossary("Pseudocode", "pseudocode")}}. diff --git a/files/en-us/learn_web_development/extensions/advanced_javascript_objects/object_building_practice/index.md b/files/en-us/learn_web_development/extensions/advanced_javascript_objects/object_building_practice/index.md index 565fcbb354a3303..11998f3f96b080c 100644 --- a/files/en-us/learn_web_development/extensions/advanced_javascript_objects/object_building_practice/index.md +++ b/files/en-us/learn_web_development/extensions/advanced_javascript_objects/object_building_practice/index.md @@ -2,10 +2,9 @@ title: Object building practice slug: Learn_web_development/Extensions/Advanced_JavaScript_objects/Object_building_practice page-type: learn-module-chapter +sidebar: learnsidebar --- -{{LearnSidebar}} - {{PreviousMenuNext("Learn_web_development/Extensions/Advanced_JavaScript_objects/Classes_in_JavaScript", "Learn_web_development/Extensions/Advanced_JavaScript_objects/Adding_bouncing_balls_features", "Learn_web_development/Extensions/Advanced_JavaScript_objects")}} In previous articles we looked at all the essential JavaScript object theory and syntax details, giving you a solid base to start from. In this article we dive into a practical exercise, giving you some more practice in building custom JavaScript objects, with a fun and colorful result. @@ -107,11 +106,14 @@ This handles the properties, but what about the methods? We want to get our ball First add the following `draw()` method to the `Ball` class: ```js -draw() { - ctx.beginPath(); - ctx.fillStyle = this.color; - ctx.arc(this.x, this.y, this.size, 0, 2 * Math.PI); - ctx.fill(); +class Ball { + // … + draw() { + ctx.beginPath(); + ctx.fillStyle = this.color; + ctx.arc(this.x, this.y, this.size, 0, 2 * Math.PI); + ctx.fill(); + } } ``` @@ -153,25 +155,28 @@ You can start testing your object out already. We can draw the ball in position, but to actually move the ball, we need an update function of some kind. Add the following code inside the class definition for `Ball`: ```js -update() { - if ((this.x + this.size) >= width) { - this.velX = -(this.velX); - } +class Ball { + // … + update() { + if (this.x + this.size >= width) { + this.velX = -this.velX; + } - if ((this.x - this.size) <= 0) { - this.velX = -(this.velX); - } + if (this.x - this.size <= 0) { + this.velX = -this.velX; + } - if ((this.y + this.size) >= height) { - this.velY = -(this.velY); - } + if (this.y + this.size >= height) { + this.velY = -this.velY; + } - if ((this.y - this.size) <= 0) { - this.velY = -(this.velY); - } + if (this.y - this.size <= 0) { + this.velY = -this.velY; + } - this.x += this.velX; - this.y += this.velY; + this.x += this.velX; + this.y += this.velY; + } } ``` @@ -255,15 +260,18 @@ Now for a bit of fun, let's add some collision detection to our program, so our First, add the following method definition to your `Ball` class. ```js -collisionDetect() { - for (const ball of balls) { - if (this !== ball) { - const dx = this.x - ball.x; - const dy = this.y - ball.y; - const distance = Math.sqrt(dx * dx + dy * dy); - - if (distance < this.size + ball.size) { - ball.color = this.color = randomRGB(); +class Ball { + // … + collisionDetect() { + for (const ball of balls) { + if (this !== ball) { + const dx = this.x - ball.x; + const dy = this.y - ball.y; + const distance = Math.sqrt(dx * dx + dy * dy); + + if (distance < this.size + ball.size) { + ball.color = this.color = randomRGB(); + } } } } diff --git a/files/en-us/learn_web_development/extensions/advanced_javascript_objects/object_prototypes/index.md b/files/en-us/learn_web_development/extensions/advanced_javascript_objects/object_prototypes/index.md index 9c0c686e85dcb25..a8e6edd30ef47d8 100644 --- a/files/en-us/learn_web_development/extensions/advanced_javascript_objects/object_prototypes/index.md +++ b/files/en-us/learn_web_development/extensions/advanced_javascript_objects/object_prototypes/index.md @@ -2,10 +2,9 @@ title: Object prototypes slug: Learn_web_development/Extensions/Advanced_JavaScript_objects/Object_prototypes page-type: learn-module-chapter +sidebar: learnsidebar --- -{{LearnSidebar}} - {{NextMenu("Learn_web_development/Extensions/Advanced_JavaScript_objects/Object-oriented_programming", "Learn_web_development/Extensions/Advanced_JavaScript_objects")}} Prototypes are the mechanism by which JavaScript objects inherit features from one another. In this article, we explain what a prototype is, how prototype chains work, and how a prototype for an object can be set. diff --git a/files/en-us/learn_web_development/extensions/advanced_javascript_objects/test_your_skills/index.md b/files/en-us/learn_web_development/extensions/advanced_javascript_objects/test_your_skills/index.md new file mode 100644 index 000000000000000..6a67e7b116375fb --- /dev/null +++ b/files/en-us/learn_web_development/extensions/advanced_javascript_objects/test_your_skills/index.md @@ -0,0 +1,17 @@ +--- +title: "Test your skills: Advanced JavaScript objects" +short-title: Test your skills +slug: Learn_web_development/Extensions/Advanced_JavaScript_objects/Test_your_skills +page-type: learn-module-assessment +sidebar: learnsidebar +--- + +This page lists tests to help you assess your understanding of Advanced JavaScript objects. + +## Test your skills in advanced JavaScript objects by topic + +{{SubpagesWithSummaries}} + +## See also + +- [Advanced JavaScript objects](/en-US/docs/Learn_web_development/Extensions/Advanced_JavaScript_objects) diff --git a/files/en-us/learn_web_development/extensions/advanced_javascript_objects/test_your_skills/object-oriented_javascript/index.md b/files/en-us/learn_web_development/extensions/advanced_javascript_objects/test_your_skills/object-oriented_javascript/index.md new file mode 100644 index 000000000000000..f5aec882bc6f9a1 --- /dev/null +++ b/files/en-us/learn_web_development/extensions/advanced_javascript_objects/test_your_skills/object-oriented_javascript/index.md @@ -0,0 +1,50 @@ +--- +title: "Test your skills: Object-oriented JavaScript" +short-title: Object-oriented JavaScript +slug: Learn_web_development/Extensions/Advanced_JavaScript_objects/Test_your_skills/Object-oriented_JavaScript +page-type: learn-module-assessment +sidebar: learnsidebar +--- + +The aim of this skill test is to assess whether you've understood our [Classes in JavaScript](/en-US/docs/Learn_web_development/Extensions/Advanced_JavaScript_objects/Classes_in_JavaScript) article. + +> [!NOTE] +> You can try solutions in the interactive editors on this page or in an online editor such as [CodePen](https://codepen.io/), [JSFiddle](https://jsfiddle.net/), or [Glitch](https://glitch.com/). +> If there is an error in your code, it will be logged into the results panel on this page or in the JavaScript console. +> +> If you get stuck, you can reach out to us in one of our [communication channels](/en-US/docs/MDN/Community/Communication_channels). + +## OOJS 1 + +In this task we provide you with the start of a definition for a `Shape` class. It has three properties: `name`, `sides`, and `sideLength`. This class only models shapes for which all sides are the same length, like a square or an equilateral triangle. + +We'd like you to: + +- Add a constructor to this class. The constructor takes arguments for the `name`, `sides`, and `sideLength` properties, and initializes them. +- Add a new method `calcPerimeter()` method to the class, which calculates its perimeter (the length of the shape's outer edge) and logs the result to the console. +- Create a new instance of the `Shape` class called `square`. Give it a `name` of `square`, `4` `sides`, and a `sideLength` of `5`. +- Call your `calcPerimeter()` method on the instance, to see whether it logs the calculation result to the browser's console as expected. +- Create a new instance of `Shape` called `triangle`, with a `name` of `triangle`, `3` `sides` and a `sideLength` of `3`. +- Call `triangle.calcPerimeter()` to check that it works OK. + +Try updating the live code below to recreate the finished example: + +{{EmbedGHLiveSample("learning-area/javascript/oojs/tasks/oojs/oojs1.html", '100%', 400)}} + +> [!CALLOUT] +> +> [Download the starting point for this task](https://github.com/mdn/learning-area/blob/main/javascript/oojs/tasks/oojs/oojs1-download.html) to work in your own editor or in an online editor. + +## OOJS 2 + +Next we'd like you to create a `Square` class that inherits from `Shape`, and adds a `calcArea()` method that calculates the square's area. Also set up the constructor so that the `name` property of `Square` object instances is automatically set to `square`, and the `sides` property is automatically set to `4`. When invoking the constructor, you should therefore just need to provide the `sideLength` property. + +Create an instance of the `Square` class called `square` with appropriate property values, and call its `calcPerimeter()` and `calcArea()` methods to show that it works OK. + +Try updating the live code below to recreate the finished example: + +{{EmbedGHLiveSample("learning-area/javascript/oojs/tasks/oojs/oojs2.html", '100%', 400)}} + +> [!CALLOUT] +> +> [Download the starting point for this task](https://github.com/mdn/learning-area/blob/main/javascript/oojs/tasks/oojs/oojs2-download.html) to work in your own editor or in an online editor. diff --git a/files/en-us/learn_web_development/extensions/advanced_javascript_objects/test_your_skills_colon__object-oriented_javascript/index.md b/files/en-us/learn_web_development/extensions/advanced_javascript_objects/test_your_skills_colon__object-oriented_javascript/index.md deleted file mode 100644 index c88706f845b4e3c..000000000000000 --- a/files/en-us/learn_web_development/extensions/advanced_javascript_objects/test_your_skills_colon__object-oriented_javascript/index.md +++ /dev/null @@ -1,50 +0,0 @@ ---- -title: "Test your skills: Object-oriented JavaScript" -slug: Learn_web_development/Extensions/Advanced_JavaScript_objects/Test_your_skills:_Object-oriented_JavaScript -page-type: learn-module-assessment ---- - -{{learnsidebar}} - -The aim of this skill test is to assess whether you've understood our [Classes in JavaScript](/en-US/docs/Learn_web_development/Extensions/Advanced_JavaScript_objects/Classes_in_JavaScript) article. - -> [!NOTE] -> You can try solutions in the interactive editors on this page or in an online editor such as [CodePen](https://codepen.io/), [JSFiddle](https://jsfiddle.net/), or [Glitch](https://glitch.com/). -> If there is an error in your code, it will be logged into the results panel on this page or in the JavaScript console. -> -> If you get stuck, you can reach out to us in one of our [communication channels](/en-US/docs/MDN/Community/Communication_channels). - -## OOJS 1 - -In this task we provide you with the start of a definition for a `Shape` class. It has three properties: `name`, `sides`, and `sideLength`. This class only models shapes for which all sides are the same length, like a square or an equilateral triangle. - -We'd like you to: - -- Add a constructor to this class. The constructor takes arguments for the `name`, `sides`, and `sideLength` properties, and initializes them. -- Add a new method `calcPerimeter()` method to the class, which calculates its perimeter (the length of the shape's outer edge) and logs the result to the console. -- Create a new instance of the `Shape` class called `square`. Give it a `name` of `square`, `4` `sides`, and a `sideLength` of `5`. -- Call your `calcPerimeter()` method on the instance, to see whether it logs the calculation result to the browser's console as expected. -- Create a new instance of `Shape` called `triangle`, with a `name` of `triangle`, `3` `sides` and a `sideLength` of `3`. -- Call `triangle.calcPerimeter()` to check that it works OK. - -Try updating the live code below to recreate the finished example: - -{{EmbedGHLiveSample("learning-area/javascript/oojs/tasks/oojs/oojs1.html", '100%', 400)}} - -> [!CALLOUT] -> -> [Download the starting point for this task](https://github.com/mdn/learning-area/blob/main/javascript/oojs/tasks/oojs/oojs1-download.html) to work in your own editor or in an online editor. - -## OOJS 2 - -Next we'd like you to create a `Square` class that inherits from `Shape`, and adds a `calcArea()` method that calculates the square's area. Also set up the constructor so that the `name` property of `Square` object instances is automatically set to `square`, and the `sides` property is automatically set to `4`. When invoking the constructor, you should therefore just need to provide the `sideLength` property. - -Create an instance of the `Square` class called `square` with appropriate property values, and call its `calcPerimeter()` and `calcArea()` methods to show that it works OK. - -Try updating the live code below to recreate the finished example: - -{{EmbedGHLiveSample("learning-area/javascript/oojs/tasks/oojs/oojs2.html", '100%', 400)}} - -> [!CALLOUT] -> -> [Download the starting point for this task](https://github.com/mdn/learning-area/blob/main/javascript/oojs/tasks/oojs/oojs2-download.html) to work in your own editor or in an online editor. diff --git a/files/en-us/learn_web_development/extensions/async_js/implementing_a_promise-based_api/index.md b/files/en-us/learn_web_development/extensions/async_js/implementing_a_promise-based_api/index.md index f46b262d74237e1..9566af64791c4d8 100644 --- a/files/en-us/learn_web_development/extensions/async_js/implementing_a_promise-based_api/index.md +++ b/files/en-us/learn_web_development/extensions/async_js/implementing_a_promise-based_api/index.md @@ -1,11 +1,11 @@ --- title: How to implement a promise-based API +short-title: Implementing promise-based APIs slug: Learn_web_development/Extensions/Async_JS/Implementing_a_promise-based_API page-type: learn-module-chapter +sidebar: learnsidebar --- -{{LearnSidebar}} - {{PreviousMenuNext("Learn_web_development/Extensions/Async_JS/Promises", "Learn_web_development/Extensions/Async_JS/Introducing_workers", "Learn_web_development/Extensions/Async_JS")}} In the last article we discussed how to use APIs that return promises. In this article we'll look at the other side — how to _implement_ APIs that return promises. This is a much less common task than using promise-based APIs, but it's still worth knowing about. diff --git a/files/en-us/learn_web_development/extensions/async_js/index.md b/files/en-us/learn_web_development/extensions/async_js/index.md index 8fdc26a891274d3..6529b8b54d0d55a 100644 --- a/files/en-us/learn_web_development/extensions/async_js/index.md +++ b/files/en-us/learn_web_development/extensions/async_js/index.md @@ -2,10 +2,9 @@ title: Asynchronous JavaScript slug: Learn_web_development/Extensions/Async_JS page-type: learn-module +sidebar: learnsidebar --- -{{LearnSidebar}} - {{NextMenu("Learn_web_development/Extensions/Async_JS/Introducing", "Learn_web_development/Extensions")}} In this module, we take a look at {{Glossary("asynchronous")}} {{Glossary("JavaScript")}}, why it is important, and how it can be used to effectively handle potential blocking operations, such as fetching resources from a server. diff --git a/files/en-us/learn_web_development/extensions/async_js/introducing/index.md b/files/en-us/learn_web_development/extensions/async_js/introducing/index.md index b656de456254339..2be6920c3728cd3 100644 --- a/files/en-us/learn_web_development/extensions/async_js/introducing/index.md +++ b/files/en-us/learn_web_development/extensions/async_js/introducing/index.md @@ -1,11 +1,11 @@ --- title: Introducing asynchronous JavaScript +short-title: Introduction slug: Learn_web_development/Extensions/Async_JS/Introducing page-type: learn-module-chapter +sidebar: learnsidebar --- -{{LearnSidebar}} - {{NextMenu("Learn_web_development/Extensions/Async_JS/Promises", "Learn_web_development/Extensions/Async_JS")}} In this article, we'll explain what asynchronous programming is, why we need it, and briefly discuss some of the ways asynchronous functions have historically been implemented in JavaScript. diff --git a/files/en-us/learn_web_development/extensions/async_js/introducing_workers/index.md b/files/en-us/learn_web_development/extensions/async_js/introducing_workers/index.md index 955ab7c7993913c..86138902d8f335c 100644 --- a/files/en-us/learn_web_development/extensions/async_js/introducing_workers/index.md +++ b/files/en-us/learn_web_development/extensions/async_js/introducing_workers/index.md @@ -2,10 +2,9 @@ title: Introducing workers slug: Learn_web_development/Extensions/Async_JS/Introducing_workers page-type: learn-module-chapter +sidebar: learnsidebar --- -{{LearnSidebar}} - {{PreviousMenuNext("Learn_web_development/Extensions/Async_JS/Implementing_a_promise-based_API", "Learn_web_development/Extensions/Async_JS/Sequencing_animations", "Learn_web_development/Extensions/Async_JS")}} In this final article in our "Asynchronous JavaScript" module, we'll introduce _workers_, which enable you to run some tasks in a separate {{Glossary("Thread", "thread")}} of execution. diff --git a/files/en-us/learn_web_development/extensions/async_js/promises/index.md b/files/en-us/learn_web_development/extensions/async_js/promises/index.md index 0ff94d19d175466..3cae2fa68d42005 100644 --- a/files/en-us/learn_web_development/extensions/async_js/promises/index.md +++ b/files/en-us/learn_web_development/extensions/async_js/promises/index.md @@ -1,11 +1,11 @@ --- title: How to use promises +short-title: Using promises slug: Learn_web_development/Extensions/Async_JS/Promises page-type: learn-module-chapter +sidebar: learnsidebar --- -{{LearnSidebar}} - {{PreviousMenuNext("Learn_web_development/Extensions/Async_JS/Introducing", "Learn_web_development/Extensions/Async_JS/Implementing_a_promise-based_API", "Learn_web_development/Extensions/Async_JS")}} **Promises** are the foundation of asynchronous programming in modern JavaScript. A promise is an object returned by an asynchronous function, which represents the current state of the operation. At the time the promise is returned to the caller, the operation often isn't finished, but the promise object provides methods to handle the eventual success or failure of the operation. @@ -24,7 +24,7 @@ page-type: learn-module-chapter <ul> <li>The concepts and fundamentals of using promises in JavaScript.</li> <li>Chaining and combining promises.</li> - <li>Handing errors in promises.</li> + <li>Handling errors in promises.</li> <li><code>async</code> and <code>await</code>: how they relate to promises, and why they are useful.</li> </ul> </td> @@ -80,7 +80,7 @@ Started request… Received response: 200 ``` -Note that `Started request…` is logged before we receive the response. Unlike a synchronous function, `fetch()` returns while the request is still going on, enabling our program to stay responsive. The response shows the `200` (OK) [status code](/en-US/docs/Web/HTTP/Status), meaning that our request succeeded. +Note that `Started request…` is logged before we receive the response. Unlike a synchronous function, `fetch()` returns while the request is still going on, enabling our program to stay responsive. The response shows the `200` (OK) [status code](/en-US/docs/Web/HTTP/Reference/Status), meaning that our request succeeded. This probably seems a lot like the example in the last article, where we added event handlers to the {{domxref("XMLHttpRequest")}} object. Instead of that, we're passing a handler into the `then()` method of the returned promise. @@ -188,7 +188,7 @@ First, a promise can be in one of three states: - **fulfilled**: the asynchronous function has succeeded. When a promise is fulfilled, its `then()` handler is called. - **rejected**: the asynchronous function has failed. When a promise is rejected, its `catch()` handler is called. -Note that what "succeeded" or "failed" means here is up to the API in question. For example, `fetch()` rejects the returned promise if (among other reasons) a network error prevented the request being sent, but fulfills the promise if the server sent a response, even if the response was an error like [404 Not Found](/en-US/docs/Web/HTTP/Status/404). +Note that what "succeeded" or "failed" means here is up to the API in question. For example, `fetch()` rejects the returned promise if (among other reasons) a network error prevented the request being sent, but fulfills the promise if the server sent a response, even if the response was an error like [404 Not Found](/en-US/docs/Web/HTTP/Reference/Status/404). Sometimes, we use the term **settled** to cover both **fulfilled** and **rejected**. diff --git a/files/en-us/learn_web_development/extensions/async_js/sequencing_animations/index.md b/files/en-us/learn_web_development/extensions/async_js/sequencing_animations/index.md index bcb48e2782a9566..86d1c244d4dd959 100644 --- a/files/en-us/learn_web_development/extensions/async_js/sequencing_animations/index.md +++ b/files/en-us/learn_web_development/extensions/async_js/sequencing_animations/index.md @@ -1,11 +1,11 @@ --- title: "Challenge: Sequencing animations" +short-title: "Challenge: Animation sequence" slug: Learn_web_development/Extensions/Async_JS/Sequencing_animations page-type: learn-module-assessment +sidebar: learnsidebar --- -{{LearnSidebar}} - {{PreviousMenu("Learn_web_development/Extensions/Async_JS/Introducing_workers", "Learn_web_development/Extensions/Async_JS")}} In this challenge you'll update a page to play a series of animations in a sequence. To do this you'll use some of the techniques we learned in the [How to use Promises](/en-US/docs/Learn_web_development/Extensions/Async_JS/Promises) article. diff --git a/files/en-us/learn_web_development/extensions/client-side_apis/client-side_storage/index.md b/files/en-us/learn_web_development/extensions/client-side_apis/client-side_storage/index.md index b85bfa9f25b579e..e17c1d3da05a020 100644 --- a/files/en-us/learn_web_development/extensions/client-side_apis/client-side_storage/index.md +++ b/files/en-us/learn_web_development/extensions/client-side_apis/client-side_storage/index.md @@ -2,10 +2,9 @@ title: Client-side storage slug: Learn_web_development/Extensions/Client-side_APIs/Client-side_storage page-type: learn-module-chapter +sidebar: learnsidebar --- -{{LearnSidebar}} - {{PreviousMenuNext("Learn_web_development/Extensions/Client-side_APIs/Drawing_graphics", "Learn_web_development/Extensions/Client-side_APIs/Third_party_APIs", "Learn_web_development/Extensions/Client-side_APIs")}} Modern web browsers support a number of ways for websites to store data on the user's computer — with the user's permission — then retrieve it when necessary. This lets you persist data for long-term storage, save sites or documents for offline use, retain user-specific settings for your site, and more. This article explains the very basics of how these work. @@ -37,10 +36,10 @@ Modern web browsers support a number of ways for websites to store data on the u Elsewhere in the MDN learning area, we talked about the difference between [static sites](/en-US/docs/Learn_web_development/Extensions/Server-side/First_steps/Client-Server_overview#static_sites) and [dynamic sites](/en-US/docs/Learn_web_development/Extensions/Server-side/First_steps/Client-Server_overview#dynamic_sites). Most major modern websites are dynamic — they store data on the server using some kind of database (server-side storage), then run [server-side](/en-US/docs/Learn_web_development/Extensions/Server-side) code to retrieve needed data, insert it into static page templates, and serve the resulting HTML to the client to be displayed by the user's browser. -Client-side storage works on similar principles, but has different uses. It consists of JavaScript APIs that allow you to store data on the client (i.e. on the user's machine) and then retrieve it when needed. This has many distinct uses, such as: +Client-side storage works on similar principles, but has different uses. It consists of JavaScript APIs that allow you to store data on the client (i.e., on the user's machine) and then retrieve it when needed. This has many distinct uses, such as: -- Personalizing site preferences (e.g. showing a user's choice of custom widgets, color scheme, or font size). -- Persisting previous site activity (e.g. storing the contents of a shopping cart from a previous session, remembering if a user was previously logged in). +- Personalizing site preferences (e.g., showing a user's choice of custom widgets, color scheme, or font size). +- Persisting previous site activity (e.g., storing the contents of a shopping cart from a previous session, remembering if a user was previously logged in). - Saving data and assets locally so a site will be quicker (and potentially less expensive) to download, or be usable without a network connection. - Saving web application generated documents locally for use offline @@ -51,9 +50,9 @@ Often client-side and server-side storage are used together. For example, you co ### Old school: Cookies -The concept of client-side storage has been around for a long time. Since the early days of the web, sites have used [cookies](/en-US/docs/Web/HTTP/Cookies) to store information to personalize user experience on websites. They're the earliest form of client-side storage commonly used on the web. +The concept of client-side storage has been around for a long time. Since the early days of the web, sites have used [cookies](/en-US/docs/Web/HTTP/Guides/Cookies) to store information to personalize user experience on websites. They're the earliest form of client-side storage commonly used on the web. -These days, there are easier mechanisms available for storing client-side data, therefore we won't be teaching you how to use cookies in this article. However, this does not mean cookies are completely useless on the modern-day web — they are still used commonly to store data related to user personalization and state, e.g. session IDs and access tokens. For more information on cookies see our [Using HTTP cookies](/en-US/docs/Web/HTTP/Cookies) article. +These days, there are easier mechanisms available for storing client-side data, therefore we won't be teaching you how to use cookies in this article. However, this does not mean cookies are completely useless on the modern-day web — they are still used commonly to store data related to user personalization and state, e.g., session IDs and access tokens. For more information on cookies see our [Using HTTP cookies](/en-US/docs/Web/HTTP/Guides/Cookies) article. ### New school: Web Storage and IndexedDB @@ -408,7 +407,7 @@ This is quite complex; breaking it down, we: - Run {{domxref("Event.preventDefault()")}} on the event object to stop the form actually submitting in the conventional manner (this would cause a page refresh and spoil the experience). - Create an object representing a record to enter into the database, populating it with values from the form inputs. Note that we don't have to explicitly include an `id` value — as we explained earlier, this is auto-populated. -- Open a `readwrite` transaction against the `notes_os` object store using the {{domxref("IDBDatabase.transaction()")}} method. This transaction object allows us to access the object store so we can do something to it, e.g. add a new record. +- Open a `readwrite` transaction against the `notes_os` object store using the {{domxref("IDBDatabase.transaction()")}} method. This transaction object allows us to access the object store so we can do something to it, e.g., add a new record. - Access the object store using the {{domxref("IDBTransaction.objectStore()")}} method, saving the result in the `objectStore` variable. - Add the new record to the database using {{domxref("IDBObjectStore.add()")}}. This creates a request object, in the same fashion as we've seen before. - Add a bunch of event handlers to the `request` and the `transaction` objects to run code at critical points in the lifecycle. Once the request has succeeded, we clear the form inputs ready for entering the next note. Once the transaction has completed, we run the `displayData()` function again to update the display of notes on the page. @@ -697,7 +696,7 @@ if ("serviceWorker" in navigator) { #### Installing the service worker -The next time any page under the service worker's control is accessed (e.g. when the example is reloaded), the service worker is installed against that page, meaning that it will start controlling it. When this occurs, an `install` event is fired against the service worker; you can write code inside the service worker itself that will respond to the installation. +The next time any page under the service worker's control is accessed (e.g., when the example is reloaded), the service worker is installed against that page, meaning that it will start controlling it. When this occurs, an `install` event is fired against the service worker; you can write code inside the service worker itself that will respond to the installation. Let's look at an example, in the [sw.js](https://github.com/mdn/learning-area/blob/main/javascript/apis/client-side-storage/cache-sw/video-store-offline/sw.js) file (the service worker). You'll see that the install listener is registered against `self`. This `self` keyword is a way to refer to the global scope of the service worker from inside the service worker file. @@ -732,7 +731,7 @@ This is what the second bit of code in `sw.js` does. We add another listener to Inside the handler, we first log the URL of the requested asset. We then provide a custom response to the request, using the {{domxref("FetchEvent.respondWith()")}} method. -Inside this block, we use {{domxref("CacheStorage.match()")}} to check whether a matching request (i.e. matches the URL) can be found in any cache. This promise fulfills with the matching response if a match is found, or `undefined` if it isn't. +Inside this block, we use {{domxref("CacheStorage.match()")}} to check whether a matching request (i.e., matches the URL) can be found in any cache. This promise fulfills with the matching response if a match is found, or `undefined` if it isn't. If a match is found, we return it as the custom response. If not, we [fetch()](/en-US/docs/Web/API/Window/fetch) the response from the network and return that instead. @@ -767,7 +766,7 @@ That's it for now. We hope you've found our rundown of client-side storage techn - [Web storage API](/en-US/docs/Web/API/Web_Storage_API) - [IndexedDB API](/en-US/docs/Web/API/IndexedDB_API) -- [Cookies](/en-US/docs/Web/HTTP/Cookies) +- [Cookies](/en-US/docs/Web/HTTP/Guides/Cookies) - [Service worker API](/en-US/docs/Web/API/Service_Worker_API) {{PreviousMenuNext("Learn_web_development/Extensions/Client-side_APIs/Drawing_graphics", "Learn_web_development/Extensions/Client-side_APIs/Third_party_APIs", "Learn_web_development/Extensions/Client-side_APIs")}} diff --git a/files/en-us/learn_web_development/extensions/client-side_apis/drawing_graphics/index.md b/files/en-us/learn_web_development/extensions/client-side_apis/drawing_graphics/index.md index 1c0e12198e6b05a..306ba0d2dfcb4ce 100644 --- a/files/en-us/learn_web_development/extensions/client-side_apis/drawing_graphics/index.md +++ b/files/en-us/learn_web_development/extensions/client-side_apis/drawing_graphics/index.md @@ -2,10 +2,9 @@ title: Drawing graphics slug: Learn_web_development/Extensions/Client-side_APIs/Drawing_graphics page-type: learn-module-chapter +sidebar: learnsidebar --- -{{LearnSidebar}} - {{PreviousMenuNext("Learn_web_development/Extensions/Client-side_APIs/Video_and_audio_APIs", "Learn_web_development/Extensions/Client-side_APIs/Client-side_storage", "Learn_web_development/Extensions/Client-side_APIs")}} The browser contains some very powerful graphics programming tools, from the Scalable Vector Graphics ([SVG](/en-US/docs/Web/SVG)) language, to APIs for drawing on HTML {{htmlelement("canvas")}} elements, (see [The Canvas API](/en-US/docs/Web/API/Canvas_API) and [WebGL](/en-US/docs/Web/API/WebGL_API)). This article provides an introduction to canvas, and further resources to allow you to learn more. @@ -70,7 +69,7 @@ You should put some fallback content inside the `<canvas>` tags. This should des The fallback should provide useful alternative content to the canvas content. For example, if you are rendering a constantly updating graph of stock prices, the fallback content could be a static image of the latest stock graph, with `alt` text saying what the prices are in text or a list of links to individual stock pages. > [!NOTE] -> Canvas content is not accessible to screen readers. Include descriptive text as the value of the [`aria-label`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-label) attribute directly on the canvas element itself or include fallback content placed within the opening and closing `<canvas>` tags. Canvas content is not part of the DOM, but nested fallback content is. +> Canvas content is not accessible to screen readers. Include descriptive text as the value of the [`aria-label`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-label) attribute directly on the canvas element itself or include fallback content placed within the opening and closing `<canvas>` tags. Canvas content is not part of the DOM, but nested fallback content is. ### Creating and sizing our canvas @@ -298,7 +297,7 @@ Now let's look at how to draw a circle in canvas. This is accomplished using the The pattern here is very similar, but with two differences: - We have set the last parameter of `arc()` to `true`, meaning that the arc is drawn counterclockwise, which means that even though the arc is specified as starting at -45 degrees and ending at 45 degrees, we draw the arc around the 270 degrees not inside this portion. If you were to change `true` to `false` and then re-run the code, only the 90 degree slice of the circle would be drawn. - - Before calling `fill()`, we draw a line to the center of the circle. This means that we get the rather nice Pac-Man-style cutout rendered. If you removed this line (try it!) then re-ran the code, you'd get just an edge of the circle chopped off between the start and end point of the arc. This illustrates another important point of the canvas — if you try to fill an incomplete path (i.e. one that is not closed), the browser fills in a straight line between the start and end point and then fills it in. + - Before calling `fill()`, we draw a line to the center of the circle. This means that we get the rather nice Pac-Man-style cutout rendered. If you removed this line (try it!) then re-ran the code, you'd get just an edge of the circle chopped off between the start and end point of the arc. This illustrates another important point of the canvas — if you try to fill an incomplete path (i.e., one that is not closed), the browser fills in a straight line between the start and end point and then fills it in. That's it for now; your final example should look like this: @@ -364,7 +363,7 @@ It is possible to render external images onto your canvas. These can be simple i image.src = "firefox.png"; ``` - Here we create a new {{domxref("HTMLImageElement")}} object using the {{domxref("HTMLImageElement.Image()", "Image()")}} constructor. The returned object is the same type as that which is returned when you grab a reference to an existing {{htmlelement("img")}} element. We then set its [`src`](/en-US/docs/Web/HTML/Element/img#src) attribute to equal our Firefox logo image. At this point, the browser starts loading the image. + Here we create a new {{domxref("HTMLImageElement")}} object using the {{domxref("HTMLImageElement.Image()", "Image()")}} constructor. The returned object is the same type as that which is returned when you grab a reference to an existing {{htmlelement("img")}} element. We then set its [`src`](/en-US/docs/Web/HTML/Reference/Elements/img#src) attribute to equal our Firefox logo image. At this point, the browser starts loading the image. 3. We could now try to embed the image using `drawImage()`, but we need to make sure the image file has been loaded first, otherwise the code will fail. We can achieve this using the `load` event, which will only be fired when the image has finished loading. Add the following block below the previous one: @@ -516,7 +515,7 @@ Optimizing animation of graphics is an entire specialty of programming, with lot In general, the process of doing a canvas animation involves the following steps: -1. Clear the canvas contents (e.g. with {{domxref("CanvasRenderingContext2D.fillRect", "fillRect()")}} or {{domxref("CanvasRenderingContext2D.clearRect", "clearRect()")}}). +1. Clear the canvas contents (e.g., with {{domxref("CanvasRenderingContext2D.fillRect", "fillRect()")}} or {{domxref("CanvasRenderingContext2D.clearRect", "clearRect()")}}). 2. Save state (if necessary) using {{domxref("CanvasRenderingContext2D.save", "save()")}} — this is needed when you want to save settings you've updated on the canvas before continuing, which is useful for more advanced applications. 3. Draw the graphics you are animating. 4. Restore the settings you saved in step 2, using {{domxref("CanvasRenderingContext2D.restore", "restore()")}} @@ -545,7 +544,7 @@ Now let's create our own simple animation — we'll get a character from a certa ctx.translate(width / 2, height / 2); ``` -4. Now let's create a new {{domxref("HTMLImageElement")}} object, set its [`src`](/en-US/docs/Web/HTML/Element/img#src) to the image we want to load, and add an `onload` event handler that will cause the `draw()` function to fire when the image is loaded: +4. Now let's create a new {{domxref("HTMLImageElement")}} object, set its [`src`](/en-US/docs/Web/HTML/Reference/Elements/img#src) to the image we want to load, and add an `onload` event handler that will cause the `draw()` function to fire when the image is loaded: ```js const image = new Image(); diff --git a/files/en-us/learn_web_development/extensions/client-side_apis/index.md b/files/en-us/learn_web_development/extensions/client-side_apis/index.md index 2ae46f8b18a8ef2..f5c64a388dc7791 100644 --- a/files/en-us/learn_web_development/extensions/client-side_apis/index.md +++ b/files/en-us/learn_web_development/extensions/client-side_apis/index.md @@ -2,10 +2,9 @@ title: Client-side web APIs slug: Learn_web_development/Extensions/Client-side_APIs page-type: learn-module +sidebar: learnsidebar --- -{{LearnSidebar}} - {{NextMenu("Learn_web_development/Extensions/Client-side_APIs/Introduction", "Learn_web_development/Extensions")}} **Application Programming Interfaces** (**APIs**) are programming features for manipulating different aspects of the browser and operating system the site is running on, or manipulating data from other websites or services. This module covers common aspects of some of the most common classes of Web APIs that we haven't previously covered in any kind of detail, providing a useful grounding for those who want to go deeper into browser API usage. @@ -30,6 +29,6 @@ It would also be helpful to have some familiarity with [HTML](/en-US/docs/Learn_ - [Client-side storage](/en-US/docs/Learn_web_development/Extensions/Client-side_APIs/Client-side_storage) - : Modern web browsers feature a number of different technologies that allow you to store data related to websites and retrieve it when necessary allowing you to persist data long term, save sites offline, and more. This article explains the very basics of how these work. - [Third party APIs](/en-US/docs/Learn_web_development/Extensions/Client-side_APIs/Third_party_APIs) - - : The APIs we've covered so far are built into the browser, but not all APIs are. Many large websites and services such as Google Maps, Facebook, PayPal, etc. provide APIs allowing developers to make use of their data or services (e.g. displaying custom Google Maps on your site, or using Facebook login to log in your users). This article looks at the difference between browser APIs and 3rd party APIs and shows some typical uses of the latter. + - : The APIs we've covered so far are built into the browser, but not all APIs are. Many large websites and services such as Google Maps, Facebook, PayPal, etc. provide APIs allowing developers to make use of their data or services (e.g., displaying custom Google Maps on your site, or using Facebook login to log in your users). This article looks at the difference between browser APIs and 3rd party APIs and shows some typical uses of the latter. {{NextMenu("Learn_web_development/Extensions/Client-side_APIs/Introduction", "Learn_web_development/Extensions")}} diff --git a/files/en-us/learn_web_development/extensions/client-side_apis/introduction/index.md b/files/en-us/learn_web_development/extensions/client-side_apis/introduction/index.md index 3f0184b1416b94b..6eaf2481930bac3 100644 --- a/files/en-us/learn_web_development/extensions/client-side_apis/introduction/index.md +++ b/files/en-us/learn_web_development/extensions/client-side_apis/introduction/index.md @@ -1,11 +1,11 @@ --- title: Introduction to web APIs +short-title: Introduction slug: Learn_web_development/Extensions/Client-side_APIs/Introduction page-type: learn-module-chapter +sidebar: learnsidebar --- -{{LearnSidebar}} - {{NextMenu("Learn_web_development/Extensions/Client-side_APIs/Video_and_audio_APIs", "Learn_web_development/Extensions/Client-side_APIs")}} First up, we'll start by looking at APIs from a high level — what are they, how do they work, how to use them in your code, and how are they structured? We'll also take a look at what the different main classes of APIs are, and what kind of uses they have. @@ -49,7 +49,7 @@ In the same way, if you want to say, program some 3D graphics, it is a lot easie Client-side JavaScript, in particular, has many APIs available to it — these are not part of the JavaScript language itself, rather they are built on top of the core JavaScript language, providing you with extra superpowers to use in your JavaScript code. They generally fall into two categories: -- **Browser APIs** are built into your web browser and are able to expose data from the browser and surrounding computer environment and do useful complex things with it. For example, the [Web Audio API](/en-US/docs/Web/API/Web_Audio_API) provides JavaScript constructs for manipulating audio in the browser — taking an audio track, altering its volume, applying effects to it, etc. In the background, the browser is actually using some complex lower-level code (e.g. C++ or Rust) to do the actual audio processing. But again, this complexity is abstracted away from you by the API. +- **Browser APIs** are built into your web browser and are able to expose data from the browser and surrounding computer environment and do useful complex things with it. For example, the [Web Audio API](/en-US/docs/Web/API/Web_Audio_API) provides JavaScript constructs for manipulating audio in the browser — taking an audio track, altering its volume, applying effects to it, etc. In the background, the browser is actually using some complex lower-level code (e.g., C++ or Rust) to do the actual audio processing. But again, this complexity is abstracted away from you by the API. - **Third-party APIs** are not built into the browser by default, and you generally have to retrieve their code and information from somewhere on the Web. For example, the [Google Maps API](https://developers.google.com/maps/documentation/javascript) allows you to do things like display an interactive map to your office on your website. It provides a special set of constructs you can use to query the Google Maps service and return specific information. ![A screenshot of the browser with the home page of firefox browser open. There are APIs built into the browser by default. Third party APIs are not built into the browser by default. Their code and information has to be retrieved from somewhere on the web to utilize them.](browser.png) @@ -60,9 +60,9 @@ So above, we talked about what client-side JavaScript APIs are, and how they rel - JavaScript — A high-level scripting language built into browsers that allows you to implement functionality on web pages/apps. Note that JavaScript is also available in other programming environments, such as [Node](/en-US/docs/Learn_web_development/Extensions/Server-side/Express_Nodejs/Introduction). - Browser APIs — constructs built into the browser that sit on top of the JavaScript language and allow you to implement functionality more easily. -- Third-party APIs — constructs built into third-party platforms (e.g. Disqus, Facebook) that allow you to use some of those platform's functionality in your own web pages (for example, display your Disqus comments on a web page). +- Third-party APIs — constructs built into third-party platforms (e.g., Disqus, Facebook) that allow you to use some of those platform's functionality in your own web pages (for example, display your Disqus comments on a web page). - JavaScript libraries — Usually one or more JavaScript files containing [custom functions](/en-US/docs/Learn_web_development/Core/Scripting/Functions) that you can attach to your web page to speed up or enable writing common functionality. Examples include jQuery, Mootools and React. -- JavaScript frameworks — The next step up from libraries, JavaScript frameworks (e.g. Angular and Ember) tend to be packages of HTML, CSS, JavaScript, and other technologies that you install and then use to write an entire web application from scratch. The key difference between a library and a framework is "Inversion of Control". When calling a method from a library, the developer is in control. With a framework, the control is inverted: the framework calls the developer's code. +- JavaScript frameworks — The next step up from libraries, JavaScript frameworks (e.g., Angular and Ember) tend to be packages of HTML, CSS, JavaScript, and other technologies that you install and then use to write an entire web application from scratch. The key difference between a library and a framework is "Inversion of Control". When calling a method from a library, the developer is in control. With a framework, the control is inverted: the framework calls the developer's code. ## What can APIs do? @@ -77,7 +77,7 @@ In particular, the most common categories of browser APIs you'll use (and which - **APIs for drawing and manipulating graphics** are widely supported in browsers — the most popular ones are [Canvas](/en-US/docs/Web/API/Canvas_API) and [WebGL](/en-US/docs/Web/API/WebGL_API), which allow you to programmatically update the pixel data contained in an HTML {{htmlelement("canvas")}} element to create 2D and 3D scenes. For example, you might draw shapes such as rectangles or circles, import an image onto the canvas, and apply a filter to it such as sepia or grayscale using the Canvas API, or create a complex 3D scene with lighting and textures using WebGL. Such APIs are often combined with APIs for creating animation loops (such as {{domxref("window.requestAnimationFrame()")}}) and others to make constantly updating scenes like cartoons and games. - **[Audio and Video APIs](/en-US/docs/Web/Media/Guides/Audio_and_video_delivery)** like {{domxref("HTMLMediaElement")}}, the [Web Audio API](/en-US/docs/Web/API/Web_Audio_API), and [WebRTC](/en-US/docs/Web/API/WebRTC_API) allow you to do really interesting things with multimedia such as creating custom UI controls for playing audio and video, displaying text tracks like captions and subtitles along with your videos, grabbing video from your web camera to be manipulated via a canvas (see above) or displayed on someone else's computer in a web conference, or adding effects to audio tracks (such as gain, distortion, panning, etc.). - **Device APIs** enable you to interact with device hardware: for example, accessing the device GPS to find the user's position using the [Geolocation API](/en-US/docs/Web/API/Geolocation_API). -- **Client-side storage APIs** enable you to store data on the client-side, so you can create an app that will save its state between page loads, and perhaps even work when the device is offline. There are several options available, e.g. simple name/value storage with the [Web Storage API](/en-US/docs/Web/API/Web_Storage_API), and more complex database storage with the [IndexedDB API](/en-US/docs/Web/API/IndexedDB_API). +- **Client-side storage APIs** enable you to store data on the client-side, so you can create an app that will save its state between page loads, and perhaps even work when the device is offline. There are several options available, e.g., simple name/value storage with the [Web Storage API](/en-US/docs/Web/API/Web_Storage_API), and more complex database storage with the [IndexedDB API](/en-US/docs/Web/API/IndexedDB_API). ### Common third-party APIs @@ -108,7 +108,7 @@ Let's return to the example of the Web Audio API — this is a fairly complex AP - {{domxref("AudioContext")}}, which represents an [audio graph](/en-US/docs/Web/API/Web_Audio_API/Basic_concepts_behind_Web_Audio_API#audio_graphs) that can be used to manipulate audio playing inside the browser, and has a number of methods and properties available to manipulate that audio. - {{domxref("MediaElementAudioSourceNode")}}, which represents an {{htmlelement("audio")}} element containing sound you want to play and manipulate inside the audio context. -- {{domxref("AudioDestinationNode")}}, which represents the destination of the audio, i.e. the device on your computer that will actually output it — usually your speakers or headphones. +- {{domxref("AudioDestinationNode")}}, which represents the destination of the audio, i.e., the device on your computer that will actually output it — usually your speakers or headphones. So how do these objects interact? If you look at our [simple web audio example](https://github.com/mdn/learning-area/blob/main/javascript/apis/introduction/web-audio/index.html) ([see it live also](https://mdn.github.io/learning-area/javascript/apis/introduction/web-audio/)), you'll first see the following HTML: @@ -190,7 +190,7 @@ The final thing to do to get this to work is to connect the different nodes in t audioSource.connect(gainNode).connect(audioCtx.destination); ``` -The audio starts in the source, which is then connected to the gain node so the audio's volume can be adjusted. The gain node is then connected to the destination node so the sound can be played on your computer (the {{domxref("BaseAudioContext/destination", "AudioContext.destination")}} property represents whatever is the default {{domxref("AudioDestinationNode")}} available on your computer's hardware, e.g. your speakers). +The audio starts in the source, which is then connected to the gain node so the audio's volume can be adjusted. The gain node is then connected to the destination node so the sound can be played on your computer (the {{domxref("BaseAudioContext/destination", "AudioContext.destination")}} property represents whatever is the default {{domxref("AudioDestinationNode")}} available on your computer's hardware, e.g., your speakers). ### They have recognizable entry points @@ -273,7 +273,7 @@ In addition, some WebAPIs request permission to be enabled from the user once ca The Web Audio and {{domxref("HTMLMediaElement")}} APIs are subject to a security mechanism called [autoplay policy](/en-US/docs/Web/API/Web_Audio_API/Best_practices#autoplay_policy) — this basically means that you can't automatically play audio when a page loads — you've got to allow your users to initiate audio play through a control like a button. This is done because autoplaying audio is usually really annoying and we really shouldn't be subjecting our users to it. > [!NOTE] -> Depending on how strict the browser is, such security mechanisms might even stop the example from working locally, i.e. if you load the local example file in your browser instead of running it from a web server. At the time of writing, our Web Audio API example wouldn't work locally on Google Chrome — we had to upload it to GitHub before it would work. +> Depending on how strict the browser is, such security mechanisms might even stop the example from working locally, i.e., if you load the local example file in your browser instead of running it from a web server. At the time of writing, our Web Audio API example wouldn't work locally on Google Chrome — we had to upload it to GitHub before it would work. ## Summary diff --git a/files/en-us/learn_web_development/extensions/client-side_apis/third_party_apis/index.md b/files/en-us/learn_web_development/extensions/client-side_apis/third_party_apis/index.md index f65a49dbfc37b68..6fdb99cd0b7b17e 100644 --- a/files/en-us/learn_web_development/extensions/client-side_apis/third_party_apis/index.md +++ b/files/en-us/learn_web_development/extensions/client-side_apis/third_party_apis/index.md @@ -2,13 +2,12 @@ title: Third-party APIs slug: Learn_web_development/Extensions/Client-side_APIs/Third_party_APIs page-type: learn-module-chapter +sidebar: learnsidebar --- -{{LearnSidebar}} - {{PreviousMenu("Learn_web_development/Extensions/Client-side_APIs/Client-side_storage", "Learn_web_development/Extensions/Client-side_APIs")}} -The APIs we've covered so far are built into the browser, but not all APIs are. Many large websites and services such as Google Maps, Twitter, Facebook, PayPal, etc. provide APIs allowing developers to make use of their data (e.g. displaying your twitter stream on your blog) or services (e.g. using Facebook login to log in your users). This article looks at the difference between browser APIs and 3rd party APIs and shows some typical uses of the latter. +The APIs we've covered so far are built into the browser, but not all APIs are. Many large websites and services such as Google Maps, Twitter, Facebook, PayPal, etc. provide APIs allowing developers to make use of their data (e.g., displaying your twitter stream on your blog) or services (e.g., using Facebook login to log in your users). This article looks at the difference between browser APIs and 3rd party APIs and shows some typical uses of the latter. <table> <tbody> @@ -112,8 +111,8 @@ Let's add some more functionality to the Mapquest example to show how to use som There are a number of different types of map that can be shown with the Mapquest API. To do this, find the following line: -```js -layers: L.mapquest.tileLayer("map"); +```js-nolint +layers: L.mapquest.tileLayer("map"), ``` Try changing `'map'` to `'hybrid'` to show a hybrid-style map. Try some other values too. The [`tileLayer` reference page](https://developer.mapquest.com/documentation/mapquest-js/v1.3/l-mapquest-tile-layer/) shows the different available options, plus a lot more information. @@ -189,7 +188,7 @@ The app will end up allowing you to type in a search term and optional start and ### Connect the API to your app -First, you'll need to make a connection between the API and your app. In the case of this API, you need to include the API key as a [get](/en-US/docs/Web/HTTP/Methods/GET) parameter every time you request data from the service at the correct URL. +First, you'll need to make a connection between the API and your app. In the case of this API, you need to include the API key as a [get](/en-US/docs/Web/HTTP/Reference/Methods/GET) parameter every time you request data from the service at the correct URL. 1. Find the following line: @@ -392,7 +391,7 @@ To get it running, you'll need to: - Make sure you visit the [Enabled APIs page](https://console.cloud.google.com/apis/enabled), and in the list of APIs, make sure the status is ON for the YouTube Data API v3. - Get an API key from [Google Cloud](https://cloud.google.com/). - Find the string `ENTER-API-KEY-HERE` in the source code, and replace it with your API key. -- Run the example through a web server. It won't work if you just run it directly in the browser (i.e. via a `file://` URL). +- Run the example through a web server. It won't work if you just run it directly in the browser (i.e., via a `file://` URL). ## Summary diff --git a/files/en-us/learn_web_development/extensions/client-side_apis/video_and_audio_apis/index.md b/files/en-us/learn_web_development/extensions/client-side_apis/video_and_audio_apis/index.md index 4c4b666379a92f4..3476547a3dc0a43 100644 --- a/files/en-us/learn_web_development/extensions/client-side_apis/video_and_audio_apis/index.md +++ b/files/en-us/learn_web_development/extensions/client-side_apis/video_and_audio_apis/index.md @@ -1,11 +1,11 @@ --- -title: Video and Audio APIs +title: Video and audio APIs +short-title: Video and audio slug: Learn_web_development/Extensions/Client-side_APIs/Video_and_audio_APIs page-type: learn-module-chapter +sidebar: learnsidebar --- -{{LearnSidebar}} - {{PreviousMenuNext("Learn_web_development/Extensions/Client-side_APIs/Introduction", "Learn_web_development/Extensions/Client-side_APIs/Drawing_graphics", "Learn_web_development/Extensions/Client-side_APIs")}} HTML comes with elements for embedding rich media in documents — {{htmlelement("video")}} and {{htmlelement("audio")}} — which in turn come with their own APIs for controlling playback, seeking, etc. This article shows you how to do common tasks such as creating custom playback controls. @@ -50,7 +50,7 @@ This creates a video player inside the browser like so: {{EmbedGHLiveSample("learning-area/html/multimedia-and-embedding/video-and-audio-content/multiple-video-formats.html", '100%', 380)}} -You can review what all the HTML features do in the article linked above; for our purposes here, the most interesting attribute is [`controls`](/en-US/docs/Web/HTML/Element/video#controls), which enables the default set of playback controls. If you don't specify this, you get no playback controls: +You can review what all the HTML features do in the article linked above; for our purposes here, the most interesting attribute is [`controls`](/en-US/docs/Web/HTML/Reference/Elements/video#controls), which enables the default set of playback controls. If you don't specify this, you get no playback controls: {{EmbedGHLiveSample("learning-area/html/multimedia-and-embedding/video-and-audio-content/multiple-video-formats-no-controls.html", '100%', 380)}} @@ -164,7 +164,7 @@ First of all, at the top of the CSS we use a {{cssxref("@font-face")}} block to Next, we use generated content to display an icon on each button: - We use the {{cssxref("::before")}} selector to display the content before each {{htmlelement("button")}} element. -- We use the {{cssxref("content")}} property to set the content to be displayed in each case to be equal to the contents of the [`data-icon`](/en-US/docs/Learn_web_development/Howto/Solve_HTML_problems/Use_data_attributes) attribute. In the case of our play button, `data-icon` contains a capital "P". +- We use the {{cssxref("content")}} property to set the content to be displayed in each case to be equal to the contents of the [`data-icon`](/en-US/docs/Web/HTML/How_to/Use_data_attributes) attribute. In the case of our play button, `data-icon` contains a capital "P". - We apply the custom web font to our buttons using {{cssxref("font-family")}}. In this font, "P" is actually a "play" icon, so therefore the play button has a "play" icon displayed on it. Icon fonts are very cool for many reasons — cutting down on HTTP requests because you don't need to download those icons as image files, great scalability, and the fact that you can use text properties to style them — like {{cssxref("color")}} and {{cssxref("text-shadow")}}. @@ -457,7 +457,7 @@ Here are some suggestions for ways you could enhance the existing example we've - {{domxref("HTMLMediaElement")}} - [HTML video and audio](/en-US/docs/Learn_web_development/Core/Structuring_content/HTML_video_and_audio) — simple guide to `<video>` and `<audio>` HTML. - [Audio and video delivery](/en-US/docs/Web/Media/Guides/Audio_and_video_delivery) — detailed guide to delivering media inside the browser, with many tips, tricks, and links to further more advanced tutorials. -- [Audio and video manipulation](/en-US/docs/Web/Media/Guides/Audio_and_video_manipulation) — detailed guide to manipulating audio and video, e.g. with [Canvas API](/en-US/docs/Web/API/Canvas_API), [Web Audio API](/en-US/docs/Web/API/Web_Audio_API), and more. +- [Audio and video manipulation](/en-US/docs/Web/Media/Guides/Audio_and_video_manipulation) — detailed guide to manipulating audio and video, e.g., with [Canvas API](/en-US/docs/Web/API/Canvas_API), [Web Audio API](/en-US/docs/Web/API/Web_Audio_API), and more. - {{htmlelement("video")}} and {{htmlelement("audio")}} reference pages. - [Guide to media types and formats on the web](/en-US/docs/Web/Media/Guides/Formats) diff --git a/files/en-us/learn_web_development/extensions/client-side_tools/deployment/index.md b/files/en-us/learn_web_development/extensions/client-side_tools/deployment/index.md index 8e7c859a72729fb..39f197beaa99c41 100644 --- a/files/en-us/learn_web_development/extensions/client-side_tools/deployment/index.md +++ b/files/en-us/learn_web_development/extensions/client-side_tools/deployment/index.md @@ -2,9 +2,10 @@ title: Deploying our app slug: Learn_web_development/Extensions/Client-side_tools/Deployment page-type: learn-module-chapter +sidebar: learnsidebar --- -{{LearnSidebar}}{{PreviousMenu("Learn_web_development/Extensions/Client-side_tools/Introducing_complete_toolchain", "Learn_web_development/Extensions/Client-side_tools")}} +{{PreviousMenu("Learn_web_development/Extensions/Client-side_tools/Introducing_complete_toolchain", "Learn_web_development/Extensions/Client-side_tools")}} In the final article in our series, we take the example toolchain we built up in the previous article and add to it so that we can deploy our sample app. We push the code to GitHub, deploy it using GitHub Pages, and even show you how to add a simple test into the process. @@ -77,7 +78,7 @@ We initialized our working directory as a git working directory earlier on. A qu git status ``` -You should get a status report of what files are being tracked, what files are staged, and so on — all terms that are part of the git grammar. If you get the error `fatal: not a git repository` returned, then the working directory is not a git working directory and you'll need to initialise git using `git init`. +You should get a status report of what files are being tracked, what files are staged, and so on — all terms that are part of the git grammar. If you get the error `fatal: not a git repository` returned, then the working directory is not a git working directory and you'll need to initialize git using `git init`. Now we have three tasks ahead of us: diff --git a/files/en-us/learn_web_development/extensions/client-side_tools/index.md b/files/en-us/learn_web_development/extensions/client-side_tools/index.md index efd214a07f9f21f..3af27aca5bab66c 100644 --- a/files/en-us/learn_web_development/extensions/client-side_tools/index.md +++ b/files/en-us/learn_web_development/extensions/client-side_tools/index.md @@ -2,10 +2,9 @@ title: Understanding client-side web development tools slug: Learn_web_development/Extensions/Client-side_tools page-type: learn-module +sidebar: learnsidebar --- -{{LearnSidebar}} - {{NextMenu("Learn_web_development/Extensions/Client-side_tools/Overview", "Learn_web_development/Extensions")}} Client-side tooling can be intimidating, but this series of articles aims to illustrate the purpose of some of the most common client-side tool types, explain the tools you can chain together, how to install them using package managers, and control them using the command line. We finish up by providing a complete toolchain example showing you how to get productive. diff --git a/files/en-us/learn_web_development/extensions/client-side_tools/introducing_complete_toolchain/index.md b/files/en-us/learn_web_development/extensions/client-side_tools/introducing_complete_toolchain/index.md index fbc588df727394f..5e128b28aa58a45 100644 --- a/files/en-us/learn_web_development/extensions/client-side_tools/introducing_complete_toolchain/index.md +++ b/files/en-us/learn_web_development/extensions/client-side_tools/introducing_complete_toolchain/index.md @@ -1,10 +1,12 @@ --- title: Introducing a complete toolchain +short-title: Sample toolchain slug: Learn_web_development/Extensions/Client-side_tools/Introducing_complete_toolchain page-type: learn-module-chapter +sidebar: learnsidebar --- -{{LearnSidebar}}{{PreviousMenuNext("Learn_web_development/Extensions/Client-side_tools/Package_management","Learn_web_development/Extensions/Client-side_tools/Deployment", "Learn_web_development/Extensions/Client-side_tools")}} +{{PreviousMenuNext("Learn_web_development/Extensions/Client-side_tools/Package_management","Learn_web_development/Extensions/Client-side_tools/Deployment", "Learn_web_development/Extensions/Client-side_tools")}} In the final couple of articles in the series, we will solidify your tooling knowledge by walking you through the process of building up a sample case study toolchain. We'll go all the way from setting up a sensible development environment and putting transformation tools in place to actually deploying your app. In this article, we'll introduce the case study, set up our development environment, and set up our code transformation tools. @@ -107,7 +109,7 @@ As we talked about in [Chapter 1](/en-US/docs/Learn_web_development/Extensions/C - **Development environment**: The tools that are most fundamental to running your code. This part is already set up in the previous chapter. - **Safety net**: Making the software development experience stable and more efficient. We might also refer to this as our development environment. -- **Transformation**: Tooling that allows us to use the latest features of a language (e.g. JavaScript) or another language entirely (e.g. JSX or TypeScript) in our development process, and then transforms our code so that the production version still runs on a wide variety of browsers, modern and older. +- **Transformation**: Tooling that allows us to use the latest features of a language (e.g., JavaScript) or another language entirely (e.g., JSX or TypeScript) in our development process, and then transforms our code so that the production version still runs on a wide variety of browsers, modern and older. - **Post development**: Tooling that comes into play after you are done with the body of development to ensure that your software makes it to the web and continues to run. In this case study we'll look at adding tests to your code, and deploying your app using GitHub Pages so it is available for all the web to see. Let's start working on these, beginning with our development environment. We will follow the same steps as how a real project would be set up, so in the future, if you are setting up a new project, you can refer back to this chapter and follow the steps again. @@ -162,7 +164,7 @@ npm install --save-dev prettier Note again that we are using `--save-dev` to add it as a dev dependency, because we only use it during development. -Like many tools made more recently Prettier comes with "sensible defaults". That means that you'll be able to use Prettier without having to configure anything (if you are happy with the [defaults](https://prettier.io/docs/en/configuration.html)). This lets you get on with what's important: the creative work. For demonstration, we'll add a config file. Create a file in the root of your `npm-experiment` directory called `.prettierrc.json`. Add the following contents: +Like many tools made more recently Prettier comes with "sensible defaults". That means that you'll be able to use Prettier without having to configure anything (if you are happy with the [defaults](https://prettier.io/docs/configuration.html)). This lets you get on with what's important: the creative work. For demonstration, we'll add a config file. Create a file in the root of your `npm-experiment` directory called `.prettierrc.json`. Add the following contents: ```json { @@ -170,7 +172,7 @@ Like many tools made more recently Prettier comes with "sensible defaults". That } ``` -With this setting, Prettier will print the `>` of a multi-line HTML (HTML, JSX, Vue, Angular) opening tag at the end of the last line instead of being alone on the next line. This is the format the MDN itself uses. You can find more about [configuring Prettier](https://prettier.io/docs/en/configuration.html) in its documentation. +With this setting, Prettier will print the `>` of a multi-line HTML (HTML, JSX, Vue, Angular) opening tag at the end of the last line instead of being alone on the next line. This is the format the MDN itself uses. You can find more about [configuring Prettier](https://prettier.io/docs/configuration.html) in its documentation. By default, Prettier formats all files that you specify. However, again, we don't need to format generated files, or there may be certain legacy code that we don't want to touch. We can tell Prettier to always ignore these files by creating a `.prettierignore` file in the root of the project directory. Add the following contents to the file: @@ -188,13 +190,13 @@ npx prettier --write ./index.html ``` > [!NOTE] -> In the command above, we use Prettier with the `--write` flag. Prettier understands this to mean "if there's any problem in my code format, go ahead and fix them, then save my file". This is fine for our development process, but we can also use `prettier` without the flag and it will only check the file. Checking the file (and not saving it) is useful for purposes like checks that run before a release - i.e. "don't release any code that's not been properly formatted." +> In the command above, we use Prettier with the `--write` flag. Prettier understands this to mean "if there's any problem in my code format, go ahead and fix them, then save my file". This is fine for our development process, but we can also use `prettier` without the flag and it will only check the file. Checking the file (and not saving it) is useful for purposes like checks that run before a release - i.e., "don't release any code that's not been properly formatted." You can also replace `./index.html` with any other file or folder to format them. For example, `.` will format everything in the current directory. In case you may forget the syntax, you can add it as a custom script in your package.json too: ```json "scripts": { - // ... + // … "format": "prettier --write ." }, ``` diff --git a/files/en-us/learn_web_development/extensions/client-side_tools/overview/index.md b/files/en-us/learn_web_development/extensions/client-side_tools/overview/index.md index 147fde7f9640761..56282baef43113f 100644 --- a/files/en-us/learn_web_development/extensions/client-side_tools/overview/index.md +++ b/files/en-us/learn_web_development/extensions/client-side_tools/overview/index.md @@ -1,11 +1,11 @@ --- title: Client-side tooling overview +short-title: Overview slug: Learn_web_development/Extensions/Client-side_tools/Overview page-type: learn-module-chapter +sidebar: learnsidebar --- -{{LearnSidebar}} - {{NextMenu("Learn_web_development/Extensions/Client-side_tools/Package_management", "Learn_web_development/Extensions/Client-side_tools")}} In this article, we provide an overview of modern web tooling, what kinds of tools are available and where you'll meet them in the lifecycle of web app development, and how to find help with individual tools. @@ -52,7 +52,7 @@ From a high-level perspective, you can put client-side tools into the following - **Environment** — Tools that help you set up your development environment, such as installing and running other tools. - **Safety net** — Tools that are useful during your code development. -- **Transformation** — Tools that transform code in some way, e.g. turning an intermediate language into JavaScript that a browser can understand. +- **Transformation** — Tools that transform code in some way, e.g., turning an intermediate language into JavaScript that a browser can understand. - **Post-development** — Tools that are useful after you have written your code, such as testing and deployment tools. Let's look at each one of these in more detail. diff --git a/files/en-us/learn_web_development/extensions/client-side_tools/package_management/index.md b/files/en-us/learn_web_development/extensions/client-side_tools/package_management/index.md index 515486dd3214be2..74a61c8420d2155 100644 --- a/files/en-us/learn_web_development/extensions/client-side_tools/package_management/index.md +++ b/files/en-us/learn_web_development/extensions/client-side_tools/package_management/index.md @@ -1,11 +1,11 @@ --- title: Package management basics +short-title: Package management slug: Learn_web_development/Extensions/Client-side_tools/Package_management page-type: learn-module-chapter +sidebar: learnsidebar --- -{{LearnSidebar}} - {{PreviousMenuNext("Learn_web_development/Extensions/Client-side_tools/Overview","Learn_web_development/Extensions/Client-side_tools/Introducing_complete_toolchain", "Learn_web_development/Extensions/Client-side_tools")}} In this article, we'll look at package managers in some detail to understand how we can use them in our own projects — to install project tool dependencies, keep them up-to-date, and more. @@ -38,7 +38,7 @@ A simple example of a useful dependency that your project might need is some cod A project dependency can be an entire JavaScript library or framework — such as React or Vue — or a very small utility like our human-readable date library, or it can be a command line tool such as Prettier or ESLint, which we talked about in previous articles. -Without modern build tools, dependencies like this might be included in your project using a simple [`<script>`](/en-US/docs/Web/HTML/Element/script) element, but this might not work right out of the box and you will likely need some modern tooling to bundle your code and dependencies together when they are released on the web. A bundle is a term that's generally used to refer to a single file on your web server that contains all the JavaScript for your software — typically compressed as much as possible to help reduce the time it takes to get your software downloaded and displayed in your visitors' browser. +Without modern build tools, dependencies like this might be included in your project using a simple [`<script>`](/en-US/docs/Web/HTML/Reference/Elements/script) element, but this might not work right out of the box and you will likely need some modern tooling to bundle your code and dependencies together when they are released on the web. A bundle is a term that's generally used to refer to a single file on your web server that contains all the JavaScript for your software — typically compressed as much as possible to help reduce the time it takes to get your software downloaded and displayed in your visitors' browser. In addition, what happens if you find a better tool that you want to use instead of the current one, or a new version of your dependency is released that you want to update to? This is not too painful for a couple of dependencies, but in larger projects with many dependencies, this kind of thing can become really challenging to keep track of. It makes more sense to use a **package manager** such as npm, as this will guarantee that the code is added and removed cleanly, as well as a host of other advantages. @@ -197,7 +197,7 @@ In Vite, the `index.html` file is front and central. It defines the starting poi Note that the `<script>` elements creates a dependency on a file called `src/main.jsx`, which declares the entry point of the JavaScript logic for the app. Create the `src` folder and create `main.jsx` in this folder, but leave it blank for now. > [!NOTE] -> The [`type="module"`](/en-US/docs/Web/HTML/Element/script/type) attribute is important. It tells the browser to treat the script as an ES module, which allows us to use `import` and `export` syntax in our JavaScript code. The file extension is `.jsx`, because in the next article, we will add React JSX syntax to it. Browsers don't understand JSX, but Vite will transform it to regular JavaScript for us, as if browsers do! +> The [`type="module"`](/en-US/docs/Web/HTML/Reference/Elements/script/type) attribute is important. It tells the browser to treat the script as an ES module, which allows us to use `import` and `export` syntax in our JavaScript code. The file extension is `.jsx`, because in the next article, we will add React JSX syntax to it. Browsers don't understand JSX, but Vite will transform it to regular JavaScript for us, as if browsers do! ### Having fun with Vite @@ -260,7 +260,7 @@ Go back to `http://localhost:5173` and you'll see a graph on the page. Change th ### Building our code for production -However, this code is not ready for production. Most build tooling systems, including Vite, have a "development mode" and a "production mode". The important difference is that a lot of the helpful features you will use in development are not needed in the final site, so will be stripped out for production, e.g. "hot module replacement", "live reloading", and "uncompressed and commented source code". Though far from exhaustive, these are some of the common web development features that are very helpful at the development stage but are not very useful in production. In production, they will just bloat your site. +However, this code is not ready for production. Most build tooling systems, including Vite, have a "development mode" and a "production mode". The important difference is that a lot of the helpful features you will use in development are not needed in the final site, so will be stripped out for production, e.g., "hot module replacement", "live reloading", and "uncompressed and commented source code". Though far from exhaustive, these are some of the common web development features that are very helpful at the development stage but are not very useful in production. In production, they will just bloat your site. Now stop the running Vite dev server using <kbd>Ctrl</kbd> + <kbd>C</kbd>. diff --git a/files/en-us/learn_web_development/extensions/forms/advanced_form_styling/index.md b/files/en-us/learn_web_development/extensions/forms/advanced_form_styling/index.md index 40860c7621de1d6..ed37b01a48e42c4 100644 --- a/files/en-us/learn_web_development/extensions/forms/advanced_form_styling/index.md +++ b/files/en-us/learn_web_development/extensions/forms/advanced_form_styling/index.md @@ -2,9 +2,10 @@ title: Advanced form styling slug: Learn_web_development/Extensions/Forms/Advanced_form_styling page-type: learn-module-chapter +sidebar: learnsidebar --- -{{LearnSidebar}}{{PreviousMenuNext("Learn_web_development/Extensions/Forms/Styling_web_forms", "Learn_web_development/Extensions/Forms/UI_pseudo-classes", "Learn_web_development/Extensions/Forms")}} +{{PreviousMenuNext("Learn_web_development/Extensions/Forms/Styling_web_forms", "Learn_web_development/Extensions/Forms/Customizable_select", "Learn_web_development/Extensions/Forms")}} In this article, we will see what can be done with CSS to style the types of form control that are more difficult to style — the "bad" and "ugly" categories. As we saw [in the previous article](/en-US/docs/Learn_web_development/Extensions/Forms/Styling_web_forms), text fields and buttons are perfectly easy to style; now we will dig into styling the more problematic bits. @@ -33,15 +34,17 @@ To recap what we said in the previous article, we have: **The bad**: Some elements are more difficult to style, requiring more complex CSS or some more specific tricks: - Checkboxes and radio buttons -- [`<input type="search">`](/en-US/docs/Web/HTML/Element/input/search) +- [`<input type="search">`](/en-US/docs/Web/HTML/Reference/Elements/input/search) **The ugly**: Some elements can't be styled thoroughly using CSS. These include: - Elements involved in creating dropdown widgets, including {{HTMLElement("select")}}, {{HTMLElement("option")}}, {{HTMLElement("optgroup")}} and {{HTMLElement("datalist")}}. -- [`<input type="color">`](/en-US/docs/Web/HTML/Element/input/color) -- Date-related controls such as [`<input type="datetime-local">`](/en-US/docs/Web/HTML/Element/input/datetime-local) -- [`<input type="range">`](/en-US/docs/Web/HTML/Element/input/range) -- [`<input type="file">`](/en-US/docs/Web/HTML/Element/input/file) + > [!NOTE] + > Some browsers now support [Customizable select elements](/en-US/docs/Learn_web_development/Extensions/Forms/Customizable_select), a set of HTML and CSS features that together enable full customization of `<select>` elements and their contents just like any regular DOM elements. +- [`<input type="color">`](/en-US/docs/Web/HTML/Reference/Elements/input/color) +- Date-related controls such as [`<input type="datetime-local">`](/en-US/docs/Web/HTML/Reference/Elements/input/datetime-local) +- [`<input type="range">`](/en-US/docs/Web/HTML/Reference/Elements/input/range) +- [`<input type="file">`](/en-US/docs/Web/HTML/Reference/Elements/input/file) - {{HTMLElement("progress")}} and {{HTMLElement("meter")}} Let's first talk about the [`appearance`](/en-US/docs/Web/CSS/appearance) property, which is pretty useful for making all of the above more stylable. @@ -97,7 +100,7 @@ In most cases, the effect is to remove the stylized border, which makes CSS styl ### Taming search boxes -[`<input type="search">`](/en-US/docs/Web/HTML/Element/input/search) is basically just a text input, so why is `appearance: none;` useful here? The answer is that Safari search boxes have some styling restrictions — you can't adjust their `height` or `font-size` freely, for example. +[`<input type="search">`](/en-US/docs/Web/HTML/Reference/Elements/input/search) is basically just a text input, so why is `appearance: none;` useful here? The answer is that Safari search boxes have some styling restrictions — you can't adjust their `height` or `font-size` freely, for example. This can be fixed using our friend `appearance: none;`, which disables the default appearance: @@ -247,7 +250,7 @@ If you view these checkboxes in a browser that doesn't support {{cssxref("appear ## What can be done about the "ugly" elements? -Now let's turn our attention to the "ugly" controls — the ones that are really hard to thoroughly style. In short, these are drop-down boxes, complex control types like [`color`](/en-US/docs/Web/HTML/Element/input/color) and [`datetime-local`](/en-US/docs/Web/HTML/Element/input/datetime-local), and feedback—oriented controls like {{HTMLElement("progress")}} and {{HTMLElement("meter")}}. +Now let's turn our attention to the "ugly" controls — the ones that are really hard to thoroughly style. In short, these are drop-down boxes, complex control types like [`color`](/en-US/docs/Web/HTML/Reference/Elements/input/color) and [`datetime-local`](/en-US/docs/Web/HTML/Reference/Elements/input/datetime-local), and feedback—oriented controls like {{HTMLElement("progress")}} and {{HTMLElement("meter")}}. The problem is that these elements have very different default looks across browsers, and while you can style them in some ways, some parts of their internals are literally impossible to style. @@ -325,7 +328,7 @@ button { > [!NOTE] > If you want to test these examples across a number of browsers simultaneously, you can [find it live here](https://mdn.github.io/learning-area/html/forms/styling-examples/ugly-controls.html) (also [see here for the source code](https://github.com/mdn/learning-area/blob/main/html/forms/styling-examples/ugly-controls.html)). > -> Also bear in mind that we've added some JavaScript to the page that lists the files selected by the file picker, below the control itself. This is a simplified version of the example found on the [`<input type="file">`](/en-US/docs/Web/HTML/Element/input/file#examples) reference page. +> Also bear in mind that we've added some JavaScript to the page that lists the files selected by the file picker, below the control itself. This is a simplified version of the example found on the [`<input type="file">`](/en-US/docs/Web/HTML/Reference/Elements/input/file#examples) reference page. As you can see, we've done fairly well at getting these to look uniform across modern browsers. @@ -367,9 +370,9 @@ Let's talk about some specifics of each of these types of control, highlighting ### Selects and datalists -In modern browsers, selects and datalists are generally not too bad to style provided you don't want to vary the look and feel too much from the defaults. +Some browsers now support [Customizable select elements](/en-US/docs/Learn_web_development/Extensions/Forms/Customizable_select), a set of HTML and CSS features that together enable full customization of `<select>` elements and their contents just like any regular DOM elements. In supporting browsers and codebases, you no longer need to worry about the legacy techniques described below for `<select>` elements. -We've managed to get the basic look of the boxes looking pretty uniform and consistent. The datalist control is `<input type="text">` anyway, so we knew this wouldn't be a problem. +Styling datalists and selects (in browsers that don't support customizable selects) allows an acceptable level of customization provided you don't want to vary the look and feel too much from the defaults. We've managed to get the basic look of the boxes looking pretty uniform and consistent. The datalist invoking control is an `<input type="text">` anyway, so we knew this wouldn't be a problem. Two things are slightly more problematic. First of all, the select's "arrow" icon that indicates it is a dropdown differs across browsers. It also tends to change if you increase the size of the select box, or resize in an ugly fashion. To fix this in our example we first used our old friend `appearance: none` to get rid of the icon altogether: @@ -423,16 +426,16 @@ Of course, this might also not fit in with the design you are going for, but it' ### Date input types -The date/time input types ([`datetime-local`](/en-US/docs/Web/HTML/Element/input/datetime-local), [`time`](/en-US/docs/Web/HTML/Element/input/time), [`week`](/en-US/docs/Web/HTML/Element/input/week), [`month`](/en-US/docs/Web/HTML/Element/input/month)) all have the same major associated issue. The actual containing box is as easy to style as any text input, and what we've got in this demo looks fine. +The date/time input types ([`datetime-local`](/en-US/docs/Web/HTML/Reference/Elements/input/datetime-local), [`time`](/en-US/docs/Web/HTML/Reference/Elements/input/time), [`week`](/en-US/docs/Web/HTML/Reference/Elements/input/week), [`month`](/en-US/docs/Web/HTML/Reference/Elements/input/month)) all have the same major associated issue. The actual containing box is as easy to style as any text input, and what we've got in this demo looks fine. -However, the internal parts of the control (e.g. the popup calendar that you use to pick a date, the spinner that you can use to increment/decrement values) are not stylable at all, and you can't get rid of them using `appearance: none;`. If you really need full control over the styling, you'll have to either use some kind of library to generate a custom control, or build your own. +However, the internal parts of the control (e.g., the popup calendar that you use to pick a date, the spinner that you can use to increment/decrement values) are not stylable at all, and you can't get rid of them using `appearance: none;`. If you really need full control over the styling, you'll have to either use some kind of library to generate a custom control, or build your own. > [!NOTE] -> It is worth mentioning [`<input type="number">`](/en-US/docs/Web/HTML/Element/input/number) here too — this also has a spinner that you can use to increment/decrement values, so potentially suffers from the same problem. However, in the case of the `number` type the data being collected is simpler, and it is easy to just use a `tel` input type instead which has the appearance of `text`, but displays the numeric keypad in devices with touch keyboards. +> It is worth mentioning [`<input type="number">`](/en-US/docs/Web/HTML/Reference/Elements/input/number) here too — this also has a spinner that you can use to increment/decrement values, so potentially suffers from the same problem. However, in the case of the `number` type the data being collected is simpler, and it is easy to just use a `tel` input type instead which has the appearance of `text`, but displays the numeric keypad in devices with touch keyboards. ### Range input types -[`<input type="range">`](/en-US/docs/Web/HTML/Element/input/range) is annoying to style. You can use something like the following to remove the default slider track completely and replace it with a custom style (a thin red track, in this case): +[`<input type="range">`](/en-US/docs/Web/HTML/Reference/Elements/input/range) is annoying to style. You can use something like the following to remove the default slider track completely and replace it with a custom style (a thin red track, in this case): ```css input[type="range"] { @@ -504,21 +507,14 @@ You can see the result of the above CSS styling in the below live example (see a ### Meters and progress bars -[`<meter>`](/en-US/docs/Web/HTML/Element/meter) and [`<progress>`](/en-US/docs/Web/HTML/Element/progress) are possibly the worst of the lot. As you saw in the earlier example, we can set them to the desired width relatively accurately. But beyond that, they are really difficult to style in any way. They don't handle height settings consistently between each other and between browsers, you can color the background, but not the foreground bar, and setting `appearance: none` on them makes things worse, not better. +[`<meter>`](/en-US/docs/Web/HTML/Reference/Elements/meter) and [`<progress>`](/en-US/docs/Web/HTML/Reference/Elements/progress) are possibly the worst of the lot. As you saw in the earlier example, we can set them to the desired width relatively accurately. But beyond that, they are really difficult to style in any way. They don't handle height settings consistently between each other and between browsers, you can color the background, but not the foreground bar, and setting `appearance: none` on them makes things worse, not better. It is easier to just create your own custom solution for these features, if you want to be able to control the styling, or use a third-party solution such as [progressbar.js](https://kimmobrunfeldt.github.io/progressbar.js/#examples). -The article [How to build custom form controls](/en-US/docs/Learn_web_development/Extensions/Forms/How_to_build_custom_form_controls) provides an example of how to build a custom designed select with HTML, CSS, and JavaScript. - ## Summary While there are still difficulties using CSS with HTML forms, there are ways to get around many of the problems. There are no clean, universal solutions, but modern browsers offer new possibilities. For now, the best solution is to learn more about the way the different browsers support CSS when applied to HTML form controls. -In the next article of this module, we will explore the different [UI pseudo-classes](/en-US/docs/Learn_web_development/Extensions/Forms/UI_pseudo-classes) available to us in modern browsers for styling forms in different states. - -{{PreviousMenuNext("Learn_web_development/Extensions/Forms/Styling_web_forms", "Learn_web_development/Extensions/Forms/UI_pseudo-classes", "Learn_web_development/Extensions/Forms")}} - -### Advanced Topics +In the next article of this module, we will explore creating [fully-customized `<select>` elements](/en-US/docs/Learn_web_development/Extensions/Forms/Customizable_select) using the dedicated, modern HTML and CSS features available for this purpose. -- [How to build custom form controls](/en-US/docs/Learn_web_development/Extensions/Forms/How_to_build_custom_form_controls) -- [Sending forms through JavaScript](/en-US/docs/Learn_web_development/Extensions/Forms/Sending_forms_through_JavaScript) +{{PreviousMenuNext("Learn_web_development/Extensions/Forms/Styling_web_forms", "Learn_web_development/Extensions/Forms/Customizable_select", "Learn_web_development/Extensions/Forms")}} diff --git a/files/en-us/learn_web_development/extensions/forms/basic_native_form_controls/index.md b/files/en-us/learn_web_development/extensions/forms/basic_native_form_controls/index.md index 89a36da4592a7e0..36423343010b2b3 100644 --- a/files/en-us/learn_web_development/extensions/forms/basic_native_form_controls/index.md +++ b/files/en-us/learn_web_development/extensions/forms/basic_native_form_controls/index.md @@ -2,9 +2,10 @@ title: Basic native form controls slug: Learn_web_development/Extensions/Forms/Basic_native_form_controls page-type: learn-module-chapter +sidebar: learnsidebar --- -{{LearnSidebar}}{{PreviousMenuNext("Learn_web_development/Extensions/Forms/How_to_structure_a_web_form", "Learn_web_development/Extensions/Forms/HTML5_input_types", "Learn_web_development/Extensions/Forms")}} +{{PreviousMenuNext("Learn_web_development/Extensions/Forms/How_to_structure_a_web_form", "Learn_web_development/Extensions/Forms/HTML5_input_types", "Learn_web_development/Extensions/Forms")}} In the [previous article](/en-US/docs/Learn_web_development/Extensions/Forms/How_to_structure_a_web_form), we marked up a functional web form example, introducing some form controls and common structural elements, and focusing on accessibility best practices. Next, we will look at the functionality of the different form controls, or widgets, in detail — studying all the different options available to collect different types of data. In this particular article, we will look at the original set of form controls, available in all browsers since the early days of the web. @@ -36,7 +37,7 @@ You've already met some form elements, including {{HTMLelement('form')}}, {{HTML - Some of the attributes that are common to all form controls. > [!NOTE] -> We cover additional, more powerful form controls in the next two articles. If you want a more advanced reference, you should consult our [HTML forms element reference](/en-US/docs/Web/HTML/Element#forms), and in particular our extensive [`<input>` types](/en-US/docs/Web/HTML/Element/input) reference. +> We cover additional, more powerful form controls in the next two articles. If you want a more advanced reference, you should consult our [HTML forms element reference](/en-US/docs/Web/HTML/Reference/Elements#forms), and in particular our extensive [`<input>` types](/en-US/docs/Web/HTML/Reference/Elements/input) reference. ## Text input fields @@ -47,17 +48,17 @@ Text {{htmlelement("input")}} fields are the most basic form widgets. They are a All basic text controls share some common behaviors: -- They can be marked as [`readonly`](/en-US/docs/Web/HTML/Element/input#readonly) (the user cannot modify the input value but it is still sent with the rest of the form data) or [`disabled`](/en-US/docs/Web/HTML/Element/input#disabled) (the input value can't be modified and is never sent with the rest of the form data). -- They can have a [`placeholder`](/en-US/docs/Web/HTML/Element/input#placeholder); this is the text that appears inside the text input box that should be used to briefly describe the purpose of the box. -- They can be constrained in [`size`](/en-US/docs/Web/HTML/Attributes/size) (the physical size of the box) and [`maxlength`](/en-US/docs/Web/HTML/Attributes/maxlength) (the maximum number of characters that can be entered into the box). -- They can benefit from spell-checking (using the [`spellcheck`](/en-US/docs/Web/HTML/Global_attributes/spellcheck) attribute). +- They can be marked as [`readonly`](/en-US/docs/Web/HTML/Reference/Elements/input#readonly) (the user cannot modify the input value but it is still sent with the rest of the form data) or [`disabled`](/en-US/docs/Web/HTML/Reference/Elements/input#disabled) (the input value can't be modified and is never sent with the rest of the form data). +- They can have a [`placeholder`](/en-US/docs/Web/HTML/Reference/Elements/input#placeholder); this is the text that appears inside the text input box that should be used to briefly describe the purpose of the box. +- They can be constrained in [`size`](/en-US/docs/Web/HTML/Reference/Attributes/size) (the physical size of the box) and [`maxlength`](/en-US/docs/Web/HTML/Reference/Attributes/maxlength) (the maximum number of characters that can be entered into the box). +- They can benefit from spell-checking (using the [`spellcheck`](/en-US/docs/Web/HTML/Reference/Global_attributes/spellcheck) attribute). > [!NOTE] -> The {{htmlelement("input")}} element is unique amongst HTML elements because it can take many forms depending on its [`type`](/en-US/docs/Web/HTML/Element/input#type) attribute value. It is used for creating most types of form widgets including single line text fields, time and date controls, controls without text input like checkboxes, radio buttons, and color pickers, and buttons. +> The {{htmlelement("input")}} element is unique amongst HTML elements because it can take many forms depending on its [`type`](/en-US/docs/Web/HTML/Reference/Elements/input#type) attribute value. It is used for creating most types of form widgets including single line text fields, time and date controls, controls without text input like checkboxes, radio buttons, and color pickers, and buttons. ### Single line text fields -A single line text field is created using an {{HTMLElement("input")}} element whose [`type`](/en-US/docs/Web/HTML/Element/input#type) attribute value is set to `text`, or by omitting the [`type`](/en-US/docs/Web/HTML/Element/input#type) attribute altogether (`text` is the default value). The value `text` for this attribute is also the fallback value if the value you specify for the [`type`](/en-US/docs/Web/HTML/Element/input#type) attribute is unknown by the browser (for example if you specify `type="color"` and the browser doesn't support native color pickers). +A single line text field is created using an {{HTMLElement("input")}} element whose [`type`](/en-US/docs/Web/HTML/Reference/Elements/input#type) attribute value is set to `text`, or by omitting the [`type`](/en-US/docs/Web/HTML/Reference/Elements/input#type) attribute altogether (`text` is the default value). The value `text` for this attribute is also the fallback value if the value you specify for the [`type`](/en-US/docs/Web/HTML/Reference/Elements/input#type) attribute is unknown by the browser (for example if you specify `type="color"` and the browser doesn't support native color pickers). > [!NOTE] > You can find examples of all the single line text field types on GitHub at [single-line-text-fields.html](https://github.com/mdn/learning-area/blob/main/html/forms/native-form-widgets/single-line-text-fields.html) ([see it live also](https://mdn.github.io/learning-area/html/forms/native-form-widgets/single-line-text-fields.html)). @@ -77,7 +78,7 @@ The screenshot below shows a text input in default, focused, and disabled states The screenshots used in this document were taken in the Chrome browser on macOS. There may be minor variations in these fields/buttons across different browsers, but the basic highlighting technique remains similar. > [!NOTE] -> We discuss values for the [`type`](/en-US/docs/Web/HTML/Element/input#type) attribute that enforce specific validation constraints including color, email, and url input types, in the next article, [The HTML5 input types](/en-US/docs/Learn_web_development/Extensions/Forms/HTML5_input_types). +> We discuss values for the [`type`](/en-US/docs/Web/HTML/Reference/Elements/input#type) attribute that enforce specific validation constraints including color, email, and url input types, in the next article, [The HTML5 input types](/en-US/docs/Learn_web_development/Extensions/Forms/HTML5_input_types). #### Password field @@ -91,9 +92,9 @@ The following screenshot shows Password input field in which each input characte ![Password field in chrome 115 on macOS](password.png) -The `password` value doesn't add any special constraints to the entered text, but it does obscure the value entered into the field (e.g. with dots or asterisks) so it can't be easily read by others. +The `password` value doesn't add any special constraints to the entered text, but it does obscure the value entered into the field (e.g., with dots or asterisks) so it can't be easily read by others. -Keep in mind this is just a user interface feature; unless you submit your form securely, it will get sent in plain text, which is bad for security — a malicious party could intercept your data and steal passwords, credit card details, or whatever else you've submitted. The best way to protect users from this is to host any pages involving forms over a secure connection (i.e. located at an `https://` address), so the data is encrypted before it is sent. +Keep in mind this is just a user interface feature; unless you submit your form securely, it will get sent in plain text, which is bad for security — a malicious party could intercept your data and steal passwords, credit card details, or whatever else you've submitted. The best way to protect users from this is to host any pages involving forms over a secure connection (i.e., located at an `https://` address), so the data is encrypted before it is sent. Browsers recognize the security implications of sending form data over an insecure connection, and have warnings to deter users from using insecure forms. For more information on what Firefox implements, see [Insecure passwords](/en-US/docs/Web/Security/Insecure_passwords). @@ -111,9 +112,9 @@ Other text input types, like {{HTMLElement("input/search", "search")}}, {{HTMLEl ## Checkable items: checkboxes and radio buttons -Checkable items are controls whose state you can change by clicking on them or their associated labels. There are two kinds of checkable items: the checkbox and the radio button. Both use the [`checked`](/en-US/docs/Web/HTML/Element/input/checkbox#checked) attribute to indicate whether the widget is checked by default or not. +Checkable items are controls whose state you can change by clicking on them or their associated labels. There are two kinds of checkable items: the checkbox and the radio button. Both use the [`checked`](/en-US/docs/Web/HTML/Reference/Elements/input/checkbox#checked) attribute to indicate whether the widget is checked by default or not. -It's worth noting that these widgets do not behave exactly like other form widgets. For most form widgets, once the form is submitted all widgets that have a [`name`](/en-US/docs/Web/HTML/Element/input#name) attribute are sent, even if no value has been filled out. In the case of checkable items, their values are sent only if they are checked. If they are not checked, nothing is sent, not even their name. If they are checked but have no value, the name is sent with a value of _on._ +It's worth noting that these widgets do not behave exactly like other form widgets. For most form widgets, once the form is submitted all widgets that have a [`name`](/en-US/docs/Web/HTML/Reference/Elements/input#name) attribute are sent, even if no value has been filled out. In the case of checkable items, their values are sent only if they are checked. If they are not checked, nothing is sent, not even their name. If they are checked but have no value, the name is sent with a value of _on._ > [!NOTE] > You can find the examples from this section on GitHub as [checkable-items.html](https://github.com/mdn/learning-area/blob/main/html/forms/native-form-widgets/checkable-items.html) ([see it live also](https://mdn.github.io/learning-area/html/forms/native-form-widgets/checkable-items.html)). @@ -122,13 +123,13 @@ For maximum usability/accessibility, you are advised to surround each list of re ### Checkbox -A checkbox is created using the {{HTMLElement("input")}} element with a [`type`](/en-US/docs/Web/HTML/Element/input#type) attribute set to the value {{HTMLElement("input/checkbox", "checkbox")}}. +A checkbox is created using the {{HTMLElement("input")}} element with a [`type`](/en-US/docs/Web/HTML/Reference/Elements/input#type) attribute set to the value {{HTMLElement("input/checkbox", "checkbox")}}. ```html <input type="checkbox" id="questionOne" name="subscribe" value="yes" checked /> ``` -Related checkbox items should use the same [`name`](/en-US/docs/Web/HTML/Element/input#name) attribute. Including the [`checked`](/en-US/docs/Web/HTML/Element/input/checkbox#checked) attribute makes the checkbox checked automatically when the page loads. Clicking the checkbox or its associated label toggles the checkbox on and off. +Related checkbox items should use the same [`name`](/en-US/docs/Web/HTML/Reference/Elements/input#name) attribute. Including the [`checked`](/en-US/docs/Web/HTML/Reference/Elements/input/checkbox#checked) attribute makes the checkbox checked automatically when the page loads. Clicking the checkbox or its associated label toggles the checkbox on and off. ```html <fieldset> @@ -160,19 +161,19 @@ The following screenshot shows checkboxes in the default, focused, and disabled ![Default, focused and disabled Checkboxes in chrome 115 on macOS](checkboxes.png) > [!NOTE] -> Any checkboxes and radio buttons with the [`checked`](/en-US/docs/Web/HTML/Element/input/checkbox#checked) attribute on load match the {{cssxref(':default')}} pseudo-class, even if they are no longer checked. Any that are currently checked match the {{cssxref(':checked')}} pseudo-class. +> Any checkboxes and radio buttons with the [`checked`](/en-US/docs/Web/HTML/Reference/Elements/input/checkbox#checked) attribute on load match the {{cssxref(':default')}} pseudo-class, even if they are no longer checked. Any that are currently checked match the {{cssxref(':checked')}} pseudo-class. Due to the on-off nature of checkboxes, the checkbox is considered a toggle button, with many developers and designers expanding on the default checkbox styling to create buttons that look like toggle switches. You can [see an example in action here](https://mdn.github.io/learning-area/html/forms/toggle-switch-example/) (also see the [source code](https://github.com/mdn/learning-area/blob/main/html/forms/toggle-switch-example/index.html)). ### Radio button -A radio button is created using the {{HTMLElement("input")}} element with its [`type`](/en-US/docs/Web/HTML/Element/input#type) attribute set to the value `radio`: +A radio button is created using the {{HTMLElement("input")}} element with its [`type`](/en-US/docs/Web/HTML/Reference/Elements/input#type) attribute set to the value `radio`: ```html <input type="radio" id="soup" name="meal" value="soup" checked /> ``` -Several radio buttons can be tied together. If they share the same value for their [`name`](/en-US/docs/Web/HTML/Element/input#name) attribute, they will be considered to be in the same group of buttons. Only one button in a given group may be checked at a time; this means that when one of them is checked all the others automatically get unchecked. When the form is sent, only the value of the checked radio button is sent. If none of them are checked, the whole pool of radio buttons is considered to be in an unknown state and no value is sent with the form. Once one of the radio buttons in a same-named group of buttons is checked, it is not possible for the user to uncheck all the buttons without resetting the form. +Several radio buttons can be tied together. If they share the same value for their [`name`](/en-US/docs/Web/HTML/Reference/Elements/input#name) attribute, they will be considered to be in the same group of buttons. Only one button in a given group may be checked at a time; this means that when one of them is checked all the others automatically get unchecked. When the form is sent, only the value of the checked radio button is sent. If none of them are checked, the whole pool of radio buttons is considered to be in an unknown state and no value is sent with the form. Once one of the radio buttons in a same-named group of buttons is checked, it is not possible for the user to uncheck all the buttons without resetting the form. ```html <fieldset> @@ -211,45 +212,22 @@ The radio button isn't actually a button, despite its name; let's move on and lo Then we also have the {{htmlelement("button")}} element itself. This can take a `type` attribute of value `submit`, `reset`, or `button` to mimic the behavior of the three `<input>` types mentioned above. The main difference between the two is that actual `<button>` elements are much easier to style. -```html -<input type="submit" value="Submit this form" /> -<input type="reset" value="Reset this form" /> -<input type="button" value="Do Nothing without JavaScript" /> - -<button type="submit">Submit this form</button> -<button type="reset">Reset this form</button> -<button type="button">Do Nothing without JavaScript</button> +```html live-sample___actual_buttons_ex +<p>Using &lt;input></p> +<p> + <input type="submit" value="Submit this form" /> + <input type="reset" value="Reset this form" /> + <input type="button" value="Do Nothing without JavaScript" /> +</p> +<p>Using &lt;button></p> +<p> + <button type="submit">Submit this form</button> + <button type="reset">Reset this form</button> + <button type="button">Do Nothing without JavaScript</button> +</p> ``` -```html hidden -<div class="button-demo"> - <p>Using &lt;input></p> - <p> - <input type="submit" value="Submit this form" /> - <input type="reset" value="Reset this form" /> - <input type="button" value="Do Nothing without JavaScript" /> - </p> - <p>Using &lt;button></p> - <p> - <button type="submit">Submit this form</button> - <button type="reset">Reset this form</button> - <button type="button">Do Nothing without JavaScript</button> - </p> -</div> -``` - -```css hidden -button, -input { - display: none; -} -.button-demo button, -.button-demo input { - all: revert; -} -``` - -{{ EmbedLiveSample('Actual_buttons', '500', '250') }} +{{ EmbedLiveSample('actual_buttons_ex', '500', '250') }} > [!NOTE] > The `image` input type also renders as a button. We'll cover that later too. @@ -293,7 +271,7 @@ The following screenshot shows a button in the default, focused, and disabled st The **image button** control is rendered exactly like an {{HTMLElement("img")}} element, except that when the user clicks on it, it behaves like a submit button. -An image button is created using an {{HTMLElement("input")}} element with its [`type`](/en-US/docs/Web/HTML/Element/input#type) attribute set to the value `image`. This element supports exactly the same set of attributes as the {{HTMLElement("img")}} element, plus all the attributes supported by other form buttons. +An image button is created using an {{HTMLElement("input")}} element with its [`type`](/en-US/docs/Web/HTML/Reference/Elements/input#type) attribute set to the value `image`. This element supports exactly the same set of attributes as the {{HTMLElement("img")}} element, plus all the attributes supported by other form buttons. ```html <input type="image" alt="Click me!" src="my-img.png" width="80" height="30" /> @@ -301,8 +279,8 @@ An image button is created using an {{HTMLElement("input")}} element with its [` If the image button is used to submit the form, this control doesn't submit its value — instead, the X and Y coordinates of the click on the image are submitted (the coordinates are relative to the image, meaning that the upper-left corner of the image represents the coordinate (0, 0)). The coordinates are sent as two key/value pairs: -- The X value key is the value of the [`name`](/en-US/docs/Web/HTML/Element/input#name) attribute followed by the string "_.x_". -- The Y value key is the value of the [`name`](/en-US/docs/Web/HTML/Element/input#name) attribute followed by the string "_.y_". +- The X value key is the value of the [`name`](/en-US/docs/Web/HTML/Reference/Elements/input#name) attribute followed by the string "_.x_". +- The Y value key is the value of the [`name`](/en-US/docs/Web/HTML/Reference/Elements/input#name) attribute followed by the string "_.y_". So for example when you click on the image at coordinate (123, 456) and it submits via the `get` method, you'll see the values appended to the URL as follows: @@ -316,7 +294,7 @@ This is a very convenient way to build a "hot map". How these values are sent an There is one last `<input>` type that came to us in early HTML: the file input type. Forms are able to send files to a server (this specific action is also detailed in the [Sending form data](/en-US/docs/Learn_web_development/Extensions/Forms/Sending_and_retrieving_form_data) article). The file picker widget can be used to choose one or more files to send. -To create a [file picker widget](/en-US/docs/Web/HTML/Element/input/file), you use the {{HTMLElement("input")}} element with its [`type`](/en-US/docs/Web/HTML/Element/input#type) attribute set to `file`. The types of files that are accepted can be constrained using the [`accept`](/en-US/docs/Web/HTML/Element/input#accept) attribute. In addition, if you want to let the user pick more than one file, you can do so by adding the [`multiple`](/en-US/docs/Web/HTML/Element/input#multiple) attribute. +To create a [file picker widget](/en-US/docs/Web/HTML/Reference/Elements/input/file), you use the {{HTMLElement("input")}} element with its [`type`](/en-US/docs/Web/HTML/Reference/Elements/input#type) attribute set to `file`. The types of files that are accepted can be constrained using the [`accept`](/en-US/docs/Web/HTML/Reference/Elements/input#accept) attribute. In addition, if you want to let the user pick more than one file, you can do so by adding the [`multiple`](/en-US/docs/Web/HTML/Reference/Elements/input#multiple) attribute. ### Example @@ -354,7 +332,7 @@ Many of the elements used to define form controls have some of their own specifi <tr> <td> <code - ><a href="/en-US/docs/Web/HTML/Global_attributes/autofocus" + ><a href="/en-US/docs/Web/HTML/Reference/Global_attributes/autofocus" >autofocus</a ></code > @@ -368,7 +346,7 @@ Many of the elements used to define form controls have some of their own specifi <tr> <td> <code - ><a href="/en-US/docs/Web/HTML/Attributes/disabled">disabled</a></code + ><a href="/en-US/docs/Web/HTML/Reference/Attributes/disabled">disabled</a></code > </td> <td>false</td> @@ -380,7 +358,7 @@ Many of the elements used to define form controls have some of their own specifi </tr> <tr> <td> - <code><a href="/en-US/docs/Web/HTML/Element/input#form">form</a></code> + <code><a href="/en-US/docs/Web/HTML/Reference/Elements/input#form">form</a></code> </td> <td></td> <td> @@ -391,14 +369,14 @@ Many of the elements used to define form controls have some of their own specifi </tr> <tr> <td> - <code><a href="/en-US/docs/Web/HTML/Element/input#name">name</a></code> + <code><a href="/en-US/docs/Web/HTML/Reference/Elements/input#name">name</a></code> </td> <td></td> <td>The name of the element; this is submitted with the form data.</td> </tr> <tr> <td> - <code><a href="/en-US/docs/Web/HTML/Element/input#value">value</a></code> + <code><a href="/en-US/docs/Web/HTML/Reference/Elements/input#value">value</a></code> </td> <td></td> <td>The element's initial value.</td> @@ -408,15 +386,10 @@ Many of the elements used to define form controls have some of their own specifi ## Test your skills! -You've reached the end of this article, but can you remember the most important information? You can find some further tests to verify that you've retained this information before you move on — see [Test your skills: Basic controls](/en-US/docs/Learn_web_development/Extensions/Forms/Test_your_skills:_Basic_controls). +You've reached the end of this article, but can you remember the most important information? You can find some further tests to verify that you've retained this information before you move on — see [Test your skills: Basic controls](/en-US/docs/Learn_web_development/Extensions/Forms/Test_your_skills/Basic_controls). ## Summary This article has covered the older input types — the original set introduced in the early days of HTML that is well-supported in all browsers. In the next section, we'll take a look at the more modern values of the `type` attribute. {{PreviousMenuNext("Learn_web_development/Extensions/Forms/How_to_structure_a_web_form", "Learn_web_development/Extensions/Forms/HTML5_input_types", "Learn_web_development/Extensions/Forms")}} - -### Advanced Topics - -- [How to build custom form controls](/en-US/docs/Learn_web_development/Extensions/Forms/How_to_build_custom_form_controls) -- [Sending forms through JavaScript](/en-US/docs/Learn_web_development/Extensions/Forms/Sending_forms_through_JavaScript) diff --git a/files/en-us/learn_web_development/extensions/forms/customizable_select/index.md b/files/en-us/learn_web_development/extensions/forms/customizable_select/index.md new file mode 100644 index 000000000000000..29ed59bc83ac86b --- /dev/null +++ b/files/en-us/learn_web_development/extensions/forms/customizable_select/index.md @@ -0,0 +1,412 @@ +--- +title: Customizable select elements +short-title: Customizable selects +slug: Learn_web_development/Extensions/Forms/Customizable_select +page-type: learn-module-chapter +sidebar: learnsidebar +--- + +{{PreviousMenuNext("Learn_web_development/Extensions/Forms/Advanced_form_styling", "Learn_web_development/Extensions/Forms/UI_pseudo-classes", "Learn_web_development/Extensions/Forms")}} + +This article explains how to use dedicated, modern HTML and CSS features together to create fully-customized {{htmlelement("select")}} elements. This includes having full control over styling the select button, drop-down picker, arrow icon, current selection checkmark, and each individual {{htmlelement("option")}} element. + +## Background + +Traditionally it has been difficult to customize the look and feel of `<select>` elements because they contain internals that are styled at the operating system level, which can't be targeted using CSS. This includes the drop-down picker, arrow icon, and so on. + +Previously, the best available option — aside from using a custom JavaScript library — was to set an {{cssxref("appearance")}} value of `none` on the `<select>` element to strip away some of the OS-level styling, and then use CSS to customize the bits that can be styled. This technique is explained in [Advanced form styling](/en-US/docs/Learn_web_development/Extensions/Forms/Advanced_form_styling). + +Customizable `<select>` elements provide a solution to these issues. They allow you to build examples like the following, using only HTML and CSS, which are fully customized in supporting browsers. This includes `<select>` and drop-down picker layout, color scheme, icons, font, transitions, positioning, markers to indicate the selected icon, and more. + +{{EmbedLiveSample("full-render", "100%", "410px")}} + +In addition, they provide a progressive enhancement on top of existing functionality, falling back to "classic" selects in non-supporting browsers. + +You'll find out how to build this example in the sections below. + +## What features comprise a customizable select? + +You can build customizable `<select>` elements using the following HTML and CSS features: + +- Plain old {{htmlelement("select")}}, {{htmlelement("option")}}, and {{htmlelement("optgroup")}} elements. These work just the same as in "classic" selects, except that they have additional permitted content types. +- A {{htmlelement("button")}} element included as the first child inside the `<select>` element, which wasn't previously allowed in "classic" selects. When this is included, it replaces the default "button" rendering of the closed `<select>` element. This is commonly known as the **select button** (as it is the button you need to press to open the drop-down picker). + > [!NOTE] + > The select button is [inert](/en-US/docs/Web/HTML/Reference/Global_attributes/inert) by default so that if interactive children (for example, links or buttons) are included inside it, it will still be treated like a single button for interaction purposes — for example, the child items won't be focusable or clickable. +- The {{htmlelement("selectedcontent")}} element can optionally be included inside the `<select>` element's first child `<button>` element in order to display the currently selected value inside the _closed_ `<select>` element. + This contains a clone of the currently-selected `<option>` element's content (created using {{domxref("Node.cloneNode", "cloneNode()")}} under the hood). +- The {{cssxref("::picker()", "::picker(select)")}} pseudo-element, which targets the entire contents of the picker. This includes all elements inside the `<select>` element, except the first child `<button>`. +- The {{cssxref("appearance")}} property value `base-select`, which opts the `<select>` element and the `::picker(select)` pseudo-element into the browser-defined default styles and behavior for customizable select. +- The {{cssxref(":open")}} pseudo-class, which targets the select button when the picker (`::picker(select)`) is open. +- The {{cssxref("::picker-icon")}} pseudo-element, which targets the icon inside the select button — the arrow that points down when the select is closed. +- The {{cssxref(":checked")}} pseudo-class, which targets the currently-selected `<option>` element. +- The {{cssxref("::checkmark")}} pseudo-element, which targets the checkmark placed inside the currently-selected `<option>` element to provide a visual indication of which one is selected. + +In addition, the `<select>` element and its drop-down picker have the following behavior assigned to them automatically: + +- They have an invoker/popover relationship, as specified by the [Popover API](/en-US/docs/Web/API/Popover_API), which provides the ability to select the picker when open via the {{cssxref(":popover-open")}} pseudo-class. See [Using the Popover API](/en-US/docs/Web/API/Popover_API/Using) for more details of popover behavior. +- They have an implicit anchor reference, meaning that the picker is automatically associated with the `<select>` element via [CSS anchor positioning](/en-US/docs/Web/CSS/CSS_anchor_positioning). The browser default styles position the picker relative to the button (the anchor) and you can customize this position as explained in [Positioning elements relative to their anchor](/en-US/docs/Web/CSS/CSS_anchor_positioning/Using#positioning_elements_relative_to_their_anchor). The browser default styles also define some position-try fallbacks that reposition the picker if it is in danger of overflowing the viewport. Position try fallback are explained in [Handling overflow: try fallbacks and conditional hiding](/en-US/docs/Web/CSS/CSS_anchor_positioning/Try_options_hiding). + +> [!NOTE] +> You can check browser support for customizable `<select>` by viewing the browser compatibility tables on the reference pages for related features such as {{htmlelement("selectedcontent")}}, {{cssxref("::picker()", "::picker(select)")}}, and {{cssxref("::checkmark")}}. + +Let's look at all of the above features in action, by walking through the example shown at the top of the page. + +## Customizable select markup + +Our example is a typical {{htmlelement("select")}} menu that allows you to choose a pet. The markup is as follows: + +```html live-sample___plain-render live-sample___second-render live-sample___third-render live-sample___fourth-render live-sample___full-render +<form> + <p> + <label for="pet-select">Select pet:</label> + <select id="pet-select"> + <button> + <selectedcontent></selectedcontent> + </button> + + <option value="">Please select a pet</option> + <option value="cat"> + <span class="icon" aria-hidden="true">🐱</span + ><span class="option-label">Cat</span> + </option> + <option value="dog"> + <span class="icon" aria-hidden="true">🐶</span + ><span class="option-label">Dog</span> + </option> + <option value="hamster"> + <span class="icon" aria-hidden="true">🐹</span + ><span class="option-label">Hamster</span> + </option> + <option value="chicken"> + <span class="icon" aria-hidden="true">🐔</span + ><span class="option-label">Chicken</span> + </option> + <option value="fish"> + <span class="icon" aria-hidden="true">🐟</span + ><span class="option-label">Fish</span> + </option> + <option value="snake"> + <span class="icon" aria-hidden="true">🐍</span + ><span class="option-label">Snake</span> + </option> + </select> + </p> +</form> +``` + +> [!NOTE] +> The [`aria-hidden="true"`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-hidden) attribute is included on the icons so that they will be hidden from assistive technologies, avoiding the option values being announced twice (for example, "cat cat"). + +The example markup is nearly the same as "classic" `<select>` markup, with the following differences: + +- The `<button><selectedcontent></selectedcontent></button>` structure represents the select {{htmlelement("button")}}. + Adding the {{htmlelement("selectedcontent")}} element causes the browser to clone the currently-selected {{htmlelement("option")}} inside the button, which you can then [provide custom styles for](#adjusting_the_styling_of_the_selected_option_contents_inside_the_select_button). If this structure is not included in your markup, the browser will fall back to rendering the selected option's text inside the default button, and you won't be able to style it as easily. + > [!NOTE] + > You _can_ include arbitrary content inside the `<button>` to render whatever you want inside the closed `<select>`, but be careful when doing this. What you include can alter the accessible value exposed to assistive technology for the `<select>` element. +- The rest of the `<select>` contents represents the drop-down picker, which is usually limited to the `<option>` elements representing the different choices in the picker. You can include other content in the picker, but it is not recommended. +- Traditionally, `<option>` elements could only contain text, but in a customizable select you can include other markup structures like images, other non-interactive text-level semantic elements, and more. You can even use the {{cssxref("::before")}} and {{cssxref("::after")}} pseudo-elements to include other content, although bear in mind that this wouldn't be included in the submittable value. In our example, each `<option>` contains two {{htmlelement("span")}} elements containing an icon and a text label respectively, allowing each one to be styled and positioned independently. + + > [!NOTE] + > Because the `<option>` content can contain multi-level DOM sub-trees, not just text nodes, there are rules concerning how the browser should extract the [current `<select>` value](/en-US/docs/Web/API/HTMLSelectElement/value) via JavaScript. The selected `<option>` element's {{domxref("Node.textContent", "textContent")}} property value is retrieved, {{jsxref("String.prototype.trim", "trim()")}} is run on it, and the result is set as the `<select>` value. + +This design allows non-supporting browsers to fall back to a classic `<select>` experience. The `<button><selectedcontent></selectedcontent></button>` structure will be ignored completely, and the non-text `<option>` contents will be stripped out to just leave the text node contents, but the result will still function. + +## Opting in to the custom select rendering + +To opt-in to the custom select functionality and minimal browser base styles (and remove the OS-provided styling), your `<select>` element and its drop-down picker (represented by the `::picker(select)` pseudo-element) both need to have an {{cssxref("appearance")}} value of `base-select` set on them: + +```css live-sample___plain-render live-sample___second-render live-sample___third-render live-sample___fourth-render live-sample___full-render +select, +::picker(select) { + appearance: base-select; +} +``` + +```css hidden live-sample___plain-render live-sample___second-render live-sample___third-render live-sample___fourth-render live-sample___full-render +* { + box-sizing: border-box; +} + +html { + font-family: Arial, Helvetica, sans-serif; +} + +body { + width: 100%; + padding: 0 10px; + max-width: 480px; + margin: 0 auto; +} + +h2 { + font-size: 1.2rem; +} + +p { + display: flex; + gap: 10px; +} + +label { + width: fit-content; + align-self: center; +} + +select { + flex: 1; +} +``` + +You can choose to opt-in just the `<select>` element to the new functionality, leaving the picker with the default OS styling, but in most cases, you'll want to opt-in both. You can't opt-in the picker without opting in the `<select>` element. + +Once this is done, the result is a very plain rendering of a `<select>` element: + +{{EmbedLiveSample("plain-render", "100%", "240px")}} + +You are now free to style this in any way you want. To begin with, the `<select>` element has custom {{cssxref("border")}}, {{cssxref("background")}} (which changes on {{cssxref(":hover")}} or {{cssxref(":focus")}}), and {{cssxref("padding")}} values set, plus a {{cssxref("transition")}} so that the background change animates smoothly: + +```css live-sample___second-render live-sample___third-render live-sample___fourth-render live-sample___full-render +select { + border: 2px solid #ddd; + background: #eee; + padding: 10px; + transition: 0.4s; +} + +select:hover, +select:focus { + background: #ddd; +} +``` + +## Styling the picker icon + +To style the icon inside the select button — the arrow that points down when the select is closed — you can target it with the {{cssxref("::picker-icon")}} pseudo-element. The following code gives the icon a custom {{cssxref("color")}} and a `transition` so that changes to its {{cssxref("rotate")}} property are smoothly animated: + +```css live-sample___second-render live-sample___third-render live-sample___fourth-render live-sample___full-render +select::picker-icon { + color: #999; + transition: 0.4s rotate; +} +``` + +Next up, `::picker-icon` is combined with the {{cssxref(":open")}} pseudo-class — which targets the select button only when the drop-down picker is open — to give the icon a `rotate` value of `180deg` when the `<select>` is opened. + +```css live-sample___second-render live-sample___third-render live-sample___fourth-render live-sample___full-render +select:open::picker-icon { + rotate: 180deg; +} +``` + +Let's have a look at the work so far — note how the picker arrow rotates smoothly through 180 degrees when the `<select>` opens and closes: + +{{EmbedLiveSample("second-render", "100%", "250px")}} + +## Styling the drop-down picker + +The drop-down picker can be targeted using the {{cssxref("::picker()", "::picker(select)")}} pseudo-element. As mentioned earlier, the picker contains everything inside the `<select>` element that isn't the button and the `<selectedcontent>`. In our example, this means all the `<option>` elements and their contents. + +First of all, the picker's default black {{cssxref("border")}} is removed: + +```css live-sample___third-render live-sample___fourth-render live-sample___full-render +::picker(select) { + border: none; +} +``` + +Now the `<option>` elements are styled. They are laid out with [flexbox](/en-US/docs/Web/CSS/CSS_flexible_box_layout), aligning them all to the start of the flex container and including a `20px` {{cssxref("gap")}} between each one. Each `<option>` is also given the same {{cssxref("border")}}, {{cssxref("background")}}, {{cssxref("padding")}}, and {{cssxref("transition")}} as the `<select>`, to provide a consistent look and feel: + +```css live-sample___third-render live-sample___fourth-render live-sample___full-render +option { + display: flex; + justify-content: flex-start; + gap: 20px; + + border: 2px solid #ddd; + background: #eee; + padding: 10px; + transition: 0.4s; +} +``` + +> [!NOTE] +> Customizable `<select>` element `<option>`s have `display: flex` set on them by default, but it is included in our stylesheet anyway to clarify what is going on. + +Next, a combination of the {{cssxref(":first-of-type")}}, {{cssxref(":last-of-type")}}, and {{cssxref(":not()")}} pseudo-classes is used to set an appropriate {{cssxref("border-radius")}} on the top and bottom corners of the picker, and remove the {{cssxref("border-bottom")}} from all `<option>` elements except the last one so the borders don't look messy and doubled-up: + +```css live-sample___third-render live-sample___fourth-render live-sample___full-render +option:first-of-type { + border-radius: 8px 8px 0 0; +} + +option:last-of-type { + border-radius: 0 0 8px 8px; +} + +option:not(option:last-of-type) { + border-bottom: none; +} +``` + +Next a different `background` color is set on the odd-numbered `<option>` elements using {{cssxref(":nth-of-type()", ":nth-of-type(odd)")}} to implement zebra-striping, and a different `background` color is set on the `<option>` elements on focus and hover, to provide a useful visual highlight during selection: + +```css live-sample___third-render live-sample___fourth-render live-sample___full-render +option:nth-of-type(odd) { + background: #fff; +} + +option:hover, +option:focus { + background: plum; +} +``` + +Finally for this section, a larger {{cssxref("font-size")}} is set on the `<option>` icons (contained within `<span>` elements with a class of `icon`) to make them bigger, and the {{cssxref("text-box")}} property is used to remove some of the annoying spacing at the block-start and block-end edges of the icon emojis, making them align better with the text labels: + +```css live-sample___third-render live-sample___fourth-render live-sample___full-render +option .icon { + font-size: 1.6rem; + text-box: trim-both cap alphabetic; +} +``` + +Our example now renders like this: + +{{EmbedLiveSample("third-render", "100%", "370px")}} + +## Adjusting the styling of the selected option contents inside the select button + +If you select any pet option from the last few live examples, you'll notice a problem — the pet icons cause the select button to increase in height, which also changes the position of the picker icon, and there is no spacing between the option icon and label. + +This can be fixed by hiding the icon when it is contained inside `<selectedcontent>`, which represents the contents of the selected `<option>` as they appear inside the select button. In our example, it is hidden using {{cssxref("display", "display: none")}}: + +```css live-sample___fourth-render live-sample___full-render +selectedcontent .icon { + display: none; +} +``` + +This does not affect the styling of the `<option>` contents as they appear inside the drop-down picker. + +## Styling the currently selected option + +To style the currently selected `<option>` as it appears inside the drop-down picker, you can target it using the {{cssxref(":checked")}} pseudo-class. This is used to set the selected `<option>` element's {{cssxref("font-weight")}} to `bold`: + +```css live-sample___fourth-render live-sample___full-render +option:checked { + font-weight: bold; +} +``` + +## Styling the current selection checkmark + +You've probably noticed that when you open the picker to make a selection, the currently selected `<option>` has a checkmark at its inline-start end. This checkmark can be targeted using the {{cssxref("::checkmark")}} pseudo-element. For example, you might want to hide this checkmark (for example, via `display: none`). + +You could also choose to do something a bit more interesting with it — earlier on the `<option>` elements were laid out horizontally using flexbox, with the flex items being aligned to the start of the row. In the below rule, the checkmark is moved from the start of the row to the end by setting an {{cssxref("order")}} value on it greater than `0`, and aligning it to the end of the row using an `auto` {{cssxref("margin-left")}} value (see [Alignment and auto margins](/en-US/docs/Web/CSS/CSS_box_alignment/Box_alignment_in_flexbox#alignment_and_auto_margins)). + +Finally, the value of the {{cssxref("content")}} property is set to a different emoji, to set a different icon to display. + +```css live-sample___fourth-render live-sample___full-render +option::checkmark { + order: 1; + margin-left: auto; + content: "☑️"; +} +``` + +> [!NOTE] +> The `::checkmark` and `::picker-icon` pseudo-elements are not included in the accessibility tree, so any generated {{cssxref("content")}} set on them will not be announced by assistive technologies. You should still make sure that any new icon you set visually makes sense for its intended purpose. + +Let's check in again on how the example is rendering. The updated state after the last three sections is as follows: + +{{EmbedLiveSample("fourth-render", "100%", "410px")}} + +## Animating the picker using popover states + +The customizable `<select>` element's select `button` and drop-down picker are automatically given an invoker/popover relationship, as described in [Using the Popover API](/en-US/docs/Web/API/Popover_API/Using). There are many advantages that this brings to `<select>` elements; our example takes advantage of the ability to animate between popover hidden and showing states using transitions. The {{cssxref(":popover-open")}} pseudo-class represents popovers in the showing state. + +The technique is covered quickly in this section — read [Animating popovers](/en-US/docs/Web/API/Popover_API/Using#animating_popovers) for a more detailed description. + +First of all, the picker is selected using `::picker(select)`, and given an {{cssxref("opacity")}} value of `0` and a `transition` value of `all 0.4s allow-discrete`. This causes all properties that change value when the popover state changes from hidden to showing to animate. + +```css live-sample___full-render +::picker(select) { + opacity: 0; + transition: all 0.4s allow-discrete; +} +``` + +The list of transitioned properties features `opacity`, however it also includes two discrete properties whose values are set by the browser default styles: + +- {{cssxref("display")}} + - : The `display` values changes from `none` to `block` when the popover changes state from hidden to shown. This needs to be animated to ensure that other transitions are visible. +- {{cssxref("overlay")}} + - : The `overlay` value changes from `none` to `auto` when the popover changes state from hidden to shown, to promote it to the {{glossary("top layer")}}, then back again when it is hidden to remove it. This needs to be animated to ensure the removal of the popover from the top layer is deferred until the transition completes, ensuring the transition is visible. + +> [!NOTE] +> The [`allow-discrete`](/en-US/docs/Web/CSS/transition-behavior#allow-discrete) value is needed to enable discrete property animations. + +Next, the picker is selected in the showing state using `::picker(select):popover-open` and given an `opacity` value to `1` — this is the end state of the transition: + +```css live-sample___full-render +::picker(select):popover-open { + opacity: 1; +} +``` + +Finally, because the picker is being transitioned while it is moving from `display: none` to a `display` value that makes it visible, the transition's starting state has to be specified inside a {{cssxref("@starting-style")}} block: + +```css live-sample___full-render +@starting-style { + ::picker(select):popover-open { + opacity: 0; + } +} +``` + +These rules work together to make the picker smoothly fade in and fade out when the `<select>` is opened and closed. + +## Positioning the picker using anchor positioning + +A customizable `<select>` element's select button and drop-down picker have an implicit anchor reference, and the picker is automatically associated with the select button via [CSS anchor positioning](/en-US/docs/Web/CSS/CSS_anchor_positioning). This means that an explicit association does not need to be made using the {{cssxref("anchor-name")}} and {{cssxref("position-anchor")}} properties. + +In addition, the [browser's default styles provide a default position](/en-US/docs/Web/CSS/::picker#picker_anchor_positioning), which you can customize as explained in [Positioning elements relative to their anchor](/en-US/docs/Web/CSS/CSS_anchor_positioning/Using#positioning_elements_relative_to_their_anchor). + +In our demo, the position of the picker is set relative to its anchor by using the {{cssxref("anchor()")}} function inside its {{cssxref("top")}} and {{cssxref("left")}} property values: + +```css live-sample___full-render +::picker(select) { + top: calc(anchor(bottom) + 1px); + left: anchor(10%); +} +``` + +This results in the top edge of the picker always being positioned 1 pixel down from the bottom edge of the select button, and the left edge of the picker always being positioned `10%` of the select button's width across from its left edge. + +## Final result + +After the last two sections, the final updated state of our `<select>` is rendered like this: + +{{EmbedLiveSample("full-render", "100%", "410px")}} + +## Customizing other classic select features + +The above sections have covered all the new functionality available in customizable selects, and shown how it interacts with both classic single-line selects, and related modern features such as popovers and anchor positioning. There are some other `<select>` element features not mentioned above; this section talks about how they currently work alongside customizable selects: + +- [`<select multiple>`](/en-US/docs/Web/HTML/Reference/Attributes/multiple) + - : There isn't currently any support specified for the `multiple` attribute on customizable `<select>` elements, but this will be worked on in the future. +- {{htmlelement("optgroup")}} + - : The default styling of `<optgroup>` elements is the same as in classic `<select>` elements — bolded and indented less than the contained options. You need to make sure to style the `<optgroup>` elements so they fit into the overall design, and bear in mind that they will behave just as containers are expected to behave in conventional HTML. In customizable `<select>` elements, the {{htmlelement("legend")}} element is allowed as a child of `<optgroup>`, to provide a label that is easy to target and style. This replaces any text set in the `<optgroup>` element's `label` attribute, and it has the same semantics. + +## Next up + +In the next article of this module, we will explore the different [UI pseudo-classes](/en-US/docs/Learn_web_development/Extensions/Forms/UI_pseudo-classes) available to us in modern browsers for styling forms in different states. + +## See also + +- {{htmlelement("select")}}, {{htmlelement("option")}}, {{htmlelement("optgroup")}}, {{htmlelement("label")}}, {{htmlelement("button")}}, {{htmlelement("selectedcontent")}} +- {{cssxref("appearance")}} +- {{cssxref("::picker()", "::picker(select)")}}, {{cssxref("::picker-icon")}}, {{cssxref("::checkmark")}} +- {{cssxref(":open")}}, {{cssxref(":checked")}} + +{{PreviousMenuNext("Learn_web_development/Extensions/Forms/Advanced_form_styling", "Learn_web_development/Extensions/Forms/UI_pseudo-classes", "Learn_web_development/Extensions/Forms")}} diff --git a/files/en-us/learn_web_development/extensions/forms/form_validation/index.md b/files/en-us/learn_web_development/extensions/forms/form_validation/index.md index 980e67017fc1fd5..af954b1f648b145 100644 --- a/files/en-us/learn_web_development/extensions/forms/form_validation/index.md +++ b/files/en-us/learn_web_development/extensions/forms/form_validation/index.md @@ -2,9 +2,10 @@ title: Client-side form validation slug: Learn_web_development/Extensions/Forms/Form_validation page-type: learn-module-chapter +sidebar: learnsidebar --- -{{LearnSidebar}}{{PreviousMenuNext("Learn_web_development/Extensions/Forms/UI_pseudo-classes", "Learn_web_development/Extensions/Forms/Sending_and_retrieving_form_data", "Learn_web_development/Extensions/Forms")}} +{{PreviousMenuNext("Learn_web_development/Extensions/Forms/UI_pseudo-classes", "Learn_web_development/Extensions/Forms/Sending_and_retrieving_form_data", "Learn_web_development/Extensions/Forms")}} It is important to ensure all required form controls are filled out, in the correct format, before submitting user entered form data to the server. This **client-side form validation** helps ensure data entered matches the requirements set forth in the various form controls. @@ -82,11 +83,11 @@ One of the most significant features of [form controls](/en-US/docs/Learn_web_de This is done by using validation attributes on form elements. We've seen many of these earlier in the course, but to recap: -- [`required`](/en-US/docs/Web/HTML/Attributes/required): Specifies whether a form field needs to be filled in before the form can be submitted. -- [`minlength`](/en-US/docs/Web/HTML/Attributes/minlength) and [`maxlength`](/en-US/docs/Web/HTML/Attributes/maxlength): Specifies the minimum and maximum length of textual data (strings). -- [`min`](/en-US/docs/Web/HTML/Attributes/min), [`max`](/en-US/docs/Web/HTML/Attributes/max), and [`step`](/en-US/docs/Web/HTML/Attributes/step): Specifies the minimum and maximum values of numerical input types, and the increment, or step, for values, starting from the minimum. -- [`type`](/en-US/docs/Web/HTML/Element/input#input_types): Specifies whether the data needs to be a number, an email address, or some other specific preset type. -- [`pattern`](/en-US/docs/Web/HTML/Attributes/pattern): Specifies a [regular expression](/en-US/docs/Web/JavaScript/Guide/Regular_expressions) that defines a pattern the entered data needs to follow. +- [`required`](/en-US/docs/Web/HTML/Reference/Attributes/required): Specifies whether a form field needs to be filled in before the form can be submitted. +- [`minlength`](/en-US/docs/Web/HTML/Reference/Attributes/minlength) and [`maxlength`](/en-US/docs/Web/HTML/Reference/Attributes/maxlength): Specifies the minimum and maximum length of textual data (strings). +- [`min`](/en-US/docs/Web/HTML/Reference/Attributes/min), [`max`](/en-US/docs/Web/HTML/Reference/Attributes/max), and [`step`](/en-US/docs/Web/HTML/Reference/Attributes/step): Specifies the minimum and maximum values of numerical input types, and the increment, or step, for values, starting from the minimum. +- [`type`](/en-US/docs/Web/HTML/Reference/Elements/input#input_types): Specifies whether the data needs to be a number, an email address, or some other specific preset type. +- [`pattern`](/en-US/docs/Web/HTML/Reference/Attributes/pattern): Specifies a [regular expression](/en-US/docs/Web/JavaScript/Guide/Regular_expressions) that defines a pattern the entered data needs to follow. If the data entered in a form field follows all of the rules specified by the attributes applied to the field, it is considered valid. If not, it is considered invalid. @@ -133,7 +134,7 @@ To begin, make a copy of the [`fruit-start.html` file found on GitHub](https://g ### The required attribute -A common HTML validation feature is the [`required`](/en-US/docs/Web/HTML/Attributes/required) attribute. +A common HTML validation feature is the [`required`](/en-US/docs/Web/HTML/Reference/Attributes/required) attribute. Add this attribute to an input to make an element mandatory. When this attribute is set, the element matches the {{cssxref(':required')}} UI pseudo-class and the form won't submit, displaying an error message on submission, if the input is empty. While empty, the input will also be considered invalid, matching the {{cssxref(':invalid')}} UI pseudo-class. @@ -180,7 +181,7 @@ Try submitting the form from the [live `required` example](https://mdn.github.io ### Validating against a regular expression -Another useful validation feature is the [`pattern`](/en-US/docs/Web/HTML/Attributes/pattern) attribute, which expects a [Regular Expression](/en-US/docs/Web/JavaScript/Guide/Regular_expressions) as its value. +Another useful validation feature is the [`pattern`](/en-US/docs/Web/HTML/Reference/Attributes/pattern) attribute, which expects a [Regular Expression](/en-US/docs/Web/JavaScript/Guide/Regular_expressions) as its value. A regular expression (regexp) is a pattern that can be used to match character combinations in text strings, so regexps are ideal for form validation and serve a variety of other uses in JavaScript. Regexps are quite complex, and we don't intend to teach you them exhaustively in this article. @@ -197,7 +198,7 @@ There are many more possibilities that we don't cover here. For a complete list and many examples, consult our [Regular expression](/en-US/docs/Web/JavaScript/Guide/Regular_expressions) documentation. Let's implement an example. -Update your HTML to add a [`pattern`](/en-US/docs/Web/HTML/Attributes/pattern) attribute like this: +Update your HTML to add a [`pattern`](/en-US/docs/Web/HTML/Reference/Attributes/pattern) attribute like this: ```html <form> @@ -225,21 +226,21 @@ You can find this [example live on GitHub](https://mdn.github.io/learning-area/h In this example, the {{HTMLElement("input")}} element accepts one of four possible values: the strings "banana", "Banana", "cherry", or "Cherry". Regular expressions are case-sensitive, but we've made it support capitalized as well as lower-case versions using an extra "Aa" pattern nested inside square brackets. -At this point, try changing the value inside the [`pattern`](/en-US/docs/Web/HTML/Attributes/pattern) attribute to equal some of the examples you saw earlier, and look at how that affects the values you can enter to make the input value valid. +At this point, try changing the value inside the [`pattern`](/en-US/docs/Web/HTML/Reference/Attributes/pattern) attribute to equal some of the examples you saw earlier, and look at how that affects the values you can enter to make the input value valid. Try writing some of your own, and see how it goes. Make them fruit-related where possible so that your examples make sense! If a non-empty value of the {{HTMLElement("input")}} doesn't match the regular expression's pattern, the `input` will match the {{cssxref(':invalid')}} pseudo-class. If empty, and the element is not required, it is not considered invalid. -Some {{HTMLElement("input")}} element types don't need a [`pattern`](/en-US/docs/Web/HTML/Attributes/pattern) attribute to be validated against a regular expression. For example, specifying the `email` type validates the inputs value against a well-formed email address pattern or a pattern matching a comma-separated list of email addresses if it has the [`multiple`](/en-US/docs/Web/HTML/Attributes/multiple) attribute. +Some {{HTMLElement("input")}} element types don't need a [`pattern`](/en-US/docs/Web/HTML/Reference/Attributes/pattern) attribute to be validated against a regular expression. For example, specifying the `email` type validates the inputs value against a well-formed email address pattern or a pattern matching a comma-separated list of email addresses if it has the [`multiple`](/en-US/docs/Web/HTML/Reference/Attributes/multiple) attribute. > [!NOTE] -> The {{HTMLElement("textarea")}} element doesn't support the [`pattern`](/en-US/docs/Web/HTML/Attributes/pattern) attribute. +> The {{HTMLElement("textarea")}} element doesn't support the [`pattern`](/en-US/docs/Web/HTML/Reference/Attributes/pattern) attribute. ### Constraining the length of your entries -You can constrain the character length of all text fields created by {{HTMLElement("input")}} or {{HTMLElement("textarea")}} by using the [`minlength`](/en-US/docs/Web/HTML/Attributes/minlength) and [`maxlength`](/en-US/docs/Web/HTML/Attributes/maxlength) attributes. -A field is invalid if it has a value and that value has fewer characters than the [`minlength`](/en-US/docs/Web/HTML/Attributes/minlength) value or more than the [`maxlength`](/en-US/docs/Web/HTML/Attributes/maxlength) value. +You can constrain the character length of all text fields created by {{HTMLElement("input")}} or {{HTMLElement("textarea")}} by using the [`minlength`](/en-US/docs/Web/HTML/Reference/Attributes/minlength) and [`maxlength`](/en-US/docs/Web/HTML/Reference/Attributes/maxlength) attributes. +A field is invalid if it has a value and that value has fewer characters than the [`minlength`](/en-US/docs/Web/HTML/Reference/Attributes/minlength) value or more than the [`maxlength`](/en-US/docs/Web/HTML/Reference/Attributes/maxlength) value. Browsers often don't let the user type a longer value than expected into text fields. A better user experience than just using `maxlength` is to also provide character count feedback in an accessible manner and let the user edit their content down to size. An example of this is the character limit when posting on social media. JavaScript, including [solutions using `maxlength`](https://github.com/mimo84/bootstrap-maxlength), can be used to provide this. @@ -249,7 +250,7 @@ An example of this is the character limit when posting on social media. JavaScri ### Constraining the values of your entries -For numeric fields, including [`<input type="number">`](/en-US/docs/Web/HTML/Element/input/number) and the various date input types, the [`min`](/en-US/docs/Web/HTML/Attributes/min) and [`max`](/en-US/docs/Web/HTML/Attributes/max) attributes can be used to provide a range of valid values. +For numeric fields, including [`<input type="number">`](/en-US/docs/Web/HTML/Reference/Elements/input/number) and the various date input types, the [`min`](/en-US/docs/Web/HTML/Reference/Attributes/min) and [`max`](/en-US/docs/Web/HTML/Reference/Attributes/max) attributes can be used to provide a range of valid values. If the field contains a value outside this range, it will be invalid. Let's look at another example. @@ -305,7 +306,7 @@ Here is the example running live: Try this [example live on GitHub](https://mdn.github.io/learning-area/html/forms/form-validation/fruit-length.html) and view the [source code](https://github.com/mdn/learning-area/blob/main/html/forms/form-validation/fruit-length.html). -Numeric input types, like `number`, `range` and `date`, can also take the [`step`](/en-US/docs/Web/HTML/Attributes/step) attribute. This attribute specifies what increment the value will go up or down by when the input controls are used (such as the up and down number buttons, or sliding the ranges thumb). The `step` attribute is omitted in our example, so the value defaults to `1`. This means that floats, like 3.2, will also show as invalid. +Numeric input types, like `number`, `range` and `date`, can also take the [`step`](/en-US/docs/Web/HTML/Reference/Attributes/step) attribute. This attribute specifies what increment the value will go up or down by when the input controls are used (such as the up and down number buttons, or sliding the ranges thumb). The `step` attribute is omitted in our example, so the value defaults to `1`. This means that floats, like 3.2, will also show as invalid. ### Full example @@ -402,7 +403,7 @@ This renders as follows: This [full example is live on GitHub](https://mdn.github.io/learning-area/html/forms/form-validation/full-example.html) along with the [source code](https://github.com/mdn/learning-area/blob/main/html/forms/form-validation/full-example.html). -See [Validation-related attributes](/en-US/docs/Web/HTML/Constraint_validation#validation-related_attributes) for a complete list of attributes that can be used to constrain input values and the input types that support them. +See [Validation-related attributes](/en-US/docs/Web/HTML/Guides/Constraint_validation#validation-related_attributes) for a complete list of attributes that can be used to constrain input values and the input types that support them. ## Validating forms using JavaScript @@ -413,30 +414,30 @@ In this section we will look at the different ways to do this. The Constraint Validation API consists of a set of methods and properties available on the following form element DOM interfaces: -- [`HTMLButtonElement`](/en-US/docs/Web/API/HTMLButtonElement) (represents a [`<button>`](/en-US/docs/Web/HTML/Element/button) element) -- [`HTMLFieldSetElement`](/en-US/docs/Web/API/HTMLFieldSetElement) (represents a [`<fieldset>`](/en-US/docs/Web/HTML/Element/fieldset) element) -- [`HTMLInputElement`](/en-US/docs/Web/API/HTMLInputElement) (represents an [`<input>`](/en-US/docs/Web/HTML/Element/input) element) -- [`HTMLOutputElement`](/en-US/docs/Web/API/HTMLOutputElement) (represents an [`<output>`](/en-US/docs/Web/HTML/Element/output) element) -- [`HTMLSelectElement`](/en-US/docs/Web/API/HTMLSelectElement) (represents a [`<select>`](/en-US/docs/Web/HTML/Element/select) element) -- [`HTMLTextAreaElement`](/en-US/docs/Web/API/HTMLTextAreaElement) (represents a [`<textarea>`](/en-US/docs/Web/HTML/Element/textarea) element) +- [`HTMLButtonElement`](/en-US/docs/Web/API/HTMLButtonElement) (represents a [`<button>`](/en-US/docs/Web/HTML/Reference/Elements/button) element) +- [`HTMLFieldSetElement`](/en-US/docs/Web/API/HTMLFieldSetElement) (represents a [`<fieldset>`](/en-US/docs/Web/HTML/Reference/Elements/fieldset) element) +- [`HTMLInputElement`](/en-US/docs/Web/API/HTMLInputElement) (represents an [`<input>`](/en-US/docs/Web/HTML/Reference/Elements/input) element) +- [`HTMLOutputElement`](/en-US/docs/Web/API/HTMLOutputElement) (represents an [`<output>`](/en-US/docs/Web/HTML/Reference/Elements/output) element) +- [`HTMLSelectElement`](/en-US/docs/Web/API/HTMLSelectElement) (represents a [`<select>`](/en-US/docs/Web/HTML/Reference/Elements/select) element) +- [`HTMLTextAreaElement`](/en-US/docs/Web/API/HTMLTextAreaElement) (represents a [`<textarea>`](/en-US/docs/Web/HTML/Reference/Elements/textarea) element) The Constraint Validation API makes the following properties available on the above elements. - `validationMessage`: Returns a localized message describing the validation constraints that the control doesn't satisfy (if any). If the control is not a candidate for constraint validation (`willValidate` is `false`) or the element's value satisfies its constraints (is valid), this will return an empty string. - `validity`: Returns a `ValidityState` object that contains several properties describing the validity state of the element. You can find full details of all the available properties in the {{domxref("ValidityState")}} reference page; below is listed a few of the more common ones: - - {{domxref("ValidityState.patternMismatch", "patternMismatch")}}: Returns `true` if the value does not match the specified [`pattern`](/en-US/docs/Web/HTML/Element/input#pattern), and `false` if it does match. If true, the element matches the {{cssxref(":invalid")}} CSS pseudo-class. - - {{domxref("ValidityState.tooLong", "tooLong")}}: Returns `true` if the value is longer than the maximum length specified by the [`maxlength`](/en-US/docs/Web/HTML/Element/input#maxlength) attribute, or `false` if it is shorter than or equal to the maximum. If true, the element matches the {{cssxref(":invalid")}} CSS pseudo-class. - - {{domxref("ValidityState.tooShort", "tooShort")}}: Returns `true` if the value is shorter than the minimum length specified by the [`minlength`](/en-US/docs/Web/HTML/Element/input#minlength) attribute, or `false` if it is greater than or equal to the minimum. If true, the element matches the {{cssxref(":invalid")}} CSS pseudo-class. - - {{domxref("ValidityState.rangeOverflow", "rangeOverflow")}}: Returns `true` if the value is greater than the maximum specified by the [`max`](/en-US/docs/Web/HTML/Element/input#max) attribute, or `false` if it is less than or equal to the maximum. If true, the element matches the {{cssxref(":invalid")}} and {{cssxref(":out-of-range")}} CSS pseudo-classes. - - {{domxref("ValidityState.rangeUnderflow", "rangeUnderflow")}}: Returns `true` if the value is less than the minimum specified by the [`min`](/en-US/docs/Web/HTML/Element/input#min) attribute, or `false` if it is greater than or equal to the minimum. If true, the element matches the {{cssxref(":invalid")}} and {{cssxref(":out-of-range")}} CSS pseudo-classes. - - {{domxref("ValidityState.typeMismatch", "typeMismatch")}}: Returns `true` if the value is not in the required syntax (when [`type`](/en-US/docs/Web/HTML/Element/input#type) is `email` or `url`), or `false` if the syntax is correct. If `true`, the element matches the {{cssxref(":invalid")}} CSS pseudo-class. + - {{domxref("ValidityState.patternMismatch", "patternMismatch")}}: Returns `true` if the value does not match the specified [`pattern`](/en-US/docs/Web/HTML/Reference/Elements/input#pattern), and `false` if it does match. If true, the element matches the {{cssxref(":invalid")}} CSS pseudo-class. + - {{domxref("ValidityState.tooLong", "tooLong")}}: Returns `true` if the value is longer than the maximum length specified by the [`maxlength`](/en-US/docs/Web/HTML/Reference/Elements/input#maxlength) attribute, or `false` if it is shorter than or equal to the maximum. If true, the element matches the {{cssxref(":invalid")}} CSS pseudo-class. + - {{domxref("ValidityState.tooShort", "tooShort")}}: Returns `true` if the value is shorter than the minimum length specified by the [`minlength`](/en-US/docs/Web/HTML/Reference/Elements/input#minlength) attribute, or `false` if it is greater than or equal to the minimum. If true, the element matches the {{cssxref(":invalid")}} CSS pseudo-class. + - {{domxref("ValidityState.rangeOverflow", "rangeOverflow")}}: Returns `true` if the value is greater than the maximum specified by the [`max`](/en-US/docs/Web/HTML/Reference/Elements/input#max) attribute, or `false` if it is less than or equal to the maximum. If true, the element matches the {{cssxref(":invalid")}} and {{cssxref(":out-of-range")}} CSS pseudo-classes. + - {{domxref("ValidityState.rangeUnderflow", "rangeUnderflow")}}: Returns `true` if the value is less than the minimum specified by the [`min`](/en-US/docs/Web/HTML/Reference/Elements/input#min) attribute, or `false` if it is greater than or equal to the minimum. If true, the element matches the {{cssxref(":invalid")}} and {{cssxref(":out-of-range")}} CSS pseudo-classes. + - {{domxref("ValidityState.typeMismatch", "typeMismatch")}}: Returns `true` if the value is not in the required syntax (when [`type`](/en-US/docs/Web/HTML/Reference/Elements/input#type) is `email` or `url`), or `false` if the syntax is correct. If `true`, the element matches the {{cssxref(":invalid")}} CSS pseudo-class. - `valid`: Returns `true` if the element meets all its validation constraints, and is therefore considered to be valid, or `false` if it fails any constraint. If true, the element matches the {{cssxref(":valid")}} CSS pseudo-class; the {{cssxref(":invalid")}} CSS pseudo-class otherwise. - - `valueMissing`: Returns `true` if the element has a [`required`](/en-US/docs/Web/HTML/Element/input#required) attribute, but no value, or `false` otherwise. If true, the element matches the {{cssxref(":invalid")}} CSS pseudo-class. + - `valueMissing`: Returns `true` if the element has a [`required`](/en-US/docs/Web/HTML/Reference/Elements/input#required) attribute, but no value, or `false` otherwise. If true, the element matches the {{cssxref(":invalid")}} CSS pseudo-class. - `willValidate`: Returns `true` if the element will be validated when the form is submitted; `false` otherwise. -The Constraint Validation API also makes the following methods available on the above elements and the [`form`](/en-US/docs/Web/HTML/Element/form) element. +The Constraint Validation API also makes the following methods available on the above elements and the [`form`](/en-US/docs/Web/HTML/Reference/Elements/form) element. - `checkValidity()`: Returns `true` if the element's value has no validity problems; `false` otherwise. If the element is invalid, this method also fires an [`invalid` event](/en-US/docs/Web/API/HTMLInputElement/invalid_event) on the element. - `reportValidity()`: Reports invalid field(s) using events. This method is useful in combination with `preventDefault()` in an `onSubmit` event handler. @@ -499,7 +500,7 @@ You can find this example live on GitHub as [custom-error-message.html](https:// The previous example showed how you can add a customized message for a particular type of error (`validity.typeMismatch`). It is also possible to use all of the built in form validation, and then add to it using `setCustomValidity()`. -Here we demonstrate how you can extend the built in [`<input type="email">`](/en-US/docs/Web/HTML/Element/input/email) validation to only accept addresses with the `@example.com` domain. +Here we demonstrate how you can extend the built in [`<input type="email">`](/en-US/docs/Web/HTML/Reference/Elements/input/email) validation to only accept addresses with the `@example.com` domain. We start with the HTML {{htmlelement("form")}} below. ```html @@ -556,14 +557,14 @@ First, the HTML. Again, feel free to build this along with us: </form> ``` -This form uses the [`novalidate`](/en-US/docs/Web/HTML/Element/form#novalidate) attribute to turn off the browser's automatic validation. Setting the `novalidate` attribute on the form stops the form from showing its own error message bubbles, and allows us to instead display the custom error messages in the DOM in some manner of our own choosing. +This form uses the [`novalidate`](/en-US/docs/Web/HTML/Reference/Elements/form#novalidate) attribute to turn off the browser's automatic validation. Setting the `novalidate` attribute on the form stops the form from showing its own error message bubbles, and allows us to instead display the custom error messages in the DOM in some manner of our own choosing. However, this doesn't disable support for the constraint validation API nor the application of CSS pseudo-classes like {{cssxref(":valid")}}, etc. That means that even though the browser doesn't automatically check the validity of the form before sending its data, you can still do it yourself and style the form accordingly. -Our input to validate is an [`<input type="email">`](/en-US/docs/Web/HTML/Element/input/email), which is `required`, and has a `minlength` of 8 characters. Let's check these using our own code, and show a custom error message for each one. +Our input to validate is an [`<input type="email">`](/en-US/docs/Web/HTML/Reference/Elements/input/email), which is `required`, and has a `minlength` of 8 characters. Let's check these using our own code, and show a custom error message for each one. We are aiming to show the error messages inside a `<span>` element. -The [`aria-live`](/en-US/docs/Web/Accessibility/ARIA/ARIA_Live_Regions) attribute is set on that `<span>` to make sure that our custom error message will be presented to everyone, including it being read out to screen reader users. +The [`aria-live`](/en-US/docs/Web/Accessibility/ARIA/Guides/Live_regions) attribute is set on that `<span>` to make sure that our custom error message will be presented to everyone, including it being read out to screen reader users. Now onto some basic CSS to improve the look of the form slightly, and provide some visual feedback when the input data is invalid: @@ -699,7 +700,7 @@ To validate a form, ask yourself a few questions: You should offer up-front suggestions so they know what's expected, as well as clear error messages. If you want to dig into form validation UI requirements, here are some useful articles you should read: - - [Help users enter the right data in forms](https://web.dev/Learn_web_development/Extensions/Forms/validation/) + - [Help users enter the right data in forms](https://web.dev/learn/forms/form-fields) - [Validating input](https://www.w3.org/WAI/tutorials/forms/validation/) - [How to Report Errors in Forms: 10 Design Guidelines](https://www.nngroup.com/articles/errors-forms-design-guidelines/) @@ -787,8 +788,7 @@ const email = document.getElementById("mail"); const error = document.getElementById("error"); // Regular expression for email validation as per HTML specification -const emailRegExp = - /^[a-zA-Z0-9.!#$%&'*+/=?^_`{|}~-]+@[a-zA-Z0-9-]+(?:\.[a-zA-Z0-9-]+)*$/; +const emailRegExp = /^[\w.!#$%&'*+/=?^`{|}~-]+@[a-z\d-]+(?:\.[a-z\d-]+)*$/i; // Check if the email is valid const isValidEmail = () => { @@ -852,7 +852,7 @@ As you can see, it's not that hard to build a validation system on your own. The ## Test your skills! -You've reached the end of this article, but can you remember the most important information? You can find some further tests to verify that you've retained this information before you move on — see [Test your skills: Form validation](/en-US/docs/Learn_web_development/Extensions/Forms/Test_your_skills:_Form_validation). +You've reached the end of this article, but can you remember the most important information? You can find some further tests to verify that you've retained this information before you move on — see [Test your skills: Form validation](/en-US/docs/Learn_web_development/Extensions/Forms/Test_your_skills/Form_validation). ## Summary @@ -867,8 +867,3 @@ Once you have checked that the form is filled out correctly, the form can be sub We'll cover [sending form data](/en-US/docs/Learn_web_development/Extensions/Forms/Sending_and_retrieving_form_data) next. {{PreviousMenuNext("Learn_web_development/Extensions/Forms/UI_pseudo-classes", "Learn_web_development/Extensions/Forms/Sending_and_retrieving_form_data", "Learn_web_development/Extensions/Forms")}} - -### Advanced Topics - -- [How to build custom form controls](/en-US/docs/Learn_web_development/Extensions/Forms/How_to_build_custom_form_controls) -- [Sending forms through JavaScript](/en-US/docs/Learn_web_development/Extensions/Forms/Sending_forms_through_JavaScript) diff --git a/files/en-us/learn_web_development/extensions/forms/how_to_build_custom_form_controls/example_1/index.md b/files/en-us/learn_web_development/extensions/forms/how_to_build_custom_form_controls/example_1/index.md index 678dc440680338d..f8ef2b6e0705926 100644 --- a/files/en-us/learn_web_development/extensions/forms/how_to_build_custom_form_controls/example_1/index.md +++ b/files/en-us/learn_web_development/extensions/forms/how_to_build_custom_form_controls/example_1/index.md @@ -2,10 +2,9 @@ title: Example 1 slug: Learn_web_development/Extensions/Forms/How_to_build_custom_form_controls/Example_1 page-type: learn-module-chapter +sidebar: learnsidebar --- -{{LearnSidebar}} - This is the first example of code that explains [how to build a custom form widget](/en-US/docs/Learn_web_development/Extensions/Forms/How_to_build_custom_form_controls). ## Basic state @@ -72,7 +71,6 @@ This is the first example of code that explains [how to build a custom form widg box-shadow: 0 0.1em 0.2em rgb(0 0 0 / 45%); /* 0 1px 2px */ - background: #f0f0f0; background: linear-gradient(0deg, #e3e3e3, #fcfcfc 50%, #f0f0f0); } @@ -208,7 +206,6 @@ This is the first example of code that explains [how to build a custom form widg box-shadow: 0 0.1em 0.2em rgb(0 0 0 / 45%); /* 0 1px 2px */ - background: #f0f0f0; background: linear-gradient(0deg, #e3e3e3, #fcfcfc 50%, #f0f0f0); } @@ -344,7 +341,6 @@ This is the first example of code that explains [how to build a custom form widg box-shadow: 0 0.1em 0.2em rgb(0 0 0 / 45%); /* 0 1px 2px */ - background: #f0f0f0; background: linear-gradient(0deg, #e3e3e3, #fcfcfc 50%, #f0f0f0); } diff --git a/files/en-us/learn_web_development/extensions/forms/how_to_build_custom_form_controls/example_2/index.md b/files/en-us/learn_web_development/extensions/forms/how_to_build_custom_form_controls/example_2/index.md index b419e8d9850c292..230a00203551a1d 100644 --- a/files/en-us/learn_web_development/extensions/forms/how_to_build_custom_form_controls/example_2/index.md +++ b/files/en-us/learn_web_development/extensions/forms/how_to_build_custom_form_controls/example_2/index.md @@ -2,10 +2,9 @@ title: Example 2 slug: Learn_web_development/Extensions/Forms/How_to_build_custom_form_controls/Example_2 page-type: learn-module-chapter +sidebar: learnsidebar --- -{{LearnSidebar}} - This is the second example that explain [how to build custom form widgets](/en-US/docs/Learn_web_development/Extensions/Forms/How_to_build_custom_form_controls). ## JS @@ -90,7 +89,6 @@ This is the second example that explain [how to build custom form widgets](/en-U box-shadow: 0 0.1em 0.2em rgb(0 0 0 / 45%); /* 0 1px 2px */ - background: #f0f0f0; background: linear-gradient(0deg, #e3e3e3, #fcfcfc 50%, #f0f0f0); } diff --git a/files/en-us/learn_web_development/extensions/forms/how_to_build_custom_form_controls/example_3/index.md b/files/en-us/learn_web_development/extensions/forms/how_to_build_custom_form_controls/example_3/index.md index 21dbf0e72c63c27..b7eba42079485a6 100644 --- a/files/en-us/learn_web_development/extensions/forms/how_to_build_custom_form_controls/example_3/index.md +++ b/files/en-us/learn_web_development/extensions/forms/how_to_build_custom_form_controls/example_3/index.md @@ -2,10 +2,9 @@ title: Example 3 slug: Learn_web_development/Extensions/Forms/How_to_build_custom_form_controls/Example_3 page-type: learn-module-chapter +sidebar: learnsidebar --- -{{LearnSidebar}} - This is the third example that explain [how to build custom form widgets](/en-US/docs/Learn_web_development/Extensions/Forms/How_to_build_custom_form_controls). ## Change states @@ -90,7 +89,6 @@ This is the third example that explain [how to build custom form widgets](/en-US box-shadow: 0 0.1em 0.2em rgb(0 0 0 / 45%); /* 0 1px 2px */ - background: #f0f0f0; background: linear-gradient(0deg, #e3e3e3, #fcfcfc 50%, #f0f0f0); } diff --git a/files/en-us/learn_web_development/extensions/forms/how_to_build_custom_form_controls/example_4/index.md b/files/en-us/learn_web_development/extensions/forms/how_to_build_custom_form_controls/example_4/index.md index c469399fdfab063..b2cead7eb2ba228 100644 --- a/files/en-us/learn_web_development/extensions/forms/how_to_build_custom_form_controls/example_4/index.md +++ b/files/en-us/learn_web_development/extensions/forms/how_to_build_custom_form_controls/example_4/index.md @@ -2,10 +2,9 @@ title: Example 4 slug: Learn_web_development/Extensions/Forms/How_to_build_custom_form_controls/Example_4 page-type: learn-module-chapter +sidebar: learnsidebar --- -{{LearnSidebar}} - This is the fourth example that explain [how to build custom form widgets](/en-US/docs/Learn_web_development/Extensions/Forms/How_to_build_custom_form_controls). ## Change states @@ -90,7 +89,6 @@ This is the fourth example that explain [how to build custom form widgets](/en-U box-shadow: 0 0.1em 0.2em rgb(0 0 0 / 45%); /* 0 1px 2px */ - background: #f0f0f0; background: linear-gradient(0deg, #e3e3e3, #fcfcfc 50%, #f0f0f0); } diff --git a/files/en-us/learn_web_development/extensions/forms/how_to_build_custom_form_controls/example_5/index.md b/files/en-us/learn_web_development/extensions/forms/how_to_build_custom_form_controls/example_5/index.md index d31d9464e412b19..dd3f09b029c6381 100644 --- a/files/en-us/learn_web_development/extensions/forms/how_to_build_custom_form_controls/example_5/index.md +++ b/files/en-us/learn_web_development/extensions/forms/how_to_build_custom_form_controls/example_5/index.md @@ -2,10 +2,9 @@ title: Example 5 slug: Learn_web_development/Extensions/Forms/How_to_build_custom_form_controls/Example_5 page-type: learn-module-chapter +sidebar: learnsidebar --- -{{LearnSidebar}} - This is the last example that explain [how to build custom form widgets](/en-US/docs/Learn_web_development/Extensions/Forms/How_to_build_custom_form_controls). ## Change states @@ -90,7 +89,6 @@ This is the last example that explain [how to build custom form widgets](/en-US/ box-shadow: 0 0.1em 0.2em rgb(0 0 0 / 45%); /* 0 1px 2px */ - background: #f0f0f0; background: linear-gradient(0deg, #e3e3e3, #fcfcfc 50%, #f0f0f0); } diff --git a/files/en-us/learn_web_development/extensions/forms/how_to_build_custom_form_controls/index.md b/files/en-us/learn_web_development/extensions/forms/how_to_build_custom_form_controls/index.md index afd1306a15fddbe..69f1f85c4494023 100644 --- a/files/en-us/learn_web_development/extensions/forms/how_to_build_custom_form_controls/index.md +++ b/files/en-us/learn_web_development/extensions/forms/how_to_build_custom_form_controls/index.md @@ -2,10 +2,9 @@ title: How to build custom form controls slug: Learn_web_development/Extensions/Forms/How_to_build_custom_form_controls page-type: learn-module-chapter +sidebar: learnsidebar --- -{{LearnSidebar}} - There are some cases where the available native HTML form controls may seem like they are not enough. For example, if you need to [perform advanced styling](/en-US/docs/Learn_web_development/Extensions/Forms/Advanced_form_styling) on some controls such as the {{HTMLElement("select")}} element, or if you want to provide custom behaviors, you may consider building your own controls. In this article, we will discuss how to build a custom control. To that end, we will work with an example: rebuilding the {{HTMLElement("select")}} element. We will also discuss how, when, and whether building your own control makes sense, and what to consider when building a control is a requirement. @@ -29,7 +28,7 @@ In terms of behavior, we are recreating a native HTML element. Therefore it shou - the page loads. - the control was active and the user clicks anywhere outside it. -- the control was active and the user moves the focus to another control using the keyboard (e.g. the <kbd>Tab</kbd> key). +- the control was active and the user moves the focus to another control using the keyboard (e.g., the <kbd>Tab</kbd> key). **The control is in its active state when:** @@ -189,8 +188,6 @@ So now that we have the basic functionality in place, the fun can start. The fol border-radius: 0.4em; box-shadow: 0 0.1em 0.2em rgb(0 0 0 / 45%); - /* The first declaration is for browsers that do not support linear gradients. */ - background: #f0f0f0; background: linear-gradient(0deg, #e3e3e3, #fcfcfc 50%, #f0f0f0); } @@ -332,7 +329,6 @@ So here's the result with our three states ([check out the source code here](/en box-shadow: 0 0.1em 0.2em rgb(0 0 0 / 45%); /* 0 1px 2px */ - background: #f0f0f0; background: linear-gradient(0deg, #e3e3e3, #fcfcfc 50%, #f0f0f0); } @@ -454,7 +450,6 @@ So here's the result with our three states ([check out the source code here](/en box-shadow: 0 0.1em 0.2em rgb(0 0 0 / 45%); /* 0 1px 2px */ - background: #f0f0f0; background: linear-gradient(0deg, #e3e3e3, #fcfcfc 50%, #f0f0f0); } @@ -576,7 +571,6 @@ So here's the result with our three states ([check out the source code here](/en box-shadow: 0 0.1em 0.2em rgb(0 0 0 / 45%); /* 0 1px 2px */ - background: #f0f0f0; background: linear-gradient(0deg, #e3e3e3, #fcfcfc 50%, #f0f0f0); } @@ -836,7 +830,6 @@ Check out the [full source code](/en-US/docs/Learn_web_development/Extensions/Fo box-shadow: 0 0.1em 0.2em rgb(0 0 0 / 45%); /* 0 1px 2px */ - background: #f0f0f0; background: linear-gradient(0deg, #e3e3e3, #fcfcfc 50%, #f0f0f0); } @@ -1134,7 +1127,6 @@ Check out the [full source code](/en-US/docs/Learn_web_development/Extensions/Fo box-shadow: 0 0.1em 0.2em rgb(0 0 0 / 45%); /* 0 1px 2px */ - background: #f0f0f0; background: linear-gradient(0deg, #e3e3e3, #fcfcfc 50%, #f0f0f0); } @@ -1464,7 +1456,6 @@ Check out the [source code here](/en-US/docs/Learn_web_development/Extensions/Fo box-shadow: 0 0.1em 0.2em rgb(0 0 0 / 45%); /* 0 1px 2px */ - background: #f0f0f0; background: linear-gradient(0deg, #e3e3e3, #fcfcfc 50%, #f0f0f0); } @@ -1663,11 +1654,11 @@ Fortunately, there is a solution and it's called [ARIA](/en-US/docs/Web/Accessib ### The `role` attribute -The key attribute used by [ARIA](/en-US/docs/Web/Accessibility/ARIA) is the [`role`](/en-US/docs/Web/Accessibility/ARIA/ARIA_Techniques) attribute. The [`role`](/en-US/docs/Web/Accessibility/ARIA/ARIA_Techniques) attribute accepts a value that defines what an element is used for. Each role defines its own requirements and behaviors. In our example, we will use the [`listbox`](/en-US/docs/Web/Accessibility/ARIA/Roles/listbox_role) role. It's a "composite role", which means elements with that role expect to have children, each with a specific role (in this case, at least one child with the `option` role). +The key attribute used by [ARIA](/en-US/docs/Web/Accessibility/ARIA) is the [`role`](/en-US/docs/Web/Accessibility/ARIA/Guides/Techniques) attribute. The [`role`](/en-US/docs/Web/Accessibility/ARIA/Guides/Techniques) attribute accepts a value that defines what an element is used for. Each role defines its own requirements and behaviors. In our example, we will use the [`listbox`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/listbox_role) role. It's a "composite role", which means elements with that role expect to have children, each with a specific role (in this case, at least one child with the `option` role). It's also worth noting that ARIA defines roles that are applied by default to standard HTML markup. For example, the {{HTMLElement("table")}} element matches the role `grid`, and the {{HTMLElement("ul")}} element matches the role `list`. Because we use a {{HTMLElement("ul")}} element, we want to make sure the `listbox` role of our control will supersede the `list` role of the {{HTMLElement("ul")}} element. To that end, we will use the role `presentation`. This role is designed to let us indicate that an element has no special meaning, and is used solely to present information. We will apply it to our {{HTMLElement("ul")}} element. -To support the [`listbox`](/en-US/docs/Web/Accessibility/ARIA/Roles/listbox_role) role, we just have to update our HTML like this: +To support the [`listbox`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/listbox_role) role, we just have to update our HTML like this: ```html <!-- We add the role="listbox" attribute to our top element --> @@ -1690,7 +1681,7 @@ To support the [`listbox`](/en-US/docs/Web/Accessibility/ARIA/Roles/listbox_role ### The `aria-selected` attribute -Using the [`role`](/en-US/docs/Web/Accessibility/ARIA/ARIA_Techniques) attribute is not enough. [ARIA](/en-US/docs/Web/Accessibility/ARIA) also provides many states and property attributes. The more and better you use them, the better your control will be understood by assistive technologies. In our case, we will limit our usage to one attribute: `aria-selected`. +Using the [`role`](/en-US/docs/Web/Accessibility/ARIA/Guides/Techniques) attribute is not enough. [ARIA](/en-US/docs/Web/Accessibility/ARIA) also provides many states and property attributes. The more and better you use them, the better your control will be understood by assistive technologies. In our case, we will limit our usage to one attribute: `aria-selected`. The `aria-selected` attribute is used to mark which option is currently selected; this lets assistive technologies inform the user what the current selection is. We will use it dynamically with JavaScript to mark the selected option each time the user chooses one. To that end, we need to revise our `updateValue()` function: @@ -1716,7 +1707,7 @@ function updateValue(select, index) { It might have seemed simpler to let a screen reader focus on the off-screen select and ignore our stylized one, but this is not an accessible solution. Screen readers are not limited to blind people; people with low vision and even perfect vision use them as well. For this reason, you can not have the screen reader focus on an off-screen element. -Below is the final result of all these changes (you'll get a better feel for this by trying it with an assistive technology such as [NVDA](https://www.nvaccess.org/) or [VoiceOver](https://www.apple.com/accessibility/vision/)). +Below is the final result of all these changes (you'll get a better feel for this by trying it with an assistive technology such as [NVDA](https://www.nvaccess.org/) or [VoiceOver](https://www.apple.com/accessibility/features/?vision)). #### Live example @@ -1790,7 +1781,6 @@ Check out the [full source code here](/en-US/docs/Learn_web_development/Extensio box-shadow: 0 0.1em 0.2em rgb(0 0 0 / 45%); /* 0 1px 2px */ - background: #f0f0f0; background: linear-gradient(0deg, #e3e3e3, #fcfcfc 50%, #f0f0f0); } @@ -2095,24 +2085,3 @@ Here are a few libraries you should consider before coding your own: - [msDropDown](https://github.com/marghoobsuleman/ms-Dropdown) If you do create alternative controls via radio buttons, your own JavaScript, or with a 3rd party library, ensure it is accessible and feature-proof; that is, it needs to be able to work better with a variety of browsers whose compatibility with the Web standards they use vary. Have fun! - -## See also - -### Learning path - -- [Your first HTML form](/en-US/docs/Learn_web_development/Extensions/Forms/Your_first_form) -- [How to structure an HTML form](/en-US/docs/Learn_web_development/Extensions/Forms/How_to_structure_a_web_form) -- [The native form controls](/en-US/docs/Learn_web_development/Extensions/Forms/Basic_native_form_controls) -- [HTML5 input types](/en-US/docs/Learn_web_development/Extensions/Forms/HTML5_input_types) -- [Additional form controls](/en-US/docs/Learn_web_development/Extensions/Forms/Other_form_controls) -- [UI pseudo-classes](/en-US/docs/Learn_web_development/Extensions/Forms/UI_pseudo-classes) -- [Styling HTML forms](/en-US/docs/Learn_web_development/Extensions/Forms/Styling_web_forms) -- [Form data validation](/en-US/docs/Learn_web_development/Extensions/Forms/Form_validation) -- [Sending form data](/en-US/docs/Learn_web_development/Extensions/Forms/Sending_and_retrieving_form_data) - -### Advanced Topics - -- [Sending forms through JavaScript](/en-US/docs/Learn_web_development/Extensions/Forms/Sending_forms_through_JavaScript) -- **How to build custom form controls** -- [HTML forms in legacy browsers](/en-US/docs/Learn_web_development/Extensions/Forms/HTML_forms_in_legacy_browsers) -- [Advanced styling for HTML forms](/en-US/docs/Learn_web_development/Extensions/Forms/Advanced_form_styling) diff --git a/files/en-us/learn_web_development/extensions/forms/how_to_structure_a_web_form/example/index.md b/files/en-us/learn_web_development/extensions/forms/how_to_structure_a_web_form/example/index.md index 16c7155bd9a7432..782d7cdcd7ecf51 100644 --- a/files/en-us/learn_web_development/extensions/forms/how_to_structure_a_web_form/example/index.md +++ b/files/en-us/learn_web_development/extensions/forms/how_to_structure_a_web_form/example/index.md @@ -2,10 +2,9 @@ title: Example slug: Learn_web_development/Extensions/Forms/How_to_structure_a_web_form/Example page-type: learn-module-chapter +sidebar: learnsidebar --- -{{LearnSidebar}} - This the example for a basic payment form for the article [How to structure an HTML form](/en-US/docs/Learn_web_development/Extensions/Forms/How_to_structure_a_web_form). ## A payment form diff --git a/files/en-us/learn_web_development/extensions/forms/how_to_structure_a_web_form/index.md b/files/en-us/learn_web_development/extensions/forms/how_to_structure_a_web_form/index.md index 915fd3ac4b65061..bf5ddcb9e7ec5ae 100644 --- a/files/en-us/learn_web_development/extensions/forms/how_to_structure_a_web_form/index.md +++ b/files/en-us/learn_web_development/extensions/forms/how_to_structure_a_web_form/index.md @@ -2,9 +2,10 @@ title: How to structure a web form slug: Learn_web_development/Extensions/Forms/How_to_structure_a_web_form page-type: learn-module-chapter +sidebar: learnsidebar --- -{{LearnSidebar}}{{PreviousMenuNext("Learn_web_development/Extensions/Forms/Your_first_form", "Learn_web_development/Extensions/Forms/Basic_native_form_controls", "Learn_web_development/Extensions/Forms")}} +{{PreviousMenuNext("Learn_web_development/Extensions/Forms/Your_first_form", "Learn_web_development/Extensions/Forms/Basic_native_form_controls", "Learn_web_development/Extensions/Forms")}} With the basics out of the way, we'll now look in more detail at the elements used to provide structure and meaning to the different parts of a form. @@ -36,7 +37,7 @@ We already met this in the previous article. > [!WARNING] > It's strictly forbidden to nest a form inside another form. Nesting can cause forms to behave unpredictably, so it is a bad idea. -It's always possible to use a form control outside of a {{HTMLElement("form")}} element. If you do so, by default that control has nothing to do with any form unless you associate it with a form using its [`form`](/en-US/docs/Web/HTML/Element/input#form) attribute. This was introduced to let you explicitly bind a control with a form even if it is not nested inside it. +It's always possible to use a form control outside of a {{HTMLElement("form")}} element. If you do so, by default that control has nothing to do with any form unless you associate it with a form using its [`form`](/en-US/docs/Web/HTML/Reference/Elements/input#form) attribute. This was introduced to let you explicitly bind a control with a form even if it is not nested inside it. Let's move forward and cover the structural elements you'll find nested in a form. @@ -79,7 +80,7 @@ Because of its influence over assistive technology, the {{HTMLElement("fieldset" ## The \<label> element -As we saw in the previous article, The {{HTMLElement("label")}} element is the formal way to define a label for an HTML form widget. This is the most important element if you want to build accessible forms — when implemented properly, screen readers will speak a form element's label along with any related instructions, as well as it being useful for sighted users. Take this example, which we saw in the previous article: +As we saw in the previous article, the {{HTMLElement("label")}} element is the formal way to define a label for an HTML form widget. This is the most important element if you want to build accessible forms — when implemented properly, screen readers will speak a form element's label along with any related instructions, as well as it being useful for sighted users. Take this example, which we saw in the previous article: ```html <label for="name">Name:</label> <input type="text" id="name" name="user_name" /> @@ -155,7 +156,7 @@ Let's consider this example: {{EmbedLiveSample("Multiple_labels", 120, 120)}} -The paragraph at the top states a rule for required elements. The rule must be included _before_ it is used so that sighted users and users of assistive technologies such as screen readers can learn what it means before they encounter a required element. While this helps inform users what an asterisk means, it can not be relied upon. A screen reader will speak an asterisk as "_star_" when encountered. When hovered by a sighted mouse user, "_required_" should appear, which is achieved by use of the `title` attribute. Titles being read aloud depends on the screen reader's settings, so it is more reliable to also include the [`aria-label`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-label) attribute, which is always read by screen readers. +The paragraph at the top states a rule for required elements. The rule must be included _before_ it is used so that sighted users and users of assistive technologies such as screen readers can learn what it means before they encounter a required element. While this helps inform users what an asterisk means, it can not be relied upon. A screen reader will speak an asterisk as "_star_" when encountered. When hovered by a sighted mouse user, "_required_" should appear, which is achieved by use of the `title` attribute. Titles being read aloud depends on the screen reader's settings, so it is more reliable to also include the [`aria-label`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-label) attribute, which is always read by screen readers. The above variants increase in effectiveness as you go through them: @@ -175,7 +176,7 @@ Beyond the structures specific to web forms, it's good to remember that form mar As you can see in the examples, it's common practice to wrap a label and its widget with a {{HTMLElement("li")}} element within a {{HTMLElement("ul")}} or {{HTMLElement("ol")}} list. {{HTMLElement("p")}} and {{HTMLElement("div")}} elements are also commonly used. Lists are recommended for structuring multiple checkboxes or radio buttons. -In addition to the {{HTMLElement("fieldset")}} element, it's also common practice to use HTML titles (e.g. {{htmlelement("Heading_Elements", "h1")}}, {{htmlelement("Heading_Elements", "h2")}}) and sectioning (e.g. {{htmlelement("section")}}) to structure complex forms. +In addition to the {{HTMLElement("fieldset")}} element, it's also common practice to use HTML titles (e.g., {{htmlelement("Heading_Elements", "h1")}}, {{htmlelement("Heading_Elements", "h2")}}) and sectioning (e.g., {{htmlelement("section")}}) to structure complex forms. Above all, it is up to you to find a comfortable coding style that results in accessible, usable forms. Each separate section of functionality should be contained in a separate {{htmlelement("section")}} element, with {{htmlelement("fieldset")}} elements to contain radio buttons. @@ -392,7 +393,7 @@ We applied some extra CSS to the finished form below. If you'd like to make chan ## Test your skills! -You've reached the end of this article, but can you remember the most important information? You can find a further test to verify that you've retained this information before you move on — see [Test your skills: Form structure](/en-US/docs/Learn_web_development/Extensions/Forms/Test_your_skills:_Form_structure). +You've reached the end of this article, but can you remember the most important information? You can find a further test to verify that you've retained this information before you move on — see [Test your skills: Form structure](/en-US/docs/Learn_web_development/Extensions/Forms/Test_your_skills/Form_structure). ## Summary @@ -403,8 +404,3 @@ You now have all the knowledge you'll need to properly structure your web forms. - [A List Apart: _Sensible Forms: A Form Usability Checklist_](https://alistapart.com/article/sensibleforms/) {{PreviousMenuNext("Learn_web_development/Extensions/Forms/Your_first_form", "Learn_web_development/Extensions/Forms/Basic_native_form_controls", "Learn_web_development/Extensions/Forms")}} - -### Advanced Topics - -- [How to build custom form controls](/en-US/docs/Learn_web_development/Extensions/Forms/How_to_build_custom_form_controls) -- [Sending forms through JavaScript](/en-US/docs/Learn_web_development/Extensions/Forms/Sending_forms_through_JavaScript) diff --git a/files/en-us/learn_web_development/extensions/forms/html5_input_types/index.md b/files/en-us/learn_web_development/extensions/forms/html5_input_types/index.md index c7999df44eb2f1f..0aba63062d6a92a 100644 --- a/files/en-us/learn_web_development/extensions/forms/html5_input_types/index.md +++ b/files/en-us/learn_web_development/extensions/forms/html5_input_types/index.md @@ -2,9 +2,10 @@ title: The HTML5 input types slug: Learn_web_development/Extensions/Forms/HTML5_input_types page-type: learn-module-chapter +sidebar: learnsidebar --- -{{LearnSidebar}}{{PreviousMenuNext("Learn_web_development/Extensions/Forms/Basic_native_form_controls", "Learn_web_development/Extensions/Forms/Other_form_controls", "Learn_web_development/Extensions/Forms")}} +{{PreviousMenuNext("Learn_web_development/Extensions/Forms/Basic_native_form_controls", "Learn_web_development/Extensions/Forms/Other_form_controls", "Learn_web_development/Extensions/Forms")}} In the [previous article](/en-US/docs/Learn_web_development/Extensions/Forms/Basic_native_form_controls) we looked at the {{htmlelement("input")}} element, covering the original values of the `type` attribute available since the early days of HTML. Now we'll look in detail at the functionality of some input types that were added later. @@ -33,7 +34,7 @@ Because HTML form control appearance may be quite different from a designer's sp ## Email address field -This type of field is set using the value `email` for the [`type`](/en-US/docs/Web/HTML/Element/input#type) attribute: +This type of field is set using the value `email` for the [`type`](/en-US/docs/Web/HTML/Reference/Elements/input#type) attribute: ```html hidden live-sample___email <label for="email">Enter your email address:</label><br /> @@ -45,11 +46,11 @@ This type of field is set using the value `email` for the [`type`](/en-US/docs/W {{EmbedLiveSample('email','100%','50')}} -When this [`type`](/en-US/docs/Web/HTML/Element/input#type) is used, the value must be an email address to be valid. Any other content causes the browser to display an error when the form is submitted. You can see this in action in the screenshot below. +When this [`type`](/en-US/docs/Web/HTML/Reference/Elements/input#type) is used, the value must be an email address to be valid. Any other content causes the browser to display an error when the form is submitted. You can see this in action in the screenshot below. ![An invalid email input showing the message "Please enter an email address."](email_address_invalid.png) -You can use the [`multiple`](/en-US/docs/Web/HTML/Attributes/multiple) attribute in combination with the `email` input type to allow several comma-separated email addresses to be entered in the same input: +You can use the [`multiple`](/en-US/docs/Web/HTML/Reference/Attributes/multiple) attribute in combination with the `email` input type to allow several comma-separated email addresses to be entered in the same input: ```html <input type="email" id="email" name="email" multiple /> @@ -70,14 +71,14 @@ As you can see above, `email` — along with other newer `input` types — provi But it _should not be considered_ an exhaustive security measure! Your apps should always perform security checks on any form-submitted data on the _server-side_ as well as the client-side, because client-side validation is too easy to turn off, so malicious users can still easily send bad data through to your server. Read [Website security](/en-US/docs/Learn_web_development/Extensions/Server-side/First_steps/Website_security) for an idea of what _could_ happen; implementing server-side validation is somewhat beyond the scope of this module, but you should bear it in mind. -Note that `a@b` is a valid email address according to the default provided constraints. This is because the `email` input type allows intranet email addresses by default. To implement different validation behavior, you can use the [`pattern`](/en-US/docs/Web/HTML/Attributes/pattern) attribute. You can also customize the error messages. We'll talk about how to use these features in the [Client-side form validation](/en-US/docs/Learn_web_development/Extensions/Forms/Form_validation) article later on. +Note that `a@b` is a valid email address according to the default provided constraints. This is because the `email` input type allows intranet email addresses by default. To implement different validation behavior, you can use the [`pattern`](/en-US/docs/Web/HTML/Reference/Attributes/pattern) attribute. You can also customize the error messages. We'll talk about how to use these features in the [Client-side form validation](/en-US/docs/Learn_web_development/Extensions/Forms/Form_validation) article later on. > [!NOTE] > If the data entered is not an email address, the {{cssxref(':invalid')}} pseudo-class will match, and the {{domxref('validityState.typeMismatch')}} property will return `true`. ## Search field -Search fields are intended to be used to create search boxes on pages and apps. This type of field is set by using the value `search` for the [`type`](/en-US/docs/Web/HTML/Element/input#type) attribute: +Search fields are intended to be used to create search boxes on pages and apps. This type of field is set by using the value `search` for the [`type`](/en-US/docs/Web/HTML/Reference/Elements/input#type) attribute: ```html hidden <label for="search">Enter a search term:</label><br /> @@ -95,7 +96,7 @@ Another worth-noting feature is that the values of a `search` field can be autom ## Phone number field -A special field for filling in phone numbers can be created using `tel` as the value of the [`type`](/en-US/docs/Web/HTML/Element/input#type) attribute: +A special field for filling in phone numbers can be created using `tel` as the value of the [`type`](/en-US/docs/Web/HTML/Reference/Elements/input#type) attribute: ```html hidden <label for="tel">Enter a telephone number:</label><br /> @@ -113,11 +114,11 @@ When accessed via a touch device with a dynamic keyboard, most devices will disp Due to the wide variety of phone number formats around the world, this type of field does not enforce any constraints on the value entered by a user (this means it may include letters, etc.). -As we mentioned earlier, the [`pattern`](/en-US/docs/Web/HTML/Attributes/pattern) attribute can be used to enforce constraints, which you'll learn about in [Client-side form validation](/en-US/docs/Learn_web_development/Extensions/Forms/Form_validation). +As we mentioned earlier, the [`pattern`](/en-US/docs/Web/HTML/Reference/Attributes/pattern) attribute can be used to enforce constraints, which you'll learn about in [Client-side form validation](/en-US/docs/Learn_web_development/Extensions/Forms/Form_validation). ## URL field -A special type of field for entering URLs can be created using the value `url` for the [`type`](/en-US/docs/Web/HTML/Element/input#type) attribute: +A special type of field for entering URLs can be created using the value `url` for the [`type`](/en-US/docs/Web/HTML/Reference/Elements/input#type) attribute: ```html hidden <label for="url">Enter a URL:</label><br /> @@ -136,7 +137,7 @@ It adds special validation constraints to the field. The browser will report an ## Numeric field -Controls for entering numbers can be created with an {{HTMLElement("input")}} [`type`](/en-US/docs/Web/HTML/Element/input#type) of `number`. This control looks like a text field but allows only floating-point numbers, and usually provides buttons in the form of a spinner to increase and decrease the value of the control. On devices with dynamic keyboards, the numeric keyboard is generally displayed. +Controls for entering numbers can be created with an {{HTMLElement("input")}} [`type`](/en-US/docs/Web/HTML/Reference/Elements/input#type) of `number`. This control looks like a text field but allows only floating-point numbers, and usually provides buttons in the form of a spinner to increase and decrease the value of the control. On devices with dynamic keyboards, the numeric keyboard is generally displayed. ```html hidden live-sample___number <label for="number">Enter a number:</label><br /> @@ -148,9 +149,9 @@ Controls for entering numbers can be created with an {{HTMLElement("input")}} [` {{EmbedLiveSample('number','100%','50')}} -With the `number` input type, you can constrain the minimum and maximum values allowed by setting the [`min`](/en-US/docs/Web/HTML/Element/input#min) and [`max`](/en-US/docs/Web/HTML/Element/input#max) attributes. +With the `number` input type, you can constrain the minimum and maximum values allowed by setting the [`min`](/en-US/docs/Web/HTML/Reference/Elements/input#min) and [`max`](/en-US/docs/Web/HTML/Reference/Elements/input#max) attributes. -You can also use the `step` attribute to set the increment increase and decrease caused by pressing the spinner buttons. By default, the number input type only validates if the number is an integer, as the [`step`](/en-US/docs/Web/HTML/Attributes/step) attribute defaults to `1`. To allow float numbers, specify `step="any"` or a specific value, like `step="0.01"` to restrict the floating point. If omitted, as the `step` value defaults to `1`, only whole numbers are valid. +You can also use the `step` attribute to set the increment increase and decrease caused by pressing the spinner buttons. By default, the number input type only validates if the number is an integer, as the [`step`](/en-US/docs/Web/HTML/Reference/Attributes/step) attribute defaults to `1`. To allow float numbers, specify `step="any"` or a specific value, like `step="0.01"` to restrict the floating point. If omitted, as the `step` value defaults to `1`, only whole numbers are valid. Let's look at some examples: @@ -188,9 +189,9 @@ Another way to pick a number is to use a **slider**. You see these quite often o Usage-wise, sliders are less accurate than text fields. Therefore, they are used to pick a number whose _precise_ value is not necessarily important. -A slider is created using the {{HTMLElement("input")}} with its [`type`](/en-US/docs/Web/HTML/Element/input#type) attribute set to the value `range`. The slider-thumb can be moved via mouse or touch, or with the arrows of the keypad. +A slider is created using the {{HTMLElement("input")}} with its [`type`](/en-US/docs/Web/HTML/Reference/Elements/input#type) attribute set to the value `range`. The slider-thumb can be moved via mouse or touch, or with the arrows of the keypad. -It's important to properly configure your slider. To that end, it's highly recommended that you set the [`min`](/en-US/docs/Web/HTML/Attributes/min), [`max`](/en-US/docs/Web/HTML/Attributes/max), and [`step`](/en-US/docs/Web/HTML/Attributes/step) attributes which set the minimum, maximum, and increment values, respectively. +It's important to properly configure your slider. To that end, it's highly recommended that you set the [`min`](/en-US/docs/Web/HTML/Reference/Attributes/min), [`max`](/en-US/docs/Web/HTML/Reference/Attributes/max), and [`step`](/en-US/docs/Web/HTML/Reference/Attributes/step) attributes which set the minimum, maximum, and increment values, respectively. Let's look at the code behind the above example, so you can see how it's done. First of all, the basic HTML: @@ -242,7 +243,7 @@ Generally, for a good user experience when gathering date and time values, it is HTML date controls are available to handle this specific kind of data, providing calendar widgets and making the data uniform. -A date and time control is created using the {{HTMLElement("input")}} element and an appropriate value for the [`type`](/en-US/docs/Web/HTML/Element/input#type) attribute, depending on whether you wish to collect dates, times, or both. Here's a live example: +A date and time control is created using the {{HTMLElement("input")}} element and an appropriate value for the [`type`](/en-US/docs/Web/HTML/Reference/Elements/input#type) attribute, depending on whether you wish to collect dates, times, or both. Here's a live example: ```html hidden live-sample___date1 <label for="party">Choose a date and time for your party:</label> @@ -266,7 +267,7 @@ Let's look at the different available types in brief. Note that the usage of the ### `date` -[`<input type="date">`](/en-US/docs/Web/HTML/Element/input/date) creates a widget to display and pick a date (year, month, and day, with no time). +[`<input type="date">`](/en-US/docs/Web/HTML/Reference/Elements/input/date) creates a widget to display and pick a date (year, month, and day, with no time). ```html hidden <label for="date">Enter the date:</label><br /> @@ -280,7 +281,7 @@ Let's look at the different available types in brief. Note that the usage of the ### `datetime-local` -[`<input type="datetime-local">`](/en-US/docs/Web/HTML/Element/input/datetime-local) creates a widget to display and pick a date with time with no specific time zone information. +[`<input type="datetime-local">`](/en-US/docs/Web/HTML/Reference/Elements/input/datetime-local) creates a widget to display and pick a date with time with no specific time zone information. ```html hidden <label for="month">Enter the date and time:</label><br /> @@ -294,7 +295,7 @@ Let's look at the different available types in brief. Note that the usage of the ### `month` -[`<input type="month">`](/en-US/docs/Web/HTML/Element/input/month) creates a widget to display and pick a month with a year. +[`<input type="month">`](/en-US/docs/Web/HTML/Reference/Elements/input/month) creates a widget to display and pick a month with a year. ```html hidden <label for="month">Enter the month:</label><br /> @@ -308,7 +309,7 @@ Let's look at the different available types in brief. Note that the usage of the ### `time` -[`<input type="time">`](/en-US/docs/Web/HTML/Element/input/time) creates a widget to display and pick a time value. While time may _display_ in 12-hour format, the _value returned_ is in 24-hour format. +[`<input type="time">`](/en-US/docs/Web/HTML/Reference/Elements/input/time) creates a widget to display and pick a time value. While time may _display_ in 12-hour format, the _value returned_ is in 24-hour format. ```html hidden <label for="time">Enter a time:</label><br /> @@ -322,7 +323,7 @@ Let's look at the different available types in brief. Note that the usage of the ### `week` -[`<input type="week">`](/en-US/docs/Web/HTML/Element/input/week) creates a widget to display and pick a week number and its year. +[`<input type="week">`](/en-US/docs/Web/HTML/Reference/Elements/input/week) creates a widget to display and pick a week number and its year. Weeks start on Monday and run to Sunday. Additionally, the first week 1 of each year contains the first Thursday of that year — which may not include the first day of the year, or may include the last few days of the previous year. @@ -338,7 +339,7 @@ Weeks start on Monday and run to Sunday. Additionally, the first week 1 of each ### Constraining date/time values -All date and time controls can be constrained using the [`min`](/en-US/docs/Web/HTML/Attributes/min) and [`max`](/en-US/docs/Web/HTML/Attributes/max) attributes, with further constraining possible via the [`step`](/en-US/docs/Web/HTML/Attributes/step) attribute (whose value varies according to input type). +All date and time controls can be constrained using the [`min`](/en-US/docs/Web/HTML/Reference/Attributes/min) and [`max`](/en-US/docs/Web/HTML/Reference/Attributes/max) attributes, with further constraining possible via the [`step`](/en-US/docs/Web/HTML/Reference/Attributes/step) attribute (whose value varies according to input type). ```html <label for="myDate">When are you available this summer?</label><br /> @@ -357,7 +358,7 @@ All date and time controls can be constrained using the [`min`](/en-US/docs/Web/ Colors are always a bit difficult to handle. There are many ways to express them: RGB values (decimal or hexadecimal), HSL values, keywords, and so on. -A `color` control can be created using the {{HTMLElement("input")}} element with its [`type`](/en-US/docs/Web/HTML/Element/input#type) attribute set to the value `color`: +A `color` control can be created using the {{HTMLElement("input")}} element with its [`type`](/en-US/docs/Web/HTML/Reference/Elements/input#type) attribute set to the value `color`: ```html hidden <label for="color">Pick a color:</label><br /> @@ -373,15 +374,10 @@ Clicking a color control generally displays the operating system's default color ## Test your skills! -You've reached the end of this article, but can you remember the most important information? You can find some further tests to verify that you've retained this information before you move on — see [Test your skills: HTML5 controls](/en-US/docs/Learn_web_development/Extensions/Forms/Test_your_skills:_HTML5_controls). +You've reached the end of this article, but can you remember the most important information? You can find some further tests to verify that you've retained this information before you move on — see [Test your skills: HTML5 controls](/en-US/docs/Learn_web_development/Extensions/Forms/Test_your_skills/Input_types). ## Summary That brings us to the end of our tour of the HTML5 form input types. There are a few other control types that cannot be easily grouped due to their very specific behaviors but are still essential to know. We cover those in the next article. {{PreviousMenuNext("Learn_web_development/Extensions/Forms/Basic_native_form_controls", "Learn_web_development/Extensions/Forms/Other_form_controls", "Learn_web_development/Extensions/Forms")}} - -### Advanced Topics - -- [How to build custom form controls](/en-US/docs/Learn_web_development/Extensions/Forms/How_to_build_custom_form_controls) -- [Sending forms through JavaScript](/en-US/docs/Learn_web_development/Extensions/Forms/Sending_forms_through_JavaScript) diff --git a/files/en-us/learn_web_development/extensions/forms/html_forms_in_legacy_browsers/index.md b/files/en-us/learn_web_development/extensions/forms/html_forms_in_legacy_browsers/index.md index de0109977a950af..820f4a899338d92 100644 --- a/files/en-us/learn_web_development/extensions/forms/html_forms_in_legacy_browsers/index.md +++ b/files/en-us/learn_web_development/extensions/forms/html_forms_in_legacy_browsers/index.md @@ -2,10 +2,9 @@ title: HTML forms in legacy browsers slug: Learn_web_development/Extensions/Forms/HTML_forms_in_legacy_browsers page-type: guide +sidebar: learnsidebar --- -{{LearnSidebar}} - All web developers learn very quickly (and sometimes painfully) that the Web is a very rough place for them. Our worst curse is legacy browsers. This used to mean "Internet Explorer", but there are millions of people using old devices, especially mobile phones, where neither the browser nor the OS can be updated. Dealing with this wilderness is part of the job. Fortunately, there are a few tricks to know that can help you to solve most of the problems caused by legacy browsers. If a browser doesn't support an HTML {{htmlelement('input')}} type, it doesn't fail: it just uses the default value of `type=text`. @@ -24,7 +23,7 @@ Let's see some examples related to HTML forms. #### HTML input types -All HTML input types are useable in all browsers, even ancient ones, because the way they degrade is highly predictable. If a browser does not know the value of the [`type`](/en-US/docs/Web/HTML/Element/input#type) attribute of an {{HTMLElement("input")}} element, it will fall back as if the value were `text`. +All HTML input types are useable in all browsers, even ancient ones, because the way they degrade is highly predictable. If a browser does not know the value of the [`type`](/en-US/docs/Web/HTML/Reference/Elements/input#type) attribute of an {{HTMLElement("input")}} element, it will fall back as if the value were `text`. ```html <label for="myColor"> @@ -62,7 +61,7 @@ All HTML input types are useable in all browsers, even ancient ones, because the There are two ways to define buttons within HTML forms: -- The {{HTMLElement("input")}} element with its attribute [`type`](/en-US/docs/Web/HTML/Element/input#type) set to the values `button`, `submit`, `reset` or `image` +- The {{HTMLElement("input")}} element with its attribute [`type`](/en-US/docs/Web/HTML/Reference/Elements/input#type) set to the values `button`, `submit`, `reset` or `image` - The {{HTMLElement("button")}} element ##### {{HTMLElement("input")}} @@ -73,7 +72,7 @@ The {{HTMLElement("input")}} element can make things a little difficult if you w <input type="button" value="click me" /> ``` -If we remove the border on all inputs, can we restore the default appearance on input buttons only? +If we remove the border on all inputs, we can restore the default appearance for input buttons only with the global CSS {{cssxref('revert')}} value. ```css input { @@ -82,22 +81,11 @@ input { border: 1px solid #ccc; } input[type="button"] { - /* This does NOT restore the default rendering */ - border: none; -} -input[type="button"] { - /* These don't either! Actually there is no standard way to do it in any browser */ - border: auto; - border: initial; -} -input[type="button"] { - /* This will come the closest to restoring default rendering. */ + /* Revert the last border declaration */ border: revert; } ``` -See the global CSS {{cssxref('revert')}} value for more information. - ### Let go of CSS One of the big issues with HTML Forms is styling form widgets with CSS. Form controls appearance is browser and operating system specific. For example, the input of color type looks different in Safari, Chrome and Firefox browser, but the color picker widget is the same in all browsers on a device as it opens up the operating system's native color picker. @@ -143,24 +131,3 @@ Even though some polyfills are very aware of performance, loading additional scr As you can see, considering browser and operating system default form control appearance is important. There are many techniques to handle these issue; however mastering all of them is beyond the scope of this article. The basic premise is to consider whether altering the default implementation is worth the work before embarking on the challenge. If you read all the articles of this [HTML Forms guide](/en-US/docs/Learn_web_development/Extensions/Forms), you should now be at ease with using forms. If you discover new techniques or hints, please help improve the guide. - -## See also - -### Learning path - -- [Your first HTML form](/en-US/docs/Learn_web_development/Extensions/Forms/Your_first_form) -- [How to structure an HTML form](/en-US/docs/Learn_web_development/Extensions/Forms/How_to_structure_a_web_form) -- [The native form widgets](/en-US/docs/Learn_web_development/Extensions/Forms/Basic_native_form_controls) -- [HTML5 input types](/en-US/docs/Learn_web_development/Extensions/Forms/HTML5_input_types) -- [Additional form controls](/en-US/docs/Learn_web_development/Extensions/Forms/Other_form_controls) -- [UI pseudo-classes](/en-US/docs/Learn_web_development/Extensions/Forms/UI_pseudo-classes) -- [Styling HTML forms](/en-US/docs/Learn_web_development/Extensions/Forms/Styling_web_forms) -- [Form data validation](/en-US/docs/Learn_web_development/Extensions/Forms/Form_validation) -- [Sending form data](/en-US/docs/Learn_web_development/Extensions/Forms/Sending_and_retrieving_form_data) - -### Advanced Topics - -- [Sending forms through JavaScript](/en-US/docs/Learn_web_development/Extensions/Forms/Sending_forms_through_JavaScript) -- [How to build custom form widgets](/en-US/docs/Learn_web_development/Extensions/Forms/How_to_build_custom_form_controls) -- **HTML forms in legacy browsers** -- [Advanced styling for HTML forms](/en-US/docs/Learn_web_development/Extensions/Forms/Advanced_form_styling) diff --git a/files/en-us/learn_web_development/extensions/forms/index.md b/files/en-us/learn_web_development/extensions/forms/index.md index 96c211641f3be51..6f523f1d8a938ec 100644 --- a/files/en-us/learn_web_development/extensions/forms/index.md +++ b/files/en-us/learn_web_development/extensions/forms/index.md @@ -2,10 +2,9 @@ title: Web forms slug: Learn_web_development/Extensions/Forms page-type: learn-module +sidebar: learnsidebar --- -{{LearnSidebar}} - {{NextMenu("Learn_web_development/Extensions/Forms/Your_first_form", "Learn_web_development/Extensions")}} This module provides a series of articles that will help you master the essentials of web forms. Web forms are a very powerful tool for interacting with users — most commonly they are used for collecting data from users, or allowing them to control a user interface. However, for historical and technical reasons, it's not always obvious how to use them to their full potential. In the articles listed below, we'll cover all the essential aspects of Web forms including marking up their HTML structure, styling form controls, validating form data, and submitting data to the server. @@ -43,6 +42,8 @@ The above text is a good indicator as to why we've put web forms into its own st - : This article provides an introduction to styling forms with CSS, including all the basics you might need to know for basic styling tasks. - [Advanced form styling](/en-US/docs/Learn_web_development/Extensions/Forms/Advanced_form_styling) - : Here we look at some more advanced form styling techniques that need to be used when trying to deal with some of the more difficult-to-style form elements. +- [Customizable select elements](/en-US/docs/Learn_web_development/Extensions/Forms/Customizable_select) + - : This article explains how to use dedicated, modern HTML and CSS features together to create fully-customized `<select>` elements. This includes having full control over styling the select button, drop-down picker, arrow icon, current selection checkmark, and each individual `<option>` element. - [UI pseudo-classes](/en-US/docs/Learn_web_development/Extensions/Forms/UI_pseudo-classes) - : An introduction to the UI pseudo-classes enabling HTML form controls to be targeted based on their current state. @@ -53,20 +54,22 @@ The above text is a good indicator as to why we've put web forms into its own st - [Sending form data](/en-US/docs/Learn_web_development/Extensions/Forms/Sending_and_retrieving_form_data) - : This article looks at what happens when a user submits a form — where does the data go, and how do we handle it when it gets there? We also look at some of the security concerns associated with sending form data. -## Advanced articles +## Additional articles The following articles aren't included in the learning pathway, but they'll prove interesting and useful when you've mastered the above techniques and want to know more. - [How to build custom form controls](/en-US/docs/Learn_web_development/Extensions/Forms/How_to_build_custom_form_controls) - - : You'll come across some cases where the native form widgets just don't provide what you need, e.g. because of styling or functionality. In such cases, you may need to build your own form widget out of raw HTML. This article explains how you'd do this and the considerations you need to be aware of when doing so, with a practical case study. + - : You'll come across some cases where the native form widgets just don't provide what you need, e.g., because of styling or functionality. In such cases, you may need to build your own form widget out of raw HTML. This article explains how you'd do this and the considerations you need to be aware of when doing so, with a practical case study. - [Sending forms through JavaScript](/en-US/docs/Learn_web_development/Extensions/Forms/Sending_forms_through_JavaScript) - : This article looks at ways to use a form to assemble an HTTP request and send it via custom JavaScript, rather than standard form submission. It also looks at why you'd want to do this, and the implications of doing so. (See also [Using FormData objects](/en-US/docs/Web/API/XMLHttpRequest_API/Using_FormData_Objects).) +- [Customizable select elements](/en-US/docs/Learn_web_development/Extensions/Forms/Customizable_select) + - : This article explains how to use dedicated, modern HTML and CSS features together to create fully-customized {{htmlelement("select")}} elements. ## See also -- [HTML forms element reference](/en-US/docs/Web/HTML/Element#forms) -- [HTML \<input> types reference](/en-US/docs/Web/HTML/Element/input) -- [HTML attribute reference](/en-US/docs/Web/HTML/Attributes) +- [HTML forms element reference](/en-US/docs/Web/HTML/Reference/Elements#forms) +- [HTML \<input> types reference](/en-US/docs/Web/HTML/Reference/Elements/input) +- [HTML attribute reference](/en-US/docs/Web/HTML/Reference/Attributes) - [User input methods and controls](/en-US/docs/Learn_web_development/Extensions/Forms/User_input_methods) {{NextMenu("Learn_web_development/Extensions/Forms/Your_first_form", "Learn_web_development/Extensions")}} diff --git a/files/en-us/learn_web_development/extensions/forms/other_form_controls/index.md b/files/en-us/learn_web_development/extensions/forms/other_form_controls/index.md index 929bfca1c1cebd6..3fe8d74bbee5d00 100644 --- a/files/en-us/learn_web_development/extensions/forms/other_form_controls/index.md +++ b/files/en-us/learn_web_development/extensions/forms/other_form_controls/index.md @@ -2,9 +2,10 @@ title: Other form controls slug: Learn_web_development/Extensions/Forms/Other_form_controls page-type: learn-module-chapter +sidebar: learnsidebar --- -{{LearnSidebar}}{{PreviousMenuNext("Learn_web_development/Extensions/Forms/HTML5_input_types","Learn_web_development/Extensions/Forms/Styling_web_forms", "Learn_web_development/Extensions/Forms")}} +{{PreviousMenuNext("Learn_web_development/Extensions/Forms/HTML5_input_types","Learn_web_development/Extensions/Forms/Styling_web_forms", "Learn_web_development/Extensions/Forms")}} We now look at the functionality of non-`<input>` form elements in detail, from other control types such as drop-down lists and multi-line text fields, to other useful form features such as the {{htmlelement('output')}} element (which we saw in action in the previous article), and progress bars. @@ -41,11 +42,11 @@ This renders like so: {{EmbedLiveSample("Multi-line_text_fields", 120, 160)}} -The main difference between a `<textarea>` and a regular single-line text field is that users are allowed to include hard line breaks (i.e. pressing return) that will be included when the data is submitted. +The main difference between a `<textarea>` and a regular single-line text field is that users are allowed to include hard line breaks (i.e., pressing return) that will be included when the data is submitted. -`<textarea>` also takes a closing tag; any default text you want it to contain should be put between the opening and closing tags. In contrast, the {{HTMLElement("input")}} is a {{glossary("void element")}} with no closing tag — any default value is put inside the [`value`](/en-US/docs/Web/HTML/Element/input#value) attribute. +`<textarea>` also takes a closing tag; any default text you want it to contain should be put between the opening and closing tags. In contrast, the {{HTMLElement("input")}} is a {{glossary("void element")}} with no closing tag — any default value is put inside the [`value`](/en-US/docs/Web/HTML/Reference/Elements/input#value) attribute. -Note that even though you can put anything inside a `<textarea>` element (including other HTML elements, CSS, and JavaScript), because of its nature, it is all rendered as if it was plain text content. (Using [`contenteditable`](/en-US/docs/Web/HTML/Global_attributes/contenteditable) on non-form controls provides an API for capturing HTML/"rich" content instead of plain text). +Note that even though you can put anything inside a `<textarea>` element (including other HTML elements, CSS, and JavaScript), because of its nature, it is all rendered as if it was plain text content. (Using [`contenteditable`](/en-US/docs/Web/HTML/Reference/Global_attributes/contenteditable) on non-form controls provides an API for capturing HTML/"rich" content instead of plain text). Visually, the text entered wraps and the form control is by default resizable. Most browsers provide a drag handle that you can drag to increase/decrease the size of the text area. @@ -55,11 +56,11 @@ You can find an example of text area usage in the [example](https://mdn.github.i {{htmlelement("textarea")}} accepts three attributes to control its rendering across several lines: -- [`cols`](/en-US/docs/Web/HTML/Element/textarea#cols) +- [`cols`](/en-US/docs/Web/HTML/Reference/Elements/textarea#cols) - : Specifies the visible width (columns) of the text control, measured in average character widths. This is effectively the starting width, as it can be changed by resizing the `<textarea>`, and overridden using CSS. The default value if none is specified is 20. -- [`rows`](/en-US/docs/Web/HTML/Element/textarea#rows) +- [`rows`](/en-US/docs/Web/HTML/Reference/Elements/textarea#rows) - : Specifies the number of visible text rows for the control. This is effectively the starting height, as it can be changed by resizing the `<textarea>`, and overridden using CSS. The default value if none is specified is 2. -- [`wrap`](/en-US/docs/Web/HTML/Element/textarea#wrap) +- [`wrap`](/en-US/docs/Web/HTML/Reference/Elements/textarea#wrap) - : Specifies how the control wraps text. The values are `soft` (the default value), which means the text submitted is not wrapped but the text rendered by the browser is wrapped; `hard` (the `cols` attribute must be specified when using this value), which means both the submitted and rendered texts are wrapped, and `off`, which stops wrapping. ### Controlling textarea resizability @@ -97,7 +98,7 @@ A simple select box is created with a {{HTMLElement("select")}} element with one {{EmbedLiveSample("Basic_example", 120, 120)}} -If required, the default value for the select box can be set using the [`selected`](/en-US/docs/Web/HTML/Element/option#selected) attribute on the desired {{HTMLElement("option")}} element — this option is then preselected when the page loads. +If required, the default value for the select box can be set using the [`selected`](/en-US/docs/Web/HTML/Reference/Elements/option#selected) attribute on the desired {{HTMLElement("option")}} element — this option is then preselected when the page loads. #### Using optgroup @@ -120,7 +121,7 @@ The {{HTMLElement("option")}} elements can be nested inside {{HTMLElement("optgr {{EmbedLiveSample("Using_optgroup", 120, 120)}} -On the {{HTMLElement("optgroup")}} element, the value of the [`label`](/en-US/docs/Web/HTML/Element/optgroup#label) attribute is displayed before the values of the nested options. The browser usually sets them visually apart from the options (i.e. by being bolded and at a different nesting level) so they are less likely to be confused for actual options. +On the {{HTMLElement("optgroup")}} element, the value of the [`label`](/en-US/docs/Web/HTML/Reference/Elements/optgroup#label) attribute is displayed before the values of the nested options. The browser usually sets them visually apart from the options (i.e., by being bolded and at a different nesting level) so they are less likely to be confused for actual options. #### Using the value attribute @@ -136,11 +137,11 @@ For example: </select> ``` -By default, the height of the select box is enough to display a single value. The optional [`size`](/en-US/docs/Web/HTML/Attributes/size) attribute provides control over how many options are visible when the select does not have focus. +By default, the height of the select box is enough to display a single value. The optional [`size`](/en-US/docs/Web/HTML/Reference/Attributes/size) attribute provides control over how many options are visible when the select does not have focus. ### Multiple choice select box -By default, a select box lets a user select only one value. By adding the [`multiple`](/en-US/docs/Web/HTML/Element/select#multiple) attribute to the {{HTMLElement("select")}} element, you can allow users to select several values. Users can select multiple values by using the default mechanism provided by the operating system (e.g., on the desktop, multiple values can be clicked while holding down <kbd>Cmd</kbd>/<kbd>Ctrl</kbd> keys). +By default, a select box lets a user select only one value. By adding the [`multiple`](/en-US/docs/Web/HTML/Reference/Elements/select#multiple) attribute to the {{HTMLElement("select")}} element, you can allow users to select several values. Users can select multiple values by using the default mechanism provided by the operating system (e.g., on the desktop, multiple values can be clicked while holding down <kbd>Cmd</kbd>/<kbd>Ctrl</kbd> keys). ```html <select id="multi" name="multi" multiple size="2"> @@ -160,16 +161,16 @@ By default, a select box lets a user select only one value. By adding the [`mult {{EmbedLiveSample("Multiple_choice_select_box", 120, 120)}} > [!NOTE] -> In the case of multiple choice select boxes, you'll notice that the select box no longer displays the values as drop-down content — instead, all values are displayed at once in a list, with the optional [`size`](/en-US/docs/Web/HTML/Attributes/size) attribute determining the height of the widget. +> In the case of multiple choice select boxes, you'll notice that the select box no longer displays the values as drop-down content — instead, all values are displayed at once in a list, with the optional [`size`](/en-US/docs/Web/HTML/Reference/Attributes/size) attribute determining the height of the widget. > [!NOTE] -> All browsers that support the {{HTMLElement("select")}} element also support the [`multiple`](/en-US/docs/Web/HTML/Element/select#multiple) attribute. +> All browsers that support the {{HTMLElement("select")}} element also support the [`multiple`](/en-US/docs/Web/HTML/Reference/Elements/select#multiple) attribute. ### Autocomplete box You can provide suggested, automatically-completed values for form widgets using the {{HTMLElement("datalist")}} element with child {{HTMLElement("option")}} elements to specify the values to display. The `<datalist>` needs to be given an `id`. -The data list is then bound to an {{htmlelement("input")}} element (e.g. a `text` or `email` input type) using the [`list`](/en-US/docs/Web/HTML/Element/input#list) attribute, the value of which is the `id` of the data list to bind. +The data list is then bound to an {{htmlelement("input")}} element (e.g., a `text` or `email` input type) using the [`list`](/en-US/docs/Web/HTML/Reference/Elements/input#list) attribute, the value of which is the `id` of the data list to bind. Once a data list is affiliated with a form widget, its options are used to auto-complete text entered by the user; typically, this is presented to the user as a drop-down box listing possible matches for what they've typed into the input. @@ -196,11 +197,11 @@ Let's look at an example. #### Less obvious datalist uses -According to [the HTML specification](https://html.spec.whatwg.org/multipage/input.html#attr-input-list), the [`list`](/en-US/docs/Web/HTML/Element/input#list) attribute and the {{HTMLElement("datalist")}} element can be used with any kind of widget requiring a user input. This leads to some uses of it that might seem a little non-obvious. +According to [the HTML specification](https://html.spec.whatwg.org/multipage/input.html#attr-input-list), the [`list`](/en-US/docs/Web/HTML/Reference/Elements/input#list) attribute and the {{HTMLElement("datalist")}} element can be used with any kind of widget requiring a user input. This leads to some uses of it that might seem a little non-obvious. -For example, in browsers that support `{{htmlelement("datalist")}}` on `range` input types, a small tick mark will be displayed above the range for each datalist `{{htmlelement("option")}}` value. You can see an implementation [example of this on the `<input type="range">` reference page](/en-US/docs/Web/HTML/Element/input/range#adding_tick_marks). +For example, in browsers that support `{{htmlelement("datalist")}}` on `range` input types, a small tick mark will be displayed above the range for each datalist `{{htmlelement("option")}}` value. You can see an implementation [example of this on the `<input type="range">` reference page](/en-US/docs/Web/HTML/Reference/Elements/input/range#adding_tick_marks). -And browsers that support {{htmlelement('datalist')}}s and [`<input type="color">`](/en-US/docs/Web/HTML/Element/input/color) should display a customized palette of colors as the default, while still making the full color palette available. +And browsers that support {{htmlelement('datalist')}}s and [`<input type="color">`](/en-US/docs/Web/HTML/Reference/Elements/input/color) should display a customized palette of colors as the default, while still making the full color palette available. In this case, different browsers behave differently from case to case, so consider such uses as progressive enhancement, and ensure they degrade gracefully. @@ -217,19 +218,19 @@ Meters and progress bars are visual representations of numeric values. Support f #### Meter -A meter bar represents a fixed value in a range delimited by [`max`](/en-US/docs/Web/HTML/Element/meter#max) and [`min`](/en-US/docs/Web/HTML/Element/meter#min) values. This value is visually rendered as a bar, and to know how this bar looks, we compare the value to some other set values: +A meter bar represents a fixed value in a range delimited by [`max`](/en-US/docs/Web/HTML/Reference/Elements/meter#max) and [`min`](/en-US/docs/Web/HTML/Reference/Elements/meter#min) values. This value is visually rendered as a bar, and to know how this bar looks, we compare the value to some other set values: -- The [`low`](/en-US/docs/Web/HTML/Element/meter#low) and [`high`](/en-US/docs/Web/HTML/Element/meter#high) values divide the range into the following three parts: +- The [`low`](/en-US/docs/Web/HTML/Reference/Elements/meter#low) and [`high`](/en-US/docs/Web/HTML/Reference/Elements/meter#high) values divide the range into the following three parts: - - The lower part of the range is between the [`min`](/en-US/docs/Web/HTML/Element/meter#min) and [`low`](/en-US/docs/Web/HTML/Element/meter#low) values, inclusive. - - The medium part of the range is between the [`low`](/en-US/docs/Web/HTML/Element/meter#low) and [`high`](/en-US/docs/Web/HTML/Element/meter#high) values, exclusive. - - The higher part of the range is between the [`high`](/en-US/docs/Web/HTML/Element/meter#high) and [`max`](/en-US/docs/Web/HTML/Element/meter#max) values, inclusive. + - The lower part of the range is between the [`min`](/en-US/docs/Web/HTML/Reference/Elements/meter#min) and [`low`](/en-US/docs/Web/HTML/Reference/Elements/meter#low) values, inclusive. + - The medium part of the range is between the [`low`](/en-US/docs/Web/HTML/Reference/Elements/meter#low) and [`high`](/en-US/docs/Web/HTML/Reference/Elements/meter#high) values, exclusive. + - The higher part of the range is between the [`high`](/en-US/docs/Web/HTML/Reference/Elements/meter#high) and [`max`](/en-US/docs/Web/HTML/Reference/Elements/meter#max) values, inclusive. -- The [`optimum`](/en-US/docs/Web/HTML/Element/meter#optimum) value defines the optimum value for the {{HTMLElement("meter")}} element. In conjunction with the [`low`](/en-US/docs/Web/HTML/Element/meter#low) and [`high`](/en-US/docs/Web/HTML/Element/meter#high) value, it defines which part of the range is preferred: +- The [`optimum`](/en-US/docs/Web/HTML/Reference/Elements/meter#optimum) value defines the optimum value for the {{HTMLElement("meter")}} element. In conjunction with the [`low`](/en-US/docs/Web/HTML/Reference/Elements/meter#low) and [`high`](/en-US/docs/Web/HTML/Reference/Elements/meter#high) value, it defines which part of the range is preferred: - - If the [`optimum`](/en-US/docs/Web/HTML/Element/meter#optimum) value is in the lower part of the range, the lower range is considered to be the preferred part, the medium range is considered to be the average part, and the higher range is considered to be the worst part. - - If the [`optimum`](/en-US/docs/Web/HTML/Element/meter#optimum) value is in the medium part of the range, the lower range is considered to be an average part, the medium range is considered to be the preferred part, and the higher range is considered to be average as well. - - If the [`optimum`](/en-US/docs/Web/HTML/Element/meter#optimum) value is in the higher part of the range, the lower range is considered to be the worst part, the medium range is considered to be the average part and the higher range is considered to be the preferred part. + - If the [`optimum`](/en-US/docs/Web/HTML/Reference/Elements/meter#optimum) value is in the lower part of the range, the lower range is considered to be the preferred part, the medium range is considered to be the average part, and the higher range is considered to be the worst part. + - If the [`optimum`](/en-US/docs/Web/HTML/Reference/Elements/meter#optimum) value is in the medium part of the range, the lower range is considered to be an average part, the medium range is considered to be the preferred part, and the higher range is considered to be average as well. + - If the [`optimum`](/en-US/docs/Web/HTML/Reference/Elements/meter#optimum) value is in the higher part of the range, the lower range is considered to be the worst part, the medium range is considered to be the average part and the higher range is considered to be the preferred part. All browsers that implement the {{HTMLElement("meter")}} element use those values to change the color of the meter bar: @@ -249,7 +250,7 @@ The content inside the {{HTMLElement("meter")}} element is a fallback for browse #### Progress -A progress bar represents a value that changes over time up to a maximum value specified by the [`max`](/en-US/docs/Web/HTML/Element/progress#max) attribute. Such a bar is created using a {{ HTMLElement("progress")}} element. +A progress bar represents a value that changes over time up to a maximum value specified by the [`max`](/en-US/docs/Web/HTML/Reference/Elements/progress#max) attribute. Such a bar is created using a {{ HTMLElement("progress")}} element. ```html <progress max="100" value="75">75/100</progress> @@ -263,7 +264,7 @@ The content inside the {{HTMLElement("progress")}} element is a fallback for bro ## Test your skills! -You've reached the end of this article, but can you remember the most important information? You can find some further tests to verify that you've retained this information before you move on — see [Test your skills: Other controls](/en-US/docs/Learn_web_development/Extensions/Forms/Test_your_skills:_Other_controls). +You've reached the end of this article, but can you remember the most important information? You can find some further tests to verify that you've retained this information before you move on — see [Test your skills: Other controls](/en-US/docs/Learn_web_development/Extensions/Forms/Test_your_skills/Other_controls). ## Summary @@ -272,8 +273,3 @@ As you'll have seen in the last few articles, there are many types of form contr Now that you have a grasp of the HTML behind the different available form controls, we'll take a look at [Styling them](/en-US/docs/Learn_web_development/Extensions/Forms/Styling_web_forms). {{PreviousMenuNext("Learn_web_development/Extensions/Forms/HTML5_input_types","Learn_web_development/Extensions/Forms/Styling_web_forms", "Learn_web_development/Extensions/Forms")}} - -### Advanced Topics - -- [How to build custom form controls](/en-US/docs/Learn_web_development/Extensions/Forms/How_to_build_custom_form_controls) -- [Sending forms through JavaScript](/en-US/docs/Learn_web_development/Extensions/Forms/Sending_forms_through_JavaScript) diff --git a/files/en-us/learn_web_development/extensions/forms/sending_and_retrieving_form_data/index.md b/files/en-us/learn_web_development/extensions/forms/sending_and_retrieving_form_data/index.md index b3ccc1bc0a4ced0..25da7a708bea6b7 100644 --- a/files/en-us/learn_web_development/extensions/forms/sending_and_retrieving_form_data/index.md +++ b/files/en-us/learn_web_development/extensions/forms/sending_and_retrieving_form_data/index.md @@ -2,9 +2,10 @@ title: Sending form data slug: Learn_web_development/Extensions/Forms/Sending_and_retrieving_form_data page-type: learn-module-chapter +sidebar: learnsidebar --- -{{LearnSidebar}}{{PreviousMenu("Learn_web_development/Extensions/Forms/Form_validation", "Learn_web_development/Extensions/Forms")}} +{{PreviousMenu("Learn_web_development/Extensions/Forms/Form_validation", "Learn_web_development/Extensions/Forms")}} Once the form data has been validated on the client-side, it is okay to submit the form. And, since we covered validation in the previous article, we're ready to submit! This article looks at what happens when a user submits a form — where does the data go, and how do we handle it when it gets there? We also look at some of the security concerns associated with sending form data. @@ -48,11 +49,11 @@ An HTML form on a web page is nothing more than a convenient user-friendly way t ## On the client side: defining how to send the data -The {{HTMLElement("form")}} element defines how the data will be sent. All of its attributes are designed to let you configure the request to be sent when a user hits a {{Glossary("submit button")}}. The two most important attributes are [`action`](/en-US/docs/Web/HTML/Element/form#action) and [`method`](/en-US/docs/Web/HTML/Element/form#method). +The {{HTMLElement("form")}} element defines how the data will be sent. All of its attributes are designed to let you configure the request to be sent when a user hits a {{Glossary("submit button")}}. The two most important attributes are [`action`](/en-US/docs/Web/HTML/Reference/Elements/form#action) and [`method`](/en-US/docs/Web/HTML/Reference/Elements/form#method). ### The action attribute -The [`action`](/en-US/docs/Web/HTML/Element/form#action) attribute defines where the data gets sent. Its value must be a valid relative or absolute [URL](/en-US/docs/Learn_web_development/Howto/Web_mechanics/What_is_a_URL). If this attribute isn't provided, the data will be sent to the URL of the page containing the form — the current page. +The [`action`](/en-US/docs/Web/HTML/Reference/Elements/form#action) attribute defines where the data gets sent. Its value must be a valid relative or absolute [URL](/en-US/docs/Learn_web_development/Howto/Web_mechanics/What_is_a_URL). If this attribute isn't provided, the data will be sent to the URL of the page containing the form — the current page. In this example, the data is sent to an absolute URL — `https://example.com`: @@ -73,7 +74,7 @@ When specified with no attributes, as below, the {{HTMLElement("form")}} data is ``` > [!NOTE] -> It's possible to specify a URL that uses the HTTPS (secure HTTP) protocol. When you do this, the data is encrypted along with the rest of the request, even if the form itself is hosted on an insecure page accessed using HTTP. On the other hand, if the form is hosted on a secure page but you specify an insecure HTTP URL with the [`action`](/en-US/docs/Web/HTML/Element/form#action) attribute, all browsers display a security warning to the user each time they try to send data because the data will not be encrypted. +> It's possible to specify a URL that uses the HTTPS (secure HTTP) protocol. When you do this, the data is encrypted along with the rest of the request, even if the form itself is hosted on an insecure page accessed using HTTP. On the other hand, if the form is hosted on a secure page but you specify an insecure HTTP URL with the [`action`](/en-US/docs/Web/HTML/Reference/Elements/form#action) attribute, all browsers display a security warning to the user each time they try to send data because the data will not be encrypted. The names and values of the non-file form controls are sent to the server as `name=value` pairs joined with ampersands. The `action` value should be a file on the server that can handle the incoming data, including ensuring server-side validation. The server then responds, generally handling the data and loading the URL defined by the `action` attribute, causing a new page load (or a refresh of the existing page, if the `action` points to the same page). @@ -81,13 +82,13 @@ How the data is sent depends on the `method` attribute. ### The method attribute -The [`method`](/en-US/docs/Web/HTML/Element/form#method) attribute defines how data is sent. The [HTTP protocol](/en-US/docs/Web/HTTP) provides several ways to perform a request; HTML form data can be transmitted via a number of different methods, the most common being the `GET` method and the `POST` method +The [`method`](/en-US/docs/Web/HTML/Reference/Elements/form#method) attribute defines how data is sent. The [HTTP protocol](/en-US/docs/Web/HTTP) provides several ways to perform a request; HTML form data can be transmitted via a number of different methods, the most common being the `GET` method and the `POST` method -To understand the difference between those two methods, let's step back and examine [how HTTP works](/en-US/docs/Web/HTTP/Overview). Each time you want to reach a resource on the Web, the browser sends a request to a URL. An HTTP request consists of two parts: a [header](/en-US/docs/Web/HTTP/Headers) that contains a set of global metadata about the browser's capabilities, and a body that can contain information necessary for the server to process the specific request. +To understand the difference between those two methods, let's step back and examine [how HTTP works](/en-US/docs/Web/HTTP/Guides/Overview). Each time you want to reach a resource on the Web, the browser sends a request to a URL. An HTTP request consists of two parts: a [header](/en-US/docs/Web/HTTP/Reference/Headers) that contains a set of global metadata about the browser's capabilities, and a body that can contain information necessary for the server to process the specific request. #### The GET method -The [`GET` method](/en-US/docs/Web/HTTP/Methods/GET) is the method used by the browser to ask the server to send back a given resource: "Hey server, I want to get this resource." In this case, the browser sends an empty body. Because the body is empty, if a form is sent using this method the data sent to the server is appended to the URL. +The [`GET` method](/en-US/docs/Web/HTTP/Reference/Methods/GET) is the method used by the browser to ask the server to send back a given resource: "Hey server, I want to get this resource." In this case, the browser sends an empty body. Because the body is empty, if a form is sent using this method the data sent to the server is appended to the URL. Consider the following form: @@ -127,13 +128,13 @@ Host: foo.com > You can find this example on GitHub — see [get-method.html](https://github.com/mdn/learning-area/blob/main/html/forms/sending-form-data/get-method.html) ([see it live also](https://mdn.github.io/learning-area/html/forms/sending-form-data/get-method.html)). > [!NOTE] -> The data will not be appended if the `action` URL scheme cannot handle queries, e.g. `file:`. +> The data will not be appended if the `action` URL scheme cannot handle queries, e.g., `file:`. #### The POST method -The [`POST` method](/en-US/docs/Web/HTTP/Methods/POST) is a little different. It's the method the browser uses to talk to the server when asking for a response that takes into account the data provided in the body of the HTTP request: "Hey server, take a look at this data and send me back an appropriate result." If a form is sent using this method, the data is appended to the body of the HTTP request. +The [`POST` method](/en-US/docs/Web/HTTP/Reference/Methods/POST) is a little different. It's the method the browser uses to talk to the server when asking for a response that takes into account the data provided in the body of the HTTP request: "Hey server, take a look at this data and send me back an appropriate result." If a form is sent using this method, the data is appended to the body of the HTTP request. -Let's look at an example — this is the same form we looked at in the `GET` section above, but with the [`method`](/en-US/docs/Web/HTML/Element/form#method) attribute set to `POST`. +Let's look at an example — this is the same form we looked at in the `GET` section above, but with the [`method`](/en-US/docs/Web/HTML/Reference/Elements/form#method) attribute set to `POST`. ```html <form action="http://www.foo.com" method="POST"> @@ -168,7 +169,7 @@ The `Content-Length` header indicates the size of the body, and the `Content-Typ > You can find this example on GitHub — see [post-method.html](https://github.com/mdn/learning-area/blob/main/html/forms/sending-form-data/post-method.html) ([see it live also](https://mdn.github.io/learning-area/html/forms/sending-form-data/post-method.html)). > [!NOTE] -> The `GET` method will be used instead if the `action` URL scheme cannot handle a request body, e.g. `data:`. +> The `GET` method will be used instead if the `action` URL scheme cannot handle a request body, e.g., `data:`. ### Viewing HTTP requests @@ -201,10 +202,10 @@ Whichever HTTP method you choose, the server receives a string that will be pars <?php // The global $_POST variable allows you to access the data sent with the POST method by name // To access the data sent with the GET method, you can use $_GET - $say = htmlspecialchars($_POST['say']); - $to = htmlspecialchars($_POST['to']); + $say = htmlspecialchars($_POST["say"]); + $to = htmlspecialchars($_POST["to"]); - echo $say, ' ', $to; + echo $say, " ", $to; ?> ``` @@ -284,9 +285,9 @@ This attribute lets you specify the value of the `Content-Type` HTTP header incl If you want to send files, you need to take three extra steps: -- Set the [`method`](/en-US/docs/Web/HTML/Element/form#method) attribute to `POST` because file content can't be put inside URL parameters. -- Set the value of [`enctype`](/en-US/docs/Web/HTML/Element/form#enctype) to `multipart/form-data` because the data will be split into multiple parts, one for each file plus one for the text data included in the form body (if the text is also entered into the form). -- Include one or more [`<input type="file">`](/en-US/docs/Web/HTML/Element/input/file) controls to allow your users to select the file(s) that will be uploaded. +- Set the [`method`](/en-US/docs/Web/HTML/Reference/Elements/form#method) attribute to `POST` because file content can't be put inside URL parameters. +- Set the value of [`enctype`](/en-US/docs/Web/HTML/Reference/Elements/form#enctype) to `multipart/form-data` because the data will be split into multiple parts, one for each file plus one for the text data included in the form body (if the text is also entered into the form). +- Include one or more [`<input type="file">`](/en-US/docs/Web/HTML/Reference/Elements/input/file) controls to allow your users to select the file(s) that will be uploaded. For example: @@ -338,8 +339,3 @@ If you want to learn more about securing a web application, you can dig into the - [Web Security by Mozilla](https://infosec.mozilla.org/guidelines/web_security) {{PreviousMenu("Learn_web_development/Extensions/Forms/Form_validation", "Learn_web_development/Extensions/Forms")}} - -### Advanced Topics - -- [How to build custom form controls](/en-US/docs/Learn_web_development/Extensions/Forms/How_to_build_custom_form_controls) -- [Sending forms through JavaScript](/en-US/docs/Learn_web_development/Extensions/Forms/Sending_forms_through_JavaScript) diff --git a/files/en-us/learn_web_development/extensions/forms/sending_forms_through_javascript/index.md b/files/en-us/learn_web_development/extensions/forms/sending_forms_through_javascript/index.md index 871297bbcdd2932..c2e8561eabc7fb5 100644 --- a/files/en-us/learn_web_development/extensions/forms/sending_forms_through_javascript/index.md +++ b/files/en-us/learn_web_development/extensions/forms/sending_forms_through_javascript/index.md @@ -2,10 +2,9 @@ title: Sending forms through JavaScript slug: Learn_web_development/Extensions/Forms/Sending_forms_through_JavaScript page-type: learn-module-chapter +sidebar: learnsidebar --- -{{LearnSidebar}} - When a user submits an HTML form, for example by clicking the {{glossary("Submit_button", "submit button")}}, the browser makes an [HTTP](/en-US/docs/Web/HTTP) request to send the data in the form. But instead of this declarative approach, web apps sometimes use JavaScript APIs such as {{domxref("Window/fetch", "fetch()")}} to send data programmatically to an endpoint that expects a form submission. This article explains why this is an important use case and how to do it. ## Why use JavaScript to submit form data? @@ -122,24 +121,3 @@ form.addEventListener("submit", (event) => { We add a submit event handler for the form element. This first calls {{domxref("Event.preventDefault()", "preventDefault()")}} to prevent the browser's built-in form submission, so we can take over. Then we call `sendData()`, which retrieves the form element and passes it into the `FormData` constructor. After that, we send the `FormData` instance as an HTTP `POST` request, using `fetch()`. - -## See also - -### Learning path - -- [Your first HTML form](/en-US/docs/Learn_web_development/Extensions/Forms/Your_first_form) -- [How to structure an HTML form](/en-US/docs/Learn_web_development/Extensions/Forms/How_to_structure_a_web_form) -- [The native form widgets](/en-US/docs/Learn_web_development/Extensions/Forms/Basic_native_form_controls) -- [HTML5 input types](/en-US/docs/Learn_web_development/Extensions/Forms/HTML5_input_types) -- [Additional form controls](/en-US/docs/Learn_web_development/Extensions/Forms/Other_form_controls) -- [UI pseudo-classes](/en-US/docs/Learn_web_development/Extensions/Forms/UI_pseudo-classes) -- [Styling HTML forms](/en-US/docs/Learn_web_development/Extensions/Forms/Styling_web_forms) -- [Form data validation](/en-US/docs/Learn_web_development/Extensions/Forms/Form_validation) -- [Sending form data](/en-US/docs/Learn_web_development/Extensions/Forms/Sending_and_retrieving_form_data) - -### Advanced Topics - -- **Sending forms through JavaScript** -- [How to build custom form widgets](/en-US/docs/Learn_web_development/Extensions/Forms/How_to_build_custom_form_controls) -- [HTML forms in legacy browsers](/en-US/docs/Learn_web_development/Extensions/Forms/HTML_forms_in_legacy_browsers) -- [Advanced styling for HTML forms](/en-US/docs/Learn_web_development/Extensions/Forms/Advanced_form_styling) diff --git a/files/en-us/learn_web_development/extensions/forms/styling_web_forms/background.jpg b/files/en-us/learn_web_development/extensions/forms/styling_web_forms/background.jpg deleted file mode 100644 index 86828bbcd47df99..000000000000000 Binary files a/files/en-us/learn_web_development/extensions/forms/styling_web_forms/background.jpg and /dev/null differ diff --git a/files/en-us/learn_web_development/extensions/forms/styling_web_forms/index.md b/files/en-us/learn_web_development/extensions/forms/styling_web_forms/index.md index 26493b32f41e675..f3c1f3a831669ab 100644 --- a/files/en-us/learn_web_development/extensions/forms/styling_web_forms/index.md +++ b/files/en-us/learn_web_development/extensions/forms/styling_web_forms/index.md @@ -2,9 +2,10 @@ title: Styling web forms slug: Learn_web_development/Extensions/Forms/Styling_web_forms page-type: learn-module-chapter +sidebar: learnsidebar --- -{{LearnSidebar}}{{PreviousMenuNext("Learn_web_development/Extensions/Forms/Other_form_controls","Learn_web_development/Extensions/Forms/Advanced_form_styling","Learn_web_development/Extensions/Forms")}} +{{PreviousMenuNext("Learn_web_development/Extensions/Forms/Other_form_controls","Learn_web_development/Extensions/Forms/Advanced_form_styling","Learn_web_development/Extensions/Forms")}} In the previous few articles, we showed how to create web forms in HTML. Now, we'll show how to style them in [CSS](/en-US/docs/Web/CSS). @@ -42,7 +43,7 @@ Even with CSS available, browser vendors were reluctant at first to make form el 1. {{HTMLElement("form")}} 2. {{HTMLElement("fieldset")}} and {{HTMLElement("legend")}} -3. Single-line text {{HTMLElement("input")}}s (e.g. type text, url, email), except for [`<input type="search">`](/en-US/docs/Web/HTML/Element/input/search). +3. Single-line text {{HTMLElement("input")}}s (e.g., type text, url, email), except for [`<input type="search">`](/en-US/docs/Web/HTML/Reference/Elements/input/search). 4. Multi-line {{HTMLElement("textarea")}} 5. Buttons (both {{HTMLElement("input")}} and {{HTMLElement("button")}}) 6. {{HTMLElement("label")}} @@ -51,17 +52,19 @@ Even with CSS available, browser vendors were reluctant at first to make form el #### Harder-to-style - Checkboxes and radio buttons -- [`<input type="search">`](/en-US/docs/Web/HTML/Element/input/search) +- [`<input type="search">`](/en-US/docs/Web/HTML/Reference/Elements/input/search) The article [Advanced form styling](/en-US/docs/Learn_web_development/Extensions/Forms/Advanced_form_styling) shows how to style these. #### Having internals can't be styled in CSS alone -- [`<input type="color">`](/en-US/docs/Web/HTML/Element/input/color) -- Date-related controls such as [`<input type="datetime-local">`](/en-US/docs/Web/HTML/Element/input/datetime-local) -- [`<input type="range">`](/en-US/docs/Web/HTML/Element/input/range) -- [`<input type="file">`](/en-US/docs/Web/HTML/Element/input/file) +- [`<input type="color">`](/en-US/docs/Web/HTML/Reference/Elements/input/color) +- Date-related controls such as [`<input type="datetime-local">`](/en-US/docs/Web/HTML/Reference/Elements/input/datetime-local) +- [`<input type="range">`](/en-US/docs/Web/HTML/Reference/Elements/input/range) +- [`<input type="file">`](/en-US/docs/Web/HTML/Reference/Elements/input/file) - Elements involved in creating dropdown widgets, including {{HTMLElement("select")}}, {{HTMLElement("option")}}, {{HTMLElement("optgroup")}} and {{HTMLElement("datalist")}}. + > [!NOTE] + > Some browsers now support [Customizable select elements](/en-US/docs/Learn_web_development/Extensions/Forms/Customizable_select), a set of HTML and CSS features that together enable full customization of `<select>` elements and their contents just like any regular DOM elements. - {{HTMLElement("progress")}} and {{HTMLElement("meter")}} For example, the date picker calendar, and the button on \<select> that displays an options list when clicked, can't be styled using CSS alone. @@ -375,15 +378,10 @@ And voilà! Your form should now look like this: ## Test your skills -You've reached the end of this article, but can you remember the most important information? You can find some further tests to verify that you've retained this information before you move on — see [Test your skills: Styling basics](/en-US/docs/Learn_web_development/Extensions/Forms/Test_your_skills:_Styling_basics). +You've reached the end of this article, but can you remember the most important information? You can find some further tests to verify that you've retained this information before you move on — see [Test your skills: Styling basics](/en-US/docs/Learn_web_development/Extensions/Forms/Test_your_skills/Styling_basics). ## Summary As you can see, as long as we want to build forms with just text fields and buttons, it's easy to style them using CSS. [In the next article](/en-US/docs/Learn_web_development/Extensions/Forms/Advanced_form_styling), we will see how to handle form widgets which fall into the "bad" and "ugly" categories. {{PreviousMenuNext("Learn_web_development/Extensions/Forms/Other_form_controls","Learn_web_development/Extensions/Forms/Advanced_form_styling","Learn_web_development/Extensions/Forms")}} - -### Advanced Topics - -- [How to build custom form controls](/en-US/docs/Learn_web_development/Extensions/Forms/How_to_build_custom_form_controls) -- [Sending forms through JavaScript](/en-US/docs/Learn_web_development/Extensions/Forms/Sending_forms_through_JavaScript) diff --git a/files/en-us/learn_web_development/extensions/forms/test_your_skills/advanced_styling/index.md b/files/en-us/learn_web_development/extensions/forms/test_your_skills/advanced_styling/index.md new file mode 100644 index 000000000000000..2239bf3f14fdcd2 --- /dev/null +++ b/files/en-us/learn_web_development/extensions/forms/test_your_skills/advanced_styling/index.md @@ -0,0 +1,67 @@ +--- +title: "Test your skills: Advanced styling" +short-title: Advanced styling +slug: Learn_web_development/Extensions/Forms/Test_your_skills/Advanced_styling +page-type: learn-module-assessment +sidebar: learnsidebar +--- + +The aim of this skill test is to assess whether you've understood our [Advanced form styling](/en-US/docs/Learn_web_development/Extensions/Forms/Advanced_form_styling) and [UI pseudo-classes](/en-US/docs/Learn_web_development/Extensions/Forms/UI_pseudo-classes) articles. + +> [!NOTE] +> You can try solutions in the interactive editors on this page or in an online editor such as [CodePen](https://codepen.io/), [JSFiddle](https://jsfiddle.net/), or [Glitch](https://glitch.com/). +> +> If you get stuck, you can reach out to us in one of our [communication channels](/en-US/docs/MDN/Community/Communication_channels). + +## Advanced form styling 1 + +In our first advanced styling tasks, we want you to handle making a search input as consistent as possible across browsers — a trickier task than with standard text inputs, even on modern browsers. + +We've already provided you with a basic reset to build upon. + +1. First of all, try giving the search box a consistent width, height, padding, and border color across browsers. +2. You'll find that some browsers will not behave in terms of the form element's height. This is due to native OS styling being used in some cases. How can you remove this native styling? +3. Once you've removed the native styling, you'll need to add back one of the features it was providing, to keep the same look and feel we originally had. How do you do this? +4. One thing that is inconsistent across browsers (particularly looking at Safari here) is the position of the standard blue focus outline. How can you remove this? +5. There is a major problem with just getting rid of the blue focus outline. What is it? Can you add some kind of styling back in so that users can tell when the search box is being hovered or focused? +6. Another thing that commonly denotes a search box is a magnifying glass icon. We've made one available in the same directory as our HTML files — see [search-24px.png](https://github.com/mdn/learning-area/blob/main/html/forms/tasks/advanced-styling/search-24px.png) — plus a `<div>` element after the search input to help you attach it, should you need it. Can you figure out a sensible way to attach it, and can you use some CSS to get it to sit to the right of the search box, and be lined up vertically as well? + +Try updating the live code below to recreate the finished example: + +{{EmbedGHLiveSample("learning-area/html/forms/tasks/advanced-styling/advanced-styling1.html", '100%', 700)}} + +> [!CALLOUT] +> +> [Download the starting point for this task](https://github.com/mdn/learning-area/blob/main/html/forms/tasks/advanced-styling/advanced-styling1-download.html) to work in your own editor or in an online editor. + +## Advanced form styling 2 + +In our next task we provide you with a set of three radio buttons. We want you to give them custom styling. + +We've already provided you with a basic reset to build upon. + +1. First of all, get rid of their default styling. +2. Next, give the radio buttons a reasonable base style — the style they have when the page first loads. This can be anything you like, but you probably want to set a width and height (of somewhere between about 18 and 24 pixels), and a subtle border and/or background color. +3. Now give the radio buttons a different style for when they are selected. +4. Align the radio buttons nicely with the labels. + +Try updating the live code below to recreate the finished example: + +{{EmbedGHLiveSample("learning-area/html/forms/tasks/advanced-styling/advanced-styling2.html", '100%', 700)}} + +> [!CALLOUT] +> +> [Download the starting point for this task](https://github.com/mdn/learning-area/blob/main/html/forms/tasks/advanced-styling/advanced-styling2-download.html) to work in your own editor or in an online editor. + +## Advanced form styling 3 + +In our final task for this assessment series, we provide you with a feedback form that is already nicely-styled — you've already seen something similar if you've worked through our [UI pseudo-classes](/en-US/docs/Learn_web_development/Extensions/Forms/UI_pseudo-classes) article, and now we want you to come up with your own solution. + +What we'd like you to do is make use of some advanced pseudo-classes to provide some useful indicators of validity. + +1. First of all, we want you to provide some specific styling to visually indicate which inputs have to be filled in — they cannot be left empty. +2. Second, we want you to provide a useful visual indicator of whether the data entered inside each input is valid or not. + +> [!CALLOUT] +> +> [Download the starting point for this task](https://github.com/mdn/learning-area/blob/main/html/forms/tasks/advanced-styling/advanced-styling3-download.html) to work in your own editor or in an online editor. diff --git a/files/en-us/learn_web_development/extensions/forms/test_your_skills/basic_controls/index.md b/files/en-us/learn_web_development/extensions/forms/test_your_skills/basic_controls/index.md new file mode 100644 index 000000000000000..0960146d7a11cc0 --- /dev/null +++ b/files/en-us/learn_web_development/extensions/forms/test_your_skills/basic_controls/index.md @@ -0,0 +1,63 @@ +--- +title: "Test your skills: Basic controls" +short-title: Basic controls +slug: Learn_web_development/Extensions/Forms/Test_your_skills/Basic_controls +page-type: learn-module-assessment +sidebar: learnsidebar +--- + +The aim of this skill test is to assess whether you've understood our [Basic native form controls](/en-US/docs/Learn_web_development/Extensions/Forms/Basic_native_form_controls) article. + +> [!NOTE] +> You can try solutions in the interactive editors on this page or in an online editor such as [CodePen](https://codepen.io/), [JSFiddle](https://jsfiddle.net/), or [Glitch](https://glitch.com/). +> +> If you get stuck, you can reach out to us in one of our [communication channels](/en-US/docs/MDN/Community/Communication_channels). + +## Basic controls 1 + +This task starts you off nice and gently by asking you to create two `<input>` elements, for a user's ID and password, along with a submit button. + +1. Create appropriate inputs for user ID and password. +2. You should also associate them with their text labels semantically. +3. Create a submit button inside the remaining list item, with button text of "Log in". + +Try updating the live code below to recreate the finished example: + +{{EmbedGHLiveSample("learning-area/html/forms/tasks/basic-controls/basic-controls1.html", '100%', 700)}} + +> [!CALLOUT] +> +> [Download the starting point for this task](https://github.com/mdn/learning-area/blob/main/html/forms/tasks/basic-controls/basic-controls1-download.html) to work in your own editor or in an online editor. + +## Basic controls 2 + +The next task requires you to create working sets of checkboxes and radio buttons, from the provided text labels. + +1. Turn the first `<fieldset>`'s contents into a set of radio buttons — you should only be able to select one pony character at once. +2. Make it so that the first radio button is selected upon page load. +3. Turn the second `<fieldset>`'s content into a set of checkboxes. +4. Add a couple more hotdog choices of your own. + +Try updating the live code below to recreate the finished example: + +{{EmbedGHLiveSample("learning-area/html/forms/tasks/basic-controls/basic-controls2.html", '100%', 700)}} + +> [!CALLOUT] +> +> [Download the starting point for this task](https://github.com/mdn/learning-area/blob/main/html/forms/tasks/basic-controls/basic-controls2-download.html) to work in your own editor or in an online editor. + +## Basic controls 3 + +The final task in this set requires you to create a file picker. + +1. Create a basic file picker. +2. Allow the user to pick multiple files at once. +3. Allow the file picker to accept JPG and PNG images only. + +Try updating the live code below to recreate the finished example: + +{{EmbedGHLiveSample("learning-area/html/forms/tasks/basic-controls/basic-controls3.html", '100%', 700)}} + +> [!CALLOUT] +> +> [Download the starting point for this task](https://github.com/mdn/learning-area/blob/main/html/forms/tasks/basic-controls/basic-controls3-download.html) to work in your own editor or in an online editor. diff --git a/files/en-us/learn_web_development/extensions/forms/test_your_skills/form_structure/index.md b/files/en-us/learn_web_development/extensions/forms/test_your_skills/form_structure/index.md new file mode 100644 index 000000000000000..9ac8e18cd4118fc --- /dev/null +++ b/files/en-us/learn_web_development/extensions/forms/test_your_skills/form_structure/index.md @@ -0,0 +1,28 @@ +--- +title: "Test your skills: Form structure" +short-title: Form structure +slug: Learn_web_development/Extensions/Forms/Test_your_skills/Form_structure +page-type: learn-module-assessment +sidebar: learnsidebar +--- + +The aim of this skill test is to assess whether you've understood our [How to structure a web form](/en-US/docs/Learn_web_development/Extensions/Forms/How_to_structure_a_web_form) article. + +> [!NOTE] +> You can try solutions in the interactive editors on this page or in an online editor such as [CodePen](https://codepen.io/), [JSFiddle](https://jsfiddle.net/), or [Glitch](https://glitch.com/). +> +> If you get stuck, you can reach out to us in one of our [communication channels](/en-US/docs/MDN/Community/Communication_channels). + +## Form structure 1 + +In this task we want you to structure the provided form features: + +1. Separate out the first two and second two form fields into two distinct containers, each with a descriptive legend (use "Personal details" for the first two, and "Comment information" for the second two). +2. Mark up each text label with an appropriate element so that it is semantically associated with its respective form field. +3. Add a suitable set of structural elements around the label/field pairs to separate them out. + +{{EmbedGHLiveSample("learning-area/html/forms/tasks/form-structure/form-structure1.html", '100%', 700)}} + +> [!CALLOUT] +> +> [Download the starting point for this task](https://github.com/mdn/learning-area/blob/main/html/forms/tasks/form-structure/form-structure1-download.html) to work in your own editor or in an online editor. diff --git a/files/en-us/learn_web_development/extensions/forms/test_your_skills/form_validation/index.md b/files/en-us/learn_web_development/extensions/forms/test_your_skills/form_validation/index.md new file mode 100644 index 000000000000000..45a612944c55ae6 --- /dev/null +++ b/files/en-us/learn_web_development/extensions/forms/test_your_skills/form_validation/index.md @@ -0,0 +1,56 @@ +--- +title: "Test your skills: Form validation" +short-title: Form validation +slug: Learn_web_development/Extensions/Forms/Test_your_skills/Form_validation +page-type: learn-module-assessment +sidebar: learnsidebar +--- + +The aim of this skill test is to assess whether you've understood our [Client-side form validation](/en-US/docs/Learn_web_development/Extensions/Forms/Form_validation) article. + +> [!NOTE] +> You can try solutions in the interactive editors on this page or in an online editor such as [CodePen](https://codepen.io/), [JSFiddle](https://jsfiddle.net/), or [Glitch](https://glitch.com/). +> +> If you get stuck, you can reach out to us in one of our [communication channels](/en-US/docs/MDN/Community/Communication_channels). + +## Form validation 1 + +In this task, we are providing you with a simple support query form, and we want you to add some validation features to it: + +1. Make all of the input fields mandatory to complete before the form can be submitted. +2. Change the type of the "Email address" and "Phone number" fields to make the browser apply some more specific validation suitable for the data being asked for. +3. Give the "User name" field a required length of between 5 and 20 characters, the "Phone number" field a maximum length of 15 characters, and the "Comment" field a maximum length of 200 characters. + +Try submitting your form — it should refuse to submit until the above constraints are followed, and give suitable error messages. To help, you might want to consider adding some simple CSS to show when a form field is valid or invalid. + +> [!CALLOUT] +> +> [Download the starting point for this task](https://github.com/mdn/learning-area/blob/main/html/forms/tasks/form-validation/form-validation1-download.html) to work in your own editor or in an online editor. + +## Form validation 2 + +Now we want you to take the same form you saw in the previous task (use your previous answer if you want to), and add some more specific pattern validation to the first three fields using regular expressions. + +1. All of the user names in our application consist of a single letter, followed by a dot, followed by three or more letters or numbers. All letters should be lowercase. +2. All of the email addresses for our users consist of one or more letters (lower or upper case) or numbers, followed by "@bigcorp.eu". +3. Remove the length validation from the phone number field if it is present, and set it so that it accepts 10 digits — either 10 digits in a row, or a pattern of three digits, three digits, then four digits, separated by either spaces, dashes, or dots. + +> [!NOTE] +> Regular expressions are really challenging if you are new to them, but don't despair — have a go and see where you get to; there is no shame in asking for some help. You can find everything you need to answer these questions at our [regular expression reference](/en-US/docs/Web/JavaScript/Guide/Regular_expressions), and by searching on [Stack Overflow](https://stackoverflow.com/). + +Again, to help you might want to consider adding some simple CSS to show when a form field is valid or invalid. + +> [!CALLOUT] +> +> [Download the starting point for this task](https://github.com/mdn/learning-area/blob/main/html/forms/tasks/form-validation/form-validation2-download.html) to work in your own editor or in an online editor. + +## Form validation 3 + +In our final task for this set, we are providing you with a similar example to what you saw in the accompanying article — an email address entry input. We would like you to use the constraint validation API, plus some form validation attributes, to program some custom error messages. + +1. Make the input mandatory to fill in, and give it a minimum length of 10 characters. +2. Add an event listener that checks whether the inputted value is an email address, and whether it is long enough. If it doesn't look like an email address or is too short, provide the user with appropriate custom error messages. + +> [!CALLOUT] +> +> [Download the starting point for this task](https://github.com/mdn/learning-area/blob/main/html/forms/tasks/form-validation/form-validation3-download.html) to work in your own editor or in an online editor. diff --git a/files/en-us/learn_web_development/extensions/forms/test_your_skills/index.md b/files/en-us/learn_web_development/extensions/forms/test_your_skills/index.md new file mode 100644 index 000000000000000..c59f6c15f051e18 --- /dev/null +++ b/files/en-us/learn_web_development/extensions/forms/test_your_skills/index.md @@ -0,0 +1,17 @@ +--- +title: "Test your skills: Web forms" +short-title: Test your skills +slug: Learn_web_development/Extensions/Forms/Test_your_skills +page-type: learn-module-assessment +sidebar: learnsidebar +--- + +This page lists tests for using forms on the web so you can verify you've understood the content in this module. + +## Test your forms skills by topic + +{{SubpagesWithSummaries}} + +## See also + +- [Web forms](/en-US/docs/Learn_web_development/Extensions/Forms) diff --git a/files/en-us/learn_web_development/extensions/forms/test_your_skills/input_types/index.md b/files/en-us/learn_web_development/extensions/forms/test_your_skills/input_types/index.md new file mode 100644 index 000000000000000..c7e2e34b46ec5e2 --- /dev/null +++ b/files/en-us/learn_web_development/extensions/forms/test_your_skills/input_types/index.md @@ -0,0 +1,47 @@ +--- +title: "Test your skills: Input types" +short-title: Input types +slug: Learn_web_development/Extensions/Forms/Test_your_skills/Input_types +page-type: learn-module-assessment +sidebar: learnsidebar +--- + +The aim of this skill test is to assess whether you've understood our [The HTML5 input types](/en-US/docs/Learn_web_development/Extensions/Forms/HTML5_input_types) article. + +> [!NOTE] +> You can try solutions in the interactive editors on this page or in an online editor such as [CodePen](https://codepen.io/), [JSFiddle](https://jsfiddle.net/), or [Glitch](https://glitch.com/). +> +> If you get stuck, you can reach out to us in one of our [communication channels](/en-US/docs/MDN/Community/Communication_channels). + +## HTML controls 1 + +First, let's explore some input types. Create appropriate inputs for a user to update their details for: + +1. Email +2. Website +3. Phone number +4. Favorite color + +Try updating the live code below to recreate the finished example: + +{{EmbedGHLiveSample("learning-area/html/forms/tasks/html5-controls/html5-controls1.html", '100%', 700)}} + +> [!CALLOUT] +> +> [Download the starting point for this task](https://github.com/mdn/learning-area/blob/main/html/forms/tasks/html5-controls/html5-controls1-download.html) to work in your own editor or in an online editor. + +## HTML controls 2 + +Next, we want you to implement a slider control to allow the user to choose a maximum number of people to invite to their party. + +1. Implement a basic slider control to go along with the provided label. +2. Give it a minimum value of 1, maximum value of 30, initial value of 10 and element `id` of `max-invite`. +3. Create a corresponding output element to put the current value of the slider into. Give it a class of `invite-output`, and semantically associate it with the input. If you do this correctly, the JavaScript included on the page will automatically update the output value when the slider is moved. + +Try updating the live code below to recreate the finished example: + +{{EmbedGHLiveSample("learning-area/html/forms/tasks/html5-controls/html5-controls2.html", '100%', 700)}} + +> [!CALLOUT] +> +> [Download the starting point for this task](https://github.com/mdn/learning-area/blob/main/html/forms/tasks/html5-controls/html5-controls2-download.html) to work in your own editor or in an online editor. diff --git a/files/en-us/learn_web_development/extensions/forms/test_your_skills/other_controls/index.md b/files/en-us/learn_web_development/extensions/forms/test_your_skills/other_controls/index.md new file mode 100644 index 000000000000000..35b429db0fee827 --- /dev/null +++ b/files/en-us/learn_web_development/extensions/forms/test_your_skills/other_controls/index.md @@ -0,0 +1,63 @@ +--- +title: "Test your skills: Other controls" +short-title: Other controls +slug: Learn_web_development/Extensions/Forms/Test_your_skills/Other_controls +page-type: learn-module-assessment +sidebar: learnsidebar +--- + +The aim of this skill test is to assess whether you've understood our [Other form controls](/en-US/docs/Learn_web_development/Extensions/Forms/Other_form_controls) article. + +> [!NOTE] +> You can try solutions in the interactive editors on this page or in an online editor such as [CodePen](https://codepen.io/), [JSFiddle](https://jsfiddle.net/), or [Glitch](https://glitch.com/). +> +> If you get stuck, you can reach out to us in one of our [communication channels](/en-US/docs/MDN/Community/Communication_channels). + +## Other controls 1 + +In our first "other controls" assessment, we'll get you to create a multi-line text input. + +1. Create a basic multi-line text input. +2. Associate it semantically with the provided "Comment" label. +3. Give the input 35 columns, and 10 rows of space in which to add comments. +4. Give the comments a maximum length of 100 characters. + +To create the input, update the HTML code in the editor below: + +{{EmbedGHLiveSample("learning-area/html/forms/tasks/other-controls/other-controls1.html", '100%', 500)}} + +> [!CALLOUT] +> +> [Download the starting point for this task](https://github.com/mdn/learning-area/blob/main/html/forms/tasks/other-controls/other-controls1-download.html) to work in your own editor or in an online editor. + +## Other controls 2 + +Now it's time to have a go at implementing a drop-down select menu, to allow a user to pick their favorite food from the choices provided. + +1. Create your basic select box structure. +2. Associate it semantically with the provided "food" label. +3. Inside the list, split the choices up into 2 subgroups — "mains" and "snacks". + +To create the menu, update the HTML code in the editor below: + +{{EmbedGHLiveSample("learning-area/html/forms/tasks/other-controls/other-controls2.html", '100%', 500)}} + +> [!CALLOUT] +> +> [Download the starting point for this task](https://github.com/mdn/learning-area/blob/main/html/forms/tasks/other-controls/other-controls2-download.html) to work in your own editor or in an online editor. + +## Other controls 3 + +In our final task of this set, we start with much the same list of food choices. However, this time we want to do things differently: + +1. Create a basic text input that is semantically associated with the provided label. +2. Put the food choices into a list that can be associated with a form input. +3. Associate the list with your text input, so that when you type characters, any of the list options that match the character sequence are given in a dropdown list as autocomplete suggestions. + +To create the input, update the HTML code in the editor below: + +{{EmbedGHLiveSample("learning-area/html/forms/tasks/other-controls/other-controls3.html", '100%', 500)}} + +> [!CALLOUT] +> +> [Download the starting point for this task](https://github.com/mdn/learning-area/blob/main/html/forms/tasks/other-controls/other-controls3-download.html) to work in your own editor or in an online editor. diff --git a/files/en-us/learn_web_development/extensions/forms/test_your_skills/styling_basics/index.md b/files/en-us/learn_web_development/extensions/forms/test_your_skills/styling_basics/index.md new file mode 100644 index 000000000000000..4cc9a0a2817708d --- /dev/null +++ b/files/en-us/learn_web_development/extensions/forms/test_your_skills/styling_basics/index.md @@ -0,0 +1,26 @@ +--- +title: "Test your skills: Styling basics" +short-title: Basic styling +slug: Learn_web_development/Extensions/Forms/Test_your_skills/Styling_basics +page-type: learn-module-assessment +sidebar: learnsidebar +--- + +The aim of this skill test is to assess whether you've understood our [Styling web forms](/en-US/docs/Learn_web_development/Extensions/Forms/Styling_web_forms) article. + +> [!NOTE] +> You can try solutions in the interactive editors on this page or in an online editor such as [CodePen](https://codepen.io/), [JSFiddle](https://jsfiddle.net/), or [Glitch](https://glitch.com/). +> +> If you get stuck, you can reach out to us in one of our [communication channels](/en-US/docs/MDN/Community/Communication_channels). + +## Styling basics 1 + +Our basic form styling assessment is fairly free-form, and you have a lot of flexibility over what you end up doing here. But your CSS should aim to fulfill the following requirements: + +1. Add some kind of lightweight "reset" to make fonts, padding, margin, and sizing more consistent to begin with. +2. On top of that, add in some nice, consistent styling for the inputs and button. +3. Use some kind of layout technique to make the inputs and labels line up neatly. + +> [!CALLOUT] +> +> [Download the starting point for this task](https://github.com/mdn/learning-area/blob/main/html/forms/tasks/styling-basics/styling-basics1-download.html) to work in your own editor or in an online editor. diff --git a/files/en-us/learn_web_development/extensions/forms/test_your_skills_colon__advanced_styling/index.md b/files/en-us/learn_web_development/extensions/forms/test_your_skills_colon__advanced_styling/index.md deleted file mode 100644 index 4550d9f9482e103..000000000000000 --- a/files/en-us/learn_web_development/extensions/forms/test_your_skills_colon__advanced_styling/index.md +++ /dev/null @@ -1,67 +0,0 @@ ---- -title: "Test your skills: Advanced styling" -slug: Learn_web_development/Extensions/Forms/Test_your_skills:_Advanced_styling -page-type: learn-module-assessment ---- - -{{learnsidebar}} - -The aim of this skill test is to assess whether you've understood our [Advanced form styling](/en-US/docs/Learn_web_development/Extensions/Forms/Advanced_form_styling) and [UI pseudo-classes](/en-US/docs/Learn_web_development/Extensions/Forms/UI_pseudo-classes) articles. - -> [!NOTE] -> You can try solutions in the interactive editors on this page or in an online editor such as [CodePen](https://codepen.io/), [JSFiddle](https://jsfiddle.net/), or [Glitch](https://glitch.com/). -> -> If you get stuck, you can reach out to us in one of our [communication channels](/en-US/docs/MDN/Community/Communication_channels). - -## Advanced form styling 1 - -In our first advanced styling tasks, we want you to handle making a search input as consistent as possible across browsers — a trickier task than with standard text inputs, even on modern browsers. - -We've already provided you with a basic reset to build upon. - -1. First of all, try giving the search box a consistent width, height, padding, and border color across browsers. -2. You'll find that some browsers will not behave in terms of the form element's height. This is due to native OS styling being used in some cases. How can you remove this native styling? -3. Once you've removed the native styling, you'll need to add back one of the features it was providing, to keep the same look and feel we originally had. How do you do this? -4. One thing that is inconsistent across browsers (particularly looking at Safari here) is the position of the standard blue focus outline. How can you remove this? -5. There is a major problem with just getting rid of the blue focus outline. What is it? Can you add some kind of styling back in so that users can tell when the search box is being hovered or focused? -6. Another thing that commonly denotes a search box is a magnifying glass icon. We've made one available in the same directory as our HTML files — see [search-24px.png](https://github.com/mdn/learning-area/blob/main/html/forms/tasks/advanced-styling/search-24px.png) — plus a `<div>` element after the search input to help you attach it, should you need it. Can you figure out a sensible way to attach it, and can you use some CSS to get it to sit to the right of the search box, and be lined up vertically as well? - -Try updating the live code below to recreate the finished example: - -{{EmbedGHLiveSample("learning-area/html/forms/tasks/advanced-styling/advanced-styling1.html", '100%', 700)}} - -> [!CALLOUT] -> -> [Download the starting point for this task](https://github.com/mdn/learning-area/blob/main/html/forms/tasks/advanced-styling/advanced-styling1-download.html) to work in your own editor or in an online editor. - -## Advanced form styling 2 - -In our next task we provide you with a set of three radio buttons. We want you to give them custom styling. - -We've already provided you with a basic reset to build upon. - -1. First of all, get rid of their default styling. -2. Next, give the radio buttons a reasonable base style — the style they have when the page first loads. This can be anything you like, but you probably want to set a width and height (of somewhere between about 18 and 24 pixels), and a subtle border and/or background color. -3. Now give the radio buttons a different style for when they are selected. -4. Align the radio buttons nicely with the labels. - -Try updating the live code below to recreate the finished example: - -{{EmbedGHLiveSample("learning-area/html/forms/tasks/advanced-styling/advanced-styling2.html", '100%', 700)}} - -> [!CALLOUT] -> -> [Download the starting point for this task](https://github.com/mdn/learning-area/blob/main/html/forms/tasks/advanced-styling/advanced-styling2-download.html) to work in your own editor or in an online editor. - -## Advanced form styling 3 - -In our final task for this assessment series, we provide you with a feedback form that is already nicely-styled — you've already seen something similar if you've worked through our [UI pseudo-classes](/en-US/docs/Learn_web_development/Extensions/Forms/UI_pseudo-classes) article, and now we want you to come up with your own solution. - -What we'd like you to do is make use of some advanced pseudo-classes to provide some useful indicators of validity. - -1. First of all, we want you to provide some specific styling to visually indicate which inputs have to be filled in — they cannot be left empty. -2. Second, we want you to provide a useful visual indicator of whether the data entered inside each input is valid or not. - -> [!CALLOUT] -> -> [Download the starting point for this task](https://github.com/mdn/learning-area/blob/main/html/forms/tasks/advanced-styling/advanced-styling3-download.html) to work in your own editor or in an online editor. diff --git a/files/en-us/learn_web_development/extensions/forms/test_your_skills_colon__basic_controls/index.md b/files/en-us/learn_web_development/extensions/forms/test_your_skills_colon__basic_controls/index.md deleted file mode 100644 index 754f666ef264267..000000000000000 --- a/files/en-us/learn_web_development/extensions/forms/test_your_skills_colon__basic_controls/index.md +++ /dev/null @@ -1,63 +0,0 @@ ---- -title: "Test your skills: Basic controls" -slug: Learn_web_development/Extensions/Forms/Test_your_skills:_Basic_controls -page-type: learn-module-assessment ---- - -{{learnsidebar}} - -The aim of this skill test is to assess whether you've understood our [Basic native form controls](/en-US/docs/Learn_web_development/Extensions/Forms/Basic_native_form_controls) article. - -> [!NOTE] -> You can try solutions in the interactive editors on this page or in an online editor such as [CodePen](https://codepen.io/), [JSFiddle](https://jsfiddle.net/), or [Glitch](https://glitch.com/). -> -> If you get stuck, you can reach out to us in one of our [communication channels](/en-US/docs/MDN/Community/Communication_channels). - -## Basic controls 1 - -This task starts you off nice and gently by asking you to create two `<input>` elements, for a user's ID and password, along with a submit button. - -1. Create appropriate inputs for user ID and password. -2. You should also associate them with their text labels semantically. -3. Create a submit button inside the remaining list item, with button text of "Log in". - -Try updating the live code below to recreate the finished example: - -{{EmbedGHLiveSample("learning-area/html/forms/tasks/basic-controls/basic-controls1.html", '100%', 700)}} - -> [!CALLOUT] -> -> [Download the starting point for this task](https://github.com/mdn/learning-area/blob/main/html/forms/tasks/basic-controls/basic-controls1-download.html) to work in your own editor or in an online editor. - -## Basic controls 2 - -The next task requires you to create working sets of checkboxes and radio buttons, from the provided text labels. - -1. Turn the first `<fieldset>`'s contents into a set of radio buttons — you should only be able to select one pony character at once. -2. Make it so that the first radio button is selected upon page load. -3. Turn the second `<fieldset>`'s content into a set of checkboxes. -4. Add a couple more hotdog choices of your own. - -Try updating the live code below to recreate the finished example: - -{{EmbedGHLiveSample("learning-area/html/forms/tasks/basic-controls/basic-controls2.html", '100%', 700)}} - -> [!CALLOUT] -> -> [Download the starting point for this task](https://github.com/mdn/learning-area/blob/main/html/forms/tasks/basic-controls/basic-controls2-download.html) to work in your own editor or in an online editor. - -## Basic controls 3 - -The final task in this set requires you to create a file picker. - -1. Create a basic file picker. -2. Allow the user to pick multiple files at once. -3. Allow the file picker to accept JPG and PNG images only. - -Try updating the live code below to recreate the finished example: - -{{EmbedGHLiveSample("learning-area/html/forms/tasks/basic-controls/basic-controls3.html", '100%', 700)}} - -> [!CALLOUT] -> -> [Download the starting point for this task](https://github.com/mdn/learning-area/blob/main/html/forms/tasks/basic-controls/basic-controls3-download.html) to work in your own editor or in an online editor. diff --git a/files/en-us/learn_web_development/extensions/forms/test_your_skills_colon__form_structure/index.md b/files/en-us/learn_web_development/extensions/forms/test_your_skills_colon__form_structure/index.md deleted file mode 100644 index 8a832bf74ee0f3f..000000000000000 --- a/files/en-us/learn_web_development/extensions/forms/test_your_skills_colon__form_structure/index.md +++ /dev/null @@ -1,28 +0,0 @@ ---- -title: "Test your skills: Form structure" -slug: Learn_web_development/Extensions/Forms/Test_your_skills:_Form_structure -page-type: learn-module-assessment ---- - -{{learnsidebar}} - -The aim of this skill test is to assess whether you've understood our [How to structure a web form](/en-US/docs/Learn_web_development/Extensions/Forms/How_to_structure_a_web_form) article. - -> [!NOTE] -> You can try solutions in the interactive editors on this page or in an online editor such as [CodePen](https://codepen.io/), [JSFiddle](https://jsfiddle.net/), or [Glitch](https://glitch.com/). -> -> If you get stuck, you can reach out to us in one of our [communication channels](/en-US/docs/MDN/Community/Communication_channels). - -## Form structure 1 - -In this task we want you to structure the provided form features: - -1. Separate out the first two and second two form fields into two distinct containers, each with a descriptive legend (use "Personal details" for the first two, and "Comment information" for the second two). -2. Mark up each text label with an appropriate element so that it is semantically associated with its respective form field. -3. Add a suitable set of structural elements around the label/field pairs to separate them out. - -{{EmbedGHLiveSample("learning-area/html/forms/tasks/form-structure/form-structure1.html", '100%', 700)}} - -> [!CALLOUT] -> -> [Download the starting point for this task](https://github.com/mdn/learning-area/blob/main/html/forms/tasks/form-structure/form-structure1-download.html) to work in your own editor or in an online editor. diff --git a/files/en-us/learn_web_development/extensions/forms/test_your_skills_colon__form_validation/index.md b/files/en-us/learn_web_development/extensions/forms/test_your_skills_colon__form_validation/index.md deleted file mode 100644 index 279e840bfdbe435..000000000000000 --- a/files/en-us/learn_web_development/extensions/forms/test_your_skills_colon__form_validation/index.md +++ /dev/null @@ -1,56 +0,0 @@ ---- -title: "Test your skills: Form validation" -slug: Learn_web_development/Extensions/Forms/Test_your_skills:_Form_validation -page-type: learn-module-assessment ---- - -{{learnsidebar}} - -The aim of this skill test is to assess whether you've understood our [Client-side form validation](/en-US/docs/Learn_web_development/Extensions/Forms/Form_validation) article. - -> [!NOTE] -> You can try solutions in the interactive editors on this page or in an online editor such as [CodePen](https://codepen.io/), [JSFiddle](https://jsfiddle.net/), or [Glitch](https://glitch.com/). -> -> If you get stuck, you can reach out to us in one of our [communication channels](/en-US/docs/MDN/Community/Communication_channels). - -## Form validation 1 - -In this task, we are providing you with a simple support query form, and we want you to add some validation features to it: - -1. Make all of the input fields mandatory to complete before the form can be submitted. -2. Change the type of the "Email address" and "Phone number" fields to make the browser apply some more specific validation suitable for the data being asked for. -3. Give the "User name" field a required length of between 5 and 20 characters, the "Phone number" field a maximum length of 15 characters, and the "Comment" field a maximum length of 200 characters. - -Try submitting your form — it should refuse to submit until the above constraints are followed, and give suitable error messages. To help, you might want to consider adding some simple CSS to show when a form field is valid or invalid. - -> [!CALLOUT] -> -> [Download the starting point for this task](https://github.com/mdn/learning-area/blob/main/html/forms/tasks/form-validation/form-validation1-download.html) to work in your own editor or in an online editor. - -## Form validation 2 - -Now we want you to take the same form you saw in the previous task (use your previous answer if you want to), and add some more specific pattern validation to the first three fields using regular expressions. - -1. All of the user names in our application consist of a single letter, followed by a dot, followed by three or more letters or numbers. All letters should be lowercase. -2. All of the email addresses for our users consist of one or more letters (lower or upper case) or numbers, followed by "@bigcorp.eu". -3. Remove the length validation from the phone number field if it is present, and set it so that it accepts 10 digits — either 10 digits in a row, or a pattern of three digits, three digits, then four digits, separated by either spaces, dashes, or dots. - -> [!NOTE] -> Regular expressions are really challenging if you are new to them, but don't despair — have a go and see where you get to; there is no shame in asking for some help. You can find everything you need to answer these questions at our [regular expression reference](/en-US/docs/Web/JavaScript/Guide/Regular_expressions), and by searching on [Stack Overflow](https://stackoverflow.com/). - -Again, to help you might want to consider adding some simple CSS to show when a form field is valid or invalid. - -> [!CALLOUT] -> -> [Download the starting point for this task](https://github.com/mdn/learning-area/blob/main/html/forms/tasks/form-validation/form-validation2-download.html) to work in your own editor or in an online editor. - -## Form validation 3 - -In our final task for this set, we are providing you with a similar example to what you saw in the accompanying article — an email address entry input. We would like you to use the constraint validation API, plus some form validation attributes, to program some custom error messages. - -1. Make the input mandatory to fill in, and give it a minimum length of 10 characters. -2. Add an event listener that checks whether the inputted value is an email address, and whether it is long enough. If it doesn't look like an email address or is too short, provide the user with appropriate custom error messages. - -> [!CALLOUT] -> -> [Download the starting point for this task](https://github.com/mdn/learning-area/blob/main/html/forms/tasks/form-validation/form-validation3-download.html) to work in your own editor or in an online editor. diff --git a/files/en-us/learn_web_development/extensions/forms/test_your_skills_colon__html5_controls/index.md b/files/en-us/learn_web_development/extensions/forms/test_your_skills_colon__html5_controls/index.md deleted file mode 100644 index 391a61183f03fb7..000000000000000 --- a/files/en-us/learn_web_development/extensions/forms/test_your_skills_colon__html5_controls/index.md +++ /dev/null @@ -1,47 +0,0 @@ ---- -title: "Test your skills: HTML5 controls" -slug: Learn_web_development/Extensions/Forms/Test_your_skills:_HTML5_controls -page-type: learn-module-assessment ---- - -{{learnsidebar}} - -The aim of this skill test is to assess whether you've understood our [The HTML5 input types](/en-US/docs/Learn_web_development/Extensions/Forms/HTML5_input_types) article. - -> [!NOTE] -> You can try solutions in the interactive editors on this page or in an online editor such as [CodePen](https://codepen.io/), [JSFiddle](https://jsfiddle.net/), or [Glitch](https://glitch.com/). -> -> If you get stuck, you can reach out to us in one of our [communication channels](/en-US/docs/MDN/Community/Communication_channels). - -## HTML controls 1 - -First, let's explore some input types. Create appropriate inputs for a user to update their details for: - -1. Email -2. Website -3. Phone number -4. Favorite color - -Try updating the live code below to recreate the finished example: - -{{EmbedGHLiveSample("learning-area/html/forms/tasks/html5-controls/html5-controls1.html", '100%', 700)}} - -> [!CALLOUT] -> -> [Download the starting point for this task](https://github.com/mdn/learning-area/blob/main/html/forms/tasks/html5-controls/html5-controls1-download.html) to work in your own editor or in an online editor. - -## HTML controls 2 - -Next, we want you to implement a slider control to allow the user to choose a maximum number of people to invite to their party. - -1. Implement a basic slider control to go along with the provided label. -2. Give it a minimum value of 1, maximum value of 30, initial value of 10 and element `id` of `max-invite`. -3. Create a corresponding output element to put the current value of the slider into. Give it a class of `invite-output`, and semantically associate it with the input. If you do this correctly, the JavaScript included on the page will automatically update the output value when the slider is moved. - -Try updating the live code below to recreate the finished example: - -{{EmbedGHLiveSample("learning-area/html/forms/tasks/html5-controls/html5-controls2.html", '100%', 700)}} - -> [!CALLOUT] -> -> [Download the starting point for this task](https://github.com/mdn/learning-area/blob/main/html/forms/tasks/html5-controls/html5-controls2-download.html) to work in your own editor or in an online editor. diff --git a/files/en-us/learn_web_development/extensions/forms/test_your_skills_colon__other_controls/index.md b/files/en-us/learn_web_development/extensions/forms/test_your_skills_colon__other_controls/index.md deleted file mode 100644 index 595cf6e799546e7..000000000000000 --- a/files/en-us/learn_web_development/extensions/forms/test_your_skills_colon__other_controls/index.md +++ /dev/null @@ -1,63 +0,0 @@ ---- -title: "Test your skills: Other controls" -slug: Learn_web_development/Extensions/Forms/Test_your_skills:_Other_controls -page-type: learn-module-assessment ---- - -{{learnsidebar}} - -The aim of this skill test is to assess whether you've understood our [Other form controls](/en-US/docs/Learn_web_development/Extensions/Forms/Other_form_controls) article. - -> [!NOTE] -> You can try solutions in the interactive editors on this page or in an online editor such as [CodePen](https://codepen.io/), [JSFiddle](https://jsfiddle.net/), or [Glitch](https://glitch.com/). -> -> If you get stuck, you can reach out to us in one of our [communication channels](/en-US/docs/MDN/Community/Communication_channels). - -## Other controls 1 - -In our first "other controls" assessment, we'll get you to create a multi-line text input. - -1. Create a basic multi-line text input. -2. Associate it semantically with the provided "Comment" label. -3. Give the input 35 columns, and 10 rows of space in which to add comments. -4. Give the comments a maximum length of 100 characters. - -To create the input, update the HTML code in the editor below: - -{{EmbedGHLiveSample("learning-area/html/forms/tasks/other-controls/other-controls1.html", '100%', 500)}} - -> [!CALLOUT] -> -> [Download the starting point for this task](https://github.com/mdn/learning-area/blob/main/html/forms/tasks/other-controls/other-controls1-download.html) to work in your own editor or in an online editor. - -## Other controls 2 - -Now it's time to have a go at implementing a drop-down select menu, to allow a user to pick their favorite food from the choices provided. - -1. Create your basic select box structure. -2. Associate it semantically with the provided "food" label. -3. Inside the list, split the choices up into 2 subgroups — "mains" and "snacks". - -To create the menu, update the HTML code in the editor below: - -{{EmbedGHLiveSample("learning-area/html/forms/tasks/other-controls/other-controls2.html", '100%', 500)}} - -> [!CALLOUT] -> -> [Download the starting point for this task](https://github.com/mdn/learning-area/blob/main/html/forms/tasks/other-controls/other-controls2-download.html) to work in your own editor or in an online editor. - -## Other controls 3 - -In our final task of this set, we start with much the same list of food choices. However, this time we want to do things differently: - -1. Create a basic text input that is semantically associated with the provided label. -2. Put the food choices into a list that can be associated with a form input. -3. Associate the list with your text input, so that when you type characters, any of the list options that match the character sequence are given in a dropdown list as autocomplete suggestions. - -To create the input, update the HTML code in the editor below: - -{{EmbedGHLiveSample("learning-area/html/forms/tasks/other-controls/other-controls3.html", '100%', 500)}} - -> [!CALLOUT] -> -> [Download the starting point for this task](https://github.com/mdn/learning-area/blob/main/html/forms/tasks/other-controls/other-controls3-download.html) to work in your own editor or in an online editor. diff --git a/files/en-us/learn_web_development/extensions/forms/test_your_skills_colon__styling_basics/index.md b/files/en-us/learn_web_development/extensions/forms/test_your_skills_colon__styling_basics/index.md deleted file mode 100644 index 75a882fbad86783..000000000000000 --- a/files/en-us/learn_web_development/extensions/forms/test_your_skills_colon__styling_basics/index.md +++ /dev/null @@ -1,26 +0,0 @@ ---- -title: "Test your skills: Styling basics" -slug: Learn_web_development/Extensions/Forms/Test_your_skills:_Styling_basics -page-type: learn-module-assessment ---- - -{{learnsidebar}} - -The aim of this skill test is to assess whether you've understood our [Styling web forms](/en-US/docs/Learn_web_development/Extensions/Forms/Styling_web_forms) article. - -> [!NOTE] -> You can try solutions in the interactive editors on this page or in an online editor such as [CodePen](https://codepen.io/), [JSFiddle](https://jsfiddle.net/), or [Glitch](https://glitch.com/). -> -> If you get stuck, you can reach out to us in one of our [communication channels](/en-US/docs/MDN/Community/Communication_channels). - -## Styling basics 1 - -Our basic form styling assessment is fairly free-form, and you have a lot of flexibility over what you end up doing here. But your CSS should aim to fulfill the following requirements: - -1. Add some kind of lightweight "reset" to make fonts, padding, margin, and sizing more consistent to begin with. -2. On top of that, add in some nice, consistent styling for the inputs and button. -3. Use some kind of layout technique to make the inputs and labels line up neatly. - -> [!CALLOUT] -> -> [Download the starting point for this task](https://github.com/mdn/learning-area/blob/main/html/forms/tasks/styling-basics/styling-basics1-download.html) to work in your own editor or in an online editor. diff --git a/files/en-us/learn_web_development/extensions/forms/ui_pseudo-classes/index.md b/files/en-us/learn_web_development/extensions/forms/ui_pseudo-classes/index.md index d99a25a0c77d2c0..75161e42feade02 100644 --- a/files/en-us/learn_web_development/extensions/forms/ui_pseudo-classes/index.md +++ b/files/en-us/learn_web_development/extensions/forms/ui_pseudo-classes/index.md @@ -2,9 +2,10 @@ title: UI pseudo-classes slug: Learn_web_development/Extensions/Forms/UI_pseudo-classes page-type: learn-module-chapter +sidebar: learnsidebar --- -{{LearnSidebar}}{{PreviousMenuNext("Learn_web_development/Extensions/Forms/Advanced_form_styling", "Learn_web_development/Extensions/Forms/Form_validation", "Learn_web_development/Extensions/Forms")}} +{{PreviousMenuNext("Learn_web_development/Extensions/Forms/Customizable_select", "Learn_web_development/Extensions/Forms/Form_validation", "Learn_web_development/Extensions/Forms")}} In the previous articles, we covered the styling of various form controls in a general manner. This included some usage of pseudo-classes, for example, using `:checked` to target a checkbox only when it is selected. In this article, we explore the different UI pseudo-classes available for styling forms in different states. @@ -38,15 +39,15 @@ In the previous articles, we covered the styling of various form controls in a g The original pseudo-classes (from [CSS 2.1](https://www.w3.org/TR/CSS21/selector.html#dynamic-pseudo-classes)) that are relevant to forms are: - {{cssxref(":hover")}}: Selects an element only when it is being hovered over by a mouse pointer. -- {{cssxref(":focus")}}: Selects an element only when it is focused (i.e. by being tabbed to via the keyboard). -- {{cssxref(":active")}}: selects an element only when it is being activated (i.e. while it is being clicked on, or when the <kbd>Return</kbd> / <kbd>Enter</kbd> key is being pressed down in the case of a keyboard activation). +- {{cssxref(":focus")}}: Selects an element only when it is focused (i.e., by being tabbed to via the keyboard). +- {{cssxref(":active")}}: selects an element only when it is being activated (i.e., while it is being clicked on, or when the <kbd>Return</kbd> / <kbd>Enter</kbd> key is being pressed down in the case of a keyboard activation). These basic pseudo-classes should be familiar to you now. [CSS selectors](/en-US/docs/Web/CSS/CSS_selectors) provide several other pseudo-classes related to HTML forms. These provide several useful targeting conditions that you can take advantage of. We'll discuss these in more detail in the sections below, but briefly, the main ones we'll be looking at are: -- {{cssxref(':required')}} and {{cssxref(':optional')}}: Target elements that can be required (e.g. elements that support the [`required`](/en-US/docs/Web/HTML/Attributes/required) HTML attribute)), based on whether they are required or optional. +- {{cssxref(':required')}} and {{cssxref(':optional')}}: Target elements that can be required (e.g., elements that support the [`required`](/en-US/docs/Web/HTML/Reference/Attributes/required) HTML attribute)), based on whether they are required or optional. - {{cssxref(":valid")}} and {{cssxref(":invalid")}}, and {{cssxref(":in-range")}} and {{cssxref(":out-of-range")}}: Target form controls that are valid/invalid according to form validation constraints set on them, or in-range/out-of-range. -- {{cssxref(":enabled")}} and {{cssxref(":disabled")}}, and {{cssxref(":read-only")}} and {{cssxref(":read-write")}}: Target elements that can be disabled (e.g. elements that support the [`disabled`](/en-US/docs/Web/HTML/Attributes/disabled) HTML attribute), based on whether they are currently enabled or disabled, and read-write or read-only form controls (e.g. elements with the [`readonly`](/en-US/docs/Web/HTML/Attributes/readonly) HTML attribute set). -- {{cssxref(":checked")}}, {{cssxref(":indeterminate")}}, and {{cssxref(":default")}}: Respectively target checkboxes and radio buttons that are checked, in an indeterminate state (neither checked or not checked), and the default selected option when the page loads (e.g. an [`<input type="checkbox">`](/en-US/docs/Web/HTML/Element/input/checkbox) with the [`checked`](/en-US/docs/Web/HTML/Element/input#checked) attribute set, or an [`<option>`](/en-US/docs/Web/HTML/Element/option) element with the [`selected`](/en-US/docs/Web/HTML/Element/option#selected) attribute set). +- {{cssxref(":enabled")}} and {{cssxref(":disabled")}}, and {{cssxref(":read-only")}} and {{cssxref(":read-write")}}: Target elements that can be disabled (e.g., elements that support the [`disabled`](/en-US/docs/Web/HTML/Reference/Attributes/disabled) HTML attribute), based on whether they are currently enabled or disabled, and read-write or read-only form controls (e.g., elements with the [`readonly`](/en-US/docs/Web/HTML/Reference/Attributes/readonly) HTML attribute set). +- {{cssxref(":checked")}}, {{cssxref(":indeterminate")}}, and {{cssxref(":default")}}: Respectively target checkboxes and radio buttons that are checked, in an indeterminate state (neither checked or not checked), and the default selected option when the page loads (e.g., an [`<input type="checkbox">`](/en-US/docs/Web/HTML/Reference/Elements/input/checkbox) with the [`checked`](/en-US/docs/Web/HTML/Reference/Elements/input#checked) attribute set, or an [`<option>`](/en-US/docs/Web/HTML/Reference/Elements/option) element with the [`selected`](/en-US/docs/Web/HTML/Reference/Elements/option#selected) attribute set). There are many others, but the ones listed above are the most obviously useful. Some of them are aimed at solving very specific niche problems. The UI pseudo-classes listed above have excellent browser support, but of course, you should test your form implementations carefully to ensure they work for your target audience. @@ -57,9 +58,10 @@ There are many others, but the ones listed above are the most obviously useful. One of the most basic concepts regarding client-side form validation is whether a form input is required (it has to be filled in before the form can be submitted) or optional. -{{htmlelement('input')}}, {{htmlelement('select')}}, and {{htmlelement('textarea')}} elements have a `required` attribute available which, when set, means that you have to fill in that control before the form will successfully submit. For example: +{{htmlelement('input')}}, {{htmlelement('select')}}, and {{htmlelement('textarea')}} elements have a `required` attribute available which, when set, means that you have to fill in that control before the form will successfully submit. +For example, the first name and last name are required in the form below, but the email address is optional: -```html +```html live-sample___optional-required-styles <form> <fieldset> <legend>Feedback form</legend> @@ -72,9 +74,7 @@ One of the most basic concepts regarding client-side form validation is whether <input id="lname" name="lname" type="text" required /> </div> <div> - <label for="email"> - Email address (include if you want a response): - </label> + <label for="email"> Email address (if you want a response): </label> <input id="email" name="email" type="email" /> </div> <div><button>Submit</button></div> @@ -82,29 +82,86 @@ One of the most basic concepts regarding client-side form validation is whether </form> ``` -Here, the first name and last name are required, but the email address is optional. - You can match these two states using the {{cssxref(':required')}} and {{cssxref(':optional')}} pseudo-classes. For example, if we apply the following CSS to the above HTML: -```css +```css hidden live-sample___optional-required-styles +body { + font-family: sans-serif; + margin: 20px auto; + max-width: 70%; +} + +fieldset { + padding: 10px 30px 0; +} + +legend { + color: white; + background: black; + padding: 5px 10px; +} + +fieldset > div { + margin-bottom: 20px; + display: flex; + flex-flow: row wrap; +} + +button, +label, +input { + display: block; + font-size: 100%; + box-sizing: border-box; + width: 100%; + padding: 5px; +} + +input { + box-shadow: inset 1px 1px 3px #ccc; + border-radius: 5px; +} + +input:hover, +input:focus { + background-color: #eee; +} + +button { + width: 60%; + margin: 0 auto; +} +``` + +```css live-sample___optional-required-styles input:required { - border: 1px solid black; + border: 2px solid; } input:optional { - border: 1px solid silver; + border: 2px dashed; } ``` -The required controls would have a black border, and the optional control will have a silver border, like so: +The required controls have a solid border, and the optional control has a dashed border. +You can also try submitting the form without filling it in, to see the client-side validation error messages browsers give you by default: -{{EmbedGHLiveSample("learning-area/html/forms/pseudo-classes/basic-required-optional.html", '100%', 400)}} +{{EmbedLiveSample("optional-required-styles", , "400px", , , , , "allow-forms")}} -You can also try submitting the form without filling it in, to see the client-side validation error messages browsers give you by default. +In general, you should avoid styling 'required' versus 'optional' elements in forms using color alone, because this isn't great for colorblind people: -The above form isn't bad, but it isn't great either. For a start, we are signaling required versus optional status using color alone, which isn't great for colorblind people. Second, the standard convention on the web for required status is an asterisk (`*`), or the word "required" being associated with the controls in question. +```css example-bad +input:required { + border: 2px solid red; +} -In the next section, we'll look at a better example of indicating required fields using `:required`, which also digs into using generated content. +input:optional { + border: 2px solid green; +} +``` + +The standard convention on the web for required status is an asterisk (`*`), or the word "required" associated with the respective controls. +In the next section, we'll look at a better example of indicating required fields using `:required` and generated content. > [!NOTE] > You'll probably not find yourself using the `:optional` pseudo-class very often. Form controls are optional by default, so you could just do your optional styling by default, and add styles on top for required controls. @@ -154,7 +211,7 @@ First of all, we'll add a paragraph to the top of the form to say what you are l Screen reader users will get "required" read out as an extra bit of information when they get to each required input, while sighted users will get our label. -As previously mentioned, text inputs don't support generated content, so we add an empty [`<span>`](/en-US/docs/Web/HTML/Element/span) to hang the generated content on: +As previously mentioned, text inputs don't support generated content, so we add an empty [`<span>`](/en-US/docs/Web/HTML/Reference/Elements/span) to hang the generated content on: ```html <div> @@ -203,7 +260,7 @@ Then we give the generated content the content "required", which is what we want ## Styling controls based on whether their data is valid -The other really important, fundamental concept in form validation is whether a form control's data is valid or not (in the case of numerical data, we can also talk about in-range and out-of-range data). Form controls with [constraint limitations](/en-US/docs/Web/HTML/Constraint_validation) can be targeted based on these states. +The other really important, fundamental concept in form validation is whether a form control's data is valid or not (in the case of numerical data, we can also talk about in-range and out-of-range data). Form controls with [constraint limitations](/en-US/docs/Web/HTML/Guides/Constraint_validation) can be targeted based on these states. ### :valid and :invalid @@ -212,7 +269,7 @@ You can target form controls using the {{cssxref(":valid")}} and {{cssxref(":inv - Controls with no constraint validation will always be valid, and therefore matched with `:valid`. - Controls with `required` set on them that have no value are counted as invalid — they will be matched with `:invalid` and `:required`. - Controls with built-in validation, such as `<input type="email">` or `<input type="url">` are (matched with) `:invalid` when the data entered into them does not match the pattern they are looking for (but they are valid when empty). -- Controls whose current value is outside the range limits specified by the [`min`](/en-US/docs/Web/HTML/Element/input#min) and [`max`](/en-US/docs/Web/HTML/Element/input#max) attributes are (matched with) `:invalid`, but also matched by {{cssxref(":out-of-range")}}, as you'll see later on. +- Controls whose current value is outside the range limits specified by the [`min`](/en-US/docs/Web/HTML/Reference/Elements/input#min) and [`max`](/en-US/docs/Web/HTML/Reference/Elements/input#max) attributes are (matched with) `:invalid`, but also matched by {{cssxref(":out-of-range")}}, as you'll see later on. - There are some other ways to make an element matched by `:valid`/`:invalid`, as you'll see in the [Client-side form validation](/en-US/docs/Learn_web_development/Extensions/Forms/Form_validation) article. But we'll keep things simple for now. Let's go in and look at an example of `:valid`/`:invalid` (see [valid-invalid.html](https://mdn.github.io/learning-area/html/forms/pseudo-classes/valid-invalid.html) for the live version, and also check out the [source code](https://github.com/mdn/learning-area/blob/main/html/forms/pseudo-classes/valid-invalid.html)). @@ -268,7 +325,7 @@ Notice how the required text inputs are invalid when empty, but valid when they ### In-range and out-of-range data -As we hinted at above, there are two other related pseudo-classes to consider — {{cssxref(":in-range")}} and {{cssxref(":out-of-range")}}. These match numeric inputs where range limits are specified by the [`min`](/en-US/docs/Web/HTML/Element/input#min) and [`max`](/en-US/docs/Web/HTML/Element/input#max), when their data is inside or outside the specified range, respectively. +As we hinted at above, there are two other related pseudo-classes to consider — {{cssxref(":in-range")}} and {{cssxref(":out-of-range")}}. These match numeric inputs where range limits are specified by the [`min`](/en-US/docs/Web/HTML/Reference/Elements/input#min) and [`max`](/en-US/docs/Web/HTML/Reference/Elements/input#max), when their data is inside or outside the specified range, respectively. > [!NOTE] > Numeric input types are `date`, `month`, `week`, `time`, `datetime-local`, `number`, and `range`. @@ -323,7 +380,7 @@ This is a similar story to what we had before in the `:required` example, except It is possible for the number input to be both required and out-of-range at the same time, so what happens then? Because the `:out-of-range` rule appears later in the source code than the `:required` rule, the [cascade rules](/en-US/docs/Learn_web_development/Core/Styling_basics/Handling_conflicts#understanding_the_cascade) come into play, and the out of range message is shown. -This works quite nicely — when the page first loads, "Required" is shown, along with a red cross and border. When you've typed in a valid age (i.e. in the range of 12-120), the input turns valid. If however, you then change the age entry to one that is out of range, the "Outside allowable value range" message then pops up in place of "Required". +This works quite nicely — when the page first loads, "Required" is shown, along with a red cross and border. When you've typed in a valid age (i.e., in the range of 12-120), the input turns valid. If however, you then change the age entry to one that is out of range, the "Outside allowable value range" message then pops up in place of "Required". > [!NOTE] > To enter an invalid/out-of-range value, you'll have to actually focus the form and type it in using the keyboard. The spinner buttons won't let you increment/decrement the value outside the allowable range. @@ -416,8 +473,8 @@ function toggleBilling() { const billingItems = document.querySelectorAll('#billing input[type="text"]'); // Toggle the billing text fields - for (let i = 0; i < billingItems.length; i++) { - billingItems[i].disabled = !billingItems[i].disabled; + for (const item of billingItems) { + item.disabled = !item.disabled; } } ``` @@ -471,7 +528,7 @@ The full example looks like this: As we've seen in earlier articles in the module, {{HTMLElement("input/radio", "radio buttons")}} and {{HTMLElement("input/checkbox", "checkboxes")}} can be checked or unchecked. But there are a couple of other states to consider too: -- {{cssxref(":default")}}: Matches radios/checkboxes that are checked by default, on page load (i.e. by setting the `checked` attribute on them). These match the {{cssxref(":default")}} pseudo-class, even if the user unchecks them. +- {{cssxref(":default")}}: Matches radios/checkboxes that are checked by default, on page load (i.e., by setting the `checked` attribute on them). These match the {{cssxref(":default")}} pseudo-class, even if the user unchecks them. - {{cssxref(":indeterminate")}}: When radios/checkboxes are neither checked nor unchecked, they are considered _indeterminate_ and will match the {{cssxref(":indeterminate")}} pseudo-class. More on what this means below. ### :checked @@ -587,7 +644,7 @@ See the live result below: > You can also find the example live on GitHub at [radios-checked-indeterminate.html](https://mdn.github.io/learning-area/html/forms/pseudo-classes/radios-checked-indeterminate.html) (also see the [source code](https://github.com/mdn/learning-area/blob/main/html/forms/pseudo-classes/radios-checked-indeterminate.html).) > [!NOTE] -> You can find an [interesting example involving `indeterminate` states](/en-US/docs/Web/HTML/Element/input/checkbox#indeterminate_state_checkboxes) on the [`<input type="checkbox">`](/en-US/docs/Web/HTML/Element/input/checkbox) reference page. +> You can find an [interesting example involving `indeterminate` states](/en-US/docs/Web/HTML/Reference/Elements/input/checkbox#indeterminate_state_checkboxes) on the [`<input type="checkbox">`](/en-US/docs/Web/HTML/Reference/Elements/input/checkbox) reference page. ## More pseudo-classes @@ -595,7 +652,7 @@ There are a number of other pseudo-classes of interest, and we don't have space - The {{cssxref(":focus-within")}} pseudo-class matches an element that has received focus or _contains_ an element that has received focus. This is useful if you want a whole form to highlight in some way when an input inside it is focused. - The {{cssxref(":focus-visible")}} pseudo-class matches focused elements that received focus via keyboard interaction (rather than touch or mouse) — useful if you want to show a different style for keyboard focus compared to mouse (or other) focus. -- The {{cssxref(":placeholder-shown")}} pseudo-class matches {{htmlelement('input')}} and {{htmlelement('textarea')}} elements that have their placeholder showing (i.e. the contents of the [`placeholder`](/en-US/docs/Web/HTML/Element/input#placeholder) attribute) because the value of the element is empty. +- The {{cssxref(":placeholder-shown")}} pseudo-class matches {{htmlelement('input')}} and {{htmlelement('textarea')}} elements that have their placeholder showing (i.e., the contents of the [`placeholder`](/en-US/docs/Web/HTML/Reference/Elements/input#placeholder) attribute) because the value of the element is empty. The following are also interesting, but as yet not well-supported in browsers: @@ -604,15 +661,10 @@ The following are also interesting, but as yet not well-supported in browsers: ## Test your skills! -You've reached the end of this article, but can you remember the most important information? You can find some further tests to verify that you've retained this information before you move on — see [Test your skills: Advanced styling](/en-US/docs/Learn_web_development/Extensions/Forms/Test_your_skills:_Advanced_styling). +You've reached the end of this article, but can you remember the most important information? You can find some further tests to verify that you've retained this information before you move on — see [Test your skills: Advanced styling](/en-US/docs/Learn_web_development/Extensions/Forms/Test_your_skills/Advanced_styling). ## Summary This completes our look at UI pseudo-classes that relate to form inputs. Keep playing with them, and create some fun form styles! Next up, we'll move on to something different — [client-side form validation](/en-US/docs/Learn_web_development/Extensions/Forms/Form_validation). -{{PreviousMenuNext("Learn_web_development/Extensions/Forms/Advanced_form_styling", "Learn_web_development/Extensions/Forms/Form_validation", "Learn_web_development/Extensions/Forms")}} - -### Advanced Topics - -- [How to build custom form controls](/en-US/docs/Learn_web_development/Extensions/Forms/How_to_build_custom_form_controls) -- [Sending forms through JavaScript](/en-US/docs/Learn_web_development/Extensions/Forms/Sending_forms_through_JavaScript) +{{PreviousMenuNext("Learn_web_development/Extensions/Forms/Customizable_select", "Learn_web_development/Extensions/Forms/Form_validation", "Learn_web_development/Extensions/Forms")}} diff --git a/files/en-us/learn_web_development/extensions/forms/user_input_methods/index.md b/files/en-us/learn_web_development/extensions/forms/user_input_methods/index.md index 6b2b3ddf32cd9b9..a2f5f2d6e3a9eff 100644 --- a/files/en-us/learn_web_development/extensions/forms/user_input_methods/index.md +++ b/files/en-us/learn_web_development/extensions/forms/user_input_methods/index.md @@ -2,10 +2,9 @@ title: User input methods and controls slug: Learn_web_development/Extensions/Forms/User_input_methods page-type: guide +sidebar: learnsidebar --- -{{LearnSidebar}} - Web forms require user input. When designing web forms, or really any web content, it's important to consider how users interact with their devices and browsers. Web user input goes beyond simple mouse and keyboard: think of touchscreens for example. In this article, we take a look at the different ways users interact with forms and other web content and provide recommendations for managing user input, real-world examples, and links to further information. @@ -20,7 +19,7 @@ You should always be mindful of keyboard accessibility — many web users only u - To support touch screen displays, [touch events](/en-US/docs/Web/API/Touch_events) interpret finger activity on touch-based user interfaces from mobile devices, to refrigerator panels, to museum kiosk displays. - The [Fullscreen API](/en-US/docs/Web/API/Fullscreen_API) allows you to display your content in fullscreen mode, which is needed if your form is being served on a refrigerator or museum kiosk. -- When you need to create a custom form control, like a rich-text editor, the [`contentEditable`](/en-US/docs/Web/HTML/Global_attributes/contenteditable) attribute enables creating editable controls from normally non-editable HTML elements. +- When you need to create a custom form control, like a rich-text editor, the [`contentEditable`](/en-US/docs/Web/HTML/Reference/Global_attributes/contenteditable) attribute enables creating editable controls from normally non-editable HTML elements. - The [Drag and Drop API](/en-US/docs/Web/API/HTML_Drag_and_Drop_API) allows users to drag elements around a page and drop them in different locations. This can help improve the user experience when it comes to selecting files for upload or reordering content modules within a page. - When screen orientation matters for your layout, you can use [CSS media queries](/en-US/docs/Web/CSS/@media/orientation) to style your forms based on the browser orientation, or even use the [Screen Orientation API](/en-US/docs/Web/API/CSS_Object_Model/Managing_screen_orientation) to read the screen orientation state and perform other actions. @@ -113,16 +112,18 @@ The [Drag & Drop](/en-US/docs/Web/API/HTML_Drag_and_Drop_API) API enables users Here is an example that allows a section of content to be dragged. ```html -<div - draggable="true" - ondragstart="event.dataTransfer.setData('text/plain', 'This text may be dragged')"> - This text <strong>may</strong> be dragged. -</div> +<div draggable="true">This text <strong>may</strong> be dragged.</div> +``` + +```js +document.querySelector("div").addEventListener("dragstart", (event) => { + event.dataTransfer.setData("text/plain", "This text may be dragged."); +}); ``` in which we: -- Set the [`draggable`](/en-US/docs/Web/HTML/Global_attributes/draggable) attribute to `true` on the element that you wish to make draggable. +- Set the [`draggable`](/en-US/docs/Web/HTML/Reference/Global_attributes/draggable) attribute to `true` on the element that you wish to make draggable. - Add a listener for the [`dragstart`](/en-US/docs/Web/API/HTMLElement/dragstart_event) event and set the drag data within this listener. > [!NOTE] @@ -132,7 +133,7 @@ in which we: Generally, you should use a {{HTMLElement("textarea")}} or an appropriate {{HTMLElement("input")}} type within a {{HTMLElement("form")}} to collect data from users, along with a descriptive {{HTMLElement("label")}}. But these elements may not meet your needs. For example, rich text editors capture italic, bold, and normal text, but no native form control captures rich text. This use case requires you to create a custom control that is stylable _and_ editable. There's an attribute for that! -Any DOM element can be made directly editable using the [`contenteditable`](/en-US/docs/Web/HTML/Global_attributes/contenteditable) attribute. +Any DOM element can be made directly editable using the [`contenteditable`](/en-US/docs/Web/HTML/Reference/Global_attributes/contenteditable) attribute. ```css hidden div { @@ -146,18 +147,18 @@ div { <div contenteditable="true">This text can be edited by the user.</div> ``` -The `contenteditable` attribute automatically adds the element to the document's default tabbing order, meaning the [`tabindex`](/en-US/docs/Web/HTML/Global_attributes/tabindex) attribute does not need to be added. However, when using non-semantic elements for data entry when [creating your own form controls](/en-US/docs/Learn_web_development/Extensions/Forms/How_to_build_custom_form_controls), you will need to add JavaScript and [ARIA](/en-US/docs/Web/Accessibility/ARIA) to retrofit the element with form control functionality for everything else. +The `contenteditable` attribute automatically adds the element to the document's default tabbing order, meaning the [`tabindex`](/en-US/docs/Web/HTML/Reference/Global_attributes/tabindex) attribute does not need to be added. However, when using non-semantic elements for data entry when [creating your own form controls](/en-US/docs/Learn_web_development/Extensions/Forms/How_to_build_custom_form_controls), you will need to add JavaScript and [ARIA](/en-US/docs/Web/Accessibility/ARIA) to retrofit the element with form control functionality for everything else. To provide a good user experience, any custom form control you create must be accessible and function like native form controls: -- The element's [`role`](/en-US/docs/Web/Accessibility/ARIA/Roles), [label](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-labelledby), and [description](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-describedby) need to be added with ARIA. +- The element's [`role`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles), [label](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-labelledby), and [description](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-describedby) need to be added with ARIA. - All user input methods needs to be supported, including [keyboard](#keyboard), [mouse](#mouse), [touch](#finger_touch), and [pointer](#pointer_events) events, all described above. - JavaScript is required to handle functionality such as [validation](/en-US/docs/Learn_web_development/Extensions/Forms/Form_validation), [submission](/en-US/docs/Learn_web_development/Extensions/Forms/Sending_and_retrieving_form_data), and [saving](/en-US/docs/Learn_web_development/Extensions/Forms/Sending_forms_through_JavaScript) of user-updated content. {{EmbedLiveSample("contentEditable")}} > [!NOTE] -> Examples and other resources can be found in the [Content Editable guide](/en-US/docs/Web/HTML/Global_attributes/contenteditable). +> Examples and other resources can be found in the [Content Editable guide](/en-US/docs/Web/HTML/Reference/Global_attributes/contenteditable). ## Tutorials @@ -177,4 +178,4 @@ To provide a good user experience, any custom form control you create must be ac - [Screen Orientation](/en-US/docs/Web/API/CSS_Object_Model/Managing_screen_orientation) API - [Fullscreen](/en-US/docs/Web/API/Fullscreen_API) API - [Drag & Drop](/en-US/docs/Web/API/HTML_Drag_and_Drop_API) API -- HTML [`contenteditable`](/en-US/docs/Web/HTML/Global_attributes/contenteditable) attribute +- HTML [`contenteditable`](/en-US/docs/Web/HTML/Reference/Global_attributes/contenteditable) attribute diff --git a/files/en-us/learn_web_development/extensions/forms/your_first_form/index.md b/files/en-us/learn_web_development/extensions/forms/your_first_form/index.md index 3c60effcd13ab9c..f094c861ddbe11a 100644 --- a/files/en-us/learn_web_development/extensions/forms/your_first_form/index.md +++ b/files/en-us/learn_web_development/extensions/forms/your_first_form/index.md @@ -2,9 +2,10 @@ title: Your first form slug: Learn_web_development/Extensions/Forms/Your_first_form page-type: learn-module-chapter +sidebar: learnsidebar --- -{{LearnSidebar}}{{NextMenu("Learn_web_development/Extensions/Forms/How_to_structure_a_web_form", "Learn_web_development/Extensions/Forms")}} +{{NextMenu("Learn_web_development/Extensions/Forms/How_to_structure_a_web_form", "Learn_web_development/Extensions/Forms")}} The first article in our series provides you with your very first experience of creating a web form, including designing a simple form, implementing it using the right HTML form controls and other HTML elements, adding some very simple styling via CSS, and describing how data is sent to a server. We'll expand on each of these subtopics in more detail later on in the module. @@ -71,7 +72,7 @@ All forms start with a {{HTMLelement("form")}} element, like this: <form action="/my-handling-form-page" method="post">…</form> ``` -This element formally defines a form. It's a container element like a {{HTMLelement("section")}} or {{HTMLelement("footer")}} element, but specifically for containing forms; it also supports some specific attributes to configure the way the form behaves. All of its attributes are optional, but it's standard practice to always set at least the [`action`](/en-US/docs/Web/HTML/Element/form#action) and [`method`](/en-US/docs/Web/HTML/Element/form#method) attributes: +This element formally defines a form. It's a container element like a {{HTMLelement("section")}} or {{HTMLelement("footer")}} element, but specifically for containing forms; it also supports some specific attributes to configure the way the form behaves. All of its attributes are optional, but it's standard practice to always set at least the [`action`](/en-US/docs/Web/HTML/Reference/Elements/form#action) and [`method`](/en-US/docs/Web/HTML/Reference/Elements/form#method) attributes: - The `action` attribute defines the location (URL) where the form's collected data should be sent when it is submitted. - The `method` attribute defines which HTTP method to send the data with (usually `get` or `post`). @@ -112,7 +113,7 @@ Update your form code to look like the above. The {{HTMLelement("p")}} elements are there to conveniently structure our code and make styling easier (see later in the article). For usability and accessibility, we include an explicit label for each form control. -Note the use of the [`for`](/en-US/docs/Web/HTML/Attributes/for) attribute on all {{HTMLelement("label")}} elements, which takes as its value the [`id`](/en-US/docs/Web/HTML/Global_attributes/id) of the form control with which it is associated — this is how you associate a form control with its label. +Note the use of the [`for`](/en-US/docs/Web/HTML/Reference/Attributes/for) attribute on all {{HTMLelement("label")}} elements, which takes as its value the [`id`](/en-US/docs/Web/HTML/Reference/Global_attributes/id) of the form control with which it is associated — this is how you associate a form control with its label. There is great benefit to doing this — it associates the label with the form control, enabling mouse, trackpad, and touch device users to click on the label to activate the corresponding control, and it also provides an accessible name for screen readers to read out to their users. You'll find further details of form labels in [How to structure a web form](/en-US/docs/Learn_web_development/Extensions/Forms/How_to_structure_a_web_form). @@ -125,7 +126,7 @@ You'll find more about this in the [Basic native form controls](/en-US/docs/Lear It represents a basic single-line text field that accepts any kind of text input. - For the second input, we use the value {{HTMLelement("input/email", "email")}}, which defines a single-line text field that only accepts a well-formed email address. This turns a basic text field into a kind of "intelligent" field that will perform some validation checks on the data typed by the user. - It also causes a more appropriate keyboard layout for entering email addresses (e.g. with an @ symbol by default) to appear on devices with dynamic keyboards, like smartphones. + It also causes a more appropriate keyboard layout for entering email addresses (e.g., with an @ symbol by default) to appear on devices with dynamic keyboards, like smartphones. You'll find out more about form validation in the [client-side form validation](/en-US/docs/Learn_web_development/Extensions/Forms/Form_validation) article later on. Last but not least, note the syntax of `<input>` vs. `<textarea></textarea>`. @@ -133,7 +134,7 @@ This is one of the oddities of HTML. The `<input>` tag is a {{glossary("void element")}}, meaning that it doesn't need a closing tag. {{HTMLElement("textarea")}} is not a void element, meaning it should be closed with the proper ending tag. This has an impact on a specific feature of forms: the way you define the default value. -To define the default value of an {{HTMLElement("input")}} element you have to use the [`value`](/en-US/docs/Web/HTML/Element/input#value) attribute like this: +To define the default value of an {{HTMLElement("input")}} element you have to use the [`value`](/en-US/docs/Web/HTML/Reference/Elements/input#value) attribute like this: ```html <input type="text" value="by default this element is filled with this text" /> @@ -180,7 +181,7 @@ First of all, add a {{htmlelement("style")}} element to your page, inside your H ```html <style> - … + /* CSS goes here */ </style> ``` @@ -258,7 +259,7 @@ Save and reload, and you'll see that your form should look much less ugly. ## Sending form data to your web server The last part, and perhaps the trickiest, is to handle form data on the server side. -The {{HTMLelement("form")}} element defines where and how to send the data thanks to the [`action`](/en-US/docs/Web/HTML/Element/form#action) and [`method`](/en-US/docs/Web/HTML/Element/form#method) attributes. +The {{HTMLelement("form")}} element defines where and how to send the data thanks to the [`action`](/en-US/docs/Web/HTML/Reference/Elements/form#action) and [`method`](/en-US/docs/Web/HTML/Reference/Elements/form#method) attributes. We provide a `name` attribute for each form control. The names are important on both the client- and server-side; they tell the browser which name to give each piece of data and, on the server side, they let the server handle each piece of data by name. @@ -287,7 +288,7 @@ Let's look at some of our form code again: ``` In our example, the form will send 3 pieces of data named `user_name`, `user_email`, and `user_message`. -That data will be sent to the URL `/my-handling-form-page` using the [HTTP `POST`](/en-US/docs/Web/HTTP/Methods/POST) method. +That data will be sent to the URL `/my-handling-form-page` using the [HTTP `POST`](/en-US/docs/Web/HTTP/Reference/Methods/POST) method. On the server side, the script at the URL `/my-handling-form-page` will receive the data as a list of 3 key/value items contained in the HTTP request. The way this script will handle that data is up to you. @@ -395,8 +396,3 @@ button { That's only the beginning, however — now it's time to take a deeper look. Forms have way more power than what we saw here and the other articles in this module will help you to master the rest. {{NextMenu("Learn_web_development/Extensions/Forms/How_to_structure_a_web_form", "Learn_web_development/Extensions/Forms")}} - -### Advanced Topics - -- [How to build custom form controls](/en-US/docs/Learn_web_development/Extensions/Forms/How_to_build_custom_form_controls) -- [Sending forms through JavaScript](/en-US/docs/Learn_web_development/Extensions/Forms/Sending_forms_through_JavaScript) diff --git a/files/en-us/learn_web_development/extensions/index.md b/files/en-us/learn_web_development/extensions/index.md index 41da2b40be11cf2..5ee38f7529f31de 100644 --- a/files/en-us/learn_web_development/extensions/index.md +++ b/files/en-us/learn_web_development/extensions/index.md @@ -2,10 +2,9 @@ title: Extension modules slug: Learn_web_development/Extensions page-type: landing-page +sidebar: learnsidebar --- -{{LearnSidebar}} - Our **Extension modules** constitute useful additional skills to learn as web developers start to expand their knowledge and develop specialisms. ## Prerequisites @@ -32,7 +31,3 @@ In particular, if you've never done any coding before, we'd recommend the [Your - : Building websites requires HTML, CSS, and JavaScript. To build websites and applications people want to use, which attract and retain users, you need to create a good user experience. Part of good user experience is ensuring the content is quick to load and responsive to user interaction. This is known as **web performance**, and in this module you'll focus on the fundamentals of how to create performant websites. - [Testing](/en-US/docs/Learn_web_development/Extensions/Testing) - : Any codebase past a certain level of complexity needs to have a system of tests associated with it, to make sure that as new code is added, the codebase continues to function correctly and performantly, and continues to meet the users' needs. This module lists the fundamentals that you should start with. -- [Transform and animate CSS](/en-US/docs/Learn_web_development/Extensions/Transform_animate) - - : Animations are a vital part of a good user experience. Subtle usage can make page designs more interesting and appealing, and also enhance usability and perceived performance. -- [Security and privacy](/en-US/docs/Learn_web_development/Extensions/Security_privacy) - - : It is vital to have an understanding of how you can and should protect your data and your user's data from would-be attackers who may try to steal it. This module covers both hardening websites to make it more difficult to steal data, and collecting user data in a respectful way that avoids tracking them or sharing it with unsuitable third parties. diff --git a/files/en-us/learn_web_development/extensions/performance/business_case_for_performance/index.md b/files/en-us/learn_web_development/extensions/performance/business_case_for_performance/index.md index ca21453974b10fd..7caaa9cb39b247d 100644 --- a/files/en-us/learn_web_development/extensions/performance/business_case_for_performance/index.md +++ b/files/en-us/learn_web_development/extensions/performance/business_case_for_performance/index.md @@ -1,10 +1,12 @@ --- title: The business case for web performance +short-title: Performance business case slug: Learn_web_development/Extensions/Performance/business_case_for_performance page-type: learn-module-chapter +sidebar: learnsidebar --- -{{LearnSidebar}}{{PreviousMenuNext("Learn_web_development/Extensions/Performance/CSS", "Learn_web_development/Extensions/Performance/Web_Performance_Basics", "Learn_web_development/Extensions/Performance")}} +{{PreviousMenuNext("Learn_web_development/Extensions/Performance/CSS", "Learn_web_development/Extensions/Performance/Web_Performance_Basics", "Learn_web_development/Extensions/Performance")}} We've discussed the importance of web performance. You've learned what you need to do to optimize for web performance. But how do you convince your clients and/or management to prioritize and invest in performance? In this section, we discuss creating a clear business case to convince decision-makers to make the investment. diff --git a/files/en-us/learn_web_development/extensions/performance/css/index.md b/files/en-us/learn_web_development/extensions/performance/css/index.md index d98fad851b912a5..56b102adc4d68b4 100644 --- a/files/en-us/learn_web_development/extensions/performance/css/index.md +++ b/files/en-us/learn_web_development/extensions/performance/css/index.md @@ -1,10 +1,12 @@ --- title: CSS performance optimization +short-title: Performant CSS slug: Learn_web_development/Extensions/Performance/CSS page-type: learn-module-chapter +sidebar: learnsidebar --- -{{LearnSidebar}}{{PreviousMenuNext("Learn_web_development/Extensions/Performance/html", "Learn_web_development/Extensions/Performance/business_case_for_performance", "Learn_web_development/Extensions/Performance")}} +{{PreviousMenuNext("Learn_web_development/Extensions/Performance/html", "Learn_web_development/Extensions/Performance/business_case_for_performance", "Learn_web_development/Extensions/Performance")}} When developing a website, you need to consider how the browser is handling the CSS on your site. To mitigate any performance issues that CSS might be causing, you should optimize it. For example, you should optimize the CSS to mitigate [render-blocking](/en-US/docs/Glossary/Render_blocking) and minimize the number of required reflows. This article walks you through key CSS performance optimization techniques. @@ -98,7 +100,7 @@ To optimize the CSSOM construction and improve page performance, you can do one - **Cut down on image HTTP requests with CSS sprites**: [CSS sprites](https://css-tricks.com/css-sprites/) is a technique that places several small images (such as icons) that you want to use on your site into a single image file, and then uses different {{cssxref("background-position")}} values to display the chunk of image that you want to show in each different place. This can dramatically cut down on the number of HTTP requests needed to fetch the images. -- **Preload important assets**: You can use [`rel="preload"`](/en-US/docs/Web/HTML/Attributes/rel/preload) to turn {{htmlelement("link")}} elements into preloaders for critical assets. This includes CSS files, fonts, and images: +- **Preload important assets**: You can use [`rel="preload"`](/en-US/docs/Web/HTML/Reference/Attributes/rel/preload) to turn {{htmlelement("link")}} elements into preloaders for critical assets. This includes CSS files, fonts, and images: ```html <link rel="preload" href="style.css" as="style" /> @@ -153,7 +155,7 @@ To further improve performance, you should consider moving animation work off th - 3D transform animations such as [`transform: translateZ()`](/en-US/docs/Web/CSS/transform) and [`rotate3d()`](/en-US/docs/Web/CSS/transform-function/rotate3d). - Elements with certain other properties animated such as [`position: fixed`](/en-US/docs/Web/CSS/position). - Elements with [`will-change`](/en-US/docs/Web/CSS/will-change) applied (see the section below). -- Certain elements that are rendered in their own layer, including [`<video>`](/en-US/docs/Web/HTML/Element/video), [`<canvas>`](/en-US/docs/Web/HTML/Element/canvas), and [`<iframe>`](/en-US/docs/Web/HTML/Element/iframe). +- Certain elements that are rendered in their own layer, including [`<video>`](/en-US/docs/Web/HTML/Reference/Elements/video), [`<canvas>`](/en-US/docs/Web/HTML/Reference/Elements/canvas), and [`<iframe>`](/en-US/docs/Web/HTML/Reference/Elements/iframe). Animation on the GPU can result in improved performance, especially on mobile. However, moving animations to GPU is not always that simple. Read [CSS GPU Animation: Doing It Right](https://www.smashingmagazine.com/2016/12/gpu-animation-doing-it-right/) (smashingmagazine.com, 2016) for a very useful and detailed analysis. @@ -171,7 +173,7 @@ Browsers may set up optimizations before an element is actually changed. These k ## Optimizing for render blocking -CSS can scope styles to particular conditions with media queries. Media queries are important for a responsive web design and help us optimize a critical rendering path. The browser blocks rendering until it parses all of these styles but will not block rendering on styles it knows it will not use, such as the print stylesheets. By splitting the CSS into multiple files based on media queries, you can prevent render blocking during download of unused CSS. To create a non-blocking CSS link, move the not-immediately used styles, such as print styles, into separate file, add a [`<link>`](/en-US/docs/Web/HTML/Element/link) to the HTML mark up, and add a media query, in this case stating it's a print stylesheet. +CSS can scope styles to particular conditions with media queries. Media queries are important for a responsive web design and help us optimize a critical rendering path. The browser blocks rendering until it parses all of these styles but will not block rendering on styles it knows it will not use, such as the print stylesheets. By splitting the CSS into multiple files based on media queries, you can prevent render blocking during download of unused CSS. To create a non-blocking CSS link, move the not-immediately used styles, such as print styles, into separate file, add a [`<link>`](/en-US/docs/Web/HTML/Reference/Elements/link) to the HTML mark up, and add a media query, in this case stating it's a print stylesheet. ```html <!-- Loading and parsing styles.css is render-blocking --> @@ -229,7 +231,7 @@ This is more likely to be beneficial if your `font-family` declaration is hidden You can also consider: -- Using [`rel="preconnect"`](/en-US/docs/Web/HTML/Attributes/rel/preconnect) to make an early connection with the font provider. See [Preconnect to critical third-party origins](https://web.dev/articles/font-best-practices#preconnect_to_critical_third-party_origins) for details. +- Using [`rel="preconnect"`](/en-US/docs/Web/HTML/Reference/Attributes/rel/preconnect) to make an early connection with the font provider. See [Preconnect to critical third-party origins](https://web.dev/articles/font-best-practices#preconnect_to_critical_third-party_origins) for details. - Using the [CSS Font Loading API](/en-US/docs/Web/API/CSS_Font_Loading_API) to customize the font loading behavior via JavaScript. ### Loading only the glyphs you need diff --git a/files/en-us/learn_web_development/extensions/performance/html/index.md b/files/en-us/learn_web_development/extensions/performance/html/index.md index 2fd1289ab7707f2..f13faecb2d2d913 100644 --- a/files/en-us/learn_web_development/extensions/performance/html/index.md +++ b/files/en-us/learn_web_development/extensions/performance/html/index.md @@ -1,10 +1,12 @@ --- title: HTML performance optimization +short-title: Performant HTML slug: Learn_web_development/Extensions/Performance/HTML page-type: learn-module-chapter +sidebar: learnsidebar --- -{{LearnSidebar}} {{PreviousMenuNext("Learn_web_development/Extensions/Performance/Javascript", "Learn_web_development/Extensions/Performance/CSS", "Learn_web_development/Extensions/Performance")}} +{{PreviousMenuNext("Learn_web_development/Extensions/Performance/Javascript", "Learn_web_development/Extensions/Performance/CSS", "Learn_web_development/Extensions/Performance")}} HTML is by default fast and accessible. It is our job, as developers, to ensure that we preserve these two properties when creating or editing HTML code. Complications can occur when, for example, the file size of a {{htmlelement("video")}} embed is too large or when JavaScript parsing blocks the rendering of critical page elements. This article walks you through the key HTML performance features that can drastically improve the quality of your web page. @@ -55,11 +57,11 @@ HTML is simple in terms of performance — it is mostly text, which is small in The so-called "mobile first" technique can ensure that the default layout is for small-screen devices, so mobiles can just download images suitable for their screens, and don't need to take the performance hit of downloading larger desktop images. However, since this is controlled using [media queries](/en-US/docs/Web/CSS/CSS_media_queries/Using_media_queries) in your CSS, it can only positively affect performance of images loaded in CSS. -In the sections below, we'll summarize how to implement responsive replaced elements. You can find a lot more detail about these implementations in the [HTML video and audio](/en-US/docs/Learn_web_development/Core/Structuring_content/HTML_video_and_audio) and [Responsive images](/en-US/docs/Web/HTML/Responsive_images) guides. +In the sections below, we'll summarize how to implement responsive replaced elements. You can find a lot more detail about these implementations in the [HTML video and audio](/en-US/docs/Learn_web_development/Core/Structuring_content/HTML_video_and_audio) and [Responsive images](/en-US/docs/Web/HTML/Guides/Responsive_images) guides. ### Providing different image resolutions via srcset -To provide different resolution versions of the same image depending on the device's resolution and viewport size, you can use the [`srcset`](/en-US/docs/Web/HTML/Element/img#srcset) and [`sizes`](/en-US/docs/Web/HTML/Element/img#sizes) attributes. +To provide different resolution versions of the same image depending on the device's resolution and viewport size, you can use the [`srcset`](/en-US/docs/Web/HTML/Reference/Elements/img#srcset) and [`sizes`](/en-US/docs/Web/HTML/Reference/Elements/img#sizes) attributes. This example provides different size images for different screen widths: @@ -260,14 +262,14 @@ Upon coming across a `rel="preload"` link, the browser will fetch the referenced See the following articles for detailed information on using `rel="preload"`: -- [`rel="preload"`](/en-US/docs/Web/HTML/Attributes/rel/preload) +- [`rel="preload"`](/en-US/docs/Web/HTML/Reference/Attributes/rel/preload) - [Preload critical assets to improve loading speed](https://web.dev/articles/preload-critical-assets) on web.dev (2020) > [!NOTE] > You can use `rel="preload"` to preload CSS and JavaScript files as well. > [!NOTE] -> There are other [`rel`](/en-US/docs/Web/HTML/Attributes/rel) values that are also designed to speed up various aspects of page loading: `dns-prefetch`, `preconnect`, `modulepreload`, `prefetch`, and `prerender`. Go to the linked page and find out what they do. +> There are other [`rel`](/en-US/docs/Web/HTML/Reference/Attributes/rel) values that are also designed to speed up various aspects of page loading: `dns-prefetch`, `preconnect`, `modulepreload`, `prefetch`, and `prerender`. Go to the linked page and find out what they do. ## See also diff --git a/files/en-us/learn_web_development/extensions/performance/index.md b/files/en-us/learn_web_development/extensions/performance/index.md index 281fb9074773d4b..0c21f95958bc2a1 100644 --- a/files/en-us/learn_web_development/extensions/performance/index.md +++ b/files/en-us/learn_web_development/extensions/performance/index.md @@ -2,10 +2,9 @@ title: Web performance slug: Learn_web_development/Extensions/Performance page-type: learn-module +sidebar: learnsidebar --- -{{LearnSidebar}} - {{NextMenu("Learn_web_development/Extensions/Performance/why_web_performance", "Learn_web_development/Extensions")}} Building websites requires HTML, CSS, and JavaScript. To build websites and applications people want to use, which attract and retain users, you need to create a good user experience. Part of good user experience is ensuring the content is quick to load and responsive to user interaction. This is known as **web performance**, and in this module you'll focus on the fundamentals of how to create performant websites. @@ -49,7 +48,7 @@ It would also be helpful to go a bit deeper into these topics, with modules such - [Web performance resources](/en-US/docs/Learn_web_development/Extensions/Performance/Web_Performance_Basics) - : In addition to the front end components of HTML, CSS, JavaScript, and media files, there are features that can make applications slower and features that can make applications subjectively and objectively faster. There are many APIs, developer tools, best practices, and bad practices relating to web performance. Here we'll introduce many of these features at the basic level and provide links to deeper dives to improve performance for each topic. -- [Responsive images](/en-US/docs/Web/HTML/Responsive_images) +- [Responsive images](/en-US/docs/Web/HTML/Guides/Responsive_images) - : In this article, we'll learn about the concept of responsive images — images that work well on devices with widely differing screen sizes, resolutions, and other such features — and look at what tools HTML provides to help implement them. This helps to improve performance across different devices. Responsive images are just one part of [responsive design](/en-US/docs/Learn_web_development/Core/CSS_layout/Responsive_Design), a future CSS topic for you to learn. - [Main web performance section on MDN](/en-US/docs/Web/Performance) - : Our main web performance section — here you'll find much more detail on web performance including overviews of performance APIs, testing and analysis tools, and performance bottleneck gotchas. diff --git a/files/en-us/learn_web_development/extensions/performance/javascript/index.md b/files/en-us/learn_web_development/extensions/performance/javascript/index.md index 3306f3119182f0b..6647c30690b305e 100644 --- a/files/en-us/learn_web_development/extensions/performance/javascript/index.md +++ b/files/en-us/learn_web_development/extensions/performance/javascript/index.md @@ -1,10 +1,12 @@ --- title: JavaScript performance optimization +short-title: Performant JavaScript slug: Learn_web_development/Extensions/Performance/JavaScript page-type: learn-module-chapter +sidebar: learnsidebar --- -{{LearnSidebar}}{{PreviousMenuNext("Learn_web_development/Extensions/Performance/video", "Learn_web_development/Extensions/Performance/HTML", "Learn_web_development/Extensions/Performance")}} +{{PreviousMenuNext("Learn_web_development/Extensions/Performance/video", "Learn_web_development/Extensions/Performance/HTML", "Learn_web_development/Extensions/Performance")}} It is very important to consider how you are using JavaScript on your websites and think about how to mitigate any performance issues that it might be causing. While images and video account for over 70% of the bytes downloaded for the average website, byte per byte, JavaScript has a greater potential for negative performance impact — it can significantly impact download times, rendering performance, and CPU and battery usage. This article introduces tips and techniques for optimizing JavaScript to enhance the performance of your website. @@ -85,7 +87,7 @@ If a script is really important and you are concerned that it is affecting perfo </head> ``` -This works OK, but is render-blocking. A better strategy is to use [`rel="preload"`](/en-US/docs/Web/HTML/Attributes/rel/preload) to create a preloader for critical JavaScript: +This works OK, but is render-blocking. A better strategy is to use [`rel="preload"`](/en-US/docs/Web/HTML/Reference/Attributes/rel/preload) to create a preloader for critical JavaScript: ```html <head> @@ -108,7 +110,7 @@ The preload {{htmlelement("link")}} fetches the JavaScript as soon as possible, or inside your script, in the case of a JavaScript module: ```js -import { function } from "important-module.js"; +import { someFunction } from "important-module.js"; ``` > [!NOTE] diff --git a/files/en-us/learn_web_development/extensions/performance/measuring_performance/index.md b/files/en-us/learn_web_development/extensions/performance/measuring_performance/index.md index f8ffa870da76e3e..7ddf74288393639 100644 --- a/files/en-us/learn_web_development/extensions/performance/measuring_performance/index.md +++ b/files/en-us/learn_web_development/extensions/performance/measuring_performance/index.md @@ -2,9 +2,10 @@ title: Measuring performance slug: Learn_web_development/Extensions/Performance/Measuring_performance page-type: learn-module-chapter +sidebar: learnsidebar --- -{{LearnSidebar}} {{PreviousMenuNext("Learn_web_development/Extensions/Performance/Perceived_performance", "Learn_web_development/Extensions/Performance/Multimedia", "Learn_web_development/Extensions/Performance")}} +{{PreviousMenuNext("Learn_web_development/Extensions/Performance/Perceived_performance", "Learn_web_development/Extensions/Performance/Multimedia", "Learn_web_development/Extensions/Performance")}} Measuring performance provides an important metric to help you assess the success of your app, site, or web service. diff --git a/files/en-us/learn_web_development/extensions/performance/multimedia/index.md b/files/en-us/learn_web_development/extensions/performance/multimedia/index.md index c21484231e50948..2de4e1c1439ddf2 100644 --- a/files/en-us/learn_web_development/extensions/performance/multimedia/index.md +++ b/files/en-us/learn_web_development/extensions/performance/multimedia/index.md @@ -2,9 +2,10 @@ title: "Multimedia: Images" slug: Learn_web_development/Extensions/Performance/Multimedia page-type: learn-module-chapter +sidebar: learnsidebar --- -{{LearnSidebar}}{{PreviousMenuNext("Learn_web_development/Extensions/Performance/measuring_performance", "Learn_web_development/Extensions/Performance/video", "Learn_web_development/Extensions/Performance")}} +{{PreviousMenuNext("Learn_web_development/Extensions/Performance/measuring_performance", "Learn_web_development/Extensions/Performance/video", "Learn_web_development/Extensions/Performance")}} Media, namely images and video, account for over 70% of the bytes downloaded for the average website. In terms of download performance, eliminating media, and reducing file size is the low-hanging fruit. This article looks at optimizing images and video to improve web performance. @@ -49,7 +50,7 @@ Despite being the largest consumer of bandwidth, the impact of image downloading ### Loading strategy -One of the biggest improvements to most websites is [lazy-loading](/en-US/docs/Web/Performance/Guides/Lazy_loading) images beneath the fold, rather than downloading them all on initial page load regardless of whether a visitor scrolls to see them or not. Browsers provide this natively via the [`loading="lazy"`](/en-US/docs/Web/HTML/Element/img#loading) attribute on the `<img>` element, and there are also many client-side JavaScript libraries that can do this. +One of the biggest improvements to most websites is [lazy-loading](/en-US/docs/Web/Performance/Guides/Lazy_loading) images beneath the fold, rather than downloading them all on initial page load regardless of whether a visitor scrolls to see them or not. Browsers provide this natively via the [`loading="lazy"`](/en-US/docs/Web/HTML/Reference/Elements/img#loading) attribute on the `<img>` element, and there are also many client-side JavaScript libraries that can do this. Beyond loading a subset of images, you should look into the format of the images themselves: @@ -74,7 +75,7 @@ PNGs can be saved with three different output combinations: A good online tool for optimizing SVGs is [SVGOMG](https://jakearchibald.github.io/svgomg/). For PNGs there is [ImageOptim online](https://imageoptim.com/online) or [Squoosh](https://squoosh.app/). -With photographic motifs that do not feature transparency, there is a much wider range of formats to choose from. If you want to play it safe, then you would go for well-compressed **Progressive JPEGs**. Progressive JPEGs, in contrast to normal JPEGs, render progressively (hence the name), meaning the user sees a low-resolution version that gains clarity as the image downloads, rather than the image loading at full resolution top-to-bottom or even only rendering once completely downloaded. A good compressor for these would be MozJPEG, e.g. available to use in the online image optimization tool [Squoosh](https://squoosh.app/). A quality setting of 75% should yield decent results. +With photographic motifs that do not feature transparency, there is a much wider range of formats to choose from. If you want to play it safe, then you would go for well-compressed **Progressive JPEGs**. Progressive JPEGs, in contrast to normal JPEGs, render progressively (hence the name), meaning the user sees a low-resolution version that gains clarity as the image downloads, rather than the image loading at full resolution top-to-bottom or even only rendering once completely downloaded. A good compressor for these would be MozJPEG, e.g., available to use in the online image optimization tool [Squoosh](https://squoosh.app/). A quality setting of 75% should yield decent results. Other formats improve on JPEG's capabilities regarding compression, but are not available on every browser: @@ -86,7 +87,7 @@ Other formats improve on JPEG's capabilities regarding compression, but are not - [AVIF](/en-US/docs/Web/Media/Guides/Formats/Image_types#avif_image) — Good choice for both images and animated images due to high performance and royalty-free image format (even more efficient than WebP, but not as widely supported). It is now supported on Chrome, Edge, Opera, and Firefox. [Squoosh](https://squoosh.app/) is a good online tool for converting previous image formats to AVIF. - **JPEG2000** — once to be the successor to JPEG but only supported in Safari. Doesn't support progressive display either. -Given the narrow support for JPEG-XR and JPEG2000, and also taking decode costs into the equation, the only serious contender for JPEG is WebP. Which is why you could offer your images in that flavor too. This can be done via the `<picture>` element with the help of a `<source>` element equipped with a [type attribute](/en-US/docs/Web/HTML/Element/picture#the_type_attribute). +Given the narrow support for JPEG-XR and JPEG2000, and also taking decode costs into the equation, the only serious contender for JPEG is WebP. Which is why you could offer your images in that flavor too. This can be done via the `<picture>` element with the help of a `<source>` element equipped with a [type attribute](/en-US/docs/Web/HTML/Reference/Elements/picture#the_type_attribute). If all of this sounds a bit complicated or feels like too much work for your team then there are also online services that you can use as image CDNs that will automate the serving of the correct image format on the fly, according to the type of device or browser requesting the image. Popular choices include [Cloudinary](https://cloudinary.com/blog/make_all_images_on_your_website_responsive_in_3_easy_steps), [Image Engine](https://imageengine.io/), [ImageKit](https://imagekit.io/docs/image-optimization#automatic-format-conversion), and [imgix](https://www.imgix.com/). @@ -102,7 +103,7 @@ Finally, should you want to include animated images on your page, then know that #### Serving the optimal size -In image delivery the "one size fits all" approach will not yield the best results, meaning that for smaller screens you would want to serve images with smaller resolution and vice versa for larger screens. On top of that, you'd also want to serve higher resolution images to those devices that boast a high DPI screen (e.g. "Retina"). So apart from creating plenty of intermediate image variants you also need a way to serve the right file to the right browser. That's where you would need to upgrade your `<picture>` and `<source>` elements with [media](/en-US/docs/Web/HTML/Element/source#media) and/or [sizes](/en-US/docs/Web/HTML/Element/source#sizes) attributes. A detailed article on how to combine all of these attributes can be found [here](https://www.smashingmagazine.com/2014/05/responsive-images-done-right-guide-picture-srcset/). +In image delivery the "one size fits all" approach will not yield the best results, meaning that for smaller screens you would want to serve images with smaller resolution and vice versa for larger screens. On top of that, you'd also want to serve higher resolution images to those devices that boast a high DPI screen (e.g., "Retina"). So apart from creating plenty of intermediate image variants you also need a way to serve the right file to the right browser. That's where you would need to upgrade your `<picture>` and `<source>` elements with [`media`](/en-US/docs/Web/HTML/Reference/Elements/source#media) and/or [`sizes`](/en-US/docs/Web/HTML/Reference/Elements/source#sizes) attributes. [Responsive images done right: A guide to `<picture>` and `srcset`](https://www.smashingmagazine.com/2014/05/responsive-images-done-right-guide-picture-srcset/) explains in detail how to combine all of these attributes. Two interesting effects to keep in mind regarding high dpi screens is that: diff --git a/files/en-us/learn_web_development/extensions/performance/perceived_performance/index.md b/files/en-us/learn_web_development/extensions/performance/perceived_performance/index.md index 2bf06e7bb0662ff..779cbef505ff6e3 100644 --- a/files/en-us/learn_web_development/extensions/performance/perceived_performance/index.md +++ b/files/en-us/learn_web_development/extensions/performance/perceived_performance/index.md @@ -2,9 +2,10 @@ title: Perceived performance slug: Learn_web_development/Extensions/Performance/Perceived_performance page-type: learn-module-chapter +sidebar: learnsidebar --- -{{LearnSidebar}}{{PreviousMenuNext("Learn_web_development/Extensions/Performance/what_is_web_performance", "Learn_web_development/Extensions/Performance/Measuring_performance", "Learn_web_development/Extensions/Performance")}} +{{PreviousMenuNext("Learn_web_development/Extensions/Performance/what_is_web_performance", "Learn_web_development/Extensions/Performance/Measuring_performance", "Learn_web_development/Extensions/Performance")}} **[Perceived performance](/en-US/docs/Glossary/Perceived_performance)** is a subjective measure of website performance, responsiveness, and reliability. In other words, how fast a website seems to the user. It is harder to quantify and measure than the actual speed of operation, but perhaps even more important. @@ -49,7 +50,7 @@ There is no single metric or test that can be run on a site to evaluate how a us - [First Paint](/en-US/docs/Glossary/First_paint) - : The time to start of first paint operation. Note that this change may not be visible; it can be a simple background color update or something even less noticeable. - [First Contentful Paint](/en-US/docs/Glossary/First_contentful_paint) (FCP) - - : The time until first significant rendering (e.g. of text, foreground or background image, canvas or SVG, etc.). Note that this content is not necessarily useful or meaningful. + - : The time until first significant rendering (e.g., of text, foreground or background image, canvas or SVG, etc.). Note that this content is not necessarily useful or meaningful. - [First Meaningful Paint](/en-US/docs/Glossary/First_meaningful_paint) (FMP) - : The time at which useful content is rendered to the screen. - [Largest Contentful Paint](https://wicg.github.io/largest-contentful-paint/) (LCP) @@ -57,7 +58,7 @@ There is no single metric or test that can be run on a site to evaluate how a us - [Speed index](/en-US/docs/Glossary/Speed_index) - : Measures the average time for pixels on the visible screen to be painted. - [Time to interactive](/en-US/docs/Glossary/Time_to_interactive) - - : Time until the UI is available for user interaction (i.e. the last [long task](/en-US/docs/Glossary/Long_task) of the load process finishes). + - : Time until the UI is available for user interaction (i.e., the last [long task](/en-US/docs/Glossary/Long_task) of the load process finishes). ## Improving performance diff --git a/files/en-us/learn_web_development/extensions/performance/video/index.md b/files/en-us/learn_web_development/extensions/performance/video/index.md index da0f0ea81be055d..5340aab14a3de5d 100644 --- a/files/en-us/learn_web_development/extensions/performance/video/index.md +++ b/files/en-us/learn_web_development/extensions/performance/video/index.md @@ -2,9 +2,10 @@ title: "Multimedia: video" slug: Learn_web_development/Extensions/Performance/video page-type: learn-module-chapter +sidebar: learnsidebar --- -{{LearnSidebar}}{{PreviousMenuNext("Learn_web_development/Extensions/Performance/Multimedia", "Learn_web_development/Extensions/Performance/Javascript", "Learn_web_development/Extensions/Performance")}} +{{PreviousMenuNext("Learn_web_development/Extensions/Performance/Multimedia", "Learn_web_development/Extensions/Performance/Javascript", "Learn_web_development/Extensions/Performance")}} As we learned in the previous section, media, namely images and video, account for over 70% of the bytes downloaded for the average website. We have already taken a look at optimizing images. This article looks at optimizing video to improve web performance. diff --git a/files/en-us/learn_web_development/extensions/performance/web_performance_basics/index.md b/files/en-us/learn_web_development/extensions/performance/web_performance_basics/index.md index 3ed57fb3364dba6..6917db2bb5aa57c 100644 --- a/files/en-us/learn_web_development/extensions/performance/web_performance_basics/index.md +++ b/files/en-us/learn_web_development/extensions/performance/web_performance_basics/index.md @@ -2,9 +2,10 @@ title: Web performance resources slug: Learn_web_development/Extensions/Performance/Web_Performance_Basics page-type: learn-module-chapter +sidebar: learnsidebar --- -{{LearnSidebar}}{{PreviousMenu("Learn_web_development/Extensions/Performance/business_case_for_performance", "Learn_web_development/Extensions/Performance")}} +{{PreviousMenu("Learn_web_development/Extensions/Performance/business_case_for_performance", "Learn_web_development/Extensions/Performance")}} There are many [reasons](https://web.dev/learn/performance/why-speed-matters) why your website should perform as well as possible. Below is a quick review of best practices, tools, APIs with links to provide more information about each topic. @@ -12,33 +13,40 @@ Below is a quick review of best practices, tools, APIs with links to provide mor ## Best practices - Start with learning the [critical rendering path](/en-US/docs/Web/Performance/Guides/Critical_rendering_path) of the browser. Knowing this will help you understand how to improve the performance of the site. -- Using _resource hints_ such as [`rel=preconnect`](/en-US/docs/Web/HTML/Attributes/rel/preconnect), [`rel=dns-prefetch`](/en-US/docs/Web/HTML/Attributes/rel/dns-prefetch), [`rel=prefetch`](/en-US/docs/Web/HTML/Attributes/rel/prefetch), [`rel=preload`](/en-US/docs/Web/HTML/Attributes/rel/preload). +- Using _resource hints_ such as [`rel=preconnect`](/en-US/docs/Web/HTML/Reference/Attributes/rel/preconnect), [`rel=dns-prefetch`](/en-US/docs/Web/HTML/Reference/Attributes/rel/dns-prefetch), [`rel=prefetch`](/en-US/docs/Web/HTML/Reference/Attributes/rel/prefetch), [`rel=preload`](/en-US/docs/Web/HTML/Reference/Attributes/rel/preload). - Keep the size of JavaScript to a [minimum](https://medium.com/@addyosmani/the-cost-of-javascript-in-2018-7d8950fbb5d4). Only use as much JavaScript as needed for the current page. - [CSS](/en-US/docs/Learn_web_development/Extensions/Performance/CSS) performance factors - Use {{Glossary("HTTP_2", "HTTP/2")}} on your server (or CDN). - Use a CDN for resources which can reduce load times significantly. - Compress your resources using [gzip](https://www.gnu.org/software/gzip/), [Brotli](https://github.com/google/brotli), and [Zopfli](https://github.com/google/zopfli). - Image optimization (use CSS animation, or SVG if possible). -- Lazy loading parts of your application outside the viewport. If you do, have a backup plan for SEO (e.g., render full page for bot traffic); for example, by using the [`loading`](/en-US/docs/Web/HTML/Element/img#loading) attribute on the {{HTMLElement("img")}} element +- Lazy loading parts of your application outside the viewport. If you do, have a backup plan for SEO (e.g., render full page for bot traffic); for example, by using the [`loading`](/en-US/docs/Web/HTML/Reference/Elements/img#loading) attribute on the {{HTMLElement("img")}} element - It is also crucial to realize what is really important to your users. It might not be absolute timing, but [user perception](/en-US/docs/Learn_web_development/Extensions/Performance/Perceived_performance). ## Quick Wins ### CSS -Web performance is all about user experience and perceived performance. As we learned in the [critical rendering path](/en-US/docs/Web/Performance/Guides/Critical_rendering_path) document, linking CSS with a traditional link tag with rel="stylesheet" is synchronous and blocks rendering. Optimize the rendering of your page by removing blocking CSS. +Web performance is all about user experience and perceived performance. As we learned in the [critical rendering path](/en-US/docs/Web/Performance/Guides/Critical_rendering_path) document, linking CSS with a traditional link tag with `rel="stylesheet"` is synchronous and blocks rendering. Optimize the rendering of your page by removing blocking CSS. -To load CSS asynchronously one can set the media type to print and then change to all once loaded. The following snippet includes an onload attribute, requiring JavaScript, so it is important to include a noscript tag with a traditional fallback. +To load CSS asynchronously one can set the media type to `print` and then change to `all` once loaded. This requires JavaScript, so it is important to include a `<noscript>` tag with a traditional fallback. ```html <link + id="my-stylesheet" rel="stylesheet" href="/path/to/my.css" - media="print" - onload="this.media='all'" /> + media="print" /> <noscript><link rel="stylesheet" href="/path/to/my.css" /></noscript> ``` +```js +const stylesheet = document.getElementById("my-stylesheet"); +stylesheet.addEventListener("load", () => { + stylesheet.media = "all"; +}); +``` + The downside with this approach is the flash of unstyled text (FOUT.) The simplest way to address this is by inlining CSS that is required for any content that is rendered above the fold, or what you see in the browser viewport before scrolling. These styles will improve perceived performance as the CSS does not require a file request. ```html @@ -49,7 +57,7 @@ The downside with this approach is the flash of unstyled text (FOUT.) The simple ### JavaScript -Avoid JavaScript blocking by using the [async](/en-US/docs/Web/HTML/Element/script) or [defer](/en-US/docs/Web/HTML/Element/script) attributes, or link JavaScript assets after the page's DOM elements. JavaScript only block rendering for elements that appear after the script tag in the DOM tree. +Avoid JavaScript blocking by using the [`async`](/en-US/docs/Web/HTML/Reference/Elements/script) or [`defer`](/en-US/docs/Web/HTML/Reference/Elements/script) attributes, or link JavaScript assets after the page's DOM elements. JavaScript only block rendering for elements that appear after the script tag in the DOM tree. ### Web Fonts diff --git a/files/en-us/learn_web_development/extensions/performance/what_is_web_performance/index.md b/files/en-us/learn_web_development/extensions/performance/what_is_web_performance/index.md index f972128539efadd..2c7d712621f2bed 100644 --- a/files/en-us/learn_web_development/extensions/performance/what_is_web_performance/index.md +++ b/files/en-us/learn_web_development/extensions/performance/what_is_web_performance/index.md @@ -2,11 +2,12 @@ title: What is web performance? slug: Learn_web_development/Extensions/Performance/What_is_web_performance page-type: learn-module-chapter +sidebar: learnsidebar --- -{{LearnSidebar}}{{PreviousMenuNext("Learn_web_development/Extensions/Performance/why_web_performance", "Learn_web_development/Extensions/Performance/Perceived_performance", "Learn_web_development/Extensions/Performance")}} +{{PreviousMenuNext("Learn_web_development/Extensions/Performance/why_web_performance", "Learn_web_development/Extensions/Performance/Perceived_performance", "Learn_web_development/Extensions/Performance")}} -Web performance is all about making websites fast, including making slow processes _seem_ fast. Does the site load quickly, allow the user to start interacting with it quickly, and offer reassuring feedback if something is taking time to load (e.g. a loading spinner)? Are scrolling and animations smooth? This article provides a brief introduction to objective, measurable web performance\*, looking at what technologies, techniques, and tools are involved in web optimization. +Web performance is all about making websites fast, including making slow processes _seem_ fast. Does the site load quickly, allow the user to start interacting with it quickly, and offer reassuring feedback if something is taking time to load (e.g., a loading spinner)? Are scrolling and animations smooth? This article provides a brief introduction to objective, measurable web performance\*, looking at what technologies, techniques, and tools are involved in web optimization. <table> <tbody> @@ -37,7 +38,7 @@ _\* versus subjective, [perceived performance](/en-US/docs/Learn_web_development Web performance is the objective measurement and perceived user experience of a website or application. This includes the following major areas: -- **Reducing overall load time**: How long does it take the files required to render the website to download on to the user's computer? This tends to be affected by [latency](/en-US/docs/Web/Performance/Guides/Understanding_latency), how big your files are, how many files there are, and other factors besides. A general strategy is to make your files as small as possible, reduce the number of HTTP requests made as much as possible, and employ clever loading techniques (such as [preload](/en-US/docs/Web/HTML/Attributes/rel/preload)) to make files available sooner. +- **Reducing overall load time**: How long does it take the files required to render the website to download on to the user's computer? This tends to be affected by [latency](/en-US/docs/Web/Performance/Guides/Understanding_latency), how big your files are, how many files there are, and other factors besides. A general strategy is to make your files as small as possible, reduce the number of HTTP requests made as much as possible, and employ clever loading techniques (such as [preload](/en-US/docs/Web/HTML/Reference/Attributes/rel/preload)) to make files available sooner. - **Making the site usable as soon as possible**: This basically means loading your website assets in a sensible order so that the user can start to actually use it really quickly. Any other assets can continue to load in the background while the user gets on with primary tasks, and sometimes we only load assets when they are actually needed (this is called [lazy loading](/en-US/docs/Web/Performance/Guides/Lazy_loading)). The measurement of how long it takes the site to get to a usable start after it has started loading is called [time to interactive](/en-US/docs/Glossary/Time_to_interactive). - **Smoothness and interactivity**: Does the application feel reliable and pleasurable to use? Is the scrolling smooth? Are buttons clickable? Are pop-ups quick to open up, and do they animate smoothly as they do so? There are a lot of best practices to consider in making apps feel smooth, for example using CSS animations rather than JavaScript for animation, and minimizing the number of repaints the UI requires due to changes in the DOM. - **[Perceived performance](/en-US/docs/Learn_web_development/Extensions/Performance/Perceived_performance)**: How fast a website seems to the user has a greater impact on user experience than how fast the website actually is. How a user perceives your performance is as important, or perhaps more important, than any objective statistic, but it's subjective, and not as readily measurable. Perceived performance is user perspective, not a metric. Even if an operation is going to take a long time (because of latency or whatever), it is possible to keep the user engaged while they wait by showing a loading spinner, or a series of useful hints and tips (or jokes, or whatever else you think might be appropriate). Such an approach is much better than just showing nothing, which will make it feel like it is taking a lot longer and possibly lead to your users thinking it is broken and giving up. @@ -56,7 +57,7 @@ To effectively understand web performance, the issues behind it, and the major t - **Source order**. Your HTML index file's source order can significantly affect performance. The download of additional assets linked to from the index file is generally sequential, based on source order, but this can be manipulated and should definitely be optimized, realizing that some resources block additional downloads until their content is parsed and executed. - **The critical path**. This is the process that the browser uses to construct the web document once the files have been downloaded from the server. The browser follows a well-defined set of steps, and optimizing the critical rendering path to prioritize the display of content that relates to the current user action will lead to significant improvements in content rendering time. See [Critical rendering path](/en-US/docs/Web/Performance/Guides/Critical_rendering_path) for more information. - The **document object model**. The document object model, or DOM, is a tree structure that represents the content and elements of your HTML as a tree of nodes. This includes all the HTML attributes and the relationships between the nodes. Extensive DOM manipulation after the pages has loaded (e.g., adding, deleting, or moving of nodes) can affect performance, so it is worth understanding how the DOM works, and how such issues can be mitigated. Find out more at [Document Object Model](/en-US/docs/Web/API/Document_Object_Model). -- **Latency**. We mention this briefly earlier on, but in brief, latency is the time it takes for your website assets to travel from the server to a user's computer. There is overhead involved in establishing TCP and HTTP connections, and some unavoidable latency in pushing the request and response bytes back and forth across the network, but there are certain ways to reduce latency (e.g. reducing the number of HTTP request you make by downloading fewer files, using a [CDN](/en-US/docs/Glossary/CDN) to make your site more universally performant across the world, and using HTTP/2 to serve files more efficiently from the server). You can read all about this topic at [Understanding Latency](/en-US/docs/Web/Performance/Guides/Understanding_latency). +- **Latency**. We mention this briefly earlier on, but in brief, latency is the time it takes for your website assets to travel from the server to a user's computer. There is overhead involved in establishing TCP and HTTP connections, and some unavoidable latency in pushing the request and response bytes back and forth across the network, but there are certain ways to reduce latency (e.g., reducing the number of HTTP request you make by downloading fewer files, using a [CDN](/en-US/docs/Glossary/CDN) to make your site more universally performant across the world, and using HTTP/2 to serve files more efficiently from the server). You can read all about this topic at [Understanding Latency](/en-US/docs/Web/Performance/Guides/Understanding_latency). ## Conclusion diff --git a/files/en-us/learn_web_development/extensions/performance/why_web_performance/index.md b/files/en-us/learn_web_development/extensions/performance/why_web_performance/index.md index 57f5a5be95dcff4..4c605c56ea6d834 100644 --- a/files/en-us/learn_web_development/extensions/performance/why_web_performance/index.md +++ b/files/en-us/learn_web_development/extensions/performance/why_web_performance/index.md @@ -2,9 +2,10 @@ title: The "why" of web performance slug: Learn_web_development/Extensions/Performance/why_web_performance page-type: learn-module-chapter +sidebar: learnsidebar --- -{{LearnSidebar}}{{NextMenu("Learn_web_development/Extensions/Performance/What_is_web_performance", "Learn_web_development/Extensions/Performance")}} +{{NextMenu("Learn_web_development/Extensions/Performance/What_is_web_performance", "Learn_web_development/Extensions/Performance")}} Web performance is all about making websites fast, including making slow processes _seem_ fast. This article provides an introduction into why web performance is important to site visitors and for your business goals. @@ -46,7 +47,7 @@ As an example, consider the loading experience of CNN.com, which at the time of A 22.6 MB site could take up to 83 seconds to load on a 3G network, with [`DOMContentLoaded`](/en-US/docs/Web/API/Document/DOMContentLoaded_event) (meaning the site's base HTML structure) at 31.86 seconds. -And it isn't just the time taken to download that is a major problem. In some regions, internet connections are billed per megabyte, making large downloads prohibitively expensive. Our example 22.6 MB CNN.com experience would cost a significant portion of a mobile data user's daily allowance or even lead to high charges in certain international roaming plans.(See [how much your site costs to download](https://whatdoesmysitecost.com/).) +And it isn't just the time taken to download that is a major problem. In some regions, internet connections are billed per megabyte, making large downloads prohibitively expensive. Our example 22.6 MB CNN.com experience would cost a significant portion of a mobile data user's daily allowance or even lead to high charges in certain international roaming plans. ### Improve conversion rates diff --git a/files/en-us/learn_web_development/extensions/security_privacy/index.md b/files/en-us/learn_web_development/extensions/security_privacy/index.md deleted file mode 100644 index 5778b02e3fb3cf9..000000000000000 --- a/files/en-us/learn_web_development/extensions/security_privacy/index.md +++ /dev/null @@ -1,109 +0,0 @@ ---- -title: Security and privacy -slug: Learn_web_development/Extensions/Security_privacy -page-type: learn-module ---- - -{{LearnSidebar}} - -> [!NOTE] -> As you'll see below, this module is currently only a curriculum outline/syllabus, with some links provided to starter guides. We are intending to convert this into a full course in the future, as time allows. - -It is vital to have an understanding of how you can and should protect your data and your user's data from would-be attackers who may try to steal it. This module covers both hardening websites to make it more difficult to steal data, and collecting user data in a respectful way that avoids tracking them or sharing it with unsuitable third parties. - -## Prerequisites - -Before starting this module, you should be familiar with [HTML](/en-US/docs/Learn_web_development/Core/Structuring_content) and [CSS](/en-US/docs/Learn_web_development/Core/Styling_basics). - -## Learning outcomes - -### 5.1 Security and privacy basics - -> [!NOTE] -> -> - Conforming to all of the criteria in this module is not going to result in a student being a qualified security engineer, but equally it is important for web developers to understand the basics of web security and privacy. -> - It is also important for students to understand that a lot of security issues are caused by problems with server-side code, or a combination of client-side and server-side code. A lot of code should present very few security risks, provided the browser is doing its job properly. - -Learning outcomes: - -- Understand the difference between security and privacy. - -- Understand the general HTTP model from a high-level. - -- Learn what HTTPS is, and why it is important. - -- Same-origin security: - - - Why this is fundamental to the web. - - - Ways of working around it safely, such as Cross-Origin Resource Sharing (CORS). - -- How cookies are stored, and their security and privacy implications, such as tracking. - -- Learn about situations where security issues generally occur: - - - When asking users to provide sensitive data (such as passwords or credit card data) and transmitting it to a server. - - - When requesting data from a server. - - - When transmitting data between servers (for example, if a server requests data from a web service). - - - When preserving user state by setting a cookie or other mechanisms. - -- Learn about common security threats and how to mitigate them: - - - Cross-site scripting (XSS). - - - Cross-site request forgery (CSRF). - - - Clickjacking. - - - Denial of service (DoS). - -- Understand the purpose of other important technologies, such as: - - - Content Security Policy (CSP). - - - Permissions-Policy. - - - The web model for user activation of "powerful features" (aka transient activation). - -### 5.2 Data protection laws - -Learning outcomes: - -- Understand fundamental concepts related to user privacy: - - - Personally identifiable information (PII). - - - Confidentiality. - - - Tracking. - - - Fingerprinting. - -- Be aware of regional privacy laws, for example: - - - [General Data Protection Regulation (GDPR)](https://eur-lex.europa.eu/legal-content/EN/TXT/HTML/?uri=CELEX:32016R0679&from=EN) (EU). - - - [Data Protection Act 2018](https://www.gov.uk/data-protection) (UK), gov.uk. - - - [California Consumer Privacy Act (2018)](https://www.oag.ca.gov/privacy/ccpa) (US, CA), ca.gov. - - - [Children's Online Privacy Protection Rule (COPPA)](https://www.ftc.gov/legal-library/browse/rules/childrens-online-privacy-protection-rule-coppa) (US), ftc.gov. - -- Understand how to comply with such laws, in terms of practical implementation. - -> [!NOTE]: -> Conforming to the above criteria does not require students to become legal experts in privacy laws, but they should understand the implications of these laws, and how that affects their work. - -## Resources - -- [Security on the web](/en-US/docs/Web/Security) -- [Website security](/en-US/docs/Learn_web_development/Extensions/Server-side/First_steps/Website_security) -- [Privacy on the web](/en-US/docs/Web/Privacy) -- [Complete guide to GDPR compliance](https://gdpr.eu/), gdpr.eu - -## See also - -- [Learn Privacy](https://web.dev/learn/privacy/), web.dev (2023) diff --git a/files/en-us/learn_web_development/extensions/server-side/apache_configuration_htaccess/index.md b/files/en-us/learn_web_development/extensions/server-side/apache_configuration_htaccess/index.md index 3f3f93cec7a678e..1e608eae851f4dc 100644 --- a/files/en-us/learn_web_development/extensions/server-side/apache_configuration_htaccess/index.md +++ b/files/en-us/learn_web_development/extensions/server-side/apache_configuration_htaccess/index.md @@ -2,10 +2,9 @@ title: "Apache Configuration: .htaccess" slug: Learn_web_development/Extensions/Server-side/Apache_Configuration_htaccess page-type: guide +sidebar: learnsidebar --- -{{LearnSidebar}} - Apache .htaccess files allow users to configure directories of the web server they control without modifying the main configuration file. While this is useful it's important to note that using `.htaccess` files slows down Apache, so, if you have access to the main server configuration file (which is usually called `httpd.conf`), you should add this logic there under a `Directory` block. @@ -79,7 +78,7 @@ One alternative is to explicitly state what domains have access to the content o ### Cross-origin images -As reported in the [Chromium Blog](https://blog.chromium.org/2011/07/using-cross-domain-images-in-webgl-and.html) and documented in [Allowing cross-origin use of images and canvas](/en-US/docs/Web/HTML/CORS_enabled_image) can lead to [fingerprinting](/en-US/docs/Glossary/Fingerprinting) attacks. +As reported in the [Chromium Blog](https://blog.chromium.org/2011/07/using-cross-domain-images-in-webgl-and.html) and documented in [Allowing cross-origin use of images and canvas](/en-US/docs/Web/HTML/How_to/CORS_enabled_image) can lead to [fingerprinting](/en-US/docs/Glossary/Fingerprinting) attacks. To mitigate the possibility of these attacks, you should use the `crossorigin` attribute in the images you request and the code snippet below in your `.htaccess` to set the CORS header from the server. @@ -108,7 +107,7 @@ Google Chrome's [Google Fonts troubleshooting guide](https://developers.google.c The [Resource Timing Level 1](https://www.w3.org/TR/resource-timing/) specification defines an interface for web applications to access the complete timing information for resources in a document. -The [Timing-Allow-Origin](/en-US/docs/Web/HTTP/Headers/Timing-Allow-Origin) response header specifies origins that are allowed to see values of attributes retrieved via features of the Resource Timing API, which would otherwise be reported as zero due to cross-origin restrictions. +The [Timing-Allow-Origin](/en-US/docs/Web/HTTP/Reference/Headers/Timing-Allow-Origin) response header specifies origins that are allowed to see values of attributes retrieved via features of the Resource Timing API, which would otherwise be reported as zero due to cross-origin restrictions. If a resource isn't served with a `Timing-Allow-Origin` or if the header does not include the origin after making the request, some attributes of the `PerformanceResourceTiming` object will be set to zero. @@ -465,7 +464,7 @@ Be aware that Strict Transport Security is not revokable, and you must ensure be - If you want to use the `<base>` element, then use `base-uri 'self'` instead 3. Only allows form submissions are from the current origin with: `form-action 'self'` -4. Prevents all websites (including your own) from embedding your webpages within e.g. the `<iframe>` or `<object>` element by setting: `frame-ancestors 'none'`. +4. Prevents all websites (including your own) from embedding your webpages within e.g., the `<iframe>` or `<object>` element by setting: `frame-ancestors 'none'`. - The `frame-ancestors` directive helps avoid [clickjacking](/en-US/docs/Web/Security/Attacks/Clickjacking) attacks and is similar to the `X-Frame-Options` header - Browsers that support the CSP header will ignore `X-Frame-Options` if `frame-ancestors` is also specified @@ -474,7 +473,7 @@ Be aware that Strict Transport Security is not revokable, and you must ensure be - **`upgrade-insecure-requests` does not ensure HTTPS for the top-level navigation. If you want to force the website itself to be loaded over HTTPS you must include the `Strict-Transport-Security` header** -6. Includes the `Content-Security-Policy` header in all responses that are able to execute scripting. This includes the commonly used file types: HTML, XML and PDF documents. Although JavaScript files can not execute scripts in a "browsing context", they are included to target [web workers](/en-US/docs/Web/HTTP/Headers/Content-Security-Policy#csp_in_workers) +6. Includes the `Content-Security-Policy` header in all responses that are able to execute scripting. This includes the commonly used file types: HTML, XML and PDF documents. Although JavaScript files can not execute scripts in a "browsing context", they are included to target [web workers](/en-US/docs/Web/HTTP/Reference/Headers/Content-Security-Policy#csp_in_workers) Some older browsers would try and guess the content type of a resource, even when it isn't properly set up on the server configuration. This reduces exposure to drive-by download attacks and cross-origin data leaks. @@ -505,7 +504,7 @@ Use services like the ones below to check your `Referrer-Policy`: ## Disable `TRACE` HTTP Method -The [TRACE](/en-US/docs/Web/HTTP/Methods/TRACE) method, while seemingly harmless, can be successfully leveraged in some scenarios to steal legitimate users' credentials. See [A Cross-Site Tracing (XST) attack](https://owasp.org/www-community/attacks/Cross_Site_Tracing) and [OWASP Web Security Testing Guide](https://owasp.org/www-project-web-security-testing-guide/v41/4-Web_Application_Security_Testing/02-Configuration_and_Deployment_Management_Testing/06-Test_HTTP_Methods#test-xst-potential) +The [TRACE](/en-US/docs/Web/HTTP/Reference/Methods/TRACE) method, while seemingly harmless, can be successfully leveraged in some scenarios to steal legitimate users' credentials. See [A Cross-Site Tracing (XST) attack](https://owasp.org/www-community/attacks/Cross_Site_Tracing) and [OWASP Web Security Testing Guide](https://owasp.org/www-project-web-security-testing-guide/v41/4-Web_Application_Security_Testing/02-Configuration_and_Deployment_Management_Testing/06-Test_HTTP_Methods#test-xst-potential) Modern browsers now prevent TRACE requests made via JavaScript, however, other ways of sending TRACE requests with browsers have been discovered, such as using Java. @@ -622,7 +621,7 @@ Map the following filename extensions to the specified encoding type using [AddE ## Cache expiration -Serve resources with a far-future expiration date using the [mod_expires](https://httpd.apache.org/docs/current/mod/mod_expires.html) module, and [Cache-Control](/en-US/docs/Web/HTTP/Headers/Cache-Control) and [Expires](/en-US/docs/Web/HTTP/Headers/Expires) headers. +Serve resources with a far-future expiration date using the [mod_expires](https://httpd.apache.org/docs/current/mod/mod_expires.html) module, and [Cache-Control](/en-US/docs/Web/HTTP/Reference/Headers/Cache-Control) and [Expires](/en-US/docs/Web/HTTP/Reference/Headers/Expires) headers. ```apacheconf <IfModule mod_expires.c> diff --git a/files/en-us/learn_web_development/extensions/server-side/configuring_server_mime_types/index.md b/files/en-us/learn_web_development/extensions/server-side/configuring_server_mime_types/index.md index d8e7093a97a212d..ad5c65e7abdbf69 100644 --- a/files/en-us/learn_web_development/extensions/server-side/configuring_server_mime_types/index.md +++ b/files/en-us/learn_web_development/extensions/server-side/configuring_server_mime_types/index.md @@ -2,10 +2,9 @@ title: Properly configuring server MIME types slug: Learn_web_development/Extensions/Server-side/Configuring_server_MIME_types page-type: guide +sidebar: learnsidebar --- -{{LearnSidebar}} - MIME types describe the media type of content, either in email, or served by web servers or web applications. They are intended to help provide a hint as to how the content should be processed and displayed. Examples of MIME types: @@ -62,7 +61,7 @@ When looking for information about JavaScript MIME types, you may see several MI While browsers may support any, some, or all of these alternative MIME types, you should **only** use `text/javascript` to indicate the MIME type of JavaScript files. > [!NOTE] -> See [MIME types (IANA media types)](/en-US/docs/Web/HTTP/MIME_types) for more information. +> See [MIME types (IANA media types)](/en-US/docs/Web/HTTP/Guides/MIME_types) for more information. ## How to determine the MIME type to set @@ -77,7 +76,7 @@ There are several ways to determine the correct MIME type value to be used to se - In Firefox - Load the file and go to **Tools > Page Info** to get the content type for the page you accessed. - - You can also go to **Tools > Web Developer > Network** and reload the page. The request tab gives you a list of all the resources the page loaded. Clicking on any resource will list all the information available, including the page's [`Content-Type`](/en-US/docs/Web/HTTP/Headers/Content-Type) header. + - You can also go to **Tools > Web Developer > Network** and reload the page. The request tab gives you a list of all the resources the page loaded. Clicking on any resource will list all the information available, including the page's [`Content-Type`](/en-US/docs/Web/HTTP/Reference/Headers/Content-Type) header. - In Chrome @@ -109,6 +108,6 @@ Trying to instead set it with just `header('application/pdf')` won't work. - [IANA | MIME Media Types](https://www.iana.org/assignments/media-types/media-types.xhtml) - [Hypertext Transfer Protocol — HTTP/1.1](https://www.w3.org/Protocols/rfc2616/rfc2616.html) -- [MIME types (IANA media types)](/en-US/docs/Web/HTTP/MIME_types) +- [MIME types (IANA media types)](/en-US/docs/Web/HTTP/Guides/MIME_types) - [Apache vs Nginx: Practical Considerations](https://www.digitalocean.com/community/tutorials/apache-vs-nginx-practical-considerations) - [Migrate Apache .htaccess to Nginx server block](https://barryvanveen.nl/articles/56-migrate-apache-htaccess-to-nginx-server-block/) diff --git a/files/en-us/learn_web_development/extensions/server-side/django/admin_site/index.md b/files/en-us/learn_web_development/extensions/server-side/django/admin_site/index.md index ce6402a8e9758d8..52b4c184774764a 100644 --- a/files/en-us/learn_web_development/extensions/server-side/django/admin_site/index.md +++ b/files/en-us/learn_web_development/extensions/server-side/django/admin_site/index.md @@ -1,10 +1,12 @@ --- title: "Django Tutorial Part 4: Django admin site" +short-title: "4: Django admin site" slug: Learn_web_development/Extensions/Server-side/Django/Admin_site page-type: learn-module-chapter +sidebar: learnsidebar --- -{{LearnSidebar}}{{PreviousMenuNext("Learn_web_development/Extensions/Server-side/Django/Models", "Learn_web_development/Extensions/Server-side/Django/Home_page", "Learn_web_development/Extensions/Server-side/Django")}} +{{PreviousMenuNext("Learn_web_development/Extensions/Server-side/Django/Models", "Learn_web_development/Extensions/Server-side/Django/Home_page", "Learn_web_development/Extensions/Server-side/Django")}} Now that we've created models for the [LocalLibrary](/en-US/docs/Learn_web_development/Extensions/Server-side/Django/Tutorial_local_library_website) website, we'll use the Django Admin site to add some "real" book data. First we'll show you how to register the models with the admin site, then we'll show you how to login and create some data. At the end of the article we will show some of the ways you can further improve the presentation of the Admin site. @@ -29,7 +31,7 @@ Now that we've created models for the [LocalLibrary](/en-US/docs/Learn_web_devel ## Overview -The Django admin _application_ can use your models to automatically build a site area that you can use to create, view, update, and delete records. This can save you a lot of time during development, making it very easy to test your models and get a feel for whether you have the _right_ data. The admin application can also be useful for managing data in production, depending on the type of website. The Django project recommends it only for internal data management (i.e. just for use by admins, or people internal to your organization), as the model-centric approach is not necessarily the best possible interface for all users, and exposes a lot of unnecessary detail about the models. +The Django admin _application_ can use your models to automatically build a site area that you can use to create, view, update, and delete records. This can save you a lot of time during development, making it very easy to test your models and get a feel for whether you have the _right_ data. The admin application can also be useful for managing data in production, depending on the type of website. The Django project recommends it only for internal data management (i.e., just for use by admins, or people internal to your organization), as the model-centric approach is not necessarily the best possible interface for all users, and exposes a lot of unnecessary detail about the models. All the configuration required to include the admin application in your website was done automatically when you [created the skeleton project](/en-US/docs/Learn_web_development/Extensions/Server-side/Django/skeleton_website) (for information about actual dependencies needed, see the [Django docs here](https://docs.djangoproject.com/en/5.0/ref/contrib/admin/)). As a result, all you **must** do to add your models to the admin application is to _register_ them. At the end of this article we'll provide a brief demonstration of how you might further configure the admin area to better display our model data. @@ -80,7 +82,7 @@ python3 manage.py runserver ## Logging in and using the site -To login to the site, open the _/admin_ URL (e.g. `http://127.0.0.1:8000/admin`) and enter your new superuser userid and password credentials (you'll be redirected to the _login_ page, and then back to the _/admin_ URL after you've entered your details). +To login to the site, open the _/admin_ URL (e.g., `http://127.0.0.1:8000/admin`) and enter your new superuser userid and password credentials (you'll be redirected to the _login_ page, and then back to the _/admin_ URL after you've entered your details). This part of the site displays all our models, grouped by installed application. You can click on a model name to go to a screen that lists all its associated records, and you can further click on those records to edit them. You can also directly click the **Add** link next to each model to start creating a record of that type. @@ -93,7 +95,7 @@ Enter values for the fields. You can create new authors or genres by pressing th ![Admin Site - Book Add](admin_book_add.png) > [!NOTE] -> At this point we'd like you to spend some time adding a few books, authors, languages, and genres (e.g. Fantasy) to your application. Make sure that each author and genre includes a couple of different books (this will make your list and detail views more interesting when we implement them later on in the article series). +> At this point we'd like you to spend some time adding a few books, authors, languages, and genres (e.g., Fantasy) to your application. Make sure that each author and genre includes a couple of different books (this will make your list and detail views more interesting when we implement them later on in the article series). When you've finished adding books, click on the **Home** link in the top bookmark to be taken back to the main admin page. Then click on the **Books** link to display the current list of books (or on one of the other links to see other model lists). Now that you've added a few books, the list might look similar to the screenshot below. The title of each book is displayed; this is the value returned in the Book model's `__str__()` method that we specified in the last article. @@ -131,13 +133,13 @@ You can further customize the interface to make it even easier to use. Some of t - List views: - Add additional fields/information displayed for each record. - - Add filters to select which records are listed, based on date or some other selection value (e.g. Book loan status). + - Add filters to select which records are listed, based on date or some other selection value (e.g., Book loan status). - Add additional options to the actions menu in list views and choose where this menu is displayed on the form. - Detail views - Choose which fields to display (or exclude), along with their order, grouping, whether they are editable, the widget used, orientation etc. - - Add related fields to a record to allow inline editing (e.g. add the ability to add and edit book records while you're creating their author record). + - Add related fields to a record to allow inline editing (e.g., add the ability to add and edit book records while you're creating their author record). In this section we're going to look at a few changes that will improve the interface for our _LocalLibrary_, including adding more information to `Book` and `Author` model lists, and improving the layout of their edit views. We won't change the `Language` and `Genre` model presentation because they only have one field each, so there is no real benefit in doing so! @@ -279,7 +281,7 @@ In your website go to the author detail view — it should now appear as shown b You can add "sections" to group related model information within the detail form, using the [fieldsets](https://docs.djangoproject.com/en/5.0/ref/contrib/admin/#django.contrib.admin.ModelAdmin.fieldsets) attribute. -In the `BookInstance` model we have information related to what the book is (i.e. `name`, `imprint`, and `id`) and when it will be available (`status`, `due_back`). We can add these to our `BookInstanceAdmin` class as shown below, using the `fieldsets` property. +In the `BookInstance` model we have information related to what the book is (i.e., `name`, `imprint`, and `id`) and when it will be available (`status`, `due_back`). We can add these to our `BookInstanceAdmin` class as shown below, using the `fieldsets` property. ```python @admin.register(BookInstance) diff --git a/files/en-us/learn_web_development/extensions/server-side/django/authentication/index.md b/files/en-us/learn_web_development/extensions/server-side/django/authentication/index.md index bd3985ebfeccf9b..17ce60385741af8 100644 --- a/files/en-us/learn_web_development/extensions/server-side/django/authentication/index.md +++ b/files/en-us/learn_web_development/extensions/server-side/django/authentication/index.md @@ -1,10 +1,12 @@ --- title: "Django Tutorial Part 8: User authentication and permissions" +short-title: "8: Authentication and permissions" slug: Learn_web_development/Extensions/Server-side/Django/Authentication page-type: learn-module-chapter +sidebar: learnsidebar --- -{{LearnSidebar}}{{PreviousMenuNext("Learn_web_development/Extensions/Server-side/Django/Sessions", "Learn_web_development/Extensions/Server-side/Django/Forms", "Learn_web_development/Extensions/Server-side/Django")}} +{{PreviousMenuNext("Learn_web_development/Extensions/Server-side/Django/Sessions", "Learn_web_development/Extensions/Server-side/Django/Forms", "Learn_web_development/Extensions/Server-side/Django")}} In this tutorial, we'll show you how to allow users to log in to your site with their own accounts, and how to control what they can do and see based on whether or not they are logged in and their _permissions_. As part of this demonstration, we'll extend the [LocalLibrary](/en-US/docs/Learn_web_development/Extensions/Server-side/Django/Tutorial_local_library_website) website, adding login and logout pages, and user- and staff-specific pages for viewing books that have been borrowed. @@ -30,7 +32,7 @@ In this tutorial, we'll show you how to allow users to log in to your site with Django provides an authentication and authorization ("permission") system, built on top of the session framework discussed in the [previous tutorial](/en-US/docs/Learn_web_development/Extensions/Server-side/Django/Sessions), that allows you to verify user credentials and define what actions each user is allowed to perform. The framework includes built-in models for `Users` and `Groups` (a generic way of applying permissions to more than one user at a time), permissions/flags that designate whether a user may perform a task, forms and views for logging in users, and view tools for restricting content. > [!NOTE] -> According to Django the authentication system aims to be very generic, and so does not provide some features provided in other web authentication systems. Solutions for some common problems are available as third-party packages. For example, {{glossary("throttle", "throttling")}} of login attempts and authentication against third parties (e.g. OAuth). +> According to Django the authentication system aims to be very generic, and so does not provide some features provided in other web authentication systems. Solutions for some common problems are available as third-party packages. For example, {{glossary("throttle", "throttling")}} of login attempts and authentication against third parties (e.g., OAuth). In this tutorial, we'll show you how to enable user authentication in the [LocalLibrary](/en-US/docs/Learn_web_development/Extensions/Server-side/Django/Tutorial_local_library_website) website, create your own login and logout pages, add permissions to your models, and control access to pages. We'll use the authentication/permissions to display lists of books that have been borrowed for both users and librarians. @@ -122,7 +124,7 @@ Now let's create a user: 3. Enter an appropriate **Username** and **Password**/**Password confirmation** for your test user 4. Press **SAVE** to create the user. - The admin site will create the new user and immediately take you to a _Change user_ screen where you can change your **username** and add information for the User model's optional fields. These fields include the first name, last name, email address, and the user's status and permissions (only the **Active** flag should be set). Further down you can specify the user's groups and permissions, and see important dates related to the user (e.g. their join date and last login date). + The admin site will create the new user and immediately take you to a _Change user_ screen where you can change your **username** and add information for the User model's optional fields. These fields include the first name, last name, email address, and the user's status and permissions (only the **Active** flag should be set). Further down you can specify the user's groups and permissions, and see important dates related to the user (e.g., their join date and last login date). ![Admin site - add user pt2](admin_authentication_add_user_prt2.png) 5. In the _Groups_ section, select **Library Member** group from the list of _Available groups_, and then press the **right-arrow** between the boxes to move it into the _Chosen groups_ box. @@ -267,7 +269,7 @@ Create a new HTML file called /**django-locallibrary-tutorial/templates/registra <input type="hidden" name="next" value="\{{ next }}"> </form> - {# Assumes you set up the password_reset view in your URLconf #} + {# Assumes you set up the password_reset view in your URLConf #} <p><a href="{% url 'password_reset' %}">Lost password?</a></p> {% endblock %} @@ -725,7 +727,7 @@ Open the **catalog/models.py**, and add the permission as shown above. You will ### Templates -The current user's permissions are stored in a template variable called `\{{ perms }}`. You can check whether the current user has a particular permission using the specific variable name within the associated Django "app" — e.g. `\{{ perms.catalog.can_mark_returned }}` will be `True` if the user has this permission, and `False` otherwise. We typically test for the permission using the template `{% if %}` tag as shown: +The current user's permissions are stored in a template variable called `\{{ perms }}`. You can check whether the current user has a particular permission using the specific variable name within the associated Django "app" — e.g., `\{{ perms.catalog.can_mark_returned }}` will be `True` if the user has this permission, and `False` otherwise. We typically test for the permission using the template `{% if %}` tag as shown: ```django {% if perms.catalog.can_mark_returned %} diff --git a/files/en-us/learn_web_development/extensions/server-side/django/deployment/index.md b/files/en-us/learn_web_development/extensions/server-side/django/deployment/index.md index 2c1fa8c6e268a20..3bf0b8d16d7cf42 100644 --- a/files/en-us/learn_web_development/extensions/server-side/django/deployment/index.md +++ b/files/en-us/learn_web_development/extensions/server-side/django/deployment/index.md @@ -1,10 +1,12 @@ --- title: "Django Tutorial Part 11: Deploying Django to production" +short-title: "11: Deploying" slug: Learn_web_development/Extensions/Server-side/Django/Deployment page-type: learn-module-chapter +sidebar: learnsidebar --- -{{LearnSidebar}}{{PreviousMenuNext("Learn_web_development/Extensions/Server-side/Django/Testing", "Learn_web_development/Extensions/Server-side/Django/web_application_security", "Learn_web_development/Extensions/Server-side/Django")}} +{{PreviousMenuNext("Learn_web_development/Extensions/Server-side/Django/Testing", "Learn_web_development/Extensions/Server-side/Django/web_application_security", "Learn_web_development/Extensions/Server-side/Django")}} Now you've created (and tested) an awesome [LocalLibrary](/en-US/docs/Learn_web_development/Extensions/Server-side/Django/Tutorial_local_library_website) website, you're going to want to install it on a public web server so that it can be accessed by library staff and members over the internet. This article provides an overview of how you might go about finding a host to deploy your website, and what you need to do in order to get your site ready for production. @@ -34,16 +36,16 @@ Up to now you've been working in a development environment, using the Django dev - Choose an environment for hosting any static files. - Set up a production-level infrastructure for serving your website. -This tutorial provides some guidance on your options for choosing a hosting site, a brief overview of what you need to do in order to get your Django app ready for production, and a working example of how to install the LocalLibrary website onto the [Railway](https://railway.app/) cloud hosting service. +This tutorial provides some guidance on your options for choosing a hosting site, a brief overview of what you need to do in order to get your Django app ready for production, and a working example of how to install the LocalLibrary website onto the [Railway](https://railway.com/) cloud hosting service. ## What is a production environment? The production environment is the environment provided by the server computer where you will run your website for external consumption. The environment includes: - Computer hardware on which the website runs. -- Operating system (e.g. Linux, Windows). +- Operating system (e.g., Linux, Windows). - Programming language runtime and framework libraries on top of which your website is written. -- Web server used to serve pages and other content (e.g. Nginx, Apache). +- Web server used to serve pages and other content (e.g., Nginx, Apache). - Application server that passes "dynamic" requests between your Django website and the web server. - Databases on which your website is dependent. @@ -67,7 +69,7 @@ Some developers will choose the increased flexibility provided by IaaS over PaaS ## Choosing a hosting provider -There are many hosting providers that are known to either actively support or work well with Django, including: [Heroku](https://www.heroku.com/), [DigitalOcean](https://www.digitalocean.com/), [Railway](https://railway.app/), [Python Anywhere](https://www.pythonanywhere.com/), [Amazon Web Services](https://aws.amazon.com/), [Azure](https://azure.microsoft.com/en-us/), [Google Cloud](https://cloud.google.com/), [Hetzner](https://www.hetzner.com/), and [Vultr Cloud Compute](https://blogs.vultr.com/new-free-tier-plan) — to name just a few. +There are many hosting providers that are known to either actively support or work well with Django, including: [Heroku](https://www.heroku.com/), [DigitalOcean](https://www.digitalocean.com/), [Railway](https://railway.com/), [Python Anywhere](https://www.pythonanywhere.com/), [Amazon Web Services](https://aws.amazon.com/), [Azure](https://azure.microsoft.com/en-us/), [Google Cloud](https://cloud.google.com/), [Hetzner](https://www.hetzner.com/), and [Vultr Cloud Compute](https://blogs.vultr.com/new-free-tier-plan) — to name just a few. These vendors provide different types of environments (IaaS, PaaS), and different levels of computing and network resources at different prices. Some of the things to consider when choosing a host: @@ -76,9 +78,9 @@ Some of the things to consider when choosing a host: - Level of support for scaling horizontally (adding more machines) and vertically (upgrading to more powerful machines) and the costs of doing so. - Where the supplier has data centres, and hence where access is likely to be fastest. - The host's historical uptime and downtime performance. -- Tools provided for managing the site — are they easy to use and are they secure (e.g. SFTP vs. FTP). +- Tools provided for managing the site — are they easy to use and are they secure (e.g., SFTP vs. FTP). - Inbuilt frameworks for monitoring your server. -- Known limitations. Some hosts will deliberately block certain services (e.g. email). Others offer only a certain number of hours of "live time" in some price tiers, or only offer a small amount of storage. +- Known limitations. Some hosts will deliberately block certain services (e.g., email). Others offer only a certain number of hours of "live time" in some price tiers, or only offer a small amount of storage. - Additional benefits. Some providers will offer free domain names and support for TLS certificates that you would otherwise have to pay for. - Whether the "free" tier you're relying on expires over time, and whether the cost of migrating to a more expensive tier means you would have been better off using some other service in the first place! @@ -88,7 +90,7 @@ They are however great for testing low traffic sites in a hosted environment, an Popular choices in this category include [Vultr Cloud Compute](https://blogs.vultr.com/new-free-tier-plan), [Python Anywhere](https://www.pythonanywhere.com/), [Amazon Web Services](https://docs.aws.amazon.com/awsaccountbilling/latest/aboutv2/billing-free-tier.html), [Microsoft Azure](https://azure.microsoft.com/en-us/pricing/details/app-service/linux/), and so on. Most providers also offer a "basic" tier that is intended for small production sites, and which provide more useful levels of computing power and fewer limitations. -[Railway](https://railway.app/), [Heroku](https://www.heroku.com/), and [DigitalOcean](https://www.digitalocean.com/) are examples of popular hosting providers that have a relatively inexpensive basic computing tier (in the $5 to $10 USD per month range). +[Railway](https://railway.com/), [Heroku](https://www.heroku.com/), and [DigitalOcean](https://www.digitalocean.com/) are examples of popular hosting providers that have a relatively inexpensive basic computing tier (in the $5 to $10 USD per month range). > [!NOTE] > Remember that price is not the only selection criterion. If your website is successful, it may turn out that scalability is the most important consideration. @@ -120,7 +122,7 @@ pip3 install python-dotenv Then open **/locallibrary/settings.py** and insert the following code after `BASE_DIR` is defined, but before the security warning: `# SECURITY WARNING: keep the secret key used in production secret!` -```py +```python # Support env variables from .env file if defined import os from dotenv import load_dotenv @@ -559,7 +561,7 @@ After getting the local library sources and installing the dependencies in a vir Replace the content in the file with the following text (first updating "hamishwillee" with your own username), and then select the **Save** button. - ```py + ```python import os import sys @@ -680,7 +682,7 @@ If the environment variable has been loaded you'll get a "Not found" message rat ## Example: Hosting on Railway -This section provides a practical demonstration of how to install _LocalLibrary_ on [Railway](https://railway.app/). +This section provides a practical demonstration of how to install _LocalLibrary_ on [Railway](https://railway.com/). ### Why Railway? @@ -692,10 +694,10 @@ Railway is an attractive hosting option for several reasons: - Railway takes care of most of the infrastructure so you don't have to. Not having to worry about servers, load balancers, reverse proxies, and so on, makes it much easier to get started. -- Railway has a [focus on developer experience for development and deployment](https://docs.railway.app/maturity/compare-to-heroku), which leads to a faster and softer learning curve than many other alternatives. +- Railway has a [focus on developer experience for development and deployment](https://docs.railway.com/maturity/compare-to-heroku), which leads to a faster and softer learning curve than many other alternatives. - The skills and concepts you will learn when using Railway are transferrable. While Railway has some excellent new features, other popular hosting services use many of the same ideas and approaches. -- [Railway documentation](https://docs.railway.app/) is clear and complete. +- [Railway documentation](https://docs.railway.com/) is clear and complete. - The service appears to be very reliable, and if you end up loving it, the pricing is predictable, and scaling your app is very easy. You should take the time to determine if Railway is [suitable for your own website](#choosing_a_hosting_provider). @@ -712,11 +714,11 @@ For Django apps we provide this information in a number of text files: For Django this will usually be the Gunicorn web application server (with a `.wsgi` script). - **wsgi.py**: [WSGI](https://wsgi.readthedocs.io/en/latest/what.html) configuration to call our Django application in the Railway environment. -Once the application is running it can configure itself using information provided in [environment variables](https://docs.railway.app/guides/variables). +Once the application is running it can configure itself using information provided in [environment variables](https://docs.railway.com/guides/variables). For example, an application that uses a database can get the address using the variable `DATABASE_URL`. The database service itself may be hosted by Railway or some other provider. -Developers interact with Railway through the Railway site, and using a special [Command Line Interface (CLI)](https://docs.railway.app/guides/cli) tool. +Developers interact with Railway through the Railway site, and using a special [Command Line Interface (CLI)](https://docs.railway.com/guides/cli) tool. The CLI allows you to associate a local GitHub repository with a railway project, upload the repository from the local branch to the live site, inspect the logs of the running process, set and get configuration variables and much more. One of the most useful features is that you can use the CLI to run your local project with the same environment variables as the live project. @@ -792,10 +794,10 @@ We should now be ready to start deploying LocalLibrary on Railway. To start using Railway you will first need to create an account: -- Go to [railway.app](https://railway.app/) and click the **Login** link in the top toolbar. +- Go to [railway.com](https://railway.com/) and click the **Login** link in the top toolbar. - Select GitHub in the popup to login using your GitHub credentials - You may then need to go to your email and verify your account. -- You'll then be logged in to the Railway.app dashboard: <https://railway.app/dashboard>. +- You'll then be logged in to the Railway.com dashboard: <https://railway.com/dashboard>. ### Deploy on Railway from GitHub @@ -899,11 +901,11 @@ Note that you could also have opened the Postgres database, then its variable ta If you open the project now it should display just as it did locally. Note however that there is no way to populate the library with data yet, because we have not yet created a superuser account. -We'll do that using the [CLI](https://docs.railway.app/guides/cli) tool on our local computer. +We'll do that using the [CLI](https://docs.railway.com/guides/cli) tool on our local computer. ### Install the client -Download and install the Railway client for your local operating system by following the [instructions here](https://docs.railway.app/guides/cli). +Download and install the Railway client for your local operating system by following the [instructions here](https://docs.railway.com/guides/cli). After the client is installed you will be able to run commands. Some of the more important operations include deploying the current directory of your computer to an associated Railway project (without having to upload to GitHub), and running your Django project locally using the same settings as you have on the production server. @@ -1003,7 +1005,7 @@ The next step is to read our last few articles, and then complete the assessment - Railway Docs - - [CLI](https://docs.railway.app/guides/cli) + - [CLI](https://docs.railway.com/guides/cli) - DigitalOcean @@ -1021,6 +1023,6 @@ The next step is to read our last few articles, and then complete the assessment - [Configuration and Config Vars](https://devcenter.heroku.com/articles/config-vars) (Heroku docs) - [Limits](https://devcenter.heroku.com/articles/limits) (Heroku docs) - [Deploying Python applications with Gunicorn](https://devcenter.heroku.com/articles/python-gunicorn) (Heroku docs) - - [Deploying Python and Django apps on Heroku](https://devcenter.heroku.com/articles/deploying-python) (Heroku docs) + - [Working with Django](https://devcenter.heroku.com/categories/working-with-django) (Heroku docs) {{PreviousMenuNext("Learn_web_development/Extensions/Server-side/Django/Testing", "Learn_web_development/Extensions/Server-side/Django/web_application_security", "Learn_web_development/Extensions/Server-side/Django")}} 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 0436dcd9942771e..c870f46af3e961f 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 @@ -1,10 +1,12 @@ --- title: Setting up a Django development environment +short-title: Dev environment setup slug: Learn_web_development/Extensions/Server-side/Django/development_environment page-type: learn-module-chapter +sidebar: learnsidebar --- -{{LearnSidebar}}{{PreviousMenuNext("Learn_web_development/Extensions/Server-side/Django/Introduction", "Learn_web_development/Extensions/Server-side/Django/Tutorial_local_library_website", "Learn_web_development/Extensions/Server-side/Django")}} +{{PreviousMenuNext("Learn_web_development/Extensions/Server-side/Django/Introduction", "Learn_web_development/Extensions/Server-side/Django/Tutorial_local_library_website", "Learn_web_development/Extensions/Server-side/Django")}} Now that you know what Django is for, we'll show you how to set up and test a Django development environment on Windows, Linux (Ubuntu), and macOS — whatever common operating system you are using, this article should give you what you need to be able to start developing Django apps. @@ -33,7 +35,7 @@ Django makes it very easy to set up your own computer so that you can start deve The development environment is an installation of Django on your local computer that you can use for developing and testing Django apps prior to deploying them to a production environment. -The main tools that Django itself provides are a set of Python scripts for creating and working with Django projects, along with a simple _development web server_ that you can use to test local (i.e. on your computer, not on an external web server) Django web applications on your computer's web browser. +The main tools that Django itself provides are a set of Python scripts for creating and working with Django projects, along with a simple _development web server_ that you can use to test local (i.e., on your computer, not on an external web server) Django web applications on your computer's web browser. There are other peripheral tools, that often form part of the development environment, that we won't be covering here. These include things like a [text editor](/en-US/docs/Learn_web_development/Howto/Tools_and_setup/Available_text_editors) or IDE for editing code, linters for auto formatting, and so on. We are assuming that you've already got a text editor installed. @@ -89,7 +91,7 @@ For this article (and most of this module) we will be using the _SQLite_ databas When you install Python3 you get a single global environment that is shared by all Python3 code. While you can install whatever Python packages you like in the environment, you can only install one particular version of each package at a time. > [!NOTE] -> Python applications installed into the global environment can potentially conflict with each other (i.e. if they depend on different versions of the same package). +> Python applications installed into the global environment can potentially conflict with each other (i.e., if they depend on different versions of the same package). If you install Django into the default/global environment then you will only be able to target one version of Django on the computer. This can be a problem if you want to create new websites (using the latest version of Django) while still maintaining websites that rely on older versions. @@ -222,7 +224,7 @@ The libraries we'll use for creating our virtual environments are [virtualenvwra #### Ubuntu virtual environment setup -After installing Python and pip you can install _virtualenvwrapper_ (which includes _virtualenv_). The official installation guide can be found [here](https://virtualenvwrapper.readthedocs.io/en/latest/install.html), or follow the instructions below. +After installing Python and pip you can install _virtualenvwrapper_ (which includes _virtualenv_). You can check [the official installation guide](https://virtualenvwrapper.readthedocs.io/en/latest/install.html), or follow the instructions below. Install the tool using _pip3_: @@ -393,7 +395,7 @@ py -3 -m django --version > > In Windows _Python 3_ scripts are launched by prefixing the command with `py -3`, although this can vary depending on your specific installation. > Try omitting the `-3` modifier if you encounter any problems with commands. -> In Linux/macOS, the command is `python3.` +> In Linux/macOS, the command is `python3`. > [!WARNING] > The rest of this **module** uses the _Linux_ command for invoking Python 3 (`python3`). If you're working on _Windows_ replace this prefix with: `py -3` @@ -461,7 +463,7 @@ Now that the repository ("repo") is created on GitHub we are going to want to cl In the "Clone" section, select the "HTTPS" tab, and copy the URL. If you used the repository name "django_local_library", the URL should be something like: `https://github.com/<your_git_user_id>/django_local_library.git`. -2. Install _git_ for your local computer (you can find versions for different platforms [here](https://git-scm.com/downloads)). +2. Install _git_ for your local computer ([official Git download guide](https://git-scm.com/downloads)). 3. Open a command prompt/terminal and clone your repo using the URL you copied above: ```bash diff --git a/files/en-us/learn_web_development/extensions/server-side/django/django_assessment_blog/index.md b/files/en-us/learn_web_development/extensions/server-side/django/django_assessment_blog/index.md index b6789fc7aa41b57..88e204186a2e3b3 100644 --- a/files/en-us/learn_web_development/extensions/server-side/django/django_assessment_blog/index.md +++ b/files/en-us/learn_web_development/extensions/server-side/django/django_assessment_blog/index.md @@ -1,19 +1,21 @@ --- -title: "Assessment: DIY Django mini blog" +title: "Challenge: DIY Django mini blog" +short-title: "Challenge: Django blog" slug: Learn_web_development/Extensions/Server-side/Django/django_assessment_blog page-type: learn-module-assessment +sidebar: learnsidebar --- -{{LearnSidebar}}{{PreviousMenu("Learn_web_development/Extensions/Server-side/Django/web_application_security", "Learn_web_development/Extensions/Server-side/Django")}} +{{PreviousMenu("Learn_web_development/Extensions/Server-side/Django/web_application_security", "Learn_web_development/Extensions/Server-side/Django")}} -In this assessment you'll use the Django knowledge you've picked up in the [Django Web Framework (Python)](/en-US/docs/Learn_web_development/Extensions/Server-side/Django) module to create a very basic blog. +In this challenge, you'll use the Django knowledge you've picked up in the [Django Web Framework (Python)](/en-US/docs/Learn_web_development/Extensions/Server-side/Django) module to create a very basic blog. <table> <tbody> <tr> <th scope="row">Prerequisites:</th> <td> - Before attempting this assessment you should have already worked through all the articles in this module. + Before attempting this challenge, you should have already worked through all the articles in this module. </td> </tr> <tr> @@ -100,7 +102,7 @@ The pages that need to be displayed, their URLs, and other requirements, are lis </li> <li> Blog posts and comments need only display plain text. - There is no need to support any sort of HTML markup (e.g. links, images, bold/italic, etc.). + There is no need to support any sort of HTML markup (e.g., links, images, bold/italic, etc.). </li> </ul> </td> @@ -185,11 +187,11 @@ The pages that need to be displayed, their URLs, and other requirements, are lis In addition you should write some basic tests to verify: - All model fields have the correct label and length. -- All models have the expected object name (e.g. `__str__()` returns the expected value). -- Models have the expected URL for individual Blog and Comment records (e.g. `get_absolute_url()` returns the expected URL). -- The BlogListView (all-blog page) is accessible at the expected location (e.g. /blog/blogs) -- The BlogListView (all-blog page) is accessible at the expected named URL (e.g. 'blogs') -- The BlogListView (all-blog page) uses the expected template (e.g. the default) +- All models have the expected object name (e.g., `__str__()` returns the expected value). +- Models have the expected URL for individual Blog and Comment records (e.g., `get_absolute_url()` returns the expected URL). +- The BlogListView (all-blog page) is accessible at the expected location (e.g., /blog/blogs) +- The BlogListView (all-blog page) is accessible at the expected named URL (e.g., 'blogs') +- The BlogListView (all-blog page) uses the expected template (e.g., the default) - The BlogListView paginates records by 5 (at least on the first page) > [!NOTE] @@ -307,7 +309,7 @@ class SomeView(generic.ListView): ## Assessment -The assessment for this task is [available on GitHub here](https://github.com/mdn/django-diy-blog/blob/main/MarkingGuide.md). This assessment is primarily based on how well your application meets the requirements we listed above, though there are some parts of the assessment that check your code uses appropriate models, and that you have written at least some test code. +The assessment for this challenge is [available on GitHub here](https://github.com/mdn/django-diy-blog/blob/main/MarkingGuide.md). This assessment is primarily based on how well your application meets the requirements we listed above, though there are some parts that check your code uses appropriate models, and that you have written at least some test code. When you're done, you can check out [the finished example](https://github.com/mdn/django-diy-blog) which reflects a "full marks" project. Once you've completed this module you've also finished all the MDN content for learning basic Django server-side website programming! We hope you enjoyed this module and feel you have a good grasp of the basics! diff --git a/files/en-us/learn_web_development/extensions/server-side/django/forms/index.md b/files/en-us/learn_web_development/extensions/server-side/django/forms/index.md index 9d3d555bb8aa95a..0f0a3d8c8dab396 100644 --- a/files/en-us/learn_web_development/extensions/server-side/django/forms/index.md +++ b/files/en-us/learn_web_development/extensions/server-side/django/forms/index.md @@ -1,10 +1,12 @@ --- title: "Django Tutorial Part 9: Working with forms" +short-title: "9: Forms" slug: Learn_web_development/Extensions/Server-side/Django/Forms page-type: learn-module-chapter +sidebar: learnsidebar --- -{{LearnSidebar}}{{PreviousMenuNext("Learn_web_development/Extensions/Server-side/Django/Sessions", "Learn_web_development/Extensions/Server-side/Django/Testing", "Learn_web_development/Extensions/Server-side/Django")}} +{{PreviousMenuNext("Learn_web_development/Extensions/Server-side/Django/Sessions", "Learn_web_development/Extensions/Server-side/Django/Testing", "Learn_web_development/Extensions/Server-side/Django")}} In this tutorial, we'll show you how to work with HTML Forms in Django, and, in particular, the easiest way to write forms to create, update, and delete model instances. As part of this demonstration, we'll extend the [LocalLibrary](/en-US/docs/Learn_web_development/Extensions/Server-side/Django/Tutorial_local_library_website) website so that librarians can renew books, and create, update, and delete authors using our own forms (rather than using the admin application). @@ -169,8 +171,8 @@ There are many other types of form fields, which you will largely recognize from The arguments that are common to most fields are listed below (these have sensible default values): - [`required`](https://docs.djangoproject.com/en/5.0/ref/forms/fields/#required): If `True`, the field may not be left blank or given a `None` value. Fields are required by default, so you would set `required=False` to allow blank values in the form. -- [`label`](https://docs.djangoproject.com/en/5.0/ref/forms/fields/#label): The label to use when rendering the field in HTML. If a [label](https://docs.djangoproject.com/en/5.0/ref/forms/fields/#label) is not specified, Django will create one from the field name by capitalizing the first letter and replacing underscores with spaces (e.g. _Renewal date_). -- [`label_suffix`](https://docs.djangoproject.com/en/5.0/ref/forms/fields/#label-suffix): By default, a colon is displayed after the label (e.g. Renewal date&ZeroWidthSpace;**:**). This argument allows you to specify a different suffix containing other character(s). +- [`label`](https://docs.djangoproject.com/en/5.0/ref/forms/fields/#label): The label to use when rendering the field in HTML. If a [label](https://docs.djangoproject.com/en/5.0/ref/forms/fields/#label) is not specified, Django will create one from the field name by capitalizing the first letter and replacing underscores with spaces (e.g., _Renewal date_). +- [`label_suffix`](https://docs.djangoproject.com/en/5.0/ref/forms/fields/#label-suffix): By default, a colon is displayed after the label (e.g., Renewal date&ZeroWidthSpace;**:**). This argument allows you to specify a different suffix containing other character(s). - [`initial`](https://docs.djangoproject.com/en/5.0/ref/forms/fields/#initial): The initial value for the field when the form is displayed. - [`widget`](https://docs.djangoproject.com/en/5.0/ref/forms/fields/#widget): The display widget to use. - [`help_text`](https://docs.djangoproject.com/en/5.0/ref/forms/fields/#help-text) (as seen in the example above): Additional text that can be displayed in forms to explain how to use the field. @@ -241,7 +243,7 @@ The URL configuration will redirect URLs with the format **/catalog/book/_\<book As discussed in the [Django form handling process](#django_form_handling_process) above, the view has to render the default form when it is first called and then either re-render it with error messages if the data is invalid, or process the data and redirect to a new page if the data is valid. In order to perform these different actions, the view has to be able to know whether it is being called for the first time to render the default form, or a subsequent time to validate data. -For forms that use a `POST` request to submit information to the server, the most common pattern is for the view to test against the `POST` request type (`if request.method == 'POST':`) to identify form validation requests and `GET` (using an `else` condition) to identify the initial form creation request. If you want to submit your data using a `GET` request, then a typical approach for identifying whether this is the first or subsequent view invocation is to read the form data (e.g. to read a hidden value in the form). +For forms that use a `POST` request to submit information to the server, the most common pattern is for the view to test against the `POST` request type (`if request.method == 'POST':`) to identify form validation requests and `GET` (using an `else` condition) to identify the initial form creation request. If you want to submit your data using a `GET` request, then a typical approach for identifying whether this is the first or subsequent view invocation is to read the form data (e.g., to read a hidden value in the form). The book renewal process will be writing to our database, so, by convention, we use the `POST` request approach. The code fragment below shows the (very standard) pattern for this sort of function view. @@ -346,7 +348,7 @@ return render(request, 'catalog/book_renew_librarian.html', context) If the form is not valid we call `render()` again, but this time the form value passed in the context will include error messages. -If the form is valid, then we can start to use the data, accessing it through the `form.cleaned_data` attribute (e.g. `data = form.cleaned_data['renewal_date']`). Here, we just save the data into the `due_back` value of the associated `BookInstance` object. +If the form is valid, then we can start to use the data, accessing it through the `form.cleaned_data` attribute (e.g., `data = form.cleaned_data['renewal_date']`). Here, we just save the data into the `due_back` value of the associated `BookInstance` object. > [!WARNING] > While you can also access the form data directly through the request (for example, `request.POST['renewal_date']` or `request.GET['renewal_date']` if using a GET request), this is NOT recommended. The cleaned data is sanitized, validated, and converted into Python-friendly types. @@ -456,13 +458,13 @@ Perhaps unsurprisingly, when used as shown this provides the default rendering o > [!NOTE] > It is perhaps not obvious because we only have one field, but, by default, every field is defined in its own table row. This same rendering is provided if you reference the template variable `\{{ form.as_table }}`. -If you were to enter an invalid date, you'd additionally get a list of the errors rendered on the page (see `errorlist` below). +If you were to enter an invalid date, you'd additionally get a list of the errors rendered on the page (see `error-list` below). ```html <tr> <th><label for="id_renewal_date">Renewal date:</label></th> <td> - <ul class="errorlist"> + <ul class="error-list"> <li>Invalid date - renewal in past</li> </ul> <input @@ -572,7 +574,7 @@ class RenewBookModelForm(ModelForm): > [!NOTE] > This might not look all that much simpler than just using a `Form` (and it isn't in this case, because we just have one field). However, if you have a lot of fields, it can considerably reduce the amount of code required! -The rest of the information comes from the model field definitions (e.g. labels, widgets, help text, error messages). If these aren't quite right, then we can override them in our `class Meta`, specifying a dictionary containing the field to change and its new value. For example, in this form, we might want a label for our field of "_Renewal date_" (rather than the default based on the field name: _Due Back_), and we also want our help text to be specific to this use case. +The rest of the information comes from the model field definitions (e.g., labels, widgets, help text, error messages). If these aren't quite right, then we can override them in our `class Meta`, specifying a dictionary containing the field to change and its new value. For example, in this form, we might want a label for our field of "_Renewal date_" (rather than the default based on the field name: _Due Back_), and we also want our help text to be specific to this use case. The `Meta` below shows you how to override these fields, and you can similarly set `widgets` and `error_messages` if the defaults aren't sufficient. ```python diff --git a/files/en-us/learn_web_development/extensions/server-side/django/generic_views/index.md b/files/en-us/learn_web_development/extensions/server-side/django/generic_views/index.md index c713141f5731174..52639349c329356 100644 --- a/files/en-us/learn_web_development/extensions/server-side/django/generic_views/index.md +++ b/files/en-us/learn_web_development/extensions/server-side/django/generic_views/index.md @@ -1,10 +1,12 @@ --- title: "Django Tutorial Part 6: Generic list and detail views" +short-title: "6: Generic list and detail views" slug: Learn_web_development/Extensions/Server-side/Django/Generic_views page-type: learn-module-chapter +sidebar: learnsidebar --- -{{LearnSidebar}}{{PreviousMenuNext("Learn_web_development/Extensions/Server-side/Django/Home_page", "Learn_web_development/Extensions/Server-side/Django/Sessions", "Learn_web_development/Extensions/Server-side/Django")}} +{{PreviousMenuNext("Learn_web_development/Extensions/Server-side/Django/Home_page", "Learn_web_development/Extensions/Server-side/Django/Sessions", "Learn_web_development/Extensions/Server-side/Django")}} This tutorial extends our [LocalLibrary](/en-US/docs/Learn_web_development/Extensions/Server-side/Django/Tutorial_local_library_website) website, adding list and detail pages for books and authors. Here we'll learn about generic class-based views, and show how they can reduce the amount of code you have to write for common use cases. We'll also go into URL handling in greater detail, showing how to perform basic pattern matching. @@ -68,7 +70,7 @@ class BookListView(generic.ListView): model = Book ``` -That's it! The generic view will query the database to get all records for the specified model (`Book`) then render a template located at **/django-locallibrary-tutorial/catalog/templates/catalog/book_list.html** (which we will create below). Within the template you can access the list of books with the template variable named `object_list` OR `book_list` (i.e. generically `<the model name>_list`). +That's it! The generic view will query the database to get all records for the specified model (`Book`) then render a template located at **/django-locallibrary-tutorial/catalog/templates/catalog/book_list.html** (which we will create below). Within the template you can access the list of books with the template variable named `object_list` OR `book_list` (i.e., generically `<the model name>_list`). > [!NOTE] > This awkward path for the template location isn't a misprint — the generic views look for templates in `/application_name/the_model_name_list.html` (`catalog/book_list.html` in this case) inside the application's `/application_name/templates/` directory (`/catalog/templates/)`. @@ -97,7 +99,7 @@ class BookListView(generic.ListView): return Book.objects.filter(title__icontains='war')[:5] # Get 5 books containing the title war ``` -We might also override `get_context_data()` in order to pass additional context variables to the template (e.g. the list of books is passed by default). The fragment below shows how to add a variable named `some_data` to the context (it would then be available as a template variable). +We might also override `get_context_data()` in order to pass additional context variables to the template (e.g., the list of books is passed by default). The fragment below shows how to add a variable named `some_data` to the context (it would then be available as a template variable). ```python class BookListView(generic.ListView): @@ -163,7 +165,7 @@ If `book_list` is not empty, then we iterate through the list of books. {% endif %} ``` -The condition above only checks for one case, but you can test on additional conditions using the `elif` template tag (e.g. `{% elif var2 %}`). +The condition above only checks for one case, but you can test on additional conditions using the `elif` template tag (e.g., `{% elif var2 %}`). For more information about conditional operators see: [if](https://docs.djangoproject.com/en/5.0/ref/templates/builtins/#if), [ifequal/ifnotequal](https://docs.djangoproject.com/en/5.0/ref/templates/builtins/#ifequal-and-ifnotequal), and [ifchanged](https://docs.djangoproject.com/en/5.0/ref/templates/builtins/#ifchanged) in [Built-in template tags and filters](https://docs.djangoproject.com/en/5.0/ref/templates/builtins/) (Django Docs). #### For loops @@ -200,7 +202,7 @@ The code inside the loop creates a list item for each book that shows both the t <a href="\{{ book.get_absolute_url }}">\{{ book.title }}</a> (\{{book.author}}) ``` -We access the _fields_ of the associated book record using the "dot notation" (e.g. `book.title` and `book.author`), where the text following the `book` item is the field name (as defined in the model). +We access the _fields_ of the associated book record using the "dot notation" (e.g., `book.title` and `book.author`), where the text following the `book` item is the field name (as defined in the model). We can also call _functions_ in the model from within our template — in this case we call `Book.get_absolute_url()` to get a URL you could use to display the associated detail record. This works provided the function does not have any arguments (there is no way to pass arguments!) @@ -265,7 +267,7 @@ re_path(r'^book/(?P<pk>\d+)$', views.BookDetailView.as_view(), name='book-detail _Regular expressions_ are an incredibly powerful pattern mapping tool. They are, frankly, quite unintuitive and can be intimidating for beginners. Below is a very short primer! -The first thing to know is that regular expressions should usually be declared using the raw string literal syntax (i.e. they are enclosed as shown: **r'\<your regular expression text goes here>'**). +The first thing to know is that regular expressions should usually be declared using the raw string literal syntax (i.e., they are enclosed as shown: **r'\<your regular expression text goes here>'**). The main parts of the syntax you will need to know for declaring the pattern matches are: @@ -292,7 +294,7 @@ The main parts of the syntax you will need to know for declaring the pattern mat <tr> <td>\w</td> <td> - Match a word character, e.g. any upper- or lower-case character in the + Match a word character, e.g., any upper- or lower-case character in the alphabet, digit or the underscore character (_) </td> </tr> @@ -428,7 +430,7 @@ class BookDetailView(generic.DetailView): model = Book ``` -That's it! All you need to do now is create a template called **/django-locallibrary-tutorial/catalog/templates/catalog/book_detail.html**, and the view will pass it the database information for the specific `Book` record extracted by the URL mapper. Within the template you can access the book's details with the template variable named `object` OR `book` (i.e. generically `the_model_name`). +That's it! All you need to do now is create a template called **/django-locallibrary-tutorial/catalog/templates/catalog/book_detail.html**, and the view will pass it the database information for the specific `Book` record extracted by the URL mapper. Within the template you can access the book's details with the template variable named `object` OR `book` (i.e., generically `the_model_name`). If you need to, you can change the template used and the name of the context object used to reference the book in the template. You can also override methods to, for example, add additional information to the context. @@ -530,7 +532,7 @@ The first interesting thing we haven't seen before is the function `book.bookins {% endfor %} ``` -This method is needed because you declare a `ForeignKey` (one-to many) field only in the "many" side of the relationship (the `BookInstance`). Since you don't do anything to declare the relationship in the other ("one") model, it (the `Book`) doesn't have any field to get the set of associated records. To overcome this problem, Django constructs an appropriately named "reverse lookup" function that you can use. The name of the function is constructed by lower-casing the model name where the `ForeignKey` was declared, followed by `_set` (i.e. so the function created in `Book` is `bookinstance_set()`). +This method is needed because you declare a `ForeignKey` (one-to many) field only in the "many" side of the relationship (the `BookInstance`). Since you don't do anything to declare the relationship in the other ("one") model, it (the `Book`) doesn't have any field to get the set of associated records. To overcome this problem, Django constructs an appropriately named "reverse lookup" function that you can use. The name of the function is constructed by lower-casing the model name where the `ForeignKey` was declared, followed by `_set` (i.e., so the function created in `Book` is `bookinstance_set()`). > [!NOTE] > Here we use `all()` to get all records (the default). While you can use the `filter()` method to get a subset of records in code, you can't do this directly in templates because you can't specify arguments to functions. diff --git a/files/en-us/learn_web_development/extensions/server-side/django/home_page/index.md b/files/en-us/learn_web_development/extensions/server-side/django/home_page/index.md index e1c75fe8ca21418..282e9de78584414 100644 --- a/files/en-us/learn_web_development/extensions/server-side/django/home_page/index.md +++ b/files/en-us/learn_web_development/extensions/server-side/django/home_page/index.md @@ -1,10 +1,12 @@ --- title: "Django Tutorial Part 5: Creating our home page" +short-title: "5: Home page" slug: Learn_web_development/Extensions/Server-side/Django/Home_page page-type: learn-module-chapter +sidebar: learnsidebar --- -{{LearnSidebar}}{{PreviousMenuNext("Learn_web_development/Extensions/Server-side/Django/Admin_site", "Learn_web_development/Extensions/Server-side/Django/Generic_views", "Learn_web_development/Extensions/Server-side/Django")}} +{{PreviousMenuNext("Learn_web_development/Extensions/Server-side/Django/Admin_site", "Learn_web_development/Extensions/Server-side/Django/Generic_views", "Learn_web_development/Extensions/Server-side/Django")}} We're now ready to add the code that displays our first complete page — a home page for the [LocalLibrary](/en-US/docs/Learn_web_development/Extensions/Server-side/Django/Tutorial_local_library_website) website. The home page will show the number of records we have for each model type and provide sidebar navigation links to our other pages. Along the way we'll gain practical experience in writing basic URL maps and views, getting records from the database, and using templates. @@ -81,7 +83,7 @@ urlpatterns += [ ``` > [!NOTE] -> Whenever Django encounters the import function [`django.urls.include()`](https://docs.djangoproject.com/en/5.0/ref/urls/#django.urls.include), it splits the URL string at the designated end character and sends the remaining substring to the included _URLconf_ module for further processing. +> Whenever Django encounters the import function [`django.urls.include()`](https://docs.djangoproject.com/en/5.0/ref/urls/#django.urls.include), it splits the URL string at the designated end character and sends the remaining substring to the included _URLConf_ module for further processing. We also created a placeholder file for the _URLConf_ module, named **/catalog/urls.py**. Add the following lines to that file: @@ -97,7 +99,7 @@ The `path()` function defines the following: - A URL pattern, which is an empty string: `''`. We'll discuss URL patterns in detail when working on the other views. - A view function that will be called if the URL pattern is detected: `views.index`, which is the function named `index()` in the **views.py** file. -The `path()` function also specifies a `name` parameter, which is a unique identifier for _this_ particular URL mapping. You can use the name to "reverse" the mapper, i.e. to dynamically create a URL that points to the resource that the mapper is designed to handle. +The `path()` function also specifies a `name` parameter, which is a unique identifier for _this_ particular URL mapping. You can use the name to "reverse" the mapper, i.e., to dynamically create a URL that points to the resource that the mapper is designed to handle. For example, we can use the name parameter to link to our home page from any other page by adding the following link in a template: ```django diff --git a/files/en-us/learn_web_development/extensions/server-side/django/index.md b/files/en-us/learn_web_development/extensions/server-side/django/index.md index 694db14cc2ae1f6..023688e0159e281 100644 --- a/files/en-us/learn_web_development/extensions/server-side/django/index.md +++ b/files/en-us/learn_web_development/extensions/server-side/django/index.md @@ -2,11 +2,10 @@ title: Django Web Framework (Python) slug: Learn_web_development/Extensions/Server-side/Django page-type: learn-module +sidebar: learnsidebar --- -{{LearnSidebar}} - -{{NextMenu("Learn_web_development/Extensions/Server-side/Django/Introduction", "Learn_web_development/Extensions/Server-side/Django")}} +{{NextMenu("Learn_web_development/Extensions/Server-side/Django/Introduction", "Learn_web_development/Extensions/Server-side")}} Django is an extremely popular and fully featured server-side web framework, written in Python. This module shows you why Django is one of the most popular web server frameworks, how to set up a development environment, and how to start using it to create your own web applications. @@ -57,4 +56,4 @@ The following assessment will test your understanding of how to create a website - [DIY Django mini blog](/en-US/docs/Learn_web_development/Extensions/Server-side/Django/django_assessment_blog) - : In this assessment you'll use some of the knowledge you've learned from this module to create your own blog. -{{NextMenu("Learn_web_development/Extensions/Server-side/Django/Introduction", "Learn_web_development/Extensions/Server-side/Django")}} +{{NextMenu("Learn_web_development/Extensions/Server-side/Django/Introduction", "Learn_web_development/Extensions/Server-side")}} diff --git a/files/en-us/learn_web_development/extensions/server-side/django/introduction/index.md b/files/en-us/learn_web_development/extensions/server-side/django/introduction/index.md index 365a37e67ed9ed3..b922df2910287ef 100644 --- a/files/en-us/learn_web_development/extensions/server-side/django/introduction/index.md +++ b/files/en-us/learn_web_development/extensions/server-side/django/introduction/index.md @@ -2,9 +2,10 @@ title: Django introduction slug: Learn_web_development/Extensions/Server-side/Django/Introduction page-type: learn-module-chapter +sidebar: learnsidebar --- -{{LearnSidebar}}{{NextMenu("Learn_web_development/Extensions/Server-side/Django/development_environment", "Learn_web_development/Extensions/Server-side/Django")}} +{{NextMenu("Learn_web_development/Extensions/Server-side/Django/development_environment", "Learn_web_development/Extensions/Server-side/Django")}} In this first Django article, we answer the question "What is Django?" and give you an overview of what makes this web framework special. @@ -39,7 +40,7 @@ Django helps you write software that is: - : Django can be (and has been) used to build almost any type of website — from content management systems and wikis, through to social networks and news sites. It can work with any client-side framework, and can deliver content in almost any format (including HTML, RSS feeds, JSON, and XML). - Internally, while it provides choices for almost any functionality you might want (e.g. several popular databases, templating engines, etc.), it can also be extended to use other components if needed. + Internally, while it provides choices for almost any functionality you might want (e.g., several popular databases, templating engines, etc.), it can also be extended to use other components if needed. - Secure @@ -50,7 +51,7 @@ Django helps you write software that is: Django enables protection against many vulnerabilities by default, including SQL injection, cross-site scripting, cross-site request forgery and [clickjacking](/en-US/docs/Web/Security/Attacks/Clickjacking) (see [Website security](/en-US/docs/Learn_web_development/Extensions/Server-side/First_steps/Website_security) for more details of such attacks). - Scalable - - : Django uses a component-based "[shared-nothing](https://en.wikipedia.org/wiki/Shared_nothing_architecture)" architecture (each part of the architecture is independent of the others, and can hence be replaced or changed if needed). Having a clear separation between the different parts means that it can scale for increased traffic by adding hardware at any level: caching servers, database servers, or application servers. Some of the busiest sites have successfully scaled Django to meet their demands (e.g. Instagram and Disqus, to name just two). + - : Django uses a component-based "[shared-nothing](https://en.wikipedia.org/wiki/Shared_nothing_architecture)" architecture (each part of the architecture is independent of the others, and can hence be replaced or changed if needed). Having a clear separation between the different parts means that it can scale for increased traffic by adding hardware at any level: caching servers, database servers, or application servers. Some of the busiest sites have successfully scaled Django to meet their demands (e.g., Instagram and Disqus, to name just two). - Maintainable - : Django code is written using design principles and patterns that encourage the creation of maintainable and reusable code. In particular, it makes use of the Don't Repeat Yourself (DRY) principle so there is no unnecessary duplication, reducing the amount of code. Django also promotes the grouping of related functionality into reusable "applications" and, at a lower level, groups related code into modules (along the lines of the [Model View Controller (MVC)](/en-US/docs/Glossary/MVC) pattern). - Portable @@ -122,7 +123,7 @@ The `urlpatterns` object is a list of `path()` and/or `re_path()` functions (Pyt The first argument to both methods is a route (pattern) that will be matched. The `path()` method uses angle brackets to define parts of a URL that will be captured and passed through to the view function as named arguments. The `re_path()` function uses a flexible pattern matching approach known as a regular expression. We'll talk about these in a later article! -The second argument is another function that will be called when the pattern is matched. The notation `views.book_detail` indicates that the function is called `book_detail()` and can be found in a module called `views` (i.e. inside a file named `views.py`) +The second argument is another function that will be called when the pattern is matched. The notation `views.book_detail` indicates that the function is called `book_detail()` and can be found in a module called `views` (i.e., inside a file named `views.py`) ### Handling the request (views.py) @@ -183,7 +184,7 @@ class Team(models.Model): ### Querying data (views.py) -The Django model provides a simple query API for searching the associated database. This can match against a number of fields at a time using different criteria (e.g. exact, case-insensitive, greater than, etc.), and can support complex statements (for example, you can specify a search on U11 teams that have a team name that starts with "Fr" or ends with "al"). +The Django model provides a simple query API for searching the associated database. This can match against a number of fields at a time using different criteria (e.g., exact, case-insensitive, greater than, etc.), and can support complex statements (for example, you can specify a search on U11 teams that have a team name that starts with "Fr" or ends with "al"). The code snippet shows a view function (resource handler) for displaying all of our U09 teams. The `list_teams = Team.objects.filter(team_level__exact="U09")` line shows how we can use the model query API to filter for all records where the `team_level` field has exactly the text `U09` (note how this criteria is passed to the `filter()` function as an argument, with the field name and match type separated by a double underscore: **`team_level__exact`**). diff --git a/files/en-us/learn_web_development/extensions/server-side/django/models/index.md b/files/en-us/learn_web_development/extensions/server-side/django/models/index.md index 04eb1e19d3fe538..20da01002aa84aa 100644 --- a/files/en-us/learn_web_development/extensions/server-side/django/models/index.md +++ b/files/en-us/learn_web_development/extensions/server-side/django/models/index.md @@ -1,10 +1,12 @@ --- title: "Django Tutorial Part 3: Using models" +short-title: "3: Models" slug: Learn_web_development/Extensions/Server-side/Django/Models page-type: learn-module-chapter +sidebar: learnsidebar --- -{{LearnSidebar}}{{PreviousMenuNext("Learn_web_development/Extensions/Server-side/Django/skeleton_website", "Learn_web_development/Extensions/Server-side/Django/Admin_site", "Learn_web_development/Extensions/Server-side/Django")}} +{{PreviousMenuNext("Learn_web_development/Extensions/Server-side/Django/skeleton_website", "Learn_web_development/Extensions/Server-side/Django/Admin_site", "Learn_web_development/Extensions/Server-side/Django")}} This article shows how to define models for the LocalLibrary website. It explains what a model is, how it is declared, and some of the main field types. It also briefly shows a few of the main ways you can access model data. @@ -41,7 +43,7 @@ We know that we need to store information about books (title, summary, author, w When designing your models, it makes sense to have separate models for every "object" (a group of related information). In this case, the obvious objects are books, book instances, and authors. -You might also want to use models to represent selection-list options (e.g. like a drop down list of choices), rather than hard coding the choices into the website itself — this is recommended when all the options aren't known up front or may change. Obvious candidates for models, in this case, include the book genre (e.g. Science Fiction, French Poetry, etc.) and language (English, French, Japanese). +You might also want to use models to represent selection-list options (e.g., like a drop down list of choices), rather than hard coding the choices into the website itself — this is recommended when all the options aren't known up front or may change. Obvious candidates for models, in this case, include the book genre (e.g., Science Fiction, French Poetry, etc.) and language (English, French, Japanese). Once we've decided on our models and field, we need to think about the relationships. Django allows you to define relationships that are one to one (`OneToOneField`), one to many (`ForeignKey`) and many to many (`ManyToManyField`). @@ -99,7 +101,7 @@ A model can have an arbitrary number of fields, of any type — each one represe my_field_name = models.CharField(max_length=20, help_text='Enter field documentation') ``` -Our above example has a single field called `my_field_name`, of type `models.CharField` — which means that this field will contain strings of alphanumeric characters. The field types are assigned using specific classes, which determine the type of record that is used to store the data in the database, along with validation criteria to be used when values are received from an HTML form (i.e. what constitutes a valid value). The field types can also take arguments that further specify how the field is stored or can be used. In this case we are giving our field two arguments: +Our above example has a single field called `my_field_name`, of type `models.CharField` — which means that this field will contain strings of alphanumeric characters. The field types are assigned using specific classes, which determine the type of record that is used to store the data in the database, along with validation criteria to be used when values are received from an HTML form (i.e., what constitutes a valid value). The field types can also take arguments that further specify how the field is stored or can be used. In this case we are giving our field two arguments: - `max_length=20` — States that the maximum length of a value in this field is 20 characters. - `help_text='Enter field documentation'` — helpful text that may be displayed in a form to help users understand how the field is used. @@ -108,13 +110,13 @@ The field name is used to refer to it in queries and templates. Fields also have a label, which is specified using the `verbose_name` argument (with a default value of `None`). If `verbose_name` is not set, the label is created from the field name by replacing any underscores with a space, and capitalizing the first letter (for example, the field `my_field_name` would have a default label of _My field name_ when used in forms). -The order that fields are declared will affect their default order if a model is rendered in a form (e.g. in the Admin site), though this may be overridden. +The order that fields are declared will affect their default order if a model is rendered in a form (e.g., in the Admin site), though this may be overridden. ##### Common field arguments The following common arguments can be used when declaring many/most of the different field types: -- [help_text](https://docs.djangoproject.com/en/5.0/ref/models/fields/#help-text): Provides a text label for HTML forms (e.g. in the admin site), as described above. +- [help_text](https://docs.djangoproject.com/en/5.0/ref/models/fields/#help-text): Provides a text label for HTML forms (e.g., in the admin site), as described above. - [verbose_name](https://docs.djangoproject.com/en/5.0/ref/models/fields/#verbose-name): A human-readable name for the field used in field labels. If not specified, Django will infer the default verbose name from the field name. - [default](https://docs.djangoproject.com/en/5.0/ref/models/fields/#default): The default value for the field. This can be a value or a callable object, in which case the object will be called every time a new record is created. - [null](https://docs.djangoproject.com/en/5.0/ref/models/fields/#null): If `True`, Django will store blank values as `NULL` in the database for fields where this is appropriate (a `CharField` will instead store an empty string). The default is `False`. @@ -133,7 +135,7 @@ The following common arguments can be used when declaring many/most of the diffe > Apps created using **manage.py** set the type of the primary key to a [BigAutoField](https://docs.djangoproject.com/en/5.0/ref/models/fields/#bigautofield). > You can see this in the local library **catalog/apps.py** file: > - > ```py + > ```python > class CatalogConfig(AppConfig): > default_auto_field = 'django.db.models.BigAutoField' > ``` @@ -151,8 +153,8 @@ The following list describes some of the more commonly used types of fields. - [EmailField](https://docs.djangoproject.com/en/5.0/ref/models/fields/#emailfield) is used to store and validate email addresses. - [FileField](https://docs.djangoproject.com/en/5.0/ref/models/fields/#filefield) and [ImageField](https://docs.djangoproject.com/en/5.0/ref/models/fields/#imagefield) are used to upload files and images respectively (the `ImageField` adds additional validation that the uploaded file is an image). These have parameters to define how and where the uploaded files are stored. - [AutoField](https://docs.djangoproject.com/en/5.0/ref/models/fields/#autofield) is a special type of `IntegerField` that automatically increments. A primary key of this type is automatically added to your model if you don't explicitly specify one. -- [ForeignKey](https://docs.djangoproject.com/en/5.0/ref/models/fields/#foreignkey) is used to specify a one-to-many relationship to another database model (e.g. a car has one manufacturer, but a manufacturer can make many cars). The "one" side of the relationship is the model that contains the "key" (models containing a "foreign key" referring to that "key", are on the "many" side of such a relationship). -- [ManyToManyField](https://docs.djangoproject.com/en/5.0/ref/models/fields/#manytomanyfield) is used to specify a many-to-many relationship (e.g. a book can have several genres, and each genre can contain several books). In our library app we will use these very similarly to `ForeignKeys`, but they can be used in more complicated ways to describe the relationships between groups. These have the parameter `on_delete` to define what happens when the associated record is deleted (e.g. a value of `models.SET_NULL` would set the value to `NULL`). +- [ForeignKey](https://docs.djangoproject.com/en/5.0/ref/models/fields/#foreignkey) is used to specify a one-to-many relationship to another database model (e.g., a car has one manufacturer, but a manufacturer can make many cars). The "one" side of the relationship is the model that contains the "key" (models containing a "foreign key" referring to that "key", are on the "many" side of such a relationship). +- [ManyToManyField](https://docs.djangoproject.com/en/5.0/ref/models/fields/#manytomanyfield) is used to specify a many-to-many relationship (e.g., a book can have several genres, and each genre can contain several books). In our library app we will use these very similarly to `ForeignKeys`, but they can be used in more complicated ways to describe the relationships between groups. These have the parameter `on_delete` to define what happens when the associated record is deleted (e.g., a value of `models.SET_NULL` would set the value to `NULL`). There are many other types of fields, including fields for different types of numbers (big integers, small integers, floats), booleans, URLs, slugs, unique ids, and other "time-related" information (duration, time, etc.). You can view the [full list here](https://docs.djangoproject.com/en/5.0/ref/models/fields/#field-types). @@ -266,7 +268,7 @@ number_wild_books = wild_books.count() The fields to match and the type of match are defined in the filter parameter name, using the format: `field_name__match_type` (note the _double underscore_ between `title` and `contains` above). Above we're filtering `title` with a case-sensitive match. There are many other types of matches you can do: `icontains` (case insensitive), `iexact` (case-insensitive exact match), `exact` (case-sensitive exact match) and `in`, `gt` (greater than), `startswith`, etc. The [full list is here](https://docs.djangoproject.com/en/5.0/ref/models/querysets/#field-lookups). -In some cases, you'll need to filter on a field that defines a one-to-many relationship to another model (e.g. a `ForeignKey`). In this case, you can "index" to fields within the related model with additional double underscores. +In some cases, you'll need to filter on a field that defines a one-to-many relationship to another model (e.g., a `ForeignKey`). In this case, you can "index" to fields within the related model with additional double underscores. So for example to filter for books with a specific genre pattern, you will have to index to the `name` through the `genre` field, as shown below: ```python @@ -276,7 +278,7 @@ books_containing_genre = Book.objects.filter(genre__name__icontains='fiction') > [!NOTE] > You can use underscores (`__`) to navigate as many levels of relationships (`ForeignKey`/`ManyToManyField`) as you like. -> For example, a `Book` that had different types, defined using a further "cover" relationship might have a parameter name: `type__cover__name__exact='hard'.` +> For example, a `Book` that had different types, defined using a further "cover" relationship might have a parameter name: `type__cover__name__exact='hard'`. There is a lot more you can do with queries, including backwards searches from related models, chaining filters, returning a smaller set of values, etc. For more information, see [Making queries](https://docs.djangoproject.com/en/5.0/topics/db/queries/) (Django Docs). @@ -442,7 +444,7 @@ The method `__str__()` represents the `BookInstance` object using a combination > A little Python: > > - Starting with Python 3.6, you can use the string interpolation syntax (also known as f-strings): `f'{self.id} ({self.book.title})'`. -> - In older versions of this tutorial, we were using a [formatted string](https://peps.python.org/pep-3101/) syntax, which is also a valid way of formatting strings in Python (e.g. `'{0} ({1})'.format(self.id,self.book.title)`). +> - In older versions of this tutorial, we were using a [formatted string](https://peps.python.org/pep-3101/) syntax, which is also a valid way of formatting strings in Python (e.g., `'{0} ({1})'.format(self.id,self.book.title)`). ### Author model @@ -488,7 +490,7 @@ Some things to consider: - Should "language" be associated with a `Book`, `BookInstance`, or some other object? - Should the different languages be represented using model, a free text field, or a hard-coded selection list? -After you've decided, add the field. You can see what we decided on GitHub [here](https://github.com/mdn/django-locallibrary-tutorial/blob/main/catalog/models.py). +After you've decided, add the field. You can see what we decided [for our project on GitHub](https://github.com/mdn/django-locallibrary-tutorial/blob/main/catalog/models.py). Don't forget that after a change to your model, you should again re-run your database migrations to add the changes. diff --git a/files/en-us/learn_web_development/extensions/server-side/django/sessions/index.md b/files/en-us/learn_web_development/extensions/server-side/django/sessions/index.md index 92db346d16adb0e..c4e60a1c5d32a81 100644 --- a/files/en-us/learn_web_development/extensions/server-side/django/sessions/index.md +++ b/files/en-us/learn_web_development/extensions/server-side/django/sessions/index.md @@ -1,10 +1,12 @@ --- title: "Django Tutorial Part 7: Sessions framework" +short-title: "7: Sessions framework" slug: Learn_web_development/Extensions/Server-side/Django/Sessions page-type: learn-module-chapter +sidebar: learnsidebar --- -{{LearnSidebar}}{{PreviousMenuNext("Learn_web_development/Extensions/Server-side/Django/Generic_views", "Learn_web_development/Extensions/Server-side/Django/Authentication", "Learn_web_development/Extensions/Server-side/Django")}} +{{PreviousMenuNext("Learn_web_development/Extensions/Server-side/Django/Generic_views", "Learn_web_development/Extensions/Server-side/Django/Authentication", "Learn_web_development/Extensions/Server-side/Django")}} This tutorial extends our [LocalLibrary](/en-US/docs/Learn_web_development/Extensions/Server-side/Django/Tutorial_local_library_website) website, adding a session-based visit-counter to the home page. This is a relatively simple example, but it does show how you can use the session framework to provide persistent behavior for anonymous users in your own sites. diff --git a/files/en-us/learn_web_development/extensions/server-side/django/skeleton_website/index.md b/files/en-us/learn_web_development/extensions/server-side/django/skeleton_website/index.md index 85fd0d55f76d0a0..4e011b3e94e78af 100644 --- a/files/en-us/learn_web_development/extensions/server-side/django/skeleton_website/index.md +++ b/files/en-us/learn_web_development/extensions/server-side/django/skeleton_website/index.md @@ -1,10 +1,12 @@ --- title: "Django Tutorial Part 2: Creating a skeleton website" +short-title: "2: Skeleton website" slug: Learn_web_development/Extensions/Server-side/Django/skeleton_website page-type: learn-module-chapter +sidebar: learnsidebar --- -{{LearnSidebar}}{{PreviousMenuNext("Learn_web_development/Extensions/Server-side/Django/Tutorial_local_library_website", "Learn_web_development/Extensions/Server-side/Django/Models", "Learn_web_development/Extensions/Server-side/Django")}} +{{PreviousMenuNext("Learn_web_development/Extensions/Server-side/Django/Tutorial_local_library_website", "Learn_web_development/Extensions/Server-side/Django/Models", "Learn_web_development/Extensions/Server-side/Django")}} This second article in our [Django Tutorial](/en-US/docs/Learn_web_development/Extensions/Server-side/Django/Tutorial_local_library_website) shows how you can create a "skeleton" website project as a basis, which you can then populate with site-specific settings, paths, models, views, and templates. @@ -107,7 +109,7 @@ py manage.py startapp catalog > If you're working on Windows, wherever you see a command starting with `python3` you should instead use `py` (or `py -3`). The tool creates a new folder and populates it with files for the different parts of the application (shown in the following example). -Most of the files are named after their purpose (e.g. views should be stored in **views.py**, models in **models.py**, tests in **tests.py**, administration site configuration in **admin.py**, application registration in **apps.py**) and contain some minimal boilerplate code for working with the associated objects. +Most of the files are named after their purpose (e.g., views should be stored in **views.py**, models in **models.py**, tests in **tests.py**, administration site configuration in **admin.py**, application registration in **apps.py**) and contain some minimal boilerplate code for working with the associated objects. The updated project directory should now look like this: @@ -206,7 +208,7 @@ Function views Class-based views 1. Add an import: from other_app.views import Home 2. Add a URL to urlpatterns: path('', Home.as_view(), name='home') -Including another URLconf +Including another URLConf 1. Import the include() function: from django.urls import include, path 2. Add a URL to urlpatterns: path('blog/', include('blog.urls')) """ @@ -221,7 +223,7 @@ urlpatterns = [ The URL mappings are managed through the `urlpatterns` variable, which is a Python _list_ of `path()` functions. Each `path()` function either associates a URL pattern to a _specific view_, which will be displayed when the pattern is matched, or with another list of URL pattern testing code (in this second case, the pattern becomes the "base URL" for patterns defined in the target module). The `urlpatterns` list initially defines a single function that maps all URLs with the pattern _admin/_ to the module `admin.site.urls`, which contains the Administration application's own URL mapping definitions. > [!NOTE] -> The route in `path()` is a string defining a URL pattern to match. This string might include a named variable (in angle brackets), e.g. `'catalog/<id>/'`. This pattern will match a URL like **catalog/_any_chars_/** and pass _`any_chars`_ to the view as a string with the parameter name `id`. We discuss path methods and route patterns further in later topics. +> The route in `path()` is a string defining a URL pattern to match. This string might include a named variable (in angle brackets), e.g., `'catalog/<id>/'`. This pattern will match a URL like **catalog/_any_chars_/** and pass _`any_chars`_ to the view as a string with the parameter name `id`. We discuss path methods and route patterns further in later topics. To add a new list item to the `urlpatterns` list, add the following lines to the bottom of the file. This new item includes a `path()` that forwards requests with the pattern `catalog/` to the module `catalog.urls` (the file with the relative URL **catalog/urls.py**). @@ -237,7 +239,7 @@ urlpatterns += [ > [!NOTE] > Note that we included the import line (`from django.urls import include`) with the code that uses it (so it is easy to see what we've added), but it is common to include all your import lines at the top of a Python file. -Now let's redirect the root URL of our site (i.e. `127.0.0.1:8000`) to the URL `127.0.0.1:8000/catalog/`. This is the only app we'll be using in this project. To do this, we'll use a special view function, `RedirectView`, which takes the new relative URL to redirect to (`/catalog/`) as its first argument when the URL pattern specified in the `path()` function is matched (the root URL, in this case). +Now let's redirect the root URL of our site (i.e., `127.0.0.1:8000`) to the URL `127.0.0.1:8000/catalog/`. This is the only app we'll be using in this project. To do this, we'll use a special view function, `RedirectView`, which takes the new relative URL to redirect to (`/catalog/`) as its first argument when the URL pattern specified in the `path()` function is matched (the root URL, in this case). Add the following lines to the bottom of the file: diff --git a/files/en-us/learn_web_development/extensions/server-side/django/testing/index.md b/files/en-us/learn_web_development/extensions/server-side/django/testing/index.md index e2c8b39086e3f00..8658228058475bf 100644 --- a/files/en-us/learn_web_development/extensions/server-side/django/testing/index.md +++ b/files/en-us/learn_web_development/extensions/server-side/django/testing/index.md @@ -1,10 +1,12 @@ --- title: "Django Tutorial Part 10: Testing a Django web application" +short-title: "10: Testing" slug: Learn_web_development/Extensions/Server-side/Django/Testing page-type: learn-module-chapter +sidebar: learnsidebar --- -{{LearnSidebar}}{{PreviousMenuNext("Learn_web_development/Extensions/Server-side/Django/Forms", "Learn_web_development/Extensions/Server-side/Django/Deployment", "Learn_web_development/Extensions/Server-side/Django")}} +{{PreviousMenuNext("Learn_web_development/Extensions/Server-side/Django/Forms", "Learn_web_development/Extensions/Server-side/Django/Deployment", "Learn_web_development/Extensions/Server-side/Django")}} As websites grow they become harder to test manually. Not only is there more to test, but, as interactions between components become more complex, a small change in one area can impact other areas, so more changes will be required to ensure everything keeps working and errors are not introduced as more changes are made. One way to mitigate these problems is to write automated tests, which can easily and reliably be run every time you make a change. This tutorial shows how to automate _unit testing_ of your website using Django's test framework. @@ -29,7 +31,7 @@ The [Local Library](/en-US/docs/Learn_web_development/Extensions/Server-side/Dja Automated tests can really help with this problem! The obvious benefits are that they can be run much faster than manual tests, can test to a much lower level of detail, and test exactly the same functionality every time (human testers are nowhere near as reliable!) Because they are fast, automated tests can be executed more regularly, and if a test fails, they point to exactly where code is not performing as expected. -In addition, automated tests can act as the first real-world "user" of your code, forcing you to be rigorous about defining and documenting how your website should behave. Often they are the basis for your code examples and documentation. For these reasons, some software development processes start with test definition and implementation, after which the code is written to match the required behavior (e.g. [test-driven](https://en.wikipedia.org/wiki/Test-driven_development) and [behavior-driven](https://en.wikipedia.org/wiki/Behavior-driven_development) development). +In addition, automated tests can act as the first real-world "user" of your code, forcing you to be rigorous about defining and documenting how your website should behave. Often they are the basis for your code examples and documentation. For these reasons, some software development processes start with test definition and implementation, after which the code is written to match the required behavior (e.g., [test-driven](https://en.wikipedia.org/wiki/Test-driven_development) and [behavior-driven](https://en.wikipedia.org/wiki/Behavior-driven_development) development). This tutorial shows how to write automated tests for Django, by adding a number of tests to the _LocalLibrary_ website. @@ -345,7 +347,7 @@ class AuthorModelTest(TestCase): def test_get_absolute_url(self): author = Author.objects.get(id=1) - # This will also fail if the urlconf is not defined. + # This will also fail if the URLConf is not defined. self.assertEqual(author.get_absolute_url(), '/catalog/author/1') ``` @@ -380,7 +382,7 @@ def test_object_name_is_last_name_comma_first_name(self): def test_get_absolute_url(self): author = Author.objects.get(id=1) - # This will also fail if the urlconf is not defined. + # This will also fail if the URLConf is not defined. self.assertEqual(author.get_absolute_url(), '/catalog/author/1') ``` @@ -411,7 +413,7 @@ The patterns for testing the other models are similar so we won't continue to di The philosophy for testing your forms is the same as for testing your models; you need to test anything that you've coded or your design specifies, but not the behavior of the underlying framework and other third party libraries. -Generally this means that you should test that the forms have the fields that you want, and that these are displayed with appropriate labels and help text. You don't need to verify that Django validates the field type correctly (unless you created your own custom field and validation) — i.e. you don't need to test that an email field only accepts emails. However you would need to test any additional validation that you expect to be performed on the fields and any messages that your code will generate for errors. +Generally this means that you should test that the forms have the fields that you want, and that these are displayed with appropriate labels and help text. You don't need to verify that Django validates the field type correctly (unless you created your own custom field and validation) — i.e., you don't need to test that an email field only accepts emails. However you would need to test any additional validation that you expect to be performed on the fields and any messages that your code will generate for errors. Consider our form for renewing books. This has just one field for the renewal date, which will have a label and help text that we will need to verify. @@ -475,7 +477,7 @@ class RenewBookFormTest(TestCase): self.assertTrue(form.is_valid()) ``` -The first two functions test that the field's `label` and `help_text` are as expected. We have to access the field using the fields dictionary (e.g. `form.fields['renewal_date']`). Note here that we also have to test whether the label value is `None`, because even though Django will render the correct label it returns `None` if the value is not _explicitly_ set. +The first two functions test that the field's `label` and `help_text` are as expected. We have to access the field using the fields dictionary (e.g., `form.fields['renewal_date']`). Note here that we also have to test whether the label value is `None`, because even though Django will render the correct label it returns `None` if the value is not _explicitly_ set. The rest of the functions test that the form is valid for renewal dates just inside the acceptable range and invalid for values outside the range. Note how we construct test date values around our current date (`datetime.date.today()`) using `datetime.timedelta()` (in this case specifying a number of days or weeks). We then just create the form, passing in our data, and test if it is valid. @@ -991,6 +993,5 @@ The next and final tutorial shows how you can deploy your wonderful (and fully t - [Advanced testing topics](https://docs.djangoproject.com/en/5.0/topics/testing/advanced/) (Django docs) - [A Guide to Testing in Django](https://toastdriven.com/blog/2011/apr/09/guide-to-testing-in-django/) (Toast Driven Blog, 2011) - [Workshop: Test-Driven Web Development with Django](https://test-driven-django-development.readthedocs.io/en/latest/index.html) (San Diego Python, 2014) -- [Testing in Django (Part 1) - Best Practices and Examples](https://realpython.com/testing-in-django-part-1-best-practices-and-examples/) (RealPython, 2013) {{PreviousMenuNext("Learn_web_development/Extensions/Server-side/Django/Forms", "Learn_web_development/Extensions/Server-side/Django/Deployment", "Learn_web_development/Extensions/Server-side/Django")}} diff --git a/files/en-us/learn_web_development/extensions/server-side/django/tutorial_local_library_website/index.md b/files/en-us/learn_web_development/extensions/server-side/django/tutorial_local_library_website/index.md index 1e03e42edd92709..762b29947d86439 100644 --- a/files/en-us/learn_web_development/extensions/server-side/django/tutorial_local_library_website/index.md +++ b/files/en-us/learn_web_development/extensions/server-side/django/tutorial_local_library_website/index.md @@ -1,10 +1,12 @@ --- title: "Django Tutorial: The Local Library website" +short-title: "1: Local library tutorial" slug: Learn_web_development/Extensions/Server-side/Django/Tutorial_local_library_website page-type: learn-module-chapter +sidebar: learnsidebar --- -{{LearnSidebar}}{{PreviousMenuNext("Learn_web_development/Extensions/Server-side/Django/development_environment", "Learn_web_development/Extensions/Server-side/Django/skeleton_website", "Learn_web_development/Extensions/Server-side/Django")}} +{{PreviousMenuNext("Learn_web_development/Extensions/Server-side/Django/development_environment", "Learn_web_development/Extensions/Server-side/Django/skeleton_website", "Learn_web_development/Extensions/Server-side/Django")}} The first article in our practical tutorial series explains what you'll learn, and provides an overview of the "local library" example website we'll be working through and evolving in subsequent articles. diff --git a/files/en-us/learn_web_development/extensions/server-side/django/web_application_security/index.md b/files/en-us/learn_web_development/extensions/server-side/django/web_application_security/index.md index 8da09f70547ab3c..9543a1e0a483c0c 100644 --- a/files/en-us/learn_web_development/extensions/server-side/django/web_application_security/index.md +++ b/files/en-us/learn_web_development/extensions/server-side/django/web_application_security/index.md @@ -1,10 +1,12 @@ --- title: Django web application security +short-title: Django security slug: Learn_web_development/Extensions/Server-side/Django/web_application_security page-type: learn-module-chapter +sidebar: learnsidebar --- -{{LearnSidebar}}{{PreviousMenuNext("Learn_web_development/Extensions/Server-side/Django/Deployment", "Learn_web_development/Extensions/Server-side/Django/django_assessment_blog", "Learn_web_development/Extensions/Server-side/Django")}} +{{PreviousMenuNext("Learn_web_development/Extensions/Server-side/Django/Deployment", "Learn_web_development/Extensions/Server-side/Django/django_assessment_blog", "Learn_web_development/Extensions/Server-side/Django")}} Protecting user data is an essential part of any website design. We previously explained some of the more common security threats in the article [Web security](/en-US/docs/Web/Security) — this article provides a practical demonstration of how Django's in-built protections handle such threats. @@ -161,7 +163,7 @@ Django also provides other forms of protection (most of which would be hard or n - SQL injection protection - : SQL injection vulnerabilities enable malicious users to execute arbitrary SQL code on a database, allowing data to be accessed, modified, or deleted irrespective of the user's permissions. In almost every case you'll be accessing the database using Django's querysets/models, so the resulting SQL will be properly escaped by the underlying database driver. If you do need to write raw queries or custom SQL then you'll need to explicitly think about preventing SQL injection. - Clickjacking protection - - : In this attack a malicious user hijacks clicks meant for a visible top level site and routes them to a hidden page beneath. This technique might be used, for example, to display a legitimate bank site but capture the login credentials in an invisible [`<iframe>`](/en-US/docs/Web/HTML/Element/iframe) controlled by the attacker. Django contains [clickjacking](/en-US/docs/Web/Security/Attacks/Clickjacking) protection in the form of the [`X-Frame-Options` middleware](https://docs.djangoproject.com/en/4.0/ref/middleware/#django.middleware.clickjacking.XFrameOptionsMiddleware) which, in a supporting browser, can prevent a site from being rendered inside a frame. + - : In this attack a malicious user hijacks clicks meant for a visible top level site and routes them to a hidden page beneath. This technique might be used, for example, to display a legitimate bank site but capture the login credentials in an invisible [`<iframe>`](/en-US/docs/Web/HTML/Reference/Elements/iframe) controlled by the attacker. Django contains [clickjacking](/en-US/docs/Web/Security/Attacks/Clickjacking) protection in the form of the [`X-Frame-Options` middleware](https://docs.djangoproject.com/en/4.0/ref/middleware/#django.middleware.clickjacking.XFrameOptionsMiddleware) which, in a supporting browser, can prevent a site from being rendered inside a frame. - Enforcing TLS/HTTPS - : TLS/HTTPS can be enabled on the web server in order to encrypt all traffic between the site and browser, including authentication credentials that would otherwise be sent in plain text (enabling HTTPS is highly recommended). If HTTPS is enabled then Django provides a number of other protections you can use: - [`SECURE_PROXY_SSL_HEADER`](https://docs.djangoproject.com/en/5.0/ref/settings/#std:setting-SECURE_PROXY_SSL_HEADER) can be used to check whether content is secure, even if it is incoming from a non-HTTP proxy. diff --git a/files/en-us/learn_web_development/extensions/server-side/express_nodejs/deployment/index.md b/files/en-us/learn_web_development/extensions/server-side/express_nodejs/deployment/index.md index b7e21e36826ddaf..3d5126c6bb04766 100644 --- a/files/en-us/learn_web_development/extensions/server-side/express_nodejs/deployment/index.md +++ b/files/en-us/learn_web_development/extensions/server-side/express_nodejs/deployment/index.md @@ -1,10 +1,12 @@ --- title: "Express Tutorial Part 7: Deploying to production" +short-title: "7: Deploying" slug: Learn_web_development/Extensions/Server-side/Express_Nodejs/deployment page-type: learn-module-chapter +sidebar: learnsidebar --- -{{LearnSidebar}}{{PreviousMenu("Learn_web_development/Extensions/Server-side/Express_Nodejs/forms", "Learn_web_development/Extensions/Server-side/Express_Nodejs")}} +{{PreviousMenu("Learn_web_development/Extensions/Server-side/Express_Nodejs/forms", "Learn_web_development/Extensions/Server-side/Express_Nodejs")}} Now you've created (and tested) an awesome [LocalLibrary](/en-US/docs/Learn_web_development/Extensions/Server-side/Express_Nodejs/Tutorial_local_library_website) website, you're going to want to install it on a public web server so that it can be accessed by library staff and members over the Internet. This article provides an overview of how you might go about finding a host to deploy your website, and what you need to do in order to get your site ready for production. @@ -35,19 +37,19 @@ Up to now, you've been working in a [development environment](/en-US/docs/Learn_ - Make a few changes to your project settings. - Set up a production-level infrastructure for serving your website. -This tutorial provides some guidance on your options for choosing a hosting site, a brief overview of what you need to do in order to get your Express app ready for production, and a working example of how to install the LocalLibrary website onto the [Railway](https://railway.app/) cloud hosting service. +This tutorial provides some guidance on your options for choosing a hosting site, a brief overview of what you need to do in order to get your Express app ready for production, and a working example of how to install the LocalLibrary website onto the [Railway](https://railway.com/) cloud hosting service. ## What is a production environment? The production environment is the environment provided by the server computer where you will run your website for external consumption. The environment includes: - Computer hardware on which the website runs. -- Operating system (e.g. Linux or Windows). +- Operating system (e.g., Linux or Windows). - Programming language runtime and framework libraries on top of which your website is written. - Web server infrastructure, possibly including a web server, reverse proxy, load balancer, etc. - Databases on which your website is dependent. -The server computer could be located on your premises and connected to the Internet by a fast link, but it is far more common to use a computer that is hosted "in the cloud". What this actually means is that your code is run on some remote computer (or possibly a "virtual" computer) in your hosting company's data center(s). The remote server will usually offer some guaranteed level of computing resources (e.g. CPU, RAM, storage memory, etc.) and Internet connectivity for a certain price. +The server computer could be located on your premises and connected to the Internet by a fast link, but it is far more common to use a computer that is hosted "in the cloud". What this actually means is that your code is run on some remote computer (or possibly a "virtual" computer) in your hosting company's data center(s). The remote server will usually offer some guaranteed level of computing resources (e.g., CPU, RAM, storage memory, etc.) and Internet connectivity for a certain price. This sort of remotely accessible computing/networking hardware is referred to as _Infrastructure as a Service (IaaS)_. Many IaaS vendors provide options to preinstall a particular operating system, onto which you must install the other components of your production environment. Other vendors allow you to select more fully-featured environments, perhaps including a complete Node setup. @@ -74,9 +76,9 @@ Some of the things to consider when choosing a host: - Level of support for scaling horizontally (adding more machines) and vertically (upgrading to more powerful machines) and the costs of doing so. - The locations where the supplier has data centers, and hence where access is likely to be fastest. - The host's historical uptime and downtime performance. -- Tools provided for managing the site — are they easy to use and are they secure (e.g. SFTP vs. FTP). +- Tools provided for managing the site — are they easy to use and are they secure (e.g., SFTP vs. FTP). - Inbuilt frameworks for monitoring your server. -- Known limitations. Some hosts will deliberately block certain services (e.g. email). Others offer only a certain number of hours of "live time" in some price tiers, or only offer a small amount of storage. +- Known limitations. Some hosts will deliberately block certain services (e.g., email). Others offer only a certain number of hours of "live time" in some price tiers, or only offer a small amount of storage. - Additional benefits. Some providers will offer free domain names and support for TLS certificates that you would otherwise have to pay for. - Whether the "free" tier you're relying on expires over time, and whether the cost of migrating to a more expensive tier means you would have been better off using some other service in the first place! @@ -86,7 +88,7 @@ They are however great for testing low-traffic sites in a hosted environment, an Popular choices in this category include [Glitch](https://glitch.com/), [Python Anywhere](https://www.pythonanywhere.com/), [Amazon Web Services](https://docs.aws.amazon.com/awsaccountbilling/latest/aboutv2/billing-free-tier.html), [Microsoft Azure](https://azure.microsoft.com/en-us/pricing/details/app-service/linux/), etc. Most providers also offer a "basic" or "hobby" tier that is intended for small production sites, and which provide more useful levels of computing power and fewer limitations. -[Railway](https://railway.app/), [Heroku](https://www.heroku.com/), [DigitalOcean](https://www.digitalocean.com/) and [Python Anywhere](https://www.pythonanywhere.com/) are examples of popular hosting providers that have a relatively inexpensive basic computing tier (in the $5 to $10 USD per month range). +[Railway](https://railway.com/), [Heroku](https://www.heroku.com/), [DigitalOcean](https://www.digitalocean.com/) and [Python Anywhere](https://www.pythonanywhere.com/) are examples of popular hosting providers that have a relatively inexpensive basic computing tier (in the $5 to $10 USD per month range). > [!NOTE] > Remember that price is not the only selection criterion. @@ -126,6 +128,7 @@ Replace the line with the following code that uses `process.env.MONGODB_URI` to ```js // Set up mongoose connection const mongoose = require("mongoose"); + mongoose.set("strictQuery", false); const dev_db_url = @@ -152,7 +155,7 @@ This change can be made either by using `export`, an environment file, or the OS ### Log appropriately -Logging calls can have an impact on a high-traffic website. In a production environment, you may need to log website activity (e.g. tracking traffic or logging API calls) but you should attempt to minimize the amount of logging added for debugging purposes. +Logging calls can have an impact on a high-traffic website. In a production environment, you may need to log website activity (e.g., tracking traffic or logging API calls) but you should attempt to minimize the amount of logging added for debugging purposes. One way to minimize "debug" logging in production is to use a module like [debug](https://www.npmjs.com/package/debug) that allows you to control what logging is performed by setting an environment variable. For example, the code fragment below shows how you might set up "author" logging. @@ -172,7 +175,7 @@ exports.author_update_get = asyncHandler(async (req, res, next) => { return next(err); } - res.render("author_form", { title: "Update Author", author: author }); + res.render("author_form", { title: "Update Author", author }); }); ``` @@ -262,7 +265,7 @@ app.use( We normally might have just inserted `app.use(helmet());` to add the _subset_ of the security-related headers that make sense for most sites. However in the [LocalLibrary base template](/en-US/docs/Learn_web_development/Extensions/Server-side/Express_Nodejs/Displaying_data/LocalLibrary_base_template) we include some bootstrap and jQuery scripts. -These violate the helmet's _default_ [Content Security Policy (CSP)](/en-US/docs/Web/HTTP/CSP), which does not allow loading of cross-site scripts. +These violate the helmet's _default_ [Content Security Policy (CSP)](/en-US/docs/Web/HTTP/Guides/CSP), which does not allow loading of cross-site scripts. To allow these scripts to be loaded we modify the helmet configuration so that it sets CSP directives to allow script loading from the indicated domains. For your own server you can add/disable specific headers as needed by following the [instructions for using helmet here](https://www.npmjs.com/package/helmet). @@ -285,11 +288,11 @@ Then add the module to the middleware chain with the `use()` method. ```js const compression = require("compression"); const helmet = require("helmet"); +const RateLimit = require("express-rate-limit"); const app = express(); // Set up rate limiter: maximum of twenty requests per minute -const RateLimit = require("express-rate-limit"); const limiter = RateLimit({ windowMs: 1 * 60 * 1000, // 1 minute max: 20, @@ -359,7 +362,7 @@ The steps are: 2. Once you are logged in, click the **+** link in the top toolbar and select **New repository**. 3. Fill in all the fields on this form. While these are not compulsory, they are strongly recommended. - - Enter a new repository name (e.g. _express-locallibrary-tutorial_), and description (e.g. "Local Library website written in Express (Node)". + - Enter a new repository name (e.g., _express-locallibrary-tutorial_), and description (e.g., "Local Library website written in Express (Node)". - Choose **Node** in the _Add .gitignore_ selection list. - Choose your preferred license in the _Add license_ selection list. - Check **Initialize this repository with a README**. @@ -376,7 +379,7 @@ The steps are: Now that the repository ("repo") is created on GitHub we are going to want to clone (copy) it to our local computer: -1. Install _git_ for your local computer (you can find versions for different platforms [here](https://git-scm.com/downloads)). +1. Install _git_ for your local computer ([official Git download guide](https://git-scm.com/downloads)). 2. Open a command prompt/terminal and clone your repo using the URL you copied above: ```bash @@ -476,7 +479,7 @@ We are choosing to use Glitch for several reasons: - The starter plan environment has a limited amount of container RAM and storage space. There is more than enough for the tutorial, in particular because our database is hosted elsewhere. - Custom domains are not well supported (at time of writing). - - Other limitations can be found in the [Glitch technical restrictions page](https://help.glitch.com/hc/en-us/articles/16287495313293-Technical-Restrictions). + - Other limitations can be found in the [Glitch technical restrictions page](https://help.glitch.com/s/article/Technical-Restrictions). While Glitch is appropriate for hosting this demonstration, you should take the time to determine if it is [suitable for your own website](#choosing_a_hosting_provider). @@ -486,9 +489,9 @@ Glitch provides a web-based interface in which you can create projects from star As you make changes, the project is built and run in its own isolated and independent virtualized container. How this all works "under the hood" is a mystery — Glitch doesn't say. -What is clear is that as long as you create a fairly standard nodejs web application (for example, using `package.json` for your dependencies), and don't consume more resources than listed in the [technical restrictions](https://help.glitch.com/hc/en-us/articles/16287495313293-Technical-Restrictions), your application should "just work". +What is clear is that as long as you create a fairly standard nodejs web application (for example, using `package.json` for your dependencies), and don't consume more resources than listed in the [technical restrictions](https://help.glitch.com/s/article/Technical-Restrictions), your application should "just work". -Once the application is running, it can be configured for production using [private data](https://help.glitch.com/hc/en-us/articles/16287550167437-Adding-Private-Data) supplied in a `.env` file. +Once the application is running, it can be configured for production using [private data](https://help.glitch.com/s/article/Adding-Private-Data) supplied in a `.env` file. The values in the secret data are read by the application as environment variables, which, as you will recall from a previous section, is how we configured our application to get its database URL. Note that the variables are _secret_: the `.env` should not be included in your GitHub repository. @@ -576,7 +579,7 @@ The site updates as you enter values into the editor. > [!NOTE] > We didn't create this file. -> It is intended for [private data](https://help.glitch.com/hc/en-us/articles/16287550167437-Adding-Private-Data) and was created automatically on import to Glitch. +> It is intended for [private data](https://help.glitch.com/s/article/Adding-Private-Data) and was created automatically on import to Glitch. > It is never exported or copied. ### Other configuration variables @@ -604,7 +607,7 @@ Some of the things you can do are: ## Example: Hosting on Railway -This section provides a practical demonstration of how to install _LocalLibrary_ on [Railway](https://railway.app/). +This section provides a practical demonstration of how to install _LocalLibrary_ on [Railway](https://railway.com/). ### Why Railway? @@ -616,10 +619,10 @@ Railway is an attractive hosting option for several reasons: - Railway takes care of most of the infrastructure so you don't have to. Not having to worry about servers, load balancers, reverse proxies, and so on, makes it much easier to get started. -- Railway has a [focus on developer experience for development and deployment](https://docs.railway.app/maturity/compare-to-heroku), which leads to a faster and softer learning curve than many other alternatives. +- Railway has a [focus on developer experience for development and deployment](https://docs.railway.com/maturity/compare-to-heroku), which leads to a faster and softer learning curve than many other alternatives. - The skills and concepts you will learn when using Railway are transferrable. While Railway has some excellent new features, other popular hosting services use many of the same ideas and approaches. -- [Railway documentation](https://docs.railway.app/) is clear and complete. +- [Railway documentation](https://docs.railway.com/) is clear and complete. - The service appears to be very reliable, and if you end up loving it, the pricing is predictable, and scaling your app is very easy. You should take the time to determine if Railway is [suitable for your own website](#choosing_a_hosting_provider). @@ -638,11 +641,11 @@ Having installed all the dependencies, Railway will look for scripts named "buil > Railway uses [Nixpacks](https://nixpacks.com/docs) to recognize various web application frameworks written in different programming languages. > You don't need to know anything else for this tutorial, but you can find out more about options for deploying node applications in [Nixpacks Node](https://nixpacks.com/docs/providers/node). -Once the application is running it can configure itself using information provided in [environment variables](https://docs.railway.app/guides/variables). +Once the application is running it can configure itself using information provided in [environment variables](https://docs.railway.com/guides/variables). For example, an application that uses a database must get the address using a variable. The database service itself may be hosted by Railway or some other provider. -Developers interact with Railway through the Railway site, and using a special [Command Line Interface (CLI)](https://docs.railway.app/guides/cli) tool. +Developers interact with Railway through the Railway site, and using a special [Command Line Interface (CLI)](https://docs.railway.com/guides/cli) tool. The CLI allows you to associate a local GitHub repository with a railway project, upload the repository from the local branch to the live site, inspect the logs of the running process, set and get configuration variables and much more. One of the most useful features is that you can use the CLI to run your local project with the same environment variables as the live project. @@ -653,10 +656,10 @@ Next we will set up a Railway account, install our website and a database, and t To start using Railway you will first need to create an account: -- Go to [railway.app](https://railway.app/) and click the **Login** link in the top toolbar. +- Go to [railway.com](https://railway.com/) and click the **Login** link in the top toolbar. - Select GitHub in the popup to login using your GitHub credentials - You may then need to go to your email and verify your account. -- You'll then be logged in to the Railway.app dashboard: <https://railway.app/dashboard>. +- You'll then be logged in to the Railway.com dashboard: <https://railway.com/dashboard>. ### Deploy on Railway from GitHub @@ -759,7 +762,7 @@ You can add data through the website interface and it should work in the same wa ### Install the client -Download and install the Railway client for your local operating system by following the [instructions here](https://docs.railway.app/guides/cli). +Download and install the Railway client for your local operating system by following the [instructions here](https://docs.railway.com/guides/cli). After the client is installed you will be able run commands. Some of the more important operations include deploying the current directory of your computer to an associated Railway project (without having to upload to GitHub), and running your project locally using the same settings as you have on the production server. @@ -788,7 +791,7 @@ That's the end of this tutorial on setting up Express apps in production, and al - [Production Best Practices: Security](https://expressjs.com/en/advanced/best-practice-security.html) (Express docs) - Railway Docs - - [CLI](https://docs.railway.app/guides/cli) + - [CLI](https://docs.railway.com/guides/cli) - DigitalOcean diff --git a/files/en-us/learn_web_development/extensions/server-side/express_nodejs/development_environment/index.md b/files/en-us/learn_web_development/extensions/server-side/express_nodejs/development_environment/index.md index 2c0d25cbdf1cf1a..1ab2bed5ef5d7bb 100644 --- a/files/en-us/learn_web_development/extensions/server-side/express_nodejs/development_environment/index.md +++ b/files/en-us/learn_web_development/extensions/server-side/express_nodejs/development_environment/index.md @@ -1,13 +1,19 @@ --- title: Setting up a Node development environment +short-title: Dev environment setup slug: Learn_web_development/Extensions/Server-side/Express_Nodejs/development_environment page-type: learn-module-chapter +sidebar: learnsidebar --- -{{LearnSidebar}}{{PreviousMenuNext("Learn_web_development/Extensions/Server-side/Express_Nodejs/Introduction", "Learn_web_development/Extensions/Server-side/Express_Nodejs/Tutorial_local_library_website", "Learn_web_development/Extensions/Server-side/Express_Nodejs")}} +{{PreviousMenuNext("Learn_web_development/Extensions/Server-side/Express_Nodejs/Introduction", "Learn_web_development/Extensions/Server-side/Express_Nodejs/Tutorial_local_library_website", "Learn_web_development/Extensions/Server-side/Express_Nodejs")}} Now that you know what [Express](/en-US/docs/Learn_web_development/Extensions/Server-side/Express_Nodejs/Introduction#introducing_express) is for, we'll show you how to set up and test a Node/Express development environment on Windows, or Linux (Ubuntu), or macOS. For any of those operating systems, this article provides what you need to start developing Express apps. +> [!WARNING] +> The Express tutorial is written for Express version 4, while the latest version is Express 5. +> We plan to update the documentation to support Express 5 in the second half of 2025. Until then, we have updated the installation commands so they install Express 4 rather than the latest version, to avoid any potential compatibility problems. + <table> <tbody> <tr> @@ -42,7 +48,7 @@ There are other peripheral tools that are part of a typical development environm ### What operating systems are supported? -_Node_ can be run on Windows, macOS, many flavors of Linux, Docker, etc. There is a full list on the Node.js [Downloads](https://nodejs.org/en/download/package-manager) page. Almost any personal computer should have the necessary performance to run Node during development. _Express_ is run in a _Node_ environment, and hence can run on any platform that runs _Node_. +_Node_ can be run on Windows, macOS, many flavors of Linux, Docker, etc. There is a full list on the Node.js [Downloads](https://nodejs.org/en/download) page. Almost any personal computer should have the necessary performance to run Node during development. _Express_ is run in a _Node_ environment, and hence can run on any platform that runs _Node_. In this article we provide setup instructions for Windows, macOS, and Ubuntu Linux. @@ -64,7 +70,7 @@ In order to use _Express_ you will have to install _Nodejs_ and the [Node Packag To make this easier we'll first install a node version manager, and then we'll use it to install the latest Long Term Supported (LTS) versions of node and npm. > [!NOTE] -> You can also install nodejs and npm with installers provide on <https://nodejs.org/en/> (select the button to download the LTS build that is "Recommended for most users"), or you can [install using the package manager for your OS](https://nodejs.org/en/download/package-manager) (nodejs.org). +> You can also install nodejs and npm with installers provide on <https://nodejs.org/en/> (select the button to download the LTS build that is "Recommended for most users"), or you can [install using the package manager for your OS](https://nodejs.org/en/download) (nodejs.org). > We highly recommend using a node version manager as these make it easier to install, upgrade, and switch between any particular version of node and npm. ### Windows @@ -136,20 +142,21 @@ As a slightly more exciting test let's create a very basic "pure node" server th 1. Copy the following text into a file named **hellonode.js**. This uses pure Node features (nothing from Express): ```js - //Load HTTP module + // Load HTTP module const http = require("http"); + const hostname = "127.0.0.1"; const port = 3000; - //Create HTTP server and listen on port 3000 for requests + // Create HTTP server and listen on port 3000 for requests const server = http.createServer((req, res) => { - //Set the response HTTP header with HTTP status and Content type + // Set the response HTTP header with HTTP status and Content type res.statusCode = 200; res.setHeader("Content-Type", "text/plain"); res.end("Hello World\n"); }); - //listen for request on port 3000, and as a callback function have the port listened on logged + // Listen for request on port 3000, and as a callback function have the port listened on logged server.listen(port, hostname, () => { console.log(`Server running at http://${hostname}:${port}/`); }); @@ -223,7 +230,7 @@ The following steps show how you can use npm to download a package, save it into 3. Now install Express in the `myapp` directory and save it in the dependencies list of your **package.json** file: ```bash - npm install express + npm install express@^4.21.2 ``` The dependencies section of your **package.json** will now appear at the end of the **package.json** file and will include _Express_. @@ -240,7 +247,7 @@ The following steps show how you can use npm to download a package, save it into "author": "", "license": "ISC", "dependencies": { - "express": "^4.17.1" + "express": "^4.21.2" } } ``` @@ -250,6 +257,7 @@ The following steps show how you can use npm to download a package, save it into ```js const express = require("express"); + const app = express(); const port = 3000; @@ -434,7 +442,7 @@ In the next article we start working through a tutorial to build a complete web ## See also -- [Downloads](https://nodejs.org/en/download/package-manager) page (nodejs.org) +- [Downloads](https://nodejs.org/en/download) page (nodejs.org) - [Installing Express](https://expressjs.com/en/starter/installing.html) (expressjs.com) - [Express Application Generator](https://expressjs.com/en/starter/generator.html) (expressjs.com) - [Using Node.js with Windows subsystem for Linux](https://learn.microsoft.com/en-us/windows/dev-environment/javascript/) (docs.microsoft.com) diff --git a/files/en-us/learn_web_development/extensions/server-side/express_nodejs/displaying_data/author_detail_page/index.md b/files/en-us/learn_web_development/extensions/server-side/express_nodejs/displaying_data/author_detail_page/index.md index 5380ff4f74107be..f27a3f101bb7c5a 100644 --- a/files/en-us/learn_web_development/extensions/server-side/express_nodejs/displaying_data/author_detail_page/index.md +++ b/files/en-us/learn_web_development/extensions/server-side/express_nodejs/displaying_data/author_detail_page/index.md @@ -2,10 +2,9 @@ title: Author detail page slug: Learn_web_development/Extensions/Server-side/Express_Nodejs/Displaying_data/Author_detail_page page-type: learn-module-chapter +sidebar: learnsidebar --- -{{LearnSidebar}} - The author detail page needs to display the information about the specified `Author`, identified using their (automatically generated) `_id` field value, along with a list of all the `Book` objects associated with that `Author`. ## Controller @@ -38,7 +37,7 @@ exports.author_detail = asyncHandler(async (req, res, next) => { res.render("author_detail", { title: "Author Detail", - author: author, + author, author_books: allBooksByAuthor, }); }); diff --git a/files/en-us/learn_web_development/extensions/server-side/express_nodejs/displaying_data/author_list_page/index.md b/files/en-us/learn_web_development/extensions/server-side/express_nodejs/displaying_data/author_list_page/index.md index dd0bcc59042adf9..c6bdb140c91641f 100644 --- a/files/en-us/learn_web_development/extensions/server-side/express_nodejs/displaying_data/author_list_page/index.md +++ b/files/en-us/learn_web_development/extensions/server-side/express_nodejs/displaying_data/author_list_page/index.md @@ -2,10 +2,9 @@ title: Author list page and Genre list page challenge slug: Learn_web_development/Extensions/Server-side/Express_Nodejs/Displaying_data/Author_list_page page-type: learn-module-chapter +sidebar: learnsidebar --- -{{LearnSidebar}} - The author list page needs to display a list of all authors in the database, with each author name linked to its associated author detail page. The date of birth and date of death should be listed after the name on the same line. ## Controller diff --git a/files/en-us/learn_web_development/extensions/server-side/express_nodejs/displaying_data/book_detail_page/index.md b/files/en-us/learn_web_development/extensions/server-side/express_nodejs/displaying_data/book_detail_page/index.md index 172b3b8b3c619cc..6f5b84e9b0821e0 100644 --- a/files/en-us/learn_web_development/extensions/server-side/express_nodejs/displaying_data/book_detail_page/index.md +++ b/files/en-us/learn_web_development/extensions/server-side/express_nodejs/displaying_data/book_detail_page/index.md @@ -2,10 +2,9 @@ title: Book detail page slug: Learn_web_development/Extensions/Server-side/Express_Nodejs/Displaying_data/Book_detail_page page-type: learn-module-chapter +sidebar: learnsidebar --- -{{LearnSidebar}} - The _Book detail page_ needs to display the information for a specific `Book` (identified using its automatically generated `_id` field value), along with information about each associated copy in the library (`BookInstance`). Wherever we display an author, genre, or book instance, these should be linked to the associated detail page for that item. ## Controller @@ -30,7 +29,7 @@ exports.book_detail = asyncHandler(async (req, res, next) => { res.render("book_detail", { title: book.title, - book: book, + book, book_instances: bookInstances, }); }); @@ -53,11 +52,11 @@ Create **/views/book_detail.pug** and add the text below. extends layout block content - h1 Title: #{book.title} + h1 Title: !{book.title} p #[strong Author: ] a(href=book.author.url) #{book.author.name} - p #[strong Summary:] #{book.summary} + p #[strong Summary:] !{book.summary} p #[strong ISBN:] #{book.isbn} p #[strong Genre: ] each val, index in book.genre @@ -86,7 +85,11 @@ block content p There are no copies of this book in the library. ``` -Almost everything in this template has been demonstrated in previous sections. +Note the preceding `!` in `!{book.title}` and `!{book.summary}`, which ensures that values are not escaped for display. +That's done because we've already sanitized the data we're displaying programmatically, and sanitizing again would display our "sanitized markup" rather than the safe version of the original text. +We've chosen not to do the same thing for Author, Genre, and so on (though we could), because we're not expecting them to include any "dangerous" characters that require sanitization. + +Almost everything else in this template has been demonstrated in previous sections. > [!NOTE] > The list of genres associated with the book is implemented in the template as below. This adds a comma and a non breaking space after every genre associated with the book except for the last one. diff --git a/files/en-us/learn_web_development/extensions/server-side/express_nodejs/displaying_data/book_list_page/index.md b/files/en-us/learn_web_development/extensions/server-side/express_nodejs/displaying_data/book_list_page/index.md index 7ec1dbf417afe18..8e5b7c22103f15d 100644 --- a/files/en-us/learn_web_development/extensions/server-side/express_nodejs/displaying_data/book_list_page/index.md +++ b/files/en-us/learn_web_development/extensions/server-side/express_nodejs/displaying_data/book_list_page/index.md @@ -2,10 +2,9 @@ title: Book list page slug: Learn_web_development/Extensions/Server-side/Express_Nodejs/Displaying_data/Book_list_page page-type: learn-module-chapter +sidebar: learnsidebar --- -{{LearnSidebar}} - Next we'll implement our book list page. This page needs to display a list of all books in the database along with their author, with each book title being a hyperlink to its associated book detail page. ## Controller @@ -48,7 +47,7 @@ block content ul each book in book_list li - a(href=book.url) #{book.title} + a(href=book.url) !{book.title} | (#{book.author.name}) else diff --git a/files/en-us/learn_web_development/extensions/server-side/express_nodejs/displaying_data/bookinstance_detail_page_and_challenge/index.md b/files/en-us/learn_web_development/extensions/server-side/express_nodejs/displaying_data/bookinstance_detail_page_and_challenge/index.md index 8d01f7a54aff659..483b5730776a676 100644 --- a/files/en-us/learn_web_development/extensions/server-side/express_nodejs/displaying_data/bookinstance_detail_page_and_challenge/index.md +++ b/files/en-us/learn_web_development/extensions/server-side/express_nodejs/displaying_data/bookinstance_detail_page_and_challenge/index.md @@ -2,10 +2,9 @@ title: BookInstance detail page and challenge slug: Learn_web_development/Extensions/Server-side/Express_Nodejs/Displaying_data/BookInstance_detail_page_and_challenge page-type: learn-module-chapter +sidebar: learnsidebar --- -{{LearnSidebar}} - ## BookInstance detail page The `BookInstance` detail page needs to display the information for each `BookInstance`, identified using its (automatically generated) `_id` field value. This will include the `Book` name (as a link to the _Book detail page_) along with other information in the record. @@ -79,7 +78,7 @@ Run the application and open your browser to `http://localhost:3000/`. Select th ## Challenge -Currently most _dates_ displayed on the site use the default JavaScript format (e.g. _Tue Oct 06 2020 15:49:58 GMT+1100 (AUS Eastern Daylight Time))_. The challenge for this article is to improve the appearance of the date display for `Author` lifespan information (date of death/birth) and for _BookInstance detail_ pages to use the format: Oct 6th, 2016. +Currently most _dates_ displayed on the site use the default JavaScript format (e.g., _Tue Oct 06 2020 15:49:58 GMT+1100 (AUS Eastern Daylight Time))_. The challenge for this article is to improve the appearance of the date display for `Author` lifespan information (date of death/birth) and for _BookInstance detail_ pages to use the format: Oct 6th, 2016. > [!NOTE] > You can use the same approach as we used for the _Book Instance List_ (adding the virtual property for the lifespan to the `Author` model and use [luxon](https://www.npmjs.com/package/luxon) to format the date strings). diff --git a/files/en-us/learn_web_development/extensions/server-side/express_nodejs/displaying_data/bookinstance_list_page/index.md b/files/en-us/learn_web_development/extensions/server-side/express_nodejs/displaying_data/bookinstance_list_page/index.md index 60b48f4a54596c0..af629fe03663e4e 100644 --- a/files/en-us/learn_web_development/extensions/server-side/express_nodejs/displaying_data/bookinstance_list_page/index.md +++ b/files/en-us/learn_web_development/extensions/server-side/express_nodejs/displaying_data/bookinstance_list_page/index.md @@ -2,10 +2,9 @@ title: BookInstance list page slug: Learn_web_development/Extensions/Server-side/Express_Nodejs/Displaying_data/BookInstance_list_page page-type: learn-module-chapter +sidebar: learnsidebar --- -{{LearnSidebar}} - Next we'll implement our list of all book copies (`BookInstance`) in the library. This page needs to include the title of the `Book` associated with each `BookInstance` (linked to its detail page) along with other information in the `BookInstance` model, including the status, imprint, and unique id of each copy. The unique id text should be linked to the `BookInstance` detail page. ## Controller diff --git a/files/en-us/learn_web_development/extensions/server-side/express_nodejs/displaying_data/date_formatting_using_moment/index.md b/files/en-us/learn_web_development/extensions/server-side/express_nodejs/displaying_data/date_formatting_using_moment/index.md index c3a604057189011..edbecf9075a8b14 100644 --- a/files/en-us/learn_web_development/extensions/server-side/express_nodejs/displaying_data/date_formatting_using_moment/index.md +++ b/files/en-us/learn_web_development/extensions/server-side/express_nodejs/displaying_data/date_formatting_using_moment/index.md @@ -2,10 +2,9 @@ title: Date formatting using luxon slug: Learn_web_development/Extensions/Server-side/Express_Nodejs/Displaying_data/Date_formatting_using_moment page-type: learn-module-chapter +sidebar: learnsidebar --- -{{LearnSidebar}} - The default rendering of dates from our models is very ugly: _Mon Apr 10 2020 15:49:58 GMT+1100 (AUS Eastern Daylight Time)_. In this section we'll show how you can update the _BookInstance List_ page from the previous section to present the `due_date` field in a more friendly format: Apr 10th, 2023. The approach we will use is to create a virtual property in our `BookInstance` model that returns the formatted date. We'll do the actual formatting using [luxon](https://www.npmjs.com/package/luxon), a powerful, modern, and friendly library for parsing, validating, manipulating, formatting and localising dates. diff --git a/files/en-us/learn_web_development/extensions/server-side/express_nodejs/displaying_data/genre_detail_page/index.md b/files/en-us/learn_web_development/extensions/server-side/express_nodejs/displaying_data/genre_detail_page/index.md index 36c2480438ef090..3538580c6abd72d 100644 --- a/files/en-us/learn_web_development/extensions/server-side/express_nodejs/displaying_data/genre_detail_page/index.md +++ b/files/en-us/learn_web_development/extensions/server-side/express_nodejs/displaying_data/genre_detail_page/index.md @@ -2,10 +2,9 @@ title: Genre detail page slug: Learn_web_development/Extensions/Server-side/Express_Nodejs/Displaying_data/Genre_detail_page page-type: learn-module-chapter +sidebar: learnsidebar --- -{{LearnSidebar}} - The genre _detail_ page needs to display the information for a particular genre instance, using its automatically generated `_id` field value as the identifier. The ID of the required genre record is encoded at the end of the URL and extracted automatically based on the route definition (**/genre/:id**). It is then accessed within the controller via the request parameters: `req.params.id`. @@ -39,7 +38,7 @@ exports.genre_detail = asyncHandler(async (req, res, next) => { res.render("genre_detail", { title: "Genre Detail", - genre: genre, + genre, genre_books: booksInGenre, }); }); @@ -49,7 +48,7 @@ We first use `Genre.findById()` to get Genre information for a specific ID, and Because the two requests do not depend on each other, we use `Promise.all()` to run the database queries in parallel (this same approach for running queries in parallel was demonstrated in the [home page](/en-US/docs/Learn_web_development/Extensions/Server-side/Express_Nodejs/Displaying_data/Home_page#controller)). We `await` on the returned promise, and once it settles we check the results. -If the genre does not exist in the database (i.e. it may have been deleted) then `findById()` will return successfully with no results. +If the genre does not exist in the database (i.e., it may have been deleted) then `findById()` will return successfully with no results. In this case we want to display a "not found" page, so we create an `Error` object and pass it to the `next` middleware function in the chain. > [!NOTE] @@ -87,7 +86,7 @@ The view is very similar to all our other templates. The main difference is that ## What does it look like? -Run the application and open your browser to `http://localhost:3000/`. Select the _All genres_ link, then select one of the genres (e.g. "Fantasy"). If everything is set up correctly, your page should look something like the following screenshot. +Run the application and open your browser to `http://localhost:3000/`. Select the _All genres_ link, then select one of the genres (e.g., "Fantasy"). If everything is set up correctly, your page should look something like the following screenshot. ![Genre Detail Page - Express Local Library site](locallibary_express_genre_detail.png) diff --git a/files/en-us/learn_web_development/extensions/server-side/express_nodejs/displaying_data/home_page/index.md b/files/en-us/learn_web_development/extensions/server-side/express_nodejs/displaying_data/home_page/index.md index 3924c6675794eff..cc635212a20c5c4 100644 --- a/files/en-us/learn_web_development/extensions/server-side/express_nodejs/displaying_data/home_page/index.md +++ b/files/en-us/learn_web_development/extensions/server-side/express_nodejs/displaying_data/home_page/index.md @@ -2,10 +2,9 @@ title: Home page slug: Learn_web_development/Extensions/Server-side/Express_Nodejs/Displaying_data/Home_page page-type: learn-module-chapter +sidebar: learnsidebar --- -{{LearnSidebar}} - The first page we'll create will be the website home page, which is accessible from either the site (`/`) or catalog (`catalog/`) root. This will display some static text describing the site, along with dynamically calculated "counts" of different record types in the database. We've already created a route for the home page. In order to complete the page we need to update our controller function to fetch "counts" of records from the database, and create a view (template) that we can use to render the page. @@ -21,7 +20,7 @@ As a reminder, all the route functions are defined in **/routes/catalog.js**: ```js // GET catalog home page. -router.get("/", book_controller.index); //This actually maps to /catalog/ because we import the route with a /catalog prefix +router.get("/", book_controller.index); // This actually maps to /catalog/ because we import the route with a /catalog prefix ``` The book controller index function passed as a parameter (`book_controller.index`) has a "placeholder" implementation defined in **/controllers/bookController.js**: @@ -136,7 +135,7 @@ Under the _Dynamic content_ heading we list the number of copies of each model. Note that the template values for the data are the keys that were specified when `render()` was called in the route handler function. > [!NOTE] -> We didn't escape the count values (i.e. we used the `!{}` syntax) because the count values are calculated. If the information was supplied by end-users then we'd escape the variable for display. +> We didn't escape the count values (i.e., we used the `!{}` syntax) because the count values are calculated. If the information was supplied by end-users then we'd escape the variable for display. ## What does it look like? diff --git a/files/en-us/learn_web_development/extensions/server-side/express_nodejs/displaying_data/index.md b/files/en-us/learn_web_development/extensions/server-side/express_nodejs/displaying_data/index.md index 64975fb9f5b1071..a3f4de7edb76803 100644 --- a/files/en-us/learn_web_development/extensions/server-side/express_nodejs/displaying_data/index.md +++ b/files/en-us/learn_web_development/extensions/server-side/express_nodejs/displaying_data/index.md @@ -1,10 +1,12 @@ --- title: "Express Tutorial Part 5: Displaying library data" +short-title: "5: Displaying data" slug: Learn_web_development/Extensions/Server-side/Express_Nodejs/Displaying_data page-type: learn-module-chapter +sidebar: learnsidebar --- -{{LearnSidebar}}{{PreviousMenuNext("Learn_web_development/Extensions/Server-side/Express_Nodejs/routes", "Learn_web_development/Extensions/Server-side/Express_Nodejs/forms", "Learn_web_development/Extensions/Server-side/Express_Nodejs")}} +{{PreviousMenuNext("Learn_web_development/Extensions/Server-side/Express_Nodejs/routes", "Learn_web_development/Extensions/Server-side/Express_Nodejs/forms", "Learn_web_development/Extensions/Server-side/Express_Nodejs")}} We're now ready to add the pages that display the [LocalLibrary](/en-US/docs/Learn_web_development/Extensions/Server-side/Express_Nodejs/Tutorial_local_library_website) website books and other data. The pages will include a home page that shows how many records we have of each model type and list and detail pages for all of our models. Along the way, we'll gain practical experience in getting records from the database, and using templates. diff --git a/files/en-us/learn_web_development/extensions/server-side/express_nodejs/displaying_data/locallibrary_base_template/index.md b/files/en-us/learn_web_development/extensions/server-side/express_nodejs/displaying_data/locallibrary_base_template/index.md index 4d6bc6f5eeba522..55c5bf0fcddefd4 100644 --- a/files/en-us/learn_web_development/extensions/server-side/express_nodejs/displaying_data/locallibrary_base_template/index.md +++ b/files/en-us/learn_web_development/extensions/server-side/express_nodejs/displaying_data/locallibrary_base_template/index.md @@ -2,11 +2,10 @@ title: LocalLibrary base template slug: Learn_web_development/Extensions/Server-side/Express_Nodejs/Displaying_data/LocalLibrary_base_template page-type: learn-module-chapter +sidebar: learnsidebar --- -{{LearnSidebar}} - -Now that we understand how to extend templates using Pug, let's start by creating a base template for the project. This will have a sidebar with links for the pages we hope to create across the tutorial articles (e.g. to display and create books, genres, authors, etc.) and a main content area that we'll override in each of our individual pages. +Now that we understand how to extend templates using Pug, let's start by creating a base template for the project. This will have a sidebar with links for the pages we hope to create across the tutorial articles (e.g., to display and create books, genres, authors, etc.) and a main content area that we'll override in each of our individual pages. Open **/views/layout.pug** and replace the content with the code below. diff --git a/files/en-us/learn_web_development/extensions/server-side/express_nodejs/displaying_data/template_primer/index.md b/files/en-us/learn_web_development/extensions/server-side/express_nodejs/displaying_data/template_primer/index.md index cb35fc447a575de..bc39881b71b7040 100644 --- a/files/en-us/learn_web_development/extensions/server-side/express_nodejs/displaying_data/template_primer/index.md +++ b/files/en-us/learn_web_development/extensions/server-side/express_nodejs/displaying_data/template_primer/index.md @@ -2,10 +2,9 @@ title: Template primer slug: Learn_web_development/Extensions/Server-side/Express_Nodejs/Displaying_data/Template_primer page-type: learn-module-chapter +sidebar: learnsidebar --- -{{LearnSidebar}} - A template is a text file defining the _structure_ or layout of an output file, with placeholders used to represent where data will be inserted when the template is rendered (in _Express_, templates are referred to as _views_). ## Express template choices @@ -31,7 +30,7 @@ If you look in the views directory you will see the .pug files for the project's These include the view for the home page (**index.pug**) and base template (**layout.pug**) that we will need to replace with our own content. ```plain -/express-locallibrary-tutorial //the project root +/express-locallibrary-tutorial # the project root /views error.pug index.pug @@ -42,7 +41,7 @@ These include the view for the home page (**index.pug**) and base template (**la The example template file below shows off many of Pug's most useful features. -The first thing to notice is that the file maps the structure of a typical HTML file, with the first word in (almost) every line being an HTML element, and indentation being used to indicate nested elements. So for example, the `body` element is inside an `html` element, and paragraph elements (`p`) are within the `body` element, etc. Non-nested elements (e.g. individual paragraphs) are on separate lines. +The first thing to notice is that the file maps the structure of a typical HTML file, with the first word in (almost) every line being an HTML element, and indentation being used to indicate nested elements. So for example, the `body` element is inside an `html` element, and paragraph elements (`p`) are within the `body` element, etc. Non-nested elements (e.g., individual paragraphs) are on separate lines. ```pug doctype html @@ -87,7 +86,7 @@ Element attributes are defined in parentheses after their associated element. In - `script(type='text/javascript')`, `link(rel='stylesheet', href='/stylesheets/style.css')` - `meta(name='viewport' content='width=device-width initial-scale=1')` -The values of all attributes are _escaped_ (e.g. characters like `>` are converted to their HTML code equivalents like `&gt;`) to prevent JavaScript injection or cross-site scripting attacks. +The values of all attributes are _escaped_ (e.g., characters like `>` are converted to their HTML code equivalents like `&gt;`) to prevent JavaScript injection or cross-site scripting attacks. If a tag is followed by the equals sign, the following text is treated as a JavaScript _expression_. So for example, in the first line below, the content of the `h1` tag will be _variable_ `title` (either defined in the file or passed into the template from Express). In the second line the paragraph content is a text string concatenated with the `title` variable. In both cases the default behavior is to _escape_ the line. @@ -110,7 +109,7 @@ p This line has an un-escaped string: !{'<em> is emphasized</em>'}, an escaped s ``` > [!NOTE] -> You will almost always want to escape data from users (via the **`#{}`** syntax). Data that can be trusted (e.g. generated counts of records, etc.) may be displayed without escaping the values. +> You will almost always want to escape data from users (via the **`#{}`** syntax). Data that can be trusted (e.g., generated counts of records, etc.) may be displayed without escaping the values. You can use the pipe ('**|**') character at the beginning of a line to indicate "[plain text](https://pugjs.org/language/plain-text.html)". For example, the additional text shown below will be displayed on the same line as the preceding anchor, but will not be linked. diff --git a/files/en-us/learn_web_development/extensions/server-side/express_nodejs/forms/create_author_form/index.md b/files/en-us/learn_web_development/extensions/server-side/express_nodejs/forms/create_author_form/index.md index 572a0fc6e8494bc..bd76172cd5d6af4 100644 --- a/files/en-us/learn_web_development/extensions/server-side/express_nodejs/forms/create_author_form/index.md +++ b/files/en-us/learn_web_development/extensions/server-side/express_nodejs/forms/create_author_form/index.md @@ -2,10 +2,9 @@ title: Create Author form slug: Learn_web_development/Extensions/Server-side/Express_Nodejs/forms/Create_author_form page-type: learn-module-chapter +sidebar: learnsidebar --- -{{LearnSidebar}} - This subarticle shows how to define a page for creating `Author` objects. ## Import validation and sanitization methods @@ -77,18 +76,17 @@ exports.author_create_post = [ // There are errors. Render form again with sanitized values/errors messages. res.render("author_form", { title: "Create Author", - author: author, + author, errors: errors.array(), }); return; - } else { - // Data from form is valid. - - // Save author. - await author.save(); - // Redirect to new author record. - res.redirect(author.url); } + // Data from form is valid. + + // Save author. + await author.save(); + // Redirect to new author record. + res.redirect(author.url); }), ]; ``` diff --git a/files/en-us/learn_web_development/extensions/server-side/express_nodejs/forms/create_book_form/index.md b/files/en-us/learn_web_development/extensions/server-side/express_nodejs/forms/create_book_form/index.md index 3eca4872bf67d5e..e46399e96107d4c 100644 --- a/files/en-us/learn_web_development/extensions/server-side/express_nodejs/forms/create_book_form/index.md +++ b/files/en-us/learn_web_development/extensions/server-side/express_nodejs/forms/create_book_form/index.md @@ -2,10 +2,9 @@ title: Create Book form slug: Learn_web_development/Extensions/Server-side/Express_Nodejs/forms/Create_book_form page-type: learn-module-chapter +sidebar: learnsidebar --- -{{LearnSidebar}} - This subarticle shows how to define a page/form to create `Book` objects. This is a little more complicated than the equivalent `Author` or `Genre` pages because we need to get and display available `Author` and `Genre` records in our `Book` form. ## Import validation and sanitization methods @@ -105,7 +104,7 @@ exports.book_create_post = [ title: "Create Book", authors: allAuthors, genres: allGenres, - book: book, + book, errors: errors.array(), }); } else { @@ -215,7 +214,7 @@ The main differences are in how we implement the selection-type fields: `Author` - The set of genres are displayed as checkboxes, and use the `checked` value we set in the controller to determine whether or not the box should be selected. - The set of authors are displayed as a single-selection alphabetically ordered drop-down list (the list passed to the template is already sorted, so we don't need to do that in the template). - If the user has previously selected a book author (i.e. when fixing invalid field values after initial form submission, or when updating book details) the author will be re-selected when the form is displayed. Here we determine what author to select by comparing the id of the current author option with the value previously entered by the user (passed in via the `book` variable). + If the user has previously selected a book author (i.e., when fixing invalid field values after initial form submission, or when updating book details) the author will be re-selected when the form is displayed. Here we determine what author to select by comparing the id of the current author option with the value previously entered by the user (passed in via the `book` variable). > [!NOTE] > If there is an error in the submitted form, then, when the form is to be re-rendered, the new book author's id and the existing books's authors ids are of type `Schema.Types.ObjectId`. So to compare them we must convert them to strings first. diff --git a/files/en-us/learn_web_development/extensions/server-side/express_nodejs/forms/create_bookinstance_form/index.md b/files/en-us/learn_web_development/extensions/server-side/express_nodejs/forms/create_bookinstance_form/index.md index 2570a5f04bae30b..d134bbb7116f81e 100644 --- a/files/en-us/learn_web_development/extensions/server-side/express_nodejs/forms/create_bookinstance_form/index.md +++ b/files/en-us/learn_web_development/extensions/server-side/express_nodejs/forms/create_bookinstance_form/index.md @@ -2,10 +2,9 @@ title: Create BookInstance form slug: Learn_web_development/Extensions/Server-side/Express_Nodejs/forms/Create_BookInstance_form page-type: learn-module-chapter +sidebar: learnsidebar --- -{{LearnSidebar}} - This subarticle shows how to define a page/form to create `BookInstance` objects. This is very much like the form we used to [create `Book` objects](/en-US/docs/Learn_web_development/Extensions/Server-side/Express_Nodejs/forms/Create_book_form). @@ -88,11 +87,10 @@ exports.bookinstance_create_post = [ bookinstance: bookInstance, }); return; - } else { - // Data from form is valid - await bookInstance.save(); - res.redirect(bookInstance.url); } + // Data from form is valid + await bookInstance.save(); + res.redirect(bookInstance.url); }), ]; ``` @@ -158,7 +156,7 @@ The one thing to note is the line where we set the "due back" date to `bookinsta input#due_back.form-control(type='date', name='due_back' value=(undefined===bookinstance ? '' : bookinstance.due_back_yyyy_mm_dd)) ``` -The date value has to be set in the format `YYYY-MM-DD` because this is expected by [`<input>` elements with `type="date"`](/en-US/docs/Web/HTML/Element/input/date), however the date is not stored in this format so we have to convert it before setting the value in the control. +The date value has to be set in the format `YYYY-MM-DD` because this is expected by [`<input>` elements with `type="date"`](/en-US/docs/Web/HTML/Reference/Elements/input/date), however the date is not stored in this format so we have to convert it before setting the value in the control. The `due_back_yyyy_mm_dd()` method is added to the `BookInstance` model in the next section. ## Model—virtual `due_back_yyyy_mm_dd()` method diff --git a/files/en-us/learn_web_development/extensions/server-side/express_nodejs/forms/create_genre_form/index.md b/files/en-us/learn_web_development/extensions/server-side/express_nodejs/forms/create_genre_form/index.md index bf596ab81858f2d..2013c1c24b4f66c 100644 --- a/files/en-us/learn_web_development/extensions/server-side/express_nodejs/forms/create_genre_form/index.md +++ b/files/en-us/learn_web_development/extensions/server-side/express_nodejs/forms/create_genre_form/index.md @@ -2,10 +2,9 @@ title: Create genre form slug: Learn_web_development/Extensions/Server-side/Express_Nodejs/forms/Create_genre_form page-type: learn-module-chapter +sidebar: learnsidebar --- -{{LearnSidebar}} - This sub article shows how we define our page to create `Genre` objects (this is a good place to start because the `Genre` has only one field, its `name`, and no dependencies). Like any other pages, we need to set up routes, controllers, and views. ## Import validation and sanitization methods @@ -18,14 +17,7 @@ Open **/controllers/genreController.js**, and add the following line at the top const { body, validationResult } = require("express-validator"); ``` -> [!NOTE] -> This syntax allows us to use `body` and `validationResult` as the associated middleware functions, as you will see in the post route section below. It is equivalent to: -> -> ```js -> const validator = require("express-validator"); -> const body = validator.body; -> const validationResult = validator.validationResult; -> ``` +Note that `require("express-validator")` is just a function call that returns an object, and we [destructure](/en-US/docs/Web/JavaScript/Reference/Operators/Destructuring) the two properties, `body` and `validationResult`, from the object, so we can use them as variables directly. ## Controller—get route @@ -67,24 +59,23 @@ exports.genre_create_post = [ // There are errors. Render the form again with sanitized values/error messages. res.render("genre_form", { title: "Create Genre", - genre: genre, + genre, errors: errors.array(), }); return; + } + // Data from form is valid. + // Check if Genre with same name already exists. + const genreExists = await Genre.findOne({ name: req.body.name }) + .collation({ locale: "en", strength: 2 }) + .exec(); + if (genreExists) { + // Genre exists, redirect to its detail page. + res.redirect(genreExists.url); } else { - // Data from form is valid. - // Check if Genre with same name already exists. - const genreExists = await Genre.findOne({ name: req.body.name }) - .collation({ locale: "en", strength: 2 }) - .exec(); - if (genreExists) { - // Genre exists, redirect to its detail page. - res.redirect(genreExists.url); - } else { - await genre.save(); - // New genre saved. Redirect to genre detail page. - res.redirect(genre.url); - } + await genre.save(); + // New genre saved. Redirect to genre detail page. + res.redirect(genre.url); } }), ]; @@ -124,14 +115,13 @@ asyncHandler(async (req, res, next) => { // There are errors. Render the form again with sanitized values/error messages. res.render("genre_form", { title: "Create Genre", - genre: genre, + genre, errors: errors.array(), }); return; - } else { - // Data from form is valid. - // … } + // Data from form is valid. + // … }); ``` diff --git a/files/en-us/learn_web_development/extensions/server-side/express_nodejs/forms/delete_author_form/index.md b/files/en-us/learn_web_development/extensions/server-side/express_nodejs/forms/delete_author_form/index.md index b9c8fdbe32ece82..9b111fd462266a4 100644 --- a/files/en-us/learn_web_development/extensions/server-side/express_nodejs/forms/delete_author_form/index.md +++ b/files/en-us/learn_web_development/extensions/server-side/express_nodejs/forms/delete_author_form/index.md @@ -2,10 +2,9 @@ title: Delete Author form slug: Learn_web_development/Extensions/Server-side/Express_Nodejs/forms/Delete_author_form page-type: learn-module-chapter +sidebar: learnsidebar --- -{{LearnSidebar}} - This subarticle shows how to define a page to delete `Author` objects. As discussed in the [form design](/en-US/docs/Learn_web_development/Extensions/Server-side/Express_Nodejs/forms#form_design) section, our strategy will be to only allow deletion of objects that are not referenced by other objects (in this case that means we won't allow an `Author` to be deleted if it is referenced by a `Book`). @@ -32,7 +31,7 @@ exports.author_delete_get = asyncHandler(async (req, res, next) => { res.render("author_delete", { title: "Delete Author", - author: author, + author, author_books: allBooksByAuthor, }); }); @@ -70,15 +69,14 @@ exports.author_delete_post = asyncHandler(async (req, res, next) => { // Author has books. Render in same way as for GET route. res.render("author_delete", { title: "Delete Author", - author: author, + author, author_books: allBooksByAuthor, }); return; - } else { - // Author has no books. Delete object and redirect to the list of authors. - await Author.findByIdAndDelete(req.body.authorid); - res.redirect("/catalog/authors"); } + // Author has no books. Delete object and redirect to the list of authors. + await Author.findByIdAndDelete(req.body.authorid); + res.redirect("/catalog/authors"); }); ``` diff --git a/files/en-us/learn_web_development/extensions/server-side/express_nodejs/forms/index.md b/files/en-us/learn_web_development/extensions/server-side/express_nodejs/forms/index.md index 97757bf19224b26..762da245da2e8cb 100644 --- a/files/en-us/learn_web_development/extensions/server-side/express_nodejs/forms/index.md +++ b/files/en-us/learn_web_development/extensions/server-side/express_nodejs/forms/index.md @@ -1,10 +1,12 @@ --- title: "Express Tutorial Part 6: Working with forms" +short-title: "6: Working with forms" slug: Learn_web_development/Extensions/Server-side/Express_Nodejs/forms page-type: learn-module-chapter +sidebar: learnsidebar --- -{{LearnSidebar}}{{PreviousMenuNext("Learn_web_development/Extensions/Server-side/Express_Nodejs/Displaying_data", "Learn_web_development/Extensions/Server-side/Express_Nodejs/deployment", "Learn_web_development/Extensions/Server-side/Express_Nodejs")}} +{{PreviousMenuNext("Learn_web_development/Extensions/Server-side/Express_Nodejs/Displaying_data", "Learn_web_development/Extensions/Server-side/Express_Nodejs/deployment", "Learn_web_development/Extensions/Server-side/Express_Nodejs")}} In this tutorial we'll show you how to work with HTML Forms in Express using Pug. In particular, we'll discuss how to write forms to create, update, and delete documents from the site's database. @@ -64,7 +66,7 @@ The `submit` input will be displayed as a button (by default)—this can be pres - `method`: The HTTP method used to send the data: `POST` or `GET`. - The `POST` method should always be used if the data is going to result in a change to the server's database, because this can be made more resistant to cross-site forgery request attacks. - - The `GET` method should only be used for forms that don't change user data (e.g. a search form). It is recommended for when you want to be able to bookmark or share the URL. + - The `GET` method should only be used for forms that don't change user data (e.g., a search form). It is recommended for when you want to be able to bookmark or share the URL. ### Form handling process @@ -78,12 +80,12 @@ As shown in the diagram above, the main things that form handling code needs to 1. Display the default form the first time it is requested by the user. - - The form may contain blank fields (e.g. if you're creating a new record), or it may be pre-populated with initial values (e.g. if you are changing a record, or have useful default initial values). + - The form may contain blank fields (e.g., if you're creating a new record), or it may be pre-populated with initial values (e.g., if you are changing a record, or have useful default initial values). 2. Receive data submitted by the user, usually in an HTTP `POST` request. 3. Validate and sanitize the data. 4. If any data is invalid, re-display the form—this time with any user populated values and error messages for the problem fields. -5. If all data is valid, perform required actions (e.g. save the data in the database, send a notification email, return the result of a search, upload a file, etc.) +5. If all data is valid, perform required actions (e.g., save the data in the database, send a notification email, return the result of a search, upload a file, etc.) 6. Once all actions are complete, redirect the user to another page. Often form handling code is implemented using a `GET` route for the initial display of the form and a `POST` route to the same path for handling validation and processing of form data. This is the approach that will be used in this tutorial. diff --git a/files/en-us/learn_web_development/extensions/server-side/express_nodejs/forms/update_book_form/index.md b/files/en-us/learn_web_development/extensions/server-side/express_nodejs/forms/update_book_form/index.md index 8640d832b888e69..578f38e451bcc97 100644 --- a/files/en-us/learn_web_development/extensions/server-side/express_nodejs/forms/update_book_form/index.md +++ b/files/en-us/learn_web_development/extensions/server-side/express_nodejs/forms/update_book_form/index.md @@ -2,10 +2,9 @@ title: Update Book form slug: Learn_web_development/Extensions/Server-side/Express_Nodejs/forms/Update_Book_form page-type: learn-module-chapter +sidebar: learnsidebar --- -{{LearnSidebar}} - This final subarticle shows how to define a page to update `Book` objects. Form handling when updating a book is much like that for creating a book, except that you must populate the form in the `GET` route with values from the database. ## Controller—get route @@ -38,7 +37,7 @@ exports.book_update_get = asyncHandler(async (req, res, next) => { title: "Update Book", authors: allAuthors, genres: allGenres, - book: book, + book, }); }); ``` @@ -119,16 +118,15 @@ exports.book_update_post = [ title: "Update Book", authors: allAuthors, genres: allGenres, - book: book, + book, errors: errors.array(), }); return; - } else { - // Data from form is valid. Update the record. - const updatedBook = await Book.findByIdAndUpdate(req.params.id, book, {}); - // Redirect to book detail page. - res.redirect(updatedBook.url); } + // Data from form is valid. Update the record. + const updatedBook = await Book.findByIdAndUpdate(req.params.id, book, {}); + // Redirect to book detail page. + res.redirect(updatedBook.url); }), ]; ``` diff --git a/files/en-us/learn_web_development/extensions/server-side/express_nodejs/index.md b/files/en-us/learn_web_development/extensions/server-side/express_nodejs/index.md index bcd686136ceb037..e7da267fe99ee60 100644 --- a/files/en-us/learn_web_development/extensions/server-side/express_nodejs/index.md +++ b/files/en-us/learn_web_development/extensions/server-side/express_nodejs/index.md @@ -2,14 +2,17 @@ title: Express web framework (Node.js/JavaScript) slug: Learn_web_development/Extensions/Server-side/Express_Nodejs page-type: learn-module +sidebar: learnsidebar --- -{{LearnSidebar}} - -{{NextMenu("Learn_web_development/Extensions/Server-side/Express_Nodejs/Introduction", "Learn_web_development/Extensions/Server-side/Express_Nodejs")}} +{{NextMenu("Learn_web_development/Extensions/Server-side/Express_Nodejs/Introduction", "Learn_web_development/Extensions/Server-side")}} Express is a popular unopinionated web framework, written in JavaScript and hosted within the Node.js runtime environment. This module explains some of the key benefits of the framework, how to set up your development environment and how to perform common web development and deployment tasks. +> [!WARNING] +> The Express documentation and tutorial are written for Express version 4, while the latest version is Express 5. +> We plan to update the documentation in the second half of 2025. + ## Prerequisites Before starting this module you will need to understand what server-side web programming and web frameworks are, ideally by reading the topics in our [Server-side website programming first steps](/en-US/docs/Learn_web_development/Extensions/Server-side/First_steps) module. A general knowledge of programming concepts and [JavaScript](/en-US/docs/Web/JavaScript) is highly recommended, but not essential to understanding the core concepts. @@ -52,4 +55,4 @@ All existing tutorials are listed above, but if you would like to extend this mo An assessment for the module would also make a wonderful addition! -{{NextMenu("Learn_web_development/Extensions/Server-side/Express_Nodejs/Introduction", "Learn_web_development/Extensions/Server-side/Express_Nodejs")}} +{{NextMenu("Learn_web_development/Extensions/Server-side/Express_Nodejs/Introduction", "Learn_web_development/Extensions/Server-side")}} diff --git a/files/en-us/learn_web_development/extensions/server-side/express_nodejs/introduction/index.md b/files/en-us/learn_web_development/extensions/server-side/express_nodejs/introduction/index.md index d72175f90711af5..bfcffe4ecbeeb3d 100644 --- a/files/en-us/learn_web_development/extensions/server-side/express_nodejs/introduction/index.md +++ b/files/en-us/learn_web_development/extensions/server-side/express_nodejs/introduction/index.md @@ -2,12 +2,17 @@ title: Express/Node introduction slug: Learn_web_development/Extensions/Server-side/Express_Nodejs/Introduction page-type: learn-module-chapter +sidebar: learnsidebar --- -{{LearnSidebar}}{{NextMenu("Learn_web_development/Extensions/Server-side/Express_Nodejs/development_environment", "Learn_web_development/Extensions/Server-side/Express_Nodejs")}} +{{NextMenu("Learn_web_development/Extensions/Server-side/Express_Nodejs/development_environment", "Learn_web_development/Extensions/Server-side/Express_Nodejs")}} In this first Express article we answer the questions "What is Node?" and "What is Express?", and give you an overview of what makes the Express web framework special. We'll outline the main features, and show you some of the main building blocks of an Express application (although at this point you won't yet have a development environment in which to test it). +> [!WARNING] +> The Express tutorial is written for Express version 4, while the latest version is Express 5. +> We plan to update the documentation in the second half of 2025. + <table> <tbody> <tr> @@ -28,13 +33,13 @@ In this first Express article we answer the questions "What is Node?" and "What ## Introducing Node [Node](https://nodejs.org/) (or more formally _Node.js_) is an open-source, cross-platform runtime environment that allows developers to create all kinds of server-side tools and applications in [JavaScript](/en-US/docs/Glossary/JavaScript). -The runtime is intended for use outside of a browser context (i.e. running directly on a computer or server OS). As such, the environment omits browser-specific JavaScript APIs and adds support for more traditional OS APIs including HTTP and file system libraries. +The runtime is intended for use outside of a browser context (i.e., running directly on a computer or server OS). As such, the environment omits browser-specific JavaScript APIs and adds support for more traditional OS APIs including HTTP and file system libraries. From a web server development perspective Node has a number of benefits: -- Great performance! Node was designed to optimize throughput and scalability in web applications and is a good solution for many common web-development problems (e.g. real-time web applications). +- Great performance! Node was designed to optimize throughput and scalability in web applications and is a good solution for many common web-development problems (e.g., real-time web applications). - Code is written in "plain old JavaScript", which means that less time is spent dealing with "context shift" between languages when you're writing both client-side and server-side code. -- JavaScript is a relatively new programming language and benefits from improvements in language design when compared to other traditional web-server languages (e.g. Python, PHP, etc.) Many other new and popular languages compile/convert into JavaScript so you can also use TypeScript, CoffeeScript, ClojureScript, Scala, LiveScript, etc. +- JavaScript is a relatively new programming language and benefits from improvements in language design when compared to other traditional web-server languages (e.g., Python, PHP, etc.) Many other new and popular languages compile/convert into JavaScript so you can also use TypeScript, CoffeeScript, ClojureScript, Scala, LiveScript, etc. - The node package manager (npm) provides access to hundreds of thousands of reusable packages. It also has best-in-class dependency resolution and can also be used to automate most of the build toolchain. - Node.js is portable. It is available on Microsoft Windows, macOS, Linux, Solaris, FreeBSD, OpenBSD, WebOS, and NonStop OS. Furthermore, it is well-supported by many web hosting providers, that often provide specific infrastructure and documentation for hosting Node sites. - It has a very active third party ecosystem and developer community, with lots of people who are willing to help. @@ -62,7 +67,7 @@ The following example creates a web server that listens for any kind of HTTP req const port = 8000; // Create HTTP server - const server = http.createServer(function (req, res) { + const server = http.createServer((req, res) => { // Set the response HTTP header with HTTP status and Content type res.writeHead(200, { "Content-Type": "text/plain" }); @@ -71,7 +76,7 @@ The following example creates a web server that listens for any kind of HTTP req }); // Prints a log once the server starts listening - server.listen(port, hostname, function () { + server.listen(port, hostname, () => { console.log(`Server running at http://${hostname}:${port}/`); }); ``` @@ -85,9 +90,12 @@ The following example creates a web server that listens for any kind of HTTP req Finally, navigate to `http://localhost:8000` in your web browser; you should see the text "**Hello World**" in the upper left of an otherwise empty web page. +> [!NOTE] +> If you want to play with some Node.js code without having to do any local setup, Scrimba's [Aside: The HTTP module](https://scrimba.com/learn-nodejs-c00ho9qqh6/~07du?via=mdn) <sup>[_MDN learning partner_](/en-US/docs/MDN/Writing_guidelines/Learning_content#partner_links_and_embeds)</sup> provides an interactive walkthrough of setting up a basic server with the Node HTTP package. + ## Web Frameworks -Other common web-development tasks are not directly supported by Node itself. If you want to add specific handling for different HTTP verbs (e.g. `GET`, `POST`, `DELETE`, etc.), separately handle requests at different URL paths ("routes"), serve static files, or use templates to dynamically create the response, Node won't be of much use on its own. You will either need to write the code yourself, or you can avoid reinventing the wheel and use a web framework! +Other common web-development tasks are not directly supported by Node itself. If you want to add specific handling for different HTTP verbs (e.g., `GET`, `POST`, `DELETE`, etc.), separately handle requests at different URL paths ("routes"), serve static files, or use templates to dynamically create the response, Node won't be of much use on its own. You will either need to write the code yourself, or you can avoid reinventing the wheel and use a web framework! ## Introducing Express @@ -107,7 +115,7 @@ While _Express_ itself is fairly minimalist, developers have created compatible Node was initially released, for Linux only, in 2009. The npm package manager was released in 2010, and native Windows support was added in 2012. Delve into [Wikipedia](https://en.wikipedia.org/wiki/Node.js#History) if you want to know more. -Express was initially released in November 2010 and is currently on major version 4 of the API. You can check out the [changelog](https://expressjs.com/en/changelog/4x.html) for information about changes in the current release, and [GitHub](https://github.com/expressjs/express/blob/master/History.md) for more detailed historical release notes. +Express was initially released in November 2010 and is currently on major version 5 of the API. You can check out the [changelog](https://expressjs.com/en/changelog/#5.x) for information about changes in the current release, and [GitHub](https://github.com/expressjs/express/blob/master/History.md) for more detailed historical release notes. ## How popular are Node and Express? @@ -146,19 +154,20 @@ First lets consider the standard Express [Hello World](https://expressjs.com/en/ ```js const express = require("express"); + const app = express(); const port = 3000; -app.get("/", function (req, res) { +app.get("/", (req, res) => { res.send("Hello World!"); }); -app.listen(port, function () { +app.listen(port, () => { console.log(`Example app listening on port ${port}!`); }); ``` -The first two lines `require()` (import) the express module and create an [Express application](https://expressjs.com/en/4x/api.html#app). This object, which is traditionally named `app`, has methods for routing HTTP requests, configuring middleware, rendering HTML views, registering a template engine, and modifying [application settings](https://expressjs.com/en/4x/api.html#app.settings.table) that control how the application behaves (e.g. the environment mode, whether route definitions are case sensitive, etc.) +The first two lines `require()` (import) the express module and create an [Express application](https://expressjs.com/en/4x/api.html#app). This object, which is traditionally named `app`, has methods for routing HTTP requests, configuring middleware, rendering HTML views, registering a template engine, and modifying [application settings](https://expressjs.com/en/4x/api.html#app.settings.table) that control how the application behaves (e.g., the environment mode, whether route definitions are case sensitive, etc.) The middle part of the code (the three lines starting with `app.get`) shows a _route definition_. The `app.get()` method specifies a callback function that will be invoked whenever there is an HTTP `GET` request with a path (`'/'`) relative to the site root. The callback function takes a request and a response object as arguments, and calls [`send()`](https://expressjs.com/en/4x/api.html#res.send) on the response to return the string "Hello World!" @@ -172,6 +181,7 @@ The code below shows how we import a module by name, using the _Express_ framewo ```js const express = require("express"); + const app = express(); ``` @@ -195,6 +205,7 @@ We can import this module using `require()`, and then call the exported method(s ```js const square = require("./square"); // Here we require() the name of the file without the (optional) .js file extension + console.log(`The area of a square with a width of 4 is ${square.area(4)}`); ``` @@ -232,7 +243,7 @@ console.log("Second"); By contrast, an asynchronous API is one in which the API will start an operation and immediately return (before the operation is complete). Once the operation finishes, the API will use some mechanism to perform additional operations. For example, the code below will print out "Second, First" because even though `setTimeout()` method is called first, and returns immediately, the operation doesn't complete for several seconds. ```js -setTimeout(function () { +setTimeout(() => { console.log("First"); }, 3000); console.log("Second"); @@ -253,7 +264,7 @@ There are a number of ways for an asynchronous API to notify your application th In our _Hello World_ Express example (see above), we defined a (callback) route handler function for HTTP `GET` requests to the site root (`'/'`). ```js -app.get("/", function (req, res) { +app.get("/", (req, res) => { res.send("Hello World!"); }); ``` @@ -270,7 +281,7 @@ The _Express application_ object also provides methods to define route handlers There is a special routing method, `app.all()`, which will be called in response to any HTTP method. This is used for loading middleware functions at a particular path for all request methods. The following example (from the Express documentation) shows a handler that will be executed for requests to `/secret` irrespective of the HTTP verb used (provided it is supported by the [http module](https://nodejs.org/docs/latest/api/http.html#httpmethods)). ```js -app.all("/secret", function (req, res, next) { +app.all("/secret", (req, res, next) => { console.log("Accessing the secret section…"); next(); // pass control to the next handler }); @@ -278,21 +289,22 @@ app.all("/secret", function (req, res, next) { Routes allow you to match particular patterns of characters in a URL, and extract some values from the URL and pass them as parameters to the route handler (as attributes of the request object passed as a parameter). -Often it is useful to group route handlers for a particular part of a site together and access them using a common route-prefix (e.g. a site with a Wiki might have all wiki-related routes in one file and have them accessed with a route prefix of _/wiki/_). In _Express_ this is achieved by using the [`express.Router`](https://expressjs.com/en/guide/routing.html#express-router) object. For example, we can create our wiki route in a module named **wiki.js**, and then export the `Router` object, as shown below: +Often it is useful to group route handlers for a particular part of a site together and access them using a common route-prefix (e.g., a site with a Wiki might have all wiki-related routes in one file and have them accessed with a route prefix of _/wiki/_). In _Express_ this is achieved by using the [`express.Router`](https://expressjs.com/en/guide/routing.html#express-router) object. For example, we can create our wiki route in a module named **wiki.js**, and then export the `Router` object, as shown below: ```js // wiki.js - Wiki route module const express = require("express"); + const router = express.Router(); // Home page route -router.get("/", function (req, res) { +router.get("/", (req, res) => { res.send("Wiki home page"); }); // About page route -router.get("/about", function (req, res) { +router.get("/about", (req, res) => { res.send("About this wiki"); }); @@ -306,6 +318,7 @@ To use the router in our main app file we would then `require()` the route modul ```js const wiki = require("./wiki.js"); + // … app.use("/wiki", wiki); ``` @@ -333,6 +346,7 @@ You could then call `use()` on the _Express application object_ to add the middl ```js const express = require("express"); const logger = require("morgan"); + const app = express(); app.use(logger("dev")); // … @@ -349,22 +363,23 @@ The example below shows how you can add the middleware function using both appro ```js const express = require("express"); + const app = express(); // An example middleware function -const a_middleware_function = function (req, res, next) { +function aMiddlewareFunction(req, res, next) { // Perform some operations next(); // Call next() so Express will call the next middleware function in the chain. -}; +} // Function added with use() for all routes and verbs -app.use(a_middleware_function); +app.use(aMiddlewareFunction); // Function added with use() for a specific route -app.use("/some-route", a_middleware_function); +app.use("/some-route", aMiddlewareFunction); // A middleware function added for a specific HTTP verb and route -app.get("/", a_middleware_function); +app.get("/", aMiddlewareFunction); app.listen(3000); ``` @@ -420,7 +435,7 @@ http://localhost:3000/media/cry.mp3 Errors are handled by one or more special middleware functions that have four arguments, instead of the usual three: `(err, req, res, next)`. For example: ```js -app.use(function (err, req, res, next) { +app.use((err, req, res, next) => { console.error(err.stack); res.status(500).send("Something broke!"); }); @@ -453,7 +468,7 @@ The database itself can be installed locally or on a cloud server. In your Expre This works with older versions of MongoDB version ~ 2.2.33: ```js -const MongoClient = require("mongodb").MongoClient; +const { MongoClient } = require("mongodb"); MongoClient.connect("mongodb://localhost:27017/animals", (err, db) => { if (err) throw err; @@ -471,7 +486,7 @@ MongoClient.connect("mongodb://localhost:27017/animals", (err, db) => { For MongoDB version 3.0 and up: ```js -const MongoClient = require("mongodb").MongoClient; +const { MongoClient } = require("mongodb"); MongoClient.connect("mongodb://localhost:27017/animals", (err, client) => { if (err) throw err; @@ -503,6 +518,7 @@ In your application settings code you set the template engine to use and the loc ```js const express = require("express"); const path = require("path"); + const app = express(); // Set directory to contain the templates ('views') @@ -515,7 +531,7 @@ app.set("view engine", "some_template_engine_name"); The appearance of the template will depend on what engine you use. Assuming that you have a template file named "index.\<template_extension>" that contains placeholders for data variables named 'title' and "message", you would call [`Response.render()`](https://expressjs.com/en/4x/api.html#res.render) in a route handler function to create and send the HTML response: ```js -app.get("/", function (req, res) { +app.get("/", (req, res) => { res.render("index", { title: "About dogs", message: "Dogs rock!" }); }); ``` @@ -524,7 +540,7 @@ For more information see [Using template engines with Express](https://expressjs ### File structure -Express makes no assumptions in terms of structure or what components you use. Routes, views, static files, and other application-specific logic can live in any number of files with any directory structure. While it is perfectly possible to have the whole _Express_ application in one file, typically it makes sense to split your application into files based on function (e.g. account management, blogs, discussion boards) and architectural problem domain (e.g. model, view or controller if you happen to be using an [MVC architecture](/en-US/docs/Glossary/MVC)). +Express makes no assumptions in terms of structure or what components you use. Routes, views, static files, and other application-specific logic can live in any number of files with any directory structure. While it is perfectly possible to have the whole _Express_ application in one file, typically it makes sense to split your application into files based on function (e.g., account management, blogs, discussion boards) and architectural problem domain (e.g., model, view or controller if you happen to be using an [MVC architecture](/en-US/docs/Glossary/MVC)). In a later topic we'll use the _Express Application Generator_, which creates a modular app skeleton that we can easily extend for creating web applications. @@ -536,6 +552,8 @@ Of course Express is deliberately a very lightweight web application framework, ## See also +- [Learn Node.js](https://scrimba.com/learn-nodejs-c00ho9qqh6?via=mdn) from Scrimba <sup>[_MDN learning partner_](/en-US/docs/MDN/Writing_guidelines/Learning_content#partner_links_and_embeds)</sup> provides a fun, interactive introduction to Node.js. +- [Learn Express.js](https://scrimba.com/learn-expressjs-c062las154?via=mdn) from Scrimba <sup>[_MDN learning partner_](/en-US/docs/MDN/Writing_guidelines/Learning_content#partner_links_and_embeds)</sup> builds on top of the previous link, showing how to start using the Express framework to build server-side websites. - [Modules](https://nodejs.org/api/modules.html#modules_modules) (Node API docs) - [Express](https://expressjs.com/) (home page) - [Basic routing](https://expressjs.com/en/starter/basic-routing.html) (Express docs) diff --git a/files/en-us/learn_web_development/extensions/server-side/express_nodejs/mongoose/index.md b/files/en-us/learn_web_development/extensions/server-side/express_nodejs/mongoose/index.md index d82d55e9ff53581..728d13c3a9571ff 100644 --- a/files/en-us/learn_web_development/extensions/server-side/express_nodejs/mongoose/index.md +++ b/files/en-us/learn_web_development/extensions/server-side/express_nodejs/mongoose/index.md @@ -1,10 +1,12 @@ --- title: "Express Tutorial Part 3: Using a Database (with Mongoose)" +short-title: "3: Using databases with Mongoose" slug: Learn_web_development/Extensions/Server-side/Express_Nodejs/mongoose page-type: learn-module-chapter +sidebar: learnsidebar --- -{{LearnSidebar}}{{PreviousMenuNext("Learn_web_development/Extensions/Server-side/Express_Nodejs/skeleton_website", "Learn_web_development/Extensions/Server-side/Express_Nodejs/routes", "Learn_web_development/Extensions/Server-side/Express_Nodejs")}} +{{PreviousMenuNext("Learn_web_development/Extensions/Server-side/Express_Nodejs/skeleton_website", "Learn_web_development/Extensions/Server-side/Express_Nodejs/routes", "Learn_web_development/Extensions/Server-side/Express_Nodejs")}} This article briefly introduces databases, and how to use them with Node/Express apps. It then goes on to show how we can use [Mongoose](https://mongoosejs.com/) to provide database access for the [LocalLibrary](/en-US/docs/Learn_web_development/Extensions/Server-side/Express_Nodejs/Tutorial_local_library_website) website. It explains how object schema and models are declared, the main field types, and basic validation. It also briefly shows a few of the main ways in which you can access model data. @@ -86,7 +88,7 @@ We know that we need to store information about books (title, summary, author, g When designing your models it makes sense to have separate models for every "object" (a group of related information). In this case some obvious candidates for these models are books, book instances, and authors. -You might also want to use models to represent selection-list options (e.g. like a drop-down list of choices), rather than hard-coding the choices into the website itself — this is recommended when all the options aren't known up front or may change. A good example is a genre (e.g. fantasy, science fiction, etc.). +You might also want to use models to represent selection-list options (e.g., like a drop-down list of choices), rather than hard-coding the choices into the website itself — this is recommended when all the options aren't known up front or may change. A good example is a genre (e.g., fantasy, science fiction, etc.). Once we've decided on our models and fields, we need to think about the relationships between them. @@ -129,20 +131,20 @@ When `myFunction()` is run, code execution is paused at `methodThatReturnsPromis The code in the `catch` block runs if an error is thrown in the asynchronous function, and this will happen if the promise returned by either of the methods is rejected. ```js -async function myFunction { - // ... +async function myFunction() { + // … await someObject.methodThatReturnsPromise(); - // ... + // … await aFunctionThatReturnsPromise(); - // ... + // … } try { - // ... + // … myFunction(); - // ... + // … } catch (e) { - // error handling code + // error handling code } ``` @@ -160,13 +162,13 @@ the function then continues to the next `await`, and waits until the promise ret You would call the `myFunction()` in a `try...catch` block to catch any errors. ```js -async function myFunction { - // ... +async function myFunction() { + // … const [resultFunction1, resultFunction2] = await Promise.all([ - functionThatReturnsPromise1(), - functionThatReturnsPromise2() + functionThatReturnsPromise1(), + functionThatReturnsPromise2(), ]); - // ... + // … await anotherFunctionThatReturnsPromise(resultFunction1); } ``` @@ -305,13 +307,13 @@ Most of the [SchemaTypes](https://mongoosejs.com/docs/schematypes.html) (the des The code also shows both ways of declaring a field: -- Field _name_ and _type_ as a key-value pair (i.e. as done with fields `name`, `binary` and `living`). +- Field _name_ and _type_ as a key-value pair (i.e., as done with fields `name`, `binary` and `living`). - Field _name_ followed by an object defining the `type`, and any other _options_ for the field. Options include things like: - default values. - - built-in validators (e.g. max/min values) and custom validation functions. + - built-in validators (e.g., max/min values) and custom validation functions. - Whether the field is required - - Whether `String` fields should automatically be set to lowercase, uppercase, or trimmed (e.g. `{ type: String, lowercase: true, trim: true }`) + - Whether `String` fields should automatically be set to lowercase, uppercase, or trimmed (e.g., `{ type: String, lowercase: true, trim: true }`) For more information about options see [SchemaTypes](https://mongoosejs.com/docs/schematypes.html) (Mongoose docs). @@ -369,7 +371,7 @@ We provide a brief overview below. For more information see: [Models](https://mo > [!NOTE] > Creation, update, deletion and querying of records are asynchronous operations that return a [promise](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise). -> The examples below show just the use of the relevant methods and `await` (i.e. the essential code for using the methods). +> The examples below show just the use of the relevant methods and `await` (i.e., the essential code for using the methods). > The surrounding `async function` and `try...catch` block to catch errors are omitted for clarity. > For more information on using `await/async` see [Database APIs are asynchronous](#database_apis_are_asynchronous) above. @@ -399,7 +401,7 @@ You can access the fields in this new record using the dot syntax, and change th ```js // Access model field values using dot notation -console.log(awesome_instance.name); //should log 'also_awesome' +console.log(awesome_instance.name); // should log 'also_awesome' // Change record by modifying the fields, then calling save(). awesome_instance.name = "New cool name"; @@ -582,7 +584,7 @@ For this tutorial, we're going to use the [MongoDB Atlas](https://www.mongodb.co > [!NOTE] > If you prefer, you can set up a MongoDB database locally by downloading and installing the [appropriate binaries for your system](https://www.mongodb.com/try/download/community-edition/releases). The rest of the instructions in this article would be similar, except for the database URL you would specify when connecting. -> In the [Express Tutorial Part 7: Deploying to Production](/en-US/docs/Learn_web_development/Extensions/Server-side/Express_Nodejs/deployment) tutorial we host both the application and database on [Railway](https://railway.app/), but we could equally well have used a database on [MongoDB Atlas](https://www.mongodb.com/products/platform/atlas-database). +> In the [Express Tutorial Part 7: Deploying to Production](/en-US/docs/Learn_web_development/Extensions/Server-side/Express_Nodejs/deployment) tutorial we host both the application and database on [Railway](https://railway.com/), but we could equally well have used a database on [MongoDB Atlas](https://www.mongodb.com/products/platform/atlas-database). You will first need to [create an account](https://www.mongodb.com/cloud/atlas/register) with MongoDB Atlas (this is free, and just requires that you enter basic contact details and acknowledge their terms of service). @@ -680,11 +682,12 @@ npm install mongoose ## Connect to MongoDB Open **/app.js** (in the root of your project) and copy the following text below where you declare the _Express application object_ (after the line `const app = express();`). -Replace the database URL string ('_insert_your_database_url_here_') with the location URL representing your own database (i.e. using the information from _MongoDB Atlas_). +Replace the database URL string ('_insert_your_database_url_here_') with the location URL representing your own database (i.e., using the information from _MongoDB Atlas_). ```js // Set up mongoose connection const mongoose = require("mongoose"); + mongoose.set("strictQuery", false); const mongoDB = "insert_your_database_url_here"; @@ -706,7 +709,7 @@ We will define a separate module for each model, as [discussed above](#one_schem Start by creating a folder for our models in the project root (**/models**) and then create separate files for each of the models: ```plain -/express-locallibrary-tutorial // the project root +/express-locallibrary-tutorial # the project root /models author.js book.js @@ -836,7 +839,7 @@ Everything else should be familiar from our previous schema. ### Genre model - challenge -Open your **./models/genre.js** file and create a schema for storing genres (the category of book, e.g. whether it is fiction or non-fiction, romance or military history, etc.). +Open your **./models/genre.js** file and create a schema for storing genres (the category of book, e.g., whether it is fiction or non-fiction, romance or military history, etc.). The definition will be very similar to the other models: diff --git a/files/en-us/learn_web_development/extensions/server-side/express_nodejs/routes/index.md b/files/en-us/learn_web_development/extensions/server-side/express_nodejs/routes/index.md index 11f2578d5ea8f3c..b5581027c070842 100644 --- a/files/en-us/learn_web_development/extensions/server-side/express_nodejs/routes/index.md +++ b/files/en-us/learn_web_development/extensions/server-side/express_nodejs/routes/index.md @@ -1,10 +1,12 @@ --- title: "Express Tutorial Part 4: Routes and controllers" +short-title: "4: Routes and controllers" slug: Learn_web_development/Extensions/Server-side/Express_Nodejs/routes page-type: learn-module-chapter +sidebar: learnsidebar --- -{{LearnSidebar}}{{PreviousMenuNext("Learn_web_development/Extensions/Server-side/Express_Nodejs/mongoose", "Learn_web_development/Extensions/Server-side/Express_Nodejs/Displaying_data", "Learn_web_development/Extensions/Server-side/Express_Nodejs")}} +{{PreviousMenuNext("Learn_web_development/Extensions/Server-side/Express_Nodejs/mongoose", "Learn_web_development/Extensions/Server-side/Express_Nodejs/Displaying_data", "Learn_web_development/Extensions/Server-side/Express_Nodejs")}} In this tutorial we'll set up routes (URL handling code) with "dummy" handler functions for all the resource endpoints that we'll eventually need in the [LocalLibrary](/en-US/docs/Learn_web_development/Extensions/Server-side/Express_Nodejs/Tutorial_local_library_website) website. On completion we'll have a modular structure for our route handling code, which we can extend with real handler functions in the following articles. We'll also have a really good understanding of how to create modular routes using Express! @@ -66,15 +68,16 @@ First we create routes for a wiki in a module named **wiki.js**. The code first // wiki.js - Wiki route module. const express = require("express"); + const router = express.Router(); // Home page route. -router.get("/", function (req, res) { +router.get("/", (req, res) => { res.send("Wiki home page"); }); // About page route. -router.get("/about", function (req, res) { +router.get("/about", (req, res) => { res.send("About this wiki"); }); @@ -88,6 +91,7 @@ To use the router module in our main app file we first `require()` the route mod ```js const wiki = require("./wiki.js"); + // … app.use("/wiki", wiki); ``` @@ -99,7 +103,7 @@ The two routes defined in our wiki route module are then accessible from `/wiki/ Our module above defines a couple of typical route functions. The "about" route (reproduced below) is defined using the `Router.get()` method, which responds only to HTTP GET requests. The first argument to this method is the URL path while the second is a callback function that will be invoked if an HTTP GET request with the path is received. ```js -router.get("/about", function (req, res) { +router.get("/about", (req, res) => { res.send("About this wiki"); }); ``` @@ -133,15 +137,15 @@ The route paths define the endpoints at which requests can be made. The examples Route paths can also be string patterns. String patterns use a form of regular expression syntax to define _patterns_ of endpoints that will be matched. The syntax is listed below (note that the hyphen (`-`) and the dot (`.`) are interpreted literally by string-based paths): -- `?` : The endpoint must have 0 or 1 of the preceding character (or group), e.g. a route path of `'/ab?cd'` will match endpoints `acd` or `abcd`. -- `+` : The endpoint must have 1 or more of the preceding character (or group), e.g. a route path of `'/ab+cd'` will match endpoints `abcd`, `abbcd`, `abbbcd`, and so on. +- `?` : The endpoint must have 0 or 1 of the preceding character (or group), e.g., a route path of `'/ab?cd'` will match endpoints `acd` or `abcd`. +- `+` : The endpoint must have 1 or more of the preceding character (or group), e.g., a route path of `'/ab+cd'` will match endpoints `abcd`, `abbcd`, `abbbcd`, and so on. - `*` : The endpoint may have an arbitrary string where the `*` character is placed. E.g. a route path of `'/ab*cd'` will match endpoints `abcd`, `abXcd`, `abSOMErandomTEXTcd`, and so on. -- `()` : Grouping match on a set of characters to perform another operation on, e.g. `'/ab(cd)?e'` will perform a `?`-match on the group `(cd)` — it will match `abe` and `abcde`. +- `()` : Grouping match on a set of characters to perform another operation on, e.g., `'/ab(cd)?e'` will perform a `?`-match on the group `(cd)` — it will match `abe` and `abcde`. The route paths can also be JavaScript [regular expressions](/en-US/docs/Web/JavaScript/Guide/Regular_expressions). For example, the route path below will match `catfish` and `dogfish`, but not `catflap`, `catfishhead`, and so on. Note that the path for a regular expression uses regular expression syntax (it is not a quoted string as in the previous cases). ```js -app.get(/.*fish$/, function (req, res) { +app.get(/.*fish$/, (req, res) => { // … }); ``` @@ -185,7 +189,7 @@ router.get("/about", (req, res, next) => { if (err) { return next(err); } - //Successful, so render + // Successful, so render res.render("about_view", { title: "About", list: queryResults }); }); }); @@ -205,7 +209,7 @@ In order for the framework to properly handle exceptions, they must be caught, a Re-imagining the simple example from the previous section with `About.find().exec()` as a database query that returns a promise, we might write the route function inside a [`try...catch`](/en-US/docs/Web/JavaScript/Reference/Statements/try...catch) block like this: ```js -exports.get("/about", async function (req, res, next) { +exports.get("/about", async (req, res, next) => { try { const successfulResult = await About.find({}).exec(); res.render("about_view", { title: "About", list: successfulResult }); @@ -238,18 +242,18 @@ exports.get( The URLs that we're ultimately going to need for our pages are listed below, where _object_ is replaced by the name of each of our models (book, bookinstance, genre, author), _objects_ is the plural of object, and _id_ is the unique instance field (`_id`) that is given to each Mongoose model instance by default. - `catalog/` — The home/index page. -- `catalog/<objects>/` — The list of all books, bookinstances, genres, or authors (e.g. /`catalog/books/`, /`catalog/genres/`, etc.) -- `catalog/<object>/<id>` — The detail page for a specific book, bookinstance, genre, or author with the given `_id` field value (e.g. `/catalog/book/584493c1f4887f06c0e67d37)`. -- `catalog/<object>/create` — The form to create a new book, bookinstance, genre, or author (e.g. `/catalog/book/create)`. -- `catalog/<object>/<id>/update` — The form to update a specific book, bookinstance, genre, or author with the given `_id` field value (e.g. `/catalog/book/584493c1f4887f06c0e67d37/update)`. -- `catalog/<object>/<id>/delete` — The form to delete a specific book, bookinstance, genre, or author with the given `_id` field value (e.g. `/catalog/book/584493c1f4887f06c0e67d37/delete)`. +- `catalog/<objects>/` — The list of all books, bookinstances, genres, or authors (e.g., /`catalog/books/`, /`catalog/genres/`, etc.) +- `catalog/<object>/<id>` — The detail page for a specific book, bookinstance, genre, or author with the given `_id` field value (e.g., `/catalog/book/584493c1f4887f06c0e67d37)`. +- `catalog/<object>/create` — The form to create a new book, bookinstance, genre, or author (e.g., `/catalog/book/create)`. +- `catalog/<object>/<id>/update` — The form to update a specific book, bookinstance, genre, or author with the given `_id` field value (e.g., `/catalog/book/584493c1f4887f06c0e67d37/update)`. +- `catalog/<object>/<id>/delete` — The form to delete a specific book, bookinstance, genre, or author with the given `_id` field value (e.g., `/catalog/book/584493c1f4887f06c0e67d37/delete)`. The first home page and list pages don't encode any additional information. While the results returned will depend on the model type and the content in the database, the queries run to get the information will always be the same (similarly the code run for object creation will always be similar). -By contrast the other URLs are used to act on a specific document/model instance—these encode the identity of the item in the URL (shown as `<id>` above). We'll use path parameters to extract the encoded information and pass it to the route handler (and in a later article we'll use this to dynamically determine what information to get from the database). By encoding the information in our URL we only need one route for every resource of a particular type (e.g. one route to handle the display of every single book item). +By contrast the other URLs are used to act on a specific document/model instance—these encode the identity of the item in the URL (shown as `<id>` above). We'll use path parameters to extract the encoded information and pass it to the route handler (and in a later article we'll use this to dynamically determine what information to get from the database). By encoding the information in our URL we only need one route for every resource of a particular type (e.g., one route to handle the display of every single book item). > [!NOTE] -> Express allows you to construct your URLs any way you like — you can encode information in the body of the URL as shown above or use URL `GET` parameters (e.g. `/book/?id=6`). Whichever approach you use, the URLs should be kept clean, logical and readable ([check out the W3C advice here](https://www.w3.org/Provider/Style/URI)). +> Express allows you to construct your URLs any way you like — you can encode information in the body of the URL as shown above or use URL `GET` parameters (e.g., `/book/?id=6`). Whichever approach you use, the URLs should be kept clean, logical and readable ([check out the W3C advice here](https://www.w3.org/Provider/Style/URI)). Next we create our route handler callback functions and route code for all the above URLs. @@ -260,7 +264,7 @@ Before we define our routes, we'll first create all the dummy/skeleton callback Start by creating a folder for our controllers in the project root (**/controllers**) and then create separate controller files/modules for handling each of the models: ```plain -/express-locallibrary-tutorial //the project root +/express-locallibrary-tutorial # the project root /controllers authorController.js bookController.js @@ -494,7 +498,7 @@ The skeleton already has a **./routes** folder containing routes for the _index_ Create another route file — **catalog.js** — inside this folder, as shown. ```plain -/express-locallibrary-tutorial //the project root +/express-locallibrary-tutorial # the project root /routes index.js users.js @@ -505,7 +509,6 @@ Open **/routes/catalog.js** and copy in the code below: ```js const express = require("express"); -const router = express.Router(); // Require controller modules. const book_controller = require("../controllers/bookController"); @@ -513,6 +516,8 @@ const author_controller = require("../controllers/authorController"); const genre_controller = require("../controllers/genreController"); const book_instance_controller = require("../controllers/bookinstanceController"); +const router = express.Router(); + /// BOOK ROUTES /// // GET catalog home page. @@ -573,7 +578,7 @@ router.get("/authors", author_controller.author_list); // GET request for creating a Genre. NOTE This must come before route that displays Genre (uses id). router.get("/genre/create", genre_controller.genre_create_get); -//POST request for creating Genre. +// POST request for creating Genre. router.post("/genre/create", genre_controller.genre_create_post); // GET request to delete Genre. @@ -644,7 +649,7 @@ module.exports = router; The module requires Express and then uses it to create a `Router` object. The routes are all set up on the router, which is then exported. The routes are defined either using `.get()` or `.post()` methods on the router object. All the paths are defined using strings (we don't use string patterns or regular expressions). -Routes that act on some specific resource (e.g. book) use path parameters to get the object id from the URL. +Routes that act on some specific resource (e.g., book) use path parameters to get the object id from the URL. The handler functions are all imported from the controller modules we created in the previous section. @@ -656,7 +661,7 @@ Open **/routes/index.js** and replace the existing route with the function below ```js // GET home page. -router.get("/", function (req, res) { +router.get("/", (req, res) => { res.redirect("/catalog"); }); ``` @@ -672,9 +677,9 @@ We do this in `app.js`. Open **app.js** and require the catalog route below the other routes (add the third line shown below, underneath the other two that should be already present in the file): ```js -var indexRouter = require("./routes/index"); -var usersRouter = require("./routes/users"); -const catalogRouter = require("./routes/catalog"); //Import routes for "catalog" area of site +const indexRouter = require("./routes/index"); +const usersRouter = require("./routes/users"); +const catalogRouter = require("./routes/catalog"); // Import routes for "catalog" area of site ``` Next, add the catalog route to the middleware stack below the other routes (add the third line shown below, underneath the other two that should be already present in the file): diff --git a/files/en-us/learn_web_development/extensions/server-side/express_nodejs/skeleton_website/index.md b/files/en-us/learn_web_development/extensions/server-side/express_nodejs/skeleton_website/index.md index 19b13f09560ebd6..38f353542a7d5e5 100644 --- a/files/en-us/learn_web_development/extensions/server-side/express_nodejs/skeleton_website/index.md +++ b/files/en-us/learn_web_development/extensions/server-side/express_nodejs/skeleton_website/index.md @@ -1,15 +1,19 @@ --- title: "Express Tutorial Part 2: Creating a skeleton website" +short-title: "2: Skeleton website" slug: Learn_web_development/Extensions/Server-side/Express_Nodejs/skeleton_website page-type: learn-module-chapter +sidebar: learnsidebar --- -{{LearnSidebar}} - {{PreviousMenuNext("Learn_web_development/Extensions/Server-side/Express_Nodejs/Tutorial_local_library_website", "Learn_web_development/Extensions/Server-side/Express_Nodejs/mongoose", "Learn_web_development/Extensions/Server-side/Express_Nodejs")}} This second article in our [Express Tutorial](/en-US/docs/Learn_web_development/Extensions/Server-side/Express_Nodejs/Tutorial_local_library_website) shows how you can create a "skeleton" website project which you can then go on to populate with site-specific routes, templates/views, and database calls. +> [!WARNING] +> The Express tutorial is written for Express version 4, while the latest version is Express 5. +> We plan to update the documentation in the second half of 2025. + <table> <tbody> <tr> @@ -81,7 +85,7 @@ express You can also choose a view (template) engine using `--view` and/or a CSS generation engine using `--css`. > [!NOTE] -> The other options for choosing template engines (e.g. `--hogan`, `--ejs`, `--hbs` etc.) are deprecated. Use `--view` (or `-v`). +> The other options for choosing template engines (e.g., `--hogan`, `--ejs`, `--hbs` etc.) are deprecated. Use `--view` (or `-v`). ### What view engine should I use? @@ -424,7 +428,7 @@ const app = require("../app"); > [!NOTE] > Node.js 14 and later support ES6 `import` statements for importing JavaScript (ECMAScript) modules. -> To use this feature you have to add `"type": "module",` to your Express **package.json** file, all the modules in your application have to use `import` rather than `require()`, and for _relative imports_ you must include the file extension (for more information see the [Node documentation](https://nodejs.org/api/esm.html#introduction)). +> To use this feature you have to add `"type": "module"` to your Express **package.json** file, all the modules in your application have to use `import` rather than `require()`, and for _relative imports_ you must include the file extension (for more information see the [Node documentation](https://nodejs.org/api/esm.html#introduction)). > While there are benefits to using `import`, this tutorial uses `require()` in order to match [the Express documentation](https://expressjs.com/en/starter/hello-world.html). The remainder of the code in this file sets up a node HTTP server with `app` set to a specific port (defined in an environment variable or 3000 if the variable isn't defined), and starts listening and reporting server errors and connections. For now you don't really need to know anything else about the code (everything in this file is "boilerplate"), but feel free to review it if you're interested. @@ -435,6 +439,7 @@ This file creates an `express` application object (named `app`, by convention), ```js const express = require("express"); + const app = express(); // … module.exports = app; @@ -530,6 +535,7 @@ Then it specifies a route on that object and lastly exports the router from the ```js const express = require("express"); + const router = express.Router(); /* GET users listing. */ diff --git a/files/en-us/learn_web_development/extensions/server-side/express_nodejs/tutorial_local_library_website/index.md b/files/en-us/learn_web_development/extensions/server-side/express_nodejs/tutorial_local_library_website/index.md index cb6a5ab01edbcba..1ac18889259b597 100644 --- a/files/en-us/learn_web_development/extensions/server-side/express_nodejs/tutorial_local_library_website/index.md +++ b/files/en-us/learn_web_development/extensions/server-side/express_nodejs/tutorial_local_library_website/index.md @@ -1,10 +1,12 @@ --- title: "Express Tutorial: The Local Library website" +short-title: "1: Local library tutorial" slug: Learn_web_development/Extensions/Server-side/Express_Nodejs/Tutorial_local_library_website page-type: learn-module-chapter +sidebar: learnsidebar --- -{{LearnSidebar}}{{PreviousMenuNext("Learn_web_development/Extensions/Server-side/Express_Nodejs/development_environment", "Learn_web_development/Extensions/Server-side/Express_Nodejs/skeleton_website", "Learn_web_development/Extensions/Server-side/Express_Nodejs")}} +{{PreviousMenuNext("Learn_web_development/Extensions/Server-side/Express_Nodejs/development_environment", "Learn_web_development/Extensions/Server-side/Express_Nodejs/skeleton_website", "Learn_web_development/Extensions/Server-side/Express_Nodejs")}} The first article in our practical tutorial series explains what you'll learn, and provides an overview of the "local library" example website we'll be working through and evolving in subsequent articles. diff --git a/files/en-us/learn_web_development/extensions/server-side/first_steps/client-server_overview/index.md b/files/en-us/learn_web_development/extensions/server-side/first_steps/client-server_overview/index.md index 86f19ac31cd57ea..65cd605b57e90af 100644 --- a/files/en-us/learn_web_development/extensions/server-side/first_steps/client-server_overview/index.md +++ b/files/en-us/learn_web_development/extensions/server-side/first_steps/client-server_overview/index.md @@ -1,10 +1,11 @@ --- -title: Client-Server Overview +title: Client-server overview slug: Learn_web_development/Extensions/Server-side/First_steps/Client-Server_overview page-type: learn-module-chapter +sidebar: learnsidebar --- -{{LearnSidebar}}{{PreviousMenuNext("Learn_web_development/Extensions/Server-side/First_steps/Introduction", "Learn_web_development/Extensions/Server-side/First_steps/Web_frameworks", "Learn_web_development/Extensions/Server-side/First_steps")}} +{{PreviousMenuNext("Learn_web_development/Extensions/Server-side/First_steps/Introduction", "Learn_web_development/Extensions/Server-side/First_steps/Web_frameworks", "Learn_web_development/Extensions/Server-side/First_steps")}} Now that you know the purpose and potential benefits of server-side programming, we're going to examine in detail what happens when a server receives a "dynamic request" from a browser. As most website server-side code handles requests and responses in similar ways, this will help you understand what you need to do when writing most of your own code. @@ -34,11 +35,11 @@ Web browsers communicate with [web servers](/en-US/docs/Learn_web_development/Ho This request includes: -- A URL identifying the target server and resource (e.g. an HTML file, a particular data point on the server, or a tool to run). +- A URL identifying the target server and resource (e.g., an HTML file, a particular data point on the server, or a tool to run). - A method that defines the required action (for example, to get a file or to save or update some data). The different methods/verbs and their associated actions are listed below: - - `GET`: Get a specific resource (e.g. an HTML file containing information about a product, or a list of products). - - `POST`: Create a new resource (e.g. add a new article to a wiki, add a new contact to a database). + - `GET`: Get a specific resource (e.g., an HTML file containing information about a product, or a list of products). + - `POST`: Create a new resource (e.g., add a new article to a wiki, add a new contact to a database). - `HEAD`: Get the metadata information about a specific resource without getting the body like `GET` would. You might for example use a `HEAD` request to find out the last time a resource was updated, and then only use the (more "expensive") `GET` request to download the resource if it has changed. - `PUT`: Update an existing resource (or create a new one if it doesn't exist). - `DELETE`: Delete the specified resource. @@ -50,9 +51,9 @@ This request includes: - `POST` data. `POST` requests add new resources, the data for which is encoded within the request body. - Client-side cookies. Cookies contain session data about the client, including keys that the server can use to determine their login status and permissions/accesses to resources. -Web servers wait for client request messages, process them when they arrive, and reply to the web browser with an HTTP response message. The response contains an [HTTP Response status code](/en-US/docs/Web/HTTP/Status) indicating whether or not the request succeeded (e.g., {{HTTPStatus("200", "200 OK")}} for success, {{HTTPStatus("404", "404 Not Found")}} if the resource cannot be found, {{HTTPStatus("403", "403 Forbidden")}} if the user isn't authorized to see the resource, etc.). The body of the response to a successful `GET` request contains the requested resource. +Web servers wait for client request messages, process them when they arrive, and reply to the web browser with an HTTP response message. The response contains an [HTTP Response status code](/en-US/docs/Web/HTTP/Reference/Status) indicating whether or not the request succeeded (e.g., {{HTTPStatus("200", "200 OK")}} for success, {{HTTPStatus("404", "404 Not Found")}} if the resource cannot be found, {{HTTPStatus("403", "403 Forbidden")}} if the user isn't authorized to see the resource, etc.). The body of the response to a successful `GET` request contains the requested resource. -When an HTML page is returned, it is rendered by the web browser. As part of processing, the browser may discover links to other resources (e.g. an HTML page usually references JavaScript and CSS files), and will send separate HTTP Requests to download these files. +When an HTML page is returned, it is rendered by the web browser. As part of processing, the browser may discover links to other resources (e.g., an HTML page usually references JavaScript and CSS files), and will send separate HTTP Requests to download these files. Both static and dynamic websites (discussed in the following sections) use exactly the same communication protocol/patterns. @@ -98,7 +99,7 @@ For example, you can see here that: - My browser (`User-Agent`) is Mozilla Firefox (`Mozilla/5.0`). - It can accept gzip compressed information (`Accept-Encoding: gzip`). - It can accept the specified languages (`Accept-Language: en-US,en;q=0.8,es;q=0.6`). -- The `Referer` line indicates the address of the web page that contained the link to this resource (i.e. the origin of the request, `https://developer.mozilla.org/en-US/`). +- The `Referer` line indicates the address of the web page that contained the link to this resource (i.e., the origin of the request, `https://developer.mozilla.org/en-US/`). HTTP requests can also have a body, but it is empty in this case. @@ -136,7 +137,7 @@ Content-Length: 41823 … ``` -The remainder of the response header includes information about the response (e.g. when it was generated), the server, and how it expects the browser to handle the page (e.g. the `X-Frame-Options: DENY` line tells the browser not to allow this page to be embedded in an {{htmlelement("iframe")}} in another site). +The remainder of the response header includes information about the response (e.g., when it was generated), the server, and how it expects the browser to handle the page (e.g., the `X-Frame-Options: DENY` line tells the browser not to allow this page to be embedded in an {{htmlelement("iframe")}} in another site). ### POST request/response example @@ -189,11 +190,11 @@ Content-Length: 0 ``` > [!NOTE] -> The HTTP responses and requests shown in these examples were captured using the [Fiddler](https://www.telerik.com/download/fiddler) application, but you can get similar information using web sniffers (e.g. [WebSniffer](https://websniffer.com/)) or packet analyzers like [Wireshark](https://www.wireshark.org/). You can try this yourself. Use any of the linked tools, and then navigate through a site and edit profile information to see the different requests and responses. Most modern browsers also have tools that monitor network requests (for example, the [Network Monitor](https://firefox-source-docs.mozilla.org/devtools-user/network_monitor/index.html) tool in Firefox). +> The HTTP responses and requests shown in these examples were captured using the [Fiddler](https://www.telerik.com/download/fiddler) application, but you can get similar information using web sniffers (e.g., [WebSniffer](https://websniffer.com/)) or packet analyzers like [Wireshark](https://www.wireshark.org/). You can try this yourself. Use any of the linked tools, and then navigate through a site and edit profile information to see the different requests and responses. Most modern browsers also have tools that monitor network requests (for example, the [Network Monitor](https://firefox-source-docs.mozilla.org/devtools-user/network_monitor/index.html) tool in Firefox). ## Static sites -A _static site_ is one that returns the same hard coded content from the server whenever a particular resource is requested. So for example if you have a page about a product at `/static/my-product1.html`, this same page will be returned to every user. If you add another similar product to your site you will need to add another page (e.g. `my-product2.html`) and so on. This can start to get really inefficient — what happens when you get to thousands of product pages? You would repeat a lot of code across each page (the basic page template, structure, etc.), and if you wanted to change anything about the page structure — like add a new "related products" section for example — then you'd have to change every page individually. +A _static site_ is one that returns the same hard coded content from the server whenever a particular resource is requested. So for example if you have a page about a product at `/static/my-product1.html`, this same page will be returned to every user. If you add another similar product to your site you will need to add another page (e.g., `my-product2.html`) and so on. This can start to get really inefficient — what happens when you get to thousands of product pages? You would repeat a lot of code across each page (the basic page template, structure, etc.), and if you wanted to change anything about the page structure — like add a new "related products" section for example — then you'd have to change every page individually. > [!NOTE] > Static sites are excellent when you have a small number of pages and you want to send the same content to every user. However they can have a significant cost to maintain as the number of pages becomes larger. @@ -202,9 +203,9 @@ Let's recap on how this works, by looking again at the static site architecture ![A simplified diagram of a static web server.](basic_static_app_server.png) -When a user wants to navigate to a page, the browser sends an HTTP `GET` request specifying the URL of its HTML page. The server retrieves the requested document from its file system and returns an HTTP response containing the document and an [HTTP Response status code](/en-US/docs/Web/HTTP/Status) of `200 OK` (indicating success). The server might return a different status code, for example `404 Not Found` if the file is not present on the server, or `301 Moved Permanently` if the file exists but has been redirected to a different location. +When a user wants to navigate to a page, the browser sends an HTTP `GET` request specifying the URL of its HTML page. The server retrieves the requested document from its file system and returns an HTTP response containing the document and an [HTTP Response status code](/en-US/docs/Web/HTTP/Reference/Status) of `200 OK` (indicating success). The server might return a different status code, for example `404 Not Found` if the file is not present on the server, or `301 Moved Permanently` if the file exists but has been redirected to a different location. -The server for a static site will only ever need to process GET requests, because the server doesn't store any modifiable data. It also doesn't change its responses based on HTTP Request data (e.g. URL parameters or cookies). +The server for a static site will only ever need to process GET requests, because the server doesn't store any modifiable data. It also doesn't change its responses based on HTTP Request data (e.g., URL parameters or cookies). Understanding how static sites work is nevertheless useful when learning server-side programming, because dynamic sites handle requests for static files (CSS, JavaScript, static images, etc.) in exactly the same way. @@ -226,7 +227,7 @@ The diagram below shows the main elements of the "team coach" website, along wit After the coach submits the form with the team name and number of players, the sequence of operations is: -1. The web browser creates an HTTP `GET` request to the server using the base URL for the resource (`/best`) and encoding the team and player number either as URL parameters (e.g. `/best?team=my_team_name&show=11`) or as part of the URL pattern (e.g. `/best/my_team_name/11/`). A `GET` request is used because the request is only fetching data (not modifying data). +1. The web browser creates an HTTP `GET` request to the server using the base URL for the resource (`/best`) and encoding the team and player number either as URL parameters (e.g., `/best?team=my_team_name&show=11`) or as part of the URL pattern (e.g., `/best/my_team_name/11/`). A `GET` request is used because the request is only fetching data (not modifying data). 2. The _Web Server_ detects that the request is "dynamic" and forwards it to the _Web Application_ for processing (the web server determines how to handle different URLs based on pattern matching rules defined in its configuration). 3. The _Web Application_ identifies that the _intention_ of the request is to get the "best team list" based on the URL (`/best/`) and finds out the required team name and number of players from the URL. The _Web Application_ then gets the required information from the database (using additional "internal" parameters to define which players are "best", and possibly also getting the identity of the logged in coach from a client-side cookie). 4. The _Web Application_ dynamically creates an HTML page by putting the data (from the _Database_) into placeholders inside an HTML template. @@ -273,7 +274,7 @@ urlpatterns = [ ``` > [!NOTE] -> The first parameters in the `url()` functions may look a bit odd (e.g. `r'^junior/$'`) because they use a pattern matching technique called "regular expressions" (RegEx, or RE). You don't need to know how regular expressions work at this point, other than that they allow us to match patterns in the URL (rather than the hard coded values above) and use them as parameters in our view functions. As an example, a really simple RegEx might say "match a single uppercase letter, followed by between 4 and 7 lower case letters." +> The first parameters in the `url()` functions may look a bit odd (e.g., `r'^junior/$'`) because they use a pattern matching technique called "regular expressions" (RegEx, or RE). You don't need to know how regular expressions work at this point, other than that they allow us to match patterns in the URL (rather than the hard coded values above) and use them as parameters in our view functions. As an example, a really simple RegEx might say "match a single uppercase letter, followed by between 4 and 7 lower case letters." The web framework also makes it easy for a view function to fetch information from the database. The structure of our data is defined in models, which are Python classes that define the fields to be stored in the underlying database. If we have a model named _Team_ with a field of "_team_type_" then we can use a simple query syntax to get back all teams that have a particular type. diff --git a/files/en-us/learn_web_development/extensions/server-side/first_steps/index.md b/files/en-us/learn_web_development/extensions/server-side/first_steps/index.md index 3cbd118411e7634..20f7d6759943be2 100644 --- a/files/en-us/learn_web_development/extensions/server-side/first_steps/index.md +++ b/files/en-us/learn_web_development/extensions/server-side/first_steps/index.md @@ -1,11 +1,11 @@ --- title: Server-side website programming first steps +short-title: First steps slug: Learn_web_development/Extensions/Server-side/First_steps page-type: learn-module +sidebar: learnsidebar --- -{{LearnSidebar}} - {{NextMenu("Learn_web_development/Extensions/Server-side/First_steps/Introduction", "Learn_web_development/Extensions/Server-side")}} In this module, we answer a few fundamental questions about server-side programming such as "What is it?", "How does it differ from client-side programming?", and "Why is it so useful?". We also provide an overview of some of the most popular server-side web frameworks, along with guidance on how to select the most suitable framework for creating your first project. Finally, we provide a high-level introductory article about web server security. diff --git a/files/en-us/learn_web_development/extensions/server-side/first_steps/introduction/index.md b/files/en-us/learn_web_development/extensions/server-side/first_steps/introduction/index.md index d08986a263a907c..b20a1f0cabd63f2 100644 --- a/files/en-us/learn_web_development/extensions/server-side/first_steps/introduction/index.md +++ b/files/en-us/learn_web_development/extensions/server-side/first_steps/introduction/index.md @@ -1,11 +1,11 @@ --- title: Introduction to the server side +short-title: Introduction slug: Learn_web_development/Extensions/Server-side/First_steps/Introduction page-type: learn-module-chapter +sidebar: learnsidebar --- -{{LearnSidebar}} - {{NextMenu("Learn_web_development/Extensions/Server-side/First_steps/Client-Server_overview", "Learn_web_development/Extensions/Server-side/First_steps")}} Welcome to the MDN beginner's server-side programming course! In this first article, we look at server-side programming from a high level, answering questions such as "what is it?", "how does it differ from client-side programming?", and "why it is so useful?". After reading this article you'll understand the additional power available to websites through server-side coding. @@ -28,7 +28,7 @@ Welcome to the MDN beginner's server-side programming course! In this first arti </tbody> </table> -Most large-scale websites use server-side code to dynamically display different data when needed, generally pulled out of a database stored on a server and sent to the client to be displayed via some code (e.g. HTML and JavaScript). +Most large-scale websites use server-side code to dynamically display different data when needed, generally pulled out of a database stored on a server and sent to the client to be displayed via some code (e.g., HTML and JavaScript). Perhaps the most significant benefit of server-side code is that it allows you to tailor website content for individual users. Dynamic sites can highlight content that is more relevant based on user preferences and habits. It can also make sites easier to use by storing personal preferences and information — for example reusing stored credit card details to streamline subsequent payments. @@ -40,17 +40,17 @@ In the modern world of web development, learning about server-side development i Web browsers communicate with [web servers](/en-US/docs/Learn_web_development/Howto/Web_mechanics/What_is_a_web_server) using the **H**yper**T**ext **T**ransfer **P**rotocol ({{glossary("HTTP")}}). When you click a link on a web page, submit a form, or run a search, an **HTTP request** is sent from your browser to the target server. -The request includes a URL identifying the affected resource, a method that defines the required action (for example to get, delete, or post the resource), and may include additional information encoded in URL parameters (the field-value pairs sent via a [query string](https://en.wikipedia.org/wiki/Query_string)), as POST data (data sent by the [HTTP POST method](/en-US/docs/Web/HTTP/Methods/POST)), or in associated {{glossary("Cookie", "cookies")}}. +The request includes a URL identifying the affected resource, a method that defines the required action (for example to get, delete, or post the resource), and may include additional information encoded in URL parameters (the field-value pairs sent via a [query string](https://en.wikipedia.org/wiki/Query_string)), as POST data (data sent by the [HTTP POST method](/en-US/docs/Web/HTTP/Reference/Methods/POST)), or in associated {{glossary("Cookie", "cookies")}}. -Web servers wait for client request messages, process them when they arrive, and reply to the web browser with an **HTTP response** message. The response contains a status line indicating whether or not the request succeeded (e.g. "HTTP/1.1 200 OK" for success). +Web servers wait for client request messages, process them when they arrive, and reply to the web browser with an **HTTP response** message. The response contains a status line indicating whether or not the request succeeded (e.g., "HTTP/1.1 200 OK" for success). -The body of a successful response to a request would contain the requested resource (e.g. a new HTML page, or an image), which could then be displayed by the web browser. +The body of a successful response to a request would contain the requested resource (e.g., a new HTML page, or an image), which could then be displayed by the web browser. ### Static sites The diagram below shows a basic web server architecture for a _static site_ (a static site is one that returns the same hard-coded content from the server whenever a particular resource is requested). When a user wants to navigate to a page, the browser sends an HTTP "GET" request specifying its URL. -The server retrieves the requested document from its file system and returns an HTTP response containing the document and a [success status](/en-US/docs/Web/HTTP/Status#successful_responses) (usually 200 OK). If the file cannot be retrieved for some reason, an error status is returned (see [client error responses](/en-US/docs/Web/HTTP/Status#client_error_responses) and [server error responses](/en-US/docs/Web/HTTP/Status#server_error_responses)). +The server retrieves the requested document from its file system and returns an HTTP response containing the document and a [success status](/en-US/docs/Web/HTTP/Reference/Status#successful_responses) (usually 200 OK). If the file cannot be retrieved for some reason, an error status is returned (see [client error responses](/en-US/docs/Web/HTTP/Reference/Status#client_error_responses) and [server error responses](/en-US/docs/Web/HTTP/Reference/Status#server_error_responses)). ![A simplified diagram of a static web server.](basic_static_app_server.png) @@ -58,7 +58,7 @@ The server retrieves the requested document from its file system and returns an A dynamic website is one where some of the response content is generated _dynamically_, only when needed. On a dynamic website, HTML pages are normally created by inserting data from a database into placeholders in HTML templates (this is a much more efficient way of storing large amounts of content than using static websites). -A dynamic site can return different data for a URL based on information provided by the user or stored preferences and can perform other operations as part of returning a response (e.g. sending notifications). +A dynamic site can return different data for a URL based on information provided by the user or stored preferences and can perform other operations as part of returning a response (e.g., sending notifications). Most of the code to support a dynamic website must run on the server. Creating this code is known as "**server-side programming**" (or sometimes "**back-end scripting**"). @@ -88,7 +88,7 @@ Server-side code can be written in any number of programming languages — examp Developers typically write their code using **web frameworks**. Web frameworks are collections of functions, objects, rules and other code constructs designed to solve common problems, speed up development, and simplify the different types of tasks faced in a particular domain. -Again, while both client and server-side code use frameworks, the domains are very different, and hence so are the frameworks. Client-side web frameworks simplify layout and presentation tasks while server-side web frameworks provide a lot of "common" web server functionality that you might otherwise have to implement yourself (e.g. support for sessions, support for users and authentication, easy database access, templating libraries, etc.). +Again, while both client and server-side code use frameworks, the domains are very different, and hence so are the frameworks. Client-side web frameworks simplify layout and presentation tasks while server-side web frameworks provide a lot of "common" web server functionality that you might otherwise have to implement yourself (e.g., support for sessions, support for users and authentication, easy database access, templating libraries, etc.). > [!NOTE] > Client-side frameworks are often used to help speed up development of client-side code, but you can also choose to write all the code by hand; in fact, writing your code by hand can be quicker and more efficient if you only need a small, simple website UI. @@ -109,7 +109,7 @@ Some of the common uses and benefits of server-side programming are listed below Imagine how many products are available on Amazon, and imagine how many posts have been written on Facebook? Creating a separate static page for each product or post would be completely impractical. -Server-side programming allows us to instead store the information in a database and dynamically construct and return HTML and other types of files (e.g. PDFs, images, etc.). It is also possible to return data ({{glossary("JSON")}}, {{glossary("XML")}}, etc.) for rendering by appropriate client-side web frameworks (this reduces the processing burden on the server and the amount of data that needs to be sent). +Server-side programming allows us to instead store the information in a database and dynamically construct and return HTML and other types of files (e.g., PDFs, images, etc.). It is also possible to return data ({{glossary("JSON")}}, {{glossary("XML")}}, etc.) for rendering by appropriate client-side web frameworks (this reduces the processing burden on the server and the amount of data that needs to be sent). The server is not limited to sending information from databases, and might alternatively return the result of software tools, or data from communications services. The content can even be targeted for the type of client device that is receiving it. @@ -156,7 +156,7 @@ Server-side programming allows developers to make use of **sessions** — basica This allows, for example, a site to know that a user has previously logged in and display links to their emails or order history, or perhaps save the state of a simple game so that the user can go to a site again and carry on where they left it. > [!NOTE] -> Visit a newspaper site that has a subscription model and open a bunch of tabs (e.g. [The Age](https://www.theage.com.au/)). Continue to visit the site over a few hours/days. Eventually, you will start to be redirected to pages explaining how to subscribe, and you will be unable to access articles. This information is an example of session information stored in cookies. +> Visit a newspaper site that has a subscription model and open a bunch of tabs (e.g., [The Age](https://www.theage.com.au/)). Continue to visit the site over a few hours/days. Eventually, you will start to be redirected to pages explaining how to subscribe, and you will be unable to access articles. This information is an example of session information stored in cookies. ### Notifications and communication diff --git a/files/en-us/learn_web_development/extensions/server-side/first_steps/web_frameworks/index.md b/files/en-us/learn_web_development/extensions/server-side/first_steps/web_frameworks/index.md index 4153d1b76085f99..e34d12643df51bb 100644 --- a/files/en-us/learn_web_development/extensions/server-side/first_steps/web_frameworks/index.md +++ b/files/en-us/learn_web_development/extensions/server-side/first_steps/web_frameworks/index.md @@ -1,10 +1,12 @@ --- title: Server-side web frameworks +short-title: Server-side frameworks slug: Learn_web_development/Extensions/Server-side/First_steps/Web_frameworks page-type: learn-module-chapter +sidebar: learnsidebar --- -{{LearnSidebar}}{{PreviousMenuNext("Learn_web_development/Extensions/Server-side/First_steps/Client-Server_overview", "Learn_web_development/Extensions/Server-side/First_steps/Website_security", "Learn_web_development/Extensions/Server-side/First_steps")}} +{{PreviousMenuNext("Learn_web_development/Extensions/Server-side/First_steps/Client-Server_overview", "Learn_web_development/Extensions/Server-side/First_steps/Website_security", "Learn_web_development/Extensions/Server-side/First_steps")}} The previous article showed you what the communication between web clients and servers looks like, the nature of HTTP requests and responses, and what a server-side web application needs to do in order to respond to requests from a web browser. With this knowledge under our belt, it's time to explore how web frameworks can simplify these tasks, and give you an idea of how you'd choose a framework for your first server-side web application. @@ -35,7 +37,7 @@ The following sections illustrate some points using code fragments taken from re ## Overview -Server-side web frameworks (a.k.a. "web application frameworks") are software frameworks that make it easier to write, maintain and scale web applications. They provide tools and libraries that simplify common web development tasks, including routing URLs to appropriate handlers, interacting with databases, supporting sessions and user authorization, formatting output (e.g. HTML, JSON, XML), and improving security against web attacks. +Server-side web frameworks (a.k.a. "web application frameworks") are software frameworks that make it easier to write, maintain and scale web applications. They provide tools and libraries that simplify common web development tasks, including routing URLs to appropriate handlers, interacting with databases, supporting sessions and user authorization, formatting output (e.g., HTML, JSON, XML), and improving security against web attacks. The next section provides a bit more detail about how web frameworks can ease web application development. We then explain some of the criteria you can use for choosing a web framework, and then list some of your options. @@ -88,7 +90,7 @@ urlpatterns = [ Data can be encoded in an HTTP request in a number of ways. An HTTP `GET` request to get files or data from the server may encode what data is required in URL parameters or within the URL structure. An HTTP `POST` request to update a resource on the server will instead include the update information as "POST data" within the body of the request. The HTTP request may also include information about the current session or user in a client-side cookie. -Web frameworks provide programming-language-appropriate mechanisms to access this information. For example, the `HttpRequest` object that Django passes to every view function contains methods and properties for accessing the target URL, the type of request (e.g. an HTTP `GET`), `GET` or `POST` parameters, cookie and session data, etc. Django can also pass information encoded in the structure of the URL by defining "capture patterns" in the URL mapper (see the last code fragment in the section above). +Web frameworks provide programming-language-appropriate mechanisms to access this information. For example, the `HttpRequest` object that Django passes to every view function contains methods and properties for accessing the target URL, the type of request (e.g., an HTTP `GET`), `GET` or `POST` parameters, cookie and session data, etc. Django can also pass information encoded in the structure of the URL by defining "capture patterns" in the URL mapper (see the last code fragment in the section above). ### Abstract and simplify database access @@ -97,9 +99,9 @@ Websites use databases to store information both to be shared with users, and ab Using an ORM has two benefits: - You can replace the underlying database without necessarily needing to change the code that uses it. This allows developers to optimize for the characteristics of different databases based on their usage. -- Basic validation of data can be implemented within the framework. This makes it easier and safer to check that data is stored in the correct type of database field, has the correct format (e.g. an email address), and isn't malicious in any way (hackers can use certain patterns of code to do bad things such as deleting database records). +- Basic validation of data can be implemented within the framework. This makes it easier and safer to check that data is stored in the correct type of database field, has the correct format (e.g., an email address), and isn't malicious in any way (hackers can use certain patterns of code to do bad things such as deleting database records). -For example, the Django web framework provides an ORM, and refers to the object used to define the structure of a record as the _model_. The model specifies the field _types_ to be stored, which may provide field-level validation on what information can be stored (e.g. an email field would only allow valid email addresses). The field definitions may also specify their maximum size, default values, selection list options, help text for documentation, label text for forms etc. The model doesn't state any information about the underlying database as that is a configuration setting that may be changed separately of our code. +For example, the Django web framework provides an ORM, and refers to the object used to define the structure of a record as the _model_. The model specifies the field _types_ to be stored, which may provide field-level validation on what information can be stored (e.g., an email field would only allow valid email addresses). The field definitions may also specify their maximum size, default values, selection list options, help text for documentation, label text for forms etc. The model doesn't state any information about the underlying database as that is a configuration setting that may be changed separately of our code. The first code snippet below shows a very simple Django model for a `Team` object. This stores the team name and team level as character fields and specifies a maximum number of characters to be stored for each record. The `team_level` is a choice field, so we also provide a mapping between choices to be displayed and data to be stored, along with a default value. @@ -120,7 +122,7 @@ class Team(models.Model): team_level = models.CharField(max_length=3,choices=TEAM_LEVELS,default='U11') ``` -The Django model provides a simple query API for searching the database. This can match against a number of fields at a time using different criteria (e.g. exact, case-insensitive, greater than, etc.), and can support complex statements (for example, you can specify a search on U11 teams that have a team name that starts with "Fr" or ends with "al"). +The Django model provides a simple query API for searching the database. This can match against a number of fields at a time using different criteria (e.g., exact, case-insensitive, greater than, etc.), and can support complex statements (for example, you can specify a search on U11 teams that have a team name that starts with "Fr" or ends with "al"). The second code snippet shows a view function (resource handler) for displaying all of our U09 teams. In this case we specify that we want to filter for all records where the `team_level` field has exactly the text 'U09' (note below how this criteria is passed to the `filter()` function as an argument with field name and match type separated by double underscores: **team_level\_\_exact**). @@ -142,7 +144,7 @@ Web frameworks often provide templating systems. These allow you to specify the Web frameworks often provide a mechanism to make it easy to generate other formats from stored data, including {{glossary("JSON")}} and {{glossary("XML")}}. -For example, the Django template system allows you to specify variables using a "double-handlebars" syntax (e.g. `\{{ variable_name }}`), which will be replaced by values passed in from the view function when a page is rendered. The template system also provides support for expressions (with syntax: `{% expression %}`), which allow templates to perform simple operations like iterating list values passed into the template. +For example, the Django template system allows you to specify variables using a "double-handlebars" syntax (e.g., `\{{ variable_name }}`), which will be replaced by values passed in from the view function when a page is rendered. The template system also provides support for expressions (with syntax: `{% expression %}`), which allow templates to perform simple operations like iterating list values passed into the template. > [!NOTE] > Many other templating systems use a similar syntax, e.g.: Jinja2 (Python), handlebars (JavaScript), moustache (JavaScript), etc. @@ -175,14 +177,14 @@ Numerous web frameworks exist for almost every programming language you might wa Some of the factors that may affect your decision are: - **Effort to learn:** The effort to learn a web framework depends on how familiar you are with the underlying programming language, the consistency of its API, the quality of its documentation, and the size and activity of its community. If you're starting from absolutely no programming experience then consider Django (it is one of the easiest to learn based on the above criteria). If you are part of a development team that already has significant experience with a particular web framework or programming language, then it makes sense to stick with that. -- **Productivity:** Productivity is a measure of how quickly you can create new features once you are familiar with the framework, and includes both the effort to write and maintain code (since you can't write new features while old ones are broken). Many of the factors affecting productivity are similar to those for "Effort to learn" — e.g. documentation, community, programming experience, etc. — other factors include: +- **Productivity:** Productivity is a measure of how quickly you can create new features once you are familiar with the framework, and includes both the effort to write and maintain code (since you can't write new features while old ones are broken). Many of the factors affecting productivity are similar to those for "Effort to learn" — e.g., documentation, community, programming experience, etc. — other factors include: - _Framework purpose/origin_: Some web frameworks were initially created to solve certain types of problems, and remain _better_ at creating web apps with similar constraints. For example, Django was created to support development of a newspaper website, so it's good for blogs and other sites that involve publishing things. By contrast, Flask is a much lighter-weight framework and is great for creating web apps running on embedded devices. - _Opinionated vs. unopinionated_: An opinionated framework is one in which there are recommended "best" ways to solve a particular problem. Opinionated frameworks tend to be more productive when you're trying to solve common problems, because they lead you in the right direction, however they are sometimes less flexible. - _Batteries included vs. get it yourself_: Some web frameworks include tools/libraries that address every problem their developers can think "by default", while more lightweight frameworks expect web developers to pick and choose solution to problems from separate libraries (Django is an example of the former, while Flask is an example of a very light-weight framework). Frameworks that include everything are often easier to get started with because you already have everything you need, and the chances are that it is well integrated and well documented. However if a smaller framework has everything you (will ever) need then it can run in more constrained environments and will have a smaller and easier subset of things to learn. - _Whether or not the framework encourages good development practices_: For example, a framework that encourages a [Model-View-Controller](/en-US/docs/Glossary/MVC) architecture to separate code into logical functions will result in more maintainable code than one that has no expectations on developers. Similarly, framework design can have a large impact on how easy it is to test and re-use code. -- **Performance of the framework/programming language:** Usually "speed" is not the biggest factor in selection because even relatively slow runtimes like Python are more than "good enough" for mid-sized sites running on moderate hardware. The perceived speed benefits of another language, e.g. C++ or JavaScript, may well be offset by the costs of learning and maintenance. +- **Performance of the framework/programming language:** Usually "speed" is not the biggest factor in selection because even relatively slow runtimes like Python are more than "good enough" for mid-sized sites running on moderate hardware. The perceived speed benefits of another language, e.g., C++ or JavaScript, may well be offset by the costs of learning and maintenance. - **Caching support:** As your website becomes more successful then you may find that it can no longer cope with the number of requests it is receiving as users access it. At this point you may consider adding support for caching. Caching is an optimization where you store all or part of a web response so that it does not have to be recalculated on subsequent requests. Returning a cached response is much faster than calculating one in the first place. Caching can be implemented in your code or in the server (see [reverse proxy](https://en.wikipedia.org/wiki/Reverse_proxy)). Web frameworks will have different levels of support for defining what content can be cached. - **Scalability:** Once your website is fantastically successful you will exhaust the benefits of caching and even reach the limits of _vertical scaling_ (running your web application on more powerful hardware). At this point you may need to _scale horizontally_ (share the load by distributing your site across a number of web servers and databases) or scale "geographically" because some of your customers are based a long way away from your server. The web framework you choose can make a big difference on how easy it is to scale your site. - **Web security:** Some web frameworks provide better support for handling common web attacks. Django for example sanitizes all user input from HTML templates so that user-entered JavaScript cannot be run. Other frameworks provide similar protection, but it is not always enabled by default. @@ -229,7 +231,7 @@ Popular sites using Django (from Django home page) include: Disqus, Instagram, K While minimalist, Flask can create serious websites out of the box. It contains a development server and debugger, and includes support for [Jinja2](https://github.com/pallets/jinja) templating, secure cookies, [unit testing](https://en.wikipedia.org/wiki/Unit_testing), and [RESTful](https://restapitutorial.com/) request dispatching. It has good documentation and an active community. -Flask has become extremely popular, particularly for developers who need to provide web services on small, resource-constrained systems (e.g. running a web server on a [Raspberry Pi](https://www.raspberrypi.org/), [Drone controllers](https://www.techuseful.com/drone-definitions-learning-the-drone-lingo/), etc.) +Flask has become extremely popular, particularly for developers who need to provide web services on small, resource-constrained systems (e.g., running a web server on a [Raspberry Pi](https://www.raspberrypi.org/), [Drone controllers](https://www.techuseful.com/drone-definitions-learning-the-drone-lingo/), etc.) ### Express (Node.js/JavaScript) @@ -313,7 +315,7 @@ Some of the features provided by Mojolicious are: Although definitely not the only framework based on [Java](https://www.java.com/) it is easy to use to create stand-alone, production-grade Spring-based Applications that you can "just run". It is an opinionated view of the Spring platform and third-party libraries but allows to start with minimum fuss and configuration. -It can be used for small problems but its strength is building larger scale applications that use a cloud approach. Usually multiple applications run in parallel talking to each other, with some providing user interaction and others doing back end work (e.g. accessing databases or other services). Load balancers help to ensure redundancy and reliability or allow geolocated handling of user requests to ensure responsiveness. +It can be used for small problems but its strength is building larger scale applications that use a cloud approach. Usually multiple applications run in parallel talking to each other, with some providing user interaction and others doing back end work (e.g., accessing databases or other services). Load balancers help to ensure redundancy and reliability or allow geolocated handling of user requests to ensure responsiveness. ## Summary diff --git a/files/en-us/learn_web_development/extensions/server-side/first_steps/website_security/index.md b/files/en-us/learn_web_development/extensions/server-side/first_steps/website_security/index.md index 57ec07c59cf4082..cff215d2d9d6249 100644 --- a/files/en-us/learn_web_development/extensions/server-side/first_steps/website_security/index.md +++ b/files/en-us/learn_web_development/extensions/server-side/first_steps/website_security/index.md @@ -2,9 +2,10 @@ title: Website security slug: Learn_web_development/Extensions/Server-side/First_steps/Website_security page-type: learn-module-chapter +sidebar: learnsidebar --- -{{LearnSidebar}}{{PreviousMenu("Learn_web_development/Extensions/Server-side/First_steps/Web_frameworks", "Learn_web_development/Extensions/Server-side/First_steps")}} +{{PreviousMenu("Learn_web_development/Extensions/Server-side/First_steps/Web_frameworks", "Learn_web_development/Extensions/Server-side/First_steps")}} Website security requires vigilance in all aspects of website design and usage. This introductory article won't make you a website security guru, but it will help you understand where threats come from, and what you can do to harden your web application against the most common attacks. @@ -134,7 +135,7 @@ Almost all of the security exploits in the previous sections are successful when A number of other concrete steps you can take are: - Use more effective password management. Encourage strong passwords. Consider two-factor authentication for your site, so that in addition to a password the user must enter another authentication code (usually one that is delivered via some physical hardware that only the user will have, such as a code in an SMS sent to their phone). -- Configure your web server to use [HTTPS](/en-US/docs/Glossary/HTTPS) and [HTTP Strict Transport Security](/en-US/docs/Web/HTTP/Headers/Strict-Transport-Security) (HSTS). HTTPS encrypts data sent between your client and server. This ensures that login credentials, cookies, `POST` requests data and header information are not easily available to attackers. +- Configure your web server to use [HTTPS](/en-US/docs/Glossary/HTTPS) and [HTTP Strict Transport Security](/en-US/docs/Web/HTTP/Reference/Headers/Strict-Transport-Security) (HSTS). HTTPS encrypts data sent between your client and server. This ensures that login credentials, cookies, `POST` requests data and header information are not easily available to attackers. - Keep track of the most popular threats (the [current OWASP list is here](https://owasp.org/www-project-top-ten/)) and address the most common vulnerabilities first. - Use [vulnerability scanning tools](https://owasp.org/www-community/Vulnerability_Scanning_Tools) to perform automated security testing on your site. Later on, your very successful website may also find bugs by offering a bug bounty [like Mozilla does here](https://www.mozilla.org/en-US/security/bug-bounty/faq-webapp/). - Only store and display data that you need. For example, if your users must store sensitive information like credit card details, only display enough of the card number that it can be identified by the user, and not enough that it can be copied by an attacker and used on another site. The most common pattern at this time is to only display the last 4 digits of a credit card number. diff --git a/files/en-us/learn_web_development/extensions/server-side/index.md b/files/en-us/learn_web_development/extensions/server-side/index.md index 599977d89a2c06e..0c789b179282685 100644 --- a/files/en-us/learn_web_development/extensions/server-side/index.md +++ b/files/en-us/learn_web_development/extensions/server-side/index.md @@ -1,11 +1,11 @@ --- title: Server-side website programming +short-title: Server-side websites slug: Learn_web_development/Extensions/Server-side page-type: learn-topic +sidebar: learnsidebar --- -{{LearnSidebar}} - The **_Dynamic Websites_** – **Server-side programming** topic is a series of modules that show how to create dynamic websites; websites that deliver customized information in response to HTTP requests. The modules provide a general introduction to server-side programming, along with specific beginner-level tutorials on how to use the Django (Python) and Express (Node.js/JavaScript) web frameworks to create basic applications. Most major websites use some kind of server-side technology to dynamically display data as required. For example, imagine how many products are available on Amazon, and imagine how many posts have been written on Facebook. Displaying all of these using different static pages would be extremely inefficient, so instead such sites display static templates (built using [HTML](/en-US/docs/Learn_web_development/Core/Structuring_content), [CSS](/en-US/docs/Learn_web_development/Core/Styling_basics), and [JavaScript](/en-US/docs/Learn_web_development/Core/Scripting)), and then dynamically update the data displayed inside those templates when needed, such as when you want to view a different product on Amazon. diff --git a/files/en-us/learn_web_development/extensions/server-side/node_server_without_framework/index.md b/files/en-us/learn_web_development/extensions/server-side/node_server_without_framework/index.md index 1a83b6685274961..2222aabfdbd04f0 100644 --- a/files/en-us/learn_web_development/extensions/server-side/node_server_without_framework/index.md +++ b/files/en-us/learn_web_development/extensions/server-side/node_server_without_framework/index.md @@ -2,10 +2,9 @@ title: Node.js server without a framework slug: Learn_web_development/Extensions/Server-side/Node_server_without_framework page-type: guide +sidebar: learnsidebar --- -{{LearnSidebar}} - This article shows a static file server built in [Node.js](https://nodejs.org/en/) without using any frameworks. The current state of Node.js is such that almost everything we need for the static file server is provided by built-in APIs and a few lines of code. @@ -23,7 +22,7 @@ const PORT = 8000; const MIME_TYPES = { default: "application/octet-stream", html: "text/html; charset=UTF-8", - js: "application/javascript", + js: "text/javascript", css: "text/css", png: "image/png", jpg: "image/jpeg", @@ -43,7 +42,7 @@ const prepareFile = async (url) => { const pathTraversal = !filePath.startsWith(STATIC_PATH); const exists = await fs.promises.access(filePath).then(...toBool); const found = !pathTraversal && exists; - const streamPath = found ? filePath : STATIC_PATH + "/404.html"; + const streamPath = found ? filePath : `${STATIC_PATH}/404.html`; const ext = path.extname(streamPath).substring(1).toLowerCase(); const stream = fs.createReadStream(streamPath); return { found, ext, stream }; @@ -90,7 +89,7 @@ If the file can be served (the server process has access and no path-traversal v Note that other status codes can be found in `http.STATUS_CODES`. With `404` status we will return content of `'/404.html'` file. -The extension of the file being requested will be parsed and lower-cased. After that we will search `MIME_TYPES` collection for the right [MIME types](/en-US/docs/Web/HTTP/MIME_types). If no matches are found, we use the `application/octet-stream` as the default type. +The extension of the file being requested will be parsed and lower-cased. After that we will search `MIME_TYPES` collection for the right [MIME types](/en-US/docs/Web/HTTP/Guides/MIME_types). If no matches are found, we use the `application/octet-stream` as the default type. Finally, if there are no errors, we send the requested file. The `file.stream` will contain a `Readable` stream that will be piped into `res` (an instance of the `Writable` stream). diff --git a/files/en-us/learn_web_development/extensions/testing/automated_testing/index.md b/files/en-us/learn_web_development/extensions/testing/automated_testing/index.md index c80069a926e25f5..4c18033c5b275d3 100644 --- a/files/en-us/learn_web_development/extensions/testing/automated_testing/index.md +++ b/files/en-us/learn_web_development/extensions/testing/automated_testing/index.md @@ -1,10 +1,12 @@ --- title: Introduction to automated testing +short-title: Automated testing slug: Learn_web_development/Extensions/Testing/Automated_testing page-type: learn-module-chapter +sidebar: learnsidebar --- -{{LearnSidebar}}{{PreviousMenuNext("Learn_web_development/Extensions/Testing/Feature_detection", "Learn_web_development/Extensions/Testing/Your_own_automation_environment", "Learn_web_development/Extensions/Testing")}} +{{PreviousMenuNext("Learn_web_development/Extensions/Testing/Feature_detection", "Learn_web_development/Extensions/Testing/Your_own_automation_environment", "Learn_web_development/Extensions/Testing")}} Manually running tests on several browsers and devices, several times per day, can get tedious, and time-consuming. To handle this efficiently, you should become familiar with automation tools. In this article, we look at what is available, how to use task runners, and how to use the basics of commercial browser test automation apps such as Sauce Labs, BrowserStack, and TestingBot. @@ -699,7 +701,7 @@ Below is an example on how to interact with the TestingBot API with the NodeJS c api_secret: "your-tb-secret", }); - tb.getTests(function (err, tests) { + tb.getTests((err, tests) => { console.log(tests); }); ``` diff --git a/files/en-us/learn_web_development/extensions/testing/automated_testing/lambdatest-dashboard.png b/files/en-us/learn_web_development/extensions/testing/automated_testing/lambdatest-dashboard.png deleted file mode 100644 index a4bee423d4eb83a..000000000000000 Binary files a/files/en-us/learn_web_development/extensions/testing/automated_testing/lambdatest-dashboard.png and /dev/null differ diff --git a/files/en-us/learn_web_development/extensions/testing/automated_testing/mark-as-bug-1.png b/files/en-us/learn_web_development/extensions/testing/automated_testing/mark-as-bug-1.png deleted file mode 100644 index d16f77035b86438..000000000000000 Binary files a/files/en-us/learn_web_development/extensions/testing/automated_testing/mark-as-bug-1.png and /dev/null differ diff --git a/files/en-us/learn_web_development/extensions/testing/automated_testing/mark-as-bug-2.png b/files/en-us/learn_web_development/extensions/testing/automated_testing/mark-as-bug-2.png deleted file mode 100644 index c5b52ccdf2847be..000000000000000 Binary files a/files/en-us/learn_web_development/extensions/testing/automated_testing/mark-as-bug-2.png and /dev/null differ diff --git a/files/en-us/learn_web_development/extensions/testing/automated_testing/mark-as-bug-3.png b/files/en-us/learn_web_development/extensions/testing/automated_testing/mark-as-bug-3.png deleted file mode 100644 index dd6b3c6cbb94044..000000000000000 Binary files a/files/en-us/learn_web_development/extensions/testing/automated_testing/mark-as-bug-3.png and /dev/null differ diff --git a/files/en-us/learn_web_development/extensions/testing/feature_detection/index.md b/files/en-us/learn_web_development/extensions/testing/feature_detection/index.md index 17a209515dc49ea..a287101a7354f00 100644 --- a/files/en-us/learn_web_development/extensions/testing/feature_detection/index.md +++ b/files/en-us/learn_web_development/extensions/testing/feature_detection/index.md @@ -1,10 +1,12 @@ --- title: Implementing feature detection +short-title: Feature detection slug: Learn_web_development/Extensions/Testing/Feature_detection page-type: learn-module-chapter +sidebar: learnsidebar --- -{{LearnSidebar}}{{PreviousMenuNext("Learn_web_development/Extensions/Testing/HTML_and_CSS","Learn_web_development/Extensions/Testing/Automated_testing", "Learn_web_development/Extensions/Testing")}} +{{PreviousMenuNext("Learn_web_development/Extensions/Testing/HTML_and_CSS","Learn_web_development/Extensions/Testing/Automated_testing", "Learn_web_development/Extensions/Testing")}} Feature detection involves working out whether a browser supports a certain block of code, and running different code depending on whether it does (or doesn't), so that the browser can always provide a working experience rather than crashing/erroring in some browsers. This article details how to write your own simple feature detection, how to use a library to speed up implementation, and native features for feature detection such as `@supports`. @@ -37,11 +39,11 @@ Feature detection involves working out whether a browser supports a certain bloc The idea behind feature detection is that you can run a test to determine whether a feature is supported in the current browser, and then conditionally run code to provide an acceptable experience both in browsers that _do_ support the feature, and browsers that _don't_. If you don't do this, browsers that don't support the features you are using in your code may not display your sites properly or might fail altogether, creating a bad user experience. -Let's recap and look at the example we touched on in our [Handling common JavaScript problems](/en-US/docs/Learn_web_development/Core/Scripting/Debugging_JavaScript#feature_detection) — the [Geolocation API](/en-US/docs/Web/API/Geolocation_API) (which exposes available location data for the device the web browser is running on) has the main entry point for its use, a `geolocation` property available on the global [Navigator](/en-US/docs/Web/API/Navigator) object. Therefore, you can detect whether the browser supports geolocation or not by using something like the following: +Let's recap and look at the example we touched on in our [JavaScript debugging and error handling](/en-US/docs/Learn_web_development/Core/Scripting/Debugging_JavaScript#feature_detection) article — the [Geolocation API](/en-US/docs/Web/API/Geolocation_API) (which exposes available location data for the device the web browser is running on) has the main entry point for its use, a `geolocation` property available on the global [Navigator](/en-US/docs/Web/API/Navigator) object. Therefore, you can detect whether the browser supports geolocation or not by using something like the following: ```js if ("geolocation" in navigator) { - navigator.geolocation.getCurrentPosition(function (position) { + navigator.geolocation.getCurrentPosition((position) => { // show the location on a map, such as the Google Maps API }); } else { @@ -49,7 +51,7 @@ if ("geolocation" in navigator) { } ``` -Before we move on, we'd like to say one thing upfront — don't confuse feature detection with **browser sniffing** (detecting what specific browser is accessing the site) — this is a terrible practice that should be discouraged at all costs. See [don't browser sniff](/en-US/docs/Learn_web_development/Core/Scripting/Debugging_JavaScript#dont_browser_sniff) for more details. +Before we move on, we'd like to say one thing upfront — don't confuse feature detection with **browser sniffing** (detecting what specific browser is accessing the site) — this is a terrible practice that should be discouraged at all costs. See [Browser detection using the user agent string (UA sniffing)](/en-US/docs/Web/HTTP/Guides/Browser_detection_using_the_user_agent) for more details. ## Writing your own feature detection tests @@ -57,7 +59,7 @@ In this section, we'll look at implementing your own feature detection tests, in ### CSS -You can write tests for CSS features by testing for the existence of _[element.style.property](/en-US/docs/Web/API/HTMLElement/style)_ (e.g. `paragraph.style.rotate`) in JavaScript. +You can write tests for CSS features by testing for the existence of _[element.style.property](/en-US/docs/Web/API/HTMLElement/style)_ (e.g., `paragraph.style.rotate`) in JavaScript. A classic example might be to test for [Subgrid](/en-US/docs/Web/CSS/CSS_grid_layout/Subgrid) support in a browser; for browsers that support the `subgrid` value for a subgrid value for [`grid-template-columns`](/en-US/docs/Web/CSS/grid-template-columns) and [`grid-template-rows`](/en-US/docs/Web/CSS/grid-template-rows), we can use subgrid in our layout. For browsers that don't, we could use regular grid that works fine but is not as cool-looking. @@ -163,11 +165,11 @@ Common patterns for detectable features include: - Specific return values of a method on an element - - : Create an element in memory using {{domxref("Document.createElement()")}} and then check if a method exists on it. If it does, check what value it returns. See the feature test in [Dive into HTML Video Format detection](https://diveinto.html5doctor.com/detect.html#video-formats) for an example of this pattern. + - : Create an element in memory using {{domxref("Document.createElement()")}} and then check if a method exists on it. If it does, check what value it returns. - Retention of assigned property value by an element - - : Create an element in memory using {{domxref("Document.createElement()")}}, set a property to a specific value, then check to see if the value is retained. See the feature test in [Dive into HTML \<input> type detection](https://diveinto.html5doctor.com/detect.html#input-types) for an example of this pattern. + - : Create an element in memory using {{domxref("Document.createElement()")}}, set a property to a specific value, then check to see if the value is retained. Bear in mind that some features are, however, known to be undetectable. In these cases, you'll need to use a different approach, such as using a {{Glossary("Polyfill", "polyfill")}}. diff --git a/files/en-us/learn_web_development/extensions/testing/html_and_css/index.md b/files/en-us/learn_web_development/extensions/testing/html_and_css/index.md index f61fc10bd0a82b4..7f66bc8b29b13b8 100644 --- a/files/en-us/learn_web_development/extensions/testing/html_and_css/index.md +++ b/files/en-us/learn_web_development/extensions/testing/html_and_css/index.md @@ -1,11 +1,11 @@ --- title: Handling common HTML and CSS problems +short-title: Common HTML and CSS problems slug: Learn_web_development/Extensions/Testing/HTML_and_CSS page-type: learn-module-chapter +sidebar: learnsidebar --- -{{LearnSidebar}} - {{PreviousMenuNext("Learn_web_development/Extensions/Testing/Testing_strategies","Learn_web_development/Extensions/Testing/Feature_detection", "Learn_web_development/Extensions/Testing")}} With the scene set, we'll now look specifically at the common cross-browser problems you will come across in HTML and CSS code, and what tools can be used to prevent problems from happening, or fix problems that occur. This includes linting code, handling CSS prefixes, using browser dev tools to track down problems, using polyfills to add support into browsers, tackling responsive design problems, and more. @@ -50,7 +50,7 @@ In our [Debugging HTML](/en-US/docs/Learn_web_development/Core/Structuring_conte Basically, it is a matter of checking whether your HTML and CSS code is well formed and doesn't contain any syntax errors. > [!NOTE] -> One common problem with CSS and HTML arises when different CSS rules begin to conflict with one another. This can be especially problematic when you are using third party code. For example, you might use a CSS framework and find that one of the class names it uses clashes with one you've already used for a different purpose. Or you might find that HTML generated by some kind of third party API (generating ad banners, for example) includes a class name or ID that you are already using for a different purpose. To ensure this doesn't happen, you need to research the tools you are using first and design your code around them. It is also worth "namespacing" CSS, e.g. if you have a widget, make sure it has a distinct class, and then start the selectors that select elements inside the widget with this class, so conflicts are less likely. For example `.audio-player ul a`. +> One common problem with CSS and HTML arises when different CSS rules begin to conflict with one another. This can be especially problematic when you are using third party code. For example, you might use a CSS framework and find that one of the class names it uses clashes with one you've already used for a different purpose. Or you might find that HTML generated by some kind of third party API (generating ad banners, for example) includes a class name or ID that you are already using for a different purpose. To ensure this doesn't happen, you need to research the tools you are using first and design your code around them. It is also worth "namespacing" CSS, e.g., if you have a widget, make sure it has a distinct class, and then start the selectors that select elements inside the widget with this class, so conflicts are less likely. For example `.audio-player ul a`. ### Validation @@ -105,7 +105,7 @@ Some problems can be solved by just taking advantage of the natural way in which Unrecognized HTML elements are treated by the browser as anonymous inline elements (effectively inline elements with no semantic value, similar to {{htmlelement("span")}} elements). You can still refer to them by their names, and style them with CSS, for example — you just need to make sure they are behaving as you want them to. Style them just as you would any other element, including setting the `display` property to something other than `inline` if needed. -More complex elements like HTML [`<video>`](/en-US/docs/Web/HTML/Element/video), [`<audio>`](/en-US/docs/Web/HTML/Element/audio), [`<picture>`](/en-US/docs/Web/HTML/Element/picture), [`<object>`](/en-US/docs/Web/HTML/Element/object), and [`<canvas>`](/en-US/docs/Web/HTML/Element/canvas) (and other features besides) have natural mechanisms for fallbacks to be added in case the resources linked to are not supported. You can add fallback content in between the opening and closing tags, and non-supporting browsers will effectively ignore the outer element and run the nested content. +More complex elements like HTML [`<video>`](/en-US/docs/Web/HTML/Reference/Elements/video), [`<audio>`](/en-US/docs/Web/HTML/Reference/Elements/audio), [`<picture>`](/en-US/docs/Web/HTML/Reference/Elements/picture), [`<object>`](/en-US/docs/Web/HTML/Reference/Elements/object), and [`<canvas>`](/en-US/docs/Web/HTML/Reference/Elements/canvas) (and other features besides) have natural mechanisms for fallbacks to be added in case the resources linked to are not supported. You can add fallback content in between the opening and closing tags, and non-supporting browsers will effectively ignore the outer element and run the nested content. For example: @@ -126,7 +126,7 @@ For example: This example includes a simple link allowing you to download the video if even the HTML video player doesn't work, so at least the user can still access the video. -Another example is form elements. When new [`<input>`](/en-US/docs/Web/HTML/Element/input) types were introduced for inputting specific information into forms, such as times, dates, colors, numbers, etc., if a browser didn't support the new feature, the browser used the default of `type="text"`. Input types were added, which are very useful, particularly on mobile platforms, where providing a pain-free way of entering data is very important for the user experience. Platforms provide different UI widgets depending on the input type, such as a calendar widget for entering dates. Should a browser not support an input type, the user can still enter the required data. +Another example is form elements. When new [`<input>`](/en-US/docs/Web/HTML/Reference/Elements/input) types were introduced for inputting specific information into forms, such as times, dates, colors, numbers, etc., if a browser didn't support the new feature, the browser used the default of `type="text"`. Input types were added, which are very useful, particularly on mobile platforms, where providing a pain-free way of entering data is very important for the user experience. Platforms provide different UI widgets depending on the input type, such as a calendar widget for entering dates. Should a browser not support an input type, the user can still enter the required data. The following example shows date and time inputs: @@ -211,7 +211,9 @@ For example, in the Firefox dev tools, you get this kind of output at the bottom If for example you were trying to use this selector, you'd be able to see that it wouldn't select the input element as desired: ```css -form > #date +form > #date { + /* … */ +} ``` (The `date` form input isn't a direct child of the `<form>`; you'd be better off using a general descendant selector instead of a child selector). @@ -258,9 +260,9 @@ If you do need to include modern features, test for feature support using [`@sup ### Responsive design problems -Responsive design is the practice of creating web layouts that change to suit different device form factors — for example, different screen widths, orientations (portrait or landscape), or resolutions. A desktop layout for example will look terrible when viewed on a mobile device, so you need to provide a suitable mobile layout using [media queries](/en-US/docs/Web/CSS/CSS_media_queries), and make sure it is applied correctly using [viewport](/en-US/docs/Web/HTML/Viewport_meta_tag). You can find a detailed account of such practices in [our responsive design tutorial](/en-US/docs/Learn_web_development/Core/CSS_layout/Responsive_Design). +Responsive design is the practice of creating web layouts that change to suit different device form factors — for example, different screen widths, orientations (portrait or landscape), or resolutions. A desktop layout for example will look terrible when viewed on a mobile device, so you need to provide a suitable mobile layout using [media queries](/en-US/docs/Web/CSS/CSS_media_queries), and make sure it is applied correctly using [viewport](/en-US/docs/Web/HTML/Guides/Viewport_meta_element). You can find a detailed account of such practices in [our responsive design tutorial](/en-US/docs/Learn_web_development/Core/CSS_layout/Responsive_Design). -Resolution is a big issue too — for example, mobile devices are less likely to need big heavy images than desktop computers, and are more likely to have slower internet connections and possibly even expensive data plans that make wasted bandwidth more of a problem. In addition, different devices can have a range of different resolutions, meaning that smaller images could appear pixelated. There are a number of techniques that allow you to work around such problems, from [media queries](/en-US/docs/Learn_web_development/Core/CSS_layout/Responsive_Design#media_queries) to more complex [responsive image techniques](/en-US/docs/Web/HTML/Responsive_images#resolution_switching_different_sizes), including {{HTMLElement('picture')}} and the {{HTMLElement('img')}} element's [`srcset`](/en-US/docs/Web/HTML/Element/img#srcset) and [`sizes`](/en-US/docs/Web/HTML/Element/img#sizes) attributes. +Resolution is a big issue too — for example, mobile devices are less likely to need big heavy images than desktop computers, and are more likely to have slower internet connections and possibly even expensive data plans that make wasted bandwidth more of a problem. In addition, different devices can have a range of different resolutions, meaning that smaller images could appear pixelated. There are a number of techniques that allow you to work around such problems, from [media queries](/en-US/docs/Learn_web_development/Core/CSS_layout/Responsive_Design#media_queries) to more complex [responsive image techniques](/en-US/docs/Web/HTML/Guides/Responsive_images#resolution_switching_different_sizes), including {{HTMLElement('picture')}} and the {{HTMLElement('img')}} element's [`srcset`](/en-US/docs/Web/HTML/Reference/Elements/img#srcset) and [`sizes`](/en-US/docs/Web/HTML/Reference/Elements/img#sizes) attributes. ## Finding help @@ -270,7 +272,7 @@ Among the best sources of support information are the Mozilla Developer Network To use the Mozilla Developer Network (MDN), most people do a search engine search of the technology they are trying to find information on, plus the term "mdn", for example, "mdn HTML video". MDN contains several useful types of content: -- Reference material with browser support information for client-side web technologies, e.g. the [\<video> reference page](/en-US/docs/Web/HTML/Element/video). +- Reference material with browser support information for client-side web technologies, e.g., the [\<video> reference page](/en-US/docs/Web/HTML/Reference/Elements/video). - Other supporting reference material, for example our [Guide to media types and formats on the web](/en-US/docs/Web/Media/Guides/Formats), - Useful tutorials that solve specific problems, for example, [Creating a cross-browser video player](/en-US/docs/Web/Media/Guides/Audio_and_video_delivery/cross_browser_video_player). diff --git a/files/en-us/learn_web_development/extensions/testing/index.md b/files/en-us/learn_web_development/extensions/testing/index.md index f6c6074c1a314e7..10d1abd44bc2fe0 100644 --- a/files/en-us/learn_web_development/extensions/testing/index.md +++ b/files/en-us/learn_web_development/extensions/testing/index.md @@ -2,10 +2,9 @@ title: Testing slug: Learn_web_development/Extensions/Testing page-type: learn-module +sidebar: learnsidebar --- -{{LearnSidebar}} - {{NextMenu("Learn_web_development/Extensions/Testing/Introduction", "Learn_web_development/Extensions")}} Any codebase past a certain level of complexity needs to have a system of tests associated with it, to make sure that as new code is added, the codebase continues to function correctly and performantly, and continues to meet the users' needs. This module lists the fundamentals that you should start with. @@ -22,7 +21,7 @@ Before starting this module, You should really have learnt the fundamentals of [ - [Introduction to cross browser testing](/en-US/docs/Learn_web_development/Extensions/Testing/Introduction) - : This article starts the module off by providing an overview of the topic of cross browser testing, answering questions such as "what is cross browser testing?", "what are the most common types of problems you'll encounter?", and "what are the main approaches for testing, identifying, and fixing problems?" - [Strategies for carrying out testing](/en-US/docs/Learn_web_development/Extensions/Testing/Testing_strategies) - - : Next, we drill down into carrying out testing, looking at identifying a target audience (e.g. what browsers, devices, and other segments should you make sure are tested), lo-fi testing strategies (get yourself a range of devices and some virtual machines and do ad hoc tests when needed), higher tech strategies (automation, using dedicated testing apps), and testing with user groups. + - : Next, we drill down into carrying out testing, looking at identifying a target audience (e.g., what browsers, devices, and other segments should you make sure are tested), lo-fi testing strategies (get yourself a range of devices and some virtual machines and do ad hoc tests when needed), higher tech strategies (automation, using dedicated testing apps), and testing with user groups. - [Handling common HTML and CSS problems](/en-US/docs/Learn_web_development/Extensions/Testing/HTML_and_CSS) - : With the scene set, we'll now look specifically at the common cross-browser problems you will come across in HTML and CSS code, and what tools can be used to prevent problems from happening, or fix problems that occur. This includes linting code, handling CSS prefixes, using browser dev tools to track down problems, using polyfills to add support into browsers, tackling responsive design problems, and more. - [Implementing feature detection](/en-US/docs/Learn_web_development/Extensions/Testing/Feature_detection) diff --git a/files/en-us/learn_web_development/extensions/testing/introduction/index.md b/files/en-us/learn_web_development/extensions/testing/introduction/index.md index 3d4ab9c53accca6..70abf0c3e6d59ea 100644 --- a/files/en-us/learn_web_development/extensions/testing/introduction/index.md +++ b/files/en-us/learn_web_development/extensions/testing/introduction/index.md @@ -1,10 +1,12 @@ --- title: Introduction to cross-browser testing +short-title: Introduction slug: Learn_web_development/Extensions/Testing/Introduction page-type: learn-module-chapter +sidebar: learnsidebar --- -{{LearnSidebar}}{{NextMenu("Learn_web_development/Extensions/Testing/Testing_strategies", "Learn_web_development/Extensions/Testing")}} +{{NextMenu("Learn_web_development/Extensions/Testing/Testing_strategies", "Learn_web_development/Extensions/Testing")}} This article gives an overview of cross-browser testing: what cross-browser testing is, some common problems, and some approaches for debugging/troubleshooting. @@ -39,7 +41,7 @@ Remember that you are not your users — just because your site works on your Ma > **Note:** [Make the web work for everyone](https://hacks.mozilla.org/2016/07/make-the-web-work-for-everyone/) discusses the different browsers, their market share, and related cross-browser compatibility issues. -Websites should be accessible across different browsers and devices, and to people with disabilities (e.g. screen-reader-friendly). A site doesn't need to deliver the exact same experience on all browsers and devices, as long as the core functionality is accessible in some way. For example, a modern browser might have something animated, 3D and shiny, while older browsers might just show a flat graphic with the same information. +Websites should be accessible across different browsers and devices, and to people with disabilities (e.g., screen-reader-friendly). A site doesn't need to deliver the exact same experience on all browsers and devices, as long as the core functionality is accessible in some way. For example, a modern browser might have something animated, 3D and shiny, while older browsers might just show a flat graphic with the same information. Also, it's just about impossible for a website to work on ALL browsers and devices, so a web developer should come to an agreement with the site owner on the range of browsers and devices where the code will work. @@ -50,7 +52,7 @@ There are many different reasons why cross-browser issues occur, and note that h Cross-browser issues commonly occur because: - sometimes browsers have bugs, or implement features differently. This situation is a lot less bad than it used to be; back when IE4 and Netscape 4 were competing to be the dominant browser in the 1990s, browser companies deliberately implemented things differently from each other to try to gain a competitive advantage, which made life hell for developers. Browsers are much better at following standards these days, but differences and bugs still creep through sometimes. -- some browsers may have different levels of support for technology features than others. This is inevitable when you are dealing with bleeding edge features that browsers are just getting around to implementing, or if you have to support very old browsers that are no longer being developed, which may have been frozen (i.e. no more new work done on them) a long time before a new feature was even invented. As an example, if you want to use cutting-edge JavaScript features in your site, they might not work in older browsers. If you need to support older browsers, you might have to not use those, or convert your code to old-fashioned syntax using some kind of cross-compiler where needed. +- some browsers may have different levels of support for technology features than others. This is inevitable when you are dealing with bleeding edge features that browsers are just getting around to implementing, or if you have to support very old browsers that are no longer being developed, which may have been frozen (i.e., no more new work done on them) a long time before a new feature was even invented. As an example, if you want to use cutting-edge JavaScript features in your site, they might not work in older browsers. If you need to support older browsers, you might have to not use those, or convert your code to old-fashioned syntax using some kind of cross-compiler where needed. - some devices may have constraints that cause a website to run slowly, or display badly. For example, if a site has been designed to look nice on a desktop PC, it will probably look tiny and be hard to read on a mobile device. If your site includes a load of big animations, it might be OK on a high-spec tablet but might be sluggish or jerky on a low-end device. …and more reasons besides. @@ -73,7 +75,7 @@ Steps 2–4 will tend to be repeated as many times as necessary to get all of th In the initial planning phase, you will probably have several planning meetings with the site owner/client (this might be your boss, or someone from an external company you are building a website for), in which you determine exactly what the website should be — what content and functionality should it have, what should it look like, etc. At this point, you'll also want to know how much time you have to develop the site — what is their deadline, and how much are they going to pay you for your work? We won't go into much detail about this, but cross-browser issues can have a serious effect on such planning. -Once you've got an idea of the required feature set, and what technologies you will likely build these features with, you should start exploring the target audience — what browsers, devices, etc. will the target audience for this site be using? The client might already have data about this from previous research they've done, e.g. from other websites they own, or from previous versions of the website you are now working on. If not, you will be able to get a good idea by looking at other sources, such as usage stats for competitors, or countries the site will be serving. You can also use a bit of intuition. +Once you've got an idea of the required feature set, and what technologies you will likely build these features with, you should start exploring the target audience — what browsers, devices, etc. will the target audience for this site be using? The client might already have data about this from previous research they've done, e.g., from other websites they own, or from previous versions of the website you are now working on. If not, you will be able to get a good idea by looking at other sources, such as usage stats for competitors, or countries the site will be serving. You can also use a bit of intuition. So for example, you might be building an e-commerce site that serves customers in North America. The site should work entirely in the last few versions of the most popular desktop and mobile browsers — this should include Chrome (and Edge, Opera as they are based on the same rendering engine as Chrome), Firefox, and Safari. It should also be accessible with WCAG AA compliance. @@ -113,7 +115,7 @@ At this point, fix any problems you find with your new code. Next, you should try expanding your list of test browsers to a full list of target audience browsers and start concentrating on weeding out cross-browser issues (see the next article for more information on [determining your target browsers](/en-US/docs/Learn_web_development/Extensions/Testing/Testing_strategies)). For example: - Try to test the latest change on all the modern desktop browsers you can — including Firefox, Chrome, Opera, Edge, and Safari on desktop (Mac, Windows, and Linux, ideally). -- Test it in common phone and tablet browsers (e.g. iOS Safari on iPhone/iPad, Chrome and Firefox on iPhone/iPad/Android), +- Test it in common phone and tablet browsers (e.g., iOS Safari on iPhone/iPad, Chrome and Firefox on iPhone/iPad/Android), - Also do tests in any other browsers you have included inside your target list. The most lo-fi option is to just do all the testing you can by yourself (pulling in teammates to help out if you are working in a team). You should try to test it on real physical devices where possible. @@ -137,7 +139,7 @@ It is often a good idea to test on prerelease versions of browsers; see the foll - [Microsoft Edge Insider](https://www.microsoft.com/en-us/edge/download/insider) - [Safari Technology Preview](https://developer.apple.com/safari/technology-preview/) - [Chrome Canary](https://www.google.com/chrome/canary/) -- [Opera Developer](https://www.opera.com/browsers/opera/developer) +- [Opera Developer](https://www.opera.com/opera/developer) This is especially prevalent if you are using very new technologies in your site, and you want to test against the latest implementations, or if you are coming across a bug in the latest release version of a browser, and you want to see if the browser's developers have fixed the bug in a newer version. @@ -145,7 +147,7 @@ This is especially prevalent if you are using very new technologies in your site Once you've discovered a bug, you need to try to fix it. -The first thing to do is to narrow down where the bug occurs as much as possible. Get as much information as you can from the person reporting the bug — what platform(s), device(s), browser version(s), etc. Try it on similar configurations (e.g. the same browser version on different desktop platforms, or a few different versions of the same browser on the same platform) to see how widely the bug persists. +The first thing to do is to narrow down where the bug occurs as much as possible. Get as much information as you can from the person reporting the bug — what platform(s), device(s), browser version(s), etc. Try it on similar configurations (e.g., the same browser version on different desktop platforms, or a few different versions of the same browser on the same platform) to see how widely the bug persists. It might not be your fault — if a bug exists in a browser, then hopefully the vendor will rapidly fix it. It might have already been fixed — for example if a bug is present in Firefox release 49, but it is no longer there in Firefox Nightly (version 52), then they have fixed it. If it is not fixed, then you may want to file a bug (see [Reporting bugs](#reporting_bugs), below). diff --git a/files/en-us/learn_web_development/extensions/testing/testing_strategies/index.md b/files/en-us/learn_web_development/extensions/testing/testing_strategies/index.md index 512ac2b8b7bd402..5f9bc1b759a6fc2 100644 --- a/files/en-us/learn_web_development/extensions/testing/testing_strategies/index.md +++ b/files/en-us/learn_web_development/extensions/testing/testing_strategies/index.md @@ -1,10 +1,12 @@ --- title: Strategies for carrying out testing +short-title: Testing strategies slug: Learn_web_development/Extensions/Testing/Testing_strategies page-type: learn-module-chapter +sidebar: learnsidebar --- -{{LearnSidebar}}{{PreviousMenuNext("Learn_web_development/Extensions/Testing/Introduction","Learn_web_development/Extensions/Testing/HTML_and_CSS", "Learn_web_development/Extensions/Testing")}} +{{PreviousMenuNext("Learn_web_development/Extensions/Testing/Introduction","Learn_web_development/Extensions/Testing/HTML_and_CSS", "Learn_web_development/Extensions/Testing")}} This article explains how to do cross-browser testing: how to choose which browsers and devices to test, how to actually test those browsers and devices, and how to test with user groups. @@ -105,7 +107,7 @@ There is a huge amount of data you could look at using Google Analytics — cust You can see what browsers and operating systems your users are using by selecting _Audience > Technology > Browser & OS_ from the left-hand menu. > [!NOTE] -> When using Google analytics, you need to beware of misleading bias, e.g. "We have no Firefox Mobile users" might lead you to not bother supporting Firefox mobile. But you are not going to have any Firefox Mobile users if the site was broken on Firefox mobile in the first place. +> When using Google analytics, you need to beware of misleading bias, e.g., "We have no Firefox Mobile users" might lead you to not bother supporting Firefox mobile. But you are not going to have any Firefox Mobile users if the site was broken on Firefox mobile in the first place. ### Other considerations @@ -148,7 +150,7 @@ You might notice that the button isn't usable with only the keyboard. We could r These test criteria are useful, because: - They give you a set of steps to follow when you are performing tests. -- They can be easily turned into sets of instructions for user groups to follow when carrying out tests (e.g. "try to activate the button using your mouse, and then the keyboard…") — see [User testing](#user_testing), below. +- They can be easily turned into sets of instructions for user groups to follow when carrying out tests (e.g., "try to activate the button using your mouse, and then the keyboard…") — see [User testing](#user_testing), below. - They can also provide a basis for writing automated tests. It is easier to write such tests if you know exactly what you want to test, and what the success conditions are (see [Selenium](/en-US/docs/Learn_web_development/Extensions/Testing/Your_own_automation_environment#selenium), later in the series). ## Putting together a testing lab @@ -208,7 +210,7 @@ Virtual machines are applications that run on your desktop computer and allow yo To use a Virtual Box, you need to: -1. Get hold of an installer disk or image (e.g. ISO file) for the operating system you want to emulate. Virtual Box is unable to provide these; most, like Windows OSes, are commercial products that can't be freely distributed. +1. Get hold of an installer disk or image (e.g., ISO file) for the operating system you want to emulate. Virtual Box is unable to provide these; most, like Windows OSes, are commercial products that can't be freely distributed. 2. [Download the appropriate installer](https://www.virtualbox.org/wiki/Downloads) for your operating system and install it. 3. Open the app; you'll be presented with a view like the following: ![Application window left panel lists Windows operating system and Opera TV emulators. Right panel include several subpanels including general, system, display, settings, audio, network and a preview.](virtualbox.png) 4. To create a new virtual machine, press the _New_ button in the top left-hand corner. @@ -267,9 +269,9 @@ Generally, you'll get your users to look at the page or view containing the new When running tests, it can also be a good idea to: - Set up a separate browser profile where possible, with browser extensions and other such things disabled, and run your tests in that profile (see [Use the Profile Manager to create and remove Firefox profiles](https://support.mozilla.org/en-US/kb/profile-manager-create-remove-switch-firefox-profiles) and [Share Chrome with others or add personas](https://support.google.com/chrome/answer/2364824), for example). -- Use browser's private mode functionality when running tests, where available (e.g. [Private Browsing](https://support.mozilla.org/en-US/kb/private-browsing-use-firefox-without-history) in Firefox, [Incognito Mode](https://support.google.com/chrome/answer/95464) in Chrome) so things like cookies and temp files are not saved. +- Use browser's private mode functionality when running tests, where available (e.g., [Private Browsing](https://support.mozilla.org/en-US/kb/private-browsing-use-firefox-without-history) in Firefox, [Incognito Mode](https://support.google.com/chrome/answer/95464) in Chrome) so things like cookies and temp files are not saved. -These steps are designed to make sure that the browser you are testing in is as "pure" as possible, i.e. there is nothing installed that could affect the results of the tests. +These steps are designed to make sure that the browser you are testing in is as "pure" as possible, i.e., there is nothing installed that could affect the results of the tests. > [!NOTE] > Another useful lo-fi option, if you have the hardware available, is to test your sites on low-end phones/other devices — as sites get larger and feature more effects, there is a higher chance of the site slowing down, so you need to start giving performance more consideration. Trying to get your functionality working on a low end device will make it more likely that the experience will be good on higher-end devices. diff --git a/files/en-us/learn_web_development/extensions/testing/your_own_automation_environment/automation-logs-1.jpg b/files/en-us/learn_web_development/extensions/testing/your_own_automation_environment/automation-logs-1.jpg deleted file mode 100644 index 95d6de9ea37d058..000000000000000 Binary files a/files/en-us/learn_web_development/extensions/testing/your_own_automation_environment/automation-logs-1.jpg and /dev/null differ diff --git a/files/en-us/learn_web_development/extensions/testing/your_own_automation_environment/index.md b/files/en-us/learn_web_development/extensions/testing/your_own_automation_environment/index.md index b1f37cd4ceb299a..8785a6b34e8005b 100644 --- a/files/en-us/learn_web_development/extensions/testing/your_own_automation_environment/index.md +++ b/files/en-us/learn_web_development/extensions/testing/your_own_automation_environment/index.md @@ -1,10 +1,12 @@ --- title: Setting up your own test automation environment +short-title: Automation environment setup slug: Learn_web_development/Extensions/Testing/Your_own_automation_environment page-type: learn-module-chapter +sidebar: learnsidebar --- -{{LearnSidebar}}{{PreviousMenu("Learn_web_development/Extensions/Testing/Automated_testing", "Learn_web_development/Extensions/Testing")}} +{{PreviousMenu("Learn_web_development/Extensions/Testing/Automated_testing", "Learn_web_development/Extensions/Testing")}} In this article, we will teach you how to install your own automation environment and run your own tests using Selenium/WebDriver and a testing library such as selenium-webdriver for Node. We will also look at how to integrate your local testing environment with commercial tools like the ones discussed in the previous article. @@ -470,7 +472,7 @@ Now when you run it, you should now see the test execute and the browser instanc There has been a lot written about best practices for writing tests. You can find some good background information at [Test Practices](https://www.selenium.dev/documentation/test_practices/). In general, you should make sure that your tests are: -1. Using good locator strategies: When you are [Interacting with the document](#interacting_with_the_document), make sure that you use locators and page objects that are unlikely to change — if you have a testable element that you want to perform a test on, make sure that it has a stable ID, or position on the page that can be selected using a CSS selector, which isn't going to just change with the next site iteration. You want to make your tests as non-brittle as possible, i.e. they won't just break when something changes. +1. Using good locator strategies: When you are [Interacting with the document](#interacting_with_the_document), make sure that you use locators and page objects that are unlikely to change — if you have a testable element that you want to perform a test on, make sure that it has a stable ID, or position on the page that can be selected using a CSS selector, which isn't going to just change with the next site iteration. You want to make your tests as non-brittle as possible, i.e., they won't just break when something changes. 2. Write atomic tests: Each test should test one thing only, making it easy to keep track of what test file is testing which criterion. The `duck_test.js` test we looked at above is pretty good, as it just tests a single thing — whether the title of a search results page is set correctly. We could work on giving it a better name so it is easier to work out what it does if we add more tests. Perhaps `results_page_title_set_correctly.js` would be slightly better? 3. Write autonomous tests: Each test should work on it's own, and not depend on other tests to work. @@ -568,7 +570,7 @@ Let's update our `bstack_duck_test.js` demo, to show how these features work: 1. Install the [axios](https://www.npmjs.com/package/axios) module by running the following command inside your project directory: - ```js + ```bash npm install axios ``` @@ -581,7 +583,10 @@ Let's update our `bstack_duck_test.js` demo, to show how these features work: 3. Now we'll update our `capabilities` object to include a project name — add the following line before the closing curly brace, remembering to add a comma at the end of the previous line (you can vary the build and project names to organize the tests in different windows in the BrowserStack automation dashboard): ```js - project: "DuckDuckGo test 2"; + const capabilities = { + // … + project: "DuckDuckGo test 2", + }; ``` 4. Next we'll retrieve the `sessionId` of the current session, and use it (along with your `userName` and `accessKey`) to assemble the URL to send requests to, to update the BrowserStack data. Include the following lines just below the block that creates the `driver` object (which starts with `const driver = new Builder()`) : @@ -629,6 +634,7 @@ Let's look at an example that demonstrates getting Selenium tests to run remotel ```js const { Builder, By, Key } = require("selenium-webdriver"); + const username = "YOUR-USER-NAME"; const accessKey = "YOUR-ACCESS-KEY"; @@ -755,7 +761,7 @@ If you now go back to your [Sauce Labs Automated Test dashboard](https://app.sau If you don't want to use a service like Sauce Labs or BrowserStack, you can always set up your own remote testing server. Let's look at how to do this. 1. The Selenium remote server requires Java to run. Download the latest JDK for your platform from the [Java SE downloads page](https://www.oracle.com/java/technologies/downloads/). Install it when it is downloaded. -2. Next, download the latest [Selenium standalone server](https://selenium-release.storage.googleapis.com/index.html) — this acts as a proxy between your script and the browser drivers. Choose the latest stable version number (i.e. not a beta), and from the list choose a file starting with "selenium-server-standalone". When this has downloaded, put it in a sensible place, like in your home directory. If you've not already added the location to your `PATH`, do so now (see the [Setting up Selenium in Node](#setting_up_selenium_in_node) section). +2. Next, download the latest [Selenium standalone server](https://selenium-release.storage.googleapis.com/index.html) — this acts as a proxy between your script and the browser drivers. Choose the latest stable version number (i.e., not a beta), and from the list choose a file starting with "selenium-server-standalone". When this has downloaded, put it in a sensible place, like in your home directory. If you've not already added the location to your `PATH`, do so now (see the [Setting up Selenium in Node](#setting_up_selenium_in_node) section). 3. Run the standalone server by entering the following into a terminal on your server computer ```bash diff --git a/files/en-us/learn_web_development/extensions/transform_animate/index.md b/files/en-us/learn_web_development/extensions/transform_animate/index.md deleted file mode 100644 index 3d9fb10fd372a91..000000000000000 --- a/files/en-us/learn_web_development/extensions/transform_animate/index.md +++ /dev/null @@ -1,34 +0,0 @@ ---- -title: Transform and animate CSS -slug: Learn_web_development/Extensions/Transform_animate -page-type: learn-module ---- - -{{LearnSidebar}} - -> [!NOTE] -> As you'll see below, this module is currently only a curriculum outline/syllabus, with some links provided to starter guides. We are intending to convert this into a full course in the future, as time allows. - -Animations are a vital part of a good user experience. Subtle usage can make page designs more interesting and appealing, and also enhance usability and perceived performance. - -## Prerequisites - -Before starting this module, you should be familiar with [HTML](/en-US/docs/Learn_web_development/Core/Structuring_content) and [CSS](/en-US/docs/Learn_web_development/Core/Styling_basics). - -## Learning outcomes - -- Understand why CSS transforms and animation are needed. -- A caveat — overuse can negatively affect usability and accessibility. -- Common transforms — scaling, rotation, and translation. -- 3D transforms, and how 3D positioning/perspective is handled on the web. -- Transitions. -- Animations. - -## Guides - -- [Using CSS transforms](/en-US/docs/Web/CSS/CSS_transforms/Using_CSS_transforms) - - : By modifying the coordinate space, CSS transforms change the shape and position of the affected content without disrupting the normal document flow. This guide provides an introduction to using transforms. -- [Using CSS transitions](/en-US/docs/Web/CSS/CSS_transitions/Using_CSS_transitions) - - : CSS transitions provide a way to control animation speed when changing CSS properties. Instead of having property changes take effect immediately, you can cause the changes in a property to take place over a period of time. For example, if you change the color of an element from white to black, usually the change is instantaneous. With CSS transitions enabled, changes occur at time intervals that follow an acceleration curve, all of which can be customized. -- [Using CSS animations](/en-US/docs/Web/CSS/CSS_animations/Using_CSS_animations) - - : CSS animations make it possible to animate transitions from one CSS style configuration to another. Animations consist of two components: a style describing the CSS animation and a set of keyframes that indicate the start and end states of the animation's style, as well as possible intermediate waypoints. 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 5fd017a764505d3..f0549806e6cf91b 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 @@ -2,10 +2,9 @@ title: Browsing the web slug: Learn_web_development/Getting_started/Environment_setup/Browsing_the_web page-type: tutorial-chapter +sidebar: learnsidebar --- -{{LearnSidebar}} - {{PreviousMenuNext("Learn_web_development/Getting_started/Environment_setup/Installing_software", "Learn_web_development/Getting_started/Environment_setup/Code_editors", "Learn_web_development/Getting_started/Environment_setup")}} By this point in the module, you should have multiple modern web browsers installed on your computer or other available devices. This article goes deeper into using browsers, looking at how a web browser works, the difference between some of the everyday things you'll interact with, and how to search for information. @@ -156,7 +155,7 @@ As a web developer, you will spend a lot of time searching for information, from If you are looking for general information about a specific web technology feature, you should type the name of the feature into the MDN search box. For example, try typing `box model`, `fetch()` or `video element` into the search box and see what comes up. If you don't find the information you need, try expanding your search — try your search term in a search engine. -If you are looking for a solution to a specific problem, such as `how to print out the fibonacci sequence with JavaScript` or `how to calculate whether a number is a prime number with JavaScript`, it is a good idea to search on a website such as [StackOverflow](https://stackoverflow.com), which is a community dedicated to answering programming problems. Again, try using a general search engine if a specific site doesn't give you a helpful answer. +If you are looking for a solution to a specific problem, such as `how to print out the fibonacci sequence with JavaScript` or `how to calculate whether a number is a prime number with JavaScript`, it is a good idea to search on a website such as [StackOverflow](https://stackoverflow.com/), which is a community dedicated to answering programming problems. Again, try using a general search engine if a specific site doesn't give you a helpful answer. > [!CALLOUT] > @@ -170,12 +169,12 @@ If you are looking for a solution to a specific problem, such as `how to print o ### Using AI -AI-generated search results are a very popular way of receiving information. They basically provide a superpowered search: they do a lot of searching in the background, before compiling the results into a single, easily-digestible answer. Common choices are [ChatGPT](https://chatgpt.com), [Google Gemini](https://gemini.google.com/app), and [Microsoft Copilot](https://copilot.microsoft.com), accessed either directly in a chat format, or via AI-powered in-app help or automation systems. +AI-generated search results are a very popular way of receiving information. They basically provide a superpowered search: they do a lot of searching in the background, before compiling the results into a single, easily-digestible answer. Common choices are [ChatGPT](https://chatgpt.com/), [Google Gemini](https://gemini.google.com/app), and [Microsoft Copilot](https://copilot.microsoft.com/), accessed either directly in a chat format, or via AI-powered in-app help or automation systems. When learning to code, AI chat prompts can be useful in a variety of ways: - Doing conventional searches, like the examples above. -- Figuring out bugs in a block of code. If you are getting frustrated because your code is not working, you can paste your code into an AI chat prompt, preceeded by a question such as `Where is the mistake in this code?` +- Figuring out bugs in a block of code. If you are getting frustrated because your code is not working, you can paste your code into an AI chat prompt, preceded by a question such as `Where is the mistake in this code?` - Generating an optimized version of a specific block of code. This can be useful when you've written a block of code that works, but you want to find out how it could be done more efficiently, or in a more robust way that solves more use cases. - Providing advice on how to do something. For example, if you don't just want to know where the bug is in a block of code, but instead you want advice on what strategy to use to debug it. @@ -205,7 +204,7 @@ As a result, you need to be careful to check the answers they give you, and not - You should include the language you are using in the search term, as shown in the examples above. If you just typed in `how to print out the fibonacci sequence`, you would likely end up with several solutions in Python, C++, Java, Ruby, or other languages — not quite as helpful when you are trying to learn JavaScript! - When you find a useful answer, bookmark or make a copy of it somewhere so you can find it again later. You'll be amazed how many times you run into the same problem. - If your code is returning a specific error message, try entering the error into a search engine or AI prompt. Other people will probably have already tackled the same error in the past and recorded solutions publicly somewhere. -- If possible, stick with recommended sites like MDN and [StackOverflow](https://stackoverflow.com). +- If possible, stick with recommended sites like MDN and [StackOverflow](https://stackoverflow.com/). - There are many advanced search techniques you can use in search engines that will give you better results than just typing a plain search term. Typing in a plain search term such as `ant fish cheese` will return results that contain any combination of those words. However, most search engines support variations of the following formats: - Typing in `"ant fish cheese"` (with the quotes) will only return results that contain that exact phrase. @@ -214,6 +213,6 @@ As a result, you need to be careful to check the answers they give you, and not - `intitle:cheese` will only return results that have "cheese" in the main title of the page. > [!NOTE] - > There are many other techniques you can use in various different search engines. Try seeing what others you can find — some useful resources are [Refine Google Searches](https://support.google.com/websearch/answer/2466433?hl=en), [How to use advanced syntax on DuckDuckGo Search](https://duckduckgo.com/duckduckgo-help-pages/results/syntax/), and [Microsoft: Advanced search options](https://support.microsoft.com/en-us/topic/advanced-search-options-b92e25f1-0085-4271-bdf9-14aaea720930). + > There are many other techniques you can use in various different search engines. Try seeing what others you can find — some useful resources are [Refine Google Searches](https://support.google.com/websearch/answer/2466433?hl=en), [How to use advanced syntax on DuckDuckGo Search](https://duckduckgo.com/duckduckgo-help-pages/results/syntax), and [Microsoft: Advanced search options](https://support.microsoft.com/en-us/topic/advanced-search-options-b92e25f1-0085-4271-bdf9-14aaea720930). {{PreviousMenuNext("Learn_web_development/Getting_started/Environment_setup/Installing_software", "Learn_web_development/Getting_started/Environment_setup/Code_editors", "Learn_web_development/Getting_started/Environment_setup")}} diff --git a/files/en-us/learn_web_development/getting_started/environment_setup/code_editors/index.md b/files/en-us/learn_web_development/getting_started/environment_setup/code_editors/index.md index 843e4221a2e5974..55bb2b1c48c3282 100644 --- a/files/en-us/learn_web_development/getting_started/environment_setup/code_editors/index.md +++ b/files/en-us/learn_web_development/getting_started/environment_setup/code_editors/index.md @@ -2,10 +2,9 @@ title: Code editors slug: Learn_web_development/Getting_started/Environment_setup/Code_editors page-type: tutorial-chapter +sidebar: learnsidebar --- -{{LearnSidebar}} - {{PreviousMenuNext("Learn_web_development/Getting_started/Environment_setup/Browsing_the_web", "Learn_web_development/Getting_started/Environment_setup/Dealing_with_files", "Learn_web_development/Getting_started/Environment_setup")}} Previously, we told you to install a code editor, as you'll need one to work through this pathway. In this article we look at code editors in more detail, giving you an idea of what they can do for you. @@ -36,7 +35,7 @@ Previously, we told you to install a code editor, as you'll need one to work thr Before starting to code, you may have had some experience working on text documents in a program like Microsoft Word. You might also be wondering whether you can work with code in these same programs. Unfortunately, the answer is "not really": - Programs like Microsoft Word are **Binary file** editors; their files contain a non-text format that can only be understood by those programs. Website source code, on the other hand, is stored as plain text. -- Word _can_ open and edit plain text files, but it doesn't handle them very well. It doesn't have a featureset designed for working with code — it is for writing documents such as letters and reports. You need a program that is designed to cleanly handle and output plain text, and work with code. +- Word _can_ open and edit plain text files, but it doesn't handle them very well. It doesn't have a feature set designed for working with code — it is for writing documents such as letters and reports. You need a program that is designed to cleanly handle and output plain text, and work with code. You probably already have a plain text editor on your computer. By default, Windows includes [Notepad](https://en.wikipedia.org/wiki/Microsoft_Notepad) and macOS comes with [TextEdit](https://en.wikipedia.org/wiki/TextEdit). Linux distros vary; the Ubuntu 22.04 LTS release comes with [GNOME Text Editor](https://en.wikipedia.org/wiki/GNOME_Text_Editor) by default. Default OS plain text editors can be OK, but they also have a limited feature set. @@ -148,7 +147,7 @@ The concept of search and replace should be fairly familiar to you if you've use 4. Type `sayHello` into the _Replace_ box that should now be visible. 5. You can now replace all instances of `createGreeting` in the code with `sayHello` using the two buttons to the right of the _Replace_ box. The left button moves to the next instance of the search string with one click and replaces it with a second click. The right button replaces all instances with a single click. -VS Code has many powerful find and replace features — see [Find and replace](https://code.visualstudio.com/docs/editor/codebasics#_find-and-replace). +VS Code has many powerful find and replace features — see [Find and replace](https://code.visualstudio.com/docs/editing/codebasics#_find-and-replace). ## Enhancing your code editor with extensions @@ -157,7 +156,7 @@ Most code editors have an extension or plugin system to allow you to add functio - Enable code completing, linting, or debugging functionality for languages not supported by default, or provide additional functionality for those that are. - Allow you to use the functionality of other tools from right inside the code editor, such as version control tools or local testing servers. - Provide additional user interface or code highlighting themes/color schemes. -- Suggest code snippets to fulfill requirements. These can be generated from static templates, or via AI tools. Using AI to generate code snippets has many of the same advantages and caveats as using it to generate search results (see [Searching for information > Using AI](/en-US/docs/Learn_web_development/Getting_started/Environment_setup/Browsing_the_web#using_ai) for more infomation). +- Suggest code snippets to fulfill requirements. These can be generated from static templates, or via AI tools. Using AI to generate code snippets has many of the same advantages and caveats as using it to generate search results (see [Searching for information > Using AI](/en-US/docs/Learn_web_development/Getting_started/Environment_setup/Browsing_the_web#using_ai) for more information). VS Code extensions are managed via the Extensions Marketplace panel in VS Code, accessed via the _View_ > _Extensions_ menu. Let's explore it now. diff --git a/files/en-us/learn_web_development/getting_started/environment_setup/command_line/glitch.png b/files/en-us/learn_web_development/getting_started/environment_setup/command_line/glitch.png deleted file mode 100644 index 1e23bdbe4f9f45d..000000000000000 Binary files a/files/en-us/learn_web_development/getting_started/environment_setup/command_line/glitch.png and /dev/null differ diff --git a/files/en-us/learn_web_development/getting_started/environment_setup/command_line/index.md b/files/en-us/learn_web_development/getting_started/environment_setup/command_line/index.md index 7fb26ae4e393a94..5224d65a48e78bb 100644 --- a/files/en-us/learn_web_development/getting_started/environment_setup/command_line/index.md +++ b/files/en-us/learn_web_development/getting_started/environment_setup/command_line/index.md @@ -1,11 +1,11 @@ --- title: Command line crash course +short-title: Command line slug: Learn_web_development/Getting_started/Environment_setup/Command_line page-type: tutorial-chapter +sidebar: learnsidebar --- -{{LearnSidebar}} - {{PreviousMenuNext("Learn_web_development/Getting_started/Environment_setup/Dealing_with_files", "Learn_web_development/Getting_started/Your_first_website", "Learn_web_development/Getting_started/Environment_setup")}} In your development process, you'll undoubtedly be required to run some commands in the terminal (or on the "command line" — these are effectively the same thing). This article provides an introduction to the terminal, the essential commands you'll need to enter into it, how to chain commands together, and how to add your own command line interface (CLI) tools. @@ -71,7 +71,7 @@ And below, you can see the macOS terminal application. ### How do you access the terminal? -Many developers today are using Unix-based tools (e.g. the terminal, and the tools you can access through it). Many tutorials and tools that exist on the web today support (and sadly assume) Unix-based systems, but not to worry — they are available on most systems. In this section, we'll look at how to get access to the terminal on your chosen system. +Many developers today are using Unix-based tools (e.g., the terminal, and the tools you can access through it). Many tutorials and tools that exist on the web today support (and sadly assume) Unix-based systems, but not to worry — they are available on most systems. In this section, we'll look at how to get access to the terminal on your chosen system. #### Linux/Unix @@ -177,7 +177,7 @@ cd Desktop/project/src Note that including a leading slash on your path makes the path absolute, for example `/Users/your-user-name/Desktop`. Omitting the leading slash as we've done above makes the path relative to your present working directory. This is exactly the same as you would see with URLs in your web browser. A leading slash means "at the root of the website", whereas omitting the slash means "the URL is relative to my current page". > [!NOTE] -> On windows, you use backslashes instead of forward slashes, e.g. `cd Desktop\project\src` — this may seem really odd, but if you are interested in why, [watch this YouTube clip](https://www.youtube.com/watch?v=5T3IJfBfBmI) featuring an explanation by one of Microsoft's Principal engineers. +> On windows, you use backslashes instead of forward slashes, e.g., `cd Desktop\project\src` — this may seem really odd, but if you are interested in why, [watch this YouTube clip](https://www.youtube.com/watch?v=5T3IJfBfBmI) featuring an explanation by one of Microsoft's Principal engineers. ### Listing directory contents @@ -238,9 +238,10 @@ We've alluded to this before, but to be clear — you need to be careful with th Let's say you had 1000 text files in a directory, and you wanted to go through them all and only delete the ones that have a certain substring inside the filename. If you are not careful, then you might end up deleting something important, losing you a load of your work in the process. One good habit to get into is to write your terminal command out inside a text editor, figure out how you think it should look, and then make a backup copy of your directory and try running the command on that first, to test it. -Another good tip — if you're not comfortable trying terminal commands out on your own machine, a nice safe place to try them is over at [Glitch.com](https://glitch.com/). Along with being a great place to try out web development code, the projects also give you access to a terminal, so you can run all these commands directly in that terminal, safe in the knowledge that you won't break your own machine. +If you're not comfortable trying terminal commands out on your own machine, there are hosted online terminals available that provide safe places to practice entering commands, without risking breaking your own machine: -![a double screenshot showing the glitch.com home page, and the glitch terminal emulator](glitch.png) +- Our learning partner, [Scrimba](https://scrimba.com/home?via=mdn), features a terminal for entering commands in their learning environment. A great place to see this in action is their [Command Line Basics](https://scrimba.com/command-line-basics-c08b87ogl0/~05hu?via=mdn) <sup>[_MDN learning partner_](/en-US/docs/MDN/Writing_guidelines/Learning_content#partner_links_and_embeds)</sup> course, which also provides a fun interactive introduction to navigating around the file tree and manipulating files and directories via the terminal. +- [Glitch.com](https://glitch.com/) is a great place to try out web development code, and Glitch projects also include a terminal for running commands. A great resource for getting a quick overview of specific terminal commands is [tldr.sh](https://tldr.sh/). This is a community-driven documentation service, similar to MDN, but specific to terminal commands. @@ -376,7 +377,7 @@ Prettier can: - Be installed on any operating system and even as a direct part of project tooling, ensuring that colleagues and friends who work on your code use the code style you're using. - Be configured to run upon save, as you type, or even before publishing your code (with additional tooling that we'll see later on in the module). -For this article, we will install Prettier locally, as suggested in the [Prettier installation guide](https://prettier.io/docs/en/install.html). +For this article, we will install Prettier locally, as suggested in the [Prettier installation guide](https://prettier.io/docs/install.html). Once you've installed node, open up the terminal and run the following command to install Prettier (we will explain what `--save-dev` does in the next article): @@ -477,7 +478,7 @@ With Prettier there's a number of ways automation can be achieved and though the - Whenever you hit "save" in your code editor, be it [VS Code](https://marketplace.visualstudio.com/items?itemName=esbenp.prettier-vscode), or [Sublime Text](https://packagecontrol.io/packages/JsPrettier). - As part of continuous integration checks using tools like [GitHub Actions](https://github.com/features/actions). -Our personal preference is the second one — while using say VS Code, Prettier kicks in and cleans up any formatting it needs to do every time we hit save. You can find a lot more information about using Prettier in different ways in the [Prettier docs](https://prettier.io/docs/en/). +Our personal preference is the second one — while using say VS Code, Prettier kicks in and cleans up any formatting it needs to do every time we hit save. You can find a lot more information about using Prettier in different ways in the [Prettier docs](https://prettier.io/docs/). ## Other tools to play with diff --git a/files/en-us/learn_web_development/getting_started/environment_setup/dealing_with_files/file-structure.png b/files/en-us/learn_web_development/getting_started/environment_setup/dealing_with_files/file-structure.png deleted file mode 100644 index c2b614ff1f5f683..000000000000000 Binary files a/files/en-us/learn_web_development/getting_started/environment_setup/dealing_with_files/file-structure.png and /dev/null differ diff --git a/files/en-us/learn_web_development/getting_started/environment_setup/dealing_with_files/index.md b/files/en-us/learn_web_development/getting_started/environment_setup/dealing_with_files/index.md index 138139994dbb03a..772dca08a6229be 100644 --- a/files/en-us/learn_web_development/getting_started/environment_setup/dealing_with_files/index.md +++ b/files/en-us/learn_web_development/getting_started/environment_setup/dealing_with_files/index.md @@ -2,10 +2,9 @@ title: Dealing with files slug: Learn_web_development/Getting_started/Environment_setup/Dealing_with_files page-type: tutorial-chapter +sidebar: learnsidebar --- -{{LearnSidebar}} - {{PreviousMenuNext("Learn_web_development/Getting_started/Environment_setup/Code_editors", "Learn_web_development/Getting_started/Environment_setup/Command_line", "Learn_web_development/Getting_started/Environment_setup")}} A website consists of many files: text content, code, stylesheets, media content, and so on. When you're building a website, you need to assemble these files into a sensible structure on your local computer, make sure they can talk to one another, and get all your content looking right before eventually putting them on a server for the world to see. This article explains how to use your computer's file explorer user interface (UI) and set up a sensible file structure for a website. @@ -99,7 +98,7 @@ You should see your `web-projects` folder open in the VS Code _EXPLORER_ pane, a #### An aside on keyboard navigation in VS Code -VS Code, while not perfect by any means, has an extensive set of keyboard shortcuts. Throughout this article we've tried to include useful ones where possible, but you can find more comprehensive lists at the VS Code [Keyboard Shortcuts Reference](https://code.visualstudio.com/docs/getstarted/keybindings#_keyboard-shortcuts-reference). +VS Code, while not perfect by any means, has an extensive set of keyboard shortcuts. Throughout this article we've tried to include useful ones where possible, but you can find more comprehensive lists at the VS Code [Keyboard Shortcuts Reference](https://code.visualstudio.com/docs/configure/keybindings). In general, if you want to navigate VS Code via the keyboard, you can press the <kbd>Tab</kbd> key to move around different areas of the UI (<kbd>Shift</kbd> + <kbd>Tab</kbd> will move you to a previous tab focus position). If there are multiple buttons in a tab focus position, you can use the cursor keys to move between them. @@ -177,6 +176,8 @@ On Windows computers, you might have trouble seeing the extensions of some files As you follow this course, you'll notice that we always ask you to name folders and files completely in lowercase with no spaces. There are many ways in which using spaces in file and folder names creates issues — some of the more common ones are as follows: +<!-- cSpell:ignore myimage --> + 1. Many computer systems, including most web servers, are case-sensitive. So for example, if you put an image on your website at `test-site/images/MyImage.jpg` and then in a different file you try to reference the image with `test-site/images/myimage.jpg`, it may not work. 2. When you invoke commands on the command line, you have to put quotes around file names with spaces in them, otherwise they will be interpreted as two separate items. 3. Some programming languages (for example, Python) do not work well with spaces in file names in certain circumstances (for example, if these files are modules to be imported). @@ -233,6 +234,6 @@ You should see a basic webpage displaying your image! - You can combine these as much as you like, for example `../subfolder/another-subfolder/my-image.jpg`. > [!NOTE] -> The Windows file system tends to use backslashes, not forward slashes, e.g. `C:\Windows`. This doesn't matter in HTML — even if you are developing your website on Windows, you should still use forward slashes in your code. +> The Windows file system tends to use backslashes, not forward slashes, e.g., `C:\Windows`. This doesn't matter in HTML — even if you are developing your website on Windows, you should still use forward slashes in your code. {{PreviousMenuNext("Learn_web_development/Getting_started/Environment_setup/Code_editors", "Learn_web_development/Getting_started/Environment_setup/Command_line", "Learn_web_development/Getting_started/Environment_setup")}} diff --git a/files/en-us/learn_web_development/getting_started/environment_setup/index.md b/files/en-us/learn_web_development/getting_started/environment_setup/index.md index 30b20b54c6c5674..cfd5bf00dcbfe68 100644 --- a/files/en-us/learn_web_development/getting_started/environment_setup/index.md +++ b/files/en-us/learn_web_development/getting_started/environment_setup/index.md @@ -2,10 +2,9 @@ title: Environment Setup slug: Learn_web_development/Getting_started/Environment_setup page-type: landing-page +sidebar: learnsidebar --- -{{LearnSidebar}} - {{NextMenu("Learn_web_development/Getting_started/Environment_setup/Installing_software", "Learn_web_development/Getting_started")}} In the _Environment setup_ module, we show you what tools you need to do simple web development and how to install them properly and help you understand important aspects of your environment such as file systems and the command line. @@ -20,7 +19,7 @@ This module assumes no prior technical knowledge, beyond basic computer usage. Y If you need to refresh yourself on such basics, we'd recommend the following resources depending on what operating system you are using: -- [Windows help and learning](https://support.microsoft.com/windows), Microsoft (2024) +- [Windows help and learning](https://support.microsoft.com/en-us/windows), Microsoft (2024) - [macOS User Guide](https://support.apple.com/guide/mac-help/welcome/mac), Apple (2024) - [Official Ubuntu documentation](https://help.ubuntu.com/), ubuntu.com (2024) @@ -36,5 +35,3 @@ If you need to refresh yourself on such basics, we'd recommend the following res - : This article discusses some issues you should be aware of with file systems so you can set up a sensible file structure for your website. - [Command line crash course](/en-US/docs/Learn_web_development/Getting_started/Environment_setup/Command_line) - : This article provides an introduction to the terminal, the essential commands you'll need to enter into it, how to chain commands together, and how to add your own command line interface (CLI) tools. - -## See also diff --git a/files/en-us/learn_web_development/getting_started/environment_setup/installing_software/index.md b/files/en-us/learn_web_development/getting_started/environment_setup/installing_software/index.md index 63e2e66c47cd300..341cc5333a922a4 100644 --- a/files/en-us/learn_web_development/getting_started/environment_setup/installing_software/index.md +++ b/files/en-us/learn_web_development/getting_started/environment_setup/installing_software/index.md @@ -1,11 +1,11 @@ --- title: Installing basic software +short-title: Installing software slug: Learn_web_development/Getting_started/Environment_setup/Installing_software page-type: tutorial-chapter +sidebar: learnsidebar --- -{{LearnSidebar}} - {{NextMenu("Learn_web_development/Getting_started/Environment_setup/Browsing_the_web", "Learn_web_development/Getting_started/Environment_setup")}} In this article, we discuss what software you need to do simple web development and what you need to install now, including a code editor and some modern web browsers. @@ -47,11 +47,11 @@ Having modern web browsers available to you is essential for web development so For now, you should install a couple of desktop and mobile/alternative device browsers to test your code in. You'll most commonly come across web browsers on desktop, laptop, and mobile devices, but you will also come across web browsers on other devices such as tablets, watches, and TVs. If possible, make sure you have one browser from each line installed and available to test on (so you don't just test in multiple browsers based on the same rendering engine): - Desktop browsers: - - Chromium: [Google Chrome](https://www.google.com/chrome/), [Opera](https://www.opera.com/browsers/opera), [Brave](https://brave.com/download/), [Microsoft Edge](https://www.microsoft.com/en-us/edge), [Vivaldi](https://vivaldi.com/). + - Chromium: [Google Chrome](https://www.google.com/chrome/), [Opera](https://www.opera.com/opera), [Brave](https://brave.com/download/), [Microsoft Edge](https://www.microsoft.com/en-us/edge), [Vivaldi](https://vivaldi.com/). - Gecko: [Mozilla Firefox](https://www.mozilla.org/en-US/firefox/new/). - WebKit: [Apple Safari](https://www.apple.com/safari/). - Mobile/alternative device browsers: - - Chromium (Android): [Google Chrome](https://www.google.com/chrome/go-mobile/), [Opera](https://www.opera.com/browsers/opera), [Brave](https://brave.com/download/), [Microsoft Edge](https://www.microsoft.com/en-us/edge/mobile), [Samsung Internet](https://www.samsung.com/us/support/owners/app/samsung-internet), [Vivaldi](https://vivaldi.com/android/). + - Chromium (Android): [Google Chrome](https://www.google.com/chrome/go-mobile/), [Opera](https://www.opera.com/opera), [Brave](https://brave.com/download/), [Microsoft Edge](https://www.microsoft.com/en-us/edge/mobile), [Samsung Internet](https://www.samsung.com/us/support/owners/app/samsung-internet), [Vivaldi](https://vivaldi.com/android/). - Gecko (Android): [Mozilla Firefox](https://www.mozilla.org/en-US/firefox/browsers/mobile/android/). - WebKit (iOS): [Apple Safari](https://www.apple.com/safari/). > [!NOTE] @@ -71,7 +71,7 @@ One of the easiest options we've found to make a local server available is to us 4. Press the _Install_ button to install the extension. 5. Now, when you are working on an HTML file in the editor, you should be able to click the "Show Preview" button to open the live example up in a separate tab. -The above option is simple, but not that flexible. In future, you may want to made a more flexible local server option available that can be used to load examples in any browser you have available. For other options (and more background information around why local servers are necessary), see [How do you set up a local testing server?](/en-US/docs/Learn_web_development/Howto/Tools_and_setup/set_up_a_local_testing_server). +The above option is simple, but not that flexible. In the future, you may want to have a more flexible local server option that can be used to load examples in any browser you have. For other options (and more background information around why local servers are necessary), see [How do you set up a local testing server?](/en-US/docs/Learn_web_development/Howto/Tools_and_setup/set_up_a_local_testing_server). ## Graphics editors @@ -87,7 +87,7 @@ For example: - The built-in Windows [Photos app](https://support.microsoft.com/en-gb/windows/manage-photos-and-videos-with-microsoft-photos-app-c0c6422f-d4cb-2e3d-eb65-7069071b2f9b) comes with many similar features. - The [tinypng](https://tinypng.com/) website, provides a free service allowing you to compress PNGs, JPEGs, and more. This is a very common task you'll have to do when preparing assets for use on a website. -If you have more substantial graphics editing/creation needs, you'll want a fully-fledged graphics package. In terms of commercial offerings, [Adobe Photoshop](https://www.adobe.com/products/photoshop.html) has long been the industry standard, and there are also popular relative newcomers such as [Figma](https://www.figma.com/), [Sketch](https://www.sketch.com/), and [Canva](https://www.canva.com). +If you have more substantial graphics editing/creation needs, you'll want a fully-fledged graphics package. In terms of commercial offerings, [Adobe Photoshop](https://www.adobe.com/products/photoshop.html) has long been the industry standard especially for photo editing, while programs like [Sketch](https://www.sketch.com/) are better suited to icon and UI work. There are also popular newcomers such as [Figma](https://www.figma.com/), [The Affinity Suite](https://affinity.serif.com/en-us/), and [Canva](https://www.canva.com/). If your budget is limited, most of the above apps have trials or free modes there are worth exploring. There are also some well-regarded free apps available such as [GIMP](https://www.gimp.org/), [Adobe Express](https://www.adobe.com/express/), and [Paint.NET](https://www.getpaint.net/). diff --git a/files/en-us/learn_web_development/getting_started/index.md b/files/en-us/learn_web_development/getting_started/index.md index 3a9759f48d62151..5b93d1d10f1a568 100644 --- a/files/en-us/learn_web_development/getting_started/index.md +++ b/files/en-us/learn_web_development/getting_started/index.md @@ -2,11 +2,10 @@ title: Getting started modules slug: Learn_web_development/Getting_started page-type: landing-page +sidebar: learnsidebar --- -{{LearnSidebar}} - -Welcome to **Getting started**! If you are a complete beginner (i.e. you've not installed a code editor or written any code yet), then this is the place to be. The Getting started modules take you through installing the software you need, familiarity with your development environment, taking your first stab at building a simple website, and understanding some of the essential concepts surrounding web development. +Welcome to **Getting started**! If you are a complete beginner (i.e., you've not installed a code editor or written any code yet), then this is the place to be. The Getting started modules take you through installing the software you need, familiarity with your development environment, taking your first stab at building a simple website, and understanding some of the essential concepts surrounding web development. ## Prerequisites @@ -24,3 +23,6 @@ There is no prerequisite knowledge for starting this course. Also note that we d - : This module provides recommendations of soft skills you can aim to get better at while learning web development, and which constitute good traits to have when entering the industry. They will help immensely in developing the right attitudes for learning, researching, and collaborating, and increase the chances of getting hired. ## See also + +- [The Frontend Developer Career Path](https://scrimba.com/the-frontend-developer-career-path-c0j?via=mdn) <sup>[_MDN learning partner_](/en-US/docs/MDN/Writing_guidelines/Learning_content#partner_links_and_embeds)</sup> + - : [Scrimba's](https://scrimba.com?via=mdn) _Frontend Developer Career Path_ teaches all you need to know to be a competent front-end web developer, with fun interactive lessons and challenges, knowledgeable teachers, and a supportive community. Go from zero to landing your first front-end job! Many of the course components are available as standalone free versions. diff --git a/files/en-us/learn_web_development/getting_started/soft_skills/collaboration_and_teamwork/index.md b/files/en-us/learn_web_development/getting_started/soft_skills/collaboration_and_teamwork/index.md index e902dfa785a50ea..2cb9c0bf0f79183 100644 --- a/files/en-us/learn_web_development/getting_started/soft_skills/collaboration_and_teamwork/index.md +++ b/files/en-us/learn_web_development/getting_started/soft_skills/collaboration_and_teamwork/index.md @@ -2,10 +2,9 @@ title: Collaboration and teamwork slug: Learn_web_development/Getting_started/Soft_skills/Collaboration_and_teamwork page-type: tutorial-chapter +sidebar: learnsidebar --- -{{LearnSidebar}} - {{PreviousMenuNext("Learn_web_development/Getting_started/Soft_skills/Research_and_learning", "Learn_web_development/Getting_started/Soft_skills/Workflows_and_processes", "Learn_web_development/Getting_started/Soft_skills")}} As a professional in the web industry, you are going to have to work with other people on projects during multiple phases — brainstorming ideas, writing proposals, implementing code, and more. This article looks at how to work together with others. @@ -39,12 +38,38 @@ As a web developer, you'll have to spend a lot of time working with your peers, It is important to treat people with the same level of empathy and respect as you'd wish for. Different people have different requirements emotionally, socially, etc., but at a base level you should be polite, respectful, and cooperative in all engagements. +## Join a community network + +The web industry has a strong sense of community, meaning that you will often interact with people outside your immediate work or study group to discuss topics of interest or solve problems. The web industry has its own online spaces, such as forums (for example, Discord servers), Slack channels, etc. It also has many in-person events, from high-profile conferences to more low-key local meetups. + +You should dive into some of those groups, say hello, get to know people, share resources, ask questions, and offer to help. Getting to know people in the community has a host of advantages — you will: + +- Meet useful contacts who may end up being friends or future colleagues or employers. +- Learn new techniques and technologies and get help with your tech problems. +- Get practice with explaining how code works and answering other people's questions. +- Learn about resources, meetups, and industry news. +- Encounter adverts for jobs. +- Find information about the companies other community members work for, which can also be beneficial for scoping out the job market and figuring out where you'd like to work. + +Here are some initial ideas for how to get involved in some community networks: + +- Do some research in your local area, see what local in-person meetup groups there are, and attend some of them. You can look events up using sites like [Meetup.com](https://www.meetup.com/) or [Eventbrite](https://www.eventbrite.co.uk/). +- Have a look at resources such as [confs.tech](https://confs.tech/) to find tech conferences of interest. If they are out of your price range, try contacting the organizers to see if you could work the conference as a volunteer — you'll still get to attend it and meet lots of people. +- The [freeCodeCamp forums](https://forum.freecodecamp.org/) is another great place to ask and answer questions. +- Check out the [Frontend Developers](https://discord.me/frontenddevelopers) Discord server. +- Hang out on [MDN's Discord server](/discord). +- Join a friendly developer-oriented {{glossary("IRC")}} channel such as [Libera.Chat](https://web.libera.chat/). +- Our learning partner, Scrimba, provides a [strong community and collaboration experience](https://scrimba.com/the-frontend-developer-career-path-c0j/~0xyi?via=mdn) via their Discord server, intending to help their students gain experience in working with others. +- Find web developers on the social networks, see what they are saying, and join in conversations. + +If you are not sure how to participate, you could start off by reading existing threads and observing how experienced folks engage in discussions. + > [!NOTE] -> Most organizations publish a document called the **Code of Conduct** (or **participation guidelines**) that defines their expectations of behavior for people who participate in their project. These guidelines usually include a definition of what is considered unacceptable behavior, the consequences of unacceptable behavior, and how to report unacceptable behavior. For example, MDN is governed by the wider [Mozilla Community Participation Guidelines](https://www.mozilla.org/en-US/about/governance/policies/participation/). +> Most communities publish a document called the **Code of Conduct** (or **participation guidelines**) that defines their expectations of behavior for people who participate in their project. These guidelines usually include a definition of what is considered unacceptable behavior, the consequences of unacceptable behavior, and how to report unacceptable behavior. For example, MDN is governed by the wider [Mozilla Community Participation Guidelines](https://www.mozilla.org/en-US/about/governance/policies/participation/). ## Help others, ask questions -If a colleague is struggling, offer to help them. Web developers who provide help are much more likely to build strong relationships and get help in return. +If a colleague or network contact is struggling, offer to help them. Web developers who provide help are much more likely to build strong relationships and get help in return. - If you've already got some experience in the area they are struggling in, share knowledge or code examples with them. The act of explaining something will improve your understanding as well, helping you to learn too. - If you have an idea of where they might find some useful answers, help them do some research. @@ -52,16 +77,6 @@ If a colleague is struggling, offer to help them. Web developers who provide hel Always err on the side of helping immediate peers, rather than waiting for a teacher or senior dev to go around and help everyone. Less able peers will get help more quickly, and more able peers will become mentors and experience the satisfaction that it brings. -You could also widen the net to outside your peer group. Join a Slack channel, Discord, or a similar space, share resources, and offer to help. - -For example: - -- [Stack Overflow](https://stackoverflow.com/) is a great place to ask questions and answer other people's questions. -- Check out the [Frontend Developers](https://discord.me/frontenddevelopers) Discord server. -- Our learning partner, Scrimba, provides a [strong community and collaboration experience](https://v2.scrimba.com/the-frontend-developer-career-path-c0j/~0xyi?via=mdn) via their Discord server, intending to help their students gain experience in working with others. - -If you are not sure how to participate, you could start off by reading existing threads and observing how experienced folks engage in discussions. - There is an art to asking and answering questions. It is essential to practice asking the right questions to find out what you need to know, and explaining what you are doing when someone else asks you. If you are not great at doing this, ask your peers if you can set up sessions with them, where they ask questions and you explain how your code works, and vice versa. Peer reviews are also a good place to get practice on this ([see below](#teamwork_and_peer_reviews)). @@ -114,7 +129,7 @@ Failure is really only a small step on the road to success. All of the most succ Here are some tips: - Define a safe space/peer group where people are free to ask questions — remember that there are no "stupid questions", only people who fail to question. Foster a culture where peers support each other and failure is not judged harshly. -- Look to your local community and try to find meetup groups with people who can either give you help and advice or are facing the same issues you are and can provide moral support or experiment together with you. +- Look to your network and try to find online or in-person groups who can either give you help and advice or are facing the same issues you are and can provide moral support or experiment together. - (For educators) Set up the marking schemes for your assessments so that you can still get a reasonable number of marks even if you didn't get the correct result provided the process is well documented. Award extra marks for innovation. - Run show 'n' tell or one-on-one sessions part-way through a project with peers and mentors to get feedback and insights into where you are going wrong and get advice on how to get back on the right path. - Run retrospective meetings to analyze projects, look at what didn't go so well, and talk about how to improve things next time. diff --git a/files/en-us/learn_web_development/getting_started/soft_skills/finding_a_job/index.md b/files/en-us/learn_web_development/getting_started/soft_skills/finding_a_job/index.md new file mode 100644 index 000000000000000..89bb2d6183c781f --- /dev/null +++ b/files/en-us/learn_web_development/getting_started/soft_skills/finding_a_job/index.md @@ -0,0 +1,327 @@ +--- +title: Finding a job +slug: Learn_web_development/Getting_started/Soft_skills/Finding_a_job +page-type: tutorial-chapter +sidebar: learnsidebar +--- + +{{PreviousMenuNext("Learn_web_development/Getting_started/Soft_skills/Workflows_and_processes", "Learn_web_development/Core", "Learn_web_development/Getting_started/Soft_skills")}} + +Technical job interviews can be very demanding, and some have quite specific requirements. Finding the right jobs to apply for in the first place can be challenging! This article provides some tips and resources to help with the process from finding potential jobs and applying, to succeeding in interviews. The process outlined below might not work for everyone exactly as-is — you might find that a slightly different approach or order works for you — but most will find it useful. + +> [!NOTE] +> You might not even want to think about what job you want right now; you may just want to concentrate on learning some code. That's fine; you can always return to this article later on, when the time is right. + +<table> + <tbody> + <tr> + <th scope="row">Prerequisites:</th> + <td> + N/A + </td> + </tr> + <tr> + <th scope="row">Learning outcomes:</th> + <td> + <ul> + <li>Deciding what kind of job you want.</li> + <li>Searching for jobs</li> + <li>Developing qualities for that employers look for.</li> + <li>Selling yourself to would-be employers.</li> + <li>Applying for jobs.</li> + <li>Preparing yourself for job interviews.</li> + </ul> + </td> + </tr> + </tbody> +</table> + +## Decide what kind of job you want + +It almost sounds too obvious to write down, but you should think carefully about the kind of job you want before you go out into the job market and start searching. If you don't, you'll probably end up using a scattergun approach that isn't very effective — going for a wide variety of jobs and not making yourself look like the ideal candidate for _any_ of them. + +If you are reading this site, you are probably interested in some kind of web development job. That's fine, but think about it more specifically, and write some ideas down about what you want in the following categories: + +- Exact type of role: Do you want to be more of a: + - Web designer: Use HTML, CSS, and graphics packages to design user interfaces. + - JS developer: Implement functionality using JavaScript and frameworks. + - Developer relations or sales engineer: Talk to customers, get them excited about technology, help them solve problems and develop solutions. + - Technical writer: Write documentation to explain how technology works and how to use it. + - More of an all-round developer. + - Something else? +- Kind of employer: Do you want to work for: + - Yourself, as a contractor, on lots of different projects. + - A design/development agency, again working on lots of different projects. + - A company or corporation, as an in-house developer. + - A not-for-profit, or charity. +- Sector: Do you want to work in: + - Technology. + - Health. + - Finance. + - Charity. + - Music industry. + - etc. +- Work location: Do you want to work + - From home full time. + - In an office. + - In some kind of hybrid setup. + - In the same location all the time, or move around between different areas or countries? + +If you are not sure of the answers to these questions, that's OK. Ask your peers, friends, teachers, or mentor what they are interested in, to get some inspiration, and look around the industry to see what's available. Realistically, many of you will probably start by seeing an interesting job ad or company, then working out how it fits in to the above categories and how to "sell yourself" to that company. + +## Sell yourself + +To get a job, you have to learn how to **sell yourself**, which means making yourself look like a great candidate for the jobs you want. This involves a few different steps, which are described in the sections below. + +### Develop qualities for that employers look for + +As a general point, you should be aware of the attributes that hiring managers look for in a candidate and prepare accordingly. Obviously, you'll need technical skills and other abilities that help you to directly do the task at hand. However, companies also look for "soft skills" that indirectly help you do the job, and also make their employees lives easier and happier while they are at work. We already touched on some of these in our [Collaboration and teamwork](/en-US/docs/Learn_web_development/Getting_started/Soft_skills/Collaboration_and_teamwork) article. + +To summarize, hiring managers will look for: + +- Someone they can get along with. +- A positive attitude, someone who is respectful, empathic, and constructive. +- An open-minded individual who works well in a diverse team with diverse viewpoints. +- Someone that is graceful when a decision does not go their way, and able to align for the greater good. +- A good communicator and relationship builder. +- A tenacious, focused individual with good problem solving skills. + +Think about whether these statements describe you, or not. This could be a useful way to identify some of your weaknesses, meaning that you can take steps to improve them. For example, if you are not good at communication or problem solving, look up some guides or classes to help you improve those skills. Even something informal such as talking to your friends about your work and describing your projects will help you become better at communicating. + +### Create a CV/résumé + +You should create a CV/résumé, which communicates your worth to an employer. There are lots of guides on how to write one on the web, but in brief, they should generally contain the following: + +- Your contact details: Include your name, postal address, phone number, email, and any maybe one more contact method that is important to you and suitable for professional communication. A [LinkedIn profile](#create_a_linkedin_profile) is recommended. +- A summary/personal statement, which describes you in a single sentence. This can be really hard to write — it needs to sound confident but not arrogant, positive but realistic. A good strategy here is to keep it really short and focus on some facts, what you believe in, and what kind of level you are at. For example, a good personal statement for a junior web developer might read some something like this: "Bob Smith is a web developer with 2 years' experience and a great passion for semantics, accessibility, and inclusive design". +- A list of work experiences, each including: + - A date range specifying when you worked there — for example 06/2023–10/2024, or 06/2023–present if you still work there. + - Company and job title. + - A short paragraph or bulleted list describing what you did in that job/internship/etc. Don't describe _everything_, just what you think are useful experiences for selling yourself. +- An education summary, which lists the different qualifications you have, the school you did them at, and the grade you achieved. Include degrees and other higher education, certificates and achievements that are directly relevant to your field (for example, a web development certification or summer school), and perhaps also regular school qualifications that employers often look for (such as English, other languages, and Math). +- A section containing supporting information, such as: + - Links to your [portfolio](#create_a_portfolio). + - Descriptions of any other relevant experience that doesn't fit into the above sections. + - Personal interests — most employers like their employees to be well-rounded and have a life outside work rather than just being corporate robots — whether that's playing music, watching movies, or volunteering at an animal sanctuary. It also helps to create talking points during job interviews. + +Here are some general tips for CV/résumé writing: + +- Make it short and concise: Ideally you want it to fit on 2 sides of A4/letter paper. Hiring managers won't bother to read a long essay describing your skill set. +- Use professional language: Don't use conversational language or slang terms — you need to sound like you are serious about your application. +- Check your writing carefully for spelling and grammatical mistakes: Run it through a service such as [Grammarly](https://www.grammarly.com/) to make sure you don't miss any mistakes and get hints for further improvements. Hiring managers will often discard a CV/résumé that contains a typo — it shows a lack of professionalism and attention to detail. +- Don't necessarily include all of your work experience on your CV/résumé: If you have a lot of experience, just include the most important or significant recent entries. You want to keep it short, but you also don't want to make it look like there are any suspicious gaps in your work history, which hiring managers might question you about. Put your full experience listing on your LinkedIn profile and only include a summary on your CV/résumé. +- Include soft skills: As mentioned in the [Develop qualities for that employers look for](#develop_qualities_for_that_employers_look_for) section, soft skills are important, and they are worth including on your CV/résumé. You should think about which ones are relevant — employers won't be interested in pages of description of how nice you are, but they will be interested to know that you are a good team player, calm under pressure, and have problem solving skills. +- References on request: Employers always require references so they can get a second opinion of you and your skills from someone else. This should ideally be someone you worked with and have a good relationship with, like a previous manager or teacher. If you are not sure who your references are right now, just write "References available on request." at the bottom of your CV/résumé. +- Keep your CV/résumé up-to-date: Check it every year to see if anything new needs to be added, or if you want to remove anything. + +> [!NOTE] +> You should think of your CV/résumé as a general document, and then customize it for individual jobs you go for, in terms of the most suitable work experience and skills for each job. + +### Get some experience + +When you start searching for jobs, you will find yourself in a vicious circle — _you need experience to get a job, but you also need to get a job to get experience._ Don't despair — there are other ways to get experience. Here are some ideas: + +- Contact local business, charities, churches, schools, etc., to see if they want a website, or help updating their existing website. If you are just starting out, you could offer to do it for free, just to get the experience. +- Following on from the previous item, move on to doing some small bits of freelance work, once you feel that you are experienced enough to start charging for your work. You could ask around at local businesses, or find work through dedicated services such as [UpWork](https://www.upwork.com/). +- Build your own hobby projects, for example, your own website to showcase your work, some fun demos and games, or a web app related to a company that you want to work at. + - You could even identify an existing issue on a company's website, fix it, and send them a link to a deployed version of the fix. +- Hang around on forums and help others with their coding problems. (See [Help others, ask questions](/en-US/docs/Learn_web_development/Getting_started/Soft_skills/Collaboration_and_teamwork#help_others_ask_questions).) +- [Contribute to open source projects](/en-US/docs/Learn_web_development/Getting_started/Soft_skills/Collaboration_and_teamwork#participate_in_open_source). + +### Create a portfolio + +Once you've got some relevant experience worth talking about, the next step is to put together a portfolio that you can include on your CV/résumé, and show to employers. The whole idea here is _don't tell me what you can do — show me what you can do_. + +This should include: + +- A nicely-presented landing page to summarize everything. +- A list of websites, apps, and other relevant products that you've worked on. For each one, include a title, thumbnail image, and a description of the project and what you did on it. If you want to say quite a lot about the projects, create a separate page about each one! Include a list of the technologies used to build the project and a link to the source code if you are able to (not all source is open). +- Links to the source code and live demos of your own personal projects and experiments. Each project should include a description of what it does and the technologies used to build it. +- Links to blog posts, writing samples, conference talks, and any other assets you think might help show off your skills. +- A list of contributions you've made to open source projects, stating what the contribution was, how it improved the project, and what technologies were involved. You should include links to the actual changes you made (source code, published documentation, etc.), and a link to the changelog (for example, the GitHub pull request) that proves you did the work. + +Keep your portfolio as highlights of your best work. You want it to be easy to access and look through. Include a few significant items in each section, rather than hundreds of items, otherwise the hiring manager will get bored and move on. A nice clean design will help with the experience, but a complex design might reduce legibility. + +In terms of how to actually publish your portfolio: + +- You should [publish your work](/en-US/docs/Learn_web_development/Getting_started/Soft_skills/Collaboration_and_teamwork#publish_your_work) in publicly-viewable places, such as a GitHub organization for source code, and a blogging platform such as medium (or your own website) for blog posts. +- For source code that is demos or snippets rather than full websites, publish live versions of the code, so that people can easily check out the live result. See [Publishing your website](/en-US/docs/Learn_web_development/Getting_started/Your_first_website/Publishing_your_website) for tips on how to do this. +- In terms of the actual portfolio landing page, you could create a GitHub repo and provide your list of links in a `README.md` file, but this doesn't look particularly great. Much better would be to create a dedicated website to contain your portfolio, with a dedicated [domain name](/en-US/docs/Learn_web_development/Howto/Web_mechanics/What_is_a_domain_name). If you are not great at design work, ask a colleague or friend for some help, perhaps in exchange for doing some coding work for them. + +### Create a LinkedIn profile + +[LinkedIn](https://www.linkedin.com/) is one of the most popular sites in the world for people to find jobs, and for employers to find employees. It is a great place to host an online account of your work experience and skills, which is similar to your CV/résumé, but also different. + +LinkedIn has many useful advantages that allow your profile to work well alongside your CV/résumé. You can: + +- List your full set of experience and skills on there without making your profile look too long. +- Get people to post recommendations. +- Link to the profiles of all your past employers, educational institutions, etc. +- Write posts on it and use it as a blog. +- Actively search for and apply for jobs on it, and get it to send you new job updates based on your skills and interests. +- Connect with contacts to build a network that you can share skills and leads with, which will ultimately help you find jobs. +- Take training courses. + +For these reasons, you should create a profile. Make it look good and sound professional. [Create a good LinkedIn profile](https://www.linkedin.com/help/linkedin/answer/a554351/how-do-i-create-a-good-linkedin-profile-?lang=en) provides some useful tips. + +## Applying for a job + +Let's now look at the process of applying for a job. + +### Job searches + +There are different ways to approach job searches, and a combination often works best: + +- Sign up to sites where jobs are advertised, such as LinkedIn (there will also be specific sites for your locale) and choose to receive regular digests of the jobs that are available. +- Go to your [community networks](/en-US/docs/Learn_web_development/Getting_started/Soft_skills/Collaboration_and_teamwork#join_a_community_network), look for job ads, and ask contacts if they know of any jobs you might be interested in. +- Research the companies you'd like to work for, go to their job pages, and see what's available. +- Attend networking events and job fairs to meet potential employers. + +The ["Decide what kind of job you want" criteria](#decide_what_kind_of_job_you_want) that you created earlier should be useful for narrowing down your lists of what companies you want to work for and what kind of jobs you want to apply for. + +### Before applying + +Before you start applying for a job, there are some useful steps you can take to prepare: + +- Check the job description to make sure it is suitable for you to apply for. For example, you don't want to waste your time applying for a job that specifies working from an office in California full-time if you live in the UK and don't want to relocate. And you won't have the experience to do a senior web developer job if you have only been learning JavaScript for 3 months. + > [!NOTE] + > If you are not sure if you should apply for a job, or want to know if that company has any more suitable jobs available, find the recruiter's contact details and ask them. They may be a useful contact in the future, if not now. +- Try to find some contacts that already work at the company, for example in your community network, or on LinkedIn, and start a conversation with them. Ask them what it is like working for the company, if there is anything specific you need to do the job, and if they have any other jobs coming up in the near future that might be more suitable. Avoid contacting too many people that work at the same company, but instead choose one or two people you think are the closest to the role you're applying for. +- Do some other research on the company — read their websites/blogs, find out about their history and what their goals are. Spend some time using their products and becoming familiar with how they work — for example install their software and use it to build a demo app, or write a website that uses their APIs to do something. + > [!NOTE] + > For bonus points, try to identify a problem they are currently trying to solve or a bug in their product, and suggest a fix for it along with a demo or code snippets. +- Customize your CV/résumé to suit this particular job. Look at the job description and make sure to amplify your most relevant skills and work experience, while minimizing or even removing items that don't seem relevant. Also make sure the demos/examples most relevant to this job are highlighted on your portfolio in some way, for example put at the top of the list. + +### Applying for the job + +When you apply for the job, make sure you follow the process exactly as they want you to. Each job advert will have instructions on how to apply. If the job ad was more of a conversation with a network contact, ask them exactly how to apply. + +Above all: + +- Make sure your application is professional and well-written, and doesn't include any typos. If it is poorly-written, you are unlikely to succeed. Check it over using a tool like Grammarly. +- Don't be late applying — make sure you submit your application by the deadline date! + +Not all job applications require the same things; you'll probably have to: + +- Fill out some details on an online form. Make sure you type out your answers locally (for example, in VSCode) or in an online document (for example, a Google doc) before entering them into the form fields, in case something (for example, a browser crash) causes you to lose your work. This can save hours of frustration, and text is also easier to review and get feedback on if you put it somewhere else first. +- Upload your CV/résumé. +- Write and upload a covering letter. There are many guides to writing effective covering letters elsewhere online, but in general, such a letter should provide a description of why you: + - Want to work for the company. + - Would be a good culture fit. + - Are perfectly suited to doing the job. +- Provide some examples of your previous work in a separate section. + +### Constant process + +A key point is that your job search should be a constant process where you do a little bit each day, and constantly keep working towards your goal. Don't just fire off a whole load of applications and then sit around waiting for a response. + +You should follow up with any promising leads you meet, for example on community networks or LinkedIn. Also, keep an inventory of the people you meet and the companies you apply to, along with contact details and descriptions of each. Periodically follow up with companies you'd like to work for to see what jobs they have available. If you get rejected for one job, they might have something else more suitable for you, either now or in the future. + +If you haven't had a response from a company after applying for one of their jobs, wait a little while and then followup with their recruiter to see if they have any feedback for you, or any other jobs coming up. Even if a company you want to work for doesn't have any suitable full-time jobs advertised at the moment, contact them any way and see if they are looking for someone with your skill set. It might lead to some useful experience, such as a freelance contract. + +Keep looking for more jobs via your chosen job sites or community networks, and chat to people about what is available. New opportunities will come up all the time. + +If you are struggling to find anything permanent that you really want, there might be some intermediate steps to take: + +- Sometimes a good strategy is to get a job adjacent to the one you want. You might have to get a lower-ranking job to begin with, to get the required experience for the job you really want, either in terms of the specific technology stack used, or the particular industry you want to work in. +- You might have to get some freelance/contract work to keep paying the rent while you continue your job search. This will also give you useful experience that will help you get the job you are after. + +## Preparing yourself for job interviews + +If the recruiter and hiring manager like your application, they will invite you to some interviews and other sessions. This section provides some advice on preparing for those. + +There are some general things you should do to prepare for _any_ interview: + +- Make sure you have a tidy, quiet place for conducting the interviews in. You want to make sure that you are not distracted by noise and commotion during the interview, and you want to make sure that your surroundings look tidy during the interview. If you are having a video call with the interviewer(s) and your space is a complete mess, it won't give them a good impression. +- Think about what you are going to wear when you do your interviews. Most developer jobs don't require you to wear a suit (check the job ad to see if it has anything about a dress code), but you should choose something fairly neutral and smart-_ish_. Don't wear a t-shirt with an offensive slogan on it, and don't turn up in your pyjamas. +- Do some [preparation for coding interviews](#coding_interviews). +- Build a collection of anecdotes to use for [experience-based interview questions](#experience-based_questions). +- Think about what your strengths and weaknesses are, and be realistic with your answers. You will seem more plausible if you don't present yourself as perfect in every way, and interviewers will commonly ask you about your biggest strength and weakness. +- Do some research into what the typical salary ranges and other benefits (such as health insurance or bonuses) are for the kind of job you are going for (level, geographical region, etc.) This will be useful when [deciding whether to accept a job offer](#accepting_the_offer). + +There is also some preparation to do specific to each company you apply to: + +- As we mentioned earlier, you should do some research into the company's history, goals, and products. + - Read about the company from a high level, and familiarize yourself with their recent news. One good reason to do this is to see if they have done anything that would raise red flags and make you reconsider working there. + - Find out about the company's market position and what _their_ strengths and weaknesses are. + - Research who their main competitors are. + - Become familiar with their products and how they work — for example, install their software and use it to build a demo app, or write a website that uses their APIs to do something. It will impress your interviewers if you can demonstrate some good insights around their situation and how you think it could be improved. Interviewers will often ask some specific questions to test your knowledge of the company and industry it exists in. +- Related to the above point, think of some questions you would ask the interviewers about the company and their roles. Interviewers always ask if you have any questions for them at the end of the interview, and it reflects well on you and makes you sound thoughtful and inquisitive if you come out with some questions more meaningful than "what did you have for breakfast today?" +- If you have contacts at the company (from your community networks, etc.), reach out to them and ask about the job. What do they think about it, is there anything specific you should focus on, say, or not say? It might also help, during the interview, to mention that you know "Bob from the e-commerce team" (or whatever). + +### Initial screening + +Once the company have looked at your application and decided you sound like a "potential", they will probably start off by inviting you to an initial phone interview, just with the recruiter or hiring manager. This is usually a short interview to assess "culture fit" (are you going to get on well with them?), make sure they don't pick up any immediate red flags that suggest you won't be a good employee, and tell you about what to expect from the rest of the interview process. + +At this stage, you should be friendly and talkative, but don't talk too much, act naturally, and see where the interviewer steers the conversation. Make sure to let them know what days and times will be suitable for you to attend further interviews. Try to be as flexible as you can, and be prepared to move your schedule around to accommodate them. + +Don't be complacent however — you don't know for definite what questions they will throw at you at this early stage, and you should treat it just as seriously as all the other stages. + +### The main interview + +Usually, the bulk of the interview process is one or more main interviews. These can vary greatly between different companies in function and frequency. + +- You might have one main interview, but you are more likely to have multiple interviews that test you on different aspects of the job (for example, the actual coding work, teamwork, working processes, documentation/communication, conflict resolution). +- They may be with a single interviewer, or multiple interviewers asking you questions about different aspects (aka a panel interview). +- Some interviews may be high level or more exploratory (for example, "describe the process you'd use to deliver x", or "what do you think the main problems are with this solution?") and some may be lower level and more intensive (for example "write a JavaScript program that solves this problem"). + +#### Experience-based questions + +Interviews will inevitably feature experience-based questions. These ask you to provide anecdotes demonstrating that you have experience relevant to the job, and will be along these lines: + +- "Give me an example of a situation in which you had to deliver some negative feedback to a colleague about their code. How did you handle it?" +- "Tell me about a time when you discovered partway through a project that your chosen approach wasn't going to work. How did you address that, and what steps did you take?" +- "Fixing minor bugs can often be hard to fit into a team's work process — often, the pile gets neglected and builds up. How have you dealt with this on past teams?" + +You should build up a set of anecdotes that you can use when answering such questions. This will get easier over time as you get more experience. + +#### Coding interviews + +Some interviews will be coding interviews, designed to test your ability at solving coding problems. These might be something like: + +- "Write a JavaScript function that takes inputs x and y, and returns z." +- "A colleague has written the following React component, but it has some bugs. Can you identify what's wrong with it, and rewrite it to fix the problems?" +- "Look at the following code, and describe to me what it is doing." +- "Write an algorithm that generates the first n entries in the fibonacci sequence." + +Often employers are looking at how you approach the problem rather than the end result — how you commented your code, how you dealt with error handling, and what you might have done if you'd had more time. + +You should research common coding interview question types, practice solving them, and practice explaining what they are doing. You'll find many resources online for practicing coding interview questions. + +#### Homework questions + +Some companies will set homework for an interview candidate to do, as an alternative or additional way of testing your coding ability. This tends to be in the form of a mini-project of some kind, which will ask you to code some functionality relevant to the job you are applying for. For example, you might be asked to create a standalone demo that uses the company's JavaScript library to pull data from their APIs and populate a page of information. + +While this is a reasonable way to test candidates if done right, many people dislike the practice of setting homework questions: + +- Sometimes they can feel a little too much like "real work", almost like the employer is asking you to do work for free. +- They can be poorly scoped, or expect an unreasonable time commitment. A specific scope that time-boxes the project to four hours and will handle follow-up questions in an separate interview is reasonable, but an expectation to spend an entire weekend on a project is not, especially for people who have families and busy lives. +- Their effectiveness is often disputed, as they are hard to evaluate conclusively. + +If you are asked to do a homework challenge, make sure the scope and timing of the work are clearly defined, to mitigate the risk of going in the wrong direction and wasting your time. + +### Accepting the offer + +If you make it through the interview process and get offered the job, then well done! It is tempting to immediately accept the offer, but there are a few things to bear in mind before you do: + +- Make sure the salary you are being offered is reasonable compared to the typical market rate for similar jobs. If it is significantly less, you might want to negotiate. +- Check that leaving your current job (or other activity) is compatible with starting the new job. For example, check how much notice your current employer wants you to work, and make sure this works for the new job. +- You should also let the employer know about preexisting commitments you have outside work, such as a booked vacation. Respectable employers will work around such commitments, and agree a start date that suits you. +- If you need to move house/relocate to take the new job, make sure that you've got everything in place for the move to work out. Starting a new job is stressful enough without the added stress of house moving difficulties. + +## Try, try, and try again + +If you have applied for lots of jobs and not gotten anything yet, try not to become disheartened. Keep trying, keep passionate about the web, and keep talking to new people and learning new things. + +If you got to the interview stage but got rejected, ask the recruiter for some feedback on why you weren't chosen, and use it to improve future applications. + +Be patient. Even the best candidates will get rejections from multiple job applications before they land the job they want. You will get there. + +## See also + +- [Getting hired](https://scrimba.com/the-frontend-developer-career-path-c0j/~0156?via=mdn), Scrimba <sup>Course Partner</sup> +- [Technical Interviewing 101: Ultimate Guide to Acing Your Tech Interview](https://learntocodewith.me/posts/technical-interview/), learntocodewith.me (2022) +- [30 Technical Interview Questions and Tips for Answering](https://www.coursera.org/articles/technical-interview-questions), Coursera (2023) +- [How to land your first developer job](/en-US/blog/how-to-land-your-first-developer-job), MDN Blog, 2024 + +{{PreviousMenuNext("Learn_web_development/Getting_started/Soft_skills/Workflows_and_processes", "Learn_web_development/Core", "Learn_web_development/Getting_started/Soft_skills")}} diff --git a/files/en-us/learn_web_development/getting_started/soft_skills/index.md b/files/en-us/learn_web_development/getting_started/soft_skills/index.md index c2cdf40b7eb28c8..4cf46c7293f2f94 100644 --- a/files/en-us/learn_web_development/getting_started/soft_skills/index.md +++ b/files/en-us/learn_web_development/getting_started/soft_skills/index.md @@ -2,10 +2,9 @@ title: Soft skills slug: Learn_web_development/Getting_started/Soft_skills page-type: landing-page +sidebar: learnsidebar --- -{{LearnSidebar}} - {{PreviousMenuNext("Learn_web_development/Getting_started/Web_standards/How_browsers_load_websites", "Learn_web_development/Getting_started/Soft_skills/Research_and_learning", "Learn_web_development/Getting_started")}} This module provides recommendations of soft skills you can aim to get better at while learning web development, and which constitute good traits to have when entering the industry. They will help immensely in developing the right attitudes for learning, researching, and collaborating, and increase the chances of getting hired. @@ -22,7 +21,7 @@ This module is mainly theoretical, and assumes no specific practical knowledge o - : As a professional in the web industry, you are going to have to work with other people on projects during multiple phases — brainstorming ideas, writing proposals, implementing code, and more. This article looks at how to work together with others. - [Workflows and processes](/en-US/docs/Learn_web_development/Getting_started/Soft_skills/Workflows_and_processes) - : Beginners often focus on specific individual aspects of technology, but miss out on the bigger picture of an overall project. This article provides some of that high-level context. -- [Succeeding in job interviews](/en-US/docs/Learn_web_development/Getting_started/Soft_skills/Job_interviews) - - : Technical job interviews can be very demanding, and some have quite specific requirements. Finding the right jobs to apply for in the first place can be challenging! This job provides some tips and resources to help. +- [Finding a job](/en-US/docs/Learn_web_development/Getting_started/Soft_skills/Finding_a_job) + - : Technical job interviews can be very demanding, and some have quite specific requirements. Finding the right jobs to apply for in the first place can be challenging! This article provides some tips and resources to help with the process from finding potential jobs and applying, to succeeding in interviews. {{PreviousMenuNext("Learn_web_development/Getting_started/Web_standards/How_browsers_load_websites", "Learn_web_development/Getting_started/Soft_skills/Research_and_learning", "Learn_web_development/Getting_started")}} diff --git a/files/en-us/learn_web_development/getting_started/soft_skills/job_interviews/index.md b/files/en-us/learn_web_development/getting_started/soft_skills/job_interviews/index.md deleted file mode 100644 index f2b7855d10ccd21..000000000000000 --- a/files/en-us/learn_web_development/getting_started/soft_skills/job_interviews/index.md +++ /dev/null @@ -1,82 +0,0 @@ ---- -title: Succeeding in job interviews -slug: Learn_web_development/Getting_started/Soft_skills/Job_interviews -page-type: tutorial-chapter ---- - -{{LearnSidebar}} - -{{PreviousMenuNext("Learn_web_development/Getting_started/Soft_skills/Workflows_and_processes", "Learn_web_development/Core", "Learn_web_development/Getting_started/Soft_skills")}} - -> [!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. - -Technical job interviews can be very demanding, and some have quite specific requirements. Finding the right jobs to apply for in the first place can be challenging! This job provides some tips and resources to help. - -<table> - <tbody> - <tr> - <th scope="row">Prerequisites:</th> - <td> - N/A - </td> - </tr> - <tr> - <th scope="row">Learning outcomes:</th> - <td> - <ul> - <li>Effective strategies for job searching.</li> - <li>Developing qualities for that employers look for.</li> - <li>Selling yourself to would-be employers.</li> - <li>Preparing yourself for job interviews.</li> - </ul> - </td> - </tr> - </tbody> -</table> - -## Effective strategies for job searching - -- Learn effective strategies for job searching. For example: -- Attend networking events and job fairs to meet potential employers. -- Keep an inventory of the people you meet and the companies you apply to. -- Follow up with any promising leads you meet. - -## Developing qualities for that employers look for - -Be aware of the attributes that hiring managers look for in a candidate and prepare accordingly: - -- Someone they can get along with. -- Positive attitude, respectful, empathic, constructive. -- Open-minded and works well in a diverse team with diverse viewpoints. -- Graceful when a decision does not go their way, able to align for the greater good. -- Good communicator and relationship builder. -- Tenacious, focused, good problem solver. -- Having a good portfolio. - -## Finding work experience - -TODO - -## Selling yourself to would-be employers - -- Create a portfolio. -- Build the perfect résumé. -- Get experience — build real projects and contribute to open source. -- Build your online persona. -- Use sites like [LinkedIn](https://www.linkedin.com/) to help with the above. - -## Preparing yourself for job interviews - -- Be aware of the kinds of questions and tests you will come across. -- Practice writing answers for coding and design interview questions. -- Build a collection of anecdotes to use for experience-based interview questions. -- Be patient. Even the best candidates will get rejections from multiple job applications before they land the job they want. - -## See also - -- [Getting hired](https://v2.scrimba.com/the-frontend-developer-career-path-c0j/~0156?via=mdn), Scrimba <sup>Course Partner</sup> -- [Technical Interviewing 101: Ultimate Guide to Acing Your Tech Interview](https://learntocodewith.me/posts/technical-interview/), learntocodewith.me (2022) -- [30 Technical Interview Questions and Tips for Answering](https://www.coursera.org/articles/technical-interview-questions), Coursera (2023) - -{{PreviousMenuNext("Learn_web_development/Getting_started/Soft_skills/Workflows_and_processes", "Learn_web_development/Core", "Learn_web_development/Getting_started/Soft_skills")}} diff --git a/files/en-us/learn_web_development/getting_started/soft_skills/research_and_learning/index.md b/files/en-us/learn_web_development/getting_started/soft_skills/research_and_learning/index.md index 2440dd24d5555a4..02827434ca9c928 100644 --- a/files/en-us/learn_web_development/getting_started/soft_skills/research_and_learning/index.md +++ b/files/en-us/learn_web_development/getting_started/soft_skills/research_and_learning/index.md @@ -2,10 +2,9 @@ title: Research and learning slug: Learn_web_development/Getting_started/Soft_skills/Research_and_learning page-type: tutorial-chapter +sidebar: learnsidebar --- -{{LearnSidebar}} - {{NextMenu("Learn_web_development/Getting_started/Soft_skills/Collaboration_and_teamwork", "Learn_web_development/Getting_started/Soft_skills")}} There is a lot to know as a web developer, and you are constantly learning. But how do you find out what you need to know most effectively? This article provides useful tips on research and learning. @@ -48,7 +47,7 @@ You should make sure that the resources you choose for research are high quality - [Scrimba](https://scrimba.com/?via=mdn) <sup>Course partner</sup> - [YouTube](https://www.youtube.com/) - [freeCodeCamp](https://www.freecodecamp.org/) -- [Codecademy](https://www.codecademy.com) +- [Codecademy](https://www.codecademy.com/) - [Dev.to](https://dev.to/) ### Learn what resources to use and when @@ -77,7 +76,7 @@ If you can't find a solution to your problem on your favorite sites, you'll need - Check the dates on the resources you find. Are they recently maintained, or not updated for some time and, therefore, possibly out-of-date? Reputable sites tend to include publication and "last-updated" dates on them, precisely so you can easily check this. Ideally, an article from a reputable site covering a modern technology or technique shouldn't be left unmaintained for longer than a few years (say 2–3). It is perfectly possible that older documentation covering a mature technology (for example, fundamental HTML or CSS features) can still be accurate, but you should keep this in mind. - As a follow-on from the previous point, even newly-published resources can contain out-of-date information. For example, does an article on CSS page layout talk about modern approaches like grid and flexbox, or does it still present obsolete techniques like using floats to create multi-column layouts? - Don't just rely on one single source of truth. Cross-reference different sources, especially if you are not sure whether a source is trustworthy or not. -- You can also try using AI to help with coding issues (for example [ChatGPT](https://openai.com/blog/chatgpt) or [GitHub Copilot](https://resources.github.com/copilot-for-business/)). You should use AI tools with caution (especially as a beginner), and familiarize yourself with their strengths and weaknesses: +- You can also try using AI to help with coding issues (for example [ChatGPT](https://openai.com/index/chatgpt) or [GitHub Copilot](https://github.com/features/copilot/copilot-business)). You should use AI tools with caution (especially as a beginner), and familiarize yourself with their strengths and weaknesses: - On the plus side, they can speed up research/searches enormously, and help with structuring code and copy. - On the other hand, AI tools have no reasoning skills and frequently provide answers that are misleading or just plain wrong. You shouldn't just assume that AI answers are correct — test them, and verify them with other sources. @@ -95,7 +94,7 @@ The advice here is that if you are going to use a solution from somewhere else, We've talked enough about websites, so now we'll talk about people. And websites. -Building a network of folks to collaborate with is an essential part of being a web developer. We'll talk about this in greater detail in [Collaboration and teamwork](/en-US/docs/Learn_web_development/Getting_started/Soft_skills/Collaboration_and_teamwork), but for now, let's concentrate specifically on using your network to help with research. +Building a network of folks to collaborate with is an essential part of being a web developer. We'll also talk about this in [Collaboration and teamwork](/en-US/docs/Learn_web_development/Getting_started/Soft_skills/Collaboration_and_teamwork#join_a_community_network); here we'll concentrate specifically on using your network to help with research. An effective research network consists of several groups of people with different levels of knowledge and proximity to you: @@ -109,7 +108,7 @@ An effective research network consists of several groups of people with differen - Ask them how they would prefer to communicate with you about the problem, to make the interaction as comfortable for them as possible. - If arranging a meeting, don't book more of their time than you need. If you are not sure how long you will need, timebox the session to say 30 minutes. You can always ask them for more help in the future. -- Wider community network: This could consist of a dedicated online community such as forums or chat groups (for example the [The MDN Web Docs discord](/discord) or the [freeCodeCamp forums](https://forum.freecodecamp.org/)), or a physical meetup such as a conference or skillshare event (you can look events up using sites like [Meetup.com](https://www.meetup.com/) or [Eventbrite](https://www.eventbrite.co.uk)). +- Wider community network: This could consist of a dedicated online community such as forums or chat groups (for example the [The MDN Web Docs discord](/discord) or the [freeCodeCamp forums](https://forum.freecodecamp.org/)), or a physical meetup such as a conference or skill-share event. - Global network: Sometimes you might be out of options, in which case you could try asking your question on a general global community like a social media network. Sometimes helpful answers can come from unexpected places. > [!NOTE] @@ -194,7 +193,7 @@ We also recommend taking a proper 15-minute break every hour to 90 minutes. While you are on your break, try discussing your issue with a colleague, friend, or family member. Even if they can't provide you with the answer, the chances are that you'll find a solution on your own by reasoning the problem in your own head. It even works when you explain the problem out loud, to yourself or to an inanimate object. -This technique is known as [rubber duck debugging](https://rubberduckdebugging.com/) (or [rubber ducking](https://wikipedia.org/wiki/Rubber_duck_debugging)), named because traditionally the idea was that you explain your coding problem to a rubber duck. +This technique is known as [rubber duck debugging](https://rubberduckdebugging.com/) (or [rubber ducking](https://en.wikipedia.org/wiki/Rubber_duck_debugging)), named because traditionally the idea was that you explain your coding problem to a rubber duck. ## Effective problem-solving diff --git a/files/en-us/learn_web_development/getting_started/soft_skills/workflows_and_processes/index.md b/files/en-us/learn_web_development/getting_started/soft_skills/workflows_and_processes/index.md index 3eed48eb8d113ff..10564571e660820 100644 --- a/files/en-us/learn_web_development/getting_started/soft_skills/workflows_and_processes/index.md +++ b/files/en-us/learn_web_development/getting_started/soft_skills/workflows_and_processes/index.md @@ -2,16 +2,12 @@ title: Workflows and processes slug: Learn_web_development/Getting_started/Soft_skills/Workflows_and_processes page-type: tutorial-chapter +sidebar: learnsidebar --- -{{LearnSidebar}} +{{PreviousMenuNext("Learn_web_development/Getting_started/Soft_skills/Collaboration_and_teamwork", "Learn_web_development/Getting_started/Soft_skills/Finding_a_job", "Learn_web_development/Getting_started/Soft_skills")}} -{{PreviousMenuNext("Learn_web_development/Getting_started/Soft_skills/Collaboration_and_teamwork", "Learn_web_development/Getting_started/Soft_skills/Job_interviews", "Learn_web_development/Getting_started/Soft_skills")}} - -> [!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. - -Beginners often focus on specific individual aspects of technology, but miss out on the bigger picture of an overall project. This article provides some of that high-level context. +An important aspect of technical projects that beginners often miss out on is an idea of the bigger picture. They might learn an individual tool or language, but be unaware of all the libraries, tools, systems, and job roles that go together to deliver an entire web application. The following sections cover different big picture aspects at a high level. <table> <tbody> @@ -25,38 +21,172 @@ Beginners often focus on specific individual aspects of technology, but miss out <th scope="row">Learning outcomes:</th> <td> <ul> - <li>Typical technology combinations and application architectures in common web projects.</li> - <li>Typical processes for a technical project, including where different tools are used in those processes.</li> - <li>Typical job roles, and where they are involved in those processes.</li> - <li>Common work management styles, such as agile and waterfall.</li> + <li>Typical technology combinations in web projects.</li> + <li>Typical job roles on a web development team.</li> + <li>Typical technical project phases, and where the different job roles are involved.</li> + <li>Common work management processes, such as agile and waterfall.</li> </ul> </td> </tr> </tbody> </table> -An important aspect of technical projects that beginners often miss out on is an idea of the bigger picture of a project. They might learn an individual tool or language and understand what they need to do, but be unaware of all the other codebases, tools, systems, and job roles that go together to deliver an entire web application. The following sections cover different big picture aspects. +## Typical technology combinations + +When building a website, you will use a combination of different technologies, commonly referred to as a **tech stack**. As websites get larger and more complex, so does the tech stack. It might start off simple when you are creating a demo and only you and a few colleagues will be looking at it. However, a seemingly-simple production website's tech stack could be more complex than you first think when you consider that it needs to: + +- Load quickly (this is the purpose of [performance](/en-US/docs/Learn_web_development/Extensions/Performance/why_web_performance)). +- Handle a large number of users simultaneously (it must **scale**). +- Be well-designed, so that users can easily access the information and services it contains. +- Be easy for a team to work on and maintain. + +At a very high level, a web application tech stack might look something like this: + +```plain +Front-end +HTML, CSS, JavaScript +| +Back-end +Node.js, .NET, PHP, Python, or some other server-side language +| +Database +MySQL, Postgres, MongoDB, or some other database +| +Web server +Your own, built around a server product such as Apache, or a service like Netlify +``` + +> [!NOTE] +> You will often see acronyms that refer to poplar tech stacks, such as [MEAN](https://www.mongodb.com/resources/languages/mean-stack) (MongoDB, Express, Angular, Node) or [LAMP](<https://en.wikipedia.org/wiki/LAMP_(software_bundle)>) (Linux, Apache, MySQL, PHP or Python). + +On MDN, we are mainly concerned with the front-end part, but even that can be broken down into lots of different pieces. Take the front-end for example: + +- You will probably use a JavaScript framework (such as [React](/en-US/docs/Learn_web_development/Core/Frameworks_libraries/React_getting_started)) to define the components that go together to create the user interface. +- The framework will probably use some kind of templating language (such as [Mustache](https://mustache.github.io/)) to define the HTML structure but also provide functionality to dynamically include variable content. +- You will include information to style your content via CSS in a way that is compatible with the framework. This might written in pure CSS, or a CSS framework (such as [Tailwind](https://tailwindcss.com/)) or preprocessor (such as [Sass](https://sass-lang.com/)). +- A JavaScript project should include tests, to make sure that any new code additions don't break its functionality. Tests are usually implemented using a testing framework (like [Jest](https://jestjs.io/)). +- Larger websites will use a packaging/build tool (such as [Parcel](https://parceljs.org/)) to improve performance by keeping file sizes down, removing unused components from the production code, etc. +- And so on. + +> [!NOTE] +> You will often hear websites and applications described as being built using specific **architectural patterns**. For example, [model-view-controller (MVC)](https://en.wikipedia.org/wiki/Model%E2%80%93view%E2%80%93controller) is a pattern that many JavaScript frameworks follow, while [publish–subscribe (pub/sub)](https://dev.to/willvelida/the-publisher-subscriber-pattern-pubsub-messaging-10in) is commonly used by messaging applications. It is not especially important that you understand these patterns in detail, but some familiarity can be useful when trying to understand a new framework or tool. + +There will also be tools involved outside the actual tech stack itself to help you manage it or create assets for the website, such as: + +- Planning tools to help you plan what you are going to do throughout the course of the project at a high level (such as [Miro](https://miro.com/)). +- Version control systems (VCS). You will probably use a [git](https://git-scm.com/)-based VCS, such as [GitHub](https://github.com/). +- Graphics/interface design packages (such as [Figma](https://www.figma.com/) or [Canva](https://www.canva.com/)). +- Project management tools such as [Trello](https://trello.com/) or [Asana](https://asana.com/). + +OK, so that is a lot to take in. Our advice is **don't panic!** The aim of this article is not to worry you by making you think that all of a sudden you have 10 times as many things to learn as you did before. The idea is simply to make you aware of the bigger picture in terms of website projects, and give you a basic familiarity with some of the terms you might encounter. + +Eventually, you will develop some knowledge of several of the above tools and technologies, but you won't be an expert in them all, nor will you need to be — that's what teams are for. For the moment, you are absolutely doing the right thing by learning the core skills such as HTML, CSS, and JavaScript. More tools, and specializations, will come later on in your career. + +## Job roles + +In a web development team, there are many different job roles involved; it is useful to understand what each one entails: + +- **Product manager** + - : Responsible for the whole website from a product perspective — how is the product performing in the market, compared to its competitors? What are its strengths and weaknesses? What new features is the target audience asking for, and which ones are the highest priority? What are the website's main success criteria, and how did recent new features help meet those criteria? The product manager will collect data and write reports to help the team understand how effective their work is, and prioritize future work. +- **Project manager** + - : Responsible for organizing the work the team needs to do. The project manager will create a project plan with prioritized tasks and due dates, assign personnel to do each task, hold regular check-in meetings to see if progress targets are being met and surface any problems, and adjust the plan as needed. +- **User experience (UX) designer** + - : Responsible for understanding the needs of the product's target audience, and designing the product workflow/experience so that those audience needs are met most effectively. Typical UX questions are "where should we direct the user first when they land on our homepage?" and "how can we make signing up for an account as easy and intuitive as possible?" This work is often coupled with user research and testing to better understand the target audience, and creating wireframes to communicate ideas. The UX designer is one of the main consumers of the product manager's reports. +- **Graphic designer** + - : Responsible for visual design work on the website project. Graphic designers are responsible for a variety of disciplines such as typography, choosing color schemes, creating icons and other graphic assets, and creating website mockups based on the UX designer's wireframes. +- **Front-end developer** + - : This is (probably) what you are aiming to be if you are reading this! Front-end developers use HTML, CSS, and JavaScript to create the visual part of the website that users interact with, bringing to life the behavioral and visual mockups created by the UX and graphic designers. +- **Back-end developer** + - : Responsible for the non-visual parts of the website. They write back-end code to request internal data, generate HTML pages from templates, and process external data submitted by users. They also handle web server configuration, keeping the site secure, etc. +- **Full-stack developer** + - : Handles both front-end development and back-end development tasks. +- **Quality assurance (QA) engineer** + - : Responsible for testing new features to make sure they work properly and reporting bugs, communicating with the developers to help them prioritize the necessary fixes. +- **Content specialist/technical writer** + - : Responsible for making sure the textual content of the website works as well as it can for the target audience. This includes the structure of the information and how it is navigated, the user interface text labels, blog posts, marketing text, and product documentation. + +### Less common job roles + +Other less common job roles include: + +- **User researcher** + - : Larger teams will often have a dedicated researcher to do user research and testing. +- **Search Engine Optimization (SEO) specialist** + - : Analyses the content and structure of the website and makes changes that will cause the website to be more visible in relevant search engine results. See {{glossary("SEO")}} for more information. + +## Technical project phases + +A typical technical project might happen like this: + +1. The product manager identifies a new set of user requirements for the website. +2. They discuss it with the team, and it is decided that these requirements can be met by adding a new feature to the website. +3. The project manager discusses with the team what the required individual work items are for creating the new feature, and creates a [work process to manage them](#work_management_processes). +4. The UX designer designs a workflow for the new feature that describes how it should work, and a wireframe to provide an idea of where it might fit on the site. +5. The graphic designer designs a mockup showing what the feature will look like on the website, along with the chosen fonts and color palette. +6. The content specialist writes the UI text required by the feature, and the documentation required to support it. +7. The back-end developer creates the necessary systems to securely store and handle the data that powers the feature. +8. The front-end developer creates the interactive feature based on the graphic designer's mockups and connects it to the back-end so that it retrieves the data it needs. +9. The QA engineer thoroughly tests the new feature, and writes a detailed report on the issues they find with it. +10. The developers fix the bugs that are deemed sufficiently serious that they should block the release of the feature. +11. Once the (blocking) bugs are fixed and the project is signed off, the feature can be put live on the website. + +This is a simplified view — other phases will exist around the feature implementation itself, and the phases will not necessarily all be completed in the order shown, but this gives you an idea of what's involved. + +## Work management processes + +The project manager will use some kind of process to manage the website project, monitoring progress on the different work items, making sure they get done in the right order and on time, etc. The two main process types are: + +- **Waterfall** + - : Refers to running a project in clear, fixed phases, where each one is dependent on the previous one, and not too many changes in requirements are anticipated. Generally a single large result is delivered at the end of the project. Management of the team tends to be more bureaucratic, with less autonomy. + - Waterfall projects tend to be better specified at the start and have less scope creep (adding requirements mid-project). In addition, larger, less frequent product releases are easier to handle in terms of release planning, marketing, delivering training and documentation, etc. + - However, waterfall tends to be less flexible, and changes happen much more slowly. Waiting several months for a bug fix can be frustrating. +- **Agile** + - : Refers to running a project more flexibly, where multiple phases can progress simultaneously, and multiple smaller results tend to be delivered at various different milestones throughout the project. Changes in requirements are expected and can be handled by shifting priorities as required. Teams are generally more autonomous. + - Agile projects are flexible and can adapt more easily to changes in requirements. It can also be nice to have more frequent releases — bugs get fixed more quickly, innovation happens more often, and there is always something for the marketing team to talk about. Agile teams often talk about continuous improvement. + - However, there is more risk of scope creep and deadline slippage, projects often never feel truly finished, and there is more of a constant pace and pressure to deliver. + +> [!NOTE] +> Web development teams often prefer to work with an agile process, as software development is by its very nature prone to (sometimes rapid) changes in requirements due to new bugs, user feedback, company strategy, etc. -## Typical technology combinations and application architectures +### Scrum and kanban -TODO +There is a specific type of agile methodology called **scrum**, which has a fixed set of rules about how a project is run. For example: -## Typical processes for a technical project +- The person in charge of the scrum is called the scrum master. This is quite often just the project manager with a different name. +- The work to do is divided into cycles, called **sprints**, which are typically two weeks long. +- Before each sprint, potential new work items are discussed, and if accepted into the sprint, they are put into a backlog. +- Work items are taken from the backlog and move through different phases towards completion, such as "in progress" and "in review". +- The scrum master holds short daily **stand-up meetings** where everyone talks about the progress they've made and any issues they might be having, so problems can be caught early. +- At end of each sprint, the scrum master holds a retrospective meeting to review what went well, what didn't go so well, and what lessons can be learnt before the next sprint. -TODO +Another type of agile methodology is called **kanban**, which has less rules than scrum, doesn't use sprints, and tends to focus more on the continuous improvement aspects of agile. Kanban is particularly useful for managing continuous processes that don't have a clear defined end, such as customer support tickets. -## Typical job roles +### Kanban boards -TODO +Tools such as [Trello](https://trello.com/) and [Asana](https://asana.com/) provide visualizations that show the status of different work items in a project. They are usually called **Kanban boards**, although they can be used to manage different process types, not just kanban. Kanban boards consist of different columns, which can represent different work statuses in a scrum project ("backlog", "todo", "in progress", etc.), different types of work ("research", "design", "development", etc.) or whatever else is useful for your project. -## Common work management styles +[GitHub Projects](https://docs.github.com/en/issues/planning-and-tracking-with-projects/learning-about-projects/about-projects) provide another good tooling option, and are free to use — you just need to sign up for a GitHub account. -TODO +> [!CALLOUT] +> +> **Try it out** +> +> You should read up on the above processes, and practice tracking some of your work or personal projects using a kanban board. Don't worry about using a complex scrum methodology; basic kanban is fine for the moment. Even if you're doing something solo, it can be great to practice the workflow of: +> +> 1. Creating tasks. +> 2. Deciding how big they are or how long they will take. +> 3. Prioritizing tasks. +> 4. Putting them in order with due dates. +> 5. Starting to work on different tasks. +> 6. Setting their statuses ("in progress", "blocked", "done", etc.) as the work progresses. +> +> Track the progress of a complete project from start to finish — try it with your own website or a side project of some kind. Also, try [contributing to an open source project](/en-US/docs/Learn_web_development/Getting_started/Soft_skills/Collaboration_and_teamwork#participate_in_open_source) or two; many of them will use a process to track their work similar to what we have described above. ## See also -- [What is a Tech Stack and How Do They Work?](https://www.mongodb.com/basics/technology-stack), mongodb.com +- [What is a Tech Stack and How Do They Work?](https://www.mongodb.com/resources/basics/technology-stack), mongodb.com - [Website development team structure: roles and processes](https://www.truemark.dev/blog/web-development-team-structure-role-process/), truemark.dev (2017) -- [Waterfall vs. Agile vs. Kanban vs. Scrum: What's the difference?](https://asana.com/resources/waterfall-agile-kanban-scrum), Asana (2022) +- [Agile vs. Waterfall](https://www.productplan.com/learn/agile-vs-waterfall/), ProductPlan +- [What is Scrum?](https://www.scrum.org/learning-series/what-is-scrum/), scrum.org -{{PreviousMenuNext("Learn_web_development/Getting_started/Soft_skills/Collaboration_and_teamwork", "Learn_web_development/Getting_started/Soft_skills/Job_interviews", "Learn_web_development/Getting_started/Soft_skills")}} +{{PreviousMenuNext("Learn_web_development/Getting_started/Soft_skills/Collaboration_and_teamwork", "Learn_web_development/Getting_started/Soft_skills/Finding_a_job", "Learn_web_development/Getting_started/Soft_skills")}} diff --git a/files/en-us/learn_web_development/getting_started/web_standards/how_browsers_load_websites/index.md b/files/en-us/learn_web_development/getting_started/web_standards/how_browsers_load_websites/index.md index ac974c2a238a36c..ef306035c3185ec 100644 --- a/files/en-us/learn_web_development/getting_started/web_standards/how_browsers_load_websites/index.md +++ b/files/en-us/learn_web_development/getting_started/web_standards/how_browsers_load_websites/index.md @@ -2,10 +2,9 @@ title: How browsers load websites slug: Learn_web_development/Getting_started/Web_standards/How_browsers_load_websites page-type: tutorial-chapter +sidebar: learnsidebar --- -{{LearnSidebar}} - {{PreviousMenuNext("Learn_web_development/Getting_started/Web_standards/The_web_standards_model", "Learn_web_development/Getting_started/Soft_skills", "Learn_web_development/Getting_started/Web_standards")}} In the previous article, we looked at an [overview of the technologies](/en-US/docs/Learn_web_development/Getting_started/Web_standards/The_web_standards_model#overview_of_modern_web_technologies) that websites are built from. In this article we walk through the process by which those technologies are rendered — when a browser has received the code files and other assets that make up a web page (as covered in [How the web works](/en-US/docs/Learn_web_development/Getting_started/Web_standards/How_the_web_works)), how are they put together to create the finished experience that the user interacts with? @@ -45,7 +44,7 @@ To summarize the [overview of web technologies](/en-US/docs/Learn_web_developmen When the user navigates to a new web page (by clicking a link, or entering a web address in the browser address bar), several HTTP requests are sent, and several files are sent back in HTTP responses. The files received in these responses are processed by the browser and put together into a web page that the user can interact with. This process of assembling the pieces into a web page is called **rendering**. -The below sections provide a high-level explanation of how a browser renders a web page. Bear in mind that this is a very simplified description, and that different browsers will handle the process in different ways. However, this will still give you an idea of the basics behind how things work. +The following sections provide a high-level explanation of how a browser renders a web page. Keep in mind that this is a simplified description, and that different browsers will handle the process in different ways. However, this will still give you an idea of how things work. ## Handling HTML @@ -60,7 +59,7 @@ To start with, the HTML file that contains the web page content and defines its </p> ``` -Each element, attribute, and piece of text in the HTML becomes a **DOM node** in the tree structure. The nodes are defined by their relationship to other DOM nodes. Some elements are parents of child nodes, and child nodes have siblings. The browser would parse the above HTML and create the following DOM tree from it: +Each element, attribute, and piece of text in the HTML becomes a **DOM node** in the tree structure. The nodes are defined by their relationship to other DOM nodes. Some elements are parents of child nodes, and child nodes have siblings. The browser will parse this HTML and create the following DOM tree from it: ```plain P @@ -73,7 +72,7 @@ P └─ "JavaScript" ``` -In the DOM, the node corresponding to our `<p>` element is a parent. Its children are a text node and the three nodes corresponding to our `<span>` elements. The `SPAN` nodes are also parents, with text nodes as their children. When the browser renders the above DOM tree, it will look like so: +In this DOM tree, the node corresponding to our `<p>` element is a parent. Its children include a text node and the three nodes corresponding to our `<span>` elements. The `SPAN` nodes are also parents, with text nodes as their children. When the browser renders this DOM tree, it will look like so: {{EmbedLiveSample('Handling the HTML', '100%', 55)}} diff --git a/files/en-us/learn_web_development/getting_started/web_standards/how_the_web_works/index.md b/files/en-us/learn_web_development/getting_started/web_standards/how_the_web_works/index.md index 20cc0ee7790f2d4..895d556ed913e7e 100644 --- a/files/en-us/learn_web_development/getting_started/web_standards/how_the_web_works/index.md +++ b/files/en-us/learn_web_development/getting_started/web_standards/how_the_web_works/index.md @@ -2,10 +2,9 @@ title: How the web works slug: Learn_web_development/Getting_started/Web_standards/How_the_web_works page-type: tutorial-chapter +sidebar: learnsidebar --- -{{LearnSidebar}} - {{NextMenu("Learn_web_development/Getting_started/Web_standards/The_Web_standards_model", "Learn_web_development/Getting_started/Web_standards")}} _How the web works_ provides a high-level description of what happens when you use a web browser to navigate to a web page, explaining the magic that goes on behind the scenes to deliver the relevant code to your computer for the browser to assemble into something you can look at. @@ -31,7 +30,7 @@ This theory is not essential to writing web code in the short term, but before l <li>DNS and how it works at a high level.</li> <li>The purpose of TCP/IP, HTTP, and packets.</li> <li>HTTP syntax at a basic level.</li> - <li>Common HTTP response codes (e.g. 200, 301, 403, 404, and 500).</li> + <li>Common HTTP response codes (e.g., 200, 301, 403, 404, and 500).</li> <li>Basic components of a URL (protocol, domain, subdomain, path).</li> </ul> </td> @@ -106,7 +105,7 @@ Basically, when data is sent across the web, it is sent in thousands of small ch ## HTTP basics -HTTP uses a simple language of verbs to perform actions such as making requests (see [HTTP request methods](/en-US/docs/Web/HTTP/Methods)). The HTTP [`GET`](/en-US/docs/Web/HTTP/Methods/GET) method is the one normally used to make HTTP requests of the type described above. For example, a request for the MDN home page might look like this: +HTTP uses a simple language of verbs to perform actions such as making requests (see [HTTP request methods](/en-US/docs/Web/HTTP/Reference/Methods)). The HTTP [`GET`](/en-US/docs/Web/HTTP/Reference/Methods/GET) method is the one normally used to make HTTP requests of the type described above. For example, a request for the MDN home page might look like this: ```http GET /en-US/ HTTP/2 @@ -133,18 +132,18 @@ content-type: text/html The full response is more complex than this, but we have omitted most of it for brevity. The main parts are as follows: - `HTTP/2 200` - - : The version of HTTP that the server is using to send the response, in this case HTTP/2, followed by a [status code](/en-US/docs/Web/HTTP/Status) indicating whether the request was successful. `200` indicates success. + - : The version of HTTP that the server is using to send the response, in this case HTTP/2, followed by a [status code](/en-US/docs/Web/HTTP/Reference/Status) indicating whether the request was successful. `200` indicates success. - `date`, `expires`, etc. - - : [HTTP headers](/en-US/docs/Web/HTTP/Headers) containing additional information about the response (note that requests can have headers too), which provide extra information and/or modify its behavior. + - : [HTTP headers](/en-US/docs/Web/HTTP/Reference/Headers) containing additional information about the response (note that requests can have headers too), which provide extra information and/or modify its behavior. - `<!doctype html>`, etc. - : The response body, which in this case contains the MDN homepage's HTML document. > [!NOTE] -> See the MDN [HTTP reference](/en-US/docs/Web/HTTP) for a lot more detail on HTTP, if you are curious. [An overview of HTTP](/en-US/docs/Web/HTTP/Overview) is a good place to start. +> See the MDN [HTTP reference](/en-US/docs/Web/HTTP) for a lot more detail on HTTP, if you are curious. [An overview of HTTP](/en-US/docs/Web/HTTP/Guides/Overview) is a good place to start. ### Other status codes -Above, we met the `200` [status code](/en-US/docs/Web/HTTP/Status), which indicates that the HTTP request was successful. There are many HTTP status codes with specific meanings and uses, but you will only commonly see a few: +Above, we met the `200` [status code](/en-US/docs/Web/HTTP/Reference/Status), which indicates that the HTTP request was successful. There are many HTTP status codes with specific meanings and uses, but you will only commonly see a few: - `301` - : The requested resource has been permanently moved to a new location, which is provided in the response. This is used for redirecting content when it's moved. @@ -172,7 +171,7 @@ The main parts of the URL are: - `https` - : The **protocol** being used to send the request. In this case, we are using [HTTPS](/en-US/docs/Glossary/HTTPS), which is a secure version of HTTP that stops bad people from reading your data while it is being transported. On the modern web, pretty much every server uses HTTPS, so if you don't include it explicitly, the browser assumes that is what you are using and adds it for you. - `developer.mozilla.org` - - : The [**domain name**](/en-US/docs/Learn_web_development/Howto/Web_mechanics/What_is_a_domain_name) of the URL, which represents the top-level location of the server you are connecting to. In this case, the web address you typed in is equal to the domain name, but this is not always the case — you could choose to type in a more complicated web address. Note that the `developer` part is a **subdomain** (distinct content area) of Mozilla's `mozilla.org` domain. There are other subdomains on Mozilla's site that host distinct content — see [support.mozilla.org](https://support.mozilla.org) and [bugzilla.mozilla.org](https://bugzilla.mozilla.org), for example. + - : The [**domain name**](/en-US/docs/Learn_web_development/Howto/Web_mechanics/What_is_a_domain_name) of the URL, which represents the top-level location of the server you are connecting to. In this case, the web address you typed in is equal to the domain name, but this is not always the case — you could choose to type in a more complicated web address. Note that the `developer` part is a **subdomain** (distinct content area) of Mozilla's `mozilla.org` domain. There are other subdomains on Mozilla's site that host distinct content — see [support.mozilla.org](https://support.mozilla.org/) and [bugzilla.mozilla.org](https://bugzilla.mozilla.org/), for example. - `/en-US/` - : The **path** to the resource on the server that you are accessing. MDN keeps all its US English content in a folder called `en-US`, which is what this URL is pointing to. diff --git a/files/en-us/learn_web_development/getting_started/web_standards/index.md b/files/en-us/learn_web_development/getting_started/web_standards/index.md index 43a53fc8293ea02..48cfb71df88579a 100644 --- a/files/en-us/learn_web_development/getting_started/web_standards/index.md +++ b/files/en-us/learn_web_development/getting_started/web_standards/index.md @@ -2,10 +2,9 @@ title: Web standards slug: Learn_web_development/Getting_started/Web_standards page-type: landing-page +sidebar: learnsidebar --- -{{LearnSidebar}} - {{PreviousMenuNext("Learn_web_development/Getting_started/Your_first_website/Publishing_your_website", "Learn_web_development/Getting_started/Web_standards/How_the_web_works", "Learn_web_development/Getting_started")}} This module covers the fundamentals of how the web works at a high level — including the model used for communication, the core technologies involved, how those technologies are created, and how a web browser renders and displays websites to a user. 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 4bbb41f13abe8ef..d9c479fd240e6e9 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 @@ -2,10 +2,9 @@ title: The web standards model slug: Learn_web_development/Getting_started/Web_standards/The_web_standards_model page-type: tutorial-chapter +sidebar: learnsidebar --- -{{LearnSidebar}} - {{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")}} 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. @@ -104,7 +103,7 @@ 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 **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. +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 are 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 money, and those costs would then be passed on to the browser users. 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. @@ -177,7 +176,7 @@ pElem.textContent = "We changed the text!"; 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. -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. +For example, writing your own interface to communicate with your webcam and capture a video stream from it would be quite difficult, 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. 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. diff --git a/files/en-us/learn_web_development/getting_started/your_first_website/adding_interactivity/index.md b/files/en-us/learn_web_development/getting_started/your_first_website/adding_interactivity/index.md index 49982759229fc24..bf4332dd07cc582 100644 --- a/files/en-us/learn_web_development/getting_started/your_first_website/adding_interactivity/index.md +++ b/files/en-us/learn_web_development/getting_started/your_first_website/adding_interactivity/index.md @@ -1,14 +1,14 @@ --- title: "JavaScript: Adding interactivity" +short-title: Adding interactivity slug: Learn_web_development/Getting_started/Your_first_website/Adding_interactivity page-type: tutorial-chapter +sidebar: learnsidebar --- -{{LearnSidebar}} - {{PreviousMenuNext("Learn_web_development/Getting_started/Your_first_website/Styling_the_content", "Learn_web_development/Getting_started/Your_first_website/Publishing_your_website", "Learn_web_development/Getting_started/Your_first_website")}} -JavaScript is a programming language that adds interactivity to websites. This happens in games, in the behavior of responses when buttons are pressed or with data entry on forms, with dynamic styling, with animation, etc. This article helps you get started with JavaScript and furthers your understanding of what is possible. +JavaScript is a programming language that adds interactivity to websites. You can use it to control just about anything — form data validation, button functionality, game logic, dynamic styling, animation updates, and much more. This article gets you started with JavaScript and walks you through adding some fun features to your first website. <table> <tbody> @@ -23,7 +23,7 @@ JavaScript is a programming language that adds interactivity to websites. This h <td> <ul> <li>The purpose and function of JavaScript.</li> - <li>JavaScript language fundamentals such as variables, operators, conditionals, functions, and events.</li> + <li>A basic understanding of JavaScript language fundamentals such as variables, operators, conditionals, functions, and events.</li> </ul> </td> </tr> @@ -32,45 +32,84 @@ JavaScript is a programming language that adds interactivity to websites. This h ## What is JavaScript? -{{Glossary("JavaScript")}} is a powerful programming language that can add interactivity to a website. -It was invented by Brendan Eich. +{{Glossary("JavaScript")}} is a full-fledged programming language — it contains all the classic programming features you may have seen in other programming languages (or at least heard about), such as **variables**, **loops**, and **functions**. + +JavaScript, when used on web pages (though it can also be used in other places), generally works by: + +- Getting references to one or more values such as numbers or to elements on the page. +- Doing something with those values, such as adding the numbers together. +- Returning a result that can be used to do something else later on. For example, you might want to display the sum of those numbers on the page. + +Let's look at an example. We'll use the same basic list we saw in the last couple of articles: + +```html live-sample___basic-js +<p>Instructions for life:</p> + +<ul> + <li>Eat</li> + <li>Sleep</li> + <li>Repeat</li> +</ul> +``` + +We'll also define a CSS class called `.done` that will style any element it's applied to, making it look like a completed task with green text color and a strikethrough. We'll apply it to our `<li>` elements using JavaScript in the next step. + +```css live-sample___basic-js +.done { + color: darkseagreen; + text-decoration: line-through solid black 2px; +} +``` + +Now on to the JavaScript. Here, we first store references to the `<li>` elements inside a variable called `listItems`. We then define a function called `toggleDone()` that adds the `done` class to a list item if it doesn't already have it, and removes the class if it does. Finally, we loop through the list items (using `forEach()`) and add an event listener (using `addEventListener()`) to each list item so that when it is clicked, the `done` class is toggled, applying the CSS we defined earlier. -JavaScript is versatile and beginner-friendly. -With more experience, you'll be able to create games, animated 2D and 3D graphics, comprehensive database-driven apps, and much more! +```js live-sample___basic-js +const listItems = document.querySelectorAll("li"); -JavaScript itself is relatively compact, yet very flexible. Developers have written a variety of tools on top of the core JavaScript language, unlocking a vast amount of functionality with minimum effort. These include: +function toggleDone(e) { + if (!e.target.className) { + e.target.className = "done"; + } else { + e.target.className = ""; + } +} -- Browser Application Programming Interfaces ({{Glossary("API","APIs")}}) built into web browsers, providing functionality such as dynamically creating HTML and setting CSS styles, collecting and manipulating a video stream from a user's webcam, or generating 3D graphics and audio samples. -- Third-party APIs that allow developers to incorporate functionality in sites from other content providers, such as YouTube or Facebook. -- Third-party frameworks and libraries that you can apply to HTML to accelerate the work of building sites and applications. +listItems.forEach((item) => { + item.addEventListener("click", toggleDone); +}); +``` -It's outside the scope of this article—as a light introduction to JavaScript—to present the details of how the core JavaScript language is different from the tools listed above. You can learn more in our [Core modules](/en-US/docs/Learn_web_development/Core), as well as in other parts of MDN. +Don't worry if you don't understand the above JavaScript now. Getting comfortable with JavaScript is more challenging than getting comfortable with HTML and CSS, but things will become clearer later on in the course. -The section below introduces some aspects of the core language and offers an opportunity to play with a few browser API features too. Have fun! +This example will render as follows in a web browser: -## A "Hello world!" example +{{EmbedLiveSample("basic-js", "100%", "140px")}} -JavaScript is one of the most popular modern web technologies! As your JavaScript skills grow, your websites will enter a new dimension of power and creativity. +Try clicking the list items a few times and note how the "done" styles are toggled on and off as a result. Not that bad for 11 lines of JavaScript. -However, getting comfortable with JavaScript is more challenging than getting comfortable with HTML and CSS. You should start small, and progress gradually. To begin, let's examine how to add JavaScript to your page for creating a _Hello world!_ example. (_Hello world!_ is [the standard for introductory programming examples](https://en.wikipedia.org/wiki/%22Hello,_World!%22_program).) +## A "Hello world!" walkthrough + +To start you off with writing some JavaScript, we'll walk you through adding a _Hello world!_ example to your sample website. ([_Hello world!_](https://en.wikipedia.org/wiki/%22Hello,_World!%22_program) is the standard introductory programming example.) > [!WARNING] > If you haven't been following along with the rest of our course, [download this example code](https://codeload.github.com/mdn/beginner-html-site-styled/zip/refs/heads/gh-pages) and use it as a starting point. -1. Inside your `first-website` folder, create a new folder named `scripts`. +1. Inside your `first-website` folder or the example folder you have just downloaded, create a new folder named `scripts`. 2. Within the `scripts` folder, create a new text document called `main.js`, and save it. -3. Go to your `index.html` file and enter this code on a new line, just before the closing `</body>` tag: +3. Go to your `index.html` file and enter this code on a new line, just before the closing `</head>` tag: ```html - <script src="scripts/main.js"></script> + <script async src="scripts/main.js"></script> ``` - This is doing the same job as the {{htmlelement("link")}} element for CSS. It applies the JavaScript to the page, so it can have an effect on the HTML (along with the CSS, and anything else on the page). + This does the same job as the {{htmlelement("link")}} element for CSS – it applies the JavaScript to the page so it can affect the HTML (along with the CSS and anything else on the page). 4. Add this code to your `scripts/main.js` file: ```js + // Store a reference to the <h1> in a variable const myHeading = document.querySelector("h1"); + // Update the text content of the <h1> myHeading.textContent = "Hello world!"; ``` @@ -78,313 +117,24 @@ However, getting comfortable with JavaScript is more challenging than getting co ![Heading "hello world" above a firefox logo](hello-world.png) -> [!NOTE] -> The reason the above instructions place the {{htmlelement("script")}} element near the bottom of the HTML file is that **the browser reads code in the order it appears in the file**. -> -> If the JavaScript loads first and it is supposed to affect the HTML that hasn't loaded yet, there could be problems. Placing JavaScript near the bottom of an HTML page is one way to accommodate this dependency. +Let's break down how this example works. -### What happened? +We used JavaScript to change the heading text to `Hello world!`. We grabbed a reference to the heading and stored it in a variable called `myHeading` (a container that stores a value). This is similar to how you apply CSS to elements – you first select the elements you want to affect using a CSS selector, and then define the styles you want for those elements. In both cases, when you want to do something to an element, you need to select it first. -We have used JavaScript to change the heading text to _Hello world!_. We did this by using a function called {{domxref("Document.querySelector", "querySelector()")}} to grab a reference to your heading, and then store it in a variable called `myHeading`. This is similar to what we did using CSS selectors. When you want to do something to an element, you need to select it first. +Following that, we set the value of the `myHeading` variable's `textContent` property (which represents the `<h1>` element's text content) to _Hello world!_. -Following that, the code set the value of the `myHeading` variable's {{domxref("Node.textContent", "textContent")}} property (which represents the content of the heading) to _Hello world!_. - -> [!NOTE] -> Both of the features you used in this exercise are parts of the [Document Object Model (DOM) API](/en-US/docs/Web/API/Document_Object_Model), which has the capability to manipulate documents. +The lines that start with `//` are JavaScript comments. In the same way as HTML and CSS comments, the browser ignores these, providing a way for you to add notes about your code to help explain how it works. -## Language basics crash course - -To give you a better understanding of how JavaScript works, let's explain some of the core features of the language. It's worth noting that these features are common to all programming languages. If you master these fundamentals, you have a head start on coding in other languages too! +Let's move on and add some new features to our example site. > [!WARNING] -> In this article, try entering the example code lines into your JavaScript console to see what happens. For more details on JavaScript consoles, see [Discover browser developer tools](/en-US/docs/Learn_web_development/Howto/Tools_and_setup/What_are_browser_developer_tools). - -### Variables - -{{Glossary("Variable", "Variables")}} are containers that store values. You start by declaring a variable with the [`let`](/en-US/docs/Web/JavaScript/Reference/Statements/let) keyword, followed by the name you give to the variable: - -```js -let myVariable; -``` - -A semicolon at the end of a line indicates where a statement ends. It is only required when you need to separate statements on a single line. However, some people believe it's good practice to have semicolons at the end of each statement. There are other rules for when you should and shouldn't use semicolons. For more details, see [Your Guide to Semicolons in JavaScript](https://www.codecademy.com/resources/blog/your-guide-to-semicolons-in-javascript/). - -You can name a variable nearly anything, but there are some restrictions. (See [this section about naming rules](/en-US/docs/Web/JavaScript/Guide/Grammar_and_types#variables).) If you are unsure, you can [check your variable name](https://mothereff.in/js-variables) to see if it's valid. - -JavaScript is case sensitive. This means `myVariable` is not the same as `myvariable`. If you have problems in your code, check the case! - -After declaring a variable, you can give it a value: - -```js -myVariable = "Bob"; -``` - -Also, you can do both these operations on the same line: - -```js -let myVariable = "Bob"; -``` - -You retrieve the value by calling the variable name: - -```js -myVariable; -``` - -After assigning a value to a variable, you can change it later in the code: - -```js -let myVariable = "Bob"; -myVariable = "Steve"; -``` - -Note that variables may hold values that have different [data types](/en-US/docs/Web/JavaScript/Data_structures): - -<table class="standard-table"> - <thead> - <tr> - <th scope="row">Variable</th> - <th scope="col">Explanation</th> - <th scope="col">Example</th> - </tr> - </thead> - <tbody> - <tr> - <th scope="row">{{Glossary("String")}}</th> - <td> - This is a sequence of text known as a string. To signify that the value - is a string, enclose it in single or double quote marks. - </td> - <td><code>let myVariable = 'Bob';</code> or <br/><code>let myVariable = "Bob";</code></td> - </tr> - <tr> - <th scope="row">{{Glossary("Number")}}</th> - <td>This is a number. Numbers don't have quotes around them.</td> - <td><code>let myVariable = 10;</code></td> - </tr> - <tr> - <th scope="row">{{Glossary("Boolean")}}</th> - <td> - This is a True/False value. The words <code>true</code> and - <code>false</code> are special keywords that don't need quote marks. - </td> - <td><code>let myVariable = true;</code></td> - </tr> - <tr> - <th scope="row">{{Glossary("Array")}}</th> - <td> - This is a structure that allows you to store multiple values in a single - reference. - </td> - <td> - <code>let myVariable = [1,'Bob','Steve',10];</code><br />Refer to each - member of the array like this:<br /><code>myVariable[0]</code>, - <code>myVariable[1]</code>, etc. - </td> - </tr> - <tr> - <th scope="row">{{Glossary("Object")}}</th> - <td> - This can be anything. Everything in JavaScript is an object and can be - stored in a variable. Keep this in mind as you learn. - </td> - <td> - <code>let myVariable = document.querySelector('h1');</code><br />All of - the above examples too. - </td> - </tr> - </tbody> -</table> - -So why do we need variables? Variables are necessary to do anything interesting in programming. If values couldn't change, then you couldn't do anything dynamic, like personalize a greeting message or change an image displayed in an image gallery. - -### Comments - -Comments are snippets of text that can be added along with code. The browser ignores text marked as comments. You can write comments in JavaScript just as you can in CSS: - -```js -/* -Everything in between is a comment. -*/ -``` - -If your comment contains no line breaks, you can put it behind two slashes like this: - -```js -// This is a comment -``` +> Before going any further, delete the "Hello world!" code from your `main.js` file. If you don't, the existing code will clash with the new code you are about to add. -### Operators +## Adding an image changer -An `{{Glossary("operator")}}` is a mathematical symbol that produces a result based on two values (or variables). In the following table, you can see some of the simplest operators, along with some examples to try in the JavaScript console. +In this section, you will use JavaScript and [DOM API](/en-US/docs/Web/API/HTML_DOM_API) features to alternate the display between two images. This change will happen when a user clicks the displayed image. -<table class="standard-table"> - <thead> - <tr> - <th scope="row">Operator</th> - <th scope="col">Explanation</th> - <th scope="col">Symbol(s)</th> - <th scope="col">Example</th> - </tr> - </thead> - <tbody> - <tr> - <th scope="row">Addition</th> - <td>Add two numbers together or combine two strings.</td> - <td><code>+</code></td> - <td> - <code>6 + 9;<br />'Hello ' + 'world!';</code> - </td> - </tr> - <tr> - <th scope="row">Subtraction, Multiplication, Division</th> - <td>These do what you'd expect them to do in basic math.</td> - <td><code>-</code>, <code>*</code>, <code>/</code></td> - <td> - <code ->9 - 3;<br />8 * 2; // multiply in JS is an asterisk<br />9 / 3;</code - > - </td> - </tr> - <tr> - <th scope="row">Assignment</th> - <td>As you've seen already: this assigns a value to a variable.</td> - <td><code>=</code></td> - <td><code>let myVariable = 'Bob';</code></td> - </tr> - <tr> - <th scope="row">Strict equality</th> - <td> - This performs a test to see if two values are equal and of the same data type. It returns a - <code>true</code>/<code>false</code> (Boolean) result. - </td> - <td><a href="/en-US/docs/Web/JavaScript/Reference/Operators/Strict_equality"><code>===</code></a></td> - <td> - <code>let myVariable = 3;<br />myVariable === 4;</code> - </td> - </tr> - <tr> - <th scope="row">Not, Does-not-equal</th> - <td> - This returns the logically opposite value of what it precedes. It turns - a <code>true</code> into a <code>false</code>, etc.. When it is used - alongside the Equality operator, the negation operator tests whether two - values are <em>not</em> equal. - </td> - <td><code>!</code>, <code>!==</code></td> - <td> - <p> - For "Not", the basic expression is <code>true</code>, but the - comparison returns <code>false</code> because we negate it: - </p> - <p> - <code>let myVariable = 3;<br />!(myVariable === 3);</code> - </p> - <p> - "Does-not-equal" gives basically the same result with different - syntax. Here we are testing "is <code>myVariable</code> NOT equal to - 3". This returns <code>false</code> because <code>myVariable</code> IS - equal to 3: - </p> - <p> - <code>let myVariable = 3;<br />myVariable !== 3;</code> - </p> - </td> - </tr> - </tbody> -</table> - -There are a lot more operators to explore, but this is enough for now. See [Expressions and operators](/en-US/docs/Web/JavaScript/Reference/Operators) for a complete list. - -> [!NOTE] -> Mixing data types can lead to some strange results when performing calculations. Be careful that you are referring to your variables correctly, and getting the results you expect. For example, enter `'35' + '25'` into your console. Why don't you get the result you expected? Because the quote marks turn the numbers into strings, so you've ended up concatenating strings rather than adding numbers. If you enter `35 + 25` you'll get the total of the two numbers. - -### Conditionals - -Conditionals are code structures used to test if an expression returns true or not. A very common form of conditionals is the `if...else` statement. For example: - -```js -let iceCream = "chocolate"; -if (iceCream === "chocolate") { - alert("Yay, I love chocolate ice cream!"); -} else { - alert("Awwww, but chocolate is my favorite…"); -} -``` - -The expression inside the `if ()` is the test. This uses the strict equality operator (as described above) to compare the variable `iceCream` with the string `chocolate` to see if the two are equal. If this comparison returns `true`, the first block of code runs. If the comparison is not true, the second block of code—after the `else` keyword—runs instead. - -### Functions - -{{Glossary("Function", "Functions")}} are a way of packaging functionality that you wish to reuse. It's possible to define a body of code as a function that executes when you call the function name in your code. This is a good alternative to repeatedly writing the same code. You have already seen some uses of functions. For example: - -```js -let myVariable = document.querySelector("h1"); -``` - -```js -alert("hello!"); -``` - -The `document.querySelector()` and `alert()` functions are built into the browser. - -If you see something which looks like a variable name, but it's followed by parentheses — `()` — it is likely to be a function. Functions often take {{Glossary("Argument", "arguments")}}: bits of data they need to do their job. Arguments go inside the parentheses, separated by commas if there is more than one argument. - -For example, the `alert()` function makes a pop-up box appear inside the browser window, but we need to give it a string as an argument to tell the function what message to display. - -You can also define your own functions. In the next example, we create a simple function which takes two numbers as arguments and multiplies them: - -```js -function multiply(num1, num2) { - let result = num1 * num2; - return result; -} -``` - -Try running this in the console; then test with several arguments. For example: - -```js -multiply(4, 7); -multiply(20, 20); -multiply(0.5, 3); -``` - -> [!NOTE] -> The [`return`](/en-US/docs/Web/JavaScript/Reference/Statements/return) statement tells the browser to return the `result` variable out of the function so it is available to use. This is necessary because variables defined inside functions are only available inside those functions. This is called variable {{Glossary("Scope", "scoping")}}. (Read more about [variable scoping](/en-US/docs/Web/JavaScript/Guide/Grammar_and_types#variable_scope).) - -### Events - -Real interactivity on a website requires event handlers. These are code structures that listen for activity in the browser, and run code in response. The most obvious example is handling the [click event](/en-US/docs/Web/API/Element/click_event), which is fired by the browser when you click on something with your mouse. To demonstrate this, enter the following into your console, then click on the current webpage: - -```js -document.querySelector("html").addEventListener("click", function () { - alert("Ouch! Stop poking me!"); -}); -``` - -There are a number of ways to attach an event handler to an element. -Here we select the {{htmlelement("html")}} element. We then call its [`addEventListener()`](/en-US/docs/Web/API/EventTarget/addEventListener) function, passing in the name of the event to listen for (`'click'`) and a function to run when the event happens. - -The function we just passed to `addEventListener()` here is called an _anonymous function_, because it doesn't have a name. There's an alternative way of writing anonymous functions, which we call an _arrow function_. -An arrow function uses `() =>` instead of `function ()`: - -```js -document.querySelector("html").addEventListener("click", () => { - alert("Ouch! Stop poking me!"); -}); -``` - -## Supercharging our example website - -With our review of JavaScript basics completed, let's add some new features to our example site. - -Before going any further, delete the current contents of your `main.js` file — the bit you added earlier during the "Hello world!" example — and save the empty file. If you don't, the existing code will clash with the new code you are about to add. - -### Adding an image changer - -In this section, you will learn how to use JavaScript and DOM API features to alternate the display between two images. This change will happen as a user clicks the displayed image. - -1. Choose another image to feature on your example site. Ideally, the image will be the same size as the image you added previously, or as close as possible. +1. Choose another image to feature on your example site. Ideally, the image should be the same size as the one you added previously, or as close as possible. 2. Save this image in your `images` folder. 3. Add the following JavaScript code to your `main.js` file, making sure to replace `firefox2.png` and both instances of `firefox-icon.png` with your second and first image names, respectively. @@ -403,19 +153,27 @@ In this section, you will learn how to use JavaScript and DOM API features to al 4. Save all files and load `index.html` in the browser. Now when you click the image, it should change to the other one. -In the above code, you stored a reference to your {{htmlelement("img")}} element in `myImage`. Next, you gave it a `click` event handler function with no name (an "anonymous" function). Every time this element is clicked, the function: +In this code, you stored a reference to your {{htmlelement("img")}} element in the `myImage` variable. Then you assigned it a `click` event handler function. Every time the `<img>` is clicked, the function does the following: + +- Retrieves the value of the image's `src` attribute. +- Uses a conditional (`if ... else` structure) to check if the `src` value is equal to the path of the original image: -1. Retrieves the value of the image's `src` attribute. -2. Uses a conditional to check if the `src` value is equal to the path of the original image: + - If it is, the code changes the `src` value to the path of the second image, forcing the other image to be loaded inside the `<img>` element. + - If it isn't (meaning the image has already been changed), the `src` value swaps back to the original image path. - 1. If it is, the code changes the `src` value to the path of the second image, forcing the other image to be loaded inside the {{htmlelement("img")}} element. - 2. If it isn't (meaning it must already have changed), the `src` value swaps back to the original image path. +> [!NOTE] +> This section introduces several important terms. Key concepts include: +> +> - [API](/en-US/docs/Glossary/API): A set of features that allows a developer to interact with a programming environment. Web APIs (such as the DOM API features we used above) are built on top of the JavaScript language and allow you to manipulate various parts of the browser and the web pages it displays. +> - [Events](/en-US/docs/Learn_web_development/Core/Scripting/Events): Things that happen in the browser. They're key to making websites interactive. You can run code in response to events using **event handler functions** – these are code blocks that run when an event occurs. The most common example is the [click event](/en-US/docs/Web/API/Element/click_event), which is fired by the browser when a user clicks on something. +> - [Functions](/en-US/docs/Learn_web_development/Core/Scripting/Functions): A way of packaging code that you wish to reuse. You can define your code inside a function once and then run it as many times as you like, which helps you avoid writing the same code over and over. In our example here, we defined a `click` event handler function, which runs every time a user clicks the image. +> - [Conditionals](/en-US/docs/Learn_web_development/Core/Scripting/Conditionals): Code structures used to test if an expression returns `true` or `false` and run different code in response to each result. A very common form of conditionals is the `if...else` statement. -### Adding a personalized welcome message +## Adding a personalized welcome message -Next, let's change the page heading to a personalized welcome message when the user first visits the site. This welcome message will persist. Should the user leave the site and return later, we will save the message using the [Web Storage API](/en-US/docs/Web/API/Web_Storage_API). We will also include an option to change the username, and therefore, the welcome message. +Next, let's change the page heading to show a personalized welcome message when the user first visits the site. This welcome message will be saved in the browser using the [Web Storage API](/en-US/docs/Web/API/Web_Storage_API), so if the user leaves the site and returns later, their personalized data will still be there. We'll also include a way for the user to change the message. -1. In `index.html`, add the following line just before the {{htmlelement("script")}} element: +1. In `index.html`, add the following line just before the closing `</body>` tag: ```html <button>Change user</button> @@ -438,9 +196,13 @@ Next, let's change the page heading to a personalized welcome message when the u } ``` - The `setUserName()` function contains a [`prompt()`](/en-US/docs/Web/API/Window/prompt) function, which displays a dialog box, similar to `alert()`. This `prompt()` function does more than `alert()`, asking the user to enter data, and storing it in a variable after the user clicks _OK_. In this case, we are asking the user to enter a name. Next, the code calls on the `localStorage` API, which allows us to store data in the browser and retrieve it later. We use localStorage's `setItem()` function to create and store a data item called `"name"`, setting its value to the `myName` variable which contains the user's entry for the name. Finally, we set the `textContent` of the heading to a string, plus the user's newly stored name. + The `setUserName()` function contains a [`prompt()`](/en-US/docs/Web/API/Window/prompt) function, which asks the user to enter data and stores it in a variable after they click _OK_. In this example, we're asking the user to enter a name and storing it in `myName`.<br /><br /> -4. Add the following condition block after the function declaration. We could call this initialization code, as it structures the app when it first loads. + Next, the code uses the [Web Storage API](/en-US/docs/Web/API/Web_Storage_API), which allows us to store data in the browser and retrieve it later. We use the {{domxref("Storage.setItem", "localStorage.setItem()")}} function to create and store a data item called `"name"`, setting its value to the `myName` variable, which contains the user's input.<br /><br /> + + Finally, we set the `textContent` of the heading to a string that includes the user's stored name. + +4. Add the following conditional block after the function declaration. This is our _initialization code_ — it runs when the page first loads to start the program off: ```js if (!localStorage.getItem("name")) { @@ -451,9 +213,9 @@ Next, let's change the page heading to a personalized welcome message when the u } ``` - This first line of this block uses the negation operator (logical NOT, represented by the `!`) to check whether the `name` data item is already stored in in localStorage. If not, the `setUserName()` function runs to create it. If it exists (that is, the user set a user name during a previous visit), we retrieve the stored name using `getItem()` and set the `textContent` of the heading to a string, plus the user's name, as we did inside `setUserName()`. + The first line of this block uses the negation operator (logical NOT, represented by the `!` character) to check whether the `name` data item is _not_ already stored in `localStorage`. If not, the `setUserName()` function runs to create it. If it exists (that is, the user set a username during a previous visit), we retrieve the stored name using {{domxref("Storage.getItem", "localStorage.getItem()")}} and set the `textContent` of the heading to a string, plus the user's name – just like we did inside `setUserName()`. -5. Add a `click` event handler function to the button, as shown below. When clicked, `setUserName()` runs. This allows the user to enter a different name by pressing the button. +5. Add a `click` event handler function to the button. When clicked, `setUserName()` runs. This allows the user to store a different name if they want to. ```js myButton.addEventListener("click", () => { @@ -461,13 +223,18 @@ Next, let's change the page heading to a personalized welcome message when the u }); ``` -### A user name of null? +6. Save all files and load `index.html` in the browser. You should immediately be asked to enter your name. After you do so, it will appear inside the `<h1>` as part of the personalized greeting. Notice how the personalization persists even after you reload the page. You can click the "Change user" button to enter a new name. + +> [!NOTE] +> The term [operator](/en-US/docs/Learn_web_development/Core/Scripting/Math) refers to a JavaScript language character that carries out an operation on one or more values. Examples include `+` (adds values), `-` (subtracts one value from another), and `!` (negates a value — as you saw earlier). + +## A user name of null? -When you run the example and get the dialog box that prompts you to enter your user name, try pressing the _Cancel_ button. You should end up with a title that reads _Mozilla is cool, null_. This happens because the value is set as [`null`](/en-US/docs/Web/JavaScript/Reference/Operators/null) when you cancel the prompt. _null_ is a special value in JavaScript that refers to the absence of a value. +When you run the example and get the dialog box that prompts you to enter your name, try pressing the _Cancel_ button. You should end up with a title that reads _Mozilla is cool, null_. This happens because the value is set to [`null`](/en-US/docs/Web/JavaScript/Reference/Operators/null) when you cancel the prompt. In JavaScript, _null_ is a special value that represents the absence of a value. Also, try clicking _OK_ without entering a name. You should end up with a title that reads _Mozilla is cool,_ because you've set `myName` to an empty string. -To avoid these problems, you could check that the user hasn't entered a blank name. Update your `setUserName()` function to this: +To avoid these problems, you can add another conditional to check that the user hasn't entered a blank name. Update your `setUserName()` function to the following: ```js function setUserName() { @@ -491,12 +258,12 @@ If you have followed all the instructions in this article, you should end up wit If you get stuck, you can compare your work with our [finished example code on GitHub](https://github.com/mdn/beginner-html-site-scripted/blob/main/scripts/main.js). -Now that you've finished creating your website, the next step is to get it online so that others can check it out. We'll show you how to do so in our next article — [Publishing your website](/en-US/docs/Learn_web_development/Getting_started/Your_first_website/Publishing_your_website). +We've only really scratched the surface of JavaScript in this article. You'll learn a lot more in our [Dynamic scripting with JavaScript](/en-US/docs/Learn_web_development/Core/Scripting) Core module later on in the course. ## See also -- [Dynamic scripting with JavaScript](/en-US/docs/Learn_web_development/Core/Scripting) - - : We have just scratched the surface of JavaScript in this article. You'll find a lot more JavaScript later on in our learning pathway, starting with our _Dynamic scripting with JavaScript_ module. +- [Scrimba: Learn JavaScript](https://scrimba.com/learn-javascript-c0v?via=mdn) <sup>[_MDN learning partner_](/en-US/docs/MDN/Writing_guidelines/Learning_content#partner_links_and_embeds)</sup> + - : [Scrimba's](https://scrimba.com?via=mdn) _Learn JavaScript_ course teaches you JavaScript through solving 140+ interactive coding challenges, building projects including a game, a browser extension, and even a mobile app. Scrimba features fun interactive lessons taught by knowledgeable teachers. - [Learn JavaScript](https://learnjavascript.online/) - : This is an excellent resource for aspiring web developers! Learn JavaScript in an interactive environment, with short lessons and interactive tests, guided by an automated assessment. The first 40 lessons are free. The complete course is available for a small one-time payment. diff --git a/files/en-us/learn_web_development/getting_started/your_first_website/creating_the_content/grumpy-cat-attribute-small.png b/files/en-us/learn_web_development/getting_started/your_first_website/creating_the_content/grumpy-cat-attribute-small.png deleted file mode 100644 index e75e441bc59f1b1..000000000000000 Binary files a/files/en-us/learn_web_development/getting_started/your_first_website/creating_the_content/grumpy-cat-attribute-small.png and /dev/null differ diff --git a/files/en-us/learn_web_development/getting_started/your_first_website/creating_the_content/grumpy-cat-small.png b/files/en-us/learn_web_development/getting_started/your_first_website/creating_the_content/grumpy-cat-small.png deleted file mode 100644 index cdb49d286026595..000000000000000 Binary files a/files/en-us/learn_web_development/getting_started/your_first_website/creating_the_content/grumpy-cat-small.png and /dev/null differ diff --git a/files/en-us/learn_web_development/getting_started/your_first_website/creating_the_content/index.md b/files/en-us/learn_web_development/getting_started/your_first_website/creating_the_content/index.md index 887398457589878..4e7f0de27178128 100644 --- a/files/en-us/learn_web_development/getting_started/your_first_website/creating_the_content/index.md +++ b/files/en-us/learn_web_development/getting_started/your_first_website/creating_the_content/index.md @@ -1,14 +1,14 @@ --- title: "HTML: Creating the content" +short-title: Creating the content slug: Learn_web_development/Getting_started/Your_first_website/Creating_the_content page-type: tutorial-chapter +sidebar: learnsidebar --- -{{LearnSidebar}} - {{PreviousMenuNext("Learn_web_development/Getting_started/Your_first_website/What_will_your_website_look_like", "Learn_web_development/Getting_started/Your_first_website/Styling_the_content", "Learn_web_development/Getting_started/Your_first_website")}} -HTML (**H**yper**T**ext **M**arkup **L**anguage) is the code that is used to structure a web page and its content. For example, content could be structured within a set of paragraphs, a list of bulleted points, or using images and data tables. This article provides a basic understanding of HTML and its functions, and shows you how to create the basic content for your first website. +HTML (**H**yper**T**ext **M**arkup **L**anguage) is the code that is used to structure a web page and its content. This article provides a basic understanding of HTML and its functionality, and shows you how to create the basic content for your first website. <table> <tbody> @@ -33,79 +33,41 @@ HTML (**H**yper**T**ext **M**arkup **L**anguage) is the code that is used to str ## So what is HTML? -HTML is a _markup language_ that defines the structure of your content. HTML consists of a series of **{{Glossary("element", "elements")}}**, which you use to enclose, or wrap, different parts of the content to make it appear a certain way, or act a certain way. The enclosing {{Glossary("tag", "tags")}} can make a word or image hyperlink to somewhere else, can italicize words, can make the font bigger or smaller, and so on. For example, take the following line of content: +HTML is a _markup language_ consisting of a series of **{{Glossary("element", "elements")}}** used to wrap (or enclose) text content to define its structure and cause it to behave in a certain way. -```plain -My cat is very grumpy -``` +Let's look at an example — the following content will all be shown on the same line when displayed on a web page, as it is not structured in any way: -If we wanted the line to stand by itself, we could specify that it is a paragraph by enclosing it in paragraph tags: - -```html -<p>My cat is very grumpy</p> +```plain +Instructions for life: +Eat +Sleep +Repeat ``` -### Anatomy of an HTML element - -Let's explore this paragraph element a bit further. - -![paragraph element including opening tag, content reading 'my cat is very grumpy', and a closing tag](grumpy-cat-small.png) - -The main parts of our element are as follows: - -1. **The opening tag:** This consists of the name of the element (in this case, p), wrapped in opening and closing **angle brackets**. This states where the element begins or starts to take effect — in this case where the paragraph begins. -2. **The closing tag:** This is the same as the opening tag, except that it includes a _forward slash_ before the element name. This states where the element ends — in this case where the paragraph ends. Failing to add a closing tag is one of the standard beginner errors and can lead to strange results. -3. **The content:** This is the content of the element, which in this case, is just text. -4. **The element:** The opening tag, the closing tag, and the content together comprise the element. +If we wrap this content with the following HTML elements, we can turn that single line into a paragraph ({{htmlelement("p")}}) and three bullet points ({{htmlelement("li")}}): -Elements can also have attributes that look like the following: +```html live-sample___basic-html +<p>Instructions for life:</p> -![Paragraph opening tag with a class attribute highlighted: class=editor-note](grumpy-cat-attribute-small.png) - -Attributes contain extra information about the element that you don't want to appear in the actual content. Here, `class` is the attribute _name_ and `editor-note` is the attribute _value_. The `class` attribute allows you to give the element a non-unique identifier that can be used to target it (and any other elements with the same `class` value) with style information and other things. -Some attributes have no value, such as [`required`](/en-US/docs/Web/HTML/Attributes/required). - -Attributes that set a value always have: - -1. A space between it and the element name (or the previous attribute, if the element already has one or more attributes). -2. The attribute name followed by an equal sign. -3. The attribute value wrapped by opening and closing quotation marks. - -> [!NOTE] -> Simple attribute values that don't contain {{Glossary("ASCII")}} whitespace (or any of the characters `"` `'` `` ` `` `=` `<` `>`) can remain unquoted, but it is recommended that you quote all attribute values, as it makes the code more consistent and understandable. - -### Nesting elements - -You can put elements inside other elements too — this is called **nesting**. If we wanted to state that our cat is **very** grumpy, we could wrap the word "very" in a {{htmlelement("strong")}} element, which means that the word is to be strongly emphasized: - -```html -<p>My cat is <strong>very</strong> grumpy.</p> -``` - -You do however need to make sure that your elements are properly nested. In the example above, we opened the {{htmlelement("p")}} element first, then the {{htmlelement("strong")}} element; therefore, we have to close the {{htmlelement("strong")}} element first, then the {{htmlelement("p")}} element. The following is incorrect: - -```html-nolint example-bad -<p>My cat is <strong>very grumpy.</p></strong> +<ul> + <li>Eat</li> + <li>Sleep</li> + <li>Repeat</li> +</ul> ``` -The elements have to open and close correctly so that they are clearly inside or outside one another. If they overlap as shown above, then your web browser will try to make the best guess at what you were trying to say, which can lead to unexpected results. So don't do it! +This HTML will render as follows in a web browser: -### Void elements - -Some elements have no content and are called **{{glossary("void element", "void elements")}}**. Take the {{htmlelement("img")}} element that we already have in our HTML page: - -```html -<img src="images/firefox-icon.png" alt="My test image" /> -``` +{{EmbedLiveSample("basic-html", "100%", "140px")}} -This contains two attributes, but there is no closing `</img>` tag and no inner content. This is because an image element doesn't wrap content to affect it. Its purpose is to embed an image in the HTML page in the place it appears. +As well as structuring text, HTML has many other uses — making text or images link to other web pages, embedding images or videos, creating data tables, and so on. ## Creating your first HTML document -That wraps up the basics of individual HTML elements, but they aren't very useful on their own. Now we'll look at how individual elements are combined to form an entire HTML page. Let's create a basic HTML file, and have a look at what it is made up of: +Let's see how individual elements are combined to form an HTML page. In this section, you'll create a basic HTML file and take a look at what it's made up of. 1. Inside your `web-projects` folder, create another new folder called `first-website`. -2. Inside `first-website`, Create a new file called `index.html`, and insert the following code into the file exactly as shown: +2. Inside `first-website`, create a new file called `index.html`, and insert the following code into the file exactly as shown: ```html <!doctype html> @@ -123,15 +85,18 @@ That wraps up the basics of individual HTML elements, but they aren't very usefu Here, we have the following: -- `<!doctype html>` — The [doctype](/en-US/docs/Glossary/Doctype) is a required preamble. In the mists of time, when HTML was young (around 1991/92), doctypes were meant to act as links to a set of rules that the HTML page had to follow to be considered good HTML, which could mean automatic error checking and other useful things. However, these days, they don't do much and are basically just needed to make sure your document behaves correctly. That's all you need to know for now. -- `<html></html>` — the {{htmlelement("html")}} element. This element wraps all the content on the entire page and is sometimes known as the root element. It also includes the `lang` attribute, setting the primary language of the document. -- `<head></head>` — the {{htmlelement("head")}} element. This element acts as a container for all the stuff you want to include on the HTML page that _isn't_ the content you are showing to your page's viewers. This includes things like {{Glossary("keyword", "keywords")}} and a page description that you want to appear in search results, CSS to style our content, character set declarations, and more. -- `<meta charset="utf-8">` — This element sets the character set your document should use to UTF-8 which includes most characters from the vast majority of written languages. Essentially, it can now handle any textual content you might put on it. There is no reason not to set this, and it can help avoid some problems later on. -- `<meta name="viewport" content="width=device-width">` — This [viewport element](/en-US/docs/Web/CSS/CSSOM_view/Viewport_concepts#mobile_viewports) ensures the page renders at the width of viewport, preventing mobile browsers from rendering pages wider than the viewport and then shrinking them down. -- `<title></title>` — the {{htmlelement("title")}} element. This sets the title of your page, which is the title that appears in the browser tab the page is loaded in. It is also used to describe the page when you bookmark/favorite it. -- `<body></body>` — the {{htmlelement("body")}} element. This contains _all_ the content that you want to show to web users when they visit your page, whether that's text, images, videos, games, playable audio tracks, or whatever else. +- `<!doctype html>`: The [doctype](/en-US/docs/Glossary/Doctype) is a required preamble. In the mists of time, when HTML was young (around 1991/92), doctypes were meant to act as links to a set of rules that the HTML page had to follow to be considered good HTML, which could mean automatic error checking and other useful things. However, these days, they don't do much and are basically just needed to make sure your document behaves correctly. That's all you need to know for now. +- `<html></html>`: The {{htmlelement("html")}} element wraps all the content on the entire page and is sometimes known as the **root element**. It also includes the `lang` [attribute](/en-US/docs/Glossary/Attribute), which sets the primary language of the document. +- `<head></head>`: The {{htmlelement("head")}} element acts as a container for all the stuff you want to include on the HTML page that _isn't_ the content you are showing to your page's viewers. This includes things like {{Glossary("keyword", "keywords")}} and a page description that you want to appear in search results, {{glossary("CSS")}} to style the content, character set declarations, and more. +- `<meta charset="utf-8">`: This element sets the character set your document should use to [UTF-8](/en-US/docs/Glossary/UTF-8), which includes most characters from the vast majority of written languages. Essentially, it can now handle any textual content you might put on it. There is no reason not to set this, and it can help avoid some problems later on. +- `<meta name="viewport" content="width=device-width">`: This [viewport element](/en-US/docs/Web/CSS/CSSOM_view/Viewport_concepts#mobile_viewports) ensures the page renders at the width of the browser viewport, preventing mobile browsers from rendering pages wider than the viewport and then shrinking them down. +- `<title></title>`: The {{htmlelement("title")}} element sets the title of your page, which is the title that appears in the browser tab the page is loaded in. It is also used to describe the page when you bookmark/favorite it. +- `<body></body>`: The {{htmlelement("body")}} element contains _all_ the content that you want to show to web users when they visit your page, whether that's text, images, videos, games, playable audio tracks, or whatever else. At the moment it only contains a single `<img>` element, but we'll add more content later on. -## Images +> [!NOTE] +> Most HTML elements consist of an **opening tag** (for example, `<body>`), followed by the element's content, followed by a **closing tag** (for example, `</body>`). Some HTML elements also have **attributes**, which contain extra settings or information about the element — see for example `charset`, `name`, and `src` in the our code sample. + +## Embedding images Let's turn our attention to the {{htmlelement("img")}} element: @@ -139,38 +104,42 @@ Let's turn our attention to the {{htmlelement("img")}} element: <img src="" alt="My test image" /> ``` -This embeds an image into our page in the position it appears. It does this via the `src` (source) attribute, which contains the path to our image file. +This embeds an image into our page in the position it appears. It does this via the `src` (source) attribute, which contains the path to the image file we want to embed. -We have also included an `alt` (alternative) attribute. In the [`alt` attribute](/en-US/docs/Web/HTML/Element/img#authoring_meaningful_alternate_descriptions), you specify descriptive text for users who cannot see the image, possibly because of the following reasons: +We have also included an `alt` (alternative) attribute. In the [`alt` attribute](/en-US/docs/Web/HTML/Reference/Elements/img#authoring_meaningful_alternate_descriptions), you specify descriptive text for users who cannot see the image, possibly because of the following reasons: 1. They are visually impaired. Users with significant visual impairments often use tools called screen readers to read out the alt text to them. -2. Something has gone wrong causing the image not to display. If the `src` attribute does not contain a valid path to an image, the alt text will be displayed instead: +2. Something has gone wrong, causing the image not to display. If the `src` attribute does not contain a valid path to an image, the alt text will be displayed instead: -![The words: my test image](alt-text-example.png) + ![The words: my test image](alt-text-example.png) -The keywords for alt text are "descriptive text". The alt text you write should provide the reader with enough information to have a good idea of what the image conveys. In this example, our current text of "My test image" is no good at all. A much better alternative for our Firefox logo would be "The Firefox logo: a flaming fox surrounding the Earth." +The alt text you write should provide the reader with enough information to have a good idea of what the image conveys. In this example, our current text of "My test image" is not good because it doesn't convey descriptive information about the image. A much better alternative for our Firefox logo would be "The Firefox logo: a flaming fox surrounding the Earth." > [!NOTE] -> Find out more about accessibility in our [accessibility learning module](/en-US/docs/Learn_web_development/Core/Accessibility). +> Elements such as `<img>` have no content or closing tag, and are therefore called **empty** (or **{{glossary("void element", "void")}}**) elements. They are sometimes written with a **trailing slash** at the end of their single tag (`<img />`), but this is optional. Let's get your image displaying now. -1. Inside the `first-website` folder, Create a new folder called `images`, and put the image you chose in the previous example inside this folder. +1. Inside the `first-website` folder, create a new folder called `images`, and put the image you chose in the previous example inside this folder. 2. Inside the `<img>` tag's `src` attribute value, enter the path to your image. It is inside a folder called `images`, which is inside the same directory as your `index.html` file, therefore the path will be `images/` plus the name of your image. For example, if your image was called `firefox-icon.png`, your `src` attribute would look like this: `src="images/firefox-icon.png"`. -3. replace the `alt` attribute value — `My test image` — with some text that better describes your image. -4. Open your `index.html` file inside a web browser. You should see your image displayed. If not, check your `<img>` element against our code above; make sure it is not missing any of the syntax, such as the quote marks. Make sure the image filename is correct. +3. Replace the `alt` attribute value — `My test image` — with some text that better describes your image. +4. Open your `index.html` file inside a web browser. You should see your image displayed. If not, check your `<img>` element against our code; make sure it is not missing any of the syntax, such as the quote marks. Make sure the image filename is correct. + +If the image is really large and therefore doesn't fit on the screen, don't worry about it. We'll fix this issue in the next article. > [!NOTE] -> If the image is really large and therefore doesn't fit on the screen, don't worry about this. We'll fix this issue in the next article. > Find out more about using an `alt` attribute for images in various situations in our [accessible multimedia tutorial](/en-US/docs/Learn_web_development/Core/Accessibility/Multimedia) and [An alt Decision Tree](https://www.w3.org/WAI/tutorials/images/decision-tree/). ## Marking up text -This section will cover some essential HTML elements you'll use for marking up the text. +This section will cover some essential HTML elements you'll use for marking up text. + +> [!NOTE] +> Scrimba's [The basics of semantic HTML](https://scrimba.com/the-frontend-developer-career-path-c0j/~0xid?via=mdn) <sup>[_MDN learning partner_](/en-US/docs/MDN/Writing_guidelines/Learning_content#partner_links_and_embeds)</sup> is an interactive lesson providing a useful description of HTML, with particular emphasis on why the _semantic_ aspect of it is important. ### Headings -Heading elements allow you to specify that certain parts of your content are headings — or subheadings. In the same way that a book has the main title, chapter titles, and subtitles, an HTML document can too. HTML contains 6 heading levels, {{htmlelement("Heading_Elements", "&lt;h1&gt; - &lt;h6&gt;")}}, although you'll commonly only use 3 to 4 at most: +Heading elements allow you to specify that certain parts of your content are headings — or subheadings. In the same way that a book has the main title, chapter titles, and subtitles, an HTML document can too. HTML contains 6 heading levels, {{htmlelement("Heading_Elements", "&lt;h1&gt;–&lt;h6&gt;")}}, although you'll commonly only use 3 to 4 at most: ```html <!-- 4 heading levels: --> @@ -181,16 +150,13 @@ Heading elements allow you to specify that certain parts of your content are hea ``` > [!NOTE] -> Anything in HTML between `<!--` and `-->` is an **HTML comment**. The browser ignores comments as it renders the code. In other words, they are not visible on the page - just in the code. HTML comments are a way for you to write helpful notes about your code or logic. +> Anything in HTML between `<!--` and `-->` is an **HTML comment**. The browser ignores comments as it renders the code. In other words, they are not visible on the page — just in the code. HTML comments are a way for you to add notes about your code or logic, which might be useful to others working on the same code, or you, if you came back to it after 6 months and can't remember what you did. Now try adding a suitable main title to your HTML page just above your {{htmlelement("img")}} element. Save the file and view it in a browser to see the effect. -> [!NOTE] -> You'll see that your heading level 1 has an implicit style. Don't use heading elements to make text bigger or bold, because they are used for [accessibility](/en-US/docs/Learn_web_development/Core/Accessibility/HTML#text_content) and [other reasons such as SEO](/en-US/docs/Learn_web_development/Core/Structuring_content/Headings_and_paragraphs#why_do_we_need_structure). Try to create a meaningful sequence of headings on your pages, without skipping levels. - ### Paragraphs -As explained above, {{htmlelement("p")}} elements are for containing paragraphs of text; you'll use these frequently when marking up regular text content: +Paragraph {{htmlelement("p")}} elements are for containing paragraphs of text; you'll use these frequently when marking up regular text content: ```html <p>This is a single paragraph</p> @@ -207,7 +173,7 @@ A lot of the web's content is lists and HTML has special elements for these. Mar Each item inside the lists is put inside an {{htmlelement("li")}} (list item) element. -For example, if we wanted to turn the part of the following paragraph fragment into a list +For example, if we wanted to turn part of the following paragraph fragment into a list: ```html <p> @@ -216,7 +182,7 @@ For example, if we wanted to turn the part of the following paragraph fragment i </p> ``` -We could modify the markup to this +We could modify the markup to this: ```html <p>At Mozilla, we're a global community of</p> @@ -232,9 +198,9 @@ We could modify the markup to this Try adding an ordered or unordered list to your example page, and view the result in a browser. -## Links +## Creating links -Links are very important — they are what makes the web a web! To add a link, we need to use a specific element — {{htmlelement("a")}} — "a" being the short form for "anchor". To make text within your paragraph into a link, follow these steps: +Links are very important — they are what makes the web a web! To add a link, we need to use an {{htmlelement("a")}} element, "a" being short for "anchor". To make text within your paragraph into a link, follow these steps: 1. Choose some text. We chose the text "Mozilla Manifesto". 2. Wrap the text in an {{htmlelement("a")}} element, as shown below: @@ -259,7 +225,7 @@ Links are very important — they are what makes the web a web! To add a link, w You might get unexpected results if you omit the `https://` or `http://` part, called the _protocol_, at the beginning of the web address. After making a link, click it to make sure it is sending you where you wanted it to. -> **Note:** `href` might appear like a rather obscure choice for an attribute name at first. If you are having trouble remembering it, remember that it stands for _**h**ypertext **ref**erence_. +> **Note:** `href` might appear like a rather obscure choice for an attribute name at first. It stands for _**h**ypertext **ref**erence_. Add a link to your page now, if you haven't already done so. @@ -271,6 +237,11 @@ If you have followed all the instructions in this article, you should end up wit If you get stuck, you can always compare your work with our [finished example code](https://github.com/mdn/beginner-html-site/blob/main/index.html) on GitHub. -Here, we have only really scratched the surface of HTML. You'll learn a lot more in our [Structuring content with HTML](/en-US/docs/Learn_web_development/Core/Structuring_content) Core module. +Here, we have only really scratched the surface of HTML. You'll learn a lot more in our [Structuring content with HTML](/en-US/docs/Learn_web_development/Core/Structuring_content) Core module later on in the course. + +## See also + +- [Learn HTML and CSS](https://scrimba.com/learn-html-and-css-c0p?via=mdn), Scrimba <sup>[_MDN learning partner_](/en-US/docs/MDN/Writing_guidelines/Learning_content#partner_links_and_embeds)</sup> + - : [Scrimba's](https://scrimba.com?via=mdn) _Learn HTML and CSS_ course teaches you HTML and CSS through building and deploying five awesome projects, with fun interactive lessons and challenges taught by knowledgeable teachers. {{PreviousMenuNext("Learn_web_development/Getting_started/Your_first_website/What_will_your_website_look_like", "Learn_web_development/Getting_started/Your_first_website/Styling_the_content", "Learn_web_development/Getting_started/Your_first_website")}} diff --git a/files/en-us/learn_web_development/getting_started/your_first_website/index.md b/files/en-us/learn_web_development/getting_started/your_first_website/index.md index e6ca0eae8223637..2492274b4419897 100644 --- a/files/en-us/learn_web_development/getting_started/your_first_website/index.md +++ b/files/en-us/learn_web_development/getting_started/your_first_website/index.md @@ -2,10 +2,9 @@ title: Your first website slug: Learn_web_development/Getting_started/Your_first_website page-type: landing-page +sidebar: learnsidebar --- -{{LearnSidebar}} - {{PreviousMenuNext("Learn_web_development/Getting_started/Environment_setup/Command_line", "Learn_web_development/Getting_started/Your_first_website/What_will_your_website_look_like", "Learn_web_development/Getting_started")}} This module introduces you to the practicalities of web development. You'll gather the assets and write the code to construct a simple webpage, then publish it for the world to see. @@ -44,5 +43,5 @@ If this is not the case, we'd suggest that you run through the [Environment setu ## See also -- [The Frontend Developer Career Path](https://v2.scrimba.com/the-frontend-developer-career-path-c0j?via=mdn) <sup>_MDN learning partner_</sup> - - : [Scrimba's](https://scrimba.com?via=mdn) _Frontend Developer Career Path_ teaches all you need to know to be a competent front-end web developer, with fun interactive lessons and challenges, knowledgeable teachers, and a supportive community. Go from zero to landing your first front-end job! Many of the course components are available as standalone free versions. +- [The Frontend Developer Career Path](https://scrimba.com/the-frontend-developer-career-path-c0j?via=mdn) <sup>[_MDN learning partner_](/en-US/docs/MDN/Writing_guidelines/Learning_content#partner_links_and_embeds)</sup> + - : [Scrimba's](https://scrimba.com/?via=mdn) _Frontend Developer Career Path_ teaches all you need to know to be a competent front-end web developer, with fun interactive lessons and challenges, knowledgeable teachers, and a supportive community. Go from zero to landing your first front-end job! Many of the course components are available as standalone free versions. diff --git a/files/en-us/learn_web_development/getting_started/your_first_website/publishing_your_website/index.md b/files/en-us/learn_web_development/getting_started/your_first_website/publishing_your_website/index.md index 1e77d5a5275ffa1..65bdf0f44c5c316 100644 --- a/files/en-us/learn_web_development/getting_started/your_first_website/publishing_your_website/index.md +++ b/files/en-us/learn_web_development/getting_started/your_first_website/publishing_your_website/index.md @@ -1,11 +1,11 @@ --- title: Publishing your website +short-title: Publishing slug: Learn_web_development/Getting_started/Your_first_website/Publishing_your_website page-type: tutorial-chapter +sidebar: learnsidebar --- -{{LearnSidebar}} - {{PreviousMenuNext("Learn_web_development/Getting_started/Your_first_website/Adding_interactivity", "Learn_web_development/Getting_started/Web_standards", "Learn_web_development/Getting_started/Your_first_website")}} Once you finish writing the code and organizing the files that make up your website, you need to put it all online so people can find it. This article explains how to get your sample website online with little effort. @@ -67,7 +67,7 @@ Companies use various mechanisms to transfer files to their web servers. Many wi Some tools let you publish your website online: - [GitHub](https://github.com/) is a "social coding" site. It allows you to upload code repositories for storage in the [Git](https://git-scm.com/) **version control system.** You can then collaborate on code projects, and the system is open-source by default, meaning that anyone in the world can find your GitHub code, use it, learn from it, and improve on it. GitHub has a very useful feature called [GitHub Pages](https://pages.github.com/), which allows you to expose website code live on the web. -- [Google App Engine](https://cloud.google.com/appengine/) is a powerful platform that lets you build and run applications on Google's infrastructure — whether you need to build a multi-tiered web application from scratch or host a static website. See [How do you host your website on Google App Engine?](/en-US/docs/Learn_web_development/Howto/Tools_and_setup/How_do_you_host_your_website_on_Google_App_Engine) for more information. +- [Google App Engine](https://cloud.google.com/appengine) is a powerful platform that lets you build and run applications on Google's infrastructure — whether you need to build a multi-tiered web application from scratch or host a static website. See [How do you host your website on Google App Engine?](/en-US/docs/Learn_web_development/Howto/Tools_and_setup/How_do_you_host_your_website_on_Google_App_Engine) for more information. These options are generally free, with a limited feature-set. @@ -77,6 +77,7 @@ There are a number of web apps that emulate a website development environment, a Try playing with some of these examples to find out which one works best for you: +- [Scrimba](https://scrimba.com/new?via=mdn) <sup>[_MDN learning partner_](/en-US/docs/MDN/Writing_guidelines/Learning_content#partner_links_and_embeds)</sup> - [JSFiddle](https://jsfiddle.net/) - [Glitch](https://glitch.com/) - [JS Bin](https://jsbin.com/) diff --git a/files/en-us/learn_web_development/getting_started/your_first_website/styling_the_content/boxes.jpg b/files/en-us/learn_web_development/getting_started/your_first_website/styling_the_content/boxes.jpg deleted file mode 100644 index 1ce5ba505193e30..000000000000000 Binary files a/files/en-us/learn_web_development/getting_started/your_first_website/styling_the_content/boxes.jpg and /dev/null differ diff --git a/files/en-us/learn_web_development/getting_started/your_first_website/styling_the_content/css-declaration-small.png b/files/en-us/learn_web_development/getting_started/your_first_website/styling_the_content/css-declaration-small.png deleted file mode 100644 index 0b5790892d5a79e..000000000000000 Binary files a/files/en-us/learn_web_development/getting_started/your_first_website/styling_the_content/css-declaration-small.png and /dev/null differ diff --git a/files/en-us/learn_web_development/getting_started/your_first_website/styling_the_content/index.md b/files/en-us/learn_web_development/getting_started/your_first_website/styling_the_content/index.md index 90ba8fc28eb9170..d769622f57e8a96 100644 --- a/files/en-us/learn_web_development/getting_started/your_first_website/styling_the_content/index.md +++ b/files/en-us/learn_web_development/getting_started/your_first_website/styling_the_content/index.md @@ -1,14 +1,14 @@ --- title: "CSS: Styling the content" +short-title: Styling the content slug: Learn_web_development/Getting_started/Your_first_website/Styling_the_content page-type: tutorial-chapter +sidebar: learnsidebar --- -{{LearnSidebar}} - {{PreviousMenuNext("Learn_web_development/Getting_started/Your_first_website/Creating_the_content", "Learn_web_development/Getting_started/Your_first_website/Adding_interactivity", "Learn_web_development/Getting_started/Your_first_website")}} -CSS (Cascading Style Sheets) is the code that styles web content. _Styling the content_ walks through what you need to get started. We'll answer questions like: How do I make text red? How do I make content display at a certain location in the (webpage) layout? How do I decorate my webpage with background images and colors? +CSS (Cascading Style Sheets) is the code that styles web content. This article walks you through a basic understanding of CSS — how it works and how to improve the look and feel of the content structure you created in the previous article. <table> <tbody> @@ -33,58 +33,80 @@ CSS (Cascading Style Sheets) is the code that styles web content. _Styling the c ## What is CSS? -Like HTML, CSS is not a programming language. It's not a markup language either. **CSS is a style sheet language.** CSS is what you use to selectively style HTML elements. For example, this CSS selects paragraph text, setting the color to red: +Like HTML, CSS is not a programming language. It's not a markup language either. **CSS is a style sheet language.** CSS is used to style HTML elements: you select the elements you want to style and set values for their style properties, which define how they will look. -```css +Let's revisit the basic HTML example from the article [Creating the content](/en-US/docs/Learn_web_development/Getting_started/Your_first_website/Creating_the_content): + +```html live-sample___basic-html live-sample___basic-css +<p>Instructions for life:</p> + +<ul> + <li>Eat</li> + <li>Sleep</li> + <li>Repeat</li> +</ul> +``` + +This renders as follows on its own: + +{{EmbedLiveSample("basic-html", "100%", "140px")}} + +If we add some CSS into the mix, we can change how the HTML looks. The following snippet selects the {{htmlelement("p")}} element and gives it a different [font](/en-US/docs/Web/CSS/font-family) and a red text {{cssxref("color")}}. It then selects all the {{htmlelement("li")}} elements and gives each one a greeny-yellow {{cssxref("background-color")}}, a 1-pixel solid black {{cssxref("border")}}, and a 5-pixel [bottom margin](/en-US/docs/Web/CSS/margin-bottom): + +```css live-sample___basic-css p { + font-family: sans-serif; color: red; } + +li { + background-color: greenyellow; + border: 1px solid black; + margin-bottom: 5px; +} ``` -Let's try it out! +With the CSS applied to the HTML, the demo now renders like this: + +{{EmbedLiveSample("basic-css", "100%", "160px")}} + +As you can see, with just a little CSS, we were able to change the appearance of a plain-looking list. + +CSS has many other functions, from specifying background images and gradients, to controlling typography and scrolling behavior, to adding animations and building entire web page layouts. + +## Applying CSS to your HTML + +When using CSS, the first thing to get right is to make sure that your CSS is successfully applied to your HTML. In this section, we'll add a CSS **stylesheet** to your `first-website` and apply it to your page. 1. Inside your `first-website` folder, create another new folder called `styles`. -2. Using a text editor, paste the three lines of CSS shown above into a new file. -3. Save the file inside your `styles` folder with a filename of `style.css`. +2. Using a text editor, paste the following CSS into a new file, which will give your `<p>` elements a red text color. It's useful to start with something like this to test whether your stylesheet is being applied to your HTML correctly. -To make the code work, we still need to apply this CSS (above) to your HTML document. Otherwise, the styling won't change the appearance of the HTML. + ```css + p { + color: red; + } + ``` -1. Open your `index.html` file. Paste the following line inside the HTML head (between the {{HTMLElement("head")}} and `</head>` tags): +3. Save the file in the `styles` folder with the filename `style.css`. +4. Open your `index.html` file. Paste the following line inside the HTML head (between the {{HTMLElement("head")}} and `</head>` tags): ```html <link href="styles/style.css" rel="stylesheet" /> ``` -2. Save `index.html` and load it in your browser. You should see something like this: +5. Save `index.html` and load it in your browser. You should see something like this: ![A Mozilla logo and some paragraphs. The paragraph text has been styled red by our css.](website-screenshot-styled.png) -If your paragraph text is red, congratulations! Your CSS is working. - -## Anatomy of a CSS ruleset - -Let's dissect the CSS code for red paragraph text to understand how it works: - -![CSS p declaration color red](css-declaration-small.png) +If your paragraph text is red, congratulations! Your CSS is working. If not, go through the above steps and check carefully that you have followed each one correctly. -The whole structure is called a **ruleset**. (The term _ruleset_ is often referred to as just _rule_.) Note the names of the individual parts: +## CSS syntax basics -- Selector - - : This is the HTML element name at the start of the ruleset. It defines the element(s) to be styled (in this example, {{HTMLElement("p")}} elements). To style a different element, change the selector. -- Declaration - - : This is a single rule like `color: red;`. It specifies which of the element's **properties** you want to style. -- Properties - - : These are features of an HTML element that you can change the values of, to make it styled differently. (In this example, `color` is a property of the {{htmlelement("p")}} elements.) In CSS, you choose which properties you want to affect in the rule. -- Property value - - : To the right of the property—after the colon—there is the **property value**. This chooses one out of many possible appearances for a given property. (For example, there are many `color` values in addition to `red`.) +In the previous CSS example, `p` is called a **selector** — it selects the element(s) to style. In particular, `p` selects all the paragraphs in the HTML. The line inside the curly braces (`{ }`) is called a **declaration** – it sets a value for a specific property. In this case, the **property** is `color`, which controls the text color of the paragraphs, and the **property value** set is `red`. -Note the other important parts of the syntax: +The whole structure is called a **ruleset**. (The term _ruleset_ is often referred to as just _rule_.) -- Apart from the selector, each ruleset must be wrapped in curly braces. (`{}`) -- Within each declaration, you must use a colon (`:`) to separate the property from its value or values. -- Within each ruleset, you must use a semicolon (`;`) to separate each declaration from the next one. - -To modify multiple property values in one ruleset, write them separated by semicolons, like this: +Let's look at another ruleset, this time with multiple declarations: ```css p { @@ -94,113 +116,64 @@ p { } ``` -### Selecting multiple elements +Within a ruleset, you must use a semicolon (`;`) to separate one declaration from the next. Within each declaration, you must use a colon (`:`) to separate the property and its value. -You can also select multiple elements and apply a single ruleset to all of them. Separate multiple selectors by commas. For example: +You can also include multiple selectors in one rule, separated by commas, to select multiple elements. For example: ```css p, -li, -h1 { +.my-class, +#my-id { color: red; } ``` -### Different types of selectors +In this CSS rule, we've included an **element** (or **type**) selector, which selects a specific HTML element. We've also included two other selector types, which aren't relevant to the rest of this tutorial. If you're curious about what they do, check out our [Basic selectors](/en-US/docs/Learn_web_development/Core/Styling_basics/Basic_selectors) guide. -There are many different types of selectors. The examples above use **element selectors**, which select all elements of a given type. But we can make more specific selections as well. Here are some of the more common types of selectors: - -<table class="standard-table no-markdown"> - <thead> - <tr> - <th scope="col">Selector name</th> - <th scope="col">What does it select</th> - <th scope="col">Example</th> - </tr> - </thead> - <tbody> - <tr> - <td>Element selector (sometimes called a tag or type selector)</td> - <td>All HTML elements of the specified type.</td> - <td><code>p</code><br />selects <code>&#x3C;p></code></td> - </tr> - <tr> - <td>ID selector</td> - <td> - The element on the page with the specified ID. On a given HTML page, - each id value should be unique. - </td> - <td> - <code>#my-id</code><br />selects <code>&#x3C;p id="my-id"></code> or - <code>&#x3C;a id="my-id"></code> - </td> - </tr> - <tr> - <td>Class selector</td> - <td> - The element(s) on the page with the specified class. Multiple instances - of the same class can appear on a page. - </td> - <td> - <code>.my-class</code><br />selects - <code>&#x3C;p class="my-class"></code> and - <code>&#x3C;a class="my-class"></code> - </td> - </tr> - <tr> - <td>Attribute selector</td> - <td>The element(s) on the page with the specified attribute.</td> - <td> - <code>img[src]</code><br />selects - <code>&#x3C;img src="my-image.png"></code> but not - <code>&#x3C;img></code> - </td> - </tr> - <tr> - <td>Pseudo-class selector</td> - <td> - The specified element(s), but only when in the specified state. (For - example, when a cursor hovers over a link.) - </td> - <td> - <code>a:hover</code><br />selects <code>&#x3C;a></code>, but only when - the mouse pointer is hovering over the link. - </td> - </tr> - </tbody> -</table> - -There are many more selectors to discover. To learn more, see our selectors tutorials, starting with [Basic selectors](/en-US/docs/Learn_web_development/Core/Styling_basics/Basic_selectors). +> [!NOTE] +> Scrimba's [Write your first lines of CSS!](https://scrimba.com/the-frontend-developer-career-path-c0j/~015?via=mdn) <sup>[_MDN learning partner_](/en-US/docs/MDN/Writing_guidelines/Learning_content#partner_links_and_embeds)</sup> provides a useful interactive introduction to CSS syntax. -## Fonts and text +## Improving the text -Now that we've explored some CSS fundamentals, let's improve the appearance of the example by adding more rules and information to the `style.css` file. +Let's return to our example and use CSS to improve the appearance of the text. We'll set a new font for the page and change some text settings for different elements. -1. First, find the [output from Google Fonts](/en-US/docs/Learn_web_development/Getting_started/Your_first_website/What_will_your_website_look_like#font) that you previously saved from [What will your website look like?](/en-US/docs/Learn_web_development/Getting_started/Your_first_website/What_will_your_website_look_like). Add the {{htmlelement("link")}} element somewhere inside your `index.html`'s head (anywhere between the {{HTMLElement("head")}} and `</head>` tags). It looks something like this: +1. First, find the [output from Google Fonts](/en-US/docs/Learn_web_development/Getting_started/Your_first_website/What_will_your_website_look_like#choosing_a_font) that you previously saved. If you've not already chosen a font, follow the link and do it now. +2. Add the {{htmlelement("link")}} elements inside your `index.html`'s {{HTMLElement("head")}}, just before the closing `</head>` tag. They should look something like this: ```html + <link rel="preconnect" href="https://fonts.googleapis.com" /> + <link rel="preconnect" href="https://fonts.gstatic.com" crossorigin /> <link - href="https://fonts.googleapis.com/css?family=Open+Sans" + href="https://fonts.googleapis.com/css2?family=Roboto:ital,wght@0,100..900;1,100..900&display=swap" rel="stylesheet" /> ``` - This code links your page to a style sheet that loads the Open Sans font family with your webpage. + This code links your page to a stylesheet hosted by the Google Fonts service, which loads your chosen font. -2. Next, delete the existing rule you have in your `style.css` file. It was a good test, but let's not continue with lots of red text. -3. Add the following lines (shown below), replacing the `font-family` assignment with your `font-family` selection from [What will your website look like?](/en-US/docs/Learn_web_development/Getting_started/Your_first_website/What_will_your_website_look_like#font). The property `font-family` refers to the font(s) you want to use for text. This rule defines a global base font and font size for the whole page. Since {{HTMLElement("html")}} is the parent element of the whole page, all elements inside it inherit the same `font-size` and `font-family`. +3. Next, go to your `style.css` file and delete the existing rule. We no longer want our paragraphs to be red. +4. Add the following lines to `style.css`: ```css html { - font-size: 10px; /* px means "pixels": the base font size is now 10 pixels high */ - font-family: - "Open Sans", sans-serif; /* this should be the rest of the output you got from Google Fonts */ + /* px means "pixels". The base font size is now 10 pixels high */ + font-size: 10px; + /* Replace PLACEHOLDER with the font-family property value you got from Google Fonts */ + font-family: PLACEHOLDER; } ``` > [!NOTE] - > Anything in CSS between `/*` and `*/` is a **CSS comment**. The browser ignores comments as it renders the code. CSS comments are a way for you to write helpful notes about your code or logic. + > Anything in CSS between `/*` and `*/` is a **CSS comment**, which is ignored by the browser. CSS comments are a way for you to include helpful notes about your code or logic, without affecting how your webpage is rendered. -4. Now let's set font sizes for elements that will have text inside the HTML body ({{htmlelement("Heading_Elements", "&lt;h1&gt;")}}, {{htmlelement("li")}}, and {{htmlelement("p")}}). We'll also center the heading. Finally, let's expand the second ruleset (below) with settings for line height and letter spacing to make body content more readable. +5. Replace the `font-family` placeholder line with the `font-family` line from your Google Fonts code, for example: + + ```css + font-family: "Roboto", sans-serif; + ``` + + The `font-family` property sets the font(s) you want to apply to your HTML. This rule defines a global base font and font size for the whole page. All elements inside the {{HTMLElement("html")}} element will inherit the same `font-size` and `font-family`. + +6. Now let's set some font and text styles on our [`<h1>`](/en-US/docs/Web/HTML/Reference/Elements/Heading_Elements), {{htmlelement("li")}}, and {{htmlelement("p")}} elements. We'll set new {{cssxref("font-size")}} values for each element. We'll also center the heading using {{cssxref("text-align")}} and increase the {{cssxref("line-height")}} and {{cssxref("letter-spacing")}} of the paragraphs and list items to make the body content more readable. ```css h1 { @@ -216,37 +189,41 @@ Now that we've explored some CSS fundamentals, let's improve the appearance of t } ``` -Adjust the `px` values as you like. Your work-in-progress should look similar to this: +7. Save your code and load your HTML in a browser (refresh it if you've got it open from before). Your work-in-progress should look similar to this: -![A Mozilla logo and some paragraphs. A sans-serif font has been set, the font sizes, line height and letter spacing are adjusted, and the main page heading has been centered](website-screenshot-font-small.png) + ![A Mozilla logo and some paragraphs. A sans-serif font has been set, the font sizes, line height and letter spacing are adjusted, and the main page heading has been centered](website-screenshot-font-small.png) -## CSS: all about boxes + > [!NOTE] + > Try adjusting the `px` values until you end up with font sizes that you like for your heading and body text. -Something you'll notice about CSS as you use it more: a lot of it is about boxes. This includes setting size, color, and position. Most HTML elements on your page can be thought of as boxes sitting on top of other boxes. +## CSS is all about boxes -![A big stack of boxes or crates sat on top of one another](boxes.jpg) +Something you'll notice about CSS as you use it more is that a lot of it is about boxes. Most HTML elements on a page can be thought of as boxes that sit on top of (or alongside) other boxes. You can set values on these boxes for size, color, positioning, etc. This is referred to as [**the box model**](/en-US/docs/Learn_web_development/Core/Styling_basics/Box_model). -Photo from [https://www.geograph.org.uk/photo/3418115](https://www.geograph.org.uk/photo/3418115) Copyright © [Jim Barton](https://www.geograph.org.uk/profile/26362) [cc-by-sa/2.0](https://creativecommons.org/licenses/by-sa/2.0/) +![Three boxes sat inside one another. From outside to in they are labelled margin, border and padding](box-model.png) -CSS layout is mostly based on the _box model._ Each box taking up space on your page has properties like: +Each box that takes up space on your page has properties like: -- `padding`, the space around the content. In the example below, it is the space around the paragraph text. -- `border`, the solid line that is just outside the padding. -- `margin`, the space around the outside of the border. +- {{cssxref("padding")}}: The space around the content. In the previous example, it is the space around the paragraph text. +- {{cssxref("border")}}: The solid line just outside the padding. +- {{cssxref("margin")}}: The space outside the border. -![Three boxes sat inside one another. From outside to in they are labelled margin, border and padding](box-model.png) +In this section, we also use the following properties, some of which you've seen before: -In this section we also use: +- {{cssxref("width")}}: The width of an element. +- {{cssxref("background-color")}}: The color behind an element's content and padding. +- {{cssxref("color")}}: The color of an element's content (usually text). +- {{cssxref("text-shadow")}}: A drop shadow on the text inside an element. +- {{cssxref("display")}}: The display mode of an element (which basically refers to how it appears or is laid out on the web page). -- `width` (of an element). -- `background-color`, the color behind an element's content and padding. -- `color`, the color of an element's content (usually text). -- `text-shadow` sets a drop shadow on the text inside an element. -- `display` sets the display mode of an element. (keep reading to learn more) +In each of the sections that follow: -To continue, let's add more CSS. Keep adding these new rules at the bottom of `style.css`. Experiment with changing values to see what happens. +1. Add the provided CSS code to the bottom of your `style.css` file. +2. Save the file and refresh your browser to see how the CSS has affected the HTML rendering. +3. Read the provided explanation to help you understand how the CSS works. +4. If you are feeling adventurous, experiment with changing the property values to further customize your page. -### Changing the page color +## Changing the page color ```css html { @@ -254,9 +231,9 @@ html { } ``` -This rule sets a background color for the entire page. Change the color code to [the color you chose in What will my website look like?](/en-US/docs/Learn_web_development/Getting_started/Your_first_website/What_will_your_website_look_like#theme_color). +This rule sets a background color for the entire page. Change the color code to the color you chose in [What will your website look like?](/en-US/docs/Learn_web_development/Getting_started/Your_first_website/What_will_your_website_look_like#choosing_a_theme_color). -### Styling the body +## Styling the body ```css body { @@ -270,13 +247,13 @@ body { The above code sets new values for several properties of the {{htmlelement("body")}} element. Let's go through these line-by-line: -- `width: 600px;` This forces the body to always be 600 pixels wide. -- `margin: 0 auto;` When you set two values on a property like `margin` or `padding`, the first value affects the element's top _and_ bottom side (setting it to `0` in this case); the second value affects the left _and_ right side. (Here, `auto` is a special value that divides the available horizontal space evenly between left and right). You can also use one, two, three, or four values, as documented in [Margin Syntax](/en-US/docs/Web/CSS/margin#syntax). -- `background-color: #FF9500;` This sets the element's background color. This project uses a reddish orange for the body background color, as opposed to dark blue for the {{htmlelement("html")}} element. (Feel free to experiment.) -- `padding: 0 20px 20px 20px;` This sets four values for padding. The goal is to put some space around the content. In this example, there is no padding on the top of the body, and 20 pixels on the right, bottom and left. The values set top, right, bottom, left, in that order. As with `margin`, you can use one, two, three, or four values, as documented in [Padding Syntax](/en-US/docs/Web/CSS/padding#syntax). -- `border: 5px solid black;` This sets values for the width, style and color of the border. In this case, it's a five-pixel–wide, solid black border, on all sides of the body. +- `width: 600px;`: This forces the body to always be 600 pixels wide. +- `margin: 0 auto;`: When you set two values on a property like `margin` or `padding`, the first value affects the element's top _and_ bottom side (setting it to `0` in this case); the second value affects the left _and_ right side. `auto` is a special value that divides the available horizontal space evenly between left and right. +- `background-color: #FF9500;`: This sets the element's background color. Our project uses a reddish orange for the `<body>` background color to contrast with the dark blue used for the {{htmlelement("html")}} element. +- `padding: 0 20px 20px 20px;`: This sets four values for padding. The goal is to put some space around the content. In this example, there is no padding on the top of the body, and 20 pixels on the right, bottom, and left. The values set top, right, bottom, and left padding, in that order. +- `border: 5px solid black;`: This sets values for the width, style, and color of the border. In this case, it's a 5-pixel-wide solid black border around all sides of the body. -### Positioning and styling the main page title +## Positioning and styling the main page title ```css h1 { @@ -287,22 +264,18 @@ h1 { } ``` -You may have noticed there's a horrible gap at the top of the body. That happens because browsers apply default styling to the {{htmlelement("Heading_Elements", "h1")}} element (among others). That might seem like a bad idea, but the intent is to provide basic readability for unstyled pages. To eliminate the gap, we overwrite the browser's default styling with the setting `margin: 0;`. +You may have noticed a horrible gap at the top of the body. That happens because browsers apply default styling to the `<h1>` element. That might seem like a bad idea, but the intent is to provide basic readability for unstyled pages. To eliminate the gap, we overwrite the browser's default styling with the setting `margin: 0;`. -Next, we set the heading's top and bottom padding to 20 pixels. +Next, we set the heading's top and bottom padding to 20 pixels, and set the heading text to be the same color as the HTML background color. -Following that, we set the heading text to be the same color as the HTML background color. - -Finally, `text-shadow` applies a shadow to the text content of the element. Its four values are: +Finally, `text-shadow` applies a shadow to the text content of the element: - The first pixel value sets the **horizontal offset** of the shadow from the text: how far it moves across. - The second pixel value sets the **vertical offset** of the shadow from the text: how far it moves down. - The third pixel value sets the **blur radius** of the shadow. A larger value produces a more fuzzy-looking shadow. - The fourth value sets the base color of the shadow. -Try experimenting with different values to see how it changes the appearance. - -### Centering the image +## Centering the image ```css img { @@ -312,14 +285,14 @@ img { } ``` -Next, we center the image to make it look better. We could use the same `margin: 0 auto` trick as we did for the body. But there are differences that require an additional setting to make the CSS work. +Next, we center the image to make it look better. We can use the same `margin: 0 auto` trick as we did for the body, but there are differences that require an additional setting to make the CSS work. -The {{htmlelement("body")}} is a **block** element, meaning it takes up space on the page. The margin applied to a block element will be respected by other elements on the page. In contrast, images are **inline** elements; for the auto margin trick to work on this image, we must give it block-level behavior using `display: block;`. +The {{htmlelement("body")}} element is a **block** element, meaning it takes up space on the page and can accept margin, padding, and other box properties. {{htmlelement("img")}} (image) elements, on the other hand, are **inline** elements: by default, they don't accept margin values in the same way block elements do. For the auto-margin trick to work on this image, we must give it block-level behavior by using `display: block;`. -Finally, we include `max-width: 100%;` to make sure that, if the image is larger than the `width` set on the body (600 pixels), it will be displayed at this width, and no bigger. +Finally, we set the {{cssxref("max-width")}} property to `100%` to ensure that if the image is larger than the `width` set on the body (600 pixels), it will be constrained to `600px` and won't stretch wider. > [!NOTE] -> Don't be too concerned if you don't completely understand `display: block;` and the differences between a block element and an inline element, or `max-width: 100%;`. They will make more sense as you continue your study of CSS. You can find more information about these properties on MDN's {{cssxref("display")}} and {{cssxref("max-width")}} reference pages. +> Don't be too concerned if you don't completely understand `display: block;` and the differences between a block element and an inline element, or `max-width: 100%;`. They will make more sense as you continue your study of CSS. ## Conclusion @@ -327,8 +300,13 @@ If you followed all the instructions in this article, you should have a page tha ![A Mozilla logo, centered, and a header and paragraphs. It now looks nicely styled, with a blue background for the whole page and orange background for the centered main content strip.](website-screenshot-final.png) -(You can [view our version here](https://mdn.github.io/beginner-html-site-styled/).) If you get stuck, you can always compare your work with our [finished example code on GitHub](https://github.com/mdn/beginner-html-site-styled/blob/gh-pages/styles/style.css). +You can [view our version here](https://mdn.github.io/beginner-html-site-styled/). If you get stuck, you can always compare your work with our [finished example code on GitHub](https://github.com/mdn/beginner-html-site-styled/blob/gh-pages/styles/style.css). + +In this article, we've only scratched the surface of CSS. You'll learn a lot more in our [CSS styling basics](/en-US/docs/Learn_web_development/Core/Styling_basics) Core module later in the course. + +## See also -In this article, we have just scratched the surface of CSS. Our [Core modules](/en-US/docs/Learn_web_development/Core), starting with the [CSS styling basics module](/en-US/docs/Learn_web_development/Core/Styling_basics), will cover it in a lot more detail. +- [Learn HTML and CSS](https://scrimba.com/learn-html-and-css-c0p?via=mdn), Scrimba <sup>[_MDN learning partner_](/en-US/docs/MDN/Writing_guidelines/Learning_content#partner_links_and_embeds)</sup> + - : [Scrimba's](https://scrimba.com?via=mdn) _Learn HTML and CSS_ course teaches you HTML and CSS through building and deploying five awesome projects, with fun interactive lessons and challenges taught by knowledgeable teachers. {{PreviousMenuNext("Learn_web_development/Getting_started/Your_first_website/Creating_the_content", "Learn_web_development/Getting_started/Your_first_website/Adding_interactivity", "Learn_web_development/Getting_started/Your_first_website")}} diff --git a/files/en-us/learn_web_development/getting_started/your_first_website/what_will_your_website_look_like/index.md b/files/en-us/learn_web_development/getting_started/your_first_website/what_will_your_website_look_like/index.md index b187ea9daa93efc..e449edb54c606b1 100644 --- a/files/en-us/learn_web_development/getting_started/your_first_website/what_will_your_website_look_like/index.md +++ b/files/en-us/learn_web_development/getting_started/your_first_website/what_will_your_website_look_like/index.md @@ -1,11 +1,11 @@ --- title: What will your website look like? +short-title: What will it look like? slug: Learn_web_development/Getting_started/Your_first_website/What_will_your_website_look_like page-type: tutorial-chapter +sidebar: learnsidebar --- -{{LearnSidebar}} - {{NextMenu("Learn_web_development/Getting_started/Your_first_website/Creating_the_content", "Learn_web_development/Getting_started/Your_first_website")}} _What will your website look like?_ discusses the planning and design work you have to do for your website before writing code, including "What information does my website offer?", "What fonts and colors do I want?", and "What does my site do?" @@ -78,16 +78,19 @@ Note that most images on the web, including in Google Images, are copyrighted. T ## Choosing a font -As with images, many fonts are protected by licenses, meaning you cannot freely use them in your site. [Google Fonts](https://developers.google.com/fonts) is a web service owned by Google that provides access to many fonts. +There is a set of fonts called the [web safe fonts](/en-US/docs/Learn_web_development/Core/Text_styling/Fundamentals#web_safe_fonts) — such as Arial, Times New Roman, or Courier New — that are generally available on most computer systems. If you use one of these fonts on your website, the browser will load the font file available on the user's computer. -Once you have found a font, there are two main ways of using it: +However, if you want to use other fonts not generally available on devices, you need to either include them along with your website files or reference the font files from a third-party font service so the browser can download them as needed. [Google Fonts](https://fonts.google.com/) is one such service that provides access to many fonts. -1. Add a reference in your code to load the font from Google's servers. -2. Download the font file to your own system, host the font yourself, and use your hosted copy in your website's code. +Let's use Google fonts to choose a font for your website: -> [!NOTE] -> Serving fonts hosted on Google Fonts may be incompatible with the European Union's data privacy regulation [GDPR](https://gdpr.eu/) as the font service exposes the user's IP address. If this is a potential problem for you, then either choose the second option or choose a font provider that is GDPR compliant, such as [Bunny Fonts](https://fonts.bunny.net/about). +1. Go to [Google Fonts](https://fonts.google.com/). +2. Scroll down the list of fonts until you find one you like. If you are having trouble finding one, you can use the filters available in the other column to narrow down your search. +3. Click your font option, then on the next page click the "Get font" button. +4. On the next page, click "Get embed code". +5. Copy both of the provided code blocks, and save them somewhere safe for later use. -Alternatively you can use [safe web fonts](https://web.mit.edu/jmorzins/www/fonts.html) such as Arial, Times New Roman, or Courier New. +> [!NOTE] +> As with images, many fonts are protected by licenses, meaning you cannot necessarily use them freely on commercial websites. You will be fine for now while working on learning examples, but keep this in mind when choosing fonts for real websites. {{NextMenu("Learn_web_development/Getting_started/Your_first_website/Creating_the_content", "Learn_web_development/Getting_started/Your_first_website")}} diff --git a/files/en-us/learn_web_development/howto/design_and_accessibility/common_web_layouts/index.md b/files/en-us/learn_web_development/howto/design_and_accessibility/common_web_layouts/index.md index 1fa00696d232d19..e81991a2c7c26cb 100644 --- a/files/en-us/learn_web_development/howto/design_and_accessibility/common_web_layouts/index.md +++ b/files/en-us/learn_web_development/howto/design_and_accessibility/common_web_layouts/index.md @@ -2,10 +2,9 @@ title: What do common web layouts contain? slug: Learn_web_development/Howto/Design_and_accessibility/Common_web_layouts page-type: learn-faq +sidebar: learn-how-to --- -{{QuicklinksWithSubPages("/en-US/docs/Learn_web_development/Howto")}} - When designing pages for your website, it's good to have an idea of the most common layouts. <table class="standard-table"> @@ -76,7 +75,7 @@ Let's study some more concrete examples taken from well-known websites. ### One-column layout -**[Invision application](https://www.invisionapp.com/)**. A typical one-column layout providing all the information linearly on one page. +A typical one-column layout providing all the information linearly on one page. ![Example of a 1 column layout in the wild](screenshot-product.jpg) ![1 column layout with header, main content, a stack of aside contents and a footer](screenshot-product-overlay.jpg) diff --git a/files/en-us/learn_web_development/howto/design_and_accessibility/design_for_all_types_of_users/index.md b/files/en-us/learn_web_development/howto/design_and_accessibility/design_for_all_types_of_users/index.md index d27822f7a10804d..fd208165ac0316c 100644 --- a/files/en-us/learn_web_development/howto/design_and_accessibility/design_for_all_types_of_users/index.md +++ b/files/en-us/learn_web_development/howto/design_and_accessibility/design_for_all_types_of_users/index.md @@ -2,10 +2,9 @@ title: How can we design for all types of users? slug: Learn_web_development/Howto/Design_and_accessibility/Design_for_all_types_of_users page-type: learn-faq +sidebar: learn-how-to --- -{{QuicklinksWithSubPages("/en-US/docs/Learn_web_development/Howto")}} - This article provides basic tips to help you design websites for any kind of user. <table class="standard-table"> @@ -247,7 +246,4 @@ You must also provide alternatives to multimedia content. ### Image compression -Some users may choose to display images, but still have limited bandwidth available, especially in developing countries and on mobile devices. If you want a successful website, please compress your images. There are various tools to help you, either online or local: - -- **Installed software.** [ImageOptim](https://imageoptim.com/api) (Mac), [OptiPNG](https://optipng.sourceforge.net/) (all platforms), [PNGcrush](https://pmt.sourceforge.io/pngcrush/) (DOS, Unix/Linux) -- **Online tools.** Dynamic drive's [Online Image Optimizer](https://tools.dynamicdrive.com/imageoptimizer/) (which can convert automatically from one format to another if it's more bandwidth-efficient) +Some users may choose to display images, but still have limited bandwidth available, especially in developing countries and on mobile devices. If you want a successful website, please compress your images. There are various tools to help you, either online or local. Generally, local tools are preferred because they can be more integrated with your development workflow; these tools include [ImageOptim](https://imageoptim.com/api) (Mac), [OptiPNG](https://optipng.sourceforge.net/) (all platforms), and [PNGcrush](https://pmt.sourceforge.io/pngcrush/) (DOS, Unix/Linux). diff --git a/files/en-us/learn_web_development/howto/design_and_accessibility/html_features_for_accessibility/index.md b/files/en-us/learn_web_development/howto/design_and_accessibility/html_features_for_accessibility/index.md index 9a2f2288c4d5211..438a34c0aae9b43 100644 --- a/files/en-us/learn_web_development/howto/design_and_accessibility/html_features_for_accessibility/index.md +++ b/files/en-us/learn_web_development/howto/design_and_accessibility/html_features_for_accessibility/index.md @@ -2,15 +2,14 @@ title: What HTML features promote accessibility? slug: Learn_web_development/Howto/Design_and_accessibility/HTML_features_for_accessibility page-type: learn-faq +sidebar: learn-how-to --- -{{QuicklinksWithSubPages("/en-US/docs/Learn_web_development/Howto")}} - The following content describes specific features of HTML that should be used to make a web page more accessible to people with different disabilities. ## Link text -If you have a link that isn't self-descriptive, or the link destination could benefit from being explained in more detail, you can add information to a link using the [`aria-label`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-label) or [`aria-labelledby`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-labelledby) attributes. +If you have a link that isn't self-descriptive, or the link destination could benefit from being explained in more detail, you can add information to a link using the [`aria-label`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-label) or [`aria-labelledby`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-labelledby) attributes. ```html <p> @@ -40,7 +39,7 @@ Note that, most of the time, it is better to instead write useful link text: ## Skip Links -To aid tabbing, you can supply a [skip link](/en-US/docs/Web/HTML/Element/a#skip_links) that allow users to jump over chunks of your web page. You might want to allow someone to jump over a plethora of navigation links that are found on every page. This enables keyboard users to quickly tab over repeated content and go directly to the page's main content: +To aid tabbing, you can supply a [skip link](/en-US/docs/Web/HTML/Reference/Elements/a#skip_links) that allow users to jump over chunks of your web page. You might want to allow someone to jump over a plethora of navigation links that are found on every page. This enables keyboard users to quickly tab over repeated content and go directly to the page's main content: ```html <header> @@ -59,7 +58,7 @@ To aid tabbing, you can supply a [skip link](/en-US/docs/Web/HTML/Element/a#skip ## Alt attribute for image -Every image should have an [`alt`](/en-US/docs/Web/HTML/Element/img#alt) attribute. If the image is purely decoration and adds no meaning to the content or context of the document, the `alt` attribute should be present, but empty. You can optionally also add [`role="presentation"`](/en-US/docs/Web/Accessibility/ARIA/Roles/presentation_role). All other images should include an `alt` attribute providing [alternative text describing the image](/en-US/docs/Web/API/HTMLImageElement/alt#usage_notes) in a way that is helpful to users who can read the rest of the content but can't see the image. Think about how you would describe the image to someone who can't load your image: that's the information you should include as the value of the `alt` attribute. +Every image should have an [`alt`](/en-US/docs/Web/HTML/Reference/Elements/img#alt) attribute. If the image is purely decoration and adds no meaning to the content or context of the document, the `alt` attribute should be present, but empty. You can optionally also add [`role="presentation"`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/presentation_role). All other images should include an `alt` attribute providing [alternative text describing the image](/en-US/docs/Web/API/HTMLImageElement/alt#usage_notes) in a way that is helpful to users who can read the rest of the content but can't see the image. Think about how you would describe the image to someone who can't load your image: that's the information you should include as the value of the `alt` attribute. ```html <!-- decorative image --> @@ -70,7 +69,7 @@ Every image should have an [`alt`](/en-US/docs/Web/HTML/Element/img#alt) attribu role="img" /> ``` -The `alt` attribute for the same content may vary depending on the context. In the following example, an animated gif is used instead of a progress bar to show the page load progress for a document teaching developers how to use the HTML [`<progress>`](/en-US/docs/Web/HTML/Element/progress) element: +The `alt` attribute for the same content may vary depending on the context. In the following example, an animated gif is used instead of a progress bar to show the page load progress for a document teaching developers how to use the HTML [`<progress>`](/en-US/docs/Web/HTML/Reference/Elements/progress) element: ```html <img alt="20% complete" src="load-progress.gif" /> @@ -81,7 +80,7 @@ The `alt` attribute for the same content may vary depending on the context. In t ## ARIA role attribute -By default, all semantic elements in HTML have a [`role`](/en-US/docs/Web/Accessibility/ARIA/Roles); for example, `<input type="radio">` has the `radio` role. Non-semantic elements in HTML do not have a role. ARIA roles can be used to describe elements that don't natively exist in HTML, such as a [`tablist`](/en-US/docs/Web/Accessibility/ARIA/Roles/tablist_role) widget. Roles are also helpful for newer elements that exist but don't yet have full browser support. For example, when using SVG images, add `role="img"` to the opening tag, as there is an [SVG VoiceOver bug](https://webkit.org/b/216364) whereby VoiceOver does not correctly announce SVG images. +By default, all semantic elements in HTML have a [`role`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles); for example, `<input type="radio">` has the `radio` role. Non-semantic elements in HTML do not have a role. ARIA roles can be used to describe elements that don't natively exist in HTML, such as a [`tablist`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/tablist_role) widget. Roles are also helpful for newer elements that exist but don't yet have full browser support. For example, when using SVG images, add `role="img"` to the opening tag, as there is an [SVG VoiceOver bug](https://webkit.org/b/216364) whereby VoiceOver does not correctly announce SVG images. ```html <img src="mdn.svg" alt="MDN logo" role="img" /> diff --git a/files/en-us/learn_web_development/howto/design_and_accessibility/index.md b/files/en-us/learn_web_development/howto/design_and_accessibility/index.md index 095cb4578776731..03c590e17e5659e 100644 --- a/files/en-us/learn_web_development/howto/design_and_accessibility/index.md +++ b/files/en-us/learn_web_development/howto/design_and_accessibility/index.md @@ -2,10 +2,9 @@ title: Design and accessibility slug: Learn_web_development/Howto/Design_and_accessibility page-type: landing-page +sidebar: learn-how-to --- -{{LearnSidebar}} - This section lists questions related to aesthetics, page structure, accessibility techniques, etc. - [How do I start to design my website?](/en-US/docs/Learn_web_development/Howto/Design_and_accessibility/Thinking_before_coding) diff --git a/files/en-us/learn_web_development/howto/design_and_accessibility/thinking_before_coding/index.md b/files/en-us/learn_web_development/howto/design_and_accessibility/thinking_before_coding/index.md index 2d0c134d1212317..f8bc6ab7dcb56a0 100644 --- a/files/en-us/learn_web_development/howto/design_and_accessibility/thinking_before_coding/index.md +++ b/files/en-us/learn_web_development/howto/design_and_accessibility/thinking_before_coding/index.md @@ -2,10 +2,9 @@ title: How do I start to design my website? slug: Learn_web_development/Howto/Design_and_accessibility/Thinking_before_coding page-type: learn-faq +sidebar: learn-how-to --- -{{QuicklinksWithSubPages("/en-US/docs/Learn_web_development/Howto")}} - This article covers the all-important first step of every project: define what you want to accomplish with it. <table> diff --git a/files/en-us/learn_web_development/howto/design_and_accessibility/what_is_accessibility/index.md b/files/en-us/learn_web_development/howto/design_and_accessibility/what_is_accessibility/index.md index 0b404a6aa3ef8b4..b9e1f8dcdee9068 100644 --- a/files/en-us/learn_web_development/howto/design_and_accessibility/what_is_accessibility/index.md +++ b/files/en-us/learn_web_development/howto/design_and_accessibility/what_is_accessibility/index.md @@ -2,10 +2,9 @@ title: What is accessibility? slug: Learn_web_development/Howto/Design_and_accessibility/What_is_accessibility page-type: learn-faq +sidebar: learn-how-to --- -{{QuicklinksWithSubPages("/en-US/docs/Learn_web_development/Howto")}} - This article introduces the basic concepts behind web accessibility. <table class="standard-table"> diff --git a/files/en-us/learn_web_development/howto/index.md b/files/en-us/learn_web_development/howto/index.md index e86947e4405d923..fa9bde1e92bda40 100644 --- a/files/en-us/learn_web_development/howto/index.md +++ b/files/en-us/learn_web_development/howto/index.md @@ -2,19 +2,13 @@ title: How to solve common problems slug: Learn_web_development/Howto page-type: landing-page +sidebar: learn-how-to --- -{{LearnSidebar}} - This section provides solutions to common front-end problems and answers to common questions. -- [Solve common HTML problems](/en-US/docs/Learn_web_development/Howto/Solve_HTML_problems) -- [Solve common CSS problems](/en-US/docs/Learn_web_development/Howto/Solve_CSS_problems) -- [Solve common JavaScript problems](/en-US/docs/Learn_web_development/Howto/Solve_JavaScript_problems) -- [Web mechanics](/en-US/docs/Learn_web_development/Howto/Web_mechanics) -- [Tools and setup](/en-US/docs/Learn_web_development/Howto/Tools_and_setup) -- [Design and accessibility](/en-US/docs/Learn_web_development/Howto/Design_and_accessibility) +{{subpageswithsummaries}} ## See also -- [HTML Cheatsheet](/en-US/docs/Learn_web_development/Howto/Solve_HTML_problems/Cheatsheet) +- [HTML Cheatsheet](/en-US/docs/Web/HTML/Guides/Cheatsheet) diff --git a/files/en-us/learn_web_development/howto/solve_css_problems/add_a_shadow/index.md b/files/en-us/learn_web_development/howto/solve_css_problems/add_a_shadow/index.md index 487f65fe6d0f0ff..0872081c5ddb298 100644 --- a/files/en-us/learn_web_development/howto/solve_css_problems/add_a_shadow/index.md +++ b/files/en-us/learn_web_development/howto/solve_css_problems/add_a_shadow/index.md @@ -1,11 +1,11 @@ --- title: How to add a shadow to an element +short-title: Add a shadow to an element slug: Learn_web_development/Howto/Solve_CSS_problems/Add_a_shadow page-type: learn-faq +sidebar: learn-how-to --- -{{LearnSidebar}} - In this guide you can find out how to add a shadow to any box on your page. ## Adding box shadows diff --git a/files/en-us/learn_web_development/howto/solve_css_problems/add_a_text_shadow/index.md b/files/en-us/learn_web_development/howto/solve_css_problems/add_a_text_shadow/index.md index 00e826059ec7386..e768b0f4f4b3492 100644 --- a/files/en-us/learn_web_development/howto/solve_css_problems/add_a_text_shadow/index.md +++ b/files/en-us/learn_web_development/howto/solve_css_problems/add_a_text_shadow/index.md @@ -1,11 +1,11 @@ --- title: How to add a shadow to text +short-title: Add a shadow to text slug: Learn_web_development/Howto/Solve_CSS_problems/Add_a_text_shadow page-type: learn-faq +sidebar: learn-how-to --- -{{LearnSidebar}} - In this guide you can find out how to add a shadow to any text on your page. ## Adding shadows to text @@ -37,4 +37,4 @@ h1 { {{EmbedLiveSample("text-shadow")}} > [!NOTE] -> It can be quite easy to make text hard to read with text shadows. Make sure that the choices you make still leave your text readable and provide enough [color contrast](/en-US/docs/Web/Accessibility/Understanding_WCAG/Perceivable/Color_contrast) for visitors who have difficulty with low-contrast text. +> It can be quite easy to make text hard to read with text shadows. Make sure that the choices you make still leave your text readable and provide enough [color contrast](/en-US/docs/Web/Accessibility/Guides/Understanding_WCAG/Perceivable/Color_contrast) for visitors who have difficulty with low-contrast text. diff --git a/files/en-us/learn_web_development/howto/solve_css_problems/center_an_item/index.md b/files/en-us/learn_web_development/howto/solve_css_problems/center_an_item/index.md index e2a5f82b81d858f..5b5cc49be06073e 100644 --- a/files/en-us/learn_web_development/howto/solve_css_problems/center_an_item/index.md +++ b/files/en-us/learn_web_development/howto/solve_css_problems/center_an_item/index.md @@ -1,11 +1,11 @@ --- title: How to center an item +short-title: Center an item slug: Learn_web_development/Howto/Solve_CSS_problems/Center_an_item page-type: learn-faq +sidebar: learn-how-to --- -{{LearnSidebar}} - In this guide you can find out how to center an item inside another element, both horizontally and vertically. ## Center a box diff --git a/files/en-us/learn_web_development/howto/solve_css_problems/create_fancy_boxes/index.md b/files/en-us/learn_web_development/howto/solve_css_problems/create_fancy_boxes/index.md index 39c268b807c50c2..80b8d24be27c5df 100644 --- a/files/en-us/learn_web_development/howto/solve_css_problems/create_fancy_boxes/index.md +++ b/files/en-us/learn_web_development/howto/solve_css_problems/create_fancy_boxes/index.md @@ -2,10 +2,9 @@ title: Create fancy boxes slug: Learn_web_development/Howto/Solve_CSS_problems/Create_fancy_boxes page-type: learn-faq +sidebar: learn-how-to --- -{{LearnSidebar}} - CSS boxes are the building blocks of any web page styled with CSS. Making them nice looking is both fun and challenging. It's fun because it's all about turning a design idea into working code; it's challenging because of the constraints of CSS. Let's do some fancy boxes. Before we start getting into the practical side of it, make sure you are familiar with [the CSS box model](/en-US/docs/Learn_web_development/Core/Styling_basics/Box_model). It's also a good idea, but not a prerequisite, to be familiar with some [CSS layout basics](/en-US/docs/Learn_web_development/Core/CSS_layout/Introduction). diff --git a/files/en-us/learn_web_development/howto/solve_css_problems/css_faq/index.md b/files/en-us/learn_web_development/howto/solve_css_problems/css_faq/index.md index c2898f1de200039..01c906064facf9b 100644 --- a/files/en-us/learn_web_development/howto/solve_css_problems/css_faq/index.md +++ b/files/en-us/learn_web_development/howto/solve_css_problems/css_faq/index.md @@ -1,11 +1,11 @@ --- title: CSS FAQ +short-title: FAQ slug: Learn_web_development/Howto/Solve_CSS_problems/CSS_FAQ page-type: learn-faq +sidebar: learn-how-to --- -{{LearnSidebar}} - In this article, you'll find some frequently-asked questions (FAQs) about CSS, along with answers that may help you on your quest to become a web developer. ## Why doesn't my CSS, which is valid, render correctly? @@ -261,8 +261,8 @@ Browsers no longer use CSS prefixes when implementing new experimental features. If you are required to use prefixes in your work, write the prefixed versions first followed by the non-prefixed standard version. This way the standard version will automatically override the prefixed versions when supported. For example: ```css --webkit-text-stroke: 4px navy; -text-stroke: 4px navy; +-webkit-border-after-color: navy; +border-block-end-color: navy; ``` > [!NOTE] diff --git a/files/en-us/learn_web_development/howto/solve_css_problems/fill_a_box_with_an_image/index.md b/files/en-us/learn_web_development/howto/solve_css_problems/fill_a_box_with_an_image/index.md index 4b4a9285935bdb4..8c0c416cc8b401d 100644 --- a/files/en-us/learn_web_development/howto/solve_css_problems/fill_a_box_with_an_image/index.md +++ b/files/en-us/learn_web_development/howto/solve_css_problems/fill_a_box_with_an_image/index.md @@ -1,16 +1,16 @@ --- title: How to fill a box with an image without distorting it +short-title: Fill a box with an image slug: Learn_web_development/Howto/Solve_CSS_problems/Fill_a_box_with_an_image page-type: learn-faq +sidebar: learn-how-to --- -{{LearnSidebar}} - In this guide you can learn a technique for causing an HTML image to completely fill a box. ## Using object-fit -When you add an image to a page using the HTML {{htmlelement("img")}} element, the image will maintain the size and {{glossary("aspect ratio")}} of the image file, or that of any HTML [`width`](/en-US/docs/Web/HTML/Element/img#width) or [`height`](/en-US/docs/Web/HTML/Element/img#height) attributes. Sometimes you would like the image to completely fill the box that you have placed it in. In that case you first need to decide what happens if the image is the wrong aspect ratio for the container. +When you add an image to a page using the HTML {{htmlelement("img")}} element, the image will maintain the size and {{glossary("aspect ratio")}} of the image file, or that of any HTML [`width`](/en-US/docs/Web/HTML/Reference/Elements/img#width) or [`height`](/en-US/docs/Web/HTML/Reference/Elements/img#height) attributes. Sometimes you would like the image to completely fill the box that you have placed it in. In that case you first need to decide what happens if the image is the wrong aspect ratio for the container. 1. The image should completely fill the box, retaining aspect ratio, and cropping any excess on the side that is too big to fit. 2. The image should fit inside the box, with the background showing through as bars on the too-small side. diff --git a/files/en-us/learn_web_development/howto/solve_css_problems/generated_content/index.md b/files/en-us/learn_web_development/howto/solve_css_problems/generated_content/index.md index 3fac50b83a49728..62cc59849b2abdd 100644 --- a/files/en-us/learn_web_development/howto/solve_css_problems/generated_content/index.md +++ b/files/en-us/learn_web_development/howto/solve_css_problems/generated_content/index.md @@ -1,11 +1,11 @@ --- -title: Using CSS generated content +title: Use CSS generated content +short-title: Use generated content slug: Learn_web_development/Howto/Solve_CSS_problems/Generated_content page-type: learn-faq +sidebar: learn-how-to --- -{{LearnSidebar}} - This article describes some ways in which you can use CSS to add content when a document is displayed. You modify your stylesheet to add text content or images. One of the important advantages of CSS is that it helps you to separate a document's style from its content. However, there are situations where it makes sense to specify certain content as part of the stylesheet, not as part of the document. You can specify text or image content within a stylesheet when that content is closely linked to the document's structure. diff --git a/files/en-us/learn_web_development/howto/solve_css_problems/highlight_first_line/index.md b/files/en-us/learn_web_development/howto/solve_css_problems/highlight_first_line/index.md index 48a340bdaff47e6..4c841213aa2b265 100644 --- a/files/en-us/learn_web_development/howto/solve_css_problems/highlight_first_line/index.md +++ b/files/en-us/learn_web_development/howto/solve_css_problems/highlight_first_line/index.md @@ -1,11 +1,11 @@ --- title: How to highlight the first line of a paragraph +short-title: Highlight the first line of a paragraph slug: Learn_web_development/Howto/Solve_CSS_problems/Highlight_first_line page-type: learn-faq +sidebar: learn-how-to --- -{{LearnSidebar}} - In this guide you will find out how to highlight the first line of text in a paragraph, even if you don't know how long that line will be. ## Styling the first line of text diff --git a/files/en-us/learn_web_development/howto/solve_css_problems/highlight_first_para/index.md b/files/en-us/learn_web_development/howto/solve_css_problems/highlight_first_para/index.md index 5b839709d64a527..ac884ea5e7116e7 100644 --- a/files/en-us/learn_web_development/howto/solve_css_problems/highlight_first_para/index.md +++ b/files/en-us/learn_web_development/howto/solve_css_problems/highlight_first_para/index.md @@ -1,11 +1,11 @@ --- title: How to highlight the first paragraph +short-title: Highlight the first paragraph slug: Learn_web_development/Howto/Solve_CSS_problems/Highlight_first_para page-type: learn-faq +sidebar: learn-how-to --- -{{LearnSidebar}} - In this guide you can find out how to highlight the first paragraph inside a container. ## Styling the first paragraph diff --git a/files/en-us/learn_web_development/howto/solve_css_problems/highlight_para_after_h1/index.md b/files/en-us/learn_web_development/howto/solve_css_problems/highlight_para_after_h1/index.md index 61d187f0a47abd2..8333eaeeacfbfd2 100644 --- a/files/en-us/learn_web_development/howto/solve_css_problems/highlight_para_after_h1/index.md +++ b/files/en-us/learn_web_development/howto/solve_css_problems/highlight_para_after_h1/index.md @@ -1,11 +1,11 @@ --- title: How to highlight a paragraph that comes after a heading +short-title: Highlight a paragraph after a heading slug: Learn_web_development/Howto/Solve_CSS_problems/Highlight_para_after_h1 page-type: learn-faq +sidebar: learn-how-to --- -{{LearnSidebar}} - In this guide you can find out how to highlight a paragraph that comes directly after a heading. ## Styling the first paragraph after a heading diff --git a/files/en-us/learn_web_development/howto/solve_css_problems/index.md b/files/en-us/learn_web_development/howto/solve_css_problems/index.md index e57540c89fa1199..8da36651bd044a0 100644 --- a/files/en-us/learn_web_development/howto/solve_css_problems/index.md +++ b/files/en-us/learn_web_development/howto/solve_css_problems/index.md @@ -1,11 +1,11 @@ --- title: Solve common CSS problems +short-title: Common CSS problems slug: Learn_web_development/Howto/Solve_CSS_problems page-type: landing-page +sidebar: learn-how-to --- -{{LearnSidebar}} - This page rounds up questions and answers, and other material on the MDN site that can help you to solve common CSS problems. ## Styling boxes diff --git a/files/en-us/learn_web_development/howto/solve_css_problems/make_box_transparent/index.md b/files/en-us/learn_web_development/howto/solve_css_problems/make_box_transparent/index.md index 95586c9c7acd39d..f5a64db6a5b3c28 100644 --- a/files/en-us/learn_web_development/howto/solve_css_problems/make_box_transparent/index.md +++ b/files/en-us/learn_web_development/howto/solve_css_problems/make_box_transparent/index.md @@ -1,11 +1,11 @@ --- title: How to make a box semi-transparent +short-title: Make a box semi-transparent slug: Learn_web_development/Howto/Solve_CSS_problems/Make_box_transparent page-type: learn-faq +sidebar: learn-how-to --- -{{LearnSidebar}} - This guide will help you to understand the ways to make a box semi-transparent using CSS. ## Change the opacity of the box and content diff --git a/files/en-us/learn_web_development/howto/solve_css_problems/transition_button/index.md b/files/en-us/learn_web_development/howto/solve_css_problems/transition_button/index.md index ca626524f4416ea..fff873222cad372 100644 --- a/files/en-us/learn_web_development/howto/solve_css_problems/transition_button/index.md +++ b/files/en-us/learn_web_development/howto/solve_css_problems/transition_button/index.md @@ -1,11 +1,11 @@ --- title: How to fade a button on hover +short-title: Fade a button on hover slug: Learn_web_development/Howto/Solve_CSS_problems/Transition_button page-type: learn-faq +sidebar: learn-how-to --- -{{LearnSidebar}} - In this guide you can find out how to do a gentle fade between two colors when hovering over a button. In our button example, we can change the background of our button by defining a different background color for the `:hover` dynamic pseudo-class. However, hovering over the button will cause the background-color to snap to the new color. To create a more gentle change between the two, we can use CSS Transitions. diff --git a/files/en-us/learn_web_development/howto/solve_html_problems/add_a_hit_map_on_top_of_an_image/index.md b/files/en-us/learn_web_development/howto/solve_html_problems/add_a_hit_map_on_top_of_an_image/index.md deleted file mode 100644 index 6856b0fe551ec80..000000000000000 --- a/files/en-us/learn_web_development/howto/solve_html_problems/add_a_hit_map_on_top_of_an_image/index.md +++ /dev/null @@ -1,124 +0,0 @@ ---- -title: Add a hitmap on top of an image -slug: Learn_web_development/Howto/Solve_HTML_problems/Add_a_hit_map_on_top_of_an_image -page-type: learn-faq ---- - -{{QuickLinksWithSubpages("/en-US/docs/Learn_web_development/Howto/Solve_HTML_problems")}} - -Here we go over how to set up an image map, and some downsides to consider first. - -<table> -<caption>Here are some things you need to know</caption> - <tbody> - <tr> - <th scope="row">Prerequisites:</th> - <td> - You should already know how to <a href="/en-US/docs/Learn_web_development/Getting_started/Your_first_website">create a basic HTML document</a> and how to <a href="/en-US/docs/Learn_web_development/Core/Structuring_content/HTML_images#how_do_we_put_an_image_on_a_webpage">add accessible images to a webpage.</a> - </td> - </tr> - <tr> - <th scope="row">Objective:</th> - <td> - Learn how to make different regions of one image link to different pages. - </td> - </tr> - </tbody> -</table> - -> [!WARNING] -> This article discusses client-side image maps only. Do not use server-side image maps, which require the user to have a mouse. - -## Image maps, and their drawbacks - -When you nest an image inside {{htmlelement('a')}}, the entire image links to one webpage. An image map, on the other hand, contains several active regions (called "hotspots") that each link to a different resource. - -Formerly, image maps were a popular navigation device, but it's important to thoroughly consider their performance and accessibility ramifications. - -> [!WARNING] -> Multiple images referencing the same image map may lead to unexpected browser behavior, severely degrading usability and accessibility. For example, when a user keyboard navigates an image with a re-used image map in Safari and Chromium-based browsers, latter image instances using that same image map are skipped entirely. In Firefox, all image maps get keyboard focus simultaneously and when the user keyboard navigates past the image, the next focused element is the one after the last image instance, effectively skipping everything between the two images. - -[Text links](/en-US/docs/Learn_web_development/Core/Structuring_content/Creating_links) (perhaps styled with CSS) are preferable to image maps for several reasons: text links are lightweight, maintainable, often more SEO-friendly, and support accessibility needs (e.g., screen readers, text-only browsers, translation services). - -## How to insert an image map, properly - -### Step 1: The image - -Not just any image is acceptable. - -- The image must make it clear what happens when people follow image links. `alt` text is mandatory, of course, but many people never see it. -- The image must clearly indicate where hotspots begin and end. -- Hotspots must be large enough to tap comfortably, at any viewport size. How large is large enough? [72 × 72 CSS pixels is a good minimum,](https://uxmovement.com/mobile/finger-friendly-design-ideal-mobile-touch-target-sizes/) with additional generous gaps between touch targets. The map of the world at [50languages.com](https://www.goethe-verlag.com/book2/) (as of time of writing) illustrates the problem perfectly. It's much easier to tap Russia or North America than Albania or Estonia. - -You insert your image [much the same way as always](/en-US/docs/Learn_web_development/Core/Structuring_content/HTML_images#how_do_we_put_an_image_on_a_webpage) (with an {{htmlelement("img")}} element and [`alt`](/en-US/docs/Web/HTML/Element/img#alt) text). If the image is only present as a navigation device, you may write `alt=""`, provided you furnish appropriate [`alt`](/en-US/docs/Web/HTML/Element/area#alt) text in the {{htmlelement('area')}} elements later on. - -You will need a special [`usemap`](/en-US/docs/Web/HTML/Element/img#usemap) attribute. Come up with a unique name, containing no spaces, for your image map. Then assign that name (preceded by a hash) as the value for the `usemap` attribute: - -```html -<img src="image-map.png" alt="" usemap="#example-map-1" /> -``` - -### Step 2: Activate your hotspots - -In this step, put all your code inside a {{htmlelement('map')}} element. `<map>` only needs one attribute, the same map [`name`](/en-US/docs/Web/HTML/Element/map#name) as you used in your `usemap` attribute above: - -```html -<map name="example-map-1"> </map> -``` - -Inside the `<map>` element, we need {{htmlelement('area')}} elements. An `<area>` element corresponds to a single hotspot. To keep keyboard navigation intuitive, make sure the source order of `<area>` elements corresponds to the visual order of hotspots. - -`<area>` elements are {{glossary("void element", "void elements")}}, but do require four attributes: - -- [`shape`](/en-US/docs/Web/HTML/Element/area#shape) - - - : The `shape` attribute takes one of four values: `circle`, `rect`, `poly`, and `default`. An `<area>` whose `shape` is `default` occupies the entire image, minus any other hotspots you've defined. - If there is any overlap between the defined areas, the source order determines which area takes preference. - The shape you choose determines the coordinate information you'll need to provide in `coords`. - -- [`coords`](/en-US/docs/Web/HTML/Element/area#coords) - - - : Coordinates are given in CSS pixels, and its value is dependent on the `shape` selected. - - - For a circle, provide the center's x and y coordinates, followed by the length of the radius. - - For a rectangle, provide the x and y coordinates of the upper-left and bottom-right corners. - - For a polygon, to provide the x and y coordinates of each corner (so, at least six values). - -- [`href`](/en-US/docs/Web/HTML/Element/area#href) - - - : The URL of the resource you're linking to. You may leave this attribute blank if you _don't_ want the current area to link anywhere (say, if you're making a hollow circle.) - -- [`alt`](/en-US/docs/Web/HTML/Element/area#alt) - - - : A mandatory attribute, telling people where the link goes or what it does. `alt` text only displays when the image is unavailable. Please refer to our [guidelines for writing accessible link text](/en-US/docs/Learn_web_development/Core/Structuring_content/Creating_links#use_clear_link_wording). - - You may write `alt=""` if the `href` attribute is blank _and_ the entire image already has an `alt` attribute. - -```html -<map name="example-map-1"> - <area - shape="circle" - coords="200,250,25" - href="page-2.html" - alt="circle example" /> - - <area - shape="rect" - coords="10, 5, 20, 15" - href="page-3.html" - alt="rectangle example" /> -</map> -``` - -### Step 3: Make sure it works for everybody - -You aren't done until you test image maps rigorously on many browsers and devices. Try following links with your keyboard alone. Try turning images off. - -If your image map is wider than about 240px, you'll need to make further adjustments to make your website responsive. It's not enough to resize the image for small screens, because the coordinates stay the same and no longer match the image. - -## Learn more - -- {{htmlelement("img")}} -- {{htmlelement("map")}} -- {{htmlelement("area")}} -- [Online image map editor](https://www.maschek.hu/imagemap/) diff --git a/files/en-us/learn_web_development/howto/solve_html_problems/author_fast-loading_html_pages/index.md b/files/en-us/learn_web_development/howto/solve_html_problems/author_fast-loading_html_pages/index.md deleted file mode 100644 index 029c91e7723ef9a..000000000000000 --- a/files/en-us/learn_web_development/howto/solve_html_problems/author_fast-loading_html_pages/index.md +++ /dev/null @@ -1,194 +0,0 @@ ---- -title: Tips for authoring fast-loading HTML pages -slug: Learn_web_development/Howto/Solve_HTML_problems/Author_fast-loading_HTML_pages -page-type: learn-faq ---- - -{{QuickLinksWithSubpages("/en-US/docs/Learn_web_development/Howto/Solve_HTML_problems")}} - -These tips are based on common knowledge and experimentation. - -An optimized web page not only provides for a more responsive site for your visitors but also reduces the load on your web servers and internet connection. This can be crucial for high volume sites or sites which have a spike in traffic due to unusual circumstances such as breaking news stories. - -Optimizing page load performance is not just for content which will be viewed by narrowband dial-up or mobile device visitors. It is just as important for broadband content and can lead to dramatic improvements even for your visitors with the fastest connections. - -## Tips - -### Reduce page weight - -Page weight is by far the most important factor in page-load performance. - -Reducing page weight through the elimination of unnecessary whitespace and comments, commonly known as minimization, and by moving inline script and CSS into external files, can improve download performance with minimal need for other changes in the page structure. - -Tools such as [HTML Tidy](https://www.html-tidy.org/) can automatically strip leading whitespace and extra blank lines from valid HTML source. Other tools can "compress" JavaScript by reformatting the source or by obfuscating the source and replacing long identifiers with shorter versions. - -### Minimize the number of files - -Reducing the number of files referenced in a web page lowers the number of [HTTP](/en-US/docs/Web/HTTP) connections required to download a page, thereby reducing the time for these requests to be sent, and for their responses to be received. - -Depending on a browser's cache settings, it may send a request with the [`If-Modified-Since`](/en-US/docs/Web/HTTP/Headers/If-Modified-Since) header for each referenced file, asking whether the file has been modified since the last time it was downloaded. Too much time spent querying the last modified time of the referenced files can delay the initial display of the web page, since the browser must check the modification time for each of these files, before rendering the page. - -If you use background images a lot in your CSS, you can reduce the number of HTTP lookups needed by combining the images into one, known as an image sprite. Then you just apply the same image each time you need it for a background and adjust the x/y coordinates appropriately. This technique works best with elements that will have limited dimensions, and will not work for every use of a background image. However, the fewer HTTP requests and single image caching can help reduce page-load time. - -### Use a Content Delivery Network (CDN) - -For the purposes of this article, a CDN is a means to reduce the physical distance between your server and your visitor. As the distance between your server origin and visitor increases, the load times will increase. Suppose your website server is located in the United States and it has a visitor from India; the page load time will be much higher for the Indian visitor compared to a visitor from the US. - -A CDN is a geographically distributed network of servers that work together to shorten the distance between the user and your website. CDNs store cached versions of your website and serve them to visitors via the network node closest to the user, thereby reducing [latency](/en-US/docs/Web/Performance/Guides/Understanding_latency). - -Further reading: - -- [Understanding CDNs](https://www.imperva.com/Learn_web_development/Extensions/Performance/what-is-cdn-how-it-works/) - -### Reduce domain lookups - -Since each separate domain costs time in a DNS lookup, the page load time will grow along with the number of separate domains appearing in CSS link(s) and JavaScript and image src(es). - -This may not always be practical; however, you should always take care to use only the minimum necessary number of different domains in your pages. - -### Cache reused content - -Make sure that any content that can be cached, is cached, and with appropriate expiration times. - -In particular, pay attention to the `Last-Modified` header. It allows for efficient page caching; by means of this header, information is conveyed to the user agent about the file it wants to load, such as when it was last modified. Most web servers automatically append the `Last-Modified` header to static pages (e.g. `.html`, `.css`), based on the last-modified date stored in the file system. With dynamic pages (e.g. `.php`, `.aspx`), this, of course, can't be done, and the header is not sent. - -So, in particular, for pages which are generated dynamically, a little research on this subject is beneficial. It can be somewhat involved, but it will save a lot in page requests on pages which would normally not be cacheable. - -More information: - -1. [HTTP Conditional Get for RSS Hackers](https://fishbowl.pastiche.org/2002/10/21/http_conditional_get_for_rss_hackers) -2. [HTTP 304: Not Modified](https://annevankesteren.nl/2005/05/http-304) -3. [HTTP ETag on Wikipedia](https://en.wikipedia.org/wiki/HTTP_ETag) -4. [Caching in HTTP](https://www.w3.org/Protocols/rfc2616/rfc2616-sec13.html) - -### Optimally order the components of the page - -Download page content first, along with any CSS or JavaScript that may be required for its initial display, so that the user gets the quickest apparent response during the page loading. This content is typically text, and can, therefore, benefit from text compression in transit, thus providing an even quicker response to the user. - -Any dynamic features that require the page to complete loading before being used, should be initially disabled, and then only enabled after the page has loaded. This will cause the JavaScript to be loaded after the page contents, which will improve the overall appearance of the page load. - -### Reduce the number of inline scripts - -Inline scripts can be expensive for page loading since the parser must assume that an inline script could modify the page structure while parsing is in progress. Reducing the use of inline scripts in general, and reducing the use of `document.write()` to output content in particular, can improve overall page loading. Use [DOM APIs to manipulate page content](/en-US/docs/Learn_web_development/Core/Scripting/DOM_scripting), rather than `document.write()`. - -### Use modern CSS and valid markup - -Use of modern CSS reduces the amount of markup, can reduce the need for (spacer) images, in terms of layout, and can very often replace images of stylized text — that "cost" much more than the equivalent text-and-CSS. - -Using valid markup has other advantages. First, browsers will have no need to perform error-correction when parsing the HTML (this is aside from the philosophical issue of whether to allow format variation in user input and then programmatically "correct" or normalize it; or whether, instead, to enforce a strict, no-tolerance input format). - -Moreover, valid markup allows for the free use of other tools that can _pre-process_ your web pages. For example, [HTML Tidy](https://www.html-tidy.org/) can remove whitespace and optional ending tags; however, it will refuse to run on a page with serious markup errors. - -### Chunk your content - -Tables for layouts are a legacy method that should not be used anymore. Layouts utilizing [floats](/en-US/docs/Learn_web_development/Core/CSS_layout/Floats), [positioning](/en-US/docs/Learn_web_development/Core/CSS_layout/Positioning), [flexbox](/en-US/docs/Learn_web_development/Core/CSS_layout/Flexbox), or [grids](/en-US/docs/Learn_web_development/Core/CSS_layout/Grids) should be used instead. - -Tables are still considered valid markup but should be used for displaying tabular data. To help the browser render your page quicker, you should avoid nesting your tables. - -Rather than deeply nesting tables as in: - -```html -<table> - <table> - <table> - … - </table> - </table> -</table> -``` - -use non-nested tables or divs as in - -```html -<table> - … -</table> -<table> - … -</table> -<table> - … -</table> -``` - -See also: [CSS flexible box layout](https://www.w3.org/TR/css-flexbox-1/) and [CSS grid layout](https://www.w3.org/TR/css-grid-1/) specifications. - -### Minify and compress SVG assets - -SVG produced by most drawing applications often contains unnecessary metadata which can be removed. Configure your servers, apply gzip compression for SVG assets. - -### Minify and compress your images - -Large images cause your page to take more time to load. Consider compressing your images before adding them to your page, using compression features built into image-manipulation tools such as Photoshop, or using a specialized tool such as [Compress JPEG](https://compressjpeg.com/) or [Tiny PNG](https://tinypng.com/). - -### Specify sizes for images and tables - -If the browser can immediately determine the height and/or width of your images and tables, it will be able to display a web page without having to reflow the content. This not only speeds the display of the page but prevents annoying changes in a page's layout when the page completes loading. For this reason, `height` and `width` should be specified for images, whenever possible. - -Tables should use the CSS selector: property combination: - -```css -table-layout: fixed; -``` - -and should specify widths of columns using the [`<col>`](/en-US/docs/Web/HTML/Element/col) and the [`<colgroup>`](/en-US/docs/Web/HTML/Element/colgroup) elements. - -### Use lazy loading for images - -By default, images are loaded **eagerly**; that is, the image is fetched and rendered as soon as it's processed in the HTML. All eagerly loaded images are rendered before the window's [`load`](/en-US/docs/Web/API/Window/load_event) event is sent. Switching to lazy loading of images tells the browser to hold off on loading images until they're about to be needed to draw the {{Glossary("visual viewport")}}. - -To mark an image for lazy loading, specify its [`loading`](/en-US/docs/Web/HTML/Element/img#loading) attribute with a value of `lazy`. With this set, the image will only be loaded when it's needed. - -```html -<img src="./images/footerlogo.jpg" loading="lazy" alt="MDN logo" /> -``` - -Note that lazily-loaded images may not be available when the `load` event is fired. You can determine if a given image is loaded by checking to see if the value of its Boolean {{domxref("HTMLImageElement.complete", "complete")}} property is `true`. - -### Choose your user-agent requirements wisely - -To achieve the greatest improvements in page design, make sure that reasonable user-agent requirements are specified for projects. Do not require your content to appear pixel-perfect in all browsers, especially not in down-version browsers. - -Ideally, your basic minimum requirements should be based on the consideration of modern browsers that support the relevant standards. This can include recent versions of Firefox, Google Chrome, Opera, and Safari. - -Note, however, that many of the tips listed in this article are common-sense techniques which apply to any user agent, and can be applied to any web page, regardless of browser-support requirements. - -### Use async and defer, if possible - -Make the JavaScript scripts such that they are compatible with both the [async](/en-US/docs/Web/HTML/Element/script#attributes) and the [defer](/en-US/docs/Web/HTML/Element/script#attributes) attributes, and use [async](/en-US/docs/Web/HTML/Element/script#attributes) whenever possible, especially if you have multiple script elements. - -With that, the page can stop rendering while JavaScript is still loading. Otherwise, the browser will not render anything that is after the script elements that do not have these attributes. - -Note: Even though these attributes do help a lot the first time a page is loaded, you should use them but not assume they will work in all browsers. If you already follow all JavaScript best practices, there is no need to change your code. - -## Example page structure - -- `{{htmlelement('html')}}` - - - `{{htmlelement('head')}}` - - - `{{htmlelement('link')}}` - - CSS files required for page appearance. Minimize the number of files for performance while keeping unrelated CSS in separate files for maintenance. - - - `{{htmlelement('script')}}` - - JavaScript files for functions **required** during the loading of the page, but not any interaction related JavaScript that can only run after page loads. - - Minimize the number of files for performance while keeping unrelated JavaScript in separate files for maintenance. - - - `{{htmlelement('body')}}` - - User visible page content in small chunks (`{{htmlelement('header')}}`/ `{{htmlelement('main')}}/` `{{htmlelement('table')}}`) that can be displayed without waiting for the full page to download. - - - `{{htmlelement('script')}}` - - Any scripts which will be used to perform interactivity. Interaction scripts typically can only run after the page has completely loaded and all necessary objects have been initialized. There is no need to load these scripts before the page content. That only slows down the initial appearance of the page load. - - Minimize the number of files for performance while keeping unrelated JavaScript in separate files for maintenance. - -## See also - -- Book: ["Speed Up Your Site" by Andy King](https://www.websiteoptimization.com/) -- [Learn performance](https://web.dev/learn/performance) via web.dev (2023) -- Tools for analyzing and optimizing performance: [Google PageSpeed Tools](https://developers.google.com/speed) and [PageSpeed Insights](https://pagespeed.web.dev/) diff --git a/files/en-us/learn_web_development/howto/solve_html_problems/cheatsheet/index.md b/files/en-us/learn_web_development/howto/solve_html_problems/cheatsheet/index.md deleted file mode 100644 index d5bf124c18326de..000000000000000 --- a/files/en-us/learn_web_development/howto/solve_html_problems/cheatsheet/index.md +++ /dev/null @@ -1,351 +0,0 @@ ---- -title: HTML Cheat Sheet -slug: Learn_web_development/Howto/Solve_HTML_problems/Cheatsheet -page-type: guide ---- - -{{LearnSidebar}} - -While using {{Glossary("HTML")}} it can be very handy to have an easy way to remember how to use HTML tags properly and how to apply them. MDN provides you with extended [HTML reference documentation](/en-US/docs/Web/HTML/Element) as well as a deep instructional [set of HTML guides](/en-US/docs/Learn_web_development/Core/Structuring_content). However, in many cases we just need some quick hints as we go. That's the whole purpose of the cheat sheet, to give you some quick accurate ready to use code snippets for common usages. - -> [!NOTE] -> HTML tags must be used for their semantic value, not their appearance. It's always possible to totally change the look and feel of a given tag using {{Glossary("CSS")}} so, when using HTML, take the time to focus on the meaning rather than the appearance. - -## Inline elements - -An "element" is a single part of a webpage. Some elements are large and hold smaller elements like containers. Some elements are small and are "nested" inside larger ones. By default, "inline elements" appear next to one another in a webpage. They take up only as much width as they need in a page and fit together horizontally like words in a sentence or books shelved side-by-side in a row. All inline elements can be placed within the `<body>` element. - -<table class="standard-table"> - <caption>Inline elements: usage and examples</caption> - <thead> - <tr> - <th scope="col">Usage</th> - <th scope="col">Element</th> - <th scope="col">Example</th> - </tr> - </thead> - <tbody> - <tr> - <td>A link</td> - <td>{{HTMLElement("a")}}</td> - <td id="a-example"> - <pre class="brush: html"> -&#x3C;a href="https://example.org"> -A link to example.org&#x3C;/a>.</pre - > - {{EmbedLiveSample("a-example", 100, 60)}} - </td> - </tr> - <tr> - <td>An image</td> - <td>{{HTMLElement("img")}}</td> - <td id="img-example"> - <pre class="brush: html">&#x3C;img src="beast.png" width="50" /></pre> - {{EmbedLiveSample("img-example", 100, 60)}} - </td> - </tr> - <tr> - <td>An inline container</td> - <td>{{HTMLElement("span")}}</td> - <td id="span-example"> - <pre class="brush: html"> -Used to group elements: for example, -to &#x3C;span style="color:blue">style -them&#x3C;/span>.</pre - > - {{EmbedLiveSample("span-example", 100, 60)}} - </td> - </tr> - <tr> - <td>Emphasize text</td> - <td>{{HTMLElement("em")}}</td> - <td id="em-example"> - <pre class="brush: html">&#x3C;em>I'm posh&#x3C;/em>.</pre> - {{EmbedLiveSample("em-example", 100, 60)}} - </td> - </tr> - <tr> - <td>Italic text</td> - <td>{{HTMLElement("i")}}</td> - <td id="i-example"> - <pre class="brush: html"> -Mark a phrase in &#x3C;i>italics&#x3C;/i>.</pre - > - {{EmbedLiveSample("i-example", 100, 60)}} - </td> - </tr> - <tr> - <td>Bold text</td> - <td>{{HTMLElement("b")}}</td> - <td id="b-example"> - <pre class="brush: html">Bold &#x3C;b>a word or phrase&#x3C;/b>.</pre> - {{EmbedLiveSample("b-example", 100, 60)}} - </td> - </tr> - <tr> - <td>Important text</td> - <td>{{HTMLElement("strong")}}</td> - <td id="strong-example"> - <pre class="brush: html">&#x3C;strong>I'm important!&#x3C;/strong></pre> - {{EmbedLiveSample("strong-example", 100, 60)}} - </td> - </tr> - <tr> - <td>Highlight text</td> - <td>{{HTMLElement("mark")}}</td> - <td id="mark-example"> - <pre class="brush: html">&#x3C;mark>Notice me!&#x3C;/mark></pre> - {{EmbedLiveSample("mark-example", 100, 60)}} - </td> - </tr> - <tr> - <td>Strikethrough text</td> - <td>{{HTMLElement("s")}}</td> - <td id="s-example"> - <pre class="brush: html">&#x3C;s>I'm irrelevant.&#x3C;/s></pre> - {{EmbedLiveSample("s-example", 100, 60)}} - </td> - </tr> - <tr> - <td>Subscript</td> - <td>{{HTMLElement("sub")}}</td> - <td id="sub-example"> - <pre class="brush: html">H&#x3C;sub>2&#x3C;/sub>O</pre> - {{EmbedLiveSample("sub-example", 100, 60)}} - </td> - </tr> - <tr> - <td>Small text</td> - <td>{{HTMLElement("small")}}</td> - <td id="small-example"> - <pre class="brush: html"> -Used to represent the &#x3C;small>small -print &#x3C;/small>of a document.</pre - > - {{EmbedLiveSample("small-example", 100, 60)}} - </td> - </tr> - <tr> - <td>Address</td> - <td>{{HTMLElement("address")}}</td> - <td id="address-example"> - <pre class="brush: html"> -&#x3C;address>Main street 67&#x3C;/address></pre - > - {{EmbedLiveSample("address-example", 100, 60)}} - </td> - </tr> - <tr> - <td>Textual citation</td> - <td>{{HTMLElement("cite")}}</td> - <td id="cite-example"> - <pre class="brush: html"> -For more monsters, -see &#x3C;cite>The Monster Book of Monsters&#x3C;/cite>.</pre - > - {{EmbedLiveSample("cite-example", 100, 60)}} - </td> - </tr> - <tr> - <td>Superscript</td> - <td>{{HTMLElement("sup")}}</td> - <td id="sup-example"> - <pre class="brush: html">x&#x3C;sup>2&#x3C;/sup></pre> - {{EmbedLiveSample("sup-example", 100, 60)}} - </td> - </tr> - <tr> - <td>Inline quotation</td> - <td>{{HTMLElement("q")}}</td> - <td id="q-example"> - <pre class="brush: html">&#x3C;q>Me?&#x3C;/q>, she said.</pre> - {{EmbedLiveSample("q-example", 100, 60)}} - </td> - </tr> - <tr> - <td>A line break</td> - <td>{{HTMLElement("br")}}</td> - <td id="br-example"> - <pre class="brush: html">Line 1&#x3C;br>Line 2</pre> - {{EmbedLiveSample("br-example", 100, 80)}} - </td> - </tr> - <tr> - <td>A possible line break</td> - <td>{{HTMLElement("wbr")}}</td> - <td id="wbr-example"> - <pre class="brush: html"> -&#x3C;div style="width: 200px"> - Llanfair&#x3C;wbr>pwllgwyngyll&#x3C;wbr>gogerychwyrndrobwllllantysiliogogogoch. -&#x3C;/div></pre - > - {{EmbedLiveSample("wbr-example", 100, 80)}} - </td> - </tr> - <tr> - <td>Date</td> - <td>{{HTMLElement("time")}}</td> - <td id="time-example"> - <pre class="brush: html"> -Used to format the date. For example: -&#x3C;time datetime="2020-05-24"> -published on 23-05-2020&#x3C;/time>.</pre - > - {{EmbedLiveSample("time-example", 100, 60)}} - </td> - </tr> - <tr> - <td>Code format</td> - <td>{{HTMLElement("code")}}</td> - <td id="code-example"> - <pre class="brush: html"> -This text is in normal format, -but &#x3C;code>this text is in code -format&#x3C;/code>.</pre - > - {{EmbedLiveSample("code-example", 100, 60)}} - </td> - </tr> - <tr> - <td>Audio</td> - <td>{{HTMLElement("audio")}}</td> - <td id="audio-example"> - <pre class="brush: html"> -&#x3C;audio controls> - &#x3C;source src="https://interactive-examples.mdn.mozilla.net/media/cc0-audio/t-rex-roar.mp3" type="audio/mpeg"> -&#x3C;/audio> - </pre> - {{EmbedLiveSample("audio-example", 100, 80)}} - </td> - </tr> - <tr> - <td>Video</td> - <td>{{HTMLElement("video")}}</td> - <td id="video-example"> - <pre class="brush: html"> -&#x3C;video controls width="250" - src="https://archive.org/download/ElephantsDream/ed_hd.ogv" > - &#x3C;a href="https://archive.org/download/ElephantsDream/ed_hd.ogv">Download OGV video&#x3C;/a> -&#x3C;/video></pre - > - {{EmbedLiveSample("video-example", 100, 200)}} - </td> - </tr> - </tbody> -</table> - -## Block elements - -"Block elements," on the other hand, take up the entire width of a webpage. They also take up a full line of a webpage; they do not fit together side-by-side. Instead, they stack like paragraphs in an essay or toy blocks in a tower. - -> [!NOTE] -> Because this cheat sheet is limited to a few elements representing specific structures or having special semantics, the [`div`](/en-US/docs/Web/HTML/Element/div) element is intentionally not included — because the `div` element doesn't represent anything and doesn't have any special semantics. - -<table class="standard-table"> - <thead> - <tr> - <th scope="col">Usage</th> - <th scope="col">Element</th> - <th scope="col">Example</th> - </tr> - </thead> - <tbody> - <tr> - <td>A simple paragraph</td> - <td>{{HTMLElement("p")}}</td> - <td id="p-example"> - <pre class="brush: html"> -&#x3C;p>I'm a paragraph&#x3C;/p> -&#x3C;p>I'm another paragraph&#x3C;/p></pre - > - {{EmbedLiveSample("p-example", 100, 150)}} - </td> - </tr> - <tr> - <td>An extended quotation</td> - <td>{{HTMLElement("blockquote")}}</td> - <td id="blockquote-example"> - <pre class="brush: html"> -They said: -&#x3C;blockquote>The blockquote element indicates -an extended quotation.&#x3C;/blockquote></pre - > - {{EmbedLiveSample("blockquote-example", 100, 100)}} - </td> - </tr> - <tr> - <td>Additional information</td> - <td>{{HTMLElement("details")}}</td> - <td id="details-example"> - <pre class="brush: html"> -&#x3C;details> - &#x3C;summary>HTML Cheat Sheet&#x3C;/summary> - &#x3C;p>Inline elements&#x3C;/p> - &#x3C;p>Block elements&#x3C;/p> -&#x3C;/details></pre - > - {{EmbedLiveSample("details-example", 100, 150)}} - </td> - </tr> - <tr> - <td>An unordered list</td> - <td>{{HTMLElement("ul")}}</td> - <td id="ul-example"> - <pre class="brush: html">&#x3C;ul> - &#x3C;li>I'm an item&#x3C;/li> - &#x3C;li>I'm another item&#x3C;/li> -&#x3C;/ul></pre> - {{EmbedLiveSample("ul-example", 100, 100)}} - </td> - </tr> - <tr> - <td>An ordered list</td> - <td>{{HTMLElement("ol")}}</td> - <td id="ol-example"> - <pre class="brush: html">&#x3C;ol> - &#x3C;li>I'm the first item&#x3C;/li> - &#x3C;li>I'm the second item&#x3C;/li> -&#x3C;/ol></pre> - {{EmbedLiveSample("ol-example", 100, 100)}} - </td> - </tr> - <tr> - <td>A definition list</td> - <td>{{HTMLElement("dl")}}</td> - <td id="dl-example"> - <pre class="brush: html">&#x3C;dl> - &#x3C;dt>A Term&#x3C;/dt> - &#x3C;dd>Definition of a term&#x3C;/dd> - &#x3C;dt>Another Term&#x3C;/dt> - &#x3C;dd>Definition of another term&#x3C;/dd> -&#x3C;/dl></pre> - {{EmbedLiveSample("dl-example", 100, 150)}} - </td> - </tr> - <tr> - <td>A horizontal rule</td> - <td>{{HTMLElement("hr")}}</td> - <td id="hr-example"> - <pre class="brush: html">before&#x3C;hr>after</pre> - {{EmbedLiveSample("hr-example", 100, 100)}} - </td> - </tr> - <tr> - <td>Text Heading</td> - <td> - {{HTMLElement("Heading_Elements", "&lt;h1&gt;-&lt;h6&gt;")}} - </td> - <td id="h1-h6-example"> - <pre class="brush: html"> -&#x3C;h1> This is Heading 1 &#x3C;/h1> -&#x3C;h2> This is Heading 2 &#x3C;/h2> -&#x3C;h3> This is Heading 3 &#x3C;/h3> -&#x3C;h4> This is Heading 4 &#x3C;/h4> -&#x3C;h5> This is Heading 5 &#x3C;/h5> -&#x3C;h6> This is Heading 6 &#x3C;/h6></pre - > - {{EmbedLiveSample("h1-h6-example", 100, 350)}} - </td> - </tr> - </tbody> -</table> diff --git a/files/en-us/learn_web_development/howto/solve_html_problems/define_terms_with_html/index.md b/files/en-us/learn_web_development/howto/solve_html_problems/define_terms_with_html/index.md deleted file mode 100644 index 364399b88b1aa3f..000000000000000 --- a/files/en-us/learn_web_development/howto/solve_html_problems/define_terms_with_html/index.md +++ /dev/null @@ -1,144 +0,0 @@ ---- -title: Define terms with HTML -slug: Learn_web_development/Howto/Solve_HTML_problems/Define_terms_with_HTML -page-type: learn-faq ---- - -{{QuickLinksWithSubpages("/en-US/docs/Learn_web_development/Howto/Solve_HTML_problems")}} - -HTML provides several ways to convey description semantics, whether inline or as structured glossaries. In this article, we'll cover how to properly mark up keywords when you're defining them. - -<table class="standard-table"> - <tbody> - <tr> - <th scope="row">Prerequisites:</th> - <td> - You need to be familiar with how to - <a href="/en-US/docs/Learn_web_development/Getting_started/Your_first_website" - >create a basic HTML document</a - >. - </td> - </tr> - <tr> - <th scope="row">Objective:</th> - <td> - Learn how to introduce new keywords and how to build description lists. - </td> - </tr> - </tbody> -</table> - -When you need a term defined, you probably go straight to a dictionary or glossary. Dictionaries and glossaries _formally_ associate keywords with one or more descriptions, as in this case: - -> - Blue (_Adjective_) -> - : Of a color like the sky in a sunny day. -> _"The clear blue sky"_ - -But we're constantly defining keywords informally, as here: - -> **Firefox** is the web browser created by the Mozilla Foundation. - -To deal with these use cases, {{Glossary("HTML")}} provides {{Glossary("tag","tags")}} to mark descriptions and words described, so that your meaning gets across properly to your readers. - -## How to mark informal description - -In textbooks, the first time a keyword occurs, it's common to put the keyword in bold and define it right away. - -We do that in HTML too, except HTML is not a visual medium and so we don't use bold. We use {{htmlelement("dfn")}}, which is a special element just for marking the first occurrence of keywords. Note that `<dfn>` tags go around the _word to be defined,_ not the definition (the definition consists of the entire paragraph): - -```html -<p><dfn>Firefox</dfn> is the web browser created by the Mozilla Foundation.</p> -``` - -> [!NOTE] -> Another use for bold is to emphasize content. Bold itself is a concept foreign to HTML, but there are [tags for indicating emphasis.](/en-US/docs/Learn_web_development/Core/Structuring_content/Emphasis_and_importance) - -### Special case: Abbreviations - -It's best to [mark abbreviations specially](/en-US/docs/Learn_web_development/Core/Structuring_content/Advanced_text_features#abbreviations) with {{htmlelement("abbr")}}, so that screen readers read them appropriately and so that you can operate on all abbreviations uniformly. Just as with any new keyword, you should define your abbreviations the first time they occur. - -```html -<p> - <dfn><abbr>HTML</abbr> (hypertext markup language)</dfn> - is a description language used to structure documents on the web. -</p> -``` - -> [!NOTE] -> The HTML spec does indeed [set aside the `title` attribute](https://html.spec.whatwg.org/multipage/text-level-semantics.html#the-abbr-element) for expanding the abbreviation. However, this is not an acceptable alternative for providing an inline expansion. The contents of `title` are completely hidden from your users, unless they're using a mouse and they happen to hover over the abbreviation. The spec duly [acknowledges this as well.](https://html.spec.whatwg.org/multipage/dom.html#attr-title) - -### Improve accessibility - -{{HTMLElement('dfn')}} marks the keyword defined, and indicates that the current paragraph defines the keyword. In other words, there's an implicit relationship between the `<dfn>` element and its container. If you want a more formal relationship, or your definition consists of only one sentence rather than the whole paragraph, you can use the [`aria-describedby`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-describedby) attribute to associate a term more formally with its definition: - -```html -<p> - <span id="ff"> - <dfn aria-describedby="ff">Firefox</dfn> - is the web browser created by the Mozilla Foundation. - </span> - You can download it at <a href="https://www.mozilla.org">mozilla.org</a> -</p> -``` - -Assistive technology can often use this attribute to find a text alternative to a given term. You can use `aria-describedby` on any tag enclosing a keyword to be defined (not just the `<dfn>` element). `aria-describedby` references the [`id`](/en-US/docs/Web/HTML/Global_attributes/id) of the element containing the description. - -## How to build a description list - -Description lists are just what they claim to be: a list of terms and their matching descriptions (e.g., definition lists, dictionary entries, FAQs, and key-value pairs). - -> [!NOTE] -> Description lists are [not suitable for marking up dialog,](https://html.spec.whatwg.org/multipage/grouping-content.html#the-dl-element) because conversation does not directly describe the speakers. Here are [recommendations for marking up dialog](https://html.spec.whatwg.org/multipage/semantics-other.html#conversations). - -The terms described go inside {{htmlelement("dt")}} elements. The matching description follows immediately, contained within one or more {{htmlelement("dd")}} elements. Enclose the whole description list with a {{htmlelement("dl")}} element. - -### A simple example - -Here's an example describing kinds of food and drink: - -```html -<dl> - <dt>jambalaya</dt> - <dd> - rice-based entree typically containing chicken, sausage, seafood, and spices - </dd> - - <dt>sukiyaki</dt> - <dd> - Japanese specialty consisting of thinly sliced meat, vegetables, and - noodles, cooked in sake and soy sauce - </dd> - - <dt>chianti</dt> - <dd>dry Italian red wine originating in Tuscany</dd> -</dl> -``` - -> [!NOTE] -> The basic pattern, as you can see, is to alternate `<dt>` terms with `<dd>` descriptions. If two or more terms occur in a row, the following description applies to all of them. If two or more descriptions occur in a row, they all apply to the last given term. - -### Improving the visual output - -Here's how a graphical browser displays the foregoing list: - -{{EmbedLiveSample("A_simple_example", 600, 180)}} - -If you want the keywords to stand out better, you could try bolding them. Remember, HTML is not a visual medium; we need {{glossary("CSS")}} for all visual effects. The CSS {{cssxref("font-weight")}} property is what you need here: - -```css -dt { - font-weight: bold; -} -``` - -This produces the slightly more readable result below: - -{{EmbedLiveSample("How_to_build_a_description_list", 600, 180)}} - -## Learn more - -- {{htmlelement("dfn")}} -- {{htmlelement("dl")}} -- {{htmlelement("dt")}} -- {{htmlelement("dd")}} -- [How to use the aria-describedby attribute](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-describedby) diff --git a/files/en-us/learn_web_development/howto/solve_html_problems/index.md b/files/en-us/learn_web_development/howto/solve_html_problems/index.md index 297f159d62be67f..6f266348d997e67 100644 --- a/files/en-us/learn_web_development/howto/solve_html_problems/index.md +++ b/files/en-us/learn_web_development/howto/solve_html_problems/index.md @@ -1,11 +1,11 @@ --- title: Solve common HTML problems +short-title: Common HTML problems slug: Learn_web_development/Howto/Solve_HTML_problems page-type: landing-page +sidebar: learn-how-to --- -{{LearnSidebar}} - The following links point to solutions to common everyday problems you'll need to solve with HTML. ### Basic structure @@ -27,7 +27,7 @@ HTML specializes in providing semantic information for a document, so HTML answe - [How to annotate images and graphics](/en-US/docs/Learn_web_development/Core/Structuring_content/HTML_images#annotating_images_with_figures_and_figure_captions) - [How to mark abbreviations and make them understandable](/en-US/docs/Learn_web_development/Core/Structuring_content/Advanced_text_features#abbreviations) - [How to add quotations and citations to web pages](/en-US/docs/Learn_web_development/Core/Structuring_content/Advanced_text_features#quotations) -- [How to define terms with HTML](/en-US/docs/Learn_web_development/Howto/Solve_HTML_problems/Define_terms_with_HTML) +- [How to define terms with HTML](/en-US/docs/Web/HTML/How_to/Define_terms_with_HTML) ### Hyperlinks @@ -46,7 +46,7 @@ One of the main reasons for HTML is making navigation easy with {{Glossary("hype HTML only sets up document structure. To solve presentation issues, use {{glossary("CSS")}}, or use scripting to make your page interactive. - [How to use CSS within a webpage](/en-US/docs/Learn_web_development/Core/Styling_basics/Getting_started#adding_css_to_our_document) -- [How to use JavaScript within a webpage](/en-US/docs/Learn_web_development/Howto/Solve_HTML_problems/Use_JavaScript_within_a_webpage) +- [How to use JavaScript within a webpage](/en-US/docs/Web/HTML/How_to/Add_JavaScript_to_your_web_page) ### Embedded content @@ -73,18 +73,18 @@ Some information, called tabular data, needs to be organized into tables with co ### Data representation - How to represent numeric and code values with HTML — see [Superscript and Subscript](/en-US/docs/Learn_web_development/Core/Structuring_content/Advanced_text_features#superscript_and_subscript), and [Representing computer code](/en-US/docs/Learn_web_development/Core/Structuring_content/Advanced_text_features#representing_computer_code). -- [How to use data attributes](/en-US/docs/Learn_web_development/Howto/Solve_HTML_problems/Use_data_attributes) +- [How to use data attributes](/en-US/docs/Web/HTML/How_to/Use_data_attributes) ### Advanced text semantics -- [How to take control of HTML line breaking](/en-US/docs/Web/HTML/Element/br) +- [How to take control of HTML line breaking](/en-US/docs/Web/HTML/Reference/Elements/br) - How to mark changes (added and removed text) — see the {{htmlelement("ins")}} and {{htmlelement("del")}} elements. ### Advanced images & multimedia -- [How to add a responsive image to a webpage](/en-US/docs/Web/HTML/Responsive_images) +- [How to add a responsive image to a webpage](/en-US/docs/Web/HTML/Guides/Responsive_images) - [How to add vector image to a webpage](/en-US/docs/Learn_web_development/Core/Structuring_content/Including_vector_graphics_in_HTML) -- [How to add a hit map on top of an image](/en-US/docs/Learn_web_development/Howto/Solve_HTML_problems/Add_a_hit_map_on_top_of_an_image) +- [How to add a hit map on top of an image](/en-US/docs/Web/HTML/How_to/Add_a_hit_map_on_top_of_an_image) ### Internationalization @@ -95,8 +95,8 @@ HTML is not monolingual. It provides tools to handle common internationalization ### Performance -- [How to author fast-loading HTML pages](/en-US/docs/Learn_web_development/Howto/Solve_HTML_problems/Author_fast-loading_HTML_pages) +- [How to author fast-loading HTML pages](/en-US/docs/Web/HTML/How_to/Author_fast-loading_HTML_pages) ## See also -- [HTML Cheatsheet](/en-US/docs/Learn_web_development/Howto/Solve_HTML_problems/Cheatsheet) +- [HTML Cheatsheet](/en-US/docs/Web/HTML/Guides/Cheatsheet) diff --git a/files/en-us/learn_web_development/howto/solve_html_problems/use_data_attributes/index.md b/files/en-us/learn_web_development/howto/solve_html_problems/use_data_attributes/index.md deleted file mode 100644 index 6f3cc4673c2b849..000000000000000 --- a/files/en-us/learn_web_development/howto/solve_html_problems/use_data_attributes/index.md +++ /dev/null @@ -1,110 +0,0 @@ ---- -title: Using data attributes -slug: Learn_web_development/Howto/Solve_HTML_problems/Use_data_attributes -page-type: learn-faq ---- - -{{QuickLinksWithSubpages("/en-US/docs/Learn_web_development/Howto/Solve_HTML_problems")}} - -HTML is designed with extensibility in mind for data that should be associated with a particular element but need not have any defined meaning. [`data-*` attributes](/en-US/docs/Web/HTML/Global_attributes/data-*) allow us to store extra information on standard, semantic HTML elements without other hacks such as non-standard attributes, or extra properties on DOM. - -## HTML syntax - -The syntax is simple. Any attribute on any element whose attribute name starts with `data-` is a data attribute. Say you have some articles and you want to store some extra information that doesn't have any visual representation. Just use `data` attributes for that: - -```html -<main> - <article - id="electric-cars" - data-columns="3" - data-index-number="12314" - data-parent="cars"> - <!-- Electric car content --> - </article> - - <article - id="solar-cars" - data-columns="3" - data-index-number="12315" - data-parent="cars"> - <!-- Solar car content --> - </article> - - <article - id="flying-cars" - data-columns="4" - data-index-number="12316" - data-parent="cars"> - <!-- Flying car content --> - </article> -</main> -``` - -## JavaScript access - -Reading the values of these attributes out in [JavaScript](/en-US/docs/Web/JavaScript) is also very simple. You could use {{domxref("Element.getAttribute", "getAttribute()")}} with their full HTML name to read them, but the standard defines a simpler way: a {{domxref("DOMStringMap")}} you can read out via a {{domxref("HTMLElement/dataset", "dataset")}} property. - -To get a `data` attribute through the `dataset` object, get the property by the part of the attribute name after `data-` (note that dashes are converted to {{Glossary("camel_case", "camel case")}}). - -```js -const article = document.querySelector("#electric-cars"); -// The following would also work: -// const article = document.getElementById("electric-cars") - -article.dataset.columns; // "3" -article.dataset.indexNumber; // "12314" -article.dataset.parent; // "cars" -``` - -Each property is a string and can be read and written. In the above case setting `article.dataset.columns = 5` would change that attribute to `"5"`. - -You can also use [`document.querySelector()`](/en-US/docs/Web/API/Document/querySelector) or [`document.querySelectorAll()`](/en-US/docs/Web/API/Document/querySelectorAll) with data attribute selectors to find one element or all elements that match: - -```js -// Find all elements with a data-columns attribute -const articles = document.querySelectorAll("[data-columns]"); - -// Find all elements with data-columns="3" -const threeColumnArticles = document.querySelectorAll('[data-columns="3"]'); -// You can then iterate over the results -threeColumnArticles.forEach((article) => { - console.log(article.dataset.indexNumber); -}); -``` - -## CSS access - -Note that, as data attributes are plain HTML attributes, you can even access them from [CSS](/en-US/docs/Web/CSS). For example to show the parent data on the article you can use [generated content](/en-US/docs/Web/CSS/content) in CSS with the [`attr()`](/en-US/docs/Web/CSS/attr) function: - -```css -article::before { - content: attr(data-parent); -} -``` - -You can also use the [attribute selectors](/en-US/docs/Web/CSS/Attribute_selectors) in CSS to change styles according to the data: - -```css -article[data-columns="3"] { - width: 400px; -} -article[data-columns="4"] { - width: 600px; -} -``` - -You can see all this working together [in this JS Bin example](https://jsbin.com/ujiday/2/edit). - -Data attributes can also be stored to contain information that is constantly changing, like scores in a game. Using the CSS selectors and JavaScript access here this allows you to build some nifty effects without having to write your own display routines. See [this screencast](https://www.youtube.com/watch?v=On_WyUB1gOk) for an example using generated content and CSS transitions ([JS Bin example](https://jsbin.com/atawaz/3/edit)). - -Data values are strings. Number values must be quoted in the selector for the styling to take effect. - -## Issues - -Do not store content that should be visible and accessible in data attributes, because assistive technology may not access them. In addition, search crawlers may not index data attributes' values. - -## See also - -- This article is adapted from [Using data attributes in JavaScript and CSS on hacks.mozilla.org](https://hacks.mozilla.org/2012/10/using-data-attributes-in-javascript-and-css/). -- Custom attributes are also supported in SVG 2; see {{domxref("HTMLElement.dataset")}} and {{SVGAttr("data-*")}} for more information. -- [How to use HTML data attributes](https://www.sitepoint.com/how-why-use-html5-custom-data-attributes/) (Sitepoint) diff --git a/files/en-us/learn_web_development/howto/solve_html_problems/use_javascript_within_a_webpage/index.md b/files/en-us/learn_web_development/howto/solve_html_problems/use_javascript_within_a_webpage/index.md deleted file mode 100644 index 5e66be35309d988..000000000000000 --- a/files/en-us/learn_web_development/howto/solve_html_problems/use_javascript_within_a_webpage/index.md +++ /dev/null @@ -1,95 +0,0 @@ ---- -title: Use JavaScript within a webpage -slug: Learn_web_development/Howto/Solve_HTML_problems/Use_JavaScript_within_a_webpage -page-type: learn-faq ---- - -{{QuickLinksWithSubpages("/en-US/docs/Learn_web_development/Howto/Solve_HTML_problems")}} - -Take your webpages to the next level by harnessing JavaScript. Learn in this article how to trigger JavaScript right from your HTML documents. - -<table> - <tbody> - <tr> - <th scope="row">Prerequisites:</th> - <td> - You need to be familiar with how to - <a href="/en-US/docs/Learn_web_development/Getting_started/Your_first_website" - >create a basic HTML document</a - >. - </td> - </tr> - <tr> - <th scope="row">Objective:</th> - <td> - Learn how to trigger JavaScript in your HTML file, and learn the most - important best practices for keeping JavaScript accessible. - </td> - </tr> - </tbody> -</table> - -## About JavaScript - -{{Glossary("JavaScript")}} is a programming language mostly used client-side to make webpages interactive. You _can_ create amazing webpages without JavaScript, but JavaScript opens up a whole new level of possibilities. - -> [!NOTE] -> In this article we're going over the HTML code you need to make JavaScript take effect. If you want to learn JavaScript itself, you can start with our [JavaScript basics](/en-US/docs/Learn_web_development/Getting_started/Your_first_website/Adding_interactivity) article. If you already know something about JavaScript or if you have a background with other programming languages, we suggest you jump directly into our [JavaScript Guide](/en-US/docs/Web/JavaScript/Guide). - -## How to trigger JavaScript from HTML - -Within a browser, JavaScript doesn't do anything by itself. You run JavaScript from inside your HTML webpages. To call JavaScript code from within HTML, you need the {{htmlelement("script")}} element. There are two ways to use `script`, depending on whether you're linking to an external script or embedding a script right in your webpage. - -### Linking an external script - -Usually, you'll be writing scripts in their own .js files. If you want to execute a .js script from your webpage, just use {{HTMLElement ('script')}} with an `src` attribute pointing to the script file, using its [URL](/en-US/docs/Learn_web_development/Howto/Web_mechanics/What_is_a_URL): - -```html -<script src="path/to/my/script.js"></script> -``` - -### Writing JavaScript within HTML - -You may also add JavaScript code between `<script>` tags rather than providing an `src` attribute. - -```html -<script> - window.addEventListener("load", () => { - console.log("This function is executed once the page is fully loaded"); - }); -</script> -``` - -That's convenient when you just need a small bit of JavaScript, but if you keep JavaScript in separate files you'll find it easier to - -- focus on your work -- write self-sufficient HTML -- write structured JavaScript applications - -## Use scripting accessibly - -Accessibility is a major issue in any software development. JavaScript can make your website more accessible if you use it wisely, or it can become a disaster if you use scripting without care. To make JavaScript work in your favor, it's worth knowing about certain best practices for adding JavaScript: - -- **Make all content available as (structured) text.** Rely on HTML for your content as much as possible. For example, if you've implemented a nice JavaScript progress bar, make sure to supplement it with matching text percentages inside the HTML. Likewise, your drop-down menus should be structured as [unordered lists](/en-US/docs/Learn_web_development/Core/Structuring_content/Lists#unordered_lists) of [links](/en-US/docs/Learn_web_development/Core/Structuring_content/Creating_links). -- **Make all functionality accessible from the keyboard.** - - - Let users Tab through all controls (e.g., links and form input) in a logical order. - - If you use pointer events (like mouse events or touch events), duplicate the functionality with keyboard events. - - Test your site using a keyboard only. - -- **Don't set nor even guess time limits.** It takes extra time to navigate with the keyboard or hear content read out. You can hardly ever predict just how long it will take for users or browsers to complete a process (especially asynchronous actions such as loading resources). -- **Keep animations subtle and brief with no flashing.** Flashing is annoying and can [cause seizures](https://www.w3.org/TR/UNDERSTANDING-WCAG20/seizure-does-not-violate.html). Additionally, if an animation lasts more than a couple seconds, give the user a way to cancel it. -- **Let users initiate interactions.** That means, don't update content, redirect, or refresh automatically. Don't use carousels or display popups without warning. -- **Have a plan B for users without JavaScript.** People may have JavaScript turned off to improve speed and security, and users often face network issues that prevent loading scripts. Moreover, third-party scripts (ads, tracking scripts, browser extensions) might break your scripts. - - - At a minimum, leave a short message with {{HTMLElement("noscript")}} like this: `<noscript>To use this site, please enable JavaScript.</noscript>` - - Ideally, replicate the JavaScript functionality with HTML and server-side scripting when possible. - - If you're only looking for simple visual effects, CSS can often get the job done even more intuitively. - - _Since almost everybody **does** have JavaScript enabled, `<noscript>` is no excuse for writing inaccessible scripts._ - -## Learn more - -- {{htmlelement("script")}} -- {{htmlelement("noscript")}} -- [James Edwards' introduction to using JavaScript accessibly](https://www.sitepoint.com/javascript-accessibility-101/) -- [Accessibility guidelines from W3C](https://www.w3.org/TR/WCAG20/) diff --git a/files/en-us/learn_web_development/howto/solve_javascript_problems/index.md b/files/en-us/learn_web_development/howto/solve_javascript_problems/index.md index 724fab932f2ea88..87e9feb2c2c4cfc 100644 --- a/files/en-us/learn_web_development/howto/solve_javascript_problems/index.md +++ b/files/en-us/learn_web_development/howto/solve_javascript_problems/index.md @@ -1,11 +1,11 @@ --- title: Solve common JavaScript problems +short-title: Common JavaScript problems slug: Learn_web_development/Howto/Solve_JavaScript_problems page-type: landing-page +sidebar: learn-how-to --- -{{LearnSidebar}} - The following links point to solutions to common problems you may encounter when writing JavaScript. ## Common beginner's mistakes @@ -51,7 +51,7 @@ myFunction(); #### Function scope -Remember that [functions have their own scope](/en-US/docs/Learn_web_development/Core/Scripting/Functions#function_scope_and_conflicts) — you can't access a variable value set inside a function from outside the function, unless you declared the variable globally (i.e. not inside any functions), or [return the value](/en-US/docs/Learn_web_development/Core/Scripting/Return_values) from the function. +Remember that [functions have their own scope](/en-US/docs/Learn_web_development/Core/Scripting/Functions#function_scope_and_conflicts) — you can't access a variable value set inside a function from outside the function, unless you declared the variable globally (i.e., not inside any functions), or [return the value](/en-US/docs/Learn_web_development/Core/Scripting/Return_values) from the function. #### Running code after a return statement @@ -111,14 +111,13 @@ const myObject = { - [How do you do basic math in JavaScript?](/en-US/docs/Learn_web_development/Core/Scripting/Math#arithmetic_operators) - [What is operator precedence, and how is it handled in JavaScript?](/en-US/docs/Learn_web_development/Core/Scripting/Math#operator_precedence) - [How do you increment and decrement values in JavaScript?](/en-US/docs/Learn_web_development/Core/Scripting/Math#increment_and_decrement_operators) -- [How do you compare values in JavaScript?](/en-US/docs/Learn_web_development/Core/Scripting/Math#comparison_operators) (e.g. to see which one is bigger, or to see if one value is equal to another). +- [How do you compare values in JavaScript?](/en-US/docs/Learn_web_development/Core/Scripting/Math#comparison_operators) (e.g., to see which one is bigger, or to see if one value is equal to another). ### Strings -- [How do you create a string in JavaScript?](/en-US/docs/Learn_web_development/Core/Scripting/Strings#creating_a_string) -- [Do you have to use single quotes or double quotes?](/en-US/docs/Learn_web_development/Core/Scripting/Strings#single_quotes_vs._double_quotes) -- [How do you escape characters in strings?](/en-US/docs/Learn_web_development/Core/Scripting/Strings#escaping_characters_in_a_string) -- [How do you join strings together?](/en-US/docs/Learn_web_development/Core/Scripting/Strings#concatenating_strings) +- [How do you create a string in JavaScript?](/en-US/docs/Learn_web_development/Core/Scripting/Strings#declaring_strings) +- [Do you have to use single quotes or double quotes?](/en-US/docs/Learn_web_development/Core/Scripting/Strings#single_quotes_double_quotes_and_backticks) +- [How do you join strings together?](/en-US/docs/Learn_web_development/Core/Scripting/Strings#concatenation_in_context) - [Can you join strings and numbers together?](/en-US/docs/Learn_web_development/Core/Scripting/Strings#numbers_vs._strings) - [How do you find the length of a string?](/en-US/docs/Learn_web_development/Core/Scripting/Useful_string_methods#finding_the_length_of_a_string) - [How do you find what character is at a certain position in a string?](/en-US/docs/Learn_web_development/Core/Scripting/Useful_string_methods#retrieving_a_specific_string_character) @@ -142,7 +141,7 @@ const myObject = { - [How do you log a value to the JavaScript console?](/en-US/docs/Learn_web_development/Core/Scripting/Debugging_JavaScript#the_console_api) - [How do you use breakpoints and other JavaScript debugging features?](/en-US/docs/Learn_web_development/Core/Scripting/Debugging_JavaScript#using_the_javascript_debugger) -For more information on JavaScript debugging, see [Handling common JavaScript problems](/en-US/docs/Learn_web_development/Core/Scripting/Debugging_JavaScript). Also, see [Other common errors](/en-US/docs/Learn_web_development/Core/Scripting/What_went_wrong#other_common_errors) for a description of common errors. +For more information on JavaScript debugging, see [JavaScript debugging and error handling](/en-US/docs/Learn_web_development/Core/Scripting/Debugging_JavaScript). Also, see [Other common errors](/en-US/docs/Learn_web_development/Core/Scripting/What_went_wrong#other_common_errors) for a description of common errors. ### Making decisions in code @@ -158,7 +157,7 @@ For more information on JavaScript debugging, see [Handling common JavaScript pr - [How do you run the same bit of code over and over again?](/en-US/docs/Learn_web_development/Core/Scripting/Loops) - [How do you exit a loop before the end if a certain condition is met?](/en-US/docs/Learn_web_development/Core/Scripting/Loops#exiting_loops_with_break) - [How do you skip to the next iteration of a loop if a certain condition is met?](/en-US/docs/Learn_web_development/Core/Scripting/Loops#skipping_iterations_with_continue) -- [How do you use while and do...while loops?](/en-US/docs/Learn_web_development/Core/Scripting/Loops#while_and_do_..._while) +- [How do you use while and do...while loops?](/en-US/docs/Learn_web_development/Core/Scripting/Loops#while_and_do...while) ## Intermediate use cases @@ -168,7 +167,7 @@ For more information on JavaScript debugging, see [Handling common JavaScript pr - [What is the difference between a function and a method?](/en-US/docs/Learn_web_development/Core/Scripting/Functions#functions_versus_methods) - [How do you create your own functions?](/en-US/docs/Learn_web_development/Core/Scripting/Build_your_own_function) - [How do you run (call, or invoke) a function?](/en-US/docs/Learn_web_development/Core/Scripting/Functions#invoking_functions) -- [What is an anonymous function?](/en-US/docs/Learn_web_development/Core/Scripting/Functions#anonymous_functions) +- [What is an anonymous function?](/en-US/docs/Learn_web_development/Core/Scripting/Functions#anonymous_functions_and_arrow_functions) - [How do you specify parameters (or arguments) when invoking a function?](/en-US/docs/Learn_web_development/Core/Scripting/Functions#function_parameters) - [What is function scope?](/en-US/docs/Learn_web_development/Core/Scripting/Functions#function_scope_and_conflicts) - [What are return values, and how do you use them?](/en-US/docs/Learn_web_development/Core/Scripting/Return_values) @@ -180,22 +179,19 @@ For more information on JavaScript debugging, see [Handling common JavaScript pr - [What is bracket notation?](/en-US/docs/Learn_web_development/Core/Scripting/Object_basics#bracket_notation) - [How do you get and set the methods and properties of an object?](/en-US/docs/Learn_web_development/Core/Scripting/Object_basics#setting_object_members) - [What is `this`, in the context of an object?](/en-US/docs/Learn_web_development/Core/Scripting/Object_basics#what_is_this) -- [What is object-oriented programming?](/en-US/docs/Learn_web_development/Extensions/Advanced_JavaScript_objects/Classes_in_JavaScript#object-oriented_programming_from_10000_meters) -- [What are constructors and instances, and how do you create them?](/en-US/docs/Learn_web_development/Extensions/Advanced_JavaScript_objects/Classes_in_JavaScript#constructors_and_object_instances) -- [What different ways are there to create objects in JavaScript?](/en-US/docs/Learn_web_development/Extensions/Advanced_JavaScript_objects/Classes_in_JavaScript#other_ways_to_create_object_instances) +- [What is object-oriented programming?](/en-US/docs/Learn_web_development/Extensions/Advanced_JavaScript_objects/Object-oriented_programming) +- [What are constructors and instances, and how do you create them?](/en-US/docs/Learn_web_development/Extensions/Advanced_JavaScript_objects/Object-oriented_programming#classes_and_instances) ### JSON - [How do you structure JSON data, and read it from JavaScript?](/en-US/docs/Learn_web_development/Core/Scripting/JSON#json_structure) -- [How can you load a JSON file into a page?](/en-US/docs/Learn_web_development/Core/Scripting/JSON#loading_our_json) - [How do you convert a JSON object to a text string, and back again?](/en-US/docs/Learn_web_development/Core/Scripting/JSON#converting_between_objects_and_text) ### Events - [What are event handlers and how do you use them?](/en-US/docs/Learn_web_development/Core/Scripting/Events#event_handler_properties) -- [What are inline event handlers?](/en-US/docs/Learn_web_development/Core/Scripting/Events#inline_event_handlers_%e2%80%94_don%27t_use_these) +- [What are inline event handlers?](/en-US/docs/Learn_web_development/Core/Scripting/Events#inline_event_handlers_—_dont_use_these) - [What does the `addEventListener()` function do, and how do you use it?](/en-US/docs/Learn_web_development/Core/Scripting/Events#using_addeventlistener) -- [Which mechanism should I use to add event code to my web pages?](/en-US/docs/Learn_web_development/Core/Scripting/Events#what_mechanism_should_i_use) - [What are event objects, and how do you use them?](/en-US/docs/Learn_web_development/Core/Scripting/Events#event_objects) - [How do you prevent default event behavior?](/en-US/docs/Learn_web_development/Core/Scripting/Events#preventing_default_behavior) - [How do events fire on nested elements? (event propagation, also related — event bubbling and capturing)](/en-US/docs/Learn_web_development/Core/Scripting/Event_bubbling) @@ -204,11 +200,10 @@ For more information on JavaScript debugging, see [Handling common JavaScript pr ### Object-oriented JavaScript - [What are object prototypes?](/en-US/docs/Learn_web_development/Extensions/Advanced_JavaScript_objects/Object_prototypes) -- [What is the constructor property, and how can you use it?](/en-US/docs/Learn_web_development/Extensions/Advanced_JavaScript_objects/Object_prototypes#the_constructor_property) -- [How do you add methods to the constructor?](/en-US/docs/Learn_web_development/Extensions/Advanced_JavaScript_objects/Object_prototypes#modifying_prototypes) +- [How do you add methods to the constructor?](/en-US/docs/Learn_web_development/Extensions/Advanced_JavaScript_objects/Object_prototypes#setting_a_prototype) - [How do you create a new constructor that inherits its members from a parent constructor?](/en-US/docs/Learn_web_development/Extensions/Advanced_JavaScript_objects/Classes_in_JavaScript) -- [When should you use inheritance in JavaScript?](/en-US/docs/Learn_web_development/Extensions/Advanced_JavaScript_objects/Classes_in_JavaScript#object_member_summary) +- [When should you use inheritance in JavaScript?](/en-US/docs/Learn_web_development/Extensions/Advanced_JavaScript_objects/Object-oriented_programming#inheritance) ### Web APIs -- [How do you manipulate the DOM (e.g. adding or removing elements) using JavaScript?](/en-US/docs/Learn_web_development/Core/Scripting/DOM_scripting#active_learning_basic_dom_manipulation) +- [How do you manipulate the DOM (e.g., adding or removing elements) using JavaScript?](/en-US/docs/Learn_web_development/Core/Scripting/DOM_scripting#active_learning_basic_dom_manipulation) diff --git a/files/en-us/learn_web_development/howto/tools_and_setup/available_text_editors/index.md b/files/en-us/learn_web_development/howto/tools_and_setup/available_text_editors/index.md index 66b1b2dd58c72ff..13711c526172133 100644 --- a/files/en-us/learn_web_development/howto/tools_and_setup/available_text_editors/index.md +++ b/files/en-us/learn_web_development/howto/tools_and_setup/available_text_editors/index.md @@ -2,10 +2,9 @@ title: What text editors are available? slug: Learn_web_development/Howto/Tools_and_setup/Available_text_editors page-type: learn-faq +sidebar: learn-how-to --- -{{QuicklinksWithSubPages("/en-US/docs/Learn_web_development/Howto")}} - In this article we highlight some things to think about when installing a text editor for web development. <table class="standard-table"> @@ -194,7 +193,7 @@ Here are some popular editors: </tr> <tr> <td> - <a href="https://www.notepad-plus-plus.org/" rel="external" + <a href="https://notepad-plus-plus.org/" rel="external" >Notepad++</a > </td> @@ -347,7 +346,7 @@ Here are some popular editors: ## Active Learning -In this active learning section, we would like you to try using and/or installing a text editor of your choice. Your computer may already be installed with one of the editors suggested above (e.g. Gedit if you use GNOME desktop, Kate if you use KDE etc.), if not then you should try installing one or more text editors of your choosing. +In this active learning section, we would like you to try using and/or installing a text editor of your choice. Your computer may already be installed with one of the editors suggested above (e.g., Gedit if you use GNOME desktop, Kate if you use KDE etc.), if not then you should try installing one or more text editors of your choosing. Try digging through the settings of your editor and read the manual or documentation to see what its capabilities are. In particular (if possible in your editor), try to: @@ -407,7 +406,6 @@ If you like _lots_ of features and your editor is slowing down because of all yo - [Aptana Studio](https://www.axway.com/en/aptana) - [Eclipse](https://www.eclipse.org/) -- [Komodo IDE](https://www.activestate.com/products/komodo-ide/) - [NetBeans IDE](https://netbeans.apache.org/) - [Visual Studio](https://visualstudio.microsoft.com/) - [WebStorm](https://www.jetbrains.com/webstorm/) diff --git a/files/en-us/learn_web_development/howto/tools_and_setup/checking_that_your_web_site_is_working_properly/index.md b/files/en-us/learn_web_development/howto/tools_and_setup/checking_that_your_web_site_is_working_properly/index.md index 568937a479234cd..e64b9b1d13e70d4 100644 --- a/files/en-us/learn_web_development/howto/tools_and_setup/checking_that_your_web_site_is_working_properly/index.md +++ b/files/en-us/learn_web_development/howto/tools_and_setup/checking_that_your_web_site_is_working_properly/index.md @@ -2,10 +2,9 @@ title: How do you make sure your website works properly? slug: Learn_web_development/Howto/Tools_and_setup/Checking_that_your_web_site_is_working_properly page-type: learn-faq +sidebar: learn-how-to --- -{{QuicklinksWithSubPages("/en-US/docs/Learn_web_development/Howto")}} - In this article, we go over various troubleshooting steps for a website and some basic actions to take in order to solve these issues. <table> @@ -69,7 +68,7 @@ Servers respond with a status message whenever they receive a request. Here are - **304: Not modified** - : The file has not changed since the last time you asked for it, so your browser can display the version from its cache, resulting in faster response times and more efficient use of bandwidth. - **403: Forbidden** - - : You aren't allowed to display the resource. Usually it has to do with a configuration mistake (e.g. your hosting provider forgot to give you access rights to a directory). + - : You aren't allowed to display the resource. Usually it has to do with a configuration mistake (e.g., your hosting provider forgot to give you access rights to a directory). - **404: Not found** - : Self-explanatory. We'll discuss how to solve this below. - **500: Internal server error** diff --git a/files/en-us/learn_web_development/howto/tools_and_setup/how_do_you_host_your_website_on_google_app_engine/index.md b/files/en-us/learn_web_development/howto/tools_and_setup/how_do_you_host_your_website_on_google_app_engine/index.md index b49847c4e064401..e444b80b12ade41 100644 --- a/files/en-us/learn_web_development/howto/tools_and_setup/how_do_you_host_your_website_on_google_app_engine/index.md +++ b/files/en-us/learn_web_development/howto/tools_and_setup/how_do_you_host_your_website_on_google_app_engine/index.md @@ -2,11 +2,10 @@ title: How do you host your website on Google App Engine? slug: Learn_web_development/Howto/Tools_and_setup/How_do_you_host_your_website_on_Google_App_Engine page-type: learn-faq +sidebar: learn-how-to --- -{{QuicklinksWithSubPages("/en-US/docs/Learn_web_development/Howto")}} - -[Google App Engine](https://cloud.google.com/appengine/) is a powerful platform that lets you build and run applications on Google's infrastructure — whether you need to build a multi-tiered web application from scratch or host a static website. Here's a step-by-step guide to hosting your website on Google App Engine. +[Google App Engine](https://cloud.google.com/appengine) is a powerful platform that lets you build and run applications on Google's infrastructure — whether you need to build a multi-tiered web application from scratch or host a static website. Here's a step-by-step guide to hosting your website on Google App Engine. ## Creating a Google Cloud Platform project @@ -49,7 +48,7 @@ Now that we've got our project made and sample app files collected together, let cd sample-app ``` -5. You are now ready to deploy your application, i.e. upload your app to App Engine: +5. You are now ready to deploy your application, i.e., upload your app to App Engine: ```bash gcloud app deploy diff --git a/files/en-us/learn_web_development/howto/tools_and_setup/how_much_does_it_cost/index.md b/files/en-us/learn_web_development/howto/tools_and_setup/how_much_does_it_cost/index.md index 0169bd3447dc49b..37585fa37ae2e7a 100644 --- a/files/en-us/learn_web_development/howto/tools_and_setup/how_much_does_it_cost/index.md +++ b/files/en-us/learn_web_development/howto/tools_and_setup/how_much_does_it_cost/index.md @@ -2,10 +2,9 @@ title: How much does it cost to do something on the Web? slug: Learn_web_development/Howto/Tools_and_setup/How_much_does_it_cost page-type: learn-faq +sidebar: learn-how-to --- -{{QuicklinksWithSubPages("/en-US/docs/Learn_web_development/Howto")}} - Getting involved on the Web isn't as cheap as it looks. In this article we discuss how much you may have to spend, and why. <table> @@ -78,7 +77,7 @@ Because FTP is inherently insecure, you should make sure to use SFTP — the sec ## Browsers -You either already have a browser or can get one for free. If necessary, download Firefox [here](https://www.mozilla.org/en-US/firefox/all/) or Google Chrome [here](https://www.google.com/chrome/). +You either already have a browser or can get one for free. If necessary, download [Firefox](https://www.mozilla.org/en-US/firefox/all/) or [Google Chrome](https://www.google.com/chrome/). ## Web access diff --git a/files/en-us/learn_web_development/howto/tools_and_setup/index.md b/files/en-us/learn_web_development/howto/tools_and_setup/index.md index 3ff93e41fc75fec..050de10885343fd 100644 --- a/files/en-us/learn_web_development/howto/tools_and_setup/index.md +++ b/files/en-us/learn_web_development/howto/tools_and_setup/index.md @@ -2,10 +2,9 @@ title: Tools and setup slug: Learn_web_development/Howto/Tools_and_setup page-type: landing-page +sidebar: learn-how-to --- -{{LearnSidebar}} - This section lists questions related to the tools/software you can use to build websites. - [What software do I need to build a website?](/en-US/docs/Learn_web_development/Howto/Tools_and_setup/What_software_do_I_need) diff --git a/files/en-us/learn_web_development/howto/tools_and_setup/set_up_a_local_testing_server/index.md b/files/en-us/learn_web_development/howto/tools_and_setup/set_up_a_local_testing_server/index.md index c0f201c9f30d7b8..ab298135e8f0b88 100644 --- a/files/en-us/learn_web_development/howto/tools_and_setup/set_up_a_local_testing_server/index.md +++ b/files/en-us/learn_web_development/howto/tools_and_setup/set_up_a_local_testing_server/index.md @@ -2,10 +2,9 @@ title: How do you set up a local testing server? slug: Learn_web_development/Howto/Tools_and_setup/set_up_a_local_testing_server page-type: learn-faq +sidebar: learn-how-to --- -{{QuicklinksWithSubPages("/en-US/docs/Learn_web_development/Howto")}} - This article explains how to set up a simple local testing server on your machine, and the basics of how to use it. <table> @@ -71,7 +70,7 @@ To use the module: npx -v ``` -2. If Node.js is not installed, you need to install it. Follow the [download instructions](https://nodejs.org/en/download/package-manager) in the Node.js docs, then run the above commands again to check if the installation is successful. +2. If Node.js is not installed, you need to install it. Follow the [download instructions](https://nodejs.org/en/download) in the Node.js docs, then run the above commands again to check if the installation is successful. 3. Let's assume the directory is `/path/to/project`. Run the following command to start the server: @@ -121,7 +120,7 @@ To do this: 5. By default, this will run the contents of the directory on a local web server, on port 8000. You can go to this server by going to the URL `localhost:8000` in your web browser. Here you'll see the contents of the directory listed — click the HTML file you want to run. > [!NOTE] -> If you already have something running on port 8000, you can choose another port by running the server command followed by an alternative port number, e.g. `python3 -m http.server 7800`. You can then access your content at `localhost:7800`. +> If you already have something running on port 8000, you can choose another port by running the server command followed by an alternative port number, e.g., `python3 -m http.server 7800`. You can then access your content at `localhost:7800`. ## Running server-side languages locally diff --git a/files/en-us/learn_web_development/howto/tools_and_setup/upload_files_to_a_web_server/index.md b/files/en-us/learn_web_development/howto/tools_and_setup/upload_files_to_a_web_server/index.md index 3bee6822ba5d04f..07702405a9b5116 100644 --- a/files/en-us/learn_web_development/howto/tools_and_setup/upload_files_to_a_web_server/index.md +++ b/files/en-us/learn_web_development/howto/tools_and_setup/upload_files_to_a_web_server/index.md @@ -2,10 +2,9 @@ title: How do you upload your files to a web server? slug: Learn_web_development/Howto/Tools_and_setup/Upload_files_to_a_web_server page-type: learn-faq +sidebar: learn-how-to --- -{{QuicklinksWithSubPages("/en-US/docs/Learn_web_development/Howto")}} - This article shows you how to publish your site online using file transfer tools. <table> @@ -107,7 +106,7 @@ Once connected, your screen should look something like this (we've connected to Let's examine what you're seeing: -- On the center left pane, you see your local files. Navigate into the directory where you store your website (e.g. `mdn`). +- On the center left pane, you see your local files. Navigate into the directory where you store your website (e.g., `mdn`). - On the center right pane, you see remote files. We are logged into our distant FTP root (in this case, `users/demozilla`) - You can ignore the bottom and top panes for now. Respectively, these are a log of messages showing the connection status between your computer and the SFTP server, and a live log of every interaction between your SFTP client and the server. @@ -119,7 +118,7 @@ Once you've found the correct remote directory to put your files in, to upload y ### Are they really online? -So far, so good, but are the files really online? You can double-check by going back to your website (e.g. `http://demozilla.examplehostingprovider.net/`) in your browser: +So far, so good, but are the files really online? You can double-check by going back to your website (e.g., `http://demozilla.examplehostingprovider.net/`) in your browser: ![Here we go: our website is live!](here-we-go.png) diff --git a/files/en-us/learn_web_development/howto/tools_and_setup/using_github_pages/index.md b/files/en-us/learn_web_development/howto/tools_and_setup/using_github_pages/index.md index 8a8747abf32166c..32073ff48563461 100644 --- a/files/en-us/learn_web_development/howto/tools_and_setup/using_github_pages/index.md +++ b/files/en-us/learn_web_development/howto/tools_and_setup/using_github_pages/index.md @@ -2,10 +2,9 @@ title: How do I use GitHub Pages? slug: Learn_web_development/Howto/Tools_and_setup/Using_GitHub_pages page-type: learn-faq +sidebar: learn-how-to --- -{{QuicklinksWithSubPages("/en-US/docs/Learn_web_development/Howto")}} - [GitHub](https://github.com/) is a "social coding" site. It allows you to upload code repositories for storage in the [Git](https://git-scm.com/) **version control system.** You can then collaborate on code projects, and the system is open-source by default, meaning that anyone in the world can find your GitHub code, use it, learn from it, and improve on it. You can do that with other people's code too! This article provides a basic guide to publishing content using GitHub's gh-pages feature. ## Publishing content @@ -20,11 +19,11 @@ GitHub is a very important and useful community to get involved in, and Git/GitH ### Preparing your code for upload -You can store any code you like in a GitHub repository, but to use the GitHub Pages feature to full effect, your code should be structured as a typical website, e.g. with the primary entry point being an HTML file called `index.html`. +You can store any code you like in a GitHub repository, but to use the GitHub Pages feature to full effect, your code should be structured as a typical website, e.g., with the primary entry point being an HTML file called `index.html`. -The other thing you need to do before moving on is to initialise your code directory as a Git repository. To do this: +The other thing you need to do before moving on is to initialize your code directory as a Git repository. To do this: -1. Point the command line to your `test-site` directory (or whatever you called the directory containing your website). For this, use the `cd` command (i.e. "**c**hange **d**irectory"). Here's what you'd type if you've put your website in a directory called `test-site` on your desktop: +1. Point the command line to your `test-site` directory (or whatever you called the directory containing your website). For this, use the `cd` command (i.e., "**c**hange **d**irectory"). Here's what you'd type if you've put your website in a directory called `test-site` on your desktop: ```bash cd Desktop/test-site diff --git a/files/en-us/learn_web_development/howto/tools_and_setup/what_are_browser_developer_tools/index.md b/files/en-us/learn_web_development/howto/tools_and_setup/what_are_browser_developer_tools/index.md index cb2bdb690a0ab12..6d45e04a1865558 100644 --- a/files/en-us/learn_web_development/howto/tools_and_setup/what_are_browser_developer_tools/index.md +++ b/files/en-us/learn_web_development/howto/tools_and_setup/what_are_browser_developer_tools/index.md @@ -2,10 +2,9 @@ title: What are browser developer tools? slug: Learn_web_development/Howto/Tools_and_setup/What_are_browser_developer_tools page-type: learn-faq +sidebar: learn-how-to --- -{{QuicklinksWithSubPages("/en-US/docs/Learn_web_development/Howto")}} - Every modern web browser includes a powerful suite of developer tools. These tools do a range of things, from inspecting currently-loaded HTML, CSS and JavaScript to showing which assets the page has requested and how long they took to load. This article explains how to use the basic functions of your browser's devtools. > [!NOTE] diff --git a/files/en-us/learn_web_development/howto/tools_and_setup/what_software_do_i_need/index.md b/files/en-us/learn_web_development/howto/tools_and_setup/what_software_do_i_need/index.md index 0371c8da4bd23d0..74494b42251f635 100644 --- a/files/en-us/learn_web_development/howto/tools_and_setup/what_software_do_i_need/index.md +++ b/files/en-us/learn_web_development/howto/tools_and_setup/what_software_do_i_need/index.md @@ -2,10 +2,9 @@ title: What software do I need to build a website? slug: Learn_web_development/Howto/Tools_and_setup/What_software_do_I_need page-type: learn-faq +sidebar: learn-how-to --- -{{QuicklinksWithSubPages("/en-US/docs/Learn_web_development/Howto")}} - In this article, we lay out which software components you need when you're editing, uploading, or viewing a website. <table class="standard-table"> @@ -189,7 +188,7 @@ Here is a screenshot of an online text editor: When your website is ready for public viewing, you'll have to upload your webpages to your web server. You can buy space on a server from various providers (see [How much does it cost to do something on the web?](/en-US/docs/Learn_web_development/Howto/Tools_and_setup/How_much_does_it_cost)). Once you settle on which provider to use, the provider will email you the access information, usually in the form of an SFTP URL, username, password, and other information needed to connect to their server. Bear in mind that (S)FTP is now somewhat old-fashioned, and other uploading systems are starting to become popular, such as [RSync](https://en.wikipedia.org/wiki/Rsync) and [Git/GitHub](https://docs.github.com/en/pages/configuring-a-custom-domain-for-your-github-pages-site). > [!NOTE] -> FTP is inherently insecure. You should make sure your hosting provider allows use of a secure connection, e.g. SFTP or RSync over SSH. +> FTP is inherently insecure. You should make sure your hosting provider allows use of a secure connection, e.g., SFTP or RSync over SSH. Uploading files to a web server is a very important step while creating a website, so we cover it in detail in [a separate article](/en-US/docs/Learn_web_development/Howto/Tools_and_setup/Upload_files_to_a_web_server). For now, here's a short list of free basic (S)FTP clients: @@ -223,7 +222,7 @@ Uploading files to a web server is a very important step while creating a websit <ul> <li> <a - href="https://wiki.gnome.org/action/show/Apps/Files?action=show&#x26;redirect=Apps%2FNautilus" + href="https://apps.gnome.org/en/Nautilus/" rel="external" >Nautilus/Files</a > @@ -263,7 +262,7 @@ There are [many web browsers available](https://en.wikipedia.org/wiki/List_of_we - [Google Chrome](https://www.google.com/chrome/) - [Apple Safari](https://www.apple.com/safari/) -If you're targeting a specific group (e.g., technical platform or locale), you may have to test the site with additional browsers, like [UC Browser](https://www.ucweb.com/) or [Opera Mini](https://www.opera.com/browsers/opera-mini). +If you're targeting a specific group (e.g., technical platform or locale), you may have to test the site with additional browsers, like [UC Browser](https://www.ucweb.com/) or [Opera Mini](https://www.opera.com/mini). Testing gets complicated because some browsers only run on certain operating systems. Notably, Apple Safari runs on iOS, iPadOS, and macOS. It's best to take advantage of services like [Browsershots](https://browsershots.org/) or [Browserstack](https://www.browserstack.com/). Browsershots creates screenshots of your website as it will look in various browsers. Browserstack gives you full remote access to virtual machines, so you can test your site in the most common environments and on different operating systems. Alternatively, you can set up your own virtual machines, but that takes some expertise. diff --git a/files/en-us/learn_web_development/howto/web_mechanics/how_does_the_internet_work/index.md b/files/en-us/learn_web_development/howto/web_mechanics/how_does_the_internet_work/index.md index 74c8fc6f5e92483..e6a770d5f73cfc6 100644 --- a/files/en-us/learn_web_development/howto/web_mechanics/how_does_the_internet_work/index.md +++ b/files/en-us/learn_web_development/howto/web_mechanics/how_does_the_internet_work/index.md @@ -2,10 +2,9 @@ title: How does the Internet work? slug: Learn_web_development/Howto/Web_mechanics/How_does_the_Internet_work page-type: learn-faq +sidebar: learn-how-to --- -{{QuicklinksWithSubPages("/en-US/docs/Learn_web_development/Howto")}} - This article discusses what the Internet is and how it works. <table> @@ -56,26 +55,30 @@ Such a network is not limited to two computers. You can connect as many computer ![Ten computers all together](internet-schema-2.png) -To solve this problem, each computer on a network is connected to a special tiny computer called a _router_. This _router_ has only one job: like a signaler at a railway station, it makes sure that a message sent from a given computer arrives at the right destination computer. To send a message to computer B, computer A must send the message to the router, which in turn forwards the message to computer B and makes sure the message is not delivered to computer C. +To solve this problem, each computer on a network is connected to a special tiny computer called a _network switch_ (or _switch_ for short). This switch has only one job: like a signaler at a railway station, it makes sure that messages sent from a given computer arrive only at their target destination computer. To send a message to computer B, computer A sends the message to the switch, which in turn forwards the message to computer B — computer B doesn't get messages intended for other computers, and none of the messages for computer B reach other computers on the local area network. -Once we add a router to the system, our network of 10 computers only requires 10 cables: a single plug for each computer and a router with 10 plugs. +Once we add a switch to the system, our network of 10 computers only requires 10 cables: a single plug for each computer and a switch with 10 plugs. -![Ten computers with a router](internet-schema-3.png) +![Ten computers with a switch](internet-schema-3.png) ### A network of networks -So far so good. But what about connecting hundreds, thousands, billions of computers? Of course a single _router_ can't scale that far, but, if you read carefully, we said that a _router_ is a computer like any other, so what keeps us from connecting two _routers_ together? Nothing, so let's do that. +So far so good. But what about connecting hundreds, thousands, billions of computers? Of course a single switch can't scale that far, but, if you read carefully, we said that a switch is a computer like any other, so what keeps us from connecting two switches together? Nothing, so let's do that. + +![Two switches linked together](internet-schema-4.png) -![Two routers linked together](internet-schema-4.png) +You may imagine that we can connect switches together infinitely, to form a network like this: -By connecting computers to routers, then routers to routers, we are able to scale infinitely. +![Switches linked to switches](internet-schema-5.png) -![Routers linked to routers](internet-schema-5.png) +In reality, this leads to many engineering problems. The more switches a packet has to go through, the longer it takes to reach its destination. And you can't have just a tree of switches, because then a single switch failure may disconnect a large portion of devices. To solve this problem, we keep each local network as small as possible, and we connect these local networks using a separate device called a _router_. A router is a computer that knows how to forward messages between networks. The router is like a post office: when a packet arrives, it reads the recipient address and forwards the packet to the right recipient directly, without going through layers of relays. -Such a network comes very close to what we call the Internet, but we're missing something. We built that network for our own purposes. There are other networks out there: your friends, your neighbors, anyone can have their own network of computers. But it's not really possible to set cables up between your house and the rest of the world, so how can you handle this? Well, there are already cables linked to your house, for example, electric power and telephone. The telephone infrastructure already connects your house with anyone in the world so it is the perfect wire we need. To connect our network to the telephone infrastructure, we need a special piece of equipment called a _modem_. This _modem_ turns the information from our network into information manageable by the telephone infrastructure and vice versa. +Such a network comes very close to what we call the Internet. We just need the physical medium (cables) to connect all these routers. Luckily, such an infrastructure already existed prior to the Internet, and that's the telephone network. To connect our network to the telephone infrastructure, we need a special piece of equipment called a _modem_. This _modem_ turns the information from our network into information manageable by the telephone infrastructure and vice versa. ![A router linked to a modem](internet-schema-6.png) +Note that the commercial router in your home is likely a combination of a switch, a router, and a modem, all in one device. + So we are connected to the telephone infrastructure. The next step is to send the messages from our network to the network we want to reach. To do that, we will connect our network to an Internet Service Provider (ISP). An ISP is a company that manages some special _routers_ that are all linked together and can also access other ISPs' routers. So the message from our network is carried through the network of ISP networks to the destination network. The Internet consists of this whole infrastructure of networks. ![Full Internet stack](internet-schema-7.png) diff --git a/files/en-us/learn_web_development/howto/web_mechanics/index.md b/files/en-us/learn_web_development/howto/web_mechanics/index.md index 40f304945af3598..b65a055b662e1a3 100644 --- a/files/en-us/learn_web_development/howto/web_mechanics/index.md +++ b/files/en-us/learn_web_development/howto/web_mechanics/index.md @@ -2,10 +2,9 @@ title: Web mechanics slug: Learn_web_development/Howto/Web_mechanics page-type: landing-page +sidebar: learn-how-to --- -{{LearnSidebar}} - This section covers questions relating to general knowledge of the web ecosystem and how it works. - [How does the Internet work?](/en-US/docs/Learn_web_development/Howto/Web_mechanics/How_does_the_Internet_work) diff --git a/files/en-us/learn_web_development/howto/web_mechanics/what_are_hyperlinks/index.md b/files/en-us/learn_web_development/howto/web_mechanics/what_are_hyperlinks/index.md index 5e308311c872301..efcd3aba09e2586 100644 --- a/files/en-us/learn_web_development/howto/web_mechanics/what_are_hyperlinks/index.md +++ b/files/en-us/learn_web_development/howto/web_mechanics/what_are_hyperlinks/index.md @@ -2,10 +2,9 @@ title: What are hyperlinks? slug: Learn_web_development/Howto/Web_mechanics/What_are_hyperlinks page-type: learn-faq +sidebar: learn-how-to --- -{{QuicklinksWithSubPages("/en-US/docs/Learn_web_development/Howto")}} - In this article, we'll go over what hyperlinks are and why they matter. <table> diff --git a/files/en-us/learn_web_development/howto/web_mechanics/what_is_a_domain_name/index.md b/files/en-us/learn_web_development/howto/web_mechanics/what_is_a_domain_name/index.md index a5c95a0f4fdfc4a..cfe5a10b9d8a172 100644 --- a/files/en-us/learn_web_development/howto/web_mechanics/what_is_a_domain_name/index.md +++ b/files/en-us/learn_web_development/howto/web_mechanics/what_is_a_domain_name/index.md @@ -2,10 +2,9 @@ title: What is a Domain Name? slug: Learn_web_development/Howto/Web_mechanics/What_is_a_domain_name page-type: learn-faq +sidebar: learn-how-to --- -{{QuicklinksWithSubPages("/en-US/docs/Learn_web_development/Howto")}} - <table> <tbody> <tr> @@ -34,7 +33,7 @@ page-type: learn-faq Domain names are a key part of the Internet infrastructure. They provide a human-readable address for any web server available on the Internet. -Any Internet-connected computer can be reached through a public {{Glossary("IP Address")}}, either an IPv4 address (e.g. `192.0.2.172`) or an IPv6 address (e.g., `2001:db8:8b73:0000:0000:8a2e:0370:1337`). +Any Internet-connected computer can be reached through a public {{Glossary("IP Address")}}, either an IPv4 address (e.g., `192.0.2.172`) or an IPv6 address (e.g., `2001:db8:8b73:0000:0000:8a2e:0370:1337`). Computers can handle such addresses easily, but people have a hard time finding out who is running the server or what service the website offers. IP addresses are hard to remember and might change over time. @@ -60,7 +59,7 @@ Each of those parts provides specific information about the whole domain name. TLDs can contain special as well as latin characters. A TLD's maximum length is 63 characters, although most are around 2–3. - The full list of TLDs is [maintained by ICANN](https://www.icann.org/resources/pages/tlds-2012-02-25-en). + The full list of TLDs is [maintained by ICANN](https://www.icann.org/en/contracted-parties/registry-operators/resources/list-of-top-level-domains). - Label (or component) @@ -68,7 +67,7 @@ Each of those parts provides specific information about the whole domain name. The label located right before the TLD is also called a _Secondary Level Domain_ (SLD). - A domain name can have many labels (or components). It is not mandatory nor necessary to have 3 labels to form a domain name. For instance, [informatics.ed.ac.uk](https://informatics.ed.ac.uk/) is a valid domain name. For any domain you control (e.g. [mozilla.org](https://www.mozilla.org/en-US/)), you can create "subdomains" with different content located at each, like [developer.mozilla.org](/), [support.mozilla.org](https://support.mozilla.org/), or [bugzilla.mozilla.org](https://bugzilla.mozilla.org/). + A domain name can have many labels (or components). It is not mandatory nor necessary to have 3 labels to form a domain name. For instance, [informatics.ed.ac.uk](https://informatics.ed.ac.uk/) is a valid domain name. For any domain you control (e.g., [mozilla.org](https://www.mozilla.org/en-US/)), you can create "subdomains" with different content located at each, like [developer.mozilla.org](/), [support.mozilla.org](https://support.mozilla.org/), or [bugzilla.mozilla.org](https://bugzilla.mozilla.org/). ### Buying a domain name @@ -172,4 +171,4 @@ Okay, we talked a lot about processes and architecture. Time to move on. - If you want to get hands-on, it's a good time to start digging into design and explore [the anatomy of a web page](/en-US/docs/Learn_web_development/Howto/Design_and_accessibility/Common_web_layouts). - It's also worth noting that some aspects of building a website cost money. Please refer to [how much it costs to build a website](/en-US/docs/Learn_web_development/Howto/Tools_and_setup/How_much_does_it_cost). - Or read more about [Domain Names](https://en.wikipedia.org/wiki/Domain_name) on Wikipedia. -- You can also find [here](https://howdns.works/) a fun and colorful explanation of how DNS works. +- The [How DNS works](https://howdns.works/) tutorial has a fun and colorful explanation. diff --git a/files/en-us/learn_web_development/howto/web_mechanics/what_is_a_url/index.md b/files/en-us/learn_web_development/howto/web_mechanics/what_is_a_url/index.md index d12829991bf68cc..89ca51a0d952e6a 100644 --- a/files/en-us/learn_web_development/howto/web_mechanics/what_is_a_url/index.md +++ b/files/en-us/learn_web_development/howto/web_mechanics/what_is_a_url/index.md @@ -2,10 +2,9 @@ title: What is a URL? slug: Learn_web_development/Howto/Web_mechanics/What_is_a_URL page-type: learn-faq +sidebar: learn-how-to --- -{{QuicklinksWithSubPages("/en-US/docs/Learn_web_development/Howto")}} - This article discusses Uniform Resource Locators (URLs), explaining what they are and how they're structured. <table> @@ -71,7 +70,7 @@ The first part of the URL is the _scheme_, which indicates the protocol that the ![Authority](mdn-url-authority.png) -Next follows the _authority_, which is separated from the scheme by the character pattern `://`. If present the authority includes both the _domain_ (e.g. `www.example.com`) and the _port_ (`80`), separated by a colon: +Next follows the _authority_, which is separated from the scheme by the character pattern `://`. If present the authority includes both the _domain_ (e.g., `www.example.com`) and the _port_ (`80`), separated by a colon: - The domain indicates which Web server is being requested. Usually this is a [domain name](/en-US/docs/Learn_web_development/Howto/Web_mechanics/What_is_a_domain_name), but an {{Glossary("IP address")}} may also be used (but this is rare as it is much less convenient). - The port indicates the technical "gate" used to access the resources on the web server. It is usually omitted if the web server uses the standard ports of the HTTP protocol (80 for HTTP and 443 for HTTPS) to grant access to its resources. Otherwise it is mandatory. @@ -137,6 +136,22 @@ All of the following URLs are relative URLs: - Going back in the directory tree: `../CSS/display` — the protocol and domain name are missing, and the path begins with `..`. This is inherited from the UNIX file system world — to tell the browser we want to go up by one level. Here we want to reach this URL: `https://developer.mozilla.org/en-US/docs/Learn_web_development/../Web/CSS/display`, which can be simplified to: `https://developer.mozilla.org/en-US/docs/Web/CSS/display`. - Anchor-only: `#semantic_urls` - all parts are missing except the anchor. The browser will use the current document's URL and replace or add the anchor part to it. This is useful when you want to link to a specific part of the current document. +## URL usernames and passwords + +Less common than the URL parts discussed above, you may see a username and password included in URLs. + +For example: + +```plain +https://username:password@www.example.com:80/ +``` + +When included, the username and password are put between the `://` characters and the authority, with a colon between the two and an ampersand (`@`) at the end. + +A username and password can be included in the URL when accessing websites that use the [HTTP authentication](/en-US/docs/Web/HTTP/Guides/Authentication) security mechanism, to immediately sign in to a website and bypass the username/password dialog box that would otherwise appear to enter your credentials into. + +While you might still see this mechanism used in the wild, it is deprecated because of security concerns, and modern websites tend to use other mechanisms for authentication. See [Access using credentials in the URL](/en-US/docs/Web/HTTP/Guides/Authentication#access_using_credentials_in_the_url) for more details. + ## Semantic URLs Despite their very technical flavor, URLs represent a human-readable entry point for a website. They can be memorized, and anyone can enter them into a browser's address bar. People are at the core of the Web, and so it is considered best practice to build what is called [_semantic URLs_](https://en.wikipedia.org/wiki/Semantic_URL). Semantic URLs use words with inherent meaning that can be understood by anyone, regardless of their technical know-how. diff --git a/files/en-us/learn_web_development/howto/web_mechanics/what_is_a_web_server/index.md b/files/en-us/learn_web_development/howto/web_mechanics/what_is_a_web_server/index.md index 7238cc055e325b7..1d0e5114799f98e 100644 --- a/files/en-us/learn_web_development/howto/web_mechanics/what_is_a_web_server/index.md +++ b/files/en-us/learn_web_development/howto/web_mechanics/what_is_a_web_server/index.md @@ -2,10 +2,9 @@ title: What is a web server? slug: Learn_web_development/Howto/Web_mechanics/What_is_a_web_server page-type: learn-faq +sidebar: learn-how-to --- -{{QuicklinksWithSubPages("Learn_web_development/Howto")}} - In this article, we explain what web servers are, how web servers work, and why they are important. <table> @@ -41,7 +40,7 @@ The term _web server_ can refer to hardware or software, or both of them working 1. On the hardware side, a web server is a computer that stores web server software and a website's component files (for example, HTML documents, images, CSS stylesheets, and JavaScript files). A web server connects to the Internet and supports physical data interchange with other devices connected to the web. 2. On the software side, a web server includes several parts that control how web users access hosted files. At a minimum, this is an _HTTP server_. An HTTP server is software that understands {{Glossary("URL","URLs")}} (web addresses) and {{Glossary("HTTP")}} (the protocol your browser uses to view webpages). An HTTP server can be accessed through the domain names of the websites it stores, and it delivers the content of these hosted websites to the end user's device. -At the most basic level, whenever a browser needs a file that is hosted on a web server, the browser requests the file via HTTP. When the request reaches the correct (hardware) web server, the (software) _HTTP server_ accepts the request, finds the requested document, and sends it back to the browser, also through HTTP. (If the server doesn't find the requested document, it returns a [404](/en-US/docs/Web/HTTP/Status/404) response instead.) +At the most basic level, whenever a browser needs a file that is hosted on a web server, the browser requests the file via HTTP. When the request reaches the correct (hardware) web server, the (software) _HTTP server_ accepts the request, finds the requested document, and sends it back to the browser, also through HTTP. (If the server doesn't find the requested document, it returns a [404](/en-US/docs/Web/HTTP/Reference/Status/404) response instead.) ![Basic representation of a client/server connection through HTTP](web-server.svg) diff --git a/files/en-us/learn_web_development/index.md b/files/en-us/learn_web_development/index.md index c9beb873fdf4be6..dee856ac471c07d 100644 --- a/files/en-us/learn_web_development/index.md +++ b/files/en-us/learn_web_development/index.md @@ -2,17 +2,16 @@ title: Learn web development slug: Learn_web_development page-type: landing-page +sidebar: learnsidebar --- -{{LearnSidebar}} - -## The essential skillset for new front-end developers +## The essential skill set for new front-end developers Welcome to MDN **Learning Web Development** (also known as **Learn**). This resource provides a structured set of tutorials teaching the essential skills and practices for being a successful front-end developer, along with challenges and further recommended resources. ## About Learn web development -- Defines the essential skills and knowledge every front-end developer needs for career success and industry relevance. +- Teaches the essential skills and knowledge every front-end developer needs for career success and industry relevance, as defined in the [MDN Curriculum](/en-US/curriculum/). - Created by the MDN community and refined with insights from students, educators, and developers from the broader web community. @@ -24,13 +23,13 @@ Welcome to MDN **Learning Web Development** (also known as **Learn**). This reso ## Don't know where to get started? - Never coded before? - - : Our [Getting started modules](/en-US/docs/Learn_web_development/Getting_started) provide setup tutorials and essential concepts and background information for complete beginners. You should start here if you are a complete beginner (i.e. you've not installed a code editor or written any code yet). + - : Our [Getting started modules](/en-US/docs/Learn_web_development/Getting_started) provide setup tutorials and essential concepts and background information for complete beginners. You should start here if you are a complete beginner (i.e., you've not installed a code editor or written any code yet). - Want to master the essentials? - : Our [Core modules](/en-US/docs/Learn_web_development/Core) provide a structured set of tutorials teaching the essential skills and practices for being a successful front-end developer. - Beyond the basics? - : Our [Extension modules](/en-US/docs/Learn_web_development/Extensions) cover useful additional skills to learn as you start to expand your knowledge and develop specialisms. Go onto these after you finish our Core. - Working at a school? - - : Use our modules to guide your teaching, check out our [Educators page](/en-US/docs/Learn_web_development/Educators) for more ideas, or enroll your students in Scrimba's [Frontend Developer Career Path](https://v2.scrimba.com/the-frontend-developer-career-path-c0j?via=mdn)<sup>_MDN learning partner_</sup>. + - : Use our modules to guide your teaching, check out our [Educators page](/en-US/docs/Learn_web_development/Educators) for more ideas, or enroll your students in Scrimba's [Frontend Developer Career Path](https://scrimba.com/the-frontend-developer-career-path-c0j?via=mdn)<sup>[_MDN learning partner_](/en-US/docs/MDN/Writing_guidelines/Learning_content#partner_links_and_embeds)</sup>. ## Getting our code examples @@ -47,11 +46,11 @@ If you're interested in helping develop/improve the content, take a look at [how ## See also +- [The Frontend Developer Career Path](https://scrimba.com/the-frontend-developer-career-path-c0j?via=mdn) <sup>[_MDN learning partner_](/en-US/docs/MDN/Writing_guidelines/Learning_content#partner_links_and_embeds)</sup> + - : [Scrimba's](https://scrimba.com?via=mdn) _Frontend Developer Career Path_ teaches all you need to know to be a competent front-end web developer, with fun interactive lessons and challenges, knowledgeable teachers, and a supportive community. Go from zero to landing your first front-end job! Many of the course components are available as standalone free versions. - [Codecademy](https://www.codecademy.com/) - : A great interactive site for learning programming languages from scratch. - [freeCodeCamp.org](https://www.freecodecamp.org/) - : Interactive site with tutorials and projects to learn web development. - [Learn JavaScript](https://learnjavascript.online/) - : An excellent resource for aspiring web developers — Learn JavaScript in an interactive environment, with short lessons and interactive tests, guided by automated assessment. The first 40 lessons are free, and the complete course is available for a small one-time payment. -- [The Frontend Developer Career Path](https://v2.scrimba.com/the-frontend-developer-career-path-c0j?via=mdn) <sup>_MDN learning partner_</sup> - - : [Scrimba's](https://scrimba.com?via=mdn) _Frontend Developer Career Path_ teaches all you need to know to be a competent front-end web developer, with fun interactive lessons and challenges, knowledgeable teachers, and a supportive community. Go from zero to landing your first front-end job! Many of the course components are available as standalone free versions. diff --git a/files/en-us/mdn/community/community_participation_guidelines/index.md b/files/en-us/mdn/community/community_participation_guidelines/index.md new file mode 100644 index 000000000000000..a86d85d99f07657 --- /dev/null +++ b/files/en-us/mdn/community/community_participation_guidelines/index.md @@ -0,0 +1,116 @@ +--- +title: Code of conduct enforcement guidelines +short-title: Community Participation Guidelines +slug: MDN/Community/Community_Participation_Guidelines +page-type: mdn-community-guide +sidebar: mdnsidebar +--- + +Participating in MDN Web Docs projects means adhering to the [Mozilla Community Participation Guidelines (CPG)](https://www.mozilla.org/en-US/about/governance/policies/participation/). +These guidelines exist to foster a welcoming, inclusive, and safe environment, and to ensure that every community member feels valued, heard, and protected. + +This document describes how to report violations and what happens depending on the severity of a violation. + +## Guiding principles + +- **Transparency:** Address every report clearly and consistently. +- **Confidentiality:** Protect reporter privacy unless explicit consent is given to share information. +- **Proportionality:** Responses to violations are proportionate to the harm caused. +- **Restorative Justice:** Repair harm and foster learning. + +## Code of Conduct Violations and Enforcement Ladder + +The MDN Community Management team ([`@mdn/community`](https://github.com/orgs/mdn/teams/community) on GitHub) investigates the severity of behavior based on a report, then determines and carries out any actions, if appropriate. +Violations follow a step-by-step escalation process, and the reportee is informed of consequences at leach level. +In serious cases, enforcement may skip levels up to and including an immediate, permanent ban. + +Below is a summary of severity levels and enforcement actions. + +### Level 0: No Action + +- **Severity:** There is no clear indication a violation of the CPG. +- **Actions:** No formal action taken. Feedback is provided to the reporter, reportee, or both, to promote good behavior and positive interactions. + +### Level 1: Simple Warning Issued + +- **Severity:** Minor violations of the CPG. +- **Actions:** A private, written warning from project leadership, with clarity of the violation and consequences of continued behavior. + +### Level 2: Warning + +- **Severity:** Moderate violation of the CPG, or repeated minor violations. +- **Actions:** + - A private, written warning with clarity of the violation and consequences of continued behavior. + - Guidance on rectifying the situation, if possible. + - Communication of next-level consequences if behaviors are repeated. + +### Level 3: Warning + Mandatory Cooling Off Period (Tool Access Revoked - GH & Discord) + +- **Severity:** Continued violations or escalation in severity. +- **Actions:** + - A private warning with clarity of the violation and consequences of continued behavior. + - No interaction on community messaging platforms, such as public forums, commenting on bugs. + - No interacting with people involved in the report or others suspected to be involved. + - Avoid interactions in Mozilla channels, physical spaces and offices, and online channels like social media (e.g., following/liking/re-posting). + - The reportee has the opportunity to participate in the project again after onboarding that clarifies expected behavior. + +### Level 4: Ban across MDN and Mozilla Spaces, All Areas Permanent Ban + +- **Severity:** Serious [Mozilla Community Participation Guidelines (CPG)](https://www.mozilla.org/en-US/about/governance/policies/participation/) breaches. +- **Actions:** + - Private communication of a ban from project leadership, with clarity of the violation and warning of consequences. Should the behavior continue, it would lead to a ban from all Mozilla community spaces. + - Required to avoid interaction on community messaging platforms and external channels. + - Deactivation of any and all Mozilla accounts. + - Permanently banned from entering Mozilla digital and event spaces. + - Permanently suspended from any and all community leadership roles. + - Revocation of any and all permissions to use the Mozilla trademark. + +## Reporting Process + +### How to Report a violation + +Reports can be sent to mdn-cpg-report@mozilla.com. +To report a violation or abuse on GitHub, see [GitHub's content reporting guide](https://docs.github.com/en/communities/maintaining-your-safety-on-github/reporting-abuse-or-spam). +The **"Report to repository admins"** option must be checked for the MDN team to see a content report. + +Include any relevant details, including date, time, description of the violation. +Include identifying information of the offender and screenshots, if possible. + +### Investigation + +MDN Community Management investigates all reports confidentially. +When necessary, further information may be requested from the involved parties. + +### Decision Making + +MDN Community Management assess the severity of the violation, apply the enforcement actions as outlined, and communicate the outcome to relevant parties. + +### Appeals + +If a reported individual believes the decision was unjust, they may appeal through the [appeals process detailed on the community page]. +Appeals are reviewed by a separate, impartial panel. + +### Documentation and Record Keeping + +All incidents will be documented to ensure consistency and fairness. +Records of violations and actions taken are kept private, and accessible only by MDN Community Management. + +## Frequently Asked Questions (FAQs) + +Common questions are answered below. +If anything else about CPG reports and processes is unclear or unanswered, get in touch via [our Communication channels](/en-US/docs/MDN/Community/Communication_channels). + +### What happens if a violation involves an edge-case scenario? + +Behavior that's inappropriate but is not explicitly described by the project's Code of Conduct are assessed individually. +The enforcement team will make a judgment based on the context and the principles of fairness, transparency, and proportionality. + +Examples include: + +- **Anonymous Reports:** These reports are investigated with extra care to validate the claims while maintaining fairness. +- **Reports Involving Leadership Members:** A separate impartial panel will handle these cases to avoid conflicts of interest. +- **Interactions During Cooling-Off Periods:** Violations during a cooling-off period, such as unintentional online interactions, may be considered differently, with an emphasis on intent and harm caused. + +### Updates to CPG + +The CPG process is a living document that evolves with the community. Feedback is welcome on [GitHub Discussions](https://github.com/orgs/mdn/discussions), [Discord](https://mdn.dev/discord), and changes will be communicated on the community page. diff --git a/files/en-us/mdn/community/getting_started/index.md b/files/en-us/mdn/community/getting_started/index.md index b307f9536f93ced..55f4e027916574a 100644 --- a/files/en-us/mdn/community/getting_started/index.md +++ b/files/en-us/mdn/community/getting_started/index.md @@ -26,7 +26,7 @@ If you do not already have one, go ahead and [sign up](https://github.com/signup If you are new to GitHub, we encourage you to take the following free, self-paced courses and reading material offered by GitHub. With this knowledge, you can focus on your contributions without the burden of learning a new tool at the same time. - [Introduction to GitHub](https://github.com/skills/introduction-to-github) -- [Setting up Git](https://docs.github.com/en/get-started/getting-started-with-git/set-up-git) +- [Setting up Git](https://docs.github.com/en/get-started/git-basics/set-up-git) - [GitHub workflow](https://docs.github.com/en/get-started/using-github/github-flow) - [Using Markdown](https://github.com/skills/communicate-using-markdown) diff --git a/files/en-us/mdn/community/index.md b/files/en-us/mdn/community/index.md index 41f2e7f3dc4cf7d..dc5bacfb4d99ac3 100644 --- a/files/en-us/mdn/community/index.md +++ b/files/en-us/mdn/community/index.md @@ -13,25 +13,32 @@ We also provide extensive [learning resources](/en-US/docs/Learn_web_development - : This section explains how you can start contributing and the type of contributions we accept. Anyone can contribute, and each person who does contribute has an impact on millions of readers. Learn how to contribute and drive innovation on the Open Web. +- [Communication channels](/en-US/docs/MDN/Community/Communication_channels) + - : This page lists communication channels used by the MDN team and our community, with hints on which might be best for you. - [Our repositories](/en-US/docs/MDN/Community/Our_repositories) - : This document describes the GitHub repositories (repos) you may need when contributing to MDN Web Docs. +- [Translated content](/en-US/docs/MDN/Community/Translated_content) + - : MDN Web Docs Localization information, with details about teams, communication channels, and how to get involved. +- [Open source etiquette](/en-US/docs/MDN/Community/Open_source_etiquette) + - : This article gives guidance on how to behave when contributing to MDN and other open source projects, including hints for collaboration and how to handle conflicts. - [GitHub Issues](/en-US/docs/MDN/Community/Issues) - : Issues are used to track all bugs and work that has a clear actionable outcome. This article contains guidelines on opening and working on issues and also covers issue triage and content suggestions. - [Pull requests](/en-US/docs/MDN/Community/Pull_requests) - : This section covers our guidelines for submitting pull requests and what you should expect from the review process. +- [GitHub Discussions](/en-US/docs/MDN/Community/Discussions) + - : On MDN Web Docs, we encourage our community to start and engage in discussions around topics related to the project. + GitHub Discussions are good for gathering feedback on ideas and getting to a consensus on tasks that may have many different approaches. - [Roles and teams](/en-US/docs/MDN/Community/Roles_teams) - : This section provides an overview of the users and teams that are part of the MDN Web Docs project and details what it means to be part of a team. -- [Translated content](MDN/Community/Translated_content) - - : MDN Web Docs Localization information, with details about teams, communication channels, and how to get involved. -- [Open source etiquette](/en-US/docs/MDN/Community/Open_source_etiquette) - - : This article gives guidance on how to behave when contributing to our open source project including rules for contributing, etiquette, and how to handle conflicts. -- [Communication channels](/en-US/docs/MDN/Community/Communication_channels) - - : This page lists communication channels used by the MDN team and our community, with hints on which might be best for you. +- [Community Participation Guidelines (CPG)](/en-US/docs/MDN/Community/Community_Participation_Guidelines) + - : This page lists all the Community Participation Guidelines we have that helps us foster a welcoming, inclusive, and safe community. It also covers [How to Report](/en-US/docs/MDN/Community/Community_Participation_Guidelines#reporting_process) a CPG Violation. +- [MDN Web Docs changelog](/en-US/docs/MDN/Writing_guidelines/Changelog) + - : This document records notable changes to MDN content processes and best practices, with information about when and why they changed. ## Code of conduct -By participating in and contributing to any of our projects in-person or online, you acknowledge that you have read and agree to the [Mozilla Community Participation Guidelines](https://github.com/mdn/mdn-community/blob/main/CODE_OF_CONDUCT.md) (CPG). +By participating in and contributing to any of our projects in-person or online, you acknowledge that you have read and agree to the [Mozilla Community Participation Guidelines](/en-US/docs/MDN/Community/Community_Participation_Guidelines) (CPG). ## General support diff --git a/files/en-us/mdn/community/issues/index.md b/files/en-us/mdn/community/issues/index.md index 481aadb77e97576..8b327b35adb37a1 100644 --- a/files/en-us/mdn/community/issues/index.md +++ b/files/en-us/mdn/community/issues/index.md @@ -24,6 +24,8 @@ Avoid doing the following: - Opening lots of issues asking vague questions. - Asking questions without trying to solve the problem yourself first. +If you want to suggest new documentation or ways to improve the website, see [Proposing new content or features](/en-US/docs/MDN/Community/Issues/Content_suggestions_feature_proposals). + ## Guidelines for reporting an issue [Issues](https://docs.github.com/en/issues/tracking-your-work-with-issues/about-issues) are used to track bugs. An issue must be a single actionable task or a collection of related actionable tasks and must have a clear outcome. @@ -34,7 +36,7 @@ If you think you've found a bug with the content on MDN Web Docs or with the loo ### Reporting an issue -Depending on the type of problem you've discovered, you can report it by filing an issue on one of the main [MDN GitHub repositories](MDN/Community/Our_repositories). +Depending on the type of problem you've discovered, you can report it by filing an issue on one of the main [MDN GitHub repositories](/en-US/docs/MDN/Community/Our_repositories). If the information you provide in the issue is incomplete, you might be asked to provide more details during the [issue triaging process](#review_the_issue_for_completeness_of_information). Here are some hints for opening issues: @@ -44,7 +46,7 @@ Here are some hints for opening issues: - **Issue title** must convey succinctly the _required action_. - **Issue description** must clearly describe the bug and the action required to resolve the issue. It must also list the task or sub-tasks to be completed to resolve the issue. Some other guidelines include: - Use the description field to indicate the status of the task or sub-tasks by using checklists. - - Update the status of a task in the issue description instead of commenting on the issue. Use [task lists](https://docs.github.com/en/get-started/writing-on-github/working-with-advanced-formatting/about-task-lists) in the description if an issue has multiple parts. This helps others who may otherwise need to scroll through comments on the issue to determine the status of various tasks. + - Update the status of a task in the issue description instead of commenting on the issue. Use [task lists](https://docs.github.com/en/get-started/writing-on-github/working-with-advanced-formatting/about-tasklists) in the description if an issue has multiple parts. This helps others who may otherwise need to scroll through comments on the issue to determine the status of various tasks. - Comments in an issue should be limited to details or context that help resolve the issue. - If you find yourself in one of the following situations, move the conversation to [MDN's discussion on GitHub](https://github.com/orgs/mdn/discussions): - A discussion needs to take place to clarify an issue. @@ -55,13 +57,13 @@ Here are some hints for opening issues: ### Creating a task list issue -If the issue you're opening is not to report a bug but to perform a series of tasks, you can create the issue as a [task list](https://docs.github.com/en/get-started/writing-on-github/working-with-advanced-formatting/about-task-lists). +If the issue you're opening is not to report a bug but to perform a series of tasks, you can create the issue as a [task list](https://docs.github.com/en/get-started/writing-on-github/working-with-advanced-formatting/about-tasklists). Explain the context or reason for performing the tasks in the description. Ensure that you list all the actionable tasks as a checklist. For example: -```markdown +```md // Issue title Ensure sections follow the order defined in the CSS property template diff --git a/files/en-us/mdn/community/pull_requests/index.md b/files/en-us/mdn/community/pull_requests/index.md index 6f138c9eeda8171..5f34717c0049382 100644 --- a/files/en-us/mdn/community/pull_requests/index.md +++ b/files/en-us/mdn/community/pull_requests/index.md @@ -28,9 +28,9 @@ The content changes go through the following stages before they are published on ### Values and participation We want MDN Web Docs to be a welcoming, friendly community that we can all be proud of. -All participants must follow our [Code of Conduct](https://github.com/mdn/content/blob/main/CODE_OF_CONDUCT.md) which means adhering to [Mozilla's Community Participation Guidelines](https://www.mozilla.org/en-US/about/governance/policies/participation/). +All participants must follow our [Community Participation Guidelines](/en-US/docs/MDN/Community/Community_Participation_Guidelines) which are derived from [Mozilla's Community Participation Guidelines](https://www.mozilla.org/en-US/about/governance/policies/participation/). Be polite and constructive when opening pull requests, writing review comments, interacting with the pull request author or other community members. -If you or someone else has experienced behavior that is potentially illegal or makes you feel unsafe, unwelcome, or uncomfortable, we encourage you to [report it](https://www.mozilla.org/en-US/about/governance/policies/participation/reporting/). +If you or someone else has experienced behavior that is potentially illegal or makes you feel unsafe, unwelcome, or uncomfortable, we encourage you to [report it](/en-US/docs/MDN/Community/Community_Participation_Guidelines#reporting_process). ### Before you start @@ -115,7 +115,7 @@ Do leave the door open to the author to ask for help, especially new contributor ### Reviewing a pull request -When it comes to the changes in a pull request, content and prose must adhere to the [MDN Writing style guide](/en-US/docs/MDN/Writing_guidelines/Writing_style_guide) and example code must follow the [code style guide](/en-US/docs/MDN/Writing_guidelines/Writing_style_guide/Code_style_guide). +When it comes to the changes in a pull request, content and prose must adhere to the [MDN Writing style guide](/en-US/docs/MDN/Writing_guidelines/Writing_style_guide) and example code must follow the [code style guide](/en-US/docs/MDN/Writing_guidelines/Code_style_guide). When you are reviewing a pull request, you should: diff --git a/files/en-us/mdn/community/security_vulnerability_response/index.md b/files/en-us/mdn/community/security_vulnerability_response/index.md deleted file mode 100644 index 95c2339b23cfd4a..000000000000000 --- a/files/en-us/mdn/community/security_vulnerability_response/index.md +++ /dev/null @@ -1,37 +0,0 @@ ---- -title: Security vulnerability response steps -slug: MDN/Community/Security_vulnerability_response -page-type: mdn-community-guide -sidebar: mdnsidebar ---- - -## A little history - -On ~27 November 2018 an npm security vulnerability was announced for all users that depend, either directly or indirectly, on the [event-stream](https://snyk.io/blog/malicious-code-found-in-npm-package-event-stream/) package. It was a very targeted attack, that only activated if the Copay bitcoin wallet was installed, whereupon it tried to steal the contents. - -Two of our projects, namely [interactive-examples](https://github.com/mdn/interactive-examples/) and [BoB](https://github.com/mdn/bob/), depend on an npm package called [npm-run-all](https://www.npmjs.com/package/npm-run-all), which in turn depended on the event-stream package. - -This meant that not only was staff at risk, but people who have forked either of these repositories might have been affected as well. Thankfully the maintainers of the affected package reacted swiftly and released an update to address the issue. Because we have the [Renovate bot](https://github.com/marketplace/renovate) running against these repositories, there was a [pull request](https://github.com/mdn/interactive-examples/pull/1239/) ready to merge. - -This only resolved one part of the problem though. Our users still needed to be notified. - -## Steps taken - -The community for especially the interactive-examples project was rather large, and not everyone active, but we still needed a way to reach out to everyone. The first step was then to open an issue against each of the repositories detailing the problem: - -- [interactive-examples](https://github.com/mdn/interactive-examples/issues/1242) -- [bob](https://github.com/mdn/bob/issues/184) - -That by itself is not enough as users do not necessarily actively monitor issues. We, therefore, needed to look at all of the [forks](https://github.com/mdn/interactive-examples/network/members) of the project. - -We then copied all of the usernames for these users and pinged them on the above issue, for example by [commenting](https://github.com/mdn/interactive-examples/issues/1242#issuecomment-442110598) in it. - -This was very effective, judging from the responses the issue received, but we could not leave it there. The next step was to post a comment on each of the open pull requests informing the user of the problem and what their next steps should be. Here is an [example](https://github.com/mdn/interactive-examples/pull/1144) of our answer. - -With this, we felt rather confident that between us reaching out, and coverage of the issue online by npm and other channels, would ensure that we ensured our users are safe. - -As a final step, we tweeted from our official Twitter account to raise awareness of the issue. - -### In closing - -Hopefully, these types of incidents will be few and far between. Should this happen again however, the above provides a solid guideline on how to respond. diff --git a/files/en-us/mdn/community/translated_content/index.md b/files/en-us/mdn/community/translated_content/index.md index cb3f62dbacf6672..25936253c3bad8d 100644 --- a/files/en-us/mdn/community/translated_content/index.md +++ b/files/en-us/mdn/community/translated_content/index.md @@ -56,6 +56,22 @@ If you need help or have any questions, feel free to get in touch with one of th - Discussions: [Matrix (`#mdn-l10n-es`)](https://chat.mozilla.org/#/room/#mdn-l10n-es:mozilla.org), [Telegram (`MDN l10n ES`)](https://t.me/+Dr6qKQCAepw4MjFj), [Discord (`#spanish`)](/discord) - Current maintainers: [JuanVqz](https://github.com/JuanVqz), [davbrito](https://github.com/davbrito), [Graywolf9](https://github.com/Graywolf9), [Vallejoanderson](https://github.com/Vallejoanderson), [marcelozarate](https://github.com/marcelozarate), [Jalkhov](https://github.com/Jalkhov) +## Machine-translated locales + +The following experimental locales are machine-translated from the English locale. + +### German (`de`) + +- Repository: [mdn/translated-content-de](https://github.com/mdn/translated-content-de) +- Discussions: [Discord (`#german`)](/discord) +- Current maintainers: [caugner](https://github.com/caugner) + +### Italian (`it`) + +- Repository: [mdn/translated-content-it](https://github.com/mdn/translated-content-it) +- Discussions: [Discord (`#italian`)](/discord) +- Current maintainers: [caugner](https://github.com/caugner) + ## See also - [MDN localization update, February 2021](https://hacks.mozilla.org/2021/02/mdn-localization-update-february-2021/) — the latest state of localization on MDN diff --git a/files/en-us/mdn/guides/index.md b/files/en-us/mdn/guides/index.md index 8109b4f848e2355..6023fe5da32a212 100644 --- a/files/en-us/mdn/guides/index.md +++ b/files/en-us/mdn/guides/index.md @@ -41,7 +41,7 @@ This page is a curated list of some of the most popular goal-oriented learning m - [Using FormData objects](/en-US/docs/Web/API/XMLHttpRequest_API/Using_FormData_Objects) - : The [`FormData`](/en-US/docs/Web/API/FormData) object lets you compile a set of key/value pairs to send using {{domxref("Window/fetch", "fetch()")}}. It's primarily intended for sending form data, but can be used independently of forms to transmit keyed data. The transmission is in the same format that the form's `submit()` method would use to send the data if the form's encoding type were set to "multipart/form-data". -- [Progressive web apps](/en-US/docs/Web/Progressive_web_apps#core_pwa_guides) +- [Progressive web apps](/en-US/docs/Web/Progressive_web_apps) - : Progressive web apps (PWAs) use modern web APIs along with traditional progressive enhancement strategy to create cross-platform web applications. These apps work everywhere and provide several features that give them the same user experience advantages as native apps. This set of guides tells you all you need to know about PWAs. - [Parsing and serializing XML](/en-US/docs/Web/XML/Guides/Parsing_and_serializing_XML) - : The web platform provides different methods of parsing and serializing XML, each with its pros and cons. diff --git a/files/en-us/mdn/kitchensink/index.md b/files/en-us/mdn/kitchensink/index.md index 5c0073d5c0a63d6..47235b492508ca2 100644 --- a/files/en-us/mdn/kitchensink/index.md +++ b/files/en-us/mdn/kitchensink/index.md @@ -29,7 +29,7 @@ Text that uses the `<kbd>` tag: <kbd>Shift</kbd> ### Another one… -{{PreviousNext("Games/Workflows/2D_Breakout_game_Phaser/Extra_lives", "Games/Workflows/2D_Breakout_game_Phaser/Buttons")}} +{{PreviousNext("Games/Tutorials/2D_breakout_game_Phaser/Extra_lives", "Games/Tutorials/2D_breakout_game_Phaser/Buttons")}} ## Code snippets @@ -76,7 +76,7 @@ const f = () => { ### WebAssembly -```wasm +```wat (func (param i32) (param f32) (local f64) local.get 0 local.get 1 @@ -106,9 +106,95 @@ class BookListView(generic.ListView): template_name = 'books/my_arbitrary_template_name_list.html' ``` -## Interactive Examples +## Interactive examples -{{EmbedInteractiveExample("pages/tabbed/abbr.html", "tabbed-shorter")}} {{EmbedInteractiveExample("pages/css/order.html")}} {{EmbedInteractiveExample("pages/js/regexp-assertions.html", "taller")}} +{{InteractiveExample("HTML Demo: &lt;data&gt;", "tabbed-shorter")}} + +```html interactive-example +<p>New Products:</p> +<ul> + <li><data value="398">Mini Ketchup</data></li> + <li><data value="399">Jumbo Ketchup</data></li> + <li><data value="400">Mega Jumbo Ketchup</data></li> +</ul> +``` + +```css interactive-example +data:hover::after { + content: " (ID " attr(value) ")"; + font-size: 0.7em; +} +``` + +{{InteractiveExample("JavaScript Demo: Set.prototype[Symbol.iterator]()")}} + +```js interactive-example +const set1 = new Set(); + +set1.add(42); +set1.add("forty two"); + +const iterator1 = set1[Symbol.iterator](); + +console.log(iterator1.next().value); +// Expected output: 42 + +console.log(iterator1.next().value); +// Expected output: "forty two" +``` + +{{InteractiveExample("CSS Demo: filter")}} + +```css interactive-example-choice +filter: url("/shared-assets/images/examples/shadow.svg#element-id"); +``` + +```css interactive-example-choice +filter: blur(5px); +``` + +```css interactive-example-choice +filter: contrast(200%); +``` + +```css interactive-example-choice +filter: grayscale(80%); +``` + +```css interactive-example-choice +filter: hue-rotate(90deg); +``` + +```css interactive-example-choice +filter: drop-shadow(16px 16px 20px red) invert(75%); +``` + +```html interactive-example +<section id="default-example"> + <div class="example-container"> + <img + id="example-element" + src="/shared-assets/images/examples/firefox-logo.svg" + width="200" /> + </div> +</section> +``` + +```css interactive-example +.example-container { + background-color: #fff; + width: 260px; + height: 260px; + display: flex; + align-items: center; + justify-content: center; +} + +#example-element { + flex: 1; + padding: 30px; +} +``` ## Tables @@ -130,17 +216,17 @@ class BookListView(generic.ListView): <tbody> <tr> <th scope="row"> - <a href="/en-US/docs/Web/HTML/Content_categories">Content categories</a> + <a href="/en-US/docs/Web/HTML/Guides/Content_categories">Content categories</a> </th> <td> - <a href="/en-US/docs/Web/HTML/Content_categories#flow_content">Flow content</a>, - <a href="/en-US/docs/Web/HTML/Content_categories#phrasing_content">phrasing content</a>, palpable content. + <a href="/en-US/docs/Web/HTML/Guides/Content_categories#flow_content">Flow content</a>, + <a href="/en-US/docs/Web/HTML/Guides/Content_categories#phrasing_content">phrasing content</a>, palpable content. </td> </tr> <tr> <th scope="row">Permitted content</th> <td> - <a href="/en-US/docs/Web/HTML/Content_categories#phrasing_content">Phrasing content</a>. + <a href="/en-US/docs/Web/HTML/Guides/Content_categories#phrasing_content">Phrasing content</a>. </td> </tr> <tr> @@ -150,7 +236,7 @@ class BookListView(generic.ListView): <tr> <th scope="row">Permitted parents</th> <td> - Any element that accepts <a href="/en-US/docs/Web/HTML/Content_categories#phrasing_content">phrasing content</a>. + Any element that accepts <a href="/en-US/docs/Web/HTML/Guides/Content_categories#phrasing_content">phrasing content</a>. </td> </tr> <tr> @@ -320,16 +406,16 @@ The [`AvailableInWorkers`](https://github.com/mdn/rari/blob/main/crates/rari-doc {{AvailableInWorkers}} -- [`button`](/en-US/docs/Web/Accessibility/ARIA/Roles/button_role) -- [`checkbox`](/en-US/docs/Web/Accessibility/ARIA/Roles/checkbox_role) -- [`menuitem`](/en-US/docs/Web/Accessibility/ARIA/Roles/menuitem_role) -- [`menuitemcheckbox`](/en-US/docs/Web/Accessibility/ARIA/Roles/menuitemcheckbox_role) -- [`menuitemradio`](/en-US/docs/Web/Accessibility/ARIA/Roles/menuitemradio_role) -- [`option`](/en-US/docs/Web/Accessibility/ARIA/Roles/option_role) -- [`radio`](/en-US/docs/Web/Accessibility/ARIA/Roles/radio_role) -- [`switch`](/en-US/docs/Web/Accessibility/ARIA/Roles/switch_role) -- [`tab`](/en-US/docs/Web/Accessibility/ARIA/Roles/tab_role) -- [`treeitem`](/en-US/docs/Web/Accessibility/ARIA/Roles/treeitem_role) +- [`button`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/button_role) +- [`checkbox`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/checkbox_role) +- [`menuitem`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/menuitem_role) +- [`menuitemcheckbox`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/menuitemcheckbox_role) +- [`menuitemradio`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/menuitemradio_role) +- [`option`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/option_role) +- [`radio`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/radio_role) +- [`switch`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/switch_role) +- [`tab`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/tab_role) +- [`treeitem`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/treeitem_role) <!----> @@ -356,8 +442,8 @@ The [`AvailableInWorkers`](https://github.com/mdn/rari/blob/main/crates/rari-doc - {{SVGElement("feGaussianBlur")}} - {{SVGAttr("keySplines")}} SVG attribute -- [dir](/en-US/docs/Web/HTML/Global_attributes#dir) -- [lang](/en-US/docs/Web/HTML/Global_attributes#lang) +- [dir](/en-US/docs/Web/HTML/Reference/Global_attributes#dir) +- [lang](/en-US/docs/Web/HTML/Reference/Global_attributes#lang) - {{cssxref(":dir")}} - {{cssxref("direction")}} diff --git a/files/en-us/mdn/tutorials/index.md b/files/en-us/mdn/tutorials/index.md index a87096b9d5ae86c..67448e5909265c4 100644 --- a/files/en-us/mdn/tutorials/index.md +++ b/files/en-us/mdn/tutorials/index.md @@ -34,7 +34,7 @@ These tutorials are created by forward-thinking companies and web developers who - [Web forms](/en-US/docs/Learn_web_development/Extensions/Forms) - : Forms are a very important part of the Web — these provide much of the functionality you need for interacting with websites, such as registering and logging in, sending feedback, buying products, and more. This module gets you started with creating the client-side parts of forms. -- [Tips for authoring fast-loading HTML pages](/en-US/docs/Learn_web_development/Howto/Solve_HTML_problems/Author_fast-loading_HTML_pages) +- [Tips for authoring fast-loading HTML pages](/en-US/docs/Web/HTML/How_to/Author_fast-loading_HTML_pages) - : Optimize web pages to provide a more responsive site for visitors and reduce the load on your web server and Internet connection. ## CSS tutorials @@ -86,8 +86,8 @@ These tutorials are created by forward-thinking companies and web developers who - : What is JavaScript and how can it help you? - [Codecademy](https://www.codecademy.com/) - : Codecademy is an easy way to learn how to code JavaScript. It's interactive and you can do it with your friends. -- [freeCodeCamp](https://www.freecodecamp.org) - - : freeCodeCamp teaches a variety of languages and frameworks for web development. It also has a [forum](https://forum.freecodecamp.org/), an [internet radio station](https://coderadio.freecodecamp.org), and a [blog](https://www.freecodecamp.org/news). +- [freeCodeCamp](https://www.freecodecamp.org/) + - : freeCodeCamp teaches a variety of languages and frameworks for web development. It also has a [forum](https://forum.freecodecamp.org/), an [internet radio station](https://coderadio.freecodecamp.org/), and a [blog](https://www.freecodecamp.org/news). ### Intermediate JavaScript topics diff --git a/files/en-us/mdn/writing_guidelines/changelog/index.md b/files/en-us/mdn/writing_guidelines/changelog/index.md index 71920a2f08b0368..8aef143957de6dd 100644 --- a/files/en-us/mdn/writing_guidelines/changelog/index.md +++ b/files/en-us/mdn/writing_guidelines/changelog/index.md @@ -26,7 +26,7 @@ Conversion to Markdown is done, so remove the old CSS style guide and redirect t Multiple updates to the CSS style guide to reflect the move towards Markdown, and encourage authors to write HTML in a Markdown-compatible way. -- Note and warning boxes no longer have a separate `<h4>` heading for the title (e.g. `<h4>Warning</h4>`). +- Note and warning boxes no longer have a separate `<h4>` heading for the title (e.g., `<h4>Warning</h4>`). See our [Markdown in MDN](/en-US/docs/MDN/Writing_guidelines/Howto/Markdown_in_MDN#notes_warnings_and_callouts) guide for the correct syntax. @@ -39,9 +39,9 @@ Multiple updates to the CSS style guide to reflect the move towards Markdown, an ### Multiline JavaScript and API syntax blocks -Previously, the syntax blocks of JavaScript builtin and WebAPI methods that can be used in multiple different ways (i.e. various parameters are optional) were commonly written using [BNF formal syntax notation](https://en.wikipedia.org/wiki/Backus%E2%80%93Naur_form). Most notably, square brackets were used to signify optional parameters. +Previously, the syntax blocks of JavaScript builtin and WebAPI methods that can be used in multiple different ways (i.e., various parameters are optional) were commonly written using [BNF formal syntax notation](https://en.wikipedia.org/wiki/Backus%E2%80%93Naur_form). Most notably, square brackets were used to signify optional parameters. -This was problematic — many developers were confused by this, and it conflicts with valid syntax forms in other programming languages (e.g. `[]` is also an array in JavaScript). +This was problematic — many developers were confused by this, and it conflicts with valid syntax forms in other programming languages (e.g., `[]` is also an array in JavaScript). As a result, going forward we are now writing multiple syntax forms of a method on separate lines inside the syntax block. See [Syntax sections > Multiple lines/Optional parameters](/en-US/docs/MDN/Writing_guidelines/Page_structures/Syntax_sections#multiple_linesoptional_parameters) for further information and examples. diff --git a/files/en-us/mdn/writing_guidelines/code_style_guide/css/index.md b/files/en-us/mdn/writing_guidelines/code_style_guide/css/index.md new file mode 100644 index 000000000000000..4e6b44ddba0777c --- /dev/null +++ b/files/en-us/mdn/writing_guidelines/code_style_guide/css/index.md @@ -0,0 +1,175 @@ +--- +title: Guidelines for writing CSS code examples +short-title: CSS examples +slug: MDN/Writing_guidelines/Code_style_guide/CSS +page-type: mdn-writing-guide +sidebar: mdnsidebar +--- + +The following guidelines cover how to write CSS example code for MDN Web Docs. + +## General guidelines for CSS code examples + +### Choosing a format + +Opinions on correct indentation, whitespace, and line lengths have always been controversial. Discussions on these topics are a distraction from creating and maintaining content. + +On MDN Web Docs, we use [Prettier](https://prettier.io/) as a code formatter to keep the code style consistent (and to avoid off-topic discussions). You can consult our [configuration file](https://github.com/mdn/content/blob/main/.prettierrc.json) to learn about the current rules, and read the [Prettier documentation](https://prettier.io/docs/index.html). + +Prettier formats all the code and keeps the style consistent. Nevertheless, there are a few additional rules that you need to follow. + +### Plan your CSS + +Before diving in and writing huge chunks of CSS, plan your styles carefully. What general styles are going to be needed, what different layouts do you need to create, what specific overrides need to be created, and are they reusable? Above all, you need to try to **avoid too much overriding**. If you keep finding yourself writing styles and then cancelling them again a few rules down, you probably need to rethink your strategy. + +### Use flexible/relative units + +For maximum flexibility over the widest possible range of devices, it is a good idea to size containers, padding, etc. using relative units like ems and rems or percentages and viewport units if you want them to vary depending on viewport width. You can read some more about this in our [guide to CSS values and units](/en-US/docs/Learn_web_development/Core/Styling_basics/Values_and_units#relative_length_units). + +### Don't use preprocessors + +Don't use preprocessor syntax, such as [Sass](https://sass-lang.com/), [Less](https://lesscss.org/), or [Stylus](https://stylus-lang.com/), in the example code. On MDN Web Docs, we document the vanilla CSS language. Using preprocessors will only raise the bar to understanding the examples, potentially confusing readers. + +### Don't use specific CSS methodologies + +In the same spirit as the previous guideline, don't write example codes on MDN Web Docs using a specific CSS methodology such as [BEM](https://getbem.com/naming/) or [SMACSS](https://smacss.com/). Even though they are valid CSS syntax, the naming conventions can be confusing to people not familiar with those methodologies. + +### Don't use resets + +For maximum control over CSS across platforms, a lot of people used to use CSS resets to remove every style, before then building things back up themselves. This certainly has its merits, but especially in the modern world, CSS resets can be an overkill, resulting in a lot of extra time spent reimplementing things that weren't completely broken in the first place, like default margins, list styles, etc. + +If you really feel like you need to use a reset, consider using [normalize.css by Nicolas Gallagher](https://necolas.github.io/normalize.css/), which aims to just make things more consistent across browsers, get rid of some default annoyances that we always remove (the margins on `<body>`, for example) and fix a few bugs. + +## !important + +`!important` is the last resort that is generally used only when you need to override something and there is no other way to do it. Using `!important` is a bad practice and you should avoid it wherever possible. + +```css example-bad +.bad-code { + font-size: 4rem !important; +} +``` + +## CSS comments + +Use CSS-style comments to comment code that isn't self-documenting. Also note that you should leave a space between the asterisks and the comment. + +```css example-good +/* This is a CSS-style comment */ +``` + +Put your comments on separate lines preceding the code they are referring to, like so: + +```css example-good +h3 { + /* Creates a red drop shadow, offset 1px right and down, w/2px blur radius */ + text-shadow: 1px 1px 2px red; + /* Sets the font-size to double the default document font size */ + font-size: 2rem; +} +``` + +## Double quotes around values + +Where quotes can or should be included, use them, and use double quotes. For example: + +```css example-good +[data-vegetable="liquid"] { + background-color: goldenrod; + background-image: url("../../media/examples/lizard.png"); +} +``` + +## Longhand vs. shorthand rules + +Usually, when teaching the specifics of CSS syntax, it is clearer and more obvious to use longhand properties, rather than terse shorthand (unless, of course, you're explaining shorthand through the example). Remember that the point of examples on MDN Web Docs is to teach people, not to be clever or efficient. We explain here why writing with longhand rules is recommended. + +- It is often harder to understand what the shorthand is doing. In the example below, it takes a while to pick apart exactly what the {{cssxref("font")}} syntax is doing. + + ```css + font: small-caps bold 2rem/1.5 sans-serif; + ``` + + Whereas the following style is clearer: + + ```css + font-variant: small-caps; + font-weight: bold; + font-size: 2rem; + line-height: 1.5; + font-family: sans-serif; + ``` + +- CSS shorthand comes with potential added pitfalls — default values are set for parts of the syntax that you don't explicitly set, which can produce unexpected resets of values you've set earlier in the cascade or other expected effects. The {{cssxref("grid")}} property, for example, sets all of the following default values for items that are not specified: + + - {{cssxref("grid-template-rows")}}: `none` + - {{cssxref("grid-template-columns")}}: `none` + - {{cssxref("grid-template-areas")}}: `none` + - {{cssxref("grid-auto-rows")}}: `auto` + - {{cssxref("grid-auto-columns")}}: `auto` + - {{cssxref("grid-auto-flow")}}: `row` + - {{cssxref("column-gap")}}: `0` + - {{cssxref("row-gap")}}: `0` + - {{cssxref("column-gap")}}: `normal` + - {{cssxref("row-gap")}}: `normal` + +- Some shorthands only work as expected if you include the different value components in a certain order. This is the case in CSS animations. In the example below, the expected order is written as a comment: + + ```css + /* duration | timing-function | delay | iteration-count + direction | fill-mode | play-state | name */ + animation: 3s ease-in 1s 2 reverse both paused slide-in; + ``` + + In this example, the first value that can be parsed as a [`<time>`](/en-US/docs/Web/CSS/time) is assigned to the [`animation-duration`](/en-US/docs/Web/CSS/animation-duration) property, and the second value that can be parsed as time is assigned to [`animation-delay`](/en-US/docs/Web/CSS/animation-delay). (For more information, see [animation syntax](/en-US/docs/Web/CSS/animation#syntax) details.) + +## Mobile-first media queries + +In a stylesheet that contains [media query](/en-US/docs/Web/CSS/CSS_media_queries/Using_media_queries) styles for different target viewport sizes, first include the narrow screen/mobile styling before any other media queries are encountered. Add styling for wider viewport sizes via successive media queries. Following this rule has many advantages that are explained in [Responsive design](/en-US/docs/Learn_web_development/Core/CSS_layout/Responsive_Design). + +```css example-good +/* Default CSS layout for narrow screens */ + +@media (min-width: 480px) { + /* CSS for medium width screens */ +} + +@media (min-width: 800px) { + /* CSS for wide screens */ +} + +@media (min-width: 1100px) { + /* CSS for really wide screens */ +} +``` + +## Selectors + +- Don't use ID selectors because they are: + + - less flexible; you can't add more if you discover you need more than one. + - harder to override because they have higher specificity than classes. + + ```css example-good + .editorial-summary { + /* ... */ + } + ``` + + ```css example-bad + #editorial-summary { + /* ... */ + } + ``` + +## Value to turn off properties + +When turning off borders (and any other properties that can take `0` or `none` as values), use `0` rather than `none`: + +```css example-good +border: 0; +``` + +## See also + +[CSS reference index](/en-US/docs/Web/CSS/Reference#index) - browse through our CSS property reference pages to check out some good, concise, meaningful CSS snippets. Our interactive examples in the "Try it" section are generally written to follow the guidelines described on this page. diff --git a/files/en-us/mdn/writing_guidelines/code_style_guide/html/index.md b/files/en-us/mdn/writing_guidelines/code_style_guide/html/index.md new file mode 100644 index 000000000000000..08c1a5f4f00620a --- /dev/null +++ b/files/en-us/mdn/writing_guidelines/code_style_guide/html/index.md @@ -0,0 +1,142 @@ +--- +title: Guidelines for writing HTML code examples +short-title: HTML examples +slug: MDN/Writing_guidelines/Code_style_guide/HTML +page-type: mdn-writing-guide +sidebar: mdnsidebar +--- + +The following guidelines cover how to write HTML example code for MDN Web Docs. + +## General guidelines for HTML code examples + +### Choosing a format + +Opinions on correct indentation, whitespace, and line lengths have always been controversial. Discussions on these topics are a distraction from creating and maintaining content. + +On MDN Web Docs, we use [Prettier](https://prettier.io/) as a code formatter to keep the code style consistent (and to avoid off-topic discussions). You can consult our [configuration file](https://github.com/mdn/content/blob/main/.prettierrc.json) to learn about the current rules, and read the [Prettier documentation](https://prettier.io/docs/index.html). + +Prettier formats all the code and keeps the style consistent. Nevertheless, there are a few additional rules that you need to follow. + +## Complete HTML document + +> [!NOTE] +> The guidelines in this section apply only when you need to show a complete HTML document. A snippet is usually enough to demonstrate a feature. When using the [EmbedLiveSample macro](/en-US/docs/MDN/Writing_guidelines/Page_structures/Code_examples#live_samples), just include the HTML snippet; it will automatically be inserted into a full HTML document when displayed. + +### Doctype + +You should use the HTML5 {{Glossary("Doctype", "doctype")}}. + +```html example-good +<!doctype html> +``` + +### Document language + +Set the document language using the [`lang`](/en-US/docs/Web/HTML/Reference/Global_attributes/lang) attribute on your {{htmlelement("html")}} element: + +```html example-good +<html lang="en-US"></html> +``` + +This is good for accessibility and search engines, helps with localizing content, and reminds people to use best practices. + +### Document character set + +You should also define your document's character set like so: + +```html example-good +<meta charset="utf-8" /> +``` + +Use UTF-8 unless you have a very good reason not to; it will cover all character needs pretty much regardless of what language you are using in your document. + +### Viewport meta tag + +Finally, you should always add the viewport meta tag into your HTML {{HTMLElement("head")}} to give the code example a better chance of working on mobile devices. You should include at least the following in your document, which can be modified later on as the need arises: + +```html example-good +<meta name="viewport" content="width=device-width" /> +``` + +See [Using the viewport meta tag to control layout on mobile browsers](/en-US/docs/Web/HTML/Guides/Viewport_meta_element) for further details. + +## Attributes + +You should put all attribute values in double quotes. It is tempting to omit quotes since HTML5 allows this, but markup is neater and easier to read if you do include them. For example, this is better: + +```html example-good +<img src="images/logo.jpg" alt="A circular globe icon" class="no-border" /> +``` + +…than this: + +```html-nolint example-bad +<img src=images/logo.jpg alt=A circular globe icon class=no-border> +``` + +Omitting quotes can also cause problems. In the above example, the `alt` attribute will be interpreted as multiple attributes because there are no quotes to specify that "A circular globe icon" is a single attribute value. + +## Boolean attributes + +Don't include values for boolean attributes (but do include values for {{glossary("enumerated")}} attributes); you can just write the attribute name to set it. For example, you can write: + +```html example-good +<input required /> +``` + +This is perfectly understandable and works fine. If a boolean HTML attribute is present, the value is true. While including a value will work, it is not necessary and incorrect: + +```html example-bad +<input required="required" /> +``` + +## Casing convention on MDN + +Use lowercase for all case-insensitive constructs, including the doctype declaration, element names, and attribute names/values. This creates a consistent appearance and allows for faster markup writing. + +```html example-good +<p class="nice">This looks nice and neat</p> +``` + +```html-nolint example-bad +<P CLASS="WHOA-THERE">Why is my markup shouting?</P> +``` + +## Class and ID names + +Use semantic class/ID names, and separate multiple words with hyphens ({{Glossary("kebab_case", "kebab case")}}). Don't use {{Glossary("camel_case", "camel case")}}. For example: + +```html example-good +<p class="editorial-summary">Blah blah blah</p> +``` + +```html example-bad +<p class="bigRedBox">Blah blah blah</p> +``` + +## Character references + +Don't use {{glossary("character reference", "character references")}} unnecessarily — use the literal character wherever possible (you'll still need to escape characters like angle brackets and quote marks). + +As an example, you could just write: + +```html example-good +<p>© 2018 Me</p> +``` + +Instead of: + +```html example-bad +<p>&copy; 2018 Me</p> +``` + +## HTML elements + +There are some rules for writing about HTML elements on MDN Web Docs. Adhering to these rules produces consistent descriptions of elements and their components and also ensures correct linking to detailed documentation. + +- **Element names**: Use the [`HTMLElement`](https://github.com/mdn/rari/blob/main/crates/rari-doc/src/templ/templs/links/htmlxref.rs) macro, which creates a link to the MDN Web Docs page for that element. For example, writing `\{{HTMLElement("title")}}` produces "{{HTMLElement("title")}}". + If you don't want to create a link, **enclose the name in angle brackets** and use the "Inline Code" style (e.g., `<title>`). +- **Attribute names**: Use "Inline Code" style to put attribute names in `code font`. + Additionally, put them in **`bold face`** when the attribute is mentioned in association with an explanation of what it does or when it is used for the first time on the page. +- **Attribute values**: Use the "Inline Code" style to apply `<code>` to attribute values, and don't use quotation marks around string values, unless needed by the syntax of a code sample. For example, "When the `type` attribute of an `<input>` element is set to `email` or `tel` ...". diff --git a/files/en-us/mdn/writing_guidelines/code_style_guide/index.md b/files/en-us/mdn/writing_guidelines/code_style_guide/index.md new file mode 100644 index 000000000000000..ed1e3967305b9bd --- /dev/null +++ b/files/en-us/mdn/writing_guidelines/code_style_guide/index.md @@ -0,0 +1,188 @@ +--- +title: Guidelines for writing code examples +short-title: Code style +slug: MDN/Writing_guidelines/Code_style_guide +page-type: mdn-writing-guide +sidebar: mdnsidebar +--- + +This article describes code style and formatting guidelines for code examples on MDN Web Docs, irrespective of programming language. +For guidelines about prose and other content, see the [writing style guide](/en-US/docs/MDN/Writing_guidelines/Writing_style_guide#code_examples). + +For technology-specific guidelines, see the following articles: + +- [HTML guidelines](/en-US/docs/MDN/Writing_guidelines/Code_style_guide/HTML) +- [CSS guidelines](/en-US/docs/MDN/Writing_guidelines/Code_style_guide/CSS) +- [JavaScript guidelines](/en-US/docs/MDN/Writing_guidelines/Code_style_guide/JavaScript) +- [Shell prompt guidelines](/en-US/docs/MDN/Writing_guidelines/Code_style_guide/Shell) + +## General principles for code examples + +There is one overarching consideration that you need to keep in mind: **Readers will copy and paste examples into their own code and may put it into production.** +Therefore, you should make sure that code examples are usable, follow generally accepted best practices, and do not do anything that will cause an application to be insecure, inefficient, bloated, or inaccessible. + +If the code example is not runnable or production-worthy, include a warning in a code comment and in the explanatory text; for example, if it is only a snippet and not a full example, make this clear. This also means that you should provide all of the information necessary to run the example including any dependencies and setup information. + +Code examples should be straightforward enough to be understandable, but complex enough to do something interesting, and (preferably) useful. +The aim is not necessarily to produce efficient, clever code that impresses experts and has great functionality, but rather to share reduced working examples that can be understood and learned from as quickly as possible. + +Some more general guidelines include: + +- Code examples should be short and should ideally only show the feature you are immediately interested in. +- Write your code to be as understandable as possible, even if it is not the most efficient way to write it. +- Don't include unnecessary server-side code, libraries, frameworks, preprocessors, and other such dependencies. They make the code less portable and harder to run and understand. Use vanilla code where possible. +- Don't assume readers' knowledge of any libraries, frameworks, preprocessors, or other non-native features. For example, use class names that make sense within the example rather than class names that make sense to BEM or Bootstrap users. +- Be inclusive in your code examples; consider that MDN readers come from all over the world, and are diverse in their ethnicities, religions, ages, genders, etc. Ensure text in code examples reflects that diversity and is inclusive of all people. +- Don't use deprecated features for brevity (such as presentation elements like {{HTMLElement("big")}} or {{domxref("Document.write", "document.write()")}}); do it correctly. +- In the case of API demos, if you are using multiple APIs together, point out which APIs are included and which features come from where. + +## MDN code style and formatting + +Opinions on correct indentation, whitespace, and line lengths have always been controversial. Discussions on these topics are a distraction from creating and maintaining content. +On MDN Web Docs, we use [Prettier](https://prettier.io/) as a code formatter to keep the code style consistent and to avoid off-topic discussions. You can check our [configuration file](https://github.com/mdn/content/blob/main/.prettierrc.json) to learn about the current rules, and read the [Prettier documentation](https://prettier.io/docs/index.html). + +Aside from automated formatting, there are a few other rules for code examples on MDN so that the result is rendered well. + +### Choose the correct language + +To ensure proper formatting and syntax highlighting of code blocks, specify the language of the code block properly. +See [Example code blocks in MDN Markdown](/en-US/docs/MDN/Writing_guidelines/Howto/Markdown_in_MDN#example_code_blocks) for a list of languages supported by MDN, as well as details on how to request a new language. + +If the code block is pseudocode, the output of a command, or otherwise not a programming language, set the language to `plain`: + +````md +```plain +StaleElementReferenceException: The element reference of ABD-123 is stale… +``` +```` + +> [!WARNING] +> If the desired language is not yet supported by MDN, do **not** set the language of a code block to a similar language, as doing so may have unintended side effects with Prettier formatting and syntax highlighting. + +### Code line length + +Code lines shouldn't be so long that they require horizontal scrolling to read. +Break long lines at natural breaking points for the sake of readability, but not at the expense of best practices. +For example, this is not great: + +```js example-bad +let tommyCat = + "Said Tommy the Cat as he reeled back to clear whatever foreign matter may have nestled its way into his mighty throat. Many a fat alley rat had met its demise while staring point blank down the cavernous barrel of this awesome prowling machine."; +``` + +This is better, but somewhat awkward: + +```js +const tommyCat = + "Said Tommy the Cat as he reeled back to clear whatever foreign " + + "matter may have nestled its way into his mighty throat. Many a fat alley rat " + + "had met its demise while staring point blank down the cavernous barrel of " + + "this awesome prowling machine."; +``` + +Even better is to use a template literal: + +```js example-good +const tommyCat = `Said Tommy the Cat as he reeled back to clear whatever foreign + matter may have nestled its way into his mighty throat. Many a fat alley rat + had met its demise while staring point blank down the cavernous barrel of + this awesome prowling machine.`; +``` + +### Code block height + +Code blocks should be as long as they need to be, but no longer. Ideally, aim for something short, like 15-25 lines. If a code block is going to be a lot longer, consider showing the most useful part and link to a complete example in a GitHub repo, Gist, or CodePen, for example. + +### Inline code formatting + +Use inline code syntax to mark up function names, variable names, and method names. For example: "the `frenchText()` function" is written in markdown as: + +```md +the `frenchText()` function +``` + +Method names should be followed by a pair of parentheses: for example, `doSomethingUseful()`. The parentheses help differentiate methods from other code terms. + +## Guidelines for proper rendering + +These guidelines should be followed to ensure that the code examples you write display properly on MDN Web Docs. You should also consider responsiveness making writing code examples so that they are also useful on mobile devices. + +### Size of the rendered code example + +- **Set the width to 100%**: The main content pane on MDN Web Docs is about 700px wide on desktop, so the embedded code examples must look OK at that width. +- **Set height below 700px**: We recommend keeping this height for the rendered code example width for maximum onscreen legibility. + +### Color in the rendered code example + +Use keywords for primary and other "basic" colors, for example: + +```css example-good +color: black; +color: white; +color: red; +``` + +Use `rgb()` for more complex colors (including semi-transparent ones): + +```css example-good +color: rgb(0 0 0 / 50%); +color: rgb(248 242 230); +``` + +For hex colors, use the short form where relevant: + +```css example-good +color: #058ed9; +color: #a39a92c1; +color: #ff0; +color: #fbfa; +``` + +As opposed to: + +```css-nolint example-bad +color: #ffff00; +color: #ffbbffaa; +``` + +### Highlight examples as good or bad + +You'll notice on this page that the code blocks that represent good practices to follow are rendered with a green check mark in the right corner, and the code blocks that demonstrate bad practices are rendered with a white cross in a red circle. + +You can follow the same style while writing code examples. You don't need to use this style everywhere — only in places where you want to specifically call out good and bad usage in code examples. + +A code block is written in markdown using "code fences" to demarcate the code block, followed by the language in the info string. For example: + +````md +```js +function myFunc() { + console.log("Hello!"); +} +``` +```` + +To represent the code block as a good or bad example, add `example-good` or `example-bad` after the language string, like so: + +````md +```html example-good +<p>Good example</p> +``` + +```html example-bad +<p>Bad example</p> +``` +```` + +These will be rendered as: + +```html example-good +<p>Good example</p> +``` + +```html example-bad +<p>Bad example</p> +``` + +## Guidelines for using placeholder text + +Use the placeholder lorem-ipsum text generated from [lipsum.com](https://www.lipsum.com/) or the [Lorem ipsum](https://marketplace.visualstudio.com/items?itemName=Tyriar.lorem-ipsum) VS Code plugin. The standard lorem-ipsum text is included in our spell-checker configuration, so it will not be reported as typos in IDEs or in tests during code review. Using a consistent placeholder text makes example code easier to review, especially when it appears repeatedly. It also helps keep examples clearly for illustration purposes and avoids distracting readers with irrelevant content. diff --git a/files/en-us/mdn/writing_guidelines/code_style_guide/javascript/index.md b/files/en-us/mdn/writing_guidelines/code_style_guide/javascript/index.md new file mode 100644 index 000000000000000..cb6f468f069d8ff --- /dev/null +++ b/files/en-us/mdn/writing_guidelines/code_style_guide/javascript/index.md @@ -0,0 +1,882 @@ +--- +title: Guidelines for writing JavaScript code examples +short-title: JavaScript examples +slug: MDN/Writing_guidelines/Code_style_guide/JavaScript +page-type: mdn-writing-guide +sidebar: mdnsidebar +--- + +The following guidelines cover writing JavaScript example code for MDN Web Docs. This article is a list of rules for writing concise examples that will be understandable by as many people as possible. + +## General guidelines for JavaScript code examples + +This section explains the general guidelines to keep in mind while writing JavaScript code examples. The later sections will cover more specific details. + +### Choosing a format + +Opinions on correct indentation, whitespace, and line lengths have always been controversial. Discussions on these topics are a distraction from creating and maintaining content. + +On MDN Web Docs, we use [Prettier](https://prettier.io/) as a code formatter to keep the code style consistent (and to avoid off-topic discussions). You can consult our [configuration file](https://github.com/mdn/content/blob/main/.prettierrc.json) to learn about the current rules, and read the [Prettier documentation](https://prettier.io/docs/index.html). + +Prettier formats all the code and keeps the style consistent. Nevertheless, there are a few additional rules that you need to follow. + +### Using modern JavaScript features + +You can use new features once every major browser — Chrome, Edge, Firefox, and Safari — supports them. + +## Arrays + +### Array creation + +For creating arrays, use literals and not constructors. + +Create arrays like this: + +```js example-good +const visitedCities = []; +``` + +Don't do this while creating arrays: + +```js example-bad +const visitedCities = new Array(length); +``` + +### Item addition + +When adding items to an array, use [`push()`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/push) and not direct assignment. Consider the following array: + +```js +const pets = []; +``` + +Add items to the array like this: + +```js example-good +pets.push("cat"); +``` + +Don't add items to the array like this: + +```js example-bad +pets[pets.length] = "cat"; +``` + +## Asynchronous methods + +Writing asynchronous code improves performance and should be used when possible. In particular, you can use: + +- [Promises](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise) +- [`async`](/en-US/docs/Web/JavaScript/Reference/Statements/async_function)/[`await`](/en-US/docs/Web/JavaScript/Reference/Operators/await) + +When both techniques are possible, we prefer using the simpler `async`/`await` syntax. Unfortunately, you can't use `await` at the top level unless you are in an ECMAScript module. CommonJS modules used by Node.js are not ES modules. If your example is intended to be used everywhere, avoid top-level `await`. + +## Comments + +Comments are critical to writing good code examples. They clarify the intent of the code and help developers understand it. Pay special attention to them. + +- If the purpose or logic of the code isn't obvious, add a comment with your intention, as shown below: + + ```js example-good + let total = 0; + + // Calculate the sum of the four first elements of arr + for (let i = 0; i < 4; i++) { + total += arr[i]; + } + ``` + + On the other hand, restating the code in prose is not a good use of comments: + + ```js example-bad + let total = 0; + + // For loop from 1 to 4 + for (let i = 0; i < 4; i++) { + // Add value to the total + total += arr[i]; + } + ``` + +- Comments are also not necessary when functions have explicit names that describe what they're doing. Write: + + ```js example-good + closeConnection(); + ``` + + Don't write: + + ```js example-bad + closeConnection(); // Closing the connection + ``` + +### Use single-line comments + +Single-line comments are marked with `//`, as opposed to block comments enclosed between `/* … */`. + +In general, use single-line comments to comment code. Writers must mark each line of the comment with `//`, so that it's easier to notice commented-out code visually. In addition, this convention allows to comment out sections of code using `/* … */` while debugging. + +- Leave a space between the slashes and the comment. Start with a capital letter, like a sentence, but don't end the comment with a period. + + ```js example-good + // This is a well-written single-line comment + ``` + +- If a comment doesn't start immediately after a new indentation level, add an empty line and then add the comment. It will create a code block, making it obvious what the comment refers to. Also, put your comments on separate lines preceding the code they are referring to. This is shown in the following example: + + ```js example-good + function checkout(goodsPrice, shipmentPrice, taxes) { + // Calculate the total price + const total = goodsPrice + shipmentPrice + taxes; + + // Create and append a new paragraph to the document + const para = document.createElement("p"); + para.textContent = `Total price is ${total}`; + document.body.appendChild(para); + } + ``` + +### Output of logs + +- In code intended to run in a production environment, you rarely need to comment when you log some data. In code examples, we often use `console.log()`, `console.error()`, or similar functions to output important values. To help the reader understand what will happen without running the code, you can put a comment _after_ the function with the log that will be produced. Write: + + ```js example-good + function exampleFunc(fruitBasket) { + console.log(fruitBasket); // ['banana', 'mango', 'orange'] + } + ``` + + Don't write: + + ```js example-bad + function exampleFunc(fruitBasket) { + // Logs: ['banana', 'mango', 'orange'] + console.log(fruitBasket); + } + ``` + +- In case the line becomes too long, put the comment _after_ the function, like this: + + ```js example-good + function exampleFunc(fruitBasket) { + console.log(fruitBasket); + // ['banana', 'mango', 'orange', 'apple', 'pear', 'durian', 'lemon'] + } + ``` + +### Multi-line comments + +Short comments are usually better, so try to keep them in one line of 60–80 characters. If this is not possible, use `//` at the beginning of each line: + +```js example-good +// This is an example of a multi-line comment. +// The imaginary function that follows has some unusual +// limitations that I want to call out. +// Limitation 1 +// Limitation 2 +``` + +Don't use `/* … */`: + +```js example-bad +/* This is an example of a multi-line comment. + The imaginary function that follows has some unusual + limitations that I want to call out. + Limitation 1 + Limitation 2 */ +``` + +### Use comments to mark ellipsis + +Skipping redundant code using ellipses (…) is necessary to keep examples short. Still, writers should do it thoughtfully as developers frequently copy & paste examples into their code, and all of our code samples should be valid JavaScript. + +In JavaScript, you should put the ellipses (`…`) in a comment. When possible, indicate what action somebody reusing this snippet is expected to add. + +Using a comment for the ellipses (…) is more explicit, preventing errors when a developer copies and pastes a sample code. Write: + +```js example-good +function exampleFunc() { + // Add your code here + // … +} +``` + +Don't use ellipses (…) like this: + +```js example-bad +function exampleFunc() { + … +} +``` + +### Comment out parameters + +When writing code, you usually omit parameters you don't need. But in some code examples, you want to demonstrate that you didn't use some possible parameters. + +To do so, use `/* … */` in the parameter list. This is an exception to the rule to only use single-line comments (`//`). + +```js +array.forEach((value /* , index, array */) => { + // … +}); +``` + +## Functions + +### Function names + +For function names, use {{Glossary("camel_case", "camel case")}}, starting with a lowercase character. Use concise, human-readable, and semantic names where appropriate. + +The following is a correct example of a function name: + +```js example-good +function sayHello() { + console.log("Hello!"); +} +``` + +Don't use function names like these: + +```js example-bad +function SayHello() { + console.log("Hello!"); +} + +function doIt() { + console.log("Hello!"); +} +``` + +### Function declarations + +- Where possible, use the function declaration over function expressions to define functions. + + Here is the recommended way to declare a function: + + ```js example-good + function sum(a, b) { + return a + b; + } + ``` + + This is not a good way to define a function: + + ```js example-bad + let sum = function (a, b) { + return a + b; + }; + ``` + +- When using anonymous functions as a callback (a function passed to another method invocation), if you do not need to access `this`, use an arrow function to make the code shorter and cleaner. + + Here is the recommended way: + + ```js example-good + const array1 = [1, 2, 3, 4]; + const sum = array1.reduce((a, b) => a + b); + ``` + + Instead of this: + + ```js example-bad + const array1 = [1, 2, 3, 4]; + const sum = array1.reduce(function (a, b) { + return a + b; + }); + ``` + +- Consider avoiding using arrow function to assign a function to an identifier. In particular, don't use arrow functions for methods. Use function declarations with the keyword `function`: + + ```js example-good + function x() { + // … + } + ``` + + Don't do: + + ```js example-bad + const x = () => { + // … + }; + ``` + +- When using arrow functions, use [implicit return](/en-US/docs/Web/JavaScript/Reference/Functions/Arrow_functions#function_body) (also known as _expression body_) when possible: + + ```js example-good + arr.map((e) => e.id); + ``` + + And not: + + ```js example-bad + arr.map((e) => { + return e.id; + }); + ``` + +## Loops and conditional statements + +### Loop initialization + +When [loops](/en-US/docs/Learn_web_development/Core/Scripting/Loops) are required, choose the appropriate one from [`for(;;)`](/en-US/docs/Web/JavaScript/Reference/Statements/for), [`for...of`](/en-US/docs/Web/JavaScript/Reference/Statements/for...of), [`while`](/en-US/docs/Web/JavaScript/Reference/Statements/while), etc. + +- When iterating through all collection elements, avoid using the classical `for (;;)` loop; prefer `for...of` or `forEach()`. Note that if you are using a collection that is not an `Array`, you have to check that `for...of` is actually supported (it requires the variable to be iterable), or that the `forEach()` method is actually present. + + Use `for...of`: + + ```js example-good + const dogs = ["Rex", "Lassie"]; + for (const dog of dogs) { + console.log(dog); + } + ``` + + Or `forEach()`: + + ```js example-good + const dogs = ["Rex", "Lassie"]; + dogs.forEach((dog) => { + console.log(dog); + }); + ``` + + Do not use `for (;;)` — not only do you have to add an extra index, `i`, but you also have to track the length of the array. This can be error-prone for beginners. + + ```js example-bad + const dogs = ["Rex", "Lassie"]; + for (let i = 0; i < dogs.length; i++) { + console.log(dogs[i]); + } + ``` + +- Make sure that you define the initializer properly by using the `const` keyword for `for...of` or `let` for the other loops. Don't omit it. These are correct examples: + + ```js example-good + const cats = ["Athena", "Luna"]; + for (const cat of cats) { + console.log(cat); + } + + for (let i = 0; i < 4; i++) { + result += arr[i]; + } + ``` + + The example below does not follow the recommended guidelines for the initialization (it implicitly creates a global variable and will fail in strict mode): + + ```js example-bad + const cats = ["Athena", "Luna"]; + for (i of cats) { + console.log(i); + } + ``` + +- When you need to access both the value and the index, you can use `.forEach()` instead of `for (;;)`. Write: + + ```js example-good + const gerbils = ["Zoé", "Chloé"]; + gerbils.forEach((gerbil, i) => { + console.log(`Gerbil #${i}: ${gerbil}`); + }); + ``` + + Do not write: + + ```js example-bad + const gerbils = ["Zoé", "Chloé"]; + for (let i = 0; i < gerbils.length; i++) { + console.log(`Gerbil #${i}: ${gerbils[i]}`); + } + ``` + +> [!WARNING] +> Never use `for...in` with arrays and strings. + +> [!NOTE] +> Consider not using a `for` loop at all. If you are using an [`Array`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array) (or a [`String`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/String) for some operations), consider using more semantic iteration methods instead, like [`map()`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/map), [`every()`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/every), [`findIndex()`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/findIndex), [`find()`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/find), [`includes()`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/includes), and many more. + +### Control statements + +There is one notable case to keep in mind for the `if...else` control statements. If the `if` statement ends with a `return`, do not add an `else` statement. + +Continue right after the `if` statement. Write: + +```js example-good +if (test) { + // Perform something if test is true + // … + return; +} + +// Perform something if test is false +// … +``` + +Do not write: + +```js example-bad +if (test) { + // Perform something if test is true + // … + return; +} else { + // Perform something if test is false + // … +} +``` + +### Use braces with control flow statements and loops + +While control flow statements like `if`, `for`, and `while` don't require the use of braces when the content is made of one single statement, you should always use braces. Write: + +```js example-good +for (const car of storedCars) { + car.paint("red"); +} +``` + +Don't write: + +```js example-bad +for (const car of storedCars) car.paint("red"); +``` + +This prevent forgetting to add the braces when adding more statements. + +### Switch statements + +Switch statements can be a little tricky. + +- Don't add a `break` statement after a `return` statement in a specific case. Instead, write `return` statements like this: + + ```js example-good + switch (species) { + case "chicken": + return farm.shed; + case "horse": + return corral.entry; + default: + return ""; + } + ``` + + If you add a `break` statement, it will be unreachable. Do not write: + + ```js example-bad + switch (species) { + case "chicken": + return farm.shed; + break; + case "horse": + return corral.entry; + break; + default: + return ""; + } + ``` + +- Use `default` as the last case, and don't end it with a `break` statement. If you need to do it differently, add a comment explaining why. + +- Remember that when you declare a local variable for a case, you need to use braces to define a scope: + + ```js + switch (fruits) { + case "Orange": { + const slice = fruit.slice(); + eat(slice); + break; + } + case "Apple": { + const core = fruit.extractCore(); + recycle(core); + break; + } + } + ``` + +### Error handling + +- If certain states of your program throw uncaught errors, they will halt execution and potentially reduce the usefulness of the example. You should, therefore, catch errors using a [`try...catch`](/en-US/docs/Web/JavaScript/Reference/Statements/try...catch) block, as shown below: + + ```js example-good + try { + console.log(getResult()); + } catch (e) { + console.error(e); + } + ``` + +- When you don't need the parameter of the `catch` statement, omit it: + + ```js example-good + try { + console.log(getResult()); + } catch { + console.error("An error happened!"); + } + ``` + +> [!NOTE] +> Keep in mind that only _recoverable_ errors should be caught and handled. All non-recoverable errors should be let through and bubble up the call stack. + +## Objects + +### Object names + +- When defining a class, use _PascalCase_ (starting with a capital letter) for the class name and _camelCase_ (starting with a lowercase letter) for the object property and method names. + +- When defining an object instance, either a literal or via a constructor, use _camelCase_, starting with lower-case character, for the instance name. For example: + + ```js example-good + const hanSolo = new Person("Han Solo", 25, "he/him"); + + const luke = { + name: "Luke Skywalker", + age: 25, + pronouns: "he/him", + }; + ``` + +### Object creation + +For creating general objects (i.e., when classes are not involved), use literals and not constructors. + +For example, do this: + +```js example-good +const object = {}; +``` + +Don't create a general object like this: + +```js example-bad +const object = new Object(); +``` + +### Object classes + +- Use ES class syntax for objects, not old-style constructors. + + For example, this is the recommended way: + + ```js example-good + class Person { + constructor(name, age, pronouns) { + this.name = name; + this.age = age; + this.pronouns = pronouns; + } + + greeting() { + console.log(`Hi! I'm ${this.name}`); + } + } + ``` + +- Use `extends` for inheritance: + + ```js example-good + class Teacher extends Person { + // … + } + ``` + +### Methods + +To define methods, use the method definition syntax: + +```js example-good +const obj = { + foo() { + // … + }, + bar() { + // … + }, +}; +``` + +Instead of: + +```js example-bad +const obj = { + foo: function () { + // … + }, + bar: function () { + // … + }, +}; +``` + +### Object properties + +- The [`Object.prototype.hasOwnProperty()`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object/hasOwnProperty) method has been deprecated in favor of [`Object.hasOwn()`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object/hasOwn). +- When possible, use the shorthand avoiding the duplication of the property identifier. Write: + + ```js example-good + function createObject(name, age) { + return { name, age }; + } + ``` + + Don't write: + + ```js example-bad + function createObject(name, age) { + return { name: name, age: age }; + } + ``` + +## Operators + +This section lists our recommendations of which operators to use and when. + +### Conditional operators + +When you want to store to a variable a literal value depending on a condition, use a [conditional (ternary) operator](/en-US/docs/Web/JavaScript/Reference/Operators/Conditional_operator) instead of an `if...else` statement. This rule also applies when returning a value. Write: + +```js example-good +const x = condition ? 1 : 2; +``` + +Do not write: + +```js example-bad +let x; +if (condition) { + x = 1; +} else { + x = 2; +} +``` + +The conditional operator is helpful when creating strings to log information. In such cases, using a regular `if...else` statement leads to long blocks of code for a side operation like logging, obfuscating the central point of the example. + +### Strict equality operator + +Prefer the [strict equality](/en-US/docs/Web/JavaScript/Reference/Operators/Strict_equality) (triple equals) and inequality operators over the loose equality (double equals) and inequality operators. + +Use the strict equality and inequality operators like this: + +```js example-good +name === "Shilpa"; +age !== 25; +``` + +Don't use the loose equality and inequality operators, as shown below: + +```js example-bad +name == "Shilpa"; +age != 25; +``` + +If you need to use `==` or `!=`, remember that `== null` is the only acceptable case. As TypeScript will fail on all other cases, we don't want to have them in our example code. Consider adding a comment to explain why you need it. + +### Shortcuts for boolean tests + +Prefer shortcuts for boolean tests. For example, use `if (x)` and `if (!x)`, not `if (x === true)` and `if (x === false)`, unless different kinds of truthy or falsy values are handled differently. + +## Strings + +String literals can be enclosed within single quotes, as in `'A string'`, or within double quotes, as in `"A string"`. Don't worry about which one to use; Prettier keeps it consistent. + +### Template literals + +For inserting values into strings, use [template literals](/en-US/docs/Web/JavaScript/Reference/Template_literals). + +- Here is an example of the recommended way to use template literals. Their use prevents a lot of spacing errors. + + ```js example-good + const name = "Shilpa"; + console.log(`Hi! I'm ${name}!`); + ``` + + Don't concatenate strings like this: + + ```js example-bad + const name = "Shilpa"; + console.log("Hi! I'm" + name + "!"); // Hi! I'mShilpa! + ``` + +- Don't overuse template literals. If there are no substitutions, use a normal string literal instead. + +## Variables + +### Variable names + +Good variable names are essential to understanding code. + +<!-- cSpell:ignore acclmtr --> + +- Use short identifiers, and avoid non-common abbreviations. Good variable names are usually between 3 to 10-character long, but as a hint only. For example, `accelerometer` is more descriptive than abbreviating to `acclmtr` for the sake of character length. +- Try to use real-world relevant examples where each variable has clear semantics. Only fall back to placeholder names like `foo` and `bar` when the example is simple and contrived. +- Do not use the [Hungarian notation](https://en.wikipedia.org/wiki/Hungarian_notation) naming convention. Do not prefix the variable name with its type. For example, write `bought = car.buyer !== null` rather than `bBought = oCar.sBuyer != null` or `name = "John Doe"` instead of `sName = "John Doe"`. +- For collections, avoid adding the type such as list, array, queue in the name. Use the content name in the plural form. For example, for an array of cars, use `cars` and not `carArray` or `carList`. There may be exceptions, like when you want to show the abstract form of a feature without the context of a particular application. +- For primitive values, use _camelCase_, starting with a lowercase character. Do not use `_`. Use concise, human-readable, and semantic names where appropriate. For example, use `currencyName` rather than `currency_name`. +- Avoid using articles and possessives. For example, use `car` instead of `myCar` or `aCar`. There may be exceptions, like when describing a feature in general without a practical context. +- Use variable names as shown here: + + ```js example-good + const playerScore = 0; + const speed = distance / time; + ``` + + Don't name variables like this: + + ```js example-bad + const thisIsaveryLONGVariableThatRecordsPlayerscore345654 = 0; + const s = d / t; + ``` + +> [!NOTE] +> The only place where it's allowed not to use human-readable, semantic names is where a very commonly recognized convention exists, such as using `i` and `j` for loop iterators. + +### Variable declarations + +When declaring variables and constants, use the [`let`](/en-US/docs/Web/JavaScript/Reference/Statements/let) and [`const`](/en-US/docs/Web/JavaScript/Reference/Statements/const) keywords, not [`var`](/en-US/docs/Web/JavaScript/Reference/Statements/var). The following examples show what's recommended and what's not on MDN Web Docs: + +- If a variable will not be reassigned, prefer `const`, like so: + + ```js example-good + const name = "Shilpa"; + console.log(name); + ``` + +- If you'll change the value of a variable, use `let` as shown below: + + ```js example-good + let age = 40; + age++; + console.log("Happy birthday!"); + ``` + +- The example below uses `let` where it should be `const`. The code will work, but we want to avoid this usage in MDN Web Docs code examples. + + ```js example-bad + let name = "Shilpa"; + console.log(name); + ``` + +- The example below uses `const` for a variable that gets reassigned. The reassignment will throw an error. + + ```js example-bad + const age = 40; + age++; + console.log("Happy birthday!"); + ``` + +- The example below uses `var`, polluting the global scope: + + ```js example-bad + var age = 40; + var name = "Shilpa"; + ``` + +- Declare one variable per line, like so: + + ```js example-good + let var1; + let var2; + let var3 = "Apapou"; + let var4 = var3; + ``` + + Do not declare multiple variables in one line, separating them with commas or using chain declaration. Avoid declaring variables like this: + + ```js-nolint example-bad + let var1, var2; + let var3 = var4 = "Apapou"; // var4 is implicitly created as a global variable; fails in strict mode + ``` + +### Type coercion + +Avoid implicit type coercions. In particular, avoid `+val` to force a value to a number and `"" + val` to force it to a string. Use `Number()` and `String()`, without `new`, instead. Write: + +```js example-good +class Person { + #name; + #birthYear; + + constructor(name, year) { + this.#name = String(name); + this.#birthYear = Number(year); + } +} +``` + +Don't write: + +```js example-bad +class Person { + #name; + #birthYear; + + constructor(name, year) { + this.#name = "" + name; + this.#birthYear = +year; + } +} +``` + +## Web APIs to avoid + +In addition to these JavaScript language features, we recommend a few guidelines related to Web APIs to keep in mind. + +### Avoid browser prefixes + +If all major browsers (Chrome, Edge, Firefox, and Safari) support a feature, don't prefix the feature. Write: + +```js example-good +const context = new AudioContext(); +``` + +Avoid the added complexity of prefixes. Don't write: + +```js example-bad +const AudioContext = window.AudioContext || window.webkitAudioContext; +const context = new AudioContext(); +``` + +The same rule applies to CSS prefixes. + +### Avoid deprecated APIs + +When a method, a property, or a whole interface is deprecated, do not use it (outside its documentation). Instead, use the modern API. + +Here is a non-exhaustive list of Web APIs to avoid and what to replace them with: + +- Use `fetch()` instead of XHR (`XMLHttpRequest`). +- Use `AudioWorklet` instead of `ScriptProcessorNode`, in the Web Audio API. + +### Use safe and reliable APIs + +- Do not use {{DOMxRef("Element.innerHTML")}} to insert purely textual content into an element; use {{DOMxRef("Node.textContent")}} instead. The property `innerHTML` leads to security problems if a developer doesn't control the parameter. The more we as writers avoid using it, the fewer security flaws are created when a developer copies and pastes our code. + + The example below demonstrates the use of `textContent`. + + ```js example-good + const text = "Hello to all you good people"; + const para = document.createElement("p"); + para.textContent = text; + ``` + + Don't use `innerHTML` to insert _pure text_ into DOM nodes. + + ```js example-bad + const text = "Hello to all you good people"; + const para = document.createElement("p"); + para.innerHTML = text; + ``` + +- The `alert()` function is unreliable. It doesn't work in live examples on MDN Web Docs that are inside an {{HTMLElement("iframe")}}. Moreover, it is modal to the whole window, which is annoying. In static code examples, use `console.log()` or `console.error()`. In [live examples](/en-US/docs/MDN/Writing_guidelines/Page_structures/Live_samples), avoid `console.log()` and `console.error()` because they are not displayed. Use a dedicated UI element. + +### Use the appropriate log method + +- When logging a message, use `console.log()`. +- When logging an error, use `console.error()`. + +## See also + +[JavaScript language reference](/en-US/docs/Web/JavaScript/Reference) - browse through our JavaScript reference pages to check out some good, concise, meaningful JavaScript snippets. diff --git a/files/en-us/mdn/writing_guidelines/code_style_guide/shell/index.md b/files/en-us/mdn/writing_guidelines/code_style_guide/shell/index.md new file mode 100644 index 000000000000000..c1dd7faff5b2855 --- /dev/null +++ b/files/en-us/mdn/writing_guidelines/code_style_guide/shell/index.md @@ -0,0 +1,43 @@ +--- +title: Guidelines for writing shell prompt code examples +short-title: Shell script examples +slug: MDN/Writing_guidelines/Code_style_guide/Shell +page-type: mdn-writing-guide +sidebar: mdnsidebar +--- + +The following guidelines cover how to write Shell prompt code examples for MDN Web Docs. + +## What is a "shell" + +A shell is a program that waits for you to type in a command and then press the return key. To indicate which commands you should type, content on MDN Web Docs lists them in a code block, similar to code examples. + +Such a block looks like this: + +```bash example-good +# This may take a while... +git clone https://github.com/mdn/content +cd content +``` + +## General guidelines for shell prompt code examples + +### Choosing a format + +Opinions on correct indentation, whitespace, and line lengths have always been controversial. Discussions on these topics are a distraction from creating and maintaining content. + +On MDN Web Docs, we use [Prettier](https://prettier.io/) as a code formatter to keep the code style consistent (and to avoid off-topic discussions). You can consult our [configuration file](https://github.com/mdn/content/blob/main/.prettierrc.json) to learn about the current rules, and read the [Prettier documentation](https://prettier.io/docs/index.html). + +Prettier formats all the code and keeps the style consistent. Nevertheless, there are a few additional rules that you need to follow. + +### Writing shell code blocks + +When writing a shell code block: + +- Do not include a `$` or `>` at the beginning of a shell instruction. It confuses more than it helps and it is not useful when copying the instructions. +- Comments start with `#`. +- Choose "bash" to indicate the language in markdown. + +## See also + +[Django server-side development docs](/en-US/docs/Learn_web_development/Extensions/Server-side/Django) show good practice presentation of shell prompt commands. diff --git a/files/en-us/mdn/writing_guidelines/criteria_for_inclusion/index.md b/files/en-us/mdn/writing_guidelines/criteria_for_inclusion/index.md new file mode 100644 index 000000000000000..85ed008da7e78fa --- /dev/null +++ b/files/en-us/mdn/writing_guidelines/criteria_for_inclusion/index.md @@ -0,0 +1,181 @@ +--- +title: Criteria for inclusion on MDN Web Docs +short-title: Criteria for inclusion +slug: MDN/Writing_guidelines/Criteria_for_inclusion +page-type: mdn-writing-guide +sidebar: mdnsidebar +--- + +This article describes, in detail, criteria for content to be included on MDN Web Docs, the application process for including new documentation, and expectations and guidelines for a party applying. + +This is aimed at larger projects. To suggest a new page or article, please refer to the [Suggesting content](/en-US/docs/MDN/Writing_guidelines/What_we_write#suggesting_content) section on the "What we write" page. + +## Web standards technologies + +The remit of MDN Web Docs is to document web standards technologies that are in a specification published by a reliable standards body and are supported in at least one stable browser. These criteria signal enough interest, stability, and "intent to implement" by the web industry at large. Therefore, we think those technologies are a safe bet for us to spend our time and effort in documenting them. Any earlier than that, a web technology or a feature might be prone to getting cancelled due to lack of interest or might be so unstable that it might change significantly, which will needlessly involve a lot of rewriting (which we try to avoid where possible). + +## Non-web standards technologies + +Non-web standards technologies are technologies that do not follow our criteria summarized above. We would not normally consider them for documentation on MDN Web Docs. + +Our mission statement is _"to provide developers with the information they need to easily build projects on the open web"_. This suggests that we should consider documenting technologies that are useful to web developers, even if they are not open web standards, on the standards track, etc. + +If you want to consider a non-web standard technology for inclusion on MDN Web Docs, you should make sure that it matches the criteria below. + +## Criteria for inclusion on MDN Web Docs + +Technologies should fulfill the criteria described here for being considered to be documented on MDN Web Docs. + +### Be open and not proprietary + +At MDN Web Docs, we are supporters of open technologies. We don't support closed technology ecosystems that are controlled by a single entity, that are not open for contributions by any interested party, and that are not interoperable across multiple platforms and systems. We believe that technology works better for everyone when created out in the open. + +### Be web-exposed and be related to web technologies + +Our central remit is web standards technologies; there is no point starting to document technologies that do not relate to the web or hold any interest to web developers. + +### Show signs of interest and adoption + +We don't want to spend our time documenting a technology that has no signal of interest and adoption from the industry. It may just be that it is too early to start documenting the technology, and we could consider it to be documented on MDN Web Docs in the future. + +### Not show signs of being deprecated or superseded + +Related to the above point, we also don't want to spend our time documenting a technology that is late in its lifecycle and is already showing signs of decline in interest. + +### Not have an established documentation resource elsewhere + +There are many libraries and frameworks in existence, which are not web standards but are built on top of web technologies and are very popular in the web industry. We do not document any of these because, in general, they all have established documentation resources already. It would be foolish to compete with the official resource of a popular framework — to do so would be a waste of time and probably end up confusing developers trying to learn the technology. + +### Have a community willing to write and maintain the documentation + +The MDN Web Docs team concentrates on documenting the open web platform. If you want a technology in this area to be considered for documentation on MDN Web Docs, you'll need to have a community assembled that is willing to write the documentation and maintain it after completion. Our team is happy to provide guidance in such cases, including edits and feedback, but we don't have the resource for more than that. + +> [!NOTE] +> MDN Web Docs work is carried out on GitHub and 'in the open'. Your team should be versed in git & GitHub and be comfortable with working in open source. + +## Process for selecting the new technology + +If a technology looks like a good candidate for being documented on MDN Web Docs, you can start a discussion on the [GitHub community discussions](/en-US/docs/MDN/Community/Communication_channels#github_discussions) to propose and discuss the inclusion of this technology. This section describes what the proposal should include. + +### Submitting the proposal + +Technologies will be considered for inclusion on MDN Web Docs on a case-by-case basis. For consideration, you would need to submit a proposal titled "Proposal for documenting a new technology on MDN Web Docs". We would need the following information from you in the proposal: + +- The technology, its core purpose/use cases, and target developer audience. +- What kind of industry or community buzz is there is around the technology? + - Are a lot web developers using it? What is the industry adoption like? + - Do a lot of web developers want or need this information? + - What is the size of the target audience for this information? Supporting statistics would help if you have them. +- How does the technology relate to core web technology and web browsers? Useful details include: + - Does it use HTML and CSS but generally not output to the web? + - Is it supported in web browsers via a polyfill? +- What documentation or resources are already available that cover the technology? +- How much documentation would need to be added to MDN Web Docs? + - List the expected number of guides, tutorials, reference pages for elements/methods/attributes, etc. + - Provide a high-level table of contents. + - Mention the kind of "advanced" features you think you might need for this resource, beyond the basic documentation pages. Are you expecting to include embedded videos, interactive code samples, etc.? +- Who will be writing the documentation? Who are they and why are they suited for the job? +- How will the documentation be maintained? + +You don't need to provide us with hundreds of pages of detail at this stage (in fact, we'd prefer it if you didn't). A couple of paragraphs on each of the above points is more than adequate. + +> [!NOTE] +> MDN Web Docs is primarily an English site (en-US). The primary language for your project should be in US English. + +### Awaiting a response + +We will consider the technology and the information you submit in the proposal and respond with one of the following answers: + +- **No**: We don't think this meets the criteria for being documented on MDN Web Docs. +- **Maybe**: We are not sure if it is suitable for documenting on MDN Web Docs and would like to ask some further questions. +- **Yes**: We think it is appropriate for including it on MDN Web Docs. + +If the technology is a good candidate, the team will assist you in getting started with the documentation. + +## Project guidelines for documenting the new technology + +If your chosen technology is accepted for documentation on MDN Web Docs, the next step is to get started. + +To ensure that your project for documenting the new technology on MDN Web Docs is successful, we'll need you to have the following in place: + +- A dedicated team +- A project plan and roadmap +- Writing guidelines and standards +- An intuitive documentation structure +- A maintenance plan + +### Dedicated team + +Make sure you have a dedicated team in place that will be there to both write the initial documentation as well as maintain it in future with the required updates. + +Have a think about how much work there is and how many people you might need for that. + +- If it is a large project, you might benefit from having a few writers, a technical reviewer to check that the work is technically accurate, a copy editor to clean up the language, someone to write code examples, etc. +- On a smaller project, you might have one or two people taking on multiple roles. However you want to build up the team is fine as long as it works for you. + +A member of the MDN Web Docs team will be assigned to your project to provide guidance on the MDN Web Docs side of things. + +You should assign one (or two) team leads who can liaise with the MDN Web Docs team member. + +The MDN Web Docs representative will help get the required permissions to everyone on your team to work in the [MDN organization on GitHub](https://github.com/mdn). + +### Project plan and roadmap + +Create a plan for the project — tasks, estimate completion dates, and milestones you would want to track to ensure you're making steady progress. + +If the project is large, you should consider assigning one of your team members as the project manager. You should also consider writing a subproject plan for an initial release that encompasses the minimum set of documentation that is useful to publish (a _minimum viable product_); you can follow it up with further additions later. + +If the documentation project is small, you would still need to keep a record of what has been done and what hasn't, what stage each part of the documentation is at (e.g., not started, in progress, draft written, reviewed, done), and who is working on what. + +### Writing guidelines and standards + +These [guidelines](/en-US/docs/MDN/Writing_guidelines) state how we expect documents to be written for MDN Web Docs. + +If you have additional guidelines for the documents you are writing, we expect this guide to be added to and kept up to date. + +In terms of standards, you are expected to maintain a reasonable level of writing quality for your documentation to stay on MDN Web Docs. Your MDN Web Docs representative will work with you to make you clear on what is expected. + +### Intuitive documentation structure + +If you went through the proposal submission process, then you should already have a rough outline of what you are going to write for this technology. At this point, you should refine that into a site structure plan: think about what the document hierarchy will be and where everything will fit and link together. + +Each project is different, but we recommend the following directory tree: + +```plain +├── Guides +│ ├── guide_one +│ ├── guide_two +│ └── index.md +├── index.md +├── Reference +│ ├── Elements +│ ├── Methods +│ ├── Others ? +│ └── index.md +└── Tutorials + ├── tutorial_one + ├── tutorial_two + └── index.md +``` + +Each page type that you will use in your project should have a page template for others to copy the structure from. You should decide on these early on. + +Please refer to our section on [page types](/en-US/docs/MDN/Writing_guidelines/Page_structures/Page_types). If additions need to be made, please liaise with your MDN Web Docs representative. + +### Maintenance plan + +The documentation for this technology will need to be maintained to remain on MDN Web Docs: + +- The content and files for MDN Web Docs are stored on GitHub. When others make changes to the documentation for your technology, a member from your team needs to review those changes to make sure the content is still good. You can track the open pull requests (PRs) via GitHub's notification feature. +- When changes occur to the technology that require documentation to be updated, your team needs to make updates as appropriate, maintaining the same standards as the original documentation. + +If positive changes are not observed over a period of six months and the documentation appears to be in any of the following states: + +- Stale or unmaintained +- Stalled without being finished +- Low quality +- Becoming obsolete + +Then the documentation for this technology will be considered dead. After a discussion between your team and the MDN Web Docs team representative, the documentation will be removed. + +We hope you understand that we need to be strict on such matters — we can't let the site fill up with bad quality, incomplete, or obsolete documentation. diff --git a/files/en-us/mdn/writing_guidelines/experimental_deprecated_obsolete/index.md b/files/en-us/mdn/writing_guidelines/experimental_deprecated_obsolete/index.md index 5c5fc6a01c91d50..43eeaaad1c3a8ef 100644 --- a/files/en-us/mdn/writing_guidelines/experimental_deprecated_obsolete/index.md +++ b/files/en-us/mdn/writing_guidelines/experimental_deprecated_obsolete/index.md @@ -100,11 +100,11 @@ When in doubt, feel free to ask for advice on the [MDN Web Docs chat rooms](/en- Sometimes, but rarely, there might be a conflict between different specification versions (usually W3C versus WHATWG). For example, one version might have a feature listed as deprecated, while the other doesn't. In such cases, consider what the reality is, that is, consider what browsers are actually doing, and write an "important" note to summarize that latest status. -For example, as of Jan 2019, the [`inputmode`](/en-US/docs/Web/HTML/Global_attributes/inputmode) global attribute has a conflict, which was summarized like so: <!--this warning example for spec conflict does not exist anymore on that page. couldn't find any other examples as well --> +For example, as of Jan 2019, the [`inputmode`](/en-US/docs/Web/HTML/Reference/Global_attributes/inputmode) global attribute has a conflict, which was summarized like so: <!--this warning example for spec conflict does not exist anymore on that page. couldn't find any other examples as well --> > [!WARNING] > Specification conflict: The WHATWG specification lists [`inputmode`](https://html.spec.whatwg.org/multipage/interaction.html#attr-inputmode) and modern browsers are working towards supporting it. -> The [W3C HTML 5.2 spec](https://html.spec.whatwg.org/multipage/index.html#contents), however, no longer lists it (i.e. marks it as obsolete). +> The [W3C HTML 5.2 spec](https://html.spec.whatwg.org/multipage/index.html#contents), however, no longer lists it (i.e., marks it as obsolete). > You should consider the WHATWG definition as correct, until a consensus is reached. ## See also diff --git a/files/en-us/mdn/writing_guidelines/howto/creating_moving_deleting/index.md b/files/en-us/mdn/writing_guidelines/howto/creating_moving_deleting/index.md index 5fb738cfbf0b3fe..303b30a9093a48f 100644 --- a/files/en-us/mdn/writing_guidelines/howto/creating_moving_deleting/index.md +++ b/files/en-us/mdn/writing_guidelines/howto/creating_moving_deleting/index.md @@ -56,8 +56,8 @@ yarn content move <from-slug> <to-slug> [locale] ``` You just have to specify the slug of the existing document that you'd like -to move (e.g., `Web/HTTP/Authentication`), as well as the slug of its new -location (e.g., `Web/HTTP/Auth`), optionally followed by the locale of the +to move (e.g., `Web/HTTP/Guides/Authentication`), as well as the slug of its new +location (e.g., `Web/HTTP/Guides/Auth`), optionally followed by the locale of the existing document (defaults to `en-US`). If the existing document that you'd like to move has child documents (i.e., @@ -65,7 +65,7 @@ it represents a document tree), the `yarn content move` command will move the entire tree. For example, let's say you want to move the entire -`/en-US/Web/HTTP/Authentication` tree to `/en-US/Web/HTTP/Auth`, you'd perform the following steps: +`/en-US/Web/HTTP/Guides/Authentication` tree to `/en-US/Web/HTTP/Guides/Auth`, you'd perform the following steps: 1. You'll start a fresh branch to work in. @@ -82,7 +82,7 @@ For example, let's say you want to move the entire 2. Perform the move (which will delete and modify existing files as well as create new files). ```bash - yarn content move Web/HTTP/Authentication Web/HTTP/Auth + yarn content move Web/HTTP/Guides/Authentication Web/HTTP/Guides/Auth ``` 3. Once files are moved we need to update references to those files in the other content files as well. Use following command to update all the references automatically in one go: @@ -95,7 +95,7 @@ For example, let's say you want to move the entire ```bash git add . - git commit -m "Move Web/HTTP/Authentication to Web/HTTP/Auth" + git commit -m "Move Web/HTTP/Guides/Authentication to Web/HTTP/Guides/Auth" git push -u origin my-move ``` @@ -119,7 +119,7 @@ yarn content delete <document-slug> [locale] > You need to use the `yarn content delete` command to delete pages from MDN Web Docs. Don't just delete their directories from the repo. The `yarn content delete` command also handles other necessary changes such as updating the `_wikihistory.json` file. You just have to specify the slug of the existing document that you'd like -to delete (e.g., `Web/HTTP/Authentication`), optionally followed by the locale +to delete (e.g., `Web/HTTP/Guides/Authentication`), optionally followed by the locale of the existing document (defaults to `en-US`). If the existing document that you'd like to delete has child documents (i.e., it represents a @@ -127,7 +127,7 @@ document tree), you must also specify the `-r, --recursive` option, otherwise the command will fail. For example, if you want to delete the -entire `/en-US/Web/HTTP/Authentication` tree, you'd perform the following steps: +entire `/en-US/Web/HTTP/Guides/Authentication` tree, you'd perform the following steps: 1. You'll start a fresh branch to work in. @@ -144,7 +144,7 @@ entire `/en-US/Web/HTTP/Authentication` tree, you'd perform the following steps: 2. Perform the delete. ```bash - yarn content delete Web/HTTP/Authentication --recursive + yarn content delete Web/HTTP/Guides/Authentication --recursive ``` 3. Add a redirect. The target page can be an external URL or another page on MDN Web Docs. diff --git a/files/en-us/mdn/writing_guidelines/howto/document_an_http_header/index.md b/files/en-us/mdn/writing_guidelines/howto/document_an_http_header/index.md index 59c9082b517e48e..9ddd446bbace579 100644 --- a/files/en-us/mdn/writing_guidelines/howto/document_an_http_header/index.md +++ b/files/en-us/mdn/writing_guidelines/howto/document_an_http_header/index.md @@ -6,26 +6,26 @@ page-type: mdn-writing-guide sidebar: mdnsidebar --- -The [HTTP headers reference](/en-US/docs/Web/HTTP/Headers) documents the header section of request and response messages in the Hypertext Transfer Protocol ([HTTP](/en-US/docs/Web/HTTP)). +The [HTTP headers reference](/en-US/docs/Web/HTTP/Reference/Headers) documents the header section of request and response messages in the Hypertext Transfer Protocol ([HTTP](/en-US/docs/Web/HTTP)). This article explains how to create a new reference page for an HTTP header. ## Step 1 – Determine the HTTP header to document - There are many HTTP headers defined in various IETF standards. - IANA maintains a [registry of HTTP header fields](https://www.iana.org/assignments/http-fields/http-fields.xhtml) and Wikipedia lists the [known header fields](https://en.wikipedia.org/wiki/List_of_HTTP_header_fields), but not all are relevant to web developers or are part of an official standard. -- If there are any **red links** on the current [HTTP headers reference overview page](/en-US/docs/Web/HTTP/Headers), these headers are a good choice to document. +- If there are any **red links** on the current [HTTP headers reference overview page](/en-US/docs/Web/HTTP/Reference/Headers), these headers are a good choice to document. - If in doubt, [ask the MDN Web Docs team](/en-US/docs/MDN/Community/Communication_channels) whether or not it makes sense to write about the header you have chosen. ## Step 2 – Check the existing HTTP header pages -- Existing HTTP headers are documented [here](/en-US/docs/Web/HTTP/Headers). +- Existing HTTP headers are documented [in the HTTP reference](/en-US/docs/Web/HTTP/Reference/Headers). - There are different header categories: {{Glossary("Request header")}}, {{Glossary("Response header")}}, and {{Glossary("Representation header")}}. - Find the category of the header you are about to document (note that some headers can be both request and response headers, depending on the context). - Go to an existing header reference page that has the same category. ## Step 3 – Create the HTTP header page -- All header pages live under this tree: [`files/en-us/web/http/headers`](https://github.com/mdn/content/tree/main/files/en-us/web/http/headers) +- All header pages live under this tree: [`files/en-us/web/http/reference/headers`](https://github.com/mdn/content/tree/main/files/en-us/web/http/reference/headers) - To create a new page, see the instructions in our [how to create a page](/en-US/docs/MDN/Writing_guidelines/Howto/Creating_moving_deleting) guide. ## Step 4 – Write the content @@ -49,7 +49,7 @@ This article explains how to create a new reference page for an HTTP header. ## Step 6 – Update the HTTP headers list -Make sure your header is listed in an appropriate category on the [HTTP headers reference overview page](/en-US/docs/Web/HTTP/Headers). +Make sure your header is listed in an appropriate category on the [HTTP headers reference overview page](/en-US/docs/Web/HTTP/Reference/Headers). ## Step 7 – Get the content reviewed diff --git a/files/en-us/mdn/writing_guidelines/howto/json_structured_data/index.md b/files/en-us/mdn/writing_guidelines/howto/json_structured_data/index.md index 2f20a07279872f6..b7b7f83931e6710 100644 --- a/files/en-us/mdn/writing_guidelines/howto/json_structured_data/index.md +++ b/files/en-us/mdn/writing_guidelines/howto/json_structured_data/index.md @@ -83,12 +83,10 @@ There are two other keys, `"dictionaries"` and `"callbacks"`, operating on the s ### Update process for GroupData -This file should be updated in the same PR where changes affecting the sidebar happens. That way, the sidebar is always up-to-date. Reviewers shouldn't merge PRs that don't adopt it. +This file, located at [`files/jsondata/GroupData.json`](https://github.com/mdn/content/blob/main/files/jsondata/GroupData.json), should be updated in the same PR where changes affecting the sidebar happens. That way, the sidebar is always up-to-date. Reviewers shouldn't merge PRs that don't adopt it. To test your changes, check that the sidebar in the files in your PR displays all entries correctly. -The `GroupData.json` file is located [here](https://github.com/mdn/content/blob/main/files/jsondata/GroupData.json) on GitHub. - ## InterfaceData: recording interface inheritance > [!NOTE] @@ -116,17 +114,15 @@ The value of `"Name_of_the_parent_interface"` is not a list but a single entry, ### Update process for InterfaceData -The same PR adding a new interface that inherits from another one must update this file. Reviewers shouldn't merge PRs that don't do so. +The same PR adding a new interface that inherits from another one must update this file, located at [`files/jsondata/InterfaceData.json`](https://github.com/mdn/content/blob/main/files/jsondata/InterfaceData.json). Reviewers shouldn't merge PRs that don't do so. To test your changes, check that the sidebars of each interface you edited in your PR display inheritance correctly. -The `InterfaceData.json` file is located [here](https://github.com/mdn/content/blob/main/files/jsondata/InterfaceData.json) on GitHub. - ## SpecData: Specification information > [!WARNING] -> The `SpecData.json` file is no longer maintained. Canonical specification information is stored at w3c/browser-spec and in the `spec_url` key of features at mdn/browser-compat-data. - -The `\{{SpecName}}` and `\{{Spec2}}` macros that we are removing use the `SpecData.json` file. We do not accept any further contributions to the `SpecData.json` file; instead, either try to insert a specification table, using the `\{{Specifications}}` macro, or try to hardcode the (good) link to the specification. Note that most of the time, mentioning or linking to a specification outside the _Specifications_ section is a sign of something not appropriately documented on MDN. +> The [`SpecData.json`](https://github.com/mdn/content/blob/main/files/jsondata/SpecData.json) file is no longer maintained. +> Canonical specification information is stored at [w3c/browser-specs](https://github.com/w3c/browser-specs) and in the `spec_url` key of features defined at [mdn/browser-compat-data](https://github.com/mdn/browser-compat-data). -The `SpecData.json` file is located [here](https://github.com/mdn/content/blob/main/files/jsondata/SpecData.json) on GitHub. +We do not accept any further contributions to the `SpecData.json` file; instead, insert a specification table using the `\{{Specifications}}` macro, or link to the specification in prose. +Note that most of the time, mentioning or linking to a specification outside the _Specifications_ section is a sign of something not appropriately documented on MDN. diff --git a/files/en-us/mdn/writing_guidelines/howto/markdown_in_mdn/index.md b/files/en-us/mdn/writing_guidelines/howto/markdown_in_mdn/index.md index 721fd5febc863e8..ac5883ad00317ac 100644 --- a/files/en-us/mdn/writing_guidelines/howto/markdown_in_mdn/index.md +++ b/files/en-us/mdn/writing_guidelines/howto/markdown_in_mdn/index.md @@ -6,7 +6,8 @@ page-type: mdn-writing-guide sidebar: mdnsidebar --- -This page describes how we use Markdown to write documentation on MDN Web Docs. We have chosen GitHub-Flavored Markdown (GFM) as a baseline, and added some extensions to support some of the things we need to do on MDN that aren't readily supported in GFM. +This page describes how we use Markdown to write documentation on MDN Web Docs. +We have chosen GitHub-Flavored Markdown (GFM) as a baseline and added extensions to support the things we need on MDN. ## Baseline: GitHub-Flavored Markdown @@ -20,7 +21,6 @@ The GFM specification defines two basic types of links: - [reference links](https://github.github.com/gfm/#reference-link), in which the destination is defined elsewhere in the document. On MDN we allow only inline links. - This is the correct way to write GFM links on MDN: ```md example-good @@ -37,19 +37,7 @@ This is an incorrect way to write links on MDN: ## Example code blocks -In GFM and CommonMark, authors can use "code fences" to demarcate `<pre>` blocks. The opening code fence may be followed by some text that is called the "info string". The specification states the following: - -> The first word of the info string is typically used to specify the language of the code sample, and rendered in the class attribute of the code tag. - -It's permissible for the info string to contain multiple words, like: - -````md -```fee fi fo fum -// some example code -``` -```` - -On MDN, writers will use code fences for example code blocks. They must specify the language of the code sample using the first word of the info string, and this will be used to provide syntax highlighting for the block. The following words are supported: +In GFM and CommonMark, authors can use "code fences" to demarcate `<pre>` blocks. The opening code fence may be followed by some text that is called the "info string". The language of the code sample must be specified using the first word of the info string, and this will be used to provide syntax highlighting for the block. The following words are supported: - Programming Languages - JavaScript @@ -68,7 +56,7 @@ On MDN, writers will use code fences for example code blocks. They must specify - `rust` - Rust - `glsl` - GLSL (OpenGL Shaders) - `sql` - SeQueL commands - - `wasm` - WebAssembly + - `wat` - WebAssembly - `webidl` - Web Interface Definition Language - Styling - `css` - CSS @@ -97,7 +85,7 @@ On MDN, writers will use code fences for example code blocks. They must specify - Templates - `django` - Django templates - `svelte` - Svelte templates - - `handlebars` - Handlebars templates + - `hbs` - Handlebars templates - `pug` - [Pug templates](https://pugjs.org/api/getting-started.html) (which may be used by [Express](/en-US/docs/Learn_web_development/Extensions/Server-side/Express_Nodejs/Displaying_data/Template_primer)) - Other - `plain` - Plain text @@ -117,6 +105,9 @@ const greeting = "I will get JavaScript syntax highlighting"; If the highlighting that you wish to use is not listed above, you should markup the code block as `plain`. Additional languages may be requested in the process [discussed on GitHub](https://github.com/orgs/mdn/discussions/170#discussioncomment-3404366). +> [!NOTE] +> Use the language identifier exactly as listed above. For example, `javascript` is not allowed and you must write `js`. + ### Suppressing linting Writers can add a `-nolint` suffix to any of the language identifiers: @@ -135,7 +126,7 @@ Code blocks like this will get appropriate syntax highlighting and will be recog GFM supports [info strings](https://github.github.com/gfm/#info-string), which allow authors to supply additional information about a code block. On MDN, info strings are converted into class names. -Writers will be able to supply any one of the following info strings: +Writers can supply one of the following info strings: - `example-good`: style this example as a good example (one to follow) - `example-bad`: style this example as a bad example (one to avoid) @@ -190,7 +181,7 @@ Writers can use the [GFM alerts syntax](https://docs.github.com/en/get-started/w Notes and warnings will add a localized **Note:** or **Warning:** to the beginning of the output, while callouts will not. This makes callouts a good choice when an author wants to provide a custom title. > [!WARNING] -> In the older MDN syntax, the type was localized and added to the first paragraph in bold text, i.e. `**Note:** Foo bar` instead of `[!NOTE] ⏎ Foo bar`. +> In the older MDN syntax, the type was localized and added to the first paragraph in bold text, i.e., `**Note:** Foo bar` instead of `[!NOTE] ⏎ Foo bar`. > > The older syntax is still supported for migration purposes. Avoid using it in new documentation. @@ -342,9 +333,7 @@ For example, this is a `<dl>`: ````md - term1 - - : My description of term1 - - `term2` - : My description of term2 @@ -458,7 +447,7 @@ and not this style: cell 4 | cell 5 | cell 6 ``` -Luckily, table formatting is auto-fixed by Prettier, so authors may rely on Prettier to format their tables properly. +Tables are formatted by Prettier, so authors rely on tooling to format tables properly. ### When to use HTML tables @@ -591,20 +580,14 @@ The first paragraph should therefore be both succinct and informative. This issue was resolved in <https://github.com/mdn/content/issues/3923>. -## KumaScript +## Macros -Writers will be able to include KumaScript macro calls in prose content: +Writers use macros in prose for templating common linking patterns, or to include specific blocks of code or text: ```md -The **`margin`** [CSS](/en-US/docs/Web/CSS) property -sets the margin area on all four sides of an element. It is a shorthand for -\{{cssxref("margin-top")}}, \{{cssxref("margin-right")}}, \{{cssxref("margin-bottom")}}, -and \{{cssxref("margin-left")}}. - -\{{EmbedInteractiveExample("pages/css/margin.html")}} - -The top and bottom margins have no effect on replaced inline elements, such as -\{{HTMLElement("span")}} or \{{HTMLElement("code")}}. +The **`margin`** [CSS](/en-US/docs/Web/CSS) property sets the margin area on all four sides of an element. +It is a shorthand for \{{cssxref("margin-top")}}, \{{cssxref("margin-right")}}, \{{cssxref("margin-bottom")}}, and \{{cssxref("margin-left")}}. +… ``` -See [Using macros](/en-US/docs/MDN/Writing_guidelines/Page_structures/Macros) for more information on macros. +See [Using macros](/en-US/docs/MDN/Writing_guidelines/Page_structures/Macros) for more information. diff --git a/files/en-us/mdn/writing_guidelines/howto/write_an_api_reference/index.md b/files/en-us/mdn/writing_guidelines/howto/write_an_api_reference/index.md index eb99786bb6f4eba..028e7b43f44fd44 100644 --- a/files/en-us/mdn/writing_guidelines/howto/write_an_api_reference/index.md +++ b/files/en-us/mdn/writing_guidelines/howto/write_an_api_reference/index.md @@ -245,7 +245,7 @@ Now you should be ready to start writing your interface pages. Each interface re - _This interface also inherits methods from \\{{domxref("XYZ")}}, and \\{{domxref("XYZ2")}}._ > [!NOTE] - > Properties that are read-only should have the \\{{ReadOnlyInline}} macro, which creates a nifty little "Read only" badge, included on the same line as their \\{{domxref}} links (after the use of the \\{{experimentalInline}}, \\{{non-standard_Inline}} and \\{{deprecatedInline}} macros, if some of these are needed. + > Properties that are read-only should have the \\{{ReadOnlyInline}} macro, which creates a nifty little "Read only" badge, included on the same line as their \\{{domxref}} links (after the use of the \\{{experimental_inline}}, \\{{non-standard_Inline}} and \\{{deprecated_inline}} macros, if some of these are needed. 6. **Examples**: Include a code listing to show typical usage of a major feature of the API. Rather than listing ALL the code, you should list an interesting subset of it. For a complete code listing, you could reference a [GitHub](https://github.com/) repo containing the full example, and you could also link to a live example created using the [GitHub gh-pages](https://docs.github.com/en/pages/getting-started-with-github-pages/creating-a-github-pages-site) feature (so long as it uses only client-side code of course.) If the example is visual, you could also use the MDN [Live Sample](/en-US/docs/MDN/Writing_guidelines/Page_structures/Live_samples) feature to make it live and playable in the page. 7. **Specifications table**: At this point you need to include a specifications table — see the "Creating a spec reference table" section for more details. diff --git a/files/en-us/mdn/writing_guidelines/howto/write_an_api_reference/information_contained_in_a_webidl_file/index.md b/files/en-us/mdn/writing_guidelines/howto/write_an_api_reference/information_contained_in_a_webidl_file/index.md index 3fecbaf1fb98300..02a337cca6a37aa 100644 --- a/files/en-us/mdn/writing_guidelines/howto/write_an_api_reference/information_contained_in_a_webidl_file/index.md +++ b/files/en-us/mdn/writing_guidelines/howto/write_an_api_reference/information_contained_in_a_webidl_file/index.md @@ -358,13 +358,13 @@ The name of the method is `canPlayType`, and we will refer to it as `HTMLMediaEl ### Parameters -```js +```webidl TextTrack addTextTrack(TextTrackKind kind, optional DOMString label = "", optional DOMString language = ""); ``` -The parameters of a method are listed in the Syntax section of the method sub-page. They are listed in the WebIDL in order, between the parenthesis, as a comma-separated list. Each parameter has a name (indicated above) and a type (e.g. a `'?'` means that the `null` value is valid.) If marked `optional`, the parameter is optional to include in a method call and must have the \\{{OptionalInline}} flag included when it is listed in the Syntax section. The parameter's default value is listed after the equality sign (`'='`). +The parameters of a method are listed in the Syntax section of the method sub-page. They are listed in the WebIDL in order, between the parenthesis, as a comma-separated list. Each parameter has a name (indicated above) and a type (e.g., a `'?'` means that the `null` value is valid.) If marked `optional`, the parameter is optional to include in a method call and must have the \\{{optional_inline}} flag included when it is listed in the Syntax section. The parameter's default value is listed after the equality sign (`'='`). Parameter types may have special behaviors described using extended attributes (like `[LegacyNullToEmptyString]`). Here is the list of such attributes, and the addition you have to do in the prose: diff --git a/files/en-us/mdn/writing_guidelines/howto/write_an_api_reference/sidebars/index.md b/files/en-us/mdn/writing_guidelines/howto/write_an_api_reference/sidebars/index.md index 3fee95120d2fd71..fa7ecb009d5cad2 100644 --- a/files/en-us/mdn/writing_guidelines/howto/write_an_api_reference/sidebars/index.md +++ b/files/en-us/mdn/writing_guidelines/howto/write_an_api_reference/sidebars/index.md @@ -14,7 +14,7 @@ You need to take the following three steps to create your API sidebar: 1. Create your API reference pages. 2. Add an entry for your particular API into the [`GroupData.json`](https://github.com/mdn/content/blob/main/files/jsondata/GroupData.json) file. -3. Use the [`APIRef`](https://github.com/mdn/rari-doc/src/templ/templs/api_list_specs.rs) macro to insert the sidebar into each page you want to display it on. +3. Use the [`APIRef`](https://github.com/mdn/rari/blob/main/crates/rari-doc/src/templ/templs/api_list_specs.rs) macro to insert the sidebar into each page you want to display it on. Let's run through each of these steps in turn. The example we'll refer to in this article is the [Fetch API](/en-US/docs/Web/API/Fetch_API). @@ -90,7 +90,7 @@ These are all technically optional, but it is strongly encouraged that instead o If there are a huge number of events, you might want to consider only listing the most popular ones, or putting them first in the list. For example, `"Document: selectionchange"` is part of the [Selection API](/en-US/docs/Web/API/Selection_API) but `Document` is not, so we add the event to the array and it will be linked from the [Selection API](/en-US/docs/Web/API/Selection_API) topic. 6. `"guides"` — the value is an array of strings, each that addresses a guide topic that explain how to use the API. - The strings contain the part of the guide's URL address after the language path: i.e. the `/docs/...` part of the guide URL. + The strings contain the part of the guide's URL address after the language path: i.e., the `/docs/...` part of the guide URL. For example, to link to the topic "Using Fetch" at `https://developer.mozilla.org/en-US/docs/Web/API/Fetch_API/Using_Fetch`, the guide array would contain "/docs/Web/API/Fetch_API/Using_Fetch". 7. `"dictionaries"` — an array of strings listing all of the dictionaries which are part of the API. Generally, only dictionaries used by more than one property or method should be listed here, unless they are of special significance or are likely to require being referenced from multiple pages. @@ -114,11 +114,11 @@ Pages under the top-level API are crawled each time the sidebar is rendered, and Sub-members are automatically decorated with warning icons based on tags as well. Decorations are added for experimental ("Experimental" tag), non-standard ("Non Standard" or "Non-standard" tag), or deprecated ("Deprecated" tag) sub-members. -Further information about tag-based processing is available [in the APIRef source](https://github.com/mdn/rari-doc/src/templ/templs/api_list_specs.rs). +Further information about tag-based processing is available [in the APIRef source](https://github.com/mdn/rari/blob/main/crates/rari-doc/src/templ/templs/api_list_specs.rs). ## Inserting the sidebar -Once you've added an entry for your API into `GroupData.json`, submitted it as a pull request and had the change accepted into the main repo, you can include it in your API reference pages using the [`APIRef`](https://github.com/mdn/rari-doc/src/templ/templs/api_list_specs.rs) macro, which takes the name you used for your API in GroupData as a parameter. +Once you've added an entry for your API into `GroupData.json`, submitted it as a pull request and had the change accepted into the main repo, you can include it in your API reference pages using the [`APIRef`](https://github.com/mdn/rari/blob/main/crates/rari-doc/src/templ/templs/api_list_specs.rs) macro, which takes the name you used for your API in GroupData as a parameter. As an example, the [WebVR API](/en-US/docs/Web/API/WebVR_API)'s sidebar is included in its pages with the following: ```plain diff --git a/files/en-us/mdn/writing_guidelines/index.md b/files/en-us/mdn/writing_guidelines/index.md index f51e021ca4c4b01..31852527479cef2 100644 --- a/files/en-us/mdn/writing_guidelines/index.md +++ b/files/en-us/mdn/writing_guidelines/index.md @@ -11,13 +11,13 @@ MDN Web Docs is an open-source project. The sections outlined below describe our - : This section covers what we include on MDN Web Docs and what we don't, as well as a number of other policies, such as when we write about new technologies, the content suggestion process, and whether we accept external links. This is a good place to start if you're considering writing or updating content for us. This section also includes: - - [Inclusion criteria](/en-US/docs/MDN/Writing_guidelines/What_we_write/Criteria_for_inclusion) + - [Inclusion criteria](/en-US/docs/MDN/Writing_guidelines/Criteria_for_inclusion) - : Provides an in-depth criteria for content to be included on MDN Web Docs, the application process for getting new documentation added on MDN Web Docs, and the expectations and guidelines for a party applying. - [Our writing style guide](/en-US/docs/MDN/Writing_guidelines/Writing_style_guide) - - : The writing style guide covers the language and style we use to write on MDN Web Docs. It also covers how to [format code examples](/en-US/docs/MDN/Writing_guidelines/Writing_style_guide/Code_style_guide). + - : The writing style guide covers the language and style we use to write on MDN Web Docs. It also covers how to [format code examples](/en-US/docs/MDN/Writing_guidelines/Code_style_guide). - [Learn web development writing guidelines](/en-US/docs/MDN/Writing_guidelines/Learning_content) diff --git a/files/en-us/mdn/writing_guidelines/learning_content/index.md b/files/en-us/mdn/writing_guidelines/learning_content/index.md index 6889e8052339dec..9d3542789843d2b 100644 --- a/files/en-us/mdn/writing_guidelines/learning_content/index.md +++ b/files/en-us/mdn/writing_guidelines/learning_content/index.md @@ -1,11 +1,11 @@ --- title: Learn web development writing guidelines +short-title: Learning content slug: MDN/Writing_guidelines/Learning_content page-type: mdn-writing-guide +sidebar: mdnsidebar --- -{{MDNSidebar}} - The [Learn web development](/en-US/docs/Learn_web_development) section of MDN is aimed specifically at folks learning the basic fundamentals of web development, and as such, requires a different approach to the rest of MDN's content. This articles provides guidelines for writing learning content. ## Target audience @@ -28,13 +28,13 @@ If you do not see a topic covered in Learn and you think it should be covered, d ## Approach -To create and update MDN Learn web development content, you should follow the same approach as for the rest of MDN, in many ways. You should follow the same general [writing style guide](/en-US/docs/MDN/Writing_guidelines/Writing_style_guide), [code style](/en-US/docs/MDN/Writing_guidelines/Writing_style_guide/Code_style_guide), and [techniques](/en-US/docs/MDN/Writing_guidelines/Howto). +To create and update MDN Learn web development content, you should follow the same approach as for the rest of MDN, in many ways. You should follow the same general [writing style guide](/en-US/docs/MDN/Writing_guidelines/Writing_style_guide), [code style](/en-US/docs/MDN/Writing_guidelines/Code_style_guide), and [techniques](/en-US/docs/MDN/Writing_guidelines/Howto). There are a few differences, however: - **Tutorial style**: Most MDN content is a mixture of reference material and guides; Learn, on the other hand, is intended to provide hands-on tutorials. We don't have a strict template for each page, but they should be written in a way that leads readers by the hand, through a combination of step-by-step sections and "Try it out" sections. These should instruct readers to jump in, try things out, and start writing code. See the "Try it out" section at the bottom of our [Search engine](/en-US/docs/Learn_web_development/Getting_started/Environment_setup/Browsing_the_web#search_engine) information, for example. These are created using the following markdown: - ```markdown + ```md > [!CALLOUT] > > **Try it out** @@ -42,14 +42,14 @@ There are a few differences, however: > Try this... ``` -- **Challenges**: Learn content includes challenges periodically to test that the reader understands the topics they have learnt about before moving on to the next article. These are currently written in a few different styles, for example see [Challenge: Structuring a page of content](/en-US/docs/Learn_web_development/Core/Structuring_content/Structuring_a_page_of_content) and [Test your skills: HTML images](/en-US/docs/Learn_web_development/Core/Structuring_content/HTML_images/Test_your_skills:_HTML_images), but we intend to improve the consistency and experience of these in the future. +- **Challenges**: Learn content includes challenges periodically to test that the reader understands the topics they have learnt about before moving on to the next article. These are currently written in a few different styles, for example see [Challenge: Structuring a page of content](/en-US/docs/Learn_web_development/Core/Structuring_content/Structuring_a_page_of_content) and [Test your skills: HTML images](/en-US/docs/Learn_web_development/Core/Structuring_content/Test_your_skills/Images), but we intend to improve the consistency and experience of these in the future. - **Density and completeness**: MDN content is generally known for its comprehensiveness. Learn content is specifically not as exhaustively complete as the rest of the MDN content. It is less dense and gentler in its approach, to allow learners to pick up useful skills and make regular progress, without feeling overwhelmed. They can dive deeper later on. Learn content can omit details to provide a more comfortable learning experience, provided it does not teach the reader anything misleading or bad practice. - **Stable learning outcomes**: The learning outcomes at the top of each tutorial provide a summary of what each tutorial teaches, and together provide a structured curriculum for front-end web development. It is vital that the learning outcomes and what is taught both remain stable and in sync, otherwise the content cannot be trusted as a basis for formal learning (for example educational courses of certifications). As such, changes to the learning outcomes should happen slowly, and not without good reason. If you try to add content that is not covered in the associated learning outcomes (or vice versa), your pull request will be closed. [Make a suggestion](/en-US/docs/MDN/Writing_guidelines/What_we_write#suggesting_content) first. > [!NOTE] -> We maintain a [changelog](/en-US/docs/Learn_web_development/Changelog) that details any significant changes made to the learning outcomes, so educations are able to maintain any resources based on MDN Learn. +> We maintain a [changelog](/en-US/docs/Learn_web_development/Changelog) that details any significant changes made to the learning outcomes, so educators are able to maintain any resources based on MDN Learn. -## External links and embeds +## Partner links and embeds As outlined in our [External links](/en-US/docs/MDN/Writing_guidelines/Writing_style_guide#external_links) guidelines, MDN generally does not allow external links (or embeds) that appear to endorse commercial products of services or point to paywalled content. This is to mitigate the risk of MDN's content losing trust and being made less useful due to being flooded by spam links. @@ -59,7 +59,7 @@ The purpose of these partner links are as follows: - Provide access to supporting content that builds on what is taught in our pages. - Provide access to multimedia learning experiences (videos, slideshows, other interactive content) that MDN content teams don't have the resources to produce. We are all about the text on MDN, but people often want different learning approaches. -- Earn revenue through affiliate links to paid content that we can invest in making MDN even better. +- Earn revenue via affiliate links to paid content options, which we can invest to make MDN even better. However, we: diff --git a/files/en-us/mdn/writing_guidelines/page_structures/code_examples/console-example.png b/files/en-us/mdn/writing_guidelines/page_structures/code_examples/console-example.png deleted file mode 100644 index 4ca0251b9dfd246..000000000000000 Binary files a/files/en-us/mdn/writing_guidelines/page_structures/code_examples/console-example.png and /dev/null differ diff --git a/files/en-us/mdn/writing_guidelines/page_structures/code_examples/index.md b/files/en-us/mdn/writing_guidelines/page_structures/code_examples/index.md index 36e6e548492748d..7372a502875a3a2 100644 --- a/files/en-us/mdn/writing_guidelines/page_structures/code_examples/index.md +++ b/files/en-us/mdn/writing_guidelines/page_structures/code_examples/index.md @@ -11,7 +11,7 @@ This article describes the ways you can add code examples to pages, along with t > [!NOTE] > This page describes **how** code gets included in MDN pages. -> If you want linting and style hints for adding code in an MDN page, see our [Code style guide](/en-US/docs/MDN/Writing_guidelines/Writing_style_guide/Code_style_guide). +> If you want linting and style hints for adding code in an MDN page, see our [Code style guide](/en-US/docs/MDN/Writing_guidelines/Code_style_guide). ## What types of code example are on MDN? @@ -108,7 +108,7 @@ An \\{{EmbedGHLiveSample}} takes the content at a specified URL (which must be a The macro has three parameters: -1. The URL of the document to embed — this is relative to the MDN organization, the top level directory of which is at `https://mdn.github.io/`. So this parameter needs to contain the part of the URL after that, e.g. `my-subdirectory/example.html`. You can omit the filename if it is called `index.html`. +1. The URL of the document to embed — this is relative to the MDN organization, the top level directory of which is at `https://mdn.github.io/`. So this parameter needs to contain the part of the URL after that, e.g., `my-subdirectory/example.html`. You can omit the filename if it is called `index.html`. 2. The width of the `<iframe>`, which can be expressed as a percentage or in pixels. 3. The height of the `<iframe>`, which can be expressed as a percentage or in pixels. diff --git a/files/en-us/mdn/writing_guidelines/page_structures/feature_status/index.md b/files/en-us/mdn/writing_guidelines/page_structures/feature_status/index.md index dc5bd45daf12e26..bf2cead4a88dc9f 100644 --- a/files/en-us/mdn/writing_guidelines/page_structures/feature_status/index.md +++ b/files/en-us/mdn/writing_guidelines/page_structures/feature_status/index.md @@ -5,17 +5,18 @@ page-type: mdn-writing-guide sidebar: mdnsidebar --- -> [!WARNING] -> Do not manually update the feature statuses in `mdn/content` repository. -> The documentation source is [automatically updated](#how_feature_statuses_are_added_or_updated) from information in the GitHub `mdn/browser-compat-data` repository - A feature status broadly indicates the cross-browser implementation and standardization state of a particular web platform feature, such as a Web API method or CSS property. + It is one of the following: - [`deprecated`](https://github.com/mdn/browser-compat-data/blob/main/docs/data-guidelines/index.md#setting-deprecated) - [`experimental`](https://github.com/mdn/browser-compat-data/blob/main/docs/data-guidelines/index.md#setting-experimental) - [`non-standard`](https://github.com/mdn/browser-compat-data/blob/main/schemas/compat-data-schema.md#status-information) +> [!WARNING] +> Do not manually update the feature statuses in the `mdn/content` repository. +> The documentation source is [automatically updated](#how_feature_statuses_are_added_or_updated) from information in the GitHub `mdn/browser-compat-data` repository. + If none of the above statuses apply, the feature is considered _stable and standard feature_. For more information on these terms, see the ["Experimental, deprecated, and obsolete"](/en-US/docs/MDN/Writing_guidelines/Experimental_deprecated_obsolete) page. @@ -28,7 +29,7 @@ The feature statuses of all the features documented on MDN are tracked in its ac The automation uses [`browser-compat`](/en-US/docs/MDN/Writing_guidelines/Page_structures/Compatibility_tables#using_bcd_data_in_mdn_pages) key in the front-matter. The key stores BCD query required to locate the feature in the compatibility data. If the `browser-compat` key has multiple values then the automation uses only the first value to render status macros. > [!NOTE] -> To update a feature's status in the MDN content, you need to [submit a pull request](https://github.com/mdn/browser-compat-data/blob/main/docs/contributing.md#updating-the-compat-data) in the BCD repository. After your changes are approved and merged in BCD, an [automated pull request](https://github.com/search?q=repo%3Amdn%2Fcontent+Synchronize+with+BCD&type=pullrequests) updates the statuses in the `mdn/content` repository. +> To update a feature's status in the MDN content, you need to [submit a pull request](https://github.com/mdn/browser-compat-data/blob/main/docs/contributing.md#updating-the-compat-data) in the BCD repository. After your changes are approved and merged in BCD, it goes into a weekly release, and an automated pull request updates the statuses in the `mdn/content` repository for every release. ## How are feature statuses specified in content? @@ -36,9 +37,9 @@ The following sections document the mechanisms that are used to insert and rende ### Feature status icons in sidebars -The `status` property in page [front-matter](/en-US/docs/MDN/Writing_guidelines/Page_structures/Page_types/CSS_function_page_template#sect1) is used to generate status icons for features when they are displayed in sidebars. +The `status` property in page front matter is used to generate status icons for features when they are displayed in sidebars. -```yml +```yaml --- title: Feature name status: diff --git a/files/en-us/mdn/writing_guidelines/page_structures/links/index.md b/files/en-us/mdn/writing_guidelines/page_structures/links/index.md index 305e7ce6f34593c..bb45bbd7bdf201d 100644 --- a/files/en-us/mdn/writing_guidelines/page_structures/links/index.md +++ b/files/en-us/mdn/writing_guidelines/page_structures/links/index.md @@ -17,7 +17,7 @@ MDN provides macros that create a list of links: - [`\{{ListSubpagesForSidebar()}}`](https://github.com/mdn/rari/blob/main/crates/rari-doc/src/templ/templs/list_subpages_for_sidebar.rs) - - : When included without parameters, inserts an ordered list of links to the current page's subpages. This macro is most often used within [sidebars](/en-US/docs/MDN/Writing_guidelines/Page_structures/Sidebars) (hence the macro name), where the bullets are not rendered. The first parameter is a slug of the link tree's parent page. The link text is displayed as code. Setting a second parameter to `true` or `1` converts the links to plain text. Setting a third parameter to `true` or `1` adds a link to the slug (parent) page at the top of the list with "Overview" as the link text. + - : When included without parameters, inserts an ordered list of links to the current page's subpages. The first parameter is a slug of the link tree's parent page. The link text is displayed as code. Setting a second parameter to `true` or `1` converts the links to plain text. Setting a third parameter to `true` or `1` adds a link to the slug (parent) page at the top of the list with "Overview" as the link text. - [`\{{QuickLinksWithSubpages()}}`](https://github.com/mdn/rari/blob/main/crates/rari-doc/src/templ/templs/quick_links_with_subpages.rs) @@ -31,10 +31,6 @@ To include an ordered list of links that includes this page and its siblings, wr \{{ListSubpagesForSidebar("/en-US/docs/MDN/Writing_guidelines/Page_structures/Macros", 1)}} ``` -This produces: - -{{ListSubpagesForSidebar("/en-US/docs/MDN/Writing_guidelines/Page_structures/Macros", 1)}} - ## Cross-reference links Some macros create a single link to cross-reference a CSS, JavaScript, SVG, or HTML feature, including attributes, elements, properties, data types, and APIs. The macros that create single links require at least one parameter: the feature being referenced. @@ -51,9 +47,9 @@ These macros are: - [`\{{HTTPMethod("")}}`](https://github.com/mdn/rari/blob/main/crates/rari-doc/src/templ/templs/links/http.rs) - [`\{{HTTPStatus("")}}`](https://github.com/mdn/rari/blob/main/crates/rari-doc/src/templ/templs/links/http.rs) -The first parameter of each of these macros is the last section of the slug of the document being referenced. For example, for HTML Elements, include `\{{HTMLElement("")}}` with the part of the slug that comes after `Web/HTML/Element/` in the slug being the first parameter. With `\{{CSSxRef("")}}`, add the part of the slug that comes after `Web/CSS/` in the slug. The link will go to this page. +The first parameter of each of these macros is the last section of the slug of the document being referenced. For example, for HTML Elements, include `\{{HTMLElement("")}}` with the part of the slug that comes after `Web/HTML/Reference/Elements/` in the slug being the first parameter. With `\{{CSSxRef("")}}`, add the part of the slug that comes after `Web/CSS/` in the slug. The link will go to this page. -By default, the text displayed is the linked resource as written in the first parameter, in angle brackets for the case of `\{{HTMLElement()}}`. This may not be what you want. For example, the slug for the range input type is `Web/HTML/Element/input/range`. Including `\{{HTMLElement("input/range")}}` produces "{{HTMLElement("input/range")}}". That is not what you want. All the macros accept additional parameters, so you can provide the text you want to display. +By default, the text displayed is the linked resource as written in the first parameter, in angle brackets for the case of `\{{HTMLElement()}}`. This may not be what you want. For example, the slug for the range input type is `Web/HTML/Reference/Elements/input/range`. Including `\{{HTMLElement("input/range")}}` produces "{{HTMLElement("input/range")}}". That is not what you want. All the macros accept additional parameters, so you can provide the text you want to display. The second parameter, if present, provides the link text. In the input range case, we would write `\{{HTMLElement("input/range", "<code>&lt;input type=&quot;range&quot;&gt;</code>")}}` which produces "{{HTMLElement("input/range", "<code>&lt;input type=&quot;range&quot;&gt;</code>")}}". This particular macro removes the {{htmlelement("code")}} and angle brackets when the second parameter includes a space, so we added the brackets and code tags. @@ -70,5 +66,5 @@ To learn which parameters each macro supports and the order of parameters for ea ## See also - [Using macros](/en-US/docs/MDN/Writing_guidelines/Page_structures/Macros) -- [Commonly used macros](/en-US/docs/MDN/Writing_guidelines/Page_structures/Macros/Commonly_used_macros), including BCD macros ( `\{{Compat}}`, `\{{Compat(&lt;feature>)}}`, and `\{{Compat(&lt;feature>, &lt;depth>)}}`) and specification macros (`\{{Specifications}}` / `\{{Specifications(&lt;feature>)}}`) +- [Commonly used macros](/en-US/docs/MDN/Writing_guidelines/Page_structures/Macros/Commonly_used_macros), including BCD macros (`\{{Compat}}`) and specification macros (`\{{Specifications}}`). - [Banners and notices guide](/en-US/docs/MDN/Writing_guidelines/Page_structures/Banners_and_notices) including the `\{{SeeCompatTable}}`, `\{{Deprecated_Header}}`, and `\{{SecureContext_Header}}` macros. diff --git a/files/en-us/mdn/writing_guidelines/page_structures/live_samples/index.md b/files/en-us/mdn/writing_guidelines/page_structures/live_samples/index.md index 54b355dbd3afe03..ac670ba1297a5ae 100644 --- a/files/en-us/mdn/writing_guidelines/page_structures/live_samples/index.md +++ b/files/en-us/mdn/writing_guidelines/page_structures/live_samples/index.md @@ -223,7 +223,7 @@ Only the `<p>` element with `class="fancy"` will get styled `red`. One common use case is to take existing code snippets already shown on MDN and turning them into live samples. The first step is to either add code snippets or ensure that existing ones are ready to be used as live samples, in terms of the content and in terms of their markup. The code snippets, taken together, must comprise a complete, runnable example. For example, if the existing snippet shows only CSS, you might need to add a snippet of HTML for the CSS to operate on. -Each piece of code must be in a code block, with a separate block for each language, properly marked as to which language it is. Most of the time, this has already been done, but it's always worth double-checking to be sure each piece of code is configured with the correct syntax. This is done with a language identifier on the code block of `language-type`, where _language-type_ is the type of language the block contains, e.g. `html`, `css`, or `js`. +Each piece of code must be in a code block, with a separate block for each language, properly marked as to which language it is. Most of the time, this has already been done, but it's always worth double-checking to be sure each piece of code is configured with the correct syntax. This is done with a language identifier on the code block of `language-type`, where _language-type_ is the type of language the block contains, e.g., `html`, `css`, or `js`. > [!NOTE] > You may have more than one block for each language; they are all concatenated together. This lets you have a chunk of code, followed by an explanation of how it works, then another chunk, and so forth. This makes it even easier to produce tutorials and the like that utilize live samples interspersed with explanatory text. @@ -358,7 +358,7 @@ Result of `\{{EmbedLiveSample("iframe_size", "", "120")}}`: ### Allowing features -The `allow` parameter can be used to specify the features that are allowed in the `<iframe>` element that contains the live sample output. The available values come from the [permission policy syntax for frames](/en-US/docs/Web/HTTP/Permissions_Policy#embedded_frame_syntax). +The `allow` parameter can be used to specify the features that are allowed in the `<iframe>` element that contains the live sample output. The available values come from the [permission policy syntax for frames](/en-US/docs/Web/HTTP/Guides/Permissions_Policy#embedded_frame_syntax). ```html <div id="fullscreen-content"> @@ -594,6 +594,6 @@ Reset the example by pressing the "Reset" button. - Orders of code blocks - : When adding a live sample, the code blocks should be sorted so that the first one corresponds to the main language for this sample (if there is one). For example, when adding a live sample for the HTML Reference, the first block should be HTML, when adding a live sample for the CSS Reference, it should be CSS and so on. - Naming of headings - - : When there is no ambiguity (e.g. the sample is under a "Examples" section), headings should be straightforward with the sole name of the corresponding language: HTML, CSS, JavaScript, SVG, etc. (see above). Headings like "HTML Content" or "JavaScript Content" should not be used. However if such a short heading makes content unclear, one can use a more thoughtful title. + - : When there is no ambiguity (e.g., the sample is under a "Examples" section), headings should be straightforward with the sole name of the corresponding language: HTML, CSS, JavaScript, SVG, etc. (see above). Headings like "HTML Content" or "JavaScript Content" should not be used. However if such a short heading makes content unclear, one can use a more thoughtful title. - Using a "Result" block - - : After the different code blocks, please use a last "Result" block before using the `EmbedLiveSample` macro (see above). This way, the semantic of the example is made clearer for both the reader and any tools that would parse the page (e.g. screen reader, web crawler). + - : After the different code blocks, please use a last "Result" block before using the `EmbedLiveSample` macro (see above). This way, the semantic of the example is made clearer for both the reader and any tools that would parse the page (e.g., screen reader, web crawler). diff --git a/files/en-us/mdn/writing_guidelines/page_structures/macros/commonly_used_macros/index.md b/files/en-us/mdn/writing_guidelines/page_structures/macros/commonly_used_macros/index.md index 017689c9888af03..c6fe747f1f1c034 100644 --- a/files/en-us/mdn/writing_guidelines/page_structures/macros/commonly_used_macros/index.md +++ b/files/en-us/mdn/writing_guidelines/page_structures/macros/commonly_used_macros/index.md @@ -6,9 +6,7 @@ sidebar: mdnsidebar --- This page lists many of the general-purpose macros created for use on MDN. -For additional how-to information on using these macros, see [Using macros](/en-US/docs/MDN/Writing_guidelines/Page_structures/Macros). - -See [Other macros](/en-US/docs/MDN/Writing_guidelines/Page_structures/Macros/Other) for information on macros that are infrequently used, are used only in special contexts, or are deprecated. +For generic how-to information on using them in MDN content, see [Using macros](/en-US/docs/MDN/Writing_guidelines/Page_structures/Macros). ## Linking @@ -70,7 +68,7 @@ Most macros will also take a second argument allowing you to change the display <a href="https://github.com/mdn/rari/blob/main/crates/rari-doc/src/templ/templs/links/htmlxref.rs">HTMLElement</a> </td> <td> - <a href="/en-US/docs/Web/HTML/Element">HTML Elements reference</a> (/Web/HTML/Element) + <a href="/en-US/docs/Web/HTML/Reference/Elements">HTML Elements reference</a> (/Web/HTML/Reference/Elements) </td> <td> <code>\{{HTMLElement("select")}}</code> results in {{HTMLElement("select")}} @@ -92,7 +90,7 @@ Most macros will also take a second argument allowing you to change the display <a href="https://github.com/mdn/rari/blob/main/crates/rari-doc/src/templ/templs/links/svgattr.rs">SVGAttr</a> </td> <td> - <a href="/en-US/docs/Web/SVG/Attribute">SVG attribute reference</a> (/Web/SVG/Attribute). + <a href="/en-US/docs/Web/SVG/Reference/Attribute">SVG attribute reference</a> (/Web/SVG/Reference/Attribute). </td> <td> <code>\{{SVGAttr("d")}}</code> results in {{SVGAttr("d")}} @@ -104,7 +102,7 @@ Most macros will also take a second argument allowing you to change the display href="https://github.com/mdn/rari/blob/main/crates/rari-doc/src/templ/templs/links/svgxref.rs">SVGElement</a> </td> <td> - <a href="/en-US/docs/Web/SVG/Attribute">SVG Element reference</a> (/Web/SVG/Element). + <a href="/en-US/docs/Web/SVG/Reference/Element">SVG Element reference</a> (/Web/SVG/Reference/Element). </td> <td> <code>\{{SVGElement("view")}}</code> results in {{SVGElement("view")}} @@ -115,7 +113,7 @@ Most macros will also take a second argument allowing you to change the display <code><a href="https://github.com/mdn/rari/blob/main/crates/rari-doc/src/templ/templs/links/http.rs">HTTPHeader</a></code> </td> <td> - <a href="/en-US/docs/Web/HTTP/Headers">HTTP headers</a> (/Web/HTTP/Headers). + <a href="/en-US/docs/Web/HTTP/Reference/Headers">HTTP headers</a> (/Web/HTTP/Reference/Headers). </td> <td> <code>\{{HTTPHeader("ACCEPT")}}</code> results in {{HTTPHeader("ACCEPT")}} @@ -126,7 +124,7 @@ Most macros will also take a second argument allowing you to change the display <a href="https://github.com/mdn/rari/blob/main/crates/rari-doc/src/templ/templs/links/http.rs">HTTPMethod</a> </td> <td> - <a href="/en-US/docs/Web/HTTP/Methods">HTTP request methods</a> (/Web/HTTP/Methods). + <a href="/en-US/docs/Web/HTTP/Reference/Methods">HTTP request methods</a> (/Web/HTTP/Reference/Methods). </td> <td> <code>\{{HTTPMethod("HEAD")}}</code> results in {{HTTPMethod("HEAD")}} @@ -137,7 +135,7 @@ Most macros will also take a second argument allowing you to change the display <a href="https://github.com/mdn/rari/blob/main/crates/rari-doc/src/templ/templs/links/http.rs">HTTPStatus</a> </td> <td> - <a href="/en-US/docs/Web/HTTP/Status">HTTP response status codes</a> (/Web/HTTP/Status) + <a href="/en-US/docs/Web/HTTP/Reference/Status">HTTP response status codes</a> (/Web/HTTP/Reference/Status) </td> <td> <code>\{{HTTPStatus("404")}}</code> results in {{HTTPStatus("404")}} @@ -232,7 +230,7 @@ They can also be used to mark up a section on a page. Example: `\{{SeeCompatTable}}` {{SeeCompatTable}} - [`Deprecated_Header`](https://github.com/mdn/rari/blob/main/crates/rari-doc/src/templ/templs/banners.rs): `\{{Deprecated_Header}}` {{Deprecated_Header}} - [`SecureContext_Header`](https://github.com/mdn/rari/blob/main/crates/rari-doc/src/templ/templs/banners.rs). - Should be used on main pages like interface pages, API overview pages, and API entry points (e.g. `navigator.xyz`) but usually not on subpages like method and property pages. + Should be used on main pages like interface pages, API overview pages, and API entry points (e.g., `navigator.xyz`) but usually not on subpages like method and property pages. Example: `\{{SecureContext_Header}}` {{SecureContext_Header}} #### Indicating that a feature is available in web workers @@ -256,12 +254,10 @@ You can also pass some arguments to indicate that a feature works in specified w The following macros are included on all reference pages, but are also supported by all page types: -- `\{{Compat}}` / `\{{Compat(&lt;feature>)}}` / `\{{Compat(&lt;feature>, &lt;depth>)}}` - - - : Generates a [compatibility table](/en-US/docs/MDN/Writing_guidelines/Page_structures/Compatibility_tables) for the feature passed as the parameter. If no parameter is included, it defaults to the features defined by `browser-compat` in the frontmatter. An optional depth parameter sets how deep sub features should be added to the table. The depth, if omitted, defaults to 1, meaning only the first level of sub feature data from BCD will be included. - -- `\{{Specifications}}` / `\{{Specifications(&lt;feature>)}}` - - : Includes the specification for the feature specified in the parameter. If no parameter is passed, the specification listed is defined by the value for `spec-urls` in the frontmatter, if present, or from the specification listed in browser compatibility data defined by `browser-compat` in the frontmatter. The specification is rendered as an external link. +- `\{{Compat}}` + - : Generates a [compatibility table](/en-US/docs/MDN/Writing_guidelines/Page_structures/Compatibility_tables) for the feature(s) defined by `browser-compat` in the frontmatter. +- `\{{Specifications}}` + - : Includes a [specification table](/en-US/docs/MDN/Writing_guidelines/Page_structures/Specification_tables) for the feature(s) defined by `spec-urls` in the frontmatter, if present, or from the specification listed in browser compatibility data defined by `browser-compat` in the frontmatter. ## See also @@ -269,3 +265,4 @@ The following macros are included on all reference pages, but are also supported - [Page templates](/en-US/docs/MDN/Writing_guidelines/Page_structures/Page_types#page_templates) - [Page components](/en-US/docs/MDN/Writing_guidelines/Writing_style_guide#page_components) - [Feature status macros](/en-US/docs/MDN/Writing_guidelines/Page_structures/Feature_status) +- [Other macros](/en-US/docs/MDN/Writing_guidelines/Page_structures/Macros/Other): infrequently used or deprecated macros diff --git a/files/en-us/mdn/writing_guidelines/page_structures/macros/index.md b/files/en-us/mdn/writing_guidelines/page_structures/macros/index.md index b8b6e00954effd5..20610d08b86a6e1 100644 --- a/files/en-us/mdn/writing_guidelines/page_structures/macros/index.md +++ b/files/en-us/mdn/writing_guidelines/page_structures/macros/index.md @@ -25,6 +25,7 @@ A few notes about macro calls: Macros can be as simple as just inserting a larger block of text or swapping in contents from another part of MDN, or as complex as building an entire index of content by searching through parts of the site, styling the output, and adding links. You can read up on our most commonly used macros on the [Commonly used macros](/en-US/docs/MDN/Writing_guidelines/Page_structures/Macros/Commonly_used_macros) page. +Less common macros are described in the [Other macros](/en-US/docs/MDN/Writing_guidelines/Page_structures/Macros/Other) documentation. ## See also diff --git a/files/en-us/mdn/writing_guidelines/page_structures/page_types/api_constructor_subpage_template/index.md b/files/en-us/mdn/writing_guidelines/page_structures/page_types/api_constructor_subpage_template/index.md index 59f7833c1fb5e7c..a9ffc819cc22f9b 100644 --- a/files/en-us/mdn/writing_guidelines/page_structures/page_types/api_constructor_subpage_template/index.md +++ b/files/en-us/mdn/writing_guidelines/page_structures/page_types/api_constructor_subpage_template/index.md @@ -67,12 +67,11 @@ sidebar: mdnsidebar > If it is, then you should also fill in an entry for it in the [Features restricted to secure contexts](/en-US/docs/Web/Security/Secure_Contexts/features_restricted_to_secure_contexts) page. > - `\{{AvailableInWorkers}}` — this generates a **Available In Workers** note that indicates that the technology is available in [worker context](/en-US/docs/Web/API/Web_Workers_API). > If it is only available in window context, then you can remove the macro call. -> If it is also available or only available in worker context, then you may also need to passing an parameter to it due to its availability (see [\\{{AvailableInWorkers}} macros source code](https://github.com/mdn/rari/blob/main/crates/rari-doc/src/templ/templs/banners.rs) for all available values), you may also need to fill in an entry for it in the [Web APIs available in workers](/en-US/docs/Web/API/Web_Workers_API/Functions_and_classes_available_to_workers#supported_web_apis) page. +> If it is also available or only available in worker context, then you may also need to passing an parameter to it due to its availability (see [\\{{AvailableInWorkers}} macros source code](https://github.com/mdn/rari/blob/main/crates/rari-doc/src/templ/templs/banners.rs) for all available values), you may also need to fill in an entry for it in the [Web APIs available in workers](/en-US/docs/Web/API/Web_Workers_API/Functions_and_classes_available_to_workers#web_apis_available_in_workers) page. > - `\{{APIRef("GroupDataName")}}` — this generates the left-hand reference sidebar showing quick reference links related to the current page. > For example, every page in the [WebVR API](/en-US/docs/Web/API/WebVR_API) has the same sidebar, which points to the other pages in the API. > To generate the correct sidebar for your API, you need to add a `GroupData` entry to our GitHub repo, and include the entry's name inside the macro call in place of _GroupDataName_. > See our [API reference sidebars](/en-US/docs/MDN/Writing_guidelines/Howto/Write_an_api_reference/Sidebars) guide for information on how to do this. -> - Remember to remove the `\{{MDNSidebar}}` macro when you copy this page. > > Do not provide status header macros manually. Refer to the section [How feature statuses are added or updated](/en-US/docs/MDN/Writing_guidelines/Page_structures/Feature_status#how_feature_statuses_are_added_or_updated) to add these statuses to the page. > diff --git a/files/en-us/mdn/writing_guidelines/page_structures/page_types/api_event_subpage_template/index.md b/files/en-us/mdn/writing_guidelines/page_structures/page_types/api_event_subpage_template/index.md index 42849cb7dfd93e2..8ed9021a366abb3 100644 --- a/files/en-us/mdn/writing_guidelines/page_structures/page_types/api_event_subpage_template/index.md +++ b/files/en-us/mdn/writing_guidelines/page_structures/page_types/api_event_subpage_template/index.md @@ -66,12 +66,11 @@ sidebar: mdnsidebar > If it is, then you should also fill in an entry for it in the [Features restricted to secure contexts](/en-US/docs/Web/Security/Secure_Contexts/features_restricted_to_secure_contexts) page. > - `\{{AvailableInWorkers}}` — this generates a **Available In Workers** note that indicates that the technology is available in [worker context](/en-US/docs/Web/API/Web_Workers_API). > If it is only available in window context, then you can remove the macro call. -> If it is also available or only available in worker context, then you may also need to passing an parameter to it due to its availability (see [\\{{AvailableInWorkers}} macros source code](https://github.com/mdn/rari/blob/main/crates/rari-doc/src/templ/templs/banners.rs) for all available values), you may also need to fill in an entry for it in the [Web APIs available in workers](/en-US/docs/Web/API/Web_Workers_API/Functions_and_classes_available_to_workers#supported_web_apis) page. +> If it is also available or only available in worker context, then you may also need to passing an parameter to it due to its availability (see [\\{{AvailableInWorkers}} macros source code](https://github.com/mdn/rari/blob/main/crates/rari-doc/src/templ/templs/banners.rs) for all available values), you may also need to fill in an entry for it in the [Web APIs available in workers](/en-US/docs/Web/API/Web_Workers_API/Functions_and_classes_available_to_workers#web_apis_available_in_workers) page. > - `\{{APIRef("GroupDataName")}}` — this generates the left-hand reference sidebar showing quick reference links related to the current page. > For example, every page in the [WebVR API](/en-US/docs/Web/API/WebVR_API) has the same sidebar, which points to the other pages in the API. > To generate the correct sidebar for your API, you need to add a `GroupData` entry to our GitHub repo, and include the entry's name inside the macro call in place of _GroupDataName_. > See our [API reference sidebars](/en-US/docs/MDN/Writing_guidelines/Howto/Write_an_api_reference/Sidebars) guide for information on how to do this. -> - Remember to remove the `\{{MDNSidebar}}` macro when you copy this page. > > Do not provide status header macros manually. Refer to the section ["How feature statuses are added or updated"](/en-US/docs/MDN/Writing_guidelines/Page_structures/Feature_status#how_feature_statuses_are_added_or_updated) to add these statuses to the page. > @@ -99,10 +98,10 @@ You could copy most of this from the property's summary on the corresponding API Use the event name in methods like {{domxref("EventTarget.addEventListener", "addEventListener()")}}, or set an event handler property. -```js -addEventListener("NameOfTheEvent", (event) => {}); +```js-nolint +addEventListener("NameOfTheEvent", (event) => { }) -onNameOfTheEvent = (event) => {}; +onNameOfTheEvent = (event) => { } ``` ## Event type diff --git a/files/en-us/mdn/writing_guidelines/page_structures/page_types/api_landing_page_template/index.md b/files/en-us/mdn/writing_guidelines/page_structures/page_types/api_landing_page_template/index.md index ab79801db20764c..8b5a3467e69b118 100644 --- a/files/en-us/mdn/writing_guidelines/page_structures/page_types/api_landing_page_template/index.md +++ b/files/en-us/mdn/writing_guidelines/page_structures/page_types/api_landing_page_template/index.md @@ -59,12 +59,11 @@ sidebar: mdnsidebar > If it is, then you should also fill in an entry for it in the [Features restricted to secure contexts](/en-US/docs/Web/Security/Secure_Contexts/features_restricted_to_secure_contexts) page. > - `\{{AvailableInWorkers}}` — this generates a **Available In Workers** note that indicates that the technology is available in [worker context](/en-US/docs/Web/API/Web_Workers_API). > If it is only available in window context, then you can remove the macro call. -> If it is also available or only available in worker context, then you may also need to passing an parameter to it due to its availability (see [\\{{AvailableInWorkers}} macros source code](https://github.com/mdn/rari/blob/main/crates/rari-doc/src/templ/templs/banners.rs) for all available values), you may also need to fill in an entry for it in the [Web APIs available in workers](/en-US/docs/Web/API/Web_Workers_API/Functions_and_classes_available_to_workers#supported_web_apis) page. +> If it is also available or only available in worker context, then you may also need to passing an parameter to it due to its availability (see [\\{{AvailableInWorkers}} macros source code](https://github.com/mdn/rari/blob/main/crates/rari-doc/src/templ/templs/banners.rs) for all available values), you may also need to fill in an entry for it in the [Web APIs available in workers](/en-US/docs/Web/API/Web_Workers_API/Functions_and_classes_available_to_workers#web_apis_available_in_workers) page. > - `\{{APIRef("GroupDataName")}}` — this generates the left-hand reference sidebar showing quick reference links related to the current page. > For example, every page in the [WebVR API](/en-US/docs/Web/API/WebVR_API) has the same sidebar, which points to the other pages in the API. > To generate the correct sidebar for your API, you need to add a `GroupData` entry to our GitHub repo, and include the entry's name inside the macro call in place of _GroupDataName_. > See our [API reference sidebars](/en-US/docs/MDN/Writing_guidelines/Howto/Write_an_api_reference/Sidebars) guide for information on how to do this. -> - Remember to remove the `\{{MDNSidebar}}` macro when you copy this page. > > Do not provide status header macros manually. Refer to the section ["How feature statuses are added or updated"](/en-US/docs/MDN/Writing_guidelines/Page_structures/Feature_status#how_feature_statuses_are_added_or_updated) to add these statuses to the page. > @@ -104,8 +103,8 @@ In this section, describe the API's purpose and usage cases in a bit more detail What problems does it solve? What concepts does it involve? How do you use it, from a high-level perspective? Don't go into a lot of detail in this section, and don't include code examples. -If there are a lot of concepts to explain around this API, you should explain them in a separate "Fundamentals" or "Concepts" article (e.g. [Fundamentals of WebXR](/en-US/docs/Web/API/WebXR_Device_API/Fundamentals)). -For a practical usage guide with code examples, you should include a "Usage…" article in your API docs (e.g. [Using the WebVR API](/en-US/docs/Web/API/WebVR_API/Using_the_WebVR_API)). +If there are a lot of concepts to explain around this API, you should explain them in a separate "Fundamentals" or "Concepts" article (e.g., [Fundamentals of WebXR](/en-US/docs/Web/API/WebXR_Device_API/Fundamentals)). +For a practical usage guide with code examples, you should include a "Usage…" article in your API docs (e.g., [Using the WebVR API](/en-US/docs/Web/API/WebVR_API/Using_the_WebVR_API)). To help improve content discoverability and {{Glossary("SEO")}}, keep the following tips in mind: diff --git a/files/en-us/mdn/writing_guidelines/page_structures/page_types/api_method_subpage_template/index.md b/files/en-us/mdn/writing_guidelines/page_structures/page_types/api_method_subpage_template/index.md index 81db745bb2806e4..9a56743334b4e1a 100644 --- a/files/en-us/mdn/writing_guidelines/page_structures/page_types/api_method_subpage_template/index.md +++ b/files/en-us/mdn/writing_guidelines/page_structures/page_types/api_method_subpage_template/index.md @@ -72,12 +72,11 @@ sidebar: mdnsidebar > If it is, then you should also fill in an entry for it in the [Features restricted to secure contexts](/en-US/docs/Web/Security/Secure_Contexts/features_restricted_to_secure_contexts) page. > - `\{{AvailableInWorkers}}` — this generates a **Available In Workers** note that indicates that the technology is available in [worker context](/en-US/docs/Web/API/Web_Workers_API). > If it is only available in window context, then you can remove the macro call. -> If it is also available or only available in worker context, then you may also need to passing an parameter to it due to its availability (see [\\{{AvailableInWorkers}} macros source code](https://github.com/mdn/rari/blob/main/crates/rari-doc/src/templ/templs/banners.rs) for all available values), you may also need to fill in an entry for it in the [Web APIs available in workers](/en-US/docs/Web/API/Web_Workers_API/Functions_and_classes_available_to_workers#supported_web_apis) page. +> If it is also available or only available in worker context, then you may also need to passing an parameter to it due to its availability (see [\\{{AvailableInWorkers}} macros source code](https://github.com/mdn/rari/blob/main/crates/rari-doc/src/templ/templs/banners.rs) for all available values), you may also need to fill in an entry for it in the [Web APIs available in workers](/en-US/docs/Web/API/Web_Workers_API/Functions_and_classes_available_to_workers#web_apis_available_in_workers) page. > - `\{{APIRef("GroupDataName")}}` — this generates the left-hand reference sidebar showing quick reference links related to the current page. > For example, every page in the [WebVR API](/en-US/docs/Web/API/WebVR_API) has the same sidebar, which points to the other pages in the API. > To generate the correct sidebar for your API, you need to add a `GroupData` entry to our GitHub repo, and include the entry's name inside the macro call in place of _GroupDataName_. > See our [API reference sidebars](/en-US/docs/MDN/Writing_guidelines/Howto/Write_an_api_reference/Sidebars) guide for information on how to do this. -> - Remember to remove the `\{{MDNSidebar}}` macro when you copy this page. > > Do not provide status header macros manually. Refer to the section ["How feature statuses are added or updated"](/en-US/docs/MDN/Writing_guidelines/Page_structures/Feature_status#how_feature_statuses_are_added_or_updated) to add these statuses to the page. > diff --git a/files/en-us/mdn/writing_guidelines/page_structures/page_types/api_property_subpage_template/index.md b/files/en-us/mdn/writing_guidelines/page_structures/page_types/api_property_subpage_template/index.md index e0d5077b7986af2..a49cd122e0da98f 100644 --- a/files/en-us/mdn/writing_guidelines/page_structures/page_types/api_property_subpage_template/index.md +++ b/files/en-us/mdn/writing_guidelines/page_structures/page_types/api_property_subpage_template/index.md @@ -70,12 +70,11 @@ sidebar: mdnsidebar > If it is, then you should also fill in an entry for it in the [Features restricted to secure contexts](/en-US/docs/Web/Security/Secure_Contexts/features_restricted_to_secure_contexts) page. > - `\{{AvailableInWorkers}}` — this generates a **Available In Workers** note that indicates that the technology is available in [worker context](/en-US/docs/Web/API/Web_Workers_API). > If it is only available in window context, then you can remove the macro call. -> If it is also available or only available in worker context, then you may also need to passing an parameter to it due to its availability (see [\\{{AvailableInWorkers}} macros source code](https://github.com/mdn/rari/blob/main/crates/rari-doc/src/templ/templs/banners.rs) for all available values), you may also need to fill in an entry for it in the [Web APIs available in workers](/en-US/docs/Web/API/Web_Workers_API/Functions_and_classes_available_to_workers#supported_web_apis) page. +> If it is also available or only available in worker context, then you may also need to passing an parameter to it due to its availability (see [\\{{AvailableInWorkers}} macros source code](https://github.com/mdn/rari/blob/main/crates/rari-doc/src/templ/templs/banners.rs) for all available values), you may also need to fill in an entry for it in the [Web APIs available in workers](/en-US/docs/Web/API/Web_Workers_API/Functions_and_classes_available_to_workers#web_apis_available_in_workers) page. > - `\{{APIRef("GroupDataName")}}` — this generates the left-hand reference sidebar showing quick reference links related to the current page. > For example, every page in the [WebVR API](/en-US/docs/Web/API/WebVR_API) has the same sidebar, which points to the other pages in the API. > To generate the correct sidebar for your API, you need to add a `GroupData` entry to our GitHub repo, and include the entry's name inside the macro call in place of _GroupDataName_. > See our [API reference sidebars](/en-US/docs/MDN/Writing_guidelines/Howto/Write_an_api_reference/Sidebars) guide for information on how to do this. -> - Remember to remove the `\{{MDNSidebar}}` macro when you copy this page. > > Do not provide status header macros manually. Refer to the section ["How feature statuses are added or updated"](/en-US/docs/MDN/Writing_guidelines/Page_structures/Feature_status#how_feature_statuses_are_added_or_updated) to add these statuses to the page. > diff --git a/files/en-us/mdn/writing_guidelines/page_structures/page_types/api_reference_page_template/index.md b/files/en-us/mdn/writing_guidelines/page_structures/page_types/api_reference_page_template/index.md index bcb0ad7b24b4fd9..0596f42052d435e 100644 --- a/files/en-us/mdn/writing_guidelines/page_structures/page_types/api_reference_page_template/index.md +++ b/files/en-us/mdn/writing_guidelines/page_structures/page_types/api_reference_page_template/index.md @@ -60,8 +60,8 @@ sidebar: mdnsidebar > - `\{{SecureContext_Header}}` — this generates a **Secure context** banner that indicates the technology is only available in a [secure context](/en-US/docs/Web/Security/Secure_Contexts). If it isn't, then you can remove the macro call. If it is, then you should also fill in an entry for it in the [Features restricted to secure contexts](/en-US/docs/Web/Security/Secure_Contexts/features_restricted_to_secure_contexts) page. > - `\{{AvailableInWorkers}}` — this generates a **Available In Workers** note that indicates that the technology is available in [worker context](/en-US/docs/Web/API/Web_Workers_API). > If it is only available in window context, then you can remove the macro call. -> If it is also available or only available in worker context, then you may also need to passing an parameter to it due to its availability (see [\\{{AvailableInWorkers}} macros source code](https://github.com/mdn/rari/blob/main/crates/rari-doc/src/templ/templs/banners.rs) for all available values), you may also need to fill in an entry for it in the [Web APIs available in workers](/en-US/docs/Web/API/Web_Workers_API/Functions_and_classes_available_to_workers#supported_web_apis) page. -> - `\{{APIRef("GroupDataName")}}` — this generates the left-hand reference sidebar showing quick reference links related to the current page. For example, every page in the [WebVR API](/en-US/docs/Web/API/WebVR_API) has the same sidebar, which points to the other pages in the API. To generate the correct sidebar for your API, you need to add a GroupData entry to our KumaScript GitHub repo, and include the entry's name inside the macro call in place of _GroupDataName_. See our [API reference sidebars](/en-US/docs/MDN/Writing_guidelines/Howto/Write_an_api_reference/Sidebars) guide for information on how to do this. +> If it is also available or only available in worker context, then you may also need to passing an parameter to it due to its availability (see [\\{{AvailableInWorkers}} macros source code](https://github.com/mdn/rari/blob/main/crates/rari-doc/src/templ/templs/banners.rs) for all available values), you may also need to fill in an entry for it in the [Web APIs available in workers](/en-US/docs/Web/API/Web_Workers_API/Functions_and_classes_available_to_workers#web_apis_available_in_workers) page. +> - `\{{APIRef("GroupDataName")}}` — this generates the left-hand reference sidebar showing quick reference links related to the current page. For example, every page in the [WebVR API](/en-US/docs/Web/API/WebVR_API) has the same sidebar, which points to the other pages in the API. To generate the correct sidebar for your API, you need to add a GroupData entry and include the entry's name inside the macro call in place of _GroupDataName_. See our [API reference sidebars](/en-US/docs/MDN/Writing_guidelines/Howto/Write_an_api_reference/Sidebars) guide for information on how to do this. > > Do not provide status header macros manually. Refer to the section ["How feature statuses are added or updated"](/en-US/docs/MDN/Writing_guidelines/Page_structures/Feature_status#how_feature_statuses_are_added_or_updated) to add these statuses to the page. > @@ -73,7 +73,7 @@ sidebar: mdnsidebar The summary paragraph — start by naming the interface, saying what API it is part of, and saying what it does. This should ideally be one or two short sentences. You could copy most of this from the Interface's summary on the corresponding API landing page. -{{InheritanceDiagram}} +`\{{InheritanceDiagram}}` _To use the [domxref macro](/en-US/docs/MDN/Writing_guidelines/Page_structures/Macros/Commonly_used_macros#linking_to_pages_in_references) in the sections below, remove the backticks and backslash in the markdown file._ diff --git a/files/en-us/mdn/writing_guidelines/page_structures/page_types/aria_page_template/index.md b/files/en-us/mdn/writing_guidelines/page_structures/page_types/aria_page_template/index.md index 942cd07896b4a82..33f33844ec5e6a9 100644 --- a/files/en-us/mdn/writing_guidelines/page_structures/page_types/aria_page_template/index.md +++ b/files/en-us/mdn/writing_guidelines/page_structures/page_types/aria_page_template/index.md @@ -7,15 +7,35 @@ sidebar: mdnsidebar ## Page front matter +Page metadata is described in front matter like the following example: + +```md +--- +title: aria-labelledby +slug: Web/Accessibility/ARIA/Reference/Attributes/aria-labelledby +page-type: aria-attribute +spec-urls: https://w3c.github.io/aria/#aria-labelledby +sidebar: accessibilitysidebar +--- +``` + ### Title and slug -An ARIA role page should have a `title` and `slug` of `ARIA: Name Of The Role`. For example, the [button role](/en-US/docs/Web/Accessibility/ARIA/Roles/button_role) has a `title` and `slug` of `ARIA/NameOfTheRole_role` and the [aria-labelledby](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-labelledby) attribute has a `title` of `aria-labelledby`. +An ARIA role page should have a `title` and `slug` of `ARIA: Name Of The Role`. For example, the [button role](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/button_role) has a `title` and `slug` of `ARIA/NameOfTheRole_role` and the [aria-labelledby](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-labelledby) attribute has a `title` of `aria-labelledby`. -### Top macros +### Sidebar -A number of macro calls appear at the top of the content section. You should update or delete them according to the advice below: +The `accessibilitysidebar` can be used in all pages under `/Web/Accessibility`: + +```yaml +sidebar: accessibilitysidebar +``` + +See [Page structures: Sidebars](/en-US/docs/MDN/Writing_guidelines/Page_structures/Sidebars) for details. + +### Top macros -- \\{{ariaref}}—generates a suitable ARIA sidebar, depending on what tags are included on the page. +A number of macro calls appear at the top of the content section. You should update or delete them according to the advice below. ### Statuses diff --git a/files/en-us/mdn/writing_guidelines/page_structures/page_types/css_function_page_template/index.md b/files/en-us/mdn/writing_guidelines/page_structures/page_types/css_function_page_template/index.md index 67f7130134a730d..5b456227f4ee893 100644 --- a/files/en-us/mdn/writing_guidelines/page_structures/page_types/css_function_page_template/index.md +++ b/files/en-us/mdn/writing_guidelines/page_structures/page_types/css_function_page_template/index.md @@ -24,6 +24,7 @@ sidebar: mdnsidebar > - experimental > - non-standard > browser-compat: css.types.NameOfTheFunction +> sidebar: cssref > --- > ``` > @@ -38,7 +39,10 @@ sidebar: mdnsidebar > - **status** > - : Flags describing the status of this feature. An array which may contain one or more of the following: `experimental`, `deprecated`, `non-standard`. This key should not be set manually: it is set automatically based on values in the browser compatibility data for the feature. See ["How feature statuses are added or updated"](/en-US/docs/MDN/Writing_guidelines/Page_structures/Feature_status#how_feature_statuses_are_added_or_updated). > - **browser-compat** -> - : Replace the placeholder value <code>css.types.NameOfTheFunction</code> with the query string for the function in the [Browser compat data repo](https://github.com/mdn/browser-compat-data/tree/main/css/types). Check the _Other macros in the page_ section of this note block to see how this key-value is used to generate content for the _Specifications_ and _Browser compatibility_ sections. +> - : Replace the placeholder value `css.types.NameOfTheFunction` with the query string for the function in the [Browser compat data repo](https://github.com/mdn/browser-compat-data/tree/main/css/types). Check the _Other macros in the page_ section of this note block to see how this key-value is used to generate content for the _Specifications_ and _Browser compatibility_ sections. +> - **sidebar** +> - : This is `cssref` for all CSS guide and reference pages. +> See [Page structures: Sidebars](/en-US/docs/MDN/Writing_guidelines/Page_structures/Sidebars) for details. > > --- > @@ -52,11 +56,6 @@ sidebar: mdnsidebar > - `\{{Deprecated_Header}}`: This macro generates a **Deprecated** banner, which indicates that the use of the technology is [discouraged](/en-US/docs/MDN/Writing_guidelines/Experimental_deprecated_obsolete#deprecated). > - `\{{Non-standard_Header}}` — this generates a **Non-standard** banner that indicates that the feature is not part of any specification. > -> You should update or delete the following macros according to the advice below: -> -> - `\{{CSSRef}}`: This macro must be present on every CSS page. It generates a suitable CSS sidebar, depending on the tags included on the page. -> Remember to remove the `\{{MDNSidebar}}` macro when you use this template. -> > Do not provide status header macros manually. Refer to the section ["How feature statuses are added or updated"](/en-US/docs/MDN/Writing_guidelines/Page_structures/Feature_status#how_feature_statuses_are_added_or_updated) to add these statuses to the page. > > Samples of the **Experimental**, **Deprecated**, and **Non-standard** banners are shown right after this note block. @@ -73,16 +72,16 @@ sidebar: mdnsidebar > > _Remember to remove this note block before publishing._ -{{CSSRef}}{{SeeCompatTable}}{{Deprecated_Header}}{{Non-standard_Header}} +{{SeeCompatTable}}{{Deprecated_Header}}{{Non-standard_Header}} Begin the content on the page with an introductory paragraph, which names the function and says what it does. This should ideally be one or two short sentences. ## Try it -_This title is auto-generated by the macro `\{{EmbedInteractiveExample}}`._ - -This section is for interactive examples added using the `\{{EmbedInteractiveExample}}` macro. See the [Interactive examples](/en-US/docs/MDN/Writing_guidelines/Page_structures/Code_examples#interactive_examples) section in our _Writing guidelines_ for more information. +This section is generated by the `InteractiveExample` macro. +This includes the "Try it" section title and the code editor. +See the [Interactive examples](/en-US/docs/MDN/Writing_guidelines/Page_structures/Code_examples#interactive_examples) section in our _Writing guidelines_ for more information. ## Syntax diff --git a/files/en-us/mdn/writing_guidelines/page_structures/page_types/css_module_landing_page_template/index.md b/files/en-us/mdn/writing_guidelines/page_structures/page_types/css_module_landing_page_template/index.md index 0c96ba587ab4b95..17f467368abcd4c 100644 --- a/files/en-us/mdn/writing_guidelines/page_structures/page_types/css_module_landing_page_template/index.md +++ b/files/en-us/mdn/writing_guidelines/page_structures/page_types/css_module_landing_page_template/index.md @@ -22,6 +22,7 @@ sidebar: mdnsidebar > spec-urls: > - url1 > - url2 +> sidebar: cssref > --- > ``` > @@ -44,13 +45,9 @@ sidebar: mdnsidebar > - https://drafts.fxtf.org/filter-effects-1/ > ``` > -> --- -> -> **Top-of-page macros** -> -> The `\{{CSSRef}}` macro call appears at the top of the content section (immediately after the page front matter). -> This macro must be present on every CSS module landing page. It generates a suitable CSS sidebar, depending on the tags included on the page. -> Remove the `\{{MDNSidebar}}` macro when you use this template. +> - **sidebar** +> - : This is `cssref` for all CSS guide and reference pages. +> See [Page structures: Sidebars](/en-US/docs/MDN/Writing_guidelines/Page_structures/Sidebars) for details. > > --- > diff --git a/files/en-us/mdn/writing_guidelines/page_structures/page_types/css_property_page_template/index.md b/files/en-us/mdn/writing_guidelines/page_structures/page_types/css_property_page_template/index.md index 5d912813a92bb63..a8f25306ef7dc9f 100644 --- a/files/en-us/mdn/writing_guidelines/page_structures/page_types/css_property_page_template/index.md +++ b/files/en-us/mdn/writing_guidelines/page_structures/page_types/css_property_page_template/index.md @@ -24,6 +24,7 @@ sidebar: mdnsidebar > - experimental > - non-standard > browser-compat: css.properties.NameOfTheProperty +> sidebar: cssref > --- > ``` > @@ -39,6 +40,9 @@ sidebar: mdnsidebar > - : Flags describing the status of this feature. An array which may contain one or more of the following: `experimental`, `deprecated`, `non-standard`. This key should not be set manually: it is set automatically based on values in the browser compatibility data for the feature. See ["How feature statuses are added or updated"](/en-US/docs/MDN/Writing_guidelines/Page_structures/Feature_status#how_feature_statuses_are_added_or_updated). > - **browser-compat** > - : Replace the placeholder value <code>css.properties.NameOfTheProperty</code> with the query string for the property in the [Browser compat data repo](https://github.com/mdn/browser-compat-data/tree/main/css/properties). Check the _Other macros in the page_ section of this note block to see how this key-value is used to generate content for the _Specifications_ and _Browser compatibility_ sections. +> - **sidebar** +> - : This is `cssref` for all CSS guide and reference pages. +> See [Page structures: Sidebars](/en-US/docs/MDN/Writing_guidelines/Page_structures/Sidebars) for details. > > --- > @@ -53,10 +57,7 @@ sidebar: mdnsidebar > - `\{{Non-standard_Header}}` — this generates a **Non-standard** banner that indicates that the feature is not part of any specification. > > You should update or delete the following macros according to the advice below: -> -> - `\{{CSSRef}}`: This macro must be present on every CSS property page. It generates a suitable CSS sidebar, depending on the tags included on the page. -> Remember to remove the `\{{MDNSidebar}}` macro when you use this template. -> + > Do not provide status header macros manually. Refer to the section ["How feature statuses are added or updated"](/en-US/docs/MDN/Writing_guidelines/Page_structures/Feature_status#how_feature_statuses_are_added_or_updated) to add these statuses to the page. > > Samples of the **Experimental**, **Deprecated**, and **Non-standard** banners are shown right after this note block. @@ -74,16 +75,16 @@ sidebar: mdnsidebar > > _Remember to remove this note block before publishing._ -{{CSSRef}}{{SeeCompatTable}}{{Deprecated_Header}}{{Non-standard_Header}} +{{SeeCompatTable}}{{Deprecated_Header}}{{Non-standard_Header}} Begin the content on the page with an introductory paragraph, which names the property and says what it does. This should ideally be one or two short sentences. ## Try it -_This title is auto-generated by the macro `\{{EmbedInteractiveExample}}`._ - -This section is for interactive examples added using the `\{{EmbedInteractiveExample}}` macro. See the [Interactive examples](/en-US/docs/MDN/Writing_guidelines/Page_structures/Code_examples#interactive_examples) section in our _Writing guidelines_ for more information. +This section is generated by the `InteractiveExample` macro. +This includes the "Try it" section title and the code editor. +See the [Interactive examples](/en-US/docs/MDN/Writing_guidelines/Page_structures/Code_examples#interactive_examples) section in our _Writing guidelines_ for more information. ## Constituent properties diff --git a/files/en-us/mdn/writing_guidelines/page_structures/page_types/css_selector_page_template/index.md b/files/en-us/mdn/writing_guidelines/page_structures/page_types/css_selector_page_template/index.md index 2851473a32768a2..6571c89119d5f1f 100644 --- a/files/en-us/mdn/writing_guidelines/page_structures/page_types/css_selector_page_template/index.md +++ b/files/en-us/mdn/writing_guidelines/page_structures/page_types/css_selector_page_template/index.md @@ -24,6 +24,7 @@ sidebar: mdnsidebar > - experimental > - non-standard > browser-compat: css.selectors.NameOfTheSelector +> sidebar: cssref > --- > ``` > @@ -45,12 +46,16 @@ sidebar: mdnsidebar > Note that you may first need to create/update an entry for the selector and its specification in our <a href="https://github.com/mdn/browser-compat-data">Browser compat data repo</a>. > See our [guide on how to do this](/en-US/docs/MDN/Writing_guidelines/Page_structures/Compatibility_tables). > +> - **sidebar** +> - : This is `cssref` for all CSS guide and reference pages. +> See [Page structures: Sidebars](/en-US/docs/MDN/Writing_guidelines/Page_structures/Sidebars) for details. +> > --- > > **Top-of-page macros** > -> A number of macro calls appear at the top of the content section (immediately below the page frontmatter). -> These macros are automatically added by the toolchain (there is no need to add/remove): +> A number of macros appear at the top of the content section immediately after the page front matter. +> These macros are automatically added by tooling, so avoid adding or removing them: > > - `\{{SeeCompatTable}}` — this generates a **This is an experimental technology** banner that indicates the technology is [experimental](/en-US/docs/MDN/Writing_guidelines/Experimental_deprecated_obsolete#experimental). > If it is experimental, and the technology is hidden behind a pref in Firefox, you should also fill in an entry for it in the [Experimental features in Firefox](/en-US/docs/Mozilla/Firefox/Experimental_features) page. @@ -59,9 +64,6 @@ sidebar: mdnsidebar > > You should update or delete the following macros according to the advice below: > -> - `\{{CSSRef}}` — this must be present on every CSS selector page. It generates a suitable CSS sidebar, depending on what tags are included on the page. -> Remember to remove the `\{{MDNSidebar}}` macro when you copy this page. -> > Do not provide status header macros manually. Refer to the section ["How feature statuses are added or updated"](/en-US/docs/MDN/Writing_guidelines/Page_structures/Feature_status#how_feature_statuses_are_added_or_updated) to add these statuses to the page. > > Samples of the **Experimental**, **Deprecated**, and **Non-standard** banners are shown right after this note block. @@ -76,7 +78,7 @@ sidebar: mdnsidebar > > _Remember to remove this whole explanatory note before publishing_ -{{CSSRef}}{{SeeCompatTable}}{{Deprecated_Header}}{{Non-standard_Header}} +{{SeeCompatTable}}{{Deprecated_Header}}{{Non-standard_Header}} The summary paragraph — start by naming the selector and saying what it does. This should ideally be one or two short sentences. diff --git a/files/en-us/mdn/writing_guidelines/page_structures/page_types/glossary_page_template/index.md b/files/en-us/mdn/writing_guidelines/page_structures/page_types/glossary_page_template/index.md index 43b6f5afdcef3fa..7d6a44d1255f2a4 100644 --- a/files/en-us/mdn/writing_guidelines/page_structures/page_types/glossary_page_template/index.md +++ b/files/en-us/mdn/writing_guidelines/page_structures/page_types/glossary_page_template/index.md @@ -19,6 +19,7 @@ sidebar: mdnsidebar > title: Term being defined > slug: Glossary/Term_being_defined > page-type: glossary-definition OR glossary-disambiguation +> sidebar: glossarysidebar > --- > ``` > @@ -30,6 +31,9 @@ sidebar: mdnsidebar > This will be formatted as snake case of the title: `Glossary/Term_being_defined`. > - **page-type** > - : `glossary-definition` for a definition page or `glossary-disambiguation` for a disambiguation page. +> - **sidebar** +> - : This is always `glossarysidebar`. +> See [Page structures: Sidebars](/en-US/docs/MDN/Writing_guidelines/Page_structures/Sidebars) for details. > > --- > diff --git a/files/en-us/mdn/writing_guidelines/page_structures/page_types/html_attribute_page_template/index.md b/files/en-us/mdn/writing_guidelines/page_structures/page_types/html_attribute_page_template/index.md new file mode 100644 index 000000000000000..cdb738c15bb8360 --- /dev/null +++ b/files/en-us/mdn/writing_guidelines/page_structures/page_types/html_attribute_page_template/index.md @@ -0,0 +1,169 @@ +--- +title: HTML attribute page template +slug: MDN/Writing_guidelines/Page_structures/Page_types/HTML_attribute_page_template +page-type: mdn-writing-guide +sidebar: mdnsidebar +--- + +HTML attributes fall into two categories: **element-specific attributes**, which apply only to certain elements (e.g., the `accept` attribute on `<input type="file">`), and **global attributes** which can be used for any HTML element (e.g., `class`, `id`). The former should be put under `HTML/Reference/Attributes`, while the latter should be put under `HTML/Reference/Global_attributes`. + +Note that most element-specific attributes don't need standalone articles if the attribute list in the element reference is sufficient to describe its behavior. +Only add an article if the attribute has enough nuance to deserve its own examples, or it is a global attribute. + +> **Note:** _Remove this whole explanatory note before publishing_ +> +> --- +> +> **Page front matter:** +> +> The frontmatter at the top of the page is used to define "page metadata". +> The values should be updated appropriately for the particular attribute. +> +> ```md +> --- +> title: name-of-the-attribute +> slug: Web/HTML/Reference/Global_attributes/name-of-the-attribute +> page-type: html-attribute +> status: +> - deprecated +> - experimental +> - non-standard +> browser-compat: html.global_attributes.name-of-the-attribute +> sidebar: htmlsidebar +> --- +> ``` +> +> - **title** +> - : Title heading displayed at the top of the page. +> Format as `name-of-the-attribute` (just the attribute name itself). +> For example, the [`class`](/en-US/docs/Web/HTML/Reference/Global_attributes/class) attribute has a _title_ of `class`. +> - **slug** +> - : The end of the URL path after `https://developer.mozilla.org/en-US/docs/`. +> This will be formatted like `Web/HTML/Reference/Global_attributes/name-of-the-attribute` or `Web/HTML/Reference/Attributes/name-of-the-attribute`, where the attributes name is in _lower case_. +> For example, the [`class`](/en-US/docs/Web/HTML/Reference/Global_attributes/class) attribute has a _slug_ of `Web/HTML/Reference/Global_attributes/class`. +> - **page-type** +> - : Always `html-attribute`. +> - **status** +> - : Flags describing the status of this feature. An array which may contain one or more of the following: `experimental`, `deprecated`, `non-standard`. This key should not be set manually: it is set automatically based on values in the browser compatibility data for the feature. See ["How feature statuses are added or updated"](/en-US/docs/MDN/Writing_guidelines/Page_structures/Feature_status#how_feature_statuses_are_added_or_updated). +> - **browser-compat** +> +> - : Replace the placeholder value `html.global_attributes.name-of-the-attribute` with the query string for the global attribute in the [Browser compat data repo](https://github.com/mdn/browser-compat-data). +> For element-specific attributes, use the format `html.elements.name-of-the-element.name-of-the-attribute`, with each query string on its own line, preceded by a dash. For example: +> +> ```yaml +> browser-compat: +> - html.elements.form.autocomplete +> - html.elements.input.autocomplete +> - html.elements.select.autocomplete +> - html.elements.textarea.autocomplete +> ``` +> +> The toolchain automatically uses the key to populate the compatibility and specification sections (replacing the `\{{Compat}}` and `\{{Specifications}}` macros). +> Note that you may first need to create/update an entry for the attribute in our [Browser compat data repo](https://github.com/mdn/browser-compat-data), and the entry will need to include specification information. +> See our [guide on how to do this](/en-US/docs/MDN/Writing_guidelines/Page_structures/Compatibility_tables). +> +> - **sidebar** +> - : Keep as `htmlsidebar` (all pages under `/web/html/` use this sidebar). +> See [Page structures: Sidebars](/en-US/docs/MDN/Writing_guidelines/Page_structures/Sidebars) for details. +> +> --- +> +> **Top-of-page macros** +> +> A number of macro calls appear at the top of the content section (immediately below the page frontmatter). +> These macros are automatically added by the toolchain (there is no need to add/remove): +> +> - `\{{SeeCompatTable}}` — this generates a **This is an experimental technology** banner that indicates the technology is [experimental](/en-US/docs/MDN/Writing_guidelines/Experimental_deprecated_obsolete#experimental). +> If it is experimental, and the technology is hidden behind a pref in Firefox, you should also fill in an entry for it in the [Experimental features in Firefox](/en-US/docs/Mozilla/Firefox/Experimental_features) page. +> - `\{{Deprecated_Header}}` — this generates a **Deprecated** banner that indicates that use of the technology is [discouraged](/en-US/docs/MDN/Writing_guidelines/Experimental_deprecated_obsolete#deprecated). +> - `\{{Non-standard_Header}}` — this generates a **Non-standard** banner that indicates that the feature is not part of any specification. +> +> Do not provide status header macros manually. Refer to the section ["How feature statuses are added or updated"](/en-US/docs/MDN/Writing_guidelines/Page_structures/Feature_status#how_feature_statuses_are_added_or_updated) to add these statuses to the page. +> +> Samples of the **Experimental**, **Deprecated**, and **Non-standard** banners are shown right after this note block. +> +> _Remember to remove this whole explanatory note before publishing_ +> +> {{SeeCompatTable}}{{Deprecated_Header}}{{Non-standard_Header}} +> +> Start by introducing the reader to the attribute, and its usage. +> For example: The **`name-of-the-attribute`** [global attribute](/en-US/docs/Web/HTML/Reference/Global_attributes) describes or manipulates [insert usage description]. + +## Try it + +This section is generated by the `InteractiveExample` macro. +This includes the "Try it" section title and the code editor. +See the [Interactive examples](/en-US/docs/MDN/Writing_guidelines/Page_structures/Code_examples#interactive_examples) section in our _Writing guidelines_ for more information. +If included, follow it with 1-2 brief paragraphs explaining the behavior implemented, and optionally highlighting any interaction with JavaScript, CSS, or other attributes. Keep it concise and avoid duplicating full docs — link out what needed. Again, see the `class` attribute page. + +## Values + +Provide a list of possible values for the attribute if any (remove if not applicable). Include the default value if there is one, and a brief description for each value. + +- `"value1"` + - : Description of value 1. This is the default value. +- `"value2"` + - : Description of value 2. +- `"value3"` + - : Description of value 3. + +## Accessibility + +Warn of any potential accessibility concerns that may exist with using this attribute, and how to work around them. Remove this section if there are none to list. + +## Examples + +Show relevant examples for this attribute, and how to use this attribute in practical HTML contexts. +Note that we use the plural "Examples" even if the page only contains one example. + +### A descriptive heading + +Each example must have an H3 heading (`###`) highlighting the example. The heading should be descriptive of what the example is doing. For example, "A simple example" does not say anything about the example and therefore, not a good heading. The heading should be concise. For a longer description, use the paragraph after the heading. +See our guide on how to add [code examples](/en-US/docs/MDN/Writing_guidelines/Page_structures/Code_examples) for more information. + +> [!NOTE] +> Sometimes you will want to link to examples given on another page. +> +> **Case 1:** If you have some examples on this page and some more examples on another page: +> +> Include an H3 heading (`###`) for each example on this page and then a final H3 heading (`###`) with the text "More examples", under which you can link to the examples on other pages. For example: +> +> ```md +> ## Examples +> +> ### Using the `for` attribute +> +> Example of `for` attribute +> +> ### More examples +> +> Links to more examples on other pages +> ``` +> +> **Case 2:** If you _only_ have examples on another page and none on this page: +> +> Don't add any H3 headings; just add the links directly under the H2 heading "Examples". For example: +> +> ```md +> ## Examples +> +> For examples of this attribute, see [the page on `for` attribute](https://example.org/). +> ``` + +## Specifications + +`\{{Specifications}}` +_To use this macro, remove the backticks and backslash in the markdown file._ + +## Browser compatibility + +`\{{Compat}}` +_To use this macro, remove the backticks and backslash in the markdown file._ + +## See also + +Include links to reference pages and guides related to the current attribute. For more guidelines, see the [See also section](/en-US/docs/MDN/Writing_guidelines/Writing_style_guide#see_also_section) in the _Writing style guide_. + +- link1 +- link2 +- external_link (year) diff --git a/files/en-us/mdn/writing_guidelines/page_structures/page_types/html_element_page_template/index.md b/files/en-us/mdn/writing_guidelines/page_structures/page_types/html_element_page_template/index.md index 8e38e850aac3263..51d64b633ee7eff 100644 --- a/files/en-us/mdn/writing_guidelines/page_structures/page_types/html_element_page_template/index.md +++ b/files/en-us/mdn/writing_guidelines/page_structures/page_types/html_element_page_template/index.md @@ -17,74 +17,71 @@ sidebar: mdnsidebar > ```md > --- > title: "<NameOfTheElement>: The NameOfTheElement element" -> slug: Web/HTML/Element/NameOfTheElement +> slug: Web/HTML/Reference/Elements/NameOfTheElement > page-type: html-element > status: > - deprecated > - experimental > - non-standard > browser-compat: html.elements.NameOfTheElement +> sidebar: htmlsidebar > --- > ``` > > - **title** > - : Title heading displayed at the top of the page. > Format as `'<NameOfTheElement>: Description of element's purpose'`. -> For example, the [`<video>`](/en-US/docs/Web/HTML/Element/video) element has a _title_ of: **'\<video>: The Video Embed element'**. +> For example, the [`<video>`](/en-US/docs/Web/HTML/Reference/Elements/video) element has a _title_ of: **'\<video>: The Video Embed element'**. > - **slug** > - : The end of the URL path after `https://developer.mozilla.org/en-US/docs/`. -> This will be formatted like `Web/HTML/Element/NameOfTheElement`, where the element name is in _lower case_. -> For example, the [`<video>`](/en-US/docs/Web/HTML/Element/video) element has a _slug_ of `Web/HTML/Element/video`. +> This will be formatted like `Web/HTML/Reference/Elements/NameOfTheElement`, where the element name is in _lower case_. +> For example, the [`<video>`](/en-US/docs/Web/HTML/Reference/Elements/video) element has a _slug_ of `Web/HTML/Reference/Elements/video`. > - **page-type** > - : Always `html-element`. > - **status** > - : Flags describing the status of this feature. An array which may contain one or more of the following: `experimental`, `deprecated`, `non-standard`. This key should not be set manually: it is set automatically based on values in the browser compatibility data for the feature. See ["How feature statuses are added or updated"](/en-US/docs/MDN/Writing_guidelines/Page_structures/Feature_status#how_feature_statuses_are_added_or_updated). > - **browser-compat** -> > - : Replace the placeholder value `html.elements.NameOfTheElement` with the query string for the element in the [Browser compat data repo](https://github.com/mdn/browser-compat-data). > The toolchain automatically uses the key to populate the compatibility and specification sections (replacing the `\{{Compat}}` and `\{{Specifications}}` macros). -> > Note that you may first need to create/update an entry for the element in our [Browser compat data repo](https://github.com/mdn/browser-compat-data), and the entry will need to include specification information. > See our [guide on how to do this](/en-US/docs/MDN/Writing_guidelines/Page_structures/Compatibility_tables). +> - **sidebar** +> - : This `htmlsidebar` for all HTML guide and reference pages. +> See [Page structures: Sidebars](/en-US/docs/MDN/Writing_guidelines/Page_structures/Sidebars) for details. > > --- > > **Top-of-page macros** > -> A number of macro calls appear at the top of the content section (immediately below the page frontmatter). -> These macros are automatically added by the toolchain (there is no need to add/remove): +> A number of macros appear at the top of the content section immediately after the page front matter. +> These macros are automatically added by tooling, so avoid adding or removing them: > > - `\{{SeeCompatTable}}` — this generates a **This is an experimental technology** banner that indicates the technology is [experimental](/en-US/docs/MDN/Writing_guidelines/Experimental_deprecated_obsolete#experimental). > If it is experimental, and the technology is hidden behind a pref in Firefox, you should also fill in an entry for it in the [Experimental features in Firefox](/en-US/docs/Mozilla/Firefox/Experimental_features) page. > - `\{{Deprecated_Header}}` — this generates a **Deprecated** banner that indicates that use of the technology is [discouraged](/en-US/docs/MDN/Writing_guidelines/Experimental_deprecated_obsolete#deprecated). > - `\{{Non-standard_Header}}` — this generates a **Non-standard** banner that indicates that the feature is not part of any specification. > -> You should update or delete the following macros according to the advice below: -> -> - `\{{SecureContext_Header}}` — this generates a **Secure context** banner that indicates the technology is only available in a [secure context](/en-US/docs/Web/Security/Secure_Contexts). -> If it isn't, then you can remove the macro call. -> If it is, then you should also fill in an entry for it in the [Features restricted to secure contexts](/en-US/docs/Web/Security/Secure_Contexts/features_restricted_to_secure_contexts) page. -> - `\{{HTMLSidebar}}` — this generates the left-hand-side reference sidebar for the element. -> The content of the sidebar depends on the tags in the page metadata. -> - Remember to remove the `\{{MDNSidebar}}` macro when you copy this page. +> See ["How feature statuses are added or updated"](/en-US/docs/MDN/Writing_guidelines/Page_structures/Feature_status#how_feature_statuses_are_added_or_updated) for information. > -> Do not provide status header macros manually. Refer to the section ["How feature statuses are added or updated"](/en-US/docs/MDN/Writing_guidelines/Page_structures/Feature_status#how_feature_statuses_are_added_or_updated) to add these statuses to the page. -> -> Samples of the **Experimental**, **Deprecated**, and **Non-standard** banners are shown right after this note block. +> Examples of the **Experimental**, **Deprecated**, and **Non-standard** banners are shown after this note block. > > _Remember to remove this whole explanatory note before publishing_ -{{HTMLSidebar}}{{SeeCompatTable}}{{Deprecated_Header}}{{Non-standard_Header}} +{{SeeCompatTable}}{{Deprecated_Header}}{{Non-standard_Header}} The **`<insert_the_element_name>`** [HTML](/en-US/docs/Web/HTML) element does _(insert a summary paragraph naming the element and saying what it does, ideally one or two short sentences)_. -\\{{EmbedInteractiveExample("pages/tabbed/nameOfElement.html", "tabbed-standard")}} +## Try it + +This section is generated by the `InteractiveExample` macro. +This includes the "Try it" section title and the code editor. +See the [Interactive examples](/en-US/docs/MDN/Writing_guidelines/Page_structures/Code_examples#interactive_examples) section in our _Writing guidelines_ for more information. Further information — at this point, include a few more paragraphs explaining the most important things you need to know about using the element and its main features. It is good to explain briefly what is going on in the interactive example if it is not immediately obvious. You could also explain key points about how this element interacts with important related JavaScript or CSS features. Not too much detail — you don't want to repeat the documentation across pages — but a key point plus a link to that feature's page would be useful. Again, see the `<video>` page for an example. ## Attributes -This element includes the [global attributes](/en-US/docs/Web/HTML/Global_attributes). +This element includes the [global attributes](/en-US/docs/Web/HTML/Reference/Global_attributes). - `attribute1` {{Deprecated_inline}} {{experimental_inline}} - : Include description here of what the attribute does. Include one term and definition for each attribute. If the attribute is not experimental/deprecated, remove the relevant macro calls. @@ -150,7 +147,7 @@ See our guide on how to add [code examples](/en-US/docs/MDN/Writing_guidelines/P <tbody> <tr> <th scope="row"> - <a href="/en-US/docs/Web/HTML/Content_categories" + <a href="/en-US/docs/Web/HTML/Guides/Content_categories" >Content categories</a > </th> @@ -173,7 +170,7 @@ See our guide on how to add [code examples](/en-US/docs/MDN/Writing_guidelines/P <td> What parent elements can the element be a child of? For example "Any element that accepts - <a href="/en-US/docs/Web/HTML/Content_categories#flow_content" + <a href="/en-US/docs/Web/HTML/Guides/Content_categories#flow_content" >flow content</a >." </td> @@ -182,7 +179,7 @@ See our guide on how to add [code examples](/en-US/docs/MDN/Writing_guidelines/P <th scope="row">Permitted ARIA roles</th> <td> Fill in a list of ARIA roles that can be set on the element; for example - <a href="/en-US/docs/Web/Accessibility/ARIA/Roles/directory_role"><code>directory</code></a>. + <a href="/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/directory_role"><code>directory</code></a>. </td> </tr> <tr> diff --git a/files/en-us/mdn/writing_guidelines/page_structures/page_types/http_header_page_template/index.md b/files/en-us/mdn/writing_guidelines/page_structures/page_types/http_header_page_template/index.md index 885c2919d62cde4..e6159acd031b3b4 100644 --- a/files/en-us/mdn/writing_guidelines/page_structures/page_types/http_header_page_template/index.md +++ b/files/en-us/mdn/writing_guidelines/page_structures/page_types/http_header_page_template/index.md @@ -16,28 +16,32 @@ sidebar: mdnsidebar > > ```md > --- -> title: NameOfTheHeader -> slug: Web/HTTP/Headers/NameOfTheHeader +> title: NameOfTheHeader header +> short-title: NameOfTheHeader +> slug: Web/HTTP/Reference/Headers/NameOfTheHeader > page-type: http-header > status: > - deprecated > - experimental > - non-standard > browser-compat: path.to.feature.NameOfTheHeader +> sidebar: httpsidebar > --- > ``` > > - **title** -> - : Title heading displayed at the top of the page. Format as _NameOfTheHeader_. For example, the [Cache-Control](/en-US/docs/Web/HTTP/Headers/Cache-Control) header has a _title_ of `Cache-Control`. +> - : Title heading displayed at the top of the page. Format as _NameOfTheHeader header_. For example, the [Cache-Control](/en-US/docs/Web/HTTP/Reference/Headers/Cache-Control) header has a _title_ of `Cache-Control header`. +> - **short-title** +> - : A short title used in breadcrumbs and sidebars. Format as _NameOfTheHeader_. For example, the [Cache-Control](/en-US/docs/Web/HTTP/Reference/Headers/Cache-Control) header has a _short-title_ of `Cache-Control`. > - **slug** -> - : The end of the URL path after `https://developer.mozilla.org/en-US/docs/`. This will be formatted like `Web/HTTP/Headers/NameOfTheHeader`. For example, the [Cache-Control](/en-US/docs/Web/HTTP/Headers/Cache-Control) slug is `Web/HTTP/Headers/Cache-Control`. +> - : The end of the URL path after `https://developer.mozilla.org/en-US/docs/`. This will be formatted like `Web/HTTP/Reference/Headers/NameOfTheHeader`. For example, the [Cache-Control](/en-US/docs/Web/HTTP/Reference/Headers/Cache-Control) slug is `Web/HTTP/Reference/Headers/Cache-Control`. > - **page-type** > - : For HTTP headers, must be `http-header`. For other HTTP `page-type` values, see the [HTTP section](/en-US/docs/MDN/Writing_guidelines/Page_structures/Page_types/Page_type_key#http_page_types) of the documentation for the `page-type` front matter key. > - **status** > - : Flags describing the status of this feature. An array which may contain one or more of the following: `experimental`, `deprecated`, `non-standard`. This key should not be set manually: it is set automatically based on values in the browser compatibility data for the feature. See ["How feature statuses are added or updated"](/en-US/docs/MDN/Writing_guidelines/Page_structures/Feature_status#how_feature_statuses_are_added_or_updated). > - **browser-compat** > -> - : Replace the placeholder value <code>path.to.feature.NameOfTheHeader</code> with the query string for the header in the [Browser compat data repo](https://github.com/mdn/browser-compat-data). +> - : Replace the placeholder value `path.to.feature.NameOfTheHeader` with the query string for the header in the [Browser compat data repo](https://github.com/mdn/browser-compat-data). > The toolchain automatically uses the key to populate the compatibility section (replacing the `\{{Compat}}` macro). > > Note that you may first need to create/update an entry for the HTTP header in our <a href="https://github.com/mdn/browser-compat-data">Browser compat data repo</a>, and the entry for the header will need to include specification information. @@ -46,36 +50,35 @@ sidebar: mdnsidebar > Browser compatibility does not apply for HTTP headers where no specific implementation is provided (such as automatically adding a request header to some requests or changing behavior based on data in a response header). > For these cases, remove the browser-compat key and value. > +> - **sidebar** +> - : This is always `httpsidebar`. +> See [Page structures: Sidebars](/en-US/docs/MDN/Writing_guidelines/Page_structures/Sidebars) for details. +> > --- > > **Top-of-page macros** > -> A number of macro calls appear at the top of the content section (immediately below the page frontmatter). -> These macros are automatically added by the toolchain (there is no need to add/remove): +> A number of macros appear at the top of the content section immediately after the page front matter. +> These macros are automatically added by tooling, so avoid adding or removing them: > > - `\{{SeeCompatTable}}` — this generates a **This is an experimental technology** banner that indicates the header is [experimental](/en-US/docs/MDN/Writing_guidelines/Experimental_deprecated_obsolete#experimental). > If it is experimental, and the technology is hidden behind a pref in Firefox, you should also fill in an entry for it in the [Experimental features in Firefox](/en-US/docs/Mozilla/Firefox/Experimental_features) page. > - `\{{deprecated_header}}` — this generates a **Deprecated** banner that indicates that use of the header is [discouraged](/en-US/docs/MDN/Writing_guidelines/Experimental_deprecated_obsolete#deprecated). > - `\{{Non-standard_Header}}` — this generates a **Non-standard** banner that indicates that the feature is not part of any specification. > -> You should update or delete the following macros according to the advice below: -> -> - `\{{httpsidebar}}` — this generates the HTTP sidebar that must appear on every HTTP reference page. -> Remember to remove the `\{{MDNSidebar}}` macro when you copy this page. -> > Do not provide status header macros manually. Refer to the section ["How feature statuses are added or updated"](/en-US/docs/MDN/Writing_guidelines/Page_structures/Feature_status#how_feature_statuses_are_added_or_updated) to add these statuses to the page. > > Samples of the **Experimental**, **Deprecated**, and **Non-standard** banners are shown right after this note block. > > _Remember to remove this whole explanatory note before publishing_ -{{httpsidebar}}{{SeeCompatTable}}{{Deprecated_Header}}{{Non-standard_Header}} +{{SeeCompatTable}}{{Deprecated_Header}}{{Non-standard_Header}} The first sentence of the page must follow this format: > The HTTP **`header-name`** (header type) is used for X in Y circumstances. -The 'header type' should say if it's a {{Glossary("Request_header", "request header")}}, a {{Glossary("Response_header", "response header")}}, or if it may be either. +The 'header type' should say if it's a {{Glossary("request header")}}, a {{Glossary("response header")}}, or if it may be either. The summary paragraph should ideally be one or two short sentences. You can mention notable gotchas or common pitfalls in this section, linking to examples or more detailed documentation (guides, etc.) in this section. @@ -89,7 +92,7 @@ Two or three paragraphs in this section is appropriate, and if there are substan Include header category (or categories), e.g. {{Glossary("Request header")}}, {{Glossary("Response header")}}, - <a href="/en-US/docs/Web/HTTP/Client_hints">Client hint</a> + <a href="/en-US/docs/Web/HTTP/Guides/Client_hints">Client hint</a> </td> </tr> <tr> @@ -108,13 +111,18 @@ Two or three paragraphs in this section is appropriate, and if there are substan ## Syntax Fill in a syntax box, like the one below, according to the guidance in our [syntax sections](/en-US/docs/MDN/Writing_guidelines/Page_structures/Syntax_sections) article. -If the header has a lot of available directives, feel free to include multiple syntax boxes, subsections and explanations as appropriate. ```http NameOfTheHeader: <directive1> NameOfTheHeader: <directive1>, <directive2>, … ``` +If the header has a lot of available directives, feel free to include multiple syntax boxes, subsections and explanations as appropriate: + +```http +NameOfTheHeader: <directive3>, …, <directiveN> +``` + The directives are case-insensitive and have an optional argument, that can use both token and quoted-string syntax. Multiple directives are comma-separated (delete information as appropriate). @@ -132,6 +140,7 @@ feel free to include multiple definition lists, subsections, and explanations as ## Description If there is too much content to include in the opening paragraphs, provide as much detail as necessary here, such as background information, hints for usage, and links to documentation. +This is a good place to note whether real-world patterns differ from what's specified if widely-deployed implementations deviate from what's described in specifications. ## Examples @@ -192,8 +201,9 @@ Developers can set and get HTTP headers using `fetch()` in order to provide appl ## See also -Include links to reference pages and guides related to the current HTTP header. For more guidelines, see the [See also section](/en-US/docs/MDN/Writing_guidelines/Writing_style_guide#see_also_section) in the _Writing style guide_. -You can link to relevant response statuses like `\{{HTTPStatus("123", "123 Response Status")}}` and headers like `\{{HTTPHeader("Header-Name")}}`. +Include links to reference pages and guides related to the current HTTP header. +For more guidelines, see the [See also section](/en-US/docs/MDN/Writing_guidelines/Writing_style_guide#see_also_section) in the _Writing style guide_. +You can link to relevant response statuses like `\{{HTTPStatus("123", "123 Reason")}}` and headers like `\{{HTTPHeader("Header-Name")}}`. You may group related statuses and headers in a single list item for brevity. - link1 diff --git a/files/en-us/mdn/writing_guidelines/page_structures/page_types/index.md b/files/en-us/mdn/writing_guidelines/page_structures/page_types/index.md index 2f7fd09337f411a..6b87dc5e5e07692 100644 --- a/files/en-us/mdn/writing_guidelines/page_structures/page_types/index.md +++ b/files/en-us/mdn/writing_guidelines/page_structures/page_types/index.md @@ -24,7 +24,7 @@ When creating a new page you can ensure that you've used the right page structur You can find the exact source code of each template (if you want to copy it) by following the "Source on **GitHub**" link at the bottom of each one. These page templates don't make much sense as published pages, but if you view their source code you'll see that they contain a lot of helpful comments, placeholders, and hints detailing how to fill in the missing information and create your page. -At the top of each template you'll find a section entitled _Remove before publishing_ — this contains information on how to fill in the page title, slug, sidebar menu, and tags (e.g. information that doesn't actually appear in the body of the article). +At the top of each template you'll find a section entitled _Remove before publishing_ — this contains information on how to fill in the page title, slug, sidebar menu, and tags (e.g., information that doesn't actually appear in the body of the article). You need to delete this section after you've followed the instructions in it, before the page can be considered finished. ## Old-style page layouts @@ -57,11 +57,13 @@ Below are examples of the various pages you'll find on MDN along with templates - [API landing pages](#api_landing_page) - [API reference page](#api_reference_page) - [API reference subpage](#api_reference_subpage) +- [ARIA reference](#aria_reference_page) - [Conceptual pages](#conceptual_page) - [CSS feature reference](#css_feature_reference_page) - [CSS module landing page](#css_module_landing_page) - [Glossary entry](#glossary_page) - [HTML element](#html_element_reference_page) +- [HTML attribute](#html_attribute_reference_page) - [HTTP header](#http_header_reference_page) - [Landing page](#landing_page) - [SVG element](#svg_element_reference_page) @@ -76,7 +78,7 @@ It does not link directly to specific methods or properties within the API's cla It is primarily a _navigation_ page, but also functions as an at-a-glance _reference_ page for the API. There are some instances where multiple APIs exist that are distinct, and are defined in their own specifications, but they closely related and therefore would make sense to cover with a single API landing page. -For example, the [Generic Sensor API](https://www.w3.org/TR/generic-sensor/) cover general sensor concerns, but more specific concerns are covered in other APIs such as [Ambient Light Sensor](https://www.w3.org/TR/ambient-light/), [Motion Sensor](https://www.w3.org/TR/motion-sensors/), etc. +For example, the [Generic Sensor API](https://w3c.github.io/sensors/) cover general sensor concerns, but more specific concerns are covered in other APIs such as [Ambient Light Sensor](https://w3c.github.io/ambient-light/), [Motion Sensor](https://w3c.github.io/motion-sensors/), etc. In such cases, many of the high level concepts are the same, so it makes no sense to repeat those over multiple landing pages. In such a case, it would make more sense in terms of repetition and findability to cover them all under a single "Web sensors" landing page. @@ -130,19 +132,34 @@ An **HTML reference page** lists all the attributes that are available on an HTM #### Example -- [`<video>` element](/en-US/docs/Web/HTML/Element/video) +- [`<video>` element](/en-US/docs/Web/HTML/Reference/Elements/video) #### Templates - [HTML element page template](/en-US/docs/MDN/Writing_guidelines/Page_structures/Page_types/HTML_element_page_template) +### HTML attribute reference page + +An HTML attribute page lists all the values that exist on an HTML attribute, explains the attribute's purpose and use cases, providing examples, browser compatibility information, and other important data. + +> [!NOTE] +> Element-specific attributes (e.g., `placeholder` for `<input>`) don't require a separate page if the attributes can be sufficiently covered within the parent element's reference page (e.g., the `placeholder` attribute should be covered on the `<input>` element's page, not as a standalone page). + +#### Example + +- [`class` attribute](/en-US/docs/Web/HTML/Reference/Global_attributes/class) + +#### Templates + +- [HTML attribute page template](/en-US/docs/MDN/Writing_guidelines/Page_structures/Page_types/HTML_attribute_page_template) + ### SVG element reference page An **SVG reference page** lists all the attributes that are available on an SVG element, explains the element's purpose and usage, and provides examples, browser compatibility information, and other important data. #### Example -- [\<g> element](/en-US/docs/Web/SVG/Element/g) +- [\<g> element](/en-US/docs/Web/SVG/Reference/Element/g) #### Templates @@ -192,12 +209,25 @@ It also provides examples, browser compatibility information, and other importan #### Example -- [Cache-Control header](/en-US/docs/Web/HTTP/Headers/Cache-Control) +- [Cache-Control header](/en-US/docs/Web/HTTP/Reference/Headers/Cache-Control) #### Templates - [HTTP header page template](/en-US/docs/MDN/Writing_guidelines/Page_structures/Page_types/HTTP_header_page_template) +### ARIA reference page + +An **ARIA reference page** describes a [role](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles) or [attribute](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes) that defines ways to make web content and web applications more accessible to people with disabilities. + +#### Examples + +- [`aria-busy` attribute](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-busy) +- [`application` role](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/application_role) + +#### Templates + +- [ARIA page template](/en-US/docs/MDN/Writing_guidelines/Page_structures/Page_types/ARIA_Page_Template) + ### Conceptual page A **conceptual page** is a _guide_ page that explains or teaches something. @@ -260,4 +290,4 @@ There are only a few types of page inside Learn web development: ## See also - [Page components](/en-US/docs/MDN/Writing_guidelines/Writing_style_guide#page_components) -- [Creating code examples in markdown](/en-US/docs/MDN/Writing_guidelines/Writing_style_guide/Code_style_guide) +- [Creating code examples in markdown](/en-US/docs/MDN/Writing_guidelines/Code_style_guide) diff --git a/files/en-us/mdn/writing_guidelines/page_structures/page_types/page_type_key/index.md b/files/en-us/mdn/writing_guidelines/page_structures/page_types/page_type_key/index.md index a94b296e3c22c7a..d829f2572175988 100644 --- a/files/en-us/mdn/writing_guidelines/page_structures/page_types/page_type_key/index.md +++ b/files/en-us/mdn/writing_guidelines/page_structures/page_types/page_type_key/index.md @@ -12,10 +12,11 @@ Like any other front matter key, the `page-type` key is specified in the YAML at ```md --- -title: Geolocation.getCurrentPosition() -slug: Web/API/Geolocation/getCurrentPosition -page-type: web-api-instance-method -browser-compat: api.Geolocation.getCurrentPosition +title: 100 Continue +slug: Web/HTTP/Reference/Status/100 +page-type: http-status-code +spec-urls: https://www.rfc-editor.org/rfc/rfc9110#status.100 +sidebar: httpsidebar --- ``` @@ -43,15 +44,15 @@ This section lists `page-type` values for pages under [Learn](/en-US/docs/Learn_ - `learn-topic`: an overview of a topic, that is, a collection of modules like [_CSS_](/en-US/docs/Learn_web_development/Core/Styling_basics). - `learn-module` an overview of a module, that is, an ordered collection of guides, like [_Structuring content with HTML_](/en-US/docs/Learn_web_development/Core/Structuring_content). - `learn-module-chapter` a guide that is part of a module, like [_Mobile accessibility_](/en-US/docs/Learn_web_development/Core/Accessibility/Mobile). -- `learn-module-assessment` a special guide with an activity allowing to assess the comprehension of a module or a part of it, like [_Test your skills: basic controls_](/en-US/docs/Learn_web_development/Extensions/Forms/Test_your_skills:_Basic_controls). +- `learn-module-assessment` a special guide with an activity allowing to assess the comprehension of a module or a part of it, like [_Test your skills: basic controls_](/en-US/docs/Learn_web_development/Extensions/Forms/Test_your_skills/Basic_controls). - `learn-faq`: the answer to a specific question about web development, like [_What is a domain name?_](/en-US/docs/Learn_web_development/Howto/Web_mechanics/What_is_a_domain_name). ### Accessibility page types This section lists `page-type` values for pages under [Web/Accessibility](/en-US/docs/Web/Accessibility). Every page in that part of the tree must have a `page-type`, and its value must be one of those listed below or one of the [generic page type](#generic_page_types) values. -- `aria-role`: an ARIA [role](/en-US/docs/Web/Accessibility/ARIA/Roles), like [`section`](/en-US/docs/Web/Accessibility/ARIA/Roles/section_role). -- `aria-attribute`: an ARIA [attribute](/en-US/docs/Web/Accessibility/ARIA/Attributes), like [`aria-sort`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-sort). +- `aria-role`: an ARIA [role](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles), like [`section`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/section_role). +- `aria-attribute`: an ARIA [attribute](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes), like [`aria-sort`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-sort). ### CSS page types @@ -82,20 +83,20 @@ This section lists `page-type` values for pages under [Glossary](/en-US/docs/Glo This section lists `page-type` values for pages under [Web/HTML](/en-US/docs/Web/HTML). Every page in that part of the tree must have a `page-type`, and its value must be one of those listed below or one of the [generic page type](#generic_page_types) values. -- `html-attribute`: an HTML attribute, like [`autocomplete`](/en-US/docs/Web/HTML/Attributes/autocomplete). -- `html-attribute-value`: a single value for an HTML attribute, like [`dns-prefetch`](/en-US/docs/Web/HTML/Attributes/rel/dns-prefetch). -- `html-element`: an HTML element, like [`<button>`](/en-US/docs/Web/HTML/Element/button). +- `html-attribute`: an HTML attribute, like [`autocomplete`](/en-US/docs/Web/HTML/Reference/Attributes/autocomplete). +- `html-attribute-value`: a single value for an HTML attribute, like [`dns-prefetch`](/en-US/docs/Web/HTML/Reference/Attributes/rel/dns-prefetch). +- `html-element`: an HTML element, like [`<button>`](/en-US/docs/Web/HTML/Reference/Elements/button). ### HTTP page types This section lists `page-type` values for pages under [Web/HTTP](/en-US/docs/Web/HTTP). Every page in that part of the tree must have a `page-type`, and its value must be one of those listed below or one of the [generic page type](#generic_page_types) values. -- `http-csp-directive`: a [CSP](/en-US/docs/Web/HTTP/Headers/Content-Security-Policy) directive, like [`script-src`](/en-US/docs/Web/HTTP/Headers/Content-Security-Policy/script-src). -- `http-cors-error`: a [CORS](/en-US/docs/Web/HTTP/CORS) error, like [`CORSDidNotSucceed`](/en-US/docs/Web/HTTP/CORS/Errors/CORSDidNotSucceed). -- `http-permissions-policy-directive`: a [`Permissions-Policy`](/en-US/docs/Web/HTTP/Headers/Permissions-Policy) directive, like [`accelerometer`](/en-US/docs/Web/HTTP/Headers/Permissions-Policy/accelerometer). -- `http-header`: an [HTTP header](/en-US/docs/Web/HTTP/Headers), like [`Referer`](/en-US/docs/Web/HTTP/Headers/Referer). -- `http-method`: an [HTTP request method](/en-US/docs/Web/HTTP/Methods) like [`GET`](/en-US/docs/Web/HTTP/Methods/GET). -- `http-status-code`: an [HTTP response status code](/en-US/docs/Web/HTTP/Status), like [`404`](/en-US/docs/Web/HTTP/Status/404). +- `http-csp-directive`: a [CSP](/en-US/docs/Web/HTTP/Reference/Headers/Content-Security-Policy) directive, like [`script-src`](/en-US/docs/Web/HTTP/Reference/Headers/Content-Security-Policy/script-src). +- `http-cors-error`: a [CORS](/en-US/docs/Web/HTTP/Guides/CORS) error, like [`CORSDidNotSucceed`](/en-US/docs/Web/HTTP/Guides/CORS/Errors/CORSDidNotSucceed). +- `http-permissions-policy-directive`: a [`Permissions-Policy`](/en-US/docs/Web/HTTP/Reference/Headers/Permissions-Policy) directive, like [`accelerometer`](/en-US/docs/Web/HTTP/Reference/Headers/Permissions-Policy/accelerometer). +- `http-header`: an [HTTP header](/en-US/docs/Web/HTTP/Reference/Headers), like [`Referer`](/en-US/docs/Web/HTTP/Reference/Headers/Referer). +- `http-method`: an [HTTP request method](/en-US/docs/Web/HTTP/Reference/Methods) like [`GET`](/en-US/docs/Web/HTTP/Reference/Methods/GET). +- `http-status-code`: an [HTTP response status code](/en-US/docs/Web/HTTP/Reference/Status), like [`404`](/en-US/docs/Web/HTTP/Reference/Status/404). ### JavaScript page types @@ -121,15 +122,15 @@ This section lists `page-type` values for pages under [Web/JavaScript](/en-US/do This section lists `page-type` values for pages under [Web/MathML](/en-US/docs/Web/MathML). Every page in that part of the tree must have a `page-type`, and its value must be one of those listed below or one of the [generic page type](#generic_page_types) values. -- `mathml-attribute`: an MathML attribute, like [`mathcolor`](/en-US/docs/Web/MathML/Global_attributes/mathcolor). -- `mathml-element`: an HTML element, like [`<msqrt>`](/en-US/docs/Web/MathML/Element/msqrt). +- `mathml-attribute`: an MathML attribute, like [`mathcolor`](/en-US/docs/Web/MathML/Reference/Global_attributes/mathcolor). +- `mathml-element`: an HTML element, like [`<msqrt>`](/en-US/docs/Web/MathML/Reference/Element/msqrt). ### SVG page types This section lists `page-type` values for pages under [Web/SVG](/en-US/docs/Web/SVG). Every page in that part of the tree must have a `page-type`, and its value must be one of those listed below or one of the [generic page type](#generic_page_types) values. -- `svg-attribute`: an SVG attribute, like [`crossorigin`](/en-US/docs/Web/SVG/Attribute/crossorigin). -- `svg-element`: an SVG element, like [`<circle>`](/en-US/docs/Web/SVG/Element/circle). +- `svg-attribute`: an SVG attribute, like [`crossorigin`](/en-US/docs/Web/SVG/Reference/Attribute/crossorigin). +- `svg-element`: an SVG element, like [`<circle>`](/en-US/docs/Web/SVG/Reference/Element/circle). ### Web API page types @@ -199,7 +200,7 @@ This section lists `page-type` values for pages under [Web/XSLT](/en-US/docs/Web This section lists `page-type` values for pages under [Web/EXSLT](/en-US/docs/Web/XML/EXSLT). Every page in that part of the tree must have a `page-type`, and its value must be one of those listed below or one of the [generic page type](#generic_page_types) values. -- `xslt-function`: a function of EXSLT, like [`exsl:node-set()`](/en-US/docs/Web/XML/EXSLT/exsl/node-set). +- `xslt-function`: a function of EXSLT, like [`exsl:node-set()`](/en-US/docs/Web/XML/EXSLT/Reference/exsl/node-set). ### Firefox page types diff --git a/files/en-us/mdn/writing_guidelines/page_structures/page_types/svg_element_page_template/index.md b/files/en-us/mdn/writing_guidelines/page_structures/page_types/svg_element_page_template/index.md index 271cebd93fc9b7e..84acf5d69dd49e0 100644 --- a/files/en-us/mdn/writing_guidelines/page_structures/page_types/svg_element_page_template/index.md +++ b/files/en-us/mdn/writing_guidelines/page_structures/page_types/svg_element_page_template/index.md @@ -17,23 +17,24 @@ sidebar: mdnsidebar > ```md > --- > title: <NameOfTheElement> -> slug: Web/SVG/Element/NameOfTheElement +> slug: Web/SVG/Reference/Element/NameOfTheElement > page-type: svg-element > status: > - deprecated > - experimental > - non-standard > browser-compat: svg.elements.NameOfTheElement +> sidebar: svgref > --- > ``` > > - **title** > - : Title heading displayed at the top of the page. > Format as **<**_NameOfTheElement_**>**. -> For example, the "[g](/en-US/docs/Web/SVG/Element/g)" element has a _title_ of `<g>`. +> For example, the "[g](/en-US/docs/Web/SVG/Reference/Element/g)" element has a _title_ of `<g>`. > - **slug** > - : The end of the URL path after `https://developer.mozilla.org/en-US/docs/`. -> This will be formatted like `Web/SVG/Element/NameOfTheElement`. +> This will be formatted like `Web/SVG/Reference/Element/NameOfTheElement`. > - **page-type** > - : Always `svg-element`. > - **status** @@ -46,34 +47,29 @@ sidebar: mdnsidebar > Note that you may first need to create/update an entry for the element in our [Browser compat data repo](https://github.com/mdn/browser-compat-data), and the entry will need to include specification information. > See our [guide on how to do this](/en-US/docs/MDN/Writing_guidelines/Page_structures/Compatibility_tables). > +> - **sidebar** +> - : This is `svgref` for all SVG guide and reference pages. +> See [Page structures: Sidebars](/en-US/docs/MDN/Writing_guidelines/Page_structures/Sidebars) for details. +> > --- > > **Top-of-page macros** > -> A number of macro calls appear at the top of the content section (immediately below the page frontmatter). -> These macros are automatically added by the toolchain (there is no need to add/remove): +> A number of macros appear at the top of the content section immediately after the page front matter. +> These macros are automatically added by tooling, so avoid adding or removing them: > > - `\{{SeeCompatTable}}` — this generates a **This is an experimental technology** banner that indicates the technology is [experimental](/en-US/docs/MDN/Writing_guidelines/Experimental_deprecated_obsolete#experimental). > If it is experimental, and the technology is hidden behind a pref in Firefox, you should also fill in an entry for it in the [Experimental features in Firefox](/en-US/docs/Mozilla/Firefox/Experimental_features) page. > - `\{{Deprecated_Header}}` — this generates a **Deprecated** banner that indicates that use of the technology is [discouraged](/en-US/docs/MDN/Writing_guidelines/Experimental_deprecated_obsolete#deprecated). > - `\{{Non-standard_Header}}` — this generates a **Non-standard** banner that indicates that the feature is not part of any specification. > -> You should update or delete the following macros according to the advice below: -> -> - `\{{SecureContext_Header}}` — this generates a **Secure context** banner that indicates the technology is only available in a [secure context](/en-US/docs/Web/Security/Secure_Contexts). -> If it isn't, then you can remove the macro call. -> If it is, then you should also fill in an entry for it in the [Features restricted to secure contexts](/en-US/docs/Web/Security/Secure_Contexts/features_restricted_to_secure_contexts) page. -> - `\{{SVGRef}}` — this generates the left-hand-side reference sidebar for the element. -> The content of the sidebar depends on the tags in the page metadata. -> - Remember to remove the `\{{MDNSidebar}}` macro when you copy this page. -> -> Do not provide status header macros manually. Refer to the section ["How feature statuses are added or updated"](/en-US/docs/MDN/Writing_guidelines/Page_structures/Feature_status#how_feature_statuses_are_added_or_updated) to add these statuses to the page. +> See ["How feature statuses are added or updated"](/en-US/docs/MDN/Writing_guidelines/Page_structures/Feature_status#how_feature_statuses_are_added_or_updated) for information. > -> Samples of the **Experimental**, **Deprecated**, and **Non-standard** banners are shown right after this note block. +> Examples of the **Experimental**, **Deprecated**, and **Non-standard** banners are shown after this note block. > > _Remember to remove this whole explanatory note before publishing_ -{{SVGRef}}{{SeeCompatTable}}{{Deprecated_Header}}{{Non-standard_Header}} +{{SeeCompatTable}}{{Deprecated_Header}}{{Non-standard_Header}} Begin the content on the page with an introductory paragraph — start by naming the element and saying what it does. This should ideally be one or two short sentences. @@ -90,9 +86,9 @@ _To use this macro, remove the backticks and backslash in the markdown file._ ### Global attributes -- [Generic attributes](/en-US/docs/Web/SVG/Attribute#generic_attributes) -- [Event attributes](/en-US/docs/Web/SVG/Attribute#event_attributes) -- [Presentation attributes](/en-US/docs/Web/SVG/Attribute#presentation_attributes) +- [Generic attributes](/en-US/docs/Web/SVG/Reference/Attribute#generic_attributes) +- [Event attributes](/en-US/docs/Web/SVG/Reference/Attribute#event_attributes) +- [Presentation attributes](/en-US/docs/Web/SVG/Reference/Attribute#presentation_attributes) - {{SVGAttr("class")}} - {{SVGAttr("style")}} - {{SVGAttr("transform")}} @@ -105,7 +101,7 @@ _To use this macro, remove the backticks and backslash in the markdown file._ ## DOM Interface -This element implements the `\{{domxref("NameOfSVGDOMElement")}}` interface. +This element implements the `\{{domxref("NameOfSVGElement")}}` interface. ## Examples diff --git a/files/en-us/mdn/writing_guidelines/page_structures/sidebars/index.md b/files/en-us/mdn/writing_guidelines/page_structures/sidebars/index.md index 41aaa38accd24f9..f6c791cc13aa5a5 100644 --- a/files/en-us/mdn/writing_guidelines/page_structures/sidebars/index.md +++ b/files/en-us/mdn/writing_guidelines/page_structures/sidebars/index.md @@ -5,9 +5,10 @@ page-type: mdn-writing-guide sidebar: mdnsidebar --- -MDN pages all include sidebars. Most of them are created using a standard system that defines data structures in YAML files, and includes sidebars on pages using macro calls. +All MDN pages should have sidebars. +Most of them are created using a system that defines data structures in YAML files, and includes sidebars on pages via front matter or a macro. -In this guide, you will learn how these sidebars work so you can edit existing sidebars and create new ones as required. We'll also detail those that don't yet use the standard system. +In this guide, you will learn how these sidebars work so you can edit existing sidebars and create new ones as required. > [!NOTE] > If you're editing sidebars, you can use `yarn tool` commands for formatting and syncing with redirects. @@ -17,55 +18,25 @@ In this guide, you will learn how these sidebars work so you can edit existing s Each sidebar has a corresponding YAML file contained inside the MDN `content` repo's [`files/sidebars`](https://github.com/mdn/content/tree/main/files/sidebars) directory. This defines the hierarchical structure of the sidebar links, the URLs each link should point to, and optional custom heading/link text, which can be localized into different languages as required. -If we take as an example the page you are currently looking at, the sidebar structure is defined in the [`mdnsidebar.yaml`](https://github.com/mdn/content/blob/main/files/sidebars/mdnsidebar.yaml) file. +The page you are currently reading has a sidebar defined in the [`mdnsidebar.yaml`](https://github.com/mdn/content/blob/main/files/sidebars/mdnsidebar.yaml) file. -The sidebar is rendered on the current page (and all others in the same document tree) by including a corresponding macro call — `\{{MDNSidebar}}` — just below the frontmatter in the [document source](https://raw.githubusercontent.com/mdn/content/refs/heads/main/files/en-us/mdn/writing_guidelines/page_structures/sidebars/index.md): +The sidebar is rendered on the current page (and all others in the same document tree) by including a `sidebar` front matter entry in the [document source](https://raw.githubusercontent.com/mdn/content/refs/heads/main/files/en-us/mdn/writing_guidelines/page_structures/sidebars/index.md): ```md --- title: Sidebars slug: MDN/Writing_guidelines/Page_structures/Sidebars page-type: mdn-writing-guide +sidebar: mdnsidebar --- -\{{MDNSidebar}} +All MDN pages should have sidebars. ``` -The frontmatter is the content between the dashes. Including the `\{{MDNSidebar}}` macro call in the source causes the system to look for a YAML file with the same name inside the `files/sidebars` directory. If it finds one, it automatically takes care of rendering the sidebar and placing it on the page as one or more ordered lists ({{htmlelement("ol")}} elements). +The front matter is the content between the dashes. Including `sidebar: mdnsidebar` in the front matter causes the system to look for a YAML file with the same name inside the `files/sidebars` directory. If it finds one, it automatically takes care of rendering the sidebar and placing it on the page as one or more ordered lists ({{htmlelement("ol")}} elements). Try navigating around the sidebar, before returning to this page. You'll notice that generally when navigating to a page, the link list for the section you are currently in will be expanded, whereas the others will be collapsed, and the page you are on is highlighted. -## Standard sidebar examples - -Some of the other standard sidebars that you will commonly encounter are as follows: - -- `\{{CSSRef}}` - - - : Present on every [CSS](/en-US/docs/Web/CSS) page. - -- `\{{GlossarySidebar}}` - - - : Present on every [glossary](/en-US/docs/Glossary) page. - -- `\{{LearnSidebar}}` - - - : Present on every page within the [Learn web development section](/en-US/docs/Learn_web_development). - -- `\{{HTMLSidebar}}` - - - : Generates the sidebar for [HTML](/en-US/docs/Web/HTML) documentation. - -- `\{{HTTPSidebar}}` - - - : Generates the sidebar for [HTTP documentation](/en-US/docs/Web/HTTP). - -- `\{{PWASidebar}}` - - - : Generates the sidebar for [progressive web app (PWA)](/en-US/docs/Web/Progressive_web_apps) documentation. - -> [!NOTE] -> The appropriate macro to use depends on the [page type](/en-US/docs/MDN/Writing_guidelines/Page_structures/Page_types). The [template](/en-US/docs/MDN/Writing_guidelines/Page_structures/Page_types#page_templates) for each page type includes the appropriate macro for that page type. - ## Sidebar YAML syntax explained This section explains the different features that can be included in MDN sidebars, and the YAML syntax used to generate each one. As you work through this documentation, cross-reference the features against the [existing sidebar YAML](https://github.com/mdn/content/tree/main/files/sidebars). @@ -79,23 +50,24 @@ sidebar: # sidebar definition goes here ``` -### Basic single links +### Single links -To create a basic single link in a sidebar, you include a YAML list item containing a relative URL: +To create a single link in a sidebar, you include a YAML list item containing a relative URL: ```yaml sidebar: - - /MDN/Changelog + - /MDN/Writing_guidelines/Page_structures/Sidebars ``` -The URL is relative to the `docs` directory in the MDN URL structure, so for example, `/MDN/Changelog` would generate a link to https://developer.mozilla.org/en-US/docs/MDN/Changelog. The system automatically uses the linked page's document title as the link text. +The URL is relative to the `docs` directory in the MDN URL structure, so for example, `/MDN/Writing_guidelines/Page_structures/Sidebars` would generate a link to the current page. The system automatically uses the linked page's document title as the link text. +If the page has a `short-title` key in the front matter, that will be used for the sidebar link display text instead. -If you want to use custom link text, you need to include two keys inside the list item — `title`, which contains the custom link text, and `link`, which contains the relative URL as before. The following example would create a link to the MDN Web Docs changelog as before, but with custom link text of "Our changelog": +If you want to use custom link text that's not a document's `title` or `short-title`, you need to include two keys inside the list item — `title`, which contains the custom link text, and `link`, which contains the relative URL as before. The following example would create a link to the current page as before, but with custom link text of "Writing sidebars": ```yaml sidebar: - - title: Our changelog - link: /MDN/Changelog + - title: Writing sidebars + link: /MDN/Writing_guidelines/Page_structures/Sidebars ``` ### Section titles @@ -142,16 +114,10 @@ sidebar: children: - /MDN/Community - /MDN/Community/Getting_started - - /MDN/Community/Our_repositories - - /MDN/Community/Translated_content - - /MDN/Community/Security_vulnerability_response - /MDN/Community/Open_source_etiquette - /MDN/Community/Communication_channels - /MDN/Community/Discussions - - /MDN/Community/Learn_forum - - /MDN/Community/Issues - - /MDN/Community/Pull_requests - - /MDN/Community/Roles_teams +# etc. ``` Note also the `details` key — this controls whether a list item's list of children is rendered closed or open when the page first loads. Possible values are as follows: @@ -249,36 +215,7 @@ If you have several different page types inside the same directory (as specified title: Selectors tags: css-selector details: closed -- type: listSubPages - path: /Web/CSS - title: Combinators - tags: css-combinator - details: closed -- type: listSubPages - path: /Web/CSS - title: Pseudo-classes - tags: css-pseudo-class - details: closed -- type: listSubPages - path: /Web/CSS - title: Pseudo-elements - tags: css-pseudo-element - details: closed -- type: listSubPages - path: /Web/CSS - title: At-rules - tags: css-at-rule - details: closed -- type: listSubPages - path: /Web/CSS - title: Functions - tags: css-function - details: closed -- type: listSubPages - path: /Web/CSS - title: Types - tags: css-type - details: closed +# etc. ``` ### Localizing text strings @@ -289,7 +226,7 @@ Let's look at an example to show what this looks like. In the [HTML](/en-US/docs ```yaml - type: listSubPages - path: /Web/HTML/Element/input + path: /Web/HTML/Reference/Elements/input title: Input_types details: closed code: true diff --git a/files/en-us/mdn/writing_guidelines/page_structures/specification_tables/index.md b/files/en-us/mdn/writing_guidelines/page_structures/specification_tables/index.md index e39c2320a00ec16..508a02390c28370 100644 --- a/files/en-us/mdn/writing_guidelines/page_structures/specification_tables/index.md +++ b/files/en-us/mdn/writing_guidelines/page_structures/specification_tables/index.md @@ -32,7 +32,7 @@ browser-compat: css.property.text-align Some features are not maintained in the above repository. In these cases, specification information can be added to the page front matter using the `spec-urls` key. -For example, the [`aria-atomic`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-atomic) attribute has the front matter key: +For example, the [`aria-atomic`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-atomic) attribute has the front matter key: ```yaml spec-urls: https://w3c.github.io/aria/#aria-atomic diff --git a/files/en-us/mdn/writing_guidelines/page_structures/syntax_sections/index.md b/files/en-us/mdn/writing_guidelines/page_structures/syntax_sections/index.md index c5f6ab2a90e8ab9..d31cb96ee3ed4c5 100644 --- a/files/en-us/mdn/writing_guidelines/page_structures/syntax_sections/index.md +++ b/files/en-us/mdn/writing_guidelines/page_structures/syntax_sections/index.md @@ -5,7 +5,7 @@ page-type: mdn-writing-guide sidebar: mdnsidebar --- -The syntax section of an MDN reference page contains a syntax box defining the exact syntax that a feature has (e.g. what parameters can it accept, which ones are optional?) This article explains how to write syntax boxes for reference articles. +The syntax section of an MDN reference page contains a syntax box defining the exact syntax that a feature has (e.g., what parameters can it accept, which ones are optional?) This article explains how to write syntax boxes for reference articles. ## API reference syntax @@ -117,7 +117,7 @@ For specific cases where it is seen as beneficial, a separate **Formal syntax** The aim is to make the syntax block as pure and unambiguous a definition of the feature's syntax as possible — don't include any irrelevant syntax. For example, you may see this syntax form used to describe promises in many places on the site: ```js-nolint -caches.match(request, options).then(function (response) { +caches.match(request, options).then((response) => { // Do something with the response }) ``` @@ -201,7 +201,7 @@ None (\\{{jsxref("undefined")}}). #### Exceptions section -Finally, include an "Exceptions" subsection, which explains what exceptions can be thrown if a problem is encountered when invoking the constructor/method. This could be because a parameter name has been misspelled or it has been given a value of the wrong datatype, because there is a problem with the environment it is being invoked in (e.g. trying to run a secure context-only feature in a non-secure context), or some other reason. +Finally, include an "Exceptions" subsection, which explains what exceptions can be thrown if a problem is encountered when invoking the constructor/method. This could be because a parameter name has been misspelled or it has been given a value of the wrong datatype, because there is a problem with the environment it is being invoked in (e.g., trying to run a secure context-only feature in a non-secure context), or some other reason. Determining what exceptions are thrown by a method can require a good perusal of the specification. Looking through the spec's step-by-step explanation of how a feature operates will generally provide a solid list of the exceptions and the situations that cause them to be thrown. @@ -222,7 +222,7 @@ If accessing the property can throw an exception, include an "Exceptions" subsec ## JavaScript reference syntax -JavaScript built-in object reference pages follow the same basic rules as API reference pages; e.g. for methods and properties. There are a few differences that you might observe: +JavaScript built-in object reference pages follow the same basic rules as API reference pages; e.g., for methods and properties. There are a few differences that you might observe: - For built-in objects with a single constructor, the constructor syntax is often included on the object landing page. See {{JSxRef("Date")}} for example. You'll notice that static methods (those that exist on the `Date` object itself) are listed under "Methods", whereas instance methods are listed under "Date.prototype methods". - You'll also notice that methods that have no parameters/exceptions are more likely to have those subsections not included at all on JavaScript reference pages. See {{JSxRef("Date.getDate()")}} and {{JSxRef("Date.now()")}} for examples. @@ -255,7 +255,7 @@ The last section, "Formal syntax", is automatically generated using the `\{{CSSS ### Selectors -The "Syntax" section of selector reference pages is much simpler than that of property pages. It contains one block styled using the "Syntax Box" style, which shows the basic syntax of the selector, whether it is just a simple keyword (e.g. {{CSSxRef(":hover")}}), or a more complex function value that takes a parameter (e.g. {{CSSxRef(":not", ":not()")}}). Sometimes the parameter is explained in a further entry inside the syntax block (see {{CSSxRef(":nth-last-of-type", ":nth-last-of-type()")}} for an example). +The "Syntax" section of selector reference pages is much simpler than that of property pages. It contains one block styled using the "Syntax Box" style, which shows the basic syntax of the selector, whether it is just a simple keyword (e.g., {{CSSxRef(":hover")}}), or a more complex function value that takes a parameter (e.g., {{CSSxRef(":not", ":not()")}}). Sometimes the parameter is explained in a further entry inside the syntax block (see {{CSSxRef(":nth-last-of-type", ":nth-last-of-type()")}} for an example). This block is automatically generated from the data included in the [MDN data repo](https://github.com/mdn/data)'s CSS directory. You just need to include a `CSSSyntax` macro call below the title, and it will take care of the rest. @@ -293,7 +293,7 @@ The "Directive" section contains a description list containing the names and des ### HTTP request methods -Request method syntax is really simple, just containing a syntax block styled using the "Syntax Box" style that shows how the method syntax is structured. The syntax for the [GET method](/en-US/docs/Web/HTTP/Methods/GET) looks like this: +Request method syntax is really simple, just containing a syntax block styled using the "Syntax Box" style that shows how the method syntax is structured. The syntax for the [GET method](/en-US/docs/Web/HTTP/Reference/Methods/GET) looks like this: ```http GET /index.html diff --git a/files/en-us/mdn/writing_guidelines/what_we_write/criteria_for_inclusion/index.md b/files/en-us/mdn/writing_guidelines/what_we_write/criteria_for_inclusion/index.md deleted file mode 100644 index 61cd7f3bddab570..000000000000000 --- a/files/en-us/mdn/writing_guidelines/what_we_write/criteria_for_inclusion/index.md +++ /dev/null @@ -1,179 +0,0 @@ ---- -title: Criteria for inclusion on MDN Web Docs -slug: MDN/Writing_guidelines/What_we_write/Criteria_for_inclusion -page-type: mdn-writing-guide -sidebar: mdnsidebar ---- - -This article describes, in detail, criteria for content to be included on MDN Web Docs, the application process for including new documentation, and expectations and guidelines for a party applying. - -This is aimed at larger projects. To suggest a new page or article, please refer to the [Suggesting content](/en-US/docs/MDN/Writing_guidelines/What_we_write#suggesting_content) section on the "What we write" page. - -## Web standards technologies - -The remit of MDN Web Docs is to document web standards technologies that are in a specification published by a reliable standards body and are supported in at least one stable browser. These criteria signal enough interest, stability, and "intent to implement" by the web industry at large. Therefore, we think those technologies are a safe bet for us to spend our time and effort in documenting them. Any earlier than that, a web technology or a feature might be prone to getting cancelled due to lack of interest or might be so unstable that it might change significantly, which will needlessly involve a lot of rewriting (which we try to avoid where possible). - -## Non-web standards technologies - -Non-web standards technologies are technologies that do not follow our criteria summarized above. We would not normally consider them for documentation on MDN Web Docs. - -Our mission statement is _"to provide developers with the information they need to easily build projects on the open web"_. This suggests that we should consider documenting technologies that are useful to web developers, even if they are not open web standards, on the standards track, etc. - -If you want to consider a non-web standard technology for inclusion on MDN Web Docs, you should make sure that it matches the criteria below. - -## Criteria for inclusion on MDN Web Docs - -Technologies should fulfill the criteria described here for being considered to be documented on MDN Web Docs. - -### Be open and not proprietary - -At MDN Web Docs, we are supporters of open technologies. We don't support closed technology ecosystems that are controlled by a single entity, that are not open for contributions by any interested party, and that are not interoperable across multiple platforms and systems. We believe that technology works better for everyone when created out in the open. - -### Be web-exposed and be related to web technologies - -Our central remit is web standards technologies; there is no point starting to document technologies that do not relate to the web or hold any interest to web developers. - -### Show signs of interest and adoption - -We don't want to spend our time documenting a technology that has no signal of interest and adoption from the industry. It may just be that it is too early to start documenting the technology, and we could consider it to be documented on MDN Web Docs in the future. - -### Not show signs of being deprecated or superseded - -Related to the above point, we also don't want to spend our time documenting a technology that is late in its lifecycle and is already showing signs of decline in interest. - -### Not have an established documentation resource elsewhere - -There are many libraries and frameworks in existence, which are not web standards but are built on top of web technologies and are very popular in the web industry. We do not document any of these because, in general, they all have established documentation resources already. It would be foolish to compete with the official resource of a popular framework — to do so would be a waste of time and probably end up confusing developers trying to learn the technology. - -### Have a community willing to write and maintain the documentation - -The MDN Web Docs team concentrates on documenting the open web platform. If you want a technology in this area to be considered for documentation on MDN Web Docs, you'll need to have a community assembled that is willing to write the documentation and maintain it after completion. Our team is happy to provide guidance in such cases, including edits and feedback, but we don't have the resource for more than that. - -> [!NOTE] -> MDN Web Docs work is carried out on GitHub and 'in the open'. Your team should be versed in git & GitHub and be comfortable with working in open source. - -## Process for selecting the new technology - -If a technology looks like a good candidate for being documented on MDN Web Docs, you can start a discussion on the [GitHub community discussions](/en-US/docs/MDN/Community/Communication_channels#github_discussions) to propose and discuss the inclusion of this technology. This section describes what the proposal should include. - -### Submitting the proposal - -Technologies will be considered for inclusion on MDN Web Docs on a case-by-case basis. For consideration, you would need to submit a proposal titled "Proposal for documenting a new technology on MDN Web Docs". We would need the following information from you in the proposal: - -- The technology, its core purpose/use cases, and target developer audience. -- What kind of industry or community buzz is there is around the technology? - - Are a lot web developers using it? What is the industry adoption like? - - Do a lot of web developers want or need this information? - - What is the size of the target audience for this information? Supporting statistics would help if you have them. -- How does the technology relate to core web technology and web browsers? Useful details include: - - Does it use HTML and CSS but generally not output to the web? - - Is it supported in web browsers via a polyfill? -- What documentation or resources are already available that cover the technology? -- How much documentation would need to be added to MDN Web Docs? - - List the expected number of guides, tutorials, reference pages for elements/methods/attributes, etc. - - Provide a high-level table of contents. - - Mention the kind of "advanced" features you think you might need for this resource, beyond the basic documentation pages. Are you expecting to include embedded videos, interactive code samples, etc.? -- Who will be writing the documentation? Who are they and why are they suited for the job? -- How will the documentation be maintained? - -You don't need to provide us with hundreds of pages of detail at this stage (in fact, we'd prefer it if you didn't). A couple of paragraphs on each of the above points is more than adequate. - -> [!NOTE] -> MDN Web Docs is primarily an English site (en-US). The primary language for your project should be in US English. - -### Awaiting a response - -We will consider the technology and the information you submit in the proposal and respond with one of the following answers: - -- **No**: We don't think this meets the criteria for being documented on MDN Web Docs. -- **Maybe**: We are not sure if it is suitable for documenting on MDN Web Docs and would like to ask some further questions. -- **Yes**: We think it is appropriate for including it on MDN Web Docs. - -If the technology is a good candidate, the team will assist you in getting started with the documentation. - -## Project guidelines for documenting the new technology - -If your chosen technology is accepted for documentation on MDN Web Docs, the next step is to get started. - -To ensure that your project for documenting the new technology on MDN Web Docs is successful, we'll need you to have the following in place: - -- A dedicated team -- A project plan and roadmap -- Writing guidelines and standards -- An intuitive documentation structure -- A maintenance plan - -### Dedicated team - -Make sure you have a dedicated team in place that will be there to both write the initial documentation as well as maintain it in future with the required updates. - -Have a think about how much work there is and how many people you might need for that. - -- If it is a large project, you might benefit from having a few writers, a technical reviewer to check that the work is technically accurate, a copy editor to clean up the language, someone to write code examples, etc. -- On a smaller project, you might have one or two people taking on multiple roles. However you want to build up the team is fine as long as it works for you. - -A member of the MDN Web Docs team will be assigned to your project to provide guidance on the MDN Web Docs side of things. - -You should assign one (or two) team leads who can liaise with the MDN Web Docs team member. - -The MDN Web Docs representative will help get the required permissions to everyone on your team to work in the [MDN organization on GitHub](https://github.com/mdn). - -### Project plan and roadmap - -Create a plan for the project — tasks, estimate completion dates, and milestones you would want to track to ensure you're making steady progress. - -If the project is large, you should consider assigning one of your team members as the project manager. You should also consider writing a subproject plan for an initial release that encompasses the minimum set of documentation that is useful to publish (a _minimum viable product_); you can follow it up with further additions later. - -If the documentation project is small, you would still need to keep a record of what has been done and what hasn't, what stage each part of the documentation is at (e.g., not started, in progress, draft written, reviewed, done), and who is working on what. - -### Writing guidelines and standards - -These [guidelines](/en-US/docs/MDN/Writing_guidelines) state how we expect documents to be written for MDN Web Docs. - -If you have additional guidelines for the documents you are writing, we expect this guide to be added to and kept up to date. - -In terms of standards, you are expected to maintain a reasonable level of writing quality for your documentation to stay on MDN Web Docs. Your MDN Web Docs representative will work with you to make you clear on what is expected. - -### Intuitive documentation structure - -If you went through the proposal submission process, then you should already have a rough outline of what you are going to write for this technology. At this point, you should refine that into a site structure plan: think about what the document hierarchy will be and where everything will fit and link together. - -Each project is different, but we'd roughly recommend something like this: - -```plain -Landing page -| -------Reference - | - --------Elements - | - --------Methods - | - --------Other reference page type(s)? -| -------Guides/tutorials -| -------Examples -``` - -Each page type that you will use in your project should have a page template for others to copy the structure from. You should decide on these early on. - -Please refer to our section on [page types](/en-US/docs/MDN/Writing_guidelines/Page_structures/Page_types). If additions need to be made, please liaise with your MDN Web Docs representative. - -### Maintenance plan - -The documentation for this technology will need to be maintained to remain on MDN Web Docs: - -- The content and files for MDN Web Docs are stored on GitHub. When others make changes to the documentation for your technology, a member from your team needs to review those changes to make sure the content is still good. You can track the open pull requests (PRs) via GitHub's notification feature. -- When changes occur to the technology that require documentation to be updated, your team needs to make updates as appropriate, maintaining the same standards as the original documentation. - -If positive changes are not observed over a period of six months and the documentation appears to be in any of the following states: - -- Stale or unmaintained -- Stalled without being finished -- Low quality -- Becoming obsolete - -Then the documentation for this technology will be considered dead. After a discussion between your team and the MDN Web Docs team representative, the documentation will be removed. - -We hope you understand that we need to be strict on such matters — we can't let the site fill up with bad quality, incomplete, or obsolete documentation. diff --git a/files/en-us/mdn/writing_guidelines/what_we_write/index.md b/files/en-us/mdn/writing_guidelines/what_we_write/index.md index 661796e1e0a48f7..3b7e5406b9e5c56 100644 --- a/files/en-us/mdn/writing_guidelines/what_we_write/index.md +++ b/files/en-us/mdn/writing_guidelines/what_we_write/index.md @@ -18,7 +18,7 @@ All content on MDN Web Docs must be relevant to the technology section in which Outbound links to commercial sites that are relevant to the topic from which they are linked will be judged on a case-by-case basis. Their value in aiding web developers must outweigh the commercial benefit to the linked site. > [!NOTE] -> You will see links to commercial sites in the MDN [Learn web development](/en-US/docs/Learn_web_development) section, but these are used sparingly, and we only link to trusted education partners. You can read more about this at [Learn web development writing guidelines > External links and embeds](/en-US/docs/MDN/Writing_guidelines/Learning_content#external_links_and_embeds). +> You will see links to commercial sites in the MDN [Learn web development](/en-US/docs/Learn_web_development) section, but these are used sparingly, and we only link to trusted education partners. You can read more about this at [Learn web development writing guidelines > Partner links and embeds](/en-US/docs/MDN/Writing_guidelines/Learning_content#partner_links_and_embeds). ### Neutrality @@ -34,7 +34,7 @@ If you'd like to suggest content for MDN Web Docs, please make sure you read thi For new reference pages or guides, please open a [new issue](https://github.com/mdn/mdn/issues/new/choose) outlining what content you are suggesting and why (please be as explicit as possible). -For suggesting larger projects that involve new sections of content, please refer to the [Criteria for inclusion](/en-US/docs/MDN/Writing_guidelines/What_we_write/Criteria_for_inclusion) page, which also outlines the application process. +For suggesting larger projects that involve new sections of content, please refer to the [Criteria for inclusion](/en-US/docs/MDN/Writing_guidelines/Criteria_for_inclusion) page, which also outlines the application process. ## Topics that belong on MDN Web Docs @@ -64,7 +64,7 @@ We also document some broader topics, such as [SVG](/en-US/docs/Web/SVG), [XML]( All content on MDN Web Docs must be relevant to the technology section in which it appears. Contributors are expected to follow these [MDN writing guidelines](/en-US/docs/MDN/Writing_guidelines) for writing style, code samples, and other topics. -For more details about the criteria for whether or not a technology can be documented on MDN Web Docs, see the [Criteria for inclusion](/en-US/docs/MDN/Writing_guidelines/What_we_write/Criteria_for_inclusion) page. +For more details about the criteria for whether or not a technology can be documented on MDN Web Docs, see the [Criteria for inclusion](/en-US/docs/MDN/Writing_guidelines/Criteria_for_inclusion) page. ### When we document a new technology diff --git a/files/en-us/mdn/writing_guidelines/writing_style_guide/code_style_guide/css/index.md b/files/en-us/mdn/writing_guidelines/writing_style_guide/code_style_guide/css/index.md deleted file mode 100644 index f2d84d3bd3ae9cb..000000000000000 --- a/files/en-us/mdn/writing_guidelines/writing_style_guide/code_style_guide/css/index.md +++ /dev/null @@ -1,174 +0,0 @@ ---- -title: Guidelines for writing CSS code examples -slug: MDN/Writing_guidelines/Writing_style_guide/Code_style_guide/CSS -page-type: mdn-writing-guide -sidebar: mdnsidebar ---- - -The following guidelines cover how to write CSS example code for MDN Web Docs. - -## General guidelines for CSS code examples - -### Choosing a format - -Opinions on correct indentation, whitespace, and line lengths have always been controversial. Discussions on these topics are a distraction from creating and maintaining content. - -On MDN Web Docs, we use [Prettier](https://prettier.io/) as a code formatter to keep the code style consistent (and to avoid off-topic discussions). You can consult our [configuration file](https://github.com/mdn/content/blob/main/.prettierrc.json) to learn about the current rules, and read the [Prettier documentation](https://prettier.io/docs/en/index.html). - -Prettier formats all the code and keeps the style consistent. Nevertheless, there are a few additional rules that you need to follow. - -### Plan your CSS - -Before diving in and writing huge chunks of CSS, plan your styles carefully. What general styles are going to be needed, what different layouts do you need to create, what specific overrides need to be created, and are they reusable? Above all, you need to try to **avoid too much overriding**. If you keep finding yourself writing styles and then cancelling them again a few rules down, you probably need to rethink your strategy. - -### Use flexible/relative units - -For maximum flexibility over the widest possible range of devices, it is a good idea to size containers, padding, etc. using relative units like ems and rems or percentages and viewport units if you want them to vary depending on viewport width. You can read some more about this in our [guide to CSS values and units](/en-US/docs/Learn_web_development/Core/Styling_basics/Values_and_units#relative_length_units). - -### Don't use preprocessors - -Don't use preprocessor syntax, such as [Sass](https://sass-lang.com/), [Less](https://lesscss.org/), or [Stylus](https://stylus-lang.com/), in the example code. On MDN Web Docs, we document the vanilla CSS language. Using preprocessors will only raise the bar to understanding the examples, potentially confusing readers. - -### Don't use specific CSS methodologies - -In the same spirit as the previous guideline, don't write example codes on MDN Web Docs using a specific CSS methodology such as [BEM](https://getbem.com/naming/) or [SMACSS](https://smacss.com/). Even though they are valid CSS syntax, the naming conventions can be confusing to people not familiar with those methodologies. - -### Don't use resets - -For maximum control over CSS across platforms, a lot of people used to use CSS resets to remove every style, before then building things back up themselves. This certainly has its merits, but especially in the modern world, CSS resets can be an overkill, resulting in a lot of extra time spent reimplementing things that weren't completely broken in the first place, like default margins, list styles, etc. - -If you really feel like you need to use a reset, consider using [normalize.css by Nicolas Gallagher](https://necolas.github.io/normalize.css/), which aims to just make things more consistent across browsers, get rid of some default annoyances that we always remove (the margins on `<body>`, for example) and fix a few bugs. - -## !important - -`!important` is the last resort that is generally used only when you need to override something and there is no other way to do it. Using `!important` is a bad practice and you should avoid it wherever possible. - -```css example-bad -.bad-code { - font-size: 4rem !important; -} -``` - -## CSS comments - -Use CSS-style comments to comment code that isn't self-documenting. Also note that you should leave a space between the asterisks and the comment. - -```css example-good -/* This is a CSS-style comment */ -``` - -Put your comments on separate lines preceding the code they are referring to, like so: - -```css example-good -h3 { - /* Creates a red drop shadow, offset 1px right and down, w/2px blur radius */ - text-shadow: 1px 1px 2px red; - /* Sets the font-size to double the default document font size */ - font-size: 2rem; -} -``` - -## Double quotes around values - -Where quotes can or should be included, use them, and use double quotes. For example: - -```css example-good -[data-vegetable="liquid"] { - background-color: goldenrod; - background-image: url("../../media/examples/lizard.png"); -} -``` - -## Longhand vs. shorthand rules - -Usually, when teaching the specifics of CSS syntax, it is clearer and more obvious to use longhand properties, rather than terse shorthand (unless, of course, you're explaining shorthand through the example). Remember that the point of examples on MDN Web Docs is to teach people, not to be clever or efficient. We explain here why writing with longhand rules is recommended. - -- It is often harder to understand what the shorthand is doing. In the example below, it takes a while to pick apart exactly what the {{cssxref("font")}} syntax is doing. - - ```css - font: small-caps bold 2rem/1.5 sans-serif; - ``` - - Whereas the following style is clearer: - - ```css - font-variant: small-caps; - font-weight: bold; - font-size: 2rem; - line-height: 1.5; - font-family: sans-serif; - ``` - -- CSS shorthand comes with potential added pitfalls — default values are set for parts of the syntax that you don't explicitly set, which can produce unexpected resets of values you've set earlier in the cascade or other expected effects. The {{cssxref("grid")}} property, for example, sets all of the following default values for items that are not specified: - - - {{cssxref("grid-template-rows")}}: `none` - - {{cssxref("grid-template-columns")}}: `none` - - {{cssxref("grid-template-areas")}}: `none` - - {{cssxref("grid-auto-rows")}}: `auto` - - {{cssxref("grid-auto-columns")}}: `auto` - - {{cssxref("grid-auto-flow")}}: `row` - - {{cssxref("column-gap")}}: `0` - - {{cssxref("row-gap")}}: `0` - - {{cssxref("column-gap")}}: `normal` - - {{cssxref("row-gap")}}: `normal` - -- Some shorthands only work as expected if you include the different value components in a certain order. This is the case in CSS animations. In the example below, the expected order is written as a comment: - - ```css - /* duration | timing-function | delay | iteration-count - direction | fill-mode | play-state | name */ - animation: 3s ease-in 1s 2 reverse both paused slide-in; - ``` - - In this example, the first value that can be parsed as a [`<time>`](/en-US/docs/Web/CSS/time) is assigned to the [`animation-duration`](/en-US/docs/Web/CSS/animation-duration) property, and the second value that can be parsed as time is assigned to [`animation-delay`](/en-US/docs/Web/CSS/animation-delay). (For more information, see [animation syntax](/en-US/docs/Web/CSS/animation#syntax) details.) - -## Mobile-first media queries - -In a stylesheet that contains [media query](/en-US/docs/Web/CSS/CSS_media_queries/Using_media_queries) styles for different target viewport sizes, first include the narrow screen/mobile styling before any other media queries are encountered. Add styling for wider viewport sizes via successive media queries. Following this rule has many advantages that are explained in [Responsive design](/en-US/docs/Learn_web_development/Core/CSS_layout/Responsive_Design). - -```css example-good -/* Default CSS layout for narrow screens */ - -@media (min-width: 480px) { - /* CSS for medium width screens */ -} - -@media (min-width: 800px) { - /* CSS for wide screens */ -} - -@media (min-width: 1100px) { - /* CSS for really wide screens */ -} -``` - -## Selectors - -- Don't use ID selectors because they are: - - - less flexible; you can't add more if you discover you need more than one. - - harder to override because they have higher specificity than classes. - - ```css example-good - .editorial-summary { - /* ... */ - } - ``` - - ```css example-bad - #editorial-summary { - /* ... */ - } - ``` - -## Value to turn off properties - -When turning off borders (and any other properties that can take `0` or `none` as values), use `0` rather than `none`: - -```css example-good -border: 0; -``` - -## See also - -[CSS reference index](/en-US/docs/Web/CSS/Reference#index) - browse through our CSS property reference pages to check out some good, concise, meaningful CSS snippets. Our interactive examples in the "Try it" section are generally written to follow the guidelines described on this page. diff --git a/files/en-us/mdn/writing_guidelines/writing_style_guide/code_style_guide/html/index.md b/files/en-us/mdn/writing_guidelines/writing_style_guide/code_style_guide/html/index.md deleted file mode 100644 index e8134556246370f..000000000000000 --- a/files/en-us/mdn/writing_guidelines/writing_style_guide/code_style_guide/html/index.md +++ /dev/null @@ -1,141 +0,0 @@ ---- -title: Guidelines for writing HTML code examples -slug: MDN/Writing_guidelines/Writing_style_guide/Code_style_guide/HTML -page-type: mdn-writing-guide -sidebar: mdnsidebar ---- - -The following guidelines cover how to write HTML example code for MDN Web Docs. - -## General guidelines for HTML code examples - -### Choosing a format - -Opinions on correct indentation, whitespace, and line lengths have always been controversial. Discussions on these topics are a distraction from creating and maintaining content. - -On MDN Web Docs, we use [Prettier](https://prettier.io/) as a code formatter to keep the code style consistent (and to avoid off-topic discussions). You can consult our [configuration file](https://github.com/mdn/content/blob/main/.prettierrc.json) to learn about the current rules, and read the [Prettier documentation](https://prettier.io/docs/en/index.html). - -Prettier formats all the code and keeps the style consistent. Nevertheless, there are a few additional rules that you need to follow. - -## Complete HTML document - -> [!NOTE] -> The guidelines in this section apply only when you need to show a complete HTML document. A snippet is usually enough to demonstrate a feature. When using the [EmbedLiveSample macro](/en-US/docs/MDN/Writing_guidelines/Page_structures/Code_examples#live_samples), just include the HTML snippet; it will automatically be inserted into a full HTML document when displayed. - -### Doctype - -You should use the HTML5 doctype. It is short, easy to remember, and backwards compatible. - -```html example-good -<!doctype html> -``` - -### Document language - -Set the document language using the [`lang`](/en-US/docs/Web/HTML/Global_attributes/lang) attribute on your {{htmlelement("html")}} element: - -```html example-good -<html lang="en-US"></html> -``` - -This is good for accessibility and search engines, helps with localizing content, and reminds people to use best practices. - -### Document character set - -You should also define your document's character set like so: - -```html example-good -<meta charset="utf-8" /> -``` - -Use UTF-8 unless you have a very good reason not to; it will cover all character needs pretty much regardless of what language you are using in your document. - -### Viewport meta tag - -Finally, you should always add the viewport meta tag into your HTML {{HTMLElement("head")}} to give the code example a better chance of working on mobile devices. You should include at least the following in your document, which can be modified later on as the need arises: - -```html example-good -<meta name="viewport" content="width=device-width" /> -``` - -See [Using the viewport meta tag to control layout on mobile browsers](/en-US/docs/Web/HTML/Viewport_meta_tag) for further details. - -## Attributes - -You should put all attribute values in double quotes. It is tempting to omit quotes since HTML5 allows this, but markup is neater and easier to read if you do include them. For example, this is better: - -```html example-good -<img src="images/logo.jpg" alt="A circular globe icon" class="no-border" /> -``` - -…than this: - -```html-nolint example-bad -<img src=images/logo.jpg alt=A circular globe icon class=no-border> -``` - -Omitting quotes can also cause problems. In the above example, the `alt` attribute will be interpreted as multiple attributes because there are no quotes to specify that "A circular globe icon" is a single attribute value. - -## Boolean attributes - -Don't include values for boolean attributes (but do include values for {{glossary("enumerated")}} attributes); you can just write the attribute name to set it. For example, you can write: - -```html example-good -<input required /> -``` - -This is perfectly understandable and works fine. If a boolean HTML attribute is present, the value is true. While including a value will work, it is not necessary and incorrect: - -```html example-bad -<input required="required" /> -``` - -## Case - -Use lowercase for all element names and attribute names/values because it looks neater and means you can write markup faster. For example: - -```html example-good -<p class="nice">This looks nice and neat</p> -``` - -```html-nolint example-bad -<P CLASS="WHOA-THERE">Why is my markup shouting?</P> -``` - -## Class and ID names - -Use semantic class/ID names, and separate multiple words with hyphens ({{Glossary("kebab_case", "kebab case")}}). Don't use {{Glossary("camel_case", "camel case")}}. For example: - -```html example-good -<p class="editorial-summary">Blah blah blah</p> -``` - -```html example-bad -<p class="bigRedBox">Blah blah blah</p> -``` - -## Character references - -Don't use {{glossary("character reference", "character references")}} unnecessarily — use the literal character wherever possible (you'll still need to escape characters like angle brackets and quote marks). - -As an example, you could just write: - -```html example-good -<p>© 2018 Me</p> -``` - -Instead of: - -```html example-bad -<p>&copy; 2018 Me</p> -``` - -## HTML elements - -There are some rules for writing about HTML elements on MDN Web Docs. Adhering to these rules produces consistent descriptions of elements and their components and also ensures correct linking to detailed documentation. - -- **Element names**: Use the [`HTMLElement`](https://github.com/mdn/rari/blob/main/crates/rari-doc/src/templ/templs/links/htmlxref.rs) macro, which creates a link to the MDN Web Docs page for that element. For example, writing `\{{HTMLElement("title")}}` produces "{{HTMLElement("title")}}". - If you don't want to create a link, **enclose the name in angle brackets** and use the "Inline Code" style (e.g., `<title>`). -- **Attribute names**: Use "Inline Code" style to put attribute names in `code font`. - Additionally, put them in **`bold face`** when the attribute is mentioned in association with an explanation of what it does or when it is used for the first time on the page. -- **Attribute values**: Use the "Inline Code" style to apply `<code>` to attribute values, and don't use quotation marks around string values, unless needed by the syntax of a code sample. For example, "When the `type` attribute of an `<input>` element is set to `email` or `tel` ...". diff --git a/files/en-us/mdn/writing_guidelines/writing_style_guide/code_style_guide/index.md b/files/en-us/mdn/writing_guidelines/writing_style_guide/code_style_guide/index.md deleted file mode 100644 index 7561ea1f50961a9..000000000000000 --- a/files/en-us/mdn/writing_guidelines/writing_style_guide/code_style_guide/index.md +++ /dev/null @@ -1,192 +0,0 @@ ---- -title: Guidelines for writing code examples -slug: MDN/Writing_guidelines/Writing_style_guide/Code_style_guide -page-type: mdn-writing-guide -sidebar: mdnsidebar ---- - -The guidelines described in this article apply to the styling and formatting of code examples, irrespective of the language. For guidelines about what content to include while writing the code examples, see the [writing style guide](/en-US/docs/MDN/Writing_guidelines/Writing_style_guide#code_examples). - -For technology-specific guidelines, see the following articles: - -- [HTML guidelines](/en-US/docs/MDN/Writing_guidelines/Writing_style_guide/Code_style_guide/HTML) -- [CSS guidelines](/en-US/docs/MDN/Writing_guidelines/Writing_style_guide/Code_style_guide/CSS) -- [JavaScript guidelines](/en-US/docs/MDN/Writing_guidelines/Writing_style_guide/Code_style_guide/JavaScript) -- [Shell prompt guidelines](/en-US/docs/MDN/Writing_guidelines/Writing_style_guide/Code_style_guide/Shell) - -## General best practices - -This section provides the best practices for creating an understandable minimal code example to demonstrate the usage of a specific feature or function. - -Code examples that you add to MDN Web Docs should be: - -- simple enough to be understandable, but -- complex enough to do something interesting, and preferably useful. - -There is one overarching consideration that you need to keep in mind: **Readers will copy and paste the code sample into their own code and may put it into production.** - -Therefore, you should make sure that the code example is usable, follows generally accepted best practices, and **does not** do anything that will cause an application to be insecure, grossly inefficient, bloated, or inaccessible. If the code example is not runnable or production-worthy, be sure to include a warning in a code comment and in the explanatory text; for example, if it is only a snippet and not a full example, make this clear. This also means that you should provide **all** of the information necessary to run the example including any dependencies and setup information. - -Code examples should be as self-contained and easy to understand as possible. The aim is not necessarily to produce efficient, clever code that impresses experts and has great functionality, but rather to produce reduced working examples that can be understood as quickly as possible. - -Some more general best practices include: - -- The code example should be short and ideally show only the feature you are immediately interested in. -- **Only** include code that is essential for the example. A large amount of non-relevant code can easily distract or confuse the reader. If you want to provide a full, more lengthy example, put it in one of our [GitHub repos](https://github.com/mdn/) (or a JS Bin, CodePen, or similar) and then provide the link to the full version above or below the sample. -- Don't include unnecessary server-side code, libraries, frameworks, preprocessors, and other such dependencies. They make the code less portable and harder to run and understand. Use vanilla code where possible. -- Don't assume readers' knowledge of any libraries, frameworks, preprocessors, or other non-native features. For example, use class names that make sense within the example rather than class names that make sense to BEM or Bootstrap users. -- Write your code to be as clean and understandable as possible, even if it is not the most efficient way to write it. -- Be inclusive in your code examples; consider that MDN readers come from all over the world, and are diverse in their ethnicities, religions, ages, genders, etc. Ensure text in code examples reflects that diversity and is inclusive of all people. -- Don't use bad practices for brevity (such as presentation elements like {{HTMLElement("big")}} or {{domxref("Document.write", "document.write()")}}); do it correctly. -- In the case of API demos, if you are using multiple APIs together, point out which APIs are included and which features come from where. - -## Guidelines for formatting - -Opinions on correct indentation, whitespace, and line lengths have always been controversial. Discussions on these topics are a distraction from creating and maintaining content. - -On MDN Web Docs, we use [Prettier](https://prettier.io/) as a code formatter to keep the code style consistent (and to avoid off-topic discussions). You can consult our [configuration file](https://github.com/mdn/content/blob/main/.prettierrc.json) to learn about the current rules, and read the [Prettier documentation](https://prettier.io/docs/en/index.html). - -Prettier formats all the code and keeps the style consistent. Nevertheless, there are a few additional rules that you need to follow. - -These MDN Web Docs guidelines for formatting code examples are also good practices when you are coding. - -### Choosing a syntax language - -To ensure proper formatting and syntax highlighting of code blocks, writers must specify the language of the code block they are writing in. See [Example code blocks in MDN Markdown](/en-US/docs/MDN/Writing_guidelines/Howto/Markdown_in_MDN#example_code_blocks) for a list of languages supported by MDN, as well as details on how to request a new language. - -If the code block is pseudocode, the output of a command, or otherwise not a programming language, explicitly set the language to `plain`. - -> [!WARNING] -> If the desired language is not yet supported by MDN, do **not** set the language of a code block to a similar language, as doing so may have unintended side effects with Prettier formatting and syntax highlighting. - -### Code line length - -- Code lines shouldn't be so long that they require horizontal scrolling to read. -- Break long lines at natural breaking points for the sake of readability, but not at the expense of best practices. - -For example, this is not great: - -```js example-bad -let tommyCat = - "Said Tommy the Cat as he reeled back to clear whatever foreign matter may have nestled its way into his mighty throat. Many a fat alley rat had met its demise while staring point blank down the cavernous barrel of this awesome prowling machine."; -``` - -This is better, but somewhat awkward: - -```js -const tommyCat = - "Said Tommy the Cat as he reeled back to clear whatever foreign " + - "matter may have nestled its way into his mighty throat. Many a fat alley rat " + - "had met its demise while staring point blank down the cavernous barrel of " + - "this awesome prowling machine."; -``` - -Even better is to use a template literal: - -```js example-good -const tommyCat = `Said Tommy the Cat as he reeled back to clear whatever foreign - matter may have nestled its way into his mighty throat. Many a fat alley rat - had met its demise while staring point blank down the cavernous barrel of - this awesome prowling machine.`; -``` - -```js example-good -if ( - obj.CONDITION || - obj.OTHER_CONDITION || - obj.SOME_OTHER_CONDITION || - obj.YET_ANOTHER_CONDITION -) { - /* something */ -} - -const toolkitProfileService = Components.classes[ - "@mozilla.org/toolkit/profile-service;1" -].createInstance(Components.interfaces.nsIToolkitProfileService); -``` - -### Code block height - -Code blocks should be as long as they need to be, but no longer. Ideally, aim for something short, like 15-25 lines. If a code block is going to be a lot longer, consider just showing the most useful snippet, and link to the complete example on a GitHub repo or CodePen, say. - -#### Inline code formatting - -Use inline code syntax (\`) to mark up function names, variable names, and method names. For example: "the `frenchText()` function". - -**Method names should be followed by a pair of parentheses**: for example, `doSomethingUseful()`. The parentheses help differentiate methods from other code terms. - -## Guidelines for proper rendering - -These guidelines should be followed to ensure that the code examples you write display properly on MDN Web Docs. You should also consider responsiveness making writing code examples so that they are also useful on mobile devices. - -### Size of the rendered code example - -- **Set the width to 100%**: The main content pane on MDN Web Docs is about 700px wide on desktop, so the embedded code examples must look OK at that width. -- **Set height below 700px**: We recommend keeping this height for the rendered code example width for maximum onscreen legibility. - -### Color in the rendered code example - -- Use keywords for primary and other "basic" colors, for example: - - ```css example-good - color: black; - color: white; - color: red; - ``` - -- Use `rgb()` for more complex colors (including semi-transparent ones): - - ```css example-good - color: rgb(0 0 0 / 50%); - color: rgb(248 242 230); - ``` - -- For hex colors, use the short form where relevant: - - ```css example-good - color: #058ed9; - color: #a39a92c1; - color: #ff0; - color: #fbfa; - ``` - - ```css-nolint example-bad - color: #ffff00; - color: #ffbbffaa; - ``` - -### Mark rendered examples as good or bad - -You'll notice on this page that the code blocks that represent good practices to follow are rendered with a green check mark in the right corner, and the code blocks that demonstrate bad practices are rendered with a white cross in a red circle. - -You can follow the same style while writing code examples. You don't need to use this style everywhere — only on pages where you want to specifically call out good and bad practices in your code examples. - -To get this rendering, use "code fences" to demarcate the code block, followed by the language info string. For example: - -```js -function myFunc() { - console.log("Hello!"); -} -``` - -To represent the code block as a good or bad example, add `example-good` or `example-bad` after the language string, like so: - -````md -```html example-good -<p></p> -``` - -```html example-bad -<p></p> -``` -```` - -These will be rendered as: - -```html example-good -<p class="brush: js example-good"></p> -``` - -```html example-bad -<p class="brush: js example-bad"></p> -``` diff --git a/files/en-us/mdn/writing_guidelines/writing_style_guide/code_style_guide/javascript/index.md b/files/en-us/mdn/writing_guidelines/writing_style_guide/code_style_guide/javascript/index.md deleted file mode 100644 index 556adbecfe9db7a..000000000000000 --- a/files/en-us/mdn/writing_guidelines/writing_style_guide/code_style_guide/javascript/index.md +++ /dev/null @@ -1,881 +0,0 @@ ---- -title: Guidelines for writing JavaScript code examples -slug: MDN/Writing_guidelines/Writing_style_guide/Code_style_guide/JavaScript -page-type: mdn-writing-guide -sidebar: mdnsidebar ---- - -The following guidelines cover writing JavaScript example code for MDN Web Docs. This article is a list of rules for writing concise examples that will be understandable by as many people as possible. - -## General guidelines for JavaScript code examples - -This section explains the general guidelines to keep in mind while writing JavaScript code examples. The later sections will cover more specific details. - -### Choosing a format - -Opinions on correct indentation, whitespace, and line lengths have always been controversial. Discussions on these topics are a distraction from creating and maintaining content. - -On MDN Web Docs, we use [Prettier](https://prettier.io/) as a code formatter to keep the code style consistent (and to avoid off-topic discussions). You can consult our [configuration file](https://github.com/mdn/content/blob/main/.prettierrc.json) to learn about the current rules, and read the [Prettier documentation](https://prettier.io/docs/en/index.html). - -Prettier formats all the code and keeps the style consistent. Nevertheless, there are a few additional rules that you need to follow. - -### Using modern JavaScript features - -You can use new features once every major browser — Chrome, Edge, Firefox, and Safari — supports them. - -## Arrays - -### Array creation - -For creating arrays, use literals and not constructors. - -Create arrays like this: - -```js example-good -const visitedCities = []; -``` - -Don't do this while creating arrays: - -```js example-bad -const visitedCities = new Array(length); -``` - -### Item addition - -When adding items to an array, use [`push()`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/push) and not direct assignment. Consider the following array: - -```js -const pets = []; -``` - -Add items to the array like this: - -```js example-good -pets.push("cat"); -``` - -Don't add items to the array like this: - -```js example-bad -pets[pets.length] = "cat"; -``` - -## Asynchronous methods - -Writing asynchronous code improves performance and should be used when possible. In particular, you can use: - -- [Promises](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise) -- [`async`](/en-US/docs/Web/JavaScript/Reference/Statements/async_function)/[`await`](/en-US/docs/Web/JavaScript/Reference/Operators/await) - -When both techniques are possible, we prefer using the simpler `async`/`await` syntax. Unfortunately, you can't use `await` at the top level unless you are in an ECMAScript module. CommonJS modules used by Node.js are not ES modules. If your example is intended to be used everywhere, avoid top-level `await`. - -## Comments - -Comments are critical to writing good code examples. They clarify the intent of the code and help developers understand it. Pay special attention to them. - -- If the purpose or logic of the code isn't obvious, add a comment with your intention, as shown below: - - ```js example-good - let total = 0; - - // Calculate the sum of the four first elements of arr - for (let i = 0; i < 4; i++) { - total += arr[i]; - } - ``` - - On the other hand, restating the code in prose is not a good use of comments: - - ```js example-bad - let total = 0; - - // For loop from 1 to 4 - for (let i = 0; i < 4; i++) { - // Add value to the total - total += arr[i]; - } - ``` - -- Comments are also not necessary when functions have explicit names that describe what they're doing. Write: - - ```js example-good - closeConnection(); - ``` - - Don't write: - - ```js example-bad - closeConnection(); // Closing the connection - ``` - -### Use single-line comments - -Single-line comments are marked with `//`, as opposed to block comments enclosed between `/* … */`. - -In general, use single-line comments to comment code. Writers must mark each line of the comment with `//`, so that it's easier to notice commented-out code visually. In addition, this convention allows to comment out sections of code using `/* … */` while debugging. - -- Leave a space between the slashes and the comment. Start with a capital letter, like a sentence, but don't end the comment with a period. - - ```js example-good - // This is a well-written single-line comment - ``` - -- If a comment doesn't start immediately after a new indentation level, add an empty line and then add the comment. It will create a code block, making it obvious what the comment refers to. Also, put your comments on separate lines preceding the code they are referring to. This is shown in the following example: - - ```js example-good - function checkout(goodsPrice, shipmentPrice, taxes) { - // Calculate the total price - const total = goodsPrice + shipmentPrice + taxes; - - // Create and append a new paragraph to the document - const para = document.createElement("p"); - para.textContent = `Total price is ${total}`; - document.body.appendChild(para); - } - ``` - -### Output of logs - -- In code intended to run in a production environment, you rarely need to comment when you log some data. In code examples, we often use `console.log()`, `console.error()`, or similar functions to output important values. To help the reader understand what will happen without running the code, you can put a comment _after_ the function with the log that will be produced. Write: - - ```js example-good - function exampleFunc(fruitBasket) { - console.log(fruitBasket); // ['banana', 'mango', 'orange'] - } - ``` - - Don't write: - - ```js example-bad - function exampleFunc(fruitBasket) { - // Logs: ['banana', 'mango', 'orange'] - console.log(fruitBasket); - } - ``` - -- In case the line becomes too long, put the comment _after_ the function, like this: - - ```js example-good - function exampleFunc(fruitBasket) { - console.log(fruitBasket); - // ['banana', 'mango', 'orange', 'apple', 'pear', 'durian', 'lemon'] - } - ``` - -### Multi-line comments - -Short comments are usually better, so try to keep them in one line of 60–80 characters. If this is not possible, use `//` at the beginning of each line: - -```js example-good -// This is an example of a multi-line comment. -// The imaginary function that follows has some unusual -// limitations that I want to call out. -// Limitation 1 -// Limitation 2 -``` - -Don't use `/* … */`: - -```js example-bad -/* This is an example of a multi-line comment. - The imaginary function that follows has some unusual - limitations that I want to call out. - Limitation 1 - Limitation 2 */ -``` - -### Use comments to mark ellipsis - -Skipping redundant code using ellipses (…) is necessary to keep examples short. Still, writers should do it thoughtfully as developers frequently copy & paste examples into their code, and all of our code samples should be valid JavaScript. - -In JavaScript, you should put the ellipses (`…`) in a comment. When possible, indicate what action somebody reusing this snippet is expected to add. - -Using a comment for the ellipses (…) is more explicit, preventing errors when a developer copies and pastes a sample code. Write: - -```js example-good -function exampleFunc() { - // Add your code here - // … -} -``` - -Don't use ellipses (…) like this: - -```js example-bad -function exampleFunc() { - … -} -``` - -### Comment out parameters - -When writing code, you usually omit parameters you don't need. But in some code examples, you want to demonstrate that you didn't use some possible parameters. - -To do so, use `/* … */` in the parameter list. This is an exception to the rule to only use single-line comments (`//`). - -```js -array.forEach((value /* , index, array */) => { - // … -}); -``` - -## Functions - -### Function names - -For function names, use {{Glossary("camel_case", "camel case")}}, starting with a lowercase character. Use concise, human-readable, and semantic names where appropriate. - -The following is a correct example of a function name: - -```js example-good -function sayHello() { - console.log("Hello!"); -} -``` - -Don't use function names like these: - -```js example-bad -function SayHello() { - console.log("Hello!"); -} - -function doIt() { - console.log("Hello!"); -} -``` - -### Function declarations - -- Where possible, use the function declaration over function expressions to define functions. - - Here is the recommended way to declare a function: - - ```js example-good - function sum(a, b) { - return a + b; - } - ``` - - This is not a good way to define a function: - - ```js example-bad - let sum = function (a, b) { - return a + b; - }; - ``` - -- When using anonymous functions as a callback (a function passed to another method invocation), if you do not need to access `this`, use an arrow function to make the code shorter and cleaner. - - Here is the recommended way: - - ```js example-good - const array1 = [1, 2, 3, 4]; - const sum = array1.reduce((a, b) => a + b); - ``` - - Instead of this: - - ```js example-bad - const array1 = [1, 2, 3, 4]; - const sum = array1.reduce(function (a, b) { - return a + b; - }); - ``` - -- Consider avoiding using arrow function to assign a function to an identifier. In particular, don't use arrow functions for methods. Use function declarations with the keyword `function`: - - ```js example-good - function x() { - // … - } - ``` - - Don't do: - - ```js example-bad - const x = () => { - // … - }; - ``` - -- When using arrow functions, use [implicit return](/en-US/docs/Web/JavaScript/Reference/Functions/Arrow_functions#function_body) (also known as _expression body_) when possible: - - ```js example-good - arr.map((e) => e.id); - ``` - - And not: - - ```js example-bad - arr.map((e) => { - return e.id; - }); - ``` - -## Loops and conditional statements - -### Loop initialization - -When [loops](/en-US/docs/Learn_web_development/Core/Scripting/Loops) are required, choose the appropriate one from [`for(;;)`](/en-US/docs/Web/JavaScript/Reference/Statements/for), [`for...of`](/en-US/docs/Web/JavaScript/Reference/Statements/for...of), [`while`](/en-US/docs/Web/JavaScript/Reference/Statements/while), etc. - -- When iterating through all collection elements, avoid using the classical `for (;;)` loop; prefer `for...of` or `forEach()`. Note that if you are using a collection that is not an `Array`, you have to check that `for...of` is actually supported (it requires the variable to be iterable), or that the `forEach()` method is actually present. - - Use `for...of`: - - ```js example-good - const dogs = ["Rex", "Lassie"]; - for (const dog of dogs) { - console.log(dog); - } - ``` - - Or `forEach()`: - - ```js example-good - const dogs = ["Rex", "Lassie"]; - dogs.forEach((dog) => { - console.log(dog); - }); - ``` - - Do not use `for (;;)` — not only do you have to add an extra index, `i`, but you also have to track the length of the array. This can be error-prone for beginners. - - ```js example-bad - const dogs = ["Rex", "Lassie"]; - for (let i = 0; i < dogs.length; i++) { - console.log(dogs[i]); - } - ``` - -- Make sure that you define the initializer properly by using the `const` keyword for `for...of` or `let` for the other loops. Don't omit it. These are correct examples: - - ```js example-good - const cats = ["Athena", "Luna"]; - for (const cat of cats) { - console.log(cat); - } - - for (let i = 0; i < 4; i++) { - result += arr[i]; - } - ``` - - The example below does not follow the recommended guidelines for the initialization (it implicitly creates a global variable and will fail in strict mode): - - ```js example-bad - const cats = ["Athena", "Luna"]; - for (i of cats) { - console.log(i); - } - ``` - -- When you need to access both the value and the index, you can use `.forEach()` instead of `for (;;)`. Write: - - ```js example-good - const gerbils = ["Zoé", "Chloé"]; - gerbils.forEach((gerbil, i) => { - console.log(`Gerbil #${i}: ${gerbil}`); - }); - ``` - - Do not write: - - ```js example-bad - const gerbils = ["Zoé", "Chloé"]; - for (let i = 0; i < gerbils.length; i++) { - console.log(`Gerbil #${i}: ${gerbils[i]}`); - } - ``` - -> [!WARNING] -> Never use `for...in` with arrays and strings. - -> [!NOTE] -> Consider not using a `for` loop at all. If you are using an [`Array`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array) (or a [`String`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/String) for some operations), consider using more semantic iteration methods instead, like [`map()`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/map), [`every()`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/every), [`findIndex()`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/findIndex), [`find()`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/find), [`includes()`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/includes), and many more. - -### Control statements - -There is one notable case to keep in mind for the `if...else` control statements. If the `if` statement ends with a `return`, do not add an `else` statement. - -Continue right after the `if` statement. Write: - -```js example-good -if (test) { - // Perform something if test is true - // … - return; -} - -// Perform something if test is false -// … -``` - -Do not write: - -```js example-bad -if (test) { - // Perform something if test is true - // … - return; -} else { - // Perform something if test is false - // … -} -``` - -### Use braces with control flow statements and loops - -While control flow statements like `if`, `for`, and `while` don't require the use of braces when the content is made of one single statement, you should always use braces. Write: - -```js example-good -for (const car of storedCars) { - car.paint("red"); -} -``` - -Don't write: - -```js example-bad -for (const car of storedCars) car.paint("red"); -``` - -This prevent forgetting to add the braces when adding more statements. - -### Switch statements - -Switch statements can be a little tricky. - -- Don't add a `break` statement after a `return` statement in a specific case. Instead, write `return` statements like this: - - ```js example-good - switch (species) { - case "chicken": - return farm.shed; - case "horse": - return corral.entry; - default: - return ""; - } - ``` - - If you add a `break` statement, it will be unreachable. Do not write: - - ```js example-bad - switch (species) { - case "chicken": - return farm.shed; - break; - case "horse": - return corral.entry; - break; - default: - return ""; - } - ``` - -- Use `default` as the last case, and don't end it with a `break` statement. If you need to do it differently, add a comment explaining why. - -- Remember that when you declare a local variable for a case, you need to use braces to define a scope: - - ```js - switch (fruits) { - case "Orange": { - const slice = fruit.slice(); - eat(slice); - break; - } - case "Apple": { - const core = fruit.extractCore(); - recycle(core); - break; - } - } - ``` - -### Error handling - -- If certain states of your program throw uncaught errors, they will halt execution and potentially reduce the usefulness of the example. You should, therefore, catch errors using a [`try...catch`](/en-US/docs/Web/JavaScript/Reference/Statements/try...catch) block, as shown below: - - ```js example-good - try { - console.log(getResult()); - } catch (e) { - console.error(e); - } - ``` - -- When you don't need the parameter of the `catch` statement, omit it: - - ```js example-good - try { - console.log(getResult()); - } catch { - console.error("An error happened!"); - } - ``` - -> [!NOTE] -> Keep in mind that only _recoverable_ errors should be caught and handled. All non-recoverable errors should be let through and bubble up the call stack. - -## Objects - -### Object names - -- When defining a class, use _PascalCase_ (starting with a capital letter) for the class name and _camelCase_ (starting with a lowercase letter) for the object property and method names. - -- When defining an object instance, either a literal or via a constructor, use _camelCase_, starting with lower-case character, for the instance name. For example: - - ```js example-good - const hanSolo = new Person("Han Solo", 25, "he/him"); - - const luke = { - name: "Luke Skywalker", - age: 25, - pronouns: "he/him", - }; - ``` - -### Object creation - -For creating general objects (i.e., when classes are not involved), use literals and not constructors. - -For example, do this: - -```js example-good -const object = {}; -``` - -Don't create a general object like this: - -```js example-bad -const object = new Object(); -``` - -### Object classes - -- Use ES class syntax for objects, not old-style constructors. - - For example, this is the recommended way: - - ```js example-good - class Person { - constructor(name, age, pronouns) { - this.name = name; - this.age = age; - this.pronouns = pronouns; - } - - greeting() { - console.log(`Hi! I'm ${this.name}`); - } - } - ``` - -- Use `extends` for inheritance: - - ```js example-good - class Teacher extends Person { - // … - } - ``` - -### Methods - -To define methods, use the method definition syntax: - -```js example-good -const obj = { - foo() { - // … - }, - bar() { - // … - }, -}; -``` - -Instead of: - -```js example-bad -const obj = { - foo: function () { - // … - }, - bar: function () { - // … - }, -}; -``` - -### Object properties - -- The [`Object.prototype.hasOwnProperty()`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object/hasOwnProperty) method has been deprecated in favor of [`Object.hasOwn()`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object/hasOwn). -- When possible, use the shorthand avoiding the duplication of the property identifier. Write: - - ```js example-good - function createObject(name, age) { - return { name, age }; - } - ``` - - Don't write: - - ```js example-bad - function createObject(name, age) { - return { name: name, age: age }; - } - ``` - -## Operators - -This section lists our recommendations of which operators to use and when. - -### Conditional operators - -When you want to store to a variable a literal value depending on a condition, use a [conditional (ternary) operator](/en-US/docs/Web/JavaScript/Reference/Operators/Conditional_operator) instead of an `if...else` statement. This rule also applies when returning a value. Write: - -```js example-good -const x = condition ? 1 : 2; -``` - -Do not write: - -```js example-bad -let x; -if (condition) { - x = 1; -} else { - x = 2; -} -``` - -The conditional operator is helpful when creating strings to log information. In such cases, using a regular `if...else` statement leads to long blocks of code for a side operation like logging, obfuscating the central point of the example. - -### Strict equality operator - -Prefer the [strict equality](/en-US/docs/Web/JavaScript/Reference/Operators/Strict_equality) (triple equals) and inequality operators over the loose equality (double equals) and inequality operators. - -Use the strict equality and inequality operators like this: - -```js example-good -name === "Shilpa"; -age !== 25; -``` - -Don't use the loose equality and inequality operators, as shown below: - -```js example-bad -name == "Shilpa"; -age != 25; -``` - -If you need to use `==` or `!=`, remember that `== null` is the only acceptable case. As TypeScript will fail on all other cases, we don't want to have them in our example code. Consider adding a comment to explain why you need it. - -### Shortcuts for boolean tests - -Prefer shortcuts for boolean tests. For example, use `if (x)` and `if (!x)`, not `if (x === true)` and `if (x === false)`, unless different kinds of truthy or falsy values are handled differently. - -## Strings - -String literals can be enclosed within single quotes, as in `'A string'`, or within double quotes, as in `"A string"`. Don't worry about which one to use; Prettier keeps it consistent. - -### Template literals - -For inserting values into strings, use [template literals](/en-US/docs/Web/JavaScript/Reference/Template_literals). - -- Here is an example of the recommended way to use template literals. Their use prevents a lot of spacing errors. - - ```js example-good - const name = "Shilpa"; - console.log(`Hi! I'm ${name}!`); - ``` - - Don't concatenate strings like this: - - ```js example-bad - const name = "Shilpa"; - console.log("Hi! I'm" + name + "!"); // Hi! I'mShilpa! - ``` - -- Don't overuse template literals. If there are no substitutions, use a normal string literal instead. - -## Variables - -### Variable names - -Good variable names are essential to understanding code. - -<!-- cSpell:ignore acclmtr --> - -- Use short identifiers, and avoid non-common abbreviations. Good variable names are usually between 3 to 10-character long, but as a hint only. For example, `accelerometer` is more descriptive than abbreviating to `acclmtr` for the sake of character length. -- Try to use real-world relevant examples where each variable has clear semantics. Only fall back to placeholder names like `foo` and `bar` when the example is simple and contrived. -- Do not use the [Hungarian notation](https://en.wikipedia.org/wiki/Hungarian_notation) naming convention. Do not prefix the variable name with its type. For example, write `bought = car.buyer !== null` rather than `bBought = oCar.sBuyer != null` or `name = "John Doe"` instead of `sName = "John Doe"`. -- For collections, avoid adding the type such as list, array, queue in the name. Use the content name in the plural form. For example, for an array of cars, use `cars` and not `carArray` or `carList`. There may be exceptions, like when you want to show the abstract form of a feature without the context of a particular application. -- For primitive values, use _camelCase_, starting with a lowercase character. Do not use `_`. Use concise, human-readable, and semantic names where appropriate. For example, use `currencyName` rather than `currency_name`. -- Avoid using articles and possessives. For example, use `car` instead of `myCar` or `aCar`. There may be exceptions, like when describing a feature in general without a practical context. -- Use variable names as shown here: - - ```js example-good - const playerScore = 0; - const speed = distance / time; - ``` - - Don't name variables like this: - - ```js example-bad - const thisIsaveryLONGVariableThatRecordsPlayerscore345654 = 0; - const s = d / t; - ``` - -> [!NOTE] -> The only place where it's allowed not to use human-readable, semantic names is where a very commonly recognized convention exists, such as using `i` and `j` for loop iterators. - -### Variable declarations - -When declaring variables and constants, use the [`let`](/en-US/docs/Web/JavaScript/Reference/Statements/let) and [`const`](/en-US/docs/Web/JavaScript/Reference/Statements/const) keywords, not [`var`](/en-US/docs/Web/JavaScript/Reference/Statements/var). The following examples show what's recommended and what's not on MDN Web Docs: - -- If a variable will not be reassigned, prefer `const`, like so: - - ```js example-good - const name = "Shilpa"; - console.log(name); - ``` - -- If you'll change the value of a variable, use `let` as shown below: - - ```js example-good - let age = 40; - age++; - console.log("Happy birthday!"); - ``` - -- The example below uses `let` where it should be `const`. The code will work, but we want to avoid this usage in MDN Web Docs code examples. - - ```js example-bad - let name = "Shilpa"; - console.log(name); - ``` - -- The example below uses `const` for a variable that gets reassigned. The reassignment will throw an error. - - ```js example-bad - const age = 40; - age++; - console.log("Happy birthday!"); - ``` - -- The example below uses `var`, polluting the global scope: - - ```js example-bad - var age = 40; - var name = "Shilpa"; - ``` - -- Declare one variable per line, like so: - - ```js example-good - let var1; - let var2; - let var3 = "Apapou"; - let var4 = var3; - ``` - - Do not declare multiple variables in one line, separating them with commas or using chain declaration. Avoid declaring variables like this: - - ```js-nolint example-bad - let var1, var2; - let var3 = var4 = "Apapou"; // var4 is implicitly created as a global variable; fails in strict mode - ``` - -### Type coercion - -Avoid implicit type coercions. In particular, avoid `+val` to force a value to a number and `"" + val` to force it to a string. Use `Number()` and `String()`, without `new`, instead. Write: - -```js example-good -class Person { - #name; - #birthYear; - - constructor(name, year) { - this.#name = String(name); - this.#birthYear = Number(year); - } -} -``` - -Don't write: - -```js example-bad -class Person { - #name; - #birthYear; - - constructor(name, year) { - this.#name = "" + name; - this.#birthYear = +year; - } -} -``` - -## Web APIs to avoid - -In addition to these JavaScript language features, we recommend a few guidelines related to Web APIs to keep in mind. - -### Avoid browser prefixes - -If all major browsers (Chrome, Edge, Firefox, and Safari) support a feature, don't prefix the feature. Write: - -```js example-good -const context = new AudioContext(); -``` - -Avoid the added complexity of prefixes. Don't write: - -```js example-bad -const AudioContext = window.AudioContext || window.webkitAudioContext; -const context = new AudioContext(); -``` - -The same rule applies to CSS prefixes. - -### Avoid deprecated APIs - -When a method, a property, or a whole interface is deprecated, do not use it (outside its documentation). Instead, use the modern API. - -Here is a non-exhaustive list of Web APIs to avoid and what to replace them with: - -- Use `fetch()` instead of XHR (`XMLHttpRequest`). -- Use `AudioWorklet` instead of `ScriptProcessorNode`, in the Web Audio API. - -### Use safe and reliable APIs - -- Do not use {{DOMxRef("Element.innerHTML")}} to insert purely textual content into an element; use {{DOMxRef("Node.textContent")}} instead. The property `innerHTML` leads to security problems if a developer doesn't control the parameter. The more we as writers avoid using it, the fewer security flaws are created when a developer copies and pastes our code. - - The example below demonstrates the use of `textContent`. - - ```js example-good - const text = "Hello to all you good people"; - const para = document.createElement("p"); - para.textContent = text; - ``` - - Don't use `innerHTML` to insert _pure text_ into DOM nodes. - - ```js example-bad - const text = "Hello to all you good people"; - const para = document.createElement("p"); - para.innerHTML = text; - ``` - -- The `alert()` function is unreliable. It doesn't work in live examples on MDN Web Docs that are inside an {{HTMLElement("iframe")}}. Moreover, it is modal to the whole window, which is annoying. In static code examples, use `console.log()` or `console.error()`. In [live examples](/en-US/docs/MDN/Writing_guidelines/Page_structures/Live_samples), avoid `console.log()` and `console.error()` because they are not displayed. Use a dedicated UI element. - -### Use the appropriate log method - -- When logging a message, use `console.log()`. -- When logging an error, use `console.error()`. - -## See also - -[JavaScript language reference](/en-US/docs/Web/JavaScript/Reference) - browse through our JavaScript reference pages to check out some good, concise, meaningful JavaScript snippets. diff --git a/files/en-us/mdn/writing_guidelines/writing_style_guide/code_style_guide/shell/index.md b/files/en-us/mdn/writing_guidelines/writing_style_guide/code_style_guide/shell/index.md deleted file mode 100644 index 532bcd874d39886..000000000000000 --- a/files/en-us/mdn/writing_guidelines/writing_style_guide/code_style_guide/shell/index.md +++ /dev/null @@ -1,42 +0,0 @@ ---- -title: Guidelines for writing shell prompt code examples -slug: MDN/Writing_guidelines/Writing_style_guide/Code_style_guide/Shell -page-type: mdn-writing-guide -sidebar: mdnsidebar ---- - -The following guidelines cover how to write Shell prompt code examples for MDN Web Docs. - -## What is a "shell" - -A shell is a program that waits for you to type in a command and then press the return key. To indicate which commands you should type, content on MDN Web Docs lists them in a code block, similar to code examples. - -Such a block looks like this: - -```bash example-good -# This may take a while... -git clone https://github.com/mdn/content -cd content -``` - -## General guidelines for shell prompt code examples - -### Choosing a format - -Opinions on correct indentation, whitespace, and line lengths have always been controversial. Discussions on these topics are a distraction from creating and maintaining content. - -On MDN Web Docs, we use [Prettier](https://prettier.io/) as a code formatter to keep the code style consistent (and to avoid off-topic discussions). You can consult our [configuration file](https://github.com/mdn/content/blob/main/.prettierrc.json) to learn about the current rules, and read the [Prettier documentation](https://prettier.io/docs/en/index.html). - -Prettier formats all the code and keeps the style consistent. Nevertheless, there are a few additional rules that you need to follow. - -### Writing shell code blocks - -When writing a shell code block: - -- Do not include a `$` or `>` at the beginning of a shell instruction. It confuses more than it helps and it is not useful when copying the instructions. -- Comments start with `#`. -- Choose "bash" to indicate the language in markdown. - -## See also - -[Django server-side development docs](/en-US/docs/Learn_web_development/Extensions/Server-side/Django) show good practice presentation of shell prompt commands. diff --git a/files/en-us/mdn/writing_guidelines/writing_style_guide/index.md b/files/en-us/mdn/writing_guidelines/writing_style_guide/index.md index ebda77b9763a700..14af64ed060d022 100644 --- a/files/en-us/mdn/writing_guidelines/writing_style_guide/index.md +++ b/files/en-us/mdn/writing_guidelines/writing_style_guide/index.md @@ -1,6 +1,6 @@ --- title: Writing style guide -short-title: Style guide +short-title: Writing style slug: MDN/Writing_guidelines/Writing_style_guide page-type: mdn-writing-guide sidebar: mdnsidebar @@ -78,7 +78,7 @@ In a guide or tutorial, the introductory paragraph(s) should inform the reader a > > You can call the **`fillText()`** method to draw a string's characters as filled with color instead of only drawing the outlines of the characters. -- **Example of an appropriate introduction**: Here we see a much better overview for the `strokeText()` method. +- **Example of an appropriate introduction**: The following section provides a much better overview for the `strokeText()` method. > The {{domxref("CanvasRenderingContext2D")}} method **`strokeText()`**, part of the [Canvas 2D API](/en-US/docs/Web/API/Canvas_API), strokes (draws the outlines of) the characters of a specified string, anchored at the position indicated by the given X and Y coordinates. > The text is drawn using the context's current {{domxref("CanvasRenderingContext2D.font", "font")}}, and is justified and aligned according to the {{domxref("CanvasRenderingContext2D.textAlign", "textAlign")}}, {{domxref("CanvasRenderingContext2D.textBaseline", "textBaseline")}}, and {{domxref("CanvasRenderingContext2D.direction", "direction")}} properties. @@ -125,6 +125,35 @@ This last example of dealing with the problem is arguably better. Not only is it grammatically more correct, but removes some of the complexity associated with dealing with genders across different languages that may have wildly different gender rules. This solution can make translation easier for both readers and translators. +### Use accessible language + +Avoid using spatial and directional words, such as "above", "below", "left", "right", or "here". These terms assume a specific visual layout, which may not apply to all users. They can also be unclear or misleading–especially for users relying on screen readers or those reading translated content, where directional language can be ambiguous or difficult to translate accurately. In responsive layouts, where the position of content can change depending on screen size, such directional references may become inaccurate. This kind of language can hinder accessibility and make it harder for all users to navigate or understand content. + +Instead, use descriptive phrases that clearly identify the section, concept, or element being referenced. Refer to sections by their titles or headings, and refer to examples or code snippets by what they demonstrate or contain. + +For example: + +- **Correct**: "Refer to the [Accessibility](/en-US/docs/Web/CSS/gradient/repeating-conic-gradient#accessibility) section later on this page." +- **Incorrect**: "Refer to the Accessibility section below." + +- **Correct**: "In the following code example, we animate a circle using CSS transitions." +- **Incorrect**: "In the code example below, we animate a circle using CSS transitions." + +- **Correct**: "This concept is explained in the earlier section titled Creating a media query." +- **Incorrect**: "This concept is explained in the section above." + +Additionally, avoid using vague link text like "Click here" or "Read this article". Descriptive link text provides better context for all readers and improves the experience for users of assistive technologies. + +<!-- markdownlint-disable descriptive-link-text --> + +- **Correct**: "Learn more about [how to order flex items](/en-US/docs/Web/CSS/CSS_flexible_box_layout/Ordering_flex_items)." +- **Incorrect**: "Click [here](/en-US/docs/Web/CSS/CSS_flexible_box_layout/Ordering_flex_items) to learn more." +- **Incorrect**: "Read [this article](/en-US/docs/Web/CSS/CSS_flexible_box_layout/Ordering_flex_items) to learn more." + +<!-- markdownlint-enable descriptive-link-text --> + +By following these guidelines, you help make MDN documentation accessible, clear, and usable by everyone, regardless of how they access the page. + ### Write with SEO in mind While the primary goal of any writing on MDN Web Docs should always be to explain and inform about open web technology so developers can quickly learn to do what they want or to find the little details they need to know in order to perfect their code, it's important that they be able to _find_ the material we write. We can achieve this by keeping Search Engine Optimization ({{Glossary("SEO")}}) in mind while writing. @@ -136,7 +165,7 @@ The following checklist is good to keep in mind while writing and reviewing cont - **Ensure that pages aren't too similar**: If the content on different pages is similar textually, search engines will assume that the pages are about the same thing even if they aren't. For example, if an interface has the properties `width` and `height`, it's easy for the text to be surprisingly similar on the two pages documenting these two properties, with just a few words swapped out and using the same example. This makes it hard for search engines to know which is which, and they wind up sharing page rank, resulting in both being harder to find than they ought to be. - It's important, then, to ensure that every page has its own content. Here are some suggestions to help you accomplish that: + It's important, then, to ensure that every page has its own content. The following suggestions can help you accomplish that: - **Explain more unique concepts**: Consider use cases where there might be more differences than one would think. For instance, in the case of documenting `width` and `height` properties, perhaps write about the ways horizontal space and vertical space are used differently, and provide a discussion about the appropriate concepts. Perhaps you can mention the use of `width` in terms of making room for a sidebar, while using `height` to handle vertical scrolling or footers. Including information about accessibility issues is a useful and important idea as well. - **Use different examples**: Examples in these situations are often even more similar than the body text because the examples may use both (or all) of the similar methods or properties to begin with, thereby requiring no real changes when reused. So throw out the example and write a new one, or at least provide multiple examples, with at least some of them different. @@ -146,15 +175,15 @@ The following checklist is good to keep in mind while writing and reviewing cont - **Ensure that pages aren't too short**: If the content on a page is too little (called "thin pages" in SEO parlance), search engines will not catalog such pages accurately (or at all). Overly-short content pages are hard to find. As a guiding principle, ensure that pages on MDN Web Docs are not shorter than around 300 words or so. Don't artificially inflate a page, but treat this guideline as a minimum target length when possible. - Here are some basic guidelines to help you create pages that have enough content to be properly searchable without resorting to cluttering them up with unnecessary text: + These basic guidelines can help you create pages that have enough content to be properly searchable without resorting to cluttering them up with unnecessary text: - **Avoid stubs**: Obviously, if the article is a stub or is missing content, add it. We try to avoid outright "stub" pages on MDN web Docs, although they do exist, but there are plenty of pages that are missing large portions of their content. - **Review page structure**: Review the page to ensure that it's structured properly for its [page type](/en-US/docs/MDN/Writing_guidelines/Page_structures/Page_types) it is. Check to make sure that all sections are present and have appropriate content. - **Ensure completeness**: Review sections to ensure that no information is missing. Ensure that all parameters are listed and explained. Ensure that any exceptions are covered — this is a particularly common place where content is missing. - **Ensure all concepts are fully fleshed-out**: It's easy to give a quick explanation of something, but make sure that all the nuances are covered. Are there special cases? Are there any known restrictions that the reader might need to know about? - - **Add examples**: There should be examples covering all parameters or at least the parameters (or properties, or attributes) that users from the beginner-through-intermediate range are likely to use, as well as any advanced ones that require extra explanation. Each example should be preceded with an overview of what the example will do, what additional knowledge might be needed to understand it, and so forth. After the example (or interspersed among pieces of the example) should be text explaining how the code works. Don't skimp on the details or the handling of errors in examples. Keep in mind that users _will_ copy and paste your example to use in their own projects, and your code _will_ wind up used on production sites! See our [code example guidelines](/en-US/docs/MDN/Writing_guidelines/Writing_style_guide/Code_style_guide) for more useful information. + - **Add examples**: There should be examples covering all parameters or at least the parameters (or properties, or attributes) that users from the beginner-through-intermediate range are likely to use, as well as any advanced ones that require extra explanation. Each example should be preceded with an overview of what the example will do, what additional knowledge might be needed to understand it, and so forth. After the example (or interspersed among pieces of the example) should be text explaining how the code works. Don't skimp on the details or the handling of errors in examples. Keep in mind that users _will_ copy and paste your example to use in their own projects, and your code _will_ wind up used on production sites! See our [code example guidelines](/en-US/docs/MDN/Writing_guidelines/Code_style_guide) for more useful information. - **Explain use cases**: If there are particularly common use cases for the feature being described, talk about them! Instead of assuming that a user will figure out that the method being documented can be used to solve a common development problem, actually add a section about that use case with an example and text explaining how the example works. - - **Add image information**: Include proper [`alt`](/en-US/docs/Web/HTML/Element/img#alt) text on all images and diagrams. This text, as well as captions on tables and other figures, counts because spiders can't crawl images, and so `alt` text tells search engine crawlers what content the embedded media contains. + - **Add image information**: Include proper [`alt`](/en-US/docs/Web/HTML/Reference/Elements/img#alt) text on all images and diagrams. This text, as well as captions on tables and other figures, counts because spiders can't crawl images, and so `alt` text tells search engine crawlers what content the embedded media contains. > [!NOTE] > It is not recommended to include too many keywords or keywords not related to the feature in an attempt to manipulate search engine rankings; this type of behavior is easy to spot and tends to be penalized. > Likewise, **do not** add repetitive, unhelpful material or blobs of keywords within the actual page, in an attempt to improve the page's size and search ranking. This does more harm than good, both to content readability and to our search results. @@ -193,21 +222,27 @@ An abbreviation is a shortened version of a longer word, while an acronym is a n - **Latin abbreviations**: You can use common Latin abbreviations (etc., i.e., e.g.) in parenthetical expressions and notes. Use periods in these abbreviations, followed by a comma or other appropriate punctuation. + <!-- markdownlint-disable search-replace --> + - **Correct**: Web browsers (e.g., Firefox) can be used ... - **Incorrect**: Web browsers e.g. Firefox can be used ... - **Incorrect**: Web browsers, e.g. Firefox, can be used ... - **Incorrect**: Web browsers, (eg: Firefox) can be used ... + <!-- markdownlint-enable search-replace --> + In regular text (i.e., text outside of notes or parentheses), use the English equivalent of the abbreviation. - **Correct**: ... web browsers, and so on. - **Incorrect**: ... web browsers, etc. - **Correct**: Web browsers such as Firefox can be used ... - - **Incorrect**: Web browsers e.g. Firefox can be used ... + - **Incorrect**: Web browsers e.g., Firefox can be used ... The following table summarizes the meanings and English equivalents of Latin abbreviations: + <!-- markdownlint-disable search-replace --> + | Abbrev | Latin | English | | ------ | ---------------- | ----------------------- | | cf. | _confer_ | compare | @@ -218,6 +253,8 @@ An abbreviation is a shortened version of a longer word, while an acronym is a n | N.B. | _nota bene_ | note well | | P.S. | _post scriptum_ | postscript | + <!-- markdownlint-enable search-replace --> + > [!NOTE] > Always consider whether it's truly beneficial to use a Latin abbreviation. Some of these are used so rarely that many readers will either confuse or fail to understand their meanings. > @@ -300,16 +337,16 @@ Do not use "curly" quotes and quotation marks. On MDN Web Docs, we only use stra ### Commas -The list below describes some of the common situations where we need to be aware of the comma usage rules: +The following list describes some of the common situations where we need to be aware of the comma usage rules: - **After introductory clauses**: An introductory clause is a dependent clause, usually found at the beginning of a sentence. Use a comma after an introductory clause to separate it from the following independent clause. - Example 1: - - **Correct**: "In this example, you will see how to use a comma." - - **Incorrect**: "In this example you will see how to use a comma." + - **Correct**: "In this example, you will learn how to use a comma." + - **Incorrect**: "In this example you will learn how to use a comma." - Example 2: - - **Correct**: "If you are looking for guidelines, you have come to the right place." - - **Incorrect**: "If you are looking for guidelines you have come to the right place." + - **Correct**: "If you are looking for guidelines, refer to our writing style guide." + - **Incorrect**: "If you are looking for guidelines refer to our writing style guide." - Example 3: - **Correct**: "On mobile platforms, you tend to get a numeric keypad for entering data." - **Incorrect**: "On mobile platforms you tend to get a numeric keypad for entering data." @@ -348,7 +385,7 @@ The list below describes some of the common situations where we need to be aware - **Correct**: "The Array object has methods for manipulating arrays in various ways, such as joining, reversing, and sorting them." - **Incorrect**: "The Array object has methods for manipulating arrays in various ways such as joining, reversing, and sorting them." - The example below shows when not to use comma with "such as". Here the clause containing "such as" is essential for the meaning of the sentence. + The following example shows when not to use a comma with "such as". In this case, the clause containing "such as" is essential for the meaning of the sentence. - **Correct**: "Web applications are becoming more powerful by adding features such as audio and video manipulation and allowing access to raw data using WebSockets." - **Incorrect**: "Web applications are becoming more powerful by adding features, such as audio and video manipulation, and allowing access to raw data using WebSockets." @@ -373,10 +410,10 @@ Do not use variant spelling. - **Correct**: localize, behavior, color - **Incorrect**: localise, behaviour, colour -We have [cSpell](https://cspell.org/) installed to catch spelling errors. It runs every week and generates [a report of spelling errors](https://github.com/mdn/content/issues?q=Weekly+spelling+check+is%3Aissue+in%3Atitle) in the repository. You can also run it locally via the following command: +We have [cSpell](https://cspell.org/) installed to catch spelling errors. It runs every week and generates [a report of spelling errors](https://github.com/mdn/content/issues?q=Weekly+spelling+check+is%3Aissue+in%3Atitle) in the repository. You can also run it locally using the following command: ```bash -npx cspell --no-progress --gitignore --config .vscode/cspell.json "**/*.md" +yarn lint:typos ``` In the repository, we maintain several word lists, located at [`.vscode/dictionaries`](https://github.com/mdn/content/tree/main/.vscode/dictionaries), that contain sanctioned words not in the default dictionaries. You can add more words to these lists if they are valid but reported by the spell checker. Read [`.vscode/cspell.json`](https://github.com/mdn/content/blob/main/.vscode/cspell.json) to understand what each dictionary contains and the details of our spell-checking configuration. @@ -385,7 +422,7 @@ In the repository, we maintain several word lists, located at [`.vscode/dictiona These are our recommendations for using certain technical terms: -- **HTML elements**: Use the term "element" to refer to HTML and XML elements, instead of "tag". In addition, the element should be wrapped in angle brackets "<>" and should be styled using backticks (\`). For example, using \<input\> inside backticks will style it as `<input>` as is expected. +- **HTML elements**: Use the term "element" to refer to HTML and XML elements, instead of "tag". In addition, the element should be wrapped in angle brackets "<>" and should be styled using backticks (`` ` ``). For example, using \<input\> inside backticks will style it as `<input>` as is expected. - **Correct**: the `<span>` element - **Incorrect**: the span tag @@ -429,34 +466,29 @@ A page on MDN Web Docs can contain more than one code example. The following lis - Each piece of example code should include: - **Heading**: A short `###` (`<h3>`) heading to describe the scenario being demonstrated through the code example. For example, "Using offset printing" and "Reverting to style in previous layer". - - **Description**: A short description preceding the example code that states the specifics of the example to which you want to draw the reader's attention. For example, "In the example below, two cascade layers are defined in the CSS, `base` and `special`." + - **Description**: A short description preceding the example code that states the specifics of the example to which you want to draw the reader's attention. For example, "In the following example, two cascade layers are defined in the CSS, `base` and `special`." - **Result explanation**: An explanation after the example code that describes the result and how the code works. - In general, the code example should not only demonstrate the syntax of the feature and how it is used, but also highlight the purpose and situations in which a web developer might want or need to use the feature. - If you are working with a large piece of example code, it may make sense to break it up into smaller logical parts so that they can be described individually. - When adding [live samples](/en-US/docs/MDN/Writing_guidelines/Page_structures/Live_samples), it's helpful to be aware that all of the sample's code blocks that have the same type (HTML, CSS, and JavaScript) are concatenated together before running the example. This lets you break the code into multiple segments, each optionally with its own descriptions, headings, and so forth. This makes documenting code incredibly powerful and flexible. -To learn about how to style or format code examples for MDN Web Docs, see [Guidelines for styling code examples](/en-US/docs/MDN/Writing_guidelines/Writing_style_guide/Code_style_guide). +To learn about how to style or format code examples for MDN Web Docs, see our [Guidelines for styling code examples](/en-US/docs/MDN/Writing_guidelines/Code_style_guide). ### Cross-references (linking) When referencing another page or the section of a page on MDN by its title, follow sentence casing in the link text (match the page or section title). Use sentence casing in the link text even if it is different from the linked page title or section title (it might be that the case used in the page or section title is incorrect). Don't use quotation marks around the link text. To refer to a page on MDN by its title, use the following style: -- **Correct**: "See the [Ordering flex items](/en-US/docs/Web/CSS/CSS_flexible_box_layout/Ordering_flex_items) guide." -- **Incorrect**: "See the "[Ordering flex items](/en-US/docs/Web/CSS/CSS_flexible_box_layout/Ordering_flex_items)" guide." - -Follow similar style when linking to a section on a page, as shown below: +- **Correct**: "Refer to the [Ordering flex items](/en-US/docs/Web/CSS/CSS_flexible_box_layout/Ordering_flex_items) guide." +- **Incorrect**: "Refer to the "[Ordering flex items](/en-US/docs/Web/CSS/CSS_flexible_box_layout/Ordering_flex_items)" guide." -- **Correct**: "For more information, see the [Allocation in JavaScript](/en-US/docs/Web/JavaScript/Memory_management#allocation_in_javascript) section on the _Memory management_ page." +Follow a consistent style when linking to sections within a page: -If the section you're linking to is on the same page, you can hint at the location of the section using the words "above" or "below". +- **Correct**: "For more information, refer to the [Allocation in JavaScript](/en-US/docs/Web/JavaScript/Guide/Memory_management#allocation_in_javascript) section in the _Memory management_ guide." -- **Correct**: "This concept is described in more detail in the [Accessibility](/en-US/docs/Web/CSS/gradient/repeating-conic-gradient#accessibility) section below." +If the section you're linking to is on the same page, you can hint at the location of the section using descriptive phrases. -You can link part of a sentence to an article or the section of an article. Be mindful to use descriptive phrases as link texts to provide enough context for the page being linked. - -- **Correct**: "Learn more about [how to order flex items](/en-US/docs/Web/CSS/CSS_flexible_box_layout/Ordering_flex_items)." -- **Incorrect**: "Click [here](/en-US/docs/Web/CSS/CSS_flexible_box_layout/Ordering_flex_items) to learn more." -- **Incorrect**: "Read [this article](/en-US/docs/Web/CSS/CSS_flexible_box_layout/Ordering_flex_items) to learn more." +- **Correct**: "This concept is described in more detail in the [Accessibility](/en-US/docs/Web/CSS/gradient/repeating-conic-gradient#accessibility) section of this document." +- **Incorrect**: "This concept is described in more detail in the [Accessibility](/en-US/docs/Web/CSS/gradient/repeating-conic-gradient#accessibility) section below." On MDN, another way to link to a reference page is by using a macro. These macros are described on the [Commonly-used macros](/en-US/docs/MDN/Writing_guidelines/Page_structures/Macros/Commonly_used_macros#linking_to_pages_in_references) page. For example, to link to the reference page of an HTML element, use the `HTMLElement` macro, and to link to the reference page of a CSS property, use the `CSSxRef` macro. @@ -464,9 +496,9 @@ We follow similar cross-referencing guidelines in the [See also](#see_also) sect ### External links -External links are allowed on MDN Web Docs in specific situations. Use the guidelines described in this section to decide whether or not it is okay to include an external link on MDN Web Docs. Your pull request to add an external link will be rejected if it does not meet the guidelines described here. +External links are allowed on MDN Web Docs in specific situations. Use the guidelines described in this section to decide whether or not it is okay to include an external link on MDN Web Docs. Pull requests that add external links will be rejected if they don't follow these guidelines. -If you are considering adding an external link to MDN [Learn web development](/en-US/docs/Learn_web_development) content, please also read [Learn web development writing guidelines > External links and embeds](/en-US/docs/MDN/Writing_guidelines/Learning_content#external_links_and_embeds). +If you are considering adding an external link to MDN's [Learn web development](/en-US/docs/Learn_web_development) content, please also read [Learn web development writing guidelines > Partner links and embeds](/en-US/docs/MDN/Writing_guidelines/Learning_content#partner_links_and_embeds). In general, if you're considering adding an external link, you need to ensure that there is minimal risk of the following: @@ -506,21 +538,25 @@ A URL shortener (such as TinyURL or Bitly) can be great for shortening long link Do not use links created via third-party (user-generatable) URL shorteners. For example, if `https://myshort.link/foobar` is a short URL generated by a random user and redirects to `https://example.com/somelongURL/details/show?page_id=foobar`, use the longer `example.com` URL. +<!-- markdownlint-disable search-replace --> + On the other hand, first-party shorteners that are maintained by the organizations that also maintain the destination URLs are encouraged. `https://bugzil.la` is owned and operated by Mozilla and is a URL shortener that redirects to `https://bugzilla.mozilla.org/`, which is also a Mozilla-owned domain. In this case, use the shorter URL. For example, use `https://bugzil.la/1682349` instead of `https://bugzilla.mozilla.org/show_bug.cgi?id=1682349`. +<!-- markdownlint-enable search-replace --> + ### Heading levels When a new paragraph starts a new section, a header should be added. -Use these markdown heading levels in decreasing order without skipping levels: `##`, then `###`, and then `####`; these translate to the [HTML heading tags](/en-US/docs/Web/HTML/Element/Heading_Elements) `<h2>`, `<h3>`, and `<h4>` tags, respectively. +Use these markdown heading levels in decreasing order without skipping levels: `##`, then `###`, and then `####`; these translate to the [HTML heading tags](/en-US/docs/Web/HTML/Reference/Elements/Heading_Elements) `<h2>`, `<h3>`, and `<h4>` tags, respectively. `##` is the highest level allowed because `#` is reserved for the page title. -We recommend to not add more than three levels of headers. If you feel the need for adding the fourth header level, consider breaking up the article into several smaller articles with a landing page. Alternatively, see if you can present the information in bulleted points to avoid adding level four header. +We recommend to not add more than three levels of headers. If you feel the need for adding the fourth header level, consider breaking up the article into several smaller articles with a landing page. Alternatively, consider presenting the information as bulleted points to avoid using a level-four header. Keep the following dos and don'ts in mind while creating headings for subsections: - **Don't create single subsections.** Don't subdivide a topic into a single subtopic. It's either two subheadings or more or none at all. -- **Don't use inline styles, classes, or macros within headings.** However, you can use backticks to indicate code terms (e.g. "Using `FooBar` interface"). +- **Don't use inline styles, classes, or macros within headings.** However, you can use backticks to indicate code terms (e.g., "Using `FooBar` interface"). - **Don't create "bumping heads".** These are headings followed immediately by a subheading, with no content text in between them. This doesn't look good and leaves readers without any explanatory text at the beginning of the outer section. @@ -537,7 +573,7 @@ If you include images or other media on a page, follow these guidelines: Lists should be formatted and structured consistently across all pages. Individual list items should be written with suitable punctuation, regardless of the list format. -However, depending on the type of list you are creating, you will want to adjust your writing as described in the sections below. In both cases, include a lead-in sentence that describes the information in the list. +However, depending on the type of list you are creating, you will want to adjust your writing as described in the sections that follow. In both cases, include a lead-in sentence that describes the information in the list. - **Bulleted lists**: Bulleted lists should be used to group related pieces of concise information. Each item in the list should follow a similar sentence structure. Sentences and phrases (i.e., sentence fragments missing a verb or a subject or both) in bulleted lists should include standard punctuation — sentences end with periods, phrases don't. @@ -569,7 +605,7 @@ However, depending on the type of list you are creating, you will want to adjust > Your instructions may be quite extensive, so it is important to write clearly and use correct punctuation. > 3. After you have finished your instructions, follow the numbered list with a brief closing summary or explanation about the expected outcome upon completion. - The following is an example of writing a closing explanation for the above list: + The following is an example of writing a closing explanation for the preceding list: > We have created a short numbered list that provides instructive steps to produce a numbered list with the correct formatting. @@ -585,10 +621,10 @@ To maintain consistency across MDN Web Docs, keep the following guidelines in mi #### Link text -- The link text should be the same as the title of the page or the section being linked to. For example, the link text to this [ARIA](/en-US/docs/Web/Accessibility/ARIA/Attributes) page with the page title "ARIA states and properties" will be: - - **Correct**: [ARIA states and properties](/en-US/docs/Web/Accessibility/ARIA/Attributes) -- Use sentence casing in the link text even if it is different from the linked page title or section title. It might be that the case used in the page or section title is incorrect. For example, the link text to the [Quirks Mode](/en-US/docs/Web/HTML/Quirks_Mode_and_Standards_Mode) page in correct sentence case will be: - - **Correct**: [Quirks mode](/en-US/docs/Web/HTML/Quirks_Mode_and_Standards_Mode) +- The link text should be the same as the title of the page or the section being linked to. For example, the link text to this [ARIA](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes) page with the page title "ARIA states and properties" will be: + - **Correct**: [ARIA states and properties](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes) +- Use sentence casing in the link text even if it is different from the linked page title or section title. It might be that the case used in the page or section title is incorrect. For example, the link text to the [Quirks Mode](/en-US/docs/Web/HTML/Guides/Quirks_mode_and_standards_mode) page in correct sentence case will be: + - **Correct**: [Quirks mode](/en-US/docs/Web/HTML/Guides/Quirks_mode_and_standards_mode) - For external links as well, use sentence casing even if the casing on the target article page is different. This is to ensure consistency across MDN Web Docs. Exceptions include names of books. - On MDN, you can optionally use a macro to link to a page, as is explained in the [Linking to pages in references](/en-US/docs/MDN/Writing_guidelines/Page_structures/Macros/Commonly_used_macros#linking_to_pages_in_references) section on the _Commonly used macros_ page. The use of macro will add code formatting to the keyword in the link text, as shown in the next example. - No article ("A", "An", "The") is needed at the beginning of the link list item. No punctuation is required at the end of the list item because it will invariably be a term or a phrase. @@ -596,7 +632,7 @@ To maintain consistency across MDN Web Docs, keep the following guidelines in mi - **Incorrect**: The [`revert-layer`](/en-US/docs/Web/CSS/revert-layer) keyword. - **Correct**: [HTML DOM API](/en-US/docs/Web/API/HTML_DOM_API) - **Incorrect**: The [HTML DOM API](/en-US/docs/Web/API/HTML_DOM_API) -- As shown in the above examples, add code formatting using backticks (\`) to keywords and literals in the link text, even though the formatting is not used in page and section titles. For example, for the page title "Array() constructor", the link text will be [`Array()` constructor](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/Array). +- As shown in the previous examples, add code formatting using backticks (`` ` ``) to keywords and literals in the link text, even though the formatting is not used in page and section titles. For example, for the page title "Array() constructor", the link text will be [`Array()` constructor](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/Array). #### Descriptive text @@ -606,7 +642,7 @@ To maintain consistency across MDN Web Docs, keep the following guidelines in mi - **Correct**: {{cssxref("background-color")}}, {{cssxref("border-color")}}, {{cssxref("color")}}, {{cssxref("caret-color")}}, {{cssxref("column-rule-color")}}, {{cssxref("outline-color")}}, {{cssxref("text-decoration-color")}}, {{cssxref("text-emphasis-color")}}, {{cssxref("text-shadow")}}: Other color-related properties - For external links, aim to specify the source website and the year of publication or last update (in parentheses) whenever feasible and appropriate. Providing this information upfront gives readers a clear idea of the destination they'll reach upon clicking the link. The date of publication or last update guides readers in assessing the relevance of the linked article and also helps MDN maintainers to review links to articles that have not been updated in a long time. If you provide a link to an article on Wikipedia, for example, you can ignore the publish/update date. The following list item is an example of adding a link to the [Top-level await](https://v8.dev/features/top-level-await) external article in the See also section, along with the source and year information: - **Correct**: [Top-level await](https://v8.dev/features/top-level-await) on v8.dev (2019) -- For external links to books, you can also provide author names. You can see a few examples for this in the [Further reading](#language_grammar_and_spelling) section below. Refrain from adding author names for blog posts or GitHub repositories you might link to. +- For external links to books, you can also provide author names. A few examples are listed in the [Further reading](#language_grammar_and_spelling) section. Refrain from adding author names for blog posts or GitHub repositories you might link to. #### Order of links @@ -625,7 +661,7 @@ For example, consider the [JavaScript](/en-US/docs/Web/JavaScript) guide, which - [JavaScript/Guide](/en-US/docs/Web/JavaScript/Guide) – Main table-of-contents page - [JavaScript/Guide/JavaScript Overview](/en-US/docs/Web/JavaScript/Guide/Introduction) - [JavaScript/Guide/Functions](/en-US/docs/Web/JavaScript/Guide/Functions) -- [JavaScript/Guide/Details of the Object Model](/en-US/docs/Web/JavaScript/Inheritance_and_the_prototype_chain) +- [JavaScript/Guide/Details of the Object Model](/en-US/docs/Web/JavaScript/Guide/Inheritance_and_the_prototype_chain) Try to avoid putting your article at the top of the hierarchy, which slows the site down and makes search and site navigation less effective. @@ -666,17 +702,17 @@ Keep the following guidelines in mind when writing titles: ## See also -- [Guidelines for writing code examples](/en-US/docs/MDN/Writing_guidelines/Writing_style_guide/Code_style_guide) -- [Guidelines for writing HTML code examples](/en-US/docs/MDN/Writing_guidelines/Writing_style_guide/Code_style_guide/HTML) -- [Guidelines for writing CSS code examples](/en-US/docs/MDN/Writing_guidelines/Writing_style_guide/Code_style_guide/CSS) -- [Guidelines for writing JavaScript code examples](/en-US/docs/MDN/Writing_guidelines/Writing_style_guide/Code_style_guide/JavaScript) -- [Guidelines for writing shell prompt code examples](/en-US/docs/MDN/Writing_guidelines/Writing_style_guide/Code_style_guide/Shell) +- [Guidelines for writing code examples](/en-US/docs/MDN/Writing_guidelines/Code_style_guide) +- [Guidelines for writing HTML code examples](/en-US/docs/MDN/Writing_guidelines/Code_style_guide/HTML) +- [Guidelines for writing CSS code examples](/en-US/docs/MDN/Writing_guidelines/Code_style_guide/CSS) +- [Guidelines for writing JavaScript code examples](/en-US/docs/MDN/Writing_guidelines/Code_style_guide/JavaScript) +- [Guidelines for writing shell prompt code examples](/en-US/docs/MDN/Writing_guidelines/Code_style_guide/Shell) ## Further reading ### Other style guides -If you have questions about usage and style not covered here, we recommend referring to the [Microsoft Writing Style Guide](https://learn.microsoft.com/en-us/style-guide/welcome/) or the [Chicago Manual of Style](https://www.chicagomanualofstyle.org/). +If you have questions about usage and style not covered in this guide, we recommend referring to the [Microsoft Writing Style Guide](https://learn.microsoft.com/en-us/style-guide/welcome/) or the [Chicago Manual of Style](https://www.chicagomanualofstyle.org/). ### Language, grammar, and spelling diff --git a/files/en-us/mozilla/add-ons/contact_us/index.md b/files/en-us/mozilla/add-ons/contact_us/index.md index 57e07c58fe40020..124a9bc6cd7f288 100644 --- a/files/en-us/mozilla/add-ons/contact_us/index.md +++ b/files/en-us/mozilla/add-ons/contact_us/index.md @@ -12,10 +12,6 @@ Use the links below to get help, to keep up to date with add-ons news, and to gi Use the [Add-ons Discourse forum](https://discourse.mozilla.org/c/add-ons/35) to discuss all aspects of add-on development and to request help. -### Mailing lists - -The **dev-addons mailing list** was retired on December 1, 2020. You can view the [dev-addons archives](https://mail.mozilla.org/pipermail/dev-addons/) to see past discussions about the WebExtensions API and addons.mozilla.org. - ### Chat [Matrix](https://matrix.org/) is an open, lightweight protocol for decentralized, real-time communications. For information on how to join Mozilla's Matrix instance, refer to the [Matrix page on MozillaWiki](https://wiki.mozilla.org/Matrix). @@ -31,4 +27,4 @@ If you discover an add-on security vulnerability, even if the add-on is not host #### Bugs on addons.mozilla.org (AMO) -If you find a problem with the site, we'd love to fix it. Please [file a bug report](https://github.com/mozilla/addons/issues/new) and include as much detail as possible. +If you find a problem with the site, we'd love to fix it. Please [file a bug report](https://github.com/mozilla/addons/issues/new/choose) and include as much detail as possible. diff --git a/files/en-us/mozilla/add-ons/index.md b/files/en-us/mozilla/add-ons/index.md index 63728b53eda0a87..517b18f011b31cd 100644 --- a/files/en-us/mozilla/add-ons/index.md +++ b/files/en-us/mozilla/add-ons/index.md @@ -24,7 +24,7 @@ Extensions written using WebExtensions APIs for Firefox are designed to be cross ### Extension Workshop -The [Firefox Extension Workshop](https://extensionworkshop.com) can help you develop extensions for Firefox and give your users simple, yet powerful ways to customize their browsing experience. You'll find: +The [Firefox Extension Workshop](https://extensionworkshop.com/) can help you develop extensions for Firefox and give your users simple, yet powerful ways to customize their browsing experience. You'll find: - [Overview of the Firefox extension features](https://extensionworkshop.com/#about) - [Tools and processes for developing and testing](https://extensionworkshop.com/documentation/develop/) @@ -40,7 +40,7 @@ In 2020, Mozilla will release a new Firefox for Android experience. This new, hi ## Publishing add-ons -[Addons.mozilla.org](https://addons.mozilla.org), commonly known as "AMO," is Mozilla's official site for developers to list add-ons, and for users to discover them. By uploading your add-on to AMO, you can participate in our community of users and creators and find an audience for your add-on. +[Addons.mozilla.org](https://addons.mozilla.org/), commonly known as "AMO," is Mozilla's official site for developers to list add-ons, and for users to discover them. By uploading your add-on to AMO, you can participate in our community of users and creators and find an audience for your add-on. You are not required to list your add-on on AMO, but your add-on must be signed by Mozilla else users will not be able to install it. diff --git a/files/en-us/mozilla/add-ons/webextensions/anatomy_of_a_webextension/index.md b/files/en-us/mozilla/add-ons/webextensions/anatomy_of_a_webextension/index.md index 553a7d22ad1cfb5..76b6d0cf1bec0da 100644 --- a/files/en-us/mozilla/add-ons/webextensions/anatomy_of_a_webextension/index.md +++ b/files/en-us/mozilla/add-ons/webextensions/anatomy_of_a_webextension/index.md @@ -87,6 +87,6 @@ See the [content scripts](/en-US/docs/Mozilla/Add-ons/WebExtensions/Content_scri Web accessible resources are resources—such as images, HTML, CSS, and JavaScript—that you include in the extension and want to make accessible to content scripts and page scripts. Resources which are made web-accessible can be referenced by page scripts and content scripts using a special URI scheme. -For example, if a content script wants to insert some images into web pages, you could include them in the extension and make them web accessible. Then the content script could create and append [`img`](/en-US/docs/Web/HTML/Element/img) tags which reference the images via the `src` attribute. +For example, if a content script wants to insert some images into web pages, you could include them in the extension and make them web accessible. Then the content script could create and append [`img`](/en-US/docs/Web/HTML/Reference/Elements/img) tags which reference the images via the `src` attribute. To learn more, see the documentation for the [`"web_accessible_resources"`](/en-US/docs/Mozilla/Add-ons/WebExtensions/manifest.json/web_accessible_resources) `manifest.json` key. diff --git a/files/en-us/mozilla/add-ons/webextensions/api/action/setbadgebackgroundcolor/index.md b/files/en-us/mozilla/add-ons/webextensions/api/action/setbadgebackgroundcolor/index.md index 0fcbc4d661aef00..3b8bfb25ccc808a 100644 --- a/files/en-us/mozilla/add-ons/webextensions/api/action/setbadgebackgroundcolor/index.md +++ b/files/en-us/mozilla/add-ons/webextensions/api/action/setbadgebackgroundcolor/index.md @@ -35,7 +35,7 @@ browser.action.setBadgeBackgroundColor( - : The color, specified as one of: - a string: any CSS [\<color>](/en-US/docs/Web/CSS/color_value) value, for example `"red"`, `"#FF0000"`, or `"rgb(255 0 0)"`. If the string is not a valid color, the returned promise will be rejected and the background color won't be altered. - - a `{{WebExtAPIRef('action.ColorArray')}}` object. + - a {{WebExtAPIRef('action.ColorArray')}} object. - `null`. If a `tabId` is specified, it removes the tab-specific badge background color so that the tab inherits the global badge background color. Otherwise it reverts the global badge background color to the default value. - `tabId` {{optional_inline}} diff --git a/files/en-us/mozilla/add-ons/webextensions/api/action/setbadgetextcolor/index.md b/files/en-us/mozilla/add-ons/webextensions/api/action/setbadgetextcolor/index.md index d3733e563e74c56..64c694f431cbc66 100644 --- a/files/en-us/mozilla/add-ons/webextensions/api/action/setbadgetextcolor/index.md +++ b/files/en-us/mozilla/add-ons/webextensions/api/action/setbadgetextcolor/index.md @@ -31,7 +31,7 @@ browser.action.setBadgeTextColor( - : The color, specified as one of: - a string: any CSS [\<color>](/en-US/docs/Web/CSS/color_value) value, for example `"red"`, `"#FF0000"`, or `"rgb(255 0 0)"`. If the string is not a valid color, the returned promise will be rejected and the text color won't be altered. - - a `{{WebExtAPIRef('action.ColorArray')}}` object. + - a {{WebExtAPIRef('action.ColorArray')}} object. - `null`. If a `tabId` is specified, it removes the tab-specific badge text color so that the tab inherits the global badge text color. Otherwise it reverts the global badge text color to the default value. - `tabId` {{optional_inline}} diff --git a/files/en-us/mozilla/add-ons/webextensions/api/action/seticon/index.md b/files/en-us/mozilla/add-ons/webextensions/api/action/seticon/index.md index ef9f7964f7824d6..da793f6358d21f6 100644 --- a/files/en-us/mozilla/add-ons/webextensions/api/action/seticon/index.md +++ b/files/en-us/mozilla/add-ons/webextensions/api/action/seticon/index.md @@ -36,7 +36,7 @@ let settingIcon = browser.action.setIcon( - `imageData` {{optional_inline}} - - : `{{WebExtAPIRef('action.ImageDataType')}}` or `object`. This is either a single `ImageData` object or a dictionary object. + - : {{WebExtAPIRef('action.ImageDataType')}} or `object`. This is either a single `ImageData` object or a dictionary object. Use a dictionary object to specify multiple `ImageData` objects in different sizes, so the icon does not have to be scaled for a device with a different pixel density. If `imageData` is a dictionary, the value of each property is an `ImageData` object, and its name is its size, like this: diff --git a/files/en-us/mozilla/add-ons/webextensions/api/action/setpopup/index.md b/files/en-us/mozilla/add-ons/webextensions/api/action/setpopup/index.md index 427bcc51f792808..f5f31ada8ac658a 100644 --- a/files/en-us/mozilla/add-ons/webextensions/api/action/setpopup/index.md +++ b/files/en-us/mozilla/add-ons/webextensions/api/action/setpopup/index.md @@ -34,7 +34,7 @@ browser.action.setPopup( - : `string` or `null`. The HTML file to show in a popup, specified as a URL. - This can point to a file packaged within the extension (for example, created using {{WebExtAPIRef("extension.getURL")}}), or a remote document (e.g. `https://example.org/`). + This can point to a file packaged within the extension (for example, created using {{WebExtAPIRef("extension.getURL")}}), or a remote document (e.g., `https://example.org/`). If an empty string (`""`) is passed here, the popup is disabled, and the extension will receive {{WebExtAPIRef("action.onClicked")}} events. diff --git a/files/en-us/mozilla/add-ons/webextensions/api/alarms/create/index.md b/files/en-us/mozilla/add-ons/webextensions/api/alarms/create/index.md index 38055a0110516f0..e00a75360315414 100644 --- a/files/en-us/mozilla/add-ons/webextensions/api/alarms/create/index.md +++ b/files/en-us/mozilla/add-ons/webextensions/api/alarms/create/index.md @@ -43,16 +43,25 @@ browser.alarms.create( - `periodInMinutes` {{optional_inline}} - : `double`. If this is specified, the alarm will fire again every `periodInMinutes` after its initial firing. If you specify this value you may omit both `when` and `delayInMinutes`, and the alarm will then fire initially after `periodInMinutes`. If `periodInMinutes` is not specified, the alarm will only fire once. +### Return value + +A [`Promise`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise) that is fulfilled with no arguments. + ## Examples Create a one-time delay-based alarm with "" for the name: ```js -const delayInMinutes = 5; +function onAdded() { + console.log("Alarm Added!"); +} + +let delayInMinutes = 5; -browser.alarms.create({ +let addingAlarm = browser.alarms.create({ delayInMinutes, }); +addingAlarm.then(onAdded); ``` Create a periodic delay-based alarm named "my-periodic-alarm": diff --git a/files/en-us/mozilla/add-ons/webextensions/api/alarms/get/index.md b/files/en-us/mozilla/add-ons/webextensions/api/alarms/get/index.md index 41c3b66cc2480d5..f22e54f5b3b53f7 100644 --- a/files/en-us/mozilla/add-ons/webextensions/api/alarms/get/index.md +++ b/files/en-us/mozilla/add-ons/webextensions/api/alarms/get/index.md @@ -26,7 +26,7 @@ let getAlarm = browser.alarms.get( ### Return value -A [`Promise`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise) that will be fulfilled with an `{{WebExtAPIRef('alarms.Alarm', "Alarm")}}` object. This represents the alarm whose name matches `name`. If no alarms match, this will be `undefined`. +A [`Promise`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise) that will be fulfilled with an {{WebExtAPIRef('alarms.Alarm', "Alarm")}} object. This represents the alarm whose name matches `name`. If no alarms match, this will be `undefined`. ## Examples diff --git a/files/en-us/mozilla/add-ons/webextensions/api/browseraction/setbadgebackgroundcolor/index.md b/files/en-us/mozilla/add-ons/webextensions/api/browseraction/setbadgebackgroundcolor/index.md index 7850986d465df84..18559c1911b3402 100644 --- a/files/en-us/mozilla/add-ons/webextensions/api/browseraction/setbadgebackgroundcolor/index.md +++ b/files/en-us/mozilla/add-ons/webextensions/api/browseraction/setbadgebackgroundcolor/index.md @@ -32,7 +32,7 @@ browser.browserAction.setBadgeBackgroundColor( - : The color, specified as one of: - a string: any CSS [\<color>](/en-US/docs/Web/CSS/color_value) value, for example `"red"`, `"#FF0000"`, or `"rgb(255 0 0)"`. If the string is not a valid color, the returned promise will be rejected and the background color won't be altered. - - a `{{WebExtAPIRef('browserAction.ColorArray')}}` object. + - a {{WebExtAPIRef('browserAction.ColorArray')}} object. - `null`. If a `tabId` is specified, it removes the tab-specific badge background color so that the tab inherits the global badge background color. Otherwise it reverts the global badge background color to the default value. - `tabId` {{optional_inline}} diff --git a/files/en-us/mozilla/add-ons/webextensions/api/browseraction/setbadgetextcolor/index.md b/files/en-us/mozilla/add-ons/webextensions/api/browseraction/setbadgetextcolor/index.md index 7bb6dc330f4bda0..e43a2bda2a04c92 100644 --- a/files/en-us/mozilla/add-ons/webextensions/api/browseraction/setbadgetextcolor/index.md +++ b/files/en-us/mozilla/add-ons/webextensions/api/browseraction/setbadgetextcolor/index.md @@ -28,7 +28,7 @@ browser.browserAction.setBadgeTextColor( - : The color, specified as one of: - a string: any CSS [\<color>](/en-US/docs/Web/CSS/color_value) value, for example `"red"`, `"#FF0000"`, or `"rgb(255 0 0)"`. If the string is not a valid color, the returned promise will be rejected and the text color won't be altered. - - a `{{WebExtAPIRef('browserAction.ColorArray')}}` object. + - a {{WebExtAPIRef('browserAction.ColorArray')}} object. - `null`. If a `tabId` is specified, it removes the tab-specific badge text color so that the tab inherits the global badge text color. Otherwise it reverts the global badge text color to the default value. - `tabId` {{optional_inline}} diff --git a/files/en-us/mozilla/add-ons/webextensions/api/browseraction/seticon/index.md b/files/en-us/mozilla/add-ons/webextensions/api/browseraction/seticon/index.md index 528db7dc16eb48b..99b57f755af6125 100644 --- a/files/en-us/mozilla/add-ons/webextensions/api/browseraction/seticon/index.md +++ b/files/en-us/mozilla/add-ons/webextensions/api/browseraction/seticon/index.md @@ -33,7 +33,7 @@ let settingIcon = browser.browserAction.setIcon( - `imageData` {{optional_inline}} - - : `{{WebExtAPIRef('browserAction.ImageDataType')}}` or `object`. This is either a single `ImageData` object or a dictionary object. + - : {{WebExtAPIRef('browserAction.ImageDataType')}} or `object`. This is either a single `ImageData` object or a dictionary object. Use a dictionary object to specify multiple `ImageData` objects in different sizes, so the icon does not have to be scaled for a device with a different pixel density. If `imageData` is a dictionary, the value of each property is an `ImageData` object, and its name is its size, like this: diff --git a/files/en-us/mozilla/add-ons/webextensions/api/browseraction/setpopup/index.md b/files/en-us/mozilla/add-ons/webextensions/api/browseraction/setpopup/index.md index ce47cad45077d8e..4a71cc15c342460 100644 --- a/files/en-us/mozilla/add-ons/webextensions/api/browseraction/setpopup/index.md +++ b/files/en-us/mozilla/add-ons/webextensions/api/browseraction/setpopup/index.md @@ -31,7 +31,7 @@ browser.browserAction.setPopup( - : `string` or `null`. The HTML file to show in a popup, specified as a URL. - This can point to a file packaged within the extension (for example, created using {{WebExtAPIRef("extension.getURL")}}), or a remote document (e.g. `https://example.org/`). + This can point to a file packaged within the extension (for example, created using {{WebExtAPIRef("extension.getURL")}}), or a remote document (e.g., `https://example.org/`). If an empty string (`""`) is passed here, the popup is disabled, and the extension will receive {{WebExtAPIRef("browserAction.onClicked")}} events. diff --git a/files/en-us/mozilla/add-ons/webextensions/api/browsersettings/index.md b/files/en-us/mozilla/add-ons/webextensions/api/browsersettings/index.md index 79446fbcf6ad6b0..5846332d1e17b04 100644 --- a/files/en-us/mozilla/add-ons/webextensions/api/browsersettings/index.md +++ b/files/en-us/mozilla/add-ons/webextensions/api/browsersettings/index.md @@ -54,7 +54,7 @@ To use this API you need to have the "browserSettings" [permission](/en-US/docs/ - {{WebExtAPIRef("browserSettings.zoomFullPage")}} - : Controls whether zoom is applied to the entire page or to text only. - {{WebExtAPIRef("browserSettings.zoomSiteSpecific")}} - - : Controls whether page zoom is applied on a per-site or per-tab basis. If {{WebExtAPIRef("privacy.websites")}}`.resistFingerprinting` is true, this setting has no effect and zoom is applied on a per-tab basis. + - : Controls whether page zoom is applied on a per-site or per-tab basis. If [`privacy.websites.resistFingerprinting`](/en-US/docs/Mozilla/Add-ons/WebExtensions/API/privacy/websites#resistfingerprinting) is true, this setting has no effect and zoom is applied on a per-tab basis. ## Browser compatibility diff --git a/files/en-us/mozilla/add-ons/webextensions/api/browsersettings/overridecontentcolorscheme/index.md b/files/en-us/mozilla/add-ons/webextensions/api/browsersettings/overridecontentcolorscheme/index.md index a92078402da99d2..e2734d970f6ab84 100644 --- a/files/en-us/mozilla/add-ons/webextensions/api/browsersettings/overridecontentcolorscheme/index.md +++ b/files/en-us/mozilla/add-ons/webextensions/api/browsersettings/overridecontentcolorscheme/index.md @@ -9,14 +9,13 @@ browser-compat: webextensions.api.browserSettings.overrideContentColorScheme A {{WebExtAPIRef("types.BrowserSetting", "BrowserSetting")}} object whose underlying value is a string. -Firefox enables users to choose a theme for the browser UI. These themes apply either a light or dark theme to webpages. Using the `layout.css.prefers-color-scheme.content-override` preference, users can override the theme and choose to render webpages in a light or dark theme or follow the device's theme. This browser setting exposes that preference. +Firefox enables users to choose a theme for the browser UI. These themes apply either a light or dark theme to webpages. Using the `layout.css.prefers-color-scheme.content-override` preference, users can override the theme and choose to render webpages in a light or dark theme. This browser setting exposes that preference. This object takes these values: - "light": Applies a light theme to webpages. - "dark": Applies a dark theme to webpages. -- "system": Applies a light or dark theme to webpages based on the device's theme. -- "browser": Applies a light or dark theme to webpages based on the browser's theme. +- "auto": Automatically applies a light or dark theme to webpages based on the browser's theme. ## Browser compatibility diff --git a/files/en-us/mozilla/add-ons/webextensions/api/browsersettings/webnotificationsdisabled/index.md b/files/en-us/mozilla/add-ons/webextensions/api/browsersettings/webnotificationsdisabled/index.md index e5bfa32a94f66e9..af296a0fba995f1 100644 --- a/files/en-us/mozilla/add-ons/webextensions/api/browsersettings/webnotificationsdisabled/index.md +++ b/files/en-us/mozilla/add-ons/webextensions/api/browsersettings/webnotificationsdisabled/index.md @@ -13,7 +13,7 @@ The `Notifications` API is used to display desktop notifications to the user. Th Setting `browserSettings.webNotificationsDisabled` to `true` switches the global permission to _deny_. -Note that this won't affect sites for which the user has set a per-site preference. For example, if the user sets <https://example.org> to _allow_, and an extension then sets `browserSettings.webNotificationsDisabled` to `true`, then pages under [https://example.org](https://example.org) will still be allowed to show notifications. +Note that this won't affect sites for which the user has set a per-site preference. For example, if the user sets <https://example.org> to _allow_, and an extension then sets `browserSettings.webNotificationsDisabled` to `true`, then pages under [https://example.org](https://example.org/) will still be allowed to show notifications. Setting `browserSettings.webNotificationsDisabled` to `false` switches the global default back to its default value. diff --git a/files/en-us/mozilla/add-ons/webextensions/api/browsersettings/zoomsitespecific/index.md b/files/en-us/mozilla/add-ons/webextensions/api/browsersettings/zoomsitespecific/index.md index d13568ba06abed1..52992395d44e85f 100644 --- a/files/en-us/mozilla/add-ons/webextensions/api/browsersettings/zoomsitespecific/index.md +++ b/files/en-us/mozilla/add-ons/webextensions/api/browsersettings/zoomsitespecific/index.md @@ -23,7 +23,7 @@ If `browser.zoom.siteSpecific` is set false, zoom operations apply to the active When Firefox is installed, `browser.zoom.siteSpecific` is true. -If [`privacy.websites`](/en-US/docs/Mozilla/Add-ons/WebExtensions/API/privacy/websites)`.resistFingerprinting` is true, this setting has no effect and zoom is set on a per-tab basis. +If [`privacy.websites.resistFingerprinting`](/en-US/docs/Mozilla/Add-ons/WebExtensions/API/privacy/websites#resistfingerprinting) is true, this setting has no effect and zoom is set on a per-tab basis. ## Browser compatibility diff --git a/files/en-us/mozilla/add-ons/webextensions/api/browsingdata/removaloptions/index.md b/files/en-us/mozilla/add-ons/webextensions/api/browsingdata/removaloptions/index.md index 399f7823e896673..3908a2003df30aa 100644 --- a/files/en-us/mozilla/add-ons/webextensions/api/browsingdata/removaloptions/index.md +++ b/files/en-us/mozilla/add-ons/webextensions/api/browsingdata/removaloptions/index.md @@ -20,15 +20,23 @@ Values of this type are objects. They contain the following properties: > [!NOTE] > On Firefox Nightly removal of localStorage items by `cookieStoreId` is also supported. +- `excludeOrigin` {{optional_inline}} + + - : `array` of `string`. List of origins to exclude from the removal process. Can't be used together with `origins`. Only supported for cookies, storage, and cache. Cookies are excluded for the entire registrable domain. + - `hostnames` {{optional_inline}} - - : `Array` of `string`. This property applies to cookie, indexedDB, local storage, and service worker registration items. Remove only cookie, indexedDB, local storage, and service worker registration items associated with these hostnames. + - : `array` of `string`. This property applies to cookie, indexedDB, local storage, and service worker registration items. Remove only cookie, indexedDB, local storage, and service worker registration items associated with these hostnames. You must pass in just a hostname here, without protocol (for example, `"google.com"` not `"https://google.com"`). You can use the [`URL`](/en-US/docs/Web/API/URL) interface to parse a raw URL and retrieve the hostname. Items associated with subdomains of a given hostname are _not_ removed: you must explicitly list subdomains. +- `origin` {{optional_inline}} + + - : `array` of `string`. List of origins to remove data for. Can't be used together with `excludeOrigins`. Only supported for cookies, storage, and cache. Cookies are cleared for the entire registrable domain. + - `originTypes` {{optional_inline}} - - : `object`. Used to control whether to remove data only from normal web pages, or also from hosted web apps and extensions. If this option is omitted, only data from normal web pages ("`unprotectedWeb`") is removed. Before removing data from web apps or extensions, be very careful to ensure that this is really what the user wants. + - : `object`. Used to control whether to remove data only from normal web pages, or also from hosted web apps and extensions. If this option is omitted, only data from normal web pages (`unprotectedWeb`) is removed. Before removing data from web apps or extensions, be very careful to ensure that this is really what the user wants. This object may contain any of the following properties: diff --git a/files/en-us/mozilla/add-ons/webextensions/api/browsingdata/remove/index.md b/files/en-us/mozilla/add-ons/webextensions/api/browsingdata/remove/index.md index 13af270af7589d5..eb80127b4e16479 100644 --- a/files/en-us/mozilla/add-ons/webextensions/api/browsingdata/remove/index.md +++ b/files/en-us/mozilla/add-ons/webextensions/api/browsingdata/remove/index.md @@ -29,7 +29,7 @@ let removing = browser.browsingData.remove( - `removalOptions` - : `object`. A {{WebExtAPIRef("browsingData.RemovalOptions")}} object, which may be used to control how far back in time to remove data, and whether to remove data from hosted web apps and extensions, or just normal web pages. - `dataTypes` - - : `object`. A {{WebExtAPIRef("browsingData.DataTypeSet")}} object, describing the types of data to remove (e.g. history, downloads, …). + - : `object`. A {{WebExtAPIRef("browsingData.DataTypeSet")}} object, describing the types of data to remove (e.g., history, downloads, …). ### Return value diff --git a/files/en-us/mozilla/add-ons/webextensions/api/browsingdata/settings/index.md b/files/en-us/mozilla/add-ons/webextensions/api/browsingdata/settings/index.md index ad5c920a43aef66..9f8135c9eae4aa3 100644 --- a/files/en-us/mozilla/add-ons/webextensions/api/browsingdata/settings/index.md +++ b/files/en-us/mozilla/add-ons/webextensions/api/browsingdata/settings/index.md @@ -7,7 +7,7 @@ browser-compat: webextensions.api.browsingData.settings {{AddonSidebar}} -Browsers have a built-in "Clear History" feature, which enables the user to clear various types of browsing data. This has a UI that enables the user to select what type of data to remove (e.g. history, downloads, …) and how far back in time to remove data. +Browsers have a built-in "Clear History" feature, which enables the user to clear various types of browsing data. This has a UI that enables the user to select what type of data to remove (e.g., history, downloads, …) and how far back in time to remove data. This function returns the current value of these settings. @@ -30,11 +30,11 @@ None. A [`Promise`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise) that will be fulfilled with an object containing the settings information. This object has three properties: - `options` - - : `{{WebExtAPIRef("browsingData.RemovalOptions")}}`. A `RemovalOptions` object describing the removal options currently selected. + - : {{WebExtAPIRef("browsingData.RemovalOptions")}}. A `RemovalOptions` object describing the removal options currently selected. - `dataToRemove` - - : `{{WebExtAPIRef("browsingData.DataTypeSet")}}`. This will contain a property for every data type that can be toggled in the browser's UI. Each property will have a value of `true` if that type is selected for removal and `false` otherwise. + - : {{WebExtAPIRef("browsingData.DataTypeSet")}}. This will contain a property for every data type that can be toggled in the browser's UI. Each property will have a value of `true` if that type is selected for removal and `false` otherwise. - `dataRemovalPermitted` - - : `{{WebExtAPIRef("browsingData.DataTypeSet")}}`. This will contain a property for every data type that can be toggled in the browser's UI. Each will have a value of `true` if the administrator of the device has allowed the user to remove that type, and `false` otherwise. + - : {{WebExtAPIRef("browsingData.DataTypeSet")}}. This will contain a property for every data type that can be toggled in the browser's UI. Each will have a value of `true` if the administrator of the device has allowed the user to remove that type, and `false` otherwise. If any error occurs, the promise will be rejected with an error message. diff --git a/files/en-us/mozilla/add-ons/webextensions/api/clipboard/setimagedata/index.md b/files/en-us/mozilla/add-ons/webextensions/api/clipboard/setimagedata/index.md index be3cc1c49c13002..0ac2d509bc303b5 100644 --- a/files/en-us/mozilla/add-ons/webextensions/api/clipboard/setimagedata/index.md +++ b/files/en-us/mozilla/add-ons/webextensions/api/clipboard/setimagedata/index.md @@ -47,10 +47,10 @@ Copy a remote image: ```js // requires: -// * the host permission for "https://cdn.mdn.mozilla.net/*" +// * the host permission for "https://mdn.github.io/*" // * the API permission "clipboardWrite" -fetch("https://cdn.mdn.mozilla.net/static/img/favicon144.png") +fetch("https://mdn.github.io/shared-assets/images/examples/favicon144.png") .then((response) => response.arrayBuffer()) .then((buffer) => browser.clipboard.setImageData(buffer, "png")); ``` diff --git a/files/en-us/mozilla/add-ons/webextensions/api/commands/command/index.md b/files/en-us/mozilla/add-ons/webextensions/api/commands/command/index.md index e460dd74899c47f..21af9ae21ff75d1 100644 --- a/files/en-us/mozilla/add-ons/webextensions/api/commands/command/index.md +++ b/files/en-us/mozilla/add-ons/webextensions/api/commands/command/index.md @@ -22,7 +22,7 @@ A value of this type is an object containing these properties for the commands: - `shortcut` {{optional_inline}} - : `string`. Keys used to execute the command, specified as a string. See the [shortcut values](/en-US/docs/Mozilla/Add-ons/WebExtensions/manifest.json/commands#shortcut_values) section of the `commands` manifest key documentation for more details. -`description` and `shortcut` reflect the values given in the `commands` manifest.json key unless they have been updated with {{WebExtAPIRef('commands.update()')}}` or, in the case of the shortcut, customized by the user. +`description` and `shortcut` reflect the values given in the `commands` manifest.json key unless they have been updated with {{WebExtAPIRef('commands.update()')}} or, in the case of the shortcut, customized by the user. ## Browser compatibility diff --git a/files/en-us/mozilla/add-ons/webextensions/api/commands/getall/index.md b/files/en-us/mozilla/add-ons/webextensions/api/commands/getall/index.md index a4bc72dfd496080..978410483b11b89 100644 --- a/files/en-us/mozilla/add-ons/webextensions/api/commands/getall/index.md +++ b/files/en-us/mozilla/add-ons/webextensions/api/commands/getall/index.md @@ -23,7 +23,7 @@ None. ### Return value -A [`Promise`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise) that will be fulfilled with an array of `{{WebExtAPIRef('commands.Command')}}` objects, one for each command registered for the extension. If no commands were registered, the array will be empty. +A [`Promise`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise) that will be fulfilled with an array of {{WebExtAPIRef('commands.Command')}} objects, one for each command registered for the extension. If no commands were registered, the array will be empty. ## Examples diff --git a/files/en-us/mozilla/add-ons/webextensions/api/cookies/getall/index.md b/files/en-us/mozilla/add-ons/webextensions/api/cookies/getall/index.md index f66766a358db35a..2dfd1422376fec7 100644 --- a/files/en-us/mozilla/add-ons/webextensions/api/cookies/getall/index.md +++ b/files/en-us/mozilla/add-ons/webextensions/api/cookies/getall/index.md @@ -42,8 +42,8 @@ let getting = browser.cookies.getAll( - : An `object` defining which [storage partitions](/en-US/docs/Mozilla/Add-ons/WebExtensions/API/cookies#storage_partitioning) to return cookies from: - If omitted, only cookies from unpartitioned storage are returned. - - If included without `topLevelSite', all cookies from partitioned and unpartitioned storage are returned. - - If included with the specified `topLevelSite', cookies from the specified partition storage are returned. + - If included without `topLevelSite`, all cookies from partitioned and unpartitioned storage are returned. + - If included with the specified `topLevelSite`, cookies from the specified partition storage are returned. This object contains: @@ -63,7 +63,7 @@ let getting = browser.cookies.getAll( ### Return value -A [`Promise`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise) that is fulfilled with an array of `{{WebExtAPIRef('cookies.Cookie')}}` objects that match the properties given in the `details` parameter. Only unexpired cookies are returned. The cookies returned are sorted by path length, longest to shortest. If multiple cookies have the same path length, those with the earliest creation time are first. +A [`Promise`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise) that is fulfilled with an array of {{WebExtAPIRef('cookies.Cookie')}} objects that match the properties given in the `details` parameter. Only unexpired cookies are returned. The cookies returned are sorted by path length, longest to shortest. If multiple cookies have the same path length, those with the earliest creation time are first. > [!NOTE] > Before Firefox 133, Firefox returned the cookie sorted by creation time, with the earliest creation time first. diff --git a/files/en-us/mozilla/add-ons/webextensions/api/cookies/samesitestatus/index.md b/files/en-us/mozilla/add-ons/webextensions/api/cookies/samesitestatus/index.md index 6c57551d224fd77..a5ade0910b882fd 100644 --- a/files/en-us/mozilla/add-ons/webextensions/api/cookies/samesitestatus/index.md +++ b/files/en-us/mozilla/add-ons/webextensions/api/cookies/samesitestatus/index.md @@ -22,7 +22,7 @@ Values of this type are strings. Possible values are: - `unspecified` - : Corresponds to a cookie set without the `SameSite` attribute. This state is not part of any SameSite standard, and is only supported by browsers that store this state internally. Other browsers map the absence of the SameSite flag to the default state (e.g., Lax). See the browser compatibility table for more details. -See [SameSite cookies](/en-US/docs/Web/HTTP/Cookies#samesite_cookies) for more information. +See [SameSite cookies](/en-US/docs/Web/HTTP/Guides/Cookies#controlling_third-party_cookies_with_samesite) for more information. ## Browser compatibility diff --git a/files/en-us/mozilla/add-ons/webextensions/api/cookies/set/index.md b/files/en-us/mozilla/add-ons/webextensions/api/cookies/set/index.md index 5b3651bd9c77906..15e9fc2d2e85ce8 100644 --- a/files/en-us/mozilla/add-ons/webextensions/api/cookies/set/index.md +++ b/files/en-us/mozilla/add-ons/webextensions/api/cookies/set/index.md @@ -47,7 +47,7 @@ let setting = browser.cookies.set( - `path` {{optional_inline}} - : A `string` representing the path of the cookie. If omitted, this defaults to the path portion of the URL parameter. - `sameSite` {{optional_inline}} - - : A {{WebExtAPIRef("cookies.SameSiteStatus")}} value that indicates the SameSite state of the cookie. If omitted, it defaults to 0, 'no_restriction'. + - : A {{WebExtAPIRef("cookies.SameSiteStatus")}} value that indicates the SameSite state of the cookie. If omitted, defaults to `unspecified`. - `secure` {{optional_inline}} - : A `boolean` that specifies whether the cookie is marked as secure (`true`), or not (false). If omitted, it defaults to false. - `storeId` {{optional_inline}} diff --git a/files/en-us/mozilla/add-ons/webextensions/api/declarativenetrequest/getmatchedrules/index.md b/files/en-us/mozilla/add-ons/webextensions/api/declarativenetrequest/getmatchedrules/index.md index e12b1048aac2062..a7af55085e29745 100644 --- a/files/en-us/mozilla/add-ons/webextensions/api/declarativenetrequest/getmatchedrules/index.md +++ b/files/en-us/mozilla/add-ons/webextensions/api/declarativenetrequest/getmatchedrules/index.md @@ -36,7 +36,7 @@ A [`Promise`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise) that - `tabId` - : `number` The `tabId` of the tab the request originated from if the tab is still active. Otherwise, `-1`. - `timeStamp` - - : `number` The time the rule was matched. Timestamps correspond to the JavaScript convention for times, i.e. the number of milliseconds since the epoch. + - : `number` The time the rule was matched. Timestamps correspond to the JavaScript convention for times, i.e., the number of milliseconds since the epoch. If no rules are matched, the object is empty. If the request fail, the promise is rejected with an error message diff --git a/files/en-us/mozilla/add-ons/webextensions/api/declarativenetrequest/headerinfo/index.md b/files/en-us/mozilla/add-ons/webextensions/api/declarativenetrequest/headerinfo/index.md index 2bf3bdded142b10..54d83934454dc78 100644 --- a/files/en-us/mozilla/add-ons/webextensions/api/declarativenetrequest/headerinfo/index.md +++ b/files/en-us/mozilla/add-ons/webextensions/api/declarativenetrequest/headerinfo/index.md @@ -9,13 +9,14 @@ browser-compat: {{AddonSidebar}} -The response header to match for the request, declared in the {{WebExtAPIRef("declarativeNetRequest.RuleCondition", "rule.condition")}}`.excludedResponseHeaders` array or {{WebExtAPIRef("declarativeNetRequest.RuleCondition", "rule.condition")}}`.responseHeaders` array. If specified, the array must be non-empty. +The response header to match for the request, declared in the [`rule.condition.excludedResponseHeaders`](/en-US/docs/Mozilla/Add-ons/WebExtensions/API/declarativeNetRequest/RuleCondition#excludedresponseheaders) array or [`rule.condition.responseHeaders`](/en-US/docs/Mozilla/Add-ons/WebExtensions/API/declarativeNetRequest/RuleCondition#responseheaders) array. If specified, the array must be non-empty. When used in the condition responseHeaders, the rule matches if the request matches this response header condition. When used in the condition excludedResponseHeaders, the rule does not match if the request matches this response header condition. Each object describes one header to match or exclude. To check multiple headers, multiple objects can be specified in these arrays, or across multiple rules. -> [!NOTE] Matching by headers is a relatively new feature. Make sure to feature-detect its availability before relying on it. While some browsers ignore the complete rule when an unrecognized condition is present, Chrome 121 until 127 applied the whole rule while ignoring the `responseHeaders` condition. This could result in matching more requests than intended, see [Chromium issue 347186592](https://crbug.com/347186592). +> [!NOTE] +> Matching by headers is a relatively new feature. Make sure to feature-detect its availability before relying on it. While some browsers ignore the complete rule when an unrecognized condition is present, Chrome 121 until 127 applied the whole rule while ignoring the `responseHeaders` condition. This could result in matching more requests than intended, see [Chromium issue 347186592](https://crbug.com/347186592). ## Type @@ -27,7 +28,7 @@ Values of this type are objects. They contain these properties: - : An array of `string`. If specified, this condition matches if the header's value matches at least one pattern in this list. This supports case-insensitive header value matching plus the following constructs: - `'*'` : Matches any number of characters. - `'?'` : Matches zero or one character(s). - - `'*'` and `'?'` can be escaped with a backslash, e.g. `'\*'` and `'\?'`. + - `'*'` and `'?'` can be escaped with a backslash, e.g., `'\*'` and `'\?'`. - `excludedValues` {{optional_inline}} - : An array of `string`. If specified, this condition is not matched if the header exists but its value contains at least one element in this list. This uses the same glob pattern syntax as `values`. If `values` and `excludedValues` are both matched, then `excludedValues` takes precedence. diff --git a/files/en-us/mozilla/add-ons/webextensions/api/declarativenetrequest/index.md b/files/en-us/mozilla/add-ons/webextensions/api/declarativenetrequest/index.md index 2531e47ebd64c1e..4df6257504cc577 100644 --- a/files/en-us/mozilla/add-ons/webextensions/api/declarativenetrequest/index.md +++ b/files/en-us/mozilla/add-ons/webextensions/api/declarativenetrequest/index.md @@ -11,7 +11,7 @@ This API enables extensions to specify conditions and actions that describe how ## Permissions -To use this API, an extension must request the `"declarativeNetRequest"` or `"declarativeNetRequestWithHostAccess"` [permission](/en-US/docs/Mozilla/Add-ons/WebExtensions/manifest.json/permissions) in its [`manifest.json`](/en-US/docs/Mozilla/Add-ons/WebExtensions/manifest.json) file. +To use this API, an extension must request the `"declarativeNetRequest"` or `"declarativeNetRequestWithHostAccess"` [permission](/en-US/docs/Mozilla/Add-ons/WebExtensions/manifest.json/permissions) in its [`manifest.json`](/en-US/docs/Mozilla/Add-ons/WebExtensions/manifest.json) file. The `"declarativeNetRequest"` permission is shown to users in permission prompts, the `"declarativeNetRequestWithHostAccess"` is not. The `"declarativeNetRequest"` permission allows extensions to block and upgrade requests without any [host permissions](/en-US/docs/Mozilla/Add-ons/WebExtensions/manifest.json/permissions#host_permissions). Host permissions are required if the extension wants to redirect requests or modify headers on requests or when the `"declarativeNetRequestWithHostAccess"` permission is used instead of the `"declarativeNetRequest"` permission. To act on requests in these cases, host permissions are required for the request URL. For all requests, except for navigation requests (i.e., resource type `main_frame` and `sub_frame`), host permissions are also required for the request's initiator. The initiator of a request is usually the document or worker that triggered the request. @@ -169,6 +169,8 @@ If the request was not blocked or redirected, the matching `modifyHeaders` actio ## Types +- {{WebExtAPIRef("declarativeNetRequest.HeaderInfo")}} + - : The response header to match for the request, declared in the [`rule.condition.excludedResponseHeaders`](/en-US/docs/Mozilla/Add-ons/WebExtensions/API/declarativeNetRequest/RuleCondition#excludedresponseheaders) array or [`rule.condition.responseHeaders`](/en-US/docs/Mozilla/Add-ons/WebExtensions/API/declarativeNetRequest/RuleCondition#responseheaders) array. - {{WebExtAPIRef("declarativeNetRequest.MatchedRule")}} - : Details of a matched rule. - {{WebExtAPIRef("declarativeNetRequest.ModifyHeaderInfo")}} @@ -228,7 +230,7 @@ If the request was not blocked or redirected, the matching `modifyHeaders` actio - {{WebExtAPIRef("declarativeNetRequest.getSessionRules()")}} - : Returns the set of session-scoped rules for the extension. - {{WebExtAPIRef("declarativeNetRequest.isRegexSupported()")}} - - : Checks if a regular expression is supported as a {{WebExtAPIRef("declarativeNetRequest.RuleCondition")}}`.regexFilter` rule condition. + - : Checks if a regular expression is supported as a [`declarativeNetRequest.RuleCondition.regexFilter`](/en-US/docs/Mozilla/Add-ons/WebExtensions/API/declarativeNetRequest/RuleCondition#regexfilter) rule condition. - {{WebExtAPIRef("declarativeNetRequest.setExtensionActionOptions()")}} - : Configures how the action count for tabs are handled. - {{WebExtAPIRef("declarativeNetRequest.testMatchOutcome()")}} diff --git a/files/en-us/mozilla/add-ons/webextensions/api/declarativenetrequest/isregexsupported/index.md b/files/en-us/mozilla/add-ons/webextensions/api/declarativenetrequest/isregexsupported/index.md index 82d5f944418f5fe..abdc873f875a153 100644 --- a/files/en-us/mozilla/add-ons/webextensions/api/declarativenetrequest/isregexsupported/index.md +++ b/files/en-us/mozilla/add-ons/webextensions/api/declarativenetrequest/isregexsupported/index.md @@ -7,7 +7,7 @@ browser-compat: webextensions.api.declarativeNetRequest.isRegexSupported {{AddonSidebar}} -Checks if a regular expression is supported as a {{WebExtAPIRef("declarativeNetRequest.RuleCondition")}}`.regexFilter` rule condition. +Checks if a regular expression is supported as a [`declarativeNetRequest.RuleCondition.regexFilter`](/en-US/docs/Mozilla/Add-ons/WebExtensions/API/declarativeNetRequest/RuleCondition#regexfilter) rule condition. ## Syntax diff --git a/files/en-us/mozilla/add-ons/webextensions/api/declarativenetrequest/modifyheaderinfo/index.md b/files/en-us/mozilla/add-ons/webextensions/api/declarativenetrequest/modifyheaderinfo/index.md index 4d3993facdd1fcc..71b8e7c2467d203 100644 --- a/files/en-us/mozilla/add-ons/webextensions/api/declarativenetrequest/modifyheaderinfo/index.md +++ b/files/en-us/mozilla/add-ons/webextensions/api/declarativenetrequest/modifyheaderinfo/index.md @@ -9,7 +9,7 @@ browser-compat: {{AddonSidebar}} -The request or response header to modify for a request, declared in the `rule.action.requestHeaders` array or `rule.action.responseHeaders` array for rules whose {{WebExtAPIRef("declarativeNetRequest.RuleAction", "rule.action")}}`.type` is "modifyHeaders". +The request or response header to modify for a request, declared in the `rule.action.requestHeaders` array or `rule.action.responseHeaders` array for rules whose [`rule.action.type`](/en-US/docs/Mozilla/Add-ons/WebExtensions/API/declarativeNetRequest/RuleAction#type_2) is "modifyHeaders". Each object describes one header modification. To modify multiple headers, multiple objects can be specified in these arrays, or across multiple rules. diff --git a/files/en-us/mozilla/add-ons/webextensions/api/declarativenetrequest/resourcetype/index.md b/files/en-us/mozilla/add-ons/webextensions/api/declarativenetrequest/resourcetype/index.md index 98a54a64bc629b3..aa961bcae95fef5 100644 --- a/files/en-us/mozilla/add-ons/webextensions/api/declarativenetrequest/resourcetype/index.md +++ b/files/en-us/mozilla/add-ons/webextensions/api/declarativenetrequest/resourcetype/index.md @@ -22,7 +22,9 @@ Values of this type are strings. Possible values are: - `image` - : Resources loaded to be rendered as image, except for `imageset` on browsers that support that type (see browser compatibility below). - `imageset` - - : Images loaded by a {{HTMLElement("picture")}} element or given in an `<img>` element's [`srcset`](/en-US/docs/Web/HTML/Element/img#srcset) attribute. + - : Images loaded by a {{HTMLElement("picture")}} element or given in an `<img>` element's [`srcset`](/en-US/docs/Web/HTML/Reference/Elements/img#srcset) attribute. +- `json` + - : JSON modules loaded through an [import statement](/en-US/docs/Web/JavaScript/Reference/Statements/import). - `main_frame` - : Top-level documents loaded into a tab. - `media` @@ -37,7 +39,7 @@ Values of this type are strings. Possible values are: - : Requests sent by plugins. - `ping` - - : Requests sent to the URL given in a hyperlink's [`ping`](/en-US/docs/Web/HTML/Element/a#ping) attribute, when the hyperlink is followed. + - : Requests sent to the URL given in a hyperlink's [`ping`](/en-US/docs/Web/HTML/Reference/Elements/a#ping) attribute, when the hyperlink is followed. Browsers that don't have a dedicated `beacon` type (see browser compatibility below), also label requests sent through the Beacon API as `ping`. diff --git a/files/en-us/mozilla/add-ons/webextensions/api/declarativenetrequest/rulecondition/index.md b/files/en-us/mozilla/add-ons/webextensions/api/declarativenetrequest/rulecondition/index.md index 3d0a334da13959f..12c92044eb843e3 100644 --- a/files/en-us/mozilla/add-ons/webextensions/api/declarativenetrequest/rulecondition/index.md +++ b/files/en-us/mozilla/add-ons/webextensions/api/declarativenetrequest/rulecondition/index.md @@ -22,7 +22,7 @@ Values of this type are objects. They contain these properties: - `initiatorDomains` {{optional_inline}} - : An array of `string`. The rule only matches network requests originating from this list of domains. If the list is omitted, the rule is applied to requests from all domains. An empty list is not allowed. A [canonical domain](#canonical_domain) should be used. This matches against the request initiator and not the request URL. - `excludedInitiatorDomains` {{optional_inline}} - - : An array of `string`. The rule does not match network requests originating from this list of domains. If the list is empty or omitted, no domains are excluded. This takes precedence over `initiatorDomains`. A [canonical domain](#whocanonical_domain) should be used. This matches against the request initiator and not the request URL. + - : An array of `string`. The rule does not match network requests originating from this list of domains. If the list is empty or omitted, no domains are excluded. This takes precedence over `initiatorDomains`. A [canonical domain](#canonical_domain) should be used. This matches against the request initiator and not the request URL. - `isUrlFilterCaseSensitive` {{optional_inline}} - : A `boolean`. Whether the [`urlFilter`](#urlfilter) or [`regexFilter`](#regexfilter) (whichever is specified) is case sensitive. While there is consensus on defaulting to `false` across browsers in [WECG issue 269](https://github.com/w3c/webextensions/issues/269), the value used to be `true` in (older) versions of Chrome and Safari. See [Browser compatibility](#browser_compatibility) for details. - `regexFilter` {{optional_inline}} @@ -47,9 +47,9 @@ Values of this type are objects. They contain these properties: - `excludedResponseHeaders` {{optional_inline}} - : An array of {{WebExtAPIRef("declarativeNetRequest.HeaderInfo")}}. The rule does not match if the request matches any response header condition in this list (if specified). If both `excludedResponseHeaders` and `responseHeaders` are specified, then the `excludedResponseHeaders` property takes precedence. - `tabIds` {{optional_inline}} - - : An array of `number`. List of {{WebExtAPIRef("tabs.Tab")}}.`id` that the rule should match. An ID of {{WebExtAPIRef("tabs.TAB_ID_NONE")}} matches requests that don't originate from a tab. An empty list is not allowed. Only supported for session-scoped rules. + - : An array of `number`. List of {{WebExtAPIRef("tabs.Tab")}}. `id` that the rule should match. An ID of {{WebExtAPIRef("tabs.TAB_ID_NONE")}} matches requests that don't originate from a tab. An empty list is not allowed. Only supported for session-scoped rules. - `excludedTabIds` {{optional_inline}} - - : An array of `number`. List of {{WebExtAPIRef("tabs.Tab")}}.`id` that the rule should not match. An ID of {{WebExtAPIRef("tabs.TAB_ID_NONE")}} excludes requests that do not originate from a tab. Only supported for session-scoped rules. + - : An array of `number`. List of {{WebExtAPIRef("tabs.Tab")}}. `id` that the rule should not match. An ID of {{WebExtAPIRef("tabs.TAB_ID_NONE")}} excludes requests that do not originate from a tab. Only supported for session-scoped rules. - `urlFilter` {{optional_inline}} - : A `string`. The pattern that is matched against the network request URL. Supported constructs: diff --git a/files/en-us/mozilla/add-ons/webextensions/api/declarativenetrequest/updateenabledrulesets/index.md b/files/en-us/mozilla/add-ons/webextensions/api/declarativenetrequest/updateenabledrulesets/index.md index 026c2526c297b6c..f24ddcc63a08de8 100644 --- a/files/en-us/mozilla/add-ons/webextensions/api/declarativenetrequest/updateenabledrulesets/index.md +++ b/files/en-us/mozilla/add-ons/webextensions/api/declarativenetrequest/updateenabledrulesets/index.md @@ -7,7 +7,7 @@ browser-compat: webextensions.api.declarativeNetRequest.updateEnabledRulesets {{AddonSidebar}} -Updates the extension's set of static rulesets. The rulesets with IDs listed in `options.disableRulesetIds` are first deactivated, and then the rulesets listed in `options.enableRulesetIds` are activated. Note that the set of enabled static rulesets persists across sessions but not across extension updates, i.e. the [`declarative_net_request.rule_resources` manifest key](/en-US/docs/Mozilla/Add-ons/WebExtensions/manifest.json/declarative_net_request) determines the set of enabled static rulesets on each extension update. +Updates the extension's set of static rulesets. The rulesets with IDs listed in `options.disableRulesetIds` are first deactivated, and then the rulesets listed in `options.enableRulesetIds` are activated. Note that the set of enabled static rulesets persists across sessions but not across extension updates, i.e., the [`declarative_net_request.rule_resources` manifest key](/en-US/docs/Mozilla/Add-ons/WebExtensions/manifest.json/declarative_net_request) determines the set of enabled static rulesets on each extension update. > [!NOTE] > In Firefox 132 and earlier, static rulesets don't load after a browser restart when there are no registered static or dynamic rules at install time ([Firefox bug 1921353](https://bugzil.la/1921353)). A workaround is to make sure that the [`declarative_net_request`](/en-US/docs/Mozilla/Add-ons/WebExtensions/manifest.json/declarative_net_request) manifest key contains at least one enabled ruleset. diff --git a/files/en-us/mozilla/add-ons/webextensions/api/devtools/inspectedwindow/reload/index.md b/files/en-us/mozilla/add-ons/webextensions/api/devtools/inspectedwindow/reload/index.md index 2a3eb0f0af25eaf..80a99c4c1449ec4 100644 --- a/files/en-us/mozilla/add-ons/webextensions/api/devtools/inspectedwindow/reload/index.md +++ b/files/en-us/mozilla/add-ons/webextensions/api/devtools/inspectedwindow/reload/index.md @@ -26,7 +26,7 @@ browser.devtools.inspectedWindow.reload( - `ignoreCache` {{optional_inline}} - : `boolean`. If true, this makes the reload ignore the browser cache (as if the user had pressed Shift+Ctrl+R). - `userAgent` {{optional_inline}} - - : `string`. Set a custom user agent for the page. The string supplied here will be sent in the browser's [User-Agent](/en-US/docs/Web/HTTP/Headers/User-Agent) header, and will be returned by calls to [`navigator.userAgent`](/en-US/docs/Web/API/Navigator/userAgent) made by scripts running in the page. + - : `string`. Set a custom user agent for the page. The string supplied here will be sent in the browser's [User-Agent](/en-US/docs/Web/HTTP/Reference/Headers/User-Agent) header, and will be returned by calls to [`navigator.userAgent`](/en-US/docs/Web/API/Navigator/userAgent) made by scripts running in the page. - `injectedScript` {{optional_inline}} - : `string`. Inject the given JavaScript expression into all frames in the page, before any other scripts. diff --git a/files/en-us/mozilla/add-ons/webextensions/api/devtools/panels/create/index.md b/files/en-us/mozilla/add-ons/webextensions/api/devtools/panels/create/index.md index a10c43c6b00d054..993a0fcb371b9de 100644 --- a/files/en-us/mozilla/add-ons/webextensions/api/devtools/panels/create/index.md +++ b/files/en-us/mozilla/add-ons/webextensions/api/devtools/panels/create/index.md @@ -26,7 +26,7 @@ let creating = browser.devtools.panels.create( - `title` - : `string`. The panel's title. This will appear in the row of tabs along the top of the devtools window, and is the main way the user will be able to identify your panel. - `iconPath` - - : `string`. Specifies an icon which will be shown next to the title. It's provided as a URL to an image file that's been bundled with your extension. Chromium-based browsers and Safari resolve this URL as absolute, while Firefox resolves this URL as relative to the current extension page (unless expressed as an absolute URL, e.g. "/icons/panel.png"). + - : `string`. Specifies an icon which will be shown next to the title. It's provided as a URL to an image file that's been bundled with your extension. Chromium-based browsers and Safari resolve this URL as absolute, while Firefox resolves this URL as relative to the current extension page (unless expressed as an absolute URL, e.g., "/icons/panel.png"). - `pagePath` - : string. Specifies an HTML file that defines the content of the panel. It's provided as a URL to an HTML file bundled with your extension. The URL may be resolved as an absolute URL or relative to the current extension page. See the browser compatibility data for more information. The HTML file can include CSS and JavaScript files, just like a normal web page. The JavaScript running in the panel can use the devtools APIs. See [Extending the developer tools](/en-US/docs/Mozilla/Add-ons/WebExtensions/Extending_the_developer_tools). diff --git a/files/en-us/mozilla/add-ons/webextensions/api/downloads/downloaditem/index.md b/files/en-us/mozilla/add-ons/webextensions/api/downloads/downloaditem/index.md index 99ea8e04dd5b5c2..04e8aa1372625a8 100644 --- a/files/en-us/mozilla/add-ons/webextensions/api/downloads/downloaditem/index.md +++ b/files/en-us/mozilla/add-ons/webextensions/api/downloads/downloaditem/index.md @@ -20,7 +20,7 @@ Values of this type are objects. They contain the following properties: - `bytesReceived` - : A `number` representing the number of bytes received so far from the host during the download; this does not take file compression into consideration. - `canResume` - - : A `boolean` indicating whether a currently-interrupted (e.g. paused) download can be resumed from the point where it was interrupted (`true`), or not (`false`). + - : A `boolean` indicating whether a currently-interrupted (e.g., paused) download can be resumed from the point where it was interrupted (`true`), or not (`false`). - `cookieStoreId` {{optional_inline}} - : The cookie store ID of the [contextual identity](/en-US/docs/Mozilla/Add-ons/WebExtensions/Work_with_contextual_identities) in which the download took place. See [Work with contextual identities](/en-US/docs/Mozilla/Add-ons/WebExtensions/Work_with_contextual_identities) for more information. - `danger` @@ -44,7 +44,7 @@ Values of this type are objects. They contain the following properties: - `mime` - : A `string` representing the downloaded file's MIME type. - `paused` - - : A `boolean` indicating whether the download is paused, i.e. if the download has stopped reading data from the host but has kept the connection open. If so, the value is `true`, `false` if not. + - : A `boolean` indicating whether the download is paused, i.e., if the download has stopped reading data from the host but has kept the connection open. If so, the value is `true`, `false` if not. - `referrer` - : A `string` representing the downloaded file's referrer. - `startTime` diff --git a/files/en-us/mozilla/add-ons/webextensions/api/downloads/downloadquery/index.md b/files/en-us/mozilla/add-ons/webextensions/api/downloads/downloadquery/index.md index 84af7a0d24655bc..482560613ea7f67 100644 --- a/files/en-us/mozilla/add-ons/webextensions/api/downloads/downloadquery/index.md +++ b/files/en-us/mozilla/add-ons/webextensions/api/downloads/downloadquery/index.md @@ -56,7 +56,7 @@ Values of this type are objects. They contain the following properties: - `state` {{optional_inline}} - : A `string` representing a download {{WebExtAPIRef('downloads.State')}} (`in_progress`, `interrupted`, or `complete`). Include only {{WebExtAPIRef("downloads.DownloadItem", "DownloadItems")}} with this `state` value. - `paused` {{optional_inline}} - - : A `boolean` that indicates whether a download is paused — i.e. has stopped reading data from the host, but kept the connection open (`true`), or not (`false`). Include only {{WebExtAPIRef("downloads.DownloadItem", "DownloadItems")}} with this `paused` value. + - : A `boolean` that indicates whether a download is paused — i.e., has stopped reading data from the host, but kept the connection open (`true`), or not (`false`). Include only {{WebExtAPIRef("downloads.DownloadItem", "DownloadItems")}} with this `paused` value. - `error` {{optional_inline}} - : A string representing an {{WebExtAPIRef('downloads.InterruptReason')}} — a reason why a download was interrupted. Include only {{WebExtAPIRef("downloads.DownloadItem", "DownloadItems")}} with this `error` value. - `bytesReceived` {{optional_inline}} diff --git a/files/en-us/mozilla/add-ons/webextensions/api/downloads/oncreated/index.md b/files/en-us/mozilla/add-ons/webextensions/api/downloads/oncreated/index.md index ec1623928a190c0..585bb35c816f343 100644 --- a/files/en-us/mozilla/add-ons/webextensions/api/downloads/oncreated/index.md +++ b/files/en-us/mozilla/add-ons/webextensions/api/downloads/oncreated/index.md @@ -7,7 +7,7 @@ browser-compat: webextensions.api.downloads.onCreated {{AddonSidebar}} -The **`onCreated()`** event of the {{WebExtAPIRef("downloads")}} API fires when a download begins, i.e. when {{WebExtAPIRef("downloads.download()")}} is successfully invoked. +The **`onCreated()`** event of the {{WebExtAPIRef("downloads")}} API fires when a download begins, i.e., when {{WebExtAPIRef("downloads.download()")}} is successfully invoked. The listener is passed the {{WebExtAPIRef('downloads.DownloadItem')}} object in question as a parameter. diff --git a/files/en-us/mozilla/add-ons/webextensions/api/downloads/search/index.md b/files/en-us/mozilla/add-ons/webextensions/api/downloads/search/index.md index 45396047cd17085..413fb7d5e175dbb 100644 --- a/files/en-us/mozilla/add-ons/webextensions/api/downloads/search/index.md +++ b/files/en-us/mozilla/add-ons/webextensions/api/downloads/search/index.md @@ -24,7 +24,7 @@ let searching = browser.downloads.search(query); ### Return value -A [`Promise`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise). The promise is fulfilled with an `array` of `{{WebExtAPIRef('downloads.DownloadItem')}}` objects that match the given criteria. +A [`Promise`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise). The promise is fulfilled with an `array` of {{WebExtAPIRef('downloads.DownloadItem')}} objects that match the given criteria. ## Browser compatibility diff --git a/files/en-us/mozilla/add-ons/webextensions/api/events/urlfilter/index.md b/files/en-us/mozilla/add-ons/webextensions/api/events/urlfilter/index.md index 3548b40dc43028f..41190a9374da1e3 100644 --- a/files/en-us/mozilla/add-ons/webextensions/api/events/urlfilter/index.md +++ b/files/en-us/mozilla/add-ons/webextensions/api/events/urlfilter/index.md @@ -7,7 +7,7 @@ browser-compat: webextensions.api.events.UrlFilter {{AddonSidebar}} -Describes various criteria for filtering URLs. If all of the criteria specified in the filter's properties match the URL, then the filter matches. Filters are often provided to API methods in an [Array](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array) of UrlFilters. For example, [webNavigation](/en-US/docs/Mozilla/Add-ons/WebExtensions/API/webNavigation) listeners can be added with a filter which is an object with a single `url` property that is an [Array](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array) of UrlFilters, e.g. `{url:[UrlFilter, UrlFilter, …]}`. If any filter within the Array of UrlFilters matches, then it is considered a match for the Array. Effectively, the criteria specified within a single filter are AND'ed together, while all of the individual filters within an Array are OR'ed. +Describes various criteria for filtering URLs. If all of the criteria specified in the filter's properties match the URL, then the filter matches. Filters are often provided to API methods in an [Array](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array) of UrlFilters. For example, [webNavigation](/en-US/docs/Mozilla/Add-ons/WebExtensions/API/webNavigation) listeners can be added with a filter which is an object with a single `url` property that is an [Array](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array) of UrlFilters, e.g., `{url:[UrlFilter, UrlFilter, …]}`. If any filter within the Array of UrlFilters matches, then it is considered a match for the Array. Effectively, the criteria specified within a single filter are AND'ed together, while all of the individual filters within an Array are OR'ed. All criteria are case sensitive. diff --git a/files/en-us/mozilla/add-ons/webextensions/api/extension/index.md b/files/en-us/mozilla/add-ons/webextensions/api/extension/index.md index 836fd2664ed04e1..b189cedb2774a99 100644 --- a/files/en-us/mozilla/add-ons/webextensions/api/extension/index.md +++ b/files/en-us/mozilla/add-ons/webextensions/api/extension/index.md @@ -21,7 +21,7 @@ Utilities related to your extension. Get URLs to resources packages with your ex - {{WebExtAPIRef("extension.lastError")}} {{deprecated_inline}} - : Set for the lifetime of a callback if an asynchronous extension API has resulted in an error. If no error has occurred, `lastError` will be {{jsxref("undefined")}}. - {{WebExtAPIRef("extension.inIncognitoContext")}} - - : `True` for content scripts running inside incognito tabs, and for extension pages running inside an incognito process. (The latter only applies to extensions with '`split`' `incognito_behavior`.) + - : `True` for content scripts running inside incognito tabs, and for extension pages running inside an incognito process. (The latter only applies to extensions with `"incognito": "split"` set in their manifest.json file.) ## Functions diff --git a/files/en-us/mozilla/add-ons/webextensions/api/history/getvisits/index.md b/files/en-us/mozilla/add-ons/webextensions/api/history/getvisits/index.md index 58667d671314f20..529a12aaf292692 100644 --- a/files/en-us/mozilla/add-ons/webextensions/api/history/getvisits/index.md +++ b/files/en-us/mozilla/add-ons/webextensions/api/history/getvisits/index.md @@ -30,7 +30,7 @@ let getting = browser.history.getVisits( ### Return value -A [`Promise`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise) will be fulfilled with an array of `{{WebExtAPIRef('history.VisitItem')}}` objects each representing a visit to the given URL. Visits are sorted in reverse chronological order. +A [`Promise`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise) will be fulfilled with an array of {{WebExtAPIRef('history.VisitItem')}} objects each representing a visit to the given URL. Visits are sorted in reverse chronological order. ## Browser compatibility diff --git a/files/en-us/mozilla/add-ons/webextensions/api/i18n/getacceptlanguages/index.md b/files/en-us/mozilla/add-ons/webextensions/api/i18n/getacceptlanguages/index.md index 4c84690e7605cde..474a5bf9380476b 100644 --- a/files/en-us/mozilla/add-ons/webextensions/api/i18n/getacceptlanguages/index.md +++ b/files/en-us/mozilla/add-ons/webextensions/api/i18n/getacceptlanguages/index.md @@ -7,7 +7,7 @@ browser-compat: webextensions.api.i18n.getAcceptLanguages {{AddonSidebar}} -Gets the [accept-languages](/en-US/docs/Web/HTTP/Content_negotiation#the_accept-language_header) of the browser. This is different from the locale used by the browser. To get the locale, use {{WebExtAPIRef('i18n.getUILanguage')}}. +Gets the [accept-languages](/en-US/docs/Web/HTTP/Guides/Content_negotiation#the_accept-language_header) of the browser. This is different from the locale used by the browser. To get the locale, use {{WebExtAPIRef('i18n.getUILanguage')}}. This is an asynchronous function that returns a [`Promise`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise). @@ -25,7 +25,7 @@ None. ### Return value -A [`Promise`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise) that will be fulfilled with an `array` of `{{WebExtAPIRef('i18n.LanguageCode')}}` objects. +A [`Promise`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise) that will be fulfilled with an `array` of {{WebExtAPIRef('i18n.LanguageCode')}} objects. ## Browser compatibility @@ -36,7 +36,7 @@ A [`Promise`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise) that ```js function onGot(languages) { console.log(languages); - //e.g. Array [ "en-US", "en" ] + // e.g. Array [ "en-US", "en" ] } let gettingAcceptLanguages = browser.i18n.getAcceptLanguages(); diff --git a/files/en-us/mozilla/add-ons/webextensions/api/i18n/getuilanguage/index.md b/files/en-us/mozilla/add-ons/webextensions/api/i18n/getuilanguage/index.md index 169210dc41d327a..1efa82890b8512f 100644 --- a/files/en-us/mozilla/add-ons/webextensions/api/i18n/getuilanguage/index.md +++ b/files/en-us/mozilla/add-ons/webextensions/api/i18n/getuilanguage/index.md @@ -35,7 +35,7 @@ None. let uiLanguage = browser.i18n.getUILanguage(); console.log(uiLanguage); -//e.g. "fr" +// e.g. "fr" ``` {{WebExtExamples}} diff --git a/files/en-us/mozilla/add-ons/webextensions/api/i18n/index.md b/files/en-us/mozilla/add-ons/webextensions/api/i18n/index.md index 77cda78690794e5..1404df59e6cdc16 100644 --- a/files/en-us/mozilla/add-ons/webextensions/api/i18n/index.md +++ b/files/en-us/mozilla/add-ons/webextensions/api/i18n/index.md @@ -7,19 +7,19 @@ browser-compat: webextensions.api.i18n {{AddonSidebar}} -Functions to internationalize your extension. You can use these APIs to get localized strings from locale files packaged with your extension, find out the browser's current language, and find out the value of its [Accept-Language header](/en-US/docs/Web/HTTP/Content_negotiation#the_accept-language_header). +Functions to internationalize your extension. You can use these APIs to get localized strings from locale files packaged with your extension, find out the browser's current language, and find out the value of its [Accept-Language header](/en-US/docs/Web/HTTP/Guides/Content_negotiation#the_accept-language_header). See the [Internationalization](/en-US/docs/Mozilla/Add-ons/WebExtensions/Internationalization) page for a guide on using this API. ## Types - {{WebExtAPIRef("i18n.LanguageCode")}} - - : A [language tag](https://www.rfc-editor.org/rfc/rfc9110.html#name-language-tags) such as `"en-US"` or "`fr`". + - : A [language tag](https://www.rfc-editor.org/rfc/rfc9110.html#name-language-tags) such as `"en-US"` or `"fr"`. ## Functions - {{WebExtAPIRef("i18n.getAcceptLanguages()")}} - - : Gets the [accept-languages](/en-US/docs/Web/HTTP/Content_negotiation#the_accept-language_header) of the browser. This is different from the locale used by the browser. To get the locale, use {{WebExtAPIRef('i18n.getUILanguage')}}. + - : Gets the [accept-languages](/en-US/docs/Web/HTTP/Guides/Content_negotiation#the_accept-language_header) of the browser. This is different from the locale used by the browser. To get the locale, use {{WebExtAPIRef('i18n.getUILanguage')}}. - {{WebExtAPIRef("i18n.getMessage()")}} - : Gets the localized string for the specified message. - {{WebExtAPIRef("i18n.getUILanguage()")}} diff --git a/files/en-us/mozilla/add-ons/webextensions/api/i18n/languagecode/index.md b/files/en-us/mozilla/add-ons/webextensions/api/i18n/languagecode/index.md index 5ac65e76dbeb705..365d0489b31d50d 100644 --- a/files/en-us/mozilla/add-ons/webextensions/api/i18n/languagecode/index.md +++ b/files/en-us/mozilla/add-ons/webextensions/api/i18n/languagecode/index.md @@ -7,7 +7,7 @@ browser-compat: webextensions.api.i18n.LanguageCode {{AddonSidebar}} -A [language tag](https://www.w3.org/Protocols/rfc2616/rfc2616-sec3.html#sec3.10) such as `"en-US"` or "`fr`". +A [language tag](https://www.w3.org/Protocols/rfc2616/rfc2616-sec3.html#sec3.10) such as `"en-US"` or `"fr"`. ## Type diff --git a/files/en-us/mozilla/add-ons/webextensions/api/i18n/locale-specific_message_reference/index.md b/files/en-us/mozilla/add-ons/webextensions/api/i18n/locale-specific_message_reference/index.md index c06c4f5950302cf..b9f745124588c3c 100644 --- a/files/en-us/mozilla/add-ons/webextensions/api/i18n/locale-specific_message_reference/index.md +++ b/files/en-us/mozilla/add-ons/webextensions/api/i18n/locale-specific_message_reference/index.md @@ -105,7 +105,7 @@ Each placeholder substring definition has a number of values of its own: #### placeholder name -The placeholder name is used to represent the placeholder in the substitution string (e.g. `"url"` becomes `$url$`). It is case insensitive and can contain the same characters as a message string [name](#name). +The placeholder name is used to represent the placeholder in the substitution string (e.g., `"url"` becomes `$url$`). It is case insensitive and can contain the same characters as a message string [name](#name). #### content diff --git a/files/en-us/mozilla/add-ons/webextensions/api/management/index.md b/files/en-us/mozilla/add-ons/webextensions/api/management/index.md index 0c12ead07bc0d72..e45b0b4e0384bdc 100644 --- a/files/en-us/mozilla/add-ons/webextensions/api/management/index.md +++ b/files/en-us/mozilla/add-ons/webextensions/api/management/index.md @@ -33,7 +33,7 @@ Most of these operations require the "management" [API permission](/en-US/docs/M - {{WebExtAPIRef("management.getSelf()")}} - : Returns information about the calling add-on. - {{WebExtAPIRef("management.install()")}} - - : Installs a particular theme, given its URL at [addons.mozilla.org](https://addons.mozilla.org). + - : Installs a particular theme, given its URL at [addons.mozilla.org](https://addons.mozilla.org/). - {{WebExtAPIRef("management.uninstall()")}} - : Uninstalls a particular add-on, given its ID. - {{WebExtAPIRef("management.uninstallSelf()")}} diff --git a/files/en-us/mozilla/add-ons/webextensions/api/management/install/index.md b/files/en-us/mozilla/add-ons/webextensions/api/management/install/index.md index ffb294b12254ac2..5391cebc29c5344 100644 --- a/files/en-us/mozilla/add-ons/webextensions/api/management/install/index.md +++ b/files/en-us/mozilla/add-ons/webextensions/api/management/install/index.md @@ -22,7 +22,7 @@ browser.management.install(options) ### Parameters - options - - : An object that includes the URL of the XPI file of the theme at [addons.mozilla.org](https://addons.mozilla.org) and an optional a hash of the XPI file, using sha256 or stronger. + - : An object that includes the URL of the XPI file of the theme at [addons.mozilla.org](https://addons.mozilla.org/) and an optional a hash of the XPI file, using sha256 or stronger. ### Return value diff --git a/files/en-us/mozilla/add-ons/webextensions/api/menus/contexttype/index.md b/files/en-us/mozilla/add-ons/webextensions/api/menus/contexttype/index.md index b4bca5c5692da4e..d6fad12bb0aa540 100644 --- a/files/en-us/mozilla/add-ons/webextensions/api/menus/contexttype/index.md +++ b/files/en-us/mozilla/add-ons/webextensions/api/menus/contexttype/index.md @@ -18,7 +18,7 @@ Values of this type are strings. The item is displayed when the given context ap - action - : Applies when the user context-clicks your browser action in a Manifest V3 extension. The maximum number of items that can be added to the top-level browser action context menu is {{WebExtAPIRef("menus.ACTION_MENU_TOP_LEVEL_LIMIT")}}, but you can add any number of items to submenus. - audio - - : Applies when the user context-clicks an [audio](/en-US/docs/Web/HTML/Element/audio) element. + - : Applies when the user context-clicks an [audio](/en-US/docs/Web/HTML/Reference/Elements/audio) element. - bookmark - : Applies when the user context-clicks a bookmark item in the bookmarks toolbar, bookmarks menu, bookmarks sidebar (<kbd>Ctrl</kbd>+<kbd>B</kbd>) and the Library window (<kbd>Ctrl</kbd>+<kbd>Shift</kbd>+<kbd>B</kbd>). The latter two are supported as of Firefox 66. Requires the "bookmarks" [API permission](/en-US/docs/Mozilla/Add-ons/WebExtensions/manifest.json/permissions#api_permissions) in the manifest. @@ -26,9 +26,9 @@ Values of this type are strings. The item is displayed when the given context ap - browser_action - : Applies when the user context-clicks your browser action in a Manifest V2 extension. The maximum number of items that can be added to the top-level browser action context menu is {{WebExtAPIRef("menus.ACTION_MENU_TOP_LEVEL_LIMIT")}}, but you can add any number of items to submenus. - editable - - : Applies when the user context-clicks an editable element, like a [textarea](/en-US/docs/Web/HTML/Element/textarea). + - : Applies when the user context-clicks an editable element, like a [textarea](/en-US/docs/Web/HTML/Reference/Elements/textarea). - frame - - : Applies when the user context-clicks in a nested [iframe](/en-US/docs/Web/HTML/Element/iframe). + - : Applies when the user context-clicks in a nested [iframe](/en-US/docs/Web/HTML/Reference/Elements/iframe). - image - : Applies when the user context-clicks an image. - link @@ -38,7 +38,7 @@ Values of this type are strings. The item is displayed when the given context ap - page_action - : Applies when the user context-clicks your page action. The maximum number of items that can be added to the top-level page action context menu is {{WebExtAPIRef("menus.ACTION_MENU_TOP_LEVEL_LIMIT")}}, but you can add any number of items to submenus. - password - - : Applies when the user context-clicks on a [password input element](/en-US/docs/Web/HTML/Element/input/password). + - : Applies when the user context-clicks on a [password input element](/en-US/docs/Web/HTML/Reference/Elements/input/password). - selection - : Applies when part of the page is selected. - tab @@ -50,7 +50,7 @@ Values of this type are strings. The item is displayed when the given context ap - tools_menu - : The item will be added to the browser's tools menu. Note that this is only available if you access `ContextType` through the `menus` namespace. It is not available if you access it through the `contextMenus` namespace. - video - - : Applies when the user context-clicks a [video](/en-US/docs/Web/HTML/Element/video) element. + - : Applies when the user context-clicks a [video](/en-US/docs/Web/HTML/Reference/Elements/video) element. Note that "launcher" is not supported. diff --git a/files/en-us/mozilla/add-ons/webextensions/api/menus/create/index.md b/files/en-us/mozilla/add-ons/webextensions/api/menus/create/index.md index 124a8599911d0f1..bf37cb7ddb3286a 100644 --- a/files/en-us/mozilla/add-ons/webextensions/api/menus/create/index.md +++ b/files/en-us/mozilla/add-ons/webextensions/api/menus/create/index.md @@ -56,7 +56,7 @@ browser.menus.create( - `contexts` {{optional_inline}} - - : `array` of `{{WebExtAPIRef('menus.ContextType')}}`. Array of contexts in which this menu item will appear. If this option is omitted: + - : `array` of {{WebExtAPIRef('menus.ContextType')}}. Array of contexts in which this menu item will appear. If this option is omitted: - if the item's parent has contexts set, then this item will inherit its parent's contexts - otherwise, the item is given a context array of \["page"]. @@ -103,7 +103,7 @@ browser.menus.create( - : `string`. The text to be displayed in the item. Mandatory unless `type` is "separator". - You can use "`%s`" in the string. If you do this in a menu item, and some text is selected in the page when the menu is shown, then the selected text will be interpolated into the title. For example, if `title` is "Translate '%s' to Pig Latin" and the user selects the word "cool", then activates the menu, then the menu item's title will be: "Translate 'cool' to Pig Latin". + You can use `%s` in the string. If you do this in a menu item, and some text is selected in the page when the menu is shown, then the selected text will be interpolated into the title. For example, if `title` is "Translate '%s' to Pig Latin" and the user selects the word "cool", then activates the menu, then the menu item's title will be: "Translate 'cool' to Pig Latin". If the title contains an ampersand "&" then the next character will be used as an access key for the item, and the ampersand will not be displayed. Exceptions to this are: @@ -116,9 +116,9 @@ browser.menus.create( In some localized versions of Firefox (Japanese and Chinese), the access key is surrounded by parentheses and appended to the menu label, _unless_ the menu title itself already ends with the access key (`"toolkit(&K)"` for example). For more details, see [Firefox bug 1647373](https://bugzil.la/1647373). - `type` {{optional_inline}} - - : `{{WebExtAPIRef('menus.ItemType')}}`. The type of menu item: "normal", "checkbox", "radio", "separator". Defaults to "normal". + - : {{WebExtAPIRef('menus.ItemType')}}. The type of menu item: "normal", "checkbox", "radio", "separator". Defaults to "normal". - `viewTypes` {{optional_inline}} - - : `{{WebExtAPIRef('extension.ViewType')}}`. List of view types where the menu item will be shown. Defaults to any view, including those without a `viewType`. + - : {{WebExtAPIRef('extension.ViewType')}}. List of view types where the menu item will be shown. Defaults to any view, including those without a `viewType`. - `visible` {{optional_inline}} - : `boolean`. Whether the item is shown in the menu. Defaults to `true`. diff --git a/files/en-us/mozilla/add-ons/webextensions/api/menus/gettargetelement/index.md b/files/en-us/mozilla/add-ons/webextensions/api/menus/gettargetelement/index.md index d22de30616768b5..b227b36f01c03d7 100644 --- a/files/en-us/mozilla/add-ons/webextensions/api/menus/gettargetelement/index.md +++ b/files/en-us/mozilla/add-ons/webextensions/api/menus/gettargetelement/index.md @@ -26,7 +26,7 @@ let elem = browser.menus.getTargetElement(targetElementId); ### Parameters - `targetElementId` - - : The property of the `{{WebExtAPIRef("menus.OnClickData")}}` object passed to the `{{WebExtAPIRef("menus.onClicked")}}` handler or `{{WebExtAPIRef("menus.onShown")}}` event. + - : The property of the {{WebExtAPIRef("menus.OnClickData")}} object passed to the {{WebExtAPIRef("menus.onClicked")}} handler or {{WebExtAPIRef("menus.onShown")}} event. ### Return value diff --git a/files/en-us/mozilla/add-ons/webextensions/api/menus/onclickdata/index.md b/files/en-us/mozilla/add-ons/webextensions/api/menus/onclickdata/index.md index c1c0a8c6c6cb423..40dafa18eaaae3c 100644 --- a/files/en-us/mozilla/add-ons/webextensions/api/menus/onclickdata/index.md +++ b/files/en-us/mozilla/add-ons/webextensions/api/menus/onclickdata/index.md @@ -20,7 +20,7 @@ Values of this type are objects. They contain the following properties: - `checked` {{optional_inline}} - : `boolean`. A flag indicating whether a checkbox or radio item was checked after it was clicked. - `editable` - - : `boolean`. A flag indicating whether the element is editable: for example, if it is a [textarea](/en-US/docs/Web/HTML/Element/textarea). + - : `boolean`. A flag indicating whether the element is editable: for example, if it is a [textarea](/en-US/docs/Web/HTML/Reference/Elements/textarea). - `frameId` {{optional_inline}} - : `integer`. The ID of the frame in which the item was clicked. The frame ID can be used in other APIs that accept frame IDs, such as {{WebExtAPIRef("tabs.sendMessage()")}}. If the item was clicked in the top level document, `frameId` is zero. If the item was clicked outside the page entirely (for example, in the `tools_menu` or `tab` context), then `frameId` is `undefined`. - `frameUrl` {{optional_inline}} @@ -44,7 +44,7 @@ Values of this type are objects. They contain the following properties: - `srcUrl` {{optional_inline}} - : `string`. If present, the `src` value for the media in the clicked element. - `targetElementId` {{optional_inline}} - - : `integer`. An identifier of the element, if any, over which the context menu was created. Use {{WebExtAPIRef("menus.getTargetElement()")}} in the content script to locate the element. Note that this is not the [id](/en-US/docs/Web/HTML/Global_attributes/id) attribute of the page element. + - : `integer`. An identifier of the element, if any, over which the context menu was created. Use {{WebExtAPIRef("menus.getTargetElement()")}} in the content script to locate the element. Note that this is not the [id](/en-US/docs/Web/HTML/Reference/Global_attributes/id) attribute of the page element. - `viewType` {{optional_inline}} - : {{WebExtAPIRef("extension.ViewType", "ViewType")}}. The type of extension view. - `wasChecked` {{optional_inline}} diff --git a/files/en-us/mozilla/add-ons/webextensions/api/menus/onshown/index.md b/files/en-us/mozilla/add-ons/webextensions/api/menus/onshown/index.md index b5ac3b9071940e2..d21f56602a11288 100644 --- a/files/en-us/mozilla/add-ons/webextensions/api/menus/onshown/index.md +++ b/files/en-us/mozilla/add-ons/webextensions/api/menus/onshown/index.md @@ -30,7 +30,7 @@ browser.menus.onShown.addListener(async (info, tab) => { lastMenuInstanceId = menuInstanceId; // Call an async function - await /* the function to call */ ; + await doSomethingAsync(); // After completing the async operation, check whether the menu is still shown. if (menuInstanceId !== lastMenuInstanceId) { @@ -48,7 +48,7 @@ Note that it is possible to call menus API functions synchronously, and in this ```js browser.menus.onShown.addListener(async (info, tab) => { - browser.menus.update(menuId /*, …*/); + browser.menus.update(menuId /*, … */); // Note: Not waiting for returned promise. browser.menus.refresh(); }); @@ -61,7 +61,7 @@ browser.menus.onShown.addListener(async (info, tab) => { let menuInstanceId = nextMenuInstanceId++; lastMenuInstanceId = menuInstanceId; - await browser.menus.update(menuId /*, …*/); + await browser.menus.update(menuId /*, … */); // must now perform the check if (menuInstanceId !== lastMenuInstanceId) { return; diff --git a/files/en-us/mozilla/add-ons/webextensions/api/menus/overridecontext/index.md b/files/en-us/mozilla/add-ons/webextensions/api/menus/overridecontext/index.md index 13c2e62d5f9329d..f899e421d4cffd5 100644 --- a/files/en-us/mozilla/add-ons/webextensions/api/menus/overridecontext/index.md +++ b/files/en-us/mozilla/add-ons/webextensions/api/menus/overridecontext/index.md @@ -50,7 +50,7 @@ document.addEventListener( // set the context to "opening a tab context menu". browser.menus.overrideContext({ context: "tab", - tabId: parseInt(foo.dataset.tabId), + tabId: parseInt(foo.dataset.tabId, 10), }); } }, diff --git a/files/en-us/mozilla/add-ons/webextensions/api/menus/update/index.md b/files/en-us/mozilla/add-ons/webextensions/api/menus/update/index.md index 67866f7d644f953..62088f02df601f5 100644 --- a/files/en-us/mozilla/add-ons/webextensions/api/menus/update/index.md +++ b/files/en-us/mozilla/add-ons/webextensions/api/menus/update/index.md @@ -47,7 +47,7 @@ let updating = browser.menus.update( - `contexts` {{optional_inline}} - - : `array` of `{{WebExtAPIRef('menus.ContextType')}}`. Array of contexts in which this menu item will appear. If this option is omitted: + - : `array` of {{WebExtAPIRef('menus.ContextType')}}. Array of contexts in which this menu item will appear. If this option is omitted: - if the item's parent has contexts set, then this item will inherit its parent's contexts - otherwise, the item is given a context array of \["page"]. @@ -94,7 +94,7 @@ let updating = browser.menus.update( - : `string`. The text to be displayed in the item. Mandatory unless `type` is "separator". - You can use "`%s`" in the string. If you do this in a menu item, and some text is selected in the page when the menu is shown, then the selected text will be interpolated into the title. For example, if `title` is "Translate '%s' to Pig Latin" and the user selects the word "cool", then activates the menu, then the menu item's title will be: "Translate 'cool' to Pig Latin". + You can use `%s` in the string. If you do this in a menu item, and some text is selected in the page when the menu is shown, then the selected text will be interpolated into the title. For example, if `title` is "Translate '%s' to Pig Latin" and the user selects the word "cool", then activates the menu, then the menu item's title will be: "Translate 'cool' to Pig Latin". If the title contains an ampersand "&" then the next character will be used as an access key for the item, and the ampersand will not be displayed. Exceptions to this are: @@ -105,9 +105,9 @@ let updating = browser.menus.update( Only the first ampersand will be used to set an access key: subsequent ampersands will not be displayed but will not set keys. So "\&A and \&B" will be shown as "A and B" and set "A" as the access key. - `type` {{optional_inline}} - - : `{{WebExtAPIRef('menus.ItemType')}}`. The type of menu item: "normal", "checkbox", "radio", "separator". Defaults to "normal". + - : {{WebExtAPIRef('menus.ItemType')}}. The type of menu item: "normal", "checkbox", "radio", "separator". Defaults to "normal". - `viewTypes` {{optional_inline}} - - : `{{WebExtAPIRef('extension.ViewType')}}`. List of view types where the menu item will be shown. Defaults to any view, including those without a `viewType`. + - : {{WebExtAPIRef('extension.ViewType')}}. List of view types where the menu item will be shown. Defaults to any view, including those without a `viewType`. - `visible` {{optional_inline}} - : `boolean`. Whether the item is shown in the menu. Defaults to `true`. diff --git a/files/en-us/mozilla/add-ons/webextensions/api/pageaction/imagedatatype/index.md b/files/en-us/mozilla/add-ons/webextensions/api/pageaction/imagedatatype/index.md index ff5d514970e7973..0012abb3824e89e 100644 --- a/files/en-us/mozilla/add-ons/webextensions/api/pageaction/imagedatatype/index.md +++ b/files/en-us/mozilla/add-ons/webextensions/api/pageaction/imagedatatype/index.md @@ -11,7 +11,7 @@ Pixel data for an image. ## Type -An [`ImageData`](/en-US/docs/Web/API/ImageData) object, e.g. from a {{htmlelement("canvas")}} element. +An [`ImageData`](/en-US/docs/Web/API/ImageData) object, e.g., from a {{htmlelement("canvas")}} element. ## Browser compatibility diff --git a/files/en-us/mozilla/add-ons/webextensions/api/pageaction/seticon/index.md b/files/en-us/mozilla/add-ons/webextensions/api/pageaction/seticon/index.md index 11e01053be312a1..22946d6a550a0ef 100644 --- a/files/en-us/mozilla/add-ons/webextensions/api/pageaction/seticon/index.md +++ b/files/en-us/mozilla/add-ons/webextensions/api/pageaction/seticon/index.md @@ -31,7 +31,7 @@ let settingIcon = browser.pageAction.setIcon( - `imageData` {{optional_inline}} - - : `{{WebExtAPIRef('pageAction.ImageDataType')}}` or `object`. This is either a single `ImageData` object or a dictionary object. + - : {{WebExtAPIRef('pageAction.ImageDataType')}} or `object`. This is either a single `ImageData` object or a dictionary object. Use a dictionary object to specify multiple `ImageData` objects in different sizes, so the icon does not have to be scaled for a device with a different pixel density. If `imageData` is a dictionary, the value of each property is an `ImageData` object, and its name is its size, like this: diff --git a/files/en-us/mozilla/add-ons/webextensions/api/privacy/websites/index.md b/files/en-us/mozilla/add-ons/webextensions/api/privacy/websites/index.md index 581d061136ec9f9..f1c9d10696b3244 100644 --- a/files/en-us/mozilla/add-ons/webextensions/api/privacy/websites/index.md +++ b/files/en-us/mozilla/add-ons/webextensions/api/privacy/websites/index.md @@ -43,7 +43,7 @@ Default values for these properties tend to vary across browsers. - `protectedContentEnabled` - : A {{WebExtAPIRef("types.BrowserSetting")}} object whose underlying value is a boolean. Available on Windows only. If `true`, the browser provides a unique ID to plugins in order to run protected content. - `referrersEnabled` - - : A {{WebExtAPIRef("types.BrowserSetting")}} object whose underlying value is a boolean. If enabled, the browser sends [referer](/en-US/docs/Web/HTTP/Headers/Referer) headers with your requests. + - : A {{WebExtAPIRef("types.BrowserSetting")}} object whose underlying value is a boolean. If enabled, the browser sends [referer](/en-US/docs/Web/HTTP/Reference/Headers/Referer) headers with your requests. - `resistFingerprinting` - : A {{WebExtAPIRef("types.BrowserSetting")}} object whose underlying value is a boolean. diff --git a/files/en-us/mozilla/add-ons/webextensions/api/proxy/onrequest/index.md b/files/en-us/mozilla/add-ons/webextensions/api/proxy/onrequest/index.md index f147c501fe48619..9e478da9d35d8b0 100644 --- a/files/en-us/mozilla/add-ons/webextensions/api/proxy/onrequest/index.md +++ b/files/en-us/mozilla/add-ons/webextensions/api/proxy/onrequest/index.md @@ -17,7 +17,7 @@ This event is closely modeled on the events defined in the [`webRequest`](/en-US The event is fired before any of the `webRequest` events for the same request. -When the event is fired, the listener is called with an object containing information about the request. The listener returns a {{WebExtAPIRef("proxy.ProxyInfo")}} object representing a proxy to use (or an array of {{WebExtAPIRef("proxy.ProxyInfo")}} objects, enabling the browser to fail over if a proxy is unreachable). +When the event is fired, the listener is called with an object containing information about the request. The listener returns a {{WebExtAPIRef("proxy.ProxyInfo")}} object representing a proxy to use (or an array of {{WebExtAPIRef("proxy.ProxyInfo")}} objects, enabling the browser to fail over if a proxy is unreachable). By default, the request fails over to any browser-defined proxy unless a `null` object or an array ending in a `null` object is returned. To use `proxy.onRequest`, an extension must have the "proxy" [API permission](/en-US/docs/Mozilla/Add-ons/WebExtensions/manifest.json/permissions#api_permissions) and the [host permission](/en-US/docs/Mozilla/Add-ons/WebExtensions/manifest.json/permissions#host_permissions) for the URLs of the requests that it intercepts, which means that the match patterns in the `filter` argument must be a subset of the extension's host permissions. @@ -38,9 +38,9 @@ Events have three functions: - `addListener(listener, filter, extraInfoSpec)` - : Adds a listener to this event. - `removeListener(listener)` - - : Stop listening to this event. The `listener` argument is the listener to remove. + - : Stops listening to this event. The `listener` argument is the listener to remove. - `hasListener(listener)` - - : Check whether `listener` is registered for this event. Returns `true` if it is listening, `false` otherwise. + - : Checks whether `listener` is registered for this event. Returns `true` if it is listening, `false` otherwise. ## addListener syntax @@ -48,7 +48,7 @@ Events have three functions: - `listener` - - : The function that is called when this event occurs. The function is passed a single argument, which is a {{WebExtAPIRef("proxy.RequestDetails")}} object containing details of the request. + - : The function called when this event occurs. The function is passed one argument, which is a {{WebExtAPIRef("proxy.RequestDetails")}} object containing details of the request. The listener can return any of: @@ -57,19 +57,17 @@ Events have three functions: - a `Promise` that resolves to a `ProxyInfo` object. - a `Promise` that resolves to an array of `ProxyInfo` objects. - If the listener returns an array, or a Promise that resolves to an array, then all `ProxyInfo` objects after the first one represent failovers: if the proxy at position N in the array is not reachable when its `ProxyInfo.failoverTimeout` expires the browser will try the proxy at position N+1. + When the listener returns an array or a Promise that resolves to an array, the `ProxyInfo` objects after the first one represent failovers. If the proxy at position N in the array is not reachable when its `ProxyInfo.failoverTimeout` expires, the browser tries the proxy at position N+1. + + By default, the request fails over to any browser-defined proxy unless a `null` object or an array ending in a `null` object (`[{ ... proxy info ...} , null]`) is returned. If there is an error specifying the {{WebExtAPIRef("proxy.ProxyInfo")}} objects, then {{WebExtAPIRef("proxy.onError")}} is called. - `filter` - - : {{WebExtAPIRef('webRequest.RequestFilter')}}. A set of filters that restricts the events that are sent to the listener. + - : {{WebExtAPIRef('webRequest.RequestFilter')}}. A set of filters that restricts the events sent to the listener. - `extraInfoSpec` {{optional_inline}} - : `array` of `string`. Extra options for the event. Pass `"requestHeaders"` to include the request headers in the `details` object passed to the listener. -## Browser compatibility - -{{Compat}} - ## Examples This code intercepts requests to `<all_urls>`, and proxies them if they are not for a top-level frame. @@ -93,3 +91,7 @@ browser.proxy.onRequest.addListener(handleProxyRequest, { ``` {{WebExtExamples}} + +## Browser compatibility + +{{Compat}} diff --git a/files/en-us/mozilla/add-ons/webextensions/api/proxy/proxyinfo/index.md b/files/en-us/mozilla/add-ons/webextensions/api/proxy/proxyinfo/index.md index 3a842c261fa093c..123da8cd9b4e886 100644 --- a/files/en-us/mozilla/add-ons/webextensions/api/proxy/proxyinfo/index.md +++ b/files/en-us/mozilla/add-ons/webextensions/api/proxy/proxyinfo/index.md @@ -37,7 +37,7 @@ Values of this type are objects. They contain the following properties: - : `number`. Failover timeout in seconds. If the connection fails to connect the proxy server after this number of seconds, the next proxy server in the array returned from the `proxy.onRequest` listener will be used. - `proxyAuthorizationHeader` - - : `string`. When set, this is passed to the {{httpheader("Proxy-Authorization")}} request header sent to HTTP or HTTPS proxies as part of a [CONNECT](/en-US/docs/Web/HTTP/Methods/CONNECT) request. Used to authenticate to HTTP and HTTPS proxies that allow non-challenging authentication. + - : `string`. When set, this is passed to the {{httpheader("Proxy-Authorization")}} request header sent to HTTP or HTTPS proxies as part of a [CONNECT](/en-US/docs/Web/HTTP/Reference/Methods/CONNECT) request. Used to authenticate to HTTP and HTTPS proxies that allow non-challenging authentication. For instance, if you want to send "username" and "password" for "basic" authentication, you can set the `proxyAuthorizationHeader` property to `Basic dXNlcm5hbWU6cGFzc3dvcmQ=` diff --git a/files/en-us/mozilla/add-ons/webextensions/api/proxy/requestdetails/index.md b/files/en-us/mozilla/add-ons/webextensions/api/proxy/requestdetails/index.md index c119cd6c0b64a2b..f5de0a5fb9bed99 100644 --- a/files/en-us/mozilla/add-ons/webextensions/api/proxy/requestdetails/index.md +++ b/files/en-us/mozilla/add-ons/webextensions/api/proxy/requestdetails/index.md @@ -26,7 +26,7 @@ Values of this type are objects. They contain the following properties: - `method` - : `string`. Standard HTTP method: for example, "GET" or "POST". - `originUrl` - - : `string`. URL of the resource that triggered the request. Note that this may not be the same as the URL of the page into which the requested resource will be loaded. For example, if a document triggers a load in a different window through the [target attribute of a link](/en-US/docs/Web/HTML/Element/a#target), or a CSS document includes an image using the [`url()` functional notation](/en-US/docs/Web/CSS/url_function), then this is the URL of the original document or of the CSS document, respectively. + - : `string`. URL of the resource that triggered the request. Note that this may not be the same as the URL of the page into which the requested resource will be loaded. For example, if a document triggers a load in a different window through the [target attribute of a link](/en-US/docs/Web/HTML/Reference/Elements/a#target), or a CSS document includes an image using the [`url()` functional notation](/en-US/docs/Web/CSS/url_function), then this is the URL of the original document or of the CSS document, respectively. - `parentFrameId` - : `integer`. ID of the frame that contains the frame that sent the request. Set to -1 if no parent frame exists. - `requestId` diff --git a/files/en-us/mozilla/add-ons/webextensions/api/runtime/getbackgroundpage/index.md b/files/en-us/mozilla/add-ons/webextensions/api/runtime/getbackgroundpage/index.md index d0141feb3570ea0..3f5240aecb50887 100644 --- a/files/en-us/mozilla/add-ons/webextensions/api/runtime/getbackgroundpage/index.md +++ b/files/en-us/mozilla/add-ons/webextensions/api/runtime/getbackgroundpage/index.md @@ -22,7 +22,7 @@ This is an asynchronous function that returns a {{JSxRef("Promise")}}. > [!NOTE] > In Firefox, this method cannot be used in Private Browsing mode — it always returns `null`. For more info see [Firefox bug 1329304](https://bugzil.la/1329304). > -> In Chrome, this method is available only with persistent background pages, which are not available in Manifest V3, so consider using Manifest V2. See the [this](https://developer.chrome.com/docs/extensions/develop/migrate/to-service-workers) for details. +> In Chrome, this method is available only with persistent background pages, which are not available in Manifest V3, so consider using Manifest V2. See [Migrate to a service worker](https://developer.chrome.com/docs/extensions/develop/migrate/to-service-workers) for details. > > Consider using {{WebExtAPIRef("runtime.sendMessage","runtime.sendMessage()")}} or {{WebExtAPIRef("runtime.connect","runtime.connect()")}}, which work correctly in both scenarios above. diff --git a/files/en-us/mozilla/add-ons/webextensions/api/runtime/getcontexts/index.md b/files/en-us/mozilla/add-ons/webextensions/api/runtime/getcontexts/index.md index 2d8710de469e11c..f6358fa72003b58 100644 --- a/files/en-us/mozilla/add-ons/webextensions/api/runtime/getcontexts/index.md +++ b/files/en-us/mozilla/add-ons/webextensions/api/runtime/getcontexts/index.md @@ -12,7 +12,7 @@ Returns information about the contexts associated with the extension. ## Syntax ```js-nolint -let gettingContexts = browser.runtime.getContexts( +let gettingContexts = await browser.runtime.getContexts( filter // object ); ``` @@ -52,7 +52,7 @@ A [`Promise`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise) that - `documentId` - : `string`. UUID of the document associated with the context, or undefined if the context is not hosted in a document. - `documentOrigin` - - : string`. The origin of the document associated with the context or undefined if the context is not hosted in a document. + - : `string`. The origin of the document associated with the context or undefined if the context is not hosted in a document. - `documentUrl` - : `string`. The URL of the document associated with the context or undefined if the context is not hosted in a document. - `frameId` @@ -73,7 +73,7 @@ This example gets all the contexts associated with the extension in private brow ```js function gotContextInfo(contexts) { for (const context of contexts) { - if (context.tabId == -1) { + if (context.tabId === -1) { console.log("Not hosted in a tab"); } else { console.log( @@ -83,7 +83,7 @@ function gotContextInfo(contexts) { } } -let gettingContextInfo = browser.runtime.getContext({ incognito: true }); +let gettingContextInfo = browser.runtime.getContexts({ incognito: true }); gettingContextInfo.then(gotContextInfo); ``` diff --git a/files/en-us/mozilla/add-ons/webextensions/api/runtime/index.md b/files/en-us/mozilla/add-ons/webextensions/api/runtime/index.md index 3f99ba132e184da..0d0af6f721c3d78 100644 --- a/files/en-us/mozilla/add-ons/webextensions/api/runtime/index.md +++ b/files/en-us/mozilla/add-ons/webextensions/api/runtime/index.md @@ -27,6 +27,8 @@ It also provides messaging APIs enabling you to: - : Identifies the browser's processor architecture. - {{WebExtAPIRef("runtime.PlatformInfo")}} - : Contains information about the platform the browser is running on. +- {{WebExtAPIRef("runtime.PlatformNaclArch")}} + - : The native client architecture. This may be different from `PlatformArch` on some platforms. - {{WebExtAPIRef("runtime.RequestUpdateCheckStatus")}} - : Result of a call to {{WebExtAPIRef("runtime.requestUpdateCheck()")}}. - {{WebExtAPIRef("runtime.OnInstalledReason")}} diff --git a/files/en-us/mozilla/add-ons/webextensions/api/runtime/messagesender/index.md b/files/en-us/mozilla/add-ons/webextensions/api/runtime/messagesender/index.md index 4e17ac8fac95e59..319318852919869 100644 --- a/files/en-us/mozilla/add-ons/webextensions/api/runtime/messagesender/index.md +++ b/files/en-us/mozilla/add-ons/webextensions/api/runtime/messagesender/index.md @@ -38,7 +38,7 @@ Values of this type are objects. They contain the following properties: If the sender is a script running in a web page (including content and normal page scripts), then `url` is the web page URL. If the script is running in an iframe, `url` is the iframe's URL. - `userScriptWorldId` {{optional_inline}} - - : `string`. The `worldId` of the `USER_SCRIPT` world that sent the message. Only present in {{WebExtAPIRef("runtime.onUserScriptMessage")}} and in {{WebExtAPIRef("port.sender")}} for {{WebExtAPIRef("runtime.onUserScriptConnect")}}. + - : `string`. The `worldId` of the `USER_SCRIPT` world that sent the message. Only present in {{WebExtAPIRef("runtime.onUserScriptMessage")}} and in [`port.sender`](/en-US/docs/Mozilla/Add-ons/WebExtensions/API/runtime/Port#sender) for {{WebExtAPIRef("runtime.onUserScriptConnect")}}. {{WebExtExamples}} diff --git a/files/en-us/mozilla/add-ons/webextensions/api/runtime/onmessage/index.md b/files/en-us/mozilla/add-ons/webextensions/api/runtime/onmessage/index.md index 94d5c85bfba4fff..fd01488c9659b29 100644 --- a/files/en-us/mozilla/add-ons/webextensions/api/runtime/onmessage/index.md +++ b/files/en-us/mozilla/add-ons/webextensions/api/runtime/onmessage/index.md @@ -13,7 +13,7 @@ Some example use cases are: - **in a [content script](/en-US/docs/Mozilla/Add-ons/WebExtensions/Anatomy_of_a_WebExtension#content_scripts)** to listen for messages from a [background script.](/en-US/docs/Mozilla/Add-ons/WebExtensions/Anatomy_of_a_WebExtension#background_scripts) - **in a background script** to listen for messages from a content script. -- **in an [options page](/en-US/docs/Mozilla/Add-ons/WebExtensions/Anatomy_of_a_WebExtension#options_pages) or [popup](/en-US/docs/Mozilla/Add-ons/WebExtensions/user_interface#popups) script** to listen for messages from a background script. +- **in an [options page or popup](/en-US/docs/Mozilla/Add-ons/WebExtensions/Anatomy_of_a_WebExtension#sidebars_popups_and_options_pages) script** to listen for messages from a background script. - **in a background script** to listen for messages from an options page or popup script. To send a message that is received by the `onMessage()` listener, use {{WebExtAPIRef("runtime.sendMessage()")}} or (to send a message to a content script) {{WebExtAPIRef("tabs.sendMessage()")}}. @@ -243,7 +243,7 @@ browser.runtime .then(handleResponse); ``` -Here is the background script. It uses `{{WebExtAPIRef("bookmarks.search()")}}` to see if the link is bookmarked, which returns a {{jsxref("Promise")}}: +Here is the background script. It uses {{WebExtAPIRef("bookmarks.search()")}} to see if the link is bookmarked, which returns a {{jsxref("Promise")}}: ```js // background-script.js diff --git a/files/en-us/mozilla/add-ons/webextensions/api/scripting/executescript/index.md b/files/en-us/mozilla/add-ons/webextensions/api/scripting/executescript/index.md index f86cbde18daf160..cfdcbfdaed2096c 100644 --- a/files/en-us/mozilla/add-ons/webextensions/api/scripting/executescript/index.md +++ b/files/en-us/mozilla/add-ons/webextensions/api/scripting/executescript/index.md @@ -72,7 +72,7 @@ let foo = "my result"; foo; ``` -Here the results array contains the string "`my result`" as an element. +Here the results array contains the string `"my result"` as an element. The script result must be a [structured cloneable](/en-US/docs/Web/API/Web_Workers_API/Structured_clone_algorithm) value in Firefox or a [JSON-serializable](/en-US/docs/Web/JavaScript/Reference/Global_Objects/JSON/stringify#description) value in Chrome. The [Chrome incompatibilities](/en-US/docs/Mozilla/Add-ons/WebExtensions/Chrome_incompatibilities) article discusses this difference in more detail in the [Data cloning algorithm](/en-US/docs/Mozilla/Add-ons/WebExtensions/Chrome_incompatibilities#data_cloning_algorithm) section. diff --git a/files/en-us/mozilla/add-ons/webextensions/api/scripting/registeredcontentscript/index.md b/files/en-us/mozilla/add-ons/webextensions/api/scripting/registeredcontentscript/index.md index 60e51129ebceaca..7dba0c8b5b0851d 100644 --- a/files/en-us/mozilla/add-ons/webextensions/api/scripting/registeredcontentscript/index.md +++ b/files/en-us/mozilla/add-ons/webextensions/api/scripting/registeredcontentscript/index.md @@ -29,6 +29,8 @@ Values of this type are objects. They contain these properties: - : `boolean`. Whether code is injected into `about:`, `data:`, and `blob:` pages when their origin matches the pattern in `matches`, even if the document origin is opaque (due to the use of CSP or iframe sandbox). Match patterns in `matches` must specify a wildcard path glob. Defaults to `false`. - `persistAcrossSessions` {{optional_inline}} - : `boolean`. Specifies if this content script persists across browser restarts and updates and extension restarts. Defaults to `true`. + > [!NOTE] + > When an extension updates, content scripts are cleared. To restore scripts, add code to the extension's {{WebExtAPIRef("runtime.onInstalled")}} event handler that responds to the `"update"` reason. - `runAt` {{optional_inline}} - : {{WebExtAPIRef("extensionTypes.RunAt")}}. Specifies when JavaScript files are injected into the web page. The default value is `document_idle`. In Firefox, `runAt` also affects the point where the CSS is inserted. In Chrome, `runAt` does not affect the CSS insertion point. - `world` {{optional_inline}} diff --git a/files/en-us/mozilla/add-ons/webextensions/api/sidebaraction/setpanel/index.md b/files/en-us/mozilla/add-ons/webextensions/api/sidebaraction/setpanel/index.md index 85b6447cc30cb3e..b9ee206b2141f8f 100644 --- a/files/en-us/mozilla/add-ons/webextensions/api/sidebaraction/setpanel/index.md +++ b/files/en-us/mozilla/add-ons/webextensions/api/sidebaraction/setpanel/index.md @@ -37,7 +37,7 @@ browser.sidebarAction.setPanel( - : `string` or `null`. The panel to load into the sidebar, specified as a URL pointing to an HTML document, or `null`, or an empty string. - This can point to a file packaged within the extension (for example, created using {{WebExtAPIRef("runtime.getURL")}}), or a remote document (e.g. `https://example.org/`). It must be a valid URL. + This can point to a file packaged within the extension (for example, created using {{WebExtAPIRef("runtime.getURL")}}), or a remote document (e.g., `https://example.org/`). It must be a valid URL. If `panel` is `null` or `""`, then a previously set panel will be removed, so that: diff --git a/files/en-us/mozilla/add-ons/webextensions/api/storage/index.md b/files/en-us/mozilla/add-ons/webextensions/api/storage/index.md index 7d9f45cd2f0afab..33c2e9ef5fbb396 100644 --- a/files/en-us/mozilla/add-ons/webextensions/api/storage/index.md +++ b/files/en-us/mozilla/add-ons/webextensions/api/storage/index.md @@ -12,7 +12,7 @@ Enables extensions to store and retrieve data, and listen for changes to stored The storage system is based on the [Web Storage API](/en-US/docs/Web/API/Web_Storage_API), with a few differences. Among other differences, these include: - It's asynchronous. -- Values are scoped to the extension, not to a specific domain (i.e. the same set of key/value pairs are available to all scripts in the background context and content scripts). +- Values are scoped to the extension, not to a specific domain (i.e., the same set of key/value pairs are available to all scripts in the background context and content scripts). - The values stored can be any JSON-ifiable value, not just [`String`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/String). Among other things, this includes: [`Array`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array) and [`Object`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object), but only when their contents can be represented as JSON, which does not include DOM nodes. You don't need to convert your values to JSON `Strings` prior to storing them, but they are represented as JSON internally, thus the requirement that they be JSON-ifiable. - Multiple key/value pairs can be set or retrieved in the same API call. diff --git a/files/en-us/mozilla/add-ons/webextensions/api/storage/local/index.md b/files/en-us/mozilla/add-ons/webextensions/api/storage/local/index.md index 688698c1e546c64..3e3351e744320d8 100644 --- a/files/en-us/mozilla/add-ons/webextensions/api/storage/local/index.md +++ b/files/en-us/mozilla/add-ons/webextensions/api/storage/local/index.md @@ -12,7 +12,7 @@ Represents the `local` storage area. Items in `local` storage are local to the m The browser may restrict the amount of data that an extension can store in the local storage area. For example: - In Chrome, an extension is limited to storing 5MB of data using this API unless it has the [`"unlimitedStorage"` permission](/en-US/docs/Mozilla/Add-ons/WebExtensions/manifest.json/permissions#unlimited_storage). -- In Firefox, the amount of data an extension can store is subjected to the same [storage limits](/en-US/docs/Web/API/Storage_API/Storage_quotas_and_eviction_criteria#storage_limits) as applied to IndexedDB databases. Extensions that intend to store more data than this limit need the ["unlimitedStorage"](/en-US/docs/Mozilla/Add-ons/WebExtensions/manifest.json/permissions#unlimited_storage) permission. However, extensions with the "unlimitedStorage" permission may get a quota exceeded error when the disk space used by storage exceeds the global limit. +- In Firefox, the amount of data an extension can store is subjected to the same [storage limits](/en-US/docs/Web/API/Storage_API/Storage_quotas_and_eviction_criteria#how_much_data_can_be_stored) as applied to IndexedDB databases. Extensions that intend to store more data than this limit need the ["unlimitedStorage"](/en-US/docs/Mozilla/Add-ons/WebExtensions/manifest.json/permissions#unlimited_storage) permission. However, extensions with the "unlimitedStorage" permission may get a quota exceeded error when the disk space used by storage exceeds the global limit. When the extension is uninstalled, its associated local storage is cleared. diff --git a/files/en-us/mozilla/add-ons/webextensions/api/tabgroups/color/index.md b/files/en-us/mozilla/add-ons/webextensions/api/tabgroups/color/index.md new file mode 100644 index 000000000000000..8bfa8a274c0a8e6 --- /dev/null +++ b/files/en-us/mozilla/add-ons/webextensions/api/tabgroups/color/index.md @@ -0,0 +1,30 @@ +--- +title: tabGroups.Color +slug: Mozilla/Add-ons/WebExtensions/API/tabGroups/Color +page-type: webextension-api-type +browser-compat: webextensions.api.tabGroups.Color +--- + +{{AddonSidebar}} + +The color of a tab group. + +## Type + +Values of this type are a string and can take these values: + +- blue +- cyan +- grey +- green +- orange +- pink +- purple +- red +- yellow + +{{WebExtExamples("h2")}} + +## Browser compatibility + +{{Compat}} diff --git a/files/en-us/mozilla/add-ons/webextensions/api/tabgroups/get/index.md b/files/en-us/mozilla/add-ons/webextensions/api/tabgroups/get/index.md new file mode 100644 index 000000000000000..9ea035a74fcfe18 --- /dev/null +++ b/files/en-us/mozilla/add-ons/webextensions/api/tabgroups/get/index.md @@ -0,0 +1,33 @@ +--- +title: tabGroups.get +slug: Mozilla/Add-ons/WebExtensions/API/tabGroups/get +page-type: webextension-api-function +browser-compat: webextensions.api.tabGroups.get +--- + +{{AddonSidebar}} + +Returns details about a tab group. + +## Syntax + +```js-nolint +let tabGroupDetails = await browser.tabGroups.get( + groupId // integer +); +``` + +### Parameters + +- `groupId` + - : `integer`. The ID of the tab group to return details for. + +### Return value + +A [`Promise`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise) fulfilled with a {{WebExtAPIRef("tabGroups.TabGroup")}} object. If the request fails, the promise is rejected with an error message. + +{{WebExtExamples("h2")}} + +## Browser compatibility + +{{Compat}} diff --git a/files/en-us/mozilla/add-ons/webextensions/api/tabgroups/index.md b/files/en-us/mozilla/add-ons/webextensions/api/tabgroups/index.md new file mode 100644 index 000000000000000..26ce84c93cec489 --- /dev/null +++ b/files/en-us/mozilla/add-ons/webextensions/api/tabgroups/index.md @@ -0,0 +1,65 @@ +--- +title: tabGroups +slug: Mozilla/Add-ons/WebExtensions/API/tabGroups +page-type: webextension-api +browser-compat: webextensions.api.tabGroups +--- + +{{AddonSidebar}} + +This API enables extensions to modify and rearrange [tab groups](https://support.mozilla.org/en-US/kb/tab-groups). + +Tab groups may persist across browser restarts as part of session restore. Tab groups in private browsing windows do not persist across restarts. When a tab group is restored, its `groupId` may differ from its original value. + +The `tabGroups` API doesn't offer the ability to create or remove tab groups. Use the {{WebExtAPIRef("tabs.group()")}} and {{WebExtAPIRef("tabs.ungroup()")}} methods instead. To query the position of a tab group within a window, use {{WebExtAPIRef("tabs.query()")}}. These APIs in the `tabs` namespace don't require any permissions. + +## Permissions + +To use this API, an extension must request the `"tabGroups"` [permission](/en-US/docs/Mozilla/Add-ons/WebExtensions/manifest.json/permissions) in its [`manifest.json`](/en-US/docs/Mozilla/Add-ons/WebExtensions/manifest.json) file. The `"tabGroups"` permission is not shown to users in permission prompts. + +## Types + +- {{WebExtAPIRef("tabGroups.Color")}} + - : The color of a tab group. +- {{WebExtAPIRef("tabGroups.TabGroup")}} + - : The state of a tab group. + +## Properties + +- {{WebExtAPIRef("tabGroups.TAB_GROUP_ID_NONE")}} + - : The tab group ID value returned when a tab isn't in a tab group. + +## Functions + +- {{WebExtAPIRef("tabGroups.get()")}} + - : Returns details about a tab group. +- {{WebExtAPIRef("tabGroups.move()")}} + - : Moves a tab group within or to another window. +- {{WebExtAPIRef("tabGroups.query()")}} + - : Returns all tab groups or finds tab groups with certain properties. +- {{WebExtAPIRef("tabGroups.update()")}} + - : Modifies the state of a tab group. + +## Events + +- {{WebExtAPIRef("tabGroups.onCreated")}} + - : Fires when a tab group is created. +- {{WebExtAPIRef("tabGroups.onMoved")}} + - : Fires when a tab group is moved within a window or to another window. +- {{WebExtAPIRef("tabGroups.onRemoved")}} + - : Fires when a tab group is removed. +- {{WebExtAPIRef("tabGroups.onUpdated")}} + - : Fires when a tab group is updated. + +{{WebExtExamples("h2")}} + +## Browser compatibility + +{{Compat}} + +## See also + +- {{WebExtAPIRef("tabs.group()")}} +- {{WebExtAPIRef("tabs.ungroup()")}} +- {{WebExtAPIRef("tabs.query()")}} +- {{WebExtAPIRef("tabs.Tab")}} diff --git a/files/en-us/mozilla/add-ons/webextensions/api/tabgroups/move/index.md b/files/en-us/mozilla/add-ons/webextensions/api/tabgroups/move/index.md new file mode 100644 index 000000000000000..04ff72acd286037 --- /dev/null +++ b/files/en-us/mozilla/add-ons/webextensions/api/tabgroups/move/index.md @@ -0,0 +1,42 @@ +--- +title: tabGroups.move +slug: Mozilla/Add-ons/WebExtensions/API/tabGroups/move +page-type: webextension-api-function +browser-compat: webextensions.api.tabGroups.move +--- + +{{AddonSidebar}} + +Moves a tab group within or to another window. Groups can't be moved before a pinned tab or inside another tab group. + +## Syntax + +```js-nolint +let movedTabGroup = await browser.tabGroups.move( + groupId, // integer + moveProperties // object +); +``` + +### Parameters + +- `groupId` + + - : `integer` The ID of the tab group to move. + +- `moveProperties` + - : An object containing details of the location to move the tab group to. + - `index` + - : `integer`. The position to move the group to. After moving, the first tab in the tab group is at this index in the tab strip. Use -1 to place the group at the end of the window. + - `windowId` {{optional_inline}} + - : `integer`. The window to move the group to. Defaults to the window the group is in. Groups can only be moved to and from windows with {{WebExtAPIRef("windows.WindowType")}} type `"normal"`. + +### Return value + +A [`Promise`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise) fulfilled with a {{WebExtAPIRef("tabGroups.TabGroup")}} object. If the request fails, the promise is rejected with an error message. + +{{WebExtExamples("h2")}} + +## Browser compatibility + +{{Compat}} diff --git a/files/en-us/mozilla/add-ons/webextensions/api/tabgroups/oncreated/index.md b/files/en-us/mozilla/add-ons/webextensions/api/tabgroups/oncreated/index.md new file mode 100644 index 000000000000000..e9cf42859848253 --- /dev/null +++ b/files/en-us/mozilla/add-ons/webextensions/api/tabgroups/oncreated/index.md @@ -0,0 +1,60 @@ +--- +title: tabGroups.onCreated +slug: Mozilla/Add-ons/WebExtensions/API/tabGroups/onCreated +page-type: webextension-api-event +browser-compat: webextensions.api.tabGroups.onCreated +--- + +{{AddonSidebar}} + +Fires when a tab group is created. + +In Chrome, this event is also fired when a tab group is moved between windows, instead of {{WebExtAPIRef("tabGroups.onMoved")}}. + +## Syntax + +```js-nolint +browser.tabGroups.onCreated.addListener(listener) +browser.tabGroups.onCreated.removeListener(listener) +browser.tabGroups.onCreated.hasListener(listener) +``` + +Events have three functions: + +- `addListener(listener)` + - : Adds a listener to this event. +- `removeListener(listener)` + - : Stops listening to this event. The `listener` argument is the listener to remove. +- `hasListener(listener)` + - : Checks whether `listener` is registered for this event. Returns `true` if it is listening, `false` otherwise. + +## addListener syntax + +### Parameters + +- `listener` + + - : The function called when this event occurs. The function is passed this argument: + + - `group` + - : {{WebExtAPIRef("tabGroups.TabGroup")}}. Details of the created tab group's state. + +## Examples + +Listen for and log tab group creation: + +```js +function tabGroupCreated(group) { + console.log( + `Tab group with ID ${group.id} was created in window ${group.windowId}.`, + ); +} + +browser.tabGroups.onCreated.addListener(tabGroupCreated); +``` + +{{WebExtExamples}} + +## Browser compatibility + +{{Compat}} diff --git a/files/en-us/mozilla/add-ons/webextensions/api/tabgroups/onmoved/index.md b/files/en-us/mozilla/add-ons/webextensions/api/tabgroups/onmoved/index.md new file mode 100644 index 000000000000000..881b7bab71bbadb --- /dev/null +++ b/files/en-us/mozilla/add-ons/webextensions/api/tabgroups/onmoved/index.md @@ -0,0 +1,73 @@ +--- +title: tabGroups.onMoved +slug: Mozilla/Add-ons/WebExtensions/API/tabGroups/onMoved +page-type: webextension-api-event +browser-compat: webextensions.api.tabGroups.onMoved +--- + +{{AddonSidebar}} + +Fires when a tab group is moved within a window or to another window. {{WebExtAPIRef("tabs.onMoved")}} also fire for the tabs within the group. + +The event is passed a {{WebExtAPIRef("tabGroups.TabGroup")}} object. This includes the `windowId` but not the position of the tab group. To determine the position of the tab group, use {{WebExtAPIRef("tabs.query()")}} with the `groupId`, and read the `index` property of the returned tab. + +In Chrome, this event doesn't fire when a tab group is moved between windows; instead, the group is removed from one window and created in another (firing {{WebExtAPIRef("tabGroups.onRemoved")}} and {{WebExtAPIRef("tabGroups.onCreated")}}. + +## Syntax + +```js-nolint +browser.tabGroups.onMoved.addListener(listener) +browser.tabGroups.onMoved.removeListener(listener) +browser.tabGroups.onMoved.hasListener(listener) +``` + +Events have three functions: + +- `addListener(listener)` + - : Adds a listener to this event. +- `removeListener(listener)` + - : Stops listening to this event. The `listener` argument is the listener to remove. +- `hasListener(listener)` + - : Checks whether `listener` is registered for this event. Returns `true` if it is listening, `false` otherwise. + +## addListener syntax + +### Parameters + +- `listener` + + - : The function called when this event occurs. The function is passed this argument: + + - `group` + - : {{WebExtAPIRef("tabGroups.TabGroup")}}. Details of the moved tab group's state. + +## Examples + +Listen for and log tab group movement: + +```js +function tabGroupMoved(group) { + console.log( + `Tab group with ID ${group.id} was moved to window ${group.windowId}.`, + ); +} + +browser.tabGroups.onMoved.addListener(tabGroupMoved); +``` + +Locate a tab group moved to another window. + +```js +browser.tabGroups.onMoved.addListener(group => { + let tabs = await browser.tabs.query({ + groupId: group.id, + }); + console.log(`Moved tab group to ${tabs[0].index} in window ${group.windowId}`); +}); +``` + +{{WebExtExamples}} + +## Browser compatibility + +{{Compat}} diff --git a/files/en-us/mozilla/add-ons/webextensions/api/tabgroups/onremoved/index.md b/files/en-us/mozilla/add-ons/webextensions/api/tabgroups/onremoved/index.md new file mode 100644 index 000000000000000..f4784a1262f9494 --- /dev/null +++ b/files/en-us/mozilla/add-ons/webextensions/api/tabgroups/onremoved/index.md @@ -0,0 +1,60 @@ +--- +title: tabGroups.onRemoved +slug: Mozilla/Add-ons/WebExtensions/API/tabGroups/onRemoved +page-type: webextension-api-event +browser-compat: webextensions.api.tabGroups.onRemoved +--- + +{{AddonSidebar}} + +Fires when a tab group is removed. This occurs when a user closes a tab group or a tab group is closed automatically because another change means it no longer contained any tabs. + +## Syntax + +```js-nolint +browser.tabGroups.onRemoved.addListener(listener) +browser.tabGroups.onRemoved.removeListener(listener) +browser.tabGroups.onRemoved.hasListener(listener) +``` + +Events have three functions: + +- `addListener(listener)` + - : Adds a listener to this event. +- `removeListener(listener)` + - : Stops listening to this event. The `listener` argument is the listener to remove. +- `hasListener(listener)` + - : Checks whether `listener` is registered for this event. Returns `true` if it is listening, `false` otherwise. + +## addListener syntax + +### Parameters + +- `listener` + + - : The function called when this event occurs. The function is passed this argument: + + - `group` + - : {{WebExtAPIRef("tabGroups.TabGroup")}}. Details of the removed tab group's state. + - `removeInfo` + - : `object`. Information on why the tab group is closing. + - `isWindowClosing` + - : `boolean`. `true` if the tab group is removed because its window is closing. + +## Examples + +Listen for and log tab group removals: + +```js +function tabGroupRemoved(group) { + console.log(`Tab group with ID ${group.id} was removed.`); +} + +browser.tabGroups.onRemoved.addListener(tabGroupRemoved); +``` + +{{WebExtExamples}} + +## Browser compatibility + +{{Compat}} diff --git a/files/en-us/mozilla/add-ons/webextensions/api/tabgroups/onupdated/index.md b/files/en-us/mozilla/add-ons/webextensions/api/tabgroups/onupdated/index.md new file mode 100644 index 000000000000000..78ed16a1cf3cc7f --- /dev/null +++ b/files/en-us/mozilla/add-ons/webextensions/api/tabgroups/onupdated/index.md @@ -0,0 +1,60 @@ +--- +title: tabGroups.onUpdated +slug: Mozilla/Add-ons/WebExtensions/API/tabGroups/onUpdated +page-type: webextension-api-event +browser-compat: webextensions.api.tabGroups.onUpdated +--- + +{{AddonSidebar}} + +Fires when a tab group's state changes. + +This event does not fire when the group's membership changes or when a tab group is moved. Those updates are covered by {{WebExtAPIRef("tabs.onUpdated")}} and {{WebExtAPIRef("tabGroups.onMoved")}} respectively. + +To detect `windowId` changes, use {{WebExtAPIRef("tabGroups.onMoved")}} instead. + +## Syntax + +```js-nolint +browser.tabGroups.onUpdated.addListener(listener) +browser.tabGroups.onUpdated.removeListener(listener) +browser.tabGroups.onUpdated.hasListener(listener) +``` + +Events have three functions: + +- `addListener(listener)` + - : Adds a listener to this event. +- `removeListener(listener)` + - : Stops listening to this event. The `listener` argument is the listener to remove. +- `hasListener(listener)` + - : Checks whether `listener` is registered for this event. Returns `true` if it is listening, `false` otherwise. + +## addListener syntax + +### Parameters + +- `listener` + + - : The function called when this event occurs. The function is passed this argument: + + - `group` + - : {{WebExtAPIRef("tabGroups.TabGroup")}}. Details of the updated tab group's state. + +## Examples + +Listen for and log tab group updates: + +```js +function tabGroupUpdated(group) { + console.log(`Tab group with ID ${group.id} was updated.`, group); +} + +browser.tabGroups.onUpdated.addListener(tabGroupUpdated); +``` + +{{WebExtExamples}} + +## Browser compatibility + +{{Compat}} diff --git a/files/en-us/mozilla/add-ons/webextensions/api/tabgroups/query/index.md b/files/en-us/mozilla/add-ons/webextensions/api/tabgroups/query/index.md new file mode 100644 index 000000000000000..6982aa0af6db6a6 --- /dev/null +++ b/files/en-us/mozilla/add-ons/webextensions/api/tabgroups/query/index.md @@ -0,0 +1,43 @@ +--- +title: tabGroups.query +slug: Mozilla/Add-ons/WebExtensions/API/tabGroups/query +page-type: webextension-api-function +browser-compat: webextensions.api.tabGroups.query +--- + +{{AddonSidebar}} + +Return all tab groups or find groups with certain properties. + +## Syntax + +```js-nolint +let group = await browser.tabGroups.query( + queryInfo // object +); +``` + +### Parameters + +- `queryInfo` + - : An object containing details of the property values to be matched in returned tab groups. + - `collapsed` {{optional_inline}} + - : `boolean`. Whether the returned tab groups are collapsed or expanded in the tab strip. + - `color` {{optional_inline}} + - : {{WebExtAPIRef("tabGroups.Color")}}. The name of the color returned tab groups are using. + - `shared` {{optional_inline}} + - : `boolean`. Whether the returned tab groups are shared. + - `title` {{optional_inline}} + - : `string`. The name of the tab groups to return. + - `windowId` {{optional_inline}} + - : `integer`. The ID of the window the returned tab group are in. + +### Return value + +A [`Promise`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise) fulfilled with an array of {{WebExtAPIRef("tabGroups.TabGroup")}} objects. If the request fails, the promise is rejected with an error message. + +{{WebExtExamples("h2")}} + +## Browser compatibility + +{{Compat}} diff --git a/files/en-us/mozilla/add-ons/webextensions/api/tabgroups/tab_group_id_none/index.md b/files/en-us/mozilla/add-ons/webextensions/api/tabgroups/tab_group_id_none/index.md new file mode 100644 index 000000000000000..de3f0aae921ec1a --- /dev/null +++ b/files/en-us/mozilla/add-ons/webextensions/api/tabgroups/tab_group_id_none/index.md @@ -0,0 +1,27 @@ +--- +title: tabGroups.TAB_GROUP_ID_NONE +slug: Mozilla/Add-ons/WebExtensions/API/tabGroups/TAB_GROUP_ID_NONE +page-type: webextension-api-property +browser-compat: webextensions.api.tabGroups.TAB_GROUP_ID_NONE +--- + +{{AddonSidebar}} + +The tab group ID value returned when a tab isn't in a tab group. + +Its value is `-1`. + +This value can appear as `groupId` in these API functions: + +- {{WebExtAPIRef("tabs.group()")}} +- {{WebExtAPIRef("tabs.ungroup()")}} +- {{WebExtAPIRef("tabs.query()")}} +- {{WebExtAPIRef("tabs.Tab")}} + +The `tabGroups.TAB_GROUP_ID_NONE` constant is part of the `tabGroups` namespace, which is only available when the [`tabGroups` permission](/en-US/docs/Mozilla/Add-ons/WebExtensions/API/tabGroups#permissions) is granted. If your extension doesn't require the `tabGroups` permission, use `-1` instead of `tabGroups.TAB_GROUP_ID_NONE`. + +{{WebExtExamples("h2")}} + +## Browser compatibility + +{{Compat}} diff --git a/files/en-us/mozilla/add-ons/webextensions/api/tabgroups/tabgroup/index.md b/files/en-us/mozilla/add-ons/webextensions/api/tabgroups/tabgroup/index.md new file mode 100644 index 000000000000000..f5cbcfc643017e0 --- /dev/null +++ b/files/en-us/mozilla/add-ons/webextensions/api/tabgroups/tabgroup/index.md @@ -0,0 +1,31 @@ +--- +title: tabGroups.TabGroup +slug: Mozilla/Add-ons/WebExtensions/API/tabGroups/TabGroup +page-type: webextension-api-type +browser-compat: webextensions.api.tabGroups.TabGroup +--- + +{{AddonSidebar}} + +The state of a tab group. + +## Type + +Values of this type are strings. Possible values are: + +- `collapsed` + - : `boolean`. Whether the tab group is collapsed or expanded in the tab strip. +- `color` + - : {{WebExtAPIRef("tabGroups.Color")}}. The name of the user-selected color for the tab group's label and icons. +- `id` + - : `integer`. The unique ID of the tab group. Can't be {{WebExtAPIRef("tabGroups.TAB_GROUP_ID_NONE")}}. The ID of a closed tab group may be reused when a tab group is restored, but this isn't guaranteed by the API. To identify tab groups across browser restarts, look at other properties and the tabs within the tab groups. +- `title` + - : `string`. The user-defined name of the tab group. +- `windowId` + - : `integer`. The unique ID of the window the tab group is in. + +{{WebExtExamples("h2")}} + +## Browser compatibility + +{{Compat}} diff --git a/files/en-us/mozilla/add-ons/webextensions/api/tabgroups/update/index.md b/files/en-us/mozilla/add-ons/webextensions/api/tabgroups/update/index.md new file mode 100644 index 000000000000000..88f9b0fddf3f6a2 --- /dev/null +++ b/files/en-us/mozilla/add-ons/webextensions/api/tabgroups/update/index.md @@ -0,0 +1,44 @@ +--- +title: tabGroups.update +slug: Mozilla/Add-ons/WebExtensions/API/tabGroups/update +page-type: webextension-api-function +browser-compat: webextensions.api.tabGroups.update +--- + +{{AddonSidebar}} + +Modifies the state of a tab group. + +## Syntax + +```js-nolint +let updatedTabGroup = await browser.tabGroups.update( + groupId, // integer + updateProperties // object +); +``` + +### Parameters + +- `groupId` + + - : `integer` The ID of the tab group to update. + +- `updateProperties` + - : An object containing details of the properties to update for this tab group. Properties that aren't specified aren't modified. + - `collapsed` {{optional_inline}} + - : `boolean`. Whether the tab group is collapsed or expanded in the tab strip. + - `color` {{optional_inline}} + - : {{WebExtAPIRef("tabGroups.Color")}}. The name of the color to use for the tab group. + - `title` {{optional_inline}} + - : `string`. The name of the tab group. + +### Return value + +A [`Promise`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise) fulfilled with a {{WebExtAPIRef("tabGroups.TabGroup")}} object. If the request fails, the promise is rejected with an error message. + +{{WebExtExamples("h2")}} + +## Browser compatibility + +{{Compat}} diff --git a/files/en-us/mozilla/add-ons/webextensions/api/tabs/executescript/index.md b/files/en-us/mozilla/add-ons/webextensions/api/tabs/executescript/index.md index 973a6c6f73c1061..160541790265795 100644 --- a/files/en-us/mozilla/add-ons/webextensions/api/tabs/executescript/index.md +++ b/files/en-us/mozilla/add-ons/webextensions/api/tabs/executescript/index.md @@ -112,7 +112,7 @@ let foo = "my result"; foo; ``` -Here the results array will contain the string "`my result`" as an element. +Here the results array will contain the string `"my result"` as an element. The result values must be [structured cloneable](/en-US/docs/Web/API/Web_Workers_API/Structured_clone_algorithm) (see [Data cloning algorithm](/en-US/docs/Mozilla/Add-ons/WebExtensions/Chrome_incompatibilities#data_cloning_algorithm)). diff --git a/files/en-us/mozilla/add-ons/webextensions/api/tabs/getallinwindow/index.md b/files/en-us/mozilla/add-ons/webextensions/api/tabs/getallinwindow/index.md index 02eaed9c76202e0..e1a60fa1e0ac6e2 100644 --- a/files/en-us/mozilla/add-ons/webextensions/api/tabs/getallinwindow/index.md +++ b/files/en-us/mozilla/add-ons/webextensions/api/tabs/getallinwindow/index.md @@ -31,7 +31,7 @@ let getting = browser.tabs.getAllInWindow( ### Return value -A [`Promise`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise) that will be fulfilled with an `array` of `{{WebExtAPIRef('tabs.Tab')}}` objects, containing information about all the tabs in the window. If the window could not be found or some other error occurs, the promise will be rejected with an error message. +A [`Promise`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise) that will be fulfilled with an `array` of {{WebExtAPIRef('tabs.Tab')}} objects, containing information about all the tabs in the window. If the window could not be found or some other error occurs, the promise will be rejected with an error message. ## Browser compatibility diff --git a/files/en-us/mozilla/add-ons/webextensions/api/tabs/getcurrent/index.md b/files/en-us/mozilla/add-ons/webextensions/api/tabs/getcurrent/index.md index 1d75a4bda489d7d..d8ed6c04fa6a83e 100644 --- a/files/en-us/mozilla/add-ons/webextensions/api/tabs/getcurrent/index.md +++ b/files/en-us/mozilla/add-ons/webextensions/api/tabs/getcurrent/index.md @@ -10,7 +10,7 @@ browser-compat: webextensions.api.tabs.getCurrent Get a {{WebExtAPIRef("tabs.Tab")}} containing information about the tab that this script is running in. > [!NOTE] -> This function is only useful in contexts where there is a browser tab, such as an [options page](/en-US/docs/Mozilla/Add-ons/WebExtensions/Anatomy_of_a_WebExtension#options_pages). +> This function is only useful in contexts where there is a browser tab, such as an [options page](/en-US/docs/Mozilla/Add-ons/WebExtensions/Anatomy_of_a_WebExtension#sidebars_popups_and_options_pages). > > If you call it from a background script or a popup, it will return `undefined`. diff --git a/files/en-us/mozilla/add-ons/webextensions/api/tabs/group/index.md b/files/en-us/mozilla/add-ons/webextensions/api/tabs/group/index.md new file mode 100644 index 000000000000000..770b17f4c3ceccf --- /dev/null +++ b/files/en-us/mozilla/add-ons/webextensions/api/tabs/group/index.md @@ -0,0 +1,103 @@ +--- +title: tabs.group() +slug: Mozilla/Add-ons/WebExtensions/API/tabs/group +page-type: webextension-api-function +browser-compat: webextensions.api.tabs.group +--- + +{{AddonSidebar}} + +Adds one or more tabs to a group or, if no group is specified, adds the tabs to a new group. All tabs in a tab group must be adjacent, and tabs are moved if needed. Any pinned tabs are unpinned before grouping. + +If a call moves tabs out of tab groups and any of those tab groups become empty, the empty tab groups are removed. + +> [!NOTE] +> The `tabs.group()` method is not the only way to group tabs. A tab also joins a tab group when {{WebExtAPIRef("tabs.move")}} places it between tabs that are part of a tab group. + +For more information on tab groups, see {{WebExtAPIRef("tabGroups")}}. + +## Syntax + +```js-nolint +let grouping = browser.tabs.group( + options // object +) +``` + +### Parameters + +- `options` + + - : An object containing details about the tab grouping. + + - `createProperties` {{optional_inline}} + + - : `object`. Configuration details for a new group. Cannot be used if `groupId` is specified. + + - `windowId` {{optional_inline}} + - : `integer`. The window of the new group. Defaults to the [current window](/en-US/docs/Mozilla/Add-ons/WebExtensions/API/windows/getCurrent). + + - `groupId` {{optional_inline}} + - : `integer`. The ID of the group to add the tabs to. If not specified, a group is created. + - `tabIds` + - : `integer` or `array` of `integer`. The tab ID or list of tab IDs to add to the group. Must contain at least one tab ID. + +### Return value + +A [`Promise`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise) that is fulfilled with an integer containing the `groupId` of the tab group the tabs were added to. If the `groupId` is not found, any of the `tabIds` are invalid, the `windowId` is invalid, or some other error occurs, the promise is rejected with an error message. When a validation error occurs, the tabs are not modified. + +## Examples + +Create two tabs and put them in a new group, then create another tab and add it to the group. + +```js +// Create two tabs and put them in a new group. +const tab1 = await browser.tabs.create({}); +const tab2 = await browser.tabs.create({}); +const groupId = await browser.tabs.group({ + tabIds: [tab1.id, tab2.id], +}); + +// Create another tab and add it to the group. +const tab3 = await browser.tabs.create({}); +await browser.tabs.group({ + tabIds: tab3.id, + groupId, +}); +``` + +Create a tab and match its grouping to that of the current tab. + +```js +let [oldTab] = await browser.tabs.query({ + active: true, + lastFocusedWindow: true, +}); + +let newTab = await browser.tabs.create({ + url: "https://example.com/", + index: oldTab.index + 1, +}); +// Feature detection: tab grouping is a relatively new feature. +// All tabs are ungrouped if the API does not exist. +if (browser.tabs.group) { + if (oldTab.groupId !== -1) { + // oldTab is in a group, add newTab to the same group + await browser.tabs.group({ groupId: oldTab.groupId, tabIds: [newTab.id] }); + } else { + // oldTab isn't in a group + // Although a new tab positioned next to an ungrouped tab is + // already ungrouped, we call ungroup() in case this example is + // adopted for use with tabs that aren't adjacent. When oldTab + // is not in a tab group, the only way to ensure that newTab isn't + // in a tab group is by using ungroup(). + await browser.tabs.ungroup(newTab.id); + } +} +``` + +{{WebExtExamples}} + +## Browser compatibility + +{{Compat}} diff --git a/files/en-us/mozilla/add-ons/webextensions/api/tabs/index.md b/files/en-us/mozilla/add-ons/webextensions/api/tabs/index.md index 2c6e5a77d9c00d4..cdb599c642b2aeb 100644 --- a/files/en-us/mozilla/add-ons/webextensions/api/tabs/index.md +++ b/files/en-us/mozilla/add-ons/webextensions/api/tabs/index.md @@ -86,6 +86,8 @@ Many tab operations use a Tab `id`. Tab `id`s are guaranteed to be unique to a s - : Go forward to the next page, if one is available. - {{WebExtAPIRef("tabs.goBack()")}} - : Go back to the previous page, if one is available. +- {{WebExtAPIRef("tabs.group()")}} + - : Adds tabs to a tab group. - {{WebExtAPIRef("tabs.hide()")}} {{experimental_inline}} - : Hides one or more tabs. - {{WebExtAPIRef("tabs.highlight()")}} @@ -122,6 +124,8 @@ Many tab operations use a Tab `id`. Tab `id`s are guaranteed to be unique to a s - : Shows one or more tabs that have been {{WebExtAPIRef("tabs.hide()", "hidden")}}. - {{WebExtAPIRef("tabs.toggleReaderMode()")}} - : Toggles Reader mode for the specified tab. +- {{WebExtAPIRef("tabs.ungroup()")}} + - : Removes tabs from tab groups. - {{WebExtAPIRef("tabs.update()")}} - : Navigate the tab to a new URL, or modify other properties of the tab. - {{WebExtAPIRef("tabs.warmup()")}} diff --git a/files/en-us/mozilla/add-ons/webextensions/api/tabs/move/index.md b/files/en-us/mozilla/add-ons/webextensions/api/tabs/move/index.md index b737fe841b9bf91..b4a4938a09da57a 100644 --- a/files/en-us/mozilla/add-ons/webextensions/api/tabs/move/index.md +++ b/files/en-us/mozilla/add-ons/webextensions/api/tabs/move/index.md @@ -42,7 +42,7 @@ let moving = browser.tabs.move( ### Return value -A [`Promise`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise) that will be fulfilled with a `{{WebExtAPIRef('tabs.Tab')}}` object or an `array` of `{{WebExtAPIRef('tabs.Tab')}}` objects, containing details about the moved tabs. If no tabs were moved (for example, because you tried to move an unpinned tab before a pinned tab) this will be an empty array. If any error occurs, the promise will be rejected with an error message. +A [`Promise`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise) that will be fulfilled with a {{WebExtAPIRef('tabs.Tab')}} object or an `array` of {{WebExtAPIRef('tabs.Tab')}} objects, containing details about the moved tabs. If no tabs were moved (for example, because you tried to move an unpinned tab before a pinned tab) this will be an empty array. If any error occurs, the promise will be rejected with an error message. ## Examples diff --git a/files/en-us/mozilla/add-ons/webextensions/api/tabs/onupdated/index.md b/files/en-us/mozilla/add-ons/webextensions/api/tabs/onupdated/index.md index 3e042bfaa0f9073..cdd893343138678 100644 --- a/files/en-us/mozilla/add-ons/webextensions/api/tabs/onupdated/index.md +++ b/files/en-us/mozilla/add-ons/webextensions/api/tabs/onupdated/index.md @@ -63,6 +63,7 @@ Events have three functions: - "audible" - "discarded" - "favIconUrl" + - "groupId" - "hidden" - "isArticle" - "mutedInfo" @@ -96,6 +97,8 @@ Lists the changes to the state of the tab that is updated. To learn more about t - : `boolean`. Whether the tab is discarded. A discarded tab is one whose content has been unloaded from memory but is visible in the tab strip. Its content gets reloaded the next time it's activated. - `favIconUrl` {{optional_inline}} - : `string`. The tab's new favicon URL. Not included when a tab loses its favicon (navigating from a page with a favicon to a page without one). Check `favIconUrl` in [tab](#tab) instead. +- `groupId` {{optional_inline}} + - : `integer`. The ID of the group the tabs are in or `-1` ({{WebExtAPIRef("tabGroups.TAB_GROUP_ID_NONE")}}) for ungrouped tabs. - `hidden` {{optional_inline}} - : `boolean`. True if the tab is {{WebExtAPIRef("tabs.hide()", "hidden")}}. - `isArticle` {{optional_inline}} diff --git a/files/en-us/mozilla/add-ons/webextensions/api/tabs/query/index.md b/files/en-us/mozilla/add-ons/webextensions/api/tabs/query/index.md index fcd99d8d6aa78f7..8b92b099c3a83b8 100644 --- a/files/en-us/mozilla/add-ons/webextensions/api/tabs/query/index.md +++ b/files/en-us/mozilla/add-ons/webextensions/api/tabs/query/index.md @@ -9,8 +9,6 @@ browser-compat: webextensions.api.tabs.query Gets all tabs that have the specified properties, or all tabs if no properties are specified. -This is an asynchronous function that returns a [`Promise`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise). - ## Syntax ```js-nolint @@ -39,6 +37,8 @@ let querying = browser.tabs.query(queryInfo) - : `boolean`. Whether the tabs are in the current window. - `discarded` {{optional_inline}} - : `boolean`. Whether the tabs are discarded. A discarded tab is one whose content has been unloaded from memory, but is still visible in the tab strip. Its content gets reloaded the next time it's activated. + - `groupId` {{optional_inline}} + - : `integer`. The ID of the tab group the tabs are in or `-1` ({{WebExtAPIRef("tabGroups.TAB_GROUP_ID_NONE")}}) for ungrouped tabs. For more information on tab groups, see {{WebExtAPIRef("tabGroups")}}. - `hidden` {{optional_inline}} - : `boolean`. Whether the tabs are hidden. - `highlighted` {{optional_inline}} @@ -64,7 +64,7 @@ let querying = browser.tabs.query(queryInfo) ### Return value -A [`Promise`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise) that will be fulfilled with an `array` of `{{WebExtAPIRef('tabs.Tab')}}` objects, containing information about each matching tab. +A [`Promise`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise) that will be fulfilled with an `array` of {{WebExtAPIRef('tabs.Tab')}} objects, containing information about each matching tab. If any error occurs, the promise will be rejected with an error message. diff --git a/files/en-us/mozilla/add-ons/webextensions/api/tabs/tab/index.md b/files/en-us/mozilla/add-ons/webextensions/api/tabs/tab/index.md index 1aca74dfd22c9e3..e234d6bace683f2 100644 --- a/files/en-us/mozilla/add-ons/webextensions/api/tabs/tab/index.md +++ b/files/en-us/mozilla/add-ons/webextensions/api/tabs/tab/index.md @@ -31,13 +31,15 @@ Values of this type are objects. They contain the following properties: - : `boolean`. Whether the tab is discarded. A discarded tab is one whose content has been unloaded from memory, but is still visible in the tab strip. Its content gets reloaded the next time it's activated. - `favIconUrl` {{optional_inline}} - : `string`. The URL of the tab's favicon. Only present if the extension has the `"tabs"` [permission](/en-US/docs/Mozilla/Add-ons/WebExtensions/manifest.json/permissions) or [host permissions](/en-US/docs/Mozilla/Add-ons/WebExtensions/manifest.json/permissions#host_permissions). It may also be `undefined` if the page has no favicon, or an empty string if the tab is loading. +- `groupId` {{optional_inline}} + - : `integer`. The ID of the tab group the tab belongs to. Set to `-1` ({{WebExtAPIRef("tabGroups.TAB_GROUP_ID_NONE")}}) if the tab doesn't belong to a tab group. See {{WebExtAPIRef("tabs.group")}}. For more information on tab groups, see {{WebExtAPIRef("tabGroups")}}. - `height` {{optional_inline}} - : `integer`. The height of the tab in pixels. - `hidden` - : `boolean`. Whether the tab is hidden. - `highlighted` - - : `boolean`. Whether the tab is highlighted, i.e. part of the current tab selection. An active tab is always highlighted, but some browsers may allow additional tabs to be highlighted, for example by clicking them while holding <kbd>Ctrl</kbd>, <kbd>Shift</kbd> or <kbd>⌘ Command</kbd> keys. + - : `boolean`. Whether the tab is highlighted, i.e., part of the current tab selection. An active tab is always highlighted, but some browsers may allow additional tabs to be highlighted, for example by clicking them while holding <kbd>Ctrl</kbd>, <kbd>Shift</kbd> or <kbd>⌘ Command</kbd> keys. Firefox for Android doesn't support highlighting multiple tabs. diff --git a/files/en-us/mozilla/add-ons/webextensions/api/tabs/ungroup/index.md b/files/en-us/mozilla/add-ons/webextensions/api/tabs/ungroup/index.md new file mode 100644 index 000000000000000..fe48734e8403eb8 --- /dev/null +++ b/files/en-us/mozilla/add-ons/webextensions/api/tabs/ungroup/index.md @@ -0,0 +1,56 @@ +--- +title: tabs.ungroup() +slug: Mozilla/Add-ons/WebExtensions/API/tabs/ungroup +page-type: webextension-api-function +browser-compat: webextensions.api.tabs.ungroup +--- + +{{AddonSidebar}} + +Removes one or more tabs from their respective tab groups. If any groups become empty, they are deleted. + +All tabs in a tab group must be adjacent. If necessary, an ungrouped tab is moved before or after the tab group to maintain this requirement. + +> [!NOTE] +> The `tabs.ungroup()` method is not the only way to ungroup tabs. A tab is also ungrouped when it's moved by calling {{WebExtAPIRef("tabs.move")}} with an `index` that is outside a tab group. + +For more information on tab groups, see {{WebExtAPIRef("tabGroups")}}. + +## Syntax + +```js-nolint +let ungrouping = browser.tabs.ungroup( + tabIds // array +) +``` + +### Parameters + +- `tabIds` + - : `integer` or `array` of `integer`. The tab ID or list of tab IDs to remove from groups. + +### Return value + +A [`Promise`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise) that is resolved with no arguments. + +If any of the `tabIds` are invalid, the promise is rejected without modifying the tabs. + +## Examples + +Remove the current tab from its tab group, if any: + +```js +let tabs = await browser.tabs.query({ + active: true, + lastFocusedWindow: true, +}); + +await browser.tabs.ungroup([tabs[0].id]); +console.log("Current tab is ungrouped"); +``` + +{{WebExtExamples}} + +## Browser compatibility + +{{Compat}} diff --git a/files/en-us/mozilla/add-ons/webextensions/api/types/browsersetting/set/index.md b/files/en-us/mozilla/add-ons/webextensions/api/types/browsersetting/set/index.md index 7cf4a5bf90a5dad..1504a5fa5bd7aa0 100644 --- a/files/en-us/mozilla/add-ons/webextensions/api/types/browsersetting/set/index.md +++ b/files/en-us/mozilla/add-ons/webextensions/api/types/browsersetting/set/index.md @@ -20,7 +20,7 @@ This means that if extension X tries to change a setting: 3. Otherwise, if a lower-precedence extension Y has already changed the setting, then X succeeds in changing the setting, and now controls the setting. However, Y's change is remembered, and is stored in a queue in precedence order. If X subsequently clears its value, or if X is disabled or uninstalled, the first extension in the queue gets to make its change to the setting. 4. Otherwise, if a higher-precedence extension Z has already changed the setting, then X does not succeed in changing the setting, but its change is queued. If Z subsequently clears its value, or if Z is disabled or uninstalled, the first extension in the queue gets to make its change to the setting. -An extension can find out which of these scenarios applies by examining the "`levelOfControl`" property returned from a call to [`BrowserSetting.get()`](/en-US/docs/Mozilla/Add-ons/WebExtensions/API/types/BrowserSetting/get). +An extension can find out which of these scenarios applies by examining the `levelOfControl` property returned from a call to [`BrowserSetting.get()`](/en-US/docs/Mozilla/Add-ons/WebExtensions/API/types/BrowserSetting/get). The `BrowserSetting.set()` method returns a Promise that resolves to a boolean: if an attempt to change a setting actually results in the setting being changed (scenarios 2 and 3 above) the boolean is `true`: otherwise it is `false`. diff --git a/files/en-us/mozilla/add-ons/webextensions/api/types/index.md b/files/en-us/mozilla/add-ons/webextensions/api/types/index.md index 8d142389cd84073..1b4f48f39a540ad 100644 --- a/files/en-us/mozilla/add-ons/webextensions/api/types/index.md +++ b/files/en-us/mozilla/add-ons/webextensions/api/types/index.md @@ -2,6 +2,7 @@ title: types slug: Mozilla/Add-ons/WebExtensions/API/types page-type: webextension-api +browser-compat: webextensions.api.types --- {{AddonSidebar}} @@ -15,6 +16,8 @@ Defines the `BrowserSetting` type, which is used to represent a browser setting. ## Browser compatibility +{{Compat}} + {{WebExtExamples("h2")}} > [!NOTE] diff --git a/files/en-us/mozilla/add-ons/webextensions/api/userscripts/index.md b/files/en-us/mozilla/add-ons/webextensions/api/userscripts/index.md index f87a8fbcdb5bb15..d4724a54d3c241b 100644 --- a/files/en-us/mozilla/add-ons/webextensions/api/userscripts/index.md +++ b/files/en-us/mozilla/add-ons/webextensions/api/userscripts/index.md @@ -10,7 +10,7 @@ browser-compat: webextensions.api.userScripts Use this API to register user scripts, third-party scripts designed to manipulate webpages or provide new features. Registering a user script instructs the browser to attach the script to pages that match the URL patterns specified during registration. > [!NOTE] -> This is documentation for the new API version, available in Firefox for Manifest V3. See {{WebExtAPIRef("userScripts_legacy","userScripts (legacy)")}} for information on the API available for use in Firefox with Manifest V2. +> This is documentation for the new API version, available in Firefox for Manifest V3. See [`userScripts` (legacy)](/en-US/docs/Mozilla/Add-ons/WebExtensions/API/userScripts_legacy) for information on the API available for use in Firefox with Manifest V2. This API offers capabilities similar to {{WebExtAPIRef("scripting")}} but with features suited to handling third-party scripts. diff --git a/files/en-us/mozilla/add-ons/webextensions/api/userscripts_legacy/index.md b/files/en-us/mozilla/add-ons/webextensions/api/userscripts_legacy/index.md index 9f9bed232850087..751b3b44c7640e6 100644 --- a/files/en-us/mozilla/add-ons/webextensions/api/userscripts_legacy/index.md +++ b/files/en-us/mozilla/add-ons/webextensions/api/userscripts_legacy/index.md @@ -21,7 +21,7 @@ This API offers similar capabilities to {{WebExtAPIRef("contentScripts")}} but w > [!WARNING] > This API requires the presence of the [`user_scripts`](/en-US/docs/Mozilla/Add-ons/WebExtensions/manifest.json/user_scripts) key in the manifest.json, even if no API script is specified. For example. `user_scripts: {}`. -To use the API, call `{{WebExtAPIRef("userScripts_legacy.register","register()")}}` passing in an object defining the scripts to register. The method returns a Promise that is resolved with a `{{WebExtAPIRef("userScripts_legacy.RegisteredUserScript","RegisteredUserScript")}}` object. +To use the API, call {{WebExtAPIRef("userScripts_legacy.register","register()")}} passing in an object defining the scripts to register. The method returns a Promise that is resolved with a {{WebExtAPIRef("userScripts_legacy.RegisteredUserScript","RegisteredUserScript")}} object. > [!NOTE] > User scripts are unregistered when the related extension page (from which the user scripts were registered) is unloaded, so you should register a user script from an extension page that persists at least as long as you want the user scripts to stay registered. @@ -30,6 +30,8 @@ To use the API, call `{{WebExtAPIRef("userScripts_legacy.register","register()") - {{WebExtAPIRef("userScripts_legacy.RegisteredUserScript", "userScripts.RegisteredUserScript")}} - : The `object` returned by the {{WebExtAPIRef("userScripts_legacy.register","register()")}} method. It represents the registered user scripts and is used to deregister the user scripts. +- {{WebExtAPIRef("userScripts_legacy.UserScriptOptions", "userScripts.UserScriptOptions")}} + - : The `object` passed to the {{WebExtAPIRef("userScripts_legacy.register","register()")}} method. It represents the content scripts to register. ## Methods diff --git a/files/en-us/mozilla/add-ons/webextensions/api/userscripts_legacy/userscriptoptions/index.md b/files/en-us/mozilla/add-ons/webextensions/api/userscripts_legacy/userscriptoptions/index.md index 8a8fa9ac72e1783..fb4e029c351a809 100644 --- a/files/en-us/mozilla/add-ons/webextensions/api/userscripts_legacy/userscriptoptions/index.md +++ b/files/en-us/mozilla/add-ons/webextensions/api/userscripts_legacy/userscriptoptions/index.md @@ -9,12 +9,12 @@ page-type: webextension-api-type > [!WARNING] > This is documentation for the legacy `userScripts` API. It's available in Firefox for Manifest V2. For functionality to work with user scripts in Manifest V3 see the new {{WebExtAPIRef("userScripts")}} API. -The UserScriptOptions object represents the content scripts to register. It has similar syntax to the contentScript options supported by browser.contentScripts.register. The differences are: +The `UserScriptOptions` object represents the content scripts to register. It has similar syntax to the `contentScript` options supported by `browser.contentScripts.register`. The differences are: -- it does not support a CSS property (use browser.contentScripts.register to dynamically register/unregister stylesheets) -- It does support an optional scriptMetadata property (as a plain JSON object which contains some metadata properties associated to the registered userScripts) +- it does not support a CSS property (use `browser.contentScripts.register` to dynamically register/unregister stylesheets) +- It does support an optional `scriptMetadata` property (as a plain JSON object which contains some metadata properties associated to the registered `userScripts`) -The UserScriptOptions object has the following properties: +The `UserScriptOptions` object has the following properties: - `allFrames` {{optional_inline}} - : Same as `all_frames` in the [`content_scripts`](/en-US/docs/Mozilla/Add-ons/WebExtensions/manifest.json/content_scripts) key. @@ -33,6 +33,6 @@ The UserScriptOptions object has the following properties: - `runAt` {{optional_inline}} - : Same as `run_at` in the [`content_scripts`](/en-US/docs/Mozilla/Add-ons/WebExtensions/manifest.json/content_scripts) key. - `scriptMetadata` {{optional_inline}} - - : A user script metadata value + - : A user script metadata value. -It has similar syntax to the contentScript options supported by browser.contentScripts.register. +It has similar syntax to the `contentScript` options supported by `browser.contentScripts.register`. diff --git a/files/en-us/mozilla/add-ons/webextensions/api/userscripts_legacy/working_with_userscripts/index.md b/files/en-us/mozilla/add-ons/webextensions/api/userscripts_legacy/working_with_userscripts/index.md index d384e775e576f22..4f3fd26f972895c 100644 --- a/files/en-us/mozilla/add-ons/webextensions/api/userscripts_legacy/working_with_userscripts/index.md +++ b/files/en-us/mozilla/add-ons/webextensions/api/userscripts_legacy/working_with_userscripts/index.md @@ -108,4 +108,4 @@ Once the script has been registered, navigate to a page whose domain name ends i - {{WebExtAPIRef("userScripts_legacy","userScripts")}} - {{WebExtAPIRef("userScripts_legacy.register()", "userScripts.register()")}} -- {{WebExtAPIRef("userScripts_legacy.onBeforeScript")}} +- {{WebExtAPIRef("userScripts_legacy.onBeforeScript", "userScripts.onBeforeScript")}} diff --git a/files/en-us/mozilla/add-ons/webextensions/api/webnavigation/getallframes/index.md b/files/en-us/mozilla/add-ons/webextensions/api/webnavigation/getallframes/index.md index cce9a3fb7eab77b..a2cafb422bda6f6 100644 --- a/files/en-us/mozilla/add-ons/webextensions/api/webnavigation/getallframes/index.md +++ b/files/en-us/mozilla/add-ons/webextensions/api/webnavigation/getallframes/index.md @@ -33,7 +33,7 @@ let gettingFrames = browser.webNavigation.getAllFrames( A [`Promise`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise) that will be fulfilled with an array of objects, each of which has the following properties: - `errorOccurred` - - : `boolean`. True if the last navigation in this frame was interrupted by an error, i.e. the {{WebExtAPIRef("webNavigation.onErrorOccurred", "onErrorOccurred")}} event fired. + - : `boolean`. True if the last navigation in this frame was interrupted by an error, i.e., the {{WebExtAPIRef("webNavigation.onErrorOccurred", "onErrorOccurred")}} event fired. - `processId` {{optional_inline}} {{deprecated_inline}} - : `integer`. This value is not set in modern browsers. When it was set, it represented the ID of the process running the renderer for this tab. - `frameId` diff --git a/files/en-us/mozilla/add-ons/webextensions/api/webnavigation/getframe/index.md b/files/en-us/mozilla/add-ons/webextensions/api/webnavigation/getframe/index.md index 1a07228f52523fc..29606a1c68f3acf 100644 --- a/files/en-us/mozilla/add-ons/webextensions/api/webnavigation/getframe/index.md +++ b/files/en-us/mozilla/add-ons/webextensions/api/webnavigation/getframe/index.md @@ -7,7 +7,7 @@ browser-compat: webextensions.api.webNavigation.getFrame {{AddonSidebar}} -Retrieves information about a particular frame. A frame may be the top-level frame in a tab or a nested [`<iframe>`](/en-US/docs/Web/HTML/Element/iframe), and is uniquely identified by a tab ID and a frame ID. +Retrieves information about a particular frame. A frame may be the top-level frame in a tab or a nested [`<iframe>`](/en-US/docs/Web/HTML/Reference/Elements/iframe), and is uniquely identified by a tab ID and a frame ID. This is an asynchronous function that returns a [`Promise`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise). @@ -37,7 +37,7 @@ let gettingFrame = browser.webNavigation.getFrame( A [`Promise`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise) that will be fulfilled with an object containing the following properties: - `errorOccurred` - - : `boolean`. True if the last navigation in this frame was interrupted by an error, i.e. the {{WebExtAPIRef("webNavigation.onErrorOccurred", "onErrorOccurred")}} event fired. + - : `boolean`. True if the last navigation in this frame was interrupted by an error, i.e., the {{WebExtAPIRef("webNavigation.onErrorOccurred", "onErrorOccurred")}} event fired. - `url` - : `string`. The URL currently associated with this frame, if the frame identified by `frameId` existed at one point in the tab identified by `tabId`. The fact that a URL is associated with a given `frameId` does not imply that the corresponding frame still exists. - `parentFrameId` @@ -66,7 +66,7 @@ let gettingFrame = browser.webNavigation.getFrame({ }); // Edge specific - processId is required not optional, must be integer not null -//let gettingFrame = browser.webNavigation.getFrame({ tabId: 19, processId: 0, frameId: 1537 }); +// let gettingFrame = browser.webNavigation.getFrame({ tabId: 19, processId: 0, frameId: 1537 }); gettingFrame.then(onGot, onError); ``` diff --git a/files/en-us/mozilla/add-ons/webextensions/api/webnavigation/index.md b/files/en-us/mozilla/add-ons/webextensions/api/webnavigation/index.md index 0b7ac0e548b5f15..59d23545bf87aa6 100644 --- a/files/en-us/mozilla/add-ons/webextensions/api/webnavigation/index.md +++ b/files/en-us/mozilla/add-ons/webextensions/api/webnavigation/index.md @@ -17,19 +17,19 @@ Each event corresponds to a particular stage in the navigation. The sequence of - The primary flow is: - - `{{WebExtAPIRef("webNavigation.onBeforeNavigate", "onBeforeNavigate")}}` - - `{{WebExtAPIRef("webNavigation.onCommitted", "onCommitted")}}` - - `{{WebExtAPIRef("webNavigation.onDOMContentLoaded", "onDOMContentLoaded")}}` - - `{{WebExtAPIRef("webNavigation.onCompleted", "onCompleted")}}`. + - {{WebExtAPIRef("webNavigation.onBeforeNavigate", "onBeforeNavigate")}} + - {{WebExtAPIRef("webNavigation.onCommitted", "onCommitted")}} + - {{WebExtAPIRef("webNavigation.onDOMContentLoaded", "onDOMContentLoaded")}} + - {{WebExtAPIRef("webNavigation.onCompleted", "onCompleted")}}. - Additionally: - - `{{WebExtAPIRef("webNavigation.onCreatedNavigationTarget", "onCreatedNavigationTarget")}}` is fired before `onBeforeNavigate` if the browser needed to create a new tab or window for the navigation (for example, because the user opened a link in a new tab). + - {{WebExtAPIRef("webNavigation.onCreatedNavigationTarget", "onCreatedNavigationTarget")}} is fired before `onBeforeNavigate` if the browser needed to create a new tab or window for the navigation (for example, because the user opened a link in a new tab). - {{WebExtAPIRef("webNavigation.onHistoryStateUpdated", "onHistoryStateUpdated")}} is fired if a page uses the [history API](/en-US/docs/Web/API/History_API) to update the URL displayed in the browser's location bar. - {{WebExtAPIRef("webNavigation.onReferenceFragmentUpdated", "onReferenceFragmentUpdated")}} is fired if the [fragment identifier](/en-US/docs/Web/URI/Reference/Fragment) for a page is changed. - {{WebExtAPIRef("webNavigation.onErrorOccurred", "onErrorOccurred")}} can be fired at any point. -Each navigation is a URL transition in a particular browser frame. The browser frame is identified by a tab ID and a frame ID. The frame may be the top-level browsing context in the tab, or may be a nested browsing context implemented as an [iframe](/en-US/docs/Web/HTML/Element/iframe). +Each navigation is a URL transition in a particular browser frame. The browser frame is identified by a tab ID and a frame ID. The frame may be the top-level browsing context in the tab, or may be a nested browsing context implemented as an [iframe](/en-US/docs/Web/HTML/Reference/Elements/iframe). Each event's `addListener()` call accepts an optional filter parameter. The filter will specify one or more URL patterns, and the event will then only be fired for navigations in which the target URL matches one of the patterns. @@ -47,7 +47,7 @@ To use this API you need to have the "webNavigation" [permission](/en-US/docs/Mo ## Functions - {{WebExtAPIRef("webNavigation.getFrame()")}} - - : Retrieves information about a particular frame. A frame may be the top-level frame in a tab or a nested [iframe](/en-US/docs/Web/HTML/Element/iframe), and is uniquely identified by a tab ID and a frame ID. + - : Retrieves information about a particular frame. A frame may be the top-level frame in a tab or a nested [iframe](/en-US/docs/Web/HTML/Reference/Elements/iframe), and is uniquely identified by a tab ID and a frame ID. - {{WebExtAPIRef("webNavigation.getAllFrames()")}} - : Given a tab ID, retrieves information about all the frames it contains. @@ -70,7 +70,7 @@ To use this API you need to have the "webNavigation" [permission](/en-US/docs/Mo - {{WebExtAPIRef("webNavigation.onTabReplaced")}} - : Fired when the contents of the tab is replaced by a different (usually previously pre-rendered) tab. - {{WebExtAPIRef("webNavigation.onHistoryStateUpdated")}} - - : Fired when the page used the [history API (2011)](/en-US/docs/Web/API/History_API) to update the URL displayed in the browser's location bar. + - : Fired when the page used the [history API](/en-US/docs/Web/API/History_API) to update the URL displayed in the browser's location bar. ## Browser compatibility diff --git a/files/en-us/mozilla/add-ons/webextensions/api/webnavigation/onbeforenavigate/index.md b/files/en-us/mozilla/add-ons/webextensions/api/webnavigation/onbeforenavigate/index.md index eb6c8444ecd4460..2d8286377eb490f 100644 --- a/files/en-us/mozilla/add-ons/webextensions/api/webnavigation/onbeforenavigate/index.md +++ b/files/en-us/mozilla/add-ons/webextensions/api/webnavigation/onbeforenavigate/index.md @@ -38,7 +38,7 @@ Events have three functions: - : The function called when this event occurs. The function is passed this argument: - `details` - - : `object`. Details about the navigation event. See the [details](#details_2) section for more information. + - : `object`. Details about the navigation event. See the [details](#details) section for more information. - `filter` {{optional_inline}} - : `object`. An object containing a single property `url`, which is an `Array` of {{WebExtAPIRef("events.UrlFilter")}} objects. If you include this parameter, then the event fires only for transitions to URLs which match at least one `UrlFilter` in the array. If you omit this parameter, the event fires for all transitions. diff --git a/files/en-us/mozilla/add-ons/webextensions/api/webnavigation/oncommitted/index.md b/files/en-us/mozilla/add-ons/webextensions/api/webnavigation/oncommitted/index.md index 9218bdf7b50532c..af933cc7e35162a 100644 --- a/files/en-us/mozilla/add-ons/webextensions/api/webnavigation/oncommitted/index.md +++ b/files/en-us/mozilla/add-ons/webextensions/api/webnavigation/oncommitted/index.md @@ -38,7 +38,7 @@ Events have three functions: - : The function called when this event occurs. The function is passed this argument: - `details` - - : `object`. Details about the navigation event. See the [details](#details_2) section for more information. + - : `object`. Details about the navigation event. See the [details](#details) section for more information. - `filter` {{optional_inline}} - : `object`. An object containing a single property `url`, which is an `Array` of {{WebExtAPIRef("events.UrlFilter")}} objects. If you include this parameter, then the event fires only for transitions to URLs which match at least one `UrlFilter` in the array. If you omit this parameter, the event fires for all transitions. diff --git a/files/en-us/mozilla/add-ons/webextensions/api/webnavigation/oncompleted/index.md b/files/en-us/mozilla/add-ons/webextensions/api/webnavigation/oncompleted/index.md index fb6ca5345efc0cc..da4f92dc2199bf0 100644 --- a/files/en-us/mozilla/add-ons/webextensions/api/webnavigation/oncompleted/index.md +++ b/files/en-us/mozilla/add-ons/webextensions/api/webnavigation/oncompleted/index.md @@ -38,7 +38,7 @@ Events have three functions: - : The function called when this event occurs. The function is passed this argument: - `details` - - : `object`. Details about the navigation event. See the [details](#details_2) section for more information. + - : `object`. Details about the navigation event. See the [details](#details) section for more information. - `filter` {{optional_inline}} - : `object`. An object containing a single property `url`, which is an `Array` of {{WebExtAPIRef("events.UrlFilter")}} objects. If you include this parameter, then the event fires only for transitions to URLs which match at least one `UrlFilter` in the array. If you omit this parameter, the event fires for all transitions. diff --git a/files/en-us/mozilla/add-ons/webextensions/api/webnavigation/oncreatednavigationtarget/index.md b/files/en-us/mozilla/add-ons/webextensions/api/webnavigation/oncreatednavigationtarget/index.md index 737a347ba76a986..0cbfe21f6ecaffe 100644 --- a/files/en-us/mozilla/add-ons/webextensions/api/webnavigation/oncreatednavigationtarget/index.md +++ b/files/en-us/mozilla/add-ons/webextensions/api/webnavigation/oncreatednavigationtarget/index.md @@ -45,7 +45,7 @@ Events have three functions: - : The function called when this event occurs. The function is passed this argument: - `details` - - : `object`. Details about the navigation event. See the [details](#details_2) section for more information. + - : `object`. Details about the navigation event. See the [details](#details) section for more information. - `filter` {{optional_inline}} - : `object`. An object containing a single property `url`, which is an `Array` of {{WebExtAPIRef("events.UrlFilter")}} objects. If you include this parameter, then the event fires only for transitions to URLs which match at least one `UrlFilter` in the array. If you omit this parameter, the event fires for all transitions. Note that `filter` is not supported in Firefox. diff --git a/files/en-us/mozilla/add-ons/webextensions/api/webnavigation/ondomcontentloaded/index.md b/files/en-us/mozilla/add-ons/webextensions/api/webnavigation/ondomcontentloaded/index.md index 1653e809f0d4fda..b40fe34a66e6749 100644 --- a/files/en-us/mozilla/add-ons/webextensions/api/webnavigation/ondomcontentloaded/index.md +++ b/files/en-us/mozilla/add-ons/webextensions/api/webnavigation/ondomcontentloaded/index.md @@ -38,7 +38,7 @@ Events have three functions: - : The function called when this event occurs. The function is passed this argument: - `details` - - : `object`. Details about the navigation event. See the [details](#details_2) section for more information. + - : `object`. Details about the navigation event. See the [details](#details) section for more information. - `filter` {{optional_inline}} - : `object`. An object containing a single property `url`, which is an {{jsxref("Array")}} of {{WebExtAPIRef("events.UrlFilter")}} objects. If you include this parameter, then the event fires only for transitions to URLs which match at least one `UrlFilter` in the array. If you omit this parameter, the event fires for all transitions. diff --git a/files/en-us/mozilla/add-ons/webextensions/api/webnavigation/onerroroccurred/index.md b/files/en-us/mozilla/add-ons/webextensions/api/webnavigation/onerroroccurred/index.md index 7984a6a06c5e1c3..dca68dd45960ed5 100644 --- a/files/en-us/mozilla/add-ons/webextensions/api/webnavigation/onerroroccurred/index.md +++ b/files/en-us/mozilla/add-ons/webextensions/api/webnavigation/onerroroccurred/index.md @@ -22,12 +22,8 @@ browser.webNavigation.onErrorOccurred.hasListener(listener) Events have three functions: -- `addListener(listener)` - - `addListener(listener, filter)` - +- `addListener(listener)`, `addListener(listener, filter)` - : Adds a listener to this event. - - `removeListener(listener)` - : Stop listening to this event. The `listener` argument is the listener to remove. - `hasListener(listener)` diff --git a/files/en-us/mozilla/add-ons/webextensions/api/webnavigation/onhistorystateupdated/index.md b/files/en-us/mozilla/add-ons/webextensions/api/webnavigation/onhistorystateupdated/index.md index 6b0c96160414bd4..41d6f13066c5cf1 100644 --- a/files/en-us/mozilla/add-ons/webextensions/api/webnavigation/onhistorystateupdated/index.md +++ b/files/en-us/mozilla/add-ons/webextensions/api/webnavigation/onhistorystateupdated/index.md @@ -7,7 +7,7 @@ browser-compat: webextensions.api.webNavigation.onHistoryStateUpdated {{AddonSidebar}} -Fired when the page used the [>history API](/en-US/docs/Web/API/History_API/Working_with_the_History_API) to update the URL displayed in the browser's location bar. All future events for this frame will use the updated URL. +Fired when the page used the [history API](/en-US/docs/Web/API/History_API/Working_with_the_History_API) to update the URL displayed in the browser's location bar. All future events for this frame will use the updated URL. ## Syntax @@ -38,7 +38,7 @@ Events have three functions: - : The function called when this event occurs. The function is passed this argument: - `details` - - : `object`. Details about the navigation event. See the [details](#details_2) section for more information. + - : `object`. Details about the navigation event. See the [details](#details) section for more information. - `filter` {{optional_inline}} - : `object`. An object containing a single property `url`, which is an `Array` of {{WebExtAPIRef("events.UrlFilter")}} objects. If you include this parameter, then the event fires only for transitions to URLs which match at least one `UrlFilter` in the array. If you omit this parameter, the event fires for all transitions. @@ -58,7 +58,7 @@ Events have three functions: - `timeStamp` - : `number`. The time that the URL was changed by the history API, in [milliseconds since the epoch](https://en.wikipedia.org/wiki/Unix_time). - `transitionType` - - : `{{WebExtAPIRef("webNavigation.transitionType", "transitionType")}}`. The reason for the navigation: for example, `"link"` if the user clicked a link. + - : {{WebExtAPIRef("webNavigation.transitionType", "transitionType")}}. The reason for the navigation: for example, `"link"` if the user clicked a link. - `transitionQualifiers` - : `Array` of {{WebExtAPIRef("webNavigation.transitionQualifier", "transitionQualifier")}}. Extra information about the navigation: for example, whether there was a server or client redirect. diff --git a/files/en-us/mozilla/add-ons/webextensions/api/webnavigation/onreferencefragmentupdated/index.md b/files/en-us/mozilla/add-ons/webextensions/api/webnavigation/onreferencefragmentupdated/index.md index 54aa11ac4f413bd..bffaa2b49ae54b7 100644 --- a/files/en-us/mozilla/add-ons/webextensions/api/webnavigation/onreferencefragmentupdated/index.md +++ b/files/en-us/mozilla/add-ons/webextensions/api/webnavigation/onreferencefragmentupdated/index.md @@ -38,7 +38,7 @@ Events have three functions: - : The function called when this event occurs. The function is passed this argument: - `details` - - : `object`. Details about the navigation event. See the [details](#details_2) section for more information. + - : `object`. Details about the navigation event. See the [details](#details) section for more information. - `filter` {{optional_inline}} - : `object`. An object containing a single property `url`, which is an `Array` of {{WebExtAPIRef("events.UrlFilter")}} objects. If you include this parameter, then the event fires only for transitions to URLs which match at least one `UrlFilter` in the array. If you omit this parameter, the event fires for all transitions. @@ -58,7 +58,7 @@ Events have three functions: - `timeStamp` - : `number`. The time that the fragment identifier for the page was changed, in [milliseconds since the epoch](https://en.wikipedia.org/wiki/Unix_time). - `transitionType` - - : `{{WebExtAPIRef("webNavigation.transitionType", "transitionType")}}`. The reason for the navigation: for example, `"link"` if the user clicked a link. + - : {{WebExtAPIRef("webNavigation.transitionType", "transitionType")}}. The reason for the navigation: for example, `"link"` if the user clicked a link. - `transitionQualifiers` - : `Array` of {{WebExtAPIRef("webNavigation.transitionQualifier", "transitionQualifier")}}. Extra information about the navigation: for example, whether there was a server or client redirect. diff --git a/files/en-us/mozilla/add-ons/webextensions/api/webnavigation/ontabreplaced/index.md b/files/en-us/mozilla/add-ons/webextensions/api/webnavigation/ontabreplaced/index.md index bb3b1494411883c..852b0747968a237 100644 --- a/files/en-us/mozilla/add-ons/webextensions/api/webnavigation/ontabreplaced/index.md +++ b/files/en-us/mozilla/add-ons/webextensions/api/webnavigation/ontabreplaced/index.md @@ -38,7 +38,7 @@ Events have three functions: - : The function called when this event occurs. The function is passed this argument: - `details` - - : `object`. See the [details](#details_2) section for more information. + - : `object`. See the [details](#details) section for more information. ## Additional objects diff --git a/files/en-us/mozilla/add-ons/webextensions/api/webnavigation/transitionqualifier/index.md b/files/en-us/mozilla/add-ons/webextensions/api/webnavigation/transitionqualifier/index.md index 99d42afbe61d529..e59600e6dc39e10 100644 --- a/files/en-us/mozilla/add-ons/webextensions/api/webnavigation/transitionqualifier/index.md +++ b/files/en-us/mozilla/add-ons/webextensions/api/webnavigation/transitionqualifier/index.md @@ -14,7 +14,7 @@ Extra information about a transition. Note that many values here are not current Values of this type are strings. Possible values are: - "client_redirect" - - : Redirect(s) caused by JavaScript running in the page or a "refresh" pragma in the page's [meta](/en-US/docs/Web/HTML/Element/meta) tag. + - : Redirect(s) caused by JavaScript running in the page or a "refresh" pragma in the page's [meta](/en-US/docs/Web/HTML/Reference/Elements/meta) tag. - "server_redirect" - : Redirect(s) caused by a [3XX HTTP status code](https://en.wikipedia.org/wiki/List_of_HTTP_status_codes#3xx_Redirection) sent from the server. - "forward_back" diff --git a/files/en-us/mozilla/add-ons/webextensions/api/webrequest/blockingresponse/index.md b/files/en-us/mozilla/add-ons/webextensions/api/webrequest/blockingresponse/index.md index b1cc0df886119c1..711e9eae54b4d0f 100644 --- a/files/en-us/mozilla/add-ons/webextensions/api/webrequest/blockingresponse/index.md +++ b/files/en-us/mozilla/add-ons/webextensions/api/webrequest/blockingresponse/index.md @@ -34,7 +34,7 @@ Values of this type are objects. They contain the following properties: Redirections to non-HTTP schemes such as `data:` are allowed. Redirects use the same request method as the original request unless initiated from `onHeadersReceived` stage, in which case the redirect uses the GET method. - If an extension wants to redirect a public (e.g. HTTPS) URL to an [extension page](/en-US/docs/Mozilla/Add-ons/WebExtensions/user_interface/Extension_pages), the extension's manifest.json file must contain a [web_accessible_resources](/en-US/docs/Mozilla/Add-ons/WebExtensions/manifest.json/web_accessible_resources) key that lists the URL for the extension page. + If an extension wants to redirect a public (e.g., HTTPS) URL to an [extension page](/en-US/docs/Mozilla/Add-ons/WebExtensions/user_interface/Extension_pages), the extension's manifest.json file must contain a [web_accessible_resources](/en-US/docs/Mozilla/Add-ons/WebExtensions/manifest.json/web_accessible_resources) key that lists the URL for the extension page. - `requestHeaders` {{optional_inline}} - : {{WebExtAPIRef('webRequest.HttpHeaders')}}. This is an {{WebExtAPIRef('webRequest.HttpHeaders', "HttpHeaders")}} object, an array in which each object represents a header. If set, the request is made with these headers rather than the original headers. You can only set this property in {{WebExtAPIRef("webRequest.onBeforeSendHeaders", "onBeforeSendHeaders")}}. diff --git a/files/en-us/mozilla/add-ons/webextensions/api/webrequest/certificateinfo/index.md b/files/en-us/mozilla/add-ons/webextensions/api/webrequest/certificateinfo/index.md index 3ef9e8c53424cab..e5529b7c99bf8ba 100644 --- a/files/en-us/mozilla/add-ons/webextensions/api/webrequest/certificateinfo/index.md +++ b/files/en-us/mozilla/add-ons/webextensions/api/webrequest/certificateinfo/index.md @@ -28,7 +28,7 @@ Values of this type are objects. They contain the following properties: - : `Boolean`. `true` if the certificate is one of the trust roots installed in the browser, `false` otherwise. - `issuer` - - : `String`. Name of the organization that issued this certificate, represented as a Distinguished Name and formatted as a comma-separated list of Relative Distinguished Names, each of the form "type=value". + - : `String`. The Distinguished Name of the entity that issued the certificate, formatted as a comma-separated list of Relative Distinguished Names, each of the form "type=value". For example: "CN=DigiCert SHA2 Secure Server CA,O=DigiCert Inc,C=US". @@ -38,7 +38,7 @@ Values of this type are objects. They contain the following properties: - : `String`. The certificate's [serial number](https://datatracker.ietf.org/doc/html/rfc5280#section-4.1.2.2). - `subject` - - : `String`. Name of the organization that issued this certificate, represented as a Distinguished Name and formatted as a comma-separated list of Relative Distinguished Names, each of the form "type=value". + - : `String`. The Distinguished Name of the entity to which the certificate was issued, formatted as a comma-separated list of Relative Distinguished Names, each of the form "type=value". For example: "CN=\*.cdn.mozilla.net,O=Mozilla Corporation,L=Mountain View,ST=California,C=US". diff --git a/files/en-us/mozilla/add-ons/webextensions/api/webrequest/index.md b/files/en-us/mozilla/add-ons/webextensions/api/webrequest/index.md index a30b742c8dd7c9e..ed98c79669e966c 100644 --- a/files/en-us/mozilla/add-ons/webextensions/api/webrequest/index.md +++ b/files/en-us/mozilla/add-ons/webextensions/api/webrequest/index.md @@ -15,7 +15,7 @@ Each event is fired at a particular stage of the request. The sequence of events However, not all of these events might be observed by an extension. For example, `onBeforeRedirect` might not be followed by `onBeforeRequest` when the redirect target doesn't match the event `filter.urls`. This can be because the URLs in the filter are narrowly defined, or the redirect target can't be observed by an extension, such as when it redirects to a `data:` URL. -{{WebExtAPIRef("webRequest.onErrorOccurred", "onErrorOccurred")}} can fire at any time during the request. Also, note that sometimes the sequence of events may differ from this. For example, in Firefox, on an [HSTS](/en-US/docs/Web/HTTP/Headers/Strict-Transport-Security) upgrade, the `onBeforeRedirect` event is triggered immediately after `onBeforeRequest`. `onErrorOccurred` is also fired if [Firefox Tracking Protection](https://support.mozilla.org/en-US/kb/enhanced-tracking-protection-firefox-desktop) blocks a request. +{{WebExtAPIRef("webRequest.onErrorOccurred", "onErrorOccurred")}} can fire at any time during the request. Also, note that sometimes the sequence of events may differ from this. For example, in Firefox, on an [HSTS](/en-US/docs/Web/HTTP/Reference/Headers/Strict-Transport-Security) upgrade, the `onBeforeRedirect` event is triggered immediately after `onBeforeRequest`. `onErrorOccurred` is also fired if [Firefox Tracking Protection](https://support.mozilla.org/en-US/kb/enhanced-tracking-protection-firefox-desktop) blocks a request. All events – _except_ `onErrorOccurred` – can take three arguments to `addListener()`: @@ -120,7 +120,7 @@ To do this, you must have the `"webRequestBlocking"` API permission as well as t - {{WebExtAPIRef("webRequest.onBeforeSendHeaders")}} - : Fired before sending any HTTP data, but after HTTP headers are available. This is a good place to listen if you want to modify HTTP request headers. - {{WebExtAPIRef("webRequest.onSendHeaders")}} - - : Fired just before sending headers. If your add-on or some other add-on modified headers in `{{WebExtAPIRef("webRequest.onBeforeSendHeaders", "onBeforeSendHeaders")}}`, you'll see the modified version here. + - : Fired just before sending headers. If your add-on or some other add-on modified headers in {{WebExtAPIRef("webRequest.onBeforeSendHeaders", "onBeforeSendHeaders")}}, you'll see the modified version here. - {{WebExtAPIRef("webRequest.onHeadersReceived")}} - : Fired when the HTTP response headers associated with a request have been received. You can use this event to modify HTTP response headers. - {{WebExtAPIRef("webRequest.onAuthRequired")}} diff --git a/files/en-us/mozilla/add-ons/webextensions/api/webrequest/max_handler_behavior_changed_calls_per_10_minutes/index.md b/files/en-us/mozilla/add-ons/webextensions/api/webrequest/max_handler_behavior_changed_calls_per_10_minutes/index.md index 1044c6457c2c4fd..cc12d1d0def99c9 100644 --- a/files/en-us/mozilla/add-ons/webextensions/api/webrequest/max_handler_behavior_changed_calls_per_10_minutes/index.md +++ b/files/en-us/mozilla/add-ons/webextensions/api/webrequest/max_handler_behavior_changed_calls_per_10_minutes/index.md @@ -7,9 +7,9 @@ browser-compat: webextensions.api.webRequest.MAX_HANDLER_BEHAVIOR_CHANGED_CALLS_ {{AddonSidebar}} -The maximum number of times that `{{WebExtAPIRef("webRequest.handlerBehaviorChanged", "handlerBehaviorChanged()")}}` can be called in a 10 minute period. +The maximum number of times that {{WebExtAPIRef("webRequest.handlerBehaviorChanged", "handlerBehaviorChanged()")}} can be called in a 10 minute period. -This property is read-only. +This property is read-only and has a value of `20`. ## Browser compatibility diff --git a/files/en-us/mozilla/add-ons/webextensions/api/webrequest/onauthrequired/index.md b/files/en-us/mozilla/add-ons/webextensions/api/webrequest/onauthrequired/index.md index d5513ac93d82da7..590decc01f9ed85 100644 --- a/files/en-us/mozilla/add-ons/webextensions/api/webrequest/onauthrequired/index.md +++ b/files/en-us/mozilla/add-ons/webextensions/api/webrequest/onauthrequired/index.md @@ -33,7 +33,7 @@ The listener can respond in one of four ways: - in addListener, pass `"asyncBlocking"` in Chrome and Firefox or `"blocking"` in Firefox in the `extraInfoSpec` parameter - If `"blocking"` is provided, the extension can return a `webRequest.BlockingResponse` object or a Promise that resolves to a `webRequest.BlockingResponse` object - - If `"asyncBlocking"` is provided, the event listener function receives a `asyncCallback` function as its second parameter. `asyncCallback`can be called asynchronously and takes a`webRequest.BlockingResponse` object as its only parameter + - If `"asyncBlocking"` is provided, the event listener function receives a `asyncCallback` function as its second parameter. `asyncCallback` can be called asynchronously and takes a `webRequest.BlockingResponse` object as its only parameter > [!NOTE] > Chrome does not support a Promise as a return value ([Chromium issue 1510405](https://crbug.com/1510405)). For alternatives, see [the return value of the `listener`](#listener). @@ -84,7 +84,7 @@ Events have three functions: - : The function called when this event occurs. The function is passed these arguments: - `details` - - : `object`. Details about the request. See the [details](#details_2) section for more information. + - : `object`. Details about the request. See the [details](#details) section for more information. - `asyncCallback` {{optional_inline}} - : A function to call, at most once, to asynchronously modify the request object. @@ -158,7 +158,7 @@ Events have three functions: - `proxyDNS` - : `boolean`. True if the proxy performs domain name resolution based on the hostname supplied, meaning that the client should not do its own DNS lookup. - `failoverTimeout` - - : `integer`. Failover timeout in seconds. If the connection fails to connect the proxy server after this number of seconds, the next proxy server in the array returned from [FindProxyForURL()](</en-US/docs/Mozilla/Add-ons/WebExtensions/API/proxy#findproxyforurl()_return_value>) is used. + - : `integer`. Failover timeout in seconds. If the connection fails to connect the proxy server after this number of seconds, the next proxy server in the array returned from [FindProxyForURL()](/en-US/docs/Web/HTTP/Guides/Proxy_servers_and_tunneling/Proxy_Auto-Configuration_PAC_file) is used. - `realm` {{optional_inline}} - : `string`. The authentication [realm](https://datatracker.ietf.org/doc/html/rfc1945#section-11) provided by the server, if there is one. @@ -167,7 +167,7 @@ Events have three functions: - `responseHeaders` {{optional_inline}} - : {{WebExtAPIRef('webRequest.HttpHeaders')}}. The HTTP response headers received with this response. - `scheme` - - : `string`. The authentication scheme: `"basic"` or `"digest`". + - : `string`. The authentication scheme: `"basic"` or `"digest"`. - `statusCode` - : `integer`. Standard HTTP status code returned by the server. - `statusLine` @@ -187,9 +187,9 @@ Events have three functions: - : `object`. The type of tracking associated with the request, if the request is classified by [Firefox Tracking Protection](https://support.mozilla.org/en-US/kb/enhanced-tracking-protection-firefox-desktop). This is an object with these properties: - `firstParty` - - : `array` of `strings`. Classification flags for the request's first party. + - : `array` of `string`. Classification flags for the request's first party. - `thirdParty` - - : `array` of `strings`. Classification flags for the request or its window hierarchy's third parties. + - : `array` of `string`. Classification flags for the request or its window hierarchy's third parties. The classification flags include: @@ -304,13 +304,12 @@ function provideCredentialsAsync(requestDetails) { if (pendingRequests.includes(requestDetails.requestId)) { console.log(`bad credentials for: ${requestDetails.requestId}`); return { cancel: true }; - } else { - pendingRequests.push(requestDetails.requestId); - console.log(`providing credentials for: ${requestDetails.requestId}`); - // we can return a promise that will be resolved - // with the stored credentials - return browser.storage.local.get(null); } + pendingRequests.push(requestDetails.requestId); + console.log(`providing credentials for: ${requestDetails.requestId}`); + // we can return a promise that will be resolved + // with the stored credentials + return browser.storage.local.get(null); } browser.webRequest.onAuthRequired.addListener( diff --git a/files/en-us/mozilla/add-ons/webextensions/api/webrequest/onbeforeredirect/index.md b/files/en-us/mozilla/add-ons/webextensions/api/webrequest/onbeforeredirect/index.md index 303ba6e5aba4b11..1bdfc1f6278f74e 100644 --- a/files/en-us/mozilla/add-ons/webextensions/api/webrequest/onbeforeredirect/index.md +++ b/files/en-us/mozilla/add-ons/webextensions/api/webrequest/onbeforeredirect/index.md @@ -41,7 +41,7 @@ Events have three functions: - : The function called when this event occurs. The function is passed this argument: - `details` - - : `object`. Details about the request. See the [details](#details_2) section for more information. + - : `object`. Details about the request. See the [details](#details) section for more information. - `filter` - : {{WebExtAPIRef('webRequest.RequestFilter')}}. A filter that restricts the events that is sent to this listener. @@ -128,9 +128,9 @@ Events have three functions: - : `object`. The type of tracking associated with the request, if the request is classified by [Firefox Tracking Protection](https://support.mozilla.org/en-US/kb/enhanced-tracking-protection-firefox-desktop). This is an object with these properties: - `firstParty` - - : `array` of `strings`. Classification flags for the request's first party. + - : `array` of `string`. Classification flags for the request's first party. - `thirdParty` - - : `array` of `strings`. Classification flags for the request or its window hierarchy's third parties. + - : `array` of `string`. Classification flags for the request or its window hierarchy's third parties. The classification flags include: diff --git a/files/en-us/mozilla/add-ons/webextensions/api/webrequest/onbeforerequest/index.md b/files/en-us/mozilla/add-ons/webextensions/api/webrequest/onbeforerequest/index.md index cf1ffd1df0b3f07..ab50845533a8bd0 100644 --- a/files/en-us/mozilla/add-ons/webextensions/api/webrequest/onbeforerequest/index.md +++ b/files/en-us/mozilla/add-ons/webextensions/api/webrequest/onbeforerequest/index.md @@ -14,7 +14,7 @@ To cancel or redirect the request, first include `"blocking"` in the `extraInfoS - to cancel the request, include a property `cancel` with the value `true`. - to redirect the request, include a property `redirectUrl` with the value set to the URL to which you want to redirect. -If an extension wants to redirect a public (e.g. HTTPS) URL to an [extension page](/en-US/docs/Mozilla/Add-ons/WebExtensions/user_interface/Extension_pages), the extension's manifest.json file must contain a [web_accessible_resources](/en-US/docs/Mozilla/Add-ons/WebExtensions/manifest.json/web_accessible_resources) key that lists the URL for the extension page. +If an extension wants to redirect a public (e.g., HTTPS) URL to an [extension page](/en-US/docs/Mozilla/Add-ons/WebExtensions/user_interface/Extension_pages), the extension's manifest.json file must contain a [web_accessible_resources](/en-US/docs/Mozilla/Add-ons/WebExtensions/manifest.json/web_accessible_resources) key that lists the URL for the extension page. When multiple blocking handlers modify a request, only one set of modifications take effect. Redirects and cancellations have the same precedence. So if you canceled a request, you might see another request with the same `requestId` again if another blocking handler redirected the request. @@ -52,7 +52,7 @@ Events have three functions: - : The function called when this event occurs. The function is passed this argument: - `details` - - : `object`. Details about the request. See the [details](#details_2) section for more information. + - : `object`. Details about the request. See the [details](#details) section for more information. Returns: {{WebExtAPIRef('webRequest.BlockingResponse')}}. If `"blocking"` is specified in the `extraInfoSpec` parameter, the event listener should return a `BlockingResponse` object, and can set either its `cancel` or its `redirectUrl` properties. From Firefox 52 onwards, instead of returning `BlockingResponse`, the listener can return a [`Promise`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise) which is resolved with a `BlockingResponse`. This enables the listener to process the request asynchronously. @@ -135,7 +135,7 @@ Events have three functions: It is a dictionary in which each key contains the list of all values for that key. For example: `{'key': ['value1', 'value2']}`. If the data is of another media type, or if it is malformed, the object is not present. - `raw` {{optional_inline}} - - : `array` of `{{WebExtAPIRef('webRequest.UploadData')}}`. If the request method is PUT or POST, and the body is not already parsed in `formData`, then this array contains the unparsed request body elements. + - : `array` of {{WebExtAPIRef('webRequest.UploadData')}}. If the request method is PUT or POST, and the body is not already parsed in `formData`, then this array contains the unparsed request body elements. - `requestId` - : `string`. The ID of the request. Request IDs are unique within a browser session, so you can use them to relate different events associated with the same request. @@ -154,9 +154,9 @@ Events have three functions: - : `object`. The type of tracking associated with the request, if the request is classified by [Firefox Tracking Protection](https://support.mozilla.org/en-US/kb/enhanced-tracking-protection-firefox-desktop). This is an object with these properties: - `firstParty` - - : `array` of `strings`. Classification flags for the request's first party. + - : `array` of `string`. Classification flags for the request's first party. - `thirdParty` - - : `array` of `strings`. Classification flags for the request or its window hierarchy's third parties. + - : `array` of `string`. Classification flags for the request or its window hierarchy's third parties. The classification flags include: diff --git a/files/en-us/mozilla/add-ons/webextensions/api/webrequest/onbeforesendheaders/index.md b/files/en-us/mozilla/add-ons/webextensions/api/webrequest/onbeforesendheaders/index.md index 031a5d5a34aa357..1674aa090e23033 100644 --- a/files/en-us/mozilla/add-ons/webextensions/api/webrequest/onbeforesendheaders/index.md +++ b/files/en-us/mozilla/add-ons/webextensions/api/webrequest/onbeforesendheaders/index.md @@ -63,7 +63,7 @@ Events have three functions: - : The function called when this event occurs. The function is passed this argument: - `details` - - : `object`. Details of the request. This includes request headers if you have included `"requestHeaders"` in `extraInfoSpec`. See the [details](#details_2) section for more information. + - : `object`. Details of the request. This includes request headers if you have included `"requestHeaders"` in `extraInfoSpec`. See the [details](#details) section for more information. Returns: {{WebExtAPIRef('webRequest.BlockingResponse')}}. If `"blocking"` is specified in the `extraInfoSpec` parameter, the event listener should return a `BlockingResponse` object, and can set its `requestHeaders` property. @@ -149,9 +149,9 @@ Events have three functions: - : `object`. The type of tracking associated with the request, if the request is classified by [Firefox Tracking Protection](https://support.mozilla.org/en-US/kb/enhanced-tracking-protection-firefox-desktop). This is an object with these properties: - `firstParty` - - : `array` of `strings`. Classification flags for the request's first party. + - : `array` of `string`. Classification flags for the request's first party. - `thirdParty` - - : `array` of `strings`. Classification flags for the request or its window hierarchy's third parties. + - : `array` of `string`. Classification flags for the request or its window hierarchy's third parties. The classification flags include: diff --git a/files/en-us/mozilla/add-ons/webextensions/api/webrequest/oncompleted/index.md b/files/en-us/mozilla/add-ons/webextensions/api/webrequest/oncompleted/index.md index 3da16623e3eb433..6c79fb07bf6d091 100644 --- a/files/en-us/mozilla/add-ons/webextensions/api/webrequest/oncompleted/index.md +++ b/files/en-us/mozilla/add-ons/webextensions/api/webrequest/oncompleted/index.md @@ -41,7 +41,7 @@ Events have three functions: - : The function called when this event occurs. The function is passed this argument: - `details` - - : `object`. Details about the request. See the [details](#details_2) section for more information. + - : `object`. Details about the request. See the [details](#details) section for more information. - `filter` - : {{WebExtAPIRef('webRequest.RequestFilter')}}. A filter that restricts the events that is sent to this listener. @@ -126,9 +126,9 @@ Events have three functions: - : `object`. The type of tracking associated with the request, if the request is classified by [Firefox Tracking Protection](https://support.mozilla.org/en-US/kb/enhanced-tracking-protection-firefox-desktop). This is an object with these properties: - `firstParty` - - : `array` of `strings`. Classification flags for the request's first party. + - : `array` of `string`. Classification flags for the request's first party. - `thirdParty` - - : `array` of `strings`. Classification flags for the request or its window hierarchy's third parties. + - : `array` of `string`. Classification flags for the request or its window hierarchy's third parties. The classification flags include: diff --git a/files/en-us/mozilla/add-ons/webextensions/api/webrequest/onerroroccurred/index.md b/files/en-us/mozilla/add-ons/webextensions/api/webrequest/onerroroccurred/index.md index 2e4cfc3439d70bc..eb6e856f788398b 100644 --- a/files/en-us/mozilla/add-ons/webextensions/api/webrequest/onerroroccurred/index.md +++ b/files/en-us/mozilla/add-ons/webextensions/api/webrequest/onerroroccurred/index.md @@ -44,7 +44,7 @@ Events have three functions: - : The function called when this event occurs. The function is passed this argument: - `details` - - : `object`. Details about the request. See the [details](#details_2) section for more information. + - : `object`. Details about the request. See the [details](#details) section for more information. - `filter` - : {{WebExtAPIRef('webRequest.RequestFilter')}}. A filter that restricts the events that is sent to this listener. @@ -120,9 +120,9 @@ Events have three functions: - : `object`. The type of tracking associated with the request, if the request is classified by [Firefox Tracking Protection](https://support.mozilla.org/en-US/kb/enhanced-tracking-protection-firefox-desktop). This is an object with these properties: - `firstParty` - - : `array` of `strings`. Classification flags for the request's first party. + - : `array` of `string`. Classification flags for the request's first party. - `thirdParty` - - : `array` of `strings`. Classification flags for the request or its window hierarchy's third parties. + - : `array` of `string`. Classification flags for the request or its window hierarchy's third parties. The classification flags include: diff --git a/files/en-us/mozilla/add-ons/webextensions/api/webrequest/onheadersreceived/index.md b/files/en-us/mozilla/add-ons/webextensions/api/webrequest/onheadersreceived/index.md index e025eaff3182ffd..10fcea8f7d92b6c 100644 --- a/files/en-us/mozilla/add-ons/webextensions/api/webrequest/onheadersreceived/index.md +++ b/files/en-us/mozilla/add-ons/webextensions/api/webrequest/onheadersreceived/index.md @@ -49,7 +49,7 @@ Events have three functions: - : The function called when this event occurs. The function is passed this argument: - `details` - - : [`object`](#details_2). Details of the request. This will include response headers if you have included `"responseHeaders"` in `extraInfoSpec`. + - : [`object`](#details). Details of the request. This will include response headers if you have included `"responseHeaders"` in `extraInfoSpec`. Returns: {{WebExtAPIRef('webRequest.BlockingResponse')}}. If `"blocking"` is specified in the `extraInfoSpec` parameter, the event listener will return a `BlockingResponse` object, and can set its `responseHeaders` property. In Firefox, the return value can be a [`Promise`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise) that resolves to a `BlockingResponse`. @@ -146,9 +146,9 @@ Events have three functions: - : `object`. The type of tracking associated with the request, if the request is classified by [Firefox Tracking Protection](https://support.mozilla.org/en-US/kb/enhanced-tracking-protection-firefox-desktop). This is an object with these properties: - `firstParty` - - : `array` of `strings`. Classification flags for the request's first party. + - : `array` of `string`. Classification flags for the request's first party. - `thirdParty` - - : `array` of `strings`. Classification flags for the request or its window hierarchy's third parties. + - : `array` of `string`. Classification flags for the request or its window hierarchy's third parties. The classification flags include: diff --git a/files/en-us/mozilla/add-ons/webextensions/api/webrequest/onresponsestarted/index.md b/files/en-us/mozilla/add-ons/webextensions/api/webrequest/onresponsestarted/index.md index e379d582e09ef7c..0fac7bfa9a9ab09 100644 --- a/files/en-us/mozilla/add-ons/webextensions/api/webrequest/onresponsestarted/index.md +++ b/files/en-us/mozilla/add-ons/webextensions/api/webrequest/onresponsestarted/index.md @@ -41,7 +41,7 @@ Events have three functions: - : The function called when this event occurs. The function is passed this argument: - `details` - - : `object`. Details about the request. See the [details](#details_2) section for more information. + - : `object`. Details about the request. See the [details](#details) section for more information. - `filter` - : {{WebExtAPIRef('webRequest.RequestFilter')}}. A filter that restricts the events that is sent to this listener. @@ -126,9 +126,9 @@ Events have three functions: - : `object`. The type of tracking associated with the request, if the request is classified by [Firefox Tracking Protection](https://support.mozilla.org/en-US/kb/enhanced-tracking-protection-firefox-desktop). This is an object with these properties: - `firstParty` - - : `array` of `strings`. Classification flags for the request's first party. + - : `array` of `string`. Classification flags for the request's first party. - `thirdParty` - - : `array` of `strings`. Classification flags for the request or its window hierarchy's third parties. + - : `array` of `string`. Classification flags for the request or its window hierarchy's third parties. The classification flags include: diff --git a/files/en-us/mozilla/add-ons/webextensions/api/webrequest/onsendheaders/index.md b/files/en-us/mozilla/add-ons/webextensions/api/webrequest/onsendheaders/index.md index cb686e8421bfeec..1a6198a13c76a70 100644 --- a/files/en-us/mozilla/add-ons/webextensions/api/webrequest/onsendheaders/index.md +++ b/files/en-us/mozilla/add-ons/webextensions/api/webrequest/onsendheaders/index.md @@ -7,7 +7,7 @@ browser-compat: webextensions.api.webRequest.onSendHeaders {{AddonSidebar}} -This event is fired just before sending headers. If your extension or some other extension modified headers in `{{WebExtAPIRef("webRequest.onBeforeSendHeaders", "onBeforeSendHeaders")}}`, you'll see the modified version here. +This event is fired just before sending headers. If your extension or some other extension modified headers in {{WebExtAPIRef("webRequest.onBeforeSendHeaders", "onBeforeSendHeaders")}}, you'll see the modified version here. This event is informational only. @@ -41,7 +41,7 @@ Events have three functions: - : The function called when this event occurs. The function is passed this argument: - `details` - - : `object`. Details about the request. See the [details](#details_2) section for more information. + - : `object`. Details about the request. See the [details](#details) section for more information. - `filter` - : {{WebExtAPIRef('webRequest.RequestFilter')}}. A filter that restricts the events that is sent to this listener. @@ -118,9 +118,9 @@ Events have three functions: - : `object`. The type of tracking associated with the request, if the request is classified by [Firefox Tracking Protection](https://support.mozilla.org/en-US/kb/enhanced-tracking-protection-firefox-desktop). This is an object with these properties: - `firstParty` - - : `array` of `strings`. Classification flags for the request's first party. + - : `array` of `string`. Classification flags for the request's first party. - `thirdParty` - - : `array` of `strings`. Classification flags for the request or its window hierarchy's third parties. + - : `array` of `string`. Classification flags for the request or its window hierarchy's third parties. The classification flags include: diff --git a/files/en-us/mozilla/add-ons/webextensions/api/webrequest/requestfilter/index.md b/files/en-us/mozilla/add-ons/webextensions/api/webrequest/requestfilter/index.md index 1bc825b98c6fd69..2b12e453c8f8b19 100644 --- a/files/en-us/mozilla/add-ons/webextensions/api/webrequest/requestfilter/index.md +++ b/files/en-us/mozilla/add-ons/webextensions/api/webrequest/requestfilter/index.md @@ -16,7 +16,7 @@ Values of this type are objects. They contain the following properties: - `urls` - : `array` of `string`. An array of [match patterns](/en-US/docs/Mozilla/Add-ons/WebExtensions/Match_patterns). The listener will only be called for requests whose targets match any of the given patterns. Only requests made using HTTP or HTTPS will trigger events, other protocols (such as data: and file:) supported by pattern matching do not trigger events. `view-source:` requests may be matched based on its inner URL. - `types` {{optional_inline}} - - : `array` of `{{WebExtAPIRef('webRequest.ResourceType')}}`. A list of resource types (for example, stylesheets, images, scripts). The listener will only be called for requests for resources which are one of the given types. + - : `array` of {{WebExtAPIRef('webRequest.ResourceType')}}. A list of resource types (for example, stylesheets, images, scripts). The listener will only be called for requests for resources which are one of the given types. - `tabId` {{optional_inline}} - : `integer`. The listener will only be called for requests from the {{WebExtAPIRef("tabs.Tab", "tab")}} identified by this ID. - `windowId` {{optional_inline}} diff --git a/files/en-us/mozilla/add-ons/webextensions/api/webrequest/resourcetype/index.md b/files/en-us/mozilla/add-ons/webextensions/api/webrequest/resourcetype/index.md index 4cf6fb8c8e3a0b0..8dac4455619539d 100644 --- a/files/en-us/mozilla/add-ons/webextensions/api/webrequest/resourcetype/index.md +++ b/files/en-us/mozilla/add-ons/webextensions/api/webrequest/resourcetype/index.md @@ -24,7 +24,9 @@ Values of this type are strings. Possible values are: - `image` - : Resources loaded to be rendered as image, except for `imageset` on browsers that support that type (see browser compatibility below). - `imageset` - - : Images loaded by a {{HTMLElement("picture")}} element or given in an `<img>` element's [`srcset`](/en-US/docs/Web/HTML/Element/img#srcset) attribute. + - : Images loaded by a {{HTMLElement("picture")}} element or given in an `<img>` element's [`srcset`](/en-US/docs/Web/HTML/Reference/Elements/img#srcset) attribute. +- `json` + - : JSON modules loaded through an [import statement](/en-US/docs/Web/JavaScript/Reference/Statements/import). - `main_frame` - : Top-level documents loaded into a tab. - `media` @@ -39,7 +41,7 @@ Values of this type are strings. Possible values are: - : Requests sent by plugins. - `ping` - - : Requests sent to the URL given in a hyperlink's [`ping`](/en-US/docs/Web/HTML/Element/a#ping) attribute, when the hyperlink is followed. + - : Requests sent to the URL given in a hyperlink's [`ping`](/en-US/docs/Web/HTML/Reference/Elements/a#ping) attribute, when the hyperlink is followed. Browsers that don't have a dedicated `beacon` type (see browser compatibility below), also label requests sent through the Beacon API as `ping`. diff --git a/files/en-us/mozilla/add-ons/webextensions/api/webrequest/securityinfo/index.md b/files/en-us/mozilla/add-ons/webextensions/api/webrequest/securityinfo/index.md index 3d5a70a1da0bcbc..7397bde4309c663 100644 --- a/files/en-us/mozilla/add-ons/webextensions/api/webrequest/securityinfo/index.md +++ b/files/en-us/mozilla/add-ons/webextensions/api/webrequest/securityinfo/index.md @@ -39,13 +39,13 @@ Values of this type are objects. They contain the following properties: Note though that at present you can only call `getSecurityInfo()` in the `onHeaderReceived` listener, and the `onHeaderReceived` event is not fired when the handshake fails. So in practice this will never be set. - `hsts` {{optional_inline}} - - : `Boolean`. `true` if the host uses [Strict Transport Security](/en-US/docs/Web/HTTP/Headers/Strict-Transport-Security), `false` otherwise. + - : `Boolean`. `true` if the host uses [Strict Transport Security](/en-US/docs/Web/HTTP/Reference/Headers/Strict-Transport-Security), `false` otherwise. - `isDomainMismatch` {{optional_inline}} - : `Boolean`. `true` if the server's domain name does not match the domain name in its certificate, `false` otherwise. - `isExtendedValidation` {{optional_inline}} - : `Boolean`. `true` if the server has an [Extended Validation Certificate](https://en.wikipedia.org/wiki/Extended_Validation_Certificate), `false` otherwise. - `isNotValidAtThisTime` {{optional_inline}} - - : `Boolean`. `true` if the current time falls outside the server certificate's validity period (i.e. the certificate has expired or is not yet valid), `false` otherwise. + - : `Boolean`. `true` if the current time falls outside the server certificate's validity period (i.e., the certificate has expired or is not yet valid), `false` otherwise. - `isUntrusted` {{optional_inline}} - : `Boolean`. `true` if a chain back to a trusted root certificate could not be constructed, `false` otherwise. - `keaGroupName` {{optional_inline}} diff --git a/files/en-us/mozilla/add-ons/webextensions/api/webrequest/streamfilter/error/index.md b/files/en-us/mozilla/add-ons/webextensions/api/webrequest/streamfilter/error/index.md index 22c26df8107749c..b20e1f536d54978 100644 --- a/files/en-us/mozilla/add-ons/webextensions/api/webrequest/streamfilter/error/index.md +++ b/files/en-us/mozilla/add-ons/webextensions/api/webrequest/streamfilter/error/index.md @@ -25,7 +25,7 @@ function listener(details) { console.log(`Error: ${filter.error}`); }; - //return {}; // not needed + // return {}; // not needed } browser.webRequest.onBeforeRequest.addListener( diff --git a/files/en-us/mozilla/add-ons/webextensions/api/webrequest/streamfilter/index.md b/files/en-us/mozilla/add-ons/webextensions/api/webrequest/streamfilter/index.md index bcdc1949e33fac6..687959f2fe85daf 100644 --- a/files/en-us/mozilla/add-ons/webextensions/api/webrequest/streamfilter/index.md +++ b/files/en-us/mozilla/add-ons/webextensions/api/webrequest/streamfilter/index.md @@ -95,7 +95,7 @@ function listener(details) { filter.disconnect(); }; - //return {}; // not needed + // return {}; // not needed } browser.webRequest.onBeforeRequest.addListener( diff --git a/files/en-us/mozilla/add-ons/webextensions/api/webrequest/streamfilter/ondata/index.md b/files/en-us/mozilla/add-ons/webextensions/api/webrequest/streamfilter/ondata/index.md index 27a2bfaf5d01153..879d7d122db4aee 100644 --- a/files/en-us/mozilla/add-ons/webextensions/api/webrequest/streamfilter/ondata/index.md +++ b/files/en-us/mozilla/add-ons/webextensions/api/webrequest/streamfilter/ondata/index.md @@ -229,10 +229,7 @@ function listener(details) { }; filter.onstop = (event) => { - let combinedLength = 0; - for (const buffer of data) { - combinedLength += buffer.length; - } + const combinedLength = data.reduce((acc, buffer) => acc + buffer.length, 0); const combinedArray = new Uint8Array(combinedLength); let writeOffset = 0; for (const buffer of data) { diff --git a/files/en-us/mozilla/add-ons/webextensions/api/webrequest/streamfilter/write/index.md b/files/en-us/mozilla/add-ons/webextensions/api/webrequest/streamfilter/write/index.md index e3e33d3f17d6fc5..79a701f5c3b78ed 100644 --- a/files/en-us/mozilla/add-ons/webextensions/api/webrequest/streamfilter/write/index.md +++ b/files/en-us/mozilla/add-ons/webextensions/api/webrequest/streamfilter/write/index.md @@ -51,7 +51,7 @@ function listener(details) { filter.disconnect(); }; - //return {}; // not needed + // return {}; // not needed } browser.webRequest.onBeforeRequest.addListener( diff --git a/files/en-us/mozilla/add-ons/webextensions/api/windows/create/index.md b/files/en-us/mozilla/add-ons/webextensions/api/windows/create/index.md index b03e0f91112a479..4f8a70cee543957 100644 --- a/files/en-us/mozilla/add-ons/webextensions/api/windows/create/index.md +++ b/files/en-us/mozilla/add-ons/webextensions/api/windows/create/index.md @@ -61,7 +61,7 @@ let creating = browser.windows.create( - `type` {{optional_inline}} - : A {{WebExtAPIRef('windows.CreateType')}} value. Specifies what type of browser window to create. Specify `panel` or `popup` here to open a window without any of the normal browser UI (address bar, toolbar, etc.). - `url` {{optional_inline}} - - : `string` or `array` of `string`s. A URL or array of URLs to open as tabs in the window. Fully-qualified URLs must include a scheme (i.e. `http://www.google.com`, not `www.google.com`). Relative URLs will be relative to the current page within the extension. Defaults to the New Tab Page. + - : `string` or `array` of `string`s. A URL or array of URLs to open as tabs in the window. Fully-qualified URLs must include a scheme (i.e., `http://www.google.com`, not `www.google.com`). Relative URLs will be relative to the current page within the extension. Defaults to the New Tab Page. - `width` {{optional_inline}} - : `integer`. The width in pixels of the new window, including the frame. If not specified defaults to a natural width. diff --git a/files/en-us/mozilla/add-ons/webextensions/api/windows/getcurrent/index.md b/files/en-us/mozilla/add-ons/webextensions/api/windows/getcurrent/index.md index 6c7d5b5d57ca380..c6da16ba1b6f4f4 100644 --- a/files/en-us/mozilla/add-ons/webextensions/api/windows/getcurrent/index.md +++ b/files/en-us/mozilla/add-ons/webextensions/api/windows/getcurrent/index.md @@ -30,7 +30,7 @@ let gettingCurrent = browser.windows.getCurrent( - `populate` {{optional_inline}} - : `boolean`. If true, the {{WebExtAPIRef('windows.Window')}} object will have a `tabs` property that contains a list of {{WebExtAPIRef('tabs.Tab')}} objects representing the tabs in the window. The `Tab` objects only contain the `url`, `title` and `favIconUrl` properties if the extension's manifest file includes the `"tabs"` permission or [host permissions](/en-US/docs/Mozilla/Add-ons/WebExtensions/manifest.json/permissions#host_permissions) that match the tab's URL. - `windowTypes` {{deprecated_inline}} {{optional_inline}} - - : An `array` of `{{WebExtAPIRef('windows.WindowType')}}` objects. If set, the {{WebExtAPIRef('windows.Window')}} returned will be filtered based on its type. If unset the default filter is set to `['normal', 'panel', 'popup']`, with `'panel'` window types limited to the extension's own windows. + - : An `array` of {{WebExtAPIRef('windows.WindowType')}} objects. If set, the {{WebExtAPIRef('windows.Window')}} returned will be filtered based on its type. If unset the default filter is set to `['normal', 'panel', 'popup']`, with `'panel'` window types limited to the extension's own windows. > [!NOTE] > If supplied, the `windowTypes` component of `getInfo` is ignored. The use of `windowTypes` has been deprecated as of Firefox 62. diff --git a/files/en-us/mozilla/add-ons/webextensions/api/windows/remove/index.md b/files/en-us/mozilla/add-ons/webextensions/api/windows/remove/index.md index 2cfefc85f45993a..d66b6e6657717fd 100644 --- a/files/en-us/mozilla/add-ons/webextensions/api/windows/remove/index.md +++ b/files/en-us/mozilla/add-ons/webextensions/api/windows/remove/index.md @@ -51,7 +51,7 @@ browser.browserAction.onClicked.addListener((tab) => { }); ``` -Close the current, e.g. popup, window when the user clicks a button on the page: +Close the current, e.g., popup, window when the user clicks a button on the page: ```js // in a script loaded by the page in the window diff --git a/files/en-us/mozilla/add-ons/webextensions/browser_compatibility_for_manifest.json/index.md b/files/en-us/mozilla/add-ons/webextensions/browser_compatibility_for_manifest.json/index.md deleted file mode 100644 index 43fed6f5227c15a..000000000000000 --- a/files/en-us/mozilla/add-ons/webextensions/browser_compatibility_for_manifest.json/index.md +++ /dev/null @@ -1,12 +0,0 @@ ---- -title: Browser compatibility for manifest.json -slug: Mozilla/Add-ons/WebExtensions/Browser_compatibility_for_manifest.json -page-type: guide -browser-compat: webextensions.manifest ---- - -{{AddonSidebar}}{{Compat}} - -## See also - -- [Browser support for JavaScript APIs](/en-US/docs/Mozilla/Add-ons/WebExtensions/Browser_support_for_JavaScript_APIs) diff --git a/files/en-us/mozilla/add-ons/webextensions/browser_support_for_javascript_apis/index.md b/files/en-us/mozilla/add-ons/webextensions/browser_support_for_javascript_apis/index.md index 94558a98729e656..631ef77c9624b68 100644 --- a/files/en-us/mozilla/add-ons/webextensions/browser_support_for_javascript_apis/index.md +++ b/files/en-us/mozilla/add-ons/webextensions/browser_support_for_javascript_apis/index.md @@ -10,4 +10,4 @@ page-type: guide ## See also -- [Browser compatibility for manifest.json](/en-US/docs/Mozilla/Add-ons/WebExtensions/Browser_compatibility_for_manifest.json) +- [Browser compatibility for manifest.json](/en-US/docs/Mozilla/Add-ons/WebExtensions/manifest.json#browser_compatibility) diff --git a/files/en-us/mozilla/add-ons/webextensions/build_a_cross_browser_extension/index.md b/files/en-us/mozilla/add-ons/webextensions/build_a_cross_browser_extension/index.md index 1c63b1bde0c20ad..5a9cbb7990d4b0a 100644 --- a/files/en-us/mozilla/add-ons/webextensions/build_a_cross_browser_extension/index.md +++ b/files/en-us/mozilla/add-ons/webextensions/build_a_cross_browser_extension/index.md @@ -129,7 +129,7 @@ For more information, see the [browser support](/en-US/docs/Mozilla/Add-ons/WebE ### Manifest keys -The differences in the [`manifest.json`](/en-US/docs/Mozilla/Add-ons/WebExtensions/Browser_compatibility_for_manifest.json) file keys supported by the main browsers fall broadly into three categories: +The differences in the [`manifest.json`](/en-US/docs/Mozilla/Add-ons/WebExtensions/manifest.json) file keys supported by the main browsers fall broadly into three categories: 1. **Extension information attributes.** For example, at the time of writing, Firefox and Opera include the [`developer`](/en-US/docs/Mozilla/Add-ons/WebExtensions/manifest.json/developer#browser_compatibility) key for details about the developer of the extension. diff --git a/files/en-us/mozilla/add-ons/webextensions/content_scripts/cloneinto/index.md b/files/en-us/mozilla/add-ons/webextensions/content_scripts/cloneinto/index.md index 51782185a7de5e8..d466f0a8603f43a 100644 --- a/files/en-us/mozilla/add-ons/webextensions/content_scripts/cloneinto/index.md +++ b/files/en-us/mozilla/add-ons/webextensions/content_scripts/cloneinto/index.md @@ -83,7 +83,7 @@ You can also pass it into a function defined in the page script. Suppose the pag ```js // page script function foo(greeting) { - console.log("they said: " + greeting.message); + console.log(`they said: ${greeting.message}`); } ``` diff --git a/files/en-us/mozilla/add-ons/webextensions/content_scripts/index.md b/files/en-us/mozilla/add-ons/webextensions/content_scripts/index.md index 0191e348ecfc557..2fa0d26c2741ffe 100644 --- a/files/en-us/mozilla/add-ons/webextensions/content_scripts/index.md +++ b/files/en-us/mozilla/add-ons/webextensions/content_scripts/index.md @@ -10,7 +10,8 @@ A content script is a part of your extension that runs in the context of a web p Content scripts can access [a small subset of the WebExtension APIs](#webextension_apis), but they can [communicate with background scripts](#communicating_with_background_scripts) using a messaging system and thereby indirectly access the WebExtension APIs. [Background scripts](/en-US/docs/Mozilla/Add-ons/WebExtensions/Background_scripts) can access all the [WebExtension JavaScript APIs](/en-US/docs/Mozilla/Add-ons/WebExtensions/API) but can't directly access the content of web pages. -> [!NOTE] Some Web APIs are restricted to [secure contexts](/en-US/docs/Web/Security/Secure_Contexts), which also applies to content scripts running in these contexts. Except for {{domxref("PointerEvent.getCoalescedEvents()")}}, which can be called from content scripts in insecure contexts in Firefox. +> [!NOTE] +> Some Web APIs are restricted to [secure contexts](/en-US/docs/Web/Security/Secure_Contexts), which also applies to content scripts running in these contexts. Except for {{domxref("PointerEvent.getCoalescedEvents()")}}, which can be called from content scripts in insecure contexts in Firefox. ## Loading content scripts @@ -27,7 +28,7 @@ There is only one global scope _per frame, per extension_. This means that varia Using methods (1) and (2), you can only load scripts into pages whose URLs can be represented using a [match pattern](/en-US/docs/Mozilla/Add-ons/WebExtensions/Match_patterns). -Using method (3), you can also load scripts into pages packaged with your extension, but you can't load scripts into privileged browser pages (like "`about:debugging`" or "`about:addons`"). +Using method (3), you can also load scripts into pages packaged with your extension, but you can't load scripts into privileged browser pages (like `about:debugging` or `about:addons`). > **Note:** [Dynamic JS module imports](/en-US/docs/Web/JavaScript/Guide/Modules#dynamic_module_loading) are now working in content scripts. For more details, see [Firefox bug 1536094](https://bugzil.la/1536094). > Only URLs with the _moz-extension_ scheme are allowed, which excludes data URLs ([Firefox bug 1587336](https://bugzil.la/1587336)). @@ -216,9 +217,9 @@ Content scripts can make requests using the normal [`window.XMLHttpRequest`](/en Content scripts get the same cross-domain privileges as the rest of the extension: so if the extension has requested cross-domain access for a domain using the [`permissions`](/en-US/docs/Mozilla/Add-ons/WebExtensions/manifest.json/permissions) key in `manifest.json`, then its content scripts get access that domain as well. > [!NOTE] -> When using Manifest V3, content scripts can perform cross-origin requests when the destination server opts in using [CORS](/en-US/docs/Web/HTTP/CORS); however, host permissions don't work in content scripts, but they still do in regular extension pages. +> When using Manifest V3, content scripts can perform cross-origin requests when the destination server opts in using [CORS](/en-US/docs/Web/HTTP/Guides/CORS); however, host permissions don't work in content scripts, but they still do in regular extension pages. -This is accomplished by exposing more privileged XHR and fetch instances in the content script, which has the side effect of not setting the [`Origin`](/en-US/docs/Web/HTTP/Headers/Origin) and [`Referer`](/en-US/docs/Web/HTTP/Headers/Referer) headers like a request from the page itself would; this is often preferable to prevent the request from revealing its cross-origin nature. +This is accomplished by exposing more privileged XHR and fetch instances in the content script, which has the side effect of not setting the [`Origin`](/en-US/docs/Web/HTTP/Reference/Headers/Origin) and [`Referer`](/en-US/docs/Web/HTTP/Reference/Headers/Referer) headers like a request from the page itself would; this is often preferable to prevent the request from revealing its cross-origin nature. > [!NOTE] > In Firefox in Manifest V2, extensions that need to perform requests that behave as if they were sent by the content itself can use `content.XMLHttpRequest` and `content.fetch()` instead. @@ -228,7 +229,7 @@ This is accomplished by exposing more privileged XHR and fetch instances in the > This is not possible in Manifest V3, as `content.XMLHttpRequest` and `content.fetch()` are not available. > [!NOTE] -> In Chrome, starting with version 73, and Firefox, starting with version 101 when using Manifest V3, content scripts are subject to the same [CORS](/en-US/docs/Web/HTTP/CORS) policy as the page they are running within. Only backend scripts have elevated cross-domain privileges. See [Changes to Cross-Origin Requests in Chrome Extension Content Scripts](https://www.chromium.org/Home/chromium-security/extension-content-script-fetches/). +> In Chrome, starting with version 73, and Firefox, starting with version 101 when using Manifest V3, content scripts are subject to the same [CORS](/en-US/docs/Web/HTTP/Guides/CORS) policy as the page they are running within. Only backend scripts have elevated cross-domain privileges. See [Changes to Cross-Origin Requests in Chrome Extension Content Scripts](https://www.chromium.org/Home/chromium-security/extension-content-script-fetches/). ## Communicating with background scripts diff --git a/files/en-us/mozilla/add-ons/webextensions/content_security_policy/index.md b/files/en-us/mozilla/add-ons/webextensions/content_security_policy/index.md index 21e6d53ea08592c..0314a7375332b8a 100644 --- a/files/en-us/mozilla/add-ons/webextensions/content_security_policy/index.md +++ b/files/en-us/mozilla/add-ons/webextensions/content_security_policy/index.md @@ -6,9 +6,9 @@ page-type: guide {{AddonSidebar}} -Extensions developed with WebExtension APIs have a Content Security Policy (CSP) applied to them by default. This restricts the sources from which they can load code such as [\<script>](/en-US/docs/Web/HTML/Element/script) and disallows potentially unsafe practices such as using [`eval()`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/eval). This article briefly explains what a CSP is, what the default policy is and what it means for an extension, and how an extension can change the default CSP. +Extensions developed with WebExtension APIs have a Content Security Policy (CSP) applied to them by default. This restricts the sources from which they can load code such as [\<script>](/en-US/docs/Web/HTML/Reference/Elements/script) and disallows potentially unsafe practices such as using [`eval()`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/eval). This article briefly explains what a CSP is, what the default policy is and what it means for an extension, and how an extension can change the default CSP. -[Content Security Policy](/en-US/docs/Web/HTTP/CSP) (CSP) is a mechanism to help prevent websites from inadvertently executing malicious content. A website specifies a CSP using an HTTP header sent from the server. The CSP is mostly concerned with specifying legitimate sources of various types of content, such as scripts or embedded plugins. For example, a website can use it to specify that the browser should only execute JavaScript served from the website itself, and not from any other sources. A CSP can also instruct the browser to disallow potentially unsafe practices, such as the use of [`eval()`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/eval). +[Content Security Policy](/en-US/docs/Web/HTTP/Guides/CSP) (CSP) is a mechanism to help prevent websites from inadvertently executing malicious content. A website specifies a CSP using an HTTP header sent from the server. The CSP is mostly concerned with specifying legitimate sources of various types of content, such as scripts or embedded plugins. For example, a website can use it to specify that the browser should only execute JavaScript served from the website itself, and not from any other sources. A CSP can also instruct the browser to disallow potentially unsafe practices, such as the use of [`eval()`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/eval). Like websites, extensions can load content from different sources. For example, a browser action's popup is specified as an HTML document, and it can include JavaScript and CSS from different sources, just like a normal web page: @@ -64,7 +64,7 @@ These policies are applied to any extension that has not explicitly set its own ### Location of script and object resources -Under the default CSP, you can only load code that is local to the extension. The CSP limits {{CSP("script-src")}} to secure sources only, which covers [\<script>](/en-US/docs/Web/HTML/Element/script) resources, [ES6 modules](/en-US/docs/Web/JavaScript/Guide/Modules) and [web workers](/en-US/docs/Web/API/Web_Workers_API/Using_web_workers). In browsers that support obsolete [plugins](/en-US/docs/Glossary/Plugin), the {{CSP("object-src")}} directive is also restricted. For more information on object-src in extensions, see the WECG issue [Remove object-src from the CSP (at least in MV3)](https://github.com/w3c/webextensions/issues/204)). +Under the default CSP, you can only load code that is local to the extension. The CSP limits {{CSP("script-src")}} to secure sources only, which covers [\<script>](/en-US/docs/Web/HTML/Reference/Elements/script) resources, [ES6 modules](/en-US/docs/Web/JavaScript/Guide/Modules) and [web workers](/en-US/docs/Web/API/Web_Workers_API/Using_web_workers). In browsers that support obsolete [plugins](/en-US/docs/Glossary/Plugin), the {{CSP("object-src")}} directive is also restricted. For more information on object-src in extensions, see the WECG issue [Remove object-src from the CSP (at least in MV3)](https://github.com/w3c/webextensions/issues/204)). For example, consider a line like this in an extension's document: diff --git a/files/en-us/mozilla/add-ons/webextensions/developing_webextensions_for_thunderbird/index.md b/files/en-us/mozilla/add-ons/webextensions/developing_webextensions_for_thunderbird/index.md index c50c22ee535380e..c09d48e43d825eb 100644 --- a/files/en-us/mozilla/add-ons/webextensions/developing_webextensions_for_thunderbird/index.md +++ b/files/en-us/mozilla/add-ons/webextensions/developing_webextensions_for_thunderbird/index.md @@ -13,11 +13,11 @@ You'll approach the coding of an extension for Thunderbird in the same way as yo > [!NOTE] > See [ReadTheDocs](https://webextension-api.thunderbird.net/en/latest/) for Thunderbird specific WebExtension API documentation. -Being both Gecko based, Thunderbird supports many of the APIs Firefox supports, with some differences, see [browser compatibility for manifest.json](/en-US/docs/Mozilla/Add-ons/WebExtensions/Browser_compatibility_for_manifest.json) and [browser support for JavaScript APIs](/en-US/docs/Mozilla/Add-ons/WebExtensions/Browser_support_for_JavaScript_APIs) for details. +Being both Gecko based, Thunderbird supports many of the APIs Firefox supports, with some differences, see [browser compatibility for manifest.json](/en-US/docs/Mozilla/Add-ons/WebExtensions/manifest.json#browser_compatibility) and [browser support for JavaScript APIs](/en-US/docs/Mozilla/Add-ons/WebExtensions/Browser_support_for_JavaScript_APIs) for details. ## See also - [Introduction to Thunderbird Add-On development](https://developer.thunderbird.net/add-ons/about-add-ons) - [Thunderbird specific WebExtension API documentation](https://webextension-api.thunderbird.net/en/latest/) - [Browser support for JavaScript APIs](/en-US/docs/Mozilla/Add-ons/WebExtensions/Browser_support_for_JavaScript_APIs) -- [Browser compatibility for manifest.json](/en-US/docs/Mozilla/Add-ons/WebExtensions/Browser_compatibility_for_manifest.json) +- [Browser compatibility for manifest.json](/en-US/docs/Mozilla/Add-ons/WebExtensions/manifest.json#browser_compatibility) diff --git a/files/en-us/mozilla/add-ons/webextensions/differences_between_api_implementations/index.md b/files/en-us/mozilla/add-ons/webextensions/differences_between_api_implementations/index.md index 559924e2753b754..5018c7334fb45f6 100644 --- a/files/en-us/mozilla/add-ons/webextensions/differences_between_api_implementations/index.md +++ b/files/en-us/mozilla/add-ons/webextensions/differences_between_api_implementations/index.md @@ -50,4 +50,4 @@ You can find more detailed information about the differences in the supported br - [Chrome incompatibilities](/en-US/docs/Mozilla/Add-ons/WebExtensions/Chrome_incompatibilities) - [Browser support for JavaScript APIs](/en-US/docs/Mozilla/Add-ons/WebExtensions/Browser_support_for_JavaScript_APIs) -- [Browser compatibility for manifest.json](/en-US/docs/Mozilla/Add-ons/WebExtensions/Browser_compatibility_for_manifest.json) +- [Browser compatibility for manifest.json](/en-US/docs/Mozilla/Add-ons/WebExtensions/manifest.json#browser_compatibility) diff --git a/files/en-us/mozilla/add-ons/webextensions/extending_the_developer_tools/index.md b/files/en-us/mozilla/add-ons/webextensions/extending_the_developer_tools/index.md index af3b22691c6f772..895b328348694ec 100644 --- a/files/en-us/mozilla/add-ons/webextensions/extending_the_developer_tools/index.md +++ b/files/en-us/mozilla/add-ons/webextensions/extending_the_developer_tools/index.md @@ -23,7 +23,7 @@ This manifest key implicitly sets the `"devtools"` permission, which triggers [a The devtools page is loaded when the browser devtools are opened, and unloaded when it is closed. Note that because the devtools window is associated with a single tab, it's quite possible for more than one devtools window - hence more than one devtools page - to exist at the same time. -The devtools page doesn't have any visible DOM, but can include JavaScript sources using [`<script>`](/en-US/docs/Web/HTML/Element/script) tags. The sources must be bundled with the extension itself. The sources get access to: +The devtools page doesn't have any visible DOM, but can include JavaScript sources using [`<script>`](/en-US/docs/Web/HTML/Reference/Elements/script) tags. The sources must be bundled with the extension itself. The sources get access to: - The normal DOM APIs accessible through the global [`window`](/en-US/docs/Web/API/Window) object - The same [WebExtension APIs as in Content Scripts](/en-US/docs/Mozilla/Add-ons/WebExtensions/Content_scripts#webextension_apis) @@ -64,8 +64,8 @@ browser.devtools.panels "/devtools/panel/panel.html", // content ) .then((newPanel) => { - newPanel.onShown.addListener(initialisePanel); - newPanel.onHidden.addListener(unInitialisePanel); + newPanel.onShown.addListener(initializePanel); + newPanel.onHidden.addListener(unInitializePanel); }); ``` diff --git a/files/en-us/mozilla/add-ons/webextensions/implement_a_settings_page/index.md b/files/en-us/mozilla/add-ons/webextensions/implement_a_settings_page/index.md index a15baea73125dc3..cedd73e37819568 100644 --- a/files/en-us/mozilla/add-ons/webextensions/implement_a_settings_page/index.md +++ b/files/en-us/mozilla/add-ons/webextensions/implement_a_settings_page/index.md @@ -188,7 +188,7 @@ Now: - [reload the extension](https://extensionworkshop.com/documentation/develop/temporary-installation-in-firefox/#reloading_a_temporary_add-on) - load a web page -- visit "`about:addons`" to open the settings and click the Preferences button next to the extension's entry and change the border color. +- visit `about:addons` to open the settings and click the Preferences button next to the extension's entry and change the border color. - reload the web page to see the difference. ## Learn more diff --git a/files/en-us/mozilla/add-ons/webextensions/index.md b/files/en-us/mozilla/add-ons/webextensions/index.md index 7ef1dd7cdecadb9..80a08a96a6505c4 100644 --- a/files/en-us/mozilla/add-ons/webextensions/index.md +++ b/files/en-us/mozilla/add-ons/webextensions/index.md @@ -20,15 +20,28 @@ The technology for extensions in Firefox is, to a large extent, compatible with - : Discover how to build and publish extensions for Firefox: get the lowdown on developer tools, publication and distribution, and porting on [Extension Workshop](https://extensionworkshop.com/). > [!NOTE] -> If you have ideas or questions or need help, you can reach us on the [community forum](https://discourse.mozilla.org/c/add-ons/35) or in the [Add-ons Room](https://matrix.to/#/!CuzZVoCbeoDHsxMCVJ:mozilla.org?via=mozilla.org&via=matrix.org&via=humanoids.be) on [Matrix](https://wiki.mozilla.org/Matrix). +> If you have ideas or questions or need help, you can reach us on the [community forum](https://discourse.mozilla.org/c/add-ons/35) or in the [Add-ons Room](https://matrix.to/#/#addons:mozilla.org) on [Matrix](https://wiki.mozilla.org/Matrix). ## Get started -Discover [what extensions can do](/en-US/docs/Mozilla/Add-ons/WebExtensions/What_are_WebExtensions) before building [your first extension.](/en-US/docs/Mozilla/Add-ons/WebExtensions/Your_first_WebExtension) Learn about the [anatomy of an extension](/en-US/docs/Mozilla/Add-ons/WebExtensions/Anatomy_of_a_WebExtension) and get an overview of the [extension development and publication workflow, Firefox style](https://extensionworkshop.com/documentation/develop/firefox-workflow-overview/). Explore a little deeper with a comprehensive selection of [example extensions](/en-US/docs/Mozilla/Add-ons/WebExtensions/Examples) that you can run right in Firefox. +Discover [what extensions can do](/en-US/docs/Mozilla/Add-ons/WebExtensions/What_are_WebExtensions) before building [your first extension](/en-US/docs/Mozilla/Add-ons/WebExtensions/Your_first_WebExtension) and [your second extension](/en-US/docs/Mozilla/Add-ons/WebExtensions/Your_second_WebExtension). Learn about the [anatomy of an extension](/en-US/docs/Mozilla/Add-ons/WebExtensions/Anatomy_of_a_WebExtension) and get an overview of the [extension development and publication workflow, Firefox style](https://extensionworkshop.com/documentation/develop/firefox-workflow-overview/). Explore a little deeper with a comprehensive selection of [example extensions](/en-US/docs/Mozilla/Add-ons/WebExtensions/Examples) that you can run right in Firefox. Continue your learning by [discovering a list of resources](/en-US/docs/Mozilla/Add-ons/WebExtensions/What_next) to follow. ## Concepts -Get detailed information on the concept that underpin extensions [from an overview of the JavaScript API](/en-US/docs/Mozilla/Add-ons/WebExtensions/API), through [content scripts,](/en-US/docs/Mozilla/Add-ons/WebExtensions/Content_scripts) [match patterns](/en-US/docs/Mozilla/Add-ons/WebExtensions/Match_patterns), [working with files](/en-US/docs/Mozilla/Add-ons/WebExtensions/Working_with_files), [internationalization](/en-US/docs/Mozilla/Add-ons/WebExtensions/Internationalization), and [content security policy](/en-US/docs/Mozilla/Add-ons/WebExtensions/Content_Security_Policy), to more advanced subjects such as [native messaging](/en-US/docs/Mozilla/Add-ons/WebExtensions/Native_messaging), [using the devtools APIs](/en-US/docs/Mozilla/Add-ons/WebExtensions/Extending_the_developer_tools), and [native manifests](/en-US/docs/Mozilla/Add-ons/WebExtensions/Native_manifests). +Get detailed information on the concepts that underpin extensions. + +- [Overview of the JavaScript API](/en-US/docs/Mozilla/Add-ons/WebExtensions/API) +- [Content scripts](/en-US/docs/Mozilla/Add-ons/WebExtensions/Content_scripts) +- [Background scripts](/en-US/docs/Mozilla/Add-ons/WebExtensions/Background_scripts) +- [Match patterns](/en-US/docs/Mozilla/Add-ons/WebExtensions/Match_patterns) +- [Working with files](/en-US/docs/Mozilla/Add-ons/WebExtensions/Working_with_files) +- [Internationalization](/en-US/docs/Mozilla/Add-ons/WebExtensions/Internationalization) +- [Content security policy](/en-US/docs/Mozilla/Add-ons/WebExtensions/Content_Security_Policy) +- [Native messaging](/en-US/docs/Mozilla/Add-ons/WebExtensions/Native_messaging) +- [Native manifests](/en-US/docs/Mozilla/Add-ons/WebExtensions/Native_manifests) +- [User actions](/en-US/docs/Mozilla/Add-ons/WebExtensions/User_actions) +- [Differences between API implementations](/en-US/docs/Mozilla/Add-ons/WebExtensions/Differences_between_API_implementations) +- [Chrome incompatibilities](/en-US/docs/Mozilla/Add-ons/WebExtensions/Chrome_incompatibilities) ## User interface @@ -36,7 +49,21 @@ Discover all the [user interface](/en-US/docs/Mozilla/Add-ons/WebExtensions/user ## How to -From patterns you'll regularly use such as [work with the Tabs API](/en-US/docs/Mozilla/Add-ons/WebExtensions/Working_with_the_Tabs_API) and [adding a button to the toolbar](/en-US/docs/Mozilla/Add-ons/WebExtensions/Add_a_button_to_the_toolbar) to more advanced topics such as [intercepting HTTP requests](/en-US/docs/Mozilla/Add-ons/WebExtensions/Intercept_HTTP_requests) and [working with contextual identities](/en-US/docs/Mozilla/Add-ons/WebExtensions/Work_with_contextual_identities), you'll find a range of tutorials to get you started. +A range of tutorials to get you started on specific aspects of extension development. + +- [Intercept HTTP requests](/en-US/docs/Mozilla/Add-ons/WebExtensions/Intercept_HTTP_requests) +- [Modify a web page](/en-US/docs/Mozilla/Add-ons/WebExtensions/Modify_a_web_page) +- [Safely insert external content into a page](/en-US/docs/Mozilla/Add-ons/WebExtensions/Safely_inserting_external_content_into_a_page) +- [Share objects with page scripts](/en-US/docs/Mozilla/Add-ons/WebExtensions/Sharing_objects_with_page_scripts) +- [Add a button to the toolbar](/en-US/docs/Mozilla/Add-ons/WebExtensions/Add_a_button_to_the_toolbar) +- [Implement a settings page](/en-US/docs/Mozilla/Add-ons/WebExtensions/Implement_a_settings_page) +- [Work with the Tabs API](/en-US/docs/Mozilla/Add-ons/WebExtensions/Working_with_the_Tabs_API) +- [Work with the Bookmarks API](/en-US/docs/Mozilla/Add-ons/WebExtensions/Work_with_the_Bookmarks_API) +- [Work with the Cookies API](/en-US/docs/Mozilla/Add-ons/WebExtensions/Work_with_the_Cookies_API) +- [Work with contextual identities](/en-US/docs/Mozilla/Add-ons/WebExtensions/Work_with_contextual_identities) +- [Interact with the clipboard](/en-US/docs/Mozilla/Add-ons/WebExtensions/Interact_with_the_clipboard) +- [Extend the developer tools](/en-US/docs/Mozilla/Add-ons/WebExtensions/Extending_the_developer_tools) +- [Build a cross-browser extension](/en-US/docs/Mozilla/Add-ons/WebExtensions/Build_a_cross_browser_extension) ## Firefox workflow @@ -55,4 +82,4 @@ Get comprehensive details about the methods, properties, types, and events for a ### Manifest keys -Get full details about the [manifest keys](/en-US/docs/Mozilla/Add-ons/WebExtensions/manifest.json), including all their properties and settings. There's also detailed information on the [compatibility](/en-US/docs/Mozilla/Add-ons/WebExtensions/Browser_compatibility_for_manifest.json) of each key with the major browsers. +Get full details about the [manifest keys](/en-US/docs/Mozilla/Add-ons/WebExtensions/manifest.json), including all their properties and settings. diff --git a/files/en-us/mozilla/add-ons/webextensions/interact_with_the_clipboard/index.md b/files/en-us/mozilla/add-ons/webextensions/interact_with_the_clipboard/index.md index 0c3274cfa323f7d..bd55ec21eeb3e60 100644 --- a/files/en-us/mozilla/add-ons/webextensions/interact_with_the_clipboard/index.md +++ b/files/en-us/mozilla/add-ons/webextensions/interact_with_the_clipboard/index.md @@ -165,7 +165,7 @@ document.querySelector("#paste").addEventListener("click", paste); ### Browser-specific considerations -Firefox supports the `"clipboardRead"` [permission](/en-US/docs/Mozilla/Add-ons/WebExtensions/manifest.json/permissions) from version 54 but only supports pasting into elements in [content editable mode](/en-US/docs/Web/HTML/Global_attributes/contenteditable), which for content scripts only works with a {{HTMLElement("textarea")}}. For background scripts, any element can be set to content editable mode. +Firefox supports the `"clipboardRead"` [permission](/en-US/docs/Mozilla/Add-ons/WebExtensions/manifest.json/permissions) from version 54 but only supports pasting into elements in [content editable mode](/en-US/docs/Web/HTML/Reference/Global_attributes/contenteditable), which for content scripts only works with a {{HTMLElement("textarea")}}. For background scripts, any element can be set to content editable mode. ## Browser compatibility @@ -175,4 +175,4 @@ Firefox supports the `"clipboardRead"` [permission](/en-US/docs/Mozilla/Add-ons/ - [Clipboard API](/en-US/docs/Web/API/Clipboard_API) - [Permissions API](/en-US/docs/Web/API/Permissions_API) -- [Make content editable](/en-US/docs/Web/HTML/Global_attributes/contenteditable) +- [Make content editable](/en-US/docs/Web/HTML/Reference/Global_attributes/contenteditable) diff --git a/files/en-us/mozilla/add-ons/webextensions/internationalization/index.md b/files/en-us/mozilla/add-ons/webextensions/internationalization/index.md index df305cd1047f64a..38dcda92a7997fd 100644 --- a/files/en-us/mozilla/add-ons/webextensions/internationalization/index.md +++ b/files/en-us/mozilla/add-ons/webextensions/internationalization/index.md @@ -201,7 +201,7 @@ It is possible to insert your variables (`$1`, `$2`, `$3`, etc.) directly into t } ``` -This may seem quicker and less complex, but the other way (using `"placeholders"`) is seen as best practice. This is because having the placeholder name (e.g. `"url"`) and example helps you to remember what the placeholder is for — a week after you write your code, you'll probably forget what `$1` – `$8` refer to, but you'll be more likely to know what your placeholder names refer to. +This may seem quicker and less complex, but the other way (using `"placeholders"`) is seen as best practice. This is because having the placeholder name (e.g., `"url"`) and example helps you to remember what the placeholder is for — a week after you write your code, you'll probably forget what `$1` – `$8` refer to, but you'll be more likely to know what your placeholder names refer to. ### Hardcoded substitution @@ -225,14 +225,14 @@ In addition, you can use such substitutions to specify parts of the string that ## Localized string selection -Locales can be specified using only a language code, like `fr` or `en`, or they may be further qualified with a region code, like `en_US` or `en_GB`, which describes a regional variant of the same basic language. When you ask the i18n system for a string, it will select a string using the following algorithm: +Locales can be specified using a language code, such as `fr` or `en` or qualified with a script and region code, such as `en-US` or `zh-Hans-CN`. When your extension asks the i18n system for a string, it selects a string using this algorithm: -1. if there is a `messages.json` file for the exact current locale, and it contains the string, return it. -2. Otherwise, if the current locale is qualified with a region (e.g. `en_US`) and there is a `messages.json` file for the regionless version of that locale (e.g. `en`), and that file contains the string, return it. +1. Return the string if there is a `messages.json` file for the user's set browser locale containing the string. For example, if the user has set their browser to `en-US` and the extension provides the `_locales/en_US/messages.json` file. +2. Otherwise, if the browser locale is qualified with a script or region (e.g., `en-US` or `zh-Hans-CN`) and there is a `messages.json` file for the regionless version and failing that the scriptless version of that locale and that file contains the string, return it. For example, if the user has set their browser to `zh-Hans-CN` (and there is no `_locales/zh_Hans_CN/messages.json` file) the i18n system looks for a string in `zh-Hans`, and if that isn't available, `zh`. 3. Otherwise, if there is a `messages.json` file for the `default_locale` defined in the `manifest.json`, and it contains the string, return it. 4. Otherwise return an empty string. -Take the following example: +Take this example: - extension-root-directory/ @@ -256,10 +256,11 @@ Take the following example: - `{ "colorLocalized": { "message": "couleur", "description": "Color." }, /* … */}` -Suppose the `default_locale` is set to `fr`, and the browser's current locale is `en_GB`: +Suppose the `default_locale` is set to `fr`. -- If the extension calls `getMessage("colorLocalized")`, it will return "colour". -- If "colorLocalized" were not present in `en_GB`, then `getMessage("colorLocalized")`, would return "color", not "couleur". +- If the browser's locale is `en-GB` when the extension calls `getMessage("colorLocalized")`, it is returned "colour" because `_locales/en_GB/messages.json` contains the `colorLocalized` message. +- If the browser's locale is `en-US` when the extension calls `getMessage("colorLocalized")`, it is returned "color" because it falls back to the message present in `_locales/en/messages.json`. +- If the browser's locale is `zh-Hans-CN` when the extension calls `getMessage("colorLocalized")`, it is returned "couleur" because there is no language, script, or region match to the `zh-Hans-CN` locale. ## Predefined messages @@ -393,12 +394,12 @@ padding-right: 0; padding-left: 1.5em; ``` -## Testing out your extension +## Testing your extension To test your extension's localization, you use [Firefox](https://www.mozilla.org/en-US/firefox/new/) or [Firefox Beta](https://www.mozilla.org/en-US/firefox/channel/desktop/), the Firefox builds in which you can install language packs. Then, for each locale supported in the extension you want to test, follow the instructions to [Use Firefox in another language](https://support.mozilla.org/en-US/kb/use-firefox-another-language) to switch the Firefox UI language. (If you know your way around Settings, under Language, use Set Alternatives.) -Once Firefox is running in your test language, [install the extension temporarily](https://extensionworkshop.com/documentation/develop/temporary-installation-in-firefox/). After installing your extension, in `about:debugging`, if you've set up your extension correctly, you see the extension listed with its icon, name, and description in the chosen language. You can also see the localized extension details in `about:addons`. Now exercise the extension's features to ensure the translations you need are in place. +When Firefox is running in your test language, from `about:debugging`, [install the extension temporarily](https://extensionworkshop.com/documentation/develop/temporary-installation-in-firefox/) or reload it if already installed. After installing or reloading your extension, if you've set up your extension correctly, you see the extension listed with its icon, name, and description in the chosen language. You can also see the localized extension details in `about:addons`. Now, exercise the extension's features to ensure the translations are in place. If you'd like to try this process out, you can use the [notify-link-clicks-i18n](https://github.com/mdn/webextensions-examples/tree/main/notify-link-clicks-i18n) extension. Set up Firefox to display one of the languages supported in this example (German, Dutch, or Japanese). Load the extension and go to a website. Click a link to see the translated version of the notification reporting the link's URL. diff --git a/files/en-us/mozilla/add-ons/webextensions/manifest.json/action/index.md b/files/en-us/mozilla/add-ons/webextensions/manifest.json/action/index.md index 4544b26280393ce..05331ecae0f21b0 100644 --- a/files/en-us/mozilla/add-ons/webextensions/manifest.json/action/index.md +++ b/files/en-us/mozilla/add-ons/webextensions/manifest.json/action/index.md @@ -173,24 +173,24 @@ The `action` key is an object that may have any of these properties, all optiona <p> The HTML file may include CSS and JavaScript files using <code - ><a href="/en-US/docs/Web/HTML/Element/link">&#x3C;link></a></code + ><a href="/en-US/docs/Web/HTML/Reference/Elements/link">&#x3C;link></a></code > and <code - ><a href="/en-US/docs/Web/HTML/Element/script" + ><a href="/en-US/docs/Web/HTML/Reference/Elements/script" >&#x3C;script></a ></code > elements, just like a normal web page. However, <code - ><a href="/en-US/docs/Web/HTML/Element/script" + ><a href="/en-US/docs/Web/HTML/Reference/Elements/script" >&#x3C;script> </a></code - >must have - <code><a href="/en-US/docs/Web/HTML/Element/script">src</a></code> + > must have + <code><a href="/en-US/docs/Web/HTML/Reference/Elements/script">src</a></code> attribute to load a file. Don't use <code - ><a href="/en-US/docs/Web/HTML/Element/script" + ><a href="/en-US/docs/Web/HTML/Reference/Elements/script" >&#x3C;script></a ></code > diff --git a/files/en-us/mozilla/add-ons/webextensions/manifest.json/author/index.md b/files/en-us/mozilla/add-ons/webextensions/manifest.json/author/index.md index ce0258a0427cfa5..c681b2bd15ab641 100644 --- a/files/en-us/mozilla/add-ons/webextensions/manifest.json/author/index.md +++ b/files/en-us/mozilla/add-ons/webextensions/manifest.json/author/index.md @@ -28,9 +28,13 @@ browser-compat: webextensions.manifest.author </tbody> </table> -The extension's author, intended for display in the browser's user interface. If the [developer](/en-US/docs/Mozilla/Add-ons/WebExtensions/manifest.json/developer) key is supplied and it contains the "name" property, it will override the author key. There's no way to specify multiple authors. +The extension's author. It's intended for display in the browser's user interface. The string held by value is a [localizable property](/en-US/docs/Mozilla/Add-ons/WebExtensions/Internationalization#internationalizing_manifest.json). -This is a [localizable property](/en-US/docs/Mozilla/Add-ons/WebExtensions/Internationalization#internationalizing_manifest.json). +Firefox expects this key to represent the name of the person or entity that developed the extension. If the [developer](/en-US/docs/Mozilla/Add-ons/WebExtensions/manifest.json/developer) key is also specified as an object with a `name` property, the value of `name` overrides the `author` key. + +Using the `developer` key to identify the author in Firefox is recommended. + +As of May 2025, Chrome and the Chrome Web Store don't use this key. ## Example diff --git a/files/en-us/mozilla/add-ons/webextensions/manifest.json/background/index.md b/files/en-us/mozilla/add-ons/webextensions/manifest.json/background/index.md index b7e1b1e81b204ed..3a835036b3647c8 100644 --- a/files/en-us/mozilla/add-ons/webextensions/manifest.json/background/index.md +++ b/files/en-us/mozilla/add-ons/webextensions/manifest.json/background/index.md @@ -52,7 +52,7 @@ The `background` key is an object that must have one of these properties (for mo <p> If you need specific content in the background page, you can define a page using the <code>page</code> property. This is a - <code>String</code> representing a path relative to the manifest.json + <code>string</code> representing a path relative to the manifest.json file to an HTML document included in your extension bundle. </p> <p> @@ -66,10 +66,10 @@ The `background` key is an object that must have one of these properties (for mo <td><code>scripts</code></td> <td> <p> - An <code>Array</code> of <code>Strings</code>, each of which is a path + An <code>array</code> of <code>string</code>, each of which is a path to a JavaScript source. The path is relative to the manifest.json file itself. These are the scripts that are executed in the - extension's background page. + extension's background context. </p> <p>The scripts share the same <code>window</code> global context.</p> <p>The scripts are loaded in the order they appear in the array.</p> @@ -114,7 +114,7 @@ The `background` key can also contain this optional property: <tr> <td><code>persistent</code></td> <td> - <p>A <code>Boolean</code> value.</p> + <p>A <code>boolean</code> value.</p> <p>If omitted, this property defaults to <code>true</code> in Manifest V2 and <code>false</code> in Manifest V3. Setting to <code>true</code> in Manifest V3 results in an error.</p> <ul> <li> @@ -139,11 +139,27 @@ The `background` key can also contain this optional property: </ul> </td> </tr> + <tr> + <td><code>preferred_environment</code></td> + <td> + <p>An <code>array</code> of <code>string</code> listing the preferred environments in order of precedence.</p> + <p>If <code>background</code> specifies a <code>service_worker</code> and a <code>page</code> or <code>scripts</code>, this property enables the extension to tell the browser which background context to use if available. See <a href="#browser_support">Browser support</a> for details of the environments supported in the major browsers.</p> + <ul> + <li> + <code>document</code> requests that the browser use the extension's background scripts as documents, if supported. + </li> + <li> + <code>service_worker</code> requests that the the browser run the extension's background scripts as service workers, if supported. + </li> + </ul> + <p>Chrome only supports service workers, so it ignores this key. If omitted, Firefox and Safari run background scripts as documents. Safari uses a service worker context if the extension specifies <code>scripts</code> and <code>preferred_environment</code> is set to <code>service_worker</code>.</p> + </td> + </tr> <tr> <td><code>type</code></td> <td> - <p>A <code>String</code> value.</p> - <p>Determines whether the scripts specified in <code>"scripts"</code> are loaded as ES modules.</p> + <p>A <code>string</code> value.</p> + <p>Determines whether the scripts specified in <code>scripts</code> are loaded as ES modules.</p> <ul> <li> <code>classic</code> indicates the background scripts or service workers are not included as an ES Module. @@ -170,8 +186,7 @@ Support for the `scripts`, `page`, and `service_worker` properties varies betwee - `background.service_worker` is not supported (see [Firefox bug 1573659](https://bugzil.la/1573659)). - supports `background.scripts` (or `background.page`) if `service_worker` is not specified or the service worker feature is disabled. Before Firefox 120, Firefox did not start the background page if `service_worker` was present (see [Firefox bug 1860304](https://bugzil.la/1860304)). From Firefox 121, the background page starts as expected, regardless of the presence of `service_worker`. - Safari: - - supports `background.service_worker`. - - supports `background.scripts` (or `background.page`) if `service_worker` is not specified. + - supports `background.scripts` (or `background.page`) and `background.service_worker`. If both are specified, uses `background.scripts` (or `background.page`), unless `preferred_environment` is set to `service_worker`. To illustrate, this is an example of a cross-browser extension that supports `scripts` and `service_worker`. The example has this manifest.json file: @@ -189,8 +204,8 @@ To illustrate, this is an example of a cross-browser extension that supports `sc And, background.js contains: -```javascript -if (typeof browser == "undefined") { +```js +if (typeof browser === "undefined") { // Chrome does not support the browser namespace yet. globalThis.browser = chrome; } diff --git a/files/en-us/mozilla/add-ons/webextensions/manifest.json/browser_action/index.md b/files/en-us/mozilla/add-ons/webextensions/manifest.json/browser_action/index.md index 54f04e0e64998de..bec5b274c0e8202 100644 --- a/files/en-us/mozilla/add-ons/webextensions/manifest.json/browser_action/index.md +++ b/files/en-us/mozilla/add-ons/webextensions/manifest.json/browser_action/index.md @@ -214,24 +214,24 @@ The `browser_action` key is an object that may have any of the following propert <p> The HTML file may include CSS and JavaScript files using <code - ><a href="/en-US/docs/Web/HTML/Element/link">&#x3C;link></a></code + ><a href="/en-US/docs/Web/HTML/Reference/Elements/link">&#x3C;link></a></code > and <code - ><a href="/en-US/docs/Web/HTML/Element/script" + ><a href="/en-US/docs/Web/HTML/Reference/Elements/script" >&#x3C;script></a ></code > elements, just like a normal web page. However, <code - ><a href="/en-US/docs/Web/HTML/Element/script" + ><a href="/en-US/docs/Web/HTML/Reference/Elements/script" >&#x3C;script> </a></code - >must have - <code><a href="/en-US/docs/Web/HTML/Element/script">src</a></code> + > must have + <code><a href="/en-US/docs/Web/HTML/Reference/Elements/script">src</a></code> attribute to load a file. Don't use <code - ><a href="/en-US/docs/Web/HTML/Element/script" + ><a href="/en-US/docs/Web/HTML/Reference/Elements/script" >&#x3C;script></a ></code > diff --git a/files/en-us/mozilla/add-ons/webextensions/manifest.json/browser_specific_settings/index.md b/files/en-us/mozilla/add-ons/webextensions/manifest.json/browser_specific_settings/index.md index b950c551dc64a24..99a90d842a11857 100644 --- a/files/en-us/mozilla/add-ons/webextensions/manifest.json/browser_specific_settings/index.md +++ b/files/en-us/mozilla/add-ons/webextensions/manifest.json/browser_specific_settings/index.md @@ -29,7 +29,7 @@ browser-compat: webextensions.manifest.browser_specific_settings <tr> <th scope="row">Example</th> <td> - <pre class="brush: json;"> + <pre class="brush: json"> "browser_specific_settings": { "gecko": { "id": "addon@example.com", @@ -54,7 +54,7 @@ Firefox stores browser-specific settings in these sub-keys: - `gecko` for the desktop version of Firefox. - `gecko_android` for the Android version of Firefox. -The `gecko` subkey supports these properties: +The `gecko` sub-key supports these properties: - `id` - : The extension ID. When provided, this property must contain 80 characters or less. See [Extensions and the Add-on ID](https://extensionworkshop.com/documentation/develop/extensions-and-the-add-on-id/) to determine when to specify the ID. @@ -65,7 +65,7 @@ The `gecko` subkey supports these properties: - `update_url` - : A link to an [extension update manifest](https://extensionworkshop.com/documentation/manage/updating-your-extension/). Note that the link must begin with "https". This key is for managing extension updates yourself (i.e., not through AMO). -The `gecko_android` subkey supports these properties: +The `gecko_android` sub-key supports these properties: - `strict_min_version` - : Minimum version of Gecko to support on Android. If the Firefox for Android version on which the extension is being installed or run is below this version, the extension is not installed or not run. If not provided, defaults to the version determined by `gecko.strict_min_version`. "\*" is not valid in this field. @@ -74,7 +74,7 @@ The `gecko_android` subkey supports these properties: See the list of [valid Gecko versions](https://addons.mozilla.org/api/v5/applications/firefox/). -To support Firefox for Android without specifying a version range, the `gecko_android` subkey must be an empty object, i.e. `"gecko_android": {}`. Otherwise, the extension is only made available on desktop Firefox. +To support Firefox for Android without specifying a version range, the `gecko_android` sub-key must be an empty object, i.e., `"gecko_android": {}`. Otherwise, the extension is only made available on desktop Firefox. #### Extension ID format @@ -97,7 +97,7 @@ For example: ### Safari properties -Safari stores its browser-specific settings in the `safari` subkey, which has these properties: +Safari stores its browser-specific settings in the `safari` sub-key, which has these properties: - `strict_min_version` - : Minimum version of Safari to support. diff --git a/files/en-us/mozilla/add-ons/webextensions/manifest.json/chrome_settings_overrides/index.md b/files/en-us/mozilla/add-ons/webextensions/manifest.json/chrome_settings_overrides/index.md index fb9fe8f0f930b8e..37d731d88afea67 100644 --- a/files/en-us/mozilla/add-ons/webextensions/manifest.json/chrome_settings_overrides/index.md +++ b/files/en-us/mozilla/add-ons/webextensions/manifest.json/chrome_settings_overrides/index.md @@ -24,7 +24,7 @@ browser-compat: webextensions.manifest.chrome_settings_overrides <tr> <th scope="row">Example</th> - <td><pre class="brush:json"> + <td><pre class="brush: json"> "chrome_settings_overrides" : { "homepage": "https://developer.mozilla.org/" }, @@ -89,7 +89,7 @@ The `chrome_settings_overrides` key is an object that may have the following pro The search provider has a name and a primary search URL. Alternative URLs may be provided, including URLs for more specialized searches like image search. In the URL you supply, use - "<code>{searchTerms}</code>" to interpolate the search term into the + <code>{searchTerms}</code> to interpolate the search term into the URL, like: <code>https://www.discogs.com/search/?q={searchTerms}</code>. You can also provide POST parameters to be sent along with the search. diff --git a/files/en-us/mozilla/add-ons/webextensions/manifest.json/chrome_url_overrides/index.md b/files/en-us/mozilla/add-ons/webextensions/manifest.json/chrome_url_overrides/index.md index 530a0ae8e51a1d1..68cd9c6065b57c8 100644 --- a/files/en-us/mozilla/add-ons/webextensions/manifest.json/chrome_url_overrides/index.md +++ b/files/en-us/mozilla/add-ons/webextensions/manifest.json/chrome_url_overrides/index.md @@ -91,7 +91,7 @@ The `chrome_url_overrides` key is an object that may have the following properti </p> <p> It's very good practice to include a - <a href="/en-US/docs/Web/HTML/Element/title">&#x3C;title></a> for the + <a href="/en-US/docs/Web/HTML/Reference/Elements/title">&#x3C;title></a> for the page, or the tab's title will be the "moz-extension://..." URL. </p> <p> diff --git a/files/en-us/mozilla/add-ons/webextensions/manifest.json/commands/index.md b/files/en-us/mozilla/add-ons/webextensions/manifest.json/commands/index.md index ed3960903e05a83..dabf69b2ae6136b 100644 --- a/files/en-us/mozilla/add-ons/webextensions/manifest.json/commands/index.md +++ b/files/en-us/mozilla/add-ons/webextensions/manifest.json/commands/index.md @@ -63,7 +63,7 @@ The `suggested_key` property is an object with any or none of these properties ( - `"android"` - `"ios"` -The value of each property is the keyboard shortcut for the command on that platform, as a string containing keys separated by "`+`". The value for `"default"` is used on all platforms that aren't explicitly listed. If `"default"`` isn't included, the command doesn't have a keyboard shortcut on any platform not included, unless a shortcut is configured by the user or through the {{WebExtAPIRef("commands.update")}} API. +The value of each property is the keyboard shortcut for the command on that platform, as a string containing keys separated by `+`. The value for `"default"` is used on all platforms that aren't explicitly listed. If `"default"` isn't included, the command doesn't have a keyboard shortcut on any platform not included, unless a shortcut is configured by the user or through the {{WebExtAPIRef("commands.update")}} API. For example: @@ -187,7 +187,7 @@ Key combinations must consist of 2 or 3 keys: > From Firefox 135, users can assign the `F13` to `F19` keys to an extension using [Manage Extension Shortcuts](https://support.mozilla.org/en-US/kb/manage-extension-shortcuts-firefox). Your extension can't assign these keys from the manifest file. However, it can assign them using {{WebExtAPIRef("commands.update")}}. - `Comma`, `Period`, `Home`, `End`, `PageUp`, `PageDown`, `Space`, `Insert`, `Delete`, `Up`, `Down`, `Left`, `Right` -The key is then given as a string containing the set of key values, in the order listed above, separated by "`+`". For example, `"Ctrl+Shift+Z"`. +The key is then given as a string containing the set of key values, in the order listed above, separated by `+`. For example, `"Ctrl+Shift+Z"`. If a key combination is already used by the browser (like `"Ctrl+P"`) or by an existing add-on, then you can't override it. You can define it, but your event handler will not be called when the user presses the key combination. diff --git a/files/en-us/mozilla/add-ons/webextensions/manifest.json/content_scripts/index.md b/files/en-us/mozilla/add-ons/webextensions/manifest.json/content_scripts/index.md index 144ada5f4311380..ecb943f352adc21 100644 --- a/files/en-us/mozilla/add-ons/webextensions/manifest.json/content_scripts/index.md +++ b/files/en-us/mozilla/add-ons/webextensions/manifest.json/content_scripts/index.md @@ -37,15 +37,15 @@ browser-compat: webextensions.manifest.content_scripts </tbody> </table> -Instructs the browser to load [content scripts](/en-US/docs/Mozilla/Add-ons/WebExtensions/Content_scripts) into web pages whose URL matches a given pattern. +Instructs the browser to load [content scripts](/en-US/docs/Mozilla/Add-ons/WebExtensions/Content_scripts) into web pages whose URL matches a pattern. This key is an array. Each item is an object which: -- **must** contain a key named **`matches`**, which specifies the URL patterns to be matched in order for the scripts to be loaded; -- **may** contain keys named **`js`** and **`css`**, which list scripts and/or stylesheets to be loaded into matching pages; and -- **may** contain a number of other properties that control finer aspects of how and when content scripts are loaded. +- **must** contain a key named **`matches`**, which specifies the URL patterns to be matched for the scripts to be loaded; +- **may** contain keys named **`js`** and **`css`**, which list scripts and stylesheets to be loaded into matching pages; and +- **may** contain a number of other properties that control aspects of how and when content scripts are loaded. -Details of all the keys you can include are given in the table below. +This table details all the keys you can include. <table class="fullwidth-table standard-table"> <thead> @@ -100,12 +100,9 @@ Details of all the keys you can include are given in the table below. <td> <p> An array of paths, relative to <code>manifest.json</code>, referencing - CSS files that will be injected into matching pages. + CSS files to inject into matching pages. For information on the order + in which files are injected, see a <a href="#load_order">Load order</a>. </p> - <p> - Files are injected in the order given, and at the time specified by - <code><a href="#run_at">run_at</a></code - >. </p> <div class="notecard note"> <p> @@ -156,23 +153,8 @@ Details of all the keys you can include are given in the table below. <td> <p> An array of paths, relative to <code>manifest.json</code>, referencing - JavaScript files that will be injected into matching pages. - </p> - <p> - Files are injected in the order given. This means that, for example, - if you include jQuery here followed by another content script, like - this: - </p> - <pre class="brush: json"> -"js": ["jquery.js", "my-content-script.js"]</pre - > - <p>Then, <code>"my-content-script.js"</code> can use jQuery.</p> - <p> - The files are injected after any files in - <code><a href="#css">css</a></code - >, and at the time specified by - <code><a href="#run_at">run_at</a></code - >. + JavaScript files to inject into matching pages. For information on the + order in which files are injected, see a <a href="#load_order">Load order</a>. </p> </td> </tr> @@ -324,6 +306,46 @@ Details of all the keys you can include are given in the table below. </tbody> </table> +## Load order + +Registered objects in `content_scripts` are injected into matching web pages at the time specified by `run_at` (first `document_start`, then `document_end`, and finally `document_idle`): + +- In the order specified in the `content_scripts` array, for each object with a matching `run_at` value, then: + - CSS is applied in the order specified in its `css` array. + - JavaScript code is executed in the order specified in its `js` array. + +For example, in this key specification: + +```json +"content_scripts": [ + { + "matches": ["*://*.mozilla.org/*"], + "js": ["jquery.js", "my-content-script.js"], + "run_at": "document_idle" + }, + { + "matches": ["*://*.mozilla.org/*"], + "css": ["my-css.css"], + "js": ["another-content-script.js", "yet-another-content-script.js"], + "run_at": "document_idle" + }, + { + "matches": ["*://*.mozilla.org/*"], + "js": ["run-first.js"], + "run_at": "document_start" + } +] +``` + +The files are loaded like this when a mozilla.org domain opens: + +- `"run-first.js"` - because it's requested to run at `"document_start"`. +- `"jquery.js"` - because it's in the first array requesting run at `"document_idle"`. +- `"my-content-script.js"` - because it's the second item in the first array requesting run at `"document_idle"`. +- `"my-css.css"` - because an object's CSS is loaded before its JavaScript. +- `"another-content-script.js"` - because it's the first item in the `js` property. +- `"yet-another-content-script.js"` + ## Matching URL patterns The `"content_scripts"` key attaches content scripts to documents based on URL matching: if the document's URL matches the specification in the key, then the script will be attached. There are four properties inside `"content_scripts"` that you can use for this specification: diff --git a/files/en-us/mozilla/add-ons/webextensions/manifest.json/content_security_policy/index.md b/files/en-us/mozilla/add-ons/webextensions/manifest.json/content_security_policy/index.md index 7eef199b092c47e..ffbfe39277d7461 100644 --- a/files/en-us/mozilla/add-ons/webextensions/manifest.json/content_security_policy/index.md +++ b/files/en-us/mozilla/add-ons/webextensions/manifest.json/content_security_policy/index.md @@ -37,17 +37,17 @@ browser-compat: webextensions.manifest.content_security_policy </tbody> </table> -Extensions have a content security policy (CSP) applied to them by default. The default policy restricts the sources from which extensions can load code (such as [\<script>](/en-US/docs/Web/HTML/Element/script) resources) and disallows potentially unsafe practices such as the use of [`eval()`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/eval). See [Default content security policy](/en-US/docs/Mozilla/Add-ons/WebExtensions/Content_Security_Policy#default_content_security_policy) to learn more about the implications of this. +Extensions have a content security policy (CSP) applied to them by default. The default policy restricts the sources from which extensions can load code (such as [\<script>](/en-US/docs/Web/HTML/Reference/Elements/script) resources) and disallows potentially unsafe practices such as the use of [`eval()`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/eval). See [Default content security policy](/en-US/docs/Mozilla/Add-ons/WebExtensions/Content_Security_Policy#default_content_security_policy) to learn more about the implications of this. -You can use the `"content_security_policy"` manifest key to loosen or tighten the default policy. This key is specified in the same way as the Content-Security-Policy HTTP header. See [Using Content Security Policy](/en-US/docs/Web/HTTP/CSP) for a general description of CSP syntax. +You can use the `"content_security_policy"` manifest key to loosen or tighten the default policy. This key is specified in the same way as the Content-Security-Policy HTTP header. See [Using Content Security Policy](/en-US/docs/Web/HTTP/Guides/CSP) for a general description of CSP syntax. For example, you can use this key to: -- Restrict permitted sources for other types of content, such as images and stylesheets, using the appropriate [policy directive](/en-US/docs/Web/HTTP/Headers/Content-Security-Policy). +- Restrict permitted sources for other types of content, such as images and stylesheets, using the appropriate [policy directive](/en-US/docs/Web/HTTP/Reference/Headers/Content-Security-Policy). - Allow the extension to take advantage of [WebAssembly](/en-US/docs/WebAssembly) by including the `'wasm-unsafe-eval'` source in the `script-src` directive. - Loosen the default {{CSP("script-src")}} policies (Manifest V2 only): - Allow the extension to load scripts from outside its package by supplying their URL in the {{CSP("script-src")}} directive. - - Allow the extension to execute inline scripts by [supplying the hash of the script in the `script-src` directive](/en-US/docs/Web/HTTP/Headers/Content-Security-Policy/script-src#unsafe_inline_script). + - Allow the extension to execute inline scripts by [supplying the hash of the script in the `script-src` directive](/en-US/docs/Web/HTTP/Reference/Headers/Content-Security-Policy/script-src#unsafe_inline_script). - Allow the extension to use `eval()` and similar features by including `'unsafe-eval'` in the {{CSP("script-src")}} directive. There are restrictions on the policy you can specify with this manifest key: @@ -65,7 +65,7 @@ In Manifest V2, a source for a script directive is considered secure if it meets - Remote sources must not use wildcards for any domains in the [public suffix list](https://publicsuffix.org/list/) (so `*.co.uk` and `*.blogspot.com` are not allowed, although `*.foo.blogspot.com` is permitted). - All sources must specify a host. - The only permitted schemes for sources are `blob:`, `filesystem:`, `moz-extension:`, `https:`, and `wss:`. -- The only permitted [keywords](/en-US/docs/Web/HTTP/Headers/Content-Security-Policy#fetch_directive_syntax) are: `'none'`, `'self'`, `'unsafe-eval'`, and `'wasm-unsafe-eval'`. +- The only permitted [keywords](/en-US/docs/Web/HTTP/Reference/Headers/Content-Security-Policy#fetch_directive_syntax) are: `'none'`, `'self'`, `'unsafe-eval'`, and `'wasm-unsafe-eval'`. ## object-src directive @@ -167,7 +167,7 @@ Allow remote scripts from any subdomain of "jquery.com": - Manifest V3 does not allow remote URLs in `script-src` of `extension_pages`. -Allow [`eval()` and friends](/en-US/docs/Mozilla/Add-ons/WebExtensions/Content_Security_Policy#eval%28%29_and_friends): +Allow [`eval()` and friends](/en-US/docs/Mozilla/Add-ons/WebExtensions/Content_Security_Policy#eval_and_friends): - Manifest V2 diff --git a/files/en-us/mozilla/add-ons/webextensions/manifest.json/externally_connectable/index.md b/files/en-us/mozilla/add-ons/webextensions/manifest.json/externally_connectable/index.md index 7637c1a1fc8fca7..8316f34bf332a32 100644 --- a/files/en-us/mozilla/add-ons/webextensions/manifest.json/externally_connectable/index.md +++ b/files/en-us/mozilla/add-ons/webextensions/manifest.json/externally_connectable/index.md @@ -24,7 +24,7 @@ browser-compat: webextensions.manifest.externally_connectable <tr> <th scope="row">Example</th> <td> - <pre> + <pre class="brush: json"> "externally_connectable": { "ids": [ "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa", diff --git a/files/en-us/mozilla/add-ons/webextensions/manifest.json/host_permissions/index.md b/files/en-us/mozilla/add-ons/webextensions/manifest.json/host_permissions/index.md index c629185a4d484ba..e4e35549818d210 100644 --- a/files/en-us/mozilla/add-ons/webextensions/manifest.json/host_permissions/index.md +++ b/files/en-us/mozilla/add-ons/webextensions/manifest.json/host_permissions/index.md @@ -24,7 +24,7 @@ browser-compat: webextensions.manifest.host_permissions <tr> <th scope="row">Example</th> <td> - <pre class="brush: json;"> + <pre class="brush: json"> "host_permissions": [ "*://developer.mozilla.org/*", "*://*.example.org/*" diff --git a/files/en-us/mozilla/add-ons/webextensions/manifest.json/icons/index.md b/files/en-us/mozilla/add-ons/webextensions/manifest.json/icons/index.md index d4549d0fe024a37..284827fc3f60da2 100644 --- a/files/en-us/mozilla/add-ons/webextensions/manifest.json/icons/index.md +++ b/files/en-us/mozilla/add-ons/webextensions/manifest.json/icons/index.md @@ -24,49 +24,49 @@ browser-compat: webextensions.manifest.icons </tbody> </table> -The `icons` key specifies icons for your extension. Those icons will be used to represent the extension in components such as the Add-ons Manager. +The `icons` key specifies icons for your extension. Those icons represent the extension in components such as the add-ons manager (`about:addons`). -It consists of key-value pairs of image size in px and image path relative to the root directory of the extension. +The key consists of key-value pairs specifying the image size in pixels and the image path relative to the extension's root directory. -If `icons` is not supplied, a standard extension icon will be used by default. +If `icons` is not supplied, a standard extension icon is used. -You should supply at least a main extension icon, ideally 48x48 px in size. This is the default icon that will be used in the Add-ons Manager. You may, however, supply icons of any size and Firefox will attempt to find the best icon to display in different components. +You should supply an extension icon, ideally 32x32 px in size. This is the default icon that is used in the add-ons manager. You can supply icons of any size, and Firefox uses the one that fits a component best. -Firefox will consider the screen resolution when choosing an icon. To deliver the best visual experience to users with high-resolution displays, such as Retina displays, provide double-sized versions of all your icons. +Firefox considers the screen resolution when choosing an icon. To deliver the best visual experience to users with high-resolution displays, such as Retina displays, provide double-sized versions of your icons. ## Example -The keys in the `icons` object specify the icon size in px, values specify the relative icon path. This example contains a 48px extension icon and a larger version for high-resolution displays. +The keys in the `icons` object specify the icon size in pixels, and values specify the relative icon file path. This example contains a 32px extension icon and a larger version for high-resolution displays. ```json "icons": { - "48": "icon.png", - "96": "icon@2x.png" + "32": "icon.png", + "64": "icon@2x.png" } ``` ## SVG -You can use SVG and the browser will scale your icon appropriately. There are currently two caveats though: +You can use SVG, and the browser scales your icon appropriately. There are two caveats: -1. You need to specify a viewBox in the image. E.g.: +1. You need to specify a viewBox in the image, e.g.: ```html <svg xmlns="http://www.w3.org/2000/svg" - viewBox="0 0 48 48" - width="48" - height="48"> + viewBox="0 0 32 32" + width="32" + height="32"> <!-- your svg content --> </svg> ``` -2. Even though you can use one file, you still need to specify various size of the icon in your manifest. E.g.: +2. Even though you can use one SVG file, you need to specify icon sizes in your manifest, e.g.: ```json "icons": { - "48": "icon.svg", - "96": "icon.svg" + "32": "icon.svg", + "64": "icon.svg" } ``` @@ -74,10 +74,10 @@ You can use SVG and the browser will scale your icon appropriately. There are cu > Only Firefox is known to support SVG icons. Chromium has a bug about [unsupported SVG icons](https://crbug.com/29683). > [!NOTE] -> Remember to include the `xmlns` attribute when creating the SVG. Otherwise, Firefox won't be able to display the icon. +> Remember to include the `xmlns` attribute when creating the SVG. Otherwise, Firefox won't display the icon. > [!NOTE] -> If you are using a program like Inkscape for creating SVG, you might want to save it as a "plain SVG". Firefox might be confused by various special namespaces and not display your icon. +> When using a program such as Inkscape to create SVG, save your file as a "plain SVG". Firefox isn't guaranteed to handle special namespaces and may not display an icon containing them. ## Browser compatibility diff --git a/files/en-us/mozilla/add-ons/webextensions/manifest.json/index.md b/files/en-us/mozilla/add-ons/webextensions/manifest.json/index.md index 4a87e6b771dab3b..2e20b4f0b91c8da 100644 --- a/files/en-us/mozilla/add-ons/webextensions/manifest.json/index.md +++ b/files/en-us/mozilla/add-ons/webextensions/manifest.json/index.md @@ -14,7 +14,7 @@ The `manifest.json` file is the only file that every extension using WebExtensio Using `manifest.json`, you specify basic metadata about your extension such as the name and version, and can also specify aspects of your extension's functionality (such as background scripts, content scripts, and browser actions). -It is a [JSON](/en-US/docs/Glossary/JSON)-formatted file, with one exception: it is allowed to contain "`//`"-style comments. +It is a [JSON](/en-US/docs/Glossary/JSON)-formatted file, with one exception: it is allowed to contain `//`-style comments. ## List of manifest.json keys @@ -36,14 +36,14 @@ These are the `manifest.json` keys; these keys are available in Manifest V2 and - [developer](/en-US/docs/Mozilla/Add-ons/WebExtensions/manifest.json/developer) - [devtools_page](/en-US/docs/Mozilla/Add-ons/WebExtensions/manifest.json/devtools_page) - [dictionaries](/en-US/docs/Mozilla/Add-ons/WebExtensions/manifest.json/dictionaries) -- [externally_connectable](/en-US/docs/Mozilla/Add-ons/WebExtensions/manifest.json/externally_connectable) +- [externally_connectable](/en-US/docs/Mozilla/Add-ons/WebExtensions/manifest.json/externally_connectable) (Not supported in Firefox) - [homepage_url](/en-US/docs/Mozilla/Add-ons/WebExtensions/manifest.json/homepage_url) - [host_permissions](/en-US/docs/Mozilla/Add-ons/WebExtensions/manifest.json/host_permissions) (Manifest V3 and above) - [icons](/en-US/docs/Mozilla/Add-ons/WebExtensions/manifest.json/icons) - [incognito](/en-US/docs/Mozilla/Add-ons/WebExtensions/manifest.json/incognito) - [manifest_version](/en-US/docs/Mozilla/Add-ons/WebExtensions/manifest.json/manifest_version) - [name](/en-US/docs/Mozilla/Add-ons/WebExtensions/manifest.json/name) -- [offline_enabled](/en-US/docs/Mozilla/Add-ons/WebExtensions/manifest.json/offline_enabled) +- [offline_enabled](/en-US/docs/Mozilla/Add-ons/WebExtensions/manifest.json/offline_enabled) (Not supported in Firefox) - [omnibox](/en-US/docs/Mozilla/Add-ons/WebExtensions/manifest.json/omnibox) - [optional_host_permissions](/en-US/docs/Mozilla/Add-ons/WebExtensions/manifest.json/optional_host_permissions) (Manifest V3 and above) - [optional_permissions](/en-US/docs/Mozilla/Add-ons/WebExtensions/manifest.json/optional_permissions) @@ -51,12 +51,12 @@ These are the `manifest.json` keys; these keys are available in Manifest V2 and - [options_ui](/en-US/docs/Mozilla/Add-ons/WebExtensions/manifest.json/options_ui) - [page_action](/en-US/docs/Mozilla/Add-ons/WebExtensions/manifest.json/page_action) (Manifest V2 only in Chrome) - [permissions](/en-US/docs/Mozilla/Add-ons/WebExtensions/manifest.json/permissions) -- [protocol_handlers](/en-US/docs/Mozilla/Add-ons/WebExtensions/manifest.json/protocol_handlers) +- [protocol_handlers](/en-US/docs/Mozilla/Add-ons/WebExtensions/manifest.json/protocol_handlers) (Firefox only) - [short_name](/en-US/docs/Mozilla/Add-ons/WebExtensions/manifest.json/short_name) - [sidebar_action](/en-US/docs/Mozilla/Add-ons/WebExtensions/manifest.json/sidebar_action) -- [storage](/en-US/docs/Mozilla/Add-ons/WebExtensions/manifest.json/storage) +- [storage](/en-US/docs/Mozilla/Add-ons/WebExtensions/manifest.json/storage) (Not supported in Firefox) - [theme](/en-US/docs/Mozilla/Add-ons/WebExtensions/manifest.json/theme) -- [theme_experiment](/en-US/docs/Mozilla/Add-ons/WebExtensions/manifest.json/theme_experiment) +- [theme_experiment](/en-US/docs/Mozilla/Add-ons/WebExtensions/manifest.json/theme_experiment) (Firefox only) (experimental) - [user_scripts](/en-US/docs/Mozilla/Add-ons/WebExtensions/manifest.json/user_scripts) (Manifest V2 only) - [version](/en-US/docs/Mozilla/Add-ons/WebExtensions/manifest.json/version) - [version_name](/en-US/docs/Mozilla/Add-ons/WebExtensions/manifest.json/version_name) @@ -65,7 +65,7 @@ These are the `manifest.json` keys; these keys are available in Manifest V2 and ### Notes about manifest.json keys - `"manifest_version"`, `"version"`, and `"name"` are the only mandatory keys. -- `"default_locale"` must be present if the "`_locales`" directory is present, and must be absent otherwise. +- `"default_locale"` must be present if the `_locales` directory is present, and must be absent otherwise. - `"browser_specific_settings"` is not supported in Google Chrome. ### Accessing manifest.json keys at runtime @@ -163,8 +163,6 @@ For complete example extensions, see [Example extensions](/en-US/docs/Mozilla/Ad ## Browser compatibility -For a full overview of all manifest keys and their sub-keys, see the [full manifest.json browser compatibility table](/en-US/docs/Mozilla/Add-ons/WebExtensions/Browser_compatibility_for_manifest.json). - {{Compat}} ## See also diff --git a/files/en-us/mozilla/add-ons/webextensions/manifest.json/optional_host_permissions/index.md b/files/en-us/mozilla/add-ons/webextensions/manifest.json/optional_host_permissions/index.md index 77a579d3e8b5ebd..63b8829a9fde5b9 100644 --- a/files/en-us/mozilla/add-ons/webextensions/manifest.json/optional_host_permissions/index.md +++ b/files/en-us/mozilla/add-ons/webextensions/manifest.json/optional_host_permissions/index.md @@ -24,7 +24,7 @@ browser-compat: webextensions.manifest.optional_host_permissions <tr> <th scope="row">Example</th> <td> - <pre class="brush: json;"> + <pre class="brush: json"> "optional_host_permissions": [ "*://developer.mozilla.org/*", "*://*.example.org/*" diff --git a/files/en-us/mozilla/add-ons/webextensions/manifest.json/optional_permissions/index.md b/files/en-us/mozilla/add-ons/webextensions/manifest.json/optional_permissions/index.md index 8b39c0cc021933a..436b59870d2e01e 100644 --- a/files/en-us/mozilla/add-ons/webextensions/manifest.json/optional_permissions/index.md +++ b/files/en-us/mozilla/add-ons/webextensions/manifest.json/optional_permissions/index.md @@ -86,6 +86,7 @@ The optional API permissions are: - `search` - `sessions` - `tabHide` +- `tabGroups` - `tabs` - `topSites` - 'userScripts' ([optional-only](#optional-only_permissions)) @@ -102,6 +103,7 @@ These optional permissions are granted silently, without a user prompt: - `activeTab` - `cookies` - `idle` +- `tabGroups` - `webRequest` - `webRequestBlocking` - `webRequestFilterResponse` diff --git a/files/en-us/mozilla/add-ons/webextensions/manifest.json/options_page/index.md b/files/en-us/mozilla/add-ons/webextensions/manifest.json/options_page/index.md index 0c5215d4e98a718..9550ea08c0d50f2 100644 --- a/files/en-us/mozilla/add-ons/webextensions/manifest.json/options_page/index.md +++ b/files/en-us/mozilla/add-ons/webextensions/manifest.json/options_page/index.md @@ -2,8 +2,6 @@ title: options_page slug: Mozilla/Add-ons/WebExtensions/manifest.json/options_page page-type: webextension-manifest-key -status: - - deprecated browser-compat: webextensions.manifest.options_page --- @@ -26,7 +24,7 @@ browser-compat: webextensions.manifest.options_page <tr> <th scope="row">Example</th> <td> - <pre class="brush: json;">"options_page": "options/options.html"</pre> + <pre class="brush: json">"options_page": "options/options.html"</pre> </td> </tr> </tbody> diff --git a/files/en-us/mozilla/add-ons/webextensions/manifest.json/options_ui/index.md b/files/en-us/mozilla/add-ons/webextensions/manifest.json/options_ui/index.md index beeaa7e12138192..b6d5d39d9465ca1 100644 --- a/files/en-us/mozilla/add-ons/webextensions/manifest.json/options_ui/index.md +++ b/files/en-us/mozilla/add-ons/webextensions/manifest.json/options_ui/index.md @@ -24,7 +24,7 @@ browser-compat: webextensions.manifest.options_ui <tr> <th scope="row">Example</th> <td> - <pre class="brush: json;"> + <pre class="brush: json"> "options_ui": { "page": "options/options.html" }</pre @@ -77,7 +77,7 @@ The `options_ui` key is an object with the following contents: </ul> <div class="notecard warning"> <p> - Do not set <code>browser_style</code> to true: its not support in Manifest V3 from Firefox 118. See <a href="/en-US/docs/Mozilla/Add-ons/WebExtensions/user_interface/Browser_styles#manifest_v3_migration">Manifest V3 migration for <code>browser_style</code></a>. + Do not set <code>browser_style</code> to true: it's not supported in Manifest V3, from Firefox 118. See <a href="/en-US/docs/Mozilla/Add-ons/WebExtensions/user_interface/Browser_styles#manifest_v3_migration">Manifest V3 migration for <code>browser_style</code></a>. </p> </div> <p> diff --git a/files/en-us/mozilla/add-ons/webextensions/manifest.json/page_action/index.md b/files/en-us/mozilla/add-ons/webextensions/manifest.json/page_action/index.md index b39c74fac9464c0..baa02fd6a49e5c4 100644 --- a/files/en-us/mozilla/add-ons/webextensions/manifest.json/page_action/index.md +++ b/files/en-us/mozilla/add-ons/webextensions/manifest.json/page_action/index.md @@ -45,7 +45,7 @@ Your extension may optionally also supply an associated popup whose content is s You must specify this key to include a page action in your extension. When specified, you can manipulate the button programmatically using the {{WebExtAPIRef("pageAction")}} API. -If you supply a popup, then the popup is opened when the user clicks the icon, and your JavaScript running in the popup can handle the user's interaction with it. If you don't supply a popup, then a click event is dispatched to your extension's [background scripts](/en-US/docs/Mozilla/Add-ons/WebExtensions/Anatomy_of_a_WebExtension#background_pages) when the user clicks the icon. +If you supply a popup, then the popup is opened when the user clicks the icon, and your JavaScript running in the popup can handle the user's interaction with it. If you don't supply a popup, then a click event is dispatched to your extension's [background scripts](/en-US/docs/Mozilla/Add-ons/WebExtensions/Anatomy_of_a_WebExtension#background_scripts) when the user clicks the icon. Page actions are like browser actions, except that they are associated with particular web pages rather than with the browser as a whole. If an action is only relevant on certain pages, then you should use a page action and display it only on relevant pages. If an action is relevant to all pages or to the browser itself, use a browser action. @@ -135,29 +135,29 @@ The `page_action` key is an object that may have any of three properties, all op <p> The HTML file may include CSS and JavaScript files using <code - ><a href="/en-US/docs/Web/HTML/Element/link">&#x3C;link></a></code + ><a href="/en-US/docs/Web/HTML/Reference/Elements/link">&#x3C;link></a></code > and <code - ><a href="/en-US/docs/Web/HTML/Element/script" + ><a href="/en-US/docs/Web/HTML/Reference/Elements/script" >&#x3C;script></a ></code > elements, just like a normal web page. However, don't use <code - ><a href="/en-US/docs/Web/HTML/Element/script" + ><a href="/en-US/docs/Web/HTML/Reference/Elements/script" >&#x3C;script></a ></code > with embedded code, because you'll get a Content Violation Policy error. Instead, <code - ><a href="/en-US/docs/Web/HTML/Element/script" + ><a href="/en-US/docs/Web/HTML/Reference/Elements/script" >&#x3C;script></a ></code > must use the - <code><a href="/en-US/docs/Web/HTML/Element/script">src</a></code> + <code><a href="/en-US/docs/Web/HTML/Reference/Elements/script">src</a></code> attribute to load a separate script file. </p> <p> diff --git a/files/en-us/mozilla/add-ons/webextensions/manifest.json/permissions/index.md b/files/en-us/mozilla/add-ons/webextensions/manifest.json/permissions/index.md index 2a1c670f9840d42..0c035d164dd3889 100644 --- a/files/en-us/mozilla/add-ons/webextensions/manifest.json/permissions/index.md +++ b/files/en-us/mozilla/add-ons/webextensions/manifest.json/permissions/index.md @@ -24,7 +24,7 @@ browser-compat: webextensions.manifest.permissions <tr> <th scope="row">Example</th> <td> - <pre class="brush: json;"> + <pre class="brush: json"> "permissions": [ "webRequest" ]</pre @@ -127,6 +127,7 @@ These permissions are available in Manifest V2 and above unless otherwise noted: - `search` - `sessions` - `storage` +- `tabGroups` - `tabHide` - `tabs` - `theme` @@ -171,7 +172,7 @@ The intention of this permission is to enable extensions to fulfill a common use For example, consider an extension that wants to run a script in the current page when the user clicks a browser action. If the `activeTab` permission did not exist, the extension would need to ask for the host permission `<all_urls>`. But this gives the extension more power than it needs: it could now execute scripts in _any tab_, _any time_ it likes, instead of just the active tab and only in response to a user action. > [!NOTE] -> You can only get access to the tab/data that was there, when the user interaction occurred (e.g. the click). When the active tab navigates away (e.g., due to finishing loading or some other event), the permission does not grant you access to the tab anymore. +> You can only get access to the tab/data that was there, when the user interaction occurred (e.g., the click). When the active tab navigates away (e.g., due to finishing loading or some other event), the permission does not grant you access to the tab anymore. The `activeTab` permission enables scripting access to the top level tab's page and same origin frames. Running scripts or modifying styles inside [cross-origin](/en-US/docs/Web/Security/Same-origin_policy#cross-origin_network_access) frames may require additional [host permissions](#host_permissions). Of course, [restrictions and limitations](/en-US/docs/Mozilla/Add-ons/WebExtensions/Content_scripts#permissions_restrictions_and_limitations) related to particular sites and URI schemes are applied as well. diff --git a/files/en-us/mozilla/add-ons/webextensions/manifest.json/sidebar_action/index.md b/files/en-us/mozilla/add-ons/webextensions/manifest.json/sidebar_action/index.md index 76a08a4633b2708..b06904a72efc3f2 100644 --- a/files/en-us/mozilla/add-ons/webextensions/manifest.json/sidebar_action/index.md +++ b/files/en-us/mozilla/add-ons/webextensions/manifest.json/sidebar_action/index.md @@ -140,11 +140,11 @@ The `sidebar_action` key is an object that may have any of the properties listed <p> The HTML file may include CSS and JavaScript files using <code - ><a href="/en-US/docs/Web/HTML/Element/link">&#x3C;link></a></code + ><a href="/en-US/docs/Web/HTML/Reference/Elements/link">&#x3C;link></a></code > and <code - ><a href="/en-US/docs/Web/HTML/Element/script" + ><a href="/en-US/docs/Web/HTML/Reference/Elements/script" >&#x3C;script></a ></code > diff --git a/files/en-us/mozilla/add-ons/webextensions/manifest.json/theme/index.md b/files/en-us/mozilla/add-ons/webextensions/manifest.json/theme/index.md index 036b399d92eae64..c2f759c75a8f938 100644 --- a/files/en-us/mozilla/add-ons/webextensions/manifest.json/theme/index.md +++ b/files/en-us/mozilla/add-ons/webextensions/manifest.json/theme/index.md @@ -151,7 +151,7 @@ Images should be 200 pixels high to ensure they always fill the header space ver </tr> <tr> <td><code>additional_backgrounds</code></td> - <td><code>Array </code>of <code>String</code></td> + <td><code>Array</code> of <code>String</code></td> <td> <div class="warning"> <p> @@ -207,7 +207,7 @@ All these properties can be specified as either a string containing any valid [C > In Firefox for Android colors can be specified using: > > - full hexadecimal notation, that is #RRGGBB only. _alpha_ and shortened syntax, as in #RGB\[A], are not supported. -> - [Functional notation](/en-US/docs/Web/CSS/color_value#rgb_syntax_variations) (RGB arrays) for themes targeting Firefox 68.2 or later. +> - [Functional notation](/en-US/docs/Web/CSS/color_value) (RGB arrays) for themes targeting Firefox 68.2 or later. > > Colors for Firefox for Android themes cannot be specified using color names. @@ -237,7 +237,7 @@ All these properties can be specified as either a string containing any valid [C </p> <p> Where <code>icons</code> isn't defined, also ensure good contrast - with<code> button_background_active</code> and + with <code>button_background_active</code> and <code>button_background_hover</code>. </p> </div> diff --git a/files/en-us/mozilla/add-ons/webextensions/manifest.json/web_accessible_resources/index.md b/files/en-us/mozilla/add-ons/webextensions/manifest.json/web_accessible_resources/index.md index efcb6809a9ee9b4..98555efcc679ca8 100644 --- a/files/en-us/mozilla/add-ons/webextensions/manifest.json/web_accessible_resources/index.md +++ b/files/en-us/mozilla/add-ons/webextensions/manifest.json/web_accessible_resources/index.md @@ -41,7 +41,7 @@ Sometimes you want to package resources—for example, images, HTML, CSS, or Jav > [!NOTE] > Until Firefox 105, extensions could access resources packaged in other extensions by default. From Firefox 105 onwards, to enable other extensions to access an extension's resources they must be included in this key. -For example, the [Beastify example extension](https://github.com/mdn/webextensions-examples/tree/main/beastify) replaces a web page with an image of a beast selected by the user. The beast images are packaged with the extension. To make the selected image visible, the extension adds [`<img>`](/en-US/docs/Web/HTML/Element/img) elements whose `src` attribute points to the beast's image. For the web page to be able to load the images, they must be made web accessible. +For example, the [Beastify example extension](https://github.com/mdn/webextensions-examples/tree/main/beastify) replaces a web page with an image of a beast selected by the user. The beast images are packaged with the extension. To make the selected image visible, the extension adds [`<img>`](/en-US/docs/Web/HTML/Reference/Elements/img) elements whose `src` attribute points to the beast's image. For the web page to be able to load the images, they must be made web accessible. With the `web_accessible_resources` key, you list all the packaged resources that you want to make available to web pages. You specify them as paths relative to the manifest.json file. @@ -149,7 +149,7 @@ my-extension-files/ my-image.png ``` -To enable a web page to use an [`<img>`](/en-US/docs/Web/HTML/Element/img) element whose `src` attribute points to this image, you would specify `web_accessible_resources` like this: +To enable a web page to use an [`<img>`](/en-US/docs/Web/HTML/Reference/Elements/img) element whose `src` attribute points to this image, you would specify `web_accessible_resources` like this: ```json "web_accessible_resources": ["images/my-image.png"] @@ -188,7 +188,7 @@ This approach gives you the correct URL regardless of the browser your extension If you make a page web-accessible, any website may link or redirect to that page. The page should then treat any input (POST data, for example) as if it came from an untrusted source, just as a normal web page should. -Web-accessible extension resources are not blocked by [CORS](/en-US/docs/Web/HTTP/CORS) or [CSP](/en-US/docs/Web/HTTP/CSP). Because of this ability to bypass security checks, extensions should avoid using web-accessible scripts when possible. A web-accessible extension script can unexpectedly be misused by malicious websites to weaken the security of other websites. Follow the [security best practices](https://extensionworkshop.com/documentation/develop/build-a-secure-extension/) by avoiding injection of moz-extension:-URLs in web pages and ensuring that third-party libraries are up to date. +Web-accessible extension resources are not blocked by [CORS](/en-US/docs/Web/HTTP/Guides/CORS) or [CSP](/en-US/docs/Web/HTTP/Guides/CSP). Because of this ability to bypass security checks, extensions should avoid using web-accessible scripts when possible. A web-accessible extension script can unexpectedly be misused by malicious websites to weaken the security of other websites. Follow the [security best practices](https://extensionworkshop.com/documentation/develop/build-a-secure-extension/) by avoiding injection of moz-extension:-URLs in web pages and ensuring that third-party libraries are up to date. ## Example diff --git a/files/en-us/mozilla/add-ons/webextensions/match_patterns/index.md b/files/en-us/mozilla/add-ons/webextensions/match_patterns/index.md index 0edb0e73cf65c97..eb2e57b6f50bb5a 100644 --- a/files/en-us/mozilla/add-ons/webextensions/match_patterns/index.md +++ b/files/en-us/mozilla/add-ons/webextensions/match_patterns/index.md @@ -360,11 +360,11 @@ The special value `<all_urls>` matches all URLs under any of the supported schem </tr> <tr> <td><code>*://*</code></td> - <td>Empty path: this should be "<code>*://*/*</code>".</td> + <td>Empty path: this should be <code>*://*/*</code>.</td> </tr> <tr> <td><code>file://*</code></td> - <td>Empty path: this should be "<code>file:///*</code>".</td> + <td>Empty path: this should be <code>file:///*</code>.</td> </tr> </tbody> </table> diff --git a/files/en-us/mozilla/add-ons/webextensions/modify_a_web_page/index.md b/files/en-us/mozilla/add-ons/webextensions/modify_a_web_page/index.md index ef447d518c42763..f47672e580626ea 100644 --- a/files/en-us/mozilla/add-ons/webextensions/modify_a_web_page/index.md +++ b/files/en-us/mozilla/add-ons/webextensions/modify_a_web_page/index.md @@ -135,7 +135,7 @@ Content scripts and background scripts can't directly access each other's state. <td> <code ><a - href="/en-US/docs/Mozilla/Add-ons/WebExtensions/API/runtime#sendmessage()" + href="/en-US/docs/Mozilla/Add-ons/WebExtensions/API/runtime/sendMessage" >browser.runtime.sendMessage()</a ></code > @@ -162,7 +162,7 @@ Content scripts and background scripts can't directly access each other's state. <td> <code ><a - href="/en-US/docs/Mozilla/Add-ons/WebExtensions/API/runtime#onmessage" + href="/en-US/docs/Mozilla/Add-ons/WebExtensions/API/runtime/onMessage" >browser.runtime.onMessage</a ></code > diff --git a/files/en-us/mozilla/add-ons/webextensions/native_manifests/index.md b/files/en-us/mozilla/add-ons/webextensions/native_manifests/index.md index 8ecce8778be53b9..8b8c8c501bcefc5 100644 --- a/files/en-us/mozilla/add-ons/webextensions/native_manifests/index.md +++ b/files/en-us/mozilla/add-ons/webextensions/native_manifests/index.md @@ -350,7 +350,7 @@ browser.pkcs11.installModule("my_module"); On Linux and macOS, you need to store the manifest in a particular place. On Windows, you need to create a registry key that points to the manifest's location. -The detailed rules are the same for all the manifest types, except that the penultimate component of the path identifies the type of manifest. The examples below show the form for each of the three different types. In all the examples, `<name>` is the value of the `name` property in the manifest. +The detailed rules are the same for all the manifest types, except that the penultimate component of the path identifies the type of manifest. The examples below show the form for each of the three different types. In all the examples, `<name>` is the value of the name property in the native manifest. ### Windows diff --git a/files/en-us/mozilla/add-ons/webextensions/native_messaging/index.md b/files/en-us/mozilla/add-ons/webextensions/native_messaging/index.md index ae59e5444af615f..e912c27da8d5a6e 100644 --- a/files/en-us/mozilla/add-ons/webextensions/native_messaging/index.md +++ b/files/en-us/mozilla/add-ons/webextensions/native_messaging/index.md @@ -25,7 +25,7 @@ Support for native messaging in extensions is mostly compatible with Chrome, wit - The app manifest lists `allowed_extensions` as an array of app IDs, while Chrome lists `allowed_origins`, as an array of `"chrome-extension"` URLs. - The app manifest is stored in a different location [compared to Chrome](https://developer.chrome.com/docs/apps/nativeMessaging/#native-messaging-host-location). -There's a complete example in the ["`native-messaging`" directory](https://github.com/mdn/webextensions-examples/tree/main/native-messaging) of the `"webextensions-examples"` repository on GitHub. Most example code in this article is taken from that example. +There's a complete example in the [`native-messaging` directory](https://github.com/mdn/webextensions-examples/tree/main/native-messaging) of the `webextensions-examples` repository on GitHub. Most example code in this article is taken from that example. ## Setup @@ -396,7 +396,7 @@ If you haven't managed to run the application, you should see an error message g - Check that the name passed to `runtime.connectNative()` matches the name in the app manifest - macOS/Linux: check that name of the app manifest is `<name>.json`. -- macOS/Linux: check the native application's manifest file location as mentioned [here](/en-US/docs/Mozilla/Add-ons/WebExtensions/Native_manifests#mac_os_x). +- macOS/Linux: check the native application's manifest file location as mentioned [in the native manifests reference](/en-US/docs/Mozilla/Add-ons/WebExtensions/Native_manifests#macos). - Windows: check that the registry key is in the correct place, and that its name matches the name in the app manifest. - Windows: check that the path given in the registry key points to the app manifest. diff --git a/files/en-us/mozilla/add-ons/webextensions/sharing_objects_with_page_scripts/index.md b/files/en-us/mozilla/add-ons/webextensions/sharing_objects_with_page_scripts/index.md index 468fe029d670ed3..b6193fefb3fa309 100644 --- a/files/en-us/mozilla/add-ons/webextensions/sharing_objects_with_page_scripts/index.md +++ b/files/en-us/mozilla/add-ons/webextensions/sharing_objects_with_page_scripts/index.md @@ -251,10 +251,8 @@ Reflect.defineProperty( ev.wrappedJSObject, "propC", { - get: exportFunction(() => { - // getters must be exported like regular functions - return "propC"; - }, window), + // getters must be exported like regular functions + get: exportFunction(() => "propC", window), }, ); diff --git a/files/en-us/mozilla/add-ons/webextensions/user_interface/browser_styles/index.md b/files/en-us/mozilla/add-ons/webextensions/user_interface/browser_styles/index.md index da87ddc5e20f954..5b9444cb45f63b8 100644 --- a/files/en-us/mozilla/add-ons/webextensions/user_interface/browser_styles/index.md +++ b/files/en-us/mozilla/add-ons/webextensions/user_interface/browser_styles/index.md @@ -47,7 +47,7 @@ Most styles are automatically applied, but some elements require you to add the <tr> <td> <code - ><a href="/en-US/docs/Web/HTML/Element/button">&#x3C;button></a></code + ><a href="/en-US/docs/Web/HTML/Reference/Elements/button">&#x3C;button></a></code > </td> <td> @@ -60,7 +60,7 @@ Most styles are automatically applied, but some elements require you to add the <td> <p> <code - ><a href="/en-US/docs/Web/HTML/Element/select" + ><a href="/en-US/docs/Web/HTML/Reference/Elements/select" >&#x3C;select></a ></code > @@ -79,7 +79,7 @@ Most styles are automatically applied, but some elements require you to add the <tr> <td> <code - ><a href="/en-US/docs/Web/HTML/Element/textarea" + ><a href="/en-US/docs/Web/HTML/Reference/Elements/textarea" >&#x3C;textarea></a ></code > @@ -94,7 +94,7 @@ Most styles are automatically applied, but some elements require you to add the <td> Parent of an <code - ><a href="/en-US/docs/Web/HTML/Element/input">&#x3C;input></a></code + ><a href="/en-US/docs/Web/HTML/Reference/Elements/input">&#x3C;input></a></code > </td> <td> diff --git a/files/en-us/mozilla/add-ons/webextensions/user_interface/context_menu_items/index.md b/files/en-us/mozilla/add-ons/webextensions/user_interface/context_menu_items/index.md index efbd200734b5508..d613a547ad32604 100644 --- a/files/en-us/mozilla/add-ons/webextensions/user_interface/context_menu_items/index.md +++ b/files/en-us/mozilla/add-ons/webextensions/user_interface/context_menu_items/index.md @@ -56,7 +56,7 @@ browser.contextMenus.onClicked.addListener((info, tab) => { ## Icons -For details on how to create icons to use with your context menu, see [Iconography](https://acorn.firefox.com/latest/styles/iconography-q7JqGl5H) in the [Acorn Design System](https://acorn.firefox.com/latest) documentation. +For details on how to create icons to use with your context menu, see [Iconography](https://acorn.firefox.com/latest/styles/iconography/overview-QEDMXQqj) in the [Acorn Design System](https://acorn.firefox.com/latest) documentation. ## Examples diff --git a/files/en-us/mozilla/add-ons/webextensions/user_interface/devtools_panels/index.md b/files/en-us/mozilla/add-ons/webextensions/user_interface/devtools_panels/index.md index 3b2ff00f9118654..3ae98f679886cc2 100644 --- a/files/en-us/mozilla/add-ons/webextensions/user_interface/devtools_panels/index.md +++ b/files/en-us/mozilla/add-ons/webextensions/user_interface/devtools_panels/index.md @@ -62,7 +62,7 @@ For details on how to design your developer panel's web page to match the style ## Icons -For details on how to create icons to use with your developer tools panel, see [Iconography](https://acorn.firefox.com/latest/styles/iconography-q7JqGl5H) in the [Acorn Design System](https://acorn.firefox.com/latest) documentation. +For details on how to create icons to use with your developer tools panel, see [Iconography](https://acorn.firefox.com/latest/styles/iconography/overview-QEDMXQqj) in the [Acorn Design System](https://acorn.firefox.com/latest) documentation. ## Examples diff --git a/files/en-us/mozilla/add-ons/webextensions/user_interface/extension_pages/index.md b/files/en-us/mozilla/add-ons/webextensions/user_interface/extension_pages/index.md index 3f216e672f05824..cf7a940afcf3d03 100644 --- a/files/en-us/mozilla/add-ons/webextensions/user_interface/extension_pages/index.md +++ b/files/en-us/mozilla/add-ons/webextensions/user_interface/extension_pages/index.md @@ -66,7 +66,7 @@ function onVisited(historyItem) { browser.history.onVisited.addListener(onVisited); ``` -To use the history API, you must request the "`history`" [permission](/en-US/docs/Mozilla/Add-ons/WebExtensions/manifest.json/permissions) in your [`manifest.json`](/en-US/docs/Mozilla/Add-ons/WebExtensions/manifest.json) file. +To use the history API, you must request the `"history"` [permission](/en-US/docs/Mozilla/Add-ons/WebExtensions/manifest.json/permissions) in your [`manifest.json`](/en-US/docs/Mozilla/Add-ons/WebExtensions/manifest.json) file. ## Web page design diff --git a/files/en-us/mozilla/add-ons/webextensions/user_interface/notifications/index.md b/files/en-us/mozilla/add-ons/webextensions/user_interface/notifications/index.md index 6d009a5f21aafed..46ba4ab88a324eb 100644 --- a/files/en-us/mozilla/add-ons/webextensions/user_interface/notifications/index.md +++ b/files/en-us/mozilla/add-ons/webextensions/user_interface/notifications/index.md @@ -45,7 +45,7 @@ If you are issuing calls to action through notifications, you will also want to ## Icons -For details on how to create icons to use with your notification, see [Iconography](https://acorn.firefox.com/latest/styles/iconography-q7JqGl5H) in the [Acorn Design System](https://acorn.firefox.com/latest) documentation. +For details on how to create icons to use with your notification, see [Iconography](https://acorn.firefox.com/latest/styles/iconography/overview-QEDMXQqj) in the [Acorn Design System](https://acorn.firefox.com/latest) documentation. ## Examples diff --git a/files/en-us/mozilla/add-ons/webextensions/user_interface/page_actions/index.md b/files/en-us/mozilla/add-ons/webextensions/user_interface/page_actions/index.md index db7d690f6731e82..4c504352b1ae510 100644 --- a/files/en-us/mozilla/add-ons/webextensions/user_interface/page_actions/index.md +++ b/files/en-us/mozilla/add-ons/webextensions/user_interface/page_actions/index.md @@ -85,7 +85,7 @@ You can change any of the page action properties programmatically using the [`pa ## Icons -For details on how to create icons to use with your page action, see [Iconography](https://acorn.firefox.com/latest/styles/iconography-q7JqGl5H) in the [Acorn Design System](https://acorn.firefox.com/latest) documentation. +For details on how to create icons to use with your page action, see [Iconography](https://acorn.firefox.com/latest/styles/iconography/overview-QEDMXQqj) in the [Acorn Design System](https://acorn.firefox.com/latest) documentation. ## Examples diff --git a/files/en-us/mozilla/add-ons/webextensions/user_interface/popups/index.md b/files/en-us/mozilla/add-ons/webextensions/user_interface/popups/index.md index 016ef562272f445..4b6af9a0cdc5301 100644 --- a/files/en-us/mozilla/add-ons/webextensions/user_interface/popups/index.md +++ b/files/en-us/mozilla/add-ons/webextensions/user_interface/popups/index.md @@ -12,7 +12,7 @@ A popup is a dialog that's associated with a [toolbar button](/en-US/docs/Mozill When the user clicks the button, the popup is shown. When the user clicks anywhere outside the popup, the popup is closed. The popup can be closed programmatically by calling [`window.close()`](/en-US/docs/Web/API/Window/close) from a script running in the popup. However, you can't open the popup programmatically from an extension's JavaScript; it can be opened only in response to a user action. -You can define a keyboard shortcut that opens the popup using the `"_execute_browser_action"` and `"_execute_page_action"` shortcuts in Manifest V2 and `"_execute_action"`and, where supported, `"_execute_page_action"` shortcuts in Manifest V3. See the documentation for the special shortcuts in manifest.json key [`commands`](/en-US/docs/Mozilla/Add-ons/WebExtensions/manifest.json/commands#special_shortcuts). +You can define a keyboard shortcut that opens the popup using the `"_execute_browser_action"` and `"_execute_page_action"` shortcuts in Manifest V2 and `"_execute_action"` and, where supported, `"_execute_page_action"` shortcuts in Manifest V3. See the documentation for the special shortcuts in manifest.json key [`commands`](/en-US/docs/Mozilla/Add-ons/WebExtensions/manifest.json/commands#special_shortcuts). ## Specifying a popup @@ -40,9 +40,9 @@ You can debug a popup's markup and JavaScript using the Add-on Debugger, but you Popups resize automatically to fit their content. The algorithm for this may differ from one browser to another. -In Firefox, the size is calculated just before the popup is shown, and at most 10 times per second after DOM mutations. For strict mode documents, the size is calculated based on the layout size of the [`<body>`](/en-US/docs/Web/HTML/Element/body) element. For quirks mode, it's the [`<html>`](/en-US/docs/Web/HTML/Element/html) element. Firefox calculates the preferred width of the contents of that element, reflows it to that width, and then resizes so there's no vertical scrolling. It will grow to a size of **800x600 pixels** at most if that fits on the user's screen. (Prior to Firefox 60 [it was only 680px](https://bugzil.la/1434177).) If the user [moves the extension's button to the menu](https://support.mozilla.org/en-US/kb/customize-firefox-controls-buttons-and-toolbars#w_customize-the-menu-or-the-toolbar) or it appears in the toolbar overflow, then the popup appears inside the menu's panel and is given a fixed width. +In Firefox, the size is calculated just before the popup is shown, and at most 10 times per second after DOM mutations. For strict mode documents, the size is calculated based on the layout size of the [`<body>`](/en-US/docs/Web/HTML/Reference/Elements/body) element. For quirks mode, it's the [`<html>`](/en-US/docs/Web/HTML/Reference/Elements/html) element. Firefox calculates the preferred width of the contents of that element, reflows it to that width, and then resizes so there's no vertical scrolling. It will grow to a size of **800x600 pixels** at most if that fits on the user's screen. (Prior to Firefox 60 [it was only 680px](https://bugzil.la/1434177).) If the user [moves the extension's button to the menu](https://support.mozilla.org/en-US/kb/customize-firefox-controls-buttons-and-toolbars#w_customize-the-menu-or-the-toolbar) or it appears in the toolbar overflow, then the popup appears inside the menu's panel and is given a fixed width. -When setting the popup `width` in CSS, you should set it in the [`<body>`](/en-US/docs/Web/HTML/Element/body) and not in the `:root`. +When setting the popup `width` in CSS, you should set it in the [`<body>`](/en-US/docs/Web/HTML/Reference/Elements/body) and not in the `:root`. In Firefox Android 57, the popup is shown as a normal page in a new tab. diff --git a/files/en-us/mozilla/add-ons/webextensions/user_interface/toolbar_button/index.md b/files/en-us/mozilla/add-ons/webextensions/user_interface/toolbar_button/index.md index 76ce45ae152c25f..90cfec3544c4707 100644 --- a/files/en-us/mozilla/add-ons/webextensions/user_interface/toolbar_button/index.md +++ b/files/en-us/mozilla/add-ons/webextensions/user_interface/toolbar_button/index.md @@ -41,7 +41,7 @@ You can change many of the browser action properties programmatically using the ## Icons -For details on how to create icons to use with your browser action, see [Iconography](https://acorn.firefox.com/latest/styles/iconography-q7JqGl5H) in the [Acorn Design System](https://acorn.firefox.com/latest) documentation. +For details on how to create icons to use with your browser action, see [Iconography](https://acorn.firefox.com/latest/styles/iconography/overview-QEDMXQqj) in the [Acorn Design System](https://acorn.firefox.com/latest) documentation. ## Examples diff --git a/files/en-us/mozilla/add-ons/webextensions/what_next/index.md b/files/en-us/mozilla/add-ons/webextensions/what_next/index.md index 57b46cbd95f5674..5c0bea3f8912ef1 100644 --- a/files/en-us/mozilla/add-ons/webextensions/what_next/index.md +++ b/files/en-us/mozilla/add-ons/webextensions/what_next/index.md @@ -8,7 +8,7 @@ page-type: guide You'll now be ready to start turning your idea for a browser extension into reality. Before you start that journey, it's worth being aware of a few things that will help to make it a smooth one. -You can find more about many of the things discussed on this page on [Extension Workshop](https://extensionworkshop.com), a website dedicated to helping you write, test, publish, and distribute extensions for Firefox. +You can find more about many of the things discussed on this page on [Extension Workshop](https://extensionworkshop.com/), a website dedicated to helping you write, test, publish, and distribute extensions for Firefox. ## Your development environment diff --git a/files/en-us/mozilla/add-ons/webextensions/work_with_contextual_identities/index.md b/files/en-us/mozilla/add-ons/webextensions/work_with_contextual_identities/index.md index 11967061d4abf68..12754e06396754f 100644 --- a/files/en-us/mozilla/add-ons/webextensions/work_with_contextual_identities/index.md +++ b/files/en-us/mozilla/add-ons/webextensions/work_with_contextual_identities/index.md @@ -12,7 +12,7 @@ To address this need, Firefox includes a feature known as contextual identities, For more background on this feature, see: -- [Put your multiple online personalities in Firefox Multi-Account Containers](https://blog.mozilla.org/en/products/firefox/introducing-firefox-multi-account-containers/) +- [Put your multiple online personalities in Firefox Multi-Account Containers](https://blog.mozilla.org/en/firefox/introducing-firefox-multi-account-containers/) - [Security/Contextual Identity Project/Containers](https://wiki.mozilla.org/Security/Contextual_Identity_Project/Containers) - [Firefox support article on containers](https://support.mozilla.org/en-US/kb/containers?redirectlocale=en-US&as=u&redirectslug=containers-experiment&utm_source=inproduct) @@ -102,48 +102,48 @@ It then checks whether the contextual identities feature is turned on in the bro ```js if (browser.contextualIdentities === undefined) { - div.innerText = 'browser.contextualIdentities not available. Check that the privacy.userContext.enabled pref is set to true, and reload the add-on.'; + div.innerText = + "browser.contextualIdentities not available. Check that the privacy.userContext.enabled pref is set to true, and reload the add-on."; } else { ``` Firefox installs with the contextual identity feature turned off. It's turned on when an extension using the `contextualIdentities` API is installed. However, the user can turn the feature off using an option on the preferences page (about:preferences), hence the need for the check. -The script now uses {{WebExtAPIRef("contextualIdentities.query.")}} to determine whether any contextual identities are defined in the browser. If there are none, a message is added to the popup and the script stops. +The script now uses {{WebExtAPIRef("contextualIdentities.query")}} to determine whether any contextual identities are defined in the browser. If there are none, a message is added to the popup and the script stops. ```js - browser.contextualIdentities.query({}) - .then((identities) => { - if (!identities.length) { - div.innerText = 'No identities returned from the API.'; - return; - } + browser.contextualIdentities.query({}).then((identities) => { + if (!identities.length) { + div.innerText = "No identities returned from the API."; + return; + } ``` If there are contextual identities present—Firefox comes with four default identities—the script loops through each one adding its name, styled in its chosen color, to the `<div>` element. The function `createOptions()` then adds the options to "create" or "close all" to the `<div>` before it's added to the popup. ```js - for (const identity of identities) { - const row = document.createElement('div'); - const span = document.createElement('span'); - span.className = 'identity'; - span.innerText = identity.name; - span.style = `color: ${identity.color}`; - console.log(identity); - row.appendChild(span); - createOptions(row, identity); - div.appendChild(row); - } + for (const identity of identities) { + const row = document.createElement("div"); + const span = document.createElement("span"); + span.className = "identity"; + span.innerText = identity.name; + span.style = `color: ${identity.color}`; + console.log(identity); + row.appendChild(span); + createOptions(row, identity); + div.appendChild(row); + } }); } function createOptions(node, identity) { - for (const option of ['Create', 'Close All']) { - const a = document.createElement('a'); - a.href = '#'; + for (const option of ["Create", "Close All"]) { + const a = document.createElement("a"); + a.href = "#"; a.innerText = option; - a.dataset.action = option.toLowerCase().replace(' ', '-'); + a.dataset.action = option.toLowerCase().replace(" ", "-"); a.dataset.identity = identity.cookieStoreId; - a.addEventListener('click', eventHandler); + a.addEventListener("click", eventHandler); node.appendChild(a); } } @@ -169,12 +169,14 @@ if (event.target.dataset.action === "create") { If the user selects the option to close all tabs for the identity, the script performs a {{WebExtAPIRef("tabs.query")}} to get all the tabs using the identity's cookie store. The script then passes this list of tabs to {{WebExtAPIRef("tabs.remove")}}. ```js - if (event.target.dataset.action === 'close-all') { - browser.tabs.query({ - cookieStoreId: event.target.dataset.identity - }).then((tabs) => { - browser.tabs.remove(tabs.map((i) => i.id)); - }); + if (event.target.dataset.action === "close-all") { + browser.tabs + .query({ + cookieStoreId: event.target.dataset.identity, + }) + .then((tabs) => { + browser.tabs.remove(tabs.map((i) => i.id)); + }); } event.preventDefault(); } diff --git a/files/en-us/mozilla/add-ons/webextensions/work_with_the_bookmarks_api/index.md b/files/en-us/mozilla/add-ons/webextensions/work_with_the_bookmarks_api/index.md index 269b17c5c93ab22..6ddddf30b1f8ccf 100644 --- a/files/en-us/mozilla/add-ons/webextensions/work_with_the_bookmarks_api/index.md +++ b/files/en-us/mozilla/add-ons/webextensions/work_with_the_bookmarks_api/index.md @@ -145,7 +145,7 @@ function isSupportedProtocol(urlString) { If the protocol is one supported by bookmarks, the extension determines if the tab's URL is already bookmarked and if it is, calls `updateIcon()`: ```js - let searching = browser.bookmarks.search({url: currentTab.url}); + let searching = browser.bookmarks.search({ url: currentTab.url }); searching.then((bookmarks) => { currentBookmark = bookmarks[0]; updateIcon(); diff --git a/files/en-us/mozilla/add-ons/webextensions/work_with_the_cookies_api/index.md b/files/en-us/mozilla/add-ons/webextensions/work_with_the_cookies_api/index.md index 7df18e408163e4d..b783f27975654cd 100644 --- a/files/en-us/mozilla/add-ons/webextensions/work_with_the_cookies_api/index.md +++ b/files/en-us/mozilla/add-ons/webextensions/work_with_the_cookies_api/index.md @@ -136,8 +136,8 @@ It then loops through all the buttons assigning them their image and creating an ```js for (let i = 0; i < bgBtns.length; i++) { - let imgName = bgBtns[i].getAttribute('class'); - let bgImg = 'url(\'images/' + imgName + '.png\')'; + let imgName = bgBtns[i].getAttribute("class"); + let bgImg = `url('images/${imgName}.png')`; bgBtns[i].style.backgroundImage = bgImg; bgBtns[i].onclick = (e) => { @@ -157,11 +157,12 @@ browser.cookies.set({ The color setting is handled in a similar way, triggered by a listener on the color input field. When a color is entered the active tab is discovered and the color selection details sent, using a message, to the page's content script to be applied to the web page background. Then the color selection is added to the cookie: ```js - cookieVal.color = currColor; - browser.cookies.set({ - url: tabs[0].url, - name: "bgpicker", - value: JSON.stringify(cookieVal) +cookieVal.color = currColor; +browser.cookies.set({ + url: tabs[0].url, + name: "bgpicker", + value: JSON.stringify(cookieVal), +}); ``` When the user clicks the reset button, which has been assigned to the variable reset: @@ -173,11 +174,11 @@ let reset = document.querySelector(".color-reset button"); `reset.onclick` first finds the active tab. Then, using the tab's ID it passes a message to the page's content script ([updatebg.js](https://github.com/mdn/webextensions-examples/blob/main/cookie-bg-picker/content_scripts/updatebg.js)) to get it to remove the icon and color from the page. The function then clears the cookie values (so the old values aren't carried forward and written onto a cookie created for a new icon or color selection on the same page) before removing the cookie: ```js - cookieVal = { image : '', - color : '' }; - browser.cookies.remove({ - url: tabs[0].url, - name: "bgpicker" +cookieVal = { image: "", color: "" }; +browser.cookies.remove({ + url: tabs[0].url, + name: "bgpicker", +}); ``` Also, so you can see what is going on with the cookies, the script reports on all changes to cookies in the console: diff --git a/files/en-us/mozilla/add-ons/webextensions/working_with_files/index.md b/files/en-us/mozilla/add-ons/webextensions/working_with_files/index.md index 5d4ebcf38aecc28..0a09ca3c82bfa28 100644 --- a/files/en-us/mozilla/add-ons/webextensions/working_with_files/index.md +++ b/files/en-us/mozilla/add-ons/webextensions/working_with_files/index.md @@ -31,7 +31,7 @@ You can let the user download to a location of their choice by specifying the `s The downloads API also provides features to cancel, pause, resume, erase, and remove downloads; search for downloaded files in the download manager; show downloaded files in the computer's file manager; and open a file in an associated application. -To use this API, you need to have the `"downloads"` [API permission](/en-US/docs/Web/API/Permissions#api_permissions) specified in your [`manifest.json`](/en-US/docs/Mozilla/Add-ons/WebExtensions/manifest.json) file. +To use this API, you need to have the `"downloads"` [API permission](/en-US/docs/Mozilla/Add-ons/WebExtensions/manifest.json/permissions#api_permissions) specified in your [`manifest.json`](/en-US/docs/Mozilla/Add-ons/WebExtensions/manifest.json) file. Example: [Latest download](https://github.com/mdn/webextensions-examples/tree/main/latest-download) API reference: [downloads API](/en-US/docs/Mozilla/Add-ons/WebExtensions/API/downloads) @@ -42,7 +42,7 @@ If you want to work with a file from the user's computer one option is to let th Example: [Imagify](https://github.com/mdn/webextensions-examples/tree/main/imagify) Guide: [Using files from web applications](/en-US/docs/Web/API/File_API/Using_files_from_web_applications) -API references: [HTML input element](/en-US/docs/Web/HTML/Element/input/file) | [DOM File API](/en-US/docs/Web/API/File) +API references: [HTML input element](/en-US/docs/Web/HTML/Reference/Elements/input/file) | [DOM File API](/en-US/docs/Web/API/File) > [!NOTE] > If you want to access or process all the files in a selected folder, you can do so using `<input type="file" webkitdirectory="true"/>` to select the folder and return all the files it contains. diff --git a/files/en-us/mozilla/add-ons/webextensions/working_with_the_tabs_api/index.md b/files/en-us/mozilla/add-ons/webextensions/working_with_the_tabs_api/index.md index ccc2a4fbaceaedf..7f98cf6992b5a86 100644 --- a/files/en-us/mozilla/add-ons/webextensions/working_with_the_tabs_api/index.md +++ b/files/en-us/mozilla/add-ons/webextensions/working_with_the_tabs_api/index.md @@ -154,13 +154,13 @@ To start with: ```js function listTabs() { - getCurrentWindowTabs().then((tabs) => { - const tabsList = document.getElementById('tabs-list'); + getCurrentWindowTabs().then((tabs) => { + const tabsList = document.getElementById("tabs-list"); const currentTabs = document.createDocumentFragment(); const limit = 5; let counter = 0; - tabsList.textContent = ''; + tabsList.textContent = ""; ``` Next, we'll create the links for each tab: @@ -204,7 +204,7 @@ else if (e.target.id === "tabs-alert-info") { callOnActiveTab((tab) => { let props = ""; for (const item in tab) { - props += `${ item } = ${ tab[item] } \n`; + props += `${item} = ${tab[item]} \n`; } alert(props); }); @@ -224,7 +224,7 @@ document.addEventListener("click", (e) => { } }); } -} +}); ``` ## Creating, duplicating, moving, updating, reloading, and removing tabs @@ -399,13 +399,13 @@ Let's take a look at how the zoom in is implemented. else if (e.target.id === "tabs-add-zoom") { callOnActiveTab((tab) => { browser.tabs.getZoom(tab.id).then((zoomFactor) => { - //the maximum zoomFactor is 5, it can't go higher + // The maximum zoomFactor is 5, it can't go higher if (zoomFactor >= MAX_ZOOM) { alert("Tab zoom factor is already at max!"); } else { let newZoomFactor = zoomFactor + ZOOM_INCREMENT; - //if the newZoomFactor is set to higher than the max accepted - //it won't change, and will never alert that it's at maximum + // If the newZoomFactor is set to higher than the max accepted + // it won't change, and will never alert that it's at maximum newZoomFactor = newZoomFactor > MAX_ZOOM ? MAX_ZOOM : newZoomFactor; browser.tabs.setZoom(tab.id, newZoomFactor); } diff --git a/files/en-us/mozilla/add-ons/webextensions/your_first_webextension/index.md b/files/en-us/mozilla/add-ons/webextensions/your_first_webextension/index.md index 2d421b2828d7814..5999a9532726a21 100644 --- a/files/en-us/mozilla/add-ons/webextensions/your_first_webextension/index.md +++ b/files/en-us/mozilla/add-ons/webextensions/your_first_webextension/index.md @@ -9,7 +9,7 @@ page-type: guide > [!NOTE] > If you're familiar with the basic concepts of browser extensions, skip this section to [see how extension files are put together](/en-US/docs/Mozilla/Add-ons/WebExtensions/Anatomy_of_a_WebExtension). Then, use the [reference documentation](/en-US/docs/Mozilla/Add-ons/WebExtensions#reference) to start building your extension. Visit [Firefox Extension Workshop](https://extensionworkshop.com/?utm_source=developer.mozilla.org&utm_medium=documentation&utm_campaign=your-first-extension) to learn more about the workflow for testing, publishing, and extensions for Firefox. -This article walks through creating an extension for Firefox, from start to finish. The extension adds a red border to any pages loaded from "`mozilla.org`" or any of its subdomains. +This article walks through creating an extension for Firefox, from start to finish. The extension adds a red border to any pages loaded from `mozilla.org` or any of its subdomains. The source code for this example is on GitHub: <https://github.com/mdn/webextensions-examples/tree/main/borderify>. @@ -120,16 +120,16 @@ Alternatively, you can run the extension from the command line using the [web-ex ### Testing > [!NOTE] -> By default [extensions don't work in private browsing](https://support.mozilla.org/en-US/kb/extensions-private-browsing). If you want to test this extension in private browsing open "`about:addons`", click on the extension, and select the Allow radio button for Run in Private Windows. +> By default [extensions don't work in private browsing](https://support.mozilla.org/en-US/kb/extensions-private-browsing). If you want to test this extension in private browsing open `about:addons`, click on the extension, and select the Allow radio button for Run in Private Windows. -Now visit a page under "`https://www.mozilla.org/en-US/`", and you should see the red border round the page. +Now visit a page under `https://www.mozilla.org/en-US/`, and you should see the red border round the page. ![Border displayed on mozilla.org](border_on_mozilla_org.png) > [!NOTE] -> Don't try it on "`addons.mozilla.org`", though! Content scripts are currently blocked on that domain. +> Don't try it on `addons.mozilla.org`, though! Content scripts are currently blocked on that domain. -Try experimenting a bit. Edit the content script to change the color of the border, or do something else to the page content. Save the content script, then reload the extension's files by clicking the Reload button in "`about:debugging`". You can see the changes right away. +Try experimenting a bit. Edit the content script to change the color of the border, or do something else to the page content. Save the content script, then reload the extension's files by clicking the Reload button in `about:debugging`. You can see the changes right away. - [Learn more about loading extensions](https://extensionworkshop.com/documentation/develop/temporary-installation-in-firefox/) diff --git a/files/en-us/mozilla/add-ons/webextensions/your_second_webextension/index.md b/files/en-us/mozilla/add-ons/webextensions/your_second_webextension/index.md index c45d283787cf5bc..78b987bbf17f108 100644 --- a/files/en-us/mozilla/add-ons/webextensions/your_second_webextension/index.md +++ b/files/en-us/mozilla/add-ons/webextensions/your_second_webextension/index.md @@ -160,7 +160,7 @@ The HTML file looks like this: </html> ``` -We have a [`<div>`](/en-US/docs/Web/HTML/Element/div) element with an ID of `"popup-content"` that contains a button for each animal choice and a reset button. We have another `<div>` with an ID of `"error-content"` and a class `"hidden"`. We'll use that in case there's a problem initializing the popup. +We have a [`<div>`](/en-US/docs/Web/HTML/Reference/Elements/div) element with an ID of `"popup-content"` that contains a button for each animal choice and a reset button. We have another `<div>` with an ID of `"error-content"` and a class `"hidden"`. We'll use that in case there's a problem initializing the popup. Note that we include the CSS and JS files from this file, just like a web page. @@ -320,7 +320,7 @@ If executing the content script is successful, we call `listenForClicks()`. This - If the click was not on a button in the popup, we ignore it and do nothing. - If the click was on a button with `type="reset"`, then we call `reset()`. -- If the click was on any other button (i.e. the beast buttons), then we call `beastify()`. +- If the click was on any other button (i.e., the beast buttons), then we call `beastify()`. The `beastify()` function does three things: @@ -391,7 +391,7 @@ The first thing the content script does is to check for a global variable `windo After that, the place to start is line 40, where the content script listens for messages from the popup, using the [`browser.runtime.onMessage`](/en-US/docs/Mozilla/Add-ons/WebExtensions/API/runtime/onMessage) API. We saw above that the popup script can send two different sorts of messages: "beastify" and "reset". -- if the message is "beastify", we expect it to contain a URL pointing to a beast image. We remove any beasts that might have been added by previous "beastify" calls, then construct and append an [`<img>`](/en-US/docs/Web/HTML/Element/img) element whose `src` attribute is set to the beast URL. +- if the message is "beastify", we expect it to contain a URL pointing to a beast image. We remove any beasts that might have been added by previous "beastify" calls, then construct and append an [`<img>`](/en-US/docs/Web/HTML/Reference/Elements/img) element whose `src` attribute is set to the beast URL. - if the message is "reset", we just remove any beasts that might have been added. ### The beasts diff --git a/files/en-us/mozilla/firefox/experimental_features/index.md b/files/en-us/mozilla/firefox/experimental_features/index.md index 7dfffcf8749868b..8f83951fd3dab0c 100644 --- a/files/en-us/mozilla/firefox/experimental_features/index.md +++ b/files/en-us/mozilla/firefox/experimental_features/index.md @@ -62,7 +62,7 @@ Layout for `input type="search"` has been updated. This causes a search field to ### Toggle password display -HTML password input elements ([`<input type="password">`](/en-US/docs/Web/HTML/Element/input/password)) include an "eye" icon that can be toggled to display or obscure the password text ([Firefox bug 502258](https://bugzil.la/502258)). +HTML password input elements ([`<input type="password">`](/en-US/docs/Web/HTML/Reference/Elements/input/password)) include an "eye" icon that can be toggled to display or obscure the password text ([Firefox bug 502258](https://bugzil.la/502258)). <table> <thead> @@ -289,8 +289,8 @@ The [@scope](/en-US/docs/Web/CSS/@scope) [CSS](/en-US/docs/Web/CSS) [at-rule](/e <tbody> <tr> <th>Nightly</th> - <td>128</td> - <td>No</td> + <td>137</td> + <td>Yes</td> </tr> <tr> <th>Developer Edition</th> @@ -574,7 +574,7 @@ Specifically, this preference will disable the following prefixed properties: ### UA styles for `<h1>` nested in sectioning elements -The `<h1>` heading doesn't decrease in font size now when nested within [sectioning elements](/en-US/docs/Web/HTML/Content_categories#sectioning_content) `<article>`, `<aside>`, `<nav>`, and `<section>`. The UA styles for `<h1>` nested within sectioning elements are no longer relevant since the outline algorithm [has been removed](https://github.com/whatwg/html/pull/7829) from the HTML specification. ([Firefox bug 1883896](https://bugzil.la/1883896)). +The `<h1>` heading doesn't decrease in font size now when nested within [sectioning elements](/en-US/docs/Web/HTML/Guides/Content_categories#sectioning_content) `<article>`, `<aside>`, `<nav>`, and `<section>`. The UA styles for `<h1>` nested within sectioning elements are no longer relevant since the outline algorithm [has been removed](https://github.com/whatwg/html/pull/7829) from the HTML specification. ([Firefox bug 1883896](https://bugzil.la/1883896)). > [!NOTE] > The preference for this feature works in reverse: it's set to `false` in the Nightly build, which removes the UA styling for headings nested in sectioning elements. It's set to `true` in all other channels, which retains the existing UA styling for the nested headings. @@ -619,7 +619,7 @@ The `<h1>` heading doesn't decrease in font size now when nested within [section ### `shape()` function -The CSS [`shape()`](/en-US/docs/Web/CSS/basic-shape/shape) function is a [`<basic-shape>`](/en-US/docs/Web/CSS/basic-shape) data type that enables you to define a shape in the {{cssxref("clip-path")}} and {{cssxref("offset-path")}} properties using one or more "shape commands". These commands are very similar to the [SVG path commands](/en-US/docs/Web/SVG/Attribute/d#path_commands). The `shape()` function is similar in some respects to the `{{cssxref("basic-shape/path","path()")}}` function, but unlike `path()`, which uses the [SVG path](/en-US/docs/Web/SVG/Element/path) syntax, `shape()` uses standard CSS syntax. This enables you to easily create and edit shapes and also allows the use of CSS math functions. +The CSS [`shape()`](/en-US/docs/Web/CSS/basic-shape/shape) function is a [`<basic-shape>`](/en-US/docs/Web/CSS/basic-shape) data type that enables you to define a shape in the {{cssxref("clip-path")}} and {{cssxref("offset-path")}} properties using one or more "shape commands". These commands are very similar to the [SVG path commands](/en-US/docs/Web/SVG/Reference/Attribute/d#path_commands). The `shape()` function is similar in some respects to the {{cssxref("basic-shape/path","path()")}} function, but unlike `path()`, which uses the [SVG path](/en-US/docs/Web/SVG/Reference/Element/path) syntax, `shape()` uses standard CSS syntax. This enables you to easily create and edit shapes and also allows the use of CSS math functions. For more details, see [Firefox bug 1823463](https://bugzil.la/1823463) for the `shape()` function support in `clip-path`, [Firefox bug 1884424](https://bugzil.la/1884424) for the function's support in `offset-path`, and [Firefox bug 1884425](https://bugzil.la/1884425) for its interpolation support. <table> @@ -784,9 +784,9 @@ The parts that have been implemented include: </tbody> </table> -### `hyphenate-limit-chars` property +### `::details-content` pseudo-element -The {{CSSXRef("hyphenate-limit-chars")}} CSS property is used to specifically the minimum word length for hyphenation as well as the number of characters before and after the hyphen. ([Firefox bug 1521723](https://bugzil.la/1521723)). +The CSS {{cssxref("::details-content")}} pseudo-element enables you to style the content of the {{htmlElement("details")}} element ([Firefox bug 1901037](https://bugzil.la/1901037)). <table> <thead> @@ -799,27 +799,71 @@ The {{CSSXRef("hyphenate-limit-chars")}} CSS property is used to specifically th <tbody> <tr> <th>Nightly</th> - <td>136</td> - <td>Yes</td> + <td>138</td> + <td>No</td> </tr> <tr> <th>Developer Edition</th> - <td>136</td> + <td>138</td> <td>No</td> </tr> <tr> <th>Beta</th> - <td>136</td> + <td>138</td> <td>No</td> </tr> <tr> <th>Release</th> - <td>136</td> + <td>138</td> <td>No</td> </tr> <tr> <th>Preference name</th> - <td colspan="2"><code>layout.css.hyphenate-limit-chars.enabled</code></td> + <td colspan="2"><code>layout.css.details-content.enabled</code></td> + </tr> + </tbody> +</table> + +### Allow pseudo-elements after element-backed pseudo-elements + +Work has started on allowing [pseudo-elements](/en-US/docs/Web/CSS/Pseudo-elements) such as {{cssxref("::first-letter")}} and {{cssxref("::before")}} to be appended to [element-backed pseudo-elements](/en-US/docs/Web/CSS/Pseudo-elements#element-backed_pseudo-elements) such as {{cssxref("::details-content")}} and {{cssxref("::file-selector-button")}}. + +This will allow users to, for , example, style the first letter of the {{htmlElement("details")}} element by using the CSS selector `::details-content::first-letter` or add content before an {{HTMLElement("input") }} of [`type="file"`](/en-US/docs/Web/HTML/Reference/Elements/input/file) using the CSS selector `::file-selector-button::before`. + +Currently only support for `::details-content::first-letter` can be parsed, using `@supports(::details-content::first-letter)` and the preference for [::details-content pseudo-element](#details-content_pseudo-element) needs enabling for this to be tested. The `::file-selector-button` pseudo-element is not yet marked as an element-based pseudo-element so there is no current way of testing this. ([Firefox bug 1953557](https://bugzil.la/1953557)). + +<table> + <thead> + <tr> + <th>Release channel</th> + <th>Version added</th> + <th>Enabled by default?</th> + </tr> + </thead> + <tbody> + <tr> + <th>Nightly</th> + <td>138</td> + <td>No</td> + </tr> + <tr> + <th>Developer Edition</th> + <td>138</td> + <td>No</td> + </tr> + <tr> + <th>Beta</th> + <td>138</td> + <td>No</td> + </tr> + <tr> + <th>Release</th> + <td>138</td> + <td>No</td> + </tr> + <tr> + <th>Preference name</th> + <td colspan="2"><code>layout.css.details-content.enabled</code></td> </tr> </tbody> </table> @@ -832,21 +876,11 @@ None. ### Temporal API -The [Temporal object](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Temporal) aims to simplify working with dates and times in various scenarios, with built-in time zone and calendar representations ([Firefox bug 1912511](https://bugzil.la/1912511)). -This includes: - -- A **duration** (difference between two time points): {{jsxref("Temporal.Duration")}} -- **Points in time**: - - As a unique instant in history: - - A timestamp: {{jsxref("Temporal.Instant")}} - - A date-time with a time zone: {{jsxref("Temporal.ZonedDateTime")}} - - **Time-zone-unaware date/time ("Plain")**: - - Date (year, month, day) + time (hour, minute, second, millisecond, nanosecond): {{jsxref("Temporal.PlainDateTime")}} - - Date (year, month, day): {{jsxref("Temporal.PlainDate")}} - - Year, month: {{jsxref("Temporal.PlainYearMonth")}} - - Month, day: {{jsxref("Temporal.PlainMonthDay")}} - - Time (hour, minute, second, millisecond, nanosecond): {{jsxref("Temporal.PlainTime")}} -- **Now** (current time) as various class instances, or in a specific format: {{jsxref("Temporal.Now")}} +The `withCalendar()` method for [`PlainDate`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Temporal/PlainDate/withCalendar), [`PlainDateTime`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Temporal/PlainDateTime/withCalendar), and [`ZonedDateTime`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Temporal/ZonedDateTime/withCalendar) objects within the [Temporal object](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Temporal) currently have the following [`calendar` types](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/supportedValuesOf#supported_calendar_types) disabled in all versions other than Firefox Nightly ([Firefox bug 1912511](https://bugzil.la/1912511) and [Firefox bug 1954138](https://bugzil.la/1954138)): + +- `islamic` +- `islamic-rgsa` +- `islamic-umalqura` <table> <thead> @@ -859,36 +893,37 @@ This includes: <tbody> <tr> <th>Nightly</th> - <td>135</td> - <td>No</td> + <td>139</td> + <td>Yes</td> </tr> <tr> <th>Developer Edition</th> - <td>—</td> - <td>—</td> + <td>137</td> + <td>No</td> </tr> <tr> <th>Beta</th> - <td>—</td> - <td>—</td> + <td>137</td> + <td>No</td> </tr> <tr> <th>Release</th> - <td>—</td> - <td>—</td> + <td>137</td> + <td>No</td> </tr> <tr> <th>Preference name</th> - <td colspan="2"><code>javascript.options.experimental.temporal</code></td> + <td colspan="2">N/A</td> </tr> </tbody> </table> -### Error.captureStackTrace +### Atomics -The {{jsxref("Error.captureStackTrace()")}} static method installs stack trace information on a provided object as the {{jsxref("Error.stack")}} property. -Its main use case is to install a stack trace on a custom error object that does not derive from the {{jsxref("Error")}} interface. -([Firefox bug 1886820](https://bugzil.la/1886820)). +#### Atomics.waitAsync() + +The {{jsxref("Atomics.waitAsync()")}} static method waits asynchronously on a shared memory location and returns an object representing the result of the operation. +It is non-blocking and usable on the main thread. ([Firefox bug 1467846](https://bugzil.la/1467846)). <table> <thead> @@ -901,27 +936,27 @@ Its main use case is to install a stack trace on a custom error object that does <tbody> <tr> <th>Nightly</th> - <td>136</td> + <td>140</td> <td>No</td> </tr> <tr> <th>Developer Edition</th> - <td>136</td> + <td>140</td> <td>No</td> </tr> <tr> <th>Beta</th> - <td>136</td> + <td>140</td> <td>No</td> </tr> <tr> <th>Release</th> - <td>136</td> + <td>140</td> <td>No</td> </tr> <tr> <th>Preference name</th> - <td colspan="2"><code>javascript.options.experimental.error_capture_stack_trace</code></td> + <td colspan="2"><code>javascript.options.atomics_wait_async</code></td> </tr> </tbody> </table> @@ -984,7 +1019,7 @@ This subset of the API has been implemented: - {{domxref("TrustedTypePolicyFactory")}}: - {{domxref("TrustedTypePolicyFactory/getAttributeType", "getAttributeType()")}} and {{domxref("TrustedTypePolicyFactory/getPropertyType", "getPropertyType()")}} ([Firefox bug 1917783](https://bugzil.la/1917783), [Firefox bug 1917784](https://bugzil.la/1917784)). - The {{domxref("Document.write()", "write()")}} and {{domxref("Document.writeln()","writeln()")}} methods of the {{domxref("Document")}} interface now accept {{domxref("TrustedHTML")}} objects as parameters, in addition to strings. ([Firefox bug 1906301](https://bugzil.la/1906301)). -- The {{domxref("HTMLScriptElement.text","text")}}, {{domxref("HTMLScriptElement.innerText","innerText")}}, and {{domxref("HTMLScriptElement.textContent","textContent")}} properties of the {{domxref("HTMLScriptElement")}} interface now accept {{domxref("TrustedScript")}} objects a value, while {{domxref("HTMLScriptElement.src", "src")}} accepts {{domxref("TrustedScriptURL")}} values. ([Firefox bug 1905706](https://bugzil.la/1905706)). +- The {{domxref("HTMLScriptElement.text","text")}}, {{domxref("HTMLElement.innerText","innerText")}}, and {{domxref("Node.textContent","textContent")}} properties of the {{domxref("HTMLScriptElement")}} interface now accept {{domxref("TrustedScript")}} objects a value, while {{domxref("HTMLScriptElement.src", "src")}} accepts {{domxref("TrustedScriptURL")}} values. ([Firefox bug 1905706](https://bugzil.la/1905706)). - The {{domxref("Window.setInterval()")}} and {{domxref("Window.setTimeout()")}} methods can be called with a {{domxref("TrustedScript")}}. ([Firefox bug 1931290](https://bugzil.la/1931290)). - The global [`trustedTypes`](/en-US/docs/Web/API/Window/trustedTypes) property is available for accessing the Trusted Types API. - The properties {{domxref("Element.innerHTML")}} and {{domxref("ShadowRoot.innerHTML")}} can be called with [trusted types](/en-US/docs/Web/API/Trusted_Types_API). @@ -1025,6 +1060,252 @@ This subset of the API has been implemented: </tbody> </table> +### HTML Sanitizer API + +The [HTML Sanitizer API](/en-US/docs/Web/API/HTML_Sanitizer_API) allow developers to take untrusted strings of HTML and sanitize them for safe insertion into a document's DOM. + +<table> + <thead> + <tr> + <th>Release channel</th> + <th>Version added</th> + <th>Enabled by default?</th> + </tr> + </thead> + <tbody> + <tr> + <th>Nightly</th> + <td>138</td> + <td>No</td> + </tr> + <tr> + <th>Developer Edition</th> + <td>138</td> + <td>No</td> + </tr> + <tr> + <th>Beta</th> + <td>138</td> + <td>No</td> + </tr> + <tr> + <th>Release</th> + <td>138</td> + <td>No</td> + </tr> + <tr> + <th>Preference name</th> + <td colspan="2"><code>dom.security.sanitizer.enabled</code></td> + </tr> + </tbody> +</table> + +### `closedBy` attribute for `<dialog>` + +The {{domxref("HTMLDialogElement/closedBy", "closedBy")}} attribute of the {{domxref("HTMLDialogElement")}} interface, and corresponding [`closedby`](/en-US/docs/Web/HTML/Reference/Elements/dialog#closedby) attribute of the {{htmlelement("dialog")}} element, are supported. +These can be used by developers to specify whether users can close a dialog by clicking outside of the dialog area, or the dialog must be closed programmatically, and so on. +([Firefox bug 1964077](https://bugzil.la/1964077)). + +<table> + <thead> + <tr> + <th>Release channel</th> + <th>Version added</th> + <th>Enabled by default?</th> + </tr> + </thead> + <tbody> + <tr> + <th>Nightly</th> + <td>140</td> + <td>Yes</td> + </tr> + <tr> + <th>Developer Edition</th> + <td>140</td> + <td>No</td> + </tr> + <tr> + <th>Beta</th> + <td>140</td> + <td>No</td> + </tr> + <tr> + <th>Release</th> + <td>140</td> + <td>No</td> + </tr> + <tr> + <th>Preference name</th> + <td colspan="2"><code>dom.dialog.light-dismiss.enabled</code></td> + </tr> + </tbody> +</table> + +### Removal of MutationEvent + +{{domxref("MutationEvent")}} and its associated events (`DOMSubtreeModified`, `DOMNodeInserted`, `DOMNodeRemoved`, `DOMCharacterDataModified`, `DOMAttrModified`) are on the path for removal, and have been disabled on nightly. +([Firefox bug 1951772](https://bugzil.la/1951772)). + +<table> + <thead> + <tr> + <th>Release channel</th> + <th>Version added</th> + <th>Enabled by default?</th> + </tr> + </thead> + <tbody> + <tr> + <th>Nightly</th> + <td>138</td> + <td>No</td> + </tr> + <tr> + <th>Developer Edition</th> + <td>138</td> + <td>Yes</td> + </tr> + <tr> + <th>Beta</th> + <td>138</td> + <td>Yes</td> + </tr> + <tr> + <th>Release</th> + <td>138</td> + <td>Yes</td> + </tr> + <tr> + <th>Preference name</th> + <td colspan="2"><code>dom.mutation_events.enabled</code></td> + </tr> + </tbody> +</table> + +### Removal of `beforescriptexecute` and `afterscriptexecute` events + +The non-standard events [`beforescriptexecute`](/en-US/docs/Web/API/Document/beforescriptexecute_event) and [`afterscriptexecute`](/en-US/docs/Web/API/Document/afterscriptexecute_event) on the {{domxref("Document")}} interface, and [`afterscriptexecute`](/en-US/docs/Web/API/Element/afterscriptexecute_event) and [`beforescriptexecute`](/en-US/docs/Web/API/Element/beforescriptexecute_event) on the {{domxref("Element")}} interface are on the path to removal. They have been disabled in Nightly. +([Firefox bug 1954685](https://bugzil.la/1954685)). + +<table> + <thead> + <tr> + <th>Release channel</th> + <th>Version added</th> + <th>Enabled by default?</th> + </tr> + </thead> + <tbody> + <tr> + <th>Nightly</th> + <td>139</td> + <td>No</td> + </tr> + <tr> + <th>Developer Edition</th> + <td>139</td> + <td>Yes</td> + </tr> + <tr> + <th>Beta</th> + <td>139</td> + <td>Yes</td> + </tr> + <tr> + <th>Release</th> + <td>139</td> + <td>Yes</td> + </tr> + <tr> + <th>Preference name</th> + <td colspan="2"><code>dom.events.script_execute.enable</code></td> + </tr> + </tbody> +</table> + +### PerformanceEventTiming.interactionId + +{{domxref("PerformanceEventTiming.interactionId")}} can be used to measure latency timing for events triggered by a particular user interaction. ([Firefox bug 1934683](https://bugzil.la/1934683)). + +<table> + <thead> + <tr> + <th>Release channel</th> + <th>Version added</th> + <th>Enabled by default?</th> + </tr> + </thead> + <tbody> + <tr> + <th>Nightly</th> + <td>138</td> + <td>No</td> + </tr> + <tr> + <th>Developer Edition</th> + <td>138</td> + <td>No</td> + </tr> + <tr> + <th>Beta</th> + <td>138</td> + <td>No</td> + </tr> + <tr> + <th>Release</th> + <td>138</td> + <td>No</td> + </tr> + <tr> + <th>Preference name</th> + <td colspan="2"><code>dom.performance.event_timing.enable_interactionid</code></td> + </tr> + </tbody> +</table> + +### Notification actions and maxActions properties + +The {{domxref("Notification/actions","actions")}} read-only property and the [`maxActions`](/en-US/docs/Web/API/Notification/maxActions_static) static read-only property of the {{domxref("Notification")}} interface are supported in Nightly on desktop. +These contain the notification actions set with {{domxref("ServiceWorkerRegistration.showNotification()")}}, and the maximum number of actions that can be set, respectively. +([Firefox bug 1225110](https://bugzil.la/1225110), [Firefox bug 1963263](https://bugzil.la/1963263)). + +<table> + <thead> + <tr> + <th>Release channel</th> + <th>Version added</th> + <th>Enabled by default?</th> + </tr> + </thead> + <tbody> + <tr> + <th>Nightly</th> + <td>138</td> + <td>Yes (desktop only)</td> + </tr> + <tr> + <th>Developer Edition</th> + <td>138</td> + <td>No</td> + </tr> + <tr> + <th>Beta</th> + <td>138</td> + <td>No</td> + </tr> + <tr> + <th>Release</th> + <td>138</td> + <td>No</td> + </tr> + <tr> + <th>Preference name</th> + <td colspan="2"><code>dom.webnotifications.actions.enabled</code></td> + </tr> + </tbody> +</table> + ### Graphics: Canvas, WebGL, and WebGPU #### WebGL: Draft extensions @@ -1073,7 +1354,7 @@ The [WebGPU API](/en-US/docs/Web/API/WebGPU_API) provides low-level support for ### Reporting API support for CSP Violations -The [Reporting API](/en-US/docs/Web/API/Reporting_API) now has support for reporting [Content Security Policy (CSP)](/en-US/docs/Web/HTTP/CSP) violations. +The [Reporting API](/en-US/docs/Web/API/Reporting_API) now has support for reporting [Content Security Policy (CSP)](/en-US/docs/Web/HTTP/Guides/CSP) violations. {{domxref('Report')}} instances returned by the {{domxref('ReportingObserver')}} interface can now have a `type` value of `"csp-violation"` and a `body` property that contains an instance of the {{domxref('CSPViolationReportBody')}} interface. This allows CSP violations to be reported within a web page. @@ -1081,7 +1362,7 @@ This allows CSP violations to be reported within a web page. CSP violation reports can also be sent to remote endpoints that are specified by name in the CSP {{CSP("report-to")}} directive — endpoints names and corresponding URLs must first be defined in the {{httpheader('Reporting-Endpoints')}} or {{httpheader('Report-To')}} HTTP response headers. The report is a serialization of the {{domxref('Report')}} object described above, with a `body` property that is a serialization of an {{domxref('CSPViolationReportBody')}} instance. -This violation report replaces a similar CSP-specific mechanism for sending violation reports, which uses the CSP {{CSP("report-uri")}} directive to set the URL of the reporting endpoint, and has a [CSP-specific JSON violation report format](/en-US/docs/Web/HTTP/Headers/Content-Security-Policy/report-uri#violation_report_syntax). +This violation report replaces a similar CSP-specific mechanism for sending violation reports, which uses the CSP {{CSP("report-uri")}} directive to set the URL of the reporting endpoint, and has a [CSP-specific JSON violation report format](/en-US/docs/Web/HTTP/Reference/Headers/Content-Security-Policy/report-uri#violation_report_syntax). ([Firefox bug 1391243](https://bugzil.la/1391243)). <table> @@ -1641,10 +1922,9 @@ See [Firefox bug 1697647](https://bugzil.la/1697647) for more details. ### Prioritized Task Scheduling API -The [Prioritized Task Scheduling API](/en-US/docs/Web/API/Prioritized_Task_Scheduling_API) provides a standardized way to prioritize all tasks belonging to an application, whether they defined in a website developer's code, or in third party libraries and frameworks. ([Firefox bug 1734997](https://bugzil.la/1734997)) - -This feature was enabled on Firefox Nightly in Firefox 101. -Support in Firefox Nightly 135 has been temporarily disabled in order to avoid [breakage in-the-wild](https://bugzil.la/1937232). +The [Prioritized Task Scheduling API](/en-US/docs/Web/API/Prioritized_Task_Scheduling_API) provides a standardized way to prioritize all tasks belonging to an application, whether they are defined in a website developer's code, or in third-party libraries and frameworks. +From Firefox version 140 the API is both feature complete and enabled in the Nightly release. +([Firefox bug 1734997](https://bugzil.la/1734997) and [Firefox bug 1920115](https://bugzil.la/1920115)). <table> <thead> @@ -1657,8 +1937,8 @@ Support in Firefox Nightly 135 has been temporarily disabled in order to avoid [ <tbody> <tr> <th>Nightly</th> - <td>101</td> - <td>No</td> + <td>139</td> + <td>Yes</td> </tr> <tr> <th>Developer Edition</th> @@ -1722,42 +2002,42 @@ Notifications have the [`requireInteraction`](/en-US/docs/Web/API/Notification/r </tbody> </table> -### SVG path API methods +### View Transition API -The `SVGPathSegment` interface now supports the `getPathData()`, `setPathData()`, and `getPathSegmentAtLength()` methods. These methods provide a convenient way to work with SVG path data instead of parsing raw string data. ([Firefox bug 1934525](https://bugzil.la/1934525)). +The [View Transition API](/en-US/docs/Web/API/View_Transition_API) provides a mechanism for easily creating animated transitions between different website views. This is especially useful for [SPAs (single-page applications)](/en-US/docs/Glossary/SPA). ([Firefox bug 1950759](https://bugzil.la/1950759)). <table> <thead> <tr> <th>Release channel</th> - <th>Version added</th> + <th>Version changed</th> <th>Enabled by default?</th> </tr> </thead> <tbody> <tr> <th>Nightly</th> - <td>136</td> + <td>139</td> <td>Yes</td> </tr> <tr> <th>Developer Edition</th> - <td>136</td> + <td>—</td> <td>No</td> </tr> <tr> <th>Beta</th> - <td>136</td> + <td>—</td> <td>No</td> </tr> <tr> <th>Release</th> - <td>136</td> + <td>—</td> <td>No</td> </tr> <tr> <th>Preference name</th> - <td colspan="2"><code>dom.svg.pathSegment.enabled</code></td> + <td colspan="2">N/A</td> </tr> </tbody> </table> @@ -1852,10 +2132,10 @@ The two `security.insecure_connection_text_*` preferences add a "Not secure" tex ### Permissions Policy / Feature policy -[Permissions Policy](/en-US/docs/Web/HTTP/Permissions_Policy) allows web developers to selectively enable, disable, and modify the behavior of certain features and APIs in the browser. It is similar to CSP but controls features instead of security behavior. +[Permissions Policy](/en-US/docs/Web/HTTP/Guides/Permissions_Policy) allows web developers to selectively enable, disable, and modify the behavior of certain features and APIs in the browser. It is similar to CSP but controls features instead of security behavior. This is implemented in Firefox as **Feature Policy**, the name used in an earlier version of the specification. -Note that supported policies can be set through the [`allow`](/en-US/docs/Web/HTML/Element/iframe#allow) attribute on `<iframe>` elements even if the user preference is not set. +Note that supported policies can be set through the [`allow`](/en-US/docs/Web/HTML/Reference/Elements/iframe#allow) attribute on `<iframe>` elements even if the user preference is not set. <table> <thead> @@ -1897,7 +2177,7 @@ Note that supported policies can be set through the [`allow`](/en-US/docs/Web/HT ### Privacy Preserving Attribution API (PPA) -[PPA API](https://support.mozilla.org/en-US/kb/privacy-preserving-attribution) provides an alternative to user tracking for ad attribution using the new `navigator.privateAttribution` object with `saveImpression()` and `measureConversion()` methods. Read more about PPA [in the explainer](https://github.com/mozilla/explainers/tree/main/ppa-experiment). This experiment can be enabled for websites via [origin trial](https://wiki.mozilla.org/Origin_Trials) or in the browser by setting the preference to `1`. ([Firefox bug 1900929](https://bugzil.la/1900929)). +[PPA API](https://support.mozilla.org/en-US/kb/privacy-preserving-attribution) provides an alternative to user tracking for ad attribution using the new `navigator.privateAttribution` object with `saveImpression()` and `measureConversion()` methods. Read more about PPA [in the original explainer](https://github.com/mozilla/explainers/tree/main/archive/ppa-experiment) and the [proposed spec](https://w3c.github.io/ppa/). This experiment can be enabled for websites via [origin trial](https://wiki.mozilla.org/Origin_Trials) or in the browser by setting the preference to `1`. ([Firefox bug 1900929](https://bugzil.la/1900929)). <table> <thead> @@ -1941,7 +2221,7 @@ Note that supported policies can be set through the [`allow`](/en-US/docs/Web/HT ### Accept header with MIME type image/jxl -The HTTP [`Accept`](/en-US/docs/Web/HTTP/Headers/Accept) header in [default requests and image requests](/en-US/docs/Web/HTTP/Content_negotiation/List_of_default_Accept_values) can be configured via a preference to indicate support for the `image/jxl` MIME type. +The HTTP [`Accept`](/en-US/docs/Web/HTTP/Reference/Headers/Accept) header in [default requests and image requests](/en-US/docs/Web/HTTP/Guides/Content_negotiation/List_of_default_Accept_values) can be configured via a preference to indicate support for the `image/jxl` MIME type. <table> <thead> @@ -1983,7 +2263,7 @@ The HTTP [`Accept`](/en-US/docs/Web/HTTP/Headers/Accept) header in [default requ ### SameSite=Lax by default -[`SameSite` cookies](/en-US/docs/Web/HTTP/Headers/Set-Cookie#samesitesamesite-value) have a default value of `Lax`. +[`SameSite` cookies](/en-US/docs/Web/HTTP/Reference/Headers/Set-Cookie#samesitesamesite-value) have a default value of `Lax`. With this setting, cookies are only sent when a user is navigating to the origin site, not for cross-site subrequests to load images or frames into a third party site and so on. For more details see [Firefox bug 1617609](https://bugzil.la/1617609). @@ -2025,7 +2305,7 @@ For more details see [Firefox bug 1617609](https://bugzil.la/1617609). ### Access-Control-Allow-Headers wildcard does not cover Authorization -The [`Access-Control-Allow-Headers`](/en-US/docs/Web/HTTP/Headers/Access-Control-Allow-Headers) is a response header to a [CORS preflight request](/en-US/docs/Glossary/Preflight_request), that indicates which request headers may be included in the final request. +The [`Access-Control-Allow-Headers`](/en-US/docs/Web/HTTP/Reference/Headers/Access-Control-Allow-Headers) is a response header to a [CORS preflight request](/en-US/docs/Glossary/Preflight_request), that indicates which request headers may be included in the final request. The response directive can contain a wildcard (`*`), which indicates that the final request may include all headers except the `Authorization` header. By default, Firefox includes the `Authorization` header in the final request after receiving a response with `Access-Control-Allow-Headers: *`. @@ -2068,47 +2348,6 @@ For more details see [Firefox bug 1687364](https://bugzil.la/1687364). </tbody> </table> -### Clear-Site-Data: cache can clear the browser cache - -The [`Clear-Site-Data`](/en-US/docs/Web/HTTP/Headers/Clear-Site-Data) can be used with the [`cache`](/en-US/docs/Web/HTTP/Headers/Clear-Site-Data#cache) or `*` directives to clear the local browser cache. -For more details see [Firefox bug 1942272](https://bugzil.la/1942272). - -<table> - <thead> - <tr> - <th>Release channel</th> - <th>Version added</th> - <th>Enabled by default?</th> - </tr> - </thead> - <tbody> - <tr> - <th>Nightly</th> - <td>136</td> - <td>Yes</td> - </tr> - <tr> - <th>Developer Edition</th> - <td>136</td> - <td>No</td> - </tr> - <tr> - <th>Beta</th> - <td>136</td> - <td>No</td> - </tr> - <tr> - <th>Release</th> - <td>136</td> - <td>No</td> - </tr> - <tr> - <th>Preference name</th> - <td colspan="2"><code>privacy.clearSiteDataHeader.cache.enabled</code></td> - </tr> - </tbody> -</table> - ## Developer tools Mozilla's developer tools are constantly evolving. We experiment with new ideas, add new features, and test them on the Nightly and Developer Edition channels before letting them go through to beta and release. The features below are the current crop of experimental developer tool features. diff --git a/files/en-us/mozilla/firefox/index.md b/files/en-us/mozilla/firefox/index.md index d63d8c826160d04..1e14ceb79badaaf 100644 --- a/files/en-us/mozilla/firefox/index.md +++ b/files/en-us/mozilla/firefox/index.md @@ -6,11 +6,11 @@ page-type: landing-page {{FirefoxSidebar}} -[Firefox](https://www.mozilla.org/en-US/firefox/) is Mozilla's popular Web browser, available for multiple platforms including Windows, macOS, and Linux on the desktop and all Android and iOS mobile devices. With broad compatibility, the latest in Web technologies, and powerful development tools, Firefox is a great choice for both Web developers and end users. +[Firefox](https://www.mozilla.org/en-US/firefox/new/) is Mozilla's popular Web browser, available for multiple platforms including Windows, macOS, and Linux on the desktop and all Android and iOS mobile devices. With broad compatibility, the latest in Web technologies, and powerful development tools, Firefox is a great choice for both Web developers and end users. Firefox is an open source project; much of the code is contributed by our huge community of volunteers. Here you can learn about how to contribute to the Firefox project and you will also find links to information about the construction of Firefox add-ons, using the developer tools in Firefox, and other topics. -Learn how to create add-ons for [Firefox](https://www.mozilla.org/en-US/firefox/), how to develop and build Firefox itself, and how the internals of Firefox and its subprojects work. +Learn how to create add-ons for [Firefox](https://www.mozilla.org/en-US/firefox/new/), how to develop and build Firefox itself, and how the internals of Firefox and its subprojects work. ## Key resources @@ -27,7 +27,7 @@ Firefox is available in five **channels**. ### Firefox Nightly -Each night we build Firefox from the latest code in [mozilla-central](https://hg.mozilla.org/mozilla-central/). These builds are for Firefox developers or those who want to try out the very latest cutting edge features while they're still under active development. +Each night we build Firefox from the latest code in [mozilla-central](https://hg-edge.mozilla.org/mozilla-central/). These builds are for Firefox developers or those who want to try out the very latest cutting edge features while they're still under active development. [Download Firefox Nightly](https://www.mozilla.org/en-US/firefox/channel/desktop/#nightly) diff --git a/files/en-us/mozilla/firefox/releases/1.5/using_firefox_1.5_caching/index.md b/files/en-us/mozilla/firefox/releases/1.5/using_firefox_1.5_caching/index.md index cbba1312765fd60..49d9e28e3bbf9c3 100644 --- a/files/en-us/mozilla/firefox/releases/1.5/using_firefox_1.5_caching/index.md +++ b/files/en-us/mozilla/firefox/releases/1.5/using_firefox_1.5_caching/index.md @@ -18,9 +18,9 @@ There are instances in which Firefox doesn't cache pages. Below are some common - "Pragma: no-cache" - with "Expires: 0" or "Expires" with a date value in the past relative to the value of the "Date" header (unless "Cache-Control: max-age=" is also specified); -- the page is not completely loaded when the user navigates away from it or has pending network requests for other reasons (e.g. `XMLHttpRequest`)); +- the page is not completely loaded when the user navigates away from it or has pending network requests for other reasons (e.g., `XMLHttpRequest`)); - the page has running IndexedDB transactions; -- the top-level page contains frames (e.g. {{HTMLElement("iframe")}}) that are not cacheable for any of the reasons listed here; +- the top-level page contains frames (e.g., {{HTMLElement("iframe")}}) that are not cacheable for any of the reasons listed here; - the page is in a frame and the user loads a new page within that frame (in this case, when the user navigates away from the page, the content that was last loaded into the frames is what is cached). This new caching feature changes page loading behavior, and Web authors may want to: @@ -100,7 +100,7 @@ In this example: } function onPageShow() { - //calculate current time + // Calculate current time var currentTime = new Date(); var year = currentTime.getFullYear(); var month = currentTime.getMonth() + 1; @@ -123,7 +123,7 @@ In this example: sec + ":" + mil; - document.getElementById("timefield").value = displayTime; + document.getElementById("time-field").value = displayTime; } function loadOnlyFirst() { @@ -138,8 +138,8 @@ In this example: name="zipForm" action="http://www.example.com/formresult.html" method="get"> - <label for="timefield">Date and time:</label> - <input type="text" id="timefield" /><br /> + <label for="time-field">Date and time:</label> + <input type="text" id="time-field" /><br /> <label for="name">Name:</label> <input type="text" id="name" /><br /> <label for="address">Email address:</label> @@ -155,31 +155,44 @@ In this example: In contrast, if the above page did not listen for the `pageshow` event and handled all calculations as part of the `load` event (and instead was coded as shown in the sample code fragment below), both the cursor position and date/time would be cached in Firefox 1.5 when the user navigated away from the page. When the user returned to the page, the cached date/time would display. ```html -<script> -function onLoad() { - loadOnlyFirst(); - -//calculate current time - var currentTime= new Date(); - var year = currentTime.getFullYear(); - var month = currentTime.getMonth()+1; - var day = currentTime.getDate(); - var hour=currentTime.getHours(); - var min=currentTime.getMinutes(); - var sec=currentTime.getSeconds(); - var mil=currentTime.getMilliseconds(); - var displayTime = (month + "/" + day + "/" + year + " " + - hour + ":" + min + ":" + sec + ":" + mil); - document.getElementById("timefield").value=displayTime; -} - -function loadOnlyFirst() { - document.zipForm.name.focus(); -} -</script> +<head> + <script> + function onLoad() { + loadOnlyFirst(); + + // Calculate current time + var currentTime = new Date(); + var year = currentTime.getFullYear(); + var month = currentTime.getMonth() + 1; + var day = currentTime.getDate(); + var hour = currentTime.getHours(); + var min = currentTime.getMinutes(); + var sec = currentTime.getSeconds(); + var mil = currentTime.getMilliseconds(); + var displayTime = + month + + "/" + + day + + "/" + + year + + " " + + hour + + ":" + + min + + ":" + + sec + + ":" + + mil; + document.getElementById("time-field").value = displayTime; + } + + function loadOnlyFirst() { + document.zipForm.name.focus(); + } + </script> </head> -<body onload="onLoad();"> +<body onload="onLoad();"></body> ``` ## Developing Firefox extensions diff --git a/files/en-us/mozilla/firefox/releases/1.5/what_s_new_in_1.5_alpha/index.md b/files/en-us/mozilla/firefox/releases/1.5/what_s_new_in_1.5_alpha/index.md index 4df4f5ae6a369c1..8b9fc167ef3e657 100644 --- a/files/en-us/mozilla/firefox/releases/1.5/what_s_new_in_1.5_alpha/index.md +++ b/files/en-us/mozilla/firefox/releases/1.5/what_s_new_in_1.5_alpha/index.md @@ -105,7 +105,7 @@ This page is based largely on [https://www.squarefree.com/burningedg...eases/](h - Adding tokens to the User-Agent string - : It is now possible for applications, extensions, and vendors to all add tokens to the User-Agent string (using default preferences) without overwriting each other. - See [documentation](/en-US/docs/Web/HTTP/Headers/User-Agent). [Firefox bug 274928](https://bugzil.la/274928) + See [documentation](/en-US/docs/Web/HTTP/Reference/Headers/User-Agent). [Firefox bug 274928](https://bugzil.la/274928) - Toolkit chrome registry diff --git a/files/en-us/mozilla/firefox/releases/10/index.md b/files/en-us/mozilla/firefox/releases/10/index.md index 07af4b6dfbdec34..0741e4e8cd8168c 100644 --- a/files/en-us/mozilla/firefox/releases/10/index.md +++ b/files/en-us/mozilla/firefox/releases/10/index.md @@ -16,7 +16,7 @@ Firefox 10 shipped on January 31, 2012. This article provides information about ### HTML - The new HTML5 {{ HTMLElement("bdi") }} element, bi-directional isolation, allowing isolation of parts of text with a different directionality has been implemented. This is especially useful when displaying text with an unknown directionality, coming from a database for example, in the middle of text with a known, and potentially, different one. -- You may now specify a fragment of "top" for the [`href`](/en-US/docs/Web/HTML/Element/a#href) attribute to create a link to the top of the page. This used to work, then went away for a while, and now it's back, for compatibility with the HTML5 specification. For example: `<a href="#top">Return to top of page</a>`. +- You may now specify a fragment of "top" for the [`href`](/en-US/docs/Web/HTML/Reference/Elements/a#href) attribute to create a link to the top of the page. This used to work, then went away for a while, and now it's back, for compatibility with the HTML5 specification. For example: `<a href="#top">Return to top of page</a>`. ### JavaScript @@ -66,7 +66,7 @@ Firefox 10 shipped on January 31, 2012. This article provides information about #### Web Workers - The attribute `XMLHttpRequest.responseType` and `XMLHttpRequest.response` are now available from inside [Workers](/en-US/docs/Web/API/Web_Workers_API/Functions_and_classes_available_to_workers#section_2). -- The [`Worker()`](/en-US/docs/Web/API/Worker#worker) constructor now accepts [data URLs](/en-US/docs/Web/URI/Reference/Schemes/data). +- The [`Worker()`](/en-US/docs/Web/API/Worker/Worker) constructor now accepts [data URLs](/en-US/docs/Web/URI/Reference/Schemes/data). #### IndexedDB @@ -89,7 +89,7 @@ Great progress has been made to update IndexedDB to the latest draft specificati - The ESC key no longer incorrectly results in the {{ domxref("Element.keydown_event", "onkeydown") }} handler incorrectly getting called. - The `NameList` interface is no longer implemented; it previously had an implementation with no way to actually get access to one. - The {{ domxref("document.createProcessingInstruction()") }} method now works on HTML documents as well as XML documents. {{ domxref("ProcessingInstruction") }} nodes are still only supported on XML documents, but since nodes can be moved among documents, it's helpful to be able to create them on HTML documents as well. -- The {{ domxref("XMLHttpRequest") }} `responseType` "`moz-json`" [introduced in Firefox 9](/en-US/docs/Mozilla/Firefox/Releases/9#dom) has been updated to the latest draft of the specification and has been unprefixed. See note in [Firefox bug 707142](https://bugzil.la/707142#c13). +- The {{ domxref("XMLHttpRequest") }} `responseType` `"moz-json"` [introduced in Firefox 9](/en-US/docs/Mozilla/Firefox/Releases/9#dom) has been updated to the latest draft of the specification and has been unprefixed. See note in [Firefox bug 707142](https://bugzil.la/707142#c13). ### CSS diff --git a/files/en-us/mozilla/firefox/releases/100/index.md b/files/en-us/mozilla/firefox/releases/100/index.md index 6e66320303cb11e..93252dc98278844 100644 --- a/files/en-us/mozilla/firefox/releases/100/index.md +++ b/files/en-us/mozilla/firefox/releases/100/index.md @@ -44,7 +44,7 @@ No notable changes. ### WebDriver conformance (Marionette) -- Added support for user prompts (e.g. `alert`) on Android ([Firefox bug 1708105](https://bugzil.la/1708105)). +- Added support for user prompts (e.g., `alert`) on Android ([Firefox bug 1708105](https://bugzil.la/1708105)). ## Changes for add-on developers diff --git a/files/en-us/mozilla/firefox/releases/101/index.md b/files/en-us/mozilla/firefox/releases/101/index.md index a3285807b70b56e..82fdc98c7d199cb 100644 --- a/files/en-us/mozilla/firefox/releases/101/index.md +++ b/files/en-us/mozilla/firefox/releases/101/index.md @@ -80,7 +80,7 @@ For more information, see the [full bug list](https://bugzilla.mozilla.org/bugli - The [`"background"`](/en-US/docs/Mozilla/Add-ons/WebExtensions/manifest.json/background) manifest key property `"persistent"` can be set to `false` under the control of preferences: for Manifest V2, the <code>extensions.eventPages.enabled</code> preference, and in Manifest V3, the <code>extensions.manifestV3.enabled</code> preference. - Addition of the [`"host_permissions"`](/en-US/docs/Mozilla/Add-ons/WebExtensions/manifest.json/host_permissions) manifest key, which is available for Manifest V3 extensions. - The content script execution environment has changed for Manifest V3 extensions: - - Content scripts can no longer rely on host permissions to perform cross-origin requests. Cross-origin requests from content scripts are possible with [CORS](/en-US/docs/Web/HTTP/CORS). + - Content scripts can no longer rely on host permissions to perform cross-origin requests. Cross-origin requests from content scripts are possible with [CORS](/en-US/docs/Web/HTTP/Guides/CORS). - The `content` object (that offered `content.fetch`, `content.XMLHttpRequest`, and `content.WebSocket`) is removed from the content script execution environment. ## Older versions diff --git a/files/en-us/mozilla/firefox/releases/102/index.md b/files/en-us/mozilla/firefox/releases/102/index.md index 43eac02cd23f9da..9da965beef872ac 100644 --- a/files/en-us/mozilla/firefox/releases/102/index.md +++ b/files/en-us/mozilla/firefox/releases/102/index.md @@ -34,7 +34,7 @@ No notable changes. ### Security -- Support of the [`wasm-unsafe-eval`](/en-US/docs/Web/HTTP/Headers/Content-Security-Policy/script-src#unsafe_webassembly_execution) CSP policy directive has been implemented. +- Support of the [`wasm-unsafe-eval`](/en-US/docs/Web/HTTP/Reference/Headers/Content-Security-Policy/script-src#unsafe_webassembly_execution) CSP policy directive has been implemented. A document with a CSP that restricts scripts will no longer load and execute WebAssembly unless the CSP uses `'wasm-unsafe-eval'` or the existing `'unsafe-eval'` keyword ([Firefox bug 1740263](https://bugzil.la/1740263)). #### DOM diff --git a/files/en-us/mozilla/firefox/releases/105/index.md b/files/en-us/mozilla/firefox/releases/105/index.md index b236010157f8577..20082a9beffae48 100644 --- a/files/en-us/mozilla/firefox/releases/105/index.md +++ b/files/en-us/mozilla/firefox/releases/105/index.md @@ -16,7 +16,7 @@ No notable changes. ### CSS -- Embedded content, such as SVG definitions and content in an [`<iframe>`](/en-US/docs/Web/HTML/Element/iframe), now respects the theme preferences of the elements in which it is embedded, rather than OS or browser preferences (which may be different). +- Embedded content, such as SVG definitions and content in an [`<iframe>`](/en-US/docs/Web/HTML/Reference/Elements/iframe), now respects the theme preferences of the elements in which it is embedded, rather than OS or browser preferences (which may be different). Specifically, embedded content now inherits the [`color-scheme`](/en-US/docs/Web/CSS/color-scheme) of the embedding element, and [`prefers-color-scheme`](/en-US/docs/Web/CSS/@media/prefers-color-scheme) media queries in the embedded content respect this value rather than the OS/browser level theme setting ([Firefox bug 1779457](https://bugzil.la/1779457)). ### JavaScript diff --git a/files/en-us/mozilla/firefox/releases/106/index.md b/files/en-us/mozilla/firefox/releases/106/index.md index bb8b0f377aa66d6..2450ea93d003afc 100644 --- a/files/en-us/mozilla/firefox/releases/106/index.md +++ b/files/en-us/mozilla/firefox/releases/106/index.md @@ -12,12 +12,12 @@ This article provides information about the changes in Firefox 106 that will aff ### HTML -- The {{HTMLElement("source")}} element now supports [`height`](/en-US/docs/Web/HTML/Element/source#height) & [`width`](/en-US/docs/Web/HTML/Element/source#width) attributes when it is a child of a {{HTMLElement("picture")}} element. +- The {{HTMLElement("source")}} element now supports [`height`](/en-US/docs/Web/HTML/Reference/Elements/source#height) & [`width`](/en-US/docs/Web/HTML/Reference/Elements/source#width) attributes when it is a child of a {{HTMLElement("picture")}} element. This functionality is an experimental feature enabled using the `dom.picture_source_dimension_attributes.enabled` preference ([Firefox bug 1694741](https://bugzil.la/1694741)). ### MathML -- The [`<semantics>`](/en-US/docs/Web/MathML/Element/semantics) and [`<maction>`](/en-US/docs/Web/MathML/Element/maction) MathML elements now only render the first child element by default ([Firefox bug 1588733](https://bugzil.la/1588733)). +- The [`<semantics>`](/en-US/docs/Web/MathML/Reference/Element/semantics) and [`<maction>`](/en-US/docs/Web/MathML/Reference/Element/maction) MathML elements now only render the first child element by default ([Firefox bug 1588733](https://bugzil.la/1588733)). ### CSS @@ -32,7 +32,7 @@ No notable changes. #### DOM -- The [`HTMLMetaElement.media`](/en-US/docs/Web/API/HTMLMetaElement/media) property is now supported. This property enables you to set different theme colors based on `media` values (e.g. `max-width: 600px`). +- The [`HTMLMetaElement.media`](/en-US/docs/Web/API/HTMLMetaElement/media) property is now supported. This property enables you to set different theme colors based on `media` values (e.g., `max-width: 600px`). Meta elements with `media` properties allow the browser to use the `content` value in conjunction with `theme-color` to set the page or UI colors for a given media query ([Firefox bug 1706179](https://bugzil.la/1706179)). ### WebDriver conformance (WebDriver BiDi, Marionette) diff --git a/files/en-us/mozilla/firefox/releases/107/index.md b/files/en-us/mozilla/firefox/releases/107/index.md index e59782189aa037e..b90f5c7f20cb761 100644 --- a/files/en-us/mozilla/firefox/releases/107/index.md +++ b/files/en-us/mozilla/firefox/releases/107/index.md @@ -16,7 +16,7 @@ No notable changes ### MathML -- Deprecated `lquote` and `rquote` attributes of the [`<ms>`](/en-US/docs/Web/MathML/Element/ms) MathML element for custom opening and closing quotes are now disabled. +- Deprecated `lquote` and `rquote` attributes of the [`<ms>`](/en-US/docs/Web/MathML/Reference/Element/ms) MathML element for custom opening and closing quotes are now disabled. This behavior is configured via the `mathml.ms_lquote_rquote_attributes.disabled` preference which is set to `true` by default ([Firefox bug 1793387](https://bugzil.la/1793387)). ### CSS diff --git a/files/en-us/mozilla/firefox/releases/108/index.md b/files/en-us/mozilla/firefox/releases/108/index.md index 28d159194694ab7..e08024d8467f1ae 100644 --- a/files/en-us/mozilla/firefox/releases/108/index.md +++ b/files/en-us/mozilla/firefox/releases/108/index.md @@ -12,7 +12,7 @@ This article provides information about the changes in Firefox 108 that will aff ### HTML -- The {{HTMLElement("source")}} element supports [`height`](/en-US/docs/Web/HTML/Element/source#height) & [`width`](/en-US/docs/Web/HTML/Element/source#width) attributes when it is a child of a {{HTMLElement("picture")}} element. +- The {{HTMLElement("source")}} element supports [`height`](/en-US/docs/Web/HTML/Reference/Elements/source#height) & [`width`](/en-US/docs/Web/HTML/Reference/Elements/source#width) attributes when it is a child of a {{HTMLElement("picture")}} element. This functionality can be configured via the `dom.picture_source_dimension_attributes.enabled` preference which is now set to `true` by default ([Firefox bug 1795953](https://bugzil.la/1795953)). ### CSS @@ -31,16 +31,16 @@ No notable changes ### HTTP -- [`Content-Security-Policy`](/en-US/docs/Web/HTTP/Headers/Content-Security-Policy) HTTP header directives [`style-src-elem`](/en-US/docs/Web/HTTP/Headers/Content-Security-Policy/style-src-elem) and [`style-src-attr`](/en-US/docs/Web/HTTP/Headers/Content-Security-Policy/style-src-attr) are now supported. +- [`Content-Security-Policy`](/en-US/docs/Web/HTTP/Reference/Headers/Content-Security-Policy) HTTP header directives [`style-src-elem`](/en-US/docs/Web/HTTP/Reference/Headers/Content-Security-Policy/style-src-elem) and [`style-src-attr`](/en-US/docs/Web/HTTP/Reference/Headers/Content-Security-Policy/style-src-attr) are now supported. A server can use these to specify valid sources for stylesheet `<style>` elements and `<link>` elements with `rel="stylesheet"`, and for styles applied to individual elements, respectively ([Firefox bug 1529338](https://bugzil.la/1529338)). -- [`Content-Security-Policy`](/en-US/docs/Web/HTTP/Headers/Content-Security-Policy) HTTP header directives [`script-src-elem`](/en-US/docs/Web/HTTP/Headers/Content-Security-Policy/script-src-elem) and [`script-src-attr`](/en-US/docs/Web/HTTP/Headers/Content-Security-Policy/script-src-attr) are now supported. +- [`Content-Security-Policy`](/en-US/docs/Web/HTTP/Reference/Headers/Content-Security-Policy) HTTP header directives [`script-src-elem`](/en-US/docs/Web/HTTP/Reference/Headers/Content-Security-Policy/script-src-elem) and [`script-src-attr`](/en-US/docs/Web/HTTP/Reference/Headers/Content-Security-Policy/script-src-attr) are now supported. A server can use these to specify valid sources for JavaScript `<script>` elements, and for inline script event handlers like `onclick`, respectively ([Firefox bug 1529337](https://bugzil.la/1529337)). -- [`Content-Security-Policy`](/en-US/docs/Web/HTTP/Headers/Content-Security-Policy) violation reports now include `effective-directive` and `status-code` properties. - For more information, see [Violation report syntax](/en-US/docs/Web/HTTP/Headers/Content-Security-Policy/report-uri#violation_report_syntax) ([Firefox bug 1192684](https://bugzil.la/1192684)). +- [`Content-Security-Policy`](/en-US/docs/Web/HTTP/Reference/Headers/Content-Security-Policy) violation reports now include `effective-directive` and `status-code` properties. + For more information, see [Violation report syntax](/en-US/docs/Web/HTTP/Reference/Headers/Content-Security-Policy/report-uri#violation_report_syntax) ([Firefox bug 1192684](https://bugzil.la/1192684)). ### APIs -- [Import maps](/en-US/docs/Web/HTML/Element/script/type/importmap) are now supported. +- [Import maps](/en-US/docs/Web/HTML/Reference/Elements/script/type/importmap) are now supported. Import maps provide flexibility and additional control over how browsers resolve module specifiers when importing [JavaScript modules](/en-US/docs/Web/JavaScript/Guide/Modules). ([Firefox bug 1795647](https://bugzil.la/1795647)). diff --git a/files/en-us/mozilla/firefox/releases/109/index.md b/files/en-us/mozilla/firefox/releases/109/index.md index da952684d36c8a7..ea8e3bcc4bb0342 100644 --- a/files/en-us/mozilla/firefox/releases/109/index.md +++ b/files/en-us/mozilla/firefox/releases/109/index.md @@ -12,7 +12,7 @@ This article provides information about the changes in Firefox 109 that will aff ### HTML -- The {{HTMLElement("input/range", "range")}} element supports the [`list`](/en-US/docs/Web/HTML/Element/input/range#list) attribute, which links via an id to a {{HTMLElement("datalist")}} to allow Firefox to display tick marks along the range. +- The {{HTMLElement("input/range", "range")}} element supports the [`list`](/en-US/docs/Web/HTML/Reference/Elements/input/range#list) attribute, which links via an id to a {{HTMLElement("datalist")}} to allow Firefox to display tick marks along the range. ### CSS @@ -31,14 +31,14 @@ No notable changes. ([Firefox bug 1803790](https://bugzil.la/1803790)). - The `SVGGraphicsElement.nearestViewportElement` and `SVGGraphicsElement.farthestViewportElement` attributes have been disabled by default in nightly and early beta builds (behind preference `svg.nearestAndFarthestViewportElement.enabled`). - [`SVGElement.viewportElement`](/en-US/docs/Web/API/SVGElement#svgelement.viewportelement) can be used as an alternative to `SVGGraphicsElement.nearestViewportElement`. + [`SVGElement.viewportElement`](/en-US/docs/Web/API/SVGElement/viewportElement) can be used as an alternative to `SVGGraphicsElement.nearestViewportElement`. They have been removed from the SVG2 specification and are likely to be removed entirely from Firefox in a future release. ([Firefox bug 1133174](https://bugzil.la/1133174)). ### HTTP - The `'unsafe-hashes'` value for {{HTTPHeader("Content-Security-Policy")}} source directives is now supported. - For more information, see [CSP unsafe-hashes](/en-US/docs/Web/HTTP/Headers/Content-Security-Policy/script-src#unsafe_hashes) ([Firefox bug 1343950](https://bugzil.la/1343950)). + For more information, see [CSP unsafe-hashes](/en-US/docs/Web/HTTP/Reference/Headers/Content-Security-Policy/script-src#unsafe_hashes) ([Firefox bug 1343950](https://bugzil.la/1343950)). ### APIs diff --git a/files/en-us/mozilla/firefox/releases/11/index.md b/files/en-us/mozilla/firefox/releases/11/index.md index 21982bb1653611b..b8bed0b706ca36e 100644 --- a/files/en-us/mozilla/firefox/releases/11/index.md +++ b/files/en-us/mozilla/firefox/releases/11/index.md @@ -28,9 +28,9 @@ Firefox 11 shipped on March 13, 2012. This article provides information about th - Support for the [`defaultMuted`](/en-US/docs/Web/API/HTMLMediaElement), [`loop`](/en-US/docs/Web/API/HTMLMediaElement) and [`muted`](/en-US/docs/Web/API/HTMLMediaElement) properties on [`HTMLMediaElement`](/en-US/docs/Web/API/HTMLMediaElement) has been added. - Calling {{domxref("Document/exitFullscreen")}} now restores the previously fullscreen element if some other element was in fullscreen mode when the current element's {{domxref("Element/requestFullScreen")}} method was called. - The {{domxref("window.requestAnimationFrame", "window.mozRequestAnimationFrame()")}} method no longer supports a no-argument form. This form was not used much and is unlikely to become part of the standard. -- SVG-as-an-image can now be drawn into a canvas without [tainting the canvas](/en-US/docs/Web/HTML/CORS_enabled_image#what_is_a_.22tainted.22_canvas.3f). +- SVG-as-an-image can now be drawn into a canvas without [tainting the canvas](/en-US/docs/Web/HTML/How_to/CORS_enabled_image#what_is_a_.22tainted.22_canvas.3f). - The non-standard `countryCode` property of the `GeoPositionAddress` interface has been removed; see `nsIDOMGeoPositionAddress`. -- [Server-sent events](/en-US/docs/Web/API/Server-sent_events) now support [CORS](/en-US/docs/Web/HTTP/CORS). +- [Server-sent events](/en-US/docs/Web/API/Server-sent_events) now support [CORS](/en-US/docs/Web/HTTP/Guides/CORS). - In the past, when the user followed a link, the values set on the {{domxref("window.navigator")}} object were retained by the new page. Now a new `navigator` object is created for the new page. This makes Firefox behave like all other browsers. ### CSS @@ -73,7 +73,7 @@ _No change._ - It is now possible to create a multi-entry index (see [`IDBObjectStore.createIndex` parameters](/en-US/docs/Web/API/IDBObjectStore/createIndex#parameters).) - The {{domxref("IDBTransaction/abort_event", "abort")}} event now bubbles; in addition, an `onabort` handler has been added. - IndexedDB can now be used to store files/blobs. -- IndexedDB now supports complex key paths, e.g. `foo.bar` to access property `bar` of property `foo`. +- IndexedDB now supports complex key paths, e.g., `foo.bar` to access property `bar` of property `foo`. - IndexedDB can now accept an array as a `keyPath` when creating an [object store](/en-US/docs/Web/API/IDBDatabase/createObjectStore) or an [index](/en-US/docs/Web/API/IDBObjectStore/createIndex) ([Firefox bug 694138](https://bugzil.la/694138).) ### Network diff --git a/files/en-us/mozilla/firefox/releases/110/index.md b/files/en-us/mozilla/firefox/releases/110/index.md index accda8ca173e481..f09c1b9df7a2418 100644 --- a/files/en-us/mozilla/firefox/releases/110/index.md +++ b/files/en-us/mozilla/firefox/releases/110/index.md @@ -19,7 +19,7 @@ No notable changes. - Container queries and container query length units are now supported by default. For more information on these queries and the related units of length, see the [CSS Container Queries](/en-US/docs/Web/CSS/CSS_containment/Container_queries#container_query_length_units) documentation ([Firefox bug 1809720](https://bugzil.la/1809720)). - The [color-gamut media query](/en-US/docs/Web/CSS/@media/color-gamut) is now supported ([Firefox bug 1422237](https://bugzil.la/1422237)). -- The [`list`](/en-US/docs/Web/HTML/Element/datalist#color_type) attribute is supported in `<input>` elements with `type="color"` on Windows and Linux ([Firefox bug 960984](https://bugzil.la/960984)). +- The [`list`](/en-US/docs/Web/HTML/Reference/Elements/datalist#color_type) attribute is supported in `<input>` elements with `type="color"` on Windows and Linux ([Firefox bug 960984](https://bugzil.la/960984)). - The [`@page`](/en-US/docs/Web/CSS/@page) at-rule now supports named pages, which allows a user to create page breaks for specific selectors using the [`page`](/en-US/docs/Web/CSS/page) property ([Firefox bug 1787947](https://bugzil.la/1787947)) ### JavaScript @@ -72,7 +72,7 @@ No notable changes. ## Changes for add-on developers -- Added the `"webRequestFilterResponse"`[API permission](/en-US/docs/Mozilla/Add-ons/WebExtensions/manifest.json/permissions#api_permissions). This permission provides access to {{WebExtAPIRef("webRequest.filterResponseData")}}. This permission can be provided as an optional permission. See {{WebExtAPIRef("webRequest.filterResponseData")}} for more information on using this permission ([Firefox bug 1809235](https://bugzil.la/1809235)). +- Added the `"webRequestFilterResponse"` [API permission](/en-US/docs/Mozilla/Add-ons/WebExtensions/manifest.json/permissions#api_permissions). This permission provides access to {{WebExtAPIRef("webRequest.filterResponseData")}}. This permission can be provided as an optional permission. See {{WebExtAPIRef("webRequest.filterResponseData")}} for more information on using this permission ([Firefox bug 1809235](https://bugzil.la/1809235)). - The `defaultZoomFactor` property of {{WebExtAPIRef("tabs.ZoomSettings")}} now returns the value of the default zoom factor setting ([Firefox bug 1772166](https://bugzil.la/1772166)) ## Older versions diff --git a/files/en-us/mozilla/firefox/releases/111/index.md b/files/en-us/mozilla/firefox/releases/111/index.md index 6d6c889946af47e..91af7dfb42aa86d 100644 --- a/files/en-us/mozilla/firefox/releases/111/index.md +++ b/files/en-us/mozilla/firefox/releases/111/index.md @@ -12,8 +12,8 @@ This article provides information about the changes in Firefox 111 that affect d ### HTML -- The [`autocapitalize`](/en-US/docs/Web/HTML/Global_attributes/autocapitalize) global attribute is now supported by default. The default value for the attribute is `none`, so no capitalization occurs ([Firefox bug 1692007](https://bugzil.la/1692007)). -- The [`translate`](/en-US/docs/Web/HTML/Global_attributes/translate) global attribute is now supported ([Firefox bug 1418449](https://bugzil.la/1418449)). +- The [`autocapitalize`](/en-US/docs/Web/HTML/Reference/Global_attributes/autocapitalize) global attribute is now supported by default. The default value for the attribute is `none`, so no capitalization occurs ([Firefox bug 1692007](https://bugzil.la/1692007)). +- The [`translate`](/en-US/docs/Web/HTML/Reference/Global_attributes/translate) global attribute is now supported ([Firefox bug 1418449](https://bugzil.la/1418449)). ### CSS @@ -28,11 +28,11 @@ No notable changes. ### SVG - The `context-stroke` and `context-fill` values are now supported inside `<marker>` elements. - For more information on using these values with `fill` and `stroke` properties, see the [`<marker>`](/en-US/docs/Web/SVG/Element/marker) documentation ([Firefox bug 752638](https://bugzil.la/752638)). + For more information on using these values with `fill` and `stroke` properties, see the [`<marker>`](/en-US/docs/Web/SVG/Reference/Element/marker) documentation ([Firefox bug 752638](https://bugzil.la/752638)). ### HTTP -- The HTTP [`Authorization`](/en-US/docs/Web/HTTP/Headers/Authorization) header is removed from cross origin redirects. +- The HTTP [`Authorization`](/en-US/docs/Web/HTTP/Reference/Headers/Authorization) header is removed from cross origin redirects. See [Firefox bug 1802086](https://bugzil.la/1802086) for more details. ### APIs @@ -41,7 +41,7 @@ No notable changes. The data in this file system is origin-specific: permission prompts are not required to access files, and clearing data for the site/origin deletes the storage. The OPFS is accessed with the {{domxref("StorageManager.getDirectory()")}} method, by calling `navigator.storage.getDirectory()` in a worker or the main thread. See [Firefox bug 1785123](https://bugzil.la/1785123) for more details. -- The HTTP [`Authorization`](/en-US/docs/Web/HTTP/Headers/Authorization) header is removed from [`fetch()`](/en-US/docs/Web/API/Window/fetch) and [`XMLHttpRequest`](/en-US/docs/Web/API/XMLHttpRequest) requests that are redirected cross-origin (`fetch()` headers may be added by developers using the [`option.headers`](/en-US/docs/Web/API/Window/fetch#headers) argument). +- The HTTP [`Authorization`](/en-US/docs/Web/HTTP/Reference/Headers/Authorization) header is removed from [`fetch()`](/en-US/docs/Web/API/Window/fetch) and [`XMLHttpRequest`](/en-US/docs/Web/API/XMLHttpRequest) requests that are redirected cross-origin (`fetch()` headers may be added by developers using the [`option.headers`](/en-US/docs/Web/API/Window/fetch#headers) argument). See [Firefox bug 1802086](https://bugzil.la/1802086) for more details. - The `none` value of the `options.imageOrientation` parameter passed to {{domxref("Window.createImageBitmap()")}} and {{domxref("WorkerGlobalScope.createImageBitmap()")}} has been renamed to `from-image`. This is to better match the meaning of the equivalent CSS [`image-orientation`](/en-US/docs/Web/CSS/image-orientation) property. ([Firefox bug 1809740](https://bugzil.la/1809740)). diff --git a/files/en-us/mozilla/firefox/releases/112/index.md b/files/en-us/mozilla/firefox/releases/112/index.md index ab082f4a1a0651f..6a19d37b5a33107 100644 --- a/files/en-us/mozilla/firefox/releases/112/index.md +++ b/files/en-us/mozilla/firefox/releases/112/index.md @@ -12,7 +12,7 @@ This article provides information about the changes in Firefox 112 that affect d ### HTML -- The {{domxref("HTMLElement")}} property [**`inert`**](/en-US/docs/Web/HTML/Global_attributes/inert) is now fully enabled. It allows the browser to ignore content or interactive elements that are within an HTMLElement with the `inert` attribute. See [Firefox bug 1764263](https://bugzil.la/1764263) for more details. +- The {{domxref("HTMLElement")}} property [**`inert`**](/en-US/docs/Web/HTML/Reference/Global_attributes/inert) is now fully enabled. It allows the browser to ignore content or interactive elements that are within an HTMLElement with the `inert` attribute. See [Firefox bug 1764263](https://bugzil.la/1764263) for more details. ### CSS diff --git a/files/en-us/mozilla/firefox/releases/113/index.md b/files/en-us/mozilla/firefox/releases/113/index.md index b906c2c27fdc2a6..5cf905f96107755 100644 --- a/files/en-us/mozilla/firefox/releases/113/index.md +++ b/files/en-us/mozilla/firefox/releases/113/index.md @@ -70,7 +70,7 @@ No notable changes. - When an extension registers multiple listeners for the same event, all the event listeners are called when the event page wakes up, instead of only the first one ([Firefox bug 1798655](https://bugzil.la/1798655)). - Support is now provided for the {{WebExtAPIRef("declarativeNetRequest")}} API ([Firefox bug 1782685](https://bugzil.la/1782685)). -- The `gecko_android` subkey has been added to the [`browser_specific_settings`](/en-US/docs/Mozilla/Add-ons/WebExtensions/manifest.json/browser_specific_settings) key. This subkey enables an extension to specify the range of Firefox for Android versions it is compatible with ([Firefox bug 1824237](https://bugzil.la/1824237)). +- The `gecko_android` sub-key has been added to the [`browser_specific_settings`](/en-US/docs/Mozilla/Add-ons/WebExtensions/manifest.json/browser_specific_settings) key. This sub-key enables an extension to specify the range of Firefox for Android versions it is compatible with ([Firefox bug 1824237](https://bugzil.la/1824237)). ## Other diff --git a/files/en-us/mozilla/firefox/releases/114/index.md b/files/en-us/mozilla/firefox/releases/114/index.md index e697077fee16ad5..7e2bd35fc0efdc5 100644 --- a/files/en-us/mozilla/firefox/releases/114/index.md +++ b/files/en-us/mozilla/firefox/releases/114/index.md @@ -12,7 +12,7 @@ This article provides information about the changes in Firefox 114 that affect d ### Developer Tools -- Fixed an issue where the [Accessibility Inspector](https://firefox-source-docs.mozilla.org/devtools-user/accessibility_inspector/index.html) did not correctly show ARIA roles on elements, which affected how [landmark roles](/en-US/docs/Web/Accessibility/ARIA/Roles/landmark_role) were displayed. +- Fixed an issue where the [Accessibility Inspector](https://firefox-source-docs.mozilla.org/devtools-user/accessibility_inspector/index.html) did not correctly show ARIA roles on elements, which affected how [landmark roles](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/landmark_role) were displayed. Roles that cannot be mapped to ARIA use a Gecko internal role name ([Firefox bug 1572512](https://bugzil.la/1572512)). ### HTML @@ -35,7 +35,7 @@ No notable changes. ### SVG -- The [`crossorigin`](/en-US/docs/Web/SVG/Attribute/crossorigin) attribute is now supported in [`image`](/en-US/docs/Web/SVG/Element/image) and [`feImage`](/en-US/docs/Web/SVG/Element/feImage) elements ([Firefox bug 1240357](https://bugzil.la/1240357)). +- The [`crossorigin`](/en-US/docs/Web/SVG/Reference/Attribute/crossorigin) attribute is now supported in [`image`](/en-US/docs/Web/SVG/Reference/Element/image) and [`feImage`](/en-US/docs/Web/SVG/Reference/Element/feImage) elements ([Firefox bug 1240357](https://bugzil.la/1240357)). ### APIs diff --git a/files/en-us/mozilla/firefox/releases/115/index.md b/files/en-us/mozilla/firefox/releases/115/index.md index eb3f20a87202780..d37dbe9a1131362 100644 --- a/files/en-us/mozilla/firefox/releases/115/index.md +++ b/files/en-us/mozilla/firefox/releases/115/index.md @@ -12,7 +12,7 @@ This article provides information about the changes in Firefox 115 that affect d ### HTML -- The [`modulepreload`](/en-US/docs/Web/HTML/Attributes/rel/modulepreload) keyword for the [`rel`](/en-US/docs/Web/HTML/Element/link#rel) attribute of the {{HTMLElement("link")}} element is now supported. +- The [`modulepreload`](/en-US/docs/Web/HTML/Reference/Attributes/rel/modulepreload) keyword for the [`rel`](/en-US/docs/Web/HTML/Reference/Elements/link#rel) attribute of the {{HTMLElement("link")}} element is now supported. This allows early (and asynchronous) fetching of [module scripts](/en-US/docs/Web/JavaScript/Guide/Modules) and their dependencies in parallel, which are then stored in the document's module map ([Firefox bug 1425310](https://bugzil.la/1425310)). ### CSS @@ -30,7 +30,7 @@ This article provides information about the changes in Firefox 115 that affect d ### HTTP -- The [`Sec-Purpose`](/en-US/docs/Web/HTTP/Headers/Sec-Purpose) HTTP {{Glossary("Fetch metadata request header", "fetch metadata request header")}} is now included in requests to {{Glossary("Prefetch")}} resources. +- The [`Sec-Purpose`](/en-US/docs/Web/HTTP/Reference/Headers/Sec-Purpose) HTTP {{Glossary("Fetch metadata request header", "fetch metadata request header")}} is now included in requests to {{Glossary("Prefetch")}} resources. This allows servers to provide any special handling that might be needed, such as adjusting the caching expiry for the request ([Firefox bug 1836328](https://bugzil.la/1836328)). ### APIs diff --git a/files/en-us/mozilla/firefox/releases/116/index.md b/files/en-us/mozilla/firefox/releases/116/index.md index 2080d23101ae2ac..72fbf0ca55b7128 100644 --- a/files/en-us/mozilla/firefox/releases/116/index.md +++ b/files/en-us/mozilla/firefox/releases/116/index.md @@ -12,7 +12,7 @@ This article provides information about the changes in Firefox 116 that affect d ### HTML -- The [`dirname`](/en-US/docs/Web/HTML/Element/input#dirname) attribute is now supported on [`input`](/en-US/docs/Web/HTML/Element/input#dirname) and [`textarea`](/en-US/docs/Web/HTML/Element/textarea#dirname) elements. +- The [`dirname`](/en-US/docs/Web/HTML/Reference/Elements/input#dirname) attribute is now supported on [`input`](/en-US/docs/Web/HTML/Reference/Elements/input#dirname) and [`textarea`](/en-US/docs/Web/HTML/Reference/Elements/textarea#dirname) elements. This attribute allows for passing text directionality information (`ltr` or `rtl`) to the server during form submission ([Firefox bug 675943](https://bugzil.la/675943)). ### CSS @@ -21,7 +21,7 @@ This article provides information about the changes in Firefox 116 that affect d ### Accessibility (ARIA) -- The [`image`](/en-US/docs/Web/Accessibility/ARIA/Roles/img_role) role is now supported as a synonym for `img`. +- The [`image`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/img_role) role is now supported as a synonym for `img`. This maintains consistency with most role names which are complete words or concatenations of complete words ([Firefox bug 1829269](https://bugzil.la/1829269)). ### JavaScript @@ -34,11 +34,11 @@ This article provides information about the changes in Firefox 116 that affect d ### SVG -- The `q` [length unit](/en-US/docs/Web/SVG/Content_type#length) (`1q = 1/40th of 1cm`) is now supported ([Firefox bug 1836995](https://bugzil.la/1836995)). +- The `q` [length unit](/en-US/docs/Web/SVG/Guides/Content_type#length) (`1q = 1/40th of 1cm`) is now supported ([Firefox bug 1836995](https://bugzil.la/1836995)). ### HTTP -- Configuring a [Content-Security-Policy](/en-US/docs/Web/HTTP/CSP) now supports specifying [external JavaScript files to be allowlisted using hashes](/en-US/docs/Web/HTTP/Headers/Content-Security-Policy/script-src#allowlisting_external_scripts_using_hashes), where previously only inline scripts could be allowlisted using a hash ([Firefox bug 1409200](https://bugzil.la/1409200)). +- Configuring a [Content-Security-Policy](/en-US/docs/Web/HTTP/Guides/CSP) now supports specifying [external JavaScript files to be allowlisted using hashes](/en-US/docs/Web/HTTP/Reference/Headers/Content-Security-Policy/script-src#allowlisting_external_scripts_using_hashes), where previously only inline scripts could be allowlisted using a hash ([Firefox bug 1409200](https://bugzil.la/1409200)). ### APIs @@ -51,7 +51,7 @@ This article provides information about the changes in Firefox 116 that affect d - The [Audio Output Devices API](/en-US/docs/Web/API/Audio_Output_Devices_API) is now supported on all platforms except for Android. This API allows web applications to redirect audio output to a permitted Bluetooth headset, speakerphone, or other device, instead of having to use the browser or underlying OS default. - Affected APIs include {{domxref("MediaDevices.selectAudioOutput()")}}, {{domxref("MediaDevices.enumerateDevices()")}}, [`HTMLMediaElement.setSinkId()`](/en-US/docs/Web/API/HTMLMediaElement/setSinkId), [`HTMLMediaElement.sinkId`](/en-US/docs/Web/API/HTMLMediaElement/sinkId), and the permission policy [`Permissions-Policy: speaker-selection`](/en-US/docs/Web/HTTP/Headers/Permissions-Policy/speaker-selection) ([Firefox bug 1498512](https://bugzil.la/1498512)). + Affected APIs include {{domxref("MediaDevices.selectAudioOutput()")}}, {{domxref("MediaDevices.enumerateDevices()")}}, [`HTMLMediaElement.setSinkId()`](/en-US/docs/Web/API/HTMLMediaElement/setSinkId), [`HTMLMediaElement.sinkId`](/en-US/docs/Web/API/HTMLMediaElement/sinkId), and the permission policy [`Permissions-Policy: speaker-selection`](/en-US/docs/Web/HTTP/Reference/Headers/Permissions-Policy/speaker-selection) ([Firefox bug 1498512](https://bugzil.la/1498512)). ### WebDriver conformance (WebDriver BiDi, Marionette) diff --git a/files/en-us/mozilla/firefox/releases/117/index.md b/files/en-us/mozilla/firefox/releases/117/index.md index e6570ca5300097d..1b0e8adb8ab0748 100644 --- a/files/en-us/mozilla/firefox/releases/117/index.md +++ b/files/en-us/mozilla/firefox/releases/117/index.md @@ -34,7 +34,7 @@ No notable changes. ### HTTP -- Fixed a bug where the [Content-Security-Policy](/en-US/docs/Web/HTTP/CSP) `'strict-dynamic'` source expression was not being enforced in `default-src` directives. +- Fixed a bug where the [Content-Security-Policy](/en-US/docs/Web/HTTP/Guides/CSP) `'strict-dynamic'` source expression was not being enforced in `default-src` directives. The behavior now matches the specification where `default-src` directive values are used as a fallback when `script-src` is not provided ([Firefox bug 1313937](https://bugzil.la/1313937)). - The `Range` header is now a [CORS-safelisted request header](/en-US/docs/Glossary/CORS-safelisted_request_header) when the value is a single byte range (e.g., `bytes=100-200`). diff --git a/files/en-us/mozilla/firefox/releases/118/index.md b/files/en-us/mozilla/firefox/releases/118/index.md index 43f3efa77fd68e6..4d95a800d936250 100644 --- a/files/en-us/mozilla/firefox/releases/118/index.md +++ b/files/en-us/mozilla/firefox/releases/118/index.md @@ -28,12 +28,12 @@ No notable changes. ### HTTP -- The HTTP [`Permissions-Policy`](/en-US/docs/Web/HTTP/Headers/Permissions-Policy) header's [`publickey-credentials-get`](/en-US/docs/Web/HTTP/Headers/Permissions-Policy/publickey-credentials-get) directive is now supported, which can be used to enable the [Web Authentication API](/en-US/docs/Web/API/Web_Authentication_API) interface for retrieving public-key credentials in a cross-origin iframe ([Firefox bug 1460986](https://bugzil.la/1460986)). +- The HTTP [`Permissions-Policy`](/en-US/docs/Web/HTTP/Reference/Headers/Permissions-Policy) header's [`publickey-credentials-get`](/en-US/docs/Web/HTTP/Reference/Headers/Permissions-Policy/publickey-credentials-get) directive is now supported, which can be used to enable the [Web Authentication API](/en-US/docs/Web/API/Web_Authentication_API) interface for retrieving public-key credentials in a cross-origin iframe ([Firefox bug 1460986](https://bugzil.la/1460986)). ### MathML -- The [`<semantics>`](/en-US/docs/Web/MathML/Element/semantics) and [`<maction>`](/en-US/docs/Web/MathML/Element/maction) elements only render the first child element by default now. The `mathml.legacy_maction_and_semantics_implementations.disabled` preference has been removed (Firefox bug [1788223](https://bugzil.la/1788223)). -- All values of the [`mathvariant`](/en-US/docs/Web/MathML/Element/mi#mathvariant) attribute other than `normal` are now deprecated. Additionally, the attribute's use is now limited to the `<mi>` element (Firefox bug [1845461](https://bugzil.la/1845461)). +- The [`<semantics>`](/en-US/docs/Web/MathML/Reference/Element/semantics) and [`<maction>`](/en-US/docs/Web/MathML/Reference/Element/maction) elements only render the first child element by default now. The `mathml.legacy_maction_and_semantics_implementations.disabled` preference has been removed (Firefox bug [1788223](https://bugzil.la/1788223)). +- All values of the [`mathvariant`](/en-US/docs/Web/MathML/Reference/Element/mi#mathvariant) attribute other than `normal` are now deprecated. Additionally, the attribute's use is now limited to the `<mi>` element (Firefox bug [1845461](https://bugzil.la/1845461)). ### APIs @@ -58,7 +58,7 @@ No notable changes. #### Marionette -- Added support for all the [Web Authentication extension commands](https://www.w3.org/TR/webauthn-2/#sctn-automation), which allow users to authenticate themselves by Public Key Credentials ([Firefox bug 1846574](https://bugzil.la/1846574)) +- Added support for all the [Web Authentication extension commands](https://w3c.github.io/webauthn/#sctn-automation), which allow users to authenticate themselves by Public Key Credentials ([Firefox bug 1846574](https://bugzil.la/1846574)) ## Changes for add-on developers diff --git a/files/en-us/mozilla/firefox/releases/119/index.md b/files/en-us/mozilla/firefox/releases/119/index.md index 4995a66c5c22fe9..11c0294ff4301ec 100644 --- a/files/en-us/mozilla/firefox/releases/119/index.md +++ b/files/en-us/mozilla/firefox/releases/119/index.md @@ -14,25 +14,25 @@ This article provides information about the changes in Firefox 119 that affect d #### Removals -- The {{HTMLElement('input')}} element no longer supports the non-standard `mozactionhint` attribute. Use [`enterkeyhint`](/en-US/docs/Web/HTML/Global_attributes/enterkeyhint) instead. (See [Firefox bug 1735980](https://bugzil.la/1735980) for more details.) +- The {{HTMLElement('input')}} element no longer supports the non-standard `mozactionhint` attribute. Use [`enterkeyhint`](/en-US/docs/Web/HTML/Reference/Global_attributes/enterkeyhint) instead. (See [Firefox bug 1735980](https://bugzil.la/1735980) for more details.) ### CSS -- The {{cssxref("attr")}} CSS function fallback value is now supported. This allows the setting of a fallback value to be used if the [global attribute](/en-US/docs/Web/HTML/Global_attributes) is missing ([Firefox bug 1448248](https://bugzil.la/1448248)). +- The {{cssxref("attr")}} CSS function fallback value is now supported. This allows the setting of a fallback value to be used if the [global attribute](/en-US/docs/Web/HTML/Reference/Global_attributes) is missing ([Firefox bug 1448248](https://bugzil.la/1448248)). ### JavaScript - The {{jsxref("Object.groupBy()")}} and {{jsxref("Map.groupBy()")}} static methods for grouping the elements of an iterable are now supported (See [Firefox bug 1792650](https://bugzil.la/1792650) for more details.) -- The {{jsxref("String.prototype.isWellFormed()")}} and {{jsxref("String.prototype.toWellFormed()")}} methods respectively can be used to check if a string contains well-formed Unicode text (i.e. contains no [lone surrogates](/en-US/docs/Web/JavaScript/Reference/Global_Objects/String#utf-16_characters_unicode_code_points_and_grapheme_clusters)) and sanitize an ill-formed string to well-formed Unicode text. +- The {{jsxref("String.prototype.isWellFormed()")}} and {{jsxref("String.prototype.toWellFormed()")}} methods respectively can be used to check if a string contains well-formed Unicode text (i.e., contains no [lone surrogates](/en-US/docs/Web/JavaScript/Reference/Global_Objects/String#utf-16_characters_unicode_code_points_and_grapheme_clusters)) and sanitize an ill-formed string to well-formed Unicode text. (See [Firefox bug 1850755](https://bugzil.la/1850755) for more details). ### SVG -- The [SVG attributes](/en-US/docs/Web/SVG/Attribute) that accept a [`<length>`](/en-US/docs/Web/SVG/Content_type#length) value now support [level 3](https://www.w3.org/TR/css-values-3/#lengths) {{cssxref("length")}} [CSS data types](/en-US/docs/Web/CSS/CSS_Values_and_Units/CSS_data_types) for all SVG elements. This enables the sizing of SVG elements based on font sizes (`cap`, `rem`, etc.), viewport (`vh`, `vw`, `vmin`, etc.), or absolute lengths (`px`, `cm`, etc.), e.g. `<line x1="10vw" y1="10vh" x2="50vw" y2="50vh"/>`. (See [Firefox bug 1287054](https://bugzil.la/1287054) for more details). +- The [SVG attributes](/en-US/docs/Web/SVG/Reference/Attribute) that accept a [`<length>`](/en-US/docs/Web/SVG/Guides/Content_type#length) value now support [level 3](https://www.w3.org/TR/css-values-3/#lengths) {{cssxref("length")}} [CSS data types](/en-US/docs/Web/CSS/CSS_Values_and_Units/CSS_data_types) for all SVG elements. This enables the sizing of SVG elements based on font sizes (`cap`, `rem`, etc.), viewport (`vh`, `vw`, `vmin`, etc.), or absolute lengths (`px`, `cm`, etc.), e.g., `<line x1="10vw" y1="10vh" x2="50vw" y2="50vh"/>`. (See [Firefox bug 1287054](https://bugzil.la/1287054) for more details). ### HTTP -- The [`credentialless`](/en-US/docs/Web/HTTP/Headers/Cross-Origin-Embedder-Policy#credentialless) directive of the {{HTTPHeader("Cross-Origin-Embedder-Policy")}} HTTP response header is now supported on desktop platforms (and mobile platforms other than Android), allowing `no-cors` requests for resources to be made on cross-origin servers that have not explicitly opted into it, albeit without cookies or other credentials ([Firefox bug 1851467](https://bugzil.la/1851467)). +- The [`credentialless`](/en-US/docs/Web/HTTP/Reference/Headers/Cross-Origin-Embedder-Policy#credentialless) directive of the {{HTTPHeader("Cross-Origin-Embedder-Policy")}} HTTP response header is now supported on desktop platforms (and mobile platforms other than Android), allowing `no-cors` requests for resources to be made on cross-origin servers that have not explicitly opted into it, albeit without cookies or other credentials ([Firefox bug 1851467](https://bugzil.la/1851467)). ### APIs @@ -45,7 +45,7 @@ This article provides information about the changes in Firefox 119 that affect d #### DOM -- [ARIA](/en-US/docs/Web/Accessibility/ARIA) reflection is now supported by default for attributes that do not reference other elements; only non-IDREF attributes are reflected. You can now get and set ARIA attributes on DOM elements directly via JavaScript APIs, rather than by using `setAttribute` and `getAttribute`. For example, `buttonElement.ariaPressed = "true";` is now supported in addition to `buttonElement.setAttribute("aria-pressed", "true");` ([Firefox bug 1785412](https://bugzil.la/1785412)). +- [ARIA](/en-US/docs/Web/Accessibility/ARIA) reflection is now supported by default for attributes that do not reference other elements; only non-ID-reference attributes are reflected. You can now get and set ARIA attributes on DOM elements directly via JavaScript APIs, rather than by using `setAttribute` and `getAttribute`. For example, `buttonElement.ariaPressed = "true";` is now supported in addition to `buttonElement.setAttribute("aria-pressed", "true");` ([Firefox bug 1785412](https://bugzil.la/1785412)). ### WebDriver conformance (WebDriver BiDi, Marionette) diff --git a/files/en-us/mozilla/firefox/releases/12/index.md b/files/en-us/mozilla/firefox/releases/12/index.md index b94b2e7c7a1762a..736f2196396c79e 100644 --- a/files/en-us/mozilla/firefox/releases/12/index.md +++ b/files/en-us/mozilla/firefox/releases/12/index.md @@ -53,7 +53,7 @@ Firefox 12 was shipped on April 24, 2012. This page summarizes the changes in Fi ### MathML -- To control the directionality of MathML formulas, the `dir` attribute is now supported on the {{MathMLElement("math")}}, {{MathMLElement("mrow")}}, and {{MathMLElement("mstyle")}} elements as well as on [MathML Token Elements](/en-US/docs/Web/MathML/Element#token_elements). This is particularly important for some [Arabic mathematical notations](https://www.w3.org/TR/arabic-math/). +- To control the directionality of MathML formulas, the `dir` attribute is now supported on the {{MathMLElement("math")}}, {{MathMLElement("mrow")}}, and {{MathMLElement("mstyle")}} elements as well as on [MathML Token Elements](/en-US/docs/Web/MathML/Reference/Element#token_elements). This is particularly important for some [Arabic mathematical notations](https://www.w3.org/TR/arabic-math/). - The alignment attribute `align` defined in MathML3 has been implemented for {{MathMLElement("munder")}}, {{MathMLElement("mover")}}, and {{MathMLElement("munderover")}}. ### Networking diff --git a/files/en-us/mozilla/firefox/releases/120/index.md b/files/en-us/mozilla/firefox/releases/120/index.md index f310a4fc9482058..38f2ce3af0e6e1a 100644 --- a/files/en-us/mozilla/firefox/releases/120/index.md +++ b/files/en-us/mozilla/firefox/releases/120/index.md @@ -12,7 +12,7 @@ This article provides information about the changes in Firefox 120 that affect d ### HTML -- Support for the `media` attribute in the [`<source>`](/en-US/docs/Web/HTML/Element/source) element has been reintroduced and expanded to include `<audio>` and `<video>` elements. This attribute was first added in Firefox 15 but was removed in Firefox 53 when its use was limited to `<source>` element within `<picture>`. With this release, the `media` attribute will be available in `<source>` elements within `<audio>`, `<video>`, and `<picture>` ([Firefox bug 1836128](https://bugzil.la/1836128)). +- Support for the `media` attribute in the [`<source>`](/en-US/docs/Web/HTML/Reference/Elements/source) element has been reintroduced and expanded to include `<audio>` and `<video>` elements. This attribute was first added in Firefox 15 but was removed in Firefox 53 when its use was limited to `<source>` element within `<picture>`. With this release, the `media` attribute will be available in `<source>` elements within `<audio>`, `<video>`, and `<picture>` ([Firefox bug 1836128](https://bugzil.la/1836128)). ### CSS @@ -45,11 +45,11 @@ This article provides information about the changes in Firefox 120 that affect d - `"YYYY.MM.DD"` - `"Mon DD YYYY hh:mmXm"` (`am`/`pm` directly following time) - - Timezone `'Z'` is now accepted for non-ISO formats (e.g. `Jan 1 1970 10:00Z`) ([Firefox bug 1852422](https://bugzil.la/1852422)) + - Timezone `'Z'` is now accepted for non-ISO formats (e.g., `Jan 1 1970 10:00Z`) ([Firefox bug 1852422](https://bugzil.la/1852422)) ### HTTP -- The [`103 Early Hints`](/en-US/docs/Web/HTTP/Status/103) HTTP [informational response](/en-US/docs/Web/HTTP/Status#informational_responses) status code is enabled for [preconnecting](/en-US/docs/Web/HTML/Attributes/rel/preconnect) to a particular origin (that the page is likely to need resources from). +- The [`103 Early Hints`](/en-US/docs/Web/HTTP/Reference/Status/103) HTTP [informational response](/en-US/docs/Web/HTTP/Reference/Status#informational_responses) status code is enabled for [preconnecting](/en-US/docs/Web/HTML/Reference/Attributes/rel/preconnect) to a particular origin (that the page is likely to need resources from). For more details see [Firefox bug 1858712](https://bugzil.la/1858712). - Firefox supports the [Global Privacy Control](https://globalprivacycontrol.org/) {{HTTPHeader("Sec-GPC")}} request header, which may be sent to indicate that the user does not consent to a website or service selling or sharing their personal information with third parties. Users can enable the header, in both normal and private browsing modes, by setting the preference `privacy.globalprivacycontrol.enabled` to `true` (in `about:config`). diff --git a/files/en-us/mozilla/firefox/releases/121/index.md b/files/en-us/mozilla/firefox/releases/121/index.md index fd57f3f0286dd00..cf4727171346bb5 100644 --- a/files/en-us/mozilla/firefox/releases/121/index.md +++ b/files/en-us/mozilla/firefox/releases/121/index.md @@ -13,14 +13,14 @@ This article provides information about the changes in Firefox 121 that affect d ### HTML - [Lazy loading](/en-US/docs/Web/Performance/Guides/Lazy_loading) of `<iframe>` elements is now supported, allowing developers to hint that particular `<iframe>` elements should only be loaded when (and if) they become visible. This can speed up initial load time by reducing the resources that need to be fetched on page load (some `<iframe>` elements may not need to be fetched at all). - The hint can be provided via the [`loading`](/en-US/docs/Web/HTML/Element/iframe#loading) attribute on the [`<iframe>`](/en-US/docs/Web/HTML/Element/iframe) element, or in JavaScript using {{domxref("HTMLIFrameElement.loading")}}. + The hint can be provided via the [`loading`](/en-US/docs/Web/HTML/Reference/Elements/iframe#loading) attribute on the [`<iframe>`](/en-US/docs/Web/HTML/Reference/Elements/iframe) element, or in JavaScript using {{domxref("HTMLIFrameElement.loading")}}. ([Firefox bug 1622090](https://bugzil.la/1622090)). ### CSS - The {{CSSXRef("text-wrap")}} property has been updated with support for the values `balance` and `stable`. The `balance` value is used for short blocks of content, such as headings, and will make sure that the content is balanced and easy to read when spread over multiple lines. The `stable` value makes sure that editable content does not reflow while the user is editing it ([Firefox bug 1731541](https://bugzil.la/1731541)). -- The {{cssxref(":has", ":has()")}} selector, commonly referred to as the _parent selector_, is now supported. It allows developers to apply styles to an element based on related elements, e.g. `li:has(ul)` will match a list which contains a sub-list, or `h1:has(+ p)` will match a heading with a paragraph directly after it. -- The [`text-indent`](/en-US/docs/Web/CSS/text-indent) CSS property now supports the [`each-line`](/en-US/docs/Web/CSS/text-indent#each-line) and [`hanging`](/en-US/docs/Web/CSS/text-indent#hanging) property values ([Firefox bug 784648](https://bugzil.la/784648)), allowing developers to more easily specify certain text indentation styles. Additionally, developers can now combine multiple `text-indent` property values for more creativity, e.g. `text-indent: 3em hanging each-line`. +- The {{cssxref(":has", ":has()")}} selector, commonly referred to as the _parent selector_, is now supported. It allows developers to apply styles to an element based on related elements, e.g., `li:has(ul)` will match a list which contains a sub-list, or `h1:has(+ p)` will match a heading with a paragraph directly after it. +- The [`text-indent`](/en-US/docs/Web/CSS/text-indent) CSS property now supports the [`each-line`](/en-US/docs/Web/CSS/text-indent#each-line) and [`hanging`](/en-US/docs/Web/CSS/text-indent#hanging) property values ([Firefox bug 784648](https://bugzil.la/784648)), allowing developers to more easily specify certain text indentation styles. Additionally, developers can now combine multiple `text-indent` property values for more creativity, e.g., `text-indent: 3em hanging each-line`. ### JavaScript @@ -28,9 +28,9 @@ This article provides information about the changes in Firefox 121 that affect d - {{jsxref("Date.parse()")}} now accepts several additional date formats: - - Year > 9999 for `YYYY-MMM-DD` format (e.g. `19999-Jan-01`) ([Firefox bug 1858851](https://bugzil.la/1858851)) - - `MMM-DD-YYYY` (e.g. `Jan-01-1970`) ([Firefox bug 1863489](https://bugzil.la/1863489)) - - Milliseconds for non-ISO date formats (e.g. `Jan 1 1970 10:00:00.050`) ([Firefox bug 1863125](https://bugzil.la/1863125)) + - Year > 9999 for `YYYY-MMM-DD` format (e.g., `19999-Jan-01`) ([Firefox bug 1858851](https://bugzil.la/1858851)) + - `MMM-DD-YYYY` (e.g., `Jan-01-1970`) ([Firefox bug 1863489](https://bugzil.la/1863489)) + - Milliseconds for non-ISO date formats (e.g., `Jan 1 1970 10:00:00.050`) ([Firefox bug 1863125](https://bugzil.la/1863125)) - Day of week at the beginning of formats which were being rejected, such as: - `Wed, 1970-01-01` @@ -49,7 +49,7 @@ This article provides information about the changes in Firefox 121 that affect d #### DOM -- {{domxref("HTMLInputElement.showPicker()")}} now works for [`<input type="week">`](/en-US/docs/Web/HTML/Element/input/month) and [`<input type="month">`](/en-US/docs/Web/HTML/Element/input/month) elements on Android ([Firefox bug 1853797](https://bugzil.la/161853797)). +- {{domxref("HTMLInputElement.showPicker()")}} now works for [`<input type="week">`](/en-US/docs/Web/HTML/Reference/Elements/input/month) and [`<input type="month">`](/en-US/docs/Web/HTML/Reference/Elements/input/month) elements on Android ([Firefox bug 1853797](https://bugzil.la/161853797)). ### WebAssembly diff --git a/files/en-us/mozilla/firefox/releases/123/index.md b/files/en-us/mozilla/firefox/releases/123/index.md index b2037bcc2342100..4932992593d6722 100644 --- a/files/en-us/mozilla/firefox/releases/123/index.md +++ b/files/en-us/mozilla/firefox/releases/123/index.md @@ -23,9 +23,9 @@ No notable changes. ### JavaScript - The {{jsxref("Date.parse()")}} global object has had a number of bug fixes to bring it into line with how other browsers parse the values being passed. - - Incorrect day of month (e.g. "31 April") now skips over to the following month (e.g. "1 May"). ([Firefox bug 1872333](https://bugzil.la/1872333)). - - Incomplete time zone (e.g. "1/1/70 gm") or AM/PM (e.g. "1/1/70 10:00 a") are no longer accepted. ([Firefox bug 1870570](https://bugzil.la/1870570)). - - Single number dates are now accepted (e.g. `Date.parse("0")` now returns `946684800000` - Sat Jan 01 2000 00:00:00). ([Firefox bug 1870434](https://bugzil.la/1870434)). + - Incorrect day of month (e.g., "31 April") now skips over to the following month (e.g., "1 May"). ([Firefox bug 1872333](https://bugzil.la/1872333)). + - Incomplete time zone (e.g., "1/1/70 gm") or AM/PM (e.g., "1/1/70 10:00 a") are no longer accepted. ([Firefox bug 1870570](https://bugzil.la/1870570)). + - Single number dates are now accepted (e.g., `Date.parse("0")` now returns `946684800000` - Sat Jan 01 2000 00:00:00). ([Firefox bug 1870434](https://bugzil.la/1870434)). ### SVG @@ -33,15 +33,15 @@ No notable changes. ### HTTP -- The [`103 Early Hints`](/en-US/docs/Web/HTTP/Status/103) HTTP [informational response](/en-US/docs/Web/HTTP/Status#informational_responses) status code is now enabled for [preloading](/en-US/docs/Web/HTML/Attributes/rel/preload) resources that the page is likely to need while the server is still preparing the full response. +- The [`103 Early Hints`](/en-US/docs/Web/HTTP/Reference/Status/103) HTTP [informational response](/en-US/docs/Web/HTTP/Reference/Status#informational_responses) status code is now enabled for [preloading](/en-US/docs/Web/HTML/Reference/Attributes/rel/preload) resources that the page is likely to need while the server is still preparing the full response. This can significantly reduce page load time. - Note that support for using the `103 Early Hints` header for [preconnecting](/en-US/docs/Web/HTML/Attributes/rel/preconnect) was added in [Firefox 120](/en-US/docs/Mozilla/Firefox/Releases/120#http). + Note that support for using the `103 Early Hints` header for [preconnecting](/en-US/docs/Web/HTML/Reference/Attributes/rel/preconnect) was added in [Firefox 120](/en-US/docs/Mozilla/Firefox/Releases/120#http). For more details see [Firefox bug 1874445](https://bugzil.la/1874445). ### APIs - The [Web Authentication API](/en-US/docs/Web/API/Web_Authentication_API) now supports cross-origin credential creation. - Specifically [`navigator.credentials.create({publicKey})`](/en-US/docs/Web/API/CredentialsContainer/create) can now be called in nested browsing contexts loaded from a different origin to the top-most document, if allowed by a [`Feature-Policy: publickey-credentials-create`](/en-US/docs/Web/HTTP/Headers/Permissions-Policy/publickey-credentials-create) on the top level nesting [`<iframe>`](/en-US/docs/Web/HTML/Element/iframe#allow). + Specifically [`navigator.credentials.create({publicKey})`](/en-US/docs/Web/API/CredentialsContainer/create) can now be called in nested browsing contexts loaded from a different origin to the top-most document, if allowed by a [`Feature-Policy: publickey-credentials-create`](/en-US/docs/Web/HTTP/Reference/Headers/Permissions-Policy/publickey-credentials-create) on the top level nesting [`<iframe>`](/en-US/docs/Web/HTML/Reference/Elements/iframe#allow). ([Firefox bug 1870863](https://bugzil.la/1870863)). #### DOM diff --git a/files/en-us/mozilla/firefox/releases/125/index.md b/files/en-us/mozilla/firefox/releases/125/index.md index c03471e1c2926ca..2decfc6b7d3bd1c 100644 --- a/files/en-us/mozilla/firefox/releases/125/index.md +++ b/files/en-us/mozilla/firefox/releases/125/index.md @@ -45,15 +45,15 @@ No notable changes. The following HTML global attributes are supported: - - [`popovertarget`](/en-US/docs/Web/HTML/Element/button#popovertarget) - - [`popovertargetaction`](/en-US/docs/Web/HTML/Element/button#popovertargetaction) + - [`popovertarget`](/en-US/docs/Web/HTML/Reference/Elements/button#popovertarget) + - [`popovertargetaction`](/en-US/docs/Web/HTML/Reference/Elements/button#popovertargetaction) ([Firefox bug 1823757](https://bugzil.la/1823757), [Firefox bug 1866993](https://bugzil.la/1866993)). - The {{domxref("RTCIceTransport")}} properties {{domxref("RTCIceTransport/state","state")}} and {{domxref("RTCIceTransport/gatheringState","gatheringState")}}, and their associated events {{domxref("RTCIceTransport/statechange_event","statechange")}} and {{domxref("RTCIceTransport/gatheringstatechange_event","gatheringstatechange")}}, are now supported, along with the {{domxref("RTCDtlsTransport.iceTransport")}} property (which returns the underlying `RTCIceTransport` for a {{domxref("RTCDtlsTransport")}}). These allow much finer-grained monitoring than provided by the {{domxref("RTCPeerConnection")}} properties {{domxref("RTCPeerConnection.iceGatheringState","iceGatheringState")}} and {{domxref("RTCPeerConnection.connectionState","connectionState")}}. ([Firefox bug 1811912](https://bugzil.la/1811912)) -- {{domxref("Element.ariaBrailleLabel")}} and {{domxref("Element.ariaBrailleRoleDescription")}} are now supported, respectively reflecting the global ARIA HTML attributes [`aria-braillelabel`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-braillelabel) and [`aria-brailleroledescription`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-brailleroledescription). ([Firefox bug 1861201](https://bugzil.la/1861201)). +- {{domxref("Element.ariaBrailleLabel")}} and {{domxref("Element.ariaBrailleRoleDescription")}} are now supported, respectively reflecting the global ARIA HTML attributes [`aria-braillelabel`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-braillelabel) and [`aria-brailleroledescription`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-brailleroledescription). ([Firefox bug 1861201](https://bugzil.la/1861201)). - Added support to allow web applications to gracefully recover if a canvas temporarily loses its 2D context, which might happen if the canvas is running hardware-accelerated on a GPU, and its driver crashes ([Firefox bug 1887729](https://bugzil.la/1887729)). Here are some additional details on the events for lost and restored canvas contexts: @@ -62,8 +62,8 @@ No notable changes. - After emitting `contextlost`, a browser will try and restart the lost context, by default, but code can prevent this by cancelling the event. - Offscreen canvases can be monitored in the same way, but using [`OffScreenCanvas`](/en-US/docs/Web/API/OffscreenCanvas) events [`contextlost`](/en-US/docs/Web/API/OffscreenCanvas/contextlost_event) and [`contextrestored`](/en-US/docs/Web/API/OffscreenCanvas/contextrestored_event), along with [`OffscreenCanvasRenderingContext2D.isContextLost()`](/en-US/docs/Web/API/OffscreenCanvasRenderingContext2D#context). -- Added support for the [`shadowrootclonable`](/en-US/docs/Web/HTML/Element/template#shadowrootclonable) attribute of the `<template>` element, and the [`shadowRootClonable`](/en-US/docs/Web/API/HTMLTemplateElement/shadowRootClonable) property of the `HTMLTemplateElement` interface that reflects it. - These set the [`clonable`](/en-US/docs/Web/API/ShadowRoot/clonable) property of a [`ShadowRoot`](/en-US/docs/Web/API/ShadowRoot) that has been created declaratively using the [`<template>`](/en-US/docs/Web/HTML/Element/template) element. +- Added support for the [`shadowrootclonable`](/en-US/docs/Web/HTML/Reference/Elements/template#shadowrootclonable) attribute of the `<template>` element, and the [`shadowRootClonable`](/en-US/docs/Web/API/HTMLTemplateElement/shadowRootClonable) property of the `HTMLTemplateElement` interface that reflects it. + These set the [`clonable`](/en-US/docs/Web/API/ShadowRoot/clonable) property of a [`ShadowRoot`](/en-US/docs/Web/API/ShadowRoot) that has been created declaratively using the [`<template>`](/en-US/docs/Web/HTML/Reference/Elements/template) element. ([Firefox bug 1880188](https://bugzil.la/1880188)). - The [`readText()`](/en-US/docs/Web/API/Clipboard/readText) method of the [`Clipboard`](/en-US/docs/Web/API/Clipboard) interface is now supported for asynchronously reading text from the system clipboard. @@ -104,7 +104,7 @@ No notable changes. ## Changes for add-on developers -- The content of the {{WebExtAPIRef("proxy.ProxyInfo")}} property `proxyAuthorization` is now passed to the {{httpheader("Proxy-Authorization")}} request header sent to HTTP proxies (in addition to the existing support for HTTPS proxies) as part of a [CONNECT](/en-US/docs/Web/HTTP/Methods/CONNECT) request ([Firefox bug 1794464](https://bugzil.la/1794464)). +- The content of the {{WebExtAPIRef("proxy.ProxyInfo")}} property `proxyAuthorization` is now passed to the {{httpheader("Proxy-Authorization")}} request header sent to HTTP proxies (in addition to the existing support for HTTPS proxies) as part of a [CONNECT](/en-US/docs/Web/HTTP/Reference/Methods/CONNECT) request ([Firefox bug 1794464](https://bugzil.la/1794464)). ## Experimental web features @@ -117,7 +117,7 @@ These features are shipping in Firefox 125 but only in developer releases or beh - **UA styles for `<h1>` nested into sectioning elements:** `layout.css.h1-in-section-ua-styles.enabled`. - The `<h1>` heading doesn't decrease in font size now when nested within [sectioning elements](/en-US/docs/Web/HTML/Content_categories#sectioning_content) `<article>`, `<aside>`, `<nav>`, and `<section>`. The UA styles for `<h1>` nested within sectioning elements are no longer relevant since the outline algorithm [has been removed](https://github.com/whatwg/html/pull/7829) from the HTML specification. ([Firefox bug 1883896](https://bugzil.la/1883896)). + The `<h1>` heading doesn't decrease in font size now when nested within [sectioning elements](/en-US/docs/Web/HTML/Guides/Content_categories#sectioning_content) `<article>`, `<aside>`, `<nav>`, and `<section>`. The UA styles for `<h1>` nested within sectioning elements are no longer relevant since the outline algorithm [has been removed](https://github.com/whatwg/html/pull/7829) from the HTML specification. ([Firefox bug 1883896](https://bugzil.la/1883896)). > [!NOTE] > The preference for this feature works in reverse: it's set to `false` in the Nightly build, which removes the UA styling for headings nested in sectioning elements. It's set to `true` in all other channels, which retains the existing UA styling for the nested headings. diff --git a/files/en-us/mozilla/firefox/releases/126/index.md b/files/en-us/mozilla/firefox/releases/126/index.md index e2c751e74d1794b..c13635bf4698d71 100644 --- a/files/en-us/mozilla/firefox/releases/126/index.md +++ b/files/en-us/mozilla/firefox/releases/126/index.md @@ -34,7 +34,7 @@ No notable changes. ### HTTP -- The [`zstd`](/en-US/docs/Web/HTTP/Headers/Content-Encoding#zstd) directive of the `Content-Encoding` HTTP header is now supported, allowing decoding of server-sent content encoded with the {{glossary("Zstandard compression")}} algorithm ([Firefox bug 1871963](https://bugzil.la/1871963)). +- The [`zstd`](/en-US/docs/Web/HTTP/Reference/Headers/Content-Encoding#zstd) directive of the `Content-Encoding` HTTP header is now supported, allowing decoding of server-sent content encoded with the {{glossary("Zstandard compression")}} algorithm ([Firefox bug 1871963](https://bugzil.la/1871963)). ### APIs @@ -61,7 +61,7 @@ No notable changes. ##### Removals -- The [`<marquee>` HTML element](/en-US/docs/Web/HTML/Element/marquee) events [`bounce`](/en-US/docs/Web/API/HTMLMarqueeElement#bounce), [`finish`](/en-US/docs/Web/API/HTMLMarqueeElement#finish), and [`start`](/en-US/docs/Web/API/HTMLMarqueeElement#start) have been removed from [`HTMLMarqueeElement`](/en-US/docs/Web/API/HTMLMarqueeElement), along with the corresponding [event handler attributes](/en-US/docs/Web/API/HTMLMarqueeElement#events) ([Firefox bug 1689705](https://bugzil.la/1689705)). +- The [`<marquee>` HTML element](/en-US/docs/Web/HTML/Reference/Elements/marquee) events [`bounce`](/en-US/docs/Web/API/HTMLMarqueeElement#bounce), [`finish`](/en-US/docs/Web/API/HTMLMarqueeElement#finish), and [`start`](/en-US/docs/Web/API/HTMLMarqueeElement#start) have been removed from [`HTMLMarqueeElement`](/en-US/docs/Web/API/HTMLMarqueeElement), along with the corresponding [event handler attributes](/en-US/docs/Web/API/HTMLMarqueeElement#events) ([Firefox bug 1689705](https://bugzil.la/1689705)). - The [Theora](/en-US/docs/Web/Media/Guides/Formats/Video_codecs#theora) codec was disabled by default, and will be removed in a future release ([Firefox bug 1860492](https://bugzil.la/1860492)). ### WebDriver conformance (WebDriver BiDi, Marionette) @@ -70,7 +70,7 @@ No notable changes. - Added the `contexts` argument to the `network.addIntercept` command to limit the interception of network requests to particular top-level browsing contexts ([Firefox bug 1882260](https://bugzil.la/1882260)). - Both the commands `session.subscribe` and `session.unsubscribe` now raise an `invalid argument` error when the value of the arguments `events` or `contexts` are empty arrays ([Firefox bug 1887871](https://bugzil.la/1887871)). -- Updated the implementation of the `storage.getCookies` command to align with the Gecko default cookie behaviour. This allows the removal of the user value for the preference `network.cookie.cookieBehavior`, which was only expected to be set for our CDP implementation ([Firefox bug 1879503](https://bugzil.la/1879503)). +- Updated the implementation of the `storage.getCookies` command to align with the Gecko default cookie behavior. This allows the removal of the user value for the preference `network.cookie.cookieBehavior`, which was only expected to be set for our CDP implementation ([Firefox bug 1879503](https://bugzil.la/1879503)). - Removed the `ownership` and `sandbox` arguments for the `browsingContext.locateNodes` command because they are no longer necessary ([Firefox bug 1884935](https://bugzil.la/1884935)). - Improved error message for the `session.new` command when no capabilities are specified ([Firefox bug 1838152](https://bugzil.la/1838152)). diff --git a/files/en-us/mozilla/firefox/releases/127/index.md b/files/en-us/mozilla/firefox/releases/127/index.md index 5968e91077d9d50..f5c7858d55b7050 100644 --- a/files/en-us/mozilla/firefox/releases/127/index.md +++ b/files/en-us/mozilla/firefox/releases/127/index.md @@ -12,7 +12,7 @@ This article provides information about the changes in Firefox 127 that affect d ### HTML -- [`data:`](/en-US/docs/Web/URI/Reference/Schemes/data) and [`javascript:`](/en-US/docs/Web/URI/Reference/Schemes/javascript) URLs are now forbidden in the [`href`](/en-US/docs/Web/HTML/Element/base#href) attribute of the `<base>` element ([Firefox bug 1850967](https://bugzil.la/1850967)). +- [`data:`](/en-US/docs/Web/URI/Reference/Schemes/data) and [`javascript:`](/en-US/docs/Web/URI/Reference/Schemes/javascript) URLs are now forbidden in the [`href`](/en-US/docs/Web/HTML/Reference/Elements/base#href) attribute of the `<base>` element ([Firefox bug 1850967](https://bugzil.la/1850967)). ### CSS diff --git a/files/en-us/mozilla/firefox/releases/128/index.md b/files/en-us/mozilla/firefox/releases/128/index.md index 6c42745dc29df97..23d0a8d49e74c98 100644 --- a/files/en-us/mozilla/firefox/releases/128/index.md +++ b/files/en-us/mozilla/firefox/releases/128/index.md @@ -12,7 +12,7 @@ This article provides information about the changes in Firefox 128 that affect d ### HTML -- The [`target`](/en-US/docs/Web/HTML/Element/base#target) attribute of the `<base>` element now disallows ASCII newlines, tabs, or the `<` character, changing the value to `_blank` if any are present. This prevents dangling markup injection attacks that use an unclosed `target` attribute ([Firefox bug 1835157](https://bugzil.la/1835157)). +- The [`target`](/en-US/docs/Web/HTML/Reference/Elements/base#target) attribute of the `<base>` element now disallows ASCII newlines, tabs, or the `<` character, changing the value to `_blank` if any are present. This prevents dangling markup injection attacks that use an unclosed `target` attribute ([Firefox bug 1835157](https://bugzil.la/1835157)). ### CSS @@ -38,8 +38,8 @@ This article provides information about the changes in Firefox 128 that affect d ### HTTP -- The HTTP [`Accept`](/en-US/docs/Web/HTTP/Headers/Accept) header in [default requests and image requests](/en-US/docs/Web/HTTP/Content_negotiation/List_of_default_Accept_values) now includes the `image/svg+xml` MIME type ([Firefox bug 1711622](https://bugzil.la/1711622)). -- The {{rfc("9218", "Extensible Prioritization Scheme for HTTP")}} is now supported, including the HTTP [`Priority`](/en-US/docs/Web/HTTP/Headers/Priority) request and response header, which allows clients to hint at the expected relative priority for resources sent over a connection, and the HTTP/2 and HTTP/3 `PRIORITY_UPDATE` frames that allow the priority to be subsequently changed after the header has been sent ([Firefox bug 1865040](https://bugzil.la/1865040)). +- The HTTP [`Accept`](/en-US/docs/Web/HTTP/Reference/Headers/Accept) header in [default requests and image requests](/en-US/docs/Web/HTTP/Guides/Content_negotiation/List_of_default_Accept_values) now includes the `image/svg+xml` MIME type ([Firefox bug 1711622](https://bugzil.la/1711622)). +- The {{rfc("9218", "Extensible Prioritization Scheme for HTTP")}} is now supported, including the HTTP [`Priority`](/en-US/docs/Web/HTTP/Reference/Headers/Priority) request and response header, which allows clients to hint at the expected relative priority for resources sent over a connection, and the HTTP/2 and HTTP/3 `PRIORITY_UPDATE` frames that allow the priority to be subsequently changed after the header has been sent ([Firefox bug 1865040](https://bugzil.la/1865040)). ### APIs @@ -92,10 +92,11 @@ This article provides information about the changes in Firefox 128 that affect d - The non-standard Web API events `overflow` and `underflow` have been deprecated. Use of these events should be removed from extension documents before the release of Firefox 131 ([Firefox bug 1898445](https://bugzil.la/1898445)). - Support is now provided for scripts to run in the web page execution environment. This is provided through support for `MAIN` in {{WebExtAPIRef("scripting.executionWorld","ExecutionWorld")}} for the {{WebExtAPIRef("scripting")}} API, the addition of `world` to the {{WebExtAPIRef("contentScripts.register()")}} API, and support for `world` in the [`content_scripts`](/en-US/docs/Mozilla/Add-ons/WebExtensions/manifest.json/content_scripts) manifest key ([Firefox bug 1736575](https://bugzil.la/1736575)). - The {{WebExtAPIRef("scripting")}} API can now inject scripts and CSS into sandboxed pages with `about:blank`, `about:srcdoc`, and `data:` URLs. This was implemented for {{WebExtAPIRef("scripting.executeScript")}}, {{WebExtAPIRef("scripting.insertCSS")}}, and {{WebExtAPIRef("scripting.removeCSS")}} in [Firefox bug 1475831](https://bugzil.la/1475831) and {{WebExtAPIRef("scripting.registerContentScripts")}} and {{WebExtAPIRef("scripting.updateContentScripts")}} in [Firefox bug 1853411](https://bugzil.la/1853411) through the introduction of `matchOriginAsFallback` to {{WebExtAPIRef("scripting.RegisteredContentScript")}}. -- Content scripts now run on [sandboxed](/en-US/docs/Web/HTTP/Headers/Content-Security-Policy/sandbox) `http`, `https`, and `file:` URLs ([Firefox bug 1411641](https://bugzil.la/1411641)). +- Content scripts now run on [sandboxed](/en-US/docs/Web/HTTP/Reference/Headers/Content-Security-Policy/sandbox) `http`, `https`, and `file:` URLs ([Firefox bug 1411641](https://bugzil.la/1411641)). - The [manifest key `content_scripts`](/en-US/docs/Mozilla/Add-ons/WebExtensions/manifest.json/content_scripts) now supports `match_origin_as_fallback` and {{WebExtAPIRef("contentScripts.register")}} `matchOriginAsFallback`, enabling scripts to be injected into `about:`, `data:`, and `blob:` pages when the document origin is opaque due to the use of CSP or iframe sandbox ([Firefox bug 1475831](https://bugzil.la/1475831) and [Firefox bug 1896669](https://bugzil.la/1896669)). In addition, scripts registered with the `content_scripts` manifest key can now only run in `blob:` pages when `match_origin_as_fallback` is `true` ([Firefox bug 1897113](https://bugzil.la/1897113)). - Support added for the {{WebExtAPIRef("declarativeNetRequest.RuleCondition")}} property `domainType` ([Firefox bug 1797408](https://bugzil.la/1797408)). - Extensions containing an unrecognized property in [manifest key `browser_specific_settings.gecko`](/en-US/docs/Mozilla/Add-ons/WebExtensions/manifest.json/browser_specific_settings) now load with a warning. Previously, these extensions errored on installation. This ensures that if a new `browser_specific_settings.gecko` property is added, extensions using that new property will load in versions of Firefox back to this release ([Firefox bug 1757293](https://bugzil.la/1757293)). +- Context menus created with {{WebExtAPIRef("menus.create")}} in extensions using a non-persistent background script now persist more reliably across extension restarts. Previously, there were cases where the menu registration disappeared on restarts ([Firefox bug 1771328](https://bugzil.la/1771328)). ## Experimental web features @@ -103,15 +104,15 @@ These features are newly shipped in Firefox 128 but are disabled by default. To - **`image/jxl` MIME type in Accept header for default and image requests:** `image.jxl.enabled`. - The HTTP [`Accept`](/en-US/docs/Web/HTTP/Headers/Accept) header in [default requests and image requests](/en-US/docs/Web/HTTP/Content_negotiation/List_of_default_Accept_values) can be configured to indicate support for the `image/jxl` MIME type. ([Firefox bug 1711622](https://bugzil.la/1711622)). + The HTTP [`Accept`](/en-US/docs/Web/HTTP/Reference/Headers/Accept) header in [default requests and image requests](/en-US/docs/Web/HTTP/Guides/Content_negotiation/List_of_default_Accept_values) can be configured to indicate support for the `image/jxl` MIME type. ([Firefox bug 1711622](https://bugzil.la/1711622)). - **Cookies Having Independent Partitioned State (CHIPS):** `network.cookie.CHIPS.enabled`. - [CHIPS](/en-US/docs/Web/Privacy/Guides/Privacy_sandbox/Partitioned_cookies), or "partitioned cookies", allow developers to opt a cookie into partitioned storage using the [`partitioned`](/en-US/docs/Web/HTTP/Headers/Set-Cookie#partitioned) directive of the `Set-Cookie` HTTP header. When set, cookies have separate storage for each top-level site, and can only be read within the same top-level site they were set on and its subdomains. This blocks cross-site tracking, while still enabling legitimate uses of third-party cookies such as persisting state of embedded maps or chat widgets across different subdomains of a site. ([Firefox bug 1898253](https://bugzil.la/1898253)). + [CHIPS](/en-US/docs/Web/Privacy/Guides/Privacy_sandbox/Partitioned_cookies), or "partitioned cookies", allow developers to opt a cookie into partitioned storage using the [`partitioned`](/en-US/docs/Web/HTTP/Reference/Headers/Set-Cookie#partitioned) directive of the `Set-Cookie` HTTP header. When set, cookies have separate storage for each top-level site, and can only be read within the same top-level site they were set on and its subdomains. This blocks cross-site tracking, while still enabling legitimate uses of third-party cookies such as persisting state of embedded maps or chat widgets across different subdomains of a site. ([Firefox bug 1898253](https://bugzil.la/1898253)). - **Privacy Preserving Attribution API (PPA):** `dom.origin-trials.private-attribution.state`. - [PPA API](https://support.mozilla.org/en-US/kb/privacy-preserving-attribution) provides an alternative to user tracking for ad attribution using the new `navigator.privateAttribution` object with `saveImpression()` and `measureConversion()` methods. Read more about PPA [in the explainer](https://github.com/mozilla/explainers/tree/main/ppa-experiment). This experiment can be enabled for websites via [origin trial](https://wiki.mozilla.org/Origin_Trials) or in the browser by setting the preference to `1`. ([Firefox bug 1900929](https://bugzil.la/1900929)). + [PPA API](https://support.mozilla.org/en-US/kb/privacy-preserving-attribution) provides an alternative to user tracking for ad attribution using the new `navigator.privateAttribution` object with `saveImpression()` and `measureConversion()` methods. Read more about PPA [in the original explainer](https://github.com/mozilla/explainers/tree/main/archive/ppa-experiment) and the [proposed spec](https://w3c.github.io/ppa/). This experiment can be enabled for websites via [origin trial](https://wiki.mozilla.org/Origin_Trials) or in the browser by setting the preference to `1`. ([Firefox bug 1900929](https://bugzil.la/1900929)). ## Older versions diff --git a/files/en-us/mozilla/firefox/releases/129/index.md b/files/en-us/mozilla/firefox/releases/129/index.md index 32739812f7b60e2..fef66b936274857 100644 --- a/files/en-us/mozilla/firefox/releases/129/index.md +++ b/files/en-us/mozilla/firefox/releases/129/index.md @@ -32,10 +32,10 @@ This article provides information about the changes in Firefox 129 that affect d ([Firefox bug 1901923](https://bugzil.la/1901923).) - The default `.toJSON()` methods {{domxref("GeolocationCoordinates.toJSON()")}} and {{domxref("GeolocationPosition.toJSON()")}} are now supported, enabling serialization of `GeolocationCoordinates` and `GeolocationPosition` objects with {{jsxref("JSON.stringify()")}} ([Firefox bug 1890706](https://bugzil.la/1890706)). - {{domxref("CSSPageDescriptors")}} is now supported, and is used as the type for {{domxref("CSSPageRule.style")}} instead of {{domxref("CSSStyleDeclaration")}} — matching the current specification. - This ensures that `CSSPageDescriptors` only exposes the `@page` related properties, rather than all properties, and also resolves an issue where setting the page [`size`](/en-US/docs/Web/CSS/@page#size) in a CSS `@page` at-rule was not reflected in `CSSPageRule.style`. + This ensures that `CSSPageDescriptors` only exposes the `@page` related properties, rather than all properties, and also resolves an issue where setting the page [`size`](/en-US/docs/Web/CSS/@page/size) in a CSS `@page` at-rule was not reflected in `CSSPageRule.style`. ([Firefox bug 1890842](https://bugzil.la/1890842), [Firefox bug 1867106](https://bugzil.la/1867106).) - {{domxref('MediaCapabilities.decodingInfo()')}} can now get decoding information for a particular _encrypted media_ configuration as well unencrypted media, allowing applications to tell ahead of time if the configuration is supported, and whether it will play the content smoothly and be power efficient. Changes include a new property `keySystemConfiguration` on the method's `configuration` argument that defines the properties of the key system used to encrypt the media, and a new `keySystemAccess` property on the returned object, which is a {{domxref('MediaKeySystemAccess')}} object that can be used to create keys and decode the content for playback. ([Firefox bug 1898344](https://bugzil.la/1898344)). -- Firefox now fires events for a synchronous {{domxref("XMLHttpRequest")}} before firing the events for any ongoing asynchronous `XMLHttpRequest`. This fixes a long-standing behavioral difference with other browsers. Note that while this should fix some sites, it may also cause degraded performance on sites that expect the old "non-blocking" behaviour for a synchronous `XMLHttpRequest`. Please [file a bug](https://bugzil.la/) if your website should have been fixed by this change but still appears to have related issues. ([Firefox bug 697151](https://bugzil.la/697151).) +- Firefox now fires events for a synchronous {{domxref("XMLHttpRequest")}} before firing the events for any ongoing asynchronous `XMLHttpRequest`. This fixes a long-standing behavioral difference with other browsers. Note that while this should fix some sites, it may also cause degraded performance on sites that expect the old "non-blocking" behavior for a synchronous `XMLHttpRequest`. Please [file a bug](https://bugzil.la/) if your website should have been fixed by this change but still appears to have related issues. ([Firefox bug 697151](https://bugzil.la/697151).) - The [Ed25519](/en-US/docs/Web/API/SubtleCrypto/sign#ed25519) digital signature algorithm is supported by the [Web Crypto API](/en-US/docs/Web/API/Web_Crypto_API), and can be used in the {{domxref("SubtleCrypto")}} methods: {{domxref("SubtleCrypto.sign()", "sign()")}}, {{domxref("SubtleCrypto.verify()", "verify()")}}, {{domxref("SubtleCrypto.generateKey()", "generateKey()")}}, {{domxref("SubtleCrypto.importKey()", "importKey()")}} and {{domxref("SubtleCrypto.exportKey()", "exportKey()")}} ([Firefox bug 1804788](https://bugzil.la/1804788)). - The {{domxref("PerformanceResourceTiming.contentType","contentType")}} and {{domxref("PerformanceResourceTiming.responseStatus","responseStatus")}} properties of the {{domxref("PerformanceResourceTiming")}} interface are now supported, indicating the content type of the fetched resource and the HTTP response status code returned when fetching the resource, respectively. ([Firefox bug 1800443](https://bugzil.la/1800443), [Firefox bug 1796785](https://bugzil.la/1796785).) - The {{domxref("RTCDTMFSender.canInsertDTMF")}} property is now supported. It enables you to check whether a WebRTC sender can insert DTMF tones into the outgoing connection. If supported, you can insert DTMF tones by using {{domxref("RTCDTMFSender.insertDTMF()")}}. ([Firefox bug 1623193](https://bugzil.la/1623193)). diff --git a/files/en-us/mozilla/firefox/releases/13/index.md b/files/en-us/mozilla/firefox/releases/13/index.md index 96850b705fb30e3..27082925d9ae8b5 100644 --- a/files/en-us/mozilla/firefox/releases/13/index.md +++ b/files/en-us/mozilla/firefox/releases/13/index.md @@ -12,14 +12,14 @@ Firefox 13 was shipped on June 5, 2012. This page summarizes the changes in Fire ### HTML -- Tables' [`cellspacing`](/en-US/docs/Web/HTML/Element/table#cellspacing) attributes are now parsed the same outside quirks mode as they are in quirks mode. That is, if a value is specified as a percentage, it's treated as a number of pixels instead, since percentage values are not actually permitted according to the specification. +- Tables' [`cellspacing`](/en-US/docs/Web/HTML/Reference/Elements/table#cellspacing) attributes are now parsed the same outside quirks mode as they are in quirks mode. That is, if a value is specified as a percentage, it's treated as a number of pixels instead, since percentage values are not actually permitted according to the specification. - The {{htmlelement("wbr")}} element has seen its bidirectional behavior fixed. It now behaves like the Unicode `U+200B ZERO-WIDTH SPACE` and therefore doesn't affect bi-directionality of its parent element anymore. - The {{Cssxref(":invalid")}} pseudo-class can now be applied to the {{htmlelement("form")}} element. ### CSS - The `turn` {{cssxref("&lt;angle&gt;")}} unit is now supported (to be used with CSS functions like `rotate()`). -- Support for 3-to-4 value syntax of the {{cssxref("background-position")}} has been added. You can offset a background image from any corner by writing like "`right 10px bottom 20px`". See [Firefox bug 522607](https://bugzil.la/522607) +- Support for 3-to-4 value syntax of the {{cssxref("background-position")}} has been added. You can offset a background image from any corner by writing like `right 10px bottom 20px`. See [Firefox bug 522607](https://bugzil.la/522607) - Support for the 2-value syntax of the CSS {{cssxref("background-repeat")}} has been added. - Support for {{cssxref("border-radius","-moz-border-radius*")}} and {{cssxref("box-shadow","-moz-box-shadow")}} has been removed. Authors should use unprefixed `border-radius` or `box-shadow` instead. See [Firefox bug 693510](https://bugzil.la/693510) - The {{cssxref("column-fill")}} property has been implemented (prefixed). diff --git a/files/en-us/mozilla/firefox/releases/130/index.md b/files/en-us/mozilla/firefox/releases/130/index.md index 0ba347f2afe7810..b1b4c945b4e9b96 100644 --- a/files/en-us/mozilla/firefox/releases/130/index.md +++ b/files/en-us/mozilla/firefox/releases/130/index.md @@ -12,8 +12,8 @@ This article provides information about the changes in Firefox 130 that affect d ### HTML -- The [`name`](/en-US/docs/Web/HTML/Element/details#name) attribute of the `<details>` element now allows the grouping of `<details>` elements, where only one element within a group can be open at a time. This allows you to create an exclusive accordion without using JavaScript ([Firefox bug 1856460](https://bugzil.la/1856460) and [Firefox bug 1909613](https://bugzil.la/1909613)). -- The [`dir`](/en-US/docs/Web/HTML/Global_attributes/dir) and [`lang`](/en-US/docs/Web/HTML/Global_attributes/lang) [global attributes](/en-US/docs/Web/HTML/Global_attributes) now have improved inheritance, including how they work with [shadow DOM](/en-US/docs/Web/API/Web_components/Using_shadow_DOM#attribute_inheritance) ([Firefox bug 1876163](https://bugzil.la/1876163)). +- The [`name`](/en-US/docs/Web/HTML/Reference/Elements/details#name) attribute of the `<details>` element now allows the grouping of `<details>` elements, where only one element within a group can be open at a time. This allows you to create an exclusive accordion without using JavaScript ([Firefox bug 1856460](https://bugzil.la/1856460) and [Firefox bug 1909613](https://bugzil.la/1909613)). +- The [`dir`](/en-US/docs/Web/HTML/Reference/Global_attributes/dir) and [`lang`](/en-US/docs/Web/HTML/Reference/Global_attributes/lang) [global attributes](/en-US/docs/Web/HTML/Reference/Global_attributes) now have improved inheritance, including how they work with [shadow DOM](/en-US/docs/Web/API/Web_components/Using_shadow_DOM#attribute_inheritance) ([Firefox bug 1876163](https://bugzil.la/1876163)). ### CSS @@ -40,7 +40,7 @@ This article provides information about the changes in Firefox 130 that affect d - Added support for the `browsingContext.navigationFailed` event, which is triggered when a navigation attempt fails to complete ([Firefox bug 1846601](https://bugzil.la/1846601)). - The `network.setCacheBehavior` command now allows defining the network cache behavior both globally and for individual navigables simultaneously ([Firefox bug 1905307](https://bugzil.la/1905307)). -- The `network.responseCompleted` and `network.fetchError`events are now emitted when the actual request stops, eliminating a race condition where `browsingContext.domContentLoaded` and `browsingContext.load` events were emitted before the `network.responseCompleted` event ([Firefox bug 1882803](https://bugzil.la/1882803)). +- The `network.responseCompleted` and `network.fetchError` events are now emitted when the actual request stops, eliminating a race condition where `browsingContext.domContentLoaded` and `browsingContext.load` events were emitted before the `network.responseCompleted` event ([Firefox bug 1882803](https://bugzil.la/1882803)). - Data URLs (e.g., for background images or fetch requests) are now fully supported across all network events ([Firefox bug 1904343](https://bugzil.la/1904343)). - Fixed an issue where the `network.authRequired` event was sent out multiple times with each call to the `network.continueWithAuth` command ([Firefox bug 1899711](https://bugzil.la/1899711)). @@ -64,7 +64,7 @@ These features are newly shipped in Firefox 130 but are disabled by default. To - **CSP violation reports using the Reporting API:** `dom.reporting.enabled`. - The [Reporting API](/en-US/docs/Web/API/Reporting_API) can be used for reporting [Content Security Policy (CSP)](/en-US/docs/Web/HTTP/CSP) violations. + The [Reporting API](/en-US/docs/Web/API/Reporting_API) can be used for reporting [Content Security Policy (CSP)](/en-US/docs/Web/HTTP/Guides/CSP) violations. This includes support for {{domxref('Report')}} objects that have a `type` property with the value `"csp-violation"` and `body` property that is an instance of the {{domxref('CSPViolationReportBody')}} interface, the {{CSP("report-to")}} directive of the {{httpheader('Content-Security-Policy')}} HTTP response header, and the {{httpheader('Reporting-Endpoints')}} and {{httpheader('Report-To')}} HTTP response headers. This feature is disabled by default. ([Firefox bug 1391243](https://bugzil.la/1391243)). diff --git a/files/en-us/mozilla/firefox/releases/131/index.md b/files/en-us/mozilla/firefox/releases/131/index.md index ad8224f38796a07..e12b607852e3c39 100644 --- a/files/en-us/mozilla/firefox/releases/131/index.md +++ b/files/en-us/mozilla/firefox/releases/131/index.md @@ -20,9 +20,9 @@ This article provides information about the changes in Firefox 131 that affect d ### HTTP -- A {{httpheader("Set-Cookie")}} HTTP header with the attribute value of [`SameSite=None`](/en-US/docs/Web/HTTP/Headers/Set-Cookie#none) must now also include the [`Secure`](/en-US/docs/Web/HTTP/Headers/Set-Cookie#secure) attribute. This ensures that cookies set with `SameSite=None` are only ever sent over HTTPS channels. In addition, since Firefox interprets an unspecified `SameSite` value as `SameSite=None`, cookies that don't specify `SameSite` will have the same restriction. ([Firefox bug 1909673](https://bugzil.la/1909673)). +- A {{httpheader("Set-Cookie")}} HTTP header with the attribute value of [`SameSite=None`](/en-US/docs/Web/HTTP/Reference/Headers/Set-Cookie#none) must now also include the [`Secure`](/en-US/docs/Web/HTTP/Reference/Headers/Set-Cookie#secure) attribute. This ensures that cookies set with `SameSite=None` are only ever sent over HTTPS channels. In addition, since Firefox interprets an unspecified `SameSite` value as `SameSite=None`, cookies that don't specify `SameSite` will have the same restriction. ([Firefox bug 1909673](https://bugzil.la/1909673)). - [Cookies Having Independent Partitioned State (CHIPS)](/en-US/docs/Web/Privacy/Guides/Privacy_sandbox/Partitioned_cookies), or "partitioned cookies", are now supported. - This feature allows developers to opt a cookie into partitioned storage using the [`partitioned`](/en-US/docs/Web/HTTP/Headers/Set-Cookie#partitioned) directive of the {{HTTPHeader("Set-Cookie")}} HTTP header. When set, cookies have separate storage for each top-level site and can only be read within the same top-level site they were set on and its subdomains. This blocks cross-site tracking while still enabling legitimate uses of third-party cookies, such as persisting state of embedded maps or chat widgets across different subdomains of a site. ([Firefox bug 1908160](https://bugzil.la/1908160)). + This feature allows developers to opt a cookie into partitioned storage using the [`partitioned`](/en-US/docs/Web/HTTP/Reference/Headers/Set-Cookie#partitioned) directive of the {{HTTPHeader("Set-Cookie")}} HTTP header. When set, cookies have separate storage for each top-level site and can only be read within the same top-level site they were set on and its subdomains. This blocks cross-site tracking while still enabling legitimate uses of third-party cookies, such as persisting state of embedded maps or chat widgets across different subdomains of a site. ([Firefox bug 1908160](https://bugzil.la/1908160)). ### APIs diff --git a/files/en-us/mozilla/firefox/releases/132/index.md b/files/en-us/mozilla/firefox/releases/132/index.md index 819b4401d91d48b..9d884b9772a3ad9 100644 --- a/files/en-us/mozilla/firefox/releases/132/index.md +++ b/files/en-us/mozilla/firefox/releases/132/index.md @@ -21,7 +21,7 @@ No notable changes #### Removals -- The [`-moz-user-modify`](/en-US/docs/Web/CSS/user-modify) CSS property has been removed. This property has been deprecated in favour of the [`contenteditable`](/en-US/docs/Web/HTML/Global_attributes/contenteditable) global attribute. ([Firefox bug 1920118](https://bugzil.la/1920118)). +- The [`-moz-user-modify`](/en-US/docs/Web/CSS/user-modify) CSS property has been removed. This property has been deprecated in favor of the [`contenteditable`](/en-US/docs/Web/HTML/Reference/Global_attributes/contenteditable) global attribute. ([Firefox bug 1920118](https://bugzil.la/1920118)). ### JavaScript @@ -29,7 +29,7 @@ No notable changes ### HTTP -- The [default/document value](/en-US/docs/Web/HTTP/Content_negotiation/List_of_default_Accept_values#default_values) of the HTTP {{httpheader("Accept")}} header was changed to `text/html,application/xhtml+xml,application/xml;q=0.9,*/*;q=0.8`. +- The [default/document value](/en-US/docs/Web/HTTP/Guides/Content_negotiation/List_of_default_Accept_values#default_values) of the HTTP {{httpheader("Accept")}} header was changed to `text/html,application/xhtml+xml,application/xml;q=0.9,*/*;q=0.8`. This removes image MIME types that sometimes caused compatibility issues, and aligns with the fetch specification and Safari. ([Firefox bug 1917177](https://bugzil.la/1917177)). #### Removals @@ -81,12 +81,12 @@ These features are newly shipped in Firefox 132 but are disabled by default. To The global {{domxref('Window.fetch','fetch()')}} method has a [`keepalive`](/en-US/docs/Web/API/RequestInit#keepalive) initialization option. When `keepalive` is set to `true`, the browser will not abort the associated request if the page that initiated it is unloaded before the request is complete. - This enables a fetch request to function as an alternative to {{domxref("Navigator.sendBeacon()")}} when sending analytics at the end of a session, which has some advantages (you can use HTTP methods other than [`POST`](/en-US/docs/Web/HTTP/Methods/POST), customize request properties, and access the server response via the fetch {{jsxref("Promise")}} fulfillment). It is also available in [service workers](/en-US/docs/Web/API/Service_Worker_API). ([Firefox bug 1906952](https://bugzil.la/1906952)). + This enables a fetch request to function as an alternative to {{domxref("Navigator.sendBeacon()")}} when sending analytics at the end of a session, which has some advantages (you can use HTTP methods other than [`POST`](/en-US/docs/Web/HTTP/Reference/Methods/POST), customize request properties, and access the server response via the fetch {{jsxref("Promise")}} fulfillment). It is also available in [service workers](/en-US/docs/Web/API/Service_Worker_API). ([Firefox bug 1906952](https://bugzil.la/1906952)). - **`CloseWatcher`**: <code>dom.closewatcher.enabled</code>. The {{domxref("CloseWatcher")}} interface enables developers to implement components that can be closed using device-native mechanisms, in the same way as built-in components. For example, on Android you can close a dialog using the back button: this interface allows you to similarly close a custom sidebar. ([Firefox bug 1888729](https://bugzil.la/1888729)). -- **`Promise.try()`**: <code>javascript.options.experimental.promise_try</code>. {{jsxref("Promise.try()")}} is a convenience method that takes a callback of any kind (returns or throws, synchronously or asynchronously) and wraps its result in a {{jsxref("Promise")}} so that promise semantics (e.g. {{jsxref("Promise.then", ".then()")}}, {{jsxref("Promise.catch", ".catch()")}}) can be used to handle it ([Firefox bug 1905364](https://bugzil.la/1905364)). +- **`Promise.try()`**: <code>javascript.options.experimental.promise_try</code>. {{jsxref("Promise.try()")}} is a convenience method that takes a callback of any kind (returns or throws, synchronously or asynchronously) and wraps its result in a {{jsxref("Promise")}} so that promise semantics (e.g., {{jsxref("Promise.then", ".then()")}}, {{jsxref("Promise.catch", ".catch()")}}) can be used to handle it ([Firefox bug 1905364](https://bugzil.la/1905364)). - **`JSON.parse` with source**: <code>javascript.options.experimental.json_parse_with_source</code>. The [`JSON.parse` source text access proposal](https://github.com/tc39/proposal-json-parse-with-source) extends `JSON.parse` behavior to provide features to mitigate issues around loss of precision when converting values such as large floats and date values between JavaScript values and JSON text ([Firefox bug 1913085](https://bugzil.la/1913085), [Firefox bug 1925334](https://bugzil.la/1925334)). Specifically, the following features are now available: - The `JSON.parse()` [`reviver` parameter `context` argument](/en-US/docs/Web/JavaScript/Reference/Global_Objects/JSON/parse#the_reviver_parameter): Provides access to the original JSON source text that was parsed. diff --git a/files/en-us/mozilla/firefox/releases/133/index.md b/files/en-us/mozilla/firefox/releases/133/index.md index f325d0d4a424ce2..59038e4e8c0c89f 100644 --- a/files/en-us/mozilla/firefox/releases/133/index.md +++ b/files/en-us/mozilla/firefox/releases/133/index.md @@ -12,7 +12,7 @@ This article provides information about the changes in Firefox 133 that affect d ### HTML -- The [`viewport <meta>` tag](/en-US/docs/Web/HTML/Viewport_meta_tag) now supports the [`interactive-widget`](/en-US/docs/Web/HTML/Viewport_meta_tag#the_effect_of_interactive_ui_widgets) attribute, this influences the size of the viewport when common UI widgets, such as virtual keyboards, are added to the screen. ([Firefox bug 1831649](https://bugzil.la/1831649) and [Firefox bug 1920755](https://bugzil.la/1920755)). +- The [`viewport <meta>` tag](/en-US/docs/Web/HTML/Guides/Viewport_meta_element) now supports the [`interactive-widget`](/en-US/docs/Web/HTML/Guides/Viewport_meta_element#the_effect_of_interactive_ui_widgets) attribute, this influences the size of the viewport when common UI widgets, such as virtual keyboards, are added to the screen. ([Firefox bug 1831649](https://bugzil.la/1831649) and [Firefox bug 1920755](https://bugzil.la/1920755)). ### CSS @@ -37,7 +37,7 @@ No notable changes - The [`keepalive`](/en-US/docs/Web/API/RequestInit#keepalive) initialization option to the global {{domxref('Window.fetch','fetch()')}} method and the [`Request()` constructor](/en-US/docs/Web/API/Request/Request#options) are now supported, along with the {{domxref("Request.keepalive")}} property. `keepalive` can be set to `true` to prevent the browser from aborting the associated request if the page that initiated it is unloaded before the request is complete. This might be used, for example, to send analytics at the end of a session, even if the user navigates away from or closes the page. - Using `fetch()` with `keepalive` has some advantages over using {{domxref("Navigator.sendBeacon()")}} for the same purpose, such as allowing the use of HTTP methods other than [`POST`](/en-US/docs/Web/HTTP/Methods/POST), customizable request properties, and access the server response via the fetch {{jsxref("Promise")}} fulfillment. It is also available in [service workers](/en-US/docs/Web/API/Service_Worker_API). ([Firefox bug 1906952](https://bugzil.la/1906952), [Firefox bug 1923044](https://bugzil.la/1923044)). + Using `fetch()` with `keepalive` has some advantages over using {{domxref("Navigator.sendBeacon()")}} for the same purpose, such as allowing the use of HTTP methods other than [`POST`](/en-US/docs/Web/HTTP/Reference/Methods/POST), customizable request properties, and access the server response via the fetch {{jsxref("Promise")}} fulfillment. It is also available in [service workers](/en-US/docs/Web/API/Service_Worker_API). ([Firefox bug 1906952](https://bugzil.la/1906952), [Firefox bug 1923044](https://bugzil.la/1923044)). - The [`onwaitingforkey`](/en-US/docs/Web/API/HTMLMediaElement/waitingforkey_event) content attribute can now be specified on {{htmlelement("audio")}}/{{htmlelement("video")}} elements to set an inline event handler for the `waitingforkey` event. ([Firefox bug 1925952](https://bugzil.la/1925952)). - {{domxref("ServiceWorkerContainer")}} is now exposed in all worker contexts via {{domxref("WorkerNavigator.serviceWorker")}}, allowing workers to inspect and manage the {{domxref("ServiceWorkerRegistration","service worker registrations","","nocode")}} associated with the current origin. Previously `ServiceWorkerContainer` was only available in the main thread, via {{domxref("Navigator.serviceWorker")}}. ([Firefox bug 1113522](https://bugzil.la/1113522)). @@ -76,7 +76,7 @@ These features are newly shipped in Firefox 133 but are disabled by default. To - **contenteditable plaintext-only value:** `dom.element.contenteditable.plaintext-only.enabled`. - The `plaintext-only` value of the [`contenteditable`](/en-US/docs/Web/HTML/Global_attributes/contenteditable) global attribute indicates that the element is editable; rich text formatting is disabled and any formatting in pasted text is automatically stripped. ([Firefox bug 1922723](https://bugzil.la/1922723).) + The `plaintext-only` value of the [`contenteditable`](/en-US/docs/Web/HTML/Reference/Global_attributes/contenteditable) global attribute indicates that the element is editable; rich text formatting is disabled and any formatting in pasted text is automatically stripped. ([Firefox bug 1922723](https://bugzil.la/1922723).) - **:has-slotted CSS pseudo-class:** `layout.css.has-slotted-selector.enabled`. diff --git a/files/en-us/mozilla/firefox/releases/134/index.md b/files/en-us/mozilla/firefox/releases/134/index.md index d7aab4859358063..02a52e107e150d6 100644 --- a/files/en-us/mozilla/firefox/releases/134/index.md +++ b/files/en-us/mozilla/firefox/releases/134/index.md @@ -41,17 +41,17 @@ No notable changes #### WebDriver BiDi -- Implemented the `browser.getClientWindows` command, which allows to retrieve information about the currently opened browser windows ([Firefox bug 1855025](https://bugzilla.mozilla.org/show_bug.cgi?id=1855025)) -- Added support for the `initiatorType` and `destination` fields to all network events ([Firefox bug 1904892](https://bugzilla.mozilla.org/show_bug.cgi?id=1904892) and [Firefox bug 1933331](https://bugzilla.mozilla.org/show_bug.cgi?id=1933331)). They allow to understand why and how the request was created. -- The `browsingContext.navigationStarted` event is no longer emitted when the initial about:blank page is loaded for a new top-level browsing context ([Firefox bug 1922014](https://bugzilla.mozilla.org/show_bug.cgi?id=1922014)) -- We fixed a bug where the `requestTime` of network events would sometimes be set to 0 ([Firefox bug 1930849](https://bugzilla.mozilla.org/show_bug.cgi?id=1930849)) -- The `browsingContext.traverseHistory` command can now only be used with top-level browsing contexts ([Firefox bug 1924859](https://bugzilla.mozilla.org/show_bug.cgi?id=1924859)) -- Improved the reliability of commands sent during a navigation, for instance when a browsing context is being replaced ([Firefox bug 1927073](https://bugzilla.mozilla.org/show_bug.cgi?id=1927073)). +- Implemented the `browser.getClientWindows` command, which allows to retrieve information about the currently opened browser windows ([Firefox bug 1855025](https://bugzil.la/1855025)) +- Added support for the `initiatorType` and `destination` fields to all network events ([Firefox bug 1904892](https://bugzil.la/1904892) and [Firefox bug 1933331](https://bugzil.la/1933331)). They allow to understand why and how the request was created. +- The `browsingContext.navigationStarted` event is no longer emitted when the initial about:blank page is loaded for a new top-level browsing context ([Firefox bug 1922014](https://bugzil.la/1922014)) +- We fixed a bug where the `requestTime` of network events would sometimes be set to 0 ([Firefox bug 1930849](https://bugzil.la/1930849)) +- The `browsingContext.traverseHistory` command can now only be used with top-level browsing contexts ([Firefox bug 1924859](https://bugzil.la/1924859)) +- Improved the reliability of commands sent during a navigation, for instance when a browsing context is being replaced ([Firefox bug 1927073](https://bugzil.la/1927073)). #### Marionette -- The `Addon:Install` and `Addon:Uninstall` commands are now available for GeckoView (Firefox for Android) ([Firefox bug 1806135](https://bugzilla.mozilla.org/show_bug.cgi?id=1806135)). -- The `Addon:Install` command can now be used to install extensions enabled in Private Browsing mode ([Firefox bug 1810718](https://bugzilla.mozilla.org/show_bug.cgi?id=1810718)) +- The `Addon:Install` and `Addon:Uninstall` commands are now available for GeckoView (Firefox for Android) ([Firefox bug 1806135](https://bugzil.la/1806135)). +- The `Addon:Install` command can now be used to install extensions enabled in Private Browsing mode ([Firefox bug 1810718](https://bugzil.la/1810718)) ## Experimental web features @@ -59,7 +59,7 @@ These features are newly shipped in Firefox 134 but are disabled by default. To - **`Intl.DurationFormat`** (Nightly release): {{jsxref("Intl.DurationFormat")}} enables locale-sensitive formatting of durations. ([Firefox bug 1648139](https://bugzil.la/1648139)). - **`autocorrect`**: <code>dom.forms.autocorrect</code>. - The HTML [`autocorrect`](/en-US/docs/Web/HTML/Global_attributes/autocorrect) attribute and {{domxref("HTMLElement.autocorrect")}} property allow autocorrection in editable text elements, including: most kinds of text {{htmlelement("input")}} elements, {{htmlelement("textarea")}} elements, and elements that have the [`contenteditable`](/en-US/docs/Web/HTML/Global_attributes/contenteditable) attribute set ([Firefox bug 1725806](https://bugzil.la/1725806)). + The HTML [`autocorrect`](/en-US/docs/Web/HTML/Reference/Global_attributes/autocorrect) attribute and {{domxref("HTMLElement.autocorrect")}} property allow autocorrection in editable text elements, including: most kinds of text {{htmlelement("input")}} elements, {{htmlelement("textarea")}} elements, and elements that have the [`contenteditable`](/en-US/docs/Web/HTML/Reference/Global_attributes/contenteditable) attribute set ([Firefox bug 1725806](https://bugzil.la/1725806)). ## Older versions diff --git a/files/en-us/mozilla/firefox/releases/135/index.md b/files/en-us/mozilla/firefox/releases/135/index.md index 262ad9aae25865f..6752fafc52352fc 100644 --- a/files/en-us/mozilla/firefox/releases/135/index.md +++ b/files/en-us/mozilla/firefox/releases/135/index.md @@ -42,31 +42,31 @@ No notable changes #### Media, WebRTC, and Web Audio -- The {{domxref("RTCOutboundRtpStreamStats.mid", "mid")}} and {{domxref("RTCOutboundRtpStreamStats.rid", "rid")}} properties of the {{domxref("RTCOutboundRtpStreamStats")}} interface, and the{{domxref("RTCOutboundRtpStreamStats.mid", "mid")}} property of the {{domxref("RTCInboundRtpStreamStats")}} interface are now supported. ([Firefox bug 1643001](https://bugzil.la/1643001)). +- The {{domxref("RTCOutboundRtpStreamStats.mid", "mid")}} and {{domxref("RTCOutboundRtpStreamStats.rid", "rid")}} properties of the {{domxref("RTCOutboundRtpStreamStats")}} interface, and the {{domxref("RTCOutboundRtpStreamStats.mid", "mid")}} property of the {{domxref("RTCInboundRtpStreamStats")}} interface are now supported. ([Firefox bug 1643001](https://bugzil.la/1643001)). ### WebDriver conformance (WebDriver BiDi, Marionette) #### General -- To make user events more realistic and better simulate real user interactions in the browser, we have moved the action sequence processing of the `Perform Actions` commands in both Marionette and WebDriver BiDi from the content process to the parent process. While events are still sent synchronously from the content process, they are now triggered asynchronously via IPC calls originating from the parent process ([Firefox bug 1922077](https://bugzilla.mozilla.org/show_bug.cgi?id=1922077)). +- To make user events more realistic and better simulate real user interactions in the browser, we have moved the action sequence processing of the `Perform Actions` commands in both Marionette and WebDriver BiDi from the content process to the parent process. While events are still sent synchronously from the content process, they are now triggered asynchronously via IPC calls originating from the parent process ([Firefox bug 1922077](https://bugzil.la/1922077)). Due to this significant change, some regressions may still exist. If you encounter any issues, please [file a bug for the Remote Agent](https://bugzilla.mozilla.org/enter_bug.cgi?product=Remote%20Protocol&component=Remote%20Agent). If the regressions block test execution, you can temporarily revert to the previous behavior by setting the Firefox preference `remote.events.async.enabled` to `false`. - With the processing of actions now handled in the parent process the following issues were fixed as well: - - We now support proper queuing of action sequences without race conditions. This is particularly important for WebDriver BiDi's `input.performActions` command, which can be called multiple times in parallel and must execute the enqueued actions sequentially ([Firefox bug 1915798](https://bugzilla.mozilla.org/show_bug.cgi?id=1915798)). + - We now support proper queuing of action sequences without race conditions. This is particularly important for WebDriver BiDi's `input.performActions` command, which can be called multiple times in parallel and must execute the enqueued actions sequentially ([Firefox bug 1915798](https://bugzil.la/1915798)). - - When dispatching actions, the `input cancel list` is now correctly updated only after the action has been successfully dispatched. Previously, if an action failed to execute, a reverse action could be left in place, leading to unexpected side effects when resetting the state of the `input source` ([Firefox bug 1930845](https://bugzilla.mozilla.org/show_bug.cgi?id=1930845)). + - When dispatching actions, the `input cancel list` is now correctly updated only after the action has been successfully dispatched. Previously, if an action failed to execute, a reverse action could be left in place, leading to unexpected side effects when resetting the state of the `input source` ([Firefox bug 1930845](https://bugzil.la/1930845)). - - When performing actions, individual actions are now retried during dispatch, particularly in situations where a single action triggers a navigation that replaces the current browsing context ([Firefox bug 1930530](https://bugzilla.mozilla.org/show_bug.cgi?id=1930530), [Firefox bug 1930090](https://bugzilla.mozilla.org/show_bug.cgi?id=1930090)). + - When performing actions, individual actions are now retried during dispatch, particularly in situations where a single action triggers a navigation that replaces the current browsing context ([Firefox bug 1930530](https://bugzil.la/1930530), [Firefox bug 1930090](https://bugzil.la/1930090)). - - When performing actions, a `TypeError: can't access property "getActor", browsingContext.currentWindowGlobal is null` error occurred if an action (not the last one) in the action chain closed the window, and the remaining actions were still being dispatched ([Firefox bug 1932916](https://bugzilla.mozilla.org/show_bug.cgi?id=1932916)). + - When performing actions, a `TypeError: can't access property "getActor", browsingContext.currentWindowGlobal is null` error occurred if an action (not the last one) in the action chain closed the window, and the remaining actions were still being dispatched ([Firefox bug 1932916](https://bugzil.la/1932916)). -- Some Marionette and WebDriver BiDi commands that rely internally on a `requestAnimationFrame` being emitted before returning would hang if the current browsing context was navigated during their execution ([Firefox bug 1937118](https://bugzilla.mozilla.org/show_bug.cgi?id=1937118)). +- Some Marionette and WebDriver BiDi commands that rely internally on a `requestAnimationFrame` being emitted before returning would hang if the current browsing context was navigated during their execution ([Firefox bug 1937118](https://bugzil.la/1937118)). #### WebDriver BiDi -- Added support for the `format` field in the `browsingContext.captureScreenshot` command, allowing clients to specify different file formats (`image/png` and `image/jpeg` are currently supported) and define the compression quality for screenshots ([Firefox bug 1861737](https://bugzilla.mozilla.org/show_bug.cgi?id=1861737)). +- Added support for the `format` field in the `browsingContext.captureScreenshot` command, allowing clients to specify different file formats (`image/png` and `image/jpeg` are currently supported) and define the compression quality for screenshots ([Firefox bug 1861737](https://bugzil.la/1861737)). ## Changes for add-on developers diff --git a/files/en-us/mozilla/firefox/releases/136/index.md b/files/en-us/mozilla/firefox/releases/136/index.md index c00f5f72bbdc7cf..6e5063778fd21fc 100644 --- a/files/en-us/mozilla/firefox/releases/136/index.md +++ b/files/en-us/mozilla/firefox/releases/136/index.md @@ -12,8 +12,8 @@ This article provides information about the changes in Firefox 136 that affect d ### HTML -- The [`autocorrect`](/en-US/docs/Web/HTML/Global_attributes/autocorrect) global attribute allows autocorrection in editable text elements including: most kinds of text {{htmlelement("input")}} elements, {{htmlelement("textarea")}} elements, and elements that have the [`contenteditable`](/en-US/docs/Web/HTML/Global_attributes/contenteditable) attribute set. The specific autocorrection behavior depends on the user agent and underlying OS. ([Firefox bug 1927977](https://bugzil.la/1927977)). -- The `plaintext-only` value of the [`contenteditable`](/en-US/docs/Web/HTML/Global_attributes/contenteditable) global attribute indicates that the element is editable; rich text formatting is disabled and any formatting in pasted text is automatically stripped ([Firefox bug 1922724](https://bugzil.la/1922724)). +- The [`autocorrect`](/en-US/docs/Web/HTML/Reference/Global_attributes/autocorrect) global attribute allows autocorrection in editable text elements including: most kinds of text {{htmlelement("input")}} elements, {{htmlelement("textarea")}} elements, and elements that have the [`contenteditable`](/en-US/docs/Web/HTML/Reference/Global_attributes/contenteditable) attribute set. The specific autocorrection behavior depends on the user agent and underlying OS. ([Firefox bug 1927977](https://bugzil.la/1927977)). +- The `plaintext-only` value of the [`contenteditable`](/en-US/docs/Web/HTML/Reference/Global_attributes/contenteditable) global attribute indicates that the element is editable; rich text formatting is disabled and any formatting in pasted text is automatically stripped ([Firefox bug 1922724](https://bugzil.la/1922724)). ### CSS @@ -34,16 +34,14 @@ This article provides information about the changes in Firefox 136 that affect d ### APIs -- The maximum size of [Data URLs](/en-US/docs/Web/URI/Schemes/data) has been increased from 32MB to 512MB, matching the limit for Chromium browsers ([Firefox bug 1911300](https://bugzil.la/1911300)). -- The [Cookie Store API](/en-US/docs/Web/API/Cookie_Store_API) is a modern, {{glossary("asynchronous")}} {{jsxref("Promise")}}-based method of managing cookies, which can be used in both the main thread and in [service workers](/en-US/docs/Web/API/Service_Worker_API). - A subset of the Cookie Store API has been implemented ([Firefox bug 1937477](https://bugzil.la/1937477)). This includes: +- The maximum size of [Data URLs](/en-US/docs/Web/URI/Reference/Schemes/data) has been increased from 32MB to 512MB, matching the limit for Chromium browsers ([Firefox bug 1911300](https://bugzil.la/1911300)). - - The [`CookieStore`](/en-US/docs/Web/API/CookieStore) interface, for getting, setting, and deleting cookies. - - The [`Window.cookieStore`](/en-US/docs/Web/API/Window/cookieStore) and [`ServiceWorkerGlobalScope.cookieStore`](/en-US/docs/Web/API/ServiceWorkerGlobalScope/cookieStore) properties for getting `CookieStore` instances. - - The [`change` event](/en-US/docs/Web/API/CookieStore/change_event) (and its interface [`CookieChangeEvent`](/en-US/docs/Web/API/CookieChangeEvent)), which fires in main thread and service worker contexts when cookies are set or deleted. +- Element properties are now reflected for the [Aria attributes that contain element references](/en-US/docs/Web/API/Document_Object_Model/Reflected_attributes#reflected_element_references) ([Firefox bug 1919102](https://bugzil.la/1919102)). - Note that while any of the supported cookie properties can be [set](/en-US/docs/Web/API/CookieStore/set), the cookie objects returned by the [`get()`](/en-US/docs/Web/API/CookieStore/get) and [`getAll()`](/en-US/docs/Web/API/CookieStore/getAll) methods, and in the `change` event, omit all properties other than `name` and `value` (matching the information returned by the {{domxref("document.cookie")}}). - The following interfaces and properties are not implemented: [`ServiceWorkerRegistration.cookies`](/en-US/docs/Web/API/ServiceWorkerRegistration/cookies), [`CookieStoreManager`](/en-US/docs/Web/API/CookieStoreManager), and [`ExtendableCookieChangeEvent`](/en-US/docs/Web/API/ExtendableCookieChangeEvent). + This includes: + + - {{domxref("Element/ariaActiveDescendantElement","ariaActiveDescendantElement")}}, {{domxref("Element/ariaControlsElements","ariaControlsElements")}}, {{domxref("Element/ariaDescribedByElements","ariaDescribedByElements")}}, {{domxref("Element/ariaDetailsElements","ariaDetailsElements")}}, {{domxref("Element/ariaErrorMessageElements","ariaErrorMessageElements")}}, {{domxref("Element/ariaFlowToElements","ariaFlowToElements")}}, {{domxref("Element/ariaLabelledByElements", "ariaLabelledByElements")}}, {{domxref("Element/ariaOwnsElements","ariaOwnsElements")}} in the {{domxref("Element")}} interface + - {{domxref("ElementInternals/ariaActiveDescendantElement","ariaActiveDescendantElement")}}, {{domxref("ElementInternals/ariaControlsElements","ariaControlsElements")}}, {{domxref("ElementInternals/ariaDescribedByElements","ariaDescribedByElements")}}, {{domxref("ElementInternals/ariaDetailsElements","ariaDetailsElements")}}, {{domxref("ElementInternals/ariaErrorMessageElements","ariaErrorMessageElements")}}, {{domxref("ElementInternals/ariaFlowToElements","ariaFlowToElements")}}, {{domxref("ElementInternals/ariaLabelledByElements", "ariaLabelledByElements")}}, {{domxref("ElementInternals/ariaOwnsElements","ariaOwnsElements")}} in the {{domxref("ElementInternals")}} interface. #### Media, WebRTC, and Web Audio @@ -61,24 +59,26 @@ This article provides information about the changes in Firefox 136 that affect d #### General -- Firefox now handles WebSocket port conflicts for the RemoteAgent more efficiently. If the port specified via the `--remote-debugging-port` command line argument cannot be acquired within 5 seconds, such as when another Firefox process is already using it, Firefox will now shut down instead of hanging ([Firefox bug 1927721](https://bugzilla.mozilla.org/show_bug.cgi?id=1927721)). +- Firefox now handles WebSocket port conflicts for the RemoteAgent more efficiently. If the port specified via the `--remote-debugging-port` command line argument cannot be acquired within 5 seconds, such as when another Firefox process is already using it, Firefox will now shut down instead of hanging ([Firefox bug 1927721](https://bugzil.la/1927721)). -- Navigations using the HTTP schema, triggered by the `WebDriver:Navigate` command in Marionette or `browsingContext.navigate` in WebDriver BiDi, will no longer be automatically upgraded to HTTPS. These requests will now remain on HTTP as intended ([Firefox bug 1943551](https://bugzilla.mozilla.org/show_bug.cgi?id=1943551)). +- Navigations using the HTTP schema, triggered by the `WebDriver:Navigate` command in Marionette or `browsingContext.navigate` in WebDriver BiDi, will no longer be automatically upgraded to HTTPS. These requests will now remain on HTTP as intended ([Firefox bug 1943551](https://bugzil.la/1943551)). #### WebDriver BiDi -- The `session.subscribe` command now returns a subscription ID, which can be used with `session.unsubscribe` to precisely target the same previously subscribed events and contexts as the original subscription. This helps prevent unintended side effects when multiple subscriptions exist, such as those limited to a specific tab ([Firefox bug 1938576](https://bugzilla.mozilla.org/show_bug.cgi?id=1938576)). +- The `session.subscribe` command now returns a subscription ID, which can be used with `session.unsubscribe` to precisely target the same previously subscribed events and contexts as the original subscription. This helps prevent unintended side effects when multiple subscriptions exist, such as those limited to a specific tab ([Firefox bug 1938576](https://bugzil.la/1938576)). Note: The previous logic for removing events by name and context has been deprecated and will be removed in a future release. -- Added support for the `userContexts` field in the `script.addPreloadScript` command, allowing clients to specify in which user contexts (containers) the script should always be loaded automatically, including any new browsing contexts opened within such specified user contexts ([Firefox bug 1940927](https://bugzilla.mozilla.org/show_bug.cgi?id=1940927)). +- Added support for the `userContexts` field in the `script.addPreloadScript` command, allowing clients to specify in which user contexts (containers) the script should always be loaded automatically, including any new browsing contexts opened within such specified user contexts ([Firefox bug 1940927](https://bugzil.la/1940927)). -- The `browsingContext.contextDestroyed` event now returns a fully serialized browsing context tree when a context is closed, including all its child contexts ([Firefox bug 1860955](https://bugzilla.mozilla.org/show_bug.cgi?id=1860955)). +- The `browsingContext.contextDestroyed` event now returns a fully serialized browsing context tree when a context is closed, including all its child contexts ([Firefox bug 1860955](https://bugzil.la/1860955)). ## Changes for add-on developers +- Adds the `preferred_environment` property to the [`background` manifest key](/en-US/docs/Mozilla/Add-ons/WebExtensions/manifest.json/background), enabling extensions to request that the browser run their background scripts as a document or service worker ([Firefox bug 1798655](https://bugzil.la/1798655)). - {{WebExtAPIRef("menus.update")}} and {{WebExtAPIRef("menus.remove")}} and the aliases {{WebExtAPIRef("contextMenus.update")}} and {{WebExtAPIRef("contextMenus.remove")}} now reject with an error when the menu item doesn't exist. Previously, the error was ignored and the promise fulfilled. ([Firefox bug 1688743](https://bugzil.la/1688743)). -- A new version of the {{WebExtAPIRef("userScripts")}} API is available. This version of the API is for use in Manifest V3 extensions and provides broad compatibility with Chrome, although [permissions mechanisms](/en-US/docs/Mozilla/Add-ons/WebExtensions/API/userScripts#permissions) differ across the browsers. ([Firefox bug 1943050](https://bugzil.la/1943050)). +- A new version of the {{WebExtAPIRef("userScripts")}} API is available on desktop Firefox. This version of the API is for use in Manifest V3 extensions and provides broad compatibility with Chrome, although [permissions mechanisms](/en-US/docs/Mozilla/Add-ons/WebExtensions/API/userScripts#permissions) differ across the browsers. ([Firefox bug 1943050](https://bugzil.la/1943050)). +- The `canResume` property of {{WebExtAPIRef("downloads.DownloadItem")}} is now set to `true` when a download fails with `NETWORK_FAILED`. This enables downloads that fail due to a network error to be resumed using {{WebExtAPIRef("downloads.resume","downloads.resume()")}}. ([Firefox bug 1694049](https://bugzil.la/1694049)). ## Experimental web features @@ -91,13 +91,13 @@ These features are newly shipped in Firefox 136 but are disabled by default. To Its main use case is to install a stack trace on a custom error object that does not derive from the {{jsxref("Error")}} interface. ([Firefox bug 1886820](https://bugzil.la/1886820)). - **Clear-Site-Data: cache**: `privacy.clearSiteDataHeader.cache.enabled`. - The [`Clear-Site-Data`](/en-US/docs/Web/HTTP/Headers/Clear-Site-Data) header can be used with the [`cache`](/en-US/docs/Web/HTTP/Headers/Clear-Site-Data#cache) or `*` directives to clear the browser cache. + The [`Clear-Site-Data`](/en-US/docs/Web/HTTP/Reference/Headers/Clear-Site-Data) header can be used with the [`cache`](/en-US/docs/Web/HTTP/Reference/Headers/Clear-Site-Data#cache) or `*` directives to clear the browser cache. ([Firefox bug 1942272](https://bugzil.la/1942272)). - **SVG `<discard>` element for SVG animations**: `svg.discard.enabled`. The {{svgelement("discard")}} SVG element allows developers to specify a trigger, such as the elapsed time since the SVG was loaded into DOM or the end of a particular animation, at which a specified element and its children should be removed from the DOM. This allows an SVG viewer to conserve memory by discarding animated elements that no longer needed. ([Firefox bug 1069931](https://bugzil.la/1069931)). - **SVG path API methods**: `dom.svg.pathSegment.enabled`. - The `SVGPathSegment` interface now supports the `getPathData()`, `setPathData()`, and `getPathSegmentAtLength()` methods. These methods provide a convenient way to work with SVG path data instead of parsing raw string data. ([Firefox bug 1934525](https://bugzil.la/1934525)). + The {{domxref("SVGPathElement/getPathData", "getPathData()")}}, {{domxref("SVGPathElement/setPathData", "setPathData()")}}, and {{domxref("SVGPathElement/getPathSegmentAtLength", "getPathSegmentAtLength()")}} methods of the {{domxref("SVGPathElement")}} interface are now supported. These methods provide a convenient way to work with SVG path data instead of parsing raw string data. ([Firefox bug 1934525](https://bugzil.la/1934525)). ## Older versions diff --git a/files/en-us/mozilla/firefox/releases/137/index.md b/files/en-us/mozilla/firefox/releases/137/index.md index 5133aa52b12c936..ddcfa8ba6a256db 100644 --- a/files/en-us/mozilla/firefox/releases/137/index.md +++ b/files/en-us/mozilla/firefox/releases/137/index.md @@ -6,46 +6,28 @@ page-type: firefox-release-notes {{FirefoxSidebar}} -This article provides information about the changes in Firefox 137 that affect developers. Firefox 137 is the current [Beta version of Firefox](https://www.mozilla.org/en-US/firefox/channel/desktop/#beta) and ships on [April 1, 2025](https://whattrainisitnow.com/release/?version=137). +This article provides information about the changes in Firefox 137 that affect developers. +Firefox 137 was released on [April 1, 2025](https://whattrainisitnow.com/release/?version=137). ## Changes for web developers -### Developer Tools - ### HTML -#### Removals +No notable changes ### CSS -#### Removals +- The {{CSSXRef("hyphenate-limit-chars")}} CSS property provides you with fine-grained control over hyphenation in text. It is used to specify the minimum word length for hyphenation as well as the number of characters before and after the hyphen. ([Firefox bug 1947183](https://bugzil.la/1947183)). +- The {{cssxref("text-decoration-line")}} CSS property now accepts the values `spelling-error` and `grammar-error`. These values use the browser's styling for spelling and grammar errors and disregard the other properties in the {{cssxref("text-decoration")}} shorthand. ([Firefox bug 1950844](https://bugzil.la/1950844)). ### JavaScript - The {{jsxref("Math.sumPrecise()")}} static method is now supported. This takes an [iterable](/en-US/docs/Web/JavaScript/Reference/Iteration_protocols#the_iterable_protocol) (such as an {{jsxref("Array")}}) of numbers and returns their sum. It is more precise than summing the numbers in a loop because it avoids floating point precision loss in intermediate results. ([Firefox bug 1943120](https://bugzil.la/1943120)). - -#### Removals - -### SVG - -- The {{svgelement("discard")}} SVG element is now supported, along with its corresponding {{domxref("SVGDiscardElement")}} JavaScript interface. - The element allows developers to specify a trigger time or event at which a specified element and its children should be removed from the DOM. - An SVG viewer can use this information to conserve memory by discarding elements that are no longer needed, such as animated elements that have completed. - ([Firefox bug 1945330](https://bugzil.la/1945330)). - -#### Removals - -### HTTP - -#### Removals - -### Security - -#### Removals +- The {{jsxref("Atomics.pause()")}} static method is now supported. This method provides a hint to the CPU that the current thread is in a spinlock while waiting on access to a shared resource. The system can then reduce the resources allocated to the core (such as power) or thread, without yielding the current thread. ([Firefox bug 1937805](https://bugzil.la/1937805)). ### APIs -#### DOM +- The {{domxref("SVGPathElement/getPathData", "getPathData()")}}, {{domxref("SVGPathElement/setPathData", "setPathData()")}}, and {{domxref("SVGPathElement/getPathSegmentAtLength", "getPathSegmentAtLength()")}} methods of the {{domxref("SVGPathElement")}} interface are now supported. These methods provide a convenient way to work with SVG path data instead of parsing raw string data. ([Firefox bug 1945312](https://bugzil.la/1945312)). #### Media, WebRTC, and Web Audio @@ -53,31 +35,39 @@ This article provides information about the changes in Firefox 137 that affect d #### Removals -### WebAssembly - -#### Removals +- The following non-standard events are now deprecated and proposed for removal: [`afterscriptexecute`](/en-US/docs/Web/API/Document/afterscriptexecute_event) and [`beforescriptexecute`](/en-US/docs/Web/API/Document/beforescriptexecute_event) in {{domxref("Document")}}, and [`afterscriptexecute`](/en-US/docs/Web/API/Element/afterscriptexecute_event), and [`beforescriptexecute`](/en-US/docs/Web/API/Element/beforescriptexecute_event) in {{domxref("Element")}}. A console warning is displayed when they are used. ([Firefox bug 1949373](https://bugzil.la/1949373)). ### WebDriver conformance (WebDriver BiDi, Marionette) #### General +- Input sources of type `mouse` and `touch` now support fractional numbers for x and y positions for the `pointerMove` action ([Firefox bug 1946774](https://bugzil.la/1946774)). + #### WebDriver BiDi +- Implemented new `webExtension.install` ([Firefox bug 1934551](https://bugzil.la/1934551)) and `webExtension.uninstall` ([Firefox bug 1934553](https://bugzil.la/1934553)) commands, enabling clients to install and uninstall web extensions in the browser. +- Added support for `userContexts` argument to `sessions.subscribe` command, which allows clients subscribing to a list of user contexts (also known as Firefox containers) + ([Firefox bug 1938604](https://bugzil.la/1938604)). +- `script.addPreloadScript` command is updated to throw an `invalid argument` error when both `contexts` and `userContexts` arguments are provided ([Firefox bug 1945554](https://bugzil.la/1945554)). +- `browsingContext.navigate` command will not return immediately anymore when `wait` argument equals `none` and beforeunload prompt opens. That's the first step of updating the logic behind `wait` argument equals `none` ([Firefox bug 1948700](https://bugzil.la/1948700)). + #### Marionette +- From now on, a `javascript error` from a syntax error raised by script evaluation will contain line and column number ([Firefox bug 1865146](https://bugzil.la/1865146)). +- Performing actions with async events enabled will not fail anymore with a `Cyclic object value` error message ([Firefox bug 1947112](https://bugzil.la/1947112)). + Async events were enabled since Firefox 135. See more details in [the release notes](/en-US/docs/Mozilla/Firefox/Releases/135#webdriver_conformance_webdriver_bidi_marionette). + ## Changes for add-on developers - Adds {{WebExtAPIRef("commands.openShortcutSettings")}} that opens the Manage Extension Shortcuts page of Manage Your Extensions (`about:addons`) and, if the extension has shortcuts, scrolls to and highlights the extension's shortcut key options. ([Firefox bug 1538451](https://bugzil.la/1538451)) - The 10 MB quota for data stored by the {{WebExtAPIRef("storage.session")}} API is now enforced. ([Firefox bug 1915688](https://bugzil.la/1915688)) -### Removals - -### Other - ## Experimental web features These features are newly shipped in Firefox 137 but are disabled by default. To experiment with them, search for the appropriate preference on the `about:config` page and set it to `true`. You can find more such features on the [Experimental features](/en-US/docs/Mozilla/Firefox/Experimental_features) page. +- **Temporal API** (Nightly release): is now enabled in Firefox Nightly by default. The [Temporal object](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Temporal) aims to simplify working with dates and times in various scenarios, with built-in time zone and calendar representations. ([Firefox bug 1946823](https://bugzil.la/1946823)). + ## Older versions {{Firefox_for_developers}} diff --git a/files/en-us/mozilla/firefox/releases/138/index.md b/files/en-us/mozilla/firefox/releases/138/index.md index 8ac65f5c2e6885b..feb58d9e6644925 100644 --- a/files/en-us/mozilla/firefox/releases/138/index.md +++ b/files/en-us/mozilla/firefox/releases/138/index.md @@ -2,69 +2,131 @@ title: Firefox 138 for developers slug: Mozilla/Firefox/Releases/138 page-type: firefox-release-notes +sidebar: firefoxsidebar --- -{{FirefoxSidebar}} - -This article provides information about the changes in Firefox 138 that affect developers. Firefox 138 is the current [Nightly version of Firefox](https://www.mozilla.org/en-US/firefox/channel/desktop/#nightly) and ships on [April 29, 2025](https://whattrainisitnow.com/release/?version=138). +This article provides information about the changes in Firefox 138 that affect developers. +Firefox 138 was released on [April 29, 2025](https://whattrainisitnow.com/release/?version=138). ## Changes for web developers -### Developer Tools - ### HTML -#### Removals +- The [`importmap`](/en-US/docs/Web/HTML/Reference/Elements/script/type/importmap) value of the [`type`](/en-US/docs/Web/HTML/Reference/Elements/script/type) attribute of the [`<script>`](/en-US/docs/Web/HTML/Reference/Elements/script) element now supports the [`integrity`](/en-US/docs/Web/HTML/Reference/Elements/script/type/importmap#integrity) key. This allows the ES module URLs referenced in the import maps to be matched against their integrity metadata. As a result, these modules are now compatible with [CSP](/en-US/docs/Web/HTTP/Guides/CSP) directives that require Subresource Integrity ([SRI](/en-US/docs/Web/Security/Practical_implementation_guides/SRI)). ([Firefox bug 1945540](https://bugzil.la/1945540)). ### CSS -#### Removals +No notable changes ### JavaScript -#### Removals - -### SVG - -#### Removals +- The {{jsxref("Error.captureStackTrace()")}} static method is now supported. This installs stack trace information on a provided object as the {{jsxref("Error.stack")}} property. Its main use case is to install a stack trace on a custom error object that does not derive from the {{jsxref("Error")}} interface. ([Firefox bug 1950508](https://bugzil.la/1950508)). +- The {{jsxref("Error.isError()")}} static method can now be used to check whether or not an object is an instance of an {{jsxref("Error")}} or a {{domxref("DOMException")}}. This is more reliable than using `instanceof` for the same purpose. ([Firefox bug 1952249](https://bugzil.la/1952249)). +- The [`import`](/en-US/docs/Web/JavaScript/Reference/Statements/import) declaration now supports importing JSON modules using the [`with`](/en-US/docs/Web/JavaScript/Reference/Statements/import/with) attribute. ### HTTP -#### Removals - -### Security - -#### Removals +- The [`Clear-Site-Data`](/en-US/docs/Web/HTTP/Reference/Headers/Clear-Site-Data) header can be used with the [`cache`](/en-US/docs/Web/HTTP/Reference/Headers/Clear-Site-Data#cache) (and `*`) directive to clear the browser network cache. This gives websites more control over data stored for their users, allowing them to, for example, mitigate the risk of privacy leaks by clearing the cache during logout. ([Firefox bug 1942272](https://bugzil.la/1930500)). +- The HTTP {{httpheader("Origin-Agent-Cluster")}} response header can now be used by a site to hint that the associated document should be placed in an origin-keyed [agent cluster](/en-US/docs/Web/JavaScript/Reference/Execution_model#agent_clusters_and_memory_sharing). + When in such a cluster, the operating system process and/or other OS resources used by the document are only shared with other documents from the same [origin](/en-US/docs/Glossary/Origin). + This makes it less likely that a resource-intensive document will degrade the performance of documents from other origins. + Developers can test whether the browser has put the document in an origin-keyed agent cluster using the {{domxref("window.originAgentCluster")}} property. + ([Firefox bug 1665474](https://bugzil.la/1665474)) ### APIs +- The [Login Status API](/en-US/docs/Web/API/FedCM_API/IDP_integration#update_login_status_using_the_login_status_api) is now supported when using the [Federated Credential Management (FedCM) API](/en-US/docs/Web/API/FedCM_API). It can be used to set and check whether a browser user is logged in to an identity provider. + This includes support for the {{domxref("NavigatorLogin")}} interface, the {{domxref("navigator.login")}} property, and the {{httpheader("Set-Login")}} HTTP response header. + ([Firefox bug 1945576](https://bugzil.la/1945576) and [Firefox bug 1945573](https://bugzil.la/1945573)). +- The [Web Audio API](/en-US/docs/Web/API/Web_Audio_API) now supports bidirectional messaging on an {{domxref("AudioWorklet.port")}} and an {{domxref("AudioWorkletGlobalScope.port")}}. + This allows for custom, asynchronous communication between code in the main thread and the global scope of an audio worklet, such as receiving control data or global settings. ([Firefox bug 1951240](https://bugzil.la/1951240)) +- The {{domxref("RTCCertificate.getFingerprints()","getFingerprints()")}} method of the {{domxref("RTCCertificate")}} interface is now supported. + An application can use this to get fingerprints for a certificate, which might be shared out-of-band in order to identify a particular user or browser across WebRTC sessions. + ([Firefox bug 1525241](https://bugzil.la/1525241)). + #### DOM #### Media, WebRTC, and Web Audio -#### Removals - -### WebAssembly - -#### Removals +- WebRTC applications can now set a preference for prioritizing framerate or resolution when both cannot be maintained at the configured levels due to network degradation. + The value is set using the [`degradationPreference`](/en-US/docs/Web/API/RTCRtpSender/setParameters#degradationpreference) property in the parameter object passed to the [`setParameters()`](/en-US/docs/Web/API/RTCRtpSender/setParameters#degradationpreference) method of the `RTCRtpSender` interface. + It can also be read from the object returned by the [`getParameters()`](/en-US/docs/Web/API/RTCRtpSender/getParameters#degradationpreference) method. + ([Firefox bug 1329847](https://bugzil.la/1329847)). ### WebDriver conformance (WebDriver BiDi, Marionette) #### General +- All remote protocols now enable the preferences required to properly pipe logs to stdout ([Firefox bug 1947740](https://bugzil.la/1947740)). +- A new Firefox argument, `--remote-enable-system-access`, was added to enable sensitive features, such as interacting with Browsing Contexts in the parent process (e.g., Browser UI) or using privileged APIs in content processes. This will be used for WebDriver BiDi features in the next releases, and can already be used with Marionette (see the Marionette section below) ([Firefox bug 1944565](https://bugzil.la/1944565)). + #### WebDriver BiDi +- The `webExtension.install` command now installs web extensions temporarily by default, allowing it to be used with unsigned extensions - either as an XPI file or as an unpacked folder. A new Firefox-specific parameter, `moz:permanent`, has been added to force installation as a regular extension instead ([Firefox bug 1947678](https://bugzil.la/1947678)). +- The `browsingContext.setViewport` command now supports a `userContexts` parameter, which must be an array of user context (Firefox container) ids. When provided, the viewport configuration will be applied to all Browsing Contexts belonging to those user contexts, as well as any future contexts created within them. This parameter cannot be used together with the existing `context` parameter ([Firefox bug 1940952](https://bugzil.la/1940952)). +- The `browsingContext.Info` type now includes a `clientWindow` property corresponding to the ID of the window owning the Browsing Context. It is typically returned by `browsingContext.getTree` or included in the payload of events such as `browsingContext.contextCreated` ([Firefox bug 1920952](https://bugzil.la/1920952)). + #### Marionette -## Changes for add-on developers +- Switching to the `chrome` (parent process) context with Marionette now requires using the `--remote-enable-system-access` command-line flag when starting Firefox ([Firefox bug 1710425](https://bugzil.la/1710425)). -### Removals +## Changes for add-on developers -### Other +- Support provided for `page_action` as a {{WebExtAPIRef("menus.ContextType")}} in the {{WebExtAPIRef("menus")}} API for Manifest V3 extensions. This provides Manifest V3 extensions the same ability as Manifest V2 extensions to add menu items to `page_action`. ([Firefox bug 1951166](https://bugzil.la/1951166)) +- The {{WebExtAPIRef("contextualIdentities")}} API is no longer defined in Firefox for Android. Previously, it was defined but defective. ([Firefox bug 1659500](https://bugzil.la/1659500)) +- The `contextualIdentities` permission is now not recognized on Firefox for Android. Previously, it enabled a broken version of the "containers" feature. ([Firefox bug 1659500](https://bugzil.la/1659500)) +- The new Manifest V3 version of the {{WebExtAPIRef("userScripts")}} API is now available on Firefox for Android. ([Firefox bug 1949955](https://bugzil.la/1949955)) +- Implements the {{WebExtAPIRef("webRequest.handlerBehaviorChanged")}} API. In previous versions this method was exposed but did nothing. ([Firefox bug 1657575](https://bugzil.la/1657575)) +- The {{WebExtAPIRef("alarms.create")}} API now returns a Promise instead of undefined. ([Firefox bug 1869171](https://bugzil.la/1869171)) +- Support added to enable the manipulation of tabs within tab groups, including the addition of: + - {{WebExtAPIRef("tabs.group()")}} and {{WebExtAPIRef("tabs.ungroup()")}}. ([Firefox bug 1959714](https://bugzil.la/1959714)) + - `groupId` to {{WebExtAPIRef("tabs.Tab")}}. ([Firefox bug 1959713](https://bugzil.la/1959713)) + - `groupId` to {{WebExtAPIRef("tabs.query")}}. ([Firefox bug 1959715](https://bugzil.la/1959715)) + - `groupId` to {{WebExtAPIRef("tabs.onUpdated")}}. ([Firefox bug 1959716](https://bugzil.la/1959716) +- The `json` resource type is now supported in both {{WebExtAPIRef("webRequest.ResourceType")}} and {{WebExtAPIRef("declarativeNetRequest.ResourceType")}} in Firefox, with import attributes enabled by default. Previously, it was reported as `script`. ([Firefox bug 1858078](https://bugzil.la/1858078) and [Firefox bug 1950836](https://bugzil.la/1950836)) ## Experimental web features -These features are newly shipped in Firefox 138 but are disabled by default. To experiment with them, search for the appropriate preference on the `about:config` page and set it to `true`. You can find more such features on the [Experimental features](/en-US/docs/Mozilla/Firefox/Experimental_features) page. +These features are newly shipped in Firefox 138 and are considered experimental. +They may be disabled by default or enabled by default but available only in the Nightly build. +For features disabled by default, search for the appropriate preference on the `about:config` page and set it to `true`. +You can find more such features on the [Experimental features](/en-US/docs/Mozilla/Firefox/Experimental_features) page. + +- **UA styles for `<h1>` nested into sectioning elements:** `layout.css.h1-in-section-ua-styles.enabled`. + + The `<h1>` heading doesn't decrease in font size now when nested within [sectioning elements](/en-US/docs/Web/HTML/Guides/Content_categories#sectioning_content) `<article>`, `<aside>`, `<nav>`, and `<section>`. The UA styles for `<h1>` nested within sectioning elements are no longer relevant since the outline algorithm [has been removed](https://github.com/whatwg/html/pull/7829) from the HTML specification. ([Firefox bug 1883896](https://bugzil.la/1883896)). + + As part of a staged rollout of this removal 5% of users of Firefox 138 and 50% of users of Firefox Beta 138 will have the value of `layout.css.h1-in-section-ua-styles.enabled` set to `false` ([Intent to unship: UA styles for h1 in article, aside, nav, section](https://groups.google.com/a/mozilla.org/g/dev-platform/c/CzG_pVa7pws/m/Ab3Bwsg2BQAJ)). + + > [!NOTE] + > The preference for this feature works in reverse: it's set to `false` in the Nightly build, which removes the UA styling for headings nested in sectioning elements. It's set to `true` in all other channels, which retains the existing UA styling for the nested headings. + +- **::details-content CSS pseudo-element:** `layout.css.details-content.enabled`. + + The CSS {{cssxref("::details-content")}} pseudo-element enables you to style the content of the {{htmlElement("details")}} element ([Firefox bug 1901037](https://bugzil.la/1901037)). + +- **Allow pseudo-elements after element-backed pseudo-elements** + + Work has begun on allowing [pseudo-elements](/en-US/docs/Web/CSS/Pseudo-elements) such as {{cssxref("::first-letter")}} and {{cssxref("::before")}} to be appended to [element-backed pseudo-elements](/en-US/docs/Web/CSS/Pseudo-elements#element-backed_pseudo-elements) such as {{cssxref("::details-content")}} and {{cssxref("::file-selector-button")}}. ([Firefox bug 1953557](https://bugzil.la/1953557)). + + > [!NOTE] + > The preference for this feature depends upon the element-backed pseudo-element being targeted, for example: [`::details-content`](/en-US/docs/Mozilla/Firefox/Experimental_features#details-content_pseudo-element). + +- **`MutationEvent` on path to removal**: `dom.mutation_events.enabled` + + {{domxref("MutationEvent")}} and its associated events (`DOMSubtreeModified`, `DOMNodeInserted`, `DOMNodeRemoved`, `DOMCharacterDataModified`, `DOMAttrModified`) are now disabled on Firefox Nightly by default. ([Firefox bug 1951772](https://bugzil.la/1951772)). + +- **`Notification.actions`** (Nightly): `dom.webnotifications.actions.enabled` + + The {{domxref("Notification.actions")}} property can get the actions associated with a `Notification`, as set using {{domxref("ServiceWorkerRegistration.showNotification()")}}. ([Firefox bug 1225110](https://bugzil.la/1225110)). + +- **`PerformanceEventTiming.interactionId`**: `dom.performance.event_timing.enable_interactionid` + + {{domxref("PerformanceEventTiming.interactionId")}} can be used to measure latency timing for events triggered by a particular user interaction. ([Firefox bug 1934683](https://bugzil.la/1934683)). + +- **HTML Sanitizer API**: `dom.security.sanitizer.enabled` + + The [HTML Sanitizer API](/en-US/docs/Web/API/HTML_Sanitizer_API) allow developers to take untrusted strings of HTML and sanitize them for safe insertion into a document's DOM. ([Firefox bug 1950605](https://bugzil.la/1950605)), ([Firefox bug 1952250](https://bugzil.la/1952250)). ## Older versions diff --git a/files/en-us/mozilla/firefox/releases/139/index.md b/files/en-us/mozilla/firefox/releases/139/index.md new file mode 100644 index 000000000000000..fe2e0f5e408f9e1 --- /dev/null +++ b/files/en-us/mozilla/firefox/releases/139/index.md @@ -0,0 +1,102 @@ +--- +title: Firefox 139 for developers +slug: Mozilla/Firefox/Releases/139 +page-type: firefox-release-notes +sidebar: firefoxsidebar +--- + +This article provides information about the changes in Firefox 139 that affect developers. +Firefox 139 was released on [May 27, 2025](https://whattrainisitnow.com/release/?version=139). + +## Changes for web developers + +### HTML + +- The [`hidden=until-found`](/en-US/docs/Web/HTML/Reference/Global_attributes/hidden#the_hidden_until_found_state) HTML attribute and the [`beforematch` event](/en-US/docs/Web/API/Element/beforematch_event) are now supported. + The _hidden until found_ state allows you to hide the contents of an element until it is found by user search (for example, using "Find in page") or by fragment navigation. + The `beforematch` event fires just before the `hidden` attribute is removed ([Firefox bug 1761043](https://bugzil.la/1761043) and [Firefox bug 1955379](https://bugzil.la/1955379)). + +### CSS + +No notable changes + +### JavaScript + +- The Temporal API is now supported, this aims to simplify working with dates and times in various scenarios, with built-in time zone and calendar representations ([Firefox bug 1912511](https://bugzil.la/1912511) and [Firefox bug 1954138](https://bugzil.la/1954138)). + This includes: + - A **duration** (difference between two time points): {{jsxref("Temporal.Duration")}} + - **Points in time**: + - As a unique instant in history: + - A timestamp: {{jsxref("Temporal.Instant")}} + - A date-time with a time zone: {{jsxref("Temporal.ZonedDateTime")}} + - **Time-zone-unaware date/time ("Plain")**: + - Date (year, month, day) + time (hour, minute, second, millisecond, nanosecond): {{jsxref("Temporal.PlainDateTime")}} + - Date (year, month, day): {{jsxref("Temporal.PlainDate")}} + - Year, month: {{jsxref("Temporal.PlainYearMonth")}} + - Month, day: {{jsxref("Temporal.PlainMonthDay")}} + - Time (hour, minute, second, millisecond, nanosecond): {{jsxref("Temporal.PlainTime")}} + - **Now** (current time) as various class instances, or in a specific format: {{jsxref("Temporal.Now")}} +- Currently the following calendar types are disabled for the `withCalendar()` method for [`PlainDate`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Temporal/PlainDate/withCalendar), [`PlainDateTime`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Temporal/PlainDateTime/withCalendar), and [`ZonedDateTime`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Temporal/ZonedDateTime/withCalendar) objects: + - `islamic` + - `islamic-rgsa` + - `islamic-umalqura` + +### SVG + +#### Removals + +- The experimental `<discard>` element has been removed, along with its corresponding {{domxref("SVGDiscardElement")}} JavaScript interface. + These aren't supported in other browsers and are expected to be removed from the specification. + ([Firefox bug 1958839](https://bugzil.la/1958839)). + +### HTTP + +No notable changes + +### APIs + +#### DOM + +- The {{domxref("HTMLDialogElement/requestClose", "requestClose()")}} method of the {{domxref("HTMLDialogElement")}} interface is now supported. + This allows developers to conditionally prevent a dialog from closing by providing a [`cancel` event](/en-US/docs/Web/API/HTMLDialogElement/cancel_event) handler. + ([Firefox bug 1960556](https://bugzil.la/1960556)). +- The [`largeBlob`](/en-US/docs/Web/API/Web_Authentication_API/WebAuthn_extensions#largeblob) and [`credProps`](/en-US/docs/Web/API/Web_Authentication_API/WebAuthn_extensions#credprops) Web Authentication extensions are now supported, while the [`prf`](/en-US/docs/Web/API/Web_Authentication_API/WebAuthn_extensions#prf) extension is supported on all desktop platforms. + These respectively provide support for large blob storage associated with a credential, additional information about a credential, and a mechanism for generating a random number associated with a credential and a particular input. + ([Firefox bug 1795020](https://bugzil.la/1795020), [Firefox bug 1844449](https://bugzil.la/1844449), [Firefox bug 1935280](https://bugzil.la/1935280)). + +### WebDriver conformance (WebDriver BiDi, Marionette) + +#### General + +- The priority manager (on macOS, the background QoS manager) in Firefox, which manages IPC message prioritization between the parent and content processes, has been temporarily disabled for all supported Remote Protocols. This change resolves an issue where, under high system load, initial page loads in newly opened background tabs were not being scheduled, resulting in certain commands hanging ([Firefox bug 1960734](https://bugzil.la/1960734)). + +#### WebDriver BiDi + +- Implemented the `emulation.setGeolocationOverride` command, allowing tests and automation tools to simulate geographic locations across specified browsing contexts or user contexts. This enables consumers to test location-aware features such as geofencing for local recommendations ([Firefox bug 1954992](https://bugzil.la/1954992)). + +## Changes for add-on developers + +- Localized extensions now cascade through locale subtags to find translations before reverting to the extension's default language. Previously, the extension used the extension default if a translation couldn't be found for a language with subtags. See [Localized string selection](/en-US/docs/Mozilla/Add-ons/WebExtensions/Internationalization#localized_string_selection) in the Internationalization article for more details of the new behavior. ([Firefox bug 1381580](https://bugzil.la/1381580)) +- Content scripts and styles are now guaranteed to execute in the order of registration (i.e., their order in the [`content_scripts` manifest key array](/en-US/docs/Mozilla/Add-ons/WebExtensions/manifest.json/content_scripts)). Previously, the order was only guaranteed for scripts within the same `js` array. ([Firefox bug 1792685](https://bugzil.la/1792685)) +- The {{WebExtAPIRef("tabGroups")}} API is now available. This API enables extensions to modify and rearrange [tab groups](https://support.mozilla.org/en-US/kb/tab-groups). For more information, see [WebExtensions Support for Tab Groups](https://blog.mozilla.org/addons/2025/04/30/webextensions-support-for-tab-groups/). ([Firefox bug 1940631](https://bugzil.la/1940631)) + +## Experimental web features + +These features are shipping in Firefox 139 but are disabled by default. To experiment with them, search for the appropriate preference on the `about:config` page and set it to `true`. You can find more such features on the [Experimental features](/en-US/docs/Mozilla/Firefox/Experimental_features) page. + +- **Prioritized Task Scheduling API** (Nightly release). + The [Prioritized Task Scheduling API](/en-US/docs/Web/API/Prioritized_Task_Scheduling_API) provides a standardized way to prioritize all tasks belonging to an application, whether they are defined in a website developer's code, or in third-party libraries and frameworks. + This adds support for the {{domxref("scheduler.yield()")}} method and re-enables the whole API in the Nightly release. + ([Firefox bug 1958943](https://bugzil.la/1958943), [Firefox bug 1920115](https://bugzil.la/1920115)). +- **View Transition API** (Nightly release). + The [View Transition API](/en-US/docs/Web/API/View_Transition_API) has been enabled for [SPAs (single-page applications)](/en-US/docs/Glossary/SPA). It provides a mechanism for easily creating animated transitions between different website views. ([Firefox bug 1950759](https://bugzil.la/1950759)). +- **Support for escaping `<` and `>` in attributes when serializing HTML**: `dom.security.html_serialization_escape_lt_gt`. + Firefox now replaces the `<` and `>` characters with `&lt;` and `&gt;`, respectively, in attributes when serializing HTML. This helps prevent certain exploits where HTML is serialized and then injected back into the DOM. + The affected methods and properties are: {{domxref("Element.innerHTML")}}, {{domxref("Element.outerHTML")}}, {{domxref("Element.getHTML()")}}, {{domxref("ShadowRoot.innerHTML")}}, and {{domxref("ShadowRoot.getHTML()")}}. ([Firefox bug 1941347](https://bugzil.la/1941347)). +- **Disable non-standard `beforescriptexecute` and `afterscriptexecute`**: `dom.events.script_execute.enabled`. + The events have been disabled on Nightly only, allowing browser testing prior to their removal. + The affected events are: [`beforescriptexecute`](/en-US/docs/Web/API/Document/beforescriptexecute_event) and [`afterscriptexecute`](/en-US/docs/Web/API/Document/afterscriptexecute_event) on the {{domxref("Document")}} interface, and [`afterscriptexecute`](/en-US/docs/Web/API/Element/afterscriptexecute_event) and [`beforescriptexecute`](/en-US/docs/Web/API/Element/beforescriptexecute_event) on the {{domxref("Element")}} interface. ([Firefox bug 1954685](https://bugzil.la/1954685)). + +## Older versions + +{{Firefox_for_developers}} diff --git a/files/en-us/mozilla/firefox/releases/14/index.md b/files/en-us/mozilla/firefox/releases/14/index.md index 0fd60089737b820..a12ab14b1f762cc 100644 --- a/files/en-us/mozilla/firefox/releases/14/index.md +++ b/files/en-us/mozilla/firefox/releases/14/index.md @@ -13,7 +13,7 @@ Firefox 14 shipped on July 17, 2012. This article lists key changes that are use ### HTML - The {{HTMLElement("progress")}} element is no longer incorrectly classified as a form element, and therefore no longer has a `form` attribute. -- The default modifier keys for the [`accesskey`](/en-US/docs/Web/HTML/Global_attributes) of HTML contents on Mac are changed to Control+Option. This is the same as WebKit-based browsers on Mac. +- The default modifier keys for the [`accesskey`](/en-US/docs/Web/HTML/Reference/Global_attributes) of HTML contents on Mac are changed to Control+Option. This is the same as WebKit-based browsers on Mac. ### DOM @@ -47,7 +47,7 @@ _No change._ ### HTTP -- Gecko now supports the new [HTTP](/en-US/docs/Web/HTTP) [`308 Permanent Redirect`](/en-US/docs/Web/HTTP/Status#308) status code. As Gecko doesn't make a distinction between permanent and temporary redirects, it behaves like the [`307 Temporary Redirect`](/en-US/docs/Web/HTTP/Status#307) status code, as it forbids the user agent from changing the HTTP method used between the two requests (`POST` will stay `POST`, `GET` will stay `GET`). +- Gecko now supports the new [HTTP](/en-US/docs/Web/HTTP) [`308 Permanent Redirect`](/en-US/docs/Web/HTTP/Reference/Status#308) status code. As Gecko doesn't make a distinction between permanent and temporary redirects, it behaves like the [`307 Temporary Redirect`](/en-US/docs/Web/HTTP/Reference/Status#307) status code, as it forbids the user agent from changing the HTTP method used between the two requests (`POST` will stay `POST`, `GET` will stay `GET`). ## Changes for Mozilla and add-on developers diff --git a/files/en-us/mozilla/firefox/releases/140/index.md b/files/en-us/mozilla/firefox/releases/140/index.md new file mode 100644 index 000000000000000..f4475675fd9725e --- /dev/null +++ b/files/en-us/mozilla/firefox/releases/140/index.md @@ -0,0 +1,118 @@ +--- +title: Firefox 140 for developers +slug: Mozilla/Firefox/Releases/140 +page-type: firefox-release-notes +sidebar: firefoxsidebar +--- + +This article provides information about the changes in Firefox 140 that affect developers. Firefox 140 is the current [Beta version of Firefox](https://www.mozilla.org/en-US/firefox/channel/desktop/#beta) and ships on [June 24, 2025](https://whattrainisitnow.com/release/?version=140). + +## Changes for web developers + +### Developer Tools + +### HTML + +#### Removals + +### CSS + +#### Removals + +### JavaScript + +#### Removals + +### SVG + +#### Removals + +### HTTP + +#### Removals + +### Security + +#### Removals + +### APIs + +- A subset of the [Cookie Store API](/en-US/docs/Web/API/Cookie_Store_API) is now supported ([Firefox bug 1958875](https://bugzil.la/1958875)). + + The API is a modern, {{glossary("asynchronous")}} {{jsxref("Promise")}}-based method of managing cookies, which can be used in both the main thread and in [service workers](/en-US/docs/Web/API/Service_Worker_API). The part of the API that is supported includes: + + - The [`CookieStore`](/en-US/docs/Web/API/CookieStore) interface, for getting, setting, and deleting cookies. + - The [`Window.cookieStore`](/en-US/docs/Web/API/Window/cookieStore) and [`ServiceWorkerGlobalScope.cookieStore`](/en-US/docs/Web/API/ServiceWorkerGlobalScope/cookieStore) properties for getting `CookieStore` instances. + - The [`change` event](/en-US/docs/Web/API/CookieStore/change_event) (and its interface [`CookieChangeEvent`](/en-US/docs/Web/API/CookieChangeEvent)), which fires in main thread and service worker contexts when cookies are set or deleted. + + Note that while any of the supported cookie properties can be [set](/en-US/docs/Web/API/CookieStore/set), the cookie objects returned by the [`get()`](/en-US/docs/Web/API/CookieStore/get) and [`getAll()`](/en-US/docs/Web/API/CookieStore/getAll) methods, and in the `change` event, omit all properties other than `name` and `value` (matching the information returned by the {{domxref("document.cookie")}}). + + The following interfaces and properties are not implemented: [`ServiceWorkerRegistration.cookies`](/en-US/docs/Web/API/ServiceWorkerRegistration/cookies), [`CookieStoreManager`](/en-US/docs/Web/API/CookieStoreManager), and [`ExtendableCookieChangeEvent`](/en-US/docs/Web/API/ExtendableCookieChangeEvent). + +### Escape < and > in attributes when serializing HTML + +- {{domxref("Element.innerHTML")}}, {{domxref("Element.outerHTML")}}, {{domxref("Element.getHTML()")}}, {{domxref("ShadowRoot.innerHTML")}}, and {{domxref("ShadowRoot.getHTML()")}} now replace the `<` and `>` characters with `&lt;` and `&gt;` (respectively) when serializing the HTML to a string. This prevents certain exploits where HTML is serialized and then injected back into the DOM. + ([Firefox bug 1962084](https://bugzil.la/1962084)). + +#### DOM + +- The [`pointerrawupdate` event](/en-US/docs/Web/API/Element/pointerrawupdate_event) is now supported. + This event typically provides lower-latency access to pointer movement properties compared to the corresponding [`pointermove`](/en-US/docs/Web/API/Element/pointermove_event) events, firing as soon as the pointer data is available. + It is intended for applications that require high-precision input handling, and that cannot achieve smooth interaction using coalesced `pointermove` events alone. + Because listening to this event may impact performance, you should avoid using it for other use cases. + ([Firefox bug 1550462](https://bugzil.la/1550462)). + +#### Media, WebRTC, and Web Audio + +#### Removals + +### WebAssembly + +#### Removals + +### WebDriver conformance (WebDriver BiDi, Marionette) + +#### General + +#### WebDriver BiDi + +#### Marionette + +## Changes for add-on developers + +- Support added for `unspecified` in {{WebExtAPIRef("cookies.SameSiteStatus")}}. In addition, `unspecified` is now the default value for `sameSite` in {{WebExtAPIRef("cookies.set()")}}. ([Firefox bug 1550032](https://bugzil.la/1550032)) + +### Removals + +### Other + +## Experimental web features + +These features are shipping in Firefox 140 but are disabled by default. To experiment with them, search for the appropriate preference on the `about:config` page and set it to `true`. You can find more such features on the [Experimental features](/en-US/docs/Mozilla/Firefox/Experimental_features) page. + +- **`Notification.maxActions`** (Nightly): `dom.webnotifications.actions.enabled` + + The [`Notification.maxActions`](/en-US/docs/Web/API/Notification/maxActions_static) read-only static property returns the browser limit on the number of actions that can be associated with a `Notification`, which you create using {{domxref("ServiceWorkerRegistration.showNotification()")}}. + This was released prematurely in Firefox version 138, and this change makes it available only in the Nightly build. ([Firefox bug 1963263](https://bugzil.la/1963263)). + +- **`closedBy` attribute for `<dialog>`** (Nightly): `dom.dialog.light-dismiss.enabled` + + The {{domxref("HTMLDialogElement/closedBy", "closedBy")}} attribute of the {{domxref("HTMLDialogElement")}} interface, and corresponding [`closedby`](/en-US/docs/Web/HTML/Reference/Elements/dialog#closedby) attribute of the {{htmlelement("dialog")}} element, are supported. + Developers can use these to specify what mechanisms are able to close the dialogs, such as user interaction outside the dialog ("light dismiss") or programmatic closing. + ([Firefox bug 1964077](https://bugzil.la/1964077)). + +- **`Atomics.waitAsync()`**: `javascript.options.atomics_wait_async` + + The {{jsxref("Atomics.waitAsync()")}} static method waits asynchronously on a shared memory location and returns an object representing the result of the operation. + It is non-blocking and usable on the main thread. + ([Firefox bug 1467846](https://bugzil.la/1467846)). + +- **Prioritized Task Scheduling API** (Nightly release). + The [Prioritized Task Scheduling API](/en-US/docs/Web/API/Prioritized_Task_Scheduling_API) provides a standardized way to prioritize all tasks belonging to an application, whether they are defined in a website developer's code, or in third-party libraries and frameworks. + This adds support for the [`TaskSignal.any()`](/en-US/docs/Web/API/TaskSignal/any_static) static method, which returns a signal that is triggered when any of the `TaskSignal` objects it is created from are triggered. + The API is now feature complete. + ([Firefox bug 1964407](https://bugzil.la/1964407)). + +## Older versions + +{{Firefox_for_developers}} diff --git a/files/en-us/mozilla/firefox/releases/141/index.md b/files/en-us/mozilla/firefox/releases/141/index.md new file mode 100644 index 000000000000000..57db768cd9e19ff --- /dev/null +++ b/files/en-us/mozilla/firefox/releases/141/index.md @@ -0,0 +1,73 @@ +--- +title: Firefox 141 for developers +slug: Mozilla/Firefox/Releases/141 +page-type: firefox-release-notes +sidebar: firefoxsidebar +--- + +This article provides information about the changes in Firefox 141 that affect developers. +Firefox 141 is the current [Nightly version of Firefox](https://www.mozilla.org/en-US/firefox/channel/desktop/#nightly) and ships on [July 22, 2025](https://whattrainisitnow.com/release/?version=141). + +## Changes for web developers + +### Developer Tools + +### HTML + +#### Removals + +### CSS + +#### Removals + +### JavaScript + +#### Removals + +### SVG + +#### Removals + +### HTTP + +#### Removals + +### Security + +#### Removals + +### APIs + +#### DOM + +#### Media, WebRTC, and Web Audio + +#### Removals + +### WebAssembly + +#### Removals + +### WebDriver conformance (WebDriver BiDi, Marionette) + +#### General + +#### WebDriver BiDi + +#### Marionette + +## Changes for add-on developers + +### Removals + +### Other + +## Experimental web features + +These features are shipping in Firefox 141 but are disabled by default. +To experiment with them, search for the appropriate preference on the `about:config` page and set it to `true`. +You can find more such features on the [Experimental features](/en-US/docs/Mozilla/Firefox/Experimental_features) page. + +## Older versions + +{{Firefox_for_developers}} diff --git a/files/en-us/mozilla/firefox/releases/15/index.md b/files/en-us/mozilla/firefox/releases/15/index.md index 40ac165bb5569a9..73553a10ba82336 100644 --- a/files/en-us/mozilla/firefox/releases/15/index.md +++ b/files/en-us/mozilla/firefox/releases/15/index.md @@ -39,8 +39,8 @@ Firefox 15 shipped on August 28, 2012. This article lists key changes that are u - The [WebSMS API](https://web.archive.org/web/20210620092659/https://developer.mozilla.org/en-US/docs/Archive/B2G_OS/API/Mobile_Messaging_API) has been updated and now supports a `read` attribute indicating whether an SMS text message is read or unread. - The [FileHandle API](https://wiki.mozilla.org/WebAPI/FileHandleAPI) has been implemented. - The [`Blob`](/en-US/docs/Web/API/Blob) constructor now takes `ArrayBufferView` as a member of `blobParts` parameter in addition to `ArrayBuffer`. ([bug 752402](https://bugzil.la/752402)) -- The `DeviceLightEvent` specified in the [Ambient Light Events Working Draft](https://www.w3.org/TR/ambient-light/) has been implemented. -- The `DeviceProximityEvent` and `UserProximityEvent` [Proximity Events](https://www.w3.org/TR/proximity/) have been implemented. +- The `DeviceLightEvent` specified in the [Ambient Light Events Working Draft](https://w3c.github.io/ambient-light/) has been implemented. +- The `DeviceProximityEvent` and `UserProximityEvent` [Proximity Events](https://w3c.github.io/proximity/) have been implemented. - The {{domxref("File")}} `lastModifiedDate` property has been implemented. ([Firefox bug 673586](https://bugzil.la/673586)) ### JavaScript @@ -59,7 +59,7 @@ Firefox 15 shipped on August 28, 2012. This article lists key changes that are u - Mathematical operators can now use downloadable fonts specified with {{cssxref("@font-face")}}. This makes the [MathML-fonts add-on](https://addons.mozilla.org/en-US/firefox/addon/mathml-fonts/) work with stretchy operators too. - The `selection` attribute of the {{MathMLElement("maction")}} is now only taken into account with the `toggle` actiontype. - [Deprecated namedspace binding](https://www.w3.org/TR/MathML3/chapter3.html#id.3.3.4.2.1) has been removed ([Firefox bug 673759](https://bugzil.la/673759)). -- Supported syntax for [Length](/en-US/docs/Web/MathML/Values) and {{MathMLElement("mpadded")}} values have been made closer to the one specified in MathML3 spec. +- Supported syntax for [Length](/en-US/docs/Web/MathML/Reference/Values) and {{MathMLElement("mpadded")}} values have been made closer to the one specified in MathML3 spec. - New MathML mirrorable operators for Arabic math have been added to the operator dictionary ([Firefox bug 757125](https://bugzil.la/757125)). ### SVG diff --git a/files/en-us/mozilla/firefox/releases/17/index.md b/files/en-us/mozilla/firefox/releases/17/index.md index 12f2008291a743c..0813632d10b68e4 100644 --- a/files/en-us/mozilla/firefox/releases/17/index.md +++ b/files/en-us/mozilla/firefox/releases/17/index.md @@ -12,7 +12,7 @@ Firefox 17 shipped on November 20, 2012. This article lists key changes that are ### HTML -- Support for the [`sandbox`](/en-US/docs/Web/HTML/Element/iframe#sandbox) attribute on the {{HTMLElement("iframe")}} element has been added. ([Firefox bug 341604](https://bugzil.la/341604)) +- Support for the [`sandbox`](/en-US/docs/Web/HTML/Reference/Elements/iframe#sandbox) attribute on the {{HTMLElement("iframe")}} element has been added. ([Firefox bug 341604](https://bugzil.la/341604)) ### CSS @@ -36,7 +36,7 @@ Firefox 17 shipped on November 20, 2012. This article lists key changes that are ### JavaScript - [`String`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/String) object now offers Harmony [`startsWith`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/String/startsWith), [`endsWith`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/String/endsWith), and [`contains`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/String/includes) methods ([Firefox bug 772733](https://bugzil.la/772733)). -- The String methods [link](/en-US/docs/Web/JavaScript/Reference/Global_Objects/String/link) and [anchor](/en-US/docs/Web/JavaScript/Reference/Global_Objects/String/anchor) now escape the `'"'` (quotation mark) ([Firefox bug 352437](https://bugzil.la/352437)). +- The String methods [`link()`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/String/link) and [`anchor()`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/String/anchor) now escape the `'"'` (quotation mark) ([Firefox bug 352437](https://bugzil.la/352437)). - Experimental support for strawman `ParallelArray` object has been implemented ([Firefox bug 778559](https://bugzil.la/778559)). - Support to iterate [`Map`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Map)/[`Set`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Set) ([Firefox bug 725909](https://bugzil.la/725909)). - Disabled ECMAScript for XML (E4X), an abandoned JavaScript extension, for web content by default ([Firefox bug 778851](https://bugzil.la/778851)). diff --git a/files/en-us/mozilla/firefox/releases/18/index.md b/files/en-us/mozilla/firefox/releases/18/index.md index 8c8bfa42fb77dd4..3b61685a8f42178 100644 --- a/files/en-us/mozilla/firefox/releases/18/index.md +++ b/files/en-us/mozilla/firefox/releases/18/index.md @@ -12,9 +12,9 @@ Firefox 18 was released on January 8, 2013. This article lists key changes that ### HTML -- The [`reversed`](/en-US/docs/Web/HTML/Element/ol#reversed) attribute of the {{HTMLElement("ol")}} element is now supported ([Firefox bug 601912](https://bugzil.la/601912)). -- The [`crossorigin`](/en-US/docs/Web/HTML/Element/link#crossorigin) attribute of the {{HTMLElement("link")}} element is now supported ([Firefox bug 786564](https://bugzil.la/786564)). -- The [`allowfullscreen`](/en-US/docs/Web/HTML/Element/iframe#allowfullscreen) attribute of the {{HTMLElement("iframe")}} has been implemented and it's prefixed predecessor [`mozallowfullscreen`](/en-US/docs/Web/HTML/Element/iframe#mozallowfullscreen) is now deprecated. +- The [`reversed`](/en-US/docs/Web/HTML/Reference/Elements/ol#reversed) attribute of the {{HTMLElement("ol")}} element is now supported ([Firefox bug 601912](https://bugzil.la/601912)). +- The [`crossorigin`](/en-US/docs/Web/HTML/Reference/Elements/link#crossorigin) attribute of the {{HTMLElement("link")}} element is now supported ([Firefox bug 786564](https://bugzil.la/786564)). +- The [`allowfullscreen`](/en-US/docs/Web/HTML/Reference/Elements/iframe#allowfullscreen) attribute of the {{HTMLElement("iframe")}} has been implemented and it's prefixed predecessor [`mozallowfullscreen`](/en-US/docs/Web/HTML/Reference/Elements/iframe#mozallowfullscreen) is now deprecated. ### CSS @@ -52,8 +52,8 @@ Firefox 18 was released on January 8, 2013. This article lists key changes that ### Network -- Quality factors ("q-values") are now clamped to 2 digits (e.g. in HTTP {{HTTPHeader("Accept-Language")}} headers) ([Firefox bug 672448](https://bugzil.la/672448)). -- The `ALLOW-FROM` syntax of the [`X-FRAME-OPTIONS`](/en-US/docs/Web/HTTP/Headers/X-Frame-Options) HTTP Response header is now supported ([Firefox bug 690168](https://bugzil.la/690168)). +- Quality factors ("q-values") are now clamped to 2 digits (e.g., in HTTP {{HTTPHeader("Accept-Language")}} headers) ([Firefox bug 672448](https://bugzil.la/672448)). +- The `ALLOW-FROM` syntax of the [`X-FRAME-OPTIONS`](/en-US/docs/Web/HTTP/Reference/Headers/X-Frame-Options) HTTP Response header is now supported ([Firefox bug 690168](https://bugzil.la/690168)). ### Developer tools diff --git a/files/en-us/mozilla/firefox/releases/2/index.md b/files/en-us/mozilla/firefox/releases/2/index.md index a1fa4eb563f1927..30f2c480c02bc8f 100644 --- a/files/en-us/mozilla/firefox/releases/2/index.md +++ b/files/en-us/mozilla/firefox/releases/2/index.md @@ -30,7 +30,7 @@ Firefox 2 introduces a vast array of new features and capabilities. This article - : Client-side session and persistent storage allows web applications to store structured data on the client side. - [SVG in Firefox](/en-US/docs/Web/SVG/SVG_1.1_Support_in_Firefox) - : Firefox 2 improves Scalable Vector Graphics (SVG) support, implementing the `<textPath>` element and adding support for some attributes not previously supported. -- [Controlling spell checking in HTML forms](/en-US/docs/Web/HTML/Global_attributes/spellcheck) +- [Controlling spell checking in HTML forms](/en-US/docs/Web/HTML/Reference/Global_attributes/spellcheck) - : Firefox 2 includes support for inline spell checking in text areas and text fields. This article describes how to write your HTML to enable and disable spell checking on individual form elements. - [Security in Firefox 2](/en-US/docs/Mozilla/Firefox/Releases/2/Security_changes) - : Firefox 2 has changes to which security protocols are enabled by default. diff --git a/files/en-us/mozilla/firefox/releases/2/updating_extensions/index.md b/files/en-us/mozilla/firefox/releases/2/updating_extensions/index.md index 18b4b1ffe8cff7f..31b0b7460029f69 100644 --- a/files/en-us/mozilla/firefox/releases/2/updating_extensions/index.md +++ b/files/en-us/mozilla/firefox/releases/2/updating_extensions/index.md @@ -38,6 +38,6 @@ Be sure to test your extension carefully on Firefox 2 before you release it to t ## Step 4: Release -Update your extension's entry on [https://addons.mozilla.org](https://addons.mozilla.org). This will ensure that users can find it. +Update your extension's entry on [https://addons.mozilla.org](https://addons.mozilla.org/). This will ensure that users can find it. In addition, if your extension provides an [`updateURL`](/en-US/Install_Manifests#updateurl) in the install manifest, be sure to update the update manifest so that the new version of your extension can be found automatically by Firefox. By doing this, the first time the user runs your extension after upgrading to Firefox 2, Firefox can offer to automatically install it for them. diff --git a/files/en-us/mozilla/firefox/releases/20/index.md b/files/en-us/mozilla/firefox/releases/20/index.md index e8dac51c25a1cfd..2fe115de593e230 100644 --- a/files/en-us/mozilla/firefox/releases/20/index.md +++ b/files/en-us/mozilla/firefox/releases/20/index.md @@ -12,9 +12,9 @@ Firefox 20 was released on April, 2nd 2013. This article provides information ab ### HTML -- Support for the [`download`](/en-US/docs/Web/HTML/Element/a#download) attribute on the {{HTMLElement("a")}} and {{HTMLElement("area")}} element has been added ([Firefox bug 676619](https://bugzil.la/676619)). -- The value `auto` for the [global attribute](/en-US/docs/Web/HTML/Global_attributes) [`dir`](/en-US/docs/Web/HTML/Global_attributes/dir) has been implemented ([Firefox bug 548206](https://bugzil.la/548206)). -- The [global attribute](/en-US/docs/Web/HTML/Global_attributes) `contextmenu` now works on Firefox for Android ([Firefox bug 736321](https://bugzil.la/736321)). +- Support for the [`download`](/en-US/docs/Web/HTML/Reference/Elements/a#download) attribute on the {{HTMLElement("a")}} and {{HTMLElement("area")}} element has been added ([Firefox bug 676619](https://bugzil.la/676619)). +- The value `auto` for the [global attribute](/en-US/docs/Web/HTML/Reference/Global_attributes) [`dir`](/en-US/docs/Web/HTML/Reference/Global_attributes/dir) has been implemented ([Firefox bug 548206](https://bugzil.la/548206)). +- The [global attribute](/en-US/docs/Web/HTML/Reference/Global_attributes) `contextmenu` now works on Firefox for Android ([Firefox bug 736321](https://bugzil.la/736321)). ### JavaScript @@ -56,7 +56,7 @@ Firefox 20 was released on April, 2nd 2013. This article provides information ab ### MathML - To help MathML authors debugging "invalid-markup" errors in their documents, MathML parsing errors (such as having too many / too few child elements) and warnings about deprecated attributes or wrong attribute values are now reported to the error console. -- The `scriptminsize` attribute now accepts unitless values and percent values. They are interpreted as multiples of the default value ("`8pt`"). +- The `scriptminsize` attribute now accepts unitless values and percent values. They are interpreted as multiples of the default value (`8pt`). - Unitless values are now also allowed for the `mathsize` and `fontsize` attributes; they multiply the default value. ## Changes for add-on and Mozilla developers diff --git a/files/en-us/mozilla/firefox/releases/21/index.md b/files/en-us/mozilla/firefox/releases/21/index.md index b266f06aabc447b..ee829299917ce1f 100644 --- a/files/en-us/mozilla/firefox/releases/21/index.md +++ b/files/en-us/mozilla/firefox/releases/21/index.md @@ -12,7 +12,7 @@ Firefox 21 was released on May 14, 2013. This article lists key changes that are ### HTML -- The [`scoped`](/en-US/docs/Web/HTML/Element/style#scoped) attribute has been added to the {{HTMLElement("style")}} element. It allows to include styles that are isolated from the rest of the document. Such styles can be selected using the {{cssxref(":scope")}} CSS pseudo-element introduced in Firefox 20. ([Firefox bug 508725](https://bugzil.la/508725)). +- The [`scoped`](/en-US/docs/Web/HTML/Reference/Elements/style#scoped) attribute has been added to the {{HTMLElement("style")}} element. It allows to include styles that are isolated from the rest of the document. Such styles can be selected using the {{cssxref(":scope")}} CSS pseudo-element introduced in Firefox 20. ([Firefox bug 508725](https://bugzil.la/508725)). - The new HTML {{HTMLElement("main")}} element has been implemented ([Firefox bug 820508](https://bugzil.la/820508)). ### JavaScript @@ -38,13 +38,13 @@ Firefox 21 was released on May 14, 2013. This article lists key changes that are - Various keyCode values for OEM specific keys on Windows are now supported again ([Firefox bug 833719](https://bugzil.la/833719)). - The function [`window.crypto.getRandomValues`](/en-US/docs/Web/API/Crypto/getRandomValues) has been implemented ([Firefox bug 440046](https://bugzil.la/440046)). - The non-standard methods `NodeIterator.expandEntityReferences()` and `TreeWalker.expandEntityReferences()` have been removed ([Firefox bug 672190](https://bugzil.la/672190)). -- CSSOM: the method {{domxref("CSSKeyframesRule")}}`.insertRule` has been removed to {{domxref("CSSKeyframesRule")}}`.appendRule` to match a spec change ([Firefox bug 841896](https://bugzil.la/841896)). +- CSSOM: the method `CSSKeyframesRule.insertRule()` has been removed to {{domxref("CSSKeyframesRule.appendRule()")}} to match a spec change ([Firefox bug 841896](https://bugzil.la/841896)). - CSSOM If the given parameter given to {{domxref("CSSStyleSheet.insertRule")}} contains more than one rule, a {{domxref("DOMException")}} with a `SYNTAX_ERR` is now thrown ([Firefox bug 765599](https://bugzil.la/765599)). - Until now, when the same headers were repeatedly set with [`XMLHttpRequest.setRequestHeader`](/en-US/docs/Web/API/XMLHttpRequest#setrequestheader), the last-specified value was used. This behavior has been changed to comply with the spec, so those values will be properly combined ([Firefox bug 819051](https://bugzil.la/819051)). ### SVG -- The [paint-order](/en-US/docs/Web/SVG/Attribute/paint-order) attribute has been implemented ([Firefox bug 828805](https://bugzil.la/828805)). +- The [paint-order](/en-US/docs/Web/SVG/Reference/Attribute/paint-order) attribute has been implemented ([Firefox bug 828805](https://bugzil.la/828805)). - The `svg.smil.enabled` preference has been removed. SMIL is always on. ([Firefox bug 835030](https://bugzil.la/835030)) ### Networking diff --git a/files/en-us/mozilla/firefox/releases/22/index.md b/files/en-us/mozilla/firefox/releases/22/index.md index 43d25ff29fb74af..a7f6a2220eac8ad 100644 --- a/files/en-us/mozilla/firefox/releases/22/index.md +++ b/files/en-us/mozilla/firefox/releases/22/index.md @@ -6,6 +6,8 @@ page-type: firefox-release-notes {{FirefoxSidebar}} +Firefox 22 was released on June 25, 2013. This article lists key changes that are useful not only for web developers, but also Firefox and Gecko developers as well as add-on developers. + ## Changes for Web developers ### HTML @@ -54,7 +56,7 @@ page-type: firefox-release-notes - The `properties` parameter has been removed from the `nsITreeView.getCellProperties()`, `nsITreeView.getColumnProperties()` and `nsITreeView.getRowProperties()` methods of `nsITreeView`. These methods should now return a string of space-separated property names ([Firefox bug 407956](https://bugzil.la/407956)). - The `inIDOMUtils.getCSSPropertyNames()` method has been implemented and will return all supported [CSS property](/en-US/docs/Web/CSS/Reference) names. -- See [here](https://blog.mozilla.org/addons/2013/06/03/compatibility-for-firefox-22/) for more changes. +- See [the Mozilla blog](https://blog.mozilla.org/addons/2013/06/03/compatibility-for-firefox-22/) for more changes. ### Firefox Developer Tools diff --git a/files/en-us/mozilla/firefox/releases/23/index.md b/files/en-us/mozilla/firefox/releases/23/index.md index 2a55beb870b2ed1..952b9feb74dee82 100644 --- a/files/en-us/mozilla/firefox/releases/23/index.md +++ b/files/en-us/mozilla/firefox/releases/23/index.md @@ -11,7 +11,7 @@ page-type: firefox-release-notes ### Security - Mixed content blocking. Firefox will no longer load non-secure (http) resources on secure (https) pages ([Firefox bug 834836](https://bugzil.la/834836)). -- The standard syntax of [CSP](/en-US/docs/Web/HTTP/CSP) 1.0 policies are now implemented and enforced by default. +- The standard syntax of [CSP](/en-US/docs/Web/HTTP/Guides/CSP) 1.0 policies are now implemented and enforced by default. ### Developer Tools @@ -22,7 +22,7 @@ page-type: firefox-release-notes ### HTML - The `<blink>` element support is now completely dropped. The `<blink>` tag now implements the {{domxref("HTMLUnknownElement")}} interface ([Firefox bug 857820](https://bugzil.la/857820)). -- The `range` type of the {{HTMLElement("input")}} element ([`<input type="range">`](/en-US/docs/Web/HTML/Element/input/range)) has been switched on by default ([Firefox bug 841950](https://bugzil.la/841950)). +- The `range` type of the {{HTMLElement("input")}} element ([`<input type="range">`](/en-US/docs/Web/HTML/Reference/Elements/input/range)) has been switched on by default ([Firefox bug 841950](https://bugzil.la/841950)). ### JavaScript @@ -45,7 +45,7 @@ page-type: firefox-release-notes ### WebRTC -- Instead of including usernames in the `RTCIceServer.url` property (such as stun:username\@stunserver.example.com), you now need to use the new `RTCIceServer.username` property. +- Instead of including usernames in the `RTCIceServer.url` property (such as `stun:username@stunserver.example.com`), you now need to use the new `RTCIceServer.username` property. ### CSS diff --git a/files/en-us/mozilla/firefox/releases/24/index.md b/files/en-us/mozilla/firefox/releases/24/index.md index d9ec72d8aa25f67..38715d026b8cec8 100644 --- a/files/en-us/mozilla/firefox/releases/24/index.md +++ b/files/en-us/mozilla/firefox/releases/24/index.md @@ -6,6 +6,8 @@ page-type: firefox-release-notes {{FirefoxSidebar}} +Firefox 24 was released on September 17, 2013. This article lists key changes that are useful not only for web developers, but also Firefox and Gecko developers as well as add-on developers. + ## Changes for Web developers ### CSS @@ -45,9 +47,9 @@ page-type: firefox-release-notes ### MathML -- The `dir` attribute for controlling directionality of formulas on e.g. {{MathMLElement("math")}} or {{MathMLElement("mrow")}} elements is now equivalent to using the {{cssxref("direction")}} CSS property. -- The equal sign ("=") is now [stretchable](/en-US/docs/Web/MathML/Element/mo#stretchy). -- The "`updiagonalarrow`" value for the `notation` attribute on {{MathMLElement("menclose")}} elements has been added. +- The `dir` attribute for controlling directionality of formulas on e.g., {{MathMLElement("math")}} or {{MathMLElement("mrow")}} elements is now equivalent to using the {{cssxref("direction")}} CSS property. +- The equal sign ("=") is now [stretchable](/en-US/docs/Web/MathML/Reference/Element/mo#stretchy). +- The `"updiagonalarrow"` value for the `notation` attribute on {{MathMLElement("menclose")}} elements has been added. ## Changes for add-on and Mozilla developers diff --git a/files/en-us/mozilla/firefox/releases/25/index.md b/files/en-us/mozilla/firefox/releases/25/index.md index 127493becf305f7..682289c81dd2796 100644 --- a/files/en-us/mozilla/firefox/releases/25/index.md +++ b/files/en-us/mozilla/firefox/releases/25/index.md @@ -26,7 +26,7 @@ page-type: firefox-release-notes ### HTML -- The [`srcdoc`](/en-US/docs/Web/HTML/Element/iframe#srcdoc) attribute of {{HTMLElement("iframe")}}, allowing the inline specification of the content of an {{HTMLElement("iframe")}}, is now supported ([Firefox bug 802895](https://bugzil.la/802895)). +- The [`srcdoc`](/en-US/docs/Web/HTML/Reference/Elements/iframe#srcdoc) attribute of {{HTMLElement("iframe")}}, allowing the inline specification of the content of an {{HTMLElement("iframe")}}, is now supported ([Firefox bug 802895](https://bugzil.la/802895)). - When used with a `"image/jpeg"` type, the method `HTMLCanvasElement.toBlob` now accepts a third attribute defining the quality of the image ([Firefox bug 891884](https://bugzil.la/891884)). ### JavaScript diff --git a/files/en-us/mozilla/firefox/releases/27/index.md b/files/en-us/mozilla/firefox/releases/27/index.md index 5a933f0bf0011a8..0225db71c72bc74 100644 --- a/files/en-us/mozilla/firefox/releases/27/index.md +++ b/files/en-us/mozilla/firefox/releases/27/index.md @@ -27,7 +27,7 @@ More details in [this post](https://hacks.mozilla.org/2013/11/firefox-developer- - The `-moz-grab` and `-moz-grabbing` keywords on the CSS {{cssxref("cursor")}} property have been unprefixed to `grab` and `grabbing` ([Firefox bug 880672](https://bugzil.la/880672)). - Support for the `-moz-hsla()` and `-moz-rgba()` functional notations has been dropped. Only the unprefixed versions, `hsla()` and `rgba()` are supported from now on ([Firefox bug 893319](https://bugzil.la/893319)). -- The "`true`" value for {{cssxref("text-align")}} has been added ([Firefox bug 929991](https://bugzil.la/929991)). +- The `true` value for {{cssxref("text-align")}} has been added ([Firefox bug 929991](https://bugzil.la/929991)). - Experimental support of `position:sticky` is now active by default on non-release builds ([Firefox bug 902992](https://bugzil.la/902992)). For releases builds, the `layout.css.sticky.enabled` preference still needs to be set to `true`. - The {{cssxref("all")}} shorthand property has been added ([Firefox bug 842329](https://bugzil.la/842329)). - The {{cssxref("unset")}} global value has been added; it allows to reset any CSS property ([Firefox bug 921731](https://bugzil.la/921731)). @@ -36,8 +36,8 @@ More details in [this post](https://hacks.mozilla.org/2013/11/firefox-developer- ### HTML -- The `color` value of the {{HTMLElement("input")}} [`type`](/en-US/docs/Web/HTML/Element/input#type) attribute has been implemented on desktop platforms. It was already available on mobile ones. -- The `allow-popups` directive is now supported with the [`sandbox`](/en-US/docs/Web/HTML/Element/iframe#sandbox) attribute of the {{HTMLElement("iframe")}} element ([Firefox bug 766282](https://bugzil.la/766282)). +- The `color` value of the {{HTMLElement("input")}} [`type`](/en-US/docs/Web/HTML/Reference/Elements/input#type) attribute has been implemented on desktop platforms. It was already available on mobile ones. +- The `allow-popups` directive is now supported with the [`sandbox`](/en-US/docs/Web/HTML/Reference/Elements/iframe#sandbox) attribute of the {{HTMLElement("iframe")}} element ([Firefox bug 766282](https://bugzil.la/766282)). - Blending of HTML elements using the {{cssxref("mix-blend-mode")}} property has been implemented. The `layout.css.mix-blend-mode.enabled` preference must be set to `true` ([Firefox bug 902525](https://bugzil.la/902525)). - The `typeMustMatch` property of the {{HTMLElement("object")}} element is now supported ([Firefox bug 827160](https://bugzil.la/827160)). diff --git a/files/en-us/mozilla/firefox/releases/28/index.md b/files/en-us/mozilla/firefox/releases/28/index.md index a437a1691de8457..c13d83ba3cfa950 100644 --- a/files/en-us/mozilla/firefox/releases/28/index.md +++ b/files/en-us/mozilla/firefox/releases/28/index.md @@ -50,11 +50,11 @@ More details in [this post](https://hacks.mozilla.org/2013/12/split-console-pret - `HTMLVideoElement.canPlayType('video/webm')` now reports `maybe`. ([Firefox bug 884275](https://bugzil.la/884275)). - The {{domxref("DocumentFragment.getElementById()")}} method has been implemented. E.g. `document.createDocumentFragment().getElementById()` ([Firefox bug 933193](https://bugzil.la/933193)). - The {{domxref("KeyboardEvent.repeat")}} attribute has been implemented ([Firefox bug 600117](https://bugzil.la/600117)). -- The {{domxref("File")}} constructor, e.g. `new File(["foo"], "foo.txt")` has been implemented. ([Firefox bug 819900](https://bugzil.la/819900)). +- The {{domxref("File")}} constructor, e.g., `new File(["foo"], "foo.txt")` has been implemented. ([Firefox bug 819900](https://bugzil.la/819900)). - The {{domxref("Navigator.plugins")}} is no more enumerable, for privacy reasons ([Firefox bug 757726](https://bugzil.la/757726)). - The two attributes {{domxref("Window.screenX")}} and {{domxref("Window.screenY")}} now return CSS pixels (and no more device pixels) ([Firefox bug 943668](https://bugzil.la/943668)). - The two methods `CanvasRenderingContext2D.drawSystemFocusRing()` and {{domxref("CanvasRenderingContext2D/drawFocusIfNeeded", "CanvasRenderingContext2D.drawCustomFocusRing()")}} have been implemented. The preference `canvas.focusring.enabled` must be set to `true` to activate both ([Firefox bug 540456](https://bugzil.la/540456)). -- The `willReadFrequently` context attribute for "`2d`" canvas contexts has been implemented (see {{domxref("HTMLCanvasElement.getContext()")}}) ([Firefox bug 884226](https://bugzil.la/884226)). +- The `willReadFrequently` context attribute for 2D canvas contexts has been implemented (see {{domxref("HTMLCanvasElement.getContext()")}}) ([Firefox bug 884226](https://bugzil.la/884226)). - The following attributes and methods of `NavigatorID` have been implemented on {{domxref("WorkerNavigator")}} to allow their use in workers: {{domxref("Navigator.appCodeName")}}, {{domxref("Navigator.product")}}, and {{domxref("Navigator.taintEnabled")}} ([Firefox bug 925847](https://bugzil.la/925847)). - The {{domxref("Element/previousElementSibling", "previousElementSibling")}} and {{domxref("Element/nextElementSibling", "nextElementSibling")}} properties has been removed from {{domxref("DocumentType")}}, because of compatibility problems ([Firefox bug 932501](https://bugzil.la/932501)). diff --git a/files/en-us/mozilla/firefox/releases/29/index.md b/files/en-us/mozilla/firefox/releases/29/index.md index d9f7815a0989579..6bbf929ed2cee3f 100644 --- a/files/en-us/mozilla/firefox/releases/29/index.md +++ b/files/en-us/mozilla/firefox/releases/29/index.md @@ -26,8 +26,8 @@ _See the [Mozilla Hacks blog post](https://hacks.mozilla.org/2014/02/css-source- ### CSS -- [CSS variables](/en-US/docs/Web/CSS/CSS_cascading_variables/Using_CSS_custom_properties) have been implemented ([Firefox bug 773296](https://bugzil.la/773296)). Mozilla Hacks article can be found [here](https://hacks.mozilla.org/2013/12/css-variables-in-firefox-nightly/). They are enabled by default only for non-release builds (on release builds flip the pref `layout.css.variables.enabled` to `true` if you want to play with them). -- Flexboxes now support {{cssxref("visibility")}}`: collapse` ([Firefox bug 783470](https://bugzil.la/783470)). +- [CSS variables](/en-US/docs/Web/CSS/CSS_cascading_variables/Using_CSS_custom_properties) have been implemented ([Firefox bug 773296](https://bugzil.la/773296)). The [CSS Variables in Firefox Nightly](https://hacks.mozilla.org/2013/12/css-variables-in-firefox-nightly/) on Mozilla Hacks contains more details. They are enabled by default only for non-release builds (on release builds flip the pref `layout.css.variables.enabled` to `true` if you want to play with them). +- Flexboxes now support {{cssxref("visibility", "visibility: collapse")}} ([Firefox bug 783470](https://bugzil.la/783470)). - The {{cssxref("box-sizing")}} property has been unprefixed ([Firefox bug 243412](https://bugzil.la/243412)). - The {{cssxref("will-change")}} property, a hint to that something will animate has been added. The preference `layout.css.will-change.enabled` must be switched to `true` to enable it. ([Firefox bug 940842](https://bugzil.la/940842)) - Scientific exponential notation, like `3e1` or `10e+0`, is now supported for {{cssxref("&lt;number&gt;")}} values and derivatives, like {{cssxref("&lt;percentage&gt;")}} and unit values, but not {{cssxref("&lt;integer&gt;")}} ([Firefox bug 964529](https://bugzil.la/964529)). @@ -81,7 +81,7 @@ _See the [Mozilla Hacks blog post](https://hacks.mozilla.org/2014/02/css-source- - The deprecated `Window.pkcs11` property has been removed; it was returning `null` since Firefox 3.0.14. ([Firefox bug 964964](https://bugzil.la/964964)) - The {{domxref("Node.cloneNode()")}} and {{domxref("Document.importNode()")}} methods take the Boolean `deep` argument. Until now, if omitted, these methods acted as if the value of `deep` was `true`. But this behavior has been changed as per the latest spec, and if omitted, the methods will act as if the value was `false`. ([Firefox bug 937461](https://bugzil.la/937461)) - `Window._content` is no longer available to Web content ([Firefox bug 946564](https://bugzil.la/946564)). -- {{domxref("HTMLAnchorElement/port", "URLUtils.port")}} behavior has been slightly changed: set to `''` will set it to the default port associated with the protocol, and `0` to `0.` ([Firefox bug 930450](https://bugzil.la/930450)) +- {{domxref("HTMLAnchorElement/port", "URLUtils.port")}} behavior has been slightly changed: set to `''` will set it to the default port associated with the protocol, and `0` to `0`. ([Firefox bug 930450](https://bugzil.la/930450)) - {{domxref("Document.referrer")}} is now based on the incumbent script ([Firefox bug 887928](https://bugzil.la/887928)). - The [Gamepad API](/en-US/docs/Web/API/Gamepad_API/Using_the_Gamepad_API) is enabled by default ([Firefox bug 878828](https://bugzil.la/878828)). - The `CanvasRenderingContext2D.drawSystemFocusRing()` method got renamed to {{domxref("CanvasRenderingContext2D.drawFocusIfNeeded()")}} ([Firefox bug 959820](https://bugzil.la/959820)). diff --git a/files/en-us/mozilla/firefox/releases/3.5/index.md b/files/en-us/mozilla/firefox/releases/3.5/index.md index 5d48dbf9fd9afa7..39e77fa464dacf6 100644 --- a/files/en-us/mozilla/firefox/releases/3.5/index.md +++ b/files/en-us/mozilla/firefox/releases/3.5/index.md @@ -15,7 +15,7 @@ page-type: firefox-release-notes #### HTML 5 support - [HTML video and audio](/en-US/docs/Learn_web_development/Core/Structuring_content/HTML_video_and_audio) - - : Firefox 3.5 adds support for the HTML 5 [`audio`](/en-US/docs/Web/HTML/Element/audio) and [`video`](/en-US/docs/Web/HTML/Element/video) elements. + - : Firefox 3.5 adds support for the HTML 5 [`audio`](/en-US/docs/Web/HTML/Reference/Elements/audio) and [`video`](/en-US/docs/Web/HTML/Reference/Elements/video) elements. - Offline resources in Firefox - : Firefox 3.5 now fully supports the HTML 5 offline resource specification. - [Drag and drop](/en-US/docs/Web/API/HTML_Drag_and_Drop_API) @@ -39,20 +39,8 @@ page-type: firefox-release-notes - : This newly-supported property lets content specify whether or not lines may be broken within words in order to prevent overflow when an otherwise unbreakable string is too long to fit on one line. - `white-space` property supports the `pre-line` value - : The {{ cssxref("white-space") }} property now accepts the `pre-line` value. -- `-moz-box-shadow` - - `-moz-border-image` - - `-moz-column-rule` - - `-moz-column-rule-width` - - `-moz-column-rule-style` - - `-moz-column-rule-color` - +- `-moz-box-shadow`, `-moz-border-image`, `-moz-column-rule`, `-moz-column-rule-width`, `-moz-column-rule-style`, `-moz-column-rule-color` - : Firefox 3.5 adds support for these Mozilla extensions to CSS. - - The {{ cssxref("color_value#Mozilla_Extensions","-moz-nativehyperlinktext") }} color value - : This new color value represents the user's system's default hyperlink color. - The `-moz-window-shadow` property and the `:-moz-system-metric(mac-graphite-theme)` pseudo-class @@ -61,20 +49,7 @@ page-type: firefox-release-notes - : The `-moz-win-glass` and `-moz-mac-unified-toolbar` values have been added to `-moz-appearance`. - [Using CSS transforms](/en-US/docs/Web/CSS/CSS_transforms/Using_CSS_transforms) - : Firefox 3.5 supports CSS transforms. See {{ cssxref("transform", "-moz-transform") }} and {{ cssxref("transform-origin", "-moz-transform-origin") }} for details. -- {{ cssxref(":nth-child") }} - - {{ cssxref(":nth-last-child") }} - - {{ cssxref(":nth-of-type") }} - - {{ cssxref(":nth-last-of-type") }} - - {{ cssxref(":first-of-type") }} - - {{ cssxref(":last-of-type") }} - - {{ cssxref(":only-of-type") }} - +- {{ cssxref(":nth-child") }}, {{ cssxref(":nth-last-child") }}, {{ cssxref(":nth-of-type") }}, {{ cssxref(":nth-last-of-type") }}, {{ cssxref(":first-of-type") }}, {{ cssxref(":last-of-type") }}, {{ cssxref(":only-of-type") }} - : These selectors are all newly-supported in Firefox 3.5. #### New DOM features @@ -127,18 +102,18 @@ page-type: firefox-release-notes - [`createImageData()`](/en-US/docs/Web/API/Canvas_API/Tutorial/Pixel_manipulation_with_canvas#creating_an_imagedata_object) - : The canvas method `createImageData()` is now supported, allowing code to specifically create an `ImageData` object instead of requiring it to be done automatically. This can improve performance of other `ImageData` methods by preventing them from having to create the object. - `moz-opaque` attribute - - : Added the [`moz-opaque`](/en-US/docs/Web/HTML/Element/canvas#moz-opaque) attribute, which lets the canvas know whether or not translucency will be a factor. If the canvas knows there's no translucency, painting performance can be optimized. See also {{domxref("HTMLCanvasElement.mozOpaque")}}. + - : Added the [`moz-opaque`](/en-US/docs/Web/HTML/Reference/Elements/canvas#moz-opaque) attribute, which lets the canvas know whether or not translucency will be a factor. If the canvas knows there's no translucency, painting performance can be optimized. See also {{domxref("HTMLCanvasElement.mozOpaque")}}. #### New SVG features -- [Applying SVG effects to HTML content](/en-US/docs/Web/SVG/Applying_SVG_effects_to_HTML_content) +- [Applying SVG effects to HTML content](/en-US/docs/Web/SVG/Guides/Applying_SVG_effects_to_HTML_content) - : You can now apply SVG effects to HTML and XHTML content; this article describes how. #### Miscellaneous new features - [ICC color correction in Firefox](/en-US/docs/Mozilla/Firefox/Releases/3.5/ICC_color_correction_in_Firefox) - : Firefox 3.5 now supports ICC color correction for tagged images. -- The `defer` attribute is now supported on [`script`](/en-US/docs/Web/HTML/Element/script) elements +- The `defer` attribute is now supported on [`script`](/en-US/docs/Web/HTML/Reference/Elements/script) elements - : This attribute indicates to the browser that it _may_ choose to continue to parse and render the page without waiting for the script to finish executing. ### Other improvements @@ -154,7 +129,7 @@ page-type: firefox-release-notes - In non-chrome scope, caught objects in exceptions are now the actual thrown object instead of an [`XPConnect`](https://web.archive.org/web/20210423135742/https://developer.mozilla.org/en-US/docs/Mozilla/Tech/XPCOM/Language_bindings/XPConnect) wrapper containing the thrown object. - SVG ID references are now live. - SVG filters now work for `foreignObject`. -- The `GetSVGDocument()` method has been added to [`object`](/en-US/docs/Web/HTML/Element/object) and [`iframe`](/en-US/docs/Web/HTML/Element/iframe) elements for compatibility. +- The `GetSVGDocument()` method has been added to [`object`](/en-US/docs/Web/HTML/Reference/Elements/object) and [`iframe`](/en-US/docs/Web/HTML/Reference/Elements/iframe) elements for compatibility. - Implicit setting of properties in object and array initializers no longer execute setters in JavaScript. - The `gDownloadLastDir.path` variable has been renamed to `gDownloadLastDir.file` since it refers to an `nsIFile`, not a path. - The `gDownloadLastDirPath` variable has been renamed to `gDownloadLastDirFile` since it refers to an `nsIFile`, not a path. diff --git a/files/en-us/mozilla/firefox/releases/3.5/security_changes/index.md b/files/en-us/mozilla/firefox/releases/3.5/security_changes/index.md index bc4136df65b27dd..f81d0db23a9a978 100644 --- a/files/en-us/mozilla/firefox/releases/3.5/security_changes/index.md +++ b/files/en-us/mozilla/firefox/releases/3.5/security_changes/index.md @@ -25,7 +25,7 @@ In previous versions of Firefox 3, SSL certificate errors resulted in the presen `about:certerror?e=error&u=url&d=desc` -Embedders needing to provide custom certificate error pages can now do so by supplying their own `about:` page implementation, and setting the `security.alternate_certificate_error_page` preference to the appropriate page name (e.g. `"certerror`"). +Embedders needing to provide custom certificate error pages can now do so by supplying their own `about:` page implementation, and setting the `security.alternate_certificate_error_page` preference to the appropriate page name (e.g., `"certerror"`). ## See also diff --git a/files/en-us/mozilla/firefox/releases/3.6/index.md b/files/en-us/mozilla/firefox/releases/3.6/index.md index eee5cf99971e5c0..a67458ca6f4d3ed 100644 --- a/files/en-us/mozilla/firefox/releases/3.6/index.md +++ b/files/en-us/mozilla/firefox/releases/3.6/index.md @@ -6,7 +6,7 @@ page-type: firefox-release-notes {{FirefoxSidebar}} -[Firefox 3.6](https://www.mozilla.org/en-US/firefox/) offers support for new and developing web standards, increased performance, and an overall better experience for web users and developers. This page provides links to articles covering the new capabilities of Firefox 3.6. +[Firefox 3.6](https://www.mozilla.org/en-US/firefox/new/) offers support for new and developing web standards, increased performance, and an overall better experience for web users and developers. This page provides links to articles covering the new capabilities of Firefox 3.6. ## For website and application developers @@ -32,7 +32,7 @@ page-type: firefox-release-notes - {{Cssxref("text-align")}}:end is now supported. [Firefox bug 299837](https://bugzil.la/299837) - DOM changes to elements using the table {{Cssxref("display")}} types now work much better. - Added {{cssxref(":-moz-locale-dir_ltr", ":-moz-locale-dir(ltr)")}} and {{cssxref(":-moz-locale-dir_rtl", ":-moz-locale-dir(rtl)")}} to make it easier to customize layouts based on whether the user interface is being displayed using a left-to-right or a right-to-left locale. [Firefox bug 478416](https://bugzil.la/478416) -- Added support for the {{cssxref(":indeterminate")}} pseudo-class, which matches `checkbox` [`input`](/en-US/docs/Web/HTML/Element/input) elements whose `indeterminate` attribute is `true`. +- Added support for the {{cssxref(":indeterminate")}} pseudo-class, which matches `checkbox` [`input`](/en-US/docs/Web/HTML/Reference/Elements/input) elements whose `indeterminate` attribute is `true`. - Windowed plugins are no longer displayed in CSS transforms, because they can't be transformed properly by the compositor. ### HTML @@ -40,13 +40,13 @@ page-type: firefox-release-notes - [Using files from web applications](/en-US/docs/Web/API/File_API/Using_files_from_web_applications) - : Support for the new HTML5 File API has been added to Gecko, making it possible for web applications to access local files selected by the user. This includes support for selecting multiple files using the `input type="file"` HTML element's new `multiple` attribute. - HTML5 video supports poster frames - - : The `poster` attribute is now supported for the [`video`](/en-US/docs/Web/HTML/Element/video) element, allowing content to specify a poster frame to be displayed until the video begins to play. + - : The `poster` attribute is now supported for the [`video`](/en-US/docs/Web/HTML/Reference/Elements/video) element, allowing content to specify a poster frame to be displayed until the video begins to play. - Checkboxes and radio buttons support the `indeterminate` property - - : HTML [`input`](/en-US/docs/Web/HTML/Element/input) elements of types `checkbox` and `radio` now support the indeterminate property, which allows a third, "indeterminate" state. + - : HTML [`input`](/en-US/docs/Web/HTML/Reference/Elements/input) elements of types `checkbox` and `radio` now support the indeterminate property, which allows a third, "indeterminate" state. - Canvas image smoothing can be controlled - - : The new [`mozImageSmoothingEnabled`](/en-US/docs/Web/API/Canvas_API/Tutorial/Using_images#controlling_image_scaling_behavior) property can be used to turn on and off image smoothing when scaling in [`canvas`](/en-US/docs/Web/HTML/Element/canvas) elements. + - : The new [`mozImageSmoothingEnabled`](/en-US/docs/Web/API/Canvas_API/Tutorial/Using_images#controlling_image_scaling_behavior) property can be used to turn on and off image smoothing when scaling in [`canvas`](/en-US/docs/Web/HTML/Reference/Elements/canvas) elements. - Asynchronous script execution - - : By setting the `async` attribute on a [`script`](/en-US/docs/Web/HTML/Element/script) element, the `script` will not block loading or display of the rest of the page. Instead the `script` executes as soon as it is downloaded. + - : By setting the `async` attribute on a [`script`](/en-US/docs/Web/HTML/Reference/Elements/script) element, the `script` will not block loading or display of the rest of the page. Instead the `script` executes as soon as it is downloaded. ### JavaScript diff --git a/files/en-us/mozilla/firefox/releases/3.6/updating_extensions/index.md b/files/en-us/mozilla/firefox/releases/3.6/updating_extensions/index.md index 453c34e43bbda05..307fc59ad0f48a8 100644 --- a/files/en-us/mozilla/firefox/releases/3.6/updating_extensions/index.md +++ b/files/en-us/mozilla/firefox/releases/3.6/updating_extensions/index.md @@ -35,7 +35,7 @@ The most probable upgrade problem is the pattern `if (elt.localName === "FOO")`. `if (elt.localName === "img" && elt.namespaceURI === "http://www.w3.org/1999/xhtml")` -#### Firefox 3.5 and 3.6, only extension-supplied text/html without foreign (e.g. SVG) script-inserted elements +#### Firefox 3.5 and 3.6, only extension-supplied text/html without foreign (e.g., SVG) script-inserted elements `if (elt.tagName === "IMG")` diff --git a/files/en-us/mozilla/firefox/releases/3/dom_improvements/index.md b/files/en-us/mozilla/firefox/releases/3/dom_improvements/index.md index a2e62b1b234c42f..f5318a369ec45ea 100644 --- a/files/en-us/mozilla/firefox/releases/3/dom_improvements/index.md +++ b/files/en-us/mozilla/firefox/releases/3/dom_improvements/index.md @@ -12,8 +12,8 @@ Firefox 3 offers a number of improvements to the [Document Object Model](/en-US/ - The [`window.fullScreen`](/en-US/docs/Web/API/Window/fullScreen) property is now always accurate no matter where it is read, even in content. Previously it would return `false` inaccurately ([Firefox bug 127013](https://bugzil.la/127013)). - The [`getClientRects`](/en-US/docs/Web/API/Element/getClientRects) and [`getBoundingClientRect`](/en-US/docs/Web/API/Element/getBoundingClientRect) DOM extensions are now supported (see [Firefox bug 174397](https://bugzil.la/174397)). - The Internet Explorer [`elementFromPoint`](/en-US/docs/Web/API/Document/elementFromPoint) DOM extension is now supported ([Firefox bug 199692](https://bugzil.la/199692)). -- The Internet Explorer [`oncut`](/en-US/docs/Web/API/HTMLElement/cut_event), [`oncopy`](/en-US/docs/Web/API/HTMLElement/copy_event), and [`onpaste`](/en-US/docs/Web/API/HTMLElement/paste_event) DOM extensions are now supported ([Firefox bug 280959](https://bugzil.la/280959)). -- Added privileged-code-only getters for `Node.nodePrincipal`, `Node.baseURIObject`, and `document.documentURIObject`. Chrome code must not touch (get or set) these properties on an unwrapped content object (e.g. on a `wrappedJSObject` of an [`XPCNativeWrapper`](/en-US/XPCNativeWrapper)), see [Firefox bug 324464](https://bugzil.la/324464) for details. +- The Internet Explorer [`oncut`](/en-US/docs/Web/API/Element/cut_event), [`oncopy`](/en-US/docs/Web/API/Element/copy_event), and [`onpaste`](/en-US/docs/Web/API/Element/paste_event) DOM extensions are now supported ([Firefox bug 280959](https://bugzil.la/280959)). +- Added privileged-code-only getters for `Node.nodePrincipal`, `Node.baseURIObject`, and `document.documentURIObject`. Chrome code must not touch (get or set) these properties on an unwrapped content object (e.g., on a `wrappedJSObject` of an [`XPCNativeWrapper`](/en-US/XPCNativeWrapper)), see [Firefox bug 324464](https://bugzil.la/324464) for details. - The Web Applications 1.0 (HTML5) [`getElementsByClassName()`](/en-US/docs/Web/API/Document/getElementsByClassName) DOM method is now supported. - The Web Applications 1.0 (HTML5) [`window.postMessage`](/en-US/docs/Web/API/Window/postMessage) DOM method is now supported. This method allows a limited, opt-in form of client-side communication between windows not necessarily on the same domain. - The `charCode` value of the `keypress` event is changed to an ASCII character if the accelerator key is pressed. Otherwise the `charCode` is the unmodified character (excepting `Shift` state). See [Gecko Keypress Event](/en-US/Gecko_Keypress_Event). diff --git a/files/en-us/mozilla/firefox/releases/3/index.md b/files/en-us/mozilla/firefox/releases/3/index.md index 5a1b56ce6f5449b..52a5a010230f024 100644 --- a/files/en-us/mozilla/firefox/releases/3/index.md +++ b/files/en-us/mozilla/firefox/releases/3/index.md @@ -22,7 +22,7 @@ If you're a developer trying to get a handle on all the new features in Firefox - : You can now draw text in a canvas using a non-standardized API supported by Firefox 3. - [Transform support for canvas](/en-US/docs/Web/API/Canvas_API/Tutorial/Transformations#transforms) - : Firefox now supports the `transform()` and `setTransform()` methods on canvases. -- [Using microformats](/en-US/docs/Web/HTML/microformats) +- [Using microformats](/en-US/docs/Web/HTML/Guides/Microformats) - : Firefox now has APIs for working with microformats. - [Drag and drop events](/en-US/docs/Web/API/HTML_Drag_and_Drop_API) - : Firefox 3 supports new events that are sent to the source node for a drag operation when the drag begins and ends. @@ -54,7 +54,7 @@ If you're a developer trying to get a handle on all the new features in Firefox - [Templates in Firefox 3](/en-US/docs/Templates_in_Firefox_3) - : Templates have been significantly improved in Firefox 3. The key improvement allows the use of custom query processors to allow data sources other than RDF to be used. - [Securing updates](/en-US/docs/Extension_Versioning,_Update_and_Compatibility#securing_updates) - - : In order to provide a more secure add-on upgrade path for users, add-ons are now required to provide a secure method for obtaining updates before they can be installed. Add-ons hosted at [AMO](https://addons.mozilla.org) automatically provide this. Any add-ons installed that do not provide a secure update method when the user upgrades to Firefox 3 will be automatically disabled. Firefox will however continue to check for updates to the extension over the insecure path and attempt to install any update offered (installation will fail if the update also fails to provide a secure update method). + - : In order to provide a more secure add-on upgrade path for users, add-ons are now required to provide a secure method for obtaining updates before they can be installed. Add-ons hosted at [AMO](https://addons.mozilla.org/) automatically provide this. Any add-ons installed that do not provide a secure update method when the user upgrades to Firefox 3 will be automatically disabled. Firefox will however continue to check for updates to the extension over the insecure path and attempt to install any update offered (installation will fail if the update also fails to provide a secure update method). - [Places migration guide](/en-US/docs/Places_Developer_Guide) - : An article about how to update an existing extension to use the Places API. - [Download Manager improvements in Firefox 3](/en-US/docs/Download_Manager_improvements_in_Firefox_3) diff --git a/files/en-us/mozilla/firefox/releases/3/svg_improvements/index.md b/files/en-us/mozilla/firefox/releases/3/svg_improvements/index.md index 722ea2a41aa4474..7b2aee02c9c3e19 100644 --- a/files/en-us/mozilla/firefox/releases/3/svg_improvements/index.md +++ b/files/en-us/mozilla/firefox/releases/3/svg_improvements/index.md @@ -8,7 +8,7 @@ page-type: guide Firefox 3 offers improved [Scalable Vector Graphics](/en-US/docs/Web/SVG) (SVG) support over prior versions of Firefox. While these features are documented elsewhere, this article serves as a convenient list so you can easily determine which features were added in Firefox 3. -- The `foreignObject` element is now supported ([Firefox bug 326966](https://bugzil.la/326966)). See the [specification](https://www.w3.org/TR/SVG11/extend.html#ForeignObjectElement) or [this article](https://robert.ocallahan.org/2006/06/future-is-now_20.html) for details. +- The `foreignObject` element is now supported ([Firefox bug 326966](https://bugzil.la/326966)). See the [specification](https://www.w3.org/TR/SVG11/extend.html#ForeignObjectElement) or [the Robert O'Callahan blog post](https://robert.ocallahan.org/2006/06/future-is-now_20.html) for details. - `pattern` element support ([spec](https://www.w3.org/TR/SVG11/pservers.html#PatternElement)) - `mask` element support ([spec](https://www.w3.org/TR/SVG11/masking.html#MaskElement)) - Support for all SVG 1.1 filters ([spec](https://www.w3.org/TR/SVG11/filters.html)): diff --git a/files/en-us/mozilla/firefox/releases/3/updating_extensions/index.md b/files/en-us/mozilla/firefox/releases/3/updating_extensions/index.md index 30eac49eed5cb1c..a2a526e28ab59ea 100644 --- a/files/en-us/mozilla/firefox/releases/3/updating_extensions/index.md +++ b/files/en-us/mozilla/firefox/releases/3/updating_extensions/index.md @@ -8,7 +8,7 @@ page-type: guide This article provides information that will be useful to developers that wish to update their extensions to work properly under Firefox 3. -Before going further, there's one helpful hint we can offer: if the only change your extension requires is a bump to the `maxVersion` field in its install manifest, and you host your extension at [addons.mozilla.org](https://addons.mozilla.org), you don't actually need to upload a new version of your extension! Use the Developer Control Panel at AMO to adjust the `maxVersion`. You can avoid having to have your extension re-reviewed this way. +Before going further, there's one helpful hint we can offer: if the only change your extension requires is a bump to the `maxVersion` field in its install manifest, and you host your extension at [addons.mozilla.org](https://addons.mozilla.org/), you don't actually need to upload a new version of your extension! Use the Developer Control Panel at AMO to adjust the `maxVersion`. You can avoid having to have your extension re-reviewed this way. ## Step 1: Update the install manifest @@ -41,7 +41,7 @@ Firefox 3 supports new properties in the install manifest to specify localized d ## Step 2: Ensure you are providing secure updates -If you are hosting addons yourself and not on a secure add-on hosting provider like [addons.mozilla.org](https://addons.mozilla.org) then you must provide a secure method of updating your add-on. This will either involve hosting your updates on an SSL website, or using cryptographic keys to sign the update information. Read [Securing Updates](/en-US/docs/Extension_Versioning,_Update_and_Compatibility#securing_updates) for more information. +If you are hosting addons yourself and not on a secure add-on hosting provider like [addons.mozilla.org](https://addons.mozilla.org/) then you must provide a secure method of updating your add-on. This will either involve hosting your updates on an SSL website, or using cryptographic keys to sign the update information. Read [Securing Updates](/en-US/docs/Extension_Versioning,_Update_and_Compatibility#securing_updates) for more information. ## Step 3: Deal with changed APIs @@ -159,7 +159,7 @@ _Add simple changes you had to make while updating your extension to work with F 1. XML PIs are now added to a XUL document's DOM. This means {{ Domxref("Node.firstChild", "document.firstChild") }} is no longer guaranteed to be the root element. If you need to get the root document in your script, use {{ Domxref("document.documentElement") }} instead. 2. `<?xml-stylesheet ?>` and `<?xul-overlay ?>` processing instructions now have no effect outside the document prolog. -- `window.addEventListener("load", myFunc, true)` is not fired when loading web content (browser page loads). This is due to [Firefox bug 296639](https://bugzil.la/296639) which changes the way inner and outer windows communicate. The simple fix here is to use `gBrowser.addEventListener("load", myFunc, true)` as described [here](/en-US/docs/Code_snippets/Tabbed_browser#detecting_page_load) and works in Firefox 2 as well. +- `window.addEventListener("load", myFunc, true)` is not fired when loading web content (browser page loads). This is due to [Firefox bug 296639](https://bugzil.la/296639) which changes the way inner and outer windows communicate. The simple fix here is to use `gBrowser.addEventListener("load", myFunc, true)` and works in Firefox 2 as well. - `content.window.getSelection()` gives an object (which can be converted to a string by `toString()`), unlike the now deprecated `content.document.getSelection()` which returns a string - `event.preventBubble()` was deprecated in Firefox 2 and has been removed in Firefox 3. Use [`event.stopPropagation()`](/en-US/docs/Web/API/Event/stopPropagation), which works in Firefox 2 as well. - Timers that are initiated using {{domxref("Window.setTimeout", "setTimeout()")}} and {{domxref("WorkerGlobalScope.setTimeout", "setTimeout()")}} are now blocked by modal windows due to the fix made for [Firefox bug 52209](https://bugzil.la/52209). You may use `nsITimer` instead. diff --git a/files/en-us/mozilla/firefox/releases/3/wai_aria_live_regions_api_support/index.md b/files/en-us/mozilla/firefox/releases/3/wai_aria_live_regions_api_support/index.md index 901f035c7d62b3a..4208963cb9456b4 100644 --- a/files/en-us/mozilla/firefox/releases/3/wai_aria_live_regions_api_support/index.md +++ b/files/en-us/mozilla/firefox/releases/3/wai_aria_live_regions_api_support/index.md @@ -7,7 +7,7 @@ page-type: guide {{FirefoxSidebar}} > [!WARNING] -> These notes are for developers of screen readers. Developers should use the [ARIA live regions developer documentation](/en-US/docs/Web/Accessibility/ARIA/ARIA_Live_Regions). +> These notes are for developers of screen readers. Developers should use the [ARIA live regions developer documentation](/en-US/docs/Web/Accessibility/ARIA/Guides/Live_regions). Firefox 3 contains important improvements to the way the Mozilla engine exposes live changes in a document. @@ -41,7 +41,7 @@ For any mutation event in a page, the author can get the following object attrib | `member-of` | If `container-atomic=true`, points to an ancestor accessible object (thus it is actually an accessible relation, not object attribute) | Not in atomic region if not provided | `aria-atomic` on ancestor element | Points to the root of the atomic container that this object is in. This will always be an ancestor of the current object. | | `event-from-input` | `"true" \| "false"` (described more below) | Browser could not calculate this | Does not require author's cooperation. | Was the root cause of this event explicit user input? | -The "container-" prefix is so named because the attribute describes what the final computed property of similar name is for that node. This means that the AT does not need to traverse up the parent chain to get this information. At this time, for properties where the `container-`_name_ attribute has not been set, the AT must have code to fall back on the default value as defined in the W3C spec. +The "container-" prefix is so named because the attribute describes what the final computed property of similar name is for that node. This means that the AT does not need to traverse up the parent chain to get this information. At this time, for properties where the `container-*` attribute has not been set, the AT must have code to fall back on the default value as defined in the W3C spec. ## Determining if event was from user input @@ -66,4 +66,4 @@ Everything else, including focus changes, timer callbacks, XMLHttpRequest callba ## What Should Screen Readers Present? -Please read the live region section of the [WAI-ARIA Screen Reader Implementor's Guide](/en-US/docs/Web/Accessibility/ARIA/ARIA_Screen_Reader_Implementors_Guide#live_regions). +Please read the live region section of the [WAI-ARIA Screen Reader Implementor's Guide](/en-US/docs/Web/Accessibility/ARIA/Guides/Screen_Reader_Implementors#live_regions). diff --git a/files/en-us/mozilla/firefox/releases/31/index.md b/files/en-us/mozilla/firefox/releases/31/index.md index 7b46228c7a5cd0b..48d688a292a71ef 100644 --- a/files/en-us/mozilla/firefox/releases/31/index.md +++ b/files/en-us/mozilla/firefox/releases/31/index.md @@ -6,6 +6,8 @@ page-type: firefox-release-notes {{FirefoxSidebar}} +Firefox 31 was released on July 22, 2014. This article lists key changes that are useful not only for web developers, but also Firefox and Gecko developers as well as add-on developers. + ## Changes for Web developers ### Developer Tools @@ -64,7 +66,7 @@ New ECMAScript 2015 features implemented: ### MathML -- Partial implementation of the [OpenType MATH table](https://mpeg.chiariglione.org/standards/mpeg-4/open-font-format/text-isoiec-cd-14496-22-3rd-edition), section 6.3.6 ([Firefox bug 407059](https://bugzil.la/407059)). For details, try the [MathML torture test](/en-US/docs/Mozilla/MathML_Project/MathML_Torture_Test). +- Partial implementation of the [OpenType MATH table](https://learn.microsoft.com/en-us/typography/opentype/spec/math), section 6.3.6 ([Firefox bug 407059](https://bugzil.la/407059)). For details, try the [MathML torture test](/en-US/docs/Mozilla/MathML_Project/MathML_Torture_Test). - The `::-moz-math-stretchy` pseudo-element has been removed ([Firefox bug 1000879](https://bugzil.la/1000879)). - When available, the Unicode Mathematical alphanumeric characters are used for bold, italic and bold-italic math variants ([Firefox bug 930504](https://bugzil.la/930504)). @@ -82,7 +84,7 @@ _No change._ ## Changes for add-on and Mozilla developers -- The "`align`" attribute on the `urlbar-wrapper` (formerly on the `urlbar-container`) which was set to "`center`" since time immemorial, has been removed. This is known to affect third-party themes. You should look carefully at what the right fix is for your theme, but for maintaining the equivalent effect, you can add the following CSS rule to your theme: +- The `align` attribute on the `urlbar-wrapper` (formerly on the `urlbar-container`) which was set to `center` since time immemorial, has been removed. This is known to affect third-party themes. You should look carefully at what the right fix is for your theme, but for maintaining the equivalent effect, you can add the following CSS rule to your theme: ```css #urlbar-wrapper { diff --git a/files/en-us/mozilla/firefox/releases/32/index.md b/files/en-us/mozilla/firefox/releases/32/index.md index 40df230100d04b7..bf6eb07316957e2 100644 --- a/files/en-us/mozilla/firefox/releases/32/index.md +++ b/files/en-us/mozilla/firefox/releases/32/index.md @@ -6,6 +6,8 @@ page-type: firefox-release-notes {{FirefoxSidebar}} +Firefox 32 was released on September 2, 2014. This article lists key changes that are useful not only for web developers, but also Firefox and Gecko developers as well as add-on developers. + ## Changes for Web developers ### Developer Tools @@ -32,8 +34,8 @@ Highlights: ### HTML -- Experimentally implemented, behind a pref, {{HTMLElement("img")}} [`srcset`](/en-US/docs/Web/HTML/Element/img#srcset) property, To activate it set `dom.image.srcset.enable` to `true` ([Firefox bug 870021](https://bugzil.la/870021)). -- [**id**](/en-US/docs/Web/HTML/Global_attributes/id) and [**class**](/en-US/docs/Web/HTML/Global_attributes/class) are now true [global attributes](/en-US/docs/Web/HTML/Global_attributes) and also apply to XML elements, in a namespace or not ([Firefox bug 741295](https://bugzil.la/741295)). +- Experimentally implemented, behind a pref, {{HTMLElement("img")}} [`srcset`](/en-US/docs/Web/HTML/Reference/Elements/img#srcset) property, To activate it set `dom.image.srcset.enable` to `true` ([Firefox bug 870021](https://bugzil.la/870021)). +- [**id**](/en-US/docs/Web/HTML/Reference/Global_attributes/id) and [**class**](/en-US/docs/Web/HTML/Reference/Global_attributes/class) are now true [global attributes](/en-US/docs/Web/HTML/Reference/Global_attributes) and also apply to XML elements, in a namespace or not ([Firefox bug 741295](https://bugzil.la/741295)). ### JavaScript @@ -74,18 +76,18 @@ _No change._ - New constraints for [WebRTC](/en-US/docs/Glossary/WebRTC)'s {{domxref("NavigatorUserMedia.getUserMedia", "getUserMedia()")}}, `width`, `height`, and `framerate`, have been added, to limit stream dimensions and frame rate ([Firefox bug 907352](https://bugzil.la/907352)): ```js - { + const constraints = { mandatory: { width: { min: 640 }, height: { min: 480 }, }, optional: [ { width: 650 }, - { width: { min: 650 }}, + { width: { min: 650 } }, { frameRate: 60 }, - { width: { max: 800 }}, - ] - } + { width: { max: 800 } }, + ], + }; ``` - WebRTC methods which previously used callback functions as input parameters are now also available using JavaScript [promises](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise). diff --git a/files/en-us/mozilla/firefox/releases/33/index.md b/files/en-us/mozilla/firefox/releases/33/index.md index 06be84c692f7119..579bc434d85a6bf 100644 --- a/files/en-us/mozilla/firefox/releases/33/index.md +++ b/files/en-us/mozilla/firefox/releases/33/index.md @@ -42,9 +42,9 @@ For details please [see the hacks post](https://hacks.mozilla.org/2014/07/event- ### HTML - Added the experimental support for {{htmlelement("picture")}} element ([Firefox bug 870022](https://bugzil.la/870022)), behind the `dom.image.picture.enabled` preference (off by default). -- The {{HTMLElement("label")}}, especially without a [`for`](/en-US/docs/Web/HTML/Element/label#for) attribute, doesn't apply anymore to a `<input type=hidden>` field ([Firefox bug 597650](https://bugzil.la/597650)). The previous behavior wasn't spec-compliant. +- The {{HTMLElement("label")}}, especially without a [`for`](/en-US/docs/Web/HTML/Reference/Elements/label#for) attribute, doesn't apply anymore to a `<input type=hidden>` field ([Firefox bug 597650](https://bugzil.la/597650)). The previous behavior wasn't spec-compliant. - The link annotation `noreferrer` has been implemented on {{HTMLElement("a")}} elements. `<a rel="noreferrer">` will not include the URL of the referrer in the HTTP request sent to fetch it ([Firefox bug 530396](https://bugzil.la/530396)). Note that this works only for in-page links, not for links clicked via the UI, like via contextual menus. -- On Android, support for two new values for the [`name`](/en-US/docs/Web/HTML/Element/meta#name) attribute of {{HTMLElement("meta")}} has been added: `msapplication-TileImage` and `msapplication-TileColor` ([Firefox bug 1014712](https://bugzil.la/1014712)). Example: +- On Android, support for two new values for the [`name`](/en-US/docs/Web/HTML/Reference/Elements/meta#name) attribute of {{HTMLElement("meta")}} has been added: `msapplication-TileImage` and `msapplication-TileColor` ([Firefox bug 1014712](https://bugzil.la/1014712)). Example: ```html <meta name="msapplication-TileImage" content="images/my-img-144.png" /> @@ -95,7 +95,7 @@ _No change._ ## Security -- The [CSP](/en-US/docs/Web/HTTP/CSP) 1.1 `frame-ancestors` [directive](/en-US/docs/Web/HTTP/Headers/Content-Security-Policy) is now supported ([Firefox bug 846978](https://bugzil.la/846978)). +- The [CSP](/en-US/docs/Web/HTTP/Guides/CSP) 1.1 `frame-ancestors` [directive](/en-US/docs/Web/HTTP/Reference/Headers/Content-Security-Policy) is now supported ([Firefox bug 846978](https://bugzil.la/846978)). ## Changes for add-on and Mozilla developers diff --git a/files/en-us/mozilla/firefox/releases/34/index.md b/files/en-us/mozilla/firefox/releases/34/index.md index fd017369f588aed..5357547b6496f82 100644 --- a/files/en-us/mozilla/firefox/releases/34/index.md +++ b/files/en-us/mozilla/firefox/releases/34/index.md @@ -46,7 +46,7 @@ _No change._ - The ES2015 syntax for [computed property names on object literals](/en-US/docs/Web/JavaScript/Reference/Operators/Object_initializer#computed_property_names) has been implemented ([Firefox bug 924688](https://bugzil.la/924688)). - - This includes [getter](/en-US/docs/Web/JavaScript/Reference/Functions/get) and [setter](/en-US/docs/Web/JavaScript/Reference/Functions/set) method names as well ([Firefox bug 1048384](https://bugzil.la/1048384)) and can also be used with [destructuring](/en-US/docs/Web/JavaScript/Reference/Operators/Destructuring_assignment#computed_object_property_names_and_destructuring). + - This includes [getter](/en-US/docs/Web/JavaScript/Reference/Functions/get) and [setter](/en-US/docs/Web/JavaScript/Reference/Functions/set) method names as well ([Firefox bug 1048384](https://bugzil.la/1048384)) and can also be used with [destructuring](/en-US/docs/Web/JavaScript/Reference/Operators/Destructuring#computed_object_property_names_and_destructuring). - The ES2015 [shorthand syntax for defining methods](/en-US/docs/Web/JavaScript/Reference/Functions/Method_definitions) on objects has been implemented ([Firefox bug 924672](https://bugzil.la/924672)). - The ES2015 `Object` method {{jsxref("Object.assign", "Object.assign()")}} has been implemented ([Firefox bug 937855](https://bugzil.la/937855)). @@ -60,8 +60,8 @@ _No change._ - The experimental {{jsxref("TypedArray.prototype.move()")}} method (only available in former Nightly and Aurora channels) has been replaced with the now implemented standard ES2015 {{jsxref("TypedArray.prototype.copyWithin()")}} method ([Firefox bug 1021379](https://bugzil.la/1021379)). - In [strict mode](/en-US/docs/Web/JavaScript/Reference/Strict_mode), setting a [duplicate property name in object literals](/en-US/docs/Web/JavaScript/Reference/Operators/Object_initializer#duplicate_property_names) will no longer throw a `SyntaxError` as per ES2015 specification ([Firefox bug 1041128](https://bugzil.la/1041128)). - In regular expressions (including `String.replace`), the matched text for a capturing group is now `undefined` instead of the empty string when that capturing group didn't get consulted because quantifiers prevented its exercise (see [Firefox bug 369778](https://bugzil.la/369778) and [this example code](/en-US/docs/Web/JavaScript/Reference/Global_Objects/RegExp#firefox-specific_notes)). Note that due to web compatibility, RegExp.$N will still return an empty string ([Firefox bug 1053944](https://bugzil.la/1053944)). -- The ES2015 [spread operator](/en-US/docs/Web/JavaScript/Reference/Operators/Spread_syntax) is now supported in [destructuring](/en-US/docs/Web/JavaScript/Reference/Operators/Destructuring_assignment) ([Firefox bug 933276](https://bugzil.la/933276)). -- [Destructuring](/en-US/docs/Web/JavaScript/Reference/Operators/Destructuring_assignment) now uses iterator protocol instead of array-like protocol ([Firefox bug 933276](https://bugzil.la/933276)). +- The ES2015 [spread operator](/en-US/docs/Web/JavaScript/Reference/Operators/Spread_syntax) is now supported in [destructuring](/en-US/docs/Web/JavaScript/Reference/Operators/Destructuring) ([Firefox bug 933276](https://bugzil.la/933276)). +- [Destructuring](/en-US/docs/Web/JavaScript/Reference/Operators/Destructuring) now uses iterator protocol instead of array-like protocol ([Firefox bug 933276](https://bugzil.la/933276)). - {{jsxref("Proxy.revocable()")}} has been implemented ([Firefox bug 978279](https://bugzil.la/978279)). ### Interfaces/APIs/DOM diff --git a/files/en-us/mozilla/firefox/releases/35/index.md b/files/en-us/mozilla/firefox/releases/35/index.md index 065b369f700cb11..632dc51d13d7a5b 100644 --- a/files/en-us/mozilla/firefox/releases/35/index.md +++ b/files/en-us/mozilla/firefox/releases/35/index.md @@ -76,7 +76,7 @@ Highlights: ### MathML -- The `dtls` OpenType feature (via the CSS {{cssxref("font-feature-settings")}} on the default stylesheet) is now applied automatically to MathML elements when positioning scripts over it (e.g. dotless i with mathematical hat). +- The `dtls` OpenType feature (via the CSS {{cssxref("font-feature-settings")}} on the default stylesheet) is now applied automatically to MathML elements when positioning scripts over it (e.g., dotless i with mathematical hat). ### SVG @@ -91,8 +91,8 @@ _No change._ - HTTP/2 has been implemented and activated, with AEAD ciphers only ([Firefox bug 1027720](https://bugzil.la/1027720) and [Firefox bug 1047594](https://bugzil.la/1047594)). - The HTTP/2 `alt-svc` header is now supported ([Firefox bug 1003448](https://bugzil.la/1003448)). - The Public Key Pinning Extension for HTTP (HPKP) has been implemented ([Firefox bug 787133](https://bugzil.la/787133)). -- The [CSP](/en-US/docs/Web/HTTP/CSP) 1.1 `base-uri` [directive](/en-US/docs/Web/HTTP/Headers/Content-Security-Policy) is now supported ([Firefox bug 1045897](https://bugzil.la/1045897)). -- Path of the source is now considered too when host-source matching happens in [CSP](/en-US/docs/Web/HTTP/CSP) ([Firefox bug 808292](https://bugzil.la/808292)). +- The [CSP](/en-US/docs/Web/HTTP/Guides/CSP) 1.1 `base-uri` [directive](/en-US/docs/Web/HTTP/Reference/Headers/Content-Security-Policy) is now supported ([Firefox bug 1045897](https://bugzil.la/1045897)). +- Path of the source is now considered too when host-source matching happens in [CSP](/en-US/docs/Web/HTTP/Guides/CSP) ([Firefox bug 808292](https://bugzil.la/808292)). ## Changes for add-on and Mozilla developers diff --git a/files/en-us/mozilla/firefox/releases/36/index.md b/files/en-us/mozilla/firefox/releases/36/index.md index 991949d74ccacef..de433fc23d69d5e 100644 --- a/files/en-us/mozilla/firefox/releases/36/index.md +++ b/files/en-us/mozilla/firefox/releases/36/index.md @@ -32,7 +32,7 @@ Highlights: - The {{cssxref("text-decoration")}} property is turned into shorthand property ([Firefox bug 1039488](https://bugzil.la/1039488)). - The properties {{cssxref("object-fit")}} and {{cssxref("object-position")}} are now supported ([Firefox bug 624647](https://bugzil.la/624647)) - The `contents` value of the {{cssxref("display")}} property has been experimentally implemented. It is preffed off by default ([Firefox bug 907396](https://bugzil.la/907396)). -- In [Quirks mode](/en-US/docs/Web/HTML/Quirks_Mode_and_Standards_Mode), the [`:active` and `:hover` quiver quirk](/en-US/docs/Mozilla_Quirks_Mode_Behavior#Miscellaneous_.26_Style) has been altered to be applied less often: it is now used only on links, only if there are no pseudo-element or other pseudo-class in the element and if it isn't part of a pseudo-class element ([Firefox bug 783213](https://bugzil.la/783213)). +- In [Quirks mode](/en-US/docs/Web/HTML/Guides/Quirks_mode_and_standards_mode), the [`:active` and `:hover` quiver quirk](/en-US/docs/Mozilla_Quirks_Mode_Behavior#Miscellaneous_.26_Style) has been altered to be applied less often: it is now used only on links, only if there are no pseudo-element or other pseudo-class in the element and if it isn't part of a pseudo-class element ([Firefox bug 783213](https://bugzil.la/783213)). - The {{cssxref("isolation")}} property has been implemented ([Firefox bug 1077872](https://bugzil.la/1077872)). - CSS {{cssxref("&lt;gradient&gt;")}} now applies on the premultiplied colors, matching the spec and other browsers, and getting rid of unexpected gray colors appearing in them ([Firefox bug 591600](https://bugzil.la/591600)). - Interpolation hint syntax has been added to {{cssxref("&lt;gradient&gt;")}} ([Firefox bug 1074056](https://bugzil.la/1074056)). @@ -40,8 +40,8 @@ Highlights: ### HTML -- Support for [`<meta name="referrer">`](/en-US/docs/Web/HTML/Element/meta) has been added ([Firefox bug 704320](https://bugzil.la/704320)). -- In Firefox, {{HTMLElement("input")}} filters specified in the [`accept`](/en-US/docs/Web/HTML/Element/input#accept) attribute will always be selected by default, unless there is an unknown value, that is an unknown mime type or badly formatted value in the [`accept`](/en-US/docs/Web/HTML/Element/input#accept) attribute. Previously specified filters were only selected by default for `image/*`, `video/*` and `audio/*` values ([Firefox bug 826185](https://bugzil.la/826185)). +- Support for [`<meta name="referrer">`](/en-US/docs/Web/HTML/Reference/Elements/meta) has been added ([Firefox bug 704320](https://bugzil.la/704320)). +- In Firefox, {{HTMLElement("input")}} filters specified in the [`accept`](/en-US/docs/Web/HTML/Reference/Elements/input#accept) attribute will always be selected by default, unless there is an unknown value, that is an unknown mime type or badly formatted value in the [`accept`](/en-US/docs/Web/HTML/Reference/Elements/input#accept) attribute. Previously specified filters were only selected by default for `image/*`, `video/*` and `audio/*` values ([Firefox bug 826185](https://bugzil.la/826185)). ### JavaScript @@ -61,7 +61,7 @@ Highlights: - The [`const`](/en-US/docs/Web/JavaScript/Reference/Statements/const) declaration is now block-scoped and requires an initializer ([Firefox bug 611388](https://bugzil.la/611388)). It also can not be redeclared anymore ([Firefox bug 1095439](https://bugzil.la/1095439)). - `{const a=1}; a;` now throws a {{jsxref("ReferenceError")}} and does not return `1` anymore due to block-scoping. - - `const a;` now throws a {{jsxref("SyntaxError")}} ("missing = in const declaration`"`): An initializer is required. + - `const a;` now throws a {{jsxref("SyntaxError")}} ("missing = in const declaration"): An initializer is required. - `const a = 1; a = 2;` now also throws a {{jsxref("SyntaxError")}} ("invalid assignment to const a"). - The ES2016 method {{jsxref("Array.prototype.includes")}} has been implemented, but for now, it is only enabled in Nightly builds ([Firefox bug 1069063](https://bugzil.la/1069063)). @@ -111,8 +111,8 @@ _No change._ - RC4 is now considered as insecure and all UI indicators will react as such; SSLv3 has been disabled by default in Firefox 34, but the UI has been changed to help the user better understand what is happening ([Firefox bug 1093595](https://bugzil.la/1093595)). - Also, RC4 is no longer offered in the initial handshake of TLS ([Firefox bug 1088915](https://bugzil.la/1088915)). -- The [`form-action`](/en-US/docs/Web/HTTP/Headers/Content-Security-Policy#form-action) directive of CSP 1.1 is now supported ([Firefox bug 529697](https://bugzil.la/529697)). -- In the preferences of Firefox, The [Do not track](/en-US/docs/Web/HTTP/Headers/DNT) selection widget is again an on/off switch ([Firefox bug 1071747](https://bugzil.la/1071747)). +- The [`form-action`](/en-US/docs/Web/HTTP/Reference/Headers/Content-Security-Policy/form-action) directive of CSP 1.1 is now supported ([Firefox bug 529697](https://bugzil.la/529697)). +- In the preferences of Firefox, The [Do not track](/en-US/docs/Web/HTTP/Reference/Headers/DNT) selection widget is again an on/off switch ([Firefox bug 1071747](https://bugzil.la/1071747)). ## Changes for add-on and Mozilla developers @@ -149,7 +149,7 @@ New constants have been added to `nsIContentPolicy` to allow Gecko internals and - `TYPE_FETCH` - : Indicates a content load request initiated by the {{domxref("Window/fetch", "fetch()")}} method. - `TYPE_IMAGESET` - - : Indicates a request to load an {{HTMLElement("img")}} (with the [`srcset`](/en-US/docs/Web/HTML/Element/img#srcset) attribute or {{HTMLElement("picture")}} element. + - : Indicates a request to load an {{HTMLElement("img")}} (with the [`srcset`](/en-US/docs/Web/HTML/Reference/Elements/img#srcset) attribute or {{HTMLElement("picture")}} element. ### XUL diff --git a/files/en-us/mozilla/firefox/releases/37/index.md b/files/en-us/mozilla/firefox/releases/37/index.md index 84e0181b33b752a..8b0b6dd97317313 100644 --- a/files/en-us/mozilla/firefox/releases/37/index.md +++ b/files/en-us/mozilla/firefox/releases/37/index.md @@ -87,7 +87,7 @@ _No change._ ## Security - The usage of weak protocols or ciphers, like SSL 3.0 and RC4, are now logged in the console, to warn sites that are using it ([Firefox bug 1092835](https://bugzil.la/1092835)). -- The [CSP](/en-US/docs/Web/HTTP/CSP) 1.1 `referrer` [directive](/en-US/docs/Web/HTTP/Headers/Content-Security-Policy) is now supported ([Firefox bug 965727](https://bugzil.la/965727)). +- The [CSP](/en-US/docs/Web/HTTP/Guides/CSP) 1.1 `referrer` [directive](/en-US/docs/Web/HTTP/Reference/Headers/Content-Security-Policy) is now supported ([Firefox bug 965727](https://bugzil.la/965727)). ## Changes for add-on and Mozilla developers diff --git a/files/en-us/mozilla/firefox/releases/38/index.md b/files/en-us/mozilla/firefox/releases/38/index.md index b7fbd05ab927630..57e88594d8a5854 100644 --- a/files/en-us/mozilla/firefox/releases/38/index.md +++ b/files/en-us/mozilla/firefox/releases/38/index.md @@ -66,9 +66,9 @@ Highlights: - Warning is shown when {{jsxref("Map")}}/{{jsxref("Set")}}/{{jsxref("WeakMap")}} constructor is called without {{jsxref("Operators/new", "new")}} ([Firefox bug 1108930](https://bugzil.la/1108930)). - The {{jsxref("WeakMap.get", "get")}}, {{jsxref("WeakMap.has", "has")}}, and {{jsxref("WeakMap.delete", "delete")}} methods of {{jsxref("WeakMap")}} objects no longer throw when the `key` parameter is not an object ([Firefox bug 1127827](https://bugzil.la/1127827)). - The optional and non-standard second `fallback` parameter for {{jsxref("WeakMap.prototype.get()")}} has been removed ([Firefox bug 1127827](https://bugzil.la/1127827)). -- When defining a [generator method](/en-US/docs/Web/JavaScript/Reference/Functions/Method_definitions), "`set`" and "`get`" are no longer invalid names ([Firefox bug 1073809](https://bugzil.la/1073809)). +- When defining a [generator method](/en-US/docs/Web/JavaScript/Reference/Functions/Method_definitions), `set` and `get` are no longer invalid names ([Firefox bug 1073809](https://bugzil.la/1073809)). - {{jsxref("RegExp.prototype.source")}} now returns "(?:)" instead of an empty string for empty regular expressions ([Firefox bug 1130798](https://bugzil.la/1130798)). -- {{jsxref("RegExp.prototype.source")}} and {{jsxref("RegExp.prototype.toString()")}} now escape regular expression patterns properly (e.g. line terminators, "\n") ([Firefox bug 1130860](https://bugzil.la/1130860)). +- {{jsxref("RegExp.prototype.source")}} and {{jsxref("RegExp.prototype.toString()")}} now escape regular expression patterns properly (e.g., line terminators, "\n") ([Firefox bug 1130860](https://bugzil.la/1130860)). - The {{jsxref("Regexp")}} {{jsxref("Regexp.global", "global")}}, {{jsxref("Regexp.ignoreCase", "ignoreCase")}}, {{jsxref("Regexp.multiline", "multiline")}}, and {{jsxref("Regexp.sticky", "sticky")}} properties are now prototype accessor properties rather than own data properties of `RegExp` instances ([Firefox bug 1120169](https://bugzil.la/1120169)). - The {{jsxref("RegExp.prototype.source")}} property is now prototype accessor property rather than own data property of `RegExp` instances ([Firefox bug 1120169](https://bugzil.la/1120169)). Available only in non-Release version, due to [Firefox bug 1150297](https://bugzil.la/1150297). - {{jsxref("Function.prototype.toString()")}} now throws for {{jsxref("Proxy")}} objects ([Firefox bug 1100936](https://bugzil.la/1100936)). @@ -107,7 +107,7 @@ _No change._ ## Security -- In Firefox, the [`autocomplete`](/en-US/docs/Web/HTML/Element/input#autocomplete)`=false` attribute is now ignored when dealing with a login form ([Firefox bug 1025703](https://bugzil.la/1025703)). This is intended to encourage the use of more secure passwords by allowing password manager tools to work more reliably. +- In Firefox, the [`autocomplete=false`](/en-US/docs/Web/HTML/Reference/Elements/input#autocomplete) attribute is now ignored when dealing with a login form ([Firefox bug 1025703](https://bugzil.la/1025703)). This is intended to encourage the use of more secure passwords by allowing password manager tools to work more reliably. - RC4 is now disabled when using TLS, except for a few specifically allowed websites. This whitelist is an interim measure until those sites are fixed ([Firefox bug 1124039](https://bugzil.la/1124039)). This fallback is controlled by the `security.tls.unrestricted_rc4_fallback` preference, `true` by default for the moment ([Firefox bug 1138882](https://bugzil.la/1138882)). - Websites needing to fall back to an insecure version of TLS in order to work are now in a hardcoded whitelist which will shrink over time ([Firefox bug 1114816](https://bugzil.la/1114816)). The whitelist can be disabled by setting `security.tls.insecure_fallback_hosts.use_static_list` to `false`. diff --git a/files/en-us/mozilla/firefox/releases/4/index.md b/files/en-us/mozilla/firefox/releases/4/index.md index d5f0170aecd01b6..64ec385611bcb37 100644 --- a/files/en-us/mozilla/firefox/releases/4/index.md +++ b/files/en-us/mozilla/firefox/releases/4/index.md @@ -16,9 +16,9 @@ Gecko now uses the [HTML5](/en-US/docs/Glossary/HTML5) parser, which fixes bugs, - [Web forms](/en-US/docs/Learn_web_development/Extensions/Forms) - : A look at improvements to web forms. Among these changes are added input types in the {{HTMLElement("input")}} element, data validation, and more. -- [HTML5 Sections](/en-US/docs/Web/HTML/Element/Heading_Elements) +- [HTML5 Sections](/en-US/docs/Web/HTML/Reference/Elements/Heading_Elements) - : Gecko now supports the new HTML5 elements related to sections in a document: {{HTMLElement("article")}}, {{HTMLElement("section")}}, {{HTMLElement("nav")}}, {{HTMLElement("aside")}}, {{HTMLElement("hgroup")}}, {{HTMLElement("header")}} and {{HTMLElement("footer")}}. -- [HTML5 hidden attribute](/en-US/docs/Web/HTML/Global_attributes/hidden) +- [HTML5 hidden attribute](/en-US/docs/Web/HTML/Reference/Global_attributes/hidden) - : This attribute, common to all elements, is used to hide content in a webpage that is not currently relevant to the user. - Other HTML5 elements - : Gecko now also supports the following new HTML5 elements: {{HTMLElement("mark")}}, {{HTMLElement("figure")}}, and {{HTMLElement("figcaption")}}. @@ -62,7 +62,7 @@ The following changes were made to the {{domxref("CanvasRenderingContext2D")}} i - : Support for touch properties is added. Details, and real article names, to come later. - [Using arbitrary elements as CSS backgrounds](/en-US/docs/Web/CSS/element) - : You can use the `-moz-element` CSS function and the {{domxref("document.mozSetImageElement()")}} DOM function to use arbitrary HTML elements as backgrounds. -- [Privacy and the :visited selector](/en-US/docs/Web/CSS/Privacy_and_the_:visited_selector) +- [Privacy and the :visited selector](/en-US/docs/Web/CSS/CSS_selectors/Privacy_and_the_visited_selector) - : Changes have been made to what information can be obtained about the style of visited links using CSS selectors. This may affect some web applications. #### New CSS properties @@ -232,7 +232,7 @@ The following changes were made to the {{domxref("CanvasRenderingContext2D")}} i - : Tips and tricks for getting the most out of graphics and video performance in Firefox 4. - [Support for WebM video](/en-US/docs/Web/Media/Guides/Formats#webm) - : The new open [WebM](https://www.webmproject.org/) video format is supported by Gecko 2.0. -- [SVG animation with SMIL](/en-US/docs/Web/SVG/SVG_animation_with_SMIL) +- [SVG animation with SMIL](/en-US/docs/Web/SVG/Guides/SVG_animation_with_SMIL) - : Support for SMIL animation of SVG is now available. - Using SVG as images and as CSS backgrounds - : You can now use SVG with the {{htmlelement("img")}} element, as well as a CSS {{cssxref("background-image")}}. @@ -284,7 +284,7 @@ Several HTML elements have had their DOM interfaces changed to the ones required - The {{domxref("Document.createElement()")}} method no longer accepts `<` and `>` around the tag name in quirks mode. - The {{domxref("Element.setCapture()")}} and {{domxref("Document.releaseCapture()")}} methods have been added, allowing elements to continue tracking mouse events even while the mouse is outside their normal tracking area after a `mousedown` event has occurred. - The `window.mozPaintCount` property has been added; it lets you determine how many times a document has been painted. This can be useful when testing performance of your web application. -- The language token has been removed from {{domxref("Navigator.appVersion")}} and {{domxref("Navigator.userAgent")}}. Use {{domxref("Navigator.language")}} or the [`Accept-Language`](/en-US/docs/Web/HTTP/Content_negotiation) header instead. [Firefox bug 572656](https://bugzil.la/572656) +- The language token has been removed from {{domxref("Navigator.appVersion")}} and {{domxref("Navigator.userAgent")}}. Use {{domxref("Navigator.language")}} or the [`Accept-Language`](/en-US/docs/Web/HTTP/Guides/Content_negotiation) header instead. [Firefox bug 572656](https://bugzil.la/572656) - The {{domxref("XMLHttpRequest")}} object now exposes the response as a JavaScript typed array as well as a string, using the Gecko-specific `mozResponseArrayBuffer` property. - [Mouse events](/en-US/docs/Web/API/MouseEvent) now include a `mozPressure` property indicating the amount of pressure on supported pressure-sensitive input devices. - The {{domxref("URL/createObjectURL_static", "URL.createObjectURL()")}} and {{domxref("URL.revokeObjectURL_static", "URL.revokeObjectURL()")}} methods let you create object URLs which reference local files. @@ -299,13 +299,13 @@ Several HTML elements have had their DOM interfaces changed to the ones required ### Security -- [Content Security Policy (CSP)](/en-US/docs/Web/HTTP/CSP) +- [Content Security Policy (CSP)](/en-US/docs/Web/HTTP/Guides/CSP) - : Content Security Policy (CSP) is a Mozilla proposal designed to help web designers and server administrators specify how content on their websites interacts. The goal is to help detect and mitigate attacks including cross-site scripting and data injection attacks. -- [HTTP Strict Transport Security](/en-US/docs/Web/HTTP/Headers/Strict-Transport-Security) +- [HTTP Strict Transport Security](/en-US/docs/Web/HTTP/Reference/Headers/Strict-Transport-Security) - : HTTP Strict Transport Security is a security feature that lets a website tell browsers that it should only be communicated with using HTTPS, instead of using HTTP. -- [The X-FRAME-OPTIONS response header](/en-US/docs/Web/HTTP/Headers/X-Frame-Options) +- [The X-FRAME-OPTIONS response header](/en-US/docs/Web/HTTP/Reference/Headers/X-Frame-Options) - : The X-FRAME-OPTIONS HTTP response header introduced in Internet Explorer 8 is now supported by Firefox. This allows sites to indicate whether or not their pages can be used in frames, and if so, whether or not to restrict that to the same origin. -- [User Agent string](/en-US/docs/Web/HTTP/Headers/User-Agent/Firefox) changes +- [User Agent string](/en-US/docs/Web/HTTP/Reference/Headers/User-Agent/Firefox) changes - : As a means to reduce the amount of data and entropy sent out in HTTP requests (see [Firefox bug 572650](https://bugzil.la/572650)), the crypto strength and language tokens have been removed from the user agent string. ### JavaScript diff --git a/files/en-us/mozilla/firefox/releases/40/index.md b/files/en-us/mozilla/firefox/releases/40/index.md index 5f2256147d6bc55..a4272c318ee58e2 100644 --- a/files/en-us/mozilla/firefox/releases/40/index.md +++ b/files/en-us/mozilla/firefox/releases/40/index.md @@ -92,7 +92,7 @@ Improvement in our experimental Web Animations implementation, mostly to match l #### DOM & HTML DOM -- When unable to parse the [`srcset`](/en-US/docs/Web/HTML/Element/img#srcset), the {{domxref("HTMLImageElement.currentSrc")}} method doesn't return `null` anymore but `""`, as requested by the latest specification ([Firefox bug 1139560](https://bugzil.la/1139560)). +- When unable to parse the [`srcset`](/en-US/docs/Web/HTML/Reference/Elements/img#srcset), the {{domxref("HTMLImageElement.currentSrc")}} method doesn't return `null` anymore but `""`, as requested by the latest specification ([Firefox bug 1139560](https://bugzil.la/1139560)). - Like for images, Firefox now throttles {{domxref("Window.requestAnimationFrame()")}} for non-visible {{HTMLElement("iframe")}} ([Firefox bug 1145439](https://bugzil.la/1145439)). - {{domxref("Navigator.taintEnabled")}} is no longer available for Web workers ([Firefox bug 1154878](https://bugzil.la/1154878)). diff --git a/files/en-us/mozilla/firefox/releases/41/index.md b/files/en-us/mozilla/firefox/releases/41/index.md index ef545d6a96c9d20..01a1125e06127e3 100644 --- a/files/en-us/mozilla/firefox/releases/41/index.md +++ b/files/en-us/mozilla/firefox/releases/41/index.md @@ -44,7 +44,7 @@ Highlights: - {{HTMLElement("a")}} without an `href` attribute is no longer classified as interactive content. Clicking it inside {{HTMLElement("label")}} will activate labelled content ([Firefox bug 1167816](https://bugzil.la/1167816)). - SVG icons are now supported for site icons, that is favicons and shortcut icons ([Firefox bug 366324](https://bugzil.la/366324)). -- The [`crossorigin`](/en-US/docs/Web/HTML/Element/link#crossorigin) attribute is now supported for [\<link rel='preconnect'>](/en-US/docs/Web/HTML/Element/link) ([Firefox bug 1174152](https://bugzil.la/1174152)). +- The [`crossorigin`](/en-US/docs/Web/HTML/Reference/Elements/link#crossorigin) attribute is now supported for [\<link rel='preconnect'>](/en-US/docs/Web/HTML/Reference/Elements/link) ([Firefox bug 1174152](https://bugzil.la/1174152)). - The picture element does not react to resize/viewport changes ([Firefox bug 1135812](https://bugzil.la/1135812)). ### JavaScript @@ -57,7 +57,7 @@ Highlights: - {{jsxref("Functions/Default_parameters", "Destructured parameters with default value assignment", "#Destructured_parameter_with_default_value_assignment", 1)}} are now supported ([Firefox bug 1018628](https://bugzil.la/1018628)). - Per ES2015, curly braces are required for [method definitions](/en-US/docs/Web/JavaScript/Reference/Functions/Method_definitions). Syntax without them will fail from now on ([Firefox bug 1150855](https://bugzil.la/1150855)). - [Method definitions](/en-US/docs/Web/JavaScript/Reference/Functions/Method_definitions) (except for generator methods) are not constructable anymore ([Firefox bug 1059908](https://bugzil.la/1059908) and [Firefox bug 1166950](https://bugzil.la/1166950)). -- As part of ES2015 specification compliance, parenthesized [destructuring](/en-US/docs/Web/JavaScript/Reference/Operators/Destructuring_assignment) patterns, like `([a, b]) = [1, 2]` or `({a, b}) = { a: 1, b: 2 }`, are now considered invalid and will throw a {{jsxref("SyntaxError")}}. See [Jeff Walden's blog post](https://whereswalden.com/2015/06/20/new-changes-to-make-spidermonkeys-and-firefoxs-parsing-of-destructuring-patterns-more-spec-compliant/) for more details. +- As part of ES2015 specification compliance, parenthesized [destructuring](/en-US/docs/Web/JavaScript/Reference/Operators/Destructuring) patterns, like `([a, b]) = [1, 2]` or `({a, b}) = { a: 1, b: 2 }`, are now considered invalid and will throw a {{jsxref("SyntaxError")}}. See [Jeff Walden's blog post](https://whereswalden.com/2015/06/20/new-changes-to-make-spidermonkeys-and-firefoxs-parsing-of-destructuring-patterns-more-spec-compliant/) for more details. - The [`new.target`](/en-US/docs/Web/JavaScript/Reference/Operators/new.target) syntax has been added ([Firefox bug 1141865](https://bugzil.la/1141865)). ### Interfaces/APIs/DOM @@ -138,8 +138,8 @@ Mathematical formulas require special fonts. So far, these fonts were hard-coded ## Security -- The [CSP](/en-US/docs/Web/HTTP/CSP) 1.1 `manifest-src` [directive](/en-US/docs/Web/HTTP/Headers/Content-Security-Policy) is now supported ([Firefox bug 1089255](https://bugzil.la/1089255)). -- Previous versions of Firefox incorrectly expected the [Content Security Policy](/en-US/docs/Web/HTTP/CSP) [referrer](/en-US/docs/Web/HTTP/Headers/Content-Security-Policy#referrer) directive's value `origin-when-cross-origin` to be spelled `origin-when-crossorigin`. This has been corrected to include the missing dash character. +- The [CSP](/en-US/docs/Web/HTTP/Guides/CSP) 1.1 `manifest-src` [directive](/en-US/docs/Web/HTTP/Reference/Headers/Content-Security-Policy) is now supported ([Firefox bug 1089255](https://bugzil.la/1089255)). +- Previous versions of Firefox incorrectly expected the [Content Security Policy](/en-US/docs/Web/HTTP/Guides/CSP) [referrer](/en-US/docs/Web/HTTP/Reference/Headers/Content-Security-Policy#referrer) directive's value `origin-when-cross-origin` to be spelled `origin-when-crossorigin`. This has been corrected to include the missing dash character. ## Changes for add-on and Mozilla developers diff --git a/files/en-us/mozilla/firefox/releases/42/index.md b/files/en-us/mozilla/firefox/releases/42/index.md index 617f7b7b5b0a123..97ad2ef62edb23a 100644 --- a/files/en-us/mozilla/firefox/releases/42/index.md +++ b/files/en-us/mozilla/firefox/releases/42/index.md @@ -30,7 +30,7 @@ Highlights: ### HTML -- Experimental support for the [`referrer`](/en-US/docs/Web/HTML/Element/input#referrer) attribute of the {{HTMLElement("img")}} ([Firefox bug 1166910](https://bugzil.la/1166910)), {{htmlElement("iframe")}} ([Firefox bug 1175736](https://bugzil.la/1175736)), {{HTMLElement("a")}} and {{HTMLElement("area")}} ([Firefox bug 1174913](https://bugzil.la/1174913)) has been added. There is no effect by default, the `network.http.enablePerElementReferrer` being `false` by default. +- Experimental support for the [`referrer`](/en-US/docs/Web/HTML/Reference/Elements/input#referrer) attribute of the {{HTMLElement("img")}} ([Firefox bug 1166910](https://bugzil.la/1166910)), {{htmlElement("iframe")}} ([Firefox bug 1175736](https://bugzil.la/1175736)), {{HTMLElement("a")}} and {{HTMLElement("area")}} ([Firefox bug 1174913](https://bugzil.la/1174913)) has been added. There is no effect by default, the `network.http.enablePerElementReferrer` being `false` by default. ### JavaScript @@ -42,7 +42,7 @@ Highlights: #### DOM & HTML DOM -- Images with an [`id`](/en-US/docs/Web/HTML/Element/img#id) are no more listed as property of the {{domxref("Window")}} interface: `<img id="login">` isn't accessible as `window.login` anymore. This behavior was introduced in Firefox 26 and has been removed to match a later change in the spec. ([Firefox bug 959992](https://bugzil.la/959992)) +- Images with an [`id`](/en-US/docs/Web/HTML/Reference/Elements/img#id) are no more listed as property of the {{domxref("Window")}} interface: `<img id="login">` isn't accessible as `window.login` anymore. This behavior was introduced in Firefox 26 and has been removed to match a later change in the spec. ([Firefox bug 959992](https://bugzil.la/959992)) - {{domxref('MouseEvent.offsetX')}} and {{domxref('MouseEvent.offsetY')}} have been added ([Firefox bug 69787](https://bugzil.la/69787)). - The {{domxref("HTMLInputElement")}} interface has been experimentally extended to handle the upload of directories ([Firefox bug 1164310](https://bugzil.la/1164310)). These four members can be exposed by setting the `dom.input.dirpicker` preference to `true`: @@ -119,7 +119,7 @@ _No change._ ## Networking -- The CSP [`upgrade-insecure-requests`](/en-US/docs/Web/HTTP/Headers/Content-Security-Policy#upgrade-insecure-requests) directive has been implemented ([Firefox bug 1139297](https://bugzil.la/1139297)). +- The CSP [`upgrade-insecure-requests`](/en-US/docs/Web/HTTP/Reference/Headers/Content-Security-Policy/upgrade-insecure-requests) directive has been implemented ([Firefox bug 1139297](https://bugzil.la/1139297)). ## Security diff --git a/files/en-us/mozilla/firefox/releases/43/index.md b/files/en-us/mozilla/firefox/releases/43/index.md index 09c4a69c8403844..be4d5d0f68da7b5 100644 --- a/files/en-us/mozilla/firefox/releases/43/index.md +++ b/files/en-us/mozilla/firefox/releases/43/index.md @@ -46,7 +46,7 @@ Highlights: - To match the ES2015 specification, [arrow functions](/en-US/docs/Web/JavaScript/Reference/Functions/Arrow_functions) no longer have their own [`arguments`](/en-US/docs/Web/JavaScript/Reference/Functions/arguments) object. The `arguments` object is now lexically bound (inherited from the outer function). In most cases, [rest parameters](/en-US/docs/Web/JavaScript/Reference/Functions/rest_parameters) are a good alternative `(...args) => args[i]`, see [Firefox bug 889158](https://bugzil.la/889158). - The [arguments](/en-US/docs/Web/JavaScript/Reference/Functions/arguments) object is now allowed in conjunction with [rest parameters](/en-US/docs/Web/JavaScript/Reference/Functions/rest_parameters) ([Firefox bug 1133298](https://bugzil.la/1133298)). -- From now on, a mapped [`arguments`](/en-US/docs/Web/JavaScript/Reference/Functions/arguments) object in non-strict functions is only provided if the function does **not** contain any [rest parameters](/en-US/docs/Web/JavaScript/Reference/Functions/rest_parameters), any [default parameters](/en-US/docs/Web/JavaScript/Reference/Functions/Default_parameters) or any [destructured parameters](/en-US/docs/Web/JavaScript/Reference/Operators/Destructuring_assignment) ([Firefox bug 1175394](https://bugzil.la/1175394)). +- From now on, a mapped [`arguments`](/en-US/docs/Web/JavaScript/Reference/Functions/arguments) object in non-strict functions is only provided if the function does **not** contain any [rest parameters](/en-US/docs/Web/JavaScript/Reference/Functions/rest_parameters), any [default parameters](/en-US/docs/Web/JavaScript/Reference/Functions/Default_parameters) or any [destructured parameters](/en-US/docs/Web/JavaScript/Reference/Operators/Destructuring) ([Firefox bug 1175394](https://bugzil.la/1175394)). #### Other changes @@ -108,7 +108,7 @@ _No change._ ## Security -- Access to Web Storage (i.e. `localStorage` and `sessionStorage`) from third-party IFrames is now denied if the user has [disabled third-party cookies](https://support.mozilla.org/en-US/kb/third-party-cookies-firefox-tracking-protection) ([Firefox bug 536509](https://bugzil.la/536509)). +- Access to Web Storage (i.e., `localStorage` and `sessionStorage`) from third-party IFrames is now denied if the user has [disabled third-party cookies](https://support.mozilla.org/en-US/kb/third-party-cookies-firefox-tracking-protection) ([Firefox bug 536509](https://bugzil.la/536509)). - This whitelist has even been removed in Nightly and Aurora/Dev Edition of the browser ([Firefox bug 1201023](https://bugzil.la/1201023)). It is currently scheduled that this removal will also happen for Beta and Release versions for the next version (Firefox 44). - Subresource integrity has been implemented for {{htmlelement("script")}} and {{htmlelement("link")}} that links to stylesheets ([Firefox bug 992096](https://bugzil.la/992096)). diff --git a/files/en-us/mozilla/firefox/releases/44/index.md b/files/en-us/mozilla/firefox/releases/44/index.md index 3290d4d86db90c9..914835ced571cd9 100644 --- a/files/en-us/mozilla/firefox/releases/44/index.md +++ b/files/en-us/mozilla/firefox/releases/44/index.md @@ -23,7 +23,7 @@ Highlights: ### HTML -- [`<link rel="prefetch">`](/en-US/docs/Glossary/Prefetch) now obeys the [`crossorigin`](/en-US/docs/Web/HTML/Element/link#crossorigin) attribute ([Firefox bug 1214819](https://bugzil.la/1214819)). +- [`<link rel="prefetch">`](/en-US/docs/Glossary/Prefetch) now obeys the [`crossorigin`](/en-US/docs/Web/HTML/Reference/Elements/link#crossorigin) attribute ([Firefox bug 1214819](https://bugzil.la/1214819)). ### CSS @@ -150,7 +150,7 @@ Highlights: - `mozRTCSessionDescription` is now {{domxref("RTCSessionDescription")}}. - The {{domxref("RTCDataChannel.bufferedAmountLowThreshold")}} property, as well as the {{domxref("RTCDataChannel.bufferedamountlow_event", "bufferedamountlow")}} event and its event handler, have been implemented ([Firefox bug 1178091](https://bugzil.la/1178091)). -- The attribute {{domxref("RTCPeerConnection.canTrickleIceCandidates")}} has been added, the non-standard method `RTCPeerConnection.updateIce()`} removed ([Firefox bug 1209744](https://bugzil.la/1209744)). +- The attribute {{domxref("RTCPeerConnection.canTrickleIceCandidates")}} has been added, the non-standard method `RTCPeerConnection.updateIce()` removed ([Firefox bug 1209744](https://bugzil.la/1209744)). - The {{domxref("MediaStream")}} interface now supports the {{domxref("MediaStream.addTrack()")}} and {{domxref("MediaStream.removeTrack()")}} methods ([Firefox bug 1103188](https://bugzil.la/1103188)). - The constructor {{domxref("MediaStream.MediaStream", "MediaStream()")}} has been implemented ([Firefox bug 1070216](https://bugzil.la/1070216)). - Support for the non-standard constraint style option list for `RTCOfferOptions` has been removed. @@ -183,7 +183,7 @@ _No change._ ## HTTP -- Support for the [Brotli](https://en.wikipedia.org/wiki/Brotli) algorithm has been added and both [`Accept-Encoding`](/en-US/docs/Web/HTTP/Content_negotiation#the_accept-encoding_header) and [`Content-Encoding`](/en-US/docs/Web/HTTP/Headers/Content-Encoding) headers now support the `br` value ([Firefox bug 366559](https://bugzil.la/366559) and [Firefox bug 1211916](https://bugzil.la/1211916)). +- Support for the [Brotli](https://en.wikipedia.org/wiki/Brotli) algorithm has been added and both [`Accept-Encoding`](/en-US/docs/Web/HTTP/Guides/Content_negotiation#the_accept-encoding_header) and [`Content-Encoding`](/en-US/docs/Web/HTTP/Reference/Headers/Content-Encoding) headers now support the `br` value ([Firefox bug 366559](https://bugzil.la/366559) and [Firefox bug 1211916](https://bugzil.la/1211916)). - Incorrect support of HTTP/2 headers containing line breaks (`'/n'`) have been removed as the spec doesn't allow it, unlike HTTP/1 ([Firefox bug 1197847](https://bugzil.la/1197847)). ## Networking @@ -215,7 +215,7 @@ _No change._ ### Other -- Due to breaking changes in Firefox 44 ([bug 1202902](https://bugzil.la/1202902)), add-ons packed with [cfx](/en-US/docs/Mozilla/Add-ons/SDK/Tools/cfx) will not work any longer. To make your add-on compatible again, please use [jpm](/en-US/docs/Mozilla/Add-ons/SDK/Tools/jpm). You can find steps to migrate from _cfx_ to _jpm_ [here](/en-US/docs/Mozilla/Add-ons/SDK/Tools/cfx_to_jpm). +- Due to breaking changes in Firefox 44 ([bug 1202902](https://bugzil.la/1202902)), add-ons packed with [cfx](/en-US/docs/Mozilla/Add-ons/SDK/Tools/cfx) will not work any longer. To make your add-on compatible again, please use [jpm](/en-US/docs/Mozilla/Add-ons/SDK/Tools/jpm). See the [_cfx_ to _jpm_ migration guide](/en-US/docs/Mozilla/Add-ons/SDK/Tools/cfx_to_jpm). ## Older versions diff --git a/files/en-us/mozilla/firefox/releases/46/index.md b/files/en-us/mozilla/firefox/releases/46/index.md index fd469203dd7ace3..9a19bba1ceb61a7 100644 --- a/files/en-us/mozilla/firefox/releases/46/index.md +++ b/files/en-us/mozilla/firefox/releases/46/index.md @@ -59,9 +59,9 @@ Highlights: #### DOM & HTML DOM -- The deprecated {{domxref("Window.showModalDialog()")}} method is no more available when Firefox runs in multi-process mode (e10s) ([Firefox bug 1234700](https://bugzil.la/1234700)). +- The deprecated `Window.showModalDialog()` method is no more available when Firefox runs in multi-process mode (e10s) ([Firefox bug 1234700](https://bugzil.la/1234700)). - Added support for {{domxref("Document.elementsFromPoint()")}} ([Firefox bug 1164427](https://bugzil.la/1164427)). -- When a non-existent option of a {{HTMLElement("select")}} element is programmatically selected, instead of being incorrectly left unchanged, the [`selectedIndex`](/en-US/docs/Web/HTML/Element/select#selectedindex) value is now set to `-1`, the [`selectedOptions`](/en-US/docs/Web/HTML/Element/select#selectedoptions) to an empty {{domxref("HTMLCollection")}}, and [`value`](/en-US/docs/Web/HTML/Element/select#value) to an empty string ([Firefox bug 1203668](https://bugzil.la/1203668)). +- When a non-existent option of a {{HTMLElement("select")}} element is programmatically selected, instead of being incorrectly left unchanged, the [`selectedIndex`](/en-US/docs/Web/HTML/Reference/Elements/select#selectedindex) value is now set to `-1`, the [`selectedOptions`](/en-US/docs/Web/HTML/Reference/Elements/select#selectedoptions) to an empty {{domxref("HTMLCollection")}}, and [`value`](/en-US/docs/Web/HTML/Reference/Elements/select#value) to an empty string ([Firefox bug 1203668](https://bugzil.la/1203668)). #### Canvas diff --git a/files/en-us/mozilla/firefox/releases/47/index.md b/files/en-us/mozilla/firefox/releases/47/index.md index cf7e44f4a7d5ba8..e42794d70206eea 100644 --- a/files/en-us/mozilla/firefox/releases/47/index.md +++ b/files/en-us/mozilla/firefox/releases/47/index.md @@ -12,7 +12,7 @@ page-type: firefox-release-notes ### Developer Tools -- [User-agent spoofing](/en-US/docs/Web/HTTP/Browser_detection_using_the_user_agent) from the [Responsive mode](https://firefox-source-docs.mozilla.org/devtools-user/responsive_design_mode/index.html) +- [User-agent spoofing](/en-US/docs/Web/HTTP/Guides/Browser_detection_using_the_user_agent) from the [Responsive mode](https://firefox-source-docs.mozilla.org/devtools-user/responsive_design_mode/index.html) - [Retaining paths panel](https://firefox-source-docs.mozilla.org/devtools-user/memory/dominators_view/index.html#retaining-paths-panel) in memory tool - [Service workers](/en-US/docs/Web/API/ServiceWorker) and [Push API](/en-US/docs/Web/API/Push_API) debugging @@ -51,7 +51,7 @@ _No change._ - The new ES2017 {{jsxref("Object.values()")}} and {{jsxref("Object.entries()")}} methods have been implemented ([Firefox bug 1232639](https://bugzil.la/1232639)). - The deprecated, old Proxy API (`Proxy.create` and `Proxy.createFunction`) now presents a deprecation warning in the console and will be removed in a future version. Use the standard {{jsxref("Proxy")}} object instead ([Firefox bug 892903](https://bugzil.la/892903)). -- Support for the deprecated non-standard `flags` argument of `String.prototype.`{{jsxref("String.prototype.match", "match")}}/{{jsxref("String.prototype.search", "search")}}/{{jsxref("String.prototype.replace", "replace")}} has been dropped in non-release builds ([Firefox bug 1245801](https://bugzil.la/1245801)). +- Support for the deprecated non-standard `flags` argument of {{jsxref("String.prototype.match")}}/{{jsxref("String.prototype.search", "search")}}/{{jsxref("String.prototype.replace", "replace")}} has been dropped in non-release builds ([Firefox bug 1245801](https://bugzil.la/1245801)). - As per the new ES2016 specification, the {{jsxref("Proxy")}} enumerate trap for [`for...in`](/en-US/docs/Web/JavaScript/Reference/Statements/for...in) statements has been removed ([Firefox bug 1246318](https://bugzil.la/1246318)). - The {{jsxref("Array.prototype.indexOf()")}} and {{jsxref("Array.prototype.lastIndexOf()")}} methods (and their {{jsxref("TypedArray")}} equivalents) have been updated to never return `-0` as per the ECMAScript specification ([Firefox bug 1242043](https://bugzil.la/1242043)). diff --git a/files/en-us/mozilla/firefox/releases/48/index.md b/files/en-us/mozilla/firefox/releases/48/index.md index 74a5b83c6ab3f7e..bab957dd931f478 100644 --- a/files/en-us/mozilla/firefox/releases/48/index.md +++ b/files/en-us/mozilla/firefox/releases/48/index.md @@ -19,7 +19,7 @@ page-type: firefox-release-notes - Added the [DOM Inspector](https://firefox-source-docs.mozilla.org/devtools-user/dom_property_viewer/index.html) ([Firefox bug 1201475](https://bugzil.la/1201475)). - [Font inspector](https://firefox-source-docs.mozilla.org/devtools-user/page_inspector/ui_tour/index.html#fonts-view) has been enabled by default again ([Firefox bug 1280121](https://bugzil.la/1280121)). - [Improved suggestions](https://firefox-source-docs.mozilla.org/devtools-user/page_inspector/how_to/examine_and_edit_css/index.html#edit-rules) for CSS properties ([Firefox bug 1168246](https://bugzil.la/1168246)). -- Cookies, localstorage and sessionstorage entries are editable via double-click ([Firefox bug 1231154](https://bugzil.la/1231154), [Firefox bug 1231179](https://bugzil.la/1231179), [Firefox bug 1231155](https://bugzil.la/1231155)). +- Cookies, localStorage and sessionStorage entries are editable via double-click ([Firefox bug 1231154](https://bugzil.la/1231154), [Firefox bug 1231179](https://bugzil.la/1231179), [Firefox bug 1231155](https://bugzil.la/1231155)). ### HTML @@ -28,7 +28,7 @@ page-type: firefox-release-notes - The default style for these elements has been adapted to match the spec ([Firefox bug 1258657](https://bugzil.la/1258657)). - The `toggle` event is now sent to the {{HTMLElement("details")}} element when this one is opened or closed ([Firefox bug 1225412](https://bugzil.la/1225412)). -- The [`meta`](/en-US/docs/Web/HTML/Element/meta) attributes now also supports the `no-referrer-when-downgrade` and `origin-when-cross-origin` values ([Firefox bug 1178337](https://bugzil.la/1178337)). +- The [`meta`](/en-US/docs/Web/HTML/Reference/Elements/meta) attributes now also supports the `no-referrer-when-downgrade` and `origin-when-cross-origin` values ([Firefox bug 1178337](https://bugzil.la/1178337)). ### CSS @@ -119,7 +119,7 @@ page-type: firefox-release-notes - Support for UTF-16 has been removed from {{domxref("TextEncoder")}} ([Firefox bug 1257877](https://bugzil.la/1257877)). - {{domxref("RTCStatsReport")}} is now a true `maplike` interface: in addition to {{domxref("RTCStatsReport.forEach()", "forEach()")}}, {{domxref("RTCStatsReport.get()", "get()")}}, and {{domxref("RTCStatsReport.has()", "has()")}}, the methods {{domxref("RTCStatsReport.entries", "entries()")}}, {{domxref("RTCStatsReport.values", "values()")}}, {{domxref("RTCStatsReport.keys()", "keys()")}}, as well as the {{domxref("RTCStatsReport.size", "size")}} getter have been implemented ([Firefox bug 906986](https://bugzil.la/906986)). - The {{domxref("Request.cache")}} property has been added allowing to control the cache behavior ([Firefox bug 1120715](https://bugzil.la/1120715)). -- Handling of dead keys on Mac OS X has been changed to work the same as other platforms; they no longer fire a {{domxref("Element/keypress_event", "keypress")}} event when no text is generated when the focused element isn't editable (when the focused element is editable, dead key causes composition events instead of keyboard events on Mac OS X). Also, like on other platforms, the value of {{domxref("KeyboardEvent.key")}} is now `"Dead"` for dead keypresses which don't generate text in other situations. +- Handling of dead keys on Mac OS X has been changed to work the same as other platforms; they no longer fire a {{domxref("Element/keypress_event", "keypress")}} event when no text is generated when the focused element isn't editable (when the focused element is editable, dead key causes composition events instead of keyboard events on Mac OS X). Also, like on other platforms, the value of {{domxref("KeyboardEvent.key")}} is now `"Dead"` for dead key presses which don't generate text in other situations. ## HTTP diff --git a/files/en-us/mozilla/firefox/releases/49/index.md b/files/en-us/mozilla/firefox/releases/49/index.md index 62159ebfed02359..4ce6f15a588633b 100644 --- a/files/en-us/mozilla/firefox/releases/49/index.md +++ b/files/en-us/mozilla/firefox/releases/49/index.md @@ -34,12 +34,12 @@ page-type: firefox-release-notes ### HTML - Added support for the {{HTMLElement("details")}} and {{HTMLElement("summary")}} elements ([Firefox bug 1226455](https://bugzil.la/1226455)). -- The [`pattern`](/en-US/docs/Web/HTML/Element/input#pattern) attribute of the {{HTMLElement("input")}} element now uses the `'u'` parameter in the underlying JavaScript {{jsxref("RegExp")}} ([Firefox bug 1227906](https://bugzil.la/1227906)). -- To match a spec change, an invalid value of the [`kind`](/en-US/docs/Web/HTML/Element/track#kind) attribute of the {{HTMLElement('track')}} element is now treated like `"metadata"` instead of `"subtitles"` ([Firefox bug 1269712](https://bugzil.la/1269712)). -- The {{HTMLElement("iframe")}} element's [`sandbox`](/en-US/docs/Web/HTML/Element/iframe#sandbox) attribute now supports the `'allow-popups-to-escape-sandbox'` and `'allow-modals'` values ([Firefox bug 1190641](https://bugzil.la/1190641)). +- The [`pattern`](/en-US/docs/Web/HTML/Reference/Elements/input#pattern) attribute of the {{HTMLElement("input")}} element now uses the `'u'` parameter in the underlying JavaScript {{jsxref("RegExp")}} ([Firefox bug 1227906](https://bugzil.la/1227906)). +- To match a spec change, an invalid value of the [`kind`](/en-US/docs/Web/HTML/Reference/Elements/track#kind) attribute of the {{HTMLElement('track')}} element is now treated like `"metadata"` instead of `"subtitles"` ([Firefox bug 1269712](https://bugzil.la/1269712)). +- The {{HTMLElement("iframe")}} element's [`sandbox`](/en-US/docs/Web/HTML/Reference/Elements/iframe#sandbox) attribute now supports the `'allow-popups-to-escape-sandbox'` and `'allow-modals'` values ([Firefox bug 1190641](https://bugzil.la/1190641)). - Support for microdata attributes and the Microdata API have been removed ([Firefox bug 909633](https://bugzil.la/909633)). -- The [`referrerpolicy`](/en-US/docs/Web/HTML/Element/a#referrerpolicy) attribute on the {{HTMLElement("a")}} element now supports the `'no-referrer-when-downgrade`' and `'origin-when-cross-origin'` ([Firefox bug 1178337](https://bugzil.la/1178337)). -- The [`form`](/en-US/docs/Web/HTML/Element/label#form) content attribute of the {{HTMLElement("label")}} element has been removed. The {{domxref("HTMLLabelElement.form")}} property still exists, but now returns the form with which the label's control is associated, if there is a control (and if that control is associated with a form) ([Firefox bug 1268852](https://bugzil.la/1268852)). +- The [`referrerpolicy`](/en-US/docs/Web/HTML/Reference/Elements/a#referrerpolicy) attribute on the {{HTMLElement("a")}} element now supports the `'no-referrer-when-downgrade'` and `'origin-when-cross-origin'` ([Firefox bug 1178337](https://bugzil.la/1178337)). +- The [`form`](/en-US/docs/Web/HTML/Reference/Elements/label#form) content attribute of the {{HTMLElement("label")}} element has been removed. The {{domxref("HTMLLabelElement.form")}} property still exists, but now returns the form with which the label's control is associated, if there is a control (and if that control is associated with a form) ([Firefox bug 1268852](https://bugzil.la/1268852)). ### CSS @@ -55,7 +55,7 @@ page-type: firefox-release-notes - Our experimental [CSS Grids](/en-US/docs/Web/CSS/CSS_grid_layout) implementation has been improved: - Implemented {{cssxref("&lt;percentage&gt;")}} for the `grid-gap`, `grid-row-gap`, and `grid-column-gap` properties ([Firefox bug 1266268](https://bugzil.la/1266268)). - - Implemented grid layout support for {{cssxref("align")}}, {{cssxref("justify-self")}}`:baseline` and `last-baseline` (aka "baseline self-alignment") ([Firefox bug 1221525](https://bugzil.la/1221525)). + - Implemented grid layout support for {{cssxref("align-self")}}, {{cssxref("justify-self")}} values `baseline` and `last-baseline` (aka "baseline self-alignment") ([Firefox bug 1221525](https://bugzil.la/1221525)). - Implemented grid item baseline content alignment ([Firefox bug 1256429](https://bugzil.la/1256429)). - Our experimental [CSS Masks](/en-US/docs/Web/CSS/CSS_masking) implementation has been improved: @@ -70,7 +70,7 @@ page-type: firefox-release-notes - The ES2015 {{jsxref("Global_Objects/Proxy/Proxy/getPrototypeOf", "getPrototypeOf()")}} and {{jsxref("Global_Objects/Proxy/Proxy/setPrototypeOf", "setPrototypeOf()")}} {{jsxref("Proxy")}} traps have been implemented ([Firefox bug 888969](https://bugzil.la/888969)). - The ES2015 [`RegExp.prototype[Symbol.match]()`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/RegExp/Symbol.match), [`RegExp.prototype[Symbol.replace]()`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/RegExp/Symbol.replace), [`RegExp.prototype[Symbol.search]()`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/RegExp/Symbol.search), and [`RegExp.prototype[Symbol.split]()`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/RegExp/Symbol.split) methods, and [`RegExp[Symbol.species]`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/RegExp/Symbol.species) getter have been implemented ([Firefox bug 887016](https://bugzil.la/887016)). -- The deprecated, non-standard `flags` argument of `String.prototype.`{{jsxref("String.prototype.match", "match")}}/{{jsxref("String.prototype.search", "search")}}/{{jsxref("String.prototype.replace", "replace")}} has been removed ([Firefox bug 1108382](https://bugzil.la/1108382)). +- The deprecated, non-standard `flags` argument of {{jsxref("String.prototype.match")}}/{{jsxref("String.prototype.search", "search")}}/{{jsxref("String.prototype.replace", "replace")}} has been removed ([Firefox bug 1108382](https://bugzil.la/1108382)). - The behavior of the {{jsxref("Date.parse()")}} method when parsing 2-digit years has been changed to be more interoperable with the Google Chrome browser ([Firefox bug 1265136](https://bugzil.la/1265136)). ### Interfaces/APIs/DOM @@ -89,7 +89,7 @@ page-type: firefox-release-notes - Added the _experimental_ and _non-standard_ {{domxref("HTMLMediaElement.seekToNextFrame()")}} method, which allows seeking frame-by-frame through video content ([Firefox bug 1235301](https://bugzil.la/1235301)). While you're encouraged to experiment with this method to help us understand how useful it is, _do not use it in production code!_ - The {{domxref("HTMLLabelElement.form")}} property now returns the form with which the label's control is associated, if there is a control (and if that control is associated with a form). Previously, labels were directly associated with forms using this property ([Firefox bug 1268852](https://bugzil.la/1268852)). - Support for the third parameter of {{domxref("EventTarget.addEventListener()")}}, either a {{jsxref("Boolean")}} or an `EventListenerOptions` has been added ([Firefox bug 1266164](https://bugzil.la/1266164) and [Firefox bug 1266066](https://bugzil.la/1266066)). -- The audio volume related values for {{domxref("KeyboardEvent.key")}} have been renamed. `"VolumeDown"` is now `"AudioVolumeDown"`, `"VolumeUp"` is now `"AudioVolumeUp"`, and `"VolumeMute"` is now `"AudioVolumeMute".` This brings Firefox into alignment with the latest draft of the UI Events specification ([Firefox bug 1272578](https://bugzil.la/1272578)). See [Code values for keyboard events](/en-US/docs/Web/API/UI_Events/Keyboard_event_code_values) for a full list of available key codes. +- The audio volume related values for {{domxref("KeyboardEvent.key")}} have been renamed. `"VolumeDown"` is now `"AudioVolumeDown"`, `"VolumeUp"` is now `"AudioVolumeUp"`, and `"VolumeMute"` is now `"AudioVolumeMute"`. This brings Firefox into alignment with the latest draft of the UI Events specification ([Firefox bug 1272578](https://bugzil.la/1272578)). See [Code values for keyboard events](/en-US/docs/Web/API/UI_Events/Keyboard_event_code_values) for a full list of available key codes. - The keys previously referred to as `"MozHomeScreen"`, `"MozCameraFocusAdjust"`, and `"MozPhoneCall"` now have official names in the UI Events specification: `"GoHome"`, `"CameraFocus"`, and `"Call"`. Firefox 49 has been updated to use the new names ([Firefox bug 1272599](https://bugzil.la/1272599)). See [Code values for keyboard events](/en-US/docs/Web/API/UI_Events/Keyboard_event_code_values) for a full list of available key codes. - The key values `"Separator"` and `"MediaSkip"` have been removed, as they were deprecated and unused ([Firefox bug 1232919](https://bugzil.la/1232919)). - Key values and the corresponding key codes `"Hyper"` and `"Super"` have been added to represent these legacy modifier keys ([Firefox bug 1232919](https://bugzil.la/1232919)). @@ -175,7 +175,7 @@ This marks the next step in the journey toward a plugin-free future. HTML is ver ## HTTP -- The [`Cache-Control: immutable`](/en-US/docs/Web/HTTP/Headers/Cache-Control) directive has been implemented ([Firefox bug 1267474](https://bugzil.la/1267474)). See also this [blog post](https://bitsup.blogspot.com/2016/05/cache-control-immutable.html) for more information. +- The [`Cache-Control: immutable`](/en-US/docs/Web/HTTP/Reference/Headers/Cache-Control) directive has been implemented ([Firefox bug 1267474](https://bugzil.la/1267474)). See also this [blog post](https://bitsup.blogspot.com/2016/05/cache-control-immutable.html) for more information. - The {{CSP("require-sri-for")}} {{HTTPHeader("Content-Security-Policy")}} has been implemented ([Firefox bug 1265318](https://bugzil.la/1265318)). ## Networking diff --git a/files/en-us/mozilla/firefox/releases/5/index.md b/files/en-us/mozilla/firefox/releases/5/index.md index 09da2f00691d3bb..a1fd4fb5107244b 100644 --- a/files/en-us/mozilla/firefox/releases/5/index.md +++ b/files/en-us/mozilla/firefox/releases/5/index.md @@ -14,7 +14,7 @@ Firefox 5, based on Gecko 5.0, was released on June 21, 2011. This article provi - All HTML elements now have the {{ domxref("HTMLElement.accessKey", "accessKey") }} attribute, as well as the {{ domxref("HTMLElement.blur()", "blur()") }}, {{ domxref("HTMLElement.click()", "click()") }}, and {{ domxref("HTMLElement.focus()", "focus()") }} methods. These are specified in the {{ domxref("HTMLElement") }} interface. - In order to comply with the HTML5 specification, support for the UTF-7 and UTF-32 [character sets](/en-US/docs/Character_Sets_Supported_by_Gecko) has been removed. -- When in quirks mode, empty {{ HTMLElement("map") }}s are no longer skipped over in favor of non-empty ones when matching. See the [Gecko notes](/en-US/docs/Web/HTML/Element/map#gecko_notes) on the {{ HTMLElement("map") }} element for details. +- When in quirks mode, empty {{ HTMLElement("map") }}s are no longer skipped over in favor of non-empty ones when matching. See the [Gecko notes](/en-US/docs/Web/HTML/Reference/Elements/map#gecko_notes) on the {{ HTMLElement("map") }} element for details. - Firefox mobile on Android now supports WOFF fonts for {{ cssxref("@font-face") }}. - WebGL [no longer loads textures from domains other than the originating domain](/en-US/docs/Web/API/WebGL_API/Tutorial/Using_textures_in_WebGL#cross-domain_textures), as a security measure. [HTTP access control](/en-US/docs/Web/HTTP_access_control) support should be coming sometime in the future to make this possible more securely. @@ -46,7 +46,7 @@ Firefox 5, based on Gecko 5.0, was released on June 21, 2011. This article provi - Similarly, the {{domxref("Window.setInterval()")}} and {{domxref("WorkerGlobalScope.setInterval()")}} method now clamps to no more than one interval per second in inactive tabs. - [`XMLHttpRequest`](/en-US/docs/Web/API/XMLHttpRequest) now [supports the `loadend` event](/en-US/docs/Web/API/XMLHttpRequest_API/Using_XMLHttpRequest#detecting_any_load_end_condition) for progress listeners. This is sent after any transfer is finished (that is, after the `abort`, `error`, or `load` event). You can use this to handle any tasks that need to be performed regardless of success or failure of a transfer. - The {{ domxref("Blob") }} and, by extension, the {{ domxref("File") }} objects' `slice()` method has been removed and replaced with a new, proposed syntax that makes it more consistent with [`Array.slice()`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/slice) and [`String.slice()`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/String/slice) methods in JavaScript. This method is named `mozSlice()` for now. -- The value of {{ domxref("Navigator.language") }} is now determined by looking at the value of the `Accept-Language` [HTTP header](/en-US/docs/Web/HTTP/Headers). +- The value of {{ domxref("Navigator.language") }} is now determined by looking at the value of the `Accept-Language` [HTTP header](/en-US/docs/Web/HTTP/Reference/Headers). - The {{ domxref("Element.prefix") }} property is now read only, as required by the DOM specification. - The {{ domxref("HTMLVideoElement") }} now supports experimental properties to get information about video paint statistics like frame rates. @@ -97,7 +97,7 @@ For a guide to updating your add-on for Firefox 5, please see [Updating add-ons ### Interface changes - The `nsIHttpChannelInternal` interface has new attributes providing access to information about the channels' endpoints' addresses and ports. This information is provided primarily for debugging purposes. -- The {{ HTMLElement("canvas") }} element's [`width`](/en-US/docs/Web/HTML/Element/canvas#width) and [`height`](/en-US/docs/Web/HTML/Element/canvas#height) attributes are now reflected in IDL as unsigned integers instead of signed (see [`HTMLCanvasElement`](/en-US/docs/Web/API/HTMLCanvasElement)). +- The {{ HTMLElement("canvas") }} element's [`width`](/en-US/docs/Web/HTML/Reference/Elements/canvas#width) and [`height`](/en-US/docs/Web/HTML/Reference/Elements/canvas#height) attributes are now reflected in IDL as unsigned integers instead of signed (see [`HTMLCanvasElement`](/en-US/docs/Web/API/HTMLCanvasElement)). - The `nsIAppStartup2` and `nsIAppStartup_MOZILLA_2_0` interfaces have been merged into the `nsIAppStartup` interface. - The `nsIDocShell_MOZILLA_2_0_BRANCH` interface has been merged into the `nsIDocShell` interface. - The `nsIFocusManager_MOZILLA_2_0_BRANCH` interface has been merged into the `nsIFocusManager` interface. diff --git a/files/en-us/mozilla/firefox/releases/50/index.md b/files/en-us/mozilla/firefox/releases/50/index.md index cd74eec1d594e2d..2f7482cdeab2c69 100644 --- a/files/en-us/mozilla/firefox/releases/50/index.md +++ b/files/en-us/mozilla/firefox/releases/50/index.md @@ -14,14 +14,14 @@ Firefox 50 was released on November 15, 2016. This article lists key changes tha ### HTML - The default style of {{HTMLElement("bdo")}} now sets {{cssxref("unicode-bidi")}} with the `isolate-override` value ([Firefox bug 1249497](https://bugzil.la/1249497)). -- Setting the {{HTMLElement("track")}} element's [`src`](/en-US/docs/Web/HTML/Element/track#src) attribute now works correctly ([Firefox bug 1281418](https://bugzil.la/1281418)). +- Setting the {{HTMLElement("track")}} element's [`src`](/en-US/docs/Web/HTML/Reference/Elements/track#src) attribute now works correctly ([Firefox bug 1281418](https://bugzil.la/1281418)). - The `referrerpolicy` attribute on {{HTMLElement("area")}}, {{HTMLElement("a")}}, {{HTMLElement("img")}}, {{HTMLElement("iframe")}} and {{HTMLElement("link")}} elements is now available by default ([Firefox bug 1223838](https://bugzil.la/1223838), [Firefox bug 1264165](https://bugzil.la/1264165)). ### CSS - Corners with border-radius and with dashed and dotted styles are now rendered with the specified style instead of a solid style ([Firefox bug 382721](https://bugzil.la/382721)). - The non-standard `:-moz-full-screen-ancestor` pseudo-class selector has been removed ([Firefox bug 1199529](https://bugzil.la/1199529)). -- The {{cssxref("box-sizing")}}`: padding-box` has been removed, since it's no longer a part of the spec and Firefox was the only major browser implementing it ([Firefox bug 1166728](https://bugzil.la/1166728)). +- The {{cssxref("box-sizing", "box-sizing: padding-box")}} has been removed, since it's no longer a part of the spec and Firefox was the only major browser implementing it ([Firefox bug 1166728](https://bugzil.la/1166728)). - The three values `isolate`, `isolate-override`, and `plaintext` of the {{cssxref("unicode-bidi")}} property have been unprefixed ([Firefox bug 1141895](https://bugzil.la/1141895)). - In quirks mode, the bullet of a list item now inherits the size of the list, like in standards mode ([Firefox bug 648331](https://bugzil.la/648331)). - The {{cssxref(":in-range")}} and {{cssxref(":out-of-range")}} pseudo-classes have changed behavior to not match disabled or read-only inputs ([Firefox bug 1264157](https://bugzil.la/1264157)). @@ -53,10 +53,10 @@ Firefox 50 was released on November 15, 2016. This article lists key changes tha ### Security -- The [`ping`](/en-US/docs/Web/HTML/Element/a#ping) attribute of {{htmlelement("a")}} element now abides by the [`connect-src`](/en-US/docs/Web/HTTP/Headers/Content-Security-Policy#connect-src) [CSP 1.1 policy directive](/en-US/docs/Web/HTTP/Headers/Content-Security-Policy) ([Firefox bug 1100181](https://bugzil.la/1100181)). -- Support for the [`sandbox`](/en-US/docs/Web/HTTP/Headers/Content-Security-Policy#sandbox) [CSP](/en-US/docs/Web/HTTP/CSP) directive has been added ([Firefox bug 671389](https://bugzil.la/671389)). +- The [`ping`](/en-US/docs/Web/HTML/Reference/Elements/a#ping) attribute of {{htmlelement("a")}} element now abides by the [`connect-src`](/en-US/docs/Web/HTTP/Reference/Headers/Content-Security-Policy/connect-src) [CSP 1.1 policy directive](/en-US/docs/Web/HTTP/Reference/Headers/Content-Security-Policy) ([Firefox bug 1100181](https://bugzil.la/1100181)). +- Support for the [`sandbox`](/en-US/docs/Web/HTTP/Reference/Headers/Content-Security-Policy/sandbox) [CSP](/en-US/docs/Web/HTTP/Guides/CSP) directive has been added ([Firefox bug 671389](https://bugzil.la/671389)). - It's now possible to set a [content security policy for workers](/en-US/docs/Web/API/Web_Workers_API/Using_web_workers#content_security_policy) ([Firefox bug 959388](https://bugzil.la/959388)). -- The {{domxref("Navigator.sendBeacon()")}} method no longer throws an exception if the beacon data couldn't be sent due to a [Content Security Policy](/en-US/docs/Web/HTTP/CSP) restriction; instead, it returns `false` as expected ([Firefox bug 1234813](https://bugzil.la/1234813)). +- The {{domxref("Navigator.sendBeacon()")}} method no longer throws an exception if the beacon data couldn't be sent due to a [Content Security Policy](/en-US/docs/Web/HTTP/Guides/CSP) restriction; instead, it returns `false` as expected ([Firefox bug 1234813](https://bugzil.la/1234813)). - Support for RC4 encryption was deprecated in Firefox 36 and disabled by default in Firefox 44. The one-year grace period has ended, so Firefox 50 removes all support for RC4 (Google Chrome removed support for RC4 in August 2016). From now on, any time Firefox encounters RC4 encryption, it will report an `SSL_ERROR_NO_CYPHER_OVERLAP` error. ### Networking @@ -138,7 +138,7 @@ Firefox 50 was released on November 15, 2016. This article lists key changes tha - {{domxref("FileSystemDirectoryEntry")}} (except for {{domxref("FileSystemDirectoryEntry.removeRecursively", "removeRecursively()")}}) - {{domxref("FileSystemDirectoryReader")}} - - {{domxref("HTMLInputElement.webkitdirectory")}} as well as the [`webkitdirectory`](/en-US/docs/Web/HTML/Element/input#webkitdirectory) attribute of the {{HTMLElement("input")}} element have been implemented; this lets you configure a file input to accept directories instead of files ([Firefox bug 1258489](https://bugzil.la/1258489)). + - {{domxref("HTMLInputElement.webkitdirectory")}} as well as the [`webkitdirectory`](/en-US/docs/Web/HTML/Reference/Elements/input#webkitdirectory) attribute of the {{HTMLElement("input")}} element have been implemented; this lets you configure a file input to accept directories instead of files ([Firefox bug 1258489](https://bugzil.la/1258489)). - {{domxref("HTMLInputElement.webkitEntries")}} has been implemented; this returns an array of {{domxref("FileSystemEntry")}}-based objects representing the selected items. - {{domxref("File.webkitRelativePath")}} has been implemented; this contains the path of the file relative to the root of the containing {{domxref("FileSystemDirectoryEntry")}} that was among the items in the list returned by {{domxref("HTMLInputElement.webkitEntries")}}. - These APIs are now enabled by default; some were previously available but only behind a preference ([Firefox bug 1288683](https://bugzil.la/1288683)). diff --git a/files/en-us/mozilla/firefox/releases/51/index.md b/files/en-us/mozilla/firefox/releases/51/index.md index 05b09f7b9bac36b..22445ff2cf296cd 100644 --- a/files/en-us/mozilla/firefox/releases/51/index.md +++ b/files/en-us/mozilla/firefox/releases/51/index.md @@ -34,7 +34,7 @@ Firefox 51 was released on January 24, 2017. This article lists key changes that - {{jsxref("Statements/const", "const")}} and {{jsxref("Statements/let", "let")}} are now fully ES2015-compliant ([Firefox bug 950547](https://bugzil.la/950547)). - Using {{jsxref("Statements/const", "const")}} in [`for...of`](/en-US/docs/Web/JavaScript/Reference/Statements/for...of) loops now has a fresh binding for each iteration and no longer throws a {{jsxref("SyntaxError")}} ([Firefox bug 1101653](https://bugzil.la/1101653)). - The deprecated [`for each...in`](/en-US/docs/Web/JavaScript/Reference/Deprecated_and_obsolete_features#statements_2) loop now presents a warning in the console ([Firefox bug 1293205](https://bugzil.la/1293205)). Please migrate your code to use the standardized [`for...of`](/en-US/docs/Web/JavaScript/Reference/Statements/for...of) loop. -- [Generator functions](/en-US/docs/Web/JavaScript/Reference/Statements/function*) can't have a [label](/en-US/docs/Web/JavaScript/Reference/Statements/label) anymore and "`let`" as a label name is disallowed now ([Firefox bug 1288459](https://bugzil.la/1288459)). +- [Generator functions](/en-US/docs/Web/JavaScript/Reference/Statements/function*) can't have a [label](/en-US/docs/Web/JavaScript/Reference/Statements/label) anymore and `let` as a label name is disallowed now ([Firefox bug 1288459](https://bugzil.la/1288459)). - Deprecated [legacy generator functions](/en-US/docs/Web/JavaScript/Reference/Deprecated_and_obsolete_features) will now throw when used in [method definitions](/en-US/docs/Web/JavaScript/Reference/Functions/Method_definitions) ([Firefox bug 1199296](https://bugzil.la/1199296)). - The `next()` method of the [iterator protocol](/en-US/docs/Web/JavaScript/Reference/Iteration_protocols#the_iterator_protocol) will now throw a {{jsxref("TypeError")}} if the returned value is not an object ([Firefox bug 1016936](https://bugzil.la/1016936)). - Child-indexed pseudo-class selectors should match without a parent ([Firefox bug 1300374](https://bugzil.la/1300374)). @@ -94,7 +94,7 @@ Firefox 51 was released on January 24, 2017. This article lists key changes that - Scripts served with an `image/*`, `video/*`, `audio/*` or `text/csv` MIME type are now blocked and are not loaded or executed. This happen when they are declared using {{HTMLElement("script")}}, or loaded via {{domxref("WorkerGlobalScope.importScripts()")}}, {{domxref("Worker.Worker","Worker()")}}, {{domxref("SharedWorker.SharedWorker", "SharedWorker()")}} ([Firefox bug 1229267](https://bugzil.la/1229267) and [Firefox bug 1288361](https://bugzil.la/1288361)). - Support for SHA-1 certificates from publicly-trusted certificate authorities has been removed ([Firefox bug 1302140](https://bugzil.la/1302140)). See also [Phasing Out SHA-1 on the Public Web](https://blog.mozilla.org/security/2016/10/18/phasing-out-sha-1-on-the-public-web/) for more information. - New WoSign and StartCom certificates will no longer be accepted ([Firefox bug 1309707](https://bugzil.la/1309707)), see [Distrusting New WoSign and StartCom Certificates](https://blog.mozilla.org/security/2016/10/24/distrusting-new-wosign-and-startcom-certificates/) for more information. -- The [PAC](/en-US/docs/Web/HTTP/Proxy_servers_and_tunneling/Proxy_Auto-Configuration_PAC_file) `FindProxyForURL(url, host)` function now strips paths and queries from https\:// URLs to avoid information leakage (see [Firefox bug 1255474](https://bugzil.la/1255474) and [CVE-2017-5384](https://nvd.nist.gov/vuln/detail/CVE-2017-5384)). +- The [PAC](/en-US/docs/Web/HTTP/Guides/Proxy_servers_and_tunneling/Proxy_Auto-Configuration_PAC_file) `FindProxyForURL(url, host)` function now strips paths and queries from https\:// URLs to avoid information leakage (see [Firefox bug 1255474](https://bugzil.la/1255474) and [CVE-2017-5384](https://nvd.nist.gov/vuln/detail/CVE-2017-5384)). ### XHR @@ -131,7 +131,7 @@ Firefox 51 was released on January 24, 2017. This article lists key changes that ### Security -- When login pages (i.e., those containing an [`<input type="password">`](/en-US/docs/Web/HTML/Element/input/password) field) are created so that they would be submitted insecurely, Firefox displays a crossed-out lock icon in the address bar to warn users ([Firefox bug 1319119](https://bugzil.la/1319119)). See [Insecure passwords](/en-US/docs/Web/Security/Insecure_passwords) for more details. +- When login pages (i.e., those containing an [`<input type="password">`](/en-US/docs/Web/HTML/Reference/Elements/input/password) field) are created so that they would be submitted insecurely, Firefox displays a crossed-out lock icon in the address bar to warn users ([Firefox bug 1319119](https://bugzil.la/1319119)). See [Insecure passwords](/en-US/docs/Web/Security/Insecure_passwords) for more details. ### Removals diff --git a/files/en-us/mozilla/firefox/releases/52/index.md b/files/en-us/mozilla/firefox/releases/52/index.md index 6b55e56293551fc..69cd1db870d892d 100644 --- a/files/en-us/mozilla/firefox/releases/52/index.md +++ b/files/en-us/mozilla/firefox/releases/52/index.md @@ -23,7 +23,7 @@ Firefox 52 was released on March 7, 2017. This article lists key changes that ar ### HTML -- The `rel="noopener"` [Link type](/en-US/docs/Web/HTML/Attributes/rel) has been implemented (see [Firefox bug 1222516](https://bugzil.la/1222516)). +- The `rel="noopener"` [Link type](/en-US/docs/Web/HTML/Reference/Attributes/rel) has been implemented (see [Firefox bug 1222516](https://bugzil.la/1222516)). ### CSS @@ -36,7 +36,7 @@ Firefox 52 was released on March 7, 2017. This article lists key changes that ar - Added support for subpixel antialiasing in CSS {{cssxref("mask")}} / {{cssxref("clip-path")}} ([Firefox bug 1305259](https://bugzil.la/1305259)). - Implemented CSS Text 3 segment break transformation rules ([Firefox bug 1081858](https://bugzil.la/1081858)). - Basic shape clipping (as applied via the {{cssxref("clip-path")}} property) can now be applied to SVG content ([Firefox bug 1246741](https://bugzil.la/1246741)). -- Implemented Flexbox layout for {{cssxref("align-self")}}|{{cssxref("justify-self")}}: \[ first | last ]? baseline ([Firefox bug 1221524](https://bugzil.la/1221524)). +- Implemented Flexbox layout for {{cssxref("align-self")}} and {{cssxref("justify-self")}} ([Firefox bug 1221524](https://bugzil.la/1221524)). - The {{cssxref("touch-action")}} property is now enabled by default on all platforms. (For the full story, see [intent to ship mail #1](https://groups.google.com/forum/#!topic/mozilla.dev.platform/6CGjsm1XpD4) and [intent to ship mail #2](https://groups.google.com/forum/#!topic/mozilla.dev.platform/SYEzvXJKw9M).) - Flexbox {{cssxref("align-content")}} handling & single-line-sizing should depend on {{cssxref("flex-wrap")}}, not number of lines ([Firefox bug 1090031](https://bugzil.la/1090031)). - [CSS Animations](/en-US/docs/Web/CSS/CSS_animations) can now be used to animate non-interpolated properties (see [Firefox bug 1064937](https://bugzil.la/1064937)). @@ -47,10 +47,10 @@ Firefox 52 was released on March 7, 2017. This article lists key changes that ar - There have been a number of changes to CSS {{cssxref("&lt;color&gt;")}} values (see [Firefox bug 1295456](https://bugzil.la/1295456)): - `rgba()` and `hsla()` have now been redefined as aliases of `rgb()` and `hsl()`; both accept the same parameter syntax. - - `rgb(`) and `hsl()` now accept an optional alpha value, e.g. `rgb(255, 0, 0, 0.5)`. - - Color functions now accept space-separated parameters rather than commas, e.g. `rgb(255 0 0 / 0.5)`. - - Alpha values can now be specified as percentages as well as numbers, e.g. `rgb(255 0 0 / 50%)`. - - The hue component in `hsl()` colors can now be specified as an angle, as well as a number, e.g. `hsl(120deg, 60%, 70%)`. + - `rgb(`) and `hsl()` now accept an optional alpha value, e.g., `rgb(255, 0, 0, 0.5)`. + - Color functions now accept space-separated parameters rather than commas, e.g., `rgb(255 0 0 / 0.5)`. + - Alpha values can now be specified as percentages as well as numbers, e.g., `rgb(255 0 0 / 50%)`. + - The hue component in `hsl()` colors can now be specified as an angle, as well as a number, e.g., `hsl(120deg, 60%, 70%)`. - Firefox's implementation of child-indexed pseudo-classes (such as {{cssxref(":nth-child")}}, {{cssxref(":first-child")}}, and so forth) has been updated to match the CSS selectors level 4 specification: these pseudo-classes now match the appropriate sibling elements rather than the children of their parent element. This allows these pseudo-classes to be used when there is no parent, or the parent is not an {{domxref("Element")}} ([Firefox bug 1300374](https://bugzil.la/1300374). @@ -81,13 +81,13 @@ Firefox 52 was released on March 7, 2017. This article lists key changes that ar #### Changes and removals -- [Array destructuring](/en-US/docs/Web/JavaScript/Reference/Operators/Destructuring_assignment#array_destructuring) now throws a {{jsxref("SyntaxError")}} when using destructuring rest with trailing comma ([Firefox bug 1041341](https://bugzil.la/1041341)). -- Duplicate `__proto__` properties are now allowed in [object destructuring](/en-US/docs/Web/JavaScript/Reference/Operators/Destructuring_assignment) ([Firefox bug 1204024](https://bugzil.la/1204024)). -- {{jsxref("Array.prototype.toLocaleString()")}} has been re-implemented to support the Intl API parameters "`locales`" and "`options`" ([Firefox bug 1130636](https://bugzil.la/1130636)). +- [Array destructuring](/en-US/docs/Web/JavaScript/Reference/Operators/Destructuring#array_destructuring) now throws a {{jsxref("SyntaxError")}} when using destructuring rest with trailing comma ([Firefox bug 1041341](https://bugzil.la/1041341)). +- Duplicate `__proto__` properties are now allowed in [object destructuring](/en-US/docs/Web/JavaScript/Reference/Operators/Destructuring) ([Firefox bug 1204024](https://bugzil.la/1204024)). +- {{jsxref("Array.prototype.toLocaleString()")}} has been re-implemented to support the Intl API parameters `locales` and `options` ([Firefox bug 1130636](https://bugzil.la/1130636)). - {{jsxref("TypedArray")}} constructors now accept [iterables](/en-US/docs/Web/JavaScript/Reference/Iteration_protocols) to create new typed arrays ([Firefox bug 1232266](https://bugzil.la/1232266)). - {{jsxref("TypedArray.from()")}}, {{jsxref("TypedArray.of()")}}, {{jsxref("TypedArray.prototype.filter()")}}, {{jsxref("TypedArray.prototype.map()")}}, {{jsxref("TypedArray.prototype.slice()")}}, {{jsxref("TypedArray.prototype.subarray()")}} now require that their `this` values are valid Typed Array constructors ([Firefox bug 1122396](https://bugzil.la/1122396)). - The non-standard {{jsxref("ArrayBuffer.slice()")}} method (not {{jsxref("ArrayBuffer.prototype.slice()")}}) is deprecated and now presents a warning when used ([Firefox bug 1316913](https://bugzil.la/1316913)). -- [Unicode code point escapes](/en-US/docs/Web/JavaScript/Reference/Lexical_grammar#unicode_code_point_escapes) can now also be used as identifiers (e.g. "`let \u{61} = 123`", see [Firefox bug 1314037](https://bugzil.la/1314037)). +- [Unicode code point escapes](/en-US/docs/Web/JavaScript/Reference/Lexical_grammar#unicode_code_point_escapes) can now also be used as identifiers (e.g., `let \u{61} = 123`, see [Firefox bug 1314037](https://bugzil.la/1314037)). - To conform with ES2015, `\u2e2f` and `ⸯ` now throw when used as identifier, for details see [Firefox bug 917436](https://bugzil.la/917436) and [Firefox bug 1197230](https://bugzil.la/1197230). ### WebAssembly @@ -106,7 +106,7 @@ Firefox 52 was released on March 7, 2017. This article lists key changes that ar - The {{domxref("DataTransfer.types")}} property of the [Drag and drop API](/en-US/docs/Web/API/HTML_Drag_and_Drop_API) now returns a frozen array of strings rather than a {{domxref("DOMStringList")}} (see [Firefox bug 1298243](https://bugzil.la/1298243)). - The `loadstart` and `loadend` events are now fired on {{htmlelement("img")}} elements (see [Firefox bug 1264769](https://bugzil.la/1264769)). - The {{domxref("Notification.requireInteraction")}} of the [Notifications API](/en-US/docs/Web/API/Notifications_API) has been implemented (see [Firefox bug 862395](https://bugzil.la/862395).) -- The {{domxref("Window.open()")}} method now has a `noopener` [window feature](/en-US/docs/Web/API/Window/open#window_functionality_features) available (see [Firefox bug 1267339](https://bugzil.la/1267339)), which mirrors the functionality of the `rel="noopener"` [Link type](/en-US/docs/Web/HTML/Attributes/rel). +- The {{domxref("Window.open()")}} method now has a `noopener` [window feature](/en-US/docs/Web/API/Window/open#window_functionality_features) available (see [Firefox bug 1267339](https://bugzil.la/1267339)), which mirrors the functionality of the `rel="noopener"` [Link type](/en-US/docs/Web/HTML/Reference/Attributes/rel). - The {{domxref("CustomElementRegistry.get()")}} method of the [Web Components API](/en-US/docs/Web/API/Web_components) has been implemented (see [Firefox bug 1275838](https://bugzil.la/1275838)). - [Pointer Event](/en-US/docs/Web/API/Pointer_events) {{domxref("PointerEvent.width","width")}} and {{domxref("PointerEvent.height","height")}} properties now default to a value of 1 (see [Firefox bug 1304315](https://bugzil.la/1304315)). - The [File and Directory Entries API](/en-US/docs/Web/API/File_and_Directory_Entries_API) has been updated to include changes in the [latest spec](https://wicg.github.io/entries-api/) (see [Firefox bug 1284987](https://bugzil.la/1284987) for the exact details). @@ -154,8 +154,8 @@ Firefox 52 was released on March 7, 2017. This article lists key changes that ar ### HTTP - The {{HTTPHeader("Referrer-Policy")}} header now supports the directives `same-origin`, `strict-origin`, and `strict-origin-when-cross-origin` ([Firefox bug 1276836](https://bugzil.la/1276836)). -- The [`'strict-dynamic'` source expression](/en-US/docs/Web/HTTP/Headers/Content-Security-Policy/script-src#strict-dynamic) is now supported for {{HTTPHeader("Content-Security-Policy")}} directives, such as {{CSP("script-src")}} ([Firefox bug 1299483](https://bugzil.la/1299483)). -- Insecure sites (`http:`) can't [set cookies](/en-US/docs/Web/HTTP/Cookies) with the "secure" directive anymore as per the [Strict Secure Cookies specification](https://datatracker.ietf.org/doc/html/draft-ietf-httpbis-cookie-alone-01) ([Firefox bug 976073](https://bugzil.la/976073)). +- The [`'strict-dynamic'` source expression](/en-US/docs/Web/HTTP/Reference/Headers/Content-Security-Policy/script-src#strict-dynamic) is now supported for {{HTTPHeader("Content-Security-Policy")}} directives, such as {{CSP("script-src")}} ([Firefox bug 1299483](https://bugzil.la/1299483)). +- Insecure sites (`http:`) can't [set cookies](/en-US/docs/Web/HTTP/Guides/Cookies) with the "secure" directive anymore as per the [Strict Secure Cookies specification](https://datatracker.ietf.org/doc/html/draft-ietf-httpbis-cookie-alone-01) ([Firefox bug 976073](https://bugzil.la/976073)). - The maximum table size format of the HTTP/2 header compression format [HPACK](https://datatracker.ietf.org/doc/html/rfc7541) has been increased from 4 KB to 64 KB ([Firefox bug 1296280](https://bugzil.la/1296280)). - The {{HTTPHeader("Large-Allocation")}} header has been added ([Firefox bug 1304140](https://bugzil.la/1304140)). @@ -165,7 +165,7 @@ Firefox 52 was released on March 7, 2017. This article lists key changes that ar ### Security -- When login pages (i.e., those containing an [`<input type="password">`](/en-US/docs/Web/HTML/Element/input/password) field) are created so that they would be submitted insecurely, Firefox displays an in-context warning message below the password field to warn users ([Firefox bug 1319119](https://bugzil.la/1319119)). Autofill is also disabled on insecure login forms ([Firefox bug 1217152](https://bugzil.la/1217152)). See [Insecure passwords](/en-US/docs/Web/Security/Insecure_passwords) for more details. +- When login pages (i.e., those containing an [`<input type="password">`](/en-US/docs/Web/HTML/Reference/Elements/input/password) field) are created so that they would be submitted insecurely, Firefox displays an in-context warning message below the password field to warn users ([Firefox bug 1319119](https://bugzil.la/1319119)). Autofill is also disabled on insecure login forms ([Firefox bug 1217152](https://bugzil.la/1217152)). See [Insecure passwords](/en-US/docs/Web/Security/Insecure_passwords) for more details. - Support for SHA-1 SSL certificates has been removed; navigating to a secure page that uses a SHA-1 certificate will now result in an `Untrusted Connection` error ([Firefox bug 1330043](https://bugzil.la/1330043)). ## Plugins diff --git a/files/en-us/mozilla/firefox/releases/53/index.md b/files/en-us/mozilla/firefox/releases/53/index.md index d03ea501a5b4bb5..038d10887b6c539 100644 --- a/files/en-us/mozilla/firefox/releases/53/index.md +++ b/files/en-us/mozilla/firefox/releases/53/index.md @@ -59,7 +59,7 @@ Firefox 53 was released on April 19, 2017. This article lists key changes that a ### DOM -- The {{domxref("HTMLAnchorElement/pathname", "pathname")}} and {{domxref("HTMLAnchorElement/search", "search")}} properties of links (like for {{HTMLElement("a")}} and {{HTMLELement("link")}} elements' interfaces previously returned the wrong parts of the URL. For example, for a URL of `http://z.com/x?a=true&b=false`, `pathname` would return "`/x?a=true&b=false"` and `search` would return "", rather than "`/x`" and "`?a=true&b=false"` respectively. This has now been fixed ([Firefox bug 1310483](https://bugzil.la/1310483)). +- The {{domxref("HTMLAnchorElement/pathname", "pathname")}} and {{domxref("HTMLAnchorElement/search", "search")}} properties of links (like for {{HTMLElement("a")}} and {{HTMLELement("link")}} elements' interfaces previously returned the wrong parts of the URL. For example, for a URL of `http://z.com/x?a=true&b=false`, `pathname` would return `"/x?a=true&b=false"` and `search` would return `""`, rather than `"/x"` and `"?a=true&b=false"` respectively. This has now been fixed ([Firefox bug 1310483](https://bugzil.la/1310483)). - The {{domxref("URLSearchParams.URLSearchParams", "URLSearchParams()")}} constructor now accepts a string or sequence of strings as an init object ([Firefox bug 1330678](https://bugzil.la/1330678)). - The {{domxref("Selection.setBaseAndExtent()")}} method of the [Selection API](/en-US/docs/Web/API/Selection) is now implemented (see [Firefox bug 1321623](https://bugzil.la/1321623)). - The ["fakepath"](https://html.spec.whatwg.org/multipage/forms.html#fakepath-srsly) addition to `file` type {{htmlelement("input")}} `values` has been implemented in Gecko, giving it parity with other browsers (see [Firefox bug 1274596](https://bugzil.la/1274596)). diff --git a/files/en-us/mozilla/firefox/releases/54/index.md b/files/en-us/mozilla/firefox/releases/54/index.md index cc8cbf2cacd511b..0cd433c82e32174 100644 --- a/files/en-us/mozilla/firefox/releases/54/index.md +++ b/files/en-us/mozilla/firefox/releases/54/index.md @@ -19,11 +19,11 @@ Firefox 54 was released on June 13, 2017. This article lists key changes that ar - {{cssxref("clip-path")}} now supports [basic shapes](/en-US/docs/Web/CSS/CSS_shapes) ([Firefox bug 1247229](https://bugzil.la/1247229)). - Firefox's implementations of CSS Flexbox and CSS alignment now implement updated spec language for interactions between the properties {{cssxref("align-items")}} and {{cssxref("align-self")}} as well as between {{cssxref("justify-items")}} and {{cssxref("justify-self")}} ([Firefox bug 1340309](https://bugzil.la/1340309)). -- {{htmlelement("input")}} elements of types `checkbox` and `radio` with {{cssxref("appearance", "-moz-appearance")}}`: none;` set on them are now non-replaced elements, for compatibility with other browsers ([Firefox bug 605985](https://bugzil.la/605985)). +- {{htmlelement("input")}} elements of types `checkbox` and `radio` with {{cssxref("appearance", "-moz-appearance: none")}} set on them are now non-replaced elements, for compatibility with other browsers ([Firefox bug 605985](https://bugzil.la/605985)). - Previously, an element styled with {{cssxref("display")}}: `inline-block` with a child element of type {{domxref("HTMLInputElement")}} styled with `display:block` had a wrong baseline ([Firefox bug 1330962](https://bugzil.la/1330962)). This is now fixed. - When Mozilla introduced dedicated content threads to Firefox (through the Electrolysis or e10s project), support for styling {{HTMLElement("option")}} elements was removed temporarily. Starting in Firefox 54, you can apply foreground and background colors to `<option>` elements again, using the {{cssxref("color")}} and {{cssxref("background-color")}} attributes. See [Firefox bug 910022](https://bugzil.la/910022) for more information. Note that this is still disabled in Linux due to lack of contrast (see [Firefox bug 1338283](https://bugzil.la/1338283) for progress on this). - [CSS Animations](/en-US/docs/Web/CSS/CSS_animations) now send the {{domxref("Element/animationcancel_event", "animationcancel")}} event as expected when an animation aborts prematurely ([Firefox bug 1302648](https://bugzil.la/1302648)). -- Transparent colors (i.e. those with an alpha channel of 0) were being serialized to the [`transparent` color keyword](/en-US/docs/Web/CSS/color_value) in certain situations; this has been fixed so that Firefox follows the spec (as well as other browsers' implementations). See ([Firefox bug 1339394](https://bugzil.la/1339394) for further information. +- Transparent colors (i.e., those with an alpha channel of 0) were being serialized to the [`transparent` color keyword](/en-US/docs/Web/CSS/color_value) in certain situations; this has been fixed so that Firefox follows the spec (as well as other browsers' implementations). See ([Firefox bug 1339394](https://bugzil.la/1339394) for further information. - The proprietary `:-moz-table-border-nonzero` pseudo-class is no longer available to web content; it is now restricted to Firefox's internal UA stylesheet ([Firefox bug 1341925](https://bugzil.la/1341925)). - \[css-grid] Intrinsic content with overflow:auto overlaps in grid ([Firefox bug 1348857](https://bugzil.la/1348857)). - \[css-grid] Transferred min-size contribution of percentage size grid item with an intrinsic ratio ([Firefox bug 1349320](https://bugzil.la/1349320)). diff --git a/files/en-us/mozilla/firefox/releases/55/index.md b/files/en-us/mozilla/firefox/releases/55/index.md index 52128c5c54d1901..213a5a8021268f8 100644 --- a/files/en-us/mozilla/firefox/releases/55/index.md +++ b/files/en-us/mozilla/firefox/releases/55/index.md @@ -19,7 +19,7 @@ Firefox 55 was released on August 8, 2017. This article lists key changes that a ### HTML -- Elements on which [`contenteditable`](/en-US/docs/Web/HTML/Global_attributes/contenteditable) has been set to `true` now use {{htmlelement("div")}} elements to separate different lines of text, to give Firefox parity with other modern browsers ([Firefox bug 1297414](https://bugzil.la/1297414)). See [Differences in markup generation](/en-US/docs/Web/HTML/Global_attributes/contenteditable#differences_in_markup_generation) for more details. +- Elements on which [`contenteditable`](/en-US/docs/Web/HTML/Reference/Global_attributes/contenteditable) has been set to `true` now use {{htmlelement("div")}} elements to separate different lines of text, to give Firefox parity with other modern browsers ([Firefox bug 1297414](https://bugzil.la/1297414)). See [Differences in markup generation](/en-US/docs/Web/HTML/Reference/Global_attributes/contenteditable#differences_in_markup_generation) for more details. - Enable `dom.forms.datetime` by default on Nightly ([Firefox bug 1366188](https://bugzil.la/1366188)). ### CSS @@ -41,7 +41,7 @@ Firefox 55 was released on August 8, 2017. This article lists key changes that a ### JavaScript - The {{jsxref("SharedArrayBuffer")}} and {{jsxref("Atomics")}} objects are now enabled by default. See [A Taste of JavaScript's New Parallel Primitives](https://hacks.mozilla.org/2016/05/a-taste-of-javascripts-new-parallel-primitives/) for an introduction to JavaScript Shared Memory and Atomics. -- The rest operator (`...`) is now supported in [object destructuring](/en-US/docs/Web/JavaScript/Reference/Operators/Destructuring_assignment) and the spread operator (`...`) now works in [object literals](/en-US/docs/Web/JavaScript/Reference/Operators/Spread_syntax#spread_in_object_literals) (Stage 3 ECMAScript proposal: [Object Rest/Spread Properties](https://github.com/tc39/proposal-object-rest-spread), [Firefox bug 1339395](https://bugzil.la/1339395)). +- The rest operator (`...`) is now supported in [object destructuring](/en-US/docs/Web/JavaScript/Reference/Operators/Destructuring) and the spread operator (`...`) now works in [object literals](/en-US/docs/Web/JavaScript/Reference/Operators/Spread_syntax#spread_in_object_literals) (Stage 3 ECMAScript proposal: [Object Rest/Spread Properties](https://github.com/tc39/proposal-object-rest-spread), [Firefox bug 1339395](https://bugzil.la/1339395)). - [Async generator methods](/en-US/docs/Web/JavaScript/Reference/Functions/Method_definitions#async_generator_methods) are now supported ([Firefox bug 1353693](https://bugzil.la/1353693)). - The {{jsxref("String.prototype.toLocaleLowerCase()")}} and {{jsxref("String.prototype.toLocaleUpperCase()")}} methods now support an optional `locale` parameter to specify a language tag for locale-specific case mappings ([Firefox bug 1318403](https://bugzil.la/1318403)). - The {{jsxref("Intl/Collator", "Intl.Collator")}} object now supports the `caseFirst` option ([Firefox bug 866473](https://bugzil.la/866473)). @@ -91,7 +91,7 @@ Firefox 55 was released on August 8, 2017. This article lists key changes that a #### Service Workers/Push -- Messages sent to service worker contexts (e.g. as the event object of {{domxref("ServiceWorkerGlobalScope.message_event","onmessage")}} are now represented by {{domxref("MessageEvent")}} objects, for consistency with other web messaging features. +- Messages sent to service worker contexts (e.g., as the event object of {{domxref("ServiceWorkerGlobalScope.message_event","onmessage")}} are now represented by {{domxref("MessageEvent")}} objects, for consistency with other web messaging features. - The {{domxref("PushManager.subscribe()")}} method now accepts {{jsxref("ArrayBuffer")}}s and Base64-encoded strings as `applicationServerKey` values ([Firefox bug 1337348](https://bugzil.la/1337348)). #### Web Audio API @@ -138,12 +138,12 @@ Firefox 55 was released on August 8, 2017. This article lists key changes that a ### HTML -- The `xml:base` attribute can no longer be used to set the base URL for paths appearing in the [`style`](/en-US/docs/Web/HTML/Global_attributes/style) attribute, for example — +- The `xml:base` attribute can no longer be used to set the base URL for paths appearing in the [`style`](/en-US/docs/Web/HTML/Reference/Global_attributes/style) attribute, for example — `<div xml:base="https://example.com/" style="background:url(picture.jpg)"></div>` ([Firefox bug 1350521](https://bugzil.la/1350521)). -- The {{htmlelement("style")}} element's [`scoped`](/en-US/docs/Web/HTML/Element/style#scoped) attribute has been hidden behind a pref (`layout.css.scoped-style.enabled`) in content documents in Firefox 55+, as no other browsers support it. -- Support for the obscure `MSThemeCompatible` value of the {{htmlelement("meta")}} element's [`http-equiv`](/en-US/docs/Web/HTML/Element/meta#http-equiv) attribute has been removed from Gecko. No other modern browsers support it, and it was causing compatibility problems ([Firefox bug 966240](https://bugzil.la/966240)). +- The {{htmlelement("style")}} element's [`scoped`](/en-US/docs/Web/HTML/Reference/Elements/style#scoped) attribute has been hidden behind a pref (`layout.css.scoped-style.enabled`) in content documents in Firefox 55+, as no other browsers support it. +- Support for the obscure `MSThemeCompatible` value of the {{htmlelement("meta")}} element's [`http-equiv`](/en-US/docs/Web/HTML/Reference/Elements/meta#http-equiv) attribute has been removed from Gecko. No other modern browsers support it, and it was causing compatibility problems ([Firefox bug 966240](https://bugzil.la/966240)). ### CSS diff --git a/files/en-us/mozilla/firefox/releases/56/index.md b/files/en-us/mozilla/firefox/releases/56/index.md index bc536de69847e5c..37990f4b9d4d2a1 100644 --- a/files/en-us/mozilla/firefox/releases/56/index.md +++ b/files/en-us/mozilla/firefox/releases/56/index.md @@ -18,7 +18,7 @@ Firefox 56 was released on September 28, 2017. This article lists key changes th ### HTML - Implemented the `labels` property for labelable form controls, for example {{domxref("HTMLInputElement.labels")}} ([Firefox bug 556743](https://bugzil.la/556743)). -- Implemented `<link rel="preload">`; see [Preloading content with rel="preload"](/en-US/docs/Web/HTML/Attributes/rel/preload) for more details ([Firefox bug 1222633](https://bugzil.la/1222633)). Note that currently Firefox only supports preloading of cacheable resources. +- Implemented `<link rel="preload">`; see [Preloading content with rel="preload"](/en-US/docs/Web/HTML/Reference/Attributes/rel/preload) for more details ([Firefox bug 1222633](https://bugzil.la/1222633)). Note that currently Firefox only supports preloading of cacheable resources. ### CSS @@ -46,7 +46,7 @@ _No changes._ - Firefox used to accept `iso-2022-jp-2` sequences silently when an `iso-2022-jp` {{domxref("TextDecoder.TextDecoder","TextDecoder()")}} was instantiated, however this has now been removed to simplify the API, as no other browsers support it and no pages seem to use it. ([Firefox bug 715833](https://bugzil.la/715833)). - The 4ms clamping behavior of {{domxref("Window.setTimeout()")}}, {{domxref("WorkerGlobalScope.setTimeout()")}}, {{domxref("Window.setInterval()")}} and {{domxref("WorkerGlobalScope.setInterval()")}} has been updated to be more in line with other browsers, as described in [Timeouts throttled to >=4ms](/en-US/docs/Web/API/Window/setTimeout#timeouts_throttled_to_%3e4ms) ([Firefox bug 1378586](https://bugzil.la/1378586)). - The [Page Visibility API's](/en-US/docs/Web/API/Page_Visibility_API) {{domxref("Document.visibilitychange_event", "onvisibilitychange")}} handler has been added ([Firefox bug 1333912](https://bugzil.la/1333912)). -- The {{domxref("Window.showModalDialog()")}} method has been removed ([Firefox bug 981796](https://bugzil.la/981796)). +- The `Window.showModalDialog()` method has been removed ([Firefox bug 981796](https://bugzil.la/981796)). - The implementation of the {{domxref("HTMLFormElement.action")}}, {{domxref("HTMLInputElement.formAction")}}, and {{domxref("HTMLButtonElement.formAction")}} properties has been updated so that they return the correct form submission URL, as per spec ([Firefox bug 1366361](https://bugzil.la/1366361)). #### DOM events diff --git a/files/en-us/mozilla/firefox/releases/57/index.md b/files/en-us/mozilla/firefox/releases/57/index.md index a7f54e2c26b4876..65fe8af3d83ee23 100644 --- a/files/en-us/mozilla/firefox/releases/57/index.md +++ b/files/en-us/mozilla/firefox/releases/57/index.md @@ -25,7 +25,7 @@ _No changes._ ### HTML -- The [date](/en-US/docs/Web/HTML/Element/input/date) and [time](/en-US/docs/Web/HTML/Element/input/time) {{htmlelement("input")}} types are now enabled in all builds ([Firefox bug 1399036](https://bugzil.la/1399036)). +- The [date](/en-US/docs/Web/HTML/Reference/Elements/input/date) and [time](/en-US/docs/Web/HTML/Reference/Elements/input/time) {{htmlelement("input")}} types are now enabled in all builds ([Firefox bug 1399036](https://bugzil.la/1399036)). ### CSS @@ -38,15 +38,15 @@ _No changes._ Following bugs have been fixed in Quantum: - Radial gradient values like `radial-gradient(circle gold,red)` will work in the old Gecko style system, even though they shouldn't because of the missing comma between `circle` and `gold` ([Firefox bug 1383323](https://bugzil.la/1383323)). -- When you animate an offscreen element onscreen but specify a delay, Gecko does not repaint on some platforms, e.g. Windows ([Firefox bug 1383239](https://bugzil.la/1383239)). +- When you animate an offscreen element onscreen but specify a delay, Gecko does not repaint on some platforms, e.g., Windows ([Firefox bug 1383239](https://bugzil.la/1383239)). - In Gecko, {{htmlelement("details")}} elements can't be made open by default using the `open` attribute if they have an {{CSSxRef("animation")}} active on them ([Firefox bug 1382124](https://bugzil.la/1382124)). - In Gecko, {{CSSxRef("transition", "transitions")}} will not work when transitioning from a {{CSSxRef("text-shadow")}} with a color specified to a `text-shadow` without a color specified ([Firefox bug 726550](https://bugzil.la/726550)). -- In Gecko, cancelling a filling animation (e.g. with `animation-fill-mode: forwards` set) can trigger a transition set on the same element, although only once (see [Firefox bug 1192592](https://bugzil.la/1192592) and [these test cases](https://bug1192592.bmoattachments.org/attachment.cgi?id=8843824) for more information). In general declarative animations should not trigger transitions. +- In Gecko, cancelling a filling animation (e.g., with `animation-fill-mode: forwards` set) can trigger a transition set on the same element, although only once (see [Firefox bug 1192592](https://bugzil.la/1192592) and [these test cases](https://bug1192592.bmoattachments.org/attachment.cgi?id=8843824) for more information). In general declarative animations should not trigger transitions. - Animations using em units are not affected by changes to the {{CSSxRef("font-size")}} on the animated element's parent in Gecko, whereas they should be ([Firefox bug 1254424](https://bugzil.la/1254424)). - Gecko also deals with `font-size` inheritance differently from Quantum CSS, meaning that for some language settings inherited font sizes end up being smaller than expected (see [Firefox bug 1391341](https://bugzil.la/1391341)). - Gecko reuses the same mechanism used when parsing a url-token when parsing the `domain()` or `url-prefix()` URL matching functions for a {{CSSxRef("@document", "@-moz-document")}} rule. Quantum CSS does not use the same mechanism and it does not consider tokens invalid when they contain brackets or quotes ([Firefox bug 1362333](https://bugzil.la/1362333)). -- In Gecko, when you set a system font as the value of a canvas 2D context's {{DOMxRef("CanvasRenderingContext2D.font", "font")}} (e.g. `menu`), getting the font value fails to return the expected font (it returns nothing). This has been fixed in Quantum. ([Firefox bug 1374885](https://bugzil.la/1374885)). -- In Gecko, when you create a detached subtree (e.g. a {{htmlelement("div")}} created using {{DOMxRef("Document.createElement","createElement()")}} that is not yet inserted into the DOM), the subtree's root element is set as a block-level element. In Quantum CSS this is set as inline, as per spec ([Firefox bug 1374994](https://bugzil.la/1374994)). +- In Gecko, when you set a system font as the value of a canvas 2D context's {{DOMxRef("CanvasRenderingContext2D.font", "font")}} (e.g., `menu`), getting the font value fails to return the expected font (it returns nothing). This has been fixed in Quantum. ([Firefox bug 1374885](https://bugzil.la/1374885)). +- In Gecko, when you create a detached subtree (e.g., a {{htmlelement("div")}} created using {{DOMxRef("Document.createElement","createElement()")}} that is not yet inserted into the DOM), the subtree's root element is set as a block-level element. In Quantum CSS this is set as inline, as per spec ([Firefox bug 1374994](https://bugzil.la/1374994)). - In Gecko, {{CSSxRef("calc", "calc()")}} expressions are rejected — causing the value to be invalid — when used as the radius component of a {{CSSxRef("gradient/radial-gradient")}} function ([Firefox bug 1376019](https://bugzil.la/1376019)). - In Gecko, `calc(1*2*3)` is not parsed successfully; Quantum CSS fixes this ([Firefox bug 1379467](https://bugzil.la/1379467)). - In Quantum CSS, [`calc()` is supported everywhere that the spec explains it should be](https://drafts.csswg.org/css-values-3/#calc-notation) ([Firefox bug 1350857](https://bugzil.la/1350857)). In Gecko it is not. @@ -91,7 +91,7 @@ _No changes._ - Support for messages of arbitrary size (up to 1GiB, although 256kiB is more interoperable) is now supported on {{DOMxRef("RTCDataChannel")}} through use of the end-of-record (EOR) flag on SCTP messages. See [Understanding message size limits](/en-US/docs/Web/API/WebRTC_API/Using_data_channels#understanding_message_size_limits) for more information ([Firefox bug 979417](https://bugzil.la/979417)). > [!NOTE] - > Because Firefox doesn't yet support the SCTP ndata protocol that provides the ability to interleave SCTP messages from multiple sources, sending large data objects can cause significant delays on all other SCTP traffic. See [Firefox bug 1381145](https://bugzil.la/1381145) to track progress on implementing and deploying ndata support in Firefox. + > Because Firefox doesn't yet support the SCTP Stream Schedulers and User Message Interleaving protocol that provides the ability to interleave SCTP messages from multiple sources, sending large data objects can cause significant delays on all other SCTP traffic. See [Firefox bug 1381145](https://bugzil.la/1381145) to track progress on implementing and deploying stream schedulers support in Firefox. - The {{DOMxRef("RTCDataChannel.send()")}} method can now throw a `TypeError` exception if the size of the message you're trying to send is not compatible with the receiving {{Glossary("user agent")}} (this is implemented as part of [Firefox bug 979417](https://bugzil.la/979417)). - The [MediaStream Recording API](/en-US/docs/Web/API/MediaStream_Recording_API) has been updated so that {{domxref("MediaRecorder/error_event", "error")}} events sent to report problems that occur while recording are now of type {{DOMxRef("MediaRecorderErrorEvent")}} rather than being generic events. @@ -115,7 +115,7 @@ _No changes._ ### HTML -- `<link rel="preload">` (see [Preloading content with rel="preload"](/en-US/docs/Web/HTML/Attributes/rel/preload)) has been disabled in Firefox 57 because of various web compatibility issues (e.g. [Firefox bug 1405761](https://bugzil.la/1405761)). An improved version that works for non-cacheable resources is expected to land in Firefox 58. +- `<link rel="preload">` (see [Preloading content with rel="preload"](/en-US/docs/Web/HTML/Reference/Attributes/rel/preload)) has been disabled in Firefox 57 because of various web compatibility issues (e.g., [Firefox bug 1405761](https://bugzil.la/1405761)). An improved version that works for non-cacheable resources is expected to land in Firefox 58. ### APIs diff --git a/files/en-us/mozilla/firefox/releases/58/index.md b/files/en-us/mozilla/firefox/releases/58/index.md index c105740911374f4..6ed6b1dfca8eb62 100644 --- a/files/en-us/mozilla/firefox/releases/58/index.md +++ b/files/en-us/mozilla/firefox/releases/58/index.md @@ -74,10 +74,10 @@ _No changes._ ### HTTP -- [`frame-ancestors`](/en-US/docs/Web/HTTP/Headers/Content-Security-Policy/frame-ancestors) is no longer ignored in {{httpheader("Content-Security-Policy-Report-Only")}} ([Firefox bug 1380755](https://bugzil.la/1380755)). +- [`frame-ancestors`](/en-US/docs/Web/HTTP/Reference/Headers/Content-Security-Policy/frame-ancestors) is no longer ignored in {{httpheader("Content-Security-Policy-Report-Only")}} ([Firefox bug 1380755](https://bugzil.la/1380755)). - Firefox now implements a TLS handshake timeout with a default value of 30 seconds. The timeout value can be varied by editing the `network.http.tls-handshake-timeout` pref in about:config ([Firefox bug 1393691](https://bugzil.la/1393691)). -- The [`worker-src`](/en-US/docs/Web/HTTP/Headers/Content-Security-Policy/worker-src) CSP directive has been implemented ([Firefox bug 1302667](https://bugzil.la/1302667)). -- The [425: Too Early](/en-US/docs/Web/HTTP/Status/425) status code and related {{httpheader("Early-Data")}} request header are now supported ([Firefox bug 1406908](https://bugzil.la/1406908)). +- The [`worker-src`](/en-US/docs/Web/HTTP/Reference/Headers/Content-Security-Policy/worker-src) CSP directive has been implemented ([Firefox bug 1302667](https://bugzil.la/1302667)). +- The [425: Too Early](/en-US/docs/Web/HTTP/Reference/Status/425) status code and related {{httpheader("Early-Data")}} request header are now supported ([Firefox bug 1406908](https://bugzil.la/1406908)). ### Security @@ -173,15 +173,15 @@ _No changes._ - tabs - - [tabs.discard](/en-US/docs/Mozilla/Add-ons/WebExtensions/API/tabs/discard) has been implemented (Bug 1322485) + - [`tabs.discard`](/en-US/docs/Mozilla/Add-ons/WebExtensions/API/tabs/discard) has been implemented (Bug 1322485) - isArticle, isInReaderMode properties of Tab implemented (Bug 1381992) - - [toggleReaderMode](/en-US/docs/Mozilla/Add-ons/WebExtensions/API/tabs/toggleReaderMode)() method implemented (Bug 1381992) + - [`toggleReaderMode()`](/en-US/docs/Mozilla/Add-ons/WebExtensions/API/tabs/toggleReaderMode) method implemented (Bug 1381992) - openInReaderMode option of tabs.created implemented (Bug 1408993) - tabs.onUpdated now notifies when entering/exiting reader mode (Bug 1402921) - theme - - [getCurrent](/en-US/docs/Mozilla/Add-ons/WebExtensions/API/theme/getCurrent)() method to obtain current theme properties (Bug [1349944](https://bugzil.la/1349944)) + - [`getCurrent()`](/en-US/docs/Mozilla/Add-ons/WebExtensions/API/theme/getCurrent) method to obtain current theme properties (Bug [1349944](https://bugzil.la/1349944)) - onUpdated method to receive WebExtension theme updates (Bug [1349944](https://bugzil.la/1349944)) - colors.bookmark_text now supported as alias of colors.toolbar_text (Bug [1412595](https://bugzil.la/1412595)) - colors.toolbar_top_separator, colors.toolbar_bottom_separator and colors.toolbar_vertical_separator implemented (Bug [1347190)](https://bugzil.la/1347190) diff --git a/files/en-us/mozilla/firefox/releases/59/index.md b/files/en-us/mozilla/firefox/releases/59/index.md index c40373939d2f517..ef35a6ea1c07c44 100644 --- a/files/en-us/mozilla/firefox/releases/59/index.md +++ b/files/en-us/mozilla/firefox/releases/59/index.md @@ -20,13 +20,13 @@ This article provides information about the changes in Firefox 59 that will affe ### HTML -- The {{HTMLElement("textarea")}} element's [`autocomplete`](/en-US/docs/Web/HTML/Element/textarea#autocomplete) attribute has been implemented. This lets you enable or disable form auto-fill for the element. +- The {{HTMLElement("textarea")}} element's [`autocomplete`](/en-US/docs/Web/HTML/Reference/Elements/textarea#autocomplete) attribute has been implemented. This lets you enable or disable form auto-fill for the element. ### CSS - The {{cssxref("overscroll-behavior")}} property and its associated longhand properties — {{cssxref("overscroll-behavior-x")}} and {{cssxref("overscroll-behavior-y")}} — have been implemented ([Firefox bug 951793](https://bugzil.la/951793)), and it has been enabled by default on all releases ([Firefox bug 1428879](https://bugzil.la/1428879)). - The behavior of "unusual elements" (elements that aren't rendered purely by CSS box concepts such as replaced elements) when given a {{cssxref("display")}} value of `contents` has been updated as per spec ([Firefox bug 1427292](https://bugzil.la/1427292)). See [Appendix B: Effects of display: contents on Unusual Elements](https://drafts.csswg.org/css-display/#unbox) for exactly what the specified behaviors are. -- {{cssxref("position")}} `sticky` is now supported on appropriate [HTML table](/en-US/docs/Learn_web_development/Core/Structuring_content/HTML_table_basics) parts (e.g. {{htmlelement("th")}} elements) ([Firefox bug 975644](https://bugzil.la/975644)). +- {{cssxref("position")}} `sticky` is now supported on appropriate [HTML table](/en-US/docs/Learn_web_development/Core/Structuring_content/HTML_table_basics) parts (e.g., {{htmlelement("th")}} elements) ([Firefox bug 975644](https://bugzil.la/975644)). - {{cssxref("calc", "calc()")}} is now supported in {{cssxref("&lt;color&gt;")}} values — `rgb()`, `rgba()`, `hsl()`, and `hsla()` ([Firefox bug 984021](https://bugzil.la/984021)). - {{cssxref("calc", "calc()")}} in [media query](/en-US/docs/Web/CSS/CSS_media_queries) values is now supported [Firefox bug 1396057](https://bugzil.la/1396057). - The {{cssxref("@document")}} at-rule has been limited to use only in user and UA sheets ([Firefox bug 1035091](https://bugzil.la/1035091)). @@ -108,7 +108,7 @@ _No changes._ ### HTML -The non-standard `version` parameter of the {{htmlelement("script")}} element's [`type`](/en-US/docs/Web/HTML/Element/script#type) attribute (e.g. `type="application/javascript;version=1.8"`) has been removed ([Firefox bug 1428745](https://bugzil.la/1428745)). +The non-standard `version` parameter of the {{htmlelement("script")}} element's [`type`](/en-US/docs/Web/HTML/Reference/Elements/script/type) attribute (e.g., `type="application/javascript;version=1.8"`) has been removed ([Firefox bug 1428745](https://bugzil.la/1428745)). ### CSS diff --git a/files/en-us/mozilla/firefox/releases/6/index.md b/files/en-us/mozilla/firefox/releases/6/index.md index aa69e591de9701e..c7396dacbbfe6a4 100644 --- a/files/en-us/mozilla/firefox/releases/6/index.md +++ b/files/en-us/mozilla/firefox/releases/6/index.md @@ -15,10 +15,10 @@ Firefox 6, based on Gecko 6.0, was released on August 16, 2011. This article pro - The HTML5 {{ HTMLElement("progress") }} element, which lets you create a progress bar, is now supported. - The parsing of the HTML5 {{ HTMLElement("track") }} element, which specifies text tracks for media elements, is now supported. This element should appear in the DOM now, though its behavior is still not implemented. - The {{ HTMLElement("iframe") }} element is now clipped correctly by its container when the container's corners have been rounded using the {{ cssxref("border-radius") }} property. -- {{ HTMLElement("form") }} elements' text {{ HTMLElement("input") }} fields no longer support the XUL [`maxwidth`](/en-US/docs/XUL/Property/maxwidth) property; this was never intentional, and is in violation of the HTML specification. You should instead use the [`size`](/en-US/docs/Web/HTML/Element/input#size) attribute to set the maximum width of input fields. +- {{ HTMLElement("form") }} elements' text {{ HTMLElement("input") }} fields no longer support the XUL [`maxwidth`](/en-US/docs/XUL/Property/maxwidth) property; this was never intentional, and is in violation of the HTML specification. You should instead use the [`size`](/en-US/docs/Web/HTML/Reference/Elements/input#size) attribute to set the maximum width of input fields. - The {{ HTMLElement("canvas") }} {{ domxref("CanvasRenderingContext2d") }} properties `fillStyle` and `strokeStyle` used to ignore garbage included after a valid color definition; now this is correctly treated as an error. For example, "red blue" as a color used to be treated as "red", when it should have been ignored. - The width and height of {{ HTMLElement("canvas") }} elements can now properly be set to 0px; previously, these were getting arbitrarily set to 300px when you tried to do that. -- Support for the HTML [custom data attributes](/en-US/docs/Web/HTML/Global_attributes/data-*) (`data-*`) has been added. The DOM {{ domxref("HTMLElement/dataset", "dataset") }} property allows to access them. +- Support for the HTML [custom data attributes](/en-US/docs/Web/HTML/Reference/Global_attributes/data-*) (`data-*`) has been added. The DOM {{ domxref("HTMLElement/dataset", "dataset") }} property allows to access them. - When a {{ HTMLElement("textarea") }} element receives focus, the text insertion point is now placed, by default, at the beginning of the text rather than at the end. This makes Firefox's behavior consistent with other browsers. ### CSS @@ -34,7 +34,7 @@ Firefox 6, based on Gecko 6.0, was released on August 16, 2011. This article pro - {{ cssxref("-moz-orient", "-moz-orient") }} - : A new (currently Mozilla-specific) property which lets you control the vertical or horizontal orientation of certain elements (particularly {{ HTMLElement("progress") }}). - {{ cssxref("::-moz-progress-bar") }} - - : A Mozilla-specific pseudo-element that lets you style the area of an {{ HTMLElement("progress") }} element representing the completed portion of a task. + - : A Mozilla-specific pseudo-element that lets you style the area of a {{ HTMLElement("progress") }} element representing the completed portion of a task. #### Other changes @@ -72,7 +72,7 @@ Firefox 6, based on Gecko 6.0, was released on August 16, 2011. This article pro - DOM views, which we never documented, have been removed. This was a bit of implementation detail that was unnecessarily complicating things, so we got rid of it. If you notice this change, you're probably doing something wrong. - The `EventTarget` function [`addEventListener()`](/en-US/docs/XPCOM_Interface_Reference/nsIDOMEventTarget)'s `useCapture` parameter is now optional, as it is in WebKit (and as per the latest version of the specification). - The `mozResponseArrayBuffer` property of the [`XMLHttpRequest`](/en-US/docs/Web/API/XMLHttpRequest) object has been replaced with the `responseType` and `response` properties. -- The {{ domxref("HTMLElement/dataset", "dataset") }} property has been added to the [`HTMLElement`](/en-US/docs/Web/API/HTMLElement) interface allowing access to the [`data-*` global attributes](/en-US/docs/Web/HTML/Global_attributes/data-*) of an element. +- The {{ domxref("HTMLElement/dataset", "dataset") }} property has been added to the [`HTMLElement`](/en-US/docs/Web/API/HTMLElement) interface allowing access to the [`data-*` global attributes](/en-US/docs/Web/HTML/Reference/Global_attributes/data-*) of an element. - The {{ domxref("CustomEvent") }} interface has been implemented. (see [Firefox bug 427537](https://bugzil.la/427537)) - For security reasons, `data:` and `javascript:` URLs no longer inherit the security context of the current page when the user enters them in the location bar; instead, a new, empty, security context is created. This means that script loaded by entering `javascript:` URLs in the location bar no longer has access to DOM methods and the like, for example. These URLs continue to work as before when used by script, however. diff --git a/files/en-us/mozilla/firefox/releases/60/index.md b/files/en-us/mozilla/firefox/releases/60/index.md index 6f190a87056dd26..c2b78fb990a1a98 100644 --- a/files/en-us/mozilla/firefox/releases/60/index.md +++ b/files/en-us/mozilla/firefox/releases/60/index.md @@ -23,7 +23,7 @@ This article provides information about the changes in Firefox 60 that will affe ### HTML -Pressing the Enter key in `designMode` and `contenteditable` now inserts `<div>` elements when the caret is in an inline element or text node which is a child of a block level editing host — instead of inserting `<br>` elements like it used to. If you want to use the old behavior on your app, you can do it with `document.execCommand()`. See [Differences in markup generation](/en-US/docs/Web/HTML/Global_attributes/contenteditable#differences_in_markup_generation) for more details (also see [Firefox bug 1430551](https://bugzil.la/1430551)). +Pressing the Enter key in `designMode` and `contenteditable` now inserts `<div>` elements when the caret is in an inline element or text node which is a child of a block level editing host — instead of inserting `<br>` elements like it used to. If you want to use the old behavior on your app, you can do it with `document.execCommand()`. See [Differences in markup generation](/en-US/docs/Web/HTML/Reference/Global_attributes/contenteditable#differences_in_markup_generation) for more details (also see [Firefox bug 1430551](https://bugzil.la/1430551)). ### CSS @@ -38,7 +38,7 @@ _No changes._ - ECMAScript 2015 modules have been enabled by default in ([Firefox bug 1438139](https://bugzil.la/1438139)). See [ES6 In Depth: Modules](https://hacks.mozilla.org/2015/08/es6-in-depth-modules/) and [ES modules: A cartoon deep dive](https://hacks.mozilla.org/2018/03/es-modules-a-cartoon-deep-dive/) for more information, or consult MDN reference docs: - - [`<script src="main.js" type="module">`](/en-US/docs/Web/HTML/Element/script#type) and [`<script nomodule src="fallback.js">`](/en-US/docs/Web/HTML/Element/script#nomodule) + - [`<script src="main.js" type="module">`](/en-US/docs/Web/HTML/Reference/Elements/script/type) and [`<script nomodule src="fallback.js">`](/en-US/docs/Web/HTML/Reference/Elements/script#nomodule) - [`import`](/en-US/docs/Web/JavaScript/Reference/Statements/import) and [`export`](/en-US/docs/Web/JavaScript/Reference/Statements/export) statements. - The {{jsxref("Array.prototype.values()")}} method has been added again ([Firefox bug 1420101](https://bugzil.la/1420101)). Make sure your code doesn't have any custom implementation of this method. diff --git a/files/en-us/mozilla/firefox/releases/61/index.md b/files/en-us/mozilla/firefox/releases/61/index.md index f63a36bf024c7a5..afbef53c6530f36 100644 --- a/files/en-us/mozilla/firefox/releases/61/index.md +++ b/files/en-us/mozilla/firefox/releases/61/index.md @@ -103,7 +103,7 @@ _No changes._ ### HTTP -- The cookie directive `SameSite` has been implemented. See [Set-Cookie](/en-US/docs/Web/HTTP/Headers/Set-Cookie) and [HTTP cookies](/en-US/docs/Web/HTTP/Cookies) ([Firefox bug 795346](https://bugzil.la/795346)). +- The cookie directive `SameSite` has been implemented. See [Set-Cookie](/en-US/docs/Web/HTTP/Reference/Headers/Set-Cookie) and [HTTP cookies](/en-US/docs/Web/HTTP/Guides/Cookies) ([Firefox bug 795346](https://bugzil.la/795346)). ### Networking @@ -144,7 +144,7 @@ _No changes._ ### SVG -- The deprecated (and never properly implemented) {{domxref("SVGViewElement")}}`.viewTarget` property has been removed ([Firefox bug 1455763](https://bugzil.la/1455763)). +- The deprecated (and never properly implemented) `SVGViewElement.viewTarget` property has been removed ([Firefox bug 1455763](https://bugzil.la/1455763)). - The following deprecated properties have been removed from {{domxref("SVGSVGElement")}} ([Firefox bug 1133172](https://bugzil.la/1133172)): - `pixelUnitToMillimeterX` diff --git a/files/en-us/mozilla/firefox/releases/62/index.md b/files/en-us/mozilla/firefox/releases/62/index.md index 30285ea9eee2698..debde1b8c6ebca5 100644 --- a/files/en-us/mozilla/firefox/releases/62/index.md +++ b/files/en-us/mozilla/firefox/releases/62/index.md @@ -20,7 +20,7 @@ This article provides information about the changes in Firefox 62 that will affe - If the option to "Select an iframe as the currently targeted document" is checked, the icon will appear in the toolbar while the Settings tab is displayed, even if the current page doesn't include any iframes ([Firefox bug 1456069](https://bugzil.la/1456069)). - The [Network Monitor](https://firefox-source-docs.mozilla.org/devtools-user/network_monitor/index.html)'s [Cookies tab](https://firefox-source-docs.mozilla.org/devtools-user/network_monitor/index.html#cookies) now shows the cookie `samesite` attribute ([Firefox bug 1452715](https://bugzil.la/1452715)). - [Responsive design mode](https://firefox-source-docs.mozilla.org/devtools-user/responsive_design_mode/index.html) now works inside container tabs ([Firefox bug 1306975](https://bugzil.la/1306975)). -- When {{Glossary("CORS")}} errors occur and are reported on the console, Firefox now provides a link to the corresponding page in our [CORS error documentation](/en-US/docs/Web/HTTP/CORS/Errors) ([Firefox bug 1475391](https://bugzil.la/1475391)). +- When {{Glossary("CORS")}} errors occur and are reported on the console, Firefox now provides a link to the corresponding page in our [CORS error documentation](/en-US/docs/Web/HTTP/Guides/CORS/Errors) ([Firefox bug 1475391](https://bugzil.la/1475391)). - Create a screenshot of the current page (with an optional filename) from the Console tab ([Firefox bug 1464461](https://bugzil.la/1464461)) using the following command: ```bash @@ -98,7 +98,7 @@ _No changes._ - The `userproximity` and `deviceproximity` events, as well as the `UserProximityEvent` and `DeviceProximityEvent` interfaces, have been disabled by default behind the `device.sensors.proximity.enabled` preference ([Firefox bug 1462308](https://bugzil.la/1462308)). - The `devicelight` event of type `DeviceLightEvent` has been disabled by default behind the `device.sensors.ambientLight.enabled` preference ([Firefox bug 1462308](https://bugzil.la/1462308)). -- The `DOMSubtreeModified` and `DOMAttrModified` [mutation events](/en-US/docs/Web/API/MutationEvent) are no longer thrown when the [`style`](/en-US/docs/Web/HTML/Global_attributes/style) attribute is changed via the CSSOM ([Firefox bug 1460295](https://bugzil.la/1460295). +- The `DOMSubtreeModified` and `DOMAttrModified` [mutation events](/en-US/docs/Web/API/MutationEvent) are no longer thrown when the [`style`](/en-US/docs/Web/HTML/Reference/Global_attributes/style) attribute is changed via the CSSOM ([Firefox bug 1460295](https://bugzil.la/1460295). - Support for {{domxref("CSSStyleDeclaration.getPropertyCSSValue()")}} has been removed ([Firefox bug 1408301](https://bugzil.la/1408301)). - Support for {{domxref("CSSValue")}}, {{domxref("CSSPrimitiveValue")}}, and {{domxref("CSSValueList")}} has been removed ([Firefox bug 1459871](https://bugzil.la/1459871)). - {{domxref("window.getComputedStyle()")}} no longer returns `null` when called on a `Window` which has no presentation ([Firefox bug 1467722](https://bugzil.la/1467722)). diff --git a/files/en-us/mozilla/firefox/releases/63/index.md b/files/en-us/mozilla/firefox/releases/63/index.md index e437d1a4a32f9ea..5e6f71450f85722 100644 --- a/files/en-us/mozilla/firefox/releases/63/index.md +++ b/files/en-us/mozilla/firefox/releases/63/index.md @@ -80,7 +80,7 @@ _No changes._ - The {{DOMxRef("Element.toggleAttribute()")}} method has been implemented ([Firefox bug 1469592](https://bugzil.la/1469592)). - The historical, previously non-standard, {{DOMxRef("Event.returnValue")}} property is now supported for compatibility purposes ([Firefox bug 1452569](https://bugzil.la/1452569)). -- We implemented the {{DOMxRef("Window.event")}} property to improve web compatibility, now that it's become standard ([Firefox bug 218415](https://bugzil.la/218415)). However, due to some web compat issues (e.g. [Firefox bug 1479964](https://bugzil.la/1479964)), this was quickly disabled in non-Nightly channels, hidden behind the `dom.window.event.enabled` pref ([Firefox bug 1493869](https://bugzil.la/1493869)). +- We implemented the {{DOMxRef("Window.event")}} property to improve web compatibility, now that it's become standard ([Firefox bug 218415](https://bugzil.la/218415)). However, due to some web compat issues (e.g., [Firefox bug 1479964](https://bugzil.la/1479964)), this was quickly disabled in non-Nightly channels, hidden behind the `dom.window.event.enabled` pref ([Firefox bug 1493869](https://bugzil.la/1493869)). - To bring Firefox into alignment with Edge and Chrome, the {{DOMxRef("Navigator/platform", "navigator.platform")}} property now returns `"Win32"` even when running on 64-bit Windows ([Firefox bug 1472618](https://bugzil.la/1472618)). - Prior to Firefox 63, links that open new windows that had `rel="noopener"`, as well as calls to {{DOMxRef("Window.open()")}} with the [`noopener`](/en-US/docs/Web/API/Window/open) window feature enabled would default to having all window features disabled so that you had to explicitly re-enable any standard features you wanted. Now, these windows have the same set of features enabled like any other window, and you need to explicitly turn off any you don't want ([Firefox bug 1419960](https://bugzil.la/1419960)). @@ -109,7 +109,7 @@ _No changes._ #### Removals -- The obsolete and non-standard Firefox-only methods {{DOMxRef("Window.back()")}} and {{DOMxRef("Window.forward()")}} have been removed. Please use the {{DOMxRef("History.back", "window.history.back()")}} and {{DOMxRef("History.forward", "window.history.forward()")}} methods instead ([Firefox bug 1479486](https://bugzil.la/1479486)). +- The obsolete and non-standard Firefox-only methods `Window.back()` and `Window.forward()` have been removed. Please use the {{DOMxRef("History.back", "window.history.back()")}} and {{DOMxRef("History.forward", "window.history.forward()")}} methods instead ([Firefox bug 1479486](https://bugzil.la/1479486)). - The {{domxref("URL.createObjectURL_static", "URL.createObjectURL()")}} and {{DOMxRef("URL.revokeObjectURL_static", "URL.revokeObjectURL()")}} methods are no longer available on {{DOMxRef("ServiceWorker")}} instances due to the potential they introduced for memory leaks to occur ([Firefox bug 1264182](https://bugzil.la/1264182)). - Since it was deprecated in the specification anyway, the limited support for Doppler effects on {{DOMxRef("PannerNode")}} has been removed from the Web Audio API. The {{DOMxRef("AudioListener")}} properties `dopplerFactor` and `speedOfSound` have been removed, along with the `PannerNode` method `setVelocity()` ([Firefox bug 1148354](https://bugzil.la/1148354)). @@ -123,7 +123,7 @@ _No changes._ ### Security -- Site favicons are now subject to [Content Security Policy](/en-US/docs/Web/HTTP/CSP) if one is configured for the site ([Firefox bug 1297156](https://bugzil.la/1297156)). +- Site favicons are now subject to [Content Security Policy](/en-US/docs/Web/HTTP/Guides/CSP) if one is configured for the site ([Firefox bug 1297156](https://bugzil.la/1297156)). - CSP `script-src` directive's `'report-sample'` expression now recognized when generating violation reports. This directive indicates that a short sample of where the violation occurred should be included in the report. Previously, Firefox always included this sample ([Firefox bug 1473218](https://bugzil.la/1473218)). - Firefox now uses NSS 3.39 ([Firefox bug 1470914](https://bugzil.la/1470914)). @@ -135,7 +135,7 @@ _No changes._ #### New features -- Marionette now returns a `setWindowRect` [capability](/en-US/docs/Web/WebDriver/Reference/Capabilities) in the `WebDriver:NewSession` response that is true if the browser window can be repositioned and resized, which e.g. is the case for Firefox but not any mobile applications ([Firefox bug 1470659](https://bugzil.la/1470659)). +- Marionette now returns a `setWindowRect` [capability](/en-US/docs/Web/WebDriver/Reference/Capabilities) in the `WebDriver:NewSession` response that is true if the browser window can be repositioned and resized, which e.g., is the case for Firefox but not any mobile applications ([Firefox bug 1470659](https://bugzil.la/1470659)). - Added support for the `unhandledPromptBehavior` capability, which allows to define a specific [prompt behavior](https://w3c.github.io/webdriver/#dfn-user-prompt-handler) of the WebDriver specification ([Firefox bug 1264259](https://bugzil.la/1264259)). - Handling of user prompts has been added to the `WebDriver:ExecuteScript` and `WebDriver:ExecuteAsyncScript` commands ([Firefox bug 1439995](https://bugzil.la/1439995)). @@ -182,7 +182,7 @@ _No changes._ #### Search -- The new {{WebExtAPIRef("search")}} AP[I](/en-US/docs/Mozilla/Add-ons/WebExtensions/API/search) enables you to retrieve the list of installed search engines and perform searches with them ([Firefox bug 1352598](https://bugzil.la/1352598)). +- The new {{WebExtAPIRef("search")}} API enables you to retrieve the list of installed search engines and perform searches with them ([Firefox bug 1352598](https://bugzil.la/1352598)). - {{WebExtAPIRef("topSites.get()")}} now takes an `options` parameter enabling you to set various options for the list of sites returned ([Firefox bug 1445836](https://bugzil.la/1445836)). #### Tabs diff --git a/files/en-us/mozilla/firefox/releases/64/index.md b/files/en-us/mozilla/firefox/releases/64/index.md index 9bd16c3c236e0cc..3af0ba3582a82a1 100644 --- a/files/en-us/mozilla/firefox/releases/64/index.md +++ b/files/en-us/mozilla/firefox/releases/64/index.md @@ -38,13 +38,13 @@ _No changes._ - [CSS Scrollbars](/en-US/docs/Web/CSS/CSS_scrollbars_styling) spec functionality has been enabled by default ([Firefox bug 1492012](https://bugzil.la/1492012)). - Interaction Media Features implemented, including [`pointer:coarse`](/en-US/docs/Web/CSS/@media/pointer) ([Firefox bug 1035774](https://bugzil.la/1035774)). For [`any-pointer`](/en-US/docs/Web/CSS/@media/any-pointer) and [`any-hover`](/en-US/docs/Web/CSS/@media/any-hover) implementation, see [Firefox bug 1483111](https://bugzil.la/1483111). - The [`prefers-reduced-motion`](/en-US/docs/Web/CSS/@media/prefers-reduced-motion) media feature is now supported in Firefox for Android ([Firefox bug 1478505](https://bugzil.la/1478505)). -- CSS {{cssxref("&lt;gradient&gt;")}} values now support multi-position color stop syntax, e.g. `yellow 25%, yellow 50%` can now be written `yellow 25% 50%` ([Firefox bug 1352643](https://bugzil.la/1352643)). +- CSS {{cssxref("&lt;gradient&gt;")}} values now support multi-position color stop syntax, e.g., `yellow 25%, yellow 50%` can now be written `yellow 25% 50%` ([Firefox bug 1352643](https://bugzil.la/1352643)). - The {{cssxref("text-transform")}} property now accepts the `full-size-kana` value ([Firefox bug 1498148](https://bugzil.la/1498148)). - Support added for {{cssxref("appearance", "-webkit-appearance")}} to alleviate associated web compat issues ([Firefox bug 1368555](https://bugzil.la/1368555)). - Closely associated with the above update, we've also removed most of the Firefox-specific `-moz-appearance` values ([Firefox bug 1496720](https://bugzil.la/1496720)). - {{cssxref("display")}}: `list-item` is now supported on {{htmlelement("legend")}} elements ([Firefox bug 1486602](https://bugzil.la/1486602)). - SVG `path()`s, as usable in {{cssxref("offset-path")}}, are now animatable ([Firefox bug 1486094](https://bugzil.la/1486094)). -- If a selector chain or group includes a `-webkit-`prefixed pseudo-element, that pseudo-element no longer invalidates it (see [Firefox bug 1424106](https://bugzil.la/1424106) for the details, and [Firefox bug 1486325](https://bugzil.la/1486325) for enabling this feature). +- If a selector chain or group includes a `-webkit-`-prefixed pseudo-element, that pseudo-element no longer invalidates it (see [Firefox bug 1424106](https://bugzil.la/1424106) for the details, and [Firefox bug 1486325](https://bugzil.la/1486325) for enabling this feature). #### Removals @@ -60,7 +60,7 @@ _No changes._ ### JavaScript - The TC39 [Well-formed JSON.stringify](https://github.com/tc39/proposal-well-formed-stringify) proposal has been implemented, to prevent {{jsxref("JSON.stringify")}} from returning ill-formed Unicode strings ([Firefox bug 1469021](https://bugzil.la/1469021)). -- Proxied functions can now be passed to {{jsxref("Function.prototype.toString")}}`.call()` ([Firefox bug 1440468](https://bugzil.la/1440468)). +- Proxied functions can now be used with {{jsxref("Function.prototype.toString")}} ([Firefox bug 1440468](https://bugzil.la/1440468)). - In the [`WebAssembly.Global()`](/en-US/docs/WebAssembly/Reference/JavaScript_interface/Global) constructor, if no value is specified a typed 0 value is used. This is specified by the [`DefaultValue` algorithm](https://webassembly.github.io/spec/js-api/#defaultvalue) ([Firefox bug 1490286](https://bugzil.la/1490286)). ### APIs @@ -104,7 +104,7 @@ _No changes._ ### Security - The Symantec CA Distrust plan has been implemented (see [Firefox bug 1409257](https://bugzil.la/1409257); see also the [Mozilla's Plan for Symantec Roots](https://groups.google.com/forum/#!topic/mozilla.dev.security.policy/FLHRT79e3XE/discussion) discussion for more details). -- {{httpheader("Referrer-Policy")}} can now be used to govern resources fetched via stylesheets ([Firefox bug 1330487](https://bugzil.la/1330487)) — see [Integration with CSS](/en-US/docs/Web/HTTP/Headers/Referrer-Policy#integration_with_css) for more information. +- {{httpheader("Referrer-Policy")}} can now be used to govern resources fetched via stylesheets ([Firefox bug 1330487](https://bugzil.la/1330487)) — see [Integration with CSS](/en-US/docs/Web/HTTP/Reference/Headers/Referrer-Policy#integration_with_css) for more information. ### Plugins @@ -129,11 +129,11 @@ _No changes._ #### Menus -- A new API, `{{WebExtAPIRef("menus.overrideContext()")}}`, can be called from the `contextmenu` DOM event to set a custom context menu in extension pages. This API allows extensions to hide all default Firefox menu items in favor of providing a custom context menu UI. This context menu can consist of multiple top-level menu items from the extension, and may optionally include tab or bookmark context menu items from other extensions. See [this blog post](https://blog.mozilla.org/addons/2018/11/08/extensions-in-firefox-64/#cm) for more details. +- A new API, {{WebExtAPIRef("menus.overrideContext()")}}, can be called from the `contextmenu` DOM event to set a custom context menu in extension pages. This API allows extensions to hide all default Firefox menu items in favor of providing a custom context menu UI. This context menu can consist of multiple top-level menu items from the extension, and may optionally include tab or bookmark context menu items from other extensions. See [this blog post](https://blog.mozilla.org/addons/2018/11/08/extensions-in-firefox-64/#cm) for more details. - - `{{WebExtAPIRef("menus.overrideContext()")}}` was implemented in ([Firefox bug 1280347](https://bugzil.la/1280347)). + - {{WebExtAPIRef("menus.overrideContext()")}} was implemented in ([Firefox bug 1280347](https://bugzil.la/1280347)). - The `showDefaults: false` option, which can be used to hide the default context menu options, was implemented in ([Firefox bug 1367160](https://bugzil.la/1367160)). - - `documentURLPatterns` can now be used to match a `moz-extension://` document URL, even if `{{WebExtAPIRef("menus.overrideContext()")}}` is used. This way, it can reliably be used to restrict custom menu items to certain documents ([Firefox bug 1498896](https://bugzil.la/1498896)). + - `documentURLPatterns` can now be used to match a `moz-extension://` document URL, even if {{WebExtAPIRef("menus.overrideContext()")}} is used. This way, it can reliably be used to restrict custom menu items to certain documents ([Firefox bug 1498896](https://bugzil.la/1498896)). - You can now restrict where context menus can appear in an add-on using the new `viewTypes` property in {{WebExtAPIRef("menus.create()")}} and {{WebExtAPIRef("menus.update()")}} ([Firefox bug 1416839](https://bugzil.la/1416839)). - {{WebExtAPIRef("menus.update()")}} can now be used to update the icon of an existing menu item ([Firefox bug 1414566](https://bugzil.la/1414566)). diff --git a/files/en-us/mozilla/firefox/releases/65/index.md b/files/en-us/mozilla/firefox/releases/65/index.md index 9b78a9a84f49a76..3a968e35bea13d6 100644 --- a/files/en-us/mozilla/firefox/releases/65/index.md +++ b/files/en-us/mozilla/firefox/releases/65/index.md @@ -15,18 +15,18 @@ This article provides information about the changes in Firefox 65 that will affe - The [Flexbox inspector](https://firefox-source-docs.mozilla.org/devtools-user/page_inspector/how_to/examine_flexbox_layouts/index.html) is now enabled by default. - Support has been added to the [JavaScript Debugger](https://firefox-source-docs.mozilla.org/devtools-user/debugger/index.html) for XHR Breakpoints ([Firefox bug 821610](https://bugzil.la/821610)). - Right-click on an item in the accessibility tree from the Accessibility viewer to [print it as JSON](https://firefox-source-docs.mozilla.org/devtools-user/accessibility_inspector/index.html#print-accessibility-tree-to-json) to the JSON viewer. -- The [color contrast](https://firefox-source-docs.mozilla.org/devtools-user/accessibility_inspector/index.html#color-contrast) display of the Accessibility Picker has been updated so that if a text's background is complex (e.g. a gradient or complex image), it shows a range of color contrast values. +- The [color contrast](https://firefox-source-docs.mozilla.org/devtools-user/accessibility_inspector/index.html#color-contrast) display of the Accessibility Picker has been updated so that if a text's background is complex (e.g., a gradient or complex image), it shows a range of color contrast values. - The Headers tab of the [Network Monitor](https://firefox-source-docs.mozilla.org/devtools-user/network_monitor/index.html) now displays the Referrer Policy for the selected request ([Firefox bug 1496742](https://bugzil.la/1496742)). -- When displaying stack traces (e.g. in console logs or the JavaScript debugger), calls to framework methods are identified and collapsed by default, making it easier to home in on your code. +- When displaying stack traces (e.g., in console logs or the JavaScript debugger), calls to framework methods are identified and collapsed by default, making it easier to home in on your code. - In the same fashion as native terminals, you can now use reverse search to find entries in your JavaScript console history (`F9` on Windows/Linux or `Ctrl` + `R` on macOS, then type a search term, followed by `Ctrl` + `R`/`Ctrl` + `S` to toggle through results). - The JavaScript console's `$0` shortcut (references the currently inspected element on the page) now has autocomplete available, so for example you could type `$0.te` to get autocomplete suggestions for properties like `$0.textContent`. - The edits you make in the Rules view of the Inspector are now listed in the Changes panel ([Firefox bug 1503920](https://bugzil.la/1503920)). ### HTML -- Events are now dispatched on disabled HTML elements, i.e. {{htmlelement("button")}}, {{htmlelement("fieldset")}}, {{htmlelement("input")}}, {{htmlelement("select")}}, and {{htmlelement("textarea")}} elements with `disabled` attributes set on them ([Firefox bug 329509](https://bugzil.la/329509)). +- Events are now dispatched on disabled HTML elements, i.e., {{htmlelement("button")}}, {{htmlelement("fieldset")}}, {{htmlelement("input")}}, {{htmlelement("select")}}, and {{htmlelement("textarea")}} elements with `disabled` attributes set on them ([Firefox bug 329509](https://bugzil.la/329509)). - Removing the `src` attribute of an {{htmlelement("iframe")}} element now causes `about:blank` to be loaded into it, giving it parity with Chrome and Safari ([Firefox bug 1507842](https://bugzil.la/1507842)). Previously removing `src` had no effect on the `iframe` content. -- We have added support for the [`referrerpolicy`](/en-US/docs/Web/HTML/Element/script#referrerpolicy) attribute on {{htmlelement("script")}} elements ([Firefox bug 1460920](https://bugzil.la/1460920)). +- We have added support for the [`referrerpolicy`](/en-US/docs/Web/HTML/Reference/Elements/script#referrerpolicy) attribute on {{htmlelement("script")}} elements ([Firefox bug 1460920](https://bugzil.la/1460920)). ### CSS @@ -107,7 +107,7 @@ _No changes._ #### Fetch and Service workers - The {{domxref("Response.redirect_static", "Response.redirect()")}} method now correctly throws a `TypeError` if a non-valid URL is specified as the first parameter ([Firefox bug 1503276](https://bugzil.la/1503276)). -- The {{domxref("ServiceWorkerContainer.register()")}} and {{domxref("WorkerGlobalScope.importScripts()")}} (when used by a service worker) methods will now accept any files with a valid [JavaScript MIME type](/en-US/docs/Web/HTTP/MIME_types#textjavascript) ([Firefox bug 1354577](https://bugzil.la/1354577)). +- The {{domxref("ServiceWorkerContainer.register()")}} and {{domxref("WorkerGlobalScope.importScripts()")}} (when used by a service worker) methods will now accept any files with a valid [JavaScript MIME type](/en-US/docs/Web/HTTP/Guides/MIME_types#textjavascript) ([Firefox bug 1354577](https://bugzil.la/1354577)). - The {{domxref("FetchEvent.replacesClientId")}} and {{domxref("FetchEvent.resultingClientId")}} properties are now supported ([Firefox bug 1264177](https://bugzil.la/1264177)). - The {{domxref("ServiceWorkerGlobalScope.messageerror_event", "ServiceWorkerGlobalScope.onmessageerror")}} and {{domxref("ServiceWorkerContainer.messageerror_event", "ServiceWorkerContainer.onmessageerror")}} handler properties have been implemented ([Firefox bug 1399446](https://bugzil.la/1399446)). - The {{httpheader("Origin")}} header is no longer set on Fetch requests with a method of {{HTTPMethod("HEAD")}} or {{HTTPMethod("GET")}} ([Firefox bug 1508661](https://bugzil.la/1508661)). diff --git a/files/en-us/mozilla/firefox/releases/66/index.md b/files/en-us/mozilla/firefox/releases/66/index.md index 8185654c5c21365..3a080010eb77149 100644 --- a/files/en-us/mozilla/firefox/releases/66/index.md +++ b/files/en-us/mozilla/firefox/releases/66/index.md @@ -22,7 +22,7 @@ This article provides information about the changes in Firefox 66 that will affe #### Removals -- The `x-moz-errormessage` attribute has been removed from the {{HTMLElement("input")}} element ([Firefox bug 1513890](https://bugzil.la/1513890)). You should use the [constraint validation](/en-US/docs/Web/HTML/Constraint_validation) API to implement custom validation messages instead. +- The `x-moz-errormessage` attribute has been removed from the {{HTMLElement("input")}} element ([Firefox bug 1513890](https://bugzil.la/1513890)). You should use the [constraint validation](/en-US/docs/Web/HTML/Guides/Constraint_validation) API to implement custom validation messages instead. ### CSS diff --git a/files/en-us/mozilla/firefox/releases/67/index.md b/files/en-us/mozilla/firefox/releases/67/index.md index 84a4b01e2484a61..ce4e39bccff031e 100644 --- a/files/en-us/mozilla/firefox/releases/67/index.md +++ b/files/en-us/mozilla/firefox/releases/67/index.md @@ -83,7 +83,7 @@ _No changes._ #### DOM events -- CSS transition ([Firefox bug 1530239](https://bugzil.la/1530239)) and animation ([Firefox bug 1531605](https://bugzil.la/1531605)) events now fire on disabled (e.g. form) elements. +- CSS transition ([Firefox bug 1530239](https://bugzil.la/1530239)) and animation ([Firefox bug 1531605](https://bugzil.la/1531605)) events now fire on disabled (e.g., form) elements. - {{domxref("InputEvent.data")}} and {{domxref("InputEvent.dataTransfer")}} have been implemented ([Firefox bug 998941](https://bugzil.la/998941)). - The `insertFromPasteAsQuotation` {{domxref("InputEvent.inputType")}} value is now supported ([Firefox bug 1532527](https://bugzil.la/1532527)). @@ -133,7 +133,7 @@ _No changes._ ### API changes -- Using the `proxy.settings.set()` method to change `{{WebExtAPIRef("types.BrowserSetting", "BrowserSetting")}}` values will throw an exception unless the extension was granted private window access by the user ([Firefox bug 1525447](https://bugzil.la/1525447)). +- Using the `proxy.settings.set()` method to change {{WebExtAPIRef("types.BrowserSetting", "BrowserSetting")}} values will throw an exception unless the extension was granted private window access by the user ([Firefox bug 1525447](https://bugzil.la/1525447)). ### Manifest changes diff --git a/files/en-us/mozilla/firefox/releases/68/index.md b/files/en-us/mozilla/firefox/releases/68/index.md index 28259c52b69f901..8f872d1ca4f6120 100644 --- a/files/en-us/mozilla/firefox/releases/68/index.md +++ b/files/en-us/mozilla/firefox/releases/68/index.md @@ -55,7 +55,7 @@ This article provides information about the changes in Firefox 68 that will affe #### Removals -- [`<meta http-equiv="set-cookie">`](/en-US/docs/Web/HTML/Element/meta) is no longer supported ([Firefox bug 1457503](https://bugzil.la/1457503)). +- [`<meta http-equiv="set-cookie">`](/en-US/docs/Web/HTML/Reference/Elements/meta) is no longer supported ([Firefox bug 1457503](https://bugzil.la/1457503)). ### CSS @@ -72,7 +72,7 @@ This article provides information about the changes in Firefox 68 that will affe - The {{CSSxRef("counter-set")}} property has been implemented. ([Firefox bug 1518201](https://bugzil.la/1518201)). - We now implement list numbering using a built-in "list-item" counter; this fixes list numbering bugs ([Firefox bug 288704](https://bugzil.la/288704)). - Selector matching and parsing support has been implemented for [`::part()`](/en-US/docs/Web/CSS/::part) ([Firefox bug 1545430](https://bugzil.la/1545430)) and ([Firefox bug 1545425](https://bugzil.la/1545425)). -- [CSS Transforms](/en-US/docs/Web/CSS/CSS_transforms) are now supported in indirectly rendered things e.g. {{SVGElement("mask")}}, {{SVGElement("marker")}}, {{SVGElement("pattern")}}, {{SVGElement("clipPath")}} ([Firefox bug 1323962](https://bugzil.la/1323962)). +- [CSS Transforms](/en-US/docs/Web/CSS/CSS_transforms) are now supported in indirectly rendered things e.g., {{SVGElement("mask")}}, {{SVGElement("marker")}}, {{SVGElement("pattern")}}, {{SVGElement("clipPath")}} ([Firefox bug 1323962](https://bugzil.la/1323962)). - While we're keeping the prefixed versions of the various gradient properties {{cssxref("gradient/linear-gradient")}}, {{cssxref("gradient/radial-gradient")}}, and {{cssxref("gradient/repeating-radial-gradient")}} available for compatibility reasons, we have revised how they're parsed so that they're handled much more like the non-prefixed versions. This means that certain existing styles won't work correctly. In particular, the complicated syntax taking both an angle and a position will no longer work, and the `to` keyword in the `<side-or-corner>` parameter is not required for the prefixed gradient properties. You are encouraged to use the standard, non-prefixed gradient properties instead, as they're now widely supported ([Firefox bug 1547939](https://bugzil.la/1547939)). diff --git a/files/en-us/mozilla/firefox/releases/69/index.md b/files/en-us/mozilla/firefox/releases/69/index.md index 1b89e565ba8e639..34b52c833d82152 100644 --- a/files/en-us/mozilla/firefox/releases/69/index.md +++ b/files/en-us/mozilla/firefox/releases/69/index.md @@ -21,14 +21,14 @@ This article provides information about the changes in Firefox 69 that will affe #### Console -- [Browser Console](https://firefox-source-docs.mozilla.org/devtools-user/browser_console/index.html) messages from [tracking protection errors](/en-US/docs/Web/Privacy/Guides/Firefox_tracking_protection), [CSP errors](/en-US/docs/Web/HTTP/CSP), and [CORS errors](/en-US/docs/Web/HTTP/CORS/Errors) are grouped automatically to reduce noise from repeated blocked resources and storage access ([Firefox bug 1522396](https://bugzil.la/1522396)). +- [Browser Console](https://firefox-source-docs.mozilla.org/devtools-user/browser_console/index.html) messages from [tracking protection errors](/en-US/docs/Web/Privacy/Guides/Firefox_tracking_protection), [CSP errors](/en-US/docs/Web/HTTP/Guides/CSP), and [CORS errors](/en-US/docs/Web/HTTP/Guides/CORS/Errors) are grouped automatically to reduce noise from repeated blocked resources and storage access ([Firefox bug 1522396](https://bugzil.la/1522396)). - All visible logs in the console can shared by saving to a file or copying to clipboard via a new _Export visible messages to_ context menu item ([Firefox bug 1517728](https://bugzil.la/1517728)). - The console's toolbar now responsively reduces its height into a single row to save vertical space ([Firefox bug 972530](https://bugzil.la/972530)). - Messages from content can now be hidden in the console to focus on logs from the Firefox UI ([Firefox bug 1523842](https://bugzil.la/1523842)). #### Network -- Resources that got blocked because of [CSP](/en-US/docs/Web/HTTP/CSP) or [Mixed Content](/en-US/docs/Web/Security/Mixed_content) are now shown in the Network panel, with details of the reason ([Firefox bug 1556451](https://bugzil.la/1556451)). +- Resources that got blocked because of [CSP](/en-US/docs/Web/HTTP/Guides/CSP) or [Mixed Content](/en-US/docs/Web/Security/Mixed_content) are now shown in the Network panel, with details of the reason ([Firefox bug 1556451](https://bugzil.la/1556451)). - A new optional _URL_ column in the Network panel can be enabled to show the full URL for resources ([Firefox bug 1341155](https://bugzil.la/1341155)). #### Inspector @@ -77,7 +77,7 @@ This article provides information about the changes in Firefox 69 that will affe ### HTTP -- The HTTP headers {{HTTPHeader("Access-Control-Expose-Headers")}}, {{HTTPHeader("Access-Control-Allow-Methods")}}, and {{HTTPHeader("Access-Control-Allow-Headers")}} now accept a wildcard value "`*`" for requests without credentials ([Firefox bug 1309358](https://bugzil.la/1309358)). This change has also been uplifted to Firefox 68 ESR. +- The HTTP headers {{HTTPHeader("Access-Control-Expose-Headers")}}, {{HTTPHeader("Access-Control-Allow-Methods")}}, and {{HTTPHeader("Access-Control-Allow-Headers")}} now accept a wildcard value `*` for requests without credentials ([Firefox bug 1309358](https://bugzil.la/1309358)). This change has also been uplifted to Firefox 68 ESR. ### APIs diff --git a/files/en-us/mozilla/firefox/releases/7/index.md b/files/en-us/mozilla/firefox/releases/7/index.md index e9086ddc206246a..8690e2b0c019c5a 100644 --- a/files/en-us/mozilla/firefox/releases/7/index.md +++ b/files/en-us/mozilla/firefox/releases/7/index.md @@ -15,8 +15,8 @@ Firefox 7 shipped on September 27, 2011. This article provides information about - The {{ domxref("HTMLHeadElement") }} `profile` property has been removed, this property has been deprecated since Gecko 2.0. - The {{ domxref("HTMLImageElement") }} `x` and `y` properties have been removed. - The {{ domxref("HTMLSelectElement") }} `add()` method `before` parameter is now optional. -- The {{ HTMLElement("body") }} element's [`background`](/en-US/docs/Web/HTML/Element/body#background) attribute is no longer resolved as a URI; this is in compliance with the current HTML specification. -- The {{ HTMLElement("option") }} element's [`label`](/en-US/docs/Web/HTML/Element/option#label) attribute now reflects the value of the element's text content if the attribute isn't specified. +- The {{ HTMLElement("body") }} element's [`background`](/en-US/docs/Web/HTML/Reference/Elements/body#background) attribute is no longer resolved as a URI; this is in compliance with the current HTML specification. +- The {{ HTMLElement("option") }} element's [`label`](/en-US/docs/Web/HTML/Reference/Elements/option#label) attribute now reflects the value of the element's text content if the attribute isn't specified. #### Canvas @@ -45,7 +45,7 @@ Firefox 7 shipped on September 27, 2011. This article provides information about - The top-level {{ MathMLElement("math") }} element now accepts any attributes of the {{ MathMLElement("mstyle") }} element. - Support for [Asana Math](https://www.ctan.org/tex-archive/fonts/Asana-Math/) fonts has been added. - The `medium` line thickness of fraction bars in {{ MathMLElement("mfrac") }} elements has been corrected to match the default thickness. -- [Names for negative spaces](</en-US/docs/Web/MathML/Values#constants_(namedspaces)>) are now supported. +- [Names for negative spaces](</en-US/docs/Web/MathML/Reference/Values#constants_(namedspaces)>) are now supported. ### DOM diff --git a/files/en-us/mozilla/firefox/releases/70/index.md b/files/en-us/mozilla/firefox/releases/70/index.md index 53b67413b1ab8f6..04f1f5e0ca0c912 100644 --- a/files/en-us/mozilla/firefox/releases/70/index.md +++ b/files/en-us/mozilla/firefox/releases/70/index.md @@ -17,7 +17,7 @@ This article provides information about the changes in Firefox 70 that will affe - In the [Debugger](https://firefox-source-docs.mozilla.org/devtools-user/debugger/index.html) you can now set breakpoints for [DOM Mutation](https://firefox-source-docs.mozilla.org/devtools-user/debugger/break_on_dom_mutation/index.html), so execution will pause when a node or its attributes are changed or when a node is removed from the DOM ([Firefox bug 1576219](https://bugzil.la/1576219)). - The Debugger now shows an overlay on the page when it is paused, with basic stepping buttons to let you step and continue ([Firefox bug 1574646](https://bugzil.la/1574646)). - The Debugger now shows sources that already got discarded by the engine (usually scripts that execute once during page load), so you can properly set breakpoints to debug when they execute next ([Firefox bug 1572280](https://bugzil.la/1572280)). -- The Debugger's [scopes panel](https://firefox-source-docs.mozilla.org/devtools-user/debugger/using_the_debugger_map_scopes_feature/index.html) grouping has been simplified, consolidating additional scopes previously shown above the top level function (e.g. blocks created by [`let`](/en-US/docs/Web/JavaScript/Reference/Statements/let), [`with`](/en-US/docs/Web/JavaScript/Reference/Statements/with), or [`if`/`else`](/en-US/docs/Web/JavaScript/Reference/Statements/if...else)) ([Firefox bug 1448166](https://bugzil.la/1448166)) +- The Debugger's [scopes panel](https://firefox-source-docs.mozilla.org/devtools-user/debugger/using_the_debugger_map_scopes_feature/index.html) grouping has been simplified, consolidating additional scopes previously shown above the top level function (e.g., blocks created by [`let`](/en-US/docs/Web/JavaScript/Reference/Statements/let), [`with`](/en-US/docs/Web/JavaScript/Reference/Statements/with), or [`if`/`else`](/en-US/docs/Web/JavaScript/Reference/Statements/if...else)) ([Firefox bug 1448166](https://bugzil.la/1448166)) - The Debugger now retains the currently selected and expanded variables in the [scopes panel](https://firefox-source-docs.mozilla.org/devtools-user/debugger/using_the_debugger_map_scopes_feature/index.html) while stepping ([Firefox bug 1405402](https://bugzil.la/1405402)). - The Debugger now handles stepping over async functions correctly, making [asynchronous function](/en-US/docs/Web/JavaScript/Reference/Statements/async_function) debugging easier ([Firefox bug 1570178](https://bugzil.la/1570178)). - When debugging in [Container sessions](https://support.mozilla.org/en-US/kb/containers) (useful for testing different logins), the sources in the debugger are now shown correctly ([Firefox bug 1375036](https://bugzil.la/1375036)). @@ -74,7 +74,7 @@ This article provides information about the changes in Firefox 70 that will affe - [Numeric separators](/en-US/docs/Web/JavaScript/Reference/Lexical_grammar#numeric_separators) are now supported ([Firefox bug 1435818](https://bugzil.la/1435818)). - The {{jsxref("Intl/RelativeTimeFormat/formatToParts", "Intl.RelativeTimeFormat.formatToParts()")}} method has been implemented ([Firefox bug 1473229](https://bugzil.la/1473229)). - The {{jsxref("BigInt.prototype.toLocaleString()")}} method has been updated to work with the `locales` and `options` parameters per the ECMAScript 402 Intl API. Also, {{jsxref("Intl/NumberFormat/format", "Intl.NumberFormat.format()")}} and {{jsxref("Intl/NumberFormat/formatToParts", "Intl.NumberFormat.formatToParts()")}} now accept {{jsxref("BigInt")}} values ([Firefox bug 1543677](https://bugzil.la/1543677)). -- Per the latest ECMAScript specification, a leading zero is now never allowed for [BigInt literals](/en-US/docs/Web/JavaScript/Reference/Lexical_grammar#bigint_literal), making `08n` and `09n` invalid similar to the existing error when legacy octal numbers like `07n` are used. Always use a leading zero with the letter "o" (lowercase or uppercase) for octal `BigInt` numbers (i.e. `0o755n` instead of `0755n`). See [Firefox bug 1568619](https://bugzil.la/1568619). +- Per the latest ECMAScript specification, a leading zero is now never allowed for [BigInt literals](/en-US/docs/Web/JavaScript/Reference/Lexical_grammar#bigint_literal), making `08n` and `09n` invalid similar to the existing error when legacy octal numbers like `07n` are used. Always use a leading zero with the letter "o" (lowercase or uppercase) for octal `BigInt` numbers (i.e., `0o755n` instead of `0755n`). See [Firefox bug 1568619](https://bugzil.la/1568619). - The Unicode extension key "nu" is now supported for the {{jsxref("Intl/RelativeTimeFormat", "Intl.RelativeTimeFormat")}} constructor and the {{jsxref("Intl/RelativeTimeFormat/resolvedOptions", "Intl.RelativeTimeFormat.resolvedOptions()")}} method now also returns `numberingSystem` ([Firefox bug 1521819](https://bugzil.la/1521819)). ### APIs @@ -106,7 +106,7 @@ This article provides information about the changes in Firefox 70 that will affe - The default referrer policy for third-party tracking resources is now `strict-origin-when-cross-origin` when [Enhanced Tracking Protection](/en-US/docs/Web/Privacy/Guides/Firefox_tracking_protection) is turned on ([Firefox bug 1569996](https://bugzil.la/1569996)). - The size of the {{httpheader("Referer")}} request header is now limited to 4 KB (4,096 bytes). If an overly long referer exceeds the defined limit, only the origin part will be sent ([Firefox bug 1557346](https://bugzil.la/1557346)). -- The [HTTP cache](/en-US/docs/Web/HTTP/Caching) is now partitioned per the top-level document's origin ([Firefox bug 1536058](https://bugzil.la/1536058)). +- The [HTTP cache](/en-US/docs/Web/HTTP/Guides/Caching) is now partitioned per the top-level document's origin ([Firefox bug 1536058](https://bugzil.la/1536058)). #### Removals diff --git a/files/en-us/mozilla/firefox/releases/71/index.md b/files/en-us/mozilla/firefox/releases/71/index.md index b19a7760262e681..e785e98e370e1fd 100644 --- a/files/en-us/mozilla/firefox/releases/71/index.md +++ b/files/en-us/mozilla/firefox/releases/71/index.md @@ -59,7 +59,7 @@ This article provides information about the changes in Firefox 71 that will affe ### MathML -- [MathML elements](/en-US/docs/Web/MathML/Element) now implement a MathML DOM and their class is {{domxref("MathMLElement")}}. With a proper MathML DOM, you can now use `mathmlEl.style`, or global event handlers, for example. Prior to this change, MathML elements only implemented the {{domxref("Element")}} class ([Firefox bug 1571487](https://bugzil.la/1571487)). +- [MathML elements](/en-US/docs/Web/MathML/Reference/Element) now implement a MathML DOM and their class is {{domxref("MathMLElement")}}. With a proper MathML DOM, you can now use `mathmlEl.style`, or global event handlers, for example. Prior to this change, MathML elements only implemented the {{domxref("Element")}} class ([Firefox bug 1571487](https://bugzil.la/1571487)). ### APIs diff --git a/files/en-us/mozilla/firefox/releases/72/index.md b/files/en-us/mozilla/firefox/releases/72/index.md index b239ee71628e876..bb5f28f2d3cf284 100644 --- a/files/en-us/mozilla/firefox/releases/72/index.md +++ b/files/en-us/mozilla/firefox/releases/72/index.md @@ -39,7 +39,7 @@ _No changes._ ### CSS -- CSS Shadow Parts are now enabled. This includes the [`part` attribute](/en-US/docs/Web/HTML/Global_attributes/part) and [`::part` pseudo-element](/en-US/docs/Web/CSS/::part), which allow shadow hosts to selectively expose chosen elements from their shadow tree to the outside page for styling purposes ([Firefox bug 1559074](https://bugzil.la/1559074)). +- CSS Shadow Parts are now enabled. This includes the [`part` attribute](/en-US/docs/Web/HTML/Reference/Global_attributes/part) and [`::part` pseudo-element](/en-US/docs/Web/CSS/::part), which allow shadow hosts to selectively expose chosen elements from their shadow tree to the outside page for styling purposes ([Firefox bug 1559074](https://bugzil.la/1559074)). - [CSS Motion Path](/en-US/docs/Web/CSS/CSS_motion_path) has been shipped ([Firefox bug 1582554](https://bugzil.la/1582554), also see the [Intent to Ship](https://groups.google.com/forum/#!topic/mozilla.dev.platform/nOOIRsuxvuc)). This includes: - {{cssxref("offset")}} @@ -98,7 +98,7 @@ _No changes._ - Removed the non-standard `window.mozPaintCount` property. ([Firefox bug 1591968](https://bugzil.la/1591968)) - The {{domxref("BatteryManager")}} interface is no longer exposed to web content ([Firefox bug 1441976](https://bugzil.la/1441976)). - {{domxref("Navigator.vibrate()")}} is no longer supported in cross-origin {{htmlelement("iframe")}}s ([Firefox bug 1591113](https://bugzil.la/1591113)). -- WebRTC no longer supports the `rid=` and `pt=` parameters on the `simulcast` attribute. The new syntax for a line such as "`a=simulcast: send rid=7 recv rid=8`" is now "`a=simulcast: send 7 recv 8`". The new syntax has been supported since Firefox 68, so now it's time tor retire support for the old syntax ([Firefox bug 1470568](https://bugzil.la/1470568)). +- WebRTC no longer supports the `rid=` and `pt=` parameters on the `simulcast` attribute. The new syntax for a line such as `a=simulcast: send rid=7 recv rid=8` is now `a=simulcast: send 7 recv 8`. The new syntax has been supported since Firefox 68, so now it's time tor retire support for the old syntax ([Firefox bug 1470568](https://bugzil.la/1470568)). ### Security diff --git a/files/en-us/mozilla/firefox/releases/73/index.md b/files/en-us/mozilla/firefox/releases/73/index.md index 260914bfc5507fa..eaee003c65356ec 100644 --- a/files/en-us/mozilla/firefox/releases/73/index.md +++ b/files/en-us/mozilla/firefox/releases/73/index.md @@ -12,7 +12,7 @@ This article provides information about the changes in Firefox 73 that will affe ### Developer tools -- [CORS errors](/en-US/docs/Web/HTTP/CORS/Errors) now appear as errors in the console (and no longer as warnings) giving them the appropriate visibility ([Firefox bug 1602093](https://bugzil.la/1602093)). +- [CORS errors](/en-US/docs/Web/HTTP/Guides/CORS/Errors) now appear as errors in the console (and no longer as warnings) giving them the appropriate visibility ([Firefox bug 1602093](https://bugzil.la/1602093)). - Text and regular expression searches in the web console [can now be negated by prefixing them with '-'](https://firefox-source-docs.mozilla.org/devtools-user/web_console/console_messages/index.html#filtering-and-searching) ([Firefox bug 1291192](https://bugzil.la/1291192)). ### HTML diff --git a/files/en-us/mozilla/firefox/releases/74/index.md b/files/en-us/mozilla/firefox/releases/74/index.md index fbea1fc1f10d57d..87414aaaa706b48 100644 --- a/files/en-us/mozilla/firefox/releases/74/index.md +++ b/files/en-us/mozilla/firefox/releases/74/index.md @@ -68,12 +68,12 @@ _No changes._ ### HTTP -- The [`Cross-Origin-Resource-Policy`](/en-US/docs/Web/HTTP/Headers/Cross-Origin-Resource-Policy) header is now enabled by default ([bug 1602363](https://bugzil.la/1602363)). +- The [`Cross-Origin-Resource-Policy`](/en-US/docs/Web/HTTP/Reference/Headers/Cross-Origin-Resource-Policy) header is now enabled by default ([bug 1602363](https://bugzil.la/1602363)). ### Security - TLS 1.0 and 1.1 support has been removed from Firefox; you'll need to make sure your web server supports TLS 1.2 or 1.3 going forward. From now on, Firefox will return a [Secure Connection Failed](https://support.mozilla.org/en-US/kb/secure-connection-failed-firefox-did-not-connect) error when connecting to servers using the older TLS versions ([Firefox bug 1606734](https://bugzil.la/1606734)). -- Starting in Firefox 74, when a site delegates permission to access a resource to embedded content in an {{HTMLElement("iframe")}} using the [`allow`](/en-US/docs/Web/HTML/Element/iframe#allow) attribute, and the embedded page requests permission to use that resource, the parent page prompts the user for permission to use the resource and share it with the embedded domain, rather than both the outer and inner pages prompting the user for permission. If the outer page doesn't have the permission requested by the `allow` attribute, the `<iframe>` is immediately denied access without prompting the user [Firefox bug 1483631](https://bugzil.la/1483631). +- Starting in Firefox 74, when a site delegates permission to access a resource to embedded content in an {{HTMLElement("iframe")}} using the [`allow`](/en-US/docs/Web/HTML/Reference/Elements/iframe#allow) attribute, and the embedded page requests permission to use that resource, the parent page prompts the user for permission to use the resource and share it with the embedded domain, rather than both the outer and inner pages prompting the user for permission. If the outer page doesn't have the permission requested by the `allow` attribute, the `<iframe>` is immediately denied access without prompting the user [Firefox bug 1483631](https://bugzil.la/1483631). ### Plugins diff --git a/files/en-us/mozilla/firefox/releases/75/index.md b/files/en-us/mozilla/firefox/releases/75/index.md index 1cf45ae6758581d..f28936ce4965037 100644 --- a/files/en-us/mozilla/firefox/releases/75/index.md +++ b/files/en-us/mozilla/firefox/releases/75/index.md @@ -20,8 +20,8 @@ This article provides information about the changes in Firefox 75 that will affe ### HTML -- The [`loading`](/en-US/docs/Web/HTML/Element/img#loading) attribute of the {{HTMLElement("img")}} element has now been implemented. This string value can be used to specify that the image should be [lazily loaded](/en-US/docs/Web/Performance/Guides/Lazy_loading), by setting its value to `lazy` ([Firefox bug 1542784](https://bugzil.la/1542784)). -- The value of the [`<style>`](/en-US/docs/Web/HTML/Element/style) element's `type` attribute is now restricted to `text/css` only, as per the spec ([Firefox bug 1614329](https://bugzil.la/1614329)). +- The [`loading`](/en-US/docs/Web/HTML/Reference/Elements/img#loading) attribute of the {{HTMLElement("img")}} element has now been implemented. This string value can be used to specify that the image should be [lazily loaded](/en-US/docs/Web/Performance/Guides/Lazy_loading), by setting its value to `lazy` ([Firefox bug 1542784](https://bugzil.la/1542784)). +- The value of the [`<style>`](/en-US/docs/Web/HTML/Reference/Elements/style) element's `type` attribute is now restricted to `text/css` only, as per the spec ([Firefox bug 1614329](https://bugzil.la/1614329)). ### CSS @@ -33,8 +33,8 @@ This article provides information about the changes in Firefox 75 that will affe New [ARIA](/en-US/docs/Web/Accessibility/ARIA) roles and attributes are now exposed in Firefox, on Windows and Linux (bear in mind that these still won't be usable until screen readers start to support them): - `aria-description` ([Firefox bug 1608961](https://bugzil.la/1608961)). -- [`role="mark"`](/en-US/docs/Web/Accessibility/ARIA/Roles/mark_role) and [`role="suggestion"`](/en-US/docs/Web/Accessibility/ARIA/Roles/suggestion_role) ([Firefox bug 1608965](https://bugzil.la/1608965)). -- [`role="comment"`](/en-US/docs/Web/Accessibility/ARIA/Roles/comment_role) ([Firefox bug 1608969](https://bugzil.la/1608969)). +- [`role="mark"`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/mark_role) and [`role="suggestion"`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/suggestion_role) ([Firefox bug 1608965](https://bugzil.la/1608965)). +- [`role="comment"`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/comment_role) ([Firefox bug 1608969](https://bugzil.la/1608969)). - Multiple IDs on `aria-details` ([Firefox bug 1608883](https://bugzil.la/1608883)). > [!NOTE] @@ -78,7 +78,7 @@ _No changes._ ### Security -- [CSP](/en-US/docs/Web/HTTP/CSP) nonces from non-script sources, such as CSS selectors, and `.getAttribute("nonce")` calls, are now hidden. Instead, check the [`.nonce`](/en-US/docs/Web/API/HTMLElement/nonce) property to access nonces from scripts ([Firefox bug 1374612](https://bugzil.la/1374612)). +- [CSP](/en-US/docs/Web/HTTP/Guides/CSP) nonces from non-script sources, such as CSS selectors, and `.getAttribute("nonce")` calls, are now hidden. Instead, check the [`.nonce`](/en-US/docs/Web/API/HTMLElement/nonce) property to access nonces from scripts ([Firefox bug 1374612](https://bugzil.la/1374612)). ### Plugins diff --git a/files/en-us/mozilla/firefox/releases/76/index.md b/files/en-us/mozilla/firefox/releases/76/index.md index e4c7240c9797a52..a31c26c9c5656ec 100644 --- a/files/en-us/mozilla/firefox/releases/76/index.md +++ b/files/en-us/mozilla/firefox/releases/76/index.md @@ -36,7 +36,7 @@ This article provides information about the changes in Firefox 76 that will affe ### HTML -- The {{HTMLElement("input")}} element's [`min`](/en-US/docs/Web/HTML/Element/input#min) and [`max`](/en-US/docs/Web/HTML/Element/input#max) attributes now work correctly when the value of `min` is greater than the value of `max` for control types whose values are periodic (that is, values that wrap around at some point). This is particularly helpful, for example, with date and time inputs, where you might want to specify a time range of 11 PM to 2 AM ([Firefox bug 1608010](https://bugzil.la/1608010)). +- The {{HTMLElement("input")}} element's [`min`](/en-US/docs/Web/HTML/Reference/Elements/input#min) and [`max`](/en-US/docs/Web/HTML/Reference/Elements/input#max) attributes now work correctly when the value of `min` is greater than the value of `max` for control types whose values are periodic (that is, values that wrap around at some point). This is particularly helpful, for example, with date and time inputs, where you might want to specify a time range of 11 PM to 2 AM ([Firefox bug 1608010](https://bugzil.la/1608010)). ### CSS @@ -59,7 +59,7 @@ _No changes._ #### DOM - UI-parts related items in the `windowFeatures` parameter of {{domxref("window.open()")}} can no longer control the visibility of each UI part separately, but become a condition for whether to open a popup or not ([Firefox bug 1507375](https://bugzil.la/1507375)). -- Attempts to navigate to an unknown protocol using methods such as [`location.href`](/en-US/docs/Web/API/Location/href) or [`<meta http-equiv="refresh">`](/en-US/docs/Web/HTML/Element/meta) are now blocked (see [Firefox bug 1528305](https://bugzil.la/1528305). +- Attempts to navigate to an unknown protocol using methods such as [`location.href`](/en-US/docs/Web/API/Location/href) or [`<meta http-equiv="refresh">`](/en-US/docs/Web/HTML/Reference/Elements/meta) are now blocked (see [Firefox bug 1528305](https://bugzil.la/1528305). - The {{domxref("IntersectionObserver.IntersectionObserver", "IntersectionObserver()")}} constructor now accepts a {{domxref("Document")}} object as its `root`, as well as an {{domxref("Element")}} object ([Firefox bug 1623623](https://bugzil.la/1623623)). This lets you explicitly use a window's entire content area as the intersection bounds. - The [Fetch API](/en-US/docs/Web/API/Fetch_API) now supports the `audioworklet` {{domxref("Request.destination", "destination")}} for requests. This causes received data to be dispatched to an {{domxref("AudioWorklet")}} ([Firefox bug 1402784](https://bugzil.la/1402784)). diff --git a/files/en-us/mozilla/firefox/releases/77/index.md b/files/en-us/mozilla/firefox/releases/77/index.md index ac0d677a7ced619..5d9ccc2ed071a45 100644 --- a/files/en-us/mozilla/firefox/releases/77/index.md +++ b/files/en-us/mozilla/firefox/releases/77/index.md @@ -29,7 +29,7 @@ This article provides information about the changes in Firefox 77 that will affe ### HTML -- Firefox now displays the [label value](/en-US/docs/Web/HTML/Element/option#browser_compatibility) on an {{HTMLElement("option")}} element when the element's content is empty. ([Firefox bug 40545](https://bugzil.la/40545)) +- Firefox now displays the [label value](/en-US/docs/Web/HTML/Reference/Elements/option#browser_compatibility) on an {{HTMLElement("option")}} element when the element's content is empty. ([Firefox bug 40545](https://bugzil.la/40545)) ### SVG @@ -73,7 +73,7 @@ This article provides information about the changes in Firefox 77 that will affe ### Other - Use of the `unlimitedStorage` permission no longer results in a prompt during extension installation or update. See [Requesting the right permissions](https://extensionworkshop.com/documentation/develop/request-the-right-permissions/) for more information. ([Firefox bug 1630413](https://bugzil.la/1630413)) -- Changes related to [`SameSite` cookies](/en-US/docs/Web/HTTP/Headers/Set-Cookie#samesitesamesite-value) mean that when setting [host permissions](/en-US/docs/Mozilla/Add-ons/WebExtensions/manifest.json/permissions#host_permissions) to bypass tracking protection for extension pages hosts must be specified as a full domain or with wildcards. However, for Content scripts tracking protection can only be bypassed for hosts specified with a full domain. +- Changes related to [`SameSite` cookies](/en-US/docs/Web/HTTP/Reference/Headers/Set-Cookie#samesitesamesite-value) mean that when setting [host permissions](/en-US/docs/Mozilla/Add-ons/WebExtensions/manifest.json/permissions#host_permissions) to bypass tracking protection for extension pages hosts must be specified as a full domain or with wildcards. However, for Content scripts tracking protection can only be bypassed for hosts specified with a full domain. ## Older versions diff --git a/files/en-us/mozilla/firefox/releases/78/index.md b/files/en-us/mozilla/firefox/releases/78/index.md index 0680305df24a043..2f8df45a9ca12b5 100644 --- a/files/en-us/mozilla/firefox/releases/78/index.md +++ b/files/en-us/mozilla/firefox/releases/78/index.md @@ -36,7 +36,7 @@ See also [New in Firefox 78: DevTools improvements, new regex engine, and abunda - The {{CSSxRef(":is", ":is()")}} and {{CSSxRef(":where", ":where()")}} pseudo-classes are now enabled by default ([Firefox bug 1632646](https://bugzil.la/1632646)). - The {{CSSxRef(":read-only")}} and {{CSSxRef(":read-write")}} pseudo-classes are now supported without prefixes ([Firefox bug 312971](https://bugzil.la/312971)). - - In addition, `:read-write` styles are no longer applied to disabled [`<input>`](/en-US/docs/Web/HTML/Element/input) and [`<textarea>`](/en-US/docs/Web/HTML/Element/textarea) elements, which was a violation of [the HTML spec](https://html.spec.whatwg.org/multipage/semantics-other.html#selector-read-write) ([Firefox bug 888884](https://bugzil.la/888884)). + - In addition, `:read-write` styles are no longer applied to disabled [`<input>`](/en-US/docs/Web/HTML/Reference/Elements/input) and [`<textarea>`](/en-US/docs/Web/HTML/Reference/Elements/textarea) elements, which was a violation of [the HTML spec](https://html.spec.whatwg.org/multipage/semantics-other.html#selector-read-write) ([Firefox bug 888884](https://bugzil.la/888884)). ### JavaScript diff --git a/files/en-us/mozilla/firefox/releases/79/index.md b/files/en-us/mozilla/firefox/releases/79/index.md index c1af85ee574724c..f787f3b5b9917f5 100644 --- a/files/en-us/mozilla/firefox/releases/79/index.md +++ b/files/en-us/mozilla/firefox/releases/79/index.md @@ -36,8 +36,8 @@ See also [Firefox 79: The safe return of shared memory, new tooling, and platfor ### HTML -- The [`<iframe>`](/en-US/docs/Web/HTML/Element/iframe) element's `sandbox` attribute now supports the `allow-top-navigation-by-user-activation` token ([Firefox bug 1359867](https://bugzil.la/1359867)). -- Setting `target="_blank"` on [`<a>`](/en-US/docs/Web/HTML/Element/a) and [`<area>`](/en-US/docs/Web/HTML/Element/area) elements implicitly provides the same behavior as also setting `rel="noopener"` ([Firefox bug 1522083](https://bugzil.la/1522083)). +- The [`<iframe>`](/en-US/docs/Web/HTML/Reference/Elements/iframe) element's `sandbox` attribute now supports the `allow-top-navigation-by-user-activation` token ([Firefox bug 1359867](https://bugzil.la/1359867)). +- Setting `target="_blank"` on [`<a>`](/en-US/docs/Web/HTML/Reference/Elements/a) and [`<area>`](/en-US/docs/Web/HTML/Reference/Elements/area) elements implicitly provides the same behavior as also setting `rel="noopener"` ([Firefox bug 1522083](https://bugzil.la/1522083)). ### CSS diff --git a/files/en-us/mozilla/firefox/releases/8/index.md b/files/en-us/mozilla/firefox/releases/8/index.md index eb2a2871a00a2aa..98105d811b2a179 100644 --- a/files/en-us/mozilla/firefox/releases/8/index.md +++ b/files/en-us/mozilla/firefox/releases/8/index.md @@ -12,7 +12,7 @@ Firefox 8 was released on November 8, 2011. This article provides information bo ### HTML -- The {{ domxref("HTMLImageElement") }} `crossOrigin` property has been added and the [`crossorigin`](/en-US/docs/Web/HTML/Element/img#crossorigin) attribute has been added to the {{ HTMLElement("img") }} element. (see [Firefox bug 664299](https://bugzil.la/664299)) +- The {{ domxref("HTMLImageElement") }} `crossOrigin` property has been added and the [`crossorigin`](/en-US/docs/Web/HTML/Reference/Elements/img#crossorigin) attribute has been added to the {{ HTMLElement("img") }} element. (see [Firefox bug 664299](https://bugzil.la/664299)) - The {{ domxref("HTMLSelectElement","","add()") }} method now supports either an item or index of an item that the new item should be inserted before. Previously it only supported an item. (see [Firefox bug 666200](https://bugzil.la/666200)) - The `HTMLIsIndexElement` constructor has been removed. No elements have implemented this interface since before Firefox 4. - The HTML5 "context menu" feature (`contextmenu` attribute), which lets you add custom element specific items to native context menu, is now supported (the implementation is still experimental awaiting changes in the specification; see [Firefox bug 617528](https://bugzil.la/617528)). @@ -34,8 +34,8 @@ Firefox 8 was released on November 8, 2011. This article provides information bo - {{ domxref("Document.getSelection()") }} now returns the same `Selection` object as {{ domxref("window.getSelection()") }}, instead of _stringifying_ it. - The HTML5 `selectionDirection` property makes it possible to define the direction of the selection in an editable text. - {{ domxref("HTMLMediaElement") }} now have a `seekable` property that return a {{ domxref("TimeRanges") }} object. -- The {{ domxref("HTMLMediaElement") }}`.preload` attribute now correctly reflects as an _enumerated value_. -- [`crossOrigin` property](/en-US/docs/Web/HTML/Attributes/crossorigin) defaults to "Anonymous" when an invalid value is used. +- The {{ domxref("HTMLMediaElement.preload") }} attribute now correctly reflects as an _enumerated value_. +- [`crossOrigin` property](/en-US/docs/Web/HTML/Reference/Attributes/crossorigin) defaults to "Anonymous" when an invalid value is used. - {{ domxref("navigator.cookieEnabled") }} now returns correct information when the default cookie setting is overridden on a per-site basis. ### JavaScript @@ -157,7 +157,9 @@ The `nsIWorkerFactory` interface has been removed as well. Workers can still be - When a window is minimized, un-minimized, or switches between full screen and windowed mode, it receives a `sizemodechange` event. - You can now [use the `extensions.autoDisableScopes` preference](https://extensionworkshop.com/documentation/publish/signing-and-distribution-overview/#preventing_automatic_install_from_specific_locations) to disable automatic installation of add-ons from specific add-on install locations. - The new `mozSyntheticDocument` property on {{ domxref("Document") }} objects lets you determine whether a document is synthetic (that is, something like a standalone image, video, or audio file) rather than a full, standard DOM document. This can be useful, for example, if you want to present different user interface in this situation (such as adding contextual items differently depending on this case). -- You can now specify a filter when opening `about:config`; for example, "about:config?filter=sessionstore" will show only session storage related preferences. +- You can now specify a filter when opening `about:config`; for example, `about:config?filter=sessionstore` will show only session storage related preferences. + +<!-- cSpell:ignore sessionstore --> ## See also diff --git a/files/en-us/mozilla/firefox/releases/8/updating_add-ons/index.md b/files/en-us/mozilla/firefox/releases/8/updating_add-ons/index.md index 6a0218ae8b7b9e2..bdc39d8393d5206 100644 --- a/files/en-us/mozilla/firefox/releases/8/updating_add-ons/index.md +++ b/files/en-us/mozilla/firefox/releases/8/updating_add-ons/index.md @@ -52,7 +52,7 @@ Similarly, a new global, `ChromeWorker`, was introduced to support allowing Work ## Security changes -Support for SSL 2.0 has been removed. This shouldn't affect any current add-ons. However, for reference, some very old code was removed, as well as support for the preferences `security.enable_ssl2` (which is false by default), and all preferences starting with "`security.ssl2.`" +Support for SSL 2.0 has been removed. This shouldn't affect any current add-ons. However, for reference, some very old code was removed, as well as support for the preferences `security.enable_ssl2` (which is false by default), and all preferences starting with `security.ssl2`. ## See also diff --git a/files/en-us/mozilla/firefox/releases/80/index.md b/files/en-us/mozilla/firefox/releases/80/index.md index 591d6355240df79..feb07666b168529 100644 --- a/files/en-us/mozilla/firefox/releases/80/index.md +++ b/files/en-us/mozilla/firefox/releases/80/index.md @@ -31,7 +31,7 @@ _No changes._ ### HTTP -- Previously, when the [fullscreen](/en-US/docs/Web/HTTP/Headers/Permissions-Policy/fullscreen) directive was applied to an [`<iframe>`](/en-US/docs/Web/HTML/Element/iframe) (i.e. via the `allow` attribute), it didn't work unless the `allowfullscreen` attribute was also present This has now been fixed ([Firefox bug 1608358](https://bugzil.la/1608358)). +- Previously, when the [fullscreen](/en-US/docs/Web/HTTP/Reference/Headers/Permissions-Policy/fullscreen) directive was applied to an [`<iframe>`](/en-US/docs/Web/HTML/Reference/Elements/iframe) (i.e., via the `allow` attribute), it didn't work unless the `allowfullscreen` attribute was also present This has now been fixed ([Firefox bug 1608358](https://bugzil.la/1608358)). ### APIs diff --git a/files/en-us/mozilla/firefox/releases/81/index.md b/files/en-us/mozilla/firefox/releases/81/index.md index 4c3b50b9edca3f0..d02a15e8b5480e0 100644 --- a/files/en-us/mozilla/firefox/releases/81/index.md +++ b/files/en-us/mozilla/firefox/releases/81/index.md @@ -19,11 +19,11 @@ This article provides information about the changes in Firefox 81 that will affe ### HTML -- Automatic downloads are now blocked in a sandboxed [`<iframe>`](/en-US/docs/Web/HTML/Element/iframe) element ([Firefox bug 1558394](https://bugzil.la/1558394)). +- Automatic downloads are now blocked in a sandboxed [`<iframe>`](/en-US/docs/Web/HTML/Reference/Elements/iframe) element ([Firefox bug 1558394](https://bugzil.la/1558394)). #### Removals -- Support for the non-standard `mozallowfullscreen` attribute has been removed from [`<iframe>`](/en-US/docs/Web/HTML/Element/iframe). Consider using `allow="fullscreen"` instead ([Firefox bug 1657599](https://bugzil.la/1657599)). +- Support for the non-standard `mozallowfullscreen` attribute has been removed from [`<iframe>`](/en-US/docs/Web/HTML/Reference/Elements/iframe). Consider using `allow="fullscreen"` instead ([Firefox bug 1657599](https://bugzil.la/1657599)). ### CSS @@ -40,8 +40,8 @@ _No changes._ ### HTTP -- Firefox now accepts non-standard [`Content-Disposition`](/en-US/docs/Web/HTTP/Headers/Content-Disposition) headers with an unquoted filename containing spaces ([Firefox bug 1440677](https://bugzil.la/1440677)). -- Firefox now supports the HTTP [`Feature-Policy`](/en-US/docs/Web/HTTP/Headers/Permissions-Policy) header's [`web-share`](/en-US/docs/Web/HTTP/Headers/Permissions-Policy/web-share) directive, which can be used to restrict access to the [Web Share API](/en-US/docs/Web/API/Navigator/share) to trusted origins. Note that Firefox does not support the Web Share API itself, at time of writing ([Firefox bug 1653199](https://bugzil.la/1653199)). +- Firefox now accepts non-standard [`Content-Disposition`](/en-US/docs/Web/HTTP/Reference/Headers/Content-Disposition) headers with an unquoted filename containing spaces ([Firefox bug 1440677](https://bugzil.la/1440677)). +- Firefox now supports the HTTP [`Feature-Policy`](/en-US/docs/Web/HTTP/Reference/Headers/Permissions-Policy) header's [`web-share`](/en-US/docs/Web/HTTP/Reference/Headers/Permissions-Policy/web-share) directive, which can be used to restrict access to the [Web Share API](/en-US/docs/Web/API/Navigator/share) to trusted origins. Note that Firefox does not support the Web Share API itself, at time of writing ([Firefox bug 1653199](https://bugzil.la/1653199)). ### APIs @@ -51,7 +51,7 @@ _No changes._ #### Workers/Service workers -- Strict MIME type checks are now enforced on worker and shared worker scripts, i.e. scripts targeted by the {{domxref("Worker.Worker()", "Worker()")}} and {{domxref("SharedWorker.SharedWorker()", "SharedWorker()")}} constructors must now be served with `text/javascript` ([Firefox bug 1569123](https://bugzil.la/1569123)). +- Strict MIME type checks are now enforced on worker and shared worker scripts, i.e., scripts targeted by the {{domxref("Worker.Worker()", "Worker()")}} and {{domxref("SharedWorker.SharedWorker()", "SharedWorker()")}} constructors must now be served with `text/javascript` ([Firefox bug 1569123](https://bugzil.la/1569123)). ### WebDriver conformance (Marionette) diff --git a/files/en-us/mozilla/firefox/releases/82/index.md b/files/en-us/mozilla/firefox/releases/82/index.md index 5e0e70afc60109f..ac2f9e71635adec 100644 --- a/files/en-us/mozilla/firefox/releases/82/index.md +++ b/files/en-us/mozilla/firefox/releases/82/index.md @@ -16,16 +16,16 @@ This article provides information about the changes in Firefox 82 that will affe ### Developer tools - You can now [inspect server-sent events](https://firefox-source-docs.mozilla.org/devtools-user/network_monitor/inspecting_server-sent_events/index.html) using the [Network Monitor](https://firefox-source-docs.mozilla.org/devtools-user/network_monitor/index.html) ([Firefox bug 1640857](https://bugzil.la/1640857)). -- The Network Monitor's _Message_ panel has now been merged with the _Response_ panel — messages (e.g. from WebSockets or server-sent events) can now be viewed right below the responses list ([Firefox bug 1636421](https://bugzil.la/1636421)). +- The Network Monitor's _Message_ panel has now been merged with the _Response_ panel — messages (e.g., from WebSockets or server-sent events) can now be viewed right below the responses list ([Firefox bug 1636421](https://bugzil.la/1636421)). ### HTML -- The color picker used for [`<input type="color">`](/en-US/docs/Web/HTML/Element/input/color) is now keyboard-accessible on Windows ([Firefox bug 1526820](https://bugzil.la/1526820)). -- The `allow-downloads` flag for the [`<iframe sandbox>`](/en-US/docs/Web/HTML/Element/iframe) attribute is now supported ([Firefox bug 1656212](https://bugzil.la/1656212)). +- The color picker used for [`<input type="color">`](/en-US/docs/Web/HTML/Reference/Elements/input/color) is now keyboard-accessible on Windows ([Firefox bug 1526820](https://bugzil.la/1526820)). +- The `allow-downloads` flag for the [`<iframe sandbox>`](/en-US/docs/Web/HTML/Reference/Elements/iframe) attribute is now supported ([Firefox bug 1656212](https://bugzil.la/1656212)). ### CSS -- Support for the new {{CSSxRef("::file-selector-button", "::file-selector-button")}} pseudo-element has been added. This pseudo-element represents the file selection button inside an [`<input type="file">`](/en-US/docs/Web/HTML/Element/input/file) element ([Firefox bug 1635675](https://bugzil.la/1635675), [Firefox bug 1662478](https://bugzil.la/1662478)). +- Support for the new {{CSSxRef("::file-selector-button", "::file-selector-button")}} pseudo-element has been added. This pseudo-element represents the file selection button inside an [`<input type="file">`](/en-US/docs/Web/HTML/Reference/Elements/input/file) element ([Firefox bug 1635675](https://bugzil.la/1635675), [Firefox bug 1662478](https://bugzil.la/1662478)). - We have improved error recovery for the {{CSSxRef(":is", ":is()")}} and {{CSSxRef(":where", ":where()")}} pseudo-classes. These pseudo-classes now accept a forgiving selector list, where an invalid selector in the list will not render the entire list invalid ([Firefox bug 1664718](https://bugzil.la/1664718)). - `appearance: button` now applies only to buttons; the `button` value of {{CSSxRef("appearance")}} will otherwise behave as `auto` ([Firefox bug 1662703](https://bugzil.la/1662703)). @@ -35,7 +35,7 @@ This article provides information about the changes in Firefox 82 that will affe ### HTTP -- The [`Content-Disposition`](/en-US/docs/Web/HTTP/Headers/Content-Disposition) header's `inline` directive will now be ignored if the HTML [`<a>`](/en-US/docs/Web/HTML/Element/a) element's `download` attribute is specified (for [same-origin URLs](/en-US/docs/Web/Security/Same-origin_policy)). Note that if specified the `Content-Disposition` header `filename` will be used in preference to a filename specified in the `download` attribute ([Firefox bug 1658877](https://bugzil.la/1658877)). +- The [`Content-Disposition`](/en-US/docs/Web/HTTP/Reference/Headers/Content-Disposition) header's `inline` directive will now be ignored if the HTML [`<a>`](/en-US/docs/Web/HTML/Reference/Elements/a) element's `download` attribute is specified (for [same-origin URLs](/en-US/docs/Web/Security/Same-origin_policy)). Note that if specified the `Content-Disposition` header `filename` will be used in preference to a filename specified in the `download` attribute ([Firefox bug 1658877](https://bugzil.la/1658877)). ### APIs @@ -47,7 +47,7 @@ This article provides information about the changes in Firefox 82 that will affe - [`Document.execCommand()`](/en-US/docs/Web/API/Document/execCommand) is no longer supported for nested/recursive calls, which will now return `false` ([Firefox bug 1634262](https://bugzil.la/1634262)). - [`Element.setPointerCapture()`](/en-US/docs/Web/API/Element/setPointerCapture) throws the `NotFoundError` exception if the pointer `id` is invalid, as per the [specification](https://w3c.github.io/pointerevents/#setting-pointer-capture) ([Firefox bug 1662124](https://bugzil.la/1662124)). Previously it wrongly threw an `InvalidPointerId` exception. -- The [`window.name`](/en-US/docs/Web/API/Window/name) property is reset to an empty string if a tab loads a page from a different domain, and restored if the original page is reloaded (e.g. via the "back" button). This prevents an untrusted page from accessing any information that the previous page might have stored in the variable. This change may impact frameworks that use `window.name` for cross-domain messaging ([Firefox bug 444222](https://bugzil.la/444222)). +- The [`window.name`](/en-US/docs/Web/API/Window/name) property is reset to an empty string if a tab loads a page from a different domain, and restored if the original page is reloaded (e.g., via the "back" button). This prevents an untrusted page from accessing any information that the previous page might have stored in the variable. This change may impact frameworks that use `window.name` for cross-domain messaging ([Firefox bug 444222](https://bugzil.la/444222)). ### WebDriver conformance (Marionette) diff --git a/files/en-us/mozilla/firefox/releases/83/index.md b/files/en-us/mozilla/firefox/releases/83/index.md index be401a4419bce3e..155ba7c89eaf221 100644 --- a/files/en-us/mozilla/firefox/releases/83/index.md +++ b/files/en-us/mozilla/firefox/releases/83/index.md @@ -21,7 +21,7 @@ This article provides information about the changes in Firefox 83 that will affe ### HTML/XML - The `crossorigin` attribute is now supported for `<link rel=icon>` ([Firefox bug 1661075](https://bugzil.la/1661075)). -- The `displaystyle` [attribute](/en-US/docs/Web/MathML/Attribute) is now implemented for all MathML elements ([Firefox bug 1666075](https://bugzil.la/1666075)). +- The `displaystyle` [attribute](/en-US/docs/Web/MathML/Reference/Attribute) is now implemented for all MathML elements ([Firefox bug 1666075](https://bugzil.la/1666075)). ### CSS @@ -43,7 +43,7 @@ _No changes._ ### WebDriver conformance (Marionette) - We've removed preliminary support for `WebDriver:SwitchToShadowRoot`, which hasn't been added to the WebDriver specification yet ([Firefox bug 1662468](https://bugzil.la/1662468)). -- We fixed a bug in `WebDriver:Back` and `WebDriver:Forward` that caused Marionette to hang when the navigation was triggered from within an [`<iframe>`](/en-US/docs/Web/HTML/Element/iframe) that gets removed ([Firefox bug 1672758](https://bugzil.la/1672758)). +- We fixed a bug in `WebDriver:Back` and `WebDriver:Forward` that caused Marionette to hang when the navigation was triggered from within an [`<iframe>`](/en-US/docs/Web/HTML/Reference/Elements/iframe) that gets removed ([Firefox bug 1672758](https://bugzil.la/1672758)). ## Changes for add-on developers diff --git a/files/en-us/mozilla/firefox/releases/84/index.md b/files/en-us/mozilla/firefox/releases/84/index.md index 8de1efcad7900a5..96b6b45e7d396a8 100644 --- a/files/en-us/mozilla/firefox/releases/84/index.md +++ b/files/en-us/mozilla/firefox/releases/84/index.md @@ -39,7 +39,7 @@ _No changes._ ### Security -- Firefox now ensures that `localhost` URLs — such as `http://localhost/` and `http://dev.localhost/` — refer to the local host's loopback interface (e.g. `http://127.0.0.1`). As a result, resources loaded from `localhost` are now assumed to have been delivered securely (see [Secure contexts](/en-US/docs/Web/Security/Secure_Contexts)), and also will not be treated as [mixed content](/en-US/docs/Web/Security/Mixed_content) ([Firefox bug 1220810](https://bugzil.la/1220810), [Firefox bug 1488740](https://bugzil.la/1488740)). +- Firefox now ensures that `localhost` URLs — such as `http://localhost/` and `http://dev.localhost/` — refer to the local host's loopback interface (e.g., `http://127.0.0.1`). As a result, resources loaded from `localhost` are now assumed to have been delivered securely (see [Secure contexts](/en-US/docs/Web/Security/Secure_Contexts)), and also will not be treated as [mixed content](/en-US/docs/Web/Security/Mixed_content) ([Firefox bug 1220810](https://bugzil.la/1220810), [Firefox bug 1488740](https://bugzil.la/1488740)). ### APIs @@ -64,7 +64,7 @@ _No changes._ - The new Fission-compatible API has been enabled by default now. To revert to the former API the `marionette.actors.enabled` preference has to be set to `false` ([Firefox bug 1669169](https://bugzil.la/1669169)). - Fixed `WebDriver:SwitchToWindow` to always switch back to the top-level browsing context ([Firefox bug 1305822](https://bugzil.la/1305822)). - Improved browsing context checks for `WebDriver:SwitchToParentFrame` ([Firefox bug 1671622](https://bugzil.la/1671622)). -- Fixed a hang for `WebDriver:Back` encountered when the currently-selected [`<iframe>`](/en-US/docs/Web/HTML/Element/iframe) gets unloaded ([Firefox bug 1672758](https://bugzil.la/1672758)). +- Fixed a hang for `WebDriver:Back` encountered when the currently-selected [`<iframe>`](/en-US/docs/Web/HTML/Reference/Elements/iframe) gets unloaded ([Firefox bug 1672758](https://bugzil.la/1672758)). #### Known bugs diff --git a/files/en-us/mozilla/firefox/releases/85/index.md b/files/en-us/mozilla/firefox/releases/85/index.md index bb271c3b9458d65..b3ba78b7adfc3ae 100644 --- a/files/en-us/mozilla/firefox/releases/85/index.md +++ b/files/en-us/mozilla/firefox/releases/85/index.md @@ -19,7 +19,7 @@ This article provides information about the changes in Firefox 85 that will affe ### HTML -- [`<link rel="preload">`](/en-US/docs/Web/HTML/Attributes/rel/preload) is now enabled. ([Firefox bug 1626997](https://bugzil.la/1626997)). +- [`<link rel="preload">`](/en-US/docs/Web/HTML/Reference/Attributes/rel/preload) is now enabled. ([Firefox bug 1626997](https://bugzil.la/1626997)). #### Removals diff --git a/files/en-us/mozilla/firefox/releases/86/index.md b/files/en-us/mozilla/firefox/releases/86/index.md index a46d72438d918b9..6a5a100c2f14ab6 100644 --- a/files/en-us/mozilla/firefox/releases/86/index.md +++ b/files/en-us/mozilla/firefox/releases/86/index.md @@ -25,7 +25,7 @@ _No changes._ ### SVG -- SVG filters can now use the {{SVGElement("feComposite")}} element with the [`lighter` operator](/en-US/docs/Web/SVG/Attribute/operator#fecomposite) ([Firefox bug 1518099](https://bugzil.la/1518099)). This operator sums the pixels of two source graphics. +- SVG filters can now use the {{SVGElement("feComposite")}} element with the [`lighter` operator](/en-US/docs/Web/SVG/Reference/Attribute/operator#fecomposite) ([Firefox bug 1518099](https://bugzil.la/1518099)). This operator sums the pixels of two source graphics. ### CSS @@ -50,7 +50,7 @@ _No changes._ #### DOM -- [`Window.name`](/en-US/docs/Web/API/Window/name) is now reset to an empty string if a tab loads a page from a different domain, and restored if the original page is reloaded (e.g. by selecting the "back" button). This prevents an untrusted page from accessing any information that the previous page might have stored in the property (potentially the new page might also modify such data, which might then be read by the original page if it was reloaded). For more information see [Firefox bug 1685089](https://bugzil.la/1685089). +- [`Window.name`](/en-US/docs/Web/API/Window/name) is now reset to an empty string if a tab loads a page from a different domain, and restored if the original page is reloaded (e.g., by selecting the "back" button). This prevents an untrusted page from accessing any information that the previous page might have stored in the property (potentially the new page might also modify such data, which might then be read by the original page if it was reloaded). For more information see [Firefox bug 1685089](https://bugzil.la/1685089). - [`EventTarget.addEventListener()`](/en-US/docs/Web/API/EventTarget/addEventListener) now supports the `signal` option. This option allows an [`AbortSignal`](/en-US/docs/Web/API/AbortSignal) to be passed to the method. The `AbortSignal` can later be used to remove the listener by calling `abort()`. For more information see [Firefox bug 1679204](https://bugzil.la/1679204). ### WebDriver conformance (Marionette) diff --git a/files/en-us/mozilla/firefox/releases/87/index.md b/files/en-us/mozilla/firefox/releases/87/index.md index 0c8dc1703f37a8b..a9fdd433577e1e3 100644 --- a/files/en-us/mozilla/firefox/releases/87/index.md +++ b/files/en-us/mozilla/firefox/releases/87/index.md @@ -58,9 +58,9 @@ _No changes._ ### HTTP -- Some enterprise authentication services require that TLS client certificates be [sent in CORS preflight requests](/en-US/docs/Web/HTTP/CORS#preflight_requests_and_credentials). Users of these services can enable this (non-specification compliant) behavior using the `network.cors_preflight.allow_client_cert` preference ([Firefox bug 1511151](https://bugzil.la/1511151)). -- The default [`Referrer-Policy`](/en-US/docs/Web/HTTP/Headers/Referrer-Policy) has been changed to [`strict-origin-when-cross-origin`](/en-US/docs/Web/HTTP/Headers/Referrer-Policy#strict-origin-when-cross-origin) (from `no-referrer-when-downgrade`), reducing the risk of leaking referrer information in cross-origin requests ([Firefox bug 1589074](https://bugzil.la/1589074)). -- [`Content-Length`](/en-US/docs/Web/HTTP/Headers/Content-Length) has been added to the list of [CORS-safelisted response headers](/en-US/docs/Glossary/CORS-safelisted_response_header) ([Firefox bug 1460299](https://bugzil.la/1460299)). +- Some enterprise authentication services require that TLS client certificates be [sent in CORS preflight requests](/en-US/docs/Web/HTTP/Guides/CORS#preflight_requests_and_credentials). Users of these services can enable this (non-specification compliant) behavior using the `network.cors_preflight.allow_client_cert` preference ([Firefox bug 1511151](https://bugzil.la/1511151)). +- The default [`Referrer-Policy`](/en-US/docs/Web/HTTP/Reference/Headers/Referrer-Policy) has been changed to [`strict-origin-when-cross-origin`](/en-US/docs/Web/HTTP/Reference/Headers/Referrer-Policy#strict-origin-when-cross-origin) (from `no-referrer-when-downgrade`), reducing the risk of leaking referrer information in cross-origin requests ([Firefox bug 1589074](https://bugzil.la/1589074)). +- [`Content-Length`](/en-US/docs/Web/HTTP/Reference/Headers/Content-Length) has been added to the list of [CORS-safelisted response headers](/en-US/docs/Glossary/CORS-safelisted_response_header) ([Firefox bug 1460299](https://bugzil.la/1460299)). ### Security @@ -70,7 +70,7 @@ _No changes._ #### DOM -- The {{domxref("Element.beforeinput_event", "beforeinput")}} event and {{domxref('InputEvent.getTargetRanges()', 'getTargetRanges()')}} method are now enabled by default. They allow web apps to override text edit behavior before the browser modifies the DOM tree, and provide more control over input events to improve performance. The global `beforeinput` event is sent to an {{HTMLElement("input")}} element — or any element whose [`contenteditable`](/en-US/docs/Web/HTML/Global_attributes/contenteditable) attribute is set to `true` — immediately before the element's value changes. The `getTargetRanges()` method of the {{domxref("InputEvent")}} interface returns an array of static ranges that will be affected by a change to the DOM if the input event is not canceled. +- The {{domxref("Element.beforeinput_event", "beforeinput")}} event and {{domxref('InputEvent.getTargetRanges()', 'getTargetRanges()')}} method are now enabled by default. They allow web apps to override text edit behavior before the browser modifies the DOM tree, and provide more control over input events to improve performance. The global `beforeinput` event is sent to an {{HTMLElement("input")}} element — or any element whose [`contenteditable`](/en-US/docs/Web/HTML/Reference/Global_attributes/contenteditable) attribute is set to `true` — immediately before the element's value changes. The `getTargetRanges()` method of the {{domxref("InputEvent")}} interface returns an array of static ranges that will be affected by a change to the DOM if the input event is not canceled. ### WebDriver conformance (Marionette) diff --git a/files/en-us/mozilla/firefox/releases/89/index.md b/files/en-us/mozilla/firefox/releases/89/index.md index 56f2669521cd1bb..89d7b96da05d7da 100644 --- a/files/en-us/mozilla/firefox/releases/89/index.md +++ b/files/en-us/mozilla/firefox/releases/89/index.md @@ -42,7 +42,7 @@ _No changes._ #### DOM - {{domxref("PerformanceEventTiming")}} is now enabled by default ([Firefox bug 1701029](https://bugzil.la/1701029)). -- The content of {{htmlelement("input")}} and {{htmlelement("textarea")}} elements can now be manipulated using {{domxref("Document.execCommand()")}} commands by default, preserving edit history and providing parity with other browsers, without [`contentEditable`](/en-US/docs/Web/HTML/Global_attributes/contenteditable) or any lengthy workarounds required ([Firefox bug 1220696](https://bugzil.la/1220696)). +- The content of {{htmlelement("input")}} and {{htmlelement("textarea")}} elements can now be manipulated using {{domxref("Document.execCommand()")}} commands by default, preserving edit history and providing parity with other browsers, without [`contentEditable`](/en-US/docs/Web/HTML/Reference/Global_attributes/contenteditable) or any lengthy workarounds required ([Firefox bug 1220696](https://bugzil.la/1220696)). #### Removals diff --git a/files/en-us/mozilla/firefox/releases/9/index.md b/files/en-us/mozilla/firefox/releases/9/index.md index 38ee0d0f6fc6387..3940d4bfa9730b0 100644 --- a/files/en-us/mozilla/firefox/releases/9/index.md +++ b/files/en-us/mozilla/firefox/releases/9/index.md @@ -14,17 +14,17 @@ Firefox 9 was released for Windows on December 20, 2011. Mac and Linux version 9 - The `value` attribute of {{ HTMLElement("li") }} now can be negative. Previously negative values were converted to 0. - You can now [specify the start and stop time of media](/en-US/docs/Learn_web_development/Core/Structuring_content/HTML_video_and_audio#specifying_playback_range) in the URI of the media when using {{ HTMLElement("audio") }} and {{ HTMLElement("video") }} elements. -- {{ HTMLElement("input") }} and {{ HTMLElement("textarea") }} elements [now respect the value of the `lang` attribute](/en-US/docs/Web/HTML/Global_attributes/spellcheck#controlling_the_spellchecker_language) when invoking the spell checker. +- {{ HTMLElement("input") }} and {{ HTMLElement("textarea") }} elements [now respect the value of the `lang` attribute](/en-US/docs/Web/HTML/Reference/Global_attributes/spellcheck#controlling_the_spellchecker_language) when invoking the spell checker. - Firefox on Android now lets users snap photos with their phone's camera without leaving the browser when the {{ HTMLElement("input") }} element is used with `type="file"` and `accept="image/*"`. - Windows Vista style PNG ICO images are now supported. -- Drawing images that use the [`crossorigin`](/en-US/docs/Web/HTML/Attributes/crossorigin) attribute to request CORS access no longer incorrectly [taint the canvas](/en-US/docs/Web/HTML/CORS_enabled_image#what_is_a_.22tainted.22_canvas.3f) when CORS is granted. -- The value of the [`rowspan`](/en-US/docs/Web/HTML/Element/td#rowspan) attribute may now be as large as 65,534, up from 8190. +- Drawing images that use the [`crossorigin`](/en-US/docs/Web/HTML/Reference/Attributes/crossorigin) attribute to request CORS access no longer incorrectly [taint the canvas](/en-US/docs/Web/HTML/How_to/CORS_enabled_image#what_is_a_.22tainted.22_canvas.3f) when CORS is granted. +- The value of the [`rowspan`](/en-US/docs/Web/HTML/Reference/Elements/td#rowspan) attribute may now be as large as 65,534, up from 8190. ### CSS - The {{ cssxref("font-stretch") }} property is now supported. - The {{ cssxref("columns") }} property is now supported, with the `-moz` prefix. This is a shorthand for the following properties: {{ cssxref("column-width") }} and {{ cssxref("column-count") }}. -- When a stylesheet included using the {{ HTMLElement("link") }} element has been fully loaded and parsed (but not yet applied to the document), a [`load` event](/en-US/docs/Web/HTML/Element/link#stylesheet_load_events) is now fired. Also, if an error occurs processing a style sheet, an `error` event is fired. +- When a stylesheet included using the {{ HTMLElement("link") }} element has been fully loaded and parsed (but not yet applied to the document), a [`load` event](/en-US/docs/Web/HTML/Reference/Elements/link#stylesheet_load_events) is now fired. Also, if an error occurs processing a style sheet, an `error` event is fired. - You can now specify overflow settings for both the left and right edges of content using a new two-value syntax for {{ cssxref("text-overflow") }}. ### JavaScript @@ -46,7 +46,7 @@ _No change._ - The set of events that can be listened for on {{ HTMLElement("body") }} elements has been revised to match the latest draft of the HTML5 specification. The list of events in the [DOM event reference](/en-US/docs/Web/Events) reflects which events can be listened for on {{ HTMLElement("body") }}. - The `readystatechange` event is now fired only on the {{ domxref("Document") }}, as intended. - Event handlers are now implemented as standard IDL interfaces. For most cases, this won't affect content, but there are exceptions. -- A new response type, "`moz-json`", has been added to `XMLHttpRequest`, letting `XMLHttpRequest` automatically parse [JSON](/en-US/docs/Glossary/JSON) strings for you; when you request this type, a returned JSON string is parsed, so that the value of the `response` property is the resulting JavaScript object. +- A new response type, `"moz-json"`, has been added to `XMLHttpRequest`, letting `XMLHttpRequest` automatically parse [JSON](/en-US/docs/Glossary/JSON) strings for you; when you request this type, a returned JSON string is parsed, so that the value of the `response` property is the resulting JavaScript object. - [`XMLHttpRequest` "progress" events](/en-US/docs/Web/API/XMLHttpRequest_API/Using_XMLHttpRequest#monitoring_progress) are now reliably sent for every chunk of data received; in the past it was possible for the last chunk of data received to not fire a "progress" event. Now you can track progress by following only "progress" events, instead of also having to monitor "load" events to detect the receipt of the last chunk of data. - In the past, calling [`addEventListener()`](/en-US/docs/Web/API/EventTarget/addEventListener) with a `null` listener would throw an exception. Now it returns without error and with no effect. - The new {{ domxref("navigator.doNotTrack") }} property lets your content easily determine whether or not the user has enabled their do-no-track preference; if this value is "yes", you should not track the user. diff --git a/files/en-us/mozilla/firefox/releases/90/index.md b/files/en-us/mozilla/firefox/releases/90/index.md index 23c0ec5f999e7b5..7ae4e6e8947bcc5 100644 --- a/files/en-us/mozilla/firefox/releases/90/index.md +++ b/files/en-us/mozilla/firefox/releases/90/index.md @@ -30,7 +30,7 @@ This article provides information about the changes in Firefox 90 that will affe - [Private class static and instance fields and methods](/en-US/docs/Web/JavaScript/Reference/Classes/Private_properties) are now supported by default ([Firefox bug 1708235](https://bugzil.la/1708235) and [Firefox bug 1708236](https://bugzil.la/1708236)). - The [`in`](/en-US/docs/Web/JavaScript/Reference/Operators/in) operator can now be used to [check if a class private method or field has been defined](/en-US/docs/Web/JavaScript/Reference/Operators/in#using_the_in_operator_to_implement_branded_checks). This offers a more compact approach for handling potentially undefined features, as oppose to wrapping code in `try/catch` blocks ([Firefox bug 1648090](https://bugzil.la/1648090)). -- Custom date/time formats specified as options to the [`Intl.DateTimeFormat()` constructor](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/DateTimeFormat/DateTimeFormat) can now include `dayPeriod` — a value indicating that the approximate time of day (e.g. "in the morning", "at night", etc.) should be included as a `narrow`, `short`, or `long` string ([Firefox bug 1645115](https://bugzil.la/1645115)). +- Custom date/time formats specified as options to the [`Intl.DateTimeFormat()` constructor](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/DateTimeFormat/DateTimeFormat) can now include `dayPeriod` — a value indicating that the approximate time of day (e.g., "in the morning", "at night", etc.) should be included as a `narrow`, `short`, or `long` string ([Firefox bug 1645115](https://bugzil.la/1645115)). - The relative indexing method `at()` has been added to the [`Array`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array), [`String`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/String) and [`TypedArray`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/TypedArray) global objects. ([Firefox bug 1681371](https://bugzil.la/1681371)) ### HTTP diff --git a/files/en-us/mozilla/firefox/releases/91/index.md b/files/en-us/mozilla/firefox/releases/91/index.md index a0044832662805d..ff30b8698992100 100644 --- a/files/en-us/mozilla/firefox/releases/91/index.md +++ b/files/en-us/mozilla/firefox/releases/91/index.md @@ -28,7 +28,7 @@ No changes ### JavaScript -- {{jsxref("Intl/DateTimeFormat/formatRange", "Intl.DateTimeFormat.prototype.formatRange()")}} and {{jsxref("Intl/DateTimeFormat/formatRangeToParts", "Intl.DateTimeFormat.prototype.formatRangeToParts()")}} are now supported in release builds. The `formatRange()` method returns a localized and formatted string for the range between two {{jsxref("Date")}} objects (e.g. "1/05/21 – 1/10/21"). The `formatRangeToParts()` method returns an array containing the locale-specific _parts_ of a formatted date range ([Firefox bug 1653024](https://bugzil.la/1653024)). +- {{jsxref("Intl/DateTimeFormat/formatRange", "Intl.DateTimeFormat.prototype.formatRange()")}} and {{jsxref("Intl/DateTimeFormat/formatRangeToParts", "Intl.DateTimeFormat.prototype.formatRangeToParts()")}} are now supported in release builds. The `formatRange()` method returns a localized and formatted string for the range between two {{jsxref("Date")}} objects (e.g., "1/05/21 – 1/10/21"). The `formatRangeToParts()` method returns an array containing the locale-specific _parts_ of a formatted date range ([Firefox bug 1653024](https://bugzil.la/1653024)). - The {{jsxref("Intl/DateTimeFormat/DateTimeFormat", "Intl.DateTimeFormat()")}} constructor allows four new `timeZoneName` options for formatting how the timezone is displayed. These include the localized GMT formats `shortOffset` and `longOffset`, and the generic non-location formats `shortGeneric` and `longGeneric` ([Firefox bug 1653024](https://bugzil.la/1653024)). - The {{jsxref("Global_Objects/Error/Error", "Error()")}} constructor can now take the error `cause` as value in the `option` parameter. This allows code to catch errors and throw new/modified versions that retain the original error and stack trace ([Firefox bug 1679653](https://bugzil.la/1679653)). @@ -45,11 +45,11 @@ No changes The API provides access to information describing the position of the {{Glossary("visual viewport")}} relative to the document, as well as to the window's content area. It also provides events that allow changes to the viewport to be monitored. ([Firefox bug 1551302](https://bugzil.la/1551302)). - The [Gamepad API](/en-US/docs/Web/API/Gamepad_API) is now protected by {{httpheader('Feature-Policy/gamepad','Feature-Policy: gamepad')}}. - If disallowed by the [Permission Policy](/en-US/docs/Web/HTTP/Permissions_Policy), calls to {{domxref('Navigator.getGamepads()')}} will throw a `SecurityError` {{domxref('DOMException')}}, + If disallowed by the [Permission Policy](/en-US/docs/Web/HTTP/Guides/Permissions_Policy), calls to {{domxref('Navigator.getGamepads()')}} will throw a `SecurityError` {{domxref('DOMException')}}, and the {{domxref("Window.gamepadconnected_event", "gamepadconnected")}} and {{domxref("Window.gamepaddisconnected_event", "gamepaddisconnected")}} events will not fire. The default `allowlist` is `*`; this default will be updated to `self` in a future release, in order to match the specification. ([Firefox bug 1704005](https://bugzil.la/1704005)). - `Window.clientInformation` has been added as an alias for {{domxref("Window.navigator")}}, in order to match recent specification updates and improve compatibility with other major browsers ([Firefox bug 1717072](https://bugzil.la/1717072)). -- Changing the playback speed of a media element ([`<video>`](/en-US/docs/Web/HTML/Element/video) or [`<audio>`](/en-US/docs/Web/HTML/Element/audio)) using the [`playbackRate`](/en-US/docs/Web/API/HTMLMediaElement/playbackRate) attribute now works when the media element is captured to a [`MediaStream`](/en-US/docs/Web/API/MediaStream) or via [`AudioContext.createMediaElementSource`](/en-US/docs/Web/API/AudioContext/createMediaElementSource) ([Firefox bug 1517199](https://bugzil.la/1517199)). +- Changing the playback speed of a media element ([`<video>`](/en-US/docs/Web/HTML/Reference/Elements/video) or [`<audio>`](/en-US/docs/Web/HTML/Reference/Elements/audio)) using the [`playbackRate`](/en-US/docs/Web/API/HTMLMediaElement/playbackRate) attribute now works when the media element is captured to a [`MediaStream`](/en-US/docs/Web/API/MediaStream) or via [`AudioContext.createMediaElementSource`](/en-US/docs/Web/API/AudioContext/createMediaElementSource) ([Firefox bug 1517199](https://bugzil.la/1517199)). ### WebDriver conformance (Marionette) diff --git a/files/en-us/mozilla/firefox/releases/92/index.md b/files/en-us/mozilla/firefox/releases/92/index.md index f6401f7e0b57c60..1434449999c568d 100644 --- a/files/en-us/mozilla/firefox/releases/92/index.md +++ b/files/en-us/mozilla/firefox/releases/92/index.md @@ -48,7 +48,7 @@ No changes #### Media, WebRTC, and Web Audio -- Access to audio output devices, like speakers and headphones, is now protected by the [speaker-selection](/en-US/docs/Web/HTTP/Headers/Permissions-Policy/speaker-selection) feature policy ([Firefox bug 1577199](https://bugzil.la/1577199)). +- Access to audio output devices, like speakers and headphones, is now protected by the [speaker-selection](/en-US/docs/Web/HTTP/Reference/Headers/Permissions-Policy/speaker-selection) feature policy ([Firefox bug 1577199](https://bugzil.la/1577199)). ### WebDriver conformance (Marionette) diff --git a/files/en-us/mozilla/firefox/releases/93/index.md b/files/en-us/mozilla/firefox/releases/93/index.md index 723ad0c28b8f6fb..f4626fb12c9cd02 100644 --- a/files/en-us/mozilla/firefox/releases/93/index.md +++ b/files/en-us/mozilla/firefox/releases/93/index.md @@ -15,8 +15,8 @@ This article provides information about the changes in Firefox 93 that will affe ### HTML -- The ARIA [`meter`](/en-US/docs/Web/Accessibility/ARIA/Roles/meter_role) role has been implemented ([Firefox bug 1727616](https://bugzil.la/1727616)). -- The UI for [`<input type="datetime-local">`](/en-US/docs/Web/HTML/Element/input/datetime-local) has been implemented. ([Firefox bug 1283388](https://bugzil.la/1283388)). +- The ARIA [`meter`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/meter_role) role has been implemented ([Firefox bug 1727616](https://bugzil.la/1727616)). +- The UI for [`<input type="datetime-local">`](/en-US/docs/Web/HTML/Reference/Elements/input/datetime-local) has been implemented. ([Firefox bug 1283388](https://bugzil.la/1283388)). ### CSS @@ -30,7 +30,7 @@ This article provides information about the changes in Firefox 93 that will affe ### HTTP -- The SHA-256 algorithm is now supported for [HTTP Authentication](/en-US/docs/Web/HTTP/Authentication) using digests. This allows much more secure authentication than previously available using the MD5 algorithm ([Firefox bug 472823](https://bugzil.la/472823)). +- The SHA-256 algorithm is now supported for [HTTP Authentication](/en-US/docs/Web/HTTP/Guides/Authentication) using digests. This allows much more secure authentication than previously available using the MD5 algorithm ([Firefox bug 472823](https://bugzil.la/472823)). - The default HTTP {{HTTPHeader("ACCEPT")}} header for _images_ changed to: `image/avif,image/webp,*/*` (following addition of support for the [AVIF](/en-US/docs/Web/Media/Guides/Formats/Image_types#avif_image) image format). ([Firefox bug 1682995](https://bugzil.la/1682995)). ### APIs @@ -42,13 +42,13 @@ This article provides information about the changes in Firefox 93 that will affe #### Events - The {{domxref("Element.securitypolicyviolation_event","onsecuritypolicyviolation")}} global event handler property is now supported. - This can be used to assign a handler for processing [`securitypolicyviolation`](/en-US/docs/Web/API/Element/securitypolicyviolation_event) events fired when there is a [Content Security Policy](/en-US/docs/Web/HTTP/CSP) violation ([Firefox bug 1727302](https://bugzil.la/1727302)). + This can be used to assign a handler for processing [`securitypolicyviolation`](/en-US/docs/Web/API/Element/securitypolicyviolation_event) events fired when there is a [Content Security Policy](/en-US/docs/Web/HTTP/Guides/CSP) violation ([Firefox bug 1727302](https://bugzil.la/1727302)). - The `onslotchange` event handler property is now supported on {{domxref("HTMLSlotElement")}} and {{domxref("ShadowRoot")}}. This can be used to assign a handler for processing [`slotchange`](/en-US/docs/Web/API/HTMLSlotElement/slotchange_event) events, which are fired on {{HTMLElement("slot")}} elements when the node(s) contained in the slot change ([Firefox bug 1501983](https://bugzil.la/1501983)). #### Removals -- {{domxref("KeyboardEvent.initKeyEvent()")}} has been moved behind the preference `dom.keyboardevent.init_key_event.enabled` and is disabled by default. +- `KeyboardEvent.initKeyEvent()` has been moved behind the preference `dom.keyboardevent.init_key_event.enabled` and is disabled by default. The method is not present in any current specification or supported in other current browsers ([Firefox bug 1717760](https://bugzil.la/1717760)). ### WebDriver conformance (Marionette) diff --git a/files/en-us/mozilla/firefox/releases/94/index.md b/files/en-us/mozilla/firefox/releases/94/index.md index 77ba25650309641..5ae3685c154e550 100644 --- a/files/en-us/mozilla/firefox/releases/94/index.md +++ b/files/en-us/mozilla/firefox/releases/94/index.md @@ -28,7 +28,7 @@ No notable changes #### DOM -- Developers can now provide a hint for the enter key label/icon used on virtual keyboards, using either [`HTMLElement.enterkeyhint`](/en-US/docs/Web/API/HTMLElement/enterKeyHint) or the global attribute [`enterkeyhint`](/en-US/docs/Web/HTML/Global_attributes/enterkeyhint) ([Firefox bug 1648332](https://bugzil.la/1648332)). +- Developers can now provide a hint for the enter key label/icon used on virtual keyboards, using either [`HTMLElement.enterkeyhint`](/en-US/docs/Web/API/HTMLElement/enterKeyHint) or the global attribute [`enterkeyhint`](/en-US/docs/Web/HTML/Reference/Global_attributes/enterkeyhint) ([Firefox bug 1648332](https://bugzil.la/1648332)). - The {{domxref("HTMLScriptElement.supports_static", "HTMLScriptElement.supports()")}} static method is now supported. This provides a simple and unified method for feature checking whether a browser supports particular types of scripts, such as JavaScript modules or classic scripts ([Firefox bug 1729239](https://bugzil.la/1729239)). - The {{domxref("ShadowRoot.delegatesFocus")}} property is now supported, allowing code to check whether the `delegatesFocus` property was set when the [shadow DOM was attached](/en-US/docs/Web/API/Element/attachShadow) ([Firefox bug 1413836](https://bugzil.la/1413836)). @@ -38,7 +38,7 @@ No notable changes ### HTTP -- The `cache` directive of the [`Clear-Site-Data`](/en-US/docs/Web/HTTP/Headers/Clear-Site-Data) response header has been disabled by default. +- The `cache` directive of the [`Clear-Site-Data`](/en-US/docs/Web/HTTP/Reference/Headers/Clear-Site-Data) response header has been disabled by default. It can be enabled using the preference `privacy.clearsitedata.cache.enabled` ([Firefox bug 1729291](https://bugzil.la/1729291)). ## Changes for add-on developers diff --git a/files/en-us/mozilla/firefox/releases/95/index.md b/files/en-us/mozilla/firefox/releases/95/index.md index cebe02b0c3e0008..0bc1d28e1bd0a08 100644 --- a/files/en-us/mozilla/firefox/releases/95/index.md +++ b/files/en-us/mozilla/firefox/releases/95/index.md @@ -13,7 +13,7 @@ Firefox 95 was released on December 7, 2021. ### HTML -- The [`inputmode`](/en-US/docs/Web/HTML/Global_attributes/inputmode) global attribute is now supported on all platforms, instead of just Android. +- The [`inputmode`](/en-US/docs/Web/HTML/Reference/Global_attributes/inputmode) global attribute is now supported on all platforms, instead of just Android. This provides a hint to browsers about the type of virtual keyboard that would be best suited to editing a particular element ([Firefox bug 1205133](https://bugzil.la/1205133)). ### CSS diff --git a/files/en-us/mozilla/firefox/releases/96/index.md b/files/en-us/mozilla/firefox/releases/96/index.md index 64e05ad5fce13c6..f4c5b51e37495bd 100644 --- a/files/en-us/mozilla/firefox/releases/96/index.md +++ b/files/en-us/mozilla/firefox/releases/96/index.md @@ -23,7 +23,7 @@ No notable changes - The {{CSSxRef("counter-reset")}} property now supports the `reversed()` function for creating _reversed_ [CSS counters](/en-US/docs/Web/CSS/CSS_counter_styles/Using_CSS_counters), which are intended for numbering elements in descending order. This can be used with the `list-item` counter to automatically number ordered lists in reverse order, starting from the number of elements in the list (`list-item` is a counter that is automatically applied for ordered lists, such as those created using {{HTMLElement("ol")}}). - Firefox uses this feature internally to support the `<ol>` [`reversed` attribute](/en-US/docs/Web/HTML/Element/ol#reversed). + Firefox uses this feature internally to support the `<ol>` [`reversed` attribute](/en-US/docs/Web/HTML/Reference/Elements/ol#reversed). ([Firefox bug 1706346](https://bugzil.la/1706346)). ### JavaScript diff --git a/files/en-us/related/imsc/imsc_and_other_standards/index.md b/files/en-us/related/imsc/imsc_and_other_standards/index.md index c205851aa9ba52d..f1a997a8a8c01ce 100644 --- a/files/en-us/related/imsc/imsc_and_other_standards/index.md +++ b/files/en-us/related/imsc/imsc_and_other_standards/index.md @@ -16,7 +16,7 @@ IMSC is also a syntactic superset of both [SDP-US](https://www.w3.org/TR/ttml10- IMSC traces its origins to the CFF-TT format, and [CFF-TT documents](https://www.w3.org/TR/ttml-imsc1.1/#cff-tt) can be converted to IMSC relatively easily. -IMSC is unrelated to [WebVTT](https://www.w3.org/TR/webvtt1/), and does not use the same syntax. [Basic conversion guidelines](https://www.w3.org/TR/webvtt1/) exist. +IMSC is unrelated to [WebVTT](https://w3c.github.io/webvtt/), and does not use the same syntax. ## Active IMSC versions diff --git a/files/en-us/related/imsc/index.md b/files/en-us/related/imsc/index.md index 37c70480f9a7a96..ea66cd4a8b420d1 100644 --- a/files/en-us/related/imsc/index.md +++ b/files/en-us/related/imsc/index.md @@ -8,7 +8,7 @@ IMSC (TTML Profiles for Internet Media Subtitles and Captions) is a file format ## Concepts and usage -IMSC is standardized by the W3C, and used around the world by content producers (e.g. 20th Century Fox), online services (e.g. Netflix), and traditional broadcasters (e.g. the BBC). Many platforms and players support it, e.g. iOS devices and the dashJS player. +IMSC is standardized by the W3C, and used around the world by content producers (e.g., 20th Century Fox), online services (e.g., Netflix), and traditional broadcasters (e.g., the BBC). Many platforms and players support it, e.g., iOS devices and the dashJS player. IMSC supports a wide range of world languages and scripts, and rich styling. In addition to text-based subtitles, IMSC also supports PNG subtitles. @@ -120,7 +120,7 @@ In contrast to IMSC, which uses markup, WebVTT uses a combination of CSS and pla - imscJS polyfill - : IMSC documents can be rendered in browsers using the [imscJS](https://github.com/sandflow/imscJS) polyfill. -- [dash.js](https://github.com/Dash-Industry-Forum/dash.js/wiki) +- [dash.js](https://github.com/Dash-Industry-Forum/dash.js) - : The reference player of the DASH Industry Forum with IMSC support. ## Specifications diff --git a/files/en-us/related/imsc/namespaces/index.md b/files/en-us/related/imsc/namespaces/index.md index fc83ef867f6a935..9f14f261cc37ac5 100644 --- a/files/en-us/related/imsc/namespaces/index.md +++ b/files/en-us/related/imsc/namespaces/index.md @@ -100,7 +100,7 @@ We've looked at elements, but how can we specify the namespace of IMSC attribute In addition, IMSC attributes are contained in more than one namespace. Let's explain further — in IMSC there are different categories of attributes, styling attributes for example. The different categories have different namespaces. For example, all styling attributes have the namespace `http://www.w3.org/ns/ttml#styling`. -As for XML elements, it would be too verbose to always write the complete namespace for each attribute, e.g. `color_http://www.w3.org/ns/ttml#styling="yellow"`. +As for XML elements, it would be too verbose to always write the complete namespace for each attribute, e.g., `color_http://www.w3.org/ns/ttml#styling="yellow"`. Luckily XML has the concept of prefixes. A prefix can be thought of as a "shortcut" for a namespace. For example, we can define an attribute namespace on the root element: diff --git a/files/en-us/related/imsc/using_the_imscjs_polyfill/index.md b/files/en-us/related/imsc/using_the_imscjs_polyfill/index.md index 48d5e9457d2f27f..78aa6bae11b1352 100644 --- a/files/en-us/related/imsc/using_the_imscjs_polyfill/index.md +++ b/files/en-us/related/imsc/using_the_imscjs_polyfill/index.md @@ -15,7 +15,7 @@ You currently need a polyfill to render IMSC on the web. imscJS is a good choice First you need to embed the imscJS library: ```html -<script src="https://unpkg.com/imsc@1.1.0-beta.2/build/umd/imsc.all.min.js"> +<script src="https://unpkg.com/imsc@1.1.0-beta.2/build/umd/imsc.all.min.js"></script> ``` Once the imscJS library is loaded, it can be used to render an IMSC document in three distinct steps, explained in the below sections. @@ -137,7 +137,7 @@ What happens is the following: To map this into HTML we need at least two cues: one that represents the text "Hello" from second 1-2 and the other representing the text "Hello world!" from second 2-3. -But this is a simplified easy scenario. Imagine that you have 5 more words accumulating. They may have all the same end time but different start times. Or imagine you have a subtitle in a different location (e.g. representing a different speaker). This subtitle is shown in parallel to the other subtitle but the accumulating words may have different start times and therefore different intervals. +But this is a simplified easy scenario. Imagine that you have 5 more words accumulating. They may have all the same end time but different start times. Or imagine you have a subtitle in a different location (e.g., representing a different speaker). This subtitle is shown in parallel to the other subtitle but the accumulating words may have different start times and therefore different intervals. Luckily in IMSC and imscJS this scenario is quite easy to cover, because IMSC has a mechanism of stateless subtitle rendering. diff --git a/files/en-us/related/index.md b/files/en-us/related/index.md index 87d49ef04a35b66..a37fbaa8c42350c 100644 --- a/files/en-us/related/index.md +++ b/files/en-us/related/index.md @@ -4,7 +4,7 @@ slug: Related page-type: landing-page --- -This section of the site is a home for documentation on web-related technologies that aren't central to the MDN's remit (i.e. they aren't web standards technologies), but are nonetheless related to the web and of interest to web developers. +This section of the site is a home for documentation on web-related technologies that aren't central to the MDN's remit (i.e., they aren't web standards technologies), but are nonetheless related to the web and of interest to web developers. > [!NOTE] > These documentation resources generally aren't maintained by the MDN writer's team — if you have suggestions or queries related to these resources, check out the landing pages for those technologies for contact details of the relevant maintenance team. diff --git a/files/en-us/web/accessibility/accessibility_and_spacial_patterns/index.md b/files/en-us/web/accessibility/accessibility_and_spacial_patterns/index.md deleted file mode 100644 index ae32b12c2401c48..000000000000000 --- a/files/en-us/web/accessibility/accessibility_and_spacial_patterns/index.md +++ /dev/null @@ -1,85 +0,0 @@ ---- -title: Accessibility and Spacial Patterns -slug: Web/Accessibility/Accessibility_and_Spacial_Patterns -page-type: guide ---- - -{{AccessibilitySidebar}} - -## Spatial Localization - -NASA conducted research on the perception of color, and found that luminance contrast mattered greatly as to how colors are perceived. The two images below are from NASA research, specifically, from the article, "[Designing With Blue](https://colorusage.arc.nasa.gov/blue_2.php)" - -![Comparison of the stability of the spatial localization of yellow vs. red. Both are roughly isoluminant with their backgrounds. The misalignment and gap between the chromatic bars and black bars is physically the same for the yellow and red but much less visually obvious for the yellow.](yellow_edge_3.gif) ![Comparison of the stability of the spatial localization of yellow vs. red. Both are roughly isoluminant with their backgrounds. The misalignment and gap between the chromatic bars and black bars is physically the same for the yellow and red but much less visually obvious for the yellow.](yellow_edge_4.gif) - -"_**Spatial Localization.** Symbols which have the same luminance as their background are perceptually less securely located in space and time than are symbols with higher luminance contrast. They tend to "float" visually or be "captured" by adjacent symbols with high luminance-contrast. The phenomenon seems to be especially problematic for symbol/background combinations that differ only in the blue channel._" - -## Distance between stripes - -Photosensitive seizures may be caused by static images as well as animation. The mechanism for this is poorly understood, but is believed to be linked to "gamma oscillations" set up in the brain. These oscillations in the brain are a different kind of response than other kinds of neurological responses believed to cause photosensitive seizures. - -Stripes and patterns are typical of the kinds of images that create problems, and stripes have been studied most closely. There's the potential for causing harm if there are more than five light-dark pairs of stripes in any orientation. They can be parallel, radial, curved or straight, and may be formed by rows of repeating elements. - -In 2005, Arnold Wilkins, John Emmett, and Graham Harding evaluated the guidelines for characterizing patterned images that could precipitate seizures. They revised the guidelines to their fundamental core, and came up with a surprisingly simple, but powerful [test](https://onlinelibrary.wiley.com/doi/full/10.1111/j.1528-1167.2005.01405.x), which they published in the paper, **[Characterizing the Patterned Images That Precipitate Seizures and Optimizing Guidelines To Prevent Them](https://onlinelibrary.wiley.com/doi/full/10.1111/j.1528-1167.2005.01405.x)** - -> [!NOTE] -> The steps necessary to evaluate material reduce to the following: -> -> Look at the screen: -> -> - Are there more than five stripes? -> - If so, do they last longer than 0.5 s? -> - If so, does the brightness exceed the stated limit? -> - If so, categorize the motion of the pattern. -> - Are the guidelines contravened? -> -> If so, reduce brightness. - -## Text and padding - -WCAG standards for contrast perception do not take into account the effect of padding. For example, blue text on a gray background is easier to perceive if it is surrounded "locally" by black than by white. There is such a thing as "local" adaptation to colors. The bottom line: padding matters. - -## Math - -Spatial reasoning affects Math learning; consequently, spatial relationships in how math is presented affects cognition. The web developer can do something about this in the manner in which they display math. Animation figures strongly in this arena. For example, "how" an object looks when it is rotated, from different angles, how they look sliced, and how they relate to each other in space all make a difference in an ability to understand Math in spatial terms. - -## Braille - -Modern technology enables non-experts to print Braille. Adobe Illustrator, for example, allows one to Typeset ADA Braille for printing out. - -The ability to represent spatial patterns accurate to those who are blind is critical for accessibility. For example, knowing Braille is not enough. The Braille dots have to be spatially apart from one another so as to be readable in a "human" way. The human touch does distinguish with ease braille dots that are too close or too far apart from one another. - -Space has to surround the braille character. A user of braille does not lay a finger on "top" of a braille character, the user has to move her finger over the character, in the way that a sighted person must move her eyes across text written on a page. - -The nature of space can change depending upon what MIME type is being used, and its version. For example, borders on SVG can extend both inward and outward from its dimensions, or for newer versions of SVG, entirely outward from it, thus reducing the space around the SVG to enable perception. - -## See also - -### MDN - -- [Accessibility: What users can do to browse more safely](/en-US/docs/Web/Accessibility/Accessibility:_What_users_can_to_to_browse_safely) -- [Web accessibility for seizures and physical reactions](/en-US/docs/Web/Accessibility/Seizure_disorders) -- [Web Accessibility: Understanding Colors and Luminance](/en-US/docs/Web/Accessibility/Understanding_Colors_and_Luminance) - -### Braille - -- [Part 3: A Step-by-Step Guide to Typesetting ADA Braille Correctly in Adobe Illustrator](https://www.tinkeringmonkey.com/guides/ada-signage/a-step-by-step-guide-to-typesetting-ada-braille-correctly-in-adobe-illustrator/) -- [Spatial Math in BrailleBlaster (4 of 5)](https://www.youtube.com/watch?v=yz9vefDsj1g) - -### Government Literature - -- [NASA: Designing With Blue](https://colorusage.arc.nasa.gov/blue_2.php) - -### Math - -- [Spatial Reasoning: Why Math Talk is About More Than Numbers](https://dreme.stanford.edu/news/spatial-reasoning-why-math-talk-is-about-more-than-numbers/) - -### Scientific Literature - -- [Color constancy in context: Roles for local adaptation and levels of reference](https://jov.arvojournals.org/article.aspx?articleid=2192799) -- [Gamma oscillations and photosensitive epilepsy](https://www.sciencedirect.com/science/article/pii/S0960982217304062?via%3Dihub) -- [Characterizing the Patterned Images That Precipitate Seizures and Optimizing Guidelines To Prevent Them](https://onlinelibrary.wiley.com/doi/epdf/10.1111/j.1528-1167.2005.01405.x) Arnold Wilkins, John Emmett, and Graham Harding - -#### Contributors - -Heartfelt thanks to Jim Allan of the [Diagram Center](http://diagramcenter.org/) for his discussions on the topic of alternative means of education. diff --git a/files/en-us/web/accessibility/accessibility_colon__what_users_can_to_to_browse_safely/index.md b/files/en-us/web/accessibility/accessibility_colon__what_users_can_to_to_browse_safely/index.md deleted file mode 100644 index 23403d50ad680fe..000000000000000 --- a/files/en-us/web/accessibility/accessibility_colon__what_users_can_to_to_browse_safely/index.md +++ /dev/null @@ -1,91 +0,0 @@ ---- -title: "Accessibility: What users can do to browse more safely" -slug: Web/Accessibility/Accessibility:_What_users_can_to_to_browse_safely -page-type: guide ---- - -{{AccessibilitySidebar}} - -This article discusses making web content accessible for those with vestibular disorders, and those who support them, by taking advantage of personalization and accessibility settings built into the operating systems. Taking advantage of personalization settings can help prevent exposure to content leading to seizures and / or other physical reactions. - -## Personalization and accessibility settings - -From the article, "**[Understanding Success Criterion 2.3.1: Three Flashes or Below Threshold](https://www.w3.org/WAI/WCAG21/Understanding/three-flashes-or-below-threshold.html)**" - -> Flashing can be caused by the display, the computer rendering the image or by the content being rendered. The author has no control of the first two. They can be addressed by the design and speed of the display and computer - -### Hardware and operating systems on many computers offer control that is not afforded to developers - -The user can do much to protect himself by learning his operating system, its personalization and accessibility settings. Those in the public sector who must accommodate those with special sensitivities, should consider setting aside at least one work station and becoming familiar with its personalization and accessibility settings. Understanding personalization and accessibility settings can actually be a money-saving endeavor. One work station can be set up to accommodate both a low-vision individual (needs high-contrast) and to accommodate an individual with photosensitive susceptibilities, by, adjusting personalization and accessibility settings. - -### Use modern browsers. Learn personalization and accessibility settings - -Modern browsers support the CSS media feature [`prefers-reduced-motion`](/en-US/docs/Web/CSS/@media/prefers-reduced-motion). Browsers can detect whether a user has requested a reduced motion experience. The user would access this through an accessibility interface, as seen below. - -![Screen shot showing how to turn off animations in Windows 10.](android-remove-animations.png) - -CSS Transition events are supported. Examples include: - -- `transitionrun` -- `transitionstart` -- `transitionend` -- `transitioncancel` - -### Safari 10.1 and above (Desktop) - -Do not enable Auto-Play (does not work for GIFs) - -#### iOS Safari 10.3 and above (Mobile and Tablet) - -Select the "Reduce motion option" in OS Accessibility settings for Apple (image source: developers.google.com from Thomas Steiner's article "Move Ya! Or maybe, don't, if the user prefers-reduced-motion!"). This will not work on animated GIFs; the source of the animation is self-contained within a gif and is not affected by these settings.![Screen shot showing how to reduce motion on a MAC OS](macos-reduce-motion.png) - -#### Use Reader Mode on browsers - -- Enable Content Blockers; Gets rid of ads, reduces and/or removes distractions -- Enables text-to-speech -- In certain browsers, enable fonts by choice -- Enable Page Zoom - -#### Turn off animated GIFs in the browser - -Browsers offer much power to their users; it's just a matter of knowing where to go. Using Firefox as an example, it explains that by changing the value the **image.animation_mode** from "normal" to "none", all animated images will be blocked. To reverse it, you will have to change the value back to "normal" - -![Screenshot of image.animation.mode selected in Firefox](image_animation_mode.png) - -#### Use browser extensions - -- [Gif Blocker](https://chromewebstore.google.com/detail/gif-blocker/ahkidgegbmbnggcnmejhobepkaphkfhl?hl=en) For Chrome, GIF Blocker is an extension available at the web store. -- [Gif Scrubber](https://chromewebstore.google.com/detail/gif-scrubber/gbdacbnhlfdlllckelpdkgeklfjfgcmp?hl=en) Gif Scrubber is a chrome extension that allows you to control GIFs like a video player. There is a GitHub repository for it at **<https://github.com/0ui/gif-scrubber>** -- [Beeline Reader](https://www.beelinereader.com/) Beeline Reader has a browser extension that allows you to set up for grayscale and Dyslexi font, among other things - -![Screenshot showing modes of Beeline Reader a user can adjust in browser](beelinereader.png) - -### Take advantage Operating System accessibility features - -Most operating systems such as Windows 10, have accessibility options that are surprisingly powerful. Usually they are quite easy to find by typing (or saying) in the word, "Accessibility" in the search finder of the operating system. - -#### Turn off animations in the operating system - -In the Windows 10 operating system, the user has an ability to turn off animations. This will not work on animated GIFs; the source of the animation is self-contained within a gif and is not affected by these settings. - -![Screen shot showing how to turn off animations in Windows10](turnoffanimationsinwindows.png) - -#### Grayscale - -Those who have suffered traumatic brain injury (TBI) may be highly sensitive to color; it can require such a great "investment of cognitive energy" on their part, there's no energy for other daily tasks. Enabling grayscale presentation of the content reduces the cognitive workload. It may assist users with other disabilities, as well. An interesting discussion by users on the benefits of using grayscale may be found in the discussion thread, "[What is the "grayscale" setting for in accessibility options?](https://ask.metafilter.com/312049/What-is-the-grayscale-setting-for-in-accessibility-options)". Of particular interest is a user who has Photosensitive Epilepsy, and uses it when feeling "seizure-y". - -Most Operating Systems have a way to let the user make an adjustment on the workstation. In the screenshot below, you can see an example of Windows 10 Accessibility Settings allowing for color filters to be selected. Grayscale is enabled when the color filters button is toggled "on" - -![Shows Windows 10 Accessibility Settings for GrayScale](colorfiltersgrayscaleinwindows.png) - -## See also - -- [Accessibility](/en-US/docs/Web/Accessibility) -- [Accessibility learning path](/en-US/docs/Learn_web_development/Core/Accessibility) -- [Web accessibility for seizures and physical reactions](/en-US/docs/Web/Accessibility/Seizure_disorders) -- [Color vision simulation](https://firefox-source-docs.mozilla.org/devtools-user/accessibility_inspector/simulation/index.html) -- Discussion: "[What is the "grayscale" setting for in accessibility options?](https://ask.metafilter.com/312049/What-is-the-grayscale-setting-for-in-accessibility-options)" - -### Contributors - -Many, many thanks to Eric Eggert from [Knowbility;](https://knowbility.org/) for his discussions and huge help on this topic. diff --git a/files/en-us/web/accessibility/an_overview_of_accessible_web_applications_and_widgets/index.md b/files/en-us/web/accessibility/an_overview_of_accessible_web_applications_and_widgets/index.md deleted file mode 100644 index 3019d51ad6bc72d..000000000000000 --- a/files/en-us/web/accessibility/an_overview_of_accessible_web_applications_and_widgets/index.md +++ /dev/null @@ -1,178 +0,0 @@ ---- -title: An overview of accessible web applications and widgets -slug: Web/Accessibility/An_overview_of_accessible_web_applications_and_widgets -page-type: guide ---- - -{{AccessibilitySidebar}} - -Most JavaScript libraries offer a library of client-side widgets that mimic the behavior of familiar desktop interfaces. Sliders, menu bars, file list views, and more can be built with a combination of JavaScript, CSS, and HTML. Since the HTML4 specification doesn't provide built-in tags that semantically describe these kinds of widgets, developers typically resort to using generic elements such as {{HTMLElement('div')}} and {{HTMLElement('span')}}. While this results in a widget that looks like its desktop counterpart, there usually isn't enough semantic information in the markup to be usable by an assistive technology. - -## The problem - -Dynamic content on a web page can be particularly problematic for users who, for whatever reason, are unable to view the screen. Stock tickers, live twitter feed updates, progress indicators, and similar content modify the DOM in ways that an assistive technology (AT) may not be aware of. That's where [ARIA](/en-US/docs/Web/Accessibility/ARIA) comes in. - -_Example 1: Markup for a tabs widget built without ARIA labeling. There's no information in the markup to describe the widget's form and function._ - -```html -<!-- This is a tabs widget. How would you know, looking only at the markup? --> -<ol> - <li id="ch1Tab"> - <a href="#ch1Panel">Chapter 1</a> - </li> - <li id="ch2Tab"> - <a href="#ch2Panel">Chapter 2</a> - </li> - <li id="quizTab"> - <a href="#quizPanel">Quiz</a> - </li> -</ol> - -<div> - <div id="ch1Panel">Chapter 1 content goes here</div> - <div id="ch2Panel">Chapter 2 content goes here</div> - <div id="quizPanel">Quiz content goes here</div> -</div> -``` - -_Example 2: How the tabs widget might be styled visually. Users might recognize it visually, but there are no machine-readable semantics for an assistive technology._ ![Screenshot of the tabs widget](tabs_widget.png) - -## ARIA - -**ARIA** enables developers to describe their widgets in more detail by adding special attributes to the markup. Designed to fill the gap between standard HTML tags and the desktop-style controls found in dynamic web applications, ARIA provides roles and states that describe the behavior of most familiar UI widgets. - -> [!WARNING] -> Many of these were later added when browsers didn't fully support modern HTML features. **Developers should always prefer using the correct semantic HTML element over using ARIA**. - -The ARIA specification is split up into three different types of attributes: roles, states, and properties. Roles describe widgets that aren't otherwise available in HTML 4, such as sliders, menu bars, tabs, and dialogs. Properties describe characteristics of these widgets, such as if they are draggable, have a required element, or have a popup associated with them. States describe the current interaction state of an element, informing the assistive technology if it is busy, disabled, selected, or hidden. - -ARIA attributes are interpreted automatically by the browser and translated to the operating system's native accessibility APIs. So an element with role="slider" will be controlled in the same way as a native slider is controlled on the operating system. - -This provides a much more consistent user experience than was possible in the previous generation of web applications, since assistive technology users can apply all of their knowledge of how desktop applications work when they are using web-based applications. - -_Example 3: Markup for the tabs widget with ARIA attributes added._ - -```html -<!-- Now *these* are Tabs! --> -<!-- We've added role attributes to describe the tab list and each tab. --> -<ol role="tablist"> - <li id="ch1Tab" role="tab"> - <a href="#ch1Panel">Chapter 1</a> - </li> - <li id="ch2Tab" role="tab"> - <a href="#ch2Panel">Chapter 2</a> - </li> - <li id="quizTab" role="tab"> - <a href="#quizPanel">Quiz</a> - </li> -</ol> - -<div> - <!-- Notice the role and aria-labelledby attributes we've added to describe these panels. --> - <div id="ch1Panel" role="tabpanel" aria-labelledby="ch1Tab"> - Chapter 1 content goes here - </div> - <div id="ch2Panel" role="tabpanel" aria-labelledby="ch2Tab"> - Chapter 2 content goes here - </div> - <div id="quizPanel" role="tabpanel" aria-labelledby="quizTab"> - Quiz content goes here - </div> -</div> -``` - -ARIA is [well supported](https://caniuse.com/#feat=wai-aria) by all major browsers and many assistive technologies. - -### Presentational changes - -Dynamic presentational changes include using CSS to change the appearance of content (such as a red border around invalid data, or changing the background color of a checked checkbox), as well as showing or hiding content. - -#### State changes - -ARIA provides attributes for declaring the current state of a UI widget. Examples include (but are certainly not limited to): - -- `aria-checked` - - : Indicates the state of a checkbox or radio button. -- `aria-disabled` - - : Indicates that an element is visible but not editable or otherwise operable. -- `aria-grabbed` - - : Indicates the 'grabbed' state of an object in a drag-and-drop operation. - -(For a full list of ARIA states, consult the [ARIA list of states and properties](https://www.w3.org/TR/wai-aria-1.1/#introstates).) - -Developers should use ARIA states to indicate the state of UI widget elements and use CSS attribute selectors to alter the visual appearance based on the state changes (rather than using script to change a class name on the element). - -#### Visibility changes - -When content visibility is changed (i.e., an element is hidden or shown), developers should change the **`aria-hidden`** property value. The techniques described above should be used to declare CSS to visually hide an element using `display:none`. - -Here is an example of a tooltip that uses **`aria-hidden`** to control the visibility of the tooltip. The example shows a simple web form with tooltips containing instructions associated with the entry fields. - -```html -<div class="text"> - <label id="tp1-label" for="first">First Name:</label> - <input - type="text" - id="first" - name="first" - size="20" - aria-labelledby="tp1-label" - aria-describedby="tp1" - aria-required="false" /> - <div id="tp1" class="tooltip" role="tooltip" aria-hidden="true"> - Your first name is optional - </div> -</div> -``` - -The CSS for this markup is shown in the following code. Note that there is no custom classname used, only the status of the **`aria-hidden`** attribute. - -```css -div.tooltip[aria-hidden="true"] { - display: none; -} -``` - -The JavaScript to update the **`aria-hidden`** property has the form shown in the following code. Note that the script only updates the **`aria-hidden`** attribute; it does not need to also add or remove a custom classname. - -```js -function showTip(el) { - el.setAttribute("aria-hidden", "false"); -} -``` - -### Role changes - -ARIA allows developers to declare a semantic role for an element that otherwise offers incorrect or no semantics. The **`role`** of an element should not change. Instead, remove the original element and replace it with an element with the new **`role`**. - -For example, consider an "inline edit" widget: a component that allows users to edit a piece of text in place, without switching contexts. This component has a "view" mode, in which the text is not editable, but is activatable, and an "edit" mode, in which the text can be edited. A developer might be tempted to implement the "view" mode using a read-only text {{ HTMLElement("input") }} element and setting its ARIA **`role`** to `button`, then switching to "edit" mode by making the element writable and removing the **`role`** attribute in "edit" mode (since {{ HTMLElement("input") }} elements have their own role semantics). - -Do not do this. Instead, implement the "view" mode using a different element altogether, such as a {{ HTMLElement("div") }} or {{ HTMLElement("span") }} with a **`role`** of `button`, and the "edit" mode using a text {{ HTMLElement("input") }} element. - -### Asynchronous content changes - -> [!NOTE] -> Under construction. See also [Live Regions](/en-US/docs/Web/Accessibility/ARIA/ARIA_Live_Regions) - -## Keyboard navigation - -Often times developers overlook support for the keyboard when they create custom widgets. To be accessible to a variety of users, all features of a web application or widget should also be controllable with the keyboard, without requiring a mouse. In practice, this usually involves following the conventions supported by similar widgets on the desktop, taking full advantage of the Tab, Enter, Spacebar, and arrow keys. - -Traditionally, keyboard navigation on the web has been limited to the Tab key. A user presses Tab to focus each link, button, or form on the page in a linear order, using Shift-Tab to navigate backwards. It's a one-dimensional form of navigation—forward and back, one element at a time. On fairly dense pages, a keyboard-only user often has to press the Tab key dozens of times before accessing the needed section. Implementing desktop-style keyboard conventions on the web has the potential to significantly speed up navigation for many users. - -Here's a summary of how keyboard navigation should work in an ARIA-enabled web application: - -- The Tab key should provide focus to the widget as a whole. For example, tabbing to a menu bar **should NOT** put focus on the menu's first element. -- The arrow keys should allow for selection or navigation within the widget. For example, using the left and right arrow keys should move focus to the previous and next menu items. -- When the widget is not inside a form, both the Enter and Spacebar keys should select or activate the control. -- Within a form, the Spacebar key should select or activate the control, while the Enter key should submit the form's default action. -- If in doubt, mimic the standard desktop behavior of the control you are creating. - -So, for the Tabs widget example above, the user should be able to navigate into and out of the widget's container (the {{HTMLElement('ol')}} in our markup) using the Tab and Shift-Tab keys. Once keyboard focus is inside the container, the arrow keys should allow the user to navigate between each tab (the {{HTMLElement('li')}} elements). From here, conventions vary from platform to platform. On Windows, the next tab should automatically be activated when the user presses the arrow keys. On macOS, the user can press either Enter or the Spacebar to activate the next tab. An in-depth tutorial for creating [Keyboard-navigable JavaScript widgets](/en-US/docs/Web/Accessibility/Keyboard-navigable_JavaScript_widgets) describes how to implement this behavior with JavaScript. - -## See also - -- [ARIA](/en-US/docs/Web/Accessibility/ARIA) -- [Writing Keyboard-navigable JavaScript widgets](/en-US/docs/Web/Accessibility/Keyboard-navigable_JavaScript_widgets) -- [WAI-ARIA Specification](https://www.w3.org/TR/wai-aria-1.1/) -- [WAI-ARIA Authoring Practices](https://www.w3.org/WAI/ARIA/apg/) diff --git a/files/en-us/web/accessibility/aria/aria_guides/index.md b/files/en-us/web/accessibility/aria/aria_guides/index.md deleted file mode 100644 index 6e1e7dffb39a897..000000000000000 --- a/files/en-us/web/accessibility/aria/aria_guides/index.md +++ /dev/null @@ -1,28 +0,0 @@ ---- -title: ARIA guides -slug: Web/Accessibility/ARIA/ARIA_Guides -page-type: landing-page ---- - -{{AccessibilitySidebar}} - -Accessible Rich Internet Applications (**ARIA**) define ways to make the web more accessible to people with disabilities. -This page lists the guides that you can use to help improve the accessibility of web page features such as tables, forms, and keyboard-navigation. - -- [Designing accessible forms](https://www.w3.org/WAI/tutorials/forms/) -- [Understanding WAI-ARIA basics](/en-US/docs/Learn_web_development/Core/Accessibility/WAI-ARIA_basics) -- [Creating keyboard-navigable JavaScript widgets](/en-US/docs/Web/Accessibility/Keyboard-navigable_JavaScript_widgets) -- [Using ARIA for labels with embedded fields inside them](/en-US/docs/Web/Accessibility/ARIA/Multipart_labels) -- [Managing focus in composite widgets](https://www.w3.org/WAI/ARIA/apg/practices/keyboard-interface/) (`aria-activedescendant` vs. roving tabindex) -- [Testing ARIA](https://www.w3.org/WAI/test-evaluate/) -- [Displaying accessible tables](https://www.w3.org/WAI/tutorials/tables/) - -## See also - -The following references are helpful for common accessibility use cases: - -- [Labeling widgets](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-label) -- [Landmark roles](/en-US/docs/Web/Accessibility/ARIA/Roles/landmark_role) -- [ARIA live regions](/en-US/docs/Web/Accessibility/ARIA/ARIA_Live_Regions) -- [HTML Drag and Drop API](/en-US/docs/Web/API/HTML_Drag_and_Drop_API) -- [ARIA: presentation role](/en-US/docs/Web/Accessibility/ARIA/Roles/presentation_role) diff --git a/files/en-us/web/accessibility/aria/aria_live_regions/index.md b/files/en-us/web/accessibility/aria/aria_live_regions/index.md deleted file mode 100644 index a0ecb38c375ecab..000000000000000 --- a/files/en-us/web/accessibility/aria/aria_live_regions/index.md +++ /dev/null @@ -1,262 +0,0 @@ ---- -title: ARIA live regions -slug: Web/Accessibility/ARIA/ARIA_Live_Regions -page-type: guide ---- - -{{AccessibilitySidebar}} - -Using JavaScript, it is possible to dynamically change parts of a page without requiring the entire page to reload — for instance, to update a list of search results on the fly, or to display a discreet alert or notification which does not require user interaction. While these changes are usually visually apparent to users who can see the page, they may not be obvious to users of assistive technologies. ARIA live regions fill this gap and provide a way to programmatically expose dynamic content changes in a way that can be announced by assistive technologies. - -> [!NOTE] -> Assistive technologies will generally only announce _dynamic_ changes in the content of a live region. -> Including an `aria-live` attribute or a specialized live region `role` (such as [`role="status"`](/en-US/docs/Web/Accessibility/ARIA/Roles/status_role)) on the element you want to announce changes to works as long as you add the attribute before the changes occur — either in the original markup, or dynamically using JavaScript. Start with an empty live region, then – in a separate step – change the content inside the region. -> While not explicitly documented in the specification, browsers/assistive technologies do include special handling for [`role="alert"`](/en-US/docs/Web/Accessibility/ARIA/Roles/alert_role): in most cases, the content inside `role="alert"` regions is announced, even when the region (which already contains the notification/message) is present in the initial markup of the page, or injected dynamically into the page. However, note that `role="alert"` regions are – depending on the specific browser/assistive technology combination – automatically prefixed with "Alert" when they are announced. - -## Live regions - -Dynamic content which updates without a page reload is generally either a region or a widget. Simple content changes which are not interactive should be marked as live regions. A live region is explicitly denoted using the `aria-live` attribute. - -**`aria-live`**: The `aria-live=POLITENESS_SETTING` is used to set the priority with which screen reader should treat updates to live regions - the possible settings are: `off`, `polite` or `assertive`. This attribute is by far the most important. - -Normally, only `aria-live="polite"` is used. Any region which receives updates that are important for the user to receive, but not so rapid as to be annoying, should receive this attribute. The screen reader will speak changes whenever the user is idle. - -`aria-live="assertive"` should only be used for time-sensitive/critical notifications that absolutely require the user's immediate attention. Generally, a change to an assertive live region will interrupt any announcement a screen reader is currently making. As such, it can be extremely annoying and disruptive and should only be used sparingly. - -Unintuitively, `aria-live="off"` does not indicate that changes should not be announced. When an element has `aria-live="off"` (or has a `role` with this implicit value, such as `role="marquee"` or `role="timer"`), changes to the element's content are only supposed to be announced when focus is on, or inside, the element. - -### Basic example: Dropdown box updates useful onscreen information - -A website specializing in providing information about planets provides a dropdown box. When a planet is selected from the dropdown, a region on the page is updated with information about the selected planet. - -```html -<fieldset> - <legend>Planet information</legend> - <label for="planetsSelect">Planet:</label> - <select id="planetsSelect" aria-controls="planetInfo"> - <option value="">Select a planet…</option> - <option value="mercury">Mercury</option> - <option value="venus">Venus</option> - <option value="earth">Earth</option> - <option value="mars">Mars</option> - </select> - <button id="renderPlanetInfoButton">Go</button> -</fieldset> - -<div role="region" id="planetInfo" aria-live="polite"> - <h2 id="planetTitle">No planet selected</h2> - <p id="planetDescription">Select a planet to view its description</p> -</div> - -<p> - <small> - Information from - <a href="https://en.wikipedia.org/wiki/Solar_System">Wikipedia</a> - </small> -</p> -``` - -```js -const PLANETS_INFO = { - mercury: { - title: "Mercury", - description: - "Mercury is the smallest and innermost planet in the Solar System. It is named after the Roman deity Mercury, the messenger to the gods.", - }, - - venus: { - title: "Venus", - description: - "Venus is the second planet from the Sun. It is named after the Roman goddess of love and beauty.", - }, - - earth: { - title: "Earth", - description: - "Earth is the third planet from the Sun and the only object in the Universe known to harbor life.", - }, - - mars: { - title: "Mars", - description: - 'Mars is the fourth planet from the Sun and the second-smallest planet in the Solar System after Mercury. In English, Mars carries a name of the Roman god of war, and is often referred to as the "Red Planet".', - }, -}; - -function renderPlanetInfo(planet) { - const planetTitle = document.querySelector("#planetTitle"); - const planetDescription = document.querySelector("#planetDescription"); - - if (planet in PLANETS_INFO) { - planetTitle.textContent = PLANETS_INFO[planet].title; - planetDescription.textContent = PLANETS_INFO[planet].description; - } else { - planetTitle.textContent = "No planet selected"; - planetDescription.textContent = "Select a planet to view its description"; - } -} - -const renderPlanetInfoButton = document.querySelector( - "#renderPlanetInfoButton", -); - -renderPlanetInfoButton.addEventListener("click", (event) => { - const planetsSelect = document.querySelector("#planetsSelect"); - const selectedPlanet = - planetsSelect.options[planetsSelect.selectedIndex].value; - - renderPlanetInfo(selectedPlanet); -}); -``` - -{{EmbedLiveSample('Basic_example_Dropdown_box_updates_useful_onscreen_information', '', 350)}} - -As the user selects a new planet, the information in the live region will be announced. Because the live region has `aria-live="polite"`, the screen reader will wait until the user pauses before announcing the update. Thus, moving down in the list and selecting another planet will not announce updates in the live region. Updates in the live region will only be announced for the planet finally chosen. - -Here is a screenshot of VoiceOver on Mac announcing the update (via subtitles) to the live region: - -![A screenshot of VoiceOver on Mac announcing the update to a live region. Subtitles are shown in the picture.](web_accessibility_aria_aria_live_regions.png) - -## Roles with implicit live region attributes - -Elements with the following [`role="…"`](/en-US/docs/Web/Accessibility/ARIA/Roles) values act as live regions by default: - -<table style="width: 100%;"> - <thead> - <tr> - <th scope="col">Role</th> - <th scope="col">Description</th> - <th scope="col">Compatibility Notes</th> - </tr> - </thead> - <tbody> - <tr> - <td>log</td> - <td>Chat, error, game or other type of log</td> - <td>To maximize compatibility, add a redundant <code>aria-live="polite"</code> when using this role.</td> - </tr> - <tr> - <td>status</td> - <td>A status bar or area of the screen that provides an updated status of some kind. Screen reader users have a special command to read the current status.</td> - <td>To maximize compatibility, add a redundant <code>aria-live="polite"</code> when using this role.</td> - </tr> - <tr> - <td>alert</td> - <td>Error or warning message that flashes on the screen. Alerts are particularly important for client side validation notices to users. <a href="https://www.w3.org/WAI/ARIA/apg/example-index/alert/alert.html" class="external" rel="noopener">Alert Example.</a></td> - <td>To maximize compatibility, some people recommend adding a redundant <code>aria-live="assertive"</code> when using this role. However, adding both <code>aria-live</code> and <code>role="alert"</code> causes double speaking issues in VoiceOver on iOS.</td> - </tr> - <tr> - <td>progressbar</td> - <td>A hybrid between a widget and a live region. Use this with <code>aria-valuemin</code>, <code>aria-valuenow</code> and <code>aria-valuemax</code>. (TBD: add more info here).</td> - <td></td> - </tr> - <tr> - <td>marquee</td> - <td>Text which scrolls, such as a stock ticker.</td> - <td></td> - </tr> - <tr> - <td>timer</td> - <td>Any kind of timer or clock, such as a countdown timer or stopwatch readout.</td> - <td></td> - </tr> - </tbody> -</table> - -## Additional live region attributes - -Live Regions are well supported. The Paciello Group, in 2014, posted [information about the state of the support of Live Regions](https://www.tpgi.com/screen-reader-support-aria-live-regions/). Paul J. Adam has researched [the support of `aria-atomic` and `aria-relevant`](https://pauljadam.com/demos/aria-atomic-relevant.html) in particular. - -1. **`aria-atomic`**: The `aria-atomic=BOOLEAN` is used to set whether or not the screen reader should always present the live region as a whole, even if only part of the region changes. The possible settings are: `false` or `true`. The default setting is `false`. -2. [**`aria-relevant`**](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-relevant) - - : The `aria-relevant=[LIST_OF_CHANGES]` is used to set what types of changes are relevant to a live region. The possible settings are one or more of: `additions`, `removals`, `text`, `all`. The default setting is: `additions text`. - -### Basic examples: `aria-atomic` - -As an illustration of `aria-atomic`, consider a site with a simple clock, showing hours and minutes. The clock is updated each minute, with the new remaining time overwriting the current content. - -```html -<div id="clock" role="timer" aria-live="polite"> - <span id="clock-hours"></span> - <span id="clock-mins"></span> -</div> -``` - -```js -/* basic JavaScript to update the clock */ -function updateClock() { - const now = new Date(); - document.getElementById("clock-hours").textContent = now.getHours(); - document.getElementById("clock-mins").textContent = - `0${now.getMinutes()}`.substr(-2); -} - -/* first run */ -updateClock(); - -/* update every minute */ -setInterval(updateClock, 60000); -``` - -The first time the function executes, the entirety of the string that is added will be announced. On subsequent calls, only the parts of the content that changed compared to the previous content will be announced. For instance, when the clock changes from "17:33" to "17:34", assistive technologies will only announce "34", which won't be very useful to users. - -One way around this would be to first clear all the contents of the live region (in this case, set the `innerHTML` of both `<span id="clock-hours">` and `<span id="clock-mins">` to be empty), and then inject the new content. However, this can sometimes be unreliable, as it's dependent on the exact timing of these two updates. - -`aria-atomic="true"` ensures that each time the live region is updated, the entirety of the content is announced in full (e.g. "17:34"). - -```html -<div id="clock" role="timer" aria-live="polite" aria-atomic="true">…</div> -``` - -Another example of `aria-atomic` - an update/notification made as a result of a user action. - -```html -<div id="date-input"> - <label for="year">Year:</label> - <input type="text" id="year" value="1990" onblur="change(event)" /> -</div> - -<div id="date-output" aria-atomic="true" aria-live="polite"> - The set year is: - <span id="year-output">1990</span> -</div> -``` - -```js -function change(event) { - const yearOut = document.getElementById("year-output"); - - switch (event.target.id) { - case "year": - yearOut.textContent = event.target.value; - break; - default: - return; - } -} -``` - -Without `aria-atomic="true"` the screen reader announces only the changed value of year. With `aria-atomic="true"`, the screen reader announces "The set year is: _changed value_" - -### Basic example: `aria-relevant` - -With `aria-relevant` you can specify which types of changes/updates to a live region should be announced. - -As an example, consider a chat site that wants to display a list of users currently logged in. Rather than just announcing the users that are currently logged in, we also want to trigger an announcement specifically when a user is _removed_ from the list. We can achieve this by specifying `aria-relevant="additions removals"`. - -```html -<ul id="roster" aria-live="polite" aria-relevant="additions removals"> - <!-- use JavaScript to add and remove users here --> -</ul> -``` - -Breakdown of ARIA live properties: - -- `aria-live="polite"` indicates that the screen reader should wait until the user is idle before presenting updates to the user. This is the most commonly used value, as interrupting the user with "assertive" might interrupt their flow. -- `aria-atomic` is not set (`false` by default) so that only the added or removed users should be spoken and not the entire roster each time. -- `aria-relevant="additions removals"` ensures that both users added or removed to the roster will be spoken. - -## See also - -- [ARIA roles](/en-US/docs/Web/Accessibility/ARIA/Roles) diff --git a/files/en-us/web/accessibility/aria/aria_screen_reader_implementors_guide/index.md b/files/en-us/web/accessibility/aria/aria_screen_reader_implementors_guide/index.md deleted file mode 100644 index 951f7649305b489..000000000000000 --- a/files/en-us/web/accessibility/aria/aria_screen_reader_implementors_guide/index.md +++ /dev/null @@ -1,27 +0,0 @@ ---- -title: ARIA Screen Reader Implementors Guide -slug: Web/Accessibility/ARIA/ARIA_Screen_Reader_Implementors_Guide -page-type: guide ---- - -{{AccessibilitySidebar}} - -## Live Regions - -This is just a guide. Live region markup is a complex area which is somewhat open to interpretation. The following is intended to provide implementation guidance that respects screen readers developers' need to try different things. The intention is to strike a balance between providing useful guidance on how to use the markup's intended meaning while supporting live regions as an area for screen readers to innovate and compete. - -### Interpreting WAI-ARIA live region markup - -1. Live changes are hints: in general live region markup is provided by the author as hints, and the assistive technology may allow for global, site or even region-specific settings, as well as heuristics to help with live changes on pages that have no WAI-ARIA hints. -2. Optionally, create a second, additional queue if the user configures a second hardware channel: If there are two channels for presentation (e.g. text to speech and a Braille display), then two queues can be maintained to allow for parallel presentation. The channels could be user configured for presenting live regions based on role or politeness. -3. Busy regions: Any changes in a region marked with aria-busy="true" should not be added to the queue until that attribute is cleared. -4. Politeness (`aria-live` or from [role](/en-US/docs/Web/Accessibility/ARIA/Roles)) takes first precedence,: items should be added to the queue based on their politeness level from the `aria-live` property or inherited from the `role` (e.g. [role="log"](/en-US/docs/Web/Accessibility/ARIA/Roles/log_role) is polite by default). Assertive items are first then politeness level. Alternatively, implementations may choose to have a policy of clearing more polite items, e.g. assertive items clear any polite items from the queue. -5. Time takes second precedence: Prioritize items with the same politeness level according to when the event occurs (earlier events come first). Present items of the same politeness level in the order of what occurred first. -6. Atomic (`aria-atomic="true"`) regions with multiple changes should not be presented twice with the same content. As a new event for an atomic region is added to the queue remove an earlier event for the same region. It is probably desirable to have at least a tiny timeout before presenting atomic region changes, in order to avoid presenting the region twice for two changes that occur quickly one after the other. -7. Include labels when presenting changes: if the change occurs in something with a semantic label of some kind, speak the label. This is particularly important for changes in data cells, where the column and row headers provide important contextual information. - -### Ideas for Settings and Heuristics - -1. Allow for a different voice (in text-to-speech) or other varying presentational characteristics to set live changes apart. -2. When no WAI-ARIA markup is present, automatically present some changes unless the user configures all live changes to off. For example, automatically speak changes that are caused by the user's own input, as part of the context of that input. -3. Allow global settings to turn off the presentation of live changes, present all live changes, use markup, or be "smart" (use heuristics) diff --git a/files/en-us/web/accessibility/aria/aria_techniques/index.md b/files/en-us/web/accessibility/aria/aria_techniques/index.md deleted file mode 100644 index 77fdca8b3b9b91b..000000000000000 --- a/files/en-us/web/accessibility/aria/aria_techniques/index.md +++ /dev/null @@ -1,166 +0,0 @@ ---- -title: "Using ARIA: Roles, states, and properties" -slug: Web/Accessibility/ARIA/ARIA_Techniques -page-type: guide ---- - -{{AccessibilitySidebar}} - -ARIA defines semantics that can be applied to elements, with these divided into **roles** (defining a type of user interface element) and **states** and **properties** that are supported by a role. Authors must assign an ARIA role and the appropriate states and properties to an element during its life-cycle, unless the element already has appropriate ARIA semantics (via use of an appropriate HTML element). Addition of ARIA semantics only exposes extra information to a browser's accessibility API, and does not affect a page's DOM. - -## Roles - -### Widget roles - -- [`button`](/en-US/docs/Web/Accessibility/ARIA/Roles/button_role) -- [`checkbox`](/en-US/docs/Web/Accessibility/ARIA/Roles/checkbox_role) -- [`gridcell`](/en-US/docs/Web/Accessibility/ARIA/Roles/gridcell_role) -- [`link`](/en-US/docs/Web/Accessibility/ARIA/Roles/link_role) -- [`menuitem`](/en-US/docs/Web/Accessibility/ARIA/Roles/menuitem_role) -- [`menuitemcheckbox`](/en-US/docs/Web/Accessibility/ARIA/Roles/menuitemcheckbox_role) -- [`menuitemradio`](/en-US/docs/Web/Accessibility/ARIA/Roles/menuitemradio_role) -- [`option`](/en-US/docs/Web/Accessibility/ARIA/Roles/option_role) -- [`progressbar`](/en-US/docs/Web/Accessibility/ARIA/Roles/progressbar_role) -- [`radio`](/en-US/docs/Web/Accessibility/ARIA/Roles/radio_role) -- [`scrollbar`](/en-US/docs/Web/Accessibility/ARIA/Roles/scrollbar_role) -- [`searchbox`](/en-US/docs/Web/Accessibility/ARIA/Roles/searchbox_role) -- [`separator`](/en-US/docs/Web/Accessibility/ARIA/Roles/separator_role) (when focusable) -- [`slider`](/en-US/docs/Web/Accessibility/ARIA/Roles/slider_role) -- [`spinbutton`](/en-US/docs/Web/Accessibility/ARIA/Roles/spinbutton_role) -- [`switch`](/en-US/docs/Web/Accessibility/ARIA/Roles/switch_role) -- [`tab`](/en-US/docs/Web/Accessibility/ARIA/Roles/tab_role) -- [`tabpanel`](/en-US/docs/Web/Accessibility/ARIA/Roles/tabpanel_role) -- [`textbox`](/en-US/docs/Web/Accessibility/ARIA/Roles/textbox_role) -- [`treeitem`](/en-US/docs/Web/Accessibility/ARIA/Roles/treeitem_role) - -### Composite roles - -The techniques below describe each composite role as well as their required and optional child roles. - -- [`combobox`](/en-US/docs/Web/Accessibility/ARIA/Roles/combobox_role) -- [`grid`](/en-US/docs/Web/Accessibility/ARIA/Roles/grid_role) (including [`row`](/en-US/docs/Web/Accessibility/ARIA/Roles/row_role), [`gridcell`](/en-US/docs/Web/Accessibility/ARIA/Roles/gridcell_role), [`rowheader`](/en-US/docs/Web/Accessibility/ARIA/Roles/rowheader_role), [`columnheader`](/en-US/docs/Web/Accessibility/ARIA/Roles/columnheader_role) roles) -- [`listbox`](/en-US/docs/Web/Accessibility/ARIA/Roles/listbox_role) (including [`option`](/en-US/docs/Web/Accessibility/ARIA/Roles/option_role) role) -- [`menu`](/en-US/docs/Web/Accessibility/ARIA/Roles/menu_role) -- [`menubar`](/en-US/docs/Web/Accessibility/ARIA/Roles/menubar_role) -- [`radiogroup`](/en-US/docs/Web/Accessibility/ARIA/Roles/radiogroup_role) (see [`radio` role](/en-US/docs/Web/Accessibility/ARIA/Roles/radio_role)) -- [`tablist`](/en-US/docs/Web/Accessibility/ARIA/Roles/tablist_role) (including [`tab`](/en-US/docs/Web/Accessibility/ARIA/Roles/tab_role) and [`tabpanel`](/en-US/docs/Web/Accessibility/ARIA/Roles/tabpanel_role) roles) -- [`tree`](/en-US/docs/Web/Accessibility/ARIA/Roles/tree_role) -- [`treegrid`](/en-US/docs/Web/Accessibility/ARIA/Roles/treegrid_role) - -### Document structure roles - -- [`application`](/en-US/docs/Web/Accessibility/ARIA/Roles/application_role) -- [`article`](/en-US/docs/Web/Accessibility/ARIA/Roles/article_role) -- [`cell`](/en-US/docs/Web/Accessibility/ARIA/Roles/cell_role) -- [`columnheader`](/en-US/docs/Web/Accessibility/ARIA/Roles/columnheader_role) -- [`definition`](/en-US/docs/Web/Accessibility/ARIA/Roles/definition_role) -- [`directory`](/en-US/docs/Web/Accessibility/ARIA/Roles/directory_role) -- [`document`](/en-US/docs/Web/Accessibility/ARIA/Roles/document_role) -- [`feed`](/en-US/docs/Web/Accessibility/ARIA/Roles/feed_role) -- [`figure`](/en-US/docs/Web/Accessibility/ARIA/Roles/figure_role) -- [`group`](/en-US/docs/Web/Accessibility/ARIA/Roles/group_role) -- [`heading`](/en-US/docs/Web/Accessibility/ARIA/Roles/heading_role) -- [`img`](/en-US/docs/Web/Accessibility/ARIA/Roles/img_role) -- [`list`](/en-US/docs/Web/Accessibility/ARIA/Roles/list_role) -- [`listitem`](/en-US/docs/Web/Accessibility/ARIA/Roles/listitem_role) -- [`math`](/en-US/docs/Web/Accessibility/ARIA/Roles/math_role) -- [`none`](/en-US/docs/Web/Accessibility/ARIA/Roles/none_role) -- [`note`](/en-US/docs/Web/Accessibility/ARIA/Roles/note_role) -- [`presentation`](/en-US/docs/Web/Accessibility/ARIA/Roles/presentation_role) -- [`row`](/en-US/docs/Web/Accessibility/ARIA/Roles/row_role) -- [`rowgroup`](/en-US/docs/Web/Accessibility/ARIA/Roles/rowgroup_role) -- [`rowheader`](/en-US/docs/Web/Accessibility/ARIA/Roles/rowheader_role) -- [`separator`](/en-US/docs/Web/Accessibility/ARIA/Roles/separator_role) -- [`table`](/en-US/docs/Web/Accessibility/ARIA/Roles/table_role) -- [`term`](/en-US/docs/Web/Accessibility/ARIA/Roles/term_role) -- [`toolbar`](/en-US/docs/Web/Accessibility/ARIA/Roles/toolbar_role) -- [`tooltip`](/en-US/docs/Web/Accessibility/ARIA/Roles/tooltip_role) - -### Landmark roles - -- [`banner`](/en-US/docs/Web/Accessibility/ARIA/Roles/banner_role) -- [`complementary`](/en-US/docs/Web/Accessibility/ARIA/Roles/complementary_role) -- [`contentinfo`](/en-US/docs/Web/Accessibility/ARIA/Roles/contentinfo_role) -- [`form`](/en-US/docs/Web/Accessibility/ARIA/Roles/form_role) -- [`main`](/en-US/docs/Web/Accessibility/ARIA/Roles/main_role) -- [`navigation`](/en-US/docs/Web/Accessibility/ARIA/Roles/navigation_role) -- [`region`](/en-US/docs/Web/Accessibility/ARIA/Roles/region_role) -- [`search`](/en-US/docs/Web/Accessibility/ARIA/Roles/search_role) - -### Live Region Roles - -- [`alert`](/en-US/docs/Web/Accessibility/ARIA/Roles/alert_role) -- [`log`](/en-US/docs/Web/Accessibility/ARIA/Roles/log_role) -- [`marquee`](/en-US/docs/Web/Accessibility/ARIA/Roles/marquee_role) -- [`status`](/en-US/docs/Web/Accessibility/ARIA/Roles/status_role) -- [`timer`](/en-US/docs/Web/Accessibility/ARIA/Roles/timer_role) - -### Window Roles - -- [`alertdialog`](/en-US/docs/Web/Accessibility/ARIA/Roles/alertdialog_role) -- [`dialog`](/en-US/docs/Web/Accessibility/ARIA/Roles/dialog_role) - -## States and properties - -### Widget attributes - -- [`aria-autocomplete`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-autocomplete) -- [`aria-checked`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-checked) -- [`aria-current`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-current) -- [`aria-disabled`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-disabled) -- [`aria-errormessage`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-errormessage) -- [`aria-expanded`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-expanded) -- [`aria-haspopup`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-haspopup) -- [`aria-hidden`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-hidden) -- [`aria-invalid`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-invalid) -- [`aria-label`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-label) -- [`aria-level`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-level) -- [`aria-modal`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-modal) -- [`aria-multiline`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-multiline) -- [`aria-multiselectable`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-multiselectable) -- [`aria-orientation`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-orientation) -- [`aria-placeholder`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-placeholder) -- [`aria-pressed`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-pressed) -- [`aria-readonly`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-readonly) -- [`aria-required`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-required) -- [`aria-selected`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-selected) -- [`aria-sort`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-sort) -- [`aria-valuemax`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-valuemax) -- [`aria-valuemin`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-valuemin) -- [`aria-valuenow`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-valuenow) -- [`aria-valuetext`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-valuetext) - -### Live region attributes - -- [`aria-live`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-live) -- [`aria-relevant`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-relevant) -- [`aria-atomic`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-atomic) -- [`aria-busy`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-busy) - -### Drag &amp; drop attributes - -- [`aria-dropeffect`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-dropeffect) {{deprecated_inline}} -- [`aria-grabbed`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-grabbed) {{deprecated_inline}} - -### Relationship attributes - -- [`aria-activedescendant`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-activedescendant) -- [`aria-colcount`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-colcount) -- [`aria-colindex`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-colindex) -- [`aria-colspan`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-colspan) -- [`aria-controls`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-controls) -- [`aria-describedby`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-describedby) -- [`aria-details`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-details) -- [`aria-errormessage`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-errormessage) -- [`aria-flowto`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-flowto) -- [`aria-labelledby`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-labelledby) -- [`aria-owns`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-owns) -- [`aria-posinset`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-posinset) -- [`aria-rowcount`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-rowcount) -- [`aria-rowindex`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-rowindex) -- [`aria-rowspan`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-rowspan) -- [`aria-setsize`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-setsize) - -### MicrosoftEdge-specific properties - -- `x-ms-aria-flowfrom` {{Non-standard_Inline}} diff --git a/files/en-us/web/accessibility/aria/attributes/aria-activedescendant/index.md b/files/en-us/web/accessibility/aria/attributes/aria-activedescendant/index.md deleted file mode 100644 index 1f8f7a02885d0c0..000000000000000 --- a/files/en-us/web/accessibility/aria/attributes/aria-activedescendant/index.md +++ /dev/null @@ -1,53 +0,0 @@ ---- -title: aria-activedescendant -slug: Web/Accessibility/ARIA/Attributes/aria-activedescendant -page-type: aria-attribute -spec-urls: - - https://w3c.github.io/aria/#aria-activedescendant - - https://www.w3.org/TR/wai-aria-1.2/#aria-activedescendant ---- - -{{AccessibilitySidebar}} - -The `aria-activedescendant` attribute identifies the currently active element when focus is on a [`composite`](/en-US/docs/Web/Accessibility/ARIA/Roles/composite_role) widget, [`combobox`](/en-US/docs/Web/Accessibility/ARIA/Roles/combobox_role), [`textbox`](/en-US/docs/Web/Accessibility/ARIA/Roles/textbox_role), [`group`](/en-US/docs/Web/Accessibility/ARIA/Roles/group_role), or [`application`](/en-US/docs/Web/Accessibility/ARIA/Roles/application_role). - -## Description - -The `aria-activedescendant` property provides a method of managing focus for assistive technologies on interactive elements when they contain multiple focusable descendants, such as menus, grids, and toolbars. Instead of the screen reader moving focus between owned elements, `aria-activedescendant` can be used on container elements to refer to the currently active element, informing assistive technology users of the currently active element when focused. - -With `aria-activedescendant`, the browser keeps the DOM focus on the container element or on an input element that controls the container element. However, the user agent communicates desktop focus events and states to the assistive technology as if the element referenced by `aria-activedescendant` has focus. - -This attribute is only relevant on elements with role of [`composite`](/en-US/docs/Web/Accessibility/ARIA/Roles/composite_role) widget, [`combobox`](/en-US/docs/Web/Accessibility/ARIA/Roles/combobox_role), [`textbox`](/en-US/docs/Web/Accessibility/ARIA/Roles/textbox_role), [`group`](/en-US/docs/Web/Accessibility/ARIA/Roles/group_role), or [`application`](/en-US/docs/Web/Accessibility/ARIA/Roles/application_role) whose `id` is referenced as the attribute value. - -The attribute manages providing assistive technologies with information as to which element has focus, but doesn't actually create focus. Changing focus and managing the attributes value is done with JavaScript. In addition to managing that attribute value, make sure the currently active descendant is visible and in view (or scrolls into view) when focused. - -In setting the value of `aria-activedescendant` on an element with DOM focus, ensure the value refers to an owned element—either a descendant of the element with DOM focus OR a logical descendant as indicated by the [`aria-owns`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-owns) attribute. - -When the element with DOM focus is a combobox, textbox, or searchbox, include [`aria-controls`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-controls) to refer to the element that supports `aria-activedescendant`. - -The value of `aria-activedescendant` refers to an owned element of the controlled element. For example, in a combobox, focus may remain on the combobox while the value of `aria-activedescendant` on the combobox element refers to a descendant of a popup listbox that is controlled by the combobox. - -> [!NOTE] -> The attribute is supported only on a few roles. For example, `dialog`s do not support `aria-activedescendant`. When a combobox opens a dialog, DOM focus moves into the dialog from the combobox as it is not referenceable with this attribute. - -> [!NOTE] -> When a descendant of a `listbox`, `grid`, or `tree` popup is focused, DOM focus remains on the combobox and the combobox has `aria-activedescendant` set to a value that refers to the focused element within the popup. - -## Values - -- ID reference - - : takes as its value the `id` of the currently focused element. - -## Associated roles - -Relevant only as an attribute on elements with the following roles: - -- [`application`](/en-US/docs/Web/Accessibility/ARIA/Roles/application_role) -- [`combobox`](/en-US/docs/Web/Accessibility/ARIA/Roles/combobox_role) -- [`composite`](/en-US/docs/Web/Accessibility/ARIA/Roles/composite_role) -- [`group`](/en-US/docs/Web/Accessibility/ARIA/Roles/group_role) -- [`textbox`](/en-US/docs/Web/Accessibility/ARIA/Roles/textbox_role) - -## Specifications - -{{Specifications}} diff --git a/files/en-us/web/accessibility/aria/attributes/aria-atomic/index.md b/files/en-us/web/accessibility/aria/attributes/aria-atomic/index.md deleted file mode 100644 index b553c8cde19f68f..000000000000000 --- a/files/en-us/web/accessibility/aria/attributes/aria-atomic/index.md +++ /dev/null @@ -1,37 +0,0 @@ ---- -title: aria-atomic -slug: Web/Accessibility/ARIA/Attributes/aria-atomic -page-type: aria-attribute -spec-urls: https://w3c.github.io/aria/#aria-atomic ---- - -{{AccessibilitySidebar}} - -In ARIA live regions, the global `aria-atomic` attribute indicates whether assistive technologies such as a screen reader will present all, or only parts of, the changed region based on the change notifications defined by the [`aria-relevant`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-relevant) attribute. - -## Description - -Live regions are sections of a web page that are updated, whether by user interaction or not, when user focus is elsewhere. As they update outside the user's focus, assistive technologies such as screen readers may not "see" the update to report it to the user. WAI-ARIA has 4 properties that allow the developer to identify these live regions and tell the assistive technology how to process them, including [`aria-live`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-live), [`aria-relevant`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-relevant), [`aria-busy`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-busy) and `aria-atomic`. - -When the content of a live region changes, the DOM is traversed from the changed element through its ancestors to find the first element with `aria-atomic` set. This determines the content that the user should be presented with. - -If no ancestor has explicitly set `aria-atomic`, only the node or nodes of live region content that have been updated are read. The difference between omitting `aria-atomic` altogether and explicitly setting an ARIA live region's ancestor node with `aria-atomic="false"` is that explicitly setting `aria-atomic="false"` will stop the screen reader from going up the ancestor chain. Both lead to only the updated node being read. When set to `aria-atomic="true"`, the entire changed region as a whole will be presented, including the updated node's `label`, if there is one. - -## Values - -- `false` (default) - - : present only the changed node or nodes. -- `true` - - : present the entire changed region as a whole, including the author-defined label if one exists. - -## Associated roles - -Used in **ALL** [roles](/en-US/docs/Web/Accessibility/ARIA/Roles). - -## Specifications - -{{Specifications}} - -## See also - -- [Event.ariaAtomic](/en-US/docs/Web/API/Element/ariaAtomic) diff --git a/files/en-us/web/accessibility/aria/attributes/aria-autocomplete/index.md b/files/en-us/web/accessibility/aria/attributes/aria-autocomplete/index.md deleted file mode 100644 index 412f467365ff85e..000000000000000 --- a/files/en-us/web/accessibility/aria/attributes/aria-autocomplete/index.md +++ /dev/null @@ -1,69 +0,0 @@ ---- -title: aria-autocomplete -slug: Web/Accessibility/ARIA/Attributes/aria-autocomplete -page-type: aria-attribute -spec-urls: - - https://w3c.github.io/aria/#aria-autocomplete, - - https://www.w3.org/WAI/ARIA/apg/patterns/combobox/examples/combobox-autocomplete-both/ ---- - -{{AccessibilitySidebar}} - -The `aria-autocomplete` attribute indicates whether inputting text could trigger display of one or more predictions of the user's intended value for a [`combobox`](/en-US/docs/Web/Accessibility/ARIA/Roles/combobox_role), [`searchbox`](/en-US/docs/Web/Accessibility/ARIA/Roles/searchbox_role), or [`textbox`](/en-US/docs/Web/Accessibility/ARIA/Roles/textbox_role) and specifies how predictions will be presented if they are made. - -## Description - -Autocompletion is user interface feature wherein inline suggestions are made as a user types in an input. Suggested text for completing the value of the field dynamically appears in the field after the input cursor, and the suggested value becomes the value if the user performs an action, such as tabbing, that causes focus to leave the field. - -The `aria-autocomplete` property describes the type of autocompletion interaction model a textbox, searchbox, or combobox will use when dynamically helping users complete text input. It distinguishes between two models: the **inline** model (`aria-autocomplete="inline"`), which presents a single predicted value and the **list** model (`aria-autocomplete="list"`), which presents a collection of possible values in a separate element that pops up next to or below the text input, similar to a {{HTMLElement('datalist')}}. A third value, `aria-autocomplete="both"` is for when the interface will present a list while also including a predicted value. The default is `none`, meaning the textbox, searchbox, or combobox will not provide an auto complete value. - -The `aria-autocomplete` property only describes the type of predictive behavior for an input element for assistive technologies; it doesn't provide the functionality. The actual autocompletion should be provided using HTML attributes or JavaScript. - -If the suggested autocomplete value provides suggested values that aren't dependent on the input provided by the user, consider omitting autocomplete for everyone. For example, a searchbox input displaying unfiltered recent search terms may be helpful to a marketing team on an e-commerce site, but likely isn't helpful for the screen reader user. When it is best to not specify a value for `aria-autocomplete` or to set the value to the `none` default, likely your non-assistive technology users also don't need the experience. - -When implementing autocomplete functionality, ensure the suggested portion of the value is presented as selected text to enable distinguishing between a user's input and the suggestion. Make sure that when the suggested value is not the desired value, users can easily delete the suggestion or replace it by continuing to type. - -When implementing a list of values, DOM focus should remain on the text input while the suggestion list is displayed. - -- include [`aria-controls`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-controls) with the value of the id of the suggested list of values. -- include [`aria-haspopup`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-haspopup) matching the role of the element that contains the collection of suggested values. -- manage focus, if required, including using [`aria-activedescendant`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-activedescendant) if the collection container supports. -- use the [`aria-expanded`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-expanded) state on the element with role [`combobox`](/en-US/docs/Web/Accessibility/ARIA/Roles/combobox_role) to communicate that the list is displayed. - -If an autocomplete list value is automatically accepted when the field loses focus, the list must be contained in a role that supports `aria-activedescendant`, with the value of `aria-activedescendant` on the input field dynamically adjusted to refer to the element containing the selected suggestion. - -## Values - -- `none` (default) - - : When a user is providing input, no automatic suggestion is displayed. -- `inline` - - : `aria-autocomplete="inline"` text suggesting one way to complete the provided input may be dynamically inserted after the caret. -- `list` - - : `aria-autocomplete="list"` When a user is providing input, an element containing a collection of values that could complete the provided input may be displayed. -- `both` - - : `aria-autocomplete="both"` an input to offer both models at the same time. When a user is providing input, an element containing a collection of values that could complete the provided input may be displayed. If displayed, one value in the collection is automatically selected, and the text needed to complete the automatically selected value appears after the caret in the input. - -## Associated roles - -Used in roles: - -- [`combobox`](/en-US/docs/Web/Accessibility/ARIA/Roles/combobox_role) role -- [`textbox`](/en-US/docs/Web/Accessibility/ARIA/Roles/textbox_role) role -- inherits from [`searchbox`](/en-US/docs/Web/Accessibility/ARIA/Roles/searchbox_role) role - -## Specifications - -{{Specifications}} - -## See also - -- [`combobox`](/en-US/docs/Web/Accessibility/ARIA/Roles/combobox_role) role -- [`textbox`](/en-US/docs/Web/Accessibility/ARIA/Roles/textbox_role) role -- [`searchbox`](/en-US/docs/Web/Accessibility/ARIA/Roles/searchbox_role) role -- {{HTMLElement('datalist')}} element and the [`<input> list` attribute](/en-US/docs/Web/HTML/Element/input#list) -- [`aria-controls`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-controls) attribute -- [`aria-haspopup`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-haspopup) attribute -- [`aria-activedescendant`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-activedescendant) attribute -- [`aria-expanded`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-expanded) attribute -- [Editable Combobox With Both List and Inline Autocomplete Example](https://www.w3.org/TR/wai-aria-practices-1.2/examples/combobox/combobox-autocomplete-both.html) -- [Event.ariaAutoComplete](/en-US/docs/Web/API/Element/ariaAutoComplete) diff --git a/files/en-us/web/accessibility/aria/attributes/aria-braillelabel/index.md b/files/en-us/web/accessibility/aria/attributes/aria-braillelabel/index.md deleted file mode 100644 index 6594394fb43fefe..000000000000000 --- a/files/en-us/web/accessibility/aria/attributes/aria-braillelabel/index.md +++ /dev/null @@ -1,57 +0,0 @@ ---- -title: aria-braillelabel -slug: Web/Accessibility/ARIA/Attributes/aria-braillelabel -page-type: aria-attribute -spec-urls: https://w3c.github.io/aria/#aria-braillelabel ---- - -{{AccessibilitySidebar}} - -The global `aria-braillelabel` property defines a string value that labels the current element, which is intended to be converted into Braille. - -## Description - -The global `aria-braillelabel` attribute is similar to the global [`aria-label`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-label) in that it defines a string value that labels the current element. While `aria-label` is read by the screen reader, the contents of the `aria-braillelabel` attribute are converted into Braille; providing the user with a recognizable name of the object in braille. - -The purpose of the `aria-braillelabel` property is to override how assistive technologies localize and express the accessible name of an element in Braille. It should only be used when, without this attribute, the accessible name would not be the desired user experience when converted to braille. - -When using `aria-braillelabel`, ensure that: - -- The element to which `aria-braillelabel` is applied has a valid accessible name. -- The value of `aria-braillelabel` has actual content and is not empty or only whitespace in unicode or unicode braille. -- The value is NOT the same as the accessible name. -- The `aria-braillelabel` values are localized to align with the document language. -- Communicate to the user that this attribute is available, especially if the content contains unicode braille patterns, so the user knows to set the settings to apply user specific braille translations - -> [!NOTE] -> Assistive technologies with braille support can convert the accessible names to braille. -> Therefore, only use `aria-braillelabel` when the accessible name is not the user experience you want. - -Using only the accessible name, e.g., from content or via `aria-label` is almost always the better user experience, so don't use aria-braillelabel to replicate aria-label. Only use `aria-braillelabel` if the accessible name cannot provide an adequate braille representation. - -```html -<button aria-braillelabel="***"> - <img alt="3 out of 5 stars" src="three_stars.png" /> -</button> -``` - -A braille display may display "btn \*\*\*" in Braille rather than the more verbose "btn gra 3 out of 5 stars". - -## Values - -- `<string>` - - : The value is a string, an unconstrained value type, that is intended to be converted into braille. - -## Associated roles - -Used in **ALL** roles. - -## Specifications - -{{Specifications}} - -## See also - -- {{domxref("Element.ariaBrailleLabel")}} -- [`aria-label`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-label) -- [`aria-brailleroledescription`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-brailleroledescription) diff --git a/files/en-us/web/accessibility/aria/attributes/aria-brailleroledescription/index.md b/files/en-us/web/accessibility/aria/attributes/aria-brailleroledescription/index.md deleted file mode 100644 index 7ce21ddaeda1c1a..000000000000000 --- a/files/en-us/web/accessibility/aria/attributes/aria-brailleroledescription/index.md +++ /dev/null @@ -1,77 +0,0 @@ ---- -title: aria-brailleroledescription -slug: Web/Accessibility/ARIA/Attributes/aria-brailleroledescription -page-type: aria-attribute -spec-urls: https://w3c.github.io/aria/#aria-brailleroledescription ---- - -{{AccessibilitySidebar}} - -The global `aria-brailleroledescription` attribute defines a human-readable, author-localized abbreviated description for the role of an element intended to be converted into Braille. - -## Description - -Braille is not a one-to-one transliteration of letters and numbers, but rather it includes various abbreviations, contractions, and characters that represent words (known as logograms). - -Instead of converting long role descriptions to Braille, the `aria-brailleroledescription` attribute allows for providing an abbreviated version of the [`aria-roledescription`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-roledescription) value, which is a human-readable, author-localized description for the role of an element, for improved user experience with braille interfaces. - -Basically, the value of `aria-brailleroledescription` is an abbreviated version of the `aria-roledescription` attribute to be converted into Braille. - -```html -<article - aria-roledescription="slide" - aria-brailleroledescription="sld" - aria-labelledby="slide1heading"> - <h1 id="slide1heading">Welcome to my talk</h1> - <img alt="Me" src="images/me.jpg" /> -</article> -``` - -Most assistive technologies, like screen readers, will read the above as "slide, welcome to my talk. Image, Me." Braille assistive technologies will present "sld welcome to my talk gra me" in braille. The semantic {{HTMLElement('article')}} is given the role of "slide" by the `aria-roledescription` attribute; "slide" being a role not defined in the specification, but is a common role for slides in a presentation. In Braille, the role is presented as "sld". The "gra" is short for "graphic", which is how the "image" role is shortened in braille. - -The `aria-brailleroledescription` attribute should only be used to clarify the purpose of non-interactive container roles like "group" or "region", or to provide a more specific description of a widget in a braille context. - -As the `aria-brailleroledescription` attribute overrides how assistive technologies localize and express the name of a role in braille, inappropriate values will prevent users from understanding and interacting with an element on braille interfaces. - -Only use `aria-brailleroledescription` if [`aria-roledescription`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-roledescription) is present. However, if the `aria-roledescription` value works in braille, the braille version of the attribute is not needed. In general, `aria-brailleroledescription` should only be used in the rare case when a `aria-roledescription` is too verbose for braille. - -A few rules to remember: - -- Only apply `aria-brailleroledescription` to elements with a valid ARIA role or elements with implicit role semantics. -- The `aria-brailleroledescription`, if present, must have a non-empty, none null value that is different from the `aria-roledescription` value, which, in turn, is different from the ARIA explicit or role or implicit semantic role. -- Avoid using Unicode Braille Patterns. If they must be used, ensure the `aria-brailleroledescription` value contains content other than unicode braille patterns, whitespace, and braille pattern dots-0. -- Ensure the value is always localized to the document's language. - -> [!WARNING] -> If the content is only in unicode braille patterns, the value will not be translated according to the user's preferred translation table. - -> [!NOTE] -> Do NOT use `aria-brailleroledescription` to replicate `aria-roledescription`. Only include this attribute when `aria-roledescription` does not provide an adequate braille representation. - -The `aria-brailleroledescription` value will not be exposed to the braille user if: - -- The value is empty or contains only whitespace characters or the empty braille pattern: dots-0 (U+2800). -- The element to which the attribute is applied has an explicit or implicit WAI-ARIA role where `aria-brailleroledescription` is prohibited, including the `generic` role. -- The element to which the attribute is applied does not have a valid `aria-roledescription`. - -> [!NOTE] -> Test your sites and applications with daily users of assistive technologies, including braille readers, to ensure your content makes sense in braille. - -## Values - -- `<string>` - - : The value is a string, an unconstrained value type, that is intended to be converted into braille - -## Associated roles - -Used in **ALL** roles (except [`generic`](/en-US/docs/Web/Accessibility/ARIA/Roles/generic_role)). - -## Specifications - -{{Specifications}} - -## See also - -- {{domxref("Element.ariaBrailleRoleDescription")}} -- [`aria-roledescription`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-roledescription). -- [`Element.ariaRoleDescription`](/en-US/docs/Web/API/Element/ariaRoleDescription) diff --git a/files/en-us/web/accessibility/aria/attributes/aria-busy/index.md b/files/en-us/web/accessibility/aria/attributes/aria-busy/index.md deleted file mode 100644 index 543a03b82224077..000000000000000 --- a/files/en-us/web/accessibility/aria/attributes/aria-busy/index.md +++ /dev/null @@ -1,77 +0,0 @@ ---- -title: aria-busy -slug: Web/Accessibility/ARIA/Attributes/aria-busy -page-type: aria-attribute -spec-urls: - - https://w3c.github.io/aria/#aria-busy - - https://www.w3.org/TR/wai-aria-1.2/#aria-busy ---- - -{{AccessibilitySidebar}} - -Used in [ARIA live regions](/en-US/docs/Web/Accessibility/ARIA/ARIA_Live_Regions), the global `aria-busy` state indicates an element is being modified and that assistive technologies may want to wait until the changes are complete before informing the user about the update. - -When multiple parts of a live region need to be loaded before changes are announced to the user, set `aria-busy="true"` until loading is complete. Then set to `aria-busy="false"`. This prevents assistive technologies from announcing changes before updates are done. - -## Description - -There is a section of content that updates. The updates are important and you want to let the user know when it has been modified, so you have converted it into an [ARIA live region](/en-US/docs/Web/Accessibility/ARIA/ARIA_Live_Regions) with the [`aria-live`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-live) attribute. You may want to update several components of that section at the same time, but you can't be sure that everything will update simultaneously. Even if it is a very important live region with `aria-live="assertive"`, you don't want to interrupt the user multiple times as different parts of the content load. This is where `aria-busy` can help. - -The `aria-busy` property is an optional property of live regions that can have the value `true` or `false`. The `aria-busy` attribute with a value of `true` can be added to an element currently being updated or modified, to inform the assistive technology that it should wait until the modifications or changes are complete before exposing the content to the user. Use the [`ariaBusy`](/en-US/docs/Web/API/Element/ariaBusy) property of the object to change the value to `false` when downloading is complete. - -```js -ariaLiveElement.ariaBusy = "false"; -``` - -[`aria-live`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-live)'s value dictates whether the changes are announced immediately upon changing the value to `false`, or the assistive technology waits until the current task is complete before interrupting the user. - -### Within a `feed` - -If an element with [`feed`](/en-US/docs/Web/Accessibility/ARIA/Roles/feed_role) role has `aria-busy` set to `true`, the rendering changes that occur inside the feed will not be announced with the exception of user-initiated changes. - -### Within a `widget` - -If changes to a rendered widget would create a state where the widget is missing required owned elements during script execution, set `aria-busy` to `true` on the widget during the update process. For example, if a rendered tree grid updates multiple branches not necessarily rendered simultaneously, an alternative to replacing the whole tree in a single update would be to mark the tree busy while each of the branches is modified. - -## Values - -- false (default): - - : There are no expected updates for the element. -- true - - : The element is being updated. - -## Associated interfaces - -- {{domxref("Element.ariaBusy")}} - - : The [`ariaBusy`](/en-US/docs/Web/API/Element/ariaBusy) property, part of each element's interface, reflects the value of the `aria-busy` attribute, which indicates whether an element is being modified. - -```html -<div - id="clock" - role="timer" - aria-live="polite" - aria-atomic="true" - aria-busy="false"></div> -``` - -```js -const el = document.getElementById("clock"); -console.log(el.ariaBusy); // false -el.ariaBusy = "true"; -console.log(el.ariaBusy); // true -``` - -## Associated roles - -Used in **ALL** roles - -## Specifications - -{{Specifications}} - -## See also - -- [ARIA live regions](/en-US/docs/Web/Accessibility/ARIA/ARIA_Live_Regions) -- [`aria-live`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-live) -- [`aria-relevant`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-relevant) -- [`aria-atomic`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-atomic) diff --git a/files/en-us/web/accessibility/aria/attributes/aria-checked/index.md b/files/en-us/web/accessibility/aria/attributes/aria-checked/index.md deleted file mode 100644 index 0e7f5962d3e2ac2..000000000000000 --- a/files/en-us/web/accessibility/aria/attributes/aria-checked/index.md +++ /dev/null @@ -1,88 +0,0 @@ ---- -title: aria-checked -slug: Web/Accessibility/ARIA/Attributes/aria-checked -page-type: aria-attribute -spec-urls: - - https://w3c.github.io/aria/#aria-checked - - https://www.w3.org/WAI/ARIA/apg/patterns/checkbox/examples/checkbox/ ---- - -{{AccessibilitySidebar}} - -The `aria-checked` attribute indicates the current "checked" state of checkboxes, radio buttons, and other widgets. - -> [!NOTE] -> Where possible use an HTML {{htmlelement("input")}} element with `type="checkbox"` and `type="radio"` as these have built in semantics and do not require ARIA attributes. - -## Description - -The `aria-checked` attribute indicates whether the element is checked (`true`), unchecked (`false)`, or if the checked status is indeterminate (`mixed`), meaning it is neither checked nor unchecked. The `mixed` value is supported by the tri-state input roles of [`checkbox`](/en-US/docs/Web/Accessibility/ARIA/Roles/checkbox_role) and [`menuitemcheckbox`](/en-US/docs/Web/Accessibility/ARIA/Roles/menuitemcheckbox_role). - -The `mixed` value is not supported on [`radio`](/en-US/docs/Web/Accessibility/ARIA/Roles/radio_role), [`menuitemradio`](/en-US/docs/Web/Accessibility/ARIA/Roles/menuitemradio_role), or [`switch`](/en-US/docs/Web/Accessibility/ARIA/Roles/switch_role) and elements that inherits from these. The value will be false if `mixed` is set when not supported. - -```html -<span - role="checkbox" - id="checkBoxInput" - aria-checked="false" - tabindex="0" - aria-labelledby="chk15-label"></span> -<label id="chk15-label">Subscribe to the newsletter</label> -``` - -The `tabindex` attribute is required to enable focus. JavaScript is required to toggle the `aria-checked` state. And, if this checkbox is part of a submittable form, more JavaScript is required to set a name and a value. - -The above could have been written as: - -```html -<input type="checkbox" id="chk15-label" name="Subscribe" /> -<label for="chk15-label">Subscribe to the newsletter</label> -``` - -By using the {{htmlelement("input")}} element with `type="checkbox"` instead of ARIA, there is no need for any JavaScript. - -## Values - -- false - - : The element supports being checked but is not currently checked. -- true - - : The element is checked. -- mixed - - : for [`checkbox`](/en-US/docs/Web/Accessibility/ARIA/Roles/checkbox_role) and [`menuitemcheckbox`](/en-US/docs/Web/Accessibility/ARIA/Roles/menuitemcheckbox_role) only, equivalent to `indeterminate`, indicating a mixed mode value of neither checked nor unchecked. -- undefined (default) - - : The element does not support being checked. - -## Associated roles - -Used in roles: - -- [`checkbox`](/en-US/docs/Web/Accessibility/ARIA/Roles/checkbox_role) -- [`menuitemcheckbox`](/en-US/docs/Web/Accessibility/ARIA/Roles/menuitemcheckbox_role) -- [`menuitemradio`](/en-US/docs/Web/Accessibility/ARIA/Roles/menuitemradio_role) -- [`option`](/en-US/docs/Web/Accessibility/ARIA/Roles/option_role) -- [`radio`](/en-US/docs/Web/Accessibility/ARIA/Roles/radio_role) -- [`switch`](/en-US/docs/Web/Accessibility/ARIA/Roles/switch_role) - -## Associated interfaces - -- {{domxref("Element.ariaChecked")}} - - : The [`ariaChecked`](/en-US/docs/Web/API/Element/ariaChecked) property, part of the {{domxref("Element")}} interface, reflects the value of the `aria-checked` attribute. -- {{domxref("ElementInternals.ariaChecked")}} - - : The [`ariaChecked`](/en-US/docs/Web/API/ElementInternals/ariaChecked) property, part of the {{domxref("ElementInternals")}} interface, reflects the value of the `aria-checked` attribute. - -```js -myHTMLElement.ariaChecked = true; -``` - -## Specifications - -{{Specifications}} - -## See also - -- [`<input type="checkbox">`](/en-US/docs/Web/HTML/Element/input/checkbox) -- [`<input type="radio">`](/en-US/docs/Web/HTML/Element/input/radio) -- [`aria-pressed`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-pressed) -- [`aria-selected`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-selected) -- [Two state checkbox example](https://www.w3.org/WAI/ARIA/apg/example-index/checkbox/checkbox.html) - w3.org -- [Mix-state checkbox example](https://www.w3.org/WAI/ARIA/apg/example-index/checkbox/checkbox-mixed.html) - w3.org diff --git a/files/en-us/web/accessibility/aria/attributes/aria-colcount/index.md b/files/en-us/web/accessibility/aria/attributes/aria-colcount/index.md deleted file mode 100644 index 1ff83a9f7498502..000000000000000 --- a/files/en-us/web/accessibility/aria/attributes/aria-colcount/index.md +++ /dev/null @@ -1,90 +0,0 @@ ---- -title: aria-colcount -slug: Web/Accessibility/ARIA/Attributes/aria-colcount -page-type: aria-attribute -spec-urls: https://w3c.github.io/aria/#aria-colcount ---- - -{{AccessibilitySidebar}} - -The `aria-colcount` attribute defines the total number of columns in a [`table`](/en-US/docs/Web/Accessibility/ARIA/Roles/table_role), [`grid`](/en-US/docs/Web/Accessibility/ARIA/Roles/grid_role), or [`treegrid`](/en-US/docs/Web/Accessibility/ARIA/Roles/treegrid_role) when not all columns are present in the [DOM](/en-US/docs/Glossary/DOM). - -## Description - -Some tables are very large, and it's not possible to show all the columns to the user. Or, it is possible, but having such a wide table would be a bad user experience. Use the `aria-colcount` attribute to let assistive technologies know how many columns the table would have if all columns were present. The value is an integer representing the number of columns that make up the full table. If you don't know the total number of columns a table will have, but know they will not all be in the DOM, use the value -1, so `aria-colcount="-1"`. This value tells the user agent that the current number of columns present in the DOM may not be the actual number of columns in the table. - -If all columns in a table are present in the DOM, the `aria-colcount` attribute isn't needed, as browsers automatically calculate the total number of columns. However, if only a portion of the columns is present in the DOM at a given moment, that is when this attribute is helpful and needed. - -When using `aria-colcount` when you have a known number of columns, make sure to also use [`aria-colindex`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-colindex) to label each column, or, if the columns are contiguous-if it's a group of columns in the original order with no breaks-label each row. - -The following example shows a grid with 6 columns, of which columns 1, 2, 5, and 6 are displayed to the user. The total number of columns that make up the table is set as `aria-colcount="6"` on the table itself. As the columns aren't contiguous, every [`cell`](/en-US/docs/Web/Accessibility/ARIA/Roles/cell_role) - in this case [`columnheader`](/en-US/docs/Web/Accessibility/ARIA/Roles/columnheader_role) and [`gridcell`](/en-US/docs/Web/Accessibility/ARIA/Roles/gridcell_role) elements - have the `aria-colindex` attribute set. - -```html -<div role="grid" aria-colcount="6"> - <div role="rowgroup"> - <div role="row"> - <div role="columnheader" aria-colindex="1">First name</div> - <div role="columnheader" aria-colindex="2">Last name</div> - <div role="columnheader" aria-colindex="5">City</div> - <div role="columnheader" aria-colindex="6">Zip</div> - </div> - </div> - <div role="rowgroup"> - <div role="row"> - <div role="gridcell" aria-colindex="1">Debra</div> - <div role="gridcell" aria-colindex="2">Burks</div> - <div role="gridcell" aria-colindex="5">New York</div> - <div role="gridcell" aria-colindex="6">14127</div> - </div> - </div> - … -</div> -``` - -The first rule of ARIA use is "if you can use a native feature with the semantics and behavior you require already built in, instead of repurposing an element and **adding** an ARIA role, state or property to make it accessible, then do so." If we employ native HTML semantics with {{HTMLElement('table')}}, {{HTMLElement('th')}}, {{HTMLElement('td')}}, etc., the `aria-colcount` attribute is still necessary, but the mark up is not as verbose. When using semantic table header elements and not all columns are in the DOM, the `aria-colcount` must still be used, but the `aria-colindex` attribute only needs to be defined once per column in the column header {{HTMLElement('th')}}. - -```html -<table aria-colcount="6"> - <thead> - <tr> - <th aria-colindex="1" scope="col">First name</th> - <th aria-colindex="2" scope="col">Last name</th> - <th aria-colindex="5" scope="col">City</th> - <th aria-colindex="6" scope="col">Zip</th> - </tr> - </thead> - <tbody> - <tr> - <td>Debra</td> - <td>Burks</td> - <td>New York</td> - <td>14127</td> - </tr> - … - </tbody> -</table> -``` - -## Values - -- `<integer>` - - : The number of columns in the full table - -## Associated roles - -Used in roles: - -- [`table`](/en-US/docs/Web/Accessibility/ARIA/Roles/table_role) - -Inherits into roles: - -- [`grid`](/en-US/docs/Web/Accessibility/ARIA/Roles/grid_role) -- [`treegrid`](/en-US/docs/Web/Accessibility/ARIA/Roles/treegrid_role) - -## Specifications - -{{Specifications}} - -## See also - -- [`aria-colindex`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-colindex) diff --git a/files/en-us/web/accessibility/aria/attributes/aria-colindex/index.md b/files/en-us/web/accessibility/aria/attributes/aria-colindex/index.md deleted file mode 100644 index db1ac62768653d5..000000000000000 --- a/files/en-us/web/accessibility/aria/attributes/aria-colindex/index.md +++ /dev/null @@ -1,116 +0,0 @@ ---- -title: aria-colindex -slug: Web/Accessibility/ARIA/Attributes/aria-colindex -page-type: aria-attribute -spec-urls: https://w3c.github.io/aria/#aria-colindex ---- - -{{AccessibilitySidebar}} - -The `aria-colindex` attribute defines an element's column index or position with respect to the total number of columns within a `table`, `grid`, or `treegrid`. - -## Description - -Some tables are very large, and as a result have only a portion of its content is initially displayed. While loading only a subsection of the columns may improve user experience, you need to let all users know what portions of the content are being displayed, and that all the table's content is not present. - -ARIA provides several attributes to provide information about `table`, `grid`, and `treegrid` structures. The `aria-colindex` attribute defines the substructure, an element's column index or position with respect to the total number of columns, within such structures. - -Used in conjunction with the [`aria-colcount`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-colcount) attribute, which informs assistive technologies how many columns the table would have if all columns were present, the `aria-colindex` is used an element's column index or position with respect to that total number of columns. - -If all of the columns are present in the DOM, including `aria-colindex` is not necessary as user agents can calculate the column index of each cell or gridcell. However, if any of the columns are left out of the DOM at any time, use `aria-colindex` to indicate the column of each cell or gridcell with respect to the full table. - -The value for `aria-colindex` is an integer greater than or equal to 1. Each value should be greater than the previous column's `aria-colindex` and less than or equal to the number of columns in the full table. - -If a cell or gridcell spans multiple columns, set [`aria-colspan`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-colspan) to the number of columns it spans if not using {{htmlelement('td')}} and {{htmlelement('th')}} HTML elements, and set `aria-colindex` to the value of the start of the span; the value it would have had if it was only one column wide spanning only the first of its columns. - -If the set of columns which is present in the DOM is contiguous, and if there are no cells which span more than one row or column in that set, you only have to put the `aria-colindex` once on each row on the first column of the set. If the columns are not contiguous, include the `aria-colindex` value on all of the children or owned elements of each row. - -The following example shows a grid with 6 columns, of which columns 1, 2, 5, and 6 are displayed to the user. The total number of columns that make up the table is set as `aria-colcount="6"` on the table itself. As the columns aren't contiguous, every [`cell`](/en-US/docs/Web/Accessibility/ARIA/Roles/cell_role) - in this case [`columnheader`](/en-US/docs/Web/Accessibility/ARIA/Roles/columnheader_role) and [`gridcell`](/en-US/docs/Web/Accessibility/ARIA/Roles/gridcell_role) elements - have the `aria-colindex` attribute set. - -```html -<div role="grid" aria-colcount="6"> - <div role="rowgroup"> - <div role="row"> - <div role="columnheader" aria-colindex="1">First name</div> - <div role="columnheader" aria-colindex="2">Last name</div> - <div role="columnheader" aria-colindex="5">City</div> - <div role="columnheader" aria-colindex="6">Zip</div> - </div> - </div> - <div role="rowgroup"> - <div role="row"> - <div role="gridcell" aria-colindex="1">Debra</div> - <div role="gridcell" aria-colindex="2">Burks</div> - <div role="gridcell" aria-colindex="5">New York</div> - <div role="gridcell" aria-colindex="6">14127</div> - </div> - </div> - … -</div> -``` - -The first rule of ARIA use is "if you can use a native feature with the semantics and behavior you require already built in, instead of repurposing an element and **adding** an ARIA role, state or property to make it accessible, then do so." If we employ native HTML semantics with {{HTMLElement('table')}}, {{HTMLElement('th')}}, {{HTMLElement('td')}}, etc., and only display a subsection of columns, the `aria-colcount` and `aria-colindex` attribute are still necessary, but the mark up is not as verbose. - -When using semantic table header elements and not all columns are in the DOM, the `aria-colindex` attribute only needs to be defined once per column in the column header {{HTMLElement('th')}}. - -```html -<table aria-colcount="6"> - <thead> - <tr> - <th aria-colindex="1" scope="col">First name</th> - <th aria-colindex="2" scope="col">Last name</th> - <th aria-colindex="5" scope="col">City</th> - <th aria-colindex="6" scope="col">Zip</th> - </tr> - </thead> - <tbody> - <tr> - <td>Debra</td> - <td>Burks</td> - <td>New York</td> - <td>14127</td> - </tr> - … - </tbody> -</table> -``` - -If all the columns are in the DOM, neither `aria-colcount` nor `aria-colindex` are necessary. - -## Values - -- `<integer>` - - : Integer greater than or equal to 1 and less than or equal to the total number of columns if all were present. - -## Associated interfaces - -- {{domxref("Element.ariaColIndex")}} - - : The [`ariaColIndex`](/en-US/docs/Web/API/Element/ariaColIndex) property, part of the {{domxref("Element")}} interface, reflects the value of the `aria-colindex` attribute. -- {{domxref("ElementInternals.ariaColIndex")}} - - : The [`ariaColIndex`](/en-US/docs/Web/API/ElementInternals/ariaColIndex) property, part of the {{domxref("ElementInternals")}} interface, reflects the value of the `aria-colindex` attribute. - -## Associated roles - -Used in roles: - -- [`cell`](/en-US/docs/Web/Accessibility/ARIA/Roles/cell_role) -- [`row`](/en-US/docs/Web/Accessibility/ARIA/Roles/row_role) - -Inherits into roles: - -- [`columnheader`](/en-US/docs/Web/Accessibility/ARIA/Roles/columnheader_role) -- [`gridcell`](/en-US/docs/Web/Accessibility/ARIA/Roles/gridcell_role) -- [`rowheader`](/en-US/docs/Web/Accessibility/ARIA/Roles/rowheader_role) - -## Specifications - -{{Specifications}} - -## See also - -- [`aria-colindextext`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-colindextext) attribute -- [`aria-colcount`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-colcount) attribute -- [`aria-colspan`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-colspan) attribute -- HTML {{HTMLElement('table')}} element -- HTML {{HTMLElement('th')}} element -- HTML {{HTMLElement('td')}} element diff --git a/files/en-us/web/accessibility/aria/attributes/aria-colindextext/index.md b/files/en-us/web/accessibility/aria/attributes/aria-colindextext/index.md deleted file mode 100644 index 7eba444729ffe64..000000000000000 --- a/files/en-us/web/accessibility/aria/attributes/aria-colindextext/index.md +++ /dev/null @@ -1,104 +0,0 @@ ---- -title: aria-colindextext -slug: Web/Accessibility/ARIA/Attributes/aria-colindextext -page-type: aria-attribute -spec-urls: https://w3c.github.io/aria/#aria-colindextext ---- - -{{AccessibilitySidebar}} - -The `aria-colindextext` attribute defines a human-readable text alternative of the numeric [`aria-colindex`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-colindex). - -## Description - -When you have a very large table or when you purposefully want to display just a section of a table, not all columns may be present in the DOM. When this happens, we use the [`aria-colcount`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-colcount) with an integer value to define how many columns the table (or grid) would have if all the columns were present and add the [`aria-colindex`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-colindex) property on each column to provide information on the column index within that larger table. - -In the following HTML snippet, our table has 8 columns, but we are only displaying 4. The "city" column is the fifth column of our larger table, as defined by `aria-colindex="5"`. - -```html -<table aria-colcount="8"> - <thead> - <tr> - <th aria-colindex="1" scope="col">First name</th> - <th aria-colindex="2" scope="col">Last name</th> - <th aria-colindex="5" scope="col">City</th> - <th aria-colindex="7" scope="col">Zip</th> - </tr> - </thead> - … -</table> -``` - -This table is not very complex. Had this been a 100+ column spreadsheet or a grid without column headers, such as a chess board, the provided or calculated value of `aria-colindex` might not be meaningful or may not reflect the displayed index. When this is the case, `aria-colindextext` can be included. The value is a string that is a human-readable text alternative to the numeric `aria-colindex`. - -```html -<table aria-colcount="128"> - <thead> - <tr> - <th aria-colindex="1" aria-colindextext="NYSE stock symbol" scope="col"> - NYSE - </th> - <th - aria-colindex="110" - aria-colindextext="Value at start of 2021" - scope="col"> - 01/21 - </th> - <th - aria-colindex="122" - aria-colindextext="Value at start of 2022" - scope="col"> - 01/22 - </th> - <th aria-colindex="124" scope="col">Recommendation</th> - </tr> - </thead> - … -</table> -``` - -In the above example, the table has 128 columns of which only 4 columns are shown. The `aria-colindextext` is used in three columns to provide human-readable text alternatives. By including `aria-colindextext="Value at start of 2021"`, assistive technologies can announce "Value at start of 2021" instead of "Column 110". - -Only use `aria-colindextext` when the provided or calculated value of `aria-colindex` is not meaningful or does not reflect the displayed index. Whenever you include `aria-colindextext`, also keep the `aria-colindex` as some assistive technologies rely on the numeric column index for the purpose of keeping track of the user's position and in providing alternative table navigation. - -> [!NOTE] -> While `aria-colindex` can be added to a row when all the columns present are contiguous as sequential values can be deduced, `aria-colindextext` is NOT a supported property of [`row`](/en-US/docs/Web/Accessibility/ARIA/Roles/row_role). - -See related [`aria-rowindextext`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-rowindextext). - -## Values - -- `<string>` - - : The human-readable text alternative of the numeric [`aria-colindex`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-colindex) - -## Associated interfaces - -- {{domxref("Element.ariaColIndexText")}} - - : The [`ariaColIndexText`](/en-US/docs/Web/API/Element/ariaColIndexText) property, part of the {{domxref("Element")}} interface, reflects the value of the `aria-colindextext` attribute. -- {{domxref("ElementInternals.ariaColIndexText")}} - - : The [`ariaColIndexText`](/en-US/docs/Web/API/ElementInternals/ariaColIndexText) property, part of the {{domxref("ElementInternals")}} interface, reflects the value of the `aria-colindextext` attribute. - -## Associated roles - -Used in roles: - -- [`cell`](/en-US/docs/Web/Accessibility/ARIA/Roles/cell_role) - -Inherits into roles: - -- [`columnheader`](/en-US/docs/Web/Accessibility/ARIA/Roles/columnheader_role) -- [`rowheader`](/en-US/docs/Web/Accessibility/ARIA/Roles/columnheader_role) - -## Specifications - -{{Specifications}} - -## See also - -- [`Element.ariaColIndexText`](/en-US/docs/Web/API/Element/ariaColIndexText) -- [`aria-colindex`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-colindex) -- [`aria-rowindextext`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-rowindextext) -- [`aria-colcount`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-colcount) -- [`cell` role](/en-US/docs/Web/Accessibility/ARIA/Roles/cell_role) -- [`columnheader` role](/en-US/docs/Web/Accessibility/ARIA/Roles/columnheader_role) -- [`rowheader` role](/en-US/docs/Web/Accessibility/ARIA/Roles/columnheader_role) diff --git a/files/en-us/web/accessibility/aria/attributes/aria-colspan/index.md b/files/en-us/web/accessibility/aria/attributes/aria-colspan/index.md deleted file mode 100644 index 00628d34ee5ce69..000000000000000 --- a/files/en-us/web/accessibility/aria/attributes/aria-colspan/index.md +++ /dev/null @@ -1,172 +0,0 @@ ---- -title: aria-colspan -slug: Web/Accessibility/ARIA/Attributes/aria-colspan -page-type: aria-attribute -spec-urls: https://w3c.github.io/aria/#aria-colspan ---- - -{{AccessibilitySidebar}} - -The `aria-colspan` attribute defines the number of columns spanned by a cell or gridcell within a [`table`](/en-US/docs/Web/Accessibility/ARIA/Roles/table_role), [`grid`](/en-US/docs/Web/Accessibility/ARIA/Roles/grid_role), or [`treegrid`](/en-US/docs/Web/Accessibility/ARIA/Roles/treegrid_role). - -## Description - -Intended for [`cell`s](/en-US/docs/Web/Accessibility/ARIA/Roles/cell_role) and [`gridcell`s](/en-US/docs/Web/Accessibility/ARIA/Roles/gridcell_role) which are not contained in a native HTML {{HTMLElement('table')}}, the `aria-colspan` property value defines the number of columns spanned by an individual cell an ARIA [`table`](/en-US/docs/Web/Accessibility/ARIA/Roles/table_role), [`grid`](/en-US/docs/Web/Accessibility/ARIA/Roles/grid_role), or [`treegrid`](/en-US/docs/Web/Accessibility/ARIA/Roles/treegrid_role). - -In HTML, {{HTMLElement('th')}} and {{HTMLElement('td')}} elements have the [`colspan`](/en-US/docs/Web/HTML/Element/td#attributes) attribute. When using the semantic {{HTMLElement('table')}}, use the native `colspan` attribute as designed. This ARIA attribute is intended for cells and gridcells which are not contained in a native table, and will be ignored if used on a cell in a {{HTMLElement('table')}}. - -> [!NOTE] -> The first rule of ARIA use is if you can use a native feature with the semantics and behavior you require already built in, instead of repurposing an element and **adding** an ARIA role, state or property to make it accessible, then do so. Employ HTML {{HTMLelement('table')}} elements, including {{HTMLelement('td')}} and {{HTMLelement('th')}} with the `colspan` attribute instead of non-semantic elements with ARIA roles and attributes whenever possible. - -The value of `aria-colspan` should be a positive integer. The default or assumed value of a cell span is 1. Make sure that the included value does cause the cell or gridcell to overlap the next cell or gridcell in the same row and does not cause the cell to span outside of the containing table, grid, or treegrid. - -## Example - -The following is an example of part of a bowling tournament league scoring spreadsheet. Each game spans 10 frames, and each frame spans a 3 scores: two balls and the current total. The 10th (and last) frame in each game spans 4 columns in case someone is scoring all strikes. - -```html -<div role="grid" aria-rowcount="27"> - aria-label="Bowling League Scores" - <div role="rowgroup"> - <div role="row" aria-rowindex="1"> - <!-- - aria-rowspan and aria-colspan provide - assistive technologies with the correct data cell header information - when header cells span more than one row or column. - --> - - <span role="columnheader" aria-rowspan="2">Team</span> - <span role="columnheader" aria-colspan="2">Player</span> - <span role="columnheader" aria-colspan="31">Game 1 Frames</span> - <span role="columnheader" aria-colspan="31">Game 2 Frames</span> - <span role="columnheader" aria-colspan="31">Game 3 Frames</span> - <span role="columnheader" aria-rowspan="2">Total</span> - </div> - <div role="row" aria-rowindex="2"> - <span role="columnheader">Last Name</span> - <span role="columnheader">First Name</span> - <span role="columnheader" aria-colspan="3">1</span> - <span role="columnheader" aria-colspan="3">2</span> - <span role="columnheader" aria-colspan="3">3</span> - <span role="columnheader" aria-colspan="3">4</span> - <span role="columnheader" aria-colspan="3">5</span> - <span role="columnheader" aria-colspan="3">6</span> - <span role="columnheader" aria-colspan="3">7</span> - <span role="columnheader" aria-colspan="3">8</span> - <span role="columnheader" aria-colspan="3">9</span> - <span role="columnheader" aria-colspan="4">10</span> - <span role="columnheader" aria-colspan="3">1</span> - <span role="columnheader" aria-colspan="3">2</span> - <span role="columnheader" aria-colspan="3">3</span> - <span role="columnheader" aria-colspan="3">4</span> - <span role="columnheader" aria-colspan="3">5</span> - <span role="columnheader" aria-colspan="3">6</span> - <span role="columnheader" aria-colspan="3">7</span> - <span role="columnheader" aria-colspan="3">8</span> - <span role="columnheader" aria-colspan="3">9</span> - <span role="columnheader" aria-colspan="4">10</span> - <span role="columnheader" aria-colspan="3">1</span> - <span role="columnheader" aria-colspan="3">2</span> - <span role="columnheader" aria-colspan="3">3</span> - <span role="columnheader" aria-colspan="3">4</span> - <span role="columnheader" aria-colspan="3">5</span> - <span role="columnheader" aria-colspan="3">6</span> - <span role="columnheader" aria-colspan="3">7</span> - <span role="columnheader" aria-colspan="3">8</span> - <span role="columnheader" aria-colspan="3">9</span> - <span role="columnheader" aria-colspan="4">10</span> - </div> - </div> - <div role="rowgroup"> - <div role="row" aria-rowindex="10"> - <span role="rowheader" aria-rowspan="3">The Mighty Quokkas</span> - <span role="cell">Henderson</span> - <span role="cell">Alice</span> - <span role="cell">7</span> - <span role="cell">/</span> - <span role="cell">20</span> - <span role="cell" aria-colspan="2">X</span> - <span role="cell">39</span> - <span role="cell">9</span> - <span role="cell">-</span> - <span role="cell">48</span> - <span role="cell" aria-colspan="2">X</span> - <span role="cell">76</span> - <span role="cell" aria-colspan="2">X</span> - <span role="cell">96</span> - <span role="cell">8</span> - <span role="cell">/</span> - <span role="cell">113</span> - <span role="cell">7</span> - <span role="cell">-</span> - <span role="cell">120</span> - <span role="cell" aria-colspan="2">X</span> - <span role="cell">146</span> - <span role="cell" aria-colspan="2">X</span> - <span role="cell">166</span> - <span role="cell">6</span> - <span role="cell">/</span> - <span role="cell">X</span> - <span role="cell">186</span> - <span role="cell">7</span> - <span role="cell">2</span> - <span role="cell">9</span> - <span role="cell">6</span> - <span role="cell">-</span> - <span role="cell">15</span> - <span role="cell" aria-colspan="2">X</span> - <span role="cell">35</span> - <span role="cell">7</span> - <span role="cell">/</span> - … - </div> - <div role="row" aria-rowindex="11"> - <span role="cell">McPherson</span> - <span role="cell">Leslie</span> - <span role="cell">9</span> - <span role="cell">-</span> - <span role="cell">9</span> - <span role="cell">8</span> - <span role="cell">1</span> - <span role="cell">18</span> - … - </div> - </div> -</div> -``` - -If we had used a {{HTMLElement('table')}} and semantic table elements our markup would have been less verbose and accessible by default. - -## Values - -- `<integer>` - - : An integer greater than or equal to the default value of 1 defining the number of columns spanned by the cell. The value must be less than what would cause a cell to overlap the next cell in the same row. - -## Associated interfaces - -- {{domxref("Element.ariaColSpan")}} - - : The [`ariaColSpan`](/en-US/docs/Web/API/Element/ariaColSpan) property, part of each element's interface, reflects the value of the `aria-colspan` attribute, which defines the number of columns spanned by a cell or gridcell within a table, grid, or treegrid. - -## Associated roles - -Used in roles: - -- [`cell`](/en-US/docs/Web/Accessibility/ARIA/Roles/cell_role) - -Inherits into roles: - -- [`columnheader`](/en-US/docs/Web/Accessibility/ARIA/Roles/columnheader_role) -- [`rowheader`](/en-US/docs/Web/Accessibility/ARIA/Roles/columnheader_role) - -## Specifications - -{{Specifications}} - -## See also - -- The {{HTMLElement('th')}} and {{HTMLElement('td')}} [`colspan`](/en-US/docs/Web/HTML/Element/td#attributes) attribute -- [`aria-colindex`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-colindex) property -- [`aria-rowspan`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-rowspan) property -- [`cell`](/en-US/docs/Web/Accessibility/ARIA/Roles/cell_role) role -- [`columnheader`](/en-US/docs/Web/Accessibility/ARIA/Roles/columnheader_role) role -- [`rowheader`](/en-US/docs/Web/Accessibility/ARIA/Roles/columnheader_role) role diff --git a/files/en-us/web/accessibility/aria/attributes/aria-controls/index.md b/files/en-us/web/accessibility/aria/attributes/aria-controls/index.md deleted file mode 100644 index d37c4d0b0cf86d6..000000000000000 --- a/files/en-us/web/accessibility/aria/attributes/aria-controls/index.md +++ /dev/null @@ -1,101 +0,0 @@ ---- -title: aria-controls -slug: Web/Accessibility/ARIA/Attributes/aria-controls -page-type: aria-attribute -spec-urls: https://w3c.github.io/aria/#aria-controls ---- - -{{AccessibilitySidebar}} - -The global `aria-controls` property identifies the element (or elements) whose contents or presence are controlled by the element on which this attribute is set. - -## Description - -When an interactive widget or element, be it a combobox, tab, button, etc., is used to adjust or modify another element or component in a document or application, the `aria-controls` attribute can be used to programmatically associate the corresponding element or elements with the controlling element. The `aria-controls` attribute identifies the element (or elements) whose contents or presence are controlled by the element on which the attribute is set, regardless of what type of interaction initiates the impacted behavior. - -A [combobox](/en-US/docs/Web/Accessibility/ARIA/Roles/combobox_role) element has `aria-controls` set to a value that refers to the element that serves as the popup. The `aria-controls` only needs to be set when the popup is visible, but it is valid and easier to program to reference an element that is not visible. - -Other examples of controls include: - -- The button parts of an accordion widget that toggle the visibility of their associated panel content. Each button may have an `aria-controls` specified, referencing the ID of the element containing the content associated with the invoking control. -- An element with a role of [`scrollbar`](/en-US/docs/Web/Accessibility/ARIA/Roles/scrollbar_role): the scrollbar requires an `aria-controls` attribute referencing the ID of the element it controls. -- A group of tabs that each display a different tab panel: each element with [`role="tab"`](/en-US/docs/Web/Accessibility/ARIA/Roles/tab_role) has an `aria-controls` attribute referencing its associated [`tabpanel`](/en-US/docs/Web/Accessibility/ARIA/Roles/tabpanel_role). - -## Example - -In this tabs example, each tab controls one tabpanel: - -```html -<div class="tab-interface"> - <div role="tablist" aria-label="Sample Tabs"> - <span - role="tab" - aria-selected="true" - aria-controls="panel-1" - id="tab-1" - tabindex="0"> - First Tab - </span> - <span - role="tab" - aria-selected="false" - aria-controls="panel-2" - id="tab-2" - tabindex="-1"> - Second Tab - </span> - <span - role="tab" - aria-selected="false" - aria-controls="panel-3" - id="tab-3" - tabindex="-1"> - Third Tab - </span> - </div> - <div id="panel-1" role="tabpanel" tabindex="0" aria-labelledby="tab-1"> - <p>Content for the first panel</p> - </div> - <div - id="panel-2" - role="tabpanel" - tabindex="0" - aria-labelledby="tab-2" - class="display-none"> - <p>Content for the second panel</p> - </div> - <div - id="panel-3" - role="tabpanel" - tabindex="0" - aria-labelledby="tab-3" - class="display-none"> - <p>Content for the third panel</p> - </div> -</div> -``` - -> [!NOTE] -> ARIA only modifies the accessibility tree for an element, identifying how assistive technology can present the content to users. ARIA doesn't change any implicit functionality or styling. - -## Values - -- `id` list - - : A space-separated list of one or more ID values referencing the elements being controlled by the current element - -## Associated interfaces - -- {{domxref("Element.ariaControlsElements")}} - - : The `ariaControlsElements` property is part of each element's interface. Its value is a list of {{domxref("Element")}}s corresponding to the ID values specified in the `aria-controls` attribute. - -## Associated roles - -Used in **ALL** roles. - -## Specifications - -{{Specifications}} - -## See also - -- [`aria-owns`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-owns) diff --git a/files/en-us/web/accessibility/aria/attributes/aria-current/index.md b/files/en-us/web/accessibility/aria/attributes/aria-current/index.md deleted file mode 100644 index d4ec26302429247..000000000000000 --- a/files/en-us/web/accessibility/aria/attributes/aria-current/index.md +++ /dev/null @@ -1,91 +0,0 @@ ---- -title: aria-current -slug: Web/Accessibility/ARIA/Attributes/aria-current -page-type: aria-attribute -spec-urls: https://w3c.github.io/aria/#aria-current ---- - -{{AccessibilitySidebar}} - -A non-null `aria-current` state on an element indicates that this element represents the current item within a container or set of related elements. - -## Description - -When you have a group of related elements, such as several links in a breadcrumb or steps in a multi-step flow, with one element in the group styled differently from the others to indicate to the sighted user that this is the current element within its group, the `aria-current` should be used to inform the assistive technology user what has been indicated via styling. - -In a breadcrumb list, when a link within a set of pagination links is styled to indicate the user is currently on that page, `aria-current="page"` should be set on that link. In a multi step based process with a step indicator such as a multi-page survey or a multi step checkout or registration process, when the current step icon is visually different to represent that it is the current step, that icon's container should have `aria-current="step"` for assistive technology users who may not be able to "see" the visual difference. - -The `aria-current` attribute indicates the element on which it is set, to a value other than `false`, represents the current item within a container or set of related elements. Only mark one element in a set of elements as current with `aria-current`. - -The `aria-current` attribute accepts a limited list of [values](#values) including `page`, `step`, `location`, `date`, `time`, `true`, and `false`. Any non-null string value not included in this list of enumerated values is treated as if `aria-current="true"` were set, not the default `false` value. If the attribute is not present, is an empty string, is present with no value, or is set to `aria-current="false"` it is not exposed to the user. - -When something is selected rather than current, such as a [`tab`](/en-US/docs/Web/Accessibility/ARIA/Roles/tab_role) in a [`tablist`](/en-US/docs/Web/Accessibility/ARIA/Roles/tablist_role), use [`aria-selected`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-selected) to indicate the currently-displayed tabpanel. - -> [!NOTE] -> Don't use `aria-current` as a substitute for [`aria-selected`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-selected) in [`gridcell`](/en-US/docs/Web/Accessibility/ARIA/Roles/gridcell_role), [`option`](/en-US/docs/Web/Accessibility/ARIA/Roles/option_role), [`row`](/en-US/docs/Web/Accessibility/ARIA/Roles/row_role) or [`tab`](/en-US/docs/Web/Accessibility/ARIA/Roles/tab_role). - -## Example - -The breadcrumb for the "current page" should have `aria-current="page"` set on it. - -```html -<nav aria-label="Breadcrumb" class="breadcrumb"> - <ol> - <li> - <a href="../../../../../">Web technology for developers</a> - </li> - <li> - <a href="../../../../">Accessibility</a> - </li> - <li> - <a href="../../../">ARIA</a> - </li> - <li> - <a href="../../">ARIA States and Properties</a> - </li> - <li> - <a href="./" aria-current="page">ARIA: `aria-current` attribute</a> - </li> - </ol> -</nav> -``` - -If the element representing the current page in the breadcrumb was not a link, the `aria-current` is optional. - -## Values - -- `page` - - : Represents the current page within a set of pages such as the link to the current document in a breadcrumb. -- `step` - - : Represents the current step within a process such as the current step in an enumerated multi step checkout flow. -- `location` - - : Represents the current location within an environment or context such as the image that is visually highlighted as the current component of a flow chart. -- `date` - - : Represents the current date within a collection of dates such as the current date within a calendar. -- `time` - - : Represents the current time within a set of times such as the current time within a timetable. -- `true` - - : Represents the current item within a set. -- `false` (default) - - : Does not represent the current item within a set. - -## Associated interfaces - -- {{domxref("Element.ariaCurrent")}} - - : The [`ariaCurrent`](/en-US/docs/Web/API/Element/ariaCurrent) property, part of the {{domxref("Element")}} interface, reflects the value of the `aria-current` attribute. -- {{domxref("ElementInternals.ariaCurrent")}} - - : The [`ariaCurrent`](/en-US/docs/Web/API/ElementInternals/ariaCurrent) property of the {{domxref("ElementInternals")}} interface reflects the value of the `aria-current` attribute. - -## Associated roles - -Usable in all roles; except for elements with the role of [`gridcell`](/en-US/docs/Web/Accessibility/ARIA/Roles/gridcell_role), [`option`](/en-US/docs/Web/Accessibility/ARIA/Roles/option_role), [`row`](/en-US/docs/Web/Accessibility/ARIA/Roles/row_role) and [`tab`](/en-US/docs/Web/Accessibility/ARIA/Roles/tab_role) where [`aria-selected`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-selected) should be used - -## Specifications - -{{Specifications}} - -## See also - -- [`aria-selected`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-selected) -- {{cssxref(':local-link')}} -- [Breadcrumb navigation with `aria-current`](/en-US/docs/Web/CSS/Layout_cookbook/Breadcrumb_Navigation) diff --git a/files/en-us/web/accessibility/aria/attributes/aria-describedby/index.md b/files/en-us/web/accessibility/aria/attributes/aria-describedby/index.md deleted file mode 100644 index bf712087dd65c1c..000000000000000 --- a/files/en-us/web/accessibility/aria/attributes/aria-describedby/index.md +++ /dev/null @@ -1,61 +0,0 @@ ---- -title: aria-describedby -slug: Web/Accessibility/ARIA/Attributes/aria-describedby -page-type: aria-attribute -spec-urls: - - https://w3c.github.io/aria/#aria-describedby - - https://www.w3.org/TR/wai-aria-1.2/#aria-describedby ---- - -{{AccessibilitySidebar}} - -The global `aria-describedby` attribute identifies the element (or elements) that describes the element on which the attribute is set. - -## Description - -The `aria-describedby` attribute lists the [`id`](/en-US/docs/Web/HTML/Global_attributes/id)s of the elements that describe the object. It is used to establish a relationship between widgets or groups and the text that describes them. - -The `aria-describedby` attribute is not limited to form controls. It can also be used to associate static text with widgets, groups of elements, regions that have a heading, definitions, and more. The `aria-describedby` attribute can be used with semantic HTML elements and with elements that have an ARIA [`role`](/en-US/docs/Web/Accessibility/ARIA/Roles). - -The `aria-describedby` attribute is very similar to the [`aria-labelledby`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-labelledby) attribute. While `aria-labelledby` lists the `id`s of the labels or elements that describe the essence of an object, `aria-describedby` lists the `id`s of the descriptions or elements providing more information that the user might need. Both `aria-labelledby` and `aria-describedby` reference other elements to calculate a text alternative, but a label should be concise, while a description is intended to provide more verbose information; a label describes the essence of an object, while a description provides more information that the user might need. - -The elements linked via `aria-describedby` don't need to be visible. It is possible to reference an element even if that element is hidden. For example, a form control can have a description that is hidden by default and revealed on request using a disclosure widget like a "more information" icon. The sighted users click on the icon to view the description, while assistive technology users can immediately access it as the description is referenced from that form control with `aria-describedby`. - -The `aria-describedby` property is appropriate when the associated content contains plain text. If the content is extensive, contains useful semantics, or has a complex structure requiring user navigation, use [`aria-details`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-details) instead. `aria-details` allows assistive technology users to visit the associated structured content and provides additional navigation commands, making it easier to understand the structure, or to experience the information in smaller pieces. - -> [!NOTE] -> The `aria-describedby` content should only be a text string. If there are important underlying semantics in the content, consider using [`aria-details`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-details). - -## Example - -```html -<button aria-describedby="trash-desc">Move to trash</button> -… -<p id="trash-desc"> - Items in the trash will be permanently removed after 30 days. -</p> -``` - -> [!NOTE] -> The `aria-describedby` attribute is not designed to reference descriptions from external resources. As its value is one or more `id`s (space-separated if multiple), it must reference elements in the same DOM document. - -## Values - -- ID reference list - - : The `id` or space-separated list of element `id`s that describe the current element. - -## Associated roles - -Used in **all** roles. Usable in all HTML elements as well. - -## Specifications - -{{Specifications}} - -## See also - -- {{HTMLElement('label')}} -- [`aria-labelledby`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-labelledby) -- [`aria-description`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-description) -- [`aria-details`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-details) -- [Browser and AT support for `aria-describedby`](https://a11ysupport.io/tech/aria/aria-describedby_attribute) diff --git a/files/en-us/web/accessibility/aria/attributes/aria-description/index.md b/files/en-us/web/accessibility/aria/attributes/aria-description/index.md deleted file mode 100644 index d6dfb1b56f5314d..000000000000000 --- a/files/en-us/web/accessibility/aria/attributes/aria-description/index.md +++ /dev/null @@ -1,58 +0,0 @@ ---- -title: aria-description -slug: Web/Accessibility/ARIA/Attributes/aria-description -page-type: aria-attribute -spec-urls: https://w3c.github.io/aria/#aria-description ---- - -{{AccessibilitySidebar}} - -The global `aria-description` attribute defines a string value that describes or annotates the current element. - -> **Note:** `aria-description` is still in W3C Editor's Draft for ARIA 1.3. For the time being, continue to use [`aria-describedby`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-describedby), which has been supported since ARIA 1.1. - -## Description - -The global `aria-description` attribute provides a mechanism for the developer to describe or annotate the current element providing greater context for assistive technology users. - -```html -<div - role="application" - aria-label="calendar" - aria-description="Game schedule for the Boston Red Sox 2021 Season"> - <h1>Red Sox 2021</h1> - <div role="grid">…</div> -</div> -``` - -The `aria-description` attribute is similar to [`aria-label`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-label) in that both provide a text string to associate with the element, but a label should be short and concise, while the description can be longer as it is intended to provide more context and information. - -The `aria-description` and `aria-describedby` properties have the same purpose; both provide the user with additional descriptive text for the object on which it is set. If descriptive text is available in the DOM, use [`aria-describedby`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-describedby) instead. - -The `aria-description` property should only be used when providing a visible description is not the desired user experience. The `aria-describedby` attribute takes as its value a list of `id`s of the elements that contain descriptive text about the object. The `aria-description` is used when there is no appropriate descriptive text that can be associated with the object by `id` reference. If both attributes are present, `aria-describedby` takes precedence in defining the {{glossary("accessible description")}} property. - -The content of the description, whether set by `aria-description` or `aria-describedby`, should be flat text. If the content is very long, has semantic meaning requirements, or has a navigational structure, use [`aria-details`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-details) instead. - -## Values - -- `<string>` - - : The value is a string, an unconstrained value type, that is intended to be conveyed to the assistive technology user. - -## Associated interfaces - -- {{domxref("Element.ariaDescription")}} - - : The [`ariaDescription`](/en-US/docs/Web/API/Element/ariaDescription) property, part of the {{domxref("Element")}} interface, reflects the value of the `aria-description` attribute, which defines a string value that describes or annotates the current element. - -## Associated roles - -Used in **ALL** roles. - -## Specifications - -{{Specifications}} - -## See also - -- [HTML `title` attribute](/en-US/docs/Web/HTML/Global_attributes/title) -- [`aria-describedby`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-describedby) -- [`aria-details`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-details) diff --git a/files/en-us/web/accessibility/aria/attributes/aria-details/index.md b/files/en-us/web/accessibility/aria/attributes/aria-details/index.md deleted file mode 100644 index 70aeea800cf677f..000000000000000 --- a/files/en-us/web/accessibility/aria/attributes/aria-details/index.md +++ /dev/null @@ -1,76 +0,0 @@ ---- -title: aria-details -slug: Web/Accessibility/ARIA/Attributes/aria-details -page-type: aria-attribute -spec-urls: https://w3c.github.io/aria/#aria-details ---- - -{{AccessibilitySidebar}} - -The global `aria-details` attribute identifies the element (or elements) that provide additional information related to the object. - -## Description - -The `aria-details` attribute can be used to provide additional information or complex descriptions to an object. It is used to inform assistive technology users about the content by providing more in-depth information, whether that content is within the current document or a link to additional assets. - -There are other HTML and WAI-ARIA properties that have similar purposes. The HTML {{HTMLElement('label')}} element and the [`aria-label`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-label) and [`aria-labelledby`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-labelledby) properties are used to provide short labels for an object. The HTML `title` attribute and the [`aria-description`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-description) and [`aria-describedby`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-describedby) properties provide for longer plain text descriptions of an object. However, when additional information, complex descriptions, or navigable content related to the object is necessary and available, the `aria-details` attribute should be used. - -The `aria-details` attribute serves a similar purpose as HTML's never fully-supported `longdesc` attribute - a URL of a long description to a replaced element's content - which was deprecated due to lack of support and misuse. - -The `aria-details` attribute takes the [`id`](/en-US/docs/Web/HTML/Global_attributes/id), or space separated list of `id`s of the elements to get more detailed information as its values. When `aria-details` is included on an element, assistive technologies inform users of the availability of extended information, enabling the user to navigate to the referenced content. - -Elements referenced by `aria-details` are intended to contain more information than would normally be provided via [`aria-describedby`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-describedby). - -The elements referenced by `aria-details` should be visible to all users. `aria-details` informs users that otherwise might not be able to scan a screen and discern quickly that the explanatory content is available. - -> **Note:** `aria-details` has no impact on the accessible description. - -Unlike `aria-describedby`, elements referenced by `aria-details` are not used in accessible descriptions and are not turned into a plain string when presented to assistive technology users. If the associated content is not too long and flattening the contents of the referenced element to a simple string of text wouldn't cause loss of information, consider using `aria-describedby` instead. That said, it is valid for an element to have both `aria-details` and a description specified with either `aria-describedby` or `aria-description`. - -## Example - -When it comes to definition and term roles, the `aria-details` would be included on the [`term`](/en-US/docs/Web/Accessibility/ARIA/Roles/term_role) element with the `id` of the element with a [`definition`](/en-US/docs/Web/Accessibility/ARIA/Roles/definition_role) role. - -```html -<p>The <strong>cubic-bezier()<strong> functional notation defines a cubic - <span role="term" aria-details="bezier bezImg">Bézier curve</span>. As - these curves are continuous, they are often used to smooth down the start and - end of the curve and are therefore sometimes called easing functions. -</p> - -<p role="definition" id="bezier">A <strong>Bézier curve</strong>, - (Pronounced \ ˈbe-zē-ˌā \) - <i aria-description="English pronunciation">BEH-zee-ay</i>) is a mathematically - described curve used in computer graphics and animation. The curve is defined - by a set of control points with a minimum of two. Web related graphics - and animations use Cubic Béziers, which are curves with four control - points P<sub>0</sub>, P<sub>1</sub>, P<sub>2</sub>, and P<sub>3</sub>. -</p> - -<a href="bezierExplanation.html" id="bezImg" - aria-label="Explanation of Bézier curve in CSS easing functions"> - <img alt="Animated Bézier curve showing 4 control points." src="bezier.gif"> -</a> -``` - -## Values - -- ID reference list - - : An `id` or space separated list of ids of elements that provide or link to additional related information. - -## Associated roles - -Used in **ALL** roles. - -## Specifications - -{{Specifications}} - -## See also - -- HTML [id](/en-US/docs/Web/HTML/Global_attributes/id) attribute -- [`aria-labelledby`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-labelledby) -- [`aria-describedby`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-describedby) -- [`aria-description`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-description) -- [The image `alt` attribute](/en-US/docs/Web/API/HTMLImageElement/alt) -- HTML [title](/en-US/docs/Web/HTML/Global_attributes/title) attribute diff --git a/files/en-us/web/accessibility/aria/attributes/aria-disabled/index.md b/files/en-us/web/accessibility/aria/attributes/aria-disabled/index.md deleted file mode 100644 index 93d96273778534e..000000000000000 --- a/files/en-us/web/accessibility/aria/attributes/aria-disabled/index.md +++ /dev/null @@ -1,161 +0,0 @@ ---- -title: aria-disabled -slug: Web/Accessibility/ARIA/Attributes/aria-disabled -page-type: aria-attribute -spec-urls: https://w3c.github.io/aria/#aria-disabled ---- - -{{AccessibilitySidebar}} - -The `aria-disabled` state indicates that the element is perceivable but disabled, so it is not editable or otherwise operable. - -## Description - -The `aria-disabled` attribute, when set to `true`, indicates that the element upon which it is set and all of its focusable descendants are meant to be in the disabled state. This declaration will inform people using assistive technologies, such as screen readers, that such elements are not meant to be editable or otherwise operable. - -Unlike HTML's [`disabled`](/en-US/docs/Web/HTML/Element/input#disabled) Boolean attribute, which will communicate a form control as semantically being disabled, change its styling to reflect its state and suppress all functionality along with disallowing the element's value from participating in form submission, the `aria-disabled="true"` <strong>only</strong> semantically exposes these elements as being disabled. Web developers must manually ensure such elements have their functionality suppressed when exposed to the disabled state. - -When needing to disable native HTML form controls, developers will need to specify the `disabled` attribute, as it provides all of the generally expected features of disabling a control by default. However, there can be instances where elements need to be exposed as disabled, but are still available for users to find when navigating via the <kbd>Tab</kbd> key. Doing so can improve their discoverability as they will not be removed from the focus order of the web page, as `aria-disabled` does not change the focusability of such elements, nor will the elements be dimmed by default browser styling, making them easier to read. Some examples of where this may be useful include: - -- The header button element associated with non-collapsible accordion panel, -- A button which is important to keep in the page's focus order, but its action is presently unavailable - such as submitting a form, -- Temporarily inactive items in a menu widget that would otherwise be skipped over via standard keyboard navigation. - -In each of these cases, one may want users to find these elements through standard keyboard navigation, though the functionality of that control is removed or "disabled". Developers will still need to use JavaScript to fully disable the functionality of the element while also changing the appearance of the element so sighted users know it is disabled. - -> [!NOTE] -> The state of being disabled applies to the element with `aria-disabled="true"` and all of its focusable descendants. Take care when using this attribute on container elements. Particularly in the case where a container may have both form controls and links - where the intent may be to expose the form controls as being in the disabled state, but <strong>not</strong> to communicate the links as being "disabled". - -Another reason to use the `aria-disabled` attribute over the HTML `disabled` attribute is if you have created custom controls which need to be marked as disabled, but are not using an element that allows for the `disabled` attribute. For instance, in the following snippet a `<div>` was used to create a custom button which needs to be marked as disabled. However, the `<div>` element does not expect, nor respect the `disabled` attribute - even if it were to be given a `role="button"` to change its exposed ARIA role. The `aria-disabled` attribute is required to disable such custom controls. - -```html -<div role="button" aria-disabled="true" tabindex="-1">Edit</div> -``` - -Similarly to needing to use JavaScript to ensure an element with `aria-disabled="true"` is not functional, the element will also need styling adjustments. In contrast to the HTML `disabled` attribute, where specifying it provides `:disabled` user-agent styles to be applied, adding `aria-disabled="true"` doesn't. The element can be styled with the [attribute selector](/en-US/docs/Web/CSS/Attribute_selectors) `[aria-disabled="true"]`. - -```css -[aria-disabled="true"] { - opacity: 0.5; -} -``` - -If you are purposefully using the `aria-disabled` attribute to allow for a form control to remain in the page's keyboard focus order, particularly if the element represents important content that all users should be able to perceive, then you may need to use styling that still passes color contrast requirements. For instance, a disabled button/heading that introduces a non-collapsible accordion panel is content that still needs to be legible. - -```css -@media (forced-colors: active) { - [aria-disabled="true"] { - border-color: GrayText; - color: GrayText; - } -} -``` - -The [`forced-colors` media query](/en-US/docs/Web/CSS/@media/forced-colors) detects if the [user agent](/en-US/docs/Glossary/User_agent) has enabled a forced colors mode; if so, the text and border colors are both set to the [system color `greyText`](/en-US/docs/Web/CSS/system-color#syntax). - -Another thing to keep in mind, when using `aria-disabled` over the native HTML attribute, is that the ARIA attribute will require the manual styling necessary to visually communicate the element as disabled in Windows High Contrast Mode. - -> [!NOTE] -> If you are using CSS's [`pointer-events: none;`](/en-US/docs/Web/CSS/pointer-events) to make an element non-clickable, make sure you disable interactivity with JavaScript as well. `pointer-events: none;` prevents mouse clicks, but does not prevent the element from being activated via the keyboard. - -```js -function onClick(event) { - event.preventDefault(); -} - -function toggleDisabled(element, status, update) { - if (status) { - //element.input.disabled = false; - element.setAttribute("aria-disabled", "false"); - update.textContent = "The element is now enabled."; - element.addEventListener("click", onClick); - } else { - //element.input.disabled = true; - element.setAttribute("aria-disabled", "true"); - update.textContent = "The element is now disabled."; - element.removeEventListener("click", onClick); - } -} -``` - -When toggling from `aria-disabled="true"` to `"false"`, use JavaScript to: - -1. Toggle the value to `false` (or remove the attribute entirely), -2. Enable the element, and -3. Let the user know the control is now enabled. - -If you used just CSS to style the disabled state using an attribute selector, the selector will no longer match and the disabled styling will no longer be in effect. - -## Values - -- `true` - - - : The element is disabled - -- `false` - - : The element is not disabled - -## Associated interfaces - -- {{domxref("Element.ariaDisabled")}} - - : The [`ariaDisabled`](/en-US/docs/Web/API/Element/ariaDisabled) property, part of the {{domxref("Element")}} interface, reflects the value of the `aria-disabled` attribute, which indicates that the element is perceivable but disabled, so it is not editable or otherwise operable. -- {{domxref("ElementInternals.ariaDisabled")}} - - : The [`ariaDisabled`](/en-US/docs/Web/API/ElementInternals/ariaDisabled) property of the {{domxref("ElementInternals")}} interface reflects the value of the `aria-disabled` attribute. - -## Associated roles - -Used in roles: - -- [`application`](/en-US/docs/Web/Accessibility/ARIA/Roles/application_role) -- [`button`](/en-US/docs/Web/Accessibility/ARIA/Roles/button_role) -- [`composite`](/en-US/docs/Web/Accessibility/ARIA/Roles/composite_role) -- [`gridcell`](/en-US/docs/Web/Accessibility/ARIA/Roles/gridcell_role) -- [`group`](/en-US/docs/Web/Accessibility/ARIA/Roles/group_role) -- [`input`](/en-US/docs/Web/Accessibility/ARIA/Roles/input_role) -- [`link`](/en-US/docs/Web/Accessibility/ARIA/Roles/link_role) -- [`menuitem`](/en-US/docs/Web/Accessibility/ARIA/Roles/menuitem_role) -- [`scrollbar`](/en-US/docs/Web/Accessibility/ARIA/Roles/scrollbar_role) -- [`separator`](/en-US/docs/Web/Accessibility/ARIA/Roles/separator_role) -- [`tab`](/en-US/docs/Web/Accessibility/ARIA/Roles/tab_role) - -Inherits into roles: - -- [`checkbox`](/en-US/docs/Web/Accessibility/ARIA/Roles/checkbox_role) -- [`columnheader`](/en-US/docs/Web/Accessibility/ARIA/Roles/columnheader_role) -- [`combobox`](/en-US/docs/Web/Accessibility/ARIA/Roles/combobox_role) -- [`grid`](/en-US/docs/Web/Accessibility/ARIA/Roles/grid_role) -- [`listbox`](/en-US/docs/Web/Accessibility/ARIA/Roles/listbox_role) -- [`menu`](/en-US/docs/Web/Accessibility/ARIA/Roles/menu_role) -- [`menubar`](/en-US/docs/Web/Accessibility/ARIA/Roles/menubar_role) -- [`menuitemcheckbox`](/en-US/docs/Web/Accessibility/ARIA/Roles/menuitemcheckbox_role) -- [`menuitemradio`](/en-US/docs/Web/Accessibility/ARIA/Roles/menuitemradio_role) -- [`option`](/en-US/docs/Web/Accessibility/ARIA/Roles/option_role) -- [`radio`](/en-US/docs/Web/Accessibility/ARIA/Roles/radio_role) -- [`radiogroup`](/en-US/docs/Web/Accessibility/ARIA/Roles/radiogroup_role) -- [`row`](/en-US/docs/Web/Accessibility/ARIA/Roles/row_role) -- [`rowheader`](/en-US/docs/Web/Accessibility/ARIA/Roles/rowheader_role) -- [`searchbox`](/en-US/docs/Web/Accessibility/ARIA/Roles/searchbox_role) -- [`select`](/en-US/docs/Web/Accessibility/ARIA/Roles/select_role) -- [`slider`](/en-US/docs/Web/Accessibility/ARIA/Roles/slider_role) -- [`spinbutton`](/en-US/docs/Web/Accessibility/ARIA/Roles/spinbutton_role) -- [`switch`](/en-US/docs/Web/Accessibility/ARIA/Roles/switch_role) -- [`tablist`](/en-US/docs/Web/Accessibility/ARIA/Roles/tablist_role) -- [`textbox`](/en-US/docs/Web/Accessibility/ARIA/Roles/textbox_role) -- [`toolbar`](/en-US/docs/Web/Accessibility/ARIA/Roles/toolbar_role) -- [`tree`](/en-US/docs/Web/Accessibility/ARIA/Roles/tree_role) -- [`treegrid`](/en-US/docs/Web/Accessibility/ARIA/Roles/treegrid_role) -- [`treeitem`](/en-US/docs/Web/Accessibility/ARIA/Roles/treeitem_role) - -## Specifications - -{{Specifications}} - -## See also - -- [Making disabled buttons more inclusive](https://css-tricks.com/making-disabled-buttons-more-inclusive/) by Sandrina Pereira -- [Styling for Windows high contrast with new standards for forced colors](https://blogs.windows.com/msedgedev/2020/09/17/styling-for-windows-high-contrast-with-new-standards-for-forced-colors/) -- [disabled](/en-US/docs/Web/HTML/Attributes/disabled) -- {{domxref("Element.ariaDisabled")}} -- {{domxref("ElementInternals.ariaDisabled")}} -- [`aria-hidden`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-hidden) -- [`aria-readonly`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-readonly) diff --git a/files/en-us/web/accessibility/aria/attributes/aria-dropeffect/index.md b/files/en-us/web/accessibility/aria/attributes/aria-dropeffect/index.md deleted file mode 100644 index 8ea52f308e8588c..000000000000000 --- a/files/en-us/web/accessibility/aria/attributes/aria-dropeffect/index.md +++ /dev/null @@ -1,64 +0,0 @@ ---- -title: aria-dropeffect -slug: Web/Accessibility/ARIA/Attributes/aria-dropeffect -page-type: aria-attribute -status: - - deprecated -spec-urls: https://w3c.github.io/aria/#aria-dropeffect ---- - -{{AccessibilitySidebar}} - -The global `aria-dropeffect` attribute indicates what functions may be performed when a dragged object is released on the drop target. {{deprecated_inline}} - -## Description - -Deprecated in ARIA 1.1, the `aria-dropeffect` property indicates what functions may be performed when a dragged object is released on the drop target. The global `aria-dropeffect` attribute provides assistive technology users the same information provided via the [`DataTransfer.dropEffect`](/en-US/docs/Web/API/DataTransfer/dropEffect) to sited users via the dropeffect icon. - -Text selections, images, and links can be dragged by default. Setting the global [`draggable="true"`](/en-US/docs/Web/HTML/Global_attributes/draggable) attribute, part of HTML5's [Drag and Drop API](/en-US/docs/Web/API/HTML_Drag_and_Drop_API), with a [`dragstart` event handler](/en-US/docs/Web/API/HTMLElement/dragstart_event), means any DOM node can be made draggable as well. - -When a drag event occurs, a translucent image is generated of the dragged element which follows the user's pointer during the drag. The default image can be changed to any image with [`setDragImage`](/en-US/docs/Web/API/DataTransfer/setDragImage). Along with the default image identifying the element being dragged, there is a [`dataTransfer.dropEffect`](/en-US/docs/Web/API/DataTransfer/dropEffect) property that can be used to control the visual feedback the user is given during a drag-and-drop operation. The `aria-dropeffect` property should be used to provide assistive technology users the same feedback provided to sited users via `dataTransfer.dropEffect` property. - -`dropeffect` defines which cursor the browser displays while dragging, and is set on the element on which the element may be dropped. During the drag operation, as the draggable element is dragged over different drop areas, the drag effects—both the `dataTransfer.dropeffect` and the `aria-dropeffect` should be modified to indicate the type of operation that will occur if the dragged element is released. - -More than one drop effect may be supported for a given element. Therefore, the value of the `aria-dropeffect` attribute is a space separated list of functions. Functions include `copy`, `execute`, `link`, and `move`. The default is `none`, meaning there is no supported functionality in the application. Setting `aria-dropeffect="popup"` informs assistive technology users that there is a popup menu or dialog of drag operations from which the user can choose. - -Including the attribute provides assistive technologies the ability to convey the possible drag options available to the assistive technology user, but doesn't add any actual functionality. - -The `aria-dropeffect` property is expected to be replaced by a new feature in a future version of WAI-ARIA and is considered deprecated. - -Typically, drop effect functions can only be provided once an object has been grabbed for a drag operation, as the drop effect functions available are dependent on the object being dragged. Therefore, you'll generally add `aria-dropeffect` to all the potential drop targets when the {{domxref("HTMLElement/dragstart_event", "dragstart")}} event is fired. - -## Values - -The value is a space separated list of possible actions. The following are the valid tokens: - -- `copy` - - : A duplicate of the source object will be dropped into the target. -- `execute` - - : A function supported by the drop target is executed, using the drag source as an input. -- `link` - - : A reference or shortcut to the dragged object will be created in the target object. -- `move` - - : The source object will be removed from its current location and dropped into the target. -- `none` (default) - - : No operation can be performed; effectively cancels the drag operation if an attempt is made to drop on this object. Ignored if combined with any other token value; for example, 'none copy' is equivalent to a 'copy' value. -- `popup` - - : There is a popup menu or dialog that allows the user to choose one of the drag operations (copy, move, link, execute) and any other drag functionality, such as cancel. - -## Associated roles - -Used in **ALL** roles. - -## Specifications - -{{Specifications}} - -## See also - -- [`aria-grabbed`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-grabbed) -- [HTML global `draggable` attribute](/en-US/docs/Web/HTML/Global_attributes/draggable) -- HTML [Drag and Drop API](/en-US/docs/Web/API/HTML_Drag_and_Drop_API) -- {{domxref('dataTransfer')}} -- {{domxref('DataTransfer.dropEffect')}} -- {{domxref("HTMLElement/dragstart_event", "dragstart")}} diff --git a/files/en-us/web/accessibility/aria/attributes/aria-errormessage/index.md b/files/en-us/web/accessibility/aria/attributes/aria-errormessage/index.md deleted file mode 100644 index 260168b96a7b276..000000000000000 --- a/files/en-us/web/accessibility/aria/attributes/aria-errormessage/index.md +++ /dev/null @@ -1,102 +0,0 @@ ---- -title: aria-errormessage -slug: Web/Accessibility/ARIA/Attributes/aria-errormessage -page-type: aria-attribute -spec-urls: https://w3c.github.io/aria/#aria-errormessage ---- - -{{AccessibilitySidebar}} - -The `aria-errormessage` attribute on an object identifies the element that provides an error message for that object. - -## Description - -When there is a user-created error, you want to let them know it exists and tell them how to fix it. There are two attributes you need to use: set [`aria-invalid="true"`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-invalid) to define the object as being in an error state, then add the `aria-errormessage` attribute with the value being the `id` of the element containing the error message text for that object. - -The `aria-errormessage` attribute should only be used when the value of an object is not valid; when [`aria-invalid`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-invalid) is set to `true`. If the object is valid and you include the `aria-errormessage` attribute, make sure the element referenced is hidden, as the message it contains is not relevant. - -When `aria-errormessage` is relevant, the element it references must be visible so users can see or hear the error message. - -Often times, you will want the element with the error message to be an [ARIA live region](/en-US/docs/Web/Accessibility/ARIA/ARIA_Live_Regions), such as when an error message is displayed to users after they have provided an invalid value. The error message should describe what is wrong and inform the user what is required to make the object valid. Adding the error message as an ARIA live region informs assistive technologies that the user may benefit from the error message content even if the error message wouldn't otherwise be conveyed to the user. - -Include a visible error message and link the invalid object with the `aria-errormessage` attribute if the failure is visually apparent and an explicit description of the error is necessary. - -## Example - -We create some styles to: - -1. Hide all error messages, -2. Make invalid objects appear invalid, and -3. Show error messages that are siblings coming after an invalid object. - -We use `aria-invalid="true"` to identify invalid objects: - -```css -.errormessage { - visibility: hidden; -} - -[aria-invalid="true"] { - outline: 2px solid red; -} - -[aria-invalid="true"] ~ .errormessage { - visibility: visible; -} -``` - -When an object is invalid, we use JavaScript to add `aria-invalid="true"`. The above CSS makes the `.errormessage` following an invalid object become visible. - -```html -<p> - <label for="email">Email address:</label> - <input - type="email" - name="email" - id="email" - aria-invalid="true" - aria-errormessage="err1" /> - <span id="err1" class="errormessage">Error: Enter a valid email address</span> -</p> -``` - -When we went from valid to invalid, the only JavaScript change for this example was an update to `aria-invalid` on the email input object. As the error message follows the input and becomes visible and available on the accessibility tree, we are able to keep our example simple. We could have also applied an [`aria-live`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-live) property or used a live region roles such as [`alert`](/en-US/docs/Web/Accessibility/ARIA/Roles/alert_role). - -## Values - -- `id` reference - - : The value of the `id` of the element containing the error message for the current element - -## Associated roles - -Used in roles: - -- [`application`](/en-US/docs/Web/Accessibility/ARIA/Roles/application_role) -- [`checkbox`](/en-US/docs/Web/Accessibility/ARIA/Roles/checkbox_role) -- [`combobox`](/en-US/docs/Web/Accessibility/ARIA/Roles/combobox_role) -- [`gridcell`](/en-US/docs/Web/Accessibility/ARIA/Roles/gridcell_role) -- [`listbox`](/en-US/docs/Web/Accessibility/ARIA/Roles/listbox_role) -- [`radiogroup`](/en-US/docs/Web/Accessibility/ARIA/Roles/radiogroup_role) -- [`slider`](/en-US/docs/Web/Accessibility/ARIA/Roles/slider_role) -- [`spinbutton`](/en-US/docs/Web/Accessibility/ARIA/Roles/spinbutton_role) -- [`textbox`](/en-US/docs/Web/Accessibility/ARIA/Roles/textbox_role) -- [`tree`](/en-US/docs/Web/Accessibility/ARIA/Roles/tree_role) - -Inherits from roles: - -- [`columnheader`](/en-US/docs/Web/Accessibility/ARIA/Roles/columnheader_role) -- [`rowheader`](/en-US/docs/Web/Accessibility/ARIA/Roles/rowheader_role) -- [`searchbox`](/en-US/docs/Web/Accessibility/ARIA/Roles/searchbox_role) -- [`switch`](/en-US/docs/Web/Accessibility/ARIA/Roles/switch_role) -- [`treegrid`](/en-US/docs/Web/Accessibility/ARIA/Roles/treegrid_role) - -## Specifications - -{{Specifications}} - -## See also - -- CSS {{CSSxref(':invalid')}} pseudoclass -- [`aria-invalid`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-invalid) -- [`aria-describedby`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-describedby) -- [`aria-live`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-live) diff --git a/files/en-us/web/accessibility/aria/attributes/aria-expanded/index.md b/files/en-us/web/accessibility/aria/attributes/aria-expanded/index.md deleted file mode 100644 index 92c071f4502a693..000000000000000 --- a/files/en-us/web/accessibility/aria/attributes/aria-expanded/index.md +++ /dev/null @@ -1,124 +0,0 @@ ---- -title: aria-expanded -slug: Web/Accessibility/ARIA/Attributes/aria-expanded -page-type: aria-attribute -spec-urls: https://w3c.github.io/aria/#aria-expanded ---- - -{{AccessibilitySidebar}} - -The `aria-expanded` attribute is set on an element to indicate if a control is expanded or collapsed, and whether or not the controlled elements are displayed or hidden. - -## Description - -There are several widgets that can be expanded and collapsed, including menus, dialogs, and accordion panels. Each of these objects, in turn, has an interactive element that controls their opening and closing. The `aria-expanded` attribute is applied to this focusable, interactive control that toggles the visibility of the object. - -For example, `aria-expanded` is applied to the parent item in a DOM tree to indicate whether its child branch is shown. The parent controls the visibility of the associated child branch, as well. - -There are two declarations that can be applied to objects that control the visibility of another object: [`aria-controls`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-controls), or [`aria-owns`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-owns) combined with `aria-expanded`. The `aria-controls` and `aria-owns` indicate the relationship between the controlling element and the controlled element. The `aria-expanded` indicates to assistive technology whether the controlled element is expanded or collapsed. - -Use the `aria-owns` property on the elements that own expandable grouping containers. If the expandable and collapsible grouping container is not owned by the element that has the `aria-expanded` attribute, use the `aria-controls` property to reference the grouping container instead. - -### Buttons - -A button that toggles a widget should have `aria-controls` set to the [`id`](/en-US/docs/Web/HTML/Global_attributes/id) of the toggled widget and `aria-expanded` set to the current state of the widget. - -```html -<button aria-expanded="false" aria-controls="widget1">Toggle widget</button> -``` - -When the widget is visible, the controlling object relays that information via having `aria-expanded="true"` set on it. The accessible name of the controlling object should reflect this change. - -```html -<button aria-expanded="true" aria-controls="widget1">Toggle widget</button> -``` - -### Menu - -When a [`menu`](/en-US/docs/Web/Accessibility/ARIA/Roles/menu_role) is displayed, the button object that toggles the visibility of that menu has `aria-expanded="true"` set. When the menu is hidden, aria-expanded can be omitted. If specified when the menu is hidden, it should be set as `aria-expanded="false"`. When a child menu is not visible, its parent [`menuitem`](/en-US/docs/Web/Accessibility/ARIA/Roles/menuitem_role) has `aria-expanded`. It should be set to `true` when the child menu is visible. - -### Combobox - -By default, some roles are hidden or collapsed and other roles are open or expanded by default. Elements with role [`combobox`](/en-US/docs/Web/Accessibility/ARIA/Roles/combobox_role) have a default value for `aria-expanded` of `false`. When a combobox popup is not visible, the element with role `combobox` has `aria-expanded` set to `false`. This is the default state. When the popup element is visible, `aria-expanded` should be set to `true`. - -```html -<label for="username">Username</label> -<input id="username" name="username" aria-describedby="username-desc" /> -<button - aria-expanded="false" - aria-controls="username-desc" - aria-label="Help about username" - type="button"> - <span aria-hidden="true">?</span> -</button> -<p id="username-desc" hidden> - Your username is the name that you use to log in to this service. -</p> -``` - -> [!NOTE] -> The presence of the `aria-expanded` attribute indicates control. Avoid including it on elements that do not control the expanded state of other elements. - -### Treeitems - -Each element with role [`treeitem`](/en-US/docs/Web/Accessibility/ARIA/Roles/treeitem_role) that serves as a parent node has `aria-expanded="false"` when the node is in a closed state and `aria-expanded="true"` when the node is in an open state. End nodes, nodes with no descendant nodes, should not have the `aria-expanded` attribute because, if they were to have it, they would be incorrectly described to assistive technologies as parent nodes. - -### Rows - -A parent row in a [`treegrid`](/en-US/docs/Web/Accessibility/ARIA/Roles/treegrid_role) is a row that can be expanded or collapsed to show or hide a set of child rows in a table or grid. Each parent row has the `aria-expanded` state set on either the row element or on a cell contained in the row. When the child rows are hidden, `aria-expanded="false"` is set. `aria-expanded="true"` is set when the child rows are displayed. Rows that do not control the display of child rows should not include the `aria-expanded` attribute at all because including the attribute defines the rows as parent rows. - -## Values - -- `false` - - - : The grouping element this element owns or controls is collapsed. - -- `true` - - - : The grouping element this element owns or controls is expanded. - -- `undefined` (default) - - : The element does not own or control a grouping element that is expandable. - -## Associated interfaces - -- {{domxref("Element.ariaExpanded")}} - - : The [`ariaExpanded`](/en-US/docs/Web/API/Element/ariaExpanded) property, part of the {{domxref("Element")}} interface, reflects the value of the `aria-expanded` attribute. -- {{domxref("ElementInternals.ariaExpanded")}} - - : The [`ariaExpanded`](/en-US/docs/Web/API/Element/ariaExpanded) property, part of the {{domxref("ElementInternals")}} interface, reflects the value of the `aria-expanded` attribute. - -## Associated roles - -Used in roles: - -- [`application`](/en-US/docs/Web/Accessibility/ARIA/Roles/application_role) -- [`button`](/en-US/docs/Web/Accessibility/ARIA/Roles/button_role) -- [`checkbox`](/en-US/docs/Web/Accessibility/ARIA/Roles/checkbox_role) -- [`combobox`](/en-US/docs/Web/Accessibility/ARIA/Roles/combobox_role) -- [`gridcell`](/en-US/docs/Web/Accessibility/ARIA/Roles/gridcell_role) -- [`link`](/en-US/docs/Web/Accessibility/ARIA/Roles/link_role) -- [`listbox`](/en-US/docs/Web/Accessibility/ARIA/Roles/listbox_role) -- [`menuitem`](/en-US/docs/Web/Accessibility/ARIA/Roles/menuitem_role) -- [`row`](/en-US/docs/Web/Accessibility/ARIA/Roles/row_role) -- [`rowheader`](/en-US/docs/Web/Accessibility/ARIA/Roles/rowheader_role) -- [`tab`](/en-US/docs/Web/Accessibility/ARIA/Roles/tab_role) -- [`treeitem`](/en-US/docs/Web/Accessibility/ARIA/Roles/treeitem_role) - -Inherits into roles: - -- [`columnheader`](/en-US/docs/Web/Accessibility/ARIA/Roles/columnheader_role) -- [`menuitemcheckbox`](/en-US/docs/Web/Accessibility/ARIA/Roles/menuitemcheckbox_role) -- [`menuitemradio`](/en-US/docs/Web/Accessibility/ARIA/Roles/menuitemradio_role) -- [`rowheader`](/en-US/docs/Web/Accessibility/ARIA/Roles/rowheader_role) -- [`switch`](/en-US/docs/Web/Accessibility/ARIA/Roles/switch_role) - -## Specifications - -{{Specifications}} - -## See also - -- [`aria-controls`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-controls) -- [`aria-owns`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-owns) -- [`aria-hidden`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-hidden) -- HTML [`hidden`](/en-US/docs/Web/HTML/Global_attributes/hidden) attribute diff --git a/files/en-us/web/accessibility/aria/attributes/aria-flowto/index.md b/files/en-us/web/accessibility/aria/attributes/aria-flowto/index.md deleted file mode 100644 index e82dbba308a075a..000000000000000 --- a/files/en-us/web/accessibility/aria/attributes/aria-flowto/index.md +++ /dev/null @@ -1,44 +0,0 @@ ---- -title: aria-flowto -slug: Web/Accessibility/ARIA/Attributes/aria-flowto -page-type: aria-attribute -spec-urls: https://w3c.github.io/aria/#aria-flowto ---- - -{{AccessibilitySidebar}} - -The global `aria-flowto` attribute identifies the next element (or elements) in an alternate reading order of content. This allows assistive technology to override the general default of reading in document source order at the user's discretion. - -## Description - -Web pages should be sequentially navigable. For this reason, developers are dissuaded from using the global [tabindex](/en-US/docs/Web/HTML/Global_attributes/tabindex) attribute which can change tab order and the CSS {{CSSXRef('order')}} property, which can change visual order from the DOM order. However, in rare circumstances a reading path different from the source order is required. For such cases, the `aria-flowto` attribute can make the content more accessible for users of assistive technologies. - -The global `aria-flowto` attribute lets the author indicate to assistive technology users which element or elements might want to be focused on next, providing an alternate reading order to the source order. This allows assistive technology to read a document in an order other than the default document source reading order. - -When `aria-flowto` has a single [id](/en-US/docs/Web/HTML/Global_attributes/id) reference, it allows assistive technologies to, at the user's request, go to the element targeted via that `id` instead of reading the document in the order of the DOM. When the `aria-flowto` value uses a space separated list of multiple `id` references, assistive technology can provide the user with a list of path choices, with each `id` referenced being a choice. The path choice names are determined by the accessible name of each target element of the `aria-flowto` attribute. - -> [!NOTE] -> Setting `aria-flowto` does not impact the content's tab order. It only provides users the option to follow a content path that doesn't match the DOM order when using tech that supports this attribute. - -## Values - -- `id` - - : Suggested next element in the reading order. -- `id` list - - : Space separated list of ID values referencing the suggested elements the user may want to go to next in the alternate reading order of content. - -## Associated roles - -Used in **ALL** roles. - -## Specifications - -{{Specifications}} - -## See also - -- HTML [id](/en-US/docs/Web/HTML/Global_attributes/id) attribute -- HTML [tabindex](/en-US/docs/Web/HTML/Global_attributes/tabindex) attribute -- CSS {{CSSXRef('order')}} property -- [WCAG: source order](/en-US/docs/Web/Accessibility/Understanding_WCAG/Operable#guideline_2.4_—_navigable_provide_ways_to_help_users_navigate_find_content_and_determine_where_they_are) -- [Using aria-flowto](https://www.w3.org/WAI/GL/wiki/Using_aria-flowto) - W3 Wiki diff --git a/files/en-us/web/accessibility/aria/attributes/aria-grabbed/index.md b/files/en-us/web/accessibility/aria/attributes/aria-grabbed/index.md deleted file mode 100644 index 34c2a9ec08f5300..000000000000000 --- a/files/en-us/web/accessibility/aria/attributes/aria-grabbed/index.md +++ /dev/null @@ -1,53 +0,0 @@ ---- -title: aria-grabbed -slug: Web/Accessibility/ARIA/Attributes/aria-grabbed -page-type: aria-attribute -status: - - deprecated -spec-urls: https://w3c.github.io/aria/#aria-grabbed ---- - -{{AccessibilitySidebar}} - -The `aria-grabbed` state indicates an element's "grabbed" state in a drag-and-drop operation. {{deprecated_inline}} - -## Description - -Text selections, images, and links can be dragged by default. Setting the global [`draggable="true"`](/en-US/docs/Web/HTML/Global_attributes/draggable) attribute, part of HTML5's [Drag and Drop API](/en-US/docs/Web/API/HTML_Drag_and_Drop_API), with a [`dragstart` event handler](/en-US/docs/Web/API/HTMLElement/dragstart_event), means any DOM node can be made draggable as well. - -The `aria-grabbed` attribute was used to indicate if an element is in a "grabbed" state in a drag-and-drop operation with `aria-grabbed="true"` or if that the element is grabbable, but not currently grabbed with `aria-grabbed="false"`. - -Setting `aria-grabbed="true"` indicated the element had been selected for dragging. Setting `aria-grabbed="false"` indicated that the element could be grabbed for a drag-and-drop operation, but is not currently grabbed. - -When `aria-grabbed` is set to `true`, the [`aria-dropeffect`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-dropeffect) attribute of all potential drop targets should be updated with the type of function, or effect, will occur to the grabbed element when it is dropped. When no element is in a grabbed state, revert the `aria-dropeffect` attributes of all your drop targets. - -The `aria-grabbed` property is expected to be replaced by a new feature in a future version of WAI-ARIA and is considered deprecated. - -> [!NOTE] -> ARIA does not enable accessible functionality. ARIA only conveys the intended behavior of your functionality. - -## Values - -- `true` - - : The element has been selected for dragging. -- `false` - - : The element is not currently selected for dragging, but can be made available for dragging by setting the property to `true`. -- `undefined` (default) - - : The element does not support being dragged - -## Associated roles - -Used in **ALL** [roles](/en-US/docs/Web/Accessibility/ARIA/Roles) - -## Specifications - -{{Specifications}} - -## See also - -- [`aria-dropeffect`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-dropeffect) -- [HTML global `draggable` attribute](/en-US/docs/Web/HTML/Global_attributes/draggable) -- HTML [Drag and Drop API](/en-US/docs/Web/API/HTML_Drag_and_Drop_API) -- {{domxref('dataTransfer')}} -- {{domxref('DataTransfer.dropEffect')}} -- {{domxref("HTMLElement/dragstart_event", "dragstart")}} diff --git a/files/en-us/web/accessibility/aria/attributes/aria-haspopup/index.md b/files/en-us/web/accessibility/aria/attributes/aria-haspopup/index.md deleted file mode 100644 index d2c163d1c0e0b2f..000000000000000 --- a/files/en-us/web/accessibility/aria/attributes/aria-haspopup/index.md +++ /dev/null @@ -1,92 +0,0 @@ ---- -title: aria-haspopup -slug: Web/Accessibility/ARIA/Attributes/aria-haspopup -page-type: aria-attribute -spec-urls: https://w3c.github.io/aria/#aria-haspopup ---- - -{{AccessibilitySidebar}} - -The `aria-haspopup` attribute indicates the availability and type of interactive popup element that can be triggered by the element on which the attribute is set. - -## Description - -In ARIA, interactive menus, listboxes, trees, grids, and dialogs that appear on top of other content when triggered to appear are considered "popups". These popups are triggered by one or more interactive elements on the page. The availability and type of popup the interactive element will trigger should be identified with the `aria-haspopup` state. - -The presence of the `aria-haspopup`, with one of six enumerated values - `menu`, `listbox`, `tree`, `grid`, `dialog`, or `true` - indicates the element can trigger a popup and what kind of popup will be displayed. In turn, the element that pops up must be of the role indicated. The value `true` is the same as `menu`. Any other value, including an empty string or other [role](/en-US/docs/Web/Accessibility/ARIA/Roles), is treated as if `false` were set. - -A [`tooltip`](/en-US/docs/Web/Accessibility/ARIA/Roles/tooltip_role) is not considered to be a popup in this context, as it is not interactive. - -> [!NOTE] -> Make sure the role of the element that serves as the container for the popup content is a [`menu`](/en-US/docs/Web/Accessibility/ARIA/Roles/menu_role), [`listbox`](/en-US/docs/Web/Accessibility/ARIA/Roles/listbox_role), [`tree`](/en-US/docs/Web/Accessibility/ARIA/Roles/tree_role), [`grid`](/en-US/docs/Web/Accessibility/ARIA/Roles/grid_role) or [`dialog`](/en-US/docs/Web/Accessibility/ARIA/Roles/dialog_role) and that the value of `aria-haspopup` matches the role of the popup container. - -The `aria-haspopup` state informs assistive technology users that there is a popup and the type of popup it is, but provides no interactivity. For the popup to be keyboard accessible, make sure the element with `aria-haspopup` is focusable and can trigger the popup, that there is a keyboard mechanism for opening the popup, and that the popup element manages focus of all its descendants. - -> [!NOTE] -> ARIA does not enable accessible functionality. ARIA only conveys the intended behavior of your functionality. - -When creating a [`menubar`](/en-US/docs/Web/Accessibility/ARIA/Roles/menubar_role), a parent [`menuitem`](/en-US/docs/Web/Accessibility/ARIA/Roles/menuitem_role) should have `aria-haspopup="menu"` (or `true`) set. Any button that open a menu should have a role of [`button`](/en-US/docs/Web/Accessibility/ARIA/Roles/button_role) or, preferably, be a {{HTMLElement('button')}}, and also have `aria-haspopup="menu"` (or `true`) set. [`Tab`](/en-US/docs/Web/Accessibility/ARIA/Roles/tab_role) elements with popup menus should also have `aria-haspopup="menu"` set. Note that `menubar`s should not be used to create website navigation. - -> [!NOTE] -> Elements with role [`combobox`](/en-US/docs/Web/Accessibility/ARIA/Roles/combobox_role) have an implicit `aria-haspopup` value of `listbox`. - -## Values - -- `false` (default) - - : The element does not have a popup. -- `true` - - : The popup is a menu. -- `menu` - - : The popup is a menu. -- `listbox` - - : The popup is a listbox. -- `tree` - - : The popup is a tree. -- `grid` - - : The popup is a grid. -- `dialog` - - : The popup is a dialog. - -## Associated interfaces - -- {{domxref("Element.ariaHasPopup")}} - - : The [`ariaHasPopup`](/en-US/docs/Web/API/Element/ariaHasPopup) property, part of the {{domxref("Element")}} interface, reflects the value of the `aria-haspopup` attribute, which indicates the availability and type of interactive popup element, such as menu or dialog, that can be triggered by an element. -- {{domxref("ElementInternals.ariaHasPopup")}} - - : The [`ariaHasPopup`](/en-US/docs/Web/API/ElementInternals/ariaHasPopup) property of the {{domxref("ElementInternals")}} interface reflects the value of the `aria-haspopup` attribute. - -## Associated roles - -Used in roles: - -- [`application`](/en-US/docs/Web/Accessibility/ARIA/Roles/application_role) -- [`button`](/en-US/docs/Web/Accessibility/ARIA/Roles/button_role) -- [`combobox`](/en-US/docs/Web/Accessibility/ARIA/Roles/combobox_role) -- [`gridcell`](/en-US/docs/Web/Accessibility/ARIA/Roles/gridcell_role) -- [`link`](/en-US/docs/Web/Accessibility/ARIA/Roles/link_role) -- [`menuitem`](/en-US/docs/Web/Accessibility/ARIA/Roles/menuitem_role) -- [`slider`](/en-US/docs/Web/Accessibility/ARIA/Roles/slider_role) -- [`tab`](/en-US/docs/Web/Accessibility/ARIA/Roles/tab_role) -- [`textbox`](/en-US/docs/Web/Accessibility/ARIA/Roles/textbox_role) -- [`treeitem`](/en-US/docs/Web/Accessibility/ARIA/Roles/treeitem_role) - -Inherited into roles: - -- [`columnheader`](/en-US/docs/Web/Accessibility/ARIA/Roles/columnheader_role) -- [`menuitemcheckbox`](/en-US/docs/Web/Accessibility/ARIA/Roles/menuitemcheckbox_role) -- [`menuitemradio`](/en-US/docs/Web/Accessibility/ARIA/Roles/menuitemradio_role) -- [`rowheader`](/en-US/docs/Web/Accessibility/ARIA/Roles/rowheader_role) -- [`searchbox`](/en-US/docs/Web/Accessibility/ARIA/Roles/searchbox_role) - -## Specifications - -{{Specifications}} - -## See also - -- [`aria-controls`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-controls) -- [`menu`](/en-US/docs/Web/Accessibility/ARIA/Roles/menu_role) -- [`listbox`](/en-US/docs/Web/Accessibility/ARIA/Roles/listbox_role) -- [`tree`](/en-US/docs/Web/Accessibility/ARIA/Roles/tree_role) -- [`grid`](/en-US/docs/Web/Accessibility/ARIA/Roles/grid_role) -- [`dialog`](/en-US/docs/Web/Accessibility/ARIA/Roles/dialog_role) -- [Toolbar example](https://www.w3.org/WAI/ARIA/apg/patterns/toolbar/examples/toolbar/) - W3C WAI ARIA practices diff --git a/files/en-us/web/accessibility/aria/attributes/aria-hidden/index.md b/files/en-us/web/accessibility/aria/attributes/aria-hidden/index.md deleted file mode 100644 index 29064d7e10eaaf3..000000000000000 --- a/files/en-us/web/accessibility/aria/attributes/aria-hidden/index.md +++ /dev/null @@ -1,95 +0,0 @@ ---- -title: aria-hidden -slug: Web/Accessibility/ARIA/Attributes/aria-hidden -page-type: aria-attribute -spec-urls: https://w3c.github.io/aria/#aria-hidden ---- - -{{AccessibilitySidebar}} - -The `aria-hidden` state indicates whether the element is exposed to an accessibility API. - -## Description - -The `aria-hidden` attribute can be used to hide non-interactive content from the accessibility API. - -Adding `aria-hidden="true"` to an element removes that element and all of its children from the accessibility tree. This can improve the experience for assistive technology users by hiding: - -- Purely decorative content, such as icons or images -- Duplicated content, such as repeated text -- Offscreen or collapsed content, such as menus - -The presence of the `aria-hidden` attribute hides content from assistive technology but doesn't visually hide anything. - -`aria-hidden="true"` should not be used on elements that can receive focus. Additionally, since this attribute is inherited by an element's children, it should not be added onto the parent or ancestor of a focusable element. - -> [!WARNING] -> Do not use `aria-hidden="true"` on focusable elements. - -An element's hidden status is based on whether it is rendered. Rendering is usually controlled by CSS. For example, an element whose `display` property is set to `none` via CSS is not rendered. An element is considered hidden if it, or any of its ancestors are not rendered or have their `aria-hidden` attribute value set to true. Note that an element and its children that has `aria-hidden="true"` declared on it will still be visible, unless also hidden by CSS. - -Use caution when using `aria-hidden` to hide visibly rendered content from assistive technologies. You should not be hiding visible content unless doing so improves the experience for users of assistive technologies by removing redundant or extraneous content. Only when identical or equivalent meaning and functionality is exposed to assistive technologies can removing visible content from the accessibility API be considered. - -> [!NOTE] -> Consider all disabilities when hiding visibly rendered content from assistive technologies. Not all users of assistive technology are visually impaired. If visible content doesn't match text content in the accessibility API, the user experience will be negatively impacted for sighted users. - -On the surface, the `aria-hidden="true"` and the `role="presentation"` and its synonym `role="none"` seem similar, but the intent behind each is different. - -- `aria-hidden="true"` will remove the entire element from the accessibility API. -- `role="presentation"` and `role="none"` will remove the semantic meaning of an element while still exposing it and its content to assistive technology. - -`aria-hidden="true"` should not be added when: - -- The HTML [`hidden`](/en-US/docs/Web/HTML/Global_attributes/hidden) attribute is present -- The element or the element's ancestor is hidden with [`display: none`](/en-US/docs/Web/CSS/display) -- The element or the element's ancestor is hidden with [`visibility: hidden`](/en-US/docs/Web/CSS/visibility) - -In all three scenarios, the attribute is unnecessary to add because the element has already been removed from the accessibility tree. Visually hiding elements with `display` or `visibility` hides content from the screen and from assistive technologies. - -Using `aria-hidden="false"` will not re-expose the element to assistive technology if any of its parents specify `aria-hidden="true"`. - -## Example - -Adding `aria-hidden="true"` to the icon hides the icon character from being included in the accessible name. - -```html -<button> - <span class="fa fa-tweet" aria-hidden="true"></span> - <span class="label"> Tweet </span> -</button> -``` - -We have a button with [a Font Awesome icon](https://fontawesome.com/). We hide the icon from assistive technologies with `aria-hidden="true"`, as exposing the icon to assistive technologies could lead to redundancy or, if the icon doesn't have the same content as the visible text, confusion. - -## Values - -- `false` - - : The element is exposed to the accessibility API as if it was rendered. -- `true` - - : The element is hidden from the accessibility API. -- `undefined` (default) - - : The element's hidden state is determined by the user agent based on whether it is rendered. - -## Associated interfaces - -- {{domxref("Element.ariaHidden")}} - - : The [`ariaHidden`](/en-US/docs/Web/API/Element/ariaHidden) property, part of the {{domxref("Element")}} interface, reflects the value of the `aria-hidden` attribute, which Indicates whether the element is exposed to an accessibility API. -- {{domxref("ElementInternals.ariaHidden")}} - - : The [`ariaHidden`](/en-US/docs/Web/API/ElementInternals/ariaHidden) property, part of the {{domxref("ElementInternals")}} interface, reflects the value of the `aria-hidden` attribute - -## Associated roles - -Used in **ALL** roles - -## Specifications - -{{Specifications}} - -## See also - -- [`aria-disabled`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-disabled) -- [`aria-modal`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-modal) -- [`aria-expanded`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-expanded) -- HTML [`hidden`](/en-US/docs/Web/HTML/Global_attributes/hidden) attribute -- CSS {{CSSXref('display')}} property -- CSS {{CSSXref('visibility')}} property diff --git a/files/en-us/web/accessibility/aria/attributes/aria-invalid/index.md b/files/en-us/web/accessibility/aria/attributes/aria-invalid/index.md deleted file mode 100644 index fc8d4817328d31a..000000000000000 --- a/files/en-us/web/accessibility/aria/attributes/aria-invalid/index.md +++ /dev/null @@ -1,152 +0,0 @@ ---- -title: aria-invalid -slug: Web/Accessibility/ARIA/Attributes/aria-invalid -page-type: aria-attribute -spec-urls: https://w3c.github.io/aria/#aria-invalid ---- - -{{AccessibilitySidebar}} - -The `aria-invalid` state indicates the entered value does not conform to the format expected by the application. - -## Description - -The `aria-invalid` attribute is used to indicate that the value entered into an input field is not in a format or a value the application will accept. This may include formats such as email addresses or telephone numbers. `aria-invalid` can also be used to indicate that a required field is empty. - -The `aria-invalid` attribute can be used with any typical HTML form element, and is not limited to elements that have an ARIA role assigned. - -The attribute should be set with JavaScript as a result of a validation process. If a value is determined to be invalid or out-of-range, set `aria-invalid="true"` **and** tell the user there is an error. For better user experience, provide suggestions for how the error can be corrected. Do not set `aria-invalid="true"` on empty required elements until after the user attempts to submit the form. They may still be working on filling it out. - -> [!NOTE] -> When `aria-invalid` is used in conjunction with the `aria-required` attribute, `aria-invalid` should not be set to true before the form is submitted - only in response to validation. - -There are currently four values: in addition to `true` and `false` we have `grammar` which can be used when a grammatical error is detected and `spelling` for spelling errors. If the attribute is not present, or its value is false, or its value is an empty string, the default value of false applies. Any other value is treated as if `true` were set. - -### Native HTML validation - -HTML has native form validation. When a user submits a form with a control containing errors, the first form control with an invalid value displays an error message, natively. - -If there is a [`required`](/en-US/docs/Web/HTML/Attributes/required) attribute on a form control that isn't filled out, the form will not submit, and an error message appears reading "Please fill out this field" or something similar. The messaging for native validation varies depending on the browser, and cannot be styled. - -```html -<input type="number" step="2" min="0" max="100" required /> -``` - -If the user had entered a value in the preceding input example above the maximum, below the minimum, or that doesn't match the step value, an error message would appear. If the user had entered "3", the native error message would be similar to "Please enter a valid value." - -If you are creating your own form validation scripts, make sure to include `aria-invalid` on invalid form controls, along with styling (use the `[aria-invalid="true"]` attribute selector) and messaging (with [`aria-errormessage`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-errormessage)) to help users understand where the mistake is and how they can fix it. - -## Values - -- `grammar` - - : A grammatical error was detected. -- `false` (default) - - : There are no detected errors in the value. -- `spelling` - - : A spelling error was detected. -- `true` - - : The value entered by the user has failed validation. - -Any value not in this list will be treated as `true`. - -## Example - -The following snippet shows a simplified version of two form fields with a validation function attached to the blur event. Note that since the default value for `aria-invalid` is `false`, it is not strictly necessary to add the attribute to input. - -```html -<ul> - <li> - <label for="name">Full Name</label> - <input - type="text" - name="name" - id="name" - aria-required="true" - aria-invalid="false" - onblur="checkValidity('name', ' ', 'Invalid name entered (requires both first and last name)');" /> - </li> - <li> - <label for="email">Email Address</label> - <input - type="email" - name="email" - id="email" - aria-required="true" - aria-invalid="false" - onblur="checkValidity('email', '@', 'Invalid email address');" /> - </li> -</ul> -``` - -Note that it is not necessary to validate the fields immediately on blur; the application could wait until the form is submitted (though this is not necessarily recommended). - -The snippet below shows a very simple validation function, which only checks for the presence of a particular character (in the real world, validation will likely be more sophisticated): - -```js -function checkValidity(id, searchTerm, msg) { - const elem = document.getElementById(id); - if (elem.value.includes(searchTerm)) { - elem.setAttribute("aria-invalid", "false"); - updateAlert(); - } else { - elem.setAttribute("aria-invalid", "true"); - updateAlert(msg); - } -} -``` - -The snippet below shows the alert functions, which add (or remove) the error message: - -```js -function updateAlert(msg) { - const oldAlert = document.getElementById("alert"); - if (oldAlert) { - oldAlert.remove(); - } - - if (msg) { - const newAlert = document.createElement("div"); - newAlert.setAttribute("role", "alert"); - newAlert.setAttribute("id", "alert"); - const content = document.createTextNode(msg); - newAlert.appendChild(content); - document.body.appendChild(newAlert); - } -} -``` - -Note that the alert has the ARIA role attribute set to [`alert`](/en-US/docs/Web/Accessibility/ARIA/Roles/alert_role). - -## Associated roles - -Used in roles: - -- [`application`](/en-US/docs/Web/Accessibility/ARIA/Roles/application_role) -- [`checkbox`](/en-US/docs/Web/Accessibility/ARIA/Roles/checkbox_role) -- [`combobox`](/en-US/docs/Web/Accessibility/ARIA/Roles/combobox_role) -- [`gridcell`](/en-US/docs/Web/Accessibility/ARIA/Roles/gridcell_role) -- [`listbox`](/en-US/docs/Web/Accessibility/ARIA/Roles/listbox_role) -- [`radiogroup`](/en-US/docs/Web/Accessibility/ARIA/Roles/radiogroup_role) -- [`slider`](/en-US/docs/Web/Accessibility/ARIA/Roles/slider_role) -- [`spinbutton`](/en-US/docs/Web/Accessibility/ARIA/Roles/spinbutton_role) -- [`textbox`](/en-US/docs/Web/Accessibility/ARIA/Roles/textbox_role) -- [`tree`](/en-US/docs/Web/Accessibility/ARIA/Roles/tree_role) - -Inherited into role: - -- [`columnheader`](/en-US/docs/Web/Accessibility/ARIA/Roles/columnheader_role) -- [`rowheader`](/en-US/docs/Web/Accessibility/ARIA/Roles/rowheader_role) -- [`searchbox`](/en-US/docs/Web/Accessibility/ARIA/Roles/searchbox_role) -- [`switch`](/en-US/docs/Web/Accessibility/ARIA/Roles/switch_role) -- [`treegrid`](/en-US/docs/Web/Accessibility/ARIA/Roles/treegrid_role) - -## Specifications - -{{Specifications}} - -## See also - -- [`aria-errormessage`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-errormessage) -- CSS {{CSSXRef(':valid')}} pseudoclass -- CSS {{CSSXRef(':invalid')}} pseudoclass -- [Form Validation](/en-US/docs/Learn_web_development/Extensions/Forms/Form_validation) tutorial diff --git a/files/en-us/web/accessibility/aria/attributes/aria-keyshortcuts/index.md b/files/en-us/web/accessibility/aria/attributes/aria-keyshortcuts/index.md deleted file mode 100644 index 62b152d40d70ac0..000000000000000 --- a/files/en-us/web/accessibility/aria/attributes/aria-keyshortcuts/index.md +++ /dev/null @@ -1,137 +0,0 @@ ---- -title: aria-keyshortcuts -slug: Web/Accessibility/ARIA/Attributes/aria-keyshortcuts -page-type: aria-attribute -spec-urls: - - https://w3c.github.io/aria/#aria-keyshortcuts - - https://www.w3.org/WAI/ARIA/apg/practices/keyboard-interface/ ---- - -{{AccessibilitySidebar}} - -The global `aria-keyshortcuts` attribute indicates keyboard shortcuts that an author has implemented to activate or give focus to an element. - -## Description - -A keyboard shortcut is a series of one or several keys that tells software to perform a pre-programmed action. Keyboard shortcuts enable keyboard users to invoke commands using the keyboard that would otherwise require accessing a menu or using touch or a mouse. The `aria-keyshortcuts` property defines the keyboard keys that have been implemented to activate or give focus to the element on which the attribute is set. - -The `aria-keyshortcuts` attribute exposes the existence of the shortcut to assistive technologies so the presence of the shortcut can be communicated to its users. Like all ARIA attributes, it has no effect on the functionality of the page; the keyboard behavior must be added via JavaScript event handlers. - -Keyboard shortcuts applied to disabled elements should also be disabled. For example, when disabling an element for mouse users, remember to disable it for keyboard shortcut users. - -Ensure all keyboard shortcuts are both visible to sighted users and made available to assistive technology. If your application is complex enough to need keyboard shortcuts, also known as "hot keys", include a guided tour of your application, an accessibility page documenting shortcuts and other accessibility features, a shortcut cheat sheet page or dialog pop up, or other method of making the availability of keyboard short cuts known. In addition, show the shortcut in menus and tooltips. - -### Property value rules - -The value of the `aria-keyshortcuts` attribute is a space-separated list of key combinations that can be pressed to activate a command or textbox widget. Each key combination includes zero, one or more modifier keys followed by exactly one non-modifier key to be pressed at the same time joined with a plus sign ("+"). The attribute value is case-insensitive. - -Examples of valid keyboard shortcuts include: - -```plain -aria-keyshortcuts="A" -aria-keyshortcuts="Shift+Space" -aria-keyshortcuts="Control+Alt+." -aria-keyshortcuts="Control+Shift+&#39;" -aria-keyshortcuts="alt+shift+p control+f" -aria-keyshortcuts="Meta+C Meta+Shift+C" -``` - -Modifier keys are keys that don't have any impact when used on their own. They are written as "Alt", "Control", "Shift", "Meta" (Command key on Mac), or "AltGraph" (Option key on Mac). - -Non-modifier keys are keys that have impact when used alone, be that printing a character, moving focus, or otherwise creating a keyboard event when used. Non-modifiers that print a single character include characters like `P`, `z` and `.`. - -Since the plus sign is used in writing key combinations, it is written as `plus` if used as the non-modifier. Other written-out non-modifiers include white space characters `Space`, `Tab`, and `Enter`, and all characters that result in actions, like `ArrowUp`, `PageUp`, and `Escape`. - -If you want to use a character that might cause problems, like a double quote character within double quotes, escape the character: `Control+&#39;`. - -Modifier keys must be listed first in each key combination. Possible key combinations include `Control+P` or `Shift+Space` and `Q`. If the full shortcut requires all three of these combinations in order, it would be written as `aria-keyshortcuts="Control+P Shift+Space Q"`. When a key combination includes more than one modifier key, the order of the modifiers doesn't matter, but they all must come first, before the non-modifier. - -These two attribute declarations are equivalent. - -```plain example-good -aria-keyshortcuts="Shift+Control+V" -aria-keyshortcuts="control+shift+v" -``` - -Note that text case doesn't matter. But order of non-modifier does. - -These two attribute declarations are invalid because the non-modifier must be last. - -```plain example-bad -aria-keyshortcuts="V+Shift+Control" -aria-keyshortcuts="V+Control+Shift" -``` - -The key combination listed must be the keys the user needs to press, not the outcome of the combined key strokes. For example, on a USA keyboard, if you need the `@` symbol, the key combination is written as `"Shift+2"`, not `"@"` nor `"Shift+@"`. - -### Best practices - -In trying to improve the accessibility of your sites and applications, there are some best practices to follow to ensure your "enhancements" don't negatively impact user experience. Remember, no ARIA is better than bad ARIA. - -#### Don't override browser, assistive technology, or operating system shortcuts - -When implementing keyboard shortcuts, make sure you don't create shortcuts that are already being used by the browser, assistive technology, or operating system, unless they are used for the same thing. For example, `"Control+P"` is used by most user-agents to initiate print functionality. Generally a web application should not create a "Control+P" shortcut as it will usurp browser functionality. There are exceptions. Web applications where printing is common, like email applications or document editors, usurping the browser's `"Control+P"` printing functionality for an application specific print flow would be expected. - -Unless you're creating an HTML version of a productivity application, you should likely avoid implementing keyboard shortcut. While overriding an operating system or browser keyboard shortcut can be annoying for non-assistive technology users, if you override a screen reader's keyboard functionality you can completely shut down access for the assistive technology user. If you must create keyboard shortcuts, avoid single letter keyboard shortcuts and common screen reader keyboard shortcuts. - -#### Consider language and keyboard differences - -Take into account the diversity of available keyboards and the various keyboard language preferences. Modifier keys are often used to create language specific common punctuation symbols and number characters. For example, numbers, when the keyboard language preference is set to French (France), use the Shift key. - -#### Don't use HTML instead - -The `aria-keyshortcuts` attribute is very similar to the [problematic](https://webaim.org/techniques/keyboard/accesskey#spec) HTML [`accesskey`](/en-US/docs/Web/HTML/Global_attributes/accesskey), which generates a keyboard shortcut for the current element. When an `accesskey` is defined for an element, the browser defines the modifiers and does all the work of handling the shortcut with no scripting required. Every browser and operating system combination has their own modifier keys for the non-modifier set in the `accesskey` attribute. What may work for one combination of operating system, assistive technology, and browser may not work with other combinations. With `aria-keyshortcuts`, the modifier keys are included in the attribute value list of key combinations and the functionality has to be scripted in. - -```html -<p> - Press the - <strong><u>S</u></strong - >tress reliever to relax! -</p> -<button accesskey="s">Stress reliever</button> -``` - -In this example, we ensured the presence of the shortcut was known to sighted users a well by highlighting the non-modifier character. - -While the goal of the `accesskey` attribute matches the intention of `aria-keyshortcuts` and to do so natively, `accesskey` is rife with issues. Because of these issues, it is generally advised not to use access keys for most general-purpose websites and web apps. - -In addition to poor browser support, the same concerns arise for `accesskey` as exist for `aria-keyshortcuts`: - -- An accesskey value can conflict with a system or browser keyboard shortcut, or assistive technology functionality. -- Certain key values may not be present on certain keyboards, especially when internationalization is a concern. So adapting to specific languages could cause further problems. -- Values that rely on numbers may be confusing to individuals experiencing cognitive concerns, where the number doesn't have a logical association with the functionality it triggers. -- Informing the user that shortcuts are present, so that they are aware of the functionality. If the system lacks a method of notifying the user about this feature, the user might accidentally activate a shortcut. - -## Values - -- `<string>` - - : The space-separated list of key combinations that, when pressed, perform the action. - -## Example - -In this example, the `aria-keyshortcuts` attribute on the element is set to "Alt+Shift+A". - -```html -<a href="#content" aria-keyshortcuts="Alt+Shift+A">Skip to content</a> -``` - -## Associated interfaces - -- {{domxref("Element.ariaKeyShortcuts")}} - - : The [`ariaKeyShortcuts`](/en-US/docs/Web/API/Element/ariaKeyShortcuts) property, part of the {{domxref("Element")}} interface, reflects the value of the `aria-keyshortcuts` attribute. -- {{domxref("ElementInternals.ariaKeyShortcuts")}} - - : The [`ariaKeyShortcuts`](/en-US/docs/Web/API/ElementInternals/ariaKeyShortcuts) property, part of the {{domxref("ElementInternals")}} interface, reflects the value of the `aria-keyshortcuts` attribute. - -## Associated roles - -Used in **ALL** roles. - -## Specifications - -{{Specifications}} - -## See also - -- [Keyboard Shortcuts](https://www.w3.org/WAI/ARIA/apg/practices/keyboard-interface/#keyboardshortcuts) section in ARIA Authoring Practices -- HTML [`accesskey`](/en-US/docs/Web/HTML/Global_attributes/accesskey) attribute -- [Issues with `accesskey`](https://webaim.org/techniques/keyboard/accesskey#spec) diff --git a/files/en-us/web/accessibility/aria/attributes/aria-label/index.md b/files/en-us/web/accessibility/aria/attributes/aria-label/index.md deleted file mode 100644 index b343643dda36af1..000000000000000 --- a/files/en-us/web/accessibility/aria/attributes/aria-label/index.md +++ /dev/null @@ -1,106 +0,0 @@ ---- -title: aria-label -slug: Web/Accessibility/ARIA/Attributes/aria-label -page-type: aria-attribute -spec-urls: https://w3c.github.io/aria/#aria-label ---- - -{{AccessibilitySidebar}} - -The `aria-label` attribute defines a string value that can be used to name an element, as long as the element's role does not [prohibit naming](#associated_roles). - -## Description - -Sometimes, the default {{Glossary("accessible_name", "accessible name")}} of an element is missing or the accessible name does not accurately describe the contents of the element and there is no content visible in the DOM that can be associated with the object to give it meaning. A common example of such an element is a button containing an SVG icon without any text. - -In cases where an element that is not part of the [prohibited list](#associated_roles), has no accessible name or an accessible name is not accurate and there is no content visible in the DOM that can be referenced via the [`aria-labelledby`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-labelledby) attribute, the `aria-label` attribute can be used to define a string that labels the interactive element on which it is set. This provides the element an accessible name. - -The code below shows an example of how to use the `aria-label` attribute to provide an accessible name for a `<button>` element. The button in this example contains an SVG graphic and lacks textual content, making the `aria-label` essential for screen reader users to understand its function, which in this case is "Close". - -```html -<button aria-label="Close" onclick="myDialog.close()"> - <svg - aria-hidden="true" - focusable="false" - width="17" - height="17" - xmlns="http://www.w3.org/2000/svg"> - <path - d="m.967 14.217 5.8-5.906-5.765-5.89L3.094.26l5.783 5.888L14.66.26l2.092 2.162-5.766 5.889 5.801 5.906-2.092 2.162-5.818-5.924-5.818 5.924-2.092-2.162Z" - fill="#000" /> - </svg> -</button> -``` - -> **Note:** `aria-label` is intended for naming elements where the implicit or explicit role does not prohibit naming. It is strongly recommended to prioritize the use of `aria-labelledby` over `aria-label` if a visible label exists for the element to reference and receive its name from. - -Most content has an accessible name generated from its immediate wrapping element's text content. Accessible names can also be created by certain attributes or associated elements. - -By default, a button's accessible name is the content between the opening and closing {{HTMLElement('button')}} tags, an image's accessible name is the content of its [`alt`](/en-US/docs/Web/HTML/Element/img#alt) attribute, and a form input's accessible name is the content of the associated {{HTMLElement('label')}} element. - -If none of these options are available or if the default accessible name is not appropriate, use the `aria-label` attribute to define the accessible name of an element. - -> [!NOTE] -> While `aria-label` can be used on any element that can have an accessible name, in practice however, it is supported only on interactive elements, [widgets](/en-US/docs/Web/Accessibility/ARIA/Roles#2._widget_roles), [landmarks](/en-US/docs/Web/Accessibility/ARIA/Roles#3._landmark_roles), images, and iframes. - -When using `aria-label`, you also need to consider [`aria-labelledby`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-labelledby): - -- `aria-label` can be used in cases where text that could label the element is _not_ visible. If there is visible text that labels an element, use `aria-labelledby` instead. -- The purpose of `aria-label` is the same as `aria-labelledby`. Both provide an accessible name for an element. If there is no visible name for the element you can reference, use `aria-label` to provide the user with a recognizable accessible name. If label text is available in the DOM and it's possible to reference it for an acceptable user experience, prefer to use `aria-labelledby`. Don't use both on the same element because `aria-labelledby` will take precedence over `aria-label` if both are applied. - -Keep the following additional guidelines in mind when using `aria-label`: - -- The `aria-label` attribute can be used with regular, semantic HTML elements; it is not limited to elements that have an [ARIA `role`](/en-US/docs/Web/Accessibility/ARIA/Roles) assigned. -- Don't "overuse" `aria-label`. Remember that it's primarily for assistive technologies. To provide additional instructions or to clarify the UI, use visible text with `aria-describedby` or [`aria-description`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-description), not `aria-label`. Instructions should be accessible to all users, not just to those with screen readers (or preferably, make your UI more intuitive). - - > [!NOTE] - > Since `aria-label` content isn't displayed outside assistive technologies, consider making important information visible for all users. - -- Not all elements can be given an accessible name. Neither `aria-label` nor `aria-labelledby` should be used with inline structural roles such as with `code`, `term`, and `emphasis`, and roles not mapped to the accessibility API, including `none`. The `aria-label` attribute is intended for elements including links, videos, form controls, and those with [landmark roles](/en-US/docs/Web/Accessibility/ARIA/Roles#3._landmark_roles) or [widget roles](/en-US/docs/Web/Accessibility/ARIA/Roles#2._widget_roles); `aria-label` provides an accessible name when no visible label exists in the DOM. -- If you assign a `title` to an {{HTMLElement('iframe')}}, define an `alt` attribute for an {{HTMLElement('img')}}, or add {{HTMLElement('label')}} for an {{HTMLElement('input')}}, `aria-label` is not necessary. However, if an `aria-label` attribute is present, it will take precedence over the iframe's `title`, the image's `alt`, or the input's `<label>` text as the accessible name for that element. - -## Values - -- `<string>` - - : A string of text that will be the accessible name for the object. - -## Associated interfaces - -- {{domxref("Element.ariaLabel")}} - - : The [`ariaLabel`](/en-US/docs/Web/API/Element/ariaLabel) property, part of the {{domxref("Element")}} interface, reflects the value of the `aria-label` attribute. -- {{domxref("ElementInternals.ariaLabel")}} - - : The [`ariaLabel`](/en-US/docs/Web/API/ElementInternals/ariaLabel) property, part of the {{domxref("ElementInternals")}} interface, reflects the value of the `aria-label` attribute. - -## Associated roles - -Used in almost all roles **except** roles that cannot be provided an accessible name by the author. - -The `aria-label` attribute is **NOT** supported in: - -- [`code`](/en-US/docs/Web/Accessibility/ARIA/Roles/structural_roles) -- [`caption`](/en-US/docs/Web/Accessibility/ARIA/Roles/structural_roles) -- [`definition`](/en-US/docs/Web/Accessibility/ARIA/Roles/structural_roles) -- [`deletion`](/en-US/docs/Web/Accessibility/ARIA/Roles/structural_roles) -- [`emphasis`](/en-US/docs/Web/Accessibility/ARIA/Roles/structural_roles) -- [`generic`](/en-US/docs/Web/Accessibility/ARIA/Roles/generic_role) -- [`insertion`](/en-US/docs/Web/Accessibility/ARIA/Roles/structural_roles) -- [`mark`](/en-US/docs/Web/Accessibility/ARIA/Roles/mark_role) -- [`paragraph`](/en-US/docs/Web/Accessibility/ARIA/Roles/structural_roles) -- [`presentation`](/en-US/docs/Web/Accessibility/ARIA/Roles/presentation_role) / [`none`](/en-US/docs/Web/Accessibility/ARIA/Roles/none_role) -- [`strong`](/en-US/docs/Web/Accessibility/ARIA/Roles/structural_roles) -- [`subscript`](/en-US/docs/Web/Accessibility/ARIA/Roles/structural_roles) -- [`superscript`](/en-US/docs/Web/Accessibility/ARIA/Roles/structural_roles) -- [`suggestion`](/en-US/docs/Web/Accessibility/ARIA/Roles/suggestion_role) -- [`term`](/en-US/docs/Web/Accessibility/ARIA/Roles/term_role) -- [`time`](/en-US/docs/Web/Accessibility/ARIA/Roles/structural_roles) - -## Specifications - -{{Specifications}} - -## See also - -- {{HTMLElement('label')}} element -- [`aria-description`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-description) -- [`aria-labelledby`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-labelledby) -- [Using HTML landmark roles to improve accessibility](/en-US/blog/aria-accessibility-html-landmark-roles/) on MDN blog (2023) diff --git a/files/en-us/web/accessibility/aria/attributes/aria-labelledby/index.md b/files/en-us/web/accessibility/aria/attributes/aria-labelledby/index.md deleted file mode 100644 index 2ec5b6708d17d9b..000000000000000 --- a/files/en-us/web/accessibility/aria/attributes/aria-labelledby/index.md +++ /dev/null @@ -1,125 +0,0 @@ ---- -title: aria-labelledby -slug: Web/Accessibility/ARIA/Attributes/aria-labelledby -page-type: aria-attribute -spec-urls: https://w3c.github.io/aria/#aria-labelledby ---- - -{{AccessibilitySidebar}} - -The `aria-labelledby` attribute identifies the element (or elements) that labels the element it is applied to. - -## Description - -The `aria-labelledby` property enables authors to reference other elements on the page to define an accessible name. This is useful when using elements that don't have native support for associating elements to provide an accessible name. - -Some elements get their [accessible name](https://w3c.github.io/accname/#dfn-accessible-name) from their inner content. For example, the accessible name for a {{HTMLElement('button')}}, {{HTMLElement('a')}}, or {{HTMLElement('td')}} comes from the text between the opening and closing tags. Other elements, such as form {{HTMLElement('textarea')}}, {{HTMLElement('fieldset')}}, and {{HTMLElement('table')}} get their accessible name from the content of associated elements; for these elements, the accessible name comes from the {{HTMLElement('label')}} with a `for` attribute, {{HTMLElement('legend')}}, and {{HTMLElement('caption')}} respectively. - -All interactive elements must have an accessible name. `aria-labelledby` can be used to reference another element to define its accessible name, when an element's accessible name needs to use content from elsewhere in the DOM. - -If there is no content that can be referenced to create an accessible name, the [`aria-label`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-label) attribute should be used instead. - -The purpose of `aria-labelledby` is the same as that of `aria-label`. It provides the user with a recognizable, accessible name for an interactive element. If an element has both attributes set, `aria-labelledby` will be used. `aria-labelledby` takes precedence over all other methods of providing an accessible name, including `aria-label`, {{HTMLElement('label')}}, and the element's inner text. - -The `aria-labelledby` and [`aria-describedby`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-describedby) attributes both reference other elements to calculate text alternatives. `aria-labelledby` should reference brief text that provides the element with an accessible name. `aria-describedby` is used to reference longer content that provides a description. If there is no element in the DOM that provides a brief label appropriate for an accessible name for an interactive element, use `aria-label` to define the accessible name for an interactive element. - -> [!NOTE] -> While in American English, "labeled" is spelled with one "l", the "labelledby" spelling has been established and is the spelling used in accessibility APIs. - -The following example uses `aria-labelledby` to provide an accessible name for a checkbox input by using the text content of a sibling element: - -```html -<span - role="checkbox" - aria-checked="false" - tabindex="0" - aria-labelledby="tac"></span> -<span id="tac">I agree to the Terms and Conditions.</span> -``` - -Note that while using `aria-labelledby` is similar in this situation to using an HTML {{HTMLElement('label')}} element with the `for` attribute, there are some very important differences. The `aria-labelledby` attribute only defines the accessible name. It doesn't provide any of `<label>`'s other functionality, such as making clicking on the labeling element activate the input it is associated with. That has to be added back in with JavaScript. - -Fortunately, the HTML {{HTMLElement('input')}} with `type="checkbox"` works with native `<label>`. When feasible, use the following: - -```html -<label for="tac"> - <input id="tac" type="checkbox" name="terms-and-conditions" /> - I agree to the Terms and Conditions. -</label> -<p><a href="tac.html">Read our Terms and Conditions</a>.</p> -``` - -### Benefits (and drawbacks) - -1. The `aria-labelledby` property has the highest precedence when browsers calculate accessible names. Be aware that it overrides other methods of naming the element, including `aria-label`, other naming attributes, and even the element's contents. - - ```html - <button aria-label="Blue" aria-labelledby="color">Red</button> - <span id="color">Yellow</span> - ``` - - In this example, that accessible name is "Yellow". - -2. The `aria-labelledby` property takes as value a space-separated id reference list, which means you can combine more than one element into a single accessible name. You can include the [`id`](/en-US/docs/Web/HTML/Global_attributes/id) of the element itself to reference its own content. - - ```html - <h2 id="attr" class="article-title">13 ARIA attributes you need to know</h2> - <p> - There are over 50 ARIA states and properties, but 13 of them stand out… - <a href="13.html" id="rm13" aria-labelledby="rm13 attr">read more</a> - </p> - ``` - - In this example, the accessible name is "read more 13 ARIA attributes you need to know". - -3. The `aria-labelledby` property value order matters. When more than one element is referenced by `aria-labelledby`, the content from each referenced element is combined in the order that they are referenced in the `aria-labelledby` value. Had we written `aria-labelledby="attr rm13">`, the accessible name would have been "13 ARIA attributes you need to know read more". - -4. The `aria-labelledby` property ignores repeated `id`s in its value. If an element is referenced more than one time, only the first reference is processed. `aria-labelledby="attr attr rm13 rm13">` is treated as `aria-labelledby="attr rm13">` - -5. The `aria-labelledby` property value can include content from elements that aren't even visible. While you should provide assistive technology users with the same content as all other users, you can include content from elements with the HTML [`hidden`](/en-US/docs/Web/HTML/Global_attributes/hidden) attribute, CSS [`display: none`](/en-US/docs/Web/CSS/display), and CSS [`visibility: hidden`](/en-US/docs/Web/CSS/visibility) in the calculated name string. - -6. The `aria-labelledby` property incorporates the value of input elements. If the value references an `<input>`, the current value of the form control is included in the calculated name string, changing if the value is updated. - -7. The `aria-labelledby` property cannot be chained. If an element with `aria-labelledby` references another element that also has `aria-labelledby`, the `aria-labelledby` attribute on the referenced element is ignored. - -> [!WARNING] -> Because calculating the name of an element with `aria-labelledby` can be complex and reference hidden content, testing with assistive technologies to ensure the expected name is presented to users is very important. - -## Values - -- ID reference list - - : Space separated list of one or more ID values referencing the elements that label the current element. - -## Associated roles - -Used in almost all roles **except** roles that can not be provided an accessible name by the author. - -The `aria-labelledby` attribute is **NOT** supported in: - -- [`code`](/en-US/docs/Web/Accessibility/ARIA/Roles/structural_roles) -- [`caption`](/en-US/docs/Web/Accessibility/ARIA/Roles/structural_roles) -- [`deletion`](/en-US/docs/Web/Accessibility/ARIA/Roles/structural_roles) -- [`emphasis`](/en-US/docs/Web/Accessibility/ARIA/Roles/structural_roles) -- [`generic`](/en-US/docs/Web/Accessibility/ARIA/Roles/generic_role) -- [`insertion`](/en-US/docs/Web/Accessibility/ARIA/Roles/structural_roles) -- [`mark`](/en-US/docs/Web/Accessibility/ARIA/Roles/mark_role) -- [`paragraph`](/en-US/docs/Web/Accessibility/ARIA/Roles/structural_roles) -- [`presentation`](/en-US/docs/Web/Accessibility/ARIA/Roles/presentation_role) / [`none`](/en-US/docs/Web/Accessibility/ARIA/Roles/none_role) -- [`strong`](/en-US/docs/Web/Accessibility/ARIA/Roles/structural_roles) -- [`subscript`](/en-US/docs/Web/Accessibility/ARIA/Roles/structural_roles) -- [`superscript`](/en-US/docs/Web/Accessibility/ARIA/Roles/structural_roles) -- [`suggestion`](/en-US/docs/Web/Accessibility/ARIA/Roles/suggestion_role) -- [`term`](/en-US/docs/Web/Accessibility/ARIA/Roles/term_role) -- [`time`](/en-US/docs/Web/Accessibility/ARIA/Roles/structural_roles) - -## Specifications - -{{Specifications}} - -## See also - -- HTML {{HTMLElement('label')}} element -- HTML {{HTMLElement('legend')}} element -- HTML {{HTMLElement('caption')}} element -- [`aria-label`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-label) -- [`aria-describedby`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-describedby) diff --git a/files/en-us/web/accessibility/aria/attributes/aria-level/index.md b/files/en-us/web/accessibility/aria/attributes/aria-level/index.md deleted file mode 100644 index 4cb110f5d75ecbb..000000000000000 --- a/files/en-us/web/accessibility/aria/attributes/aria-level/index.md +++ /dev/null @@ -1,65 +0,0 @@ ---- -title: aria-level -slug: Web/Accessibility/ARIA/Attributes/aria-level -page-type: aria-attribute -spec-urls: https://w3c.github.io/aria/#aria-level ---- - -{{AccessibilitySidebar}} - -The `aria-level` attribute defines the hierarchical level of an element within a structure. - -## Description - -Levels of hierarchy appear in headings, trees, nested grid, nested tablists, and more. If the DOM ancestry does not accurately represent the level, the `aria-level` attribute should be used to define the hierarchical level elements within their hierarchical structures. Levels increase with depth. The value for aria-level is an integer greater than or equal to `1`. - -When it comes to the headings in a document structure, you can have first-level headings, second-level headings, third-level headings, etc. In trees, you have the root element, its children, the children's children (or grandchildren), and so on. - -The `aria-level` attribute exposes hierarchy to assistive technologies so it can be communicated to the users. Like all ARIA attributes, it has no impact on the user agent and therefore no impact on the user agent's determination of the document structure. - -If the DOM ancestry accurately represents the level, the user agent can calculate the level of an item from the document structure, making `aria-level` not only redundant but a risk of creating misinformation. `aria-level` should really only be used to provide an explicit indication of level when it is not possible to calculate from the document structure. Test to see if this attribute is needed. If the user agent can calculate the level, it is best to omit the `aria-level` attribute. - -### With `heading` role - -The `aria-level` attribute is a required attribute of the [`heading`](/en-US/docs/Web/Accessibility/ARIA/Roles/heading_role) role which indicates to assistive technologies that the element should be treated as a heading. `<div role="heading" aria-level="1">` defines the `<div>` as being the main heading of the page. A level 2 heading, defined with `aria-level="2"` would be the first subsection, a level 3 is a subsection of that, and so on. - -```html -<div role="heading" aria-level="3">Heading for this sub section</div> -``` - -Opt for using the {{htmlelement("Heading_Elements", "h1")}} through {{htmlelement("Heading_Elements", "h6")}} elements instead. - -### Within `treegrid` role - -In the case of a [`treegrid`](/en-US/docs/Web/Accessibility/ARIA/Roles/treegrid_role), `aria-level` is supported on elements with the role [`row`](/en-US/docs/Web/Accessibility/ARIA/Roles/row_role), not elements with role [`gridcell`](/en-US/docs/Web/Accessibility/ARIA/Roles/gridcell_role). Rows act as leaf nodes within the vertical orientation of the grid. Gridcells are leaf nodes within the horizontal orientation of each row. `Aria-level` is not supported on cells within rows. So, in treegrids, the `aria-level` attribute is applied to the element with the role `row`. - -If a complete set of available nodes is not present in the DOM due to dynamic loading as the user moves focus in or scrolls the tree, each node has `aria-level`, [`aria-setsize`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-setsize), and [`aria-posinset`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-posinset) included. - -## Values - -- `<integer>` - - : An integer greater than or equal to 1 - -## Associated interfaces - -- {{domxref("Element.ariaLevel")}} - - : The [`ariaLevel`](/en-US/docs/Web/API/Element/ariaLevel) property, part of the {{domxref("Element")}} interface, reflects the value of the `aria-level` attribute. -- {{domxref("ElementInternals.ariaLevel")}} - - : The [`ariaLevel`](/en-US/docs/Web/API/ElementInternals/ariaLevel) property, part of the {{domxref("ElementInternals")}} interface, reflects the value of the `aria-level` attribute. - -## Associated roles - -Used in roles: - -- [`associationlistitemkey`](/en-US/docs/Web/Accessibility/ARIA/Roles/structural_roles) -- [`comment`](/en-US/docs/Web/Accessibility/ARIA/Roles/comment_role) -- [`heading`](/en-US/docs/Web/Accessibility/ARIA/Roles/heading_role) -- [`row`](/en-US/docs/Web/Accessibility/ARIA/Roles/row_role) - -## Specifications - -{{Specifications}} - -## See also - -- [`<h1>` through `<h6>`: The HTML Section Heading elements](/en-US/docs/Web/HTML/Element/Heading_Elements) ({{htmlelement("Heading_Elements", "h1")}}, {{htmlelement("Heading_Elements", "h2")}}, {{htmlelement("Heading_Elements", "h3")}}, {{htmlelement("Heading_Elements", "h4")}}, {{htmlelement("Heading_Elements", "h5")}}, and {{htmlelement("Heading_Elements", "h6")}}) diff --git a/files/en-us/web/accessibility/aria/attributes/aria-live/index.md b/files/en-us/web/accessibility/aria/attributes/aria-live/index.md deleted file mode 100644 index f5e8bbfd9e26068..000000000000000 --- a/files/en-us/web/accessibility/aria/attributes/aria-live/index.md +++ /dev/null @@ -1,90 +0,0 @@ ---- -title: aria-live -slug: Web/Accessibility/ARIA/Attributes/aria-live -page-type: aria-attribute -spec-urls: https://w3c.github.io/aria/#aria-live ---- - -{{AccessibilitySidebar}} - -The global `aria-live` attribute indicates that an element will be updated, and describes the types of updates the user agents, assistive technologies, and user can expect from the live region. - -## Description - -When content changes after initial load, assistive technology (AT) users may not "see" the changes. Some changes are important. Others are not. The `aria-live` attribute enables developers to inform the user of updates and choose, based on importance and urgency, whether to immediately, proactively, or passively inform AT users of changes to the content. - -If a section of the screen updates, if it's styled in a way to be noticeable, most sighted users will generally notice live updates. Screen readers, on the other hand, only focus on one part of the page at a time; and that part may not be where the update is. The `aria-live` attribute provides a way for developers to announce such changes to AT based on event triggers set by the developer rather than by user initiated actions so they are made aware that the content has changed. - -```html -<div id="announce" aria-live="polite"></div> -``` - -The `aria-live` attribute is set on an **empty** element. When an update to the page occurs, the empty element with that `aria-live` attribute should be updated with a brief announcement informing the user an update has been made. - -```html -<div id="announce" aria-live="polite"> - <p>This message is announced.</p> -</div> -``` - -When the accessibility API recognizes a change to the live region above, it will announce the contents of that live region based on the value of the attribute. The element is **not** given focus. - -If you want all the contents of the live region to be read, use the [`aria-atomic`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-atomic). Use [`aria-relevant`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-relevant) to define only the sections of an update that need to be reread to the user. Use [`aria-busy`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-busy) to prevent announcements while updates are still being made. - -### Choosing the `aria-live` value - -As some assistive technology users can't "see" live updates, the `aria-live` attribute is used to define what updated information the user should be: - -- Made aware of immediately, -- Informed about if the opportunity avails itself, and -- Proactively informed about but can learn when they choose to focus on the updated area. - -`aria-live`'s value describes the types of updates the user agents, assistive technologies, and user can expect from the live region, and is used to express degrees of importance. - -When `aria-live`'s attribute is set to `polite`, assistive technologies will notify users of updates but generally do not interrupt the current task, with the updates having a low priority. When set to `assertive`, assistive technologies immediately notify the user, potentially clearing the speech queue of previous updates. - -Screen readers buffer content when the page is loaded. Because of this, content added after the initial accessibility tree is built may not be noticed as AT users start consuming content before dynamic widgets are populated—users may not know about the page or view content updating as widgets finish loading. In this situation you can let users know the page has been updated by setting `aria-live="polite"`. - -Fully populated pages may have updates too. Examples are content like real-time sports scores, news crawlers, and stock market tickers. Unless these kinds of updates are the main function of the page, you likely do not want to inform the user every time it updates, but do want to inform them the widget does get updated. Here, you would set `aria-live="off"`. In these scenarios there is no reason to inform the user of updates unless they are focused on the live region. - -Some live updates are important and time sensitive. For example, if you are selling concert tickets and the user has a limited time to make the purchase, you don't want to wait until a lull in activity to tell them their time is almost up (or already over). When being informed as soon as possible is necessary, set `aria-live="assertive"`. If the updated information is an [`alert`](/en-US/docs/Web/Accessibility/ARIA/Roles/alert_role), the `aria-live` attribute is not needed. - -In this time-limit scenario, to be accessible, you need to also [provide a way for users to extend the time available or turn the timer off completely](https://www.w3.org/WAI/WCAG21/Understanding/timing-adjustable.html). - -### Using `aria-live` - -A live region includes the element and all its descendants. When not set on updating content, `aria-live`'s value comes from the nearest ancestor with a valid `aria-live` attribute value set. When set to `off`, or when the attribute is omitted altogether on the updated element and all the ancestor nodes in the DOM tree, the user is not informed. Users will still be able to hear the updates if they navigate to the live region, however. - -> [!WARNING] -> Because an interruption may disorient users or cause them to not complete their current task, don't use the `assertive` value unless the interruption is imperative. - -## Values - -- `assertive` - - : Indicates that updates to the region have the highest priority and should be presented to the user immediately. -- `off` (default) - - : Indicates that updates to the region should **not** be presented to the user unless the user is currently focused on that region. -- `polite` - - : Indicates that updates to the region should be presented at the next graceful opportunity, such as at the end of speaking the current sentence or when the user pauses typing. - -## Associated interfaces - -- {{domxref("Element.ariaLive")}} - - : The [`ariaLive`](/en-US/docs/Web/API/Element/ariaLive) property, part of the {{domxref("Element")}} interface, reflects the value of the `aria-live` attribute. -- {{domxref("ElementInternals.ariaLive")}} - - : The [`ariaLive`](/en-US/docs/Web/API/ElementInternals/ariaLive) property, part of the {{domxref("ElementInternals")}} interface, reflects the value of the `aria-live` attribute. - -## Associated roles - -Used in **ALL** roles. - -## Specifications - -{{Specifications}} - -## See also - -- [`aria-atomic`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-atomic) -- [`aria-relevant`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-relevant) -- [`aria-busy`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-busy) -- [`alert` role](/en-US/docs/Web/Accessibility/ARIA/Roles/alert_role) diff --git a/files/en-us/web/accessibility/aria/attributes/aria-modal/index.md b/files/en-us/web/accessibility/aria/attributes/aria-modal/index.md deleted file mode 100644 index 128ae971086d6b5..000000000000000 --- a/files/en-us/web/accessibility/aria/attributes/aria-modal/index.md +++ /dev/null @@ -1,103 +0,0 @@ ---- -title: aria-modal -slug: Web/Accessibility/ARIA/Attributes/aria-modal -page-type: aria-attribute -spec-urls: https://w3c.github.io/aria/#aria-modal ---- - -{{AccessibilitySidebar}} - -The `aria-modal` attribute indicates whether an element is modal when displayed. - -## Description - -A section of content is "modal" means navigation is limited to the area itself and the background (the ancestors and siblings of the modal) is hidden. Setting `aria-modal="true"` on [`dialog`](/en-US/docs/Web/Accessibility/ARIA/Roles/dialog_role) and [`alertdialog` role](/en-US/docs/Web/Accessibility/ARIA/Roles/alertdialog_role) containers indicates the presence of a "modal" element to users of assistive technology, but does not actually make the element modal. The features that make the element actually modal must be implemented by the developer. - -> [!NOTE] -> ARIA only modifies the accessibility tree, modifying how assistive technology presents the content to your users. ARIA doesn't change anything about an element's function or behavior. To create a modal effect you must use JavaScript to manage behavior, focus, and ARIA states. - -Relevant only on `dialog` and `alertdialog` containers, setting `aria-modal="true"` tells assistive technologies to let the user know the ability to interact with, or access other content on the page requires the modal dialog to be closed or otherwise lose focus. - -Modal dialogs are when content is displayed and the user's interaction is limited to only that section until it is dismissed. - -When creating modal dialogs, `aria-modal="true"` tells assistive technologies that the windows underneath the current dialog are not part of the modal content. - -When a modal element is displayed, focus should be placed in the modal. Focus needs to be "trapped" inside the modal when it is visible, until it is dismissed. Assistive technology (<abbr>AT</abbr>) can then navigate the modal's content and understand the scope of the modal's content. The `aria-modal` attribute helps AT communicate the bounds of the modal and distinguishes it from the rest of the page's content. When dismissed, focus should return to the element that triggered the modal. - -Ensure the modal is controllable using only its descendant elements. If a modal dialog has a close button, the button should be a descendant contained with the modal container in the DOM. - -When a modal element is displayed, authors **should** mark all other contents as inert (such as "inert subtrees" in HTML). Disabled content is not inert content. Inert content cannot be interacted with using both normal and specialized browsing modes such as caret browsing, which allow an assistive technology user to explore a page in detail. This includes disabled content, whose content may provide meaning. - -The [`inert`](/en-US/docs/Web/HTML/Global_attributes/inert) attribute is a boolean attribute that indicates, by its presence, that the element and all its shadow-including descendants are to be made inert. Until [`HTMLElement.inert`](/en-US/docs/Web/API/HTMLElement/inert) is fully supported, content can be [made inert with JavaScript](https://samthor.au/2021/inert/). - -Including `aria-modal="true"` on a [`dialog`](/en-US/docs/Web/Accessibility/ARIA/Roles/dialog_role) or [`alertdialog`](/en-US/docs/Web/Accessibility/ARIA/Roles/alertdialog_role), removes the requirement of putting [`aria-hidden`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-hidden) on background content, as the `aria-modal` informs assistive technologies that content outside a dialog is inert. Note that while support for the {{HTMLElement("dialog")}} element is good, thoroughly testing your implementation is vitally important. - -If a dialog is not modal — there is no inert background and focus isn't confined to the dialog — either include `aria-modal="false"` or omit the attribute altogether. - -## Example - -```html -<div id="backdrop" class="no-scroll"> - <div - role="alertdialog" - aria-modal="true" - aria-labelledby="dialog_label" - aria-describedby="dialog_desc"> - <h2 id="dialog_label">Confirmation</h2> - <div id="dialog_desc"> - <p>Are you sure you want to delete this file?</p> - </div> - <button type="button" onclick="closeDialog(this)"> - No. Close this popup. - </button> - <button type="button" onclick="deleteFile(this)"> - Yes. Delete the file. - </button> - </div> -</div> -``` - -This partial example includes an `alertdialog` nested in a full-screen, non-scrollable backdrop. - -The [`role="alertdialog"`](/en-US/docs/Web/Accessibility/ARIA/Roles/alertdialog_role) identifies the element that serves as the alert dialog container. The [`aria-labelledby`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-labelledby) provides the alert dialog an accessible name by referring to the element that provides the alert dialog title. The [`aria-describedby`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-describedby) attribute gives the alert dialog an {{glossary("accessible description")}} by referring to the alert dialog content that describes the primary message or purpose of the alert dialog. - -The `aria-modal="true"` informs the assistive technology user that the content underneath the dialog is not interactive so long as the element with a declaration of `role="alertdialog"` has focus. - -The `aria-modal` attribute exposes the existence of the modal to assistive technologies so the disabling of the content behind the modal can be communicated to AT users. Like all ARIA attributes, `aria-modal` itself has no effect on the page's functionality; focus management and disabling, interactivity on background elements, and the ability to remove focus from the alertdialog must all be managed with JavaScript. - -## Values - -- `false` (default) - - : Element is not modal. -- `true` - - : Element is modal. - -## Associated interfaces - -- {{domxref("Element.ariaModal")}} - - : The [`ariaModal`](/en-US/docs/Web/API/Element/ariaModal) property, part of the {{domxref("Element")}} interface, reflects the value of the `aria-modal` attribute. -- {{domxref("ElementInternals.ariaModal")}} - - : The [`ariaModal`](/en-US/docs/Web/API/ElementInternals/ariaModal) property, part of the {{domxref("ElementInternals")}} interface, reflects the value of the `aria-modal` attribute. - -## Associated roles - -Used in roles: - -- [`window`](/en-US/docs/Web/Accessibility/ARIA/Roles/window_role) - -Inherits into roles: - -- [`alertdialog`](/en-US/docs/Web/Accessibility/ARIA/Roles/alertdialog_role) -- [`dialog`](/en-US/docs/Web/Accessibility/ARIA/Roles/dialog_role) - -## Specifications - -{{Specifications}} - -## See also - -- HTML {{HTMLElement("dialog")}} element -- [`alertdialog` role](/en-US/docs/Web/Accessibility/ARIA/Roles/alertdialog_role) -- [`dialog` role](/en-US/docs/Web/Accessibility/ARIA/Roles/dialog_role) -- HTML [`inert` global attribute](/en-US/docs/Web/HTML/Global_attributes/inert) -- HTMLElement API [`inert`](/en-US/docs/Web/API/HTMLElement/inert) property diff --git a/files/en-us/web/accessibility/aria/attributes/aria-multiline/index.md b/files/en-us/web/accessibility/aria/attributes/aria-multiline/index.md deleted file mode 100644 index 44f050e2ac5a559..000000000000000 --- a/files/en-us/web/accessibility/aria/attributes/aria-multiline/index.md +++ /dev/null @@ -1,58 +0,0 @@ ---- -title: aria-multiline -slug: Web/Accessibility/ARIA/Attributes/aria-multiline -page-type: aria-attribute -spec-urls: https://w3c.github.io/aria/#aria-multiline ---- - -{{AccessibilitySidebar}} - -The `aria-multiline` attribute indicates whether a `textbox` accepts multiple lines of input or only a single line. - -## Description - -The default behavior of the <kbd>Enter</kbd> or <kbd>Return</kbd> key differs between single-line and multi-line text fields. When user focus is in a single-line `{{htmlelement("input/text", '&lt;input type="text"&gt;')}}`, an <kbd>Enter</kbd> or <kbd>Return</kbd> keystroke usually submits the form. - -When user focus is in a multi-line {{HTMLElement('textarea')}}, the keystroke inserts a line break. Only relevant for elements with the [`textbox`](/en-US/docs/Web/Accessibility/ARIA/Roles/textbox_role) role set, the `aria-multiline` attribute indicates to assistive technologies whether that text box accepts multiple lines of input or only a single line, setting expectations as to what type of data to enter and what those keystroke will do. - -> [!NOTE] -> Where possible, use the HTML {{HTMLElement('input')}} or the {{HTMLElement('textarea')}}, as these have built in semantics and behaviors, do not require ARIA attributes or scripting, and have keyboard support built in. - -If the `aria-multiline="true"` is set, it means the textbox widget will accept line breaks within the input, similar to the HTML {{HTMLElement('textarea')}}. Elements with a role of `textbox` that do not have the attribute, or with the value set to `false`, are simple text box. - -Be aware of focus and keystrokes when designing text boxes. ARIA only modifies the accessibility tree and therefore how assistive technology presents the textbox to your users. ARIA doesn't change anything about an element's default function or behavior. When not using semantic HTML elements for their intended purpose and default functionality, you must use JavaScript to manage behavior and functionality, including responding to keystroke events. - -## Values - -- `true` - - - : The text box accepts multiple lines of input. - -- `false` - - : The text box only accepts a single line of input. - -## Associated interfaces - -- {{domxref("Element.ariaMultiLine")}} - - : The [`ariaMultiLine`](/en-US/docs/Web/API/Element/ariaMultiLine) property, part of the {{domxref("Element")}} interface, reflects the value of the `aria-multiline` attribute. -- {{domxref("ElementInternals.ariaMultiLine")}} - - : The [`ariaMultiLine`](/en-US/docs/Web/API/ElementInternals/ariaMultiLine) property, part of the {{domxref("ElementInternals")}} interface, reflects the value of the `aria-multiline` attribute. - -## Associated roles - -Used in roles: - -- [`textbox`](/en-US/docs/Web/Accessibility/ARIA/Roles/textbox_role) - -Inherits into roles: - -- [`searchbox`](/en-US/docs/Web/Accessibility/ARIA/Roles/searchbox_role) - -## Specifications - -{{Specifications}} - -## See also - -- ARIA [`textbox`](/en-US/docs/Web/Accessibility/ARIA/Roles/textbox_role) role -- ARIA [`searchbox`](/en-US/docs/Web/Accessibility/ARIA/Roles/searchbox_role) role diff --git a/files/en-us/web/accessibility/aria/attributes/aria-multiselectable/index.md b/files/en-us/web/accessibility/aria/attributes/aria-multiselectable/index.md deleted file mode 100644 index d4a83a28b296556..000000000000000 --- a/files/en-us/web/accessibility/aria/attributes/aria-multiselectable/index.md +++ /dev/null @@ -1,166 +0,0 @@ ---- -title: aria-multiselectable -slug: Web/Accessibility/ARIA/Attributes/aria-multiselectable -page-type: aria-attribute -spec-urls: https://w3c.github.io/aria/#aria-multiselectable ---- - -{{AccessibilitySidebar}} - -The `aria-multiselectable` attribute indicates that the user may select more than one item from the current selectable descendants. - -## Description - -The default behavior of selection lists, such as {{HTMLElement('select')}}, is to be able to choose only one item or option. By default or by convention, when a user is presented with list from which they must select an item, they assume they can only select a single item unless otherwise notified. The `aria-multiselectable` attribute is the way to inform assistive technology users that they may select more than one item from the current selectable items if they so choose. Lists and trees are examples of roles that might allow users to select more than one item at a time. - -> [!NOTE] -> When allowing for multiple selections, inform the user that multiple values are allowed and provide directions on how to provide multiple values, such as "to select more than one value, keep the control key pressed during selection." - -### Used with `aria-selected` - -When the user does select one or more items, remember to set the selected descendants as selected with [`aria-selected="true"`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-selected), and selectable descendants that are not selected have `aria-selected="false"` set. If an element is not selectable, omit the `aria-selected` attribute altogether as its presence informs the user the item is selectable. - -If a tree, grid, tab list, or list box supports selection of more than one node, the element with role [`grid`](/en-US/docs/Web/Accessibility/ARIA/Roles/grid_role), [`listbox`](/en-US/docs/Web/Accessibility/ARIA/Roles/listbox_role), [`tablist`](/en-US/docs/Web/Accessibility/ARIA/Roles/tablist_role), or [`tree`](/en-US/docs/Web/Accessibility/ARIA/Roles/tree_role) has `aria-multiselectable` set to `true`. Otherwise, `aria-multiselectable` is either set to `false` or the default value of false is implied. - -## Example - -```html -<p id="colorOptions">Choose the colors for your flag.</p> -<ul - tabindex="0" - role="listbox" - aria-labelledby="colorOptions" - aria-multiselectable="true"> - <li id="red" role="option" aria-selected="false">Red</li> - <li id="orange" role="option" aria-selected="false">Orange</li> - <li id="yellow" role="option" aria-selected="false">Yellow</li> - <li id="green" role="option" aria-selected="false">Green</li> - <li id="blue" role="option" aria-selected="false">Blue</li> - <li id="purple" role="option" aria-selected="false">Purple</li> - <li id="magenta" role="option" aria-selected="false">Hot pink</li> - <li id="lightpink" role="option" aria-selected="true">Light pink</li> - <li id="white" role="option" aria-selected="true">White</li> - <li id="lightblue" role="option" aria-selected="true">Light blue</li> - <li id="black" role="option" aria-selected="false">Black</li> - <li id="brown" role="option" aria-selected="false">Brown</li> -</ul> -``` - -This listbox supports multiple selection so we set the element with role `listbox` with `aria-multiselectable="true"`. All selected options have `aria-selected` set to `true`. All options that are not selected but are selectable have `aria-selected` set to false. Had we included options that were disabled or otherwise not selectable, we would have omitted the `aria-selected` attribute altogether. Including the attribute, even with no value or explicitly set to `false` indicates to assistive technology users that the item is selectable. - -The first rule of ARIA use is "if you can use a native feature with the semantics and behavior you require already built in, instead of repurposing an element and **adding** an ARIA role, state or property to make it accessible, then do so." Instead of creating an unordered list requiring [`tabindex`](/en-US/docs/Web/HTML/Global_attributes/tabindex), ARIA and JavaScript to turn text into selectable options, we could have used a native multiselect: the {{htmlelement('select')}} element has a Boolean [`multiple`](/en-US/docs/Web/HTML/Element/select#multiple) attribute. If included, the user can select multiple options. If not, only a single option can be selected. - -```html -<label for="flagcolors"> Choose the colors for your flag. </label> -<select multiple id="flagcolors"> - <option value="red">Red</option> - <option value="orange">Orange</option> - <option value="yellow">Yellow</option> - <option value="green">Green</option> - <option value="blue">Blue</option> - <option value="purple">Purple</option> - <option value="magenta">Hot pink</option> - <option value="lightpink" selected>Light pink</option> - <option value="white" selected>White</option> - <option value="lightblue" selected>Light blue</option> - <option value="black">Black</option> - <option value="brown">Brown</option> -</select> -``` - -This HTML `<select>` version is accessible and interactive, and needs no ARIA or JavaScript to function. - -If the above isn't stylable to your liking, you can also create a list of selectable options with HTML checkboxes, which is also semantic, focusable, and infinitely stylable with CSS: - -```html -<fieldset> - <legend>Choose the colors for your flag.</legend> - <ul> - <li> - <label><input type="checkbox" name="fc" value="red" />Red</label> - </li> - <li> - <label><input type="checkbox" name="fc" value="orange" />Orange</label> - </li> - <li> - <label><input type="checkbox" name="fc" value="yellow" />Yellow</label> - </li> - <li> - <label><input type="checkbox" name="fc" value="green" />Green</label> - </li> - <li> - <label><input type="checkbox" name="fc" value="blue" />Blue</label> - </li> - <li> - <label><input type="checkbox" name="fc" value="purple" />Purple</label> - </li> - <li> - <label><input type="checkbox" name="fc" value="magenta" />Hot pink</label> - </li> - <li> - <label - ><input type="checkbox" name="fc" value="lightpink" checked />Light - pink</label - > - </li> - <li> - <label - ><input type="checkbox" name="fc" value="white" checked />White</label - > - </li> - <li> - <label - ><input type="checkbox" name="fc" value="lightblue" checked />Light - blue</label - > - </li> - <li> - <label><input type="checkbox" name="fc" value="black" />Black</label> - </li> - <li> - <label><input type="checkbox" name="fc" value="brown" />Brown</label> - </li> - </ul> -</fieldset> -``` - -Instead of `aria-selected="true"`, include the [`checked`](/en-US/docs/Web/HTML/Element/input/checkbox#checked) attribute. The browser does the rest. - -## Values - -- `true` - - : More than one item in the widget may be selected at a time -- `false` - - : Only one item can be selected - -## Associated interfaces - -- {{domxref("Element.ariaMultiSelectable")}} - - : The [`ariaMultiSelectable`](/en-US/docs/Web/API/Element/ariaMultiSelectable) property, part of the {{domxref("Element")}} interface, reflects the value of the `aria-multiselectable` attribute. -- {{domxref("ElementInternals.ariaMultiSelectable")}} - - : The [`ariaMultiSelectable`](/en-US/docs/Web/API/ElementInternals/ariaMultiSelectable) property, part of the {{domxref("ElementInternals")}} interface, reflects the value of the `aria-multiselectable` attribute. - -## Associated roles - -Used in roles: - -- [`grid`](/en-US/docs/Web/Accessibility/ARIA/Roles/grid_role) -- [`listbox`](/en-US/docs/Web/Accessibility/ARIA/Roles/listbox_role) -- [`tablist`](/en-US/docs/Web/Accessibility/ARIA/Roles/tablist_role) -- [`tree`](/en-US/docs/Web/Accessibility/ARIA/Roles/tree_role) - -Inherited into roles: - -- [`treegrid`](/en-US/docs/Web/Accessibility/ARIA/Roles/treegrid_role) - -## Specifications - -{{Specifications}} - -## See also - -- HTML {{HTMLElement('select')}} element -- HTML {{HTMLElement('option')}} element -- HTML {{HTMLElement('input')}} element -- [multiple](/en-US/docs/Web/HTML/Attributes/multiple) attribute -- [`aria-selected`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-selected) diff --git a/files/en-us/web/accessibility/aria/attributes/aria-orientation/index.md b/files/en-us/web/accessibility/aria/attributes/aria-orientation/index.md deleted file mode 100644 index b63c3e023b7d858..000000000000000 --- a/files/en-us/web/accessibility/aria/attributes/aria-orientation/index.md +++ /dev/null @@ -1,82 +0,0 @@ ---- -title: aria-orientation -slug: Web/Accessibility/ARIA/Attributes/aria-orientation -page-type: aria-attribute -spec-urls: https://w3c.github.io/aria/#aria-orientation ---- - -{{AccessibilitySidebar}} - -The `aria-orientation` attribute indicates whether the element's orientation is horizontal, vertical, or unknown/ambiguous. - -## Description - -It may be important for the user to know the orientation to know how to navigate certain widgets, as orientation impacts the expected behaviors of the left, right, up and down arrows. The `aria-orientation` attribute is used to indicate to assistive technology users whether an element's orientation is `horizontal` or `vertical`, or `undefined`. - -Several widgets have default orientations: - -Horizontal by default: - -- [`slider`](/en-US/docs/Web/Accessibility/ARIA/Roles/slider_role), -- [`tablist`](/en-US/docs/Web/Accessibility/ARIA/Roles/tablist_role) -- [`toolbar`](/en-US/docs/Web/Accessibility/ARIA/Roles/toolbar_role) -- [`menubar`](/en-US/docs/Web/Accessibility/ARIA/Roles/menubar_role) - -Vertical by default: - -- [`scrollbar`](/en-US/docs/Web/Accessibility/ARIA/Roles/scrollbar_role) -- [`tree`](/en-US/docs/Web/Accessibility/ARIA/Roles/tree_role) -- [`listbox`](/en-US/docs/Web/Accessibility/ARIA/Roles/listbox_role) -- [`menu`](/en-US/docs/Web/Accessibility/ARIA/Roles/menu_role) - -Each [`separator`](/en-US/docs/Web/Accessibility/ARIA/Roles/separator_role) should have `aria-orientation` consistent with the separator's orientation. - -When nodes in a tree are arranged horizontally instead of its default vertical orientation, or when a tab list is vertical instead of its default horizontal, the down arrow performs as a right arrow normally would, and the up arrow performs as a left arrow normally would. In these instances, assistive technology users need to know the widget's orientation so as to navigate correctly. - -Up and down arrows are generally available for normal browser scrolling, even when focus is inside a tree or tab list. Include `aria-orientation` to enable alerting users when a widget doesn't have the default, expected orientation and associated navigation. - -Always remember that ARIA only modifies how assistive technology presents content to your users; altering the behavior of arrow keys requires JavaScript. - -## Values - -- `horizontal` - - : The element is oriented horizontally. -- `undefined` (default) - - : The element's orientation is unknown/ambiguous. -- `vertical` - - : The element is oriented vertically. - -## Associated interfaces - -- {{domxref("Element.ariaOrientation")}} - - : The [`ariaOrientation`](/en-US/docs/Web/API/Element/ariaOrientation) property, part of the {{domxref("Element")}} interface, reflects the value of the `aria-orientation` attribute. -- {{domxref("ElementInternals.ariaOrientation")}} - - : The [`ariaOrientation`](/en-US/docs/Web/API/ElementInternals/ariaOrientation) property, part of the {{domxref("ElementInternals")}} interface, reflects the value of the `aria-orientation` attribute. - -## Associated roles - -Used in roles: - -- [`scrollbar`](/en-US/docs/Web/Accessibility/ARIA/Roles/scrollbar_role) -- [`select`](/en-US/docs/Web/Accessibility/ARIA/Roles/select_role) -- [`separator`](/en-US/docs/Web/Accessibility/ARIA/Roles/separator_role) -- [`slider`](/en-US/docs/Web/Accessibility/ARIA/Roles/slider_role) -- [`tablist`](/en-US/docs/Web/Accessibility/ARIA/Roles/tablist_role) -- [`toolbar`](/en-US/docs/Web/Accessibility/ARIA/Roles/toolbar_role) - -Inherited into roles: - -- [`listbox`](/en-US/docs/Web/Accessibility/ARIA/Roles/listbox_role) -- [`menu`](/en-US/docs/Web/Accessibility/ARIA/Roles/menu_role) -- [`menubar`](/en-US/docs/Web/Accessibility/ARIA/Roles/menubar_role) -- [`radiogroup`](/en-US/docs/Web/Accessibility/ARIA/Roles/radiogroup_role) -- [`tree`](/en-US/docs/Web/Accessibility/ARIA/Roles/tree_role) -- [`treegrid`](/en-US/docs/Web/Accessibility/ARIA/Roles/treegrid_role) - -## Specifications - -{{Specifications}} - -## See also - -- [Understanding WCAG: Keyboard](/en-US/docs/Web/Accessibility/Understanding_WCAG/Keyboard) diff --git a/files/en-us/web/accessibility/aria/attributes/aria-owns/index.md b/files/en-us/web/accessibility/aria/attributes/aria-owns/index.md deleted file mode 100644 index 85460dfca498871..000000000000000 --- a/files/en-us/web/accessibility/aria/attributes/aria-owns/index.md +++ /dev/null @@ -1,68 +0,0 @@ ---- -title: aria-owns -slug: Web/Accessibility/ARIA/Attributes/aria-owns -page-type: aria-attribute -spec-urls: https://w3c.github.io/aria/#aria-owns ---- - -{{AccessibilitySidebar}} - -The `aria-owns` attribute identifies an element (or elements) in order to define a visual, functional, or contextual relationship between a parent and its child elements when the DOM hierarchy cannot be used to represent the relationship. - -## Description - -Every element is the parent, sibling, or child of another element. The document object, made up of HTML elements and text nodes, is the basis of the DOM tree. The Accessibility Object Model (<abbr>AOM</abbr>) relies on a well-built DOM to enable assistive technologies to relay meaningful information about a document's contents to users. - -There are circumstances where the layout that appears on screen may differ from the underlying DOM structure due to the ability of JavaScript to alter content and CSS to alter layout. When this is the case, the `aria-owns` attribute can be used to recreate a meaningful relationship for assistive technology that consumes the DOM. - -When elements appear to be related visually but are not associated in the DOM, the `aria-owns` attribute enables creating the relationship that appears on screen in the accessibility layer for use by assistive technology. The **only** reason to include `aria-owns` is to expose a parent/child contextual relationship to assistive technology when the DOM's construction can't provide that relationship. - -An "owning element" is any DOM ancestor of an element. If an element visually, functionally, or contextually appears to "own" (be an ancestor of) an element, but isn't actually an ancestor of the element in the DOM, include the `aria-owns` to create that relationship. Add the attribute to the owning element with reference to the non-child owned element (or elements) to tell assistive technology that an element should be treated as a child. - -Referencing the ID of one or more elements allows any element to "own" any other element with an `aria-owns` declaration. The value of the `aria-owns` attribute is a space-separated ID reference list that references the IDs of one or more elements in the document. - -> [!NOTE] -> An "owned" element is any DOM descendant of the element, any element specified as a child via `aria-owns`, or any DOM descendant of the owned child. The `aria-owns`-owned element should be an element that belongs to a separate parent tree in the DOM but should be treated as a child of the current element. - -Do not use `aria-owns` as a replacement for the DOM hierarchy. If the relationship is represented in the DOM, do not use `aria-owns`. - -A child element is owned by its DOM parent by default: in this case, `aria-owns` should not be used. Avoid using the `aria-owns` attribute to rearrange existing child elements into a different order. - -When using `aria-owns`, make sure you [manage focus order](https://css-tricks.com/focus-management-and-inert/). Ensure the visual focus order matches this assistive technology reading order. - -An example of when to use `aria-owns` includes pop-up sub-menus that visually appear positioned near a parent menu, but cannot be nested in the DOM within the parent menu because it would affect the visual presentation. In this case, use `aria-owns` to present the sub-menu as a child of the parent menu to a screen reader. - -> [!NOTE] -> The `aria-owns` attribute should only be used when the parent/child relationship cannot be determined from the DOM. - -If an element has both `aria-owns` and DOM children, the order of the child elements: - -1. The actual DOM children first, -2. Then the elements referenced in `aria-owns`. - -This order can be changed by including the ID references to the actual DOM children in the `aria-owns` value. - -The {{CSSXRef('order')}} property, part of flex or grid layouts, can be used to change the order of flex and grid items making them appear in a different order from their order in the source document, creating a divergence of the logical order of elements. While it may be tempting to order the accessibility layer to match order changes created with the CSS {{CSSXref('order')}} property, avoiding both the `order` property and the `aria-owns` attribute is the best option. - -Make sure your owned elements have only one owner. Do not specify the `id` of an element in more than one other element's `aria-owns` attribute. An element can have only one owner. - -> [!WARNING] -> While [`aria-owns` is now supported](https://a11ysupport.io/tech/aria/aria-owns_attribute) in all modern browsers, `aria-owns` may not be exposed to users of macOS and iOS using VoiceOver prior to iOS 17.3 and macOS 14.3. - -## Values - -- `id` list - - : Space separated list of one or more ID values referencing the elements being owned by the current element - -## Associated roles - -Used in **ALL** roles. - -## Specifications - -{{Specifications}} - -## See also - -- [`aria-controls`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-controls) -- [`aria-owns` browser support](https://a11ysupport.io/tech/aria/aria-owns_attribute) diff --git a/files/en-us/web/accessibility/aria/attributes/aria-placeholder/index.md b/files/en-us/web/accessibility/aria/attributes/aria-placeholder/index.md deleted file mode 100644 index 1a4b3dad856d5f9..000000000000000 --- a/files/en-us/web/accessibility/aria/attributes/aria-placeholder/index.md +++ /dev/null @@ -1,72 +0,0 @@ ---- -title: aria-placeholder -slug: Web/Accessibility/ARIA/Attributes/aria-placeholder -page-type: aria-attribute -spec-urls: https://w3c.github.io/aria/#aria-placeholder ---- - -{{AccessibilitySidebar}} - -The `aria-placeholder` attribute defines a short hint (a word or short phrase) intended to help the user with data entry when a form control has no value. The hint can be a sample value or a brief description of the expected format. - -## Description - -A placeholder is text that appears in the form control when it has no value set. The HTML [`placeholder`](/en-US/docs/Web/HTML/Element/input#placeholder) attribute enables providing a sample value or a brief description of the expected format for several HTML {{HTMLElement('input')}} types and {{HTMLElement('textarea')}}. - -If you are creating a `textbox` using any other element, `placeholder` is not supported. That is where `aria-placeholder` comes into play. The `aria-placeholder` attribute can be used to defines a short hint to help the user understand what type of data is expected when a non-semantic form control has no value. - -```html -<span id="date-of-birth">Birthday</span> -<div - contenteditable - role="textbox" - aria-labelledby="date-of-birth" - aria-placeholder="MM-DD-YYYY"> - MM-DD-YYYY -</div> -``` - -The placeholder hint should be shown to the user whenever the control's value is empty, including when a value is deleted. - -> [!NOTE] -> ARIA is only modify the accessibility tree for an element and therefore how assistive technology presents the content to your users. ARIA doesn't change anything about an elements function or behavior. When not using semantic HTML elements for their intended purpose and default functionality, you must use JavaScript to manage behavior. - -The `aria-placeholder` is used in addition to, not instead of, a label. They have different purposes and different functionality. A label explains what kind of information is expected. Placeholder text provides a hint about the expected value. - -> [!WARNING] -> Using a placeholder instead of a visible label harms accessibility and usability for many users including older users and users with cognitive, mobility, fine motor skill and vision impairments. Labels are better: they are always visible and they provide for a larger hit region to focus on the control. Placeholders have several drawbacks: they disappear when the control has any value including just white space, they can confuse users into thinking the value is pre-filled, and the default color has insufficient contrast. - -> [!NOTE] -> Placeholders should only be used to show an example of the type of data that should be entered into a form; they don't replace a proper label. - -## Values - -- `<string>` - - : The word or short phrase to display in a control when the control has no value. - -## Associated interfaces - -- {{domxref("Element.ariaPlaceholder")}} - - : The [`ariaPlaceholder`](/en-US/docs/Web/API/Element/ariaPlaceholder) property, part of the {{domxref("Element")}} interface, reflects the value of the `aria-placeholder` attribute. -- {{domxref("ElementInternals.ariaPlaceholder")}} - - : The [`ariaPlaceholder`](/en-US/docs/Web/API/ElementInternals/ariaPlaceholder) property, part of the {{domxref("ElementInternals")}} interface, reflects the value of the `aria-placeholder` attribute. - -## Associated roles - -Used in roles: - -- [`textbox`](/en-US/docs/Web/Accessibility/ARIA/Roles/textbox_role) - -Inherited into roles: - -- [`searchbox`](/en-US/docs/Web/Accessibility/ARIA/Roles/searchbox_role) - -## Specifications - -{{Specifications}} - -## See also - -- [HTML `placeholder` attribute](/en-US/docs/Web/HTML/Element/input#placeholder) -- [`aria-labelledby`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-labelledby) -- [`aria-label`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-label) diff --git a/files/en-us/web/accessibility/aria/attributes/aria-posinset/index.md b/files/en-us/web/accessibility/aria/attributes/aria-posinset/index.md deleted file mode 100644 index 0165b9347187ebb..000000000000000 --- a/files/en-us/web/accessibility/aria/attributes/aria-posinset/index.md +++ /dev/null @@ -1,79 +0,0 @@ ---- -title: aria-posinset -slug: Web/Accessibility/ARIA/Attributes/aria-posinset -page-type: aria-attribute -spec-urls: https://w3c.github.io/aria/#aria-posinset ---- - -{{AccessibilitySidebar}} - -The `aria-posinset` attribute defines an element's number or position in the current set of listitems or treeitems when not all items are present in the DOM. - -## Description - -Short for "position in set", the `aria-posinset` attribute defines the position of the element within the whole set of listitems or treeitems when only a subset of the items are present in the DOM. - -If all the items in a list are present in the DOM, the browser can calculate the total and the position of each, making `aria-posinset` unnecessary. When only a portion of a set is in the DOM, include `aria-posinset` to provide information about the element's position within the set along with [`aria-setsize`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-setsize) to inform the user how many items are in the full set. - -The following example shows a listbox with four element options out of the 118 in the periodic table of chemical elements. - -```html -<h2 id="periodic-table">Periodic table of chemical elements</h2> -<ul role="listbox" aria-labelledby="periodic-table"> - <li role="option" aria-setsize="118" aria-posinset="1">Hydrogen</li> - <li role="option" aria-setsize="118" aria-posinset="3">Lithium</li> - <li role="option" aria-setsize="118" aria-posinset="11">Sodium</li> - <li role="option" aria-setsize="118" aria-posinset="19">Potassium</li> -</ul> -``` - -The value of each `aria-posinset` is an integer greater than or equal to `1`, and less than or equal to the size of the set when that size is known. - -> [!NOTE] -> When using `aria-posinset` you must also include value for [`aria-setsize`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-setsize), which is the size of the entire set. If the size of the entire set is unknown, set `aria-setsize="-1"`. - -For [`menuitem`](/en-US/docs/Web/Accessibility/ARIA/Roles/menuitem_role), [`menuitemcheckbox`](/en-US/docs/Web/Accessibility/ARIA/Roles/menuitemcheckbox_role), or [`menuitemradio`](/en-US/docs/Web/Accessibility/ARIA/Roles/menuitemradio_role), set the value of `aria-posinset` with respect to the total number of items in the menu, excluding any separators. - -In a [`feed`](/en-US/docs/Web/Accessibility/ARIA/Roles/feed_role), each {{HTMLElement('article')}} element has `aria-posinset` set to a value that represents its position in the feed along with the `aria-setsize` set to either the number of articles that have been loaded or the total number in the feed, depending on which value is most helpful to users. - -## Values - -- `<integer>` - - : Integer greater than or equal to 1, and less than or equal to the value of `aria-setsize`. - -## Associated interfaces - -- {{domxref("Element.ariaPosInSet")}} - - : The [`ariaPosInSet`](/en-US/docs/Web/API/Element/ariaPosInSet) property, part of the {{domxref("Element")}} interface, reflects the value of the `aria-posinset` attribute. -- {{domxref("ElementInternals.ariaPosInSet")}} - - : The [`ariaPosInSet`](/en-US/docs/Web/API/ElementInternals/ariaPosInSet) property, part of the {{domxref("ElementInternals")}} interface, reflects the value of the `aria-posinset` attribute. - -## Associated roles - -Used in roles: - -- [`article`](/en-US/docs/Web/Accessibility/ARIA/Roles/article_role) -- [`associationlistitemkey`](/en-US/docs/Web/Accessibility/ARIA/Roles/structural_roles) -- [`associationlistitemvalue`](/en-US/docs/Web/Accessibility/ARIA/Roles/structural_roles) -- [`comment`](/en-US/docs/Web/Accessibility/ARIA/Roles/comment_role) -- [`listitem`](/en-US/docs/Web/Accessibility/ARIA/Roles/listitem_role) -- [`menuitem`](/en-US/docs/Web/Accessibility/ARIA/Roles/menuitem_role) -- [`option`](/en-US/docs/Web/Accessibility/ARIA/Roles/option_role) -- [`radio`](/en-US/docs/Web/Accessibility/ARIA/Roles/radio_role) -- [`row`](/en-US/docs/Web/Accessibility/ARIA/Roles/row_role) -- [`tab`](/en-US/docs/Web/Accessibility/ARIA/Roles/tab_role) - -Inherits into roles: - -- [`comment`](/en-US/docs/Web/Accessibility/ARIA/Roles/comment_role) -- [`menuitemcheckbox`](/en-US/docs/Web/Accessibility/ARIA/Roles/menuitemcheckbox_role) -- [`menuitemradio`](/en-US/docs/Web/Accessibility/ARIA/Roles/menuitemradio_role) -- [`treeitem`](/en-US/docs/Web/Accessibility/ARIA/Roles/treeitem_role) - -## Specifications - -{{Specifications}} - -## See also - -- [`aria-setsize`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-setsize) diff --git a/files/en-us/web/accessibility/aria/attributes/aria-pressed/index.md b/files/en-us/web/accessibility/aria/attributes/aria-pressed/index.md deleted file mode 100644 index 8cc9bc883173ae6..000000000000000 --- a/files/en-us/web/accessibility/aria/attributes/aria-pressed/index.md +++ /dev/null @@ -1,66 +0,0 @@ ---- -title: aria-pressed -slug: Web/Accessibility/ARIA/Attributes/aria-pressed -page-type: aria-attribute -spec-urls: https://w3c.github.io/aria/#aria-pressed ---- - -{{AccessibilitySidebar}} - -The `aria-pressed` attribute indicates the current "pressed" state of a toggle button. - -## Description - -Adding `aria-pressed` to an element with a role of [`button`](/en-US/docs/Web/Accessibility/ARIA/Roles/button_role) turns the button into a toggle button. The `aria-pressed` attribute is only relevant for toggle buttons. It represents the button's current "pressed" state. - -The value is "tri-state", meaning the value can be set to `true`, `false`, `mixed`, or `undefined` values. In the case of `aria-pressed`, like most tri-state value types, the default value is `undefined`. - -Toggle buttons require a full press-and-release cycle to change their value. Pressing and releasing it once changes the value to `true`. If it's pressed and released again, the value changes back to `false`. - -A value of `mixed` means that the values of more than one item controlled by the button do not all share the same value. - -Do not change the contents of the label on a toggle when the state changes. If a button label says "pause", do not change it to "play" when pressed. In this example, when the pressed state is true, the label remains "Pause" so a screen reader would say something like "Pause toggle button pressed". - -```html -<button aria-pressed="false">Pause</button> -``` - -If you want the label to toggle between "Paused" and "Play", don't use `aria-pressed`. - -The first rule of ARIA use is "if you can use a native feature with the semantics and behavior you require already built in, instead of repurposing an element and adding an ARIA role, state or property to make it accessible, then do so." If we employ native HTML semantics with {{HTMLElement('button')}}, we can toggle the label instead of toggling the pressed state, removing the need for the `aria-pressed` attribute. - -## Values - -- `false` - - : The button supports being pressed but is not currently pressed. -- `mixed` - - : Indicates a mixed mode value for a tri-state toggle button. -- `true` - - : The button is pressed. -- `undefined` (default) - - : The element does not support being pressed. - -## Associated interfaces - -- {{domxref("Element.ariaPressed")}} - - : The [`ariaPressed`](/en-US/docs/Web/API/Element/ariaPressed) property, part of the {{domxref("Element")}} interface, reflects the value of the `aria-pressed` attribute. -- {{domxref("ElementInternals.ariaPressed")}} - - : The [`ariaPressed`](/en-US/docs/Web/API/ElementInternals/ariaPressed) property, part of the {{domxref("ElementInternals")}} interface, reflects the value of the `aria-pressed` attribute. - -## Associated roles - -Used in roles: - -- [`button`](/en-US/docs/Web/Accessibility/ARIA/Roles/button_role) - -## Specifications - -{{Specifications}} - -## See also - -- [`<input type="button">`](/en-US/docs/Web/HTML/Element/input/button) -- [`<input type="submit">`](/en-US/docs/Web/HTML/Element/input/submit) -- {{HTMLElement('button')}} -- [`aria-checked`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-checked) -- [`aria-selected`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-selected) diff --git a/files/en-us/web/accessibility/aria/attributes/aria-readonly/index.md b/files/en-us/web/accessibility/aria/attributes/aria-readonly/index.md deleted file mode 100644 index 2233b4478982375..000000000000000 --- a/files/en-us/web/accessibility/aria/attributes/aria-readonly/index.md +++ /dev/null @@ -1,75 +0,0 @@ ---- -title: aria-readonly -slug: Web/Accessibility/ARIA/Attributes/aria-readonly -page-type: aria-attribute -spec-urls: https://w3c.github.io/aria/#aria-readonly ---- - -{{AccessibilitySidebar}} - -The `aria-readonly` attribute indicates that the element is not editable, but is otherwise operable. - -## Description - -When you want to indicate that an interactive element works but is not editable, set `aria-readonly="true"`. This indicates to the user that an interactive element that would normally be focusable and copyable has been placed in a read-only (not disabled) state. - -When `aria-readonly` is set to `true`, it means the user can read but not set the value of the widget. Read-only elements are still relevant to the user, so you should not prevent the user from navigating to the element or its focusable descendants or copying the value. - -Examples include: - -- Form elements which should not be changed. -- Row and column headers in a spreadsheet. -- The total value in a shopping cart. - -If the non-changeable value shouldn't be able to receive focus, use [`aria-disabled`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-disabled) instead. - -> [!NOTE] -> When using semantic HTML form controls, if you set the `readonly` attribute, you don't need to include `aria-readonly="true"`. - -> [!NOTE] -> The value of `<input type="checkbox">` can not be edited making `readonly` not relevant. However, when creating checkboxes with `role="checkbox"` the `aria-readonly` attribute _is_ supported. - -## Values - -- `true` - - : The element is readonly. -- `false` (default) - - : The element is not readonly. - -## Associated interfaces - -- {{domxref("Element.ariaReadOnly")}} - - : The [`ariaReadOnly`](/en-US/docs/Web/API/Element/ariaReadOnly) property, part of the {{domxref("Element")}} interface, reflects the value of the `aria-readonly` attribute. -- {{domxref("ElementInternals.ariaReadOnly")}} - - : The [`ariaReadOnly`](/en-US/docs/Web/API/ElementInternals/ariaReadOnly) property, part of the {{domxref("ElementInternals")}} interface, reflects the value of the `aria-readonly` attribute. - -## Associated roles - -Used in roles: - -- [`checkbox`](/en-US/docs/Web/Accessibility/ARIA/Roles/checkbox_role) -- [`combobox`](/en-US/docs/Web/Accessibility/ARIA/Roles/combobox_role) -- [`grid`](/en-US/docs/Web/Accessibility/ARIA/Roles/grid_role) -- [`gridcell`](/en-US/docs/Web/Accessibility/ARIA/Roles/gridcell_role) -- [`listbox`](/en-US/docs/Web/Accessibility/ARIA/Roles/listbox_role) -- [`radiogroup`](/en-US/docs/Web/Accessibility/ARIA/Roles/radiogroup_role) -- [`slider`](/en-US/docs/Web/Accessibility/ARIA/Roles/slider_role) -- [`spinbutton`](/en-US/docs/Web/Accessibility/ARIA/Roles/spinbutton_role) -- [`textbox`](/en-US/docs/Web/Accessibility/ARIA/Roles/textbox_role) - -Inherited into roles: - -- [`columnheader`](/en-US/docs/Web/Accessibility/ARIA/Roles/columnheader_role) -- [`rowheader`](/en-US/docs/Web/Accessibility/ARIA/Roles/rowheader_role) -- [`searchbox`](/en-US/docs/Web/Accessibility/ARIA/Roles/searchbox_role) -- [`switch`](/en-US/docs/Web/Accessibility/ARIA/Roles/switch_role) -- [`treegrid`](/en-US/docs/Web/Accessibility/ARIA/Roles/treegrid_role) - -## Specifications - -{{Specifications}} - -## See also - -- [HTML `readonly` attribute](/en-US/docs/Web/HTML/Attributes/readonly) -- [`aria-disabled`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-disabled) diff --git a/files/en-us/web/accessibility/aria/attributes/aria-relevant/index.md b/files/en-us/web/accessibility/aria/attributes/aria-relevant/index.md deleted file mode 100644 index e8a2b09b04670bf..000000000000000 --- a/files/en-us/web/accessibility/aria/attributes/aria-relevant/index.md +++ /dev/null @@ -1,57 +0,0 @@ ---- -title: aria-relevant -slug: Web/Accessibility/ARIA/Attributes/aria-relevant -page-type: aria-attribute -spec-urls: https://w3c.github.io/aria/#aria-relevant ---- - -{{AccessibilitySidebar}} - -Used in ARIA live regions, the global `aria-relevant` attribute indicates what notifications the user agent will trigger when the [accessibility tree](/en-US/docs/Glossary/Accessibility_tree) within a live region is modified. - -## Description - -[ARIA live regions](/en-US/docs/Web/Accessibility/ARIA/ARIA_Live_Regions) are areas of a web page that are updated when user's attention may be elsewhere. When an update is outside of the user's keyboard focus, assistive technologies such as screen readers use a live region area to report updates to the user. - -Examples of live regions include news marquees, stock tickers, chat windows, and score boards. These update without user interaction. Some updates are important for the user to know about. They're relevant. Others are not. The `aria-relevant` is used to describe what types of changes have occurred to an [`aria-live`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-live) region, and which are relevant and should be announced. - -The value is a space-separated list of change types, including `additions`, `removals`, and `text`, with a shorthand `all` meaning all three. - -When `aria-relevant` is not defined, the value is inherited from the nearest ancestor with a defined value. Inherited values are not additive; the value provided on a descendant element completely overrides any inherited value from an ancestor element. When a live region doesn't have an `aria-relevant` attribute set and has no ancestor with it set, it defaults to `additions text`, which means element nodes are added to the accessibility tree within the live region, AND text content or a text alternative is added to any descendant in the accessibility tree of the live region. This is because generally text modifications and node additions are relevant, but node removals are not. - -While not a supported value, if the value of `none` makes the most sense, it should not be a live region. - -The values of `removals` and `all` should be used sparingly. For example, when a goal happens in the World Cup, the new score (the addition) is important, the old value (the removal) is not. Assistive technologies only need to be informed of content removal when its removal represents an important change, such as a when a player is taken out of the game. - -## Values - -- `additions` - - : Element nodes are added to the accessibility tree within the live region. -- `all` - - : Shorthand for `additions removals text`. -- `removals` - - : Text content, a text alternative, or an element node within the live region is removed from the accessibility tree. -- `text` - - : Text content or a text alternative is added to any descendant in the accessibility tree of the live region. - -## Associated interfaces - -- {{domxref("Element.ariaRelevant")}} - - : The [`ariaRelevant`](/en-US/docs/Web/API/Element/ariaRelevant) property, part of the {{domxref("Element")}} interface, reflects the value of the `aria-relevant` attribute. -- {{domxref("ElementInternals.ariaRelevant")}} - - : The [`ariaRelevant`](/en-US/docs/Web/API/ElementInternals/ariaRelevant) property, part of the {{domxref("ElementInternals")}} interface, reflects the value of the `aria-relevant` attribute. - -## Associated roles - -Used in **ALL** roles. - -## Specifications - -{{Specifications}} - -## See also - -- [`aria-atomic`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-atomic) -- [`aria-live`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-live) -- [`aria-busy`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-busy) -- [ARIA live regions](/en-US/docs/Web/Accessibility/ARIA/ARIA_Live_Regions) diff --git a/files/en-us/web/accessibility/aria/attributes/aria-required/index.md b/files/en-us/web/accessibility/aria/attributes/aria-required/index.md deleted file mode 100644 index 80b133076c7da18..000000000000000 --- a/files/en-us/web/accessibility/aria/attributes/aria-required/index.md +++ /dev/null @@ -1,102 +0,0 @@ ---- -title: aria-required -slug: Web/Accessibility/ARIA/Attributes/aria-required -page-type: aria-attribute -spec-urls: https://w3c.github.io/aria/#aria-required ---- - -{{AccessibilitySidebar}} - -The `aria-required` attribute indicates that user input is required on the element before a form may be submitted. - -## Description - -When a semantic HTML {{htmlelement("input")}}, {{htmlelement("select")}}, or {{htmlelement("textarea")}} must have a value, it should have the [`required`](/en-US/docs/Web/HTML/Element/input#required) attribute applied to it. The HTML `required` attribute disables submitting the form unless the required form controls have valid values, while ensuring those navigating with the aid of assistive technologies understand which semantic form controls need valid content. - -When form controls are created using non-semantic elements, such as a {{HTMLElement('div')}} with a [role](/en-US/docs/Web/Accessibility/ARIA/Roles) of [`checkbox`](/en-US/docs/Web/Accessibility/ARIA/Roles/checkbox_role), the `aria-required` attribute should be included, with a value of `true`, to indicate to assistive technologies that user input is required on the element for the form to be submittable. The `aria-required` attribute can be used with HTML form elements; it is not limited to elements that have an ARIA role assigned. - -Similar to the HTML `required` attribute set on semantic HTML form controls, the `aria-required` attribute explicitly conveys to assistive technologies that the element is required before a form may be submitted. The `required` attribute on a semantic HTML form control will prevent the form control from being submitted if no value is present — providing native error messaging in some browsers if a required value is invalid when the user attempts to submit the form. The `aria-required` attribute, like all ARIA states and properties, has no impact on element functionality. Functionality and behavior must be added in with JavaScript. - -> [!NOTE] -> ARIA only modifies the accessibility tree, modifying how assistive technology presents content to users. ARIA does not change anything about an element's function or behavior. When not using semantic HTML elements for their intended purpose and default functionality, you must use JavaScript to manage behavior, focus, and ARIA states. - -The CSS {{CSSXRef(':required')}} and {{CSSXRef(':optional')}} pseudoclasses match {{htmlelement("input")}}, {{htmlelement("select")}}, and {{htmlelement("textarea")}} elements based on whether they are required or optional, respectively. When using non-semantic elements as form controls, you don't get this CSS pseudoclass selector benefit. You can, however, use attribute selectors if the attribute is present: `[aria-required="true"]` or `[aria-required="false"]`. - -If a form contains both required and optional form elements, the required elements should be indicated visually using a treatment that does not rely solely on color to convey meaning. Typically, descriptive text and/or an icon are used. - -> [!NOTE] -> Which elements are required should be apparent to all users. Ensure the visual presentation indicates the form control is required in a consistent, visible manner, remembering that color is not enough to convey information. - -## Examples - -The attribute should be added to the form-control role. If the user needs to fill in an email address [`textbox`](/en-US/docs/Web/Accessibility/ARIA/Roles/textbox_role), include `aria-required="true"` on the textbox. - -```html -<div id="tbLabel">Email Address *</div> -<div - role="textbox" - contenteditable - aria-labelledby="tblabel" - aria-required="true" - id="email1"></div> -``` - -> [!NOTE] -> If the field's label already contains the word "required", it is recommended to leave out the `aria-required` attribute. This avoids that screen readers read out the term "required" twice. - -In this example, JavaScript must be used to prevent the containing form from being submitted if the textbox has no content. - -This could be written semantically, without the need for JavaScript: - -```html -<label for="email1">Email Address (required)</label> -<input type="email" id="email1" required /> -``` - -## Values - -- `true` - - : The element requires a value or must be checked for the form to be submittable. -- `false` - - : The element is not required. - -## Associated interfaces - -- {{domxref("Element.ariaRequired")}} - - : The [`ariaRequired`](/en-US/docs/Web/API/Element/ariaRequired) property, part of the {{domxref("Element")}} interface, reflects the value of the `aria-required` attribute. -- {{domxref("ElementInternals.ariaRequired")}} - - : The [`ariaRequired`](/en-US/docs/Web/API/ElementInternals/ariaRequired) property, part of the {{domxref("ElementInternals")}} interface, reflects the value of the `aria-required` attribute. - -## Associated roles - -Used in roles: - -- [`checkbox`](/en-US/docs/Web/Accessibility/ARIA/Roles/checkbox_role) -- [`combobox`](/en-US/docs/Web/Accessibility/ARIA/Roles/combobox_role) -- [`gridcell`](/en-US/docs/Web/Accessibility/ARIA/Roles/gridcell_role) -- [`listbox`](/en-US/docs/Web/Accessibility/ARIA/Roles/listbox_role) -- [`radiogroup`](/en-US/docs/Web/Accessibility/ARIA/Roles/radiogroup_role) -- [`spinbutton`](/en-US/docs/Web/Accessibility/ARIA/Roles/spinbutton_role) -- [`textbox`](/en-US/docs/Web/Accessibility/ARIA/Roles/textbox_role) -- [`tree`](/en-US/docs/Web/Accessibility/ARIA/Roles/tree_role) - -Inherits into roles: - -- [`columnheader`](/en-US/docs/Web/Accessibility/ARIA/Roles/columnheader_role) -- [`rowheader`](/en-US/docs/Web/Accessibility/ARIA/Roles/rowheader_role) -- [`searchbox`](/en-US/docs/Web/Accessibility/ARIA/Roles/searchbox_role) -- [`switch`](/en-US/docs/Web/Accessibility/ARIA/Roles/switch_role) -- [`treegrid`](/en-US/docs/Web/Accessibility/ARIA/Roles/treegrid_role) - -## Specifications - -{{Specifications}} - -## See also - -- HTML [`required`](/en-US/docs/Web/HTML/Element/input#required) attribute -- [`:optional` pseudoclass](/en-US/docs/Web/CSS/:optional) -- [`:required` pseudoclass](/en-US/docs/Web/CSS/:required) -- [`aria-invalid` attribute](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-invalid) -- [MDN Understanding WCAG, Guideline 3.3 explanations](/en-US/docs/Web/Accessibility/Understanding_WCAG/Understandable#guideline_3.3_%e2%80%94_input_assistance_help_users_avoid_and_correct_mistakes) -- [Understanding Success Criterion 3.3.2 | W3C Understanding WCAG 2.0](https://www.w3.org/TR/UNDERSTANDING-WCAG20/minimize-error-cues.html) diff --git a/files/en-us/web/accessibility/aria/attributes/aria-roledescription/index.md b/files/en-us/web/accessibility/aria/attributes/aria-roledescription/index.md deleted file mode 100644 index c3bce49e7e1c32a..000000000000000 --- a/files/en-us/web/accessibility/aria/attributes/aria-roledescription/index.md +++ /dev/null @@ -1,76 +0,0 @@ ---- -title: aria-roledescription -slug: Web/Accessibility/ARIA/Attributes/aria-roledescription -page-type: aria-attribute -spec-urls: https://w3c.github.io/aria/#aria-roledescription ---- - -{{AccessibilitySidebar}} - -The `aria-roledescription` attribute defines a human-readable, author-localized description for the role of an element. - -## Description - -Some assistive technologies (<abbr>AT</abbr>), such as screen readers, present the role of an element as part of the user experience. The `aria-roledescription` attribute provides a way to define a different human-readable name to be presented by AT as the role of an element. - -> [!NOTE] -> Only use aria-roledescription to clarify the purpose of non-interactive container roles and to provide a more specific description to a widget. - -Users depend on the presentation of known role name to understand the purpose of the element and, if it is a widget, how to interact with it. So, only use `aria-roledescription` to clarify the purpose of non-interactive container roles like `group` or `region` and to provide a more specific description to a widget. - -The `aria-roledescription` property overrides how ATs localize and express the name of a role. When you override a role name the user understands, you can potentially negatively impact a users' ability to understand and interact with an element. - -Avoid using the `aria-roledescription` attribute. When a use case appears special worthy of a unique roledescription, the interactions can often times be broken down into smaller pieces that have relevant roles. - -When there are no semantic or ARIA widget roles that correspond to the interaction model of your widget, use `role="application"`, provide an `aria-roledescription` with a human-readable, author-localized customized role name, and use `aria-describedby` to provide user instructions. - -ATs may customize and localize the names of ARIA roles. If you are using `aria-roledescription` to change how the role name is presented to the user, remember to handle localization. The value should be translated when a page is localized. - -Changing how the role is presented to the user has no impact on the functionality of the element. For example, if an element has a role of [`region`](/en-US/docs/Web/Accessibility/ARIA/Roles/region_role) or [`button`](/en-US/docs/Web/Accessibility/ARIA/Roles/button_role) when AT provides functions for navigating to the next region or button, if you set the `aria-roledescription` to `continent` and `escape` respectively, the AT will still allow those functions to navigate to regions and buttons. - -Again, avoid using `aria-roledescription`. In this example, `escape` has no relevant meaning to the user, but `button` with "escape" as a label does. - -When using `aria-roledescription`, also ensure that the element to which it is applied has a valid ARIA [`role`](/en-US/docs/Web/Accessibility/ARIA/Roles) or has implicit role semantics and that the value itself is not empty and contains more than just whitespace characters. - -The `aria-roledescription` is required when using `aria-brailleroledescription`. Note that, in general, `aria-brailleroledescription` should only be used in rare cases when a `aria-roledescription` is excessively verbose when rendered in Braille. - -## Examples - -The following example shows the use of `aria-roledescription` to indicate that a non-interactive container is a "slide" in a web-based presentation application. - -```html -<div - role="article" - aria-roledescription="slide" - id="slide" - aria-labelledby="slideheading"> - <h1 id="slideheading">Quarterly Report</h1> - <!-- remaining slide contents --> -</div> -``` - -In the previous examples, a screen reader user may hear "Quarterly Report, slide" rather than the less precise "Quarterly Report, article". - -## Values - -- `<string>` - - : A non-empty string, an unconstrained value type, containing more than just white space. - -## Associated interfaces - -- {{domxref("Element.ariaRoleDescription")}} - - : The [`ariaRoleDescription`](/en-US/docs/Web/API/Element/ariaRoleDescription) property, part of the {{domxref("Element")}} interface, reflects the value of the `aria-roledescription` attribute. -- {{domxref("ElementInternals.ariaRoleDescription")}} - - : The [`ariaRoleDescription`](/en-US/docs/Web/API/ElementInternals/ariaRoleDescription) property, part of the {{domxref("ElementInternals")}} interface, reflects the value of the `aria-roledescription` attribute. - -## Associated roles - -Supported by all roles and by all base markup elements except for `role="generic"`. - -## Specifications - -{{Specifications}} - -## See also - -- [ARIA roles](/en-US/docs/Web/Accessibility/ARIA/Roles) diff --git a/files/en-us/web/accessibility/aria/attributes/aria-rowcount/index.md b/files/en-us/web/accessibility/aria/attributes/aria-rowcount/index.md deleted file mode 100644 index 7f9c96123591211..000000000000000 --- a/files/en-us/web/accessibility/aria/attributes/aria-rowcount/index.md +++ /dev/null @@ -1,83 +0,0 @@ ---- -title: aria-rowcount -slug: Web/Accessibility/ARIA/Attributes/aria-rowcount -page-type: aria-attribute -spec-urls: https://w3c.github.io/aria/#aria-rowcount ---- - -{{AccessibilitySidebar}} - -The `aria-rowcount` attribute defines the total number of rows in a table, grid, or treegrid. - -## Description - -Some tables have hundreds, even millions, of rows. Even for tables with fewer rows, loading only a subsection of rows may be a design requirement, improve performance, or improve user experience. When only a subset of rows are loaded, you do need to let all users know that only a subset of the data is being displayed. The `aria-rowcount` attribute is used to define the total number of rows in a table, grid, or treegrid. - -Included on the {{HTMLElement('table')}} element or on an element with a role of [`table`](/en-US/docs/Web/Accessibility/ARIA/Roles/cell_role), the value is the number of rows in the full table, as an integer. If the total number of rows is not known, include `aria-rowcount="-1"`, which tells the browser to not count the total number of rows. - -If all of the rows are loaded and in the DOM, you don't need to include `aria-rowcount` as browsers automatically count the total number of rows. However, if the rows aren't all present in the DOM at any time, this attribute is needed to provide the number of rows when the full table size is known and to tell the browser to not automatically count the rows when the total number of rows is not known. - -## Example - -The following example shows a grid with 24 rows, of which the first row and rows 7 through 9 are displayed to the user. - -```html -<div role="grid" aria-rowcount="24"> - <div role="rowgroup"> - <div role="row" aria-rowindex="1"> - <span role="columnheader">First Name</span> - <span role="columnheader">Last Name</span> - <span role="columnheader">Position</span> - </div> - </div> - <div role="rowgroup"> - <div role="row" aria-rowindex="7"> - <span role="gridcell">Morgan</span> - <span role="gridcell">Brian</span> - <span role="gridcell">Midfielder</span> - </div> - <div role="row" aria-rowindex="8"> - <span role="gridcell">Abby</span> - <span role="gridcell">Dahlkemper</span> - <span role="gridcell">Defender</span> - </div> - <div role="row" aria-rowindex="9"> - <span role="gridcell">Ashlyn</span> - <span role="gridcell">Harris</span> - <span role="gridcell">Goalkeeper</span> - </div> - </div> -</div> -``` - -## Values - -- `<integer>` - - : The number of rows in the full table or `-1` is the table size is not known. - -## Associated interfaces - -- {{domxref("Element.ariaRowCount")}} - - : The [`ariaRowCount`](/en-US/docs/Web/API/Element/ariaRowCount) property, part of the {{domxref("Element")}} interface, reflects the value of the `aria-rowcount` attribute. -- {{domxref("ElementInternals.ariaRowCount")}} - - : The [`ariaRowCount`](/en-US/docs/Web/API/ElementInternals/ariaRowCount) property, part of the {{domxref("ElementInternals")}} interface, reflects the value of the `aria-rowcount` attribute. - -## Associated roles - -Used in roles: - -- [`table`](/en-US/docs/Web/Accessibility/ARIA/Roles/cell_role) - -Inherited into roles: - -- [`grid`](/en-US/docs/Web/Accessibility/ARIA/Roles/columnheader_role) -- [`treegrid`](/en-US/docs/Web/Accessibility/ARIA/Roles/gridcell_role) - -## Specifications - -{{Specifications}} - -## See also - -- [`aria-rowindex`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-rowindex) -- [`aria-colcount`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-colcount) diff --git a/files/en-us/web/accessibility/aria/attributes/aria-rowindex/index.md b/files/en-us/web/accessibility/aria/attributes/aria-rowindex/index.md deleted file mode 100644 index 3a234a636c9e77a..000000000000000 --- a/files/en-us/web/accessibility/aria/attributes/aria-rowindex/index.md +++ /dev/null @@ -1,103 +0,0 @@ ---- -title: aria-rowindex -slug: Web/Accessibility/ARIA/Attributes/aria-rowindex -page-type: aria-attribute -spec-urls: https://w3c.github.io/aria/#aria-rowindex ---- - -{{AccessibilitySidebar}} - -The `aria-rowindex` attribute defines an element's position with respect to the total number of rows within a table, grid, or treegrid. - -## Description - -Some tables have many, many rows. Loading only a subsection of rows may be done as a design requirement, to improve performance, or to improve user experience. - -When only a subset of rows are loaded, you do need to let all users know which subsets of rows are being displayed. The `aria-rowindex` attribute is used to define the cell or row's row index or position with respect to the total number of rows within a table, grid, or treegrid. - -Included on the {{HTMLElement('tr')}} element or on an element with a role of [`row`](/en-US/docs/Web/Accessibility/ARIA/Roles/row_role), or directly on the {{HTMLElement('td')}}, {{HTMLElement('th')}}, or element with role of [`cell`](/en-US/docs/Web/Accessibility/ARIA/Roles/cell_role) or [`gridcell`](/en-US/docs/Web/Accessibility/ARIA/Roles/gridcell_role), the value is the row's position with respect to the full table. - -The value for `aria-rowindex` is an integer greater than or equal to `1`, greater than the `aria-rowindex` value of any previous rows, and less than or equal to the number of rows in the full table. - -If all of the rows are loaded and in the DOM, you don't need to include `aria-rowindex` as browsers automatically calculate the index of each row. However, when only a subset of the rows are present in the DOM, `aria-rowindex` is needed to indicate each row's position with respect to the full table. If only a subset of rows are loaded, you also need to include [`aria-rowcount`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-rowcount) on the table ancestor, even if you don't know the total rowcount. - -If the table with only a subset of rows has a cell that spans more than one row, both the row and cell need to have the `aria-rowindex` set. If a cell spans more than one row-when a cell role includes the `aria-rowspan` attribute or HTML cell has a `rowspan` attribute set to a value greater than 1-include the row's `aria-rowindex` value on the spanning cell in addition to the appropriate row spanning attribute. The value should be the row index of the row where the span starts. - -> [!NOTE] -> The `aria-rowindex` must be added to each row, but is optional on the cells, except for cells that span rows: the `aria-rowindex` attribute is required on all spanning cells. - -## Examples - -The following example shows a grid with 24 rows, of which the first row and rows 7 through 10 are displayed to the user. The last "position" cell spans column 9 and 10. - -```html -<div role="grid" aria-rowcount="24"> - <div role="rowgroup"> - <div role="row" aria-rowindex="1"> - <span role="columnheader">First Name</span> - <span role="columnheader">Last Name</span> - <span role="columnheader">Position</span> - </div> - </div> - <div role="rowgroup"> - <div role="row" aria-rowindex="7"> - <span role="gridcell">Morgan</span> - <span role="gridcell">Brian</span> - <span role="gridcell">Midfielder</span> - </div> - <div role="row" aria-rowindex="8"> - <span role="gridcell">Abby</span> - <span role="gridcell">Dahlkemper</span> - <span role="gridcell">Defender</span> - </div> - <div role="row" aria-rowindex="9"> - <span role="gridcell">Ashlyn</span> - <span role="gridcell">Harris</span> - <span role="gridcell" aria-rowspan="2" aria-rowindex="9">Goalkeeper</span> - </div> - <div role="row" aria-rowindex="10"> - <span role="gridcell">Alyssa</span> - <span role="gridcell">Naeher</span> - </div> - </div> -</div> -``` - -Note both `aria-rowspan` and `aria-rowindex` are present on the Goalkeeper cell, which spans two rows. - -## Values - -- `<integer>` - - : An integer greater than or equal to 1, greater than the `aria-rowindex` of the previous row, if any, and less than or equal to the value of [`aria-rowcount`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-rowcount). - -## Associated interfaces - -- {{domxref("Element.ariaRowIndex")}} - - : The [`ariaRowIndex`](/en-US/docs/Web/API/Element/ariaRowIndex) property, part of the {{domxref("Element")}} interface, reflects the value of the `aria-rowindex` attribute. -- {{domxref("ElementInternals.ariaRowIndex")}} - - : The [`ariaRowIndex`](/en-US/docs/Web/API/ElementInternals/ariaRowIndex) property, part of the {{domxref("ElementInternals")}} interface, reflects the value of the `aria-rowindex` attribute. - -## Associated roles - -Used in roles: - -- [`cell`](/en-US/docs/Web/Accessibility/ARIA/Roles/cell_role) -- [`row`](/en-US/docs/Web/Accessibility/ARIA/Roles/row_role) - -Inherited into roles: - -- [`columnheader`](/en-US/docs/Web/Accessibility/ARIA/Roles/columnheader_role) -- [`gridcell`](/en-US/docs/Web/Accessibility/ARIA/Roles/gridcell_role) -- [`rowheader`](/en-US/docs/Web/Accessibility/ARIA/Roles/rowheader_role) - -## Specifications - -{{Specifications}} - -## See also - -- [`aria-rowindextext`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-rowindextext) -- [`aria-rowcount`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-rowcount) -- [`aria-rowspan`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-rowspan) -- [`aria-colindex`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-colindex) -- The [`rowspan`](/en-US/docs/Web/HTML/Element/td#rowspan) attribute on {{HTMLElement('td')}} diff --git a/files/en-us/web/accessibility/aria/attributes/aria-rowindextext/index.md b/files/en-us/web/accessibility/aria/attributes/aria-rowindextext/index.md deleted file mode 100644 index 57422c9bc4f20e0..000000000000000 --- a/files/en-us/web/accessibility/aria/attributes/aria-rowindextext/index.md +++ /dev/null @@ -1,55 +0,0 @@ ---- -title: aria-rowindextext -slug: Web/Accessibility/ARIA/Attributes/aria-rowindextext -page-type: aria-attribute -spec-urls: https://w3c.github.io/aria/#aria-rowindextext ---- - -{{AccessibilitySidebar}} - -The `aria-rowindextext` attribute defines a human-readable text alternative of `aria-rowindex`. - -## Description - -When you have a very long table or when you purposefully want to display just a section of a table, not all rows may be present in the DOM. When this happens, we use the [`aria-rowcount`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-rowcount) with an integer value to define how many rows the table (or grid) would have if all the rows were present and add the [`aria-rowindex`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-rowindex) property on each row and spanning cell to provide information on the row index within that larger table. When the value of `aria-rowindex` is not meaningful or does not reflect the displayed index, we can also add the `aria-rowindextext` to provide a human-readable text alternative to the `aria-rowindex` integer value. - -The `aria-rowindextext` should only be included **in addition to**, not as a replacement of, the `aria-rowindex`. Some assistive technologies use the numeric row index for the purpose of keeping track of the user's position or providing alternative table navigation. The `aria-rowindextext` is useful if that integer value isn't meaningful or does not reflect the displayed index, such as a game of Chess or Battleship. - -The `aria-rowindextext` is added to each {{HTMLElement('tr')}} or to elements with the `row` role. It can also be addition to cells or owned elements of each row. - -## Values - -- `<string>` - - The human-readable text alternative of the numeric [`aria-rowindex`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-rowindex) - -## Associated interfaces - -- {{domxref("Element.ariaRowIndexText")}} - - : The [`ariaRowIndexText`](/en-US/docs/Web/API/Element/ariaRowIndexText) property, part of the {{domxref("Element")}} interface, reflects the value of the `aria-rowindextext` attribute. -- {{domxref("ElementInternals.ariaRowIndexText")}} - - : The [`ariaRowIndexText`](/en-US/docs/Web/API/ElementInternals/ariaRowIndexText) property, part of the {{domxref("ElementInternals")}} interface, reflects the value of the `aria-rowindextext` attribute. - -## Associated roles - -Used in roles: - -- [`cell`](/en-US/docs/Web/Accessibility/ARIA/Roles/cell_role) -- [`row`](/en-US/docs/Web/Accessibility/ARIA/Roles/row_role) - -Inherited into roles: - -- [`columnheader`](/en-US/docs/Web/Accessibility/ARIA/Roles/columnheader_role) -- [`gridcell`](/en-US/docs/Web/Accessibility/ARIA/Roles/gridcell_role) -- [`rowheader`](/en-US/docs/Web/Accessibility/ARIA/Roles/rowheader_role) - -## Specifications - -{{Specifications}} - -## See also - -- [`aria-rowindex`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-rowindex) -- [`aria-rowcount`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-rowcount) -- [`aria-rowspan`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-rowspan) -- [`aria-colindextext`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-colindextext) -- [`aria-colindex`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-colindex) diff --git a/files/en-us/web/accessibility/aria/attributes/aria-rowspan/index.md b/files/en-us/web/accessibility/aria/attributes/aria-rowspan/index.md deleted file mode 100644 index da36a5d03755391..000000000000000 --- a/files/en-us/web/accessibility/aria/attributes/aria-rowspan/index.md +++ /dev/null @@ -1,54 +0,0 @@ ---- -title: aria-rowspan -slug: Web/Accessibility/ARIA/Attributes/aria-rowspan -page-type: aria-attribute -spec-urls: https://w3c.github.io/aria/#aria-rowspan ---- - -{{AccessibilitySidebar}} - -The `aria-rowspan` attribute defines the number of rows spanned by a cell or gridcell within a table, grid, or treegrid. - -## Description - -Similar to the `rowspan` attribute of the {{HTMLElement('td')}} and {{HTMLElement('th')}} elements, but for cells and gridcells which are not contained in a native table, the `aria-rowspan` attribute defines the number of rows spanned by a `cell` or `gridcell` within a `table`, `grid`, or `treegrid`. - -This attribute is intended for cells and gridcells which are **not** part of an HTML {{HTMLElement('table')}}. When a cell is nested in a semantic `<table>`, the `rowspan` attribute should be used when a <td> or <th> spans more than one row. If both are present, `rowspan` takes precedence over `aria-rowspan`. But, like all ARIA attributes, `aria-rowspan` only impacts the accessibility tree. It doesn't change your layout. - -> [!NOTE] -> ARIA modifies the accessibility tree and how assistive technology presents content to your users. ARIA doesn't change anything about an element's function, behavior, or appearance. When using non-semantic elements, you must use CSS to manage layout and appearance. - -The value of `aria-rowspan` is an integer greater than or equal to 0 and less than the value which would cause the cell or gridcell to overlap the next cell or gridcell in the same column. Setting the value to `0` indicates that the cell or gridcell is to span all the remaining rows in the row group. The default value is `1`. - -## Values - -- `<integer>` - - : An integer greater than or equal to `0` and less than would cause a cell to overlap the next cell in the same column. - -## Associated interfaces - -- {{domxref("Element.ariaRowSpan")}} - - : The [`ariaRowSpan`](/en-US/docs/Web/API/Element/ariaRowSpan) property, part of the {{domxref("Element")}} interface, reflects the value of the `aria-rowspan` attribute. -- {{domxref("ElementInternals.ariaRowSpan")}} - - : The [`ariaRowSpan`](/en-US/docs/Web/API/ElementInternals/ariaRowSpan) property, part of the {{domxref("ElementInternals")}} interface, reflects the value of the `aria-rowspan` attribute. - -## Associated roles - -Used in roles: - -- [`cell`](/en-US/docs/Web/Accessibility/ARIA/Roles/cell_role) - -Inherited into roles: - -- [`columnheader`](/en-US/docs/Web/Accessibility/ARIA/Roles/columnheader_role) -- [`rowheader`](/en-US/docs/Web/Accessibility/ARIA/Roles/rowheader_role) - -## Specifications - -{{Specifications}} - -## See also - -- The [`rowspan`](/en-US/docs/Web/HTML/Element/td#rowspan) attribute on {{HTMLElement('td')}} -- [`aria-rowindex`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-rowindex) -- [`aria-colspan`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-colspan) diff --git a/files/en-us/web/accessibility/aria/attributes/aria-selected/index.md b/files/en-us/web/accessibility/aria/attributes/aria-selected/index.md deleted file mode 100644 index 475febc643722f1..000000000000000 --- a/files/en-us/web/accessibility/aria/attributes/aria-selected/index.md +++ /dev/null @@ -1,131 +0,0 @@ ---- -title: aria-selected -slug: Web/Accessibility/ARIA/Attributes/aria-selected -page-type: aria-attribute -spec-urls: https://w3c.github.io/aria/#aria-selected ---- - -{{AccessibilitySidebar}} - -The `aria-selected` attribute indicates the current "selected" state of various widgets. - -## Description - -The `aria-selected` attribute indicates the current "selected" state for [`gridcell`](/en-US/docs/Web/Accessibility/ARIA/Roles/gridcell_role), [`option`](/en-US/docs/Web/Accessibility/ARIA/Roles/option_role), [`row`](/en-US/docs/Web/Accessibility/ARIA/Roles/row_role) and [`tab`](/en-US/docs/Web/Accessibility/ARIA/Roles/tab_role) roles. - -This attribute is used to indicate which elements within single-selection and multiple-selection composite widgets are selected. If more than one element is selectable at a time, include `aria-multiselectable="true"` on the grid, listbox, tablist, or other owning role, while including `aria-selected` only on the selectable cells, options, and tabs. - -For other roles, the currently selected state is set with [`aria-current`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-current), or possibly [`aria-checked`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-checked) or [`aria-pressed`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-pressed), depending on the role. - -Widgets that support both `aria-selected` and `aria-current` at the same time have different meanings for each. For example, `aria-current="page"` can be used in a navigation tree to indicate which page is currently displayed, while `aria-selected="true"` indicates which page will be displayed if the user activates the `treeitem`. - -### Grid - -Setting `aria-selected="false"` on a focusable gridcell indicates the cell is selectable. If the grid allows more than one gridcell to be selected at a time, set `aria-multiselectable="true"` on the element with role [`grid`](/en-US/docs/Web/Accessibility/ARIA/Roles/grid_role). Setting `aria-selected` on a column or row header gridcell does not propagate the state to other cells in the column or row. - -### Option - -Both `aria-selected` and `aria-checked` are valid for [`option`](/en-US/docs/Web/Accessibility/ARIA/Roles/option_role). Some user interfaces indicate selection with `aria-selected` in single-select list boxes and with `aria-checked` in multi-select list boxes. - -Don't specify both `aria-selected` and `aria-checked` on `option` elements contained by the same `listbox` unless the meaning and purpose of `aria-selected` is different from the meaning and purpose of aria-checked in the user interface, the meaning and purpose of each state apparent, and the UI provides separate methods for controlling each state. - -### Row - -The `aria-selected` attribute is supported on `row` but not `column`. If a grid supports selection, when a cell or row is selected, the selected element has `aria-selected="true"` set. - -If the grid supports column selection and a column is selected, all cells in the column have `aria-selected` set to `true`. - -### Tab - -In a tablist, `aria-selected` is used on a tab to indicate the currently-displayed [`tabpanel`](/en-US/docs/Web/Accessibility/ARIA/Roles/tabpanel_role). - -The selected [`tab`](/en-US/docs/Web/Accessibility/ARIA/Roles/tab_role) in a [`tablist`](/en-US/docs/Web/Accessibility/ARIA/Roles/tablist_role) should have the attribute `aria-selected="true"` set. All inactive tabs in the tablist should have `aria-selected="false"` set. Setting the state only impacts the accessibility tree: make sure to style the active tab in a way that visual indicates it's selected state. The default value for `aria-selected` on a `tab` role is `false`. - -If more than one tab is selectable at a time, include `aria-multiselectable` on the `tablist`. - -## Examples - -In this `tablist` example, the first `tab` is selected: - -```html -<div class="tab-interface"> - <div role="tablist" aria-label="Sample Tabs"> - <span - role="tab" - aria-selected="true" - aria-controls="panel-1" - id="tab-1" - tabindex="0"> - First Tab - </span> - <span - role="tab" - aria-selected="false" - aria-controls="panel-2" - id="tab-2" - tabindex="-1"> - Second Tab - </span> - <span - role="tab" - aria-selected="false" - aria-controls="panel-3" - id="tab-3" - tabindex="-1"> - Third Tab - </span> - </div> - <div id="panel-1" role="tabpanel" tabindex="0" aria-labelledby="tab-1"> - <p>Content for the first panel</p> - </div> - <div id="panel-2" role="tabpanel" tabindex="0" aria-labelledby="tab-2" hidden> - <p>Content for the second panel</p> - </div> - <div id="panel-3" role="tabpanel" tabindex="0" aria-labelledby="tab-3" hidden> - <p>Content for the third panel</p> - </div> -</div> -``` - -> [!NOTE] -> ARIA only modifies the accessibility tree for an element and how assistive technology presents the content to users. ARIA doesn't change anything about an element's function or behavior. - -## Values - -- `true` - - : The selectable element is selected. -- `false` - - : The selectable element is not selected. Implicit default for [`tab`](/en-US/docs/Web/Accessibility/ARIA/Roles/tab_role). -- `undefined` (default) - - : The element is not selectable. - -## Associated interfaces - -- {{domxref("Element.ariaSelected")}} - - : The [`ariaSelected`](/en-US/docs/Web/API/Element/ariaSelected) property, part of the {{domxref("Element")}} interface, reflects the value of the `aria-selected` attribute. -- {{domxref("ElementInternals.ariaSelected")}} - - : The [`ariaSelected`](/en-US/docs/Web/API/ElementInternals/ariaSelected) property, part of the {{domxref("ElementInternals")}} interface, reflects the value of the `aria-selected` attribute. - -## Associated roles - -Used in roles: - -- [`gridcell`](/en-US/docs/Web/Accessibility/ARIA/Roles/gridcell_role) -- [`option`](/en-US/docs/Web/Accessibility/ARIA/Roles/option_role) -- [`row`](/en-US/docs/Web/Accessibility/ARIA/Roles/row_role) -- [`tab`](/en-US/docs/Web/Accessibility/ARIA/Roles/tab_role) - -Inherited into roles: - -- [`columnheader`](/en-US/docs/Web/Accessibility/ARIA/Roles/columnheader_role) -- [`rowheader`](/en-US/docs/Web/Accessibility/ARIA/Roles/rowheader_role) -- [`treeitem`](/en-US/docs/Web/Accessibility/ARIA/Roles/treeitem_role) - -## Specifications - -{{Specifications}} - -## See also - -- [`aria-pressed`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-pressed) -- [`aria-checked`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-checked) diff --git a/files/en-us/web/accessibility/aria/attributes/aria-setsize/index.md b/files/en-us/web/accessibility/aria/attributes/aria-setsize/index.md deleted file mode 100644 index eb9e9cb596f4008..000000000000000 --- a/files/en-us/web/accessibility/aria/attributes/aria-setsize/index.md +++ /dev/null @@ -1,92 +0,0 @@ ---- -title: aria-setsize -slug: Web/Accessibility/ARIA/Attributes/aria-setsize -page-type: aria-attribute -spec-urls: https://w3c.github.io/aria/#aria-setsize ---- - -{{AccessibilitySidebar}} - -The `aria-setsize` attribute defines the number of items in the current set of listitems or treeitems when not all items in the set are present in the DOM. - -## Description - -Browsers automatically calculate the set size and position for each item in a group of items, like the number of {{HTMLelement('li')}}s in a list, buttons in a same-named group of [radio buttons](/en-US/docs/Web/HTML/Element/input/radio), and {{HTMLelement('option')}}s in a {{HTMLelement('select')}}. Assistive technologies, like screen readers, take advantage of this state management to report set sizes to the user. - -When the DOM is not complete, the browser calculation of the number of items in a set can be incorrect. When only a subset of items, such as list items, are loaded into the DOM, the browser calculates the number of items based only on those present. The `aria-setsize` attribute should be used to override the browser's incorrect count. It defines the number of items in the current set of listitems or treeitems had the entire set been loaded. - -`aria-setsize` attribute is set on each item, rather than on any containing element. The value is the same for each item: an integer reflecting number of items in the complete set, or `-1` if the set size is unknown. If all the items are present in the DOM, the browser can calculate the set size and the position of each item, making both `aria-setsize` and `aria-posinset` unnecessary. - -Elements with the `aria-setsize` generally have the [`aria-posinset`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-posinset) attribute included as well to indicate the position of that item within the set. The `aria-posinset` value is between `1` and the positive value of `aria-setsize`. - -For example, in a page's comments section, When comments in are not all in the DOM, such as when comments are paginated, the level, total number of comments, and position of each comment should be set with ARIA. The hierarchical level of comments can be indicated with [`aria-level`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-level). Group positional information is indicated with `aria-posinset` and `aria-setsize`. - -When a feed has a static number of articles, `aria-setsize` can be added to each article element with the value being either the total number of articles loaded or the total number in the feed. The value chosen depends on which value is most helpful to users. If the number of articles is extremely large, indefinite, or changes often, `aria-setsize="-1"` can be set to communicate the size of the set is unknown. - -In a [`listbox`](/en-US/docs/Web/Accessibility/ARIA/Roles/listbox_role), when the complete set of available options is not present in the DOM due to dynamic loading on scroll, both `aria-setsize` and `aria-posinset` can be set on each [`option`](/en-US/docs/Web/Accessibility/ARIA/Roles/option_role). - -In a tree view, if the complete set of available nodes is not present in the DOM due to dynamic loading as the user moves focus in or scrolls the tree, each node has `aria-level`, `aria-setsize`, and `aria-posinset` set. - -In a menu, `aria-setsize` is set on all [`menuitem`](/en-US/docs/Web/Accessibility/ARIA/Roles/menuitem_role), [`menuitemcheckbox`](/en-US/docs/Web/Accessibility/ARIA/Roles/menuitemcheckbox_role), or [`menuitemradio`](/en-US/docs/Web/Accessibility/ARIA/Roles/menuitemradio_role) roles, with the value being the total number of items in the menu, excluding any separators. - -## Example - -The following example shows items 5 through 8 in a set of 16. - -```html -<h2 id="label_fruit">Available Fruit</h2> -<ul role="listbox" aria-labelledby="label_fruit"> - <li role="option" aria-setsize="16" aria-posinset="5">apples</li> - <li role="option" aria-setsize="16" aria-posinset="6">bananas</li> - <li role="option" aria-setsize="16" aria-posinset="7">cantaloupes</li> - <li role="option" aria-setsize="16" aria-posinset="8">dates</li> -</ul> -``` - -To orient the user, assistive technologies would list the bananas above as "item 6 out of 16." - -## Values - -- `<integer>` - - : The number of items in the full set or `-1` is the set size is unknown. - -## Associated interfaces - -- {{domxref("Element.ariaSetSize")}} - - : The [`ariaSetSize`](/en-US/docs/Web/API/Element/ariaSetSize) property, part of the {{domxref("Element")}} interface, reflects the value of the `aria-setsize` attribute. -- {{domxref("ElementInternals.ariaSetSize")}} - - : The [`ariaSetSize`](/en-US/docs/Web/API/ElementInternals/ariaSetSize) property, part of the {{domxref("ElementInternals")}} interface, reflects the value of the `aria-setsize` attribute. - -## Associated roles - -Used in roles: - -- [`article`](/en-US/docs/Web/Accessibility/ARIA/Roles/article_role) -- [`associationlistitemkey`](/en-US/docs/Web/Accessibility/ARIA/Roles/structural_roles) -- [`associationlistitemvalue`](/en-US/docs/Web/Accessibility/ARIA/Roles/structural_roles) -- [`comment`](/en-US/docs/Web/Accessibility/ARIA/Roles/comment_role) -- [`listitem`](/en-US/docs/Web/Accessibility/ARIA/Roles/listitem_role) -- [`menuitem`](/en-US/docs/Web/Accessibility/ARIA/Roles/menuitem_role) -- [`option`](/en-US/docs/Web/Accessibility/ARIA/Roles/option_role) -- [`radio`](/en-US/docs/Web/Accessibility/ARIA/Roles/radio_role) -- [`row`](/en-US/docs/Web/Accessibility/ARIA/Roles/row_role) -- [`tab`](/en-US/docs/Web/Accessibility/ARIA/Roles/tab_role) - -Inherits into roles: - -- [`comment`](/en-US/docs/Web/Accessibility/ARIA/Roles/comment_role) -- [`menuitemcheckbox`](/en-US/docs/Web/Accessibility/ARIA/Roles/menuitemcheckbox_role) -- [`menuitemradio`](/en-US/docs/Web/Accessibility/ARIA/Roles/menuitemradio_role) -- [`treeitem`](/en-US/docs/Web/Accessibility/ARIA/Roles/treeitem_role) - -## Specifications - -{{Specifications}} - -## See also - -- [`aria-posinset`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-posinset) -- W3C WAI-ARIA practices: - - [Treegrid Email Inbox example](https://www.w3.org/WAI/ARIA/apg/patterns/treegrid/examples/treegrid-1/) - - [Navigation Treeview example](https://www.w3.org/WAI/ARIA/apg/patterns/treeview/examples/treeview-navigation/) - - [File Directory Treeview Example Using Declared Properties](https://www.w3.org/WAI/ARIA/apg/patterns/treeview/examples/treeview-1b/) diff --git a/files/en-us/web/accessibility/aria/attributes/aria-sort/index.md b/files/en-us/web/accessibility/aria/attributes/aria-sort/index.md deleted file mode 100644 index ac8403c594da122..000000000000000 --- a/files/en-us/web/accessibility/aria/attributes/aria-sort/index.md +++ /dev/null @@ -1,86 +0,0 @@ ---- -title: aria-sort -slug: Web/Accessibility/ARIA/Attributes/aria-sort -page-type: aria-attribute -spec-urls: https://w3c.github.io/aria/#aria-sort ---- - -{{AccessibilitySidebar}} - -The `aria-sort` attribute indicates if items in a table or grid are sorted in ascending or descending order. - -## Description - -If a grid or table provides sort functionality, the `aria-sort` attribute should be set to either `ascending` or `descending` (or `other`) on the header cell element for the sorted column or row. - -The `aria-sort` attribute is only set on the currently sorted column or row. Set `aria-sort="ascending"` to indicate the data cells in the column or row are sorted in ascending order. If the sort order is reversed, toggle the value to `aria-sort="descending"`. When a different column or row becomes sorted, the single `aria-sort` attribute is moved to the header cell for the newly sorted column or row with the appropriate value for the sort order. - -The `aria-sort` attribute should only be added to a single table or grid header at a time. The attribute is set to inform assistive technology users which column or row is sorted. It doesn't have any impact on the actual sort order. - -## Examples - -This table loads with the last name column sorted in ascending order. - -```html -<table> - <caption> - Steering Committee Members - </caption> - <thead> - <tr> - <th> - <button>First Name</button> - </th> - <th aria-sort="ascending"> - <button>Last Name</button> - </th> - <th> - <button>Company</button> - </th> - <th>Email</th> - </tr> - </thead> - <tbody> - … - </tbody> -</table> -``` - -If a user clicks on the _Last Name_ button, [`aria-pressed="true"`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-pressed) would be added to the {{HTMLElement('button')}} element and the `aria-sort` value would be toggled to `"descending"` with JavaScript. If the user clicks on a different header button, the `aria-sort` would be removed from the _Last Name_ header to be placed on the clicked button's {{HTMLElement('th')}} parent. - -We provided instructions in the caption for assistive technology who may not see the down arrows that we would add with CSS targeting the `th[aria-sort="ascending"]` and `th[aria-sort="descending"]` selectors. - -## Values - -- `ascending` - - : Items are sorted in ascending order by this column. -- `descending` - - : Items are sorted in descending order by this column. -- `none` (default) - - : There is no defined sort applied to the column. -- `other` - - : A sorting algorithm other than ascending or descending has been applied. - -## Associated interfaces - -- {{domxref("Element.ariaSort")}} - - : The [`ariaSort`](/en-US/docs/Web/API/Element/ariaSort) property, part of the {{domxref("Element")}} interface, reflects the value of the `aria-sort` attribute. -- {{domxref("ElementInternals.ariaSort")}} - - : The [`ariaSort`](/en-US/docs/Web/API/ElementInternals/ariaSort) property, part of the {{domxref("ElementInternals")}} interface, reflects the value of the `aria-sort` attribute. - -## Associated roles - -Used in roles: - -- [`columnheader`](/en-US/docs/Web/Accessibility/ARIA/Roles/columnheader_role) -- [`rowheader`](/en-US/docs/Web/Accessibility/ARIA/Roles/rowheader_role) - -## Specifications - -{{Specifications}} - -## See also - -- [Sortable table example](https://www.w3.org/TR/wai-aria-practices-1.2/examples/table/sortable-table.html) -W3C -- [`aria-pressed`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-pressed) -- The {{HTMLElement('th')}} element diff --git a/files/en-us/web/accessibility/aria/attributes/aria-valuemax/index.md b/files/en-us/web/accessibility/aria/attributes/aria-valuemax/index.md deleted file mode 100644 index d60a0e6bebecc67..000000000000000 --- a/files/en-us/web/accessibility/aria/attributes/aria-valuemax/index.md +++ /dev/null @@ -1,77 +0,0 @@ ---- -title: aria-valuemax -slug: Web/Accessibility/ARIA/Attributes/aria-valuemax -page-type: aria-attribute -spec-urls: https://w3c.github.io/aria/#aria-valuemax ---- - -{{AccessibilitySidebar}} - -The `aria-valuemax` attribute defines the maximum allowed value for a range widget. - -## Description - -The `aria-valuemax` attribute defines the maximum value allowed for range widgets. It is similar to the `max` attribute of {{HTMLElement('progress')}}, {{HTMLElement('meter')}}, and {{HTMLElement('input')}} of type [`range`](/en-US/docs/Web/HTML/Element/input/range), [`number`](/en-US/docs/Web/HTML/Element/input/number) and all the date-time types. - -When creating a range type role, including [`meter`](/en-US/docs/Web/Accessibility/ARIA/Roles/meter_role), [`scrollbar`](/en-US/docs/Web/Accessibility/ARIA/Roles/scrollbar_role), [`slider`](/en-US/docs/Web/Accessibility/ARIA/Roles/slider_role), and [`spinbutton`](/en-US/docs/Web/Accessibility/ARIA/Roles/spinbutton_role) on a non-semantic element, the `aria-valuemax` enables defining a maximum that is more than the minimum value and is a required attribute of `slider`, `scrollbar` and `spinbutton`. - -Declaring the minimum and maximum values allows assistive technologies to convey the size of the range to users. The minimum value is defined with [`aria-valuemin`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-valuemin). - -> [!WARNING] -> The [`range`](/en-US/docs/Web/Accessibility/ARIA/Roles/range_role) role itself should **NOT** be used as it is an ["abstract"](/en-US/docs/Web/Accessibility/ARIA/Roles#6._abstract_roles). The `aria-valuemax` attribute is used on all of the range roles subtypes. - -## Example - -The code below shows a simple slider with a maximum value of 9. - -```html -<div id="dimesLabel">Dimes</div> -<div - role="slider" - aria-valuenow="0" - aria-valuemin="0" - aria-valuemax="9" - aria-labelledby="dimesLabel" - id="dimes"></div> -``` - -## Values - -- `<number>` - - : An integer or decimal number that is greater than the minimum value. - -## Associated interfaces - -- {{domxref("Element.ariaValueMax")}} - - : The [`ariaValueMax`](/en-US/docs/Web/API/Element/ariaValueMax) property, part of the {{domxref("Element")}} interface, reflects the value of the `aria-valuemax` attribute. -- {{domxref("ElementInternals.ariaValueMax")}} - - : The [`ariaValueMax`](/en-US/docs/Web/API/ElementInternals/ariaValueMax) property, part of the {{domxref("ElementInternals")}} interface, reflects the value of the `aria-valuemax` attribute. - -## Associated roles - -Used in roles: - -- [`meter`](/en-US/docs/Web/Accessibility/ARIA/Roles/meter_role) -- [`scrollbar`](/en-US/docs/Web/Accessibility/ARIA/Roles/scrollbar_role) (required) -- [`separator`](/en-US/docs/Web/Accessibility/ARIA/Roles/separator_role) -- [`slider`](/en-US/docs/Web/Accessibility/ARIA/Roles/slider_role) (required) -- [`spinbutton`](/en-US/docs/Web/Accessibility/ARIA/Roles/spinbutton_role) (required) - -Inherited into roles: - -- [`meter`](/en-US/docs/Web/Accessibility/ARIA/Roles/meter_role) -- [`progressbar`](/en-US/docs/Web/Accessibility/ARIA/Roles/progressbar_role) -- [`scrollbar`](/en-US/docs/Web/Accessibility/ARIA/Roles/scrollbar_role) -- [`slider`](/en-US/docs/Web/Accessibility/ARIA/Roles/slider_role) -- [`spinbutton`](/en-US/docs/Web/Accessibility/ARIA/Roles/spinbutton_role) - -## Specifications - -{{Specifications}} - -## See also - -- [`range` role](/en-US/docs/Web/Accessibility/ARIA/Roles/range_role) -- [`<input type="range>` element `max` attribute](/en-US/docs/Web/HTML/Element/input/range#max) -- [`aria-valuemin`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-valuemin) -- [`aria-valuenow`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-valuenow) diff --git a/files/en-us/web/accessibility/aria/attributes/aria-valuemin/index.md b/files/en-us/web/accessibility/aria/attributes/aria-valuemin/index.md deleted file mode 100644 index e18252f0f0b2935..000000000000000 --- a/files/en-us/web/accessibility/aria/attributes/aria-valuemin/index.md +++ /dev/null @@ -1,64 +0,0 @@ ---- -title: aria-valuemin -slug: Web/Accessibility/ARIA/Attributes/aria-valuemin -page-type: aria-attribute -spec-urls: https://w3c.github.io/aria/#aria-valuemin ---- - -{{AccessibilitySidebar}} - -The `aria-valuemin` attribute defines the minimum allowed value for a range widget. - -## Description - -The `aria-valuemin` attribute defines the minimum value allowed for range widgets. It is similar to the `min` attribute of {{HTMLElement('progress')}}, {{HTMLElement('meter')}}, and {{HTMLElement('input')}} of type [`range`](/en-US/docs/Web/HTML/Element/input/range), [`number`](/en-US/docs/Web/HTML/Element/input/number) and all the date-time types. - -When creating a range type role, including [`meter`](/en-US/docs/Web/Accessibility/ARIA/Roles/meter_role), [`scrollbar`](/en-US/docs/Web/Accessibility/ARIA/Roles/scrollbar_role), [`slider`](/en-US/docs/Web/Accessibility/ARIA/Roles/slider_role), and [`spinbutton`](/en-US/docs/Web/Accessibility/ARIA/Roles/spinbutton_role) on a non-semantic element, the `aria-valuemin` enables defining a minimum that is less than the maximum value and is a required attribute of `slider`, `scrollbar` and `spinbutton`. - -Declaring the minimum and maximum values allows assistive technologies to convey the size of the range to users. - -The maximum value is defined with [`aria-valuemax`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-valuemax). - -> [!WARNING] -> The [`range`](/en-US/docs/Web/Accessibility/ARIA/Roles/range_role) role itself should **NOT** be used as it is an ["abstract"](/en-US/docs/Web/Accessibility/ARIA/Roles#6._abstract_roles). The `aria-valuemin` attribute is used on all of the range roles subtypes. - -## Values - -- `<number>` - - : A decimal number, below the maximum value. - -## Associated interfaces - -- {{domxref("Element.ariaValueMin")}} - - : The [`ariaValueMin`](/en-US/docs/Web/API/Element/ariaValueMin) property, part of the {{domxref("Element")}} interface, reflects the value of the `aria-valuemin` attribute. -- {{domxref("ElementInternals.ariaValueMin")}} - - : The [`ariaValueMin`](/en-US/docs/Web/API/ElementInternals/ariaValueMin) property, part of the {{domxref("ElementInternals")}} interface, reflects the value of the `aria-valuemin` attribute. - -## Associated roles - -Used in roles: - -- [`meter`](/en-US/docs/Web/Accessibility/ARIA/Roles/meter_role) -- [`scrollbar`](/en-US/docs/Web/Accessibility/ARIA/Roles/scrollbar_role) -- [`separator`](/en-US/docs/Web/Accessibility/ARIA/Roles/separator_role) -- [`slider`](/en-US/docs/Web/Accessibility/ARIA/Roles/slider_role) -- [`spinbutton`](/en-US/docs/Web/Accessibility/ARIA/Roles/spinbutton_role) - -Inherited into roles: - -- [`meter`](/en-US/docs/Web/Accessibility/ARIA/Roles/meter_role) -- [`progressbar`](/en-US/docs/Web/Accessibility/ARIA/Roles/progressbar_role) -- [`scrollbar`](/en-US/docs/Web/Accessibility/ARIA/Roles/scrollbar_role) -- [`slider`](/en-US/docs/Web/Accessibility/ARIA/Roles/slider_role) -- [`spinbutton`](/en-US/docs/Web/Accessibility/ARIA/Roles/spinbutton_role) - -## Specifications - -{{Specifications}} - -## See also - -- [`range` role](/en-US/docs/Web/Accessibility/ARIA/Roles/range_role) -- [`<input type="range>` element `min` attribute](/en-US/docs/Web/HTML/Element/input/range#min) -- [`aria-valuemax`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-valuemax) -- [`aria-valuenow`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-valuenow) diff --git a/files/en-us/web/accessibility/aria/attributes/aria-valuenow/index.md b/files/en-us/web/accessibility/aria/attributes/aria-valuenow/index.md deleted file mode 100644 index 7c8469cf80ce081..000000000000000 --- a/files/en-us/web/accessibility/aria/attributes/aria-valuenow/index.md +++ /dev/null @@ -1,123 +0,0 @@ ---- -title: aria-valuenow -slug: Web/Accessibility/ARIA/Attributes/aria-valuenow -page-type: aria-attribute -spec-urls: https://w3c.github.io/aria/#aria-valuenow ---- - -{{AccessibilitySidebar}} - -The `aria-valuenow` attribute defines the current value for a `range` widget. - -## Description - -The `aria-valuenow` attribute defines the current value for range widgets. It is similar to the `value` attribute of {{HTMLElement('progress')}}, {{HTMLElement('meter')}}, and {{HTMLElement('input')}} of type [`range`](/en-US/docs/Web/HTML/Element/input/range), [`number`](/en-US/docs/Web/HTML/Element/input/number) and all the date-time types. - -When creating a range type role, including [`meter`](/en-US/docs/Web/Accessibility/ARIA/Roles/meter_role), [`scrollbar`](/en-US/docs/Web/Accessibility/ARIA/Roles/scrollbar_role), [`slider`](/en-US/docs/Web/Accessibility/ARIA/Roles/slider_role), and [`spinbutton`](/en-US/docs/Web/Accessibility/ARIA/Roles/spinbutton_role) on a non-semantic element, the `aria-valuenow` enables defining a current numeric value between the minimum and maximum values. The minimum and maximum values are defined with [`aria-valuemin`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-valuemin) and [`aria-valuemax`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-valuemax). - -> [!WARNING] -> The [`range`](/en-US/docs/Web/Accessibility/ARIA/Roles/range_role) role itself should **NOT** be used as it is an ["abstract"](/en-US/docs/Web/Accessibility/ARIA/Roles#6._abstract_roles). The `aria-valuenow` attribute is used on all of the range roles subtypes. - -```html -<p id="birthyearLabel">What year were you born?</p> -<div - role="spinbutton" - tabindex="-1" - aria-valuenow="1984" - aria-valuemin="1900" - aria-valuemax="2021" - aria-labelledby="birthyearLabel"> - <span class="value"> 1984 </span> - <span role="button"> - <span aria-hidden="true">+</span> - Increment year by 1 - </span> - <span role="button"> - <span aria-hidden="true">-</span> - Decrement year by 1 - </span> -</div> -``` - -Use semantic HTML elements when you can: - -```html -<label for="birthyear">What year were you born?</label> -<input type="number" id="birthyear" value="1984" min="1900" max="2021" /> -``` - -If there is no known value, like when a progress bar is in an indeterminate state, don't set an `aria-valuenow` attribute. - -When there is no `aria-valuenow` set, no information is implied about a current value. - -When used with sliders and spinbuttons, assistive technologies announce the actual value to users. - -When used with progressbar and scrollbar, assistive technologies announce the value to users as a percent. When `aria-valuemin` and `aria-valuemax` are both defined, the percent value is calculated as a position on the range. Otherwise, the actual value is announced as a percent. - -When the value to be announced, either the actual value or the value as a percent, may not be clear to users, the [`aria-valuetext`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-valuetext) attribute should be used to provide a user-friendly representation of the value. When set, the valuetext string is announced instead of the valuenow numeric value. For example, if a slider represents the days of the week, so the day of the week's `aria-valuenow` is a number, the `aria-valuetext` property should be set to a string that makes the slider value understandable, such as "Monday". - -## Examples - -```html -<p id="temperatureLabel">Oven Temperature</p> -<div - role="meter" - id="temperature" - aria-valuenow="205" - aria-valuemin="70" - aria-valuemax="250" - aria-labelledby="temperatureLabel"> - <div class="meter-color" aria-hidden="true"></div> -</div> -``` - -The first rule of ARIA use is "if you can use a native feature with the semantics and behavior you require already built in, instead of repurposing an element and **adding** an ARIA role, state or property to make it accessible, then do so." - -```html -<label for="temperature">Oven Temperature</label> -<input type="range" id="temperature" value="205" min="70" max="250" step="5" /> -``` - -If we employ native HTML semantics with {{HTMLElement('input')}} we get styles and semantics for free. - -## Values - -- `<number>` - - : A decimal number, between the minimum and maximum values. - -## Associated interfaces - -- {{domxref("Element.ariaValueNow")}} - - : The [`ariaValueNow`](/en-US/docs/Web/API/Element/ariaValueNow) property, part of the {{domxref("Element")}} interface, reflects the value of the `aria-valuenow` attribute. -- {{domxref("ElementInternals.ariaValueNow")}} - - : The [`ariaValueNow`](/en-US/docs/Web/API/ElementInternals/ariaValueNow) property, part of the {{domxref("ElementInternals")}} interface, reflects the value of the `aria-valuenow` attribute. - -## Associated roles - -Used in roles: - -- [`meter`](/en-US/docs/Web/Accessibility/ARIA/Roles/meter_role) -- [`scrollbar`](/en-US/docs/Web/Accessibility/ARIA/Roles/scrollbar_role) -- [`separator`](/en-US/docs/Web/Accessibility/ARIA/Roles/separator_role) -- [`slider`](/en-US/docs/Web/Accessibility/ARIA/Roles/slider_role) -- [`spinbutton`](/en-US/docs/Web/Accessibility/ARIA/Roles/spinbutton_role) - -Inherited into roles: - -- [`meter`](/en-US/docs/Web/Accessibility/ARIA/Roles/meter_role) -- [`progressbar`](/en-US/docs/Web/Accessibility/ARIA/Roles/progressbar_role) -- [`scrollbar`](/en-US/docs/Web/Accessibility/ARIA/Roles/scrollbar_role) -- [`slider`](/en-US/docs/Web/Accessibility/ARIA/Roles/slider_role) -- [`spinbutton`](/en-US/docs/Web/Accessibility/ARIA/Roles/spinbutton_role) - -## Specifications - -{{Specifications}} - -## See also - -- [`range` role](/en-US/docs/Web/Accessibility/ARIA/Roles/range_role) -- [`<input type="range>` element `value` attribute](/en-US/docs/Web/HTML/Element/input/range#value) -- [`aria-valuetext`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-valuetext) -- [`aria-valuemax`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-valuemax) -- [`aria-valuemin`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-valuemin). diff --git a/files/en-us/web/accessibility/aria/attributes/aria-valuetext/index.md b/files/en-us/web/accessibility/aria/attributes/aria-valuetext/index.md deleted file mode 100644 index ee9d461683038cb..000000000000000 --- a/files/en-us/web/accessibility/aria/attributes/aria-valuetext/index.md +++ /dev/null @@ -1,58 +0,0 @@ ---- -title: aria-valuetext -slug: Web/Accessibility/ARIA/Attributes/aria-valuetext -page-type: aria-attribute -spec-urls: https://w3c.github.io/aria/#aria-valuetext ---- - -{{AccessibilitySidebar}} - -The `aria-valuetext` attribute defines the human-readable text alternative of `aria-valuenow` for a range widget. - -## Description - -Numbers — even percentages — aren't always user-friendly. Assistive technologies present [`aria-valuenow`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-valuenow) as numeric values. If a progress bar is at 8%, what does that mean? `aria-valuetext` provides a way of presenting the current value in a more user-friendly, human-understandable way. For example, a battery meter value might be conveyed as `aria-valuetext="8% (34 minutes) remaining"`. - -The `aria-valuetext` attribute is used with the `aria-valuenow` attribute, not instead of it, unless that value is not known. - -`aria-valuetext` is only needed when the numeric value of `aria-valuenow` is not meaningful. For example, a range's values are numeric but may be used for non-numeric values, such as college class level. The values of `aria-valuenow` for a 4-year college could range from 1 through 4, which indicate the position of each value in the value space. In this case, the `aria-valuetext` could be one of the strings: "first year", "sophomore", "junior", and "senior". - -If the numeric value is meaningful, such as a spinner with `aria-valuenow="3"` for how many pizza slices you want to order, `aria-valuetext` is not needed. - -When both the `aria-valuetext` and `aria-valuenow` are included, the `aria-valuetext` is announced. When there is no `aria-valuetext` attribute, assistive technologies will announce the `aria-valuenow` attribute for the current value. - -## Values - -- `<string>` - - : A human-readable text alternative of the `aria-valuenow` value. - -## Associated interfaces - -- {{domxref("Element.ariaValueText")}} - - : The [`ariaValueText`](/en-US/docs/Web/API/Element/ariaValueText) property, part of the {{domxref("Element")}} interface, reflects the value of the `aria-valuetext` attribute. -- {{domxref("ElementInternals.ariaValueText")}} - - : The [`ariaValueText`](/en-US/docs/Web/API/ElementInternals/ariaValueText) property, part of the {{domxref("ElementInternals")}} interface, reflects the value of the `aria-valuetext` attribute. - -## Associated roles - -Used in roles: - -- [`range`](/en-US/docs/Web/Accessibility/ARIA/Roles/range_role) -- [`separator`](/en-US/docs/Web/Accessibility/ARIA/Roles/separator_role) -- [`spinbutton`](/en-US/docs/Web/Accessibility/ARIA/Roles/spinbutton_role) - -Inherited into roles: - -- [`meter`](/en-US/docs/Web/Accessibility/ARIA/Roles/meter_role) -- [`progressbar`](/en-US/docs/Web/Accessibility/ARIA/Roles/progressbar_role) -- [`scrollbar`](/en-US/docs/Web/Accessibility/ARIA/Roles/scrollbar_role) -- [`slider`](/en-US/docs/Web/Accessibility/ARIA/Roles/slider_role) -- [`spinbutton`](/en-US/docs/Web/Accessibility/ARIA/Roles/spinbutton_role) - -## Specifications - -{{Specifications}} - -## See also - -- [`aria-valuenow`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-valuenow) diff --git a/files/en-us/web/accessibility/aria/attributes/index.md b/files/en-us/web/accessibility/aria/attributes/index.md deleted file mode 100644 index 997672569094318..000000000000000 --- a/files/en-us/web/accessibility/aria/attributes/index.md +++ /dev/null @@ -1,118 +0,0 @@ ---- -title: ARIA states and properties -slug: Web/Accessibility/ARIA/Attributes -page-type: landing-page ---- - -{{AccessibilitySidebar}} - -This page lists reference pages covering all the <abbr>WAI-ARIA</abbr> attributes discussed on MDN. - -<abbr>ARIA</abbr> attributes enable modifying an element's states and properties as defined in the accessibility tree. - -> [!NOTE] -> ARIA only modifies the accessibility tree, modifying how assistive technology presents the content to your users. ARIA doesn't change anything about an element's function or behavior. When not using semantic HTML elements for their intended purpose and default functionality, you must use JavaScript to manage behavior, focus, and ARIA states. - -## ARIA attribute types - -There are 4 categories of ARIA states and properties: - -1. ### Widget attributes - - - [`aria-autocomplete`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-autocomplete) - - [`aria-checked`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-checked) - - [`aria-disabled`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-disabled) - - [`aria-errormessage`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-errormessage) - - [`aria-expanded`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-expanded) - - [`aria-haspopup`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-haspopup) - - [`aria-hidden`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-hidden) - - [`aria-invalid`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-invalid) - - [`aria-label`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-label) - - [`aria-level`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-level) - - [`aria-modal`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-modal) - - [`aria-multiline`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-multiline) - - [`aria-multiselectable`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-multiselectable) - - [`aria-orientation`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-orientation) - - [`aria-placeholder`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-placeholder) - - [`aria-pressed`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-pressed) - - [`aria-readonly`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-readonly) - - [`aria-required`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-required) - - [`aria-selected`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-selected) - - [`aria-sort`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-sort) - - [`aria-valuemax`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-valuemax) - - [`aria-valuemin`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-valuemin) - - [`aria-valuenow`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-valuenow) - - [`aria-valuetext`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-valuetext) - -2. ### Live region attributes - - - [`aria-busy`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-busy) - - [`aria-live`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-live) - - [`aria-relevant`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-relevant) - - [`aria-atomic`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-atomic) - -3. ### Drag-and-Drop attributes - - - [`aria-dropeffect`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-dropeffect) - - [`aria-grabbed`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-grabbed) - -4. ### Relationship attributes - - - [`aria-activedescendant`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-activedescendant) - - [`aria-colcount`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-colcount) - - [`aria-colindex`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-colindex) - - [`aria-colspan`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-colspan) - - [`aria-controls`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-controls) - - [`aria-describedby`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-describedby) - - [`aria-description`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-description) - - [`aria-details`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-details) - - [`aria-errormessage`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-errormessage) - - [`aria-flowto`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-flowto) - - [`aria-labelledby`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-labelledby) - - [`aria-owns`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-owns) - - [`aria-posinset`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-posinset) - - [`aria-rowcount`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-rowcount) - - [`aria-rowindex`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-rowindex) - - [`aria-rowspan`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-rowspan) - - [`aria-setsize`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-setsize) - -## Global ARIA attributes - -Some states and properties apply to all HTML elements regardless of whether an ARIA role is applied. These are defined as "Global" attributes. Global states and properties are supported by all roles and base markup elements. - -Many of the above attributes are global, meaning they can be included on any element unless specifically disallowed: - -- [`aria-atomic`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-atomic) -- [`aria-busy`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-busy) -- [`aria-controls`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-controls) -- [`aria-current`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-current) -- [`aria-describedby`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-describedby) -- [`aria-description`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-description) -- [`aria-details`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-details) -- [`aria-disabled`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-disabled) -- [`aria-dropeffect`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-dropeffect) -- [`aria-errormessage`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-errormessage) -- [`aria-flowto`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-flowto) -- [`aria-grabbed`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-grabbed) -- [`aria-haspopup`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-haspopup) -- [`aria-hidden`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-hidden) -- [`aria-invalid`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-invalid) -- [`aria-keyshortcuts`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-keyshortcuts) -- [`aria-label`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-label) -- [`aria-labelledby`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-labelledby) -- [`aria-live`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-live) -- [`aria-owns`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-owns) -- [`aria-relevant`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-relevant) -- [`aria-roledescription`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-roledescription) - -By "specifically disallowed," all the above attributes are global except for the `aria-label` and `aria-labelledby` properties, which are not allowed on elements with role [`presentation`](/en-US/docs/Web/Accessibility/ARIA/Roles/presentation_role) nor its synonym [`none`](/en-US/docs/Web/Accessibility/ARIA/Roles/none_role) role. - -## States and properties defined on MDN - -The following are the reference pages covering the <abbr>WAI-ARIA</abbr> states and properties discussed on <abbr>MDN</abbr>. - -{{SubpagesWithSummaries}} - -## See also - -- [Using ARIA: roles, states, and properties](/en-US/docs/Web/Accessibility/ARIA/ARIA_Techniques) diff --git a/files/en-us/web/accessibility/aria/guides/index.md b/files/en-us/web/accessibility/aria/guides/index.md new file mode 100644 index 000000000000000..a9fd68a46596a7c --- /dev/null +++ b/files/en-us/web/accessibility/aria/guides/index.md @@ -0,0 +1,26 @@ +--- +title: ARIA guides +slug: Web/Accessibility/ARIA/Guides +page-type: landing-page +sidebar: accessibilitysidebar +--- + +Accessible Rich Internet Applications (**ARIA**) define ways to make the web more accessible to people with disabilities. +This page lists the guides that you can use to help improve the accessibility of web page features such as tables, forms, and keyboard-navigation. + +{{SubPagesWithSummaries}} + +## See also + +- [Designing accessible forms](https://www.w3.org/WAI/tutorials/forms/) +- [Understanding WAI-ARIA basics](/en-US/docs/Learn_web_development/Core/Accessibility/WAI-ARIA_basics) +- [Creating keyboard-navigable JavaScript widgets](/en-US/docs/Web/Accessibility/Guides/Keyboard-navigable_JavaScript_widgets) +- [Using ARIA for labels with embedded fields inside them](/en-US/docs/Web/Accessibility/ARIA/Guides/Multipart_labels) +- [Managing focus in composite widgets](https://www.w3.org/WAI/ARIA/apg/practices/keyboard-interface/) (`aria-activedescendant` vs. roving tabindex) +- [Testing ARIA](https://www.w3.org/WAI/test-evaluate/) +- [Displaying accessible tables](https://www.w3.org/WAI/tutorials/tables/) +- [Labeling widgets](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-label) +- [Landmark roles](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/landmark_role) +- [ARIA live regions](/en-US/docs/Web/Accessibility/ARIA/Guides/Live_regions) +- [HTML Drag and Drop API](/en-US/docs/Web/API/HTML_Drag_and_Drop_API) +- [ARIA: presentation role](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/presentation_role) diff --git a/files/en-us/web/accessibility/aria/guides/live_regions/index.md b/files/en-us/web/accessibility/aria/guides/live_regions/index.md new file mode 100644 index 000000000000000..8eaca2b4d573c0a --- /dev/null +++ b/files/en-us/web/accessibility/aria/guides/live_regions/index.md @@ -0,0 +1,261 @@ +--- +title: ARIA live regions +slug: Web/Accessibility/ARIA/Guides/Live_regions +page-type: guide +sidebar: accessibilitysidebar +--- + +Using JavaScript, it is possible to dynamically change parts of a page without requiring the entire page to reload — for instance, to update a list of search results on the fly, or to display a discreet alert or notification which does not require user interaction. While these changes are usually visually apparent to users who can see the page, they may not be obvious to users of assistive technologies. ARIA live regions fill this gap and provide a way to programmatically expose dynamic content changes in a way that can be announced by assistive technologies. + +> [!NOTE] +> Assistive technologies will generally only announce _dynamic_ changes in the content of a live region. +> Including an `aria-live` attribute or a specialized live region `role` (such as [`role="status"`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/status_role)) on the element you want to announce changes to works as long as you add the attribute before the changes occur — either in the original markup, or dynamically using JavaScript. Start with an empty live region, then – in a separate step – change the content inside the region. +> While not explicitly documented in the specification, browsers/assistive technologies do include special handling for [`role="alert"`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/alert_role): in most cases, the content inside `role="alert"` regions is announced, even when the region (which already contains the notification/message) is present in the initial markup of the page, or injected dynamically into the page. However, note that `role="alert"` regions are – depending on the specific browser/assistive technology combination – automatically prefixed with "Alert" when they are announced. + +## Live regions + +Dynamic content which updates without a page reload is generally either a region or a widget. Simple content changes which are not interactive should be marked as live regions. A live region is explicitly denoted using the `aria-live` attribute. + +**`aria-live`**: The `aria-live=POLITENESS_SETTING` is used to set the priority with which screen reader should treat updates to live regions - the possible settings are: `off`, `polite` or `assertive`. This attribute is by far the most important. + +Normally, only `aria-live="polite"` is used. Any region which receives updates that are important for the user to receive, but not so rapid as to be annoying, should receive this attribute. The screen reader will speak changes whenever the user is idle. + +`aria-live="assertive"` should only be used for time-sensitive/critical notifications that absolutely require the user's immediate attention. Generally, a change to an assertive live region will interrupt any announcement a screen reader is currently making. As such, it can be extremely annoying and disruptive and should only be used sparingly. + +Unintuitively, `aria-live="off"` does not indicate that changes should not be announced. When an element has `aria-live="off"` (or has a `role` with this implicit value, such as `role="marquee"` or `role="timer"`), changes to the element's content are only supposed to be announced when focus is on, or inside, the element. + +### Basic example: Dropdown box updates useful onscreen information + +A website specializing in providing information about planets provides a dropdown box. When a planet is selected from the dropdown, a region on the page is updated with information about the selected planet. + +```html +<fieldset> + <legend>Planet information</legend> + <label for="planetsSelect">Planet:</label> + <select id="planetsSelect" aria-controls="planetInfo"> + <option value="">Select a planet…</option> + <option value="mercury">Mercury</option> + <option value="venus">Venus</option> + <option value="earth">Earth</option> + <option value="mars">Mars</option> + </select> + <button id="renderPlanetInfoButton">Go</button> +</fieldset> + +<div role="region" id="planetInfo" aria-live="polite"> + <h2 id="planetTitle">No planet selected</h2> + <p id="planetDescription">Select a planet to view its description</p> +</div> + +<p> + <small> + Information from + <a href="https://en.wikipedia.org/wiki/Solar_System">Wikipedia</a> + </small> +</p> +``` + +```js +const PLANETS_INFO = { + mercury: { + title: "Mercury", + description: + "Mercury is the smallest and innermost planet in the Solar System. It is named after the Roman deity Mercury, the messenger to the gods.", + }, + + venus: { + title: "Venus", + description: + "Venus is the second planet from the Sun. It is named after the Roman goddess of love and beauty.", + }, + + earth: { + title: "Earth", + description: + "Earth is the third planet from the Sun and the only object in the Universe known to harbor life.", + }, + + mars: { + title: "Mars", + description: + 'Mars is the fourth planet from the Sun and the second-smallest planet in the Solar System after Mercury. In English, Mars carries a name of the Roman god of war, and is often referred to as the "Red Planet".', + }, +}; + +function renderPlanetInfo(planet) { + const planetTitle = document.querySelector("#planetTitle"); + const planetDescription = document.querySelector("#planetDescription"); + + if (planet in PLANETS_INFO) { + planetTitle.textContent = PLANETS_INFO[planet].title; + planetDescription.textContent = PLANETS_INFO[planet].description; + } else { + planetTitle.textContent = "No planet selected"; + planetDescription.textContent = "Select a planet to view its description"; + } +} + +const renderPlanetInfoButton = document.querySelector( + "#renderPlanetInfoButton", +); + +renderPlanetInfoButton.addEventListener("click", (event) => { + const planetsSelect = document.querySelector("#planetsSelect"); + const selectedPlanet = + planetsSelect.options[planetsSelect.selectedIndex].value; + + renderPlanetInfo(selectedPlanet); +}); +``` + +{{EmbedLiveSample('Basic_example_Dropdown_box_updates_useful_onscreen_information', '', 350)}} + +As the user selects a new planet, the information in the live region will be announced. Because the live region has `aria-live="polite"`, the screen reader will wait until the user pauses before announcing the update. Thus, moving down in the list and selecting another planet will not announce updates in the live region. Updates in the live region will only be announced for the planet finally chosen. + +Here is a screenshot of VoiceOver on Mac announcing the update (via subtitles) to the live region: + +![A screenshot of VoiceOver on Mac announcing the update to a live region. Subtitles are shown in the picture.](web_accessibility_aria_aria_live_regions.png) + +## Roles with implicit live region attributes + +Elements with the following [`role="…"`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles) values act as live regions by default: + +<table style="width: 100%;"> + <thead> + <tr> + <th scope="col">Role</th> + <th scope="col">Description</th> + <th scope="col">Compatibility Notes</th> + </tr> + </thead> + <tbody> + <tr> + <td>log</td> + <td>Chat, error, game or other type of log</td> + <td>To maximize compatibility, add a redundant <code>aria-live="polite"</code> when using this role.</td> + </tr> + <tr> + <td>status</td> + <td>A status bar or area of the screen that provides an updated status of some kind. Screen reader users have a special command to read the current status.</td> + <td>To maximize compatibility, add a redundant <code>aria-live="polite"</code> when using this role.</td> + </tr> + <tr> + <td>alert</td> + <td>Error or warning message that flashes on the screen. Alerts are particularly important for client side validation notices to users. <a href="https://www.w3.org/WAI/ARIA/apg/example-index/alert/alert.html" class="external" rel="noopener">Alert Example.</a></td> + <td>To maximize compatibility, some people recommend adding a redundant <code>aria-live="assertive"</code> when using this role. However, adding both <code>aria-live</code> and <code>role="alert"</code> causes double speaking issues in VoiceOver on iOS.</td> + </tr> + <tr> + <td>progressbar</td> + <td>A hybrid between a widget and a live region. Use this with <code>aria-valuemin</code>, <code>aria-valuenow</code> and <code>aria-valuemax</code>. (TBD: add more info here).</td> + <td></td> + </tr> + <tr> + <td>marquee</td> + <td>Text which scrolls, such as a stock ticker.</td> + <td></td> + </tr> + <tr> + <td>timer</td> + <td>Any kind of timer or clock, such as a countdown timer or stopwatch readout.</td> + <td></td> + </tr> + </tbody> +</table> + +## Additional live region attributes + +Live Regions are well supported. The Paciello Group, in 2014, posted [information about the state of the support of Live Regions](https://www.tpgi.com/screen-reader-support-aria-live-regions/). Paul J. Adam has researched [the support of `aria-atomic` and `aria-relevant`](https://pauljadam.com/demos/aria-atomic-relevant.html) in particular. + +1. **`aria-atomic`**: The `aria-atomic=BOOLEAN` is used to set whether or not the screen reader should always present the live region as a whole, even if only part of the region changes. The possible settings are: `false` or `true`. The default setting is `false`. +2. [**`aria-relevant`**](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-relevant) + + : The `aria-relevant=[LIST_OF_CHANGES]` is used to set what types of changes are relevant to a live region. The possible settings are one or more of: `additions`, `removals`, `text`, `all`. The default setting is: `additions text`. + +### Basic examples: `aria-atomic` + +As an illustration of `aria-atomic`, consider a site with a basic clock, showing hours and minutes. The clock is updated each minute, with the new remaining time overwriting the current content. + +```html +<div id="clock" role="timer" aria-live="polite"> + <span id="clock-hours"></span> + <span id="clock-mins"></span> +</div> +``` + +```js +/* basic JavaScript to update the clock */ +function updateClock() { + const now = new Date(); + document.getElementById("clock-hours").textContent = now.getHours(); + document.getElementById("clock-mins").textContent = + `0${now.getMinutes()}`.substr(-2); +} + +/* first run */ +updateClock(); + +/* update every minute */ +setInterval(updateClock, 60000); +``` + +The first time the function executes, the entirety of the string that is added will be announced. On subsequent calls, only the parts of the content that changed compared to the previous content will be announced. For instance, when the clock changes from "17:33" to "17:34", assistive technologies will only announce "34", which won't be very useful to users. + +One way around this would be to first clear all the contents of the live region (in this case, set the `innerHTML` of both `<span id="clock-hours">` and `<span id="clock-mins">` to be empty), and then inject the new content. However, this can sometimes be unreliable, as it's dependent on the exact timing of these two updates. + +`aria-atomic="true"` ensures that each time the live region is updated, the entirety of the content is announced in full (e.g., "17:34"). + +```html +<div id="clock" role="timer" aria-live="polite" aria-atomic="true">…</div> +``` + +Another example of `aria-atomic` - an update/notification made as a result of a user action. + +```html +<div id="date-input"> + <label for="year">Year:</label> + <input type="text" id="year" value="1990" /> +</div> + +<div id="date-output" aria-atomic="true" aria-live="polite"> + The set year is: + <span id="year-output">1990</span> +</div> +``` + +```js +function change(event) { + const yearOut = document.getElementById("year-output"); + + switch (event.target.id) { + case "year": + yearOut.textContent = event.target.value; + break; + } +} + +document.getElementById("year").addEventListener("blur", change); +``` + +Without `aria-atomic="true"` the screen reader announces only the changed value of year. With `aria-atomic="true"`, the screen reader announces "The set year is: _changed value_" + +### Basic example: `aria-relevant` + +With `aria-relevant` you can specify which types of changes/updates to a live region should be announced. + +As an example, consider a chat site that wants to display a list of users currently logged in. Rather than just announcing the users that are currently logged in, we also want to trigger an announcement specifically when a user is _removed_ from the list. We can achieve this by specifying `aria-relevant="additions removals"`. + +```html +<ul id="roster" aria-live="polite" aria-relevant="additions removals"> + <!-- use JavaScript to add and remove users here --> +</ul> +``` + +Breakdown of ARIA live properties: + +- `aria-live="polite"` indicates that the screen reader should wait until the user is idle before presenting updates to the user. This is the most commonly used value, as interrupting the user with "assertive" might interrupt their flow. +- `aria-atomic` is not set (`false` by default) so that only the added or removed users should be spoken and not the entire roster each time. +- `aria-relevant="additions removals"` ensures that both users added or removed to the roster will be spoken. + +## See also + +- [ARIA roles](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles) diff --git a/files/en-us/web/accessibility/aria/aria_live_regions/web_accessibility_aria_aria_live_regions.png b/files/en-us/web/accessibility/aria/guides/live_regions/web_accessibility_aria_aria_live_regions.png similarity index 100% rename from files/en-us/web/accessibility/aria/aria_live_regions/web_accessibility_aria_aria_live_regions.png rename to files/en-us/web/accessibility/aria/guides/live_regions/web_accessibility_aria_aria_live_regions.png diff --git a/files/en-us/web/accessibility/aria/guides/multipart_labels/index.md b/files/en-us/web/accessibility/aria/guides/multipart_labels/index.md new file mode 100644 index 000000000000000..c073f3e0f332628 --- /dev/null +++ b/files/en-us/web/accessibility/aria/guides/multipart_labels/index.md @@ -0,0 +1,54 @@ +--- +title: "Multipart labels: Using ARIA for labels with embedded fields inside them" +short-title: Using ARIA for labels with embedded fields +slug: Web/Accessibility/ARIA/Guides/Multipart_labels +page-type: guide +sidebar: accessibilitysidebar +--- + +## Problem + +You have a form where you ask your user a question, but the answer is mentioned in the question itself. A classic example we all know from our browser settings is the setting "Delete history after x days". "Delete history after" is to the left of the textbox, x is the number, for example 21, and the word "days" follows the textbox, forming a sentence that is easy to understand. + +If you're using a screen reader, have you noticed that, when you go to this setting in Firefox, it tells you "Delete history after 21 days"?, followed by the announcement that you're in a textbox, and that it contains the number 21. Isn't that cool? You do not need to navigate around to find out the unit. "Days" could easily be "months" or "years", and in many ordinary dialogs, there is no way to find this out other than navigating around with screen reviewing commands. + +The solution is in an ARIA attribute called `aria-labelledby`. Its parameter is a string that consists of the IDs of the HTML elements you want to concatenate into a single accessible name. + +Both `aria-labelledby` and `aria-describedby` are specified on the form element that is to be labelled, for example an `<input>` In both cases, the label for/label control bindings that may also exist are overridden by `aria-labelledby`. If on an HTML page you provide `aria-labelledby`, you should also provide a label for construct to also support older browsers that do not have ARIA support yet. With Firefox 3, your visually impaired users will automatically get better accessibility from the new attribute, but the users of older browsers are not left in the dark this way. + +### Example + +{{ EmbedLiveSample("Example") }} + +```css hidden +body { + margin: 1rem; +} +``` + +```html +<input + aria-labelledby="labelShutdown shutdownTime shutdownUnit" + type="checkbox" /> + +<span id="labelShutdown">Shut down computer after</span> + +<input + aria-labelledby="labelShutdown shutdownTime shutdownUnit" + id="shutdownTime" + type="text" + value="10" /> + +<span id="shutdownUnit"> minutes</span> +``` + +## A Note for JAWS 8 users + +JAWS 8.0 has its own logic to find labels, causing it to always override the accessibleName the textbox of an HTML document gets. With JAWS 8, I have not found a way to make it to accept the label from the example above. But NVDA and Window-Eyes do it just fine, and Orca on Linux also has no problems. + +> [!NOTE] +> TBD: add more compatibility info + +## Can this be done without ARIA? + +Community member Ben Millard has pointed out in a blog post that [controls can be embedded in labels as shown in the above example using HTML 4](https://projectcerbera.com/blog/2008/03/#day24), by embedding the input into the label. Thanks for that info, Ben! It is very useful and shows that some techniques that have been available for years escape even the gurus sometimes. This technique works in Firefox; however, it doesn't currently work in many other browsers, including IE. For labels with embedded form controls, using `aria-labelledby` is still the best approach. diff --git a/files/en-us/web/accessibility/aria/guides/screen_reader_implementors/index.md b/files/en-us/web/accessibility/aria/guides/screen_reader_implementors/index.md new file mode 100644 index 000000000000000..f054fb7bb6dbf13 --- /dev/null +++ b/files/en-us/web/accessibility/aria/guides/screen_reader_implementors/index.md @@ -0,0 +1,27 @@ +--- +title: ARIA Screen Reader Implementors Guide +short-title: Screen reader implementors guide +slug: Web/Accessibility/ARIA/Guides/Screen_Reader_Implementors +page-type: guide +sidebar: accessibilitysidebar +--- + +## Live Regions + +This is just a guide. Live region markup is a complex area which is somewhat open to interpretation. The following is intended to provide implementation guidance that respects screen readers developers' need to try different things. The intention is to strike a balance between providing useful guidance on how to use the markup's intended meaning while supporting live regions as an area for screen readers to innovate and compete. + +### Interpreting WAI-ARIA live region markup + +1. Live changes are hints: in general live region markup is provided by the author as hints, and the assistive technology may allow for global, site or even region-specific settings, as well as heuristics to help with live changes on pages that have no WAI-ARIA hints. +2. Optionally, create a second, additional queue if the user configures a second hardware channel: If there are two channels for presentation (e.g., text to speech and a Braille display), then two queues can be maintained to allow for parallel presentation. The channels could be user configured for presenting live regions based on role or politeness. +3. Busy regions: Any changes in a region marked with aria-busy="true" should not be added to the queue until that attribute is cleared. +4. Politeness (`aria-live` or from [role](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles)) takes first precedence,: items should be added to the queue based on their politeness level from the `aria-live` property or inherited from the `role` (e.g., [role="log"](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/log_role) is polite by default). Assertive items are first then politeness level. Alternatively, implementations may choose to have a policy of clearing more polite items, e.g., assertive items clear any polite items from the queue. +5. Time takes second precedence: Prioritize items with the same politeness level according to when the event occurs (earlier events come first). Present items of the same politeness level in the order of what occurred first. +6. Atomic (`aria-atomic="true"`) regions with multiple changes should not be presented twice with the same content. As a new event for an atomic region is added to the queue remove an earlier event for the same region. It is probably desirable to have at least a tiny timeout before presenting atomic region changes, in order to avoid presenting the region twice for two changes that occur quickly one after the other. +7. Include labels when presenting changes: if the change occurs in something with a semantic label of some kind, speak the label. This is particularly important for changes in data cells, where the column and row headers provide important contextual information. + +### Ideas for Settings and Heuristics + +1. Allow for a different voice (in text-to-speech) or other varying presentational characteristics to set live changes apart. +2. When no WAI-ARIA markup is present, automatically present some changes unless the user configures all live changes to off. For example, automatically speak changes that are caused by the user's own input, as part of the context of that input. +3. Allow global settings to turn off the presentation of live changes, present all live changes, use markup, or be "smart" (use heuristics) diff --git a/files/en-us/web/accessibility/aria/guides/techniques/index.md b/files/en-us/web/accessibility/aria/guides/techniques/index.md new file mode 100644 index 000000000000000..056e585b640a9e5 --- /dev/null +++ b/files/en-us/web/accessibility/aria/guides/techniques/index.md @@ -0,0 +1,165 @@ +--- +title: "Using ARIA: Roles, states, and properties" +slug: Web/Accessibility/ARIA/Guides/Techniques +page-type: guide +sidebar: accessibilitysidebar +--- + +ARIA defines semantics that can be applied to elements, with these divided into **roles** (defining a type of user interface element) and **states** and **properties** that are supported by a role. Authors must assign an ARIA role and the appropriate states and properties to an element during its life-cycle, unless the element already has appropriate ARIA semantics (via use of an appropriate HTML element). Addition of ARIA semantics only exposes extra information to a browser's accessibility API, and does not affect a page's DOM. + +## Roles + +### Widget roles + +- [`button`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/button_role) +- [`checkbox`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/checkbox_role) +- [`gridcell`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/gridcell_role) +- [`link`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/link_role) +- [`menuitem`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/menuitem_role) +- [`menuitemcheckbox`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/menuitemcheckbox_role) +- [`menuitemradio`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/menuitemradio_role) +- [`option`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/option_role) +- [`progressbar`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/progressbar_role) +- [`radio`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/radio_role) +- [`scrollbar`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/scrollbar_role) +- [`searchbox`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/searchbox_role) +- [`separator`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/separator_role) (when focusable) +- [`slider`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/slider_role) +- [`spinbutton`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/spinbutton_role) +- [`switch`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/switch_role) +- [`tab`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/tab_role) +- [`tabpanel`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/tabpanel_role) +- [`textbox`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/textbox_role) +- [`treeitem`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/treeitem_role) + +### Composite roles + +The techniques below describe each composite role as well as their required and optional child roles. + +- [`combobox`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/combobox_role) +- [`grid`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/grid_role) (including [`row`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/row_role), [`gridcell`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/gridcell_role), [`rowheader`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/rowheader_role), [`columnheader`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/columnheader_role) roles) +- [`listbox`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/listbox_role) (including [`option`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/option_role) role) +- [`menu`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/menu_role) +- [`menubar`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/menubar_role) +- [`radiogroup`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/radiogroup_role) (see [`radio` role](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/radio_role)) +- [`tablist`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/tablist_role) (including [`tab`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/tab_role) and [`tabpanel`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/tabpanel_role) roles) +- [`tree`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/tree_role) +- [`treegrid`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/treegrid_role) + +### Document structure roles + +- [`application`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/application_role) +- [`article`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/article_role) +- [`cell`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/cell_role) +- [`columnheader`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/columnheader_role) +- [`definition`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/definition_role) +- [`directory`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/directory_role) +- [`document`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/document_role) +- [`feed`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/feed_role) +- [`figure`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/figure_role) +- [`group`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/group_role) +- [`heading`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/heading_role) +- [`img`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/img_role) +- [`list`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/list_role) +- [`listitem`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/listitem_role) +- [`math`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/math_role) +- [`none`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/none_role) +- [`note`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/note_role) +- [`presentation`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/presentation_role) +- [`row`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/row_role) +- [`rowgroup`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/rowgroup_role) +- [`rowheader`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/rowheader_role) +- [`separator`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/separator_role) +- [`table`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/table_role) +- [`term`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/term_role) +- [`toolbar`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/toolbar_role) +- [`tooltip`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/tooltip_role) + +### Landmark roles + +- [`banner`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/banner_role) +- [`complementary`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/complementary_role) +- [`contentinfo`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/contentinfo_role) +- [`form`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/form_role) +- [`main`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/main_role) +- [`navigation`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/navigation_role) +- [`region`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/region_role) +- [`search`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/search_role) + +### Live Region Roles + +- [`alert`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/alert_role) +- [`log`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/log_role) +- [`marquee`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/marquee_role) +- [`status`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/status_role) +- [`timer`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/timer_role) + +### Window Roles + +- [`alertdialog`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/alertdialog_role) +- [`dialog`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/dialog_role) + +## States and properties + +### Widget attributes + +- [`aria-autocomplete`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-autocomplete) +- [`aria-checked`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-checked) +- [`aria-current`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-current) +- [`aria-disabled`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-disabled) +- [`aria-errormessage`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-errormessage) +- [`aria-expanded`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-expanded) +- [`aria-haspopup`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-haspopup) +- [`aria-hidden`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-hidden) +- [`aria-invalid`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-invalid) +- [`aria-label`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-label) +- [`aria-level`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-level) +- [`aria-modal`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-modal) +- [`aria-multiline`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-multiline) +- [`aria-multiselectable`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-multiselectable) +- [`aria-orientation`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-orientation) +- [`aria-placeholder`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-placeholder) +- [`aria-pressed`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-pressed) +- [`aria-readonly`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-readonly) +- [`aria-required`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-required) +- [`aria-selected`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-selected) +- [`aria-sort`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-sort) +- [`aria-valuemax`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-valuemax) +- [`aria-valuemin`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-valuemin) +- [`aria-valuenow`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-valuenow) +- [`aria-valuetext`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-valuetext) + +### Live region attributes + +- [`aria-live`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-live) +- [`aria-relevant`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-relevant) +- [`aria-atomic`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-atomic) +- [`aria-busy`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-busy) + +### Drag &amp; drop attributes + +- [`aria-dropeffect`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-dropeffect) {{deprecated_inline}} +- [`aria-grabbed`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-grabbed) {{deprecated_inline}} + +### Relationship attributes + +- [`aria-activedescendant`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-activedescendant) +- [`aria-colcount`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-colcount) +- [`aria-colindex`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-colindex) +- [`aria-colspan`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-colspan) +- [`aria-controls`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-controls) +- [`aria-describedby`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-describedby) +- [`aria-details`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-details) +- [`aria-errormessage`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-errormessage) +- [`aria-flowto`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-flowto) +- [`aria-labelledby`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-labelledby) +- [`aria-owns`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-owns) +- [`aria-posinset`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-posinset) +- [`aria-rowcount`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-rowcount) +- [`aria-rowindex`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-rowindex) +- [`aria-rowspan`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-rowspan) +- [`aria-setsize`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-setsize) + +### MicrosoftEdge-specific properties + +- `x-ms-aria-flowfrom` {{Non-standard_Inline}} diff --git a/files/en-us/web/accessibility/aria/how_to/file_aria-related_bugs/index.md b/files/en-us/web/accessibility/aria/how_to/file_aria-related_bugs/index.md new file mode 100644 index 000000000000000..4f4f2f34c098908 --- /dev/null +++ b/files/en-us/web/accessibility/aria/how_to/file_aria-related_bugs/index.md @@ -0,0 +1,66 @@ +--- +title: How to file ARIA-related bugs +slug: Web/Accessibility/ARIA/How_to/File_ARIA-related_bugs +page-type: guide +sidebar: accessibilitysidebar +--- + +The state of ARIA technology has always depended on the community. If you notice an implementation issue, please take a little time and let the developers know. Here's where to file bugs: + +### Screen Readers + +<table style="width: 100%;"> + <thead> + <tr> + <th>Software</th> + <th>Where to file</th> + <th>Notes</th> + </tr> + </thead> + <tbody> + <tr> + <td><a href="https://www.freedomscientific.com/products/software/jaws/">Freedom Scientific JAWS</a></td> + <td><a href="https://support.freedomscientific.com/Forms/TechSupport">JAWS technical support form</a></td> + <td></td> + </tr> + <tr> + <td><a href="https://www.nvaccess.org/">Non Visual Desktop Access (NVDA)</a></td> + <td><a href="https://github.com/nvaccess/nvda">File NVDA bugs</a></td> + <td>Discuss NVDA issues</td> + </tr> + </tbody> + </table> + +### Browsers + +<table style="width: 100%;"> + <thead> + <tr> + <th>Software</th> + <th>Where to file</th> + <th>Notes</th> + </tr> + </thead> + <tbody> + <tr> + <td>Apple Safari</td> + <td><a href="https://www.webkit.org/reporting-bugs/">File WebKit.org bugs</a></td> + <td></td> + </tr> + <tr> + <td>Google Chrome</td> + <td><a href="https://issues.chromium.org/issues">File Chromium bugs</a></td> + <td></td> + </tr> + <tr> + <td>Mozilla Firefox</td> + <td><a href="https://bugzilla.mozilla.org/">File Firefox bugs </a></td> + <td>Use Component: Disability Access APIs</td> + </tr> + <tr> + <td>Opera</td> + <td><a href="https://bugs.opera.com/wizard/">File Opera bugs</a></td> + <td>Use [ARIA] in the summary field</td> + </tr> + </tbody> +</table> diff --git a/files/en-us/web/accessibility/aria/how_to/index.md b/files/en-us/web/accessibility/aria/how_to/index.md new file mode 100644 index 000000000000000..58f80dff585da65 --- /dev/null +++ b/files/en-us/web/accessibility/aria/how_to/index.md @@ -0,0 +1,10 @@ +--- +title: How to +slug: Web/Accessibility/ARIA/How_to +page-type: listing-page +sidebar: accessibilitysidebar +--- + +How-to guides for Accessible Rich Internet Applications (ARIA). + +{{SubPagesWithSummaries}} diff --git a/files/en-us/web/accessibility/aria/how_to_file_aria-related_bugs/index.md b/files/en-us/web/accessibility/aria/how_to_file_aria-related_bugs/index.md deleted file mode 100644 index 653a0cf84a46326..000000000000000 --- a/files/en-us/web/accessibility/aria/how_to_file_aria-related_bugs/index.md +++ /dev/null @@ -1,72 +0,0 @@ ---- -title: How to file ARIA-related bugs -slug: Web/Accessibility/ARIA/How_to_file_ARIA-related_bugs -page-type: guide ---- - -{{AccessibilitySidebar}} - -The state of ARIA technology has always depended on the community. If you notice an implementation issue, please take a little time and let the developers know. Here's where to file bugs: - -### Screen Readers - -<table style="width: 100%;"> - <thead> - <tr> - <th>Software</th> - <th>Where to file</th> - <th>Notes</th> - </tr> - </thead> - <tbody> - <tr> - <td><a href="https://www.freedomscientific.com/products/software/jaws/">Freedom Scientific JAWS</a></td> - <td><a href="https://support.freedomscientific.com/Forms/TechSupport">JAWS technical support form</a></td> - <td></td> - </tr> - <tr> - <td><a href="/en-US/docs/Mozilla/Developer_guide/Inner_and_outer_windows">GW Micro Window Eyes</a></td> - <td><a href="mailto:support@gwmicro.com">Window-Eyes comments, questions, and feedback</a></td> - <td></td> - </tr> - <tr> - <td><a href="https://www.nvaccess.org/">Non Visual Desktop Access (NVDA)</a></td> - <td><a href="https://github.com/nvaccess/nvda">File NVDA bugs</a></td> - <td>Discuss NVDA issues</td> - </tr> - </tbody> - </table> - -### Browsers - -<table style="width: 100%;"> - <thead> - <tr> - <th>Software</th> - <th>Where to file</th> - <th>Notes</th> - </tr> - </thead> - <tbody> - <tr> - <td>Apple Safari</td> - <td><a href="https://www.webkit.org/reporting-bugs/">File WebKit.org bugs</a></td> - <td></td> - </tr> - <tr> - <td>Google Chrome</td> - <td><a href="https://issues.chromium.org/issues">File Chromium bugs</a></td> - <td></td> - </tr> - <tr> - <td>Mozilla Firefox</td> - <td><a href="https://bugzilla.mozilla.org/">File Firefox bugs </a></td> - <td>Use Component: Disability Access APIs</td> - </tr> - <tr> - <td>Opera</td> - <td><a href="https://bugs.opera.com/wizard/">File Opera bugs</a></td> - <td>Use [ARIA] in the summary field</td> - </tr> - </tbody> -</table> diff --git a/files/en-us/web/accessibility/aria/index.md b/files/en-us/web/accessibility/aria/index.md index b959c7eb5133188..8cdc80854355791 100644 --- a/files/en-us/web/accessibility/aria/index.md +++ b/files/en-us/web/accessibility/aria/index.md @@ -2,16 +2,17 @@ title: ARIA slug: Web/Accessibility/ARIA page-type: landing-page +sidebar: accessibilitysidebar --- -{{AccessibilitySidebar}} +Accessible Rich Internet Applications **(<abbr>ARIA</abbr>)** is a set of [roles](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles) and [attributes](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes) that define ways to make web content and web applications (especially those developed with JavaScript) more accessible to people with disabilities. -Accessible Rich Internet Applications **(<abbr>ARIA</abbr>)** is a set of [roles](/en-US/docs/Web/Accessibility/ARIA/Roles) and [attributes](/en-US/docs/Web/Accessibility/ARIA/Attributes) that define ways to make web content and web applications (especially those developed with JavaScript) more accessible to people with disabilities. +ARIA supplements HTML so that interactions and widgets commonly used in applications can be passed to assistive technologies when there is not otherwise a mechanism. For example, ARIA enables accessible JavaScript widgets, form hints and error messages, live content updates, and more. -It supplements HTML so that interactions and widgets commonly used in applications can be passed to assistive technologies when there is not otherwise a mechanism. For example, ARIA enables accessible JavaScript widgets, form hints and error messages, live content updates, and more. +## Before using ARIA > [!WARNING] -> Many of these widgets are fully supported in modern browsers. **Developers should prefer using the correct semantic HTML element over using ARIA**, if such an element exists. For instance, native elements have built-in [keyboard accessibility](/en-US/docs/Web/Accessibility/Keyboard-navigable_JavaScript_widgets), roles and states. However, if you choose to use ARIA, you are responsible for mimicking the equivalent browser behavior in script. +> Many of these widgets are fully supported in modern browsers. **Developers should prefer using the correct semantic HTML element over using ARIA**, if such an element exists. For instance, native elements have built-in [keyboard accessibility](/en-US/docs/Web/Accessibility/Guides/Keyboard-navigable_JavaScript_widgets), roles and states. However, if you choose to use ARIA, you are responsible for mimicking the equivalent browser behavior in script. [The first rule of ARIA](https://www.w3.org/TR/using-aria/#rule1) use is "If you can use a native HTML element or attribute with the semantics and behavior you require already built in, instead of re-purposing an element and adding an ARIA role, state or property to make it accessible, then do so." @@ -29,7 +30,7 @@ Here's the markup for a progress bar widget: aria-valuemax="100"></div> ``` -This progress bar is built using a {{HTMLElement("div")}}, which has no meaning. We include ARIA roles and properties to add meaning. In this example, the [`role="progressbar"`](/en-US/docs/Web/Accessibility/ARIA/Roles/progressbar_role) attribute informs the browser that this element is actually a JavaScript-powered progress bar widget. The [`aria-valuemin`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-valuemin) and [`aria-valuemax`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-valuemax) attributes specify the minimum and maximum values for the progress bar, and the [`aria-valuenow`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-valuenow) describes the current state of it and therefore must be kept updated with JavaScript. +This progress bar is built using a {{HTMLElement("div")}}, which has no meaning. We include ARIA roles and properties to add meaning. In this example, the [`role="progressbar"`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/progressbar_role) attribute informs the browser that this element is actually a JavaScript-powered progress bar widget. The [`aria-valuemin`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-valuemin) and [`aria-valuemax`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-valuemax) attributes specify the minimum and maximum values for the progress bar, and the [`aria-valuenow`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-valuenow) describes the current state of it and therefore must be kept updated with JavaScript. Along with placing them directly in the markup, ARIA attributes can be added to the element and updated dynamically using JavaScript code like this: @@ -72,12 +73,18 @@ It is also important to acknowledge that some people who rely on assistive techn It is also important to test your authored ARIA with actual assistive technology. This is because browser emulators and simulators are not really effective for testing full support. Similarly, proxy assistive technology solutions are not sufficient to fully guarantee functionality. -## References +## Reference -- [ARIA roles](/en-US/docs/Web/Accessibility/ARIA/Roles) - - : Reference pages covering all the WAI-ARIA roles discussed on MDN. -- [ARIA states and properties](/en-US/docs/Web/Accessibility/ARIA/Attributes) - - : Reference pages covering all the WAI-ARIA states and properties discussed on MDN. +The [ARIA reference](/en-US/docs/Web/Accessibility/ARIA/Reference) is a comprehensive list of ARIA attributes and roles that are documented on MDN. + +- [ARIA roles](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles) + - : ARIA roles can be used to describe elements that don't natively exist in HTML or those which exist but don't yet have wide browser support. +- [ARIA states and properties (attributes)](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes) + - : ARIA attributes enable modifying an element's states and properties as defined in the accessibility tree. + +## Guides + +The [ARIA guides](/en-US/docs/Web/Accessibility/ARIA/Guides) and [How-to pages](/en-US/docs/Web/Accessibility/ARIA/How_to) are resources that help you improve the accessibility of web page features such as tables, forms, and keyboard-navigation. ## Standardization efforts @@ -88,9 +95,9 @@ It is also important to test your authored ARIA with actual assistive technology ## ARIA for scripted widgets -- [Writing keyboard-navigable JavaScript widgets](/en-US/docs/Web/Accessibility/Keyboard-navigable_JavaScript_widgets) +- [Writing keyboard-navigable JavaScript widgets](/en-US/docs/Web/Accessibility/Guides/Keyboard-navigable_JavaScript_widgets) - : Built-in elements like {{HTMLElement("input")}}, {{HTMLElement("button")}}, etc. have built-in keyboard accessibility. If you 'fake' these with {{HTMLElement("div")}}s and ARIA, you must ensure your widgets are keyboard accessible. -- [Live regions](/en-US/docs/Web/Accessibility/ARIA/ARIA_Live_Regions) +- [Live regions](/en-US/docs/Web/Accessibility/ARIA/Guides/Live_regions) - : Live regions provide suggestions to screen readers about how to handle changes to the contents of a page. ## Videos diff --git a/files/en-us/web/accessibility/aria/multipart_labels/index.md b/files/en-us/web/accessibility/aria/multipart_labels/index.md deleted file mode 100644 index f3e4e99c7627ae3..000000000000000 --- a/files/en-us/web/accessibility/aria/multipart_labels/index.md +++ /dev/null @@ -1,54 +0,0 @@ ---- -title: "Multipart labels: Using ARIA for labels with embedded fields inside them" -slug: Web/Accessibility/ARIA/Multipart_labels -page-type: guide ---- - -{{AccessibilitySidebar}} - -## Problem - -You have a form where you ask your user a question, but the answer is mentioned in the question itself. A classic example we all know from our browser settings is the setting "Delete history after x days". "Delete history after" is to the left of the textbox, x is the number, for example 21, and the word "days" follows the textbox, forming a sentence that is easy to understand. - -If you're using a screen reader, have you noticed that, when you go to this setting in Firefox, it tells you "Delete history after 21 days"?, followed by the announcement that you're in a textbox, and that it contains the number 21. Isn't that cool? You do not need to navigate around to find out the unit. "Days" could easily be "months" or "years", and in many ordinary dialogs, there is no way to find this out other than navigating around with screen reviewing commands. - -The solution is in an ARIA attribute called `aria-labelledby`. Its parameter is a string that consists of the IDs of the HTML elements you want to concatenate into a single accessible name. - -Both `aria-labelledby` and `aria-describedby` are specified on the form element that is to be labelled, for example an `<input>` In both cases, the label for/label control bindings that may also exist are overridden by `aria-labelledby`. If on an HTML page you provide `aria-labelledby`, you should also provide a label for construct to also support older browsers that do not have ARIA support yet. With Firefox 3, your visually impaired users will automatically get better accessibility from the new attribute, but the users of older browsers are not left in the dark this way. - -### Example - -{{ EmbedLiveSample("Example") }} - -```css hidden -body { - margin: 1rem; -} -``` - -```html -<input - aria-labelledby="labelShutdown shutdownTime shutdownUnit" - type="checkbox" /> - -<span id="labelShutdown">Shut down computer after</span> - -<input - aria-labelledby="labelShutdown shutdownTime shutdownUnit" - id="shutdownTime" - type="text" - value="10" /> - -<span id="shutdownUnit"> minutes</span> -``` - -## A Note for JAWS 8 users - -JAWS 8.0 has its own logic to find labels, causing it to always override the accessibleName the textbox of an HTML document gets. With JAWS 8, I have not found a way to make it to accept the label from the example above. But NVDA and Window-Eyes do it just fine, and Orca on Linux also has no problems. - -> [!NOTE] -> TBD: add more compatibility info - -## Can this be done without ARIA? - -Community member Ben Millard has pointed out in a blog post that [controls can be embedded in labels as shown in the above example using HTML 4](https://projectcerbera.com/blog/2008/03/#day24), by embedding the input into the label. Thanks for that info, Ben! It is very useful and shows that some techniques that have been available for years escape even the gurus sometimes. This technique works in Firefox; however, it doesn't currently work in many other browsers, including IE. For labels with embedded form controls, using `aria-labelledby` is still the best approach. diff --git a/files/en-us/web/accessibility/aria/reference/attributes/aria-activedescendant/index.md b/files/en-us/web/accessibility/aria/reference/attributes/aria-activedescendant/index.md new file mode 100644 index 000000000000000..995c94e20f951e8 --- /dev/null +++ b/files/en-us/web/accessibility/aria/reference/attributes/aria-activedescendant/index.md @@ -0,0 +1,62 @@ +--- +title: "ARIA: aria-activedescendant attribute" +short-title: aria-activedescendant +slug: Web/Accessibility/ARIA/Reference/Attributes/aria-activedescendant +page-type: aria-attribute +spec-urls: + - https://w3c.github.io/aria/#aria-activedescendant + - https://www.w3.org/TR/wai-aria-1.2/#aria-activedescendant +sidebar: accessibilitysidebar +--- + +The `aria-activedescendant` attribute identifies the currently active element when focus is on a [`composite`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/composite_role) widget, [`combobox`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/combobox_role), [`textbox`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/textbox_role), [`group`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/group_role), or [`application`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/application_role). + +## Description + +The `aria-activedescendant` property provides a method of managing focus for assistive technologies on interactive elements when they contain multiple focusable descendants, such as menus, grids, and toolbars. Instead of the screen reader moving focus between owned elements, `aria-activedescendant` can be used on container elements to refer to the currently active element, informing assistive technology users of the currently active element when focused. + +With `aria-activedescendant`, the browser keeps the DOM focus on the container element or on an input element that controls the container element. However, the user agent communicates desktop focus events and states to the assistive technology as if the element referenced by `aria-activedescendant` has focus. + +This attribute is only relevant on elements with role of [`composite`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/composite_role) widget, [`combobox`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/combobox_role), [`textbox`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/textbox_role), [`group`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/group_role), or [`application`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/application_role) whose `id` is referenced as the attribute value. + +The attribute manages providing assistive technologies with information as to which element has focus, but doesn't actually create focus. Changing focus and managing the attributes value is done with JavaScript. In addition to managing that attribute value, make sure the currently active descendant is visible and in view (or scrolls into view) when focused. + +In setting the value of `aria-activedescendant` on an element with DOM focus, ensure the value refers to an owned element—either a descendant of the element with DOM focus OR a logical descendant as indicated by the [`aria-owns`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-owns) attribute. + +When the element with DOM focus is a combobox, textbox, or searchbox, include [`aria-controls`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-controls) to refer to the element that supports `aria-activedescendant`. + +The value of `aria-activedescendant` refers to an owned element of the controlled element. For example, in a combobox, focus may remain on the combobox while the value of `aria-activedescendant` on the combobox element refers to a descendant of a popup listbox that is controlled by the combobox. + +> [!NOTE] +> The attribute is supported only on a few roles. For example, `dialog`s do not support `aria-activedescendant`. When a combobox opens a dialog, DOM focus moves into the dialog from the combobox as it is not referenceable with this attribute. + +> [!NOTE] +> When a descendant of a `listbox`, `grid`, or `tree` popup is focused, DOM focus remains on the combobox and the combobox has `aria-activedescendant` set to a value that refers to the focused element within the popup. + +## Values + +- ID reference + - : takes as its value the `id` of the currently focused element. + +## Associated interfaces + +- {{domxref("Element.ariaActiveDescendantElement")}} + - : The `ariaActiveDescendantElement` property is part of each element's interface. + Its value is an instance of a subclass of {{domxref("Element")}} that reflects the `id` reference in the `aria-activedescendant` attribute ([with some caveats](/en-US/docs/Web/API/Document_Object_Model/Reflected_attributes#reflected_element_references)). +- {{domxref("ElementInternals.ariaActiveDescendantElement")}} + - : The `ariaActiveDescendantElement` property is part of each custom element's interface. + Its value is an instance of a subclass of {{domxref("Element")}} that reflects the `id` reference in the `aria-activedescendant` attribute ([with some caveats](/en-US/docs/Web/API/Document_Object_Model/Reflected_attributes#reflected_element_references)). + +## Associated roles + +Relevant only as an attribute on elements with the following roles: + +- [`application`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/application_role) +- [`combobox`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/combobox_role) +- [`composite`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/composite_role) +- [`group`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/group_role) +- [`textbox`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/textbox_role) + +## Specifications + +{{Specifications}} diff --git a/files/en-us/web/accessibility/aria/reference/attributes/aria-atomic/index.md b/files/en-us/web/accessibility/aria/reference/attributes/aria-atomic/index.md new file mode 100644 index 000000000000000..ce96c9b04dcc684 --- /dev/null +++ b/files/en-us/web/accessibility/aria/reference/attributes/aria-atomic/index.md @@ -0,0 +1,37 @@ +--- +title: "ARIA: aria-atomic attribute" +short-title: aria-atomic +slug: Web/Accessibility/ARIA/Reference/Attributes/aria-atomic +page-type: aria-attribute +spec-urls: https://w3c.github.io/aria/#aria-atomic +sidebar: accessibilitysidebar +--- + +In ARIA live regions, the global `aria-atomic` attribute indicates whether assistive technologies such as a screen reader will present all, or only parts of, the changed region based on the change notifications defined by the [`aria-relevant`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-relevant) attribute. + +## Description + +Live regions are sections of a web page that are updated, whether by user interaction or not, when user focus is elsewhere. As they update outside the user's focus, assistive technologies such as screen readers may not "see" the update to report it to the user. WAI-ARIA has 4 properties that allow the developer to identify these live regions and tell the assistive technology how to process them, including [`aria-live`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-live), [`aria-relevant`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-relevant), [`aria-busy`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-busy) and `aria-atomic`. + +When the content of a live region changes, the DOM is traversed from the changed element through its ancestors to find the first element with `aria-atomic` set. This determines the content that the user should be presented with. + +If no ancestor has explicitly set `aria-atomic`, only the node or nodes of live region content that have been updated are read. The difference between omitting `aria-atomic` altogether and explicitly setting an ARIA live region's ancestor node with `aria-atomic="false"` is that explicitly setting `aria-atomic="false"` will stop the screen reader from going up the ancestor chain. Both lead to only the updated node being read. When set to `aria-atomic="true"`, the entire changed region as a whole will be presented, including the updated node's `label`, if there is one. + +## Values + +- `false` (default) + - : present only the changed node or nodes. +- `true` + - : present the entire changed region as a whole, including the author-defined label if one exists. + +## Associated roles + +Used in **ALL** [roles](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles). + +## Specifications + +{{Specifications}} + +## See also + +- [Event.ariaAtomic](/en-US/docs/Web/API/Element/ariaAtomic) diff --git a/files/en-us/web/accessibility/aria/reference/attributes/aria-autocomplete/index.md b/files/en-us/web/accessibility/aria/reference/attributes/aria-autocomplete/index.md new file mode 100644 index 000000000000000..7946637bd7dcb1b --- /dev/null +++ b/files/en-us/web/accessibility/aria/reference/attributes/aria-autocomplete/index.md @@ -0,0 +1,69 @@ +--- +title: "ARIA: aria-autocomplete attribute" +short-title: aria-autocomplete +slug: Web/Accessibility/ARIA/Reference/Attributes/aria-autocomplete +page-type: aria-attribute +spec-urls: + - https://w3c.github.io/aria/#aria-autocomplete, + - https://www.w3.org/WAI/ARIA/apg/patterns/combobox/examples/combobox-autocomplete-both/ +sidebar: accessibilitysidebar +--- + +The `aria-autocomplete` attribute indicates whether inputting text could trigger display of one or more predictions of the user's intended value for a [`combobox`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/combobox_role), [`searchbox`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/searchbox_role), or [`textbox`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/textbox_role) and specifies how predictions will be presented if they are made. + +## Description + +Autocompletion is user interface feature wherein inline suggestions are made as a user types in an input. Suggested text for completing the value of the field dynamically appears in the field after the input cursor, and the suggested value becomes the value if the user performs an action, such as tabbing, that causes focus to leave the field. + +The `aria-autocomplete` property describes the type of autocompletion interaction model a textbox, searchbox, or combobox will use when dynamically helping users complete text input. It distinguishes between two models: the **inline** model (`aria-autocomplete="inline"`), which presents a single predicted value and the **list** model (`aria-autocomplete="list"`), which presents a collection of possible values in a separate element that pops up next to or below the text input, similar to a {{HTMLElement('datalist')}}. A third value, `aria-autocomplete="both"` is for when the interface will present a list while also including a predicted value. The default is `none`, meaning the textbox, searchbox, or combobox will not provide an auto complete value. + +The `aria-autocomplete` property only describes the type of predictive behavior for an input element for assistive technologies; it doesn't provide the functionality. The actual autocompletion should be provided using HTML attributes or JavaScript. + +If the suggested autocomplete value provides suggested values that aren't dependent on the input provided by the user, consider omitting autocomplete for everyone. For example, a searchbox input displaying unfiltered recent search terms may be helpful to a marketing team on an e-commerce site, but likely isn't helpful for the screen reader user. When it is best to not specify a value for `aria-autocomplete` or to set the value to the `none` default, likely your non-assistive technology users also don't need the experience. + +When implementing autocomplete functionality, ensure the suggested portion of the value is presented as selected text to enable distinguishing between a user's input and the suggestion. Make sure that when the suggested value is not the desired value, users can easily delete the suggestion or replace it by continuing to type. + +When implementing a list of values, DOM focus should remain on the text input while the suggestion list is displayed. + +- include [`aria-controls`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-controls) with the value of the id of the suggested list of values. +- include [`aria-haspopup`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-haspopup) matching the role of the element that contains the collection of suggested values. +- manage focus, if required, including using [`aria-activedescendant`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-activedescendant) if the collection container supports. +- use the [`aria-expanded`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-expanded) state on the element with role [`combobox`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/combobox_role) to communicate that the list is displayed. + +If an autocomplete list value is automatically accepted when the field loses focus, the list must be contained in a role that supports `aria-activedescendant`, with the value of `aria-activedescendant` on the input field dynamically adjusted to refer to the element containing the selected suggestion. + +## Values + +- `none` (default) + - : When a user is providing input, no automatic suggestion is displayed. +- `inline` + - : `aria-autocomplete="inline"` text suggesting one way to complete the provided input may be dynamically inserted after the caret. +- `list` + - : `aria-autocomplete="list"` When a user is providing input, an element containing a collection of values that could complete the provided input may be displayed. +- `both` + - : `aria-autocomplete="both"` an input to offer both models at the same time. When a user is providing input, an element containing a collection of values that could complete the provided input may be displayed. If displayed, one value in the collection is automatically selected, and the text needed to complete the automatically selected value appears after the caret in the input. + +## Associated roles + +Used in roles: + +- [`combobox`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/combobox_role) role +- [`textbox`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/textbox_role) role +- inherits from [`searchbox`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/searchbox_role) role + +## Specifications + +{{Specifications}} + +## See also + +- [`combobox`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/combobox_role) role +- [`textbox`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/textbox_role) role +- [`searchbox`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/searchbox_role) role +- {{HTMLElement('datalist')}} element and the [`<input> list` attribute](/en-US/docs/Web/HTML/Reference/Elements/input#list) +- [`aria-controls`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-controls) attribute +- [`aria-haspopup`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-haspopup) attribute +- [`aria-activedescendant`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-activedescendant) attribute +- [`aria-expanded`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-expanded) attribute +- [Editable Combobox With Both List and Inline Autocomplete Example](https://www.w3.org/TR/wai-aria-practices-1.2/examples/combobox/combobox-autocomplete-both.html) +- [Event.ariaAutoComplete](/en-US/docs/Web/API/Element/ariaAutoComplete) diff --git a/files/en-us/web/accessibility/aria/reference/attributes/aria-braillelabel/index.md b/files/en-us/web/accessibility/aria/reference/attributes/aria-braillelabel/index.md new file mode 100644 index 000000000000000..d4be9989a9aac29 --- /dev/null +++ b/files/en-us/web/accessibility/aria/reference/attributes/aria-braillelabel/index.md @@ -0,0 +1,57 @@ +--- +title: "ARIA: aria-braillelabel attribute" +short-title: aria-braillelabel +slug: Web/Accessibility/ARIA/Reference/Attributes/aria-braillelabel +page-type: aria-attribute +spec-urls: https://w3c.github.io/aria/#aria-braillelabel +sidebar: accessibilitysidebar +--- + +The global `aria-braillelabel` property defines a string value that labels the current element, which is intended to be converted into Braille. + +## Description + +The global `aria-braillelabel` attribute is similar to the global [`aria-label`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-label) in that it defines a string value that labels the current element. While `aria-label` is read by the screen reader, the contents of the `aria-braillelabel` attribute are converted into Braille; providing the user with a recognizable name of the object in braille. + +The purpose of the `aria-braillelabel` property is to override how assistive technologies localize and express the accessible name of an element in Braille. It should only be used when, without this attribute, the accessible name would not be the desired user experience when converted to braille. + +When using `aria-braillelabel`, ensure that: + +- The element to which `aria-braillelabel` is applied has a valid accessible name. +- The value of `aria-braillelabel` has actual content and is not empty or only whitespace in unicode or unicode braille. +- The value is NOT the same as the accessible name. +- The `aria-braillelabel` values are localized to align with the document language. +- Communicate to the user that this attribute is available, especially if the content contains unicode braille patterns, so the user knows to set the settings to apply user specific braille translations + +> [!NOTE] +> Assistive technologies with braille support can convert the accessible names to braille. +> Therefore, only use `aria-braillelabel` when the accessible name is not the user experience you want. + +Using only the accessible name, e.g., from content or via `aria-label` is almost always the better user experience, so don't use aria-braillelabel to replicate aria-label. Only use `aria-braillelabel` if the accessible name cannot provide an adequate braille representation. + +```html +<button aria-braillelabel="***"> + <img alt="3 out of 5 stars" src="three_stars.png" /> +</button> +``` + +A braille display may display "btn \*\*\*" in Braille rather than the more verbose "btn gra 3 out of 5 stars". + +## Values + +- `<string>` + - : The value is a string, an unconstrained value type, that is intended to be converted into braille. + +## Associated roles + +Used in **ALL** roles. + +## Specifications + +{{Specifications}} + +## See also + +- {{domxref("Element.ariaBrailleLabel")}} +- [`aria-label`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-label) +- [`aria-brailleroledescription`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-brailleroledescription) diff --git a/files/en-us/web/accessibility/aria/reference/attributes/aria-brailleroledescription/index.md b/files/en-us/web/accessibility/aria/reference/attributes/aria-brailleroledescription/index.md new file mode 100644 index 000000000000000..19708e837225cf1 --- /dev/null +++ b/files/en-us/web/accessibility/aria/reference/attributes/aria-brailleroledescription/index.md @@ -0,0 +1,77 @@ +--- +title: "ARIA: aria-brailleroledescription attribute" +short-title: aria-brailleroledescription +slug: Web/Accessibility/ARIA/Reference/Attributes/aria-brailleroledescription +page-type: aria-attribute +spec-urls: https://w3c.github.io/aria/#aria-brailleroledescription +sidebar: accessibilitysidebar +--- + +The global `aria-brailleroledescription` attribute defines a human-readable, author-localized abbreviated description for the role of an element intended to be converted into Braille. + +## Description + +Braille is not a one-to-one transliteration of letters and numbers, but rather it includes various abbreviations, contractions, and characters that represent words (known as logograms). + +Instead of converting long role descriptions to Braille, the `aria-brailleroledescription` attribute allows for providing an abbreviated version of the [`aria-roledescription`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-roledescription) value, which is a human-readable, author-localized description for the role of an element, for improved user experience with braille interfaces. + +Basically, the value of `aria-brailleroledescription` is an abbreviated version of the `aria-roledescription` attribute to be converted into Braille. + +```html +<article + aria-roledescription="slide" + aria-brailleroledescription="sld" + aria-labelledby="slide1heading"> + <h1 id="slide1heading">Welcome to my talk</h1> + <img alt="Me" src="images/me.jpg" /> +</article> +``` + +Most assistive technologies, like screen readers, will read the above as "slide, welcome to my talk. Image, Me." Braille assistive technologies will present "sld welcome to my talk gra me" in braille. The semantic {{HTMLElement('article')}} is given the role of "slide" by the `aria-roledescription` attribute; "slide" being a role not defined in the specification, but is a common role for slides in a presentation. In Braille, the role is presented as "sld". The "gra" is short for "graphic", which is how the "image" role is shortened in braille. + +The `aria-brailleroledescription` attribute should only be used to clarify the purpose of non-interactive container roles like "group" or "region", or to provide a more specific description of a widget in a braille context. + +As the `aria-brailleroledescription` attribute overrides how assistive technologies localize and express the name of a role in braille, inappropriate values will prevent users from understanding and interacting with an element on braille interfaces. + +Only use `aria-brailleroledescription` if [`aria-roledescription`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-roledescription) is present. However, if the `aria-roledescription` value works in braille, the braille version of the attribute is not needed. In general, `aria-brailleroledescription` should only be used in the rare case when a `aria-roledescription` is too verbose for braille. + +A few rules to remember: + +- Only apply `aria-brailleroledescription` to elements with a valid ARIA role or elements with implicit role semantics. +- The `aria-brailleroledescription`, if present, must have a non-empty, none null value that is different from the `aria-roledescription` value, which, in turn, is different from the ARIA explicit or role or implicit semantic role. +- Avoid using Unicode Braille Patterns. If they must be used, ensure the `aria-brailleroledescription` value contains content other than unicode braille patterns, whitespace, and braille pattern dots-0. +- Ensure the value is always localized to the document's language. + +> [!WARNING] +> If the content is only in unicode braille patterns, the value will not be translated according to the user's preferred translation table. + +> [!NOTE] +> Do NOT use `aria-brailleroledescription` to replicate `aria-roledescription`. Only include this attribute when `aria-roledescription` does not provide an adequate braille representation. + +The `aria-brailleroledescription` value will not be exposed to the braille user if: + +- The value is empty or contains only whitespace characters or the empty braille pattern: dots-0 (U+2800). +- The element to which the attribute is applied has an explicit or implicit WAI-ARIA role where `aria-brailleroledescription` is prohibited, including the `generic` role. +- The element to which the attribute is applied does not have a valid `aria-roledescription`. + +> [!NOTE] +> Test your sites and applications with daily users of assistive technologies, including braille readers, to ensure your content makes sense in braille. + +## Values + +- `<string>` + - : The value is a string, an unconstrained value type, that is intended to be converted into braille + +## Associated roles + +Used in **ALL** roles (except [`generic`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/generic_role)). + +## Specifications + +{{Specifications}} + +## See also + +- {{domxref("Element.ariaBrailleRoleDescription")}} +- [`aria-roledescription`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-roledescription). +- [`Element.ariaRoleDescription`](/en-US/docs/Web/API/Element/ariaRoleDescription) diff --git a/files/en-us/web/accessibility/aria/reference/attributes/aria-busy/index.md b/files/en-us/web/accessibility/aria/reference/attributes/aria-busy/index.md new file mode 100644 index 000000000000000..84ee63d19955fe3 --- /dev/null +++ b/files/en-us/web/accessibility/aria/reference/attributes/aria-busy/index.md @@ -0,0 +1,77 @@ +--- +title: "ARIA: aria-busy attribute" +short-title: aria-busy +slug: Web/Accessibility/ARIA/Reference/Attributes/aria-busy +page-type: aria-attribute +spec-urls: + - https://w3c.github.io/aria/#aria-busy + - https://www.w3.org/TR/wai-aria-1.2/#aria-busy +sidebar: accessibilitysidebar +--- + +Used in [ARIA live regions](/en-US/docs/Web/Accessibility/ARIA/Guides/Live_regions), the global `aria-busy` state indicates an element is being modified and that assistive technologies may want to wait until the changes are complete before informing the user about the update. + +When multiple parts of a live region need to be loaded before changes are announced to the user, set `aria-busy="true"` until loading is complete. Then set to `aria-busy="false"`. This prevents assistive technologies from announcing changes before updates are done. + +## Description + +There is a section of content that updates. The updates are important and you want to let the user know when it has been modified, so you have converted it into an [ARIA live region](/en-US/docs/Web/Accessibility/ARIA/Guides/Live_regions) with the [`aria-live`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-live) attribute. You may want to update several components of that section at the same time, but you can't be sure that everything will update simultaneously. Even if it is a very important live region with `aria-live="assertive"`, you don't want to interrupt the user multiple times as different parts of the content load. This is where `aria-busy` can help. + +The `aria-busy` property is an optional property of live regions that can have the value `true` or `false`. The `aria-busy` attribute with a value of `true` can be added to an element currently being updated or modified, to inform the assistive technology that it should wait until the modifications or changes are complete before exposing the content to the user. Use the [`ariaBusy`](/en-US/docs/Web/API/Element/ariaBusy) property of the object to change the value to `false` when downloading is complete. + +```js +ariaLiveElement.ariaBusy = "false"; +``` + +[`aria-live`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-live)'s value dictates whether the changes are announced immediately upon changing the value to `false`, or the assistive technology waits until the current task is complete before interrupting the user. + +### Within a `feed` + +If an element with [`feed`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/feed_role) role has `aria-busy` set to `true`, the rendering changes that occur inside the feed will not be announced with the exception of user-initiated changes. + +### Within a `widget` + +If changes to a rendered widget would create a state where the widget is missing required owned elements during script execution, set `aria-busy` to `true` on the widget during the update process. For example, if a rendered tree grid updates multiple branches not necessarily rendered simultaneously, an alternative to replacing the whole tree in a single update would be to mark the tree busy while each of the branches is modified. + +## Values + +- false (default): + - : There are no expected updates for the element. +- true + - : The element is being updated. + +## Associated interfaces + +- {{domxref("Element.ariaBusy")}} + - : The [`ariaBusy`](/en-US/docs/Web/API/Element/ariaBusy) property, part of each element's interface, reflects the value of the `aria-busy` attribute, which indicates whether an element is being modified. + +```html +<div + id="clock" + role="timer" + aria-live="polite" + aria-atomic="true" + aria-busy="false"></div> +``` + +```js +const el = document.getElementById("clock"); +console.log(el.ariaBusy); // false +el.ariaBusy = "true"; +console.log(el.ariaBusy); // true +``` + +## Associated roles + +Used in **ALL** roles + +## Specifications + +{{Specifications}} + +## See also + +- [ARIA live regions](/en-US/docs/Web/Accessibility/ARIA/Guides/Live_regions) +- [`aria-live`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-live) +- [`aria-relevant`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-relevant) +- [`aria-atomic`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-atomic) diff --git a/files/en-us/web/accessibility/aria/reference/attributes/aria-checked/index.md b/files/en-us/web/accessibility/aria/reference/attributes/aria-checked/index.md new file mode 100644 index 000000000000000..0b5b939dbcfb79f --- /dev/null +++ b/files/en-us/web/accessibility/aria/reference/attributes/aria-checked/index.md @@ -0,0 +1,88 @@ +--- +title: "ARIA: aria-checked attribute" +short-title: aria-checked +slug: Web/Accessibility/ARIA/Reference/Attributes/aria-checked +page-type: aria-attribute +spec-urls: + - https://w3c.github.io/aria/#aria-checked + - https://www.w3.org/WAI/ARIA/apg/patterns/checkbox/examples/checkbox/ +sidebar: accessibilitysidebar +--- + +The `aria-checked` attribute indicates the current "checked" state of checkboxes, radio buttons, and other widgets. + +> [!NOTE] +> Where possible use an HTML {{htmlelement("input")}} element with `type="checkbox"` and `type="radio"` as these have built in semantics and do not require ARIA attributes. + +## Description + +The `aria-checked` attribute indicates whether the element is checked (`true`), unchecked (`false)`, or if the checked status is indeterminate (`mixed`), meaning it is neither checked nor unchecked. The `mixed` value is supported by the tri-state input roles of [`checkbox`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/checkbox_role) and [`menuitemcheckbox`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/menuitemcheckbox_role). + +The `mixed` value is not supported on [`radio`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/radio_role), [`menuitemradio`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/menuitemradio_role), or [`switch`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/switch_role) and elements that inherits from these. The value will be false if `mixed` is set when not supported. + +```html +<span + role="checkbox" + id="checkBoxInput" + aria-checked="false" + tabindex="0" + aria-labelledby="chk15-label"></span> +<label id="chk15-label">Subscribe to the newsletter</label> +``` + +The `tabindex` attribute is required to enable focus. JavaScript is required to toggle the `aria-checked` state. And, if this checkbox is part of a submittable form, more JavaScript is required to set a name and a value. + +The above could have been written as: + +```html +<input type="checkbox" id="chk15-label" name="Subscribe" /> +<label for="chk15-label">Subscribe to the newsletter</label> +``` + +By using the {{htmlelement("input")}} element with `type="checkbox"` instead of ARIA, there is no need for any JavaScript. + +## Values + +- false + - : The element supports being checked but is not currently checked. +- true + - : The element is checked. +- mixed + - : for [`checkbox`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/checkbox_role) and [`menuitemcheckbox`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/menuitemcheckbox_role) only, equivalent to `indeterminate`, indicating a mixed mode value of neither checked nor unchecked. +- undefined (default) + - : The element does not support being checked. + +## Associated roles + +Used in roles: + +- [`checkbox`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/checkbox_role) +- [`menuitemcheckbox`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/menuitemcheckbox_role) +- [`menuitemradio`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/menuitemradio_role) +- [`option`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/option_role) +- [`radio`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/radio_role) +- [`switch`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/switch_role) + +## Associated interfaces + +- {{domxref("Element.ariaChecked")}} + - : The [`ariaChecked`](/en-US/docs/Web/API/Element/ariaChecked) property, part of the {{domxref("Element")}} interface, reflects the value of the `aria-checked` attribute. +- {{domxref("ElementInternals.ariaChecked")}} + - : The [`ariaChecked`](/en-US/docs/Web/API/ElementInternals/ariaChecked) property, part of the {{domxref("ElementInternals")}} interface, reflects the value of the `aria-checked` attribute. + +```js +myHTMLElement.ariaChecked = true; +``` + +## Specifications + +{{Specifications}} + +## See also + +- [`<input type="checkbox">`](/en-US/docs/Web/HTML/Reference/Elements/input/checkbox) +- [`<input type="radio">`](/en-US/docs/Web/HTML/Reference/Elements/input/radio) +- [`aria-pressed`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-pressed) +- [`aria-selected`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-selected) +- [Two state checkbox example](https://www.w3.org/WAI/ARIA/apg/example-index/checkbox/checkbox.html) - w3.org +- [Mix-state checkbox example](https://www.w3.org/WAI/ARIA/apg/example-index/checkbox/checkbox-mixed.html) - w3.org diff --git a/files/en-us/web/accessibility/aria/reference/attributes/aria-colcount/index.md b/files/en-us/web/accessibility/aria/reference/attributes/aria-colcount/index.md new file mode 100644 index 000000000000000..41a202177b9b698 --- /dev/null +++ b/files/en-us/web/accessibility/aria/reference/attributes/aria-colcount/index.md @@ -0,0 +1,90 @@ +--- +title: "ARIA: aria-colcount attribute" +short-title: aria-colcount +slug: Web/Accessibility/ARIA/Reference/Attributes/aria-colcount +page-type: aria-attribute +spec-urls: https://w3c.github.io/aria/#aria-colcount +sidebar: accessibilitysidebar +--- + +The `aria-colcount` attribute defines the total number of columns in a [`table`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/table_role), [`grid`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/grid_role), or [`treegrid`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/treegrid_role) when not all columns are present in the [DOM](/en-US/docs/Glossary/DOM). + +## Description + +Some tables are very large, and it's not possible to show all the columns to the user. Or, it is possible, but having such a wide table would be a bad user experience. Use the `aria-colcount` attribute to let assistive technologies know how many columns the table would have if all columns were present. The value is an integer representing the number of columns that make up the full table. If you don't know the total number of columns a table will have, but know they will not all be in the DOM, use the value -1, so `aria-colcount="-1"`. This value tells the user agent that the current number of columns present in the DOM may not be the actual number of columns in the table. + +If all columns in a table are present in the DOM, the `aria-colcount` attribute isn't needed, as browsers automatically calculate the total number of columns. However, if only a portion of the columns is present in the DOM at a given moment, that is when this attribute is helpful and needed. + +When using `aria-colcount` when you have a known number of columns, make sure to also use [`aria-colindex`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-colindex) to label each column, or, if the columns are contiguous-if it's a group of columns in the original order with no breaks-label each row. + +The following example shows a grid with 6 columns, of which columns 1, 2, 5, and 6 are displayed to the user. The total number of columns that make up the table is set as `aria-colcount="6"` on the table itself. As the columns aren't contiguous, every [`cell`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/cell_role) - in this case [`columnheader`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/columnheader_role) and [`gridcell`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/gridcell_role) elements - have the `aria-colindex` attribute set. + +```html +<div role="grid" aria-colcount="6"> + <div role="rowgroup"> + <div role="row"> + <div role="columnheader" aria-colindex="1">First name</div> + <div role="columnheader" aria-colindex="2">Last name</div> + <div role="columnheader" aria-colindex="5">City</div> + <div role="columnheader" aria-colindex="6">Zip</div> + </div> + </div> + <div role="rowgroup"> + <div role="row"> + <div role="gridcell" aria-colindex="1">Debra</div> + <div role="gridcell" aria-colindex="2">Burks</div> + <div role="gridcell" aria-colindex="5">New York</div> + <div role="gridcell" aria-colindex="6">14127</div> + </div> + </div> + … +</div> +``` + +The first rule of ARIA use is "if you can use a native feature with the semantics and behavior you require already built in, instead of repurposing an element and **adding** an ARIA role, state or property to make it accessible, then do so." If we employ native HTML semantics with {{HTMLElement('table')}}, {{HTMLElement('th')}}, {{HTMLElement('td')}}, etc., the `aria-colcount` attribute is still necessary, but the mark up is not as verbose. When using semantic table header elements and not all columns are in the DOM, the `aria-colcount` must still be used, but the `aria-colindex` attribute only needs to be defined once per column in the column header {{HTMLElement('th')}}. + +```html +<table aria-colcount="6"> + <thead> + <tr> + <th aria-colindex="1" scope="col">First name</th> + <th aria-colindex="2" scope="col">Last name</th> + <th aria-colindex="5" scope="col">City</th> + <th aria-colindex="6" scope="col">Zip</th> + </tr> + </thead> + <tbody> + <tr> + <td>Debra</td> + <td>Burks</td> + <td>New York</td> + <td>14127</td> + </tr> + … + </tbody> +</table> +``` + +## Values + +- `<integer>` + - : The number of columns in the full table + +## Associated roles + +Used in roles: + +- [`table`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/table_role) + +Inherits into roles: + +- [`grid`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/grid_role) +- [`treegrid`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/treegrid_role) + +## Specifications + +{{Specifications}} + +## See also + +- [`aria-colindex`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-colindex) diff --git a/files/en-us/web/accessibility/aria/reference/attributes/aria-colindex/index.md b/files/en-us/web/accessibility/aria/reference/attributes/aria-colindex/index.md new file mode 100644 index 000000000000000..b9d95529dbd2695 --- /dev/null +++ b/files/en-us/web/accessibility/aria/reference/attributes/aria-colindex/index.md @@ -0,0 +1,116 @@ +--- +title: "ARIA: aria-colindex attribute" +short-title: aria-colindex +slug: Web/Accessibility/ARIA/Reference/Attributes/aria-colindex +page-type: aria-attribute +spec-urls: https://w3c.github.io/aria/#aria-colindex +sidebar: accessibilitysidebar +--- + +The `aria-colindex` attribute defines an element's column index or position with respect to the total number of columns within a `table`, `grid`, or `treegrid`. + +## Description + +Some tables are very large, and as a result have only a portion of its content is initially displayed. While loading only a subsection of the columns may improve user experience, you need to let all users know what portions of the content are being displayed, and that all the table's content is not present. + +ARIA provides several attributes to provide information about `table`, `grid`, and `treegrid` structures. The `aria-colindex` attribute defines the substructure, an element's column index or position with respect to the total number of columns, within such structures. + +Used in conjunction with the [`aria-colcount`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-colcount) attribute, which informs assistive technologies how many columns the table would have if all columns were present, the `aria-colindex` is used an element's column index or position with respect to that total number of columns. + +If all of the columns are present in the DOM, including `aria-colindex` is not necessary as user agents can calculate the column index of each cell or gridcell. However, if any of the columns are left out of the DOM at any time, use `aria-colindex` to indicate the column of each cell or gridcell with respect to the full table. + +The value for `aria-colindex` is an integer greater than or equal to 1. Each value should be greater than the previous column's `aria-colindex` and less than or equal to the number of columns in the full table. + +If a cell or gridcell spans multiple columns, set [`aria-colspan`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-colspan) to the number of columns it spans if not using {{htmlelement('td')}} and {{htmlelement('th')}} HTML elements, and set `aria-colindex` to the value of the start of the span; the value it would have had if it was only one column wide spanning only the first of its columns. + +If the set of columns which is present in the DOM is contiguous, and if there are no cells which span more than one row or column in that set, you only have to put the `aria-colindex` once on each row on the first column of the set. If the columns are not contiguous, include the `aria-colindex` value on all of the children or owned elements of each row. + +The following example shows a grid with 6 columns, of which columns 1, 2, 5, and 6 are displayed to the user. The total number of columns that make up the table is set as `aria-colcount="6"` on the table itself. As the columns aren't contiguous, every [`cell`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/cell_role) - in this case [`columnheader`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/columnheader_role) and [`gridcell`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/gridcell_role) elements - have the `aria-colindex` attribute set. + +```html +<div role="grid" aria-colcount="6"> + <div role="rowgroup"> + <div role="row"> + <div role="columnheader" aria-colindex="1">First name</div> + <div role="columnheader" aria-colindex="2">Last name</div> + <div role="columnheader" aria-colindex="5">City</div> + <div role="columnheader" aria-colindex="6">Zip</div> + </div> + </div> + <div role="rowgroup"> + <div role="row"> + <div role="gridcell" aria-colindex="1">Debra</div> + <div role="gridcell" aria-colindex="2">Burks</div> + <div role="gridcell" aria-colindex="5">New York</div> + <div role="gridcell" aria-colindex="6">14127</div> + </div> + </div> + … +</div> +``` + +The first rule of ARIA use is "if you can use a native feature with the semantics and behavior you require already built in, instead of repurposing an element and **adding** an ARIA role, state or property to make it accessible, then do so." If we employ native HTML semantics with {{HTMLElement('table')}}, {{HTMLElement('th')}}, {{HTMLElement('td')}}, etc., and only display a subsection of columns, the `aria-colcount` and `aria-colindex` attribute are still necessary, but the mark up is not as verbose. + +When using semantic table header elements and not all columns are in the DOM, the `aria-colindex` attribute only needs to be defined once per column in the column header {{HTMLElement('th')}}. + +```html +<table aria-colcount="6"> + <thead> + <tr> + <th aria-colindex="1" scope="col">First name</th> + <th aria-colindex="2" scope="col">Last name</th> + <th aria-colindex="5" scope="col">City</th> + <th aria-colindex="6" scope="col">Zip</th> + </tr> + </thead> + <tbody> + <tr> + <td>Debra</td> + <td>Burks</td> + <td>New York</td> + <td>14127</td> + </tr> + … + </tbody> +</table> +``` + +If all the columns are in the DOM, neither `aria-colcount` nor `aria-colindex` are necessary. + +## Values + +- `<integer>` + - : Integer greater than or equal to 1 and less than or equal to the total number of columns if all were present. + +## Associated interfaces + +- {{domxref("Element.ariaColIndex")}} + - : The [`ariaColIndex`](/en-US/docs/Web/API/Element/ariaColIndex) property, part of the {{domxref("Element")}} interface, reflects the value of the `aria-colindex` attribute. +- {{domxref("ElementInternals.ariaColIndex")}} + - : The [`ariaColIndex`](/en-US/docs/Web/API/ElementInternals/ariaColIndex) property, part of the {{domxref("ElementInternals")}} interface, reflects the value of the `aria-colindex` attribute. + +## Associated roles + +Used in roles: + +- [`cell`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/cell_role) +- [`row`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/row_role) + +Inherits into roles: + +- [`columnheader`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/columnheader_role) +- [`gridcell`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/gridcell_role) +- [`rowheader`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/rowheader_role) + +## Specifications + +{{Specifications}} + +## See also + +- [`aria-colindextext`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-colindextext) attribute +- [`aria-colcount`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-colcount) attribute +- [`aria-colspan`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-colspan) attribute +- HTML {{HTMLElement('table')}} element +- HTML {{HTMLElement('th')}} element +- HTML {{HTMLElement('td')}} element diff --git a/files/en-us/web/accessibility/aria/reference/attributes/aria-colindextext/index.md b/files/en-us/web/accessibility/aria/reference/attributes/aria-colindextext/index.md new file mode 100644 index 000000000000000..c260f00d9e43a88 --- /dev/null +++ b/files/en-us/web/accessibility/aria/reference/attributes/aria-colindextext/index.md @@ -0,0 +1,104 @@ +--- +title: "ARIA: aria-colindextext attribute" +short-title: aria-colindextext +slug: Web/Accessibility/ARIA/Reference/Attributes/aria-colindextext +page-type: aria-attribute +spec-urls: https://w3c.github.io/aria/#aria-colindextext +sidebar: accessibilitysidebar +--- + +The `aria-colindextext` attribute defines a human-readable text alternative of the numeric [`aria-colindex`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-colindex). + +## Description + +When you have a very large table or when you purposefully want to display just a section of a table, not all columns may be present in the DOM. When this happens, we use the [`aria-colcount`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-colcount) with an integer value to define how many columns the table (or grid) would have if all the columns were present and add the [`aria-colindex`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-colindex) property on each column to provide information on the column index within that larger table. + +In the following HTML snippet, our table has 8 columns, but we are only displaying 4. The "city" column is the fifth column of our larger table, as defined by `aria-colindex="5"`. + +```html +<table aria-colcount="8"> + <thead> + <tr> + <th aria-colindex="1" scope="col">First name</th> + <th aria-colindex="2" scope="col">Last name</th> + <th aria-colindex="5" scope="col">City</th> + <th aria-colindex="7" scope="col">Zip</th> + </tr> + </thead> + … +</table> +``` + +This table is not very complex. Had this been a 100+ column spreadsheet or a grid without column headers, such as a chess board, the provided or calculated value of `aria-colindex` might not be meaningful or may not reflect the displayed index. When this is the case, `aria-colindextext` can be included. The value is a string that is a human-readable text alternative to the numeric `aria-colindex`. + +```html +<table aria-colcount="128"> + <thead> + <tr> + <th aria-colindex="1" aria-colindextext="NYSE stock symbol" scope="col"> + NYSE + </th> + <th + aria-colindex="110" + aria-colindextext="Value at start of 2021" + scope="col"> + 01/21 + </th> + <th + aria-colindex="122" + aria-colindextext="Value at start of 2022" + scope="col"> + 01/22 + </th> + <th aria-colindex="124" scope="col">Recommendation</th> + </tr> + </thead> + … +</table> +``` + +In the above example, the table has 128 columns of which only 4 columns are shown. The `aria-colindextext` is used in three columns to provide human-readable text alternatives. By including `aria-colindextext="Value at start of 2021"`, assistive technologies can announce "Value at start of 2021" instead of "Column 110". + +Only use `aria-colindextext` when the provided or calculated value of `aria-colindex` is not meaningful or does not reflect the displayed index. Whenever you include `aria-colindextext`, also keep the `aria-colindex` as some assistive technologies rely on the numeric column index for the purpose of keeping track of the user's position and in providing alternative table navigation. + +> [!NOTE] +> While `aria-colindex` can be added to a row when all the columns present are contiguous as sequential values can be deduced, `aria-colindextext` is NOT a supported property of [`row`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/row_role). + +See related [`aria-rowindextext`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-rowindextext). + +## Values + +- `<string>` + - : The human-readable text alternative of the numeric [`aria-colindex`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-colindex) + +## Associated interfaces + +- {{domxref("Element.ariaColIndexText")}} + - : The [`ariaColIndexText`](/en-US/docs/Web/API/Element/ariaColIndexText) property, part of the {{domxref("Element")}} interface, reflects the value of the `aria-colindextext` attribute. +- {{domxref("ElementInternals.ariaColIndexText")}} + - : The [`ariaColIndexText`](/en-US/docs/Web/API/ElementInternals/ariaColIndexText) property, part of the {{domxref("ElementInternals")}} interface, reflects the value of the `aria-colindextext` attribute. + +## Associated roles + +Used in roles: + +- [`cell`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/cell_role) + +Inherits into roles: + +- [`columnheader`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/columnheader_role) +- [`rowheader`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/columnheader_role) + +## Specifications + +{{Specifications}} + +## See also + +- [`Element.ariaColIndexText`](/en-US/docs/Web/API/Element/ariaColIndexText) +- [`aria-colindex`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-colindex) +- [`aria-rowindextext`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-rowindextext) +- [`aria-colcount`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-colcount) +- [`cell` role](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/cell_role) +- [`columnheader` role](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/columnheader_role) +- [`rowheader` role](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/columnheader_role) diff --git a/files/en-us/web/accessibility/aria/reference/attributes/aria-colspan/index.md b/files/en-us/web/accessibility/aria/reference/attributes/aria-colspan/index.md new file mode 100644 index 000000000000000..c520cd84fe67012 --- /dev/null +++ b/files/en-us/web/accessibility/aria/reference/attributes/aria-colspan/index.md @@ -0,0 +1,172 @@ +--- +title: "ARIA: aria-colspan attribute" +short-title: aria-colspan +slug: Web/Accessibility/ARIA/Reference/Attributes/aria-colspan +page-type: aria-attribute +spec-urls: https://w3c.github.io/aria/#aria-colspan +sidebar: accessibilitysidebar +--- + +The `aria-colspan` attribute defines the number of columns spanned by a cell or gridcell within a [`table`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/table_role), [`grid`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/grid_role), or [`treegrid`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/treegrid_role). + +## Description + +Intended for [`cell`s](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/cell_role) and [`gridcell`s](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/gridcell_role) which are not contained in a native HTML {{HTMLElement('table')}}, the `aria-colspan` property value defines the number of columns spanned by an individual cell an ARIA [`table`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/table_role), [`grid`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/grid_role), or [`treegrid`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/treegrid_role). + +In HTML, {{HTMLElement('th')}} and {{HTMLElement('td')}} elements have the [`colspan`](/en-US/docs/Web/HTML/Reference/Elements/td#attributes) attribute. When using the semantic {{HTMLElement('table')}}, use the native `colspan` attribute as designed. This ARIA attribute is intended for cells and gridcells which are not contained in a native table, and will be ignored if used on a cell in a {{HTMLElement('table')}}. + +> [!NOTE] +> The first rule of ARIA use is if you can use a native feature with the semantics and behavior you require already built in, instead of repurposing an element and **adding** an ARIA role, state or property to make it accessible, then do so. Employ HTML {{HTMLelement('table')}} elements, including {{HTMLelement('td')}} and {{HTMLelement('th')}} with the `colspan` attribute instead of non-semantic elements with ARIA roles and attributes whenever possible. + +The value of `aria-colspan` should be a positive integer. The default or assumed value of a cell span is 1. Make sure that the included value does cause the cell or gridcell to overlap the next cell or gridcell in the same row and does not cause the cell to span outside of the containing table, grid, or treegrid. + +## Example + +The following is an example of part of a bowling tournament league scoring spreadsheet. Each game spans 10 frames, and each frame spans a 3 scores: two balls and the current total. The 10th (and last) frame in each game spans 4 columns in case someone is scoring all strikes. + +```html +<div role="grid" aria-rowcount="27"> + aria-label="Bowling League Scores" + <div role="rowgroup"> + <div role="row" aria-rowindex="1"> + <!-- + aria-rowspan and aria-colspan provide + assistive technologies with the correct data cell header information + when header cells span more than one row or column. + --> + + <span role="columnheader" aria-rowspan="2">Team</span> + <span role="columnheader" aria-colspan="2">Player</span> + <span role="columnheader" aria-colspan="31">Game 1 Frames</span> + <span role="columnheader" aria-colspan="31">Game 2 Frames</span> + <span role="columnheader" aria-colspan="31">Game 3 Frames</span> + <span role="columnheader" aria-rowspan="2">Total</span> + </div> + <div role="row" aria-rowindex="2"> + <span role="columnheader">Last Name</span> + <span role="columnheader">First Name</span> + <span role="columnheader" aria-colspan="3">1</span> + <span role="columnheader" aria-colspan="3">2</span> + <span role="columnheader" aria-colspan="3">3</span> + <span role="columnheader" aria-colspan="3">4</span> + <span role="columnheader" aria-colspan="3">5</span> + <span role="columnheader" aria-colspan="3">6</span> + <span role="columnheader" aria-colspan="3">7</span> + <span role="columnheader" aria-colspan="3">8</span> + <span role="columnheader" aria-colspan="3">9</span> + <span role="columnheader" aria-colspan="4">10</span> + <span role="columnheader" aria-colspan="3">1</span> + <span role="columnheader" aria-colspan="3">2</span> + <span role="columnheader" aria-colspan="3">3</span> + <span role="columnheader" aria-colspan="3">4</span> + <span role="columnheader" aria-colspan="3">5</span> + <span role="columnheader" aria-colspan="3">6</span> + <span role="columnheader" aria-colspan="3">7</span> + <span role="columnheader" aria-colspan="3">8</span> + <span role="columnheader" aria-colspan="3">9</span> + <span role="columnheader" aria-colspan="4">10</span> + <span role="columnheader" aria-colspan="3">1</span> + <span role="columnheader" aria-colspan="3">2</span> + <span role="columnheader" aria-colspan="3">3</span> + <span role="columnheader" aria-colspan="3">4</span> + <span role="columnheader" aria-colspan="3">5</span> + <span role="columnheader" aria-colspan="3">6</span> + <span role="columnheader" aria-colspan="3">7</span> + <span role="columnheader" aria-colspan="3">8</span> + <span role="columnheader" aria-colspan="3">9</span> + <span role="columnheader" aria-colspan="4">10</span> + </div> + </div> + <div role="rowgroup"> + <div role="row" aria-rowindex="10"> + <span role="rowheader" aria-rowspan="3">The Mighty Quokkas</span> + <span role="cell">Henderson</span> + <span role="cell">Alice</span> + <span role="cell">7</span> + <span role="cell">/</span> + <span role="cell">20</span> + <span role="cell" aria-colspan="2">X</span> + <span role="cell">39</span> + <span role="cell">9</span> + <span role="cell">-</span> + <span role="cell">48</span> + <span role="cell" aria-colspan="2">X</span> + <span role="cell">76</span> + <span role="cell" aria-colspan="2">X</span> + <span role="cell">96</span> + <span role="cell">8</span> + <span role="cell">/</span> + <span role="cell">113</span> + <span role="cell">7</span> + <span role="cell">-</span> + <span role="cell">120</span> + <span role="cell" aria-colspan="2">X</span> + <span role="cell">146</span> + <span role="cell" aria-colspan="2">X</span> + <span role="cell">166</span> + <span role="cell">6</span> + <span role="cell">/</span> + <span role="cell">X</span> + <span role="cell">186</span> + <span role="cell">7</span> + <span role="cell">2</span> + <span role="cell">9</span> + <span role="cell">6</span> + <span role="cell">-</span> + <span role="cell">15</span> + <span role="cell" aria-colspan="2">X</span> + <span role="cell">35</span> + <span role="cell">7</span> + <span role="cell">/</span> + … + </div> + <div role="row" aria-rowindex="11"> + <span role="cell">McPherson</span> + <span role="cell">Leslie</span> + <span role="cell">9</span> + <span role="cell">-</span> + <span role="cell">9</span> + <span role="cell">8</span> + <span role="cell">1</span> + <span role="cell">18</span> + … + </div> + </div> +</div> +``` + +If we had used a {{HTMLElement('table')}} and semantic table elements our markup would have been less verbose and accessible by default. + +## Values + +- `<integer>` + - : An integer greater than or equal to the default value of 1 defining the number of columns spanned by the cell. The value must be less than what would cause a cell to overlap the next cell in the same row. + +## Associated interfaces + +- {{domxref("Element.ariaColSpan")}} + - : The [`ariaColSpan`](/en-US/docs/Web/API/Element/ariaColSpan) property, part of each element's interface, reflects the value of the `aria-colspan` attribute, which defines the number of columns spanned by a cell or gridcell within a table, grid, or treegrid. + +## Associated roles + +Used in roles: + +- [`cell`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/cell_role) + +Inherits into roles: + +- [`columnheader`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/columnheader_role) +- [`rowheader`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/columnheader_role) + +## Specifications + +{{Specifications}} + +## See also + +- The {{HTMLElement('th')}} and {{HTMLElement('td')}} [`colspan`](/en-US/docs/Web/HTML/Reference/Elements/td#attributes) attribute +- [`aria-colindex`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-colindex) property +- [`aria-rowspan`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-rowspan) property +- [`cell`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/cell_role) role +- [`columnheader`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/columnheader_role) role +- [`rowheader`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/columnheader_role) role diff --git a/files/en-us/web/accessibility/aria/reference/attributes/aria-controls/index.md b/files/en-us/web/accessibility/aria/reference/attributes/aria-controls/index.md new file mode 100644 index 000000000000000..9d59fb58b49260e --- /dev/null +++ b/files/en-us/web/accessibility/aria/reference/attributes/aria-controls/index.md @@ -0,0 +1,105 @@ +--- +title: "ARIA: aria-controls attribute" +short-title: aria-controls +slug: Web/Accessibility/ARIA/Reference/Attributes/aria-controls +page-type: aria-attribute +spec-urls: https://w3c.github.io/aria/#aria-controls +sidebar: accessibilitysidebar +--- + +The global `aria-controls` property identifies the element (or elements) whose contents or presence are controlled by the element on which this attribute is set. + +## Description + +When an interactive widget or element, be it a combobox, tab, button, etc., is used to adjust or modify another element or component in a document or application, the `aria-controls` attribute can be used to programmatically associate the corresponding element or elements with the controlling element. The `aria-controls` attribute identifies the element (or elements) whose contents or presence are controlled by the element on which the attribute is set, regardless of what type of interaction initiates the impacted behavior. + +A [combobox](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/combobox_role) element has `aria-controls` set to a value that refers to the element that serves as the popup. The `aria-controls` only needs to be set when the popup is visible, but it is valid and easier to program to reference an element that is not visible. + +Other examples of controls include: + +- The button parts of an accordion widget that toggle the visibility of their associated panel content. Each button may have an `aria-controls` specified, referencing the ID of the element containing the content associated with the invoking control. +- An element with a role of [`scrollbar`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/scrollbar_role): the scrollbar requires an `aria-controls` attribute referencing the ID of the element it controls. +- A group of tabs that each display a different tab panel: each element with [`role="tab"`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/tab_role) has an `aria-controls` attribute referencing its associated [`tabpanel`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/tabpanel_role). + +## Example + +In this tabs example, each tab controls one tabpanel: + +```html +<div class="tab-interface"> + <div role="tablist" aria-label="Sample Tabs"> + <span + role="tab" + aria-selected="true" + aria-controls="panel-1" + id="tab-1" + tabindex="0"> + First Tab + </span> + <span + role="tab" + aria-selected="false" + aria-controls="panel-2" + id="tab-2" + tabindex="-1"> + Second Tab + </span> + <span + role="tab" + aria-selected="false" + aria-controls="panel-3" + id="tab-3" + tabindex="-1"> + Third Tab + </span> + </div> + <div id="panel-1" role="tabpanel" tabindex="0" aria-labelledby="tab-1"> + <p>Content for the first panel</p> + </div> + <div + id="panel-2" + role="tabpanel" + tabindex="0" + aria-labelledby="tab-2" + class="display-none"> + <p>Content for the second panel</p> + </div> + <div + id="panel-3" + role="tabpanel" + tabindex="0" + aria-labelledby="tab-3" + class="display-none"> + <p>Content for the third panel</p> + </div> +</div> +``` + +> [!NOTE] +> ARIA only modifies the accessibility tree for an element, identifying how assistive technology can present the content to users. ARIA doesn't change any implicit functionality or styling. + +## Values + +- `id` list + - : A space-separated list of one or more ID values referencing the elements being controlled by the current element + +## Associated interfaces + +- {{domxref("Element.ariaControlsElements")}} + - : The `ariaControlsElements` property is part of each element's interface. + Its value is an array of instances of subclasses of {{domxref("Element")}} that reflect the `id` references in the `aria-controls` attribute ([with some caveats](/en-US/docs/Web/API/Document_Object_Model/Reflected_attributes#reflected_element_references)). +- {{domxref("ElementInternals.ariaControlsElements")}} + - : The `ariaControlsElements` property is part of each custom element's interface. + Its value is an array of instances of subclasses of {{domxref("Element")}} that reflect the `id` references in the `aria-controls` attribute ([with some caveats](/en-US/docs/Web/API/Document_Object_Model/Reflected_attributes#reflected_element_references)). + +## Associated roles + +Used in **ALL** roles. + +## Specifications + +{{Specifications}} + +## See also + +- [`aria-owns`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-owns) diff --git a/files/en-us/web/accessibility/aria/reference/attributes/aria-current/index.md b/files/en-us/web/accessibility/aria/reference/attributes/aria-current/index.md new file mode 100644 index 000000000000000..f8323bfc566caa7 --- /dev/null +++ b/files/en-us/web/accessibility/aria/reference/attributes/aria-current/index.md @@ -0,0 +1,91 @@ +--- +title: "ARIA: aria-current attribute" +short-title: aria-current +slug: Web/Accessibility/ARIA/Reference/Attributes/aria-current +page-type: aria-attribute +spec-urls: https://w3c.github.io/aria/#aria-current +sidebar: accessibilitysidebar +--- + +A non-null `aria-current` state on an element indicates that this element represents the current item within a container or set of related elements. + +## Description + +When you have a group of related elements, such as several links in a breadcrumb or steps in a multi-step flow, with one element in the group styled differently from the others to indicate to the sighted user that this is the current element within its group, the `aria-current` should be used to inform the assistive technology user what has been indicated via styling. + +In a breadcrumb list, when a link within a set of pagination links is styled to indicate the user is currently on that page, `aria-current="page"` should be set on that link. In a multi step based process with a step indicator such as a multi-page survey or a multi step checkout or registration process, when the current step icon is visually different to represent that it is the current step, that icon's container should have `aria-current="step"` for assistive technology users who may not be able to "see" the visual difference. + +The `aria-current` attribute indicates the element on which it is set, to a value other than `false`, represents the current item within a container or set of related elements. Only mark one element in a set of elements as current with `aria-current`. + +The `aria-current` attribute accepts a limited list of [values](#values) including `page`, `step`, `location`, `date`, `time`, `true`, and `false`. Any non-null string value not included in this list of enumerated values is treated as if `aria-current="true"` were set, not the default `false` value. If the attribute is not present, is an empty string, is present with no value, or is set to `aria-current="false"` it is not exposed to the user. + +When something is selected rather than current, such as a [`tab`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/tab_role) in a [`tablist`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/tablist_role), use [`aria-selected`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-selected) to indicate the currently-displayed tabpanel. + +> [!NOTE] +> Don't use `aria-current` as a substitute for [`aria-selected`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-selected) in [`gridcell`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/gridcell_role), [`option`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/option_role), [`row`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/row_role) or [`tab`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/tab_role). + +## Example + +The breadcrumb for the "current page" should have `aria-current="page"` set on it. + +```html +<nav aria-label="Breadcrumb" class="breadcrumb"> + <ol> + <li> + <a href="../../../../../">Web technology for developers</a> + </li> + <li> + <a href="../../../../">Accessibility</a> + </li> + <li> + <a href="../../../">ARIA</a> + </li> + <li> + <a href="../../">ARIA States and Properties</a> + </li> + <li> + <a href="./" aria-current="page">ARIA: `aria-current` attribute</a> + </li> + </ol> +</nav> +``` + +If the element representing the current page in the breadcrumb was not a link, the `aria-current` is optional. + +## Values + +- `page` + - : Represents the current page within a set of pages such as the link to the current document in a breadcrumb. +- `step` + - : Represents the current step within a process such as the current step in an enumerated multi step checkout flow. +- `location` + - : Represents the current location within an environment or context such as the image that is visually highlighted as the current component of a flow chart. +- `date` + - : Represents the current date within a collection of dates such as the current date within a calendar. +- `time` + - : Represents the current time within a set of times such as the current time within a timetable. +- `true` + - : Represents the current item within a set. +- `false` (default) + - : Does not represent the current item within a set. + +## Associated interfaces + +- {{domxref("Element.ariaCurrent")}} + - : The [`ariaCurrent`](/en-US/docs/Web/API/Element/ariaCurrent) property, part of the {{domxref("Element")}} interface, reflects the value of the `aria-current` attribute. +- {{domxref("ElementInternals.ariaCurrent")}} + - : The [`ariaCurrent`](/en-US/docs/Web/API/ElementInternals/ariaCurrent) property of the {{domxref("ElementInternals")}} interface reflects the value of the `aria-current` attribute. + +## Associated roles + +Usable in all roles; except for elements with the role of [`gridcell`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/gridcell_role), [`option`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/option_role), [`row`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/row_role) and [`tab`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/tab_role) where [`aria-selected`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-selected) should be used + +## Specifications + +{{Specifications}} + +## See also + +- [`aria-selected`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-selected) +- {{cssxref(':local-link')}} +- [Breadcrumb navigation with `aria-current`](/en-US/docs/Web/CSS/Layout_cookbook/Breadcrumb_Navigation) diff --git a/files/en-us/web/accessibility/aria/reference/attributes/aria-describedby/index.md b/files/en-us/web/accessibility/aria/reference/attributes/aria-describedby/index.md new file mode 100644 index 000000000000000..dedb10c135231f3 --- /dev/null +++ b/files/en-us/web/accessibility/aria/reference/attributes/aria-describedby/index.md @@ -0,0 +1,69 @@ +--- +title: "ARIA: aria-describedby attribute" +short-title: aria-describedby +slug: Web/Accessibility/ARIA/Reference/Attributes/aria-describedby +page-type: aria-attribute +spec-urls: + - https://w3c.github.io/aria/#aria-describedby + - https://www.w3.org/TR/wai-aria-1.2/#aria-describedby +sidebar: accessibilitysidebar +--- + +The global `aria-describedby` attribute identifies the element (or elements) that describes the element on which the attribute is set. + +## Description + +The `aria-describedby` attribute lists the [`id`](/en-US/docs/Web/HTML/Reference/Global_attributes/id)s of the elements that describe the object. It is used to establish a relationship between widgets or groups and the text that describes them. + +The `aria-describedby` attribute is not limited to form controls. It can also be used to associate static text with widgets, groups of elements, regions that have a heading, definitions, and more. The `aria-describedby` attribute can be used with semantic HTML elements and with elements that have an ARIA [`role`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles). + +The `aria-describedby` attribute is very similar to the [`aria-labelledby`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-labelledby) attribute. While `aria-labelledby` lists the `id`s of the labels or elements that describe the essence of an object, `aria-describedby` lists the `id`s of the descriptions or elements providing more information that the user might need. Both `aria-labelledby` and `aria-describedby` reference other elements to calculate a text alternative, but a label should be concise, while a description is intended to provide more verbose information; a label describes the essence of an object, while a description provides more information that the user might need. + +The elements linked via `aria-describedby` don't need to be visible. It is possible to reference an element even if that element is hidden. For example, a form control can have a description that is hidden by default and revealed on request using a disclosure widget like a "more information" icon. The sighted users click on the icon to view the description, while assistive technology users can immediately access it as the description is referenced from that form control with `aria-describedby`. + +The `aria-describedby` property is appropriate when the associated content contains plain text. If the content is extensive, contains useful semantics, or has a complex structure requiring user navigation, use [`aria-details`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-details) instead. `aria-details` allows assistive technology users to visit the associated structured content and provides additional navigation commands, making it easier to understand the structure, or to experience the information in smaller pieces. + +> [!NOTE] +> The `aria-describedby` content should only be a text string. If there are important underlying semantics in the content, consider using [`aria-details`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-details). + +## Example + +```html +<button aria-describedby="trash-desc">Move to trash</button> +… +<p id="trash-desc"> + Items in the trash will be permanently removed after 30 days. +</p> +``` + +> [!NOTE] +> The `aria-describedby` attribute is not designed to reference descriptions from external resources. As its value is one or more `id`s (space-separated if multiple), it must reference elements in the same DOM document. + +## Values + +- ID reference list + - : The `id` or space-separated list of element `id`s that describe the current element. + +## Associated interfaces + +- {{domxref("Element.ariaDescribedByElements")}} + - : The `ariaDescribedByElements` property is part of each element's interface. + Its value is an array of subclasses of {{domxref("Element")}} that reflect the `id` references in the `aria-describedby` attribute ([with some caveats](/en-US/docs/Web/API/Document_Object_Model/Reflected_attributes#reflected_element_references)). +- {{domxref("ElementInternals.ariaDescribedByElements")}} + - : The `ariaDescribedByElements` property is part of each custom element's interface. + Its value is an array of subclasses of {{domxref("Element")}} that reflect the `id` references in the `aria-describedby` attribute ([with some caveats](/en-US/docs/Web/API/Document_Object_Model/Reflected_attributes#reflected_element_references)). + +## Associated roles + +Used in **all** roles. Usable in all HTML elements as well. + +## Specifications + +{{Specifications}} + +## See also + +- [`aria-labelledby`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-labelledby) +- [`aria-description`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-description) +- [`aria-details`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-details) +- [Browser and AT support for `aria-describedby`](https://a11ysupport.io/tech/aria/aria-describedby_attribute) diff --git a/files/en-us/web/accessibility/aria/reference/attributes/aria-description/index.md b/files/en-us/web/accessibility/aria/reference/attributes/aria-description/index.md new file mode 100644 index 000000000000000..77d5d44992e4f3e --- /dev/null +++ b/files/en-us/web/accessibility/aria/reference/attributes/aria-description/index.md @@ -0,0 +1,58 @@ +--- +title: "ARIA: aria-description attribute" +short-title: aria-description +slug: Web/Accessibility/ARIA/Reference/Attributes/aria-description +page-type: aria-attribute +spec-urls: https://w3c.github.io/aria/#aria-description +sidebar: accessibilitysidebar +--- + +The global `aria-description` attribute defines a string value that describes or annotates the current element. + +> **Note:** `aria-description` is still in W3C Editor's Draft for ARIA 1.3. For the time being, continue to use [`aria-describedby`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-describedby), which has been supported since ARIA 1.1. + +## Description + +The global `aria-description` attribute provides a mechanism for the developer to describe or annotate the current element providing greater context for assistive technology users. + +```html +<div + role="application" + aria-label="calendar" + aria-description="Game schedule for the Boston Red Sox 2021 Season"> + <h1>Red Sox 2021</h1> + <div role="grid">…</div> +</div> +``` + +The `aria-description` attribute is similar to [`aria-label`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-label) in that both provide a text string to associate with the element, but a label should be short and concise, while the description can be longer as it is intended to provide more context and information. + +The `aria-description` and `aria-describedby` properties have the same purpose; both provide the user with additional descriptive text for the object on which it is set. If descriptive text is available in the DOM, use [`aria-describedby`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-describedby) instead. + +The `aria-description` property should only be used when providing a visible description is not the desired user experience. The `aria-describedby` attribute takes as its value a list of `id`s of the elements that contain descriptive text about the object. The `aria-description` is used when there is no appropriate descriptive text that can be associated with the object by `id` reference. If both attributes are present, `aria-describedby` takes precedence in defining the {{glossary("accessible description")}} property. + +The content of the description, whether set by `aria-description` or `aria-describedby`, should be flat text. If the content is very long, has semantic meaning requirements, or has a navigational structure, use [`aria-details`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-details) instead. + +## Values + +- `<string>` + - : The value is a string, an unconstrained value type, that is intended to be conveyed to the assistive technology user. + +## Associated interfaces + +- {{domxref("Element.ariaDescription")}} + - : The [`ariaDescription`](/en-US/docs/Web/API/Element/ariaDescription) property, part of the {{domxref("Element")}} interface, reflects the value of the `aria-description` attribute, which defines a string value that describes or annotates the current element. + +## Associated roles + +Used in **ALL** roles. + +## Specifications + +{{Specifications}} + +## See also + +- [HTML `title` attribute](/en-US/docs/Web/HTML/Reference/Global_attributes/title) +- [`aria-describedby`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-describedby) +- [`aria-details`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-details) diff --git a/files/en-us/web/accessibility/aria/reference/attributes/aria-details/index.md b/files/en-us/web/accessibility/aria/reference/attributes/aria-details/index.md new file mode 100644 index 000000000000000..5cb40c7de92cfa8 --- /dev/null +++ b/files/en-us/web/accessibility/aria/reference/attributes/aria-details/index.md @@ -0,0 +1,88 @@ +--- +title: "ARIA: aria-details attribute" +short-title: aria-details +slug: Web/Accessibility/ARIA/Reference/Attributes/aria-details +page-type: aria-attribute +spec-urls: https://w3c.github.io/aria/#aria-details +sidebar: accessibilitysidebar +--- + +The global `aria-details` attribute identifies the element (or elements) that provide additional information related to the object. + +## Description + +The `aria-details` attribute can be used to provide additional information or complex descriptions to an object. It is used to inform assistive technology users about the content by providing more in-depth information, whether that content is within the current document or a link to additional assets. + +There are other HTML and WAI-ARIA properties that have similar purposes. The HTML {{HTMLElement('label')}} element and the [`aria-label`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-label) and [`aria-labelledby`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-labelledby) properties are used to provide short labels for an object. The HTML `title` attribute and the [`aria-description`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-description) and [`aria-describedby`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-describedby) properties provide for longer plain text descriptions of an object. However, when additional information, complex descriptions, or navigable content related to the object is necessary and available, the `aria-details` attribute should be used. + +The `aria-details` attribute serves a similar purpose as HTML's never fully-supported `longdesc` attribute - a URL of a long description to a replaced element's content - which was deprecated due to lack of support and misuse. + +The `aria-details` attribute takes the [`id`](/en-US/docs/Web/HTML/Reference/Global_attributes/id), or space separated list of `id`s of the elements to get more detailed information as its values. When `aria-details` is included on an element, assistive technologies inform users of the availability of extended information, enabling the user to navigate to the referenced content. + +Elements referenced by `aria-details` are intended to contain more information than would normally be provided via [`aria-describedby`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-describedby). + +The elements referenced by `aria-details` should be visible to all users. `aria-details` informs users that otherwise might not be able to scan a screen and discern quickly that the explanatory content is available. + +> **Note:** `aria-details` has no impact on the accessible description. + +Unlike `aria-describedby`, elements referenced by `aria-details` are not used in accessible descriptions and are not turned into a plain string when presented to assistive technology users. If the associated content is not too long and flattening the contents of the referenced element to a simple string of text wouldn't cause loss of information, consider using `aria-describedby` instead. That said, it is valid for an element to have both `aria-details` and a description specified with either `aria-describedby` or `aria-description`. + +## Example + +When it comes to definition and term roles, the `aria-details` would be included on the [`term`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/term_role) element with the `id` of the element with a [`definition`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/definition_role) role. + +```html +<p> + The <strong>cubic-bezier()</strong> functional notation defines a cubic + <span role="term" aria-details="bezier bezImg">Bézier curve</span>. As these + curves are continuous, they are often used to smooth down the start and end of + the curve and are therefore sometimes called easing functions. +</p> + +<p role="definition" id="bezier"> + A <strong>Bézier curve</strong>, (Pronounced \ ˈbe-zē-ˌā \) + <i aria-description="English pronunciation">BEH-zee-ay</i>) is a + mathematically described curve used in computer graphics and animation. The + curve is defined by a set of control points with a minimum of two. Web related + graphics and animations use Cubic Béziers, which are curves with four control + points P<sub>0</sub>, P<sub>1</sub>, P<sub>2</sub>, and P<sub>3</sub>. +</p> + +<a + href="bezierExplanation.html" + id="bezImg" + aria-label="Explanation of Bézier curve in CSS easing functions"> + <img alt="Animated Bézier curve showing 4 control points." src="bezier.gif" /> +</a> +``` + +## Values + +- ID reference list + - : An `id` or space separated list of ids of elements that provide or link to additional related information. + +## Associated interfaces + +- {{domxref("Element.ariaDetailsElements")}} + - : The `ariaDetailsElements` property is part of each element's interface. + Its value is an array of subclasses of {{domxref("Element")}} that reflect the `id` references in the `aria-details` attribute ([with some caveats](/en-US/docs/Web/API/Document_Object_Model/Reflected_attributes#reflected_element_references)). +- {{domxref("ElementInternals.ariaDetailsElements")}} + - : The `ariaDetailsElements` property is part of each custom element's interface. + Its value is an array of subclasses of {{domxref("Element")}} that reflect the `id` references in the `aria-details` attribute ([with some caveats](/en-US/docs/Web/API/Document_Object_Model/Reflected_attributes#reflected_element_references)). + +## Associated roles + +Used in **ALL** roles. + +## Specifications + +{{Specifications}} + +## See also + +- HTML [id](/en-US/docs/Web/HTML/Reference/Global_attributes/id) attribute +- [`aria-labelledby`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-labelledby) +- [`aria-describedby`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-describedby) +- [`aria-description`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-description) +- [The image `alt` attribute](/en-US/docs/Web/API/HTMLImageElement/alt) +- HTML [title](/en-US/docs/Web/HTML/Reference/Global_attributes/title) attribute diff --git a/files/en-us/web/accessibility/aria/reference/attributes/aria-disabled/index.md b/files/en-us/web/accessibility/aria/reference/attributes/aria-disabled/index.md new file mode 100644 index 000000000000000..68dedbe0b311388 --- /dev/null +++ b/files/en-us/web/accessibility/aria/reference/attributes/aria-disabled/index.md @@ -0,0 +1,161 @@ +--- +title: "ARIA: aria-disabled attribute" +short-title: aria-disabled +slug: Web/Accessibility/ARIA/Reference/Attributes/aria-disabled +page-type: aria-attribute +spec-urls: https://w3c.github.io/aria/#aria-disabled +sidebar: accessibilitysidebar +--- + +The `aria-disabled` state indicates that the element is perceivable but disabled, so it is not editable or otherwise operable. + +## Description + +The `aria-disabled` attribute, when set to `true`, indicates that the element upon which it is set and all of its focusable descendants are meant to be in the disabled state. This declaration will inform people using assistive technologies, such as screen readers, that such elements are not meant to be editable or otherwise operable. + +Unlike HTML's [`disabled`](/en-US/docs/Web/HTML/Reference/Elements/input#disabled) Boolean attribute, which will communicate a form control as semantically being disabled, change its styling to reflect its state and suppress all functionality along with disallowing the element's value from participating in form submission, the `aria-disabled="true"` <strong>only</strong> semantically exposes these elements as being disabled. Web developers must manually ensure such elements have their functionality suppressed when exposed to the disabled state. + +When needing to disable native HTML form controls, developers will need to specify the `disabled` attribute, as it provides all of the generally expected features of disabling a control by default. However, there can be instances where elements need to be exposed as disabled, but are still available for users to find when navigating via the <kbd>Tab</kbd> key. Doing so can improve their discoverability as they will not be removed from the focus order of the web page, as `aria-disabled` does not change the focusability of such elements, nor will the elements be dimmed by default browser styling, making them easier to read. Some examples of where this may be useful include: + +- The header button element associated with non-collapsible accordion panel, +- A button which is important to keep in the page's focus order, but its action is presently unavailable - such as submitting a form, +- Temporarily inactive items in a menu widget that would otherwise be skipped over via standard keyboard navigation. + +In each of these cases, one may want users to find these elements through standard keyboard navigation, though the functionality of that control is removed or "disabled". Developers will still need to use JavaScript to fully disable the functionality of the element while also changing the appearance of the element so sighted users know it is disabled. + +> [!NOTE] +> The state of being disabled applies to the element with `aria-disabled="true"` and all of its focusable descendants. Take care when using this attribute on container elements. Particularly in the case where a container may have both form controls and links - where the intent may be to expose the form controls as being in the disabled state, but <strong>not</strong> to communicate the links as being "disabled". + +Another reason to use the `aria-disabled` attribute over the HTML `disabled` attribute is if you have created custom controls which need to be marked as disabled, but are not using an element that allows for the `disabled` attribute. For instance, in the following snippet a `<div>` was used to create a custom button which needs to be marked as disabled. However, the `<div>` element does not expect, nor respect the `disabled` attribute - even if it were to be given a `role="button"` to change its exposed ARIA role. The `aria-disabled` attribute is required to disable such custom controls. + +```html +<div role="button" aria-disabled="true" tabindex="-1">Edit</div> +``` + +Similarly to needing to use JavaScript to ensure an element with `aria-disabled="true"` is not functional, the element will also need styling adjustments. In contrast to the HTML `disabled` attribute, where specifying it provides `:disabled` user-agent styles to be applied, adding `aria-disabled="true"` doesn't. The element can be styled with the [attribute selector](/en-US/docs/Web/CSS/Attribute_selectors) `[aria-disabled="true"]`. + +```css +[aria-disabled="true"] { + opacity: 0.5; +} +``` + +If you are purposefully using the `aria-disabled` attribute to allow for a form control to remain in the page's keyboard focus order, particularly if the element represents important content that all users should be able to perceive, then you may need to use styling that still passes color contrast requirements. For instance, a disabled button/heading that introduces a non-collapsible accordion panel is content that still needs to be legible. + +```css +@media (forced-colors: active) { + [aria-disabled="true"] { + border-color: GrayText; + color: GrayText; + } +} +``` + +The [`forced-colors` media query](/en-US/docs/Web/CSS/@media/forced-colors) detects if the [user agent](/en-US/docs/Glossary/User_agent) has enabled a forced colors mode; if so, the text and border colors are both set to the [system color `greyText`](/en-US/docs/Web/CSS/system-color#syntax). + +Another thing to keep in mind, when using `aria-disabled` over the native HTML attribute, is that the ARIA attribute will require the manual styling necessary to visually communicate the element as disabled in Windows High Contrast Mode. + +> [!NOTE] +> If you are using CSS's [`pointer-events: none;`](/en-US/docs/Web/CSS/pointer-events) to make an element non-clickable, make sure you disable interactivity with JavaScript as well. `pointer-events: none;` prevents mouse clicks, but does not prevent the element from being activated via the keyboard. + +```js +function onClick(event) { + event.preventDefault(); +} + +function toggleDisabled(element, status, update) { + if (status) { + // element.input.disabled = false; + element.setAttribute("aria-disabled", "false"); + update.textContent = "The element is now enabled."; + element.addEventListener("click", onClick); + } else { + // element.input.disabled = true; + element.setAttribute("aria-disabled", "true"); + update.textContent = "The element is now disabled."; + element.removeEventListener("click", onClick); + } +} +``` + +When toggling from `aria-disabled="true"` to `"false"`, use JavaScript to: + +1. Toggle the value to `false` (or remove the attribute entirely), +2. Enable the element, and +3. Let the user know the control is now enabled. + +If you used just CSS to style the disabled state using an attribute selector, the selector will no longer match and the disabled styling will no longer be in effect. + +## Values + +- `true` + + - : The element is disabled + +- `false` + - : The element is not disabled + +## Associated interfaces + +- {{domxref("Element.ariaDisabled")}} + - : The [`ariaDisabled`](/en-US/docs/Web/API/Element/ariaDisabled) property, part of the {{domxref("Element")}} interface, reflects the value of the `aria-disabled` attribute, which indicates that the element is perceivable but disabled, so it is not editable or otherwise operable. +- {{domxref("ElementInternals.ariaDisabled")}} + - : The [`ariaDisabled`](/en-US/docs/Web/API/ElementInternals/ariaDisabled) property of the {{domxref("ElementInternals")}} interface reflects the value of the `aria-disabled` attribute. + +## Associated roles + +Used in roles: + +- [`application`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/application_role) +- [`button`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/button_role) +- [`composite`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/composite_role) +- [`gridcell`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/gridcell_role) +- [`group`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/group_role) +- [`input`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/input_role) +- [`link`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/link_role) +- [`menuitem`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/menuitem_role) +- [`scrollbar`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/scrollbar_role) +- [`separator`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/separator_role) +- [`tab`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/tab_role) + +Inherits into roles: + +- [`checkbox`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/checkbox_role) +- [`columnheader`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/columnheader_role) +- [`combobox`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/combobox_role) +- [`grid`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/grid_role) +- [`listbox`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/listbox_role) +- [`menu`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/menu_role) +- [`menubar`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/menubar_role) +- [`menuitemcheckbox`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/menuitemcheckbox_role) +- [`menuitemradio`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/menuitemradio_role) +- [`option`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/option_role) +- [`radio`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/radio_role) +- [`radiogroup`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/radiogroup_role) +- [`row`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/row_role) +- [`rowheader`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/rowheader_role) +- [`searchbox`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/searchbox_role) +- [`select`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/select_role) +- [`slider`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/slider_role) +- [`spinbutton`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/spinbutton_role) +- [`switch`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/switch_role) +- [`tablist`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/tablist_role) +- [`textbox`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/textbox_role) +- [`toolbar`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/toolbar_role) +- [`tree`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/tree_role) +- [`treegrid`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/treegrid_role) +- [`treeitem`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/treeitem_role) + +## Specifications + +{{Specifications}} + +## See also + +- [Making disabled buttons more inclusive](https://css-tricks.com/making-disabled-buttons-more-inclusive/) by Sandrina Pereira +- [Styling for Windows high contrast with new standards for forced colors](https://blogs.windows.com/msedgedev/2020/09/17/styling-for-windows-high-contrast-with-new-standards-for-forced-colors/) +- [disabled](/en-US/docs/Web/HTML/Reference/Attributes/disabled) +- {{domxref("Element.ariaDisabled")}} +- {{domxref("ElementInternals.ariaDisabled")}} +- [`aria-hidden`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-hidden) +- [`aria-readonly`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-readonly) diff --git a/files/en-us/web/accessibility/aria/reference/attributes/aria-dropeffect/index.md b/files/en-us/web/accessibility/aria/reference/attributes/aria-dropeffect/index.md new file mode 100644 index 000000000000000..6778f3a66e23991 --- /dev/null +++ b/files/en-us/web/accessibility/aria/reference/attributes/aria-dropeffect/index.md @@ -0,0 +1,64 @@ +--- +title: "ARIA: aria-dropeffect attribute" +short-title: aria-dropeffect +slug: Web/Accessibility/ARIA/Reference/Attributes/aria-dropeffect +page-type: aria-attribute +status: + - deprecated +spec-urls: https://w3c.github.io/aria/#aria-dropeffect +sidebar: accessibilitysidebar +--- + +The global `aria-dropeffect` attribute indicates what functions may be performed when a dragged object is released on the drop target. {{deprecated_inline}} + +## Description + +Deprecated in ARIA 1.1, the `aria-dropeffect` property indicates what functions may be performed when a dragged object is released on the drop target. The global `aria-dropeffect` attribute provides assistive technology users the same information provided via the [`DataTransfer.dropEffect`](/en-US/docs/Web/API/DataTransfer/dropEffect) to sited users via the dropeffect icon. + +Text selections, images, and links can be dragged by default. Setting the global [`draggable="true"`](/en-US/docs/Web/HTML/Reference/Global_attributes/draggable) attribute, part of HTML5's [Drag and Drop API](/en-US/docs/Web/API/HTML_Drag_and_Drop_API), with a [`dragstart` event handler](/en-US/docs/Web/API/HTMLElement/dragstart_event), means any DOM node can be made draggable as well. + +When a drag event occurs, a translucent image is generated of the dragged element which follows the user's pointer during the drag. The default image can be changed to any image with [`setDragImage`](/en-US/docs/Web/API/DataTransfer/setDragImage). Along with the default image identifying the element being dragged, there is a [`dataTransfer.dropEffect`](/en-US/docs/Web/API/DataTransfer/dropEffect) property that can be used to control the visual feedback the user is given during a drag-and-drop operation. The `aria-dropeffect` property should be used to provide assistive technology users the same feedback provided to sited users via `dataTransfer.dropEffect` property. + +`dropeffect` defines which cursor the browser displays while dragging, and is set on the element on which the element may be dropped. During the drag operation, as the draggable element is dragged over different drop areas, the drag effects—both the `dataTransfer.dropeffect` and the `aria-dropeffect` should be modified to indicate the type of operation that will occur if the dragged element is released. + +More than one drop effect may be supported for a given element. Therefore, the value of the `aria-dropeffect` attribute is a space separated list of functions. Functions include `copy`, `execute`, `link`, and `move`. The default is `none`, meaning there is no supported functionality in the application. Setting `aria-dropeffect="popup"` informs assistive technology users that there is a popup menu or dialog of drag operations from which the user can choose. + +Including the attribute provides assistive technologies the ability to convey the possible drag options available to the assistive technology user, but doesn't add any actual functionality. + +The `aria-dropeffect` property is expected to be replaced by a new feature in a future version of WAI-ARIA and is considered deprecated. + +Typically, drop effect functions can only be provided once an object has been grabbed for a drag operation, as the drop effect functions available are dependent on the object being dragged. Therefore, you'll generally add `aria-dropeffect` to all the potential drop targets when the {{domxref("HTMLElement/dragstart_event", "dragstart")}} event is fired. + +## Values + +The value is a space separated list of possible actions. The following are the valid tokens: + +- `copy` + - : A duplicate of the source object will be dropped into the target. +- `execute` + - : A function supported by the drop target is executed, using the drag source as an input. +- `link` + - : A reference or shortcut to the dragged object will be created in the target object. +- `move` + - : The source object will be removed from its current location and dropped into the target. +- `none` (default) + - : No operation can be performed; effectively cancels the drag operation if an attempt is made to drop on this object. Ignored if combined with any other token value; for example, 'none copy' is equivalent to a 'copy' value. +- `popup` + - : There is a popup menu or dialog that allows the user to choose one of the drag operations (copy, move, link, execute) and any other drag functionality, such as cancel. + +## Associated roles + +Used in **ALL** roles. + +## Specifications + +{{Specifications}} + +## See also + +- [`aria-grabbed`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-grabbed) +- [HTML global `draggable` attribute](/en-US/docs/Web/HTML/Reference/Global_attributes/draggable) +- HTML [Drag and Drop API](/en-US/docs/Web/API/HTML_Drag_and_Drop_API) +- {{domxref('dataTransfer')}} +- {{domxref('DataTransfer.dropEffect')}} +- {{domxref("HTMLElement/dragstart_event", "dragstart")}} diff --git a/files/en-us/web/accessibility/aria/reference/attributes/aria-errormessage/index.md b/files/en-us/web/accessibility/aria/reference/attributes/aria-errormessage/index.md new file mode 100644 index 000000000000000..f6a27d29c2ab867 --- /dev/null +++ b/files/en-us/web/accessibility/aria/reference/attributes/aria-errormessage/index.md @@ -0,0 +1,111 @@ +--- +title: "ARIA: aria-errormessage attribute" +short-title: aria-errormessage +slug: Web/Accessibility/ARIA/Reference/Attributes/aria-errormessage +page-type: aria-attribute +spec-urls: https://w3c.github.io/aria/#aria-errormessage +sidebar: accessibilitysidebar +--- + +The `aria-errormessage` attribute on an object identifies the element(s) that provides an error message for that object. + +## Description + +When there is a user-created error, you want to let the user know it exists and tell them how to fix it. There are two attributes you need to use: set [`aria-invalid="true"`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-invalid) to define the object as being in an error state, then add the `aria-errormessage` attribute with the value being the `id` of the element (or elements) containing the error message text for that object. + +The `aria-errormessage` attribute should only be used when the value of an object is not valid; when [`aria-invalid`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-invalid) is set to `true`. If the object is valid and you include the `aria-errormessage` attribute, make sure the element referenced is hidden, as the message it contains is not relevant. + +When `aria-errormessage` is relevant, the element(s) it references must be visible so users can see or hear the error message. + +Often times, you will want the element with the error message to be an [ARIA live region](/en-US/docs/Web/Accessibility/ARIA/Guides/Live_regions), such as when an error message is displayed to users after they have provided an invalid value. The error message should describe what is wrong and inform the user what is required to make the object valid. Adding the error message as an ARIA live region informs assistive technologies that the user may benefit from the error message content even if the error message wouldn't otherwise be conveyed to the user. + +Include a visible error message and link the invalid object with the `aria-errormessage` attribute if the failure is visually apparent and an explicit description of the error is necessary. + +## Example + +We create some styles to: + +1. Hide all error messages, +2. Make invalid objects appear invalid, and +3. Show error messages that are siblings coming after an invalid object. + +We use `aria-invalid="true"` to identify invalid objects: + +```css +.errormessage { + visibility: hidden; +} + +[aria-invalid="true"] { + outline: 2px solid red; +} + +[aria-invalid="true"] ~ .errormessage { + visibility: visible; +} +``` + +When an object is invalid, we use JavaScript to add `aria-invalid="true"`. The above CSS makes the `.errormessage` following an invalid object become visible. + +```html +<p> + <label for="email">Email address:</label> + <input + type="email" + name="email" + id="email" + aria-invalid="true" + aria-errormessage="err1" /> + <span id="err1" class="errormessage">Error: Enter a valid email address</span> +</p> +``` + +When we went from valid to invalid, the only JavaScript change for this example was an update to `aria-invalid` on the email input object. As the error message follows the input and becomes visible and available on the accessibility tree, we are able to keep our example simple. We could have also applied an [`aria-live`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-live) property or used a live region roles such as [`alert`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/alert_role). + +## Values + +- ID reference list + - : The `id` or space-separated list of element `id`s that contain the error message for the current element. + +## Associated interfaces + +- {{domxref("Element.ariaErrorMessageElements")}} + - : The `ariaErrorMessageElements` property is part of each element's interface. + Its value is an array of subclasses of {{domxref("Element")}} that reflect the `id` references in the `aria-errormessage` attribute ([with some caveats](/en-US/docs/Web/API/Document_Object_Model/Reflected_attributes#reflected_element_references)). +- {{domxref("ElementInternals.ariaErrorMessageElements")}} + - : The `ariaErrorMessageElements` property is part of each custom element's interface. + Its value is an array of subclasses of {{domxref("Element")}} that reflect the `id` references in the `aria-errormessage` attribute ([with some caveats](/en-US/docs/Web/API/Document_Object_Model/Reflected_attributes#reflected_element_references)). + +## Associated roles + +Used in roles: + +- [`application`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/application_role) +- [`checkbox`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/checkbox_role) +- [`combobox`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/combobox_role) +- [`gridcell`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/gridcell_role) +- [`listbox`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/listbox_role) +- [`radiogroup`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/radiogroup_role) +- [`slider`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/slider_role) +- [`spinbutton`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/spinbutton_role) +- [`textbox`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/textbox_role) +- [`tree`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/tree_role) + +Inherits from roles: + +- [`columnheader`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/columnheader_role) +- [`rowheader`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/rowheader_role) +- [`searchbox`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/searchbox_role) +- [`switch`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/switch_role) +- [`treegrid`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/treegrid_role) + +## Specifications + +{{Specifications}} + +## See also + +- CSS {{CSSxref(':invalid')}} pseudoclass +- [`aria-invalid`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-invalid) +- [`aria-describedby`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-describedby) +- [`aria-live`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-live) diff --git a/files/en-us/web/accessibility/aria/reference/attributes/aria-expanded/index.md b/files/en-us/web/accessibility/aria/reference/attributes/aria-expanded/index.md new file mode 100644 index 000000000000000..caef14d401d8185 --- /dev/null +++ b/files/en-us/web/accessibility/aria/reference/attributes/aria-expanded/index.md @@ -0,0 +1,124 @@ +--- +title: "ARIA: aria-expanded attribute" +short-title: aria-expanded +slug: Web/Accessibility/ARIA/Reference/Attributes/aria-expanded +page-type: aria-attribute +spec-urls: https://w3c.github.io/aria/#aria-expanded +sidebar: accessibilitysidebar +--- + +The `aria-expanded` attribute is set on an element to indicate if a control is expanded or collapsed, and whether or not the controlled elements are displayed or hidden. + +## Description + +There are several widgets that can be expanded and collapsed, including menus, dialogs, and accordion panels. Each of these objects, in turn, has an interactive element that controls their opening and closing. The `aria-expanded` attribute is applied to this focusable, interactive control that toggles the visibility of the object. + +For example, `aria-expanded` is applied to the parent item in a DOM tree to indicate whether its child branch is shown. The parent controls the visibility of the associated child branch, as well. + +There are two declarations that can be applied to objects that control the visibility of another object: [`aria-controls`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-controls), or [`aria-owns`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-owns) combined with `aria-expanded`. The `aria-controls` and `aria-owns` indicate the relationship between the controlling element and the controlled element. The `aria-expanded` indicates to assistive technology whether the controlled element is expanded or collapsed. + +Use the `aria-owns` property on the elements that own expandable grouping containers. If the expandable and collapsible grouping container is not owned by the element that has the `aria-expanded` attribute, use the `aria-controls` property to reference the grouping container instead. + +### Buttons + +A button that toggles a widget should have `aria-controls` set to the [`id`](/en-US/docs/Web/HTML/Reference/Global_attributes/id) of the toggled widget and `aria-expanded` set to the current state of the widget. + +```html +<button aria-expanded="false" aria-controls="widget1">Toggle widget</button> +``` + +When the widget is visible, the controlling object relays that information via having `aria-expanded="true"` set on it. The accessible name of the controlling object should reflect this change. + +```html +<button aria-expanded="true" aria-controls="widget1">Toggle widget</button> +``` + +### Menu + +When a [`menu`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/menu_role) is displayed, the button object that toggles the visibility of that menu has `aria-expanded="true"` set. When the menu is hidden, aria-expanded can be omitted. If specified when the menu is hidden, it should be set as `aria-expanded="false"`. When a child menu is not visible, its parent [`menuitem`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/menuitem_role) has `aria-expanded`. It should be set to `true` when the child menu is visible. + +### Combobox + +By default, some roles are hidden or collapsed and other roles are open or expanded by default. Elements with role [`combobox`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/combobox_role) have a default value for `aria-expanded` of `false`. When a combobox popup is not visible, the element with role `combobox` has `aria-expanded` set to `false`. This is the default state. When the popup element is visible, `aria-expanded` should be set to `true`. + +```html +<label for="username">Username</label> +<input id="username" name="username" aria-describedby="username-desc" /> +<button + aria-expanded="false" + aria-controls="username-desc" + aria-label="Help about username" + type="button"> + <span aria-hidden="true">?</span> +</button> +<p id="username-desc" hidden> + Your username is the name that you use to log in to this service. +</p> +``` + +> [!NOTE] +> The presence of the `aria-expanded` attribute indicates control. Avoid including it on elements that do not control the expanded state of other elements. + +### Treeitems + +Each element with role [`treeitem`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/treeitem_role) that serves as a parent node has `aria-expanded="false"` when the node is in a closed state and `aria-expanded="true"` when the node is in an open state. End nodes, nodes with no descendant nodes, should not have the `aria-expanded` attribute because, if they were to have it, they would be incorrectly described to assistive technologies as parent nodes. + +### Rows + +A parent row in a [`treegrid`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/treegrid_role) is a row that can be expanded or collapsed to show or hide a set of child rows in a table or grid. Each parent row has the `aria-expanded` state set on either the row element or on a cell contained in the row. When the child rows are hidden, `aria-expanded="false"` is set. `aria-expanded="true"` is set when the child rows are displayed. Rows that do not control the display of child rows should not include the `aria-expanded` attribute at all because including the attribute defines the rows as parent rows. + +## Values + +- `false` + + - : The grouping element this element owns or controls is collapsed. + +- `true` + + - : The grouping element this element owns or controls is expanded. + +- `undefined` (default) + - : The element does not own or control a grouping element that is expandable. + +## Associated interfaces + +- {{domxref("Element.ariaExpanded")}} + - : The [`ariaExpanded`](/en-US/docs/Web/API/Element/ariaExpanded) property, part of the {{domxref("Element")}} interface, reflects the value of the `aria-expanded` attribute. +- {{domxref("ElementInternals.ariaExpanded")}} + - : The [`ariaExpanded`](/en-US/docs/Web/API/Element/ariaExpanded) property, part of the {{domxref("ElementInternals")}} interface, reflects the value of the `aria-expanded` attribute. + +## Associated roles + +Used in roles: + +- [`application`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/application_role) +- [`button`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/button_role) +- [`checkbox`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/checkbox_role) +- [`combobox`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/combobox_role) +- [`gridcell`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/gridcell_role) +- [`link`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/link_role) +- [`listbox`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/listbox_role) +- [`menuitem`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/menuitem_role) +- [`row`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/row_role) +- [`rowheader`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/rowheader_role) +- [`tab`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/tab_role) +- [`treeitem`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/treeitem_role) + +Inherits into roles: + +- [`columnheader`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/columnheader_role) +- [`menuitemcheckbox`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/menuitemcheckbox_role) +- [`menuitemradio`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/menuitemradio_role) +- [`rowheader`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/rowheader_role) +- [`switch`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/switch_role) + +## Specifications + +{{Specifications}} + +## See also + +- [`aria-controls`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-controls) +- [`aria-owns`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-owns) +- [`aria-hidden`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-hidden) +- HTML [`hidden`](/en-US/docs/Web/HTML/Reference/Global_attributes/hidden) attribute diff --git a/files/en-us/web/accessibility/aria/reference/attributes/aria-flowto/index.md b/files/en-us/web/accessibility/aria/reference/attributes/aria-flowto/index.md new file mode 100644 index 000000000000000..06d941fa7ef73f6 --- /dev/null +++ b/files/en-us/web/accessibility/aria/reference/attributes/aria-flowto/index.md @@ -0,0 +1,53 @@ +--- +title: "ARIA: aria-flowto attribute" +short-title: aria-flowto +slug: Web/Accessibility/ARIA/Reference/Attributes/aria-flowto +page-type: aria-attribute +spec-urls: https://w3c.github.io/aria/#aria-flowto +sidebar: accessibilitysidebar +--- + +The global `aria-flowto` attribute identifies the next element (or elements) in an alternate reading order of content. This allows assistive technology to override the general default of reading in document source order at the user's discretion. + +## Description + +Web pages should be sequentially navigable. For this reason, developers are dissuaded from using the global [tabindex](/en-US/docs/Web/HTML/Reference/Global_attributes/tabindex) attribute which can change tab order and the CSS {{CSSXRef('order')}} property, which can change visual order from the DOM order. However, in rare circumstances a reading path different from the source order is required. For such cases, the `aria-flowto` attribute can make the content more accessible for users of assistive technologies. + +The global `aria-flowto` attribute lets the author indicate to assistive technology users which element or elements might want to be focused on next, providing an alternate reading order to the source order. This allows assistive technology to read a document in an order other than the default document source reading order. + +When `aria-flowto` has a single [id](/en-US/docs/Web/HTML/Reference/Global_attributes/id) reference, it allows assistive technologies to, at the user's request, go to the element targeted via that `id` instead of reading the document in the order of the DOM. When the `aria-flowto` value uses a space separated list of multiple `id` references, assistive technology can provide the user with a list of path choices, with each `id` referenced being a choice. The path choice names are determined by the accessible name of each target element of the `aria-flowto` attribute. + +> [!NOTE] +> Setting `aria-flowto` does not impact the content's tab order. It only provides users the option to follow a content path that doesn't match the DOM order when using tech that supports this attribute. + +## Values + +- `id` + - : The `id` of the next element in the alternate reading order. +- `id` list + - : Space separated list of values referencing the `id` values of elements the user may want to go to next in the alternate reading order of content. + +## Associated interfaces + +- {{domxref("Element.ariaFlowToElements")}} + - : The `ariaFlowToElements` property is part of each element's interface. + Its value is an array of instances of subclasses of {{domxref("Element")}} that reflect the `id` references in the `aria-flowto` attribute ([with some caveats](/en-US/docs/Web/API/Document_Object_Model/Reflected_attributes#reflected_element_references)). +- {{domxref("ElementInternals.ariaFlowToElements")}} + - : The `ariaFlowToElements` property is part of each custom element's interface. + Its value is an array of instances of subclasses of {{domxref("Element")}} that reflect the `id` references in the `aria-flowto` attribute ([with some caveats](/en-US/docs/Web/API/Document_Object_Model/Reflected_attributes#reflected_element_references)). + +## Associated roles + +Used in **ALL** roles. + +## Specifications + +{{Specifications}} + +## See also + +- HTML [id](/en-US/docs/Web/HTML/Reference/Global_attributes/id) attribute +- HTML [tabindex](/en-US/docs/Web/HTML/Reference/Global_attributes/tabindex) attribute +- CSS {{CSSXRef('order')}} property +- [WCAG: source order](/en-US/docs/Web/Accessibility/Guides/Understanding_WCAG/Operable#guideline_2.4_—_navigable_provide_ways_to_help_users_navigate_find_content_and_determine_where_they_are) +- [Using aria-flowto](https://www.w3.org/WAI/GL/wiki/Using_aria-flowto) - W3 Wiki diff --git a/files/en-us/web/accessibility/aria/reference/attributes/aria-grabbed/index.md b/files/en-us/web/accessibility/aria/reference/attributes/aria-grabbed/index.md new file mode 100644 index 000000000000000..b264321430331e2 --- /dev/null +++ b/files/en-us/web/accessibility/aria/reference/attributes/aria-grabbed/index.md @@ -0,0 +1,53 @@ +--- +title: "ARIA: aria-grabbed attribute" +short-title: aria-grabbed +slug: Web/Accessibility/ARIA/Reference/Attributes/aria-grabbed +page-type: aria-attribute +status: + - deprecated +spec-urls: https://w3c.github.io/aria/#aria-grabbed +sidebar: accessibilitysidebar +--- + +The `aria-grabbed` state indicates an element's "grabbed" state in a drag-and-drop operation. {{deprecated_inline}} + +## Description + +Text selections, images, and links can be dragged by default. Setting the global [`draggable="true"`](/en-US/docs/Web/HTML/Reference/Global_attributes/draggable) attribute, part of HTML5's [Drag and Drop API](/en-US/docs/Web/API/HTML_Drag_and_Drop_API), with a [`dragstart` event handler](/en-US/docs/Web/API/HTMLElement/dragstart_event), means any DOM node can be made draggable as well. + +The `aria-grabbed` attribute was used to indicate if an element is in a "grabbed" state in a drag-and-drop operation with `aria-grabbed="true"` or if that the element is grabbable, but not currently grabbed with `aria-grabbed="false"`. + +Setting `aria-grabbed="true"` indicated the element had been selected for dragging. Setting `aria-grabbed="false"` indicated that the element could be grabbed for a drag-and-drop operation, but is not currently grabbed. + +When `aria-grabbed` is set to `true`, the [`aria-dropeffect`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-dropeffect) attribute of all potential drop targets should be updated with the type of function, or effect, will occur to the grabbed element when it is dropped. When no element is in a grabbed state, revert the `aria-dropeffect` attributes of all your drop targets. + +The `aria-grabbed` property is expected to be replaced by a new feature in a future version of WAI-ARIA and is considered deprecated. + +> [!NOTE] +> ARIA does not enable accessible functionality. ARIA only conveys the intended behavior of your functionality. + +## Values + +- `true` + - : The element has been selected for dragging. +- `false` + - : The element is not currently selected for dragging, but can be made available for dragging by setting the property to `true`. +- `undefined` (default) + - : The element does not support being dragged + +## Associated roles + +Used in **ALL** [roles](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles) + +## Specifications + +{{Specifications}} + +## See also + +- [`aria-dropeffect`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-dropeffect) +- [HTML global `draggable` attribute](/en-US/docs/Web/HTML/Reference/Global_attributes/draggable) +- HTML [Drag and Drop API](/en-US/docs/Web/API/HTML_Drag_and_Drop_API) +- {{domxref('dataTransfer')}} +- {{domxref('DataTransfer.dropEffect')}} +- {{domxref("HTMLElement/dragstart_event", "dragstart")}} diff --git a/files/en-us/web/accessibility/aria/reference/attributes/aria-haspopup/index.md b/files/en-us/web/accessibility/aria/reference/attributes/aria-haspopup/index.md new file mode 100644 index 000000000000000..6c62530b1e1404a --- /dev/null +++ b/files/en-us/web/accessibility/aria/reference/attributes/aria-haspopup/index.md @@ -0,0 +1,92 @@ +--- +title: "ARIA: aria-haspopup attribute" +short-title: aria-haspopup +slug: Web/Accessibility/ARIA/Reference/Attributes/aria-haspopup +page-type: aria-attribute +spec-urls: https://w3c.github.io/aria/#aria-haspopup +sidebar: accessibilitysidebar +--- + +The `aria-haspopup` attribute indicates the availability and type of interactive popup element that can be triggered by the element on which the attribute is set. + +## Description + +In ARIA, interactive menus, listboxes, trees, grids, and dialogs that appear on top of other content when triggered to appear are considered "popups". These popups are triggered by one or more interactive elements on the page. The availability and type of popup the interactive element will trigger should be identified with the `aria-haspopup` state. + +The presence of the `aria-haspopup`, with one of six enumerated values - `menu`, `listbox`, `tree`, `grid`, `dialog`, or `true` - indicates the element can trigger a popup and what kind of popup will be displayed. In turn, the element that pops up must be of the role indicated. The value `true` is the same as `menu`. Any other value, including an empty string or other [role](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles), is treated as if `false` were set. + +A [`tooltip`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/tooltip_role) is not considered to be a popup in this context, as it is not interactive. + +> [!NOTE] +> Make sure the role of the element that serves as the container for the popup content is a [`menu`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/menu_role), [`listbox`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/listbox_role), [`tree`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/tree_role), [`grid`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/grid_role) or [`dialog`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/dialog_role) and that the value of `aria-haspopup` matches the role of the popup container. + +The `aria-haspopup` state informs assistive technology users that there is a popup and the type of popup it is, but provides no interactivity. For the popup to be keyboard accessible, make sure the element with `aria-haspopup` is focusable and can trigger the popup, that there is a keyboard mechanism for opening the popup, and that the popup element manages focus of all its descendants. + +> [!NOTE] +> ARIA does not enable accessible functionality. ARIA only conveys the intended behavior of your functionality. + +When creating a [`menubar`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/menubar_role), a parent [`menuitem`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/menuitem_role) should have `aria-haspopup="menu"` (or `true`) set. Any button that open a menu should have a role of [`button`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/button_role) or, preferably, be a {{HTMLElement('button')}}, and also have `aria-haspopup="menu"` (or `true`) set. [`Tab`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/tab_role) elements with popup menus should also have `aria-haspopup="menu"` set. Note that `menubar`s should not be used to create website navigation. + +> [!NOTE] +> Elements with role [`combobox`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/combobox_role) have an implicit `aria-haspopup` value of `listbox`. + +## Values + +- `false` (default) + - : The element does not have a popup. +- `true` + - : The popup is a menu. +- `menu` + - : The popup is a menu. +- `listbox` + - : The popup is a listbox. +- `tree` + - : The popup is a tree. +- `grid` + - : The popup is a grid. +- `dialog` + - : The popup is a dialog. + +## Associated interfaces + +- {{domxref("Element.ariaHasPopup")}} + - : The [`ariaHasPopup`](/en-US/docs/Web/API/Element/ariaHasPopup) property, part of the {{domxref("Element")}} interface, reflects the value of the `aria-haspopup` attribute, which indicates the availability and type of interactive popup element, such as menu or dialog, that can be triggered by an element. +- {{domxref("ElementInternals.ariaHasPopup")}} + - : The [`ariaHasPopup`](/en-US/docs/Web/API/ElementInternals/ariaHasPopup) property of the {{domxref("ElementInternals")}} interface reflects the value of the `aria-haspopup` attribute. + +## Associated roles + +Used in roles: + +- [`application`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/application_role) +- [`button`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/button_role) +- [`combobox`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/combobox_role) +- [`gridcell`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/gridcell_role) +- [`link`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/link_role) +- [`menuitem`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/menuitem_role) +- [`slider`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/slider_role) +- [`tab`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/tab_role) +- [`textbox`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/textbox_role) +- [`treeitem`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/treeitem_role) + +Inherited into roles: + +- [`columnheader`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/columnheader_role) +- [`menuitemcheckbox`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/menuitemcheckbox_role) +- [`menuitemradio`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/menuitemradio_role) +- [`rowheader`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/rowheader_role) +- [`searchbox`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/searchbox_role) + +## Specifications + +{{Specifications}} + +## See also + +- [`aria-controls`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-controls) +- [`menu`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/menu_role) +- [`listbox`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/listbox_role) +- [`tree`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/tree_role) +- [`grid`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/grid_role) +- [`dialog`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/dialog_role) +- [Toolbar example](https://www.w3.org/WAI/ARIA/apg/patterns/toolbar/examples/toolbar/) - W3C WAI ARIA practices diff --git a/files/en-us/web/accessibility/aria/reference/attributes/aria-hidden/index.md b/files/en-us/web/accessibility/aria/reference/attributes/aria-hidden/index.md new file mode 100644 index 000000000000000..ea11dc98be6abd5 --- /dev/null +++ b/files/en-us/web/accessibility/aria/reference/attributes/aria-hidden/index.md @@ -0,0 +1,95 @@ +--- +title: "ARIA: aria-hidden attribute" +short-title: aria-hidden +slug: Web/Accessibility/ARIA/Reference/Attributes/aria-hidden +page-type: aria-attribute +spec-urls: https://w3c.github.io/aria/#aria-hidden +sidebar: accessibilitysidebar +--- + +The `aria-hidden` state indicates whether the element is exposed to an accessibility API. + +## Description + +The `aria-hidden` attribute can be used to hide non-interactive content from the accessibility API. + +Adding `aria-hidden="true"` to an element removes that element and all of its children from the accessibility tree. This can improve the experience for assistive technology users by hiding: + +- Purely decorative content, such as icons or images +- Duplicated content, such as repeated text +- Offscreen or collapsed content, such as menus + +The presence of the `aria-hidden` attribute hides content from assistive technology but doesn't visually hide anything. + +`aria-hidden="true"` should not be used on elements that can receive focus. Additionally, since this attribute is inherited by an element's children, it should not be added onto the parent or ancestor of a focusable element. + +> [!WARNING] +> Do not use `aria-hidden="true"` on focusable elements. + +An element's hidden status is based on whether it is rendered. Rendering is usually controlled by CSS. For example, an element whose `display` property is set to `none` via CSS is not rendered. An element is considered hidden if it, or any of its ancestors are not rendered or have their `aria-hidden` attribute value set to true. Note that an element and its children that has `aria-hidden="true"` declared on it will still be visible, unless also hidden by CSS. + +Use caution when using `aria-hidden` to hide visibly rendered content from assistive technologies. You should not be hiding visible content unless doing so improves the experience for users of assistive technologies by removing redundant or extraneous content. Only when identical or equivalent meaning and functionality is exposed to assistive technologies can removing visible content from the accessibility API be considered. + +> [!NOTE] +> Consider all disabilities when hiding visibly rendered content from assistive technologies. Not all users of assistive technology are visually impaired. If visible content doesn't match text content in the accessibility API, the user experience will be negatively impacted for sighted users. + +On the surface, the `aria-hidden="true"` and the `role="presentation"` and its synonym `role="none"` seem similar, but the intent behind each is different. + +- `aria-hidden="true"` will remove the entire element from the accessibility API. +- `role="presentation"` and `role="none"` will remove the semantic meaning of an element while still exposing it and its content to assistive technology. + +`aria-hidden="true"` should not be added when: + +- The HTML [`hidden`](/en-US/docs/Web/HTML/Reference/Global_attributes/hidden) attribute is present +- The element or the element's ancestor is hidden with [`display: none`](/en-US/docs/Web/CSS/display) +- The element or the element's ancestor is hidden with [`visibility: hidden`](/en-US/docs/Web/CSS/visibility) + +In all three scenarios, the attribute is unnecessary to add because the element has already been removed from the accessibility tree. Visually hiding elements with `display` or `visibility` hides content from the screen and from assistive technologies. + +Using `aria-hidden="false"` will not re-expose the element to assistive technology if any of its parents specify `aria-hidden="true"`. + +## Example + +Adding `aria-hidden="true"` to the icon hides the icon character from being included in the accessible name. + +```html +<button> + <span class="fa fa-tweet" aria-hidden="true"></span> + <span class="label"> Tweet </span> +</button> +``` + +We have a button with [a Font Awesome icon](https://fontawesome.com/). We hide the icon from assistive technologies with `aria-hidden="true"`, as exposing the icon to assistive technologies could lead to redundancy or, if the icon doesn't have the same content as the visible text, confusion. + +## Values + +- `false` + - : The element is exposed to the accessibility API as if it was rendered. +- `true` + - : The element is hidden from the accessibility API. +- `undefined` (default) + - : The element's hidden state is determined by the user agent based on whether it is rendered. + +## Associated interfaces + +- {{domxref("Element.ariaHidden")}} + - : The [`ariaHidden`](/en-US/docs/Web/API/Element/ariaHidden) property, part of the {{domxref("Element")}} interface, reflects the value of the `aria-hidden` attribute, which Indicates whether the element is exposed to an accessibility API. +- {{domxref("ElementInternals.ariaHidden")}} + - : The [`ariaHidden`](/en-US/docs/Web/API/ElementInternals/ariaHidden) property, part of the {{domxref("ElementInternals")}} interface, reflects the value of the `aria-hidden` attribute + +## Associated roles + +Used in **ALL** roles + +## Specifications + +{{Specifications}} + +## See also + +- [`aria-disabled`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-disabled) +- [`aria-modal`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-modal) +- [`aria-expanded`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-expanded) +- HTML [`hidden`](/en-US/docs/Web/HTML/Reference/Global_attributes/hidden) attribute +- CSS {{CSSXref('display')}} property +- CSS {{CSSXref('visibility')}} property diff --git a/files/en-us/web/accessibility/aria/reference/attributes/aria-invalid/index.md b/files/en-us/web/accessibility/aria/reference/attributes/aria-invalid/index.md new file mode 100644 index 000000000000000..585ca823dfc96f5 --- /dev/null +++ b/files/en-us/web/accessibility/aria/reference/attributes/aria-invalid/index.md @@ -0,0 +1,171 @@ +--- +title: "ARIA: aria-invalid attribute" +short-title: aria-invalid +slug: Web/Accessibility/ARIA/Reference/Attributes/aria-invalid +page-type: aria-attribute +spec-urls: https://w3c.github.io/aria/#aria-invalid +sidebar: accessibilitysidebar +--- + +The `aria-invalid` state indicates the entered value does not conform to the format expected by the application. + +## Description + +The `aria-invalid` attribute is used to indicate that the value entered into an input field is not in a format or a value the application will accept. This may include formats such as email addresses or telephone numbers. `aria-invalid` can also be used to indicate that a required field is empty. + +The `aria-invalid` attribute can be used with any typical HTML form element, and is not limited to elements that have an ARIA role assigned. + +The attribute should be set with JavaScript as a result of a validation process. If a value is determined to be invalid or out-of-range, set `aria-invalid="true"` **and** tell the user there is an error. For better user experience, provide suggestions for how the error can be corrected. Do not set `aria-invalid="true"` on empty required elements until after the user attempts to submit the form. They may still be working on filling it out. + +> [!NOTE] +> When `aria-invalid` is used in conjunction with the `aria-required` attribute, `aria-invalid` should not be set to true before the form is submitted - only in response to validation. + +There are currently four values: in addition to `true` and `false` we have `grammar` which can be used when a grammatical error is detected and `spelling` for spelling errors. If the attribute is not present, or its value is false, or its value is an empty string, the default value of false applies. Any other value is treated as if `true` were set. + +### Native HTML validation + +HTML has native form validation. When a user submits a form with a control containing errors, the first form control with an invalid value displays an error message, natively. + +If there is a [`required`](/en-US/docs/Web/HTML/Reference/Attributes/required) attribute on a form control that isn't filled out, the form will not submit, and an error message appears reading "Please fill out this field" or something similar. The messaging for native validation varies depending on the browser, and cannot be styled. + +```html +<input type="number" step="2" min="0" max="100" required /> +``` + +If the user had entered a value in the preceding input example above the maximum, below the minimum, or that doesn't match the step value, an error message would appear. If the user had entered "3", the native error message would be similar to "Please enter a valid value." + +If you are creating your own form validation scripts, make sure to include `aria-invalid` on invalid form controls, along with styling (use the `[aria-invalid="true"]` attribute selector) and messaging (with [`aria-errormessage`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-errormessage)) to help users understand where the mistake is and how they can fix it. + +## Values + +- `grammar` + - : A grammatical error was detected. +- `false` (default) + - : There are no detected errors in the value. +- `spelling` + - : A spelling error was detected. +- `true` + - : The value entered by the user has failed validation. + +Any value not in this list will be treated as `true`. + +## Example + +The following snippet shows a simplified version of two form fields with a validation function attached to the blur event. Note that since the default value for `aria-invalid` is `false`, it is not strictly necessary to add the attribute to input. + +```html +<ul> + <li> + <label for="name">Full Name</label> + <input + type="text" + name="name" + id="name" + aria-required="true" + aria-invalid="false" /> + </li> + <li> + <label for="email">Email Address</label> + <input + type="email" + name="email" + id="email" + aria-required="true" + aria-invalid="false" /> + </li> +</ul> +``` + +```js +document.getElementById("name").addEventListener("blur", () => { + checkValidity( + "name", + " ", + "Invalid name entered (requires both first and last name)", + ); +}); + +document.getElementById("email").addEventListener("blur", () => { + checkValidity("email", "@", "Invalid email address"); +}); +``` + +Note that it is not necessary to validate the fields immediately on blur; the application could wait until the form is submitted (though this is not necessarily recommended). + +The snippet below shows a validation function, which only checks for the presence of a particular character (in the real world, validation will likely be more sophisticated): + +```js +function checkValidity(id, searchTerm, msg) { + const elem = document.getElementById(id); + if (elem.value.includes(searchTerm)) { + elem.setAttribute("aria-invalid", "false"); + updateAlert(); + } else { + elem.setAttribute("aria-invalid", "true"); + updateAlert(msg); + } +} +``` + +The snippet below shows the alert functions, which add (or remove) the error message: + +```js +function updateAlert(msg) { + const oldAlert = document.getElementById("alert"); + if (oldAlert) { + oldAlert.remove(); + } + + if (msg) { + const newAlert = document.createElement("div"); + newAlert.setAttribute("role", "alert"); + newAlert.setAttribute("id", "alert"); + const content = document.createTextNode(msg); + newAlert.appendChild(content); + document.body.appendChild(newAlert); + } +} +``` + +Note that the alert has the ARIA role attribute set to [`alert`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/alert_role). + +## Associated interfaces + +- {{domxref("Element.ariaInvalid")}} + - : The [`ariaInvalid`](/en-US/docs/Web/API/Element/ariaInvalid) property, part of the {{domxref("Element")}} interface, reflects the value of the `aria-invalid` attribute, which indicates whether the element is exposed to an accessibility API. +- {{domxref("ElementInternals.ariaInvalid")}} + - : The [`ariaInvalid`](/en-US/docs/Web/API/ElementInternals/ariaInvalid) property, part of the {{domxref("ElementInternals")}} interface, reflects the value of the `aria-invalid` attribute. + +## Associated roles + +Used in roles: + +- [`application`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/application_role) +- [`checkbox`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/checkbox_role) +- [`combobox`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/combobox_role) +- [`gridcell`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/gridcell_role) +- [`listbox`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/listbox_role) +- [`radiogroup`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/radiogroup_role) +- [`slider`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/slider_role) +- [`spinbutton`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/spinbutton_role) +- [`textbox`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/textbox_role) +- [`tree`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/tree_role) + +Inherited into role: + +- [`columnheader`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/columnheader_role) +- [`rowheader`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/rowheader_role) +- [`searchbox`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/searchbox_role) +- [`switch`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/switch_role) +- [`treegrid`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/treegrid_role) + +## Specifications + +{{Specifications}} + +## See also + +- [`aria-errormessage`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-errormessage) +- CSS {{CSSXRef(':valid')}} pseudoclass +- CSS {{CSSXRef(':invalid')}} pseudoclass +- [Form Validation](/en-US/docs/Learn_web_development/Extensions/Forms/Form_validation) tutorial diff --git a/files/en-us/web/accessibility/aria/reference/attributes/aria-keyshortcuts/index.md b/files/en-us/web/accessibility/aria/reference/attributes/aria-keyshortcuts/index.md new file mode 100644 index 000000000000000..eb907bb8da1b4cd --- /dev/null +++ b/files/en-us/web/accessibility/aria/reference/attributes/aria-keyshortcuts/index.md @@ -0,0 +1,137 @@ +--- +title: "ARIA: aria-keyshortcuts attribute" +short-title: aria-keyshortcuts +slug: Web/Accessibility/ARIA/Reference/Attributes/aria-keyshortcuts +page-type: aria-attribute +spec-urls: + - https://w3c.github.io/aria/#aria-keyshortcuts + - https://www.w3.org/WAI/ARIA/apg/practices/keyboard-interface/ +sidebar: accessibilitysidebar +--- + +The global `aria-keyshortcuts` attribute indicates keyboard shortcuts that an author has implemented to activate or give focus to an element. + +## Description + +A keyboard shortcut is a series of one or several keys that tells software to perform a pre-programmed action. Keyboard shortcuts enable keyboard users to invoke commands using the keyboard that would otherwise require accessing a menu or using touch or a mouse. The `aria-keyshortcuts` property defines the keyboard keys that have been implemented to activate or give focus to the element on which the attribute is set. + +The `aria-keyshortcuts` attribute exposes the existence of the shortcut to assistive technologies so the presence of the shortcut can be communicated to its users. Like all ARIA attributes, it has no effect on the functionality of the page; the keyboard behavior must be added via JavaScript event handlers. + +Keyboard shortcuts applied to disabled elements should also be disabled. For example, when disabling an element for mouse users, remember to disable it for keyboard shortcut users. + +Ensure all keyboard shortcuts are both visible to sighted users and made available to assistive technology. If your application is complex enough to need keyboard shortcuts, also known as "hot keys", include a guided tour of your application, an accessibility page documenting shortcuts and other accessibility features, a shortcut cheat sheet page or dialog pop up, or other method of making the availability of keyboard short cuts known. In addition, show the shortcut in menus and tooltips. + +### Property value rules + +The value of the `aria-keyshortcuts` attribute is a space-separated list of key combinations that can be pressed to activate a command or textbox widget. Each key combination includes zero, one or more modifier keys followed by exactly one non-modifier key to be pressed at the same time joined with a plus sign ("+"). The attribute value is case-insensitive. + +Examples of valid keyboard shortcuts include: + +```plain +aria-keyshortcuts="A" +aria-keyshortcuts="Shift+Space" +aria-keyshortcuts="Control+Alt+." +aria-keyshortcuts="Control+Shift+&#39;" +aria-keyshortcuts="alt+shift+p control+f" +aria-keyshortcuts="Meta+C Meta+Shift+C" +``` + +Modifier keys are keys that don't have any impact when used on their own. They are written as "Alt", "Control", "Shift", "Meta" (Command key on Mac), or "AltGraph" (Option key on Mac). + +Non-modifier keys are keys that have impact when used alone, be that printing a character, moving focus, or otherwise creating a keyboard event when used. Non-modifiers that print a single character include characters like `P`, `z` and `.`. + +Since the plus sign is used in writing key combinations, it is written as `plus` if used as the non-modifier. Other written-out non-modifiers include white space characters `Space`, `Tab`, and `Enter`, and all characters that result in actions, like `ArrowUp`, `PageUp`, and `Escape`. + +If you want to use a character that might cause problems, like a double quote character within double quotes, escape the character: `Control+&#39;`. + +Modifier keys must be listed first in each key combination. Possible key combinations include `Control+P` or `Shift+Space` and `Q`. If the full shortcut requires all three of these combinations in order, it would be written as `aria-keyshortcuts="Control+P Shift+Space Q"`. When a key combination includes more than one modifier key, the order of the modifiers doesn't matter, but they all must come first, before the non-modifier. + +These two attribute declarations are equivalent. + +```plain example-good +aria-keyshortcuts="Shift+Control+V" +aria-keyshortcuts="control+shift+v" +``` + +Note that text case doesn't matter. But order of non-modifier does. + +These two attribute declarations are invalid because the non-modifier must be last. + +```plain example-bad +aria-keyshortcuts="V+Shift+Control" +aria-keyshortcuts="V+Control+Shift" +``` + +The key combination listed must be the keys the user needs to press, not the outcome of the combined key strokes. For example, on a USA keyboard, if you need the `@` symbol, the key combination is written as `"Shift+2"`, not `"@"` nor `"Shift+@"`. + +### Best practices + +In trying to improve the accessibility of your sites and applications, there are some best practices to follow to ensure your "enhancements" don't negatively impact user experience. Remember, no ARIA is better than bad ARIA. + +#### Don't override browser, assistive technology, or operating system shortcuts + +When implementing keyboard shortcuts, make sure you don't create shortcuts that are already being used by the browser, assistive technology, or operating system, unless they are used for the same thing. For example, `"Control+P"` is used by most user-agents to initiate print functionality. Generally a web application should not create a "Control+P" shortcut as it will usurp browser functionality. There are exceptions. Web applications where printing is common, like email applications or document editors, usurping the browser's `"Control+P"` printing functionality for an application specific print flow would be expected. + +Unless you're creating an HTML version of a productivity application, you should likely avoid implementing keyboard shortcut. While overriding an operating system or browser keyboard shortcut can be annoying for non-assistive technology users, if you override a screen reader's keyboard functionality you can completely shut down access for the assistive technology user. If you must create keyboard shortcuts, avoid single letter keyboard shortcuts and common screen reader keyboard shortcuts. + +#### Consider language and keyboard differences + +Take into account the diversity of available keyboards and the various keyboard language preferences. Modifier keys are often used to create language specific common punctuation symbols and number characters. For example, numbers, when the keyboard language preference is set to French (France), use the Shift key. + +#### Don't use HTML instead + +The `aria-keyshortcuts` attribute is very similar to the [problematic](https://webaim.org/techniques/keyboard/accesskey#spec) HTML [`accesskey`](/en-US/docs/Web/HTML/Reference/Global_attributes/accesskey), which generates a keyboard shortcut for the current element. When an `accesskey` is defined for an element, the browser defines the modifiers and does all the work of handling the shortcut with no scripting required. Every browser and operating system combination has their own modifier keys for the non-modifier set in the `accesskey` attribute. What may work for one combination of operating system, assistive technology, and browser may not work with other combinations. With `aria-keyshortcuts`, the modifier keys are included in the attribute value list of key combinations and the functionality has to be scripted in. + +```html +<p> + Press the + <strong><u>S</u></strong + >tress reliever to relax! +</p> +<button accesskey="s">Stress reliever</button> +``` + +In this example, we ensured the presence of the shortcut was known to sighted users a well by highlighting the non-modifier character. + +While the goal of the `accesskey` attribute matches the intention of `aria-keyshortcuts` and to do so natively, `accesskey` is rife with issues. Because of these issues, it is generally advised not to use access keys for most general-purpose websites and web apps. + +In addition to poor browser support, the same concerns arise for `accesskey` as exist for `aria-keyshortcuts`: + +- An accesskey value can conflict with a system or browser keyboard shortcut, or assistive technology functionality. +- Certain key values may not be present on certain keyboards, especially when internationalization is a concern. So adapting to specific languages could cause further problems. +- Values that rely on numbers may be confusing to individuals experiencing cognitive concerns, where the number doesn't have a logical association with the functionality it triggers. +- Informing the user that shortcuts are present, so that they are aware of the functionality. If the system lacks a method of notifying the user about this feature, the user might accidentally activate a shortcut. + +## Values + +- `<string>` + - : The space-separated list of key combinations that, when pressed, perform the action. + +## Example + +In this example, the `aria-keyshortcuts` attribute on the element is set to "Alt+Shift+A". + +```html +<a href="#content" aria-keyshortcuts="Alt+Shift+A">Skip to content</a> +``` + +## Associated interfaces + +- {{domxref("Element.ariaKeyShortcuts")}} + - : The [`ariaKeyShortcuts`](/en-US/docs/Web/API/Element/ariaKeyShortcuts) property, part of the {{domxref("Element")}} interface, reflects the value of the `aria-keyshortcuts` attribute. +- {{domxref("ElementInternals.ariaKeyShortcuts")}} + - : The [`ariaKeyShortcuts`](/en-US/docs/Web/API/ElementInternals/ariaKeyShortcuts) property, part of the {{domxref("ElementInternals")}} interface, reflects the value of the `aria-keyshortcuts` attribute. + +## Associated roles + +Used in **ALL** roles. + +## Specifications + +{{Specifications}} + +## See also + +- [Keyboard Shortcuts](https://www.w3.org/WAI/ARIA/apg/practices/keyboard-interface/#keyboardshortcuts) section in ARIA Authoring Practices +- HTML [`accesskey`](/en-US/docs/Web/HTML/Reference/Global_attributes/accesskey) attribute +- [Issues with `accesskey`](https://webaim.org/techniques/keyboard/accesskey#spec) diff --git a/files/en-us/web/accessibility/aria/reference/attributes/aria-label/index.md b/files/en-us/web/accessibility/aria/reference/attributes/aria-label/index.md new file mode 100644 index 000000000000000..f18c9eaeb8dd6f9 --- /dev/null +++ b/files/en-us/web/accessibility/aria/reference/attributes/aria-label/index.md @@ -0,0 +1,112 @@ +--- +title: "ARIA: aria-label attribute" +short-title: aria-label +slug: Web/Accessibility/ARIA/Reference/Attributes/aria-label +page-type: aria-attribute +spec-urls: https://w3c.github.io/aria/#aria-label +sidebar: accessibilitysidebar +--- + +The `aria-label` attribute defines a string value that can be used to name an element, as long as the element's role does not [prohibit naming](#associated_roles). + +## Description + +Sometimes, the default {{Glossary("accessible_name", "accessible name")}} of an element is missing or the accessible name does not accurately describe the contents of the element and there is no content visible in the DOM that can be associated with the object to give it meaning. A common example of such an element is a button containing an SVG icon without any text. + +In cases where an element that is not part of the [prohibited list](#associated_roles), has no accessible name or an accessible name is not accurate and there is no content visible in the DOM that can be referenced via the [`aria-labelledby`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-labelledby) attribute, the `aria-label` attribute can be used to define a string that labels the interactive element on which it is set. This provides the element an accessible name. + +The code below shows an example of how to use the `aria-label` attribute to provide an accessible name for a `<button>` element. The button in this example contains an SVG graphic and lacks textual content, making the `aria-label` essential for screen reader users to understand its function, which in this case is "Close". + +```html +<button aria-label="Close"> + <svg + aria-hidden="true" + focusable="false" + width="17" + height="17" + xmlns="http://www.w3.org/2000/svg"> + <path + d="m.967 14.217 5.8-5.906-5.765-5.89L3.094.26l5.783 5.888L14.66.26l2.092 2.162-5.766 5.889 5.801 5.906-2.092 2.162-5.818-5.924-5.818 5.924-2.092-2.162Z" + fill="#000" /> + </svg> +</button> +``` + +```js +document.querySelector("button").addEventListener("click", () => { + myDialog.close(); +}); +``` + +> **Note:** `aria-label` is intended for naming elements where the implicit or explicit role does not prohibit naming. It is strongly recommended to prioritize the use of `aria-labelledby` over `aria-label` if a visible label exists for the element to reference and receive its name from. + +Most content has an accessible name generated from its immediate wrapping element's text content. Accessible names can also be created by certain attributes or associated elements. + +By default, a button's accessible name is the content between the opening and closing {{HTMLElement('button')}} tags, an image's accessible name is the content of its [`alt`](/en-US/docs/Web/HTML/Reference/Elements/img#alt) attribute, and a form input's accessible name is the content of the associated {{HTMLElement('label')}} element. + +If none of these options are available or if the default accessible name is not appropriate, use the `aria-label` attribute to define the accessible name of an element. + +> [!NOTE] +> While `aria-label` can be used on any element that can have an accessible name, in practice however, it is supported only on interactive elements, [widgets](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles#2._widget_roles), [landmarks](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles#3._landmark_roles), images, and iframes. + +When using `aria-label`, you also need to consider [`aria-labelledby`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-labelledby): + +- `aria-label` can be used in cases where text that could label the element is _not_ visible. If there is visible text that labels an element, use `aria-labelledby` instead. +- The purpose of `aria-label` is the same as `aria-labelledby`. Both provide an accessible name for an element. If there is no visible name for the element you can reference, use `aria-label` to provide the user with a recognizable accessible name. If label text is available in the DOM and it's possible to reference it for an acceptable user experience, prefer to use `aria-labelledby`. Don't use both on the same element because `aria-labelledby` will take precedence over `aria-label` if both are applied. + +Keep the following additional guidelines in mind when using `aria-label`: + +- The `aria-label` attribute can be used with regular, semantic HTML elements; it is not limited to elements that have an [ARIA `role`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles) assigned. +- Don't "overuse" `aria-label`. Remember that it's primarily for assistive technologies. To provide additional instructions or to clarify the UI, use visible text with `aria-describedby` or [`aria-description`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-description), not `aria-label`. Instructions should be accessible to all users, not just to those with screen readers (or preferably, make your UI more intuitive). + + > [!NOTE] + > Since `aria-label` content isn't displayed outside assistive technologies, consider making important information visible for all users. + +- Not all elements can be given an accessible name. Neither `aria-label` nor `aria-labelledby` should be used with inline structural roles such as with `code`, `term`, and `emphasis`, and roles not mapped to the accessibility API, including `none`. The `aria-label` attribute is intended for elements including links, videos, form controls, and those with [landmark roles](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles#3._landmark_roles) or [widget roles](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles#2._widget_roles); `aria-label` provides an accessible name when no visible label exists in the DOM. +- If you assign a `title` to an {{HTMLElement('iframe')}}, define an `alt` attribute for an {{HTMLElement('img')}}, or add {{HTMLElement('label')}} for an {{HTMLElement('input')}}, `aria-label` is not necessary. However, if an `aria-label` attribute is present, it will take precedence over the iframe's `title`, the image's `alt`, or the input's `<label>` text as the accessible name for that element. + +## Values + +- `<string>` + - : A string of text that will be the accessible name for the object. + +## Associated interfaces + +- {{domxref("Element.ariaLabel")}} + - : The [`ariaLabel`](/en-US/docs/Web/API/Element/ariaLabel) property, part of the {{domxref("Element")}} interface, reflects the value of the `aria-label` attribute. +- {{domxref("ElementInternals.ariaLabel")}} + - : The [`ariaLabel`](/en-US/docs/Web/API/ElementInternals/ariaLabel) property, part of the {{domxref("ElementInternals")}} interface, reflects the value of the `aria-label` attribute. + +## Associated roles + +Used in almost all roles **except** roles that cannot be provided an accessible name by the author. + +The `aria-label` attribute is **NOT** supported in: + +- [`code`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/structural_roles) +- [`caption`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/structural_roles) +- [`definition`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/structural_roles) +- [`deletion`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/structural_roles) +- [`emphasis`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/structural_roles) +- [`generic`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/generic_role) +- [`insertion`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/structural_roles) +- [`mark`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/mark_role) +- [`paragraph`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/structural_roles) +- [`presentation`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/presentation_role) / [`none`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/none_role) +- [`strong`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/structural_roles) +- [`subscript`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/structural_roles) +- [`superscript`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/structural_roles) +- [`suggestion`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/suggestion_role) +- [`term`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/term_role) +- [`time`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/structural_roles) + +## Specifications + +{{Specifications}} + +## See also + +- {{HTMLElement('label')}} element +- [`aria-description`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-description) +- [`aria-labelledby`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-labelledby) +- [Using HTML landmark roles to improve accessibility](/en-US/blog/aria-accessibility-html-landmark-roles/) on MDN blog (2023) diff --git a/files/en-us/web/accessibility/aria/reference/attributes/aria-labelledby/index.md b/files/en-us/web/accessibility/aria/reference/attributes/aria-labelledby/index.md new file mode 100644 index 000000000000000..5647df0d9e5a7ba --- /dev/null +++ b/files/en-us/web/accessibility/aria/reference/attributes/aria-labelledby/index.md @@ -0,0 +1,134 @@ +--- +title: "ARIA: aria-labelledby attribute" +short-title: aria-labelledby +slug: Web/Accessibility/ARIA/Reference/Attributes/aria-labelledby +page-type: aria-attribute +spec-urls: https://w3c.github.io/aria/#aria-labelledby +sidebar: accessibilitysidebar +--- + +The `aria-labelledby` attribute identifies the element (or elements) that labels the element it is applied to. + +## Description + +The `aria-labelledby` property enables authors to reference other elements on the page to define an accessible name. This is useful when using elements that don't have native support for associating elements to provide an accessible name. + +Some elements get their [accessible name](https://w3c.github.io/accname/#dfn-accessible-name) from their inner content. For example, the accessible name for a {{HTMLElement('button')}}, {{HTMLElement('a')}}, or {{HTMLElement('td')}} comes from the text between the opening and closing tags. Other elements, such as form {{HTMLElement('textarea')}}, {{HTMLElement('fieldset')}}, and {{HTMLElement('table')}} get their accessible name from the content of associated elements; for these elements, the accessible name comes from the {{HTMLElement('label')}} with a `for` attribute, {{HTMLElement('legend')}}, and {{HTMLElement('caption')}} respectively. + +All interactive elements must have an accessible name. `aria-labelledby` can be used to reference another element to define its accessible name, when an element's accessible name needs to use content from elsewhere in the DOM. + +If there is no content that can be referenced to create an accessible name, the [`aria-label`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-label) attribute should be used instead. + +The purpose of `aria-labelledby` is the same as that of `aria-label`. It provides the user with a recognizable, accessible name for an interactive element. If an element has both attributes set, `aria-labelledby` will be used. `aria-labelledby` takes precedence over all other methods of providing an accessible name, including `aria-label`, {{HTMLElement('label')}}, and the element's inner text. + +The `aria-labelledby` and [`aria-describedby`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-describedby) attributes both reference other elements to calculate text alternatives. `aria-labelledby` should reference brief text that provides the element with an accessible name. `aria-describedby` is used to reference longer content that provides a description. If there is no element in the DOM that provides a brief label appropriate for an accessible name for an interactive element, use `aria-label` to define the accessible name for an interactive element. + +> [!NOTE] +> While in American English, "labeled" is spelled with one "l", the "labelledby" spelling has been established and is the spelling used in accessibility APIs. + +The following example uses `aria-labelledby` to provide an accessible name for a checkbox input by using the text content of a sibling element: + +```html +<span + role="checkbox" + aria-checked="false" + tabindex="0" + aria-labelledby="tac"></span> +<span id="tac">I agree to the Terms and Conditions.</span> +``` + +Note that while using `aria-labelledby` is similar in this situation to using an HTML {{HTMLElement('label')}} element with the `for` attribute, there are some very important differences. The `aria-labelledby` attribute only defines the accessible name. It doesn't provide any of `<label>`'s other functionality, such as making clicking on the labeling element activate the input it is associated with. That has to be added back in with JavaScript. + +Fortunately, the HTML {{HTMLElement('input')}} with `type="checkbox"` works with native `<label>`. When feasible, use the following: + +```html +<label for="tac"> + <input id="tac" type="checkbox" name="terms-and-conditions" /> + I agree to the Terms and Conditions. +</label> +<p><a href="tac.html">Read our Terms and Conditions</a>.</p> +``` + +### Benefits (and drawbacks) + +1. The `aria-labelledby` property has the highest precedence when browsers calculate accessible names. Be aware that it overrides other methods of naming the element, including `aria-label`, other naming attributes, and even the element's contents. + + ```html + <button aria-label="Blue" aria-labelledby="color">Red</button> + <span id="color">Yellow</span> + ``` + + In this example, that accessible name is "Yellow". + +2. The `aria-labelledby` property takes as value a space-separated id reference list, which means you can combine more than one element into a single accessible name. You can include the [`id`](/en-US/docs/Web/HTML/Reference/Global_attributes/id) of the element itself to reference its own content. + + ```html + <h2 id="attr" class="article-title">13 ARIA attributes you need to know</h2> + <p> + There are over 50 ARIA states and properties, but 13 of them stand out… + <a href="13.html" id="rm13" aria-labelledby="rm13 attr">read more</a> + </p> + ``` + + In this example, the accessible name is "read more 13 ARIA attributes you need to know". + +3. The `aria-labelledby` property value order matters. When more than one element is referenced by `aria-labelledby`, the content from each referenced element is combined in the order that they are referenced in the `aria-labelledby` value. Had we written `aria-labelledby="attr rm13">`, the accessible name would have been "13 ARIA attributes you need to know read more". + +4. The `aria-labelledby` property ignores repeated `id`s in its value. If an element is referenced more than one time, only the first reference is processed. `aria-labelledby="attr attr rm13 rm13">` is treated as `aria-labelledby="attr rm13">` + +5. The `aria-labelledby` property value can include content from elements that aren't even visible. While you should provide assistive technology users with the same content as all other users, you can include content from elements with the HTML [`hidden`](/en-US/docs/Web/HTML/Reference/Global_attributes/hidden) attribute, CSS [`display: none`](/en-US/docs/Web/CSS/display), and CSS [`visibility: hidden`](/en-US/docs/Web/CSS/visibility) in the calculated name string. + +6. The `aria-labelledby` property incorporates the value of input elements. If the value references an `<input>`, the current value of the form control is included in the calculated name string, changing if the value is updated. + +7. The `aria-labelledby` property cannot be chained. If an element with `aria-labelledby` references another element that also has `aria-labelledby`, the `aria-labelledby` attribute on the referenced element is ignored. + +> [!WARNING] +> Because calculating the name of an element with `aria-labelledby` can be complex and reference hidden content, testing with assistive technologies to ensure the expected name is presented to users is very important. + +## Values + +- ID reference list + - : Space separated list of one or more ID values referencing the elements that label the current element. + +## Associated interfaces + +- {{domxref("Element.ariaLabelledByElements")}} + - : The `ariaLabelledByElements` property is part of each element's interface. + Its value is an array of subclasses of {{domxref("Element")}} that reflect the `id` references in the `aria-labelledby` attribute ([with some caveats](/en-US/docs/Web/API/Document_Object_Model/Reflected_attributes#reflected_element_references)). +- {{domxref("ElementInternals.ariaLabelledByElements")}} + - : The `ariaLabelledByElements` property is part of each custom element's interface. + Its value is an array of subclasses of {{domxref("Element")}} that reflect the `id` references in the `aria-labelledby` attribute ([with some caveats](/en-US/docs/Web/API/Document_Object_Model/Reflected_attributes#reflected_element_references)). + +## Associated roles + +Used in almost all roles **except** roles that can not be provided an accessible name by the author. + +The `aria-labelledby` attribute is **NOT** supported in: + +- [`code`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/structural_roles) +- [`caption`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/structural_roles) +- [`deletion`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/structural_roles) +- [`emphasis`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/structural_roles) +- [`generic`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/generic_role) +- [`insertion`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/structural_roles) +- [`mark`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/mark_role) +- [`paragraph`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/structural_roles) +- [`presentation`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/presentation_role) / [`none`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/none_role) +- [`strong`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/structural_roles) +- [`subscript`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/structural_roles) +- [`superscript`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/structural_roles) +- [`suggestion`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/suggestion_role) +- [`term`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/term_role) +- [`time`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/structural_roles) + +## Specifications + +{{Specifications}} + +## See also + +- HTML {{HTMLElement('label')}} element +- HTML {{HTMLElement('legend')}} element +- HTML {{HTMLElement('caption')}} element +- [`aria-label`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-label) +- [`aria-describedby`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-describedby) diff --git a/files/en-us/web/accessibility/aria/reference/attributes/aria-level/index.md b/files/en-us/web/accessibility/aria/reference/attributes/aria-level/index.md new file mode 100644 index 000000000000000..22cb4d2469a02f3 --- /dev/null +++ b/files/en-us/web/accessibility/aria/reference/attributes/aria-level/index.md @@ -0,0 +1,65 @@ +--- +title: "ARIA: aria-level attribute" +short-title: aria-level +slug: Web/Accessibility/ARIA/Reference/Attributes/aria-level +page-type: aria-attribute +spec-urls: https://w3c.github.io/aria/#aria-level +sidebar: accessibilitysidebar +--- + +The `aria-level` attribute defines the hierarchical level of an element within a structure. + +## Description + +Levels of hierarchy appear in headings, trees, nested grid, nested tablists, and more. If the DOM ancestry does not accurately represent the level, the `aria-level` attribute should be used to define the hierarchical level elements within their hierarchical structures. Levels increase with depth. The value for aria-level is an integer greater than or equal to `1`. + +When it comes to the headings in a document structure, you can have first-level headings, second-level headings, third-level headings, etc. In trees, you have the root element, its children, the children's children (or grandchildren), and so on. + +The `aria-level` attribute exposes hierarchy to assistive technologies so it can be communicated to the users. Like all ARIA attributes, it has no impact on the user agent and therefore no impact on the user agent's determination of the document structure. + +If the DOM ancestry accurately represents the level, the user agent can calculate the level of an item from the document structure, making `aria-level` not only redundant but a risk of creating misinformation. `aria-level` should really only be used to provide an explicit indication of level when it is not possible to calculate from the document structure. Test to see if this attribute is needed. If the user agent can calculate the level, it is best to omit the `aria-level` attribute. + +### With `heading` role + +The `aria-level` attribute is a required attribute of the [`heading`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/heading_role) role which indicates to assistive technologies that the element should be treated as a heading. `<div role="heading" aria-level="1">` defines the `<div>` as being the main heading of the page. A level 2 heading, defined with `aria-level="2"` would be the first subsection, a level 3 is a subsection of that, and so on. + +```html +<div role="heading" aria-level="3">Heading for this sub section</div> +``` + +Opt for using the {{htmlelement("Heading_Elements", "h1")}} through {{htmlelement("Heading_Elements", "h6")}} elements instead. + +### Within `treegrid` role + +In the case of a [`treegrid`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/treegrid_role), `aria-level` is supported on elements with the role [`row`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/row_role), not elements with role [`gridcell`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/gridcell_role). Rows act as leaf nodes within the vertical orientation of the grid. Gridcells are leaf nodes within the horizontal orientation of each row. `Aria-level` is not supported on cells within rows. So, in treegrids, the `aria-level` attribute is applied to the element with the role `row`. + +If a complete set of available nodes is not present in the DOM due to dynamic loading as the user moves focus in or scrolls the tree, each node has `aria-level`, [`aria-setsize`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-setsize), and [`aria-posinset`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-posinset) included. + +## Values + +- `<integer>` + - : An integer greater than or equal to 1 + +## Associated interfaces + +- {{domxref("Element.ariaLevel")}} + - : The [`ariaLevel`](/en-US/docs/Web/API/Element/ariaLevel) property, part of the {{domxref("Element")}} interface, reflects the value of the `aria-level` attribute. +- {{domxref("ElementInternals.ariaLevel")}} + - : The [`ariaLevel`](/en-US/docs/Web/API/ElementInternals/ariaLevel) property, part of the {{domxref("ElementInternals")}} interface, reflects the value of the `aria-level` attribute. + +## Associated roles + +Used in roles: + +- [`associationlistitemkey`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/structural_roles) +- [`comment`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/comment_role) +- [`heading`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/heading_role) +- [`row`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/row_role) + +## Specifications + +{{Specifications}} + +## See also + +- [`<h1>` through `<h6>`: The HTML Section Heading elements](/en-US/docs/Web/HTML/Reference/Elements/Heading_Elements) ({{htmlelement("Heading_Elements", "h1")}}, {{htmlelement("Heading_Elements", "h2")}}, {{htmlelement("Heading_Elements", "h3")}}, {{htmlelement("Heading_Elements", "h4")}}, {{htmlelement("Heading_Elements", "h5")}}, and {{htmlelement("Heading_Elements", "h6")}}) diff --git a/files/en-us/web/accessibility/aria/reference/attributes/aria-live/index.md b/files/en-us/web/accessibility/aria/reference/attributes/aria-live/index.md new file mode 100644 index 000000000000000..720e0f9857e77b3 --- /dev/null +++ b/files/en-us/web/accessibility/aria/reference/attributes/aria-live/index.md @@ -0,0 +1,90 @@ +--- +title: "ARIA: aria-live attribute" +short-title: aria-live +slug: Web/Accessibility/ARIA/Reference/Attributes/aria-live +page-type: aria-attribute +spec-urls: https://w3c.github.io/aria/#aria-live +sidebar: accessibilitysidebar +--- + +The global `aria-live` attribute indicates that an element will be updated, and describes the types of updates the user agents, assistive technologies, and user can expect from the live region. + +## Description + +When content changes after initial load, assistive technology (AT) users may not "see" the changes. Some changes are important. Others are not. The `aria-live` attribute enables developers to inform the user of updates and choose, based on importance and urgency, whether to immediately, proactively, or passively inform AT users of changes to the content. + +If a section of the screen updates, if it's styled in a way to be noticeable, most sighted users will generally notice live updates. Screen readers, on the other hand, only focus on one part of the page at a time; and that part may not be where the update is. The `aria-live` attribute provides a way for developers to announce such changes to AT based on event triggers set by the developer rather than by user initiated actions so they are made aware that the content has changed. + +```html +<div id="announce" aria-live="polite"></div> +``` + +The `aria-live` attribute is set on an **empty** element. When an update to the page occurs, the empty element with that `aria-live` attribute should be updated with a brief announcement informing the user an update has been made. + +```html +<div id="announce" aria-live="polite"> + <p>This message is announced.</p> +</div> +``` + +When the accessibility API recognizes a change to the live region above, it will announce the contents of that live region based on the value of the attribute. The element is **not** given focus. + +If you want all the contents of the live region to be read, use the [`aria-atomic`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-atomic). Use [`aria-relevant`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-relevant) to define only the sections of an update that need to be reread to the user. Use [`aria-busy`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-busy) to prevent announcements while updates are still being made. + +### Choosing the `aria-live` value + +As some assistive technology users can't "see" live updates, the `aria-live` attribute is used to define what updated information the user should be: + +- Made aware of immediately, +- Informed about if the opportunity avails itself, and +- Proactively informed about but can learn when they choose to focus on the updated area. + +`aria-live`'s value describes the types of updates the user agents, assistive technologies, and user can expect from the live region, and is used to express degrees of importance. + +When `aria-live`'s attribute is set to `polite`, assistive technologies will notify users of updates but generally do not interrupt the current task, with the updates having a low priority. When set to `assertive`, assistive technologies immediately notify the user, potentially clearing the speech queue of previous updates. + +Screen readers buffer content when the page is loaded. Because of this, content added after the initial accessibility tree is built may not be noticed as AT users start consuming content before dynamic widgets are populated—users may not know about the page or view content updating as widgets finish loading. In this situation you can let users know the page has been updated by setting `aria-live="polite"`. + +Fully populated pages may have updates too. Examples are content like real-time sports scores, news crawlers, and stock market tickers. Unless these kinds of updates are the main function of the page, you likely do not want to inform the user every time it updates, but do want to inform them the widget does get updated. Here, you would set `aria-live="off"`. In these scenarios there is no reason to inform the user of updates unless they are focused on the live region. + +Some live updates are important and time sensitive. For example, if you are selling concert tickets and the user has a limited time to make the purchase, you don't want to wait until a lull in activity to tell them their time is almost up (or already over). When being informed as soon as possible is necessary, set `aria-live="assertive"`. If the updated information is an [`alert`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/alert_role), the `aria-live` attribute is not needed. + +In this time-limit scenario, to be accessible, you need to also [provide a way for users to extend the time available or turn the timer off completely](https://www.w3.org/WAI/WCAG21/Understanding/timing-adjustable.html). + +### Using `aria-live` + +A live region includes the element and all its descendants. When not set on updating content, `aria-live`'s value comes from the nearest ancestor with a valid `aria-live` attribute value set. When set to `off`, or when the attribute is omitted altogether on the updated element and all the ancestor nodes in the DOM tree, the user is not informed. Users will still be able to hear the updates if they navigate to the live region, however. + +> [!WARNING] +> Because an interruption may disorient users or cause them to not complete their current task, don't use the `assertive` value unless the interruption is imperative. + +## Values + +- `assertive` + - : Indicates that updates to the region have the highest priority and should be presented to the user immediately. +- `off` (default) + - : Indicates that updates to the region should **not** be presented to the user unless the user is currently focused on that region. +- `polite` + - : Indicates that updates to the region should be presented at the next graceful opportunity, such as at the end of speaking the current sentence or when the user pauses typing. + +## Associated interfaces + +- {{domxref("Element.ariaLive")}} + - : The [`ariaLive`](/en-US/docs/Web/API/Element/ariaLive) property, part of the {{domxref("Element")}} interface, reflects the value of the `aria-live` attribute. +- {{domxref("ElementInternals.ariaLive")}} + - : The [`ariaLive`](/en-US/docs/Web/API/ElementInternals/ariaLive) property, part of the {{domxref("ElementInternals")}} interface, reflects the value of the `aria-live` attribute. + +## Associated roles + +Used in **ALL** roles. + +## Specifications + +{{Specifications}} + +## See also + +- [`aria-atomic`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-atomic) +- [`aria-relevant`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-relevant) +- [`aria-busy`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-busy) +- [`alert` role](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/alert_role) diff --git a/files/en-us/web/accessibility/aria/reference/attributes/aria-modal/index.md b/files/en-us/web/accessibility/aria/reference/attributes/aria-modal/index.md new file mode 100644 index 000000000000000..17a3c011753a1f9 --- /dev/null +++ b/files/en-us/web/accessibility/aria/reference/attributes/aria-modal/index.md @@ -0,0 +1,109 @@ +--- +title: "ARIA: aria-modal attribute" +short-title: aria-modal +slug: Web/Accessibility/ARIA/Reference/Attributes/aria-modal +page-type: aria-attribute +spec-urls: https://w3c.github.io/aria/#aria-modal +sidebar: accessibilitysidebar +--- + +The `aria-modal` attribute indicates whether an element is modal when displayed. + +## Description + +A section of content is "modal" means navigation is limited to the area itself and the background (the ancestors and siblings of the modal) is hidden. Setting `aria-modal="true"` on [`dialog`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/dialog_role) and [`alertdialog` role](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/alertdialog_role) containers indicates the presence of a "modal" element to users of assistive technology, but does not actually make the element modal. The features that make the element actually modal must be implemented by the developer. + +> [!NOTE] +> ARIA only modifies the accessibility tree, modifying how assistive technology presents the content to your users. ARIA doesn't change anything about an element's function or behavior. To create a modal effect you must use JavaScript to manage behavior, focus, and ARIA states. + +Relevant only on `dialog` and `alertdialog` containers, setting `aria-modal="true"` tells assistive technologies to let the user know the ability to interact with, or access other content on the page requires the modal dialog to be closed or otherwise lose focus. + +Modal dialogs are when content is displayed and the user's interaction is limited to only that section until it is dismissed. + +When creating modal dialogs, `aria-modal="true"` tells assistive technologies that the windows underneath the current dialog are not part of the modal content. + +When a modal element is displayed, focus should be placed in the modal. Focus needs to be "trapped" inside the modal when it is visible, until it is dismissed. Assistive technology (<abbr>AT</abbr>) can then navigate the modal's content and understand the scope of the modal's content. The `aria-modal` attribute helps AT communicate the bounds of the modal and distinguishes it from the rest of the page's content. When dismissed, focus should return to the element that triggered the modal. + +Ensure the modal is controllable using only its descendant elements. If a modal dialog has a close button, the button should be a descendant contained with the modal container in the DOM. + +When a modal element is displayed, authors **should** mark all other contents as inert (such as "inert subtrees" in HTML). Disabled content is not inert content. Inert content cannot be interacted with using both normal and specialized browsing modes such as caret browsing, which allow an assistive technology user to explore a page in detail. This includes disabled content, whose content may provide meaning. + +The [`inert`](/en-US/docs/Web/HTML/Reference/Global_attributes/inert) attribute is a boolean attribute that indicates, by its presence, that the element and all its shadow-including descendants are to be made inert. Until [`HTMLElement.inert`](/en-US/docs/Web/API/HTMLElement/inert) is fully supported, content can be [made inert with JavaScript](https://samthor.au/2021/inert/). + +Including `aria-modal="true"` on a [`dialog`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/dialog_role) or [`alertdialog`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/alertdialog_role), removes the requirement of putting [`aria-hidden`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-hidden) on background content, as the `aria-modal` informs assistive technologies that content outside a dialog is inert. Note that while support for the {{HTMLElement("dialog")}} element is good, thoroughly testing your implementation is vitally important. + +If a dialog is not modal — there is no inert background and focus isn't confined to the dialog — either include `aria-modal="false"` or omit the attribute altogether. + +## Example + +```html +<div id="backdrop" class="no-scroll"> + <div + role="alertdialog" + aria-modal="true" + aria-labelledby="dialog_label" + aria-describedby="dialog_desc"> + <h2 id="dialog_label">Confirmation</h2> + <div id="dialog_desc"> + <p>Are you sure you want to delete this file?</p> + </div> + <button id="close-btn" type="button">No. Close this popup.</button> + <button id="confirm-btn" type="button">Yes. Delete the file.</button> + </div> +</div> +``` + +```js +document.getElementById("close-btn").addEventListener("click", () => { + closeDialog(); +}); + +document.getElementById("confirm-btn").addEventListener("click", (event) => { + deleteFile(); +}); +``` + +This partial example includes an `alertdialog` nested in a full-screen, non-scrollable backdrop. + +The [`role="alertdialog"`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/alertdialog_role) identifies the element that serves as the alert dialog container. The [`aria-labelledby`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-labelledby) provides the alert dialog an accessible name by referring to the element that provides the alert dialog title. The [`aria-describedby`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-describedby) attribute gives the alert dialog an {{glossary("accessible description")}} by referring to the alert dialog content that describes the primary message or purpose of the alert dialog. + +The `aria-modal="true"` informs the assistive technology user that the content underneath the dialog is not interactive so long as the element with a declaration of `role="alertdialog"` has focus. + +The `aria-modal` attribute exposes the existence of the modal to assistive technologies so the disabling of the content behind the modal can be communicated to AT users. Like all ARIA attributes, `aria-modal` itself has no effect on the page's functionality; focus management and disabling, interactivity on background elements, and the ability to remove focus from the alertdialog must all be managed with JavaScript. + +## Values + +- `false` (default) + - : Element is not modal. +- `true` + - : Element is modal. + +## Associated interfaces + +- {{domxref("Element.ariaModal")}} + - : The [`ariaModal`](/en-US/docs/Web/API/Element/ariaModal) property, part of the {{domxref("Element")}} interface, reflects the value of the `aria-modal` attribute. +- {{domxref("ElementInternals.ariaModal")}} + - : The [`ariaModal`](/en-US/docs/Web/API/ElementInternals/ariaModal) property, part of the {{domxref("ElementInternals")}} interface, reflects the value of the `aria-modal` attribute. + +## Associated roles + +Used in roles: + +- [`window`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/window_role) + +Inherits into roles: + +- [`alertdialog`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/alertdialog_role) +- [`dialog`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/dialog_role) + +## Specifications + +{{Specifications}} + +## See also + +- HTML {{HTMLElement("dialog")}} element +- [`alertdialog` role](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/alertdialog_role) +- [`dialog` role](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/dialog_role) +- HTML [`inert` global attribute](/en-US/docs/Web/HTML/Reference/Global_attributes/inert) +- HTMLElement API [`inert`](/en-US/docs/Web/API/HTMLElement/inert) property diff --git a/files/en-us/web/accessibility/aria/reference/attributes/aria-multiline/index.md b/files/en-us/web/accessibility/aria/reference/attributes/aria-multiline/index.md new file mode 100644 index 000000000000000..aec29d8873c324e --- /dev/null +++ b/files/en-us/web/accessibility/aria/reference/attributes/aria-multiline/index.md @@ -0,0 +1,58 @@ +--- +title: "ARIA: aria-multiline attribute" +short-title: aria-multiline +slug: Web/Accessibility/ARIA/Reference/Attributes/aria-multiline +page-type: aria-attribute +spec-urls: https://w3c.github.io/aria/#aria-multiline +sidebar: accessibilitysidebar +--- + +The `aria-multiline` attribute indicates whether a `textbox` accepts multiple lines of input or only a single line. + +## Description + +The default behavior of the <kbd>Enter</kbd> or <kbd>Return</kbd> key differs between single-line and multi-line text fields. When user focus is in a single-line `{{htmlelement("input/text", '&lt;input type="text"&gt;')}}`, an <kbd>Enter</kbd> or <kbd>Return</kbd> keystroke usually submits the form. + +When user focus is in a multi-line {{HTMLElement('textarea')}}, the keystroke inserts a line break. Only relevant for elements with the [`textbox`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/textbox_role) role set, the `aria-multiline` attribute indicates to assistive technologies whether that text box accepts multiple lines of input or only a single line, setting expectations as to what type of data to enter and what those keystroke will do. + +> [!NOTE] +> Where possible, use the HTML {{HTMLElement('input')}} or the {{HTMLElement('textarea')}}, as these have built in semantics and behaviors, do not require ARIA attributes or scripting, and have keyboard support built in. + +If the `aria-multiline="true"` is set, it means the textbox widget will accept line breaks within the input, similar to the HTML {{HTMLElement('textarea')}}. Elements with a role of `textbox` that do not have the attribute, or with the value set to `false`, are simple text boxes. + +Be aware of focus and keystrokes when designing text boxes. ARIA only modifies the accessibility tree and therefore how assistive technology presents the textbox to your users. ARIA doesn't change anything about an element's default function or behavior. When not using semantic HTML elements for their intended purpose and default functionality, you must use JavaScript to manage behavior and functionality, including responding to keystroke events. + +## Values + +- `true` + + - : The text box accepts multiple lines of input. + +- `false` + - : The text box only accepts a single line of input. + +## Associated interfaces + +- {{domxref("Element.ariaMultiLine")}} + - : The [`ariaMultiLine`](/en-US/docs/Web/API/Element/ariaMultiLine) property, part of the {{domxref("Element")}} interface, reflects the value of the `aria-multiline` attribute. +- {{domxref("ElementInternals.ariaMultiLine")}} + - : The [`ariaMultiLine`](/en-US/docs/Web/API/ElementInternals/ariaMultiLine) property, part of the {{domxref("ElementInternals")}} interface, reflects the value of the `aria-multiline` attribute. + +## Associated roles + +Used in roles: + +- [`textbox`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/textbox_role) + +Inherits into roles: + +- [`searchbox`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/searchbox_role) + +## Specifications + +{{Specifications}} + +## See also + +- ARIA [`textbox`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/textbox_role) role +- ARIA [`searchbox`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/searchbox_role) role diff --git a/files/en-us/web/accessibility/aria/reference/attributes/aria-multiselectable/index.md b/files/en-us/web/accessibility/aria/reference/attributes/aria-multiselectable/index.md new file mode 100644 index 000000000000000..ecaf42a41589ca9 --- /dev/null +++ b/files/en-us/web/accessibility/aria/reference/attributes/aria-multiselectable/index.md @@ -0,0 +1,166 @@ +--- +title: "ARIA: aria-multiselectable attribute" +short-title: aria-multiselectable +slug: Web/Accessibility/ARIA/Reference/Attributes/aria-multiselectable +page-type: aria-attribute +spec-urls: https://w3c.github.io/aria/#aria-multiselectable +sidebar: accessibilitysidebar +--- + +The `aria-multiselectable` attribute indicates that the user may select more than one item from the current selectable descendants. + +## Description + +The default behavior of selection lists, such as {{HTMLElement('select')}}, is to be able to choose only one item or option. By default or by convention, when a user is presented with list from which they must select an item, they assume they can only select a single item unless otherwise notified. The `aria-multiselectable` attribute is the way to inform assistive technology users that they may select more than one item from the current selectable items if they so choose. Lists and trees are examples of roles that might allow users to select more than one item at a time. + +> [!NOTE] +> When allowing for multiple selections, inform the user that multiple values are allowed and provide directions on how to provide multiple values, such as "to select more than one value, keep the control key pressed during selection." + +### Used with `aria-selected` + +When the user does select one or more items, remember to set the selected descendants as selected with [`aria-selected="true"`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-selected), and selectable descendants that are not selected have `aria-selected="false"` set. If an element is not selectable, omit the `aria-selected` attribute altogether as its presence informs the user the item is selectable. + +If a tree, grid, tab list, or list box supports selection of more than one node, the element with role [`grid`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/grid_role), [`listbox`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/listbox_role), [`tablist`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/tablist_role), or [`tree`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/tree_role) has `aria-multiselectable` set to `true`. Otherwise, `aria-multiselectable` is either set to `false` or the default value of false is implied. + +## Example + +```html +<p id="colorOptions">Choose the colors for your flag.</p> +<ul + tabindex="0" + role="listbox" + aria-labelledby="colorOptions" + aria-multiselectable="true"> + <li id="red" role="option" aria-selected="false">Red</li> + <li id="orange" role="option" aria-selected="false">Orange</li> + <li id="yellow" role="option" aria-selected="false">Yellow</li> + <li id="green" role="option" aria-selected="false">Green</li> + <li id="blue" role="option" aria-selected="false">Blue</li> + <li id="purple" role="option" aria-selected="false">Purple</li> + <li id="magenta" role="option" aria-selected="false">Hot pink</li> + <li id="lightpink" role="option" aria-selected="true">Light pink</li> + <li id="white" role="option" aria-selected="true">White</li> + <li id="lightblue" role="option" aria-selected="true">Light blue</li> + <li id="black" role="option" aria-selected="false">Black</li> + <li id="brown" role="option" aria-selected="false">Brown</li> +</ul> +``` + +This listbox supports multiple selection so we set the element with role `listbox` with `aria-multiselectable="true"`. All selected options have `aria-selected` set to `true`. All options that are not selected but are selectable have `aria-selected` set to false. Had we included options that were disabled or otherwise not selectable, we would have omitted the `aria-selected` attribute altogether. Including the attribute, even with no value or explicitly set to `false` indicates to assistive technology users that the item is selectable. + +The first rule of ARIA use is "if you can use a native feature with the semantics and behavior you require already built in, instead of repurposing an element and **adding** an ARIA role, state or property to make it accessible, then do so." Instead of creating an unordered list requiring [`tabindex`](/en-US/docs/Web/HTML/Reference/Global_attributes/tabindex), ARIA and JavaScript to turn text into selectable options, we could have used a native multiselect: the {{htmlelement('select')}} element has a Boolean [`multiple`](/en-US/docs/Web/HTML/Reference/Elements/select#multiple) attribute. If included, the user can select multiple options. If not, only a single option can be selected. + +```html +<label for="flagcolors"> Choose the colors for your flag. </label> +<select multiple id="flagcolors"> + <option value="red">Red</option> + <option value="orange">Orange</option> + <option value="yellow">Yellow</option> + <option value="green">Green</option> + <option value="blue">Blue</option> + <option value="purple">Purple</option> + <option value="magenta">Hot pink</option> + <option value="lightpink" selected>Light pink</option> + <option value="white" selected>White</option> + <option value="lightblue" selected>Light blue</option> + <option value="black">Black</option> + <option value="brown">Brown</option> +</select> +``` + +This HTML `<select>` version is accessible and interactive, and needs no ARIA or JavaScript to function. + +If the above isn't stylable to your liking, you can also create a list of selectable options with HTML checkboxes, which is also semantic, focusable, and infinitely stylable with CSS: + +```html +<fieldset> + <legend>Choose the colors for your flag.</legend> + <ul> + <li> + <label><input type="checkbox" name="fc" value="red" />Red</label> + </li> + <li> + <label><input type="checkbox" name="fc" value="orange" />Orange</label> + </li> + <li> + <label><input type="checkbox" name="fc" value="yellow" />Yellow</label> + </li> + <li> + <label><input type="checkbox" name="fc" value="green" />Green</label> + </li> + <li> + <label><input type="checkbox" name="fc" value="blue" />Blue</label> + </li> + <li> + <label><input type="checkbox" name="fc" value="purple" />Purple</label> + </li> + <li> + <label><input type="checkbox" name="fc" value="magenta" />Hot pink</label> + </li> + <li> + <label + ><input type="checkbox" name="fc" value="lightpink" checked />Light + pink</label + > + </li> + <li> + <label + ><input type="checkbox" name="fc" value="white" checked />White</label + > + </li> + <li> + <label + ><input type="checkbox" name="fc" value="lightblue" checked />Light + blue</label + > + </li> + <li> + <label><input type="checkbox" name="fc" value="black" />Black</label> + </li> + <li> + <label><input type="checkbox" name="fc" value="brown" />Brown</label> + </li> + </ul> +</fieldset> +``` + +Instead of `aria-selected="true"`, include the [`checked`](/en-US/docs/Web/HTML/Reference/Elements/input/checkbox#checked) attribute. The browser does the rest. + +## Values + +- `true` + - : More than one item in the widget may be selected at a time +- `false` + - : Only one item can be selected + +## Associated interfaces + +- {{domxref("Element.ariaMultiSelectable")}} + - : The [`ariaMultiSelectable`](/en-US/docs/Web/API/Element/ariaMultiSelectable) property, part of the {{domxref("Element")}} interface, reflects the value of the `aria-multiselectable` attribute. +- {{domxref("ElementInternals.ariaMultiSelectable")}} + - : The [`ariaMultiSelectable`](/en-US/docs/Web/API/ElementInternals/ariaMultiSelectable) property, part of the {{domxref("ElementInternals")}} interface, reflects the value of the `aria-multiselectable` attribute. + +## Associated roles + +Used in roles: + +- [`grid`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/grid_role) +- [`listbox`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/listbox_role) +- [`tablist`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/tablist_role) +- [`tree`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/tree_role) + +Inherited into roles: + +- [`treegrid`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/treegrid_role) + +## Specifications + +{{Specifications}} + +## See also + +- HTML {{HTMLElement('select')}} element +- HTML {{HTMLElement('option')}} element +- HTML {{HTMLElement('input')}} element +- [multiple](/en-US/docs/Web/HTML/Reference/Attributes/multiple) attribute +- [`aria-selected`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-selected) diff --git a/files/en-us/web/accessibility/aria/reference/attributes/aria-orientation/index.md b/files/en-us/web/accessibility/aria/reference/attributes/aria-orientation/index.md new file mode 100644 index 000000000000000..55d99fd44881461 --- /dev/null +++ b/files/en-us/web/accessibility/aria/reference/attributes/aria-orientation/index.md @@ -0,0 +1,82 @@ +--- +title: "ARIA: aria-orientation attribute" +short-title: aria-orientation +slug: Web/Accessibility/ARIA/Reference/Attributes/aria-orientation +page-type: aria-attribute +spec-urls: https://w3c.github.io/aria/#aria-orientation +sidebar: accessibilitysidebar +--- + +The `aria-orientation` attribute indicates whether the element's orientation is horizontal, vertical, or unknown/ambiguous. + +## Description + +It may be important for the user to know the orientation to know how to navigate certain widgets, as orientation impacts the expected behaviors of the left, right, up and down arrows. The `aria-orientation` attribute is used to indicate to assistive technology users whether an element's orientation is `horizontal` or `vertical`, or `undefined`. + +Several widgets have default orientations: + +Horizontal by default: + +- [`slider`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/slider_role), +- [`tablist`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/tablist_role) +- [`toolbar`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/toolbar_role) +- [`menubar`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/menubar_role) + +Vertical by default: + +- [`scrollbar`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/scrollbar_role) +- [`tree`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/tree_role) +- [`listbox`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/listbox_role) +- [`menu`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/menu_role) + +Each [`separator`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/separator_role) should have `aria-orientation` consistent with the separator's orientation. + +When nodes in a tree are arranged horizontally instead of its default vertical orientation, or when a tab list is vertical instead of its default horizontal, the down arrow performs as a right arrow normally would, and the up arrow performs as a left arrow normally would. In these instances, assistive technology users need to know the widget's orientation so as to navigate correctly. + +Up and down arrows are generally available for normal browser scrolling, even when focus is inside a tree or tab list. Include `aria-orientation` to enable alerting users when a widget doesn't have the default, expected orientation and associated navigation. + +Always remember that ARIA only modifies how assistive technology presents content to your users; altering the behavior of arrow keys requires JavaScript. + +## Values + +- `horizontal` + - : The element is oriented horizontally. +- `undefined` (default) + - : The element's orientation is unknown/ambiguous. +- `vertical` + - : The element is oriented vertically. + +## Associated interfaces + +- {{domxref("Element.ariaOrientation")}} + - : The [`ariaOrientation`](/en-US/docs/Web/API/Element/ariaOrientation) property, part of the {{domxref("Element")}} interface, reflects the value of the `aria-orientation` attribute. +- {{domxref("ElementInternals.ariaOrientation")}} + - : The [`ariaOrientation`](/en-US/docs/Web/API/ElementInternals/ariaOrientation) property, part of the {{domxref("ElementInternals")}} interface, reflects the value of the `aria-orientation` attribute. + +## Associated roles + +Used in roles: + +- [`scrollbar`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/scrollbar_role) +- [`select`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/select_role) +- [`separator`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/separator_role) +- [`slider`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/slider_role) +- [`tablist`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/tablist_role) +- [`toolbar`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/toolbar_role) + +Inherited into roles: + +- [`listbox`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/listbox_role) +- [`menu`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/menu_role) +- [`menubar`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/menubar_role) +- [`radiogroup`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/radiogroup_role) +- [`tree`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/tree_role) +- [`treegrid`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/treegrid_role) + +## Specifications + +{{Specifications}} + +## See also + +- [Understanding WCAG: Keyboard](/en-US/docs/Web/Accessibility/Guides/Understanding_WCAG/Keyboard) diff --git a/files/en-us/web/accessibility/aria/reference/attributes/aria-owns/index.md b/files/en-us/web/accessibility/aria/reference/attributes/aria-owns/index.md new file mode 100644 index 000000000000000..58b0eb9555b7928 --- /dev/null +++ b/files/en-us/web/accessibility/aria/reference/attributes/aria-owns/index.md @@ -0,0 +1,77 @@ +--- +title: "ARIA: aria-owns attribute" +short-title: aria-owns +slug: Web/Accessibility/ARIA/Reference/Attributes/aria-owns +page-type: aria-attribute +spec-urls: https://w3c.github.io/aria/#aria-owns +sidebar: accessibilitysidebar +--- + +The `aria-owns` attribute identifies an element (or elements) in order to define a visual, functional, or contextual relationship between a parent and its child elements when the DOM hierarchy cannot be used to represent the relationship. + +## Description + +Every element is the parent, sibling, or child of another element. The document object, made up of HTML elements and text nodes, is the basis of the DOM tree. The Accessibility Object Model (<abbr>AOM</abbr>) relies on a well-built DOM to enable assistive technologies to relay meaningful information about a document's contents to users. + +There are circumstances where the layout that appears on screen may differ from the underlying DOM structure due to the ability of JavaScript to alter content and CSS to alter layout. When this is the case, the `aria-owns` attribute can be used to recreate a meaningful relationship for assistive technology that consumes the DOM. + +When elements appear to be related visually but are not associated in the DOM, the `aria-owns` attribute enables creating the relationship that appears on screen in the accessibility layer for use by assistive technology. The **only** reason to include `aria-owns` is to expose a parent/child contextual relationship to assistive technology when the DOM's construction can't provide that relationship. + +An "owning element" is any DOM ancestor of an element. If an element visually, functionally, or contextually appears to "own" (be an ancestor of) an element, but isn't actually an ancestor of the element in the DOM, include the `aria-owns` to create that relationship. Add the attribute to the owning element with reference to the non-child owned element (or elements) to tell assistive technology that an element should be treated as a child. + +Referencing the ID of one or more elements allows any element to "own" any other element with an `aria-owns` declaration. The value of the `aria-owns` attribute is a space-separated ID reference list that references the IDs of one or more elements in the document. + +> [!NOTE] +> An "owned" element is any DOM descendant of the element, any element specified as a child via `aria-owns`, or any DOM descendant of the owned child. The `aria-owns`-owned element should be an element that belongs to a separate parent tree in the DOM but should be treated as a child of the current element. + +Do not use `aria-owns` as a replacement for the DOM hierarchy. If the relationship is represented in the DOM, do not use `aria-owns`. + +A child element is owned by its DOM parent by default: in this case, `aria-owns` should not be used. Avoid using the `aria-owns` attribute to rearrange existing child elements into a different order. + +When using `aria-owns`, make sure you [manage focus order](https://css-tricks.com/focus-management-and-inert/). Ensure the visual focus order matches this assistive technology reading order. + +An example of when to use `aria-owns` includes pop-up sub-menus that visually appear positioned near a parent menu, but cannot be nested in the DOM within the parent menu because it would affect the visual presentation. In this case, use `aria-owns` to present the sub-menu as a child of the parent menu to a screen reader. + +> [!NOTE] +> The `aria-owns` attribute should only be used when the parent/child relationship cannot be determined from the DOM. + +If an element has both `aria-owns` and DOM children, the order of the child elements: + +1. The actual DOM children first, +2. Then the elements referenced in `aria-owns`. + +This order can be changed by including the ID references to the actual DOM children in the `aria-owns` value. + +The {{CSSXRef('order')}} property, part of flex or grid layouts, can be used to change the order of flex and grid items making them appear in a different order from their order in the source document, creating a divergence of the logical order of elements. While it may be tempting to order the accessibility layer to match order changes created with the CSS {{CSSXref('order')}} property, avoiding both the `order` property and the `aria-owns` attribute is the best option. + +Make sure your owned elements have only one owner. Do not specify the `id` of an element in more than one other element's `aria-owns` attribute. An element can have only one owner. + +> [!WARNING] +> While [`aria-owns` is now supported](https://a11ysupport.io/tech/aria/aria-owns_attribute) in all modern browsers, `aria-owns` may not be exposed to users of macOS and iOS using VoiceOver prior to iOS 17.3 and macOS 14.3. + +## Values + +- `id` list + - : Space separated list of one or more ID values referencing the elements being owned by the current element + +## Associated interfaces + +- {{domxref("Element.ariaOwnsElements")}} + - : The `ariaOwnsElements` property is part of each element's interface. + Its value is an array of subclasses of {{domxref("Element")}} that reflect the `id` references in the `aria-owns` attribute ([with some caveats](/en-US/docs/Web/API/Document_Object_Model/Reflected_attributes#reflected_element_references)). +- {{domxref("ElementInternals.ariaOwnsElements")}} + - : The `ariaOwnsElements` property is part of each custom element's interface. + Its value is an array of subclasses of {{domxref("Element")}} that reflect the `id` references in the `aria-owns` attribute ([with some caveats](/en-US/docs/Web/API/Document_Object_Model/Reflected_attributes#reflected_element_references)). + +## Associated roles + +Used in **ALL** roles. + +## Specifications + +{{Specifications}} + +## See also + +- [`aria-controls`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-controls) +- [`aria-owns` browser support](https://a11ysupport.io/tech/aria/aria-owns_attribute) diff --git a/files/en-us/web/accessibility/aria/reference/attributes/aria-placeholder/index.md b/files/en-us/web/accessibility/aria/reference/attributes/aria-placeholder/index.md new file mode 100644 index 000000000000000..cbc4b94cac8214a --- /dev/null +++ b/files/en-us/web/accessibility/aria/reference/attributes/aria-placeholder/index.md @@ -0,0 +1,72 @@ +--- +title: "ARIA: aria-placeholder attribute" +short-title: aria-placeholder +slug: Web/Accessibility/ARIA/Reference/Attributes/aria-placeholder +page-type: aria-attribute +spec-urls: https://w3c.github.io/aria/#aria-placeholder +sidebar: accessibilitysidebar +--- + +The `aria-placeholder` attribute defines a short hint (a word or short phrase) intended to help the user with data entry when a form control has no value. The hint can be a sample value or a brief description of the expected format. + +## Description + +A placeholder is text that appears in the form control when it has no value set. The HTML [`placeholder`](/en-US/docs/Web/HTML/Reference/Elements/input#placeholder) attribute enables providing a sample value or a brief description of the expected format for several HTML {{HTMLElement('input')}} types and {{HTMLElement('textarea')}}. + +If you are creating a `textbox` using any other element, `placeholder` is not supported. That is where `aria-placeholder` comes into play. The `aria-placeholder` attribute can be used to defines a short hint to help the user understand what type of data is expected when a non-semantic form control has no value. + +```html +<span id="date-of-birth">Birthday</span> +<div + contenteditable + role="textbox" + aria-labelledby="date-of-birth" + aria-placeholder="MM-DD-YYYY"> + MM-DD-YYYY +</div> +``` + +The placeholder hint should be shown to the user whenever the control's value is empty, including when a value is deleted. + +> [!NOTE] +> ARIA is only modify the accessibility tree for an element and therefore how assistive technology presents the content to your users. ARIA doesn't change anything about an elements function or behavior. When not using semantic HTML elements for their intended purpose and default functionality, you must use JavaScript to manage behavior. + +The `aria-placeholder` is used in addition to, not instead of, a label. They have different purposes and different functionality. A label explains what kind of information is expected. Placeholder text provides a hint about the expected value. + +> [!WARNING] +> Using a placeholder instead of a visible label harms accessibility and usability for many users including older users and users with cognitive, mobility, fine motor skill and vision impairments. Labels are better: they are always visible and they provide for a larger hit region to focus on the control. Placeholders have several drawbacks: they disappear when the control has any value including just white space, they can confuse users into thinking the value is pre-filled, and the default color has insufficient contrast. + +> [!NOTE] +> Placeholders should only be used to show an example of the type of data that should be entered into a form; they don't replace a proper label. + +## Values + +- `<string>` + - : The word or short phrase to display in a control when the control has no value. + +## Associated interfaces + +- {{domxref("Element.ariaPlaceholder")}} + - : The [`ariaPlaceholder`](/en-US/docs/Web/API/Element/ariaPlaceholder) property, part of the {{domxref("Element")}} interface, reflects the value of the `aria-placeholder` attribute. +- {{domxref("ElementInternals.ariaPlaceholder")}} + - : The [`ariaPlaceholder`](/en-US/docs/Web/API/ElementInternals/ariaPlaceholder) property, part of the {{domxref("ElementInternals")}} interface, reflects the value of the `aria-placeholder` attribute. + +## Associated roles + +Used in roles: + +- [`textbox`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/textbox_role) + +Inherited into roles: + +- [`searchbox`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/searchbox_role) + +## Specifications + +{{Specifications}} + +## See also + +- [HTML `placeholder` attribute](/en-US/docs/Web/HTML/Reference/Elements/input#placeholder) +- [`aria-labelledby`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-labelledby) +- [`aria-label`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-label) diff --git a/files/en-us/web/accessibility/aria/reference/attributes/aria-posinset/index.md b/files/en-us/web/accessibility/aria/reference/attributes/aria-posinset/index.md new file mode 100644 index 000000000000000..39f593848090f86 --- /dev/null +++ b/files/en-us/web/accessibility/aria/reference/attributes/aria-posinset/index.md @@ -0,0 +1,79 @@ +--- +title: "ARIA: aria-posinset attribute" +short-title: aria-posinset +slug: Web/Accessibility/ARIA/Reference/Attributes/aria-posinset +page-type: aria-attribute +spec-urls: https://w3c.github.io/aria/#aria-posinset +sidebar: accessibilitysidebar +--- + +The `aria-posinset` attribute defines an element's number or position in the current set of listitems or treeitems when not all items are present in the DOM. + +## Description + +Short for "position in set", the `aria-posinset` attribute defines the position of the element within the whole set of listitems or treeitems when only a subset of the items are present in the DOM. + +If all the items in a list are present in the DOM, the browser can calculate the total and the position of each, making `aria-posinset` unnecessary. When only a portion of a set is in the DOM, include `aria-posinset` to provide information about the element's position within the set along with [`aria-setsize`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-setsize) to inform the user how many items are in the full set. + +The following example shows a listbox with four element options out of the 118 in the periodic table of chemical elements. + +```html +<h2 id="periodic-table">Periodic table of chemical elements</h2> +<ul role="listbox" aria-labelledby="periodic-table"> + <li role="option" aria-setsize="118" aria-posinset="1">Hydrogen</li> + <li role="option" aria-setsize="118" aria-posinset="3">Lithium</li> + <li role="option" aria-setsize="118" aria-posinset="11">Sodium</li> + <li role="option" aria-setsize="118" aria-posinset="19">Potassium</li> +</ul> +``` + +The value of each `aria-posinset` is an integer greater than or equal to `1`, and less than or equal to the size of the set when that size is known. + +> [!NOTE] +> When using `aria-posinset` you must also include value for [`aria-setsize`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-setsize), which is the size of the entire set. If the size of the entire set is unknown, set `aria-setsize="-1"`. + +For [`menuitem`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/menuitem_role), [`menuitemcheckbox`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/menuitemcheckbox_role), or [`menuitemradio`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/menuitemradio_role), set the value of `aria-posinset` with respect to the total number of items in the menu, excluding any separators. + +In a [`feed`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/feed_role), each {{HTMLElement('article')}} element has `aria-posinset` set to a value that represents its position in the feed along with the `aria-setsize` set to either the number of articles that have been loaded or the total number in the feed, depending on which value is most helpful to users. + +## Values + +- `<integer>` + - : Integer greater than or equal to 1, and less than or equal to the value of `aria-setsize`. + +## Associated interfaces + +- {{domxref("Element.ariaPosInSet")}} + - : The [`ariaPosInSet`](/en-US/docs/Web/API/Element/ariaPosInSet) property, part of the {{domxref("Element")}} interface, reflects the value of the `aria-posinset` attribute. +- {{domxref("ElementInternals.ariaPosInSet")}} + - : The [`ariaPosInSet`](/en-US/docs/Web/API/ElementInternals/ariaPosInSet) property, part of the {{domxref("ElementInternals")}} interface, reflects the value of the `aria-posinset` attribute. + +## Associated roles + +Used in roles: + +- [`article`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/article_role) +- [`associationlistitemkey`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/structural_roles) +- [`associationlistitemvalue`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/structural_roles) +- [`comment`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/comment_role) +- [`listitem`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/listitem_role) +- [`menuitem`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/menuitem_role) +- [`option`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/option_role) +- [`radio`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/radio_role) +- [`row`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/row_role) +- [`tab`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/tab_role) + +Inherits into roles: + +- [`comment`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/comment_role) +- [`menuitemcheckbox`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/menuitemcheckbox_role) +- [`menuitemradio`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/menuitemradio_role) +- [`treeitem`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/treeitem_role) + +## Specifications + +{{Specifications}} + +## See also + +- [`aria-setsize`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-setsize) diff --git a/files/en-us/web/accessibility/aria/reference/attributes/aria-pressed/index.md b/files/en-us/web/accessibility/aria/reference/attributes/aria-pressed/index.md new file mode 100644 index 000000000000000..ad9c753bbde1be9 --- /dev/null +++ b/files/en-us/web/accessibility/aria/reference/attributes/aria-pressed/index.md @@ -0,0 +1,66 @@ +--- +title: "ARIA: aria-pressed attribute" +short-title: aria-pressed +slug: Web/Accessibility/ARIA/Reference/Attributes/aria-pressed +page-type: aria-attribute +spec-urls: https://w3c.github.io/aria/#aria-pressed +sidebar: accessibilitysidebar +--- + +The `aria-pressed` attribute indicates the current "pressed" state of a toggle button. + +## Description + +Adding `aria-pressed` to an element with a role of [`button`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/button_role) turns the button into a toggle button. The `aria-pressed` attribute is only relevant for toggle buttons. It represents the button's current "pressed" state. + +The value is "tri-state", meaning the value can be set to `true`, `false`, `mixed`, or `undefined` values. In the case of `aria-pressed`, like most tri-state value types, the default value is `undefined`. + +Toggle buttons require a full press-and-release cycle to change their value. Pressing and releasing it once changes the value to `true`. If it's pressed and released again, the value changes back to `false`. + +A value of `mixed` means that the values of more than one item controlled by the button do not all share the same value. + +Do not change the contents of the label on a toggle when the state changes. If a button label says "pause", do not change it to "play" when pressed. In this example, when the pressed state is true, the label remains "Pause" so a screen reader would say something like "Pause toggle button pressed". + +```html +<button aria-pressed="false">Pause</button> +``` + +If you want the label to toggle between "Paused" and "Play", don't use `aria-pressed`. + +The first rule of ARIA use is "if you can use a native feature with the semantics and behavior you require already built in, instead of repurposing an element and adding an ARIA role, state or property to make it accessible, then do so." If we employ native HTML semantics with {{HTMLElement('button')}}, we can toggle the label instead of toggling the pressed state, removing the need for the `aria-pressed` attribute. + +## Values + +- `false` + - : The button supports being pressed but is not currently pressed. +- `mixed` + - : Indicates a mixed mode value for a tri-state toggle button. +- `true` + - : The button is pressed. +- `undefined` (default) + - : The element does not support being pressed. + +## Associated interfaces + +- {{domxref("Element.ariaPressed")}} + - : The [`ariaPressed`](/en-US/docs/Web/API/Element/ariaPressed) property, part of the {{domxref("Element")}} interface, reflects the value of the `aria-pressed` attribute. +- {{domxref("ElementInternals.ariaPressed")}} + - : The [`ariaPressed`](/en-US/docs/Web/API/ElementInternals/ariaPressed) property, part of the {{domxref("ElementInternals")}} interface, reflects the value of the `aria-pressed` attribute. + +## Associated roles + +Used in roles: + +- [`button`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/button_role) + +## Specifications + +{{Specifications}} + +## See also + +- [`<input type="button">`](/en-US/docs/Web/HTML/Reference/Elements/input/button) +- [`<input type="submit">`](/en-US/docs/Web/HTML/Reference/Elements/input/submit) +- {{HTMLElement('button')}} +- [`aria-checked`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-checked) +- [`aria-selected`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-selected) diff --git a/files/en-us/web/accessibility/aria/reference/attributes/aria-readonly/index.md b/files/en-us/web/accessibility/aria/reference/attributes/aria-readonly/index.md new file mode 100644 index 000000000000000..58943319b816bf6 --- /dev/null +++ b/files/en-us/web/accessibility/aria/reference/attributes/aria-readonly/index.md @@ -0,0 +1,75 @@ +--- +title: "ARIA: aria-readonly attribute" +short-title: aria-readonly +slug: Web/Accessibility/ARIA/Reference/Attributes/aria-readonly +page-type: aria-attribute +spec-urls: https://w3c.github.io/aria/#aria-readonly +sidebar: accessibilitysidebar +--- + +The `aria-readonly` attribute indicates that the element is not editable, but is otherwise operable. + +## Description + +When you want to indicate that an interactive element works but is not editable, set `aria-readonly="true"`. This indicates to the user that an interactive element that would normally be focusable and copyable has been placed in a read-only (not disabled) state. + +When `aria-readonly` is set to `true`, it means the user can read but not set the value of the widget. Read-only elements are still relevant to the user, so you should not prevent the user from navigating to the element or its focusable descendants or copying the value. + +Examples include: + +- Form elements which should not be changed. +- Row and column headers in a spreadsheet. +- The total value in a shopping cart. + +If the non-changeable value shouldn't be able to receive focus, use [`aria-disabled`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-disabled) instead. + +> [!NOTE] +> When using semantic HTML form controls, if you set the `readonly` attribute, you don't need to include `aria-readonly="true"`. + +> [!NOTE] +> The value of `<input type="checkbox">` can not be edited making `readonly` not relevant. However, when creating checkboxes with `role="checkbox"` the `aria-readonly` attribute _is_ supported. + +## Values + +- `true` + - : The element is readonly. +- `false` (default) + - : The element is not readonly. + +## Associated interfaces + +- {{domxref("Element.ariaReadOnly")}} + - : The [`ariaReadOnly`](/en-US/docs/Web/API/Element/ariaReadOnly) property, part of the {{domxref("Element")}} interface, reflects the value of the `aria-readonly` attribute. +- {{domxref("ElementInternals.ariaReadOnly")}} + - : The [`ariaReadOnly`](/en-US/docs/Web/API/ElementInternals/ariaReadOnly) property, part of the {{domxref("ElementInternals")}} interface, reflects the value of the `aria-readonly` attribute. + +## Associated roles + +Used in roles: + +- [`checkbox`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/checkbox_role) +- [`combobox`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/combobox_role) +- [`grid`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/grid_role) +- [`gridcell`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/gridcell_role) +- [`listbox`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/listbox_role) +- [`radiogroup`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/radiogroup_role) +- [`slider`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/slider_role) +- [`spinbutton`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/spinbutton_role) +- [`textbox`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/textbox_role) + +Inherited into roles: + +- [`columnheader`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/columnheader_role) +- [`rowheader`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/rowheader_role) +- [`searchbox`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/searchbox_role) +- [`switch`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/switch_role) +- [`treegrid`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/treegrid_role) + +## Specifications + +{{Specifications}} + +## See also + +- [HTML `readonly` attribute](/en-US/docs/Web/HTML/Reference/Attributes/readonly) +- [`aria-disabled`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-disabled) diff --git a/files/en-us/web/accessibility/aria/reference/attributes/aria-relevant/index.md b/files/en-us/web/accessibility/aria/reference/attributes/aria-relevant/index.md new file mode 100644 index 000000000000000..8dc45322fa98358 --- /dev/null +++ b/files/en-us/web/accessibility/aria/reference/attributes/aria-relevant/index.md @@ -0,0 +1,57 @@ +--- +title: "ARIA: aria-relevant attribute" +short-title: aria-relevant +slug: Web/Accessibility/ARIA/Reference/Attributes/aria-relevant +page-type: aria-attribute +spec-urls: https://w3c.github.io/aria/#aria-relevant +sidebar: accessibilitysidebar +--- + +Used in ARIA live regions, the global `aria-relevant` attribute indicates what notifications the user agent will trigger when the [accessibility tree](/en-US/docs/Glossary/Accessibility_tree) within a live region is modified. + +## Description + +[ARIA live regions](/en-US/docs/Web/Accessibility/ARIA/Guides/Live_regions) are areas of a web page that are updated when user's attention may be elsewhere. When an update is outside of the user's keyboard focus, assistive technologies such as screen readers use a live region area to report updates to the user. + +Examples of live regions include news marquees, stock tickers, chat windows, and score boards. These update without user interaction. Some updates are important for the user to know about. They're relevant. Others are not. The `aria-relevant` is used to describe what types of changes have occurred to an [`aria-live`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-live) region, and which are relevant and should be announced. + +The value is a space-separated list of change types, including `additions`, `removals`, and `text`, with a shorthand `all` meaning all three. + +When `aria-relevant` is not defined, the value is inherited from the nearest ancestor with a defined value. Inherited values are not additive; the value provided on a descendant element completely overrides any inherited value from an ancestor element. When a live region doesn't have an `aria-relevant` attribute set and has no ancestor with it set, it defaults to `additions text`, which means element nodes are added to the accessibility tree within the live region, AND text content or a text alternative is added to any descendant in the accessibility tree of the live region. This is because generally text modifications and node additions are relevant, but node removals are not. + +While not a supported value, if the value of `none` makes the most sense, it should not be a live region. + +The values of `removals` and `all` should be used sparingly. For example, when a goal happens in the World Cup, the new score (the addition) is important, the old value (the removal) is not. Assistive technologies only need to be informed of content removal when its removal represents an important change, such as when a player is taken out of the game. + +## Values + +- `additions` + - : Element nodes are added to the accessibility tree within the live region. +- `all` + - : Shorthand for `additions removals text`. +- `removals` + - : Text content, a text alternative, or an element node within the live region is removed from the accessibility tree. +- `text` + - : Text content or a text alternative is added to any descendant in the accessibility tree of the live region. + +## Associated interfaces + +- {{domxref("Element.ariaRelevant")}} + - : The [`ariaRelevant`](/en-US/docs/Web/API/Element/ariaRelevant) property, part of the {{domxref("Element")}} interface, reflects the value of the `aria-relevant` attribute. +- {{domxref("ElementInternals.ariaRelevant")}} + - : The [`ariaRelevant`](/en-US/docs/Web/API/ElementInternals/ariaRelevant) property, part of the {{domxref("ElementInternals")}} interface, reflects the value of the `aria-relevant` attribute. + +## Associated roles + +Used in **ALL** roles. + +## Specifications + +{{Specifications}} + +## See also + +- [`aria-atomic`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-atomic) +- [`aria-live`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-live) +- [`aria-busy`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-busy) +- [ARIA live regions](/en-US/docs/Web/Accessibility/ARIA/Guides/Live_regions) diff --git a/files/en-us/web/accessibility/aria/reference/attributes/aria-required/index.md b/files/en-us/web/accessibility/aria/reference/attributes/aria-required/index.md new file mode 100644 index 000000000000000..dae16df03509c1e --- /dev/null +++ b/files/en-us/web/accessibility/aria/reference/attributes/aria-required/index.md @@ -0,0 +1,102 @@ +--- +title: "ARIA: aria-required attribute" +short-title: aria-required +slug: Web/Accessibility/ARIA/Reference/Attributes/aria-required +page-type: aria-attribute +spec-urls: https://w3c.github.io/aria/#aria-required +sidebar: accessibilitysidebar +--- + +The `aria-required` attribute indicates that user input is required on the element before a form may be submitted. + +## Description + +When a semantic HTML {{htmlelement("input")}}, {{htmlelement("select")}}, or {{htmlelement("textarea")}} must have a value, it should have the [`required`](/en-US/docs/Web/HTML/Reference/Elements/input#required) attribute applied to it. The HTML `required` attribute disables submitting the form unless the required form controls have valid values, while ensuring those navigating with the aid of assistive technologies understand which semantic form controls need valid content. + +When form controls are created using non-semantic elements, such as a {{HTMLElement('div')}} with a [role](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles) of [`checkbox`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/checkbox_role), the `aria-required` attribute should be included, with a value of `true`, to indicate to assistive technologies that user input is required on the element for the form to be submittable. The `aria-required` attribute can be used with HTML form elements; it is not limited to elements that have an ARIA role assigned. + +Similar to the HTML `required` attribute set on semantic HTML form controls, the `aria-required` attribute explicitly conveys to assistive technologies that the element is required before a form may be submitted. The `required` attribute on a semantic HTML form control will prevent the form control from being submitted if no value is present — providing native error messaging in some browsers if a required value is invalid when the user attempts to submit the form. The `aria-required` attribute, like all ARIA states and properties, has no impact on element functionality. Functionality and behavior must be added in with JavaScript. + +> [!NOTE] +> ARIA only modifies the accessibility tree, modifying how assistive technology presents content to users. ARIA does not change anything about an element's function or behavior. When not using semantic HTML elements for their intended purpose and default functionality, you must use JavaScript to manage behavior, focus, and ARIA states. + +The CSS {{CSSXRef(':required')}} and {{CSSXRef(':optional')}} pseudoclasses match {{htmlelement("input")}}, {{htmlelement("select")}}, and {{htmlelement("textarea")}} elements based on whether they are required or optional, respectively. When using non-semantic elements as form controls, you don't get this CSS pseudoclass selector benefit. You can, however, use attribute selectors if the attribute is present: `[aria-required="true"]` or `[aria-required="false"]`. + +If a form contains both required and optional form elements, the required elements should be indicated visually using a treatment that does not rely solely on color to convey meaning. Typically, descriptive text and/or an icon are used. + +> [!NOTE] +> Which elements are required should be apparent to all users. Ensure the visual presentation indicates the form control is required in a consistent, visible manner, remembering that color is not enough to convey information. + +## Examples + +The attribute should be added to the form-control role. If the user needs to fill in an email address [`textbox`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/textbox_role), include `aria-required="true"` on the textbox. + +```html +<div id="tbLabel">Email Address *</div> +<div + role="textbox" + contenteditable + aria-labelledby="tblabel" + aria-required="true" + id="email1"></div> +``` + +> [!NOTE] +> If the field's label already contains the word "required", it is recommended to leave out the `aria-required` attribute. This avoids that screen readers read out the term "required" twice. + +In this example, JavaScript must be used to prevent the containing form from being submitted if the textbox has no content. + +This could be written semantically, without the need for JavaScript: + +```html +<label for="email1">Email Address (required)</label> +<input type="email" id="email1" required /> +``` + +## Values + +- `true` + - : The element requires a value or must be checked for the form to be submittable. +- `false` + - : The element is not required. + +## Associated interfaces + +- {{domxref("Element.ariaRequired")}} + - : The [`ariaRequired`](/en-US/docs/Web/API/Element/ariaRequired) property, part of the {{domxref("Element")}} interface, reflects the value of the `aria-required` attribute. +- {{domxref("ElementInternals.ariaRequired")}} + - : The [`ariaRequired`](/en-US/docs/Web/API/ElementInternals/ariaRequired) property, part of the {{domxref("ElementInternals")}} interface, reflects the value of the `aria-required` attribute. + +## Associated roles + +Used in roles: + +- [`checkbox`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/checkbox_role) +- [`combobox`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/combobox_role) +- [`gridcell`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/gridcell_role) +- [`listbox`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/listbox_role) +- [`radiogroup`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/radiogroup_role) +- [`spinbutton`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/spinbutton_role) +- [`textbox`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/textbox_role) +- [`tree`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/tree_role) + +Inherits into roles: + +- [`columnheader`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/columnheader_role) +- [`rowheader`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/rowheader_role) +- [`searchbox`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/searchbox_role) +- [`switch`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/switch_role) +- [`treegrid`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/treegrid_role) + +## Specifications + +{{Specifications}} + +## See also + +- HTML [`required`](/en-US/docs/Web/HTML/Reference/Elements/input#required) attribute +- [`:optional` pseudoclass](/en-US/docs/Web/CSS/:optional) +- [`:required` pseudoclass](/en-US/docs/Web/CSS/:required) +- [`aria-invalid` attribute](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-invalid) +- [MDN Understanding WCAG, Guideline 3.3 explanations](/en-US/docs/Web/Accessibility/Guides/Understanding_WCAG/Understandable#guideline_3.3_%e2%80%94_input_assistance_help_users_avoid_and_correct_mistakes) +- [Understanding Success Criterion 3.3.2 | W3C Understanding WCAG 2.0](https://www.w3.org/TR/UNDERSTANDING-WCAG20/minimize-error-cues.html) diff --git a/files/en-us/web/accessibility/aria/reference/attributes/aria-roledescription/index.md b/files/en-us/web/accessibility/aria/reference/attributes/aria-roledescription/index.md new file mode 100644 index 000000000000000..e29179484ef1706 --- /dev/null +++ b/files/en-us/web/accessibility/aria/reference/attributes/aria-roledescription/index.md @@ -0,0 +1,76 @@ +--- +title: "ARIA: aria-roledescription attribute" +short-title: aria-roledescription +slug: Web/Accessibility/ARIA/Reference/Attributes/aria-roledescription +page-type: aria-attribute +spec-urls: https://w3c.github.io/aria/#aria-roledescription +sidebar: accessibilitysidebar +--- + +The `aria-roledescription` attribute defines a human-readable, author-localized description for the role of an element. + +## Description + +Some assistive technologies (<abbr>AT</abbr>), such as screen readers, present the role of an element as part of the user experience. The `aria-roledescription` attribute provides a way to define a different human-readable name to be presented by AT as the role of an element. + +> [!NOTE] +> Only use aria-roledescription to clarify the purpose of non-interactive container roles and to provide a more specific description to a widget. + +Users depend on the presentation of known role name to understand the purpose of the element and, if it is a widget, how to interact with it. So, only use `aria-roledescription` to clarify the purpose of non-interactive container roles like `group` or `region` and to provide a more specific description to a widget. + +The `aria-roledescription` property overrides how ATs localize and express the name of a role. When you override a role name the user understands, you can potentially negatively impact a users' ability to understand and interact with an element. + +Avoid using the `aria-roledescription` attribute. When a use case appears special worthy of a unique roledescription, the interactions can often times be broken down into smaller pieces that have relevant roles. + +When there are no semantic or ARIA widget roles that correspond to the interaction model of your widget, use `role="application"`, provide an `aria-roledescription` with a human-readable, author-localized customized role name, and use `aria-describedby` to provide user instructions. + +ATs may customize and localize the names of ARIA roles. If you are using `aria-roledescription` to change how the role name is presented to the user, remember to handle localization. The value should be translated when a page is localized. + +Changing how the role is presented to the user has no impact on the functionality of the element. For example, if an element has a role of [`region`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/region_role) or [`button`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/button_role) when AT provides functions for navigating to the next region or button, if you set the `aria-roledescription` to `continent` and `escape` respectively, the AT will still allow those functions to navigate to regions and buttons. + +Again, avoid using `aria-roledescription`. In this example, `escape` has no relevant meaning to the user, but `button` with "escape" as a label does. + +When using `aria-roledescription`, also ensure that the element to which it is applied has a valid ARIA [`role`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles) or has implicit role semantics and that the value itself is not empty and contains more than just whitespace characters. + +The `aria-roledescription` is required when using `aria-brailleroledescription`. Note that, in general, `aria-brailleroledescription` should only be used in rare cases when a `aria-roledescription` is excessively verbose when rendered in Braille. + +## Examples + +The following example shows the use of `aria-roledescription` to indicate that a non-interactive container is a "slide" in a web-based presentation application. + +```html +<div + role="article" + aria-roledescription="slide" + id="slide" + aria-labelledby="slideheading"> + <h1 id="slideheading">Quarterly Report</h1> + <!-- remaining slide contents --> +</div> +``` + +In the previous examples, a screen reader user may hear "Quarterly Report, slide" rather than the less precise "Quarterly Report, article". + +## Values + +- `<string>` + - : A non-empty string, an unconstrained value type, containing more than just white space. + +## Associated interfaces + +- {{domxref("Element.ariaRoleDescription")}} + - : The [`ariaRoleDescription`](/en-US/docs/Web/API/Element/ariaRoleDescription) property, part of the {{domxref("Element")}} interface, reflects the value of the `aria-roledescription` attribute. +- {{domxref("ElementInternals.ariaRoleDescription")}} + - : The [`ariaRoleDescription`](/en-US/docs/Web/API/ElementInternals/ariaRoleDescription) property, part of the {{domxref("ElementInternals")}} interface, reflects the value of the `aria-roledescription` attribute. + +## Associated roles + +Supported by all roles and by all base markup elements except for `role="generic"`. + +## Specifications + +{{Specifications}} + +## See also + +- [ARIA roles](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles) diff --git a/files/en-us/web/accessibility/aria/reference/attributes/aria-rowcount/index.md b/files/en-us/web/accessibility/aria/reference/attributes/aria-rowcount/index.md new file mode 100644 index 000000000000000..aee37227e0fd624 --- /dev/null +++ b/files/en-us/web/accessibility/aria/reference/attributes/aria-rowcount/index.md @@ -0,0 +1,83 @@ +--- +title: "ARIA: aria-rowcount attribute" +short-title: aria-rowcount +slug: Web/Accessibility/ARIA/Reference/Attributes/aria-rowcount +page-type: aria-attribute +spec-urls: https://w3c.github.io/aria/#aria-rowcount +sidebar: accessibilitysidebar +--- + +The `aria-rowcount` attribute defines the total number of rows in a table, grid, or treegrid. + +## Description + +Some tables have hundreds, even millions, of rows. Even for tables with fewer rows, loading only a subsection of rows may be a design requirement, improve performance, or improve user experience. When only a subset of rows are loaded, you do need to let all users know that only a subset of the data is being displayed. The `aria-rowcount` attribute is used to define the total number of rows in a table, grid, or treegrid. + +Included on the {{HTMLElement('table')}} element or on an element with a role of [`table`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/cell_role), the value is the number of rows in the full table, as an integer. If the total number of rows is not known, include `aria-rowcount="-1"`, which tells the browser to not count the total number of rows. + +If all of the rows are loaded and in the DOM, you don't need to include `aria-rowcount` as browsers automatically count the total number of rows. However, if the rows aren't all present in the DOM at any time, this attribute is needed to provide the number of rows when the full table size is known and to tell the browser to not automatically count the rows when the total number of rows is not known. + +## Example + +The following example shows a grid with 24 rows, of which the first row and rows 7 through 9 are displayed to the user. + +```html +<div role="grid" aria-rowcount="24"> + <div role="rowgroup"> + <div role="row" aria-rowindex="1"> + <span role="columnheader">First Name</span> + <span role="columnheader">Last Name</span> + <span role="columnheader">Position</span> + </div> + </div> + <div role="rowgroup"> + <div role="row" aria-rowindex="7"> + <span role="gridcell">Morgan</span> + <span role="gridcell">Brian</span> + <span role="gridcell">Midfielder</span> + </div> + <div role="row" aria-rowindex="8"> + <span role="gridcell">Abby</span> + <span role="gridcell">Dahlkemper</span> + <span role="gridcell">Defender</span> + </div> + <div role="row" aria-rowindex="9"> + <span role="gridcell">Ashlyn</span> + <span role="gridcell">Harris</span> + <span role="gridcell">Goalkeeper</span> + </div> + </div> +</div> +``` + +## Values + +- `<integer>` + - : The number of rows in the full table or `-1` is the table size is not known. + +## Associated interfaces + +- {{domxref("Element.ariaRowCount")}} + - : The [`ariaRowCount`](/en-US/docs/Web/API/Element/ariaRowCount) property, part of the {{domxref("Element")}} interface, reflects the value of the `aria-rowcount` attribute. +- {{domxref("ElementInternals.ariaRowCount")}} + - : The [`ariaRowCount`](/en-US/docs/Web/API/ElementInternals/ariaRowCount) property, part of the {{domxref("ElementInternals")}} interface, reflects the value of the `aria-rowcount` attribute. + +## Associated roles + +Used in roles: + +- [`table`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/cell_role) + +Inherited into roles: + +- [`grid`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/columnheader_role) +- [`treegrid`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/gridcell_role) + +## Specifications + +{{Specifications}} + +## See also + +- [`aria-rowindex`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-rowindex) +- [`aria-colcount`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-colcount) diff --git a/files/en-us/web/accessibility/aria/reference/attributes/aria-rowindex/index.md b/files/en-us/web/accessibility/aria/reference/attributes/aria-rowindex/index.md new file mode 100644 index 000000000000000..15781bc73b9f32f --- /dev/null +++ b/files/en-us/web/accessibility/aria/reference/attributes/aria-rowindex/index.md @@ -0,0 +1,103 @@ +--- +title: "ARIA: aria-rowindex attribute" +short-title: aria-rowindex +slug: Web/Accessibility/ARIA/Reference/Attributes/aria-rowindex +page-type: aria-attribute +spec-urls: https://w3c.github.io/aria/#aria-rowindex +sidebar: accessibilitysidebar +--- + +The `aria-rowindex` attribute defines an element's position with respect to the total number of rows within a table, grid, or treegrid. + +## Description + +Some tables have many, many rows. Loading only a subsection of rows may be done as a design requirement, to improve performance, or to improve user experience. + +When only a subset of rows are loaded, you do need to let all users know which subsets of rows are being displayed. The `aria-rowindex` attribute is used to define the cell or row's row index or position with respect to the total number of rows within a table, grid, or treegrid. + +Included on the {{HTMLElement('tr')}} element or on an element with a role of [`row`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/row_role), or directly on the {{HTMLElement('td')}}, {{HTMLElement('th')}}, or element with role of [`cell`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/cell_role) or [`gridcell`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/gridcell_role), the value is the row's position with respect to the full table. + +The value for `aria-rowindex` is an integer greater than or equal to `1`, greater than the `aria-rowindex` value of any previous rows, and less than or equal to the number of rows in the full table. + +If all of the rows are loaded and in the DOM, you don't need to include `aria-rowindex` as browsers automatically calculate the index of each row. However, when only a subset of the rows are present in the DOM, `aria-rowindex` is needed to indicate each row's position with respect to the full table. If only a subset of rows are loaded, you also need to include [`aria-rowcount`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-rowcount) on the table ancestor, even if you don't know the total rowcount. + +If the table with only a subset of rows has a cell that spans more than one row, both the row and cell need to have the `aria-rowindex` set. If a cell spans more than one row-when a cell role includes the `aria-rowspan` attribute or HTML cell has a `rowspan` attribute set to a value greater than 1-include the row's `aria-rowindex` value on the spanning cell in addition to the appropriate row spanning attribute. The value should be the row index of the row where the span starts. + +> [!NOTE] +> The `aria-rowindex` must be added to each row, but is optional on the cells, except for cells that span rows: the `aria-rowindex` attribute is required on all spanning cells. + +## Examples + +The following example shows a grid with 24 rows, of which the first row and rows 7 through 10 are displayed to the user. The last "position" cell spans column 9 and 10. + +```html +<div role="grid" aria-rowcount="24"> + <div role="rowgroup"> + <div role="row" aria-rowindex="1"> + <span role="columnheader">First Name</span> + <span role="columnheader">Last Name</span> + <span role="columnheader">Position</span> + </div> + </div> + <div role="rowgroup"> + <div role="row" aria-rowindex="7"> + <span role="gridcell">Morgan</span> + <span role="gridcell">Brian</span> + <span role="gridcell">Midfielder</span> + </div> + <div role="row" aria-rowindex="8"> + <span role="gridcell">Abby</span> + <span role="gridcell">Dahlkemper</span> + <span role="gridcell">Defender</span> + </div> + <div role="row" aria-rowindex="9"> + <span role="gridcell">Ashlyn</span> + <span role="gridcell">Harris</span> + <span role="gridcell" aria-rowspan="2" aria-rowindex="9">Goalkeeper</span> + </div> + <div role="row" aria-rowindex="10"> + <span role="gridcell">Alyssa</span> + <span role="gridcell">Naeher</span> + </div> + </div> +</div> +``` + +Note both `aria-rowspan` and `aria-rowindex` are present on the Goalkeeper cell, which spans two rows. + +## Values + +- `<integer>` + - : An integer greater than or equal to 1, greater than the `aria-rowindex` of the previous row, if any, and less than or equal to the value of [`aria-rowcount`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-rowcount). + +## Associated interfaces + +- {{domxref("Element.ariaRowIndex")}} + - : The [`ariaRowIndex`](/en-US/docs/Web/API/Element/ariaRowIndex) property, part of the {{domxref("Element")}} interface, reflects the value of the `aria-rowindex` attribute. +- {{domxref("ElementInternals.ariaRowIndex")}} + - : The [`ariaRowIndex`](/en-US/docs/Web/API/ElementInternals/ariaRowIndex) property, part of the {{domxref("ElementInternals")}} interface, reflects the value of the `aria-rowindex` attribute. + +## Associated roles + +Used in roles: + +- [`cell`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/cell_role) +- [`row`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/row_role) + +Inherited into roles: + +- [`columnheader`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/columnheader_role) +- [`gridcell`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/gridcell_role) +- [`rowheader`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/rowheader_role) + +## Specifications + +{{Specifications}} + +## See also + +- [`aria-rowindextext`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-rowindextext) +- [`aria-rowcount`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-rowcount) +- [`aria-rowspan`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-rowspan) +- [`aria-colindex`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-colindex) +- The [`rowspan`](/en-US/docs/Web/HTML/Reference/Elements/td#rowspan) attribute on {{HTMLElement('td')}} diff --git a/files/en-us/web/accessibility/aria/reference/attributes/aria-rowindextext/index.md b/files/en-us/web/accessibility/aria/reference/attributes/aria-rowindextext/index.md new file mode 100644 index 000000000000000..7661ac20dcfc1e0 --- /dev/null +++ b/files/en-us/web/accessibility/aria/reference/attributes/aria-rowindextext/index.md @@ -0,0 +1,55 @@ +--- +title: "ARIA: aria-rowindextext attribute" +short-title: aria-rowindextext +slug: Web/Accessibility/ARIA/Reference/Attributes/aria-rowindextext +page-type: aria-attribute +spec-urls: https://w3c.github.io/aria/#aria-rowindextext +sidebar: accessibilitysidebar +--- + +The `aria-rowindextext` attribute defines a human-readable text alternative of `aria-rowindex`. + +## Description + +When you have a very long table or when you purposefully want to display just a section of a table, not all rows may be present in the DOM. When this happens, we use the [`aria-rowcount`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-rowcount) with an integer value to define how many rows the table (or grid) would have if all the rows were present and add the [`aria-rowindex`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-rowindex) property on each row and spanning cell to provide information on the row index within that larger table. When the value of `aria-rowindex` is not meaningful or does not reflect the displayed index, we can also add the `aria-rowindextext` to provide a human-readable text alternative to the `aria-rowindex` integer value. + +The `aria-rowindextext` should only be included **in addition to**, not as a replacement of, the `aria-rowindex`. Some assistive technologies use the numeric row index for the purpose of keeping track of the user's position or providing alternative table navigation. The `aria-rowindextext` is useful if that integer value isn't meaningful or does not reflect the displayed index, such as a game of Chess or Battleship. + +The `aria-rowindextext` is added to each {{HTMLElement('tr')}} or to elements with the `row` role. It can also be addition to cells or owned elements of each row. + +## Values + +- `<string>` + - The human-readable text alternative of the numeric [`aria-rowindex`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-rowindex) + +## Associated interfaces + +- {{domxref("Element.ariaRowIndexText")}} + - : The [`ariaRowIndexText`](/en-US/docs/Web/API/Element/ariaRowIndexText) property, part of the {{domxref("Element")}} interface, reflects the value of the `aria-rowindextext` attribute. +- {{domxref("ElementInternals.ariaRowIndexText")}} + - : The [`ariaRowIndexText`](/en-US/docs/Web/API/ElementInternals/ariaRowIndexText) property, part of the {{domxref("ElementInternals")}} interface, reflects the value of the `aria-rowindextext` attribute. + +## Associated roles + +Used in roles: + +- [`cell`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/cell_role) +- [`row`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/row_role) + +Inherited into roles: + +- [`columnheader`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/columnheader_role) +- [`gridcell`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/gridcell_role) +- [`rowheader`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/rowheader_role) + +## Specifications + +{{Specifications}} + +## See also + +- [`aria-rowindex`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-rowindex) +- [`aria-rowcount`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-rowcount) +- [`aria-rowspan`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-rowspan) +- [`aria-colindextext`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-colindextext) +- [`aria-colindex`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-colindex) diff --git a/files/en-us/web/accessibility/aria/reference/attributes/aria-rowspan/index.md b/files/en-us/web/accessibility/aria/reference/attributes/aria-rowspan/index.md new file mode 100644 index 000000000000000..ac35660589daae2 --- /dev/null +++ b/files/en-us/web/accessibility/aria/reference/attributes/aria-rowspan/index.md @@ -0,0 +1,54 @@ +--- +title: "ARIA: aria-rowspan attribute" +short-title: aria-rowspan +slug: Web/Accessibility/ARIA/Reference/Attributes/aria-rowspan +page-type: aria-attribute +spec-urls: https://w3c.github.io/aria/#aria-rowspan +sidebar: accessibilitysidebar +--- + +The `aria-rowspan` attribute defines the number of rows spanned by a cell or gridcell within a table, grid, or treegrid. + +## Description + +Similar to the `rowspan` attribute of the {{HTMLElement('td')}} and {{HTMLElement('th')}} elements, but for cells and gridcells which are not contained in a native table, the `aria-rowspan` attribute defines the number of rows spanned by a `cell` or `gridcell` within a `table`, `grid`, or `treegrid`. + +This attribute is intended for cells and gridcells which are **not** part of an HTML {{HTMLElement('table')}}. When a cell is nested in a semantic `<table>`, the `rowspan` attribute should be used when a <td> or <th> spans more than one row. If both are present, `rowspan` takes precedence over `aria-rowspan`. But, like all ARIA attributes, `aria-rowspan` only impacts the accessibility tree. It doesn't change your layout. + +> [!NOTE] +> ARIA modifies the accessibility tree and how assistive technology presents content to your users. ARIA doesn't change anything about an element's function, behavior, or appearance. When using non-semantic elements, you must use CSS to manage layout and appearance. + +The value of `aria-rowspan` is an integer greater than or equal to 0 and less than the value which would cause the cell or gridcell to overlap the next cell or gridcell in the same column. Setting the value to `0` indicates that the cell or gridcell is to span all the remaining rows in the row group. The default value is `1`. + +## Values + +- `<integer>` + - : An integer greater than or equal to `0` and less than would cause a cell to overlap the next cell in the same column. + +## Associated interfaces + +- {{domxref("Element.ariaRowSpan")}} + - : The [`ariaRowSpan`](/en-US/docs/Web/API/Element/ariaRowSpan) property, part of the {{domxref("Element")}} interface, reflects the value of the `aria-rowspan` attribute. +- {{domxref("ElementInternals.ariaRowSpan")}} + - : The [`ariaRowSpan`](/en-US/docs/Web/API/ElementInternals/ariaRowSpan) property, part of the {{domxref("ElementInternals")}} interface, reflects the value of the `aria-rowspan` attribute. + +## Associated roles + +Used in roles: + +- [`cell`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/cell_role) + +Inherited into roles: + +- [`columnheader`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/columnheader_role) +- [`rowheader`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/rowheader_role) + +## Specifications + +{{Specifications}} + +## See also + +- The [`rowspan`](/en-US/docs/Web/HTML/Reference/Elements/td#rowspan) attribute on {{HTMLElement('td')}} +- [`aria-rowindex`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-rowindex) +- [`aria-colspan`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-colspan) diff --git a/files/en-us/web/accessibility/aria/reference/attributes/aria-selected/index.md b/files/en-us/web/accessibility/aria/reference/attributes/aria-selected/index.md new file mode 100644 index 000000000000000..64a804c9e0e4fa2 --- /dev/null +++ b/files/en-us/web/accessibility/aria/reference/attributes/aria-selected/index.md @@ -0,0 +1,131 @@ +--- +title: "ARIA: aria-selected attribute" +short-title: aria-selected +slug: Web/Accessibility/ARIA/Reference/Attributes/aria-selected +page-type: aria-attribute +spec-urls: https://w3c.github.io/aria/#aria-selected +sidebar: accessibilitysidebar +--- + +The `aria-selected` attribute indicates the current "selected" state of various widgets. + +## Description + +The `aria-selected` attribute indicates the current "selected" state for [`gridcell`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/gridcell_role), [`option`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/option_role), [`row`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/row_role) and [`tab`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/tab_role) roles. + +This attribute is used to indicate which elements within single-selection and multiple-selection composite widgets are selected. If more than one element is selectable at a time, include `aria-multiselectable="true"` on the grid, listbox, tablist, or other owning role, while including `aria-selected` only on the selectable cells, options, and tabs. + +For other roles, the currently selected state is set with [`aria-current`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-current), or possibly [`aria-checked`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-checked) or [`aria-pressed`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-pressed), depending on the role. + +Widgets that support both `aria-selected` and `aria-current` at the same time have different meanings for each. For example, `aria-current="page"` can be used in a navigation tree to indicate which page is currently displayed, while `aria-selected="true"` indicates which page will be displayed if the user activates the `treeitem`. + +### Grid + +Setting `aria-selected="false"` on a focusable gridcell indicates the cell is selectable. If the grid allows more than one gridcell to be selected at a time, set `aria-multiselectable="true"` on the element with role [`grid`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/grid_role). Setting `aria-selected` on a column or row header gridcell does not propagate the state to other cells in the column or row. + +### Option + +Both `aria-selected` and `aria-checked` are valid for [`option`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/option_role). Some user interfaces indicate selection with `aria-selected` in single-select list boxes and with `aria-checked` in multi-select list boxes. + +Don't specify both `aria-selected` and `aria-checked` on `option` elements contained by the same `listbox` unless the meaning and purpose of `aria-selected` is different from the meaning and purpose of aria-checked in the user interface, the meaning and purpose of each state apparent, and the UI provides separate methods for controlling each state. + +### Row + +The `aria-selected` attribute is supported on `row` but not `column`. If a grid supports selection, when a cell or row is selected, the selected element has `aria-selected="true"` set. + +If the grid supports column selection and a column is selected, all cells in the column have `aria-selected` set to `true`. + +### Tab + +In a tablist, `aria-selected` is used on a tab to indicate the currently-displayed [`tabpanel`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/tabpanel_role). + +The selected [`tab`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/tab_role) in a [`tablist`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/tablist_role) should have the attribute `aria-selected="true"` set. All inactive tabs in the tablist should have `aria-selected="false"` set. Setting the state only impacts the accessibility tree: make sure to style the active tab in a way that visual indicates it's selected state. The default value for `aria-selected` on a `tab` role is `false`. + +If more than one tab is selectable at a time, include `aria-multiselectable` on the `tablist`. + +## Examples + +In this `tablist` example, the first `tab` is selected: + +```html +<div class="tab-interface"> + <div role="tablist" aria-label="Sample Tabs"> + <span + role="tab" + aria-selected="true" + aria-controls="panel-1" + id="tab-1" + tabindex="0"> + First Tab + </span> + <span + role="tab" + aria-selected="false" + aria-controls="panel-2" + id="tab-2" + tabindex="-1"> + Second Tab + </span> + <span + role="tab" + aria-selected="false" + aria-controls="panel-3" + id="tab-3" + tabindex="-1"> + Third Tab + </span> + </div> + <div id="panel-1" role="tabpanel" tabindex="0" aria-labelledby="tab-1"> + <p>Content for the first panel</p> + </div> + <div id="panel-2" role="tabpanel" tabindex="0" aria-labelledby="tab-2" hidden> + <p>Content for the second panel</p> + </div> + <div id="panel-3" role="tabpanel" tabindex="0" aria-labelledby="tab-3" hidden> + <p>Content for the third panel</p> + </div> +</div> +``` + +> [!NOTE] +> ARIA only modifies the accessibility tree for an element and how assistive technology presents the content to users. ARIA doesn't change anything about an element's function or behavior. + +## Values + +- `true` + - : The selectable element is selected. +- `false` + - : The selectable element is not selected. Implicit default for [`tab`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/tab_role). +- `undefined` (default) + - : The element is not selectable. + +## Associated interfaces + +- {{domxref("Element.ariaSelected")}} + - : The [`ariaSelected`](/en-US/docs/Web/API/Element/ariaSelected) property, part of the {{domxref("Element")}} interface, reflects the value of the `aria-selected` attribute. +- {{domxref("ElementInternals.ariaSelected")}} + - : The [`ariaSelected`](/en-US/docs/Web/API/ElementInternals/ariaSelected) property, part of the {{domxref("ElementInternals")}} interface, reflects the value of the `aria-selected` attribute. + +## Associated roles + +Used in roles: + +- [`gridcell`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/gridcell_role) +- [`option`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/option_role) +- [`row`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/row_role) +- [`tab`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/tab_role) + +Inherited into roles: + +- [`columnheader`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/columnheader_role) +- [`rowheader`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/rowheader_role) +- [`treeitem`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/treeitem_role) + +## Specifications + +{{Specifications}} + +## See also + +- [`aria-pressed`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-pressed) +- [`aria-checked`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-checked) diff --git a/files/en-us/web/accessibility/aria/reference/attributes/aria-setsize/index.md b/files/en-us/web/accessibility/aria/reference/attributes/aria-setsize/index.md new file mode 100644 index 000000000000000..a6417c3c020c905 --- /dev/null +++ b/files/en-us/web/accessibility/aria/reference/attributes/aria-setsize/index.md @@ -0,0 +1,92 @@ +--- +title: "ARIA: aria-setsize attribute" +short-title: aria-setsize +slug: Web/Accessibility/ARIA/Reference/Attributes/aria-setsize +page-type: aria-attribute +spec-urls: https://w3c.github.io/aria/#aria-setsize +sidebar: accessibilitysidebar +--- + +The `aria-setsize` attribute defines the number of items in the current set of listitems or treeitems when not all items in the set are present in the DOM. + +## Description + +Browsers automatically calculate the set size and position for each item in a group of items, like the number of {{HTMLelement('li')}}s in a list, buttons in a same-named group of [radio buttons](/en-US/docs/Web/HTML/Reference/Elements/input/radio), and {{HTMLelement('option')}}s in a {{HTMLelement('select')}}. Assistive technologies, like screen readers, take advantage of this state management to report set sizes to the user. + +When the DOM is not complete, the browser calculation of the number of items in a set can be incorrect. When only a subset of items, such as list items, are loaded into the DOM, the browser calculates the number of items based only on those present. The `aria-setsize` attribute should be used to override the browser's incorrect count. It defines the number of items in the current set of listitems or treeitems had the entire set been loaded. + +`aria-setsize` attribute is set on each item, rather than on any containing element. The value is the same for each item: an integer reflecting number of items in the complete set, or `-1` if the set size is unknown. If all the items are present in the DOM, the browser can calculate the set size and the position of each item, making both `aria-setsize` and `aria-posinset` unnecessary. + +Elements with the `aria-setsize` generally have the [`aria-posinset`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-posinset) attribute included as well to indicate the position of that item within the set. The `aria-posinset` value is between `1` and the positive value of `aria-setsize`. + +For example, in a page's comments section, When comments in are not all in the DOM, such as when comments are paginated, the level, total number of comments, and position of each comment should be set with ARIA. The hierarchical level of comments can be indicated with [`aria-level`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-level). Group positional information is indicated with `aria-posinset` and `aria-setsize`. + +When a feed has a static number of articles, `aria-setsize` can be added to each article element with the value being either the total number of articles loaded or the total number in the feed. The value chosen depends on which value is most helpful to users. If the number of articles is extremely large, indefinite, or changes often, `aria-setsize="-1"` can be set to communicate the size of the set is unknown. + +In a [`listbox`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/listbox_role), when the complete set of available options is not present in the DOM due to dynamic loading on scroll, both `aria-setsize` and `aria-posinset` can be set on each [`option`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/option_role). + +In a tree view, if the complete set of available nodes is not present in the DOM due to dynamic loading as the user moves focus in or scrolls the tree, each node has `aria-level`, `aria-setsize`, and `aria-posinset` set. + +In a menu, `aria-setsize` is set on all [`menuitem`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/menuitem_role), [`menuitemcheckbox`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/menuitemcheckbox_role), or [`menuitemradio`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/menuitemradio_role) roles, with the value being the total number of items in the menu, excluding any separators. + +## Example + +The following example shows items 5 through 8 in a set of 16. + +```html +<h2 id="label_fruit">Available Fruit</h2> +<ul role="listbox" aria-labelledby="label_fruit"> + <li role="option" aria-setsize="16" aria-posinset="5">apples</li> + <li role="option" aria-setsize="16" aria-posinset="6">bananas</li> + <li role="option" aria-setsize="16" aria-posinset="7">cantaloupes</li> + <li role="option" aria-setsize="16" aria-posinset="8">dates</li> +</ul> +``` + +To orient the user, assistive technologies would list the bananas above as "item 6 out of 16." + +## Values + +- `<integer>` + - : The number of items in the full set or `-1` is the set size is unknown. + +## Associated interfaces + +- {{domxref("Element.ariaSetSize")}} + - : The [`ariaSetSize`](/en-US/docs/Web/API/Element/ariaSetSize) property, part of the {{domxref("Element")}} interface, reflects the value of the `aria-setsize` attribute. +- {{domxref("ElementInternals.ariaSetSize")}} + - : The [`ariaSetSize`](/en-US/docs/Web/API/ElementInternals/ariaSetSize) property, part of the {{domxref("ElementInternals")}} interface, reflects the value of the `aria-setsize` attribute. + +## Associated roles + +Used in roles: + +- [`article`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/article_role) +- [`associationlistitemkey`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/structural_roles) +- [`associationlistitemvalue`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/structural_roles) +- [`comment`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/comment_role) +- [`listitem`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/listitem_role) +- [`menuitem`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/menuitem_role) +- [`option`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/option_role) +- [`radio`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/radio_role) +- [`row`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/row_role) +- [`tab`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/tab_role) + +Inherits into roles: + +- [`comment`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/comment_role) +- [`menuitemcheckbox`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/menuitemcheckbox_role) +- [`menuitemradio`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/menuitemradio_role) +- [`treeitem`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/treeitem_role) + +## Specifications + +{{Specifications}} + +## See also + +- [`aria-posinset`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-posinset) +- W3C WAI-ARIA practices: + - [Treegrid Email Inbox example](https://www.w3.org/WAI/ARIA/apg/patterns/treegrid/examples/treegrid-1/) + - [Navigation Treeview example](https://www.w3.org/WAI/ARIA/apg/patterns/treeview/examples/treeview-navigation/) + - [File Directory Treeview Example Using Declared Properties](https://www.w3.org/WAI/ARIA/apg/patterns/treeview/examples/treeview-1b/) diff --git a/files/en-us/web/accessibility/aria/reference/attributes/aria-sort/index.md b/files/en-us/web/accessibility/aria/reference/attributes/aria-sort/index.md new file mode 100644 index 000000000000000..44e666a3edf2d5c --- /dev/null +++ b/files/en-us/web/accessibility/aria/reference/attributes/aria-sort/index.md @@ -0,0 +1,86 @@ +--- +title: "ARIA: aria-sort attribute" +short-title: aria-sort +slug: Web/Accessibility/ARIA/Reference/Attributes/aria-sort +page-type: aria-attribute +spec-urls: https://w3c.github.io/aria/#aria-sort +sidebar: accessibilitysidebar +--- + +The `aria-sort` attribute indicates if items in a table or grid are sorted in ascending or descending order. + +## Description + +If a grid or table provides sort functionality, the `aria-sort` attribute should be set to either `ascending` or `descending` (or `other`) on the header cell element for the sorted column or row. + +The `aria-sort` attribute is only set on the currently sorted column or row. Set `aria-sort="ascending"` to indicate the data cells in the column or row are sorted in ascending order. If the sort order is reversed, toggle the value to `aria-sort="descending"`. When a different column or row becomes sorted, the single `aria-sort` attribute is moved to the header cell for the newly sorted column or row with the appropriate value for the sort order. + +The `aria-sort` attribute should only be added to a single table or grid header at a time. The attribute is set to inform assistive technology users which column or row is sorted. It doesn't have any impact on the actual sort order. + +## Examples + +This table loads with the last name column sorted in ascending order. + +```html +<table> + <caption> + Steering Committee Members + </caption> + <thead> + <tr> + <th> + <button>First Name</button> + </th> + <th aria-sort="ascending"> + <button>Last Name</button> + </th> + <th> + <button>Company</button> + </th> + <th>Email</th> + </tr> + </thead> + <tbody> + … + </tbody> +</table> +``` + +If a user clicks on the _Last Name_ button, [`aria-pressed="true"`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-pressed) would be added to the {{HTMLElement('button')}} element and the `aria-sort` value would be toggled to `"descending"` with JavaScript. If the user clicks on a different header button, the `aria-sort` would be removed from the _Last Name_ header to be placed on the clicked button's {{HTMLElement('th')}} parent. + +We provided instructions in the caption for assistive technology who may not see the down arrows that we would add with CSS targeting the `th[aria-sort="ascending"]` and `th[aria-sort="descending"]` selectors. + +## Values + +- `ascending` + - : Items are sorted in ascending order by this column. +- `descending` + - : Items are sorted in descending order by this column. +- `none` (default) + - : There is no defined sort applied to the column. +- `other` + - : A sorting algorithm other than ascending or descending has been applied. + +## Associated interfaces + +- {{domxref("Element.ariaSort")}} + - : The [`ariaSort`](/en-US/docs/Web/API/Element/ariaSort) property, part of the {{domxref("Element")}} interface, reflects the value of the `aria-sort` attribute. +- {{domxref("ElementInternals.ariaSort")}} + - : The [`ariaSort`](/en-US/docs/Web/API/ElementInternals/ariaSort) property, part of the {{domxref("ElementInternals")}} interface, reflects the value of the `aria-sort` attribute. + +## Associated roles + +Used in roles: + +- [`columnheader`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/columnheader_role) +- [`rowheader`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/rowheader_role) + +## Specifications + +{{Specifications}} + +## See also + +- [Sortable table example](https://www.w3.org/TR/wai-aria-practices-1.2/examples/table/sortable-table.html) -W3C +- [`aria-pressed`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-pressed) +- The {{HTMLElement('th')}} element diff --git a/files/en-us/web/accessibility/aria/reference/attributes/aria-valuemax/index.md b/files/en-us/web/accessibility/aria/reference/attributes/aria-valuemax/index.md new file mode 100644 index 000000000000000..dddf88176e44648 --- /dev/null +++ b/files/en-us/web/accessibility/aria/reference/attributes/aria-valuemax/index.md @@ -0,0 +1,77 @@ +--- +title: "ARIA: aria-valuemax attribute" +short-title: aria-valuemax +slug: Web/Accessibility/ARIA/Reference/Attributes/aria-valuemax +page-type: aria-attribute +spec-urls: https://w3c.github.io/aria/#aria-valuemax +sidebar: accessibilitysidebar +--- + +The `aria-valuemax` attribute defines the maximum allowed value for a range widget. + +## Description + +The `aria-valuemax` attribute defines the maximum value allowed for range widgets. It is similar to the `max` attribute of {{HTMLElement('progress')}}, {{HTMLElement('meter')}}, and {{HTMLElement('input')}} of type [`range`](/en-US/docs/Web/HTML/Reference/Elements/input/range), [`number`](/en-US/docs/Web/HTML/Reference/Elements/input/number) and all the date-time types. + +When creating a range type role, including [`meter`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/meter_role), [`scrollbar`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/scrollbar_role), [`slider`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/slider_role), and [`spinbutton`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/spinbutton_role) on a non-semantic element, the `aria-valuemax` enables defining a maximum that is more than the minimum value and is a required attribute of `slider`, `scrollbar` and `spinbutton`. + +Declaring the minimum and maximum values allows assistive technologies to convey the size of the range to users. The minimum value is defined with [`aria-valuemin`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-valuemin). + +> [!WARNING] +> The [`range`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/range_role) role itself should **NOT** be used as it is an ["abstract"](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles#6._abstract_roles). The `aria-valuemax` attribute is used on all of the range roles subtypes. + +## Example + +The code below shows a slider with a maximum value of 9. + +```html +<div id="dimesLabel">Dimes</div> +<div + role="slider" + aria-valuenow="0" + aria-valuemin="0" + aria-valuemax="9" + aria-labelledby="dimesLabel" + id="dimes"></div> +``` + +## Values + +- `<number>` + - : An integer or decimal number that is greater than the minimum value. + +## Associated interfaces + +- {{domxref("Element.ariaValueMax")}} + - : The [`ariaValueMax`](/en-US/docs/Web/API/Element/ariaValueMax) property, part of the {{domxref("Element")}} interface, reflects the value of the `aria-valuemax` attribute. +- {{domxref("ElementInternals.ariaValueMax")}} + - : The [`ariaValueMax`](/en-US/docs/Web/API/ElementInternals/ariaValueMax) property, part of the {{domxref("ElementInternals")}} interface, reflects the value of the `aria-valuemax` attribute. + +## Associated roles + +Used in roles: + +- [`meter`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/meter_role) +- [`scrollbar`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/scrollbar_role) (required) +- [`separator`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/separator_role) +- [`slider`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/slider_role) (required) +- [`spinbutton`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/spinbutton_role) (required) + +Inherited into roles: + +- [`meter`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/meter_role) +- [`progressbar`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/progressbar_role) +- [`scrollbar`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/scrollbar_role) +- [`slider`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/slider_role) +- [`spinbutton`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/spinbutton_role) + +## Specifications + +{{Specifications}} + +## See also + +- [`range` role](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/range_role) +- [`<input type="range>` element `max` attribute](/en-US/docs/Web/HTML/Reference/Elements/input/range#max) +- [`aria-valuemin`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-valuemin) +- [`aria-valuenow`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-valuenow) diff --git a/files/en-us/web/accessibility/aria/reference/attributes/aria-valuemin/index.md b/files/en-us/web/accessibility/aria/reference/attributes/aria-valuemin/index.md new file mode 100644 index 000000000000000..42bbaa7e7e8d148 --- /dev/null +++ b/files/en-us/web/accessibility/aria/reference/attributes/aria-valuemin/index.md @@ -0,0 +1,64 @@ +--- +title: "ARIA: aria-valuemin attribute" +short-title: aria-valuemin +slug: Web/Accessibility/ARIA/Reference/Attributes/aria-valuemin +page-type: aria-attribute +spec-urls: https://w3c.github.io/aria/#aria-valuemin +sidebar: accessibilitysidebar +--- + +The `aria-valuemin` attribute defines the minimum allowed value for a range widget. + +## Description + +The `aria-valuemin` attribute defines the minimum value allowed for range widgets. It is similar to the `min` attribute of {{HTMLElement('progress')}}, {{HTMLElement('meter')}}, and {{HTMLElement('input')}} of type [`range`](/en-US/docs/Web/HTML/Reference/Elements/input/range), [`number`](/en-US/docs/Web/HTML/Reference/Elements/input/number) and all the date-time types. + +When creating a range type role, including [`meter`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/meter_role), [`scrollbar`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/scrollbar_role), [`slider`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/slider_role), and [`spinbutton`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/spinbutton_role) on a non-semantic element, the `aria-valuemin` enables defining a minimum that is less than the maximum value and is a required attribute of `slider`, `scrollbar` and `spinbutton`. + +Declaring the minimum and maximum values allows assistive technologies to convey the size of the range to users. + +The maximum value is defined with [`aria-valuemax`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-valuemax). + +> [!WARNING] +> The [`range`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/range_role) role itself should **NOT** be used as it is an ["abstract"](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles#6._abstract_roles). The `aria-valuemin` attribute is used on all of the range roles subtypes. + +## Values + +- `<number>` + - : A decimal number, below the maximum value. + +## Associated interfaces + +- {{domxref("Element.ariaValueMin")}} + - : The [`ariaValueMin`](/en-US/docs/Web/API/Element/ariaValueMin) property, part of the {{domxref("Element")}} interface, reflects the value of the `aria-valuemin` attribute. +- {{domxref("ElementInternals.ariaValueMin")}} + - : The [`ariaValueMin`](/en-US/docs/Web/API/ElementInternals/ariaValueMin) property, part of the {{domxref("ElementInternals")}} interface, reflects the value of the `aria-valuemin` attribute. + +## Associated roles + +Used in roles: + +- [`meter`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/meter_role) +- [`scrollbar`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/scrollbar_role) +- [`separator`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/separator_role) +- [`slider`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/slider_role) +- [`spinbutton`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/spinbutton_role) + +Inherited into roles: + +- [`meter`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/meter_role) +- [`progressbar`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/progressbar_role) +- [`scrollbar`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/scrollbar_role) +- [`slider`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/slider_role) +- [`spinbutton`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/spinbutton_role) + +## Specifications + +{{Specifications}} + +## See also + +- [`range` role](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/range_role) +- [`<input type="range>` element `min` attribute](/en-US/docs/Web/HTML/Reference/Elements/input/range#min) +- [`aria-valuemax`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-valuemax) +- [`aria-valuenow`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-valuenow) diff --git a/files/en-us/web/accessibility/aria/reference/attributes/aria-valuenow/index.md b/files/en-us/web/accessibility/aria/reference/attributes/aria-valuenow/index.md new file mode 100644 index 000000000000000..902e8c1eb199d55 --- /dev/null +++ b/files/en-us/web/accessibility/aria/reference/attributes/aria-valuenow/index.md @@ -0,0 +1,123 @@ +--- +title: "ARIA: aria-valuenow attribute" +short-title: aria-valuenow +slug: Web/Accessibility/ARIA/Reference/Attributes/aria-valuenow +page-type: aria-attribute +spec-urls: https://w3c.github.io/aria/#aria-valuenow +sidebar: accessibilitysidebar +--- + +The `aria-valuenow` attribute defines the current value for a `range` widget. + +## Description + +The `aria-valuenow` attribute defines the current value for range widgets. It is similar to the `value` attribute of {{HTMLElement('progress')}}, {{HTMLElement('meter')}}, and {{HTMLElement('input')}} of type [`range`](/en-US/docs/Web/HTML/Reference/Elements/input/range), [`number`](/en-US/docs/Web/HTML/Reference/Elements/input/number) and all the date-time types. + +When creating a range type role, including [`meter`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/meter_role), [`scrollbar`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/scrollbar_role), [`slider`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/slider_role), and [`spinbutton`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/spinbutton_role) on a non-semantic element, the `aria-valuenow` enables defining a current numeric value between the minimum and maximum values. The minimum and maximum values are defined with [`aria-valuemin`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-valuemin) and [`aria-valuemax`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-valuemax). + +> [!WARNING] +> The [`range`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/range_role) role itself should **NOT** be used as it is an ["abstract"](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles#6._abstract_roles). The `aria-valuenow` attribute is used on all of the range roles subtypes. + +```html +<p id="birthyearLabel">What year were you born?</p> +<div + role="spinbutton" + tabindex="-1" + aria-valuenow="1984" + aria-valuemin="1900" + aria-valuemax="2021" + aria-labelledby="birthyearLabel"> + <span class="value"> 1984 </span> + <span role="button"> + <span aria-hidden="true">+</span> + Increment year by 1 + </span> + <span role="button"> + <span aria-hidden="true">-</span> + Decrement year by 1 + </span> +</div> +``` + +Use semantic HTML elements when you can: + +```html +<label for="birthyear">What year were you born?</label> +<input type="number" id="birthyear" value="1984" min="1900" max="2021" /> +``` + +If there is no known value, like when a progress bar is in an indeterminate state, don't set an `aria-valuenow` attribute. + +When there is no `aria-valuenow` set, no information is implied about a current value. + +When used with sliders and spinbuttons, assistive technologies announce the actual value to users. + +When used with progressbar and scrollbar, assistive technologies announce the value to users as a percent. When `aria-valuemin` and `aria-valuemax` are both defined, the percent value is calculated as a position on the range. Otherwise, the actual value is announced as a percent. + +When the value to be announced, either the actual value or the value as a percent, may not be clear to users, the [`aria-valuetext`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-valuetext) attribute should be used to provide a user-friendly representation of the value. When set, the valuetext string is announced instead of the valuenow numeric value. For example, if a slider represents the days of the week, so the day of the week's `aria-valuenow` is a number, the `aria-valuetext` property should be set to a string that makes the slider value understandable, such as "Monday". + +## Examples + +```html +<p id="temperatureLabel">Oven Temperature</p> +<div + role="meter" + id="temperature" + aria-valuenow="205" + aria-valuemin="70" + aria-valuemax="250" + aria-labelledby="temperatureLabel"> + <div class="meter-color" aria-hidden="true"></div> +</div> +``` + +The first rule of ARIA use is "if you can use a native feature with the semantics and behavior you require already built in, instead of repurposing an element and **adding** an ARIA role, state or property to make it accessible, then do so." + +```html +<label for="temperature">Oven Temperature</label> +<input type="range" id="temperature" value="205" min="70" max="250" step="5" /> +``` + +If we employ native HTML semantics with {{HTMLElement('input')}} we get styles and semantics for free. + +## Values + +- `<number>` + - : A decimal number, between the minimum and maximum values. + +## Associated interfaces + +- {{domxref("Element.ariaValueNow")}} + - : The [`ariaValueNow`](/en-US/docs/Web/API/Element/ariaValueNow) property, part of the {{domxref("Element")}} interface, reflects the value of the `aria-valuenow` attribute. +- {{domxref("ElementInternals.ariaValueNow")}} + - : The [`ariaValueNow`](/en-US/docs/Web/API/ElementInternals/ariaValueNow) property, part of the {{domxref("ElementInternals")}} interface, reflects the value of the `aria-valuenow` attribute. + +## Associated roles + +Used in roles: + +- [`meter`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/meter_role) +- [`scrollbar`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/scrollbar_role) +- [`separator`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/separator_role) +- [`slider`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/slider_role) +- [`spinbutton`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/spinbutton_role) + +Inherited into roles: + +- [`meter`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/meter_role) +- [`progressbar`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/progressbar_role) +- [`scrollbar`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/scrollbar_role) +- [`slider`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/slider_role) +- [`spinbutton`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/spinbutton_role) + +## Specifications + +{{Specifications}} + +## See also + +- [`range` role](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/range_role) +- [`<input type="range>` element `value` attribute](/en-US/docs/Web/HTML/Reference/Elements/input/range#value) +- [`aria-valuetext`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-valuetext) +- [`aria-valuemax`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-valuemax) +- [`aria-valuemin`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-valuemin). diff --git a/files/en-us/web/accessibility/aria/reference/attributes/aria-valuetext/index.md b/files/en-us/web/accessibility/aria/reference/attributes/aria-valuetext/index.md new file mode 100644 index 000000000000000..e42f3c7df1305c9 --- /dev/null +++ b/files/en-us/web/accessibility/aria/reference/attributes/aria-valuetext/index.md @@ -0,0 +1,58 @@ +--- +title: "ARIA: aria-valuetext attribute" +short-title: aria-valuetext +slug: Web/Accessibility/ARIA/Reference/Attributes/aria-valuetext +page-type: aria-attribute +spec-urls: https://w3c.github.io/aria/#aria-valuetext +sidebar: accessibilitysidebar +--- + +The `aria-valuetext` attribute defines the human-readable text alternative of `aria-valuenow` for a range widget. + +## Description + +Numbers — even percentages — aren't always user-friendly. Assistive technologies present [`aria-valuenow`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-valuenow) as numeric values. If a progress bar is at 8%, what does that mean? `aria-valuetext` provides a way of presenting the current value in a more user-friendly, human-understandable way. For example, a battery meter value might be conveyed as `aria-valuetext="8% (34 minutes) remaining"`. + +The `aria-valuetext` attribute is used with the `aria-valuenow` attribute, not instead of it, unless that value is not known. + +`aria-valuetext` is only needed when the numeric value of `aria-valuenow` is not meaningful. For example, a range's values are numeric but may be used for non-numeric values, such as college class level. The values of `aria-valuenow` for a 4-year college could range from 1 through 4, which indicate the position of each value in the value space. In this case, the `aria-valuetext` could be one of the strings: "first year", "sophomore", "junior", and "senior". + +If the numeric value is meaningful, such as a spinner with `aria-valuenow="3"` for how many pizza slices you want to order, `aria-valuetext` is not needed. + +When both the `aria-valuetext` and `aria-valuenow` are included, the `aria-valuetext` is announced. When there is no `aria-valuetext` attribute, assistive technologies will announce the `aria-valuenow` attribute for the current value. + +## Values + +- `<string>` + - : A human-readable text alternative of the `aria-valuenow` value. + +## Associated interfaces + +- {{domxref("Element.ariaValueText")}} + - : The [`ariaValueText`](/en-US/docs/Web/API/Element/ariaValueText) property, part of the {{domxref("Element")}} interface, reflects the value of the `aria-valuetext` attribute. +- {{domxref("ElementInternals.ariaValueText")}} + - : The [`ariaValueText`](/en-US/docs/Web/API/ElementInternals/ariaValueText) property, part of the {{domxref("ElementInternals")}} interface, reflects the value of the `aria-valuetext` attribute. + +## Associated roles + +Used in roles: + +- [`range`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/range_role) +- [`separator`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/separator_role) +- [`spinbutton`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/spinbutton_role) + +Inherited into roles: + +- [`meter`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/meter_role) +- [`progressbar`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/progressbar_role) +- [`scrollbar`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/scrollbar_role) +- [`slider`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/slider_role) +- [`spinbutton`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/spinbutton_role) + +## Specifications + +{{Specifications}} + +## See also + +- [`aria-valuenow`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-valuenow) diff --git a/files/en-us/web/accessibility/aria/reference/attributes/index.md b/files/en-us/web/accessibility/aria/reference/attributes/index.md new file mode 100644 index 000000000000000..f22e51631a5869c --- /dev/null +++ b/files/en-us/web/accessibility/aria/reference/attributes/index.md @@ -0,0 +1,118 @@ +--- +title: ARIA states and properties (attributes) +short-title: Attributes +slug: Web/Accessibility/ARIA/Reference/Attributes +page-type: landing-page +sidebar: accessibilitysidebar +--- + +This page lists reference pages covering all the <abbr>WAI-ARIA</abbr> attributes discussed on MDN. + +<abbr>ARIA</abbr> attributes enable modifying an element's states and properties as defined in the accessibility tree. + +> [!NOTE] +> ARIA only modifies the accessibility tree, modifying how assistive technology presents the content to your users. ARIA doesn't change anything about an element's function or behavior. When not using semantic HTML elements for their intended purpose and default functionality, you must use JavaScript to manage behavior, focus, and ARIA states. + +## ARIA attribute types + +There are 4 categories of ARIA states and properties: + +### Widget attributes + +- [`aria-autocomplete`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-autocomplete) +- [`aria-checked`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-checked) +- [`aria-disabled`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-disabled) +- [`aria-errormessage`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-errormessage) +- [`aria-expanded`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-expanded) +- [`aria-haspopup`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-haspopup) +- [`aria-hidden`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-hidden) +- [`aria-invalid`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-invalid) +- [`aria-label`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-label) +- [`aria-level`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-level) +- [`aria-modal`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-modal) +- [`aria-multiline`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-multiline) +- [`aria-multiselectable`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-multiselectable) +- [`aria-orientation`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-orientation) +- [`aria-placeholder`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-placeholder) +- [`aria-pressed`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-pressed) +- [`aria-readonly`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-readonly) +- [`aria-required`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-required) +- [`aria-selected`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-selected) +- [`aria-sort`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-sort) +- [`aria-valuemax`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-valuemax) +- [`aria-valuemin`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-valuemin) +- [`aria-valuenow`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-valuenow) +- [`aria-valuetext`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-valuetext) + +### Live region attributes + +- [`aria-busy`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-busy) +- [`aria-live`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-live) +- [`aria-relevant`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-relevant) +- [`aria-atomic`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-atomic) + +### Drag-and-Drop attributes + +- [`aria-dropeffect`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-dropeffect) +- [`aria-grabbed`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-grabbed) + +### Relationship attributes + +- [`aria-activedescendant`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-activedescendant) +- [`aria-colcount`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-colcount) +- [`aria-colindex`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-colindex) +- [`aria-colspan`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-colspan) +- [`aria-controls`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-controls) +- [`aria-describedby`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-describedby) +- [`aria-description`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-description) +- [`aria-details`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-details) +- [`aria-errormessage`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-errormessage) +- [`aria-flowto`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-flowto) +- [`aria-labelledby`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-labelledby) +- [`aria-owns`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-owns) +- [`aria-posinset`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-posinset) +- [`aria-rowcount`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-rowcount) +- [`aria-rowindex`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-rowindex) +- [`aria-rowspan`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-rowspan) +- [`aria-setsize`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-setsize) + +## Global ARIA attributes + +Some states and properties apply to all HTML elements regardless of whether an ARIA role is applied. These are defined as "Global" attributes. Global states and properties are supported by all roles and base markup elements. + +Many of the above attributes are global, meaning they can be included on any element unless specifically disallowed: + +- [`aria-atomic`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-atomic) +- [`aria-busy`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-busy) +- [`aria-controls`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-controls) +- [`aria-current`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-current) +- [`aria-describedby`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-describedby) +- [`aria-description`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-description) +- [`aria-details`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-details) +- [`aria-disabled`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-disabled) +- [`aria-dropeffect`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-dropeffect) +- [`aria-errormessage`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-errormessage) +- [`aria-flowto`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-flowto) +- [`aria-grabbed`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-grabbed) +- [`aria-haspopup`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-haspopup) +- [`aria-hidden`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-hidden) +- [`aria-invalid`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-invalid) +- [`aria-keyshortcuts`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-keyshortcuts) +- [`aria-label`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-label) +- [`aria-labelledby`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-labelledby) +- [`aria-live`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-live) +- [`aria-owns`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-owns) +- [`aria-relevant`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-relevant) +- [`aria-roledescription`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-roledescription) + +By "specifically disallowed," all the above attributes are global except for the `aria-label` and `aria-labelledby` properties, which are not allowed on elements with role [`presentation`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/presentation_role) nor its synonym [`none`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/none_role) role. + +## Index of states and properties + +The following are the reference pages covering the <abbr>WAI-ARIA</abbr> states and properties described on <abbr>MDN</abbr>. + +{{SubpagesWithSummaries}} + +## See also + +- [Using ARIA: roles, states, and properties](/en-US/docs/Web/Accessibility/ARIA/Guides/Techniques) diff --git a/files/en-us/web/accessibility/aria/reference/index.md b/files/en-us/web/accessibility/aria/reference/index.md new file mode 100644 index 000000000000000..e58afdfeafaf9e0 --- /dev/null +++ b/files/en-us/web/accessibility/aria/reference/index.md @@ -0,0 +1,10 @@ +--- +title: ARIA reference +slug: Web/Accessibility/ARIA/Reference +page-type: listing-page +sidebar: accessibilitysidebar +--- + +This page lists reference documentation for Accessible Rich Internet Applications (ARIA). + +{{SubPagesWithSummaries}} diff --git a/files/en-us/web/accessibility/aria/reference/roles/alert_role/index.md b/files/en-us/web/accessibility/aria/reference/roles/alert_role/index.md new file mode 100644 index 000000000000000..d191ad531249dff --- /dev/null +++ b/files/en-us/web/accessibility/aria/reference/roles/alert_role/index.md @@ -0,0 +1,127 @@ +--- +title: "ARIA: alert role" +short-title: alert +slug: Web/Accessibility/ARIA/Reference/Roles/alert_role +page-type: aria-role +spec-urls: + - https://w3c.github.io/aria/#alert + - https://www.w3.org/TR/wai-aria-1.2/#alert +sidebar: accessibilitysidebar +--- + +The `alert` role is for important, and usually time-sensitive, information. The `alert` is a type of [`status`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/status_role) processed as an atomic live region. + +## Description + +The `alert` role is used to communicate an important and usually time-sensitive message to the user. When this role is added to an element, the browser will send out an accessible alert event to assistive technology products which can then notify the user. + +The alert role should only be used for information that requires the user's immediate attention, for example: + +- An invalid value was entered into a form field +- The user's login session is about to expire +- The connection to the server was lost so local changes will not be saved + +The `alert` role should only be used for text content, not interactive elements such as links or buttons. The element with the `alert` role does not have to be able to receive focus, as screen readers (speech or braille) will automatically announce the updated content regardless of where keyboard focus when the role is added. + +The `alert` role is added to the node containing an alert message, **not** the element causing the alert to be triggered. Alerts are [assertive live regions](/en-US/docs/Web/Accessibility/ARIA/Guides/Live_regions). Setting `role="alert"` is equivalent to setting [`aria-live="assertive"`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-live) and [`aria-atomic="true"`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-atomic). As they don't receive focus, focus does not need to be managed and no user interaction should be required. + +> [!WARNING] +> Because of its intrusive nature, the `alert` role must be used sparingly and only in situations where the user's immediate attention is required. + +The [`alert`](https://www.w3.org/TR/wai-aria-1.1/#alert) role is of the five [live region](/en-US/docs/Web/Accessibility/ARIA/Guides/Live_regions) roles. Dynamic changes that are less urgent should use a less aggressive method, such as including `aria-live="polite"` or using an other live region role like [`status`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/status_role). If the user is expected to close the alert, then the [`alertdialog`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/alertdialog_role) role should be used instead. + +The most important thing to know about the `alert` role is that it's for content that is dynamically displayed, not for content that appears on page load. It is perfect for situations such as when a user fills out a form and JavaScript is used to add an error message - the alert would immediately read out the message. It should not be used on HTML that the user hasn't interacted with. For example, if a page loads with multiple visible alerts scattered throughout, the alert role should not be used, as the messages were not dynamically triggered. + +As with all other [live regions](/en-US/docs/Web/Accessibility/ARIA/Guides/Live_regions), alerts will only be announced when the content of the element with `role="alert"` is _updated_. Make sure that the element with the role is present in the page's markup first - this will "prime" the browser and screen reader to keep watching the element for changes. After this, any changes to the content will be announced. Do not try to dynamically add/generate an element with `role="alert"` that is already populated with the alert message you want announced - this generally does _not_ lead to an announcement, as it is not a content change. + +As the `alert` role reads out any content that has changed, it should be used with caution. Alerts, by definition, are disruptive. Several alerts at once, and unnecessary alerts, create bad user experiences. + +## Examples + +The following are common examples of alerts and how to implement them: + +### Example 1: Making ready-made content inside an element with an alert role visible + +If the content _inside_ the element with `role="alert"` is initially hidden using CSS, making it visible will cause the alert to fire. This means that an existing alert container element can be "reused" multiple times. + +```css +.hidden { + display: none; +} +``` + +```html +<div id="expirationWarning" role="alert"> + <span class="hidden">Your log in session will expire in 2 minutes</span> +</div> +``` + +```js +// removing the 'hidden' class makes the content inside the element visible, which will make the screen reader announce the alert: +document + .getElementById("expirationWarning") + .firstChild.classList.remove("hidden"); +``` + +### Example 2: Dynamically changing the content inside an element with an alert role + +Using JavaScript, you can dynamically change the content _inside_ the element with `role="alert"`. Note that if you need to fire the same alert multiple times (i.e., the content you're dynamically inserting is the same as before), this generally won't be seen as a change and will _not_ lead to an announcement. For this reason, it's usually best to briefly "clear" the contents of the alert container before then injecting the alert message. + +```html +<div id="alertContainer" role="alert"></div> +``` + +```js +// clear the contents of the container +document.getElementById("alertContainer").textContent = ""; +// inject the new alert message +document.getElementById("alertContainer").textContent = + `Your session will expire in ${expiration} minutes`; +``` + +### Example 3: Visually hidden alert container for screen reader notifications + +It's possible to visually hide the alert container itself, and use it to provide updates/notifications explicitly for screen readers. This can be useful in situations where important content on the page has been updated, but where the change would not be immediately obvious to a screen-reader user. + +However, make sure that the container is not hidden using `display:none`, as this will hide it even from assistive technologies, meaning that they won't be notified of any changes. Instead, use something like the [`.visually-hidden` styles](https://www.a11yproject.com/posts/how-to-hide-content/). + +```html +<div id="hiddenAlertContainer" role="alert" class="visually-hidden"></div> +``` + +```css +.visually-hidden { + clip: rect(0 0 0 0); + clip-path: inset(50%); + height: 1px; + overflow: hidden; + position: absolute; + white-space: nowrap; + width: 1px; +} +``` + +```js +// clear the contents of the container +document.getElementById("hiddenAlertContainer").textContent = ""; +// inject the new alert message +document.getElementById("hiddenAlertContainer").textContent = + "All items were removed from your inventory."; +``` + +## Specifications + +{{Specifications}} + +## See also + +- [`aria-live`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-live) +- [`aria-atomic`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-atomic) +- [ARIA: `log` role](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/log_role) +- [ARIA: `marquee` role](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/marquee_role) +- [ARIA: `status` role](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/status_role) +- [ARIA: `timer` role](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/timer_role) +- [ARIA: `alertdialog` role](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/alertdialog_role) +- [ARIA: live regions](/en-US/docs/Web/Accessibility/ARIA/Guides/Live_regions) +- [ARIA alert support - The Paciello Group](https://www.tpgi.com/aria-alert-support/) +- [ARIA Practices alert example](https://www.w3.org/WAI/ARIA/apg/patterns/alert/examples/alert/) diff --git a/files/en-us/web/accessibility/aria/reference/roles/alertdialog_role/index.md b/files/en-us/web/accessibility/aria/reference/roles/alertdialog_role/index.md new file mode 100644 index 000000000000000..8f459ed92788ac9 --- /dev/null +++ b/files/en-us/web/accessibility/aria/reference/roles/alertdialog_role/index.md @@ -0,0 +1,111 @@ +--- +title: "ARIA: alertdialog role" +short-title: alertdialog +slug: Web/Accessibility/ARIA/Reference/Roles/alertdialog_role +page-type: aria-role +spec-urls: + - https://w3c.github.io/aria/#alertdialog + - https://www.w3.org/TR/wai-aria-1.2/#alertdialog +sidebar: accessibilitysidebar +--- + +The **alertdialog** role is to be used on modal alert dialogs that interrupt a user's workflow to communicate an important message and require a response. + +## Description + +The `alertdialog` role is used to notify users of urgent information that demands the user's immediate attention. Including `role="alertdialog"` on the element containing the dialog helps assistive technology identify the content as being grouped and separated from the rest of the page content. Examples include error messages that require confirmation and other action confirmation prompts. + +As the name implies, `alertdialog` is a mashup of the [`dialog`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/dialog_role) and [`alert`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/alert_role) roles. `alertdialog` is a type of `dialog` with similar use cases as `alert`, but for when a user response is required. + +> [!NOTE] +> The `alertdialog` role should only be used for alert messages that have associated interactive controls. If an alert dialog only contains static content and has no interactive controls at all, use [`alert`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/alert_role) instead. + +Being a type of dialog, the [`dialog`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/dialog_role) role's states, properties, and keyboard focus requirements are applicable to the `alertdialog` role as well. + +Because of its urgent nature, interrupting the user's workflow, alert dialogs should be [modal](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-modal). + +The alert dialog must have at least one focusable control — such as Confirm, Close, and Cancel — and focus must be moved to that control when the alert dialog appears. Alert dialogs can have additional interactive controls such as text fields and checkboxes. + +The `alertdialog` role is not to be used as a replacement for other dialogs, including no-confirmation-required `alert` dialogs ([`Window.alert()`](/en-US/docs/Web/API/Window/alert)) and prompts ([`Window.prompt()`](/en-US/docs/Web/API/Window/prompt)). + +Adding `role="alertdialog"` alone is not sufficient to make an alert dialog accessible. The following also need to be done: + +- The alert dialog must be properly labeled +- Keyboard focus must be managed correctly + +The `alertdialog` must have an accessible name, defined with [`aria-labelledby`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-labelledby) or [`aria-label`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-label). The alert dialog text must have an {{glossary("accessible description")}} using [`aria-describedby`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-describedby). + +### Associated WAI-ARIA roles, states, and properties + +- [`aria-labelledby`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-labelledby) + + - : Use this attribute to label the alertdialog. The `aria-labelledby` attribute is generally the id of the element used to title the alertdialog. + +- [`aria-describedby`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-describedby) + - : Use this attribute to encompass the description of the contents of the alert dialog. The value of the `aria-describedby` attribute is generally the ID of the element containing the alert dialog's messaging, usually coming right after the title. + +## Examples + +### Example 1: A basic alert dialog + +```html +<div + role="alertdialog" + aria-labelledby="dialog1Title" + aria-describedby="dialog1Desc"> + <div role="document" tabindex="0"> + <h2 id="dialog1Title">Your login session is about to expire</h2> + <p id="dialog1Desc">To extend your session, click the OK button</p> + <button>OK</button> + </div> +</div> +``` + +The code snippet above shows how to mark up an alert dialog that only provides a message and an OK button. + +### Example 2: Confirmation dialog with two options + +```html +<div + id="alert_dialog" + role="alertdialog" + aria-modal="true" + aria-labelledby="dialog_label" + aria-describedby="dialog_desc"> + <h2 id="dialog_label">Confirmation</h2> + <div id="dialog_desc"> + <p>Are you sure you want to delete this image?</p> + <p>This change can't be undone.</p> + </div> + <ul> + <li> + <button id="close-btn" type="button">No</button> + </li> + <li> + <button id="confirm-btn" type="button" aria-controls="form">Yes</button> + </li> + </ul> +</div> +``` + +```js +document.getElementById("close-btn").addEventListener("click", () => { + closeDialog(); +}); +document.getElementById("confirm-btn").addEventListener("click", (event) => { + deleteFile(); +}); +``` + +## Specifications + +{{Specifications}} + +## See also + +- HTML {{HTMLElement("dialog")}} element +- [The `dialog` role](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/dialog_role) +- [The `alert` role](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/alert_role) +- [`aria-modal` attribute](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-modal) +- [`Window.alert()`](/en-US/docs/Web/API/Window/alert) +- [`Window.prompt()`](/en-US/docs/Web/API/Window/prompt) diff --git a/files/en-us/web/accessibility/aria/reference/roles/application_role/index.md b/files/en-us/web/accessibility/aria/reference/roles/application_role/index.md new file mode 100644 index 000000000000000..835ce97b13be5d5 --- /dev/null +++ b/files/en-us/web/accessibility/aria/reference/roles/application_role/index.md @@ -0,0 +1,100 @@ +--- +title: "ARIA: application role" +short-title: application +slug: Web/Accessibility/ARIA/Reference/Roles/application_role +page-type: aria-role +spec-urls: https://w3c.github.io/aria/#application +sidebar: accessibilitysidebar +--- + +The `application` role indicates to assistive technologies that an element _and all of its children_ should be treated similar to a desktop application, and no traditional HTML interpretation techniques should be used. This role should only be used to define very dynamic and desktop-like web applications. Most mobile and desktop web apps _are not_ considered applications for this purpose. + +```html +<div role="application" aria-label="…">…</div> +``` + +By specifying the `application` role, it indicates this `div` element and all of its descendants are to be treated like they are part of a desktop application. + +## Description + +The `application` [document structure role](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles#1._document_structure_roles), indicates to assistive technologies that this part of the web content contains elements that do not conform to any other known HTML element or WAI-ARIA widget. Any sort of special interpretation of HTML structures and widgets should be suspended, and control should be completely handed over to the browser and web application to handle mouse, keyboard, or touch interaction. + +In this mode, the web author is completely responsible for handling any and all keyboard input, focus management, and other interactions and cannot assume assistive technologies would do any processing on their end. + +If the web application encompassed by the application role contains parts that _should_ be treated like normal web content, a role of [`document`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/document_role) or [`article`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/article_role) should be used to contain such content. + +### Background + +For historic reasons, especially on Windows, screen readers and some other assistive technologies (AT) have traditionally grabbed the whole web content from the browser at once after it had finished loading. The ATs build their own representation of it that makes the most sense for a visually impaired user to consume the content. This is often referred to as _virtual document_, _browse mode_, or similar terms. The document is streamlined to a single-column view. A keyboard interaction model is generated that is very similar to a word processor where users can read line by line, sentence by sentence, or paragraph by paragraph. The AT will read any semantics like links, headings, form controls, tables, lists, or images. + +In addition, a set of so-called _quick navigation keys_ has been established over the years that allows visually impaired users to skim through a page via a certain element type. Such elements usually include headings, form fields, lists, tables, links, graphics, or landmark regions. + +For all of this to work, ATs intercept almost all keyboard input and consume it themselves, letting nothing through to the browser or other user agent. To be able to interact with a web page, a standard set of widgets is recognized that, when pressing a certain key (usually the <kbd>Enter</kbd> key) this mode is switched off. The screen reader mode, often called _forms mode_ or _focus mode_, lets all keyboard input go through to the browser again. <kbd>Escape</kbd> is the most common way of switching back to _browse_ mode, but when within a specific `application` section, some screen readers may require other keys to purposefully exit this mode. For instance <kbd>NUMPAD PLUS</kbd> with JAWS. + +The `application` role is designed to provide a means for widgets that are not part of the standard set to be accessible for direct interaction in ATs that use both _browse_ and _focus_ modes for interacting with web content. Most common widgets have expected keyboard interaction behaviors. Because of this, a custom keyboard experience created by a web author would create a confusing experience. + +### Associated WAI-ARIA roles, states, and properties + +- [`document`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/document_role), [`article`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/article_role) + - : Used to indicate parts of the application that should be treated as normal web content +- [`aria-activedescendant`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-activedescendant) + - : Used to manage focus inside the application. +- [`aria-label`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-label) + - : Used to provide the name of the application or purpose of the widget that is being exposed. +- [`aria-describedby`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-describedby) + - : Used to reference the ID of an element that contains additional instructions for navigating or operating this element. +- [`aria-roledescription`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-roledescription) + - : Used to give the application a more descriptive role text for screen readers to speak. This should be localized. +- [`aria-disabled`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-disabled) + - : Indicates that an element is visible but disabled +- [`aria-errormessage`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-errormessage) + - : A reference to the element that provides the error message for the element on which it is set +- [`aria-expanded`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-expanded) + - : If set to `true`, the grouping element owned or controlled by this element is expanded, or `false` if collapsed. +- [`aria-haspopup`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-haspopup) + - : Indicates there is a popup, such as menu or dialog, that can be triggered by the element. + +### Keyboard interactions + +Keyboard interaction is completely under the web author's control and can be anything associated with the particular widget being implemented. In a slides application, for example, a widget could be created that uses the arrow keys to position elements on the slide, and uses audio feedback via an ARIA live region to communicate the position and overlap status with other objects. Focus is being managed via _aria-activedescendant_. + +The <kbd>Tab</kbd>, <kbd>Space</kbd> and <kbd>Enter</kbd> keys, as well as <kbd>Escape</kbd>, must be handled by the application. The one exception is if focus is set to a standard widget inside the application that supports keyboard navigation from the browser, for example an [input](/en-US/docs/Web/HTML/Reference/Elements/input) element. + +### Required JavaScript features + +- keyPress + - : Used to handle keyboard input and control the focus +- Click, Touch + - : Handle as appropriate for your widget as well +- Changing attribute values + - : [`aria-activedescendant`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-activedescendant) is used to manage the focus inside the application container. Set in response to keyboard or other application events that change focus or point of interaction. + +> [!NOTE] +> The `application` role does not have a related HTML widget and thus is completely free form. The author of the application must take full responsibility for not letting users get stuck in a focus trap inside something the user cannot exit from. All aspects of interaction, including returning to the regular web content on other parts of the page, must be handled. Use wisely, and cautiously, and remember to test! + +## Examples + +Some prominent web applications that use or have used the application role properly are: + +- Google Docs, Sheets and Slides +- CKEditor and TinyMCE WYSIWYG web editors, like the one used on the Mozilla Developer Network +- Some parts of Gmail + +## Accessibility concerns + +Improperly using the `application` role can unintentionally take away access from information on a web page, so be very mindful of using it. Think hard on if you actually need it and cannot just use a set of other known widgets to accomplish the same task. + +If used, the application role should be added to the lowest common container possible, not on the `<body>` element, for example. Also be sure to test what you have written with assistive technology, to verify it works as intended. + +## Specifications + +{{Specifications}} + +## Precedence order + +Applying the `application` role will cause this and all of the descendant elements of this element to be treated like application content, not web content. Any reading mechanisms assistive technologies may have for web content will not apply. + +## See also + +- [If you use the WAI-ARIA role `application`, please do so wisely](https://www.marcozehe.de/if-you-use-the-wai-aria-role-application-please-do-so-wisely/) - blog post by Marco Zehe +- [Using the ARIA `application` role](https://tink.uk/using-the-aria-application-role/) - by Léonie Watson diff --git a/files/en-us/web/accessibility/aria/reference/roles/article_role/index.md b/files/en-us/web/accessibility/aria/reference/roles/article_role/index.md new file mode 100644 index 000000000000000..0b7e836596d1afe --- /dev/null +++ b/files/en-us/web/accessibility/aria/reference/roles/article_role/index.md @@ -0,0 +1,92 @@ +--- +title: "ARIA: article role" +short-title: article +slug: Web/Accessibility/ARIA/Reference/Roles/article_role +page-type: aria-role +spec-urls: + - https://w3c.github.io/aria/#article + - https://www.w3.org/WAI/ARIA/apg/patterns/feed/examples/feed/ +sidebar: accessibilitysidebar +--- + +The `article` role indicates a section of a page that could easily stand on its own on a page, in a document, or on a website. It is usually set on related content items such as comments, forum posts, newspaper articles or other items grouped together on one page. + +```html +<div role="article"> + <h2>Heading of the segment</h2> + <p>Paragraph for the segment.</p> + <p>Another paragraph.</p> + Controls to interact with the article, share it, etc. +</div> +<div role="article">…</div> +``` + +This example shows two articles side by side on one page that could be structured similarly and are related. + +> [!NOTE] +> Instead of a `<div>` with an `article` role, use the {{HTMLElement('article')}} element. **Always use native element if available** + +Don't use `role="article"`. Instead use the `<article>` element. + +```html +<article> + <h2>Heading of the segment</h2> + <p>Paragraph for the segment.</p> + <p>Another paragraph.</p> + Controls to interact with the article, share it, etc. +</article> +<article>…</article> +``` + +## Description + +The `article` [document structure role](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles#1._document_structure_roles) denotes a section of a document, page, or site that, if it were standing on its own, could be viewed as a complete document, page or site. The aim of a set of article sections is to indicate their relationship to one another. + +Articles are not considered a navigational landmark, but many assistive technologies that support landmarks also support a means to navigate among articles. They may also support indication of nesting relationships within articles. + +Articles can be nested, indicating that a nested article directly relates to the one it is nested in, but not necessarily to the ones outside the nesting hierarchy. Reference the examples for specific use cases. + +If an article is part of a feed, it can have the [`aria-posinset`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-posinset) and [`aria-setsize`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-setsize) attributes set to indicate which position within the feed this particular article represents. + +Inside an `application` or other widget that causes screen readers and other assistive technologies to be in pass-through mode, an article can be used to indicate that these should switch back to treating the enclosed content as regular web content. + +Instead of including the `article` role on a non-semantic element, the {{HTMLElement('article')}} element should be used. User agents translate this to the appropriate accessibility information just like the `article` role. Using the {{HTMLElement('article')}} element also helps search engines better discover the structure of a page. Examples of appropriate uses of the `role="article"`, or preferably `<article>`, include blog posts, forum posts, a comment to a forum or blog post, any an item in a social media feed. + +### Associated WAI-ARIA roles, states, and properties + +- [`aria-posinset`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-posinset) + - : In the context of a feed, indicates the position of this particular article within that feed, based on a count starting at 1. +- [`aria-setsize`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-setsize) + - : In the context of a feed, indicates how many article items there are within that feed. + +### Keyboard interactions + +This role does not support any specific keyboard interaction. + +### Required JavaScript features + +- Event handlers + - : This role does not require any event handlers to be present. +- Changing attribute values + - : When constructing a feed, set the `aria-posinset` and `aria-setsize` attributes on each article role to the appropriate values, bearing in mind that `aria-posinset` is 1-based. + +> **Note:** **Always use native element if available.** Instead of a `<div>` with the `article` role, the `<article>` element should be used. + +## Examples + +- The [restaurant recommendations feed display](https://www.w3.org/WAI/ARIA/apg/patterns/feed/examples/feed-display.html) along with its separate [documentation](https://www.w3.org/WAI/ARIA/apg/patterns/feed/examples/feed/) from the WAI-ARIA 1.1 authoring practices feed design pattern + +## Specifications + +{{Specifications}} + +## Precedence order + +This role corresponds to the {{HTMLElement('article')}} element in HTML, and that element should be used instead, if possible. This role does not require any specific roles to be present among its children. It is the only role allowed as a direct child of an element with the [`feed`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/feed_role) role. + +## See also + +- [`feed` role](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/feed_role) +- [`section` role](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/section_role) +- The {{HTMLElement('article')}} element +- {{Glossary("RSS")}} glossary definition diff --git a/files/en-us/web/accessibility/aria/reference/roles/banner_role/index.md b/files/en-us/web/accessibility/aria/reference/roles/banner_role/index.md new file mode 100644 index 000000000000000..beb8903a3580f6a --- /dev/null +++ b/files/en-us/web/accessibility/aria/reference/roles/banner_role/index.md @@ -0,0 +1,75 @@ +--- +title: "ARIA: banner role" +short-title: banner +slug: Web/Accessibility/ARIA/Reference/Roles/banner_role +page-type: aria-role +spec-urls: + - https://w3c.github.io/aria/#banner + - https://www.w3.org/WAI/ARIA/apg/patterns/landmarks/examples/banner.html +sidebar: accessibilitysidebar +--- + +The `banner` role is for defining a global site header, which usually includes a logo, company name, search feature, and possibly the global navigation or a slogan. It is generally located at the top of the page. + +By default, the HTML's {{htmlelement("header")}} element has an identical meaning to the `banner` landmark, unless it is a descendant of {{htmlelement("aside")}}, {{htmlelement("article")}}, {{htmlelement("main")}}, {{htmlelement("nav")}}, or {{htmlelement("section")}}, at which point {{htmlelement("header")}} exposes a [`generic`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/generic_role) role, and not the equivalent of the site-wide banner. + +## Description + +A `banner` landmark role overwrites the implicit ARIA role of the container element upon which it is applied. It should be reserved for globally repeating site-wide content that is generally located at the top of every page. + +The banner typically includes things such as a logo or corporate identity, or possibly a site-specific search tool, and is generally what your marketing team would call the "header" or "top banner" of the site. If the [`header` element](/en-US/docs/Web/HTML/Reference/Elements/header) technique is not being used for that banner, a declaration of `role="banner"` should be used to define a banner landmark to assistive technologies. + +Assistive technologies can identify the `header` element of a page as the `banner` if it is a descendant of the [`body` element](/en-US/docs/Web/HTML/Reference/Elements/body), and not nested within an `article`, `aside`, `main`, `nav` or `section` subsection. + +Each page may have a `banner` landmark, but each page should generally be limited to a single element with the role of banner. In the case of a page containing nested `document` and/or `application` roles, each nested `document` or `application` role may also have one `banner` landmark. If a page includes more than one `banner` landmark, each should have a unique accessible name. + +### Associated ARIA roles, states, and properties + +None. + +### Keyboard interactions + +None. + +### Required JavaScript features + +None. + +## Examples + +Here's a fake banner with a skip to navigation link, a logo, a title and a subtitle. As this is the main header for the site, we've added the `banner` landmark role to the container element. + +```html +<div role="banner"> + <a href="#main" id="skipToMain" class="skiptocontent">Skip To main content</a> + <img src="images/w3c.png" alt="W3C Logo" /> + <h1>ARIA Landmarks</h1> + <p>Identifying page subsections for easy navigation</p> + <nav>…</nav> +</div> +``` + +We could also have written the above with the HTML `header` element: + +```html +<header> + <a href="#main" id="skipToMain" class="skiptocontent">Skip To main content</a> + <img src="images/w3c.png" alt="W3C Logo" /> + <h1>ARIA Landmarks</h1> + <p>Identifying page subsections for easy navigation</p> + <nav>…</nav> +</header> +``` + +## Best practices + +While it is best to use the `header` element and ensure it is not a descendant of any subsection of the page, sometimes you don't have access to the underlying HTML. If this is the case, you can add the role of `banner` to the element of the page which should be exposed as a `banner` with JavaScript. Identifying the page's banner in this way will help improve the site's accessibility. + +## Specifications + +{{Specifications}} + +## See also + +- [HTML `header` element](/en-US/docs/Web/HTML/Reference/Elements/header) +- [WC3 Landmarks Example](https://www.w3.org/WAI/ARIA/apg/patterns/landmarks/examples/banner.html) diff --git a/files/en-us/web/accessibility/aria/reference/roles/button_role/index.md b/files/en-us/web/accessibility/aria/reference/roles/button_role/index.md new file mode 100644 index 000000000000000..69eac230a0e3f01 --- /dev/null +++ b/files/en-us/web/accessibility/aria/reference/roles/button_role/index.md @@ -0,0 +1,292 @@ +--- +title: "ARIA: button role" +short-title: button +slug: Web/Accessibility/ARIA/Reference/Roles/button_role +page-type: aria-role +spec-urls: + - https://w3c.github.io/aria/#button + - https://www.w3.org/WAI/ARIA/apg/patterns/button/examples/button/ +sidebar: accessibilitysidebar +--- + +The `button` role is for clickable elements that trigger a response when activated by the user. Adding `role="button"` tells the screen reader the element is a button, but provides no button functionality. Use {{HTMLElement("button")}} or {{HTMLElement("input")}} with `type="button"` instead. + +## Description + +The button role identifies an element as a button to assistive technology such as screen readers. A button is a widget used to perform actions such as submitting a form, opening a dialog, canceling an action, or performing a command such as inserting a new record or displaying information. Adding `role="button"` tells assistive technology that the element is a button but provides no button functionality. Use {{HTMLElement("button")}} or {{HTMLElement("input")}} with `type="button"` instead. + +This `button` role can be used in combination with the [`aria-pressed`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-pressed) attribute to [create toggle buttons](#toggle_buttons). + +```html +<div id="saveChanges" tabindex="0" role="button" aria-pressed="false">Save</div> +``` + +The above example creates a focusable button, but requires JavaScript and CSS to include button appearance and functionality. These are features provided by default when using the {{HTMLElement("button")}} and {{HTMLElement("input")}} with `type="button"` elements: + +```html +<button type="button" id="saveChanges">Save</button> +``` + +> [!NOTE] +> If using `role="button"` instead of the semantic `<button>` or `<input type="button">` elements, you will need to make the element focusable and define event handlers for {{domxref("Element/click_event", "click")}} and {{domxref("Element/keydown_event", "keydown")}} events. This includes handling the <kbd>Enter</kbd> and <kbd>Space</kbd> key presses in order to process all forms of user input. See [the official WAI-ARIA example code](https://www.w3.org/WAI/ARIA/apg/patterns/button/examples/button/). + +In addition to the ordinary button widget, `role="button"` should be included when creating a toggle button or menu button using a non-button element. + +A toggle button is a two-state button that can be either off (not pressed) or on (pressed). The [`aria-pressed`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-pressed) attribute values of `true` or `false` identify a button as a toggle button. + +A menu button is a button that controls a menu and has an [`aria-haspopup`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-haspopup) property attribute set to either `menu` or `true`. + +### All descendants are presentational + +There are some types of user interface components that, when represented in a platform accessibility API, can only contain text. Accessibility APIs do not have a way of representing semantic elements contained in a `button`. To deal with this limitation, browsers, automatically apply role [`presentation`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/presentation_role) to all descendant elements of any `button` element as it is a role that does not support semantic children. + +For example, consider the following `button` element, which contains a heading. + +```html +<div role="button"><h3>Title of my button</h3></div> +``` + +Because descendants of `button` are presentational, the following code is equivalent: + +```html +<div role="button"><h3 role="presentation">Title of my button</h3></div> +``` + +From the assistive technology user's perspective, the heading does not exist since the previous code snippets are equivalent to the following in the [accessibility tree](/en-US/docs/Glossary/Accessibility_tree): + +```html +<div role="button">Title of my button</div> +``` + +### Associated ARIA roles, states, and properties + +- [`aria-pressed`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-pressed) + - : The `aria-pressed` attribute defines the button as a toggle button. The value describes the state of the button. The values include `aria-pressed="false"` when a button is not currently pressed, `aria-pressed="true"` to indicate a button is currently pressed, and `aria-pressed="mixed"` if the button is considered to be partially pressed. If the attribute is omitted or set to its default value of `aria-pressed="undefined"`, the element does not support being pressed. +- [`aria-expanded`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-expanded) + - : If the button controls a grouping of other elements, the `aria-expanded` state indicates whether the controlled grouping is currently expanded or collapsed. If the button has `aria-expanded="false"` set, the grouping is not currently expanded; If the button has `aria-expanded="true"` set, it is currently expanded; if the button has `aria-expanded="undefined"` set or the attribute is omitted, it is not expandable. + +### Basic buttons + +Buttons should always have an accessible name. For most buttons, this name will be the same as the text inside the button, between the opening and closing tags. In some cases, for example buttons represented by icons, the accessible name may be provided from the [`aria-label`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-label) or [`aria-labelledby`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-labelledby) attributes. + +### Toggle buttons + +A toggle button typically has two states: pressed and not pressed. A third mixed state is available for toggle buttons that control other elements, such as other toggle buttons or checkboxes, which do not all share the same value. Whether an element is a toggle button or not can be indicated with the [`aria-pressed`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-pressed) attribute in addition to the `button` role (if the element is not already a native button element): + +- If `aria-pressed` is not used, or is set to the "undefined" state, the button is not a toggle button. +- If `aria-pressed="false"` is used the button is a toggle button that is currently not pressed. +- If `aria-pressed="true"` is used the button is a toggle button that is currently pressed. +- if `aria-pressed="mixed"` is used, the button is considered to be partially pressed. + +As an example, the mute button on an audio player labeled "mute" could indicate that sound is muted by setting the `aria-pressed` state true. The label of a toggle button should not change when its state changes. In our example the label remains "Mute" with a screen reader reading "Mute toggle button pressed" or "Mute toggle button not pressed" depending on the value of `aria-pressed`. If the design were to call for the button label to change from "Mute" to "Unmute," a toggle button would not be appropriate, so the `aria-pressed` attribute would be omitted. + +### Keyboard interactions + +| Key | Function | +| ---------------- | --------------------- | +| <kbd>Enter</kbd> | Activates the button. | +| <kbd>Space</kbd> | Activates the button | + +Following button activation, focus is set depending on the type of action the button performs. For example, if clicking the button opens a dialog, the focus should move to the dialog. If the button closes a dialog, focus should return to the button that opened the dialog unless the function performed in the dialog context logically leads to a different element. If the button alters the current context, such as muting and unmuting an audio file, then focus typically remains on the button. + +### Required JavaScript Features + +#### Required event handlers + +Buttons can be operated by mouse, touch, and keyboard users. For native HTML `<button>` elements, the button's `onclick` event fires for mouse clicks and when the user presses <kbd>Space</kbd> or <kbd>Enter</kbd> while the button has focus. But if another tag is used to create a button, the `onclick` event only fires when clicked by the mouse cursor, even if `role="button"` is used. Because of this, separate key event handlers must be added to the element so that the button is be triggered when the <kbd>Space</kbd> or <kbd>Enter</kbd> key is pressed. + +- `onclick` + - : Handles the event raised when the button is activated using a mouse click or touch event. +- `onKeyDown` + - : Handles the event raised when the button is activated using the Enter or Space key on the keyboard. (Note not the [deprecated onKeyPress](/en-US/docs/Web/API/Element/keypress_event)) + +## Examples + +### Basic button example + +In this example, a span element has been given the `button` role. Because a `<span>` element is used, the `tabindex` attribute is required to make the button focusable and part of the page's tab order. The included CSS style is provided to make the `<span>` element look like a button, and to provide visual cues when the button has focus. + +The `handleBtnClick` and `handleBtnKeyDown` event handlers perform the button's action when activated using a mouse click or the <kbd>Space</kbd> or <kbd>Enter</kbd> key. In this case, the action is to add a new name to the list of names. + +Try the example by adding a name to the text box. The button will cause the name to be added to a list. + +#### HTML + +```html +<h1>ARIA Button Example</h1> +<ul id="nameList"></ul> +<label for="newName">Enter your Name: </label> +<input type="text" id="newName" /> +<span role="button" tabindex="0">Add Name</span> +``` + +#### CSS + +```css +[role="button"] { + padding: 2px; + background-color: navy; + color: white; + cursor: default; +} +[role="button"]:hover, +[role="button"]:focus, +[role="button"]:active { + background-color: white; + color: navy; +} +ul { + list-style: none; +} +``` + +#### JavaScript + +```js +function handleCommand(event) { + // Handles both mouse clicks and keyboard + // activate with Enter or Space + + // Key presses other than Enter and Space should not trigger a command + if ( + event instanceof KeyboardEvent && + event.key !== "Enter" && + event.key !== " " + ) { + return; + } + + // Get the new name value from the input element + const newNameInput = document.getElementById("newName"); + const name = newNameInput.value; + newNameInput.value = ""; // clear the text field + newNameInput.focus(); // give the text field focus to enable entering and additional name. + + // Don't add blank entries to the list. + if (name.length > 0) { + const listItem = document.createElement("li"); + listItem.appendChild(document.createTextNode(name)); + + // Add the new name to the list. + const list = document.getElementById("nameList"); + list.appendChild(listItem); + } +} + +const btn = document.querySelector("span[role='button']"); +btn.addEventListener("click", handleCommand); +btn.addEventListener("keydown", handleCommand); +``` + +{{EmbedLiveSample("Basic_button_example")}} + +### Toggle button example + +In this snippet a {{HTMLElement("span")}} element is converted to a toggle button using the `button` role and the `aria-pressed` attribute. When the button is activated, the `aria-pressed` value switches states; changing from `true` to `false` and back again. + +#### HTML + +```html +<button type="button">Mute Audio</button> + +<span role="button" tabindex="0" aria-pressed="false"> Mute Audio </span> + +<audio + id="audio" + src="https://soundbible.com/mp3/Tyrannosaurus%20Rex%20Roar-SoundBible.com-807702404.mp3"> + Your browser does not support the `audio` element. +</audio> +``` + +#### CSS + +```css +button, +[role="button"] { + padding: 3px; + border: 2px solid transparent; +} + +button:active, +button:focus, +[role="button"][aria-pressed="true"] { + border: 2px solid #000; +} +``` + +#### JavaScript + +```js +function handleBtnClick(event) { + toggleButton(event.target); +} + +function handleBtnKeyDown(event) { + // Check to see if space or enter were pressed + // "Spacebar" for IE11 support + if (event.key === " " || event.key === "Enter" || event.key === "Spacebar") { + // Prevent the default action to stop scrolling when space is pressed + event.preventDefault(); + toggleButton(event.target); + } +} + +function toggleButton(element) { + const audio = document.getElementById("audio"); + + // Check to see if the button is pressed + const pressed = element.getAttribute("aria-pressed") === "true"; + + // Change aria-pressed to the opposite state + element.setAttribute("aria-pressed", !pressed); + + // Toggle the play state of the audio file + if (pressed) { + audio.pause(); + } else { + audio.play(); + } +} + +const button = document.querySelector("button"); +const spanButton = document.querySelector("span[role='button']"); +button.addEventListener("click", handleBtnClick); +button.addEventListener("keydown", handleBtnKeyDown); +spanButton.addEventListener("click", handleBtnClick); +spanButton.addEventListener("keydown", handleBtnKeyDown); +``` + +#### Result + +{{EmbedLiveSample('Toggle_button_example')}} + +## Accessibility concerns + +Buttons are interactive controls and thus focusable. If the `button` role is added to an element that is not focusable by itself (such as `<span>`, `<div>` or `<p>`) then, the `tabindex` attribute has to be used to make the button focusable. + +> [!WARNING] +> Be careful when marking up links with the button role. Buttons are expected to be triggered using the <kbd>Space</kbd> or <kbd>Enter</kbd> key, while links are expected to be triggered using the <kbd>Enter</kbd> key. In other words, when links are used to behave like buttons, adding `role="button"` alone is not sufficient. It will also be necessary to add a key event handler that listens for the <kbd>Space</kbd> key in order to be consistent with native buttons. + +When the `button` role is used, screen readers announce the element as a button, generally saying "click" followed by the button's accessible name. The accessible name is either the content of the element or the value of an `aria-label` or element referenced by an `aria-labelledby` attribute, or description, if included. + +## Best practices + +If a link performs the action of a button, giving the element `role="button"` helps assistive technology users understand the function of the element. However, a better solution is to adjust the visual design so it matches the function and ARIA role. Where possible, it is recommended to use native HTML buttons (`<button>`, `<input type="button">`, `<input type="submit">`, `<input type="reset">` and `<input type="image">`) rather than the `button` role, as native HTML buttons are supported by all user agents and assistive technology and provide keyboard and focus requirements by default, without need for additional customization. + +## Specifications + +{{Specifications}} + +## See also + +- The {{HTMLElement('button')}} element +- The {{HTMLElement("input")}} element +- [`<input type="button">`](/en-US/docs/Web/HTML/Reference/Elements/input/button) +- [`<input type="submit">`](/en-US/docs/Web/HTML/Reference/Elements/input/submit) +- [`<input type="reset">`](/en-US/docs/Web/HTML/Reference/Elements/input/reset) +- [`aria-pressed`](https://www.w3.org/TR/wai-aria-1.1/#aria-pressed) +- [`aria-expanded`](https://www.w3.org/TR/wai-aria-1.1/#aria-expanded) +- [`aria-haspopup`](https://www.w3.org/TR/wai-aria-1.1/#aria-haspopup) +- [Strong native semantics in HTML5](https://html.spec.whatwg.org/multipage/dom.html#aria-usage-note) +- [Notes on Using ARIA in HTML](https://www.w3.org/TR/aria-in-html/) +- [Official WAI-ARIA example code](https://www.w3.org/WAI/ARIA/apg/patterns/button/examples/button/) diff --git a/files/en-us/web/accessibility/aria/reference/roles/cell_role/index.md b/files/en-us/web/accessibility/aria/reference/roles/cell_role/index.md new file mode 100644 index 000000000000000..48706aa202443b5 --- /dev/null +++ b/files/en-us/web/accessibility/aria/reference/roles/cell_role/index.md @@ -0,0 +1,187 @@ +--- +title: "ARIA: cell role" +short-title: cell +slug: Web/Accessibility/ARIA/Reference/Roles/cell_role +page-type: aria-role +spec-urls: + - https://w3c.github.io/aria/#cell + - https://www.w3.org/WAI/ARIA/apg/patterns/table/examples/table/ +sidebar: accessibilitysidebar +--- + +The `cell` value of the ARIA _role_ attribute identifies an element as being a cell in a tabular container that does not contain column or row header information. To be supported, the cell must be nested in an element with the role of `row`. + +```html +<div role="row"> + <span role="cell">France</span> + <span role="cell">67 million</span> +</div> +``` + +A better, more semantic way of writing the cells above would be to use the semantic [`<td>`](/en-US/docs/Web/HTML/Reference/Elements/td) element. + +```html +<tr role="row"> + <td role="cell">France</td> + <td role="cell">67 million</td> +</tr> +``` + +## Description + +The element with `role="cell"` is a cell within a row, optionally within a [`rowgroup`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/rowgroup_role), within a [`table`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/table_role). If the cell is in a [`grid`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/grid_role) or [`treegrid`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/treegrid_role), opt for [`gridcell`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/gridcell_role). Using native HTML {{HTMLElement('td')}} elements, whenever possible, is strongly encouraged. + +Each element with `role="cell"` MUST be nested in a container element with [`role="row"`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/row_role). That row, in turn, can be nested within an element with [`role="rowgroup"`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/rowgroup_role), and should be nested within a `grid`, `table` or `treegrid`. If a cell contains column or row header information, use the `columnheader` or `rowheader` roles, respectively. If the cell does not contain header information and is nested in a `grid` or `treegrid`, the role of `gridcell` may be more appropriate. + +A cell can contain a number of property attributes clarifying the cell's position within the tabular data structure, including [`aria-colindex`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-colindex), [`aria-colspan`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-colspan), [`aria-rowindex`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-rowindex), and [`aria-rowspan`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-rowspan). + +> [!NOTE] +> Using the native HTML table element ({{HTMLElement('table')}}) element, along with the table row element ({{HTMLElement('tr')}}), and table cell element ({{HTMLElement('td')}}), whenever possible, is strongly encouraged. + +### Associated WAI-ARIA roles, states, and properties + +#### Context roles + +- [role="row"](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/row_role) + - : An element with `role="row"` is a row of cells within a tabular structure. A row contains one or more cells, grid cells, column headers, or row headers within a [`grid`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/grid_role), [`table`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/table_role) or `treegrid`, and optionally within a [`rowgroup`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/rowgroup_role). +- [role="rowgroup"](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/rowgroup_role) + - : `Row` is a required cell parent. `Rowgroup` is an optional contextual row parent. It establishes a relationship between descendant rows. It is a structural equivalent to the [`thead`](/en-US/docs/Web/HTML/Reference/Elements/thead), [`tfoot`](/en-US/docs/Web/HTML/Reference/Elements/tfoot), and [`tbody`](/en-US/docs/Web/HTML/Reference/Elements/tbody) elements in an [HTML `table`](/en-US/docs/Learn_web_development/Core/Structuring_content/HTML_table_basics) element. +- [role="table"](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/table_role) + - : One of the three possible contexts (along with `grid` and `treegrid`) in which you'll find a row containing cells. Table identifies the cell as being part of a non-interactive table structure containing data arranged in rows and columns, similar to the native HTML [`<table>`](/en-US/docs/Web/HTML/Reference/Elements/table) element. +- [role="grid"](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/grid_role) + - : One of the three possible contexts (along with `table` and `treegrid`) in which you'll find a row containing `cells` and `gridcells`. `Grid` identifies a cell as being part of a possibly interactive table structure containing data arranged in rows and columns, similar to the native [`<table>`](/en-US/docs/Web/HTML/Reference/Elements/table) HTML element. +- [role="treegrid"](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/treegrid_role) + - : Similar to a grid, but with rows that can be expanded and collapsed in the same manner as for a tree. + +#### Subclass roles + +- [role="gridcell"](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/gridcell_role) + - : A cell in a row within a `grid` or `treegrid`. +- [role="columnheader"](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/columnheader_role) + - : A header cell that is the structural equivalent of the HTML [`<th>`](/en-US/docs/Web/HTML/Reference/Elements/th) element with a column scope. Unlike a plain cell, the `columnheader` role establishes a relationship between it and all cells in the corresponding column. +- [role="rowheader"](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/rowheader_role) + - : A header cell that is the structural equivalent of the HTML [`<th>`](/en-US/docs/Web/HTML/Reference/Elements/th) element with a row scope. Unlike a plain cell, the `rowheader` role establishes a relationship between it and all cells in the corresponding row. + +#### States and properties + +- [`aria-colspan`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-colspan) + - : Similar to the HTML [`<th>`](/en-US/docs/Web/HTML/Reference/Elements/th) and [`<td>` colspan attribute](/en-US/docs/Web/HTML/Reference/Elements/td), it defines the number of columns spanned by the cell. +- [`aria-rowspan`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-rowspan) + - : Similar to the HTML [`<th>`](/en-US/docs/Web/HTML/Reference/Elements/th) and [`<td>` rowspan attribute](/en-US/docs/Web/HTML/Reference/Elements/td), it defines the number of rows spanned by the cell. +- [`aria-colindex`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-colindex) attribute + - : The `aria-colindex` attribute is only needed if columns are hidden from the DOM. The attribute takes as its value an integer between 1 and the total number of columns within the `table`, `grid` or `treegrid`. The `aria-colindex` defines an element's column index or position with respect to the total number of columns within a row. If all the columns are in the DOM, this attribute is not necessary. +- [`aria-rowindex`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-rowindex) attribute + - : The `aria-rowindex` attribute is only needed if rows are hidden from the DOM, to indicate which row, in the list of total rows, the current cell is in. The attribute, takes as its value an integer between 1 and the total number of rows within the table, grid, or treegrid, indicating the position, or index, of the cell. For example, a cell in the first row of the first header would likely have `aria-rowindex="1"` set, and cells in row 47 would have `aria-rowindex="47"`, if `aria-rowindex` were needed due to not all rows being in the DOM. If the rows that are visible are contiguous, and there are no cells with a `colspan` or `rowspan` greater than one, this property can be added to the parent rows instead of all the rows' cells. + +### Keyboard interactions + +None. + +### Required JavaScript features + +The first rule of ARIA use is if you can use a native feature with the semantics and behavior you require already built in, instead of repurposing an element and **adding** an ARIA role, state or property to make it accessible, then do so. Employ the HTML [`<td>`](/en-US/docs/Web/HTML/Reference/Elements/td) element instead of the ARIA role of `cell` whenever possible. + +## Examples + +```html +<div + role="table" + aria-label="Semantic Elements" + aria-describedby="semantic_elements_table_desc" + aria-rowcount="81"> + <div id="semantic_elements_table_desc"> + Semantic Elements to use instead of ARIA's roles + </div> + <div role="rowgroup"> + <div role="row"> + <span role="columnheader" aria-sort="none" aria-rowindex="1" + >ARIA Role</span + > + <span role="columnheader" aria-sort="none" aria-rowindex="1" + >Semantic Element</span + > + </div> + </div> + <div role="rowgroup"> + <div role="row"> + <span role="cell" aria-rowindex="11">header</span> + <span role="cell" aria-rowindex="11">h1</span> + </div> + <div role="row"> + <span role="cell" aria-rowindex="16">header</span> + <span role="cell" aria-rowindex="16">h6</span> + </div> + <div role="row"> + <span role="cell" aria-rowindex="18">rowgroup</span> + <span role="cell" aria-rowindex="18">thead</span> + </div> + <div role="row"> + <span role="cell" aria-rowindex="24">term</span> + <span role="cell" aria-rowindex="24">dt</span> + </div> + </div> +</div> +``` + +The above is a non-semantic ARIA table with five of 81 rows present in the DOM: one within a table header and four rows within the table body. Because not all the rows are in the DOM, we've included the `aria-rowindex` property on every cell. If no cells spanned more than one row or column, the `aria-rowindex` could have been placed on the row rather than the row's individual cells. + +## Best practices + +Only use {{HTMLElement('table')}}, {{HTMLElement('tbody')}}, {{HTMLElement('thead')}}, {{HTMLElement('tr')}}, {{HTMLElement('th')}}, {{HTMLElement('td')}}, etc., for data table structure. You can add ARIA roles to ensure accessibility should the native semantics of the table be removed, such as with CSS. A relevant use case for the ARIA table role is when the native semantics of a table are overridden by [CSS's display property, such as by display: grid](/en-US/docs/Web/CSS/display#accessibility). In this case, you can use the ARIA table roles to add the semantics back in. + +```html +<table + role="table" + aria-label="Semantic Elements" + aria-describedby="semantic_elements_table_desc" + aria-rowcount="81"> + <caption id="semantic_elements_table_desc"> + Semantic Elements to use instead of ARIA's roles + </caption> + <thead role="rowgroup"> + <tr role="row"> + <th role="columnheader" aria-sort="none" aria-rowindex="1">ARIA Role</th> + <th role="columnheader" aria-sort="none" aria-rowindex="1"> + Semantic Element + </th> + </tr> + </thead> + <tbody role="rowgroup"> + <tr role="row"> + <td role="cell" aria-rowindex="11">header</td> + <td role="cell" aria-rowindex="11">h1</td> + </tr> + <tr role="row"> + <td role="cell" aria-rowindex="16">header</td> + <td role="cell" aria-rowindex="16">h6</td> + </tr> + <tr role="row"> + <td role="cell" aria-rowindex="18">rowgroup</td> + <td role="cell" aria-rowindex="18">thead</td> + </tr> + <tr role="row"> + <td role="cell" aria-rowindex="24">term</td> + <td role="cell" aria-rowindex="24">dt</td> + </tr> + </tbody> +</table> +``` + +Above is the semantic way of writing a table. The ARIA roles are not necessary if the native semantics of the table, and therefore the table rows, have not been altered, such as through [the display property](/en-US/docs/Web/CSS/display#accessibility). + +### Added benefits + +When applied to a {{HTMLElement('td')}}, it returns cell semantics to the element in case the semantics were removed, such as with `display: grid;`. + +## Specifications + +{{Specifications}} + +## See also + +- [`role="row"`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/row_role) +- [`role="gridcell"`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/gridcell_role) +- [HTML `<td>` element](/en-US/docs/Web/HTML/Reference/Elements/td) +- [HTML `<th>` element](/en-US/docs/Web/HTML/Reference/Elements/th) +- [Learn: HTML table accessibility](/en-US/docs/Learn_web_development/Core/Structuring_content/Table_accessibility) +- [Learn: HTML table basics](/en-US/docs/Learn_web_development/Core/Structuring_content/HTML_table_basics) diff --git a/files/en-us/web/accessibility/aria/reference/roles/checkbox_role/index.md b/files/en-us/web/accessibility/aria/reference/roles/checkbox_role/index.md new file mode 100644 index 000000000000000..f5d79ee97bef0ca --- /dev/null +++ b/files/en-us/web/accessibility/aria/reference/roles/checkbox_role/index.md @@ -0,0 +1,191 @@ +--- +title: "ARIA: checkbox role" +short-title: checkbox +slug: Web/Accessibility/ARIA/Reference/Roles/checkbox_role +page-type: aria-role +sidebar: accessibilitysidebar +--- + +The `checkbox` role is for checkable interactive controls. Elements containing `role="checkbox"` must also include the [`aria-checked`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-checked) attribute to expose the checkbox's state to assistive technology. + +```html +<span + role="checkbox" + aria-checked="false" + tabindex="0" + aria-labelledby="chk1-label"></span> +<label id="chk1-label">Remember my preferences</label> +``` + +> [!NOTE] +> The first rule of ARIA is if a native HTML element or attribute has the semantics and behavior you require, use it instead of re-purposing an element and adding ARIA. Instead use the native [HTML checkbox of `<input type="checkbox">`](/en-US/docs/Web/HTML/Reference/Elements/input/checkbox) (with an associated {{HTMLElement('label')}}), which natively provides all the functionality required: + +```html +<input type="checkbox" id="chk1-label" name="RememberPreferences" /> +<label for="chk1-label">Remember my preferences</label> +``` + +## Description + +The native HTML checkbox ([`<input type="checkbox">`](/en-US/docs/Web/HTML/Reference/Elements/input/checkbox)) form control had two states ("checked" or "not checked"), with an [`indeterminate`](/en-US/docs/Web/HTML/Reference/Elements/input/checkbox#indeterminate_state_checkboxes) state settable via JavaScript. Similarly, an element with `role="checkbox"` can expose three states through the `aria-checked` attribute: `true`, `false`, or `mixed`. + +Since a checkbox is an interactive control, it must be focusable and keyboard accessible. If the role is applied to a non-focusable element, use the [`tabindex`](/en-US/docs/Web/HTML/Reference/Global_attributes/tabindex) attribute to change this. The expected keyboard shortcut for activating a checkbox is the <kbd>Space</kbd> key. + +The developer is required to change the value of the `aria-checked` attribute dynamically when the checkbox is activated. + +### All descendants are presentational + +There are some types of user interface components that, when represented in a platform accessibility API, can only contain text. Accessibility APIs do not have a way of representing semantic elements contained in a `checkbox`. To deal with this limitation, browsers, automatically apply role [`presentation`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/presentation_role) to all descendant elements of any `checkbox` element as it is a role that does not support semantic children. + +For example, consider the following `checkbox` element, which contains a heading. + +```html +<div role="checkbox"><h6>Name of my checkbox</h6></div> +``` + +Because descendants of `checkbox` are presentational, the following code is equivalent: + +```html +<div role="checkbox"><h6 role="presentation">Name of my checkbox</h6></div> +``` + +From the assistive technology user's perspective, the heading does not exist since the previous code snippets are equivalent to the following in the [accessibility tree](/en-US/docs/Glossary/Accessibility_tree): + +```html +<div role="checkbox">Name of my checkbox</div> +``` + +### Associated WAI-ARIA roles, states, and properties + +- [`aria-checked`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-checked) + + - : The value of `aria-checked` defines the state of a checkbox. This attribute has one of three possible values: + + - `true` + - : The checkbox is checked. + - `false` + - : The checkbox is not checked. + - `mixed` + - : The checkbox is partially checked, or indeterminate. + +- `tabindex="0"` + - : Used to make it focusable so the assistive technology user can tab to it and start reading right away. + +### Keyboard interactions + +| Key | Function | +| ---------------- | ---------------------- | +| <kbd>Space</kbd> | Activates the checkbox | + +### Required JavaScript + +#### Required event handlers + +- `onclick` + - : Handle mouse clicks on both the checkbox and the associated label that will change the state of the checkbox by changing the value of the `aria-checked` attribute and the appearance of the checkbox so it appears checked or unchecked to the sighted user +- `onKeyDown` + + - : Handle the case where the user presses the <kbd>Space</kbd> key to change the state of the checkbox by changing the value of the `aria-checked` attribute and the appearance of the checkbox so it appears checked or unchecked to the sighted user + +## Examples + +The following example creates an otherwise non-semantic checkbox element using CSS and JavaScript to handle the checked or unchecked status of the element. + +### HTML + +```html +<span + role="checkbox" + id="chkPref" + aria-checked="false" + tabindex="0" + aria-labelledby="chk1-label"></span> +<label id="chk1-label">Remember my preferences</label> +``` + +### CSS + +```css +[role="checkbox"] { + padding: 5px; +} + +[role="checkbox"]:focus { + border: 2px solid #0198e1; +} + +[aria-checked="true"]::before { + content: "[x]"; +} + +[aria-checked="false"]::before { + content: "[ ]"; +} +``` + +### JavaScript + +```js +const item = document.getElementById("chkPref"); +const label = document.getElementById("chk1-label"); + +function changeCheckbox(code) { + const checked = item.getAttribute("aria-checked"); + + if (code && code !== "Space") { + return; + } + if (checked === "true") { + item.setAttribute("aria-checked", "false"); + } else { + item.setAttribute("aria-checked", "true"); + } +} + +item.addEventListener("keydown", (event) => { + changeCheckbox(event.code); +}); + +label.addEventListener("keydown", (event) => { + changeCheckbox(event.code); +}); + +item.addEventListener("click", changeCheckbox); +label.addEventListener("click", changeCheckbox); +``` + +{{EmbedLiveSample("Examples", 230, 250)}} + +## Accessibility concerns + +When the `checkbox` role is added to an element, the user agent should do the following: + +- Expose the element as having a `checkbox` role in the operating system's accessibility API. +- When the `aria-checked` value changes, send an accessible state changed event. + +Assistive technology products should do the following: + +- Screen readers should announce the element as a checkbox, and optionally provide instructions on how to activate it. + +People implementing checkboxes should do the following: + +- Ensure that the checkbox can be reached and interacted with by both keyboard controls and clicks +- Keep the `aria-checked` attribute up to date following user interactions +- Provide styles that indicate when the checkbox has focus + +> [!NOTE] +> Opinions may differ on how assistive technology should handle this technique. The information provided above is one of those opinions and may change. + +## Best practices + +The first rule of ARIA is: if a native HTML element or attribute has the semantics and behavior you require, use it instead of re-purposing an element and adding an ARIA role, state or property to make it accessible. As such, it is recommended to use the native [HTML checkbox](/en-US/docs/Web/HTML/Reference/Elements/input/checkbox) using form control instead of recreating a checkbox's functionality with JavaScript and ARIA. + +## See also + +- [`<input type="checkbox">`](/en-US/docs/Web/HTML/Reference/Elements/input/checkbox) +- [ARIA: `radio` role](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/radio_role) +- [ARIA: `menuitem` role](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/menuitem_role) +- [ARIA: `menuitemcheckbox` role](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/menuitemcheckbox_role) +- [ARIA: `menuitemradio` role](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/menuitemradio_role) +- [ARIA: `switch` role](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/switch_role) +- [ARIA: `option` role](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/option_role) diff --git a/files/en-us/web/accessibility/aria/reference/roles/columnheader_role/index.md b/files/en-us/web/accessibility/aria/reference/roles/columnheader_role/index.md new file mode 100644 index 000000000000000..2d43800a5c2917c --- /dev/null +++ b/files/en-us/web/accessibility/aria/reference/roles/columnheader_role/index.md @@ -0,0 +1,85 @@ +--- +title: "ARIA: columnheader role" +short-title: columnheader +slug: Web/Accessibility/ARIA/Reference/Roles/columnheader_role +page-type: aria-role +spec-urls: + - https://w3c.github.io/aria/#columnheader + - https://www.w3.org/WAI/ARIA/apg/patterns/table/examples/table/ +sidebar: accessibilitysidebar +--- + +The `columnheader` value of the ARIA role attribute identifies an element as being a cell in a row contains header information for a column, similar to the native {{HTMLElement('th')}} element with column scope. + +## Description + +An element with `role="columnheader"` nested as a descendant for an element with `role="row"`, is a static tabular structure of a column header cell in a tabular container, either a table or grid, or other chart that needs to show data relationships. To be supported, the columnheader must be nested in an element with the [role of `row`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/row_role). + +### Associated WAI-ARIA roles, states, and properties + +All column headers should be nested within a [row](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/row_role). Every row, in turn, should be nested within a [grid](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/grid_role), [table](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/table_role), or [treegrid](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/row_role), alternatively within a [rowgroup](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/rowgroup_role) nested within one of the above. + +- [`aria-sort`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-sort) + - : Only applied to one column header at a time, if any, the `aria-sort` attribute indicates if a column is sorted in the three values of `ascending` or `descending` order, or `none` for not sorted. + +### Keyboard interactions + +This role does not support any specific keyboard interaction. + +### Required JavaScript features + +JavaScript is only required if the `aria-sort` attribute is used. + +## Examples + +```html +<table> + <thead> + <tr role="row"> + <th role="columnheader" scope="col"> + <button>First Name</button> + </th> + <th role="columnheader" scope="col"> + <button>Last Name</button> + </th> + <th role="columnheader" scope="col" aria-sort="ascending"> + <button>Company Name</button> + </th> + <th role="columnheader" scope="col"> + <button>Job Title</button> + </th> + </tr> + </thead> + <tbody> + … + </tbody> +</table> +``` + +## Best practices + +Column headers should contain a title or header information for the column. + +The first rule of ARIA is: if a native HTML element or attribute has the semantics and behavior you require, use it instead of re-purposing an element and adding an ARIA role, state or property to make it accessible. It is recommended to use the native HTML `<th>` element with the `scope` attribute set `<th scope="col">` instead of a `<div>` or other element. If you use semantic HTML's `<th scope="col">` the role attribute is not required, but can be included as a back up to ensure the table retains its semantics should the default semantics be removed with a CSS display property value. + +The `aria-sort` attribute can be added to a `<th scope="col">` even when the ARIA role attribute is not specified. + +### Prefer HTML + +Columnheader has the same semantics `<th scope="col">`. + +## Specifications + +{{Specifications}} + +## See also + +- [`table` role](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/table_role) +- [`grid` role](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/grid_role) +- [`treegrid` role](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/row_role) +- [`row` role](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/row_role) +- [`rowgroup` role](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/rowgroup_role) +- [The `<th>` element](/en-US/docs/Web/HTML/Reference/Elements/th) +- [The `<table>` element](/en-US/docs/Web/HTML/Reference/Elements/table) +- [The `<tr>` element](/en-US/docs/Web/HTML/Reference/Elements/tr) +- [The `<td>` element](/en-US/docs/Web/HTML/Reference/Elements/td) diff --git a/files/en-us/web/accessibility/aria/reference/roles/combobox_role/index.md b/files/en-us/web/accessibility/aria/reference/roles/combobox_role/index.md new file mode 100644 index 000000000000000..fbde377af5d3fbe --- /dev/null +++ b/files/en-us/web/accessibility/aria/reference/roles/combobox_role/index.md @@ -0,0 +1,115 @@ +--- +title: "ARIA: combobox role" +short-title: combobox +slug: Web/Accessibility/ARIA/Reference/Roles/combobox_role +page-type: aria-role +spec-urls: + - https://w3c.github.io/aria/#combobox, + - https://www.w3.org/WAI/ARIA/apg/patterns/combobox/examples/combobox-select-only/ +sidebar: accessibilitysidebar +--- + +The `combobox` role identifies an element as an `input` that controls another element, such as a `listbox` or `grid`, that can dynamically pop up to help the user set the value of that `input`. + +## Description + +A `combobox` is a composite widget that combines a named input field with a popup providing possible values for that input field. The purpose of this widget is to improve user experience by helping the user select a value without having to type in the complete value and, optionally depending whether supported values are limited, preventing the user from entering invalid or otherwise unsupported values. + +The `combobox` role is set on input that controls another element, such as a listbox or grid, that can dynamically pop up to help the user set the value of the input. + +The `combobox` input field can either be a single-line text field that supports editing and typing, similar to a HTML {{HTMLElement('input')}} with a {{HTMLElement('datalist')}}, or an element that only displays the current value of the combobox. + +A WAI-ARIA combobox only has one attribute that is required that authors specify: [`aria-expanded`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-expanded). However, it also has several other attributes which will be necessary to specify, depending on the combobox's implementation. These include [`aria-haspopup`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-haspopup), [`aria-controls`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-controls), [`aria-activedescendant`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-activedescendant), and [`aria-autocomplete`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-autocomplete). + +Typically, the initial state of a combobox is collapsed, with `aria-expanded="false"` set. In the collapsed state, only the combobox element and, optionally a sibling button to invoke the popup, are visible. The [`aria-expanded`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-expanded), with the value set to `false`, is required when collapsed, because it indicates to assistive technologies that the widget is expandable. + +The combobox is in the expanded state when both the combobox element showing its current value and its associated popup element are visible. When expanded, `aria-expanded="true"` must be set. + +The popup element associated with a `combobox` can be either a [`listbox`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/listbox_role), [`tree`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/tree_role), [`grid`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/grid_role), or [`dialog`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/dialog_role) element. + +Comboboxes have an implicit [`aria-haspopup`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-haspopup) value of `listbox`, so including this attribute is optional if the popup is a `listbox`. If the combobox popup element is a `tree`, `grid`, or `dialog` (anything other than a `listbox`), the `aria-haspopup` attribute is required. The value of `aria-haspopup` must be either the `tree`, `grid`, `dialog`, or `listbox` role. Note that for this property, `true` means `menu`, so make sure that the value corresponds to the role of the popup, not a Boolean value. + +When a combobox's popup is displayed, ensure the [`aria-controls`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-controls) attribute on the combobox element is set to the [`id`](/en-US/docs/Web/HTML/Reference/Global_attributes/id) of the popup `listbox`, `tree`, `grid`, or `dialog` element. This is how the relationship between the element with the `combobox` role and the popup it controls is indicated. (Note: In older ARIA specs, this was `aria-owns` rather than `aria-controls`, so you may see `aria-owns` in older combobox implementations. The `aria-owns` in the code should be updated to `aria-controls`!) + +If the combobox UI includes a visible control, such as an icon, that allows the visibility of the popup to be controlled via pointer and touch events, that control should be a {{HTMLElement('button')}}, {{HTMLElement('input')}} of type `button`, or a [`button`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/button_role) role element with a [`tabindex`](/en-US/docs/Web/HTML/Reference/Global_attributes/tabindex) of `-1`. Doing so will allow the button to be focusable but not included in keyboard tab sequence. It must not be a descendant of the element with role `combobox`. + +To be keyboard accessible, keyboard support for moving focus between the `combobox` input field element and elements contained in the popup `listbox`, `tree`, `grid`, or `dialog`, must be programmed in. One common convention is that <kbd>Down Arrow</kbd> moves focus from the input to the first focusable descendant of the popup element. + +The [`aria-activedescendant`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-activedescendant) property can be used to identify the currently active element of the combobox popup, for instance an `option` within a popup `listbox`, for implementations where DOM focus remains on the combobox. If DOM focus does not remain on the combobox when its popup is invoked, but rather DOM focus moves into the popup, such as a dialog, then `aria-activedescendant` may not be necessary. + +If the combobox element is an {{HTMLElement('input')}} element, the value of the combobox is the input's value. Otherwise, the value of the combobox comes from its descendant elements. + +If the `combobox` supports text input and provides autocompletion behavior, set [`aria-autocomplete`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-autocomplete) on the combobox element to the value that corresponds to the provided behavior: `inline`, `list`, or `both`. The `aria-autocomplete` attribute indicates that inputting text will trigger display of one or more predictions of the user's intended value for the combobox and specifies how the predictions will be presented when made. + +Every `combobox` must have an accessible name. If using an {{HTMLElement('input')}} element, the accessible name should come from the associated {{HTMLElement('label')}}. If not, if an appropriate label is visible in the content, provide the name via [`aria-labelledby`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-labelledby). In other words, if there is an element in the user interface that serves as a label for the `combobox` input field, include `aria-labelledby` as an attribute on the element with the role of `combobox`, and set the value of the attribute to the `id` of the labelling element or elements. If no visible label is present, use [`aria-label`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-label) instead. Not both. + +### Associated WAI-ARIA roles, states, and properties + +- [`aria-expanded`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-expanded) + - : Required. Identifies whether the combobox is open (`true`) or closed (`false`). +- [`aria-haspopup`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-haspopup) + - : Implied. If omitted, defaults to `listbox`. Also supports `tree`, `grid`, or `dialog`. Identifies the combobox has having a popout, and indicates the type. + +### Keyboard interactions + +- <kbd>Down Arrow</kbd> + + - : Moves focus to the next option, or to the first option if none was selected. + +- <kbd>Alt</kbd> + <kbd>Down Arrow</kbd> (Optional) + + - : If the popup is available but not displayed, displays the popup without moving focus. + +- <kbd>Up Arrow</kbd> + + - : Moves focus to the previous option. Moving focus to the first option if focus was originally on the last option. + +- <kbd>Alt</kbd> + <kbd>Up Arrow</kbd> (Optional) + + - : If the popup has focus, returns focus to the combobox, otherwise it closes the popup. + +- <kbd>Enter</kbd> + - : If the combobox is editable and an autocomplete suggestion is selected in the popup, accepts the suggestion either by placing the input cursor at the end of the accepted value in the combobox or by performing a default action on the value. For example, in a messaging application, the default action may be to add the accepted value to a list of message recipients and then clear the combobox so the user can add another recipient. + +## Examples + +```html +<label for="jokes">Pick what type of jokes you like</label> +<div class="combo-wrap"> + <input + type="text" + id="jokes" + role="combobox" + aria-controls="joketypes" + aria-autocomplete="list" + aria-expanded="false" + data-active-option="item1" + aria-activedescendant="" /> + <span aria-hidden="true" data-trigger="multiselect"></span> + <ul id="joketypes" role="listbox" aria-label="Jokes"> + <li class="active" role="option" id="item1">Puns</li> + <li class="option" role="option" id="item2">Riddles</li> + <li class="option" role="option" id="item3">Observations</li> + <li class="option" role="option" id="item4">Knock-knock</li> + <li class="option" role="option" id="item5">One liners</li> + </ul> +</div> +``` + +## Specifications + +{{Specifications}} + +## See also + +- HTML {{HTMLElement('label')}} element +- HTML {{HTMLElement('select')}} element +- HTML {{HTMLElement('option')}} element +- HTML {{HTMLElement('input')}} element +- [ARIA: `listbox` role](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/listbox_role) +- [ARIA: `option` role](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/option_role) +- [ARIA: `list` role](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/list_role) +- [ARIA: `listitem` role](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/listitem_role) +- [ARIA Best Practices – Combobox](https://www.w3.org/WAI/ARIA/apg/patterns/combobox/) +- [ARIA Role Model – Combobox](https://www.w3.org/TR/wai-aria-1.2/#combobox) +- [Accessible combobox module](https://dequelabs.github.io/combobo/demo/) examples by Deque diff --git a/files/en-us/web/accessibility/aria/reference/roles/command_role/index.md b/files/en-us/web/accessibility/aria/reference/roles/command_role/index.md new file mode 100644 index 000000000000000..55da02320c96689 --- /dev/null +++ b/files/en-us/web/accessibility/aria/reference/roles/command_role/index.md @@ -0,0 +1,32 @@ +--- +title: "ARIA: command role" +short-title: command +slug: Web/Accessibility/ARIA/Reference/Roles/command_role +page-type: aria-role +spec-urls: https://w3c.github.io/aria/#command +sidebar: accessibilitysidebar +--- + +The `command` role defines a widget that performs an action but does not receive input data. + +> [!NOTE] +> The `command` role is an abstract role. It is included here for completeness of documentation. It should not be used by web authors. + +## Description + +A command is form of widget that performs an action but does not receive input data. It is a superclass for the widget roles [`button`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/button_role), [`link`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/link_role), and [`menuitem`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/menuitem_role) + +## Best Practices + +Do not use. + +## Specifications + +{{Specifications}} + +## See also + +- [ARIA: `widget` role](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/widget_role) +- [ARIA: `button` role](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/button_role) +- [ARIA: `link` role](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/link_role) +- [ARIA: `menuitem` role](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/menuitem_role) diff --git a/files/en-us/web/accessibility/aria/reference/roles/comment_role/index.md b/files/en-us/web/accessibility/aria/reference/roles/comment_role/index.md new file mode 100644 index 000000000000000..8b8c7d172b4698c --- /dev/null +++ b/files/en-us/web/accessibility/aria/reference/roles/comment_role/index.md @@ -0,0 +1,89 @@ +--- +title: "ARIA: comment role" +short-title: comment +slug: Web/Accessibility/ARIA/Reference/Roles/comment_role +page-type: aria-role +sidebar: accessibilitysidebar +--- + +The `comment` role semantically denotes a comment/reaction to some content on the page, or to a previous comment. + +> [!NOTE] +> The comment role is proposed in WAI-ARIA 1.3 ([Most recent ARIA draft](https://w3c.github.io/aria/)), which is still being drafted. + +## Examples + +In the following example we have a document section that has been commented. The commented section is marked up using `<span role="mark">`. + +The related comment is marked up using an HTML structure wrapped with a `<div>` containing `role="comment"`. + +```html +<p> + The last half of the song is a slow-rising crescendo that peaks at the + <span role="mark" aria-details="thread-1">end of the guitar solo</span>, + before fading away sharply. +</p> + +<div role="comment" id="thread-1" data-author="chris"> + <h3>Chris said</h3> + <p class="comment-text">I really think this moment could use more cowbell.</p> + <p><time datetime="2019-03-30T19:29">March 30 2019, 19:29</time></p> +</div> +``` + +To associate the comment with the text being commented, we need to wrap the commented text with an element containing the [`aria-details`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-details) attribute, the value of which should be the ID of the comment. + +### Multiple comments + +Since `aria-details` can now accept multiple IDs, we can associate multiple comments with the same annotation, like so: + +```html +<p> + The last half of the song is a slow-rising crescendo that peaks at the + <mark aria-details="thread-1 thread-2">end of the guitar solo</mark>, before + fading away sharply. +</p> + +<div role="comment" id="thread-1" data-author="chris"> + <h3>Chris said</h3> + <p class="comment-text">I really think this moment could use more cowbell.</p> + <p><time datetime="2019-03-30T19:29">March 30 2019, 19:29</time></p> +</div> + +<div role="comment" id="thread-2" data-author="chris"> + <h3>Marcus said</h3> + <p class="comment-text"> + The guitar solo could do with a touch more chorus, and a slightly lower + volume. + </p> + <p><time datetime="2019-03-29T15:35">March 29 2019, 15:35</time></p> +</div> +``` + +### Nested comments + +It's possible to nest comments inside one another, like so: + +```html +<div role="comment" id="thread-1" data-author="chris"> + <h3>Chris said</h3> + <p class="comment-text">I really think this moment could use more cowbell.</p> + <p><time datetime="2021-03-30T19:29">March 30 2021, 19:29</time></p> + + <div role="comment" data-author="marcus"> + <h3>Marcus replied</h3> + <p class="comment-text"> + I don't know about that. I think the cowbell could distract from the solo. + </p> + <p><time datetime="2021-03-30T21:02">March 30 2021, 21:02</time></p> + </div> +</div> +``` + +## Accessibility concerns + +None. + +## Specifications + +Will be part of WAI-ARIA 1.3, which is still being drafted. diff --git a/files/en-us/web/accessibility/aria/reference/roles/complementary_role/index.md b/files/en-us/web/accessibility/aria/reference/roles/complementary_role/index.md new file mode 100644 index 000000000000000..81f745969856fdb --- /dev/null +++ b/files/en-us/web/accessibility/aria/reference/roles/complementary_role/index.md @@ -0,0 +1,99 @@ +--- +title: "ARIA: complementary role" +short-title: complementary +slug: Web/Accessibility/ARIA/Reference/Roles/complementary_role +page-type: aria-role +spec-urls: + - https://w3c.github.io/aria/#complementary + - https://www.w3.org/WAI/ARIA/apg/patterns/landmarks/examples/complementary.html +sidebar: accessibilitysidebar +--- + +The `complementary` [landmark role](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles#3._landmark_roles) is used to designate a supporting section that relates to the main content, yet can stand alone when separated. These sections are frequently presented as sidebars or call-out boxes. If possible, use the [HTML \<aside> element](/en-US/docs/Web/HTML/Reference/Elements/aside) instead. + +```html +<div role="complementary"> + <h2>Our partners</h2> + <!-- complementary section content --> +</div> +``` + +This is a sidebar containing links to project sponsors. + +## Description + +The `complementary` role is [a landmark](/en-US/docs/Web/Accessibility/ARIA/Guides/Techniques#landmark_roles) role. Landmarks can be used by assistive technology to quickly identify and navigate to large sections of the document. Content listed within a container with the `complementary` landmark role should make sense if separated from the main content of the document. + +> [!NOTE] +> Using the {{HTMLElement('aside')}} element will automatically communicate a section has a role of `complementary`. Developers should always prefer using the correct semantic HTML element over using ARIA. + +## Examples + +```html +<div role="complementary"> + <h2>Trending articles</h2> + <ul> + <li><a href="#">18 tweets that will make you feel all the feels</a></li> + <li> + <a href="#">Stop searching! I've found the perfect lunch containers.</a> + </li> + <li> + <a href="#">The time has come to decide how to call these foods</a> + </li> + <li><a href="#">17 really good posts we saw on Tumblr this week</a></li> + <li><a href="#">10 parent hacks we know work because we tried them</a></li> + </ul> +</div> +``` + +## Accessibility concerns + +[Landmark roles](/en-US/docs/Web/Accessibility/ARIA/Guides/Techniques#landmark_roles) are intended to be used sparingly, to identify larger overall sections of the document. Using too many landmark roles can create "noise" in screen readers, making it difficult to understand the overall layout of the page. + +## Best practices + +### Prefer HTML + +Using the {{HTMLElement('aside')}} element will automatically communicate a section has a role of `complementary`. If at all possible, prefer using it instead. + +### Labeling landmarks + +#### Multiple landmarks + +If there is more than one `complementary` landmark role or {{HTMLElement('aside')}} element in a document, provide a label for each landmark using the [`aria-label`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-label) attribute, or, if the aside has an appropriately descriptive title, point to it with the [`aria-labelledby`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-labelledby) attribute. This label will allow an assistive technology user to be able to quickly understand the purpose of each landmark. + +```html +<aside aria-label="Note about usage"> + <!-- content --> +</aside> + +… + +<aside id="sidebar" aria-label="Sponsors"> + <!-- content --> +</aside> +``` + +#### Redundant descriptions + +Screen readers will announce the type of role the landmark is. Because of this, you do not need to describe what the landmark is in its label. For example, a declaration of `role="complementary"` with an of `aria-label="Sidebar"` may be announced redundantly as, "complementary sidebar". + +### Added benefits + +Certain technologies such as browser extensions can generate lists of all landmark roles present on a page, allowing non-screen reader users to also quickly identify and navigate to large sections of the document. + +- [Landmarks browser extension](https://matatk.agrip.org.uk/landmarks/) + +## Specifications + +{{Specifications}} + +## See also + +- [\<aside>: The Aside element](/en-US/docs/Web/HTML/Reference/Elements/aside) +- [complementary (role): Accessible Rich Internet Applications (WAI-ARIA) 1.1](https://www.w3.org/TR/wai-aria/#complementary) +- [Using HTML sections and outlines](/en-US/docs/Web/HTML/Reference/Elements/Heading_Elements) +- [Landmark roles: Using ARIA: Roles, States, and Properties](/en-US/docs/Web/Accessibility/ARIA/Guides/Techniques#landmark_roles) +- [Using WAI-ARIA Landmarks – 2013 | The Paciello Group](https://www.tpgi.com/using-wai-aria-landmarks-2013/) +- [Accessible Landmarks | scottohara.me](https://www.scottohara.me/blog/2018/03/03/landmarks.html) +- [Aside Revisited | HTML5 Doctor](https://html5doctor.com/aside-revisited/) diff --git a/files/en-us/web/accessibility/aria/reference/roles/composite_role/index.md b/files/en-us/web/accessibility/aria/reference/roles/composite_role/index.md new file mode 100644 index 000000000000000..a9eedc91d7d5933 --- /dev/null +++ b/files/en-us/web/accessibility/aria/reference/roles/composite_role/index.md @@ -0,0 +1,29 @@ +--- +title: "ARIA: composite role" +short-title: composite +slug: Web/Accessibility/ARIA/Reference/Roles/composite_role +page-type: aria-role +spec-urls: https://w3c.github.io/aria/#composite +sidebar: accessibilitysidebar +--- + +The `composite` [abstract role](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles#6._abstract_roles) indicates a widget that may contain navigable descendants or owned children. + +> [!WARNING] +> The `composite` role is an abstract role. It is included here for completeness of documentation. It should not be used by web authors. + +## Description + +`Composite` is an abstract role used for the ontology. Don't use this role in content. Instead, use the composite subclasses of [`grid`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/grid_role), [`select`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/select_role), [`spinbutton`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/spinbutton_role), and [`tablist`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/tablist_role). + +## Specifications + +{{Specifications}} + +## See also + +- [ARIA: `widget` role](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/widget_role) +- [ARIA: `grid` role](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/grid_role) +- [ARIA: `select` role](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/select_role) +- [ARIA: `spinbutton` role](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/spinbutton_role) +- [ARIA: `tablist` role](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/tablist_role) diff --git a/files/en-us/web/accessibility/aria/reference/roles/contentinfo_role/index.md b/files/en-us/web/accessibility/aria/reference/roles/contentinfo_role/index.md new file mode 100644 index 000000000000000..872b264b577d9de --- /dev/null +++ b/files/en-us/web/accessibility/aria/reference/roles/contentinfo_role/index.md @@ -0,0 +1,133 @@ +--- +title: "ARIA: contentinfo role" +short-title: contentinfo +slug: Web/Accessibility/ARIA/Reference/Roles/contentinfo_role +page-type: aria-role +spec-urls: + - https://w3c.github.io/aria/#contentinfo + - https://www.w3.org/WAI/ARIA/apg/patterns/landmarks/examples/contentinfo.html +sidebar: accessibilitysidebar +--- + +The `contentinfo` role defines a footer, containing identifying information such as copyright information, navigation links, and privacy statements, found on every document within a site. This section is commonly called a footer. + +```html +<div role="contentinfo"> + <h2>Footer</h2> + <!-- footer content --> +</div> +``` + +This is a website footer. Using the {{HTMLElement('footer')}} element instead is recommended: + +```html +<footer> + <h2>Footer</h2> + <!-- footer content --> +</footer> +``` + +## Description + +The `contentinfo` role is [a landmark](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles#3._landmark_roles) used to identify a page footer. Landmarks can be used by assistive technology to quickly identify and navigate to large sections of the document. Pages should only include one top-level `contentinfo` landmark role per page. + +Each page should only include one `contentinfo` landmark, created by either using the {{HTMLElement('footer')}} element or by declaring `role="contentinfo"`. `contentinfo` landmarks present in content embedded via {{HTMLElement('iframe')}} do not count towards this limit. + +> [!NOTE] +> Using the {{HTMLElement('footer')}} element will automatically communicate a section has a role of `contentinfo`. Developers should always prefer using the correct semantic HTML element over using ARIA, making sure to {{HTMLElement('footer#accessibility', 'test for known issues')}} in VoiceOver. + +## Examples + +```html +<body> + <!-- other page content --> + + <div role="contentinfo"> + <h2>MDN Web Docs</h2> + <ul> + <li><a href="#">Web Technologies</a></li> + <li><a href="#">Learn Web Development</a></li> + <li><a href="#">About MDN</a></li> + <li><a href="#">Feedback</a></li> + </ul> + <p> + © 2005-2012 Mozilla and individual contributors. Content is available + under <a href="#">these licenses</a>. + </p> + </div> +</body> +``` + +## Accessibility concerns + +### Use sparingly + +[Landmark roles](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles#3._landmark_roles) are intended to identify larger overall sections of the document. Using too many landmark roles can create "noise" in screen readers, making it difficult to understand the overall layout of the page. + +### One `contentinfo` landmark per page + +#### The `<body>` element + +There should be only one `contentinfo` landmark per document, used as the immediate descendant of the {{HTMLElement('body')}} element. + +#### Mega-footers + +Do not nest additional {{HTMLElement('footer')}} elements or `contentinfo` landmarks inside the document's footer. Use other [content sectioning elements](/en-US/docs/Web/HTML/Reference/Elements#content_sectioning) instead. + +### Labeling landmarks + +#### Multiple landmarks + +If there is more than one `contentinfo` landmark role or {{HTMLElement('footer')}} element in a document, provide a label with the [`aria-label`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-label) attribute for each landmark. This label will allow assistive technology users to quickly understand the purpose of each landmark. + +```html +<body> + … + + <article> + <h2>Everyday Pad Thai</h2> + <!-- article content --> + <footer aria-label="Everyday Pad Thai metadata"> + <p> + Posted on <time datetime="2021-09-23 12:17">September 23</time> by + <a href="#">Lisa</a>. + </p> + </footer> + </article> + + … + + <footer aria-label="Footer"> + <!-- footer content --> + </footer> +</body> +``` + +#### Redundant descriptions + +Screen readers will announce the type of role the landmark is. Because of this, you do not need to describe what the landmark is in its label. For example, a declaration of `role="contentinfo"` with an of `aria-label="Footer"` may be announced redundantly as, "contentinfo footer". + +## Best practices + +### Prefer HTML + +When it is an immediate descendant of the {{HTMLElement('body')}} using the {{HTMLElement('footer')}} element will automatically communicate a section has a role of `contentinfo` (save for {{HTMLElement('footer#accessibility', 'a known issue')}} in VoiceOver). If at all possible, prefer using `<footer>` instead. Note that a `footer` element nested within an `article`, `aside`, `main`, `nav`, or `section` is not considered `contentinfo`. + +### Added benefits + +Certain technologies such as browser extensions can generate lists of all landmark roles present on a page, allowing non-screen reader users to also quickly identify and navigate to large sections of the document. + +- [Landmarks browser extension](https://matatk.agrip.org.uk/landmarks/) + +## Specifications + +{{Specifications}} + +## See also + +- The {{HTMLElement('footer')}} element +- [contentinfo (role): Accessible Rich Internet Applications (WAI-ARIA) 1.1](https://www.w3.org/TR/wai-aria/#contentinfo) +- [Using HTML sections and outlines](/en-US/docs/Web/HTML/Reference/Elements/Heading_Elements) +- [Using WAI-ARIA Landmarks – 2013 | The Paciello Group](https://www.tpgi.com/using-wai-aria-landmarks-2013/) +- [Accessible Landmarks | scottohara.me](https://www.scottohara.me/blog/2018/03/03/landmarks.html) +- [The Footer Element Update | HTML5 Doctor](https://html5doctor.com/the-footer-element-update/) diff --git a/files/en-us/web/accessibility/aria/reference/roles/definition_role/index.md b/files/en-us/web/accessibility/aria/reference/roles/definition_role/index.md new file mode 100644 index 000000000000000..1d4b87b50526cbc --- /dev/null +++ b/files/en-us/web/accessibility/aria/reference/roles/definition_role/index.md @@ -0,0 +1,48 @@ +--- +title: "ARIA: definition role" +short-title: definition +slug: Web/Accessibility/ARIA/Reference/Roles/definition_role +page-type: aria-role +spec-urls: https://w3c.github.io/aria/#definition +sidebar: accessibilitysidebar +--- + +The `definition` ARIA role indicates the element is a definition of a term or concept. + +## Description + +The `definition` ARIA role can be included on an element that is a definition of a term or concept, similar to the native {{HTMLElement('dfn')}} element. To associate the definition with the `term` being defined, and to provide an accessible name, reference the term being defined with `role="term"`, using [`aria-labelledby`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-labelledby). + +```html-nolint +<p> + <span role="term">Mansplaining</span>, + <span role="definition"> + a portmanteau of "man" and "explain", is the patronizing act of explaining + without being asked to do so, to someone already learned on the topic, often + after someone has already explained it + </span>. +</p> +``` + +> [!NOTE] +> Instead of a `<span>` with the [`term`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/term_role) and `definition` roles, use the {{HTMLElement('dfn')}} element. **Always use native element if available.** + +```html +<p> + <dfn>Mansplaining</dfn>, a portmanteau of "man" and "explain", is the + patronizing act of explaining without being asked to do so, to someone already + learned on the topic, often after someone has already explained it. +</p> +``` + +## Specifications + +{{Specifications}} + +## See also + +- [The `term` role](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/term_role) +- The {{HTMLElement('dfn')}} element +- The {{HTMLElement('dd')}} element +- The {{HTMLElement('dl')}} element +- The {{HTMLElement('dt')}} element diff --git a/files/en-us/web/accessibility/aria/reference/roles/dialog_role/index.md b/files/en-us/web/accessibility/aria/reference/roles/dialog_role/index.md new file mode 100644 index 000000000000000..a145597be7dec0f --- /dev/null +++ b/files/en-us/web/accessibility/aria/reference/roles/dialog_role/index.md @@ -0,0 +1,143 @@ +--- +title: "ARIA: dialog role" +short-title: dialog +slug: Web/Accessibility/ARIA/Reference/Roles/dialog_role +page-type: aria-role +spec-urls: + - https://w3c.github.io/aria/#dialog + - https://www.w3.org/WAI/ARIA/apg/patterns/dialog-modal/examples/dialog/ +sidebar: accessibilitysidebar +--- + +The `dialog` role is used to mark up an HTML based application dialog or window that separates content or UI from the rest of the web application or page. Dialogs are generally placed on top of the rest of the page content using an overlay. Dialogs can be either non-modal (it's still possible to interact with content outside of the dialog) or modal (only the content in the dialog can be interacted with). + +```html +<div + role="dialog" + aria-labelledby="dialog1Title" + aria-describedby="dialog1Desc"> + <h2 id="dialog1Title">Your personal details were successfully updated</h2> + <p id="dialog1Desc"> + You can change your details at any time in the user account section. + </p> + <button>Close</button> +</div> +``` + +## Description + +A dialog is a descendant window of the primary window of a web application. For HTML pages, the primary application window is the entire web document, i.e., the body element. + +Marking up a dialog element with the `dialog` role helps assistive technology identify the dialog's content as being grouped and separated from the rest of the page content. However, adding `role="dialog"` alone is not sufficient to make a dialog accessible. Additionally, the following needs to be done: + +- The dialog must be properly labeled +- Keyboard focus must be managed correctly + +The sections below describe how these two requirements can be met. + +### Labeling + +Even though it is not required for the dialog itself to be able to receive focus, it still needs to be labeled. The label given to the dialog will provide contextual information for the interactive controls inside the dialog. In other words, the dialog's label acts like a grouping label for the controls inside it (similar to how a `<legend>` element provides a grouping label for the controls inside a `<fieldset>` element). + +If a dialog already has a visible title bar, the text inside that bar can be used to label the dialog itself. The best way to achieve this is by using the [`aria-labelledby`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-labelledby) attribute to the `role="dialog"` element. Additionally, if the dialog contains additional descriptive text besides the dialog title, this text can be associated with the dialog using the [`aria-describedby`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-describedby) attribute. This approach is shown in the code snippet below: + +```html +<div + role="dialog" + aria-labelledby="dialog1Title" + aria-describedby="dialog1Desc"> + <h2 id="dialog1Title">Your personal details were successfully updated</h2> + <p id="dialog1Desc"> + You can change your details at any time in the user account section. + </p> + <button>Close</button> +</div> +``` + +> [!NOTE] +> Keep in mind that a dialog's title and description text do not have to be focusable in order to be perceived by screen readers operating in a non-virtual mode. The combination of the ARIA dialog role and labeling techniques should make the screen reader announce the dialog's information when focus is moved into it. + +### Required JavaScript features + +#### Focus management + +A dialog has particular requirements for how keyboard focus should be managed: + +- Dialogs should always have at least one focusable control. For many dialogs, there will be a button like "Close", "OK" or "Cancel". In addition to the needed control, dialogs can contain any number of focusable elements, even entire forms or other container widgets like tabs. +- When the dialog appears on the screen, keyboard focus (whose control depends upon the dialog's purpose) should be moved to the default focusable control inside the dialog. For dialogs that only provide a basic message, it could be an "OK" button. For dialogs containing a form it could be the first field in the form. +- After the dialog is dismissed, keyboard focus should be moved back to where it was before it moved into the dialog. Otherwise the focus can be dropped to the beginning of the page. +- For most dialogs, the expected behavior is that the dialog's tab order _wraps_, which means that when the user tabs through the focusable elements in the dialog, the first focusable element will be focused after the last one has been reached. In other words, the tab order should be contained within and by the dialog. +- If the dialog can be moved or resized, ensure that these actions must be performable by keyboard users as well as mouse users. Similarly, if a dialog provides special features like toolbars or context menus, these must be reachable and operable by keyboard users as well. +- Dialogs can be modal or non-modal. When a _modal_ dialog appears on the screen, it's not possible to interact with any page content outside the dialog. In other words, the main application UI or page content is considered to be temporarily disabled as long as the modal dialog is showing. For _non-modal_ dialogs it is still possible to interact with content outside of the dialog while the dialog is showing. Note that for non-modal dialogs there will have to be a global keyboard shortcut that allows focus to be moved between opened dialogs and the main page. + +### Associated ARIA roles, states, and properties + +- [`aria-labelledby`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-labelledby) + - : Use this attribute to label the dialog. Often, the value of the `aria-labelledby` attribute will be the id of the element used to title the dialog. +- [`aria-describedby`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-describedby) + - : Use this attribute to describe the contents of the dialog. + +### Possible effects on user agents and assistive technology + +When the `dialog` role is used, the user agent should do the following: + +- Expose the element as a dialog in the operating system's accessibility API. + +When the dialog is correctly labeled and focus is moved to an element (often an interactive element, such as a button) inside the dialog, screen readers should announce the dialog's accessible role, name and optionally description, along with announcing the focused element. + +> [!NOTE] +> Opinions may differ on how assistive technology should handle this technique, and the order of announcements may differ depending on the assistive technology used. The information provided above is one of those opinions and may change as the specification is defined. + +## Examples + +### A dialog containing a form + +```html +<div + role="dialog" + aria-labelledby="dialog1Title" + aria-describedby="dialog1Desc"> + <h2 id="dialog1Title">Subscription Form</h2> + <p id="dialog1Desc">We will not share this information with third parties.</p> + <form> + <p> + <label for="firstName">First Name</label> + <input id="firstName" type="text" /> + </p> + <p> + <label for="lastName">Last Name</label> + <input id="lastName" type="text" /> + </p> + <p> + <label for="interests">Interests</label> + <textarea id="interests"></textarea> + </p> + <p> + <input type="checkbox" id="autoLogin" name="autoLogin" /> + <label for="autoLogin">Auto-login?</label> + </p> + <p> + <input type="submit" value="Save Information" /> + </p> + </form> +</div> +``` + +#### Working Examples + +- [jQuery-UI Dialog](https://jqueryui.com/dialog/) + +### Notes + +> [!NOTE] +> While it is possible to prevent keyboard users from moving focus to elements outside of the dialog, screen reader users may still be able to navigate to that content using their screen reader's virtual cursor. +> It is important for developers to ensure that content outside of the modal dialog is inaccessible to all users while the modal dialog is active. + +## Specifications + +{{Specifications}} + +## See also + +- [ARIA: alertdialog role](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/alertdialog_role) +- {{HTMLElement('dialog', 'The HTML <code>&lt;dialog&gt;</code> element')}} diff --git a/files/en-us/web/accessibility/aria/reference/roles/directory_role/index.md b/files/en-us/web/accessibility/aria/reference/roles/directory_role/index.md new file mode 100644 index 000000000000000..0740b13f2426eab --- /dev/null +++ b/files/en-us/web/accessibility/aria/reference/roles/directory_role/index.md @@ -0,0 +1,32 @@ +--- +title: "ARIA: directory role" +short-title: directory +slug: Web/Accessibility/ARIA/Reference/Roles/directory_role +page-type: aria-role +status: + - deprecated +spec-urls: https://w3c.github.io/aria/#directory +sidebar: accessibilitysidebar +--- + +The `directory` role was for a list of references to members of a group, such as a static table of contents. + +> [!WARNING] +> The `directory` role was deprecated in ARIA 1.2 + +## Description + +A directory is a static table of contents, whether linked or unlinked. This includes tables of contents built with lists, including nested lists. Dynamic tables of contents, however, might use a tree role instead. + +The deprecated `directory` role was used for lists of references to members of a group, such as a static table of contents. +Use the [`list`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/list_role) role instead. Or, better yet, use the {{HTMLElement('ul')}} or {{HTMLElement('ol')}} elements, as using `directory` does not provide any additional benefits to assistive technology users. + +## Specifications + +{{Specifications}} + +## See also + +- [The `list` role](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/list_role) +- The {{HTMLElement('ul')}} element +- The {{HTMLElement('ol')}} element diff --git a/files/en-us/web/accessibility/aria/reference/roles/document_role/index.md b/files/en-us/web/accessibility/aria/reference/roles/document_role/index.md new file mode 100644 index 000000000000000..14a55b49f0e3deb --- /dev/null +++ b/files/en-us/web/accessibility/aria/reference/roles/document_role/index.md @@ -0,0 +1,75 @@ +--- +title: "ARIA: document role" +short-title: document +slug: Web/Accessibility/ARIA/Reference/Roles/document_role +page-type: aria-role +spec-urls: https://w3c.github.io/aria/#document +sidebar: accessibilitysidebar +--- + +The `document` role is for focusable content within complex composite [widgets](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/widget_role) or [applications](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/application_role) for which assistive technologies can switch reading context back to a reading mode. + +## Description + +The `document` role is for the top container containing content that assistive technology users may want to browse in a reading mode. Only useful on focusable sections within complex composite [widgets](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/widget_role) or [applications](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/application_role), the `document` role informs assistive technologies to the reading context back to a reading mode: The `document` role tells assistive technologies with reading or browse modes to use the document mode to read the content contained within this element. + +```html +<div role="dialog"> + … + <div id="InfoText" role="document" tabindex="0"> + <p>Some informational text goes here.</p> + </div> + … + <button>Close</button> +</div> +``` + +This example shows a [dialog](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/dialog_role), a complex composite widget role, with some controls and a section with some informational text that the assistive technology user can go into reading mode when tabbed to. + +By default, web pages are treated as documents; assistive technologies (AT) enter browse or read mode when entering a new web page. This mode can be altered through various roles, including the widget and application roles. The `document` role brings the AT back into browse or read mode. + +Generally placed within an application role or other interactive widget role, the `document` role is used to indicate a section of a complex composite widget that an assistive technology user should read using its browse or virtual reading mode, if available. + +Because ATs with reading mode default to that mode for all elements except for those with a widget or application role set, document role is only useful for focusable elements within a widget or application that should be read as static rich text. Adding `role="document"` and `tabindex="0"` to the element containing the text within a widget enables the screen reader user to press the Tab key to place focus on the document element and read the text with the screen reader's reading cursor. + +Assistive technologies should switch context back to document mode, possibly intercepting from controls rewired for the parent's dynamic context, re-enabling the standard input events, such as Up or Down arrow keyboard events, to control the reading cursor. + +In contrast to the [`article`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/article_role) role, the `document` role does not have any relation to other elements with a document role, it merely has a relationship to the containing composite widget. An article can have associated articles. + +### Associated WAI-ARIA roles, states, and properties + +- [`aria-expanded`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-expanded) + + - : Include with a value of `true` or `false` if the document element is collapsible, to indicate if the document is currently expanded or collapsed. Other values include the default `undefined` which means the document is not collapsible. + +- tabindex="0" + - : Used to make it focusable so the assistive technology user can tab to it and start reading right away. + +### Keyboard interactions + +The element should be made focusable by setting the `tabindex="0"` attribute / value pair on it. This way, the user can tab to it, reading mode is invoked automatically, and the content can be read right away. + +### Required JavaScript features + +None, except as required by any attributes. For example, if the `document` is collapsible, then the state and the value of `aria-expanded` must be maintained. + +## Examples + +An example is Gmail and the single conversation view. GMail is a web application. When in GMail, most user agent interactions are usurped by the application. However, when the Keyboard focus is set on the starting heading on a single conversation that contains the subject of the conversation, the screen reader user can use the reading mode commands to read through the messages, expand or collapse them, and manipulate them. Once focus returns to the message list either by activating the Back button or pressing an associated keystroke, direct application interaction mode is invoked again, and the user can move to a different conversation in the list with the <kbd>arrow</kbd> keys. + +## Best practices + +Always make sure an item with the document role is focusable, by setting the `tabindex` attribute with a value of 0. That will also include it in the tab order. + +### Added benefits + +The document role is an easy way to indirectly control assistive technology behavior by unambiguously stating that this is content the user should read with standard screen reader commands. + +## Specifications + +{{Specifications}} + +## See also + +- [ARIA: `widget` role](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/widget_role) +- [ARIA: `application` role](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/application_role) diff --git a/files/en-us/web/accessibility/aria/reference/roles/feed_role/index.md b/files/en-us/web/accessibility/aria/reference/roles/feed_role/index.md new file mode 100644 index 000000000000000..62f64abaa0e9417 --- /dev/null +++ b/files/en-us/web/accessibility/aria/reference/roles/feed_role/index.md @@ -0,0 +1,90 @@ +--- +title: "ARIA: feed role" +short-title: feed +slug: Web/Accessibility/ARIA/Reference/Roles/feed_role +page-type: aria-role +spec-urls: https://w3c.github.io/aria/#feed +sidebar: accessibilitysidebar +--- + +A `feed` is a dynamic scrollable `list` of `articles` in which articles are added to or removed from either end of the list as the user scrolls. A `feed` enables screen readers to use the browse mode reading cursor to both read and scroll through a stream of rich content that may continue scrolling infinitely by loading more content as the user reads. + +```html +<section role="feed" aria-busy="false"> + … + <article aria-posinset="427" aria-setsize="-1">…</article> + <article aria-posinset="428" aria-setsize="-1">…</article> + <article aria-posinset="429" aria-setsize="-1">…</article> + … +</section> +``` + +## Description + +A `feed` is a type of [`list`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/list_role), the containing role for scrollable [`articles`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/article_role) where scrolling may cause articles to be added to the top or end of the list. The role enables assistive technology to use the browse mode reading cursor to both read and scroll through a stream of rich content that may continue scrolling infinitely by loading more content as the user reads. Examples include an RSS feed, news feeds, social media feeds like Facebook, Instagram or Mastodon, or even a list of related products on an e-commerce page. These streams can be limited or infinite, loading more content as the user scrolls. Implementing the `feed` pattern allows a screen reader to reliably read and trigger the loading of feed content while in reading mode. + +Unlike the document structure elements that represent static HTML elements, the `feed` role requires specific interactions and implementation of keyboard navigation. The `feed` is a container element whose children are {{HTMLElement('article')}}s or have role `article`. Each article within a feed should be focusable, with tabindex of 0 or -1. An article should be scrolled into view when it, or a descendant element, receives focus. If the addition of articles occupies the main browser thread, make sure to set `aria-busy="true"` on the feed itself, and make sure to set it back to `false` when processing ends, or the user may not see the updates. + +If the number of articles is known, set [`aria-setsize`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-setsize) on the articles themselves. However, if the total number is extremely large, indefinite, or changes often, set `aria-setsize="-1"` to indicate that the size of the feed is not known. + +Another feature of the feed pattern is skim reading: Articles within a feed can contain both an accessible name with the [`aria-label`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-label) and a description with an `aria-describedby`, suggesting to screen readers which elements to speak after the label when navigating by article. By identifying the elements inside an article that provide the title and the primary content, assistive technologies can provide functions that enable users to jump from article to article and efficiently discern which articles they want to read. + +The feed pattern enables reliable assistive technology reading mode interaction by establishing the following interoperability agreement between the web page and assistive technologies: + +In the context of a feed, the web page code is responsible for: + +- Appropriate visual scrolling of the content based on which article contains DOM focus. +- Loading or removing feed articles based on which article contains DOM focus. + +### Keyboard interactions + +Supporting the following, or a similar, interface is recommended when focus is inside the feed: + +- <kbd>Page Down</kbd>: Move focus to next article. +- <kbd>Page Up</kbd>: Move focus to previous article. +- <kbd>Control + End</kbd>: Move focus to the first focusable element after the feed. +- <kbd>Control + Home</kbd>: Move focus to the first focusable element before the feed. + +If a feed is nested within a feed, such as a comments feed within a feed of blog posts, the convention is to tab into the nested feed with the <kbd>Tab</kbd> key and to provide another key, such as <kbd>Alt + Page Down</kbd>, to navigate from an 'outer' article to the first item in that article's nested feed. Navigate between the nested feed and main feed with <kbd>Control + End</kbd>, moving focus from the inner feed to the next article in the outer feed. + +### <abbr title="Accessible Rich Internet Applications">WAI-ARIA</abbr> roles, states, and properties + +- [`aria-label`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-label) + + - : If the feed has no visible title, the `feed` element has a label specified with `aria-label`. If it does, see `aria-labelledby`. + +- [`aria-labelledby`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-labelledby) + + - : If the feed has a visible title, the `feed` element has `aria-labelledby` referring to the element containing the title. If not, add an `aria-label`. + +- [`aria-busy`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-busy) + + - : When busy, such as when articles are being added or removed from the `feed`, set `aria-busy="true"` during the update operation. Make sure it's reset to `false` when the operation is complete or the changes may not become visible. + +- article + - : Each section of content in a feed should be contained in an `<article>` or element with role [`article`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/article_role). Each `article` should have an `aria-labelledby` referring to the article title or other child that can serve as a distinguishing label. Each article should preferably have `aria-describedby` referring to one or more elements inside the article that serve as the primary content of the article. Each `article` element has [`aria-posinset`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-posinset) set to a value that represents its position in the feed and an [`aria-setsize`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-setsize) set to a value that represents either the total number of articles that have been loaded or the total number in the feed, depending on which value is more helpful to users. If the total number in the feed is not known, set `aria-setsize="-1"`. + +### Required JavaScript features + +None, except as required by any attributes. For example, setting [`aria-busy`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-busy) to `true` during the update operation if needed, and then to `false` upon completion. + +Note: It is the author's responsibility to apply the "above" keyboard behavior. + +## Examples + +[Example Implementation of Feed Pattern](https://www.w3.org/WAI/ARIA/apg/patterns/feed/examples/feed/) + +## Best practices + +To ensure good user experience, avoid inserting or removing articles in the middle of a `feed`, load new articles before the user has reached the end of the feed, and provide keyboard commands for moving focus among articles so that keyboard users can navigate through your feed. See [Keyboard interactions](#keyboard_interactions). + +## Specifications + +{{Specifications}} + +## See also + +- The HTML {{HTMLElement('article')}} element +- The {{HTMLElement('ul')}} unordered list element +- [ARIA: `article` role](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/article_role) +- [ARIA: `list` role](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/list_role) diff --git a/files/en-us/web/accessibility/aria/reference/roles/figure_role/index.md b/files/en-us/web/accessibility/aria/reference/roles/figure_role/index.md new file mode 100644 index 000000000000000..5b06d267d3b80f9 --- /dev/null +++ b/files/en-us/web/accessibility/aria/reference/roles/figure_role/index.md @@ -0,0 +1,117 @@ +--- +title: "ARIA: figure role" +short-title: figure +slug: Web/Accessibility/ARIA/Reference/Roles/figure_role +page-type: aria-role +spec-urls: https://w3c.github.io/aria/#figure +sidebar: accessibilitysidebar +--- + +The ARIA `figure` role can be used to identify a figure inside page content where appropriate semantics do not already exist. A figure is generally considered to be one or more images, code snippets, or other content that puts across information in a different way to a regular flow of text. + +## Description + +A `figure` is a perceivable section of content that typically contains a graphical document, images, code snippets, or example text. The parts of a figure MAY be user-navigable. Any content that should be grouped together and consumed as a figure (which could include images, video, audio, code snippets, or other content) can be identified as a figure using `role="figure"`. + +```html +<div role="figure" aria-labelledby="caption"> + <img src="image.png" alt="put image description here" /> + <p id="caption">Figure 1: The caption</p> +</div> +``` + +In the above example, we have a figure that consists of two separate content items — an image and a caption. This is wrapped by a {{htmlelement("div")}} element that identifies the content as a figure using `role="figure"`. + +For HTML, use the {{HTMLElement('figure')}} and {{HTMLElement('figcaption')}} elements. The figcaption will serve as the accessible name for the figure. When not using HTML, or when retrofitting legacy HTML, use the [`aria-labelledby`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-labelledby) on the figure, pointing to the figure's caption. +If there is no visible caption, [`aria-label`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-label) can be used. + +```html +<div role="figure" aria-labelledby="figure-1"> + … + <p id="figure-1">Text that describes the figure.</p> +</div> +``` + +- Use `aria-labelledby` when the text is a concise label. +- Use [`aria-describedby`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-describedby) when the text is a longer description. +- Use [`aria-label`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-label) when there is no visible figure caption. + +This can be done semantically, without ARIA, with HTML's {{HTMLElement('figure')}} element along with {{HTMLElement('figcaption')}}. + +```html +<figure> + <img src="image.png" alt="put image description here" /> + <figcaption>Figure 1: The caption</figcaption> +</figure> +``` + +> [!NOTE] +> If at all possible in your work, you should use the appropriate semantic HTML elements to mark up a figure and its caption — {{htmlelement("figure")}} and {{htmlelement("figcaption")}}. + +### Associated WAI-ARIA roles, states, and properties + +- [`aria-describedby`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-describedby) + - : The id of an element containing reference text serving as a caption. +- [`aria-labelledby`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-labelledby) + - : The id of an element containing text serving as a label. +- [`aria-label`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-label) + - : If there is no element containing text that could serve as a label, you can add the label directly as a value on the `aria-label` on the element with the `figure` role or on the `<figure>` element. + +### Keyboard interactions + +No role specific keyboard interactions. + +### Required JavaScript features + +No role specific JavaScript requirements. If you don't have control over the HTML semantics, you can improve the accessibility of HTML by adding these roles and properties with JavaScript. + +## Examples + +We could extend the initial example on the page to also identify a paragraph that provides a descriptive label for the figure by referencing its ID in `aria-labelledby`: + +```html +<div role="figure" aria-labelledby="figure-1"> + <img + src="diagram.png" + alt="diagram showing the four layers of awesome and their relative priority order — + music, cats, nature, and ice cream" /> + <pre> +` + let awesome = ['music', 'cats', 'nature', 'ice cream']; + `</pre + > + <p id="figure-1">Figure 1: The four layers of awesome.</p> +</div> +``` + +## Best practices + +Only use `role="figure"` if you have to — for example if you don't have control over your HTML but are able to improve accessibility dynamically after the fact with JavaScript. + +If at all possible, you should use the appropriate semantic HTML elements to mark up a figure and its caption — {{htmlelement("figure")}} and {{htmlelement("figcaption")}}. For example, our above example should be rewritten as follows: + +```html +<figure> + <img + src="diagram.png" + alt="diagram showing the four layers of awesome and their relative priority order — + music, cats, nature, and ice cream" /> + <pre> +` + let awesome = ['music', 'cats', 'nature', 'ice cream']; + `</pre + > + <figcaption>Figure 1: The four layers of awesome.</figcaption> +</figure> +``` + +## Specifications + +{{Specifications}} + +## See also + +- [Accessibility Object Model](https://wicg.github.io/aom/spec/) +- [ARIA in HTML](https://w3c.github.io/html-aria/) +- [HTML `<figure>` element](/en-US/docs/Web/HTML/Reference/Elements/figure) +- [HTML `<figcaption>` element](/en-US/docs/Web/HTML/Reference/Elements/figcaption) diff --git a/files/en-us/web/accessibility/aria/reference/roles/form_role/index.md b/files/en-us/web/accessibility/aria/reference/roles/form_role/index.md new file mode 100644 index 000000000000000..8746feebea57f23 --- /dev/null +++ b/files/en-us/web/accessibility/aria/reference/roles/form_role/index.md @@ -0,0 +1,131 @@ +--- +title: "ARIA: form role" +short-title: form +slug: Web/Accessibility/ARIA/Reference/Roles/form_role +page-type: aria-role +spec-urls: + - https://w3c.github.io/aria/#form + - https://www.w3.org/WAI/ARIA/apg/patterns/landmarks/examples/form.html +sidebar: accessibilitysidebar +--- + +The `form` role can be used to identify a group of elements on a page that provide equivalent functionality to an HTML form. The form is not exposed as a landmark region unless it has an [accessible name](/en-US/docs/Glossary/Accessible_name). + +```html +<div role="form" id="contact-info" aria-label="Contact information"> + <!-- form content --> +</div> +``` + +This is a form that collects and saves a user's contact information. + +> [!WARNING] +> Use an HTML {{htmlelement("form")}} element to contain your form controls, rather than the ARIA `form` role, unless you have a very good reason. +> The HTML `<form>` element is sufficient to tell assistive technologies that there is a form. + +## Description + +A `form` [landmark](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles#3._landmark_roles) identifies a region of content that contains a collection of items and objects that, as a whole, combine to create a form when no other named landmark is appropriate (e.g., [`main`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/main_role) or [`search`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/search_role)). + +> [!NOTE] +> Using the {{HTMLElement('form')}} element will automatically communicate a section of content as a `form` landmark, if it is provided an accessible name. Developers should always prefer using the correct semantic HTML element over using ARIA. + +Use the HTML {{HTMLElement('form')}} element if possible. The `<form>` element defines a `form` landmark when it has an accessible name (e.g., [`aria-labelledby`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-labelledby), [`aria-label`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-label) or [`title`](/en-US/docs/Web/HTML/Reference/Global_attributes/title)). Make sure to have a unique label on each form in a document to help users understand the purpose of the form. This label should be visible to all users, not just assistive technology users. Use the `search` landmark instead of the `form` landmark when the form is used for search functionality. + +Use the `role="form"` to identify a region of the page; do not use it to identify every form field. Even if you are using the form landmark instead of `<form>`, you are encouraged to use native HTML form controls like {{HTMLElement('button')}}, {{HTMLElement('input')}}, {{HTMLElement('select')}}, and {{HTMLElement('textarea')}}. + +### Associated WAI-ARIA roles, states, and properties + +No role specific states or properties. + +### Keyboard interactions + +No role specific keyboard interactions + +### Required JavaScript features + +- `onsubmit` + - : The onSubmit event handler handles the event raised when the form is submitted. Anything that is not a `<form>` cannot be submitted, therefore you would have to use JavaScript to build an alternative data submission mechanism, for example with {{domxref("Window/fetch", "fetch()")}}. + +## Examples + +```html +<div role="form" id="send-comment" aria-label="Add a comment"> + <label for="username">Username</label> + <input + id="username" + name="username" + autocomplete="nickname" + autocorrect="off" + type="text" /> + + <label for="email">Email</label> + <input + id="email" + name="email" + autocomplete="email" + autocapitalize="off" + autocorrect="off" + spellcheck="false" + type="text" /> + + <label for="comment">Comment</label> + <textarea id="comment" name="comment"></textarea> + + <input value="Comment" type="submit" /> +</div> +``` + +It is recommended to use `<form>` instead. + +```html +<form id="send-comment" aria-label="Add a comment">…</form> +``` + +## Accessibility concerns + +### Use sparingly + +[Landmark roles](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles#3._landmark_roles) are intended to identify larger overall sections of the document. Using too many landmark roles can create "noise" in screen readers, making it difficult to understand the overall layout of the page. + +### Inputs are not forms + +You do not need to declare `role="form"` on every [form element](/en-US/docs/Web/HTML/Reference/Elements#forms) (inputs, text areas, selects, etc.). It should be declared on the HTML element that wraps the form elements. Ideally, use the {{HTMLElement('form')}} element as the wrapping element and do not declare `role="form"`. + +### Search + +If a form is used to search, you should use the more specialized [`role="search"`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/search_role) value. + +### Labeling landmarks + +Each {{HTMLElement('form')}} element and form `role` that needs to be exposed as a landmark must be given an accessible name. This name will allow an assistive technology user to be able to quickly understand the purpose of the form landmark. + +Use an `aria-labelledby`, `aria-label` or `title` on the same element that was given the `role="form"` to provide it an accessible name. + +#### Using `role="form"` + +```html +<div role="form" id="gift-cards" aria-label="Purchase a gift card"> + <!-- form content --> +</div> +``` + +#### Redundant descriptions + +Screen readers will announce the type of role the landmark is. Because of this, you do not need to describe what the landmark is in its label. For example, a declaration of `role="form"` with an of `aria-label="Contact form"` may be announced redundantly as, "contact form form". + +## Best practices + +### Prefer HTML + +Using the {{HTMLElement('form')}} element will automatically communicate a section has a role of `form`. If at all possible, prefer using it instead. + +## Specifications + +{{Specifications}} + +## See also + +- The {{HTMLElement('form')}} element +- The {{HTMLElement('legend')}} element +- [form (role): Accessible Rich Internet Applications (WAI-ARIA) 1.1](https://www.w3.org/TR/wai-aria/#form) diff --git a/files/en-us/web/accessibility/aria/reference/roles/generic_role/index.md b/files/en-us/web/accessibility/aria/reference/roles/generic_role/index.md new file mode 100644 index 000000000000000..5f2f0103f926319 --- /dev/null +++ b/files/en-us/web/accessibility/aria/reference/roles/generic_role/index.md @@ -0,0 +1,44 @@ +--- +title: "ARIA: generic role" +short-title: generic +slug: Web/Accessibility/ARIA/Reference/Roles/generic_role +page-type: aria-role +spec-urls: https://w3c.github.io/aria/#generic +sidebar: accessibilitysidebar +--- + +The `generic` role creates a nameless container element which has no semantic meaning on its own. + +> [!NOTE] +> The `generic` role is the implicit role of generic elements used by user agents. It is included here for completeness of documentation. It should not be used by web authors. + +## Description + +While ARIA is primarily used to express semantics, there are some elements that shouldn't expose a semantic name to assistive technologies. The `generic` role indicates an element's role is equivalent to that of the non-semantic {{HTMLElement('div')}} and {{HTMLElement('span')}} elements. + +The `generic` role is intended for use as the implicit role of generic elements in host languages for use by user agents only; not for use by developers. Instead, to remove implicit accessibility semantics, use [`presentation`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/presentation_role) or `none`, the {{HTMLElement('div')}} and {{HTMLElement('span')}} elements that have no semantic meaning, or semantic container roles such as [`group`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/group_role) to semantically group descendants in a named container. + +Like an element with role `presentation`, an element with `role="generic"` can provide a limited number of accessible states and properties for its descendants, such as [`aria-live`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-live) attributes. However, unlike elements with role `presentation`, `generic` elements are exposed in accessibility APIs so that assistive technologies can gather certain properties such as layout and bounds. + +Because the generic role is nameless, the [`aria-labelledby`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-labelledby) and [`aria-label`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-label) attributes are prohibited. Because the role is generic, the [`aria-roledescription`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-roledescription) and [`aria-brailleroledescription`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-brailleroledescription) attributes are also prohibited. + +> [!NOTE] +> The element with `role="generic"` should not have an accessible name or role description. + +### Associated WAI-ARIA roles, states, and properties + +None. If a global ARIA state and property is set, `generic` or `none` will be ignored, and the implicit role of the element will be used. + +## Examples + +This role is for use by user agents and not by developers. As such, no appropriate example exists. + +## Specifications + +{{Specifications}} + +## See also + +- HTML {{HTMLElement('div')}} and {{HTMLElement('span')}} elements +- [`presentation`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/presentation_role) roles such as +- [`group`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/group_role) role diff --git a/files/en-us/web/accessibility/aria/reference/roles/grid_role/index.md b/files/en-us/web/accessibility/aria/reference/roles/grid_role/index.md new file mode 100644 index 000000000000000..4bf9bb0ee67e59f --- /dev/null +++ b/files/en-us/web/accessibility/aria/reference/roles/grid_role/index.md @@ -0,0 +1,386 @@ +--- +title: "ARIA: grid role" +short-title: grid +slug: Web/Accessibility/ARIA/Reference/Roles/grid_role +page-type: aria-role +spec-urls: https://w3c.github.io/aria/#grid +sidebar: accessibilitysidebar +--- + +The grid role is for a widget that contains one or more rows of cells. The position of each cell is significant and can be focused using keyboard input. + +## Description + +The `grid` role is a composite widget containing a collection of one or more rows with one or more cells where some or all cells in the grid are focusable by using methods of two-dimensional navigation, such as directional arrow keys. + +```html +<table role="grid" aria-labelledby="id-select-your-seat"> + <caption id="id-select-your-seat"> + Select your seat + </caption> + <tbody role="presentation"> + <tr role="presentation"> + <td></td> + <th>Row A</th> + <th>Row B</th> + </tr> + <tr> + <th scope="row">Aisle 1</th> + <td tabindex="0"> + <button id="1a" tabindex="-1">1A</button> + </td> + <td tabindex="-1"> + <button id="1b" tabindex="-1">1B</button> + </td> + <!-- More Columns --> + </tr> + <tr> + <th scope="row">Aisle 2</th> + <td tabindex="-1"> + <button id="2a" tabindex="-1">2A</button> + </td> + <td tabindex="-1"> + <button id="2b" tabindex="-1">2B</button> + </td> + <!-- More Columns --> + </tr> + </tbody> +</table> +``` + +A grid widget contains one or more rows with one or more cells of thematically related interactive content. While it does not imply a specific visual presentation, it implies a relationship among elements. Uses fall into two categories: presenting tabular information (data grids) and grouping other widgets (layout grids). Even though both data grids and layout grids employ the same ARIA roles, states, and properties, differences in their content and purpose surface factors that are important to consider in keyboard interaction design. See [ARIA Authoring Practices Guide](https://www.w3.org/WAI/ARIA/apg/patterns/grid/) for more details. + +Cell elements have the role [`gridcell`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/gridcell_role), unless they are a row or column header, in which case, the elements are [`rowheader`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/rowheader_role) and [`columnheader`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/columnheader_role), respectively. Cell elements need to be owned by elements with a [`row`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/row_role) role. Rows can be grouped using the [`rowgroup`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/rowgroup_role) role. + +If the grid is used as an interactive widget, [keyboard interactions](#keyboard_interactions) need to be implemented. + +### Associated ARIA roles, states, and properties + +#### Roles + +- [treegrid](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/treegrid_role) (subclass) + - : If a grid has columns that can expanded or collapsed, a treegrid can be used. +- [row](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/row_role) + - : A row inside the grid. +- [rowgroup](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/rowgroup_role) + - : A group containing one or multiple [row](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/row_role)s. + +#### States and properties + +- [aria-level](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-level) + - : Indicates the hierarchical level of the grid within other structures. +- [aria-multiselectable](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-multiselectable) + - : If `aria-multiselectable` is set to `true`, multiple items in the grid can be selected. The default value is `false`. +- [aria-readonly](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-readonly) + - : If the user can navigate the grid but not change the value or values of the grid, the [`aria-readonly`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-readonly) should be set to `true`. The default value is `false`. + +> [!NOTE] +> For many use cases, an HTML {{HTMLElement('table')}} element is sufficient as it and the various table elements already include many ARIA roles. + +### Keyboard interactions + +When a keyboard user encounters a grid, they navigate the rows and columns using the <kbd>left</kbd>, <kbd>right</kbd>, <kbd>top</kbd> and <kbd>down</kbd> keys. To activate the interactive component, they will use the <kbd>return</kbd> and <kbd>space</kbd> keys. + +| Key | Action | +| --------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| <kbd>→</kbd> | Moves focus one cell to the right. Optionally (layout grids), if focus is on the right-most cell in the row, focus may move to the first cell in the following row. If focus is on the last cell in the grid, focus does not move. | +| <kbd>←</kbd> | Moves focus one cell to the left. Optionally (layout grids), if focus is on the left-most cell in the row, focus may move to the last cell in the previous row. If focus is on the first cell in the grid, focus does not move. | +| <kbd>↓</kbd> | Moves focus one cell down. Optionally (layout grids), if focus is on the bottom cell in the column, focus may move to the top cell in the following column. If focus is on the last cell in the grid, focus does not move. | +| <kbd>↑</kbd> | Moves focus one cell up. Optionally (layout grids), if focus is on the top cell in the column, focus may move to the bottom cell in the previous column. If focus is on the first cell in the grid, focus does not move. | +| <kbd>Page Down</kbd> | Moves focus down an author-determined number of rows, typically scrolling so the bottom row in the currently visible set of rows becomes one of the first visible rows. If focus is in the last row of the grid, focus does not move. | +| <kbd>Page Up</kbd> | Moves focus up an author-determined number of rows, typically scrolling so the top row in the currently visible set of rows becomes one of the last visible rows. If focus is in the first row of the grid, focus does not move. | +| <kbd>Home</kbd> | Moves focus to the first cell in the row that contains focus. | +| <kbd>End</kbd> | Moves focus to the last cell in the row that contains focus. | +| <kbd>ctrl</kbd> + <kbd>Home</kbd> | Moves focus to the first cell in the first row. | +| <kbd>ctrl</kbd> + <kbd>End</kbd> | Moves focus to the last cell in the last row. | + +If cells, rows, or columns can be selected, the following key combination are commonly used: + +| Key combination | Action | +| ----------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| <kbd>ctrl</kbd> + <kbd>Space</kbd> | Select the column that contains the focus. | +| <kbd>shift</kbd> + <kbd>Space</kbd> | Selects the row that contains the focus. If the grid includes a column with checkboxes to select rows, this key combination can be used to check that box even if the focus is not on the checkbox. | +| <kbd>ctrl</kbd> + <kbd>A</kbd> | Selects all cells. | +| <kbd>shift</kbd> + <kbd>→</kbd> | Extends selection one cell to the right. | +| <kbd>shift</kbd> + <kbd>←</kbd> | Extends selection one cell to the left. | +| <kbd>shift</kbd> + <kbd>↓</kbd> | Extends selection one cell down. | +| <kbd>shift</kbd> + <kbd>↑</kbd> | Extends selection one cell up. | + +## Examples + +### Calendar example + +{{EmbedLiveSample("Calendar_example", "100%", "300")}} + +#### HTML + +```html +<table role="grid" aria-labelledby="calendarheader"> + <caption id="calendarheader"> + September 2018 + </caption> + <thead role="rowgroup"> + <tr role="row"> + <td></td> + <th role="columnheader" aria-label="Sunday">S</th> + <th role="columnheader" aria-label="Monday">M</th> + <th role="columnheader" aria-label="Tuesday">T</th> + <th role="columnheader" aria-label="Wednesday">W</th> + <th role="columnheader" aria-label="Thursday">T</th> + <th role="columnheader" aria-label="Friday">F</th> + <th role="columnheader" aria-label="Saturday">S</th> + </tr> + </thead> + <tbody role="rowgroup"> + <tr role="row"> + <th scope="row" role="rowheader">Week 1</th> + <td>26</td> + <td>27</td> + <td>28</td> + <td>29</td> + <td>30</td> + <td>31</td> + <td role="gridcell" tabindex="-1">1</td> + </tr> + <tr role="row"> + <th scope="row" role="rowheader">Week 2</th> + <td role="gridcell" tabindex="-1">2</td> + <td role="gridcell" tabindex="-1">3</td> + <td role="gridcell" tabindex="-1">4</td> + <td role="gridcell" tabindex="-1">5</td> + <td role="gridcell" tabindex="-1">6</td> + <td role="gridcell" tabindex="-1">7</td> + <td role="gridcell" tabindex="-1">8</td> + </tr> + <tr role="row"> + <th scope="row" role="rowheader">Week 3</th> + <td role="gridcell" tabindex="-1">9</td> + <td role="gridcell" tabindex="-1">10</td> + <td role="gridcell" tabindex="-1">11</td> + <td role="gridcell" tabindex="-1">12</td> + <td role="gridcell" tabindex="-1">13</td> + <td role="gridcell" tabindex="-1">14</td> + <td role="gridcell" tabindex="-1">15</td> + </tr> + <tr role="row"> + <th scope="row" role="rowheader">Week 4</th> + <td role="gridcell" tabindex="-1">16</td> + <td role="gridcell" tabindex="-1">17</td> + <td role="gridcell" tabindex="-1">18</td> + <td role="gridcell" tabindex="-1">19</td> + <td role="gridcell" tabindex="-1">20</td> + <td role="gridcell" tabindex="-1">21</td> + <td role="gridcell" tabindex="-1">22</td> + </tr> + <tr role="row"> + <th scope="row" role="rowheader">Week 5</th> + <td role="gridcell" tabindex="-1">23</td> + <td role="gridcell" tabindex="-1">24</td> + <td role="gridcell" tabindex="-1">25</td> + <td role="gridcell" tabindex="-1">26</td> + <td role="gridcell" tabindex="-1">27</td> + <td role="gridcell" tabindex="-1">28</td> + <td role="gridcell" tabindex="-1">29</td> + </tr> + <tr role="row"> + <th scope="row" role="rowheader">Week 6</th> + <td role="gridcell" tabindex="-1">30</td> + <td>1</td> + <td>2</td> + <td>3</td> + <td>4</td> + <td>5</td> + <td>6</td> + </tr> + </tbody> +</table> +``` + +#### CSS + +```css +table { + margin: 0; + border-collapse: collapse; + font-variant-numeric: tabular-nums; +} + +tbody th, +tbody td { + padding: 5px; +} + +tbody td { + border: 1px solid #000; + text-align: right; + color: #767676; +} + +tbody td[role="gridcell"] { + color: #000; +} + +tbody td[role="gridcell"]:hover, +tbody td[role="gridcell"]:focus { + background-color: #f6f6f6; + outline: 3px solid blue; +} +``` + +#### JavaScript + +```js +const selectables = document.querySelectorAll('table td[role="gridcell"]'); + +selectables[0].setAttribute("tabindex", 0); + +const trs = document.querySelectorAll("table tbody tr"); +let rowIndex = 0; +let colIndex = 0; +let maxRow = trs.length - 1; +let maxCol = 0; + +trs.forEach((row) => { + row.querySelectorAll("td").forEach((el) => { + el.dataset.row = rowIndex; + el.dataset.col = colIndex; + colIndex++; + }); + if (colIndex > maxCol) { + maxCol = colIndex - 1; + } + colIndex = 0; + rowIndex++; +}); + +function moveTo(newRow, newCol) { + const tgt = document.querySelector( + `[data-row="${newRow}"][data-col="${newCol}"]`, + ); + if (tgt?.getAttribute("role") !== "gridcell") { + return false; + } + document.querySelectorAll("[role=gridcell]").forEach((el) => { + el.setAttribute("tabindex", "-1"); + }); + tgt.setAttribute("tabindex", "0"); + tgt.focus(); + return true; +} + +document.querySelector("table").addEventListener("keydown", (event) => { + const col = parseInt(event.target.dataset.col, 10); + const row = parseInt(event.target.dataset.row, 10); + switch (event.key) { + case "ArrowRight": { + const newRow = col === 6 ? row + 1 : row; + const newCol = col === 6 ? 0 : col + 1; + moveTo(newRow, newCol); + break; + } + case "ArrowLeft": { + const newRow = col === 0 ? row - 1 : row; + const newCol = col === 0 ? 6 : col - 1; + moveTo(newRow, newCol); + break; + } + case "ArrowDown": + moveTo(row + 1, col); + break; + case "ArrowUp": + moveTo(row - 1, col); + break; + case "Home": { + if (event.ctrlKey) { + let i = 0; + let result; + do { + let j = 0; + do { + result = moveTo(i, j); + j++; + } while (!result); + i++; + } while (!result); + } else { + moveTo(row, 0); + } + break; + } + case "End": { + if (event.ctrlKey) { + let i = maxRow; + let result; + do { + let j = maxCol; + do { + result = moveTo(i, j); + j--; + } while (!result); + i--; + } while (!result); + } else { + moveTo( + row, + document.querySelector( + `[data-row="${event.target.dataset.row}"]:last-of-type`, + ).dataset.col, + ); + } + break; + } + case "PageUp": { + let i = 0; + let result; + do { + result = moveTo(i, col); + i++; + } while (!result); + break; + } + case "PageDown": { + let i = maxRow; + let result; + do { + result = moveTo(i, col); + i--; + } while (!result); + break; + } + case "Enter": { + console.log(event.target.textContent); + break; + } + } + event.preventDefault(); +}); +``` + +### More examples + +- [Data Grid Examples](https://www.w3.org/WAI/ARIA/apg/example-index/grid/dataGrids.html) +- [Layout Grids Examples](https://www.w3.org/WAI/ARIA/apg/example-index/grid/LayoutGrids.html) +- [W3C/WAI Tutorial: Tables](https://www.w3.org/WAI/tutorials/tables/) + +## Accessibility concerns + +Even if the keyboard use is properly implemented, some users might not be aware that they have to use the arrow keys. Make sure that the functionality and interaction needed can be best achieved using the grid role. + +## Specifications + +{{Specifications}} + +## See also + +- [ARIA `composite` role](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/composite_role) +- [ARIA `table` role](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/table_role) +- [ARIA `treegrid` role](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/treegrid_role) +- [ARIA `row` role](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/row_role) +- [ARIA `rowgroup` role](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/rowgroup_role) +- [ARIA: `gridcell` role](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/gridcell_role) +- [ARIA: `rowheader` role](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/rowheader_role) +- [ARIA: columnheader role](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/columnheader_role) +- {{HTMLElement('table','HTML <code>&lt;table&gt;</code> element')}} +- [`aria-level`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-level) +- [`aria-multiselectable`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-multiselectable) +- [`aria-readonly`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-readonly) diff --git a/files/en-us/web/accessibility/aria/reference/roles/gridcell_role/index.md b/files/en-us/web/accessibility/aria/reference/roles/gridcell_role/index.md new file mode 100644 index 000000000000000..c62f6fb2b93bacf --- /dev/null +++ b/files/en-us/web/accessibility/aria/reference/roles/gridcell_role/index.md @@ -0,0 +1,161 @@ +--- +title: "ARIA: gridcell role" +short-title: gridcell +slug: Web/Accessibility/ARIA/Reference/Roles/gridcell_role +page-type: aria-role +sidebar: accessibilitysidebar +--- + +The [gridcell role](https://www.w3.org/TR/wai-aria-1.1/#gridcell) is used to make a cell in a [grid](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/grid_role) or [treegrid](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/treegrid_role). It is intended to mimic the functionality of the HTML {{HTMLElement('td')}} element for table-style grouping of information. + +```html +<div role="gridcell">Potato</div> +<div role="gridcell">Cabbage</div> +<div role="gridcell">Onion</div> +``` + +Elements that have `role="gridcell"` applied to them must be the child of an element with a role of [`row`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/row_role). + +```html +<div role="row"> + <div role="gridcell">Jane</div> + <div role="gridcell">Smith</div> + <div role="gridcell">496-619-5098</div> + … +</div> +``` + +The first rule of ARIA is if a native HTML element or attribute has the semantics and behavior you require, use it instead of re-purposing an element and adding ARIA. Instead use the HTML {{HTMLElement('td')}} element: + +```html +<td>Potato</td> +<td>Cabbage</td> +<td>Onion</td> +``` + +## Description + +### gridcells with dynamically added, hidden, or removed rows and columns + +Any element with a `role="gridcell"` applied to it should use ARIA to describe its order in the table-style grouping, provided the table, grid, or treegrid has the ability to have rows and/or columns dynamically added, hidden, or removed. + +Use [`aria-colindex`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-colindex) to describe a `gridcell`'s order in the list of columns, and [`aria-rowindex`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-rowindex) to describe a gridcell's order in the list of rows. Use [`aria-colcount`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-colcount) and [`aria-rowcount`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-rowcount) on the parent element with [`role="grid"`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/grid_role) applied to it to set the total number of columns or rows. + +This sample code demonstrates a table-style grouping of information where the third and fourth columns have been removed. [`aria-colindex`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-colindex) is being used to describe the rows' position and allows a person using assistive technology to infer that certain rows have been removed: + +```html +<div role="grid" aria-colcount="6"> + <div role="rowgroup"> + <div role="row"> + <div role="columnheader" aria-colindex="1">First name</div> + <div role="columnheader" aria-colindex="2">Last name</div> + <div role="columnheader" aria-colindex="5">City</div> + <div role="columnheader" aria-colindex="6">Zip</div> + </div> + </div> + <div role="rowgroup"> + <div role="row"> + <div role="gridcell" aria-colindex="1">Debra</div> + <div role="gridcell" aria-colindex="2">Burks</div> + <div role="gridcell" aria-colindex="5">New York</div> + <div role="gridcell" aria-colindex="6">14127</div> + </div> + </div> + … +</div> +``` + +### Describing the position of gridcells when the overall structure is unknown + +In situations where the table-style grouping of content does not provide information about the columns and rows, gridcells must have their positions programmatically described by using [`aria-describedby`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-describedby). The [`id`](/en-US/docs/Web/HTML/Reference/Global_attributes/id)s provided for `aria-describedby` should correspond to parent elements intended to be the rows and columns. + +By referencing the parent elements with roles of [`rowheader`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/rowheader_role) or [`columnheader`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/columnheader_role) applied to them via `aria-describedby`, it allows assistive technology to understand the position and relationship of the `gridcell` element to the rest of the table-style grouping of content. + +### Interactive grids and treegrids + +#### Editable cells + +Both `<td>` elements and elements with a role of `gridcell` applied to them can be made editable, mimicking functionality similar to editing a spreadsheet. This is done by applying the HTML [`contenteditable` attribute](/en-US/docs/Web/HTML/Reference/Global_attributes/contenteditable). + +```html +<td contenteditable="true">Notes</td> + +<div role="gridcell" contenteditable="true">Item cost</div> +``` + +`contenteditable` will make the element it is applied to focusable via the <kbd>Tab</kbd> key. If a gridcell is conditionally toggled into a state where editing is prohibited, toggle [`aria-readonly`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-readonly) on the gridcell element. + +#### Expandable cells + +In a [treegrid](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/treegrid_role), gridcells may be made expandable by toggling the [`aria-expanded`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-expanded) attribute. Note that if this attribute is provided, it applies only to the individual gridcell. + +### Associated WAI-ARIA roles, states, and properties + +- `grid` + - : Communicates that a parent element is a table or tree style grouping of information. +- `row` + - : Required to communicate the `gridcell` is part of a row of a table-style grouping of information. +- `columnheader` + - : Specifies which element is the associated column header. +- [`aria-colindex`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-colindex) + - : Identifies the position of an element in relation to the rest of the table-style grouping of information's columns. +- `rowheader` + - : Specifies which element is the associated row header. +- [`aria-rowindex`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-rowindex) + - : Identifies the position of an element in relation to the rest of the table-style grouping of information's rows. + +### Examples + +The following example creates a table-style grouping of information: + +```html +<h3 id="table-title">Jovian gas giant planets</h3> +<div role="grid" aria-describedby="table-title"> + <div role="rowgroup"> + <div role="row"> + <div role="columnheader">Name</div> + <div role="columnheader">Diameter (km)</div> + <div role="columnheader">Length of day (hours)</div> + <div role="columnheader">Distance from Sun (10<sup>6</sup>km)</div> + <div role="columnheader">Number of moons</div> + </div> + </div> + <div role="rowgroup"> + <div role="row"> + <div role="gridcell">Jupiter</div> + <div role="gridcell">142,984</div> + <div role="gridcell">9.9</div> + <div role="gridcell">778.6</div> + <div role="gridcell">67</div> + </div> + </div> + <div role="rowgroup"> + <div role="row"> + <div role="gridcell">Saturn</div> + <div role="gridcell">120,536</div> + <div role="gridcell">10.7</div> + <div role="gridcell">1433.5</div> + <div role="gridcell">62</div> + </div> + </div> +</div> +``` + +## Accessibility concerns + +Support for `gridcell` and certain `gridcell` related ARIA roles and properties have poor support with assistive technologies. If at all possible, use [HTML table markup](/en-US/docs/Web/HTML/Reference/Elements/table) in their place. + +## Best practices + +The first rule of ARIA is: if a native HTML element or attribute has the semantics and behavior you require, use it instead of re-purposing an element and adding an ARIA role, state or property to make it accessible. As such, it is recommended to use [native HTML table markup](/en-US/docs/Web/HTML/Reference/Elements/table) instead of recreating a table's form and functionality with ARIA and JavaScript. + +## See also + +- [The Table element](/en-US/docs/Web/HTML/Reference/Elements/table) +- [ARIA: Grid role](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/grid_role) +- [The Table row element](/en-US/docs/Web/HTML/Reference/Elements/tr) +- [ARIA: row role](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/row_role) +- [ARIA: rowgroup role](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/rowgroup_role) +- [The Table header element](/en-US/docs/Web/HTML/Reference/Elements/th) +- [The Table Data Cell element](/en-US/docs/Web/HTML/Reference/Elements/td) +- [gridcell: Accessible Rich Internet Applications (WAI-ARIA) 1.1](https://www.w3.org/TR/wai-aria-1.1/#gridcell) diff --git a/files/en-us/web/accessibility/aria/reference/roles/group_role/index.md b/files/en-us/web/accessibility/aria/reference/roles/group_role/index.md new file mode 100644 index 000000000000000..2ae419dbda88f0c --- /dev/null +++ b/files/en-us/web/accessibility/aria/reference/roles/group_role/index.md @@ -0,0 +1,100 @@ +--- +title: "ARIA: group role" +short-title: group +slug: Web/Accessibility/ARIA/Reference/Roles/group_role +page-type: aria-role +spec-urls: https://w3c.github.io/aria/#group +sidebar: accessibilitysidebar +--- + +The `group` role identifies a set of user interface objects that is not intended to be included in a page summary or table of contents by assistive technologies. + +## Description + +Most closely related to HTML's {{HTMLElement('fieldset')}} element, the `group` document structure role is used to identify a set of user interface objects which, as compared to [`region`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/region_role), is not intended to be included in the page's summary or table of contents. + +The `group` role should be used to form a logical collection of items with related functionality, such as children in a [`tree`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/tree_role) widget forming a collection of siblings in a hierarchy, or a collection of items having the same container in a [`directory`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/directory_role). + +When a `group` is used in the context of [`list`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/list_role), limit the children of the `group` to [`listitem`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/listitem_role) elements. In this case, it is recommended to use multiple ordered or unordered lists, {{HTMLElement('ol')}} or {{HTMLElement('ul')}}, with nested {{HTMLElement('li')}} children. + +When used in the context of a [`listbox`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/listbox_role), the only children allowed are {{HTMLElement('option')}} elements. In this case, it is recommended to use {{HTMLElement('select')}}, {{HTMLElement('option')}} and {{HTMLElement('optgroup')}} instead. + +`Group` elements may be nested. + +The `group` role should not be used for major perceivable sections of a page. If a section is significant enough that it should be included in the page's table of contents, use the `region` role or a standard [landmark role](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles#3._landmark_roles). + +When the role is added to an element, the browser will send out an accessible group event to assistive technology products, which can then notify the user about it. + +## Examples + +The HTML code example below uses the `group` role with a `tree` view: + +```html +<div id="tree1" role="tree" tabindex="-1"> + <div + id="animals" + class="groupHeader" + role="presentation" + aria-owns="animalGroup" + aria-expanded="true"> + <img role="presentation" tabindex="-1" src="images/treeExpanded.gif" /> + <span role="treeitem" tabindex="0">Animals</span> + </div> + <div id="animalGroup" role="group"> + <div id="birds" role="treeitem"> + <span tabindex="-1">Birds</span> + </div> + <div + id="cats" + class="groupHeader" + role="presentation" + aria-owns="catGroup" + aria-expanded="false"> + <img role="presentation" tabindex="-1" src="images/treeContracted.gif" /> + <span role="treeitem" tabindex="0">Cats</span> + </div> + <div id="catGroup" role="group"> + <div id="siamese" role="treeitem"> + <span tabindex="-1">Siamese</span> + </div> + <div id="tabby" role="treeitem"> + <span tabindex="-1">Tabby</span> + </div> + </div> + </div> +</div> +``` + +The following example uses the `group` role with a drop-down [`menu`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/menu_role) containing [`menuitem`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/menuitem_role)s: + +```html +<div role="menu"> + <ul role="group"> + <li role="menuitem">Inbox</li> + <li role="menuitem">Archive</li> + <li role="menuitem">Trash</li> + </ul> + <ul role="group"> + <li role="menuitem">Custom Folder 1</li> + <li role="menuitem">Custom Folder 2</li> + <li role="menuitem">Custom Folder 3</li> + </ul> + <ul role="group"> + <li role="menuitem">New Folder</li> + </ul> +</div> +``` + +This menu could be constructed using {{HTMLElement('select')}} and {{HTMLElement('option')}} elements. In this case, the `group` role would be most similar to the {{HTMLElement('optgroup')}} element. + +## Specifications + +{{Specifications}} + +## See also + +- The {{HTMLElement('fieldset')}} Element +- [ARIA: `section` role](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/section_role) +- [ARIA: `row` role](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/row_role) +- [ARIA: `select` role](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/select_role) +- [ARIA: `toolbar` role](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/toolbar_role) diff --git a/files/en-us/web/accessibility/aria/reference/roles/heading_role/index.md b/files/en-us/web/accessibility/aria/reference/roles/heading_role/index.md new file mode 100644 index 000000000000000..c43e26e35497bc7 --- /dev/null +++ b/files/en-us/web/accessibility/aria/reference/roles/heading_role/index.md @@ -0,0 +1,115 @@ +--- +title: "ARIA: heading role" +short-title: heading +slug: Web/Accessibility/ARIA/Reference/Roles/heading_role +page-type: aria-role +spec-urls: + - https://w3c.github.io/aria/#heading + - https://www.w3.org/WAI/ARIA/apg/practices/structural-roles/#when_to_use_structural_roles +sidebar: accessibilitysidebar +--- + +The `heading` role defines this element as a heading to a page or section, with the [`aria-level`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-level) attribute providing for more structure. + +## Description + +The heading role indicates to assistive technologies that this element should be treated like a heading. Screen readers would read the text and indicate that it is formatted like a heading. In addition, the level tells assistive technologies which part of the page structure this heading represents. A level 1 heading, indicated with `aria-level="1"`, usually indicates the main heading of a page, a level 2 heading, defined with `aria-level="2"` the first subsection, a level 3 is a subsection of that, and so on. + +```html +<div role="heading" aria-level="1">This is a main page heading</div> +``` + +This defines the text in the `<div>` to be the main heading of the page, indicated by being level 1 via the `aria-level` attribute. Opt for using the {{HTMLElement("Heading_Elements", "h1")}} (through {{HTMLElement("Heading_Elements", "h6")}}) element instead. + +```html +<h1>This is a main page heading</h1> +``` + +### Associated WAI-ARIA roles, states, and properties + +- [`aria-level`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-level) + - : The `aria-level` attribute specifies the heading level in the document structure. If no level is present, a value of 2 is the default. + +### Keyboard interactions + +This role does not require any special keyboard navigation. As with any heading, giving it an ID ensures it can be referenced from anchor links, making it accessible via the keyboard. + +### Required JavaScript features + +- Required event handlers + - : None. +- Changing attribute values + - : Usually not required, unless dynamically inserting content. In that case, the newly-added headings need `aria-level` attributes whose values are consistent with the rest of the document structure. + +> [!NOTE] +> Instead of using a `<div>` or `<span>` with a `heading` role and `aria-level`, consider using a native {{HTMLElement("Heading_Elements", "h1")}} through {{HTMLElement("Heading_Elements", "h6")}} elements instead to indicate that this text is a heading, and what part of the structure it represents. + +## Examples + +The following shows a typical page structure. + +```html +<div id="container"> + <div role="heading" aria-level="1">The main page heading</div> + <p>This article is about showing a page structure.</p> + <div role="heading" aria-level="2">Introduction</div> + <p>An introductory text.</p> + <div role="heading" aria-level="2">Chapter 1</div> + <p>Text</p> + <div role="heading" aria-level="3">Chapter 1.1</div> + <p>More text in a sub section.</p> +</div> +``` + +However, instead, you should do: + +```html +<div id="container"> + <h1>The main page heading</h1> + <p>This article is about showing a page structure.</p> + <h2>Introduction</h2> + <p>An introductory text.</p> + <h2>Chapter 1</h2> + <p>Text</p> + <h3>Chapter 1.1</h3> + <p>More text in a sub section.</p> +</div> +``` + +## Accessibility concerns + +> [!WARNING] +> Using [`aria-label`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-label) or [`aria-labelledby`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-labelledby) will hide the content of your heading from assistive technologies, reading the label instead of the heading. + +If you must use the `heading` role and [`aria-level`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-level) attribute, do not go over level 6 so that you are consistent with HTML. Although theoretically you can go higher, and some screen readers may support it, the results can be unpredictable with other browser and screen reader combinations. + +## Best practices + +The best way to use this role is to **not use it at all**, and instead use the native heading tags {{HTMLElement("Heading_Elements", "h1")}} through {{HTMLElement("Heading_Elements", "h6")}} as shown in the example above. The `heading` role and `aria-level` attribute should only be used to retrofit accessibility on legacy code that you cannot make major changes to. + +Instead of using the ARIA `heading` role, use the semantic HTML element: + +| HTML Element | `heading` role | +| ----------------------------------------- | ------------------------------------- | +| {{HTMLElement("Heading_Elements", "h1")}} | `<div role="heading" aria-level="1">` | +| {{HTMLElement("Heading_Elements", "h2")}} | `<div role="heading" aria-level="2">` | +| {{HTMLElement("Heading_Elements", "h3")}} | `<div role="heading" aria-level="3">` | +| {{HTMLElement("Heading_Elements", "h4")}} | `<div role="heading" aria-level="4">` | +| {{HTMLElement("Heading_Elements", "h5")}} | `<div role="heading" aria-level="5">` | +| {{HTMLElement("Heading_Elements", "h6")}} | `<div role="heading" aria-level="6">` | + +### Added benefits + +None. + +## Specifications + +{{Specifications}} + +## Precedence order + +The heading role overrides the native semantic meaning of the element it is being used for. The `aria-level` attribute, in addition, determines what level of heading is being exposed. + +## See also + +- [`<h1>` through `<h6>`: The HTML Section Heading elements](/en-US/docs/Web/HTML/Reference/Elements/Heading_Elements) diff --git a/files/en-us/web/accessibility/aria/reference/roles/img_role/index.md b/files/en-us/web/accessibility/aria/reference/roles/img_role/index.md new file mode 100644 index 000000000000000..1a4f08f6cefdccf --- /dev/null +++ b/files/en-us/web/accessibility/aria/reference/roles/img_role/index.md @@ -0,0 +1,136 @@ +--- +title: "ARIA: img role" +short-title: img +slug: Web/Accessibility/ARIA/Reference/Roles/img_role +page-type: aria-role +spec-urls: https://w3c.github.io/aria/#img +sidebar: accessibilitysidebar +--- + +The ARIA `img` role can be used to identify multiple elements inside page content that should be considered as a single image. These elements could be images, code snippets, text, emojis, or other content that can be combined to deliver information in a visual manner. + +```html +<div role="img" aria-label="Description of the overall image"> + <img src="graphic1.png" alt="" /> + <img src="graphic2.png" /> +</div> +``` + +## Description + +Any set of content that should be consumed as a single image (which could include images, video, audio, code snippets, emojis, or other content) can be identified using `role="img"`. + +You shouldn't count on the alt text of individual images for conveying context to assistive technologies; most screen readers will consider the element with `role="img"` set on it to be like a black box, and not access the individual elements inside it. Therefore, provide a comprehensive overall descriptive alt text for image, either in the surrounding text, or by using an [`aria-label`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-label) attribute, with `alt` attributes for search engines or sighted users to be written to the page should an image fail: + +```html +<div role="img" aria-label="Description of the overall image"> + <img src="graphic1.png" alt="alternative text" /> + <img src="graphic2.png" alt="in case the images don't load" /> +</div> +``` + +If you wish to add a caption or label to your image that is visible on the page, you can do using: + +- [`aria-labelledby`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-labelledby) when the text is a concise label. +- [`aria-describedby`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-describedby) when the text is a longer description. + +For example: + +```html +<div role="img" aria-labelledby="image-1"> + … + <p id="image-1">Text that describes the group of images.</p> +</div> +``` + +If an image is purely presentational, consider using the [`presentation`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/presentation_role) role. + +### SVG and role="img" + +If you are using embedded SVG images in your page, it is a good idea to set `role="img"` on the outer {{SVGElement('svg')}} element and give it a label. This will cause screen readers to just consider it as a single entity and describe it using the label, rather than trying to read out all the child nodes: + +```html +<svg role="img" aria-label="Description of your SVG image"> + <!-- contents of the SVG image --> +</svg> +``` + +### Using role="img" to confer meaning that is obscured or implied + +In certain cases, assistive technology users won't be able to get the meaning of content expressed in certain ways, through certain media, or implied in certain ways. This is obvious to fix in the case of images (you can use the `alt` attribute), but in the case of mixed or other certain types of content it is not so obvious, and `role="img"` can come into play. + +For example, if you use emojis in your text, the meaning might be obvious to a sighted user, but someone using a screen reader might get confused because the emojis might have either no text representation at all, or the alternative text might be confusing and not match the context it is being used in. For example, take the following code: + +```html +<div role="img" aria-label="That cat is so cute"> + <p>&#x1F408; &#x1F602;</p> +</div> +``` + +`&#x1F408; &#x1F602;`, 🐈 and 😂, are entity references for emojis read out as "Cat" and "Face with tears of joy", but this doesn't necessarily make sense — the implied meaning is possibly more like "That cat is so cute", so we include that in an `aria-label` along with `role="img"`. + +This seems to work OK across some browser/screen reader combinations, but some of them end up reading the label out twice. Use with caution and test thoroughly. + +Another example where this might be suitable is when using {{Glossary("ASCII")}} emoji combinations, like the legendary "Table flip": + +```html +<div role="img" aria-label="Table flip"> + <p>(╯°□°)╯︵ ┻━┻</p> +</div> +``` + +If `aria-labelledby` were used, the screen reader would read it. In this case, only the contents of the `aria-label` are announced to screen reader users, hiding the gibberish of the characters without the need for descendant ARIA to hide things, but also hiding potential content that may be part of the image. + +### All descendants are presentational + +There are some types of user interface components that, when represented in a platform accessibility API, can only contain text. Accessibility APIs do not have a way of representing semantic elements contained in an `img`. To deal with this limitation, browsers, automatically apply role [`presentation`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/presentation_role) to all descendant elements of any `img` element as it is a role that does not support semantic children. + +For example, consider the following `img` element, which contains a heading. + +```html +<div role="img"><h3>Title of my image</h3></div> +``` + +Because descendants of `img` are presentational, the following code is equivalent: + +```html +<div role="img"><h3 role="presentation">Title of my image</h3></div> +``` + +From the assistive technology user's perspective, the heading does not exist since the previous code snippets are equivalent to the following in the [accessibility tree](/en-US/docs/Glossary/Accessibility_tree).: + +```html +<div role="img">Title of my image</div> +``` + +### Associated WAI-ARIA roles, states, and properties + +- `aria-label` or `aria-labelledby` + - : An accessible name is required. For the HTML {{HTMLElement('img')}} element, use the `alt` attribute. For all other elements with the `img` role, use `aria-labelledby` if a visible label is present, otherwise use `aria-label`. + +## Examples + +```html +<span role="img" aria-label="Rating: 4 out of 5 stars"> + <span>★</span> + <span>★</span> + <span>★</span> + <span>★</span> + <span>☆</span> +</span> +``` + +## Specifications + +{{Specifications}} + +## See also + +- The {{HTMLElement('img')}} element +- The {{SVGElement('svg')}} element +- The {{HTMLElement('picture')}} element +- The {{HTMLElement('audio')}} element +- The {{HTMLElement('video')}} element +- [ARIA: `presentation` role](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/presentation_role) +- [Accessibility Object Model](https://wicg.github.io/aom/spec/) +- [ARIA in HTML](https://w3c.github.io/html-aria/) diff --git a/files/en-us/web/accessibility/aria/reference/roles/index.md b/files/en-us/web/accessibility/aria/reference/roles/index.md new file mode 100644 index 000000000000000..c282533fcc5a5de --- /dev/null +++ b/files/en-us/web/accessibility/aria/reference/roles/index.md @@ -0,0 +1,154 @@ +--- +title: WAI-ARIA Roles +short-title: Roles +slug: Web/Accessibility/ARIA/Reference/Roles +page-type: landing-page +sidebar: accessibilitysidebar +--- + +ARIA roles provide semantic meaning to content, allowing screen readers and other tools to present and support interaction with an object in a way that is consistent with user expectations of that type of object. <abbr>ARIA</abbr> roles can be used to describe elements that don't natively exist in HTML or exist but don't yet have full browser support. + +By default, many semantic elements in HTML have a role; for example, `<input type="radio">` has the "radio" role. Non-semantic elements in HTML do not have a role; `<div>` and `<span>` without added semantics return `null`. The `role` attribute can provide semantics. + +ARIA roles are added to HTML elements using `role="role type"`, where _role type_ is the name of a role in the ARIA specification. Some roles require the inclusion of associated ARIA states or properties; others are only valid in association with other roles. + +For example, `<ul role="tabpanel">` will be announced as a 'tab panel' by screen readers. However, if the tab panel doesn't have nested tabs, the element with the tabpanel role is not in fact a tab panel and accessibility has actually been negatively impacted. + +The [ARIA states and properties](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes) associated with each role are included in the role's pages, with each attribute also having a dedicated page. + +## ARIA role types + +There are 6 categories of ARIA roles: + +### 1. Document structure roles + +Document Structure roles are used to provide a structural description for a section of content. Most of these roles should no longer be used as browsers now support semantic HTML elements with the same meaning. The roles without HTML equivalents, such as presentation, toolbar and tooltip roles, provide information on the document structure to assistive technologies such as screen readers as equivalent native HTML tags are not available. + +- [`toolbar`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/toolbar_role) +- [`tooltip`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/tooltip_role) +- [`feed`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/feed_role) +- [`math`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/math_role) +- [`presentation`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/presentation_role) / [`none`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/none_role) +- [`note`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/note_role) + +For most document structure roles, semantic HTML equivalent elements are available and supported. Avoid using: + +- [`application`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/application_role) +- [`article`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/article_role) (use {{HTMLElement('article')}}) +- [`cell`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/cell_role) (use {{HTMLElement('td')}}) +- [`columnheader`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/columnheader_role) (use `{{HTMLElement('th', '&lt;th scope="col">')}}`) +- [`definition`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/definition_role) (use {{HTMLElement('dfn')}}) +- [`directory`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/directory_role) +- [`document`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/document_role) +- [`figure`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/figure_role) (use {{HTMLElement('figure')}} instead) +- [`group`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/group_role) +- [`heading`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/heading_role) (use {{HTMLElement("Heading_Elements", "h1")}} through {{HTMLElement("Heading_Elements", "h6")}}) +- [`img`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/img_role) (use {{HTMLElement('img')}} or {{HTMLElement('picture')}} instead) +- [`list`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/list_role) (use either {{HTMLElement('ul')}} or {{HTMLElement('ol')}} instead) +- [`listitem`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/listitem_role) (use {{HTMLElement('li')}} instead) +- [`meter`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/meter_role) (use {{HTMLElement('meter')}} instead) +- [`row`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/row_role) (use the {{HTMLElement('tr')}} with {{HTMLElement('table')}}) +- [`rowgroup`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/rowgroup_role) (use {{HTMLElement('thead')}}, {{HTMLElement('tfoot')}} and {{HTMLElement('tbody')}}) +- [`rowheader`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/rowheader_role) (use `{{HTMLElement('th','&lt;th scope="row">')}}`) +- [`separator`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/separator_role) (use {{HTMLElement('hr')}} if it doesn't have focus) +- [`table`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/table_role) (use {{HTMLElement('table')}}) +- [`term`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/term_role) (use {{HTMLElement('dfn')}}) + +These are included for completeness, but in most cases are rarely, if ever, useful: + +- [`associationlist`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/structural_roles) +- [`associationlistitemkey`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/structural_roles) +- [`associationlistitemvalue`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/structural_roles) +- [`blockquote`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/structural_roles) +- [`caption`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/structural_roles) +- [`code`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/structural_roles) +- [`deletion`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/structural_roles) +- [`emphasis`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/structural_roles) +- [`insertion`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/structural_roles) +- [`paragraph`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/structural_roles) +- [`strong`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/structural_roles) +- [`subscript`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/structural_roles) +- [`superscript`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/structural_roles) +- [`time`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/structural_roles) + +### 2. Widget roles + +Widget roles are used to define common interactive patterns. Like document structure roles, some widget roles have the same semantics as well-supported native HTML elements, and therefore should be avoided. The key difference is that widget roles typically require JavaScript for interaction, while document structure roles often do not. + +- [`scrollbar`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/scrollbar_role) +- [`searchbox`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/searchbox_role) +- [`separator`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/separator_role) (when focusable) +- [`slider`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/slider_role) +- [`spinbutton`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/spinbutton_role) +- [`switch`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/switch_role) +- [`tab`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/tab_role) +- [`tabpanel`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/tabpanel_role) +- [`treeitem`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/treeitem_role) + +Avoid using [`button`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/button_role), [`checkbox`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/checkbox_role), [`gridcell`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/gridcell_role), [`link`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/link_role), [`menuitem`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/menuitem_role), [`menuitemcheckbox`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/menuitemcheckbox_role), [`menuitemradio`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/menuitemradio_role), [`option`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/option_role), [`progressbar`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/progressbar_role), [`radio`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/radio_role), and [`textbox`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/textbox_role), which we've included for completeness. For most, semantic equivalents with accessible interactivity are available and supported. See the individual role documentation for more information. + +#### Composite widget roles + +- [`combobox`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/combobox_role) +- [`menu`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/menu_role) +- [`menubar`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/menubar_role) +- [`tablist`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/tablist_role) +- [`tree`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/tree_role) +- [`treegrid`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/treegrid_role) + +Avoid using [`grid`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/grid_role), [`listbox`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/listbox_role), and [`radiogroup`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/radio_role), which we've included for completeness. See the individual role documentation for more information. + +Note that there is also a widget role (`role="widget"`), which is an abstract role and not in the widget role category. + +### 3. Landmark roles + +Landmark roles provide a way to identify the organization and structure of a web page. By classifying and labeling sections of a page, structural information conveyed visually through layout is represented programmatically. Screen readers use landmark roles to provide keyboard navigation to important sections of a page. Use these sparingly. Too many landmark roles create "noise" in screen readers, making it difficult to understand the overall layout of the page. + +- [`banner`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/banner_role) (document {{HTMLElement('header')}}) +- [`complementary`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/complementary_role) ({{HTMLElement('aside')}}) +- [`contentinfo`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/contentinfo_role) (document {{HTMLElement('footer')}}) +- [`form`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/form_role) ({{HTMLElement('form')}}) +- [`main`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/main_role) ({{HTMLElement('main')}}) +- [`navigation`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/navigation_role) ({{HTMLElement('nav')}}) +- [`region`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/region_role) ({{HTMLElement('section')}}) +- [`search`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/search_role) ({{HTMLElement('search')}}) + +### 4. Live region roles + +Live Region roles are used to define elements with content that will be dynamically changed. Sighted users can see dynamic changes when they are visually noticeable. These roles help low vision and blind users know if content has been updated. Assistive technologies, like screen readers, can be made to announce dynamic content changes: + +- [`alert`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/alert_role) +- [`log`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/log_role) +- [`marquee`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/marquee_role) +- [`status`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/status_role) +- [`timer`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/timer_role) + +### 5. Window roles + +Window roles define sub-windows to the main document window, within the same window, such as pop up modal dialogs: + +- [`alertdialog`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/alertdialog_role) +- [`dialog`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/dialog_role) + +### 6. Abstract roles + +Abstract roles are only intended for use by browsers to help organize and streamline a document. They should not be used by developers writing HTML markup. Doing so will not result in any meaningful information being conveyed to assistive technologies or to users. + +Avoid using [`command`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/command_role), [`composite`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/composite_role), [`input`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/input_role), [`landmark`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/landmark_role), [`range`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/range_role), [`roletype`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/roletype_role), [`section`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/section_role), [`sectionhead`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/sectionhead_role), [`select`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/select_role), [`structure`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/structure_role), [`widget`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/widget_role),and [`window`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/window_role). + +> [!NOTE] +> Don't use abstract roles in your sites and applications. They are for use by browsers. They are included for reference only. + +> [!WARNING] +> "Abstract roles are used for the ontology. Authors **MUST NOT** use abstract roles in content." - The <abbr>WAI-ARIA</abbr> specification + +## Roles defined on MDN + +The following are the reference pages covering the WAI-ARIA roles discussed on <abbr>MDN</abbr>. + +{{SubpagesWithSummaries}} + +## See also + +- [Using ARIA: Roles, States, and Properties](/en-US/docs/Web/Accessibility/ARIA/Guides/Techniques) +- [ARIA states and properties](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes) diff --git a/files/en-us/web/accessibility/aria/reference/roles/input_role/index.md b/files/en-us/web/accessibility/aria/reference/roles/input_role/index.md new file mode 100644 index 000000000000000..7023256b18798ea --- /dev/null +++ b/files/en-us/web/accessibility/aria/reference/roles/input_role/index.md @@ -0,0 +1,33 @@ +--- +title: "ARIA: input role" +short-title: input +slug: Web/Accessibility/ARIA/Reference/Roles/input_role +page-type: aria-role +spec-urls: https://w3c.github.io/aria/#input +sidebar: accessibilitysidebar +--- + +The `input` abstract role is a generic type of widget that allows user input. + +> [!WARNING] +> The `input` role is an [abstract role](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles#6._abstract_roles). It is included here for completeness of documentation. It is not to be used by web authors. + +## Description + +The `input` role is an abstract role. It must not be used by web authors. It is the superclass for input widgets that provide for user input, including [`checkbox`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/checkbox_role), [`radio`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/radio_role), and [`textbox`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/textbox_role). For all three, consider using the {{HTMLElement("input")}} element of type [`checkbox`](/en-US/docs/Web/HTML/Reference/Elements/input/checkbox), [`radio`](/en-US/docs/Web/HTML/Reference/Elements/input/radio) and [`text`](/en-US/docs/Web/HTML/Reference/Elements/input/text), respectively. + +## Specifications + +{{Specifications}} + +## See also + +- [ARIA: `widget` role](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/widget_role) +- [ARIA: `checkbox` role](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/checkbox_role) +- [ARIA: `combobox` role](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/combobox_role) +- [ARIA: `option` role](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/option_role) +- [ARIA: `radio` role](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/radio_role) +- [ARIA: `slider` role](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/slider_role) +- [ARIA: `spinbutton` role](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/spinbutton_role) +- [ARIA: `textbox` role](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/textbox_role) +- [HTML: the `input` element](/en-US/docs/Web/HTML/Reference/Elements/input) diff --git a/files/en-us/web/accessibility/aria/reference/roles/landmark_role/index.md b/files/en-us/web/accessibility/aria/reference/roles/landmark_role/index.md new file mode 100644 index 000000000000000..1d37c3ad6cad6d9 --- /dev/null +++ b/files/en-us/web/accessibility/aria/reference/roles/landmark_role/index.md @@ -0,0 +1,46 @@ +--- +title: "ARIA: landmark role" +short-title: landmark +slug: Web/Accessibility/ARIA/Reference/Roles/landmark_role +page-type: aria-role +spec-urls: https://w3c.github.io/aria/#landmark +sidebar: accessibilitysidebar +--- + +A landmark is an important subsection of a page. The `landmark` role is an abstract superclass for the aria role values for sections of content that are important enough that users will likely want to be able to navigate directly to them. + +> [!NOTE] +> The `landmark` role is an [abstract role](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles#6._abstract_roles). It is included here for completeness of documentation. It should not be used by web authors. + +## Description + +A `landmark` is an abstract role for a section of content that is important enough that users will likely want to be able to navigate to the section easily and have it included in a dynamically generated summary of the page. Landmarks allow assistive technologies to navigate and to find content quickly. + +To create a landmark role, define the purpose of the content by using a semantic element such as `<section>`, `<nav>`, or `<main>`, or adding an ARIA role that is a subclass of the `landmark` role such as [`role="banner"`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/banner_role), [`role="complementary"`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/complementary_role), or [`role="region"`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/region_role). Do not use `role="landmark"`. + +A visible label should be provided, referenced with [`aria-labelledby`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-labelledby). If necessary, brief, descriptive, label can be provided with [`aria-label`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-label). + +For screen reader users, adding landmark roles effectively creates 'skip links' for screen reader users, but don't replace in page navigation as the landmark roles are not otherwise surfaced. + +## Best practices + +Do not use `role="landmark"`. Do use HTML and subclass landmark roles. + +Landmarks ensure content is in navigable regions. Use {{HTMLElement('main')}} for [`role="main"`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/main_role), {{HTMLElement('header')}} for [`role="banner"`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/banner_role), {{HTMLElement('nav')}} for [`role="navigation"`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/navigation_role), and {{HTMLElement('footer')}} for [`role="contentinfo"`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/contentinfo_role). It is also good practice to include the role redundantly with the associated semantic element. It is not as good practice to use non-semantic elements, such as {{HTMLElement('div')}}, adding semantics with landmark roles. But do include one or the other or both. Otherwise, your content is no longer as navigable for screen reader users. + +## Specifications + +{{Specifications}} + +## See also + +- [ARIA: `section` role](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/section_role) +- [ARIA: `banner` role](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/banner_role) +- [ARIA: `complementary` role](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/complementary_role) +- [ARIA: `contentinfo` role](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/contentinfo_role) +- [ARIA: `form` role](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/form_role) +- [ARIA: `main` role](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/main_role) +- [ARIA: `navigation` role](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/navigation_role) +- [ARIA: `region` role](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/region_role) +- [ARIA: `search` role](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/search_role) +- [Using HTML landmark roles to improve accessibility](/en-US/blog/aria-accessibility-html-landmark-roles/) on MDN blog (2023) diff --git a/files/en-us/web/accessibility/aria/reference/roles/link_role/index.md b/files/en-us/web/accessibility/aria/reference/roles/link_role/index.md new file mode 100644 index 000000000000000..626dd147bc52b7a --- /dev/null +++ b/files/en-us/web/accessibility/aria/reference/roles/link_role/index.md @@ -0,0 +1,103 @@ +--- +title: "ARIA: link role" +short-title: link +slug: Web/Accessibility/ARIA/Reference/Roles/link_role +page-type: aria-role +spec-urls: https://w3c.github.io/aria/#link +sidebar: accessibilitysidebar +--- + +A `link` widget provides an interactive reference to a resource. The target resource can be either external or local; i.e., either outside or within the current page or application. + +> [!NOTE] +> Where possible, it is recommended that you use a native {{HTMLElement("a")}} element rather than the `link` role, as native elements are more widely supported by user agents and assistive technology. Native {{HTMLElement("a")}} elements also support keyboard and focus requirements by default, without need for additional customization. + +## Description + +The `link` role is used to identify an element that creates a hyperlink to a resource that is in the application or external. + +When not using semantic HTML for its intended purpose, interactive features must be re-implemented. For example, when `role="link"` is added to an element, the <kbd>tab</kbd> key should enable giving focus to the link and the <kbd>enter</kbd> key should execute the link when focused. + +Use the [`tabindex`](/en-US/docs/Web/HTML/Reference/Global_attributes/tabindex) attribute with a value of `0` to ensure the link is in the correct tab focus order. + +> [!WARNING] +> Applying the `link` role to an element will not cause browsers to enhance the element with standard link appearance or behaviors, such as underlining, focus rings, navigation to the link target, or context menu actions. That's the developer's responsibility. + +## Examples + +To recreate an accessible link using the `link` role on an element that is not an {{HTMLElement('a')}}, you need to ensure the link receives focus in the correct tab order, that the element looks like a link, and that the "link" behaves like a link. + +```html +<span data-href="https://mozilla.org" tabindex="0" role="link"> + Fake accessible link created using a span +</span> +``` + +### CSS + +```css +span[role="link"] { + color: blue; + text-decoration: underline; + cursor: pointer; +} +span[role="link"]:hover, +span[role="link"]:active, +span[role="link"]:focus { + color: purple; +} + +span[role="link"]:focus { + background-color: palegoldenrod; + outline: 1px dotted; +} +``` + +### JavaScript + +```js +const fakeLinks = document.querySelectorAll('[role="link"]'); + +for (const link of fakeLinks) { + link.addEventListener("click", navigateLink); + link.addEventListener("keydown", navigateLink); +} + +// handles click and keydown events on the link +function navigateLink(e) { + if (e.type === "click" || e.key === "Enter") { + const ref = e.target ?? e.srcElement; + if (ref) { + window.open(ref.getAttribute("data-href"), "_blank"); + } + } +} +``` + +If the element with `role="link"` receives an <kbd>Enter</kbd> key event, this executes the link, going to the linked page or moving focus to the in page target. + +Optionally, <kbd>Shift</kbd> + <kbd>F10</kbd> opens a context menu for the link. + +## Best practices + +The various widget roles are used to define common interactive patterns. Similar to the document-structure roles, some of these roles, including the `link` role, duplicate the semantics of native HTML elements that are well supported, and should not be used. + +Avoid using `link`, which we've included for completeness. The {{HTMLElement('a')}} semantic equivalent with accessible interactivity is available and supported. + +### Prefer HTML + +Using the {{HTMLElement('a')}} instead. + +> [!NOTE] +> There is no need to include `role="link"` on an HTML link as the `<a>`, by default, has that role already. + +## Specifications + +{{Specifications}} + +## See also + +- The {{HTMLElement('a')}} element +- The {{HTMLElement('button')}} element +- [`aria-label`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-label) +- [ARIA practices `link` role examples](https://www.w3.org/WAI/ARIA/apg/patterns/link/examples/link/) diff --git a/files/en-us/web/accessibility/aria/reference/roles/list_role/index.md b/files/en-us/web/accessibility/aria/reference/roles/list_role/index.md new file mode 100644 index 000000000000000..381d02c44891a23 --- /dev/null +++ b/files/en-us/web/accessibility/aria/reference/roles/list_role/index.md @@ -0,0 +1,78 @@ +--- +title: "ARIA: list role" +short-title: list +slug: Web/Accessibility/ARIA/Reference/Roles/list_role +page-type: aria-role +spec-urls: https://w3c.github.io/aria/#list +sidebar: accessibilitysidebar +--- + +The ARIA `list` role can be used to identify a list of items. It is normally used in conjunction with the `listitem` role, which is used to identify a list item contained inside the list. + +```html +<div role="list"> + <div role="listitem">List item 1</div> + <div role="listitem">List item 2</div> + <div role="listitem">List item 3</div> +</div> +``` + +## Description + +Any content that consists of an outer container with a list of elements inside can be identified to assistive technologies using the `list` and `listitem` containers, respectively. A `list` can only contain zero or more `listitem` children. + +There are no hard and fast rules about which elements you should use to mark up the list and list items, but you should make sure that the list items make sense in the context of a list, e.g., a shopping list, recipe steps, driving directions. + +> [!NOTE] +> Best practices dictate using the appropriate semantic HTML elements over ARIA roles to mark up lists and listitems — {{HTMLElement("ul")}}, {{HTMLElement("ol")}} and {{HTMLElement("li")}}. See [Best practices](#best_practices) for a full example. + +### Associated WAI-ARIA roles, states, and properties + +- [`listitem`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/listitem_role) role + - : A single item in a list. Elements with role `listitem` can only be found in an element with the role `list`. + +## Best practices + +Only use `role="list"` and `role="listitem"` if you have to — for example if you don't have control over your HTML but are able to improve accessibility dynamically after the fact with JavaScript. + +Unlike the HTML {{HTMLElement("ol")}} and {{HTMLElement("ul")}}, the ARIA `list` roles doesn't distinguish between ordered and unordered lists. If at all possible, you should use the appropriate semantic HTML elements to mark up a list ({{HTMLElement("ol")}} and {{HTMLElement("ul")}}) and list items ({{HTMLElement("li")}}). For example, our above example should be rewritten as follows: + +```html +<ul> + <li>List item 1</li> + <li>List item 2</li> + <li>List item 3</li> +</ul> +``` + +or use an ordered list if the order of the list items matters: + +```html +<ol> + <li>List item 1</li> + <li>List item 2</li> + <li>List item 3</li> +</ol> +``` + +> [!NOTE] +> The ARIA `list` / `listitem` roles don't distinguish between ordered and unordered lists. + +As an aside, note that if you are using the semantic HTML elements of `<ol>` or `<ul>` and apply a role of [`presentation`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/presentation_role), each child `<li>` element inherits the `presentation` role because ARIA requires the `listitem` elements to have the parent `list` element. So, the `<li>` elements are not exposed to assistive technologies, but elements contained inside of those `<li>` elements, including nested lists, are visible to assistive technologies. + +> [!NOTE] +> If you are marking up a list of items that will function as a tabbed interface, you should instead use the [`tab`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/tab_role), [`tabpanel`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/tabpanel_role), and [`tablist`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/tablist_role) roles. + +## Specifications + +{{Specifications}} + +## See also + +- The {{HTMLElement("ul")}} element +- The {{HTMLElement("ol")}} element +- The {{HTMLElement("li")}} element +- [ARIA: listitem role](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/listitem_role) +- [ARIA Lists examples](https://www.scottohara.me/blog/2018/05/26/aria-lists.html) — by Scott O'Hara +- [Accessibility Object Model](https://wicg.github.io/aom/spec/) +- [ARIA in HTML](https://w3c.github.io/html-aria/) diff --git a/files/en-us/web/accessibility/aria/reference/roles/listbox_role/index.md b/files/en-us/web/accessibility/aria/reference/roles/listbox_role/index.md new file mode 100644 index 000000000000000..2b5c53579892667 --- /dev/null +++ b/files/en-us/web/accessibility/aria/reference/roles/listbox_role/index.md @@ -0,0 +1,207 @@ +--- +title: "ARIA: listbox role" +short-title: listbox +slug: Web/Accessibility/ARIA/Reference/Roles/listbox_role +page-type: aria-role +spec-urls: + - https://w3c.github.io/aria/#listbox + - https://www.w3.org/WAI/ARIA/apg/patterns/listbox/examples/listbox-scrollable/ +sidebar: accessibilitysidebar +--- + +The `listbox` role is used for lists from which a user may select one or more items which are static and, unlike HTML {{HTMLElement('select')}} elements, may contain images. + +## Description + +The `listbox` role is used to identify an element that creates a list from which a user may select one or more static items, similar to the HTML {{HTMLElement('select')}} element. Unlike {{HTMLElement('select')}}, a listbox can contain images. Listboxes contain children whose role is [`option`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/option_role) or elements whose role is [`group`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/group_role) which in turn contain children whose role is `option`. + +It is highly recommended using the HTML select element, or a group of radio buttons if only one item can be selected, or a group of checkboxes if multiple items can be selected, because there is a lot of keyboard interactivity to manage focus for all the descendants, and native HTML elements provide this functionality for you for free. + +Elements with the role `listbox` have an implicit [`aria-orientation`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-orientation) value of `vertical`. + +When a list is tabbed to, the first item in the list will be selected if nothing else already is. Up/down arrows navigate the list, and pressing Shift + Up/Down arrows will move and extend the selection. Typing one or more letters will navigate the list items (same letter goes to each item starting with that, different letters go to the first item starting with that entire string). If the current item has an associated context menu, Shift+F10 will launch that menu. If list items are checkable, Space can be used to toggle [checkboxes](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/checkbox_role). For selectable list items, Space toggles their selection, Shift+Space can be used to select contiguous items, Ctrl+Arrow moves without selecting, and Ctrl+Space can be used to select non-contiguous items. It is recommended that a checkbox, link or other method be used to select all items, and Ctrl+A could be used as a shortcut key for this. + +When the listbox role is added to an element, or such an element becomes visible, screen readers announce the label and role of the listbox when it gets focus. If an option or item is focused within the list, it gets announced next, followed by an indication of the item's position with the list if the screen reader supports this. As focus moves within the list, the screen reader announces the relevant items. + +### Associated ARIA roles, states, and properties + +#### Associated Roles + +- [`option`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/option_role) role + - : One or more nested options are required. All selected options have [`aria-selected`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-selected) set to `true`. All options that are not selected have [`aria-selected`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-selected) set to `false`. If an option is not selectable, omit the [`aria-selected`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-selected). +- [`list`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/list_role) role + - : A section containing `listitem` elements + +#### States and Properties + +- [`aria-activedescendant`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-activedescendant) + - : Holds the `id` string of the currently active element within the listbox. If that's an option element, then that would be the `id` of the most recently interacted with option, regardless of whether that option has an [`aria-selected`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-selected) value of `true` or not. Takes the value of only one `id`, even in a multiselectable listbox. If the `id` does not refer to a DOM descendant of the listbox, then that `id` must be included among the IDs in the [`aria-owns`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-owns) attribute. +- [`aria-owns`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-owns) + + - : This is a space-separated list of element IDs which are not DOM child elements of the listbox. IDs listed here cannot also be listed in [`aria-owns`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-owns) attributes of any other elements. + +- [`aria-multiselectable`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-multiselectable) + + - : Include and set to `true` if the user can select more than one option. If set to `true`, _every_ selectable option should have an [`aria-selected`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-selected) attribute included and set to `true` or `false`. Options which are _not_ selectable _should not_ have the [`aria-selected`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-selected) attribute. If `false` or omitted, only the currently selected option, if any option is selected, needs the [`aria-selected`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-selected) attribute, and it must be set to `true`. + +- [`aria-required`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-required) + + - : A Boolean attribute which indicates that an option with a non-empty string value must be selected. + +- [`aria-readonly`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-readonly) + + - : The user cannot change which options are selected or unselected, but the listbox is otherwise operable. + +- [`aria-label`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-label) + + - : A human-readable string value which identifies the listbox. If there's a visible label, then [`aria-labelledby`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-labelledby) should be used instead to refer to that label. + +- [`aria-labelledby`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-labelledby) + + - : Identifies the visible element or elements in a space-separated list of element IDs which identify the listbox. If there's no visible label, then [`aria-label`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-label) should be used instead to include a label. (Note: "labelled", with two L's, is the correct spelling based on the accessibility API conventions.) + +- [`aria-roledescription`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-roledescription) + - : A human-readable string value which more clearly identifies the role of the listbox. Screen readers will often read this value to the user after reading the label (if there is one), in place of saying "listbox". + +### Keyboard interactions + +- When a single-select listbox receives focus: + + - If none of the options are selected before the listbox receives focus, the first option receives focus. Optionally, the first option may be automatically selected. + - If an option is selected before the listbox receives focus, focus is set on the selected option. + +- When a multi-select listbox receives focus: + + - If none of the options are selected before the listbox receives focus, focus is set on the first option and there is no automatic change in the selection state. + - If one or more options are selected before the listbox receives focus, focus is set on the first option in the list that is selected. + +- <kbd>Down Arrow</kbd> + + : Moves focus to the next option. Optionally, in a single-select listbox, selection may also move with focus. + +- <kbd>Up Arrow</kbd> + + : Moves focus to the previous option. Optionally, in a single-select listbox, selection may also move with focus. + +- <kbd>Home</kbd> + + (Optional): Moves focus to first option. Optionally, in a single-select listbox, selection may also move with focus. Supporting this key is strongly recommended for lists with more than five options. + +- <kbd>End</kbd> + + (Optional): Moves focus to last option. Optionally, in a single-select listbox, selection may also move with focus. Supporting this key is strongly recommended for lists with more than five options. + +- Type-ahead is recommended for all listboxes, especially those with more than seven options: + + - Type a character: focus moves to the next item with a name that starts with the typed character. + - Type multiple characters in rapid succession: focus moves to the next item with a name that starts with the string of characters typed. + +- **Multiple Selection**: Authors may implement either of two interaction models to support multiple selection: a recommended model that does not require the user to hold a modifier key, such as <kbd>Shift</kbd> or <kbd>Control</kbd>, while navigating the list or an alternative model that does require modifier keys to be held while navigating in order to avoid losing selection states. + + - Recommended selection model — holding modifier keys is not necessary: + + - <kbd>Space</kbd>: changes the selection state of the focused option. + - <kbd>Shift + Down Arrow</kbd> (Optional): Moves focus to and toggles the selected state of the next option. + - <kbd>Shift + Up Arrow</kbd> (Optional): Moves focus to and toggles the selected state of the previous option. + - <kbd>Shift + Space</kbd> (Optional): Selects contiguous items from the most recently selected item to the focused item. + - <kbd>Control + Shift + Home</kbd> (Optional): Selects the focused option and all options up to the first option. Optionally, moves focus to the first option. + - <kbd>Control + Shift + End</kbd> (Optional): Selects the focused option and all options down to the last option. Optionally, moves focus to the last option. + - <kbd>Control + A</kbd> (Optional): Selects all options in the list. Optionally, if all options are selected, it may also unselect all options. + +### Required JavaScript features + +#### selecting an option in a single select listbox + +When the user selects an option, the following must occur: + +1. Deselect the previously selected option, setting the [`aria-selected`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-selected) to `false`, or removing the attribute altogether, changing the appearance of the newly unselected option to appear not selected. +2. Select the newly selected option, setting `aria-selected="true"` on the option and changing the appearance of the newly selected option to appear selected. +3. Update the [`aria-activedescendant`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-activedescendant) value on the listbox to the id of the newly selected option +4. Visually handle the blur, focus, and selected states of the option + +#### Toggling the state of an option in a multi select listbox + +When the user clicks on an option, hits <kbd>Space</kbd> when focused on an option, or otherwise toggles the state of an option, the following must occur: + +1. Toggle the [`aria-selected`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-selected) state of the currently focused option, changing the state of the `aria-selected` to true if it was false or false if it was true. +2. Change the appearance of the option to reflect its selected state +3. Update the [`aria-activedescendant`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-activedescendant) value on the listbox to the ID of the option the user just interacted with, even if they toggled the option to be unselected. + +> [!NOTE] +> The first rule of ARIA use is you can use a native feature with the semantics and behavior you require already built in, instead of re-purposing an element and **adding** an ARIA role, state or property to make it accessible, then do so. The {{HTMLElement('select')}} element with descendant {{HTMLElement('option')}} elements handles all the needed interactions natively. + +## Examples + +### Example 1: A single select listbox that uses `aria-activedescendant` + +The snippet below, using [`aria-activedescendant`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-activedescendant), shows how the listbox role is added directly into the HTML source code. + +```html +<p id="listbox1label" role="label">Select a color:</p> +<div + role="listbox" + tabindex="0" + id="listbox1" + aria-labelledby="listbox1label" + aria-activedescendant="listbox1-1"> + <div role="option" id="listbox1-1" class="selected" aria-selected="true"> + Green + </div> + <div role="option" id="listbox1-2">Orange</div> + <div role="option" id="listbox1-3">Red</div> + <div role="option" id="listbox1-4">Blue</div> + <div role="option" id="listbox1-5">Violet</div> + <div role="option" id="listbox1-6">Periwinkle</div> +</div> +``` + +```js +const listbox = document.getElementById("listbox1"); +listbox.addEventListener("click", listItemClick); +listbox.addEventListener("keydown", listItemKeyEvent); +listbox.addEventListener("keypress", listItemKeyEvent); +``` + +This could have more easily been handled with the native HTML {{HTMLElement('select')}} and {{HTMLElement('label')}} elements. + +```html +<label for="listbox1">Select a color:</label> +<select id="listbox1"> + <option selected>Green</option> + <option>Orange</option> + <option>Red</option> + <option>Blue</option> + <option>Violet</option> + <option>Periwinkle</option> +</select> +``` + +### More examples + +- [Scrollable Listbox Example](https://www.w3.org/WAI/ARIA/apg/patterns/listbox/examples/listbox-scrollable/): Single-select listbox that scrolls to reveal more options, similar to HTML {{HTMLElement('select')}} with `size` attribute greater than one. +- [Listbox Example with Grouped Options](https://www.w3.org/WAI/ARIA/apg/patterns/listbox/examples/listbox-grouped/): Single-select listbox with grouped options, similar to HTML {{HTMLElement('select')}} with the attribute `size` set to greater than `"1"` and options grouped with `optgroup` elements. +- [Example Listboxes with Rearrangeable Options](https://www.w3.org/WAI/ARIA/apg/patterns/listbox/examples/listbox-rearrangeable/): Examples of both single-select and multi-select listboxes with accompanying toolbars where options can be added, moved, and removed. + +## Best practices + +- To be keyboard-accessible, authors should [manage focus](https://www.w3.org/TR/wai-aria-1.1/#managingfocus) of all descendants of this role. +- It is recommended that authors use different styling for the selection when the list is not focused, e.g., a non-active selection is often shown with a lighter background color. +- If the listbox is not part of another widget, it should have the [`aria-labelledby`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-labelledby) property set. +- If one or more entries are not DOM children of listbox, additional `aria-*` properties will need to be set (see [ARIA Best Practices](https://www.w3.org/WAI/ARIA/apg/patterns/listbox/)). +- If there is a valid reason to [expand](https://www.w3.org/TR/wai-aria-1.1/#aria-expanded) the listbox, the [`combobox`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/combobox_role) role may be more appropriate. + +## Specifications + +{{Specifications}} + +## See also + +- HTML {{HTMLElement('select')}} element +- HTML {{HTMLElement('label')}} element +- HTML {{HTMLElement('option')}} element +- [ARIA: `combobox` role](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/combobox_role) +- [ARIA: `option` role](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/option_role) +- [ARIA: `list` role](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/list_role) +- [ARIA: `listitem` role](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/listitem_role) +- [ARIA Best Practices – Listbox](https://www.w3.org/WAI/ARIA/apg/patterns/listbox/) +- [ARIA Role Model – Listbox](https://www.w3.org/TR/wai-aria-1.1/#listbox) diff --git a/files/en-us/web/accessibility/aria/reference/roles/listitem_role/index.md b/files/en-us/web/accessibility/aria/reference/roles/listitem_role/index.md new file mode 100644 index 000000000000000..b5edc434b42e0bc --- /dev/null +++ b/files/en-us/web/accessibility/aria/reference/roles/listitem_role/index.md @@ -0,0 +1,82 @@ +--- +title: "ARIA: listitem role" +short-title: listitem +slug: Web/Accessibility/ARIA/Reference/Roles/listitem_role +page-type: aria-role +spec-urls: https://w3c.github.io/aria/#listitem +sidebar: accessibilitysidebar +--- + +The ARIA `listitem` role can be used to identify an item inside a list of items. It is normally used in conjunction with the [`list`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/list_role) role, which is used to identify a list container. + +```html +<section role="list"> + <div role="listitem">List item 1</div> + <div role="listitem">List item 2</div> + <div role="listitem">List item 3</div> +</section> +``` + +## Description + +Any content that consists of an outer container with a list of elements inside it can be identified to assistive technologies using the `list` and `listitem` containers respectively. + +There are no hard and fast rules about which elements you should use to mark up the list and list items, but you should make sure that the list items make sense in the context of a list, e.g., a shopping list, recipe steps, driving directions. + +> [!NOTE] +> If at all possible in your work, you should use the appropriate semantic HTML elements to mark up a list and its listitems — {{HTMLElement("ul")}}/{{HTMLElement("ol")}} and {{HTMLElement("li")}}. See [Best practices](#best_practices) for a full example. + +### Associated WAI-ARIA Roles, States, and Properties + +- [`list`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/list_role) + - : A list of items. Elements with role `list` must have one or more elements with the role `listitem` as children, a one or more elements with the role of `group` that have one or more elements with the `listitem` role as children. +- [`group`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/group_role) + - : A collection of related objects, limited to list items when nested in a list, not important enough to have their own place in a pages table of contents. + +## Best practices + +Only use `role="list"` and `role="listitem"` if you have to — for example if you don't have control over your HTML but are able to improve accessibility dynamically after the fact with JavaScript. + +If at all possible, you should use the appropriate semantic HTML elements to mark up a list and listitems — {{HTMLElement("ol")}}, {{HTMLElement("ul")}} and {{HTMLElement("li")}}. For example, our above example should be rewritten as follows: + +```html +<ul> + <li>List item 1</li> + <li>List item 2</li> + <li>List item 3</li> +</ul> +``` + +or use an ordered list if the order of the list items matters: + +```html +<ol> + <li>List item 1</li> + <li>List item 2</li> + <li>List item 3</li> +</ol> +``` + +> [!NOTE] +> The ARIA `list` / `listitem` roles don't distinguish between ordered and unordered lists. + +> [!NOTE] +> Styling a list with `list-style: none;` in CSS removes the list semantics. Adding `role="listitem"` returns the semantics. + +> [!NOTE] +> If you are marking up a list of items that will function as a tabbed interface, you should instead use the [`tab`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/tab_role), [`tabpanel`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/tabpanel_role), and [`tablist`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/tablist_role) roles. + +## Specifications + +{{Specifications}} + +## See also + +- [HTML `<li>` element](/en-US/docs/Web/HTML/Reference/Elements/li) +- [HTML `<ul>` element](/en-US/docs/Web/HTML/Reference/Elements/ul) +- [HTML `<ol>` element](/en-US/docs/Web/HTML/Reference/Elements/ol) +- [ARIA: `list` role](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/list_role) +- [ARIA: `group` role](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/group_role) +- [Accessibility Object Model](https://wicg.github.io/aom/spec/) +- [ARIA in HTML](https://w3c.github.io/html-aria/) +- [ARIA Lists examples](https://www.scottohara.me/blog/2018/05/26/aria-lists.html) — by Scott O'Hara diff --git a/files/en-us/web/accessibility/aria/reference/roles/log_role/index.md b/files/en-us/web/accessibility/aria/reference/roles/log_role/index.md new file mode 100644 index 000000000000000..cf2cf9f16b7cb6b --- /dev/null +++ b/files/en-us/web/accessibility/aria/reference/roles/log_role/index.md @@ -0,0 +1,48 @@ +--- +title: "ARIA: log role" +short-title: log +slug: Web/Accessibility/ARIA/Reference/Roles/log_role +page-type: aria-role +spec-urls: https://w3c.github.io/aria/#log +sidebar: accessibilitysidebar +--- + +The `log` role is used to identify an element that creates a [live region](/en-US/docs/Web/Accessibility/ARIA/Guides/Live_regions) where new information is added in a meaningful order and old information may disappear. + +## Description + +A log is a type of live region where new information is added in meaningful order and old information may disappear. Examples include chat logs, messaging history, game log, or an error log. In contrast to other live regions, in this role there is a relationship between the arrival of new items in the log and the reading order. The log contains a meaningful sequence and new information is added only to the end of the log, not at arbitrary points. + +In contrast to other types of live region, a log is sequentially ordered and new information is only added to the end of the log. When this role is added to an element, the browser will send out an accessible log event to assistive technology products which can then notify the user about it. + +By default, updates contain only the changes to the live region and these are announced when the user is idle. Elements with the role `log` have an implicit `aria-live` value of `polite`. Where the user needs to hear the entire live region upon a change `aria-atomic="true"` should be set. To have announcements made as soon as possible and where the user may be interrupted, `aria-live="assertive"` can be set for more aggressive updates. + +### Associated WAI-ARIA roles, states, and properties + +- `aria-atomic` + + - : Defines whether assistive technologies should present all, or only parts of, the changed region. Elements with the role `log` have an implicit [aria-atomic](https://www.w3.org/TR/wai-aria-1.1/#aria-atomic) value of `false`. + +- `aria-live` + + - : Defines when assistive technology should inform the user of updates to content. Elements with the role `log` have an implicit [aria-live](https://www.w3.org/TR/wai-aria-1.1/#aria-live) value of `polite`, meaning screen readers will announce changes inside the log when the user is idle. + +- `aria-label` and `aria-labelledby` + + - : The `log` is required to have an accessible name. Use `aria-labelledby` if a visible label is present, otherwise use `aria-label`. + +## Best practices + +With an area that has scrolling text, such as a stock ticker, the [`marquee`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/marquee_role) role should be used instead. + +## Specifications + +{{Specifications}} + +## See also + +- [ARIA: `alert` role](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/alert_role) +- [ARIA: `marquee` role](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/marquee_role) +- [ARIA: `status` role](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/status_role) +- [ARIA: `timer` role](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/timer_role) +- [ARIA live regions](/en-US/docs/Web/Accessibility/ARIA/Guides/Live_regions) diff --git a/files/en-us/web/accessibility/aria/reference/roles/main_role/index.md b/files/en-us/web/accessibility/aria/reference/roles/main_role/index.md new file mode 100644 index 000000000000000..d50fa6026ecd8da --- /dev/null +++ b/files/en-us/web/accessibility/aria/reference/roles/main_role/index.md @@ -0,0 +1,130 @@ +--- +title: "ARIA: main role" +short-title: main +slug: Web/Accessibility/ARIA/Reference/Roles/main_role +page-type: aria-role +spec-urls: + - https://w3c.github.io/aria/#main + - https://www.w3.org/WAI/ARIA/apg/patterns/landmarks/examples/main.html +sidebar: accessibilitysidebar +--- + +The `main` landmark role is used to indicate the primary content of a document. The main content area consists of content that is directly related to or expands upon the central topic of a document, or the main function of an application. + +```html +<div id="main" role="main"> + <h1>Avocados</h1> + <!-- main section content --> +</div> +``` + +This is the main section of a document that discusses avocados. Subsections of this document could discuss their history, the different types, regions where they grow, etc. + +## Description + +The `main` role is a navigational [landmark](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles#3._landmark_roles) role identifying the main content of a document. Landmarks can be used by assistive technology such as screen readers to quickly identify and navigate to large sections of the document. + +By classifying and labeling sections of a page, structural information conveyed visually through layout can be represented programmatically. Screen readers use landmark roles to provide keyboard navigation to important sections of a page. For those navigating via landmark roles, the main role is an alternative for "skip to main content" links. + +There should only be one `main` landmark role per document. + +The {{HTMLElement('main')}} element has a role of `main`. Developers should use semantic HTML — in this case {{HTMLElement('main')}} — over using ARIA. + +### Associated ARIA roles, states, and properties + +- [`aria-owns`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-owns) + + - : The `aria-owns` attribute establishes relationships in the accessibility layer that aren't present in the DOM. Documents and applications can be nested in the DOM, which may lead to having more than one main element as DOM descendants. If this is the case, include `aria-owns` to identify the relationship of the main to its document or application ancestor. + +- [`aria-label`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-label) or `aria-labelledby` + + - : Identify the accessible name with [`aria-labelledby`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-labelledby) if a visible header is present. Otherwise, including an [`aria-label`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-label) can be helpful for orienting assistive technology users, especially in single-page applications where main content changes happen without generating a page load event. + +## Example + +```html +<body> + <!-- primary navigation --> + + <div role="main"> + <h1>The First Indochina War</h1> + <!-- article content --> + </div> + + <!-- sidebar and footer --> +</body> +``` + +## Accessibility concerns + +### Use only one `main` role per document + +The `main` [landmark role](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles#3._landmark_roles) should only be used once per document. + +If a document contains two `main` roles, say updating page content when triggered by JavaScript, the inactive `main` role's presence should be removed from assistive technology via techniques such as toggling the [`hidden` attribute](/en-US/docs/Web/HTML/Reference/Global_attributes/hidden). + +```html +<main> + <h1>Active `main` element</h1> + <!-- content --> +</main> + +<main hidden> + <h1>Hidden `main` element</h1> + <!-- content --> +</main> +``` + +It is also helpful to include an accessible name to help orient assistive technology users, especially in single-page applications where main content changes happen without generating a page load event. This can be added with `aria-labelledby` if there is an appropriate name in the content, or `aria-label` if not. + +## Best practices + +### Prefer HTML + +Using the {{HTMLElement('main')}} element will automatically communicate a section has a role of `main`. If at all possible, prefer using it instead. + +### Skip navigation + +Skip navigation, also known as "skipnav", is a technique that allows an assistive technology user to quickly bypass large sections of repeated content (main navigation, info banners, etc.). This allows the user to access the main content of the page faster. + +Adding an [`id` attribute](/en-US/docs/Web/HTML/Reference/Global_attributes/id) to the element with a declaration of `role="main"` allows it to be a target of a skip navigation link users. + +```html +<body> + <a href="#main-content">Skip to main content</a> + + <!-- navigation and header content --> + + <div id="main-content" role="main"> + <!-- main page content --> + </div> +</body> +``` + +Which is the equivalent of: + +```html +<body> + <a href="#main-content">Skip to main content</a> + + <!-- navigation and header content --> + + <main id="main-content"> + <!-- main page content --> + </main> +</body> +``` + +- [WebAIM: "Skip Navigation" Links](https://webaim.org/techniques/skipnav/) + +## Specifications + +{{Specifications}} + +## See also + +- The {{HTMLElement('main')}} element +- [Using HTML sections and outlines](/en-US/docs/Web/HTML/Reference/Elements/Heading_Elements) +- [Using WAI-ARIA Landmarks – 2013 | The Paciello Group](https://www.tpgi.com/using-wai-aria-landmarks-2013/) +- [Accessible Landmarks | scottohara.me](https://www.scottohara.me/blog/2018/03/03/landmarks.html) +- [The main element | HTML5 Doctor](https://html5doctor.com/the-main-element/) diff --git a/files/en-us/web/accessibility/aria/reference/roles/mark_role/index.md b/files/en-us/web/accessibility/aria/reference/roles/mark_role/index.md new file mode 100644 index 000000000000000..c6b943d2db4962d --- /dev/null +++ b/files/en-us/web/accessibility/aria/reference/roles/mark_role/index.md @@ -0,0 +1,55 @@ +--- +title: "ARIA: mark role" +short-title: mark +slug: Web/Accessibility/ARIA/Reference/Roles/mark_role +page-type: aria-role +sidebar: accessibilitysidebar +--- + +The `mark` role denotes content which is marked or highlighted for reference or notation purposes, due to the content's relevance in the enclosing context. + +## Description + +The `mark` role semantically denotes HTML elements containing text that is marked/highlighted for reference purposes. This is semantically equivalent to the HTML {{HTMLElement('mark')}} element. If possible, you should use this element instead. + +Example uses for `mark` are the exact same as the `<mark>` element. They include highlighting text in a quotation which is of special interest but is not marked in the original source material, comparable to using a highlighter pen to mark passages of a print article and indicating portions of the content that are relevant to the user's current activity, such as highlighting text matches found by a search feature. + +Don't use `mark` for purely decorative styling such as syntax highlighting. + +The `mark` element should not be given an accessible name; both [`aria-label`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-label) and [`aria-labelledby`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-labelledby) attributes are prohibited on `mark`. + +## Examples + +In the following example we have a document section that has been commented. The commented section is marked up using `<span role="mark">`. + +```html +<p> + The last half of the song is a slow-rising crescendo that peaks at the + <span role="mark" aria-details="thread-1">end of the guitar solo</span>, + before fading away sharply. +</p> + +<div role="comment" id="thread-1" data-author="chris"> + <h3>Chris said</h3> + <p class="comment-text">I really think this moment could use more cowbell.</p> + <p><time datetime="2022-03-30T19:29">March 30 2022, 19:29</time></p> +</div> +``` + +The related comment is marked up using an HTML structure wrapped with a {{HTMLElement('div')}} containing [`role="comment"`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/comment_role). + +To associate the comment with the text being commented, we need to wrap the commented text with an element containing the [`aria-details`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-details) attribute, the value of which should be the ID of the comment. + +## Best practices + +### Prefer HTML + +Using the {{HTMLElement('mark')}} element will automatically communicate a node has a role of `mark`. If at all possible, prefer using it instead. + +## Specifications + +Will be part of [WAI-ARIA 1.3](https://w3c.github.io/aria/#mark), which is still being drafted. + +## See also + +- HTML {{HTMLElement('mark')}} element diff --git a/files/en-us/web/accessibility/aria/reference/roles/marquee_role/index.md b/files/en-us/web/accessibility/aria/reference/roles/marquee_role/index.md new file mode 100644 index 000000000000000..d238e7c3af668ec --- /dev/null +++ b/files/en-us/web/accessibility/aria/reference/roles/marquee_role/index.md @@ -0,0 +1,40 @@ +--- +title: "ARIA: marquee role" +short-title: marquee +slug: Web/Accessibility/ARIA/Reference/Roles/marquee_role +page-type: aria-role +spec-urls: https://w3c.github.io/aria/#marquee +sidebar: accessibilitysidebar +--- + +A `marquee` is a type of [live region](/en-US/docs/Web/Accessibility/ARIA/Guides/Live_regions) containing non-essential information which changes frequently. + +## Description + +The `marquee` role defines an area as a type of live region that presents non-essential information that changes frequently. Examples of marquees include stock tickers and ad banners; information that is not necessarily sought out by the user that may be presented in any order. The main difference between a `marquee` and a [`log`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/log_role) is that log information is presented in a meaningful order such as a by date. + +Elements with the role marquee have an implicit [aria-live](/en-US/docs/Web/Accessibility/ARIA/Guides/Live_regions) value of `off`. + +The marquee is required to have an accessible name. Use [`aria-labelledby`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-labelledby) if a visible label is present, otherwise use [`aria-label`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-label). + +### Associated WAI-ARIA roles, states, and properties + +- [`aria-live`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-live) + + - : Defines when assistive technology should inform the user of updates to content. Elements with the role `marquee` have an implicit [aria-live](https://www.w3.org/TR/wai-aria-1.1/#aria-live) value of `off`, meaning screen readers will not announce changes inside the marquee, even when the user is idle. + +- [`aria-label`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-label) or [`aria-labelledby`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-labelledby) + + - : The `marquee` is required to have an accessible name. Use `aria-labelledby` if a visible label is present, otherwise use `aria-label`. + +## Specifications + +{{Specifications}} + +## See also + +- [ARIA: `alert` role](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/alert_role) +- [ARIA: `log` role](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/log_role) +- [ARIA: `status` role](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/status_role) +- [ARIA: `timer` role](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/timer_role) +- [ARIA live regions](/en-US/docs/Web/Accessibility/ARIA/Guides/Live_regions) diff --git a/files/en-us/web/accessibility/aria/reference/roles/math_role/index.md b/files/en-us/web/accessibility/aria/reference/roles/math_role/index.md new file mode 100644 index 000000000000000..68bf8d3615f11cb --- /dev/null +++ b/files/en-us/web/accessibility/aria/reference/roles/math_role/index.md @@ -0,0 +1,50 @@ +--- +title: "ARIA: math role" +short-title: math +slug: Web/Accessibility/ARIA/Reference/Roles/math_role +page-type: aria-role +spec-urls: https://w3c.github.io/aria/#math +sidebar: accessibilitysidebar +--- + +The `math` role indicates that the content represents a mathematical expression. + +## Description + +Content with the role `math` is intended to be marked up in an accessible format such as [MathML](/en-US/docs/Web/MathML), or with another type of textual representation, which can be converted to an accessible format by the browser or a polyfill library. + +Unfortunately, browser support for MathML is not universal. While using an image of a mathematical expression is not optimal, if you do use image, use the `math` role. +Make sure any images of math are labeled by an `alt` attribute that describes the mathematical expression as it would be spoken. + +If the math element has only presentational children and the accessible name is intended to convey the mathematical expression, use [`aria-label`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-label) to provide a string that represents the expression. If the math element contains navigable content that conveys the mathematical expression and a visible label for the expression is present, use [`aria-labelledby`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-labelledby). Otherwise, use `aria-label` to name the expression, e.g., `aria-label="Pythagorean Theorem"`. + +## Examples + +If you use image or non-semantic HTML to create an equation, use the `math` role. + +<div role="math" aria-label="a^{2} + b^{2} = c^{2}"> + a<sup>2</sup> + b<sup>2</sup> = c<sup>2</sup> +</div> + +The above pythagorean theorem is written accessibly as: + +```html +<div role="math" aria-label="a^{2} + b^{2} = c^{2}"> + a<sup>2</sup> + b<sup>2</sup> = c<sup>2</sup> +</div> +``` + +Had an image been used, the `alt` attribute would be used along with the `math` role: + +```html +<img src="pythagorean_theorem.gif" alt="a^{2} + b^{2} = c^{2}" role="math" /> +``` + +## Specifications + +{{Specifications}} + +## See also + +- [MathML on MDN](/en-US/docs/Web/MathML) and the [`<math>`](/en-US/docs/Web/MathML/Reference/Element/math) element (not HTML) +- [The MathML specification](https://www.w3.org/TR/MathML3/) diff --git a/files/en-us/web/accessibility/aria/reference/roles/menu_role/index.md b/files/en-us/web/accessibility/aria/reference/roles/menu_role/index.md new file mode 100644 index 000000000000000..16bd1c2edcff1ed --- /dev/null +++ b/files/en-us/web/accessibility/aria/reference/roles/menu_role/index.md @@ -0,0 +1,195 @@ +--- +title: "ARIA: menu role" +short-title: menu +slug: Web/Accessibility/ARIA/Reference/Roles/menu_role +page-type: aria-role +spec-urls: + - https://w3c.github.io/aria/#menu + - https://www.w3.org/WAI/ARIA/apg/patterns/menubar/examples/menubar-navigation/ +sidebar: accessibilitysidebar +--- + +The `menu` role is a type of composite widget that offers a list of choices to the user. + +## Description + +A `menu` generally represents a grouping of common actions or functions that the user can invoke. The `menu` role is appropriate when a list of menu items is presented in a manner similar to a menu on a desktop application. Submenus, also known as pop-up menus, also have the role `menu`. + +While the term "menu" is a generically used term to describe site navigation, the `menu` role is for a list of actions or functions that require complex functionality, such as composite widget focus management and first-character navigation + +A menu can be a permanently visible list of controls or a widget that can be made to open and close. A closed `menu` widget is usually opened, or made visible, by activating a menu button, choosing an item in a menu that opens a submenu, or by invoking a command, such as <kbd>Shift + F10</kbd> in Windows which opens a context specific menu. + +When a user activates a choice in a menu that has been opened, the menu usually closes. If the menu choice action invokes a submenu, the menu will remain open and the submenu is displayed. + +When a menu opens, keyboard focus is placed on the first menu item. To be keyboard accessible, you need to [manage focus](https://usability.yale.edu/web-accessibility/articles/focus-keyboard-operability) for all descendants: all menu items within the `menu` are focusable. The menu button which opens the menu and the menu items, rather than the menu itself, are the focusable elements. + +Menu items include [`menuitem`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/menuitem_role), [`menuitemcheckbox`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/menuitemcheckbox_role), and [`menuitemradio`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/menuitemradio_role). [Disabled](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-disabled) menu items are focusable but cannot be activated. + +Menu items can be grouped in elements with the [`group`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/group_role) role, and separated by elements with role [`separator`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/separator_role). Neither `group` nor `separator` receive focus or are interactive. + +If a `menu` is opened as a result of a context action, <kbd>Escape</kbd> or <kbd>Enter</kbd> may return focus to the invoking context. If focus was on the menu button, <kbd>Enter</kbd> opens the menu, giving focus to the first menu item. If focus is on the menu itself, <kbd>Escape</kbd> closes the menu and returns focus to the menu button or parent menubar item (or the context action that opened the menu). + +Elements with the role `menu` have an implicit [`aria-orientation`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-orientation) value of `vertical`. For horizontally oriented menu, use [`aria-orientation="horizontal"`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-orientation). + +If the menu is visually persistent, consider the [`menubar`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/menubar_role) role instead. + +### Associated WAI-ARIA roles, states, and properties + +- [`menuitem`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/menuitem_role), [`menuitemcheckbox`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/menuitemcheckbox_role), and [`menuitemradio`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/menuitemradio_role) roles + - : Roles of items contained in a containing `menu` or `menubar`, known collectively as "menu items". These must be able to receive focus. +- [`group`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/group_role) role + - : Menu items can be nested in a [`group`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/group_role) +- [`separator`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/separator_role) role + + - : A divider that separates and distinguishes sections of content or groups of menu items within the menu + +- [`tabindex`](/en-US/docs/Web/HTML/Reference/Global_attributes/tabindex) attribute + - : The `menu` container has `tabindex` set to `-1` or `0` and each item in the menu has `tabindex` set to `-1`. +- [`aria-activedescendant`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-activedescendant) + - : Set to the ID of the focused item, if there is one. +- [`aria-orientation`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-orientation) + - : indicates whether the menu orientation is horizontal or vertical; defaults to `vertical` if omitted. +- [`aria-label`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-label) or [`aria-labelledby`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-labelledby) + - : The `menu` is required to have an accessible name. Use `aria-labelledby` if a visible label is present, otherwise use `aria-label`. Either include the `aria-labelledby` set to a the `id` to the `menuitem` or `button` that controls its display or use `aria-label` to define the label. +- [`aria-owns`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-owns) + - : Only set on the menu container to include elements that are not DOM children of the container. If set, those elements will appear in the reading order in the sequence they are referenced and after any items that are DOM children. When managing focus, ensure the visual focus order matches this assistive technology reading order. + +### Keyboard interactions + +- <kbd>Space</kbd> / <kbd>Enter</kbd> + - : If the item is a parent menu item, it opens the submenu and moves focus to the first item in the submenu. Otherwise, activates the menu item, which loads new content and places focus on the heading that titles the content. +- <kbd>Escape</kbd> + - : When in a submenu, it closes the submenu and moves focus to the parent menu or menubar item. +- <kbd>Right Arrow</kbd> + - : In a menubar, moves focus to the next item in the menubar. If focus is on the last item, it moves focus to the first item. If in a submenu, if focus is on an item that does not have a submenu, it closes the submenu and moves focus to the next item in the menubar. Otherwise, it opens the submenu of the newly focused menubar item, keeping focus on that parent menubar item. If not in a menubar or submenu and not on a `menuitem` with a submenu, if focus is not the last focusable element in the menu, it optionally moves focus to the next focusable element. +- <kbd>Left Arrow </kbd> + - : Moves focus to the previous item in the menubar. If focus is on the first item, it moves focus to the last item. If in a submenu, it closes the submenu and moves focus to the parent menu item. If not in a menubar or submenu, if focus is not the first focusable element in the menu, it optionally moves focus to the last focusable element. +- <kbd>Down Arrow</kbd> + - : Opens submenu and moves focus to the first item in the submenu. +- <kbd>Up Arrow</kbd> + - : Opens submenu and moves focus to the last item in the submenu. +- <kbd>Home</kbd> + - : Moves focus to the first item in the menubar. +- <kbd>End</kbd> + - : Moves focus to the last item in the menubar. +- Any character key + - : Moves focus to the next item in the menubar having a name that starts with the typed character. If none of the items have a name starting with the typed character, focus does not move. + +## Examples + +Below are two example menu implementations. + +### Example 1: navigation menu + +```html +<div> + <button id="menubutton" aria-haspopup="true" aria-controls="menu"> + <img src="hamburger.svg" alt="Page Sections" /> + </button> + <ul id="menu" role="menu" aria-labelledby="menubutton"> + <li role="presentation"> + <a role="menuitem" href="#description">Description</a> + </li> + <li role="presentation"> + <a + role="menuitem" + href="#associated_wai-aria_roles_states_and_properties"> + Associated WAI-ARIA roles, states, and properties + </a> + </li> + <li role="presentation"> + <a role="menuitem" href="#keyboard_interactions"> + Keyboard interactions + </a> + </li> + <li role="presentation"> + <a role="menuitem" href="#examples">Examples</a> + </li> + <li role="presentation"> + <a role="menuitem" href="#specifications">Specifications</a> + </li> + <li role="presentation"> + <a role="menuitem" href="#see_also">See Also</a> + </li> + </ul> +</div> +``` + +To progressively enhance this navigation widget that is by default accessible, the class to hide the `menu` and the inclusion of `tabindex="-1"` on the interactive menuitem content should be added with JavaScript on load. + +When including a "menu" for site navigation, do not use the `menu` role. Rather, for the main site navigation use the native HTML {{HTMLElement('nav')}} element or simply a list of links. The `menu` role should be reserved for composite widgets requiring focus management. See [ARIA practices for disclosure navigation](https://www.w3.org/TR/wai-aria-practices-1.2/examples/disclosure/disclosure-navigation.html) for an explanation and additional examples. + +### Example 2: menubar submenu option picker + +The following snippet of code is a popup menu nested in a menubar. It is displayed when the menu button is activated. It is a menu to select the text color from a list of color options: + +```html +<div> + <button + type="button" + aria-haspopup="menu" + aria-controls="colormenu" + tabindex="0" + aria-label="Text Color: purple"> + Purple + </button> + <ul role="menu" id="colormenu" aria-label="Color Options" tabindex="-1"> + <li + role="menuitemradio" + aria-checked="true" + style="color: purple" + tabindex="-1"> + Purple + </li> + <li + role="menuitemradio" + aria-checked="false" + style="color: magenta" + tabindex="-1"> + Magenta + </li> + <li + role="menuitemradio" + aria-checked="false" + style="color: black;" + tabindex="-1"> + Black + </li> + </ul> +</div> +``` + +The button that opens the menu has [`aria-haspopup="menu"`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-haspopup) set, explicitly indicating that the popup it controls is a `menu`. + +For a menu to open, the user generally interacts with a menu button as the opener. The menu button must be focusable and respond to both click and keyboard events. When focused, selecting <kbd>Enter</kbd>, <kbd>Space</kbd>, <kbd>Down Arrow</kbd>, or the <kbd>Up Arrow</kbd> should open the menu and place focus on a menu item. + +The opening and closing of the menu toggles the [`aria-expanded="true"`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-expanded) attribute on the button. It is added when the menu is open. Removed or set to `false` when the menu is closed. The `true` value indicates that the menu is displayed and that activating the menu button closes the menu. + +When the menu is open, the button itself generally does not receive focus as users arrow through the menu items. Rather, <kbd>Escape</kbd> and optionally <kbd>Shift + Tab</kbd> closes the menu and returns focus to the menu button. + +The `menu` role was set on the {{HTMLElement('ul')}}, identifying the `<ul>` element as a menu. + +The showing and hiding of the menu can be done with CSS. For example, in these code examples we can use the attribute and next-sibling selectors to toggle the visibility of the menu: + +```css +[role="menu"] { + display: none; +} +[aria-expanded="true"] + [role="menu"] { + display: block; +} +``` + +The navigation example has a static button. The submenu example has a button that gets updated when the user selects a new value. In this case, the `aria-label="Text Color: purple"` is set on the `menu` element. It defines the accessible name for the menu as "Text color: purple"; identifying the purpose of the menu (selecting a text color) and the current value (purple). When a new color is selected, the value of the `aria-label` property should be updated as well. + +## Specifications + +{{Specifications}} + +## See also + +- [`menubar`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/menubar_role) +- [`menuitem`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/menuitem_role) +- [`menuitemcheckbox`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/menuitemcheckbox_role) +- [`menuitemradio`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/menuitemradio_role) +- [`aria-haspopup`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-haspopup) diff --git a/files/en-us/web/accessibility/aria/reference/roles/menubar_role/index.md b/files/en-us/web/accessibility/aria/reference/roles/menubar_role/index.md new file mode 100644 index 000000000000000..0e361c34a9aeb85 --- /dev/null +++ b/files/en-us/web/accessibility/aria/reference/roles/menubar_role/index.md @@ -0,0 +1,94 @@ +--- +title: "ARIA: menubar role" +short-title: menubar +slug: Web/Accessibility/ARIA/Reference/Roles/menubar_role +page-type: aria-role +spec-urls: + - https://w3c.github.io/aria/#menubar + - https://www.w3.org/WAI/ARIA/apg/patterns/menubar/examples/menubar-navigation/ +sidebar: accessibilitysidebar +--- + +A `menubar` is a presentation of `menu` that usually remains visible and is usually presented horizontally. + +## Description + +A menu is a widget that offers a list of choices to the user, such as a set of actions or functions. The menubar type of menu is usually presented as a persistently visible horizontal bar of commands. Menubars behave like native operating system menubars, such as the menubars containing pull down menus, commonly found at the top of many desktop application windows. + +The `menubar` role is used to create a menu bar similar to those found near the top of the window in many desktop applications, visually persistent, typically horizontal, bar of menu items offering the user quick access to a consistent set of commands. + +A `menubar` contains three types of menu items, including [`menuitem`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/menuitem_role), [`menuitemradio`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/menuitemradio_role) and [`menuitemcheckbox`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/menuitemcheckbox_role). These menu items may optionally be nested in one or more [`group`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/group_role) containers. Groups or items may optionally by separated with [`separator`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/separator_role) elements. While every menu item must be able to receive focus, even if disabled, the `group` and `separator` elements are not focusable. + +An example of a native menubar is the bar which may be present at the top of the screen if you are reading this in a desktop browser. An example of a web-based menubar is the horizontal menu bar that reads "File Edit View Insert Format", etc., which is usually visible under the document name in a Google doc. + +Menubar interactions should be similar to the typical menu bar interaction in a desktop graphical user interface. In Google Docs, each of those menu items is a `menuitem` with a popup submenu, so each has an `aria-haspopup` attribute set to `true`. The `menubar` element does not. + +The menubar and all the menu items are focusable and have a [tabindex](/en-US/docs/Web/HTML/Reference/Global_attributes/tabindex) attribute set. When the menubar receives focus through tabbing, keyboard focus is placed on the first menuitem. Each item in the menu has `tabindex` set to `-1`, except the first item has which has its `tabindex` set to `0`. + +If a menubar receives focus as a result of a context action, such as a shortcut key, <kbd>Escape</kbd> or <kbd>Enter</kbd> may return focus to the invoking context. That said, make sure not to create shortcut keys that interfere with user agent, operating system, or assistive technology shortcuts - any UA, OS, or AT. + +Every menu item, no matter how deeply nested, is able to receive focus, even if disabled. + +If a `menubar` has a visible label, include [`aria-labelledby`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-labelledby) set to a value that refers to the labelling element. Otherwise, provide the menubar with an accessible name by including a descriptive [`aria-label`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-label). + +A `menuitem` element in the `menubar` can contain a child submenu of menu items. Submenus can be nested several deep. Generally, the outer `menubar` is horizontal and all the submenus are vertical. If this is not the case, if your menubar is vertical, include [`aria-orientation="vertical"`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-orientation) on the `menubar` element. Otherwise, this attribute is not necessary, as the default value is horizontal. + +### Associated WAI-ARIA roles, states, and properties + +- [`group`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/group_role) role + - : Identifies a set of menu items +- [`menuitem`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/menuitem_role) role + - : An option in a set of choices contained by a `menubar`. May have a submenu. +- [`menuitemradio`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/menuitemradio_role) role + - : A checkable menu item in a set of elements with the same role, only one of which can be checked at a time. +- [`menuitemcheckbox`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/menuitemcheckbox_role) role + - : a menu item with a checkable state whose possible values are `true`, `false`, or `mixed`. +- [`aria-orientation`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-orientation) + - : Include `aria-orientation="vertical"` on `menubar` element if it's the menubar is vertical. The default orientation is `horizontal`. + +### Keyboard interactions + +When focus is in a `menubar` it is always on a menu item within the menu bar. When focus is on a top level `menuitem` in a menu bar, the following keyboard interactions must be supported: + +- <kbd>Down Arrow</kbd> + - : If the currently focused `menuitem` has a submenu, opens the submenu and places focus on the first item in the submenu. +- <kbd>Up Arrow</kbd> + - : (Optional) If the currently focused `menuitem` has a submenu, opens the submenu and places focus on the _last_ item in the submenu. +- <kbd>Right Arrow</kbd> + - : Moves focus to the next item, optionally wrapping from the last to the first. +- <kbd>Left Arrow</kbd> + - : Moves focus to the previous item, optionally wrapping from the first to the last. +- <kbd>Home</kbd> + - : If arrow key wrapping is not supported, moves focus to the first item in the `menubar`. +- <kbd>End</kbd> + - : If arrow key wrapping is not supported, moves focus to the last item in the `menubar`. +- <kbd>Tab</kbd> + - : Moves focus to the next element in the tab sequence. If that makes it exit the menubar, all submenus in the menubar get closed. +- <kbd>shift + Tab</kbd> + - : Moves focus to the previous element in the tab sequence. If that makes it exit the menubar, all submenus in the menubar get closed. + +See [`menuitem` keyboard interactions](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/menuitem_role#keyboard_interactions), [`menuitemradio` keyboard interactions](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/menuitemradio_role#keyboard_interactions), and [`menuitemcheckbox` keyboard interactions](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/menuitemcheckbox_role#keyboard_interactions) for more information on keyboard interactions when focus is on a menuitem in a menubar (which it always is). + +Note: The above interactions assumed the `menubar` is horizontal. If the `menubar` is vertical, include `aria-orientation="vertical"` and change the following keyboard keys accordingly: + +- <kbd>Down Arrow</kbd> + - : Performs like the <kbd>Right Arrow</kbd> as described above. +- <kbd>Up Arrow</kbd> + - : Performs like the <kbd>Left Arrow</kbd> as described above +- <kbd>Right Arrow</kbd> + - : Performs like the <kbd>Down Arrow</kbd> as described above. +- <kbd>Left Arrow</kbd> + - : Performs as the <kbd>Up Arrow</kbd> as described above + +## Examples + +- [W3C WAI-ARIA practices: navigation `menubar` example](https://www.w3.org/WAI/ARIA/apg/patterns/menubar/examples/menubar-navigation/) +- [W3C WAI-ARIA practices: editor `menubar` example](https://www.w3.org/WAI/ARIA/apg/patterns/menubar/examples/menubar-editor/) + +## Specifications + +{{Specifications}} + +## See also + +- [`toolbar` role](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/toolbar_role) diff --git a/files/en-us/web/accessibility/aria/reference/roles/menuitem_role/index.md b/files/en-us/web/accessibility/aria/reference/roles/menuitem_role/index.md new file mode 100644 index 000000000000000..9e9ab497b9a51d1 --- /dev/null +++ b/files/en-us/web/accessibility/aria/reference/roles/menuitem_role/index.md @@ -0,0 +1,117 @@ +--- +title: "ARIA: menuitem role" +short-title: menuitem +slug: Web/Accessibility/ARIA/Reference/Roles/menuitem_role +page-type: aria-role +spec-urls: + - https://w3c.github.io/aria/#menuitem + - https://www.w3.org/WAI/ARIA/apg/patterns/menubar/examples/menubar-navigation/ +sidebar: accessibilitysidebar +--- + +The `menuitem` role indicates the element is an option in a set of choices contained by a `menu` or `menubar`. + +## Description + +A `menuitem` is one of the three types of options in a set of choices contained by a [`menu`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/menu_role) or [`menubar`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/menubar_role); the other two being [`menuitemcheckbox`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/menuitemcheckbox_role) and [`menuitemradio`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/menuitemradio_role). The `menuitem` is only found as a descendant of, or owned by, elements with role `menu` or `menubar`, optionally nested within an element with role [`group`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/group_role) that is contained in, or owned by, a menu. + +If the `menuitem` is not a descendant of a menu in the DOM, include the [`aria-owns`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-owns) attribute on menu to indicate the relationship. If `aria-owns` is set on the menu container to include elements that are not DOM children of the container, those elements will appear in the reading order in the sequence they are referenced and after any items that are DOM children in supporting technologies. Ensure the visual focus order matches the assistive technology reading order. + +Every `menuitem` in a menu is focusable, whether or not it is disabled. Indicate a `menuitem` is disabled by setting [`aria-disabled="true"`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-disabled) on the element with the role. + +If a `menuitem` has a submenu, program it to display a new sub-level menu when the menu item is activated and include [`aria-haspopup="menu"`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-haspopup) or with the `true` value to indicate to assistive technologies that the menu item is used to open a submenu. + +A common convention for indicating that a `menuitem` launches a dialog box is to append "…" (ellipsis) to the menu item label, e.g., "Save as …". + +Every `menuitem` must have an accessible name. This name comes from the element's contents by default. If the contents don't provide for a useful accessible name, [`aria-labelledby`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-labelledby) can be used to reference visible label. If no visible content is available to provide the accessible name, an accessible name can be provided with [`aria-label`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-label). + +### Associated WAI-ARIA roles, states, and properties + +- [`menu`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/menu_role) role + - : A widget providing a list of choices. Required context role (or `menubar`) +- [`menubar`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/menubar_role) role + - : A presentation of a `menu` that usually remains visible and is usually presented horizontally. Required context role (or `menu`) +- [`group`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/group_role) role + - : Can be used to identify a set of related `menuitem`s within or otherwise owned by a `menu` or `menubar` +- [`aria-disabled`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-disabled) + - : Indicates the element is perceivable but disabled, so it is not operable +- [`aria-haspopup`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-haspopup) + - : Indicates the availability and type of interactive popup that can be triggered by the `menuitem` + +### Keyboard interactions + +- <kbd>Enter</kbd> and <kbd>Space</kbd> + - : If the `menuitem` has a submenu, opens the submenu and places focus on its first item. Otherwise, activates the item and closes the menu. +- <kbd>Down Arrow</kbd> + - : On a `menuitem` that has a submenu in a `menubar`, opens the submenu and places focus on the first item in the submenu. Otherwise, moves focus to the next item, optionally wrapping from the last to the first. +- <kbd>Up Arrow</kbd> + - : Moves focus to the previous item, optionally wrapping from the first to the last. Optionally, if the `menuitem` is in a menubar and has a submenu, opens the submenu and places focus on the last item in the submenu. +- <kbd>Right Arrow</kbd> + - : If in a `menu` opened with a menubutton and not in a `menubar`, if the menuitem does not have a submenu, does nothing. When focus is in a `menubar`, moves focus to the next item, optionally wrapping from the last to the first. When focus is in a `menu` and on a `menuitem` that has a submenu, opens the submenu and places focus on its first item. When focus is in a `menu` and on an item that does not have a submenu, closes the submenu and any parent menus, moves focus to the next item in the `menubar`, and, if focus is now on a `menuitem` with a submenu, either opens the submenu of that `menuitem` without moving focus into the submenu, or opens the submenu of that `menuitem` and places focus on the first item in the submenu. +- <kbd>Left Arrow</kbd> + - : When focus is in a `menubar`, moves focus to the previous item, optionally wrapping from the first to the last. When focus is in a submenu of an item in a menu, closes the submenu and returns focus to the parent `menuitem`. When focus is in a submenu of an item in a `menubar`, closes the submenu, moves focus to the previous item in the `menubar`, and, if focus is now on a `menuitem` with a submenu, either opens the submenu of that `menuitem` without moving focus into the submenu, or opens the submenu of that `menuitem` and places focus on the first item in the submenu. +- <kbd>Home</kbd> + - : If arrow key wrapping is not supported, moves focus to the first item in the current `menu` or `menubar`. +- <kbd>End</kbd> + - : If arrow key wrapping is not supported, moves focus to the last item in the current `menu` or `menubar`. +- Any key that corresponds to a printable character (Optional) + - : Move focus to the next item in the current menu whose label begins with that printable character. +- <kbd>Escape</kbd> + - : Close the menu that contains focus and return focus to the element or context, e.g., menu button or parent `menuitem`, from which the menu was opened. +- <kbd>Tab</kbd> + - : Moves focus to the next element in the tab sequence, and if the item that had focus is not in a menubar, closes its menu and all open parent menu containers. +- <kbd>Shift + Tab</kbd> + - : Moves focus to the previous element in the tab sequence, and if the item that had focus is not in a menubar, closes its menu and all open parent menu containers. + +If a menu is opened or a menu bar receives focus as a result of a context action, <kbd>Escape</kbd> or <kbd>Enter</kbd> may return focus to the invoking context. + +Some implementations of navigation menubars may have menuitem elements that both perform a function and open a submenu. In such implementations, <kbd>Enter</kbd> and <kbd>Space</kbd> perform a navigation function while <kbd>Down Arrow</kbd>, in a horizontal menubar, opens the submenu associated with that same menuitem. + +When items in a `menubar` are arranged vertically and items in menu containers are arranged horizontally the <kbd>Down Arrow</kbd> performs as <kbd>Right Arrow</kbd> is described above, the <kbd>Up Arrow</kbd> performs as <kbd>Left Arrow</kbd> is described above, and vice versa. + +## Examples + +```html +<div> + <button id="menubutton" aria-haspopup="true" aria-controls="menu"> + <img src="hamburger.svg" alt="Page Sections" /> + </button> + <ul id="menu" role="menu" aria-labelledby="menubutton"> + <li role="presentation"> + <a role="menuitem" href="#description">Description</a> + </li> + <li role="presentation"> + <a + role="menuitem" + href="#associated_wai-aria_roles_states_and_properties"> + Associated WAI-ARIA roles, states, and properties + </a> + </li> + <li role="presentation"> + <a role="menuitem" href="#keyboard_interactions"> + Keyboard interactions + </a> + </li> + <li role="presentation"> + <a role="menuitem" href="#examples">Examples</a> + </li> + <li role="presentation"> + <a role="menuitem" href="#specifications">Specifications</a> + </li> + <li role="presentation"> + <a role="menuitem" href="#see_also">See Also</a> + </li> + </ul> +</div> +``` + +## Specifications + +{{Specifications}} + +## See also + +- [`menuitemcheckbox` role](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/menuitemcheckbox_role) +- [`menuitemradio` role](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/menuitemradio_role) +- [`listitem` role](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/listitem_role) +- [`option` role](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/option_role) diff --git a/files/en-us/web/accessibility/aria/reference/roles/menuitemcheckbox_role/index.md b/files/en-us/web/accessibility/aria/reference/roles/menuitemcheckbox_role/index.md new file mode 100644 index 000000000000000..47074c5a8effbd7 --- /dev/null +++ b/files/en-us/web/accessibility/aria/reference/roles/menuitemcheckbox_role/index.md @@ -0,0 +1,142 @@ +--- +title: "ARIA: menuitemcheckbox role" +short-title: menuitemcheckbox +slug: Web/Accessibility/ARIA/Reference/Roles/menuitemcheckbox_role +page-type: aria-role +spec-urls: + - https://w3c.github.io/aria/#menuitemcheckbox + - https://www.w3.org/WAI/ARIA/apg/patterns/menubar/examples/menubar-navigation/ +sidebar: accessibilitysidebar +--- + +A `menuitemcheckbox` is a `menuitem` with a checkable state whose possible values are `true`, `false`, or `mixed`. + +## Description + +The items in menu and menubars are menu items. There are three types of menu items: [`menuitem`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/menuitem_role), [`menuitemradio`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/menuitemradio_role), and `menuitemcheckbox`. + +These three elements can only be contained in, or owned by, an element with role [`menu`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/menu_role) or [`menubar`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/menubar_role), optionally nested within a grouping element with role of [`group`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/group_role). Being nested or otherwise owned (see [`aria-owns`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-owns)) in a `menu` or `menubar` identifies the menu items as being related widgets. + +Menu items, including `menuitemcheckbox` elements, may be grouped within `group` elements or separated by elements with the [`separator`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/separator_role) role or other equivalent native role such as {{HTMLElement('fieldset')}} and {{HTMLElement('hr')}}. + +Menu items containing the role of `menuitemcheckbox` must include the [`aria-checked`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-checked) attribute to expose the checkbox's state to assistive technology, unless using [`<input type="checkbox">`](/en-US/docs/Web/HTML/Reference/Elements/input/checkbox), in which case the [`checked`](/en-US/docs/Web/HTML/Reference/Elements/input/checkbox#checked) attribute should be used. + +Similar to the `checked` attribute of {{HTMLElement('input')}}s of type `checkbox`, the `aria-checked` attribute of a `menuitemcheckbox` indicates whether the menu item is checked (`true`), unchecked (`false`), or represents a sub-level menu of other menu items that have a mixture of checked and unchecked values (`mixed`). The `mixed` value is similar to the checkbox's [`indeterminate`](/en-US/docs/Web/HTML/Reference/Elements/input/checkbox#indeterminate_state_checkboxes) attribute, which gives the appearance of a third, neither checked nor unchecked, state. + +An accessible name is required. Ideally, the accessible name should come from an associated {{htmlelement('label')}} element if using `<input type="checkbox">` or visible, descendant content. Realize if the label or descendant content is not sufficient and, preferably, [`aria-labelledby`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-labelledby) is used referencing non-descendant content or [`aria-label`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-label) is used, these two ARIA properties will hide other descendant content from assistive technologies. + +If all elements in the set are not present in the DOM include the [`aria-setsize`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-setsize) and [`aria-posinset`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-posinset) properties. When specifying `aria-setsize` and `aria-posinset` on a `menuitemcheckbox`, set the value with respect to the total number of items in the menu, excluding any separators. + +The `menuitemcheckbox` element can have phrasing content, but can not have interactive content as descendants and no descendants with a `tabindex` attribute specified. + +### All descendants are presentational + +There are some types of user interface components that, when represented in a platform accessibility API, can only contain text. Accessibility APIs do not have a way of representing semantic elements contained in a `menuitemcheckbox`. To deal with this limitation, browsers, automatically apply role [`presentation`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/presentation_role) to all descendant elements of any `menuitemcheckbox` element as it is a role that does not support semantic children. + +For example, consider the following `menuitemcheckbox` element, which contains a heading. + +```html +<div role="menuitemcheckbox"><h6>Name of my checkbox</h6></div> +``` + +Because descendants of `menuitemcheckbox` are presentational, the following code is equivalent: + +```html +<div role="menuitemcheckbox"> + <h6 role="presentation">Name of my checkbox</h6> +</div> +``` + +From the assistive technology user's perspective, the heading does not exist since the previous code snippets are equivalent to the following in the [accessibility tree](/en-US/docs/Glossary/Accessibility_tree): + +```html +<div role="menuitemcheckbox">Name of my checkbox</div> +``` + +### Associated WAI-ARIA roles, states, and properties + +- [`menu`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/menu_role) role + - : Widget that offers a list of common actions or functions the user can invoke. +- [`menubar`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/menubar_role) role + - : Similar to `menu` for a consistent set of frequently used commands remaining visible and usually presented horizontally. +- [`group`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/group_role) role + - : Container for a group of `menuitem` elements, including `menuitemcheckbox` elements within a `menu` or `menubar`. +- [`aria-checked`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-checked) (Required) + - : Set to `true`, `false`, or `mixed`, it indicates the current "checked" state of the menuitemcheckbox + +### Keyboard interactions + +When a `menu` opens, or when a `menubar` receives focus, keyboard focus is placed on the first item. All items in both are focusable, including all `menuitemcheckbox` elements. + +If the `menuitemcheckbox` is in a submenu in a `menubar` or a menu opened with a menu button, the following keyboard interactions must be programmed in. : + +- <kbd>Enter</kbd> + - : Toggles the `aria-checked` state of the `menuitemcheckbox` and closes the menu. +- <kbd>Space</kbd> + - : Toggles the `aria-checked` state of the `menuitemcheckbox`. Does not close the menu. +- <kbd>Escape</kbd> + - : Closes menu. In menubar, moves focus to parent menubar item. +- <kbd>Right Arrow</kbd> + - : Closes submenu. In menubar, moves focus to next item in the menubar, opening any submenu if there is one. +- <kbd>Left Arrow</kbd> + - : Closes menu. In menubar, moves focus to previous item in the menubar, opening any submenu if there is one. +- <kbd>Down Arrow</kbd> + - : Moves focus to the next item in the menu. If focus is on the last item, moves focus to the first item. +- <kbd>Up Arrow</kbd> + - : Moves focus to previous item in the menu. If focus is on the first item, moves focus to the last item. +- <kbd>Home</kbd> + - : Moves focus to the first item in the menu. +- <kbd>End</kbd> + - : Moves focus to the last item in the menu. +- <kbd>Character</kbd> + - : Moves focus to the next item having a name that starts with the typed character. If none of the items have a name starting with the typed character, focus does not move. + +### Required JavaScript + +#### Required event handlers + +- `onclick` + - : Handle mouse clicks on both the checkbox and the associated label that will change the state of the checkbox by changing the value of the `aria-checked` attribute and the appearance of the checkbox so it appears checked or unchecked to the sighted user +- `onKeyDown` + - : Handle the case where the user presses the <kbd>Space</kbd> key to change the state of the checkbox by changing the value of the `aria-checked` attribute and the appearance of the checkbox so it appears checked or unchecked to the sighted user. Also handles all keys listed in the keyboard navigation section above. + +## Examples + +```html +<li role="menuitemcheckbox" tabindex="-1" aria-checked="false">Purple</li> +``` + +The [`tabindex="-1"`](/en-US/docs/Web/HTML/Reference/Global_attributes/tabindex) makes the `menuitemcheckbox` focusable but not part of the page tab sequence. Had we included `aria-checked="true"` it would have indicated that the `menuitemcheckbox` was checked, and we would have visually styled the selected state to look checked using the attribute selector `[role='menuitemcheckbox'][aria-checked='true']`. Instead, the presence of `aria-checked="false"` indicates to assistive technologies that the `menuitemcheckbox` is checkable but not currently checked. The accessible name "purple" comes from the contents. + +The visual appearance of the selected state is a checked checkbox which we can create using [generated content](/en-US/docs/Web/CSS/CSS_generated_content), making it visible and the same color as the content by synchronizing with the `aria-checked` value using CSS [attribute selectors](/en-US/docs/Web/CSS/Attribute_selectors) and [inheriting](/en-US/docs/Web/CSS/inherit) the color. + +```css +[role="menuitemcheckbox"]::before { + display: inline-block; + content: ""; + color: transparent; + width: 1em; + text-align: center; + outline: 1px solid; + margin-inline-end: 2px; + font-family: sans-serif; +} +[role="menuitemcheckbox"][aria-checked="true"]::before { + color: inherit; + content: "X"; +} +``` + +### Prefer HTML + +The first rule of ARIA is: if a native HTML element or attribute has the semantics and behavior you require, use it instead of re-purposing an element and adding an ARIA role, state or property to make it accessible. As such, it is recommended to use the native [HTML checkbox](/en-US/docs/Web/HTML/Reference/Elements/input/checkbox) form control instead of recreating a checkbox's functionality with JavaScript and ARIA. + +## Specifications + +{{Specifications}} + +## See also + +- [`menuitemradio` role](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/menuitemradio_role) +- [`checkbox` role](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/checkbox_role) +- [`<input type="checkbox">`](/en-US/docs/Web/HTML/Reference/Elements/input/checkbox) diff --git a/files/en-us/web/accessibility/aria/reference/roles/menuitemradio_role/index.md b/files/en-us/web/accessibility/aria/reference/roles/menuitemradio_role/index.md new file mode 100644 index 000000000000000..63e6c393e91c061 --- /dev/null +++ b/files/en-us/web/accessibility/aria/reference/roles/menuitemradio_role/index.md @@ -0,0 +1,152 @@ +--- +title: "ARIA: menuitemradio role" +short-title: menuitemradio +slug: Web/Accessibility/ARIA/Reference/Roles/menuitemradio_role +page-type: aria-role +spec-urls: + - https://w3c.github.io/aria/#menuitemradio + - https://www.w3.org/WAI/ARIA/apg/patterns/menubar/examples/menubar-navigation/ +sidebar: accessibilitysidebar +--- + +A `menuitemradio` is checkable menuitem in a set of elements with the same role, only one of which can be checked at a time. + +## Description + +The items in menu and menubars are menu items. There are three types of menu items: [`menuitem`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/menuitem_role), [`menuitemcheckbox`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/menuitemcheckbox_role), and `menuitemradio`. To limit the number of checked menu items to one within a group, use the `menuitemradio` role on all the elements in the group. + +A `menuitemradio` is checkable menuitem in a set of elements with the same role, of which only can be checked at a time. + +The three menu item elements can only be contained in, or owned by, an element with role [`menu`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/menu_role) or [`menubar`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/menubar_role), optionally nested within a grouping element with role of [`group`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/group_role). Being nested or otherwise owned (see [`aria-owns`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-owns)) in a `menu` or `menubar` identifies the menu items as being related widgets. + +When all items in a submenu are members of the same radio group, the `group` is defined by the menu element; the `group` element is not necessary. + +Menu items containing the role of `menuitemradio` must include the [`aria-checked`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-checked) attribute to expose the radio button's state to assistive technology, unless using [`<input type="radio">`](/en-US/docs/Web/HTML/Reference/Elements/input/checkbox), in which case the [`checked`](/en-US/docs/Web/HTML/Reference/Elements/input/checkbox#checked) attribute should be used. + +Similar to the `checked` attribute of {{HTMLElement('input')}}s of type `radio`, the `aria-checked` attribute of a `menuitemradio` indicates whether the menu item is checked (`true`), unchecked (`false`). There is no `mixed` value like there is for `menuitemcheckbox`. + +Only one `menuitemradio` in a group can be checked at the same time. When one item in the group is checked, the `aria-checked` attribute gets set to `true`, while the previously checked `menuitemradio` element in the same group, if there was one, becomes unchecked, by having the `aria-checked` attribute value switched to `false`. + +If your want more than one item in a group to be checked, or if you want to enable checking and unchecking an item, consider using `menuitemcheckbox`. + +If a `menu` or `menubar` contains more than one group of `menuitemradio` elements, or if the `menu` contains a group of `menuitemradio` elements as well as other, unrelated `menuitem` elements and/or `menuitemcheckbox` elements, contain each set of related `menuitemradio` elements in a `group` element or delimit the group the `menuitemradio` elements from the other menu items with a `separator` element (or an HTML element with an equivalent role such as a {{HTMLElement('fieldset')}} grouping or a thematic break {{HTMLElement('hr')}} separator. + +An accessible name is required. Ideally, the accessible name should come from an associated {{htmlelement('label')}} element if using `<input type="radio">` or visible, descendant content. Realize if the label or descendant content is not sufficient and, preferably, [`aria-labelledby`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-labelledby) is used referencing non-descendant content or [`aria-label`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-label) is used, these two ARIA properties will hide other descendant content from assistive technologies. + +If all elements in the set are not present in the DOM include the [`aria-setsize`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-setsize) and [`aria-posinset`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-posinset) properties. When specifying `aria-setsize` and `aria-posinset` on a `menuitemradio`, set the value with respect to the total number of items in the menu, excluding any separators. + +The `menuitemradio` element can have phrasing content, but can not have interactive content as descendants and no descendants with a `tabindex` attribute specified. + +### All descendants are presentational + +There are some types of user interface components that, when represented in a platform accessibility API, can only contain text. Accessibility APIs do not have a way of representing semantic elements contained in a `menuitemradio`. To deal with this limitation, browsers, automatically apply role [`presentation`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/presentation_role) to all descendant elements of any `menuitemradio` element as it is a role that does not support semantic children. + +For example, consider the following `menuitemradio` element, which contains a heading. + +```html +<div role="menuitemradio"><h6>Name of my radio button</h6></div> +``` + +Because descendants of `menuitemradio` are presentational, the following code is equivalent: + +```html +<div role="menuitemradio"> + <h6 role="presentation">Name of my radio button</h6> +</div> +``` + +From the assistive technology user's perspective, the heading does not exist since the previous code snippets are equivalent to the following in the [accessibility tree](/en-US/docs/Glossary/Accessibility_tree): + +```html +<div role="menuitemradio">Name of my radio button</div> +``` + +### Associated WAI-ARIA roles, states, and properties + +- [`menu`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/menu_role) role + - : Widget that offers a list of common actions or functions the user can invoke. +- [`menubar`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/menubar_role) role + - : Similar to `menu` for a consistent set of frequently used commands remaining visible and usually presented horizontally. +- [`group`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/group_role) role + - : Container for a group of `menuitem` elements, including `menuitemradio` elements within a `menu` or `menubar`. +- [`aria-checked`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-checked) (Required) + - : Set to `true` or `false`, it indicates the current "checked" state of the menuitemradio + +### Keyboard interactions + +When a `menu` opens, or when a `menubar` receives focus, keyboard focus is placed on the first item. All items in both are focusable, including all `menuitemradio` elements. + +If the `menuitemradio` is in a submenu in a `menubar` or a menu opened with a menu button, the following keyboard interactions must be programmed in. : + +- <kbd>Enter</kbd> + - : If not checked, checks the focused `menuitemradio` and unchecks any other checked `menuitemradio` element in the same group. Also, closes the menu. +- <kbd>Space</kbd> + - : If not checked, checks the focused `menuitemradio` and unchecks any other checked `menuitemradio` element in the same group without closing the menu. +- <kbd>Escape</kbd> + - : Closes menu. In menubar, moves focus to parent menubar item. +- <kbd>Right Arrow</kbd> + - : Closes submenu. In menubar, moves focus to next item in the menubar, opening any submenu if there is one. +- <kbd>Left Arrow</kbd> + - : Closes menu. In menubar, moves focus to previous item in the menubar, opening any submenu if there is one. +- <kbd>Down Arrow</kbd> + - : Moves focus to the next item in the menu. If focus is on the last item, moves focus to the first item. +- <kbd>Up Arrow</kbd> + - : Moves focus to previous item in the menu. If focus is on the first item, moves focus to the last item. +- <kbd>Home</kbd> + - : Moves focus to the first item in the menu. +- <kbd>End</kbd> + - : Moves focus to the last item in the menu. +- <kbd>Character</kbd> + - : Moves focus to the next item having a name that starts with the typed character. If none of the items have a name starting with the typed character, focus does not move. + +### Required JavaScript + +#### Required event handlers + +- `onclick` + - : Handle mouse clicks on both the radio button and the associated label that will change the state of the radio button by changing the value of the `aria-checked` attribute and the appearance of the radio button so it appears checked or unchecked to the sighted user +- `onKeyDown` + - : Handle the case where the user presses the <kbd>Space</kbd> key to change the state of the radio button by changing the value of the `aria-checked` attribute and the appearance of the radio button so it appears checked or unchecked to the sighted user. Also handles all keys listed in the keyboard navigation section above. + +## Examples + +```html +<li role="menuitemradio" tabindex="-1" aria-checked="false">Purple</li> +``` + +The [`tabindex="-1"`](/en-US/docs/Web/HTML/Reference/Global_attributes/tabindex) makes the `menuitemradio` focusable but not part of the page tab sequence. Had we included `aria-checked="true"` it would have indicated that the `menuitemradio` was checked, and we would have visually styled the selected state to look checked using the attribute selector `[role='menuitemradio'][aria-checked='true']`. Instead, the presence of `aria-checked="false"` indicates to assistive technologies that the `menuitemradio` is checkable but not currently checked. The accessible name "purple" comes from the contents. + +The visual appearance of the selected state is a checked radio button which we can create using [generated content](/en-US/docs/Web/CSS/CSS_generated_content), making it visible and the same color as the content by synchronizing with the `aria-checked` value using CSS [attribute selectors](/en-US/docs/Web/CSS/Attribute_selectors) and changing the [`background-color`](/en-US/docs/Web/CSS/background-color). + +```css +[role="menuitemradio"]::before { + display: inline-block; + content: ""; + width: 1em; + height: 1em; + padding: 0.1em; + border: 2px solid #333; + border-radius: 50%; + box-sizing: border-box; + background-clip: content-box; + margin-inline-end: 2px; +} +[role="menuitemradio"][aria-checked="true"]::before { + background-color: purple; +} +``` + +Don't use the [`background`](/en-US/docs/Web/CSS/background) shorthand property, as that will override the [`background-clip`](/en-US/docs/Web/CSS/background-clip) property we used to create the radio button effect. + +### Prefer HTML + +The first rule of ARIA is: if a native HTML element or attribute has the semantics and behavior you require, use it instead of re-purposing an element and adding an ARIA role, state or property to make it accessible. As such, it is recommended to use the native [HTML radio button](/en-US/docs/Web/HTML/Reference/Elements/input/radio) form control instead of recreating a radio button's functionality with JavaScript and ARIA. + +## Specifications + +{{Specifications}} + +## See also + +- [`radio` role](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/radio_role) +- [`<input type="radio">`](/en-US/docs/Web/HTML/Reference/Elements/input/radio) diff --git a/files/en-us/web/accessibility/aria/reference/roles/meter_role/index.md b/files/en-us/web/accessibility/aria/reference/roles/meter_role/index.md new file mode 100644 index 000000000000000..2d03ca352c44d2a --- /dev/null +++ b/files/en-us/web/accessibility/aria/reference/roles/meter_role/index.md @@ -0,0 +1,85 @@ +--- +title: "ARIA: meter role" +short-title: meter +slug: Web/Accessibility/ARIA/Reference/Roles/meter_role +page-type: aria-role +spec-urls: https://www.w3.org/TR/wai-aria-1.2/#meter +sidebar: accessibilitysidebar +--- + +The `meter` role is used to identify an element being used as a meter. + +> [!NOTE] +> Where possible, it is recommended that you use a native {{HTMLElement("meter")}} element rather than the `meter` role, as native elements are more widely supported by user agents and assistive technology. + +## Description + +A meter is a graphical display of a numeric value within a defined range. For example, showing battery percentage. A meter is not appropriate for values that do not have a meaningful maximum limit. Meters should not be used to indicate progress (for example loading), this should be communicated with the {{HTMLElement('progress')}} element. + +Each element with `role="meter"` must also have one of the following: + +- An [`aria-label`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-label) attribute. +- An [`aria-labelledby`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-labelledby) attribute pointing to an element with text that describes the meter. + +### All descendants are presentational + +There are some types of user interface components that, when represented in a platform accessibility API, can only contain text. Accessibility APIs do not have a way of representing semantic elements contained in a `meter`. To deal with this limitation, browsers, automatically apply role [`presentation`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/presentation_role) to all descendant elements of any `meter` element as it is a role that does not support semantic children. + +For example, consider the following `meter` element, which contains a heading. + +```html +<div role="meter"><h3>Title of my meter</h3></div> +``` + +Because descendants of `meter` are presentational, the following code is equivalent: + +```html +<div role="meter"><h3 role="presentation">Title of my meter</h3></div> +``` + +From the assistive technology user's perspective, the heading does not exist since the previous code snippets are equivalent to the following in the [accessibility tree](/en-US/docs/Glossary/Accessibility_tree).: + +```html +<div role="meter">Title of my meter</div> +``` + +### Associated ARIA roles, states, and properties + +- [`aria-valuenow`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-valuenow) + - : Set to a decimal value between `aria-valuemin` and `aria-valuemax` indicating the current value of the meter. +- [`aria-valuetext`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-valuetext) + - : Assistive technologies often present the value of `aria-valuenow` as a percentage. If this would not be accurate use this property to make the meter value understandable. +- [`aria-valuemin`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-valuemin) + - : Set to a decimal value representing the minimum value, and less than `aria-valuemax`. +- [`aria-valuemax`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-valuemax) + - : Set to a decimal value representing the maximum value, and greater than `aria-valuemin`. + +It is recommended to use a native {{HTMLElement("meter")}} element rather than the `meter` role. User agents provide a stylize widget for the {{HTMLElement("meter")}} element based on the current `value` as it relates to the `min` and `max` values. When using non-semantic elements, all features of the native semantic element need to be recreated with ARIA attributes, JavaScript and CSS. + +## Examples + +An example of a meter using `role="meter"`: + +```html +<div + role="meter" + aria-valuenow="90" + aria-valuemin="0" + aria-valuemax="100" + aria-labelledby="cpu_usage_label"> + <svg xmlns="http://www.w3.org/2000/svg" aria-hidden="true" style="width: 90%"> + <rect x="0" y="0" width="100%" height="100%" fill="currentcolor"></rect> + </svg> +</div> +``` + +In the above scenario, when the `aria-valuenow` value updates, the width of the SVG also needs to be updated as can be seen in [the W3C working meter example](https://www.w3.org/TR/wai-aria-practices-1.2/examples/meter/meter.html). + +## Specifications + +{{Specifications}} + +## See also + +- {{HTMLElement('meter')}} +- {{HTMLElement('progress')}} diff --git a/files/en-us/web/accessibility/aria/reference/roles/navigation_role/index.md b/files/en-us/web/accessibility/aria/reference/roles/navigation_role/index.md new file mode 100644 index 000000000000000..68ab30795f1314a --- /dev/null +++ b/files/en-us/web/accessibility/aria/reference/roles/navigation_role/index.md @@ -0,0 +1,121 @@ +--- +title: "ARIA: navigation role" +short-title: navigation +slug: Web/Accessibility/ARIA/Reference/Roles/navigation_role +page-type: aria-role +spec-urls: + - https://w3c.github.io/aria/#navigation + - https://www.w3.org/WAI/ARIA/apg/patterns/landmarks/examples/navigation.html +sidebar: accessibilitysidebar +--- + +The `navigation` role is used to identify major groups of links used for navigating through a website or page content. + +```html +<div role="navigation" aria-label="Main"> + <!-- list of links to main website locations --> +</div> +``` + +This is a website's main navigation. + +## Description + +The `navigation` role is [a landmark](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles#3._landmark_roles) role. Landmark roles provide a way to identify the organization and structure of a web page. By classifying and labeling sections of a page, structural information conveyed visually through layout is represented programmatically. Screen readers use landmark roles to provide keyboard navigation to important sections of a page. Like the HTML {{HTMLElement('nav')}} element, navigation landmarks provide a way to identify groups (e.g., lists) of links that are intended to be used for website or page content navigation. If a page includes more than one navigation landmark, each should have a unique label. If two or more navigational landmark on a page have the same set of links, use the same label for each. + +It is preferable to use the HTML5 [`<nav>` element](/en-US/docs/Web/HTML/Reference/Elements/nav) to define a navigation landmark. If the HTML5 nav element technique is not being used, use a `role="navigation"` attribute to define a navigation landmark. + +> [!NOTE] +> Using the {{HTMLElement('nav')}} element will automatically communicate a section has a role of `navigation`. Developers should always prefer using the correct semantic HTML element over using ARIA + +### Associated WAI-ARIA roles, states, and properties + +- [`aria-label`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-label) + - : A brief description of the purpose of the navigation, omitting the term "navigation", as the screen reader will read both the role and the contents of the label. + +### Keyboard interactions + +None. + +### Required JavaScript features + +None. + +## Examples + +```html +<div role="navigation" aria-label="Customer service"> + <ul> + <li><a href="#">Help</a></li> + <li><a href="#">Order tracking</a></li> + <li><a href="#">Shipping &amp; Delivery</a></li> + <li><a href="#">Returns</a></li> + <li><a href="#">Contact us</a></li> + <li><a href="#">Find a store</a></li> + </ul> +</div> +``` + +## Accessibility concerns + +[Landmark roles](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles#3._landmark_roles) are intended to be used sparingly, to identify larger overall sections of the document. Using too many landmark roles can create "noise" in screen readers, making it difficult to understand the overall layout of the page. + +## Best practices + +### Prefer HTML + +Using the {{HTMLElement('nav')}} element will automatically communicate a section has a role of `navigation`. If at all possible, prefer using it instead. + +### Labeling landmarks + +#### Multiple landmarks + +If there is more than one `navigation` landmark role or {{HTMLElement('nav')}} element in a document, provide a label for each landmark. This label will allow an assistive technology user to be able to quickly understand the purpose of each landmark. + +```html +<div id="main-nav" role="navigation" aria-label="Main"> + <!-- content --> +</div> + +… + +<nav id="footer-nav" aria-label="Footer"> + <!-- content --> +</nav> +``` + +#### Repeated landmarks + +If a `navigation` landmark role or {{HTMLElement('nav')}} element in a document is repeated in a document, and both landmarks have identical content, use the same label for each landmark. An example of this would be repeating the main navigation at the top and bottom of the page. + +```html +<header> + <nav id="main-nav" aria-label="Main"> + <!-- list of links to main website locations --> + </nav> +</header> + +… + +<footer> + <nav id="footer-nav" aria-label="Main"> + <!-- list of links to main website locations --> + </nav> +</footer> +``` + +#### Redundant descriptions + +Screen readers will announce the type of role the landmark is. Because of this, you do not need to describe what the landmark is in its label. For example, a declaration of `role="navigation"` with an of `aria-label="Primary navigation"` may be announced redundantly as, "primary navigation navigation". + +## Specifications + +{{Specifications}} + +## See also + +- The {{HTMLElement('nav')}} element +- [Using HTML sections and outlines](/en-US/docs/Web/HTML/Reference/Elements/Heading_Elements) +- [Using WAI-ARIA Landmarks – 2013 | The Paciello Group](https://www.tpgi.com/using-wai-aria-landmarks-2013/) +- [Accessible Landmarks | scottohara.me](https://www.scottohara.me/blog/2018/03/03/landmarks.html) +- [Semantic navigation with the nav element | HTML5 Doctor](https://html5doctor.com/nav-element/) diff --git a/files/en-us/web/accessibility/aria/reference/roles/none_role/index.md b/files/en-us/web/accessibility/aria/reference/roles/none_role/index.md new file mode 100644 index 000000000000000..99b9905277419fd --- /dev/null +++ b/files/en-us/web/accessibility/aria/reference/roles/none_role/index.md @@ -0,0 +1,11 @@ +--- +title: "ARIA: none role" +short-title: none +slug: Web/Accessibility/ARIA/Reference/Roles/none_role +page-type: aria-role +sidebar: accessibilitysidebar +--- + +The `none` role is a synonym for the [`presentation`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/presentation_role) role; they both remove an element's implicit ARIA semantics from being exposed to the accessibility tree. + +See the [`presentation`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/presentation_role) role for more information. diff --git a/files/en-us/web/accessibility/aria/reference/roles/note_role/index.md b/files/en-us/web/accessibility/aria/reference/roles/note_role/index.md new file mode 100644 index 000000000000000..bc5a87ee6c99d50 --- /dev/null +++ b/files/en-us/web/accessibility/aria/reference/roles/note_role/index.md @@ -0,0 +1,49 @@ +--- +title: "ARIA: note role" +short-title: note +slug: Web/Accessibility/ARIA/Reference/Roles/note_role +page-type: aria-role +spec-urls: https://w3c.github.io/aria/#note +sidebar: accessibilitysidebar +--- + +A `note` role suggests a section whose content is parenthetic or ancillary to the main content. + +## Description + +The `note` role can be added to parenthetic or ancillary content if no other native element or other role fits the purpose. + +### Associated WAI-ARIA roles, states, and properties + +- [`aria-label`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-label) or [`aria-labelledby`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-labelledby) (optional) + - : Naming a note is optional, but can help screen reader users understand its context and purpose. The name can be provided using `aria-labelledby` if a visible label is present, otherwise with `aria-label`. + +## Examples + +```html +<h1>Madam C. J. Walker</h1> +<p> + Madam C.J. Walker was an African American entrepreneur, philanthropist, and + political and social activist. +</p> +<h2>Early Life</h2> +… +<h2>Career</h2> +… +<p role="note" class="highlight-box"> + At the height of the depression, Madam C. J. Walker trained 20,000 women to + sell hair pomade door-to-door +</p> +<h2>Activism and Philanthropy</h2> +… +``` + +In the above Wikipedia style entry for Madam C.J. Walker, the `highlight-box` with role `note` could have been a {{HTMLElement('blockquote')}} if it contained a quote or {{HTMLElement('figcaption')}} in a {{HTMLElement('figure')}} if there was an associated image. In this case, as neither of those made sense, the `note` role was added to add semantics to the parenthetic content. + +## Specifications + +{{Specifications}} + +## See also + +- [Document structure roles](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles#1._document_structure_roles) diff --git a/files/en-us/web/accessibility/aria/reference/roles/option_role/index.md b/files/en-us/web/accessibility/aria/reference/roles/option_role/index.md new file mode 100644 index 000000000000000..035ab6cc1ec4965 --- /dev/null +++ b/files/en-us/web/accessibility/aria/reference/roles/option_role/index.md @@ -0,0 +1,109 @@ +--- +title: "ARIA: option role" +short-title: option +slug: Web/Accessibility/ARIA/Reference/Roles/option_role +page-type: aria-role +spec-urls: + - https://w3c.github.io/aria/#option + - https://www.w3.org/WAI/ARIA/apg/patterns/listbox/examples/listbox-scrollable/ +sidebar: accessibilitysidebar +--- + +The `option` role is used for selectable items in a `listbox`. + +## Description + +The `option` role is used to identify selections a user can make in a [`listbox`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/listbox_role). These options are similar to the {{HTMLElement('option')}} elements in a {{HTMLElement('select')}} element, but they can contain images. + +All selectable options should have [`aria-selected`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-selected) match their state, `true` when selected and `false` when not. If an option is not selectable, `aria-selected` can be omitted. A disabled option can have [`aria-disabled="true"`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-disabled) and `aria-selected="false"` to communicate to the user that the option is present, albeit disabled. + +The `option` role is for identifying selectable choices of a `listbox`. Options must be provided an accessible name. Generally, the accessible name for an option should come from the element's descendant content. + +Authors can also explicitly provide an accessible name by specifying [`aria-label`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-label) or [`aria-labelledby`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-labelledby) to the element with the `option` role. If using `aria-label` or `aria-labelledby`, and the option also displays a visible text label, authors must ensure they adhere to <a href="https://www.w3.org/WAI/WCAG21/Understanding/label-in-name.html">WCAG Success Criterion 2.5.3 Label in Name</a>. + +It is highly recommended to use a {{HTMLElement('select')}} element or an {{HTMLElement('input')}} element with the `checkbox` or `radio` type instead, when possible. These native HTML elements provide keyboard interactivity to manage focus for all the descendants for you automatically. + +### All descendants are presentational + +There are some types of user interface components that, when represented in a platform accessibility API, can only contain text. Accessibility APIs do not have a way of representing semantic elements contained in a `option`. To deal with this limitation, browsers, automatically apply role [`presentation`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/presentation_role) to all descendant elements of any `option` element as it is a role that does not support semantic children. + +For example, consider the following `option` element, which contains a heading. + +```html +<div role="option"><h3>Title of my option</h3></div> +``` + +Because descendants of `option` are presentational, the following code is equivalent: + +```html +<div role="option"><h3 role="presentation">Title of my option</h3></div> +``` + +From the assistive technology user's perspective, the heading does not exist since the previous code snippets are equivalent to the following in the [accessibility tree](/en-US/docs/Glossary/Accessibility_tree): + +```html +<div role="option">Title of my option</div> +``` + +### Associated ARIA roles, states, and properties + +#### Associated Roles + +- [`listbox`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/listbox_role) + - : An `option` _must_ be contained in or owned by a `listbox` + +#### States and Properties + +- [`aria-selected`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-selected) + + - : Used to describe the selection state of the option. Required. + +- [`aria-checked`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-checked) + + - : Used to describe the checked state when options are used in a multiple selection fashion. Supports `true`, `false` and `mixed`. Optional. + +- [`aria-posinset`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-posinset) + + - : Used to describe the position in the set of options when it does not match the DOM, such as virtual scrolling where only some options are present at a time. Optional. + +- [`aria-setsize`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-setsize) + + - : Used in conjunction with `aria-posinset` to declare the total number of options. Optional. + +- [`aria-disabled`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-disabled) + + - : Used to indicate that the option is present but not editable. Optional. + +- [`aria-hidden`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-hidden) + + - : Used to hide the option from accessibility tools. It should only be used to hide non-visible content or visible content if it improves the experience of assistive technology, such as redundant content. Optional. + +- [`aria-invalid`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-invalid) + + - : Used to indicate that the value of the option is considered invalid by the application. Optional. + +- [`aria-busy`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-busy) + + - : Used to indicate that an element is being modified, such as while it is loading. Optional. + +- [`aria-labelledby`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-labelledby) + + - : Used to indicate which element labels the option. The content of the option should be used instead where appropriate. Optional. + +- [`aria-label`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-label) + - : Used to label the option. If the label is present in the DOM, `aria-labelledby` should be used instead. Optional. + +(For further details and a full list of ARIA states and properties see the <a href="https://www.w3.org/TR/wai-aria-1.1/#option">ARIA `option` (role)</a> documentation.) + +## Specifications + +{{Specifications}} + +## See also + +- HTML {{HTMLElement('select')}} element +- HTML {{HTMLElement('label')}} element +- HTML {{HTMLElement('option')}} element +- [ARIA: `combobox` role](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/combobox_role) +- [ARIA: `list` role](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/list_role) +- [ARIA: `listbox` role](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/listbox_role) diff --git a/files/en-us/web/accessibility/aria/reference/roles/presentation_role/index.md b/files/en-us/web/accessibility/aria/reference/roles/presentation_role/index.md new file mode 100644 index 000000000000000..ab4c2fe7464be98 --- /dev/null +++ b/files/en-us/web/accessibility/aria/reference/roles/presentation_role/index.md @@ -0,0 +1,61 @@ +--- +title: "ARIA: presentation role" +short-title: presentation +slug: Web/Accessibility/ARIA/Reference/Roles/presentation_role +page-type: aria-role +spec-urls: https://w3c.github.io/aria/#presentation +sidebar: accessibilitysidebar +--- + +The `presentation` role and its synonym `none` remove an element's implicit ARIA semantics from being exposed to the accessibility tree. + +The content of the element will still be available to assistive technologies; it is only the semantics of the container — and in some instance, required associated descendants — which will no longer expose their mappings to the accessibility API. + +## Description + +While ARIA is primarily used to express semantics, there are some situations where hiding an element's semantics from assistive technologies is helpful. This is done with the `presentation` role or its synonym role `none`, which declare that an element is being used only for presentation and therefore does not have any accessibility semantics. + +Writing `<h2 role="presentation">Democracy Dies in Darkness</h2>` removes the heading semantics of the {{HTMLElement("Heading_Elements", "h2")}} element, making it the equivalent of `<div>Democracy Dies in Darkness</div>`. The heading role semantics are removed, but the content itself is still available. + +When an element has required descendants, such as the various {{HTMLElement('table')}}, elements and {{HTMLElement('li')}}s children of a {{HTMLElement('ul')}} or {{HTMLElement('ol')}}, the `presentation` or `none` role on the table or list removes the default semantics of the element on which it was applied and their required descendant elements. + +If `presentation` or `none` is applied to a {{HTMLElement('table')}} element, the descendant {{HTMLElement('caption')}}, {{HTMLElement('thead')}}, {{HTMLElement('tbody')}}, {{HTMLElement('tfoot')}}, {{HTMLElement('tr')}}, {{HTMLElement('th')}}, and {{HTMLElement('td')}} elements inherit the role and are thus not exposed to assistive technologies. But, elements inside of the {{HTMLElement('th')}} and {{HTMLElement('td')}} elements, including nested tables, are exposed to assistive technologies. + +```html +<ul role="presentation"> + <li> + <a href="#">Link 1</a> + </li> + <li> + <a href="#">Link 2</a> + </li> + <li> + <a href="#">Link 3</a> + </li> +</ul> +``` + +Because the `presentation` role was applied to the {{HTMLElement('ul')}} element, every child {{HTMLElement('li')}} element inherits the `presentation` role. This is because ARIA requires the `listitem` elements to have a parent `list` element. While the {{HTMLElement('li')}} elements, in this case, are not exposed to assistive technologies, descendants of those required elements are exposed. If we had nested a list within one of those {{HTMLElement('li')}}'s, they would be visible to assistive technologies. For elements with no required children, any elements nested inside the element with `role="presentation"` or `role="none"` preserve their semantics. In this case, the {{HTMLElement('a')}} elements contained inside of those {{HTMLElement('li')}} elements are exposed. + +The {{HTMLElement('a')}} is a special case. Its role would have been exposed even if it had the `presentation` or `none` role directly applied to it. Browsers ignore `role="presentation"` and `role="none"` on focusable elements, including link and inputs, or anything with a [tabindex](/en-US/docs/Web/HTML/Reference/Global_attributes/tabindex) attribute set. Browsers also ignore the inclusion of the role if any of the element contains any global ARIA states and properties, such as [`aria-describedby`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-describedby). + +> [!NOTE] +> The element with `role="presentation"` is not part of the accessibility tree and should not have an accessible name. Do **not** use [`aria-labelledby`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-labelledby) or [`aria-label`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-label). + +### Associated WAI-ARIA roles, states, and properties + +None. If a global ARIA state and property is set, `presentation` or `none` will be ignored, and the implicit role of the element will be used. + +## Examples + +```html +<hr role="none" /> +``` + +## Specifications + +{{Specifications}} + +## See also + +- [`aria-hidden`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-hidden) versus [`role="presentation/none"`](https://www.scottohara.me/blog/2018/05/05/hidden-vs-none.html) - by Scott O'Hara diff --git a/files/en-us/web/accessibility/aria/reference/roles/progressbar_role/index.md b/files/en-us/web/accessibility/aria/reference/roles/progressbar_role/index.md new file mode 100644 index 000000000000000..933521e23dc37c7 --- /dev/null +++ b/files/en-us/web/accessibility/aria/reference/roles/progressbar_role/index.md @@ -0,0 +1,107 @@ +--- +title: "ARIA: progressbar role" +short-title: progressbar +slug: Web/Accessibility/ARIA/Reference/Roles/progressbar_role +page-type: aria-role +spec-urls: https://w3c.github.io/aria/#progressbar +sidebar: accessibilitysidebar +--- + +The `progressbar` role defines an element that displays the progress status for tasks that take a long time. + +## Description + +The `progressbar` range widget indicates that a request has been received and the application is making progress toward completing the requested action. + +Authors **may** set aria-valuemin and aria-valuemax to indicate the minimum and maximum progress indicator values. Otherwise, their implicit values follow the same rules as HTML's [`<input type="range">`](/en-US/docs/Web/HTML/Reference/Elements/input/range): + +- If [`aria-valuemin`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-valuemin) is missing or not a number, it defaults to `0` (zero). +- If [`aria-valuemax`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-valuemax) is missing or not a number, it defaults to `100`. +- The `aria-valuemin` and `aria-valuemax` properties only need to be set for the `progressbar` role when the progress bar's minimum is not `0` or the maximum value is not `100`. +- The read-only [`aria-valuenow`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-valuenow) should be provided and updated unless the value is `indeterminate`, in which case don't include the attribute. If set, make sure the `aria-valuenow` value is between the minimum and maximum values. + +If the `progressbar` role is applied to an HTML {{HTMLElement('progress')}} element, the accessible name can come from the associated {{HTMLElement('label')}}. Otherwise use [`aria-labelledby`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-labelledby) if a visible label is present or [`aria-label`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-label) if a visible label is not present. + +### All descendants are presentational + +There are some types of user interface components that, when represented in a platform accessibility API, can only contain text. Accessibility APIs do not have a way of representing semantic elements contained in a `progressbar`. To deal with this limitation, browsers, automatically apply role [`presentation`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/presentation_role) to all descendant elements of any `progressbar` element as it is a role that does not support semantic children. + +For example, consider the following `progressbar` element, which contains a heading. + +```html +<div role="progressbar"><h3>Title of my progressbar</h3></div> +``` + +Because descendants of `progressbar` are presentational, the following code is equivalent: + +```html +<div role="progressbar"> + <h3 role="presentation">Title of my progressbar</h3> +</div> +``` + +From the assistive technology user's perspective, the heading does not exist since the previous code snippets are equivalent to the following in the [accessibility tree](/en-US/docs/Glossary/Accessibility_tree): + +```html +<div role="progressbar">Title of my progressbar</div> +``` + +### Associated WAI-ARIA roles, states, and properties + +- [`aria-valuenow`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-valuenow) + - : Only present and required if the value is not indeterminate. Set to a decimal value between `0`, or `aria-valuemin` if present, and `aria-valuemax` indicating the current value of the progress bar. +- [`aria-valuetext`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-valuetext) + - : Assistive technologies often present the value of `aria-valuenow` as a percentage. If this would not be accurate use this property to make the progress bar value understandable. +- [`aria-valuemin`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-valuemin) + - : Set to a decimal value representing the minimum value, and less than `aria-valuemax`. If not present, the default value is `0`. +- [`aria-valuemax`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-valuemax) + - : Set to a decimal value representing the maximum value, and greater than `aria-valuemin`. If not present, the default value is `100`. +- [`aria-label`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-label) or [`aria-labelledby`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-labelledby) + - : Defines the string value or identifies the element (or elements) that label the progressbar element providing an accessible name. An accessible name is required. + +It is recommended to use a native {{HTMLElement("progress")}} or [`<input type="range">`](/en-US/docs/Web/HTML/Reference/Elements/input/range) elements rather than the `progressbar` role. User agents provide a stylize widget for the {{HTMLElement("progress")}} element based on the current `value` as it relates to the `0`, the minimum value, and the `max` value. When using non-semantic elements, all features of the native semantic element need to be recreated with ARIA attributes, JavaScript and CSS. + +## Examples + +In the example below, the progress bar uses the default values of 0 and 100 for `aria-valuemin` and `aria-valuemax`: + +```html +<div> + <span id="loadinglabel">Loading:</span> + <span role="progressbar" aria-labelledby="loadinglabel" aria-valuenow="23"> + <svg width="100" height="10"> + <rect height="10" width="100" stroke="black" fill="black" /> + <rect height="10" width="23" fill="white" /> + </svg> + </span> +</div> +``` + +Using semantic HTML, this could be written as: + +```html +<label for="loadinglabel">Loading:</label> +<progress id="loadinglabel" max="100" value="23"></progress> +``` + +## Best practices + +If the progress bar is describing the loading progress of a particular region of a page, include the [`aria-describedby`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-describedby) attribute to reference the progress bar's status, and set the [`aria-busy`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-busy) attribute to `true` on the region until it is finished loading. + +### Prefer HTML + +It is recommended to use a native {{HTMLElement("progress")}} or [`<input type="range">`](/en-US/docs/Web/HTML/Reference/Elements/input/range) elements rather than the `progressbar` role. + +## Specifications + +{{Specifications}} + +## See also + +- HTML {{HTMLElement('progress')}} element +- Other range widgets include: + - [`meter`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/meter_role) + - [`scrollbar`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/scrollbar_role) + - [`separator`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/separator_role) (if focusable) + - [`slider`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/slider_role) + - [`spinbutton`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/spinbutton_role) diff --git a/files/en-us/web/accessibility/aria/reference/roles/radio_role/index.md b/files/en-us/web/accessibility/aria/reference/roles/radio_role/index.md new file mode 100644 index 000000000000000..5d040cb02bbfee3 --- /dev/null +++ b/files/en-us/web/accessibility/aria/reference/roles/radio_role/index.md @@ -0,0 +1,301 @@ +--- +title: "ARIA: radio role" +short-title: radio +slug: Web/Accessibility/ARIA/Reference/Roles/radio_role +page-type: aria-role +sidebar: accessibilitysidebar +--- + +The `radio` role is one of a group of checkable radio buttons, in a `radiogroup`, where no more than a single radio button can be checked at a time. + +## Description + +A radio button is a checkable input that when associated with other radio buttons, only one of which can be checked at a time. The radio buttons must be grouped together in a [`radiogroup`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/radiogroup_role) to indicate which ones affect the same value. + +```html +<div role="radiogroup" aria-labelledby="legend25" id="radiogroup25"> + <p id="legend25">Ipsum and lorem?</p> + <div> + <span + role="radio" + aria-checked="false" + tabindex="0" + aria-labelledby="q25_radio1-label" + data-value="True"></span> + <label id="q25_radio1-label">True</label> + </div> + <div> + <span + role="radio" + aria-checked="false" + tabindex="0" + aria-labelledby="q25_radio2-label" + data-value="False"></span> + <label id="q25_radio2-label">False</label> + </div> + <div> + <span + role="radio" + aria-checked="true" + tabindex="0" + aria-labelledby="q25_radio3-label" + data-value="huh?"></span> + <label id="q25_radio3-label">What is the question?</label> + </div> +</div> +``` + +The `role` attribute only adds semantics; all of the functionality that comes natively with the [HTML radio](/en-US/docs/Web/HTML/Reference/Elements/input/radio) needs to be added with JavaScript and the HTML [`tabindex`](/en-US/docs/Web/HTML/Reference/Global_attributes/tabindex) attribute. + +> [!NOTE] +> The first rule of ARIA is if a native HTML element or attribute has the semantics and behavior you require, use it instead of re-purposing an element and adding ARIA. Instead use the native [HTML `<input type="radio">`](/en-US/docs/Web/HTML/Reference/Elements/input/radio) (with an associated {{HTMLElement('label')}}), which natively provides all the functionality required: + +```html +<fieldset> + <legend>Ipsum and lorem?</legend> + <div> + <input type="radio" value="True" id="q25_radio1" name="q25" /> + <label for="q25_radio1">True</label> + </div> + <div> + <input type="radio" value="False" id="q25_radio2" name="q25" /> + <label for="q25_radio2">False</label> + </div> + <div> + <input type="radio" value="huh?" id="q25_radio3" name="q25" checked /> + <label for="q25_radio3">What is the question?</label> + </div> +</fieldset> +``` + +The native HTML radio form control ([`<input type="radio">`](/en-US/docs/Web/HTML/Reference/Elements/input/radio)) has two states ("checked" or "not checked"). Similarly, an element with `role="radio"` can expose two states through the [`aria-checked`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-checked) attribute: `true` representing the checked state, and `false` representing the unchecked state. The `aria-checked` value of `mixed` is not valid to use for a radio button. + +If a radio button is checked, the radio element has `aria-checked` set to `true`. If it is not checked, it has `aria-checked` set to `false`. + +Each radio button element has role `radio`. The radio role should always be nested with other associated radios in a `radiogroup`. If it is not possible to nest the radio button within a radio group, use the `id` of the non-grouped radio in a space separated list of values as the value of the [`aria-owns`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-owns) attribute on the `radiogroup` element to indicate the relationship of the `radiogroup` to its radio members. + +Each radio element is labelled by its content, has a visible label referenced by `aria-labelledby`, or has a label specified with `aria-label`. The containing `radiogroup` element should either have a visible label referenced by `aria-labelledby` or a label specified with `aria-label`. If elements providing additional information about either the radio group or each radio button are present, those elements should be referenced by the `radiogroup` element or radio elements with the [`aria-describedby`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-describedby) property. + +As `radio` is an interactive control; it must be focusable and keyboard accessible. If the role is applied to a non-focusable element, use the [`tabindex`](/en-US/docs/Web/HTML/Reference/Global_attributes/tabindex) attribute to change this. The expected keyboard shortcut for activating a radio is the <kbd>Space</kbd> key. Use JavaScript to toggle the `aria-checked` attribute to `true` when a radio becomes checked while ensuing that all the other radio roles in the group are set to `aria-checked="false"`. + +To programmatically indicate that a radio button must be chosen from a radio group the [`aria-required`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-required) attribute, with a value of `true`, must be specified on the `radiogroup` element. It is not expected to use the `aria-required` attribute on individual ARIA radio buttons. + +### All descendants are presentational + +There are some types of user interface components that, when represented in a platform accessibility API, can only contain text. Accessibility APIs do not have a way of representing semantic elements contained in a `radio`. To deal with this limitation, browsers, automatically apply role [`presentation`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/presentation_role) to all descendant elements of any `radio` element as it is a role that does not support semantic children. + +For example, consider the following `radio` element, which contains a heading. + +```html +<div role="radio"><h6>name of my radio</h6></div> +``` + +Because descendants of `radio` are presentational, the following code is equivalent: + +```html +<div role="radio"><h6 role="presentation">name of my radio</h6></div> +``` + +From the assistive technology user's perspective, the heading does not exist since the previous code snippets are equivalent to the following in the [accessibility tree](/en-US/docs/Glossary/Accessibility_tree): + +```html +<div role="radio">name of my radio</div> +``` + +### Associated WAI-ARIA roles, states, and properties + +- [`radiogroup`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/radiogroup_role) role + + - : The radio buttons are contained in or owned by an element with role `radiogroup`. If unable to be nested within a `radiogroup` within the markup, the `aria-owns` attribute of the `radiogroup` contains the `id` values of the non-nested radio buttons in the group. + +- [`aria-checked`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-checked) + + - : The value of `aria-checked` defines the state of a radio. When used with radio elements, the attribute has one of two possible values: + + - `true` + - : The radio is checked. + - `false` + - : The radio is not checked. + +> [!NOTE] +> Use the [`tabindex` attribute](/en-US/docs/Web/HTML/Reference/Global_attributes/tabindex) if the `role="radio"` is used on an element that does not natively accept keyboard focus. E.g., a `<div>` or `<span>`. + +### Keyboard interactions + +- <kbd>Tab</kbd> + <kbd>Shift</kbd> + + - : Move focus into and out of the radio group. When focus moves into a radio group, and a radio button is already checked, focus is set on the checked button. If none of the radio buttons are checked, focus is set on the first radio button in the group. + +- <kbd>Space</kbd> + + - : Checks the radio if not already checked. Unchecks a previously checked radio button in the radio group. + +- <kbd>Right Arrow</kbd> and <kbd>Down Arrow</kbd> + + - : Move focus to and checks the next radio button in the group, unchecking the previously focused radio button. If focus is on the last radio button, focus moves to the first radio button. + +- <kbd>Left Arrow</kbd> and <kbd>Up Arrow</kbd> + - : Move focus to and checks the previous radio button in the group, unchecking the previously focused radio button. If focus is on the first radio button, focus moves to the last radio button. + +### Radios in a toolbar + +Because arrow keys are used to navigate among elements of a toolbar and the <kbd>Tab</kbd> key moves focus in and out of a toolbar, when a radio group is nested inside a toolbar, the keyboard interaction of the radio group is slightly different from that of a radio group that is not inside of a toolbar. See [`radiogroup` keyboard interactions](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/radiogroup_role#keyboard_interactions) for more information + +## Required JavaScript + +- `onClick` + - : Handle mouse clicks on both the radio and the associated label that will change the state of the radio by changing the value of the `aria-checked` attribute and the appearance of the radio so it appears checked or unchecked to the sighted user +- `onKeyPress` + - : Handle the case where the user presses the <kbd>Space</kbd> key to change the state of the radio by changing the value of the `aria-checked` attribute and the appearance of the radio so it appears checked or unchecked to the sighted user + +## Examples + +The following example uses ARIA to modify otherwise generic elements to be exposed as radio buttons. CSS and JavaScript are used to visually and programmatically modify the checked or unchecked state of the element. + +### HTML + +```html +<div role="radiogroup" aria-labelledby="legend" id="radiogroup"> + <p id="legend"> + Should you be using the <code>radio</code> role or + <code>&lt;input type="radio"></code>? + </p> + <div> + <span + role="radio" + aria-checked="true" + tabindex="0" + aria-labelledby="ariaLabel" + data-value="True"></span> + <label id="ariaLabel">ARIA role</label> + </div> + <div> + <span + role="radio" + aria-checked="false" + tabindex="0" + aria-labelledby="htmllabel" + data-value="False"></span> + <label id="htmllabel">HTML <code>&lt;input type="radio"></code></label> + </div> +</div> +``` + +### CSS + +```css +[role="radio"] { + padding: 5px; +} + +[role="radio"][aria-checked="true"]::before { + content: "(x)"; + font-family: monospace; +} + +[role="radio"][aria-checked="false"]::before { + content: "( )"; + font-family: monospace; +} +``` + +### JavaScript + +A lot of JavaScript is required to make radio buttons out of non-semantic HTML. + +```js +// initialize all the radio role elements + +const radioGroups = document.querySelectorAll('[role="radiogroup"]'); + +for (const radioGroup of radioGroups) { + const radios = radioGroup.querySelectorAll("[role=radio]"); + for (const radio of radios) { + radio.addEventListener("keydown", handleKeydown); + radio.addEventListener("click", handleClick); + } +} + +// handle mouse and touch events +function handleClick(event) { + setChecked(this); + event.stopPropagation(); + event.preventDefault(); +} + +// handle key presses +function handleKeydown(event) { + switch (event.code) { + case "Space": + case "Enter": + currentChecked(); + break; + + case "ArrowUp": + case "ArrowLeft": + previousRadioChecked(); + break; + + case "ArrowDown": + case "ArrowRight": + nextItemChecked(); + break; + + default: + break; + } + event.stopPropagation(); + event.preventDefault(); +} + +// when a radio is selected, give it focus, set checked to true; +// ensure all other radios in radio group are not checked + +function setChecked() { + // uncheck all the radios in group + // iterated through all the radios in radio group + // eachRadio.tabIndex = -1; + // eachRadio.setAttribute('aria-checked', 'false'); + // set the selected radio to checked + // thisRadio.setAttribute('aria-checked', 'true'); + // thisRadio.tabIndex = 0; + // thisRadio.focus(); + // set the value of the radioGroup to the value of the currently selected radio +} +``` + +<!-- {{EmbedLiveSample("Examples", 230, 250)}} --> + +No JavaScript (or even CSS) would be needed had we used semantic HTML element with the name of each radio button in a group of radio buttons being the same: + +```html +<fieldset> + <legend> + Should you be using the <code>radio</code> role or + <code>&lt;input type="radio"></code>? + </legend> + <div> + <input type="radio" name="bestPractices" id="ariaLabel" value="True" /> + <label for="ariaLabel">ARIA role</label> + </div> + <div> + <input type="radio" name="bestPractices" id="htmllabel" value="False" /> + <label for="htmllabel">HTML <code>&lt;input type="radio"></code></label> + </div> +</fieldset> +``` + +## Best practices + +The first rule of ARIA is: if a native HTML element or attribute has the semantics and behavior you require, use it instead of re-purposing an element and adding an ARIA role, state or property to make it accessible. As such, it is recommended to use native [HTML radio button](/en-US/docs/Web/HTML/Reference/Elements/input/radio) form controls instead of recreating a radio's functionality with JavaScript and ARIA. + +## See also + +- [HTML `<input type="radio">` radio button](/en-US/docs/Web/HTML/Reference/Elements/input/radio) +- [HTML `tabindex` attribute](/en-US/docs/Web/HTML/Reference/Global_attributes/tabindex) +- [ARIA: `radiogroup` role](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/radiogroup_role) +- [ARIA: `checkbox` role](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/checkbox_role) +- [ARIA: `menuitem` role](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/menuitem_role) +- [ARIA: `menuitemradio` role](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/menuitemradio_role) +- [ARIA: `menuitemradio` role](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/menuitemradio_role) +- [ARIA: `option` role](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/option_role) diff --git a/files/en-us/web/accessibility/aria/reference/roles/radiogroup_role/index.md b/files/en-us/web/accessibility/aria/reference/roles/radiogroup_role/index.md new file mode 100644 index 000000000000000..e23ca2248e1233f --- /dev/null +++ b/files/en-us/web/accessibility/aria/reference/roles/radiogroup_role/index.md @@ -0,0 +1,154 @@ +--- +title: "ARIA: radiogroup role" +short-title: radiogroup +slug: Web/Accessibility/ARIA/Reference/Roles/radiogroup_role +page-type: aria-role +spec-urls: + - https://w3c.github.io/aria/#radiogroup + - https://www.w3.org/WAI/ARIA/apg/patterns/radio/examples/radio/ +sidebar: accessibilitysidebar +--- + +The `radiogroup` role is a group of `radio` buttons. + +## Description + +Radio groups are collections describing a set of related [`radio`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/radio_role) options. A `radiogroup` is a type of [`select`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/select_role) list that can only have a single entry, or `radio`, checked at any one time. + +When using HTML's native input radio button, [`<input type="radio">`](/en-US/docs/Web/HTML/Reference/Elements/input/radio), the radio buttons are grouped when each of input radio buttons in the group is given the same [`name`](/en-US/docs/Web/HTML/Reference/Elements/input#name). Once a group of same-named input radio buttons is established, selecting any input radio button in that group automatically deselects any currently-selected input radio button in the same group. While this will associate the radio buttons together, to expose a grouping of radio buttons as a `radiogroup` explicitly set the ARIA role. + +It is recommended to create radio groups by using same-named HTML input radio buttons, but, if you must use ARIA roles and attributes instead of semantic HTML form controls, custom `radio` buttons can and should act like native HTML radio input buttons. + +When using non-semantic elements as radio buttons, you must ensure your users can only select one radio button from the group at a time. When one item in the group is checked, having their [`aria-checked`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-checked) attribute set to `true`, the previously checked item becomes unchecked, with its `aria-checked` attribute becoming `false`. The `aria-checked` attribute is set on the associated `radio` roles, not on the `radiogroup` itself. + +Some `radiogroup` implementations initialize the set with all buttons in the unchecked state. Once a `radio` in a `radiogroup` is checked, it is generally not possible to return to an all-unchecked state. + +The `radiogroup` must have an accessible name either by a visible label referenced by [`aria-labelledby`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-labelledby) or has a label specified with [`aria-label`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-label). If elements provide additional information about the radio group, those elements are referenced by the `radiogroup` element with the [`aria-describedby`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-describedby) property. + +### Associated WAI-ARIA roles, states, and properties + +- [`radio`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/radio_role) role + - : One of a group of checkable buttons, in a `radiogroup`, where no more than one of the buttons can be checked at a time. +- [`aria-labelledby`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-labelledby) / [`aria-label`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-label) + - : The `radiogroup` must have an accessible name either by a visible label referenced by `aria-labelledby` or has a label specified with `aria-label`. +- [`aria-describedby`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-describedby) + - : Reference to elements providing additional information about the `radiogroup` +- [`aria-required`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-required) + - : Indicates that one `radio` within the group must have `aria-checked="true"` set before the form may be submitted. The required state is specified on the `radiogroup` element rather than one of the `radio` elements, unlike when using HTML radio buttons where the [`required`](/en-US/docs/Web/HTML/Reference/Attributes/required) attribute is set directly on one or more radio {{HTMLElement('input')}} elements. +- [`aria-errormessage`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-errormessage) + - : Identifies the element that provides an error message for the `radiogroup`, if there is an error. That message should be hidden while not relevant. + +### Keyboard interactions + +For `radio` buttons in a `radiogroup` that is NOT in a [`toolbar`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/toolbar_role), the following keyboard interactions must be supported: + +- <kbd>Tab</kbd> and <kbd>Shift + Tab</kbd> + - : Move focus into and out of the `radiogroup`. When focus moves into a `radiogroup`, if a radio button is checked, focus is set on the checked button. If none of the radio buttons are checked, focus is set on the first radio button in the group. +- <kbd>Space</kbd> + - : Checks the focused radio button if it is not already checked. +- <kbd>Right Arrow</kbd> and <kbd>Down Arrow</kbd> + - : Moves focus to the next radio button in the group, unchecking the previously focused button, and checking the newly focused button. If focus is on the last button, focus moves to the first button. +- <kbd>Left Arrow</kbd> and <kbd>Up Arrow</kbd> + - : Moves focus to the previous radio button in the group, unchecking the previously focused button, and checking the newly focused button. If focus is on the first button, focus moves to the last button. + +Arrow keys are used to navigate among elements of a toolbar. When a `radiogroup` is nested inside a toolbar, users need to be able to navigate among all toolbar elements, including the radio buttons, without changing which radio button is checked. So, when navigating through a `radiogroup` in a [`toolbar`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/toolbar_role) with arrow keys, the button that is checked does not change. Rather, when inside a `toolbar`, the <kbd>Space</kbd> and <kbd>Enter</kbd> keys check the focused `radio` button if it is not already checked, with <kbd>Tab</kbd> moving focus into and out of the `toolbar`. + +### Required JavaScript features + +User interactions for `radiogroup`s must replicate the user interaction of a user entering into a group of same-named HTML radio buttons. Keyboard events for tabs, space, and arrow keys must be captured. Click events on both the radio elements and their associated labels must also be captured. Additionally, [focus must be managed](https://usability.yale.edu/web-accessibility/articles/focus-keyboard-operability). + +While generally moving off an a focused element brings you to the next focusable element in the DOM order, using the arrow keys to navigate through a group of radio button keeps you in the group, moving focus to the first radio button when the <kbd>Right Arrow</kbd> or <kbd>Down Arrow</kbd> is released when focus was on the last radio in the group, and moving to the last radio if the <kbd>Left Arrow</kbd> or <kbd>Up Arrow</kbd> is released if focus was on the first radio. Managing roving [`tabindex`](/en-US/docs/Web/HTML/Reference/Global_attributes/tabindex) is one method to manage arrow key events. + +### Required CSS features + +Use the `[aria-checked="true"]` [attribute selector](/en-US/docs/Web/CSS/Attribute_selectors) to style the checked state of checked radio buttons. + +Use CSS {{CSSXRef(':hover')}} and {{CSSXRef(':focus')}} pseudo-classes for styling visual keyboard focus and hover. The focus and hover effect should encompass both the radio button and label to make it easier to perceive which option is being chosen and to indicate that clicking either the label or button will activate the radio button. + +## Examples + +The basic set up for a `radiogroup` using non-semantic ARIA roles instead of semantic HTML is as follows: + +```html +<div role="radiogroup" aria-labelledby="question"> + <div id="question">Which is the best color?</div> + <div id="radioGroup"> + <p> + <span + id="colorOption_0" + tabindex="0" + role="radio" + aria-checked="false" + aria-labelledby="purple"></span> + <span id="purple">Purple</span> + </p> + <p> + <span + id="colorOption_1" + tabindex="-1" + role="radio" + aria-checked="false" + aria-labelledby="aubergine"></span> + <span id="aubergine">Aubergine</span> + </p> + <p> + <span + id="colorOption_2" + tabindex="-1" + role="radio" + aria-checked="false" + aria-labelledby="magenta"></span> + <span id="magenta">Magenta</span> + </p> + <p> + <span + id="colorOption_3" + tabindex="-1" + role="radio" + aria-checked="false" + aria-labelledby="all"></span> + <span id="all">All of the above</span> + </p> + </div> +</div> +``` + +This could have been written using semantic HTML, which requires no CSS or JavaScript: + +```html +<fieldset> + <legend>Which is the best color?</legend> + <p> + <input name="colorOption" type="radio" id="purple" /> + <label for="purple">Purple</label> + </p> + <p> + <input name="colorOption" type="radio" id="aubergine" /> + <label for="aubergine">Aubergine</label> + </p> + <p> + <input name="colorOption" type="radio" id="magenta" /> + <label for="magenta">Magenta</label> + </p> + <p> + <input name="colorOption" type="radio" id="all" /> + <label for="all">All of the above</label> + </p> +</fieldset> +``` + +In this {{HTMLElement('fieldset')}} example, while `role="radiogroup"` is not necessary, to have this grouping explicitly announced as `radiogroup`, include the ARIA role. + +## Specifications + +{{Specifications}} + +## See also + +- HTML {{HTMLElement('fieldset')}} element +- HTML {{HTMLElement('input/radio', '&lt;input type="radio">')}} radio button element +- [ARIA `radio` role](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/radio_role) +- [`aria-errormessage`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-errormessage) +- [`aria-invalid`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-invalid) +- [`aria-readonly`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-readonly) +- [`aria-required`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-required) diff --git a/files/en-us/web/accessibility/aria/reference/roles/range_role/index.md b/files/en-us/web/accessibility/aria/reference/roles/range_role/index.md new file mode 100644 index 000000000000000..804a958d3fada43 --- /dev/null +++ b/files/en-us/web/accessibility/aria/reference/roles/range_role/index.md @@ -0,0 +1,33 @@ +--- +title: "ARIA: range role" +short-title: range +slug: Web/Accessibility/ARIA/Reference/Roles/range_role +page-type: aria-role +spec-urls: https://w3c.github.io/aria/#range +sidebar: accessibilitysidebar +--- + +The `range` abstract role is a generic type of structure role representing a range of values. + +> [!WARNING] +> The `range` role is an [abstract role](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles#6._abstract_roles). It is included here for completeness of documentation. It is not to be used by web authors. + +## Description + +The `range` role is an abstract role. It must not be used by web authors. It is the superclass for structural roles for elements that accept a value within a range of values, including the [`meter`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/meter_role) role, [`progressbar`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/progressbar_role) and [`slider`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/slider_role). For these three, consider using the {{HTMLElement("meter")}} element, the {{HTMLElement("progress")}} element, and the {{HTMLElement("input/range")}}, respectively. + +## Specifications + +{{Specifications}} + +## See also + +- [ARIA: `structure` role](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/structure_role) +- [ARIA: `meter` role](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/meter_role) +- [ARIA: `progressbar` role](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/progressbar_role) +- [ARIA: `scrollbar` role](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/scrollbar_role) +- [ARIA: `slider` role](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/slider_role) +- [ARIA: `spinbutton` role](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/spinbutton_role) +- {{HTMLElement("input/range")}} +- {{HTMLElement("meter")}} +- {{HTMLElement("progress")}} diff --git a/files/en-us/web/accessibility/aria/reference/roles/region_role/index.md b/files/en-us/web/accessibility/aria/reference/roles/region_role/index.md new file mode 100644 index 000000000000000..99f4c0c3e5670f6 --- /dev/null +++ b/files/en-us/web/accessibility/aria/reference/roles/region_role/index.md @@ -0,0 +1,102 @@ +--- +title: "ARIA: region role" +short-title: region +slug: Web/Accessibility/ARIA/Reference/Roles/region_role +page-type: aria-role +spec-urls: + - https://w3c.github.io/aria/#region + - https://www.w3.org/WAI/ARIA/apg/patterns/landmarks/examples/region.html +sidebar: accessibilitysidebar +--- + +The **`region`** role is used to identify document areas the author deems significant. It is a generic landmark available to aid in navigation when none of the other landmark roles are appropriate. + +```html +<div role="region" aria-label="Example"> + <!-- region content --> +</div> +``` + +## Description + +The `region` role is an [ARIA landmark](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles#3._landmark_roles) role. +The `region` role should be reserved for sections of content sufficiently important that users will likely want to navigate to the section easily and to have it listed in a summary of the page. A region role is a more generic term, and should only be used if the section needing to be identified is not accurately described by one of the other landmark roles, such as [`banner`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/banner_role), [`main`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/main_role), [`contentinfo`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/contentinfo_role), [`complementary`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/complementary_role), or [`navigation`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/navigation_role). + +Every element with a `region` role should include a label that describes the purpose of the content in the region, preferably with an [`aria-labelledby`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-labelledby) referencing a visible header. If no visible appropriate header is present, [`aria-label`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-label) should be used. + +The `region` landmark role's content should make sense if separated from the main content of the document. + +Using the {{HTMLElement('section')}} element will automatically communicate a section has a role of `region` if it is given an accessible name. Developers should always prefer using the correct semantic HTML element, in this case `<section>`, over using ARIA. + +### Associated WAI-ARIA roles, states, and properties + +- [`aria-labelledby`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-labelledby) or [`aria-label`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-label) + - : Use this attribute to label the region. Often, the value of the `aria-labelledby` attribute will be the id of the element used to title the section. If no visible appropriate header is present, `aria-label` should be used. + +## Examples + +```html +<div role="region" aria-labelledby="region-heading"> + <h2 id="region-heading"> + This heading's `id` attribute helps this region have an accessible name + </h2> + <!-- region content --> +</div> +``` + +## Accessibility concerns + +Use sparingly! [Landmark roles](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles#3._landmark_roles) are intended to be used sparingly, to identify larger overall sections of the document. Using too many landmark roles can create "noise" in screen readers, making it difficult to understand the overall layout of the page. + +Only use the `region` role if no other relevant [content sectioning](/en-US/docs/Web/HTML/Reference/Elements#content_sectioning) element or [landmark role](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles#3._landmark_roles) applies. If multiple regions exist on a page, it may be worth reinvestigating the page's overall structure. + +## Best practices + +### Prefer HTML + +Using the {{HTMLElement('section')}} element will automatically communicate that a section has a role of `region` if it is given an accessible name. If at all possible, prefer using {{HTMLElement('section')}} instead. + +### Labeling landmarks + +If there is more than one `region` landmark role in a document, provide a unique label for each one. This label will allow an assistive technology user to be able to quickly understand the purpose of each landmark. + +```html +<div role="region" aria-labelledby="use-discretion"> + <h3 id="use-discretion">Please use the `region` role with discretion</h3> + <!-- content --> +</div> + +… + +<div role="region" aria-labelledby="please-reconsider"> + <h3 id="please-reconsider">Please reconsider your document structure</h3> + <!-- content --> +</div> +``` + +In this example, the region's label is being generated by the [`aria-labelledby` attribute](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-labelledby). + +### Scrolling content areas with overflow text + +If there is a content area with `tabindex="0"`, add `role="region"` to convey to screen reader users that is a generic region. This is done to allow keyboard-only users to scroll regions with overflow text. + +### SVG + +`role="region"` can be declared on areas of {{SVGElement('svg')}} along with an `aria-label` to allow individual sections of the SVG to be described. + +## Specifications + +{{Specifications}} + +## See also + +- The {{HTMLElement('section')}} element +- [region (role): Accessible Rich Internet Applications (WAI-ARIA) 1.1](https://www.w3.org/TR/wai-aria/#region) +- [ARIA: `banner` role](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/banner_role) +- [ARIA: `main` role](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/main_role) +- [ARIA: `contentinfo` role](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/contentinfo_role) +- [ARIA: `complementary` role](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/complementary_role) +- [ARIA: `navigation` role](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/navigation_role) +- [Landmark roles: Using ARIA: Roles, States, and Properties](/en-US/docs/Web/Accessibility/ARIA/Guides/Techniques#landmark_roles) +- [Using WAI-ARIA Landmarks – 2013 | The Paciello Group](https://www.tpgi.com/using-wai-aria-landmarks-2013/) +- [Accessible Landmarks | scottohara.me](https://www.scottohara.me/blog/2018/03/03/landmarks.html) diff --git a/files/en-us/web/accessibility/aria/reference/roles/roletype_role/index.md b/files/en-us/web/accessibility/aria/reference/roles/roletype_role/index.md new file mode 100644 index 000000000000000..f366e25642286de --- /dev/null +++ b/files/en-us/web/accessibility/aria/reference/roles/roletype_role/index.md @@ -0,0 +1,28 @@ +--- +title: "ARIA: roletype role" +short-title: roletype +slug: Web/Accessibility/ARIA/Reference/Roles/roletype_role +page-type: aria-role +spec-urls: https://w3c.github.io/aria/#roletype +sidebar: accessibilitysidebar +--- + +The **`roletype`** role, an [abstract role](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles#6._abstract_roles), is the base role from which all other ARIA roles inherit. + +> [!WARNING] +> The `roletype` role is an abstract role used for the ontology. It is included here for completeness of documentation. It should not be used by web authors. + +## Description + +The `roletype` role's properties describe the structural and functional purpose of objects that are assigned this role, or "instances". A role is a concept that can be used to understand and operate instances. + +## Specifications + +{{Specifications}} + +## See also + +- [ARIA: `structure` role](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/structure_role) +- [ARIA: `widget` role](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/widget_role) +- [ARIA: `window` role](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/window_role) +- The HTML [`rel`](/en-US/docs/Web/HTML/Reference/Attributes/rel) attribute diff --git a/files/en-us/web/accessibility/aria/reference/roles/row_role/index.md b/files/en-us/web/accessibility/aria/reference/roles/row_role/index.md new file mode 100644 index 000000000000000..586731dd7ae45e3 --- /dev/null +++ b/files/en-us/web/accessibility/aria/reference/roles/row_role/index.md @@ -0,0 +1,226 @@ +--- +title: "ARIA: row role" +short-title: row +slug: Web/Accessibility/ARIA/Reference/Roles/row_role +page-type: aria-role +spec-urls: + - https://w3c.github.io/aria/#row + - https://www.w3.org/WAI/ARIA/apg/patterns/table/examples/table/ +sidebar: accessibilitysidebar +--- + +An element with `role="row"` is a row of cells within a tabular structure. A row contains one or more cells, grid cells or column headers, and possibly a row header, within a [`grid`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/grid_role), [`table`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/table_role) or [`treegrid`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/treegrid_role), and optionally within a [`rowgroup`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/rowgroup_role). + +```html +<div + role="table" + aria-label="Populations" + aria-describedby="country_population_desc"> + <div id="country_population_desc">World Populations by Country</div> + <div role="rowgroup"> + <div role="row"> + <span role="columnheader" aria-sort="descending">Country</span> + <span role="columnheader" aria-sort="none">Population</span> + </div> + </div> + <div role="rowgroup"> + <div role="row"> + <span role="cell">Finland</span> + <span role="cell">5.5 million</span> + </div> + <div role="row"> + <span role="cell">France</span> + <span role="cell">67 million</span> + </div> + </div> +</div> +``` + +## Description + +The element with `role="row"` is a row within a [`grid`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/grid_role), [`table`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/table_role), or [`treegrid`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/treegrid_role), and optionally within a [`rowgroup`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/rowgroup_role) that contains one or more [`cell`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/cell_role), [`gridcell`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/gridcell_role), [`columnheader`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/columnheader_role), or [`rowheader`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/rowheader_role) elements within a static tabular structure. Using native [HTML `<tr>`](/en-US/docs/Web/HTML/Reference/Elements/tr) elements, whenever possible, is strongly encouraged. + +To create an ARIA row, add `role="row"` to the container element. That row should be nested within a grid, table or treegrid. A group of rows can be nested within a grid, table or treegrid directly, or within a rowgroup in one of those containers. Each row contains child cells. These cells can be of different types, depending on whether they are column or row headers, or grid or regular cells. + +A row can contain a number of attributes clarifying the row's role, including [`aria-colindex`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-colindex), [`aria-level`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-level), [`aria-rowindex`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-rowindex), and [`aria-selected`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-selected). + +If the row is within a treegrid, rows can include the [`aria-expanded`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-expanded) attribute, using the attribute to indicate the present status. This is not the case for an ordinary table or grid, in which the `aria-expanded` attribute is not present. + +To create an interactive widget that has a tabular structure, use the grid pattern instead. If the interaction provides for the selection state of individual cells, if left to right and top to bottom navigation is provided, or if the user interface allows the rearranging of cell order or otherwise changing individual cell order such as through drag and drop, use [grid](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/grid_role) or [treegrid](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/treegrid_role) instead. + +> [!NOTE] +> Using the native HTML table element ({{HTMLElement('table')}}) along with the table row element ({{HTMLElement('tr')}}) whenever possible is strongly encouraged. + +### Associated WAI-ARIA roles, states, and properties + +#### Context roles + +- [role="rowgroup"](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/rowgroup_role) + - : An optional contextual row parent, it establishes a relationship between descendant rows. It is a structural equivalent to the thead, tfoot, and tbody elements in an HTML table element. +- [role="table"](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/table_role) + - : One of the three possible contexts (along with grid and treegrid) in which you'll find a row, it identifies the row as being part of a non-interactive table structure containing data arranged in rows and columns, similar to the native {{HTMLElement('table')}} HTML element. +- [role="grid"](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/grid_role) + - : One of the three possible contexts (along with table and treegrid) in which you'll find a row, it identifies the row as being part of a non-interactive table structure containing data arranged in rows and columns, similar to the native {{HTMLElement('table')}} HTML element. +- [role="treegrid"](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/treegrid_role) + - : Similar to a grid, but with rows that can be expanded and collapsed in the same manner as for a tree. + +#### Descendant roles + +- [role="cell"](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/cell_role) + - : A cell in a row within a tabular container. +- [role="gridcell"](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/gridcell_role) + - : A cell in a row within a grid or treegrid. +- [role="columnheader"](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/columnheader_role) + - : A header cell that is the structural equivalent of the HTML {{HTMLElement('th')}} element with a column scope ({{HTMLElement('tr', '<code>&lt;tr scope="col"&gt;</code>')}}). Unlike a plain cell, the columnheader role establishes a relationship between it and all cells in the corresponding column. +- [role="rowheader"](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/rowheader_role) + - : A header cell that is the structural equivalent of the HTML {{HTMLElement('th')}} element with a row scope ({{HTMLElement('tr', '<code>&lt;tr scope="row"&gt;</code>')}}). Unlike a plain cell, the rowheader role establishes a relationship between it and all cells in the corresponding row. + +#### States and properties + +- [`aria-expanded`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-expanded) state + + - : The `aria-expanded` attribute, which defines the state of the row, can take one of three values, or be omitted: + + - `aria-expanded="true"`: Row is currently expanded. + - `aria-expanded="false"`: Row is currently collapsed. + - `aria-expanded="undefined"` or the attribute is missing: The row is neither expandable nor collapsible. + + If the element with the `aria-expanded` attribute controls the expansion of another grouping container that is not 'owned by' the element, the author **should** reference the container by using the `aria-controls` attribute. + +- [`aria-selected`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-selected) state + + - : Only relevant if the row is in an interactive container, such as a grid or treegrid, but not relevant if the row is in a table. The `aria-selected` attribute can take one of three values, or be omitted: + + - `aria-selected="true"`: Row is currently selected + - `aria-selected="false"`: Row is not currently selected. + - `aria-selected="undefined"` or the attribute is missing: The row is not selectable. + +- [`aria-colindex`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-colindex) attribute + + - : The `aria-colindex` attribute is only needed if columns are hidden from the DOM. It is generally placed on row children, rather than on the row itself. If the columns displayed are contiguous, then it can be placed on the row. + + The attribute takes as its value an integer between 1 and the total number of columns within the table, grid or treegrid. When placed on the row, the `aria-colindex` defines an element's column index or position with respect to the total number of columns within a row. For example, in a table with 15 columns, and columns 4, 5, and 6 are in the DOM, `aria-colindex="4"` could be set on every row. + + If the set of columns which is present in the DOM is **not** contiguous, or if there are cells spanning more than one row or column, put the `aria-colindex` on all of the children of each row instead of on the row itself. + + If all the columns are in the DOM, this attribute is not necessary. + +- [`aria-rowindex`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-rowindex) attribute + + - : The `aria-rowindex` attribute is only needed if rows are hidden from the DOM, to indicate which row, in the list of total rows, is being read. The attribute, placed with a unique value on each row, takes as its value an integer between 1 and the total number of rows within the table, grid or treegrid, indicating the position, or index, of each row. For example, if a table has 1,500 rows, but only the header and rows 47 and 52 are in the DOM, `aria-rowindex="1"` would be set on the header row, and `aria-rowindex="47"` and `aria-rowindex="52"` would be set on the 47th and 52nd row, respectively. + + If all the rows are present in the DOM, this attribute is not necessary. + +### Keyboard interactions + +None. + +### Required JavaScript features + +None. For sortable columns, see the [`columnheader`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/columnheader_role) aria role. + +> [!NOTE] +> The first rule of ARIA use is you can use a native feature with the semantics and behavior you require already built in, instead of re-purposing an element and **adding** an ARIA role, state or property to make it accessible, then do so. Employ the HTML {{HTMLElement('table')}} element instead of the ARIA role of table whenever possible. + +## Examples + +```html +<div + role="table" + aria-label="Semantic Elements" + aria-describedby="semantic_elements_table_desc" + aria-rowcount="81"> + <div id="semantic_elements_table_desc"> + Semantic Elements to use instead of ARIA's roles + </div> + <div role="rowgroup"> + <div role="row"> + <span role="columnheader" aria-sort="none">ARIA Role</span> + <span role="columnheader" aria-sort="none">Semantic Element</span> + </div> + </div> + <div role="rowgroup"> + <div role="row" aria-rowindex="11"> + <span role="cell">header</span> + <span role="cell">h1</span> + </div> + <div role="row" aria-rowindex="16"> + <span role="cell">header</span> + <span role="cell">h6</span> + </div> + <div role="row" aria-rowindex="18"> + <span role="cell">rowgroup</span> + <span role="cell">thead</span> + </div> + <div role="row" aria-rowindex="24"> + <span role="cell">term</span> + <span role="cell">dt</span> + </div> + </div> +</div> +``` + +The above is a non-semantic ARIA table with five of 81 rows present in the DOM: One within a table header and four rows within the table body. The header row, alone in a header rowgroup, has two column headers. The columns are sortable, but not currently sorted, as indicated by the `aria-sort` property. The table body is in a separate rowgroup, with four rows currently in the DOM. Because not all the rows are in the DOM, we've included the `aria-rowindex` property on every row. + +## Best practices + +Only use {{HTMLElement('table')}}, {{HTMLElement('tbody')}}, {{HTMLElement('thead')}}, {{HTMLElement('tr')}}, {{HTMLElement('th')}}, {{HTMLElement('td')}}, etc., for data table structure. You can add these ARIA roles to ensure accessibility should the native semantics of the table be removed, such as with CSS. A relevant use case for the ARIA table role is when the native semantics of a table are overridden by CSS's display property, such as by display: grid. In this case, you can use the ARIA table roles to add the semantics back in. + +```html +<table + role="table" + aria-label="Semantic Elements" + aria-describedby="semantic_elements_table_desc" + aria-rowcount="81"> + <caption id="semantic_elements_table_desc"> + Semantic Elements to use instead of ARIA's roles + </caption> + <thead role="rowgroup"> + <tr role="row"> + <th role="columnheader" aria-sort="none">ARIA Role</th> + <th role="columnheader" aria-sort="none">Semantic Element</th> + </tr> + </thead> + <tbody role="rowgroup"> + <tr role="row" aria-rowindex="11"> + <td role="cell">header</td> + <td role="cell">h1</td> + </tr> + <tr role="row" aria-rowindex="16"> + <td role="cell">header</td> + <td role="cell">h6</td> + </tr> + <tr role="row" aria-rowindex="18"> + <td role="cell">rowgroup</td> + <td role="cell">thead</td> + </tr> + <tr role="row" aria-rowindex="24"> + <td role="cell">term</td> + <td role="cell">dt</td> + </tr> + </tbody> +</table> +``` + +Above is the semantic way of writing a table. The ARIA roles are only necessary if the native semantics of the table, and therefore the table rows, are obliterated, such as via setting the [display property to flex or grid](/en-US/docs/Web/CSS/display#accessibility). + +### Added benefits + +none + +## Specifications + +{{Specifications}} + +## See also + +- The HTML {{HTMLElement('tr', '<code>&lt;tr&gt;</code> table row')}} element +- {{HTMLElement('table')}} +- [The `rowgroup` role](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/rowgroup_role) +- [The `table` role](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/table_role) +- [The `grid` role](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/grid_role) +- [The `treegrid` role](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/treegrid_role) +- [The `cell` role](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/cell_role) +- [The `gridcell` role](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/gridcell_role) +- [The `columnheader` role](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/columnheader_role) +- [The `rowheader` role](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/rowheader_role) diff --git a/files/en-us/web/accessibility/aria/reference/roles/rowgroup_role/index.md b/files/en-us/web/accessibility/aria/reference/roles/rowgroup_role/index.md new file mode 100644 index 000000000000000..629770c6a7edf2e --- /dev/null +++ b/files/en-us/web/accessibility/aria/reference/roles/rowgroup_role/index.md @@ -0,0 +1,160 @@ +--- +title: "ARIA: rowgroup role" +short-title: rowgroup +slug: Web/Accessibility/ARIA/Reference/Roles/rowgroup_role +page-type: aria-role +spec-urls: https://w3c.github.io/aria/#rowgroup +sidebar: accessibilitysidebar +--- + +An element with `role="rowgroup"` is a group of [rows](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/row_role) within a tabular structure. A `rowgroup` contains one or more rows of [cells](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/cell_role), [grid cells](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/gridcell_role), [column headers](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/columnheader_role), or [row headers](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/rowheader_role) within a [`grid`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/grid_role), [`table`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/table_role) or [`treegrid`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/treegrid_role). + +```html +<div + role="table" + aria-label="Populations" + aria-describedby="country_population_desc"> + <div id="country_population_desc">World Populations by Country</div> + <div role="rowgroup"> + <div role="row"> + <span role="columnheader" aria-sort="descending">Country</span> + <span role="columnheader" aria-sort="none">Population</span> + </div> + </div> + <div role="rowgroup"> + <div role="row"> + <span role="cell">Finland</span> + <span role="cell">5.5 million</span> + </div> + <div role="row"> + <span role="cell">France</span> + <span role="cell">67 million</span> + </div> + </div> +</div> +``` + +## Description + +`Rowgroup` establishes a relationship between owned row elements and is a structural equivalent to the {{HTMLElement('thead')}}, {{HTMLElement('tfoot')}} and {{HTMLElement('tbody')}} elements in HTML. There is, however, no differentiation between different types of row groups. Their elements must be contained in, or owned by, elements with either the [table](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/table_role) or [grid](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/grid_role) role. Using the native {{HTMLElement('thead')}}, {{HTMLElement('tfoot')}} and {{HTMLElement('tbody')}} HTML elements, whenever possible, is strongly encouraged. + +To create an ARIA table header, table footer or table body, add `role="rowgroup"` to the element. That rowgroup should be nested within a grid, table or treegrid, encompassing a group of one or more rows. Each row, in turn, contains child cells. These cells can be of different types, depending on whether they are column or row headers, or plain or grid cells. + +> [!NOTE] +> Using the native HTML table element ({{HTMLElement('table')}}) along with the table header ({{HTMLElement('thead')}}), footer ({{HTMLElement('tfoot')}}), and body ({{HTMLElement('tbody')}}) elements whenever possible is strongly encouraged. + +### Associated WAI-ARIA roles, states, and properties + +#### Context roles + +- [role="table"](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/table_role) + - : One of the three possible contexts (along with grid and treegrid) in which you'll find a row. It identifies the row as being part of a non-interactive table structure containing data arranged in rows and columns, similar to the native {{HTMLElement('table')}} HTML element. +- [role="grid"](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/grid_role) + - : One of the three possible contexts (along with table and treegrid) in which you'll find a row. It identifies the row as being part of a non-interactive table structure containing data arranged in rows and columns, similar to the native {{HTMLElement('table')}} HTML element. +- [role="treegrid"](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/treegrid_role) + - : Similar to a grid, but with rows that can be expanded and collapsed in the same manner as for a tree. + +#### Descendant roles + +- [role="row"](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/row_role) + - : A row of cells within a tabular structure. A row contains one or more [cells](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/cell_role), [gridcell](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/gridcell_role), or [column headers](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/columnheader_role), and sometimes a [row header](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/rowheader_role). + +### Keyboard interactions + +None. + +### Required JavaScript features + +None. + +> [!NOTE] +> The first rule of ARIA use is if you can use a native feature with the semantics and behavior you require already built in, instead of re-purposing an element and **adding** an ARIA role, state or property to make it accessible, then do so. Employ the HTML `<table>` element instead of the ARIA role of table whenever possible. + +## Examples + +```html +<div + role="table" + aria-label="Semantic Elements" + aria-describedby="semantic_elements_table_desc" + aria-rowcount="81"> + <div id="semantic_elements_table_desc"> + Semantic Elements to use instead of ARIA's roles + </div> + <div role="rowgroup"> + <div role="row"> + <span role="columnheader" aria-sort="none">ARIA Role</span> + <span role="columnheader" aria-sort="none">Semantic Element</span> + </div> + </div> + <div role="rowgroup"> + <div role="row" aria-rowindex="11"> + <span role="cell">header</span> + <span role="cell">h1</span> + </div> + <div role="row" aria-rowindex="16"> + <span role="cell">header</span> + <span role="cell">h6</span> + </div> + <div role="row" aria-rowindex="18"> + <span role="cell">rowgroup</span> + <span role="cell">thead</span> + </div> + <div role="row" aria-rowindex="24"> + <span role="cell">term</span> + <span role="cell">dt</span> + </div> + </div> +</div> +``` + +The above is a non-semantic ARIA table with a table header and table body, with five of 81 rows present in the DOM: one within a table header and four rows within the table body. The header row, alone in a header rowgroup, has two column headers. The columns are sortable, but not currently sorted, as indicated by the [`aria-sort`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-sort) property. The table body is a separate rowgroup, with four rows currently in the DOM. Because not all the rows are in the DOM, we've included the [`aria-rowindex`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-rowindex) property on every row. + +## Best practices + +Only use {{HTMLElement('table')}}, {{HTMLElement('tbody')}}, {{HTMLElement('thead')}}, {{HTMLElement('tr')}}, {{HTMLElement('th')}}, {{HTMLElement('td')}}, and so on for data table structure. You can add these ARIA roles to ensure accessibility should the native semantics of the table be removed, such as with CSS. A relevant use case for the ARIA table role is when the CSS's display property overrides the native semantics of a table, such as by `display: grid`. In this case, you can use the ARIA table roles to add in the semantics. + +```html +<table + role="table" + aria-label="Semantic Elements" + aria-describedby="semantic_elements_table_desc" + aria-rowcount="81"> + <caption id="semantic_elements_table_desc"> + Semantic Elements to use instead of ARIA's roles + </caption> + <thead role="rowgroup"> + <tr role="row"> + <th role="columnheader" aria-sort="none">ARIA Role</th> + <th role="columnheader" aria-sort="none">Semantic Element</th> + </tr> + </thead> + <tbody role="rowgroup"> + <tr role="row" aria-rowindex="11"> + <td role="cell">header</td> + <td role="cell">h1</td> + </tr> + <tr role="row" aria-rowindex="16"> + <td role="cell">header</td> + <td role="cell">h6</td> + </tr> + </tbody> +</table> +``` + +Above is the semantic way of writing a table. The ARIA roles are only necessary if the native semantics of the table, and therefore the table rows, are obliterated, such as by setting the [display property to flex or grid](/en-US/docs/Web/CSS/display#accessibility). + +### Added benefits + +none + +## Specifications + +{{Specifications}} + +## See also + +- [HTML table](/en-US/docs/Web/HTML/Reference/Elements/table) +- [HTML table body](/en-US/docs/Web/HTML/Reference/Elements/tbody) +- [HTML table footer](/en-US/docs/Web/HTML/Reference/Elements/tfoot) +- [HTML table header](/en-US/docs/Web/HTML/Reference/Elements/thead) diff --git a/files/en-us/web/accessibility/aria/reference/roles/rowheader_role/index.md b/files/en-us/web/accessibility/aria/reference/roles/rowheader_role/index.md new file mode 100644 index 000000000000000..c4e58fcb7e536dd --- /dev/null +++ b/files/en-us/web/accessibility/aria/reference/roles/rowheader_role/index.md @@ -0,0 +1,155 @@ +--- +title: "ARIA: rowheader role" +short-title: rowheader +slug: Web/Accessibility/ARIA/Reference/Roles/rowheader_role +page-type: aria-role +spec-urls: https://w3c.github.io/aria/#rowheader +sidebar: accessibilitysidebar +--- + +An element with `role="rowheader"` is a [cell](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/cell_role) containing header information for a [row](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/row_role) within a tabular structure of a [`grid`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/grid_role), [`table`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/table_role) or [`treegrid`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/treegrid_role). + +## Description + +`Rowheader` is the header [`cell`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/cell_role) for a row, establishing a relationship between it and the other cells in the same [`row`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/row_role). + +```html +<div + role="table" + aria-label="Populations" + aria-describedby="country_population_desc"> + <div id="country_population_desc">World Populations by Country</div> + <div role="rowgroup"> + <div role="row"> + <span role="columnheader" aria-sort="descending">Country</span> + <span role="columnheader" aria-sort="none">Population</span> + </div> + </div> + <div role="rowgroup"> + <div role="row"> + <span role="rowheader">Finland</span> + <span role="cell">5.5 million</span> + </div> + <div role="row"> + <span role="rowheader">France</span> + <span role="cell">67 million</span> + </div> + </div> +</div> +``` + +It is a structural equivalent to the {{HTMLElement('th')}} element with a scope of `row`, `<th scope="row">`. Using the native {{HTMLElement('th')}} HTML element is strongly encouraged. + +To create an ARIA row header, add `role="rowheader"` to the element. That row header must be nested within a `row`, which, in turn, is nested within a `rowgroup`, or directly within a `grid`, `table` or `treegrid`. + +> [!NOTE] +> Using the native [table elements](/en-US/docs/Learn_web_development/Core/Structuring_content/HTML_table_basics) whenever possible, is strongly encouraged. + +### Associated WAI-ARIA roles, states, and properties + +#### Context roles + +- [role="row"](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/row_role) + - : The only context in which you will find a row. It encompasses a cell or group of cells row, of which only one should be of rowheader type. Similar to the native {{HTMLElement('tr')}} HTML element. + +### Keyboard interactions + +None. + +### Required JavaScript features + +None. + +> [!NOTE] +> The first rule of ARIA use is if you can use a native feature with the semantics and behavior you require already built in, instead of re-purposing an element and **adding** an ARIA role, state or property to make it accessible, then do so. Employ the HTML `<table>`, `<tr>`, `<th>`, `<td>`, and other [table elements](/en-US/docs/Learn_web_development/Core/Structuring_content/HTML_table_basics) instead of the ARIA table roles whenever possible. + +## Examples + +```html +<div + role="table" + aria-label="Semantic Elements" + aria-describedby="semantic_elements_table_desc" + aria-rowcount="81"> + <div id="semantic_elements_table_desc"> + Semantic Elements to use instead of ARIA's roles + </div> + <div role="rowgroup"> + <div role="row"> + <span role="columnheader" aria-sort="none">ARIA Role</span> + <span role="columnheader" aria-sort="none">Semantic Element</span> + </div> + </div> + <div role="rowgroup"> + <div role="row" aria-rowindex="11"> + <span role="rowheader">header</span> + <span role="cell">h1</span> + </div> + <div role="row" aria-rowindex="16"> + <span role="rowheader">header</span> + <span role="cell">h6</span> + </div> + <div role="row" aria-rowindex="18"> + <span role="rowheader">rowgroup</span> + <span role="cell">thead</span> + </div> + <div role="row" aria-rowindex="24"> + <span role="rowheader">term</span> + <span role="cell">dt</span> + </div> + </div> +</div> +``` + +The above is a non-semantic ARIA table with a table header and table body, with five of 81 rows present in the DOM: one within a table header and four rows within the table body. The header row, alone in a header rowgroup, has two column headers. The columns are sortable, but not currently sorted, as indicated by the [`aria-sort`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-sort) property. The table body is a separate rowgroup, with four rows currently in the DOM. Each data table row has a row header. Because not all the rows are in the DOM, we've included the [`aria-rowindex`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-rowindex) property on every row. + +## Best practices + +Only use {{HTMLElement('table')}}, {{HTMLElement('tbody')}}, {{HTMLElement('thead')}}, {{HTMLElement('tr')}}, {{HTMLElement('th')}}, {{HTMLElement('td')}}, and so on for data table structure. You can add these ARIA roles to ensure accessibility should the native semantics of the table be removed, such as with CSS. A relevant use case for all the ARIA table roles is when the CSS's `display` property overrides the native semantics of a table, such as by `display: grid`. In this case, you can use the ARIA table roles to add in the semantics. + +```html +<table + role="table" + aria-label="Semantic Elements" + aria-describedby="semantic_elements_table_desc" + aria-rowcount="81"> + <caption id="semantic_elements_table_desc"> + Semantic Elements to use instead of ARIA's roles + </caption> + <thead role="rowgroup"> + <tr role="row"> + <th role="columnheader" aria-sort="none">ARIA Role</th> + <th role="columnheader" aria-sort="none">Semantic Element</th> + </tr> + </thead> + <tbody role="rowgroup"> + <tr role="row" aria-rowindex="11"> + <th role="rowheader">header</th> + <td role="cell">h1</td> + </tr> + <tr role="row" aria-rowindex="16"> + <th role="rowheader">header</th> + <td role="cell">h6</td> + </tr> + </tbody> +</table> +``` + +Above is the semantic way of writing a table. The ARIA roles are only necessary if the native semantics of the table, and therefore the table row headers, are obliterated, such as by setting the [display property to flex or grid](/en-US/docs/Web/CSS/display#accessibility). + +### Added benefits + +none + +## Specifications + +{{Specifications}} + +## See also + +- [The HTML `<table>` element](/en-US/docs/Web/HTML/Reference/Elements/table) +- [The HTML `<th>` element](/en-US/docs/Web/HTML/Reference/Elements/th) +- [HTML table tutorial](/en-US/docs/Learn_web_development/Core/Structuring_content/HTML_table_basics) +- [ARIA `cell` role](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/cell_role) +- [ARIA `row` role](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/row_role) +- [ARIA `gridcell` role](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/gridcell_role) diff --git a/files/en-us/web/accessibility/aria/reference/roles/scrollbar_role/index.md b/files/en-us/web/accessibility/aria/reference/roles/scrollbar_role/index.md new file mode 100644 index 000000000000000..7de6320cc4016c5 --- /dev/null +++ b/files/en-us/web/accessibility/aria/reference/roles/scrollbar_role/index.md @@ -0,0 +1,172 @@ +--- +title: "ARIA: scrollbar role" +short-title: scrollbar +slug: Web/Accessibility/ARIA/Reference/Roles/scrollbar_role +page-type: aria-role +spec-urls: https://w3c.github.io/aria/#scrollbar +sidebar: accessibilitysidebar +--- + +A `scrollbar` is a graphical object that controls the scrolling of content within a viewing area. + +## Description + +A `scrollbar` is a range that controls what part of a viewport's content is currently visible in the viewport's frame; whether the viewport is a full browser size, an iframe, or any element's [block formatting context](/en-US/docs/Web/CSS/CSS_display/Block_formatting_context). + +### What is scroll bar + +Many applications provide native scroll bars when the content area is larger than the application window. Scrollbars generally appear on the right or bottom of the viewing area. Native scroll bars appear as thin rectangular track areas the length of the viewport it controls with a piece of UI called a thumb or scroller that can be dragged along a track to move the associated content within the viewport. Some scrollbars have arrows at each end of the track that allow scrolling the viewport a short set distance when activated. + +Take this document as an example: if the viewport is the full browser window and the content is taller than the viewport, in most browsers the scroll bar on the right edge of the window represents the overall length of the page and the scroll thumb represents the portion of the page content that is currently in the viewport. + +Scroll bars may also appear on viewports that are sub-sections of the full browser window. Continuing with this content as our example, if this content is embedded in an {{HTMLElement('iframe')}} or {{HTMLElement('object')}}, the native vertical scroll bar will be the height of the frame. A scroll bar generally is the length of the viewport, but isn't required to be. + +If you aren't currently seeing a scroll bar, it may be because your browser only displays the scroll bar when scrolling or only when an element's content is too big to fit in its block formatting context. Depending on the browser and operating system, scroll bars can be made to be visible even when the content fits in the viewport when no scrolling is necessary or even possible. + +### ARIA `scrollbar` + +It is always best to use native scroll bars. You can use the CSS {{CSSXref('overflow')}} property to ensure the appearance of native scroll bars. A [CSS scrollbar specification](https://drafts.csswg.org/css-scrollbars/) is being developed. Some browsers allow [styling scroll bars via prefixed pseudo-elements](/en-US/docs/Web/CSS/::-webkit-scrollbar). + +Because native scroll bar styling has historically been limited, you may come across a scrollbar implemented in JavaScript that you need to support and make fully accessible. For this, you can use the `scrollbar` role to inform assistive technologies that a UI control is an interactive scrollbar. + +An element with the `scrollbar` role is a graphical object that controls the scrolling of content within a viewing area; it is the ARIA role which indicates an element is a scroll bar. The HTML element that is most similar is the `range` {{HTMLElement('input')}} type, [`<input type="range">`](/en-US/docs/Web/HTML/Reference/Elements/input/range). + +The `scrollbar` element has two required attributes: [`aria-controls`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-controls) and [`aria-valuenow`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-valuenow). The `aria-controls` attribute references the [`id`](/en-US/docs/Web/HTML/Reference/Global_attributes/id) of the scrollable area it controls. The `aria-valuenow` property defines the current value of the scrollbar. + +While the `aria-valuenow` is always required, the [`aria-valuemin`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-valuemin) and [`aria-valuemax`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-valuemax) properties only need to be set for the scrollbar role when the `scrollbar`'s minimum value is not 0 or the maximum value is not 100. The value of `aria-valuenow` must always be between the minimum and maximum inclusive values, or between `0` and `100` inclusive if the minimum and maximum values default to `0` and `100` respectively. `aria-valuenow` communicates how close the viewport is to the bottom of the document. Think of it like a progress bar, where the start of the document is the minimum value and the end of the document is the maximum value. + +A `scrollbar` represents the current value and range of possible values via the size of the scrollbar and position of the thumb with respect to the visible range of the orientation (horizontal or vertical) it controls. In other words, the `scrollbar` length (height or width) represents all the content within a viewport. The `aria-valuemin` value represents the beginning of the content and the scrollbar, the `aria-valuemax` value represents the end of the content and the end of the scrollbar. The `aria-valuenow` represents the content that is currently visible in the viewport and the current position, or value, of the movable thumb. The `aria-valuenow` value will generally be exposed as a percentage between `aria-valuemin` and `aria-valuemax` calculated by assistive technologies. + +> [!NOTE] +> Assistive technologies generally render the value of `aria-valuenow` as a percent of a range between the value of `aria-valuemin` and `aria-valuemax`, unless [`aria-valuetext`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-valuetext) is set. It is recommended to set the values for `aria-valuemin`, `aria-valuemax`, and `aria-valuenow` in a manner that is appropriate for this calculation. + +Like a native scroll bar, users interact with `scrollbar` elements directly or indirectly using mouse, touchpad, keyboard, and voice input. `scrollbar` role implementations must also accommodate all these interaction methods. + +When using a mouse, the user must be able to activate the `scrollbar` by clicking the scroll arrows at either end of the scroll bar, if present, clicking an empty portion of the scroll track, as well as clicking and dragging the scroll thumb. + +Keyboard scrolling must also be supported. When focus is within the viewport controlled by a `scrollbar`, the <kbd>Up Arrow</kbd> and <kbd>Down Arrow</kbd> (or <kbd>Left Arrow</kbd> and <kbd>Right Arrow</kbd> for a horizontal scroll bar) should move the scroll bar thumb proportionally. Additionally, the <kbd>Page Up</kbd>, <kbd>Page Down</kbd>, <kbd>Space</kbd>, and <kbd>Shift + Space</kbd> keys must move the content and the scroll thumb the height (or width) of the viewport for each key press until the bottom or top (or left or right) of the content is in view. + +JavaScript must be used to translate the `scrollbar` action into scrolling commands, providing the user with feedback by: + +1. Visually updating the `scrollbar` element, +2. Scrolling the viewport's content, and +3. Updating the [`aria-valuenow`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-valuenow) property value. + +The default orientation of the `scrollbar` role is vertical. Including [`aria-orientation="vertical"`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-orientation), in this case, is optional. The orientation represents the orientation of the scrollbar and the scrolling effect on the viewing area controlled by the scrollbar. If the scrolling is left to right or right to left and not top to bottom, include `aria-orientation="horizontal"` on the element with the `scrollbar` role. + +> [!NOTE] +> An accessible name is **required**. If the `scrollbar` role is applied to an HTML {{HTMLElement('input')}} element (or `<meter>` or `<progress>` element), the accessible name can come from the associated {{HTMLElement('label')}}. Otherwise use [`aria-labelledby`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-labelledby) if a visible label is present or [`aria-label`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-label) if a visible label is not present. + +### All descendants are presentational + +There are some types of user interface components that, when represented in a platform accessibility API, can only contain text. Accessibility APIs do not have a way of representing semantic elements contained in a `scrollbar`. To deal with this limitation, browsers, automatically apply role [`presentation`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/presentation_role) to all descendant elements of any `scrollbar` element as it is a role that does not support semantic children. + +For example, consider the following `scrollbar` element, which contains a heading. + +```html +<div role="scrollbar"><h3>Title of my scrollbar</h3></div> +``` + +Because descendants of `scrollbar` are presentational, the following code is equivalent: + +```html +<div role="scrollbar"><h3 role="presentation">Title of my scrollbar</h3></div> +``` + +From the assistive technology user's perspective, the heading does not exist since the previous code snippets are equivalent to the following in the [accessibility tree](/en-US/docs/Glossary/Accessibility_tree): + +```html +<div role="scrollbar">Title of my scrollbar</div> +``` + +### Associated WAI-ARIA roles, states, and properties + +- [`aria-controls`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-controls) (Required) + - : Identifies the viewport, via the `id`, whose contents controlled by the scrollbar. +- [`aria-valuenow`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-valuenow) (Required) + - : Set to a decimal value between `0`, or `aria-valuemin` if present, and `aria-valuemax` indicating the current value of the scrollbar. +- [`aria-valuetext`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-valuetext) + - : Assistive technologies often present the value of `aria-valuenow` as a percentage. If this would not be helpful, use this property to make the scrollbar value more understandable to users. +- [`aria-valuemin`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-valuemin) + - : Set to a decimal value representing the minimum value, and less than `aria-valuemax`. If not present, the default value is `0`. +- [`aria-valuemax`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-valuemax) + - : Set to a decimal value representing the maximum value, and greater than `aria-valuemin`. If not present, the default value is `100`. +- [`aria-labelledby`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-labelledby) + - : When not using a native form control and therefore not able to associate the scrollbar with a {{HTMLElement('label')}}, if visible text is available that can provide the required accessible name, set to the [`id`](/en-US/docs/Web/HTML/Reference/Global_attributes/id) of an element containing text serving as a label. Otherwise, use `aria-label`. +- [`aria-label`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-label) + - : If no {{htmlelement('label')}} can be used, and no visible text is present that can be referenced by `aria-labelledby`, provides the string value that labels the `scrollbar` element providing the required accessible name. +- [`aria-orientation`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-orientation) + - : By default, the orientation is `vertical`. The property can be included and set to `horizontal`, `undefined` (the default for all roles unless otherwise specified), or `vertical`. + +### Keyboard interactions + +- <kbd>Up Arrow</kbd> + - : The content in the viewport moves up one line with the thumb moving up the scroll bar slider proportionally, until the top of the content and scrollbar are reached. +- <kbd>Down Arrow</kbd> + - : The content in the viewport moves down one line with the thumb moving down the scroll bar slider proportionally, until the bottom of the content and scrollbar are reached. +- <kbd>Left Arrow</kbd> + - : With horizontal scrolling, the content in the viewport moves left the width of one character with the thumb moving left across the scroll bar slider proportionally, until the left edge of the content abuts the left end of the viewport and the thumb is aligned on the left end of the scrollbar. +- <kbd>Right Arrow</kbd> + - : With horizontal scrolling, the content in the viewport moves right the width of one character with the thumb moving right across the scroll bar slider proportionally, until the right edge of the content abuts the right end of the viewport and the thumb is aligned on the right end of the scrollbar. +- <kbd>Page Up</kbd> and <kbd>Shift + Space</kbd> + - : The content in the viewport moves up the height of one viewport with the thumb moving up the scroll bar slider proportionally, until the top of the content and scrollbar are reached. +- <kbd>Page Down</kbd> and <kbd>Space</kbd> + - : The content in the viewport moves down the height of one viewport with the thumb moving down the scroll bar slider proportionally, until the bottom of the content and scrollbar are reached.the bottom or top of the content is in view. + +## Examples + +The following is an example of a word likely being too long for a parent container. + +```html +<div id="pi-label">Pi</div> +<div id="pi"> + 3.1415926535897932384626433832795028841971693993751058209749445923078164062862089986280348253421170679 +</div> +<div + role="scrollbar" + aria-labelledby="pi-label" + aria-controls="pi" + aria-orientation="horizontal" + aria-valuenow="0" + aria-valuemin="0" + aria-valuemax="100"> + <div id="thumb"></div> +</div> +``` + +When using the ARIA roles instead of native UI features, CSS must be used to style the scrollbar and thumb and JavaScript must be used to handle all keyboard and pointer events. + +CSS could have been used to ensure the overflowing value of PI had a native scrollbar: + +```html +<h3 id="PI">Pi</h3> +<p class="pi" tabindex="0" aria-labelledby="PI"> + 3.1415926535897932384626433832795028841971693993751058209749445923078164062862089986280348253421170679 +</p> +``` + +```css +.pi { + overflow: auto; + max-width: 100%; +} +``` + +The above CSS means a native scroll bar will appear when the user interacts with the paragraph's viewport if the length of the longest word in the paragraph is wider than the paragraphs containing box. The `tabindex` attribute was added to allow people using a keyboard to navigate to, and scroll around the overflowed content. + +## Specifications + +{{Specifications}} + +## See also + +- [`<input type="range">`](/en-US/docs/Web/HTML/Reference/Elements/input/range), +- HTML {{HTMLElement('progress')}} element +- HTML {{HTMLElement('meter')}} element +- Other range widgets include: + - [`meter`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/meter_role) + - [`slider`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/slider_role) + - [`separator`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/separator_role) (if focusable) + - [`progressbar`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/progressbar_role) + - [`spinbutton`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/spinbutton_role) +- [Document `scroll` event](/en-US/docs/Web/API/Document/scroll_event) diff --git a/files/en-us/web/accessibility/aria/reference/roles/search_role/index.md b/files/en-us/web/accessibility/aria/reference/roles/search_role/index.md new file mode 100644 index 000000000000000..155a53fdb88b7dc --- /dev/null +++ b/files/en-us/web/accessibility/aria/reference/roles/search_role/index.md @@ -0,0 +1,98 @@ +--- +title: "ARIA: search role" +short-title: search +slug: Web/Accessibility/ARIA/Reference/Roles/search_role +page-type: aria-role +spec-urls: + - https://w3c.github.io/aria/#search + - https://www.w3.org/WAI/ARIA/apg/patterns/landmarks/examples/search.html +sidebar: accessibilitysidebar +--- + +The `search` role is used to identify the search functionality; the section of the page used to search the page, site, or collection of sites. + +```html +<form role="search"> + <!-- search input --> +</form> +``` + +## Description + +The `search` role is [a landmark](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles#3._landmark_roles) role that can be added to the container element that encompasses all of the elements that combined to form the search feature of the document or application, including a descendant [`<input type="search">`](/en-US/docs/Web/HTML/Reference/Elements/input/search). If a document includes more than one search, each should have a unique label, unless they are the same search repeated, then use the same name. There is an [`input` of type `search`](/en-US/docs/Web/HTML/Reference/Elements/input/search), though this does not define a search landmark by itself. Using {{HTMLElement('search')}} is an alternative way to define a search landmark. + +## Examples + +When a {{HTMLElement('form')}} is a search form, use the `search` role instead of [`form`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/form_role) role. + +```html +<form id="search" role="search"> + <label for="search-input">Search this site</label> + <input type="search" id="search-input" name="search" spellcheck="false" /> + <input value="Submit" type="submit" /> +</form> +``` + +## Accessibility concerns + +[Landmark roles](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles#3._landmark_roles) are intended to be used sparingly, to identify larger overall sections of the document. Using too many landmark roles can create "noise" in screen readers, making it difficult to understand the overall layout of the page. + +## Best practices + +### Prefer HTML + +Using the {{HTMLElement('form')}} element in conjunction with a declaration of `role="search"` will provide the largest amount of support. + +### Labeling landmarks + +#### Multiple landmarks + +If there is more than one `search` landmark role in a document, provide a label for each landmark. This label will allow an assistive technology user to be able to quickly understand the purpose of each landmark. + +```html +<form id="site-search" role="search" aria-label="Sitewide"> + <!-- search input --> +</form> + +… + +<form id="page-search" role="search" aria-label="On this page"> + <!-- search input --> +</form> +``` + +#### Repeated landmarks + +If a `search` landmark role in a document is repeated in a document, and both landmarks have identical content, use the same label for each landmark. An example of this would be repeating the sitewide search at the top and bottom of the page. + +```html +<header> + <form id="site-search-top" role="search" aria-label="Sitewide"> + <!-- search input --> + </form> +</header> + +… + +<footer> + <form id="site-search-bottom" role="search" aria-label="Sitewide"> + <!-- search input --> + </form> +</footer> +``` + +#### Redundant descriptions + +Screen readers will announce the type of role the landmark is. Because of this, you do not need to describe what the landmark is in its label. For example, a declaration of `role="search"` with an [`aria-label="Sitewide search"`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-label) may be announced redundantly as, "sitewide search search". + +## Specifications + +{{Specifications}} + +## See also + +- The {{HTMLElement('form')}} element +- The {{HTMLElement('input')}} element +- The {{HTMLElement('search')}} element +- [`<input type="search">`](/en-US/docs/Web/HTML/Reference/Elements/input/search) +- [Using HTML sections and outlines](/en-US/docs/Web/HTML/Reference/Elements/Heading_Elements) diff --git a/files/en-us/web/accessibility/aria/reference/roles/searchbox_role/index.md b/files/en-us/web/accessibility/aria/reference/roles/searchbox_role/index.md new file mode 100644 index 000000000000000..e9b13ed74d0f122 --- /dev/null +++ b/files/en-us/web/accessibility/aria/reference/roles/searchbox_role/index.md @@ -0,0 +1,70 @@ +--- +title: "ARIA: searchbox role" +short-title: searchbox +slug: Web/Accessibility/ARIA/Reference/Roles/searchbox_role +page-type: aria-role +spec-urls: https://w3c.github.io/aria/#searchbox +sidebar: accessibilitysidebar +--- + +The `searchbox` role indicates an element is a type of `textbox` intended for specifying search criteria. + +## Description + +The `searchbox` can be used instead of [`textbox`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/textbox_role) when the text box is within an element with role [`search`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/search_role). A `searchbox` is the semantic equivalent is HTML's {{HTMLElement('input')}} of type `search`, [`<input type="search">`](/en-US/docs/Web/HTML/Reference/Elements/input/search), which should be used instead if possible. + +The `searchbox` must have an accessible name. If the `searchbox` role is applied to an HTML {{HTMLElement('input')}} element, an associated {{HTMLElement('label')}} should be used. +Otherwise, use [`aria-labelledby`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-labelledby) if a visible label is present, or [`aria-label`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-label) if a visible label is not present. + +The screen reader will announce "search box", "search edit", or "search field" plus the accessible name. This can be redundant if "search" is included in the label. + +## Examples + +```html +<div tabindex="0" aria-label="search" role="searchbox" contenteditable></div> +``` + +While the above is valid, it is simpler, more concise, and less redundant to the screen reader user to write: + +```html +<input type="search" /> +``` + +The following is a search form with a searchbox and button, ARIA live region, and container for search results. + +```html +<form role="search"> + <input + type="search" + role="searchbox" + aria-description="search results will appear below" + id="search" + value="" /> + <label for="search">Search this site</label> + <button>Submit search</button> +</form> +<div aria-live="polite" role="region" aria-atomic="true"> + <div class="sr-only"></div> +</div> +<div id="search-results"></div> +``` + +Including `role="searchbox"` when the form is a `search` and the label indicates the element is a search may result in assistive technology announcing something along the lines of "search search this site search box", which is redundant. The inclusion of `role="searchbox"` is not necessary: + +```html +<input + type="search" + aria-description="search results will appear below" + id="search" + value="" /> +``` + +## Specifications + +{{Specifications}} + +## See also + +- [`<input type="search">`](/en-US/docs/Web/HTML/Reference/Elements/input/search) +- [ARIA: `search` role](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/search_role) +- [ARIA: `textbox` role](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/textbox_role) diff --git a/files/en-us/web/accessibility/aria/reference/roles/section_role/index.md b/files/en-us/web/accessibility/aria/reference/roles/section_role/index.md new file mode 100644 index 000000000000000..4fdeaf4262fe4ac --- /dev/null +++ b/files/en-us/web/accessibility/aria/reference/roles/section_role/index.md @@ -0,0 +1,60 @@ +--- +title: "ARIA: section role" +short-title: section +slug: Web/Accessibility/ARIA/Reference/Roles/section_role +page-type: aria-role +spec-urls: https://w3c.github.io/aria/#section +sidebar: accessibilitysidebar +--- + +The **`section` role**, an abstract role, is a superclass role for renderable structural containment components. + +> [!WARNING] +> The `section` role is an [abstract role](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles#6._abstract_roles). It is included here for completeness of documentation. It should not be used by web authors. + +## Description + +The structural `section` role is an abstract role for categorizing all the section subclass roles. The role must not be used. Some subclasses, like [`alert`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/alert_role), +[`note`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/note_role), and [`tooltip`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/tooltip_role) are useful, and can be used to add semantics when no semantic HTML elements quite fit the purpose of a component. Others, like [`code`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/structural_roles), [`figure`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/figure_role), and [`subscript`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/structural_roles), aren't necessary, as there are HTML element equivalents. In this case, {{HTMLElement('code')}} {{HTMLElement('figure')}} and {{HTMLElement('sub')}}, respectively. + +## Specifications + +{{Specifications}} + +## See also + +- [ARIA: `structure` role](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/structure_role) +- [ARIA: `alert` role](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/alert_role) +- [ARIA: `associationlist` role](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/structural_roles) +- [ARIA: `associationlistitemkey` role](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/structural_roles) +- [ARIA: `associationlistitemvalue` role](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/structural_roles) +- [ARIA: `blockquote` role](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/structural_roles) +- [ARIA: `caption` role](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/structural_roles) +- [ARIA: `cell` role](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/cell_role) +- [ARIA: `code` role](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/structural_roles) +- [ARIA: `definition` role](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/definition_role) +- [ARIA: `deletion` role](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/structural_roles) +- [ARIA: `emphasis` role](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/structural_roles) +- [ARIA: `figure` role](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/figure_role) +- [ARIA: `group` role](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/group_role) +- [ARIA: `img` role](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/img_role) +- [ARIA: `insertion` role](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/structural_roles) +- [ARIA: `landmark` role](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/landmark_role) +- [ARIA: `list` role](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/list_role) +- [ARIA: `listitem` role](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/listitem_role) +- [ARIA: `log` role](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/log_role) +- [ARIA: `mark` role](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/mark_role) +- [ARIA: `marquee` role](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/marquee_role) +- [ARIA: `math` role](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/math_role) +- [ARIA: `note` role](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/note_role) +- [ARIA: `paragraph` role](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/structural_roles) +- [ARIA: `status` role](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/status_role) +- [ARIA: `strong` role](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/structural_roles) +- [ARIA: `subscript` role](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/structural_roles) +- [ARIA: `suggestion` role](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/suggestion_role) +- [ARIA: `superscript` role](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/structural_roles) +- [ARIA: `table` role](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/table_role) +- [ARIA: `tabpanel` role](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/tabpanel_role) +- [ARIA: `term` role](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/term_role) +- [ARIA: `time` role](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/structural_roles) +- [ARIA: `tooltip` role](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/tooltip_role) diff --git a/files/en-us/web/accessibility/aria/reference/roles/sectionhead_role/index.md b/files/en-us/web/accessibility/aria/reference/roles/sectionhead_role/index.md new file mode 100644 index 000000000000000..38d8debb696b3c8 --- /dev/null +++ b/files/en-us/web/accessibility/aria/reference/roles/sectionhead_role/index.md @@ -0,0 +1,29 @@ +--- +title: "ARIA: sectionhead role" +short-title: sectionhead +slug: Web/Accessibility/ARIA/Reference/Roles/sectionhead_role +page-type: aria-role +spec-urls: https://w3c.github.io/aria/#sectionhead +sidebar: accessibilitysidebar +--- + +The **`sectionhead` role**, an abstract role, is superclass role for labels or summaries of the topic of its related section. + +> [!WARNING] +> The `sectionhead` role is an [abstract role](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles#6._abstract_roles). It is included here for completeness of documentation. It should not be used by web authors. + +## Description + +The structural `sectionhead` role is an abstract role for the subclass roles that identify the labels or summaries of the sections they label. The role must not be used. The four subclasses — [`columnheader`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/columnheader_role), [`heading`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/heading_role), [`rowheader`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/rowheader_role), and [`tab`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/tab_role). There are HTML element equivalents, like, {{HTMLElement('th', '<code>&lt;th scope="col"&gt;</code>')}} for `columnheader`, {{HTMLElement('th', '<code>&lt;th scope="row"&gt;</code>')}} for rowheader, and any of the HTML headings, {{HTMLElement("Heading_Elements", "h1")}} through {{HTMLElement("Heading_Elements", "h6")}} for `heading`. The `tab` role does not currently have an HTML equivalent. + +## Specifications + +{{Specifications}} + +## See also + +- [ARIA: `structure` role](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/structure_role) +- [ARIA: `columnheader` role](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/columnheader_role) +- [ARIA: `heading` role](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/heading_role) +- [ARIA: `rowheader` role](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/rowheader_role) +- [ARIA: `tab` role](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/tab_role) diff --git a/files/en-us/web/accessibility/aria/reference/roles/select_role/index.md b/files/en-us/web/accessibility/aria/reference/roles/select_role/index.md new file mode 100644 index 000000000000000..09c9147ec0985a1 --- /dev/null +++ b/files/en-us/web/accessibility/aria/reference/roles/select_role/index.md @@ -0,0 +1,30 @@ +--- +title: "ARIA: select role" +short-title: select +slug: Web/Accessibility/ARIA/Reference/Roles/select_role +page-type: aria-role +spec-urls: https://w3c.github.io/aria/#select +sidebar: accessibilitysidebar +--- + +The **`select` role**, an abstract role, is superclass role for form widgets that allows the user to make selections from a set of choices. + +> [!WARNING] +> The `select` role is an [abstract role](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles#6._abstract_roles). It is included here for completeness of documentation. It should not be used by web authors. + +## Description + +The structural `select` role, an abstract role, is superclass role for four form widgets, [`listbox`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/listbox_role), [`menu`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/menu_role), [`radiogroup`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/radiogroup_role), and [`tree`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/tree_role), which allow users to make selections from a set of choices. + +## Specifications + +{{Specifications}} + +## See also + +- [ARIA: `composite` role](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/composite_role) +- [ARIA: `group` role](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/group_role) +- [ARIA: `listbox` role](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/listbox_role) +- [ARIA: `menu` role](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/menu_role) +- [ARIA: `radiogroup` role](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/radiogroup_role) +- [ARIA: `tree` role](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/tree_role) diff --git a/files/en-us/web/accessibility/aria/reference/roles/separator_role/index.md b/files/en-us/web/accessibility/aria/reference/roles/separator_role/index.md new file mode 100644 index 000000000000000..16f4a6783bbb9d2 --- /dev/null +++ b/files/en-us/web/accessibility/aria/reference/roles/separator_role/index.md @@ -0,0 +1,128 @@ +--- +title: "ARIA: separator role" +short-title: separator +slug: Web/Accessibility/ARIA/Reference/Roles/separator_role +page-type: aria-role +spec-urls: + - https://w3c.github.io/aria/#separator + - https://www.w3.org/WAI/ARIA/apg/patterns/menubar/examples/menubar-editor/ +sidebar: accessibilitysidebar +--- + +The `separator` role indicates the element is a divider that separates and distinguishes sections of content or groups of menuitems. The implicit ARIA role of the native thematic break {{HTMLElement('hr')}} element is `separator`. + +## Description + +A separator is a divider that separates and distinguishes sections of content or groups of menuitems. There are two types of separators: a static structure that provides a visible boundary, identical to the HTML {{HTMLElement('hr')}} element, and a focusable, moveable widget. + +Elements with the role `separator` have an implicit [`aria-orientation`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-orientation) value of `horizontal`. + +### Non-focusable separator + +A non-focusable separator is a static structural element that can be used to help visually divide two groups of menu items in a menu or to provide a horizontal rule between two sections of a page. Thematic breaks that aren't focusable can still be perceivable by a screen reader user when using a reading cursor that does not depend on focus. + +```html +<h2>My first blog post</h2> +… +<img src="blueline.gif" role="separator" alt="" /> +<h2>Two years later, my second post</h2> +… +``` + +In the example, an image creates a visual separator between two blog posts. The author could have used a semantic thematic break {{HTMLElement('hr')}} element and styled it with CSS to make it blue (and not have to change the image when they change the blog's theme), or the author could have encompassed each post in the semantic {{HTMLElement('article')}} element, or both. + +```html +<section role="feed"> + <article> + <h2>My first blog post</h2> + … + </article> + <hr /> + <article> + <h2>Two years later, my second post</h2> + … + </article> +</section> +``` + +```css +[role="feed"] > hr { + height: 3px; + background-color: blue; +} +``` + +An accessible name is not needed. + +### Focusable separator + +The separator role can be used to identify the element as a visual separator between groups of items within a menu, such as groups of `menuitemradio` or `menuitemcheckbox` elements. + +If the separator is focusable, providing a visible boundary between two sections of content and enabling the user to change the relative size of the sections it separates by changing its position, the value of [`aria-valuenow`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-valuenow) must be set to a number reflecting the current position of the separator and the value must be updated when it changes. The [`aria-valuemin`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-valuemin) and [`aria-valuemax`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-valuemax) should also be included if they aren't set to the default values of 0 and 100, respectively. + +An accessible name, with [`aria-label`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-label) should be included if there is more than one focusable separator. + +### All descendants are presentational + +There are some types of user interface components that, when represented in a platform accessibility API, can only contain text. Accessibility APIs do not have a way of representing semantic elements contained in a `separator`. To deal with this limitation, browsers, automatically apply role [`presentation`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/presentation_role) to all descendant elements of any `separator` element as it is a role that does not support semantic children. + +For example, consider the following `separator` element, which contains a heading. + +```html +<div role="separator"><h3>Title of my separator</h3></div> +``` + +Because descendants of `separator` are presentational, the following code is equivalent: + +```html +<div role="separator"><h3 role="presentation">Title of my separator</h3></div> +``` + +From the assistive technology user's perspective, the heading does not exist since the previous code snippets are equivalent to the following in the [accessibility tree](/en-US/docs/Glossary/Accessibility_tree): + +```html +<div role="separator">Title of my separator</div> +``` + +### Associated WAI-ARIA roles, states, and properties + +- [`aria-orientation`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-orientation) (default is horizontal for separator) + + - : By default, the divider for `separator` roles is assumed to be horizontal. The value can be included and set to horizontal, undefined (the default for other roles unless otherwise specified), or vertical. + +- [`aria-valuenow`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-valuenow) + + - : If the separator is focusable and has a known value, the `aria-valuenow` defines the current value. If not focusable or the value is unknown, do not include this attribute. + +- [`aria-valuemin`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-valuemin) (default is 0) + + - : If the separator is focusable, and the minimum value is not 0, include the minimum value with `aria-valuemin`. If the + +- [`aria-valuemax`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-valuemax) (default is 100) + + - : If the separator is focusable, and the maximum value is not 100, include `aria-valuemax` with a value equal to or larger than `aria-valuemin`. + +- [`aria-valuetext`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-valuetext) + - : If the separator is focusable, and the `aria-valuenow` is not optimal in providing the user with usable information, included `aria-valuetext` content will be read instead of the `aria-valuenow` value. + +<!-- +### Keyboard interactions + +### Required JavaScript features + +## Examples + +## Accessibility concerns + +## Best Practices + +### Prefer HTML --> + +## Specifications + +{{Specifications}} + +## See also + +- Thematic break HTML {{HTMLElement('hr')}} element +- [Example separator in a menubar](https://www.w3.org/WAI/ARIA/apg/patterns/menubar/examples/menubar-editor/) diff --git a/files/en-us/web/accessibility/aria/reference/roles/slider_role/index.md b/files/en-us/web/accessibility/aria/reference/roles/slider_role/index.md new file mode 100644 index 000000000000000..fcc2da85edea52f --- /dev/null +++ b/files/en-us/web/accessibility/aria/reference/roles/slider_role/index.md @@ -0,0 +1,222 @@ +--- +title: "ARIA: slider role" +short-title: slider +slug: Web/Accessibility/ARIA/Reference/Roles/slider_role +page-type: aria-role +spec-urls: https://w3c.github.io/aria/#slider +sidebar: accessibilitysidebar +--- + +The `slider` role defines an input where the user selects a value from within a given range. + +## Description + +The `slider` role is for range input widgets where the user selects a value from within given minimum and maximum values. + +### The `slider` role compared other range options + +ARIA provides developers with six different range [widget roles](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles#2._widget_roles), including `progressbar`, `meter`, and `slider`. + +The [`progressbar`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/progressbar_role) role, similar to HTML's {{HTMLElement('progress')}} element, is a read-only range indicating the portion of completion of a task, progressing in a single direction, such as a file upload's loading progress bar that eventually reaches 100% when fully loaded. + +The [`meter`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/meter_role) role, similar to HTML's {{HTMLElement('meter')}} element, is a read-only gauge indicating the amount of something within a known range, such as a computer's battery indicator or a car's gas gauge. + +The `slider` role, similar to HTML's `input` of type `range`, [`<input type="range">`](/en-US/docs/Web/HTML/Reference/Elements/input/range), is a read-write input range. Sliders allow users to select a value between set minimum and maximum values. The user selects a value by moving a slider thumb along a horizontal or vertical slider to select a value. + +While all three of these ranges have the same ARIA states and properties, the `slider` role is the only read-write range: it is the only one whose value changes via user interaction. As such, it must be able to receive focus. In addition, keyboard interaction, mouse clicks, and touch interaction must be supported. + +> [!WARNING] +> To change the slider value, touch-based assistive technologies need to respond to user gestures for increasing and decreasing the value by synthesizing key events. +> Fully test slider widgets using assistive technologies on devices where touch is a primary input mechanism before using the `slider` role (and all range widgets). + +### Common attributes + +The [`aria-valuemin`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-valuemin) attribute sets the minimum value. If omitted or not a number, it defaults to `0` (zero). + +The [`aria-valuemax`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-valuemax) attribute defines the maximum value. If it is missing or not a number, it defaults to 100. + +The [`aria-valuenow`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-valuenow) attribute value must be between the minimum and maximum values, inclusive. This attribute is required for `slider` and `meter`, and optional for `progressbar`. + +For `slider`, unless using the [`<input type="range">`](/en-US/docs/Web/HTML/Reference/Elements/input/range) element, the `aria-valuenow` value must be updated programmatically when the user updates the value. + +The optional [`aria-valuetext`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-valuetext) attribute is included when the `aria-valuenow` numeric value doesn't reflect the intended value of the slider. As the minimum, maximum, and current values are all numeric, when the values those numbers represent are not numeric, the `aria-valuetext` attribute should be included with a string value defining the numeric value. For example, if using a slider for t-shirt sizes, the `aria-valuetext` attribute should shift from xx-small through to XX-large as the `aria-valuenow` increases. + +The `aria-valuetext` value must be updated as the `value` or `aria-valuenow` is updated. While there is no equivalent HTML attribute for `<input type="range">`, you can include `aria-valuetext` on any {{htmlelement('input')}} type. ARIA attributes are supported on semantic HTML elements. + +When `aria-valuetext` is an important feature for a slider, consider using {{HTMLElement('select')}} with {{HTMLElement('option')}} elements instead. While not visually a range, every option's value is more accessible to all users, not just users of assistive technology. + +An accessible name is **required**. If the range's role is applied to an HTML {{HTMLElement('input')}} element (or `<meter>` or `<progress>` element), the accessible name can come from the associated {{HTMLElement('label')}}. Otherwise use [`aria-labelledby`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-labelledby) if a visible label is present or [`aria-label`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-label) if a visible label is not present. + +When not using the HTML {{HTMLElement('input')}} element to create your slider, include the [`tabindex`](/en-US/docs/Web/HTML/Reference/Global_attributes/tabindex) attribute to make the slider focusable. Of the three range types, only `slider` is user-interactive, and so is the only one that requires being able to receive focus. Focus should be placed on the slider thumb. + +Sliders have an implicit [`aria-orientation`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-orientation) value of `horizontal`. This attribute is not supported with `meter` or `progressbar`. + +### User interactions + +Unlike the read-only `meter` and `progressbar` roles, a `slider` is an input, accepting user interaction. In addition to including the [`tabindex`](/en-US/docs/Web/HTML/Reference/Global_attributes/tabindex) attribute to enable slider focus, keyboard and pointer device support must be implemented. + +The slider represents the range of possible values. The position of the slider thumb along the slider represents the current value. User actions that must be supported include changing the value by dragging the thumb or clicking the slider for pointing devices and using directional keys such as arrow keys for the keyboard users. See [keyboard interactions](#keyboard_interactions) below. + +> [!NOTE] +> It is recommended to use native [`<input type="range">`](/en-US/docs/Web/HTML/Reference/Elements/input/range) elements rather than the `slider` role. User agents provide a stylized widget for the range input element, based on the current `value` as it relates to the minimum and maximum values. When using non-semantic elements, all features of the native semantic element need to be recreated with ARIA attributes, JavaScript and CSS. + +### Range with multiple thumbs + +A multi-thumb slider is a slider with two or more thumbs that each set a value in a group of related values. For example, in a product search, a two-thumb slider could be used to enable users to set the minimum and maximum price limits for the search. + +In many two-thumb sliders, the thumbs are not allowed to pass one another, such as when the slider sets the minimum and maximum values for a range. For example, in a price-range selector, the maximum value of the thumb that sets the lower end of the range is limited by the current value of the thumb that sets the upper end of the range. The minimum value of the upper-end thumb is also limited by the current value of the lower-end thumb. + +It is not a requirement that the thumbs in multi-thumb sliders be dependent on the other thumb values, but intuitive user experience is a requirement, so it is recommended to avoid this anti-pattern. + +### All descendants are presentational + +There are some types of user interface components that, when represented in a platform accessibility API, can only contain text. Accessibility APIs do not have a way of representing semantic elements contained in a `slider`. To deal with this limitation, browsers, automatically apply role [`presentation`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/presentation_role) to all descendant elements of any `slider` element as it is a role that does not support semantic children. + +For example, consider the following `slider` element, which contains a heading. + +```html +<div role="slider"><h3>Temperature in Celsius</h3></div> +``` + +Because descendants of `slider` are presentational, the following code is equivalent: + +```html +<div role="slider"><h3 role="presentation">Temperature in Celsius</h3></div> +``` + +From the assistive technology user's perspective, the heading does not exist since the previous code snippets are equivalent to the following in the [accessibility tree](/en-US/docs/Glossary/Accessibility_tree): + +```html +<div role="slider">Temperature in Celsius</div> +``` + +### Associated WAI-ARIA roles, states, and properties + +- [`aria-valuenow`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-valuenow) (required) + - : Set to a decimal value between `aria-valuemin` and `aria-valuemax`, indicating the current value of the slider. +- [`aria-valuetext`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-valuetext) + - : Assistive technologies often present the value of `aria-valuenow` as a number. If this would not be accurate, use `aria-valuetext` to provide the slider with a more understandable value. +- [`aria-valuemin`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-valuemin) + - : Set to a decimal value representing the minimum value, and less than `aria-valuemax`. If not present, the default value is 0. +- [`aria-valuemax`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-valuemax) + - : Set to a decimal value representing the maximum value, and greater than `aria-valuemin`. If not present, the default value is 100. +- [`aria-label`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-label) or [`aria-labelledby`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-labelledby) + - : Defines the string value or identifies the element (or elements) that label the slider element providing an accessible name. An accessible name is required. +- [`aria-orientation`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-orientation) + - : Indicates whether the element's orientation is horizontal, vertical, or unknown/ambiguous. With a slider, the implicit value is `horizontal` but can be set to `vertical`. As it has an implicit value, the slider orientation is never ambiguous. + +### Keyboard interactions + +| Key(s) | Action | +| -------------------- | ------------------------------------------------------------------- | +| Right and Up arrows | Increase the selected value by one step | +| Left and Down arrows | Decrease the selected value by one step | +| Page Up | (Optional) increase the value by a set amount greater than one step | +| Page Down | (Optional) decrease the value by a set amount greater than one step | +| Home | Set the slider to the minimum value. | +| End | Set the slider to the maximum value. | + +For the optional <kbd>Page Up</kbd> and <kbd>Page Down</kbd> keys, the change in slider value should be by an amount larger than the step changes made by up and down arrows. + +## Examples + +In the example below, we create a vertical thermometer with which the user can set the room temperature: + +```html +<div> + <div id="temperatureLabel">Temperature</div> + <div id="temperatureValue">20°C</div> + <div id="temperatureSlider"> + <div + id="temperatureSliderThumb" + role="slider" + aria-labelledby="temperatureLabel" + aria-orientation="vertical" + tabindex="0" + aria-valuemin="15.0" + aria-valuemax="25.0" + aria-valuenow="20.0" + aria-valuetext="20 degrees Celsius" + style="top: calc((25 - 20)*2rem - 0.5rem)"></div> + </div> +</div> +``` + +The position of the thumb is the maximum value minus the current value times the height of one degree, minus half the height of the thumb to center it. The rest of the styles are static. + +```css +[id="temperatureSlider"] { + position: relative; + height: 20rem; + width: 1rem; + outline: 1px solid; + margin: 3rem; +} + +[id="temperatureSliderThumb"] { + position: absolute; + height: 1rem; + width: 2rem; + background-color: currentcolor; + left: -0.5rem; +} +``` + +For this example to work, we have to write a script to handle all keyboard and pointer events, including event listeners for `pointermove`, `pointerup`, `focus`, `blur`, and `keydown`, and provide styles for the default state and when the thumb and slider receive focus. The position of the thumb, the `aria-valuenow` and `aria-valuetext` values, and the inner text of the element with the [`id`](/en-US/docs/Web/HTML/Reference/Global_attributes/id) "temperatureValue" need to be updated every time <kbd>ArrowLeft</kbd>, <kbd>ArrowDown</kbd>, <kbd>ArrowRight</kbd>, <kbd>ArrowUp</kbd>, <kbd>Home</kbd>, <kbd>End</kbd>, and, optionally, <kbd>PageDown</kbd> and <kbd>PageUp</kbd> keys are released and when the user drags the thumb or otherwise clicks on the temperature slider. + +Using semantic HTML, this could have been written as: + +```html +<label for="temperature"> Temperature </label> +<output id="temperatureValue">20°C</output> +<input + type="range" + id="temperatureSlider" + min="15" + max="25" + step="0.1" + value="20" + aria-valuetext="20 degrees celsius" /> +``` + +```css +#temperatureSlider { + transform: rotate(-90deg); +} +``` + +By using {{HTMLElement('input')}}, we get an already-styled range-input widget with keyboard focus, focus styling, keyboard interactions, and `value` updated on user interaction for free. We still need to use JavaScript to change the `aria-valuetext` and the value of the {{HTMLElement('output')}} element. + +There are a few ways to make a range input vertical. In this example, we used [CSS transforms](/en-US/docs/Web/CSS/transform). + +## Best practices + +If the slider is describing the loading progress of a particular region of a page, include the [`aria-describedby`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-describedby) attribute to reference the slider status, and set the [`aria-busy`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-busy) attribute to `true` on the region until it is finished loading. + +HTML's `<input type="range">` implicitly has the `role` of `slider`. Do not use `aria-valuemax` or `aria-valuemin` attributes on `<input type="range">` elements; use `min` and `max` instead. Otherwise, any global `aria-*` attributes and any other `aria-*` attributes applicable to the slider role. + +### Prefer HTML + +It is recommended to use a native {{HTMLElement("input")}} of type `range`, [`<input type="range">`](/en-US/docs/Web/HTML/Reference/Elements/input/range), rather than the `slider` role. + +## Specifications + +{{Specifications}} + +## See also + +- [`<input type="range">`](/en-US/docs/Web/HTML/Reference/Elements/input/range), +- HTML {{HTMLElement('progress')}} element +- HTML {{HTMLElement('meter')}} element +- Other range widgets include: + - [`meter`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/meter_role) + - [`scrollbar`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/scrollbar_role) + - [`separator`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/separator_role) (if focusable) + - [`progressbar`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/progressbar_role) + - [`spinbutton`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/spinbutton_role) +- W3C WAI-ARIA practices examples: + - [Horizontal Multi-Thumb Slider](https://www.w3.org/WAI/ARIA/apg/patterns/slider-multithumb/examples/slider-multithumb/) + - [Color Viewer Slider](https://www.w3.org/WAI/ARIA/apg/patterns/slider/examples/slider-color-viewer/) + - [Rating Slider](https://www.w3.org/WAI/ARIA/apg/patterns/slider/examples/slider-rating/) + - [Media Seek Slider](https://www.w3.org/WAI/ARIA/apg/patterns/slider/examples/slider-seek/) + - [Vertical Temperature Slider](https://www.w3.org/WAI/ARIA/apg/patterns/slider/examples/slider-temperature/) diff --git a/files/en-us/web/accessibility/aria/reference/roles/spinbutton_role/index.md b/files/en-us/web/accessibility/aria/reference/roles/spinbutton_role/index.md new file mode 100644 index 000000000000000..13adb425abbdd82 --- /dev/null +++ b/files/en-us/web/accessibility/aria/reference/roles/spinbutton_role/index.md @@ -0,0 +1,165 @@ +--- +title: "ARIA: spinbutton role" +short-title: spinbutton +slug: Web/Accessibility/ARIA/Reference/Roles/spinbutton_role +page-type: aria-role +spec-urls: https://w3c.github.io/aria/#spinbutton +sidebar: accessibilitysidebar +--- + +The `spinbutton` role defines a type of range that expects the user to select a value from among discrete choices. + +## Description + +The `spinbutton` role indicates that the element is an input widget that restricts its value to a set or range of discrete values. The role also comes with increment and decrement functionality. For example, in a widget that enables users to choose an amount to bet in a game of Texas Holdem, the `spinbutton` role can allow users to select a number between the minimum and maximum bets in increments, as allowed by the current game rules. + +The spinbutton represents the range of possible values. The value of the spinbutton input represents the current value. + +Spinbuttons often have three components, including a text field that displays the current value, an increment button, and a decrement button. The text field is usually the only focusable component because the increment and decrement functions are keyboard accessible via arrow keys. Typically, the text field also allows users to directly edit the value. + +In addition to including the [`tabindex`](/en-US/docs/Web/HTML/Reference/Global_attributes/tabindex) attribute to enable spinbutton focus, keyboard and pointer device support must be implemented. Directional keys such as the arrow keys must be supported for keyboard users. Changing the value when increment and decrement buttons are clicked must be supported for pointing devices. See [keyboard interactions](#keyboard_interactions) below. + +> [!NOTE] +> It is recommended to use [`<input type="number">`](/en-US/docs/Web/HTML/Reference/Elements/input/number) element, or other input types for dates and time that also implicitly have the `role="spinbutton"` semantic, rather than the `spinbutton` role. User agents provide stylized widget for the these input elements which provide default increment, decrement, and native range limiting functionality. When using non-semantic elements, all features of the native semantic element need to be recreated with ARIA attributes, JavaScript, and CSS. + +### ARIA range widget options + +ARIA provides developers with six different range [widget roles](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles#2._widget_roles), including `progressbar`, `meter`, `slider`, and `spinbutton`. + +The [`progressbar`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/progressbar_role) role, similar to HTML's {{HTMLElement('progress')}} element, is a read-only range. It indicates the portion of completion of a task, progressing in a single direction, such as a file upload's loading progress bar that eventually reaches 100% when fully loaded. + +The [`meter`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/meter_role) role, similar to HTML's {{HTMLElement('meter')}} element, is a read-only gauge. It indicates the amount of something within a known range, such as a computer's battery indicator or a car's gas gauge. + +The `slider` role, similar to HTML's `input` of type `range`, [`<input type="range">`](/en-US/docs/Web/HTML/Reference/Elements/input/range), is a read-write input range. Sliders allow users to select a value between the predefined minimum and maximum values. The user selects a value by moving a slider thumb along a horizontal or vertical slider to select a value. + +While all three of these ranges have the same ARIA states and properties, the `spinbutton` role is the only read-write range: it is the only one whose value changes via user interaction. As such, it must be able to receive focus. In addition, keyboard interaction, mouse clicks, and touch interaction must be supported. + +> [!WARNING] +> To change the spinbutton value, touch-based assistive technologies need to respond to user gestures for increasing and decreasing the value by synthesizing key events. +> Fully test spinbutton widgets using assistive technologies on devices where touch is a primary input mechanism before using the `spinbutton` role (and all range widgets). + +### Common attributes + +The [`aria-valuemin`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-valuemin) attribute sets the minimum value. If omitted or not a number, it defaults to `0` (zero). + +The [`aria-valuemax`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-valuemax) attribute defines the maximum value. If it is missing or not a number, it defaults to `100`. + +The [`aria-valuenow`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-valuenow) attribute value must be between the minimum and maximum values, both inclusive. This attribute is required for `spinbutton` and `meter`, and optional for `progressbar`. + +For `spinbutton`, unless using semantic HTML elements like [`<input type="number">`](/en-US/docs/Web/HTML/Reference/Elements/input/number), if the value is updated, the `aria-valuenow` value must also be updated programmatically. + +The optional [`aria-valuetext`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-valuetext) attribute is included when the `aria-valuenow` numeric value doesn't reflect the intended value of the spinbutton. The optional minimum, maximum, and current values should be numeric. When the values these numbers represent are not numeric, the `aria-valuetext` attribute should be included with a string value defining the numeric value. For example, if using a spinbutton for t-shirt sizes, the `aria-valuetext` attribute should shift from `XX-Small` through `XX-Large` as the `aria-valuenow` increases. + +The `aria-valuetext` value must be updated as the value or `aria-valuenow` is updated. ARIA attributes are supported on semantic HTML elements. While there is no equivalent HTML attribute for `<input>`, you can include `aria-valuetext` on any {{htmlelement('input')}} type. When `aria-valuetext` is an important feature for a spinbutton, consider using {{HTMLElement('select')}} with {{HTMLElement('option')}} elements instead. + +An accessible name is **required**. If the `spinbutton` role is applied to an HTML {{HTMLElement('input')}} element, the accessible name can come from the associated {{HTMLElement('label')}}. Otherwise, use [`aria-labelledby`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-labelledby) if a visible label is present or [`aria-label`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-label) if a visible label is not present. + +When not using the HTML {{HTMLElement('input')}} element to create your spinbutton, include the [`tabindex`](/en-US/docs/Web/HTML/Reference/Global_attributes/tabindex) attribute to make the spinbutton focusable. The `spinbutton` role is user-interactive, and therefore, requires being able to receive focus. Focus should be placed on the spinbutton input and not on the associated buttons that increment and decrement the spinbutton value. + +### Descendants limited to buttons or text + +There are some types of user interface components that, when represented in a platform accessibility API, can only contain specific content. The children or owned elements of `spinbutton` are limited to a textbox and two buttons. Alternatively, the `spinbutton` role can be applied to a `text` input and sibling buttons can be used to support the increment and decrement functions. + +### Associated WAI-ARIA roles, states, and properties + +- [`aria-valuenow`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-valuenow) (required) + + - : Set to a decimal value between `aria-valuemin` and `aria-valuemax`, indicating the current value of the spinbutton. If not present, there is no default value. + +- [`aria-valuetext`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-valuetext) + + - : Assistive technologies often present the value of `aria-valuenow` as a number. If `aria-valuenow` cannot be accurate, use `aria-valuetext` to provide the spinbutton with a more understandable value. + +- [`aria-valuemin`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-valuemin) + + - : Set to a decimal value representing the minimum value and less than `aria-valuemax`. If not present, there is no default value. + +- [`aria-valuemax`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-valuemax) + + - : Set to a decimal value representing the maximum value and greater than `aria-valuemin`. If not present, there is no default value. + +- [`aria-labelledby`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-labelledby) + - : Defines the string value or identifies the element (or elements) that label the spinbutton element providing an accessible name. An accessible name is required. +- [`aria-label`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-label) + - : Defines a string value that labels the spinbutton element. This provides an accessible name to the element when no visible label is available to provide the required accessible name via {{HTMLElement('label')}} or `aria-labelledby`. + +### Keyboard interactions + +| Key(s) | Action | +| -------------------- | ------------------------------------------------------------------------------- | +| Right and Up arrows | Increase the selected value by one step | +| Left and Down arrows | Decrease the selected value by one step | +| Page Up | (Optional) Increase the value by a set amount greater than or equal to one step | +| Page Down | (Optional) Decrease the value by a set amount greater than or equal to one step | +| Home | Set the spinbutton to the minimum value | +| End | Set the spinbutton to the maximum value | + +For the optional <kbd>Page Up</kbd> and <kbd>Page Down</kbd> keys, the change in spinbutton value should preferably be by an amount larger than the step changes made by Up and Down arrow keys. + +## Examples + +In the example below, a `spinbutton` role has been defined to allow users to select a day of the month. + +```html +<p id="day">Enter the day of the month</p> +<button type="button" tabindex="-1" aria-label="previous day">˱</button> +<div + role="spinbutton" + tabindex="0" + aria-valuenow="1" + aria-valuetext="first" + aria-valuemin="1" + aria-valuemax="31" + aria-labelledby="day"> + 1 +</div> +<button type="button" tabindex="-1" aria-label="next day">˲</button> +``` + +In this example, we included a negative `tabindex` to remove the buttons from the default tabbing order. We also added `tabindex` to a normally non-interactive {{HTMLElement('div')}} to add the `spinbutton` itself to the tabbing order. This example requires JavaScript to handle keyboard actions when the spinbutton has focus and when a mouse user clicks on the buttons. + +### With semantic HTML + +This could have also been written using semantic HTML, removing the need for any CSS or JavaScript and also removing the need to include and provide functionality for extraneous incrementing and decrementing buttons. The code snippet below shows the previous example without the `spinbutton` role and using semantic HTML. + +```html +<label for="day">Enter the day of the month</label> +<input + type="number" + value="1" + aria-valuetext="first" + min="1" + max="31" + id="day" /> +``` + +{{EmbedLiveSample("With_semantic_HTML", 50, 50)}} + +In this case, the only JavaScript needed would be to update the `aria-valuetext` when the input value changes, which really is an optional feature in this case. + +## Best practices + +HTML's `<input type="number">` implicitly has the `role` of `spinbutton`. HTML's `<input type="date">` has 3 nested spin buttons, one each for month, day, and year. When using semantic HTML form elements for their intended purposes, do not use `aria-valuemax` or `aria-valuemin` attributes; use `min` and `max` instead. Otherwise, any global `aria-*` attributes and any other `aria-*` attributes are applicable to the `spinbutton` role. + +### Prefer semantic HTML + +It is recommended to use the native {{HTMLElement("input")}} element of type `number`, [`<input type="number">`](/en-US/docs/Web/HTML/Reference/Elements/input/number), rather than the `spinbutton` role. + +## Specifications + +{{Specifications}} + +## See also + +- [`<input type="number">`](/en-US/docs/Web/HTML/Reference/Elements/input/number) +- [`<input type="date">`](/en-US/docs/Web/HTML/Reference/Elements/input/date) +- [`<input type="time">`](/en-US/docs/Web/HTML/Reference/Elements/input/time) +- Other range widgets include: + - [`meter`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/meter_role) + - [`scrollbar`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/scrollbar_role) + - [`separator`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/separator_role) (if focusable) + - [`progressbar`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/progressbar_role) + - [`slider`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/slider_role) +- Working examples: + - [Date picker spin button example](https://www.w3.org/WAI/ARIA/apg/patterns/spinbutton/examples/datepicker-spinbuttons/) + - [Toolbar example: font-size picker](https://www.w3.org/WAI/ARIA/apg/patterns/toolbar/examples/toolbar/) diff --git a/files/en-us/web/accessibility/aria/reference/roles/status_role/index.md b/files/en-us/web/accessibility/aria/reference/roles/status_role/index.md new file mode 100644 index 000000000000000..df32d3f2db19c3e --- /dev/null +++ b/files/en-us/web/accessibility/aria/reference/roles/status_role/index.md @@ -0,0 +1,44 @@ +--- +title: "ARIA: status role" +short-title: status +slug: Web/Accessibility/ARIA/Reference/Roles/status_role +page-type: aria-role +spec-urls: https://w3c.github.io/aria/#status +sidebar: accessibilitysidebar +--- + +The `status` role defines a [live region](/en-US/docs/Web/Accessibility/ARIA/Guides/Live_regions) containing advisory information for the user that is not important enough to be an [`alert`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/alert_role). + +## Description + +A `status` is a type of [live region](/en-US/docs/Web/Accessibility/ARIA/Guides/Live_regions) providing advisory information that is not important enough to justify an alert, which would immediately interrupt the announcement of a user's current activity. It is often, but not necessarily, presented as a status bar. + +Do not give focus to the status when its content updates. Live regions are meant to inform users of dynamic updates that have occurred in other areas of the current web page, but which do not necessitate interrupting the user's current activity with a change in context. If a situation requires that focus needs to be moved, then using a `status`, or other live region, are likely not appropriate. + +Elements with the role status have an implicit [`aria-live`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-live) value of `polite` and an implicit [`aria-atomic`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-atomic) value of `true`. + +### Associated WAI-ARIA roles, states, and properties + +- [`aria-atomic`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-atomic) + + - : Defines whether assistive technologies should present all, or only parts of, the changed region. Elements with the role `status` have an implicit [aria-atomic](https://www.w3.org/TR/wai-aria-1.1/#aria-atomic) value of `true`. + +- [`aria-live`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-live) + + - : Defines when assistive technology should inform the user of updates to content. Elements with the role `status` have an implicit [aria-live](https://www.w3.org/TR/wai-aria-1.1/#aria-live) value of `polite`, meaning screen readers will announce changes inside the log when the user is idle. + +- [`aria-label`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-label) or [`aria-labelledby`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-labelledby) + + - : Some screen readers announce the name of a status element before announcing its contents. If a name is visible, reference it using `aria-labelledby`. Including an `aria-label` provides a method for prefacing the visible content of a status element with text that is not displayed when a screen reader reads the content. Naming a status is not required so if nothing is appropriate both these attributes can be omitted. + +## Specifications + +{{Specifications}} + +## See also + +- [ARIA: `alert` role](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/alert_role) +- [ARIA: `log` role](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/log_role) +- [ARIA: `marquee` role](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/marquee_role) +- [ARIA: `timer` role](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/timer_role) +- [ARIA live regions](/en-US/docs/Web/Accessibility/ARIA/Guides/Live_regions) diff --git a/files/en-us/web/accessibility/aria/reference/roles/structural_roles/index.md b/files/en-us/web/accessibility/aria/reference/roles/structural_roles/index.md new file mode 100644 index 000000000000000..ab1c42bab032fa6 --- /dev/null +++ b/files/en-us/web/accessibility/aria/reference/roles/structural_roles/index.md @@ -0,0 +1,56 @@ +--- +title: "ARIA: document structural roles" +short-title: Structural +slug: Web/Accessibility/ARIA/Reference/Roles/structural_roles +page-type: aria-role +spec-urls: https://w3c.github.io/aria/#document_structure_roles +sidebar: accessibilitysidebar +--- + +ARIA document-structure roles are used to provide a structural description for a section of content. + +Structural ARIA roles were originally created as a bridge to inform assistive technologies of HTML5 elements that were not yet fully supported in browsers. Some roles, like `presentation`, `toolbar` and `tooltip`, provide information on the document structure to assistive technologies in cases where equivalent native HTML elements don't exist. Other roles, including those listed in the table below, are not needed, as there are semantic HTML elements with the same meanings. In many cases, these equivalent HTML elements have always been supported. + +> [!WARNING] +> These structural roles all have semantic HTML equivalents. They are included here for completeness of documentation. Preferably, they should not be used by web authors. Opt for HTML semantic elements instead. + +Some structural roles, like [`suggestion`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/suggestion_role), don't have HTML equivalents, and therefore have separate documentation. Some structural roles with HTML equivalents, like [`heading`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/heading_role), have ARIA-attribute requirements. They are listed below with links to their individual role documentation. + +Most of the following roles were never needed but were added to ARIA for completeness. We've included them here for completeness as well. + +## Structural roles with HTML equivalents + +The structure roles with HTML equivalents are listed below: + +| ARIA role & description | HTML Equivalent | +| ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| **`associationlist`** <br> Contains only `associationlistitemkey` children and their sibling `associationlistitemvalue`. | {{HTMLElement('dl')}} | +| **`associationlistitemkey`** <br/> Must be contained in an `associationlist`. | {{HTMLElement('dt')}} | +| **`associationlistitemvalue`** <br/> Always a sibling following an `associationlistitemkey`. | {{HTMLElement('dd')}} | +| **`blockquote`** <br/> A section of content that is quoted from another source. | {{HTMLElement('blockquote')}} | +| **`caption`** <br>Visible content that names, and may also describe, a `figure`, `table`, `grid`, or `treegrid`.<br/> Only found in those 4 roles. A caption's `id` is generally referenced by a `figure`, `grid`, `table`, or `treegrid`'s `aria-labelledby` attribute.<br/> Prohibited attributes: `aria-label` and `aria-labelledby`. | {{HTMLElement('caption')}} <br/> {{HTMLElement('figcaption')}} | +| **`code`** <br/> A section representing a fragment of computer code. <br/> Prohibited attributes: `aria-label` and `aria-labelledby`. | {{HTMLElement('code')}} | +| **`deletion`** <br/>Content that is marked as removed or suggested for removal.<br/> Prohibited attributes: `aria-label` and `aria-labelledby`. | {{HTMLElement('del')}} | +| **`emphasis`** <br/> Used to stress or emphasize content, but not to suggest importance.<br/>Prohibited attributes: `aria-label` and `aria-labelledby`. | {{HTMLElement('em')}} | +| [`figure`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/figure_role) <br/>Container for a graphical document, images, code snippets, or example text. | {{HTMLElement('figure')}} | +| [`heading`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/heading_role) <br/> A heading for a section of the page.<br/>The `aria-level` attribute is required to indicate the nesting level.<br/>See the [`heading` role](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/heading_role) for more information. | {{HTMLElement("Heading_Elements", "h1")}}, {{HTMLElement("Heading_Elements", "h2")}}, {{HTMLElement("Heading_Elements", "h3")}}, {{HTMLElement("Heading_Elements", "h4")}}, {{HTMLElement("Heading_Elements", "h5")}}, and {{HTMLElement("Heading_Elements", "h6")}} | +| **`image`** <br/>Container for a collection of elements that form an image. Synonym for `img` role. | {{HTMLElement('img')}} | +| [`img`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/img_role) <br/>Container for a collection of elements that form an image. <br/>Accessible name is required. <br/>See the [`img` role](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/img_role) for more information. | {{HTMLElement('img')}} | +| **`insertion`** <br/>Content that is marked as added or content that is being suggested for addition.<br/> Prohibited attributes: `aria-label` and `aria-labelledby`. | {{HTMLElement('ins')}} | +| [`list`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/list_role)<br/>A section containing `listitem` elements.<br/> See [`list` role](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/list_role) for more information | {{HTMLElement('ol')}}<br/>{{HTMLElement('ul')}} | +| [`listitem`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/listitem_role)<br/>A single item in a `list` or `directory`.<br/>Must be contained in a `list` (like `<li>`).<br>See [`listitem` role](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/listitem_role) for more information. | {{HTMLElement('li')}} | +| [`mark`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/mark_role)<br/>Marked or highlighted for reference or notation purposes.<br>See [`mark` role](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/mark_role) for more information. | {{HTMLElement('mark')}} | +| [`meter`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/meter_role) <br/>A scalar measurement within a known range, or a fractional value.<br/>Accessible name required. `aria-valuenow` required.<br/>See [`meter` role](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/meter_role) for more information. | {{HTMLElement('meter')}} | +| **`paragraph`** <br/>A paragraph of content.<br/> Prohibited attributes: `aria-label` and `aria-labelledby`. | {{HTMLElement('p')}} | +| **`strong`** <br/>Important, serious, or urgent content.<br/> Prohibited attributes: `aria-label` and `aria-labelledby`. | {{HTMLElement('strong')}} | +| **`subscript`** <br/>One or more subscripted characters.<br/>Only use if absence of role would change the content's meaning.<br/> Prohibited attributes: `aria-label` and `aria-labelledby`. | {{HTMLElement('sub')}} | +| **`superscript`** <br/>One or more superscripted characters.<br/>Only use if absence of role would change the content's meaning.<br/> Prohibited attributes: `aria-label` and `aria-labelledby`. | {{HTMLElement('sup')}} | +| [`term`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/term_role)<br/>Word or phrase with an optional corresponding definition.<br/> Prohibited attributes: `aria-label` and `aria-labelledby`.<br/>See [`term` role](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/term_role) for more information. | {{HTMLElement('dfn')}} | +| **`time`** <br> A valid date or time string format list a specific point in time.<br/> Prohibited attributes: `aria-label` and `aria-labelledby`. | {{HTMLElement('time')}} | + +> [!NOTE] +> The `aria-label` and `aria-labelledby` attributes are prohibited on `code`, `caption`, `deletion`, `emphasis`, `generic`, `insertion`, `mark`, `paragraph`, `presentation`, `none`, `strong`, `subscript`, `superscript`, `suggestion`, `term`, and `time`, and should only be used on interactive content. + +## Specifications + +{{Specifications}} diff --git a/files/en-us/web/accessibility/aria/reference/roles/structure_role/index.md b/files/en-us/web/accessibility/aria/reference/roles/structure_role/index.md new file mode 100644 index 000000000000000..9b113d6d44d26ca --- /dev/null +++ b/files/en-us/web/accessibility/aria/reference/roles/structure_role/index.md @@ -0,0 +1,41 @@ +--- +title: "ARIA: structure role" +short-title: structure +slug: Web/Accessibility/ARIA/Reference/Roles/structure_role +page-type: aria-role +spec-urls: https://w3c.github.io/aria/#structure +sidebar: accessibilitysidebar +--- + +The `structure` role is for document structural elements. + +> [!WARNING] +> The `structure` role is an [abstract role](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles#6._abstract_roles). It is included here for completeness of documentation. It should not be used by web authors. Use HTML and subclass structure roles. + +## Description + +`Structure` is a superclass [abstract role](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles#6._abstract_roles) for document structures, like as [`document`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/document_role), +[`rowgroup`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/rowgroup_role), and [`sectionhead`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/sectionhead_role), that support the accessibility of dynamic web content by helping assistive technologies determine active content versus static document content. Some subclass roles, like +[`section` role](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/section_role), are in turn superclasses of other roles. + +The `structure` role is the superclass for all document structure roles, which are used to provide a structural description for a section of content. Most structure roles should no longer be used as browsers now support semantic HTML element with the same meaning. The structure roles without HTML equivalents, such as the [`presentation` role](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/presentation_role) which means content is presentational only, provide information on the document structure to assistive technologies such as screen readers as equivalent native HTML tags are not available. + +## Specifications + +{{Specifications}} + +## See also + +- [ARIA: `roletype` role](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/roletype_role) +- [ARIA: `generic` role](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/generic_role) +- [ARIA: `presentation` role](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/presentation_role) +- [ARIA: `range` role](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/range_role) +- [ARIA: `section` role](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/section_role) +- [ARIA: `sectionhead` role](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/sectionhead_role) + +<!-- these shouldn't be used so we shouldn't link to them +- [ARIA: `application` role](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/application_role) +- [ARIA: `document` role](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/document_role) +- [ARIA: `rowgroup` role](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/rowgroup_role) +- [ARIA: `separator` role](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/separator_role) +--> diff --git a/files/en-us/web/accessibility/aria/reference/roles/suggestion_role/index.md b/files/en-us/web/accessibility/aria/reference/roles/suggestion_role/index.md new file mode 100644 index 000000000000000..73f237f4d7821a3 --- /dev/null +++ b/files/en-us/web/accessibility/aria/reference/roles/suggestion_role/index.md @@ -0,0 +1,52 @@ +--- +title: "ARIA: suggestion role" +short-title: suggestion +slug: Web/Accessibility/ARIA/Reference/Roles/suggestion_role +page-type: aria-role +sidebar: accessibilitysidebar +--- + +The `suggestion` role semantically denotes a single proposed change to an editable document. This should be used on an element that wraps an element with an `insertion` role, and one with a `deletion` role. + +## Examples + +When you've got a content change that involves an insertion _and_ a deletion, there is no way for a screen reader user to work out if the two are related or not. This is the job of `role="suggestion"`, which should be set on an element wrapping both of them like so: + +```html +<p> + Freida's pet is a + <span role="suggestion"> + <span role="deletion">black Cat called Luna</span> + <span role="insertion">purple T. Rex called Tiny</span></span + >. +</p> +``` + +We could even provide an information box saying who made the suggestion and when, and associate it with the suggestion via [`aria-details`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-details): + +```html +<p> + Freida's pet is a + <span role="suggestion" aria-details="comment-source"> + <span role="deletion">black Cat called Luna</span> + <span role="insertion">purple T. Rex called Tiny</span></span + >. +</p> + +<div id="comment-source"> + Suggested by Chris, + <time datetime="2019-03-30T19:29">March 30 2019, 19:29</time> +</div> +``` + +Browsers tend to provide a default black strikethrough for deletions, and a black underline for insertions when using the HTML elements that implicitly expose these roles. But when using explicit ARIA roles to modify HTML elements, such as divs, you'll need to use CSS to customize the visual styling for such deletions and insertions. + +## Best practices + +### Prefer HTML + +Using the [`<ins>`](/en-US/docs/Web/HTML/Reference/Elements/ins) and [`<del>`](/en-US/docs/Web/HTML/Reference/Elements/del) element will automatically communicate a section has a role of `insertion` or `deletion`. If at all possible, prefer using the HTML elements. + +## Specifications + +Will be part of WAI-ARIA 1.3, which is still being drafted. diff --git a/files/en-us/web/accessibility/aria/reference/roles/switch_role/index.md b/files/en-us/web/accessibility/aria/reference/roles/switch_role/index.md new file mode 100644 index 000000000000000..50122d251a98f19 --- /dev/null +++ b/files/en-us/web/accessibility/aria/reference/roles/switch_role/index.md @@ -0,0 +1,192 @@ +--- +title: "ARIA: switch role" +short-title: switch +slug: Web/Accessibility/ARIA/Reference/Roles/switch_role +page-type: aria-role +spec-urls: + - https://w3c.github.io/aria/#switch + - https://w3c.github.io/html-aria/#index-aria-switch +sidebar: accessibilitysidebar +--- + +The ARIA **`switch`** role is functionally identical to the [checkbox](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/checkbox_role) role, except that instead of representing "checked" and "unchecked" states, which are fairly generic in meaning, the `switch` role represents the states "on" and "off." + +This example creates a widget and assigns the ARIA `switch` role to it. + +```html +<button + type="button" + role="switch" + aria-checked="true" + id="speakerPower" + class="switch"> + <span aria-hidden="true">off</span> + <span aria-hidden="true">on</span> +</button> +<label for="speakerPower" class="switch">Speaker power</label> +``` + +## Description + +The ARIA **`switch`** role is identical to the [checkbox](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/checkbox_role) role, except instead of being "checked" or "unchecked", it is either "on" or "off". Like the [checkbox](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/checkbox_role) role, the [`aria-checked`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-checked) attribute is required. The two possible values are `true` and `false`. Unlike an `<input type="checkbox">` or `role="checkbox"`, there is no `indeterminate` or `mixed` state. The `switch` role does not support the value `mixed` for the `aria-checked` attribute; assigning a value of `mixed` to a `switch` instead sets the value to `false`. + +Assistive technologies may choose to represent `switch` widgets with a specialized presentation to reflect the notion of an on/off switch. + +Since a switch is an interactive control, it must be focusable and keyboard accessible. If the role is applied to a non-focusable element, use the `tabindex` attribute to change this. The expected keyboard shortcut for toggling the value of a switch is the <kbd>Space</kbd> key. The developer is required to change the value of the `aria-checked` attribute dynamically when the switch is toggled. + +### All descendants are presentational + +There are some types of user interface components that, when represented in a platform accessibility API, can only contain text. Accessibility APIs do not have a way of representing semantic elements contained in a `switch`. To deal with this limitation, browsers, automatically apply role [`presentation`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/presentation_role) to all descendant elements of any `switch` element as it is a role that does not support semantic children. + +For example, consider the following `switch` element, which contains a heading. + +```html +<div role="switch"><h3>Title of my switch</h3></div> +``` + +Because descendants of `switch` are presentational, the following code is equivalent: + +```html +<div role="switch"><h3 role="presentation">Title of my switch</h3></div> +``` + +From the assistive technology user's perspective, the heading does not exist since the previous code snippets are equivalent to the following in the [accessibility tree](/en-US/docs/Glossary/Accessibility_tree): + +```html +<div role="switch">Title of my switch</div> +``` + +### Associated ARIA roles, states, and properties + +- [`aria-checked`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-checked) attribute + - : The `aria-checked` attribute is **required** when using the `switch` role, as it represents the current state of the widget that the `switch` role is applied to. A value of `true` represents the "on" state; `false` represents the "off" state; a value of `mixed` is not supported by the switch role, and is treated as `false`. +- [`aria-readonly`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-readonly) attribute + - : The `aria-readonly` attribute is supported by the `switch` role. It indicates whether the widget's state is editable by the user. A value of `false` means that the user _can_ change the widget's state; a value of `true` means that the user _cannot_ change the widget's state. The default value is `false`. + +### Required JavaScript features + +- Handler for click events + - : When the user clicks on the switch widget, a [click event](/en-US/docs/Web/API/Element/click_event) is fired, which must be handled in order to change the state of the widget. +- Changing the `aria-checked` attribute + - : When a click event is fired on the switch widget, the handler must change the value of the `aria-checked` attribute from `true` to `false`, or vice versa. + +## Possible effects on user agents and assistive technology + +When the `switch` role is added to an element, the {{Glossary("user agent")}} handles it like this: + +- The element is exposed to the system's accessibility infrastructure as having the `switch` role. +- When the `aria-checked` attribute's value changes, an accessible event is fired using the system's accessibility API if one is available and it supports the `switch` role. +- All elements that are descendants of an element with the `switch` role applied to it are automatically assigned role `presentation`. This prevents elements that are used to construct the switch from being interacted with individually by assistive technologies. Text in these elements remains visible to the user agent and may be read or otherwise delivered to the user, unless it's expressly hidden using {{cssxref("display", "display: none")}} or `aria-hidden="true"`. + +The assistive technology, if it supports the `switch` role, responds by doing the following: + +- Screen readers should announce the element as a switch, optionally providing instructions as to how to activate the switch. + +> [!NOTE] +> There are varying opinions on how assistive technologies should handle this role; the above is a suggested practice and may differ from other sources. + +## Examples + +The following examples should help you understand how to apply and use the `switch` role. + +### Adding the switch role in ARIA + +This example creates a widget and assigns the ARIA `switch` role to it. The button is styled with an appearance reminiscent of an on/off power switch. + +#### HTML + +A switch is implemented as a {{HTMLElement("button")}} element, which is initially checked courtesy of its `aria-checked` attribute being set to `"true"`. The switch has two child elements containing the "off" and "on" labels and is followed by a {{HTMLElement("label")}} identifying the switch. + +```html +<button role="switch" aria-checked="true" id="speakerPower" class="switch"> + <span>off</span> + <span>on</span> +</button> +<label for="speakerPower" class="switch">Speaker power</label> +``` + +#### JavaScript + +This JavaScript code defines and applies a function to handle click events on switch widgets. The function changes the `aria-checked` attribute from `true` to `false`, or vice versa. + +```js +document.querySelectorAll(".switch").forEach((theSwitch) => { + theSwitch.addEventListener("click", handleClickEvent, false); +}); + +function handleClickEvent(evt) { + const el = evt.target; + + if (el.getAttribute("aria-checked") === "true") { + el.setAttribute("aria-checked", "false"); + } else { + el.setAttribute("aria-checked", "true"); + } +} +``` + +#### CSS + +The purpose of the CSS is to establish a look and feel for the switch that's reminiscent of the power switch paradigm. + +```css +button.switch { + margin: 0; + padding: 0; + width: 70px; + height: 26px; + border: 2px solid black; + display: inline-block; + margin-right: 0.25em; + vertical-align: middle; + text-align: center; + font: + 12px / 20px "Open Sans", + "Arial", + serif; +} + +button.switch span { + padding: 0 4px; + pointer-events: none; +} + +[role="switch"][aria-checked="false"] :first-child, +[role="switch"][aria-checked="true"] :last-child { + background: #262; + color: #eef; +} + +[role="switch"][aria-checked="false"] :last-child, +[role="switch"][aria-checked="true"] :first-child { + color: #bbd; +} + +label.switch { + font: + 16px "Open Sans", + "Arial", + sans-serif; + line-height: 20px; + vertical-align: middle; + user-select: none; +} +``` + +The most interesting part is probably the use of attribute selectors and the {{cssxref(":first-child")}} and {{cssxref(":last-child")}} pseudo-classes to do all the heavy lifting of changing the appearance of the switch based on whether it's on or off. + +#### Result + +The result looks like this: + +{{EmbedLiveSample("Adding_the_switch_role_in_ARIA", 600, 40)}} + +## Specifications + +{{Specifications}} + +## See also + +- [ARIA: checkbox role](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/checkbox_role) +- [`<input type="checkbox">`](/en-US/docs/Web/HTML/Reference/Elements/input/checkbox) +- [`aria-hidden`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-hidden) diff --git a/files/en-us/web/accessibility/aria/reference/roles/tab_role/index.md b/files/en-us/web/accessibility/aria/reference/roles/tab_role/index.md new file mode 100644 index 000000000000000..ec8484be7fc9336 --- /dev/null +++ b/files/en-us/web/accessibility/aria/reference/roles/tab_role/index.md @@ -0,0 +1,246 @@ +--- +title: "ARIA: tab role" +short-title: tab +slug: Web/Accessibility/ARIA/Reference/Roles/tab_role +page-type: aria-role +spec-urls: + - https://w3c.github.io/aria/#tab + - https://www.w3.org/WAI/ARIA/apg/patterns/tabs/examples/tabs-manual/ +sidebar: accessibilitysidebar +--- + +The ARIA `tab` role indicates an interactive element inside a `tablist` that, when activated, displays its associated `tabpanel`. + +```html +<button role="tab" aria-selected="true" aria-controls="tabpanel-id" id="tab-id"> + Tab label +</button> +``` + +## Description + +An element with the `tab` role controls the visibility of an associated element with the [`tabpanel`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/tabpanel_role) role. The common user experience pattern is a group of visual tabs above, or to the side of, a content area, and selecting a different tab changes the content and makes the selected tab more prominent than the other tabs. + +Elements with the role `tab` _must_ either be a child of an element with the `tablist` role, or have their `id` as part of the [`aria-owns`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-owns) property of a `tablist`. This combination identifies to assistive technology that the element is part of a group of related elements. Some assistive technology will provide a count of the number of `tab` role elements inside a `tablist`, and inform users of which `tab` they currently have targeted. Further, an element with the `tab` role _should_ contain the [`aria-controls`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-controls) property identifying a corresponding `tabpanel` (that has a `tabpanel` role) by that element's `id`. When an element with the `tabpanel` role has focus, or a child of it has focus, that indicates that the connected element with the `tab` role is the active tab in a `tablist`. + +When elements with the `tab` role are selected or active they should have their [`aria-selected`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-selected) attribute set to `true`. Otherwise, their `aria-selected` attribute should be set to `false`. When a single-selectable `tablist` is selected or active, the `hidden` attribute of the other tabpanels should be set to true until the user selects the tab associated with that tabpanel. When a multi-selectable `tablist` is selected or active, its corresponding controlled `tabpanel` should have its [`aria-expanded`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-expanded) attribute set to `true` and its `hidden` attribute set to `false`, otherwise the reverse. + +### All descendants are presentational + +There are some types of user interface components that, when represented in a platform accessibility API, can only contain text. Accessibility APIs do not have a way of representing semantic elements contained in a `tab`. To deal with this limitation, browsers, automatically apply role [`presentation`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/presentation_role) to all descendant elements of any `tab` element as it is a role that does not support semantic children. + +For example, consider the following `tab` element, which contains a heading. + +```html +<div role="tab"><h3>Title of my tab</h3></div> +``` + +Because descendants of `tab` are presentational, the following code is equivalent: + +```html +<div role="tab"><h3 role="presentation">Title of my tab</h3></div> +``` + +From the assistive technology user's perspective, the heading does not exist since the previous code snippets are equivalent to the following in the [accessibility tree](/en-US/docs/Glossary/Accessibility_tree): + +```html +<div role="tab">Title of my tab</div> +``` + +### Associated roles and attributes + +- [`aria-selected`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-selected) + - : boolean +- [`aria-controls`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-controls) + - : `id` of element with `tabpanel` role +- [id](/en-US/docs/Web/HTML/Reference/Global_attributes/id) + - : content + +### Keyboard interactions + +| Key | Action | +| ----------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| <kbd>Tab</kbd> | When focus is outside of the `tablist` moves focus to the active tab. If focus is on the active tab moves focus to the next element in the keyboard focus order, ideally the active tab's associated `tabpanel`. | +| <kbd>→</kbd> | Focuses and optionally activates the next tab in the tab list. If the current tab is the last tab in the tab list it activates the first tab. | +| <kbd>←</kbd> | Focuses and optionally activates the previous tab in the tab list. If the current tab is the first tab in the tab list it activates the last tab. | +| <kbd>Delete</kbd> | When allowed removes the currently selected tab from the tab list. | + +### Required JavaScript features + +> [!NOTE] +> While there are ways to build tab-like functionality without JavaScript, there is no substitute combination using only HTML and CSS that will provide the same set of functionality that's required above for accessible tabs with content. + +## Example + +This example combines the role `tab` with `tablist` and elements with `tabpanel` to create an interactive group of tabbed content. Here we are enclosing our group of content in a `div`, with our `tablist` having an `aria-label` which labels it for assistive technology. Each `tab` is a `button` with the attributes previously mentioned. The first `tab` has both `tabindex="0"` and `aria-selected="true"` applied. These two attributes must always be coordinated as such—so when another tab is selected, it will then have `tabindex="0"` and `aria-selected="true"` applied. All unselected tabs must have `aria-selected="false"` and `tabindex="-1"`. + +All of the `tabpanel` elements have `tabindex="0"` to make them tabbable, and all but the currently active one have the `hidden` attribute. The `hidden` attribute will be removed when a `tabpanel` becomes visible with JavaScript. There is some basic styling applied that restyles the buttons and changes the [`z-index`](/en-US/docs/Web/CSS/z-index) of `tab` elements to give the illusion of it connecting to the `tabpanel` for active elements, and the illusion that inactive elements are behind the active `tabpanel`. + +```html +<div class="tabs"> + <div role="tablist" aria-label="Sample Tabs"> + <button + role="tab" + aria-selected="true" + aria-controls="panel-1" + id="tab-1" + tabindex="0"> + First Tab + </button> + <button + role="tab" + aria-selected="false" + aria-controls="panel-2" + id="tab-2" + tabindex="-1"> + Second Tab + </button> + <button + role="tab" + aria-selected="false" + aria-controls="panel-3" + id="tab-3" + tabindex="-1"> + Third Tab + </button> + </div> + <div id="panel-1" role="tabpanel" tabindex="0" aria-labelledby="tab-1"> + <p>Content for the first panel</p> + </div> + <div id="panel-2" role="tabpanel" tabindex="0" aria-labelledby="tab-2" hidden> + <p>Content for the second panel</p> + </div> + <div id="panel-3" role="tabpanel" tabindex="0" aria-labelledby="tab-3" hidden> + <p>Content for the third panel</p> + </div> +</div> +``` + +```css hidden +.tabs { + padding: 1em; +} + +[role="tablist"] { + margin-bottom: -1px; +} + +[role="tab"] { + position: relative; + z-index: 1; + background: white; + border-radius: 5px 5px 0 0; + border: 1px solid grey; + border-bottom: 0; + padding: 0.2em; +} + +[role="tab"][aria-selected="true"] { + z-index: 3; +} + +[role="tabpanel"] { + position: relative; + padding: 0 0.5em 0.5em 0.7em; + border: 1px solid grey; + border-radius: 0 0 5px 5px; + background: white; + z-index: 2; +} + +[role="tabpanel"]:focus { + border-color: orange; + outline: 1px solid orange; +} +``` + +There are two things we need to do with JavaScript: we need to change focus and tab index of our `tab` elements with the right and left arrows, and we need to change the active `tab` and `tabpanel` when we click on a `tab`. + +To accomplish the first, we listen for the [`keydown`](/en-US/docs/Web/API/Element/keydown_event) event on the `tablist`. If the event's [`key`](/en-US/docs/Web/API/KeyboardEvent/key) is `ArrowRight` or `ArrowLeft`, we react to the event. We start by setting the `tabindex` of the current `tab` element to -1, making it no longer tabbable. Then, if the right arrow is being pressed, we increase our tab focus counter by one. If the counter is greater than the number of `tab` elements we have, we circle back to the first tab by setting that counter to 0. If the left arrow is being pressed, we decrease our tab focus counter by one, and if it is then less than 0, we set it to the number of `tab` elements minus one (to get to the last element). Finally, we set `focus` to the `tab` element whose index is equal to the tab focus counter, and set its `tabindex` to 0 to make it tabbable. + +To handle changing the active `tab` and `tabpanel`, we have a function that takes in the event, gets the element that triggered the event, the triggering element's parent element, and its grandparent element. We then find all tabs with `aria-selected="true"` inside the parent element and sets it to `false`, then sets the triggering element's `aria-selected` to `true`. After that, we find all `tabpanel` elements in the grandparent element, make them all `hidden`, and finally select the element whose `id` is equal to the triggering `tab`'s `aria-controls` and removes the `hidden` attribute, making it visible. + +```js +window.addEventListener("DOMContentLoaded", () => { + // Only handle one particular tablist; if you have multiple tab + // lists (might even be nested), you have to apply this code for each one + const tabList = document.querySelector('[role="tablist"]'); + const tabs = tabList.querySelectorAll(':scope > [role="tab"]'); + + // Add a click event handler to each tab + tabs.forEach((tab) => { + tab.addEventListener("click", changeTabs); + }); + + // Enable arrow navigation between tabs in the tab list + let tabFocus = 0; + + tabList.addEventListener("keydown", (e) => { + // Move right + if (e.key === "ArrowRight" || e.key === "ArrowLeft") { + tabs[tabFocus].setAttribute("tabindex", -1); + if (e.key === "ArrowRight") { + tabFocus++; + // If we're at the end, go to the start + if (tabFocus >= tabs.length) { + tabFocus = 0; + } + // Move left + } else if (e.key === "ArrowLeft") { + tabFocus--; + // If we're at the start, move to the end + if (tabFocus < 0) { + tabFocus = tabs.length - 1; + } + } + + tabs[tabFocus].setAttribute("tabindex", 0); + tabs[tabFocus].focus(); + } + }); +}); + +function changeTabs(e) { + const targetTab = e.target; + const tabList = targetTab.parentNode; + const tabGroup = tabList.parentNode; + + // Remove all current selected tabs + tabList + .querySelectorAll(':scope > [aria-selected="true"]') + .forEach((t) => t.setAttribute("aria-selected", false)); + + // Set this tab as selected + targetTab.setAttribute("aria-selected", true); + + // Hide all tab panels + tabGroup + .querySelectorAll(':scope > [role="tabpanel"]') + .forEach((p) => p.setAttribute("hidden", true)); + + // Show the selected panel + tabGroup + .querySelector(`#${targetTab.getAttribute("aria-controls")}`) + .removeAttribute("hidden"); +} +``` + +{{EmbedLiveSample("Example", 600, 130)}} + +## Best practices + +It is recommended to use a {{HTMLElement('button')}} element with the role `tab` for their built-in functional and accessible features instead, as opposed to needing to add them yourself. For controlling tab key functionality for elements with the role `tab`, it is recommended to set all non-active elements to `tabindex="-1"`, and to set the active element to `tabindex="0"`. + +## Precedence order + +What are the related properties, and in what order will this attribute or property be read, which property will take precedence over this one, and which property will be overwritten. + +## Specifications + +{{Specifications}} + +## See also + +- HTML {{HTMLElement('button')}} element +- [KeyboardEvent.key](/en-US/docs/Web/API/KeyboardEvent/key) +- [ARIA `tabpanel` role](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/tabpanel_role) diff --git a/files/en-us/web/accessibility/aria/reference/roles/table_role/index.md b/files/en-us/web/accessibility/aria/reference/roles/table_role/index.md new file mode 100644 index 000000000000000..237e8c47d2aaa63 --- /dev/null +++ b/files/en-us/web/accessibility/aria/reference/roles/table_role/index.md @@ -0,0 +1,146 @@ +--- +title: "ARIA: table role" +short-title: table +slug: Web/Accessibility/ARIA/Reference/Roles/table_role +page-type: aria-role +spec-urls: + - https://w3c.github.io/aria/#table + - https://www.w3.org/WAI/ARIA/apg/patterns/table/examples/table/ +sidebar: accessibilitysidebar +--- + +The `table` value of the ARIA `role` attribute identifies the element containing the role as having a non-interactive table structure containing data arranged in rows and columns, similar to the native {{HTMLElement('table')}} HTML element. + +```html +<div + role="table" + aria-label="Semantic Elements" + aria-describedby="semantic_elements_table_desc" + aria-rowcount="81"> + <div id="semantic_elements_table_desc"> + Semantic Elements to use instead of ARIA's roles + </div> + <div role="rowgroup"> + <div role="row"> + <span role="columnheader" aria-sort="none">ARIA Role</span> + <span role="columnheader" aria-sort="none">Semantic Element</span> + </div> + </div> + <div role="rowgroup"> + <div role="row" aria-rowindex="11"> + <span role="cell">header</span> + <span role="cell">h1</span> + </div> + <div role="row" aria-rowindex="16"> + <span role="cell">header</span> + <span role="cell">h6</span> + </div> + <div role="row" aria-rowindex="18"> + <span role="cell">rowgroup</span> + <span role="cell">thead</span> + </div> + <div role="row" aria-rowindex="24"> + <span role="cell">term</span> + <span role="cell">dt</span> + </div> + </div> +</div> +``` + +## Description + +An element with `role="table"` is a static tabular structure with rows containing cells. The cells are not focusable or selectable, though widgets within individual cells of the table can be interactive. Using a native HTML {{HTMLElement('table')}} element whenever possible is strongly encouraged. + +> [!WARNING] +> If a table maintains a selection state, has two-dimensional navigation, or allows the user to rearrange cell order use [`grid`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/grid_role) or [`treegrid`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/treegrid_role) instead. + +To create an ARIA table, add `role="table"` to the container element. Within that container, each row has `role="row"` set and contains child cells. Each cell has a role of either `columnheader`, `rowheader`, or `cell`. Rows can be children of the table or within a `rowgroup`. + +The table caption can be defined via [`aria-labelledby`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-labelledby) or [`aria-label`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-label). All other semantic table elements, such as {{HTMLElement('tbody')}}, {{HTMLElement('thead')}}, {{HTMLElement('tr')}}, {{HTMLElement('th')}}, and {{HTMLElement('td')}}, need to be added via associated roles, such as `rowgroup`, `row`, `columnheader`, and `cell`. + +If the table contains sortable columns or rows, the [`aria-sort`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-sort) attribute should be added on the header cell element (not the table itself). If any rows or columns are hidden, the [`aria-colcount`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-colcount) or [`aria-rowcount`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-rowcount) should be included indicating the total number of columns or rows, respectively, along with the [`aria-colindex`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-colindex) or [`aria-rowindex`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-rowindex) on each cell. The [`aria-colindex`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-colindex) or [`aria-rowindex`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-rowindex) is set to the position of a cell within the row or column, respectively. If the table includes cells that span multiple rows or multiple columns, then [`aria-rowspan`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-rowspan) or [`aria-colspan`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-colspan) should be included as well. Realize, it is much simpler to use the {{HTMLElement('table')}} element, along with all the related semantic elements and attributes that are all supported by all assistive technologies. + +To create an interactive widget that has a tabular structure, use the `grid` pattern instead. If the interaction provides for the selection state of individual cells, if left to right and top to bottom navigation is provided, or if the user interface allows the rearranging of cell order or otherwise changing individual cell order such as through drag and drop, use [`grid`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/grid_role) or [`treegrid`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/treegrid_role) instead. + +> [!NOTE] +> Using a native HTML table element whenever possible is strongly encouraged. + +### Associated WAI-ARIA roles, states, and properties + +- `role="rowgroup"` + - : An optional child of the table, the row group encapsulates a group of rows, similar to {{HTMLElement('thead')}}, {{HTMLElement('tbody')}}, and {{HTMLElement('tfoot')}}. +- [`role="row"`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/row_role) + - : A row within the table, and optionally within a rowgroup that contains one or more cells, column headers, or row headers. +- [`aria-describedby`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-describedby) attribute + - : Takes as its value the id of the element that serves as a description for the table. +- [`aria-label`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-label) attribute + - : The [`aria-label`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-label) provides an accessible name for the table. +- [`aria-colcount`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-colcount) attribute + - : This attribute is only required if the columns are not present in the DOM all the time. It provides an explicit indication of the number of columns in the full table. Set the value to the total number of columns in the full table. If unknown, set `aria-colcount="-1"`. +- [`aria-rowcount`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-rowcount) attribute + - : This attribute is only required if the rows are not present in the DOM all the time, such as scrollable tables that reuse rows to minimize the number of DOM nodes. It provides an explicit indication of the number of rows in the full table. Set the value to the total number of rows in the full table. If unknown, set `aria-rowcount="-1"`. + +### Keyboard interactions + +None. + +### Required JavaScript features + +None. For sortable columns, see the [columnheader](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/columnheader_role) aria role. + +> [!NOTE] +> The first rule of ARIA use is if you can use a native feature with the semantics and behavior you require already built in, instead of re-purposing an element and **adding** an ARIA role, state or property to make it accessible, then do so. Employ the HTML {{HTMLElement('table')}} element instead of the ARIA role of table whenever possible. + +## Examples + +```html +<div + role="table" + aria-label="Semantic Elements" + aria-describedby="semantic_elements_table_desc" + aria-rowcount="81"> + <div id="semantic_elements_table_desc"> + Semantic Elements to use instead of ARIA's roles + </div> + <div role="rowgroup"> + <div role="row"> + <span role="columnheader" aria-sort="none">ARIA Role</span> + <span role="columnheader" aria-sort="none">Semantic Element</span> + </div> + </div> + <div role="rowgroup"> + <div role="row" aria-rowindex="11"> + <span role="cell">header</span> + <span role="cell">h1</span> + </div> + <div role="row" aria-rowindex="16"> + <span role="cell">header</span> + <span role="cell">h6</span> + </div> + <div role="row" aria-rowindex="18"> + <span role="cell">rowgroup</span> + <span role="cell">thead</span> + </div> + <div role="row" aria-rowindex="24"> + <span role="cell">term</span> + <span role="cell">dt</span> + </div> + </div> +</div> +``` + +The above is part of a table. While the full table has 81 entries, as indicated by the [`aria-rowcount`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-rowcount) property, only four are currently visible. The columns are sortable, but not currently sorted, as indicated by the [`aria-sort`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-sort) property on the column headers. + +## Best practices + +Only use {{HTMLElement('table')}}, {{HTMLElement('tbody')}}, {{HTMLElement('thead')}}, {{HTMLElement('tr')}}, {{HTMLElement('th')}}, {{HTMLElement('td')}}, etc., for data table structure. You can add these ARIA roles to ensure accessibility should the native semantics of the table be removed, such as with CSS. A relevant use case for the ARIA table role is when CSS's display property overrides the native semantics of a table, such as by `display: grid`. In this case, you can use the ARIA table roles to re-add the semantics. + +## Specifications + +{{Specifications}} + +## See also + +- [Learn: HTML table accessibility](/en-US/docs/Learn_web_development/Core/Structuring_content/Table_accessibility) +- [Learn: HTML table basics](/en-US/docs/Learn_web_development/Core/Structuring_content/HTML_table_basics) +- [ARIA: `grid` role](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/grid_role) diff --git a/files/en-us/web/accessibility/aria/reference/roles/tablist_role/index.md b/files/en-us/web/accessibility/aria/reference/roles/tablist_role/index.md new file mode 100644 index 000000000000000..97e604a2f08379a --- /dev/null +++ b/files/en-us/web/accessibility/aria/reference/roles/tablist_role/index.md @@ -0,0 +1,102 @@ +--- +title: "ARIA: tablist role" +short-title: tablist +slug: Web/Accessibility/ARIA/Reference/Roles/tablist_role +page-type: aria-role +spec-urls: https://w3c.github.io/aria/#tablist +sidebar: accessibilitysidebar +--- + +The `tablist` role identifies the element that serves as the container for a set of `tabs`. The tab content are referred to as `tabpanel` elements. + +## Description + +You may be interacting with a tabbed interface as you read this! Browser tabs allow a user have multiple web pages open in a single window. Clicking on a tab in the tablist at the top of the browser window enables the user to display the associated content in the main content area, the tabpanel, one site at a time. This is called a "tab design pattern". + +When implementing a tab design pattern, the [`tab`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/tab_role), `tablist` and [`tabpanel`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/tabpanel_role) roles are used. + +Tabs are a set of layered sections of content, known as tab panels, that display one panel of content at a time. Each tab panel has an associated `tab` element, that, when activated, displays the panel. The list of tab elements is arranged along one edge of the currently displayed panel, most commonly the top edge, nested in a `tablist` element. + +Each `tab` in a `tablist` serves as a label for one `tabpanel` and can be activated to display that panel. The `tablist` is the containing element for the set of tab elements contained. + +When a tabbed interface is initialized, one tab panel is displayed and its associated tab is styled to indicate that it is active. When the user activates one of the other tab elements, the previously displayed tab panel is hidden, the tab panel associated with the activated tab becomes visible, and the tab is considered "active". + +For a single-selectable tablist, the non-active tabpanel elements should be hidden from the user until the user selects the tab associated with that tabpanel. + +When creating a multi-selectable tablist, include [`aria-multiselectable="true"`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-multiselectable) on the `tablist element`. + +The `tab` elements not the `tablist`, have the [`aria-selected`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-selected) attribute. Set to `aria-selected="true"` for the tabs associated with each visible tabpanel. The tabs associated with hidden tabpanel elements have their `aria-selected` attributes set to `false`. + +If the tab list has a visible label, set [`aria-labelledby`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-labelledby) to the `id` of the labelling element. If not, use [`aria-label`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-label) to provide a label. + +To be keyboard accessible, focus must be managed for the descendants of this role. + +Elements with the `tablist` role have an implicit [`aria-orientation`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-orientation) value of `horizontal`. + +### Associated WAI-ARIA roles, states, and properties + +- [`tab`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/tab_role) role + - : Required Owned Elements. Every tablist must have one or more `tab` children. +- [`aria-multiselectable`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-multiselectable) + - : When set to `true`, indicates the user may select more than one `tab` from the `tablist` descendants. +- [`aria-orientation`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-orientation) + - : If the tablist element is vertically oriented, set `aria-orientation="vertical"`. The default is `horizontal`. + +### Keyboard interactions + +For the tab list: + +- <kbd>Tab</kbd> + - : When focus moves into the tab list, places focus on the active `tab` element. <br/><br/>When the tab list contains the focus, moves focus to the next element in the page tab sequence outside the tablist, which is the tabpanel unless the first element containing meaningful content inside the tabpanel is focusable. + +When focus is on a tab element in a horizontal tab list: + +- <kbd>Left Arrow</kbd> + - : moves focus to the previous tab. If focus is on the first tab, moves focus to the last tab. Optionally, activates the newly focused tab +- <kbd>Right Arrow</kbd> + - : Moves focus to the next tab. If focus is on the last tab element, moves focus to the first tab. Optionally, activates the newly focused tab + +When focus is on a tab element in a vertical tab list: + +- <kbd>Up Arrow</kbd> + - : moves focus to the previous tab. If focus is on the first tab, moves focus to the last tab. Optionally, activates the newly focused tab +- <kbd>Down Arrow</kbd> + - : Moves focus to the next tab. If focus is on the last tab element, moves focus to the first tab. Optionally, activates the newly focused tab + +If the tab list is horizontal, it does not listen for <kbd>Down Arrow</kbd> or <kbd>Up Arrow</kbd> so those keys can provide their normal browser scrolling functions even when focus is inside the tab list. + +When focus is on a tab in a tablist with either horizontal or vertical orientation: + +- <kbd>Space</kbd> or <kbd>Enter</kbd> + - : Activates the tab if it was not activated automatically on focus. +- <kbd>Home</kbd> (Optional) + - : Moves focus to the first tab. Optionally, activates the newly focused tab +- <kbd>End</kbd> (Optional) + - : Moves focus to the last tab. Optionally, activates the newly focused tab +- <kbd>Shift + F10</kbd> + - : If the tab has an associated popup menu, opens the menu. +- <kbd>Delete</kbd> (Optional) + - : If deletion is allowed, deletes (closes) the current tab element and its associated tab panel, sets focus on the tab following the tab that was closed, and optionally activates the newly focused tab. If there is not a tab that followed the tab that was deleted, e.g., the deleted tab was the right-most tab in a left-to-right horizontal tab list, sets focus on and optionally activates the tab that preceded the deleted tab. If the application allows all tabs to be deleted, and the user deletes the last remaining tab in the tab list, the application moves focus to another element that provides a logical work flow. As an alternative to Delete, or in addition to supporting Delete, the delete function is available in a context menu. + +<!-- +### Required JavaScript features + +## Accessibility concerns + +## Best Practices + +### Prefer HTML +--> + +## Examples + +See the [`tabpanel`, `tab`, and `tablist` example](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/tab_role#example) in the [`tab`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/tab_role) role definition. + +## Specifications + +{{Specifications}} + +## See also + +- [`tab` role](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/tab_role) +- [`tabpanel` role](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/tabpanel_role) diff --git a/files/en-us/web/accessibility/aria/reference/roles/tabpanel_role/index.md b/files/en-us/web/accessibility/aria/reference/roles/tabpanel_role/index.md new file mode 100644 index 000000000000000..54412b05db888df --- /dev/null +++ b/files/en-us/web/accessibility/aria/reference/roles/tabpanel_role/index.md @@ -0,0 +1,72 @@ +--- +title: "ARIA: tabpanel role" +short-title: tabpanel +slug: Web/Accessibility/ARIA/Reference/Roles/tabpanel_role +page-type: aria-role +spec-urls: + - https://w3c.github.io/aria/#tabpanel + - https://www.w3.org/WAI/ARIA/apg/patterns/tabs/examples/tabs-manual/ +sidebar: accessibilitysidebar +--- + +The ARIA `tabpanel` is a container for the resources of layered content associated with a `tab`. + +## Description + +The `tabpanel` role indicates the element is a container for the resources associated with a [`tab`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/tab_role) role, where each `tab` is contained in a [`tablist`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/tablist_role). + +A `tabpanel` is part of a tab interface, a common user experience pattern in which a group of visual tabs allow for quickly switching between multiple layered views. Each tab is defined as such with the `tab` role, and these tabs are contained within an element with the `tablist` role. The `tablist` is often visually positioned above or to the side of a content area, containing the associated tabpanels. The `tabpanel` is the role of the container for each pane of content that is associated with a corresponding `tab` in the tab interface's `tablist`. + +In many tab interfaces, only a single `tabpanel` will be visible at a time. However, some interfaces may require multiple tab panels to be displayed at once. In these cases the `tablist` would be provided the [`aria-multiselectable`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-multiselectable) attribute, and the `tab` elements would then use the [`aria-expanded`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-expanded) attribute to indicate whether its associated `tabpanel` was visible or not. The tab's selected state would instead be used to indicate which tabpanel is the currently 'active' panel. For example, this could indicate which tabpanel keyboard focus would move to if someone were to press the <kbd>tab</kbd> key when focused on an tab within the multi-select `tablist`. + +In single-select tab interfaces, only the `tabpanel` associated with the currently selected tab is displayed. All other `tabpanel` elements associated with the unselected tabs must be hidden from users. So when tab selection changes, the displayed tabpanel would also, while the previously-displayed tabpanel would then become hidden. + +In multi-select tab interfaces, multiple `tabpanel` elements may be displayed, matching the expanded state of their associated `tab` elements. + +Tabs do not act as anchor links to individual panels — and upon activation, keyboard focus should remain on the current `tab` element and not automatically move to the newly displayed `tabpanel`. While a tab interface may be progressively enhanced based off an underlying markup pattern of in-page hyperlinks pointing to their associated sections of content, when JavaScript is used to modify these elements into a tabbed interface, the hyperlinks' default behavior should be prevented. Ideally, this could be done by removing or modifying the `href` attribute, as this would have the added benefit of removing the hyperlink-specific menu items from the element's browser context menu. + +When keyboard focus is on a `tablist`, or a `tab` within the `tablist`, the <kbd>Tab</kbd> key should be programmed to move from the focused tab — which may or may not be the selected tab — to the `tabpanel` which represents the currently selected tab. + +Each `tab` in a `tablist` can serve as the label for its corresponding `tabpanel`. Include the `id` of each `tab` as the value for each `tabpanel`'s [`aria-labelledby`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-labelledby) attribute. + +You can also optionally associate each `tabpanel` with its associated `tab` by including the [`id`](/en-US/docs/Web/HTML/Reference/Global_attributes/id) of the `tabpanel` as the value of the `tab`'s [`aria-controls`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-controls) attribute. + +When a tabbed interface is initialized, one `tabpanel` is displayed and its associated `tab` is styled to indicate that it is active, reflecting its programmatic state. All inactive `tabpanel` elements must be hidden to all users. This is most commonly achieved by use of CSS's `display: none`. + +See the [ARIA `tab` role](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/tab_role) article for more information specific to the use of this role. + +Include [`tabindex="-1"`](/en-US/docs/Web/HTML/Reference/Global_attributes/tabindex) to allow a `tabpanel` to receive focus without including the `tabpanel` in the page's keyboard focus order. + +Make sure to define styles for a `tabpanel` for when it receives focus, optimally using the CSS {{CSSXref(':focus')}} pseudo-class, so keyboard users know there was a change in focus and are aware of what content currently has focus. + +Carousels can be created using this tab pattern: A slide picker controls can be marked up as `tabs` in a `tablist` with the slide represented by a `tabpanel` element. + +### Associated Roles and Attributes + +- [`tab` role](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/tab_role) + - : Controls the visibility of the associated `tabpanel` +- [`tablist` role](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/tablist_role) + - : Group of `tab` elements. +- [`aria-labelledby`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-labelledby) + - : Provides an accessible name. References the `tab` element that controls the panel +- [`aria-expanded`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-expanded) + - : Should be used on the necessary `tab` elements if a multi-selectable `tablist` is used. + +### Keyboard interactions + +See the [`tablist` keyboard interactions](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/tablist_role#keyboard_interactions) in the [`tablist`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/tablist_role) role definition. + +## Example + +See the [`tabpanel`, `tab`, and `tablist` example](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/tab_role#example) in the [`tab`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/tab_role) role definition. + +## Specifications + +{{Specifications}} + +## See also + +- [ARIA `tab` role](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/tab_role) +- [ARIA `tablist` role](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/tablist_role) +- [Example: Tabs with Automatic Activation](https://www.w3.org/WAI/ARIA/apg/example-index/tabs/tabs-automatic.html) - W3C +- [Example: Tabs with Manual Activation](https://www.w3.org/WAI/ARIA/apg/example-index/tabs/tabs-manual.html) -W3C diff --git a/files/en-us/web/accessibility/aria/reference/roles/term_role/index.md b/files/en-us/web/accessibility/aria/reference/roles/term_role/index.md new file mode 100644 index 000000000000000..b90795570de60be --- /dev/null +++ b/files/en-us/web/accessibility/aria/reference/roles/term_role/index.md @@ -0,0 +1,89 @@ +--- +title: "ARIA: term role" +short-title: term +slug: Web/Accessibility/ARIA/Reference/Roles/term_role +page-type: aria-role +spec-urls: https://w3c.github.io/aria/#term +sidebar: accessibilitysidebar +--- + +The `term` role can be used for a word or phrase with an optional corresponding [`definition`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/definition_role). + +## Description + +The `term` role can be used for a word or phrase with an optional corresponding [`definition`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/definition_role). It is equivalent in semantics to the HTML {{HTMLElement('dfn')}} element and the definition term ({{HTMLElement('dt')}}) element within a definition list ({{HTMLElement('dl')}} ). + +The `term` role is used to explicitly identify a word or phrase for which a definition has been provided by the author or is expected to be provided by the user. If there is an existing definition, or a form or form control to enter a definition, authors SHOULD set [`aria-details`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-details) to point to the related element. + +Don't use the `role="term"` on interactive elements like links because it can interfere with assistive technology users ability to interact with the element. Also, the term itself is the accessible name, so do not use [`aria-label`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-label) or [`aria-labelledby`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-labelledby). + +> [!WARNING] +> The accessible name should be the term itself, so DO NOT use `aria-label` or `aria-labelledby`. + +### Associated WAI-ARIA roles, states, and properties + +None. + +### Keyboard interactions + +None. + +### Required JavaScript features + +None. + +## Examples + +```html +<p> + <span role="term">Mansplaining</span>, + <span role="definition" + >a portmanteau of "man" and "explain", is the patronizing act of explaining + without being asked to do so, to someone already learned on the topic, often + after someone has already explained it</span + >. +</p> +``` + +Including better semantics, the above could also be written: + +```html +<p> + <dfn role="term">Mansplaining</dfn>, + <span role="definition" + >a portmanteau of "man" and "explain", is the patronizing act of explaining + without being asked to do so, to someone already learned on the topic, often + after someone has already explained it</span + >. +</p> +``` + +or without any ARIA (but possibly not how you want it presented) + +```html +<dl> + <dt>Mansplaining</dt> + <dd> + A portmanteau of "man" and "explain", is the patronizing act of explaining + without being asked to do so, to someone already learned on the topic, often + after someone has already explained it. + </dd> +</dl> +``` + +## Accessibility concerns + +Don't use the `role="term"` on interactive elements such as links as it can interfere with the assistive technology user's ability to interact with the element. + +## Best practices + +Allow the term itself to define the accessible name. Do not use `aria-label` or `aria-labelledby`. + +## Specifications + +{{Specifications}} + +## See also + +- [ARIA: `definition` role](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/definition_role). +- The HTML {{HTMLElement('dfn')}} element diff --git a/files/en-us/web/accessibility/aria/reference/roles/textbox_role/index.md b/files/en-us/web/accessibility/aria/reference/roles/textbox_role/index.md new file mode 100644 index 000000000000000..16eb327ce337e2b --- /dev/null +++ b/files/en-us/web/accessibility/aria/reference/roles/textbox_role/index.md @@ -0,0 +1,128 @@ +--- +title: "ARIA: textbox role" +short-title: textbox +slug: Web/Accessibility/ARIA/Reference/Roles/textbox_role +page-type: aria-role +sidebar: accessibilitysidebar +--- + +The `textbox` role is used to identify an element that allows the input of free-form text. Whenever possible, rather than using this role, use an {{HTMLElement("input")}} element with [type="text"](/en-US/docs/Web/HTML/Reference/Elements/input/text), for single-line input, or a {{HTMLElement("textarea")}} element for multi-line input. + +## Description + +When an element has the `textbox` role, the browser sends an accessible textbox event to assistive technologies, which can then notify the user about it. + +The default is a single line input, in which <kbd>Return</kbd> or <kbd>Enter</kbd> submits the form; in this case, it is preferable to use an HTML {{HTMLElement("input")}} with `type="text"`. To create a multi-line text box which supports line breaks, as in an HTML {{HTMLElement("textarea")}}, set `aria-multiline="true"`. Including the HTML `contenteditable` attribute ensures the text node is editable. + +```html +<!-- Text input field --> +<div id="txtboxLabel">Enter your five-digit zip code</div> +<div + role="textbox" + contenteditable="true" + aria-placeholder="5-digit zip code" + aria-labelledby="txtboxLabel"></div> + +<!-- Multi-line text area --> +<div id="txtboxMultilineLabel">Enter the tags for the article</div> +<div + role="textbox" + contenteditable="true" + aria-multiline="true" + aria-labelledby="txtboxMultilineLabel" + aria-required="true"></div> +``` + +Semantic elements are more concise and require no JavaScript to support textbox features. + +```html +<label for="txtbox">Enter your five-digit zip code</label> +<input type="text" placeholder="5-digit zip code" id="txtbox" /> + +<!-- Multi-line text area --> +<label for="txtboxMultiline">Enter the tags for the article</label> +<textarea id="txtboxMultiline" required></textarea> +``` + +Where a text field is read-only, indicated this by setting `aria-readonly="true"` on the element. + +### Associated ARIA properties + +- [`aria-activedescendant`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-activedescendant) attribute + - : Taking as it's value the ID of is either a descendant of the element with DOM focus or is a logical descendant as indicated by the [`aria-owns`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-owns) attribute, it indicates when that element has focus, when it is part of a composite widget such as a [`combobox`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/combobox_role). For example, in a combobox, focus may remain on the textbox while the value of `aria-activedescendant` on the textbox element refers to a descendant of a popup listbox that is controlled by the textbox. This attribute must be updated programmatically as the focus changes. +- [`aria-autocomplete`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-autocomplete) attribute + + - : Indicates whether and how the user's input into the field could trigger display of a prediction of the intended value. It supports the following values: + + - `inline`: Predicted text is inserted after the caret. + - `list`: Predicted text is presented as a collection of values. + - `both`: Predicted text is presented as a collection of values, with the text needed to complete one value inserted after the caret. + - `none` (default): Predicted text is not offered. + + If list or both is set, the [`aria-controls`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-controls) and [`aria-haspopup`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-haspopup) attributes should also be included. The value of `aria-controls` is the ID of the element that contains the list of suggested values. Additionally, either the textbox or a containing element with role `combobox` has a value for `aria-haspopup` that matches the role of the element that contains the list of suggested values. + +- [`aria-multiline`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-multiline) attribute + + - : If `aria-multiline="true"` is set, the AT informs the user that the textbox supports multi-line input, with the expectation that <kbd>Enter</kbd> or <kbd>Return</kbd> will create a line break rather than submitting the form. ARIA does not alter the behavior of the element; rather this feature must be controlled by the developer. If false is set, or the attribute is omitted and defaults to false, the user expectation is that the control is a single line text box, and <kbd>Enter</kbd> or <kbd>Return</kbd> submits the form. + +- [`aria-placeholder`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-placeholder) attribute + - : Represents a hint (word or phrase) to the user about what to enter into the text field. The hint should be a sample value or a brief description of the expected format. This information should not be used as a substitute for a label: a label is focusable, permanent, indicates what kind of information is expected, and increases the hit area for setting focus on the control, whereas placeholder text is only temporary hint about the expected value, which if implemented incorrectly can decrease accessibility. The placeholder should be visible when the control's value is the empty string such as when the control first receives focus and when users remove a previously-entered value. Instead of using `aria-placeholder`, use the semantic `<input type="text">` or `<textarea>` with a `placeholder` attribute. +- [`aria-readonly`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-readonly) attribute + - : Indicates that the user cannot modify the value of the text field. Instead of using `aria-readonly`, use the semantic `<input type="text">` or `<textarea>` with a `readonly` attribute. +- [`aria-required`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-required) attribute + - : Indicates that a value must be provided for the field before it is submitted. Instead of using `aria-required`, use the semantic `<input type="text">` or `<textarea>` with a `required` attribute. + +### Keyboard interactions + +In a single-line use (when `aria-multiline` is `false` or not used), the Return or Enter key submits the form. In a multi-line use (when `aria-multiline` is `true`), Return or Enter key inserts a line break. + +### JavaScript features + +All features associated with any and all properties and states must be maintained, and forms submission on enter or return on a single line textbox needs to be handled. + +- Focus event handler and aria-activedescendant attribute + - : If you are implementing a composite widget, such as a combobox composed of a text box and a listbox, you need to manage the `aria-activedescendant` attribute using a handler. Before using this technique, ensure that the browsers you need to target currently support it. See the [specification of aria-descendant](https://www.w3.org/TR/wai-aria-1.1/#aria-activedescendant) for further information. + +> [!NOTE] +> It is a better practice to use an {{HTMLElement("input")}} element with type="text", or a {{HTMLElement("textarea")}} element instead of the ARIA textbox role. When using either semantic element, the ARIA textbox role is not necessary. See [Notes on Using ARIA in HTML](https://www.w3.org/TR/aria-in-html/). + +## Possible effects on user agents and assistive technology + +When the `textbox` role is added to an element, or such an element becomes visible, the user agent should do the following: + +- Expose the element as having a textbox role in the operating system's accessibility API. +- Fire an accessible textbox event using the operating system's accessibility API if it supports it. + +Assistive technology products should listen for such an event and notify the user accordingly: + +- Screen readers should announce its label and role when focus first lands on a textbox. If it also contains content, this should be announced as with a regular textbox. +- Screen magnifiers may enlarge the textbox. + +> [!NOTE] +> Opinions may differ on how assistive technology should handle this technique. The information provided above is one of those opinions and may be experienced differently. + +## Examples + +### Example 1: Adding the role in the HTML code for single line input + +The snippet below shows how the textbox role is added directly into the HTML source code. + +```html +<div role="textbox" contenteditable="true"></div> +``` + +### Example 2: Adding the role in the HTML code for multi-line input + +The snippet below shows how the textbox role is added directly into the HTML source code. + +```html +<div role="textbox" contenteditable="true" aria-multiline="true"></div> +``` + +## Best practices + +Be sure to add the `contenteditable="true"` attribute to the HTML element to which this role is applied. Do so even if you set `aria-readonly` to `true`; in this way, you communicate that the content would be editable if it were not read-only. + +## See also + +- [ARIA: search role](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/search_role) diff --git a/files/en-us/web/accessibility/aria/reference/roles/timer_role/index.md b/files/en-us/web/accessibility/aria/reference/roles/timer_role/index.md new file mode 100644 index 000000000000000..5e4ad9adc7ce8ee --- /dev/null +++ b/files/en-us/web/accessibility/aria/reference/roles/timer_role/index.md @@ -0,0 +1,49 @@ +--- +title: "ARIA: timer role" +short-title: timer +slug: Web/Accessibility/ARIA/Reference/Roles/timer_role +page-type: aria-role +spec-urls: https://w3c.github.io/aria/#timer +sidebar: accessibilitysidebar +--- + +The **`timer`** role indicates to assistive technologies that an element is a numerical counter listing the amount of elapsed time from a starting point or the remaining time until an end point. Assistive technologies will not announce updates to a timer as it has an implicit [aria-live](https://www.w3.org/TR/wai-aria/#aria-live) value of `off`. + +```html +<div role="timer" id="eggtimer">0</div> +``` + +This defines this `div` element as a timer with no remaining time. + +## Description + +The `timer` role indicates to assistive technologies that this part of the web content is a live region containing a timer listing the time remaining or elapsed time. A timer's inner text should be an updating current time measurement. While the value does not necessarily need to be machine parsable, it should continuously update at regular intervals unless the timer is paused or reaches its end-point. + +Along with [`alert`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/alert_role), [`log`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/log_role), [`marquee`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/marquee_role), and [`status`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/status_role) the `timer` role is a live region and can be modified by [live region](/en-US/docs/Web/Accessibility/ARIA/Guides/Live_regions) attributes. + +### Associated WAI-ARIA roles, states, and properties + +- [`aria-label`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-label) or [`aria-labelledby`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-labelledby) + + - : Some screen readers announce the name of a timer element before announcing its contents. If a name is visible, reference it using `aria-labelledby`. Including an `aria-label` provides a method for prefacing the visible content of a timer element with text that is not displayed when a screen reader reads the content. Naming a timer is not required so if nothing is appropriate both these attributes can be omitted. + +- [`aria-live`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-live) + + - : Elements with the role `timer` have an implicit [aria-live](https://www.w3.org/TR/wai-aria/#aria-live) value of `off`. + +## Accessibility concerns + +If a time limit needs to be in place, for example, for security reasons, the user should have the option to turn it off or extend it. This restriction does not apply if the time limit is due to a live event, such as an auction or a game, or if the time to complete the form is essential for a valid submission. + +## Specifications + +{{Specifications}} + +## See also + +- [ARIA: `alert` role](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/alert_role) +- [ARIA: `log` role](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/log_role) +- [ARIA: `marquee` role](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/marquee_role) +- [ARIA: `status` role](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/status_role) +- [ARIA live regions](/en-US/docs/Web/Accessibility/ARIA/Guides/Live_regions) +- [`timer` example on CodePen](https://codepen.io/heydon/pres/NGgNjZ) by Heydon Pickering diff --git a/files/en-us/web/accessibility/aria/reference/roles/toolbar_role/index.md b/files/en-us/web/accessibility/aria/reference/roles/toolbar_role/index.md new file mode 100644 index 000000000000000..dc7a0ffab1e4efb --- /dev/null +++ b/files/en-us/web/accessibility/aria/reference/roles/toolbar_role/index.md @@ -0,0 +1,104 @@ +--- +title: "ARIA: toolbar role" +short-title: toolbar +slug: Web/Accessibility/ARIA/Reference/Roles/toolbar_role +page-type: aria-role +spec-urls: + - https://w3c.github.io/aria/#toolbar + - https://www.w3.org/WAI/ARIA/apg/patterns/toolbar/examples/toolbar/ +sidebar: accessibilitysidebar +--- + +The `toolbar` role defines the containing element as a collection of commonly used function buttons or controls represented in a compact visual form. + +## Description + +A toolbar is a collection of commonly used controls, such as buttons or checkboxes, grouped together in a compact visual form. The `toolbar` role can be used to communicate the presence and purpose of such a grouping to screen reader users and can help reduce the number of tab stops for keyboard users. Only use the `toolbar` role to group 3 or more controls. + +The toolbar is commonly a subset of functions found in a `menubar` as a way to reduce user effort. If you have more than one toolbar in a menubar, each toolbar requires a label; which you can include with [`aria-labelledby`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-labelledby) or [`aria-label`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-label). + +When creating a toolbar, you need to implement focus management and keyboard interactions within the toolbar, handling when the same keyboard interactions is used both in the toolbar and in included native control. The <kbd>Left Arrow</kbd> and <kbd>Right Arrow</kbd> should be used to navigate between the controls within a horizontal tool bar. The <kbd>Up Arrow</kbd> and <kbd>Down Arrow</kbd> should be used if the toolbar is vertical — in which case you also want to include the `aria-orientation="vertical"` — or, in a horizontal toolbar, can be reserved for operating controls, such as spin buttons that require vertical arrow keys to operate. + +Avoid including controls whose operation requires arrow keys used for toolbar navigation. If you must include such a control, make it the last control in the toolbar. For example, in a horizontal toolbar, a textbox could be included as the last element. + +If any of the otherwise interactive elements within the toolbar are temporarily disabled, consider letting them remain focusable so screen reader users can be made aware of their presence. + +### Associated WAI-ARIA roles, states, and properties + +- [`aria-orientation`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-orientation) + + - : Elements with the role toolbar have an implicit `aria-orientation` value of horizontal. + +- [`aria-labelledby`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-labelledby) / [`aria-label`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-label) + - : If the toolbar has a visible label, reference it by ID with the `aria-labelledby` attribute. Otherwise, provide an `aria-label`. If there is more than one toolbar in a menu, naming is required. + +### Keyboard interactions + +Implement focus management so the keyboard tab sequence includes one stop for the toolbar and arrow keys move focus among the controls in the toolbar. + +- <kbd>Tab</kbd> and <kbd>Shift + Tab</kbd> + + - : Move focus into and out of the toolbar. When focus moves into a toolbar: + + - If focus is moving into the toolbar for the first time, focus is set on the first control that is not disabled. + - If the toolbar has previously contained focus, focus is optionally set on the control that last had focus. Otherwise, it is set on the first control that is not disabled. + +- <kbd>Home</kbd> (Optional) + + - : Moves focus to first element. + +- <kbd>End</kbd> (Optional) + - : Moves focus to last element. + +#### Horizontal toolbar + +Elements with the role toolbar have an implicit `aria-orientation` value of horizontal. If the toolbar indeed has this orientation, the following keyboard interactions need to be implemented: + +- <kbd>Left Arrow</kbd> (For a horizontal toolbar (the default) + + - : Moves focus to the previous control. Optionally, focus movement may wrap from the first element to the last element. + +- <kbd>Right Arrow</kbd> (For a horizontal toolbar (the default) + - : Moves focus to the next control. Optionally, focus movement may wrap from the last element to the first element. + +In toolbars with multiple rows of controls, allow the left and right arrows to wraps from row to row, leaving the option of reserving vertical arrow keys for operating controls, such as navigating among radios buttons, or incrementing/decrementing a numeric spinner. + +#### Vertical toolbar + +If the toolbar is vertical, ensure `aria-orientation="vertical"` is set, and the following keyboard interactions are implemented: + +- <kbd>Down Arrow</kbd> (For a horizontal toolbar (the default) + + - : Moves focus to the previous control. Optionally, focus movement may wrap from the first element to the last element. + +- <kbd>Up Arrow</kbd> (For a horizontal toolbar (the default) + - : Moves focus to the next control. Optionally, focus movement may wrap from the last element to the first element. + +### Required JavaScript features + +Implement focus management so the keyboard tab sequence includes one stop for the toolbar and arrow keys move focus among the controls in the toolbar. When tabbing into the toolbar, focus returns to the control that last had focus. + +While the toolbar element itself does not receive focus, focus on movement into, out of, and within the toolbar has to be managed. On load, the first element in the tabbing sequence within the toolbar has `tabindex="0"` with `tabindex="-1"` set on all other focusable elements within the toolbar. Depending on the [keyboard interaction], the element receiving focus gets set to `tabindex="0"` and the element that just lost focus gets switched back to `tabindex="-1"`. Set focus, `element.focus()`, on the element that has `tabindex="0"`. This is called "roving tabindex". A benefit of using roving tabindex to manage focus is that the browser will scroll the newly focused element into view. + +If the design calls for a specific element to be focused the next time the user moves focus into the toolbar with <kbd>Tab</kbd> or <kbd>Shift + Tab</kbd>, check if that target element has `tabindex="0"` when toolbar loses focus. + +When the toolbar has focus within it, provide visual cues. When an element within the toolbar has focus, a visual cue must be included on both the toolbar itself - to help the toolbar supports directional navigation with the arrow keys - and the control that has focus. The CSS pseudoclasses of `:focus` and `:focus-within` can be used to target both elements. + +## Examples + +[Toolbar example from <abbr>W3C</abbr>, the World Wide Web Consortium](https://www.w3.org/TR/wai-aria-practices-1.2/examples/toolbar/toolbar.html) + +## Accessibility concerns + +Avoid including controls whose operation requires arrow keys used for toolbar navigation (right and left arrows, or top and bottom for vertical toolbars). If you must include such a control, make it the last control in the toolbar. For example, in a horizontal toolbar, a textbox could be included as the last element. + +If any of the otherwise interactive elements within the toolbar are disabled, consider letting them remain focusable so screen reader users can be made aware of their presence. + +## Specifications + +{{Specifications}} + +## See also + +- [The CSS `:focus` pseudoclass](/en-US/docs/Web/CSS/:focus) +- [The CSS `:focus-within` pseudoclass](/en-US/docs/Web/CSS/:focus-within) diff --git a/files/en-us/web/accessibility/aria/reference/roles/tooltip_role/index.md b/files/en-us/web/accessibility/aria/reference/roles/tooltip_role/index.md new file mode 100644 index 000000000000000..0a7755a04daa09d --- /dev/null +++ b/files/en-us/web/accessibility/aria/reference/roles/tooltip_role/index.md @@ -0,0 +1,119 @@ +--- +title: "ARIA: tooltip role" +short-title: tooltip +slug: Web/Accessibility/ARIA/Reference/Roles/tooltip_role +page-type: aria-role +spec-urls: https://w3c.github.io/aria/#tooltip +sidebar: accessibilitysidebar +--- + +A `tooltip` is a contextual text bubble that displays a description for an element that appears on pointer hover or keyboard focus. + +## Description + +Tooltips provide contextual information about an element when that owning element receives focus or is hovered over, but is otherwise not visible on the page. The tooltip is displayed automatically, after a brief delay; the user does not request it. While a tooltip can be placed on any content, they generally are tips for tools or controls, such as providing additional content for icons that have brief labels (or no labels at all, which is not accessible!). + +A tooltip typically becomes visible, after a short delay of generally one to five seconds, in response to a mouse hover, or after the owning element receives keyboard focus. Just as it is opened automatically, without user request, it is closed automatically when the focus is lost or on mouse out. It must stay open when the mouse moves over the tooltip itself, and should also close when the user presses the <kbd>Escape</kbd> key. + +Because the tooltip itself never receives focus and is not in the tabbing order, a tooltip can not contain interactive elements like links, inputs, or buttons. + +The tooltip is not the appropriate role for the more information "i" icon, ⓘ. A tooltip is directly associated with the owning element. The ⓘ isn't 'described by' detailed information; the tool or control is. + +The use of the ARIA `tooltip` role is a supplement to the normal browser tooltip behavior. An example of a native browser tooltip is the way some browsers display an element's [`title` attribute](/en-US/docs/Web/HTML/Reference/Global_attributes/title) on long mouse hover. One cannot activate this feature through either keyboard focus or through touch interaction, making this feature inaccessible. If the information is important enough to include as a tooltip or title, consider including it in visible text. + +Elements with the `tooltip` role should be referenced through the use of [`aria-describedby`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-describedby) before or when the tooltip is displayed. The `aria-describedby` attribute is on the owning element, not on the tooltip. + +The tooltip is not considered a popup in terms of the [`aria-haspopup`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-haspopup) property on the owning element, which is why we used "text bubble" in the introductory definition. + +Though a tooltip may appear and disappear, as its appearance is automatic and not intentionally controlled by the user, the [`aria-expanded`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-expanded) role is not supported. + +The accessible name of a tooltip can come from the contents. While, in theory, they could come from an [`aria-label`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-label) or [`aria-labelledby`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-labelledby), in most cases, using ARIA properties to provide a tooltip with an accessible name is not recommended. + +Tooltips provide additional information, generally with no direct interaction on the tooltip itself. They are generally associated with the content they're defining via an [`aria-describedby`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-describedby) with the `id` of the primary element. Therefore, if the tooltip has an accessible name explicitly set, that name is exposed as the primary element's description rather than the contents of the tooltip, meaning the tooltip contents may never be discovered by a screen reader user. + +### Associated WAI-ARIA roles, states, and properties + +- The element that serves as the tooltip container has `role="tooltip"` set. +- The element that triggers the tooltip references the tooltip element with [`aria-describedby`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-describedby). + +### Keyboard interactions + +- <kbd>Escape</kbd> + - : Closes the tooltip + +The tooltip should appear on focus or when the element is hovered on, without additional interaction. It should disappear automatically when the focus on the owning element is lost or the mouse is moved outside the owning element and the tooltip. While the tooltip does not receive focus, the <kbd>Escape</kbd> should close it if it is open. + +### Required JavaScript features + +- The tooltip is displayed and disappears via keyboard focus and removal of focus and by the mouse events - mousing over and mousing out. + +- The tooltip never receives focus. Focus stays on the owning element. + +- The tooltip can be hidden with the <kbd>Escape</kbd> key + +- The tooltip stays open when hovered + +- The tooltip is only hidden via JavaScript and CSS selectors. If JavaScript is not available the tooltip is shown. + +## Examples + +```html +<label for="password">Password:</label> +<input aria-describedby="passwordrules" id="password" type="password" /> +<div role="tooltip" id="passwordrules"> + <p>Password Rules:</p> + <ul> + <li>Minimum of 8 characters</li> + <li> + Include at least one lowercase letter, one uppercase letter, one number + and one special character + </li> + <li>Unique to this website</li> + </ul> +</div> +``` + +The tooltip can be instantiated with CSS. Change the class name with JavaScript to a class that hides the tooltip if the user hits the <kbd>Escape</kbd> key. + +```css +[role="tooltip"], +.hide-tooltip.hide-tooltip.hide-tooltip + [role="tooltip"] { + visibility: hidden; + position: absolute; + top: 2rem; + left: 2rem; + background: black; + color: white; +} +[aria-describedby]:hover, +[aria-describedby]:focus { + position: relative; +} +[aria-describedby]:hover + [role="tooltip"], +[aria-describedby]:focus + [role="tooltip"] { + visibility: visible; +} +``` + +The above hides the tooltip with CSS in the default state or if the `hide-tooltip` class has been added with JavaScript (when the user hit <kbd>Escape</kbd>), with high specificity to ensure the tooltip doesn't show. When the owning element receives focus, it gets positioned relatively and the tooltip becomes visible. + +## Accessibility concerns + +If the information is important enough for a tooltip, isn't it important enough to always be visible? + +The tooltip must stay open when hovered, even if that technically means the mouse moves out of the owning element. As content which appears on hover can be difficult or impossible to perceive if a user is required to keep their mouse pointer over the trigger, [WCAG 1.4.13](/en-US/docs/Web/Accessibility/Guides/Understanding_WCAG/Perceivable#guideline_1.4_make_it_easier_for_users_to_see_and_hear_content_including_separating_foreground_from_background) states that content made visible should be persistent, meaning it should not disappear without user action. + +## Best practices + +Instead of using tooltips and hiding important information, consider writing clear, succinct, always visible descriptions. If you have space, don't use tooltips or toggletips. Just provide clear labels and sufficient body text. + +## Specifications + +{{Specifications}} + +## See also + +- [The `dialog` role](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/dialog_role) +- [CSS: `:focus` pseudoclass](/en-US/docs/Web/CSS/:focus) +- [Tooltips & Toggletips](https://inclusive-components.design/tooltips-toggletips/) by Heydon Pickering +- [Understanding SC 1.4.13:Content on Hover or Focus (WCAG Level AA)](https://www.w3.org/WAI/WCAG21/Understanding/content-on-hover-or-focus.html) diff --git a/files/en-us/web/accessibility/aria/reference/roles/tree_role/index.md b/files/en-us/web/accessibility/aria/reference/roles/tree_role/index.md new file mode 100644 index 000000000000000..d7e1036d83a8fb4 --- /dev/null +++ b/files/en-us/web/accessibility/aria/reference/roles/tree_role/index.md @@ -0,0 +1,239 @@ +--- +title: "ARIA: tree role" +short-title: tree +slug: Web/Accessibility/ARIA/Reference/Roles/tree_role +page-type: aria-role +spec-urls: + - https://w3c.github.io/aria/#tree + - https://www.w3.org/WAI/ARIA/apg/patterns/treeview/examples/treeview-navigation/ +sidebar: accessibilitysidebar +--- + +A `tree` is a widget that allows the user to select one or more items from a hierarchically organized collection. + +## Description + +A `tree` widget is a hierarchical list with parent and child nodes that can expand and collapse. Any item in the hierarchy may have child tree items, set with [`role="treeitem"`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/treeitem_role). Tree items that have children can be expanded or collapsed, showing and hiding their children. + +An example of a `tree` is a file system selection user interface: a tree view displaying folders and files. Folder items can be expanded to reveal the contents of the folder — which may be files, folders, or both — and collapsed, hiding its contents. + +ARIA tree views are navigated primarily with arrow keys on the keyboard instead of the <kbd>Tab</kbd>. This form of navigation is not common for most browser content, though normal and expected for native applications. For this reason, before creating a tree view, consider alternative options to address the functionality you need. + +> [!WARNING] +> Tree views use navigation more similar to native applications than to web applications. For this reason, consider alternative options to address the functionality you need before creating a tree view. + +### Single and multiple select trees + +Trees can be "single-select", allowing users to choose just one item for an action, or "multi-select", where users are able to select more than one item for an action. In multi-select trees, the `tree` has [`aria-multiselectable`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-multiselectable) set to true. Otherwise, `aria-multiselectable` is either set to `false` or the default value of `false` is implied. In both cases, to be keyboard accessible, focus must be managed for all tree descendants. + +In some implementations of single-select tree, the focused item also has a selected state; this is known as "selection follows focus". When a single-select tree receives focus, if none of the tree items are selected before the tree receives focus, focus is set on the first node. If a tree item is selected before the tree receives focus, focus is set on the selected tree item. In single-select trees, [`aria-selected`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-selected) is set to `true` for the selected tree items and it is not present on any other tree item in the tree. + +In multi-select trees, all selected tree items have `aria-selected="true"` set and all tree item nodes that are selectable but not currently selected have `aria-selected="false"` set. Do not includes the `aria-selected` attribute on tree items that are not selectable. + +When a multi-select tree receives focus, if none of the tree items are selected before the tree receives focus, focus is set on the first tree item. If one or more tree items are selected before the tree receives focus, focus is set on the first selected node. + +In multi-select trees, the selected state is always independent of the focus. For example, in a typical file system navigator, the user can move focus to select any number of files for an action, such as copy or move. The visual design should make it clear which items are selected and which item has focus. + +### Tree hierarchy + +In a tree view, the `tree` node is the root node; it can have child, grandchild, and further descendant `treeitem` nodes. + +Each element serving as a tree node has role `treeitem`, except for the root tree node which has a role of `tree`. A `tree` does not have a parent `tree` node - it is the root node. If a node is both nested in a tree and has descendant tree items, then it has the role `treeitem` and the [`aria-expanded`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-expanded) attribute; `aria-expanded="false"` is set when the node is in a closed state, `aria-expanded="true"` is set when the node is in an open state. + +`treeitem` nodes can be direct children of the `tree` root node, nested within a `treeitem` node, or, optionally nested in a [`group`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/group_role) element, which, when nested in a `tree` is an expandable collection of treeitem elements. + +Do not include `aria-expanded` on end nodes — those without tree item children — as that would incorrectly describe the node as a parent node to assistive technologies. + +### DOM placement and presence + +All treeitems are contained in or owned by an element with role `tree`. If there are any tree items that are not direct descendants of the `tree` in the markup, include [`aria-owns`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-owns) on the owning tree container to include elements that are not DOM children of the container. These non-child owned elements will appear in the reading order in the sequence they are referenced and after any tree items that are DOM children. Scripts that manage focus need to ensure the visual focus order matches this assistive technology reading order. + +If the complete set of available nodes is not present in the DOM due to dynamic loading as the user moves focus in or scrolls the tree, each node has [`aria-level`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-level), [`aria-setsize`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-setsize), and [`aria-posinset`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-posinset) specified. + +### Accessible name + +The `tree` must be provided with an accessible name. Either reference a visible label referenced with [`aria-labelledby`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-labelledby) or specify a label with [`aria-label`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-label). + +### Menu orientation + +Elements with the role `tree` have an implicit [`aria-orientation`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-orientation) value of vertical. If the tree element is horizontally oriented, include `aria-orientation="horizontal"`. + +### Associated WAI-ARIA roles, states, and properties + +- [`role="treeitem"`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/treeitem_role) + - : An item in a tree. +- [`role="group"`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/group_role) + - : An expandable collection of tree items. +- [`aria-labelledby`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-labelledby) + - : Identifies the element (or elements) that labels the `tree` providing the required accessible name when a visible label is present. Otherwise use `aria-label`. +- [`aria-label`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-label) + - : Defines a string value that labels the `tree` when no visible label is present. +- [`aria-orientation`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-orientation) + - : indicates whether the tree orientation is horizontal or vertical; defaults to `vertical` if omitted. +- [`aria-multiselectable`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-multiselectable) + - : When set to true, indicates the user may select more than one tree item from the tree's current selectable descendants. + +### Keyboard interactions + +For a vertically oriented `tree`, which is the default orientation: + +<table> +<tr> +<td><kbd>Right arrow</kbd></td> +<td> +<ul> +<li>When focus is on a closed node, opens the node; focus does not move. +<li>When focus is on an open node, moves focus to the first child node. +<li>When focus is on an end node (a tree item with no children), does nothing. +</td> +</tr> +<tr> +<td><kbd>Left arrow</kbd></td> +<td> +<ul> +<li>When focus is on an open node, closes the node. +<li>When focus is on a child node that is also either an end node or a closed node, moves focus to its parent node. +<li>When focus is on a closed tree, does nothing. +</td> +</tr> +<tr> +<td><kbd>Down Arrow</kbd></td> +<td> Moves focus to the next node that is focusable without opening or closing a node. +</td> +</tr> +<tr> +<td><kbd>Up Arrow</kbd></td> +<td> Moves focus to the previous node that is focusable without opening or closing a node. +</td> +</tr> +<tr> +<td><kbd>Home</kbd></td> +<td> Moves focus to the first node in the tree without opening or closing a node. +</td> +</tr> +<tr> +<td><kbd>End</kbd></td> +<td> Moves focus to the last node in the tree that is focusable without opening the node. +</td> +</tr> +<tr> +<td><kbd>Enter</kbd></td> +<td>Performs the default action of the currently focused node. For parent nodes, it opens or closes the node. In single-select trees, if the node has no children, selects the current node if not already selected (which is the default action). +</td> +</tr> +<tr> +<td>Type a character*</td> +<td> +<ul> +<li>Focus moves to the next node with a name that starts with the typed character. +<li>If multiple characters are typed in rapid succession, focus moves to the next node with a name that starts with the string of characters typed. +</td> +</tr> +<tr> +<td> +<kbd>*</kbd> (Optional)</td> +<td> Expands all siblings that are at the same level as the current node. +</td> +</tr> +</table> + +\* Type-ahead is recommended for all trees, especially for trees with more than 7 root nodes + +### Multi-select keyboard interactions + +There are two interaction models for multi-select trees: While you can require that users press a modifier key, such as <kbd>Shift</kbd> or <kbd>Control</kbd> while navigating the list in order to avoid losing selection states, the model that does not require the user to hold a modifier key is recommended. + +#### Recommended multi user select model + +<table> +<tr> +<td><kbd>Space</kbd></td> +<td> Toggles the selection state of the focused node. +</td> +</tr> +<tr> +<td><kbd>Shift + Down Arrow</kbd> (Optional)</td> +<td> Moves focus to and toggles the selection state of the next node. +</td> +</tr> +<tr> +<td><kbd>Shift + Up Arrow</kbd> (Optional)</td> +<td> Moves focus to and toggles the selection state of the previous node. +</td> +</tr> +<tr> +<td><kbd>Shift + Space</kbd> (Optional)</td> +<td> Selects contiguous nodes from the most recently selected node to the current node. +</td> +</tr> +<tr> +<td><kbd>Control + Shift + Home</kbd> (Optional)</td> +<td> Selects the node with focus and all nodes up to the first node. Optionally, moves focus to the first node. +</td> +</tr> +<tr> +<td><kbd>Control + Shift + End</kbd> (Optional)</td> +<td> Selects the node with focus and all nodes down to the last node. Optionally, moves focus to the last node. +</td> +</tr> +<tr> +<td><kbd>Control + A</kbd> (Optional)</td> +<td> Selects all nodes in the tree. Optionally, if all nodes are selected, it can also unselect all nodes.</td> +</tr> +</table> + +#### Alternative multi-selection model + +The alternative multi-selection model is a modifier key model in which moving focus without holding a modifier key such as <kbd>Shift</kbd> or <kbd>Control</kbd> unselects all selected nodes except for the focused node: + +<table> +<tr> +<td><kbd>Shift + Down Arrow</kbd></td> +<td> Moves focus to and toggles the selection state of the next node. +</td> +</tr> +<tr> +<td><kbd>Shift + Up Arrow</kbd></td> +<td> Moves focus to and toggles the selection state of the previous node. +</td> +</tr> +<tr> +<td><kbd>Control + Down Arrow</kbd></td> +<td> Without changing the selection state, moves focus to the next node. +</td> +</tr> +<tr> +<td><kbd>Control + Up Arrow</kbd></td> +<td> Without changing the selection state, moves focus to the previous node. +</td> +</tr> +<tr> +<td><kbd>Control + Space</kbd></td> +<td> Toggles the selection state of the focused node. +</td> +</tr> +<tr> +<td><kbd>Shift + Space</kbd> (Optional)</td> +<td> Selects contiguous nodes from the most recently selected node to the current node. +</td> +</tr> +<tr> +<td><kbd>Control + Shift + Home</kbd> (Optional)</td> +<td> Selects the node with focus and all nodes up to the first node. Optionally, moves focus to the first node. +</td> +</tr> +<tr> +<td><kbd>Control + Shift + End</kbd> (Optional)</td> +<td> Selects the node with focus and all nodes down to the last node. Optionally, moves focus to the last node. +</td> +</tr> +<tr> +<td><kbd>Control + A</kbd> (Optional)</td> +<td> Selects all nodes in the tree. Optionally, if all nodes are selected, it can also unselect all nodes. +</td> +</tr> +</table> + +## Specifications + +{{Specifications}} diff --git a/files/en-us/web/accessibility/aria/reference/roles/treegrid_role/index.md b/files/en-us/web/accessibility/aria/reference/roles/treegrid_role/index.md new file mode 100644 index 000000000000000..09f47adf5a80b08 --- /dev/null +++ b/files/en-us/web/accessibility/aria/reference/roles/treegrid_role/index.md @@ -0,0 +1,154 @@ +--- +title: "ARIA: treegrid role" +short-title: treegrid +slug: Web/Accessibility/ARIA/Reference/Roles/treegrid_role +page-type: aria-role +spec-urls: + - https://w3c.github.io/aria/#treegrid + - https://www.w3.org/WAI/ARIA/apg/patterns/treegrid/examples/treegrid-1/ +sidebar: accessibilitysidebar +--- + +The `treegrid` role identifies an element as being grid whose rows can be expanded and collapsed in the same manner as for a `tree`. + +## Description + +A `treegrid` is a hierarchical data grid, or table, consisting of tabular information that is editable or interactive. A `treegrid` is a combination of the [`tree`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/tree_role) and [`grid`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/grid_role) roles. Like a `grid`, the `treegrid` is made up of rows, columns, and gridcells. Like a `tree`, parent nodes in a `treegrid` are expandable and collapsible. +The `treegrid` widget contains one or more [`row`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/row_role) elements, optionally with [`rowgroup`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/rowgroup_role) elements grouping the rows. Each row, in turn, contains one or more cells. Each cell is either a DOM descendant of or owned by a row element and is either a [`columnheader`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/columnheader_role), [`rowheader`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/rowheader_role), or [`gridcell`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/gridcell_role) element, with the `gridcell` role being used for all cells that do not contain column or row header information. + +A `row` that can be expanded or collapsed to show or hide a set of child rows is a **parent row**. Each parent row has the [`aria-expanded`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-expanded) state set on either the row element or on a cell contained in the row. + +The `aria-expanded` state is set to `true` when the child rows are displayed and set to `false` when the child rows are hidden. Elements that do not control display of child rows should not have the `aria-expanded` attribute because the presence of the attribute indicates to assistive technologies that the element with the attribute is a parent. + +When your grid UI calls for rows supporting `aria-expanded` or if your grid requires supporting [`aria-posinset`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-posinset), [`aria-setsize`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-setsize), or [`aria-level`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-level), use `treegrid` and not `grid`. + +Each `row` or `gridcell` in a row should be keyboard focusable, and keyboard focus for all these tree grid descendants must be managed. The exception to this rule is column header cells which aren't required to be focusable if they do not provide functionality such as sort or filter. Every row and cell should either contain a focusable element or be focusable itself, regardless of whether individual cell content is editable or interactive. + +### Single and multi-select treegrids + +If the `treegrid` allows the user to choose just one item for an action, then it is known as a **single-select** treegrid. In single-select treegrids, the item with focus also has a selected state set with [`aria-selected`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-selected). + +If the treegrid supports selection of more than one row or cell, it is a **multi-select** treegrid. In the multi-select treegrid, the selected state is independent of the focus. The visual design and assistive technologies must distinguish between items that are selected and the item that has focus. + +For multi-select treegrids, include [`aria-multiselectable="true"`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-multiselectable) on the element with the `treegrid` role. All selected rows or cells have [`aria-selected`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-selected) set to true. All rows and cells that are selectable but not currently selected have `aria-selected` set to `false`. Don't include the `aria-selected` attribute on rows and cells that are not individually selectable as the presence of the attribute indicates to assistive technologies that the row or cell is selectable. + +### Orphan rows + +In cases where a child `row` or `rowgroup` is not nested within the `treegrid` in the DOM, the [`aria-owns`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-owns) attribute, referencing all of the IDs of the non-descendant children must be set on the `treegrid` element. If rows or cells are included in a treegrid via `aria-owns`, they will be presented to assistive technologies after the DOM descendants of the `treegrid` element unless the grid's actual DOM descendants are also included in the `aria-owns` attribute. + +### Treegrids with dynamically loaded content + +If some rows or columns are not in the DOM and are dynamically loaded when scrolling, [`aria-colcount`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-colcount), [`aria-rowcount`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-rowcount), [`aria-colindex`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-colindex) and [`aria-rowindex`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-rowindex) come into play. The `aria-colcount` and `aria-rowcount` properties get set on the `treegrid`. The values being the total number of columns and rows of the fully loaded grid, respectively. The indexes for each row and column get set on individual cells, not on the `treegrid` element. + +### A treegrid's accessible name, description, and focus + +The element with the role of `treegrid` must have an accessible name. If an appropriate label is visible in the content, provide the name via [`aria-labelledby`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-labelledby). In other words, if there is an element in the user interface that serves as a label for the treegrid, include `aria-labelledby` as an attribute on the element with the role of `treegrid`, and set the value of the attribute to the `id` of the labelling element or elements. If no visible label is present, use [`aria-label`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-label) instead. Not both. + +If the content includes a caption or description for the `treegrid`, include [`aria-describedby`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-describedby) on the `treegrid` element with the attribute value being the `id` of the element containing the description. + +If the `treegrid` container itself receives focus, the value of its [`aria-activedescendant`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-activedescendant) property should reference the [`id`](/en-US/docs/Web/HTML/Reference/Global_attributes/id) of the selected `row`, `columnheader`, `rowheader` or `gridcell`, unless roving tabindex is used to manage focus between those roles, in which case `aria-activedescendant` should not be used. + +If the `treegrid` is disabled, make that disabled state visually apparent, programmatically enforced, and include the [`aria-disabled`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-disabled) attribute on the `treegrid` itself to inform assistive technologies of its disabled state. + +### Treegrid sorting + +If the treegrid provides sort functions, the [`aria-sort`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-sort) attribute is included on relevant header cell elements, not on the grid itself. + +### Treegrid menus + +If the `treegrid` has an attached [`menu`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/menu_role) that opens when right clicked, include [`aria-haspopup="true"`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-haspopup) on the `treegrid` element. This informs assistive technologies that the `treegrid` has an associated popup. The ability for both keyboard and pointer device users to open and set focus in the menu must be added with JavaScript. + +### Read-only treegrids + +By default, treegrids are assumed to be editable. If a tree grid is not editable, use the [`aria-readonly`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-readonly) attribute to inform assistive technologies the `treegrid` is readonly. The attribute value, when set on the element with the `treegrid` role, propagates down to all `columnheader`, `rowheader`, and `gridcell` elements. That global value can be overridden for individual `gridcell` elements by including `aria-readonly` on individual tree grid element descendants. + +Like all ARIA attributes, adding `aria-readonly` only informs assistive technologies that the content is or is not editable, but it does nothing to enable or disable interactivity. That must be done with HTML's global [`contenteditable`](/en-US/docs/Web/HTML/Reference/Global_attributes/contenteditable) attribute or with JavaScript. + +### Associated WAI-ARIA roles, states, and properties + +- [`row`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/row_role) role + - : A row of cells within a tabular structure, optionally within a `rowgroup`. Contains one or more rows of grid cells, column headers, or row headers. +- [`rowgroup`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/rowgroup_role) role + - : A group of [rows](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/row_role) within a tabular structure. +- [`gridcell`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/gridcell_role) role + - : Intended to mimic the functionality of the HTML {{HTMLElement('td')}} element, is found in `grid` and `treegrid` roles and must be the direct child of a `row`. +- [columnheader](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/columnheader_role) role + - : A cell in a row containing header information for a column, similar to the native {{HTMLElement('th')}} element with column scope +- [rowheader](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/rowheader_role) role + - : A cell containing header information for a `row` within a tabular structure. +- [`aria-expanded`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-expanded) + - : For expandable items, the value is `true` or `false`. Also indicates that the item is expandable, so should not be present if the item cannot be expanded. +- [`aria-owns`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-owns) + - : Identifies a contextual relationship between a parent and its child elements when the DOM hierarchy cannot be used to represent the relationship +- [`aria-labelledby`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-labelledby) + - : Use this attribute to label the `treegrid`. The `aria-labelledby` attribute is generally the id of the element used to title the treegrid. +- [`aria-label`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-label) + - : A human-readable string value which identifies the `treegrid`. If there's a visible label, then `aria-labelledby` should be used instead. + +### Keyboard interactions + +Being able to move focus among rows and cells of the grid with a keyboard must be implemented in order to create an accessible treegrid. Moving focus into the grid may result in the first cell or the first row being focused. Whether focus goes to the next adjacent cell or the row depends on its content requirements, with some treegrids not providing focus to rows. + +The following keyboard interactions need to be supported when an element in the grid has received focus, e.g., after a user has moved focus to the grid with Tab. + +- <kbd>Enter</kbd> + - : If cell-only focus is enabled and focus is on the first cell with the `aria-expanded` property, opens or closes the child rows. Otherwise, performs the default action for the cell. +- <kbd>Tab</kbd> + - : If the row containing focus contains focusable elements such as an {{HTMLElement('input')}}, {{HTMLElement('button')}} or {{HTMLElement('a')}}, moves the focus to the next input in the row. If focus is on the last focusable element in the row, moves focus out of the treegrid widget to the next focusable element. +- <kbd>Right Arrow</kbd> + - : If focus is on a collapsed row, expand the row. If focus is on an expanded row or is on a row that does not have child rows, moves focus to the first cell in the row. If focus is on the right-most cell in a row, focus does not move. If focus is on any other cell, moves focus one cell to the right. +- <kbd>Left Arrow</kbd> + - : If focus is on an expanded row, collapses the row. If focus is on a collapsed row or on a row that does not have child rows, focus does not move. If focus is on the first cell in a row and row focus is supported, moves focus to the row. If focus is on the first cell in a row and row focus is not supported, focus does not move. If focus is on any other cell, moves focus one cell to the left. +- <kbd>Down Arrow</kbd> + - : If focus is on a row, moves focus one row down. If focus is on the last row, focus does not move. If focus is on a cell, moves focus one cell down. If focus is on the bottom cell in the column, focus does not move. +- <kbd>Up Arrow</kbd> + - : If focus is on a row, moves focus one row up. If focus is on the first row, focus does not move. If focus is on a cell, moves focus one cell up. If focus is on the top cell in the column, focus does not move. +- <kbd>Page Down</kbd> + - : If focus is on a row or cell, moves focus down a predetermined number of rows or cells. Usually, it moves down the equivalent of the height of the treegrid, scrolling so the bottom row in the currently visible set of rows becomes one of the first visible rows. If focus is in the last row, focus does not move. +- <kbd>Page Up</kbd> + - : If focus is on a row or cell, moves focus up an predetermined number of rows. Usually, it moves up the equivalent of the height of the treegrid, scrolling so the top row in the currently visible set of rows becomes one of the last visible rows. If focus is in the first row, focus does not move. +- <kbd>Home</kbd> <kbd>Control + Home</kbd> + - : If focus is on a row, moves focus to the first row. If focus is in the first row, focus does not move. If focus is on a cell, moves focus to the first cell in the row. If focus is in the first cell of the row, focus does not move. +- <kbd>End</kbd> <kbd>Control + End</kbd></td><td> + - : If focus is on a row, moves focus to the last row. If focus is in the last row, focus does not move. If focus is on a cell, moves focus to the last cell in the row. If focus is in the last cell of the row, focus does not move. If not all rows are present in the DOM, this can be used to focus on the last row present in the DOM, or on the last row available if the entire database were present in the DOM. + +If a treegrid supports selection of cells, rows, or columns, the following keys are commonly used for these functions. + +- <kbd>Control + Space</kbd> + - : If focus is on a row, selects all cells. If focus is on a cell, selects the column that contains the focus. +- <kbd>Shift + Space</kbd> + - : If focus is on a row, select the row. If focus is on a cell, select the row that contains the focus. If the treegrid includes a column with checkboxes for selecting rows, this key can also be used as a shortcut for checking the box when focus is not on the checkbox. +- <kbd>Control + A</kbd> + - : Selects all cells. +- <kbd>Shift + Right Arrow</kbd> + - : if focus is on a cell, extends selection one cell to the right. +- <kbd>Shift + Left Arrow</kbd> + - : if focus is on a cell, extends selection one cell to the left. +- <kbd>Shift + Down Arrow</kbd> + - : If focus is on a row, extends selection to all the cells in the next row. If focus is on a cell, extends selection one cell down. +- <kbd>Shift + Up Arrow</kbd> + - : If focus is on a row, extends selection to all the cells in the previous row. If focus is on a cell, extends selection one cell up. + +If navigation functions can dynamically add more rows or columns to the DOM, key events that move focus to the beginning or end of the grid, such as <kbd>control + End</kbd>, may move focus to the last row in the DOM rather than the last available row in the back-end data. + +While navigation keys, such as arrow keys, are moving focus from cell to cell, they are not available to do something like operate a combobox or move an editing caret inside of a cell. If this functionality is needed, see [Editing and Navigating Inside a Cell](https://www.w3.org/WAI/ARIA/apg/patterns/grid/#gridNav_inside). + +<!-- +### Required JavaScript features + +## Examples +--> + +## Accessibility concerns + +It is important for all cells to be able to receive or contain keyboard focus because screen readers are generally in application reading mode, rather than their document reading mode, when users are interacting with the grid. While in application mode, a screen reader user hears only focusable elements and content that labels focusable elements. If content can't receive focus, screen reader users may unknowingly overlook elements contained in the treegrid. + +<!-- +## Best Practices + +### Prefer HTML +--> + +## Specifications + +{{Specifications}} diff --git a/files/en-us/web/accessibility/aria/reference/roles/treeitem_role/index.md b/files/en-us/web/accessibility/aria/reference/roles/treeitem_role/index.md new file mode 100644 index 000000000000000..222fa9be6c6d69e --- /dev/null +++ b/files/en-us/web/accessibility/aria/reference/roles/treeitem_role/index.md @@ -0,0 +1,236 @@ +--- +title: "ARIA: treeitem role" +short-title: treeitem +slug: Web/Accessibility/ARIA/Reference/Roles/treeitem_role +page-type: aria-role +spec-urls: + - https://w3c.github.io/aria/#treeitem + - https://www.w3.org/WAI/ARIA/apg/patterns/treeview/examples/treeview-navigation/ +sidebar: accessibilitysidebar +--- + +A `treeitem` is an item in a `tree`. + +## Description + +A [`tree`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/tree_role) is a hierarchical list with parent and child nodes that can expand and collapse. A `treeitem` is a node in a `tree`. The root of the tree is `tree`, but all tree nodes are `treeitem` elements, even if they themselves have nested `treeitem` nodes. + +An example of a `tree` is a file system selection user interface: a tree view displaying folders and files. Each folder and file is a `treeitem`. Folder items, which are `treeitem` elements, can be expanded to reveal the contents of the folder—which may be files, folders, or both, and are all `treeitems`—and collapsed, hiding its contents. + +In a tree hierarchy, the _root node_ has the role `tree`. All other nodes, other than the root node, have the role of `treeitem`, whether or not they have children. A `treeitem` that is a parent is a **parent node**. A `treeitem` that is not a parent is an _end node_. + +Tree items that have children can be expanded or collapsed, showing and hiding their children. A parent node that is expanded so its child nodes are visible is an **open node**. A parent node that is collapsed so the child nodes are not visible is a **closed node**. + +Each parent node contains or owns an element with role [`group`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/group_role). A parent node is an expandable collection of `treeitem` elements. These child nodes are not direct descendants of the parent node: rather, they should be enclosed in an element with the `group` role. + +Each parent node should include the [`aria-expanded`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-expanded) attribute. It is set to `false` when closed `true` when open. End nodes should not have the `aria-expanded` attribute included as the presence of the attribute indicates to assistive technologies that the node is a parent. + +> [!NOTE] +> ARIA tree views use navigation more similar to native applications than to web applications and are navigated primarily with arrow keys on the keyboard instead of the <kbd>Tab</kbd>. This form of navigation is not common for most browser content, though normal and expected for native applications. For this reason, consider alternative options to address the functionality you need before creating a tree view. + +Any element with a `treeitem` role must be nested in, or owned by, an element with role `tree`. Tree items can be a child of `tree`, `treeitem`, or an element with role `group` that is contained in, or owned by, an element with role `tree` or `treeitem`. If a `treeitem` is not nested within a `tree`, or nested in a `group` that is owned by a `tree`, include the [`id`](/en-US/docs/Web/HTML/Reference/Global_attributes/id) of the `treeitem` in the [`aria-owns`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-owns) attribute value on the owning `tree`, `treeitem` or `group` element. + +Trees can be "single-select", allowing users to choose just one `treeitem` for an action, or "multi-select", where users are able to select more than one `treeitem` nodes for an action. In both cases, to be keyboard accessible, focus must be managed for all tree descendants. + +In single-select trees, only one treeitem can have [`aria-selected`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-selected) (or [`aria-checked`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-checked)) set to `true`. When a single-select tree receives focus, if no `treeitem` is selected before the tree receives focus, focus is set on the first `treeitem`. If a `treeitem` is selected before the tree receives focus, focus is set on the single `treeitem` that has `aria-selected="true"` set. + +All nodes that are selectable but not selected have either `aria-selected` or `aria-checked` set to `false`. If the tree contains nodes that are not selectable, do not include either `aria-selected` or `aria-checked`, as the presence of either attribute indicates to assistive technologies the node is selectable. + +No more than one node can be selected at a time unless the `tree` node has [`aria-multiselectable="true"`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-multiselectable) set. + +When a multi-select tree receives focus, if none of the tree items are selected before the tree receives focus, focus is set on the first `treeitem`. If one or more tree items are selected before the tree receives focus, focus is set on the first selected `treeitem`. + +In multi-select trees, all selected tree items have either `aria-selected="true"` (or `aria-checked="true"`) set. All tree item nodes that are selectable but not currently selected should have `aria-selected="false"` (or `aria-checked="false"`) set. + +Either `aria-selected` or `aria-checked` can be used to indicate selection for `treeitem` elements. Some user interfaces indicate selection with `aria-selected` in single-select trees and with `aria-checked` in multi-select trees. + +Using both `aria-selected` and `aria-checked` in the same `tree` is strongly discouraged. Don't use both `aria-selected` and `aria-checked` on treeitems in a single tree unless the meaning and purpose of `aria-selected` is different from the meaning and purpose of `aria-checked`, the meaning and purpose of each state apparent, and the user interface provides a separate method for controlling each state. + +In multi-select trees, the selected state should be independent of the focus. For example, in a typical file system navigator, the user can move focus to select any number of files for an action, such as copy or move. The visual design should make it clear which items are selected and which item has focus. + +If the complete set of available treeitems is not present in the DOM due to dynamic loading as the user moves focus in or scrolls the tree, each `treeitem` should have [`aria-level`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-level), [`aria-setsize`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-setsize), and [`aria-posinset`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-posinset) specified. + +A `treeitem` is required to have an accessible name. Generally, that name comes from the `treeitem`'s contents. The accessible name can also be set via [`aria-label`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-label) or [`aria-labelledby`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-labelledby). + +### Associated WAI-ARIA roles, states, and properties + +- [`tree`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/tree_role) role + - : The root node for the hierarchical list of parent and child `treeitem` nodes that can expand and collapse +- [`group`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/group_role) role + - : Identifies a set of `treeitem` child nodes. +- [`aria-expanded`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-expanded) + - : Set on the root `tree` and on `group` nodes that are parents of `treeitem` nodes, to indicate whether the tree view is expanded (`true`) or collapsed (`false`). +- [`aria-selected`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-selected) + - : Set to `true` or `false`, indicates a `treeitem` is selectable, and whether or not it is currently selected. +- [`aria-checked`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-checked) + - : Set to `true` or `false`, indicates the `treeitem` can be checked, and whether or not it is currently checked. + +### Keyboard interactions + +For a vertically oriented `tree`, which is the default orientation: + +<table> +<tr> +<td><kbd>Right arrow</kbd></td> +<td> +<ul> +<li>When focus is on a closed node, opens the node; focus does not move. +<li>When focus is on an open node, moves focus to the first child node. +<li>When focus is on an end node (a tree item with no children), does nothing. +</td> +</tr> +<tr> +<td><kbd>Left arrow</kbd></td> +<td> +<ul> +<li>When focus is on an open node, closes the node. +<li>When focus is on a child node that is also either an end node or a closed node, moves focus to its parent node. +<li>When focus is on a closed tree, does nothing. +</td> +</tr> +<tr> +<td><kbd>Down Arrow</kbd></td> +<td> Moves focus to the next node that is focusable without opening or closing a node. +</td> +</tr> +<tr> +<td><kbd>Up Arrow</kbd></td> +<td> Moves focus to the previous node that is focusable without opening or closing a node. +</td> +</tr> +<tr> +<td><kbd>Home</kbd></td> +<td> Moves focus to the first node in the tree without opening or closing a node. +</td> +</tr> +<tr> +<td><kbd>End</kbd></td> +<td> Moves focus to the last node in the tree that is focusable without opening the node. +</td> +</tr> +<tr> +<td><kbd>Enter</kbd></td> +<td>Performs the default action of the currently focused node. For parent nodes, it opens or closes the node. In single-select trees, if the node has no children, selects the current node if not already selected (which is the default action). +</td> +</tr> +<tr> +<td>Type a character*</td> +<td> +<ul> +<li>Focus moves to the next node with a name that starts with the typed character. +<li>If multiple characters are typed in rapid succession, focus moves to the next node with a name that starts with the string of characters typed. +</td> +</tr> +<tr> +<td> +<kbd>*</kbd> (Optional)</td> +<td> Expands all siblings that are at the same level as the current node. +</td> +</tr> +</table> + +\* Type-ahead is recommended for all trees, especially for trees with more than 7 root nodes + +### Multi-select keyboard interactions + +There are two interaction models for multi-select trees: While you can require that users press a modifier key, such as <kbd>Shift</kbd> or <kbd>Control</kbd> while navigating the list in order to avoid losing selection states, the model that does not require the user to hold a modifier key is recommended. + +#### Recommended multi user select model + +<table> +<tr> +<td><kbd>Space</kbd></td> +<td> Toggles the selection state of the focused node. +</td> +</tr> +<tr> +<td><kbd>Shift + Down Arrow</kbd> (Optional)</td> +<td> Moves focus to and toggles the selection state of the next node. +</td> +</tr> +<tr> +<td><kbd>Shift + Up Arrow</kbd> (Optional)</td> +<td> Moves focus to and toggles the selection state of the previous node. +</td> +</tr> +<tr> +<td><kbd>Shift + Space</kbd> (Optional)</td> +<td> Selects contiguous nodes from the most recently selected node to the current node. +</td> +</tr> +<tr> +<td><kbd>Control + Shift + Home</kbd> (Optional)</td> +<td> Selects the node with focus and all nodes up to the first node. Optionally, moves focus to the first node. +</td> +</tr> +<tr> +<td><kbd>Control + Shift + End</kbd> (Optional)</td> +<td> Selects the node with focus and all nodes down to the last node. Optionally, moves focus to the last node. +</td> +</tr> +<tr> +<td><kbd>Control + A</kbd> (Optional)</td> +<td> Selects all nodes in the tree. Optionally, if all nodes are selected, it can also unselect all nodes.</td> +</tr> +</table> + +## Examples + +The following is how one might mark up a directory listing of web development courses as a tree view: + +```html +<div> + <h3 id="treeLabel">Developer Learning Path</h3> + <ul role="tree" aria-labelledby="treeLabel"> + <li role="treeitem" aria-expanded="true"> + <span>Web</span> + <ul role="group"> + <li role="treeitem" aria-expanded="false"> + <span>Languages</span> + <ul role="group"> + <li role="treeitem" aria-expanded="false"> + <span>HTML</span> + <ul role="group"> + <li role="treeitem">Document structure</li> + <li role="treeitem">Head elements</li> + <li role="treeitem">Semantic elements</li> + <li role="treeitem">Attributes</li> + <li role="treeitem">Web forms</li> + </ul> + </li> + <li role="treeitem">CSS</li> + <li role="treeitem">JavaScript</li> + </ul> + </li> + <li role="treeitem" aria-expanded="false"> + <span>Accessibility</span> + <ul role="group"> + <li role="treeitem" aria-label="accessibility object model">AOM</li> + <li role="treeitem">WCAG</li> + <li role="treeitem">ARIA</li> + </ul> + </li> + <li role="treeitem" aria-expanded="false"> + <span>Web Performance</span> + <ul role="group"> + <li role="treeitem">Load time</li> + </ul> + </li> + <li role="treeitem">APIs</li> + </ul> + </li> + </ul> +</div> +``` + +The above provides the semantics for a tree view, but does not provide any of the interactivity. That must be added in with JavaScript. + +If the tree items aren't by default focusable, JavaScript can be used [`tabIndex="-1"`](/en-US/docs/Web/HTML/Reference/Global_attributes/tabindex) to all the treeitems except the one that should receive focus when the user tabs into the tree which should be set to `tabIndex="0"`. + +All the keyboard functionality in Keyboard interactions and all pointer events need to be programmed, including focus management, going up and down the tree, expanding and collapsing parent nodes, and selection management. + +If the tree has more than 7 tree items, including type ahead functionality is recommended. + +## Specifications + +{{Specifications}} diff --git a/files/en-us/web/accessibility/aria/reference/roles/widget_role/index.md b/files/en-us/web/accessibility/aria/reference/roles/widget_role/index.md new file mode 100644 index 000000000000000..c365a6d080f38f4 --- /dev/null +++ b/files/en-us/web/accessibility/aria/reference/roles/widget_role/index.md @@ -0,0 +1,38 @@ +--- +title: "ARIA: widget role" +short-title: widget +slug: Web/Accessibility/ARIA/Reference/Roles/widget_role +page-type: aria-role +spec-urls: https://w3c.github.io/aria/#widget +sidebar: accessibilitysidebar +--- + +The **`widget`** role, an [abstract role](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles#6._abstract_roles), is an interactive component of a graphical user interface (GUI). + +> [!WARNING] +> The `widget` role is an abstract role used for the ontology. It is included here for completeness of documentation. It should not be used by web authors. + +## Description + +The abstract `widget` role is a superclass role for some interactive GUI elements and grouping roles. `role="widget"` should not be confused with widgets roles, such as `option`, `menuitem`, and `searchbox`. + +The `widget` role is a superclass role several abstract interactive GUI roles, including [`command`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/command_role), [`composite`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/composite_role), [`input`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/input_role), [`range`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/range_role), and [`separator`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/separator_role) (if focusable), which should not be used by web authors. + +The abstract `widget` role is also a superclass role for some grouping roles which can be used by web authors, including [`gridcell`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/gridcell_role), [`row`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/row_role), [`separator`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/separator_role) (when not focusable), and [`tab`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/tab_role), which can and should be used when appropriate. When the user navigates to one of these non-abstract roles of widget, keyboard events can switch to an application browsing mode, and pass keyboard events through to the browser. + +## Specifications + +{{Specifications}} + +## See also + +- [ARIA: `roletype` role](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/roletype_role) + +- [ARIA: `command` role](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/command_role) +- [ARIA: `composite` role](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/composite_role) +- [ARIA: `gridcell` role](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/gridcell_role) +- [ARIA: `input` role](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/input_role) +- [ARIA: `range` role](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/range_role) +- [ARIA: `row` role](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/row_role) +- [ARIA: `separator` role](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/separator_role) +- [ARIA: `tab` role](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/tab_role) diff --git a/files/en-us/web/accessibility/aria/reference/roles/window_role/index.md b/files/en-us/web/accessibility/aria/reference/roles/window_role/index.md new file mode 100644 index 000000000000000..daf455e75328a16 --- /dev/null +++ b/files/en-us/web/accessibility/aria/reference/roles/window_role/index.md @@ -0,0 +1,26 @@ +--- +title: "ARIA: window role" +short-title: window +slug: Web/Accessibility/ARIA/Reference/Roles/window_role +page-type: aria-role +spec-urls: https://w3c.github.io/aria/#window +sidebar: accessibilitysidebar +--- + +The `window` role defines a browser or app window. + +> [!WARNING] +> The `window` role is an abstract role. It is included here for completeness of documentation. It should not be used by web authors. + +## Description + +The `window` role, an abstract role, is a superclass for roles defining a browser or app window. The sub-class roles, currently only the [`dialog`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/dialog_role) role, have a window-like <abbr>GUI</abbr>, or graphical user interface, whether it's a full native window or just a section of a document styled to look like a window, where `role="dialog"` would be appropriate. + +## Specifications + +{{Specifications}} + +## See also + +- [ARIA: `roletype` role](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/roletype_role) +- [ARIA: `dialog` role](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/dialog_role) diff --git a/files/en-us/web/accessibility/aria/roles/alert_role/index.md b/files/en-us/web/accessibility/aria/roles/alert_role/index.md deleted file mode 100644 index 4c5672c5cc55fb0..000000000000000 --- a/files/en-us/web/accessibility/aria/roles/alert_role/index.md +++ /dev/null @@ -1,127 +0,0 @@ ---- -title: "ARIA: alert role" -slug: Web/Accessibility/ARIA/Roles/alert_role -page-type: aria-role -spec-urls: - - https://w3c.github.io/aria/#alert - - https://www.w3.org/TR/wai-aria-1.2/#alert ---- - -{{AccessibilitySidebar}} - -The `alert` role is for important, and usually time-sensitive, information. The `alert` is a type of [`status`](/en-US/docs/Web/Accessibility/ARIA/Roles/status_role) processed as an atomic live region. - -## Description - -The `alert` role is used to communicate an important and usually time-sensitive message to the user. When this role is added to an element, the browser will send out an accessible alert event to assistive technology products which can then notify the user. - -The alert role should only be used for information that requires the user's immediate attention, for example: - -- An invalid value was entered into a form field -- The user's login session is about to expire -- The connection to the server was lost so local changes will not be saved - -The `alert` role should only be used for text content, not interactive elements such as links or buttons. The element with the `alert` role does not have to be able to receive focus, as screen readers (speech or braille) will automatically announce the updated content regardless of where keyboard focus when the role is added. - -The `alert` role is added to the node containing an alert message, **not** the element causing the alert to be triggered. Alerts are [assertive live regions](/en-US/docs/Web/Accessibility/ARIA/ARIA_Live_Regions). Setting `role="alert"` is equivalent to setting [`aria-live="assertive"`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-live) and [`aria-atomic="true"`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-atomic). As they don't receive focus, focus does not need to be managed and no user interaction should be required. - -> [!WARNING] -> Because of its intrusive nature, the `alert` role must be used sparingly and only in situations where the user's immediate attention is required. - -The [`alert`](https://www.w3.org/TR/wai-aria-1.1/#alert) role is of the five [live region](/en-US/docs/Web/Accessibility/ARIA/ARIA_Live_Regions) roles. Dynamic changes that are less urgent should use a less aggressive method, such as including `aria-live="polite"` or using an other live region role like [`status`](/en-US/docs/Web/Accessibility/ARIA/Roles/status_role). If the user is expected to close the alert, then the [`alertdialog`](/en-US/docs/Web/Accessibility/ARIA/Roles/alertdialog_role) role should be used instead. - -The most important thing to know about the `alert` role is that it's for content that is dynamically displayed, not for content that appears on page load. It is perfect for situations such as when a user fills out a form and JavaScript is used to add an error message - the alert would immediately read out the message. It should not be used on HTML that the user hasn't interacted with. For example, if a page loads with multiple visible alerts scattered throughout, the alert role should not be used, as the messages were not dynamically triggered. - -As with all other [live regions](/en-US/docs/Web/Accessibility/ARIA/ARIA_Live_Regions), alerts will only be announced when the content of the element with `role="alert"` is _updated_. Make sure that the element with the role is present in the page's markup first - this will "prime" the browser and screen reader to keep watching the element for changes. After this, any changes to the content will be announced. Do not try to dynamically add/generate an element with `role="alert"` that is already populated with the alert message you want announced - this generally does _not_ lead to an announcement, as it is not a content change. - -As the `alert` role reads out any content that has changed, it should be used with caution. Alerts, by definition, are disruptive. Several alerts at once, and unnecessary alerts, create bad user experiences. - -## Examples - -The following are common examples of alerts and how to implement them: - -### Example 1: Making ready-made content inside an element with an alert role visible - -If the content _inside_ the element with `role="alert"` is initially hidden using CSS, making it visible will cause the alert to fire. This means that an existing alert container element can be "reused" multiple times. - -```css -.hidden { - display: none; -} -``` - -```html -<div id="expirationWarning" role="alert"> - <span class="hidden">Your log in session will expire in 2 minutes</span> -</div> -``` - -```js -// removing the 'hidden' class makes the content inside the element visible, which will make the screen reader announce the alert: -document - .getElementById("expirationWarning") - .firstChild.classList.remove("hidden"); -``` - -### Example 2: Dynamically changing the content inside an element with an alert role - -Using JavaScript, you can dynamically change the content _inside_ the element with `role="alert"`. Note that if you need to fire the same alert multiple times (i.e. the content you're dynamically inserting is the same as before), this generally won't be seen as a change and will _not_ lead to an announcement. For this reason, it's usually best to briefly "clear" the contents of the alert container before then injecting the alert message. - -```html -<div id="alertContainer" role="alert"></div> -``` - -```js -// clear the contents of the container -document.getElementById("alertContainer").textContent = ""; -// inject the new alert message -document.getElementById("alertContainer").textContent = - "Your session will expire in " + expiration + " minutes"; -``` - -### Example 3: Visually hidden alert container for screen reader notifications - -It's possible to visually hide the alert container itself, and use it to provide updates/notifications explicitly for screen readers. This can be useful in situations where important content on the page has been updated, but where the change would not be immediately obvious to a screen-reader user. - -However, make sure that the container is not hidden using `display:none`, as this will hide it even from assistive technologies, meaning that they won't be notified of any changes. Instead, use something like the [`.visually-hidden` styles](https://www.a11yproject.com/posts/how-to-hide-content/). - -```html -<div id="hiddenAlertContainer" role="alert" class="visually-hidden"></div> -``` - -```css -.visually-hidden { - clip: rect(0 0 0 0); - clip-path: inset(50%); - height: 1px; - overflow: hidden; - position: absolute; - white-space: nowrap; - width: 1px; -} -``` - -```js -// clear the contents of the container -document.getElementById("hiddenAlertContainer").textContent = ""; -// inject the new alert message -document.getElementById("hiddenAlertContainer").textContent = - "All items were removed from your inventory."; -``` - -## Specifications - -{{Specifications}} - -## See also - -- [`aria-live`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-live) -- [`aria-atomic`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-atomic) -- [ARIA: `log` role](/en-US/docs/Web/Accessibility/ARIA/Roles/log_role) -- [ARIA: `marquee` role](/en-US/docs/Web/Accessibility/ARIA/Roles/marquee_role) -- [ARIA: `status` role](/en-US/docs/Web/Accessibility/ARIA/Roles/status_role) -- [ARIA: `timer` role](/en-US/docs/Web/Accessibility/ARIA/Roles/timer_role) -- [ARIA: `alertdialog` role](/en-US/docs/Web/Accessibility/ARIA/Roles/alertdialog_role) -- [ARIA: live regions](/en-US/docs/Web/Accessibility/ARIA/ARIA_Live_Regions) -- [ARIA alert support - The Paciello Group](https://www.tpgi.com/aria-alert-support/) -- [ARIA Practices alert example](https://www.w3.org/WAI/ARIA/apg/patterns/alert/examples/alert/) diff --git a/files/en-us/web/accessibility/aria/roles/alertdialog_role/index.md b/files/en-us/web/accessibility/aria/roles/alertdialog_role/index.md deleted file mode 100644 index 212c3488a535f2e..000000000000000 --- a/files/en-us/web/accessibility/aria/roles/alertdialog_role/index.md +++ /dev/null @@ -1,108 +0,0 @@ ---- -title: "ARIA: alertdialog role" -slug: Web/Accessibility/ARIA/Roles/alertdialog_role -page-type: aria-role -spec-urls: - - https://w3c.github.io/aria/#alertdialog - - https://www.w3.org/TR/wai-aria-1.2/#alertdialog ---- - -{{AccessibilitySidebar}} - -The **alertdialog** role is to be used on modal alert dialogs that interrupt a user's workflow to communicate an important message and require a response. - -## Description - -The `alertdialog` role is used to notify users of urgent information that demands the user's immediate attention. Including `role="alertdialog"` on the element containing the dialog helps assistive technology identify the content as being grouped and separated from the rest of the page content. Examples include error messages that require confirmation and other action confirmation prompts. - -As the name implies, `alertdialog` is a mashup of the [`dialog`](/en-US/docs/Web/Accessibility/ARIA/Roles/dialog_role) and [`alert`](/en-US/docs/Web/Accessibility/ARIA/Roles/alert_role) roles. `alertdialog` is a type of `dialog` with similar use cases as `alert`, but for when a user response is required. - -> [!NOTE] -> The `alertdialog` role should only be used for alert messages that have associated interactive controls. If an alert dialog only contains static content and has no interactive controls at all, use [`alert`](/en-US/docs/Web/Accessibility/ARIA/Roles/alert_role) instead. - -Being a type of dialog, the [`dialog`](/en-US/docs/Web/Accessibility/ARIA/Roles/dialog_role) role's states, properties, and keyboard focus requirements are applicable to the `alertdialog` role as well. - -Because of its urgent nature, interrupting the user's workflow, alert dialogs should be [modal](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-modal). - -The alert dialog must have at least one focusable control — such as Confirm, Close, and Cancel — and focus must be moved to that control when the alert dialog appears. Alert dialogs can have additional interactive controls such as text fields and checkboxes. - -The `alertdialog` role is not to be used as a replacement for other dialogs, including no-confirmation-required `alert` dialogs ([`Window.alert()`](/en-US/docs/Web/API/Window/alert)) and prompts ([`Window.prompt()`](/en-US/docs/Web/API/Window/prompt)). - -Adding `role="alertdialog"` alone is not sufficient to make an alert dialog accessible. The following also need to be done: - -- The alert dialog must be properly labeled -- Keyboard focus must be managed correctly - -The `alertdialog` must have an accessible name, defined with [`aria-labelledby`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-labelledby) or [`aria-label`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-label). The alert dialog text must have an {{glossary("accessible description")}} using [`aria-describedby`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-describedby). - -## Examples - -### Example 1: A basic alert dialog - -```html -<div - role="alertdialog" - aria-labelledby="dialog1Title" - aria-describedby="dialog1Desc"> - <div role="document" tabindex="0"> - <h2 id="dialog1Title">Your login session is about to expire</h2> - <p id="dialog1Desc">To extend your session, click the OK button</p> - <button>OK</button> - </div> -</div> -``` - -The code snippet above shows how to mark up an alert dialog that only provides a message and an OK button. - -### Example 2: Confirmation dialog with two options - -```html -<div - id="alert_dialog" - role="alertdialog" - aria-modal="true" - aria-labelledby="dialog_label" - aria-describedby="dialog_desc"> - <h2 id="dialog_label">Confirmation</h2> - <div id="dialog_desc"> - <p>Are you sure you want to delete this image?</p> - <p>This change can't be undone.</p> - </div> - <ul> - <li> - <button type="button" onclick="closeThis()">No</button> - </li> - <li> - <button - type="button" - aria-controls="form" - id="delete_file_confirm" - onclick="deleteFile()"> - Yes - </button> - </li> - </ul> -</div> -``` - -### Associated WAI-ARIA roles, states, and properties - -- [`aria-labelledby`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-labelledby) - - - : Use this attribute to label the alertdialog. The `aria-labelledby` attribute is generally the id of the element used to title the alertdialog. - -- [`aria-describedby`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-describedby) - - : Use this attribute to encompass the description of the contents of the alert dialog. The value of the `aria-describedby` attribute is generally the ID of the element containing the alert dialog's messaging, usually coming right after the title. - -## Specifications - -{{Specifications}} - -## See also - -- HTML {{HTMLElement("dialog")}} element -- [The `dialog` role](/en-US/docs/Web/Accessibility/ARIA/Roles/dialog_role) -- [The `alert` role](/en-US/docs/Web/Accessibility/ARIA/Roles/alert_role) -- [`aria-modal` attribute](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-modal) -- [`Window.alert()`](/en-US/docs/Web/API/Window/alert) -- [`Window.prompt()`](/en-US/docs/Web/API/Window/prompt) diff --git a/files/en-us/web/accessibility/aria/roles/application_role/index.md b/files/en-us/web/accessibility/aria/roles/application_role/index.md deleted file mode 100644 index 388a053b14b18f1..000000000000000 --- a/files/en-us/web/accessibility/aria/roles/application_role/index.md +++ /dev/null @@ -1,100 +0,0 @@ ---- -title: "ARIA: application role" -slug: Web/Accessibility/ARIA/Roles/application_role -page-type: aria-role -spec-urls: https://w3c.github.io/aria/#application ---- - -{{AccessibilitySidebar}} - -The `application` role indicates to assistive technologies that an element _and all of its children_ should be treated similar to a desktop application, and no traditional HTML interpretation techniques should be used. This role should only be used to define very dynamic and desktop-like web applications. Most mobile and desktop web apps _are not_ considered applications for this purpose. - -```html -<div role="application" aria-label="…">…</div> -``` - -By specifying the `application` role, it indicates this `div` element and all of its descendants are to be treated like they are part of a desktop application. - -## Description - -The `application` [document structure role](/en-US/docs/Web/Accessibility/ARIA/Roles#1._document_structure_roles), indicates to assistive technologies that this part of the web content contains elements that do not conform to any other known HTML element or WAI-ARIA widget. Any sort of special interpretation of HTML structures and widgets should be suspended, and control should be completely handed over to the browser and web application to handle mouse, keyboard, or touch interaction. - -In this mode, the web author is completely responsible for handling any and all keyboard input, focus management, and other interactions and cannot assume assistive technologies would do any processing on their end. - -If the web application encompassed by the application role contains parts that _should_ be treated like normal web content, a role of [`document`](/en-US/docs/Web/Accessibility/ARIA/Roles/document_role) or [`article`](/en-US/docs/Web/Accessibility/ARIA/Roles/article_role) should be used to contain such content. - -### Background - -For historic reasons, especially on Windows, screen readers and some other assistive technologies (AT) have traditionally grabbed the whole web content from the browser at once after it had finished loading. The ATs build their own representation of it that makes the most sense for a visually impaired user to consume the content. This is often referred to as _virtual document_, _browse mode_, or similar terms. The document is streamlined to a single-column view. A keyboard interaction model is generated that is very similar to a word processor where users can read line by line, sentence by sentence, or paragraph by paragraph. The AT will read any semantics like links, headings, form controls, tables, lists, or images. - -In addition, a set of so-called _quick navigation keys_ has been established over the years that allows visually impaired users to skim through a page via a certain element type. Such elements usually include headings, form fields, lists, tables, links, graphics, or landmark regions. - -For all of this to work, ATs intercept almost all keyboard input and consume it themselves, letting nothing through to the browser or other user agent. To be able to interact with a web page, a standard set of widgets is recognized that, when pressing a certain key (usually the <kbd>Enter</kbd> key) this mode is switched off. The screen reader mode, often called _forms mode_ or _focus mode_, lets all keyboard input go through to the browser again. <kbd>Escape</kbd> is the most common way of switching back to _browse_ mode, but when within a specific `application` section, some screen readers may require other keys to purposefully exit this mode. For instance <kbd>NUMPAD PLUS</kbd> with JAWS. - -The `application` role is designed to provide a means for widgets that are not part of the standard set to be accessible for direct interaction in ATs that use both _browse_ and _focus_ modes for interacting with web content. Most common widgets have expected keyboard interaction behaviors. Because of this, a custom keyboard experience created by a web author would create a confusing experience. - -### Associated WAI-ARIA roles, states, and properties - -- [`document`](/en-US/docs/Web/Accessibility/ARIA/Roles/document_role), [`article`](/en-US/docs/Web/Accessibility/ARIA/Roles/article_role) - - : Used to indicate parts of the application that should be treated as normal web content -- [`aria-activedescendant`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-activedescendant) - - : Used to manage focus inside the application. -- [`aria-label`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-label) - - : Used to provide the name of the application or purpose of the widget that is being exposed. -- [`aria-describedby`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-describedby) - - : Used to indicate the idref of an element that contains additional instructions for navigating or operating this element. -- [`aria-roledescription`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-roledescription) - - : Used to give the application a more descriptive role text for screen readers to speak. This should be localized. -- [`aria-disabled`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-disabled) - - : Indicates that an element is visible but disabled -- [`aria-errormessage`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-errormessage) - - : A reference to the element that provides the error message for the element on which it is set -- [`aria-expanded`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-expanded) - - : If set to `true`, the grouping element owned or controlled by this element is expanded, or `false` if collapsed. -- [`aria-haspopup`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-haspopup) - - : Indicates there is a popup, such as menu or dialog, that can be triggered by the element. - -### Keyboard interactions - -Keyboard interaction is completely under the web author's control and can be anything associated with the particular widget being implemented. In a slides application, for example, a widget could be created that uses the arrow keys to position elements on the slide, and uses audio feedback via an ARIA live region to communicate the position and overlap status with other objects. Focus is being managed via _aria-activedescendant_. - -The <kbd>Tab</kbd>, <kbd>Space</kbd> and <kbd>Enter</kbd> keys, as well as <kbd>Escape</kbd>, must be handled by the application. The one exception is if focus is set to a standard widget inside the application that supports keyboard navigation from the browser, for example an [input](/en-US/docs/Web/HTML/Element/input) element. - -### Required JavaScript features - -- keyPress - - : Used to handle keyboard input and control the focus -- Click, Touch - - : Handle as appropriate for your widget as well -- Changing attribute values - - : [`aria-activedescendant`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-activedescendant) is used to manage the focus inside the application container. Set in response to keyboard or other application events that change focus or point of interaction. - -> [!NOTE] -> The `application` role does not have a related HTML widget and thus is completely free form. The author of the application must take full responsibility for not letting users get stuck in a focus trap inside something the user cannot exit from. All aspects of interaction, including returning to the regular web content on other parts of the page, must be handled. Use wisely, and cautiously, and remember to test! - -## Examples - -Some prominent web applications that use or have used the application role properly are: - -- Google Docs, Sheets and Slides -- CKEditor and TinyMCE WYSIWYG web editors, like the one used on the Mozilla Developer Network -- Some parts of Gmail - -## Accessibility concerns - -Improperly using the `application` role can unintentionally take away access from information on a web page, so be very mindful of using it. Think hard on if you actually need it and cannot just use a set of other known widgets to accomplish the same task. - -If used, the application role should be added to the lowest common container possible, not on the `<body>` element, for example. Also be sure to test what you have written with assistive technology, to verify it works as intended. - -## Specifications - -{{Specifications}} - -## Precedence order - -Applying the `application` role will cause this and all of the descendant elements of this element to be treated like application content, not web content. Any reading mechanisms assistive technologies may have for web content will not apply. - -## See also - -- [If you use the WAI-ARIA role `application`, please do so wisely](https://www.marcozehe.de/if-you-use-the-wai-aria-role-application-please-do-so-wisely/) - blog post by Marco Zehe -- [Using the ARIA `application` role](https://tink.uk/using-the-aria-application-role/) - by Léonie Watson diff --git a/files/en-us/web/accessibility/aria/roles/article_role/index.md b/files/en-us/web/accessibility/aria/roles/article_role/index.md deleted file mode 100644 index b1afb2b0617e3d4..000000000000000 --- a/files/en-us/web/accessibility/aria/roles/article_role/index.md +++ /dev/null @@ -1,92 +0,0 @@ ---- -title: "ARIA: article role" -slug: Web/Accessibility/ARIA/Roles/article_role -page-type: aria-role -spec-urls: - - https://w3c.github.io/aria/#article - - https://www.w3.org/WAI/ARIA/apg/patterns/feed/examples/feed/ ---- - -{{AccessibilitySidebar}} - -The `article` role indicates a section of a page that could easily stand on its own on a page, in a document, or on a website. It is usually set on related content items such as comments, forum posts, newspaper articles or other items grouped together on one page. - -```html -<div role="article"> - <h2>Heading of the segment</h2> - <p>Paragraph for the segment.</p> - <p>Another paragraph.</p> - Controls to interact with the article, share it, etc. -</div> -<div role="article">…</div> -``` - -This example shows two articles side by side on one page that could be structured similarly and are related. - -> [!NOTE] -> Instead of a `<div>` with an `article` role, use the {{HTMLElement('article')}} element. **Always use native element if available** - -Don't use `role="article"`. Instead use the `<article>` element. - -```html -<article> - <h2>Heading of the segment</h2> - <p>Paragraph for the segment.</p> - <p>Another paragraph.</p> - Controls to interact with the article, share it, etc. -</article> -<article>…</article> -``` - -## Description - -The `article` [document structure role](/en-US/docs/Web/Accessibility/ARIA/Roles#1._document_structure_roles) denotes a section of a document, page, or site that, if it were standing on its own, could be viewed as a complete document, page or site. The aim of a set of article sections is to indicate their relationship to one another. - -Articles are not considered a navigational landmark, but many assistive technologies that support landmarks also support a means to navigate among articles. They may also support indication of nesting relationships within articles. - -Articles can be nested, indicating that a nested article directly relates to the one it is nested in, but not necessarily to the ones outside the nesting hierarchy. Reference the examples for specific use cases. - -If an article is part of a feed, it can have the [`aria-posinset`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-posinset) and [`aria-setsize`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-setsize) attributes set to indicate which position within the feed this particular article represents. - -Inside an `application` or other widget that causes screen readers and other assistive technologies to be in pass-through mode, an article can be used to indicate that these should switch back to treating the enclosed content as regular web content. - -Instead of including the `article` role on a non-semantic element, the {{HTMLElement('article')}} element should be used. User agents translate this to the appropriate accessibility information just like the `article` role. Using the {{HTMLElement('article')}} element also helps search engines better discover the structure of a page. Examples of appropriate uses of the `role="article"`, or preferably `<article>`, include blog posts, forum posts, a comment to a forum or blog post, any an item in a social media feed. - -### Associated WAI-ARIA roles, states, and properties - -- [`aria-posinset`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-posinset) - - : In the context of a feed, indicates the position of this particular article within that feed, based on a count starting at 1. -- [`aria-setsize`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-setsize) - - : In the context of a feed, indicates how many article items there are within that feed. - -### Keyboard interactions - -This role does not support any specific keyboard interaction. - -### Required JavaScript features - -- Event handlers - - : This role does not require any event handlers to be present. -- Changing attribute values - - : When constructing a feed, set the `aria-posinset` and `aria-setsize` attributes on each article role to the appropriate values, bearing in mind that `aria-posinset` is 1-based. - -> **Note:** **Always use native element if available.** Instead of a `<div>` with the `article` role, the `<article>` element should be used. - -## Examples - -- The [restaurant recommendations feed display](https://www.w3.org/WAI/ARIA/apg/patterns/feed/examples/feed-display.html) along with its separate [documentation](https://www.w3.org/WAI/ARIA/apg/patterns/feed/examples/feed/) from the WAI-ARIA 1.1 authoring practices feed design pattern - -## Specifications - -{{Specifications}} - -## Precedence order - -This role corresponds to the {{HTMLElement('article')}} element in HTML, and that element should be used instead, if possible. This role does not require any specific roles to be present among its children. It is the only role allowed as a direct child of an element with the [`feed`](/en-US/docs/Web/Accessibility/ARIA/Roles/feed_role) role. - -## See also - -- [`feed` role](/en-US/docs/Web/Accessibility/ARIA/Roles/feed_role) -- [`section` role](/en-US/docs/Web/Accessibility/ARIA/Roles/section_role) -- The {{HTMLElement('article')}} element -- {{Glossary("RSS")}} glossary definition diff --git a/files/en-us/web/accessibility/aria/roles/banner_role/index.md b/files/en-us/web/accessibility/aria/roles/banner_role/index.md deleted file mode 100644 index f1bebcd92c1b279..000000000000000 --- a/files/en-us/web/accessibility/aria/roles/banner_role/index.md +++ /dev/null @@ -1,75 +0,0 @@ ---- -title: "ARIA: banner role" -slug: Web/Accessibility/ARIA/Roles/banner_role -page-type: aria-role -spec-urls: - - https://w3c.github.io/aria/#banner - - https://www.w3.org/WAI/ARIA/apg/patterns/landmarks/examples/banner.html ---- - -{{AccessibilitySidebar}} - -The `banner` role is for defining a global site header, which usually includes a logo, company name, search feature, and possibly the global navigation or a slogan. It is generally located at the top of the page. - -By default, the HTML's {{htmlelement("header")}} element has an identical meaning to the `banner` landmark, unless it is a descendant of {{htmlelement("aside")}}, {{htmlelement("article")}}, {{htmlelement("main")}}, {{htmlelement("nav")}}, or {{htmlelement("section")}}, at which point {{htmlelement("header")}} exposes a [`generic`](/en-US/docs/Web/Accessibility/ARIA/Roles/generic_role) role, and not the equivalent of the site-wide banner. - -## Description - -A `banner` landmark role overwrites the implicit ARIA role of the container element upon which it is applied. It should be reserved for globally repeating site-wide content that is generally located at the top of every page. - -The banner typically includes things such as a logo or corporate identity, or possibly a site-specific search tool, and is generally what your marketing team would call the "header" or "top banner" of the site. If the [`header` element](/en-US/docs/Web/HTML/Element/header) technique is not being used for that banner, a declaration of `role="banner"` should be used to define a banner landmark to assistive technologies. - -Assistive technologies can identify the `header` element of a page as the `banner` if it is a descendant of the [`body` element](/en-US/docs/Web/HTML/Element/body), and not nested within an `article`, `aside`, `main`, `nav` or `section` subsection. - -Each page may have a `banner` landmark, but each page should generally be limited to a single element with the role of banner. In the case of a page containing nested `document` and/or `application` roles, each nested `document` or `application` role may also have one `banner` landmark. If a page includes more than one `banner` landmark, each should have a unique accessible name. - -### Associated ARIA roles, states, and properties - -None - -### Keyboard interactions - -None - -### Required JavaScript features - -None - -## Examples - -Here's a fake simple banner with a skip to navigation link, a logo, a title and a subtitle. As this is the main header for the site, we've added the `banner` landmark role to the container element. - -```html -<div role="banner"> - <a href="#main" id="skipToMain" class="skiptocontent">Skip To main content</a> - <img src="images/w3c.png" alt="W3C Logo" /> - <h1>ARIA Landmarks</h1> - <p>Identifying page subsections for easy navigation</p> - <nav>…</nav> -</div> -``` - -We could also have written the above with the HTML `header` element: - -```html -<header> - <a href="#main" id="skipToMain" class="skiptocontent">Skip To main content</a> - <img src="images/w3c.png" alt="W3C Logo" /> - <h1>ARIA Landmarks</h1> - <p>Identifying page subsections for easy navigation</p> - <nav>…</nav> -</header> -``` - -## Best practices - -While it is best to use the `header` element and ensure it is not a descendant of any subsection of the page, sometimes you don't have access to the underlying HTML. If this is the case, you can add the role of `banner` to the element of the page which should be exposed as a `banner` with JavaScript. Identifying the page's banner in this way will help improve the site's accessibility. - -## Specifications - -{{Specifications}} - -## See also - -- [HTML `header` element](/en-US/docs/Web/HTML/Element/header) -- [WC3 Landmarks Example](https://www.w3.org/WAI/ARIA/apg/patterns/landmarks/examples/banner.html) diff --git a/files/en-us/web/accessibility/aria/roles/button_role/index.md b/files/en-us/web/accessibility/aria/roles/button_role/index.md deleted file mode 100644 index 44e817bbc89065d..000000000000000 --- a/files/en-us/web/accessibility/aria/roles/button_role/index.md +++ /dev/null @@ -1,299 +0,0 @@ ---- -title: "ARIA: button role" -slug: Web/Accessibility/ARIA/Roles/button_role -page-type: aria-role -spec-urls: - - https://w3c.github.io/aria/#button - - https://www.w3.org/WAI/ARIA/apg/patterns/button/examples/button/ ---- - -{{AccessibilitySidebar}} - -The `button` role is for clickable elements that trigger a response when activated by the user. Adding `role="button"` tells the screen reader the element is a button, but provides no button functionality. Use {{HTMLElement("button")}} or {{HTMLElement("input")}} with `type="button"` instead. - -## Description - -The button role identifies an element as a button to assistive technology such as screen readers. A button is a widget used to perform actions such as submitting a form, opening a dialog, canceling an action, or performing a command such as inserting a new record or displaying information. Adding `role="button"` tells assistive technology that the element is a button but provides no button functionality. Use {{HTMLElement("button")}} or {{HTMLElement("input")}} with `type="button"` instead. - -This `button` role can be used in combination with the [`aria-pressed`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-pressed) attribute to [create toggle buttons](#toggle_buttons). - -```html -<div id="saveChanges" tabindex="0" role="button" aria-pressed="false">Save</div> -``` - -The above example creates a focusable button, but requires JavaScript and CSS to include button appearance and functionality. These are features provided by default when using the {{HTMLElement("button")}} and {{HTMLElement("input")}} with `type="button"` elements: - -```html -<button type="button" id="saveChanges">Save</button> -``` - -> [!NOTE] -> If using `role="button"` instead of the semantic `<button>` or `<input type="button">` elements, you will need to make the element focusable and define event handlers for {{domxref("Element/click_event", "click")}} and {{domxref("Element/keydown_event", "keydown")}} events. This includes handling the <kbd>Enter</kbd> and <kbd>Space</kbd> keypresses in order to process all forms of user input. See [the official WAI-ARIA example code](https://www.w3.org/WAI/ARIA/apg/patterns/button/examples/button/). - -In addition to the ordinary button widget, `role="button"` should be included when creating a toggle button or menu button using a non-button element. - -A toggle button is a two-state button that can be either off (not pressed) or on (pressed). The [`aria-pressed`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-pressed) attribute values of `true` or `false` identify a button as a toggle button. - -A menu button is a button that controls a menu and has an [`aria-haspopup`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-haspopup) property attribute set to either `menu` or `true`. - -### All descendants are presentational - -There are some types of user interface components that, when represented in a platform accessibility API, can only contain text. Accessibility APIs do not have a way of representing semantic elements contained in a `button`. To deal with this limitation, browsers, automatically apply role [`presentation`](/en-US/docs/Web/Accessibility/ARIA/Roles/presentation_role) to all descendant elements of any `button` element as it is a role that does not support semantic children. - -For example, consider the following `button` element, which contains a heading. - -```html -<div role="button"><h3>Title of my button</h3></div> -``` - -Because descendants of `button` are presentational, the following code is equivalent: - -```html -<div role="button"><h3 role="presentation">Title of my button</h3></div> -``` - -From the assistive technology user's perspective, the heading does not exist since the previous code snippets are equivalent to the following in the [accessibility tree](/en-US/docs/Glossary/Accessibility_tree): - -```html -<div role="button">Title of my button</div> -``` - -### Associated ARIA roles, states, and properties - -- [`aria-pressed`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-pressed) - - : The `aria-pressed` attribute defines the button as a toggle button. The value describes the state of the button. The values include `aria-pressed="false"` when a button is not currently pressed, `aria-pressed="true"` to indicate a button is currently pressed, and `aria-pressed="mixed"` if the button is considered to be partially pressed. If the attribute is omitted or set to its default value of `aria-pressed="undefined"`, the element does not support being pressed. -- [`aria-expanded`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-expanded) - - : If the button controls a grouping of other elements, the `aria-expanded` state indicates whether the controlled grouping is currently expanded or collapsed. If the button has `aria-expanded="false"` set, the grouping is not currently expanded; If the button has `aria-expanded="true"` set, it is currently expanded; if the button has `aria-expanded="undefined"` set or the attribute is omitted, it is not expandable. - -### Basic buttons - -Buttons should always have an accessible name. For most buttons, this name will be the same as the text inside the button, between the opening and closing tags. In some cases, for example buttons represented by icons, the accessible name may be provided from the [`aria-label`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-label) or [`aria-labelledby`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-labelledby) attributes. - -### Toggle buttons - -A toggle button typically has two states: pressed and not pressed. A third mixed state is available for toggle buttons that control other elements, such as other toggle buttons or checkboxes, which do not all share the same value. Whether an element is a toggle button or not can be indicated with the [`aria-pressed`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-pressed) attribute in addition to the `button` role (if the element is not already a native button element): - -- If `aria-pressed` is not used, or is set to the "undefined" state, the button is not a toggle button. -- If `aria-pressed="false"` is used the button is a toggle button that is currently not pressed. -- If `aria-pressed="true"` is used the button is a toggle button that is currently pressed. -- if `aria-pressed="mixed"` is used, the button is considered to be partially pressed. - -As an example, the mute button on an audio player labeled "mute" could indicate that sound is muted by setting the `aria-pressed` state true. The label of a toggle button should not change when its state changes. In our example the label remains "Mute" with a screen reader reading "Mute toggle button pressed" or "Mute toggle button not pressed" depending on the value of `aria-pressed`. If the design were to call for the button label to change from "Mute" to "Unmute," a toggle button would not be appropriate, so the `aria-pressed` attribute would be omitted. - -### Keyboard interactions - -| Key | Function | -| ---------------- | --------------------- | -| <kbd>Enter</kbd> | Activates the button. | -| <kbd>Space</kbd> | Activates the button | - -Following button activation, focus is set depending on the type of action the button performs. For example, if clicking the button opens a dialog, the focus should move to the dialog. If the button closes a dialog, focus should return to the button that opened the dialog unless the function performed in the dialog context logically leads to a different element. If the button alters the current context, such as muting and unmuting an audio file, then focus typically remains on the button. - -### Required JavaScript Features - -#### Required event handlers - -Buttons can be operated by mouse, touch, and keyboard users. For native HTML `<button>` elements, the button's `onclick` event fires for mouse clicks and when the user presses <kbd>Space</kbd> or <kbd>Enter</kbd> while the button has focus. But if another tag is used to create a button, the `onclick` event only fires when clicked by the mouse cursor, even if `role="button"` is used. Because of this, separate key event handlers must be added to the element so that the button is be triggered when the <kbd>Space</kbd> or <kbd>Enter</kbd> key is pressed. - -- `onclick` - - : Handles the event raised when the button is activated using a mouse click or touch event. -- `onKeyDown` - - : Handles the event raised when the button is activated using the Enter or Space key on the keyboard. (Note not the [deprecated onKeyPress](/en-US/docs/Web/API/Element/keypress_event)) - -## Examples - -### Basic button example - -In this example, a span element has been given the `button` role. Because a `<span>` element is used, the `tabindex` attribute is required to make the button focusable and part of the page's tab order. The included CSS style is provided to make the `<span>` element look like a button, and to provide visual cues when the button has focus. - -The `handleBtnClick` and `handleBtnKeyDown` event handlers perform the button's action when activated using a mouse click or the <kbd>Space</kbd> or <kbd>Enter</kbd> key. In this case, the action is to add a new name to the list of names. - -Try the example by adding a name to the text box. The button will cause the name to be added to a list. - -#### HTML - -```html -<h1>ARIA Button Example</h1> -<ul id="nameList"></ul> -<label for="newName">Enter your Name: </label> -<input type="text" id="newName" /> -<span - role="button" - tabindex="0" - onclick="handleCommand(event)" - onKeyDown="handleCommand(event)" - >Add Name</span -> -``` - -#### CSS - -```css -[role="button"] { - padding: 2px; - background-color: navy; - color: white; - cursor: default; -} -[role="button"]:hover, -[role="button"]:focus, -[role="button"]:active { - background-color: white; - color: navy; -} -ul { - list-style: none; -} -``` - -#### JavaScript - -```js -function handleCommand(event) { - // Handles both mouse clicks and keyboard - // activate with Enter or Space - - // Keypresses other than Enter and Space should not trigger a command - if ( - event instanceof KeyboardEvent && - event.key !== "Enter" && - event.key !== " " - ) { - return; - } - - // Get the new name value from the input element - const newNameInput = document.getElementById("newName"); - const name = newNameInput.value; - newNameInput.value = ""; // clear the text field - newNameInput.focus(); // give the text field focus to enable entering and additional name. - - // Don't add blank entries to the list. - if (name.length > 0) { - const listItem = document.createElement("li"); - listItem.appendChild(document.createTextNode(name)); - - // Add the new name to the list. - const list = document.getElementById("nameList"); - list.appendChild(listItem); - } -} -``` - -{{EmbedLiveSample("Basic_button_example")}} - -### Toggle button example - -In this snippet a {{HTMLElement("span")}} element is converted to a toggle button using the `button` role and the `aria-pressed` attribute. When the button is activated, the `aria-pressed` value switches states; changing from `true` to `false` and back again. - -#### HTML - -```html -<button - type="button" - onclick="handleBtnClick(event)" - onKeyDown="handleBtnKeyDown(event)"> - Mute Audio -</button> - -<span - role="button" - tabindex="0" - aria-pressed="false" - onclick="handleBtnClick(event)" - onKeyDown="handleBtnKeyDown(event)"> - Mute Audio -</span> - -<audio - id="audio" - src="https://soundbible.com/mp3/Tyrannosaurus%20Rex%20Roar-SoundBible.com-807702404.mp3"> - Your browser does not support the `audio` element. -</audio> -``` - -#### CSS - -```css -button, -[role="button"] { - padding: 3px; - border: 2px solid transparent; -} - -button:active, -button:focus, -[role="button"][aria-pressed="true"] { - border: 2px solid #000; -} -``` - -#### JavaScript - -```js -function handleBtnClick(event) { - toggleButton(event.target); -} - -function handleBtnKeyDown(event) { - // Check to see if space or enter were pressed - // "Spacebar" for IE11 support - if (event.key === " " || event.key === "Enter" || event.key === "Spacebar") { - // Prevent the default action to stop scrolling when space is pressed - event.preventDefault(); - toggleButton(event.target); - } -} - -function toggleButton(element) { - const audio = document.getElementById("audio"); - - // Check to see if the button is pressed - const pressed = element.getAttribute("aria-pressed") === "true"; - - // Change aria-pressed to the opposite state - element.setAttribute("aria-pressed", !pressed); - - // Toggle the play state of the audio file - if (pressed) { - audio.pause(); - } else { - audio.play(); - } -} -``` - -#### Result - -{{EmbedLiveSample('Toggle_button_example')}} - -## Accessibility concerns - -Buttons are interactive controls and thus focusable. If the `button` role is added to an element that is not focusable by itself (such as `<span>`, `<div>` or `<p>`) then, the `tabindex` attribute has to be used to make the button focusable. - -> [!WARNING] -> Be careful when marking up links with the button role. Buttons are expected to be triggered using the <kbd>Space</kbd> or <kbd>Enter</kbd> key, while links are expected to be triggered using the <kbd>Enter</kbd> key. In other words, when links are used to behave like buttons, adding `role="button"` alone is not sufficient. It will also be necessary to add a key event handler that listens for the <kbd>Space</kbd> key in order to be consistent with native buttons. - -When the `button` role is used, screen readers announce the element as a button, generally saying "click" followed by the button's accessible name. The accessible name is either the content of the element or the value of an `aria-label` or element referenced by an `aria-labelledby` attribute, or description, if included. - -## Best practices - -If a link performs the action of a button, giving the element `role="button"` helps assistive technology users understand the function of the element. However, a better solution is to adjust the visual design so it matches the function and ARIA role. Where possible, it is recommended to use native HTML buttons (`<button>`, `<input type="button">`, `<input type="submit">`, `<input type="reset">` and `<input type="image">`) rather than the `button` role, as native HTML buttons are supported by all user agents and assistive technology and provide keyboard and focus requirements by default, without need for additional customization. - -## Specifications - -{{Specifications}} - -## See also - -- The {{HTMLElement('button')}} element -- The {{HTMLElement("input")}} element -- [`<input type="button">`](/en-US/docs/Web/HTML/Element/input/button) -- [`<input type="submit">`](/en-US/docs/Web/HTML/Element/input/submit) -- [`<input type="reset">`](/en-US/docs/Web/HTML/Element/input/reset) -- [`aria-pressed`](https://www.w3.org/TR/wai-aria-1.1/#aria-pressed) -- [`aria-expanded`](https://www.w3.org/TR/wai-aria-1.1/#aria-expanded) -- [`aria-haspopup`](https://www.w3.org/TR/wai-aria-1.1/#aria-haspopup) -- [Strong native semantics in HTML5](https://html.spec.whatwg.org/multipage/dom.html#aria-usage-note) -- [Notes on Using ARIA in HTML](https://www.w3.org/TR/aria-in-html/) -- [Official WAI-ARIA example code](https://www.w3.org/WAI/ARIA/apg/patterns/button/examples/button/) diff --git a/files/en-us/web/accessibility/aria/roles/cell_role/index.md b/files/en-us/web/accessibility/aria/roles/cell_role/index.md deleted file mode 100644 index eaa119e0b0bac9c..000000000000000 --- a/files/en-us/web/accessibility/aria/roles/cell_role/index.md +++ /dev/null @@ -1,187 +0,0 @@ ---- -title: "ARIA: cell role" -slug: Web/Accessibility/ARIA/Roles/cell_role -page-type: aria-role -spec-urls: - - https://w3c.github.io/aria/#cell - - https://www.w3.org/WAI/ARIA/apg/patterns/table/examples/table/ ---- - -{{AccessibilitySidebar}} - -The `cell` value of the ARIA _role_ attribute identifies an element as being a cell in a tabular container that does not contain column or row header information. To be supported, the cell must be nested in an element with the role of `row`. - -```html -<div role="row"> - <span role="cell">France</span> - <span role="cell">67 million</span> -</div> -``` - -A better, more semantic way of writing the cells above would be to use the semantic [`<td>`](/en-US/docs/Web/HTML/Element/td) element. - -```html -<tr role="row"> - <td role="cell">France</td> - <td role="cell">67 million</td> -</tr> -``` - -## Description - -The element with `role="cell"` is a cell within a row, optionally within a [`rowgroup`](/en-US/docs/Web/Accessibility/ARIA/Roles/rowgroup_role), within a [`table`](/en-US/docs/Web/Accessibility/ARIA/Roles/table_role). If the cell is in a [`grid`](/en-US/docs/Web/Accessibility/ARIA/Roles/grid_role) or [`treegrid`](/en-US/docs/Web/Accessibility/ARIA/Roles/treegrid_role), opt for [`gridcell`](/en-US/docs/Web/Accessibility/ARIA/Roles/gridcell_role). Using native HTML {{HTMLElement('td')}} elements, whenever possible, is strongly encouraged. - -Each element with `role="cell"` MUST be nested in a container element with [`role="row"`](/en-US/docs/Web/Accessibility/ARIA/Roles/row_role). That row, in turn, can be nested within an element with [`role="rowgroup"`](/en-US/docs/Web/Accessibility/ARIA/Roles/rowgroup_role), and should be nested within a `grid`, `table` or `treegrid`. If a cell contains column or row header information, use the `columnheader` or `rowheader` roles, respectively. If the cell does not contain header information and is nested in a `grid` or `treegrid`, the role of `gridcell` may be more appropriate. - -A cell can contain a number of property attributes clarifying the cell's position within the tabular data structure, including [`aria-colindex`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-colindex), [`aria-colspan`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-colspan), [`aria-rowindex`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-rowindex), and [`aria-rowspan`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-rowspan). - -> [!NOTE] -> Using the native HTML table element ({{HTMLElement('table')}}) element, along with the table row element ({{HTMLElement('tr')}}), and table cell element ({{HTMLElement('td')}}), whenever possible, is strongly encouraged. - -### Associated WAI-ARIA roles, states, and properties - -#### Context roles - -- [role="row"](/en-US/docs/Web/Accessibility/ARIA/Roles/row_role) - - : An element with `role="row"` is a row of cells within a tabular structure. A row contains one or more cells, grid cells, column headers, or row headers within a [`grid`](/en-US/docs/Web/Accessibility/ARIA/Roles/grid_role), [`table`](/en-US/docs/Web/Accessibility/ARIA/Roles/table_role) or `treegrid`, and optionally within a [`rowgroup`](/en-US/docs/Web/Accessibility/ARIA/Roles/rowgroup_role). -- [role="rowgroup"](/en-US/docs/Web/Accessibility/ARIA/Roles/rowgroup_role) - - : `Row` is a required cell parent. `Rowgroup` is an optional contextual row parent. It establishes a relationship between descendant rows. It is a structural equivalent to the [`thead`](/en-US/docs/Web/HTML/Element/thead), [`tfoot`](/en-US/docs/Web/HTML/Element/tfoot), and [`tbody`](/en-US/docs/Web/HTML/Element/tbody) elements in an [HTML `table`](/en-US/docs/Learn_web_development/Core/Structuring_content/HTML_table_basics) element. -- [role="table"](/en-US/docs/Web/Accessibility/ARIA/Roles/table_role) - - : One of the three possible contexts (along with `grid` and `treegrid`) in which you'll find a row containing cells. Table identifies the cell as being part of a non-interactive table structure containing data arranged in rows and columns, similar to the native HTML [`<table>`](/en-US/docs/Web/HTML/Element/table) element. -- [role="grid"](/en-US/docs/Web/Accessibility/ARIA/Roles/grid_role) - - : One of the three possible contexts (along with `table` and `treegrid`) in which you'll find a row containing `cells` and `gridcells`. `Grid` identifies a cell as being part of a possibly interactive table structure containing data arranged in rows and columns, similar to the native [`<table>`](/en-US/docs/Web/HTML/Element/table) HTML element. -- [role="treegrid"](/en-US/docs/Web/Accessibility/ARIA/Roles/treegrid_role) - - : Similar to a grid, but with rows that can be expanded and collapsed in the same manner as for a tree. - -#### Subclass roles - -- [role="gridcell"](/en-US/docs/Web/Accessibility/ARIA/Roles/gridcell_role) - - : A cell in a row within a `grid` or `treegrid`. -- [role="columnheader"](/en-US/docs/Web/Accessibility/ARIA/Roles/columnheader_role) - - : A header cell that is the structural equivalent of the HTML [`<th>`](/en-US/docs/Web/HTML/Element/th) element with a column scope. Unlike a plain cell, the `columnheader` role establishes a relationship between it and all cells in the corresponding column. -- [role="rowheader"](/en-US/docs/Web/Accessibility/ARIA/Roles/rowheader_role) - - : A header cell that is the structural equivalent of the HTML [`<th>`](/en-US/docs/Web/HTML/Element/th) element with a row scope. Unlike a plain cell, the `rowheader` role establishes a relationship between it and all cells in the corresponding row. - -#### States and properties - -- [`aria-colspan`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-colspan) - - : Similar to the HTML [`<th>`](/en-US/docs/Web/HTML/Element/th) and [`<td>` colspan attribute](/en-US/docs/Web/HTML/Element/td), it defines the number of columns spanned by the cell. -- [`aria-rowspan`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-rowspan) - - : Similar to the HTML [`<th>`](/en-US/docs/Web/HTML/Element/th) and [`<td>` rowspan attribute](/en-US/docs/Web/HTML/Element/td), it defines the number of rows spanned by the cell. -- [`aria-colindex`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-colindex) attribute - - : The `aria-colindex` attribute is only needed if columns are hidden from the DOM. The attribute takes as its value an integer between 1 and the total number of columns within the `table`, `grid` or `treegrid`. The `aria-colindex` defines an element's column index or position with respect to the total number of columns within a row. If all the columns are in the DOM, this attribute is not necessary. -- [`aria-rowindex`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-rowindex) attribute - - : The `aria-rowindex` attribute is only needed if rows are hidden from the DOM, to indicate which row, in the list of total rows, the current cell is in. The attribute, takes as its value an integer between 1 and the total number of rows within the table, grid, or treegrid, indicating the position, or index, of the cell. For example, a cell in the first row of the first header would likely have `aria-rowindex="1"` set, and cells in row 47 would have `aria-rowindex="47"`, if `aria-rowindex` were needed due to not all rows being in the DOM. If the rows that are visible are contiguous, and there are no cells with a `colspan` or `rowspan` greater than one, this property can be added to the parent rows instead of all the rows' cells. - -### Keyboard interactions - -None - -### Required JavaScript features - -The first rule of ARIA use is if you can use a native feature with the semantics and behavior you require already built in, instead of repurposing an element and **adding** an ARIA role, state or property to make it accessible, then do so. Employ the HTML [`<td>`](/en-US/docs/Web/HTML/Element/td) element instead of the ARIA role of `cell` whenever possible. - -## Examples - -```html -<div - role="table" - aria-label="Semantic Elements" - aria-describedby="semantic_elements_table_desc" - aria-rowcount="81"> - <div id="semantic_elements_table_desc"> - Semantic Elements to use instead of ARIA's roles - </div> - <div role="rowgroup"> - <div role="row"> - <span role="columnheader" aria-sort="none" aria-rowindex="1" - >ARIA Role</span - > - <span role="columnheader" aria-sort="none" aria-rowindex="1" - >Semantic Element</span - > - </div> - </div> - <div role="rowgroup"> - <div role="row"> - <span role="cell" aria-rowindex="11">header</span> - <span role="cell" aria-rowindex="11">h1</span> - </div> - <div role="row"> - <span role="cell" aria-rowindex="16">header</span> - <span role="cell" aria-rowindex="16">h6</span> - </div> - <div role="row"> - <span role="cell" aria-rowindex="18">rowgroup</span> - <span role="cell" aria-rowindex="18">thead</span> - </div> - <div role="row"> - <span role="cell" aria-rowindex="24">term</span> - <span role="cell" aria-rowindex="24">dt</span> - </div> - </div> -</div> -``` - -The above is a non-semantic ARIA table with five of 81 rows present in the DOM: one within a table header and four rows within the table body. Because not all the rows are in the DOM, we've included the `aria-rowindex` property on every cell. If no cells spanned more than one row or column, the `aria-rowindex` could have been placed on the row rather than the row's individual cells. - -## Best practices - -Only use {{HTMLElement('table')}}, {{HTMLElement('tbody')}}, {{HTMLElement('thead')}}, {{HTMLElement('tr')}}, {{HTMLElement('th')}}, {{HTMLElement('td')}}, etc., for data table structure. You can add ARIA roles to ensure accessibility should the native semantics of the table be removed, such as with CSS. A relevant use case for the ARIA table role is when the native semantics of a table are overridden by [CSS's display property, such as by display: grid](/en-US/docs/Web/CSS/display#accessibility). In this case, you can use the ARIA table roles to add the semantics back in. - -```html -<table - role="table" - aria-label="Semantic Elements" - aria-describedby="semantic_elements_table_desc" - aria-rowcount="81"> - <caption id="semantic_elements_table_desc"> - Semantic Elements to use instead of ARIA's roles - </caption> - <thead role="rowgroup"> - <tr role="row"> - <th role="columnheader" aria-sort="none" aria-rowindex="1">ARIA Role</th> - <th role="columnheader" aria-sort="none" aria-rowindex="1"> - Semantic Element - </th> - </tr> - </thead> - <tbody role="rowgroup"> - <tr role="row"> - <td role="cell" aria-rowindex="11">header</td> - <td role="cell" aria-rowindex="11">h1</td> - </tr> - <tr role="row"> - <td role="cell" aria-rowindex="16">header</td> - <td role="cell" aria-rowindex="16">h6</td> - </tr> - <tr role="row"> - <td role="cell" aria-rowindex="18">rowgroup</td> - <td role="cell" aria-rowindex="18">thead</td> - </tr> - <tr role="row"> - <td role="cell" aria-rowindex="24">term</td> - <td role="cell" aria-rowindex="24">dt</td> - </tr> - </tbody> -</table> -``` - -Above is the semantic way of writing a table. The ARIA roles are not necessary if the native semantics of the table, and therefore the table rows, have not been altered, such as through [the display property](/en-US/docs/Web/CSS/display#accessibility). - -### Added benefits - -When applied to a {{HTMLElement('td')}}, it returns cell semantics to the element in case the semantics were removed, such as with `display: grid;`. - -## Specifications - -{{Specifications}} - -## See also - -- [`role="row"`](/en-US/docs/Web/Accessibility/ARIA/Roles/row_role) -- [`role="gridcell"`](/en-US/docs/Web/Accessibility/ARIA/Roles/gridcell_role) -- [HTML `<td>` element](/en-US/docs/Web/HTML/Element/td) -- [HTML `<th>` element](/en-US/docs/Web/HTML/Element/th) -- [Learn: HTML table accessibility](/en-US/docs/Learn_web_development/Core/Structuring_content/Table_accessibility) -- [Learn: HTML table basics](/en-US/docs/Learn_web_development/Core/Structuring_content/HTML_table_basics) diff --git a/files/en-us/web/accessibility/aria/roles/checkbox_role/index.md b/files/en-us/web/accessibility/aria/roles/checkbox_role/index.md deleted file mode 100644 index b7279130023e002..000000000000000 --- a/files/en-us/web/accessibility/aria/roles/checkbox_role/index.md +++ /dev/null @@ -1,184 +0,0 @@ ---- -title: "ARIA: checkbox role" -slug: Web/Accessibility/ARIA/Roles/checkbox_role -page-type: aria-role ---- - -{{AccessibilitySidebar}} - -The `checkbox` role is for checkable interactive controls. Elements containing `role="checkbox"` must also include the [`aria-checked`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-checked) attribute to expose the checkbox's state to assistive technology. - -```html -<span - role="checkbox" - aria-checked="false" - tabindex="0" - aria-labelledby="chk1-label"></span> -<label id="chk1-label">Remember my preferences</label> -``` - -> [!NOTE] -> The first rule of ARIA is if a native HTML element or attribute has the semantics and behavior you require, use it instead of re-purposing an element and adding ARIA. Instead use the native [HTML checkbox of `<input type="checkbox">`](/en-US/docs/Web/HTML/Element/input/checkbox) (with an associated {{HTMLElement('label')}}), which natively provides all the functionality required: - -```html -<input type="checkbox" id="chk1-label" name="RememberPreferences" /> -<label for="chk1-label">Remember my preferences</label> -``` - -## Description - -The native HTML checkbox ([`<input type="checkbox">`](/en-US/docs/Web/HTML/Element/input/checkbox)) form control had two states ("checked" or "not checked"), with an [`indeterminate`](/en-US/docs/Web/HTML/Element/input/checkbox#indeterminate_state_checkboxes) state settable via JavaScript. Similarly, an element with `role="checkbox"` can expose three states through the `aria-checked` attribute: `true`, `false`, or `mixed`. - -Since a checkbox is an interactive control, it must be focusable and keyboard accessible. If the role is applied to a non-focusable element, use the [`tabindex`](/en-US/docs/Web/HTML/Global_attributes/tabindex) attribute to change this. The expected keyboard shortcut for activating a checkbox is the <kbd>Space</kbd> key. - -The developer is required to change the value of the `aria-checked` attribute dynamically when the checkbox is activated. - -### All descendants are presentational - -There are some types of user interface components that, when represented in a platform accessibility API, can only contain text. Accessibility APIs do not have a way of representing semantic elements contained in a `checkbox`. To deal with this limitation, browsers, automatically apply role [`presentation`](/en-US/docs/Web/Accessibility/ARIA/Roles/presentation_role) to all descendant elements of any `checkbox` element as it is a role that does not support semantic children. - -For example, consider the following `checkbox` element, which contains a heading. - -```html -<div role="checkbox"><h6>Name of my checkbox</h6></div> -``` - -Because descendants of `checkbox` are presentational, the following code is equivalent: - -```html -<div role="checkbox"><h6 role="presentation">Name of my checkbox</h6></div> -``` - -From the assistive technology user's perspective, the heading does not exist since the previous code snippets are equivalent to the following in the [accessibility tree](/en-US/docs/Glossary/Accessibility_tree): - -```html -<div role="checkbox">Name of my checkbox</div> -``` - -### Associated WAI-ARIA Roles, States, and Properties - -- [`aria-checked`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-checked) - - - : The value of `aria-checked` defines the state of a checkbox. This attribute has one of three possible values: - - - `true` - - : The checkbox is checked. - - `false` - - : The checkbox is not checked. - - `mixed` - - : The checkbox is partially checked, or indeterminate. - -- `tabindex="0"` - - : Used to make it focusable so the assistive technology user can tab to it and start reading right away. - -### Keyboard interactions - -| Key | Function | -| ---------------- | ---------------------- | -| <kbd>Space</kbd> | Activates the checkbox | - -### Required JavaScript - -#### Required event handlers - -- `onclick` - - : Handle mouse clicks on both the checkbox and the associated label that will change the state of the checkbox by changing the value of the `aria-checked` attribute and the appearance of the checkbox so it appears checked or unchecked to the sighted user -- `onKeyDown` - - - : Handle the case where the user presses the <kbd>Space</kbd> key to change the state of the checkbox by changing the value of the `aria-checked` attribute and the appearance of the checkbox so it appears checked or unchecked to the sighted user - -## Examples - -The following example creates an otherwise non-semantic checkbox element using CSS and JavaScript to handle the checked or unchecked status of the element. - -### HTML - -```html -<span - role="checkbox" - id="chkPref" - aria-checked="false" - onclick="changeCheckbox()" - onKeyDown="changeCheckbox(event.code)" - tabindex="0" - aria-labelledby="chk1-label"></span> -<label - id="chk1-label" - onclick="changeCheckbox()" - onKeyDown="changeCheckbox(event.code)" - >Remember my preferences</label -> -``` - -### CSS - -```css -[role="checkbox"] { - padding: 5px; -} - -[role="checkbox"]:focus { - border: 2px solid #0198e1; -} - -[aria-checked="true"]::before { - content: "[x]"; -} - -[aria-checked="false"]::before { - content: "[ ]"; -} -``` - -### JavaScript - -```js -function changeCheckbox(code) { - const item = document.getElementById("chkPref"); - const checked = item.getAttribute("aria-checked"); - - if (code && code !== "Space") { - return; - } else if (checked === "true") { - item.setAttribute("aria-checked", "false"); - } else { - item.setAttribute("aria-checked", "true"); - } -} -``` - -{{EmbedLiveSample("Examples", 230, 250)}} - -## Accessibility concerns - -When the `checkbox` role is added to an element, the user agent should do the following: - -- Expose the element as having a `checkbox` role in the operating system's accessibility API. -- When the `aria-checked` value changes, send an accessible state changed event. - -Assistive technology products should do the following: - -- Screen readers should announce the element as a checkbox, and optionally provide instructions on how to activate it. - -People implementing checkboxes should do the following: - -- Ensure that the checkbox can be reached and interacted with by both keyboard controls and clicks -- Keep the `aria-checked` attribute up to date following user interactions -- Provide styles that indicate when the checkbox has focus - -> [!NOTE] -> Opinions may differ on how assistive technology should handle this technique. The information provided above is one of those opinions and may change. - -## Best practices - -The first rule of ARIA is: if a native HTML element or attribute has the semantics and behavior you require, use it instead of re-purposing an element and adding an ARIA role, state or property to make it accessible. As such, it is recommended to use the native [HTML checkbox](/en-US/docs/Web/HTML/Element/input/checkbox) using form control instead of recreating a checkbox's functionality with JavaScript and ARIA. - -## See also - -- [`<input type="checkbox">`](/en-US/docs/Web/HTML/Element/input/checkbox) -- [ARIA: `radio` role](/en-US/docs/Web/Accessibility/ARIA/Roles/radio_role) -- [ARIA: `menuitem` role](/en-US/docs/Web/Accessibility/ARIA/Roles/menuitem_role) -- [ARIA: `menuitemcheckbox` role](/en-US/docs/Web/Accessibility/ARIA/Roles/menuitemcheckbox_role) -- [ARIA: `menuitemradio` role](/en-US/docs/Web/Accessibility/ARIA/Roles/menuitemradio_role) -- [ARIA: `switch` role](/en-US/docs/Web/Accessibility/ARIA/Roles/switch_role) -- [ARIA: `option` role](/en-US/docs/Web/Accessibility/ARIA/Roles/option_role) diff --git a/files/en-us/web/accessibility/aria/roles/columnheader_role/index.md b/files/en-us/web/accessibility/aria/roles/columnheader_role/index.md deleted file mode 100644 index 60925b2c1196d61..000000000000000 --- a/files/en-us/web/accessibility/aria/roles/columnheader_role/index.md +++ /dev/null @@ -1,85 +0,0 @@ ---- -title: "ARIA: columnheader role" -slug: Web/Accessibility/ARIA/Roles/columnheader_role -page-type: aria-role -spec-urls: - - https://w3c.github.io/aria/#columnheader - - https://www.w3.org/WAI/ARIA/apg/patterns/table/examples/table/ ---- - -{{AccessibilitySidebar}} - -The `columnheader` value of the ARIA role attribute identifies an element as being a cell in a row contains header information for a column, similar to the native {{HTMLElement('th')}} element with column scope. - -## Description - -An element with `role="columnheader"` nested as a descendant for an element with `role="row"`, is a static tabular structure of a column header cell in a tabular container, either a table or grid, or other chart that needs to show data relationships. To be supported, the columnheader must be nested in an element with the [role of `row`](/en-US/docs/Web/Accessibility/ARIA/Roles/row_role). - -### Associated WAI-ARIA roles, states, and properties - -All column headers should be nested within a [row](/en-US/docs/Web/Accessibility/ARIA/Roles/row_role). Every row, in turn, should be nested within a [grid](/en-US/docs/Web/Accessibility/ARIA/Roles/grid_role), [table](/en-US/docs/Web/Accessibility/ARIA/Roles/table_role), or [treegrid](/en-US/docs/Web/Accessibility/ARIA/Roles/row_role), alternatively within a [rowgroup](/en-US/docs/Web/Accessibility/ARIA/Roles/rowgroup_role) nested within one of the above. - -- [`aria-sort`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-sort) - - : Only applied to one column header at a time, if any, the `aria-sort` attribute indicates if a column is sorted in the three values of `ascending` or `descending` order, or `none` for not sorted. - -### Keyboard interactions - -This role does not support any specific keyboard interaction. - -### Required JavaScript features - -JavaScript is only required if the `aria-sort` attribute is used. - -## Examples - -```html -<table> - <thead> - <tr role="row"> - <th role="columnheader" scope="col"> - <button>First Name</button> - </th> - <th role="columnheader" scope="col"> - <button>Last Name</button> - </th> - <th role="columnheader" scope="col" aria-sort="ascending"> - <button>Company Name</button> - </th> - <th role="columnheader" scope="col"> - <button>Job Title</button> - </th> - </tr> - </thead> - <tbody> - … - </tbody> -</table> -``` - -## Best Practices - -Column headers should contain a title or header information for the column. - -The first rule of ARIA is: if a native HTML element or attribute has the semantics and behavior you require, use it instead of re-purposing an element and adding an ARIA role, state or property to make it accessible. It is recommended to use the native HTML `<th>` element with the `scope` attribute set `<th scope="col">` instead of a `<div>` or other element. If you use semantic HTML's `<th scope="col">` the role attribute is not required, but can be included as a back up to ensure the table retains its semantics should the default semantics be removed with a CSS display property value. - -The `aria-sort` attribute can be added to a `<th scope="col">` even when the ARIA role attribute is not specified. - -### Prefer HTML - -Columnheader has the same semantics `<th scope="col">`. - -## Specifications - -{{Specifications}} - -## See also - -- [`table` role](/en-US/docs/Web/Accessibility/ARIA/Roles/table_role) -- [`grid` role](/en-US/docs/Web/Accessibility/ARIA/Roles/grid_role) -- [`treegrid` role](/en-US/docs/Web/Accessibility/ARIA/Roles/row_role) -- [`row` role](/en-US/docs/Web/Accessibility/ARIA/Roles/row_role) -- [`rowgroup` role](/en-US/docs/Web/Accessibility/ARIA/Roles/rowgroup_role) -- [The `<th>` element](/en-US/docs/Web/HTML/Element/th) -- [The `<table>` element](/en-US/docs/Web/HTML/Element/table) -- [The `<tr>` element](/en-US/docs/Web/HTML/Element/tr) -- [The `<td>` element](/en-US/docs/Web/HTML/Element/td) diff --git a/files/en-us/web/accessibility/aria/roles/combobox_role/index.md b/files/en-us/web/accessibility/aria/roles/combobox_role/index.md deleted file mode 100644 index 07c79e5fc44cc2a..000000000000000 --- a/files/en-us/web/accessibility/aria/roles/combobox_role/index.md +++ /dev/null @@ -1,115 +0,0 @@ ---- -title: "ARIA: combobox role" -slug: Web/Accessibility/ARIA/Roles/combobox_role -page-type: aria-role -spec-urls: - - https://w3c.github.io/aria/#combobox, - - https://www.w3.org/WAI/ARIA/apg/patterns/combobox/examples/combobox-select-only/ ---- - -{{AccessibilitySidebar}} - -The `combobox` role identifies an element as an `input` that controls another element, such as a `listbox` or `grid`, that can dynamically pop up to help the user set the value of that `input`. - -## Description - -A `combobox` is a composite widget that combines a named input field with a popup providing possible values for that input field. The purpose of this widget is to improve user experience by helping the user select a value without having to type in the complete value and, optionally depending whether supported values are limited, preventing the user from entering invalid or otherwise unsupported values. - -The `combobox` role is set on input that controls another element, such as a listbox or grid, that can dynamically pop up to help the user set the value of the input. - -The `combobox` input field can either be a single-line text field that supports editing and typing, similar to a HTML {{HTMLElement('input')}} with a {{HTMLElement('datalist')}}, or an element that only displays the current value of the combobox. - -A WAI-ARIA combobox only has one attribute that is required that authors specify: [`aria-expanded`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-expanded). However, it also has several other attributes which will be necessary to specify, depending on the combobox's implementation. These include [`aria-haspopup`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-haspopup), [`aria-controls`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-controls), [`aria-activedescendant`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-activedescendant), and [`aria-autocomplete`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-autocomplete). - -Typically, the initial state of a combobox is collapsed, with `aria-expanded="false"` set. In the collapsed state, only the combobox element and, optionally a sibling button to invoke the popup, are visible. The [`aria-expanded`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-expanded), with the value set to `false`, is required when collapsed, because it indicates to assistive technologies that the widget is expandable. - -The combobox is in the expanded state when both the combobox element showing its current value and its associated popup element are visible. When expanded, `aria-expanded="true"` must be set. - -The popup element associated with a `combobox` can be either a [`listbox`](/en-US/docs/Web/Accessibility/ARIA/Roles/listbox_role), [`tree`](/en-US/docs/Web/Accessibility/ARIA/Roles/tree_role), [`grid`](/en-US/docs/Web/Accessibility/ARIA/Roles/grid_role), or [`dialog`](/en-US/docs/Web/Accessibility/ARIA/Roles/dialog_role) element. - -Comboboxes have an implicit [`aria-haspopup`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-haspopup) value of `listbox`, so including this attribute is optional if the popup is a `listbox`. If the combobox popup element is a `tree`, `grid`, or `dialog` (anything other than a `listbox`), the `aria-haspopup` attribute is required. The value of `aria-haspopup` must be either the `tree`, `grid`, `dialog`, or `listbox` role. Note that for this property, `true` means `menu`, so make sure that the value corresponds to the role of the popup, not a Boolean value. - -When a combobox's popup is displayed, ensure the [`aria-controls`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-controls) attribute on the combobox element is set to the [`id`](/en-US/docs/Web/HTML/Global_attributes/id) of the popup `listbox`, `tree`, `grid`, or `dialog` element. This is how the relationship between the element with the `combobox` role and the popup it controls is indicated. (Note: In older ARIA specs, this was `aria-owns` rather than `aria-controls`, so you may see `aria-owns` in older combobox implementations. The `aria-owns` in the code should be updated to `aria-controls`!) - -If the combobox UI includes a visible control, such as an icon, that allows the visibility of the popup to be controlled via pointer and touch events, that control should be a {{HTMLElement('button')}}, {{HTMLElement('input')}} of type `button`, or a [`button`](/en-US/docs/Web/Accessibility/ARIA/Roles/button_role) role element with a [`tabindex`](/en-US/docs/Web/HTML/Global_attributes/tabindex) of `-1`. Doing so will allow the button to be focusable but not included in keyboard tab sequence. It must not be a descendant of the element with role `combobox`. - -To be keyboard accessible, keyboard support for moving focus between the `combobox` input field element and elements contained in the popup `listbox`, `tree`, `grid`, or `dialog`, must be programmed in. One common convention is that <kbd>Down Arrow</kbd> moves focus from the input to the first focusable descendant of the popup element. - -The [`aria-activedescendant`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-activedescendant) property can be used to identify the currently active element of the combobox popup, for instance an `option` within a popup `listbox`, for implementations where DOM focus remains on the combobox. If DOM focus does not remain on the combobox when its popup is invoked, but rather DOM focus moves into the popup, such as a dialog, then `aria-activedescendant` may not be necessary. - -If the combobox element is an {{HTMLElement('input')}} element, the value of the combobox is the input's value. Otherwise, the value of the combobox comes from its descendant elements. - -If the `combobox` supports text input and provides autocompletion behavior, set [`aria-autocomplete`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-autocomplete) on the combobox element to the value that corresponds to the provided behavior: `inline`, `list`, or `both`. The `aria-autocomplete` attribute indicates that inputting text will trigger display of one or more predictions of the user's intended value for the combobox and specifies how the predictions will be presented when made. - -Every `combobox` must have an accessible name. If using an {{HTMLElement('input')}} element, the accessible name should come from the associated {{HTMLElement('label')}}. If not, if an appropriate label is visible in the content, provide the name via [`aria-labelledby`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-labelledby). In other words, if there is an element in the user interface that serves as a label for the `combobox` input field, include `aria-labelledby` as an attribute on the element with the role of `combobox`, and set the value of the attribute to the `id` of the labelling element or elements. If no visible label is present, use [`aria-label`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-label) instead. Not both. - -### Associated WAI-ARIA roles, states, and properties - -- [`aria-expanded`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-expanded) - - : Required. Identifies whether the combobox is open (`true`) or closed (`false`). -- [`aria-haspopup`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-haspopup) - - : Implied. If omitted, defaults to `listbox`. Also supports `tree`, `grid`, or `dialog`. Identifies the combobox has having a popout, and indicates the type. - -### Keyboard interactions - -- <kbd>Down Arrow</kbd> - - - : Moves focus to the next option, or to the first option if none was selected. - -- <kbd>Alt</kbd> + <kbd>Down Arrow</kbd> (Optional) - - - : If the popup is available but not displayed, displays the popup without moving focus. - -- <kbd>Up Arrow</kbd> - - - : Moves focus to the previous option. Moving focus to the first option if focus was originally on the last option. - -- <kbd>Alt</kbd> + <kbd>Up Arrow</kbd> (Optional) - - - : If the popup has focus, returns focus to the combobox, otherwise it closes the popup. - -- <kbd>Enter</kbd> - - : If the combobox is editable and an autocomplete suggestion is selected in the popup, accepts the suggestion either by placing the input cursor at the end of the accepted value in the combobox or by performing a default action on the value. For example, in a messaging application, the default action may be to add the accepted value to a list of message recipients and then clear the combobox so the user can add another recipient. - -## Examples - -```html -<label for="jokes">Pick what type of jokes you like</label> -<div class="combo-wrap"> - <input - type="text" - id="jokes" - role="combobox" - aria-controls="joketypes" - aria-autocomplete="list" - aria-expanded="false" - data-active-option="item1" - aria-activedescendant="" /> - <span aria-hidden="true" data-trigger="multiselect"></span> - <ul id="joketypes" role="listbox" aria-label="Jokes"> - <li class="active" role="option" id="item1">Puns</li> - <li class="option" role="option" id="item2">Riddles</li> - <li class="option" role="option" id="item3">Observations</li> - <li class="option" role="option" id="item4">Knock-knock</li> - <li class="option" role="option" id="item5">One liners</li> - </ul> -</div> -``` - -## Specifications - -{{Specifications}} - -## See also - -- HTML {{HTMLElement('label')}} element -- HTML {{HTMLElement('select')}} element -- HTML {{HTMLElement('option')}} element -- HTML {{HTMLElement('input')}} element -- [ARIA: `listbox` role](/en-US/docs/Web/Accessibility/ARIA/Roles/listbox_role) -- [ARIA: `option` role](/en-US/docs/Web/Accessibility/ARIA/Roles/option_role) -- [ARIA: `list` role](/en-US/docs/Web/Accessibility/ARIA/Roles/list_role) -- [ARIA: `listitem` role](/en-US/docs/Web/Accessibility/ARIA/Roles/listitem_role) -- [ARIA Best Practices – Combobox](https://www.w3.org/WAI/ARIA/apg/patterns/combobox/) -- [ARIA Role Model – Combobox](https://www.w3.org/TR/wai-aria-1.2/#combobox) -- [Accessible combobox module](https://dequelabs.github.io/combobo/demo/) examples by Deque diff --git a/files/en-us/web/accessibility/aria/roles/command_role/index.md b/files/en-us/web/accessibility/aria/roles/command_role/index.md deleted file mode 100644 index 4630d9e71e2b544..000000000000000 --- a/files/en-us/web/accessibility/aria/roles/command_role/index.md +++ /dev/null @@ -1,32 +0,0 @@ ---- -title: "ARIA: command role" -slug: Web/Accessibility/ARIA/Roles/command_role -page-type: aria-role -spec-urls: https://w3c.github.io/aria/#command ---- - -{{AccessibilitySidebar}} - -The `command` role defines a widget that performs an action but does not receive input data. - -> [!NOTE] -> The `command` role is an abstract role. It is included here for completeness of documentation. It should not be used by web authors. - -## Description - -A command is form of widget that performs an action but does not receive input data. It is a superclass for the widget roles [`button`](/en-US/docs/Web/Accessibility/ARIA/Roles/button_role), [`link`](/en-US/docs/Web/Accessibility/ARIA/Roles/link_role), and [`menuitem`](/en-US/docs/Web/Accessibility/ARIA/Roles/menuitem_role) - -## Best Practices - -Do not use. - -## Specifications - -{{Specifications}} - -## See also - -- [ARIA: `widget` role](/en-US/docs/Web/Accessibility/ARIA/Roles/widget_role) -- [ARIA: `button` role](/en-US/docs/Web/Accessibility/ARIA/Roles/button_role) -- [ARIA: `link` role](/en-US/docs/Web/Accessibility/ARIA/Roles/link_role) -- [ARIA: `menuitem` role](/en-US/docs/Web/Accessibility/ARIA/Roles/menuitem_role) diff --git a/files/en-us/web/accessibility/aria/roles/comment_role/index.md b/files/en-us/web/accessibility/aria/roles/comment_role/index.md deleted file mode 100644 index 97e519d75525224..000000000000000 --- a/files/en-us/web/accessibility/aria/roles/comment_role/index.md +++ /dev/null @@ -1,91 +0,0 @@ ---- -title: "ARIA: comment role" -slug: Web/Accessibility/ARIA/Roles/comment_role -page-type: aria-role ---- - -{{AccessibilitySidebar}} - -The `comment` role semantically denotes a comment/reaction to some content on the page, or to a previous comment. - -> [!NOTE] -> The comment role is proposed in WAI-ARIA 1.3 ([Most recent ARIA draft](https://w3c.github.io/aria/)), which is still being drafted. - -## Examples - -In the following example we have a document section that has been commented. The commented section is marked up using `<span role="mark">`. - -The related comment is marked up using an HTML structure wrapped with a `<div>` containing `role="comment"`. - -```html -<p> - The last half of the song is a slow-rising crescendo that peaks at the - <span role="mark" aria-details="thread-1">end of the guitar solo</span>, - before fading away sharply. -</p> - -<div role="comment" id="thread-1" data-author="chris"> - <h3>Chris said</h3> - <p class="comment-text">I really think this moment could use more cowbell.</p> - <p><time datetime="2019-03-30T19:29">March 30 2019, 19:29</time></p> -</div> -``` - -To associate the comment with the text being commented, we need to wrap the commented text with an element containing the [`aria-details`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-details) attribute, the value of which should be the ID of the comment. - -### Multiple comments - -Since `aria-details` can now accept multiple IDs, we can associate multiple comments with the same annotation, like so: - -```html -<p> - The last half of the song is a slow-rising crescendo that peaks at the - <mark aria-details="thread-1 thread-2">end of the guitar solo</mark>, before - fading away sharply. -</p> - -<div role="comment" id="thread-1" data-author="chris"> - <h3>Chris said</h3> - <p class="comment-text">I really think this moment could use more cowbell.</p> - <p><time datetime="2019-03-30T19:29">March 30 2019, 19:29</time></p> -</div> - -<div role="comment" id="thread-2" data-author="chris"> - <h3>Marcus said</h3> - <p class="comment-text"> - The guitar solo could do with a touch more chorus, and a slightly lower - volume. - </p> - <p><time datetime="2019-03-29T15:35">March 29 2019, 15:35</time></p> -</div> -``` - -### Nested comments - -It's possible to nest comments inside one another, like so: - -```html -<div role="comment" id="thread-1" data-author="chris"> - <h3>Chris said</h3> - <p class="comment-text">I really think this moment could use more cowbell.</p> - <p><time datetime="2021-03-30T19:29">March 30 2021, 19:29</time></p> - - <div role="comment" data-author="marcus"> - <h3>Marcus replied</h3> - <p class="comment-text"> - I don't know about that. I think the cowbell could distract from the solo. - </p> - <p><time datetime="2021-03-30T21:02">March 30 2021, 21:02</time></p> - </div> -</div> -``` - -## Accessibility concerns - -None - -## Specifications - -Will be part of WAI-ARIA 1.3, which is still being drafted. - -## See also diff --git a/files/en-us/web/accessibility/aria/roles/complementary_role/index.md b/files/en-us/web/accessibility/aria/roles/complementary_role/index.md deleted file mode 100644 index ddc3d49941abe27..000000000000000 --- a/files/en-us/web/accessibility/aria/roles/complementary_role/index.md +++ /dev/null @@ -1,99 +0,0 @@ ---- -title: "ARIA: complementary role" -slug: Web/Accessibility/ARIA/Roles/complementary_role -page-type: aria-role -spec-urls: - - https://w3c.github.io/aria/#complementary - - https://www.w3.org/WAI/ARIA/apg/patterns/landmarks/examples/complementary.html ---- - -{{AccessibilitySidebar}} - -The `complementary` [landmark role](/en-US/docs/Web/Accessibility/ARIA/Roles#3._landmark_roles) is used to designate a supporting section that relates to the main content, yet can stand alone when separated. These sections are frequently presented as sidebars or call-out boxes. If possible, use the [HTML \<aside> element](/en-US/docs/Web/HTML/Element/aside) instead. - -```html -<div role="complementary"> - <h2>Our partners</h2> - <!-- complementary section content --> -</div> -``` - -This is a sidebar containing links to project sponsors. - -## Description - -The `complementary` role is [a landmark](/en-US/docs/Web/Accessibility/ARIA/ARIA_Techniques#landmark_roles) role. Landmarks can be used by assistive technology to quickly identify and navigate to large sections of the document. Content listed within a container with the `complementary` landmark role should make sense if separated from the main content of the document. - -> [!NOTE] -> Using the {{HTMLElement('aside')}} element will automatically communicate a section has a role of `complementary`. Developers should always prefer using the correct semantic HTML element over using ARIA. - -## Examples - -```html -<div role="complementary"> - <h2>Trending articles</h2> - <ul> - <li><a href="#">18 tweets that will make you feel all the feels</a></li> - <li> - <a href="#">Stop searching! I've found the perfect lunch containers.</a> - </li> - <li> - <a href="#">The time has come to decide how to call these foods</a> - </li> - <li><a href="#">17 really good posts we saw on Tumblr this week</a></li> - <li><a href="#">10 parent hacks we know work because we tried them</a></li> - </ul> -</div> -``` - -## Accessibility concerns - -[Landmark roles](/en-US/docs/Web/Accessibility/ARIA/ARIA_Techniques#landmark_roles) are intended to be used sparingly, to identify larger overall sections of the document. Using too many landmark roles can create "noise" in screen readers, making it difficult to understand the overall layout of the page. - -## Best practices - -### Prefer HTML - -Using the {{HTMLElement('aside')}} element will automatically communicate a section has a role of `complementary`. If at all possible, prefer using it instead. - -### Labeling landmarks - -#### Multiple landmarks - -If there is more than one `complementary` landmark role or {{HTMLElement('aside')}} element in a document, provide a label for each landmark using the [`aria-label`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-label) attribute, or, if the aside has an appropriately descriptive title, point to it with the [`aria-labelledby`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-labelledby) attribute. This label will allow an assistive technology user to be able to quickly understand the purpose of each landmark. - -```html -<aside aria-label="Note about usage"> - <!-- content --> -</aside> - -… - -<aside id="sidebar" aria-label="Sponsors"> - <!-- content --> -</aside> -``` - -#### Redundant descriptions - -Screen readers will announce the type of role the landmark is. Because of this, you do not need to describe what the landmark is in its label. For example, a declaration of `role="complementary"` with an of `aria-label="Sidebar"` may be announced redundantly as, "complementary sidebar". - -### Added benefits - -Certain technologies such as browser extensions can generate lists of all landmark roles present on a page, allowing non-screen reader users to also quickly identify and navigate to large sections of the document. - -- [Landmarks browser extension](https://matatk.agrip.org.uk/landmarks/) - -## Specifications - -{{Specifications}} - -## See also - -- [\<aside>: The Aside element](/en-US/docs/Web/HTML/Element/aside) -- [complementary (role): Accessible Rich Internet Applications (WAI-ARIA) 1.1](https://www.w3.org/TR/wai-aria/#complementary) -- [Using HTML sections and outlines](/en-US/docs/Web/HTML/Element/Heading_Elements) -- [Landmark roles: Using ARIA: Roles, States, and Properties](/en-US/docs/Web/Accessibility/ARIA/ARIA_Techniques#landmark_roles) -- [Using WAI-ARIA Landmarks – 2013 | The Paciello Group](https://www.tpgi.com/using-wai-aria-landmarks-2013/) -- [Accessible Landmarks | scottohara.me](https://www.scottohara.me/blog/2018/03/03/landmarks.html) -- [Aside Revisited | HTML5 Doctor](https://html5doctor.com/aside-revisited/) diff --git a/files/en-us/web/accessibility/aria/roles/composite_role/index.md b/files/en-us/web/accessibility/aria/roles/composite_role/index.md deleted file mode 100644 index aef99552c478d27..000000000000000 --- a/files/en-us/web/accessibility/aria/roles/composite_role/index.md +++ /dev/null @@ -1,33 +0,0 @@ ---- -title: "ARIA: composite role" -slug: Web/Accessibility/ARIA/Roles/composite_role -page-type: aria-role -spec-urls: https://w3c.github.io/aria/#composite ---- - -{{AccessibilitySidebar}} - -The `composite` [abstract role](/en-US/docs/Web/Accessibility/ARIA/Roles#6._abstract_roles) indicates a widget that may contain navigable descendants or owned children. - -> [!NOTE] -> The `composite` role is an abstract role. It is included here for completeness of documentation. It should not be used by web authors. - -## Description - -`Composite` is an abstract role used for the ontology. Don't use this role in content. Instead, use the composite subclasses of [`grid`](/en-US/docs/Web/Accessibility/ARIA/Roles/grid_role), [`select`](/en-US/docs/Web/Accessibility/ARIA/Roles/select_role), [`spinbutton`](/en-US/docs/Web/Accessibility/ARIA/Roles/spinbutton_role), and [`tablist`](/en-US/docs/Web/Accessibility/ARIA/Roles/tablist_role) - -## Best Practices - -Do not use. - -## Specifications - -{{Specifications}} - -## See also - -- [ARIA: `widget` role](/en-US/docs/Web/Accessibility/ARIA/Roles/widget_role) -- [ARIA: `grid` role](/en-US/docs/Web/Accessibility/ARIA/Roles/grid_role) -- [ARIA: `select` role](/en-US/docs/Web/Accessibility/ARIA/Roles/select_role) -- [ARIA: `spinbutton` role](/en-US/docs/Web/Accessibility/ARIA/Roles/spinbutton_role) -- [ARIA: `tablist` role](/en-US/docs/Web/Accessibility/ARIA/Roles/tablist_role) diff --git a/files/en-us/web/accessibility/aria/roles/contentinfo_role/index.md b/files/en-us/web/accessibility/aria/roles/contentinfo_role/index.md deleted file mode 100644 index 6a7fe8cb59723d2..000000000000000 --- a/files/en-us/web/accessibility/aria/roles/contentinfo_role/index.md +++ /dev/null @@ -1,133 +0,0 @@ ---- -title: "ARIA: contentinfo role" -slug: Web/Accessibility/ARIA/Roles/contentinfo_role -page-type: aria-role -spec-urls: - - https://w3c.github.io/aria/#contentinfo - - https://www.w3.org/WAI/ARIA/apg/patterns/landmarks/examples/contentinfo.html ---- - -{{AccessibilitySidebar}} - -The `contentinfo` role defines a footer, containing identifying information such as copyright information, navigation links, and privacy statements, found on every document within a site. This section is commonly called a footer. - -```html -<div role="contentinfo"> - <h2>Footer</h2> - <!-- footer content --> -</div> -``` - -This is a website footer. Using the {{HTMLElement('footer')}} element instead is recommended: - -```html -<footer> - <h2>Footer</h2> - <!-- footer content --> -</footer> -``` - -## Description - -The `contentinfo` role is [a landmark](/en-US/docs/Web/Accessibility/ARIA/Roles#3._landmark_roles) used to identify a page footer. Landmarks can be used by assistive technology to quickly identify and navigate to large sections of the document. Pages should only include one top-level `contentinfo` landmark role per page. - -Each page should only include one `contentinfo` landmark, created by either using the {{HTMLElement('footer')}} element or by declaring `role="contentinfo"`. `contentinfo` landmarks present in content embedded via {{HTMLElement('iframe')}} do not count towards this limit. - -> [!NOTE] -> Using the {{HTMLElement('footer')}} element will automatically communicate a section has a role of `contentinfo`. Developers should always prefer using the correct semantic HTML element over using ARIA, making sure to {{HTMLElement('footer#accessibility', 'test for known issues')}} in VoiceOver. - -## Examples - -```html -<body> - <!-- other page content --> - - <div role="contentinfo"> - <h2>MDN Web Docs</h2> - <ul> - <li><a href="#">Web Technologies</a></li> - <li><a href="#">Learn Web Development</a></li> - <li><a href="#">About MDN</a></li> - <li><a href="#">Feedback</a></li> - </ul> - <p> - © 2005-2012 Mozilla and individual contributors. Content is available - under <a href="#">these licenses</a>. - </p> - </div> -</body> -``` - -## Accessibility concerns - -### Use sparingly - -[Landmark roles](/en-US/docs/Web/Accessibility/ARIA/Roles#3._landmark_roles) are intended to identify larger overall sections of the document. Using too many landmark roles can create "noise" in screen readers, making it difficult to understand the overall layout of the page. - -### One `contentinfo` landmark per page - -#### The `<body>` element - -There should be only one `contentinfo` landmark per document, used as the immediate descendant of the {{HTMLElement('body')}} element. - -#### Mega-footers - -Do not nest additional {{HTMLElement('footer')}} elements or `contentinfo` landmarks inside the document's footer. Use other [content sectioning elements](/en-US/docs/Web/HTML/Element#content_sectioning) instead. - -### Labeling landmarks - -#### Multiple landmarks - -If there is more than one `contentinfo` landmark role or {{HTMLElement('footer')}} element in a document, provide a label with the [`aria-label`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-label) attribute for each landmark. This label will allow assistive technology users to quickly understand the purpose of each landmark. - -```html -<body> - … - - <article> - <h2>Everyday Pad Thai</h2> - <!-- article content --> - <footer aria-label="Everyday Pad Thai metadata"> - <p> - Posted on <time datetime="2021-09-23 12:17">September 23</time> by - <a href="#">Lisa</a>. - </p> - </footer> - </article> - - … - - <footer aria-label="Footer"> - <!-- footer content --> - </footer> -</body> -``` - -#### Redundant descriptions - -Screen readers will announce the type of role the landmark is. Because of this, you do not need to describe what the landmark is in its label. For example, a declaration of `role="contentinfo"` with an of `aria-label="Footer"` may be announced redundantly as, "contentinfo footer". - -## Best practices - -### Prefer HTML - -When it is an immediate descendant of the {{HTMLElement('body')}} using the {{HTMLElement('footer')}} element will automatically communicate a section has a role of `contentinfo` (save for {{HTMLElement('footer#accessibility', 'a known issue')}} in VoiceOver). If at all possible, prefer using `<footer>` instead. Note that a `footer` element nested within an `article`, `aside`, `main`, `nav`, or `section` is not considered `contentinfo`. - -### Added benefits - -Certain technologies such as browser extensions can generate lists of all landmark roles present on a page, allowing non-screen reader users to also quickly identify and navigate to large sections of the document. - -- [Landmarks browser extension](https://matatk.agrip.org.uk/landmarks/) - -## Specifications - -{{Specifications}} - -## See also - -- The {{HTMLElement('footer')}} element -- [contentinfo (role): Accessible Rich Internet Applications (WAI-ARIA) 1.1](https://www.w3.org/TR/wai-aria/#contentinfo) -- [Using HTML sections and outlines](/en-US/docs/Web/HTML/Element/Heading_Elements) -- [Using WAI-ARIA Landmarks – 2013 | The Paciello Group](https://www.tpgi.com/using-wai-aria-landmarks-2013/) -- [Accessible Landmarks | scottohara.me](https://www.scottohara.me/blog/2018/03/03/landmarks.html) -- [The Footer Element Update | HTML5 Doctor](https://html5doctor.com/the-footer-element-update/) diff --git a/files/en-us/web/accessibility/aria/roles/definition_role/index.md b/files/en-us/web/accessibility/aria/roles/definition_role/index.md deleted file mode 100644 index 2ff762eb6991871..000000000000000 --- a/files/en-us/web/accessibility/aria/roles/definition_role/index.md +++ /dev/null @@ -1,48 +0,0 @@ ---- -title: "ARIA: definition role" -slug: Web/Accessibility/ARIA/Roles/definition_role -page-type: aria-role -spec-urls: https://w3c.github.io/aria/#definition ---- - -{{AccessibilitySidebar}} - -The `definition` ARIA role indicates the element is a definition of a term or concept. - -## Description - -The `definition` ARIA role can be included on an element that is a definition of a term or concept, similar to the native {{HTMLElement('dfn')}} element. To associate the definition with the `term` being defined, and to provide an accessible name, reference the term being defined with `role="term"`, using [`aria-labelledby`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-labelledby). - -```html-nolint -<p> - <span role="term">Mansplaining</span>, - <span role="definition"> - a portmanteau of "man" and "explain", is the patronizing act of explaining - without being asked to do so, to someone already learned on the topic, often - after someone has already explained it - </span>. -</p> -``` - -> [!NOTE] -> Instead of a `<span>` with the [`term`](/en-US/docs/Web/Accessibility/ARIA/Roles/term_role) and `definition` roles, use the {{HTMLElement('dfn')}} element. **Always use native element if available.** - -```html -<p> - <dfn>Mansplaining</dfn>, a portmanteau of "man" and "explain", is the - patronizing act of explaining without being asked to do so, to someone already - learned on the topic, often after someone has already explained it. -</p> -``` - -## Specifications - -{{Specifications}} - -## See also - -- [The `term` role](/en-US/docs/Web/Accessibility/ARIA/Roles/term_role) -- The {{HTMLElement('dfn')}} element -- The {{HTMLElement('dd')}} element -- The {{HTMLElement('dl')}} element -- The {{HTMLElement('dt')}} element diff --git a/files/en-us/web/accessibility/aria/roles/dialog_role/index.md b/files/en-us/web/accessibility/aria/roles/dialog_role/index.md deleted file mode 100644 index d0ea56f4f08c10a..000000000000000 --- a/files/en-us/web/accessibility/aria/roles/dialog_role/index.md +++ /dev/null @@ -1,143 +0,0 @@ ---- -title: "ARIA: dialog role" -slug: Web/Accessibility/ARIA/Roles/dialog_role -page-type: aria-role -spec-urls: - - https://w3c.github.io/aria/#dialog - - https://www.w3.org/WAI/ARIA/apg/patterns/dialog-modal/examples/dialog/ ---- - -{{AccessibilitySidebar}} - -The `dialog` role is used to mark up an HTML based application dialog or window that separates content or UI from the rest of the web application or page. Dialogs are generally placed on top of the rest of the page content using an overlay. Dialogs can be either non-modal (it's still possible to interact with content outside of the dialog) or modal (only the content in the dialog can be interacted with). - -```html -<div - role="dialog" - aria-labelledby="dialog1Title" - aria-describedby="dialog1Desc"> - <h2 id="dialog1Title">Your personal details were successfully updated</h2> - <p id="dialog1Desc"> - You can change your details at any time in the user account section. - </p> - <button>Close</button> -</div> -``` - -## Description - -A dialog is a descendant window of the primary window of a web application. For HTML pages, the primary application window is the entire web document, i.e., the body element. - -Marking up a dialog element with the `dialog` role helps assistive technology identify the dialog's content as being grouped and separated from the rest of the page content. However, adding `role="dialog"` alone is not sufficient to make a dialog accessible. Additionally, the following needs to be done: - -- The dialog must be properly labeled -- Keyboard focus must be managed correctly - -The sections below describe how these two requirements can be met. - -### Labeling - -Even though it is not required for the dialog itself to be able to receive focus, it still needs to be labeled. The label given to the dialog will provide contextual information for the interactive controls inside the dialog. In other words, the dialog's label acts like a grouping label for the controls inside it (similar to how a `<legend>` element provides a grouping label for the controls inside a `<fieldset>` element). - -If a dialog already has a visible title bar, the text inside that bar can be used to label the dialog itself. The best way to achieve this is by using the [`aria-labelledby`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-labelledby) attribute to the `role="dialog"` element. Additionally, if the dialog contains additional descriptive text besides the dialog title, this text can be associated with the dialog using the [`aria-describedby`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-describedby) attribute. This approach is shown in the code snippet below: - -```html -<div - role="dialog" - aria-labelledby="dialog1Title" - aria-describedby="dialog1Desc"> - <h2 id="dialog1Title">Your personal details were successfully updated</h2> - <p id="dialog1Desc"> - You can change your details at any time in the user account section. - </p> - <button>Close</button> -</div> -``` - -> [!NOTE] -> Keep in mind that a dialog's title and description text do not have to be focusable in order to be perceived by screen readers operating in a non-virtual mode. The combination of the ARIA dialog role and labeling techniques should make the screen reader announce the dialog's information when focus is moved into it. - -### Required JavaScript features - -#### Focus management - -A dialog has particular requirements for how keyboard focus should be managed: - -- Dialogs should always have at least one focusable control. For many dialogs, there will be a button like "Close", "OK" or "Cancel". In addition to the needed control, dialogs can contain any number of focusable elements, even entire forms or other container widgets like tabs. -- When the dialog appears on the screen, keyboard focus (whose control depends upon the dialog's purpose) should be moved to the default focusable control inside the dialog. For dialogs that only provide a basic message, it could be an "OK" button. For dialogs containing a form it could be the first field in the form. -- After the dialog is dismissed, keyboard focus should be moved back to where it was before it moved into the dialog. Otherwise the focus can be dropped to the beginning of the page. -- For most dialogs, the expected behavior is that the dialog's tab order _wraps_, which means that when the user tabs through the focusable elements in the dialog, the first focusable element will be focused after the last one has been reached. In other words, the tab order should be contained within and by the dialog. -- If the dialog can be moved or resized, ensure that these actions must be performable by keyboard users as well as mouse users. Similarly, if a dialog provides special features like toolbars or context menus, these must be reachable and operable by keyboard users as well. -- Dialogs can be modal or non-modal. When a _modal_ dialog appears on the screen, it's not possible to interact with any page content outside the dialog. In other words, the main application UI or page content is considered to be temporarily disabled as long as the modal dialog is showing. For _non-modal_ dialogs it is still possible to interact with content outside of the dialog while the dialog is showing. Note that for non-modal dialogs there will have to be a global keyboard shortcut that allows focus to be moved between opened dialogs and the main page. - -### Associated ARIA roles, states, and properties - -- [`aria-labelledby`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-labelledby) - - : Use this attribute to label the dialog. Often, the value of the `aria-labelledby` attribute will be the id of the element used to title the dialog. -- [`aria-describedby`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-describedby) - - : Use this attribute to describe the contents of the dialog. - -### Possible effects on user agents and assistive technology - -When the `dialog` role is used, the user agent should do the following: - -- Expose the element as a dialog in the operating system's accessibility API. - -When the dialog is correctly labeled and focus is moved to an element (often an interactive element, such as a button) inside the dialog, screen readers should announce the dialog's accessible role, name and optionally description, along with announcing the focused element. - -> [!NOTE] -> Opinions may differ on how assistive technology should handle this technique, and the order of announcements may differ depending on the assistive technology used. The information provided above is one of those opinions and may change as the specification is defined. - -## Examples - -### A dialog containing a form - -```html -<div - role="dialog" - aria-labelledby="dialog1Title" - aria-describedby="dialog1Desc"> - <h2 id="dialog1Title">Subscription Form</h2> - <p id="dialog1Desc">We will not share this information with third parties.</p> - <form> - <p> - <label for="firstName">First Name</label> - <input id="firstName" type="text" /> - </p> - <p> - <label for="lastName">Last Name</label> - <input id="lastName" type="text" /> - </p> - <p> - <label for="interests">Interests</label> - <textarea id="interests"></textarea> - </p> - <p> - <input type="checkbox" id="autoLogin" name="autoLogin" /> - <label for="autoLogin">Auto-login?</label> - </p> - <p> - <input type="submit" value="Save Information" /> - </p> - </form> -</div> -``` - -#### Working Examples - -- [jQuery-UI Dialog](https://jqueryui.com/dialog/) - -### Notes - -> [!NOTE] -> While it is possible to prevent keyboard users from moving focus to elements outside of the dialog, screen reader users may still be able to navigate to that content using their screen reader's virtual cursor. -> It is important for developers to ensure that content outside of the modal dialog is inaccessible to all users while the modal dialog is active. - -## Specifications - -{{Specifications}} - -## See also - -- [ARIA: alertdialog role](/en-US/docs/Web/Accessibility/ARIA/Roles/alertdialog_role) -- {{HTMLElement('dialog', 'The HTML <code>&lt;dialog&gt;</code> element')}} diff --git a/files/en-us/web/accessibility/aria/roles/directory_role/index.md b/files/en-us/web/accessibility/aria/roles/directory_role/index.md deleted file mode 100644 index 357014652ead1b1..000000000000000 --- a/files/en-us/web/accessibility/aria/roles/directory_role/index.md +++ /dev/null @@ -1,32 +0,0 @@ ---- -title: "ARIA: directory role" -slug: Web/Accessibility/ARIA/Roles/directory_role -page-type: aria-role -status: - - deprecated -spec-urls: https://w3c.github.io/aria/#directory ---- - -{{AccessibilitySidebar}} - -The `directory` role was for a list of references to members of a group, such as a static table of contents. - -> [!WARNING] -> The `directory` role was deprecated in ARIA 1.2 - -## Description - -A directory is a static table of contents, whether linked or unlinked. This includes tables of contents built with lists, including nested lists. Dynamic tables of contents, however, might use a tree role instead. - -The deprecated `directory` role was used for lists of references to members of a group, such as a static table of contents. -Use the [`list`](/en-US/docs/Web/Accessibility/ARIA/Roles/list_role) role instead. Or, better yet, use the {{HTMLElement('ul')}} or {{HTMLElement('ol')}} elements, as using `directory` does not provide any additional benefits to assistive technology users. - -## Specifications - -{{Specifications}} - -## See also - -- [The `list` role](/en-US/docs/Web/Accessibility/ARIA/Roles/list_role) -- The {{HTMLElement('ul')}} element -- The {{HTMLElement('ol')}} element diff --git a/files/en-us/web/accessibility/aria/roles/document_role/index.md b/files/en-us/web/accessibility/aria/roles/document_role/index.md deleted file mode 100644 index 434b2247a577175..000000000000000 --- a/files/en-us/web/accessibility/aria/roles/document_role/index.md +++ /dev/null @@ -1,75 +0,0 @@ ---- -title: "ARIA: document role" -slug: Web/Accessibility/ARIA/Roles/document_role -page-type: aria-role -spec-urls: https://w3c.github.io/aria/#document ---- - -{{AccessibilitySidebar}} - -The `document` role is for focusable content within complex composite [widgets](/en-US/docs/Web/Accessibility/ARIA/Roles/widget_role) or [applications](/en-US/docs/Web/Accessibility/ARIA/Roles/application_role) for which assistive technologies can switch reading context back to a reading mode. - -## Description - -The `document` role is for the top container containing content that assistive technology users may want to browse in a reading mode. Only useful on focusable sections within complex composite [widgets](/en-US/docs/Web/Accessibility/ARIA/Roles/widget_role) or [applications](/en-US/docs/Web/Accessibility/ARIA/Roles/application_role), the `document` role informs assistive technologies to the reading context back to a reading mode: The `document` role tells assistive technologies with reading or browse modes to use the document mode to read the content contained within this element. - -```html -<div role="dialog"> - … - <div id="InfoText" role="document" tabindex="0"> - <p>Some informational text goes here.</p> - </div> - … - <button>Close</button> -</div> -``` - -This example shows a [dialog](/en-US/docs/Web/Accessibility/ARIA/Roles/dialog_role), a complex composite widget role, with some controls and a section with some informational text that the assistive technology user can go into reading mode when tabbed to. - -By default, web pages are treated as documents; assistive technologies (AT) enter browse or read mode when entering a new web page. This mode can be altered through various roles, including the widget and application roles. The `document` role brings the AT back into browse or read mode. - -Generally placed within an application role or other interactive widget role, the `document` role is used to indicate a section of a complex composite widget that an assistive technology user should read using its browse or virtual reading mode, if available. - -Because ATs with reading mode default to that mode for all elements except for those with a widget or application role set, document role is only useful for focusable elements within a widget or application that should be read as static rich text. Adding `role="document"` and `tabindex="0"` to the element containing the text within a widget enables the screen reader user to press the Tab key to place focus on the document element and read the text with the screen reader's reading cursor. - -Assistive technologies should switch context back to document mode, possibly intercepting from controls rewired for the parent's dynamic context, re-enabling the standard input events, such as Up or Down arrow keyboard events, to control the reading cursor. - -In contrast to the [`article`](/en-US/docs/Web/Accessibility/ARIA/Roles/article_role) role, the `document` role does not have any relation to other elements with a document role, it merely has a relationship to the containing composite widget. An article can have associated articles. - -### Associated WAI-ARIA roles, states, and properties - -- [`aria-expanded`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-expanded) - - - : Include with a value of `true` or `false` if the document element is collapsible, to indicate if the document is currently expanded or collapsed. Other values include the default `undefined` which means the document is not collapsible. - -- tabindex="0" - - : Used to make it focusable so the assistive technology user can tab to it and start reading right away. - -### Keyboard interactions - -The element should be made focusable by setting the `tabindex="0"` attribute / value pair on it. This way, the user can tab to it, reading mode is invoked automatically, and the content can be read right away. - -### Required JavaScript features - -None, except as required by any attributes. For example, if the `document` is collapsible, then the state and the value of `aria-expanded` must be maintained. - -## Examples - -An example is Gmail and the single conversation view. GMail is a web application. When in GMail, most user agent interactions are usurped by the application. However, when the Keyboard focus is set on the starting heading on a single conversation that contains the subject of the conversation, the screen reader user can use the reading mode commands to read through the messages, expand or collapse them, and manipulate them. Once focus returns to the message list either by activating the Back button or pressing an associated keystroke, direct application interaction mode is invoked again, and the user can move to a different conversation in the list with the <kbd>arrow</kbd> keys. - -## Best practices - -Always make sure an item with the document role is focusable, by setting the `tabindex` attribute with a value of 0. That will also include it in the tab order. - -### Added benefits - -The document role is an easy way to indirectly control assistive technology behavior by unambiguously stating that this is content the user should read with standard screen reader commands. - -## Specifications - -{{Specifications}} - -## See also - -- [ARIA: `widget` role](/en-US/docs/Web/Accessibility/ARIA/Roles/widget_role) -- [ARIA: `application` role](/en-US/docs/Web/Accessibility/ARIA/Roles/application_role) diff --git a/files/en-us/web/accessibility/aria/roles/feed_role/index.md b/files/en-us/web/accessibility/aria/roles/feed_role/index.md deleted file mode 100644 index 7777c3e1d54b7fa..000000000000000 --- a/files/en-us/web/accessibility/aria/roles/feed_role/index.md +++ /dev/null @@ -1,90 +0,0 @@ ---- -title: "ARIA: feed role" -slug: Web/Accessibility/ARIA/Roles/feed_role -page-type: aria-role -spec-urls: https://w3c.github.io/aria/#feed ---- - -{{AccessibilitySidebar}} - -A `feed` is a dynamic scrollable `list` of `articles` in which articles are added to or removed from either end of the list as the user scrolls. A `feed` enables screen readers to use the browse mode reading cursor to both read and scroll through a stream of rich content that may continue scrolling infinitely by loading more content as the user reads. - -```html -<section role="feed" aria-busy="false"> - … - <article aria-posinset="427" aria-setsize="-1">…</article> - <article aria-posinset="428" aria-setsize="-1">…</article> - <article aria-posinset="429" aria-setsize="-1">…</article> - … -</section> -``` - -## Description - -A `feed` is a type of [`list`](/en-US/docs/Web/Accessibility/ARIA/Roles/list_role), the containing role for scrollable [`articles`](/en-US/docs/Web/Accessibility/ARIA/Roles/article_role) where scrolling may cause articles to be added to the top or end of the list. The role enables assistive technology to use the browse mode reading cursor to both read and scroll through a stream of rich content that may continue scrolling infinitely by loading more content as the user reads. Examples include an RSS feed, news feeds, social media feeds like Facebook, Instagram or Mastodon, or even a list of related products on an e-commerce page. These streams can be limited or infinite, loading more content as the user scrolls. Implementing the `feed` pattern allows a screen reader to reliably read and trigger the loading of feed content while in reading mode. - -Unlike the document structure elements that represent static HTML elements, the `feed` role requires specific interactions and implementation of keyboard navigation. The `feed` is a container element whose children are {{HTMLElement('article')}}s or have role `article`. Each article within a feed should be focusable, with tabindex of 0 or -1. An article should be scrolled into view when it, or a descendant element, receives focus. If the addition of articles occupies the main browser thread, make sure to set `aria-busy="true"` on the feed itself, and make sure to set it back to `false` when processing ends, or the user may not see the updates. - -If the number of articles is known, set [`aria-setsize`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-setsize) on the articles themselves. However, if the total number is extremely large, indefinite, or changes often, set `aria-setsize="-1"` to indicate that the size of the feed is not known. - -Another feature of the feed pattern is skim reading: Articles within a feed can contain both an accessible name with the [`aria-label`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-label) and a description with an `aria-describedby`, suggesting to screen readers which elements to speak after the label when navigating by article. By identifying the elements inside an article that provide the title and the primary content, assistive technologies can provide functions that enable users to jump from article to article and efficiently discern which articles they want to read. - -The feed pattern enables reliable assistive technology reading mode interaction by establishing the following interoperability agreement between the web page and assistive technologies: - -In the context of a feed, the web page code is responsible for: - -- Appropriate visual scrolling of the content based on which article contains DOM focus. -- Loading or removing feed articles based on which article contains DOM focus. - -### Keyboard interactions - -Supporting the following, or a similar, interface is recommended when focus is inside the feed: - -- <kbd>Page Down</kbd>: Move focus to next article. -- <kbd>Page Up</kbd>: Move focus to previous article. -- <kbd>Control + End</kbd>: Move focus to the first focusable element after the feed. -- <kbd>Control + Home</kbd>: Move focus to the first focusable element before the feed. - -If a feed is nested within a feed, such as a comments feed within a feed of blog posts, the convention is to tab into the nested feed with the <kbd>Tab</kbd> key and to provide another key, such as <kbd>Alt + Page Down</kbd>, to navigate from an 'outer' article to the first item in that article's nested feed. Navigate between the nested feed and main feed with <kbd>Control + End</kbd>, moving focus from the inner feed to the next article in the outer feed. - -### <abbr title="Accessible Rich Internet Applications">WAI-ARIA</abbr> roles, states, and properties - -- [`aria-label`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-label) - - - : If the feed has no visible title, the `feed` element has a label specified with `aria-label`. If it does, see `aria-labelledby`. - -- [`aria-labelledby`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-labelledby) - - - : If the feed has a visible title, the `feed` element has `aria-labelledby` referring to the element containing the title. If not, add an `aria-label`. - -- [`aria-busy`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-busy) - - - : When busy, such as when articles are being added or removed from the `feed`, set `aria-busy="true"` during the update operation. Make sure it's reset to `false` when the operation is complete or the changes may not become visible. - -- article - - : Each section of content in a feed should be contained in an `<article>` or element with role [`article`](/en-US/docs/Web/Accessibility/ARIA/Roles/article_role). Each `article` should have an `aria-labelledby` referring to the article title or other child that can serve as a distinguishing label. Each article should preferably have `aria-describedby` referring to one or more elements inside the article that serve as the primary content of the article. Each `article` element has [`aria-posinset`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-posinset) set to a value that represents its position in the feed and an [`aria-setsize`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-setsize) set to a value that represents either the total number of articles that have been loaded or the total number in the feed, depending on which value is more helpful to users. If the total number in the feed is not known, set `aria-setsize="-1"`. - -### Required JavaScript features - -None, except as required by any attributes. For example, setting [`aria-busy`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-busy) to `true` during the update operation if needed, and then to `false` upon completion. - -Note: It is the author's responsibility to apply the "above" keyboard behavior. - -## Examples - -[Example Implementation of Feed Pattern](https://www.w3.org/WAI/ARIA/apg/patterns/feed/examples/feed/) - -## Best practices - -To ensure good user experience, avoid inserting or removing articles in the middle of a `feed`, load new articles before the user has reached the end of the feed, and provide keyboard commands for moving focus among articles so that keyboard users can navigate through your feed. See [Keyboard interactions](#keyboard_interactions). - -## Specifications - -{{Specifications}} - -## See also - -- The HTML {{HTMLElement('article')}} element -- The {{HTMLElement('ul')}} unordered list element -- [ARIA: `article` role](/en-US/docs/Web/Accessibility/ARIA/Roles/article_role) -- [ARIA: `list` role](/en-US/docs/Web/Accessibility/ARIA/Roles/list_role) diff --git a/files/en-us/web/accessibility/aria/roles/figure_role/index.md b/files/en-us/web/accessibility/aria/roles/figure_role/index.md deleted file mode 100644 index dfc6beffcd7addd..000000000000000 --- a/files/en-us/web/accessibility/aria/roles/figure_role/index.md +++ /dev/null @@ -1,117 +0,0 @@ ---- -title: "ARIA: figure role" -slug: Web/Accessibility/ARIA/Roles/figure_role -page-type: aria-role -spec-urls: https://w3c.github.io/aria/#figure ---- - -{{AccessibilitySidebar}} - -The ARIA `figure` role can be used to identify a figure inside page content where appropriate semantics do not already exist. A figure is generally considered to be one or more images, code snippets, or other content that puts across information in a different way to a regular flow of text. - -## Description - -A `figure` is a perceivable section of content that typically contains a graphical document, images, code snippets, or example text. The parts of a figure MAY be user-navigable. Any content that should be grouped together and consumed as a figure (which could include images, video, audio, code snippets, or other content) can be identified as a figure using `role="figure"`. - -```html -<div role="figure" aria-labelledby="caption"> - <img src="image.png" alt="put image description here" /> - <p id="caption">Figure 1: The caption</p> -</div> -``` - -In the above example, we have a figure that consists of two separate content items — an image and a caption. This is wrapped by a {{htmlelement("div")}} element that identifies the content as a figure using `role="figure"`. - -For HTML, use the {{HTMLElement('figure')}} and {{HTMLElement('figcaption')}} elements. The figcaption will serve as the accessible name for the figure. When not using HTML, or when retrofitting legacy HTML, use the [`aria-labelledby`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-labelledby) on the figure, pointing to the figure's caption. -If there is no visible caption, [`aria-label`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-label) can be used. - -```html -<div role="figure" aria-labelledby="figure-1"> - … - <p id="figure-1">Text that describes the figure.</p> -</div> -``` - -- Use `aria-labelledby` when the text is a concise label. -- Use [`aria-describedby`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-describedby) when the text is a longer description. -- Use [`aria-label`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-label) when there is no visible figure caption. - -This can be done semantically, without ARIA, with HTML's {{HTMLElement('figure')}} element along with {{HTMLElement('figcaption')}}. - -```html -<figure> - <img src="image.png" alt="put image description here" /> - <figcaption>Figure 1: The caption</figcaption> -</figure> -``` - -> [!NOTE] -> If at all possible in your work, you should use the appropriate semantic HTML elements to mark up a figure and its caption — {{htmlelement("figure")}} and {{htmlelement("figcaption")}}. - -### Associated WAI-ARIA roles, states, and properties - -- [`aria-describedby`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-describedby) - - : The id of an element containing reference text serving as a caption. -- [`aria-labelledby`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-labelledby) - - : The id of an element containing text serving as a label. -- [`aria-label`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-label) - - : If there is no element containing text that could serve as a label, you can add the label directly as a value on the `aria-label` on the element with the `figure` role or on the `<figure>` element. - -### Keyboard interactions - -No role specific keyboard interactions. - -### Required JavaScript features - -No role specific JavaScript requirements. If you don't have control over the HTML semantics, you can improve the accessibility of HTML by adding these roles and properties with JavaScript. - -## Examples - -We could extend the initial example on the page to also identify a paragraph that provides a descriptive label for the figure by referencing its ID in `aria-labelledby`: - -```html -<div role="figure" aria-labelledby="figure-1"> - <img - src="diagram.png" - alt="diagram showing the four layers of awesome and their relative priority order — - music, cats, nature, and ice cream" /> - <pre> -` - let awesome = ['music', 'cats', 'nature', 'ice cream']; - `</pre - > - <p id="figure-1">Figure 1: The four layers of awesome.</p> -</div> -``` - -## Best practices - -Only use `role="figure"` if you have to — for example if you don't have control over your HTML but are able to improve accessibility dynamically after the fact with JavaScript. - -If at all possible, you should use the appropriate semantic HTML elements to mark up a figure and its caption — {{htmlelement("figure")}} and {{htmlelement("figcaption")}}. For example, our above example should be rewritten as follows: - -```html -<figure> - <img - src="diagram.png" - alt="diagram showing the four layers of awesome and their relative priority order — - music, cats, nature, and ice cream" /> - <pre> -` - let awesome = ['music', 'cats', 'nature', 'ice cream']; - `</pre - > - <figcaption>Figure 1: The four layers of awesome.</figcaption> -</figure> -``` - -## Specifications - -{{Specifications}} - -## See also - -- [Accessibility Object Model](https://wicg.github.io/aom/spec/) -- [ARIA in HTML](https://w3c.github.io/html-aria/) -- [HTML `<figure>` element](/en-US/docs/Web/HTML/Element/figure) -- [HTML `<figcaption>` element](/en-US/docs/Web/HTML/Element/figcaption) diff --git a/files/en-us/web/accessibility/aria/roles/form_role/index.md b/files/en-us/web/accessibility/aria/roles/form_role/index.md deleted file mode 100644 index ac40622a4c643db..000000000000000 --- a/files/en-us/web/accessibility/aria/roles/form_role/index.md +++ /dev/null @@ -1,131 +0,0 @@ ---- -title: "ARIA: form role" -slug: Web/Accessibility/ARIA/Roles/form_role -page-type: aria-role -spec-urls: - - https://w3c.github.io/aria/#form - - https://www.w3.org/WAI/ARIA/apg/patterns/landmarks/examples/form.html ---- - -{{AccessibilitySidebar}} - -The `form` role can be used to identify a group of elements on a page that provide equivalent functionality to an HTML form. The form is not exposed as a landmark region unless it has an [accessible name](/en-US/docs/Glossary/Accessible_name). - -```html -<div role="form" id="contact-info" aria-label="Contact information"> - <!-- form content --> -</div> -``` - -This is a form that collects and saves a user's contact information. - -> [!WARNING] -> Use an HTML {{htmlelement("form")}} element to contain your form controls, rather than the ARIA `form` role, unless you have a very good reason. -> The HTML `<form>` element is sufficient to tell assistive technologies that there is a form. - -## Description - -A `form` [landmark](/en-US/docs/Web/Accessibility/ARIA/Roles#3._landmark_roles) identifies a region of content that contains a collection of items and objects that, as a whole, combine to create a form when no other named landmark is appropriate (e.g. [`main`](/en-US/docs/Web/Accessibility/ARIA/Roles/main_role) or [`search`](/en-US/docs/Web/Accessibility/ARIA/Roles/search_role)). - -> [!NOTE] -> Using the {{HTMLElement('form')}} element will automatically communicate a section of content as a `form` landmark, if it is provided an accessible name. Developers should always prefer using the correct semantic HTML element over using ARIA. - -Use the HTML {{HTMLElement('form')}} element if possible. The `<form>` element defines a `form` landmark when it has an accessible name (e.g. [`aria-labelledby`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-labelledby), [`aria-label`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-label) or [`title`](/en-US/docs/Web/HTML/Global_attributes/title)). Make sure to have a unique label on each form in a document to help users understand the purpose of the form. This label should be visible to all users, not just assistive technology users. Use the `search` landmark instead of the `form` landmark when the form is used for search functionality. - -Use the `role="form"` to identify a region of the page; do not use it to identify every form field. Even if you are using the form landmark instead of `<form>`, you are encouraged to use native HTML form controls like {{HTMLElement('button')}}, {{HTMLElement('input')}}, {{HTMLElement('select')}}, and {{HTMLElement('textarea')}}. - -### Associated WAI-ARIA Roles, States, and Properties - -No role specific states or properties. - -### Keyboard Interactions - -No role specific keyboard interactions - -### Required JavaScript features - -- `onsubmit` - - : The onSubmit event handler handles the event raised when the form is submitted. Anything that is not a `<form>` cannot be submitted, therefore you would have to use JavaScript to build an alternative data submission mechanism, for example with {{domxref("Window/fetch", "fetch()")}}. - -## Examples - -```html -<div role="form" id="send-comment" aria-label="Add a comment"> - <label for="username">Username</label> - <input - id="username" - name="username" - autocomplete="nickname" - autocorrect="off" - type="text" /> - - <label for="email">Email</label> - <input - id="email" - name="email" - autocomplete="email" - autocapitalize="off" - autocorrect="off" - spellcheck="false" - type="text" /> - - <label for="comment">Comment</label> - <textarea id="comment" name="comment"></textarea> - - <input value="Comment" type="submit" /> -</div> -``` - -It is recommended to use `<form>` instead. - -```html -<form id="send-comment" aria-label="Add a comment">…</form> -``` - -## Accessibility concerns - -### Use sparingly - -[Landmark roles](/en-US/docs/Web/Accessibility/ARIA/Roles#3._landmark_roles) are intended to identify larger overall sections of the document. Using too many landmark roles can create "noise" in screen readers, making it difficult to understand the overall layout of the page. - -### Inputs are not forms - -You do not need to declare `role="form"` on every [form element](/en-US/docs/Web/HTML/Element#forms) (inputs, text areas, selects, etc.). It should be declared on the HTML element that wraps the form elements. Ideally, use the {{HTMLElement('form')}} element as the wrapping element and do not declare `role="form"`. - -### Search - -If a form is used to search, you should use the more specialized [`role="search"`](/en-US/docs/Web/Accessibility/ARIA/Roles/search_role) value. - -### Labeling landmarks - -Each {{HTMLElement('form')}} element and form `role` that needs to be exposed as a landmark must be given an accessible name. This name will allow an assistive technology user to be able to quickly understand the purpose of the form landmark. - -Use an `aria-labelledby`, `aria-label` or `title` on the same element that was given the `role="form"` to provide it an accessible name. - -#### Using `role="form"` - -```html -<div role="form" id="gift-cards" aria-label="Purchase a gift card"> - <!-- form content --> -</div> -``` - -#### Redundant descriptions - -Screen readers will announce the type of role the landmark is. Because of this, you do not need to describe what the landmark is in its label. For example, a declaration of `role="form"` with an of `aria-label="Contact form"` may be announced redundantly as, "contact form form". - -## Best practices - -### Prefer HTML - -Using the {{HTMLElement('form')}} element will automatically communicate a section has a role of `form`. If at all possible, prefer using it instead. - -## Specifications - -{{Specifications}} - -## See also - -- The {{HTMLElement('form')}} element -- The {{HTMLElement('legend')}} element -- [form (role): Accessible Rich Internet Applications (WAI-ARIA) 1.1](https://www.w3.org/TR/wai-aria/#form) diff --git a/files/en-us/web/accessibility/aria/roles/generic_role/index.md b/files/en-us/web/accessibility/aria/roles/generic_role/index.md deleted file mode 100644 index 11a23b395baefed..000000000000000 --- a/files/en-us/web/accessibility/aria/roles/generic_role/index.md +++ /dev/null @@ -1,44 +0,0 @@ ---- -title: "ARIA: generic role" -slug: Web/Accessibility/ARIA/Roles/generic_role -page-type: aria-role -spec-urls: https://w3c.github.io/aria/#generic ---- - -{{AccessibilitySidebar}} - -The `generic` role creates a nameless container element which has no semantic meaning on its own. - -> [!NOTE] -> The `generic` role is the implicit role of generic elements used by user agents. It is included here for completeness of documentation. It should not be used by web authors. - -## Description - -While ARIA is primarily used to express semantics, there are some elements that shouldn't expose a semantic name to assistive technologies. The `generic` role indicates an element's role is equivalent to that of the non-semantic {{HTMLElement('div')}} and {{HTMLElement('span')}} elements. - -The `generic` role is intended for use as the implicit role of generic elements in host languages for use by user agents only; not for use by developers. Instead, to remove implicit accessibility semantics, use [`presentation`](/en-US/docs/Web/Accessibility/ARIA/Roles/presentation_role) or `none`, the {{HTMLElement('div')}} and {{HTMLElement('span')}} elements that have no semantic meaning, or semantic container roles such as [`group`](/en-US/docs/Web/Accessibility/ARIA/Roles/group_role) to semantically group descendants in a named container. - -Like an element with role `presentation`, an element with `role="generic"` can provide a limited number of accessible states and properties for its descendants, such as [`aria-live`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-live) attributes. However, unlike elements with role `presentation`, `generic` elements are exposed in accessibility APIs so that assistive technologies can gather certain properties such as layout and bounds. - -Because the generic role is nameless, the [`aria-labelledby`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-labelledby) and [`aria-label`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-label) attributes are prohibited. Because the role is generic, the [`aria-roledescription`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-roledescription) and [`aria-brailleroledescription`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-brailleroledescription) attributes are also prohibited. - -> [!NOTE] -> The element with `role="generic"` should not have an accessible name or role description. - -### Associated WAI-ARIA roles, states, and properties - -None. If a global ARIA state and property is set, `generic` or `none` will be ignored, and the implicit role of the element will be used. - -## Examples - -This role is for use by user agents and not by developers. As such, no appropriate example exists. - -## Specifications - -{{Specifications}} - -## See also - -- HTML {{HTMLElement('div')}} and {{HTMLElement('span')}} elements -- [`presentation`](/en-US/docs/Web/Accessibility/ARIA/Roles/presentation_role) roles such as -- [`group`](/en-US/docs/Web/Accessibility/ARIA/Roles/group_role) role diff --git a/files/en-us/web/accessibility/aria/roles/grid_role/index.md b/files/en-us/web/accessibility/aria/roles/grid_role/index.md deleted file mode 100644 index 716123579306ed3..000000000000000 --- a/files/en-us/web/accessibility/aria/roles/grid_role/index.md +++ /dev/null @@ -1,387 +0,0 @@ ---- -title: "ARIA: grid role" -slug: Web/Accessibility/ARIA/Roles/grid_role -page-type: aria-role -spec-urls: https://w3c.github.io/aria/#grid ---- - -{{AccessibilitySidebar}} - -The grid role is for a widget that contains one or more rows of cells. The position of each cell is significant and can be focused using keyboard input. - -## Description - -The `grid` role is a composite widget containing a collection of one or more rows with one or more cells where some or all cells in the grid are focusable by using methods of two-dimensional navigation, such as directional arrow keys. - -```html -<table role="grid" aria-labelledby="id-select-your-seat"> - <caption id="id-select-your-seat"> - Select your seat - </caption> - <tbody role="presentation"> - <tr role="presentation"> - <td></td> - <th>Row A</th> - <th>Row B</th> - </tr> - <tr> - <th scope="row">Aisle 1</th> - <td tabindex="0"> - <button id="1a" tabindex="-1">1A</button> - </td> - <td tabindex="-1"> - <button id="1b" tabindex="-1">1B</button> - </td> - <!-- More Columns --> - </tr> - <tr> - <th scope="row">Aisle 2</th> - <td tabindex="-1"> - <button id="2a" tabindex="-1">2A</button> - </td> - <td tabindex="-1"> - <button id="2b" tabindex="-1">2B</button> - </td> - <!-- More Columns --> - </tr> - </tbody> -</table> -``` - -A grid widget contains one or more rows with one or more cells of thematically related interactive content. While it does not imply a specific visual presentation, it implies a relationship among elements. Uses fall into two categories: presenting tabular information (data grids) and grouping other widgets (layout grids). Even though both data grids and layout grids employ the same ARIA roles, states, and properties, differences in their content and purpose surface factors that are important to consider in keyboard interaction design. See [ARIA Authoring Practices Guide](https://www.w3.org/WAI/ARIA/apg/patterns/grid/) for more details. - -Cell elements have the role [`gridcell`](/en-US/docs/Web/Accessibility/ARIA/Roles/gridcell_role), unless they are a row or column header, in which case, the elements are [`rowheader`](/en-US/docs/Web/Accessibility/ARIA/Roles/rowheader_role) and [`columnheader`](/en-US/docs/Web/Accessibility/ARIA/Roles/columnheader_role), respectively. Cell elements need to be owned by elements with a [`row`](/en-US/docs/Web/Accessibility/ARIA/Roles/row_role) role. Rows can be grouped using the [`rowgroup`](/en-US/docs/Web/Accessibility/ARIA/Roles/rowgroup_role) role. - -If the grid is used as an interactive widget, [keyboard interactions](#keyboard_interactions) need to be implemented. - -### Associated ARIA roles, states, and properties - -#### Roles - -- [treegrid](/en-US/docs/Web/Accessibility/ARIA/Roles/treegrid_role) (subclass) - - : If a grid has columns that can expanded or collapsed, a treegrid can be used. -- [row](/en-US/docs/Web/Accessibility/ARIA/Roles/row_role) - - : A row inside the grid. -- [rowgroup](/en-US/docs/Web/Accessibility/ARIA/Roles/rowgroup_role) - - : A group containing one or multiple [row](/en-US/docs/Web/Accessibility/ARIA/Roles/row_role)s. - -#### States and properties - -- [aria-level](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-level) - - : Indicates the hierarchical level of the grid within other structures. -- [aria-multiselectable](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-multiselectable) - - : If `aria-multiselectable` is set to `true`, multiple items in the grid can be selected. The default value is `false`. -- [aria-readonly](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-readonly) - - : If the user can navigate the grid but not change the value or values of the grid, the [`aria-readonly`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-readonly) should be set to `true`. The default value is `false`. - -> [!NOTE] -> For many use cases, an HTML {{HTMLElement('table')}} element is sufficient as it and the various table elements already include many ARIA roles. - -### Keyboard interactions - -When a keyboard user encounters a grid, they navigate the rows and columns using the <kbd>left</kbd>, <kbd>right</kbd>, <kbd>top</kbd> and <kbd>down</kbd> keys. To activate the interactive component, they will use the <kbd>return</kbd> and <kbd>space</kbd> keys. - -| Key | Action | -| --------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| <kbd>→</kbd> | Moves focus one cell to the right. Optionally (layout grids), if focus is on the right-most cell in the row, focus may move to the first cell in the following row. If focus is on the last cell in the grid, focus does not move. | -| <kbd>←</kbd> | Moves focus one cell to the left. Optionally (layout grids), if focus is on the left-most cell in the row, focus may move to the last cell in the previous row. If focus is on the first cell in the grid, focus does not move. | -| <kbd>↓</kbd> | Moves focus one cell down. Optionally (layout grids), if focus is on the bottom cell in the column, focus may move to the top cell in the following column. If focus is on the last cell in the grid, focus does not move. | -| <kbd>↑</kbd> | Moves focus one cell up. Optionally (layout grids), if focus is on the top cell in the column, focus may move to the bottom cell in the previous column. If focus is on the first cell in the grid, focus does not move. | -| <kbd>Page Down</kbd> | Moves focus down an author-determined number of rows, typically scrolling so the bottom row in the currently visible set of rows becomes one of the first visible rows. If focus is in the last row of the grid, focus does not move. | -| <kbd>Page Up</kbd> | Moves focus up an author-determined number of rows, typically scrolling so the top row in the currently visible set of rows becomes one of the last visible rows. If focus is in the first row of the grid, focus does not move. | -| <kbd>Home</kbd> | Moves focus to the first cell in the row that contains focus. | -| <kbd>End</kbd> | Moves focus to the last cell in the row that contains focus. | -| <kbd>ctrl</kbd> + <kbd>Home</kbd> | Moves focus to the first cell in the first row. | -| <kbd>ctrl</kbd> + <kbd>End</kbd> | Moves focus to the last cell in the last row. | - -If cells, rows, or columns can be selected, the following key combination are commonly used: - -| Key combination | Action | -| ----------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| <kbd>ctrl</kbd> + <kbd>Space</kbd> | Select the column that contains the focus. | -| <kbd>shift</kbd> + <kbd>Space</kbd> | Selects the row that contains the focus. If the grid includes a column with checkboxes to select rows, this key combination can be used to check that box even if the focus is not on the checkbox. | -| <kbd>ctrl</kbd> + <kbd>A</kbd> | Selects all cells. | -| <kbd>shift</kbd> + <kbd>→</kbd> | Extends selection one cell to the right. | -| <kbd>shift</kbd> + <kbd>←</kbd> | Extends selection one cell to the left. | -| <kbd>shift</kbd> + <kbd>↓</kbd> | Extends selection one cell down. | -| <kbd>shift</kbd> + <kbd>↑</kbd> | Extends selection one cell up. | - -## Examples - -### Calendar example - -{{EmbedLiveSample("Calendar_example", "100%", "300")}} - -#### HTML - -```html -<table role="grid" aria-labelledby="calendarheader"> - <caption id="calendarheader"> - September 2018 - </caption> - <thead role="rowgroup"> - <tr role="row"> - <td></td> - <th role="columnheader" aria-label="Sunday">S</th> - <th role="columnheader" aria-label="Monday">M</th> - <th role="columnheader" aria-label="Tuesday">T</th> - <th role="columnheader" aria-label="Wednesday">W</th> - <th role="columnheader" aria-label="Thursday">T</th> - <th role="columnheader" aria-label="Friday">F</th> - <th role="columnheader" aria-label="Saturday">S</th> - </tr> - </thead> - <tbody role="rowgroup"> - <tr role="row"> - <th scope="row" role="rowheader">Week 1</th> - <td>26</td> - <td>27</td> - <td>28</td> - <td>29</td> - <td>30</td> - <td>31</td> - <td role="gridcell" tabindex="-1">1</td> - </tr> - <tr role="row"> - <th scope="row" role="rowheader">Week 2</th> - <td role="gridcell" tabindex="-1">2</td> - <td role="gridcell" tabindex="-1">3</td> - <td role="gridcell" tabindex="-1">4</td> - <td role="gridcell" tabindex="-1">5</td> - <td role="gridcell" tabindex="-1">6</td> - <td role="gridcell" tabindex="-1">7</td> - <td role="gridcell" tabindex="-1">8</td> - </tr> - <tr role="row"> - <th scope="row" role="rowheader">Week 3</th> - <td role="gridcell" tabindex="-1">9</td> - <td role="gridcell" tabindex="-1">10</td> - <td role="gridcell" tabindex="-1">11</td> - <td role="gridcell" tabindex="-1">12</td> - <td role="gridcell" tabindex="-1">13</td> - <td role="gridcell" tabindex="-1">14</td> - <td role="gridcell" tabindex="-1">15</td> - </tr> - <tr role="row"> - <th scope="row" role="rowheader">Week 4</th> - <td role="gridcell" tabindex="-1">16</td> - <td role="gridcell" tabindex="-1">17</td> - <td role="gridcell" tabindex="-1">18</td> - <td role="gridcell" tabindex="-1">19</td> - <td role="gridcell" tabindex="-1">20</td> - <td role="gridcell" tabindex="-1">21</td> - <td role="gridcell" tabindex="-1">22</td> - </tr> - <tr role="row"> - <th scope="row" role="rowheader">Week 5</th> - <td role="gridcell" tabindex="-1">23</td> - <td role="gridcell" tabindex="-1">24</td> - <td role="gridcell" tabindex="-1">25</td> - <td role="gridcell" tabindex="-1">26</td> - <td role="gridcell" tabindex="-1">27</td> - <td role="gridcell" tabindex="-1">28</td> - <td role="gridcell" tabindex="-1">29</td> - </tr> - <tr role="row"> - <th scope="row" role="rowheader">Week 6</th> - <td role="gridcell" tabindex="-1">30</td> - <td>1</td> - <td>2</td> - <td>3</td> - <td>4</td> - <td>5</td> - <td>6</td> - </tr> - </tbody> -</table> -``` - -#### CSS - -```css -table { - margin: 0; - border-collapse: collapse; - font-variant-numeric: tabular-nums; -} - -tbody th, -tbody td { - padding: 5px; -} - -tbody td { - border: 1px solid #000; - text-align: right; - color: #767676; -} - -tbody td[role="gridcell"] { - color: #000; -} - -tbody td[role="gridcell"]:hover, -tbody td[role="gridcell"]:focus { - background-color: #f6f6f6; - outline: 3px solid blue; -} -``` - -#### JavaScript - -```js -const selectables = document.querySelectorAll('table td[role="gridcell"]'); - -selectables[0].setAttribute("tabindex", 0); - -const trs = document.querySelectorAll("table tbody tr"); -let rowIndex = 0; -let colIndex = 0; -let maxRow = trs.length - 1; -let maxCol = 0; - -trs.forEach((row) => { - row.querySelectorAll("td").forEach((el) => { - el.dataset.row = rowIndex; - el.dataset.col = colIndex; - colIndex++; - }); - if (colIndex > maxCol) { - maxCol = colIndex - 1; - } - colIndex = 0; - rowIndex++; -}); - -function moveTo(newRow, newCol) { - const tgt = document.querySelector( - `[data-row="${newRow}"][data-col="${newCol}"]`, - ); - if (tgt?.getAttribute("role") === "gridcell") { - document.querySelectorAll("[role=gridcell]").forEach((el) => { - el.setAttribute("tabindex", "-1"); - }); - tgt.setAttribute("tabindex", "0"); - tgt.focus(); - return true; - } else { - return false; - } -} - -document.querySelector("table").addEventListener("keydown", (event) => { - const col = parseInt(event.target.dataset.col, 10); - const row = parseInt(event.target.dataset.row, 10); - switch (event.key) { - case "ArrowRight": { - const newRow = col === 6 ? row + 1 : row; - const newCol = col === 6 ? 0 : col + 1; - moveTo(newRow, newCol); - break; - } - case "ArrowLeft": { - const newRow = col === 0 ? row - 1 : row; - const newCol = col === 0 ? 6 : col - 1; - moveTo(newRow, newCol); - break; - } - case "ArrowDown": - moveTo(row + 1, col); - break; - case "ArrowUp": - moveTo(row - 1, col); - break; - case "Home": { - if (event.ctrlKey) { - let i = 0; - let result; - do { - let j = 0; - do { - result = moveTo(i, j); - j++; - } while (!result); - i++; - } while (!result); - } else { - moveTo(row, 0); - } - break; - } - case "End": { - if (event.ctrlKey) { - let i = maxRow; - let result; - do { - let j = maxCol; - do { - result = moveTo(i, j); - j--; - } while (!result); - i--; - } while (!result); - } else { - moveTo( - row, - document.querySelector( - `[data-row="${event.target.dataset.row}"]:last-of-type`, - ).dataset.col, - ); - } - break; - } - case "PageUp": { - let i = 0; - let result; - do { - result = moveTo(i, col); - i++; - } while (!result); - break; - } - case "PageDown": { - let i = maxRow; - let result; - do { - result = moveTo(i, col); - i--; - } while (!result); - break; - } - case "Enter": { - console.log(event.target.textContent); - break; - } - } - event.preventDefault(); -}); -``` - -### More examples - -- [Data Grid Examples](https://www.w3.org/WAI/ARIA/apg/example-index/grid/dataGrids.html) -- [Layout Grids Examples](https://www.w3.org/WAI/ARIA/apg/example-index/grid/LayoutGrids.html) -- [W3C/WAI Tutorial: Tables](https://www.w3.org/WAI/tutorials/tables/) - -## Accessibility concerns - -Even if the keyboard use is properly implemented, some users might not be aware that they have to use the arrow keys. Make sure that the functionality and interaction needed can be best achieved using the grid role. - -## Specifications - -{{Specifications}} - -## See also - -- [ARIA `composite` role](/en-US/docs/Web/Accessibility/ARIA/Roles/composite_role) -- [ARIA `table` role](/en-US/docs/Web/Accessibility/ARIA/Roles/table_role) -- [ARIA `treegrid` role](/en-US/docs/Web/Accessibility/ARIA/Roles/treegrid_role) -- [ARIA `row` role](/en-US/docs/Web/Accessibility/ARIA/Roles/row_role) -- [ARIA `rowgroup` role](/en-US/docs/Web/Accessibility/ARIA/Roles/rowgroup_role) -- [ARIA: `gridcell` role](/en-US/docs/Web/Accessibility/ARIA/Roles/gridcell_role) -- [ARIA: `rowheader` role](/en-US/docs/Web/Accessibility/ARIA/Roles/rowheader_role) -- [ARIA: columnheader role](/en-US/docs/Web/Accessibility/ARIA/Roles/columnheader_role) -- {{HTMLElement('table','HTML <code>&lt;table&gt;</code> element')}} -- [`aria-level`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-level) -- [`aria-multiselectable`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-multiselectable) -- [`aria-readonly`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-readonly) diff --git a/files/en-us/web/accessibility/aria/roles/gridcell_role/index.md b/files/en-us/web/accessibility/aria/roles/gridcell_role/index.md deleted file mode 100644 index e4659c171b3a1fa..000000000000000 --- a/files/en-us/web/accessibility/aria/roles/gridcell_role/index.md +++ /dev/null @@ -1,168 +0,0 @@ ---- -title: "ARIA: gridcell role" -slug: Web/Accessibility/ARIA/Roles/gridcell_role -page-type: aria-role ---- - -{{AccessibilitySidebar}} - -The [gridcell role](https://www.w3.org/TR/wai-aria-1.1/#gridcell) is used to make a cell in a [grid](/en-US/docs/Web/Accessibility/ARIA/Roles/grid_role) or [treegrid](/en-US/docs/Web/Accessibility/ARIA/Roles/treegrid_role). It is intended to mimic the functionality of the HTML {{HTMLElement('td')}} element for table-style grouping of information. - -```html -<div role="gridcell">Potato</div> -<div role="gridcell">Cabbage</div> -<div role="gridcell">Onion</div> -``` - -Elements that have `role="gridcell"` applied to them must be the child of an element with a role of [`row`](/en-US/docs/Web/Accessibility/ARIA/Roles/row_role). - -```html -<div role="row"> - <div role="gridcell">Jane</div> - <div role="gridcell">Smith</div> - <div role="gridcell">496-619-5098</div> - … -</div> -``` - -The first rule of ARIA is if a native HTML element or attribute has the semantics and behavior you require, use it instead of re-purposing an element and adding ARIA. Instead use the HTML {{HTMLElement('td')}} element: - -```html -<td>Potato</td> -<td>Cabbage</td> -<td>Onion</td> -``` - -## Description - -### gridcells with dynamically added, hidden, or removed rows and columns - -Any element with a `role="gridcell"` applied to it should use ARIA to describe its order in the table-style grouping, provided the table, grid, or treegrid has the ability to have rows and/or columns dynamically added, hidden, or removed. - -Use [`aria-colindex`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-colindex) to describe a `gridcell`'s order in the list of columns, and [`aria-rowindex`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-rowindex) to describe a gridcell's order in the list of rows. Use [`aria-colcount`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-colcount) and [`aria-rowcount`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-rowcount) on the parent element with [`role="grid"`](/en-US/docs/Web/Accessibility/ARIA/Roles/grid_role) applied to it to set the total number of columns or rows. - -This sample code demonstrates a table-style grouping of information where the third and fourth columns have been removed. [`aria-colindex`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-colindex) is being used to describe the rows' position and allows a person using assistive technology to infer that certain rows have been removed: - -```html -<div role="grid" aria-colcount="6"> - <div role="rowgroup"> - <div role="row"> - <div role="columnheader" aria-colindex="1">First name</div> - <div role="columnheader" aria-colindex="2">Last name</div> - <div role="columnheader" aria-colindex="5">City</div> - <div role="columnheader" aria-colindex="6">Zip</div> - </div> - </div> - <div role="rowgroup"> - <div role="row"> - <div role="gridcell" aria-colindex="1">Debra</div> - <div role="gridcell" aria-colindex="2">Burks</div> - <div role="gridcell" aria-colindex="5">New York</div> - <div role="gridcell" aria-colindex="6">14127</div> - </div> - </div> - … -</div> -``` - -### Describing the position of gridcells when the overall structure is unknown - -In situations where the table-style grouping of content does not provide information about the columns and rows, gridcells must have their positions programmatically described by using [`aria-describedby`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-describedby). The [`id`](/en-US/docs/Web/HTML/Global_attributes/id)s provided for `aria-describedby` should correspond to parent elements intended to be the rows and columns. - -By referencing the parent elements with roles of [`rowheader`](/en-US/docs/Web/Accessibility/ARIA/Roles/rowheader_role) or [`columnheader`](/en-US/docs/Web/Accessibility/ARIA/Roles/columnheader_role) applied to them via `aria-describedby`, it allows assistive technology to understand the position and relationship of the `gridcell` element to the rest of the table-style grouping of content. - -### Interactive grids and treegrids - -#### Editable cells - -Both `<td>` elements and elements with a role of `gridcell` applied to them can be made editable, mimicking functionality similar to editing a spreadsheet. This is done by applying the HTML [`contenteditable` attribute](/en-US/docs/Web/HTML/Global_attributes/contenteditable). - -```html -<td contenteditable="true">Notes</td> - -<div role="gridcell" contenteditable="true">Item cost</div> -``` - -`contenteditable` will make the element it is applied to focusable via the <kbd>Tab</kbd> key. If a gridcell is conditionally toggled into a state where editing is prohibited, toggle [`aria-readonly`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-readonly) on the gridcell element. - -#### Expandable cells - -In a [treegrid](/en-US/docs/Web/Accessibility/ARIA/Roles/treegrid_role), gridcells may be made expandable by toggling the [`aria-expanded`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-expanded) attribute. Note that if this attribute is provided, it applies only to the individual gridcell. - -### Associated WAI-ARIA Roles, States, and Properties - -- `grid` - - : Communicates that a parent element is a table or tree style grouping of information. -- `row` - - : Required to communicate the `gridcell` is part of a row of a table-style grouping of information. -- `columnheader` - - : Specifies which element is the associated column header. -- [`aria-colindex`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-colindex) - - : Identifies the position of an element in relation to the rest of the table-style grouping of information's columns. -- `rowheader` - - : Specifies which element is the associated row header. -- [`aria-rowindex`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-rowindex) - - : Identifies the position of an element in relation to the rest of the table-style grouping of information's rows. - -### Examples - -The following example creates a table-style grouping of information: - -```html -<h3 id="table-title">Jovian gas giant planets</h3> -<div role="grid" aria-describedby="table-title"> - <div role="rowgroup"> - <div role="row"> - <div role="columnheader">Name</div> - <div role="columnheader">Diameter (km)</div> - <div role="columnheader">Length of day (hours)</div> - <div role="columnheader">Distance from Sun (10<sup>6</sup>km)</div> - <div role="columnheader">Number of moons</div> - </div> - </div> - <div role="rowgroup"> - <div role="row"> - <div role="gridcell">Jupiter</div> - <div role="gridcell">142,984</div> - <div role="gridcell">9.9</div> - <div role="gridcell">778.6</div> - <div role="gridcell">67</div> - </div> - </div> - <div role="rowgroup"> - <div role="row"> - <div role="gridcell">Saturn</div> - <div role="gridcell">120,536</div> - <div role="gridcell">10.7</div> - <div role="gridcell">1433.5</div> - <div role="gridcell">62</div> - </div> - </div> -</div> -``` - -## Accessibility concerns - -Support for `gridcell` and certain `gridcell` related ARIA roles and properties have poor support with assistive technologies. If at all possible, use [HTML table markup](/en-US/docs/Web/HTML/Element/table) in their place. - -## Best practices - -The first rule of ARIA is: if a native HTML element or attribute has the semantics and behavior you require, use it instead of re-purposing an element and adding an ARIA role, state or property to make it accessible. As such, it is recommended to use [native HTML table markup](/en-US/docs/Web/HTML/Element/table) instead of recreating a table's form and functionality with ARIA and JavaScript. - -## See also - -- [The Table element](/en-US/docs/Web/HTML/Element/table) -- [ARIA: Grid role](/en-US/docs/Web/Accessibility/ARIA/Roles/grid_role) -- [Grid Role - Maxability](https://www.maxability.co.in/wai-aria-overview/grid-role/) -- [The Table row element](/en-US/docs/Web/HTML/Element/tr) -- [ARIA: row role](/en-US/docs/Web/Accessibility/ARIA/Roles/row_role) -- [Row Role - Maxability](https://www.maxability.co.in/wai-aria-overview/row-role/) -- [aria-rowcount - Maxability](https://www.maxability.co.in/2018/09/07/aria-rowcount-property/) -- [ARIA: rowgroup role](/en-US/docs/Web/Accessibility/ARIA/Roles/rowgroup_role) -- [Rowgroup Role - Maxability](https://www.maxability.co.in/wai-aria-overview/rowgroup-role/) -- [The Table header element](/en-US/docs/Web/HTML/Element/th) -- [Columnheader - Maxability](https://www.maxability.co.in/wai-aria-overview/columnheader-role/) -- [aria-colcount - Maxability](https://www.maxability.co.in/2017/07/26/aria-colcount-property/) -- [The Table Data Cell element](/en-US/docs/Web/HTML/Element/td) -- [gridcell: Accessible Rich Internet Applications (WAI-ARIA) 1.1](https://www.w3.org/TR/wai-aria-1.1/#gridcell) -- [Gridcell Role - Maxability](https://www.maxability.co.in/wai-aria-overview/gridcell-role/) diff --git a/files/en-us/web/accessibility/aria/roles/group_role/index.md b/files/en-us/web/accessibility/aria/roles/group_role/index.md deleted file mode 100644 index c5244d988cdaa0e..000000000000000 --- a/files/en-us/web/accessibility/aria/roles/group_role/index.md +++ /dev/null @@ -1,100 +0,0 @@ ---- -title: "ARIA: group role" -slug: Web/Accessibility/ARIA/Roles/group_role -page-type: aria-role -spec-urls: https://w3c.github.io/aria/#group ---- - -{{AccessibilitySidebar}} - -The `group` role identifies a set of user interface objects that is not intended to be included in a page summary or table of contents by assistive technologies. - -## Description - -Most closely related to HTML's {{HTMLElement('fieldset')}} element, the `group` document structure role is used to identify a set of user interface objects which, as compared to [`region`](/en-US/docs/Web/Accessibility/ARIA/Roles/region_role), is not intended to be included in the page's summary or table of contents. - -The `group` role should be used to form a logical collection of items with related functionality, such as children in a [`tree`](/en-US/docs/Web/Accessibility/ARIA/Roles/tree_role) widget forming a collection of siblings in a hierarchy, or a collection of items having the same container in a [`directory`](/en-US/docs/Web/Accessibility/ARIA/Roles/directory_role). - -When a `group` is used in the context of [`list`](/en-US/docs/Web/Accessibility/ARIA/Roles/list_role), limit the children of the `group` to [`listitem`](/en-US/docs/Web/Accessibility/ARIA/Roles/listitem_role) elements. In this case, it is recommended to use multiple ordered or unordered lists, {{HTMLElement('ol')}} or {{HTMLElement('ul')}}, with nested {{HTMLElement('li')}} children. - -When used in the context of a [`listbox`](/en-US/docs/Web/Accessibility/ARIA/Roles/listbox_role), the only children allowed are {{HTMLElement('option')}} elements. In this case, it is recommended to use {{HTMLElement('select')}}, {{HTMLElement('option')}} and {{HTMLElement('optgroup')}} instead. - -`Group` elements may be nested. - -The `group` role should not be used for major perceivable sections of a page. If a section is significant enough that it should be included in the page's table of contents, use the `region` role or a standard [landmark role](/en-US/docs/Web/Accessibility/ARIA/Roles#3._landmark_roles). - -When the role is added to an element, the browser will send out an accessible group event to assistive technology products, which can then notify the user about it. - -## Examples - -The HTML code example below uses the `group` role with a `tree` view: - -```html -<div id="tree1" role="tree" tabindex="-1"> - <div - id="animals" - class="groupHeader" - role="presentation" - aria-owns="animalGroup" - aria-expanded="true"> - <img role="presentation" tabindex="-1" src="images/treeExpanded.gif" /> - <span role="treeitem" tabindex="0">Animals</span> - </div> - <div id="animalGroup" role="group"> - <div id="birds" role="treeitem"> - <span tabindex="-1">Birds</span> - </div> - <div - id="cats" - class="groupHeader" - role="presentation" - aria-owns="catGroup" - aria-expanded="false"> - <img role="presentation" tabindex="-1" src="images/treeContracted.gif" /> - <span role="treeitem" tabindex="0">Cats</span> - </div> - <div id="catGroup" role="group"> - <div id="siamese" role="treeitem"> - <span tabindex="-1">Siamese</span> - </div> - <div id="tabby" role="treeitem"> - <span tabindex="-1">Tabby</span> - </div> - </div> - </div> -</div> -``` - -The following example uses the `group` role with a drop-down [`menu`](/en-US/docs/Web/Accessibility/ARIA/Roles/menu_role) containing [`menuitem`](/en-US/docs/Web/Accessibility/ARIA/Roles/menuitem_role)s: - -```html -<div role="menu"> - <ul role="group"> - <li role="menuitem">Inbox</li> - <li role="menuitem">Archive</li> - <li role="menuitem">Trash</li> - </ul> - <ul role="group"> - <li role="menuitem">Custom Folder 1</li> - <li role="menuitem">Custom Folder 2</li> - <li role="menuitem">Custom Folder 3</li> - </ul> - <ul role="group"> - <li role="menuitem">New Folder</li> - </ul> -</div> -``` - -This menu could be constructed using {{HTMLElement('select')}} and {{HTMLElement('option')}} elements. In this case, the `group` role would be most similar to the {{HTMLElement('optgroup')}} element. - -## Specifications - -{{Specifications}} - -## See also - -- The {{HTMLElement('fieldset')}} Element -- [ARIA: `section` role](/en-US/docs/Web/Accessibility/ARIA/Roles/section_role) -- [ARIA: `row` role](/en-US/docs/Web/Accessibility/ARIA/Roles/row_role) -- [ARIA: `select` role](/en-US/docs/Web/Accessibility/ARIA/Roles/select_role) -- [ARIA: `toolbar` role](/en-US/docs/Web/Accessibility/ARIA/Roles/toolbar_role) diff --git a/files/en-us/web/accessibility/aria/roles/heading_role/index.md b/files/en-us/web/accessibility/aria/roles/heading_role/index.md deleted file mode 100644 index 5c049c4d6869790..000000000000000 --- a/files/en-us/web/accessibility/aria/roles/heading_role/index.md +++ /dev/null @@ -1,115 +0,0 @@ ---- -title: "ARIA: heading role" -slug: Web/Accessibility/ARIA/Roles/heading_role -page-type: aria-role -spec-urls: - - https://w3c.github.io/aria/#heading - - https://www.w3.org/WAI/ARIA/apg/practices/structural-roles/#when_to_use_structural_roles ---- - -{{AccessibilitySidebar}} - -The `heading` role defines this element as a heading to a page or section, with the [`aria-level`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-level) attribute providing for more structure. - -## Description - -The heading role indicates to assistive technologies that this element should be treated like a heading. Screen readers would read the text and indicate that it is formatted like a heading. In addition, the level tells assistive technologies which part of the page structure this heading represents. A level 1 heading, indicated with `aria-level="1"`, usually indicates the main heading of a page, a level 2 heading, defined with `aria-level="2"` the first subsection, a level 3 is a subsection of that, and so on. - -```html -<div role="heading" aria-level="1">This is a main page heading</div> -``` - -This defines the text in the `<div>` to be the main heading of the page, indicated by being level 1 via the `aria-level` attribute. Opt for using the {{HTMLElement("Heading_Elements", "h1")}} (through {{HTMLElement("Heading_Elements", "h6")}}) element instead. - -```html -<h1>This is a main page heading</h1> -``` - -### Associated WAI-ARIA roles, states, and properties - -- [`aria-level`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-level) - - : The `aria-level` attribute specifies the heading level in the document structure. If no level is present, a value of 2 is the default. - -### Keyboard interactions - -This role does not require any special keyboard navigation. As with any heading, giving it an ID ensures it can be referenced from anchor links, making it accessible via the keyboard. - -### Required JavaScript features - -- Required event handlers - - : None. -- Changing attribute values - - : Usually not required, unless dynamically inserting content. In that case, the newly-added headings need `aria-level` attributes whose values are consistent with the rest of the document structure. - -> [!NOTE] -> Instead of using a `<div>` or `<span>` with a `heading` role and `aria-level`, consider using a native {{HTMLElement("Heading_Elements", "h1")}} through {{HTMLElement("Heading_Elements", "h6")}} elements instead to indicate that this text is a heading, and what part of the structure it represents. - -## Examples - -The following shows a typical page structure. - -```html -<div id="container"> - <div role="heading" aria-level="1">The main page heading</div> - <p>This article is about showing a page structure.</p> - <div role="heading" aria-level="2">Introduction</div> - <p>An introductory text.</p> - <div role="heading" aria-level="2">Chapter 1</div> - <p>Text</p> - <div role="heading" aria-level="3">Chapter 1.1</div> - <p>More text in a sub section.</p> -</div> -``` - -However, instead, you should do: - -```html -<div id="container"> - <h1>The main page heading</h1> - <p>This article is about showing a page structure.</p> - <h2>Introduction</h2> - <p>An introductory text.</p> - <h2>Chapter 1</h2> - <p>Text</p> - <h3>Chapter 1.1</h3> - <p>More text in a sub section.</p> -</div> -``` - -## Accessibility concerns - -> [!WARNING] -> Using [`aria-label`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-label) or [`aria-labelledby`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-labelledby) will hide the content of your heading from assistive technologies, reading the label instead of the heading. - -If you must use the `heading` role and [`aria-level`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-level) attribute, do not go over level 6 so that you are consistent with HTML. Although theoretically you can go higher, and some screen readers may support it, the results can be unpredictable with other browser and screen reader combinations. - -## Best practices - -The best way to use this role is to **not use it at all**, and instead use the native heading tags {{HTMLElement("Heading_Elements", "h1")}} through {{HTMLElement("Heading_Elements", "h6")}} as shown in the example above. The `heading` role and `aria-level` attribute should only be used to retrofit accessibility on legacy code that you cannot make major changes to. - -Instead of using the ARIA `heading` role, use the semantic HTML element: - -| HTML Element | `heading` role | -| ----------------------------------------- | ------------------------------------- | -| {{HTMLElement("Heading_Elements", "h1")}} | `<div role="heading" aria-level="1">` | -| {{HTMLElement("Heading_Elements", "h2")}} | `<div role="heading" aria-level="2">` | -| {{HTMLElement("Heading_Elements", "h3")}} | `<div role="heading" aria-level="3">` | -| {{HTMLElement("Heading_Elements", "h4")}} | `<div role="heading" aria-level="4">` | -| {{HTMLElement("Heading_Elements", "h5")}} | `<div role="heading" aria-level="5">` | -| {{HTMLElement("Heading_Elements", "h6")}} | `<div role="heading" aria-level="6">` | - -### Added benefits - -None. - -## Specifications - -{{Specifications}} - -## Precedence order - -The heading role overrides the native semantic meaning of the element it is being used for. The `aria-level` attribute, in addition, determines what level of heading is being exposed. - -## See also - -- [`<h1>` through `<h6>`: The HTML Section Heading elements](/en-US/docs/Web/HTML/Element/Heading_Elements) diff --git a/files/en-us/web/accessibility/aria/roles/img_role/index.md b/files/en-us/web/accessibility/aria/roles/img_role/index.md deleted file mode 100644 index 9391cbb16f07178..000000000000000 --- a/files/en-us/web/accessibility/aria/roles/img_role/index.md +++ /dev/null @@ -1,136 +0,0 @@ ---- -title: "ARIA: img role" -slug: Web/Accessibility/ARIA/Roles/img_role -page-type: aria-role -spec-urls: https://w3c.github.io/aria/#img ---- - -{{AccessibilitySidebar}} - -The ARIA `img` role can be used to identify multiple elements inside page content that should be considered as a single image. These elements could be images, code snippets, text, emojis, or other content that can be combined to deliver information in a visual manner. - -```html -<div role="img" aria-label="Description of the overall image"> - <img src="graphic1.png" alt="" /> - <img src="graphic2.png" /> -</div> -``` - -## Description - -Any set of content that should be consumed as a single image (which could include images, video, audio, code snippets, emojis, or other content) can be identified using `role="img"`. - -You shouldn't count on the alt text of individual images for conveying context to assistive technologies; most screen readers will consider the element with `role="img"` set on it to be like a black box, and not access the individual elements inside it. Therefore, provide a comprehensive overall descriptive alt text for image, either in the surrounding text, or by using an [`aria-label`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-label) attribute, with `alt` attributes for search engines or sighted users to be written to the page should an image fail: - -```html -<div role="img" aria-label="Description of the overall image"> - <img src="graphic1.png" alt="alternative text" /> - <img src="graphic2.png" alt="in case the images don't load" /> -</div> -``` - -If you wish to add a caption or label to your image that is visible on the page, you can do using: - -- [`aria-labelledby`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-labelledby) when the text is a concise label. -- [`aria-describedby`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-describedby) when the text is a longer description. - -For example: - -```html -<div role="img" aria-labelledby="image-1"> - … - <p id="image-1">Text that describes the group of images.</p> -</div> -``` - -If an image is purely presentational, consider using the [`presentation`](/en-US/docs/Web/Accessibility/ARIA/Roles/presentation_role) role. - -### SVG and role="img" - -If you are using embedded SVG images in your page, it is a good idea to set `role="img"` on the outer {{SVGElement('svg')}} element and give it a label. This will cause screen readers to just consider it as a single entity and describe it using the label, rather than trying to read out all the child nodes: - -```html -<svg role="img" aria-label="Description of your SVG image"> - <!-- contents of the SVG image --> -</svg> -``` - -### Using role="img" to confer meaning that is obscured or implied - -In certain cases, assistive technology users won't be able to get the meaning of content expressed in certain ways, through certain media, or implied in certain ways. This is obvious to fix in the case of images (you can use the `alt` attribute), but in the case of mixed or other certain types of content it is not so obvious, and `role="img"` can come into play. - -For example, if you use emojis in your text, the meaning might be obvious to a sighted user, but someone using a screen reader might get confused because the emojis might have either no text representation at all, or the alternative text might be confusing and not match the context it is being used in. For example, take the following code: - -```html -<div role="img" aria-label="That cat is so cute"> - <p>&#x1F408; &#x1F602;</p> -</div> -``` - -`&#x1F408; &#x1F602;`, 🐈 and 😂, are entity references for emojis read out as "Cat" and "Face with tears of joy", but this doesn't necessarily make sense — the implied meaning is possibly more like "That cat is so cute", so we include that in an `aria-label` along with `role="img"`. - -This seems to work OK across some browser/screen reader combinations, but some of them end up reading the label out twice. Use with caution and test thoroughly. - -Another example where this might be suitable is when using {{Glossary("ASCII")}} emoji combinations, like the legendary "Table flip": - -```html -<div role="img" aria-label="Table flip"> - <p>(╯°□°)╯︵ ┻━┻</p> -</div> -``` - -If `aria-labelledby` were used, the screen reader would read it. In this case, only the contents of the `aria-label` are announced to screen reader users, hiding the gibberish of the characters without the need for descendant ARIA to hide things, but also hiding potential content that may be part of the image. - -### All descendants are presentational - -There are some types of user interface components that, when represented in a platform accessibility API, can only contain text. Accessibility APIs do not have a way of representing semantic elements contained in an `img`. To deal with this limitation, browsers, automatically apply role [`presentation`](/en-US/docs/Web/Accessibility/ARIA/Roles/presentation_role) to all descendant elements of any `img` element as it is a role that does not support semantic children. - -For example, consider the following `img` element, which contains a heading. - -```html -<div role="img"><h3>Title of my image</h3></div> -``` - -Because descendants of `img` are presentational, the following code is equivalent: - -```html -<div role="img"><h3 role="presentation">Title of my image</h3></div> -``` - -From the assistive technology user's perspective, the heading does not exist since the previous code snippets are equivalent to the following in the [accessibility tree](/en-US/docs/Glossary/Accessibility_tree).: - -```html -<div role="img">Title of my image</div> -``` - -### Associated WAI-ARIA Roles, States, and Properties - -- `aria-label` or `aria-labelledby` - - : An accessible name is required. For the HTML {{HTMLElement('img')}} element, use the `alt` attribute. For all other elements with the `img` role, use `aria-labelledby` if a visible label is present, otherwise use `aria-label`. - -## Examples - -```html -<span role="img" aria-label="Rating: 4 out of 5 stars"> - <span>★</span> - <span>★</span> - <span>★</span> - <span>★</span> - <span>☆</span> -</span> -``` - -## Specifications - -{{Specifications}} - -## See also - -- The {{HTMLElement('img')}} element -- The {{SVGElement('svg')}} element -- The {{HTMLElement('picture')}} element -- The {{HTMLElement('audio')}} element -- The {{HTMLElement('video')}} element -- [ARIA: `presentation` role](/en-US/docs/Web/Accessibility/ARIA/Roles/presentation_role) -- [Accessibility Object Model](https://wicg.github.io/aom/spec/) -- [ARIA in HTML](https://w3c.github.io/html-aria/) diff --git a/files/en-us/web/accessibility/aria/roles/index.md b/files/en-us/web/accessibility/aria/roles/index.md deleted file mode 100644 index 3ca4cb230c10588..000000000000000 --- a/files/en-us/web/accessibility/aria/roles/index.md +++ /dev/null @@ -1,154 +0,0 @@ ---- -title: WAI-ARIA Roles -slug: Web/Accessibility/ARIA/Roles -page-type: landing-page ---- - -{{AccessibilitySidebar}} - -ARIA roles provide semantic meaning to content, allowing screen readers and other tools to present and support interaction with an object in a way that is consistent with user expectations of that type of object. <abbr>ARIA</abbr> roles can be used to describe elements that don't natively exist in HTML or exist but don't yet have full browser support. - -By default, many semantic elements in HTML have a role; for example, `<input type="radio">` has the "radio" role. Non-semantic elements in HTML do not have a role; `<div>` and `<span>` without added semantics return `null`. The `role` attribute can provide semantics. - -ARIA roles are added to HTML elements using `role="role type"`, where _role type_ is the name of a role in the ARIA specification. Some roles require the inclusion of associated ARIA states or properties; others are only valid in association with other roles. - -For example, `<ul role="tabpanel">` will be announced as a 'tab panel' by screen readers. However, if the tab panel doesn't have nested tabs, the element with the tabpanel role is not in fact a tab panel and accessibility has actually been negatively impacted. - -The [ARIA states and properties](/en-US/docs/Web/Accessibility/ARIA/Attributes) associated with each role are included in the role's pages, with each attribute also having a dedicated page. - -## ARIA role types - -There are 6 categories of ARIA roles: - -### 1. Document structure roles - -Document Structure roles are used to provide a structural description for a section of content. Most of these roles should no longer be used as browsers now support semantic HTML elements with the same meaning. The roles without HTML equivalents, such as presentation, toolbar and tooltip roles, provide information on the document structure to assistive technologies such as screen readers as equivalent native HTML tags are not available. - -- [toolbar](/en-US/docs/Web/Accessibility/ARIA/Roles/toolbar_role) -- [tooltip](/en-US/docs/Web/Accessibility/ARIA/Roles/tooltip_role) -- [feed](/en-US/docs/Web/Accessibility/ARIA/Roles/feed_role) -- [math](/en-US/docs/Web/Accessibility/ARIA/Roles/math_role) -- [presentation](/en-US/docs/Web/Accessibility/ARIA/Roles/presentation_role) / [none](/en-US/docs/Web/Accessibility/ARIA/Roles/none_role) -- [note](/en-US/docs/Web/Accessibility/ARIA/Roles/note_role) - -For most document structure roles, semantic HTML equivalent elements are available and supported. Avoid using: - -- [application](/en-US/docs/Web/Accessibility/ARIA/Roles/application_role) -- [article](/en-US/docs/Web/Accessibility/ARIA/Roles/article_role) (use {{HTMLElement('article')}}) -- [cell](/en-US/docs/Web/Accessibility/ARIA/Roles/cell_role) (use {{HTMLElement('td')}}) -- [columnheader](/en-US/docs/Web/Accessibility/ARIA/Roles/columnheader_role) (use `{{HTMLElement('th', '&lt;th scope="col">')}}`) -- [definition](/en-US/docs/Web/Accessibility/ARIA/Roles/definition_role) (use {{HTMLElement('dfn')}}) -- [directory](/en-US/docs/Web/Accessibility/ARIA/Roles/directory_role) -- [document](/en-US/docs/Web/Accessibility/ARIA/Roles/document_role) -- [figure](/en-US/docs/Web/Accessibility/ARIA/Roles/figure_role) (use {{HTMLElement('figure')}} instead) -- [group](/en-US/docs/Web/Accessibility/ARIA/Roles/group_role) -- [heading](/en-US/docs/Web/Accessibility/ARIA/Roles/heading_role) (use {{HTMLElement("Heading_Elements", "h1")}} through {{HTMLElement("Heading_Elements", "h6")}}) -- [img](/en-US/docs/Web/Accessibility/ARIA/Roles/img_role) (use {{HTMLElement('img')}} or {{HTMLElement('picture')}} instead) -- [list](/en-US/docs/Web/Accessibility/ARIA/Roles/list_role) (use either {{HTMLElement('ul')}} or {{HTMLElement('ol')}} instead) -- [listitem](/en-US/docs/Web/Accessibility/ARIA/Roles/listitem_role) (use {{HTMLElement('li')}} instead) -- [meter](/en-US/docs/Web/Accessibility/ARIA/Roles/meter_role) (use {{HTMLElement('meter')}} instead) -- [row](/en-US/docs/Web/Accessibility/ARIA/Roles/row_role) (use the {{HTMLElement('tr')}} with {{HTMLElement('table')}}) -- [rowgroup](/en-US/docs/Web/Accessibility/ARIA/Roles/rowgroup_role) (use {{HTMLElement('thead')}}, {{HTMLElement('tfoot')}} and {{HTMLElement('tbody')}}) -- [rowheader](/en-US/docs/Web/Accessibility/ARIA/Roles/rowheader_role) (use `{{HTMLElement('th','&lt;th scope="row">')}}`) -- [separator](/en-US/docs/Web/Accessibility/ARIA/Roles/separator_role) (use {{HTMLElement('hr')}} if it doesn't have focus) -- [table](/en-US/docs/Web/Accessibility/ARIA/Roles/table_role) (use {{HTMLElement('table')}}) -- [term](/en-US/docs/Web/Accessibility/ARIA/Roles/term_role) (use {{HTMLElement('dfn')}}) - -These are included for completeness, but in most cases are rarely, if ever, useful: - -- [`associationlist`](/en-US/docs/Web/Accessibility/ARIA/Roles/structural_roles) -- [`associationlistitemkey`](/en-US/docs/Web/Accessibility/ARIA/Roles/structural_roles) -- [`associationlistitemvalue`](/en-US/docs/Web/Accessibility/ARIA/Roles/structural_roles) -- [`blockquote`](/en-US/docs/Web/Accessibility/ARIA/Roles/structural_roles) -- [`caption`](/en-US/docs/Web/Accessibility/ARIA/Roles/structural_roles) -- [`code`](/en-US/docs/Web/Accessibility/ARIA/Roles/structural_roles) -- [`deletion`](/en-US/docs/Web/Accessibility/ARIA/Roles/structural_roles) -- [`emphasis`](/en-US/docs/Web/Accessibility/ARIA/Roles/structural_roles) -- [`insertion`](/en-US/docs/Web/Accessibility/ARIA/Roles/structural_roles) -- [`paragraph`](/en-US/docs/Web/Accessibility/ARIA/Roles/structural_roles) -- [`strong`](/en-US/docs/Web/Accessibility/ARIA/Roles/structural_roles) -- [`subscript`](/en-US/docs/Web/Accessibility/ARIA/Roles/structural_roles) -- [`superscript`](/en-US/docs/Web/Accessibility/ARIA/Roles/structural_roles) -- [`time`](/en-US/docs/Web/Accessibility/ARIA/Roles/structural_roles) - -### 2. Widget roles - -Widget roles are used to define common interactive patterns. Like document structure roles, some widget roles have the same semantics as well-supported native HTML elements, and therefore should be avoided. The key difference is that widget roles typically require JavaScript for interaction, while document structure roles often do not. - -- [scrollbar](/en-US/docs/Web/Accessibility/ARIA/Roles/scrollbar_role) -- [searchbox](/en-US/docs/Web/Accessibility/ARIA/Roles/searchbox_role) -- [separator](/en-US/docs/Web/Accessibility/ARIA/Roles/separator_role) (when focusable) -- [slider](/en-US/docs/Web/Accessibility/ARIA/Roles/slider_role) -- [spinbutton](/en-US/docs/Web/Accessibility/ARIA/Roles/spinbutton_role) -- [switch](/en-US/docs/Web/Accessibility/ARIA/Roles/switch_role) -- [tab](/en-US/docs/Web/Accessibility/ARIA/Roles/tab_role) -- [tabpanel](/en-US/docs/Web/Accessibility/ARIA/Roles/tabpanel_role) -- [treeitem](/en-US/docs/Web/Accessibility/ARIA/Roles/treeitem_role) - -Avoid using [button](/en-US/docs/Web/Accessibility/ARIA/Roles/button_role), [checkbox](/en-US/docs/Web/Accessibility/ARIA/Roles/checkbox_role), [gridcell](/en-US/docs/Web/Accessibility/ARIA/Roles/gridcell_role), [link](/en-US/docs/Web/Accessibility/ARIA/Roles/link_role), [menuitem](/en-US/docs/Web/Accessibility/ARIA/Roles/menuitem_role), [menuitemcheckbox](/en-US/docs/Web/Accessibility/ARIA/Roles/menuitemcheckbox_role), [menuitemradio](/en-US/docs/Web/Accessibility/ARIA/Roles/menuitemradio_role), [option](/en-US/docs/Web/Accessibility/ARIA/Roles/option_role), [progressbar](/en-US/docs/Web/Accessibility/ARIA/Roles/progressbar_role), [radio](/en-US/docs/Web/Accessibility/ARIA/Roles/radio_role), and [textbox](/en-US/docs/Web/Accessibility/ARIA/Roles/textbox_role), which we've included for completeness. For most, semantic equivalents with accessible interactivity are available and supported. See the individual role documentation for more information. - -#### Composite widget roles - -- [combobox](/en-US/docs/Web/Accessibility/ARIA/Roles/combobox_role) -- [menu](/en-US/docs/Web/Accessibility/ARIA/Roles/menu_role) -- [menubar](/en-US/docs/Web/Accessibility/ARIA/Roles/menubar_role) -- [tablist](/en-US/docs/Web/Accessibility/ARIA/Roles/tablist_role) -- [tree](/en-US/docs/Web/Accessibility/ARIA/Roles/tree_role) -- [treegrid](/en-US/docs/Web/Accessibility/ARIA/Roles/treegrid_role) - -Avoid using [grid](/en-US/docs/Web/Accessibility/ARIA/Roles/grid_role), [listbox](/en-US/docs/Web/Accessibility/ARIA/Roles/listbox_role), and [radiogroup](/en-US/docs/Web/Accessibility/ARIA/Roles/radio_role), which we've included for completeness. See the individual role documentation for more information. - -Note that there is also a widget role (`role="widget"`), which is an abstract role and not in the widget role category. - -### 3. Landmark roles - -Landmark roles provide a way to identify the organization and structure of a web page. By classifying and labeling sections of a page, structural information conveyed visually through layout is represented programmatically. Screen readers use landmark roles to provide keyboard navigation to important sections of a page. Use these sparingly. Too many landmark roles create "noise" in screen readers, making it difficult to understand the overall layout of the page. - -- [banner](/en-US/docs/Web/Accessibility/ARIA/Roles/banner_role) (document {{HTMLElement('header')}}) -- [complementary](/en-US/docs/Web/Accessibility/ARIA/Roles/complementary_role) ({{HTMLElement('aside')}}) -- [contentinfo](/en-US/docs/Web/Accessibility/ARIA/Roles/contentinfo_role) (document {{HTMLElement('footer')}}) -- [form](/en-US/docs/Web/Accessibility/ARIA/Roles/form_role) ({{HTMLElement('form')}}) -- [main](/en-US/docs/Web/Accessibility/ARIA/Roles/main_role) ({{HTMLElement('main')}}) -- [navigation](/en-US/docs/Web/Accessibility/ARIA/Roles/navigation_role) ({{HTMLElement('nav')}}) -- [region](/en-US/docs/Web/Accessibility/ARIA/Roles/region_role) ({{HTMLElement('section')}}) -- [search](/en-US/docs/Web/Accessibility/ARIA/Roles/search_role) ({{HTMLElement('search')}}) - -### 4. Live region roles - -Live Region roles are used to define elements with content that will be dynamically changed. Sighted users can see dynamic changes when they are visually noticeable. These roles help low vision and blind users know if content has been updated. Assistive technologies, like screen readers, can be made to announce dynamic content changes: - -- [alert](/en-US/docs/Web/Accessibility/ARIA/Roles/alert_role) -- [log](/en-US/docs/Web/Accessibility/ARIA/Roles/log_role) -- [marquee](/en-US/docs/Web/Accessibility/ARIA/Roles/marquee_role) -- [status](/en-US/docs/Web/Accessibility/ARIA/Roles/status_role) -- [timer](/en-US/docs/Web/Accessibility/ARIA/Roles/timer_role) - -### 5. Window roles - -Window roles define sub-windows to the main document window, within the same window, such as pop up modal dialogs: - -- [alertdialog](/en-US/docs/Web/Accessibility/ARIA/Roles/alertdialog_role) -- [dialog](/en-US/docs/Web/Accessibility/ARIA/Roles/dialog_role) - -### 6. Abstract roles - -Abstract roles are only intended for use by browsers to help organize and streamline a document. They should not be used by developers writing HTML markup. Doing so will not result in any meaningful information being conveyed to assistive technologies or to users. - -Avoid using [command](/en-US/docs/Web/Accessibility/ARIA/Roles/command_role), [composite](/en-US/docs/Web/Accessibility/ARIA/Roles/composite_role), [input](/en-US/docs/Web/Accessibility/ARIA/Roles/input_role), [landmark](/en-US/docs/Web/Accessibility/ARIA/Roles/landmark_role), [range](/en-US/docs/Web/Accessibility/ARIA/Roles/range_role), [roletype](/en-US/docs/Web/Accessibility/ARIA/Roles/roletype_role), [section](/en-US/docs/Web/Accessibility/ARIA/Roles/section_role), [sectionhead](/en-US/docs/Web/Accessibility/ARIA/Roles/sectionhead_role), [select](/en-US/docs/Web/Accessibility/ARIA/Roles/select_role), [structure](/en-US/docs/Web/Accessibility/ARIA/Roles/structure_role), [widget](/en-US/docs/Web/Accessibility/ARIA/Roles/widget_role),and [window](/en-US/docs/Web/Accessibility/ARIA/Roles/window_role). - -> [!NOTE] -> Don't use abstract roles in your sites and applications. They are for use by browsers. They are included for reference only. - -> [!WARNING] -> "Abstract roles are used for the ontology. Authors **MUST NOT** use abstract roles in content." - The <abbr>WAI-ARIA</abbr> specification - -## Roles defined on MDN - -The following are the reference pages covering the WAI-ARIA roles discussed on <abbr>MDN</abbr>. - -{{SubpagesWithSummaries}} - -## See also - -- [Using ARIA: Roles, States, and Properties](/en-US/docs/Web/Accessibility/ARIA/ARIA_Techniques) -- [ARIA states and properties](/en-US/docs/Web/Accessibility/ARIA/Attributes) diff --git a/files/en-us/web/accessibility/aria/roles/input_role/index.md b/files/en-us/web/accessibility/aria/roles/input_role/index.md deleted file mode 100644 index de4d48521788b0b..000000000000000 --- a/files/en-us/web/accessibility/aria/roles/input_role/index.md +++ /dev/null @@ -1,37 +0,0 @@ ---- -title: "ARIA: input role" -slug: Web/Accessibility/ARIA/Roles/input_role -page-type: aria-role -spec-urls: https://w3c.github.io/aria/#input ---- - -{{AccessibilitySidebar}} - -The `input` abstract role is a generic type of widget that allows user input. - -> [!NOTE] -> The `input` role is an [abstract role](/en-US/docs/Web/Accessibility/ARIA/Roles#6._abstract_roles). It is included here for completeness of documentation. It is not to be used by web authors. - -## Description - -The `input` role is an abstract role. It must not be used by web authors. It is the superclass for input widgets that provide for user input, including [`checkbox`](/en-US/docs/Web/Accessibility/ARIA/Roles/checkbox_role), [`radio`](/en-US/docs/Web/Accessibility/ARIA/Roles/radio_role), and [`textbox`](/en-US/docs/Web/Accessibility/ARIA/Roles/textbox_role). For all three, consider using the {{HTMLElement("input")}} element of type [`checkbox`](/en-US/docs/Web/HTML/Element/input/checkbox), [`radio`](/en-US/docs/Web/HTML/Element/input/radio) and [`text`](/en-US/docs/Web/HTML/Element/input/text), respectively. - -## Best Practices - -Do not use. - -## Specifications - -{{Specifications}} - -## See also - -- [ARIA: `widget` role](/en-US/docs/Web/Accessibility/ARIA/Roles/widget_role) -- [ARIA: `checkbox` role](/en-US/docs/Web/Accessibility/ARIA/Roles/checkbox_role) -- [ARIA: `combobox` role](/en-US/docs/Web/Accessibility/ARIA/Roles/combobox_role) -- [ARIA: `option` role](/en-US/docs/Web/Accessibility/ARIA/Roles/option_role) -- [ARIA: `radio` role](/en-US/docs/Web/Accessibility/ARIA/Roles/radio_role) -- [ARIA: `slider` role](/en-US/docs/Web/Accessibility/ARIA/Roles/slider_role) -- [ARIA: `spinbutton` role](/en-US/docs/Web/Accessibility/ARIA/Roles/spinbutton_role) -- [ARIA: `textbox` role](/en-US/docs/Web/Accessibility/ARIA/Roles/textbox_role) -- [HTML: the `input` element](/en-US/docs/Web/HTML/Element/input) diff --git a/files/en-us/web/accessibility/aria/roles/landmark_role/index.md b/files/en-us/web/accessibility/aria/roles/landmark_role/index.md deleted file mode 100644 index e56ab777edfd24c..000000000000000 --- a/files/en-us/web/accessibility/aria/roles/landmark_role/index.md +++ /dev/null @@ -1,46 +0,0 @@ ---- -title: "ARIA: landmark role" -slug: Web/Accessibility/ARIA/Roles/landmark_role -page-type: aria-role -spec-urls: https://w3c.github.io/aria/#landmark ---- - -{{AccessibilitySidebar}} - -A landmark is an important subsection of a page. The `landmark` role is an abstract superclass for the aria role values for sections of content that are important enough that users will likely want to be able to navigate directly to them. - -> [!NOTE] -> The `landmark` role is an [abstract role](/en-US/docs/Web/Accessibility/ARIA/Roles#6._abstract_roles). It is included here for completeness of documentation. It should not be used by web authors. - -## Description - -A `landmark` is an abstract role for a section of content that is important enough that users will likely want to be able to navigate to the section easily and have it included in a dynamically generated summary of the page. Landmarks allow assistive technologies to navigate and to find content quickly. - -To create a landmark role, define the purpose of the content by using a semantic element such as `<section>`, `<nav>`, or `<main>`, or adding an ARIA role that is a subclass of the `landmark` role such as [`role="banner"`](/en-US/docs/Web/Accessibility/ARIA/Roles/banner_role), [`role="complementary"`](/en-US/docs/Web/Accessibility/ARIA/Roles/complementary_role), or [`role="region"`](/en-US/docs/Web/Accessibility/ARIA/Roles/region_role). Do not use `role="landmark"`. - -A visible label should be provided, referenced with [`aria-labelledby`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-labelledby). If necessary, brief, descriptive, label can be provided with [`aria-label`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-label). - -For screen reader users, adding landmark roles effectively creates 'skip links' for screen reader users, but don't replace in page navigation as the landmark roles are not otherwise surfaced. - -## Best Practices - -Do not use `role="landmark"`. Do use HTML and subclass landmark roles. - -Landmarks ensure content is in navigable regions. Use {{HTMLElement('main')}} for [`role="main"`](/en-US/docs/Web/Accessibility/ARIA/Roles/main_role), {{HTMLElement('header')}} for [`role="banner"`](/en-US/docs/Web/Accessibility/ARIA/Roles/banner_role), {{HTMLElement('nav')}} for [`role="navigation"`](/en-US/docs/Web/Accessibility/ARIA/Roles/navigation_role), and {{HTMLElement('footer')}} for [`role="contentinfo"`](/en-US/docs/Web/Accessibility/ARIA/Roles/contentinfo_role). It is also good practice to include the role redundantly with the associated semantic element. It is not as good practice to use non-semantic elements, such as {{HTMLElement('div')}}, adding semantics with landmark roles. But do include one or the other or both. Otherwise, your content is no longer as navigable for screen reader users. - -## Specifications - -{{Specifications}} - -## See also - -- [ARIA: `section` role](/en-US/docs/Web/Accessibility/ARIA/Roles/section_role) -- [ARIA: `banner` role](/en-US/docs/Web/Accessibility/ARIA/Roles/banner_role) -- [ARIA: `complementary` role](/en-US/docs/Web/Accessibility/ARIA/Roles/complementary_role) -- [ARIA: `contentinfo` role](/en-US/docs/Web/Accessibility/ARIA/Roles/contentinfo_role) -- [ARIA: `form` role](/en-US/docs/Web/Accessibility/ARIA/Roles/form_role) -- [ARIA: `main` role](/en-US/docs/Web/Accessibility/ARIA/Roles/main_role) -- [ARIA: `navigation` role](/en-US/docs/Web/Accessibility/ARIA/Roles/navigation_role) -- [ARIA: `region` role](/en-US/docs/Web/Accessibility/ARIA/Roles/region_role) -- [ARIA: `search` role](/en-US/docs/Web/Accessibility/ARIA/Roles/search_role) -- [Using HTML landmark roles to improve accessibility](/en-US/blog/aria-accessibility-html-landmark-roles/) on MDN blog (2023) diff --git a/files/en-us/web/accessibility/aria/roles/link_role/index.md b/files/en-us/web/accessibility/aria/roles/link_role/index.md deleted file mode 100644 index 84730d110e46ee5..000000000000000 --- a/files/en-us/web/accessibility/aria/roles/link_role/index.md +++ /dev/null @@ -1,103 +0,0 @@ ---- -title: "ARIA: link role" -slug: Web/Accessibility/ARIA/Roles/link_role -page-type: aria-role -spec-urls: https://w3c.github.io/aria/#link ---- - -{{AccessibilitySidebar}} - -A `link` widget provides an interactive reference to a resource. The target resource can be either external or local; i.e., either outside or within the current page or application. - -> [!NOTE] -> Where possible, it is recommended that you use a native {{HTMLElement("a")}} element rather than the `link` role, as native elements are more widely supported by user agents and assistive technology. Native {{HTMLElement("a")}} elements also support keyboard and focus requirements by default, without need for additional customization. - -## Description - -The `link` role is used to identify an element that creates a hyperlink to a resource that is in the application or external. - -When not using semantic HTML for its intended purpose, interactive features must be re-implemented. For example, when `role="link"` is added to an element, the <kbd>tab</kbd> key should enable giving focus to the link and the <kbd>enter</kbd> key should execute the link when focused. - -Use the [`tabindex`](/en-US/docs/Web/HTML/Global_attributes/tabindex) attribute with a value of `0` to ensure the link is in the correct tab focus order. - -> [!WARNING] -> Applying the `link` role to an element will not cause browsers to enhance the element with standard link appearance or behaviors, such as underlining, focus rings, navigation to the link target, or context menu actions. That's the developer's responsibility. - -## Examples - -To recreate an accessible link using the `link` role on an element that is not an {{HTMLElement('a')}}, you need to ensure the link receives focus in the correct tab order, that the element looks like a link, and that the "link" behaves like a link. - -```html -<span data-href="https://mozilla.org" tabindex="0" role="link"> - Fake accessible link created using a span -</span> -``` - -### CSS - -```css -span[role="link"] { - color: blue; - text-decoration: underline; - cursor: pointer; -} -span[role="link"]:hover, -span[role="link"]:active, -span[role="link"]:focus { - color: purple; -} - -span[role="link"]:focus { - background-color: palegoldenrod; - outline: 1px dotted; -} -``` - -### JavaScript - -```js -const fakeLinks = document.querySelectorAll('[role="link"]'); - -for (let i = 0; i < fakeLinks.length; i++) { - fakeLinks[i].addEventListener("click", navigateLink); - fakeLinks[i].addEventListener("keydown", navigateLink); -} - -// handles click and keydown events on the link -function navigateLink(e) { - if (e.type === "click" || e.key === "Enter") { - const ref = e.target ?? e.srcElement; - if (ref) { - window.open(ref.getAttribute("data-href"), "_blank"); - } - } -} -``` - -If the element with `role="link"` receives an <kbd>Enter</kbd> key event, this executes the link, going to the linked page or moving focus to the in page target. - -Optionally, <kbd>Shift</kbd> + <kbd>F10</kbd> opens a context menu for the link. - -## Best practices - -The various widget roles are used to define common interactive patterns. Similar to the document-structure roles, some of these roles, including the `link` role, duplicate the semantics of native HTML elements that are well supported, and should not be used. - -Avoid using `link`, which we've included for completeness. The {{HTMLElement('a')}} semantic equivalent with accessible interactivity is available and supported. - -### Prefer HTML - -Using the {{HTMLElement('a')}} instead. - -> [!NOTE] -> There is no need to include `role="link"` on an HTML link as the `<a>`, by default, has that role already. - -## Specifications - -{{Specifications}} - -## See also - -- The {{HTMLElement('a')}} element -- The {{HTMLElement('button')}} element -- [`aria-label`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-label) -- [ARIA practices `link` role examples](https://www.w3.org/WAI/ARIA/apg/patterns/link/examples/link/) diff --git a/files/en-us/web/accessibility/aria/roles/list_role/index.md b/files/en-us/web/accessibility/aria/roles/list_role/index.md deleted file mode 100644 index 6b7266ee0a94ec0..000000000000000 --- a/files/en-us/web/accessibility/aria/roles/list_role/index.md +++ /dev/null @@ -1,78 +0,0 @@ ---- -title: "ARIA: list role" -slug: Web/Accessibility/ARIA/Roles/list_role -page-type: aria-role -spec-urls: https://w3c.github.io/aria/#list ---- - -{{AccessibilitySidebar}} - -The ARIA `list` role can be used to identify a list of items. It is normally used in conjunction with the `listitem` role, which is used to identify a list item contained inside the list. - -```html -<div role="list"> - <div role="listitem">List item 1</div> - <div role="listitem">List item 2</div> - <div role="listitem">List item 3</div> -</div> -``` - -## Description - -Any content that consists of an outer container with a list of elements inside can be identified to assistive technologies using the `list` and `listitem` containers, respectively. A `list` can only contain zero or more `listitem` children. - -There are no hard and fast rules about which elements you should use to mark up the list and list items, but you should make sure that the list items make sense in the context of a list, e.g. a shopping list, recipe steps, driving directions. - -> [!NOTE] -> Best practices dictate using the appropriate semantic HTML elements over ARIA roles to mark up lists and listitems — {{HTMLElement("ul")}}, {{HTMLElement("ol")}} and {{HTMLElement("li")}}. See [Best practices](#best_practices) for a full example. - -### Associated WAI-ARIA Roles, States, and Properties - -- [`listitem`](/en-US/docs/Web/Accessibility/ARIA/Roles/listitem_role) role - - : A single item in a list. Elements with role `listitem` can only be found in an element with the role `list`. - -## Best practices - -Only use `role="list"` and `role="listitem"` if you have to — for example if you don't have control over your HTML but are able to improve accessibility dynamically after the fact with JavaScript. - -Unlike the HTML {{HTMLElement("ol")}} and {{HTMLElement("ul")}}, the ARIA `list` roles doesn't distinguish between ordered and unordered lists. If at all possible, you should use the appropriate semantic HTML elements to mark up a list ({{HTMLElement("ol")}} and {{HTMLElement("ul")}}) and list items ({{HTMLElement("li")}}). For example, our above example should be rewritten as follows: - -```html -<ul> - <li>List item 1</li> - <li>List item 2</li> - <li>List item 3</li> -</ul> -``` - -or use an ordered list if the order of the list items matters: - -```html -<ol> - <li>List item 1</li> - <li>List item 2</li> - <li>List item 3</li> -</ol> -``` - -> [!NOTE] -> The ARIA `list` / `listitem` roles don't distinguish between ordered and unordered lists. - -As an aside, note that if you are using the semantic HTML elements of `<ol>` or `<ul>` and apply a role of [`presentation`](/en-US/docs/Web/Accessibility/ARIA/Roles/presentation_role), each child `<li>` element inherits the `presentation` role because ARIA requires the `listitem` elements to have the parent `list` element. So, the `<li>` elements are not exposed to assistive technologies, but elements contained inside of those `<li>` elements, including nested lists, are visible to assistive technologies. - -> [!NOTE] -> If you are marking up a list of items that will function as a tabbed interface, you should instead use the [`tab`](/en-US/docs/Web/Accessibility/ARIA/Roles/tab_role), [`tabpanel`](/en-US/docs/Web/Accessibility/ARIA/Roles/tabpanel_role), and [`tablist`](/en-US/docs/Web/Accessibility/ARIA/Roles/tablist_role) roles. - -## Specifications - -{{Specifications}} - -## See also - -- The {{HTMLElement("ul")}} element -- The {{HTMLElement("ol")}} element -- The {{HTMLElement("li")}} element -- [ARIA: listitem role](/en-US/docs/Web/Accessibility/ARIA/Roles/listitem_role) -- [ARIA Lists examples](https://www.scottohara.me/blog/2018/05/26/aria-lists.html) — by Scott O'Hara -- [Accessibility Object Model](https://wicg.github.io/aom/spec/) -- [ARIA in HTML](https://w3c.github.io/html-aria/) diff --git a/files/en-us/web/accessibility/aria/roles/listbox_role/index.md b/files/en-us/web/accessibility/aria/roles/listbox_role/index.md deleted file mode 100644 index c16891cc0cfad4c..000000000000000 --- a/files/en-us/web/accessibility/aria/roles/listbox_role/index.md +++ /dev/null @@ -1,203 +0,0 @@ ---- -title: "ARIA: listbox role" -slug: Web/Accessibility/ARIA/Roles/listbox_role -page-type: aria-role -spec-urls: - - https://w3c.github.io/aria/#listbox - - https://www.w3.org/WAI/ARIA/apg/patterns/listbox/examples/listbox-scrollable/ ---- - -{{AccessibilitySidebar}} - -The `listbox` role is used for lists from which a user may select one or more items which are static and, unlike HTML {{HTMLElement('select')}} elements, may contain images. - -## Description - -The `listbox` role is used to identify an element that creates a list from which a user may select one or more static items, similar to the HTML {{HTMLElement('select')}} element. Unlike {{HTMLElement('select')}}, a listbox can contain images. Listboxes contain children whose role is [`option`](/en-US/docs/Web/Accessibility/ARIA/Roles/option_role) or elements whose role is [`group`](/en-US/docs/Web/Accessibility/ARIA/Roles/group_role) which in turn contain children whose role is `option`. - -It is highly recommended using the HTML select element, or a group of radio buttons if only one item can be selected, or a group of checkboxes if multiple items can be selected, because there is a lot of keyboard interactivity to manage focus for all the descendants, and native HTML elements provide this functionality for you for free. - -Elements with the role `listbox` have an implicit [`aria-orientation`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-orientation) value of `vertical`. - -When a list is tabbed to, the first item in the list will be selected if nothing else already is. Up/down arrows navigate the list, and pressing Shift + Up/Down arrows will move and extend the selection. Typing one or more letters will navigate the list items (same letter goes to each item starting with that, different letters go to the first item starting with that entire string). If the current item has an associated context menu, Shift+F10 will launch that menu. If list items are checkable, Space can be used to toggle [checkboxes](/en-US/docs/Web/Accessibility/ARIA/Roles/checkbox_role). For selectable list items, Space toggles their selection, Shift+Space can be used to select contiguous items, Ctrl+Arrow moves without selecting, and Ctrl+Space can be used to select non-contiguous items. It is recommended that a checkbox, link or other method be used to select all items, and Ctrl+A could be used as a shortcut key for this. - -When the listbox role is added to an element, or such an element becomes visible, screen readers announce the label and role of the listbox when it gets focus. If an option or item is focused within the list, it gets announced next, followed by an indication of the item's position with the list if the screen reader supports this. As focus moves within the list, the screen reader announces the relevant items. - -### Associated ARIA roles, states, and properties - -#### Associated Roles - -- [`option`](/en-US/docs/Web/Accessibility/ARIA/Roles/option_role) role - - : One or more nested options are required. All selected options have [`aria-selected`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-selected) set to `true`. All options that are not selected have [`aria-selected`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-selected) set to `false`. If an option is not selectable, omit the [`aria-selected`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-selected). -- [`list`](/en-US/docs/Web/Accessibility/ARIA/Roles/list_role) role - - : A section containing `listitem` elements - -#### States and Properties - -- [`aria-activedescendant`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-activedescendant) - - : Holds the `id` string of the currently active element within the listbox. If that's an option element, then that would be the `id` of the most recently interacted with option, regardless of whether that option has an [`aria-selected`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-selected) value of `true` or not. Takes the value of only one `id`, even in a multiselectable listbox. If the `id` does not refer to a DOM descendant of the listbox, then that `id` must be included among the IDs in the [`aria-owns`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-owns) attribute. -- [`aria-owns`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-owns) - - - : This is a space-separated list of element IDs which are not DOM child elements of the listbox. IDs listed here cannot also be listed in [`aria-owns`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-owns) attributes of any other elements. - -- [`aria-multiselectable`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-multiselectable) - - - : Include and set to `true` if the user can select more than one option. If set to `true`, _every_ selectable option should have an [`aria-selected`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-selected) attribute included and set to `true` or `false`. Options which are _not_ selectable _should not_ have the [`aria-selected`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-selected) attribute. If `false` or omitted, only the currently selected option, if any option is selected, needs the [`aria-selected`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-selected) attribute, and it must be set to `true`. - -- [`aria-required`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-required) - - - : A Boolean attribute which indicates that an option with a non-empty string value must be selected. - -- [`aria-readonly`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-readonly) - - - : The user cannot change which options are selected or unselected, but the listbox is otherwise operable. - -- [`aria-label`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-label) - - - : A human-readable string value which identifies the listbox. If there's a visible label, then [`aria-labelledby`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-labelledby) should be used instead to refer to that label. - -- [`aria-labelledby`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-labelledby) - - - : Identifies the visible element or elements in a space-separated list of element IDs which identify the listbox. If there's no visible label, then [`aria-label`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-label) should be used instead to include a label. (Note: "labelled", with two L's, is the correct spelling based on the accessibility API conventions.) - -- [`aria-roledescription`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-roledescription) - - : A human-readable string value which more clearly identifies the role of the listbox. Screen readers will often read this value to the user after reading the label (if there is one), in place of saying "listbox". - -### Keyboard interactions - -- When a single-select listbox receives focus: - - - If none of the options are selected before the listbox receives focus, the first option receives focus. Optionally, the first option may be automatically selected. - - If an option is selected before the listbox receives focus, focus is set on the selected option. - -- When a multi-select listbox receives focus: - - - If none of the options are selected before the listbox receives focus, focus is set on the first option and there is no automatic change in the selection state. - - If one or more options are selected before the listbox receives focus, focus is set on the first option in the list that is selected. - -- <kbd>Down Arrow</kbd> - - : Moves focus to the next option. Optionally, in a single-select listbox, selection may also move with focus. - -- <kbd>Up Arrow</kbd> - - : Moves focus to the previous option. Optionally, in a single-select listbox, selection may also move with focus. - -- <kbd>Home</kbd> - - (Optional): Moves focus to first option. Optionally, in a single-select listbox, selection may also move with focus. Supporting this key is strongly recommended for lists with more than five options. - -- <kbd>End</kbd> - - (Optional): Moves focus to last option. Optionally, in a single-select listbox, selection may also move with focus. Supporting this key is strongly recommended for lists with more than five options. - -- Type-ahead is recommended for all listboxes, especially those with more than seven options: - - - Type a character: focus moves to the next item with a name that starts with the typed character. - - Type multiple characters in rapid succession: focus moves to the next item with a name that starts with the string of characters typed. - -- **Multiple Selection**: Authors may implement either of two interaction models to support multiple selection: a recommended model that does not require the user to hold a modifier key, such as <kbd>Shift</kbd> or <kbd>Control</kbd>, while navigating the list or an alternative model that does require modifier keys to be held while navigating in order to avoid losing selection states. - - - Recommended selection model — holding modifier keys is not necessary: - - - <kbd>Space</kbd>: changes the selection state of the focused option. - - <kbd>Shift + Down Arrow</kbd> (Optional): Moves focus to and toggles the selected state of the next option. - - <kbd>Shift + Up Arrow</kbd> (Optional): Moves focus to and toggles the selected state of the previous option. - - <kbd>Shift + Space</kbd> (Optional): Selects contiguous items from the most recently selected item to the focused item. - - <kbd>Control + Shift + Home</kbd> (Optional): Selects the focused option and all options up to the first option. Optionally, moves focus to the first option. - - <kbd>Control + Shift + End</kbd> (Optional): Selects the focused option and all options down to the last option. Optionally, moves focus to the last option. - - <kbd>Control + A</kbd> (Optional): Selects all options in the list. Optionally, if all options are selected, it may also unselect all options. - -### Required JavaScript features - -#### selecting an option in a single select listbox - -When the user selects an option, the following must occur: - -1. Deselect the previously selected option, setting the [`aria-selected`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-selected) to `false`, or removing the attribute altogether, changing the appearance of the newly unselected option to appear not selected. -2. Select the newly selected option, setting `aria-selected="true"` on the option and changing the appearance of the newly selected option to appear selected. -3. Update the [`aria-activedescendant`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-activedescendant) value on the listbox to the id of the newly selected option -4. Visually handle the blur, focus, and selected states of the option - -#### Toggling the state of an option in a multi select listbox - -When the user clicks on an option, hits <kbd>Space</kbd> when focused on an option, or otherwise toggles the state of an option, the following must occur: - -1. Toggle the [`aria-selected`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-selected) state of the currently focused option, changing the state of the `aria-selected` to true if it was false or false if it was true. -2. Change the appearance of the option to reflect its selected state -3. Update the [`aria-activedescendant`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-activedescendant) value on the listbox to the ID of the option the user just interacted with, even if they toggled the option to be unselected. - -> [!NOTE] -> The first rule of ARIA use is you can use a native feature with the semantics and behavior you require already built in, instead of re-purposing an element and **adding** an ARIA role, state or property to make it accessible, then do so. The {{HTMLElement('select')}} element with descendant {{HTMLElement('option')}} elements handles all the needed interactions natively. - -## Examples - -### Example 1: A single select listbox that uses `aria-activedescendant` - -The snippet below, using [`aria-activedescendant`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-activedescendant), shows how the listbox role is added directly into the HTML source code. - -```html -<p id="listbox1label" role="label">Select a color:</p> -<div - role="listbox" - tabindex="0" - id="listbox1" - aria-labelledby="listbox1label" - onclick="return listItemClick(event);" - onkeydown="return listItemKeyEvent(event);" - onkeypress="return listItemKeyEvent(event);" - aria-activedescendant="listbox1-1"> - <div role="option" id="listbox1-1" class="selected" aria-selected="true"> - Green - </div> - <div role="option" id="listbox1-2">Orange</div> - <div role="option" id="listbox1-3">Red</div> - <div role="option" id="listbox1-4">Blue</div> - <div role="option" id="listbox1-5">Violet</div> - <div role="option" id="listbox1-6">Periwinkle</div> -</div> -``` - -This could have more easily been handled with the native HTML {{HTMLElement('select')}} and {{HTMLElement('label')}} elements. - -```html -<label for="listbox1">Select a color:</label> -<select id="listbox1"> - <option selected>Green</option> - <option>Orange</option> - <option>Red</option> - <option>Blue</option> - <option>Violet</option> - <option>Periwinkle</option> -</select> -``` - -### More examples - -- [Scrollable Listbox Example](https://www.w3.org/WAI/ARIA/apg/patterns/listbox/examples/listbox-scrollable/): Single-select listbox that scrolls to reveal more options, similar to HTML {{HTMLElement('select')}} with `size` attribute greater than one. -- [Listbox Example with Grouped Options](https://www.w3.org/WAI/ARIA/apg/patterns/listbox/examples/listbox-grouped/): Single-select listbox with grouped options, similar to HTML {{HTMLElement('select')}} with the attribute `size` set to greater than `"1"` and options grouped with `optgroup` elements. -- [Example Listboxes with Rearrangeable Options](https://www.w3.org/WAI/ARIA/apg/patterns/listbox/examples/listbox-rearrangeable/): Examples of both single-select and multi-select listboxes with accompanying toolbars where options can be added, moved, and removed. - -## Best practices - -- To be keyboard-accessible, authors should [manage focus](https://www.w3.org/TR/wai-aria-1.1/#managingfocus) of all descendants of this role. -- It is recommended that authors use different styling for the selection when the list is not focused, e.g. a non-active selection is often shown with a lighter background color. -- If the listbox is not part of another widget, it should have the [`aria-labelledby`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-labelledby) property set. -- If one or more entries are not DOM children of listbox, additional `aria-*` properties will need to be set (see [ARIA Best Practices](https://www.w3.org/WAI/ARIA/apg/patterns/listbox/)). -- If there is a valid reason to [expand](https://www.w3.org/TR/wai-aria-1.1/#aria-expanded) the listbox, the [`combobox`](/en-US/docs/Web/Accessibility/ARIA/Roles/combobox_role) role may be more appropriate. - -## Specifications - -{{Specifications}} - -## See also - -- HTML {{HTMLElement('select')}} element -- HTML {{HTMLElement('label')}} element -- HTML {{HTMLElement('option')}} element -- [ARIA: `combobox` role](/en-US/docs/Web/Accessibility/ARIA/Roles/combobox_role) -- [ARIA: `option` role](/en-US/docs/Web/Accessibility/ARIA/Roles/option_role) -- [ARIA: `list` role](/en-US/docs/Web/Accessibility/ARIA/Roles/list_role) -- [ARIA: `listitem` role](/en-US/docs/Web/Accessibility/ARIA/Roles/listitem_role) -- [ARIA Best Practices – Listbox](https://www.w3.org/WAI/ARIA/apg/patterns/listbox/) -- [ARIA Role Model – Listbox](https://www.w3.org/TR/wai-aria-1.1/#listbox) diff --git a/files/en-us/web/accessibility/aria/roles/listitem_role/index.md b/files/en-us/web/accessibility/aria/roles/listitem_role/index.md deleted file mode 100644 index b103f0f7671619f..000000000000000 --- a/files/en-us/web/accessibility/aria/roles/listitem_role/index.md +++ /dev/null @@ -1,82 +0,0 @@ ---- -title: "ARIA: listitem role" -slug: Web/Accessibility/ARIA/Roles/listitem_role -page-type: aria-role -spec-urls: https://w3c.github.io/aria/#listitem ---- - -{{AccessibilitySidebar}} - -The ARIA `listitem` role can be used to identify an item inside a list of items. It is normally used in conjunction with the [`list`](/en-US/docs/Web/Accessibility/ARIA/Roles/list_role) role, which is used to identify a list container. - -```html -<section role="list"> - <div role="listitem">List item 1</div> - <div role="listitem">List item 2</div> - <div role="listitem">List item 3</div> -</section> -``` - -## Description - -Any content that consists of an outer container with a list of elements inside it can be identified to assistive technologies using the `list` and `listitem` containers respectively. - -There are no hard and fast rules about which elements you should use to mark up the list and list items, but you should make sure that the list items make sense in the context of a list, e.g. a shopping list, recipe steps, driving directions. - -> [!NOTE] -> If at all possible in your work, you should use the appropriate semantic HTML elements to mark up a list and its listitems — {{HTMLElement("ul")}}/{{HTMLElement("ol")}} and {{HTMLElement("li")}}. See [Best practices](#best_practices) for a full example. - -### Associated WAI-ARIA Roles, States, and Properties - -- [`list`](/en-US/docs/Web/Accessibility/ARIA/Roles/list_role) - - : A list of items. Elements with role `list` must have one or more elements with the role `listitem` as children, a one or more elements with the role of `group` that have one or more elements with the `listitem` role as children. -- [`group`](/en-US/docs/Web/Accessibility/ARIA/Roles/group_role) - - : A collection of related objects, limited to list items when nested in a list, not important enough to have their own place in a pages table of contents. - -## Best practices - -Only use `role="list"` and `role="listitem"` if you have to — for example if you don't have control over your HTML but are able to improve accessibility dynamically after the fact with JavaScript. - -If at all possible, you should use the appropriate semantic HTML elements to mark up a list and listitems — {{HTMLElement("ol")}}, {{HTMLElement("ul")}} and {{HTMLElement("li")}}. For example, our above example should be rewritten as follows: - -```html -<ul> - <li>List item 1</li> - <li>List item 2</li> - <li>List item 3</li> -</ul> -``` - -or use an ordered list if the order of the list items matters: - -```html -<ol> - <li>List item 1</li> - <li>List item 2</li> - <li>List item 3</li> -</ol> -``` - -> [!NOTE] -> The ARIA `list` / `listitem` roles don't distinguish between ordered and unordered lists. - -> [!NOTE] -> Styling a list with `list-style: none;` in CSS removes the list semantics. Adding `role="listitem"` returns the semantics. - -> [!NOTE] -> If you are marking up a list of items that will function as a tabbed interface, you should instead use the [`tab`](/en-US/docs/Web/Accessibility/ARIA/Roles/tab_role), [`tabpanel`](/en-US/docs/Web/Accessibility/ARIA/Roles/tabpanel_role), and [`tablist`](/en-US/docs/Web/Accessibility/ARIA/Roles/tablist_role) roles. - -## Specifications - -{{Specifications}} - -## See also - -- [HTML `<li>` element](/en-US/docs/Web/HTML/Element/li) -- [HTML `<ul>` element](/en-US/docs/Web/HTML/Element/ul) -- [HTML `<ol>` element](/en-US/docs/Web/HTML/Element/ol) -- [ARIA: `list` role](/en-US/docs/Web/Accessibility/ARIA/Roles/list_role) -- [ARIA: `group` role](/en-US/docs/Web/Accessibility/ARIA/Roles/group_role) -- [Accessibility Object Model](https://wicg.github.io/aom/spec/) -- [ARIA in HTML](https://w3c.github.io/html-aria/) -- [ARIA Lists examples](https://www.scottohara.me/blog/2018/05/26/aria-lists.html) — by Scott O'Hara diff --git a/files/en-us/web/accessibility/aria/roles/log_role/index.md b/files/en-us/web/accessibility/aria/roles/log_role/index.md deleted file mode 100644 index da391a2866044ea..000000000000000 --- a/files/en-us/web/accessibility/aria/roles/log_role/index.md +++ /dev/null @@ -1,48 +0,0 @@ ---- -title: "ARIA: log role" -slug: Web/Accessibility/ARIA/Roles/log_role -page-type: aria-role -spec-urls: https://w3c.github.io/aria/#log ---- - -{{AccessibilitySidebar}} - -The `log` role is used to identify an element that creates a [live region](/en-US/docs/Web/Accessibility/ARIA/ARIA_Live_Regions) where new information is added in a meaningful order and old information may disappear. - -## Description - -A log is a type of live region where new information is added in meaningful order and old information may disappear. Examples include chat logs, messaging history, game log, or an error log. In contrast to other live regions, in this role there is a relationship between the arrival of new items in the log and the reading order. The log contains a meaningful sequence and new information is added only to the end of the log, not at arbitrary points. - -In contrast to other types of live region, a log is sequentially ordered and new information is only added to the end of the log. When this role is added to an element, the browser will send out an accessible log event to assistive technology products which can then notify the user about it. - -By default, updates contain only the changes to the live region and these are announced when the user is idle. Elements with the role `log` have an implicit `aria-live` value of `polite`. Where the user needs to hear the entire live region upon a change `aria-atomic="true"` should be set. To have announcements made as soon as possible and where the user may be interrupted, `aria-live="assertive"` can be set for more aggressive updates. - -### Associated WAI-ARIA roles, states, and properties - -- `aria-atomic` - - - : Defines whether assistive technologies should present all, or only parts of, the changed region. Elements with the role `log` have an implicit [aria-atomic](https://www.w3.org/TR/wai-aria-1.1/#aria-atomic) value of `false`. - -- `aria-live` - - - : Defines when assistive technology should inform the user of updates to content. Elements with the role `log` have an implicit [aria-live](https://www.w3.org/TR/wai-aria-1.1/#aria-live) value of `polite`, meaning screen readers will announce changes inside the log when the user is idle. - -- `aria-label` and `aria-labelledby` - - - : The `log` is required to have an accessible name. Use `aria-labelledby` if a visible label is present, otherwise use `aria-label`. - -## Best Practices - -With an area that has scrolling text, such as a stock ticker, the [`marquee`](/en-US/docs/Web/Accessibility/ARIA/Roles/marquee_role) role should be used instead. - -## Specifications - -{{Specifications}} - -## See also - -- [ARIA: `alert` role](/en-US/docs/Web/Accessibility/ARIA/Roles/alert_role) -- [ARIA: `marquee` role](/en-US/docs/Web/Accessibility/ARIA/Roles/marquee_role) -- [ARIA: `status` role](/en-US/docs/Web/Accessibility/ARIA/Roles/status_role) -- [ARIA: `timer` role](/en-US/docs/Web/Accessibility/ARIA/Roles/timer_role) -- [ARIA live regions](/en-US/docs/Web/Accessibility/ARIA/ARIA_Live_Regions) diff --git a/files/en-us/web/accessibility/aria/roles/main_role/index.md b/files/en-us/web/accessibility/aria/roles/main_role/index.md deleted file mode 100644 index f032396c7608b03..000000000000000 --- a/files/en-us/web/accessibility/aria/roles/main_role/index.md +++ /dev/null @@ -1,130 +0,0 @@ ---- -title: "ARIA: main role" -slug: Web/Accessibility/ARIA/Roles/main_role -page-type: aria-role -spec-urls: - - https://w3c.github.io/aria/#main - - https://www.w3.org/WAI/ARIA/apg/patterns/landmarks/examples/main.html ---- - -{{AccessibilitySidebar}} - -The `main` landmark role is used to indicate the primary content of a document. The main content area consists of content that is directly related to or expands upon the central topic of a document, or the main function of an application. - -```html -<div id="main" role="main"> - <h1>Avocados</h1> - <!-- main section content --> -</div> -``` - -This is the main section of a document that discusses avocados. Subsections of this document could discuss their history, the different types, regions where they grow, etc. - -## Description - -The `main` role is a navigational [landmark](/en-US/docs/Web/Accessibility/ARIA/Roles#3._landmark_roles) role identifying the main content of a document. Landmarks can be used by assistive technology such as screen readers to quickly identify and navigate to large sections of the document. - -By classifying and labeling sections of a page, structural information conveyed visually through layout can be represented programmatically. Screen readers use landmark roles to provide keyboard navigation to important sections of a page. For those navigating via landmark roles, the main role is an alternative for "skip to main content" links. - -There should only be one `main` landmark role per document. - -The {{HTMLElement('main')}} element has a role of `main`. Developers should use semantic HTML — in this case {{HTMLElement('main')}} — over using ARIA. - -### Associated ARIA roles, states, and properties - -- [`aria-owns`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-owns) - - - : The `aria-owns` attribute establishes relationships in the accessibility layer that aren't present in the DOM. Documents and applications can be nested in the DOM, which may lead to having more than one main element as DOM descendants. If this is the case, include `aria-owns` to identify the relationship of the main to its document or application ancestor. - -- [`aria-label`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-label) or `aria-labelledby` - - - : Identify the accessible name with [`aria-labelledby`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-labelledby) if a visible header is present. Otherwise, including an [`aria-label`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-label) can be helpful for orienting assistive technology users, especially in single-page applications where main content changes happen without generating a page load event. - -## Example - -```html -<body> - <!-- primary navigation --> - - <div role="main"> - <h1>The First Indochina War</h1> - <!-- article content --> - </div> - - <!-- sidebar and footer --> -</body> -``` - -## Accessibility concerns - -### Use only one `main` role per document - -The `main` [landmark role](/en-US/docs/Web/Accessibility/ARIA/Roles#3._landmark_roles) should only be used once per document. - -If a document contains two `main` roles, say updating page content when triggered by JavaScript, the inactive `main` role's presence should be removed from assistive technology via techniques such as toggling the [`hidden` attribute](/en-US/docs/Web/HTML/Global_attributes/hidden). - -```html -<main> - <h1>Active `main` element</h1> - <!-- content --> -</main> - -<main hidden> - <h1>Hidden `main` element</h1> - <!-- content --> -</main> -``` - -It is also helpful to include an accessible name to help orient assistive technology users, especially in single-page applications where main content changes happen without generating a page load event. This can be added with `aria-labelledby` if there is an appropriate name in the content, or `aria-label` if not. - -## Best practices - -### Prefer HTML - -Using the {{HTMLElement('main')}} element will automatically communicate a section has a role of `main`. If at all possible, prefer using it instead. - -### Skip navigation - -Skip navigation, also known as "skipnav", is a technique that allows an assistive technology user to quickly bypass large sections of repeated content (main navigation, info banners, etc.). This allows the user to access the main content of the page faster. - -Adding an [`id` attribute](/en-US/docs/Web/HTML/Global_attributes/id) to the element with a declaration of `role="main"` allows it to be a target of a skip navigation link users. - -```html -<body> - <a href="#main-content">Skip to main content</a> - - <!-- navigation and header content --> - - <div id="main-content" role="main"> - <!-- main page content --> - </div> -</body> -``` - -Which is the equivalent of: - -```html -<body> - <a href="#main-content">Skip to main content</a> - - <!-- navigation and header content --> - - <main id="main-content"> - <!-- main page content --> - </main> -</body> -``` - -- [WebAIM: "Skip Navigation" Links](https://webaim.org/techniques/skipnav/) - -## Specifications - -{{Specifications}} - -## See also - -- The {{HTMLElement('main')}} element -- [Using HTML sections and outlines](/en-US/docs/Web/HTML/Element/Heading_Elements) -- [Using WAI-ARIA Landmarks – 2013 | The Paciello Group](https://www.tpgi.com/using-wai-aria-landmarks-2013/) -- [Accessible Landmarks | scottohara.me](https://www.scottohara.me/blog/2018/03/03/landmarks.html) -- [The main element | HTML5 Doctor](https://html5doctor.com/the-main-element/) diff --git a/files/en-us/web/accessibility/aria/roles/mark_role/index.md b/files/en-us/web/accessibility/aria/roles/mark_role/index.md deleted file mode 100644 index 0d0d372fdfc6963..000000000000000 --- a/files/en-us/web/accessibility/aria/roles/mark_role/index.md +++ /dev/null @@ -1,55 +0,0 @@ ---- -title: "ARIA: mark role" -slug: Web/Accessibility/ARIA/Roles/mark_role -page-type: aria-role ---- - -{{AccessibilitySidebar}} - -The `mark` role denotes content which is marked or highlighted for reference or notation purposes, due to the content's relevance in the enclosing context. - -## Description - -The `mark` role semantically denotes HTML elements containing text that is marked/highlighted for reference purposes. This is semantically equivalent to the HTML {{HTMLElement('mark')}} element. If possible, you should use this element instead. - -Example uses for `mark` are the exact same as the `<mark>` element. They include highlighting text in a quotation which is of special interest but is not marked in the original source material, comparable to using a highlighter pen to mark passages of a print article and indicating portions of the content that are relevant to the user's current activity, such as highlighting text matches found by a search feature. - -Don't use `mark` for purely decorative styling such as syntax highlighting. - -The `mark` element should not be given an accessible name; both [`aria-label`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-label) and [`aria-labelledby`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-labelledby) attributes are prohibited on `mark`. - -## Examples - -In the following example we have a document section that has been commented. The commented section is marked up using `<span role="mark">`. - -```html -<p> - The last half of the song is a slow-rising crescendo that peaks at the - <span role="mark" aria-details="thread-1">end of the guitar solo</span>, - before fading away sharply. -</p> - -<div role="comment" id="thread-1" data-author="chris"> - <h3>Chris said</h3> - <p class="comment-text">I really think this moment could use more cowbell.</p> - <p><time datetime="2022-03-30T19:29">March 30 2022, 19:29</time></p> -</div> -``` - -The related comment is marked up using an HTML structure wrapped with a {{HTMLElement('div')}} containing [`role="comment"`](/en-US/docs/Web/Accessibility/ARIA/Roles/comment_role). - -To associate the comment with the text being commented, we need to wrap the commented text with an element containing the [`aria-details`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-details) attribute, the value of which should be the ID of the comment. - -## Best practices - -### Prefer HTML - -Using the {{HTMLElement('mark')}} element will automatically communicate a node has a role of `mark`. If at all possible, prefer using it instead. - -## Specifications - -Will be part of [WAI-ARIA 1.3](https://w3c.github.io/aria/#mark), which is still being drafted. - -## See also - -- HTML {{HTMLElement('mark')}} element diff --git a/files/en-us/web/accessibility/aria/roles/marquee_role/index.md b/files/en-us/web/accessibility/aria/roles/marquee_role/index.md deleted file mode 100644 index 91d41624404b657..000000000000000 --- a/files/en-us/web/accessibility/aria/roles/marquee_role/index.md +++ /dev/null @@ -1,40 +0,0 @@ ---- -title: "ARIA: marquee role" -slug: Web/Accessibility/ARIA/Roles/marquee_role -page-type: aria-role -spec-urls: https://w3c.github.io/aria/#marquee ---- - -{{AccessibilitySidebar}} - -A `marquee` is a type of [live region](/en-US/docs/Web/Accessibility/ARIA/ARIA_Live_Regions) containing non-essential information which changes frequently. - -## Description - -The `marquee` role defines an area as a type of live region that presents non-essential information that changes frequently. Examples of marquees include stock tickers and ad banners; information that is not necessarily sought out by the user that may be presented in any order. The main difference between a `marquee` and a [`log`](/en-US/docs/Web/Accessibility/ARIA/Roles/log_role) is that log information is presented in a meaningful order such as a by date. - -Elements with the role marquee have an implicit [aria-live](/en-US/docs/Web/Accessibility/ARIA/ARIA_Live_Regions) value of `off`. - -The marquee is required to have an accessible name. Use [`aria-labelledby`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-labelledby) if a visible label is present, otherwise use [`aria-label`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-label). - -### Associated WAI-ARIA roles, states, and properties - -- [`aria-live`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-live) - - - : Defines when assistive technology should inform the user of updates to content. Elements with the role `marquee` have an implicit [aria-live](https://www.w3.org/TR/wai-aria-1.1/#aria-live) value of `off`, meaning screen readers will not announce changes inside the marquee, even when the user is idle. - -- [`aria-label`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-label) or [`aria-labelledby`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-labelledby) - - - : The `marquee` is required to have an accessible name. Use `aria-labelledby` if a visible label is present, otherwise use `aria-label`. - -## Specifications - -{{Specifications}} - -## See also - -- [ARIA: `alert` role](/en-US/docs/Web/Accessibility/ARIA/Roles/alert_role) -- [ARIA: `log` role](/en-US/docs/Web/Accessibility/ARIA/Roles/log_role) -- [ARIA: `status` role](/en-US/docs/Web/Accessibility/ARIA/Roles/status_role) -- [ARIA: `timer` role](/en-US/docs/Web/Accessibility/ARIA/Roles/timer_role) -- [ARIA live regions](/en-US/docs/Web/Accessibility/ARIA/ARIA_Live_Regions) diff --git a/files/en-us/web/accessibility/aria/roles/math_role/index.md b/files/en-us/web/accessibility/aria/roles/math_role/index.md deleted file mode 100644 index 743af46492b39bd..000000000000000 --- a/files/en-us/web/accessibility/aria/roles/math_role/index.md +++ /dev/null @@ -1,50 +0,0 @@ ---- -title: "ARIA: math role" -slug: Web/Accessibility/ARIA/Roles/math_role -page-type: aria-role -spec-urls: https://w3c.github.io/aria/#math ---- - -{{AccessibilitySidebar}} - -The `math` role indicates that the content represents a mathematical expression. - -## Description - -Content with the role `math` is intended to be marked up in an accessible format such as [MathML](/en-US/docs/Web/MathML), or with another type of textual representation, which can be converted to an accessible format by the browser or a polyfill library. - -Unfortunately, browser support for MathML is not universal. While using an image of a mathematical expression is not optimal, if you do use image, use the `math` role. -Make sure any images of math are labeled by an `alt` attribute that describes the mathematical expression as it would be spoken. - -If the math element has only presentational children and the accessible name is intended to convey the mathematical expression, use [`aria-label`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-label) to provide a string that represents the expression. If the math element contains navigable content that conveys the mathematical expression and a visible label for the expression is present, use [`aria-labelledby`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-labelledby). Otherwise, use `aria-label` to name the expression, e.g., `aria-label="Pythagorean Theorem"`. - -## Examples - -If you use image or non-semantic HTML to create an equation, use the `math` role. - -<div role="math" aria-label="a^{2} + b^{2} = c^{2}"> - a<sup>2</sup> + b<sup>2</sup> = c<sup>2</sup> -</div> - -The above pythagorean theorem is written accessibly as: - -```html -<div role="math" aria-label="a^{2} + b^{2} = c^{2}"> - a<sup>2</sup> + b<sup>2</sup> = c<sup>2</sup> -</div> -``` - -Had an image been used, the `alt` attribute would be used along with the `math` role: - -```html -<img src="pythagorean_theorem.gif" alt="a^{2} + b^{2} = c^{2}" role="math" /> -``` - -## Specifications - -{{Specifications}} - -## See also - -- [MathML on MDN](/en-US/docs/Web/MathML) and the [`<math>`](/en-US/docs/Web/MathML/Element/math) element (not HTML) -- [The MathML specification](https://www.w3.org/TR/MathML3/) diff --git a/files/en-us/web/accessibility/aria/roles/menu_role/index.md b/files/en-us/web/accessibility/aria/roles/menu_role/index.md deleted file mode 100644 index 9d2bca8c5d8677f..000000000000000 --- a/files/en-us/web/accessibility/aria/roles/menu_role/index.md +++ /dev/null @@ -1,196 +0,0 @@ ---- -title: "ARIA: menu role" -slug: Web/Accessibility/ARIA/Roles/menu_role -page-type: aria-role -spec-urls: - - https://w3c.github.io/aria/#menu - - https://www.w3.org/WAI/ARIA/apg/patterns/menubar/examples/menubar-navigation/ ---- - -{{AccessibilitySidebar}} - -The `menu` role is a type of composite widget that offers a list of choices to the user. - -## Description - -A `menu` generally represents a grouping of common actions or functions that the user can invoke. The `menu` role is appropriate when a list of menu items is presented in a manner similar to a menu on a desktop application. Submenus, also known as pop-up menus, also have the role `menu`. - -While the term "menu" is a generically used term to describe site navigation, the `menu` role is for a list of actions or functions that require complex functionality, such as composite widget focus management and first-character navigation - -A menu can be a permanently visible list of controls or a widget that can be made to open and close. A closed `menu` widget is usually opened, or made visible, by activating a menu button, choosing an item in a menu that opens a submenu, or by invoking a command, such as <kbd>Shift + F10</kbd> in Windows which opens a context specific menu. - -When a user activates a choice in a menu that has been opened, the menu usually closes. If the menu choice action invokes a submenu, the menu will remain open and the submenu is displayed. - -When a menu opens, keyboard focus is placed on the first menu item. To be keyboard accessible, you need to [manage focus](https://usability.yale.edu/web-accessibility/articles/focus-keyboard-operability) for all descendants: all menu items within the `menu` are focusable. The menu button which opens the menu and the menu items, rather than the menu itself, are the focusable elements. - -Menu items include [`menuitem`](/en-US/docs/Web/Accessibility/ARIA/Roles/menuitem_role), [`menuitemcheckbox`](/en-US/docs/Web/Accessibility/ARIA/Roles/menuitemcheckbox_role), and [`menuitemradio`](/en-US/docs/Web/Accessibility/ARIA/Roles/menuitemradio_role). [Disabled](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-disabled) menu items are focusable but cannot be activated. - -Menu items can be grouped in elements with the [`group`](/en-US/docs/Web/Accessibility/ARIA/Roles/group_role) role, and separated by elements with role [`separator`](/en-US/docs/Web/Accessibility/ARIA/Roles/separator_role). Neither `group` nor `separator` receive focus or are interactive. - -If a `menu` is opened as a result of a context action, <kbd>Escape</kbd> or <kbd>Enter</kbd> may return focus to the invoking context. If focus was on the menu button, <kbd>Enter</kbd> opens the menu, giving focus to the first menu item. If focus is on the menu itself, <kbd>Escape</kbd> closes the menu and returns focus to the menu button or parent menubar item (or the context action that opened the menu). - -Elements with the role `menu` have an implicit [`aria-orientation`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-orientation) value of `vertical`. For horizontally oriented menu, use [`aria-orientation="horizontal"`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-orientation). - -If the menu is visually persistent, consider the [`menubar`](/en-US/docs/Web/Accessibility/ARIA/Roles/menubar_role) role instead. - -### Associated WAI-ARIA roles, states, and properties - -- [`menuitem`](/en-US/docs/Web/Accessibility/ARIA/Roles/menuitem_role), [`menuitemcheckbox`](/en-US/docs/Web/Accessibility/ARIA/Roles/menuitemcheckbox_role), and [`menuitemradio`](/en-US/docs/Web/Accessibility/ARIA/Roles/menuitemradio_role) roles - - : Roles of items contained in a containing `menu` or `menubar`, known collectively as "menu items". These must be able to receive focus. -- [`group`](/en-US/docs/Web/Accessibility/ARIA/Roles/group_role) role - - : Menu items can be nested in a [`group`](/en-US/docs/Web/Accessibility/ARIA/Roles/group_role) -- [`separator`](/en-US/docs/Web/Accessibility/ARIA/Roles/separator_role) role - - - : A divider that separates and distinguishes sections of content or groups of menu items within the menu - -- [`tabindex`](/en-US/docs/Web/HTML/Global_attributes/tabindex) attribute - - : The `menu` container has `tabindex` set to `-1` or `0` and each item in the menu has `tabindex` set to `-1`. -- [`aria-activedescendant`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-activedescendant) - - : Set to the ID of the focused item, if there is one. -- [`aria-orientation`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-orientation) - - : indicates whether the menu orientation is horizontal or vertical; defaults to `vertical` if omitted. -- [`aria-label`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-label) or [`aria-labelledby`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-labelledby) - - : The `menu` is required to have an accessible name. Use `aria-labelledby` if a visible label is present, otherwise use `aria-label`. Either include the `aria-labelledby` set to a the `id` to the `menuitem` or `button` that controls its display or use `aria-label` to define the label. -- [`aria-owns`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-owns) - - : Only set on the menu container to include elements that are not DOM children of the container. If set, those elements will appear in the reading order in the sequence they are referenced and after any items that are DOM children. When managing focus, ensure the visual focus order matches this assistive technology reading order. - -### Keyboard interactions - -- <kbd>Space</kbd> / <kbd>Enter</kbd> - - : If the item is a parent menu item, it opens the submenu and moves focus to the first item in the submenu. Otherwise, activates the menu item, which loads new content and places focus on the heading that titles the content. -- <kbd>Escape</kbd> - - : When in a submenu, it closes the submenu and moves focus to the parent menu or menubar item. -- <kbd>Right Arrow</kbd> - - : In a menubar, moves focus to the next item in the menubar. If focus is on the last item, it moves focus to the first item. If in a submenu, if focus is on an item that does not have a submenu, it closes the submenu and moves focus to the next item in the menubar. Otherwise, it opens the submenu of the newly focused menubar item, keeping focus on that parent menubar item. If not in a menubar or submenu and not on a `menuitem` with a submenu, if focus is not the last focusable element in the menu, it optionally moves focus to the next focusable element. -- <kbd>Left Arrow </kbd> - - : Moves focus to the previous item in the menubar. If focus is on the first item, it moves focus to the last item. If in a submenu, it closes the submenu and moves focus to the parent menu item. If not in a menubar or submenu, if focus is not the first focusable element in the menu, it optionally moves focus to the last focusable element. -- <kbd>Down Arrow</kbd> - - : Opens submenu and moves focus to the first item in the submenu. -- <kbd>Up Arrow</kbd> - - : Opens submenu and moves focus to the last item in the submenu. -- <kbd>Home</kbd> - - : Moves focus to the first item in the menubar. -- <kbd>End</kbd> - - : Moves focus to the last item in the menubar. -- Any character key - - : Moves focus to the next item in the menubar having a name that starts with the typed character. If none of the items have a name starting with the typed character, focus does not move. - -## Examples - -Below are two example menu implementations. - -### Example 1: navigation menu - -```html -<div> - <button id="menubutton" aria-haspopup="true" aria-controls="menu"> - <img src="hamburger.svg" alt="Page Sections" /> - </button> - <ul id="menu" role="menu" aria-labelledby="menubutton"> - <li role="presentation"> - <a role="menuitem" href="#description">Description</a> - </li> - <li role="presentation"> - <a - role="menuitem" - href="#associated_wai-aria_roles_states_and_properties"> - Associated WAI-ARIA roles, states, and properties - </a> - </li> - <li role="presentation"> - <a role="menuitem" href="#keyboard_interactions"> - Keyboard interactions - </a> - </li> - <li role="presentation"> - <a role="menuitem" href="#examples">Examples</a> - </li> - <li role="presentation"> - <a role="menuitem" href="#specifications">Specifications</a> - </li> - <li role="presentation"> - <a role="menuitem" href="#see_also">See Also</a> - </li> - </ul> -</div> -``` - -To progressively enhance this navigation widget that is by default accessible, the class to hide the `menu` and the inclusion of `tabindex="-1"` on the interactive menuitem content should be added with JavaScript on load. - -When including a "menu" for site navigation, do not use the `menu` role. Rather, for the main site navigation use the native HTML {{HTMLElement('nav')}} element or simply a list of links. The `menu` role should be reserved for composite widgets requiring focus management. See [ARIA practices for disclosure navigation](https://www.w3.org/TR/wai-aria-practices-1.2/examples/disclosure/disclosure-navigation.html) for an explanation and additional examples. - -### Example 2: menubar submenu option picker - -The following snippet of code is a popup menu nested in a menubar. It is displayed when the menu button is activated. It is a menu to select the text color from a list of color options: - -```html -<div> - <button - type="button" - aria-haspopup="menu" - aria-controls="colormenu" - tabindex="0" - aria-label="Text Color: purple"> - Purple - <span></span> - </button> - <ul role="menu" id="colormenu" aria-label="Color Options" tabindex="-1"> - <li - role="menuitemradio" - aria-checked="true" - style="color: purple" - tabindex="-1"> - Purple - </li> - <li - role="menuitemradio" - aria-checked="false" - style="color: magenta" - tabindex="-1"> - Magenta - </li> - <li - role="menuitemradio" - aria-checked="false" - style="color: black;" - tabindex="-1"> - Black - </li> - </ul> -</div> -``` - -The button that opens the menu has [`aria-haspopup="menu"`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-haspopup) set, explicitly indicating that the popup it controls is a `menu`. - -For a menu to open, the user generally interacts with a menu button as the opener. The menu button must be focusable and respond to both click and keyboard events. When focused, selecting <kbd>Enter</kbd>, <kbd>Space</kbd>, <kbd>Down Arrow</kbd>, or the <kbd>Up Arrow</kbd> should open the menu and place focus on a menu item. - -The opening and closing of the menu toggles the [`aria-expanded="true"`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-expanded) attribute on the button. It is added when the menu is open. Removed or set to `false` when the menu is closed. The `true` value indicates that the menu is displayed and that activating the menu button closes the menu. - -When the menu is open, the button itself generally does not receive focus as users arrow through the menu items. Rather, <kbd>Escape</kbd> and optionally <kbd>Shift + Tab</kbd> closes the menu and returns focus to the menu button. - -The `menu` role was set on the {{HTMLElement('ul')}}, identifying the `<ul>` element as a menu. - -The showing and hiding of the menu can be done with CSS. For example, in these code examples we can use the attribute and next-sibling selectors to toggle the visibility of the menu: - -```css -[role="menu"] { - display: none; -} -[aria-expanded="true"] + [role="menu"] { - display: block; -} -``` - -The navigation example has a static button. The submenu example has a button that gets updated when the user selects a new value. In this case, the `aria-label="Text Color: purple"` is set on the `menu` element. It defines the accessible name for the menu as "Text color: purple"; identifying the purpose of the menu (selecting a text color) and the current value (purple). When a new color is selected, the value of the `aria-label` property should be updated as well. - -## Specifications - -{{Specifications}} - -## See also - -- [`menubar`](/en-US/docs/Web/Accessibility/ARIA/Roles/menubar_role) -- [`menuitem`](/en-US/docs/Web/Accessibility/ARIA/Roles/menuitem_role) -- [`menuitemcheckbox`](/en-US/docs/Web/Accessibility/ARIA/Roles/menuitemcheckbox_role) -- [`menuitemradio`](/en-US/docs/Web/Accessibility/ARIA/Roles/menuitemradio_role) -- [`aria-haspopup`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-haspopup) diff --git a/files/en-us/web/accessibility/aria/roles/menubar_role/index.md b/files/en-us/web/accessibility/aria/roles/menubar_role/index.md deleted file mode 100644 index fbb054dad797c01..000000000000000 --- a/files/en-us/web/accessibility/aria/roles/menubar_role/index.md +++ /dev/null @@ -1,94 +0,0 @@ ---- -title: "ARIA: menubar role" -slug: Web/Accessibility/ARIA/Roles/menubar_role -page-type: aria-role -spec-urls: - - https://w3c.github.io/aria/#menubar - - https://www.w3.org/WAI/ARIA/apg/patterns/menubar/examples/menubar-navigation/ ---- - -{{AccessibilitySidebar}} - -A `menubar` is a presentation of `menu` that usually remains visible and is usually presented horizontally. - -## Description - -A menu is a widget that offers a list of choices to the user, such as a set of actions or functions. The menubar type of menu is usually presented as a persistently visible horizontal bar of commands. Menubars behave like native operating system menubars, such as the menubars containing pull down menus, commonly found at the top of many desktop application windows. - -The `menubar` role is used to create a menu bar similar to those found near the top of the window in many desktop applications, visually persistent, typically horizontal, bar of menu items offering the user quick access to a consistent set of commands. - -A `menubar` contains three types of menu items, including [`menuitem`](/en-US/docs/Web/Accessibility/ARIA/Roles/menuitem_role), [`menuitemradio`](/en-US/docs/Web/Accessibility/ARIA/Roles/menuitemradio_role) and [`menuitemcheckbox`](/en-US/docs/Web/Accessibility/ARIA/Roles/menuitemcheckbox_role). These menu items may optionally be nested in one or more [`group`](/en-US/docs/Web/Accessibility/ARIA/Roles/group_role) containers. Groups or items may optionally by separated with [`separator`](/en-US/docs/Web/Accessibility/ARIA/Roles/separator_role) elements. While every menu item must be able to receive focus, even if disabled, the `group` and `separator` elements are not focusable. - -An example of a native menubar is the bar which may be present at the top of the screen if you are reading this in a desktop browser. An example of a web-based menubar is the horizontal menu bar that reads "File Edit View Insert Format", etc., which is usually visible under the document name in a Google doc. - -Menubar interactions should be similar to the typical menu bar interaction in a desktop graphical user interface. In Google Docs, each of those menu items is a `menuitem` with a popup submenu, so each has an `aria-haspopup` attribute set to `true`. The `menubar` element does not. - -The menubar and all the menu items are focusable and have a [tabindex](/en-US/docs/Web/HTML/Global_attributes/tabindex) attribute set. When the menubar receives focus through tabbing, keyboard focus is placed on the first menuitem. Each item in the menu has `tabindex` set to `-1`, except the first item has which has its `tabindex` set to `0`. - -If a menubar receives focus as a result of a context action, such as a shortcut key, <kbd>Escape</kbd> or <kbd>Enter</kbd> may return focus to the invoking context. That said, make sure not to create shortcut keys that interfere with user agent, operating system, or assistive technology shortcuts - any UA, OS, or AT. - -Every menu item, no matter how deeply nested, is able to receive focus, even if disabled. - -If a `menubar` has a visible label, include [`aria-labelledby`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-labelledby) set to a value that refers to the labelling element. Otherwise, provide the menubar with an accessible name by including a descriptive [`aria-label`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-label). - -A `menuitem` element in the `menubar` can contain a child submenu of menu items. Submenus can be nested several deep. Generally, the outer `menubar` is horizontal and all the submenus are vertical. If this is not the case, if your menubar is vertical, include [`aria-orientation="vertical"`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-orientation) on the `menubar` element. Otherwise, this attribute is not necessary, as the default value is horizontal. - -### Associated WAI-ARIA roles, states, and properties - -- [`group`](/en-US/docs/Web/Accessibility/ARIA/Roles/group_role) role - - : Identifies a set of menu items -- [`menuitem`](/en-US/docs/Web/Accessibility/ARIA/Roles/menuitem_role) role - - : An option in a set of choices contained by a `menubar`. May have a submenu. -- [`menuitemradio`](/en-US/docs/Web/Accessibility/ARIA/Roles/menuitemradio_role) role - - : A checkable menu item in a set of elements with the same role, only one of which can be checked at a time. -- [`menuitemcheckbox`](/en-US/docs/Web/Accessibility/ARIA/Roles/menuitemcheckbox_role) role - - : a menu item with a checkable state whose possible values are `true`, `false`, or `mixed`. -- [`aria-orientation`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-orientation) - - : Include `aria-orientation="vertical"` on `menubar` element if it's the menubar is vertical. The default orientation is `horizontal`. - -### Keyboard interactions - -When focus is in a `menubar` it is always on a menu item within the menu bar. When focus is on a top level `menuitem` in a menu bar, the following keyboard interactions must be supported: - -- <kbd>Down Arrow</kbd> - - : If the currently focused `menuitem` has a submenu, opens the submenu and places focus on the first item in the submenu. -- <kbd>Up Arrow</kbd> - - : (Optional) If the currently focused `menuitem` has a submenu, opens the submenu and places focus on the _last_ item in the submenu. -- <kbd>Right Arrow</kbd> - - : Moves focus to the next item, optionally wrapping from the last to the first. -- <kbd>Left Arrow</kbd> - - : Moves focus to the previous item, optionally wrapping from the first to the last. -- <kbd>Home</kbd> - - : If arrow key wrapping is not supported, moves focus to the first item in the `menubar`. -- <kbd>End</kbd> - - : If arrow key wrapping is not supported, moves focus to the last item in the `menubar`. -- <kbd>Tab</kbd> - - : Moves focus to the next element in the tab sequence. If that makes it exit the menubar, all submenus in the menubar get closed. -- <kbd>shift + Tab</kbd> - - : Moves focus to the previous element in the tab sequence. If that makes it exit the menubar, all submenus in the menubar get closed. - -See [`menuitem` keyboard interactions](/en-US/docs/Web/Accessibility/ARIA/Roles/menuitem_role#keyboard_interactions), [`menuitemradio` keyboard interactions](/en-US/docs/Web/Accessibility/ARIA/Roles/menuitemradio_role#keyboard_interactions), and [`menuitemcheckbox` keyboard interactions](/en-US/docs/Web/Accessibility/ARIA/Roles/menuitemcheckbox_role#keyboard_interactions) for more information on keyboard interactions when focus is on a menuitem in a menubar (which it always is). - -Note: The above interactions assumed the `menubar` is horizontal. If the `menubar` is vertical, include `aria-orientation="vertical"` and change the following keyboard keys accordingly: - -- <kbd>Down Arrow</kbd> - - : Performs like the <kbd>Right Arrow</kbd> as described above. -- <kbd>Up Arrow</kbd> - - : Performs like the <kbd>Left Arrow</kbd> as described above -- <kbd>Right Arrow</kbd> - - : Performs like the <kbd>Down Arrow</kbd> as described above. -- <kbd>Left Arrow</kbd> - - : Performs as the <kbd>Up Arrow</kbd> as described above - -## Examples - -- [W3C WAI-ARIA practices: navigation `menubar` example](https://www.w3.org/WAI/ARIA/apg/patterns/menubar/examples/menubar-navigation/) -- [W3C WAI-ARIA practices: editor `menubar` example](https://www.w3.org/WAI/ARIA/apg/patterns/menubar/examples/menubar-editor/) - -## Specifications - -{{Specifications}} - -## See also - -- [`toolbar` role](/en-US/docs/Web/Accessibility/ARIA/Roles/toolbar_role) diff --git a/files/en-us/web/accessibility/aria/roles/menuitem_role/index.md b/files/en-us/web/accessibility/aria/roles/menuitem_role/index.md deleted file mode 100644 index 997c65d9281beb7..000000000000000 --- a/files/en-us/web/accessibility/aria/roles/menuitem_role/index.md +++ /dev/null @@ -1,117 +0,0 @@ ---- -title: "ARIA: menuitem role" -slug: Web/Accessibility/ARIA/Roles/menuitem_role -page-type: aria-role -spec-urls: - - https://w3c.github.io/aria/#menuitem - - https://www.w3.org/WAI/ARIA/apg/patterns/menubar/examples/menubar-navigation/ ---- - -{{AccessibilitySidebar}} - -The `menuitem` role indicates the element is an option in a set of choices contained by a `menu` or `menubar`. - -## Description - -A `menuitem` is one of the three types of options in a set of choices contained by a [`menu`](/en-US/docs/Web/Accessibility/ARIA/Roles/menu_role) or [`menubar`](/en-US/docs/Web/Accessibility/ARIA/Roles/menubar_role); the other two being [`menuitemcheckbox`](/en-US/docs/Web/Accessibility/ARIA/Roles/menuitemcheckbox_role) and [`menuitemradio`](/en-US/docs/Web/Accessibility/ARIA/Roles/menuitemradio_role). The `menuitem` is only found as a descendant of, or owned by, elements with role `menu` or `menubar`, optionally nested within an element with role [`group`](/en-US/docs/Web/Accessibility/ARIA/Roles/group_role) that is contained in, or owned by, a menu. - -If the `menuitem` is not a descendant of a menu in the DOM, include the [`aria-owns`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-owns) attribute on menu to indicate the relationship. If `aria-owns` is set on the menu container to include elements that are not DOM children of the container, those elements will appear in the reading order in the sequence they are referenced and after any items that are DOM children in supporting technologies. Ensure the visual focus order matches the assistive technology reading order. - -Every `menuitem` in a menu is focusable, whether or not it is disabled. Indicate a `menuitem` is disabled by setting [`aria-disabled="true"`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-disabled) on the element with the role. - -If a `menuitem` has a submenu, program it to display a new sub-level menu when the menu item is activated and include [`aria-haspopup="menu"`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-haspopup) or with the `true` value to indicate to assistive technologies that the menu item is used to open a submenu. - -A common convention for indicating that a `menuitem` launches a dialog box is to append "…" (ellipsis) to the menu item label, e.g., "Save as …". - -Every `menuitem` must have an accessible name. This name comes from the element's contents by default. If the contents don't provide for a useful accessible name, [`aria-labelledby`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-labelledby) can be used to reference visible label. If no visible content is available to provide the accessible name, an accessible name can be provided with [`aria-label`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-label). - -## Associated WAI-ARIA roles, states, and properties - -- [`menu`](/en-US/docs/Web/Accessibility/ARIA/Roles/menu_role) role - - : A widget providing a list of choices. Required context role (or `menubar`) -- [`menubar`](/en-US/docs/Web/Accessibility/ARIA/Roles/menubar_role) role - - : A presentation of a `menu` that usually remains visible and is usually presented horizontally. Required context role (or `menu`) -- [`group`](/en-US/docs/Web/Accessibility/ARIA/Roles/group_role) role - - : Can be used to identify a set of related `menuitem`s within or otherwise owned by a `menu` or `menubar` -- [`aria-disabled`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-disabled) - - : Indicates the element is perceivable but disabled, so it is not operable -- [`aria-haspopup`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-haspopup) - - : Indicates the availability and type of interactive popup that can be triggered by the `menuitem` - -## Keyboard interactions - -- <kbd>Enter</kbd> and <kbd>Space</kbd> - - : If the `menuitem` has a submenu, opens the submenu and places focus on its first item. Otherwise, activates the item and closes the menu. -- <kbd>Down Arrow</kbd> - - : On a `menuitem` that has a submenu in a `menubar`, opens the submenu and places focus on the first item in the submenu. Otherwise, moves focus to the next item, optionally wrapping from the last to the first. -- <kbd>Up Arrow</kbd> - - : Moves focus to the previous item, optionally wrapping from the first to the last. Optionally, if the `menuitem` is in a menubar and has a submenu, opens the submenu and places focus on the last item in the submenu. -- <kbd>Right Arrow</kbd> - - : If in a `menu` opened with a menubutton and not in a `menubar`, if the menuitem does not have a submenu, does nothing. When focus is in a `menubar`, moves focus to the next item, optionally wrapping from the last to the first. When focus is in a `menu` and on a `menuitem` that has a submenu, opens the submenu and places focus on its first item. When focus is in a `menu` and on an item that does not have a submenu, closes the submenu and any parent menus, moves focus to the next item in the `menubar`, and, if focus is now on a `menuitem` with a submenu, either opens the submenu of that `menuitem` without moving focus into the submenu, or opens the submenu of that `menuitem` and places focus on the first item in the submenu. -- <kbd>Left Arrow</kbd> - - : When focus is in a `menubar`, moves focus to the previous item, optionally wrapping from the first to the last. When focus is in a submenu of an item in a menu, closes the submenu and returns focus to the parent `menuitem`. When focus is in a submenu of an item in a `menubar`, closes the submenu, moves focus to the previous item in the `menubar`, and, if focus is now on a `menuitem` with a submenu, either opens the submenu of that `menuitem` without moving focus into the submenu, or opens the submenu of that `menuitem` and places focus on the first item in the submenu. -- <kbd>Home</kbd> - - : If arrow key wrapping is not supported, moves focus to the first item in the current `menu` or `menubar`. -- <kbd>End</kbd> - - : If arrow key wrapping is not supported, moves focus to the last item in the current `menu` or `menubar`. -- Any key that corresponds to a printable character (Optional) - - : Move focus to the next item in the current menu whose label begins with that printable character. -- <kbd>Escape</kbd> - - : Close the menu that contains focus and return focus to the element or context, e.g., menu button or parent `menuitem`, from which the menu was opened. -- <kbd>Tab</kbd> - - : Moves focus to the next element in the tab sequence, and if the item that had focus is not in a menubar, closes its menu and all open parent menu containers. -- <kbd>Shift + Tab</kbd> - - : Moves focus to the previous element in the tab sequence, and if the item that had focus is not in a menubar, closes its menu and all open parent menu containers. - -If a menu is opened or a menu bar receives focus as a result of a context action, <kbd>Escape</kbd> or <kbd>Enter</kbd> may return focus to the invoking context. - -Some implementations of navigation menubars may have menuitem elements that both perform a function and open a submenu. In such implementations, <kbd>Enter</kbd> and <kbd>Space</kbd> perform a navigation function while <kbd>Down Arrow</kbd>, in a horizontal menubar, opens the submenu associated with that same menuitem. - -When items in a `menubar` are arranged vertically and items in menu containers are arranged horizontally the <kbd>Down Arrow</kbd> performs as <kbd>Right Arrow</kbd> is described above, the <kbd>Up Arrow</kbd> performs as <kbd>Left Arrow</kbd> is described above, and vice versa. - -## Examples - -```html -<div> - <button id="menubutton" aria-haspopup="true" aria-controls="menu"> - <img src="hamburger.svg" alt="Page Sections" /> - </button> - <ul id="menu" role="menu" aria-labelledby="menubutton"> - <li role="presentation"> - <a role="menuitem" href="#description">Description</a> - </li> - <li role="presentation"> - <a - role="menuitem" - href="#associated_wai-aria_roles_states_and_properties"> - Associated WAI-ARIA roles, states, and properties - </a> - </li> - <li role="presentation"> - <a role="menuitem" href="#keyboard_interactions"> - Keyboard interactions - </a> - </li> - <li role="presentation"> - <a role="menuitem" href="#examples">Examples</a> - </li> - <li role="presentation"> - <a role="menuitem" href="#specifications">Specifications</a> - </li> - <li role="presentation"> - <a role="menuitem" href="#see_also">See Also</a> - </li> - </ul> -</div> -``` - -## Specifications - -{{Specifications}} - -## See also - -- [`menuitemcheckbox` role](/en-US/docs/Web/Accessibility/ARIA/Roles/menuitemcheckbox_role) -- [`menuitemradio` role](/en-US/docs/Web/Accessibility/ARIA/Roles/menuitemradio_role) -- [`listitem` role](/en-US/docs/Web/Accessibility/ARIA/Roles/listitem_role) -- [`option` role](/en-US/docs/Web/Accessibility/ARIA/Roles/option_role) diff --git a/files/en-us/web/accessibility/aria/roles/menuitemcheckbox_role/index.md b/files/en-us/web/accessibility/aria/roles/menuitemcheckbox_role/index.md deleted file mode 100644 index dd346a4e1b82718..000000000000000 --- a/files/en-us/web/accessibility/aria/roles/menuitemcheckbox_role/index.md +++ /dev/null @@ -1,140 +0,0 @@ ---- -title: "ARIA: menuitemcheckbox role" -slug: Web/Accessibility/ARIA/Roles/menuitemcheckbox_role -page-type: aria-role -spec-urls: - - https://w3c.github.io/aria/#menuitemcheckbox - - https://www.w3.org/WAI/ARIA/apg/patterns/menubar/examples/menubar-navigation/ ---- - -{{AccessibilitySidebar}} - -A `menuitemcheckbox` is a `menuitem` with a checkable state whose possible values are `true`, `false`, or `mixed`. - -## Description - -The items in menu and menubars are menu items. There are three types of menu items: [`menuitem`](/en-US/docs/Web/Accessibility/ARIA/Roles/menuitem_role), [`menuitemradio`](/en-US/docs/Web/Accessibility/ARIA/Roles/menuitemradio_role), and `menuitemcheckbox`. - -These three elements can only be contained in, or owned by, an element with role [`menu`](/en-US/docs/Web/Accessibility/ARIA/Roles/menu_role) or [`menubar`](/en-US/docs/Web/Accessibility/ARIA/Roles/menubar_role), optionally nested within a grouping element with role of [`group`](/en-US/docs/Web/Accessibility/ARIA/Roles/group_role). Being nested or otherwise owned (see [`aria-owns`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-owns)) in a `menu` or `menubar` identifies the menu items as being related widgets. - -Menu items, including `menuitemcheckbox` elements, may be grouped within `group` elements or separated by elements with the [`separator`](/en-US/docs/Web/Accessibility/ARIA/Roles/separator_role) role or other equivalent native role such as {{HTMLElement('fieldset')}} and {{HTMLElement('hr')}}. - -Menu items containing the role of `menuitemcheckbox` must include the [`aria-checked`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-checked) attribute to expose the checkbox's state to assistive technology, unless using [`<input type="checkbox">`](/en-US/docs/Web/HTML/Element/input/checkbox), in which case the [`checked`](/en-US/docs/Web/HTML/Element/input/checkbox#checked) attribute should be used. - -Similar to the `checked` attribute of {{HTMLElement('input')}}s of type `checkbox`, the `aria-checked` attribute of a `menuitemcheckbox` indicates whether the menu item is checked (`true`), unchecked (`false`), or represents a sub-level menu of other menu items that have a mixture of checked and unchecked values (`mixed`). The `mixed` value is similar to the checkbox's [`indeterminate`](/en-US/docs/Web/HTML/Element/input/checkbox#indeterminate_state_checkboxes) attribute, which gives the appearance of a third, neither checked nor unchecked, state. - -An accessible name is required. Ideally, the accessible name should come from an associated {{htmlelement('label')}} element if using `<input type="checkbox">` or visible, descendant content. Realize if the label or descendant content is not sufficient and, preferably, [`aria-labelledby`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-labelledby) is used referencing non-descendant content or [`aria-label`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-label) is used, these two ARIA properties will hide other descendant content from assistive technologies. - -If all elements in the set are not present in the DOM include the [`aria-setsize`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-setsize) and [`aria-posinset`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-posinset) properties. When specifying `aria-setsize` and `aria-posinset` on a `menuitemcheckbox`, set the value with respect to the total number of items in the menu, excluding any separators. - -The `menuitemcheckbox` element can have phrasing content, but can not have interactive content as descendants and no descendants with a `tabindex` attribute specified. - -### All descendants are presentational - -There are some types of user interface components that, when represented in a platform accessibility API, can only contain text. Accessibility APIs do not have a way of representing semantic elements contained in a `menuitemcheckbox`. To deal with this limitation, browsers, automatically apply role [`presentation`](/en-US/docs/Web/Accessibility/ARIA/Roles/presentation_role) to all descendant elements of any `menuitemcheckbox` element as it is a role that does not support semantic children. - -For example, consider the following `menuitemcheckbox` element, which contains a heading. - -```html -<div role="menuitemcheckbox"><h6>Name of my checkbox</h6></li> -``` - -Because descendants of `menuitemcheckbox` are presentational, the following code is equivalent: - -```html -<div role="menuitemcheckbox"><h6 role="presentation">Name of my checkbox</h6></li> -``` - -From the assistive technology user's perspective, the heading does not exist since the previous code snippets are equivalent to the following in the [accessibility tree](/en-US/docs/Glossary/Accessibility_tree): - -```html -<div role="menuitemcheckbox">Name of my checkbox</div> -``` - -### Associated WAI-ARIA roles, states, and properties - -- [`menu`](/en-US/docs/Web/Accessibility/ARIA/Roles/menu_role) role - - : Widget that offers a list of common actions or functions the user can invoke. -- [`menubar`](/en-US/docs/Web/Accessibility/ARIA/Roles/menubar_role) role - - : Similar to `menu` for a consistent set of frequently used commands remaining visible and usually presented horizontally. -- [`group`](/en-US/docs/Web/Accessibility/ARIA/Roles/group_role) role - - : Container for a group of `menuitem` elements, including `menuitemcheckbox` elements within a `menu` or `menubar`. -- [`aria-checked`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-checked) (Required) - - : Set to `true`, `false`, or `mixed`, it indicates the current "checked" state of the menuitemcheckbox - -### Keyboard interactions - -When a `menu` opens, or when a `menubar` receives focus, keyboard focus is placed on the first item. All items in both are focusable, including all `menuitemcheckbox` elements. - -If the `menuitemcheckbox` is in a submenu in a `menubar` or a menu opened with a menu button, the following keyboard interactions must be programmed in. : - -- <kbd>Enter</kbd> - - : Toggles the `aria-checked` state of the `menuitemcheckbox` and closes the menu. -- <kbd>Space</kbd> - - : Toggles the `aria-checked` state of the `menuitemcheckbox`. Does not close the menu. -- <kbd>Escape</kbd> - - : Closes menu. In menubar, moves focus to parent menubar item. -- <kbd>Right Arrow</kbd> - - : Closes submenu. In menubar, moves focus to next item in the menubar, opening any submenu if there is one. -- <kbd>Left Arrow</kbd> - - : Closes menu. In menubar, moves focus to previous item in the menubar, opening any submenu if there is one. -- <kbd>Down Arrow</kbd> - - : Moves focus to the next item in the menu. If focus is on the last item, moves focus to the first item. -- <kbd>Up Arrow</kbd> - - : Moves focus to previous item in the menu. If focus is on the first item, moves focus to the last item. -- <kbd>Home</kbd> - - : Moves focus to the first item in the menu. -- <kbd>End</kbd> - - : Moves focus to the last item in the menu. -- <kbd>Character</kbd> - - : Moves focus to the next item having a name that starts with the typed character. If none of the items have a name starting with the typed character, focus does not move. - -### Required JavaScript - -#### Required event handlers - -- `onclick` - - : Handle mouse clicks on both the checkbox and the associated label that will change the state of the checkbox by changing the value of the `aria-checked` attribute and the appearance of the checkbox so it appears checked or unchecked to the sighted user -- `onKeyDown` - - : Handle the case where the user presses the <kbd>Space</kbd> key to change the state of the checkbox by changing the value of the `aria-checked` attribute and the appearance of the checkbox so it appears checked or unchecked to the sighted user. Also handles all keys listed in the keyboard navigation section above. - -## Examples - -```html -<li role="menuitemcheckbox" tabindex="-1" aria-checked="false">Purple</li> -``` - -The [`tabindex="-1"`](/en-US/docs/Web/HTML/Global_attributes/tabindex) makes the `menuitemcheckbox` focusable but not part of the page tab sequence. Had we included `aria-checked="true"` it would have indicated that the `menuitemcheckbox` was checked, and we would have visually styled the selected state to look checked using the attribute selector `[role='menuitemcheckbox'][aria-checked='true']`. Instead, the presence of `aria-checked="false"` indicates to assistive technologies that the `menuitemcheckbox` is checkable but not currently checked. The accessible name "purple" comes from the contents. - -The visual appearance of the selected state is a checked checkbox which we can create using [generated content](/en-US/docs/Web/CSS/CSS_generated_content), making it visible and the same color as the content by synchronizing with the `aria-checked` value using CSS [attribute selectors](/en-US/docs/Web/CSS/Attribute_selectors) and [inheriting](/en-US/docs/Web/CSS/inherit) the color. - -```css -[role="menuitemcheckbox"]::before { - display: inline-block; - content: ""; - color: transparent; - width: 1em; - text-align: center; - outline: 1px solid; - margin-inline-end: 2px; - font-family: sans-serif; -} -[role="menuitemcheckbox"][aria-checked="true"]::before { - color: inherit; - content: "X"; -} -``` - -### Prefer HTML - -The first rule of ARIA is: if a native HTML element or attribute has the semantics and behavior you require, use it instead of re-purposing an element and adding an ARIA role, state or property to make it accessible. As such, it is recommended to use the native [HTML checkbox](/en-US/docs/Web/HTML/Element/input/checkbox) form control instead of recreating a checkbox's functionality with JavaScript and ARIA. - -## Specifications - -{{Specifications}} - -## See also - -- [`menuitemradio` role](/en-US/docs/Web/Accessibility/ARIA/Roles/menuitemradio_role) -- [`checkbox` role](/en-US/docs/Web/Accessibility/ARIA/Roles/checkbox_role) -- [`<input type="checkbox">`](/en-US/docs/Web/HTML/Element/input/checkbox) diff --git a/files/en-us/web/accessibility/aria/roles/menuitemradio_role/index.md b/files/en-us/web/accessibility/aria/roles/menuitemradio_role/index.md deleted file mode 100644 index 802225f5315533b..000000000000000 --- a/files/en-us/web/accessibility/aria/roles/menuitemradio_role/index.md +++ /dev/null @@ -1,150 +0,0 @@ ---- -title: "ARIA: menuitemradio role" -slug: Web/Accessibility/ARIA/Roles/menuitemradio_role -page-type: aria-role -spec-urls: - - https://w3c.github.io/aria/#menuitemradio - - https://www.w3.org/WAI/ARIA/apg/patterns/menubar/examples/menubar-navigation/ ---- - -{{AccessibilitySidebar}} - -A `menuitemradio` is checkable menuitem in a set of elements with the same role, only one of which can be checked at a time. - -## Description - -The items in menu and menubars are menu items. There are three types of menu items: [`menuitem`](/en-US/docs/Web/Accessibility/ARIA/Roles/menuitem_role), [`menuitemcheckbox`](/en-US/docs/Web/Accessibility/ARIA/Roles/menuitemcheckbox_role), and `menuitemradio`. To limit the number of checked menu items to one within a group, use the `menuitemradio` role on all the elements in the group. - -A `menuitemradio` is checkable menuitem in a set of elements with the same role, of which only can be checked at a time. - -The three menu item elements can only be contained in, or owned by, an element with role [`menu`](/en-US/docs/Web/Accessibility/ARIA/Roles/menu_role) or [`menubar`](/en-US/docs/Web/Accessibility/ARIA/Roles/menubar_role), optionally nested within a grouping element with role of [`group`](/en-US/docs/Web/Accessibility/ARIA/Roles/group_role). Being nested or otherwise owned (see [`aria-owns`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-owns)) in a `menu` or `menubar` identifies the menu items as being related widgets. - -When all items in a submenu are members of the same radio group, the `group` is defined by the menu element; the `group` element is not necessary. - -Menu items containing the role of `menuitemradio` must include the [`aria-checked`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-checked) attribute to expose the radio button's state to assistive technology, unless using [`<input type="radio">`](/en-US/docs/Web/HTML/Element/input/checkbox), in which case the [`checked`](/en-US/docs/Web/HTML/Element/input/checkbox#checked) attribute should be used. - -Similar to the `checked` attribute of {{HTMLElement('input')}}s of type `radio`, the `aria-checked` attribute of a `menuitemradio` indicates whether the menu item is checked (`true`), unchecked (`false`). There is no `mixed` value like there is for `menuitemcheckbox`. - -Only one `menuitemradio` in a group can be checked at the same time. When one item in the group is checked, the `aria-checked` attribute gets set to `true`, while the previously checked `menuitemradio` element in the same group, if there was one, becomes unchecked, by having the `aria-checked` attribute value switched to `false`. - -If your want more than one item in a group to be checked, or if you want to enable checking and unchecking an item, consider using `menuitemcheckbox`. - -If a `menu` or `menubar` contains more than one group of `menuitemradio` elements, or if the `menu` contains a group of `menuitemradio` elements as well as other, unrelated `menuitem` elements and/or `menuitemcheckbox` elements, contain each set of related `menuitemradio` elements in a `group` element or delimit the group the `menuitemradio` elements from the other menu items with a `separator` element (or an HTML element with an equivalent role such as a {{HTMLElement('fieldset')}} grouping or a thematic break {{HTMLElement('hr')}} separator. - -An accessible name is required. Ideally, the accessible name should come from an associated {{htmlelement('label')}} element if using `<input type="radio">` or visible, descendant content. Realize if the label or descendant content is not sufficient and, preferably, [`aria-labelledby`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-labelledby) is used referencing non-descendant content or [`aria-label`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-label) is used, these two ARIA properties will hide other descendant content from assistive technologies. - -If all elements in the set are not present in the DOM include the [`aria-setsize`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-setsize) and [`aria-posinset`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-posinset) properties. When specifying `aria-setsize` and `aria-posinset` on a `menuitemradio`, set the value with respect to the total number of items in the menu, excluding any separators. - -The `menuitemradio` element can have phrasing content, but can not have interactive content as descendants and no descendants with a `tabindex` attribute specified. - -### All descendants are presentational - -There are some types of user interface components that, when represented in a platform accessibility API, can only contain text. Accessibility APIs do not have a way of representing semantic elements contained in a `menuitemradio`. To deal with this limitation, browsers, automatically apply role [`presentation`](/en-US/docs/Web/Accessibility/ARIA/Roles/presentation_role) to all descendant elements of any `menuitemradio` element as it is a role that does not support semantic children. - -For example, consider the following `menuitemradio` element, which contains a heading. - -```html -<div role="menuitemradio"><h6>Name of my radio button</h6></li> -``` - -Because descendants of `menuitemradio` are presentational, the following code is equivalent: - -```html -<div role="menuitemradio"><h6 role="presentation">Name of my radio button</h6></li> -``` - -From the assistive technology user's perspective, the heading does not exist since the previous code snippets are equivalent to the following in the [accessibility tree](/en-US/docs/Glossary/Accessibility_tree): - -```html -<div role="menuitemradio">Name of my radio button</div> -``` - -### Associated WAI-ARIA roles, states, and properties - -- [`menu`](/en-US/docs/Web/Accessibility/ARIA/Roles/menu_role) role - - : Widget that offers a list of common actions or functions the user can invoke. -- [`menubar`](/en-US/docs/Web/Accessibility/ARIA/Roles/menubar_role) role - - : Similar to `menu` for a consistent set of frequently used commands remaining visible and usually presented horizontally. -- [`group`](/en-US/docs/Web/Accessibility/ARIA/Roles/group_role) role - - : Container for a group of `menuitem` elements, including `menuitemradio` elements within a `menu` or `menubar`. -- [`aria-checked`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-checked) (Required) - - : Set to `true` or `false`, it indicates the current "checked" state of the menuitemradio - -### Keyboard interactions - -When a `menu` opens, or when a `menubar` receives focus, keyboard focus is placed on the first item. All items in both are focusable, including all `menuitemradio` elements. - -If the `menuitemradio` is in a submenu in a `menubar` or a menu opened with a menu button, the following keyboard interactions must be programmed in. : - -- <kbd>Enter</kbd> - - : If not checked, checks the focused `menuitemradio` and unchecks any other checked `menuitemradio` element in the same group. Also, closes the menu. -- <kbd>Space</kbd> - - : If not checked, checks the focused `menuitemradio` and unchecks any other checked `menuitemradio` element in the same group without closing the menu. -- <kbd>Escape</kbd> - - : Closes menu. In menubar, moves focus to parent menubar item. -- <kbd>Right Arrow</kbd> - - : Closes submenu. In menubar, moves focus to next item in the menubar, opening any submenu if there is one. -- <kbd>Left Arrow</kbd> - - : Closes menu. In menubar, moves focus to previous item in the menubar, opening any submenu if there is one. -- <kbd>Down Arrow</kbd> - - : Moves focus to the next item in the menu. If focus is on the last item, moves focus to the first item. -- <kbd>Up Arrow</kbd> - - : Moves focus to previous item in the menu. If focus is on the first item, moves focus to the last item. -- <kbd>Home</kbd> - - : Moves focus to the first item in the menu. -- <kbd>End</kbd> - - : Moves focus to the last item in the menu. -- <kbd>Character</kbd> - - : Moves focus to the next item having a name that starts with the typed character. If none of the items have a name starting with the typed character, focus does not move. - -### Required JavaScript - -#### Required event handlers - -- `onclick` - - : Handle mouse clicks on both the radio button and the associated label that will change the state of the radio button by changing the value of the `aria-checked` attribute and the appearance of the radio button so it appears checked or unchecked to the sighted user -- `onKeyDown` - - : Handle the case where the user presses the <kbd>Space</kbd> key to change the state of the radio button by changing the value of the `aria-checked` attribute and the appearance of the radio button so it appears checked or unchecked to the sighted user. Also handles all keys listed in the keyboard navigation section above. - -## Examples - -```html -<li role="menuitemradio" tabindex="-1" aria-checked="false">Purple</li> -``` - -The [`tabindex="-1"`](/en-US/docs/Web/HTML/Global_attributes/tabindex) makes the `menuitemradio` focusable but not part of the page tab sequence. Had we included `aria-checked="true"` it would have indicated that the `menuitemradio` was checked, and we would have visually styled the selected state to look checked using the attribute selector `[role='menuitemradio'][aria-checked='true']`. Instead, the presence of `aria-checked="false"` indicates to assistive technologies that the `menuitemradio` is checkable but not currently checked. The accessible name "purple" comes from the contents. - -The visual appearance of the selected state is a checked radio button which we can create using [generated content](/en-US/docs/Web/CSS/CSS_generated_content), making it visible and the same color as the content by synchronizing with the `aria-checked` value using CSS [attribute selectors](/en-US/docs/Web/CSS/Attribute_selectors) and changing the [`background-color`](/en-US/docs/Web/CSS/background-color). - -```css -[role="menuitemradio"]::before { - display: inline-block; - content: ""; - width: 1em; - height: 1em; - padding: 0.1em; - border: 2px solid #333; - border-radius: 50%; - box-sizing: border-box; - background-clip: content-box; - margin-inline-end: 2px; -} -[role="menuitemradio"][aria-checked="true"]::before { - background-color: purple; -} -``` - -Don't use the [`background`](/en-US/docs/Web/CSS/background) shorthand property, as that will override the [`background-clip`](/en-US/docs/Web/CSS/background-clip) property we used to create the radio button effect. - -### Prefer HTML - -The first rule of ARIA is: if a native HTML element or attribute has the semantics and behavior you require, use it instead of re-purposing an element and adding an ARIA role, state or property to make it accessible. As such, it is recommended to use the native [HTML radio button](/en-US/docs/Web/HTML/Element/input/radio) form control instead of recreating a radio button's functionality with JavaScript and ARIA. - -## Specifications - -{{Specifications}} - -## See also - -- [`radio` role](/en-US/docs/Web/Accessibility/ARIA/Roles/radio_role) -- [`<input type="radio">`](/en-US/docs/Web/HTML/Element/input/radio) diff --git a/files/en-us/web/accessibility/aria/roles/meter_role/index.md b/files/en-us/web/accessibility/aria/roles/meter_role/index.md deleted file mode 100644 index ee6eb10d162f248..000000000000000 --- a/files/en-us/web/accessibility/aria/roles/meter_role/index.md +++ /dev/null @@ -1,85 +0,0 @@ ---- -title: "ARIA: meter role" -slug: Web/Accessibility/ARIA/Roles/meter_role -page-type: aria-role -spec-urls: https://www.w3.org/TR/wai-aria-1.2/#meter ---- - -{{AccessibilitySidebar}} - -The `meter` role is used to identify an element being used as a meter. - -> [!NOTE] -> Where possible, it is recommended that you use a native {{HTMLElement("meter")}} element rather than the `meter` role, as native elements are more widely supported by user agents and assistive technology. - -## Description - -A meter is a graphical display of a numeric value within a defined range. For example, showing battery percentage. A meter is not appropriate for values that do not have a meaningful maximum limit. Meters should not be used to indicate progress (for example loading), this should be communicated with the {{HTMLElement('progress')}} element. - -Each element with `role="meter"` must also have one of the following: - -- An [`aria-label`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-label) attribute. -- An [`aria-labelledby`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-labelledby) attribute pointing to an element with text that describes the meter. - -### All descendants are presentational - -There are some types of user interface components that, when represented in a platform accessibility API, can only contain text. Accessibility APIs do not have a way of representing semantic elements contained in a `meter`. To deal with this limitation, browsers, automatically apply role [`presentation`](/en-US/docs/Web/Accessibility/ARIA/Roles/presentation_role) to all descendant elements of any `meter` element as it is a role that does not support semantic children. - -For example, consider the following `meter` element, which contains a heading. - -```html -<div role="meter"><h3>Title of my meter</h3></div> -``` - -Because descendants of `meter` are presentational, the following code is equivalent: - -```html -<div role="meter"><h3 role="presentation">Title of my meter</h3></div> -``` - -From the assistive technology user's perspective, the heading does not exist since the previous code snippets are equivalent to the following in the [accessibility tree](/en-US/docs/Glossary/Accessibility_tree).: - -```html -<div role="meter">Title of my meter</div> -``` - -### Associated ARIA roles, states, and properties - -- [`aria-valuenow`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-valuenow) - - : Set to a decimal value between `aria-valuemin` and `aria-valuemax` indicating the current value of the meter. -- [`aria-valuetext`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-valuetext) - - : Assistive technologies often present the value of `aria-valuenow` as a percentage. If this would not be accurate use this property to make the meter value understandable. -- [`aria-valuemin`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-valuemin) - - : Set to a decimal value representing the minimum value, and less than `aria-valuemax`. -- [`aria-valuemax`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-valuemax) - - : Set to a decimal value representing the maximum value, and greater than `aria-valuemin`. - -It is recommended to use a native {{HTMLElement("meter")}} element rather than the `meter` role. User agents provide a stylize widget for the {{HTMLElement("meter")}} element based on the current `value` as it relates to the `min` and `max` values. When using non-semantic elements, all features of the native semantic element need to be recreated with ARIA attributes, JavaScript and CSS. - -## Examples - -An example of a meter using `role="meter"`: - -```html -<div - role="meter" - aria-valuenow="90" - aria-valuemin="0" - aria-valuemax="100" - aria-labelledby="cpu_usage_label"> - <svg xmlns="http://www.w3.org/2000/svg" aria-hidden="true" style="width: 90%"> - <rect x="0" y="0" width="100%" height="100%" fill="currentcolor"></rect> - </svg> -</div> -``` - -In the above scenario, when the `aria-valuenow` value updates, the width of the SVG also needs to be updated as can be seen in [the W3C working meter example](https://www.w3.org/TR/wai-aria-practices-1.2/examples/meter/meter.html). - -## Specifications - -{{Specifications}} - -## See also - -- {{HTMLElement('meter')}} -- {{HTMLElement('progress')}} diff --git a/files/en-us/web/accessibility/aria/roles/navigation_role/index.md b/files/en-us/web/accessibility/aria/roles/navigation_role/index.md deleted file mode 100644 index 6dc7c7e91c343dc..000000000000000 --- a/files/en-us/web/accessibility/aria/roles/navigation_role/index.md +++ /dev/null @@ -1,121 +0,0 @@ ---- -title: "ARIA: navigation role" -slug: Web/Accessibility/ARIA/Roles/navigation_role -page-type: aria-role -spec-urls: - - https://w3c.github.io/aria/#navigation - - https://www.w3.org/WAI/ARIA/apg/patterns/landmarks/examples/navigation.html ---- - -{{AccessibilitySidebar}} - -The `navigation` role is used to identify major groups of links used for navigating through a website or page content. - -```html -<div role="navigation" aria-label="Main"> - <!-- list of links to main website locations --> -</div> -``` - -This is a website's main navigation. - -## Description - -The `navigation` role is [a landmark](/en-US/docs/Web/Accessibility/ARIA/Roles#3._landmark_roles) role. Landmark roles provide a way to identify the organization and structure of a web page. By classifying and labeling sections of a page, structural information conveyed visually through layout is represented programmatically. Screen readers use landmark roles to provide keyboard navigation to important sections of a page. Like the HTML {{HTMLElement('nav')}} element, navigation landmarks provide a way to identify groups (e.g. lists) of links that are intended to be used for website or page content navigation. If a page includes more than one navigation landmark, each should have a unique label. If two or more navigational landmark on a page have the same set of links, use the same label for each. - -It is preferable to use the HTML5 [`<nav>` element](/en-US/docs/Web/HTML/Element/nav) to define a navigation landmark. If the HTML5 nav element technique is not being used, use a `role="navigation"` attribute to define a navigation landmark. - -> [!NOTE] -> Using the {{HTMLElement('nav')}} element will automatically communicate a section has a role of `navigation`. Developers should always prefer using the correct semantic HTML element over using ARIA - -### Associated WAI-ARIA Roles, States, and Properties - -- [`aria-label`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-label) - - : A brief description of the purpose of the navigation, omitting the term "navigation", as the screen reader will read both the role and the contents of the label. - -### Keyboard Interactions - -None. - -### Required JavaScript features - -None. - -## Examples - -```html -<div role="navigation" aria-label="Customer service"> - <ul> - <li><a href="#">Help</a></li> - <li><a href="#">Order tracking</a></li> - <li><a href="#">Shipping &amp; Delivery</a></li> - <li><a href="#">Returns</a></li> - <li><a href="#">Contact us</a></li> - <li><a href="#">Find a store</a></li> - </ul> -</div> -``` - -## Accessibility concerns - -[Landmark roles](/en-US/docs/Web/Accessibility/ARIA/Roles#3._landmark_roles) are intended to be used sparingly, to identify larger overall sections of the document. Using too many landmark roles can create "noise" in screen readers, making it difficult to understand the overall layout of the page. - -## Best practices - -### Prefer HTML - -Using the {{HTMLElement('nav')}} element will automatically communicate a section has a role of `navigation`. If at all possible, prefer using it instead. - -### Labeling landmarks - -#### Multiple landmarks - -If there is more than one `navigation` landmark role or {{HTMLElement('nav')}} element in a document, provide a label for each landmark. This label will allow an assistive technology user to be able to quickly understand the purpose of each landmark. - -```html -<div id="main-nav" role="navigation" aria-label="Main"> - <!-- content --> -</div> - -… - -<nav id="footer-nav" aria-label="Footer"> - <!-- content --> -</nav> -``` - -#### Repeated landmarks - -If a `navigation` landmark role or {{HTMLElement('nav')}} element in a document is repeated in a document, and both landmarks have identical content, use the same label for each landmark. An example of this would be repeating the main navigation at the top and bottom of the page. - -```html -<header> - <nav id="main-nav" aria-label="Main"> - <!-- list of links to main website locations --> - </nav> -</header> - -… - -<footer> - <nav id="footer-nav" aria-label="Main"> - <!-- list of links to main website locations --> - </nav> -</footer> -``` - -#### Redundant descriptions - -Screen readers will announce the type of role the landmark is. Because of this, you do not need to describe what the landmark is in its label. For example, a declaration of `role="navigation"` with an of `aria-label="Primary navigation"` may be announced redundantly as, "primary navigation navigation". - -## Specifications - -{{Specifications}} - -## See also - -- The {{HTMLElement('nav')}} element -- [Using HTML sections and outlines](/en-US/docs/Web/HTML/Element/Heading_Elements) -- [Using WAI-ARIA Landmarks – 2013 | The Paciello Group](https://www.tpgi.com/using-wai-aria-landmarks-2013/) -- [Accessible Landmarks | scottohara.me](https://www.scottohara.me/blog/2018/03/03/landmarks.html) -- [Semantic navigation with the nav element | HTML5 Doctor](https://html5doctor.com/nav-element/) diff --git a/files/en-us/web/accessibility/aria/roles/none_role/index.md b/files/en-us/web/accessibility/aria/roles/none_role/index.md deleted file mode 100644 index fb9af4971053d09..000000000000000 --- a/files/en-us/web/accessibility/aria/roles/none_role/index.md +++ /dev/null @@ -1,11 +0,0 @@ ---- -title: "ARIA: none role" -slug: Web/Accessibility/ARIA/Roles/none_role -page-type: aria-role ---- - -{{AccessibilitySidebar}} - -The `none` role is a synonym for the [`presentation`](/en-US/docs/Web/Accessibility/ARIA/Roles/presentation_role) role; they both remove an element's implicit ARIA semantics from being exposed to the accessibility tree. - -See the [`presentation`](/en-US/docs/Web/Accessibility/ARIA/Roles/presentation_role) role for more information. diff --git a/files/en-us/web/accessibility/aria/roles/note_role/index.md b/files/en-us/web/accessibility/aria/roles/note_role/index.md deleted file mode 100644 index 0377cd1da49d2f5..000000000000000 --- a/files/en-us/web/accessibility/aria/roles/note_role/index.md +++ /dev/null @@ -1,49 +0,0 @@ ---- -title: "ARIA: note role" -slug: Web/Accessibility/ARIA/Roles/note_role -page-type: aria-role -spec-urls: https://w3c.github.io/aria/#note ---- - -{{AccessibilitySidebar}} - -A `note` role suggests a section whose content is parenthetic or ancillary to the main content. - -## Description - -The `note` role can be added to parenthetic or ancillary content if no other native element or other role fits the purpose. - -### Associated WAI-ARIA roles, states, and properties - -- [`aria-label`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-label) or [`aria-labelledby`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-labelledby) (optional) - - : Naming a note is optional, but can help screen reader users understand its context and purpose. The name can be provided using `aria-labelledby` if a visible label is present, otherwise with `aria-label`. - -## Examples - -```html -<h1>Madam C. J. Walker</h1> -<p> - Madam C.J. Walker was an African American entrepreneur, philanthropist, and - political and social activist. -</p> -<h2>Early Life</h2> -… -<h2>Career</h2> -… -<p role="note" class="highlight-box"> - At the height of the depression, Madam C. J. Walker trained 20,000 women to - sell hair pomade door-to-door -</p> -<h2>Activism and Philanthropy</h2> -… -``` - -In the above Wikipedia style entry for Madam C.J. Walker, the `highlight-box` with role `note` could have been a {{HTMLElement('blockquote')}} if it contained a quote or {{HTMLElement('figcaption')}} in a {{HTMLElement('figure')}} if there was an associated image. In this case, as neither of those made sense, the `note` role was added to add semantics to the parenthetic content. - -## Specifications - -{{Specifications}} - -## See also - -- [Document structure roles](/en-US/docs/Web/Accessibility/ARIA/Roles#1._document_structure_roles) diff --git a/files/en-us/web/accessibility/aria/roles/option_role/index.md b/files/en-us/web/accessibility/aria/roles/option_role/index.md deleted file mode 100644 index 0220428eef31e12..000000000000000 --- a/files/en-us/web/accessibility/aria/roles/option_role/index.md +++ /dev/null @@ -1,109 +0,0 @@ ---- -title: "ARIA: option role" -slug: Web/Accessibility/ARIA/Roles/option_role -page-type: aria-role -spec-urls: - - https://w3c.github.io/aria/#option - - https://www.w3.org/WAI/ARIA/apg/patterns/listbox/examples/listbox-scrollable/ ---- - -{{AccessibilitySidebar}} - -The `option` role is used for selectable items in a `listbox`. - -## Description - -The `option` role is used to identify selections a user can make in a [`listbox`](/en-US/docs/Web/Accessibility/ARIA/Roles/listbox_role). These options are similar to the {{HTMLElement('option')}} elements in a {{HTMLElement('select')}} element, but they can contain images. - -All selectable options should have [`aria-selected`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-selected) match their state, `true` when selected and `false` when not. If an option is not selectable, `aria-selected` can be omitted. A disabled option can have [`aria-disabled="true"`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-disabled) and `aria-selected="false"` to communicate to the user that the option is present, albeit disabled. - -The `option` role is for identifying selectable choices of a `listbox`. Options must be provided an accessible name. Generally, the accessible name for an option should come from the element's descendant content. - -Authors can also explicitly provide an accessible name by specifying [`aria-label`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-label) or [`aria-labelledby`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-labelledby) to the element with the `option` role. If using `aria-label` or `aria-labelledby`, and the option also displays a visible text label, authors must ensure they adhere to <a href="https://www.w3.org/WAI/WCAG21/Understanding/label-in-name.html">WCAG Success Criterion 2.5.3 Label in Name</a>. - -It is highly recommended to use a {{HTMLElement('select')}} element or an {{HTMLElement('input')}} element with the `checkbox` or `radio` type instead, when possible. These native HTML elements provide keyboard interactivity to manage focus for all the descendants for you automatically. - -### All descendants are presentational - -There are some types of user interface components that, when represented in a platform accessibility API, can only contain text. Accessibility APIs do not have a way of representing semantic elements contained in a `option`. To deal with this limitation, browsers, automatically apply role [`presentation`](/en-US/docs/Web/Accessibility/ARIA/Roles/presentation_role) to all descendant elements of any `option` element as it is a role that does not support semantic children. - -For example, consider the following `option` element, which contains a heading. - -```html -<div role="option"><h3>Title of my option</h3></div> -``` - -Because descendants of `option` are presentational, the following code is equivalent: - -```html -<div role="option"><h3 role="presentation">Title of my option</h3></div> -``` - -From the assistive technology user's perspective, the heading does not exist since the previous code snippets are equivalent to the following in the [accessibility tree](/en-US/docs/Glossary/Accessibility_tree): - -```html -<div role="option">Title of my option</div> -``` - -### Associated ARIA roles, states, and properties - -#### Associated Roles - -- [`listbox`](/en-US/docs/Web/Accessibility/ARIA/Roles/listbox_role) - - : An `option` _must_ be contained in or owned by a `listbox` - -#### States and Properties - -- [`aria-selected`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-selected) - - - : Used to describe the selection state of the option. Required. - -- [`aria-checked`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-checked) - - - : Used to describe the checked state when options are used in a multiple selection fashion. Supports `true`, `false` and `mixed`. Optional. - -- [`aria-posinset`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-posinset) - - - : Used to describe the position in the set of options when it does not match the DOM, such as virtual scrolling where only some options are present at a time. Optional. - -- [`aria-setsize`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-setsize) - - - : Used in conjunction with `aria-posinset` to declare the total number of options. Optional. - -- [`aria-disabled`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-disabled) - - - : Used to indicate that the option is present but not editable. Optional. - -- [`aria-hidden`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-hidden) - - - : Used to hide the option from accessibility tools. It should only be used to hide non-visible content or visible content if it improves the experience of assistive technology, such as redundant content. Optional. - -- [`aria-invalid`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-invalid) - - - : Used to indicate that the value of the option is considered invalid by the application. Optional. - -- [`aria-busy`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-busy) - - - : Used to indicate that an element is being modified, such as while it is loading. Optional. - -- [`aria-labelledby`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-labelledby) - - - : Used to indicate which element labels the option. The content of the option should be used instead where appropriate. Optional. - -- [`aria-label`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-label) - - : Used to label the option. If the label is present in the DOM, `aria-labelledby` should be used instead. Optional. - -(For further details and a full list of ARIA states and properties see the <a href="https://www.w3.org/TR/wai-aria-1.1/#option">ARIA `option` (role)</a> documentation.) - -## Specifications - -{{Specifications}} - -## See also - -- HTML {{HTMLElement('select')}} element -- HTML {{HTMLElement('label')}} element -- HTML {{HTMLElement('option')}} element -- [ARIA: `combobox` role](/en-US/docs/Web/Accessibility/ARIA/Roles/combobox_role) -- [ARIA: `list` role](/en-US/docs/Web/Accessibility/ARIA/Roles/list_role) -- [ARIA: `listbox` role](/en-US/docs/Web/Accessibility/ARIA/Roles/listbox_role) diff --git a/files/en-us/web/accessibility/aria/roles/presentation_role/index.md b/files/en-us/web/accessibility/aria/roles/presentation_role/index.md deleted file mode 100644 index 47583148b2d1f7e..000000000000000 --- a/files/en-us/web/accessibility/aria/roles/presentation_role/index.md +++ /dev/null @@ -1,61 +0,0 @@ ---- -title: "ARIA: presentation role" -slug: Web/Accessibility/ARIA/Roles/presentation_role -page-type: aria-role -spec-urls: https://w3c.github.io/aria/#presentation ---- - -{{AccessibilitySidebar}} - -The `presentation` role and its synonym `none` remove an element's implicit ARIA semantics from being exposed to the accessibility tree. - -The content of the element will still be available to assistive technologies; it is only the semantics of the container — and in some instance, required associated descendants — which will no longer expose their mappings to the accessibility API. - -## Description - -While ARIA is primarily used to express semantics, there are some situations where hiding an element's semantics from assistive technologies is helpful. This is done with the `presentation` role or its synonym role `none`, which declare that an element is being used only for presentation and therefore does not have any accessibility semantics. - -Writing `<h2 role="presentation">Democracy Dies in Darkness</h2>` removes the heading semantics of the {{HTMLElement("Heading_Elements", "h2")}} element, making it the equivalent of `<div>Democracy Dies in Darkness</div>`. The heading role semantics are removed, but the content itself is still available. - -When an element has required descendants, such as the various {{HTMLElement('table')}}, elements and {{HTMLElement('li')}}s children of a {{HTMLElement('ul')}} or {{HTMLElement('ol')}}, the `presentation` or `none` role on the table or list removes the default semantics of the element on which it was applied and their required descendant elements. - -If `presentation` or `none` is applied to a {{HTMLElement('table')}} element, the descendant {{HTMLElement('caption')}}, {{HTMLElement('thead')}}, {{HTMLElement('tbody')}}, {{HTMLElement('tfoot')}}, {{HTMLElement('tr')}}, {{HTMLElement('th')}}, and {{HTMLElement('td')}} elements inherit the role and are thus not exposed to assistive technologies. But, elements inside of the {{HTMLElement('th')}} and {{HTMLElement('td')}} elements, including nested tables, are exposed to assistive technologies. - -```html -<ul role="presentation"> - <li> - <a href="#">Link 1</a> - </li> - <li> - <a href="#">Link 2</a> - </li> - <li> - <a href="#">Link 3</a> - </li> -</ul> -``` - -Because the `presentation` role was applied to the {{HTMLElement('ul')}} element, every child {{HTMLElement('li')}} element inherits the `presentation` role. This is because ARIA requires the `listitem` elements to have a parent `list` element. While the {{HTMLElement('li')}} elements, in this case, are not exposed to assistive technologies, descendants of those required elements are exposed. If we had nested a list within one of those {{HTMLElement('li')}}'s, they would be visible to assistive technologies. For elements with no required children, any elements nested inside the element with `role="presentation"` or `role="none"` preserve their semantics. In this case, the {{HTMLElement('a')}} elements contained inside of those {{HTMLElement('li')}} elements are exposed. - -The {{HTMLElement('a')}} is a special case. Its role would have been exposed even if it had the `presentation` or `none` role directly applied to it. Browsers ignore `role="presentation"` and `role="none"` on focusable elements, including link and inputs, or anything with a [tabindex](/en-US/docs/Web/HTML/Global_attributes/tabindex) attribute set. Browsers also ignore the inclusion of the role if any of the element contains any global ARIA states and properties, such as [`aria-describedby`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-describedby). - -> [!NOTE] -> The element with `role="presentation"` is not part of the accessibility tree and should not have an accessible name. Do **not** use [`aria-labelledby`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-labelledby) or [`aria-label`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-label). - -### Associated WAI-ARIA roles, states, and properties - -None. If a global ARIA state and property is set, `presentation` or `none` will be ignored, and the implicit role of the element will be used. - -## Examples - -```html -<hr role="none" /> -``` - -## Specifications - -{{Specifications}} - -## See also - -- [`aria-hidden`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-hidden) versus [`role="presentation/none"`](https://www.scottohara.me/blog/2018/05/05/hidden-vs-none.html) - by Scott O'Hara diff --git a/files/en-us/web/accessibility/aria/roles/progressbar_role/index.md b/files/en-us/web/accessibility/aria/roles/progressbar_role/index.md deleted file mode 100644 index d7791faa6e505dd..000000000000000 --- a/files/en-us/web/accessibility/aria/roles/progressbar_role/index.md +++ /dev/null @@ -1,107 +0,0 @@ ---- -title: "ARIA: progressbar role" -slug: Web/Accessibility/ARIA/Roles/progressbar_role -page-type: aria-role -spec-urls: https://w3c.github.io/aria/#progressbar ---- - -{{AccessibilitySidebar}} - -The `progressbar` role defines an element that displays the progress status for tasks that take a long time. - -## Description - -The `progressbar` range widget indicates that a request has been received and the application is making progress toward completing the requested action. - -Authors **may** set aria-valuemin and aria-valuemax to indicate the minimum and maximum progress indicator values. Otherwise, their implicit values follow the same rules as HTML's [`<input type="range">`](/en-US/docs/Web/HTML/Element/input/range): - -- If [`aria-valuemin`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-valuemin) is missing or not a number, it defaults to `0` (zero). -- If [`aria-valuemax`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-valuemax) is missing or not a number, it defaults to `100`. -- The `aria-valuemin` and `aria-valuemax` properties only need to be set for the `progressbar` role when the progress bar's minimum is not `0` or the maximum value is not `100`. -- The read-only [`aria-valuenow`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-valuenow) should be provided and updated unless the value is `indeterminate`, in which case don't include the attribute. If set, make sure the `aria-valuenow` value is between the minimum and maximum values. - -If the `progressbar` role is applied to an HTML {{HTMLElement('progress')}} element, the accessible name can come from the associated {{HTMLElement('label')}}. Otherwise use [`aria-labelledby`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-labelledby) if a visible label is present or [`aria-label`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-label) if a visible label is not present. - -### All descendants are presentational - -There are some types of user interface components that, when represented in a platform accessibility API, can only contain text. Accessibility APIs do not have a way of representing semantic elements contained in a `progressbar`. To deal with this limitation, browsers, automatically apply role [`presentation`](/en-US/docs/Web/Accessibility/ARIA/Roles/presentation_role) to all descendant elements of any `progressbar` element as it is a role that does not support semantic children. - -For example, consider the following `progressbar` element, which contains a heading. - -```html -<div role="progressbar"><h3>Title of my progressbar</h3></div> -``` - -Because descendants of `progressbar` are presentational, the following code is equivalent: - -```html -<div role="progressbar"> - <h3 role="presentation">Title of my progressbar</h3> -</div> -``` - -From the assistive technology user's perspective, the heading does not exist since the previous code snippets are equivalent to the following in the [accessibility tree](/en-US/docs/Glossary/Accessibility_tree): - -```html -<div role="progressbar">Title of my progressbar</div> -``` - -### Associated WAI-ARIA roles, states, and properties - -- [`aria-valuenow`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-valuenow) - - : Only present and required if the value is not indeterminate. Set to a decimal value between `0`, or `aria-valuemin` if present, and `aria-valuemax` indicating the current value of the progress bar. -- [`aria-valuetext`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-valuetext) - - : Assistive technologies often present the value of `aria-valuenow` as a percentage. If this would not be accurate use this property to make the progress bar value understandable. -- [`aria-valuemin`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-valuemin) - - : Set to a decimal value representing the minimum value, and less than `aria-valuemax`. If not present, the default value is `0`. -- [`aria-valuemax`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-valuemax) - - : Set to a decimal value representing the maximum value, and greater than `aria-valuemin`. If not present, the default value is `100`. -- [`aria-label`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-label) or [`aria-labelledby`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-labelledby) - - : Defines the string value or identifies the element (or elements) that label the progressbar element providing an accessible name. An accessible name is required. - -It is recommended to use a native {{HTMLElement("progress")}} or [`<input type="range">`](/en-US/docs/Web/HTML/Element/input/range) elements rather than the `progressbar` role. User agents provide a stylize widget for the {{HTMLElement("progress")}} element based on the current `value` as it relates to the `0`, the minimum value, and the `max` value. When using non-semantic elements, all features of the native semantic element need to be recreated with ARIA attributes, JavaScript and CSS. - -## Examples - -In the example below, the progress bar uses the default values of 0 and 100 for `aria-valuemin` and `aria-valuemax`: - -```html -<div> - <span id="loadinglabel">Loading:</span> - <span role="progressbar" aria-labelledby="loadinglabel" aria-valuenow="23"> - <svg width="100" height="10"> - <rect height="10" width="100" stroke="black" fill="black" /> - <rect height="10" width="23" fill="white" /> - </svg> - </span> -</div> -``` - -Using semantic HTML, this could be written as: - -```html -<label for="loadinglabel">Loading:</label> -<progress id="loadinglabel" max="100" value="23"></progress> -``` - -## Best Practices - -If the progress bar is describing the loading progress of a particular region of a page, include the [`aria-describedby`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-describedby) attribute to reference the progress bar's status, and set the [`aria-busy`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-busy) attribute to `true` on the region until it is finished loading. - -### Prefer HTML - -It is recommended to use a native {{HTMLElement("progress")}} or [`<input type="range">`](/en-US/docs/Web/HTML/Element/input/range) elements rather than the `progressbar` role. - -## Specifications - -{{Specifications}} - -## See also - -- HTML {{HTMLElement('progress')}} element -- Other range widgets include: - - [`meter`](/en-US/docs/Web/Accessibility/ARIA/Roles/meter_role) - - [`scrollbar`](/en-US/docs/Web/Accessibility/ARIA/Roles/scrollbar_role) - - [`separator`](/en-US/docs/Web/Accessibility/ARIA/Roles/separator_role) (if focusable) - - [`slider`](/en-US/docs/Web/Accessibility/ARIA/Roles/slider_role) - - [`spinbutton`](/en-US/docs/Web/Accessibility/ARIA/Roles/spinbutton_role) diff --git a/files/en-us/web/accessibility/aria/roles/radio_role/index.md b/files/en-us/web/accessibility/aria/roles/radio_role/index.md deleted file mode 100644 index 59c3f8846cdec2c..000000000000000 --- a/files/en-us/web/accessibility/aria/roles/radio_role/index.md +++ /dev/null @@ -1,305 +0,0 @@ ---- -title: "ARIA: radio role" -slug: Web/Accessibility/ARIA/Roles/radio_role -page-type: aria-role ---- - -{{AccessibilitySidebar}} - -The `radio` role is one of a group of checkable radio buttons, in a `radiogroup`, where no more than a single radio button can be checked at a time. - -## Description - -A radio button is a checkable input that when associated with other radio buttons, only one of which can be checked at a time. The radio buttons must be grouped together in a [`radiogroup`](/en-US/docs/Web/Accessibility/ARIA/Roles/radiogroup_role) to indicate which ones affect the same value. - -```html -<div role="radiogroup" aria-labelledby="legend25" id="radiogroup25"> - <p id="legend25">Ipsum and lorem?</p> - <div> - <span - role="radio" - aria-checked="false" - tabindex="0" - aria-labelledby="q25_radio1-label" - data-value="True"></span> - <label id="q25_radio1-label">True</label> - </div> - <div> - <span - role="radio" - aria-checked="false" - tabindex="0" - aria-labelledby="q25_radio2-label" - data-value="False"></span> - <label id="q25_radio2-label">False</label> - </div> - <div> - <span - role="radio" - aria-checked="true" - tabindex="0" - aria-labelledby="q25_radio3-label" - data-value="huh?"></span> - <label id="q25_radio3-label">What is the question?</label> - </div> -</div> -``` - -The `role` attribute only adds semantics; all of the functionality that comes natively with the [HTML radio](/en-US/docs/Web/HTML/Element/input/radio) needs to be added with JavaScript and the HTML [`tabindex`](/en-US/docs/Web/HTML/Global_attributes/tabindex) attribute. - -> [!NOTE] -> The first rule of ARIA is if a native HTML element or attribute has the semantics and behavior you require, use it instead of re-purposing an element and adding ARIA. Instead use the native [HTML `<input type="radio">`](/en-US/docs/Web/HTML/Element/input/radio) (with an associated {{HTMLElement('label')}}), which natively provides all the functionality required: - -```html -<fieldset> - <legend>Ipsum and lorem?</legend> - <div> - <input type="radio" value="True" id="q25_radio1" name="q25" /> - <label for="q25_radio1">True</label> - </div> - <div> - <input type="radio" value="False" id="q25_radio2" name="q25" /> - <label for="q25_radio2">False</label> - </div> - <div> - <input type="radio" value="huh?" id="q25_radio3" name="q25" checked /> - <label for="q25_radio3">What is the question?</label> - </div> -</fieldset> -``` - -The native HTML radio form control ([`<input type="radio">`](/en-US/docs/Web/HTML/Element/input/radio)) has two states ("checked" or "not checked"). Similarly, an element with `role="radio"` can expose two states through the [`aria-checked`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-checked) attribute: `true` representing the checked state, and `false` representing the unchecked state. The `aria-checked` value of `mixed` is not valid to use for a radio button. - -If a radio button is checked, the radio element has `aria-checked` set to `true`. If it is not checked, it has `aria-checked` set to `false`. - -Each radio button element has role `radio`. The radio role should always be nested with other associated radios in a `radiogroup`. If it is not possible to nest the radio button within a radio group, use the `id` of the non-grouped radio in a space separated list of values as the value of the [`aria-owns`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-owns) attribute on the `radiogroup` element to indicate the relationship of the `radiogroup` to its radio members. - -Each radio element is labelled by its content, has a visible label referenced by `aria-labelledby`, or has a label specified with `aria-label`. The containing `radiogroup` element should either have a visible label referenced by `aria-labelledby` or a label specified with `aria-label`. If elements providing additional information about either the radio group or each radio button are present, those elements should be referenced by the `radiogroup` element or radio elements with the [`aria-describedby`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-describedby) property. - -As `radio` is an interactive control; it must be focusable and keyboard accessible. If the role is applied to a non-focusable element, use the [`tabindex`](/en-US/docs/Web/HTML/Global_attributes/tabindex) attribute to change this. The expected keyboard shortcut for activating a radio is the <kbd>Space</kbd> key. Use JavaScript to toggle the `aria-checked` attribute to `true` when a radio becomes checked while ensuing that all the other radio roles in the group are set to `aria-checked="false"`. - -To programmatically indicate that a radio button must be chosen from a radio group the [`aria-required`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-required) attribute, with a value of `true`, must be specified on the `radiogroup` element. It is not expected to use the `aria-required` attribute on individual ARIA radio buttons. - -### All descendants are presentational - -There are some types of user interface components that, when represented in a platform accessibility API, can only contain text. Accessibility APIs do not have a way of representing semantic elements contained in a `radio`. To deal with this limitation, browsers, automatically apply role [`presentation`](/en-US/docs/Web/Accessibility/ARIA/Roles/presentation_role) to all descendant elements of any `radio` element as it is a role that does not support semantic children. - -For example, consider the following `radio` element, which contains a heading. - -```html -<div role="radio"><h6>name of my radio</h6></div> -``` - -Because descendants of `radio` are presentational, the following code is equivalent: - -```html -<div role="radio"><h6 role="presentation">name of my radio</h6></div> -``` - -From the assistive technology user's perspective, the heading does not exist since the previous code snippets are equivalent to the following in the [accessibility tree](/en-US/docs/Glossary/Accessibility_tree): - -```html -<div role="radio">name of my radio</div> -``` - -## Associated WAI-ARIA Roles, States, and Properties - -- [`radiogroup`](/en-US/docs/Web/Accessibility/ARIA/Roles/radiogroup_role) role - - - : The radio buttons are contained in or owned by an element with role `radiogroup`. If unable to be nested within a `radiogroup` within the markup, the `aria-owns` attribute of the `radiogroup` contains the `id` values of the non-nested radio buttons in the group. - -- [`aria-checked`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-checked) - - - : The value of `aria-checked` defines the state of a radio. When used with radio elements, the attribute has one of two possible values: - - - `true` - - : The radio is checked. - - `false` - - : The radio is not checked. - -> [!NOTE] -> Use the [`tabindex` attribute](/en-US/docs/Web/HTML/Global_attributes/tabindex) if the `role="radio"` is used on an element that does not natively accept keyboard focus. E.g., a `<div>` or `<span>`. - -## Keyboard interactions - -- <kbd>Tab</kbd> + <kbd>Shift</kbd> - - - : Move focus into and out of the radio group. When focus moves into a radio group, and a radio button is already checked, focus is set on the checked button. If none of the radio buttons are checked, focus is set on the first radio button in the group. - -- <kbd>Space</kbd> - - - : Checks the radio if not already checked. Unchecks a previously checked radio button in the radio group. - -- <kbd>Right Arrow</kbd> and <kbd>Down Arrow</kbd> - - - : Move focus to and checks the next radio button in the group, unchecking the previously focused radio button. If focus is on the last radio button, focus moves to the first radio button. - -- <kbd>Left Arrow</kbd> and <kbd>Up Arrow</kbd> - - : Move focus to and checks the previous radio button in the group, unchecking the previously focused radio button. If focus is on the first radio button, focus moves to the last radio button. - -### Radios in a toolbar - -Because arrow keys are used to navigate among elements of a toolbar and the <kbd>Tab</kbd> key moves focus in and out of a toolbar, when a radio group is nested inside a toolbar, the keyboard interaction of the radio group is slightly different from that of a radio group that is not inside of a toolbar. See [`radiogroup` keyboard interactions](/en-US/docs/Web/Accessibility/ARIA/Roles/radiogroup_role#keyboard_interactions) for more information - -## Required JavaScript - -- `onClick` - - : Handle mouse clicks on both the radio and the associated label that will change the state of the radio by changing the value of the `aria-checked` attribute and the appearance of the radio so it appears checked or unchecked to the sighted user -- `onKeyPress` - - : Handle the case where the user presses the <kbd>Space</kbd> key to change the state of the radio by changing the value of the `aria-checked` attribute and the appearance of the radio so it appears checked or unchecked to the sighted user - -## Examples - -The following example uses ARIA to modify otherwise generic elements to be exposed as radio buttons. CSS and JavaScript are used to visually and programmatically modify the checked or unchecked state of the element. - -### HTML - -```html -<div role="radiogroup" aria-labelledby="legend" id="radiogroup"> - <p id="legend"> - Should you be using the <code>radio</code> role or - <code>&lt;input type="radio"></code>? - </p> - <div> - <span - role="radio" - aria-checked="true" - tabindex="0" - aria-labelledby="ariaLabel" - data-value="True"></span> - <label id="ariaLabel">ARIA role</label> - </div> - <div> - <span - role="radio" - aria-checked="false" - tabindex="0" - aria-labelledby="htmllabel" - data-value="False"></span> - <label id="htmllabel">HTML <code>&lt;input type="radio"></code></label> - </div> -</div> -``` - -### CSS - -```css -[role="radio"] { - padding: 5px; -} - -[role="radio"][aria-checked="true"]::before { - content: "(x)"; - font-family: monospace; -} - -[role="radio"][aria-checked="false"]::before { - content: "( )"; - font-family: monospace; -} -``` - -### JavaScript - -A lot of JavaScript is required to make radio buttons out of non-semantic HTML. - -```js -// initialize all the radio role elements - -const radioGroups = document.querySelectorAll('[role="radiogroup"]'); - -for (let i = 0; i < radioGroups.length; i++) { - const radios = radioGroups[i].querySelectorAll("[role=radio]"); - for (let j = 0; j < radios.length; j++) { - radios[j].addEventListener("keydown", function () { - handleKeydown(); - }); - radios[j].addEventListener("click", function () { - handleClick(); - }); - } -} - -// handle mouse and touch events -let handleClick = function (event) { - setChecked(this); - event.stopPropagation(); - event.preventDefault(); -}; - -// handle key presses -let handleKeydown = function (event) { - switch (event.code) { - case "Space": - case "Enter": - currentChecked(); - break; - - case "ArrowUp": - case "ArrowLeft": - previousRadioChecked(); - break; - - case "ArrowDown": - case "ArrowRight": - nextItemChecked(); - break; - - default: - break; - } - event.stopPropagation(); - event.preventDefault(); -}; - -// when a radio is selected, give it focus, set checked to true; -// ensure all other radios in radio group are not checked - -setChecked = function () { - // uncheck all the radios in group - // iterated through all the radios in radio group - // eachRadio.tabIndex = -1; - // eachRadio.setAttribute('aria-checked', 'false'); - // set the selected radio to checked - // thisRadio.setAttribute('aria-checked', 'true'); - // thisRadio.tabIndex = 0; - // thisRadio.focus(); - // set the value of the radioGroup to the value of the currently selected radio -}; -``` - -<!-- {{EmbedLiveSample("Examples", 230, 250)}} --> - -No JavaScript (or even CSS) would be needed had we used semantic HTML element with the name of each radio button in a group of radio buttons being the same: - -```html -<fieldset> - <legend> - Should you be using the <code>radio</code> role or - <code>&lt;input type="radio"></code>? - </legend> - <div> - <input type="radio" name="bestPractices" id="ariaLabel" value="True" /> - <label for="ariaLabel">ARIA role</label> - </div> - <div> - <input type="radio" name="bestPractices" id="htmllabel" value="False" /> - <label for="htmllabel">HTML <code>&lt;input type="radio"></code></label> - </div> -</fieldset> -``` - -## Best practices - -The first rule of ARIA is: if a native HTML element or attribute has the semantics and behavior you require, use it instead of re-purposing an element and adding an ARIA role, state or property to make it accessible. As such, it is recommended to use native [HTML radio button](/en-US/docs/Web/HTML/Element/input/radio) form controls instead of recreating a radio's functionality with JavaScript and ARIA. - -## See also - -- [HTML `<input type="radio">` radio button](/en-US/docs/Web/HTML/Element/input/radio) -- [HTML `tabindex` attribute](/en-US/docs/Web/HTML/Global_attributes/tabindex) -- [ARIA: `radiogroup` role](/en-US/docs/Web/Accessibility/ARIA/Roles/radiogroup_role) -- [ARIA: `checkbox` role](/en-US/docs/Web/Accessibility/ARIA/Roles/checkbox_role) -- [ARIA: `menuitem` role](/en-US/docs/Web/Accessibility/ARIA/Roles/menuitem_role) -- [ARIA: `menuitemradio` role](/en-US/docs/Web/Accessibility/ARIA/Roles/menuitemradio_role) -- [ARIA: `menuitemradio` role](/en-US/docs/Web/Accessibility/ARIA/Roles/menuitemradio_role) -- [ARIA: `option` role](/en-US/docs/Web/Accessibility/ARIA/Roles/option_role) diff --git a/files/en-us/web/accessibility/aria/roles/radiogroup_role/index.md b/files/en-us/web/accessibility/aria/roles/radiogroup_role/index.md deleted file mode 100644 index 21421ddcd258a81..000000000000000 --- a/files/en-us/web/accessibility/aria/roles/radiogroup_role/index.md +++ /dev/null @@ -1,154 +0,0 @@ ---- -title: "ARIA: radiogroup role" -slug: Web/Accessibility/ARIA/Roles/radiogroup_role -page-type: aria-role -spec-urls: - - https://w3c.github.io/aria/#radiogroup - - https://www.w3.org/WAI/ARIA/apg/patterns/radio/examples/radio/ ---- - -{{AccessibilitySidebar}} - -The `radiogroup` role is a group of `radio` buttons. - -## Description - -Radio groups are collections describing a set of related [`radio`](/en-US/docs/Web/Accessibility/ARIA/Roles/radio_role) options. A `radiogroup` is a type of [`select`](/en-US/docs/Web/Accessibility/ARIA/Roles/select_role) list that can only have a single entry, or `radio`, checked at any one time. - -When using HTML's native input radio button, [`<input type="radio">`](/en-US/docs/Web/HTML/Element/input/radio), the radio buttons are grouped when each of input radio buttons in the group is given the same [`name`](/en-US/docs/Web/HTML/Element/input#name). Once a group of same-named input radio buttons is established, selecting any input radio button in that group automatically deselects any currently-selected input radio button in the same group. While this will associate the radio buttons together, to expose a grouping of radio buttons as a `radiogroup` explicitly set the ARIA role. - -It is recommended to create radio groups by using same-named HTML input radio buttons, but, if you must use ARIA roles and attributes instead of semantic HTML form controls, custom `radio` buttons can and should act like native HTML radio input buttons. - -When using non-semantic elements as radio buttons, you must ensure your users can only select one radio button from the group at a time. When one item in the group is checked, having their [`aria-checked`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-checked) attribute set to `true`, the previously checked item becomes unchecked, with its `aria-checked` attribute becoming `false`. The `aria-checked` attribute is set on the associated `radio` roles, not on the `radiogroup` itself. - -Some `radiogroup` implementations initialize the set with all buttons in the unchecked state. Once a `radio` in a `radiogroup` is checked, it is generally not possible to return to an all-unchecked state. - -The `radiogroup` must have an accessible name either by a visible label referenced by [`aria-labelledby`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-labelledby) or has a label specified with [`aria-label`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-label). If elements provide additional information about the radio group, those elements are referenced by the `radiogroup` element with the [`aria-describedby`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-describedby) property. - -### Associated WAI-ARIA roles, states, and properties - -- [`radio`](/en-US/docs/Web/Accessibility/ARIA/Roles/radio_role) role - - : One of a group of checkable buttons, in a `radiogroup`, where no more than one of the buttons can be checked at a time. -- [`aria-labelledby`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-labelledby) / [`aria-label`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-label) - - : The `radiogroup` must have an accessible name either by a visible label referenced by `aria-labelledby` or has a label specified with `aria-label`. -- [`aria-describedby`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-describedby) - - : Reference to elements providing additional information about the `radiogroup` -- [`aria-required`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-required) - - : Indicates that one `radio` within the group must have `aria-checked="true"` set before the form may be submitted. The required state is specified on the `radiogroup` element rather than one of the `radio` elements, unlike when using HTML radio buttons where the [`required`](/en-US/docs/Web/HTML/Attributes/required) attribute is set directly on one or more radio {{HTMLElement('input')}} elements. -- [`aria-errormessage`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-errormessage) - - : Identifies the element that provides an error message for the `radiogroup`, if there is an error. That message should be hidden while not relevant. - -### Keyboard interactions - -For `radio` buttons in a `radiogroup` that is NOT in a [`toolbar`](/en-US/docs/Web/Accessibility/ARIA/Roles/toolbar_role), the following keyboard interactions must be supported: - -- <kbd>Tab</kbd> and <kbd>Shift + Tab</kbd> - - : Move focus into and out of the `radiogroup`. When focus moves into a `radiogroup`, if a radio button is checked, focus is set on the checked button. If none of the radio buttons are checked, focus is set on the first radio button in the group. -- <kbd>Space</kbd> - - : Checks the focused radio button if it is not already checked. -- <kbd>Right Arrow</kbd> and <kbd>Down Arrow</kbd> - - : Moves focus to the next radio button in the group, unchecking the previously focused button, and checking the newly focused button. If focus is on the last button, focus moves to the first button. -- <kbd>Left Arrow</kbd> and <kbd>Up Arrow</kbd> - - : Moves focus to the previous radio button in the group, unchecking the previously focused button, and checking the newly focused button. If focus is on the first button, focus moves to the last button. - -Arrow keys are used to navigate among elements of a toolbar. When a `radiogroup` is nested inside a toolbar, users need to be able to navigate among all toolbar elements, including the radio buttons, without changing which radio button is checked. So, when navigating through a `radiogroup` in a [`toolbar`](/en-US/docs/Web/Accessibility/ARIA/Roles/toolbar_role) with arrow keys, the button that is checked does not change. Rather, when inside a `toolbar`, the <kbd>Space</kbd> and <kbd>Enter</kbd> keys check the focused `radio` button if it is not already checked, with <kbd>Tab</kbd> moving focus into and out of the `toolbar`. - -### Required JavaScript features - -User interactions for `radiogroup`s must replicate the user interaction of a user entering into a group of same-named HTML radio buttons. Keyboard events for tabs, space, and arrow keys must be captured. Click events on both the radio elements and their associated labels must also be captured. Additionally, [focus must be managed](https://usability.yale.edu/web-accessibility/articles/focus-keyboard-operability). - -While generally moving off an a focused element brings you to the next focusable element in the DOM order, using the arrow keys to navigate through a group of radio button keeps you in the group, moving focus to the first radio button when the <kbd>Right Arrow</kbd> or <kbd>Down Arrow</kbd> is released when focus was on the last radio in the group, and moving to the last radio if the <kbd>Left Arrow</kbd> or <kbd>Up Arrow</kbd> is released if focus was on the first radio. Managing roving [`tabindex`](/en-US/docs/Web/HTML/Global_attributes/tabindex) is one method to manage arrow key events. - -### Required CSS features - -Use the `[aria-checked="true"]` [attribute selector](/en-US/docs/Web/CSS/Attribute_selectors) to style the checked state of checked radio buttons. - -Use CSS {{CSSXRef(':hover')}} and {{CSSXRef(':focus')}} pseudo-classes for styling visual keyboard focus and hover. The focus and hover effect should encompass both the radio button and label to make it easier to perceive which option is being chosen and to indicate that clicking either the label or button will activate the radio button. - -## Examples - -The basic set up for a `radiogroup` using non-semantic ARIA roles instead of semantic HTML is as follows: - -```html -<div role="radiogroup" aria-labelledby="question"> - <div id="question">Which is the best color?</div> - <div id="radioGroup"> - <p> - <span - id="colorOption_0" - tabindex="0" - role="radio" - aria-checked="false" - aria-labelledby="purple"></span> - <span id="purple">Purple</span> - </p> - <p> - <span - id="colorOption_1" - tabindex="-1" - role="radio" - aria-checked="false" - aria-labelledby="aubergine"></span> - <span id="aubergine">Aubergine</span> - </p> - <p> - <span - id="colorOption_2" - tabindex="-1" - role="radio" - aria-checked="false" - aria-labelledby="magenta"></span> - <span id="magenta">Magenta</span> - </p> - <p> - <span - id="colorOption_3" - tabindex="-1" - role="radio" - aria-checked="false" - aria-labelledby="all"></span> - <span id="all">All of the above</span> - </p> - </div> -</div> -``` - -This could have been written using semantic HTML, which requires no CSS or JavaScript: - -```html -<fieldset> - <legend>Which is the best color?</legend> - <p> - <input name="colorOption" type="radio" id="purple" /> - <label for="purple">Purple</label> - </p> - <p> - <input name="colorOption" type="radio" id="aubergine" /> - <label for="aubergine">Aubergine</label> - </p> - <p> - <input name="colorOption" type="radio" id="magenta" /> - <label for="magenta">Magenta</label> - </p> - <p> - <input name="colorOption" type="radio" id="all" /> - <label for="all">All of the above</label> - </p> -</fieldset> -``` - -In this {{HTMLElement('fieldset')}} example, while `role="radiogroup"` is not necessary, to have this grouping explicitly announced as `radiogroup`, include the ARIA role. - -## Specifications - -{{Specifications}} - -## See also - -- HTML {{HTMLElement('fieldset')}} element -- HTML {{HTMLElement('input/radio', '&lt;input type="radio">')}} radio button element -- [ARIA `radio` role](/en-US/docs/Web/Accessibility/ARIA/Roles/radio_role) -- [`aria-errormessage`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-errormessage) -- [`aria-invalid`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-invalid) -- [`aria-readonly`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-readonly) -- [`aria-required`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-required) diff --git a/files/en-us/web/accessibility/aria/roles/range_role/index.md b/files/en-us/web/accessibility/aria/roles/range_role/index.md deleted file mode 100644 index db35cf10661a4af..000000000000000 --- a/files/en-us/web/accessibility/aria/roles/range_role/index.md +++ /dev/null @@ -1,37 +0,0 @@ ---- -title: "ARIA: range role" -slug: Web/Accessibility/ARIA/Roles/range_role -page-type: aria-role -spec-urls: https://w3c.github.io/aria/#range ---- - -{{AccessibilitySidebar}} - -The `range` abstract role is a generic type of structure role representing a range of values. - -> [!NOTE] -> The `range` role is an [abstract role](/en-US/docs/Web/Accessibility/ARIA/Roles#6._abstract_roles). It is included here for completeness of documentation. It is not to be used by web authors. - -## Description - -The `range` role is an abstract role. It must not be used by web authors. It is the superclass for structural roles for elements that accept a value within a range of values, including the [`meter`](/en-US/docs/Web/Accessibility/ARIA/Roles/meter_role) role, [`progressbar`](/en-US/docs/Web/Accessibility/ARIA/Roles/progressbar_role) and [`slider`](/en-US/docs/Web/Accessibility/ARIA/Roles/slider_role). For these three, consider using the {{HTMLElement("meter")}} element, the {{HTMLElement("progress")}} element, and the {{HTMLElement("input/range")}}, respectively. - -## Best Practices - -Do not use. - -## Specifications - -{{Specifications}} - -## See also - -- [ARIA: `structure` role](/en-US/docs/Web/Accessibility/ARIA/Roles/structure_role) -- [ARIA: `meter` role](/en-US/docs/Web/Accessibility/ARIA/Roles/meter_role) -- [ARIA: `progressbar` role](/en-US/docs/Web/Accessibility/ARIA/Roles/progressbar_role) -- [ARIA: `scrollbar` role](/en-US/docs/Web/Accessibility/ARIA/Roles/scrollbar_role) -- [ARIA: `slider` role](/en-US/docs/Web/Accessibility/ARIA/Roles/slider_role) -- [ARIA: `spinbutton` role](/en-US/docs/Web/Accessibility/ARIA/Roles/spinbutton_role) -- {{HTMLElement("input/range")}} -- {{HTMLElement("meter")}} -- {{HTMLElement("progress")}} diff --git a/files/en-us/web/accessibility/aria/roles/region_role/index.md b/files/en-us/web/accessibility/aria/roles/region_role/index.md deleted file mode 100644 index e68d0a58927d9e5..000000000000000 --- a/files/en-us/web/accessibility/aria/roles/region_role/index.md +++ /dev/null @@ -1,102 +0,0 @@ ---- -title: "ARIA: region role" -slug: Web/Accessibility/ARIA/Roles/region_role -page-type: aria-role -spec-urls: - - https://w3c.github.io/aria/#region - - https://www.w3.org/WAI/ARIA/apg/patterns/landmarks/examples/region.html ---- - -{{AccessibilitySidebar}} - -The **`region`** role is used to identify document areas the author deems significant. It is a generic landmark available to aid in navigation when none of the other landmark roles are appropriate. - -```html -<div role="region" aria-label="Example"> - <!-- region content --> -</div> -``` - -## Description - -The `region` role is an [ARIA landmark](/en-US/docs/Web/Accessibility/ARIA/Roles#3._landmark_roles) role. -The `region` role should be reserved for sections of content sufficiently important that users will likely want to navigate to the section easily and to have it listed in a summary of the page. A region role is a more generic term, and should only be used if the section needing to be identified is not accurately described by one of the other landmark roles, such as [`banner`](/en-US/docs/Web/Accessibility/ARIA/Roles/banner_role), [`main`](/en-US/docs/Web/Accessibility/ARIA/Roles/main_role), [`contentinfo`](/en-US/docs/Web/Accessibility/ARIA/Roles/contentinfo_role), [`complementary`](/en-US/docs/Web/Accessibility/ARIA/Roles/complementary_role), or [`navigation`](/en-US/docs/Web/Accessibility/ARIA/Roles/navigation_role). - -Every element with a `region` role should include a label that describes the purpose of the content in the region, preferably with an [`aria-labelledby`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-labelledby) referencing a visible header. If no visible appropriate header is present, [`aria-label`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-label) should be used. - -The `region` landmark role's content should make sense if separated from the main content of the document. - -Using the {{HTMLElement('section')}} element will automatically communicate a section has a role of `region` if it is given an accessible name. Developers should always prefer using the correct semantic HTML element, in this case `<section>`, over using ARIA. - -### Associated WAI-ARIA Roles, States, and Properties - -- [`aria-labelledby`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-labelledby) or [`aria-label`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-label) - - : Use this attribute to label the region. Often, the value of the `aria-labelledby` attribute will be the id of the element used to title the section. If no visible appropriate header is present, `aria-label` should be used. - -## Examples - -```html -<div role="region" aria-labelledby="region-heading"> - <h2 id="region-heading"> - This heading's `id` attribute helps this region have an accessible name - </h2> - <!-- region content --> -</div> -``` - -## Accessibility concerns - -Use sparingly! [Landmark roles](/en-US/docs/Web/Accessibility/ARIA/Roles#3._landmark_roles) are intended to be used sparingly, to identify larger overall sections of the document. Using too many landmark roles can create "noise" in screen readers, making it difficult to understand the overall layout of the page. - -Only use the `region` role if no other relevant [content sectioning](/en-US/docs/Web/HTML/Element#content_sectioning) element or [landmark role](/en-US/docs/Web/Accessibility/ARIA/Roles#3._landmark_roles) applies. If multiple regions exist on a page, it may be worth reinvestigating the page's overall structure. - -## Best practices - -### Prefer HTML - -Using the {{HTMLElement('section')}} element will automatically communicate that a section has a role of `region` if it is given an accessible name. If at all possible, prefer using {{HTMLElement('section')}} instead. - -### Labeling landmarks - -If there is more than one `region` landmark role in a document, provide a unique label for each one. This label will allow an assistive technology user to be able to quickly understand the purpose of each landmark. - -```html -<div role="region" aria-labelledby="use-discretion"> - <h3 id="use-discretion">Please use the `region` role with discretion</h3> - <!-- content --> -</div> - -… - -<div role="region" aria-labelledby="please-reconsider"> - <h3 id="please-reconsider">Please reconsider your document structure</h3> - <!-- content --> -</div> -``` - -In this example, the region's label is being generated by the [`aria-labelledby` attribute](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-labelledby). - -### Scrolling content areas with overflow text - -If there is a content area with `tabindex="0"`, add `role="region"` to convey to screen reader users that is a generic region. This is done to allow keyboard-only users to scroll regions with overflow text. - -### SVG - -`role="region"` can be declared on areas of {{SVGElement('svg')}} along with an `aria-label` to allow individual sections of the SVG to be described. - -## Specifications - -{{Specifications}} - -## See also - -- The {{HTMLElement('section')}} element -- [region (role): Accessible Rich Internet Applications (WAI-ARIA) 1.1](https://www.w3.org/TR/wai-aria/#region) -- [ARIA: `banner` role](/en-US/docs/Web/Accessibility/ARIA/Roles/banner_role) -- [ARIA: `main` role](/en-US/docs/Web/Accessibility/ARIA/Roles/main_role) -- [ARIA: `contentinfo` role](/en-US/docs/Web/Accessibility/ARIA/Roles/contentinfo_role) -- [ARIA: `complementary` role](/en-US/docs/Web/Accessibility/ARIA/Roles/complementary_role) -- [ARIA: `navigation` role](/en-US/docs/Web/Accessibility/ARIA/Roles/navigation_role) -- [Landmark roles: Using ARIA: Roles, States, and Properties](/en-US/docs/Web/Accessibility/ARIA/ARIA_Techniques#landmark_roles) -- [Using WAI-ARIA Landmarks – 2013 | The Paciello Group](https://www.tpgi.com/using-wai-aria-landmarks-2013/) -- [Accessible Landmarks | scottohara.me](https://www.scottohara.me/blog/2018/03/03/landmarks.html) diff --git a/files/en-us/web/accessibility/aria/roles/roletype_role/index.md b/files/en-us/web/accessibility/aria/roles/roletype_role/index.md deleted file mode 100644 index c18292f1df3f668..000000000000000 --- a/files/en-us/web/accessibility/aria/roles/roletype_role/index.md +++ /dev/null @@ -1,33 +0,0 @@ ---- -title: "ARIA: roletype role" -slug: Web/Accessibility/ARIA/Roles/roletype_role -page-type: aria-role -spec-urls: https://w3c.github.io/aria/#roletype ---- - -{{AccessibilitySidebar}} - -The **`roletype`** role, an [abstract role](/en-US/docs/Web/Accessibility/ARIA/Roles#6._abstract_roles), is the base role from which all other ARIA roles inherit. - -> [!NOTE] -> The `roletype` role is an abstract role used for the ontology. It is included here for completeness of documentation. It should not be used by web authors. - -## Description - -The `roletype` role's properties describe the structural and functional purpose of objects that are assigned this role, or "instances". A role is a concept that can be used to understand and operate instances. -Note - -## Best Practices - -Do not use. - -## Specifications - -{{Specifications}} - -## See also - -- [ARIA: `structure` role](/en-US/docs/Web/Accessibility/ARIA/Roles/structure_role) -- [ARIA: `widget` role](/en-US/docs/Web/Accessibility/ARIA/Roles/widget_role) -- [ARIA: `window` role](/en-US/docs/Web/Accessibility/ARIA/Roles/window_role) -- The HTML [`rel`](/en-US/docs/Web/HTML/Attributes/rel) attribute diff --git a/files/en-us/web/accessibility/aria/roles/row_role/index.md b/files/en-us/web/accessibility/aria/roles/row_role/index.md deleted file mode 100644 index dc9c37220499ef4..000000000000000 --- a/files/en-us/web/accessibility/aria/roles/row_role/index.md +++ /dev/null @@ -1,226 +0,0 @@ ---- -title: "ARIA: row role" -slug: Web/Accessibility/ARIA/Roles/row_role -page-type: aria-role -spec-urls: - - https://w3c.github.io/aria/#row - - https://www.w3.org/WAI/ARIA/apg/patterns/table/examples/table/ ---- - -{{AccessibilitySidebar}} - -An element with `role="row"` is a row of cells within a tabular structure. A row contains one or more cells, grid cells or column headers, and possibly a row header, within a [`grid`](/en-US/docs/Web/Accessibility/ARIA/Roles/grid_role), [`table`](/en-US/docs/Web/Accessibility/ARIA/Roles/table_role) or [`treegrid`](/en-US/docs/Web/Accessibility/ARIA/Roles/treegrid_role), and optionally within a [`rowgroup`](/en-US/docs/Web/Accessibility/ARIA/Roles/rowgroup_role). - -```html -<div - role="table" - aria-label="Populations" - aria-describedby="country_population_desc"> - <div id="country_population_desc">World Populations by Country</div> - <div role="rowgroup"> - <div role="row"> - <span role="columnheader" aria-sort="descending">Country</span> - <span role="columnheader" aria-sort="none">Population</span> - </div> - </div> - <div role="rowgroup"> - <div role="row"> - <span role="cell">Finland</span> - <span role="cell">5.5 million</span> - </div> - <div role="row"> - <span role="cell">France</span> - <span role="cell">67 million</span> - </div> - </div> -</div> -``` - -## Description - -The element with `role="row"` is a row within a [`grid`](/en-US/docs/Web/Accessibility/ARIA/Roles/grid_role), [`table`](/en-US/docs/Web/Accessibility/ARIA/Roles/table_role), or [`treegrid`](/en-US/docs/Web/Accessibility/ARIA/Roles/treegrid_role), and optionally within a [`rowgroup`](/en-US/docs/Web/Accessibility/ARIA/Roles/rowgroup_role) that contains one or more [`cell`](/en-US/docs/Web/Accessibility/ARIA/Roles/cell_role), [`gridcell`](/en-US/docs/Web/Accessibility/ARIA/Roles/gridcell_role), [`columnheader`](/en-US/docs/Web/Accessibility/ARIA/Roles/columnheader_role), or [`rowheader`](/en-US/docs/Web/Accessibility/ARIA/Roles/rowheader_role) elements within a static tabular structure. Using native [HTML `<tr>`](/en-US/docs/Web/HTML/Element/tr) elements, whenever possible, is strongly encouraged. - -To create an ARIA row, add `role="row"` to the container element. That row should be nested within a grid, table or treegrid. A group of rows can be nested within a grid, table or treegrid directly, or within a rowgroup in one of those containers. Each row contains child cells. These cells can be of different types, depending on whether they are column or row headers, or grid or regular cells. - -A row can contain a number of attributes clarifying the row's role, including [`aria-colindex`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-colindex), [`aria-level`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-level), [`aria-rowindex`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-rowindex), and [`aria-selected`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-selected). - -If the row is within a treegrid, rows can include the [`aria-expanded`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-expanded) attribute, using the attribute to indicate the present status. This is not the case for an ordinary table or grid, in which the `aria-expanded` attribute is not present. - -To create an interactive widget that has a tabular structure, use the grid pattern instead. If the interaction provides for the selection state of individual cells, if left to right and top to bottom navigation is provided, or if the user interface allows the rearranging of cell order or otherwise changing individual cell order such as through drag and drop, use [grid](/en-US/docs/Web/Accessibility/ARIA/Roles/grid_role) or [treegrid](/en-US/docs/Web/Accessibility/ARIA/Roles/treegrid_role) instead. - -> [!NOTE] -> Using the native HTML table element ({{HTMLElement('table')}}) along with the table row element ({{HTMLElement('tr')}}) whenever possible is strongly encouraged. - -### Associated WAI-ARIA roles, states, and properties - -#### Context roles - -- [role="rowgroup"](/en-US/docs/Web/Accessibility/ARIA/Roles/rowgroup_role) - - : An optional contextual row parent, it establishes a relationship between descendant rows. It is a structural equivalent to the thead, tfoot, and tbody elements in an HTML table element. -- [role="table"](/en-US/docs/Web/Accessibility/ARIA/Roles/table_role) - - : One of the three possible contexts (along with grid and treegrid) in which you'll find a row, it identifies the row as being part of a non-interactive table structure containing data arranged in rows and columns, similar to the native {{HTMLElement('table')}} HTML element. -- [role="grid"](/en-US/docs/Web/Accessibility/ARIA/Roles/grid_role) - - : One of the three possible contexts (along with table and treegrid) in which you'll find a row, it identifies the row as being part of a non-interactive table structure containing data arranged in rows and columns, similar to the native {{HTMLElement('table')}} HTML element. -- [role="treegrid"](/en-US/docs/Web/Accessibility/ARIA/Roles/treegrid_role) - - : Similar to a grid, but with rows that can be expanded and collapsed in the same manner as for a tree. - -#### Descendant roles - -- [role="cell"](/en-US/docs/Web/Accessibility/ARIA/Roles/cell_role) - - : A cell in a row within a tabular container. -- [role="gridcell"](/en-US/docs/Web/Accessibility/ARIA/Roles/gridcell_role) - - : A cell in a row within a grid or treegrid. -- [role="columnheader"](/en-US/docs/Web/Accessibility/ARIA/Roles/columnheader_role) - - : A header cell that is the structural equivalent of the HTML {{HTMLElement('th')}} element with a column scope ({{HTMLElement('tr', '<code>&lt;tr scope="col"&gt;</code>')}}). Unlike a plain cell, the columnheader role establishes a relationship between it and all cells in the corresponding column. -- [role="rowheader"](/en-US/docs/Web/Accessibility/ARIA/Roles/rowheader_role) - - : A header cell that is the structural equivalent of the HTML {{HTMLElement('th')}} element with a row scope ({{HTMLElement('tr', '<code>&lt;tr scope="row"&gt;</code>')}}). Unlike a plain cell, the rowheader role establishes a relationship between it and all cells in the corresponding row. - -#### States and properties - -- [`aria-expanded`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-expanded) state - - - : The `aria-expanded` attribute, which defines the state of the row, can take one of three values, or be omitted: - - - `aria-expanded="true"`: Row is currently expanded. - - `aria-expanded="false"`: Row is currently collapsed. - - `aria-expanded="undefined"` or the attribute is missing: The row is neither expandable nor collapsible. - - If the element with the `aria-expanded` attribute controls the expansion of another grouping container that is not 'owned by' the element, the author **should** reference the container by using the `aria-controls` attribute. - -- [`aria-selected`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-selected) state - - - : Only relevant if the row is in an interactive container, such as a grid or treegrid, but not relevant if the row is in a table. The `aria-selected` attribute can take one of three values, or be omitted: - - - `aria-selected="true"`: Row is currently selected - - `aria-selected="false"`: Row is not currently selected. - - `aria-selected="undefined"` or the attribute is missing: The row is not selectable. - -- [`aria-colindex`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-colindex) attribute - - - : The `aria-colindex` attribute is only needed if columns are hidden from the DOM. It is generally placed on row children, rather than on the row itself. If the columns displayed are contiguous, then it can be placed on the row. - - The attribute takes as its value an integer between 1 and the total number of columns within the table, grid or treegrid. When placed on the row, the `aria-colindex` defines an element's column index or position with respect to the total number of columns within a row. For example, in a table with 15 columns, and columns 4, 5, and 6 are in the DOM, `aria-colindex="4"` could be set on every row. - - If the set of columns which is present in the DOM is **not** contiguous, or if there are cells spanning more than one row or column, put the `aria-colindex` on all of the children of each row instead of on the row itself. - - If all the columns are in the DOM, this attribute is not necessary. - -- [`aria-rowindex`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-rowindex) attribute - - - : The `aria-rowindex` attribute is only needed if rows are hidden from the DOM, to indicate which row, in the list of total rows, is being read. The attribute, placed with a unique value on each row, takes as its value an integer between 1 and the total number of rows within the table, grid or treegrid, indicating the position, or index, of each row. For example, if a table has 1,500 rows, but only the header and rows 47 and 52 are in the DOM, `aria-rowindex="1"` would be set on the header row, and `aria-rowindex="47"` and `aria-rowindex="52"` would be set on the 47th and 52nd row, respectively. - - If all the rows are present in the DOM, this attribute is not necessary. - -### Keyboard Interactions - -None - -### Required JavaScript features - -None. For sortable columns, see the [`columnheader`](/en-US/docs/Web/Accessibility/ARIA/Roles/columnheader_role) aria role. - -> [!NOTE] -> The first rule of ARIA use is you can use a native feature with the semantics and behavior you require already built in, instead of re-purposing an element and **adding** an ARIA role, state or property to make it accessible, then do so. Employ the HTML {{HTMLElement('table')}} element instead of the ARIA role of table whenever possible. - -## Examples - -```html -<div - role="table" - aria-label="Semantic Elements" - aria-describedby="semantic_elements_table_desc" - aria-rowcount="81"> - <div id="semantic_elements_table_desc"> - Semantic Elements to use instead of ARIA's roles - </div> - <div role="rowgroup"> - <div role="row"> - <span role="columnheader" aria-sort="none">ARIA Role</span> - <span role="columnheader" aria-sort="none">Semantic Element</span> - </div> - </div> - <div role="rowgroup"> - <div role="row" aria-rowindex="11"> - <span role="cell">header</span> - <span role="cell">h1</span> - </div> - <div role="row" aria-rowindex="16"> - <span role="cell">header</span> - <span role="cell">h6</span> - </div> - <div role="row" aria-rowindex="18"> - <span role="cell">rowgroup</span> - <span role="cell">thead</span> - </div> - <div role="row" aria-rowindex="24"> - <span role="cell">term</span> - <span role="cell">dt</span> - </div> - </div> -</div> -``` - -The above is a non-semantic ARIA table with five of 81 rows present in the DOM: One within a table header and four rows within the table body. The header row, alone in a header rowgroup, has two column headers. The columns are sortable, but not currently sorted, as indicated by the `aria-sort` property. The table body is in a separate rowgroup, with four rows currently in the DOM. Because not all the rows are in the DOM, we've included the `aria-rowindex` property on every row. - -## Best practices - -Only use {{HTMLElement('table')}}, {{HTMLElement('tbody')}}, {{HTMLElement('thead')}}, {{HTMLElement('tr')}}, {{HTMLElement('th')}}, {{HTMLElement('td')}}, etc., for data table structure. You can add these ARIA roles to ensure accessibility should the native semantics of the table be removed, such as with CSS. A relevant use case for the ARIA table role is when the native semantics of a table are overridden by CSS's display property, such as by display: grid. In this case, you can use the ARIA table roles to add the semantics back in. - -```html -<table - role="table" - aria-label="Semantic Elements" - aria-describedby="semantic_elements_table_desc" - aria-rowcount="81"> - <caption id="semantic_elements_table_desc"> - Semantic Elements to use instead of ARIA's roles - </caption> - <thead role="rowgroup"> - <tr role="row"> - <th role="columnheader" aria-sort="none">ARIA Role</th> - <th role="columnheader" aria-sort="none">Semantic Element</th> - </tr> - </thead> - <tbody role="rowgroup"> - <tr role="row" aria-rowindex="11"> - <td role="cell">header</td> - <td role="cell">h1</td> - </tr> - <tr role="row" aria-rowindex="16"> - <td role="cell">header</td> - <td role="cell">h6</td> - </tr> - <tr role="row" aria-rowindex="18"> - <td role="cell">rowgroup</td> - <td role="cell">thead</td> - </tr> - <tr role="row" aria-rowindex="24"> - <td role="cell">term</td> - <td role="cell">dt</td> - </tr> - </tbody> -</table> -``` - -Above is the semantic way of writing a table. The ARIA roles are only necessary if the native semantics of the table, and therefore the table rows, are obliterated, such as via setting the [display property to flex or grid](/en-US/docs/Web/CSS/display#accessibility). - -### Added benefits - -none - -## Specifications - -{{Specifications}} - -## See also - -- The HTML {{HTMLElement('tr', '<code>&lt;tr&gt;</code> table row')}} element -- {{HTMLElement('table')}} -- [The `rowgroup` role](/en-US/docs/Web/Accessibility/ARIA/Roles/rowgroup_role) -- [The `table` role](/en-US/docs/Web/Accessibility/ARIA/Roles/table_role) -- [The `grid` role](/en-US/docs/Web/Accessibility/ARIA/Roles/grid_role) -- [The `treegrid` role](/en-US/docs/Web/Accessibility/ARIA/Roles/treegrid_role) -- [The `cell` role](/en-US/docs/Web/Accessibility/ARIA/Roles/cell_role) -- [The `gridcell` role](/en-US/docs/Web/Accessibility/ARIA/Roles/gridcell_role) -- [The `columnheader` role](/en-US/docs/Web/Accessibility/ARIA/Roles/columnheader_role) -- [The `rowheader` role](/en-US/docs/Web/Accessibility/ARIA/Roles/rowheader_role) diff --git a/files/en-us/web/accessibility/aria/roles/rowgroup_role/index.md b/files/en-us/web/accessibility/aria/roles/rowgroup_role/index.md deleted file mode 100644 index b3c05098a871fd1..000000000000000 --- a/files/en-us/web/accessibility/aria/roles/rowgroup_role/index.md +++ /dev/null @@ -1,160 +0,0 @@ ---- -title: "ARIA: rowgroup role" -slug: Web/Accessibility/ARIA/Roles/rowgroup_role -page-type: aria-role -spec-urls: https://w3c.github.io/aria/#rowgroup ---- - -{{AccessibilitySidebar}} - -An element with `role="rowgroup"` is a group of [rows](/en-US/docs/Web/Accessibility/ARIA/Roles/row_role) within a tabular structure. A `rowgroup` contains one or more rows of [cells](/en-US/docs/Web/Accessibility/ARIA/Roles/cell_role), [grid cells](/en-US/docs/Web/Accessibility/ARIA/Roles/gridcell_role), [column headers](/en-US/docs/Web/Accessibility/ARIA/Roles/columnheader_role), or [row headers](/en-US/docs/Web/Accessibility/ARIA/Roles/rowheader_role) within a [`grid`](/en-US/docs/Web/Accessibility/ARIA/Roles/grid_role), [`table`](/en-US/docs/Web/Accessibility/ARIA/Roles/table_role) or [`treegrid`](/en-US/docs/Web/Accessibility/ARIA/Roles/treegrid_role). - -```html -<div - role="table" - aria-label="Populations" - aria-describedby="country_population_desc"> - <div id="country_population_desc">World Populations by Country</div> - <div role="rowgroup"> - <div role="row"> - <span role="columnheader" aria-sort="descending">Country</span> - <span role="columnheader" aria-sort="none">Population</span> - </div> - </div> - <div role="rowgroup"> - <div role="row"> - <span role="cell">Finland</span> - <span role="cell">5.5 million</span> - </div> - <div role="row"> - <span role="cell">France</span> - <span role="cell">67 million</span> - </div> - </div> -</div> -``` - -## Description - -`Rowgroup` establishes a relationship between owned row elements and is a structural equivalent to the {{HTMLElement('thead')}}, {{HTMLElement('tfoot')}} and {{HTMLElement('tbody')}} elements in HTML. There is, however, no differentiation between different types of row groups. Their elements must be contained in, or owned by, elements with either the [table](/en-US/docs/Web/Accessibility/ARIA/Roles/table_role) or [grid](/en-US/docs/Web/Accessibility/ARIA/Roles/grid_role) role. Using the native {{HTMLElement('thead')}}, {{HTMLElement('tfoot')}} and {{HTMLElement('tbody')}} HTML elements, whenever possible, is strongly encouraged. - -To create an ARIA table header, table footer or table body, add `role="rowgroup"` to the element. That rowgroup should be nested within a grid, table or treegrid, encompassing a group of one or more rows. Each row, in turn, contains child cells. These cells can be of different types, depending on whether they are column or row headers, or plain or grid cells. - -> [!NOTE] -> Using the native HTML table element ({{HTMLElement('table')}}) along with the table header ({{HTMLElement('thead')}}), footer ({{HTMLElement('tfoot')}}), and body ({{HTMLElement('tbody')}}) elements whenever possible is strongly encouraged. - -### Associated WAI-ARIA roles, states, and properties - -#### Context roles - -- [role="table"](/en-US/docs/Web/Accessibility/ARIA/Roles/table_role) - - : One of the three possible contexts (along with grid and treegrid) in which you'll find a row. It identifies the row as being part of a non-interactive table structure containing data arranged in rows and columns, similar to the native {{HTMLElement('table')}} HTML element. -- [role="grid"](/en-US/docs/Web/Accessibility/ARIA/Roles/grid_role) - - : One of the three possible contexts (along with table and treegrid) in which you'll find a row. It identifies the row as being part of a non-interactive table structure containing data arranged in rows and columns, similar to the native {{HTMLElement('table')}} HTML element. -- [role="treegrid"](/en-US/docs/Web/Accessibility/ARIA/Roles/treegrid_role) - - : Similar to a grid, but with rows that can be expanded and collapsed in the same manner as for a tree. - -#### Descendant roles - -- [role="row"](/en-US/docs/Web/Accessibility/ARIA/Roles/row_role) - - : A row of cells within a tabular structure. A row contains one or more [cells](/en-US/docs/Web/Accessibility/ARIA/Roles/cell_role), [gridcell](/en-US/docs/Web/Accessibility/ARIA/Roles/gridcell_role), or [column headers](/en-US/docs/Web/Accessibility/ARIA/Roles/columnheader_role), and sometimes a [row header](/en-US/docs/Web/Accessibility/ARIA/Roles/rowheader_role). - -### Keyboard interactions - -None - -### Required JavaScript features - -None. - -> [!NOTE] -> The first rule of ARIA use is if you can use a native feature with the semantics and behavior you require already built in, instead of re-purposing an element and **adding** an ARIA role, state or property to make it accessible, then do so. Employ the HTML `<table>` element instead of the ARIA role of table whenever possible. - -## Examples - -```html -<div - role="table" - aria-label="Semantic Elements" - aria-describedby="semantic_elements_table_desc" - aria-rowcount="81"> - <div id="semantic_elements_table_desc"> - Semantic Elements to use instead of ARIA's roles - </div> - <div role="rowgroup"> - <div role="row"> - <span role="columnheader" aria-sort="none">ARIA Role</span> - <span role="columnheader" aria-sort="none">Semantic Element</span> - </div> - </div> - <div role="rowgroup"> - <div role="row" aria-rowindex="11"> - <span role="cell">header</span> - <span role="cell">h1</span> - </div> - <div role="row" aria-rowindex="16"> - <span role="cell">header</span> - <span role="cell">h6</span> - </div> - <div role="row" aria-rowindex="18"> - <span role="cell">rowgroup</span> - <span role="cell">thead</span> - </div> - <div role="row" aria-rowindex="24"> - <span role="cell">term</span> - <span role="cell">dt</span> - </div> - </div> -</div> -``` - -The above is a non-semantic ARIA table with a table header and table body, with five of 81 rows present in the DOM: one within a table header and four rows within the table body. The header row, alone in a header rowgroup, has two column headers. The columns are sortable, but not currently sorted, as indicated by the [`aria-sort`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-sort) property. The table body is a separate rowgroup, with four rows currently in the DOM. Because not all the rows are in the DOM, we've included the [`aria-rowindex`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-rowindex) property on every row. - -## Best practices - -Only use {{HTMLElement('table')}}, {{HTMLElement('tbody')}}, {{HTMLElement('thead')}}, {{HTMLElement('tr')}}, {{HTMLElement('th')}}, {{HTMLElement('td')}}, and so on for data table structure. You can add these ARIA roles to ensure accessibility should the native semantics of the table be removed, such as with CSS. A relevant use case for the ARIA table role is when the CSS's display property overrides the native semantics of a table, such as by `display: grid`. In this case, you can use the ARIA table roles to add in the semantics. - -```html -<table - role="table" - aria-label="Semantic Elements" - aria-describedby="semantic_elements_table_desc" - aria-rowcount="81"> - <caption id="semantic_elements_table_desc"> - Semantic Elements to use instead of ARIA's roles - </caption> - <thead role="rowgroup"> - <tr role="row"> - <th role="columnheader" aria-sort="none">ARIA Role</th> - <th role="columnheader" aria-sort="none">Semantic Element</th> - </tr> - </thead> - <tbody role="rowgroup"> - <tr role="row" aria-rowindex="11"> - <td role="cell">header</td> - <td role="cell">h1</td> - </tr> - <tr role="row" aria-rowindex="16"> - <td role="cell">header</td> - <td role="cell">h6</td> - </tr> - </tbody> -</table> -``` - -Above is the semantic way of writing a table. The ARIA roles are only necessary if the native semantics of the table, and therefore the table rows, are obliterated, such as by setting the [display property to flex or grid](/en-US/docs/Web/CSS/display#accessibility). - -### Added benefits - -none - -## Specifications - -{{Specifications}} - -## See also - -- [HTML table](/en-US/docs/Web/HTML/Element/table) -- [HTML table body](/en-US/docs/Web/HTML/Element/tbody) -- [HTML table footer](/en-US/docs/Web/HTML/Element/tfoot) -- [HTML table header](/en-US/docs/Web/HTML/Element/thead) diff --git a/files/en-us/web/accessibility/aria/roles/rowheader_role/index.md b/files/en-us/web/accessibility/aria/roles/rowheader_role/index.md deleted file mode 100644 index c638e974e10e28b..000000000000000 --- a/files/en-us/web/accessibility/aria/roles/rowheader_role/index.md +++ /dev/null @@ -1,155 +0,0 @@ ---- -title: "ARIA: rowheader role" -slug: Web/Accessibility/ARIA/Roles/rowheader_role -page-type: aria-role -spec-urls: https://w3c.github.io/aria/#rowheader ---- - -{{AccessibilitySidebar}} - -An element with `role="rowheader"` is a [cell](/en-US/docs/Web/Accessibility/ARIA/Roles/cell_role) containing header information for a [row](/en-US/docs/Web/Accessibility/ARIA/Roles/row_role) within a tabular structure of a [`grid`](/en-US/docs/Web/Accessibility/ARIA/Roles/grid_role), [`table`](/en-US/docs/Web/Accessibility/ARIA/Roles/table_role) or [`treegrid`](/en-US/docs/Web/Accessibility/ARIA/Roles/treegrid_role). - -## Description - -`Rowheader` is the header [`cell`](/en-US/docs/Web/Accessibility/ARIA/Roles/cell_role) for a row, establishing a relationship between it and the other cells in the same [`row`](/en-US/docs/Web/Accessibility/ARIA/Roles/row_role). - -```html -<div - role="table" - aria-label="Populations" - aria-describedby="country_population_desc"> - <div id="country_population_desc">World Populations by Country</div> - <div role="rowgroup"> - <div role="row"> - <span role="columnheader" aria-sort="descending">Country</span> - <span role="columnheader" aria-sort="none">Population</span> - </div> - </div> - <div role="rowgroup"> - <div role="row"> - <span role="rowheader">Finland</span> - <span role="cell">5.5 million</span> - </div> - <div role="row"> - <span role="rowheader">France</span> - <span role="cell">67 million</span> - </div> - </div> -</div> -``` - -It is a structural equivalent to the {{HTMLElement('th')}} element with a scope of `row`, `<th scope="row">`. Using the native {{HTMLElement('th')}} HTML element is strongly encouraged. - -To create an ARIA row header, add `role="rowheader"` to the element. That row header must be nested within a `row`, which, in turn, is nested within a `rowgroup`, or directly within a `grid`, `table` or `treegrid`. - -> [!NOTE] -> Using the native [table elements](/en-US/docs/Learn_web_development/Core/Structuring_content/HTML_table_basics) whenever possible, is strongly encouraged. - -### Associated WAI-ARIA roles, states, and properties - -#### Context roles - -- [role="row"](/en-US/docs/Web/Accessibility/ARIA/Roles/row_role) - - : The only context in which you will find a row. It encompasses a cell or group of cells row, of which only one should be of rowheader type. Similar to the native {{HTMLElement('tr')}} HTML element. - -### Keyboard interactions - -None - -### Required JavaScript features - -None. - -> [!NOTE] -> The first rule of ARIA use is if you can use a native feature with the semantics and behavior you require already built in, instead of re-purposing an element and **adding** an ARIA role, state or property to make it accessible, then do so. Employ the HTML `<table>`, `<tr>`, `<th>`, `<td>`, and other [table elements](/en-US/docs/Learn_web_development/Core/Structuring_content/HTML_table_basics) instead of the ARIA table roles whenever possible. - -## Examples - -```html -<div - role="table" - aria-label="Semantic Elements" - aria-describedby="semantic_elements_table_desc" - aria-rowcount="81"> - <div id="semantic_elements_table_desc"> - Semantic Elements to use instead of ARIA's roles - </div> - <div role="rowgroup"> - <div role="row"> - <span role="columnheader" aria-sort="none">ARIA Role</span> - <span role="columnheader" aria-sort="none">Semantic Element</span> - </div> - </div> - <div role="rowgroup"> - <div role="row" aria-rowindex="11"> - <span role="rowheader">header</span> - <span role="cell">h1</span> - </div> - <div role="row" aria-rowindex="16"> - <span role="rowheader">header</span> - <span role="cell">h6</span> - </div> - <div role="row" aria-rowindex="18"> - <span role="rowheader">rowgroup</span> - <span role="cell">thead</span> - </div> - <div role="row" aria-rowindex="24"> - <span role="rowheader">term</span> - <span role="cell">dt</span> - </div> - </div> -</div> -``` - -The above is a non-semantic ARIA table with a table header and table body, with five of 81 rows present in the DOM: one within a table header and four rows within the table body. The header row, alone in a header rowgroup, has two column headers. The columns are sortable, but not currently sorted, as indicated by the [`aria-sort`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-sort) property. The table body is a separate rowgroup, with four rows currently in the DOM. Each data table row has a row header. Because not all the rows are in the DOM, we've included the [`aria-rowindex`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-rowindex) property on every row. - -## Best practices - -Only use {{HTMLElement('table')}}, {{HTMLElement('tbody')}}, {{HTMLElement('thead')}}, {{HTMLElement('tr')}}, {{HTMLElement('th')}}, {{HTMLElement('td')}}, and so on for data table structure. You can add these ARIA roles to ensure accessibility should the native semantics of the table be removed, such as with CSS. A relevant use case for all the ARIA table roles is when the CSS's `display` property overrides the native semantics of a table, such as by `display: grid`. In this case, you can use the ARIA table roles to add in the semantics. - -```html -<table - role="table" - aria-label="Semantic Elements" - aria-describedby="semantic_elements_table_desc" - aria-rowcount="81"> - <caption id="semantic_elements_table_desc"> - Semantic Elements to use instead of ARIA's roles - </caption> - <thead role="rowgroup"> - <tr role="row"> - <th role="columnheader" aria-sort="none">ARIA Role</th> - <th role="columnheader" aria-sort="none">Semantic Element</th> - </tr> - </thead> - <tbody role="rowgroup"> - <tr role="row" aria-rowindex="11"> - <th role="rowheader">header</th> - <td role="cell">h1</td> - </tr> - <tr role="row" aria-rowindex="16"> - <th role="rowheader">header</th> - <td role="cell">h6</td> - </tr> - </tbody> -</table> -``` - -Above is the semantic way of writing a table. The ARIA roles are only necessary if the native semantics of the table, and therefore the table row headers, are obliterated, such as by setting the [display property to flex or grid](/en-US/docs/Web/CSS/display#accessibility). - -### Added benefits - -none - -## Specifications - -{{Specifications}} - -## See also - -- [The HTML `<table>` element](/en-US/docs/Web/HTML/Element/table) -- [The HTML `<th>` element](/en-US/docs/Web/HTML/Element/th) -- [HTML table tutorial](/en-US/docs/Learn_web_development/Core/Structuring_content/HTML_table_basics/Basics) -- [ARIA `cell` role](/en-US/docs/Web/Accessibility/ARIA/Roles/cell_role) -- [ARIA `row` role](/en-US/docs/Web/Accessibility/ARIA/Roles/row_role) -- [ARIA `gridcell` role](/en-US/docs/Web/Accessibility/ARIA/Roles/gridcell_role) diff --git a/files/en-us/web/accessibility/aria/roles/scrollbar_role/index.md b/files/en-us/web/accessibility/aria/roles/scrollbar_role/index.md deleted file mode 100644 index 47858c38163a244..000000000000000 --- a/files/en-us/web/accessibility/aria/roles/scrollbar_role/index.md +++ /dev/null @@ -1,172 +0,0 @@ ---- -title: "ARIA: scrollbar role" -slug: Web/Accessibility/ARIA/Roles/scrollbar_role -page-type: aria-role -spec-urls: https://w3c.github.io/aria/#scrollbar ---- - -{{AccessibilitySidebar}} - -A `scrollbar` is a graphical object that controls the scrolling of content within a viewing area. - -## Description - -A `scrollbar` is a range that controls what part of a viewport's content is currently visible in the viewport's frame; whether the viewport is a full browser size, an iframe, or any element's [block formatting context](/en-US/docs/Web/CSS/CSS_display/Block_formatting_context). - -### What is scroll bar - -Many applications provide native scroll bars when the content area is larger than the application window. Scrollbars generally appear on the right or bottom of the viewing area. Native scroll bars appear as thin rectangular track areas the length of the viewport it controls with a piece of UI called a thumb or scroller that can be dragged along a track to move the associated content within the viewport. Some scrollbars have arrows at each end of the track that allow scrolling the viewport a short set distance when activated. - -Take this document as an example: if the viewport is the full browser window and the content is taller than the viewport, in most browsers the scroll bar on the right edge of the window represents the overall length of the page and the scroll thumb represents the portion of the page content that is currently in the viewport. - -Scroll bars may also appear on viewports that are sub-sections of the full browser window. Continuing with this content as our example, if this content is embedded in an {{HTMLElement('iframe')}} or {{HTMLElement('object')}}, the native vertical scroll bar will be the height of the frame. A scroll bar generally is the length of the viewport, but isn't required to be. - -If you aren't currently seeing a scroll bar, it may be because your browser only displays the scroll bar when scrolling or only when an element's content is too big to fit in its block formatting context. Depending on the browser and operating system, scroll bars can be made to be visible even when the content fits in the viewport when no scrolling is necessary or even possible. - -### ARIA `scrollbar` - -It is always best to use native scroll bars. You can use the CSS {{CSSXref('overflow')}} property to ensure the appearance of native scroll bars. A [CSS scrollbar specification](https://drafts.csswg.org/css-scrollbars/) is being developed. Some browsers allow [styling scroll bars via prefixed pseudo-elements](/en-US/docs/Web/CSS/::-webkit-scrollbar). - -Because native scroll bar styling has historically been limited, you may come across a scrollbar implemented in JavaScript that you need to support and make fully accessible. For this, you can use the `scrollbar` role to inform assistive technologies that a UI control is an interactive scrollbar. - -An element with the `scrollbar` role is a graphical object that controls the scrolling of content within a viewing area; it is the ARIA role which indicates an element is a scroll bar. The HTML element that is most similar is the `range` {{HTMLElement('input')}} type, [`<input type="range">`](/en-US/docs/Web/HTML/Element/input/range). - -The `scrollbar` element has two required attributes: [`aria-controls`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-controls) and [`aria-valuenow`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-valuenow). The `aria-controls` attribute references the [`id`](/en-US/docs/Web/HTML/Global_attributes/id) of the scrollable area it controls. The `aria-valuenow` property defines the current value of the scrollbar. - -While the `aria-valuenow` is always required, the [`aria-valuemin`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-valuemin) and [`aria-valuemax`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-valuemax) properties only need to be set for the scrollbar role when the `scrollbar`'s minimum value is not 0 or the maximum value is not 100. The value of `aria-valuenow` must always be between the minimum and maximum inclusive values, or between `0` and `100` inclusive if the minimum and maximum values default to `0` and `100` respectively. `aria-valuenow` communicates how close the viewport is to the bottom of the document. Think of it like a progress bar, where the start of the document is the minimum value and the end of the document is the maximum value. - -A `scrollbar` represents the current value and range of possible values via the size of the scrollbar and position of the thumb with respect to the visible range of the orientation (horizontal or vertical) it controls. In other words, the `scrollbar` length (height or width) represents all the content within a viewport. The `aria-valuemin` value represents the beginning of the content and the scrollbar, the `aria-valuemax` value represents the end of the content and the end of the scrollbar. The `aria-valuenow` represents the content that is currently visible in the viewport and the current position, or value, of the movable thumb. The `aria-valuenow` value will generally be exposed as a percentage between `aria-valuemin` and `aria-valuemax` calculated by assistive technologies. - -> [!NOTE] -> Assistive technologies generally render the value of `aria-valuenow` as a percent of a range between the value of `aria-valuemin` and `aria-valuemax`, unless [`aria-valuetext`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-valuetext) is set. It is recommended to set the values for `aria-valuemin`, `aria-valuemax`, and `aria-valuenow` in a manner that is appropriate for this calculation. - -Like a native scroll bar, users interact with `scrollbar` elements directly or indirectly using mouse, touchpad, keyboard, and voice input. `scrollbar` role implementations must also accommodate all these interaction methods. - -When using a mouse, the user must be able to activate the `scrollbar` by clicking the scroll arrows at either end of the scroll bar, if present, clicking an empty portion of the scroll track, as well as clicking and dragging the scroll thumb. - -Keyboard scrolling must also be supported. When focus is within the viewport controlled by a `scrollbar`, the <kbd>Up Arrow</kbd> and <kbd>Down Arrow</kbd> (or <kbd>Left Arrow</kbd> and <kbd>Right Arrow</kbd> for a horizontal scroll bar) should move the scroll bar thumb proportionally. Additionally, the <kbd>Page Up</kbd>, <kbd>Page Down</kbd>, <kbd>Space</kbd>, and <kbd>Shift + Space</kbd> keys must move the content and the scroll thumb the height (or width) of the viewport for each key press until the bottom or top (or left or right) of the content is in view. - -JavaScript must be used to translate the `scrollbar` action into scrolling commands, providing the user with feedback by: - -1. Visually updating the `scrollbar` element, -2. Scrolling the viewport's content, and -3. Updating the [`aria-valuenow`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-valuenow) property value. - -The default orientation of the `scrollbar` role is vertical. Including [`aria-orientation="vertical"`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-orientation), in this case, is optional. The orientation represents the orientation of the scrollbar and the scrolling effect on the viewing area controlled by the scrollbar. If the scrolling is left to right or right to left and not top to bottom, include `aria-orientation="horizontal"` on the element with the `scrollbar` role. - -> [!NOTE] -> An accessible name is **required**. If the `scrollbar` role is applied to an HTML {{HTMLElement('input')}} element (or `<meter>` or `<progress>` element), the accessible name can come from the associated {{HTMLElement('label')}}. Otherwise use [`aria-labelledby`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-labelledby) if a visible label is present or [`aria-label`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-label) if a visible label is not present. - -### All descendants are presentational - -There are some types of user interface components that, when represented in a platform accessibility API, can only contain text. Accessibility APIs do not have a way of representing semantic elements contained in a `scrollbar`. To deal with this limitation, browsers, automatically apply role [`presentation`](/en-US/docs/Web/Accessibility/ARIA/Roles/presentation_role) to all descendant elements of any `scrollbar` element as it is a role that does not support semantic children. - -For example, consider the following `scrollbar` element, which contains a heading. - -```html -<div role="scrollbar"><h3>Title of my scrollbar</h3></div> -``` - -Because descendants of `scrollbar` are presentational, the following code is equivalent: - -```html -<div role="scrollbar"><h3 role="presentation">Title of my scrollbar</h3></div> -``` - -From the assistive technology user's perspective, the heading does not exist since the previous code snippets are equivalent to the following in the [accessibility tree](/en-US/docs/Glossary/Accessibility_tree): - -```html -<div role="scrollbar">Title of my scrollbar</div> -``` - -### Associated WAI-ARIA roles, states, and properties - -- [`aria-controls`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-controls) (Required) - - : Identifies the viewport, via the `id`, whose contents controlled by the scrollbar. -- [`aria-valuenow`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-valuenow) (Required) - - : Set to a decimal value between `0`, or `aria-valuemin` if present, and `aria-valuemax` indicating the current value of the scrollbar. -- [`aria-valuetext`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-valuetext) - - : Assistive technologies often present the value of `aria-valuenow` as a percentage. If this would not be helpful, use this property to make the scrollbar value more understandable to users. -- [`aria-valuemin`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-valuemin) - - : Set to a decimal value representing the minimum value, and less than `aria-valuemax`. If not present, the default value is `0`. -- [`aria-valuemax`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-valuemax) - - : Set to a decimal value representing the maximum value, and greater than `aria-valuemin`. If not present, the default value is `100`. -- [`aria-labelledby`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-labelledby) - - : When not using a native form control and therefore not able to associate the scrollbar with a {{HTMLElement('label')}}, if visible text is available that can provide the required accessible name, set to the [`id`](/en-US/docs/Web/HTML/Global_attributes/id) of an element containing text serving as a label. Otherwise, use `aria-label`. -- [`aria-label`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-label) - - : If no {{htmlelement('label')}} can be used, and no visible text is present that can be referenced by `aria-labelledby`, provides the string value that labels the `scrollbar` element providing the required accessible name. -- [`aria-orientation`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-orientation) - - : By default, the orientation is `vertical`. The property can be included and set to `horizontal`, `undefined` (the default for all roles unless otherwise specified), or `vertical`. - -### Keyboard interactions - -- <kbd>Up Arrow</kbd> - - : The content in the viewport moves up one line with the thumb moving up the scroll bar slider proportionally, until the top of the content and scrollbar are reached. -- <kbd>Down Arrow</kbd> - - : The content in the viewport moves down one line with the thumb moving down the scroll bar slider proportionally, until the bottom of the content and scrollbar are reached. -- <kbd>Left Arrow</kbd> - - : With horizontal scrolling, the content in the viewport moves left the width of one character with the thumb moving left across the scroll bar slider proportionally, until the left edge of the content abuts the left end of the viewport and the thumb is aligned on the left end of the scrollbar. -- <kbd>Right Arrow</kbd> - - : With horizontal scrolling, the content in the viewport moves right the width of one character with the thumb moving right across the scroll bar slider proportionally, until the right edge of the content abuts the right end of the viewport and the thumb is aligned on the right end of the scrollbar. -- <kbd>Page Up</kbd> and <kbd>Shift + Space</kbd> - - : The content in the viewport moves up the height of one viewport with the thumb moving up the scroll bar slider proportionally, until the top of the content and scrollbar are reached. -- <kbd>Page Down</kbd> and <kbd>Space</kbd> - - : The content in the viewport moves down the height of one viewport with the thumb moving down the scroll bar slider proportionally, until the bottom of the content and scrollbar are reached.the bottom or top of the content is in view. - -## Examples - -The following is an example of a word likely being too long for a parent container. - -```html -<span id="pi-label">Pi</div> -<div id="pi"> -3.1415926535897932384626433832795028841971693993751058209749445923078164062862089986280348253421170679 -</div> -<div - role="scrollbar" - aria-labelledby="pi-label" - aria-controls="pi" - aria-orientation="horizontal" - aria-valuenow="0" - aria-valuemin="0" - aria-valuemax="100"> - <div id="thumb"></div> -</div> -``` - -When using the ARIA roles instead of native UI features, CSS must be used to style the scrollbar and thumb and JavaScript must be used to handle all keyboard and pointer events. - -CSS could have been used to ensure the overflowing value of PI had a native scrollbar: - -```html -<h3 id="PI">Pi</h3> -<p class="pi" tabindex="0" aria-labelledby="PI"> - 3.1415926535897932384626433832795028841971693993751058209749445923078164062862089986280348253421170679 -</p> -``` - -```css -.pi { - overflow: auto; - max-width: 100%; -} -``` - -The above CSS means a native scroll bar will appear when the user interacts with the paragraph's viewport if the length of the longest word in the paragraph is wider than the paragraphs containing box. The `tabindex` attribute was added to allow people using a keyboard to navigate to, and scroll around the overflowed content. - -## Specifications - -{{Specifications}} - -## See also - -- [`<input type="range">`](/en-US/docs/Web/HTML/Element/input/range), -- HTML {{HTMLElement('progress')}} element -- HTML {{HTMLElement('meter')}} element -- Other range widgets include: - - [`meter`](/en-US/docs/Web/Accessibility/ARIA/Roles/meter_role) - - [`slider`](/en-US/docs/Web/Accessibility/ARIA/Roles/slider_role) - - [`separator`](/en-US/docs/Web/Accessibility/ARIA/Roles/separator_role) (if focusable) - - [`progressbar`](/en-US/docs/Web/Accessibility/ARIA/Roles/progressbar_role) - - [`spinbutton`](/en-US/docs/Web/Accessibility/ARIA/Roles/spinbutton_role) -- [Document `scroll` event](/en-US/docs/Web/API/Document/scroll_event) diff --git a/files/en-us/web/accessibility/aria/roles/search_role/index.md b/files/en-us/web/accessibility/aria/roles/search_role/index.md deleted file mode 100644 index c4c2910f645adb9..000000000000000 --- a/files/en-us/web/accessibility/aria/roles/search_role/index.md +++ /dev/null @@ -1,98 +0,0 @@ ---- -title: "ARIA: search role" -slug: Web/Accessibility/ARIA/Roles/search_role -page-type: aria-role -spec-urls: - - https://w3c.github.io/aria/#search - - https://www.w3.org/WAI/ARIA/apg/patterns/landmarks/examples/search.html ---- - -{{AccessibilitySidebar}} - -The `search` role is used to identify the search functionality; the section of the page used to search the page, site, or collection of sites. - -```html -<form role="search"> - <!-- search input --> -</form> -``` - -## Description - -The `search` role is [a landmark](/en-US/docs/Web/Accessibility/ARIA/Roles#3._landmark_roles) role that can be added to the container element that encompasses all of the elements that combined to form the search feature of the document or application, including a descendant [(`<input type="search">`)](/en-US/docs/Web/HTML/Element/input/search). If a document includes more than one search, each should have a unique label, unless they are the same search repeated, then use the same name. There is a [`input` of type `search`)](/en-US/docs/Web/HTML/Element/input/search), though this does not define a search landmark by itself. Using {{HTMLElement('search')}} is an alternative way to define a search landmark. - -## Examples - -When a {{HTMLElement('form')}} is a search form, use the `search` role instead of [`form`](/en-US/docs/Web/Accessibility/ARIA/Roles/form_role) role. - -```html -<form id="search" role="search"> - <label for="search-input">Search this site</label> - <input type="search" id="search-input" name="search" spellcheck="false" /> - <input value="Submit" type="submit" /> -</form> -``` - -## Accessibility concerns - -[Landmark roles](/en-US/docs/Web/Accessibility/ARIA/Roles#3._landmark_roles) are intended to be used sparingly, to identify larger overall sections of the document. Using too many landmark roles can create "noise" in screen readers, making it difficult to understand the overall layout of the page. - -## Best practices - -### Prefer HTML - -Using the {{HTMLElement('form')}} element in conjunction with a declaration of `role="search"` will provide the largest amount of support. - -### Labeling landmarks - -#### Multiple landmarks - -If there is more than one `search` landmark role in a document, provide a label for each landmark. This label will allow an assistive technology user to be able to quickly understand the purpose of each landmark. - -```html -<form id="site-search" role="search" aria-label="Sitewide"> - <!-- search input --> -</form> - -… - -<form id="page-search" role="search" aria-label="On this page"> - <!-- search input --> -</form> -``` - -#### Repeated landmarks - -If a `search` landmark role in a document is repeated in a document, and both landmarks have identical content, use the same label for each landmark. An example of this would be repeating the sitewide search at the top and bottom of the page. - -```html -<header> - <form id="site-search-top" role="search" aria-label="Sitewide"> - <!-- search input --> - </form> -</header> - -… - -<footer> - <form id="site-search-bottom" role="search" aria-label="Sitewide"> - <!-- search input --> - </form> -</footer> -``` - -#### Redundant descriptions - -Screen readers will announce the type of role the landmark is. Because of this, you do not need to describe what the landmark is in its label. For example, a declaration of `role="search"` with an [`aria-label="Sitewide search"`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-label) may be announced redundantly as, "sitewide search search". - -## Specifications - -{{Specifications}} - -## See also - -- The {{HTMLElement('form')}} element -- The {{HTMLElement('input')}} element -- The {{HTMLElement('search')}} element -- [`<input type="search">`](/en-US/docs/Web/HTML/Element/input/search) -- [Using HTML sections and outlines](/en-US/docs/Web/HTML/Element/Heading_Elements) diff --git a/files/en-us/web/accessibility/aria/roles/searchbox_role/index.md b/files/en-us/web/accessibility/aria/roles/searchbox_role/index.md deleted file mode 100644 index 061005f0e79e71a..000000000000000 --- a/files/en-us/web/accessibility/aria/roles/searchbox_role/index.md +++ /dev/null @@ -1,70 +0,0 @@ ---- -title: "ARIA: searchbox role" -slug: Web/Accessibility/ARIA/Roles/searchbox_role -page-type: aria-role -spec-urls: https://w3c.github.io/aria/#searchbox ---- - -{{AccessibilitySidebar}} - -The `searchbox` role indicates an element is a type of `textbox` intended for specifying search criteria. - -## Description - -The `searchbox` can be used instead of [`textbox`](/en-US/docs/Web/Accessibility/ARIA/Roles/textbox_role) when the text box is within an element with role [`search`](/en-US/docs/Web/Accessibility/ARIA/Roles/search_role). A `searchbox` is the semantic equivalent is HTML's {{HTMLElement('input')}} of type `search`, [`<input type="search">`](/en-US/docs/Web/HTML/Element/input/search), which should be used instead if possible. - -The `searchbox` must have an accessible name. If the `searchbox` role is applied to an HTML {{HTMLElement('input')}} element, an associated {{HTMLElement('label')}} should be used. -Otherwise, use [`aria-labelledby`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-labelledby) if a visible label is present, or [`aria-label`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-label) if a visible label is not present. - -The screen reader will announce "search box", "search edit", or "search field" plus the accessible name. This can be redundant if "search" is included in the label. - -## Examples - -```html -<div tabindex="0" aria-label="search" role="searchbox" contenteditable></div> -``` - -While the above is valid, it is simpler, more concise, and less redundant to the screen reader user to write: - -```html -<input type="search" /> -``` - -The following is a search form with a searchbox and button, ARIA live region, and container for search results. - -```html -<form role="search"> - <input - type="search" - role="searchbox" - aria-description="search results will appear below" - id="search" - value="" /> - <label for="search">Search this site</label> - <button>Submit search</button> -</form> -<div aria-live="polite" role="region" aria-atomic="true"> - <div class="sr-only"></div> -</div> -<div id="search-results"></div> -``` - -Including `role="searchbox"` when the form is a `search` and the label indicates the element is a search may result in assistive technology announcing something along the lines of "search search this site search box", which is redundant. The inclusion of `role="searchbox"` is not necessary: - -```html -<input - type="search" - aria-description="search results will appear below" - id="search" - value="" /> -``` - -## Specifications - -{{Specifications}} - -## See also - -- [`<input type="search">`](/en-US/docs/Web/HTML/Element/input/search) -- [ARIA: `search` role](/en-US/docs/Web/Accessibility/ARIA/Roles/search_role) -- [ARIA: `textbox` role](/en-US/docs/Web/Accessibility/ARIA/Roles/textbox_role) diff --git a/files/en-us/web/accessibility/aria/roles/section_role/index.md b/files/en-us/web/accessibility/aria/roles/section_role/index.md deleted file mode 100644 index d89c5ecc1ad7afc..000000000000000 --- a/files/en-us/web/accessibility/aria/roles/section_role/index.md +++ /dev/null @@ -1,64 +0,0 @@ ---- -title: "ARIA: section role" -slug: Web/Accessibility/ARIA/Roles/section_role -page-type: aria-role -spec-urls: https://w3c.github.io/aria/#section ---- - -{{AccessibilitySidebar}} - -The **`section` role**, an abstract role, is a superclass role for renderable structural containment components. - -> [!NOTE] -> The `section` role is an [abstract role](/en-US/docs/Web/Accessibility/ARIA/Roles#6._abstract_roles). It is included here for completeness of documentation. It **should not be used** by web authors. - -## Description - -The structural `section` role is an abstract role for categorizing all the section subclass roles. The role must not be used. Some subclasses, like [`alert`](/en-US/docs/Web/Accessibility/ARIA/Roles/alert_role), -[`note`](/en-US/docs/Web/Accessibility/ARIA/Roles/note_role), and [`tooltip`](/en-US/docs/Web/Accessibility/ARIA/Roles/tooltip_role) are useful, and can be used to add semantics when no semantic HTML elements quite fit the purpose of a component. Others, like [`code`](/en-US/docs/Web/Accessibility/ARIA/Roles/structural_roles), [`figure`](/en-US/docs/Web/Accessibility/ARIA/Roles/figure_role), and [`subscript`](/en-US/docs/Web/Accessibility/ARIA/Roles/structural_roles), aren't necessary, as there are HTML element equivalents. In this case, {{HTMLElement('code')}} {{HTMLElement('figure')}} and {{HTMLElement('sub')}}, respectively. - -## Best Practices - -Do not use. - -## Specifications - -{{Specifications}} - -## See also - -- [ARIA: `structure` role](/en-US/docs/Web/Accessibility/ARIA/Roles/structure_role) -- [ARIA: `alert` role](/en-US/docs/Web/Accessibility/ARIA/Roles/alert_role) -- [ARIA: `associationlist` role](/en-US/docs/Web/Accessibility/ARIA/Roles/structural_roles) -- [ARIA: `associationlistitemkey` role](/en-US/docs/Web/Accessibility/ARIA/Roles/structural_roles) -- [ARIA: `associationlistitemvalue` role](/en-US/docs/Web/Accessibility/ARIA/Roles/structural_roles) -- [ARIA: `blockquote` role](/en-US/docs/Web/Accessibility/ARIA/Roles/structural_roles) -- [ARIA: `caption` role](/en-US/docs/Web/Accessibility/ARIA/Roles/structural_roles) -- [ARIA: `cell` role](/en-US/docs/Web/Accessibility/ARIA/Roles/cell_role) -- [ARIA: `code` role](/en-US/docs/Web/Accessibility/ARIA/Roles/structural_roles) -- [ARIA: `definition` role](/en-US/docs/Web/Accessibility/ARIA/Roles/definition_role) -- [ARIA: `deletion` role](/en-US/docs/Web/Accessibility/ARIA/Roles/structural_roles) -- [ARIA: `emphasis` role](/en-US/docs/Web/Accessibility/ARIA/Roles/structural_roles) -- [ARIA: `figure` role](/en-US/docs/Web/Accessibility/ARIA/Roles/figure_role) -- [ARIA: `group` role](/en-US/docs/Web/Accessibility/ARIA/Roles/group_role) -- [ARIA: `img` role](/en-US/docs/Web/Accessibility/ARIA/Roles/img_role) -- [ARIA: `insertion` role](/en-US/docs/Web/Accessibility/ARIA/Roles/structural_roles) -- [ARIA: `landmark` role](/en-US/docs/Web/Accessibility/ARIA/Roles/landmark_role) -- [ARIA: `list` role](/en-US/docs/Web/Accessibility/ARIA/Roles/list_role) -- [ARIA: `listitem` role](/en-US/docs/Web/Accessibility/ARIA/Roles/listitem_role) -- [ARIA: `log` role](/en-US/docs/Web/Accessibility/ARIA/Roles/log_role) -- [ARIA: `mark` role](/en-US/docs/Web/Accessibility/ARIA/Roles/mark_role) -- [ARIA: `marquee` role](/en-US/docs/Web/Accessibility/ARIA/Roles/marquee_role) -- [ARIA: `math` role](/en-US/docs/Web/Accessibility/ARIA/Roles/math_role) -- [ARIA: `note` role](/en-US/docs/Web/Accessibility/ARIA/Roles/note_role) -- [ARIA: `paragraph` role](/en-US/docs/Web/Accessibility/ARIA/Roles/structural_roles) -- [ARIA: `status` role](/en-US/docs/Web/Accessibility/ARIA/Roles/status_role) -- [ARIA: `strong` role](/en-US/docs/Web/Accessibility/ARIA/Roles/structural_roles) -- [ARIA: `subscript` role](/en-US/docs/Web/Accessibility/ARIA/Roles/structural_roles) -- [ARIA: `suggestion` role](/en-US/docs/Web/Accessibility/ARIA/Roles/suggestion_role) -- [ARIA: `superscript` role](/en-US/docs/Web/Accessibility/ARIA/Roles/structural_roles) -- [ARIA: `table` role](/en-US/docs/Web/Accessibility/ARIA/Roles/table_role) -- [ARIA: `tabpanel` role](/en-US/docs/Web/Accessibility/ARIA/Roles/tabpanel_role) -- [ARIA: `term` role](/en-US/docs/Web/Accessibility/ARIA/Roles/term_role) -- [ARIA: `time` role](/en-US/docs/Web/Accessibility/ARIA/Roles/structural_roles) -- [ARIA: `tooltip` role](/en-US/docs/Web/Accessibility/ARIA/Roles/tooltip_role) diff --git a/files/en-us/web/accessibility/aria/roles/sectionhead_role/index.md b/files/en-us/web/accessibility/aria/roles/sectionhead_role/index.md deleted file mode 100644 index c1d7324d1d06859..000000000000000 --- a/files/en-us/web/accessibility/aria/roles/sectionhead_role/index.md +++ /dev/null @@ -1,33 +0,0 @@ ---- -title: "ARIA: sectionhead role" -slug: Web/Accessibility/ARIA/Roles/sectionhead_role -page-type: aria-role -spec-urls: https://w3c.github.io/aria/#sectionhead ---- - -{{AccessibilitySidebar}} - -The **`sectionhead` role**, an abstract role, is superclass role for labels or summaries of the topic of its related section. - -> [!NOTE] -> The `sectionhead` role is an [abstract role](/en-US/docs/Web/Accessibility/ARIA/Roles#6._abstract_roles). It is included here for completeness of documentation. It should not be used by web authors. - -## Description - -The structural `sectionhead` role is an abstract role for the subclass roles that identify the labels or summaries of the sections they label. The role must not be used. The four subclasses — [`columnheader`](/en-US/docs/Web/Accessibility/ARIA/Roles/columnheader_role), [`heading`](/en-US/docs/Web/Accessibility/ARIA/Roles/heading_role), [`rowheader`](/en-US/docs/Web/Accessibility/ARIA/Roles/rowheader_role), and [`tab`](/en-US/docs/Web/Accessibility/ARIA/Roles/tab_role). There are HTML element equivalents, like, {{HTMLElement('th', '<code>&lt;th scope="col"&gt;</code>')}} for `columnheader`, {{HTMLElement('th', '<code>&lt;th scope="row"&gt;</code>')}} for rowheader, and any of the HTML headings, {{HTMLElement("Heading_Elements", "h1")}} through {{HTMLElement("Heading_Elements", "h6")}} for `heading`. The `tab` role does not currently have an HTML equivalent. - -## Best Practices - -Do not use. - -## Specifications - -{{Specifications}} - -## See also - -- [ARIA: `structure` role](/en-US/docs/Web/Accessibility/ARIA/Roles/structure_role) -- [ARIA: `columnheader` role](/en-US/docs/Web/Accessibility/ARIA/Roles/columnheader_role) -- [ARIA: `heading` role](/en-US/docs/Web/Accessibility/ARIA/Roles/heading_role) -- [ARIA: `rowheader` role](/en-US/docs/Web/Accessibility/ARIA/Roles/rowheader_role) -- [ARIA: `tab` role](/en-US/docs/Web/Accessibility/ARIA/Roles/tab_role) diff --git a/files/en-us/web/accessibility/aria/roles/select_role/index.md b/files/en-us/web/accessibility/aria/roles/select_role/index.md deleted file mode 100644 index 6fe24edc63eb3f1..000000000000000 --- a/files/en-us/web/accessibility/aria/roles/select_role/index.md +++ /dev/null @@ -1,34 +0,0 @@ ---- -title: "ARIA: select role" -slug: Web/Accessibility/ARIA/Roles/select_role -page-type: aria-role -spec-urls: https://w3c.github.io/aria/#select ---- - -{{AccessibilitySidebar}} - -The **`select` role**, an abstract role, is superclass role for form widgets that allows the user to make selections from a set of choices. - -> [!NOTE] -> The `select` role is an [abstract role](/en-US/docs/Web/Accessibility/ARIA/Roles#6._abstract_roles). It is included here for completeness of documentation. It **should not be used** by web authors. - -## Description - -The structural `select` role, an abstract role, is superclass role for four form widgets, [`listbox`](/en-US/docs/Web/Accessibility/ARIA/Roles/listbox_role), [`menu`](/en-US/docs/Web/Accessibility/ARIA/Roles/menu_role), [`radiogroup`](/en-US/docs/Web/Accessibility/ARIA/Roles/radiogroup_role), and [`tree`](/en-US/docs/Web/Accessibility/ARIA/Roles/tree_role), which allow users to make selections from a set of choices. - -## Best Practices - -Do not use. - -## Specifications - -{{Specifications}} - -## See also - -- [ARIA: `composite` role](/en-US/docs/Web/Accessibility/ARIA/Roles/composite_role) -- [ARIA: `group` role](/en-US/docs/Web/Accessibility/ARIA/Roles/group_role) -- [ARIA: `listbox` role](/en-US/docs/Web/Accessibility/ARIA/Roles/listbox_role) -- [ARIA: `menu` role](/en-US/docs/Web/Accessibility/ARIA/Roles/menu_role) -- [ARIA: `radiogroup` role](/en-US/docs/Web/Accessibility/ARIA/Roles/radiogroup_role) -- [ARIA: `tree` role](/en-US/docs/Web/Accessibility/ARIA/Roles/tree_role) diff --git a/files/en-us/web/accessibility/aria/roles/separator_role/index.md b/files/en-us/web/accessibility/aria/roles/separator_role/index.md deleted file mode 100644 index 8c0e516e0b10375..000000000000000 --- a/files/en-us/web/accessibility/aria/roles/separator_role/index.md +++ /dev/null @@ -1,128 +0,0 @@ ---- -title: "ARIA: separator role" -slug: Web/Accessibility/ARIA/Roles/separator_role -page-type: aria-role -spec-urls: - - https://w3c.github.io/aria/#separator - - https://www.w3.org/WAI/ARIA/apg/patterns/menubar/examples/menubar-editor/ ---- - -{{AccessibilitySidebar}} - -The `separator` role indicates the element is a divider that separates and distinguishes sections of content or groups of menuitems. The implicit ARIA role the native thematic break {{HTMLElement('hr')}} element is `separator`. - -## Description - -A separator is a divider that separates and distinguishes sections of content or groups of menuitems. There are two types of separators: a static structure that provides a visible boundary, identical to the HTML {{HTMLElement('hr')}} element, and a focusable, moveable widget. - -Elements with the role `separator` have an implicit [`aria-orientation`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-orientation) value of `horizontal`. - -### Non-focusable separator - -A non-focusable separator is a static structural element that can be used to help visually divide two groups of menu items in a menu or to provide a horizontal rule between two sections of a page. Thematic breaks that aren't focusable can still be perceivable by a screen reader user when using a reading cursor that does not depend on focus. - -```html -<h2>My first blog post</h2> -… -<img src="blueline.gif" role="separator" alt="" /> -<h2>Two years later, my second post</h2> -… -``` - -In the example, an image creates a visual separator between two blog posts. The author could have used a semantic thematic break {{HTMLElement('hr')}} element and styled it with CSS to make it blue (and not have to change the image when they change the blog's theme), or the author could have encompassed each post in the semantic {{HTMLElement('article')}} element, or both. - -```html -<section role="feed"> - <article> - <h2>My first blog post</h2> - … - </article> - <hr /> - <article> - <h2>Two years later, my second post</h2> - … - </article> -</section> -``` - -```css -[role="feed"] > hr { - height: 3px; - background-color: blue; -} -``` - -An accessible name is not needed. - -### Focusable separator - -The separator role can be used to identify the element as a visual separator between groups of items within a menu, such as groups of `menuitemradio` or `menuitemcheckbox` elements. - -If the separator is focusable, providing a visible boundary between two sections of content and enabling the user to change the relative size of the sections it separates by changing its position, the value of [`aria-valuenow`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-valuenow) must be set to a number reflecting the current position of the separator and the value must be updated when it changes. The [`aria-valuemin`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-valuemin) and [`aria-valuemax`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-valuemax) should also be included if they aren't set to the default values of 0 and 100, respectively. - -An accessible name, with [`aria-label`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-label) should be included if there is more than one focusable separator. - -### All descendants are presentational - -There are some types of user interface components that, when represented in a platform accessibility API, can only contain text. Accessibility APIs do not have a way of representing semantic elements contained in a `separator`. To deal with this limitation, browsers, automatically apply role [`presentation`](/en-US/docs/Web/Accessibility/ARIA/Roles/presentation_role) to all descendant elements of any `separator` element as it is a role that does not support semantic children. - -For example, consider the following `separator` element, which contains a heading. - -```html -<div role="separator"><h3>Title of my separator</h3></div> -``` - -Because descendants of `separator` are presentational, the following code is equivalent: - -```html -<div role="separator"><h3 role="presentation">Title of my separator</h3></div> -``` - -From the assistive technology user's perspective, the heading does not exist since the previous code snippets are equivalent to the following in the [accessibility tree](/en-US/docs/Glossary/Accessibility_tree): - -```html -<div role="separator">Title of my separator</div> -``` - -### Associated WAI-ARIA roles, states, and properties - -- [`aria-orientation`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-orientation) (default is horizontal for separator) - - - : By default, the divider for `separator` roles is assumed to be horizontal. The value can be included and set to horizontal, undefined (the default for other roles unless otherwise specified), or vertical. - -- [`aria-valuenow`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-valuenow) - - - : If the separator is focusable and has a known value, the `aria-valuenow` defines the current value. If not focusable or the value is unknown, do not include this attribute. - -- [`aria-valuemin`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-valuemin) (default is 0) - - - : If the separator is focusable, and the minimum value is not 0, include the minimum value with `aria-valuemin`. If the - -- [`aria-valuemax`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-valuemax) (default is 100) - - - : If the separator is focusable, and the maximum value is not 100, include `aria-valuemax` with a value equal to or larger than `aria-valuemin`. - -- [`aria-valuetext`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-valuetext) - - : If the separator is focusable, and the `aria-valuenow` is not optimal in providing the user with usable information, included `aria-valuetext` content will be read instead of the `aria-valuenow` value. - -<!-- -### Keyboard interactions - -### Required JavaScript features - -## Examples - -## Accessibility concerns - -## Best Practices - -### Prefer HTML --> - -## Specifications - -{{Specifications}} - -## See also - -- Thematic break HTML {{HTMLElement('hr')}} element -- [Example separator in a menubar](https://www.w3.org/WAI/ARIA/apg/patterns/menubar/examples/menubar-editor/) diff --git a/files/en-us/web/accessibility/aria/roles/slider_role/index.md b/files/en-us/web/accessibility/aria/roles/slider_role/index.md deleted file mode 100644 index 091b00a2acd3891..000000000000000 --- a/files/en-us/web/accessibility/aria/roles/slider_role/index.md +++ /dev/null @@ -1,217 +0,0 @@ ---- -title: "ARIA: slider role" -slug: Web/Accessibility/ARIA/Roles/slider_role -page-type: aria-role -spec-urls: https://w3c.github.io/aria/#slider ---- - -{{AccessibilitySidebar}} - -The `slider` role defines an input where the user selects a value from within a given range. - -## Description - -The `slider` role is for range input widgets where the user selects a value from within given minimum and maximum values. - -### The `slider` role compared other range options - -ARIA provides developers with six different range [widget roles](/en-US/docs/Web/Accessibility/ARIA/Roles#2._widget_roles), including `progressbar`, `meter`, and `slider`. - -The [`progressbar`](/en-US/docs/Web/Accessibility/ARIA/Roles/progressbar_role) role, similar to HTML's {{HTMLElement('progress')}} element, is a read-only range indicating the portion of completion of a task, progressing in a single direction, such as a file upload's loading progress bar that eventually reaches 100% when fully loaded. - -The [`meter`](/en-US/docs/Web/Accessibility/ARIA/Roles/meter_role) role, similar to HTML's {{HTMLElement('meter')}} element, is a read-only gauge indicating the amount of something within a known range, such as a computer's battery indicator or a car's gas gauge. - -The `slider` role, similar to HTML's `input` of type `range`, [`<input type="range">`](/en-US/docs/Web/HTML/Element/input/range), is a read-write input range. Sliders allow users to select a value between set minimum and maximum values. The user selects a value by moving a slider thumb along a horizontal or vertical slider to select a value. - -While all three of these ranges have the same ARIA states and properties, the `slider` role is the only read-write range: it is the only one whose value changes via user interaction. As such, it must be able to receive focus. In addition, keyboard interaction, mouse clicks, and touch interaction must be supported. - -> [!WARNING] -> To change the slider value, touch-based assistive technologies need to respond to user gestures for increasing and decreasing the value by synthesizing key events. -> Fully test slider widgets using assistive technologies on devices where touch is a primary input mechanism before using the `slider` role (and all range widgets). - -#### Common attributes - -The [`aria-valuemin`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-valuemin) attribute sets the minimum value. If omitted or not a number, it defaults to `0` (zero). - -The [`aria-valuemax`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-valuemax) attribute defines the maximum value. If it is missing or not a number, it defaults to 100. - -The [`aria-valuenow`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-valuenow) attribute value must be between the minimum and maximum values, inclusive. This attribute is required for `slider` and `meter`, and optional for `progressbar`. - -For `slider`, unless using the [`<input type="range">`](/en-US/docs/Web/HTML/Element/input/range) element, the `aria-valuenow` value must be updated programmatically when the user updates the value. - -The optional [`aria-valuetext`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-valuetext) attribute is included when the `aria-valuenow` numeric value doesn't reflect the intended value of the slider. As the minimum, maximum, and current values are all numeric, when the values those numbers represent are not numeric, the `aria-valuetext` attribute should be included with a string value defining the numeric value. For example, if using a slider for t-shirt sizes, the `aria-valuetext` attribute should shift from xx-small through to XX-large as the `aria-valuenow` increases. - -The `aria-valuetext` value must be updated as the `value` or `aria-valuenow` is updated. While there is no equivalent HTML attribute for `<input type="range">`, you can include `aria-valuetext` on any {{htmlelement('input')}} type. ARIA attributes are supported on semantic HTML elements. - -When `aria-valuetext` is an important feature for a slider, consider using {{HTMLElement('select')}} with {{HTMLElement('option')}} elements instead. While not visually a range, every option's value is more accessible to all users, not just users of assistive technology. - -An accessible name is **required**. If the range's role is applied to an HTML {{HTMLElement('input')}} element (or `<meter>` or `<progress>` element), the accessible name can come from the associated {{HTMLElement('label')}}. Otherwise use [`aria-labelledby`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-labelledby) if a visible label is present or [`aria-label`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-label) if a visible label is not present. - -When not using the HTML {{HTMLElement('input')}} element to create your slider, include the [`tabindex`](/en-US/docs/Web/HTML/Global_attributes/tabindex) attribute to make the slider focusable. Of the three range types, only `slider` is user-interactive, and so is the only one that requires being able to receive focus. Focus should be placed on the slider thumb. - -Sliders have an implicit [`aria-orientation`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-orientation) value of `horizontal`. This attribute is not supported with `meter` or `progressbar`. - -### User interactions - -Unlike the read-only `meter` and `progressbar` roles, a `slider` is an input, accepting user interaction. In addition to including the [`tabindex`](/en-US/docs/Web/HTML/Global_attributes/tabindex) attribute to enable slider focus, keyboard and pointer device support must be implemented. - -The slider represents the range of possible values. The position of the slider thumb along the slider represents the current value. User actions that must be supported include changing the value by dragging the thumb or clicking the slider for pointing devices and using directional keys such as arrow keys for the keyboard users. See [keyboard interactions](#keyboard_interactions) below. - -> [!NOTE] -> It is recommended to use native [`<input type="range">`](/en-US/docs/Web/HTML/Element/input/range) elements rather than the `slider` role. User agents provide a stylized widget for the range input element, based on the current `value` as it relates to the minimum and maximum values. When using non-semantic elements, all features of the native semantic element need to be recreated with ARIA attributes, JavaScript and CSS. - -### Range with multiple thumbs - -A multi-thumb slider is a slider with two or more thumbs that each set a value in a group of related values. For example, in a product search, a two-thumb slider could be used to enable users to set the minimum and maximum price limits for the search. - -In many two-thumb sliders, the thumbs are not allowed to pass one another, such as when the slider sets the minimum and maximum values for a range. For example, in a price-range selector, the maximum value of the thumb that sets the lower end of the range is limited by the current value of the thumb that sets the upper end of the range. The minimum value of the upper-end thumb is also limited by the current value of the lower-end thumb. - -It is not a requirement that the thumbs in multi-thumb sliders be dependent on the other thumb values, but intuitive user experience is a requirement, so it is recommended to avoid this anti-pattern. - -### All descendants are presentational - -There are some types of user interface components that, when represented in a platform accessibility API, can only contain text. Accessibility APIs do not have a way of representing semantic elements contained in a `slider`. To deal with this limitation, browsers, automatically apply role [`presentation`](/en-US/docs/Web/Accessibility/ARIA/Roles/presentation_role) to all descendant elements of any `slider` element as it is a role that does not support semantic children. - -For example, consider the following `slider` element, which contains a heading. - -```html -<div role="slider"><h3>Temperature in Celsius</h3></div> -``` - -Because descendants of `slider` are presentational, the following code is equivalent: - -```html -<div role="slider"><h3 role="presentation">Temperature in Celsius</h3></div> -``` - -From the assistive technology user's perspective, the heading does not exist since the previous code snippets are equivalent to the following in the [accessibility tree](/en-US/docs/Glossary/Accessibility_tree): - -```html -<div role="slider">Temperature in Celsius</div> -``` - -## Associated roles, states, and properties - -- [`aria-valuenow`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-valuenow) (required) - - : Set to a decimal value between `aria-valuemin` and `aria-valuemax`, indicating the current value of the slider. -- [`aria-valuetext`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-valuetext) - - : Assistive technologies often present the value of `aria-valuenow` as a number. If this would not be accurate, use `aria-valuetext` to provide the slider with a more understandable value. -- [`aria-valuemin`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-valuemin) - - : Set to a decimal value representing the minimum value, and less than `aria-valuemax`. If not present, the default value is 0. -- [`aria-valuemax`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-valuemax) - - : Set to a decimal value representing the maximum value, and greater than `aria-valuemin`. If not present, the default value is 100. -- [`aria-label`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-label) or [`aria-labelledby`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-labelledby) - - : Defines the string value or identifies the element (or elements) that label the slider element providing an accessible name. An accessible name is required. -- [`aria-orientation`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-orientation) - - : Indicates whether the element's orientation is horizontal, vertical, or unknown/ambiguous. With a slider, the implicit value is `horizontal` but can be set to `vertical`. As it has an implicit value, the slider orientation is never ambiguous. - -## Examples - -In the example below, we create a vertical thermometer with which the user can set the room temperature: - -```html -<div> - <div id="temperatureLabel">Temperature</div> - <div id="temperatureValue">20°C</div> - <div id="temperatureSlider"> - <div - id="temperatureSliderThumb" - role="slider" - aria-labelledby="temperatureLabel" - aria-orientation="vertical" - tabindex="0" - aria-valuemin="15.0" - aria-valuemax="25.0" - aria-valuenow="20.0" - aria-valuetext="20 degrees Celsius" - style="top: calc((25 - 20)*2rem - 0.5rem)"></div> - </div> -</div> -``` - -The position of the thumb is the maximum value minus the current value times the height of one degree, minus half the height of the thumb to center it. The rest of the styles are static. - -```css -[id="temperatureSlider"] { - position: relative; - height: 20rem; - width: 1rem; - outline: 1px solid; - margin: 3rem; -} - -[id="temperatureSliderThumb"] { - position: absolute; - height: 1rem; - width: 2rem; - background-color: currentcolor; - left: -0.5rem; -} -``` - -For this example to work, we have to write a script to handle all keyboard and pointer events, including event listeners for `pointermove`, `pointerup`, `focus`, `blur`, and `keydown`, and provide styles for the default state and when the thumb and slider receive focus. The position of the thumb, the `aria-valuenow` and `aria-valuetext` values, and the inner text of the element with the [`id`](/en-US/docs/Web/HTML/Global_attributes/id) "temperatureValue" need to be updated every time <kbd>ArrowLeft</kbd>, <kbd>ArrowDown</kbd>, <kbd>ArrowRight</kbd>, <kbd>ArrowUp</kbd>, <kbd>Home</kbd>, <kbd>End</kbd>, and, optionally, <kbd>PageDown</kbd> and <kbd>PageUp</kbd> keys are released and when the user drags the thumb or otherwise clicks on the temperature slider. - -Using semantic HTML, this could have been written as: - -```html -<label for="temperature"> Temperature </label> -<output id="temperatureValue">20°C</output> -<input - type="range" - id="temperatureSlider" - min="15" - max="25" - step="0.1" - value="20" - aria-valuetext="20 degrees celsius" - style="transform: rotate(-90deg);" /> -``` - -By using {{HTMLElement('input')}}, we get an already-styled range-input widget with keyboard focus, focus styling, keyboard interactions, and `value` updated on user interaction for free. We still need to use JavaScript to change the `aria-valuetext` and the value of the {{HTMLElement('output')}} element. - -There are a few ways to make a range input vertical. In this example, we used [CSS transforms](/en-US/docs/Web/CSS/transform). - -## Keyboard interactions - -| Key(s) | Action | -| -------------------- | ------------------------------------------------------------------- | -| Right and Up arrows | Increase the selected value by one step | -| Left and Down arrows | Decrease the selected value by one step | -| Page Up | (Optional) increase the value by a set amount greater than one step | -| Page Down | (Optional) decrease the value by a set amount greater than one step | -| Home | Set the slider to the minimum value. | -| End | Set the slider to the maximum value. | - -For the optional <kbd>Page Up</kbd> and <kbd>Page Down</kbd> keys, the change in slider value should be by an amount larger than the step changes made by up and down arrows. - -## Best practices - -If the slider is describing the loading progress of a particular region of a page, include the [`aria-describedby`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-describedby) attribute to reference the slider status, and set the [`aria-busy`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-busy) attribute to `true` on the region until it is finished loading. - -HTML's `<input type="range">` implicitly has the `role` of `slider`. Do not use `aria-valuemax` or `aria-valuemin` attributes on `<input type="range">` elements; use `min` and `max` instead. Otherwise, any global `aria-*` attributes and any other `aria-*` attributes applicable to the slider role. - -### Prefer HTML - -It is recommended to use a native {{HTMLElement("input")}} of type `range`, [`<input type="range">`](/en-US/docs/Web/HTML/Element/input/range), rather than the `slider` role. - -## Specifications - -{{Specifications}} - -## See also - -- [`<input type="range">`](/en-US/docs/Web/HTML/Element/input/range), -- HTML {{HTMLElement('progress')}} element -- HTML {{HTMLElement('meter')}} element -- Other range widgets include: - - [`meter`](/en-US/docs/Web/Accessibility/ARIA/Roles/meter_role) - - [`scrollbar`](/en-US/docs/Web/Accessibility/ARIA/Roles/scrollbar_role) - - [`separator`](/en-US/docs/Web/Accessibility/ARIA/Roles/separator_role) (if focusable) - - [`progressbar`](/en-US/docs/Web/Accessibility/ARIA/Roles/progressbar_role) - - [`spinbutton`](/en-US/docs/Web/Accessibility/ARIA/Roles/spinbutton_role) -- W3C WAI-ARIA practices examples: - - [Horizontal Multi-Thumb Slider](https://www.w3.org/WAI/ARIA/apg/patterns/slider-multithumb/examples/slider-multithumb/) - - [Color Viewer Slider](https://www.w3.org/WAI/ARIA/apg/patterns/slider/examples/slider-color-viewer/) - - [Rating Slider](https://www.w3.org/WAI/ARIA/apg/patterns/slider/examples/slider-rating/) - - [Media Seek Slider](https://www.w3.org/WAI/ARIA/apg/patterns/slider/examples/slider-seek/) - - [Vertical Temperature Slider](https://www.w3.org/WAI/ARIA/apg/patterns/slider/examples/slider-temperature/) diff --git a/files/en-us/web/accessibility/aria/roles/spinbutton_role/index.md b/files/en-us/web/accessibility/aria/roles/spinbutton_role/index.md deleted file mode 100644 index 30448ace10d622d..000000000000000 --- a/files/en-us/web/accessibility/aria/roles/spinbutton_role/index.md +++ /dev/null @@ -1,165 +0,0 @@ ---- -title: "ARIA: spinbutton role" -slug: Web/Accessibility/ARIA/Roles/spinbutton_role -page-type: aria-role -spec-urls: https://w3c.github.io/aria/#spinbutton ---- - -{{AccessibilitySidebar}} - -The `spinbutton` role defines a type of range that expects the user to select a value from among discrete choices. - -## Description - -The `spinbutton` role indicates that the element is an input widget that restricts its value to a set or range of discrete values. The role also comes with increment and decrement functionality. For example, in a widget that enables users to choose an amount to bet in a game of Texas Holdem, the `spinbutton` role can allow users to select a number between the minimum and maximum bets in increments, as allowed by the current game rules. - -The spinbutton represents the range of possible values. The value of the spinbutton input represents the current value. - -Spinbuttons often have three components, including a text field that displays the current value, an increment button, and a decrement button. The text field is usually the only focusable component because the increment and decrement functions are keyboard accessible via arrow keys. Typically, the text field also allows users to directly edit the value. - -In addition to including the [`tabindex`](/en-US/docs/Web/HTML/Global_attributes/tabindex) attribute to enable spinbutton focus, keyboard and pointer device support must be implemented. Directional keys such as the arrow keys must be supported for keyboard users. Changing the value when increment and decrement buttons are clicked must be supported for pointing devices. See [keyboard interactions](#keyboard_interactions) below. - -> [!NOTE] -> It is recommended to use [`<input type="number">`](/en-US/docs/Web/HTML/Element/input/number) element, or other input types for dates and time that also implicitly have the `role="spinbutton"` semantic, rather than the `spinbutton` role. User agents provide stylized widget for the these input elements which provide default increment, decrement, and native range limiting functionality. When using non-semantic elements, all features of the native semantic element need to be recreated with ARIA attributes, JavaScript, and CSS. - -### ARIA range widget options - -ARIA provides developers with six different range [widget roles](/en-US/docs/Web/Accessibility/ARIA/Roles#2._widget_roles), including `progressbar`, `meter`, `slider`, and `spinbutton`. - -The [`progressbar`](/en-US/docs/Web/Accessibility/ARIA/Roles/progressbar_role) role, similar to HTML's {{HTMLElement('progress')}} element, is a read-only range. It indicates the portion of completion of a task, progressing in a single direction, such as a file upload's loading progress bar that eventually reaches 100% when fully loaded. - -The [`meter`](/en-US/docs/Web/Accessibility/ARIA/Roles/meter_role) role, similar to HTML's {{HTMLElement('meter')}} element, is a read-only gauge. It indicates the amount of something within a known range, such as a computer's battery indicator or a car's gas gauge. - -The `slider` role, similar to HTML's `input` of type `range`, [`<input type="range">`](/en-US/docs/Web/HTML/Element/input/range), is a read-write input range. Sliders allow users to select a value between the predefined minimum and maximum values. The user selects a value by moving a slider thumb along a horizontal or vertical slider to select a value. - -While all three of these ranges have the same ARIA states and properties, the `spinbutton` role is the only read-write range: it is the only one whose value changes via user interaction. As such, it must be able to receive focus. In addition, keyboard interaction, mouse clicks, and touch interaction must be supported. - -> [!WARNING] -> To change the spinbutton value, touch-based assistive technologies need to respond to user gestures for increasing and decreasing the value by synthesizing key events. -> Fully test spinbutton widgets using assistive technologies on devices where touch is a primary input mechanism before using the `spinbutton` role (and all range widgets). - -#### Common attributes - -The [`aria-valuemin`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-valuemin) attribute sets the minimum value. If omitted or not a number, it defaults to `0` (zero). - -The [`aria-valuemax`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-valuemax) attribute defines the maximum value. If it is missing or not a number, it defaults to `100`. - -The [`aria-valuenow`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-valuenow) attribute value must be between the minimum and maximum values, both inclusive. This attribute is required for `spinbutton` and `meter`, and optional for `progressbar`. - -For `spinbutton`, unless using semantic HTML elements like [`<input type="number">`](/en-US/docs/Web/HTML/Element/input/number), if the value is updated, the `aria-valuenow` value must also be updated programmatically. - -The optional [`aria-valuetext`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-valuetext) attribute is included when the `aria-valuenow` numeric value doesn't reflect the intended value of the spinbutton. The optional minimum, maximum, and current values should be numeric. When the values these numbers represent are not numeric, the `aria-valuetext` attribute should be included with a string value defining the numeric value. For example, if using a spinbutton for t-shirt sizes, the `aria-valuetext` attribute should shift from `XX-Small` through `XX-Large` as the `aria-valuenow` increases. - -The `aria-valuetext` value must be updated as the value or `aria-valuenow` is updated. ARIA attributes are supported on semantic HTML elements. While there is no equivalent HTML attribute for `<input>`, you can include `aria-valuetext` on any {{htmlelement('input')}} type. When `aria-valuetext` is an important feature for a spinbutton, consider using {{HTMLElement('select')}} with {{HTMLElement('option')}} elements instead. - -An accessible name is **required**. If the `spinbutton` role is applied to an HTML {{HTMLElement('input')}} element, the accessible name can come from the associated {{HTMLElement('label')}}. Otherwise, use [`aria-labelledby`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-labelledby) if a visible label is present or [`aria-label`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-label) if a visible label is not present. - -When not using the HTML {{HTMLElement('input')}} element to create your spinbutton, include the [`tabindex`](/en-US/docs/Web/HTML/Global_attributes/tabindex) attribute to make the spinbutton focusable. The `spinbutton` role is user-interactive, and therefore, requires being able to receive focus. Focus should be placed on the spinbutton input and not on the associated buttons that increment and decrement the spinbutton value. - -### Descendants limited to buttons or text - -There are some types of user interface components that, when represented in a platform accessibility API, can only contain specific content. The children or owned elements of `spinbutton` are limited to a textbox and two buttons. Alternatively, the `spinbutton` role can be applied to a `text` input and sibling buttons can be used to support the increment and decrement functions. - -## Associated roles, states, and properties - -- [`aria-valuenow`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-valuenow) (required) - - - : Set to a decimal value between `aria-valuemin` and `aria-valuemax`, indicating the current value of the spinbutton. If not present, there is no default value. - -- [`aria-valuetext`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-valuetext) - - - : Assistive technologies often present the value of `aria-valuenow` as a number. If `aria-valuenow` cannot be accurate, use `aria-valuetext` to provide the spinbutton with a more understandable value. - -- [`aria-valuemin`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-valuemin) - - - : Set to a decimal value representing the minimum value and less than `aria-valuemax`. If not present, there is no default value. - -- [`aria-valuemax`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-valuemax) - - - : Set to a decimal value representing the maximum value and greater than `aria-valuemin`. If not present, there is no default value. - -- [`aria-labelledby`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-labelledby) - - : Defines the string value or identifies the element (or elements) that label the spinbutton element providing an accessible name. An accessible name is required. -- [`aria-label`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-label) - - : Defines a string value that labels the spinbutton element. This provides an accessible name to the element when no visible label is available to provide the required accessible name via {{HTMLElement('label')}} or `aria-labelledby`. - -## Examples - -In the example below, a `spinbutton` role has been defined to allow users to select a day of the month. - -```html -<p id="day">Enter the day of the month</p> -<button type="button" tabindex="-1" aria-label="previous day">˱</button> -<div - role="spinbutton" - tabindex="0" - aria-valuenow="1" - aria-valuetext="first" - aria-valuemin="1" - aria-valuemax="31" - aria-labelledby="day"> - 1 -</div> -<button type="button" tabindex="-1" aria-label="next day">˲</button> -``` - -In this example, we included a negative `tabindex` to remove the buttons from the default tabbing order. We also added `tabindex` to a normally non-interactive {{HTMLElement('div')}} to add the `spinbutton` itself to the tabbing order. This example requires JavaScript to handle keyboard actions when the spinbutton has focus and when a mouse user clicks on the buttons. - -### With semantic HTML - -This could have also been written using semantic HTML, removing the need for any CSS or JavaScript and also removing the need to include and provide functionality for extraneous incrementing and decrementing buttons. The code snippet below shows the previous example without the `spinbutton` role and using semantic HTML. - -```html -<label for="day">Enter the day of the month</label> -<input - type="number" - value="1" - aria-valuetext="first" - min="1" - max="31" - id="day" /> -``` - -{{EmbedLiveSample("With_semantic_HTML", 50, 50)}} - -In this case, the only JavaScript needed would be to update the `aria-valuetext` when the input value changes, which really is an optional feature in this case. - -## Keyboard interactions - -| Key(s) | Action | -| -------------------- | ------------------------------------------------------------------------------- | -| Right and Up arrows | Increase the selected value by one step | -| Left and Down arrows | Decrease the selected value by one step | -| Page Up | (Optional) Increase the value by a set amount greater than or equal to one step | -| Page Down | (Optional) Decrease the value by a set amount greater than or equal to one step | -| Home | Set the spinbutton to the minimum value | -| End | Set the spinbutton to the maximum value | - -For the optional <kbd>Page Up</kbd> and <kbd>Page Down</kbd> keys, the change in spinbutton value should preferably be by an amount larger than the step changes made by Up and Down arrow keys. - -## Best practices - -HTML's `<input type="number">` implicitly has the `role` of `spinbutton`. HTML's `<input type="date">` has 3 nested spin buttons, one each for month, day, and year. When using semantic HTML form elements for their intended purposes, do not use `aria-valuemax` or `aria-valuemin` attributes; use `min` and `max` instead. Otherwise, any global `aria-*` attributes and any other `aria-*` attributes are applicable to the `spinbutton` role. - -### Prefer semantic HTML - -It is recommended to use the native {{HTMLElement("input")}} element of type `number`, [`<input type="number">`](/en-US/docs/Web/HTML/Element/input/number), rather than the `spinbutton` role. - -## Specifications - -{{Specifications}} - -## See also - -- [`<input type="number">`](/en-US/docs/Web/HTML/Element/input/number) -- [`<input type="date">`](/en-US/docs/Web/HTML/Element/input/date) -- [`<input type="time">`](/en-US/docs/Web/HTML/Element/input/time) -- Other range widgets include: - - [`meter`](/en-US/docs/Web/Accessibility/ARIA/Roles/meter_role) - - [`scrollbar`](/en-US/docs/Web/Accessibility/ARIA/Roles/scrollbar_role) - - [`separator`](/en-US/docs/Web/Accessibility/ARIA/Roles/separator_role) (if focusable) - - [`progressbar`](/en-US/docs/Web/Accessibility/ARIA/Roles/progressbar_role) - - [`slider`](/en-US/docs/Web/Accessibility/ARIA/Roles/slider_role) -- Working examples: - - [Date picker spin button example](https://www.w3.org/WAI/ARIA/apg/patterns/spinbutton/examples/datepicker-spinbuttons/) - - [Toolbar example: font-size picker](https://www.w3.org/WAI/ARIA/apg/patterns/toolbar/examples/toolbar/) diff --git a/files/en-us/web/accessibility/aria/roles/status_role/index.md b/files/en-us/web/accessibility/aria/roles/status_role/index.md deleted file mode 100644 index 6e1e82aab200d1c..000000000000000 --- a/files/en-us/web/accessibility/aria/roles/status_role/index.md +++ /dev/null @@ -1,44 +0,0 @@ ---- -title: "ARIA: status role" -slug: Web/Accessibility/ARIA/Roles/status_role -page-type: aria-role -spec-urls: https://w3c.github.io/aria/#status ---- - -{{AccessibilitySidebar}} - -The `status` role defines a [live region](/en-US/docs/Web/Accessibility/ARIA/ARIA_Live_Regions) containing advisory information for the user that is not important enough to be an [`alert`](/en-US/docs/Web/Accessibility/ARIA/Roles/alert_role). - -## Description - -A `status` is a type of [live region](/en-US/docs/Web/Accessibility/ARIA/ARIA_Live_Regions) providing advisory information that is not important enough to justify an alert, which would immediately interrupt the announcement of a user's current activity. It is often, but not necessarily, presented as a status bar. - -Do not give focus to the status when its content updates. Live regions are meant to inform users of dynamic updates that have occurred in other areas of the current web page, but which do not necessitate interrupting the user's current activity with a change in context. If a situation requires that focus needs to be moved, then using a `status`, or other live region, are likely not appropriate. - -Elements with the role status have an implicit [`aria-live`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-live) value of `polite` and an implicit [`aria-atomic`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-atomic) value of `true`. - -### Associated WAI-ARIA roles, states, and properties - -- [`aria-atomic`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-atomic) - - - : Defines whether assistive technologies should present all, or only parts of, the changed region. Elements with the role `status` have an implicit [aria-atomic](https://www.w3.org/TR/wai-aria-1.1/#aria-atomic) value of `true`. - -- [`aria-live`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-live) - - - : Defines when assistive technology should inform the user of updates to content. Elements with the role `status` have an implicit [aria-live](https://www.w3.org/TR/wai-aria-1.1/#aria-live) value of `polite`, meaning screen readers will announce changes inside the log when the user is idle. - -- [`aria-label`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-label) or [`aria-labelledby`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-labelledby) - - - : Some screen readers announce the name of a status element before announcing its contents. If a name is visible, reference it using `aria-labelledby`. Including an `aria-label` provides a method for prefacing the visible content of a status element with text that is not displayed when a screen reader reads the content. Naming a status is not required so if nothing is appropriate both these attributes can be omitted. - -## Specifications - -{{Specifications}} - -## See also - -- [ARIA: `alert` role](/en-US/docs/Web/Accessibility/ARIA/Roles/alert_role) -- [ARIA: `log` role](/en-US/docs/Web/Accessibility/ARIA/Roles/log_role) -- [ARIA: `marquee` role](/en-US/docs/Web/Accessibility/ARIA/Roles/marquee_role) -- [ARIA: `timer` role](/en-US/docs/Web/Accessibility/ARIA/Roles/timer_role) -- [ARIA live regions](/en-US/docs/Web/Accessibility/ARIA/ARIA_Live_Regions) diff --git a/files/en-us/web/accessibility/aria/roles/structural_roles/index.md b/files/en-us/web/accessibility/aria/roles/structural_roles/index.md deleted file mode 100644 index bc1fc5491586f86..000000000000000 --- a/files/en-us/web/accessibility/aria/roles/structural_roles/index.md +++ /dev/null @@ -1,62 +0,0 @@ ---- -title: "ARIA: document structural roles" -slug: Web/Accessibility/ARIA/Roles/structural_roles -page-type: aria-role -spec-urls: https://w3c.github.io/aria/#document_structure_roles ---- - -{{AccessibilitySidebar}} - -ARIA document-structure roles are used to provide a structural description for a section of content. - -Structural ARIA roles were originally created as a bridge to inform assistive technologies of HTML5 elements that were not yet fully supported in browsers. Some roles, like `presentation`, `toolbar` and `tooltip`, provide information on the document structure to assistive technologies in cases where equivalent native HTML elements don't exist. Other roles, including those listed in the table below, are not needed, as there are semantic HTML elements with the same meanings. In many cases, these equivalent HTML elements have always been supported. - -> [!NOTE] -> These structural roles all have semantic HTML equivalents. They are included here for completeness of documentation. Preferably, they should not be used by web authors. - -Some structural roles, like [`suggestion`](/en-US/docs/Web/Accessibility/ARIA/Roles/suggestion_role), don't have HTML equivalents, and therefore have separate documentation. Some structural roles with HTML equivalents, like [`heading`](/en-US/docs/Web/Accessibility/ARIA/Roles/heading_role), have ARIA-attribute requirements. They are listed below with links to their individual role documentation. - -Most of the following roles were never needed but were added to ARIA for completeness. We've included them here for completeness as well. - -## Structural roles with HTML equivalents - -The structure roles with HTML equivalents are listed below: - -| ARIA role & description | HTML Equivalent | -| ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| **`associationlist`** <br> Contains only `associationlistitemkey` children and their sibling `associationlistitemvalue`. | {{HTMLElement('dl')}} | -| **`associationlistitemkey`** <br/> Must be contained in an `associationlist`. | {{HTMLElement('dt')}} | -| **`associationlistitemvalue`** <br/> Always a sibling following an `associationlistitemkey`. | {{HTMLElement('dd')}} | -| **`blockquote`** <br/> A section of content that is quoted from another source. | {{HTMLElement('blockquote')}} | -| **`caption`** <br>Visible content that names, and may also describe, a `figure`, `table`, `grid`, or `treegrid`.<br/> Only found in those 4 roles. A caption's `id` is generally referenced by a `figure`, `grid`, `table`, or `treegrid`'s `aria-labelledby` attribute.<br/> Prohibited attributes: `aria-label` and `aria-labelledby`. | {{HTMLElement('caption')}} <br/> {{HTMLElement('figcaption')}} | -| **`code`** <br/> A section representing a fragment of computer code. <br/> Prohibited attributes: `aria-label` and `aria-labelledby`. | {{HTMLElement('code')}} | -| **`deletion`** <br/>Content that is marked as removed or suggested for removal.<br/> Prohibited attributes: `aria-label` and `aria-labelledby`. | {{HTMLElement('del')}} | -| **`emphasis`** <br/> Used to stress or emphasize content, but not to suggest importance.<br/>Prohibited attributes: `aria-label` and `aria-labelledby`. | {{HTMLElement('em')}} | -| [`figure`](/en-US/docs/Web/Accessibility/ARIA/Roles/figure_role) <br/>Container for a graphical document, images, code snippets, or example text. | {{HTMLElement('figure')}} | -| [`heading`](/en-US/docs/Web/Accessibility/ARIA/Roles/heading_role) <br/> A heading for a section of the page.<br/>The `aria-level` attribute is required to indicate the nesting level.<br/>See the [`heading` role](/en-US/docs/Web/Accessibility/ARIA/Roles/heading_role) for more information. | {{HTMLElement("Heading_Elements", "h1")}}, {{HTMLElement("Heading_Elements", "h2")}}, {{HTMLElement("Heading_Elements", "h3")}}, {{HTMLElement("Heading_Elements", "h4")}}, {{HTMLElement("Heading_Elements", "h5")}}, and {{HTMLElement("Heading_Elements", "h6")}} | -| **`image`** <br/>Container for a collection of elements that form an image. Synonym for `img` role. | {{HTMLElement('img')}} | -| [`img`](/en-US/docs/Web/Accessibility/ARIA/Roles/img_role) <br/>Container for a collection of elements that form an image. <br/>Accessible name is required. <br/>See the [`img` role](/en-US/docs/Web/Accessibility/ARIA/Roles/img_role) for more information. | {{HTMLElement('img')}} | -| **`insertion`** <br/>Content that is marked as added or content that is being suggested for addition.<br/> Prohibited attributes: `aria-label` and `aria-labelledby`. | {{HTMLElement('ins')}} | -| [`list`](/en-US/docs/Web/Accessibility/ARIA/Roles/list_role)<br/>A section containing `listitem` elements.<br/> See [`list` role](/en-US/docs/Web/Accessibility/ARIA/Roles/list_role) for more information | {{HTMLElement('ol')}}<br/>{{HTMLElement('ul')}} | -| [`listitem`](/en-US/docs/Web/Accessibility/ARIA/Roles/listitem_role)<br/>A single item in a `list` or `directory`.<br/>Must be contained in a `list` (like `<li>`).<br>See [`listitem` role](/en-US/docs/Web/Accessibility/ARIA/Roles/listitem_role) for more information. | {{HTMLElement('li')}} | -| [`mark`](/en-US/docs/Web/Accessibility/ARIA/Roles/mark_role)<br/>Marked or highlighted for reference or notation purposes.<br>See [`mark` role](/en-US/docs/Web/Accessibility/ARIA/Roles/mark_role) for more information. | {{HTMLElement('mark')}} | -| [`meter`](/en-US/docs/Web/Accessibility/ARIA/Roles/meter_role) <br/>A scalar measurement within a known range, or a fractional value.<br/>Accessible name required. `aria-valuenow` required.<br/>See [`meter` role](/en-US/docs/Web/Accessibility/ARIA/Roles/meter_role) for more information. | {{HTMLElement('meter')}} | -| **`paragraph`** <br/>A paragraph of content.<br/> Prohibited attributes: `aria-label` and `aria-labelledby`. | {{HTMLElement('p')}} | -| **`strong`** <br/>Important, serious, or urgent content.<br/> Prohibited attributes: `aria-label` and `aria-labelledby`. | {{HTMLElement('strong')}} | -| **`subscript`** <br/>One or more subscripted characters.<br/>Only use if absence of role would change the content's meaning.<br/> Prohibited attributes: `aria-label` and `aria-labelledby`. | {{HTMLElement('sub')}} | -| **`superscript`** <br/>One or more superscripted characters.<br/>Only use if absence of role would change the content's meaning.<br/> Prohibited attributes: `aria-label` and `aria-labelledby`. | {{HTMLElement('sup')}} | -| [`term`](/en-US/docs/Web/Accessibility/ARIA/Roles/term_role)<br/>Word or phrase with an optional corresponding definition.<br/> Prohibited attributes: `aria-label` and `aria-labelledby`.<br/>See [`term` role](/en-US/docs/Web/Accessibility/ARIA/Roles/term_role) for more information. | {{HTMLElement('dfn')}} | -| **`time`** <br> A valid date or time string format list a specific point in time.<br/> Prohibited attributes: `aria-label` and `aria-labelledby`. | {{HTMLElement('time')}} | - -> [!NOTE] -> The `aria-label` and `aria-labelledby` attributes are prohibited on `code`, `caption`, `deletion`, `emphasis`, `generic`, `insertion`, `mark`, `paragraph`, `presentation`, `none`, `strong`, `subscript`, `superscript`, `suggestion`, `term`, and `time`, and should only be used on interactive content. - -## Best Practices - -Do not use structural roles. Opt for HTML semantic elements instead. - -## Specifications - -{{Specifications}} - -## See also diff --git a/files/en-us/web/accessibility/aria/roles/structure_role/index.md b/files/en-us/web/accessibility/aria/roles/structure_role/index.md deleted file mode 100644 index 00eed89804867e8..000000000000000 --- a/files/en-us/web/accessibility/aria/roles/structure_role/index.md +++ /dev/null @@ -1,45 +0,0 @@ ---- -title: "ARIA: structure role" -slug: Web/Accessibility/ARIA/Roles/structure_role -page-type: aria-role -spec-urls: https://w3c.github.io/aria/#structure ---- - -{{AccessibilitySidebar}} - -The `structure` role is for document structural elements. - -> [!NOTE] -> The `structure` role is an [abstract role](/en-US/docs/Web/Accessibility/ARIA/Roles#6._abstract_roles). It is included here for completeness of documentation. It should not be used by web authors. - -## Description - -`Structure` is a superclass [abstract role](/en-US/docs/Web/Accessibility/ARIA/Roles#6._abstract_roles) for document structures, like as [`document`](/en-US/docs/Web/Accessibility/ARIA/Roles/document_role), -[`rowgroup`](/en-US/docs/Web/Accessibility/ARIA/Roles/rowgroup_role), and [`sectionhead`](/en-US/docs/Web/Accessibility/ARIA/Roles/sectionhead_role), that support the accessibility of dynamic web content by helping assistive technologies determine active content versus static document content. Some subclass roles, like -[`section` role](/en-US/docs/Web/Accessibility/ARIA/Roles/section_role), are in turn superclasses of other roles. - -The `structure` role is the superclass for all document structure roles, which are used to provide a structural description for a section of content. Most structure roles should no longer be used as browsers now support semantic HTML element with the same meaning. The structure roles without HTML equivalents, such as the [`presentation` role](/en-US/docs/Web/Accessibility/ARIA/Roles/presentation_role) which means content is presentational only, provide information on the document structure to assistive technologies such as screen readers as equivalent native HTML tags are not available. - -## Best Practices - -Do not use `role="structure"`. Do use HTML and subclass structure roles. - -## Specifications - -{{Specifications}} - -## See also - -- [ARIA: `roletype` role](/en-US/docs/Web/Accessibility/ARIA/Roles/roletype_role) -- [ARIA: `generic` role](/en-US/docs/Web/Accessibility/ARIA/Roles/generic_role) -- [ARIA: `presentation` role](/en-US/docs/Web/Accessibility/ARIA/Roles/presentation_role) -- [ARIA: `range` role](/en-US/docs/Web/Accessibility/ARIA/Roles/range_role) -- [ARIA: `section` role](/en-US/docs/Web/Accessibility/ARIA/Roles/section_role) -- [ARIA: `sectionhead` role](/en-US/docs/Web/Accessibility/ARIA/Roles/sectionhead_role) - -<!-- these shouldn't be used so we shouldn't link to them -- [ARIA: `application` role](/en-US/docs/Web/Accessibility/ARIA/Roles/application_role) -- [ARIA: `document` role](/en-US/docs/Web/Accessibility/ARIA/Roles/document_role) -- [ARIA: `rowgroup` role](/en-US/docs/Web/Accessibility/ARIA/Roles/rowgroup_role) -- [ARIA: `separator` role](/en-US/docs/Web/Accessibility/ARIA/Roles/separator_role) ---> diff --git a/files/en-us/web/accessibility/aria/roles/suggestion_role/index.md b/files/en-us/web/accessibility/aria/roles/suggestion_role/index.md deleted file mode 100644 index ec8b6bad10401de..000000000000000 --- a/files/en-us/web/accessibility/aria/roles/suggestion_role/index.md +++ /dev/null @@ -1,54 +0,0 @@ ---- -title: "ARIA: suggestion role" -slug: Web/Accessibility/ARIA/Roles/suggestion_role -page-type: aria-role ---- - -{{AccessibilitySidebar}} - -The `suggestion` role semantically denotes a single proposed change to an editable document. This should be used on an element that wraps an element with an `insertion` role, and one with a `deletion` role. - -## Examples - -When you've got a content change that involves an insertion _and_ a deletion, there is no way for a screen reader user to work out if the two are related or not. This is the job of `role="suggestion"`, which should be set on an element wrapping both of them like so: - -```html -<p> - Freida's pet is a - <span role="suggestion"> - <span role="deletion">black Cat called Luna</span> - <span role="insertion">purple T. Rex called Tiny</span></span - >. -</p> -``` - -We could even provide an information box saying who made the suggestion and when, and associate it with the suggestion via [`aria-details`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-details): - -```html -<p> - Freida's pet is a - <span role="suggestion" aria-details="comment-source"> - <span role="deletion">black Cat called Luna</span> - <span role="insertion">purple T. Rex called Tiny</span></span - >. -</p> - -<div id="comment-source"> - Suggested by Chris, - <time datetime="2019-03-30T19:29">March 30 2019, 19:29</time> -</div> -``` - -Browsers tend to provide a default black strikethrough for deletions, and a black underline for insertions when using the HTML elements that implicitly expose these roles. But when using explicit ARIA roles to modify HTML elements, such as divs, you'll need to use CSS to customize the visual styling for such deletions and insertions. - -## Best practices - -### Prefer HTML - -Using the [`<ins>`](/en-US/docs/Web/HTML/Element/ins) and [`<del>`](/en-US/docs/Web/HTML/Element/del) element will automatically communicate a section has a role of `insertion` or `deletion`. If at all possible, prefer using the HTML elements. - -## Specifications - -Will be part of WAI-ARIA 1.3, which is still being drafted. - -## See also diff --git a/files/en-us/web/accessibility/aria/roles/switch_role/index.md b/files/en-us/web/accessibility/aria/roles/switch_role/index.md deleted file mode 100644 index 52e805e2f3fcdfe..000000000000000 --- a/files/en-us/web/accessibility/aria/roles/switch_role/index.md +++ /dev/null @@ -1,193 +0,0 @@ ---- -title: "ARIA: switch role" -slug: Web/Accessibility/ARIA/Roles/switch_role -page-type: aria-role -spec-urls: - - https://w3c.github.io/aria/#switch - - https://w3c.github.io/html-aria/#index-aria-switch ---- - -{{AccessibilitySidebar}} - -The ARIA **`switch`** role is functionally identical to the [checkbox](/en-US/docs/Web/Accessibility/ARIA/Roles/checkbox_role) role, except that instead of representing "checked" and "unchecked" states, which are fairly generic in meaning, the `switch` role represents the states "on" and "off." - -This example creates a widget and assigns the ARIA `switch` role to it. - -```html -<button - type="button" - role="switch" - aria-checked="true" - id="speakerPower" - class="switch"> - <span aria-hidden="true">off</span> - <span aria-hidden="true">on</span> -</button> -<label for="speakerPower" class="switch">Speaker power</label> -``` - -## Description - -The ARIA **`switch`** role is identical to the [checkbox](/en-US/docs/Web/Accessibility/ARIA/Roles/checkbox_role) role, except instead of being "checked" or "unchecked", it is either "on" or "off". Like the [checkbox](/en-US/docs/Web/Accessibility/ARIA/Roles/checkbox_role) role, the [`aria-checked`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-checked) attribute is required. The two possible values are `true` and `false`. Unlike an `<input type="checkbox">` or `role="checkbox"`, there is no `indeterminate` or `mixed` state. The `switch` role does not support the value `mixed` for the `aria-checked` attribute; assigning a value of `mixed` to a `switch` instead sets the value to `false`. - -Assistive technologies may choose to represent `switch` widgets with a specialized presentation to reflect the notion of an on/off switch. - -Since a switch is an interactive control, it must be focusable and keyboard accessible. If the role is applied to a non-focusable element, use the `tabindex` attribute to change this. The expected keyboard shortcut for toggling the value of a switch is the <kbd>Space</kbd> key. The developer is required to change the value of the `aria-checked` attribute dynamically when the switch is toggled. - -### All descendants are presentational - -There are some types of user interface components that, when represented in a platform accessibility API, can only contain text. Accessibility APIs do not have a way of representing semantic elements contained in a `switch`. To deal with this limitation, browsers, automatically apply role [`presentation`](/en-US/docs/Web/Accessibility/ARIA/Roles/presentation_role) to all descendant elements of any `switch` element as it is a role that does not support semantic children. - -For example, consider the following `switch` element, which contains a heading. - -```html -<div role="switch"><h3>Title of my switch</h3></div> -``` - -Because descendants of `switch` are presentational, the following code is equivalent: - -```html -<div role="switch"><h3 role="presentation">Title of my switch</h3></div> -``` - -From the assistive technology user's perspective, the heading does not exist since the previous code snippets are equivalent to the following in the [accessibility tree](/en-US/docs/Glossary/Accessibility_tree): - -```html -<div role="switch">Title of my switch</div> -``` - -### Associated ARIA roles, states, and properties - -- [`aria-checked`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-checked) attribute - - : The `aria-checked` attribute is **required** when using the `switch` role, as it represents the current state of the widget that the `switch` role is applied to. A value of `true` represents the "on" state; `false` represents the "off" state; a value of `mixed` is not supported by the switch role, and is treated as `false`. -- [`aria-readonly`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-readonly) attribute - - : The `aria-readonly` attribute is supported by the `switch` role. It indicates whether the widget's state is editable by the user. A value of `false` means that the user _can_ change the widget's state; a value of `true` means that the user _cannot_ change the widget's state. The default value is `false`. - -### Required JavaScript features - -- Handler for click events - - : When the user clicks on the switch widget, a [click event](/en-US/docs/Web/API/Element/click_event) is fired, which must be handled in order to change the state of the widget. -- Changing the `aria-checked` attribute - - : When a click event is fired on the switch widget, the handler must change the value of the `aria-checked` attribute from `true` to `false`, or vice versa. - -## Possible effects on user agents and assistive technology - -When the `switch` role is added to an element, the {{Glossary("user agent")}} handles it like this: - -- The element is exposed to the system's accessibility infrastructure as having the `switch` role. -- When the `aria-checked` attribute's value changes, an accessible event is fired using the system's accessibility API if one is available and it supports the `switch` role. -- All elements that are descendants of an element with the `switch` role applied to it are automatically assigned role `presentation`. This prevents elements that are used to construct the switch from being interacted with individually by assistive technologies. Text in these elements remains visible to the user agent and may be read or otherwise delivered to the user, unless it's expressly hidden using {{cssxref("display", "display: none")}} or `aria-hidden="true"`. - -The assistive technology, if it supports the `switch` role, responds by doing the following: - -- Screen readers should announce the element as a switch, optionally providing instructions as to how to activate the switch. - -> [!NOTE] -> There are varying opinions on how assistive technologies should handle this role; the above is a suggested practice and may differ from other sources. - -## Examples - -The following examples should help you understand how to apply and use the `switch` role. - -### Adding the switch role in ARIA - -This simple example just creates a widget and assigns the ARIA `switch` role to it. The button is styled with an appearance reminiscent of an on/off power switch. - -#### HTML - -The HTML is fairly simple here. The switch is implemented as a {{HTMLElement("button")}} element which is initially checked courtesy of its `aria-checked` attribute being set to `"true"`. The switch has two child elements containing the "off" and "on" labels and is followed by a {{HTMLElement("label")}} identifying the switch. - -```html -<button role="switch" aria-checked="true" id="speakerPower" class="switch"> - <span>off</span> - <span>on</span> -</button> -<label for="speakerPower" class="switch">Speaker power</label> -``` - -#### JavaScript - -This JavaScript code defines and applies a function to handle click events on switch widgets. The function changes the `aria-checked` attribute from `true` to `false`, or vice versa. - -```js -document.querySelectorAll(".switch").forEach((theSwitch) => { - theSwitch.addEventListener("click", handleClickEvent, false); -}); - -function handleClickEvent(evt) { - const el = evt.target; - - if (el.getAttribute("aria-checked") === "true") { - el.setAttribute("aria-checked", "false"); - } else { - el.setAttribute("aria-checked", "true"); - } -} -``` - -#### CSS - -The purpose of the CSS is to establish a look and feel for the switch that's reminiscent of the power switch paradigm. - -```css -button.switch { - margin: 0; - padding: 0; - width: 70px; - height: 26px; - border: 2px solid black; - display: inline-block; - margin-right: 0.25em; - line-height: 20px; - vertical-align: middle; - text-align: center; - font: - 12px "Open Sans", - "Arial", - serif; -} - -button.switch span { - padding: 0 4px; - pointer-events: none; -} - -[role="switch"][aria-checked="false"] :first-child, -[role="switch"][aria-checked="true"] :last-child { - background: #262; - color: #eef; -} - -[role="switch"][aria-checked="false"] :last-child, -[role="switch"][aria-checked="true"] :first-child { - color: #bbd; -} - -label.switch { - font: - 16px "Open Sans", - "Arial", - sans-serif; - line-height: 20px; - vertical-align: middle; - user-select: none; -} -``` - -The most interesting part is probably the use of attribute selectors and the {{cssxref(":first-child")}} and {{cssxref(":last-child")}} pseudo-classes to do all the heavy lifting of changing the appearance of the switch based on whether it's on or off. - -#### Result - -The result looks like this: - -{{EmbedLiveSample("Adding_the_switch_role_in_ARIA", 600, 40)}} - -## Specifications - -{{Specifications}} - -## See also - -- [ARIA: checkbox role](/en-US/docs/Web/Accessibility/ARIA/Roles/checkbox_role) -- [`<input type="checkbox">`](/en-US/docs/Web/HTML/Element/input/checkbox) -- [`aria-hidden`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-hidden) diff --git a/files/en-us/web/accessibility/aria/roles/tab_role/index.md b/files/en-us/web/accessibility/aria/roles/tab_role/index.md deleted file mode 100644 index 4561b763e4a1b98..000000000000000 --- a/files/en-us/web/accessibility/aria/roles/tab_role/index.md +++ /dev/null @@ -1,246 +0,0 @@ ---- -title: "ARIA: tab role" -slug: Web/Accessibility/ARIA/Roles/tab_role -page-type: aria-role -spec-urls: - - https://w3c.github.io/aria/#tab - - https://www.w3.org/WAI/ARIA/apg/patterns/tabs/examples/tabs-manual/ ---- - -{{AccessibilitySidebar}} - -The ARIA `tab` role indicates an interactive element inside a `tablist` that, when activated, displays its associated `tabpanel`. - -```html -<button role="tab" aria-selected="true" aria-controls="tabpanel-id" id="tab-id"> - Tab label -</button> -``` - -## Description - -An element with the `tab` role controls the visibility of an associated element with the [`tabpanel`](/en-US/docs/Web/Accessibility/ARIA/Roles/tabpanel_role) role. The common user experience pattern is a group of visual tabs above, or to the side of, a content area, and selecting a different tab changes the content and makes the selected tab more prominent than the other tabs. - -Elements with the role `tab` _must_ either be a child of an element with the `tablist` role, or have their `id` as part of the [`aria-owns`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-owns) property of a `tablist`. This combination identifies to assistive technology that the element is part of a group of related elements. Some assistive technology will provide a count of the number of `tab` role elements inside a `tablist`, and inform users of which `tab` they currently have targeted. Further, an element with the `tab` role _should_ contain the [`aria-controls`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-controls) property identifying a corresponding `tabpanel` (that has a `tabpanel` role) by that element's `id`. When an element with the `tabpanel` role has focus, or a child of it has focus, that indicates that the connected element with the `tab` role is the active tab in a `tablist`. - -When elements with the `tab` role are selected or active they should have their [`aria-selected`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-selected) attribute set to `true`. Otherwise, their `aria-selected` attribute should be set to `false`. When a single-selectable `tablist` is selected or active, the `hidden` attribute of the other tabpanels should be set to true until the user selects the tab associated with that tabpanel. When a multi-selectable `tablist` is selected or active, its corresponding controlled `tabpanel` should have its [`aria-expanded`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-expanded) attribute set to `true` and its `hidden` attribute set to `false`, otherwise the reverse. - -### All descendants are presentational - -There are some types of user interface components that, when represented in a platform accessibility API, can only contain text. Accessibility APIs do not have a way of representing semantic elements contained in a `tab`. To deal with this limitation, browsers, automatically apply role [`presentation`](/en-US/docs/Web/Accessibility/ARIA/Roles/presentation_role) to all descendant elements of any `tab` element as it is a role that does not support semantic children. - -For example, consider the following `tab` element, which contains a heading. - -```html -<div role="tab"><h3>Title of my tab</h3></div> -``` - -Because descendants of `tab` are presentational, the following code is equivalent: - -```html -<div role="tab"><h3 role="presentation">Title of my tab</h3></div> -``` - -From the assistive technology user's perspective, the heading does not exist since the previous code snippets are equivalent to the following in the [accessibility tree](/en-US/docs/Glossary/Accessibility_tree): - -```html -<div role="tab">Title of my tab</div> -``` - -### Associated roles and attributes - -- [`aria-selected`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-selected) - - : boolean -- [`aria-controls`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-controls) - - : `id` of element with `tabpanel` role -- [id](/en-US/docs/Web/HTML/Global_attributes/id) - - : content - -### Keyboard interactions - -| Key | Action | -| ----------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| <kbd>Tab</kbd> | When focus is outside of the `tablist` moves focus to the active tab. If focus is on the active tab moves focus to the next element in the keyboard focus order, ideally the active tab's associated `tabpanel`. | -| <kbd>→</kbd> | Focuses and optionally activates the next tab in the tab list. If the current tab is the last tab in the tab list it activates the first tab. | -| <kbd>←</kbd> | Focuses and optionally activates the previous tab in the tab list. If the current tab is the first tab in the tab list it activates the last tab. | -| <kbd>Delete</kbd> | When allowed removes the currently selected tab from the tab list. | - -### Required JavaScript features - -> [!NOTE] -> While there are ways to build tab-like functionality without JavaScript, there is no substitute combination using only HTML and CSS that will provide the same set of functionality that's required above for accessible tabs with content. - -## Example - -This example combines the role `tab` with `tablist` and elements with `tabpanel` to create an interactive group of tabbed content. Here we are enclosing our group of content in a `div`, with our `tablist` having an `aria-label` which labels it for assistive technology. Each `tab` is a `button` with the attributes previously mentioned. The first `tab` has both `tabindex="0"` and `aria-selected="true"` applied. These two attributes must always be coordinated as such—so when another tab is selected, it will then have `tabindex="0"` and `aria-selected="true"` applied. All unselected tabs must have `aria-selected="false"` and `tabindex="-1"`. - -All of the `tabpanel` elements have `tabindex="0"` to make them tabbable, and all but the currently active one have the `hidden` attribute. The `hidden` attribute will be removed when a `tabpanel` becomes visible with JavaScript. There is some basic styling applied that restyles the buttons and changes the [`z-index`](/en-US/docs/Web/CSS/z-index) of `tab` elements to give the illusion of it connecting to the `tabpanel` for active elements, and the illusion that inactive elements are behind the active `tabpanel`. - -```html -<div class="tabs"> - <div role="tablist" aria-label="Sample Tabs"> - <button - role="tab" - aria-selected="true" - aria-controls="panel-1" - id="tab-1" - tabindex="0"> - First Tab - </button> - <button - role="tab" - aria-selected="false" - aria-controls="panel-2" - id="tab-2" - tabindex="-1"> - Second Tab - </button> - <button - role="tab" - aria-selected="false" - aria-controls="panel-3" - id="tab-3" - tabindex="-1"> - Third Tab - </button> - </div> - <div id="panel-1" role="tabpanel" tabindex="0" aria-labelledby="tab-1"> - <p>Content for the first panel</p> - </div> - <div id="panel-2" role="tabpanel" tabindex="0" aria-labelledby="tab-2" hidden> - <p>Content for the second panel</p> - </div> - <div id="panel-3" role="tabpanel" tabindex="0" aria-labelledby="tab-3" hidden> - <p>Content for the third panel</p> - </div> -</div> -``` - -```css hidden -.tabs { - padding: 1em; -} - -[role="tablist"] { - margin-bottom: -1px; -} - -[role="tab"] { - position: relative; - z-index: 1; - background: white; - border-radius: 5px 5px 0 0; - border: 1px solid grey; - border-bottom: 0; - padding: 0.2em; -} - -[role="tab"][aria-selected="true"] { - z-index: 3; -} - -[role="tabpanel"] { - position: relative; - padding: 0 0.5em 0.5em 0.7em; - border: 1px solid grey; - border-radius: 0 0 5px 5px; - background: white; - z-index: 2; -} - -[role="tabpanel"]:focus { - border-color: orange; - outline: 1px solid orange; -} -``` - -There are two things we need to do with JavaScript: we need to change focus and tab index of our `tab` elements with the right and left arrows, and we need to change the active `tab` and `tabpanel` when we click on a `tab`. - -To accomplish the first, we listen for the [`keydown`](/en-US/docs/Web/API/Element/keydown_event) event on the `tablist`. If the event's [`key`](/en-US/docs/Web/API/KeyboardEvent/key) is `ArrowRight` or `ArrowLeft`, we react to the event. We start by setting the `tabindex` of the current `tab` element to -1, making it no longer tabbable. Then, if the right arrow is being pressed, we increase our tab focus counter by one. If the counter is greater than the number of `tab` elements we have, we circle back to the first tab by setting that counter to 0. If the left arrow is being pressed, we decrease our tab focus counter by one, and if it is then less than 0, we set it to the number of `tab` elements minus one (to get to the last element). Finally, we set `focus` to the `tab` element whose index is equal to the tab focus counter, and set its `tabindex` to 0 to make it tabbable. - -To handle changing the active `tab` and `tabpanel`, we have a function that takes in the event, gets the element that triggered the event, the triggering element's parent element, and its grandparent element. We then find all tabs with `aria-selected="true"` inside the parent element and sets it to `false`, then sets the triggering element's `aria-selected` to `true`. After that, we find all `tabpanel` elements in the grandparent element, make them all `hidden`, and finally select the element whose `id` is equal to the triggering `tab`'s `aria-controls` and removes the `hidden` attribute, making it visible. - -```js -window.addEventListener("DOMContentLoaded", () => { - // Only handle one particular tablist; if you have multiple tab - // lists (might even be nested), you have to apply this code for each one - const tabList = document.querySelector('[role="tablist"]'); - const tabs = tabList.querySelectorAll(':scope > [role="tab"]'); - - // Add a click event handler to each tab - tabs.forEach((tab) => { - tab.addEventListener("click", changeTabs); - }); - - // Enable arrow navigation between tabs in the tab list - let tabFocus = 0; - - tabList.addEventListener("keydown", (e) => { - // Move right - if (e.key === "ArrowRight" || e.key === "ArrowLeft") { - tabs[tabFocus].setAttribute("tabindex", -1); - if (e.key === "ArrowRight") { - tabFocus++; - // If we're at the end, go to the start - if (tabFocus >= tabs.length) { - tabFocus = 0; - } - // Move left - } else if (e.key === "ArrowLeft") { - tabFocus--; - // If we're at the start, move to the end - if (tabFocus < 0) { - tabFocus = tabs.length - 1; - } - } - - tabs[tabFocus].setAttribute("tabindex", 0); - tabs[tabFocus].focus(); - } - }); -}); - -function changeTabs(e) { - const targetTab = e.target; - const tabList = targetTab.parentNode; - const tabGroup = tabList.parentNode; - - // Remove all current selected tabs - tabList - .querySelectorAll(':scope > [aria-selected="true"]') - .forEach((t) => t.setAttribute("aria-selected", false)); - - // Set this tab as selected - targetTab.setAttribute("aria-selected", true); - - // Hide all tab panels - tabGroup - .querySelectorAll(':scope > [role="tabpanel"]') - .forEach((p) => p.setAttribute("hidden", true)); - - // Show the selected panel - tabGroup - .querySelector(`#${targetTab.getAttribute("aria-controls")}`) - .removeAttribute("hidden"); -} -``` - -{{EmbedLiveSample("Example", 600, 130)}} - -## Best practices - -It is recommended to use a {{HTMLElement('button')}} element with the role `tab` for their built-in functional and accessible features instead, as opposed to needing to add them yourself. For controlling tab key functionality for elements with the role `tab`, it is recommended to set all non-active elements to `tabindex="-1"`, and to set the active element to `tabindex="0"`. - -## Precedence order - -What are the related properties, and in what order will this attribute or property be read, which property will take precedence over this one, and which property will be overwritten. - -## Specifications - -{{Specifications}} - -## See also - -- HTML {{HTMLElement('button')}} element -- [KeyboardEvent.key](/en-US/docs/Web/API/KeyboardEvent/key) -- [ARIA `tabpanel` role](/en-US/docs/Web/Accessibility/ARIA/Roles/tabpanel_role) diff --git a/files/en-us/web/accessibility/aria/roles/table_role/index.md b/files/en-us/web/accessibility/aria/roles/table_role/index.md deleted file mode 100644 index 8b7f5fbed8e617d..000000000000000 --- a/files/en-us/web/accessibility/aria/roles/table_role/index.md +++ /dev/null @@ -1,150 +0,0 @@ ---- -title: "ARIA: table role" -slug: Web/Accessibility/ARIA/Roles/table_role -page-type: aria-role -spec-urls: - - https://w3c.github.io/aria/#table - - https://www.w3.org/WAI/ARIA/apg/patterns/table/examples/table/ ---- - -{{AccessibilitySidebar}} - -The `table` value of the ARIA `role` attribute identifies the element containing the role as having a non-interactive table structure containing data arranged in rows and columns, similar to the native {{HTMLElement('table')}} HTML element. - -```html -<div - role="table" - aria-label="Semantic Elements" - aria-describedby="semantic_elements_table_desc" - aria-rowcount="81"> - <div id="semantic_elements_table_desc"> - Semantic Elements to use instead of ARIA's roles - </div> - <div role="rowgroup"> - <div role="row"> - <span role="columnheader" aria-sort="none">ARIA Role</span> - <span role="columnheader" aria-sort="none">Semantic Element</span> - </div> - </div> - <div role="rowgroup"> - <div role="row" aria-rowindex="11"> - <span role="cell">header</span> - <span role="cell">h1</span> - </div> - <div role="row" aria-rowindex="16"> - <span role="cell">header</span> - <span role="cell">h6</span> - </div> - <div role="row" aria-rowindex="18"> - <span role="cell">rowgroup</span> - <span role="cell">thead</span> - </div> - <div role="row" aria-rowindex="24"> - <span role="cell">term</span> - <span role="cell">dt</span> - </div> - </div> -</div> -``` - -## Description - -An element with `role="table"` is a static tabular structure with rows containing cells. The cells are not focusable or selectable, though widgets within individual cells of the table can be interactive. Using a native HTML {{HTMLElement('table')}} element whenever possible is strongly encouraged. - -> [!WARNING] -> If a table maintains a selection state, has two-dimensional navigation, or allows the user to rearrange cell order use [`grid`](/en-US/docs/Web/Accessibility/ARIA/Roles/grid_role) or [`treegrid`](/en-US/docs/Web/Accessibility/ARIA/Roles/treegrid_role) instead. - -To create an ARIA table, add `role="table"` to the container element. Within that container, each row has `role="row"` set and contains child cells. Each cell has a role of either `columnheader`, `rowheader`, or `cell`. Rows can be children of the table or within a `rowgroup`. - -The table caption can be defined via [`aria-labelledby`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-labelledby) or [`aria-label`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-label). All other semantic table elements, such as {{HTMLElement('tbody')}}, {{HTMLElement('thead')}}, {{HTMLElement('tr')}}, {{HTMLElement('th')}}, and {{HTMLElement('td')}}, need to be added via associated roles, such as `rowgroup`, `row`, `columnheader`, and `cell`. - -If the table contains sortable columns or rows, the [`aria-sort`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-sort) attribute should be added on the header cell element (not the table itself). If any rows or columns are hidden, the [`aria-colcount`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-colcount) or [`aria-rowcount`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-rowcount) should be included indicating the total number of columns or rows, respectively, along with the [`aria-colindex`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-colindex) or [`aria-rowindex`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-rowindex) on each cell. The [`aria-colindex`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-colindex) or [`aria-rowindex`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-rowindex) is set to the position of a cell within the row or column, respectively. If the table includes cells that span multiple rows or multiple columns, then [`aria-rowspan`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-rowspan) or [`aria-colspan`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-colspan) should be included as well. Realize, it is much simpler to use the {{HTMLElement('table')}} element, along with all the related semantic elements and attributes that are all supported by all assistive technologies. - -To create an interactive widget that has a tabular structure, use the `grid` pattern instead. If the interaction provides for the selection state of individual cells, if left to right and top to bottom navigation is provided, or if the user interface allows the rearranging of cell order or otherwise changing individual cell order such as through drag and drop, use [`grid`](/en-US/docs/Web/Accessibility/ARIA/Roles/grid_role) or [`treegrid`](/en-US/docs/Web/Accessibility/ARIA/Roles/treegrid_role) instead. - -> [!NOTE] -> Using a native HTML table element whenever possible is strongly encouraged. - -### Associated WAI-ARIA roles, states, and properties - -- `role="rowgroup"` - - : An optional child of the table, the row group encapsulates a group of rows, similar to {{HTMLElement('thead')}}, {{HTMLElement('tbody')}}, and {{HTMLElement('tfoot')}}. -- [`role="row"`](/en-US/docs/Web/Accessibility/ARIA/Roles/row_role) - - : A row within the table, and optionally within a rowgroup that contains one or more cells, column headers, or row headers. -- [`aria-describedby`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-describedby) attribute - - : Takes as its value the id of the element that serves as a description for the table. -- [`aria-label`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-label) attribute - - : The [`aria-label`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-label) provides an accessible name for the table. -- [`aria-colcount`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-colcount) attribute - - : This attribute is only required if the columns are not present in the DOM all the time. It provides an explicit indication of the number of columns in the full table. Set the value to the total number of columns in the full table. If unknown, set `aria-colcount="-1"`. -- [`aria-rowcount`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-rowcount) attribute - - : This attribute is only required if the rows are not present in the DOM all the time, such as scrollable tables that reuse rows to minimize the number of DOM nodes. It provides an explicit indication of the number of rows in the full table. Set the value to the total number of rows in the full table. If unknown, set `aria-rowcount="-1"`. - -### Keyboard interactions - -None - -### Required JavaScript features - -None. For sortable columns, see the [columnheader](/en-US/docs/Web/Accessibility/ARIA/Roles/columnheader_role) aria role. - -> [!NOTE] -> The first rule of ARIA use is if you can use a native feature with the semantics and behavior you require already built in, instead of re-purposing an element and **adding** an ARIA role, state or property to make it accessible, then do so. Employ the HTML {{HTMLElement('table')}} element instead of the ARIA role of table whenever possible. - -## Examples - -```html -<div - role="table" - aria-label="Semantic Elements" - aria-describedby="semantic_elements_table_desc" - aria-rowcount="81"> - <div id="semantic_elements_table_desc"> - Semantic Elements to use instead of ARIA's roles - </div> - <div role="rowgroup"> - <div role="row"> - <span role="columnheader" aria-sort="none">ARIA Role</span> - <span role="columnheader" aria-sort="none">Semantic Element</span> - </div> - </div> - <div role="rowgroup"> - <div role="row" aria-rowindex="11"> - <span role="cell">header</span> - <span role="cell">h1</span> - </div> - <div role="row" aria-rowindex="16"> - <span role="cell">header</span> - <span role="cell">h6</span> - </div> - <div role="row" aria-rowindex="18"> - <span role="cell">rowgroup</span> - <span role="cell">thead</span> - </div> - <div role="row" aria-rowindex="24"> - <span role="cell">term</span> - <span role="cell">dt</span> - </div> - </div> -</div> -``` - -The above is part of a table. While the full table has 81 entries, as indicated by the [`aria-rowcount`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-rowcount) property, only four are currently visible. The columns are sortable, but not currently sorted, as indicated by the [`aria-sort`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-sort) property on the column headers. - -## Best practices - -Only use {{HTMLElement('table')}}, {{HTMLElement('tbody')}}, {{HTMLElement('thead')}}, {{HTMLElement('tr')}}, {{HTMLElement('th')}}, {{HTMLElement('td')}}, etc., for data table structure. You can add these ARIA roles to ensure accessibility should the native semantics of the table be removed, such as with CSS. A relevant use case for the ARIA table role is when CSS's display property overrides the native semantics of a table, such as by `display: grid`. In this case, you can use the ARIA table roles to re-add the semantics. - -### Added benefits - -none - -## Specifications - -{{Specifications}} - -## See also - -- [Learn: HTML table accessibility](/en-US/docs/Learn_web_development/Core/Structuring_content/Table_accessibility) -- [Learn: HTML table basics](/en-US/docs/Learn_web_development/Core/Structuring_content/HTML_table_basics) -- [ARIA: `grid` role](/en-US/docs/Web/Accessibility/ARIA/Roles/grid_role) diff --git a/files/en-us/web/accessibility/aria/roles/tablist_role/index.md b/files/en-us/web/accessibility/aria/roles/tablist_role/index.md deleted file mode 100644 index 43a3d3d62d405c6..000000000000000 --- a/files/en-us/web/accessibility/aria/roles/tablist_role/index.md +++ /dev/null @@ -1,102 +0,0 @@ ---- -title: "ARIA: tablist role" -slug: Web/Accessibility/ARIA/Roles/tablist_role -page-type: aria-role -spec-urls: https://w3c.github.io/aria/#tablist ---- - -{{AccessibilitySidebar}} - -The `tablist` role identifies the element that serves as the container for a set of `tabs`. The tab content are referred to as `tabpanel` elements. - -## Description - -You may be interacting with a tabbed interface as you read this! Browser tabs allow a user have multiple web pages open in a single window. Clicking on a tab in the tablist at the top of the browser window enables the user to display the associated content in the main content area, the tabpanel, one site at a time. This is called a "tab design pattern". - -When implementing a tab design pattern, the [`tab`](/en-US/docs/Web/Accessibility/ARIA/Roles/tab_role), `tablist` and [`tabpanel`](/en-US/docs/Web/Accessibility/ARIA/Roles/tabpanel_role) roles are used. - -Tabs are a set of layered sections of content, known as tab panels, that display one panel of content at a time. Each tab panel has an associated `tab` element, that, when activated, displays the panel. The list of tab elements is arranged along one edge of the currently displayed panel, most commonly the top edge, nested in a `tablist` element. - -Each `tab` in a `tablist` serves as a label for one `tabpanel` and can be activated to display that panel. The `tablist` is the containing element for the set of tab elements contained. - -When a tabbed interface is initialized, one tab panel is displayed and its associated tab is styled to indicate that it is active. When the user activates one of the other tab elements, the previously displayed tab panel is hidden, the tab panel associated with the activated tab becomes visible, and the tab is considered "active". - -For a single-selectable tablist, the non-active tabpanel elements should be hidden from the user until the user selects the tab associated with that tabpanel. - -When creating a multi-selectable tablist, include [`aria-multiselectable="true"`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-multiselectable) on the `tablist element`. - -The `tab` elements not the `tablist`, have the [`aria-selected`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-selected) attribute. Set to `aria-selected="true"` for the tabs associated with each visible tabpanel. The tabs associated with hidden tabpanel elements have their `aria-selected` attributes set to `false`. - -If the tab list has a visible label, set [`aria-labelledby`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-labelledby) to the `id` of the labelling element. If not, use [`aria-label`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-label) to provide a label. - -To be keyboard accessible, focus must be managed for the descendants of this role. - -Elements with the `tablist` role have an implicit [`aria-orientation`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-orientation) value of `horizontal`. - -### Associated WAI-ARIA roles, states, and properties - -- [`tab`](/en-US/docs/Web/Accessibility/ARIA/Roles/tab_role) role - - : Required Owned Elements. Every tablist must have one or more `tab` children. -- [`aria-multiselectable`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-multiselectable) - - : When set to `true`, indicates the user may select more than one `tab` from the `tablist` descendants. -- [`aria-orientation`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-orientation) - - : If the tablist element is vertically oriented, set `aria-orientation="vertical"`. The default is `horizontal`. - -### Keyboard interactions - -For the tab list: - -- <kbd>Tab</kbd> - - : When focus moves into the tab list, places focus on the active `tab` element. <br/><br/>When the tab list contains the focus, moves focus to the next element in the page tab sequence outside the tablist, which is the tabpanel unless the first element containing meaningful content inside the tabpanel is focusable. - -When focus is on a tab element in a horizontal tab list: - -- <kbd>Left Arrow</kbd> - - : moves focus to the previous tab. If focus is on the first tab, moves focus to the last tab. Optionally, activates the newly focused tab -- <kbd>Right Arrow</kbd> - - : Moves focus to the next tab. If focus is on the last tab element, moves focus to the first tab. Optionally, activates the newly focused tab - -When focus is on a tab element in a vertical tab list: - -- <kbd>Up Arrow</kbd> - - : moves focus to the previous tab. If focus is on the first tab, moves focus to the last tab. Optionally, activates the newly focused tab -- <kbd>Down Arrow</kbd> - - : Moves focus to the next tab. If focus is on the last tab element, moves focus to the first tab. Optionally, activates the newly focused tab - -If the tab list is horizontal, it does not listen for <kbd>Down Arrow</kbd> or <kbd>Up Arrow</kbd> so those keys can provide their normal browser scrolling functions even when focus is inside the tab list. - -When focus is on a tab in a tablist with either horizontal or vertical orientation: - -- <kbd>Space</kbd> or <kbd>Enter</kbd> - - : Activates the tab if it was not activated automatically on focus. -- <kbd>Home</kbd> (Optional) - - : Moves focus to the first tab. Optionally, activates the newly focused tab -- <kbd>End</kbd> (Optional) - - : Moves focus to the last tab. Optionally, activates the newly focused tab -- <kbd>Shift + F10</kbd> - - : If the tab has an associated popup menu, opens the menu. -- <kbd>Delete</kbd> (Optional) - - : If deletion is allowed, deletes (closes) the current tab element and its associated tab panel, sets focus on the tab following the tab that was closed, and optionally activates the newly focused tab. If there is not a tab that followed the tab that was deleted, e.g., the deleted tab was the right-most tab in a left-to-right horizontal tab list, sets focus on and optionally activates the tab that preceded the deleted tab. If the application allows all tabs to be deleted, and the user deletes the last remaining tab in the tab list, the application moves focus to another element that provides a logical work flow. As an alternative to Delete, or in addition to supporting Delete, the delete function is available in a context menu. - -<!-- -### Required JavaScript features - -## Accessibility concerns - -## Best Practices - -### Prefer HTML ---> - -## Examples - -See the [`tabpanel`, `tab`, and `tablist` example](/en-US/docs/Web/Accessibility/ARIA/Roles/tab_role#example) in the [`tab`](/en-US/docs/Web/Accessibility/ARIA/Roles/tab_role) role definition. - -## Specifications - -{{Specifications}} - -## See also - -- [`tab` role](/en-US/docs/Web/Accessibility/ARIA/Roles/tab_role) -- [`tabpanel` role](/en-US/docs/Web/Accessibility/ARIA/Roles/tabpanel_role) diff --git a/files/en-us/web/accessibility/aria/roles/tabpanel_role/index.md b/files/en-us/web/accessibility/aria/roles/tabpanel_role/index.md deleted file mode 100644 index b5038b3a031a4b2..000000000000000 --- a/files/en-us/web/accessibility/aria/roles/tabpanel_role/index.md +++ /dev/null @@ -1,72 +0,0 @@ ---- -title: "ARIA: tabpanel role" -slug: Web/Accessibility/ARIA/Roles/tabpanel_role -page-type: aria-role -spec-urls: - - https://w3c.github.io/aria/#tabpanel - - https://www.w3.org/WAI/ARIA/apg/patterns/tabs/examples/tabs-manual/ ---- - -{{AccessibilitySidebar}} - -The ARIA `tabpanel` is a container for the resources of layered content associated with a `tab`. - -## Description - -The `tabpanel` role indicates the element is a container for the resources associated with a [`tab`](/en-US/docs/Web/Accessibility/ARIA/Roles/tab_role) role, where each `tab` is contained in a [`tablist`](/en-US/docs/Web/Accessibility/ARIA/Roles/tablist_role). - -A `tabpanel` is part of a tab interface, a common user experience pattern in which a group of visual tabs allow for quickly switching between multiple layered views. Each tab is defined as such with the `tab` role, and these tabs are contained within an element with the `tablist` role. The `tablist` is often visually positioned above or to the side of a content area, containing the associated tabpanels. The `tabpanel` is the role of the container for each pane of content that is associated with a corresponding `tab` in the tab interface's `tablist`. - -In many tab interfaces, only a single `tabpanel` will be visible at a time. However, some interfaces may require multiple tab panels to be displayed at once. In these cases the `tablist` would be provided the [`aria-multiselectable`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-multiselectable) attribute, and the `tab` elements would then use the [`aria-expanded`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-expanded) attribute to indicate whether its associated `tabpanel` was visible or not. The tab's selected state would instead be used to indicate which tabpanel is the currently 'active' panel. For example, this could indicate which tabpanel keyboard focus would move to if someone were to press the <kbd>tab</kbd> key when focused on an tab within the multi-select `tablist`. - -In single-select tab interfaces, only the `tabpanel` associated with the currently selected tab is displayed. All other `tabpanel` elements associated with the unselected tabs must be hidden from users. So when tab selection changes, the displayed tabpanel would also, while the previously-displayed tabpanel would then become hidden. - -In multi-select tab interfaces, multiple `tabpanel` elements may be displayed, matching the expanded state of their associated `tab` elements. - -Tabs do not act as anchor links to individual panels — and upon activation, keyboard focus should remain on the current `tab` element and not automatically move to the newly displayed `tabpanel`. While a tab interface may be progressively enhanced based off an underlying markup pattern of in-page hyperlinks pointing to their associated sections of content, when JavaScript is used to modify these elements into a tabbed interface, the hyperlinks' default behavior should be prevented. Ideally, this could be done by removing or modifying the `href` attribute, as this would have the added benefit of removing the hyperlink-specific menu items from the element's browser context menu. - -When keyboard focus is on a `tablist`, or a `tab` within the `tablist`, the <kbd>Tab</kbd> key should be programmed to move from the focused tab — which may or may not be the selected tab — to the `tabpanel` which represents the currently selected tab. - -Each `tab` in a `tablist` can serve as the label for its corresponding `tabpanel`. Include the `id` of each `tab` as the value for each `tabpanel`'s [`aria-labelledby`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-labelledby) attribute. - -You can also optionally associate each `tabpanel` with its associated `tab` by including the [`id`](/en-US/docs/Web/HTML/Global_attributes/id) of the `tabpanel` as the value of the `tab`'s [`aria-controls`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-controls) attribute. - -When a tabbed interface is initialized, one `tabpanel` is displayed and its associated `tab` is styled to indicate that it is active, reflecting its programmatic state. All inactive `tabpanel` elements must be hidden to all users. This is most commonly achieved by use of CSS's `display: none`. - -See the [ARIA `tab` role](/en-US/docs/Web/Accessibility/ARIA/Roles/tab_role) article for more information specific to the use of this role. - -Include [`tabindex="-1"`](/en-US/docs/Web/HTML/Global_attributes/tabindex) to allow a `tabpanel` to receive focus without including the `tabpanel` in the page's keyboard focus order. - -Make sure to define styles for a `tabpanel` for when it receives focus, optimally using the CSS {{CSSXref(':focus')}} pseudo-class, so keyboard users know there was a change in focus and are aware of what content currently has focus. - -Carousels can be created using this tab pattern: A slide picker controls can be marked up as `tabs` in a `tablist` with the slide represented by a `tabpanel` element. - -### Associated Roles and Attributes - -- [`tab` role](/en-US/docs/Web/Accessibility/ARIA/Roles/tab_role) - - : Controls the visibility of the associated `tabpanel` -- [`tablist` role](/en-US/docs/Web/Accessibility/ARIA/Roles/tablist_role) - - : Group of `tab` elements. -- [`aria-labelledby`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-labelledby) - - : Provides an accessible name. References the `tab` element that controls the panel -- [`aria-expanded`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-expanded) - - : Should be used on the necessary `tab` elements if a multi-selectable `tablist` is used. - -### Keyboard interactions - -See the [`tablist` keyboard interactions](/en-US/docs/Web/Accessibility/ARIA/Roles/tablist_role#keyboard_interactions) in the [`tablist`](/en-US/docs/Web/Accessibility/ARIA/Roles/tablist_role) role definition. - -## Example - -See the [`tabpanel`, `tab`, and `tablist` example](/en-US/docs/Web/Accessibility/ARIA/Roles/tab_role#example) in the [`tab`](/en-US/docs/Web/Accessibility/ARIA/Roles/tab_role) role definition. - -## Specifications - -{{Specifications}} - -## See also - -- [ARIA `tab` role](/en-US/docs/Web/Accessibility/ARIA/Roles/tab_role) -- [ARIA `tablist` role](/en-US/docs/Web/Accessibility/ARIA/Roles/tablist_role) -- [Example: Tabs with Automatic Activation](https://www.w3.org/WAI/ARIA/apg/example-index/tabs/tabs-automatic.html) - W3C -- [Example: Tabs with Manual Activation](https://www.w3.org/WAI/ARIA/apg/example-index/tabs/tabs-manual.html) -W3C diff --git a/files/en-us/web/accessibility/aria/roles/term_role/index.md b/files/en-us/web/accessibility/aria/roles/term_role/index.md deleted file mode 100644 index 2e3c3a2d5970b2e..000000000000000 --- a/files/en-us/web/accessibility/aria/roles/term_role/index.md +++ /dev/null @@ -1,91 +0,0 @@ ---- -title: "ARIA: term role" -slug: Web/Accessibility/ARIA/Roles/term_role -page-type: aria-role -spec-urls: https://w3c.github.io/aria/#term ---- - -{{AccessibilitySidebar}} - -The `term` role can be used for a word or phrase with an optional corresponding [`definition`](/en-US/docs/Web/Accessibility/ARIA/Roles/definition_role). - -## Description - -The `term` role can be used for a word or phrase with an optional corresponding [`definition`](/en-US/docs/Web/Accessibility/ARIA/Roles/definition_role). It is equivalent in semantics to the HTML {{HTMLElement('dfn')}} element and the definition term ({{HTMLElement('dt')}}) element within a definition list ({{HTMLElement('dl')}} ). - -The `term` role is used to explicitly identify a word or phrase for which a definition has been provided by the author or is expected to be provided by the user. If there is an existing definition, or a form or form control to enter a definition, authors SHOULD set [`aria-details`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-details) to point to the related element. - -Don't use the `role="term"` on interactive elements like links because it can interfere with assistive technology users ability to interact with the element. Also, the term itself is the accessible name, so do not use [`aria-label`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-label) or [`aria-labelledby`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-labelledby). - -> [!WARNING] -> The accessible name should be the term itself, so DO NOT use `aria-label` or `aria-labelledby`. - -### Associated WAI-ARIA roles, states, and properties - -None. - -### Keyboard interactions - -None. - -### Required JavaScript features - -None. - -## Examples - -```html -<p> - <span role="term">Mansplaining</span>, - <span role="definition" - >a portmanteau of "man" and "explain", is the patronizing act of explaining - without being asked to do so, to someone already learned on the topic, often - after someone has already explained it</span - >. -</p> -``` - -Including better semantics, the above could also be written: - -```html -<p> - <dfn role="term">Mansplaining</dfn>, - <span role="definition" - >a portmanteau of "man" and "explain", is the patronizing act of explaining - without being asked to do so, to someone already learned on the topic, often - after someone has already explained it</span - >. -</p> -``` - -or without any ARIA (but possibly not how you want it presented) - -```html -<dl> - <dt>Mansplaining</dt> - <dd> - A portmanteau of "man" and "explain", is the patronizing act of explaining - without being asked to do so, to someone already learned on the topic, often - after someone has already explained it. - </dd> -</dl> -``` - -## Accessibility concerns - -Don't use the `role="term"` on interactive elements such as links as it can interfere with the assistive technology user's ability to interact with the element. - -## Best Practices - -Allow the term itself to define the accessible name. Do not use `aria-label` or `aria-labelledby`. - -### Prefer HTML - -## Specifications - -{{Specifications}} - -## See also - -- [ARIA: `definition` role](/en-US/docs/Web/Accessibility/ARIA/Roles/definition_role). -- The HTML {{HTMLElement('dfn')}} element diff --git a/files/en-us/web/accessibility/aria/roles/textbox_role/index.md b/files/en-us/web/accessibility/aria/roles/textbox_role/index.md deleted file mode 100644 index 505a079850b5cfc..000000000000000 --- a/files/en-us/web/accessibility/aria/roles/textbox_role/index.md +++ /dev/null @@ -1,128 +0,0 @@ ---- -title: "ARIA: textbox role" -slug: Web/Accessibility/ARIA/Roles/textbox_role -page-type: aria-role ---- - -{{AccessibilitySidebar}} - -The `textbox` role is used to identify an element that allows the input of free-form text. Whenever possible, rather than using this role, use an {{HTMLElement("input")}} element with [type="text"](/en-US/docs/Web/HTML/Element/input/text), for single-line input, or a {{HTMLElement("textarea")}} element for multi-line input. - -## Description - -When an element has the `textbox` role, the browser sends an accessible textbox event to assistive technologies, which can then notify the user about it. - -The default is a single line input, in which <kbd>Return</kbd> or <kbd>Enter</kbd> submits the form; in this case, it is preferable to use an HTML {{HTMLElement("input")}} with `type="text"`. To create a multi-line text box which supports line breaks, as in an HTML {{HTMLElement("textarea")}}, set `aria-multiline="true"`. Including the HTML `contenteditable` attribute ensures the text node is editable. - -```html -<!-- Simple text input field --> -<div id="txtboxLabel">Enter your five-digit zip code</div> -<div - role="textbox" - contenteditable="true" - aria-placeholder="5-digit zip code" - aria-labelledby="txtboxLabel"></div> - -<!-- Multi-line text area --> -<div id="txtboxMultilineLabel">Enter the tags for the article</div> -<div - role="textbox" - contenteditable="true" - aria-multiline="true" - aria-labelledby="txtboxMultilineLabel" - aria-required="true"></div> -``` - -Semantic elements are more concise and require no JavaScript to support textbox features. - -```html -<label for="txtbox">Enter your five-digit zip code</label> -<input type="text" placeholder="5-digit zip code" id="txtbox" /> - -<!-- Multi-line text area --> -<label for="txtboxMultiline">Enter the tags for the article</label> -<textarea id="txtboxMultiline" required></textarea> -``` - -Where a text field is read-only, indicated this by setting `aria-readonly="true"` on the element. - -### Associated ARIA properties - -- [`aria-activedescendant`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-activedescendant) attribute - - : Taking as it's value the ID of is either a descendant of the element with DOM focus or is a logical descendant as indicated by the [`aria-owns`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-owns) attribute, it indicates when that element has focus, when it is part of a composite widget such as a [`combobox`](/en-US/docs/Web/Accessibility/ARIA/Roles/combobox_role). For example, in a combobox, focus may remain on the textbox while the value of `aria-activedescendant` on the textbox element refers to a descendant of a popup listbox that is controlled by the textbox. This attribute must be updated programmatically as the focus changes. -- [`aria-autocomplete`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-autocomplete) attribute - - - : Indicates whether and how the user's input into the field could trigger display of a prediction of the intended value. It supports the following values: - - - `inline`: Predicted text is inserted after the caret. - - `list`: Predicted text is presented as a collection of values. - - `both`: Predicted text is presented as a collection of values, with the text needed to complete one value inserted after the caret. - - `none` (default): Predicted text is not offered. - - If list or both is set, the [`aria-controls`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-controls) and [`aria-haspopup`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-haspopup) attributes should also be included. The value of `aria-controls` is the ID of the element that contains the list of suggested values. Additionally, either the textbox or a containing element with role `combobox` has a value for `aria-haspopup` that matches the role of the element that contains the list of suggested values. - -- [`aria-multiline`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-multiline) attribute - - - : If `aria-multiline="true"` is set, the AT informs the user that the textbox supports multi-line input, with the expectation that <kbd>Enter</kbd> or <kbd>Return</kbd> will create a line break rather than submitting the form. ARIA does not alter the behavior of the element; rather this feature must be controlled by the developer. If false is set, or the attribute is omitted and defaults to false, the user expectation is that the control is a single line text box, and <kbd>Enter</kbd> or <kbd>Return</kbd> submits the form. - -- [`aria-placeholder`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-placeholder) attribute - - : Represents a hint (word or phrase) to the user about what to enter into the text field. The hint should be a sample value or a brief description of the expected format. This information should not be used as a substitute for a label: a label is focusable, permanent, indicates what kind of information is expected, and increases the hit area for setting focus on the control, whereas placeholder text is only temporary hint about the expected value, which if implemented incorrectly can decrease accessibility. The placeholder should be visible when the control's value is the empty string such as when the control first receives focus and when users remove a previously-entered value. Instead of using `aria-placeholder`, use the semantic `<input type="text">` or `<textarea>` with a `placeholder` attribute. -- [`aria-readonly`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-readonly) attribute - - : Indicates that the user cannot modify the value of the text field. Instead of using `aria-readonly`, use the semantic `<input type="text">` or `<textarea>` with a `readonly` attribute. -- [`aria-required`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-required) attribute - - : Indicates that a value must be provided for the field before it is submitted. Instead of using `aria-required`, use the semantic `<input type="text">` or `<textarea>` with a `required` attribute. - -### Keyboard interactions - -In a single-line use (when `aria-multiline` is `false` or not used), the Return or Enter key submits the form. In a multi-line use (when `aria-multiline` is `true`), Return or Enter key inserts a line break. - -### JavaScript features - -All features associated with any and all properties and states must be maintained, and forms submission on enter or return on a single line textbox needs to be handled. - -- Focus event handler and aria-activedescendant attribute - - : If you are implementing a composite widget, such as a combobox composed of a text box and a listbox, you need to manage the `aria-activedescendant` attribute using a handler. Before using this technique, ensure that the browsers you need to target currently support it. See the [specification of aria-descendant](https://www.w3.org/TR/wai-aria-1.1/#aria-activedescendant) for further information. - -> [!NOTE] -> It is a better practice to use an {{HTMLElement("input")}} element with type="text", or a {{HTMLElement("textarea")}} element instead of the ARIA textbox role. When using either semantic element, the ARIA textbox role is not necessary. See [Notes on Using ARIA in HTML](https://www.w3.org/TR/aria-in-html/). - -## Possible effects on user agents and assistive technology - -When the `textbox` role is added to an element, or such an element becomes visible, the user agent should do the following: - -- Expose the element as having a textbox role in the operating system's accessibility API. -- Fire an accessible textbox event using the operating system's accessibility API if it supports it. - -Assistive technology products should listen for such an event and notify the user accordingly: - -- Screen readers should announce its label and role when focus first lands on a textbox. If it also contains content, this should be announced as with a regular textbox. -- Screen magnifiers may enlarge the textbox. - -> [!NOTE] -> Opinions may differ on how assistive technology should handle this technique. The information provided above is one of those opinions and may be experienced differently. - -## Examples - -### Example 1: Adding the role in the HTML code for single line input - -The snippet below shows how the textbox role is added directly into the HTML source code. - -```html -<div role="textbox" contenteditable="true"></div> -``` - -### Example 2: Adding the role in the HTML code for multi-line input - -The snippet below shows how the textbox role is added directly into the HTML source code. - -```html -<div role="textbox" contenteditable="true" aria-multiline="true"></div> -``` - -## Best practices - -- Be sure to add the `contenteditable="true"` attribute to the HTML element to which this role is applied. Do so even if you set `aria-readonly` to `true`; in this way, you communicate that the content would be editable if it were not read-only. - -## See also - -- [ARIA: search role](/en-US/docs/Web/Accessibility/ARIA/Roles/search_role) diff --git a/files/en-us/web/accessibility/aria/roles/timer_role/index.md b/files/en-us/web/accessibility/aria/roles/timer_role/index.md deleted file mode 100644 index a014c79e261c120..000000000000000 --- a/files/en-us/web/accessibility/aria/roles/timer_role/index.md +++ /dev/null @@ -1,49 +0,0 @@ ---- -title: "ARIA: timer role" -slug: Web/Accessibility/ARIA/Roles/timer_role -page-type: aria-role -spec-urls: https://w3c.github.io/aria/#timer ---- - -{{AccessibilitySidebar}} - -The **`timer`** role indicates to assistive technologies that an element is a numerical counter listing the amount of elapsed time from a starting point or the remaining time until an end point. Assistive technologies will not announce updates to a timer as it has an implicit [aria-live](https://www.w3.org/TR/wai-aria/#aria-live) value of `off`. - -```html -<div role="timer" id="eggtimer">0</div> -``` - -This defines this `div` element as a timer with no remaining time. - -## Description - -The `timer` role indicates to assistive technologies that this part of the web content is a live region containing a timer listing the time remaining or elapsed time. A timer's inner text should be an updating current time measurement. While the value does not necessarily need to be machine parsable, it should continuously update at regular intervals unless the timer is paused or reaches its end-point. - -Along with [`alert`](/en-US/docs/Web/Accessibility/ARIA/Roles/alert_role), [`log`](/en-US/docs/Web/Accessibility/ARIA/Roles/log_role), [`marquee`](/en-US/docs/Web/Accessibility/ARIA/Roles/marquee_role), and [`status`](/en-US/docs/Web/Accessibility/ARIA/Roles/status_role) the `timer` role is a live region and can be modified by [live region](/en-US/docs/Web/Accessibility/ARIA/ARIA_Live_Regions) attributes. - -### Associated WAI-ARIA roles, states, and properties - -- [`aria-label`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-label) or [`aria-labelledby`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-labelledby) - - - : Some screen readers announce the name of a timer element before announcing its contents. If a name is visible, reference it using `aria-labelledby`. Including an `aria-label` provides a method for prefacing the visible content of a timer element with text that is not displayed when a screen reader reads the content. Naming a timer is not required so if nothing is appropriate both these attributes can be omitted. - -- [`aria-live`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-live) - - - : Elements with the role `timer` have an implicit [aria-live](https://www.w3.org/TR/wai-aria/#aria-live) value of `off`. - -## Accessibility concerns - -If a time limit needs to be in place, for example, for security reasons, the user should have the option to turn it off or extend it. This restriction does not apply if the time limit is due to a live event, such as an auction or a game, or if the time to complete the form is essential for a valid submission. - -## Specifications - -{{Specifications}} - -## See also - -- [ARIA: `alert` role](/en-US/docs/Web/Accessibility/ARIA/Roles/alert_role) -- [ARIA: `log` role](/en-US/docs/Web/Accessibility/ARIA/Roles/log_role) -- [ARIA: `marquee` role](/en-US/docs/Web/Accessibility/ARIA/Roles/marquee_role) -- [ARIA: `status` role](/en-US/docs/Web/Accessibility/ARIA/Roles/status_role) -- [ARIA live regions](/en-US/docs/Web/Accessibility/ARIA/ARIA_Live_Regions) -- [`timer` example on CodePen](https://codepen.io/heydon/pres/NGgNjZ) by Heydon Pickering diff --git a/files/en-us/web/accessibility/aria/roles/toolbar_role/index.md b/files/en-us/web/accessibility/aria/roles/toolbar_role/index.md deleted file mode 100644 index c3bf819e48f02fc..000000000000000 --- a/files/en-us/web/accessibility/aria/roles/toolbar_role/index.md +++ /dev/null @@ -1,104 +0,0 @@ ---- -title: "ARIA: toolbar role" -slug: Web/Accessibility/ARIA/Roles/toolbar_role -page-type: aria-role -spec-urls: - - https://w3c.github.io/aria/#toolbar - - https://www.w3.org/WAI/ARIA/apg/patterns/toolbar/examples/toolbar/ ---- - -{{AccessibilitySidebar}} - -The `toolbar` role defines the containing element as a collection of commonly used function buttons or controls represented in a compact visual form. - -## Description - -A toolbar is a collection of commonly used controls, such as buttons or checkboxes, grouped together in a compact visual form. The `toolbar` role can be used to communicate the presence and purpose of such a grouping to screen reader users and can help reduce the number of tab stops for keyboard users. Only use the `toolbar` role to group 3 or more controls. - -The toolbar is commonly a subset of functions found in a `menubar` as a way to reduce user effort. If you have more than one toolbar in a menubar, each toolbar requires a label; which you can include with [`aria-labelledby`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-labelledby) or [`aria-label`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-label). - -When creating a toolbar, you need to implement focus management and keyboard interactions within the toolbar, handling when the same keyboard interactions is used both in the toolbar and in included native control. The <kbd>Left Arrow</kbd> and <kbd>Right Arrow</kbd> should be used to navigate between the controls within a horizontal tool bar. The <kbd>Up Arrow</kbd> and <kbd>Down Arrow</kbd> should be used if the toolbar is vertical — in which case you also want to include the `aria-orientation="vertical"` — or, in a horizontal toolbar, can be reserved for operating controls, such as spin buttons that require vertical arrow keys to operate. - -Avoid including controls whose operation requires arrow keys used for toolbar navigation. If you must include such a control, make it the last control in the toolbar. For example, in a horizontal toolbar, a textbox could be included as the last element. - -If any of the otherwise interactive elements within the toolbar are temporarily disabled, consider letting them remain focusable so screen reader users can be made aware of their presence. - -### Associated WAI-ARIA roles, states, and properties - -- [`aria-orientation`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-orientation) - - - : Elements with the role toolbar have an implicit `aria-orientation` value of horizontal. - -- [`aria-labelledby`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-labelledby) / [`aria-label`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-label) - - : If the toolbar has a visible label, reference it by ID with the `aria-labelledby` attribute. Otherwise, provide an `aria-label`. If there is more than one toolbar in a menu, naming is required. - -### Keyboard interactions - -Implement focus management so the keyboard tab sequence includes one stop for the toolbar and arrow keys move focus among the controls in the toolbar. - -- <kbd>Tab</kbd> and <kbd>Shift + Tab</kbd> - - - : Move focus into and out of the toolbar. When focus moves into a toolbar: - - - If focus is moving into the toolbar for the first time, focus is set on the first control that is not disabled. - - If the toolbar has previously contained focus, focus is optionally set on the control that last had focus. Otherwise, it is set on the first control that is not disabled. - -- <kbd>Home</kbd> (Optional) - - - : Moves focus to first element. - -- <kbd>End</kbd> (Optional) - - : Moves focus to last element. - -#### Horizontal toolbar - -Elements with the role toolbar have an implicit `aria-orientation` value of horizontal. If the toolbar indeed has this orientation, the following keyboard interactions need to be implemented: - -- <kbd>Left Arrow</kbd> (For a horizontal toolbar (the default) - - - : Moves focus to the previous control. Optionally, focus movement may wrap from the first element to the last element. - -- <kbd>Right Arrow</kbd> (For a horizontal toolbar (the default) - - : Moves focus to the next control. Optionally, focus movement may wrap from the last element to the first element. - -In toolbars with multiple rows of controls, allow the left and right arrows to wraps from row to row, leaving the option of reserving vertical arrow keys for operating controls, such as navigating among radios buttons, or incrementing/decrementing a numeric spinner. - -#### Vertical toolbar - -If the toolbar is vertical, ensure `aria-orientation="vertical"` is set, and the following keyboard interactions are implemented: - -- <kbd>Down Arrow</kbd> (For a horizontal toolbar (the default) - - - : Moves focus to the previous control. Optionally, focus movement may wrap from the first element to the last element. - -- <kbd>Up Arrow</kbd> (For a horizontal toolbar (the default) - - : Moves focus to the next control. Optionally, focus movement may wrap from the last element to the first element. - -### Required JavaScript features - -Implement focus management so the keyboard tab sequence includes one stop for the toolbar and arrow keys move focus among the controls in the toolbar. When tabbing into the toolbar, focus returns to the control that last had focus. - -While the toolbar element itself does not receive focus, focus on movement into, out of, and within the toolbar has to be managed. On load, the first element in the tabbing sequence within the toolbar has `tabindex="0"` with `tabindex="-1"` set on all other focusable elements within the toolbar. Depending on the [keyboard interaction], the element receiving focus gets set to `tabindex="0"` and the element that just lost focus gets switched back to `tabindex="-1"`. Set focus, `element.focus()`, on the element that has `tabindex="0"`. This is called "roving tabindex". A benefit of using roving tabindex to manage focus is that the browser will scroll the newly focused element into view. - -If the design calls for a specific element to be focused the next time the user moves focus into the toolbar with <kbd>Tab</kbd> or <kbd>Shift + Tab</kbd>, check if that target element has `tabindex="0"` when toolbar loses focus. - -When the toolbar has focus within it, provide visual cues. When an element within the toolbar has focus, a visual cue must be included on both the toolbar itself - to help the toolbar supports directional navigation with the arrow keys - and the control that has focus. The CSS pseudoclasses of `:focus` and `:focus-within` can be used to target both elements. - -## Examples - -[Toolbar example from <abbr>W3C</abbr>, the World Wide Web Consortium](https://www.w3.org/TR/wai-aria-practices-1.2/examples/toolbar/toolbar.html) - -## Accessibility concerns - -Avoid including controls whose operation requires arrow keys used for toolbar navigation (right and left arrows, or top and bottom for vertical toolbars). If you must include such a control, make it the last control in the toolbar. For example, in a horizontal toolbar, a textbox could be included as the last element. - -If any of the otherwise interactive elements within the toolbar are disabled, consider letting them remain focusable so screen reader users can be made aware of their presence. - -## Specifications - -{{Specifications}} - -## See also - -- [The CSS `:focus` pseudoclass](/en-US/docs/Web/CSS/:focus) -- [The CSS `:focus-within` pseudoclass](/en-US/docs/Web/CSS/:focus-within) diff --git a/files/en-us/web/accessibility/aria/roles/tooltip_role/index.md b/files/en-us/web/accessibility/aria/roles/tooltip_role/index.md deleted file mode 100644 index 40b91f6a77d9144..000000000000000 --- a/files/en-us/web/accessibility/aria/roles/tooltip_role/index.md +++ /dev/null @@ -1,119 +0,0 @@ ---- -title: "ARIA: tooltip role" -slug: Web/Accessibility/ARIA/Roles/tooltip_role -page-type: aria-role -spec-urls: https://w3c.github.io/aria/#tooltip ---- - -{{AccessibilitySidebar}} - -A `tooltip` is a contextual text bubble that displays a description for an element that appears on pointer hover or keyboard focus. - -## Description - -Tooltips provide contextual information about an element when that owning element receives focus or is hovered over, but is otherwise not visible on the page. The tooltip is displayed automatically, after a brief delay; the user does not request it. While a tooltip can be placed on any content, they generally are tips for tools or controls, such as providing additional content for icons that have brief labels (or no labels at all, which is not accessible!). - -A tooltip typically becomes visible, after a short delay of generally one to five seconds, in response to a mouse hover, or after the owning element receives keyboard focus. Just as it is opened automatically, without user request, it is closed automatically when the focus is lost or on mouse out. It must stay open when the mouse moves over the tooltip itself, and should also close when the user presses the <kbd>Escape</kbd> key. - -Because the tooltip itself never receives focus and is not in the tabbing order, a tooltip can not contain interactive elements like links, inputs, or buttons. - -The tooltip is not the appropriate role for the more information "i" icon, ⓘ. A tooltip is directly associated with the owning element. The ⓘ isn't 'described by' detailed information; the tool or control is. - -The use of the ARIA `tooltip` role is a supplement to the normal browser tooltip behavior. An example of a native browser tooltip is the way some browsers display an element's [`title` attribute](/en-US/docs/Web/HTML/Global_attributes/title) on long mouse hover. One cannot activate this feature through either keyboard focus or through touch interaction, making this feature inaccessible. If the information is important enough to include as a tooltip or title, consider including it in visible text. - -Elements with the `tooltip` role should be referenced through the use of [`aria-describedby`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-describedby) before or when the tooltip is displayed. The `aria-describedby` attribute is on the owning element, not on the tooltip. - -The tooltip is not considered a popup in terms of the [`aria-haspopup`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-haspopup) property on the owning element, which is why we used "text bubble" in the introductory definition. - -Though a tooltip may appear and disappear, as its appearance is automatic and not intentionally controlled by the user, the [`aria-expanded`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-expanded) role is not supported. - -The accessible name of a tooltip can come from the contents. While, in theory, they could come from an [`aria-label`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-label) or [`aria-labelledby`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-labelledby), in most cases, using ARIA properties to provide a tooltip with an accessible name is not recommended. - -Tooltips provide additional information, generally with no direct interaction on the tooltip itself. They are generally associated with the content they're defining via an [`aria-describedby`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-describedby) with the `id` of the primary element. Therefore, if the tooltip has an accessible name explicitly set, that name is exposed as the primary element's description rather than the contents of the tooltip, meaning the tooltip contents may never be discovered by a screen reader user. - -### Associated WAI-ARIA roles, states, and properties - -- The element that serves as the tooltip container has `role="tooltip"` set. -- The element that triggers the tooltip references the tooltip element with [`aria-describedby`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-describedby). - -### Keyboard interactions - -- <kbd>Escape</kbd> - - : Closes the tooltip - -The tooltip should appear on focus or when the element is hovered on, without additional interaction. It should disappear automatically when the focus on the owning element is lost or the mouse is moved outside the owning element and the tooltip. While the tooltip does not receive focus, the <kbd>Escape</kbd> should close it if it is open. - -### Required JavaScript features - -- The tooltip is displayed and disappears via keyboard focus and removal of focus and by the mouse events - mousing over and mousing out. - -- The tooltip never receives focus. Focus stays on the owning element. - -- The tooltip can be hidden with the <kbd>Escape</kbd> key - -- The tooltip stays open when hovered - -- The tooltip is only hidden via JavaScript and CSS selectors. If JavaScript is not available the tooltip is shown. - -## Examples - -```html -<label for="password">Password:</label> -<input aria-describedby="passwordrules" id="password" type="password" /> -<div role="tooltip" id="passwordrules"> - <p>Password Rules:</p> - <ul> - <li>Minimum of 8 characters</li> - <li> - Include at least one lowercase letter, one uppercase letter, one number - and one special character - </li> - <li>Unique to this website</li> - </ul> -</div> -``` - -The tooltip can be instantiated with CSS. Change the class name with JavaScript to a class that hides the tooltip if the user hits the <kbd>Escape</kbd> key. - -```css -[role="tooltip"], -.hide-tooltip.hide-tooltip.hide-tooltip + [role="tooltip"] { - visibility: hidden; - position: absolute; - top: 2rem; - left: 2rem; - background: black; - color: white; -} -[aria-describedby]:hover, -[aria-describedby]:focus { - position: relative; -} -[aria-describedby]:hover + [role="tooltip"], -[aria-describedby]:focus + [role="tooltip"] { - visibility: visible; -} -``` - -The above hides the tooltip with CSS in the default state or if the `hide-tooltip` class has been added with JavaScript (when the user hit <kbd>Escape</kbd>), with high specificity to ensure the tooltip doesn't show. When the owning element receives focus, it gets positioned relatively and the tooltip becomes visible. - -## Accessibility concerns - -If the information is important enough for a tooltip, isn't it important enough to always be visible? - -The tooltip must stay open when hovered, even if that technically means the mouse moves out of the owning element. As content which appears on hover can be difficult or impossible to perceive if a user is required to keep their mouse pointer over the trigger, [WCAG 1.4.13](/en-US/docs/Web/Accessibility/Understanding_WCAG/Perceivable#guideline_1.4_make_it_easier_for_users_to_see_and_hear_content_including_separating_foreground_from_background) states that content made visible should be persistent, meaning it should not disappear without user action. - -## Best Practices - -Instead of using tooltips and hiding important information, consider writing clear, succinct, always visible descriptions. If you have space, don't use tooltips or toggletips. Just provide clear labels and sufficient body text. - -## Specifications - -{{Specifications}} - -## See also - -- [The `dialog` role](/en-US/docs/Web/Accessibility/ARIA/Roles/dialog_role) -- [CSS: `:focus` pseudoclass](/en-US/docs/Web/CSS/:focus) -- [Tooltips & Toggletips](https://inclusive-components.design/tooltips-toggletips/) by Heydon Pickering -- [Understanding SC 1.4.13:Content on Hover or Focus (WCAG Level AA)](https://www.w3.org/WAI/WCAG21/Understanding/content-on-hover-or-focus.html) diff --git a/files/en-us/web/accessibility/aria/roles/tree_role/index.md b/files/en-us/web/accessibility/aria/roles/tree_role/index.md deleted file mode 100644 index 48e5275664a858f..000000000000000 --- a/files/en-us/web/accessibility/aria/roles/tree_role/index.md +++ /dev/null @@ -1,241 +0,0 @@ ---- -title: "ARIA: tree role" -slug: Web/Accessibility/ARIA/Roles/tree_role -page-type: aria-role -spec-urls: - - https://w3c.github.io/aria/#tree - - https://www.w3.org/WAI/ARIA/apg/patterns/treeview/examples/treeview-navigation/ ---- - -{{AccessibilitySidebar}} - -A `tree` is a widget that allows the user to select one or more items from a hierarchically organized collection. - -## Description - -A `tree` widget is a hierarchical list with parent and child nodes that can expand and collapse. Any item in the hierarchy may have child tree items, set with [`role="treeitem"`](/en-US/docs/Web/Accessibility/ARIA/Roles/treeitem_role). Tree items that have children can be expanded or collapsed, showing and hiding their children. - -An example of a `tree` is a file system selection user interface: a tree view displaying folders and files. Folder items can be expanded to reveal the contents of the folder — which may be files, folders, or both — and collapsed, hiding its contents. - -ARIA tree views are navigated primarily with arrow keys on the keyboard instead of the <kbd>Tab</kbd>. This form of navigation is not common for most browser content, though normal and expected for native applications. For this reason, before creating a tree view, consider alternative options to address the functionality you need. - -> [!WARNING] -> Tree views use navigation more similar to native applications than to web applications. For this reason, consider alternative options to address the functionality you need before creating a tree view. - -### Single and multiple select trees - -Trees can be "single-select", allowing users to choose just one item for an action, or "multi-select", where users are able to select more than one item for an action. In multi-select trees, the `tree` has [`aria-multiselectable`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-multiselectable) set to true. Otherwise, `aria-multiselectable` is either set to `false` or the default value of `false` is implied. In both cases, to be keyboard accessible, focus must be managed for all tree descendants. - -In some implementations of single-select tree, the focused item also has a selected state; this is known as "selection follows focus". When a single-select tree receives focus, if none of the tree items are selected before the tree receives focus, focus is set on the first node. If a tree item is selected before the tree receives focus, focus is set on the selected tree item. In single-select trees, [`aria-selected`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-selected) is set to `true` for the selected tree items and it is not present on any other tree item in the tree. - -In multi-select trees, all selected tree items have `aria-selected="true"` set and all tree item nodes that are selectable but not currently selected have `aria-selected="false"` set. Do not includes the `aria-selected` attribute on tree items that are not selectable. - -When a multi-select tree receives focus, if none of the tree items are selected before the tree receives focus, focus is set on the first tree item. If one or more tree items are selected before the tree receives focus, focus is set on the first selected node. - -In multi-select trees, the selected state is always independent of the focus. For example, in a typical file system navigator, the user can move focus to select any number of files for an action, such as copy or move. The visual design should make it clear which items are selected and which item has focus. - -### Tree hierarchy - -In a tree view, the `tree` node is the root node; it can have child, grandchild, and further descendant `treeitem` nodes. - -Each element serving as a tree node has role `treeitem`, except for the root tree node which has a role of `tree`. A `tree` does not have a parent `tree` node - it is the root node. If a node is both nested in a tree and has descendant tree items, then it has the role `treeitem` and the [`aria-expanded`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-expanded) attribute; `aria-expanded="false"` is set when the node is in a closed state, `aria-expanded="true"` is set when the node is in an open state. - -`treeitem` nodes can be direct children of the `tree` root node, nested within a `treeitem` node, or, optionally nested in a [`group`](/en-US/docs/Web/Accessibility/ARIA/Roles/group_role) element, which, when nested in a `tree` is an expandable collection of treeitem elements. - -Do not include `aria-expanded` on end nodes — those without tree item children — as that would incorrectly describe the node as a parent node to assistive technologies. - -### DOM placement and presence - -All treeitems are contained in or owned by an element with role `tree`. If there are any tree items that are not direct descendants of the `tree` in the markup, include [`aria-owns`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-owns) on the owning tree container to include elements that are not DOM children of the container. These non-child owned elements will appear in the reading order in the sequence they are referenced and after any tree items that are DOM children. Scripts that manage focus need to ensure the visual focus order matches this assistive technology reading order. - -If the complete set of available nodes is not present in the DOM due to dynamic loading as the user moves focus in or scrolls the tree, each node has [`aria-level`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-level), [`aria-setsize`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-setsize), and [`aria-posinset`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-posinset) specified. - -### Accessible name - -The `tree` must be provided with an accessible name. Either reference a visible label referenced with [`aria-labelledby`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-labelledby) or specify a label with [`aria-label`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-label). - -### Menu orientation - -Elements with the role `tree` have an implicit [`aria-orientation`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-orientation) value of vertical. If the tree element is horizontally oriented, include `aria-orientation="horizontal"`. - -### Associated WAI-ARIA roles, states, and properties - -- [`role="treeitem"`](/en-US/docs/Web/Accessibility/ARIA/Roles/treeitem_role) - - : An item in a tree. -- [`role="group"`](/en-US/docs/Web/Accessibility/ARIA/Roles/group_role) - - : An expandable collection of tree items. -- [`aria-labelledby`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-labelledby) - - : Identifies the element (or elements) that labels the `tree` providing the required accessible name when a visible label is present. Otherwise use `aria-label`. -- [`aria-label`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-label) - - : Defines a string value that labels the `tree` when no visible label is present. -- [`aria-orientation`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-orientation) - - : indicates whether the tree orientation is horizontal or vertical; defaults to `vertical` if omitted. -- [`aria-multiselectable`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-multiselectable) - - : When set to true, indicates the user may select more than one tree item from the tree's current selectable descendants. - -### Keyboard interactions - -For a vertically oriented `tree`, which is the default orientation: - -<table> -<tr> -<td><kbd>Right arrow</kbd></td> -<td> -<ul> -<li>When focus is on a closed node, opens the node; focus does not move. -<li>When focus is on an open node, moves focus to the first child node. -<li>When focus is on an end node (a tree item with no children), does nothing. -</td> -</tr> -<tr> -<td><kbd>Left arrow</kbd></td> -<td> -<ul> -<li>When focus is on an open node, closes the node. -<li>When focus is on a child node that is also either an end node or a closed node, moves focus to its parent node. -<li>When focus is on a closed tree, does nothing. -</td> -</tr> -<tr> -<td><kbd>Down Arrow</kbd></td> -<td> Moves focus to the next node that is focusable without opening or closing a node. -</td> -</tr> -<tr> -<td><kbd>Up Arrow</kbd></td> -<td> Moves focus to the previous node that is focusable without opening or closing a node. -</td> -</tr> -<tr> -<td><kbd>Home</kbd></td> -<td> Moves focus to the first node in the tree without opening or closing a node. -</td> -</tr> -<tr> -<td><kbd>End</kbd></td> -<td> Moves focus to the last node in the tree that is focusable without opening the node. -</td> -</tr> -<tr> -<td><kbd>Enter</kbd></td> -<td>Performs the default action of the currently focused node. For parent nodes, it opens or closes the node. In single-select trees, if the node has no children, selects the current node if not already selected (which is the default action). -</td> -</tr> -<tr> -<td>Type a character*</td> -<td> -<ul> -<li>Focus moves to the next node with a name that starts with the typed character. -<li>If multiple characters are typed in rapid succession, focus moves to the next node with a name that starts with the string of characters typed. -</td> -</tr> -<tr> -<td> -<kbd>*</kbd> (Optional)</td> -<td> Expands all siblings that are at the same level as the current node. -</td> -</tr> -</table> - -\* Type-ahead is recommended for all trees, especially for trees with more than 7 root nodes - -### Multi-select keyboard interactions - -There are two interaction models for multi-select trees: While you can require that users press a modifier key, such as <kbd>Shift</kbd> or <kbd>Control</kbd> while navigating the list in order to avoid losing selection states, the model that does not require the user to hold a modifier key is recommended. - -#### Recommended multi user select model - -<table> -<tr> -<td><kbd>Space</kbd></td> -<td> Toggles the selection state of the focused node. -</td> -</tr> -<tr> -<td><kbd>Shift + Down Arrow</kbd> (Optional)</td> -<td> Moves focus to and toggles the selection state of the next node. -</td> -</tr> -<tr> -<td><kbd>Shift + Up Arrow</kbd> (Optional)</td> -<td> Moves focus to and toggles the selection state of the previous node. -</td> -</tr> -<tr> -<td><kbd>Shift + Space</kbd> (Optional)</td> -<td> Selects contiguous nodes from the most recently selected node to the current node. -</td> -</tr> -<tr> -<td><kbd>Control + Shift + Home</kbd> (Optional)</td> -<td> Selects the node with focus and all nodes up to the first node. Optionally, moves focus to the first node. -</td> -</tr> -<tr> -<td><kbd>Control + Shift + End</kbd> (Optional)</td> -<td> Selects the node with focus and all nodes down to the last node. Optionally, moves focus to the last node. -</td> -</tr> -<tr> -<td><kbd>Control + A</kbd> (Optional)</td> -<td> Selects all nodes in the tree. Optionally, if all nodes are selected, it can also unselect all nodes.</td> -</tr> -</table> - -#### Alternative multi-selection model - -The alternative multi-selection model is a modifier key model in which moving focus without holding a modifier key such as <kbd>Shift</kbd> or <kbd>Control</kbd> unselects all selected nodes except for the focused node: - -<table> -<tr> -<td><kbd>Shift + Down Arrow</kbd></td> -<td> Moves focus to and toggles the selection state of the next node. -</td> -</tr> -<tr> -<td><kbd>Shift + Up Arrow</kbd></td> -<td> Moves focus to and toggles the selection state of the previous node. -</td> -</tr> -<tr> -<td><kbd>Control + Down Arrow</kbd></td> -<td> Without changing the selection state, moves focus to the next node. -</td> -</tr> -<tr> -<td><kbd>Control + Up Arrow</kbd></td> -<td> Without changing the selection state, moves focus to the previous node. -</td> -</tr> -<tr> -<td><kbd>Control + Space</kbd></td> -<td> Toggles the selection state of the focused node. -</td> -</tr> -<tr> -<td><kbd>Shift + Space</kbd> (Optional)</td> -<td> Selects contiguous nodes from the most recently selected node to the current node. -</td> -</tr> -<tr> -<td><kbd>Control + Shift + Home</kbd> (Optional)</td> -<td> Selects the node with focus and all nodes up to the first node. Optionally, moves focus to the first node. -</td> -</tr> -<tr> -<td><kbd>Control + Shift + End</kbd> (Optional)</td> -<td> Selects the node with focus and all nodes down to the last node. Optionally, moves focus to the last node. -</td> -</tr> -<tr> -<td><kbd>Control + A</kbd> (Optional)</td> -<td> Selects all nodes in the tree. Optionally, if all nodes are selected, it can also unselect all nodes. -</td> -</tr> -</table> - -## Specifications - -{{Specifications}} - -## See also diff --git a/files/en-us/web/accessibility/aria/roles/treegrid_role/index.md b/files/en-us/web/accessibility/aria/roles/treegrid_role/index.md deleted file mode 100644 index edff99299f022cb..000000000000000 --- a/files/en-us/web/accessibility/aria/roles/treegrid_role/index.md +++ /dev/null @@ -1,156 +0,0 @@ ---- -title: "ARIA: treegrid role" -slug: Web/Accessibility/ARIA/Roles/treegrid_role -page-type: aria-role -spec-urls: - - https://w3c.github.io/aria/#treegrid - - https://www.w3.org/WAI/ARIA/apg/patterns/treegrid/examples/treegrid-1/ ---- - -{{AccessibilitySidebar}} - -The `treegrid` role identifies an element as being grid whose rows can be expanded and collapsed in the same manner as for a `tree`. - -## Description - -A `treegrid` is a hierarchical data grid, or table, consisting of tabular information that is editable or interactive. A `treegrid` is a combination of the [`tree`](/en-US/docs/Web/Accessibility/ARIA/Roles/tree_role) and [`grid`](/en-US/docs/Web/Accessibility/ARIA/Roles/grid_role) roles. Like a `grid`, the `treegrid` is made up of rows, columns, and gridcells. Like a `tree`, parent nodes in a `treegrid` are expandable and collapsible. -The `treegrid` widget contains one or more [`row`](/en-US/docs/Web/Accessibility/ARIA/Roles/row_role) elements, optionally with [`rowgroup`](/en-US/docs/Web/Accessibility/ARIA/Roles/rowgroup_role) elements grouping the rows. Each row, in turn, contains one or more cells. Each cell is either a DOM descendant of or owned by a row element and is either a [`columnheader`](/en-US/docs/Web/Accessibility/ARIA/Roles/columnheader_role), [`rowheader`](/en-US/docs/Web/Accessibility/ARIA/Roles/rowheader_role), or [`gridcell`](/en-US/docs/Web/Accessibility/ARIA/Roles/gridcell_role) element, with the `gridcell` role being used for all cells that do not contain column or row header information. - -A `row` that can be expanded or collapsed to show or hide a set of child rows is a **parent row**. Each parent row has the [`aria-expanded`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-expanded) state set on either the row element or on a cell contained in the row. - -The `aria-expanded` state is set to `true` when the child rows are displayed and set to `false` when the child rows are hidden. Elements that do not control display of child rows should not have the `aria-expanded` attribute because the presence of the attribute indicates to assistive technologies that the element with the attribute is a parent. - -When your grid UI calls for rows supporting `aria-expanded` or if your grid requires supporting [`aria-posinset`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-posinset), [`aria-setsize`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-setsize), or [`aria-level`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-level), use `treegrid` and not `grid`. - -Each `row` or `gridcell` in a row should be keyboard focusable, and keyboard focus for all these tree grid descendants must be managed. The exception to this rule is column header cells which aren't required to be focusable if they do not provide functionality such as sort or filter. Every row and cell should either contain a focusable element or be focusable itself, regardless of whether individual cell content is editable or interactive. - -### Single and multi-select treegrids - -If the `treegrid` allows the user to choose just one item for an action, then it is known as a **single-select** treegrid. In single-select treegrids, the item with focus also has a selected state set with [`aria-selected`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-selected). - -If the treegrid supports selection of more than one row or cell, it is a **multi-select** treegrid. In the multi-select treegrid, the selected state is independent of the focus. The visual design and assistive technologies must distinguish between items that are selected and the item that has focus. - -For multi-select treegrids, include [`aria-multiselectable="true"`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-multiselectable) on the element with the `treegrid` role. All selected rows or cells have [`aria-selected`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-selected) set to true. All rows and cells that are selectable but not currently selected have `aria-selected` set to `false`. Don't include the `aria-selected` attribute on rows and cells that are not individually selectable as the presence of the attribute indicates to assistive technologies that the row or cell is selectable. - -### Orphan rows - -In cases where a child `row` or `rowgroup` is not nested within the `treegrid` in the DOM, the [`aria-owns`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-owns) attribute, referencing all of the IDs of the non-descendant children must be set on the `treegrid` element. If rows or cells are included in a treegrid via `aria-owns`, they will be presented to assistive technologies after the DOM descendants of the `treegrid` element unless the grid's actual DOM descendants are also included in the `aria-owns` attribute. - -### Treegrids with dynamically loaded content - -If some rows or columns are not in the DOM and are dynamically loaded when scrolling, [`aria-colcount`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-colcount), [`aria-rowcount`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-rowcount), [`aria-colindex`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-colindex) and [`aria-rowindex`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-rowindex) come into play. The `aria-colcount` and `aria-rowcount` properties get set on the `treegrid`. The values being the total number of columns and rows of the fully loaded grid, respectively. The indexes for each row and column get set on individual cells, not on the `treegrid` element. - -### A treegrid's accessible name, description, and focus - -The element with the role of `treegrid` must have an accessible name. If an appropriate label is visible in the content, provide the name via [`aria-labelledby`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-labelledby). In other words, if there is an element in the user interface that serves as a label for the treegrid, include `aria-labelledby` as an attribute on the element with the role of `treegrid`, and set the value of the attribute to the `id` of the labelling element or elements. If no visible label is present, use [`aria-label`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-label) instead. Not both. - -If the content includes a caption or description for the `treegrid`, include [`aria-describedby`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-describedby) on the `treegrid` element with the attribute value being the `id` of the element containing the description. - -If the `treegrid` container itself receives focus, the value of its [`aria-activedescendant`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-activedescendant) property should reference the [`id`](/en-US/docs/Web/HTML/Global_attributes/id) of the selected `row`, `columnheader`, `rowheader` or `gridcell`, unless roving tabindex is used to manage focus between those roles, in which case `aria-activedescendant` should not be used. - -If the `treegrid` is disabled, make that disabled state visually apparent, programmatically enforced, and include the [`aria-disabled`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-disabled) attribute on the `treegrid` itself to inform assistive technologies of its disabled state. - -### Treegrid sorting - -If the treegrid provides sort functions, the [`aria-sort`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-sort) attribute is included on relevant header cell elements, not on the grid itself. - -### Treegrid menus - -If the `treegrid` has an attached [`menu`](/en-US/docs/Web/Accessibility/ARIA/Roles/menu_role) that opens when right clicked, include [`aria-haspopup="true"`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-haspopup) on the `treegrid` element. This informs assistive technologies that the `treegrid` has an associated popup. The ability for both keyboard and pointer device users to open and set focus in the menu must be added with JavaScript. - -### Read-only treegrids - -By default, treegrids are assumed to be editable. If a tree grid is not editable, use the [`aria-readonly`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-readonly) attribute to inform assistive technologies the `treegrid` is readonly. The attribute value, when set on the element with the `treegrid` role, propagates down to all `columnheader`, `rowheader`, and `gridcell` elements. That global value can be overridden for individual `gridcell` elements by including `aria-readonly` on individual tree grid element descendants. - -Like all ARIA attributes, adding `aria-readonly` only informs assistive technologies that the content is or is not editable, but it does nothing to enable or disable interactivity. That must be done with HTML's global [`contenteditable`](/en-US/docs/Web/HTML/Global_attributes/contenteditable) attribute or with JavaScript. - -### Associated WAI-ARIA roles, states, and properties - -- [`row`](/en-US/docs/Web/Accessibility/ARIA/Roles/row_role) role - - : A row of cells within a tabular structure, optionally within a `rowgroup`. Contains one or more rows of grid cells, column headers, or row headers. -- [`rowgroup`](/en-US/docs/Web/Accessibility/ARIA/Roles/rowgroup_role) role - - : A group of [rows](/en-US/docs/Web/Accessibility/ARIA/Roles/row_role) within a tabular structure. -- [`gridcell`](/en-US/docs/Web/Accessibility/ARIA/Roles/gridcell_role) role - - : Intended to mimic the functionality of the HTML {{HTMLElement('td')}} element, is found in `grid` and `treegrid` roles and must be the direct child of a `row`. -- [columnheader](/en-US/docs/Web/Accessibility/ARIA/Roles/columnheader_role) role - - : A cell in a row containing header information for a column, similar to the native {{HTMLElement('th')}} element with column scope -- [rowheader](/en-US/docs/Web/Accessibility/ARIA/Roles/rowheader_role) role - - : A cell containing header information for a `row` within a tabular structure. -- [`aria-expanded`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-expanded) - - : For expandable items, the value is `true` or `false`. Also indicates that the item is expandable, so should not be present if the item cannot be expanded. -- [`aria-owns`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-owns) - - : Identifies a contextual relationship between a parent and its child elements when the DOM hierarchy cannot be used to represent the relationship -- [`aria-labelledby`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-labelledby) - - : Use this attribute to label the `treegrid`. The `aria-labelledby` attribute is generally the id of the element used to title the treegrid. -- [`aria-label`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-label) - - : A human-readable string value which identifies the `treegrid`. If there's a visible label, then `aria-labelledby` should be used instead. - -### Keyboard interactions - -Being able to move focus among rows and cells of the grid with a keyboard must be implemented in order to create an accessible treegrid. Moving focus into the grid may result in the first cell or the first row being focused. Whether focus goes to the next adjacent cell or the row depends on its content requirements, with some treegrids not providing focus to rows. - -The following keyboard interactions need to be supported when an element in the grid has received focus, e.g., after a user has moved focus to the grid with Tab. - -- <kbd>Enter</kbd> - - : If cell-only focus is enabled and focus is on the first cell with the `aria-expanded` property, opens or closes the child rows. Otherwise, performs the default action for the cell. -- <kbd>Tab</kbd> - - : If the row containing focus contains focusable elements such as an {{HTMLElement('input')}}, {{HTMLElement('button')}} or {{HTMLElement('a')}}, moves the focus to the next input in the row. If focus is on the last focusable element in the row, moves focus out of the treegrid widget to the next focusable element. -- <kbd>Right Arrow</kbd> - - : If focus is on a collapsed row, expand the row. If focus is on an expanded row or is on a row that does not have child rows, moves focus to the first cell in the row. If focus is on the right-most cell in a row, focus does not move. If focus is on any other cell, moves focus one cell to the right. -- <kbd>Left Arrow</kbd> - - : If focus is on an expanded row, collapses the row. If focus is on a collapsed row or on a row that does not have child rows, focus does not move. If focus is on the first cell in a row and row focus is supported, moves focus to the row. If focus is on the first cell in a row and row focus is not supported, focus does not move. If focus is on any other cell, moves focus one cell to the left. -- <kbd>Down Arrow</kbd> - - : If focus is on a row, moves focus one row down. If focus is on the last row, focus does not move. If focus is on a cell, moves focus one cell down. If focus is on the bottom cell in the column, focus does not move. -- <kbd>Up Arrow</kbd> - - : If focus is on a row, moves focus one row up. If focus is on the first row, focus does not move. If focus is on a cell, moves focus one cell up. If focus is on the top cell in the column, focus does not move. -- <kbd>Page Down</kbd> - - : If focus is on a row or cell, moves focus down a predetermined number of rows or cells. Usually, it moves down the equivalent of the height of the treegrid, scrolling so the bottom row in the currently visible set of rows becomes one of the first visible rows. If focus is in the last row, focus does not move. -- <kbd>Page Up</kbd> - - : If focus is on a row or cell, moves focus up an predetermined number of rows. Usually, it moves up the equivalent of the height of the treegrid, scrolling so the top row in the currently visible set of rows becomes one of the last visible rows. If focus is in the first row, focus does not move. -- <kbd>Home</kbd> <kbd>Control + Home</kbd> - - : If focus is on a row, moves focus to the first row. If focus is in the first row, focus does not move. If focus is on a cell, moves focus to the first cell in the row. If focus is in the first cell of the row, focus does not move. -- <kbd>End</kbd> <kbd>Control + End</kbd></td><td> - - : If focus is on a row, moves focus to the last row. If focus is in the last row, focus does not move. If focus is on a cell, moves focus to the last cell in the row. If focus is in the last cell of the row, focus does not move. If not all rows are present in the DOM, this can be used to focus on the last row present in the DOM, or on the last row available if the entire database were present in the DOM. - -If a treegrid supports selection of cells, rows, or columns, the following keys are commonly used for these functions. - -- <kbd>Control + Space</kbd> - - : If focus is on a row, selects all cells. If focus is on a cell, selects the column that contains the focus. -- <kbd>Shift + Space</kbd> - - : If focus is on a row, select the row. If focus is on a cell, select the row that contains the focus. If the treegrid includes a column with checkboxes for selecting rows, this key can also be used as a shortcut for checking the box when focus is not on the checkbox. -- <kbd>Control + A</kbd> - - : Selects all cells. -- <kbd>Shift + Right Arrow</kbd> - - : if focus is on a cell, extends selection one cell to the right. -- <kbd>Shift + Left Arrow</kbd> - - : if focus is on a cell, extends selection one cell to the left. -- <kbd>Shift + Down Arrow</kbd> - - : If focus is on a row, extends selection to all the cells in the next row. If focus is on a cell, extends selection one cell down. -- <kbd>Shift + Up Arrow</kbd> - - : If focus is on a row, extends selection to all the cells in the previous row. If focus is on a cell, extends selection one cell up. - -If navigation functions can dynamically add more rows or columns to the DOM, key events that move focus to the beginning or end of the grid, such as <kbd>control + End</kbd>, may move focus to the last row in the DOM rather than the last available row in the back-end data. - -While navigation keys, such as arrow keys, are moving focus from cell to cell, they are not available to do something like operate a combobox or move an editing caret inside of a cell. If this functionality is needed, see [Editing and Navigating Inside a Cell](https://www.w3.org/WAI/ARIA/apg/patterns/grid/#gridNav_inside). - -<!-- -### Required JavaScript features - -## Examples ---> - -## Accessibility concerns - -It is important for all cells to be able to receive or contain keyboard focus because screen readers are generally in application reading mode, rather than their document reading mode, when users are interacting with the grid. While in application mode, a screen reader user hears only focusable elements and content that labels focusable elements. If content can't receive focus, screen reader users may unknowingly overlook elements contained in the treegrid. - -<!-- -## Best Practices - -### Prefer HTML ---> - -## Specifications - -{{Specifications}} - -## See also diff --git a/files/en-us/web/accessibility/aria/roles/treeitem_role/index.md b/files/en-us/web/accessibility/aria/roles/treeitem_role/index.md deleted file mode 100644 index 71ccd9374f081ed..000000000000000 --- a/files/en-us/web/accessibility/aria/roles/treeitem_role/index.md +++ /dev/null @@ -1,238 +0,0 @@ ---- -title: "ARIA: treeitem role" -slug: Web/Accessibility/ARIA/Roles/treeitem_role -page-type: aria-role -spec-urls: - - https://w3c.github.io/aria/#treeitem - - https://www.w3.org/WAI/ARIA/apg/patterns/treeview/examples/treeview-navigation/ ---- - -{{AccessibilitySidebar}} - -A `treeitem` is an item in a `tree`. - -## Description - -A [`tree`](/en-US/docs/Web/Accessibility/ARIA/Roles/tree_role) is a hierarchical list with parent and child nodes that can expand and collapse. A `treeitem` is a node in a `tree`. The root of the tree is `tree`, but all tree nodes are `treeitem` elements, even if they themselves have nested `treeitem` nodes. - -An example of a `tree` is a file system selection user interface: a tree view displaying folders and files. Each folder and file is a `treeitem`. Folder items, which are `treeitem` elements, can be expanded to reveal the contents of the folder—which may be files, folders, or both, and are all `treeitems`—and collapsed, hiding its contents. - -In a tree hierarchy, the _root node_ has the role `tree`. All other nodes, other than the root node, have the role of `treeitem`, whether or not they have children. A `treeitem` that is a parent is a **parent node**. A `treeitem` that is not a parent is an _end node_. - -Tree items that have children can be expanded or collapsed, showing and hiding their children. A parent node that is expanded so its child nodes are visible is an **open node**. A parent node that is collapsed so the child nodes are not visible is a **closed node**. - -Each parent node contains or owns an element with role [`group`](/en-US/docs/Web/Accessibility/ARIA/Roles/group_role). A parent node is an expandable collection of `treeitem` elements. These child nodes are not direct descendants of the parent node: rather, they should be enclosed in an element with the `group` role. - -Each parent node should include the [`aria-expanded`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-expanded) attribute. It is set to `false` when closed `true` when open. End nodes should not have the `aria-expanded` attribute included as the presence of the attribute indicates to assistive technologies that the node is a parent. - -> [!NOTE] -> ARIA tree views use navigation more similar to native applications than to web applications and are navigated primarily with arrow keys on the keyboard instead of the <kbd>Tab</kbd>. This form of navigation is not common for most browser content, though normal and expected for native applications. For this reason, consider alternative options to address the functionality you need before creating a tree view. - -Any element with a `treeitem` role must be nested in, or owned by, an element with role `tree`. Tree items can be a child of `tree`, `treeitem`, or an element with role `group` that is contained in, or owned by, an element with role `tree` or `treeitem`. If a `treeitem` is not nested within a `tree`, or nested in a `group` that is owned by a `tree`, include the [`id`](/en-US/docs/Web/HTML/Global_attributes/id) of the `treeitem` in the [`aria-owns`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-owns) attribute value on the owning `tree`, `treeitem` or `group` element. - -Trees can be "single-select", allowing users to choose just one `treeitem` for an action, or "multi-select", where users are able to select more than one `treeitem` nodes for an action. In both cases, to be keyboard accessible, focus must be managed for all tree descendants. - -In single-select trees, only one treeitem can have [`aria-selected`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-selected) (or [`aria-checked`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-checked)) set to `true`. When a single-select tree receives focus, if no `treeitem` is selected before the tree receives focus, focus is set on the first `treeitem`. If a `treeitem` is selected before the tree receives focus, focus is set on the single `treeitem` that has `aria-selected="true"` set. - -All nodes that are selectable but not selected have either `aria-selected` or `aria-checked` set to `false`. If the tree contains nodes that are not selectable, do not include either `aria-selected` or `aria-checked`, as the presence of either attribute indicates to assistive technologies the node is selectable. - -No more than one node can be selected at a time unless the `tree` node has [`aria-multiselectable="true"`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-multiselectable) set. - -When a multi-select tree receives focus, if none of the tree items are selected before the tree receives focus, focus is set on the first `treeitem`. If one or more tree items are selected before the tree receives focus, focus is set on the first selected `treeitem`. - -In multi-select trees, all selected tree items have either `aria-selected="true"` (or `aria-checked="true"`) set. All tree item nodes that are selectable but not currently selected should have `aria-selected="false"` (or `aria-checked="false"`) set. - -Either `aria-selected` or `aria-checked` can be used to indicate selection for `treeitem` elements. Some user interfaces indicate selection with `aria-selected` in single-select trees and with `aria-checked` in multi-select trees. - -Using both `aria-selected` and `aria-checked` in the same `tree` is strongly discouraged. Don't use both `aria-selected` and `aria-checked` on treeitems in a single tree unless the meaning and purpose of `aria-selected` is different from the meaning and purpose of `aria-checked`, the meaning and purpose of each state apparent, and the user interface provides a separate method for controlling each state. - -In multi-select trees, the selected state should be independent of the focus. For example, in a typical file system navigator, the user can move focus to select any number of files for an action, such as copy or move. The visual design should make it clear which items are selected and which item has focus. - -If the complete set of available treeitems is not present in the DOM due to dynamic loading as the user moves focus in or scrolls the tree, each `treeitem` should have [`aria-level`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-level), [`aria-setsize`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-setsize), and [`aria-posinset`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-posinset) specified. - -A `treeitem` is required to have an accessible name. Generally, that name comes from the `treeitem`'s contents. The accessible name can also be set via [`aria-label`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-label) or [`aria-labelledby`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-labelledby). - -### Associated WAI-ARIA roles, states, and properties - -- [`tree`](/en-US/docs/Web/Accessibility/ARIA/Roles/tree_role) role - - : The root node for the hierarchical list of parent and child `treeitem` nodes that can expand and collapse -- [`group`](/en-US/docs/Web/Accessibility/ARIA/Roles/group_role) role - - : Identifies a set of `treeitem` child nodes. -- [`aria-expanded`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-expanded) - - : Set on the root `tree` and on `group` nodes that are parents of `treeitem` nodes, to indicate whether the tree view is expanded (`true`) or collapsed (`false`). -- [`aria-selected`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-selected) - - : Set to `true` or `false`, indicates a `treeitem` is selectable, and whether or not it is currently selected. -- [`aria-checked`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-checked) - - : Set to `true` or `false`, indicates the `treeitem` can be checked, and whether or not it is currently checked. - -### Keyboard interactions - -For a vertically oriented `tree`, which is the default orientation: - -<table> -<tr> -<td><kbd>Right arrow</kbd></td> -<td> -<ul> -<li>When focus is on a closed node, opens the node; focus does not move. -<li>When focus is on an open node, moves focus to the first child node. -<li>When focus is on an end node (a tree item with no children), does nothing. -</td> -</tr> -<tr> -<td><kbd>Left arrow</kbd></td> -<td> -<ul> -<li>When focus is on an open node, closes the node. -<li>When focus is on a child node that is also either an end node or a closed node, moves focus to its parent node. -<li>When focus is on a closed tree, does nothing. -</td> -</tr> -<tr> -<td><kbd>Down Arrow</kbd></td> -<td> Moves focus to the next node that is focusable without opening or closing a node. -</td> -</tr> -<tr> -<td><kbd>Up Arrow</kbd></td> -<td> Moves focus to the previous node that is focusable without opening or closing a node. -</td> -</tr> -<tr> -<td><kbd>Home</kbd></td> -<td> Moves focus to the first node in the tree without opening or closing a node. -</td> -</tr> -<tr> -<td><kbd>End</kbd></td> -<td> Moves focus to the last node in the tree that is focusable without opening the node. -</td> -</tr> -<tr> -<td><kbd>Enter</kbd></td> -<td>Performs the default action of the currently focused node. For parent nodes, it opens or closes the node. In single-select trees, if the node has no children, selects the current node if not already selected (which is the default action). -</td> -</tr> -<tr> -<td>Type a character*</td> -<td> -<ul> -<li>Focus moves to the next node with a name that starts with the typed character. -<li>If multiple characters are typed in rapid succession, focus moves to the next node with a name that starts with the string of characters typed. -</td> -</tr> -<tr> -<td> -<kbd>*</kbd> (Optional)</td> -<td> Expands all siblings that are at the same level as the current node. -</td> -</tr> -</table> - -\* Type-ahead is recommended for all trees, especially for trees with more than 7 root nodes - -### Multi-select keyboard interactions - -There are two interaction models for multi-select trees: While you can require that users press a modifier key, such as <kbd>Shift</kbd> or <kbd>Control</kbd> while navigating the list in order to avoid losing selection states, the model that does not require the user to hold a modifier key is recommended. - -#### Recommended multi user select model - -<table> -<tr> -<td><kbd>Space</kbd></td> -<td> Toggles the selection state of the focused node. -</td> -</tr> -<tr> -<td><kbd>Shift + Down Arrow</kbd> (Optional)</td> -<td> Moves focus to and toggles the selection state of the next node. -</td> -</tr> -<tr> -<td><kbd>Shift + Up Arrow</kbd> (Optional)</td> -<td> Moves focus to and toggles the selection state of the previous node. -</td> -</tr> -<tr> -<td><kbd>Shift + Space</kbd> (Optional)</td> -<td> Selects contiguous nodes from the most recently selected node to the current node. -</td> -</tr> -<tr> -<td><kbd>Control + Shift + Home</kbd> (Optional)</td> -<td> Selects the node with focus and all nodes up to the first node. Optionally, moves focus to the first node. -</td> -</tr> -<tr> -<td><kbd>Control + Shift + End</kbd> (Optional)</td> -<td> Selects the node with focus and all nodes down to the last node. Optionally, moves focus to the last node. -</td> -</tr> -<tr> -<td><kbd>Control + A</kbd> (Optional)</td> -<td> Selects all nodes in the tree. Optionally, if all nodes are selected, it can also unselect all nodes.</td> -</tr> -</table> - -## Examples - -The following is how one might mark up a directory listing of web development courses as a tree view: - -```html -<div> - <h3 id="treeLabel">Developer Learning Path</h3> - <ul role="tree" aria-labelledby="treeLabel"> - <li role="treeitem" aria-expanded="true"> - <span>Web</span> - <ul role="group"> - <li role="treeitem" aria-expanded="false"> - <span>Languages</span> - <ul role="group"> - <li role="treeitem" aria-expanded="false"> - <span>HTML</span> - <ul role="group"> - <li role="treeitem">Document structure</li> - <li role="treeitem">Head elements</li> - <li role="treeitem">Semantic elements</li> - <li role="treeitem">Attributes</li> - <li role="treeitem">Web forms</li> - </ul> - </li> - <li role="treeitem">CSS</li> - <li role="treeitem">JavaScript</li> - </ul> - </li> - <li role="treeitem" aria-expanded="false"> - <span>Accessibility</span> - <ul role="group"> - <li role="treeitem" aria-label="accessibility object model">AOM</li> - <li role="treeitem">WCAG</li> - <li role="treeitem">ARIA</li> - </ul> - </li> - <li role="treeitem" aria-expanded="false"> - <span>Web Performance</span> - <ul role="group"> - <li role="treeitem">Load time</li> - </ul> - </li> - <li role="treeitem">APIs</li> - </ul> - </li> - </ul> -</div> -``` - -The above provides the semantics for a tree view, but does not provide any of the interactivity. That must be added in with JavaScript. - -If the tree items aren't by default focusable, JavaScript can be used [`tabIndex="-1"`](/en-US/docs/Web/HTML/Global_attributes/tabindex) to all the treeitems except the one that should receive focus when the user tabs into the tree which should be set to `tabIndex="0"`. - -All the keyboard functionality in Keyboard interactions and all pointer events need to be programmed, including focus management, going up and down the tree, expanding and collapsing parent nodes, and selection management. - -If the tree has more than 7 tree items, including type ahead functionality is recommended. - -## Specifications - -{{Specifications}} - -## See also diff --git a/files/en-us/web/accessibility/aria/roles/widget_role/index.md b/files/en-us/web/accessibility/aria/roles/widget_role/index.md deleted file mode 100644 index f691038a21645fd..000000000000000 --- a/files/en-us/web/accessibility/aria/roles/widget_role/index.md +++ /dev/null @@ -1,42 +0,0 @@ ---- -title: "ARIA: widget role" -slug: Web/Accessibility/ARIA/Roles/widget_role -page-type: aria-role -spec-urls: https://w3c.github.io/aria/#widget ---- - -{{AccessibilitySidebar}} - -The **`widget`** role, an [abstract role](/en-US/docs/Web/Accessibility/ARIA/Roles#6._abstract_roles), is an interactive component of a graphical user interface (GUI). - -> [!NOTE] -> The `widget` role is an abstract role used for the ontology. It is included here for completeness of documentation. It should not be used by web authors. - -## Description - -The abstract `widget` role is a superclass role for some interactive GUI elements and grouping roles. `role="widget"` should not be confused with widgets roles, such as `option`, `menuitem`, and `searchbox`. - -The `widget` role is a superclass role several abstract interactive GUI roles, including [`command`](/en-US/docs/Web/Accessibility/ARIA/Roles/command_role), [`composite`](/en-US/docs/Web/Accessibility/ARIA/Roles/composite_role), [`input`](/en-US/docs/Web/Accessibility/ARIA/Roles/input_role), [`range`](/en-US/docs/Web/Accessibility/ARIA/Roles/range_role), and [`separator`](/en-US/docs/Web/Accessibility/ARIA/Roles/separator_role) (if focusable), which should not be used by web authors. - -The abstract `widget` role is also a superclass role for some grouping roles which can be used by web authors, including [`gridcell`](/en-US/docs/Web/Accessibility/ARIA/Roles/gridcell_role), [`row`](/en-US/docs/Web/Accessibility/ARIA/Roles/row_role), [`separator`](/en-US/docs/Web/Accessibility/ARIA/Roles/separator_role) (when not focusable), and [`tab`](/en-US/docs/Web/Accessibility/ARIA/Roles/tab_role), which can and should be used when appropriate. When the user navigates to one of these non-abstract roles of widget, keyboard events can switch to an application browsing mode, and pass keyboard events through to the browser. - -## Best Practices - -Do not use. - -## Specifications - -{{Specifications}} - -## See also - -- [ARIA: `roletype` role](/en-US/docs/Web/Accessibility/ARIA/Roles/roletype_role) - -- [ARIA: `command` role](/en-US/docs/Web/Accessibility/ARIA/Roles/command_role) -- [ARIA: `composite` role](/en-US/docs/Web/Accessibility/ARIA/Roles/composite_role) -- [ARIA: `gridcell` role](/en-US/docs/Web/Accessibility/ARIA/Roles/gridcell_role) -- [ARIA: `input` role](/en-US/docs/Web/Accessibility/ARIA/Roles/input_role) -- [ARIA: `range` role](/en-US/docs/Web/Accessibility/ARIA/Roles/range_role) -- [ARIA: `row` role](/en-US/docs/Web/Accessibility/ARIA/Roles/row_role) -- [ARIA: `separator` role](/en-US/docs/Web/Accessibility/ARIA/Roles/separator_role) -- [ARIA: `tab` role](/en-US/docs/Web/Accessibility/ARIA/Roles/tab_role) diff --git a/files/en-us/web/accessibility/aria/roles/window_role/index.md b/files/en-us/web/accessibility/aria/roles/window_role/index.md deleted file mode 100644 index 72d09a6827e3b7d..000000000000000 --- a/files/en-us/web/accessibility/aria/roles/window_role/index.md +++ /dev/null @@ -1,30 +0,0 @@ ---- -title: "ARIA: window role" -slug: Web/Accessibility/ARIA/Roles/window_role -page-type: aria-role -spec-urls: https://w3c.github.io/aria/#window ---- - -{{AccessibilitySidebar}} - -The `window` role defines a browser or app window. - -> [!NOTE] -> The `window` role is an abstract role. It is included here for completeness of documentation. It should not be used by web authors. - -## Description - -The `window` role, an abstract role, is a superclass for roles defining a browser or app window. The sub-class roles, currently only the [`dialog`](/en-US/docs/Web/Accessibility/ARIA/Roles/dialog_role) role, have a window-like <abbr>GUI</abbr>, or graphical user interface, whether it's a full native window or just a section of a document styled to look like a window, where `role="dialog"` would be appropriate. - -## Best Practices - -Do not use. - -## Specifications - -{{Specifications}} - -## See also - -- [ARIA: `roletype` role](/en-US/docs/Web/Accessibility/ARIA/Roles/roletype_role) -- [ARIA: `dialog` role](/en-US/docs/Web/Accessibility/ARIA/Roles/dialog_role) diff --git a/files/en-us/web/accessibility/cognitive_accessibility/index.md b/files/en-us/web/accessibility/cognitive_accessibility/index.md deleted file mode 100644 index 4a24e83ad70f393..000000000000000 --- a/files/en-us/web/accessibility/cognitive_accessibility/index.md +++ /dev/null @@ -1,282 +0,0 @@ ---- -title: Cognitive accessibility -slug: Web/Accessibility/Cognitive_accessibility -page-type: guide ---- - -{{AccessibilitySidebar}} - -Cognitive accessibility covers accessibility considerations for people with cognition and learning disabilities. This document introduces cognitive accessibility and improving accessibility of the web for people with cognitive and learning differences. - -Cognitive impairment refers to a broad range of disabilities, from people with intellectual disabilities who may have the most-limited capabilities, to age-related issues with thinking and remembering. The range includes people with mental illnesses, such as depression and schizophrenia. It also includes people with learning disabilities, such as dyslexia and attention deficit hyperactivity disorder (ADHD). - -Though there is a lot of diversity within clinical definitions of cognitive impairments, people with them experience a common set of functional problems. These problems include difficulty with understanding content, remembering how to complete tasks, and confusion caused by inconsistent or non-traditional web page layouts. In this document, we focus on steps developers should take to improve the cognitive accessibility of their websites and applications. - -## Overview - -Cognitive and intellectual disabilities cover a large spectrum, and may be momentary, temporary, or permanent conditions. For example, dementia and Alzheimer's are permanent cognitive impairments that get progressively worse. Other permanent cognitive impairments include aphasia, speech and language, autism, ADD/ADHD, dyslexia, and dyscalculia. - -An example of a temporary cognitive impairment could be people affected by substances such as alcohol or drugs. Another form it can take is depression, such as when mourning the loss of a loved one, or being momentarily saddened by a tweet or video they just saw online. A third example could be sleep deprivation. - -It may seem like an overwhelming challenge to address the wide range of cognitive differences, especially when solutions for two different people may be conflicting. One way to handle this is to focus on cognitive skills. Cognitive skills include: - -- attention -- memory -- processing speed -- time management -- letters and language -- numbers symbols and math -- understanding and making choices - -A solid approach to providing accessible solutions for people with cognitive impairments includes: - -- delivering content in more than one way, such as by text-to-speech or by video; -- providing easily-understood content, such as text written using plain-language standards; -- focusing attention on important content; -- minimizing distractions, such as unnecessary content or advertisements; -- providing consistent web page layout and navigation; -- incorporating familiar elements, such as underlined links that are blue when not visited and purple when visited; -- dividing processes into logical, essential steps with progress indicators; -- making website authentication as easy as possible without compromising security; and -- making forms easy to complete, such as with clear error messages and simple error recovery. - -## WCAG Guidelines - -WCAG, Web Content Accessibility Guidelines, includes several guidelines to improve cognitive accessibility. These guidelines are published by the Web Accessibility Initiative (WAI) of the World Wide Web Consortium (W3C), the main international standards organization for the Internet. This group is also responsible for the [Accessible Rich Internet Application (ARIA)](/en-US/docs/Web/Accessibility/ARIA/ARIA_Guides) guidelines. - -WCAG are guided by four principles: websites must be Perceivable, Operable, Understandable, and Robust. To this end, they define 17 specific guidelines, of which six are especially relevant for cognitive accessibility. - -All of the following guidelines help more than just people with cognitive disabilities. For example, being able to extend the expiration time on an application requiring an authentication code sent to a mobile device via text message helps with the following scenarios: - -- People with attention or anxiety disorders. -- People who have a poor short-term memory, or who are multitasking. -- People who are less technologically literate. -- People who have poor wireless reception. -- People who have motor control issues. - -## Adaptability - -[Guideline 1.3](https://www.w3.org/WAI/WCAG21/Understanding/adaptable) states "content should be **adaptable**". Create content that can be presented in different ways without losing information or structure. For example, provide {{glossary('responsive web design', 'responsive')}} layouts, with a single column mobile design. - -All information, including structure and relationships conveyed through the presentation, should be available in a form that can be perceived by all users to achieve this goal. For example, the information could be spoken aloud via a narration tool. Making your content capable of being understood by the software is a good way to help ensure it can be used by alternate presentational modes. - -## Time - -It is important to allow users the time they require to complete tasks. [Guideline 2.2](https://www.w3.org/WAI/WCAG21/Understanding/enough-time) states "provide users enough **time** to read and use content". - -A **time limit** is any process that happens without user initiation after a set time or on a periodic basis, such as being logged out after 30 minutes or having 15 minutes to make a purchase. People with cognitive disabilities may require more time to read content, or to perform functions such as filling out forms. Solutions include providing users enough additional time to complete tasks or eliminate time constraints altogether. - -### Timers - -Options for adjusting time requirements include: - -- Allowing the user to turn off or adjust the time to at least 10 times the original limit before encountering it. -- Alerting the user and providing a buffer of at least 20 seconds to extend the timeout duration by a factor of 10 with an action, such as hitting the space bar. - -Provide a toggle on content that allows users to enable a longer session time limit, or no session time limit at all. Examples of timed content include forms, timed reading exercises, and training materials. If the time limit is longer than 20 hours, accommodations are not required. - -### Moving, blinking, scrolling - -It is important not to distract users, especially ones with cognitive disabilities. - -If moving, blinking, scrolling, or auto-updating information starts automatically, lasts more than five seconds, and is presented in parallel with other content, the user must able to pause, stop, hide or control it, unless it's an essential functionality. "Essential" means that removing the moving, blinking, scrolling, or auto-updating information would fundamentally change the meaning of the content and/or functionality, **and** information and functionality cannot be achieved in another way that would conform. This includes animated GIFs, if the gif animates for more than 5 seconds. - -Additional timing criteria to consider are: - -- People who have cognitive or language limitations may need more time to read and to understand. For improved usability remove any time limit. Timed content should also be avoided, with exceptions for non-interactive synchronized media and real-time events. -- People with attention deficit disorders should be able to focus on content without distractions. The user should be able to postpone or suppress interruptions, except situations involving alerting a person to an emergency. This provides access to people with cognitive disabilities by enabling them to focus on the main purpose of the content. Enable the user to postpone content updates by providing a way to request content updates rather than updating automatically. Also, enable a way to make nonessential alerts optional. -- Ensure that people can continue an activity without loss of data after re-authenticating an expired session, for example, saving the state of a questionnaire. Make sure to save data in such a way that it can be modified after a user re-authenticates. Before re-authenticating, encode the data as hidden or encrypted. -- Providing warnings about inactivity that could result in data loss. When a timeout is used, tell people exactly how much time will cause the session to time out and result in lost data. The exception to this is preserving data for more than 20 hours when no actions are taken. - -## Navigation - -[Guideline 2.4](https://www.w3.org/WAI/WCAG21/Understanding/navigable) states "provide ways to help users navigate, find content, and determine where they are," and provides 10 guidelines to ensure the site is navigable and content is findable: - -### Include a `<title>` - -Make sure to include a {{HTMLElement('title')}} for the document, as titles provide a quick and easy to reference description of the screen's main point. People with cognitive disabilities, limited short-term memory, and reading disabilities all benefit from being able to identify the purpose of content this way. - -### Heading and labels - -Include clear and descriptive headings so users can easily find information and understand relationships between different content sections. Descriptive labels help users identify specific components within the content. People who read slowly and people with limited short-term memory benefit when section titles make it possible to predict what each section contains. - -### Section headings - -Headings help define overall organization of page content. They help facilitate navigation through page content sections, and provide a mechanism to aid comprehension. Examples of headings include chapters, sections and subsections of content, and so on. - -Headings are more obvious navigational aids compared to other methods to identify page content sections (borders, whitespace, horizontal rules, etc.). - -### Multiple ways to find content - -Different users prefer different methods of finding information, so it is important to provide multiple ways for users to locate content on your site. - -Providing more than one way to navigate your site can help people find information faster. Some users may prefer a table of contents, site map, or search functionality rather than reading and traversing through several pages to find what they need. Others may prefer to explore the site in a sequential manner, moving from page to page in order to best understand the site's layout, content, and concepts. - -### Ability to bypass blocks of content - -Providing a mechanism, such as a [skip link](/en-US/docs/Web/HTML/Element/a#skip_links), to bypass blocks of content that are repeated on multiple web pages. - -### Focus order makes sense - -The order of focus for interactive elements should make sense. To achieve this, the DOM order should match the visual order, which in turn should match the tabbing order. If the tab order jumps around, especially in a way that does not match the visual order when navigating with a keyboard, users can become disoriented. - -### Focused elements should be visibly focused - -When a user navigates using a keyboard, the UI should make it obvious which element currently has focus. Don't alter or remove the browser's default [`:focus`](/en-US/docs/Web/CSS/:focus) styling, unless you're making focus even more obvious. - -### Link text conveys meaning - -The link's text should clearly and concisely communicate what the user should expect to be navigated to next if they choose to activate it. Poorly phrased link text may confuse users as to its purpose or destination. - -Some forms of assistive technology allow users to navigate by lists of all the links present on the page. Links will be removed from the context of their surrounding non-link content, making the need for understandable link text even more important. An example of a poor experience is a page full of links whose text reads, "Click here". Without indicating where "here" will take you, the link's purpose is unclear. - -For screen readers, it is vital that linked text describes the purpose of each link. If you have added content to links for screen readers, and that content is verbose and potentially confusing to sighted readers, consider clipping the added text to visually hide it from those not using assistive technologies. - -### Current location is available - -Users should be able to orient themselves within a site or application. This is especially important and helpful for people with short attention spans who may become confused when following a long series of navigation steps. - -All users benefit from information about where they are in a site's hierarchy, especially for sites or applications with large amounts of content or many subsections. [Breadcrumbs](/en-US/docs/Glossary/Breadcrumb), [site maps](/en-US/docs/Glossary/Site_map), and identifying the current page in the navigation as "current" are all techniques that help communicate the current location. - -## Readability - -[Guideline 3.1](https://www.w3.org/WAI/WCAG21/Understanding/readable) states "make text content readable and understandable". For some users, it is difficult to infer the meaning of a word or phrase from context, especially when the word or phrase is used in an unusual way, or has been given a specialized meaning. - -For these users, the ability to read and understand may depend on the availability of specific definitions or the expanded forms of acronyms or abbreviations. Some users may experience great difficulty in recognizing written words yet they understand extremely complex and sophisticated documents when the text is read aloud, or when key processes and ideas are illustrated visually. - -### Declare the language of the page and any content not in that main language - -The language of every page must be declared by using the [`lang`](/en-US/docs/Web/HTML/Global_attributes/lang) attribute on the {{HTMLElement('html')}} element. Include the `lang` attribute again on text that is in a language other than the main language of the document. - -Proper use of `lang` allows some screen readers to announce the text properly when converting it into synthetic speech. It also helps people who use text-to-speech software. - -### Define unusual words and word usage - -Some disabilities make it difficult to understand nonliteral word usage, such as idioms, colloquialisms, and specialized jargon. Non-native language speakers may also struggle with these terms. If a word or phrase has a unique meaning, in the document provide a definition inline or linked, within a glossary, or to an online dictionary. If a word or phrase is used to mean more than one thing, define each use. - -### Define abbreviations - -Abbreviations can be confusing for people who: - -- Have difficulty decoding words. -- Have limited memory. -- Have difficulty using context to aid understanding. -- Rely on screen magnifiers (which often reduce contextual cues). - -Provide an expanded form of the abbreviation the first time it is used, followed by the abbreviation placed within an {{HTMLElement('abbr')}} element. If an abbreviation has no expanded form, or is an abbreviation for a word that is not in the document's main language (such as Latin), explain its meaning. Also, consider using [ruby text](/en-US/docs/Web/HTML/Element/ruby) for initialism (pronunciation of acronyms). - -### Reading level - -Content should be written as clearly as possible. A good rule to go by is to make content simple enough that it can be understood the first time. Methods to achieve this include: - -- Using short, simple words. -- Writing short sentences. -- Using active voice in the present tense. -- Using correct grammar and spelling. - -It helps users with cognitive disabilities to provide a text summary (sometimes referred to as a TL;DR, or "too long; didn't read") at a low reading level. Another technique you can use is providing accompanying visuals to help explain ideas, events, and processes. - -There are tools that can rate the level of your content. For example, this document has an average grade level of about 11. This means it should be easily understood by a native English speaker aged 16 to 17. Some tools can even provide suggestions to help simplify it. - -### Pronunciation - -There are multiple techniques that can help teach people how to pronounce words: - -- Provide the pronunciation immediately following the word. -- Link to a list of pronunciations. -- Provide a glossary with pronunciation. -- Use the {{HTMLElement('ruby')}} element to illustrate how a word is pronounced. - -Providing guidance on how to pronounce words helps many different kinds of people, including those who prefer to read aloud, non-native language speakers, and people who are unfamiliar with the meaning of a term in context. - -Another solution is to use glyphs or diacritical marks to illustrate pronunciation. However, if this technique is used, there must be a mechanism to turn it off. Further, it is helpful to link to a guide to the marks being used, as their meaning may not be obvious. - -## Predictability - -WCAG [Guideline 3.2](https://www.w3.org/WAI/WCAG21/Understanding/predictable) states "make web pages appear and operate in predictable ways". This is a tenet of good user experience design. Consistency is especially important for people with cognitive difficulties. This includes consistency in page layout and predictable interactive components. - -### Use activation, not focus to change context - -Creating a change in context should be intentional. Because of this, when a UI feature receives [focus](/en-US/docs/Web/API/HTMLElement/focus), it should not trigger further user-facing actions. Rather, users should need to "activate" a feature to trigger the change. - -### Change setting based on an active request - -Form control operation and data entry should result in predictable behavior. Changes in context can confuse users with cognitive disabilities, and should therefore only occur when it is clear that such a change will happen in response to the user's action. - -Changing state should require intentional user action. Examples of this are checking a checkbox, entering data or changing a select option. Also be sure to provide a submit button to initiate the change of context, and describe what will happen before the change is made. - -### Keep navigation consistent throughout the site - -Keep the navigation order consistent between pages. For example, if you have a navigation bar on multiple pages, make that navigation uniform across the site with the same links in the same location. This doesn't just apply to navigation: present all repeated components in the same relative order each time they appear. - -### Provide consistent labeling - -Identical functions should have similar labels every time they are utilized. Consistent button labels, alternative text for icons, and iconography for similar interactions and so on, even on different sections of your site, help all your users. - -### Be consistent and predictable, and use norms - -While unlabeled iconography is not the most effective method of conveying information, keeping the use of the icons (and if labeled, their label text) consistent helps people to understand what the icon represents. Similarly, don't change defaults like the browser's back button. If you need to redirect a user, let the user know about it beforehand. - -## Input Assistance - -[Guideline 3.3](https://www.w3.org/WAI/WCAG21/Understanding/input-assistance) helps to ensure accurate data entry, stating "help users avoid and correct mistakes". While we all make mistakes, some people are more likely to make mistakes, less likely to notice a mistake, or have a harder time correcting a mistake once they make one. - -Input Assistance guidelines aim to reduce the likelihood that users, especially those with disabilities, make a mistake, and, if they do make a mistake, increase the likelihood that they see and comprehend the error message and can successfully fix any errors. - -### Convey automated error detection - -Users need to be alerted to the error and informed of what is wrong. If there is client side error detection, observe the following guidelines to make the error as effective as possible when conveyed to the user: - -- The error must be described in the text. -- Ensure that the error message is as specific as possible. -- Provide text to identify incomplete required fields and text descriptions if a value entered is invalid. -- If the error prevented a form submission, focus on the error. If multiple errors are present, provide a summary, with each error linking to the related input. -- Include text along with use of icons, images, color and so on. Some people have difficulty understanding the meaning of icons and other visual cues. -- Other people may have difficulty understanding the text version of your error message. For these people, also provide things like icons and colors. -- Also, provide feedback on when there is a successful form submission. - -### Provide instructions for user input - -Start the form with text instructions on how to operate it. Include labels or instructions when users need to input information, using the {{HTMLElement('label')}}, {{HTMLElement('fieldset')}}, and {{HTMLElement('legend')}} elements to do so. - -Labels should be descriptive and positioned close to the input they relate to. When requiring a specific format for input, provide an example formatted in the proper way. Additionally, consider performing server-side validation to help format input data, to aid in the ease of user input. - -If a form control is required, indicate it both visually and [via code](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-required). If a form control changes context, describe what will happen in a way that the user will understand it before they cause the context change to happen. - -### Error Suggestion - -Provide suggested input to the user if an input error is automatically detected and suggestions for correction are known (unless doing so would jeopardize the security or purpose of the content). - -### Prevent catastrophes - -For submissions that cause, or can lead to, legal, financial, or other significant consequences, ensure that the submissions can be reviewed, confirmed, and/or are reversible. - -Data entered by the user should be checked for errors before submission, and the user should be given the opportunity to correct them. The user should be able to review, confirm, and correct information before final submission. Also, be sure to include a confirmation checkbox in addition to a submit button. - -If a submission causes a legal or financial transaction to occur, provide a stated time within which the request can be amended or canceled by the user. - -### Provide help - -Context-sensitive help should be made available. If a form requires text input, provide form instructions describing the purpose and the necessary input. Include spell checking and suggestions for long-form text input, as well as links to help and support material. If a specific data format is expected for input, provide an example. - -## Notes - -The above are good design practices. They will benefit everyone. - -- Many people with cognitive impairments also have physical disabilities. Websites must conform with the W3C's [Web Content Accessibility Guidelines](https://www.w3.org/WAI/standards-guidelines/wcag/). -- The W3C's [Cognitive and Learning Disabilities Accessibility Task Force](https://www.w3.org/WAI/GL/task-forces/coga/) produces web accessibility guidelines for people with cognitive impairments. -- WebAIM has a [Cognitive page](https://webaim.org/articles/cognitive/) of relevant information and resources. -- The United States Centers for Disease Control estimate that, as of 2018, 1 in 4 U.S. citizens have a disability and, of them, [cognitive impairment is the most common for young people](https://archive.cdc.gov/www_cdc_gov/media/releases/2018/p0816-disability.html). -- In the U.S., "intellectual disabilities" used to be called "mental retardation". In the U.K., "intellectual disabilities" is commonly called "learning disabilities" or "learning difficulties". - -## See also - -- [Accessibility Guidelines](https://extensionworkshop.com/documentation/develop/build-an-accessible-extension/) -- [What is accessibility](/en-US/docs/Learn_web_development/Core/Accessibility/What_is_accessibility) -- [Accessibility for seizure disorders](/en-US/docs/Web/Accessibility/Seizure_disorders) -- [Understanding WCAG Guidelines](/en-US/docs/Web/Accessibility/Understanding_WCAG) -- [Accessibility overview](/en-US/docs/Learn_web_development/Core/Accessibility) -- [Web Content Accessibility Guidelines](https://www.w3.org/WAI/standards-guidelines/wcag/), including [cognitive accessibility guidelines](#wcag_guidelines) -- [The W3C's Cognitive and Learning Disabilities Accessibility Task Force](https://www.w3.org/WAI/GL/task-forces/coga/) -- [WebAIM Cognitive information](https://webaim.org/articles/cognitive/) -- [CDC information on disabilities](https://www.cdc.gov/ncbddd/disabilityandhealth/) diff --git a/files/en-us/web/accessibility/guides/accessibility_and_spatial_patterns/index.md b/files/en-us/web/accessibility/guides/accessibility_and_spatial_patterns/index.md new file mode 100644 index 000000000000000..2155fe9c9d90ff4 --- /dev/null +++ b/files/en-us/web/accessibility/guides/accessibility_and_spatial_patterns/index.md @@ -0,0 +1,87 @@ +--- +title: Accessibility and spatial patterns +short-title: Spatial patterns +slug: Web/Accessibility/Guides/Accessibility_and_Spatial_Patterns +page-type: guide +sidebar: accessibilitysidebar +--- + +This document describes visual patterns that can induce physical symptoms in people who have photosensitive epilepsy, vestibular disorders, or other perceptual issues. + +## Spatial Localization + +NASA conducted research on the perception of color, and found that luminance contrast mattered greatly as to how colors are perceived. The two images below are from NASA research, specifically, from the article, "[Designing With Blue](https://colorusage.arc.nasa.gov/blue_2.php)" + +![Comparison of the stability of the spatial localization of yellow vs. red. Both are roughly isoluminant with their backgrounds. The misalignment and gap between the chromatic bars and black bars is physically the same for the yellow and red but much less visually obvious for the yellow.](yellow_edge_3.gif) ![Comparison of the stability of the spatial localization of yellow vs. red. Both are roughly isoluminant with their backgrounds. The misalignment and gap between the chromatic bars and black bars is physically the same for the yellow and red but much less visually obvious for the yellow.](yellow_edge_4.gif) + +"_**Spatial Localization.** Symbols which have the same luminance as their background are perceptually less securely located in space and time than are symbols with higher luminance contrast. They tend to "float" visually or be "captured" by adjacent symbols with high luminance-contrast. The phenomenon seems to be especially problematic for symbol/background combinations that differ only in the blue channel._" + +## Distance between stripes + +Photosensitive seizures may be caused by static images as well as animation. The mechanism for this is poorly understood, but is believed to be linked to "gamma oscillations" set up in the brain. These oscillations in the brain are a different kind of response than other kinds of neurological responses believed to cause photosensitive seizures. + +Stripes and patterns are typical of the kinds of images that create problems, and stripes have been studied most closely. There's the potential for causing harm if there are more than five light-dark pairs of stripes in any orientation. They can be parallel, radial, curved or straight, and may be formed by rows of repeating elements. + +In 2005, Arnold Wilkins, John Emmett, and Graham Harding evaluated the guidelines for characterizing patterned images that could precipitate seizures. They revised the guidelines to their fundamental core, and came up with a surprisingly simple, but powerful [test](https://onlinelibrary.wiley.com/doi/full/10.1111/j.1528-1167.2005.01405.x), which they published in the paper, **[Characterizing the Patterned Images That Precipitate Seizures and Optimizing Guidelines To Prevent Them](https://onlinelibrary.wiley.com/doi/full/10.1111/j.1528-1167.2005.01405.x)** + +> [!NOTE] +> The steps necessary to evaluate material reduce to the following: +> +> Look at the screen: +> +> - Are there more than five stripes? +> - If so, do they last longer than 0.5 s? +> - If so, does the brightness exceed the stated limit? +> - If so, categorize the motion of the pattern. +> - Are the guidelines contravened? +> +> If so, reduce brightness. + +## Text and padding + +WCAG standards for contrast perception do not take into account the effect of padding. For example, blue text on a gray background is easier to perceive if it is surrounded "locally" by black than by white. There is such a thing as "local" adaptation to colors. The bottom line: padding matters. + +## Math + +Spatial reasoning affects Math learning; consequently, spatial relationships in how math is presented affects cognition. The web developer can do something about this in the manner in which they display math. Animation figures strongly in this arena. For example, "how" an object looks when it is rotated, from different angles, how they look sliced, and how they relate to each other in space all make a difference in an ability to understand Math in spatial terms. + +## Braille + +Modern technology enables non-experts to print Braille. Adobe Illustrator, for example, allows one to Typeset ADA Braille for printing out. + +The ability to represent spatial patterns accurate to those who are blind is critical for accessibility. For example, knowing Braille is not enough. The Braille dots have to be spatially apart from one another so as to be readable in a "human" way. The human touch does distinguish with ease braille dots that are too close or too far apart from one another. + +Space has to surround the braille character. A user of braille does not lay a finger on "top" of a braille character, the user has to move her finger over the character, in the way that a sighted person must move her eyes across text written on a page. + +The nature of space can change depending upon what MIME type is being used, and its version. For example, borders on SVG can extend both inward and outward from its dimensions, or for newer versions of SVG, entirely outward from it, thus reducing the space around the SVG to enable perception. + +## See also + +### MDN + +- [Accessibility: What users can do to browse more safely](/en-US/docs/Web/Accessibility/Guides/Browsing_safely) +- [Web accessibility for seizures and physical reactions](/en-US/docs/Web/Accessibility/Guides/Seizure_disorders) +- [Web Accessibility: Understanding Colors and Luminance](/en-US/docs/Web/Accessibility/Guides/Colors_and_Luminance) + +### Braille + +- [Part 3: A Step-by-Step Guide to Typesetting ADA Braille Correctly in Adobe Illustrator](https://www.tinkeringmonkey.com/guides/ada-signage/a-step-by-step-guide-to-typesetting-ada-braille-correctly-in-adobe-illustrator/) +- [Spatial Math in BrailleBlaster (4 of 5)](https://www.youtube.com/watch?v=yz9vefDsj1g) + +### Government Literature + +- [NASA: Designing With Blue](https://colorusage.arc.nasa.gov/blue_2.php) + +### Math + +- [Spatial Reasoning: Why Math Talk is About More Than Numbers](https://dreme.stanford.edu/news/spatial-reasoning-why-math-talk-is-about-more-than-numbers/) + +### Scientific Literature + +- [Color constancy in context: Roles for local adaptation and levels of reference](https://jov.arvojournals.org/article.aspx?articleid=2192799) +- [Gamma oscillations and photosensitive epilepsy](https://www.sciencedirect.com/science/article/pii/S0960982217304062?via%3Dihub) +- [Characterizing the Patterned Images That Precipitate Seizures and Optimizing Guidelines To Prevent Them](https://onlinelibrary.wiley.com/doi/epdf/10.1111/j.1528-1167.2005.01405.x) Arnold Wilkins, John Emmett, and Graham Harding + +#### Contributors + +Heartfelt thanks to Jim Allan of the [Diagram Center](http://diagramcenter.org/) for his discussions on the topic of alternative means of education. diff --git a/files/en-us/web/accessibility/accessibility_and_spacial_patterns/yellow_edge_3.gif b/files/en-us/web/accessibility/guides/accessibility_and_spatial_patterns/yellow_edge_3.gif similarity index 100% rename from files/en-us/web/accessibility/accessibility_and_spacial_patterns/yellow_edge_3.gif rename to files/en-us/web/accessibility/guides/accessibility_and_spatial_patterns/yellow_edge_3.gif diff --git a/files/en-us/web/accessibility/accessibility_and_spacial_patterns/yellow_edge_4.gif b/files/en-us/web/accessibility/guides/accessibility_and_spatial_patterns/yellow_edge_4.gif similarity index 100% rename from files/en-us/web/accessibility/accessibility_and_spacial_patterns/yellow_edge_4.gif rename to files/en-us/web/accessibility/guides/accessibility_and_spatial_patterns/yellow_edge_4.gif diff --git a/files/en-us/web/accessibility/guides/accessible_web_applications_and_widgets/index.md b/files/en-us/web/accessibility/guides/accessible_web_applications_and_widgets/index.md new file mode 100644 index 000000000000000..5aa3e39a5474e5d --- /dev/null +++ b/files/en-us/web/accessibility/guides/accessible_web_applications_and_widgets/index.md @@ -0,0 +1,178 @@ +--- +title: An overview of accessible web applications and widgets +short-title: Accessible web applications and widgets +slug: Web/Accessibility/Guides/Accessible_web_applications_and_widgets +page-type: guide +sidebar: accessibilitysidebar +--- + +Most JavaScript libraries offer a library of client-side widgets that mimic the behavior of familiar desktop interfaces. Sliders, menu bars, file list views, and more can be built with a combination of JavaScript, CSS, and HTML. Since the HTML4 specification doesn't provide built-in tags that semantically describe these kinds of widgets, developers typically resort to using generic elements such as {{HTMLElement('div')}} and {{HTMLElement('span')}}. While this results in a widget that looks like its desktop counterpart, there usually isn't enough semantic information in the markup to be usable by an assistive technology. + +## The problem + +Dynamic content on a web page can be particularly problematic for users who, for whatever reason, are unable to view the screen. Stock tickers, live twitter feed updates, progress indicators, and similar content modify the DOM in ways that an assistive technology (AT) may not be aware of. That's where [ARIA](/en-US/docs/Web/Accessibility/ARIA) comes in. + +_Example 1: Markup for a tabs widget built without ARIA labeling. There's no information in the markup to describe the widget's form and function._ + +```html +<!-- This is a tabs widget. How would you know, looking only at the markup? --> +<ol> + <li id="ch1Tab"> + <a href="#ch1Panel">Chapter 1</a> + </li> + <li id="ch2Tab"> + <a href="#ch2Panel">Chapter 2</a> + </li> + <li id="quizTab"> + <a href="#quizPanel">Quiz</a> + </li> +</ol> + +<div> + <div id="ch1Panel">Chapter 1 content goes here</div> + <div id="ch2Panel">Chapter 2 content goes here</div> + <div id="quizPanel">Quiz content goes here</div> +</div> +``` + +_Example 2: How the tabs widget might be styled visually. Users might recognize it visually, but there are no machine-readable semantics for an assistive technology._ ![Screenshot of the tabs widget](tabs_widget.png) + +## ARIA + +**ARIA** enables developers to describe their widgets in more detail by adding special attributes to the markup. Designed to fill the gap between standard HTML tags and the desktop-style controls found in dynamic web applications, ARIA provides roles and states that describe the behavior of most familiar UI widgets. + +> [!WARNING] +> Many of these were later added when browsers didn't fully support modern HTML features. **Developers should always prefer using the correct semantic HTML element over using ARIA**. + +The ARIA specification is split up into three different types of attributes: roles, states, and properties. Roles describe widgets that aren't otherwise available in HTML 4, such as sliders, menu bars, tabs, and dialogs. Properties describe characteristics of these widgets, such as if they are draggable, have a required element, or have a popup associated with them. States describe the current interaction state of an element, informing the assistive technology if it is busy, disabled, selected, or hidden. + +ARIA attributes are interpreted automatically by the browser and translated to the operating system's native accessibility APIs. So an element with role="slider" will be controlled in the same way as a native slider is controlled on the operating system. + +This provides a much more consistent user experience than was possible in the previous generation of web applications, since assistive technology users can apply all of their knowledge of how desktop applications work when they are using web-based applications. + +_Example 3: Markup for the tabs widget with ARIA attributes added._ + +```html +<!-- Now *these* are Tabs! --> +<!-- We've added role attributes to describe the tab list and each tab. --> +<ol role="tablist"> + <li id="ch1Tab" role="tab"> + <a href="#ch1Panel">Chapter 1</a> + </li> + <li id="ch2Tab" role="tab"> + <a href="#ch2Panel">Chapter 2</a> + </li> + <li id="quizTab" role="tab"> + <a href="#quizPanel">Quiz</a> + </li> +</ol> + +<div> + <!-- Notice the role and aria-labelledby attributes we've added to describe these panels. --> + <div id="ch1Panel" role="tabpanel" aria-labelledby="ch1Tab"> + Chapter 1 content goes here + </div> + <div id="ch2Panel" role="tabpanel" aria-labelledby="ch2Tab"> + Chapter 2 content goes here + </div> + <div id="quizPanel" role="tabpanel" aria-labelledby="quizTab"> + Quiz content goes here + </div> +</div> +``` + +ARIA is [well supported](https://caniuse.com/#feat=wai-aria) by all major browsers and many assistive technologies. + +### Presentational changes + +Dynamic presentational changes include using CSS to change the appearance of content (such as a red border around invalid data, or changing the background color of a checked checkbox), as well as showing or hiding content. + +#### State changes + +ARIA provides attributes for declaring the current state of a UI widget. Examples include (but are certainly not limited to): + +- `aria-checked` + - : Indicates the state of a checkbox or radio button. +- `aria-disabled` + - : Indicates that an element is visible but not editable or otherwise operable. +- `aria-grabbed` + - : Indicates the 'grabbed' state of an object in a drag-and-drop operation. + +(For a full list of ARIA states, consult the [ARIA list of states and properties](https://www.w3.org/TR/wai-aria-1.1/#introstates).) + +Developers should use ARIA states to indicate the state of UI widget elements and use CSS attribute selectors to alter the visual appearance based on the state changes (rather than using script to change a class name on the element). + +#### Visibility changes + +When content visibility is changed (i.e., an element is hidden or shown), developers should change the **`aria-hidden`** property value. The techniques described above should be used to declare CSS to visually hide an element using `display:none`. + +Here is an example of a tooltip that uses **`aria-hidden`** to control the visibility of the tooltip. The example shows a web form with tooltips containing instructions associated with the entry fields. + +```html +<div class="text"> + <label id="tp1-label" for="first">First Name:</label> + <input + type="text" + id="first" + name="first" + size="20" + aria-labelledby="tp1-label" + aria-describedby="tp1" + aria-required="false" /> + <div id="tp1" class="tooltip" role="tooltip" aria-hidden="true"> + Your first name is optional + </div> +</div> +``` + +The CSS for this markup is shown in the following code. Note that there is no custom classname used, only the status of the **`aria-hidden`** attribute. + +```css +div.tooltip[aria-hidden="true"] { + display: none; +} +``` + +The JavaScript to update the **`aria-hidden`** property has the form shown in the following code. Note that the script only updates the **`aria-hidden`** attribute; it does not need to also add or remove a custom classname. + +```js +function showTip(el) { + el.setAttribute("aria-hidden", "false"); +} +``` + +### Role changes + +ARIA allows developers to declare a semantic role for an element that otherwise offers incorrect or no semantics. The **`role`** of an element should not change. Instead, remove the original element and replace it with an element with the new **`role`**. + +For example, consider an "inline edit" widget: a component that allows users to edit a piece of text in place, without switching contexts. This component has a "view" mode, in which the text is not editable, but is activatable, and an "edit" mode, in which the text can be edited. A developer might be tempted to implement the "view" mode using a read-only text {{ HTMLElement("input") }} element and setting its ARIA **`role`** to `button`, then switching to "edit" mode by making the element writable and removing the **`role`** attribute in "edit" mode (since {{ HTMLElement("input") }} elements have their own role semantics). + +Do not do this. Instead, implement the "view" mode using a different element altogether, such as a {{ HTMLElement("div") }} or {{ HTMLElement("span") }} with a **`role`** of `button`, and the "edit" mode using a text {{ HTMLElement("input") }} element. + +### Asynchronous content changes + +> [!NOTE] +> Under construction. See also [Live Regions](/en-US/docs/Web/Accessibility/ARIA/Guides/Live_regions) + +## Keyboard navigation + +Often times developers overlook support for the keyboard when they create custom widgets. To be accessible to a variety of users, all features of a web application or widget should also be controllable with the keyboard, without requiring a mouse. In practice, this usually involves following the conventions supported by similar widgets on the desktop, taking full advantage of the Tab, Enter, Spacebar, and arrow keys. + +Traditionally, keyboard navigation on the web has been limited to the Tab key. A user presses Tab to focus each link, button, or form on the page in a linear order, using Shift-Tab to navigate backwards. It's a one-dimensional form of navigation—forward and back, one element at a time. On fairly dense pages, a keyboard-only user often has to press the Tab key dozens of times before accessing the needed section. Implementing desktop-style keyboard conventions on the web has the potential to significantly speed up navigation for many users. + +Here's a summary of how keyboard navigation should work in an ARIA-enabled web application: + +- The Tab key should provide focus to the widget as a whole. For example, tabbing to a menu bar **should NOT** put focus on the menu's first element. +- The arrow keys should allow for selection or navigation within the widget. For example, using the left and right arrow keys should move focus to the previous and next menu items. +- When the widget is not inside a form, both the Enter and Spacebar keys should select or activate the control. +- Within a form, the Spacebar key should select or activate the control, while the Enter key should submit the form's default action. +- If in doubt, mimic the standard desktop behavior of the control you are creating. + +So, for the Tabs widget example above, the user should be able to navigate into and out of the widget's container (the {{HTMLElement('ol')}} in our markup) using the Tab and Shift-Tab keys. Once keyboard focus is inside the container, the arrow keys should allow the user to navigate between each tab (the {{HTMLElement('li')}} elements). From here, conventions vary from platform to platform. On Windows, the next tab should automatically be activated when the user presses the arrow keys. On macOS, the user can press either Enter or the Spacebar to activate the next tab. An in-depth tutorial for creating [Keyboard-navigable JavaScript widgets](/en-US/docs/Web/Accessibility/Guides/Keyboard-navigable_JavaScript_widgets) describes how to implement this behavior with JavaScript. + +## See also + +- [ARIA](/en-US/docs/Web/Accessibility/ARIA) +- [Writing Keyboard-navigable JavaScript widgets](/en-US/docs/Web/Accessibility/Guides/Keyboard-navigable_JavaScript_widgets) +- [WAI-ARIA Specification](https://www.w3.org/TR/wai-aria-1.1/) +- [WAI-ARIA Authoring Practices](https://www.w3.org/WAI/ARIA/apg/) diff --git a/files/en-us/web/accessibility/an_overview_of_accessible_web_applications_and_widgets/tabs_widget.png b/files/en-us/web/accessibility/guides/accessible_web_applications_and_widgets/tabs_widget.png similarity index 100% rename from files/en-us/web/accessibility/an_overview_of_accessible_web_applications_and_widgets/tabs_widget.png rename to files/en-us/web/accessibility/guides/accessible_web_applications_and_widgets/tabs_widget.png diff --git a/files/en-us/web/accessibility/accessibility_colon__what_users_can_to_to_browse_safely/android-remove-animations.png b/files/en-us/web/accessibility/guides/browsing_safely/android-remove-animations.png similarity index 100% rename from files/en-us/web/accessibility/accessibility_colon__what_users_can_to_to_browse_safely/android-remove-animations.png rename to files/en-us/web/accessibility/guides/browsing_safely/android-remove-animations.png diff --git a/files/en-us/web/accessibility/accessibility_colon__what_users_can_to_to_browse_safely/beelinereader.png b/files/en-us/web/accessibility/guides/browsing_safely/beelinereader.png similarity index 100% rename from files/en-us/web/accessibility/accessibility_colon__what_users_can_to_to_browse_safely/beelinereader.png rename to files/en-us/web/accessibility/guides/browsing_safely/beelinereader.png diff --git a/files/en-us/web/accessibility/accessibility_colon__what_users_can_to_to_browse_safely/colorfiltersgrayscaleinwindows.png b/files/en-us/web/accessibility/guides/browsing_safely/colorfiltersgrayscaleinwindows.png similarity index 100% rename from files/en-us/web/accessibility/accessibility_colon__what_users_can_to_to_browse_safely/colorfiltersgrayscaleinwindows.png rename to files/en-us/web/accessibility/guides/browsing_safely/colorfiltersgrayscaleinwindows.png diff --git a/files/en-us/web/accessibility/accessibility_colon__what_users_can_to_to_browse_safely/image_animation_mode.png b/files/en-us/web/accessibility/guides/browsing_safely/image_animation_mode.png similarity index 100% rename from files/en-us/web/accessibility/accessibility_colon__what_users_can_to_to_browse_safely/image_animation_mode.png rename to files/en-us/web/accessibility/guides/browsing_safely/image_animation_mode.png diff --git a/files/en-us/web/accessibility/guides/browsing_safely/index.md b/files/en-us/web/accessibility/guides/browsing_safely/index.md new file mode 100644 index 000000000000000..8ede23c73d0de40 --- /dev/null +++ b/files/en-us/web/accessibility/guides/browsing_safely/index.md @@ -0,0 +1,91 @@ +--- +title: "Accessibility: What personalization helps browse more safely" +short-title: Personalization to help browse safely +slug: Web/Accessibility/Guides/Browsing_safely +page-type: guide +sidebar: accessibilitysidebar +--- + +This article discusses making web content accessible for those with vestibular disorders, and those who support them, by taking advantage of personalization and accessibility settings built into the operating systems. Taking advantage of personalization settings can help prevent exposure to content leading to seizures and / or other physical reactions. + +## Personalization and accessibility settings + +From the article, "**[Understanding Success Criterion 2.3.1: Three Flashes or Below Threshold](https://www.w3.org/WAI/WCAG21/Understanding/three-flashes-or-below-threshold.html)**" + +> Flashing can be caused by the display, the computer rendering the image or by the content being rendered. The author has no control of the first two. They can be addressed by the design and speed of the display and computer + +### Hardware and operating systems on many computers offer control that is not afforded to developers + +The user can do much to protect himself by learning his operating system, its personalization and accessibility settings. Those in the public sector who must accommodate those with special sensitivities, should consider setting aside at least one work station and becoming familiar with its personalization and accessibility settings. Understanding personalization and accessibility settings can actually be a money-saving endeavor. One work station can be set up to accommodate both a low-vision individual (needs high-contrast) and to accommodate an individual with photosensitive susceptibilities, by, adjusting personalization and accessibility settings. + +### Use modern browsers. Learn personalization and accessibility settings + +Modern browsers support the CSS media feature [`prefers-reduced-motion`](/en-US/docs/Web/CSS/@media/prefers-reduced-motion). Browsers can detect whether a user has requested a reduced motion experience. The user would access this through an accessibility interface, as seen below. + +![Screen shot showing how to turn off animations in Windows 10.](android-remove-animations.png) + +CSS Transition events are supported. Examples include: + +- `transitionrun` +- `transitionstart` +- `transitionend` +- `transitioncancel` + +### Safari 10.1 and above (Desktop) + +Do not enable Auto-Play (does not work for GIFs) + +#### iOS Safari 10.3 and above (Mobile and Tablet) + +Select the "Reduce motion option" in OS Accessibility settings for Apple (image source: developers.google.com from Thomas Steiner's article "Move Ya! Or maybe, don't, if the user prefers-reduced-motion!"). This will not work on animated GIFs; the source of the animation is self-contained within a gif and is not affected by these settings.![Screen shot showing how to reduce motion on a MAC OS](macos-reduce-motion.png) + +#### Use Reader Mode on browsers + +- Enable Content Blockers; Gets rid of ads, reduces and/or removes distractions +- Enables text-to-speech +- In certain browsers, enable fonts by choice +- Enable Page Zoom + +#### Turn off animated GIFs in the browser + +Browsers offer much power to their users; it's just a matter of knowing where to go. Using Firefox as an example, it explains that by changing the value the **image.animation_mode** from "normal" to "none", all animated images will be blocked. To reverse it, you will have to change the value back to "normal" + +![Screenshot of image.animation.mode selected in Firefox](image_animation_mode.png) + +#### Use browser extensions + +- [Gif Blocker](https://chromewebstore.google.com/detail/gif-blocker/ahkidgegbmbnggcnmejhobepkaphkfhl?hl=en) For Chrome, GIF Blocker is an extension available at the web store. +- [Gif Scrubber](https://chromewebstore.google.com/detail/gif-scrubber/gbdacbnhlfdlllckelpdkgeklfjfgcmp?hl=en) Gif Scrubber is a chrome extension that allows you to control GIFs like a video player. There is a GitHub repository for it at **<https://github.com/0ui/gif-scrubber>** +- [Beeline Reader](https://www.beelinereader.com/) Beeline Reader has a browser extension that allows you to set up for grayscale and Dyslexi font, among other things + +![Screenshot showing modes of Beeline Reader a user can adjust in browser](beelinereader.png) + +### Take advantage Operating System accessibility features + +Most operating systems such as Windows 10, have accessibility options that are surprisingly powerful. Usually they are quite easy to find by typing (or saying) in the word, "Accessibility" in the search finder of the operating system. + +#### Turn off animations in the operating system + +In the Windows 10 operating system, the user has an ability to turn off animations. This will not work on animated GIFs; the source of the animation is self-contained within a gif and is not affected by these settings. + +![Screen shot showing how to turn off animations in Windows10](turnoffanimationsinwindows.png) + +#### Grayscale + +Those who have suffered traumatic brain injury (TBI) may be highly sensitive to color; it can require such a great "investment of cognitive energy" on their part, there's no energy for other daily tasks. Enabling grayscale presentation of the content reduces the cognitive workload. It may assist users with other disabilities, as well. An interesting discussion by users on the benefits of using grayscale may be found in the discussion thread, "[What is the "grayscale" setting for in accessibility options?](https://ask.metafilter.com/312049/What-is-the-grayscale-setting-for-in-accessibility-options)". Of particular interest is a user who has Photosensitive Epilepsy, and uses it when feeling "seizure-y". + +Most Operating Systems have a way to let the user make an adjustment on the workstation. In the screenshot below, you can see an example of Windows 10 Accessibility Settings allowing for color filters to be selected. Grayscale is enabled when the color filters button is toggled "on" + +![Shows Windows 10 Accessibility Settings for GrayScale](colorfiltersgrayscaleinwindows.png) + +## See also + +- [Accessibility](/en-US/docs/Web/Accessibility) +- [Accessibility learning path](/en-US/docs/Learn_web_development/Core/Accessibility) +- [Web accessibility for seizures and physical reactions](/en-US/docs/Web/Accessibility/Guides/Seizure_disorders) +- [Color vision simulation](https://firefox-source-docs.mozilla.org/devtools-user/accessibility_inspector/simulation/index.html) +- Discussion: "[What is the "grayscale" setting for in accessibility options?](https://ask.metafilter.com/312049/What-is-the-grayscale-setting-for-in-accessibility-options)" + +### Contributors + +Many, many thanks to Eric Eggert from [Knowbility;](https://knowbility.org/) for his discussions and huge help on this topic. diff --git a/files/en-us/web/accessibility/accessibility_colon__what_users_can_to_to_browse_safely/macos-reduce-motion.png b/files/en-us/web/accessibility/guides/browsing_safely/macos-reduce-motion.png similarity index 100% rename from files/en-us/web/accessibility/accessibility_colon__what_users_can_to_to_browse_safely/macos-reduce-motion.png rename to files/en-us/web/accessibility/guides/browsing_safely/macos-reduce-motion.png diff --git a/files/en-us/web/accessibility/accessibility_colon__what_users_can_to_to_browse_safely/turnoffanimationsinwindows.png b/files/en-us/web/accessibility/guides/browsing_safely/turnoffanimationsinwindows.png similarity index 100% rename from files/en-us/web/accessibility/accessibility_colon__what_users_can_to_to_browse_safely/turnoffanimationsinwindows.png rename to files/en-us/web/accessibility/guides/browsing_safely/turnoffanimationsinwindows.png diff --git a/files/en-us/web/accessibility/guides/cognitive_accessibility/index.md b/files/en-us/web/accessibility/guides/cognitive_accessibility/index.md new file mode 100644 index 000000000000000..b4569f3d9980d7b --- /dev/null +++ b/files/en-us/web/accessibility/guides/cognitive_accessibility/index.md @@ -0,0 +1,281 @@ +--- +title: Cognitive accessibility +slug: Web/Accessibility/Guides/Cognitive_accessibility +page-type: guide +sidebar: accessibilitysidebar +--- + +Cognitive accessibility covers accessibility considerations for people with cognition and learning disabilities. This document introduces cognitive accessibility and improving accessibility of the web for people with cognitive and learning differences. + +Cognitive impairment refers to a broad range of disabilities, from people with intellectual disabilities who may have the most-limited capabilities, to age-related issues with thinking and remembering. The range includes people with mental illnesses, such as depression and schizophrenia. It also includes people with learning disabilities, such as dyslexia and attention deficit hyperactivity disorder (ADHD). + +Though there is a lot of diversity within clinical definitions of cognitive impairments, people with them experience a common set of functional problems. These problems include difficulty with understanding content, remembering how to complete tasks, and confusion caused by inconsistent or non-traditional web page layouts. In this document, we focus on steps developers should take to improve the cognitive accessibility of their websites and applications. + +## Overview + +Cognitive and intellectual disabilities cover a large spectrum, and may be momentary, temporary, or permanent conditions. For example, dementia and Alzheimer's are permanent cognitive impairments that get progressively worse. Other permanent cognitive impairments include aphasia, speech and language, autism, ADD/ADHD, dyslexia, and dyscalculia. + +An example of a temporary cognitive impairment could be people affected by substances such as alcohol or drugs. Another form it can take is depression, such as when mourning the loss of a loved one, or being momentarily saddened by a tweet or video they just saw online. A third example could be sleep deprivation. + +It may seem like an overwhelming challenge to address the wide range of cognitive differences, especially when solutions for two different people may be conflicting. One way to handle this is to focus on cognitive skills. Cognitive skills include: + +- attention +- memory +- processing speed +- time management +- letters and language +- numbers symbols and math +- understanding and making choices + +A solid approach to providing accessible solutions for people with cognitive impairments includes: + +- delivering content in more than one way, such as by text-to-speech or by video; +- providing easily-understood content, such as text written using plain-language standards; +- focusing attention on important content; +- minimizing distractions, such as unnecessary content or advertisements; +- providing consistent web page layout and navigation; +- incorporating familiar elements, such as underlined links that are blue when not visited and purple when visited; +- dividing processes into logical, essential steps with progress indicators; +- making website authentication as easy as possible without compromising security; and +- making forms easy to complete, such as with clear error messages and error recovery. + +## WCAG Guidelines + +WCAG, Web Content Accessibility Guidelines, includes several guidelines to improve cognitive accessibility. These guidelines are published by the Web Accessibility Initiative (WAI) of the World Wide Web Consortium (W3C), the main international standards organization for the Internet. This group is also responsible for the [Accessible Rich Internet Application (ARIA)](/en-US/docs/Web/Accessibility/ARIA/Guides) guidelines. + +WCAG are guided by four principles: websites must be Perceivable, Operable, Understandable, and Robust. To this end, they define 17 specific guidelines, of which six are especially relevant for cognitive accessibility. + +All of the following guidelines help more than just people with cognitive disabilities. For example, being able to extend the expiration time on an application requiring an authentication code sent to a mobile device via text message helps with the following scenarios: + +- People with attention or anxiety disorders. +- People who have a poor short-term memory, or who are multitasking. +- People who are less technologically literate. +- People who have poor wireless reception. +- People who have motor control issues. + +## Adaptability + +[Guideline 1.3](https://www.w3.org/WAI/WCAG21/Understanding/adaptable) states "content should be **adaptable**". Create content that can be presented in different ways without losing information or structure. For example, provide {{glossary('responsive web design', 'responsive')}} layouts, with a single column mobile design. + +All information, including structure and relationships conveyed through the presentation, should be available in a form that can be perceived by all users to achieve this goal. For example, the information could be spoken aloud via a narration tool. Making your content capable of being understood by the software is a good way to help ensure it can be used by alternate presentational modes. + +## Time + +It is important to allow users the time they require to complete tasks. [Guideline 2.2](https://www.w3.org/WAI/WCAG21/Understanding/enough-time) states "provide users enough **time** to read and use content". + +A **time limit** is any process that happens without user initiation after a set time or on a periodic basis, such as being logged out after 30 minutes or having 15 minutes to make a purchase. People with cognitive disabilities may require more time to read content, or to perform functions such as filling out forms. Solutions include providing users enough additional time to complete tasks or eliminate time constraints altogether. + +### Timers + +Options for adjusting time requirements include: + +- Allowing the user to turn off or adjust the time to at least 10 times the original limit before encountering it. +- Alerting the user and providing a buffer of at least 20 seconds to extend the timeout duration by a factor of 10 with an action, such as hitting the space bar. + +Provide a toggle on content that allows users to enable a longer session time limit, or no session time limit at all. Examples of timed content include forms, timed reading exercises, and training materials. If the time limit is longer than 20 hours, accommodations are not required. + +### Moving, blinking, scrolling + +It is important not to distract users, especially ones with cognitive disabilities. + +If moving, blinking, scrolling, or auto-updating information starts automatically, lasts more than five seconds, and is presented in parallel with other content, the user must able to pause, stop, hide or control it, unless it's an essential functionality. "Essential" means that removing the moving, blinking, scrolling, or auto-updating information would fundamentally change the meaning of the content and/or functionality, **and** information and functionality cannot be achieved in another way that would conform. This includes animated GIFs, if the gif animates for more than 5 seconds. + +Additional timing criteria to consider are: + +- People who have cognitive or language limitations may need more time to read and to understand. For improved usability remove any time limit. Timed content should also be avoided, with exceptions for non-interactive synchronized media and real-time events. +- People with attention deficit disorders should be able to focus on content without distractions. The user should be able to postpone or suppress interruptions, except situations involving alerting a person to an emergency. This provides access to people with cognitive disabilities by enabling them to focus on the main purpose of the content. Enable the user to postpone content updates by providing a way to request content updates rather than updating automatically. Also, enable a way to make nonessential alerts optional. +- Ensure that people can continue an activity without loss of data after re-authenticating an expired session, for example, saving the state of a questionnaire. Make sure to save data in such a way that it can be modified after a user re-authenticates. Before re-authenticating, encode the data as hidden or encrypted. +- Providing warnings about inactivity that could result in data loss. When a timeout is used, tell people exactly how much time will cause the session to time out and result in lost data. The exception to this is preserving data for more than 20 hours when no actions are taken. + +## Navigation + +[Guideline 2.4](https://www.w3.org/WAI/WCAG21/Understanding/navigable) states "provide ways to help users navigate, find content, and determine where they are," and provides 10 guidelines to ensure the site is navigable and content is findable: + +### Include a `<title>` + +Make sure to include a {{HTMLElement('title')}} for the document, as titles provide a quick and easy to reference description of the screen's main point. People with cognitive disabilities, limited short-term memory, and reading disabilities all benefit from being able to identify the purpose of content this way. + +### Heading and labels + +Include clear and descriptive headings so users can easily find information and understand relationships between different content sections. Descriptive labels help users identify specific components within the content. People who read slowly and people with limited short-term memory benefit when section titles make it possible to predict what each section contains. + +### Section headings + +Headings help define overall organization of page content. They help facilitate navigation through page content sections, and provide a mechanism to aid comprehension. Examples of headings include chapters, sections and subsections of content, and so on. + +Headings are more obvious navigational aids compared to other methods to identify page content sections (borders, whitespace, horizontal rules, etc.). + +### Multiple ways to find content + +Different users prefer different methods of finding information, so it is important to provide multiple ways for users to locate content on your site. + +Providing more than one way to navigate your site can help people find information faster. Some users may prefer a table of contents, site map, or search functionality rather than reading and traversing through several pages to find what they need. Others may prefer to explore the site in a sequential manner, moving from page to page in order to best understand the site's layout, content, and concepts. + +### Ability to bypass blocks of content + +Providing a mechanism, such as a [skip link](/en-US/docs/Web/HTML/Reference/Elements/a#skip_links), to bypass blocks of content that are repeated on multiple web pages. + +### Focus order makes sense + +The order of focus for interactive elements should make sense. To achieve this, the DOM order should match the visual order, which in turn should match the tabbing order. If the tab order jumps around, especially in a way that does not match the visual order when navigating with a keyboard, users can become disoriented. + +### Focused elements should be visibly focused + +When a user navigates using a keyboard, the UI should make it obvious which element currently has focus. Don't alter or remove the browser's default [`:focus`](/en-US/docs/Web/CSS/:focus) styling, unless you're making focus even more obvious. + +### Link text conveys meaning + +The link's text should clearly and concisely communicate what the user should expect to be navigated to next if they choose to activate it. Poorly phrased link text may confuse users as to its purpose or destination. + +Some forms of assistive technology allow users to navigate by lists of all the links present on the page. Links will be removed from the context of their surrounding non-link content, making the need for understandable link text even more important. An example of a poor experience is a page full of links whose text reads, "Click here". Without indicating where "here" will take you, the link's purpose is unclear. + +For screen readers, it is vital that linked text describes the purpose of each link. If you have added content to links for screen readers, and that content is verbose and potentially confusing to sighted readers, consider clipping the added text to visually hide it from those not using assistive technologies. + +### Current location is available + +Users should be able to orient themselves within a site or application. This is especially important and helpful for people with short attention spans who may become confused when following a long series of navigation steps. + +All users benefit from information about where they are in a site's hierarchy, especially for sites or applications with large amounts of content or many subsections. [Breadcrumbs](/en-US/docs/Glossary/Breadcrumb), [site maps](/en-US/docs/Glossary/Site_map), and identifying the current page in the navigation as "current" are all techniques that help communicate the current location. + +## Readability + +[Guideline 3.1](https://www.w3.org/WAI/WCAG21/Understanding/readable) states "make text content readable and understandable". For some users, it is difficult to infer the meaning of a word or phrase from context, especially when the word or phrase is used in an unusual way, or has been given a specialized meaning. + +For these users, the ability to read and understand may depend on the availability of specific definitions or the expanded forms of acronyms or abbreviations. Some users may experience great difficulty in recognizing written words yet they understand extremely complex and sophisticated documents when the text is read aloud, or when key processes and ideas are illustrated visually. + +### Declare the language of the page and any content not in that main language + +The language of every page must be declared by using the [`lang`](/en-US/docs/Web/HTML/Reference/Global_attributes/lang) attribute on the {{HTMLElement('html')}} element. Include the `lang` attribute again on text that is in a language other than the main language of the document. + +Proper use of `lang` allows some screen readers to announce the text properly when converting it into synthetic speech. It also helps people who use text-to-speech software. + +### Define unusual words and word usage + +Some disabilities make it difficult to understand nonliteral word usage, such as idioms, colloquialisms, and specialized jargon. Non-native language speakers may also struggle with these terms. If a word or phrase has a unique meaning, in the document provide a definition inline or linked, within a glossary, or to an online dictionary. If a word or phrase is used to mean more than one thing, define each use. + +### Define abbreviations + +Abbreviations can be confusing for people who: + +- Have difficulty decoding words. +- Have limited memory. +- Have difficulty using context to aid understanding. +- Rely on screen magnifiers (which often reduce contextual cues). + +Provide an expanded form of the abbreviation the first time it is used, followed by the abbreviation placed within an {{HTMLElement('abbr')}} element. If an abbreviation has no expanded form, or is an abbreviation for a word that is not in the document's main language (such as Latin), explain its meaning. Also, consider using [ruby text](/en-US/docs/Web/HTML/Reference/Elements/ruby) for initialism (pronunciation of acronyms). + +### Reading level + +Content should be written as clearly as possible. A good rule to go by is to make content simple enough that it can be understood the first time. Methods to achieve this include: + +- Using short, simple words. +- Writing short sentences. +- Using active voice in the present tense. +- Using correct grammar and spelling. + +It helps users with cognitive disabilities to provide a text summary (sometimes referred to as a TL;DR, or "too long; didn't read") at a low reading level. Another technique you can use is providing accompanying visuals to help explain ideas, events, and processes. + +There are tools that can rate the level of your content. For example, this document has an average grade level of about 11. This means it should be easily understood by a native English speaker aged 16 to 17. Some tools can even provide suggestions to help simplify it. + +### Pronunciation + +There are multiple techniques that can help teach people how to pronounce words: + +- Provide the pronunciation immediately following the word. +- Link to a list of pronunciations. +- Provide a glossary with pronunciation. +- Use the {{HTMLElement('ruby')}} element to illustrate how a word is pronounced. + +Providing guidance on how to pronounce words helps many different kinds of people, including those who prefer to read aloud, non-native language speakers, and people who are unfamiliar with the meaning of a term in context. + +Another solution is to use glyphs or diacritical marks to illustrate pronunciation. However, if this technique is used, there must be a mechanism to turn it off. Further, it is helpful to link to a guide to the marks being used, as their meaning may not be obvious. + +## Predictability + +WCAG [Guideline 3.2](https://www.w3.org/WAI/WCAG21/Understanding/predictable) states "make web pages appear and operate in predictable ways". This is a tenet of good user experience design. Consistency is especially important for people with cognitive difficulties. This includes consistency in page layout and predictable interactive components. + +### Use activation, not focus to change context + +Creating a change in context should be intentional. Because of this, when a UI feature receives [focus](/en-US/docs/Web/API/HTMLElement/focus), it should not trigger further user-facing actions. Rather, users should need to "activate" a feature to trigger the change. + +### Change setting based on an active request + +Form control operation and data entry should result in predictable behavior. Changes in context can confuse users with cognitive disabilities, and should therefore only occur when it is clear that such a change will happen in response to the user's action. + +Changing state should require intentional user action. Examples of this are checking a checkbox, entering data or changing a select option. Also be sure to provide a submit button to initiate the change of context, and describe what will happen before the change is made. + +### Keep navigation consistent throughout the site + +Keep the navigation order consistent between pages. For example, if you have a navigation bar on multiple pages, make that navigation uniform across the site with the same links in the same location. This doesn't just apply to navigation: present all repeated components in the same relative order each time they appear. + +### Provide consistent labeling + +Identical functions should have similar labels every time they are utilized. Consistent button labels, alternative text for icons, and iconography for similar interactions and so on, even on different sections of your site, help all your users. + +### Be consistent and predictable, and use norms + +While unlabeled iconography is not the most effective method of conveying information, keeping the use of the icons (and if labeled, their label text) consistent helps people to understand what the icon represents. Similarly, don't change defaults like the browser's back button. If you need to redirect a user, let the user know about it beforehand. + +## Input Assistance + +[Guideline 3.3](https://www.w3.org/WAI/WCAG21/Understanding/input-assistance) helps to ensure accurate data entry, stating "help users avoid and correct mistakes". While we all make mistakes, some people are more likely to make mistakes, less likely to notice a mistake, or have a harder time correcting a mistake once they make one. + +Input Assistance guidelines aim to reduce the likelihood that users, especially those with disabilities, make a mistake, and, if they do make a mistake, increase the likelihood that they see and comprehend the error message and can successfully fix any errors. + +### Convey automated error detection + +Users need to be alerted to the error and informed of what is wrong. If there is client side error detection, observe the following guidelines to make the error as effective as possible when conveyed to the user: + +- The error must be described in the text. +- Ensure that the error message is as specific as possible. +- Provide text to identify incomplete required fields and text descriptions if a value entered is invalid. +- If the error prevented a form submission, focus on the error. If multiple errors are present, provide a summary, with each error linking to the related input. +- Include text along with use of icons, images, color and so on. Some people have difficulty understanding the meaning of icons and other visual cues. +- Other people may have difficulty understanding the text version of your error message. For these people, also provide things like icons and colors. +- Also, provide feedback on when there is a successful form submission. + +### Provide instructions for user input + +Start the form with text instructions on how to operate it. Include labels or instructions when users need to input information, using the {{HTMLElement('label')}}, {{HTMLElement('fieldset')}}, and {{HTMLElement('legend')}} elements to do so. + +Labels should be descriptive and positioned close to the input they relate to. When requiring a specific format for input, provide an example formatted in the proper way. Additionally, consider performing server-side validation to help format input data, to aid in the ease of user input. + +If a form control is required, indicate it both visually and [via code](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-required). If a form control changes context, describe what will happen in a way that the user will understand it before they cause the context change to happen. + +### Error Suggestion + +Provide suggested input to the user if an input error is automatically detected and suggestions for correction are known (unless doing so would jeopardize the security or purpose of the content). + +### Prevent catastrophes + +For submissions that cause, or can lead to, legal, financial, or other significant consequences, ensure that the submissions can be reviewed, confirmed, and/or are reversible. + +Data entered by the user should be checked for errors before submission, and the user should be given the opportunity to correct them. The user should be able to review, confirm, and correct information before final submission. Also, be sure to include a confirmation checkbox in addition to a submit button. + +If a submission causes a legal or financial transaction to occur, provide a stated time within which the request can be amended or canceled by the user. + +### Provide help + +Context-sensitive help should be made available. If a form requires text input, provide form instructions describing the purpose and the necessary input. Include spell checking and suggestions for long-form text input, as well as links to help and support material. If a specific data format is expected for input, provide an example. + +## Notes + +The above are good design practices. They will benefit everyone. + +- Many people with cognitive impairments also have physical disabilities. Websites must conform with the W3C's [Web Content Accessibility Guidelines](https://www.w3.org/WAI/standards-guidelines/wcag/). +- The W3C's [Cognitive and Learning Disabilities Accessibility Task Force](https://www.w3.org/WAI/GL/task-forces/coga/) produces web accessibility guidelines for people with cognitive impairments. +- WebAIM has a [Cognitive page](https://webaim.org/articles/cognitive/) of relevant information and resources. +- The United States Centers for Disease Control estimate that, as of 2018, 1 in 4 U.S. citizens have a disability and, of them, [cognitive impairment is the most common for young people](https://archive.cdc.gov/www_cdc_gov/media/releases/2018/p0816-disability.html). +- In the U.S., "intellectual disabilities" used to be called "mental retardation". In the U.K., "intellectual disabilities" is commonly called "learning disabilities" or "learning difficulties". + +## See also + +- [Accessibility Guidelines](https://extensionworkshop.com/documentation/develop/build-an-accessible-extension/) +- [What is accessibility](/en-US/docs/Learn_web_development/Core/Accessibility/What_is_accessibility) +- [Accessibility for seizure disorders](/en-US/docs/Web/Accessibility/Guides/Seizure_disorders) +- [Understanding WCAG Guidelines](/en-US/docs/Web/Accessibility/Guides/Understanding_WCAG) +- [Accessibility overview](/en-US/docs/Learn_web_development/Core/Accessibility) +- [Web Content Accessibility Guidelines](https://www.w3.org/WAI/standards-guidelines/wcag/), including [cognitive accessibility guidelines](#wcag_guidelines) +- [The W3C's Cognitive and Learning Disabilities Accessibility Task Force](https://www.w3.org/WAI/GL/task-forces/coga/) +- [WebAIM Cognitive information](https://webaim.org/articles/cognitive/) +- [CDC information on disabilities](https://www.cdc.gov/disability-and-health/) diff --git a/files/en-us/web/accessibility/understanding_colors_and_luminance/320px-red_saturations.svg.png b/files/en-us/web/accessibility/guides/colors_and_luminance/320px-red_saturations.svg.png similarity index 100% rename from files/en-us/web/accessibility/understanding_colors_and_luminance/320px-red_saturations.svg.png rename to files/en-us/web/accessibility/guides/colors_and_luminance/320px-red_saturations.svg.png diff --git a/files/en-us/web/accessibility/understanding_colors_and_luminance/conemosaics.jpg b/files/en-us/web/accessibility/guides/colors_and_luminance/conemosaics.jpg similarity index 100% rename from files/en-us/web/accessibility/understanding_colors_and_luminance/conemosaics.jpg rename to files/en-us/web/accessibility/guides/colors_and_luminance/conemosaics.jpg diff --git a/files/en-us/web/accessibility/guides/colors_and_luminance/index.md b/files/en-us/web/accessibility/guides/colors_and_luminance/index.md new file mode 100644 index 000000000000000..178969d83ce2388 --- /dev/null +++ b/files/en-us/web/accessibility/guides/colors_and_luminance/index.md @@ -0,0 +1,322 @@ +--- +title: "Web Accessibility: Understanding Colors and Luminance" +short-title: Colors and Luminance +slug: Web/Accessibility/Guides/Colors_and_Luminance +page-type: guide +sidebar: accessibilitysidebar +--- + +While understanding color, luminance, and saturation is important for design and readability for all sighted users, they are essential for those with reduced vision and color-deficient vision and those with specific neurological, cognitive, and other impairments. + +Accessibility guidelines define adequate [color contrast](/en-US/docs/Web/Accessibility/Guides/Understanding_WCAG/Perceivable/Color_contrast) for sighted users with reduced vision, as well as guidelines intended to help users with color insensitive vision, commonly referred to as "color blindness". Understanding color is also important in preventing [seizures and other physical reactions](/en-US/docs/Web/Accessibility/Guides/Seizure_disorders) in people with vestibular disorders or other neurological disorders. + +## Overview + +The choice of colors and their use is a significant component of accessibility. On the surface, the subject seems simple. Still, it is a complex subject because color perception is as much about the physiology of the eye and human brain processing as it is about light emitting from a computer screen. + +### Environment and perception + +Environment matters. Perception of color in a well-lit room will be different than perception of that same color on that same computer screen in a dark room. Regarding accessibility, using certain color combinations has more impact than others. Font size, [font style](https://www.nngroup.com/articles/glanceable-fonts/) (some fonts are so thin or fancy that they present accessibility problems on their own), background color, the size of the background space around the text, even pixel densities, and more all affect how color is delivered from the screen. + +A viewer's distance from the screen, the ambient background, the health of his eyes, and more all affect how that color is received by the viewer. How the viewer perceives color after it gets to their eyes is yet another matter, and can be affected by overall health. Fortunately, there are [media queries](/en-US/docs/Web/CSS/@media) that enable developers to provide styles based on user preferences, including [contrast](/en-US/docs/Web/CSS/@media/prefers-contrast) and [color scheme](/en-US/docs/Web/CSS/@media/prefers-color-scheme) preferences. + +When supported, the [Ambient Light Sensor](/en-US/docs/Web/API/AmbientLightSensor) interface returns the current light level or illuminance of the ambient light around the hosting device, enabling a web page to be aware of any change in the light intensity, and consequently, adjust the text accordingly. Additionally, the above media queries enable developers to provide alternative user experiences when user preferences indicate preferred contrast levels, automatically adjusting levels depending on the user's location and what kind of screen they are using. + +### Luminance and perception + +Color, contrast, and luminance are the most central and critical concepts to creating accessible web content with color. Luminance is of particular importance, however, because understanding what it is and how it is employed enables accessibility for those who are color-blind, as well as those who can perceive color. The luminance contrast enables the color blind to distinguish dark from light. + +Luminance must be established before the contrast may be. When speaking of color contrast, W3C formulas are incorporating luminance, not just the colors ("hues") themselves. + +### Terminology + +Terminology can be confusing because different terms often describe the same thing. "Luminance" and "Saturation" are particularly important to get right. For example, "saturation" is known as "chroma" in some circles. In others, "chroma" and "saturation" are two different concepts. The "L" in the HSL color space is sometimes referred to as "luminosity," and other times as "lightness." Even something seemingly simple, like naming common colors, can be open to debate. For example, the color "crimson red" may be described in hex values as `#990000` by some and `#DC143C` by others. For this document, we'll use terminology as it is defined in the W3C, in the [CSS Color Module Level 4](https://www.w3.org/TR/css-color-4/) + +When working with color, it's important to know which "color space" you are working in, as different color spaces map to different measurement systems. + +In color printing, your printer likely has cyan, magenta, yellow, and black (CMYK) ink cartridges. CMYK is a subtractive model wherein the four inks _remove_ specific wavelengths of light, reflecting only the narrow range each is associated with. RGB is an additive color model that adds different proportions of red, green, and blue lights. + +Currently, the {{glossary("RGB", "RGB color space")}} predominates as the space web developers work in. While HEX, RGB, and HSL color spaces are notated differently, browsers automatically convert values between these color notations. [CSS color modules](/en-US/docs/Web/CSS/CSS_colors) provide additional color spaces. Still, because of the current domination of the RGB color space in measuring color output, most calculations in this document are presumed to be in the RGB color space and, very specifically, in the sRGB color space. + +## The sRGB color space + +Color has many ways of being defined, as is apparent in the [`<color>` data type](/en-US/docs/Web/CSS/color_value), including RGB, RGB decimal, RGB percent, HSL, HWB, LCH, LAB, and CMYK, among others. + +For digital concerns, much of the technology has historically resided in the RGB color space. The RGB color model is extended to include "alpha" — RGBA — to allow specification of the opacity of a color. Other methods for measuring color involve measurements using other color spaces and are supported in modern displays and browsers. Still, color measurements in the RGB color space predominate, including in video production. + +Technologies, such as [OpenGL](https://en.wikipedia.org/wiki/OpenGL) and [Direct3D](https://en.wikipedia.org/wiki/Direct3D) incorporate support for the sRGB gamma curve, although some articles for OpenGL reference use of RGBA rather than sRGB. WebGL is usually in the RGBA format; see an example of how it is used in "[Clearing with colors](/en-US/docs/Web/API/WebGL_API/By_example/Clearing_with_colors)". + +### CSS color values + +It's important to know that there are variations even within one {{glossary("color space")}}, such as the {{glossary("RGB")}} color space. For example, variations of the RGB color space include **RGB**, **sRGB**, **Adobe RGB**, **Adobe Wide Gamut RGB**, and **RGBA**, among others. + +These are examples of the CSS notations used to define a color. Here the example color for each is a fully opaque magenta: + +```css +/* named color */ +color: magenta; + +/* sRGB value with percentage values */ +color: rgb(100% 0% 100%); +color: rgb(100% 0% 100% / 100%); + +/* by sRGB numeric values */ +color: rgb(255 0 255); +color: rgb(255 0 255 / 1); + +/* legacy rgb and rgba notation */ +color: rgb(100%, 0%, 100%); +color: rgba(255, 0, 255, 1); + +/* by sRGB value in hex */ +color: #f0f; /* #rgb, a shorthand for #rrggbb */ +color: #ff00ff; /* #rrggbb */ +color: #f0ff; /* #rgba */ +color: #ff00ffff; /* #rrggbbaa */ + +/* by HSL representation of the sRGB value */ +color: hsl(300 100% 50%); +color: hsl(300deg 100% 50% / 100%); + +/* by HWB representation of the sRGB value */ +color: hwb(300deg 0% 0%); +color: hwb(300 0% 0% / 1); + +/* by LAB representation of the sRGB value*/ +color: lab(60 93.56 -60.5); +color: lab(60 93.56 -60.5 / 1); + +/* representation in the CIELAB color spaces */ +color: oklch(0.7 0.32 328.37); +color: oklch(0.7 0.32 328.37 / 1); + +/* color() function in the XYZ color space */ +color: color(xyz-d65 0.59 0.28 0.96); +color: color(xyz-d65 0.59 0.28 0.96 / 1); +``` + +The first example uses one of the defined [named colors](/en-US/docs/Web/CSS/named-color). + +We can set the sRGB values directly as a percentage, with 0% being off (black) and 100% being the full value for that color. The values are in the order of red, green, and blue. We can also set the sRGB values directly by a number from 0 to 255. + +Shown after that are hex color values. Hexadecimal is a numbering system with base-16, where the 0-255 integer is represented by two digits ranging from 0-15 using the digits 0-9 and a-f for 10-15. Thus, `ff` = `255`, `00` = `0`, and `d5` = `200`. The '#' symbol precedes the color to indicate the value is hex. + +If all values are pairs of identical digits, the value can be represented by single digits that the browser will duplicate. Thus `f00` is the same as `ff0000`. If a fourth set of numbers is present, that value is the A in RGBA, the alpha channel defining transparency in terms of the opacity value of the color. A higher value means the color is more opaque and therefore, less transparent. In the examples above, the alpha value is `f`, `ff`, `1`, and `100%` for fully opaque. + +The example also shows the legacy syntax for both [`rgb()` and `rgba()`](/en-US/docs/Web/CSS/color_value/rgb#examples). The legacy syntax for color functions is comma-separated, with a separate function for when the alpha channel is included. New color functions only have one syntax with space-separated (rather than comma-separated) values, with the alpha channel, if present, being preceded by a slash. Modern syntax allows for mixing numbers and percents and supports the `none` keyword; the comma-separated legacy syntax does not. + +The following examples show "HSL", which stands for _Hue, Saturation, and Lightness_. HSL color values are considered by many to be more intuitive than RGB values. The color produced from the settings are still in the sRGB colorspace, but [`hsl()`](/en-US/docs/Web/CSS/color_value/hsl) is an intuitive syntax for many. The hue is adjusted as an angle, and it is easy to create a user interface using a knob or circular control to adjust the hue. Do note that HSL colors incorporate _lightness_, not _luminance_, which is a significant consideration. + +The next examples shows "HWB" which stands for _Hue, Whiteness, and Blackness_. With both `hsl()` and [`hwb()`](/en-US/docs/Web/CSS/color_value/hwb) the first value can be a [`<number>`](/en-US/docs/Web/CSS/number) or an [`<angle>`](/en-US/docs/Web/CSS/angle) value. When unitless, the value is interpreted as `deg` degrees. + +There are several other color functions and color spaces. The last three examples demonstrate representing magenta using the [`lab()`](/en-US/docs/Web/CSS/color_value/lab), [`oklch()`](/en-US/docs/Web/CSS/color_value/oklch), and [`color()`](/en-US/docs/Web/CSS/color_value/color) color functions. + +### Conversions + +As we saw, one color within the same color space may be expressed in many ways. Looking at how the RGB color space is used to describe the color "magenta", you can see that the same color may be expressed in a shorthand, three-digit hex number that converts to an rgb value as a six-digit hex number that also converts to the same rgb value, or as a rgba value, expressed in percentages. + +RGB is hardware-oriented, reflecting the use of CRTs. Many developers and designers prefer the intuitiveness of [`hsl()`](/en-US/docs/Web/CSS/color_value/hsl) notation. Fortunately, browsers convert from RGB to HSL automatically, and shift-clicking on colors in browser developer tools provides conversion functionality. + +In addition to developer tools, many tools can convert RGB to HSL for you and provide both the RGB hexadecimal and CSS function syntax. A great example of a tool that converts colors for you is Tom Jewett's "[mini color selector](https://colortutorial.design/microColorsC.html)" with HSL, RGB, and Hex options for checking contrast in the browser. Note that developer tools color pickers and this tool all provide WCAG [color contrast](https://webaim.org/resources/contrastchecker/) values. + +![Color picker with HSL and RGB, with color contrast values.](microcolorsc.jpg) + +As noted earlier, the [CSS color module](/en-US/docs/Web/CSS/CSS_colors) includes adding additional colorspaces, including [`lch()`](/en-US/docs/Web/CSS/color_value/lch) and [`oklch()`](/en-US/docs/Web/CSS/color_value/oklch) functional color notation and the [`lab()`](/en-US/docs/Web/CSS/color_value/lab) and [`oklab()`](/en-US/docs/Web/CSS/color_value/oklab) color coordinate systems, which can specify any visible color. That said, sRGB is still the default and preferred colorspace for accessibility because of its ubiquity. + +Where accessibility is concerned, however, standards and guidelines are currently written predominantly using the sRGB color space, especially as it applies to color contrast ratios. + +> [!NOTE] +> Almost all systems used today to view Web content assume sRGB encoding. Unless it is known that another color space will be used to process and display the content, authors should evaluate using sRGB colorspace. If using other color spaces, apply the principles of [minimum contrast ratios](https://webaim.org/articles/contrast/#sc143). + +### Querying color values + +The {{domxref('Window.getComputedStyle()')}} method returns values using the RGB Decimal Reference scale or via `color(srgb...)`. For example, calling `Window.getComputedStyle()` on a `<div>` with `background-color: #ff0000` set on it returns the computed background color as `rgb(255 0 0)` — the RGB Decimal reference. However, when [using relative colors](/en-US/docs/Web/CSS/CSS_colors/Relative_colors) (for example `background-color: rgb(from blue 255 0 0)`), calling `Window.getComputedStyle()` returns the computed background color as `color(srgb 1 0 0)`. Being tied to computer hardware, `Window.getComputedStyle()` measures color in terms of RGB, not how the human eye perceives color. + +### Red / green color blindness + +Protanopia is a color vision deficiency in which the eye has no red cones; sRGB can still be perceived via green cones, though darker than normal vision. Both protan (red deficient) and deutan (green deficient) deficiencies cause difficulty distinguishing _between_ red and green. + +Developer tools can help simulate color vision differences right in your browser. For example, Firefox's Accessibility Inspector enables simulating protanopia, deuteranopia, tritanopia, achromatopsia, and contrast loss right in the accessibility panel. + +![Snippet of Firefox developer tools showing the simulate popup](simulate_color_differences.jpg) + +## Luminance and Contrast + +### Contrast + +The contrast between colors ("hues") is a critical component, but the use of color ("hues") alone is not enough to create accessible content. As mentioned before, any calculation of contrast must include luminance. + +In addition, the "shape" of the text itself will matter. Thin letters will be harder to read than thick ones; all typefaces need space to "breathe" for human perception. + +### Contrast and font size + +[WCAG contrast guidelines](/en-US/docs/Web/Accessibility/Guides/Understanding_WCAG/Perceivable#guideline_1.4_make_it_easier_for_users_to_see_and_hear_content_including_separating_foreground_from_background) define "large" text as text that is `18pt` (approximately `24px`) or larger when {{cssxref('font-weight')}} is `normal` and `14pt` (approximately `18.7px`) for `bold` text. Stating: + +_Text that is larger and has wider character strokes is easier to read at lower contrast. Therefore, the contrast requirement for larger text is lower. This allows authors to use a wider range of color choices for large text, which is helpful for the design of pages, particularly titles._ + +While larger text does not require as great color contrast with its background as smaller text, increasing font size is not a panacea. + +"Normal" print is usually considered 11.5pt to 12pt, equivalent to 16px on screen. While smaller font may be legible — a user can make out letters at \~70% accuracy — that is not readable. A 16px font size is generally readable for people with normal vision. Someone with 20/40 needs twice that, about a 31px font. This is why the WCAG guidelines require that users have the ability to zoom any text larger. + +While a text displayed too small is hard to read, so is a text that is too large. For users with 20/20 vision, with a text size greater than approximately 96px, reading speed decreases. Also, when there is a large disparity between the smallest and largest font size on a page, the larger text will become less readable if users enlarge the smaller text on the page, as most browsers zoom all text as the user zooms. + +In general, for accessibility purposes, the more contrast, the better. That changes with animation. "Safer" animation means images with less contrast, not more. For more on color contrast in animation, see [Three Flashes or Below Threshold Understanding SC 2.3.1](https://www.w3.org/TR/UNDERSTANDING-WCAG20/seizure-does-not-violate.html) + +Also, note that icons need sufficient contrast for perception. See [WCAG 2.1 technique G207](https://www.w3.org/WAI/WCAG21/Techniques/general/G207) + +### Luminance + +It is the difference in the luminance of a color that enables us to see the contrast. Relative luminance is defined in WCAG as "the relative brightness of any point in a colorspace, normalized to 0 for darkest black and 1 for lightest white." + +This statement is of course accurate, but may be confusing when used in reference to the RGB color space, which is an integer between 0 and 255. White has 100% relative luminance, black has 0% relative luminance (in most but not all literature). Interpreting for the W3C standard above, that would mean that white, normalized to 1, would have an RGB value of `rgb(255 255 255)` and black, normalized to 0, would have an RGB value of `rgb(0 0 0)`. Note that black and white can also be written as `rgb(100% 100% 100%)` and `rgb(0% 0% 0%)` respectively, which may be more intuitive. + +So, where do these numbers of 0 to 255 come from? Historically, graphics engines stored the color channels as a single byte, which means a range of integers between 0 and 255. + +The luminances of the primary colors are different. Yellow has a greater luminance than blue, for example. This was done by way of design, _to achieve white alignment of the monitor_, according to the NASA document, "[Luminance Contrast in Color Graphics](https://colorusage.arc.nasa.gov/design_lum_1.php)" + +A color contrast ratio is meaningless without its luminance component, and once luminance is established, the color contrast ratio can be established. + +Where human perception is concerned, a difference in luminance matters more than a color difference. This is important, as luminance contrast enables the development of content that even those with color blindness can see. With this understanding, luminance may be manipulated so that colors that are difficult to see because of their low luminance could be made more legible by placing these colors against another with contrasting luminance. An interesting study by NASA on the color blue, for example, noted that this color, which has low luminance, can be made legible if _care was taken to achieve adequate luminance contrast_ (From the article, [Designing with blue](https://colorusage.arc.nasa.gov/blue_2.php)) + +Calculations for relative luminance are not casual ones. Luckily, there are [online luminance and contrast checkers](https://www.siegemedia.com/contrast-ratio) available, and even instructions on how to [calculate relative luminance](https://www.w3.org/TR/WCAG21/#dfn-relative-luminance). + +## Perceiving color + +Color is our perception of the narrow band of visible light, from red through yellow and green to blue. Our sensitivity to these various hues of color are not equal. The light sensitive cells in our [eyes](https://www.verywellhealth.com/eye-cones-5088699), called cones, are tuned to perceive some colors more than others. About 65% of cones are _most_ sensitive to a yellow/green, but also respond to red (we'll call these "red" cones). 30% are green sensitive, and only [5% are blue sensitive](https://journals.plos.org/plosone/article?id=10.1371/journal.pone.0144891#sec001). While there are far fewer blue-sensitive cones than the other two types, these cones are very sensitive, which partially makes up for their smaller numbers. + +Deep, pure blue is perceived differently than other colors as blue cones do not contribute to luminance and we have far fewer blue cones than red or green. + +![On the left is a cone mosaic of standard vision, and on the right is that of someone with protanopia where they are missing the red cones.](conemosaics.jpg) + +On the left is the central cone mosaic of standard vision, and on the right is that of someone with protanopia, a form of color vision deficiency, where they are missing the red cones. (Illustration by Mark Fairchild of RIT, [Wikimedia Commons](https://commons.wikimedia.org/wiki/File:ConeMosaics.jpg)) + +The red and the green cones join together to create luminance, which we can think of as lightness/darkness without regard to hue. Separately, the red, green, and blue cones allow for standard vision to perceive millions of colors. For accessibility, it's important to know that our brain processes luminance separately from color (hue and colorfulness). + +Luminance provides for fine vision details, including differentiating edges and text. Hue and colorfulness carry a third of the detail of luminance. Image data compression takes advantage of this fact. As an example, [h.264 video codec](/en-US/docs/Web/Media/Guides/Formats/Video_codecs) samples color at a fourth of the resolution of the luminance. + +For accessibility, this means that luminance contrast is critically important for text. Color, as in hue and colorfulness, is important for _distinguishing_ items such as different lines on a map or bars in a graph. + +Another essential point to consider is the color or luminance that is surrounding a color. Colors appear differently depending on what is surrounding them. In the following image, both the yellow dots and the grey squares are the same sRGB color. Context-sensitive color perception makes them appear different; your brain's image processing adjusts the perception based on what it thinks is in shadow or not. + +![An image of a checkerboard, where identical colors look different if they are in shadow](yellowdotcheckershadow_dlyon.png) + +The yellow dots in this image are identical colors on your monitor, but they appear different due to context. (Image D.Lyon) + +Our contrast, lightness, and color perception are affected by the context of the nearby colors and other features of a design or image. This makes predicting contrast challenging. It is not merely a mathematical ratio between two colors. + +To summarize, color is as much about human physiology and perception in the brain as it is about measuring light from a computer screen. It's also important to understand that the ambient light environment affects the ability to perceive color and contrast. Light and its measurements are linear, but human vision and perception are not. + +## Adaptation + +Our eyes don't adapt equally, in the same way, going from light areas to dark ones and vice versa. This is due to the physiological ways our eyes are built. This affects the ability of a user to read text against a background. At least two kinds of adaptation take place: local adaptation and adaptation to an ambient environment. + +Local adaptation occurs right on the "page" a reader is looking at. For example, if you have blue text within a gray "highlighted" area, your eyes will perceive that exact blue text with a gray highlight differently if it is in a black {{HTMLElement("div")}}, or a white one. This is called _local_ adaptation. This difference in the ability to perceive the text is affected even though the room's ambient lighting does not change. + +The implication is that web developers who seek to improve the legibility of text against a background can take advantage of the principles of local adaptation. + +Dark adaptation to low luminance is slow. When you come in from outside, where the sun is bright, and walk into a dark room, you are experiencing dark adaptation. It can take a few minutes to adjust to this. + +Light adaptation is the reverse. Going from a dark room into bright sunlight is quicker but can also hurt. + +The implication is that web developers who seek to improve the legibility of text in which the ambient conditions of a room have changed can take advantage of the `AmbientLightSensor` interface and the [`prefers-contrast`](/en-US/docs/Web/CSS/@media/prefers-contrast) media query. + +## Saturation + +Saturation deserves a special mention in discussions about color ("hues") and accessibility. Generally speaking, most focus is on luminance when attempting to ensure enough contrast between text and its background or evaluating the possibility of inducing seizures in those sensitive to photosensitive seizures. One aspect of color ("hues"), independent of luminance, deserves special attention as it applies to accessibility: the concept of saturation. This is due to its ability to cause seizures in those susceptible to photosensitive seizures, regardless of color's luminance. As discussed in [the particular case of red](#the_special_case_of_red), [Harding et al. 2005](https://onlinelibrary.wiley.com/doi/pdf/10.1111/j.1528-1167.2005.31305.x) noted that, _irrespective of luminance, a transition to or from a saturated red is also considered a risk_. + +Saturation is sometimes described as the "purity" or "intensity" of a color. Although these are good definitions for "pigments" in an artist's paint set, they are not as accurate as color definitions from a computer screen. + +When it comes to color on a monitor, saturated colors are of a particular wavelength. While the definition of saturation for each color space may differ, saturation is readily measured. The key is to know which color space you are working in and be ready to convert it if necessary. + +The color spaces most frequently considered when discussing photosensitivity are the RGB, HSL, and HSV, also known as HSB, color spaces. The HSV color space, which stands for _hue_, _saturation_, and _value_, and the synonym HSB, which stands for _hue_, _saturation_, and _brightness_, are represented in CSS as [`hwb()`](/en-US/docs/Web/CSS/color_value/hwb) for _hue_, _whiteness_, and _blackness_. + +It's important to know what color space you're working with. For example, saturated colors have a lightness of `0.5` in HSL, while in HWB, they have a value `1`. Saturation in the RGB color space is usually indicated by an RGB value of `255` or `100%` for the color in question. For example, a saturated red of hex value `#ff0000` has an RGB value of `rgb(255 0 0)` and an HSL value of `hsl(0 100% 50%)`. A different saturated red with a hex value of `#ff3300` has an RGB value of `rgb(255 51 0)` and an HSL value of `hsl(12 100% 50%)`. Both are "saturated" reds. They are two different "hues" but are both considered to be a saturated color. + +Saturation is not brightness. Brightness refers to how much white or black is mixed in with a color. One can decrease saturation by adding white, black, or gray to the color; to take the example further, brightness can be increased by adding white, reducing saturation. A typical example is to add white to red to get the color pink. Pink is considered a desaturated red. + +### Saturation and luminance + +There is a loss of saturation at the extremes of luminance and the extremes of black and white. In NASA's [effect of luminance on saturation](https://colorusage.arc.nasa.gov/design_lum_1.php), they point out that there is a loss of saturation at low luminances, and also, "…the loss of saturation at high luminances–the colors converge on white." + +## Color combinations + +Contrast alone is not enough when it comes to accessibility considerations. In the case of animation, certain color combinations are more likely to cause photosensitive seizures to those who are susceptible to them than others. For example, alternating flashes between red and blue is more problematic than alternating flashes between green and blue. It has been theorized that this is because the "red" sensitive cones of our eyes, which tend to cluster around the fovea (near the center), are physically located at a different location than the "blue" sensitive cones of our eyes, which are located away from the fovea and towards the rims. The electrical signals from the eye to the brain have much to resolve between them as the information is processed in our brains. + +Some colors more likely to [cause epileptic seizures](https://www.epilepsy.com/sites/default/files/2022-10/Epilepsia_2022_fisher_visually_sensitive_seizures.pdf). Complexities underlying brain dynamics can be modulated by some color combinations more than the others. For example, red-blue flickering stimulus causes larger cortical excitation than red-green or blue-green stimulus. + +Certain color combinations can be very problematic on a computer monitor or mobile device, and some color combinations can interfere with some impairments. The combination of red/blue is one such example. + +- Never rely on hue alone for differentiating details. Adequate luminance contrast is required. +- The green in a monitor makes up the vast majority of luminance (light), so it will usually be a significant part of the lighter colors. + +### Working with blue + +Some people cannot differentiate between all colors. Some colors, such as pure blue, are low in luminance. Colors that are low in luminance should be the darker of contrasting colors. Blue is also very low in resolution. There are far fewer blue cones, and they are scattered in our peripheral vision and not present in our central vision. The human eye sees blue at a lower resolution than green and red. + +This leads to some blue color use guidelines: + +- Pure blues should typically be the darkest of two colors. +- When using blue as the lighter of the two colors, add green to increase contrast and improve readability. + +The nature of blue light causes it to focus at a different location on the retina than red, so a pure red and a pure blue color that are immediately adjacent and touching may "shimmer" when next to each other. + +## The special case of red + +Not all colors ("hue") are processed similarly by our brains. Human physiology and psychology are affected by the color red, generally speaking, in ways different from that of other colors. We respond physiologically as well as psychologically to colors. For example, it has been demonstrated that [some colors are more likely to cause epileptic fits than others](https://www.sciencedaily.com/releases/2009/09/090925092858.htm). Some devices offer a ["grayscale" setting as an accessibility option](https://ask.metafilter.com/312049/What-is-the-grayscale-setting-for-in-accessibility-options)" which can help people who are photo-sensitive. To mimic the grayscale setting, use the CSS {{cssxref("filter")}} property with a [`grayscale()`](/en-US/docs/Web/CSS/filter-function/grayscale) or [`saturate()`](/en-US/docs/Web/CSS/filter-function/saturate) [`<filter-function>`](/en-US/docs/Web/CSS/filter-function). + +### Saturated red + +"Saturated Red" is a special, dangerous case, and there are special tests for it. + +The concept of color saturation is a difficult one to understand when only looking at numbers and terminology, so consider looking at the image below to illustrate the concept of saturation in a color: + +![Red Saturation from Wikimedia Commons svg saved as png Attribution: Datumizer [CC0]](320px-red_saturations.svg.png) + +The same "color" proceeds from least saturated on the left-hand side to most saturated on the right-hand side. + +_More than one "red" color may be considered a "saturated" red._ For example, the color `#990000` at `hsl(0 100% 30%)` is fully saturated but is less bright than the colors described above. Similarly, the color `#8b0000` also has a saturation of 100%. + +Not all saturated reds may be represented well in the RGB spectrum or other spectrums commonly used in web development. According to Wikipedia's page on "Shades of Red", the color "Carmine" is a saturated red which, in its pigment form, mostly contains red light with wavelengths longer than 600nm; the article makes the special note that "Carmine" is close to the extreme spectrum. This places it far beyond standard gamuts (RGB and CMYK), and its given RGB value is a poor approximation only." + +### Saturated red flashing + +In addition to a red environment affecting the cognitive function of those with traumatic brain injury, color in the red spectrum wavelength requires special attention and tests. + +Gregg Vanderheiden, when testing the _Photosensitive epilepsy analysis tool_, noted seizure rates were much higher than expected. They found that we are much more sensitive to saturated red flashing. (See the video, [The Photosensitive epilepsy analysis tool](https://www.pbs.org/video/university-place-the-photosensitive-epilepsy-analysis-tool-ep-429/).) + +### Flashing and seizures + +Continuous flashing brighter/darker at rates higher than three flashes per second has been shown to induce photic seizures in some people. It has also been found that specific, very regular, high-contrast patterns, such as parallel white and black stripes, can also induce seizures. + +[Harding et al. 2005](https://onlinelibrary.wiley.com/doi/pdf/10.1111/j.1528-1167.2005.31305.x) present several fundamental guidelines: + +1. Single, double, or triple flashes in one second are acceptable, but a sequence of flashes is not recommended when more than three flashes happen within one second. +2. When displaying light and dark stripes, the pattern should display no more than five light–dark pairs of stripes, if the stripes change direction, oscillate, flash, or reverse in contrast or eight light–dark pairs of stripes, if the pattern is unchanging or continuously and smoothly drifting in one direction. + +For more recommendations, see the paper [Photic- and Pattern-induced Seizures: Expert Consensus of the Epilepsy Foundation of America](https://onlinelibrary.wiley.com/doi/epdf/10.1111/j.1528-1167.2005.31405.x). + +## Psychophysical aspects of color + +Color as in hues and saturation can affect our mood, and enhance — or de-enhance — our interactive experiences. + +### Examples of color's effect beyond vision + +- **Color can be culturally dependent:** [A Cross-Cultural Study of the Affective Meanings of Color](https://journals.sagepub.com/doi/10.1177/002202217300400201) +- **Color affects our emotions:** [Color and emotion: effects of hue, saturation, and brightness](https://pubmed.ncbi.nlm.nih.gov/28612080/) +- **Higher contrasts can also have a positive affect on our emotions:** [Emotion Variation from Controlling Contrast of Visual Contents through EEG-Based Deep Emotion Recognition](https://pubmed.ncbi.nlm.nih.gov/32823741/) +- **Some colors can affect our perception of time:** [Color and time perception: Evidence for temporal overestimation of blue stimuli](https://pubmed.ncbi.nlm.nih.gov/29374198/) +- **Blue also has a significant effect on brightness and glare:** [Blue and glare & brightness](https://pubmed.ncbi.nlm.nih.gov/31288107/) +- **Red tinted glasses can provide increased happiness or joy:** [Looking Through "Rose-Tinted" Glasses: The Influence of Tint on Visual Affective Processing](https://pubmed.ncbi.nlm.nih.gov/31244627/) +- **Red is well known to have significant effects on our behavior:** [How the Color Red Influences Our Behavior](https://www.scientificamerican.com/article/how-the-color-red-influences-our-behavior/), Scientific American, S. Martinez-Conde, Stephen L. Macknik +- **Red Environment:** Studies have shown that for those who suffer Traumatic Brain Injury, [cognitive function is reduced in a red environment](https://pubmed.ncbi.nlm.nih.gov/20649469/). + +## See also + +- [Accessibility](/en-US/docs/Web/Accessibility) +- [Accessibility learning path](/en-US/docs/Learn_web_development/Core/Accessibility) +- CSS [`color`](/en-US/docs/Web/CSS/color) property +- [`<color>`](/en-US/docs/Web/CSS/color_value) data type +- [Web accessibility for seizures and physical reactions](/en-US/docs/Web/Accessibility/Guides/Seizure_disorders) +- [How the Color Red Influences Our Behavior](https://www.scientificamerican.com/article/how-the-color-red-influences-our-behavior/) Scientific American By Susana Martinez-Conde, Stephen L. Macknik on November 1, 2014 +- [Red Desaturation](https://www.smartoptometry.app/red-desaturation/) The human eye is so sensitively "tuned" to red, that ophthalmologists set up a test using it, assessing the integrity of the optic nerve. +- [Photic- and pattern-induced seizures: expert consensus of the Epilepsy Foundation of America Working Group](https://onlinelibrary.wiley.com/doi/pdf/10.1111/j.1528-1167.2005.31305.x) diff --git a/files/en-us/web/accessibility/understanding_colors_and_luminance/microcolorsc.jpg b/files/en-us/web/accessibility/guides/colors_and_luminance/microcolorsc.jpg similarity index 100% rename from files/en-us/web/accessibility/understanding_colors_and_luminance/microcolorsc.jpg rename to files/en-us/web/accessibility/guides/colors_and_luminance/microcolorsc.jpg diff --git a/files/en-us/web/accessibility/understanding_colors_and_luminance/simulate_color_differences.jpg b/files/en-us/web/accessibility/guides/colors_and_luminance/simulate_color_differences.jpg similarity index 100% rename from files/en-us/web/accessibility/understanding_colors_and_luminance/simulate_color_differences.jpg rename to files/en-us/web/accessibility/guides/colors_and_luminance/simulate_color_differences.jpg diff --git a/files/en-us/web/accessibility/understanding_colors_and_luminance/yellowdotcheckershadow_dlyon.png b/files/en-us/web/accessibility/guides/colors_and_luminance/yellowdotcheckershadow_dlyon.png similarity index 100% rename from files/en-us/web/accessibility/understanding_colors_and_luminance/yellowdotcheckershadow_dlyon.png rename to files/en-us/web/accessibility/guides/colors_and_luminance/yellowdotcheckershadow_dlyon.png diff --git a/files/en-us/web/accessibility/guides/index.md b/files/en-us/web/accessibility/guides/index.md new file mode 100644 index 000000000000000..c61dc99664c777c --- /dev/null +++ b/files/en-us/web/accessibility/guides/index.md @@ -0,0 +1,12 @@ +--- +title: Accessibility guides +short-title: Guides +slug: Web/Accessibility/Guides +page-type: listing-page +sidebar: accessibilitysidebar +--- + +This page lists guides for web accessibility. +They're intended to help you understand what kinds of things are possible to improve the accessibility of your projects on the web. + +{{SubPagesWithSummaries}} diff --git a/files/en-us/web/accessibility/guides/information_for_web_authors/index.md b/files/en-us/web/accessibility/guides/information_for_web_authors/index.md new file mode 100644 index 000000000000000..00dcc8e9a66df1a --- /dev/null +++ b/files/en-us/web/accessibility/guides/information_for_web_authors/index.md @@ -0,0 +1,48 @@ +--- +title: Accessibility information for web authors +short-title: Information for web authors +slug: Web/Accessibility/Guides/Information_for_Web_authors +page-type: guide +sidebar: accessibilitysidebar +--- + +This document lists guidelines and regulations, how-to's, and tools for checking and repairing accessibility problems with websites. + +## Guidelines and Regulations + +- [<abbr>ARIA</abbr> Authoring Practices Guide (<abbr>APG</abbr>)](https://www.w3.org/WAI/ARIA/apg/) + - : Guide to accessibility semantics defined by the Accessible Rich Internet Application (<abbr>ARIA</abbr>) specification to create accessible web experiences. Describes how to apply accessibility semantics to common design patterns and widgets, providing design patterns and functional examples. +- [Web Content Accessibility Guidelines (<abbr>WCAG</abbr>)](https://www.w3.org/WAI/standards-guidelines/wcag/) + - : Another important set of guidelines from the W3C _Web Accessibility Initiative (<abbr>WAI</abbr>)_. The European Union is looking to base their upcoming accessibility regulations on these guidelines. These guidelines are discussed on the [<abbr>WAI</abbr> interest group discussion list](https://www.w3.org/WAI/about/groups/waiig/#mailinglist). +- [ARIA on this site](/en-US/docs/Web/Accessibility/ARIA) + - : <abbr>MDN</abbr> guide to all the [ARIA roles](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles) and [ARIA properties](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes), including best practices, related roles and properties, and examples. + +## How-to's + +- [Accessibility for teams](https://digital.gov/guides/accessibility-for-teams/) + - : A brief guide from the U.S. General Services administration's Technology Transformation Services covering several accessibility topics with links to "how-to" videos and to related WCAG references. +- [Accessible Web Page Authoring](https://www.ibm.com/able/requirements/requirements/) + - : IBM has made their accessibility requirements that need to be met public and interactive. + +## Automated Checking & Repair + +Use a tool to quickly check for common errors in your browser. + +- [HTML CodeSniffer](https://squizlabs.github.io/HTML_CodeSniffer/) +- [aXe](https://chromewebstore.google.com/detail/axe-devtools-web-accessib/lhdoppojpmngadmnindnejefpokejbdd?hl=en-US) +- [Lighthouse Accessibility Audit](https://developer.chrome.com/docs/lighthouse/overview/) +- [Accessibility Insights](https://accessibilityinsights.io/) +- [<abbr>WAVE</abbr>](https://wave.webaim.org/extension/) + +Tools to integrate into your build process, programmatically adding accessibility tests, so you can catch errors as you develop your web application: + +- [axe-core](https://github.com/dequelabs/axe-core) +- [jsx-a11y](https://github.com/jsx-eslint/eslint-plugin-jsx-a11y) +- [Lighthouse Audits](https://github.com/GoogleChrome/lighthouse/blob/main/docs/readme.md#using-programmatically) +- [AccessLint.js](https://github.com/accesslint/accesslint.js/tree/master) + +Continuous integration tools to find accessibility issues in your GitHub pull requests: + +- [AccessLint](https://accesslint.com/) + +While best to test your web applications with real users, you can simulate color blindness, low vision, low and contrast, and zooming. You should always test your site with out a mouse and touch to test keyboard navigation. You may also want to try your site using voice commands. Try disabling your mouse and using browser extensions like [Web Disability Simulator](https://chromewebstore.google.com/detail/web-disability-simulator/olioanlbgbpmdlgjnnampnnlohigkjla) diff --git a/files/en-us/web/accessibility/guides/keyboard-navigable_javascript_widgets/index.md b/files/en-us/web/accessibility/guides/keyboard-navigable_javascript_widgets/index.md new file mode 100644 index 000000000000000..f87a9cd58043319 --- /dev/null +++ b/files/en-us/web/accessibility/guides/keyboard-navigable_javascript_widgets/index.md @@ -0,0 +1,160 @@ +--- +title: Keyboard-navigable JavaScript widgets +slug: Web/Accessibility/Guides/Keyboard-navigable_JavaScript_widgets +page-type: guide +sidebar: accessibilitysidebar +--- + +Web applications often use JavaScript to mimic desktop widgets such as menus, tree views, rich text fields, and tab panels. These widgets are typically composed of {{ HTMLElement("div") }} and {{ HTMLElement("span") }} elements that do not, by nature, offer the same keyboard functionality that their desktop counterparts do. This document describes techniques to make JavaScript widgets accessible with the keyboard. + +## Using tabindex + +By default, when people use the tab key to browse a webpage, only interactive elements (like links, form controls) get focused. With the `tabindex` [global attribute](/en-US/docs/Web/HTML/Reference/Global_attributes), authors can make other elements focusable, too. When set to `0`, the element becomes focusable by keyboard and script. When set to `-1`, the element becomes focusable by script, but it does not become part of the keyboard focus order. + +The order in which elements gain focus when using a keyboard, is the source order by default. In exceptional circumstances, authors may want to redefine the order. To do this, authors can set `tabindex` to any positive number. + +> [!WARNING] +> Avoid using positive values for `tabindex`. Elements with a positive `tabindex` are put before the default interactive elements on the page, which means page authors will have to set (and maintain) `tabindex` values for all focusable elements on the page whenever they use one or more positive values for `tabindex`. + +The following table describes `tabindex` behavior in modern browsers: + +<table> + <thead> + <tr> + <th><code>tabindex</code> attribute</th> + <th>Focusable with mouse or JavaScript via <code>element.focus()</code></th> + <th>Tab navigable</th> + </tr> + </thead> + <tbody> + <tr> + <td>not present</td> + <td>Follows the platform convention of the element (yes for form controls, links, etc.).</td> + <td>Follows the platform convention of the element.</td> + </tr> + <tr> + <td>Negative (i.e., <code>tabindex="-1"</code>)</td> + <td>Yes</td> + <td>No; author must focus the element with <a href="/en-US/docs/Web/API/HTMLElement/focus"><code>focus()</code></a> in response to arrow or other key presses.</td> + </tr> + <tr> + <td>Zero (i.e., <code>tabindex="0"</code>)</td> + <td>Yes</td> + <td>In tab order relative to element's position in document (note that interactive elements like {{HTMLElement('a')}} have this behavior by default, they don't need the attribute).</td> + </tr> + <tr> + <td>Positive (e.g., <code>tabindex="33"</code>)</td> + <td>Yes</td> + <td><code>tabindex</code> value determines where this element is positioned in the tab order: smaller values will position elements earlier in the tab order than larger values (for example, <code>tabindex="7"</code> will be positioned before <code>tabindex="11"</code>).</td> + </tr> + </tbody> +</table> + +### Non-native controls + +Native HTML elements that are interactive, like {{ HTMLElement("a") }}, {{ HTMLElement("input") }} and {{ HTMLElement("select") }}, are already accessible by keyboards, so to use one of them is the fastest path to make components work with keyboards. + +Authors can also make a {{ HTMLElement("div") }} or {{ HTMLElement("span") }} keyboard accessible by adding a `tabindex` of `0`. This is particularly useful for components that use interactive elements that do not exist in HTML. + +### Grouping controls + +For grouping widgets such as menus, tablists, grids, or tree views, the parent element should be in the tab order (`tabindex="0"`), and each descendant choice/tab/cell/row should be removed from the tab order (`tabindex="-1"`). Users should be able to navigate the descendant elements using arrow keys. (For a full description of the keyboard support that is normally expected for typical widgets, see the [WAI-ARIA Authoring Practices](https://www.w3.org/WAI/ARIA/apg/).) + +The example below shows this technique used with a nested menu control. Once keyboard focus lands on the containing {{ HTMLElement("ul") }} element, the JavaScript developer must programmatically manage focus and respond to arrow keys. For techniques for managing focus within widgets, see "Managing focus inside groups" below. + +```html +<ul id="mb1" tabindex="0"> + <li id="mb1_menu1" tabindex="-1"> + Font + <ul id="fontMenu" title="Font" tabindex="-1"> + <li id="sans-serif" tabindex="-1">Sans-serif</li> + <li id="serif" tabindex="-1">Serif</li> + <li id="monospace" tabindex="-1">Monospace</li> + <li id="fantasy" tabindex="-1">Fantasy</li> + </ul> + </li> + <li id="mb1_menu2" tabindex="-1"> + Style + <ul id="styleMenu" title="Style" tabindex="-1"> + <li id="italic" tabindex="-1">Italics</li> + <li id="bold" tabindex="-1">Bold</li> + <li id="underline" tabindex="-1">Underlined</li> + </ul> + </li> + <li id="mb1_menu3" tabindex="-1"> + Justification + <ul id="justificationMenu" title="Justification" tabindex="-1"> + <li id="left" tabindex="-1">Left</li> + <li id="center" tabindex="-1">Centered</li> + <li id="right" tabindex="-1">Right</li> + <li id="justify" tabindex="-1">Justify</li> + </ul> + </li> +</ul> +``` + +#### Disabled controls + +When a custom control becomes disabled, remove it from the tab order by setting `tabindex="-1"`. Note that disabled items within a grouped widget (such as menu items in a menu) should remain navigable using arrow keys. + +## Managing focus inside groups + +When a user tabs away from a widget and returns, focus should return to the specific element that had focus, for example, the tree item or grid cell. There are two techniques for accomplishing this: + +1. Roving `tabindex`: programmatically moving focus +2. `aria-activedescendant`: managing a 'virtual' focus + +### Technique 1: Roving tabindex + +Setting the `tabindex` of the focused element to "0" ensures that if the user tabs away from the widget and then returns, the selected item within the group retains focus. Note that updating the `tabindex` to "0" requires also updating the previously selected item to `tabindex="-1"`. This technique involves programmatically moving focus in response to key events and updating the `tabindex` to reflect the currently focused item. To do this: + +Bind a key down handler to each element in the group, and when an arrow key is used to move to another element: + +1. programmatically apply focus to the new element, +2. update the `tabindex` of the focused element to "0", and +3. update the `tabindex` of the previously focused element to "-1". + +### Technique 2: `aria-activedescendant` + +This technique involves binding a single event handler to the container widget and using the `aria-activedescendant` to track a "virtual" focus. (For more information about ARIA, see this [overview of accessible web applications and widgets](/en-US/docs/Web/Accessibility/Guides/Accessible_web_applications_and_widgets).) + +The `aria-activedescendant` property identifies the ID of the descendant element that currently has the virtual focus. The event handler on the container must respond to key and mouse events by updating the value of `aria-activedescendant` and ensuring that the current item is styled appropriately (for example, with a border or background color). + +## General guidelines + +### Usage of focus events + +- Do not dispatch the [`focus`](/en-US/docs/Web/API/Element/focus_event) event to send focus to an element. DOM focus events are considered informational only: they are generated by the system after something is focused, but not actually used to set focus. Use `element.focus()` instead. +- Do listen for the [`focus`](/en-US/docs/Web/API/Element/focus_event) and [`blur`](/en-US/docs/Web/API/Element/blur_event) events to track focus changes. Don't assume that all focus changes will come via key and mouse events: assistive technologies such as screen readers can set the focus to any focusable element. If you want to track the focus status for the whole document, you can use the [`document.activeElement`](/en-US/docs/Web/API/Document/activeElement) to get the active element, or [`document.hasFocus`](/en-US/docs/Web/API/Document/hasFocus) to make sure if the current document has focus. + +### Ensure that keyboard and mouse produce the same experience + +To ensure that the user experience is consistent regardless of input device, keyboard and mouse event handlers should share code where appropriate. For example, the code that updates the `tabindex` or the styling when users navigate using the arrow keys should also be used by mouse click handlers to produce the same changes. + +### Ensure that the keyboard can be used to activate element + +To ensure that the keyboard can be used to activate elements, any handlers bound to mouse events should also be bound to keyboard events. For example, to ensure that the Enter key will activate an element, if you have an `onclick="doSomething()"`, you should bind `doSomething()` to the key down event as well: `onkeydown="event.code === "Enter" && doSomething();"`. + +### Always draw the focus for tabindex="-1" items and elements that receive focus programmatically + +Ensure that focused elements have a focus ring. This can be done using the CSS {{cssxref("outline")}} property, which should not be unconditionally set to `none`—if you want to prevent unnecessary focus rings being displayed, use the {{cssxref(":focus-visible")}} pseudo-class. + +### Prevent used key events from performing browser functions + +If your widget handles a key event, prevent the browser from also handling it (for example, scrolling in response to the arrow keys) by using your event handler's return code. If your event handler returns `false`, the event will not be propagated beyond your handler. + +For example: + +```html +<span tabindex="-1">…</span> +``` + +```js +span.onkeydown = handleKeyDown; +``` + +If `handleKeyDown()` returns `false`, the event will be consumed, preventing the browser from performing any action based on the keystroke. + +### Don't rely on consistent behavior for key repeat, at this point + +Unfortunately `onkeydown` may or may not repeat depending on what browser and OS you're running on. diff --git a/files/en-us/web/accessibility/guides/mobile_accessibility_checklist/index.md b/files/en-us/web/accessibility/guides/mobile_accessibility_checklist/index.md new file mode 100644 index 000000000000000..3907ad9b106e724 --- /dev/null +++ b/files/en-us/web/accessibility/guides/mobile_accessibility_checklist/index.md @@ -0,0 +1,80 @@ +--- +title: Mobile accessibility checklist +slug: Web/Accessibility/Guides/Mobile_accessibility_checklist +page-type: guide +sidebar: accessibilitysidebar +--- + +This document provides a concise checklist of accessibility requirements for mobile app developers. It is intended to continuously evolve as more patterns arise. + +## Color + +- Color contrast must comply with [WCAG 2.1 AA level requirements](https://www.w3.org/TR/WCAG/#contrast-minimum): + + - Contrast ratio of 4.5:1 for normal text (less than 18 point or 14 point bold.) + - Contrast ratio of 3:1 for large text (at least 18 point or 14 point bold.) + +- Information conveyed via color must be also available by other means too (underlined text for links, etc.) + +## Visibility + +- Content hiding techniques such as zero opacity, z-index order and off-screen placement must not be used exclusively to handle visibility. +- Everything other than the currently visible screen must be _truly_ invisible (especially relevant for single page apps with multiple _cards_): + + - Use the `hidden` attribute or `visibility` or `display` style properties. + - Unless absolutely unavoidable, `aria-hidden` attribute should not be used. + +## Focus + +- All activatable elements must be focusable: + + - Standard controls such as links, buttons, and form fields are focusable by default. + - Non-standard controls must have an appropriate [ARIA Role](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles) assigned to them, such as `button`, `link`, or `checkbox`. + +- Focus should be handled in a logical order and consistent manner. + +## Text equivalents + +- Text equivalent must be provided for every non-strictly presentational non-text element within the app. + + - Use _alt_ and _title_ where appropriate (read Steve Faulkner's post about [Using the HTML title attribute](https://www.tpgi.com/using-the-html-title-attribute-updated/) for a good guide.) + - If the above attributes are not applicable, use appropriate [ARIA States and Properties](https://www.w3.org/TR/wai-aria-1.1/#state_prop_def) such as `aria-label`, `aria-labelledby`, or `aria-describedby`. + +- Images of text must be avoided. +- All user interface components with visible text (or image of text) as labels must have the same text available in the programmatic [name](https://www.w3.org/TR/WCAG21/#dfn-name) of the component. [WCAG 2.1: Label in name.](https://www.w3.org/WAI/WCAG21/Understanding/label-in-name.html) +- All form controls must have labels ({{ htmlelement("label") }} elements) for the benefit of screen reader users. + +## Handling state + +- Standard controls such as radio buttons and checkboxes are handled by the operating system. However, for other custom controls state changes must be provided via [ARIA States](https://www.w3.org/TR/wai-aria-1.1/#state_prop_def) such as `aria-checked`, `aria-disabled`, `aria-selected`, `aria-expanded`, and `aria-pressed`. + +## Orientation + +- Content should not be restricted to a single orientation, such as portrait or landscape, unless essential. [WCAG 2.1: Orientation](https://www.w3.org/WAI/WCAG21/Understanding/orientation.html) + + - Examples of when an orientation is essential is a piano application or a bank check. + +## General guidelines + +- An app title must be provided. +- Headings must not break hierarchical structure + + ```html + <h1>Top level heading</h1> + <h2>Secondary heading</h2> + <h2>Another secondary heading</h2> + <h3>Low level heading</h3> + ``` + +- [ARIA Landmark Roles](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles#3._landmark_roles) should be used to describe an app or document structure, such as `banner`, `complementary`, `contentinfo`, `main`, `navigation`, `search`. +- For touch events, ensure the following ([WCAG 2.1: Pointer Cancellation](https://www.w3.org/WAI/WCAG21/Understanding/pointer-cancellation.html)): + + - The down-event should not be used to execute any part of the function; + - Failing the above, _completion_ of the function should be on the up-event, and a mechanism is available to abort the action before its completion or to undo the action after its completion; + - Failing the above, the up-event should be able to undo any action that was triggered on a down event; + - All the above may be violated if it is essential to trigger the action on the down event, usually to simulate real-world experiences or to provide real-time feedback. For example, game controls, piano keyboards, or virtual keyboards. + +- Touch targets must be large enough for the user to interact with (see the [BBC Mobile Accessibility Guidelines](https://www.bbc.co.uk/accessibility/forproducts/guides/mobile/target-touch-size) for useful touch target size guidelines). + +> [!NOTE] +> The [original version of this document](https://yzen.github.io/firefoxos/2014/04/30/mobile-accessibility-checklist.html) was written by [Yura Zenevich](https://yzen.github.io/). diff --git a/files/en-us/web/accessibility/guides/seizure_disorders/index.md b/files/en-us/web/accessibility/guides/seizure_disorders/index.md new file mode 100644 index 000000000000000..d9e020beb354573 --- /dev/null +++ b/files/en-us/web/accessibility/guides/seizure_disorders/index.md @@ -0,0 +1,632 @@ +--- +title: Web accessibility for seizures and physical reactions +short-title: Preventing seizures and physical reactions +slug: Web/Accessibility/Guides/Seizure_disorders +page-type: guide +sidebar: accessibilitysidebar +--- + +This article introduces concepts behind making web content accessible for those with vestibular disorders, and how to measure and prevent content leading to seizures and/or other physical reactions. + +## Overview + +### Seizures + +Seizures caused by light are known as photosensitive epilepsy. Content that flickers, flashes, or blinks can trigger photosensitive epilepsy. Web technologies that use video, animated GIFs, animated PNGs, animated SVGs, {{Glossary("Canvas")}}, and CSS or JavaScript animations can all produce content that may induce seizures or other incapacitating physical reactions. Certain visual patterns, especially stripes, can also cause physical reactions even though they are not animated. Photosensitive epilepsy is actually a kind of "reflex epilepsy"—seizures occurring in response to a trigger. In the case of photosensitive epilepsy, seizures are triggered specifically by flashing lights, but other types of reflex epilepsies may be triggered by the act of reading or by noises. Patterns and images can also trigger epilepsy. + +The fact that static images may cause seizures and other disorders is documented in articles such as ["Gamma Oscillations and photosensitive epilepsy"](https://linkinghub.elsevier.com/retrieve/pii/S0960982217304062), where it is noted "_Certain visual images, even in the absence of motion or flicker, can trigger seizures in patients with photosensitive epilepsy_". The Epilepsy Foundation, in its article, ["Shedding Light on Photosensitivity, One of Epilepsy's Most Complex Conditions"](https://www.epilepsy.com/stories/shedding-light-photosensitivity-one-epilepsys-most-complex-conditions) talks about static images and patterns: "_Static or moving patterns of discernible light and dark stripes have the same effect as flashing lights because of the alternation of dark and bright areas."_ The Epilepsy Foundation of America Working Group is able to "quantify" the problem a little: _"A pattern with the potential for provoking seizures contains clearly discernible stripes, numbering more than five light-dark pairs of stripes in any orientation_". In addition to stripes, checkered patterns have also been known to cause photosensitive seizures, according to [Cedars-Sinai](https://www.cedars-sinai.org/health-library/diseases-and-conditions/p/photosensitive-seizures.html). + +Although static images are possible as triggers, they are less consistent. The trigger that is well established and strong is flashing/strobe lights. Dr. Selim Benbadis of USF's Comprehensive Epilepsy Program notes, _"The only thing that is really documented is flashing lights, which can trigger seizures in patients with photosensitive epilepsy. Only a few types of epilepsies are photosensitive though, and the vast majority of epilepsies are not."_ In addition to seizures brought about by photosensitivity, listening to certain pieces of music can also trigger what are called musicogenic seizures, although these types of seizures seem to be much more rare. For a great introduction on the topic of musicogenic seizures, visit Epilepsy Ontario's web page on [Musicogenic Seizures](https://epilepsyontario.org/musicogenic-seizures/). + +Seizures and epilepsy are not the same. In its article ["A Revised Definition of Epilepsy"](https://www.epilepsy.com/stories/revised-definition-epilepsy), the Epilepsy Foundation notes that "_a seizure is an event and epilepsy is the disease involving recurrent unprovoked seizures_." According to the Epilepsy Foundation's page ["How Serious Are Seizures?"](https://www.epilepsy.com/what-is-epilepsy/understanding-seizures/how-serious-are-seizures), _"Sudden unexpected death in epilepsy (SUDEP) is likely the most common disease-related cause of death in with epilepsy. It is not frequent but it is a very real problem and people need to be aware of its risk"_. + +The point is, seizures most definitely can be and are fatal, and developers and designers are incredibly important for making the web a safer place for those with sensitivities to photosensitive or musicogenic triggers. + +Seizures can be fatal, but even the ones that are "only" debilitating can be of such severity that they render the user incapacitated. Other disorders, such as disorientation, nausea, vomiting, and more can also be so severe that the user is unable to function. The Epilepsy Foundation's article, ["Photosensitivity and Seizures"](https://www.epilepsy.com/what-is-epilepsy/seizure-triggers/photosensitivity), provides a list of triggers that may cause seizures in photosensitive people; here's an excerpt from that list: + +- Television screens or computer monitors due to the flicker or rolling images. +- Certain video games or TV broadcasts containing rapid flashes or alternating patterns of different colors. +- Intense strobe lights like visual fire alarms. +- Natural light, such as sunlight, especially when shimmering off water, flickering through trees or through the slats of Venetian blinds. +- Certain visual patterns, especially stripes of contrasting colors. + +That same article continues that many factors must combine to trigger the photosensitive reaction. Of note is that it includes the wavelength of light as a possible factor; wavelengths in the red part of the spectrum seem to be especially problematic. In the article, ["Understanding WCAG 2.0 Three Flashes or Below Threshold"](https://www.w3.org/TR/UNDERSTANDING-WCAG20/seizure-does-not-violate.html) notes generally that: _"Individuals who have photosensitive seizure disorders can have a seizure triggered by content that flashes at certain frequencies for more than a few flashes"_ and goes on to note, very specifically that: "_People are even more sensitive to red flashing than to other colors, so a special test is provided for saturated red flashing_". + +You don't even need an image or video to cause harm. A {{HTMLElement('div')}} element set to change color and luminosity at high frequency, easily done via JavaScript, can cause real harm. And, flickering can occur everywhere. For example, "spinners" commonly used to display while pages load can easily "flicker" while spinning. + +Additional concerns exist for individuals with motor-skill problems. For example, the page for Trace Research & Development Center's [Photosensitive Epilepsy Analysis Tool](https://trace.umd.edu/peat/) notes that _"Photosensitive seizures can be provoked by certain types of flashing in web or computer content, including mouse-overs that cause large areas of the screen to rapidly flash on and off repeatedly"_. + +### Other physical reactions + +Nausea, vertigo (or dizziness), and disorientation are very nonspecific symptoms associated with all kinds of diseases and not particularly suggestive of seizures (except maybe disorientation, which is seen in seizures). However, seizures are not the only adverse physical response possible from flashing, flickering, blinking, and other such stimuli. In 1997, a Japanese cartoon featured an animated "virus bomb". Some of the children watching the cartoon reacted by having seizures, others by suffering nausea, shaking, and vomiting blood. The reactions from the children were so severe, they had to be rushed to the emergency room. The physical disorders listed below are all possible consequences: each of these physical reactions may be so severe as to be incapacitating. + +- Seizures +- Vestibular Disorders +- Migraines +- Nausea +- Vomiting + +## Flashing, blinking, & flickering + +Although "flashing" and "blinking" are sometimes used interchangeably, they are not the same. According to the W3C, blinking is a distraction problem, whereas flashing refers to content that occurs more than 3 times per second, and which is sufficiently large and bright. [Section 508](https://www.section508.gov/content/guide-accessible-web-design-development/#flashing) prohibits flickering effects with a frequency greater than 3 Hz (flickers per second) and lower than 55 Hz. The Epilepsy Foundation's article ["Shedding Light on Photosensitivity, One of Epilepsy's Most Complex Conditions"](https://www.epilepsy.com/stories/shedding-light-photosensitivity-one-epilepsys-most-complex-conditions) notes that _"Generally, flashing lights between the frequencies of five to 30 flashes per second (Hertz) are most likely to trigger seizures. In order to be safe, the consensus recommends that photosensitive individuals should not be exposed to flashes greater than three per second."_ For some people, however, flashing/blinking can cause symptoms at less than 3 Hz. + +It's important to note that not all flashing and blinking is bad. NASA, in its document titled, ["Blinking, Flashing, and Temporal Response"](https://colorusage.arc.nasa.gov/flashing.php) notes that blinking and flashing can be powerful tools for drawing attention—as is necessary for warning buttons (this assumes that users can still see the screen while elements are flashing, which is not always true). For some users, blinking buttons also caution that they must be used sparingly, and with care. As it applies to web design, systems that alert company employees to danger by "hijacking" the screen to provide a flashing warning of emergency need to take into consideration the rate, size, and luminosity changes on the screen as these warnings are flashed. + +### Flashing and flickering—how is danger quantified? + +According to the article ["Photic- and pattern-induced seizures: expert consensus of the Epilepsy Foundation of America Working Group",](https://onlinelibrary.wiley.com/doi/epdf/10.1111/j.1528-1167.2005.31405.x) _"A flash is a potential hazard if it has luminance ≥20 cd/m<sup>2</sup>, occurs at a frequency of ≥3 Hz, and occupies a solid visual angle of ≥0.006 steradians (approximately 10% of the central visual field or 25% of screen area at typical viewing distances)."_ + +How far is a typical viewing distance? The recommendation considered for a typical viewing distance at the time of writing was "_the area can be taken as applying to an area >25% of the area of a television screen, assuming standard viewing distances of ≥2 m (∼9 feet)"_. Much has changed since that time, and we are now much closer to our screen. + +Certain colors, and/or combinations of colors, also matter. ["Certain Colors More Likely To Cause Epileptic Fits, Researchers Find"](https://www.sciencedaily.com/releases/2009/09/090925092858.htm) notes that _"…complexities underlying brain dynamics could be modulated by certain color combinations more than the others, for example, red-blue flickering stimulus causes larger cortical excitation than red-green or blue-green stimulus."_ + +### Flashing & flashing red + +[WCAG 2.3.1 general flash and red flash thresholds](https://www.w3.org/WAI/WCAG21/Understanding/three-flashes-or-below-threshold.html) are defined as follows: + +- A **general flash** is defined as a pair of opposing changes in [relative luminance](https://www.w3.org/TR/WCAG21/#dfn-relative-luminance) of 10% or more of the maximum relative luminance where the relative luminance of the darker image is below 0.80, and where "a pair of opposing changes" is an increase followed by a decrease, or a decrease followed by an increase; +- A **red flash** is defined as any pair of opposing transitions involving a saturated red. + +These standards are based on earlier research. In 2004, The Epilepsy Foundation of America convened a workshop developed a [consensus](https://pubmed.ncbi.nlm.nih.gov/16146438/) on photosensitive seizures, stating _"A flash is a potential hazard if it has luminance at least 20 cd/m<sup>2</sup>, occurs at a frequency of least 3 Hz, and occupies a solid visual angle of at least 0.006 steradians (about 10% of the central visual field or 25% of screen area at typical viewing distances)."_ The transition to or from a saturated red is important and constitutes a risk on its own: "_Irrespective of luminance, a transition to or from a saturated red is also considered a risk._" + +### Size and distance + +#### How big? It depends + +"Relative" size and distance both matter. According to [PEAT](https://trace.umd.edu/peat/), _"The combined area of flashes occurring concurrently occupies no more than a total of one quarter of any 341 x 256 pixel rectangle anywhere on the displayed screen area when the content is viewed at 1024 by 768 pixels."_ + +The point that the field of vision is an important consideration arises in the article addressing WCAG 2.3.1 continues: "_The 1024 x 768 screen is used as the reference screen resolution for the evaluation. The 341 x 256 pixel block represents a 10 degree viewport at a typical viewing distance. (The 10 degree field is taken from the original specifications and represents the central vision portion of the eye, where people are most susceptible to photo stimuli.)_" + +This pixel area ratio calculates for relative size, but distance also matters. + +Distance matters because it affects the total field of vision. When viewers wear ocular masks for gaming, the field of vision is likely enveloped in its entirety by the screen. [WebXR](/en-US/docs/Web/API/WebXR_Device_API) is an open specification that makes it possible to experience VR in your browser, which can be experienced on phone, computer or headset. The concern about flashing images in an ocular mask is a growing one, since the mask is so close to the eyes. + +Research generally indicates that VR usage may actually be safer than normal screen consumption, due to higher refresh rates. As [Fisher et al. 2022](https://onlinelibrary.wiley.com/doi/full/10.1111/epi.17175) summarizes, _"The limited data so far available raise no special seizure concerns in terms of VR technology, although this view may change with more experience. Certain types of VR content, including bright flashes, provocative patterns, or color changes would be expected to provoke seizures, just as they do in the real world."_ + +(Note that some users will not be able to see with blinking cursors, and may get migraines, motion sickness, and disorientation, although blinking cursors occupy a much smaller area of the screen.) + +### Patterns, and parallax + +Contrasting dark and light geometric patterns are a known culprit; stripes and checks are the best known examples. The Epilepsy Foundation of America Working Group lists how many light-dark pairs of stripes are likely to provoke seizures, and, in what conditions. If a pattern is unchanging and straight, eight lines is the maximum allowable, but if it undulates, no more than five lines. + +Parallax effects can cause disorientation. Use parallax effects with caution; if you must use them, ensure the user has a control to turn them off. + +"A pattern with the potential for provoking seizures contains clearly discernible stripes, numbering more than five light-dark pairs of stripes in any orientation. When the light-dark stripes of any pattern collectively subtend at the eye from the minimal-expected viewing distance a solid angle of >0.006 steradians, the luminance of the lightest stripe is >50 cd/m<sup>2</sup>, and the pattern is presented for ≥0.5 s, then the pattern should display no more than five light-dark pairs of stripes, if the stripes change direction, oscillate, flash, or reverse in contrast; if the pattern is unchanging or smoothly drifting in one direction, no more than eight stripes." + +Not all is known, and even with the metrics listed above, additional factors come into play. For example, going from a smaller area to a larger one increases the likelihood that the brain responds, as well as increasing contrast, and increasing spatial frequency from a low to middle. It's also known, although the reasoning is not understood behind it, that going from basic orientations (for example, stripes) to a multiple one (for example, the checkered pattern that emerges when laying one set of stripes on top of, but perpendicular to, the original set) affects the brain. + +### Colors + +Understanding color is important for accessibility. See [understanding colors and luminance](/en-US/docs/Web/Accessibility/Guides/Colors_and_Luminance) as it relates to web accessibility and accessibility in general. + +How the color relates to its background—usually framed in terms of contrast—and how drastically the color changes frame to frame in animation is important. For more on this, see [Three Flashes or Below Threshold Understanding SC 2.3.1](https://www.w3.org/TR/UNDERSTANDING-WCAG20/seizure-does-not-violate.html). + +#### The Special Case of Red + +It has been demonstrated that [some colors are more likely to cause epileptic fits than others](https://www.sciencedaily.com/releases/2009/09/090925092858.htm). Human physiology and psychology are affected by the color red in general. Its power to influence behavior has even been noted in animals. + +- **Red Desaturation tests:** The human eye is so sensitively tuned to red that ophthalmologists set up a test using it. The Red desaturation test assesses the integrity of the optic nerve. For more information as to how an ophthalmologist uses this test, see [Red Desaturation](https://www.smartoptometry.app/red-desaturation/). +- **Red Environment:** Studies have shown that for those who suffer Traumatic Brain Injury, [cognitive function is reduced in a red environment](https://pubmed.ncbi.nlm.nih.gov/20649469/). + +[Saturated Red](/en-US/docs/Web/Accessibility/Guides/Colors_and_Luminance) is a special, dangerous case, and there are special tests for it. In addition to a red environment affecting the cognitive function of those with Traumatic Brain Injury, color in the red spectrum wavelength seems to require special concern and special tests. Dr. Gregg Vanderheiden, when testing the Photosensitive Epilepsy Analysis Tool, noted that the seizure rates were much higher than expected. They found that we are much more sensitive to saturated red flashing. (See the video, [The Photosensitive Epilepsy Analysis Tool](https://www.pbs.org/video/university-place-the-photosensitive-epilepsy-analysis-tool-ep-429/).) + +#### Websafe does not mean seizure-safe + +Note that the color **#990000** is considered "**websafe**". That does _not_ mean it is "safe for not causing seizures", it only means that the color may be "safely" reproduced accurately by the technology used to generate color on screens. + +## Measuring to prevent harm + +Measuring the potential for harm is a good starting point. Factors considered within tests include color, luminosity, size, contrast, and in cases of animation, frequency. WCAG 2.1 provides guidance for evaluating content. + +In August, 2004, the Epilepsy Foundation of America convened a workshop to begin to develop an expert consensus on photosensitive seizures. The following, expert, and authoritative information is from: [Photic- and pattern-induced seizures: expert consensus of the Epilepsy Foundation of America Working Group.](https://pubmed.ncbi.nlm.nih.gov/16146438/) + +> A flash is a potential hazard if it has luminance ≥20 cd/m<sup>2</sup>, occurs at a frequency of ≥3 Hz, and occupies a solid visual angle of ≥0.006 steradians (approximately 10% of the central visual field or 25% of screen area at typical viewing distances). A transition to or from saturated red also is considered a risk. A pattern with the potential for provoking seizures contains clearly discernible stripes, numbering more than five light-dark pairs of stripes in any orientation. When the light-dark stripes of any pattern collectively subtend at the eye from the minimal-expected viewing distance a solid angle of >0.006 steradians, the luminance of the lightest stripe is >50 cd/m2, and the pattern is presented for ≥0.5 s, then the pattern should display no more than five light-dark pairs of stripes, if the stripes change direction, oscillate, flash, or reverse in contrast; if the pattern is unchanging or smoothly drifting in one direction, no more than eight stripes. These principles are easier to apply in the case of fixed media, for example, a prerecorded TV show, which can be analyzed frame-by-frame, as compared with interactive media. + +The "cd/m<sup>2</sup>" refers to candela per square meter. So for the web developer, how does this relate to measurements for color, luminance, and saturation? + +The candela is a SI unit (International System of units) of luminous intensity. It's a photometric term, and photometry deals with the measurement of visible light as perceived by human eyes. Wikipedia's article on ["Candela per square metre"](https://en.wikipedia.org/wiki/Candela_per_square_metre) puts it in terms of what we are familiar with as developers: on a display device, and in the RGB space. This is helpful, because there's a specific standard assumed to be used on monitors, printers, and the Internet, and it is the **sRGB** (standard Red Green Blue). + +> As a measure of light emitted per unit area, this unit is frequently used to specify the brightness of a display device. The [sRGB](https://en.wikipedia.org/wiki/SRGB) spec for monitors targets 80 cd/m<sup>2</sup>. Typically, calibrated monitors should have a brightness of 120 cd/m<sup>2</sup>. Most consumer desktop [liquid crystal displays](https://en.wikipedia.org/wiki/Liquid_crystal_display) have luminances of 200 to 300 cd/m<sup>2</sup>. [High-definition televisions](https://en.wikipedia.org/wiki/High-definition_television) range from 450 to about 1500 cd/m<sup>2</sup>. + +The takeaway is that the **sRGB** color space is a common touch point between research, assessment tools, and developers, since it is easily converted from the commonly used Hex code. + +### Human physiology and psychology as a consideration + +Many experts work to quantify and measure to the greatest extent possible the kinds of web content that can serve as triggers for seizures. That said, it can't be forgotten that color is as much about human perception in the brain as it is the measurement of light coming from a computer screen. + +In addition to the psychological variances, there are also physiological differences among us. There will be variances and nuances as to how a real human being perceives, and responds to, color and light. For example, Tom Jewett, Lecturer Emeritus of Computer Sciences at Cal State University Long Beach, notes the following concerning [lightness in the HSL color scale](https://colortutorial.design/hsb.html) _"…The distinction between levels of lightness is not actually linear as the HSL scale would imply; we are much more sensitive to changes in lighter values than to darker ones."_ + +It's important to understand that light and its measurements are linear, but human vision and human perception are not. Investigation and discussion is ongoing as to how to relate the machine measurement of light as it passes from a computer screen, through the distance to the human eye, filtered by human vision, and then manipulated through the human brain. + +Even age and sex can play a role. According to the Epilepsy Foundation's article, ["Shedding Light on Photosensitivity, One of Epilepsy's Most Complex Conditions"](https://www.epilepsy.com/stories/shedding-light-photosensitivity-one-epilepsys-most-complex-conditions), _"Children and adolescents are more prone than adults to have an abnormal response to light stimulation, and the first light-induced seizure almost always occurs before age 20"._ The article follows with this statistic: _"Girls (60 percent) are more often affected than boys (40 percent), although seizures are more frequent in boys because they are more likely to be playing video games. Video games often contain potentially provocative light stimulation"_. + +**User testing is very problematic**. Naturally, no one wants to subject a seizure-prone individual to user testing. It's dangerous. To that point, one of the most ethical thing that developers and designers can do is use tools that have been developed by experts in the field who have worked hand-in-hand with physicians to develop the tool. As of this writing, there are two commonly available tools that have been ethically and professionally developed by researchers and physicians for film/videos: **PEAT**, and the **Harding Test**. + +### Photosensitive Epilepsy Analysis Tool (PEAT) + +The [Trace Research and Development Center](https://trace.umd.edu/) has set a gold standard for a [Photosensitive Epilepsy Analysis Tool](https://trace.umd.edu/peat/), and they've made a point to make it **_free_** to download. PEAT can help authors determine whether animations or video in their content are likely to cause seizures. Please note the restriction on its use: **_Use of PEAT to assess material commercially produced for television broadcast, film, home entertainment, or gaming industries is prohibited. Use the Harding Test or other tools for commercial purposes._** + +To get a free copy of the University of Maryland's Photosensitive Epilepsy Analysis Tool, visit the [Trace Research & Development Center](https://trace.umd.edu/). + +![University of Maryland College of Information Studies Photosensitive Epilepsy Analysis Tool.](peatversion1pt6.png) + +### The Harding Test + +As use of the PEAT tool is prohibited for commercial use, television programmers can use the Harding Test at [HardingTest.com](https://hardingtest.com/). The Harding Test is another gold standard. Television programmers in various countries must pass this test before being able to broadcast, so the group at [HardingTest.com](https://hardingtest.com/) provides both analysis and certification of video content. + +![Harding Flash and Pattern Analyzer.](screen_shot_2019-06-20_at_11.16.17_am.png) + +## Accessibility Solutions for Developers + +All animations are potentially dangerous. As designers and developers our responsibility is to ensure we do no harm either intentionally or unintentionally. If we must include something that has the potential to cause harm, it is vital to prevent users from accidentally encountering the harmful content, and to provide ways for users to prevent and control animations mitigating potential harm. + +### What the web developer can do + +#### Do no harm + +[WCAG Guideline 2.3 Seizures and Physical Reactions](https://www.w3.org/WAI/standards-guidelines/wcag/new-in-21/) provides an overview: _"Do not design content in a way that is known to cause seizures or physical reactions"_. Don't include animation that a user cannot control. Don't design with patterns known to cause problems. If you must include a gif or png with flashing in it, record it in a video format instead so that controls are available to the user. Give the user the ability to avoid it, turn it off, or render it less harmful. + +#### Understand malice + +As a developer or designer, ask yourself if strobing content really needs to be on your webpage. Even if handled properly, there are those who may download offending content from your site and weaponize it. It is believed the first documented attempt at using computers to effect physical harm via animation began Saturday, March 22, 2008: The Epilepsy Foundation's website was hacked via posts with flashing images and links falsely claiming to be helpful. Users with vestibular disorders who were seeking help from the site were affected. + +A series of legal considerations are underway after journalist Kurt Eichenwald, a known epileptic, suffered a seizure after being sent an animated gif in December 2016: the flashing gif carried the message, _"You deserve a seizure for your posts"_. + +#### Control exposure, control access + +Controlling exposure to the page is key to ensuring that someone susceptible to seizures is not exposed to it accidentally. WCAG notes that a single object can make the entire page unusable. + +If you believe you may have an image or animation that may cause seizures, control access to it by first displaying a warning about the content, and then putting it in a location where the user must opt in to it, such as clicking a button, or ensuring that the link to the page has a distinct and obvious warning. + +Consider using metadata such as `<meta name="robots" content="noindex, nofollow">` so that the page is not indexed by search engines. + +#### Do Not Index, Do Not Follow + +By not indexing the page, the likelihood that users will stumble upon it via search will be reduced. + +```html +<html lang="en"> + <head> + <title>…</title> + <meta name="robots" content="noindex, nofollow" /> + </head> +</html> +``` + +### Animated GIFs + +All image types are potentially dangerous, however, animated GIFs deserve special mention because of their ubiquity, and the fact that the animation speed is actually controlled within the GIF file itself. + +#### Detect if a GIF is animated + +- The [animated-gif-detector](https://www.npmjs.com/package/animated-gif-detector) npm package allows for the ability to determine animate _as early as possible_ in a given HTTP request. +- Zakirt provides a gist for [animated-gif-detect.js](https://gist.github.com/zakirt/faa4a58cec5a7505b10e3686a226f285) + +With animated GIFs, ensure animation is inactive until the user chooses to activate it. For example, the user must push a button or check a box in order to start the animation. + +### Videos + +As in the case of animated GIFs, the user must push a button or check a box in order to start the animation. There are many ways to do this, such as NOT adding the [`autoplay`](/en-US/docs/Web/API/HTMLMediaElement/autoplay) attribute to `<video controls>`, or setting {{CSSxRef('animation-play-state')}} to `paused` as an initial state. To see a powerful example of how this can actually work see the article by Kirupa, ["Toggling Animations On and Off"](https://www.kirupa.com/html5/toggling_animations_on_off.htm). Kirupa uses the `animation-play-state` in concert with {{CSSxRef('transition')}}, {{CSSxRef('transform')}}, and [`prefers-reduced-motion`](/en-US/docs/Web/CSS/@media/prefers-reduced-motion) to create a very accessible experience under the user's control. + +[`animation-play-state`](https://www.w3.org/TR/css-animations-1/#animation-play-state) is a CSS property that sets whether an animation is running or paused. + +```css +div { + animation-play-state: paused; +} +``` + +[CSS transitions](/en-US/docs/Web/CSS/CSS_transitions) can be used to set the duration to zero for the initial stage of animation. + +```css +div { + transition-duration: 0s; +} +``` + +### Ensure the user can also stop animations as well as start them + +A {{HTMLElement('video')}} element with no attributes will not play automatically, and will also have no controls. Ensure that you add the `controls` attribute to the video element so that the user can stop the video as well as start it. + +```html +<video controls> + <source src="video.mp4" type="video/mp4" /> + <source src="video.ogg" type="video/ogg" /> + Your browser does not support the video tag. +</video> +``` + +#### Programmatically ensure controls are available + +The `HTMLMediaElement.controls` property reflects the `controls` HTML attribute, which controls whether user interface controls for playing the media item will be displayed. + +##### Video + +To ensure that a video has controls that a user can access, ensure that you add the word "controls" to HTML video and audio elements. + +`<video controls>` + +```html +<video controls> + <source src="myVideo.mp4" type="video/mp4" /> + <source src="myVideo.webm" type="video/webm" /> + <p> + Your browser doesn't support HTML video. Here is a + <a href="myVideo.mp4">link to the video</a> instead. + </p> +</video> +``` + +##### Audio + +Taking that same example and applying it to audio: + +`<audio controls>` + +```html +<audio controls> + <source src="myAudio.ogg" type="audio/ogg" /> + <source src="myAudio.mp3" type="audio/mpeg" /> + <p> + Your browser does not support the audio element. Here is a + <a href="myAudio.mp3">link to the audio</a> instead. + </p> +</audio> +``` + +##### Audio as part of Video + +Note that the audio in videos can be controlled by the `muted` content attribute, even though the content is within the {{HTMLElement('video')}} element rather than the {{HTMLElement('audio')}} element. This example is from the section on [muted media attribute](https://html.spec.whatwg.org/multipage/media.html#concept-media-muted) description from the HTML Living Standard. It explains that the video will autoplay quietly in the background until the user takes action to unmute the audio. + +```html +<video src="adverts.cgi?kind=video" controls autoplay loop muted></video> +``` + +### Control speed + +This seems obvious, but because there are so many MIME types, the mechanisms for handling them varies greatly, and for that reason there's not a one-size-fits-all solution to the problem. This is further complicated by the fact that even how files are classified complicates how they should be handled. For example, the .gif file format is usually understood to be an image, but is also considered a video file format in some circles because of its ability to be animated. For a comprehensive listing of media types, please visit [IANA.org's page for Media Types](https://www.iana.org/assignments/media-types/media-types.xhtml). + +The methods for sniffing them out is not a casual exercise. You may be interested in following the [MIME Sniffing](https://mimesniff.spec.whatwg.org/) standard at whatwg.org. Just about every kind of image can be animated; how they are animated varies, and therefore, the control of the animation varies. + +#### Commonly animated file types + +- **Bitmap**: Animation +- **Canvas**: MDN's tutorial on Canvas has a great section on [basic animations](/en-US/docs/Web/API/Canvas_API/Tutorial/Basic_animations). `setInterval()` is a mainstay in Canvas animation, but it is also interesting to see how it interacts with screen refresh. See the article, ["Controlling fps with requestAnimationFrame?"](https://stackoverflow.com/questions/19764018/controlling-fps-with-requestanimationframe) in which they discuss the nuts and bolts of implementing `requestAnimationFrame` against the backdrop of screen refresh. +- **GIFs (Raster)**: Tough to crack because control for their animation resides within the gif files themselves. For information about controlling the speed of GIFs see W3C's ["G152: Setting animated gif images to stop blinking after n cycles (within 5 seconds)"](https://www.w3.org/TR/WCAG20-TECHS/G152.html). A great Stack Overflow article on the subject is, ["Can you control GIF animation with JavaScript?"](https://stackoverflow.com/questions/2385203/can-you-control-gif-animation-with-javascript) +- **GIFV (Raster)**: Considered a variant, video version of GIF. The format is not standardized, and must reference a "real" video file (e.g., a .webm file) which must exist elsewhere. +- **JPG (Raster)** +- **MNG (Raster)**: Multiple-image Network Graphics is a graphics file format for animated images. Also considered by some to be a video format. +- **PNG, APNG (Raster)**: Portable Network Graphics and Animated Portable Network Graphics may both be animated. +- **SVGs (Vector)**: The MDN document, ["SVG: Scalable Vector Graphics"](/en-US/docs/Web/SVG), notes that _"SVG is a text-based open Web standard. It is explicitly designed to work with other web standards such as [CSS](/en-US/docs/Web/CSS), [DOM](/en-US/docs/Web/API/Document_Object_Model), and [SMIL](/en-US/docs/Web/SVG/Guides/SVG_animation_with_SMIL)."_ SVGs can be used as an image like in this example: `<img src="example.svg" alt="This is an image using a svg as a source">`. This means that SVG appearance and animation can be controlled through CSS keyframes and animations. For interaction with JavaScript, see the MDN documents on [SVG Interfaces](/en-US/docs/Web/API/Document_Object_Model#svg_dom) and [Applying SVG effects to HTML content](/en-US/docs/Web/SVG/Guides/Applying_SVG_effects_to_HTML_content). +- **Voxel (Raster)**: Three-dimensional [voxel](https://en.wikipedia.org/wiki/Voxel) raster graphics are employed in video games, as well as in medical imaging. + +#### Text can also be animated + +Translations and transformations can animate text in a div, and do harm. Moving text can induce seizures for the same reasons that moving images do, so avoid animating your text. It's a good idea to avoid using moving text anyhow, as many screen readers cannot read moving text and it's bad user experience even for those with no vision or vestibular issues. + +### CSS for animation + +In the style sheet or within the {{HTMLElement('style')}} element, many options can combine together to create a powerful experience for the user. We've already mentioned the `animation` property earlier in this document. It's actually shorthand for all animation properties, including: + +- `animation-play-state` +- `animation-duration` has a value of `<time>`; this is the duration an animation takes to complete one cycle. This may be specified in either seconds `(s)` or milliseconds `(ms)`. A default value of `0s` indicates no animation should occur. +- `animation-timing-function` + +The animation property is already powerful on its own, but combined with other properties and queries such as `prefers-reduced-motion`, a powerful set of options can be set up for the user. Setting `animation-duration` and `transition-duration` properties to a short duration rather than setting them to `animation: none` and `transition: none`, enables a safeguard to prevent issues in any case there is a dependency on the animation to run. + +### JavaScript animation + +JavaScript is often used to control {{HTMLElement('canvas')}} elements and SVGs. Most JavaScript code that applies to HTML video also applies to audio. `HTMLMediaElement.playbackRate` is used to implement user controls for the playback rate for both video and audio. A value of 1.0 is default and considered normal speed; a value of 0.5 is half the speed, a value of 2.0 is twice the speed. A negative number plays the video or audio backwards. Set the playback rate property: `HTMLMediaElement.playbackRate = playbackSpeed`. + +[document.getAnimations()](/en-US/docs/Web/API/Document/getAnimations) is an experimental technology, and includes [CSS Animations](/en-US/docs/Web/CSS/CSS_animations), [CSS Transitions](/en-US/docs/Web/CSS/CSS_transitions), and [Web Animations](/en-US/docs/Web/API/Web_Animations_API). The MDN page on [Document.getAnimations()](/en-US/docs/Web/API/Document/getAnimations) provides the following code sample of how to slow down all animations on a page to half speed: + +```js +document.getAnimations().forEach((animation) => { + animation.playbackRate *= 0.5; +}); +``` + +#### Image sources for animation + +One of the easiest ways is to start with an image that is already in existence, using it as an image source, and then animating it. Remember, you can use GIFs, JPGs, PNGs, SVGs and other file types here as an image source, as long as they are allowed file types—and sizes—in your environment. SVGs are often not allowed, due to security concerns. The MDN document, [Basic animations](/en-US/docs/Web/API/Canvas_API/Tutorial/Basic_animations), provides outstanding examples of this, using multiple image sources for the sun, earth, and moon, and using several canvas methods to control the speed and animation of the earth as it orbits around the sun, and the moon as it orbits around the earth. Use the codepen available with this tutorial to adjust `ctx.rotate` in the code to see how the animation is affected when changes are made. + +#### If you absolutely, positively must use a flashing animation… + +Make sure it has a control on it. Make sure it is turned off when the viewer first encounters it, and that a user must opt-in to see the animation. + +An example of a format that has no controls available to the user is a gif file. Animation speed is controlled within the gif image itself. Converting an animated gif to video enables controls to be put on the animation, and gives the user agency. There are many free online converters available for use, such as [EZGif](https://ezgif.com/) and [GIF to MP4](https://gif-2-mp4.com/). + +#### Set user expectations + +Give users a heads-up as to what will happen before they click on that link. Describe the animation that is to follow. See [WCAG 2.1 Success Criterion 3.2.5 Change on Request](https://www.w3.org/TR/WCAG21/#change-on-request). + +#### Keep it small + +If you absolutely positively must have flashing, keep it small. Generally speaking, limit the size of the flash to an area approximately 341 by 256 pixels or less. This pixel size assumes that a viewer is at a typical distance from the screen. As mentioned earlier, this size may be too big if the image is to be viewed at close range, such as in a VR headset. WebVR is an open specification that makes it possible to experience VR in your browser. WebVR can be experienced on phone, computer or headset. + +If you are designing for a game or VR that uses an ocular mask, **or CAN be used by an ocular mask**, such as in Firefox Reality (a browser for virtual reality), ensure that the size of the rectangle is much smaller than 341 by 256 pixels, because the image is much closer to a user's eyes. + +#### Reduce contrast + +Normally, higher contrast is a good thing when it comes to accessibility. The greater the contrast of a text color to its background (technically called _luminosity contrast ratio,_ according to W3.org's page on [Colors with Good Contrast](https://www.w3.org/WAI/perspective-videos/contrast/), the easier such content is to read. Users with low vision are especially appreciative of efforts to ensure high contrast of text against its background. When the content is animated, however, **_reducing_** contrast is actually a way to reduce the likelihood that the animated content will cause seizures. Drop the contrast ratio if three flashes within one second are detected. + +The contrast ratio is defined in [WCAG 2.1](https://www.w3.org/TR/WCAG21/) as follows: + +- _contrast ratio_ + + - : (L1 + 0.05) / (L2 + 0.05), where + + - L1 is the [relative luminance](https://www.w3.org/TR/WCAG21/#dfn-relative-luminance) of the lighter of the colors, and + - L2 is the [relative luminance](https://www.w3.org/TR/WCAG21/#dfn-relative-luminance) of the darker of the colors. + +It's best if you can adjust the contrast before it is uploaded or published to the web. For videos and animated GIFs, the Adobe Suite of products is a phenomenal resource for traditional images. Also for images, an online tool available is pinetools.com's [Brightness and contrast online](https://pinetools.com/brightness-contrast-image). If you intend to make animated GIFs, for example, start with one that has a lower contrast ratio. + +JavaScript is also an option for reducing contrast dynamically. Here's a code example from the section titled, ["Example: Setting the background color of a paragraph"](/en-US/docs/Web/API/Document_Object_Model/Traversing_an_HTML_table_with_JavaScript_and_DOM_Interfaces#setting_the_background_color_of_a_paragraph) from the MDN document, [Traversing an HTML table with JavaScript and DOM Interfaces](/en-US/docs/Web/API/Document_Object_Model/Traversing_an_HTML_table_with_JavaScript_and_DOM_Interfaces). Notice that the color in the example is described in the **RGB** color space. + +**HTML Content [(link to source page)](/en-US/docs/Web/API/Document_Object_Model/Traversing_an_HTML_table_with_JavaScript_and_DOM_Interfaces#html_2)** + +```html +<body> + <input type="button" value="Set paragraph background color" /> + <p>hi</p> + <p>hello</p> +</body> +``` + +**JavaScript Content [(link to source page)](/en-US/docs/Web/API/Document_Object_Model/Traversing_an_HTML_table_with_JavaScript_and_DOM_Interfaces#javascript_2)** + +```js +function setBackground() { + // now, get all the p elements in the document + const paragraphs = document.getElementsByTagName("p"); + + // get the second paragraph from the list + const secondParagraph = paragraphs[1]; + + // set the inline style + secondParagraph.style.background = "red"; +} + +document.querySelector("input").addEventListener("click", setBackground); +``` + +#### Avoid fully saturated reds for flashing content + +As mentioned earlier in this document, the Epilepsy Foundation of America convened a workshop in August 2004 to begin to develop an expert consensus on photosensitive seizures. Among their results was the understanding that _"A flash is a potential hazard if it has luminance at least 20 cd/m2, occurs at a frequency of least 3 Hz, and occupies a solid visual angle of at least 0.006 steradians (about 10% of the central visual field or 25% of screen area at typical viewing distances). A transition to or from saturated red also is considered a risk."_ They also note in that same consensus: _"Irrespective of luminance, a transition to or from a saturated red is also considered a risk."_ + +### Provide alternative CSS styles + +With the understanding that much of animation and flashing can be controlled via CSS methods, it's important to explore ways to make alternative options available to users, and to make the control of these options convenient and visible. + +#### Alternative Style Sheets + +Modern browsers will display the alternate CSS available in alternate style sheets if the users know where to look for them. In some cases, the alternate styles are revealed when the users go through the View menu, in other cases they are manifested in the settings, sometimes both. Not all users know to look for these options via the browser or settings, so it's worth considering doing things the old-fashioned way, with obvious buttons or links to change the style so that users can see them. Doing so won't conflict with, or override, the browser's ability to read the alternate style sheets, or the ability of the user to set preferences in the settings. + +It's important to know that certain users, such as those who rely on speech-recognition systems, often depend on legacy buttons and links because their disability prevents them from using a mouse, or to be able to take advantage of touch events on mobile tablets. + +Common ways to include the alternative stylesheets into your HTML documents are to use the {{HTMLElement('link')}} element, and {{CSSxref('@import')}}. + +#### The {{HTMLElement('link')}} element + +Use the {{HTMLElement('link')}} element, alongside with and together with the attributes of `rel="alternate stylesheet"` and for title, `title="…"` in the {{HTMLElement('head')}} section of the webpage. + +```html +<head> + <title>Home Page</title> + <link href="main.css" rel="stylesheet" title="Default Style" /> + <link + href="alternate1.css" + rel="alternate stylesheet" + title="Alternate One" /> + <link + href="alternate2.css" + rel="alternate stylesheet" + title="Alternate Two" /> +</head> +``` + +**{{CSSxref('@import')}}** is also a way to incorporate style sheets, but it is not quite as well supported as the {{HTMLElement('link')}} element. + +```css +@import url(alternate1.css); +@import url(alternate2.css); +``` + +By using alternate style sheets (remember to add the titles) you are setting it up for users to be able to use their browsers to choose alternate styles. + +### Dynamic Style Switching + +One problem with relying on the browser to reveal alternative styles is that not all users are technically savvy enough to discover the alternate styles. Or, because of their disability, are not able to. Buttons or links make it obvious that options are available to many grateful users. There's a multitude of ways to add toggle buttons to allow the user to switch to the different style sheets. That said, the use of alternative style sheets are not the only option. Another option is to manipulate the style of the page itself. According to the MDN document, [Using dynamic styling information](/en-US/docs/Web/API/CSS_Object_Model/Using_dynamic_styling_information), _"where possible, it really is best practice to dynamically manipulate classes via the [`className`](/en-US/docs/Web/API/Element/className) property since the ultimate appearance of all of the styling hooks can be controlled in a single stylesheet"._ One of the best examples around as to how to do this is from the W3C's page, ["C29: Using a style switcher to provide a conforming alternate version"](https://www.w3.org/TR/WCAG20-TECHS/C29.html). + +### Extreme Cases: Text-Only Alternatives + +A separate, alternative stylesheet that prevents images from being displayed is easy to make. It's a draconian solution; but it is one that is sometimes necessary for school teachers and other public servants who must serve those with extreme sensitivities. These public servants can ask their developers to develop a special alternative style sheet using `display: none`. Here's how to do it via CSS: + +```css +img { + display: none; +} +``` + +#### Take advantage of media queries with {{HTMLElement('style')}} + +In setting up media queries, you are enabling controls by the user; these controls are made available in the browser or in the OS. See the MDN document, [Accessibility: What users can do to browse more safely](/en-US/docs/Web/Accessibility/Guides/Browsing_safely) to see more details of how a user accesses the controls. + +#### `prefers-reduced-motion` + +Support for `prefers-reduced-motion` in modern browsers is growing. + +```css +@media screen and (prefers-reduced-motion: reduce) { +} +@media screen and (prefers-reduced-motion) { +} +``` + +To see a great example of how to use the code `prefers-reduced-motion`, visit the MDN document, [`prefers-reduced-motion`](/en-US/docs/Web/CSS/@media/prefers-reduced-motion), or see the example below from the section on ["New in Chrome 74"](https://developer.chrome.com/blog/new-in-chrome-74/). + +```css +button { + animation: vibrate 0.3s linear infinite both; +} + +@media (prefers-reduced-motion: reduce) { + button { + animation: none; + } +} +``` + +#### `prefers-color-scheme` + +This can be useful if the ambient light API is not available. Support is emerging. + +```css +@media (prefers-color-scheme: dark) { + /* adjust styles for dark mode */ +} +``` + +#### Window.matchMedia() + +There is a powerful tool available to developers via Window.matchMedia(). A great resource is MDN's document on [`Window.matchMedia()`](/en-US/docs/Web/API/Window/matchMedia). + +#### Media update feature + +The more often the screen is refreshed, the more stable it appears to the human eye, and the less it "flickers". The vast majority of modern technology refreshes at a rate that does not cause problems with photosensitivity. However, not everybody is wealthy enough to be able to afford the most recent technology: older or underpowered computers can have low refresh rates. [AbilityNet's Factsheet (November 2015) Computers and Epilepsy](https://www.abilitynet.org.uk/sites/abilitynet.org.uk/files/Epilepsy%20and%20Computing%20Nov%202015.pdf) describes more of the details on refresh rates. + +A very old article, Tech Republic's ["Epilepsy and CRT/LCD screen flicker"](https://www.techrepublic.com/forums/discussions/epilepsy-and-crt-lcd-screen-flicker/), had an interesting response concerning the refresh rates in Hz: + +- _"This effect is noticeable, and documented, up to 70 Hz."_ +- _"These studies would seem to indicate that you should stay away from refresh rates under 70 Hz, and use a rate not divisible by 10."_ + +Eric Bailey, of CSS-Tricks, found an innovative use the update feature which, used in combination with animation-duration or transition-duration, to conclude at a rate that is imperceptible to the human eye. In other words, Eric's techniques address the refresh-rate problem. The CSS below is from the CSS-Tricks article, [" Revisiting prefers-reduced-motion, the reduced motion media query"](https://css-tricks.com/revisiting-prefers-reduced-motion/). + +```css +@media screen and (prefers-reduced-motion: reduce), (update: slow) { + * { + animation-duration: 0.001ms !important; + animation-iteration-count: 1 !important; /* Hat tip Nick/cssremedy (https://css-tricks.com/revisiting-prefers-reduced-motion/#comment-1700170) */ + transition-duration: 0.001ms !important; + } +} +``` + +From W3.org's page on [Media Queries 4](https://www.w3.org/TR/mediaqueries-4/): + +The `update` media feature is used to query the ability of the output device to modify the appearance of content once it has been rendered. It has the values of "none", "slow", and "fast". + +## Developmental & Experimental Features + +### Media Queries Level 5 + +EnvironmentMQ (Planned in Media Queries Level 5) + +- `light-level` + - : [`light-level`](https://drafts.csswg.org/mediaqueries-5/#light-level) has three valid values: dim, normal, and washed. Interestingly, the specification refrains from actually defining the three levels in terms of a measurement of lux, because devices with a light sensor usually adjust the brightness of the screen automatically. The specifications also note the difference in technology, such as e-ink, which remains readable in bright daylight, versus liquid crystals, which do not. +- `environment-blending` + - : From W3C's Draft document, Media Queries Level 5: _"The [`environment-blending`](https://drafts.csswg.org/mediaqueries-5/#descdef-media-environment-blending) media feature is used to query the characteristics of the user's display so the author can adjust the style of the document. An author might choose to adjust the visuals and/or layout of the page depending on the display technology to increase the appeal or improve legibility."_ + +#### User Preference Media Features (Planned in Media Queries Level 5) + +[User Preference Media Features](https://drafts.csswg.org/mediaqueries-5/#mf-user-preferences) in [W3C Editor's Draft Media Queries Level 5](https://drafts.csswg.org/mediaqueries-5/) are especially promising in providing user control over media. Here are some highlights: + +- `inverted-colors` + - : According to the section, [User Preference Media Features](https://drafts.csswg.org/mediaqueries-5/#mf-user-preferences), "The [`inverted-colors`](https://drafts.csswg.org/mediaqueries-5/#descdef-media-inverted-colors) media feature indicates whether the content is displayed normally, or whether colors have been inverted." +- [`forced-colors`](/en-US/docs/Web/CSS/@media/forced-colors) + - : In [`forced-colors-mode`](https://drafts.csswg.org/css-color-adjust-1/#forced-colors-mode), the user agent enforces the user's preferred color palette on the page, overriding the author's chosen colors. From W3C's Draft document, Media Queries Level 5 section on forced-colors: _"The forced-colors media feature is used to detect if the user agent has enabled a [forced colors mode](https://drafts.csswg.org/css-color-adjust-1/#forced-colors-mode) where it enforces a user-chosen limited color palette on the page"._ The user will need to be made aware of this ability, and it will need to play nice with the appropriate value for the prefers-color-scheme media query. +- `light-level` + - : From W3C's Draft document, Media Queries Level 5 section on light-level: _"The [`light-level`](https://drafts.csswg.org/mediaqueries-5/#descdef-media-light-level) media feature is used to query about the ambient light-level in which the device is used, to allow the author to adjust style of the document in response."_ This will be a godsend to those who have motor-skills problems, or for some with cognitive difficulties, who cannot find the right "button" to change their screen settings. +- prefers-contrast + - : From W3C's Draft document, Media Queries Level 5 section on [`prefers-contrast`](/en-US/docs/Web/CSS/@media/prefers-contrast): _"The `prefers-contrast` media feature is used to detect if the user has requested the system increase or decrease the amount of contrast between adjacent colors. For example, many users have difficulty reading text that has a small difference in contrast to the text background and would prefer a larger contrast."_ Sometimes there can be such a thing as too much contrast; a halo effect around text can occur in such situations and actually reduce legibility. Putting the amount of contrast in the user's control is a definite gift for accessibility. + +#### `MediaQueryList` Interface + +Section 4.2 from the CSSWG.org drafts integrates with the [event loop](https://html.spec.whatwg.org/multipage/webappapis.html#event-loop) defined in HTML. [HTML](https://drafts.csswg.org/cssom-view/#biblio-html) for the [`MediaQueryList`](https://drafts.csswg.org/cssom-view/#mediaquerylist) object. See the MDN document, [MediaQueryList](/en-US/docs/Web/API/MediaQueryList) for more information. + +#### Personalization Help and Support + +The requirement for the `literal` property is taken from [section 23 Non-literal Text and Images](https://www.w3.org/TR/personalization-semantics-help-1.0/). + +**Requirement:** Some users cannot understand non-literal text and icons such as metaphors, idioms etc. The `literal` property is intended to identify text or images as non-literal and allows the author to explain non-literal text and images to users. + +#### Transitions (for CSS and SVG) + +The following is from the [Web Animations model](https://www.w3.org/TR/web-animations-1/) CSSWG.org drafts + +The Web Animations model is intended to provide the features necessary for expressing [CSS Transitions](https://drafts.csswg.org/web-animations/#biblio-css-transitions-1), [CSS Animations](https://drafts.csswg.org/web-animations/#biblio-css-animations-1), and [SVG](https://drafts.csswg.org/web-animations/#biblio-svg11). + +## See also + +### MDN + +- [Accessibility: What users can do to browse more safely](/en-US/docs/Web/Accessibility/Guides/Browsing_safely) +- [Accessibility: Understanding color and luminance](/en-US/docs/Web/Accessibility/Guides/Colors_and_Luminance) +- [Applying SVG effects to HTML Content](/en-US/docs/Web/SVG/Guides/Applying_SVG_effects_to_HTML_content) +- [Basic Animations](/en-US/docs/Web/API/Canvas_API/Tutorial/Basic_animations) (Canvas Tutorial) +- [Canvas API](/en-US/docs/Web/API/Canvas_API) +- [CanvasRenderingContext2D.drawImage()](/en-US/docs/Web/API/CanvasRenderingContext2D/drawImage) +- [\<color>](/en-US/docs/Web/CSS/color_value) +- [Document Object Model](/en-US/docs/Web/API/Document_Object_Model) +- [MediaQueryList](/en-US/docs/Web/API/MediaQueryList) +- [Using dynamic styling information](/en-US/docs/Web/API/CSS_Object_Model/Using_dynamic_styling_information) +- [WebGL: 2D and 3D graphics for the web](/en-US/docs/Web/API/WebGL_API) +- [WebVR API](/en-US/docs/Web/API/WebVR_API) + +### Color + +- [Color Tutorial: describing color](https://colortutorial.design/) Tom Jewett +- [Formula to Determine Brightness of RGB color](https://stackoverflow.com/questions/596216/formula-to-determine-perceived-brightness-of-rgb-color) Stack Exchange Discussion Thread +- [How the Color Red Influences Our Behavior](https://www.scientificamerican.com/article/how-the-color-red-influences-our-behavior/) Scientific American By Susana Martinez-Conde, Stephen L. Macknik on November 1, 2014 + +### Discussions + +- [Problems with WCAG 2.0 Flash Definition #553](https://github.com/w3c/wcag/issues/553) +- [WCAG 2.1 Understanding 2.3.1 - missing/vague dimension definitions #585](https://github.com/w3c/wcag/issues/585) + +### Epilepsy and Seizures + +- [Shedding Light on Photosensitivity, One of Epilepsy's Most Complex Conditions](https://www.epilepsy.com/stories/shedding-light-photosensitivity-one-epilepsys-most-complex-conditions) Epilepsy Foundation: _"Certain individuals are born with special sensitivity to flashing lights or contrasting visual patterns, such as stripes, grids and checkerboards. Because of this condition, their brain will produce seizure-like discharges when exposed to this type of visual stimulation."_ +- [Gamma oscillations and photosensitive epilepsy](https://www.sciencedirect.com/science/article/pii/S0960982217304062?via%3Dihub) Current Biology [Volume 27, Issue 9](https://www.sciencedirect.com/journal/current-biology/vol/27/issue/9), 8 May 2017, Pages R336-R338: _"Certain [visual images](https://www.sciencedirect.com/topics/biochemistry-genetics-and-molecular-biology/retina-image), even in the absence of motion or flicker, can trigger seizures in patients with photosensitive epilepsy."_ +- [Photosensitive Seizures. Cedars-Sinai](https://www.cedars-sinai.org/health-library/diseases-and-conditions/p/photosensitive-seizures.html) "_Photosensitive seizures are triggered by flashing or flickering lights. These seizures can also be triggered by certain patterns such as stripes._" +- [Photic-and pattern-induced seizures: expert consensus of the Epilepsy Foundation of America Working Group](https://pubmed.ncbi.nlm.nih.gov/16146438/) Eplepsia 2005 Sept, 46(9):1423-5 PubMed.gov NCBI [Harding G](https://pubmed.ncbi.nlm.nih.gov/?term=Harding%20G%5BAuthor%5D&cauthor=true&cauthor_uid=16146438), [Wilkins AJ](https://pubmed.ncbi.nlm.nih.gov/?term=Wilkins%20AJ%5BAuthor%5D&cauthor=true&cauthor_uid=16146438), [Erba G](https://pubmed.ncbi.nlm.nih.gov/?term=Erba%20G%5BAuthor%5D&cauthor=true&cauthor_uid=16146438), [Barkley GL](https://pubmed.ncbi.nlm.nih.gov/?term=Barkley%20GL%5BAuthor%5D&cauthor=true&cauthor_uid=16146438), [Fisher RS](https://pubmed.ncbi.nlm.nih.gov/?term=Fisher%20RS%5BAuthor%5D&cauthor=true&cauthor_uid=16146438); [Epilepsy Foundation of America Working Group](https://pubmed.ncbi.nlm.nih.gov/?term=Epilepsy%20Foundation%20of%20America%20Working%20Group%5BCorporate%20Author%5D). + +### GPII + +- [Accessibility Master List](https://ds.gpii.net/learn/accessibility-masterlist) Gregg Vanderheiden Ph.D. Editor + +### Harding + +Along with the PEAT tool, is generally recognized to be one of the two "gold standards" for analyzing flashes. + +- [Harding Flash and Pattern Analyzer](https://www.hardingfpa.com/) + +### ISO + +- [IEC 61966-2-2:2003(en)](https://www.iso.org/obp/ui/#iso:std:iec:61966:-2-2:ed-1:v1:en) Multimedia systems and equipment — Colour measurement and management — Part 2-2: Colour management — Extended RGB color space — scRGB + +### Photosensitive Epilepsy Analysis Tool + +Along with the Harding tool, is generally recognized to be one of the two "gold standards" for analyzing flashes. + +- [Trace Research and Development Center](https://trace.umd.edu/peat/) +- [Using PEAT To Create Seizureless Web Animations](https://www.useragentman.com/blog/2017/04/02/using-peat-to-create-seizureless-web-animations/) + +### W3C + +- [CSS Color Module Level 3](https://www.w3.org/TR/css-color-3/) +- [Personalization Semantics Explainer 1.0](https://www.w3.org/TR/personalization-semantics-1.0/). Working Draft +- [WAI-Adapt: Tools Module](https://www.w3.org/TR/adapt-tools/) Working Draft +- [Three Flashes or Below Threshold Understanding SC 2.3.1](https://www.w3.org/TR/UNDERSTANDING-WCAG20/seizure-does-not-violate.html) Understanding WCAG 2.0 (Older, but contains some explanations of references made in the WCAG 2.1 criteria) +- [Three Flashes or Below Threshold Understanding Success Criterion 2.3.1](https://www.w3.org/WAI/WCAG21/Understanding/three-flashes-or-below-threshold.html) Understanding WCAG 2.1 +- [Understanding Success Criteria 1.4.3: Contrast (Minimum)](https://www.w3.org/WAI/WCAG21/Understanding/contrast-minimum.html) +- [Web Accessibility Initiative (WAI)](https://www.w3.org/WAI/) +- [Web Animations Model](https://www.w3.org/TR/web-animations-1/) W3C Working Draft +- [Web Content Accessibility Guidelines (WCAG) 2.0](https://www.w3.org/TR/WCAG20/#relativeluminancedef) definition of relative luminance +- [Web Content Accessibility Guidelines (WCAG) 2.1](https://www.w3.org/TR/WCAG21/) + +## Contributors + +Heartfelt thanks to Teal; Wayne Dick of the [Low Vision Task Force of the W3C](https://www.w3.org/WAI/GL/task-forces/low-vision-a11y-tf/); Tom Jewett and Eric Eggert from [Knowbility](https://knowbility.org/); Jim Allan of the [Diagram Center](http://diagramcenter.org/); and Dr. Selim R. Benbadis, Director, [Comprehensive Epilepsy Program and Clinical Neurophysiology Laboratory at USF and TGH in Tampa, Florida](https://health.usf.edu/medicine/neurology/epilepsy) for their great, great assistance and discussions on this topic. + +We are _all_ in tremendous gratitude to the Trace Research & Development Center for making their amazing tool, the [Photosensitive Epilepsy Analysis Tool (PEAT)](https://trace.umd.edu/peat/) for free. diff --git a/files/en-us/web/accessibility/seizure_disorders/peatversion1pt6.png b/files/en-us/web/accessibility/guides/seizure_disorders/peatversion1pt6.png similarity index 100% rename from files/en-us/web/accessibility/seizure_disorders/peatversion1pt6.png rename to files/en-us/web/accessibility/guides/seizure_disorders/peatversion1pt6.png diff --git a/files/en-us/web/accessibility/seizure_disorders/screen_shot_2019-06-20_at_11.16.17_am.png b/files/en-us/web/accessibility/guides/seizure_disorders/screen_shot_2019-06-20_at_11.16.17_am.png similarity index 100% rename from files/en-us/web/accessibility/seizure_disorders/screen_shot_2019-06-20_at_11.16.17_am.png rename to files/en-us/web/accessibility/guides/seizure_disorders/screen_shot_2019-06-20_at_11.16.17_am.png diff --git a/files/en-us/web/accessibility/guides/understanding_wcag/index.md b/files/en-us/web/accessibility/guides/understanding_wcag/index.md new file mode 100644 index 000000000000000..dbdb961b6a66255 --- /dev/null +++ b/files/en-us/web/accessibility/guides/understanding_wcag/index.md @@ -0,0 +1,44 @@ +--- +title: Understanding the Web Content Accessibility Guidelines (WCAG) +short-title: Understanding WCAG +slug: Web/Accessibility/Guides/Understanding_WCAG +page-type: guide +sidebar: accessibilitysidebar +--- + +This set of articles provides quick explanations to help you understand the steps that need to be taken to conform to the recommendations outlined in the {{glossary("WCAG", "Web Content Accessibility Guidelines")}} (WCAG). + +The WCAG guidelines are a set of recommendations for making web content more accessible developed by W3C's {{Glossary("WAI")}}, primarily for people with disabilities — but also for all user agents, including some highly limited devices or services, such as digital assistants. + +WCAG 2.2 is the most recent version of the guidelines with WCAG 2.1 and 2.0 also widely used. WCAG 3.0 is the working draft. +Newer versions of WCAG are not meant to supersede previous versions, but WAI recommends using the most recent version to ensure the best possible accessibility for your website. + +## The four principles + +WCAG is broadly broken down into four principles — major things that web content **must be** to be considered accessible (see [Understanding the Four Principles of Accessibility](https://www.w3.org/WAI/WCAG22/Understanding/intro#understanding-the-four-principles-of-accessibility) for the WCAG definitions). + +Each of the links below will take you to pages that further expand on these areas, giving you practical advice on how to write your web content so it conforms to the success criteria outlined in the WCAG 2 four guiding principles. + +- [Perceivable](/en-US/docs/Web/Accessibility/Guides/Understanding_WCAG/Perceivable): Users must be able to perceive it in some way, using one or more of their senses. +- [Operable](/en-US/docs/Web/Accessibility/Guides/Understanding_WCAG/Operable): Users must be able to control UI elements (e.g., buttons must be clickable in some way — mouse, keyboard, voice command, etc.). +- [Understandable](/en-US/docs/Web/Accessibility/Guides/Understanding_WCAG/Understandable): The content must be understandable to its users. +- [Robust](/en-US/docs/Web/Accessibility/Guides/Understanding_WCAG/Robust): The content must be developed using well-adopted web standards that will work across different browsers, now and in the future. + +We also included two additional WCAG resources focused on making sites [keyboard accessible](/en-US/docs/Web/Accessibility/Guides/Understanding_WCAG/Keyboard) and provided descriptive names or labels with [text labels and names](/en-US/docs/Web/Accessibility/Guides/Understanding_WCAG/Text_labels_and_names). + +## Legal standing + +This introductory documentation is intended to provide practical information to help you build better, more accessible websites. However, we are not lawyers, and none of this constitutes legal advice. If you are worried about the legal implications of web accessibility, we recommend that you check the specific legislation governing accessibility for the web and public resources in your country or locale and seek the advice of a qualified lawyer. + +[What is accessibility?](/en-US/docs/Learn_web_development/Core/Accessibility/What_is_accessibility) and particularity the [Accessibility guidelines and the law](/en-US/docs/Learn_web_development/Core/Accessibility/What_is_accessibility#accessibility_guidelines_and_the_law) section provide more related information. + +## See also + +- [WCAG: Perceivable](/en-US/docs/Web/Accessibility/Guides/Understanding_WCAG/Perceivable) principle +- [WCAG: Operable](/en-US/docs/Web/Accessibility/Guides/Understanding_WCAG/Operable) principle +- [WCAG: Understandable](/en-US/docs/Web/Accessibility/Guides/Understanding_WCAG/Understandable) principle +- [WCAG: Robust](/en-US/docs/Web/Accessibility/Guides/Understanding_WCAG/Robust) principle +- [WCAG text labels and names](/en-US/docs/Web/Accessibility/Guides/Understanding_WCAG/Text_labels_and_names) +- [WCAG keyboard accessibility](/en-US/docs/Web/Accessibility/Guides/Understanding_WCAG/Keyboard) +- [WCAG Overview](https://www.w3.org/WAI/standards-guidelines/wcag/) +- [WCAG 2.2](https://www.w3.org/TR/WCAG22/) diff --git a/files/en-us/web/accessibility/guides/understanding_wcag/keyboard/index.md b/files/en-us/web/accessibility/guides/understanding_wcag/keyboard/index.md new file mode 100644 index 000000000000000..5c4d86e53f9b4b2 --- /dev/null +++ b/files/en-us/web/accessibility/guides/understanding_wcag/keyboard/index.md @@ -0,0 +1,76 @@ +--- +title: Keyboard accessible +slug: Web/Accessibility/Guides/Understanding_WCAG/Keyboard +page-type: guide +sidebar: accessibilitysidebar +--- + +To be fully accessible, a web page must be operable by someone using only a keyboard to access and control it. This includes users of screen readers, but can also include users who have trouble operating a pointing device such as a mouse or trackball, or whose mouse is not working at the moment, or who prefer to use a keyboard for input whenever possible. + +## Focusable elements should have interactive semantics + +If an element can be focused using the keyboard, then it should be interactive; that is, the user should be able to do something to it and produce a change of some kind (for example, activating a link or changing an option). + +> [!NOTE] +> One important exception to this rule is if the element has `role="document"` applied to it, **inside** an interactive context (such as `role="application"`). In such a case, focusing the nested document is the only way of returning assistive technology to a non-interactive state (often called "browse mode"). + +Most interactive elements are focusable by default; you can make an element focusable by adding a `tabindex=0` attribute value to it. However, you should only add `tabindex` if you have also made the element interactive, for example, by defining appropriate event handlers keyboard events. + +### See also + +- [tabindex](/en-US/docs/Web/HTML/Reference/Global_attributes/tabindex) global HTML attribute +- Element: [keydown event](/en-US/docs/Web/API/Element/keydown_event) +- Element: [keyup event](/en-US/docs/Web/API/Element/keyup_event) + +## Avoid using `tabindex` attribute greater than zero + +The `tabindex` attribute indicates that an element is focusable using the keyboard. A value of zero indicates that the element is part of the default focus order, which is based on the ordering of elements in the HTML document. A positive value puts the element ahead of those in the default ordering; elements with positive values are focused in the order of their `tabindex` values (1, then 2, then 3, etc.). + +This creates confusion for keyboard-only users when the focus order differs from the logical order of the page. A better strategy is to structure the HTML document so that focusable elements are in a logical order, without the need to re-order them with positive `tabindex` values. + +### See also + +- [tabindex](/en-US/docs/Web/HTML/Reference/Global_attributes/tabindex) global HTML attribute +- [Understanding focus order](https://www.w3.org/WAI/WCAG21/Understanding/focus-order.html) +- [Don't use tabindex greater than 0](https://adrianroselli.com/2014/11/dont-use-tabindex-greater-than-0.html) + +## Clickable elements must be focusable and should have interactive semantics + +If an element can be clicked with a pointing device, such as a mouse, then it should also be focusable using the keyboard, and the user should be able to do something by interacting with it. + +An element is clickable if it has an `onclick` event handler defined. You can make it focusable by adding a `tabindex=0` attribute value to it. You can make it operable with the keyboard by defining an `onkeydown` event handler; in most cases, the action taken by event handler should be the same for both types of events. + +### See also + +- [tabindex](/en-US/docs/Web/HTML/Reference/Global_attributes/tabindex) global HTML attribute +- Element: [keydown event](/en-US/docs/Web/API/Element/keydown_event) +- Element: [keyup event](/en-US/docs/Web/API/Element/keyup_event) + +## Interactive elements must be able to be activated using a keyboard + +If the user can interact with an element using touch or a pointing device, then the element should also support interacting using the keyboard. That is, if you have defined event handlers for touch or click events, you should also define them for keyboard events. The keyboard event handlers should enable effectively the same interaction as the touch or click handlers. + +### See also + +- Element: [keydown event](/en-US/docs/Web/API/Element/keydown_event) +- Element: [keyup event](/en-US/docs/Web/API/Element/keyup_event) + +## Interactive elements must be focusable + +If the user can interact with an element (for example, using touch or a pointing device), then it should be focusable using the keyboard. You can make it focusable by adding a `tabindex=0` attribute value to it. That will add the element to the list of elements that can be focused by pressing the <kbd>Tab</kbd> key, in the sequence of such elements as defined in the HTML document. + +### See also + +- [tabindex](/en-US/docs/Web/HTML/Reference/Global_attributes/tabindex) global HTML attribute + +## Focusable element must have focus styling + +Any element that can receive keyboard focus should have visible styling that indicates when the element is focused. You can do this with the [`:focus`](/en-US/docs/Web/CSS/:focus) and [`:focus-visible`](/en-US/docs/Web/CSS/:focus-visible) CSS pseudo-classes. + +Standard focusable elements such as links and input fields are given special styling by the browser by default, so you might not need to specify focus styling for such elements, unless you want the focus styling to be more distinctive. + +If you create your own focusable components, be sure that you also define focus styling for them. + +### See also + +- [Using CSS to change the presentation of a UI component when it receives focus](https://www.w3.org/WAI/WCAG21/Techniques/css/C15.html) diff --git a/files/en-us/web/accessibility/guides/understanding_wcag/operable/index.md b/files/en-us/web/accessibility/guides/understanding_wcag/operable/index.md new file mode 100644 index 000000000000000..53951a818f5ad3a --- /dev/null +++ b/files/en-us/web/accessibility/guides/understanding_wcag/operable/index.md @@ -0,0 +1,578 @@ +--- +title: Operable +slug: Web/Accessibility/Guides/Understanding_WCAG/Operable +page-type: guide +sidebar: accessibilitysidebar +--- + +This article provides practical advice on how to write your web content so that it conforms to the success criteria outlined in the **Operable** principle of the Web Content Accessibility Guidelines (WCAG) 2.0 and 2.1. Operable states that user interface components and navigation must be operable. + +> [!NOTE] +> To read the W3C definitions for Operable and its guidelines and success criteria, see [Principle 2: Operable — User interface components and navigation must be operable.](https://www.w3.org/TR/WCAG21/#operable) + +## Guideline 2.1 — Keyboard Accessible: Make all functionality available from a keyboard + +This guideline covers the necessity of making core website functionality available via a keyboard in addition to other means (e.g., mouse), so that users that rely on keyboard controls can access them. + +<table class="standard-table"> + <thead> + <tr> + <th scope="col">Success criteria</th> + <th scope="col">How to conform to the criteria</th> + <th scope="col">Practical resource</th> + </tr> + </thead> + <tbody> + <tr> + <td>2.1.1 Keyboard (A)</td> + <td> + All functionality should be accessible using keyboard controls, unless + it cannot be done using the keyboard (e.g., freehand drawing). Built-in + controls should be used where possible (e.g., tabbing through form + controls), and you should only build in custom functionality where + needed. + </td> + <td> + See + <a href="/en-US/docs/Learn_web_development/Core/Accessibility/HTML#use_semantic_ui_controls_where_possible" + >Use semantic UI controls where possible</a + > + and + <a + href="/en-US/docs/Learn_web_development/Core/Accessibility/HTML#building_keyboard_accessibility_back_in" + >Building keyboard accessibility back in</a + > + </td> + </tr> + <tr> + <td>2.1.2 No keyboard trap (A)</td> + <td> + <p> + When entering a section of functionality using the keyboard, you + should be able to get out of that section again using <em>only</em> the + keyboard. For example, if you press <kbd>Enter</kbd>/<kbd>Return</kbd> + on a focused button to open an options window, you should be able to + close that window again and return to the main content using the + keyboard. + </p> + <p> + This is very important so that keyboard users do not get trapped on + specific sections of your apps. + </p> + </td> + <td></td> + </tr> + <tr> + <td>2.1.3 Keyboard — all functionality (AAA)</td> + <td> + This is a further step beyond criterion 2.1.1. To achieve AAA + conformance, all functionality should be accessible using keyboard + controls — with no exceptions. + </td> + <td> + See + <a href="/en-US/docs/Learn_web_development/Core/Accessibility/HTML#use_semantic_ui_controls_where_possible" + >Use semantic UI controls where possible</a + > + and + <a + href="/en-US/docs/Learn_web_development/Core/Accessibility/HTML#building_keyboard_accessibility_back_in" + >Building keyboard accessibility back in</a + > + </td> + </tr> + <tr> + <td> + 2.1.4 Character Key Shortcuts (A) + <em + ><a href="https://www.w3.org/TR/WCAG21/#new-features-in-wcag-2-1" + >added in 2.1</a + ></em + > + </td> + <td> + If a single character key shortcut exists, then at least one of the + following is true: single character key shortcuts can be turned off, + remapped or are only active when the relevant user interface component + is in focus. + </td> + <td> + <a + href="https://www.w3.org/WAI/WCAG21/Understanding/character-key-shortcuts.html" + >Understanding Character Key Shortcuts</a + > + </td> + </tr> + </tbody> +</table> + +> [!NOTE] +> Also see the WCAG description for [Guideline 2.1 Keyboard Accessible: Make all functionality available from a keyboard](https://www.w3.org/TR/WCAG21/#keyboard-accessible). + +## Guideline 2.2 — Enough Time: Provide users enough time to read and use content + +This guideline covers situations in which functionality may have a time limit. For example, purchases sometimes need to be completed within a time limit for security reasons. + +<table class="standard-table"> + <thead> + <tr> + <th scope="col">Success criteria</th> + <th scope="col">How to conform to the criteria</th> + <th scope="col">Practical resource</th> + </tr> + </thead> + <tbody> + <tr> + <td>2.2.1 Timing is adjustable (A)</td> + <td> + <p> + For functionality with time limits (e.g., completing a hotel or flight + booking often has a time limit), the user should be given controls to + allow them to adjust, extend or turn off the time limit. + </p> + <p> + Exceptions to this are activities with time limits longer than 20 + hours, real time events (e.g., live multiplayer games), and any other + activity that requires a time limit and would be invalidated if it + were turned off. + </p> + </td> + <td></td> + </tr> + <tr> + <td>2.2.2 Pausing, stopping, hiding (A)</td> + <td> + <p> + For moving/blinking content that starts automatically, lasts longer + than 5 seconds, and is shown alongside other content, controls should + be provided to pause, stop, or hide it. This does not apply to + moving/blinking content that is essential to the experience. Examples + include scrolling text and videos. + </p> + <p> + For auto-updating information that starts automatically and is shown + alongside other content, controls should be provided to pause, stop, + or hide it, or to control the frequency of updates. This does not + apply to auto-updating content that is essential to the experience. + Examples include carousels or rotating announcements. + </p> + </td> + <td></td> + </tr> + <tr> + <td>2.2.3 No time limits (AAA)</td> + <td> + This builds on criteria 2.2.1, stating that content that wants to pass + AAA conformance should have no time limits. + </td> + <td></td> + </tr> + <tr> + <td>2.2.4 Suppress interruptions (AAA)</td> + <td> + Any interruptions such as alerts or interstitial adverts should have + functionality available to suppress or postpone them, unless it is an + emergency alert. + </td> + <td></td> + </tr> + <tr> + <td>2.2.5 Re-authenticating (AAA)</td> + <td> + If an authentication session expires during usage of a web app, the user + can re-authenticate and continue their usage without losing any data. + </td> + <td></td> + </tr> + <tr> + <td> + 2.2.6 Timeouts (AAA) + <em + ><a href="https://www.w3.org/TR/WCAG21/#new-features-in-wcag-2-1" + >added in 2.1</a + ></em + > + </td> + <td> + <p> + If there is a timeout (caused by user inactivity) warn users at the + start of a process so they will not be surprised that a timeout exists + (or only allow the timeout to occur after 20 hours of inactivity). + </p> + </td> + <td> + <a href="https://www.w3.org/WAI/WCAG21/Understanding/timeouts.html" + >Understanding Timeouts</a + > + </td> + </tr> + </tbody> +</table> + +> [!NOTE] +> Also see the WCAG description for [Guideline 2.2 Enough Time: Provide users enough time to read and use content](https://www.w3.org/TR/WCAG21/#enough-time). + +## Guideline 2.3 — Seizures and Physical Reactions: Do not design content in a way that is known to cause seizures or physical reactions + +This refers to content that, if not changed, could cause seizures in users with conditions such as epilepsy OR could cause physical reactions (like dizziness) for users with conditions such as vestibular disorders. + +<table> + <thead> + <tr> + <th scope="col">Success criteria</th> + <th scope="col">How to conform to the criteria</th> + <th scope="col">Practical resource</th> + </tr> + </thead> + <tbody> + <tr> + <td>2.3.1 Three flashes, or below threshold (A)</td> + <td>Content doesn't contain any aspect that Flashes more than three times per second, or flashing content is below acceptable <a href="https://www.w3.org/TR/WCAG20/#general-thresholddef">flash and red flash thresholds</a>.</td> + <td></td> + </tr> + <tr> + <td>2.3.2 Three flashes (AAA)</td> + <td>Content doesn't contain any aspect that Flashes more than three times per second.</td> + <td></td> + </tr> + <tr> + <td>2.3.3 Animations from Interactions (AAA) <em><a href="https://www.w3.org/TR/WCAG21/#new-features-in-wcag-2-1">added in 2.1</a></em></td> + <td>Allow users to disable animations from interactions (unless the animation is essential).</td> + <td><a href="https://www.w3.org/TR/WCAG21/#animation-from-interactions">Understanding Animations from Interactions</a></td> + </tr> + </tbody> +</table> + +> [!NOTE] +> Also see the WCAG description for [Guideline 2.3 Seizures and Physical Reactions: Do not design content in a way that is known to cause seizures or physical reactions.](https://www.w3.org/TR/WCAG21/#seizures-and-physical-reactions) + +## Guideline 2.4 — Navigable: Provide ways to help users navigate, find content, and determine where they are + +The conformance criteria under this guideline relate to ways in which users can be expected to orientate themselves, and find the content and functionality they are looking for on the current page or other pages of the site. + +<table class="standard-table"> + <thead> + <tr> + <th scope="col">Success criteria</th> + <th scope="col">How to conform to the criteria</th> + <th scope="col">Practical resource</th> + </tr> + </thead> + <tbody> + <tr> + <td>2.4.1 Bypass blocks (A)</td> + <td> + <p> + A mechanism should be provided that allows the user to skip straight + to the main content or functionality available on the page, past the + repeated features (such as the company logo or navigation). This is + often achieved using "skip links" — links put at the top of the page + source that link to the main content and are hidden by CSS. + </p> + <p> + If a proper structure of headings and semantic containers is provided + to navigate with (for example {{htmlelement("section")}}, + {{htmlelement("aside")}}, etc.), then an added "skip link" is + not needed. + </p> + </td> + <td><em>Need to add a section on "skip links".</em></td> + </tr> + <tr> + <td>2.4.2 Include page title (A)</td> + <td> + Each web page should include an informative + {{htmlelement("title")}}, the content of which describes the + page's content/purpose. + </td> + <td> + See + <a + href="/en-US/docs/Learn_web_development/Core/Structuring_content/Webpage_metadata#adding_a_title" + >Adding a title</a + >. + </td> + </tr> + <tr> + <td>2.4.3 Logical focus order (A)</td> + <td> + The "tabbing order" of focusable page features (e.g., links, buttons, + form inputs) makes logical sense, meaning that the page is still usable + by non-sighted/keyboard users. + </td> + <td> + See + <a href="/en-US/docs/Learn_web_development/Core/Accessibility/HTML#use_semantic_ui_controls_where_possible" + >Use semantic UI controls where possible</a + > + for general advice on tabbing to controls. If you need to place elements + in an unusual layout, it is better to make sure the source order is + sensible, then use CSS features like + <a href="/en-US/docs/Learn_web_development/Core/CSS_layout/Positioning">positioning</a> + to handle the layout. + </td> + </tr> + <tr> + <td>2.4.4 Link purpose (in context) (A)</td> + <td> + The purpose/destination of a link can be determined from the link text, + or from its surroundings (e.g., the surrounding text). Exceptions are + where the link purpose is ambiguous to <em>all</em> users (see + <a href="https://www.w3.org/TR/WCAG20/#ambiguouslinkdef" + >ambiguous to users in general</a + > + for a useful explanation of this). + </td> + <td> + See + <a href="/en-US/docs/Learn_web_development/Core/Accessibility/HTML#use_meaningful_text_labels" + >Use meaningful text labels</a + >. Also note that you should minimize instances where multiple copies of + the same text are linked to different places. This can cause problems + for screen reader users, who will often bring up a list of the links out + of context — several links all labelled "click here", "click here", + "click here" would be confusing. + </td> + </tr> + <tr> + <td>2.4.5 Multiple navigation mechanisms (AA)</td> + <td> + <p> + You should provide at least two general navigation mechanisms to find + pages on your website, for example navigation menu, breadcrumb trail, + site search, site map, list of related links, etc. + </p> + <p> + The only exception to this is where a page is one step in a process, + so should only logically have links to the previous and next steps. + </p> + </td> + <td> + Most of these mechanisms can be created using fully supported HTML features, for + example see + <a + href="/en-US/docs/Learn_web_development/Extensions/Forms/HTML5_input_types#search_field" + >Search field</a + >, + <a + href="/en-US/docs/Learn_web_development/Core/Structuring_content/Creating_links#active_learning_creating_a_navigation_menu" + >Creating a navigation menu</a + >, + <a + href="/en-US/docs/Learn_web_development/Core/Text_styling/Styling_links#styling_links_as_buttons" + >Styling links as buttons</a + >. + </td> + </tr> + <tr> + <td>2.4.6 Headings and labels (AA)</td> + <td> + Heading (e.g., {{htmlelement("Heading_Elements", "&lt;h2&gt;")}}) and + {{htmlelement("label")}} elements clearly describe the purpose + of the content and form elements they are supposed to be describing. + </td> + <td> + <p> + See + <a href="/en-US/docs/Learn_web_development/Core/Accessibility/HTML#use_semantic_ui_controls_where_possible" + >Use semantic UI controls where possible</a + >, + <a href="/en-US/docs/Learn_web_development/Core/Accessibility/HTML#use_meaningful_text_labels" + >Use meaningful text labels</a + >, + <a + href="/en-US/docs/Learn_web_development/Core/Structuring_content/Headings_and_paragraphs" + >The basics of headings and paragraphs</a + >, + <a + href="/en-US/docs/Learn_web_development/Extensions/Forms/How_to_structure_a_web_form#the_label_element" + >The &#x3C;label> element</a + >. + </p> + <p> + Note that you should avoid duplicating headings or labels (e.g. + multiple instances of "Further information"), unless the structure + allows you to differentiate between them easily. + </p> + </td> + </tr> + <tr> + <td>2.4.7 Visible focus for focusable elements (AA)</td> + <td> + When tabbing through focusable elements such as links or form inputs, + there should be a visual indicator to show you which element currently + has focus. This is usually a dotted or blue outline by default + (depending on browser, platform, etc.), but this can be overridden by + CSS. + </td> + <td> + See + <a + href="/en-US/docs/Learn_web_development/Core/Accessibility/HTML#use_semantic_ui_controls_where_possible" + >Use semantic UI controls where possible</a + >. + </td> + </tr> + <tr> + <td>2.4.8 Location within site (AAA)</td> + <td> + When on a page inside a complex site or set of steps, the user should be + given an indicator of where they are in the site, for example a + breadcrumb trail, sitemap or text such as "Form page 2 of 10". + </td> + <td></td> + </tr> + <tr> + <td>2.4.9 Link purpose (link only) (AAA)</td> + <td> + This criterion builds on 2.4.4, stating that to conform to AAA, the + purpose/destination of a link should be determinable from the link text + alone, even if out of context. + </td> + <td> + See + <a href="/en-US/docs/Learn_web_development/Core/Accessibility/HTML#use_meaningful_text_labels" + >Use meaningful text labels</a + >. Also note that you should minimize instances where multiple copies of + the same text are linked to different places. This can cause problems + for screen reader users, who will often bring up a list of the links out + of context — several links all labelled "click here", "click here", + "click here" would be confusing. + </td> + </tr> + <tr> + <td>2.4.10 Section headings (AAA)</td> + <td> + <p> + As well as creating a useful document structure, headings should also + accurately describe and break up content areas into logical sections. + </p> + <p> + Note that this criterion refers to headings and titles in general web + content (e.g., headings within text content). Headings and titles for + user interfaces are a special case covered in criterion 4.1.2. + </p> + </td> + <td> + <p> + See + <a + href="/en-US/docs/Learn_web_development/Core/Structuring_content/Headings_and_paragraphs" + >The basics of headings and paragraphs</a + >. + </p> + </td> + </tr> + <tr> + <td> 2.4.11 Focus not obscured (Minimum) (AA)</td> + <td> + <p> When a user interface component receives keyboard focus, the component is not entirely hidden due to containing author-created content.</p> + <p> <strong>Note:</strong> If the interface's content can be repositioned by the user, then only the initial position of the user-movable content is considered for testing to conform to this standard. Also, content opened by the user may obscure the component receiving focus. Furthermore, if the user can reveal the focused component without changing keyboard focus, the component with focus is not considered hidden for conformance and testing purposes.</p> + </td> + <td> + <p> Check out <a href="https://www.w3.org/WAI/WCAG22/Understanding/focus-not-obscured-minimum">Understanding focus not obscured (Minimum)</a> to learn more about this standard.</p> + </td> + </tr> + <tr> + <td> 2.4.12 Focus not obscured (Enhanced) (AAA) </td> + <td> + <p> Follows the rules as 2.4.11 except when a user interface component receives focus, no part of the component can be hidden by author-created content. If the interface is configurable, only the initial positions of user-movable content are considered for testing and meeting of this standard.</p> + </td> + <td> + <p> Check out <a href="https://www.w3.org/WAI/WCAG22/Understanding/focus-not-obscured-enhanced">Understanding focus not obscured (Enhanced) (Level AAA)</a> to learn more about this standard.</p> </td> + </td> + </tr> +<tr> + <td> 2.4.13 Focus appearance (AAA)</td> + <td> + <p>When the keyboard focus indicator is visible, the area of the focus indicator meets all the following:</p> + <ul> + <li>Must be at least as large as the area of a <code>2px</code> thick perimeter of the unfocused component or sub-component, which includes component's content, border, and background, excluding outer shadows or glow effects.</li> + <li>Needs to have a contrast ratio of at least 3:1 between the same pixels in the focused and unfocused states</li> + </ul> + <p> The exceptions to this are:</p> + <ul> + <li>The focus indicator is determined by the user and cannot be adjusted by the author.</li> + <li>The focus indicator and the indicator's background color are not modified by the author.</li> + </ul> + </td> + <td> + <p> Check out <a href="https://www.w3.org/WAI/WCAG22/Understanding/focus-appearance.html">Understanding focus appearance (Level AAA)</a> to learn more about this standard.</p> + </td> +</tr> + </tbody> +</table> + +> [!NOTE] +> Also see the WCAG description for [Guideline 2.4 Navigable: Provide ways to help users navigate, find content, and determine where they are.](https://www.w3.org/TR/WCAG21/#navigable) + +## Guideline 2.5 Input Modalities: Make it easier for users to operate functionality through various inputs beyond keyboard + +The conformance criteria under this guideline ensures that users are able to interact with digital technology using different input methods beyond a keyboard or mouse (including touchscreen, voice, device motion, or alternative input devices). + +<table> + <thead> + <tr> + <th scope="col">Success criteria</th> + <th scope="col">How to conform to the criteria</th> + <th scope="col">Practical resource</th> + </tr> + </thead> + <tbody> + <tr> + <td>2.5.1 Pointer Gestures (A) <em><a href="https://www.w3.org/TR/WCAG21/#new-features-in-wcag-2-1">added in 2.1</a></em></td> + <td>All functionality that can be operated with a pointer can be operated with single-point actions. Path-based or multi-point gestures are not required to operate any functionality. Exceptions exist.</td> + <td><a href="https://www.w3.org/WAI/WCAG21/Understanding/pointer-gestures.html">Understanding Pointer Gestures</a></td> + </tr> + <tr> + <td>2.5.2 Pointer Cancellation (A) <em><a href="https://www.w3.org/TR/WCAG21/#new-features-in-wcag-2-1">added in 2.1</a></em></td> + <td>For functionality that can be operated using a single-pointer at least one of the following is true: no down-event, abort/undo, up reversal or essential.</td> + <td><a href="https://www.w3.org/WAI/WCAG21/Understanding/pointer-cancellation.html">Understanding Pointer Cancellation</a></td> + </tr> + <tr> + <td>2.5.3 Label in Name (A) <em><a href="https://www.w3.org/TR/WCAG21/#new-features-in-wcag-2-1">added in 2.1</a></em></td> + <td>For each user interface component that includes a visible text label, make sure the accessible name matches (or includes) the visible text in the label.</td> + <td><a href="https://www.w3.org/WAI/WCAG21/Understanding/label-in-name.html">Understanding Label in Name</a></td> + </tr> + <tr> + <td>2.5.4 Motion Actuation (A) <em><a href="https://www.w3.org/TR/WCAG21/#new-features-in-wcag-2-1">added in 2.1</a></em></td> + <td>Ensure that for functionality that can be triggered by a) device motion (like shaking, tilting) or b) user gestures detected by device sensors (including a camera) that both of the following are true: 1) motion actuation can be disabled, and 2) the functionality can be operated without using device motion or user gestures. Exceptions exist.</td> + <td><a href="https://www.w3.org/WAI/WCAG21/Understanding/motion-actuation.html">Understanding Motion Actuation</a></td> + </tr> + <tr> + <td>2.5.5 Target Size (AAA) <em><a href="https://www.w3.org/TR/WCAG21/#new-features-in-wcag-2-1">added in 2.1</a></em></td> + <td>The size of an actionable item's touch target must be at least 44 CSS pixels in both width and height. Exceptions exist.</td> + <td><a href="https://www.w3.org/WAI/WCAG21/Understanding/target-size.html">Understanding Target Size</a></td> + </tr> + <tr> + <td>2.5.6 Concurrent Input Mechanisms (AAA) <em><a href="https://www.w3.org/TR/WCAG21/#new-features-in-wcag-2-1">added in 2.1</a></em></td> + <td>Make sure people can use and switch between different modes of input when interacting with digital content including touchscreen, keyboard, mouse, voice commands, or alternative input devices. An essential exception exists. </td> + <td><a href="https://www.w3.org/WAI/WCAG21/Understanding/concurrent-input-mechanisms.html">Understanding Concurrent Input Mechanism</a></td> + </tr> + <tr> + <td> 2.5.8 Target size minimum (AA)</td> + <td> Target size for pointer inputs should be at least <code>24px</code> wide by <code>24px</code> tall except for the following areas: + <ul> + <li> <strong>Spacing:</strong>Targets that are less than <code>24px x 24px</code> are positioned so that if a <code>24px</code> diameter circle is centered on each target's bounding box, the circles do not intersect with any other target or the circle for another undersized target.</li> + <li> <strong>Equivalent:</strong> A separate control that achieves the same function that meets this standard is available on the same page.</li> + <li> <strong>Inline:</strong> The target is located within a line of text with its size constrained by the line height or surrounding non-target text.</li> + <li> <strong>User agent control:</strong> The target's size is determined by the user agent and has not been modified by the author.</li> + <li> <strong>Essential:</strong> A particular presentation of the target is essential or legally required for the information being conveyed.</li> + </ul> + <td> Check out <a href="https://www.w3.org/WAI/WCAG22/Understanding/target-size-minimum.html">Understanding target size minimum</a> </td> +</tr> + </tr> + </tbody> +</table> + +> [!NOTE] +> Also see the WCAG description for [Guideline 2.5: Input Modalities: Make it easier for users to operate functionality through various inputs beyond keyboard.](https://www.w3.org/TR/WCAG21/#input-modalities) + +## See also + +- [WCAG](/en-US/docs/Web/Accessibility/Guides/Understanding_WCAG) + + 1. [Perceivable](/en-US/docs/Web/Accessibility/Guides/Understanding_WCAG/Perceivable) + 2. Operable + 3. [Understandable](/en-US/docs/Web/Accessibility/Guides/Understanding_WCAG/Understandable) + 4. [Robust](/en-US/docs/Web/Accessibility/Guides/Understanding_WCAG/Robust) diff --git a/files/en-us/web/accessibility/guides/understanding_wcag/perceivable/color_contrast/index.md b/files/en-us/web/accessibility/guides/understanding_wcag/perceivable/color_contrast/index.md new file mode 100644 index 000000000000000..f32deea6a33bd4f --- /dev/null +++ b/files/en-us/web/accessibility/guides/understanding_wcag/perceivable/color_contrast/index.md @@ -0,0 +1,138 @@ +--- +title: Color contrast +slug: Web/Accessibility/Guides/Understanding_WCAG/Perceivable/Color_contrast +page-type: guide +sidebar: accessibilitysidebar +--- + +The [color contrast](https://www.w3.org/TR/WCAG21/#dfn-contrast-ratio) between background and foreground content (that is, usually text) should be great enough to ensure legibility. + +When designing readable interfaces for different vision capabilities, the WCAG guidelines recommend the following contrast ratios: + +| Type of content | Minimum ratio (AA rating) | Enhanced ratio (AAA rating) | +| ------------------------------------------------------------------------------- | ------------------------- | --------------------------- | +| Body text | 4.5 : 1 | 7 : 1 | +| Large-scale text (120-150% larger than body text) | 3 : 1 | 4.5 : 1 | +| Active user interface components and graphical objects such as icons and graphs | 3 : 1 | Not defined | + +These ratios do not apply to "incidental" text, such as inactive controls, logotypes, or purely decorative text. + +See the [Solution](#solution) section below for further information. + +Having good color contrast on your site benefits all your users, but it is particularly beneficial to users with certain types of color blindness and other similar conditions, who experience low contrast, and have trouble differentiating between similar colors. This is because they don't see bright and dark areas as readily as those without such conditions, and therefore have trouble seeing edges, borders, and other details. + +It is good to have a cool design on your website, but the design is worthless if your users can't read your content. + +## Examples + +Let's have a look at some HTML and CSS code: + +```html +<div class="good">Good contrast</div> +<div class="bad">Bad contrast</div> +``` + +```css +div { + /* General div styles here */ +} + +.good { + background-color: #5a80a9; +} + +.bad { + background-color: #400064; +} +``` + +Both pieces of text have their default black color. + +### Good Contrast + +The "good" `<div>` has a neon blue background, which makes the text easy to read: + +```html +<div class="good">Good contrast</div> +``` + +```css +div { + font-family: sans-serif; + text-align: center; + font-size: 2rem; + font-weight: bold; + width: 250px; + padding: 30px; + border-radius: 20px; + box-shadow: 4px 4px 4px black; +} + +.good { + background-color: #5a80a9; +} +``` + +{{EmbedLiveSample('Good_Contrast', '100%', '100')}} + +### Bad Contrast + +The "bad" `<div>` on the other hand has a very dark purple background, which makes the text much harder to read: + +```html +<div class="bad">Bad contrast</div> +``` + +```css +div { + font-family: sans-serif; + text-align: center; + font-size: 2rem; + font-weight: bold; + width: 250px; + padding: 30px; + border-radius: 20px; + box-shadow: 4px 4px 4px black; +} + +.bad { + background-color: #400064; +} +``` + +{{EmbedLiveSample('Bad_Contrast', '100%', '100')}} + +## Solution + +When choosing a color scheme for your website, choose foreground and background colors that have good contrast. Make the color contrast as good as it can be within your design constraints — ideally go for the AAA rating (see 1.4.6 below), but at least meet the AA rating (see 1.4.3 below). + +If you are including non-text content such as video or animation, you should follow 1.4.11 (again, see below). + +To check your contrast as you make your color choices, use a tool such as WebAIM's [Color Contrast Checker](https://webaim.org/resources/contrastchecker/). + +You can also check color contrast on the fly using Firefox's Developer Tools — see the [Accessibility inspector](https://firefox-source-docs.mozilla.org/devtools-user/accessibility_inspector/index.html) guide, and in particular the section [Check for accessibility issues](https://firefox-source-docs.mozilla.org/devtools-user/accessibility_inspector/index.html#check-for-accessibility-issues). Try using it on the live examples in the description section. + +## Related WCAG success criteria + +- [1.4.3 Minimum contrast (AA)](https://www.w3.org/TR/WCAG21/#contrast-minimum) + + - : The color contrast between background and foreground content should be at a minimum level to ensure legibility: + + - Text and its background should have a contrast ratio of at least 4.5:1. + - Heading (or just larger) text should have a ratio of at least 3:1. Larger text is defined as at least 18pt, or 14pt bold. + +- [1.4.6 Enhanced contrast (AAA)](https://www.w3.org/TR/WCAG21/#contrast-enhanced) + + - : This follows, and builds on, criterion 1.4.3. + + - Text and its background should have a contrast ratio of at least 7:1. + - Heading (or just larger) text should have a ratio of at least 4.5:1. + +- [1.4.11 Non-Text Contrast (AA)](https://www.w3.org/TR/WCAG21/#non-text-contrast) (added in 2.1) + - : There should be a minimum color contrast ratio of 3 to 1 for user interface components and graphical objects. + +## See also + +- [Color and color contrast](/en-US/docs/Learn_web_development/Core/Accessibility/CSS_and_JavaScript#color_and_color_contrast) +- [Multiple labels](/en-US/docs/Learn_web_development/Extensions/Forms/How_to_structure_a_web_form#multiple_labels) +- [Understanding Non-Text Contrast](https://www.w3.org/WAI/WCAG21/Understanding/non-text-contrast.html) diff --git a/files/en-us/web/accessibility/guides/understanding_wcag/perceivable/index.md b/files/en-us/web/accessibility/guides/understanding_wcag/perceivable/index.md new file mode 100644 index 000000000000000..8d93d47c70ecfd2 --- /dev/null +++ b/files/en-us/web/accessibility/guides/understanding_wcag/perceivable/index.md @@ -0,0 +1,667 @@ +--- +title: Perceivable +slug: Web/Accessibility/Guides/Understanding_WCAG/Perceivable +page-type: guide +sidebar: accessibilitysidebar +--- + +This article provides practical advice on how to write your web content so that it conforms to the success criteria outlined in the **Perceivable** principle of the Web Content Accessibility Guidelines (WCAG) 2.0 and 2.1. Perceivable states that users must be able to perceive it in some way, using one or more of their senses. + +> [!NOTE] +> To read the W3C definitions for Perceivable and its guidelines and success criteria, see [Principle 1: Perceivable - Information and user interface components must be presentable to users in ways they can perceive.](https://www.w3.org/TR/WCAG21/#perceivable) + +## Guideline 1.1 — Providing text alternatives for non-text content + +The key here is that text can be converted to other forms that people with disabilities can use. For example, it can be spoken by a screen reader, converted to large print, or represented on a braille display. Non-text content refers to multimedia such as images, audio, and video. + +<table class="standard-table"> + <thead> + <tr> + <th scope="col">Success criteria</th> + <th scope="col">How to conform to the criteria</th> + <th scope="col">Practical resource</th> + </tr> + </thead> + <tbody> + <tr> + <td rowspan="5">1.1.1 Provide text equivalents (A)</td> + <td> + All images that convey meaningful content should be given suitable + alternative text. + </td> + <td> + <a href="/en-US/docs/Learn_web_development/Core/Accessibility/HTML#text_alternatives" + >Text alternatives.</a + > + </td> + </tr> + <tr> + <td> + Complex images or charts should have an accessible alternative provided, + either on the same page or via a link. Use a regular link instead of + a <code>longdesc</code> attribute. + </td> + <td> + <p> + A text description may work, or an accessible data table (see + <a href="/en-US/docs/Learn_web_development/Core/Structuring_content/Table_accessibility" + >HTML table accessibility</a + >). See W3C's + <a href="https://www.w3.org/TR/html-longdesc/">Image Description Extension (longdesc)</a> + for the argument against <code>longdesc</code>. + </p> + </td> + </tr> + <tr> + <td> + Multimedia content (i.e., audio or video) should at least have a + descriptive identification available, such as a caption or similar. + </td> + <td> + <p> + See <a href="/en-US/docs/Learn_web_development/Core/Accessibility/HTML#text_alternatives" + >Text alternatives</a + > + for static caption options, and + <a href="/en-US/docs/Learn_web_development/Core/Accessibility/Multimedia#audio_transcripts" + >Audio transcripts</a + >, + <a href="/en-US/docs/Learn_web_development/Core/Accessibility/Multimedia#video_text_tracks" + >Video text tracks</a + > + for other alternatives. + </p> + </td> + </tr> + <tr> + <td> + UI controls such as form elements and buttons should have text labels + that describe their purpose. + </td> + <td> + Buttons are simple—you should make sure the button text describes the + function of the button (e.g., <code + >&#x3C;button>Upload image&#x3C;/button></code + >). For more information on other UI controls, see + <a href="/en-US/docs/Learn_web_development/Core/Accessibility/HTML#use_semantic_ui_controls_where_possible" + >Use semantic UI controls where possible</a + >. + </td> + </tr> + <tr> + <td> + Implement decorative (non-content) images, video, etc., in a way that is + invisible to assistive technology, so it doesn't confuse users. + </td> + <td> + <p> + Decorative images should be implemented using CSS background images + (see + <a + href="/en-US/docs/Learn_web_development/Core/Styling_basics/Backgrounds_and_borders" + >Backgrounds and borders</a + >). If you have to include an image via an + {{htmlelement("img")}} element, give it a blank alt + (<code>alt=""</code>). Otherwise, screen readers may try to read out + the filepath, etc. + </p> + <p> + If you are including background video or audio that autoplays, make it + as unobtrusive as possible. Don't make it look/sound like content, and + provide a control to turn it off. Ideally, don't include it at all. + </p> + </td> + </tr> + </tbody> +</table> + +> [!NOTE] +> Also see the [WCAG description for Guideline 1.1: Text alternatives](https://www.w3.org/TR/WCAG21/#text-alternatives). + +## Guideline 1.2 — Providing text alternatives for time-based media + +Time-based media refers to multimedia with a duration, such as audio and video. Note that if the audio/video serves as an alternative to existing text content, you don't need to provide another text alternative. + +<table> + <thead> + <tr> + <th scope="col">Success criteria</th> + <th scope="col">How to conform to the criteria</th> + <th scope="col">Practical resource</th> + </tr> + </thead> + <tbody> + <tr> + <td>1.2.1 Provide alternatives for pre-recorded audio-only and video-only content (A)</td> + <td>A transcript should be provided for prerecorded audio-only media, and a transcript or audio description should be provided for prerecorded video-only media (i.e., silent video).</td> + <td>See&nbsp;<a href="/en-US/docs/Learn_web_development/Core/Accessibility/Multimedia#audio_transcripts">Audio transcripts</a> for transcript information. No audio description tutorial is available yet.</td> + </tr> + <tr> + <td>1.2.2 Provide captions for web-based video (A)</td> + <td>You should provide captions for video presented on the web (e.g., HTML video). This is for the benefit of people who can't hear the audio part of the video.</td> + <td>See <a href="/en-US/docs/Learn_web_development/Core/Accessibility/Multimedia#video_text_tracks">Video text tracks</a> for HTML video captions. See also <a href="https://support.google.com/youtube/answer/2734796?hl=en">Add your own subtitles &amp; closed captions</a> (YouTube).</td> + </tr> + <tr> + <td>1.2.3 Provide text transcript or audio description for web-based video (A)</td> + <td>You should provide text transcripts or audio descriptions for video presented on the web (e.g., HTML video. This is for the benefit of people who can't see the visual part of the video, and don't get the full content from the audio alone.</td> + <td>See&nbsp;<a href="/en-US/docs/Learn_web_development/Core/Accessibility/Multimedia#audio_transcripts">Audio transcripts</a> for transcript information. No audio description tutorial is available yet.</td> + </tr> + <tr> + <td>1.2.4 Provide captions for live audio (AA)</td> + <td>You should provide synchronized captions for all live multimedia that contains audio (e.g., video conferences, live audio broadcasts).</td> + <td></td> + </tr> + <tr> + <td>1.2.5 Provide audio descriptions for prerecorded video (AA)</td> + <td>Audio descriptions should be provided for prerecorded video, but only where the existing audio does not convey the full meaning expressed by the video.</td> + <td></td> + </tr> + <tr> + <td>1.2.6 Provide sign language equivalent to prerecorded audio (AAA)</td> + <td>An equivalent sign language video should be provided for any prerecorded content containing audio.</td> + <td></td> + </tr> + <tr> + <td>1.2.7 Provide extended video with audio descriptions (AAA)</td> + <td>Where audio descriptions cannot be provided (see 1.2.5) due to video timing issues (e.g., there are no suitable pauses in the content in which to insert the audio descriptions), an alternative version of the video should be provided that includes inserted pauses (and audio descriptions).</td> + <td></td> + </tr> + <tr> + <td>1.2.8 Provide an alternative for prerecorded media (AAA)</td> + <td>For all content that features video, a descriptive text transcript should be provided, for example a script of the movie you are watching. This is for the benefit of hearing-impaired viewers who cannot hear the content.</td> + <td>See&nbsp;<a href="/en-US/docs/Learn_web_development/Core/Accessibility/Multimedia#audio_transcripts">Audio transcripts</a> for transcript information.</td> + </tr> + <tr> + <td>1.2.9 Provide a transcript for live audio (AAA)</td> + <td>For any live audio content being broadcast, a descriptive text should be provided, for example a script of the play or musical you are listening to. This is for the benefit of hearing-impaired viewers who cannot hear the content.</td> + <td>See&nbsp;<a href="/en-US/docs/Learn_web_development/Core/Accessibility/Multimedia#audio_transcripts">Audio transcripts</a> for transcript information.</td> + </tr> + </tbody> +</table> + +> [!NOTE] +> Also see the [WCAG description for Guideline 1.2: Time-based Media: Provide alternatives for time-based media](https://www.w3.org/TR/WCAG21/#time-based-media). + +## Guideline 1.3 — Create content that can be presented in different ways + +This guideline refers to the ability of content to be consumed by users in multiple ways, accommodating their differing needs. + +<table class="standard-table"> + <tbody> + <tr> + <th scope="col">Success criteria</th> + <th scope="col">How to conform to the criteria</th> + <th scope="col">Practical resource</th> + </tr> + <tr> + <td>1.3.1 Info and relationships (A)</td> + <td> + <p> + Any content structure—or visual relationship made between content—can + also be determined programmatically, or be inferred from text + description. The main situations in which this is relevant are: + </p> + <ul> + <li> + Text labels and the form elements they describe. These are + associated unambiguously using the {{htmlelement("label")}} + element, which can be picked up by screen readers, etc. + </li> + <li> + Image alt text. Content images should have text available that + clearly describes the image's contents, which can be + programmatically associated with it (e.g., alt text), + or otherwise is easy to associate (e.g., describes it and is sat + right next to it). This should mean that the full meaning can still + be inferred even if you can't see the image. + </li> + <li> + Lists. If the order of list items is important, use an ordered list + ({{htmlelement("ol")}}). + </li> + </ul> + </td> + <td> + The whole of + <p> + <a href="/en-US/docs/Learn_web_development/Core/Accessibility/HTML" + >HTML: A good basis for accessibility</a + > + is packed with information about this, but you should particularly + refer to + <a href="/en-US/docs/Learn_web_development/Core/Accessibility/HTML#good_semantics" + >Good semantics</a + >, + <a href="/en-US/docs/Learn_web_development/Core/Accessibility/HTML#use_semantic_ui_controls_where_possible" + >Use semantic UI controls where possible</a + >, and + <a href="/en-US/docs/Learn_web_development/Core/Accessibility/HTML#text_alternatives" + >Text alternatives</a + >. + </p> + </td> + </tr> + <tr> + <td>1.3.2 Meaningful content sequence (A)</td> + <td> + A sensible, logical reading order should be easy to determine for any + content, even if it is visually presented in an unusual way. The order + should be made obvious by use of correct semantic elements (e.g., + headings, paragraphs), with CSS being used to create any unusual layout + styles, irrespective of the markup. + </td> + <td> + Again, refer to + <a href="/en-US/docs/Learn_web_development/Core/Accessibility/HTML" + >HTML: A good basis for accessibility</a + >. + </td> + </tr> + <tr> + <td>1.3.3 Sensory characteristics (A)</td> + <td> + <p> + Instructions for operating controls or understanding content do not + rely on a single sense. This may prove inaccessible to people with a + disability related to that sense, or a device that does not support + that sense. So, for example: + </p> + <ul> + <li> + "Click the round button to continue"<br />The button should be + clearly labelled so that it is obvious that it is the button you + need to press. If there are multiple buttons, make sure they are all + clearly labelled to distinguish their function. + </li> + <li> + "Listen to the audio instructions for guidance"<br />This is + obviously problematic—audio will be inaccessible to those with + hearing impairments, whereas text can be read, but also spoken by a + screen reader if required. + </li> + <li> + "Swipe from the right-hand side of the screen to reveal the menu"<br />Some + users might not be able to swipe the screen, either due to + disability or because their device does not support touch. An + alternative should be provided, such as a keyboard shortcut or + button that can be activated by keyboard or other means. + </li> + </ul> + <div class="note notecard"> + <p> + <strong>Note:</strong> Conveying instructions solely by color is + related, but covered in a different guideline — 1.4.1. + </p> + </div> + </td> + <td></td> + </tr> + <tr> + <td> + 1.3.4 Orientation (AA) + <em + ><a href="https://www.w3.org/TR/WCAG21/#new-features-in-wcag-2-1" + >added in 2.1</a + ></em + > + </td> + <td> + Content does not restrict its view and operation to a single display + orientation, such as portrait or landscape, unless a specific display + orientation is essential. + </td> + <td> + <p> + <a href="https://www.w3.org/WAI/WCAG21/Understanding/orientation.html" + >Understanding Orientation</a + > + </p> + </td> + </tr> + <tr> + <td> + 1.3.5 Identify Input Purpose (AA) <em + ><a href="https://www.w3.org/TR/WCAG21/#new-features-in-wcag-2-1" + >added in 2.1</a + ></em + > + </td> + <td> + <p> + Follow the list of + <a href="https://www.w3.org/TR/WCAG21/#input-purposes" + >53 input fields</a + > + to programmatically identify the purpose of a field. + </p> + </td> + <td> + <a + href="https://www.w3.org/WAI/WCAG21/Understanding/identify-input-purpose.html" + >Understanding Identify Input Purpose</a + > + </td> + </tr> + <tr> + <td> + 1.3.6 Identify Purpose (AAA) <em + ><a href="https://www.w3.org/TR/WCAG21/#new-features-in-wcag-2-1" + >added in 2.1</a + ></em + > + </td> + <td> + In content implemented using markup languages, the purpose of user + interface components, icons, and regions can be programmatically + determined. + </td> + <td> + <a + href="https://www.w3.org/WAI/WCAG21/Understanding/identify-purpose.html" + >Understanding Identify Purpose</a + > + </td> + </tr> + </tbody> +</table> + +> [!NOTE] +> Also see the WCAG description for [Guideline 1.3: Adaptable: Create content that can be presented in different ways without losing information or structure.](https://www.w3.org/TR/WCAG21/#adaptable) + +## Guideline 1.4: Make it easier for users to see and hear content including separating foreground from background + +This guideline relates to making sure core content is easy to discern from backgrounds and other decoration. The classic example is color (both [color contrast](/en-US/docs/Web/Accessibility/Guides/Understanding_WCAG/Perceivable/Color_contrast) and [use of color](/en-US/docs/Web/Accessibility/Guides/Understanding_WCAG/Perceivable/Use_of_color) to convey instructions), but it applies in other situations too. + +<table class="standard-table"> + <thead> + <tr> + <th scope="col">Success criteria</th> + <th scope="col">How to conform to the criteria</th> + <th scope="col">Practical resource</th> + </tr> + <tr> + <td>1.4.1 Use of color (A)</td> + <td> + <p> + Color should not be solely relied upon to convey information. For + example, in forms, you should never mark required fields purely with a + color (like red). Instead (or as well as), something like an asterisk + with a label of "required" would be more appropriate. + </p> + </td> + <td> + See + <a href="/en-US/docs/Web/Accessibility/Guides/Understanding_WCAG/Perceivable/Use_of_color" + >Use of color</a + >, + <a + href="/en-US/docs/Learn_web_development/Core/Accessibility/CSS_and_JavaScript#color_and_color_contrast" + >Color and color contrast</a + >, + and + <a + href="/en-US/docs/Learn_web_development/Extensions/Forms/How_to_structure_a_web_form#multiple_labels" + >Multiple labels</a + >. + </td> + </tr> + <tr> + <td>1.4.2 Audio controls (A)</td> + <td> + For any audio that plays for longer than three seconds, provide + accessible controls to play and pause the audio/video, and mute/adjust + volume. + </td> + <td> + Use native <code>&lt;button&gt;</code>s to provide accessible keyboard + controls, as shown in + <a + href="/en-US/docs/Web/Media/Guides/Audio_and_video_delivery/Video_player_styling_basics" + >Video player styling basics</a + >. + </td> + </tr> + <tr> + <td>1.4.3 Minimum contrast (AA)</td> + <td> + <p> + The color contrast between background and foreground content should be + at a minimum level to ensure legibility: + </p> + <ul> + <li> + Text and its background should have a contrast ratio of at least + 4.5:1. + </li> + <li> + Heading (or just larger) text should have a ratio of at least 3:1. + Larger text is defined as at least 18pt, or 14pt bold. + </li> + </ul> + </td> + <td> + See + <a href="/en-US/docs/Web/Accessibility/Guides/Understanding_WCAG/Perceivable/Color_contrast" + >Color contrast</a + > and + <a + href="/en-US/docs/Learn_web_development/Core/Accessibility/CSS_and_JavaScript#color_and_color_contrast" + >Color and color contrast</a + >. + </td> + </tr> + <tr> + <td>1.4.4 Resize text (AA)</td> + <td> + The page should be readable and usable when the text size is doubled. + This means that designs should be responsive, so that when the text size + is increased, the content is still accessible. + </td> + <td></td> + </tr> + <tr> + <td>1.4.5 Images of text (AA)</td> + <td> + Images should NOT be used to present content where text would do the + job. For example, if an image is mostly textual, it could be represented + using text as well as images. + </td> + <td></td> + </tr> + <tr> + <td>1.4.6 Enhanced contrast (AAA)</td> + <td> + <p>This follows, and builds on, criterion 1.4.3.</p> + <ul> + <li> + Text and its background should have a contrast ratio of at least + 7:1. + </li> + <li> + Heading (or just larger) text should have a ratio of at least 4.5:1. + Larger text is defined as at least 18pt, or 14pt bold. + </li> + </ul> + </td> + <td> + See + <a + href="/en-US/docs/Learn_web_development/Core/Accessibility/CSS_and_JavaScript#color_and_color_contrast" + >Color and color contrast</a + >. + </td> + </tr> + <tr> + <td>1.4.7 Low or no background audio (AAA)</td> + <td> + Prerecorded audio recordings that primarily feature speech should have + minimal background noise, so the content can be easily understood. + </td> + <td></td> + </tr> + <tr> + <td>1.4.8 Visual presentation (AAA)</td> + <td> + <p>For text content presentation, the following should be true:</p> + <ul> + <li>Foreground and background colors should be user-selectable.</li> + <li> + Text blocks should be no wider than 80 characters (or glyphs), for + maximum readability. + </li> + <li> + Text should not be fully justified (e.g., <code + >text-align: justify;</code + >). + </li> + <li> + Line height should be at least 1.5 times the text size within + paragraphs (e.g., <code>line-height: 1.5;</code>), and at least 2.25 + times the text size between paragraphs (e.g., <code + >padding: 2.25rem;</code + >). + </li> + <li> + When the text size is doubled, the content should not need to be + scrolled. + </li> + </ul> + </td> + <td></td> + </tr> + <tr> + <td>1.4.9 Images of text (No Exception) (AAA)</td> + <td> + Text should not be presented as part of an image unless it is purely + decoration (i.e., it does not convey any content) or cannot be presented + in any other way. + </td> + <td></td> + </tr> + <tr> + <td> + 1.4.10 Reflow (AA) <em + ><a href="https://www.w3.org/TR/WCAG21/#new-features-in-wcag-2-1" + >added in 2.1</a + ></em + > + </td> + <td> + <ul> + <li> + No horizontal scrolling for left-to-right languages (like English) + or right-to-left languages (like Arabic) + </li> + <li> + No vertical scrolling for top-to-bottom languages (like Japanese) + </li> + <li> + Except for parts of the content which require two-dimensional layout + for usage or meaning (like a large data table) + </li> + </ul> + </td> + <td> + <a href="https://www.w3.org/WAI/WCAG21/Understanding/reflow.html" + >Understanding Reflow</a + > + </td> + </tr> + <tr> + <td> + 1.4.11 Non-Text Contrast(AA) <em + ><a href="https://www.w3.org/TR/WCAG21/#new-features-in-wcag-2-1" + >added in 2.1</a + ></em + > + </td> + <td> + Minimum color contrast ratio of 3:1 for user interface components and + graphical objects. + </td> + <td> + <a + href="https://www.w3.org/WAI/WCAG21/Understanding/non-text-contrast.html" + >Understanding Non-Text Contrast</a + > + </td> + </tr> + <tr> + <td> + 1.4.12 Text Spacing (AA) <em + ><a href="https://www.w3.org/TR/WCAG21/#new-features-in-wcag-2-1" + >added in 2.1</a + ></em + > + </td> + <td> + <p> + No loss of content or functionality occurs when the following styles + are applied: + </p> + <ul> + <li> + Line height (line spacing) to at least 1.5 times the font size + </li> + <li> + Spacing following paragraphs to at least 2 times the font size + </li> + <li> + Letter spacing (tracking) to at least 0.12 times the font size + </li> + <li>Word spacing to at least 0.16 times the font size</li> + </ul> + </td> + <td> + <a href="https://www.w3.org/WAI/WCAG21/Understanding/text-spacing.html" + >Understanding Text Spacing</a + > + </td> + </tr> + <tr> + <td> + 1.4.13 Content on Hover or Focus (AA) <em + ><a href="https://www.w3.org/TR/WCAG21/#new-features-in-wcag-2-1" + >added in 2.1</a + ></em + > + </td> + <td> + <p> + While additional content may appear and disappear in coordination with + hover and keyboard focus, this success criterion specifies three + conditions that must be met: + </p> + <ul> + <li>dismissible (can be closed/removed)</li> + <li> + hoverable (the additional content does not disappear when the + pointer is over it) + </li> + <li> + persistent (the additional content does not disappear without user + action) + </li> + </ul> + </td> + <td> + <a + href="https://www.w3.org/WAI/WCAG21/Understanding/content-on-hover-or-focus.html" + >Understanding Content on Hover or Focus</a + > + </td> + </tr> + </thead> +</table> + +> [!NOTE] +> Also see the WCAG description for [Guideline 1.4: Distinguishable: Make it easier for users to see and hear content including separating foreground from background.](https://www.w3.org/TR/WCAG21/#distinguishable) + +## See also + +- [WCAG](/en-US/docs/Web/Accessibility/Guides/Understanding_WCAG) + + 1. Perceivable + 2. [Operable](/en-US/docs/Web/Accessibility/Guides/Understanding_WCAG/Operable) + 3. [Understandable](/en-US/docs/Web/Accessibility/Guides/Understanding_WCAG/Understandable) + 4. [Robust](/en-US/docs/Web/Accessibility/Guides/Understanding_WCAG/Robust) diff --git a/files/en-us/web/accessibility/guides/understanding_wcag/perceivable/use_of_color/index.md b/files/en-us/web/accessibility/guides/understanding_wcag/perceivable/use_of_color/index.md new file mode 100644 index 000000000000000..1205e77b66aab54 --- /dev/null +++ b/files/en-us/web/accessibility/guides/understanding_wcag/perceivable/use_of_color/index.md @@ -0,0 +1,25 @@ +--- +title: Use of color +slug: Web/Accessibility/Guides/Understanding_WCAG/Perceivable/Use_of_color +page-type: guide +sidebar: accessibilitysidebar +--- + +While [color contrast](/en-US/docs/Web/Accessibility/Guides/Understanding_WCAG/Perceivable/Color_contrast) is often primarily an aesthetic choice, the _use of color_ on a website pertains to _using color to communicate information_. WCAG guideline 1.4.1 on the use of color requires that "color is not used as the only visual means of conveying information, indicating an action, prompting a response, or distinguishing a visual element." + +## Solution + +Use another factor in addition to color to convey information. For example, to indicate form validation errors, you can change the labels of the relevant fields by another font attribute as well as by color. Icons and symbols should differ by shape as well as by color. + +To accommodate users with color vision disorders ("color blindness"), be careful when using a "stoplight" color metaphor, with green indicating "good" values and red indicating "bad" values. Users with red-green color blindness have trouble distinguishing red and green, and so may not be able to tell these values apart. Using an additional factor to signal "good" vs. "bad" is necessary. Avoid pure red and green in this situation; a reddish-orange and a bluish-green are distinguishable by color blind users, while still conveying the cultural "good" and "bad" meanings to users with normal color vision. [Color contrast](/en-US/docs/Web/Accessibility/Guides/Understanding_WCAG/Perceivable/Color_contrast) can be helpful in this context, as well, if one color is darker or lighter than the other. + +## Related WCAG success criteria + +- [1.4.1 Use of color (A)](https://www.w3.org/TR/WCAG21/#use-of-color) + - : Color is not used as the only visual means of conveying information, indicating an action, prompting a response, or distinguishing a visual element. + +## See also + +- [Understanding Success Criterion 1.4.1: Use of Color](https://www.w3.org/WAI/WCAG21/Understanding/use-of-color.html) +- [Color contrast](/en-US/docs/Web/Accessibility/Guides/Understanding_WCAG/Perceivable/Color_contrast) +- [Color and color contrast](/en-US/docs/Learn_web_development/Core/Accessibility/CSS_and_JavaScript#color_and_color_contrast) in the Accessibility tutorials diff --git a/files/en-us/web/accessibility/guides/understanding_wcag/robust/index.md b/files/en-us/web/accessibility/guides/understanding_wcag/robust/index.md new file mode 100644 index 000000000000000..c6fc3941ceec51d --- /dev/null +++ b/files/en-us/web/accessibility/guides/understanding_wcag/robust/index.md @@ -0,0 +1,111 @@ +--- +title: Robust +slug: Web/Accessibility/Guides/Understanding_WCAG/Robust +page-type: guide +sidebar: accessibilitysidebar +--- + +This article provides practical advice on how to write your web content so that it conforms to the success criteria outlined in the **Robust** principle of the Web Content Accessibility Guidelines (WCAG) 2.0 and 2.1. Robust states that content must be robust enough that it can be interpreted reliably by a wide variety of user agents, including assistive technologies. This can generally be achieved by following web standards and [testing rigorously](/en-US/docs/Learn_web_development/Extensions/Testing). + +> [!NOTE] +> To read the W3C definitions for Robust and its guidelines and success criteria, see [Principle 4: Robust — Content must be robust enough that it can be interpreted reliably by a wide variety of user agents, including assistive technologies.](https://www.w3.org/TR/WCAG21/#robust) + +## Guideline 4.1 — Compatible: Maximize compatibility with current and future user agents, including assistive technologies + +This guideline focuses on making content as compatible as possible, not only with current user agents (e.g., browsers), but also with future ones too. + +<table class="standard-table"> + <thead> + <tr> + <th scope="col">Success criteria</th> + <th scope="col">How to conform to the criteria</th> + <th scope="col">Practical resource</th> + </tr> + </thead> + <tbody> + <tr> + <td>4.1.1 Parsing (A)</td> + <td> + <p> + Content should be well-formed so it can be parsed successfully by + browsers and other user agents such as screen readers. + </p> + <p> + To pass this criterion, make sure that your HTML is as valid as + possible. Use the + <a href="https://validator.w3.org/">W3C validator</a> to validate your + markup. + </p> + </td> + <td> + See + <a href="/en-US/docs/Learn_web_development/Core/Structuring_content/Debugging_HTML" + >Debugging HTML</a + > + for a practical guide. + </td> + </tr> + <tr> + <td>4.1.2 Name, Role, Value (A)</td> + <td> + <p> + The name and role of user interface components (e.g., form inputs, + buttons, links, etc.) should be programmatically determinable. + </p> + <p> + When using semantic elements correctly for their intended purpose, + this criterion should be passed automatically. When scripting custom + components, you will need to use WAI-ARIA roles and other features to + make sure your controls will be interpreted and are able to be used as + intended, e.g., not only by sighted mouse users, but also by + screen reader users, keyboard-only users, etc. + </p> + </td> + <td> + See + <a href="/en-US/docs/Learn_web_development/Core/Accessibility/HTML" + >HTML: A good basis for accessibility</a + > + and + <a href="/en-US/docs/Learn_web_development/Core/Accessibility/WAI-ARIA_basics" + >WAI-ARIA basics</a + >. + </td> + </tr> + <tr> + <td> + 4.1.3 Status Messages (AA) <em + ><a + href="https://www.w3.org/TR/WCAG21/#new-features-in-wcag-2-1" + rel="noopener" + >added in 2.1</a + ></em + > + </td> + <td> + <p> + Assistive technology users are made aware of new status messages added + to the page. + </p> + </td> + <td> + <a + href="https://www.w3.org/WAI/WCAG21/Understanding/status-messages.html" + >Understanding Status Messages</a + > + </td> + </tr> + </tbody> +</table> + +> [!NOTE] +> Also see the WCAG description for [Guideline 4.1: Compatible: Maximize compatibility with current and future user agents, including assistive technologies.](https://www.w3.org/TR/WCAG21/#compatible) + +## See also + +- [WCAG](/en-US/docs/Web/Accessibility/Guides/Understanding_WCAG) + + 1. [Perceivable](/en-US/docs/Web/Accessibility/Guides/Understanding_WCAG/Perceivable) + 2. [Operable](/en-US/docs/Web/Accessibility/Guides/Understanding_WCAG/Operable) + 3. [Understandable](/en-US/docs/Web/Accessibility/Guides/Understanding_WCAG/Understandable) + 4. Robust diff --git a/files/en-us/web/accessibility/guides/understanding_wcag/text_labels_and_names/index.md b/files/en-us/web/accessibility/guides/understanding_wcag/text_labels_and_names/index.md new file mode 100644 index 000000000000000..f4ed316290b62f8 --- /dev/null +++ b/files/en-us/web/accessibility/guides/understanding_wcag/text_labels_and_names/index.md @@ -0,0 +1,285 @@ +--- +title: Text labels and names +slug: Web/Accessibility/Guides/Understanding_WCAG/Text_labels_and_names +page-type: guide +sidebar: accessibilitysidebar +--- + +There are many situations in which a control, dialog, or other website feature should be given a descriptive name or label to allow users of assistive technologies to understand what its purpose is and how to operate it correctly. There are a number of different types of problems in this category, found in different contexts, and each has its own solution. The different problems and solutions are discussed in the sections below. + +## Use alt attribute to label area elements that have the href attribute + +In image maps, give each {{htmlelement("area")}} element an `alt` attribute containing a name that describes what resources the areas links to. Failure to do so makes an image map hard to use for users of assistive technology — they need alternative text to be able to understand the purpose of an image. + +### Examples + +The following example show an image map (taken from [H24: Providing text alternatives for the area elements of image maps](https://www.w3.org/TR/WCAG20-TECHS/H24.html)): + +```html +<img + src="welcome.gif" + usemap="#map1" + alt="Areas in the library. Select an area for +more information on that area." /> +<map id="map1" name="map1"> + <area shape="rect" coords="0,0,30,30" href="reference.html" alt="Reference" /> + <area + shape="rect" + coords="34,34,100,100" + href="media.html" + alt="Audio visual lab" /> +</map> +``` + +See the [`<area>` element reference page](/en-US/docs/Web/HTML/Reference/Elements/area) for a live interactive example. + +### See also + +- {{htmlelement("area")}} +- [H24: Providing text alternatives for the area elements of image maps](https://www.w3.org/TR/WCAG20-TECHS/H24.html) + +## Dialogs should be labeled + +For any container whose contents act as a dialog box (for example, a modal dialog asking the user to make a choice or respond to an action being taken), give it a descriptive label or name, so that assistive technology users can easily discover what its purpose is. + +A dialog box is generally denoted by an ARIA [`role="dialog"`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/dialog_role) or [`role="alertdialog"`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/alertdialog_role); you can use the [`aria-label`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-label) or [`aria-labelledby`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-labelledby) attributes to provide a label. + +### Examples + +The following example shows a dialog box, defined as such using `role="dialog"` and labelled using `aria-labelledby`. + +```html +<div + role="dialog" + aria-labelledby="dialog1Title" + aria-describedby="dialog1Desc"> + <h2 id="dialog1Title">Your personal details were successfully updated</h2> + <p id="dialog1Desc"> + You can change your details at any time in the user account section. + </p> + <button>Close</button> +</div> +``` + +If the dialog box doesn't have a heading, you can instead use `aria-label` to contain the label text: + +```html +<div role="dialog" aria-label="Personal details updated confirmation"> + <p> + Your personal details were successfully updated. You can change your details + at any time in the user account section. + </p> + <button>Close</button> +</div> +``` + +### See also + +- [`role="dialog"`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/dialog_role) +- [`role="alertdialog"`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/alertdialog_role) +- [`aria-label`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-label) +- [`aria-labelledby`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-labelledby) +- [WAI-ARIA: dialog role](https://www.w3.org/TR/wai-aria-1.2/#dialog) +- [Dialog authoring practices](https://www.w3.org/WAI/ARIA/apg/patterns/dialog-modal/) + +## Documents must have a title + +It is important in each HTML document to include a {{htmlelement("title")}} that describes the page's purpose. A common navigation technique for users of assistive technology is to infer what content a page contains by reading its title. If the title is not available, they have to navigate the page to determine its content, which can be a time consuming and potentially confusing process. + +### Examples + +The title for the reference article about the {{htmlelement("title")}} element is as follows: + +```html +<title> + &lt;title&gt;: The Document Title element - HTML: Hypertext Markup Language | + MDN +</title> +``` + +Another example might look like so: + +```html +<title>Fill in your details to register — myGov services</title> +``` + +To help the user, you can update the page title value to reflect significant page state changes (such as form validation problems): + +```html +<title>2 errors — Fill in your details to register — myGov services</title> +``` + +### See also + +- {{htmlelement("title")}} + +## Embedded content must be labeled + +Make sure that elements that embed content have a [title](/en-US/docs/Web/HTML/Reference/Global_attributes/title) attribute that describes the embedded content. This includes the {{htmlelement("embed")}} and {{htmlelement("object")}} elements. These elements are often used for graphical content, much like the {{HTMLelement("img")}} element. A descriptive title helps users of assistive technology understand what the element is showing. + +## Figures with optional captions should be labeled + +For best accessibility, include a {{HTMLElement("figcaption")}} within a {{HTMLElement("figure")}} element, even though doing so is technically optional. The caption is in addition to any alternative text on images within the figure. The caption describes the purpose of the figure in the document, which may be different from a description of a visual item, as provided by the alternative text. + +### Example + +The following example shows code for a figure with a caption. The `alt` attribute of the {{htmlelement("img")}} describes the appearance of the image; the {{htmlelement("figcaption")}} describes it from a functional perspective (in this case, the Latin name of the flower in the image). + +```html +<figure> + <img + src="milkweed.jpg" + alt="Black and white close-up photo of milkweed flowers" /> + <figcaption>Asclepias verticillata</figcaption> +</figure> +``` + +## Fieldset elements must be labeled + +Fieldset elements must have a text description, similar to other form elements. Use the {{htmlelement("legend")}} element to describe the purpose of a fieldset. + +## Use a legend to label a fieldset + +When grouping a set of form elements together with a {{htmlelement("fieldset")}} element, you should include a nested {{htmlelement("legend")}} element inside it, containing a clear description of the group. + +Users of assistive technology find this description helpful when trying to work out the overall purpose of the group. Without the legend, they would have to navigate around the individual form controls in the group to infer an idea of the overall purpose, which could result in confusion. + +### Examples + +```html +<form> + <fieldset> + <legend>Choose your favorite monster</legend> + + <input type="radio" id="kraken" name="monster" value="K" /> + <label for="kraken">Kraken</label><br /> + + <input type="radio" id="sasquatch" name="monster" value="S" /> + <label for="sasquatch">Sasquatch</label><br /> + + <input type="radio" id="mothman" name="monster" value="M" /> + <label for="mothman">Mothman</label> + </fieldset> +</form> +``` + +You can see a live, interactive version of this example on the [`<fieldset>` reference page](/en-US/docs/Web/HTML/Reference/Elements/fieldset). + +### See also + +- {{htmlelement("fieldset")}} +- {{htmlelement("legend")}} + +## Form elements must be labeled + +All elements within a form must have a {{htmlelement("label")}} that identifies its purpose. This applies to all types of {{htmlelement("input")}} items, as well as {{htmlelement("button")}}, {{htmlelement("output")}}, {{htmlelement("select")}}, {{htmlelement("textarea")}}, {{htmlelement("progress")}} and {{htmlelement("meter")}} elements, as well as any element with the [`switch` ARIA role](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/switch_role). + +The form element can be placed inside the {{htmlelement("label")}}, in which case the association between the form element and the label is obvious from the structure. Or, you can create an association between a {{htmlelement("label")}} and a form element by specifying the form element's `id` value as the value of the label's `for` attribute. + +### Example + +```html +<label + >I agree to the terms and conditions. + <input type="checkbox" id="terms" name="terms" /> +</label> + +<input type="checkbox" id="email-opt-in" name="opt-in" /> +<label for="email-opt-in">Yes, please send me news about this product.</label> +``` + +## Form elements should have a visible text label + +In addition to having a {{htmlelement("label")}} for every form element, those labels should be visible, not hidden. Visible labels help _all_ users understand the purpose of a form element. Do not rely on placeholder text, because it disappears as soon as the user starts typing. + +## Frame elements must be labeled + +Frame elements, both {{htmlelement("iframe")}} and the older, obsolete {{htmlelement("frame")}}, must have a title to describe the contents of the frame. Use the `title` attribute to label a frame element. Without a title, users of assistive technologies have to navigate into the frame in order to understand what it contains, which can be difficult and confusing. + +The {{HTMLElement('frame')}} element is no longer part of the HTML specification. Support for it may be dropped by browsers in the future. In addition, it is difficult for screen readers to navigate pages with {{HTMLElement('frame')}} elements. For best accessibility and future maintenance, redesign any pages that use frames to use CSS to achieve a similar layout. + +As a best practice, also provide a {{htmlelement("title")}} for the document that is enclosed in the frame, with content identical to the frame's `title` attribute. (This assumes that the enclosed document is under your control; if not, try to match the frame's `title` attribute to the document's title.) Some screen readers replace the contents of the `title` attribute with the contents of the enclosed document's {{htmlelement("title")}}. It's safest and most accessible to provide the same title in both places. + +### Example + +```html +<iframe + title="MDN Web docs" + width="300" + height="200" + src="https://developer.mozilla.org"> +</iframe> +``` + +## Headings must be labeled + +Make sure that your headings have non-empty text content, and are not hidden, such as with CSS `display:none` or `aria-hidden=true`. Users of screen readers rely on headings to understand the structure and content of a document. + +Also, be sure you are using [heading elements](/en-US/docs/Web/HTML/Reference/Elements/Heading_Elements) only for actual section headings, and not as a shortcut way to make text stand out. Screen reader users typically "skim" a page's headings, much like sighted users; non-heading text that is marked-up with heading elements can cause confusion. + +## Headings should have visible text content + +Make sure that your headings have non-empty text content, and are not hidden, such as with CSS `display:none` or `aria-hidden=true`. Users of screen readers rely on headings to understand the structure and content of a document. Do not use heading elements to mark up images or other graphical content. + +## Use title attribute to describe `<iframe>` content + +Make sure that {{htmlelement("iframe")}} elements have a `title` attribute to describe the contents of the frame. Without a title, users of assistive technologies have to navigate into the frame in order to understand what it contains, which can be difficult and confusing. + +As a best practice, also provide a {{htmlelement("title")}} for the document that is enclosed in the frame, with content identical to the frame's `title` attribute. (This assumes that the enclosed document is under your control; if not, try to match the frame's `title` attribute to the document's title.) Some screen readers replace the contents of the `title` attribute with the contents of the enclosed document's {{htmlelement("title")}}. It's safest and most accessible to provide the same title in both places. + +## Content with images must be labeled + +Provide descriptive text for all contentful (that is, non-decorative) images and image-like elements. This includes SVG images, {{htmlelement("img")}}, {{htmlelement("canvas")}}, {{htmlelement("map")}}, and {{htmlelement("area")}} elements, as well as {{htmlelement("input")}} elements where `type=image` and {{htmlelement("object")}} elements where the `type` starts with `image/`. The typical way to do this is with the `alt` attribute. Be sure that the description conveys what is shown in the image. + +### Example + +```html +<img + src="milkweed.jgp" + alt="Black and white close-up photo of milkweed flowers" /> +``` + +## Interactive elements must be labeled + +If an element is intended for users to interact with it, it should have a label. Interactive elements include links ({{htmlelement("a")}}), form elements, buttons, and any element that has a handler for mouse or keyboard events. The way to label an element depends on its type: for form elements, use a {{htmlelement("label")}}; for links, buttons and clickable elements, the text content of the element typically provides the label. If no other option exists for labeling an element, use the [`aria-label`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-label) attribute. + +## Use label attribute on optgroup elements + +In an {{htmlelement("optgroup")}} element, use the `label` attribute to describe the group so that assistive technologies can access it for their users. + +### Example + +In this example, the `label` attribute on the {{HTMLElement('optgroup')}} elements gives a category name for the group of options. + +```html +<label for="dino-select">Choose a dinosaur:</label> +<select id="dino-select"> + <optgroup label="Theropods"> + <option>Tyrannosaurus</option> + <option>Velociraptor</option> + <option>Deinonychus</option> + </optgroup> + <optgroup label="Sauropods"> + <option>Diplodocus</option> + <option>Saltasaurus</option> + <option>Apatosaurus</option> + </optgroup> +</select> +``` + +## Toolbars must be labeled when there is more than one toolbar + +If you define more than one toolbar in a web application using the ARIA `toolbar` role, you must use the [`aria-label`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-label) attribute to label each one so that it can be described by assistive technology. It is a good practice to label a toolbar, even if there is only one per page. + +### See also + +- [W3C ARIA toolbar example](https://www.w3.org/WAI/ARIA/apg/patterns/toolbar/examples/toolbar/) + +## Related WCAG success criteria + +- [1.1.1 Non-text Content (A)](https://www.w3.org/TR/WCAG21/#non-text-content) + - : All non-text content that is presented to the user has a text alternative that serves the equivalent purpose, except for the situations listed in the above link. +- [2.4.4 Link Purpose (In Context) (A)](https://www.w3.org/TR/WCAG21/#link-purpose-in-context) + - : The purpose of each link can be determined from the link text alone or from the link text together with its programmatically determined link context, except where the purpose of the link would be ambiguous to users in general. +- [2.4.9 Link Purpose (Link Only) (AAA)](https://www.w3.org/TR/WCAG21/#link-purpose-link-only) + - : A mechanism is available to allow the purpose of each link to be identified from link text alone, except where the purpose of the link would be ambiguous to users in general. diff --git a/files/en-us/web/accessibility/guides/understanding_wcag/understandable/index.md b/files/en-us/web/accessibility/guides/understanding_wcag/understandable/index.md new file mode 100644 index 000000000000000..c85a97810667166 --- /dev/null +++ b/files/en-us/web/accessibility/guides/understanding_wcag/understandable/index.md @@ -0,0 +1,514 @@ +--- +title: Understandable +slug: Web/Accessibility/Guides/Understanding_WCAG/Understandable +page-type: guide +sidebar: accessibilitysidebar +--- + +This article provides practical advice on how to write your web content so that it conforms to the success criteria outlined in the **Understandable** principle of the Web Content Accessibility Guidelines (WCAG) 2.0 and 2.1. Understandable states that information and the operation of user interface must be understandable. + +> [!NOTE] +> To read the W3C definitions for Understandable and its guidelines and success criteria, see [Principle 3: Understandable — Information and the operation of user interface must be understandable](https://www.w3.org/TR/WCAG21/#understandable). + +## Guideline 3.1 — Readable: Make text content readable and understandable + +This guideline focuses on making text content as understandable as possible. + +<table class="standard-table"> + <thead> + <tr> + <th scope="col">Success criteria</th> + <th scope="col">How to conform to the criteria</th> + <th scope="col">Practical resource</th> + </tr> + </thead> + <tbody> + <tr> + <td>3.1.1 Language of Page (A)</td> + <td> + The default human language of each web page should be detectable via + code. This is essential for purposes like making sure the reader has + arrived at a page written in a language suitable for them. The simplest + way to achieve this is to set the <a href="/en-US/docs/Web/HTML/Reference/Global_attributes/lang">lang</a> + attribute on the page's {{htmlelement("html")}} element, giving + it a value equal to the language code that best represents the language + the page is written in. + </td> + <td> + See + <a + href="/en-US/docs/Learn_web_development/Core/Structuring_content/Webpage_metadata#setting_the_primary_language_of_the_document" + >Setting the primary language of the document</a + >. + </td> + </tr> + <tr> + <td>3.1.2 Language of Parts (AA)</td> + <td> + <p> + In cases where the content of a page includes words or phrases that + are in a different language to the primary language, use the + <a href="/en-US/docs/Web/HTML/Reference/Global_attributes/lang">lang</a> attribute on an element wrapped + around the term in question (e.g., a {{htmlelement("span")}} + if no semantic element is available) to set an appropriate language + for it. + </p> + <p> + You don't need to set a different language for words or phrases that + are the same regardless of language (for example proper names, + technical terms that aren't part of a specific language). + </p> + </td> + <td></td> + </tr> + <tr> + <td>3.1.3 Unusual Words (AAA)</td> + <td> + Where technical terms, jargon, or idioms/slang are used, definitions + should be provided for such phrases/words. Your site should provide a + glossary that contains definitions of such words/terms that you can then + link to when they appear, or at the very least provide definitions + somewhere in the surrounding text, or in a + <a + href="/en-US/docs/Learn_web_development/Core/Structuring_content/Lists#description_lists" + >description list</a + > + at the bottom of the page. + </td> + <td></td> + </tr> + <tr> + <td>3.1.4 Abbreviations (AAA)</td> + <td> + <p> + Where abbreviations are used, you should provide an expansion of them, + or a definition as required. + </p> + <p> + The {{htmlelement("abbr")}} element is often thought of as + the preferred way to provide an expansion for an abbreviation — it + takes a <a href="/en-US/docs/Web/HTML/Reference/Global_attributes/title">title</a> attribute that contains the + expansion, and this appears when the acronym is moused over. However, + the title contents are not accessible via keyboard, nor are they + reliably read out by screen readers. A better way to handle this is to + again provide links to glossary pages containing the acronym expansion + and explanation, or at the very least include them in the surrounding + text in context. + </p> + </td> + <td> + See + <a + href="/en-US/docs/Learn_web_development/Core/Structuring_content/Advanced_text_features#abbreviations" + >Abbreviations</a + >. + </td> + </tr> + <tr> + <td>3.1.5 Reading Level (AAA)</td> + <td> + <p> + If text is provided that requires a higher reading level that lower + secondary education level (typically children around 11-14 years old), + provide supplementary explainer material to help people who can't read + it, or provide an alternative version that is written at lower + secondary level. + </p> + <p> + This doesn't mean that all subject matter should be understood by + everyone, but that the style of writing should be accessible by + everyone. It is better to just write all content at lower secondary + level, even technical documentation like programming tutorials, unless + there is a good reason not to (e.g., an alternative style for poetic + effect), or they have to be written in a strict style (e.g., W3C + specs). + </p> + </td> + <td></td> + </tr> + <tr> + <td>3.1.6 Pronunciation (AAA)</td> + <td> + <p> + A mechanism should be provided to give users access to pronunciation + of words where they are is needed to understand the content fully. + </p> + <p> + The HTML {{htmlelement("audio")}} element can be used to + create a control that allows the reader to play back an audio file + containing the correct pronunciation, and it also makes sense to + include a textual pronunciation guide after difficult words, in the + same way that you find in dictionary entries. + </p> + </td> + <td> + See + <a + href="/en-US/docs/Learn_web_development/Core/Structuring_content/HTML_video_and_audio" + >Video and audio content</a + >, and + <a + href="https://www.oxfordlearnersdictionaries.com/us/about/pronunciation_english.html" + >Pronunciation Guide for English Dictionary</a + > + </td> + </tr> + </tbody> +</table> + +> [!NOTE] +> Also see the WCAG description for [Guideline 3.1 Readable: Make text content readable and understandable](https://www.w3.org/TR/WCAG21/#readable). + +## Guideline 3.2 — Predictable: Make Web pages appear and operate in predictable ways + +This guideline focuses on making user interfaces intuitive and understandable. + +<table class="standard-table"> + <thead> + <tr> + <th scope="col">Success criteria</th> + <th scope="col">How to conform to the criteria</th> + <th scope="col">Practical resource</th> + </tr> + </thead> + <tbody> + <tr> + <td>3.2.1 On Focus (A)</td> + <td> + <p> + When a control or other page feature receives focus, it should not + change the context in a way that may confuse or disorientate the user. + </p> + <p> + This is a matter of sensible design — people don't want interfaces to + surprise them; they want things to be intuitive and behave as + expected. For example, focusing a navigation menu option should not + change the displayed page — it should be activated before the display + changes. + </p> + </td> + <td> + <code>Element</code>'s {{domxref("Element.focus_event", "focus")}} event contains some + useful information. Also see + <a + href="/en-US/docs/Learn_web_development/Core/Accessibility/HTML#building_keyboard_accessibility_back_in" + >Building keyboard accessibility back in</a + > + for some useful implementation ideas. + </td> + </tr> + <tr> + <td>3.2.2 On Input (A)</td> + <td> + <p> + When data is inputted into a control, or a setting is changed, context + should not be changed unexpectedly. The user should be warned/advised + of the impending change before it occurs. + </p> + <p> + Again, sensible design should be implemented. For example, if pressing + a button causes the application to exit the current view, the user + should be asked to confirm this action, save their work if + appropriate, etc. + </p> + </td> + <td> + The {{domxref("Element/input_event", "input")}} event is useful here. + </td> + </tr> + <tr> + <td>3.2.3 Consistent Navigation (AA)</td> + <td> + <p> + Navigation menu/control style and positioning should be consistent + between different pages or views of a web page, and the existing items + should appear in the same order, even if for example new items are + added. If the user has initiated a change, e.g., choosing a different + color scheme or position for the navigation, their choice should be + respected across all pages. + </p> + <p> + Again, sensible design — make the navigation controls the same across + all pages or views. + </p> + </td> + <td> + See + <a href="/en-US/docs/Learn_web_development/Core/Accessibility/HTML#structure_page_sections_logically" + >Structure page sections logically</a + > + for information on modern markup for layouts. See also + <a + href="/en-US/docs/Learn_web_development/Core/Text_styling/Styling_links#styling_links_as_buttons" + >Styling links as buttons</a + > + for a useful accessible navigation menu example. + </td> + </tr> + <tr> + <td>3.2.4 Consistent Identification (AA)</td> + <td> + <p> + Controls or components that have the same functionality should be + identified in the same way across different pages or views. A currency + converter appearing on every page of a world travel site for example + should be exactly the same, semantically and in terms of labels. + </p> + <p>Again, sensible design!</p> + </td> + <td> + "Labels" can refer to descriptive information in text content, or HTML + form labels. See + <a href="/en-US/docs/Learn_web_development/Core/Accessibility/HTML#use_meaningful_text_labels" + >Use meaningful text labels</a + > + for more information. + </td> + </tr> + <tr> + <td>3.2.5 Change on Request (AAA)</td> + <td> + <p> + Changes in context that could possibly confuse or disorient users + should only occur only when requested by the user, OR the user should + be able to turn them off. + </p> + <p> + If you need to have something that significantly changes the current + view (e.g., content or controls), let the user control when they want + that change to occur (e.g., what page to show, when to advance to the + next photo in the gallery...) + </p> + <p> + If you need to have something like a carousel on a page, provide an + option to stop it automatically advancing. Better to avoid such + functionality if possible. + </p> + </td> + </tr> + <tr> + <td> 3.2.6 Consistent help (A)</td> + <td> <p> Web pages that contain help mechanisms, including self-help options and human contact details, that are repeated on multiple web pages, need to place those mechanisms in the same order on all pages, unless a change is initiated by the user.</p> + <td> <p> Check out the <a href="https://www.w3.org/WAI/WCAG22/Understanding/consistent-help">consistent help documentation</a> for this standard to learn more. </p> + </td> + </td> + <tr> + </tr> + </tbody> +</table> + +> [!NOTE] +> Also see the WCAG description for [Guideline 3.2 Predictable: Make Web pages appear and operate in predictable ways](https://www.w3.org/TR/WCAG21/#predictable). + +## Guideline 3.3 — Input Assistance: Help users avoid and correct mistakes + +This guideline centers around helping users enter correct information when required with the minimum of mistakes. + +<table class="standard-table"> + <thead> + <tr> + <th scope="col">Success criteria</th> + <th scope="col">How to conform to the criteria</th> + <th scope="col">Practical resource</th> + </tr> + </thead> + <tbody> + <tr> + <td>3.3.1 Error Identification (A)</td> + <td> + <p> + When a user is filling out a form or choosing between options, any + error that is detected should be clearly reported to the user, along + with the form control that the error relates to. + </p> + <p> + It is advisable to implement client-side error detection and handling, + via HTML form validation features, and/or JavaScript, whatever is + best for your situation. When an error is detected, an intuitive error + message should be shown next to the form input that is at fault to + help the user correct their inputs. For screen reader users, you can + use aria live regions to alert the user to a change on the page. + </p> + <div class="note notecard"> + <p> + <strong>Note:</strong> Server-side validation should <em>always</em> be + used alongside client-side validation. Client-side validation is too + easy to turn off or otherwise get around, so it can't be relied on + alone. + </p> + </div> + </td> + <td> + See + <a href="/en-US/docs/Learn_web_development/Extensions/Forms/Form_validation" + >Form data validation</a + > + for comprehensive validation information, and + <a + href="/en-US/docs/Learn_web_development/Core/Accessibility/WAI-ARIA_basics#dynamic_content_updates" + >WAI-ARIA: Dynamic content updates</a + > + for information on live regions. + </td> + </tr> + <tr> + <td>3.3.2 Labels or Instructions (A)</td> + <td> + <p> + Clear instructions should be provided when data input is required. + When a short instruction or prompt is required, you can use + {{htmlelement("label")}} elements for single inputs like name + or age, a combination or {{htmlelement("label")}}s and + {{htmlelement("fieldset")}}s/{{htmlelement("legend")}}s + for multiple inputs that go together (like the elements of a date of + birth or postal address). + </p> + <p> + When more complex explanation is required, you can always include + explanatory paragraphs too, or maybe you need to try to make your + forms more intuitive. + </p> + </td> + <td> + <ul> + <li> + <a + href="/en-US/docs/Learn_web_development/Core/Accessibility/HTML#use_meaningful_text_labels" + >Use meaningful text labels</a + > + </li> + <li> + <a href="/en-US/docs/Learn_web_development/Extensions/Forms/How_to_structure_a_web_form" + >How to structure an HTML form</a + > + </li> + <li> + <a + href="/en-US/docs/Web/Accessibility/Guides/Understanding_WCAG/Text_labels_and_names" + >Text labels and names</a + > + </li> + </ul> + </td> + </tr> + <tr> + <td>3.3.3 Error Suggestion (AA)</td> + <td> + <p> + When an error is detected and suggestions for correction are known, + provide these to the user (e.g., suggesting alternatives when the user + is choosing a user name and has selected one that is already taken), + unless doing so would cause a security issue (e.g., when entering a + password) or context problem (e.g., they are trying to answer a + question in a quiz app). + </p> + <p> + In such cases, when this is appropriate, you'll probably use a + combination of JavaScript and server-side functionality to check if + the entry is correct, and if not, what viable suggestions can be given + to the user. Such suggestions should be displayed usefully in context, + just like error messages (see 3.3.1). + </p> + </td> + <td>No tutorial suggestions yet.</td> + </tr> + <tr> + <td>3.3.4 Error Prevention (Legal, Financial, Data) (AA)</td> + <td> + <p> + In the case of forms involved with entry of sensitive data (such as + legal agreements, e-commerce transactions, or personal data), at least + one of the following should be true: + </p> + <ul> + <li>Submissions are reversible.</li> + <li> + Data is checked for errors, and the user is given an opportunity to + correct them. + </li> + <li> + A mechanism is available for confirming and correcting information + before final submission. + </li> + </ul> + </td> + <td> + <p> + <strong>Reversible</strong> — for any view where data can be entered, + provide an equivalent view that allows you to edit or even delete an + entry, as appropriate (for example, see + <a href="/en-US/docs/Learn_web_development/Extensions/Server-side/Django">Django web framework</a + >). + </p> + <p> + <strong>Checking data</strong> — as covered in 3.3.1, a combination of + client-side and server-side validation should be used to detect errors + and display helpful messages to the user to allow them to correct + their inputs. + </p> + <p> + <strong>Confirm and correct</strong> — where appropriate, after + filling in a series of form fields to perform a task (such as buying a + product), the user should be shown a confirmation screen where they + can review their inputs and correct anything that doesn't look right. + This pattern is commonly used on e-commerce sites like Amazon. + </p> + </td> + </tr> + <tr> + <td>3.3.5 Context-sensitive help is available (AAA)</td> + <td> + Provide instructions and other appropriate cues in context to aid form + completion and submission. + </td> + <td> + This really just builds on 3.3.1 and other similar criteria but requires + more thorough contextual help information and services, e.g., providing a + dedicated link to a help page or service on each page, providing + examples showing what successful completion should look like. + </td> + </tr> + <tr> + <td>3.3.6 Error Prevention (All) (AAA)</td> + <td> + This principle builds on 3.3.4, extending its requirements to all user + input situations, not just ones involving sensitive data. + </td> + <td>Again, see 3.3.4.</td> + </tr> + <tr> + <td> 3.3.7 Redundant entry (A) </td> + <td> + Information that is required that was previously entered or provided by the user in the same process or user flow is either auto-populated or made selectable to the user from a list of options, unless re-entering the information is essential or required for security reasons, or if the information is no longer valid. + </td> + <td>Check out <a href="https://www.w3.org/WAI/WCAG22/Understanding/redundant-entry">Understanding redundant entry</a> to learn more.</td> + </tr> + <tr> + <td> 3.3.8 Accessible authentication (Minimum) (AA) + </td> + <td> +Cognitive function tests, like remembering a password, are not required for any step in an authentication process unless an alternative is provided, such as an object or personal content (e.g., images, videos, and audio) recognition, or a mechanism to assist (e.g., copy and paste and autosave passwords). + </td> + <td> Check out the <a href="https://www.w3.org/WAI/WCAG22/Understanding/accessible-authentication-minimum"> accessible authentication documentation</a> for this standard to learn more. </td> + </tr> + <tr> + <td> 3.3.9 Accessible Authentication (Enhanced) (AAA) </td> + <td> +A cognitive function test, like remembering a password, must not be required for any step in an authentication process without providing an alternative that does not rely on a cognitive function test or provides a mechanism to assist the user in completing the cognitive function test. Authentication tests that require the user to recognize objects or identify non-text content the user provided to the website are allowed. + </td> +<td> Check out the <a href="https://www.w3.org/WAI/WCAG22/Understanding/accessible-authentication-enhanced">enhanced accessible authentication documentation (AAA)</a> to learn more.</td> + </tr> + </tbody> +</table> + +> [!NOTE] +> Also see the WCAG description for [Guideline 3.3 Input Assistance: Help users avoid and correct mistakes](https://www.w3.org/TR/WCAG21/#input-assistance). + +## See also + +- [WCAG](/en-US/docs/Web/Accessibility/Guides/Understanding_WCAG) + + 1. [Perceivable](/en-US/docs/Web/Accessibility/Guides/Understanding_WCAG/Perceivable) + 2. [Operable](/en-US/docs/Web/Accessibility/Guides/Understanding_WCAG/Operable) + 3. Understandable + 4. [Robust](/en-US/docs/Web/Accessibility/Guides/Understanding_WCAG/Robust) diff --git a/files/en-us/web/accessibility/index.md b/files/en-us/web/accessibility/index.md index 777fbadb7729e50..4bfb41a472ba0fe 100644 --- a/files/en-us/web/accessibility/index.md +++ b/files/en-us/web/accessibility/index.md @@ -2,17 +2,51 @@ title: Accessibility slug: Web/Accessibility page-type: landing-page +sidebar: accessibilitysidebar --- -{{AccessibilitySidebar}} - **Accessibility** (often abbreviated to **A11y** — as in, "a", then 11 characters, and then "y") in web development means enabling as many people as possible to use websites, even when those people's abilities are limited in some way. For many people, technology makes things easier. For people with disabilities, technology makes things possible. Accessibility means developing content to be as accessible as possible, no matter an individual's physical and cognitive abilities and how they access the web. -"**The Web is fundamentally designed to work for all people**, whatever their hardware, software, language, location, or ability. When the Web meets this goal, it is accessible to people with a diverse range of hearing, movement, sight, and cognitive ability." ([W3C - Accessibility](https://www.w3.org/standards/webdesign/accessibility)) +> **The Web is fundamentally designed to work for all people**, whatever their hardware, software, language, location, or ability. +> When the Web meets this goal, it is accessible to people with a diverse range of hearing, movement, sight, and cognitive ability. \ +> – ([W3C - Accessibility](https://www.w3.org/standards/webdesign/accessibility)) + +## Accessibility guides + +The [Accessibility guides](/en-US/docs/Web/Accessibility/Guides) cover authoring principles, WCAG compliance, accessible widgets and navigation, mobile accessibility, and other key topics that will help you understand why accessibility is crucial for the web and how to improve it in your projects. + +- [Accessibility information for web authors](/en-US/docs/Web/Accessibility/Guides/Information_for_Web_authors) + - : This document lists guidelines and regulations, how-to's, and tools for checking and repairing accessibility problems with websites. +- [Personalization to help browse safely](/en-US/docs/Web/Accessibility/Guides/Browsing_safely) + - : This article discusses making web content accessible for those with vestibular disorders, and those who support them, by taking advantage of personalization and accessibility settings built into the operating systems. +- [Accessible web applications and widgets](/en-US/docs/Web/Accessibility/Guides/Accessible_web_applications_and_widgets) + - : Most JavaScript libraries offer a library of client-side widgets that mimic the behavior of familiar desktop interfaces. + While this results in a widget that looks like its desktop counterpart, there usually isn't enough semantic information in the markup to be usable by an assistive technology. + This document describes techniques to improve accessibility of such widgets. +- [Keyboard-navigable JavaScript widgets](/en-US/docs/Web/Accessibility/Guides/Keyboard-navigable_JavaScript_widgets) + - : Until now, web developers who wanted to make their styled `<div>` and `<span>` based widgets accessible have lacked proper techniques. + **Keyboard accessibility** is part of the minimum accessibility requirements, which a developer should be aware of. + This document describes techniques to make JavaScript widgets accessible with the keyboard. +- [Mobile accessibility checklist](/en-US/docs/Web/Accessibility/Guides/Mobile_accessibility_checklist) + - : This document provides a concise checklist of accessibility requirements for mobile app developers. +- [Understanding the Web Content Accessibility Guidelines (WCAG)](/en-US/docs/Web/Accessibility/Guides/Understanding_WCAG) + - : A set of articles that provide quick explanations to help you understand the steps that need to be taken to conform to the recommendations outlined in the Web Content Accessibility Guidelines (WCAG). +- [Cognitive accessibility](/en-US/docs/Web/Accessibility/Guides/Cognitive_accessibility) + - : Cognitive accessibility covers accessibility considerations for people with cognition and learning disabilities. + This document introduces cognitive accessibility and improving accessibility of the web for people with cognitive and learning differences. +- [Accessibility and spatial patterns](/en-US/docs/Web/Accessibility/Guides/Accessibility_and_Spatial_Patterns) + - : This document describes visual patterns that can induce physical symptoms in people who have photosensitive epilepsy, vestibular disorders, or other perceptual issues. +- [Web Accessibility: Understanding Colors and Luminance](/en-US/docs/Web/Accessibility/Guides/Colors_and_Luminance) + - : While understanding color, luminance, and saturation is important for design and readability for all sighted users, they are essential for those with reduced vision and color-deficient vision and those with specific neurological, cognitive, and other impairments. +- [Web accessibility for seizures and physical reactions](/en-US/docs/Web/Accessibility/Guides/Seizure_disorders) + - : Some types of visual web content can induce seizures in people with certain brain disorders. + This article helps you understand the types of content that can be problematic and find tools and strategies to help you avoid them. +- [ARIA](/en-US/docs/Web/Accessibility/ARIA) + - : This is a collection of articles to learn how to use Accessible Rich Internet Applications (ARIA) to make your HTML documents more accessible. -## Key tutorials +## Tutorials for beginners The MDN [Accessibility Learning Area](/en-US/docs/Learn_web_development/Core/Accessibility) contains modern, up-to-date tutorials covering the following accessibility essentials: @@ -29,24 +63,12 @@ The MDN [Accessibility Learning Area](/en-US/docs/Learn_web_development/Core/Acc - [Mobile accessibility](/en-US/docs/Learn_web_development/Core/Accessibility/Mobile) - : With web access on mobile devices being so popular and popular platforms such as iOS and Android having fully-fledged accessibility tools, it is important to consider the accessibility of your web content on these platforms. This article looks at mobile-specific accessibility considerations. -## Other documentation +## References -- [Understanding the Web Content Accessibility Guidelines](/en-US/docs/Web/Accessibility/Understanding_WCAG) - - : This set of articles provides quick explanations to help you understand the steps that need to be taken to conform to the recommendations outlined in the W3C Web Content Accessibility Guidelines 2.0 (WCAG 2.0 or just WCAG, for the purposes of this writing). -- [Introduction to color and accessibility](/en-US/docs/Web/Accessibility/Understanding_Colors_and_Luminance) - - : This article discusses our perception of light and color, provides a foundation for the use of color in accessible designs, and demonstrates best practices for visual and readable content. -- [Keyboard-navigable JavaScript widgets](/en-US/docs/Web/Accessibility/Keyboard-navigable_JavaScript_widgets) - - : Until now, web developers who wanted to make their styled `<div>` and `<span>` based widgets accessible have lacked proper techniques. **Keyboard accessibility** is part of the minimum accessibility requirements, which a developer should be aware of. -- [ARIA](/en-US/docs/Web/Accessibility/ARIA) - - : This is a collection of articles to learn how to use Accessible Rich Internet Applications (ARIA) to make your HTML documents more accessible. -- [Mobile accessibility checklist](/en-US/docs/Web/Accessibility/Mobile_accessibility_checklist) - - : This article provides a concise checklist of accessibility requirements for mobile app developers. -- [Cognitive accessibility](/en-US/docs/Web/Accessibility/Cognitive_accessibility) - - : This article explains how to ensure that the web content you're creating is accessible to people with cognitive impairments. -- [Accessibility for seizure disorders](/en-US/docs/Web/Accessibility/Seizure_disorders) - - : Some types of visual web content can induce seizures in people with certain brain disorders. This article helps you understand the types of content that can be problematic and find tools and strategies to help you avoid them. +- [ARIA reference](/en-US/docs/Web/Accessibility/ARIA/Reference) + - : Reference documentation for Accessible Rich Internet Applications (ARIA) attributes and roles. ## See also -- [WAI Interest Group](https://www.w3.org/WAI/about/groups/waiig/) - [Developer guides](/en-US/docs/MDN/Guides) +- [WAI Interest Group](https://www.w3.org/WAI/about/groups/waiig/) diff --git a/files/en-us/web/accessibility/information_for_web_authors/index.md b/files/en-us/web/accessibility/information_for_web_authors/index.md deleted file mode 100644 index 9ea764c98caa06a..000000000000000 --- a/files/en-us/web/accessibility/information_for_web_authors/index.md +++ /dev/null @@ -1,52 +0,0 @@ ---- -title: Accessibility information for web authors -slug: Web/Accessibility/Information_for_Web_authors -page-type: guide ---- - -{{AccessibilitySidebar}} - -## Guidelines and Regulations - -- [<abbr>ARIA</abbr> Authoring Practices Guide (<abbr>APG</abbr>)](https://www.w3.org/WAI/ARIA/apg/) - - - : Guide to accessibility semantics defined by the Accessible Rich Internet Application (<abbr>ARIA</abbr>) specification to create accessible web experiences. Describes how to apply accessibility semantics to common design patterns and widgets, providing design patterns and functional examples. - -- [Web Content Accessibility Guidelines (<abbr>WCAG</abbr>)](https://www.w3.org/WAI/standards-guidelines/wcag/) - - - : Another important set of guidelines from the W3C _Web Accessibility Initiative (<abbr>WAI</abbr>)_. The European Union is looking to base their upcoming accessibility regulations on these guidelines. These guidelines are discussed on the [<abbr>WAI</abbr> interest group discussion list](https://www.w3.org/WAI/about/groups/waiig/#mailinglist). - -- [ARIA on this site](/en-US/docs/Web/Accessibility/ARIA) - - : <abbr>MDN</abbr> guide to all the [ARIA roles](/en-US/docs/Web/Accessibility/ARIA/Roles) and [ARIA properties](/en-US/docs/Web/Accessibility/ARIA/Attributes), including best practices, related roles and properties, and examples. - -## How-to's - -- [Accessibility for teams](https://digital.gov/guides/accessibility-for-teams/) - - - : A brief guide from the U.S. General Services administration's Technology Transformation Services covering several accessibility topics with links to "how-to" videos and to related WCAG references. - -- [Accessible Web Page Authoring](https://www.ibm.com/able/requirements/requirements/) - - : IBM has made their accessibility requirements that need to be met public and interactive. - -## Automated Checking & Repair - -Use a tool to quickly check for common errors in your browser. - -- [HTML CodeSniffer](https://squizlabs.github.io/HTML_CodeSniffer/) -- [aXe](https://chromewebstore.google.com/detail/axe-devtools-web-accessib/lhdoppojpmngadmnindnejefpokejbdd?hl=en-US) -- [Lighthouse Accessibility Audit](https://developer.chrome.com/docs/lighthouse/overview/) -- [Accessibility Insights](https://accessibilityinsights.io/) -- [<abbr>WAVE</abbr>](https://wave.webaim.org/extension/) - -Tools to integrate into your build process, programmatically adding accessibility tests, so you can catch errors as you develop your web application: - -- [axe-core](https://github.com/dequelabs/axe-core) -- [jsx-a11y](https://github.com/jsx-eslint/eslint-plugin-jsx-a11y) -- [Lighthouse Audits](https://github.com/GoogleChrome/lighthouse/blob/main/docs/readme.md#using-programmatically) -- [AccessLint.js](https://github.com/accesslint/accesslint.js/tree/master) - -Continuous integration tools to find accessibility issues in your GitHub pull requests: - -- [AccessLint](https://accesslint.com/) - -While best to test your web applications with real users, you can simulate color blindness, low vision, low and contrast, and zooming. You should always test your site with out a mouse and touch to test keyboard navigation. You may also want to try your site using voice commands. Try disabling your mouse and using browser extensions like [Web Disability Simulator](https://chromewebstore.google.com/detail/web-disability-simulator/olioanlbgbpmdlgjnnampnnlohigkjla) diff --git a/files/en-us/web/accessibility/keyboard-navigable_javascript_widgets/index.md b/files/en-us/web/accessibility/keyboard-navigable_javascript_widgets/index.md deleted file mode 100644 index 489c5bbcdd6a981..000000000000000 --- a/files/en-us/web/accessibility/keyboard-navigable_javascript_widgets/index.md +++ /dev/null @@ -1,159 +0,0 @@ ---- -title: Keyboard-navigable JavaScript widgets -slug: Web/Accessibility/Keyboard-navigable_JavaScript_widgets -page-type: guide ---- - -{{AccessibilitySidebar}} - -Web applications often use JavaScript to mimic desktop widgets such as menus, tree views, rich text fields, and tab panels. These widgets are typically composed of {{ HTMLElement("div") }} and {{ HTMLElement("span") }} elements that do not, by nature, offer the same keyboard functionality that their desktop counterparts do. This document describes techniques to make JavaScript widgets accessible with the keyboard. - -## Using tabindex - -By default, when people use the tab key to browse a webpage, only interactive elements (like links, form controls) get focused. With the `tabindex` [global attribute](/en-US/docs/Web/HTML/Global_attributes), authors can make other elements focusable, too. When set to `0`, the element becomes focusable by keyboard and script. When set to `-1`, the element becomes focusable by script, but it does not become part of the keyboard focus order. - -The order in which elements gain focus when using a keyboard, is the source order by default. In exceptional circumstances, authors may want to redefine the order. To do this, authors can set `tabindex` to any positive number. - -> [!WARNING] -> Avoid using positive values for `tabindex`. Elements with a positive `tabindex` are put before the default interactive elements on the page, which means page authors will have to set (and maintain) `tabindex` values for all focusable elements on the page whenever they use one or more positive values for `tabindex`. - -The following table describes `tabindex` behavior in modern browsers: - -<table> - <thead> - <tr> - <th><code>tabindex</code> attribute</th> - <th>Focusable with mouse or JavaScript via <code>element.focus()</code></th> - <th>Tab navigable</th> - </tr> - </thead> - <tbody> - <tr> - <td>not present</td> - <td>Follows the platform convention of the element (yes for form controls, links, etc.).</td> - <td>Follows the platform convention of the element.</td> - </tr> - <tr> - <td>Negative (i.e. <code>tabindex="-1"</code>)</td> - <td>Yes</td> - <td>No; author must focus the element with <a href="/en-US/docs/Web/API/HTMLElement/focus"><code>focus()</code></a> in response to arrow or other key presses.</td> - </tr> - <tr> - <td>Zero (i.e. <code>tabindex="0"</code>)</td> - <td>Yes</td> - <td>In tab order relative to element's position in document (note that interactive elements like {{HTMLElement('a')}} have this behavior by default, they don't need the attribute).</td> - </tr> - <tr> - <td>Positive (e.g. <code>tabindex="33"</code>)</td> - <td>Yes</td> - <td><code>tabindex</code> value determines where this element is positioned in the tab order: smaller values will position elements earlier in the tab order than larger values (for example, <code>tabindex="7"</code> will be positioned before <code>tabindex="11"</code>).</td> - </tr> - </tbody> -</table> - -### Non-native controls - -Native HTML elements that are interactive, like {{ HTMLElement("a") }}, {{ HTMLElement("input") }} and {{ HTMLElement("select") }}, are already accessible by keyboards, so to use one of them is the fastest path to make components work with keyboards. - -Authors can also make a {{ HTMLElement("div") }} or {{ HTMLElement("span") }} keyboard accessible by adding a `tabindex` of `0`. This is particularly useful for components that use interactive elements that do not exist in HTML. - -### Grouping controls - -For grouping widgets such as menus, tablists, grids, or tree views, the parent element should be in the tab order (`tabindex="0"`), and each descendant choice/tab/cell/row should be removed from the tab order (`tabindex="-1"`). Users should be able to navigate the descendant elements using arrow keys. (For a full description of the keyboard support that is normally expected for typical widgets, see the [WAI-ARIA Authoring Practices](https://www.w3.org/WAI/ARIA/apg/).) - -The example below shows this technique used with a nested menu control. Once keyboard focus lands on the containing {{ HTMLElement("ul") }} element, the JavaScript developer must programmatically manage focus and respond to arrow keys. For techniques for managing focus within widgets, see "Managing focus inside groups" below. - -```html -<ul id="mb1" tabindex="0"> - <li id="mb1_menu1" tabindex="-1"> - Font - <ul id="fontMenu" title="Font" tabindex="-1"> - <li id="sans-serif" tabindex="-1">Sans-serif</li> - <li id="serif" tabindex="-1">Serif</li> - <li id="monospace" tabindex="-1">Monospace</li> - <li id="fantasy" tabindex="-1">Fantasy</li> - </ul> - </li> - <li id="mb1_menu2" tabindex="-1"> - Style - <ul id="styleMenu" title="Style" tabindex="-1"> - <li id="italic" tabindex="-1">Italics</li> - <li id="bold" tabindex="-1">Bold</li> - <li id="underline" tabindex="-1">Underlined</li> - </ul> - </li> - <li id="mb1_menu3" tabindex="-1"> - Justification - <ul id="justificationMenu" title="Justification" tabindex="-1"> - <li id="left" tabindex="-1">Left</li> - <li id="center" tabindex="-1">Centered</li> - <li id="right" tabindex="-1">Right</li> - <li id="justify" tabindex="-1">Justify</li> - </ul> - </li> -</ul> -``` - -#### Disabled controls - -When a custom control becomes disabled, remove it from the tab order by setting `tabindex="-1"`. Note that disabled items within a grouped widget (such as menu items in a menu) should remain navigable using arrow keys. - -## Managing focus inside groups - -When a user tabs away from a widget and returns, focus should return to the specific element that had focus, for example, the tree item or grid cell. There are two techniques for accomplishing this: - -1. Roving `tabindex`: programmatically moving focus -2. `aria-activedescendant`: managing a 'virtual' focus - -### Technique 1: Roving tabindex - -Setting the `tabindex` of the focused element to "0" ensures that if the user tabs away from the widget and then returns, the selected item within the group retains focus. Note that updating the `tabindex` to "0" requires also updating the previously selected item to `tabindex="-1"`. This technique involves programmatically moving focus in response to key events and updating the `tabindex` to reflect the currently focused item. To do this: - -Bind a key down handler to each element in the group, and when an arrow key is used to move to another element: - -1. programmatically apply focus to the new element, -2. update the `tabindex` of the focused element to "0", and -3. update the `tabindex` of the previously focused element to "-1". - -Here's an example of a [WAI-ARIA tree view](https://files.paciellogroup.com/training/WWW2012/samples/Samples/aria/tree/index.html) using this technique. - -### Technique 2: `aria-activedescendant` - -This technique involves binding a single event handler to the container widget and using the `aria-activedescendant` to track a "virtual" focus. (For more information about ARIA, see this [overview of accessible web applications and widgets](/en-US/docs/Web/Accessibility/An_overview_of_accessible_web_applications_and_widgets).) - -The `aria-activedescendant` property identifies the ID of the descendant element that currently has the virtual focus. The event handler on the container must respond to key and mouse events by updating the value of `aria-activedescendant` and ensuring that the current item is styled appropriately (for example, with a border or background color). - -## General guidelines - -### Usage of focus events - -- Do not dispatch the [`focus`](/en-US/docs/Web/API/Element/focus_event) event to send focus to an element. DOM focus events are considered informational only: they are generated by the system after something is focused, but not actually used to set focus. Use `element.focus()` instead. -- Do listen for the [`focus`](/en-US/docs/Web/API/Element/focus_event) and [`blur`](/en-US/docs/Web/API/Element/blur_event) events to track focus changes. Don't assume that all focus changes will come via key and mouse events: assistive technologies such as screen readers can set the focus to any focusable element. If you want to track the focus status for the whole document, you can use the [`document.activeElement`](/en-US/docs/Web/API/Document/activeElement) to get the active element, or [`document.hasFocus`](/en-US/docs/Web/API/Document/hasFocus) to make sure if the current document has focus. - -### Ensure that keyboard and mouse produce the same experience - -To ensure that the user experience is consistent regardless of input device, keyboard and mouse event handlers should share code where appropriate. For example, the code that updates the `tabindex` or the styling when users navigate using the arrow keys should also be used by mouse click handlers to produce the same changes. - -### Ensure that the keyboard can be used to activate element - -To ensure that the keyboard can be used to activate elements, any handlers bound to mouse events should also be bound to keyboard events. For example, to ensure that the Enter key will activate an element, if you have an `onclick="doSomething()"`, you should bind `doSomething()` to the key down event as well: `onkeydown="event.code === "Enter" && doSomething();"`. - -### Always draw the focus for tabindex="-1" items and elements that receive focus programmatically - -Ensure that focused elements have a focus ring. This can be done using the CSS {{cssxref("outline")}} property, which should not be unconditionally set to `none`—if you want to prevent unnecessary focus rings being displayed, use the {{cssxref(":focus-visible")}} pseudo-class. - -### Prevent used key events from performing browser functions - -If your widget handles a key event, prevent the browser from also handling it (for example, scrolling in response to the arrow keys) by using your event handler's return code. If your event handler returns `false`, the event will not be propagated beyond your handler. - -For example: - -```html -<span tabindex="-1" onkeydown="return handleKeyDown();">…</span> -``` - -If `handleKeyDown()` returns `false`, the event will be consumed, preventing the browser from performing any action based on the keystroke. - -### Don't rely on consistent behavior for key repeat, at this point - -Unfortunately `onkeydown` may or may not repeat depending on what browser and OS you're running on. diff --git a/files/en-us/web/accessibility/mobile_accessibility_checklist/index.md b/files/en-us/web/accessibility/mobile_accessibility_checklist/index.md deleted file mode 100644 index c6fa3c2d89b3f90..000000000000000 --- a/files/en-us/web/accessibility/mobile_accessibility_checklist/index.md +++ /dev/null @@ -1,81 +0,0 @@ ---- -title: Mobile accessibility checklist -slug: Web/Accessibility/Mobile_accessibility_checklist -page-type: guide ---- - -{{AccessibilitySidebar}} - -This document provides a concise checklist of accessibility requirements for mobile app developers. It is intended to continuously evolve as more patterns arise. - -## Color - -- Color contrast must comply with [WCAG 2.1 AA level requirements](https://www.w3.org/TR/WCAG/#contrast-minimum): - - - Contrast ratio of 4.5:1 for normal text (less than 18 point or 14 point bold.) - - Contrast ratio of 3:1 for large text (at least 18 point or 14 point bold.) - -- Information conveyed via color must be also available by other means too (underlined text for links, etc.) - -## Visibility - -- Content hiding techniques such as zero opacity, z-index order and off-screen placement must not be used exclusively to handle visibility. -- Everything other than the currently visible screen must be _truly_ invisible (especially relevant for single page apps with multiple _cards_): - - - Use the `hidden` attribute or `visibility` or `display` style properties. - - Unless absolutely unavoidable, `aria-hidden` attribute should not be used. - -## Focus - -- All activatable elements must be focusable: - - - Standard controls such as links, buttons, and form fields are focusable by default. - - Non-standard controls must have an appropriate [ARIA Role](/en-US/docs/Web/Accessibility/ARIA/Roles) assigned to them, such as `button`, `link`, or `checkbox`. - -- Focus should be handled in a logical order and consistent manner. - -## Text equivalents - -- Text equivalent must be provided for every non-strictly presentational non-text element within the app. - - - Use _alt_ and _title_ where appropriate (read Steve Faulkner's post about [Using the HTML title attribute](https://www.tpgi.com/using-the-html-title-attribute-updated/) for a good guide.) - - If the above attributes are not applicable, use appropriate [ARIA States and Properties](https://www.w3.org/TR/wai-aria-1.1/#state_prop_def) such as `aria-label`, `aria-labelledby`, or `aria-describedby`. - -- Images of text must be avoided. -- All user interface components with visible text (or image of text) as labels must have the same text available in the programmatic [name](https://www.w3.org/TR/WCAG21/#dfn-name) of the component. [WCAG 2.1: Label in name.](https://www.w3.org/WAI/WCAG21/Understanding/label-in-name.html) -- All form controls must have labels ({{ htmlelement("label") }} elements) for the benefit of screen reader users. - -## Handling state - -- Standard controls such as radio buttons and checkboxes are handled by the operating system. However, for other custom controls state changes must be provided via [ARIA States](https://www.w3.org/TR/wai-aria-1.1/#state_prop_def) such as `aria-checked`, `aria-disabled`, `aria-selected`, `aria-expanded`, and `aria-pressed`. - -## Orientation - -- Content should not be restricted to a single orientation, such as portrait or landscape, unless essential. [WCAG 2.1: Orientation](https://www.w3.org/WAI/WCAG21/Understanding/orientation.html) - - - Examples of when an orientation is essential is a piano application or a bank check. - -## General guidelines - -- An app title must be provided. -- Headings must not break hierarchical structure - - ```html - <h1>Top level heading</h1> - <h2>Secondary heading</h2> - <h2>Another secondary heading</h2> - <h3>Low level heading</h3> - ``` - -- [ARIA Landmark Roles](https://www.washington.edu/accesstech/websites/regions/) should be used to describe an app or document structure, such as `banner`, `complementary`, `contentinfo`, `main`, `navigation`, `search`. -- For touch events, ensure the following ([WCAG 2.1: Pointer Cancellation](https://www.w3.org/WAI/WCAG21/Understanding/pointer-cancellation.html)): - - - The down-event should not be used to execute any part of the function; - - Failing the above, _completion_ of the function should be on the up-event, and a mechanism is available to abort the action before its completion or to undo the action after its completion; - - Failing the above, the up-event should be able to undo any action that was triggered on a down event; - - All the above may be violated if it is essential to trigger the action on the down event, usually to simulate real-world experiences or to provide real-time feedback. For example, game controls, piano keyboards, or virtual keyboards. - -- Touch targets must be large enough for the user to interact with (see the [BBC Mobile Accessibility Guidelines](https://www.bbc.co.uk/accessibility/forproducts/guides/mobile/target-touch-size) for useful touch target size guidelines). - -> [!NOTE] -> The [original version of this document](https://yzen.github.io/firefoxos/2014/04/30/mobile-accessibility-checklist.html) was written by [Yura Zenevich](https://yzen.github.io/). diff --git a/files/en-us/web/accessibility/seizure_disorders/index.md b/files/en-us/web/accessibility/seizure_disorders/index.md deleted file mode 100644 index 594a7bc3463661a..000000000000000 --- a/files/en-us/web/accessibility/seizure_disorders/index.md +++ /dev/null @@ -1,642 +0,0 @@ ---- -title: Web accessibility for seizures and physical reactions -slug: Web/Accessibility/Seizure_disorders -page-type: guide ---- - -{{AccessibilitySidebar}} - -This article introduces concepts behind making web content accessible for those with vestibular disorders, and how to measure and prevent content leading to seizures and/or other physical reactions. - -## Overview - -### Seizures - -Seizures caused by light are known as photosensitive epilepsy. Content that flickers, flashes, or blinks can trigger photosensitive epilepsy. Web technologies that use video, animated GIFs, animated PNGs, animated SVGs, {{Glossary("Canvas")}}, and CSS or JavaScript animations can all produce content that may induce seizures or other incapacitating physical reactions. Certain visual patterns, especially stripes, can also cause physical reactions even though they are not animated. Photosensitive epilepsy is actually a kind of "reflex epilepsy"—seizures occurring in response to a trigger. In the case of photosensitive epilepsy, seizures are triggered specifically by flashing lights, but other types of reflex epilepsies may be triggered by the act of reading or by noises. Patterns and images can also trigger epilepsy. - -The fact that static images may cause seizures and other disorders is documented in articles such as ["Gamma Oscillations and photosensitive epilepsy"](https://linkinghub.elsevier.com/retrieve/pii/S0960982217304062), where it is noted "_Certain visual images, even in the absence of motion or flicker, can trigger seizures in patients with photosensitive epilepsy_". The Epilepsy Foundation, in its article, ["Shedding Light on Photosensitivity, One of Epilepsy's Most Complex Conditions"](https://www.epilepsy.com/stories/shedding-light-photosensitivity-one-epilepsys-most-complex-conditions-0) talks about static images and patterns: "_Static or moving patterns of discernible light and dark stripes have the same effect as flashing lights because of the alternation of dark and bright areas."_ The Epilepsy Foundation of America Working Group is able to "quantify" the problem a little: _"A pattern with the potential for provoking seizures contains clearly discernible stripes, numbering more than five light-dark pairs of stripes in any orientation_". In addition to stripes, checkered patterns have also been known to cause photosensitive seizures, according to [Cedars-Sinai](https://www.cedars-sinai.org/health-library/diseases-and-conditions/p/photosensitive-seizures.html). - -Although static images are possible as triggers, they are less consistent. The trigger that is well established and strong is flashing/strobe lights. Dr. Selim Benbadis of USF's Comprehensive Epilepsy Program notes, _"The only thing that is really documented is flashing lights, which can trigger seizures in patients with photosensitive epilepsy. Only a few types of epilepsies are photosensitive though, and the vast majority of epilepsies are not."_ In addition to seizures brought about by photosensitivity, listening to certain pieces of music can also trigger what are called musicogenic seizures, although these types of seizures seem to be much more rare. For a great introduction on the topic of musicogenic seizures, visit Epilepsy Ontario's web page on [Musicogenic Seizures](https://epilepsyontario.org/musicogenic-seizures/). - -Seizures and epilepsy are not the same. In its article ["A Revised Definition of Epilepsy"](https://www.epilepsy.com/stories/revised-definition-epilepsy), the Epilepsy Foundation notes that "_a seizure is an event and epilepsy is the disease involving recurrent unprovoked seizures_." According to the Epilepsy Foundation's page ["How Serious Are Seizures?"](https://www.epilepsy.com/what-is-epilepsy/understanding-seizures/how-serious-are-seizures), _"Sudden unexpected death in epilepsy (SUDEP) is likely the most common disease-related cause of death in with epilepsy. It is not frequent but it is a very real problem and people need to be aware of its risk"_. - -The point is, seizures most definitely can be and are fatal, and developers and designers are incredibly important for making the web a safer place for those with sensitivities to photosensitive or musicogenic triggers. - -Seizures can be fatal, but even the ones that are "only" debilitating can be of such severity that they render the user incapacitated. Other disorders, such as disorientation, nausea, vomiting, and more can also be so severe that the user is unable to function. The Epilepsy Foundation's article, ["Photosensitivity and Seizures"](https://www.epilepsy.com/what-is-epilepsy/seizure-triggers/photosensitivity), provides a list of triggers that may cause seizures in photosensitive people; here's an excerpt from that list: - -- Television screens or computer monitors due to the flicker or rolling images. -- Certain video games or TV broadcasts containing rapid flashes or alternating patterns of different colors. -- Intense strobe lights like visual fire alarms. -- Natural light, such as sunlight, especially when shimmering off water, flickering through trees or through the slats of Venetian blinds. -- Certain visual patterns, especially stripes of contrasting colors. - -That same article continues that many factors must combine to trigger the photosensitive reaction. Of note is that it includes the wavelength of light as a possible factor; wavelengths in the red part of the spectrum seem to be especially problematic. In the article, ["Understanding WCAG 2.0 Three Flashes or Below Threshold"](https://www.w3.org/TR/UNDERSTANDING-WCAG20/seizure-does-not-violate.html) notes generally that: _"Individuals who have photosensitive seizure disorders can have a seizure triggered by content that flashes at certain frequencies for more than a few flashes"_ and goes on to note, very specifically that: "_People are even more sensitive to red flashing than to other colors, so a special test is provided for saturated red flashing_". - -You don't even need an image or video to cause harm. A {{HTMLElement('div')}} element set to change color and luminosity at high frequency, easily done via JavaScript, can cause real harm. And, flickering can occur everywhere. For example, "spinners" commonly used to display while pages load can easily "flicker" while spinning. - -Additional concerns exist for individuals with motor-skill problems. For example, the page for Trace Research & Development Center's [Photosensitive Epilepsy Analysis Tool](https://trace.umd.edu/peat/) notes that _"Photosensitive seizures can be provoked by certain types of flashing in web or computer content, including mouse-overs that cause large areas of the screen to rapidly flash on and off repeatedly"_. - -### Other physical reactions - -Nausea, vertigo (or dizziness), and disorientation are very nonspecific symptoms associated with all kinds of diseases and not particularly suggestive of seizures (except maybe disorientation, which is seen in seizures). However, seizures are not the only adverse physical response possible from flashing, flickering, blinking, and other such stimuli. In 1997, a Japanese cartoon featured an animated "virus bomb". Some of the children watching the cartoon reacted by having seizures, others by suffering nausea, shaking, and vomiting blood. The reactions from the children were so severe, they had to be rushed to the emergency room. The physical disorders listed below are all possible consequences: each of these physical reactions may be so severe as to be incapacitating. - -- Seizures -- Vestibular Disorders -- Migraines -- Nausea -- Vomiting - -## Flashing, blinking, & flickering - -Although "flashing" and "blinking" are sometimes used interchangeably, they are not the same. According to the W3C, blinking is a distraction problem, whereas flashing refers to content that occurs more than 3 times per second, and which is sufficiently large and bright. [Section 508](https://www.section508.gov/content/guide-accessible-web-design-development/#flashing) prohibits flickering effects with a frequency greater than 3 Hz (flickers per second) and lower than 55 Hz. The Epilepsy Foundation's article ["Shedding Light on Photosensitivity, One of Epilepsy's Most Complex Conditions"](https://www.epilepsy.com/stories/shedding-light-photosensitivity-one-epilepsys-most-complex-conditions-0) notes that _"Generally, flashing lights between the frequencies of five to 30 flashes per second (Hertz) are most likely to trigger seizures. In order to be safe, the consensus recommends that photosensitive individuals should not be exposed to flashes greater than three per second."_ For some people, however, flashing/blinking can cause symptoms at less than 3 Hz. - -It's important to note that not all flashing and blinking is bad. NASA, in its document titled, ["Blinking, Flashing, and Temporal Response"](https://colorusage.arc.nasa.gov/flashing.php) notes that blinking and flashing can be powerful tools for drawing attention—as is necessary for warning buttons (this assumes that users can still see the screen while elements are flashing, which is not always true). For some users, blinking buttons also caution that they must be used sparingly, and with care. As it applies to web design, systems that alert company employees to danger by "hijacking" the screen to provide a flashing warning of emergency need to take into consideration the rate, size, and luminosity changes on the screen as these warnings are flashed. - -### Flashing and flickering—how is danger quantified? - -According to the article ["Photic- and pattern-induced seizures: expert consensus of the Epilepsy Foundation of America Working Group",](https://onlinelibrary.wiley.com/doi/epdf/10.1111/j.1528-1167.2005.31405.x) _"A flash is a potential hazard if it has luminance ≥20 cd/m<sup>2</sup>, occurs at a frequency of ≥3 Hz, and occupies a solid visual angle of ≥0.006 steradians (approximately 10% of the central visual field or 25% of screen area at typical viewing distances)."_ - -How far is a typical viewing distance? The recommendation considered for a typical viewing distance at the time of writing was "_the area can be taken as applying to an area >25% of the area of a television screen, assuming standard viewing distances of ≥2 m (∼9 feet)"_. Much has changed since that time, and we are now much closer to our screen. - -Certain colors, and/or combinations of colors, also matter. ["Certain Colors More Likely To Cause Epileptic Fits, Researchers Find"](https://www.sciencedaily.com/releases/2009/09/090925092858.htm) notes that _"…complexities underlying brain dynamics could be modulated by certain color combinations more than the others, for example, red-blue flickering stimulus causes larger cortical excitation than red-green or blue-green stimulus."_ - -### Flashing & flashing red - -[WCAG 2.3.1 general flash and red flash thresholds](https://www.w3.org/WAI/WCAG21/Understanding/three-flashes-or-below-threshold.html) are defined as follows: - -- A **general flash** is defined as a pair of opposing changes in [relative luminance](https://www.w3.org/TR/WCAG21/#dfn-relative-luminance) of 10% or more of the maximum relative luminance where the relative luminance of the darker image is below 0.80, and where "a pair of opposing changes" is an increase followed by a decrease, or a decrease followed by an increase; -- A **red flash** is defined as any pair of opposing transitions involving a saturated red. - -These standards are based on earlier research. In 2004, The Epilepsy Foundation of America convened a workshop developed a [consensus](https://pubmed.ncbi.nlm.nih.gov/16146438/) on photosensitive seizures, stating _"A flash is a potential hazard if it has luminance at least 20 cd/m<sup>2</sup>, occurs at a frequency of least 3 Hz, and occupies a solid visual angle of at least 0.006 steradians (about 10% of the central visual field or 25% of screen area at typical viewing distances)."_ The transition to or from a saturated red is important and constitutes a risk on its own: "_Irrespective of luminance, a transition to or from a saturated red is also considered a risk._" - -### Size and distance - -#### How big? It depends - -"Relative" size and distance both matter. According to [PEAT](https://trace.umd.edu/peat/), _"The combined area of flashes occurring concurrently occupies no more than a total of one quarter of any 341 x 256 pixel rectangle anywhere on the displayed screen area when the content is viewed at 1024 by 768 pixels."_ - -The point that the field of vision is an important consideration arises in the article addressing WCAG 2.3.1 continues: "_The 1024 x 768 screen is used as the reference screen resolution for the evaluation. The 341 x 256 pixel block represents a 10 degree viewport at a typical viewing distance. (The 10 degree field is taken from the original specifications and represents the central vision portion of the eye, where people are most susceptible to photo stimuli.)_" - -This pixel area ratio calculates for relative size, but distance also matters. - -Distance matters because it affects the total field of vision. When viewers wear ocular masks for gaming, the field of vision is likely enveloped in its entirety by the screen. [WebVR](https://webvr.info/) is an open specification that makes it possible to experience VR in your browser, which can be experienced on phone, computer or headset. The concern about flashing images in an ocular mask is a growing one, since the mask is so close to the eyes. - -[The Epilepsy Society (UK)](https://epilepsysociety.org.uk/), in their article, ["3d Films and Virtual Reality"](https://epilepsysociety.org.uk/3d-films-and-virtual-reality#.XQlC5ohKiUk), noted: _"With VR the images flash very quickly and generally this is too quickly to trigger a seizure in people with photosensitive epilepsy. However, the field of view is large and so more of the eye is stimulated. This means that more of the brain may be affected and this may trigger a photosensitive seizure."_ - -(Note that some users will not be able to see with blinking cursors, and may get migraines, motion sickness, and disorientation, although blinking cursors occupy a much smaller area of the screen.) - -### Patterns, and parallax - -Contrasting dark and light geometric patterns are a known culprit; stripes and checks are the best known examples. The Epilepsy Foundation of America Working Group lists how many light-dark pairs of stripes are likely to provoke seizures, and, in what conditions. If a pattern is unchanging and straight, eight lines is the maximum allowable, but if it undulates, no more than five lines. - -Parallax effects can cause disorientation. Use parallax effects with caution; if you must use them, ensure the user has a control to turn them off. - -"A pattern with the potential for provoking seizures contains clearly discernible stripes, numbering more than five light-dark pairs of stripes in any orientation. When the light-dark stripes of any pattern collectively subtend at the eye from the minimal-expected viewing distance a solid angle of >0.006 steradians, the luminance of the lightest stripe is >50 cd/m<sup>2</sup>, and the pattern is presented for ≥0.5 s, then the pattern should display no more than five light-dark pairs of stripes, if the stripes change direction, oscillate, flash, or reverse in contrast; if the pattern is unchanging or smoothly drifting in one direction, no more than eight stripes." - -Not all is known, and even with the metrics listed above, additional factors come into play. For example, going from a smaller area to a larger one increases the likelihood that the brain responds, as well as increasing contrast, and increasing spatial frequency from a low to middle. It's also known, although the reasoning is not understood behind it, that going from simple orientations (for example, stripes) to a multiple one (for example, the checkered pattern that emerges when laying one set of stripes on top of, but perpendicular to, the original set) affects the brain. - -### Colors - -Understanding color is important for accessibility. See [understanding colors and luminance](/en-US/docs/Web/Accessibility/Understanding_Colors_and_Luminance) as it relates to web accessibility and accessibility in general. - -How the color relates to its background—usually framed in terms of contrast—and how drastically the color changes frame to frame in animation is important. For more on this, see [Three Flashes or Below Threshold Understanding SC 2.3.1](https://www.w3.org/TR/UNDERSTANDING-WCAG20/seizure-does-not-violate.html). - -#### The Special Case of Red - -It has been demonstrated that [some colors are more likely to cause epileptic fits than others](https://www.sciencedaily.com/releases/2009/09/090925092858.htm). Human physiology and psychology are affected by the color red in general. Its power to influence behavior has even been noted in animals. - -- **Red Desaturation tests:** The human eye is so sensitively tuned to red that ophthalmologists set up a test using it. The Red desaturation test assesses the integrity of the optic nerve. For more information as to how an ophthalmologist uses this test, see [Red Desaturation](https://www.smartoptometry.app/red-desaturation/). -- **Red Environment:** Studies have shown that for those who suffer Traumatic Brain Injury, [cognitive function is reduced in a red environment](https://pubmed.ncbi.nlm.nih.gov/20649469/). - -[Saturated Red](/en-US/docs/Web/Accessibility/Understanding_Colors_and_Luminance) is a special, dangerous case, and there are special tests for it. In addition to a red environment affecting the cognitive function of those with Traumatic Brain Injury, color in the red spectrum wavelength seems to require special concern and special tests. Dr. Gregg Vanderheiden, when testing the Photosensitive Epilepsy Analysis Tool, noted that the seizure rates were much higher than expected. They found that we are much more sensitive to saturated red flashing. (See the video, [The Photosensitive Epilepsy Analysis Tool](https://www.pbs.org/video/university-place-the-photosensitive-epilepsy-analysis-tool-ep-429/).) - -#### Websafe does not mean seizure-safe - -Note that the color **#990000** is considered "**websafe**". That does _not_ mean it is "safe for not causing seizures", it only means that the color may be "safely" reproduced accurately by the technology used to generate color on screens. - -## Measuring to prevent harm - -Measuring the potential for harm is a good starting point. Factors considered within tests include color, luminosity, size, contrast, and in cases of animation, frequency. WCAG 2.1 provides guidance for evaluating content. - -In August, 2004, the Epilepsy Foundation of America convened a workshop to begin to develop an expert consensus on photosensitive seizures. The following, expert, and authoritative information is from: [Photic- and pattern-induced seizures: expert consensus of the Epilepsy Foundation of America Working Group.](https://pubmed.ncbi.nlm.nih.gov/16146438/) - -> A flash is a potential hazard if it has luminance ≥20 cd/m<sup>2</sup>, occurs at a frequency of ≥3 Hz, and occupies a solid visual angle of ≥0.006 steradians (approximately 10% of the central visual field or 25% of screen area at typical viewing distances). A transition to or from saturated red also is considered a risk. A pattern with the potential for provoking seizures contains clearly discernible stripes, numbering more than five light-dark pairs of stripes in any orientation. When the light-dark stripes of any pattern collectively subtend at the eye from the minimal-expected viewing distance a solid angle of >0.006 steradians, the luminance of the lightest stripe is >50 cd/m2, and the pattern is presented for ≥0.5 s, then the pattern should display no more than five light-dark pairs of stripes, if the stripes change direction, oscillate, flash, or reverse in contrast; if the pattern is unchanging or smoothly drifting in one direction, no more than eight stripes. These principles are easier to apply in the case of fixed media, for example, a prerecorded TV show, which can be analyzed frame-by-frame, as compared with interactive media. - -The "cd/m<sup>2</sup>" refers to candela per square meter. So for the web developer, how does this relate to measurements for color, luminance, and saturation? - -The candela is a SI unit (International System of units) of luminous intensity. It's a photometric term, and photometry deals with the measurement of visible light as perceived by human eyes. Wikipedia's article on ["Candela per square metre"](https://en.wikipedia.org/wiki/Candela_per_square_metre) puts it in terms of what we are familiar with as developers: on a display device, and in the RGB space. This is helpful, because there's a specific standard assumed to be used on monitors, printers, and the Internet, and it is the **sRGB** (standard Red Green Blue). - -> As a measure of light emitted per unit area, this unit is frequently used to specify the brightness of a display device. The [sRGB](https://en.wikipedia.org/wiki/SRGB) spec for monitors targets 80 cd/m<sup>2</sup>.[<sup>\[3\]</sup>](https://en.wikipedia.org/wiki/Candela_per_square_metre#cite_note-3) Typically, calibrated monitors should have a brightness of 120 cd/m<sup>2</sup>. Most consumer desktop [liquid crystal displays](https://en.wikipedia.org/wiki/Liquid_crystal_display) have luminances of 200 to 300 cd/m<sup>2</sup>.[<sup>\[4\]</sup>](https://en.wikipedia.org/wiki/Candela_per_square_metre#cite_note-4) [High-definition televisions](https://en.wikipedia.org/wiki/High-definition_television) range from 450 to about 1500 cd/m<sup>2</sup>. - -The takeaway is that the **sRGB** color space is a common touch point between research, assessment tools, and developers, since it is easily converted from the commonly used Hex code. - -### Human physiology and psychology as a consideration - -Many experts work to quantify and measure to the greatest extent possible the kinds of web content that can serve as triggers for seizures. That said, it can't be forgotten that color is as much about human perception in the brain as it is the measurement of light coming from a computer screen. - -In addition to the psychological variances, there are also physiological differences among us. There will be variances and nuances as to how a real human being perceives, and responds to, color and light. For example, Tom Jewett, Lecturer Emeritus of Computer Sciences at Cal State University Long Beach, notes the following concerning [lightness in the HSL color scale](https://colortutorial.design/hsb.html) _"…The distinction between levels of lightness is not actually linear as the HSL scale would imply; we are much more sensitive to changes in lighter values than to darker ones."_ - -It's important to understand that light and its measurements are linear, but human vision and human perception are not. Investigation and discussion is ongoing as to how to relate the machine measurement of light as it passes from a computer screen, through the distance to the human eye, filtered by human vision, and then manipulated through the human brain. - -Even age and sex can play a role. According to the Epilepsy Foundation's article, ["Shedding Light on Photosensitivity, One of Epilepsy's Most Complex Conditions"](https://www.epilepsy.com/stories/shedding-light-photosensitivity-one-epilepsys-most-complex-conditions-0), _"Children and adolescents are more prone than adults to have an abnormal response to light stimulation, and the first light-induced seizure almost always occurs before age 20"._ The article follows with this statistic: _"Girls (60 percent) are more often affected than boys (40 percent), although seizures are more frequent in boys because they are more likely to be playing video games. Video games often contain potentially provocative light stimulation"_. - -**User testing is very problematic**. Naturally, no one wants to subject a seizure-prone individual to user testing. It's dangerous. To that point, one of the most ethical thing that developers and designers can do is use tools that have been developed by experts in the field who have worked hand-in-hand with physicians to develop the tool. As of this writing, there are two commonly available tools that have been ethically and professionally developed by researchers and physicians for film/videos: **PEAT**, and the **Harding Test**. - -### Photosensitive Epilepsy Analysis Tool (PEAT) - -The [Trace Research and Development Center](https://trace.umd.edu/) has set a gold standard for a [Photosensitive Epilepsy Analysis Tool](https://trace.umd.edu/peat/), and they've made a point to make it **_free_** to download. PEAT can help authors determine whether animations or video in their content are likely to cause seizures. Please note the restriction on its use: **_Use of PEAT to assess material commercially produced for television broadcast, film, home entertainment, or gaming industries is prohibited. Use the Harding Test or other tools for commercial purposes._** - -To get a free copy of the University of Maryland's Photosensitive Epilepsy Analysis Tool, visit the [Trace Research & Development Center](https://trace.umd.edu/). - -![University of Maryland College of Information Studies Photosensitive Epilepsy Analysis Tool.](peatversion1pt6.png) - -### The Harding Test - -As use of the PEAT tool is prohibited for commercial use, television programmers can use the Harding Test at [HardingTest.com](https://hardingtest.com/). The Harding Test is another gold standard. Television programmers in various countries must pass this test before being able to broadcast, so the group at [HardingTest.com](https://hardingtest.com/) provides both analysis and certification of video content. - -![Harding Flash and Pattern Analyzer.](screen_shot_2019-06-20_at_11.16.17_am.png) - -## Accessibility Solutions for Developers - -All animations are potentially dangerous. As designers and developers our responsibility is to ensure we do no harm either intentionally or unintentionally. If we must include something that has the potential to cause harm, it is vital to prevent users from accidentally encountering the harmful content, and to provide ways for users to prevent and control animations mitigating potential harm. - -### What the web developer can do - -#### Do no harm - -[WCAG Guideline 2.3 Seizures and Physical Reactions](https://www.w3.org/WAI/standards-guidelines/wcag/new-in-21/) provides an overview: _"Do not design content in a way that is known to cause seizures or physical reactions"_. Don't include animation that a user cannot control. Don't design with patterns known to cause problems. If you must include a gif or png with flashing in it, record it in a video format instead so that controls are available to the user. Give the user the ability to avoid it, turn it off, or render it less harmful. - -#### Understand malice - -As a developer or designer, ask yourself if strobing content really needs to be on your webpage. Even if handled properly, there are those who may download offending content from your site and weaponize it. It is believed the first documented attempt at using computers to effect physical harm via animation began Saturday, March 22, 2008: The Epilepsy Foundation's website was hacked via posts with flashing images and links falsely claiming to be helpful. Users with vestibular disorders who were seeking help from the site were affected. - -A series of legal considerations are underway after journalist Kurt Eichenwald, a known epileptic, suffered a seizure after being sent an animated gif in December 2016: the flashing gif carried the message, _"You deserve a seizure for your posts"_. - -#### Control exposure, control access - -Controlling exposure to the page is key to ensuring that someone susceptible to seizures is not exposed to it accidentally. WCAG notes that a single object can make the entire page unusable. - -If you believe you may have an image or animation that may cause seizures, control access to it by first displaying a warning about the content, and then putting it in a location where the user must opt in to it, such as clicking a button, or ensuring that the link to the page has a distinct and obvious warning. - -Consider using metadata such as `<meta name="robots" content="noindex, nofollow">` so that the page is not indexed by search engines. - -#### Do Not Index, Do Not Follow - -By not indexing the page, the likelihood that users will stumble upon it via search will be reduced. - -```html -<html lang="en"> - <head> - <title>…</title> - <meta name="robots" content="noindex, nofollow" /> - </head> -</html> -``` - -### Animated GIFs - -All image types are potentially dangerous, however, animated GIFs deserve special mention because of their ubiquity, and the fact that the animation speed is actually controlled within the GIF file itself. - -#### Detect if a GIF is animated - -- The [animated-gif-detector](https://www.npmjs.com/package/animated-gif-detector) npm package allows for the ability to determine animate _as early as possible_ in a given HTTP request. -- Zakirt provides a gist for [animated-gif-detect.js](https://gist.github.com/zakirt/faa4a58cec5a7505b10e3686a226f285) - -With animated GIFs, ensure animation is inactive until the user chooses to activate it. For example, the user must push a button or check a box in order to start the animation. - -**Resources for detecting and controlling animated GIFs include:** - -- [RunKit Animated GIF Detector](https://npm.runkit.com/animated-gif-detector) -- [gifplayer](https://github.com/rubentd/gifplayer), a jQuery plugin that will help you play and stop animated GIFs on your website - -### Videos - -As in the case of animated GIFs, the user must push a button or check a box in order to start the animation. There are many ways to do this, such as NOT adding the [`autoplay`](/en-US/docs/Web/API/HTMLMediaElement/autoplay) attribute to `<video controls>`, or setting {{CSSxRef('animation-play-state')}} to `paused` as an initial state. To see a powerful example of how this can actually work see the article by Kirupa, ["Toggling Animations On and Off"](https://www.kirupa.com/html5/toggling_animations_on_off.htm). Kirupa uses the `animation-play-state` in concert with {{CSSxRef('transition')}}, {{CSSxRef('transform')}}, and [`prefers-reduced-motion`](/en-US/docs/Web/CSS/@media/prefers-reduced-motion) to create a very accessible experience under the user's control. - -[`animation-play-state`](https://www.w3.org/TR/css-animations-1/#animation-play-state) is a CSS property that sets whether an animation is running or paused. - -```css -div { - animation-play-state: paused; -} -``` - -[CSS transitions](/en-US/docs/Web/CSS/CSS_transitions) can be used to set the duration to zero for the initial stage of animation. - -```css -div { - transition-duration: 0s; -} -``` - -### Ensure the user can also stop animations as well as start them - -A {{HTMLElement('video')}} element with no attributes will not play automatically, and will also have no controls. Ensure that you add the `controls` attribute to the video element so that the user can stop the video as well as start it. - -```html -<video controls> - <source src="video.mp4" type="video/mp4" /> - <source src="video.ogg" type="video/ogg" /> - Your browser does not support the video tag. -</video> -``` - -#### Programmatically ensure controls are available - -The `HTMLMediaElement.controls` property reflects the `controls` HTML attribute, which controls whether user interface controls for playing the media item will be displayed. - -##### Video - -To ensure that a video has controls that a user can access, ensure that you add the word "controls" to HTML video and audio elements. - -`<video controls>` - -```html -<video controls> - <source src="myVideo.mp4" type="video/mp4" /> - <source src="myVideo.webm" type="video/webm" /> - <p> - Your browser doesn't support HTML video. Here is a - <a href="myVideo.mp4">link to the video</a> instead. - </p> -</video> -``` - -##### Audio - -Taking that same example and applying it to audio: - -`<audio controls>` - -```html -<audio controls> - <source src="myAudio.ogg" type="audio/ogg" /> - <source src="myAudio.mp3" type="audio/mpeg" /> - <p> - Your browser does not support the audio element. Here is a - <a href="myAudio.mp3">link to the audio</a> instead. - </p> -</audio> -``` - -##### Audio as part of Video - -Note that the audio in videos can be controlled by the `muted` content attribute, even though the content is within the {{HTMLElement('video')}} element rather than the {{HTMLElement('audio')}} element. This example is from the section on [muted media attribute](https://html.spec.whatwg.org/multipage/media.html#concept-media-muted) description from the HTML Living Standard. It explains that the video will autoplay quietly in the background until the user takes action to unmute the audio. - -```html -<video src="adverts.cgi?kind=video" controls autoplay loop muted></video> -``` - -### Control speed - -This seems obvious, but because there are so many MIME types, the mechanisms for handling them varies greatly, and for that reason there's not a one-size-fits-all solution to the problem. This is further complicated by the fact that even how files are classified complicates how they should be handled. For example, the .gif file format is usually understood to be an image, but is also considered a video file format in some circles because of its ability to be animated. For a comprehensive listing of media types, please visit [IANA.org's page for Media Types](https://www.iana.org/assignments/media-types/media-types.xhtml). - -The methods for sniffing them out is not a casual exercise. You may be interested in following the [MIME Sniffing](https://mimesniff.spec.whatwg.org/) standard at whatwg.org. Just about every kind of image can be animated; how they are animated varies, and therefore, the control of the animation varies. - -#### Commonly animated file types - -- **Bitmap**: Animation -- **Canvas**: MDN's tutorial on Canvas has a great section on [basic animations](/en-US/docs/Web/API/Canvas_API/Tutorial/Basic_animations). `setInterval()` is a mainstay in Canvas animation, but it is also interesting to see how it interacts with screen refresh. See the article, ["Controlling fps with requestAnimationFrame?"](https://stackoverflow.com/questions/19764018/controlling-fps-with-requestanimationframe) in which they discuss the nuts and bolts of implementing `requestAnimationFrame` against the backdrop of screen refresh. -- **GIFs (Raster)**: Tough to crack because control for their animation resides within the gif files themselves. For information about controlling the speed of GIFs see W3C's ["G152: Setting animated gif images to stop blinking after n cycles (within 5 seconds)"](https://www.w3.org/TR/WCAG20-TECHS/G152.html). A great Stack Overflow article on the subject is, ["Can you control GIF animation with JavaScript?"](https://stackoverflow.com/questions/2385203/can-you-control-gif-animation-with-javascript) -- **GIFV (Raster)**: Considered a variant, video version of GIF. The format is not standardized, and must reference a "real" video file (e.g. a .webm file) which must exist elsewhere. -- **JPG (Raster)** -- **MNG (Raster)**: Multiple-image Network Graphics is a graphics file format for animated images. Also considered by some to be a video format. -- **PNG, APNG (Raster)**: Portable Network Graphics and Animated Portable Network Graphics may both be animated. -- **SVGs (Vector)**: The MDN document, ["SVG: Scalable Vector Graphics"](/en-US/docs/Web/SVG), notes that _"SVG is a text-based open Web standard. It is explicitly designed to work with other web standards such as [CSS](/en-US/docs/Web/CSS), [DOM](/en-US/docs/Web/API/Document_Object_Model), and [SMIL](/en-US/docs/Web/SVG/SVG_animation_with_SMIL)."_ SVGs can be used as an image like in this example: `<img src="example.svg" alt="This is an image using a svg as a source">`. This means that SVG appearance and animation can be controlled through CSS keyframes and animations. For interaction with JavaScript, see the MDN documents on [SVG Interfaces](/en-US/docs/Web/API/Document_Object_Model#svg_dom) and [Applying SVG effects to HTML content](/en-US/docs/Web/SVG/Applying_SVG_effects_to_HTML_content). -- **Voxel (Raster)**: Three-dimensional [voxel](https://en.wikipedia.org/wiki/Voxel) raster graphics are employed in video games, as well as in medical imaging. - -#### Text can also be animated - -Translations and transformations can animate text in a div, and do harm. Moving text can induce seizures for the same reasons that moving images do, so avoid animating your text. It's a good idea to avoid using moving text anyhow, as many screen readers cannot read moving text and it's bad user experience even for those with no vision or vestibular issues. - -### CSS for animation - -In the style sheet or within the {{HTMLElement('style')}} element, many options can combine together to create a powerful experience for the user. We've already mentioned the `animation` property earlier in this document. It's actually shorthand for all animation properties, including: - -- `animation-play-state` -- `animation-duration` has a value of `<time>`; this is the duration an animation takes to complete one cycle. This may be specified in either seconds `(s)` or milliseconds `(ms)`. A default value of `0s` indicates no animation should occur. -- `animation-timing-function` - -The animation property is already powerful on its own, but combined with other properties and queries such as `prefers-reduced-motion`, a powerful set of options can be set up for the user. Setting `animation-duration` and `transition-duration` properties to a short duration rather than setting them to `animation: none` and `transition: none`, enables a safeguard to prevent issues in any case there is a dependency on the animation to run. - -### JavaScript animation - -JavaScript is often used to control {{HTMLElement('canvas')}} elements and SVGs. Most JavaScript code that applies to HTML video also applies to audio. `HTMLMediaElement.playbackRate` is used to implement user controls for the playback rate for both video and audio. A value of 1.0 is default and considered normal speed; a value of 0.5 is half the speed, a value of 2.0 is twice the speed. A negative number plays the video or audio backwards. Set the playback rate property: `HTMLMediaElement.playbackRate = playbackSpeed`. - -[document.getAnimations()](/en-US/docs/Web/API/Document/getAnimations) is an experimental technology, and includes [CSS Animations](/en-US/docs/Web/CSS/CSS_animations), [CSS Transitions](/en-US/docs/Web/CSS/CSS_transitions), and [Web Animations](/en-US/docs/Web/API/Web_Animations_API). The MDN page on [Document.getAnimations()](/en-US/docs/Web/API/Document/getAnimations) provides the following code sample of how to slow down all animations on a page to half speed: - -```js -document.getAnimations().forEach((animation) => { - animation.playbackRate *= 0.5; -}); -``` - -#### Image sources for animation - -One of the easiest ways is to start with an image that is already in existence, using it as an image source, and then animating it. Remember, you can use GIFs, JPGs, PNGs, SVGs and other file types here as an image source, as long as they are allowed file types—and sizes—in your environment. SVGs are often not allowed, due to security concerns. The MDN document, [Basic animations](/en-US/docs/Web/API/Canvas_API/Tutorial/Basic_animations), provides outstanding examples of this, using multiple image sources for the sun, earth, and moon, and using several canvas methods to control the speed and animation of the earth as it orbits around the sun, and the moon as it orbits around the earth. Use the codepen available with this tutorial to adjust `ctx.rotate` in the code to see how the animation is affected when changes are made. - -#### If you absolutely, positively must use a flashing animation… - -Make sure it has a control on it. Make sure it is turned off when the viewer first encounters it, and that a user must opt-in to see the animation. - -An example of a format that has no controls available to the user is a gif file. Animation speed is controlled within the gif image itself. Converting an animated gif to video enables controls to be put on the animation, and gives the user agency. There are many free online converters available for use, such as [EZGif](https://ezgif.com/) and [GIF to MP4](https://gif-2-mp4.com/). - -#### Set user expectations - -Give users a heads-up as to what will happen before they click on that link. Describe the animation that is to follow. See [WCAG 2.1 Success Criterion 3.2.5 Change on Request](https://www.w3.org/TR/WCAG21/#change-on-request). - -#### Keep it small - -If you absolutely positively must have flashing, keep it small. Generally speaking, limit the size of the flash to an area approximately 341 by 256 pixels or less. This pixel size assumes that a viewer is at a typical distance from the screen. As mentioned earlier, this size may be too big if the image is to be viewed at close range, such as in a VR headset. WebVR is an open specification that makes it possible to experience VR in your browser. WebVR can be experienced on phone, computer or headset. - -If you are designing for a game or VR that uses an ocular mask, **or CAN be used by an ocular mask**, such as in Firefox Reality (a browser for virtual reality), ensure that the size of the rectangle is much smaller than 341 by 256 pixels, because the image is much closer to a user's eyes. - -#### Reduce contrast - -Normally, higher contrast is a good thing when it comes to accessibility. The greater the contrast of a text color to its background (technically called _luminosity contrast ratio,_ according to W3.org's page on [Colors with Good Contrast](https://www.w3.org/WAI/perspective-videos/contrast/), the easier such content is to read. Users with low vision are especially appreciative of efforts to ensure high contrast of text against its background. When the content is animated, however, **_reducing_** contrast is actually a way to reduce the likelihood that the animated content will cause seizures. Drop the contrast ratio if three flashes within one second are detected. - -The contrast ratio is defined in [WCAG 2.1](https://www.w3.org/TR/WCAG21/) as follows: - -- _contrast ratio_ - - - : (L1 + 0.05) / (L2 + 0.05), where - - - L1 is the [relative luminance](https://www.w3.org/TR/WCAG21/#dfn-relative-luminance) of the lighter of the colors, and - - L2 is the [relative luminance](https://www.w3.org/TR/WCAG21/#dfn-relative-luminance) of the darker of the colors. - -It's best if you can adjust the contrast before it is uploaded or published to the web. For videos and animated GIFs, the Adobe Suite of products is a phenomenal resource for traditional images. Also for images, an online tool available is pinetools.com's [Brightness and contrast online](https://pinetools.com/brightness-contrast-image). If you intend to make animated GIFs, for example, start with one that has a lower contrast ratio. - -JavaScript is also an option for reducing contrast dynamically. Here's a code example from the section titled, ["Example: Setting the background color of a paragraph"](/en-US/docs/Web/API/Document_Object_Model/Traversing_an_HTML_table_with_JavaScript_and_DOM_Interfaces#setting_the_background_color_of_a_paragraph) from the MDN document, [Traversing an HTML table with JavaScript and DOM Interfaces](/en-US/docs/Web/API/Document_Object_Model/Traversing_an_HTML_table_with_JavaScript_and_DOM_Interfaces). Notice that the color in the example is described in the **RGB** color space. - -**HTML Content [(link to source page)](/en-US/docs/Web/API/Document_Object_Model/Traversing_an_HTML_table_with_JavaScript_and_DOM_Interfaces#html_2)** - -```html -<body> - <input - type="button" - value="Set paragraph background color" - onclick="set_background()" /> - <p>hi</p> - <p>hello</p> -</body> -``` - -**JavaScript Content [(link to source page)](/en-US/docs/Web/API/Document_Object_Model/Traversing_an_HTML_table_with_JavaScript_and_DOM_Interfaces#javascript_2)** - -```js -function set_background() { - // get a list of all the body elements (there will only be one), - // and then select the zeroth (or first) such element - myBody = document.getElementsByTagName("body")[0]; - - // now, get all the p elements that are descendants of the body - myBodyElements = myBody.getElementsByTagName("p"); - - // get the second item of the list of p elements - myP = myBodyElements[1]; - myP.style.background = "rgb(255 0 0)"; -} -``` - -#### Avoid fully saturated reds for flashing content - -As mentioned earlier in this document, the Epilepsy Foundation of America convened a workshop in August 2004 to begin to develop an expert consensus on photosensitive seizures. Among their results was the understanding that _"A flash is a potential hazard if it has luminance at least 20 cd/m2, occurs at a frequency of least 3 Hz, and occupies a solid visual angle of at least 0.006 steradians (about 10% of the central visual field or 25% of screen area at typical viewing distances). A transition to or from saturated red also is considered a risk."_ They also note in that same consensus: _"Irrespective of luminance, a transition to or from a saturated red is also considered a risk."_ - -### Provide alternative CSS styles - -With the understanding that much of animation and flashing can be controlled via CSS methods, it's important to explore ways to make alternative options available to users, and to make the control of these options convenient and visible. - -#### Alternative Style Sheets - -Modern browsers will display the alternate CSS available in alternate style sheets if the users know where to look for them. In some cases, the alternate styles are revealed when the users go through the View menu, in other cases they are manifested in the settings, sometimes both. Not all users know to look for these options via the browser or settings, so it's worth considering doing things the old-fashioned way, with obvious buttons or links to change the style so that users can see them. Doing so won't conflict with, or override, the browser's ability to read the alternate style sheets, or the ability of the user to set preferences in the settings. - -It's important to know that certain users, such as those who rely on speech-recognition systems, often depend on legacy buttons and links because their disability prevents them from using a mouse, or to be able to take advantage of touch events on mobile tablets. - -Common ways to include the alternative stylesheets into your HTML documents are to use the {{HTMLElement('link')}} element, and {{CSSxref('@import')}}. - -#### The {{HTMLElement('link')}} element - -Use the {{HTMLElement('link')}} element, alongside with and together with the attributes of `rel="alternate stylesheet"` and for title, `title="…"` in the {{HTMLElement('head')}} section of the webpage. - -```html -<head> - <title>Home Page</title> - <link href="main.css" rel="stylesheet" title="Default Style" /> - <link - href="alternate1.css" - rel="alternate stylesheet" - title="Alternate One" /> - <link - href="alternate2.css" - rel="alternate stylesheet" - title="Alternate Two" /> -</head> -``` - -**{{CSSxref('@import')}}** is also a way to incorporate style sheets, but it is not quite as well supported as the {{HTMLElement('link')}} element. - -```html -<style> - @import url(alternate1.css); - @import url(alternate2.css); -</style> -``` - -By using alternate style sheets (remember to add the titles) you are setting it up for users to be able to use their browsers to choose alternate styles. - -### Dynamic Style Switching - -One problem with relying on the browser to reveal alternative styles is that not all users are technically savvy enough to discover the alternate styles. Or, because of their disability, are not able to. Buttons or links make it obvious that options are available to many grateful users. There's a multitude of ways to add toggle buttons to allow the user to switch to the different style sheets. That said, the use of alternative style sheets are not the only option. Another option is to manipulate the style of the page itself. According to the MDN document, [Using dynamic styling information](/en-US/docs/Web/API/CSS_Object_Model/Using_dynamic_styling_information), _"where possible, it really is best practice to dynamically manipulate classes via the [`className`](/en-US/docs/Web/API/Element/className) property since the ultimate appearance of all of the styling hooks can be controlled in a single stylesheet"._ One of the best examples around as to how to do this is from the W3C's page, ["C29: Using a style switcher to provide a conforming alternate version"](https://www.w3.org/TR/WCAG20-TECHS/C29.html). - -### Extreme Cases: Text-Only Alternatives - -A separate, alternative stylesheet that prevents images from being displayed is easy to make. It's a draconian solution; but it is one that is sometimes necessary for school teachers and other public servants who must serve those with extreme sensitivities. These public servants can ask their developers to develop a special alternative style sheet using `display: none`. Here's how to do it via CSS: - -```css -img { - display: none; -} -``` - -#### Take advantage of media queries with {{HTMLElement('style')}} - -In setting up media queries, you are enabling controls by the user; these controls are made available in the browser or in the OS. See the MDN document, [Accessibility: What users can do to browse more safely](/en-US/docs/Web/Accessibility/Accessibility:_What_users_can_to_to_browse_safely) to see more details of how a user accesses the controls. - -#### `prefers-reduced-motion` - -Support for `prefers-reduced-motion` in modern browsers is growing. - -```css -@media screen and (prefers-reduced-motion: reduce) { -} -@media screen and (prefers-reduced-motion) { -} -``` - -To see a great example of how to use the code `prefers-reduced-motion`, visit the MDN document, [`prefers-reduced-motion`](/en-US/docs/Web/CSS/@media/prefers-reduced-motion), or see the example below from the section on ["New in Chrome 74"](https://developer.chrome.com/blog/new-in-chrome-74/). - -```css -button { - animation: vibrate 0.3s linear infinite both; -} - -@media (prefers-reduced-motion: reduce) { - button { - animation: none; - } -} -``` - -#### `prefers-color-scheme` - -This can be useful if the ambient light API is not available. Support is emerging. - -```css -@media (prefers-color-scheme: dark) { - /* adjust styles for dark mode */ -} -``` - -#### Window.matchMedia() - -There is a powerful tool available to developers via Window.matchMedia(). A great resource is MDN's document on [`Window.matchMedia()`](/en-US/docs/Web/API/Window/matchMedia). - -#### Media update feature - -The more often the screen is refreshed, the more stable it appears to the human eye, and the less it "flickers". The vast majority of modern technology refreshes at a rate that does not cause problems with photosensitivity. However, not everybody is wealthy enough to be able to afford the most recent technology: older or underpowered computers can have low refresh rates. [AbilityNet's Factsheet (November 2015) Computers and Epilepsy](https://www.abilitynet.org.uk/sites/abilitynet.org.uk/files/Epilepsy%20and%20Computing%20Nov%202015.pdf) describes more of the details on refresh rates. - -A very old article, Tech Republic's ["Epilepsy and CRT/LCD screen flicker"](https://www.techrepublic.com/forums/discussions/epilepsy-and-crt-lcd-screen-flicker/), had an interesting response concerning the refresh rates in Hz: - -- _"This effect is noticeable, and documented, up to 70 Hz."_ -- _"These studies would seem to indicate that you should stay away from refresh rates under 70 Hz, and use a rate not divisible by 10."_ - -Eric Bailey, of CSS-Tricks, found an innovative use the update feature which, used in combination with animation-duration or transition-duration, to conclude at a rate that is imperceptible to the human eye. In other words, Eric's techniques address the refresh-rate problem. The CSS below is from the CSS-Tricks article, [" Revisiting prefers-reduced-motion, the reduced motion media query"](https://css-tricks.com/revisiting-prefers-reduced-motion/). - -```css -@media screen and (prefers-reduced-motion: reduce), (update: slow) { - * { - animation-duration: 0.001ms !important; - animation-iteration-count: 1 !important; /* Hat tip Nick/cssremedy (https://css-tricks.com/revisiting-prefers-reduced-motion/#comment-1700170) */ - transition-duration: 0.001ms !important; - } -} -``` - -From W3.org's page on [Media Queries 4](https://www.w3.org/TR/mediaqueries-4/): - -The `update` media feature is used to query the ability of the output device to modify the appearance of content once it has been rendered. It has the values of "none", "slow", and "fast". - -## Developmental & Experimental Features - -### Media Queries Level 5 - -EnvironmentMQ (Planned in Media Queries Level 5) - -- `light-level` - - : [`light-level`](https://drafts.csswg.org/mediaqueries-5/#light-level) has three valid values: dim, normal, and washed. Interestingly, the specification refrains from actually defining the three levels in terms of a measurement of lux, because devices with a light sensor usually adjust the brightness of the screen automatically. The specifications also note the difference in technology, such as e-ink, which remains readable in bright daylight, versus liquid crystals, which do not. -- `environment-blending` - - : From W3C's Draft document, Media Queries Level 5: _"The [`environment-blending`](https://drafts.csswg.org/mediaqueries-5/#descdef-media-environment-blending) media feature is used to query the characteristics of the user's display so the author can adjust the style of the document. An author might choose to adjust the visuals and/or layout of the page depending on the display technology to increase the appeal or improve legibility."_ - -#### User Preference Media Features (Planned in Media Queries Level 5) - -[User Preference Media Features](https://drafts.csswg.org/mediaqueries-5/#mf-user-preferences) in [W3C Editor's Draft Media Queries Level 5](https://drafts.csswg.org/mediaqueries-5/) are especially promising in providing user control over media. Here are some highlights: - -- `inverted-colors` - - : According to the section, [User Preference Media Features](https://drafts.csswg.org/mediaqueries-5/#mf-user-preferences), "The [`inverted-colors`](https://drafts.csswg.org/mediaqueries-5/#descdef-media-inverted-colors) media feature indicates whether the content is displayed normally, or whether colors have been inverted." -- [`forced-colors`](/en-US/docs/Web/CSS/@media/forced-colors) - - : In [`forced-colors-mode`](https://drafts.csswg.org/css-color-adjust-1/#forced-colors-mode), the user agent enforces the user's preferred color palette on the page, overriding the author's chosen colors. From W3C's Draft document, Media Queries Level 5 section on forced-colors: _"The forced-colors media feature is used to detect if the user agent has enabled a [forced colors mode](https://drafts.csswg.org/css-color-adjust-1/#forced-colors-mode) where it enforces a user-chosen limited color palette on the page"._ The user will need to be made aware of this ability, and it will need to play nice with the appropriate value for the prefers-color-scheme media query. -- `light-level` - - : From W3C's Draft document, Media Queries Level 5 section on light-level: _"The [`light-level`](https://drafts.csswg.org/mediaqueries-5/#descdef-media-light-level) media feature is used to query about the ambient light-level in which the device is used, to allow the author to adjust style of the document in response."_ This will be a godsend to those who have motor-skills problems, or for some with cognitive difficulties, who cannot find the right "button" to change their screen settings. -- prefers-contrast - - : From W3C's Draft document, Media Queries Level 5 section on [`prefers-contrast`](/en-US/docs/Web/CSS/@media/prefers-contrast): _"The `prefers-contrast` media feature is used to detect if the user has requested the system increase or decrease the amount of contrast between adjacent colors. For example, many users have difficulty reading text that has a small difference in contrast to the text background and would prefer a larger contrast."_ Sometimes there can be such a thing as too much contrast; a halo effect around text can occur in such situations and actually reduce legibility. Putting the amount of contrast in the user's control is a definite gift for accessibility. - -#### `MediaQueryList` Interface - -Section 4.2 from the CSSWG.org drafts integrates with the [event loop](https://html.spec.whatwg.org/multipage/webappapis.html#event-loop) defined in HTML. [HTML](https://drafts.csswg.org/cssom-view/#biblio-html) for the [`MediaQueryList`](https://drafts.csswg.org/cssom-view/#mediaquerylist) object. See the MDN document, [MediaQueryList](/en-US/docs/Web/API/MediaQueryList) for more information. - -#### Personalization Help and Support - -The requirement for the `literal` property is taken from [section 23 Non-literal Text and Images](https://www.w3.org/TR/personalization-semantics-help-1.0/). - -**Requirement:** Some users cannot understand non-literal text and icons such as metaphors, idioms etc. The `literal` property is intended to identify text or images as non-literal and allows the author to explain non-literal text and images to users. - -#### Transitions (for CSS and SVG) - -The following is from the [Web Animations model](https://www.w3.org/TR/web-animations-1/) CSSWG.org drafts - -The Web Animations model is intended to provide the features necessary for expressing [CSS Transitions](https://drafts.csswg.org/web-animations/#biblio-css-transitions-1), [CSS Animations](https://drafts.csswg.org/web-animations/#biblio-css-animations-1), and [SVG](https://drafts.csswg.org/web-animations/#biblio-svg11). - -## See also - -### MDN - -- [Accessibility: What users can do to browse more safely](/en-US/docs/Web/Accessibility/Accessibility:_What_users_can_to_to_browse_safely) -- [Accessibility: Understanding color and luminance](/en-US/docs/Web/Accessibility/Understanding_Colors_and_Luminance) -- [Applying SVG effects to HTML Content](/en-US/docs/Web/SVG/Applying_SVG_effects_to_HTML_content) -- [Basic Animations](/en-US/docs/Web/API/Canvas_API/Tutorial/Basic_animations) (Canvas Tutorial) -- [Canvas API](/en-US/docs/Web/API/Canvas_API) -- [CanvasRenderingContext2D.drawImage()](/en-US/docs/Web/API/CanvasRenderingContext2D/drawImage) -- [\<color>](/en-US/docs/Web/CSS/color_value) -- [Document Object Model](/en-US/docs/Web/API/Document_Object_Model) -- [MediaQueryList](/en-US/docs/Web/API/MediaQueryList) -- [Using dynamic styling information](/en-US/docs/Web/API/CSS_Object_Model/Using_dynamic_styling_information) -- [WebGL: 2D and 3D graphics for the web](/en-US/docs/Web/API/WebGL_API) -- [WebVR API](/en-US/docs/Web/API/WebVR_API) - -### Color - -- [Color Tutorial: describing color](https://colortutorial.design/) Tom Jewett -- [Formula to Determine Brightness of RGB color](https://stackoverflow.com/questions/596216/formula-to-determine-perceived-brightness-of-rgb-color) Stack Exchange Discussion Thread -- [How the Color Red Influences Our Behavior](https://www.scientificamerican.com/article/how-the-color-red-influences-our-behavior/) Scientific American By Susana Martinez-Conde, Stephen L. Macknik on November 1, 2014 - -### Discussions - -- [Problems with WCAG 2.0 Flash Definition #553](https://github.com/w3c/wcag/issues/553) -- [WCAG 2.1 Understanding 2.3.1 - missing/vague dimension definitions #585](https://github.com/w3c/wcag/issues/585) - -### Epilepsy and Seizures - -- [Shedding Light on Photosensitivity, One of Epilepsy's Most Complex Conditions](https://www.epilepsy.com/stories/shedding-light-photosensitivity-one-epilepsys-most-complex-conditions-0) Epilepsy Foundation: _"Certain individuals are born with special sensitivity to flashing lights or contrasting visual patterns, such as stripes, grids and checkerboards. Because of this condition, their brain will produce seizure-like discharges when exposed to this type of visual stimulation."_ -- [Gamma oscillations and photosensitive epilepsy](https://www.sciencedirect.com/science/article/pii/S0960982217304062?via%3Dihub) Current Biology [Volume 27, Issue 9](https://www.sciencedirect.com/journal/current-biology/vol/27/issue/9), 8 May 2017, Pages R336-R338: _"Certain [visual images](https://www.sciencedirect.com/topics/biochemistry-genetics-and-molecular-biology/retina-image), even in the absence of motion or flicker, can trigger seizures in patients with photosensitive epilepsy."_ -- [Photosensitive Seizures. Cedars-Sinai](https://www.cedars-sinai.org/health-library/diseases-and-conditions/p/photosensitive-seizures.html) "_Photosensitive seizures are triggered by flashing or flickering lights. These seizures can also be triggered by certain patterns such as stripes._" -- [Photic-and pattern-induced seizures: expert consensus of the Epilepsy Foundation of America Working Group](https://pubmed.ncbi.nlm.nih.gov/16146438/) Eplepsia 2005 Sept, 46(9):1423-5 PubMed.gov NCBI [Harding G](https://pubmed.ncbi.nlm.nih.gov/?term=Harding%20G%5BAuthor%5D&cauthor=true&cauthor_uid=16146438), [Wilkins AJ](https://pubmed.ncbi.nlm.nih.gov/?term=Wilkins%20AJ%5BAuthor%5D&cauthor=true&cauthor_uid=16146438), [Erba G](https://pubmed.ncbi.nlm.nih.gov/?term=Erba%20G%5BAuthor%5D&cauthor=true&cauthor_uid=16146438), [Barkley GL](https://pubmed.ncbi.nlm.nih.gov/?term=Barkley%20GL%5BAuthor%5D&cauthor=true&cauthor_uid=16146438), [Fisher RS](https://pubmed.ncbi.nlm.nih.gov/?term=Fisher%20RS%5BAuthor%5D&cauthor=true&cauthor_uid=16146438); [Epilepsy Foundation of America Working Group](https://pubmed.ncbi.nlm.nih.gov/?term=Epilepsy%20Foundation%20of%20America%20Working%20Group%5BCorporate%20Author%5D). - -### GPII - -- [Accessibility Master List](https://ds.gpii.net/learn/accessibility-masterlist) Gregg Vanderheiden Ph.D. Editor - -### Harding - -Along with the PEAT tool, is generally recognized to be one of the two "gold standards" for analyzing flashes. - -- [Harding Flash and Pattern Analyzer](https://www.hardingfpa.com/) - -### ISO - -- [IEC 61966-2-2:2003(en)](https://www.iso.org/obp/ui/#iso:std:iec:61966:-2-2:ed-1:v1:en) Multimedia systems and equipment — Colour measurement and management — Part 2-2: Colour management — Extended RGB color space — scRGB - -### Photosensitive Epilepsy Analysis Tool - -Along with the Harding tool, is generally recognized to be one of the two "gold standards" for analyzing flashes. - -- [Trace Research and Development Center](https://trace.umd.edu/peat/) -- [Using PEAT To Create Seizureless Web Animations](https://www.useragentman.com/blog/2017/04/02/using-peat-to-create-seizureless-web-animations/) - -### W3C - -- [CSS Color Module Level 3](https://www.w3.org/TR/css-color-3/) -- [Personalization Semantics Explainer 1.0](https://www.w3.org/TR/personalization-semantics-1.0/). Working Draft -- [WAI-Adapt: Tools Module](https://www.w3.org/TR/adapt-tools/) Working Draft -- [Three Flashes or Below Threshold Understanding SC 2.3.1](https://www.w3.org/TR/UNDERSTANDING-WCAG20/seizure-does-not-violate.html) Understanding WCAG 2.0 (Older, but contains some explanations of references made in the WCAG 2.1 criteria) -- [Three Flashes or Below Threshold Understanding Success Criterion 2.3.1](https://www.w3.org/WAI/WCAG21/Understanding/three-flashes-or-below-threshold.html) Understanding WCAG 2.1 -- [Understanding Success Criteria 1.4.3: Contrast (Minimum)](https://www.w3.org/WAI/WCAG21/Understanding/contrast-minimum.html) -- [Web Accessibility Initiative (WAI)](https://www.w3.org/WAI/) -- [Web Animations Model](https://www.w3.org/TR/web-animations-1/) W3C Working Draft -- [Web Content Accessibility Guidelines (WCAG) 2.0](https://www.w3.org/TR/WCAG20/#relativeluminancedef) definition of relative luminance -- [Web Content Accessibility Guidelines (WCAG) 2.1](https://www.w3.org/TR/WCAG21/) - -## Contributors - -Heartfelt thanks to Teal; Wayne Dick of the [Low Vision Task Force of the W3C](https://www.w3.org/WAI/GL/task-forces/low-vision-a11y-tf/); Tom Jewett and Eric Eggert from [Knowbility](https://knowbility.org/); Jim Allan of the [Diagram Center](http://diagramcenter.org/); and Dr. Selim R. Benbadis, Director, [Comprehensive Epilepsy Program and Clinical Neurophysiology Laboratory at USF and TGH in Tampa, Florida](https://health.usf.edu/medicine/neurology/epilepsy) for their great, great assistance and discussions on this topic. - -We are _all_ in tremendous gratitude to the Trace Research & Development Center for making their amazing tool, the [Photosensitive Epilepsy Analysis Tool (PEAT)](https://trace.umd.edu/peat/) for free. diff --git a/files/en-us/web/accessibility/understanding_colors_and_luminance/index.md b/files/en-us/web/accessibility/understanding_colors_and_luminance/index.md deleted file mode 100644 index 0919465f31f9cdc..000000000000000 --- a/files/en-us/web/accessibility/understanding_colors_and_luminance/index.md +++ /dev/null @@ -1,324 +0,0 @@ ---- -title: "Web Accessibility: Understanding Colors and Luminance" -slug: Web/Accessibility/Understanding_Colors_and_Luminance -page-type: guide ---- - -{{AccessibilitySidebar}} - -While understanding color, luminance, and saturation is important for design and readability for all sighted users, they are essential for those with reduced vision and color-deficient vision and those with specific neurological, cognitive, and other impairments. - -Accessibility guidelines define adequate [color contrast](/en-US/docs/Web/Accessibility/Understanding_WCAG/Perceivable/Color_contrast) for sighted users with reduced vision, as well as guidelines intended to help users with color insensitive vision, commonly referred to as "color blindness". Understanding color is also important in preventing [seizures and other physical reactions](/en-US/docs/Web/Accessibility/Seizure_disorders) in people with vestibular disorders or other neurological disorders. - -## Overview - -The choice of colors and their use is a significant component of accessibility. On the surface, the subject seems simple. Still, it is a complex subject because color perception is as much about the physiology of the eye and human brain processing as it is about light emitting from a computer screen. - -### Environment and perception - -Environment matters. Perception of color in a well-lit room will be different than perception of that same color on that same computer screen in a dark room. Regarding accessibility, using certain color combinations has more impact than others. Font size, [font style](https://www.nngroup.com/articles/glanceable-fonts/) (some fonts are so thin or fancy that they present accessibility problems on their own), background color, the size of the background space around the text, even pixel densities, and more all affect how color is delivered from the screen. - -A viewer's distance from the screen, the ambient background, the health of his eyes, and more all affect how that color is received by the viewer. How the viewer perceives color after it gets to their eyes is yet another matter, and can be affected by overall health. Fortunately, there are [media queries](/en-US/docs/Web/CSS/@media) that enable developers to provide styles based on user preferences, including [contrast](/en-US/docs/Web/CSS/@media/prefers-contrast) and [color scheme](/en-US/docs/Web/CSS/@media/prefers-color-scheme) preferences. - -When supported, the [Ambient Light Sensor](/en-US/docs/Web/API/AmbientLightSensor) interface returns the current light level or illuminance of the ambient light around the hosting device, enabling a web page to be aware of any change in the light intensity, and consequently, adjust the text accordingly. Additionally, the above media queries enable developers to provide alternative user experiences when user preferences indicate preferred contrast levels, automatically adjusting levels depending on the user's location and what kind of screen they are using. - -### Luminance and perception - -Color, contrast, and luminance are the most central and critical concepts to creating accessible web content with color. Luminance is of particular importance, however, because understanding what it is and how it is employed enables accessibility for those who are color-blind, as well as those who can perceive color. The luminance contrast enables the color blind to distinguish dark from light. - -Luminance must be established before the contrast may be. When speaking of color contrast, W3C formulas are incorporating luminance, not just the colors ("hues") themselves. - -### Terminology - -Terminology can be confusing because different terms often describe the same thing. "Luminance" and "Saturation" are particularly important to get right. For example, "saturation" is known as "chroma" in some circles. In others, "chroma" and "saturation" are two different concepts. The "L" in the HSL color space is sometimes referred to as "luminosity," and other times as "lightness." Even something seemingly simple, like naming common colors, can be open to debate. For example, the color "crimson red" may be described in hex values as `#990000` by some and `#DC143C` by others. For this document, we'll use terminology as it is defined in the W3C, in the [CSS Color Module Level 4](https://www.w3.org/TR/css-color-4/) - -When working with color, it's important to know which "color space" you are working in, as different color spaces map to different measurement systems. - -In color printing, your printer likely has cyan, magenta, yellow, and black (CMYK) ink cartridges. CMYK is a subtractive model wherein the four inks _remove_ specific wavelengths of light, reflecting only the narrow range each is associated with. RGB is an additive color model that adds different proportions of red, green, and blue lights. - -Currently, the {{glossary("RGB", "RGB color space")}} predominates as the space web developers work in. While HEX, RGB, and HSL color spaces are notated differently, browsers automatically convert values between these color notations. [CSS color modules](/en-US/docs/Web/CSS/CSS_colors) provide additional color spaces. Still, because of the current domination of the RGB color space in measuring color output, most calculations in this document are presumed to be in the RGB color space and, very specifically, in the sRGB color space. - -## The sRGB color space - -Color has many ways of being defined, as is apparent in the [`<color>` data type](/en-US/docs/Web/CSS/color_value), including RGB, RGB decimal, RGB percent, HSL, HWB, LCH, LAB, and CMYK, among others. - -For digital concerns, much of the technology has historically resided in the RGB color space. The RGB color model is extended to include "alpha" — RGBA — to allow specification of the opacity of a color. Other methods for measuring color involve measurements using other color spaces and are supported in modern displays and browsers. Still, color measurements in the RGB color space predominate, including in video production. - -Technologies, such as [OpenGL](https://en.wikipedia.org/wiki/OpenGL) and [Direct3D](https://en.wikipedia.org/wiki/Direct3D) incorporate support for the sRGB gamma curve, although some articles for OpenGL reference use of RGBA rather than sRGB. WebGL is usually in the RGBA format; see an example of how it is used in "[Clearing with colors](/en-US/docs/Web/API/WebGL_API/By_example/Clearing_with_colors)". - -### CSS color values - -It's important to know that there are variations even within one {{glossary("color space")}}, such as the {{glossary("RGB")}} color space. For example, variations of the RGB color space include **RGB**, **sRGB**, **Adobe RGB**, **Adobe Wide Gamut RGB**, and **RGBA**, among others. - -These are examples of the CSS notations used to define a color. Here the example color for each is a fully opaque magenta: - -```css -/* named color */ -color: magenta; - -/* sRGB value with percentage values */ -color: rgb(100% 0% 100%); -color: rgb(100% 0% 100% / 100%); - -/* by sRGB numeric values */ -color: rgb(255 0 255); -color: rgb(255 0 255 / 1); - -/* legacy rgb and rgba notation */ -color: rgb(100%, 0%, 100%); -color: rgba(255, 0, 255, 1); - -/* by sRGB value in hex */ -color: #f0f; /* #rgb, a shorthand for #rrggbb */ -color: #ff00ff; /* #rrggbb */ -color: #f0ff; /* #rgba */ -color: #ff00ffff; /* #rrggbbaa */ - -/* by HSL representation of the sRGB value */ -color: hsl(300 100% 50%); -color: hsl(300deg 100% 50% / 100%); - -/* by HWB representation of the sRGB value */ -color: hwb(300deg 0% 0%); -color: hwb(300 0% 0% / 1); - -/* by LAB representation of the sRGB value*/ -color: lab(60 93.56 -60.5); -color: lab(60 93.56 -60.5 / 1); - -/* representation in the CIELAB color spaces */ -oklch(0.7 0.32 328.37); -oklch(0.7 0.32 328.37 / 1); - -/* color() function in the XYZ color space */ -color(xyz-d65 0.59 0.28 0.96); -color(xyz-d65 0.59 0.28 0.96 / 1); -``` - -The first example uses one of the defined [named colors](/en-US/docs/Web/CSS/named-color). - -We can set the sRGB values directly as a percentage, with 0% being off (black) and 100% being the full value for that color. The values are in the order of red, green, and blue. We can also set the sRGB values directly by a number from 0 to 255. - -Shown after that are hex color values. Hexadecimal is a numbering system with base-16, where the 0-255 integer is represented by two digits ranging from 0-15 using the digits 0-9 and a-f for 10-15. Thus, `ff` = `255`, `00` = `0`, and `d5` = `200`. The '#' symbol precedes the color to indicate the value is hex. - -If all values are pairs of identical digits, the value can be represented by single digits that the browser will duplicate. Thus `f00` is the same as `ff0000`. If a fourth set of numbers is present, that value is the A in RGBA, the alpha channel defining transparency in terms of the opacity value of the color. A higher value means the color is more opaque and therefore, less transparent. In the examples above, the alpha value is `f`, `ff`, `1`, and `100%` for fully opaque. - -The example also shows the legacy syntax for both [`rgb()` and `rgba()`](/en-US/docs/Web/CSS/color_value/rgb#examples). The legacy syntax for color functions is comma-separated, with a separate function for when the alpha channel is included. New color functions only have one syntax with space-separated (rather than comma-separated) values, with the alpha channel, if present, being preceded by a slash. Modern syntax allows for mixing numbers and percents and supports the `none` keyword; the comma-separated legacy syntax does not. - -The following examples show "HSL", which stands for _Hue, Saturation, and Lightness_. HSL color values are considered by many to be more intuitive than RGB values. The color produced from the settings are still in the sRGB colorspace, but [`hsl()`](/en-US/docs/Web/CSS/color_value/hsl) is an intuitive syntax for many. The hue is adjusted as an angle, and it is easy to create a user interface using a knob or circular control to adjust the hue. Do note that HSL colors incorporate _lightness_, not _luminance_, which is a significant consideration. - -The next examples shows "HWB" which stands for _Hue, Whiteness, and Blackness_. With both `hsl()` and [`hwb()`](/en-US/docs/Web/CSS/color_value/hwb) the first value can be a [`<number>`](/en-US/docs/Web/CSS/number) or an [`<angle>`](/en-US/docs/Web/CSS/angle) value. When unitless, the value is interpreted as `deg` degrees. - -There are several other color functions and color spaces. The last three examples demonstrate representing magenta using the [`lab()`](/en-US/docs/Web/CSS/color_value/lab), [`oklch()`](/en-US/docs/Web/CSS/color_value/oklch), and [`color()`](/en-US/docs/Web/CSS/color_value/color) color functions. - -### Conversions - -As we saw, one color within the same color space may be expressed in many ways. Looking at how the RGB color space is used to describe the color "magenta", you can see that the same color may be expressed in a shorthand, three-digit hex number that converts to an rgb value as a six-digit hex number that also converts to the same rgb value, or as a rgba value, expressed in percentages. - -RGB is hardware-oriented, reflecting the use of CRTs. Many developers and designers prefer the intuitiveness of [`hsl()`](/en-US/docs/Web/CSS/color_value/hsl) notation. Converting from RGB to HSL is not a simple equation. Fortunately, browsers do it automatically, and shift-clicking on colors in browser developer tools provides conversion functionality. - -In addition to developer tools, many tools can convert RGB to HSL for you and provide both the RGB hexadecimal and CSS function syntax. A great example of a tool that converts colors for you is Tom Jewett's "[mini color selector](https://colortutorial.design/microColorsC.html)" with HSL, RGB, and Hex options for checking contrast in the browser. Note that developer tools color pickers and this tool all provide WCAG [color contrast](https://webaim.org/resources/contrastchecker/) values. - -![Color picker with HSL and RGB, with color contrast values.](microcolorsc.jpg) - -As noted earlier, the [CSS color module](/en-US/docs/Web/CSS/CSS_colors) includes adding additional colorspaces, including [`lch()`](/en-US/docs/Web/CSS/color_value/lch) and [`oklch()`](/en-US/docs/Web/CSS/color_value/oklch) functional color notation and the [`lab()`](/en-US/docs/Web/CSS/color_value/lab) and [`oklab()`](/en-US/docs/Web/CSS/color_value/oklab) color coordinate systems, which can specify any visible color. That said, sRGB is still the default and preferred colorspace for accessibility because of its ubiquity. - -Where accessibility is concerned, however, standards and guidelines are currently written predominantly using the sRGB color space, especially as it applies to color contrast ratios. - -> [!NOTE] -> Almost all systems used today to view Web content assume sRGB encoding. Unless it is known that another color space will be used to process and display the content, authors should evaluate using sRGB colorspace. If using other color spaces, apply the principles of [minimum contrast ratios](https://webaim.org/articles/contrast/#sc143). - -### Querying color values - -The {{domxref('Window.getComputedStyle()')}} method returns values using the RGB Decimal Reference scale or via `color(srgb...)`. For example, calling `Window.getComputedStyle()` on a `<div>` with `background-color: #ff0000` set on it returns the computed background color as `rgb(255 0 0)` — the RGB Decimal reference. However, when [using relative colors](/en-US/docs/Web/CSS/CSS_colors/Relative_colors) (for example `background-color: rgb(from blue 255 0 0)`), calling `Window.getComputedStyle()` returns the computed background color as `color(srgb 1 0 0)`. Being tied to computer hardware, `Window.getComputedStyle()` measures color in terms of RGB, not how the human eye perceives color. - -### Red / green color blindness - -Protanopia is a color vision deficiency in which the eye has no red cones; sRGB can still be perceived via green cones, though darker than normal vision. Both protan (red deficient) and deutan (green deficient) deficiencies cause difficulty distinguishing _between_ red and green. - -Developer tools can help simulate color vision differences right in your browser. For example, Firefox's Accessibility Inspector enables simulating protanopia, deuteranopia, tritanopia, achromatopsia, and contrast loss right in the accessibility panel. - -![Snippet of Firefox developer tools showing the simulate popup](simulate_color_differences.jpg) - -## Luminance and Contrast - -### Contrast - -The contrast between colors ("hues") is a critical component, but the use of color ("hues") alone is not enough to create accessible content. As mentioned before, any calculation of contrast must include luminance. - -In addition, the "shape" of the text itself will matter. Thin letters will be harder to read than thick ones; all typefaces need space to "breathe" for human perception. - -### Contrast and font size - -[WCAG contrast guidelines](/en-US/docs/Web/Accessibility/Understanding_WCAG/Perceivable#guideline_1.4_make_it_easier_for_users_to_see_and_hear_content_including_separating_foreground_from_background) define "large" text as text that is `18pt` (approximately `24px`) or larger when {{cssxref('font-weight')}} is `normal` and `14pt` (approximately `18.7px`) for `bold` text. Stating: - -_Text that is larger and has wider character strokes is easier to read at lower contrast. Therefore, the contrast requirement for larger text is lower. This allows authors to use a wider range of color choices for large text, which is helpful for the design of pages, particularly titles._ - -While larger text does not require as great color contrast with its background as smaller text, increasing font size is not a panacea. - -"Normal" print is usually considered 11.5pt to 12pt, equivalent to 16px on screen. While smaller font may be legible — a user can make out letters at \~70% accuracy — that is not readable. A 16px font size is generally readable for people with normal vision. Someone with 20/40 needs twice that, about a 31px font. This is why the WCAG guidelines require that users have the ability to zoom any text larger. - -While a text displayed too small is hard to read, so is a text that is too large. For users with 20/20 vision, with a text size greater than approximately 96px, reading speed decreases. Also, when there is a large disparity between the smallest and largest font size on a page, the larger text will become less readable if users enlarge the smaller text on the page, as most browsers zoom all text as the user zooms. - -In general, for accessibility purposes, the more contrast, the better. That changes with animation. "Safer" animation means images with less contrast, not more. For more on color contrast in animation, see [Three Flashes or Below Threshold Understanding SC 2.3.1](https://www.w3.org/TR/UNDERSTANDING-WCAG20/seizure-does-not-violate.html) - -Also, note that icons need sufficient contrast for perception. See [WCAG 2.1 technique G207](https://www.w3.org/WAI/WCAG21/Techniques/general/G207) - -### Luminance - -It is the difference in the luminance of a color that enables us to see the contrast. Relative luminance is defined in WCAG as "the relative brightness of any point in a colorspace, normalized to 0 for darkest black and 1 for lightest white." - -This statement is of course accurate, but may be confusing when used in reference to the RGB color space, which is an integer between 0 and 255. White has 100% relative luminance, black has 0% relative luminance (in most but not all literature). Interpreting for the W3C standard above, that would mean that white, normalized to 1, would have an RGB value of `rgb(255 255 255)` and black, normalized to 0, would have an RGB value of `rgb(0 0 0)`. Note that black and white can also be written as `rgb(100% 100% 100%)` and `rgb(0% 0% 0%)` respectively, which may be more intuitive. - -So, where do these numbers of 0 to 255 come from? Historically, graphics engines stored the color channels as a single byte, which means a range of integers between 0 and 255. - -The luminances of the primary colors are different. Yellow has a greater luminance than blue, for example. This was done by way of design, _to achieve white alignment of the monitor_, according to the NASA document, "[Luminance Contrast in Color Graphics](https://colorusage.arc.nasa.gov/design_lum_1.php)" - -A color contrast ratio is meaningless without its luminance component, and once luminance is established, the color contrast ratio can be established. - -Where human perception is concerned, a difference in luminance matters more than a color difference. This is important, as luminance contrast enables the development of content that even those with color blindness can see. With this understanding, luminance may be manipulated so that colors that are difficult to see because of their low luminance could be made more legible by placing these colors against another with contrasting luminance. An interesting study by NASA on the color blue, for example, noted that this color, which has low luminance, can be made legible if _care was taken to achieve adequate luminance contrast_ (From the article, [Designing with blue](https://colorusage.arc.nasa.gov/blue_2.php)) - -Calculations for relative luminance are not casual ones. Luckily, there are [online luminance and contrast checkers](https://www.siegemedia.com/contrast-ratio) available, and even instructions on how to [calculate relative luminance](https://www.w3.org/TR/WCAG21/#dfn-relative-luminance). - -## Perceiving color - -Color is our perception of the narrow band of visible light, from red through yellow and green to blue. Our sensitivity to these various hues of color are not equal. The light sensitive cells in our [eyes](https://www.verywellhealth.com/eye-cones-5088699), called cones, are tuned to perceive some colors more than others. About 65% of cones are _most_ sensitive to a yellow/green, but also respond to red (we'll call these "red" cones). 30% are green sensitive, and only [5% are blue sensitive](https://journals.plos.org/plosone/article?id=10.1371/journal.pone.0144891#sec001). While there are far fewer blue-sensitive cones than the other two types, these cones are very sensitive, which partially makes up for their smaller numbers. - -Deep, pure blue is perceived differently than other colors as blue cones do not contribute to luminance and we have far fewer blue cones than red or green. - -![On the left is a cone mosaic of standard vision, and on the right is that of someone with protanopia where they are missing the red cones.](conemosaics.jpg) - -On the left is the central cone mosaic of standard vision, and on the right is that of someone with protanopia, a form of color vision deficiency, where they are missing the red cones. (Illustration by Mark Fairchild of RIT, [Wikimedia Commons](https://commons.wikimedia.org/wiki/File:ConeMosaics.jpg)) - -The red and the green cones join together to create luminance, which we can think of as lightness/darkness without regard to hue. Separately, the red, green, and blue cones allow for standard vision to perceive millions of colors. For accessibility, it's important to know that our brain processes luminance separately from color (hue and colorfulness). - -Luminance provides for fine vision details, including differentiating edges and text. Hue and colorfulness carry a third of the detail of luminance. Image data compression takes advantage of this fact. As an example, [h.264 video codec](/en-US/docs/Web/Media/Guides/Formats/Video_codecs) samples color at a fourth of the resolution of the luminance. - -For accessibility, this means that luminance contrast is critically important for text. Color, as in hue and colorfulness, is important for _distinguishing_ items such as different lines on a map or bars in a graph. - -Another essential point to consider is the color or luminance that is surrounding a color. Colors appear differently depending on what is surrounding them. In the following image, both the yellow dots and the grey squares are the same sRGB color. Context-sensitive color perception makes them appear different; your brain's image processing adjusts the perception based on what it thinks is in shadow or not. - -![An image of a checkerboard, where identical colors look different if they are in shadow](yellowdotcheckershadow_dlyon.png) - -The yellow dots in this image are identical colors on your monitor, but they appear different due to context. (Image D.Lyon) - -Our contrast, lightness, and color perception are affected by the context of the nearby colors and other features of a design or image. This makes predicting contrast challenging. It is not as simple as a mathematical ratio between two colors. - -To summarize, color is as much about human physiology and perception in the brain as it is about measuring light from a computer screen. It's also important to understand that the ambient light environment affects the ability to perceive color and contrast. Light and its measurements are linear, but human vision and perception are not. - -## Adaptation - -Our eyes don't adapt equally, in the same way, going from light areas to dark ones and vice versa. This is due to the physiological ways our eyes are built. This affects the ability of a user to read text against a background. At least two kinds of adaptation take place: local adaptation and adaptation to an ambient environment. - -Local adaptation occurs right on the "page" a reader is looking at. For example, if you have blue text within a gray "highlighted" area, your eyes will perceive that exact blue text with a gray highlight differently if it is in a black {{HTMLElement("div")}}, or a white one. This is called _local_ adaptation. This difference in the ability to perceive the text is affected even though the room's ambient lighting does not change. - -The implication is that web developers who seek to improve the legibility of text against a background can take advantage of the principles of local adaptation. - -Dark adaptation to low luminance is slow. When you come in from outside, where the sun is bright, and walk into a dark room, you are experiencing dark adaptation. It can take a few minutes to adjust to this. - -Light adaptation is the reverse. Going from a dark room into bright sunlight is quicker but can also hurt. - -The implication is that web developers who seek to improve the legibility of text in which the ambient conditions of a room have changed can take advantage of the `AmbientLightSensor` interface and the [`prefers-contrast`](/en-US/docs/Web/CSS/@media/prefers-contrast) media query. - -## Saturation - -Saturation deserves a special mention in discussions about color ("hues") and accessibility. Generally speaking, most focus is on luminance when attempting to ensure enough contrast between text and its background or evaluating the possibility of inducing seizures in those sensitive to photosensitive seizures. One aspect of color ("hues"), independent of luminance, deserves special attention as it applies to accessibility: the concept of saturation. This is due to its ability to cause seizures in those susceptible to photosensitive seizures, regardless of color's luminance. As discussed in [the particular case of red](#the_special_case_of_red), -the [Epilepsy Foundation](https://citeseerx.ist.psu.edu/viewdoc/download?doi=10.1.1.532.7063&rep=rep1&type=pdf) noted that, _irrespective of luminance, a transition to or from a saturated red is also considered a risk_. - -Saturation is sometimes described as the "purity" or "intensity" of a color. Although these are good definitions for "pigments" in an artist's paint set, they are not as accurate as color definitions from a computer screen. - -When it comes to color on a monitor, saturated colors are of a particular wavelength. While the definition of saturation for each color space may differ, saturation is readily measured. The key is to know which color space you are working in and be ready to convert it if necessary. - -The color spaces most frequently considered when discussing photosensitivity are the RGB, HSL, and HSV, also known as HSB, color spaces. The HSV color space, which stands for _hue_, _saturation_, and _value_, and the synonym HSB, which stands for _hue_, _saturation_, and _brightness_, are represented in CSS as [`hwb()`](/en-US/docs/Web/CSS/color_value/hwb) for _hue_, _whiteness_, and _blackness_. - -It's important to know what color space you're working with. For example, saturated colors have a lightness of `0.5` in HSL, while in HWB, they have a value `1`. Saturation in the RGB color space is usually indicated by an RGB value of `255` or `100%` for the color in question. For example, a saturated red of hex value `#ff0000` has an RGB value of `rgb(255 0 0)` and an HSL value of `hsl(0 100% 50%)`. A different saturated red with a hex value of `#ff3300` has an RGB value of `rgb(255 51 0)` and an HSL value of `hsl(12 100% 50%)`. Both are "saturated" reds. They are two different "hues" but are both considered to be a saturated color. - -Saturation is not brightness. Brightness refers to how much white or black is mixed in with a color. One can decrease saturation by adding white, black, or gray to the color; to take the example further, brightness can be increased by adding white, reducing saturation. A typical example is to add white to red to get the color pink. Pink is considered a desaturated red. - -### Saturation and luminance - -There is a loss of saturation at the extremes of luminance and the extremes of black and white. In NASA's [effect of luminance on saturation](https://colorusage.arc.nasa.gov/design_lum_1.php), they point out that there is a loss of saturation at low luminances, and also, "…the loss of saturation at high luminances–the colors converge on white." - -## Color combinations - -Contrast alone is not enough when it comes to accessibility considerations. In the case of animation, certain color combinations are more likely to cause photosensitive seizures to those who are susceptible to them than others. For example, alternating flashes between red and blue is more problematic than alternating flashes between green and blue. It has been theorized that this is because the "red" sensitive cones of our eyes, which tend to cluster around the fovea (near the center), are physically located at a different location than the "blue" sensitive cones of our eyes, which are located away from the fovea and towards the rims. The electrical signals from the eye to the brain have much to resolve between them as the information is processed in our brains. - -Some colors more likely to [cause epileptic seizures](https://www.epilepsy.com/sites/default/files/2022-10/Epilepsia_2022_fisher_visually_sensitive_seizures.pdf). Complexities underlying brain dynamics can be modulated by some color combinations more than the others. For example, red-blue flickering stimulus causes larger cortical excitation than red-green or blue-green stimulus. - -Certain color combinations can be very problematic on a computer monitor or mobile device, and some color combinations can interfere with some impairments. The combination of red/blue is one such example. - -- Never rely on hue alone for differentiating details. Adequate luminance contrast is required. -- The green in a monitor makes up the vast majority of luminance (light), so it will usually be a significant part of the lighter colors. - -### Working with blue - -Some people cannot differentiate between all colors. Some colors, such as pure blue, are low in luminance. Colors that are low in luminance should be the darker of contrasting colors. Blue is also very low in resolution. There are far fewer blue cones, and they are scattered in our peripheral vision and not present in our central vision. The human eye sees blue at a lower resolution than green and red. - -This leads to some blue color use guidelines: - -- Pure blues should typically be the darkest of two colors. -- When using blue as the lighter of the two colors, add green to increase contrast and improve readability. - -The nature of blue light causes it to focus at a different location on the retina than red, so a pure red and a pure blue color that are immediately adjacent and touching may "shimmer" when next to each other. - -## The special case of red - -Not all colors ("hue") are processed similarly by our brains. Human physiology and psychology are affected by the color red, generally speaking, in ways different from that of other colors. We respond physiologically as well as psychologically to colors. For example, it has been demonstrated that [some colors are more likely to cause epileptic fits than others](https://www.sciencedaily.com/releases/2009/09/090925092858.htm). Some devices offer a ["grayscale" setting as an accessibility option](https://ask.metafilter.com/312049/What-is-the-grayscale-setting-for-in-accessibility-options)" which can help people who are photo-sensitive. To mimic the grayscale setting, use the CSS {{cssxref("filter")}} property with a [`grayscale()`](/en-US/docs/Web/CSS/filter-function/grayscale) or [`saturate()`](/en-US/docs/Web/CSS/filter-function/saturate) [`<filter-function>`](/en-US/docs/Web/CSS/filter-function). - -### Saturated red - -"Saturated Red" is a special, dangerous case, and there are special tests for it. - -The concept of color saturation is a difficult one to understand when only looking at numbers and terminology, so consider looking at the image below to illustrate the concept of saturation in a color: - -![Red Saturation from Wikimedia Commons svg saved as png Attribution: Datumizer [CC0]](320px-red_saturations.svg.png) - -The same "color" proceeds from least saturated on the left-hand side to most saturated on the right-hand side. - -_More than one "red" color may be considered a "saturated" red._ For example, the color `#990000` at `hsl(0 100% 30%)` is fully saturated but is less bright than the colors described above. Similarly, the color `#8b0000` also has a saturation of 100%. - -Not all saturated reds may be represented well in the RGB spectrum or other spectrums commonly used in web development. According to Wikipedia's page on "Shades of Red", the color "Carmine" is a saturated red which, in its pigment form, mostly contains red light with wavelengths longer than 600nm; the article makes the special note that "Carmine" is close to the extreme spectrum. This places it far beyond standard gamuts (RGB and CMYK), and its given RGB value is a poor approximation only." - -### Saturated red flashing - -In addition to a red environment affecting the cognitive function of those with traumatic brain injury, color in the red spectrum wavelength requires special attention and tests. - -Gregg Vanderheiden, when testing the _Photosensitive epilepsy analysis tool_, noted seizure rates were much higher than expected. They found that we are much more sensitive to saturated red flashing. (See the video, [The Photosensitive epilepsy analysis tool](https://www.pbs.org/video/university-place-the-photosensitive-epilepsy-analysis-tool-ep-429/).) - -### Flashing and seizures - -Continuous flashing brighter/darker at rates higher than three flashes per second has been shown to induce photic seizures in some people. It has also been found that specific, very regular, high-contrast patterns, such as parallel white and black stripes, can also induce seizures. - -The Epilepsy Foundation of America researched [photic- and pattern-induced seizures](https://www.researchgate.net/publication/7615895_Photic-_and_Pattern-induced_Seizures_A_Review_for_the_Epilepsy_Foundation_of_America_Working_Group). The study resulted in several fundamental guidelines: - -1. Single, double, or triple flashes in one second are acceptable, but a sequence of flashes is not recommended when more than three flashes happen within one second. - -2. When displaying light and dark stripes, the pattern should display no more than five light–dark pairs of stripes, if the stripes change direction, oscillate, flash, or reverse in contrast or eight light–dark pairs of stripes, if the pattern is unchanging or continuously and smoothly drifting in one direction. - -The consensus recommendations are in this brief paper, [Photic- and Pattern-induced Seizures: Expert Consensus of the Epilepsy Foundation of America](https://onlinelibrary.wiley.com/doi/epdf/10.1111/j.1528-1167.2005.31405.x). Some additional insights are available in this UK paper covering [guidelines for preventing seizures.](https://citeseerx.ist.psu.edu/viewdoc/download?doi=10.1.1.106.9473&rep=rep1&type=pdf). - -## Psychophysical aspects of color - -Color as in hues and saturation can affect our mood, and enhance — or de-enhance — our interactive experiences. - -### Examples of color's effect beyond vision - -- **Color can be culturally dependent:** [A Cross-Cultural Study of the Affective Meanings of Color](https://journals.sagepub.com/doi/10.1177/002202217300400201) -- **Color affects our emotions:** [Color and emotion: effects of hue, saturation, and brightness](https://pubmed.ncbi.nlm.nih.gov/28612080/) -- **Higher contrasts can also have a positive affect on our emotions:** [Emotion Variation from Controlling Contrast of Visual Contents through EEG-Based Deep Emotion Recognition](https://pubmed.ncbi.nlm.nih.gov/32823741/) -- **Some colors can affect our perception of time:** [Color and time perception: Evidence for temporal overestimation of blue stimuli](https://pubmed.ncbi.nlm.nih.gov/29374198/) -- **Blue also has a significant effect on brightness and glare:** [Blue and glare & brightness](https://pubmed.ncbi.nlm.nih.gov/31288107/) -- **Red tinted glasses can provide increased happiness or joy:** [Looking Through "Rose-Tinted" Glasses: The Influence of Tint on Visual Affective Processing](https://pubmed.ncbi.nlm.nih.gov/31244627/) -- **Red is well known to have significant effects on our behavior:** [How the Color Red Influences Our Behavior](https://www.scientificamerican.com/article/how-the-color-red-influences-our-behavior/), Scientific American, S. Martinez-Conde, Stephen L. Macknik -- **Red Environment:** Studies have shown that for those who suffer Traumatic Brain Injury, [cognitive function is reduced in a red environment](https://pubmed.ncbi.nlm.nih.gov/20649469/). - -## See also - -- [Accessibility](/en-US/docs/Web/Accessibility) -- [Accessibility learning path](/en-US/docs/Learn_web_development/Core/Accessibility) -- CSS [`color`](/en-US/docs/Web/CSS/color) property -- [`<color>`](/en-US/docs/Web/CSS/color_value) data type -- [Web accessibility for seizures and physical reactions](/en-US/docs/Web/Accessibility/Seizure_disorders) -- [How the Color Red Influences Our Behavior](https://www.scientificamerican.com/article/how-the-color-red-influences-our-behavior/) Scientific American By Susana Martinez-Conde, Stephen L. Macknik on November 1, 2014 -- [Red Desaturation](https://www.smartoptometry.app/red-desaturation/) The human eye is so sensitively "tuned" to red, that ophthalmologists set up a test using it, assessing the integrity of the optic nerve. -- [Photic- and pattern-induced seizures: expert consensus of the Epilepsy Foundation of America Working Group](https://citeseerx.ist.psu.edu/viewdoc/download?doi=10.1.1.532.7063&rep=rep1&type=pdf) diff --git a/files/en-us/web/accessibility/understanding_wcag/index.md b/files/en-us/web/accessibility/understanding_wcag/index.md deleted file mode 100644 index 20edf432d610493..000000000000000 --- a/files/en-us/web/accessibility/understanding_wcag/index.md +++ /dev/null @@ -1,44 +0,0 @@ ---- -title: Understanding the Web Content Accessibility Guidelines -slug: Web/Accessibility/Understanding_WCAG -page-type: guide ---- - -{{AccessibilitySidebar}} - -This set of articles provides quick explanations to help you understand the steps that need to be taken to conform to the recommendations outlined in the {{glossary("WCAG", "Web Content Accessibility Guidelines")}} (WCAG). - -The WCAG guidelines are a set of recommendations for making web content more accessible developed by W3C's {{Glossary("WAI")}}, primarily for people with disabilities — but also for all user agents, including some highly limited devices or services, such as digital assistants. - -WCAG 2.2 is the most recent version of the guidelines with WCAG 2.1 and 2.0 also widely used. WCAG 3.0 is the working draft. -Newer versions of WCAG are not meant to supersede previous versions, but WAI recommends using the most recent version to ensure the best possible accessibility for your website. - -## The four principles - -WCAG is broadly broken down into four principles — major things that web content **must be** to be considered accessible (see [Understanding the Four Principles of Accessibility](https://www.w3.org/WAI/WCAG22/Understanding/intro#understanding-the-four-principles-of-accessibility) for the WCAG definitions). - -Each of the links below will take you to pages that further expand on these areas, giving you practical advice on how to write your web content so it conforms to the success criteria outlined in the WCAG 2 four guiding principles. - -- [Perceivable](/en-US/docs/Web/Accessibility/Understanding_WCAG/Perceivable): Users must be able to perceive it in some way, using one or more of their senses. -- [Operable](/en-US/docs/Web/Accessibility/Understanding_WCAG/Operable): Users must be able to control UI elements (e.g. buttons must be clickable in some way — mouse, keyboard, voice command, etc.). -- [Understandable](/en-US/docs/Web/Accessibility/Understanding_WCAG/Understandable): The content must be understandable to its users. -- [Robust](/en-US/docs/Web/Accessibility/Understanding_WCAG/Robust): The content must be developed using well-adopted web standards that will work across different browsers, now and in the future. - -We also included two additional WCAG resources focused on making sites [keyboard accessible](/en-US/docs/Web/Accessibility/Understanding_WCAG/Keyboard) and provided descriptive names or labels with [text labels and names](/en-US/docs/Web/Accessibility/Understanding_WCAG/Text_labels_and_names). - -## Legal standing - -This introductory documentation is intended to provide practical information to help you build better, more accessible websites. However, we are not lawyers, and none of this constitutes legal advice. If you are worried about the legal implications of web accessibility, we recommend that you check the specific legislation governing accessibility for the web and public resources in your country or locale and seek the advice of a qualified lawyer. - -[What is accessibility?](/en-US/docs/Learn_web_development/Core/Accessibility/What_is_accessibility) and particularity the [Accessibility guidelines and the law](/en-US/docs/Learn_web_development/Core/Accessibility/What_is_accessibility#accessibility_guidelines_and_the_law) section provide more related information. - -## See also - -- [WCAG: Perceivable](/en-US/docs/Web/Accessibility/Understanding_WCAG/Perceivable) -- [WCAG: Operable](/en-US/docs/Web/Accessibility/Understanding_WCAG/Operable) -- [WCAG: Understandable](/en-US/docs/Web/Accessibility/Understanding_WCAG/Understandable) -- [WCAG: Robust](/en-US/docs/Web/Accessibility/Understanding_WCAG/Robust) -- [WCAG text labels and names](/en-US/docs/Web/Accessibility/Understanding_WCAG/Text_labels_and_names) -- [WCAG keyboard accessibility](/en-US/docs/Web/Accessibility/Understanding_WCAG/Keyboard) -- [WCAG Overview](https://www.w3.org/WAI/standards-guidelines/wcag/) -- [WCAG 2.2](https://www.w3.org/TR/WCAG22/) diff --git a/files/en-us/web/accessibility/understanding_wcag/keyboard/index.md b/files/en-us/web/accessibility/understanding_wcag/keyboard/index.md deleted file mode 100644 index eca8d1e2037dca8..000000000000000 --- a/files/en-us/web/accessibility/understanding_wcag/keyboard/index.md +++ /dev/null @@ -1,77 +0,0 @@ ---- -title: Keyboard -slug: Web/Accessibility/Understanding_WCAG/Keyboard -page-type: guide ---- - -{{AccessibilitySidebar}} - -To be fully accessible, a web page must be operable by someone using only a keyboard to access and control it. This includes users of screen readers, but can also include users who have trouble operating a pointing device such as a mouse or trackball, or whose mouse is not working at the moment, or who prefer to use a keyboard for input whenever possible. - -## Focusable elements should have interactive semantics - -If an element can be focused using the keyboard, then it should be interactive; that is, the user should be able to do something to it and produce a change of some kind (for example, activating a link or changing an option). - -> [!NOTE] -> One important exception to this rule is if the element has `role="document"` applied to it, **inside** an interactive context (such as `role="application"`). In such a case, focusing the nested document is the only way of returning assistive technology to a non-interactive state (often called "browse mode"). - -Most interactive elements are focusable by default; you can make an element focusable by adding a `tabindex=0` attribute value to it. However, you should only add `tabindex` if you have also made the element interactive, for example, by defining appropriate event handlers keyboard events. - -### See also - -- [tabindex](/en-US/docs/Web/HTML/Global_attributes/tabindex) global HTML attribute -- Element: [keydown event](/en-US/docs/Web/API/Element/keydown_event) -- Element: [keyup event](/en-US/docs/Web/API/Element/keyup_event) - -## Avoid using `tabindex` attribute greater than zero - -The `tabindex` attribute indicates that an element is focusable using the keyboard. A value of zero indicates that the element is part of the default focus order, which is based on the ordering of elements in the HTML document. A positive value puts the element ahead of those in the default ordering; elements with positive values are focused in the order of their `tabindex` values (1, then 2, then 3, etc.). - -This creates confusion for keyboard-only users when the focus order differs from the logical order of the page. A better strategy is to structure the HTML document so that focusable elements are in a logical order, without the need to re-order them with positive `tabindex` values. - -### See also - -- [tabindex](/en-US/docs/Web/HTML/Global_attributes/tabindex) global HTML attribute -- [Understanding focus order](https://www.w3.org/WAI/WCAG21/Understanding/focus-order.html) -- [Don't use tabindex greater than 0](https://adrianroselli.com/2014/11/dont-use-tabindex-greater-than-0.html) - -## Clickable elements must be focusable and should have interactive semantics - -If an element can be clicked with a pointing device, such as a mouse, then it should also be focusable using the keyboard, and the user should be able to do something by interacting with it. - -An element is clickable if it has an `onclick` event handler defined. You can make it focusable by adding a `tabindex=0` attribute value to it. You can make it operable with the keyboard by defining an `onkeydown` event handler; in most cases, the action taken by event handler should be the same for both types of events. - -### See also - -- [tabindex](/en-US/docs/Web/HTML/Global_attributes/tabindex) global HTML attribute -- Element: [keydown event](/en-US/docs/Web/API/Element/keydown_event) -- Element: [keyup event](/en-US/docs/Web/API/Element/keyup_event) - -## Interactive elements must be able to be activated using a keyboard - -If the user can interact with an element using touch or a pointing device, then the element should also support interacting using the keyboard. That is, if you have defined event handlers for touch or click events, you should also define them for keyboard events. The keyboard event handlers should enable effectively the same interaction as the touch or click handlers. - -### See also - -- Element: [keydown event](/en-US/docs/Web/API/Element/keydown_event) -- Element: [keyup event](/en-US/docs/Web/API/Element/keyup_event) - -## Interactive elements must be focusable - -If the user can interact with an element (for example, using touch or a pointing device), then it should be focusable using the keyboard. You can make it focusable by adding a `tabindex=0` attribute value to it. That will add the element to the list of elements that can be focused by pressing the <kbd>Tab</kbd> key, in the sequence of such elements as defined in the HTML document. - -### See also - -- [tabindex](/en-US/docs/Web/HTML/Global_attributes/tabindex) global HTML attribute - -## Focusable element must have focus styling - -Any element that can receive keyboard focus should have visible styling that indicates when the element is focused. You can do this with the [`:focus`](/en-US/docs/Web/CSS/:focus) and [`:focus-visible`](/en-US/docs/Web/CSS/:focus-visible) CSS pseudo-classes. - -Standard focusable elements such as links and input fields are given special styling by the browser by default, so you might not need to specify focus styling for such elements, unless you want the focus styling to be more distinctive. - -If you create your own focusable components, be sure that you also define focus styling for them. - -### See also - -- [Using CSS to change the presentation of a UI component when it receives focus](https://www.w3.org/WAI/WCAG21/Techniques/css/C15.html) diff --git a/files/en-us/web/accessibility/understanding_wcag/operable/index.md b/files/en-us/web/accessibility/understanding_wcag/operable/index.md deleted file mode 100644 index 282e95f3a6ce9e1..000000000000000 --- a/files/en-us/web/accessibility/understanding_wcag/operable/index.md +++ /dev/null @@ -1,579 +0,0 @@ ---- -title: Operable -slug: Web/Accessibility/Understanding_WCAG/Operable -page-type: guide ---- - -{{AccessibilitySidebar}} - -This article provides practical advice on how to write your web content so that it conforms to the success criteria outlined in the **Operable** principle of the Web Content Accessibility Guidelines (WCAG) 2.0 and 2.1. Operable states that user interface components and navigation must be operable. - -> [!NOTE] -> To read the W3C definitions for Operable and its guidelines and success criteria, see [Principle 2: Operable — User interface components and navigation must be operable.](https://www.w3.org/TR/WCAG21/#operable) - -## Guideline 2.1 — Keyboard Accessible: Make all functionality available from a keyboard - -This guideline covers the necessity of making core website functionality available via a keyboard in addition to other means (e.g. mouse), so that users that rely on keyboard controls can access them. - -<table class="standard-table"> - <thead> - <tr> - <th scope="col">Success criteria</th> - <th scope="col">How to conform to the criteria</th> - <th scope="col">Practical resource</th> - </tr> - </thead> - <tbody> - <tr> - <td>2.1.1 Keyboard (A)</td> - <td> - All functionality should be accessible using keyboard controls, unless - it cannot be done using the keyboard (e.g. freehand drawing). Built-in - controls should be used where possible (e.g. tabbing through form - controls), and you should only build in custom functionality where - needed. - </td> - <td> - See - <a href="/en-US/docs/Learn_web_development/Core/Accessibility/HTML#ui_controls" - >UI controls</a - > - and - <a - href="/en-US/docs/Learn_web_development/Core/Accessibility/HTML#building_keyboard_accessibility_back_in" - >Building keyboard accessibility back in</a - > - </td> - </tr> - <tr> - <td>2.1.2 No keyboard trap (A)</td> - <td> - <p> - When entering a section of functionality using the keyboard, you - should be able to get out of that section again using <em>only</em> the - keyboard. For example, if you press <kbd>Enter</kbd>/<kbd>Return</kbd> - on a focused button to open an options window, you should be able to - close that window again and return to the main content using the - keyboard. - </p> - <p> - This is very important so that keyboard users do not get trapped on - specific sections of your apps. - </p> - </td> - <td></td> - </tr> - <tr> - <td>2.1.3 Keyboard — all functionality (AAA)</td> - <td> - This is a further step beyond criterion 2.1.1. To achieve AAA - conformance, all functionality should be accessible using keyboard - controls — with no exceptions. - </td> - <td> - See - <a href="/en-US/docs/Learn_web_development/Core/Accessibility/HTML#ui_controls" - >UI controls</a - > - and - <a - href="/en-US/docs/Learn_web_development/Core/Accessibility/HTML#building_keyboard_accessibility_back_in" - >Building keyboard accessibility back in</a - > - </td> - </tr> - <tr> - <td> - 2.1.4 Character Key Shortcuts (A) - <em - ><a href="https://www.w3.org/TR/WCAG21/#new-features-in-wcag-2-1" - >added in 2.1</a - ></em - > - </td> - <td> - If a single character key shortcut exists, then at least one of the - following is true: single character key shortcuts can be turned off, - remapped or are only active when the relevant user interface component - is in focus. - </td> - <td> - <a - href="https://www.w3.org/WAI/WCAG21/Understanding/character-key-shortcuts.html" - >Understanding Character Key Shortcuts</a - > - </td> - </tr> - </tbody> -</table> - -> [!NOTE] -> Also see the WCAG description for [Guideline 2.1 Keyboard Accessible: Make all functionality available from a keyboard](https://www.w3.org/TR/WCAG21/#keyboard-accessible). - -## Guideline 2.2 — Enough Time: Provide users enough time to read and use content - -This guideline covers situations in which functionality may have a time limit. For example, purchases sometimes need to be completed within a time limit for security reasons. - -<table class="standard-table"> - <thead> - <tr> - <th scope="col">Success criteria</th> - <th scope="col">How to conform to the criteria</th> - <th scope="col">Practical resource</th> - </tr> - </thead> - <tbody> - <tr> - <td>2.2.1 Timing is adjustable (A)</td> - <td> - <p> - For functionality with time limits (e.g. completing a hotel or flight - booking often has a time limit), the user should be given controls to - allow them to adjust, extend or turn off the time limit. - </p> - <p> - Exceptions to this are activities with time limits longer than 20 - hours, real time events (e.g. live multiplayer games), and any other - activity that requires a time limit and would be invalidated if it - were turned off. - </p> - </td> - <td></td> - </tr> - <tr> - <td>2.2.2 Pausing, stopping, hiding (A)</td> - <td> - <p> - For moving/blinking content that starts automatically, lasts longer - than 5 seconds, and is shown alongside other content, controls should - be provided to pause, stop, or hide it. This does not apply to - moving/blinking content that is essential to the experience. Examples - include scrolling text and videos. - </p> - <p> - For auto-updating information that starts automatically and is shown - alongside other content, controls should be provided to pause, stop, - or hide it, or to control the frequency of updates. This does not - apply to auto-updating content that is essential to the experience. - Examples include carousels or rotating announcements. - </p> - </td> - <td></td> - </tr> - <tr> - <td>2.2.3 No time limits (AAA)</td> - <td> - This builds on criteria 2.2.1, stating that content that wants to pass - AAA conformance should have no time limits. - </td> - <td></td> - </tr> - <tr> - <td>2.2.4 Suppress interruptions (AAA)</td> - <td> - Any interruptions such as alerts or interstitial adverts should have - functionality available to suppress or postpone them, unless it is an - emergency alert. - </td> - <td></td> - </tr> - <tr> - <td>2.2.5 Re-authenticating (AAA)</td> - <td> - If an authentication session expires during usage of a web app, the user - can re-authenticate and continue their usage without losing any data. - </td> - <td></td> - </tr> - <tr> - <td> - 2.2.6 Timeouts (AAA) - <em - ><a href="https://www.w3.org/TR/WCAG21/#new-features-in-wcag-2-1" - >added in 2.1</a - ></em - > - </td> - <td> - <p> - If there is a timeout (caused by user inactivity) warn users at the - start of a process so they will not be surprised that a timeout exists - (or only allow the timeout to occur after 20 hours of inactivity). - </p> - </td> - <td> - <a href="https://www.w3.org/WAI/WCAG21/Understanding/timeouts.html" - >Understanding Timeouts</a - > - </td> - </tr> - </tbody> -</table> - -> [!NOTE] -> Also see the WCAG description for [Guideline 2.2 Enough Time: Provide users enough time to read and use content](https://www.w3.org/TR/WCAG21/#enough-time). - -## Guideline 2.3 — Seizures and Physical Reactions: Do not design content in a way that is known to cause seizures or physical reactions - -This refers to content that, if not changed, could cause seizures in users with conditions such as epilepsy OR could cause physical reactions (like dizziness) for users with conditions such as vestibular disorders. - -<table> - <thead> - <tr> - <th scope="col">Success criteria</th> - <th scope="col">How to conform to the criteria</th> - <th scope="col">Practical resource</th> - </tr> - </thead> - <tbody> - <tr> - <td>2.3.1 Three flashes, or below threshold (A)</td> - <td>Content doesn't contain any aspect that Flashes more than three times per second, or flashing content is below acceptable <a href="https://www.w3.org/TR/WCAG20/#general-thresholddef">flash and red flash thresholds</a>.</td> - <td></td> - </tr> - <tr> - <td>2.3.2 Three flashes (AAA)</td> - <td>Content doesn't contain any aspect that Flashes more than three times per second.</td> - <td></td> - </tr> - <tr> - <td>2.3.3 Animations from Interactions (AAA) <em><a href="https://www.w3.org/TR/WCAG21/#new-features-in-wcag-2-1">added in 2.1</a></em></td> - <td>Allow users to disable animations from interactions (unless the animation is essential).</td> - <td><a href="https://www.w3.org/TR/WCAG21/#animation-from-interactions">Understanding Animations from Interactions</a></td> - </tr> - </tbody> -</table> - -> [!NOTE] -> Also see the WCAG description for [Guideline 2.3 Seizures and Physical Reactions: Do not design content in a way that is known to cause seizures or physical reactions.](https://www.w3.org/TR/WCAG21/#seizures-and-physical-reactions) - -## Guideline 2.4 — Navigable: Provide ways to help users navigate, find content, and determine where they are - -The conformance criteria under this guideline relate to ways in which users can be expected to orientate themselves, and find the content and functionality they are looking for on the current page or other pages of the site. - -<table class="standard-table"> - <thead> - <tr> - <th scope="col">Success criteria</th> - <th scope="col">How to conform to the criteria</th> - <th scope="col">Practical resource</th> - </tr> - </thead> - <tbody> - <tr> - <td>2.4.1 Bypass blocks (A)</td> - <td> - <p> - A mechanism should be provided that allows the user to skip straight - to the main content or functionality available on the page, past the - repeated features (such as the company logo or navigation). This is - often achieved using "skip links" — links put at the top of the page - source that link to the main content and are hidden by CSS. - </p> - <p> - If a proper structure of headings and semantic containers is provided - to navigate with (for example {{htmlelement("section")}}, - {{htmlelement("aside")}}, etc.), then an added "skip link" is - not needed. - </p> - </td> - <td><em>Need to add a section on "skip links".</em></td> - </tr> - <tr> - <td>2.4.2 Include page title (A)</td> - <td> - Each web page should include an informative - {{htmlelement("title")}}, the content of which describes the - page's content/purpose. - </td> - <td> - See - <a - href="/en-US/docs/Learn_web_development/Core/Structuring_content/Webpage_metadata#adding_a_title" - >Adding a title</a - >. - </td> - </tr> - <tr> - <td>2.4.3 Logical focus order (A)</td> - <td> - The "tabbing order" of focusable page features (e.g. links, buttons, - form inputs) makes logical sense, meaning that the page is still usable - by non-sighted/keyboard users. - </td> - <td> - See - <a href="/en-US/docs/Learn_web_development/Core/Accessibility/HTML#ui_controls" - >UI controls</a - > - for general advice on tabbing to controls. If you need to place elements - in an unusual layout, it is better to make sure the source order is - sensible, then use CSS features like - <a href="/en-US/docs/Learn_web_development/Core/CSS_layout/Positioning">positioning</a> - to handle the layout. - </td> - </tr> - <tr> - <td>2.4.4 Link purpose (in context) (A)</td> - <td> - The purpose/destination of a link can be determined from the link text, - or from its surroundings (e.g. the surrounding text). Exceptions are - where the link purpose is ambiguous to <em>all</em> users (see - <a href="https://www.w3.org/TR/WCAG20/#ambiguouslinkdef" - >ambiguous to users in general</a - > - for a useful explanation of this). - </td> - <td> - See - <a href="/en-US/docs/Learn_web_development/Core/Accessibility/HTML#meaningful_text_labels" - >Meaningful text labels</a - >. Also note that you should minimize instances where multiple copies of - the same text are linked to different places. This can cause problems - for screen reader users, who will often bring up a list of the links out - of context — several links all labelled "click here", "click here", - "click here" would be confusing. - </td> - </tr> - <tr> - <td>2.4.5 Multiple navigation mechanisms (AA)</td> - <td> - <p> - You should provide at least two general navigation mechanisms to find - pages on your website, for example navigation menu, breadcrumb trail, - site search, site map, list of related links, etc. - </p> - <p> - The only exception to this is where a page is one step in a process, - so should only logically have links to the previous and next steps. - </p> - </td> - <td> - Most of these mechanisms can be created using simple HTML features, for - example see - <a - href="/en-US/docs/Learn_web_development/Extensions/Forms/HTML5_input_types#search_field" - >Search field</a - >, - <a - href="/en-US/docs/Learn_web_development/Core/Structuring_content/Creating_links#active_learning_creating_a_navigation_menu" - >Creating a navigation menu</a - >, - <a - href="/en-US/docs/Learn_web_development/Core/Text_styling/Styling_links#styling_links_as_buttons" - >Styling links as buttons</a - >. - </td> - </tr> - <tr> - <td>2.4.6 Headings and labels (AA)</td> - <td> - Heading (e.g. {{htmlelement("Heading_Elements", "&lt;h2&gt;")}}) and - {{htmlelement("label")}} elements clearly describe the purpose - of the content and form elements they are supposed to be describing. - </td> - <td> - <p> - See - <a href="/en-US/docs/Learn_web_development/Core/Accessibility/HTML#ui_controls" - >UI controls</a - >, - <a href="/en-US/docs/Learn_web_development/Core/Accessibility/HTML#meaningful_text_labels" - >Meaningful text labels</a - >, - <a - href="/en-US/docs/Learn_web_development/Core/Structuring_content/Headings_and_paragraphs" - >The basics of headings and paragraphs</a - >, - <a - href="/en-US/docs/Learn_web_development/Extensions/Forms/How_to_structure_a_web_form#the_label_element" - >The &#x3C;label> element</a - >. - </p> - <p> - Note that you should avoid duplicating headings or labels (e.g. - multiple instances of "Further information"), unless the structure - allows you to differentiate between them easily. - </p> - </td> - </tr> - <tr> - <td>2.4.7 Visible focus for focusable elements (AA)</td> - <td> - When tabbing through focusable elements such as links or form inputs, - there should be a visual indicator to show you which element currently - has focus. This is usually a dotted or blue outline by default - (depending on browser, platform, etc.), but this can be overridden by - CSS. - </td> - <td> - See - <a - href="/en-US/docs/Learn_web_development/Core/Accessibility/HTML#ui_controls" - >UI controls</a - >. - </td> - </tr> - <tr> - <td>2.4.8 Location within site (AAA)</td> - <td> - When on a page inside a complex site or set of steps, the user should be - given an indicator of where they are in the site, for example a - breadcrumb trail, sitemap or text such as "Form page 2 of 10". - </td> - <td></td> - </tr> - <tr> - <td>2.4.9 Link purpose (link only) (AAA)</td> - <td> - This criterion builds on 2.4.4, stating that to conform to AAA, the - purpose/destination of a link should be determinable from the link text - alone, even if out of context. - </td> - <td> - See - <a href="/en-US/docs/Learn_web_development/Core/Accessibility/HTML#meaningful_text_labels" - >Meaningful text labels</a - >. Also note that you should minimize instances where multiple copies of - the same text are linked to different places. This can cause problems - for screen reader users, who will often bring up a list of the links out - of context — several links all labelled "click here", "click here", - "click here" would be confusing. - </td> - </tr> - <tr> - <td>2.4.10 Section headings (AAA)</td> - <td> - <p> - As well as creating a useful document structure, headings should also - accurately describe and break up content areas into logical sections. - </p> - <p> - Note that this criterion refers to headings and titles in general web - content (e.g. headings within text content). Headings and titles for - user interfaces are a special case covered in criterion 4.1.2. - </p> - </td> - <td> - <p> - See - <a - href="/en-US/docs/Learn_web_development/Core/Structuring_content/Headings_and_paragraphs" - >The basics of headings and paragraphs</a - >. - </p> - </td> - </tr> - <tr> - <td> 2.4.11 Focus not obscured (Minimum) (AA)</td> - <td> - <p> When a user interface component receives keyboard focus, the component is not entirely hidden due to containing author-created content.</p> - <p> <strong>Note:</strong> If the interface's content can be repositioned by the user, then only the initial position of the user-movable content is considered for testing to conform to this standard. Also, content opened by the user may obscure the component receiving focus. Furthermore, if the user can reveal the focused component without changing keyboard focus, the component with focus is not considered hidden for conformance and testing purposes.</p> - </td> - <td> - <p> Check out <a href="https://www.w3.org/WAI/WCAG22/Understanding/focus-not-obscured-minimum">Understanding focus not obscured (Minimum)</a> to learn more about this standard.</p> - </td> - </tr> - <tr> - <td> 2.4.12 Focus not obscured (Enhanced) (AAA) </td> - <td> - <p> Follows the rules as 2.4.11 except when a user interface component receives focus, no part of the component can be hidden by author-created content. If the interface is configurable, only the initial positions of user-movable content are considered for testing and meeting of this standard.</p> - </td> - <td> - <p> Check out <a href="https://www.w3.org/WAI/WCAG22/Understanding/focus-not-obscured-enhanced">Understanding focus not obscured (Enhanced) (Level AAA)</a> to learn more about this standard.</p> </td> - </td> - </tr> -<tr> - <td> 2.4.13 Focus appearance (AAA)</td> - <td> - <p>When the keyboard focus indicator is visible, the area of the focus indicator meets all the following:</p> - <ul> - <li>Must be at least as large as the area of a <code>2px</code> thick perimeter of the unfocused component or sub-component, which includes component's content, border, and background, excluding outer shadows or glow effects.</li> - <li>Needs to have a contrast ratio of at least 3:1 between the same pixels in the focused and unfocused states</li> - </ul> - <p> The exceptions to this are:</p> - <ul> - <li>The focus indicator is determined by the user and cannot be adjusted by the author.</li> - <li>The focus indicator and the indicator's background color are not modified by the author.</li> - </ul> - </td> - <td> - <p> Check out <a href="https://www.w3.org/WAI/WCAG22/Understanding/focus-appearance.html">Understanding focus appearance (Level AAA)</a> to learn more about this standard.</p> - </td> -</tr> - </tbody> -</table> - -> [!NOTE] -> Also see the WCAG description for [Guideline 2.4 Navigable: Provide ways to help users navigate, find content, and determine where they are.](https://www.w3.org/TR/WCAG21/#navigable) - -## Guideline 2.5 Input Modalities: Make it easier for users to operate functionality through various inputs beyond keyboard - -The conformance criteria under this guideline ensures that users are able to interact with digital technology using different input methods beyond a keyboard or mouse (including touchscreen, voice, device motion, or alternative input devices). - -<table> - <thead> - <tr> - <th scope="col">Success criteria</th> - <th scope="col">How to conform to the criteria</th> - <th scope="col">Practical resource</th> - </tr> - </thead> - <tbody> - <tr> - <td>2.5.1 Pointer Gestures (A) <em><a href="https://www.w3.org/TR/WCAG21/#new-features-in-wcag-2-1">added in 2.1</a></em></td> - <td>All functionality that can be operated with a pointer can be operated with single-point actions. Path-based or multi-point gestures are not required to operate any functionality. Exceptions exist.</td> - <td><a href="https://www.w3.org/WAI/WCAG21/Understanding/pointer-gestures.html">Understanding Pointer Gestures</a></td> - </tr> - <tr> - <td>2.5.2 Pointer Cancellation (A) <em><a href="https://www.w3.org/TR/WCAG21/#new-features-in-wcag-2-1">added in 2.1</a></em></td> - <td>For functionality that can be operated using a single-pointer at least one of the following is true: no down-event, abort/undo, up reversal or essential.</td> - <td><a href="https://www.w3.org/WAI/WCAG21/Understanding/pointer-cancellation.html">Understanding Pointer Cancellation</a></td> - </tr> - <tr> - <td>2.5.3 Label in Name (A) <em><a href="https://www.w3.org/TR/WCAG21/#new-features-in-wcag-2-1">added in 2.1</a></em></td> - <td>For each user interface component that includes a visible text label, make sure the accessible name matches (or includes) the visible text in the label.</td> - <td><a href="https://www.w3.org/WAI/WCAG21/Understanding/label-in-name.html">Understanding Label in Name</a></td> - </tr> - <tr> - <td>2.5.4 Motion Actuation (A) <em><a href="https://www.w3.org/TR/WCAG21/#new-features-in-wcag-2-1">added in 2.1</a></em></td> - <td>Ensure that for functionality that can be triggered by a) device motion (like shaking, tilting) or b) user gestures detected by device sensors (including a camera) that both of the following are true: 1) motion actuation can be disabled, and 2) the functionality can be operated without using device motion or user gestures. Exceptions exist.</td> - <td><a href="https://www.w3.org/WAI/WCAG21/Understanding/motion-actuation.html">Understanding Motion Actuation</a></td> - </tr> - <tr> - <td>2.5.5 Target Size (AAA) <em><a href="https://www.w3.org/TR/WCAG21/#new-features-in-wcag-2-1">added in 2.1</a></em></td> - <td>The size of an actionable item's touch target must be at least 44 CSS pixels in both width and height. Exceptions exist.</td> - <td><a href="https://www.w3.org/WAI/WCAG21/Understanding/target-size.html">Understanding Target Size</a></td> - </tr> - <tr> - <td>2.5.6 Concurrent Input Mechanisms (AAA) <em><a href="https://www.w3.org/TR/WCAG21/#new-features-in-wcag-2-1">added in 2.1</a></em></td> - <td>Make sure people can use and switch between different modes of input when interacting with digital content including touchscreen, keyboard, mouse, voice commands, or alternative input devices. An essential exception exists. </td> - <td><a href="https://www.w3.org/WAI/WCAG21/Understanding/concurrent-input-mechanisms.html">Understanding Concurrent Input Mechanism</a></td> - </tr> - <tr> - <td> 2.5.8 Target size minimum (AA)</td> - <td> Target size for pointer inputs should be at least <code>24px</code> wide by <code>24px</code> tall except for the following areas: - <ul> - <li> <strong>Spacing:</strong>Targets that are less than <code>24px x 24px</code> are positioned so that if a <code>24px</code> diameter circle is centered on each target's bounding box, the circles do not intersect with any other target or the circle for another undersized target.</li> - <li> <strong>Equivalent:</strong> A separate control that achieves the same function that meets this standard is available on the same page.</li> - <li> <strong>Inline:</strong> The target is located within a line of text with its size constrained by the line height or surrounding non-target text.</li> - <li> <strong>User agent control:</strong> The target's size is determined by the user agent and has not been modified by the author.</li> - <li> <strong>Essential:</strong> A particular presentation of the target is essential or legally required for the information being conveyed.</li> - </ul> - <td> Check out <a href="https://www.w3.org/WAI/WCAG22/Understanding/target-size-minimum.html">Understanding target size minimum</a> </td> -</tr> - </tr> - </tbody> -</table> - -> [!NOTE] -> Also see the WCAG description for [Guideline 2.5: Input Modalities: Make it easier for users to operate functionality through various inputs beyond keyboard.](https://www.w3.org/TR/WCAG21/#input-modalities) - -## See also - -- [WCAG](/en-US/docs/Web/Accessibility/Understanding_WCAG) - - 1. [Perceivable](/en-US/docs/Web/Accessibility/Understanding_WCAG/Perceivable) - 2. Operable - 3. [Understandable](/en-US/docs/Web/Accessibility/Understanding_WCAG/Understandable) - 4. [Robust](/en-US/docs/Web/Accessibility/Understanding_WCAG/Robust) diff --git a/files/en-us/web/accessibility/understanding_wcag/perceivable/color_contrast/index.md b/files/en-us/web/accessibility/understanding_wcag/perceivable/color_contrast/index.md deleted file mode 100644 index ad1b9b4da2e0423..000000000000000 --- a/files/en-us/web/accessibility/understanding_wcag/perceivable/color_contrast/index.md +++ /dev/null @@ -1,139 +0,0 @@ ---- -title: Color contrast -slug: Web/Accessibility/Understanding_WCAG/Perceivable/Color_contrast -page-type: guide ---- - -{{AccessibilitySidebar}} - -The [color contrast](https://www.w3.org/TR/WCAG21/#dfn-contrast-ratio) between background and foreground content (that is, usually text) should be great enough to ensure legibility. - -When designing readable interfaces for different vision capabilities, the WCAG guidelines recommend the following contrast ratios: - -| Type of content | Minimum ratio (AA rating) | Enhanced ratio (AAA rating) | -| ------------------------------------------------------------------------------- | ------------------------- | --------------------------- | -| Body text | 4.5 : 1 | 7 : 1 | -| Large-scale text (120-150% larger than body text) | 3 : 1 | 4.5 : 1 | -| Active user interface components and graphical objects such as icons and graphs | 3 : 1 | Not defined | - -These ratios do not apply to "incidental" text, such as inactive controls, logotypes, or purely decorative text. - -See the [Solution](#solution) section below for further information. - -Having good color contrast on your site benefits all your users, but it is particularly beneficial to users with certain types of color blindness and other similar conditions, who experience low contrast, and have trouble differentiating between similar colors. This is because they don't see bright and dark areas as readily as those without such conditions, and therefore have trouble seeing edges, borders, and other details. - -It is good to have a cool design on your website, but the design is worthless if your users can't read your content. - -## Examples - -Let's have a look at some simple HTML and CSS code: - -```html -<div class="good">Good contrast</div> -<div class="bad">Bad contrast</div> -``` - -```css -div { - /* General div styles here */ -} - -.good { - background-color: #5a80a9; -} - -.bad { - background-color: #400064; -} -``` - -Both pieces of text have their default black color. - -### Good Contrast - -The "good" `<div>` has a neon blue background, which makes the text easy to read: - -```html -<div class="good">Good contrast</div> -``` - -```css -div { - font-family: sans-serif; - text-align: center; - font-size: 2rem; - font-weight: bold; - width: 250px; - padding: 30px; - border-radius: 20px; - box-shadow: 4px 4px 4px black; -} - -.good { - background-color: #5a80a9; -} -``` - -{{EmbedLiveSample('Good_Contrast', '100%', '100')}} - -### Bad Contrast - -The "bad" `<div>` on the other hand has a very dark purple background, which makes the text much harder to read: - -```html -<div class="bad">Bad contrast</div> -``` - -```css -div { - font-family: sans-serif; - text-align: center; - font-size: 2rem; - font-weight: bold; - width: 250px; - padding: 30px; - border-radius: 20px; - box-shadow: 4px 4px 4px black; -} - -.bad { - background-color: #400064; -} -``` - -{{EmbedLiveSample('Bad_Contrast', '100%', '100')}} - -## Solution - -When choosing a color scheme for your website, choose foreground and background colors that have good contrast. Make the color contrast as good as it can be within your design constraints — ideally go for the AAA rating (see 1.4.6 below), but at least meet the AA rating (see 1.4.3 below). - -If you are including non-text content such as video or animation, you should follow 1.4.11 (again, see below). - -To check your contrast as you make your color choices, use a tool such as WebAIM's [Color Contrast Checker](https://webaim.org/resources/contrastchecker/). - -You can also check color contrast on the fly using Firefox's Developer Tools — see the [Accessibility inspector](https://firefox-source-docs.mozilla.org/devtools-user/accessibility_inspector/index.html) guide, and in particular the section [Check for accessibility issues](https://firefox-source-docs.mozilla.org/devtools-user/accessibility_inspector/index.html#check-for-accessibility-issues). Try using it on the live examples in the description section. - -## Related WCAG success criteria - -- [1.4.3 Minimum contrast (AA)](https://www.w3.org/TR/WCAG21/#contrast-minimum) - - - : The color contrast between background and foreground content should be at a minimum level to ensure legibility: - - - Text and its background should have a contrast ratio of at least 4.5:1. - - Heading (or just larger) text should have a ratio of at least 3:1. Larger text is defined as at least 18pt, or 14pt bold. - -- [1.4.6 Enhanced contrast (AAA)](https://www.w3.org/TR/WCAG21/#contrast-enhanced) - - - : This follows, and builds on, criterion 1.4.3. - - - Text and its background should have a contrast ratio of at least 7:1. - - Heading (or just larger) text should have a ratio of at least 4.5:1. - -- [1.4.11 Non-Text Contrast (AA)](https://www.w3.org/TR/WCAG21/#non-text-contrast) (added in 2.1) - - : There should be a minimum color contrast ratio of 3 to 1 for user interface components and graphical objects. - -## See also - -- [Color and color contrast](/en-US/docs/Learn_web_development/Core/Accessibility/CSS_and_JavaScript#color_and_color_contrast) -- [Multiple labels](/en-US/docs/Learn_web_development/Extensions/Forms/How_to_structure_a_web_form#multiple_labels) -- [Understanding Non-Text Contrast](https://www.w3.org/WAI/WCAG21/Understanding/non-text-contrast.html) diff --git a/files/en-us/web/accessibility/understanding_wcag/perceivable/index.md b/files/en-us/web/accessibility/understanding_wcag/perceivable/index.md deleted file mode 100644 index 2c2a56bf6cab9ab..000000000000000 --- a/files/en-us/web/accessibility/understanding_wcag/perceivable/index.md +++ /dev/null @@ -1,668 +0,0 @@ ---- -title: Perceivable -slug: Web/Accessibility/Understanding_WCAG/Perceivable -page-type: guide ---- - -{{AccessibilitySidebar}} - -This article provides practical advice on how to write your web content so that it conforms to the success criteria outlined in the **Perceivable** principle of the Web Content Accessibility Guidelines (WCAG) 2.0 and 2.1. Perceivable states that users must be able to perceive it in some way, using one or more of their senses. - -> [!NOTE] -> To read the W3C definitions for Perceivable and its guidelines and success criteria, see [Principle 1: Perceivable - Information and user interface components must be presentable to users in ways they can perceive.](https://www.w3.org/TR/WCAG21/#perceivable) - -## Guideline 1.1 — Providing text alternatives for non-text content - -The key here is that text can be converted to other forms that people with disabilities can use. For example, it can be spoken by a screen reader, converted to large print, or represented on a braille display. Non-text content refers to multimedia such as images, audio, and video. - -<table class="standard-table"> - <thead> - <tr> - <th scope="col">Success criteria</th> - <th scope="col">How to conform to the criteria</th> - <th scope="col">Practical resource</th> - </tr> - </thead> - <tbody> - <tr> - <td rowspan="5">1.1.1 Provide text equivalents (A)</td> - <td> - All images that convey meaningful content should be given suitable - alternative text. - </td> - <td> - <a href="/en-US/docs/Learn_web_development/Core/Accessibility/HTML#text_alternatives" - >Text alternatives.</a - > - </td> - </tr> - <tr> - <td> - Complex images or charts should have an accessible alternative provided, - either on the same page or via a link. Use a regular link instead of - a <code>longdesc</code> attribute. - </td> - <td> - <p> - A text description may work, or an accessible data table (see - <a href="Learn_web_development/Core/Structuring_content/Table_accessibility" - >HTML table accessibility</a - >). See W3C's - <a href="https://www.w3.org/TR/html-longdesc/">Image Description Extension (longdesc)</a> - for the argument against <code>longdesc</code>. - </p> - </td> - </tr> - <tr> - <td> - Multimedia content (i.e., audio or video) should at least have a - descriptive identification available, such as a caption or similar. - </td> - <td> - <p> - See <a href="/en-US/docs/Learn_web_development/Core/Accessibility/HTML#text_alternatives" - >Text alternatives</a - > - for static caption options, and - <a href="/en-US/docs/Learn_web_development/Core/Accessibility/Multimedia#audio_transcripts" - >Audio transcripts</a - >, - <a href="/en-US/docs/Learn_web_development/Core/Accessibility/Multimedia#video_text_tracks" - >Video text tracks</a - > - for other alternatives. - </p> - </td> - </tr> - <tr> - <td> - UI controls such as form elements and buttons should have text labels - that describe their purpose. - </td> - <td> - Buttons are simple—you should make sure the button text describes the - function of the button (e.g., <code - >&#x3C;button>Upload image&#x3C;/button></code - >). For more information on other UI controls, see - <a href="/en-US/docs/Learn_web_development/Core/Accessibility/HTML#ui_controls" - >UI controls</a - >. - </td> - </tr> - <tr> - <td> - Implement decorative (non-content) images, video, etc., in a way that is - invisible to assistive technology, so it doesn't confuse users. - </td> - <td> - <p> - Decorative images should be implemented using CSS background images - (see - <a - href="/en-US/docs/Learn_web_development/Core/Styling_basics/Backgrounds_and_borders" - >Backgrounds and borders</a - >). If you have to include an image via an - {{htmlelement("img")}} element, give it a blank alt - (<code>alt=""</code>). Otherwise, screen readers may try to read out - the filepath, etc. - </p> - <p> - If you are including background video or audio that autoplays, make it - as unobtrusive as possible. Don't make it look/sound like content, and - provide a control to turn it off. Ideally, don't include it at all. - </p> - </td> - </tr> - </tbody> -</table> - -> [!NOTE] -> Also see the [WCAG description for Guideline 1.1: Text alternatives](https://www.w3.org/TR/WCAG21/#text-alternatives). - -## Guideline 1.2 — Providing text alternatives for time-based media - -Time-based media refers to multimedia with a duration, such as audio and video. Note that if the audio/video serves as an alternative to existing text content, you don't need to provide another text alternative. - -<table> - <thead> - <tr> - <th scope="col">Success criteria</th> - <th scope="col">How to conform to the criteria</th> - <th scope="col">Practical resource</th> - </tr> - </thead> - <tbody> - <tr> - <td>1.2.1 Provide alternatives for pre-recorded audio-only and video-only content (A)</td> - <td>A transcript should be provided for prerecorded audio-only media, and a transcript or audio description should be provided for prerecorded video-only media (i.e., silent video).</td> - <td>See&nbsp;<a href="/en-US/docs/Learn_web_development/Core/Accessibility/Multimedia#audio_transcripts">Audio transcripts</a> for transcript information. No audio description tutorial is available yet.</td> - </tr> - <tr> - <td>1.2.2 Provide captions for web-based video (A)</td> - <td>You should provide captions for video presented on the web (e.g., HTML video). This is for the benefit of people who can't hear the audio part of the video.</td> - <td>See <a href="/en-US/docs/Learn_web_development/Core/Accessibility/Multimedia#video_text_tracks">Video text tracks</a> for HTML video captions. See also <a href="https://support.google.com/youtube/answer/2734796?hl=en">Add your own subtitles &amp; closed captions</a> (YouTube).</td> - </tr> - <tr> - <td>1.2.3 Provide text transcript or audio description for web-based video (A)</td> - <td>You should provide text transcripts or audio descriptions for video presented on the web (e.g., HTML video. This is for the benefit of people who can't see the visual part of the video, and don't get the full content from the audio alone.</td> - <td>See&nbsp;<a href="/en-US/docs/Learn_web_development/Core/Accessibility/Multimedia#audio_transcripts">Audio transcripts</a> for transcript information. No audio description tutorial is available yet.</td> - </tr> - <tr> - <td>1.2.4 Provide captions for live audio (AA)</td> - <td>You should provide synchronized captions for all live multimedia that contains audio (e.g., video conferences, live audio broadcasts).</td> - <td></td> - </tr> - <tr> - <td>1.2.5 Provide audio descriptions for prerecorded video (AA)</td> - <td>Audio descriptions should be provided for prerecorded video, but only where the existing audio does not convey the full meaning expressed by the video.</td> - <td></td> - </tr> - <tr> - <td>1.2.6 Provide sign language equivalent to prerecorded audio (AAA)</td> - <td>An equivalent sign language video should be provided for any prerecorded content containing audio.</td> - <td></td> - </tr> - <tr> - <td>1.2.7 Provide extended video with audio descriptions (AAA)</td> - <td>Where audio descriptions cannot be provided (see 1.2.5) due to video timing issues (e.g., there are no suitable pauses in the content in which to insert the audio descriptions), an alternative version of the video should be provided that includes inserted pauses (and audio descriptions).</td> - <td></td> - </tr> - <tr> - <td>1.2.8 Provide an alternative for prerecorded media (AAA)</td> - <td>For all content that features video, a descriptive text transcript should be provided, for example a script of the movie you are watching. This is for the benefit of hearing-impaired viewers who cannot hear the content.</td> - <td>See&nbsp;<a href="/en-US/docs/Learn_web_development/Core/Accessibility/Multimedia#audio_transcripts">Audio transcripts</a> for transcript information.</td> - </tr> - <tr> - <td>1.2.9 Provide a transcript for live audio (AAA)</td> - <td>For any live audio content being broadcast, a descriptive text should be provided, for example a script of the play or musical you are listening to. This is for the benefit of hearing-impaired viewers who cannot hear the content.</td> - <td>See&nbsp;<a href="/en-US/docs/Learn_web_development/Core/Accessibility/Multimedia#audio_transcripts">Audio transcripts</a> for transcript information.</td> - </tr> - </tbody> -</table> - -> [!NOTE] -> Also see the [WCAG description for Guideline 1.2: Time-based Media: Provide alternatives for time-based media](https://www.w3.org/TR/WCAG21/#time-based-media). - -## Guideline 1.3 — Create content that can be presented in different ways - -This guideline refers to the ability of content to be consumed by users in multiple ways, accommodating their differing needs. - -<table class="standard-table"> - <tbody> - <tr> - <th scope="col">Success criteria</th> - <th scope="col">How to conform to the criteria</th> - <th scope="col">Practical resource</th> - </tr> - <tr> - <td>1.3.1 Info and relationships (A)</td> - <td> - <p> - Any content structure—or visual relationship made between content—can - also be determined programmatically, or be inferred from text - description. The main situations in which this is relevant are: - </p> - <ul> - <li> - Text labels and the form elements they describe. These are - associated unambiguously using the {{htmlelement("label")}} - element, which can be picked up by screen readers, etc. - </li> - <li> - Image alt text. Content images should have text available that - clearly describes the image's contents, which can be - programmatically associated with it (e.g., alt text), - or otherwise is easy to associate (e.g., describes it and is sat - right next to it). This should mean that the full meaning can still - be inferred even if you can't see the image. - </li> - <li> - Lists. If the order of list items is important, use an ordered list - ({{htmlelement("ol")}}). - </li> - </ul> - </td> - <td> - The whole of - <p> - <a href="/en-US/docs/Learn_web_development/Core/Accessibility/HTML" - >HTML: A good basis for accessibility</a - > - is packed with information about this, but you should particularly - refer to - <a href="/en-US/docs/Learn_web_development/Core/Accessibility/HTML#good_semantics" - >Good semantics</a - >, - <a href="/en-US/docs/Learn_web_development/Core/Accessibility/HTML#ui_controls" - >UI controls</a - >, and - <a href="/en-US/docs/Learn_web_development/Core/Accessibility/HTML#text_alternatives" - >Text alternatives</a - >. - </p> - </td> - </tr> - <tr> - <td>1.3.2 Meaningful content sequence (A)</td> - <td> - A sensible, logical reading order should be easy to determine for any - content, even if it is visually presented in an unusual way. The order - should be made obvious by use of correct semantic elements (e.g., - headings, paragraphs), with CSS being used to create any unusual layout - styles, irrespective of the markup. - </td> - <td> - Again, refer to - <a href="/en-US/docs/Learn_web_development/Core/Accessibility/HTML" - >HTML: A good basis for accessibility</a - >. - </td> - </tr> - <tr> - <td>1.3.3 Sensory characteristics (A)</td> - <td> - <p> - Instructions for operating controls or understanding content do not - rely on a single sense. This may prove inaccessible to people with a - disability related to that sense, or a device that does not support - that sense. So, for example: - </p> - <ul> - <li> - "Click the round button to continue"<br />The button should be - clearly labelled so that it is obvious that it is the button you - need to press. If there are multiple buttons, make sure they are all - clearly labelled to distinguish their function. - </li> - <li> - "Listen to the audio instructions for guidance"<br />This is - obviously problematic—audio will be inaccessible to those with - hearing impairments, whereas text can be read, but also spoken by a - screen reader if required. - </li> - <li> - "Swipe from the right-hand side of the screen to reveal the menu"<br />Some - users might not be able to swipe the screen, either due to - disability or because their device does not support touch. An - alternative should be provided, such as a keyboard shortcut or - button that can be activated by keyboard or other means. - </li> - </ul> - <div class="note notecard"> - <p> - <strong>Note:</strong> Conveying instructions solely by color is - related, but covered in a different guideline — 1.4.1. - </p> - </div> - </td> - <td></td> - </tr> - <tr> - <td> - 1.3.4 Orientation (AA) - <em - ><a href="https://www.w3.org/TR/WCAG21/#new-features-in-wcag-2-1" - >added in 2.1</a - ></em - > - </td> - <td> - Content does not restrict its view and operation to a single display - orientation, such as portrait or landscape, unless a specific display - orientation is essential. - </td> - <td> - <p> - <a href="https://www.w3.org/WAI/WCAG21/Understanding/orientation.html" - >Understanding Orientation</a - > - </p> - </td> - </tr> - <tr> - <td> - 1.3.5 Identify Input Purpose (AA) <em - ><a href="https://www.w3.org/TR/WCAG21/#new-features-in-wcag-2-1" - >added in 2.1</a - ></em - > - </td> - <td> - <p> - Follow the list of - <a href="https://www.w3.org/TR/WCAG21/#input-purposes" - >53 input fields</a - > - to programmatically identify the purpose of a field. - </p> - </td> - <td> - <a - href="https://www.w3.org/WAI/WCAG21/Understanding/identify-input-purpose.html" - >Understanding Identify Input Purpose</a - > - </td> - </tr> - <tr> - <td> - 1.3.6 Identify Purpose (AAA) <em - ><a href="https://www.w3.org/TR/WCAG21/#new-features-in-wcag-2-1" - >added in 2.1</a - ></em - > - </td> - <td> - In content implemented using markup languages, the purpose of user - interface components, icons, and regions can be programmatically - determined. - </td> - <td> - <a - href="https://www.w3.org/WAI/WCAG21/Understanding/identify-purpose.html" - >Understanding Identify Purpose</a - > - </td> - </tr> - </tbody> -</table> - -> [!NOTE] -> Also see the WCAG description for [Guideline 1.3: Adaptable: Create content that can be presented in different ways without losing information or structure.](https://www.w3.org/TR/WCAG21/#adaptable) - -## Guideline 1.4: Make it easier for users to see and hear content including separating foreground from background - -This guideline relates to making sure core content is easy to discern from backgrounds and other decoration. The classic example is color (both [color contrast](/en-US/docs/Web/Accessibility/Understanding_WCAG/Perceivable/Color_contrast) and [use of color](/en-US/docs/Web/Accessibility/Understanding_WCAG/Perceivable/Use_of_color) to convey instructions), but it applies in other situations too. - -<table class="standard-table"> - <thead> - <tr> - <th scope="col">Success criteria</th> - <th scope="col">How to conform to the criteria</th> - <th scope="col">Practical resource</th> - </tr> - <tr> - <td>1.4.1 Use of color (A)</td> - <td> - <p> - Color should not be solely relied upon to convey information. For - example, in forms, you should never mark required fields purely with a - color (like red). Instead (or as well as), something like an asterisk - with a label of "required" would be more appropriate. - </p> - </td> - <td> - See - <a href="/en-US/docs/Web/Accessibility/Understanding_WCAG/Perceivable/Use_of_color" - >Use of color</a - >, - <a - href="/en-US/docs/Learn_web_development/Core/Accessibility/CSS_and_JavaScript#color_and_color_contrast" - >Color and color contrast</a - >, - and - <a - href="/en-US/docs/Learn_web_development/Extensions/Forms/How_to_structure_a_web_form#multiple_labels" - >Multiple labels</a - >. - </td> - </tr> - <tr> - <td>1.4.2 Audio controls (A)</td> - <td> - For any audio that plays for longer than three seconds, provide - accessible controls to play and pause the audio/video, and mute/adjust - volume. - </td> - <td> - Use native <code>&lt;button&gt;</code>s to provide accessible keyboard - controls, as shown in - <a - href="/en-US/docs/Web/Media/Guides/Audio_and_video_delivery/Video_player_styling_basics" - >Video player styling basics</a - >. - </td> - </tr> - <tr> - <td>1.4.3 Minimum contrast (AA)</td> - <td> - <p> - The color contrast between background and foreground content should be - at a minimum level to ensure legibility: - </p> - <ul> - <li> - Text and its background should have a contrast ratio of at least - 4.5:1. - </li> - <li> - Heading (or just larger) text should have a ratio of at least 3:1. - Larger text is defined as at least 18pt, or 14pt bold. - </li> - </ul> - </td> - <td> - See - <a href="/en-US/docs/Web/Accessibility/Understanding_WCAG/Perceivable/Color_contrast" - >Color contrast</a - > and - <a - href="/en-US/docs/Learn_web_development/Core/Accessibility/CSS_and_JavaScript#color_and_color_contrast" - >Color and color contrast</a - >. - </td> - </tr> - <tr> - <td>1.4.4 Resize text (AA)</td> - <td> - The page should be readable and usable when the text size is doubled. - This means that designs should be responsive, so that when the text size - is increased, the content is still accessible. - </td> - <td></td> - </tr> - <tr> - <td>1.4.5 Images of text (AA)</td> - <td> - Images should NOT be used to present content where text would do the - job. For example, if an image is mostly textual, it could be represented - using text as well as images. - </td> - <td></td> - </tr> - <tr> - <td>1.4.6 Enhanced contrast (AAA)</td> - <td> - <p>This follows, and builds on, criterion 1.4.3.</p> - <ul> - <li> - Text and its background should have a contrast ratio of at least - 7:1. - </li> - <li> - Heading (or just larger) text should have a ratio of at least 4.5:1. - Larger text is defined as at least 18pt, or 14pt bold. - </li> - </ul> - </td> - <td> - See - <a - href="/en-US/docs/Learn_web_development/Core/Accessibility/CSS_and_JavaScript#color_and_color_contrast" - >Color and color contrast</a - >. - </td> - </tr> - <tr> - <td>1.4.7 Low or no background audio (AAA)</td> - <td> - Prerecorded audio recordings that primarily feature speech should have - minimal background noise, so the content can be easily understood. - </td> - <td></td> - </tr> - <tr> - <td>1.4.8 Visual presentation (AAA)</td> - <td> - <p>For text content presentation, the following should be true:</p> - <ul> - <li>Foreground and background colors should be user-selectable.</li> - <li> - Text blocks should be no wider than 80 characters (or glyphs), for - maximum readability. - </li> - <li> - Text should not be fully justified (e.g., <code - >text-align: justify;</code - >). - </li> - <li> - Line height should be at least 1.5 times the text size within - paragraphs (e.g., <code>line-height: 1.5;</code>), and at least 2.25 - times the text size between paragraphs (e.g., <code - >padding: 2.25rem;</code - >). - </li> - <li> - When the text size is doubled, the content should not need to be - scrolled. - </li> - </ul> - </td> - <td></td> - </tr> - <tr> - <td>1.4.9 Images of text (No Exception) (AAA)</td> - <td> - Text should not be presented as part of an image unless it is purely - decoration (i.e., it does not convey any content) or cannot be presented - in any other way. - </td> - <td></td> - </tr> - <tr> - <td> - 1.4.10 Reflow (AA) <em - ><a href="https://www.w3.org/TR/WCAG21/#new-features-in-wcag-2-1" - >added in 2.1</a - ></em - > - </td> - <td> - <ul> - <li> - No horizontal scrolling for left-to-right languages (like English) - or right-to-left languages (like Arabic) - </li> - <li> - No vertical scrolling for top-to-bottom languages (like Japanese) - </li> - <li> - Except for parts of the content which require two-dimensional layout - for usage or meaning (like a large data table) - </li> - </ul> - </td> - <td> - <a href="https://www.w3.org/WAI/WCAG21/Understanding/reflow.html" - >Understanding Reflow</a - > - </td> - </tr> - <tr> - <td> - 1.4.11 Non-Text Contrast(AA) <em - ><a href="https://www.w3.org/TR/WCAG21/#new-features-in-wcag-2-1" - >added in 2.1</a - ></em - > - </td> - <td> - Minimum color contrast ratio of 3:1 for user interface components and - graphical objects. - </td> - <td> - <a - href="https://www.w3.org/WAI/WCAG21/Understanding/non-text-contrast.html" - >Understanding Non-Text Contrast</a - > - </td> - </tr> - <tr> - <td> - 1.4.12 Text Spacing (AA) <em - ><a href="https://www.w3.org/TR/WCAG21/#new-features-in-wcag-2-1" - >added in 2.1</a - ></em - > - </td> - <td> - <p> - No loss of content or functionality occurs when the following styles - are applied: - </p> - <ul> - <li> - Line height (line spacing) to at least 1.5 times the font size - </li> - <li> - Spacing following paragraphs to at least 2 times the font size - </li> - <li> - Letter spacing (tracking) to at least 0.12 times the font size - </li> - <li>Word spacing to at least 0.16 times the font size</li> - </ul> - </td> - <td> - <a href="https://www.w3.org/WAI/WCAG21/Understanding/text-spacing.html" - >Understanding Text Spacing</a - > - </td> - </tr> - <tr> - <td> - 1.4.13 Content on Hover or Focus (AA) <em - ><a href="https://www.w3.org/TR/WCAG21/#new-features-in-wcag-2-1" - >added in 2.1</a - ></em - > - </td> - <td> - <p> - While additional content may appear and disappear in coordination with - hover and keyboard focus, this success criterion specifies three - conditions that must be met: - </p> - <ul> - <li>dismissible (can be closed/removed)</li> - <li> - hoverable (the additional content does not disappear when the - pointer is over it) - </li> - <li> - persistent (the additional content does not disappear without user - action) - </li> - </ul> - </td> - <td> - <a - href="https://www.w3.org/WAI/WCAG21/Understanding/content-on-hover-or-focus.html" - >Understanding Content on Hover or Focus</a - > - </td> - </tr> - </thead> -</table> - -> [!NOTE] -> Also see the WCAG description for [Guideline 1.4: Distinguishable: Make it easier for users to see and hear content including separating foreground from background.](https://www.w3.org/TR/WCAG21/#distinguishable) - -## See also - -- [WCAG](/en-US/docs/Web/Accessibility/Understanding_WCAG) - - 1. Perceivable - 2. [Operable](/en-US/docs/Web/Accessibility/Understanding_WCAG/Operable) - 3. [Understandable](/en-US/docs/Web/Accessibility/Understanding_WCAG/Understandable) - 4. [Robust](/en-US/docs/Web/Accessibility/Understanding_WCAG/Robust) diff --git a/files/en-us/web/accessibility/understanding_wcag/perceivable/use_of_color/index.md b/files/en-us/web/accessibility/understanding_wcag/perceivable/use_of_color/index.md deleted file mode 100644 index 356fb0800ab15bc..000000000000000 --- a/files/en-us/web/accessibility/understanding_wcag/perceivable/use_of_color/index.md +++ /dev/null @@ -1,26 +0,0 @@ ---- -title: Use of color -slug: Web/Accessibility/Understanding_WCAG/Perceivable/Use_of_color -page-type: guide ---- - -{{AccessibilitySidebar}} - -While [color contrast](/en-US/docs/Web/Accessibility/Understanding_WCAG/Perceivable/Color_contrast) is often primarily an aesthetic choice, the _use of color_ on a website pertains to _using color to communicate information_. WCAG guideline 1.4.1 on the use of color requires that "color is not used as the only visual means of conveying information, indicating an action, prompting a response, or distinguishing a visual element." - -## Solution - -Use another factor in addition to color to convey information. For example, to indicate form validation errors, you can change the labels of the relevant fields by another font attribute as well as by color. Icons and symbols should differ by shape as well as by color. - -To accommodate users with color vision disorders ("color blindness"), be careful when using a "stoplight" color metaphor, with green indicating "good" values and red indicating "bad" values. Users with red-green color blindness have trouble distinguishing red and green, and so may not be able to tell these values apart. Using an additional factor to signal "good" vs. "bad" is necessary. Avoid pure red and green in this situation; a reddish-orange and a bluish-green are distinguishable by color blind users, while still conveying the cultural "good" and "bad" meanings to users with normal color vision. [Color contrast](/en-US/docs/Web/Accessibility/Understanding_WCAG/Perceivable/Color_contrast) can be helpful in this context, as well, if one color is darker or lighter than the other. - -## Related WCAG success criteria - -- [1.4.1 Use of color (A)](https://www.w3.org/TR/WCAG21/#use-of-color) - - : Color is not used as the only visual means of conveying information, indicating an action, prompting a response, or distinguishing a visual element. - -## See also - -- [Understanding Success Criterion 1.4.1: Use of Color](https://www.w3.org/WAI/WCAG21/Understanding/use-of-color.html) -- [Color contrast](/en-US/docs/Web/Accessibility/Understanding_WCAG/Perceivable/Color_contrast) -- [Color and color contrast](/en-US/docs/Learn_web_development/Core/Accessibility/CSS_and_JavaScript#color_and_color_contrast) in the Accessibility tutorials diff --git a/files/en-us/web/accessibility/understanding_wcag/robust/index.md b/files/en-us/web/accessibility/understanding_wcag/robust/index.md deleted file mode 100644 index b201374ed7ded57..000000000000000 --- a/files/en-us/web/accessibility/understanding_wcag/robust/index.md +++ /dev/null @@ -1,112 +0,0 @@ ---- -title: Robust -slug: Web/Accessibility/Understanding_WCAG/Robust -page-type: guide ---- - -{{AccessibilitySidebar}} - -This article provides practical advice on how to write your web content so that it conforms to the success criteria outlined in the **Robust** principle of the Web Content Accessibility Guidelines (WCAG) 2.0 and 2.1. Robust states that content must be robust enough that it can be interpreted reliably by a wide variety of user agents, including assistive technologies. This can generally be achieved by following web standards and [testing rigorously](/en-US/docs/Learn_web_development/Extensions/Testing). - -> [!NOTE] -> To read the W3C definitions for Robust and its guidelines and success criteria, see [Principle 4: Robust — Content must be robust enough that it can be interpreted reliably by a wide variety of user agents, including assistive technologies.](https://www.w3.org/TR/WCAG21/#robust) - -## Guideline 4.1 — Compatible: Maximize compatibility with current and future user agents, including assistive technologies - -This guideline focuses on making content as compatible as possible, not only with current user agents (e.g. browsers), but also with future ones too. - -<table class="standard-table"> - <thead> - <tr> - <th scope="col">Success criteria</th> - <th scope="col">How to conform to the criteria</th> - <th scope="col">Practical resource</th> - </tr> - </thead> - <tbody> - <tr> - <td>4.1.1 Parsing (A)</td> - <td> - <p> - Content should be well-formed so it can be parsed successfully by - browsers and other user agents such as screen readers. - </p> - <p> - To pass this criterion, make sure that your HTML is as valid as - possible. Use the - <a href="https://validator.w3.org/">W3C validator</a> to validate your - markup. - </p> - </td> - <td> - See - <a href="/en-US/docs/Learn_web_development/Core/Structuring_content/Debugging_HTML" - >Debugging HTML</a - > - for a practical guide. - </td> - </tr> - <tr> - <td>4.1.2 Name, Role, Value (A)</td> - <td> - <p> - The name and role of user interface components (e.g. form inputs, - buttons, links, etc.) should be programmatically determinable. - </p> - <p> - When using semantic elements correctly for their intended purpose, - this criterion should be passed automatically. When scripting custom - components, you will need to use WAI-ARIA roles and other features to - make sure your controls will be interpreted and are able to be used as - intended, e.g. not only by sighted mouse users, but also by - screen reader users, keyboard-only users, etc. - </p> - </td> - <td> - See - <a href="/en-US/docs/Learn_web_development/Core/Accessibility/HTML" - >HTML: A good basis for accessibility</a - > - and - <a href="/en-US/docs/Learn_web_development/Core/Accessibility/WAI-ARIA_basics" - >WAI-ARIA basics</a - >. - </td> - </tr> - <tr> - <td> - 4.1.3 Status Messages (AA) <em - ><a - href="https://www.w3.org/TR/WCAG21/#new-features-in-wcag-2-1" - rel="noopener" - >added in 2.1</a - ></em - > - </td> - <td> - <p> - Assistive technology users are made aware of new status messages added - to the page. - </p> - </td> - <td> - <a - href="https://www.w3.org/WAI/WCAG21/Understanding/status-messages.html" - >Understanding Status Messages</a - > - </td> - </tr> - </tbody> -</table> - -> [!NOTE] -> Also see the WCAG description for [Guideline 4.1: Compatible: Maximize compatibility with current and future user agents, including assistive technologies.](https://www.w3.org/TR/WCAG21/#compatible) - -## See also - -- [WCAG](/en-US/docs/Web/Accessibility/Understanding_WCAG) - - 1. [Perceivable](/en-US/docs/Web/Accessibility/Understanding_WCAG/Perceivable) - 2. [Operable](/en-US/docs/Web/Accessibility/Understanding_WCAG/Operable) - 3. [Understandable](/en-US/docs/Web/Accessibility/Understanding_WCAG/Understandable) - 4. Robust diff --git a/files/en-us/web/accessibility/understanding_wcag/text_labels_and_names/index.md b/files/en-us/web/accessibility/understanding_wcag/text_labels_and_names/index.md deleted file mode 100644 index a7268191cfeb82c..000000000000000 --- a/files/en-us/web/accessibility/understanding_wcag/text_labels_and_names/index.md +++ /dev/null @@ -1,286 +0,0 @@ ---- -title: Text labels and names -slug: Web/Accessibility/Understanding_WCAG/Text_labels_and_names -page-type: guide ---- - -{{AccessibilitySidebar}} - -There are many situations in which a control, dialog, or other website feature should be given a descriptive name or label to allow users of assistive technologies to understand what its purpose is and how to operate it correctly. There are a number of different types of problems in this category, found in different contexts, and each has its own solution. The different problems and solutions are discussed in the sections below. - -## Use alt attribute to label area elements that have the href attribute - -In image maps, give each {{htmlelement("area")}} element an `alt` attribute containing a name that describes what resources the areas links to. Failure to do so makes an image map hard to use for users of assistive technology — they need alternative text to be able to understand the purpose of an image. - -### Examples - -The following example show an image map (taken from [H24: Providing text alternatives for the area elements of image maps](https://www.w3.org/TR/WCAG20-TECHS/H24.html)): - -```html -<img - src="welcome.gif" - usemap="#map1" - alt="Areas in the library. Select an area for -more information on that area." /> -<map id="map1" name="map1"> - <area shape="rect" coords="0,0,30,30" href="reference.html" alt="Reference" /> - <area - shape="rect" - coords="34,34,100,100" - href="media.html" - alt="Audio visual lab" /> -</map> -``` - -See the [`<area>` element reference page](/en-US/docs/Web/HTML/Element/area) for a live interactive example. - -### See also - -- {{htmlelement("area")}} -- [H24: Providing text alternatives for the area elements of image maps](https://www.w3.org/TR/WCAG20-TECHS/H24.html) - -## Dialogs should be labeled - -For any container whose contents act as a dialog box (for example, a modal dialog asking the user to make a choice or respond to an action being taken), give it a descriptive label or name, so that assistive technology users can easily discover what its purpose is. - -A dialog box is generally denoted by an ARIA [`role="dialog"`](/en-US/docs/Web/Accessibility/ARIA/Roles/dialog_role) or [`role="alertdialog"`](/en-US/docs/Web/Accessibility/ARIA/Roles/alertdialog_role); you can use the [`aria-label`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-label) or [`aria-labelledby`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-labelledby) attributes to provide a label. - -### Examples - -The following example shows a simple dialog box, defined as such using `role="dialog"` and labelled using `aria-labelledby`. - -```html -<div - role="dialog" - aria-labelledby="dialog1Title" - aria-describedby="dialog1Desc"> - <h2 id="dialog1Title">Your personal details were successfully updated</h2> - <p id="dialog1Desc"> - You can change your details at any time in the user account section. - </p> - <button>Close</button> -</div> -``` - -If the dialog box doesn't have a heading, you can instead use `aria-label` to contain the label text: - -```html -<div role="dialog" aria-label="Personal details updated confirmation"> - <p> - Your personal details were successfully updated. You can change your details - at any time in the user account section. - </p> - <button>Close</button> -</div> -``` - -### See also - -- [`role="dialog"`](/en-US/docs/Web/Accessibility/ARIA/Roles/dialog_role) -- [`role="alertdialog"`](/en-US/docs/Web/Accessibility/ARIA/Roles/alertdialog_role) -- [`aria-label`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-label) -- [`aria-labelledby`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-labelledby) -- [WAI-ARIA: dialog role](https://www.w3.org/TR/wai-aria-1.2/#dialog) -- [Dialog authoring practices](https://www.w3.org/WAI/ARIA/apg/patterns/dialog-modal/) - -## Documents must have a title - -It is important in each HTML document to include a {{htmlelement("title")}} that describes the page's purpose. A common navigation technique for users of assistive technology is to infer what content a page contains by reading its title. If the title is not available, they have to navigate the page to determine its content, which can be a time consuming and potentially confusing process. - -### Examples - -The title for the reference article about the {{htmlelement("title")}} element is as follows: - -```html -<title> - &lt;title&gt;: The Document Title element - HTML: Hypertext Markup Language | - MDN -</title> -``` - -Another example might look like so: - -```html -<title>Fill in your details to register — myGov services</title> -``` - -To help the user, you can update the page title value to reflect significant page state changes (such as form validation problems): - -```html -<title>2 errors — Fill in your details to register — myGov services</title> -``` - -### See also - -- {{htmlelement("title")}} - -## Embedded content must be labeled - -Make sure that elements that embed content have a [title](/en-US/docs/Web/HTML/Global_attributes/title) attribute that describes the embedded content. This includes the {{htmlelement("embed")}} and {{htmlelement("object")}} elements. These elements are often used for graphical content, much like the {{HTMLelement("img")}} element. A descriptive title helps users of assistive technology understand what the element is showing. - -## Figures with optional captions should be labeled - -For best accessibility, include a {{HTMLElement("figcaption")}} within a {{HTMLElement("figure")}} element, even though doing so is technically optional. The caption is in addition to any alternative text on images within the figure. The caption describes the purpose of the figure in the document, which may be different from a simple description of a visual item, as provided by the alternative text. - -### Example - -The following example shows code for a figure with a caption. The `alt` attribute of the {{htmlelement("img")}} describes the appearance of the image; the {{htmlelement("figcaption")}} describes it from a functional perspective (in this case, the Latin name of the flower in the image). - -```html -<figure> - <img - src="milkweed.jpg" - alt="Black and white close-up photo of milkweed flowers" /> - <figcaption>Asclepias verticillata</figcaption> -</figure> -``` - -## Fieldset elements must be labeled - -Fieldset elements must have a text description, similar to other form elements. Use the {{htmlelement("legend")}} element to describe the purpose of a fieldset. - -## Use a legend to label a fieldset - -When grouping a set of form elements together with a {{htmlelement("fieldset")}} element, you should include a nested {{htmlelement("legend")}} element inside it, containing a clear description of the group. - -Users of assistive technology find this description helpful when trying to work out the overall purpose of the group. Without the legend, they would have to navigate around the individual form controls in the group to infer an idea of the overall purpose, which could result in confusion. - -### Examples - -```html -<form> - <fieldset> - <legend>Choose your favorite monster</legend> - - <input type="radio" id="kraken" name="monster" value="K" /> - <label for="kraken">Kraken</label><br /> - - <input type="radio" id="sasquatch" name="monster" value="S" /> - <label for="sasquatch">Sasquatch</label><br /> - - <input type="radio" id="mothman" name="monster" value="M" /> - <label for="mothman">Mothman</label> - </fieldset> -</form> -``` - -You can see a live, interactive version of this example on the [`<fieldset>` reference page](/en-US/docs/Web/HTML/Element/fieldset). - -### See also - -- {{htmlelement("fieldset")}} -- {{htmlelement("legend")}} - -## Form elements must be labeled - -All elements within a form must have a {{htmlelement("label")}} that identifies its purpose. This applies to all types of {{htmlelement("input")}} items, as well as {{htmlelement("button")}}, {{htmlelement("output")}}, {{htmlelement("select")}}, {{htmlelement("textarea")}}, {{htmlelement("progress")}} and {{htmlelement("meter")}} elements, as well as any element with the [`switch` ARIA role](/en-US/docs/Web/Accessibility/ARIA/Roles/switch_role). - -The form element can be placed inside the {{htmlelement("label")}}, in which case the association between the form element and the label is obvious from the structure. Or, you can create an association between a {{htmlelement("label")}} and a form element by specifying the form element's `id` value as the value of the label's `for` attribute. - -### Example - -```html -<label - >I agree to the terms and conditions. - <input type="checkbox" id="terms" name="terms" /> -</label> - -<input type="checkbox" id="email-opt-in" name="opt-in" /> -<label for="email-opt-in">Yes, please send me news about this product.</label> -``` - -## Form elements should have a visible text label - -In addition to having a {{htmlelement("label")}} for every form element, those labels should be visible, not hidden. Visible labels help _all_ users understand the purpose of a form element. Do not rely on placeholder text, because it disappears as soon as the user starts typing. - -## Frame elements must be labeled - -Frame elements, both {{htmlelement("iframe")}} and the older, obsolete {{htmlelement("frame")}}, must have a title to describe the contents of the frame. Use the `title` attribute to label a frame element. Without a title, users of assistive technologies have to navigate into the frame in order to understand what it contains, which can be difficult and confusing. - -The {{HTMLElement('frame')}} element is no longer part of the HTML specification. Support for it may be dropped by browsers in the future. In addition, it is difficult for screen readers to navigate pages with {{HTMLElement('frame')}} elements. For best accessibility and future maintenance, redesign any pages that use frames to use CSS to achieve a similar layout. - -As a best practice, also provide a {{htmlelement("title")}} for the document that is enclosed in the frame, with content identical to the frame's `title` attribute. (This assumes that the enclosed document is under your control; if not, try to match the frame's `title` attribute to the document's title.) Some screen readers replace the contents of the `title` attribute with the contents of the enclosed document's {{htmlelement("title")}}. It's safest and most accessible to provide the same title in both places. - -### Example - -```html -<iframe - title="MDN Web docs" - width="300" - height="200" - src="https://developer.mozilla.org"> -</iframe> -``` - -## Headings must be labeled - -Make sure that your headings have non-empty text content, and are not hidden, such as with CSS `display:none` or `aria-hidden=true`. Users of screen readers rely on headings to understand the structure and content of a document. - -Also, be sure you are using [heading elements](/en-US/docs/Web/HTML/Element/Heading_Elements) only for actual section headings, and not as a shortcut way to make text stand out. Screen reader users typically "skim" a page's headings, much like sighted users; non-heading text that is marked-up with heading elements can cause confusion. - -## Headings should have visible text content - -Make sure that your headings have non-empty text content, and are not hidden, such as with CSS `display:none` or `aria-hidden=true`. Users of screen readers rely on headings to understand the structure and content of a document. Do not use heading elements to mark up images or other graphical content. - -## Use title attribute to describe `<iframe>` content - -Make sure that {{htmlelement("iframe")}} elements have a `title` attribute to describe the contents of the frame. Without a title, users of assistive technologies have to navigate into the frame in order to understand what it contains, which can be difficult and confusing. - -As a best practice, also provide a {{htmlelement("title")}} for the document that is enclosed in the frame, with content identical to the frame's `title` attribute. (This assumes that the enclosed document is under your control; if not, try to match the frame's `title` attribute to the document's title.) Some screen readers replace the contents of the `title` attribute with the contents of the enclosed document's {{htmlelement("title")}}. It's safest and most accessible to provide the same title in both places. - -## Content with images must be labeled - -Provide descriptive text for all contentful (that is, non-decorative) images and image-like elements. This includes SVG images, {{htmlelement("img")}}, {{htmlelement("canvas")}}, {{htmlelement("map")}}, and {{htmlelement("area")}} elements, as well as {{htmlelement("input")}} elements where `type=image` and {{htmlelement("object")}} elements where the `type` starts with `image/`. The typical way to do this is with the `alt` attribute. Be sure that the description conveys what is shown in the image. - -### Example - -```html -<img - src="milkweed.jgp" - alt="Black and white close-up photo of milkweed flowers" /> -``` - -## Interactive elements must be labeled - -If an element is intended for users to interact with it, it should have a label. Interactive elements include links ({{htmlelement("a")}}), form elements, buttons, and any element that has a handler for mouse or keyboard events. The way to label an element depends on its type: for form elements, use a {{htmlelement("label")}}; for links, buttons and clickable elements, the text content of the element typically provides the label. If no other option exists for labeling an element, use the [`aria-label`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-label) attribute. - -## Use label attribute on optgroup elements - -In an {{htmlelement("optgroup")}} element, use the `label` attribute to describe the group so that assistive technologies can access it for their users. - -### Example - -In this example, the `label` attribute on the {{HTMLElement('optgroup')}} elements gives a category name for the group of options. - -```html -<label for="dino-select">Choose a dinosaur:</label> -<select id="dino-select"> - <optgroup label="Theropods"> - <option>Tyrannosaurus</option> - <option>Velociraptor</option> - <option>Deinonychus</option> - </optgroup> - <optgroup label="Sauropods"> - <option>Diplodocus</option> - <option>Saltasaurus</option> - <option>Apatosaurus</option> - </optgroup> -</select> -``` - -## Toolbars must be labeled when there is more than one toolbar - -If you define more than one toolbar in a web application using the ARIA `toolbar` role, you must use the [`aria-label`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-label) attribute to label each one so that it can be described by assistive technology. It is a good practice to label a toolbar, even if there is only one per page. - -### See also - -- [W3C ARIA toolbar example](https://www.w3.org/WAI/ARIA/apg/patterns/toolbar/examples/toolbar/) - -## Related WCAG success criteria - -- [1.1.1 Non-text Content (A)](https://www.w3.org/TR/WCAG21/#non-text-content) - - : All non-text content that is presented to the user has a text alternative that serves the equivalent purpose, except for the situations listed in the above link. -- [2.4.4 Link Purpose (In Context) (A)](https://www.w3.org/TR/WCAG21/#link-purpose-in-context) - - : The purpose of each link can be determined from the link text alone or from the link text together with its programmatically determined link context, except where the purpose of the link would be ambiguous to users in general. -- [2.4.9 Link Purpose (Link Only) (AAA)](https://www.w3.org/TR/WCAG21/#link-purpose-link-only) - - : A mechanism is available to allow the purpose of each link to be identified from link text alone, except where the purpose of the link would be ambiguous to users in general. diff --git a/files/en-us/web/accessibility/understanding_wcag/understandable/index.md b/files/en-us/web/accessibility/understanding_wcag/understandable/index.md deleted file mode 100644 index 048873832c1445f..000000000000000 --- a/files/en-us/web/accessibility/understanding_wcag/understandable/index.md +++ /dev/null @@ -1,515 +0,0 @@ ---- -title: Understandable -slug: Web/Accessibility/Understanding_WCAG/Understandable -page-type: guide ---- - -{{AccessibilitySidebar}} - -This article provides practical advice on how to write your web content so that it conforms to the success criteria outlined in the **Understandable** principle of the Web Content Accessibility Guidelines (WCAG) 2.0 and 2.1. Understandable states that information and the operation of user interface must be understandable. - -> [!NOTE] -> To read the W3C definitions for Understandable and its guidelines and success criteria, see [Principle 3: Understandable — Information and the operation of user interface must be understandable](https://www.w3.org/TR/WCAG21/#understandable). - -## Guideline 3.1 — Readable: Make text content readable and understandable - -This guideline focuses on making text content as understandable as possible. - -<table class="standard-table"> - <thead> - <tr> - <th scope="col">Success criteria</th> - <th scope="col">How to conform to the criteria</th> - <th scope="col">Practical resource</th> - </tr> - </thead> - <tbody> - <tr> - <td>3.1.1 Language of Page (A)</td> - <td> - The default human language of each web page should be detectable via - code. This is essential for purposes like making sure the reader has - arrived at a page written in a language suitable for them. The simplest - way to achieve this is to set the <a href="/en-US/docs/Web/HTML/Global_attributes/lang">lang</a> - attribute on the page's {{htmlelement("html")}} element, giving - it a value equal to the language code that best represents the language - the page is written in. - </td> - <td> - See - <a - href="/en-US/docs/Learn_web_development/Core/Structuring_content/Webpage_metadata#setting_the_primary_language_of_the_document" - >Setting the primary language of the document</a - >. - </td> - </tr> - <tr> - <td>3.1.2 Language of Parts (AA)</td> - <td> - <p> - In cases where the content of a page includes words or phrases that - are in a different language to the primary language, use the - <a href="/en-US/docs/Web/HTML/Global_attributes/lang">lang</a> attribute on an element wrapped - around the term in question (e.g. a {{htmlelement("span")}} - if no semantic element is available) to set an appropriate language - for it. - </p> - <p> - You don't need to set a different language for words or phrases that - are the same regardless of language (for example proper names, - technical terms that aren't part of a specific language). - </p> - </td> - <td></td> - </tr> - <tr> - <td>3.1.3 Unusual Words (AAA)</td> - <td> - Where technical terms, jargon, or idioms/slang are used, definitions - should be provided for such phrases/words. Your site should provide a - glossary that contains definitions of such words/terms that you can then - link to when they appear, or at the very least provide definitions - somewhere in the surrounding text, or in a - <a - href="/en-US/docs/Learn_web_development/Core/Structuring_content/Advanced_text_features#description_lists" - >description list</a - > - at the bottom of the page. - </td> - <td></td> - </tr> - <tr> - <td>3.1.4 Abbreviations (AAA)</td> - <td> - <p> - Where abbreviations are used, you should provide an expansion of them, - or a definition as required. - </p> - <p> - The {{htmlelement("abbr")}} element is often thought of as - the preferred way to provide an expansion for an abbreviation — it - takes a <a href="/en-US/docs/Web/HTML/Global_attributes/title">title</a> attribute that contains the - expansion, and this appears when the acronym is moused over. However, - the title contents are not accessible via keyboard, nor are they - reliably read out by screen readers. A better way to handle this is to - again provide links to glossary pages containing the acronym expansion - and explanation, or at the very least include them in the surrounding - text in context. - </p> - </td> - <td> - See - <a - href="/en-US/docs/Learn_web_development/Core/Structuring_content/Advanced_text_features#abbreviations" - >Abbreviations</a - >. - </td> - </tr> - <tr> - <td>3.1.5 Reading Level (AAA)</td> - <td> - <p> - If text is provided that requires a higher reading level that lower - secondary education level (typically children around 11-14 years old), - provide supplementary explainer material to help people who can't read - it, or provide an alternative version that is written at lower - secondary level. - </p> - <p> - This doesn't mean that all subject matter should be understood by - everyone, but that the style of writing should be accessible by - everyone. It is better to just write all content at lower secondary - level, even technical documentation like programming tutorials, unless - there is a good reason not to (e.g. an alternative style for poetic - effect), or they have to be written in a strict style (e.g. W3C - specs). - </p> - </td> - <td></td> - </tr> - <tr> - <td>3.1.6 Pronunciation (AAA)</td> - <td> - <p> - A mechanism should be provided to give users access to pronunciation - of words where they are is needed to understand the content fully. - </p> - <p> - The HTML {{htmlelement("audio")}} element can be used to - create a control that allows the reader to play back an audio file - containing the correct pronunciation, and it also makes sense to - include a textual pronunciation guide after difficult words, in the - same way that you find in dictionary entries. - </p> - </td> - <td> - See - <a - href="/en-US/docs/Learn_web_development/Core/Structuring_content/HTML_video_and_audio" - >Video and audio content</a - >, and - <a - href="https://www.oxfordlearnersdictionaries.com/us/about/pronunciation_english.html" - >Pronunciation Guide for English Dictionary</a - > - </td> - </tr> - </tbody> -</table> - -> [!NOTE] -> Also see the WCAG description for [Guideline 3.1 Readable: Make text content readable and understandable](https://www.w3.org/TR/WCAG21/#readable). - -## Guideline 3.2 — Predictable: Make Web pages appear and operate in predictable ways - -This guideline focuses on making user interfaces intuitive and understandable. - -<table class="standard-table"> - <thead> - <tr> - <th scope="col">Success criteria</th> - <th scope="col">How to conform to the criteria</th> - <th scope="col">Practical resource</th> - </tr> - </thead> - <tbody> - <tr> - <td>3.2.1 On Focus (A)</td> - <td> - <p> - When a control or other page feature receives focus, it should not - change the context in a way that may confuse or disorientate the user. - </p> - <p> - This is a matter of sensible design — people don't want interfaces to - surprise them; they want things to be intuitive and behave as - expected. For example, focusing a navigation menu option should not - change the displayed page — it should be activated before the display - changes. - </p> - </td> - <td> - <code>Element</code>'s {{domxref("Element.focus_event", "focus")}} event contains some - useful information. Also see - <a - href="/en-US/docs/Learn_web_development/Core/Accessibility/HTML#building_keyboard_accessibility_back_in" - >Building keyboard accessibility back in</a - > - for some useful implementation ideas. - </td> - </tr> - <tr> - <td>3.2.2 On Input (A)</td> - <td> - <p> - When data is inputted into a control, or a setting is changed, context - should not be changed unexpectedly. The user should be warned/advised - of the impending change before it occurs. - </p> - <p> - Again, sensible design should be implemented. For example, if pressing - a button causes the application to exit the current view, the user - should be asked to confirm this action, save their work if - appropriate, etc. - </p> - </td> - <td> - The {{domxref("Element/input_event", "input")}} event is useful here. - </td> - </tr> - <tr> - <td>3.2.3 Consistent Navigation (AA)</td> - <td> - <p> - Navigation menu/control style and positioning should be consistent - between different pages or views of a web page, and the existing items - should appear in the same order, even if for example new items are - added. If the user has initiated a change, e.g. choosing a different - color scheme or position for the navigation, their choice should be - respected across all pages. - </p> - <p> - Again, sensible design — make the navigation controls the same across - all pages or views. - </p> - </td> - <td> - See - <a href="/en-US/docs/Learn_web_development/Core/Accessibility/HTML#page_layouts" - >Page layouts</a - > - for information on modern markup for layouts. See also - <a - href="/en-US/docs/Learn_web_development/Core/Text_styling/Styling_links#styling_links_as_buttons" - >Styling links as buttons</a - > - for a useful accessible navigation menu example. - </td> - </tr> - <tr> - <td>3.2.4 Consistent Identification (AA)</td> - <td> - <p> - Controls or components that have the same functionality should be - identified in the same way across different pages or views. A currency - converter appearing on every page of a world travel site for example - should be exactly the same, semantically and in terms of labels. - </p> - <p>Again, sensible design!</p> - </td> - <td> - "Labels" can refer to descriptive information in text content, or HTML - form labels. See - <a href="/en-US/docs/Learn_web_development/Core/Accessibility/HTML#meaningful_text_labels" - >Meaningful text labels</a - > - for more information. - </td> - </tr> - <tr> - <td>3.2.5 Change on Request (AAA)</td> - <td> - <p> - Changes in context that could possibly confuse or disorient users - should only occur only when requested by the user, OR the user should - be able to turn them off. - </p> - <p> - If you need to have something that significantly changes the current - view (e.g. content or controls), let the user control when they want - that change to occur (e.g. what page to show, when to advance to the - next photo in the gallery...) - </p> - <p> - If you need to have something like a carousel on a page, provide an - option to stop it automatically advancing. Better to avoid such - functionality if possible. - </p> - </td> - </tr> - <tr> - <td> 3.2.6 Consistent help (A)</td> - <td> <p> Web pages that contain help mechanisms, including self-help options and human contact details, that are repeated on multiple web pages, need to place those mechanisms in the same order on all pages, unless a change is initiated by the user.</p> - <td> <p> Check out the <a href="https://www.w3.org/WAI/WCAG22/Understanding/consistent-help">consistent help documentation</a> for this standard to learn more. </p> - </td> - </td> - <tr> - </tr> - </tbody> -</table> - -> [!NOTE] -> Also see the WCAG description for [Guideline 3.2 Predictable: Make Web pages appear and operate in predictable ways](https://www.w3.org/TR/WCAG21/#predictable). - -## Guideline 3.3 — Input Assistance: Help users avoid and correct mistakes - -This guideline centers around helping users enter correct information when required with the minimum of mistakes. - -<table class="standard-table"> - <thead> - <tr> - <th scope="col">Success criteria</th> - <th scope="col">How to conform to the criteria</th> - <th scope="col">Practical resource</th> - </tr> - </thead> - <tbody> - <tr> - <td>3.3.1 Error Identification (A)</td> - <td> - <p> - When a user is filling out a form or choosing between options, any - error that is detected should be clearly reported to the user, along - with the form control that the error relates to. - </p> - <p> - It is advisable to implement client-side error detection and handling, - via HTML form validation features, and/or JavaScript, whatever is - best for your situation. When an error is detected, an intuitive error - message should be shown next to the form input that is at fault to - help the user correct their inputs. For screen reader users, you can - use aria live regions to alert the user to a change on the page. - </p> - <div class="note notecard"> - <p> - <strong>Note:</strong> Server-side validation should <em>always</em> be - used alongside client-side validation. Client-side validation is too - easy to turn off or otherwise get around, so it can't be relied on - alone. - </p> - </div> - </td> - <td> - See - <a href="/en-US/docs/Learn_web_development/Extensions/Forms/Form_validation" - >Form data validation</a - > - for comprehensive validation information, and - <a - href="/en-US/docs/Learn_web_development/Core/Accessibility/WAI-ARIA_basics#dynamic_content_updates" - >WAI-ARIA: Dynamic content updates</a - > - for information on live regions. - </td> - </tr> - <tr> - <td>3.3.2 Labels or Instructions (A)</td> - <td> - <p> - Clear instructions should be provided when data input is required. - When a simple instruction or prompt is required, you can use - {{htmlelement("label")}} elements for single inputs like name - or age, a combination or {{htmlelement("label")}}s and - {{htmlelement("fieldset")}}s/{{htmlelement("legend")}}s - for multiple inputs that go together (like the elements of a date of - birth or postal address). - </p> - <p> - When more complex explanation is required, you can always include - explanatory paragraphs too, or maybe you need to try to make your - forms more intuitive. - </p> - </td> - <td> - <ul> - <li> - <a - href="/en-US/docs/Learn_web_development/Core/Accessibility/HTML#meaningful_text_labels" - >Meaningful text labels</a - > - </li> - <li> - <a href="/en-US/docs/Learn_web_development/Extensions/Forms/How_to_structure_a_web_form" - >How to structure an HTML form</a - > - </li> - <li> - <a - href="/en-US/docs/Web/Accessibility/Understanding_WCAG/Text_labels_and_names" - >Text labels and names</a - > - </li> - </ul> - </td> - </tr> - <tr> - <td>3.3.3 Error Suggestion (AA)</td> - <td> - <p> - When an error is detected and suggestions for correction are known, - provide these to the user (e.g. suggesting alternatives when the user - is choosing a user name and has selected one that is already taken), - unless doing so would cause a security issue (e.g. when entering a - password) or context problem (e.g. they are trying to answer a - question in a quiz app). - </p> - <p> - In such cases, when this is appropriate, you'll probably use a - combination of JavaScript and server-side functionality to check if - the entry is correct, and if not, what viable suggestions can be given - to the user. Such suggestions should be displayed usefully in context, - just like error messages (see 3.3.1). - </p> - </td> - <td>No tutorial suggestions yet.</td> - </tr> - <tr> - <td>3.3.4 Error Prevention (Legal, Financial, Data) (AA)</td> - <td> - <p> - In the case of forms involved with entry of sensitive data (such as - legal agreements, e-commerce transactions, or personal data), at least - one of the following should be true: - </p> - <ul> - <li>Submissions are reversible.</li> - <li> - Data is checked for errors, and the user is given an opportunity to - correct them. - </li> - <li> - A mechanism is available for confirming and correcting information - before final submission. - </li> - </ul> - </td> - <td> - <p> - <strong>Reversible</strong> — for any view where data can be entered, - provide an equivalent view that allows you to edit or even delete an - entry, as appropriate (for example, see - <a href="/en-US/docs/Learn_web_development/Extensions/Server-side/Django">Django web framework</a - >). - </p> - <p> - <strong>Checking data</strong> — as covered in 3.3.1, a combination of - client-side and server-side validation should be used to detect errors - and display helpful messages to the user to allow them to correct - their inputs. - </p> - <p> - <strong>Confirm and correct</strong> — where appropriate, after - filling in a series of form fields to perform a task (such as buying a - product), the user should be shown a confirmation screen where they - can review their inputs and correct anything that doesn't look right. - This pattern is commonly used on e-commerce sites like Amazon. - </p> - </td> - </tr> - <tr> - <td>3.3.5 Context-sensitive help is available (AAA)</td> - <td> - Provide instructions and other appropriate cues in context to aid form - completion and submission. - </td> - <td> - This really just builds on 3.3.1 and other similar criteria but requires - more thorough contextual help information and services, e.g. providing a - dedicated link to a help page or service on each page, providing - examples showing what successful completion should look like. - </td> - </tr> - <tr> - <td>3.3.6 Error Prevention (All) (AAA)</td> - <td> - This principle builds on 3.3.4, extending its requirements to all user - input situations, not just ones involving sensitive data. - </td> - <td>Again, see 3.3.4.</td> - </tr> - <tr> - <td> 3.3.7 Redundant entry (A) </td> - <td> - Information that is required that was previously entered or provided by the user in the same process or user flow is either auto-populated or made selectable to the user from a list of options, unless re-entering the information is essential or required for security reasons, or if the information is no longer valid. - </td> - <td>Check out <a href="https://www.w3.org/WAI/WCAG22/Understanding/redundant-entry">Understanding redundant entry</a> to learn more.</td> - </tr> - <tr> - <td> 3.3.8 Accessible authentication (Minimum) (AA) - </td> - <td> -Cognitive function tests, like remembering a password, are not required for any step in an authentication process unless an alternative is provided, such as an object or personal content (e.g., images, videos, and audio) recognition, or a mechanism to assist (e.g., copy and paste and autosave passwords). - </td> - <td> Check out the <a href="https://www.w3.org/WAI/WCAG22/Understanding/accessible-authentication-minimum"> accessible authentication documentation</a> for this standard to learn more. </td> - </tr> - <tr> - <td> 3.3.9 Accessible Authentication (Enhanced) (AAA) </td> - <td> -A cognitive function test, like remembering a password, must not be required for any step in an authentication process without providing an alternative that does not rely on a cognitive function test or provides a mechanism to assist the user in completing the cognitive function test. Authentication tests that require the user to recognize objects or identify non-text content the user provided to the website are allowed. - </td> -<td> Check out the <a href="https://www.w3.org/WAI/WCAG22/Understanding/accessible-authentication-enhanced">enhanced accessible authentication documentation (AAA)</a> to learn more.</td> - </tr> - </tbody> -</table> - -> [!NOTE] -> Also see the WCAG description for [Guideline 3.3 Input Assistance: Help users avoid and correct mistakes](https://www.w3.org/TR/WCAG21/#input-assistance). - -## See also - -- [WCAG](/en-US/docs/Web/Accessibility/Understanding_WCAG) - - 1. [Perceivable](/en-US/docs/Web/Accessibility/Understanding_WCAG/Perceivable) - 2. [Operable](/en-US/docs/Web/Accessibility/Understanding_WCAG/Operable) - 3. Understandable - 4. [Robust](/en-US/docs/Web/Accessibility/Understanding_WCAG/Robust) diff --git a/files/en-us/web/api/abortsignal/abort_event/index.md b/files/en-us/web/api/abortsignal/abort_event/index.md index f15cf33a720eeed..15a5e734991cc57 100644 --- a/files/en-us/web/api/abortsignal/abort_event/index.md +++ b/files/en-us/web/api/abortsignal/abort_event/index.md @@ -8,14 +8,14 @@ browser-compat: api.AbortSignal.abort_event {{APIRef("DOM")}}{{AvailableInWorkers}} -The **`abort`** event of the {{domxref("AbortSignal")}} is fired when the associated request is aborted, i.e. using {{domxref("AbortController.abort()")}}. +The **`abort`** event of the {{domxref("AbortSignal")}} is fired when the associated request is aborted, i.e., using {{domxref("AbortController.abort()")}}. ## Syntax Use the event name in methods like {{domxref("EventTarget.addEventListener", "addEventListener()")}}, or set an event handler property. ```js-nolint -addEventListener('abort', (event) => { }) +addEventListener("abort", (event) => { }) onabort = (event) => { } ``` diff --git a/files/en-us/web/api/abortsignal/abort_static/index.md b/files/en-us/web/api/abortsignal/abort_static/index.md index 465ec2bc3546221..3d93f576a52b7c2 100644 --- a/files/en-us/web/api/abortsignal/abort_static/index.md +++ b/files/en-us/web/api/abortsignal/abort_static/index.md @@ -18,7 +18,7 @@ controller.abort(); return controller.signal; ``` -This could, for example, be passed to a fetch method in order to run its abort logic (i.e. it may be that code is organized such that the abort logic should be run even if the intended fetch operation has not been started). +This could, for example, be passed to a fetch method in order to run its abort logic (i.e., it may be that code is organized such that the abort logic should be run even if the intended fetch operation has not been started). > [!NOTE] > The method is similar in purpose to {{JSxRef("Promise.reject")}}. diff --git a/files/en-us/web/api/abortsignal/any_static/index.md b/files/en-us/web/api/abortsignal/any_static/index.md index 3fc1999a6e30484..3fd3338d5c9720e 100644 --- a/files/en-us/web/api/abortsignal/any_static/index.md +++ b/files/en-us/web/api/abortsignal/any_static/index.md @@ -60,7 +60,7 @@ try { }); const body = await res.blob(); // Do something with downloaded content: - // ... + // … } catch (e) { if (e.name === "AbortError") { // Cancelled by the user diff --git a/files/en-us/web/api/absoluteorientationsensor/index.md b/files/en-us/web/api/absoluteorientationsensor/index.md index 2500da58a28ba55..33776c86786357a 100644 --- a/files/en-us/web/api/absoluteorientationsensor/index.md +++ b/files/en-us/web/api/absoluteorientationsensor/index.md @@ -11,7 +11,7 @@ The **`AbsoluteOrientationSensor`** interface of the [Sensor APIs](/en-US/docs/W To use this sensor, the user must grant permission to the `'accelerometer'`, `'gyroscope'`, and `'magnetometer'` device sensors through the [Permissions API](/en-US/docs/Web/API/Permissions_API). -This feature may be blocked by a [Permissions Policy](/en-US/docs/Web/HTTP/Permissions_Policy) set on your server. +This feature may be blocked by a [Permissions Policy](/en-US/docs/Web/HTTP/Guides/Permissions_Policy) set on your server. {{InheritanceDiagram}} diff --git a/files/en-us/web/api/accelerometer/accelerometer/index.md b/files/en-us/web/api/accelerometer/accelerometer/index.md index bf8b42cf312dd1a..04e04bf4e194c3c 100644 --- a/files/en-us/web/api/accelerometer/accelerometer/index.md +++ b/files/en-us/web/api/accelerometer/accelerometer/index.md @@ -33,7 +33,7 @@ new Accelerometer(options) ### Exceptions - `SecurityError` {{domxref("DOMException")}} - - : Use of this feature was blocked by a [Permissions Policy](/en-US/docs/Web/HTTP/Permissions_Policy). + - : Use of this feature was blocked by a [Permissions Policy](/en-US/docs/Web/HTTP/Guides/Permissions_Policy). ## Specifications diff --git a/files/en-us/web/api/accelerometer/index.md b/files/en-us/web/api/accelerometer/index.md index 327c7f3067eb6ec..8d9876a28caa50c 100644 --- a/files/en-us/web/api/accelerometer/index.md +++ b/files/en-us/web/api/accelerometer/index.md @@ -13,7 +13,7 @@ The **`Accelerometer`** interface of the [Sensor APIs](/en-US/docs/Web/API/Senso To use this sensor, the user must grant permission to the `'accelerometer'`, device sensor through the [Permissions API](/en-US/docs/Web/API/Permissions_API). -This feature may be blocked by a [Permissions Policy](/en-US/docs/Web/HTTP/Permissions_Policy) set on your server. +This feature may be blocked by a [Permissions Policy](/en-US/docs/Web/HTTP/Guides/Permissions_Policy) set on your server. {{InheritanceDiagram}} diff --git a/files/en-us/web/api/aesgcmparams/index.md b/files/en-us/web/api/aesgcmparams/index.md index 3943bd46d75f4b9..178d2a855b8ee52 100644 --- a/files/en-us/web/api/aesgcmparams/index.md +++ b/files/en-us/web/api/aesgcmparams/index.md @@ -29,7 +29,7 @@ For details of how to supply appropriate values for this parameter, see the spec - : A `Number`. This determines the size in bits of the authentication tag generated in the encryption operation and used for authentication in the corresponding decryption. - According to the [Web Crypto specification](https://www.w3.org/TR/WebCryptoAPI/#dfn-AesGcmParams) this must have one of the following values: 32, 64, 96, 104, 112, 120, or 128. The AES-GCM specification recommends that it should be 96, 104, 112, 120 or 128, although 32 or 64 bits may be acceptable in some applications: [Appendix C of the specification](https://nvlpubs.nist.gov/nistpubs/Legacy/SP/nistspecialpublication800-38d.pdf#%5B%7B%22num%22%3A92%2C%22gen%22%3A0%7D%2C%7B%22name%22%3A%22XYZ%22%7D%2C0%2C792%2Cnull%5D) provides additional guidance here. + The [Web Crypto API specification](https://w3c.github.io/webcrypto/#aes-gcm-operations-encrypt) requires this to have one of the following values: 32, 64, 96, 104, 112, 120, or 128. On the other hand, the AES-GCM specification recommends that it should be 96, 104, 112, 120, or 128, although 32 or 64 bits may be acceptable in some applications. For additional guidance, see [Appendix C](https://nvlpubs.nist.gov/nistpubs/Legacy/SP/nistspecialpublication800-38d.pdf#%5B%7B%22num%22%3A92%2C%22gen%22%3A0%7D%2C%7B%22name%22%3A%22XYZ%22%7D%2C0%2C792%2Cnull%5D) of the NIST Publication on "Recommendation for Block Cipher Modes of Operation". `tagLength` is optional and defaults to 128 if it is not specified. diff --git a/files/en-us/web/api/ambientlightsensor/ambientlightsensor/index.md b/files/en-us/web/api/ambientlightsensor/ambientlightsensor/index.md index 0a5f213d53c3e74..b192ea562dfb1fc 100644 --- a/files/en-us/web/api/ambientlightsensor/ambientlightsensor/index.md +++ b/files/en-us/web/api/ambientlightsensor/ambientlightsensor/index.md @@ -31,7 +31,7 @@ new AmbientLightSensor(options) ### Exceptions - `SecurityError` {{domxref("DOMException")}} - - : Use of this feature was blocked by a [Permissions Policy](/en-US/docs/Web/HTTP/Permissions_Policy). + - : Use of this feature was blocked by a [Permissions Policy](/en-US/docs/Web/HTTP/Guides/Permissions_Policy). ## Specifications diff --git a/files/en-us/web/api/ambientlightsensor/index.md b/files/en-us/web/api/ambientlightsensor/index.md index 383e81b47b47376..82ecd8d58dfd0a1 100644 --- a/files/en-us/web/api/ambientlightsensor/index.md +++ b/files/en-us/web/api/ambientlightsensor/index.md @@ -13,7 +13,7 @@ The **`AmbientLightSensor`** interface of the [Sensor APIs](/en-US/docs/Web/API/ To use this sensor, the user must grant permission to the `'ambient-light-sensor'` device sensor through the [Permissions API](/en-US/docs/Web/API/Permissions_API). -This feature may be blocked by a [Permissions Policy](/en-US/docs/Web/HTTP/Permissions_Policy) set on your server. +This feature may be blocked by a [Permissions Policy](/en-US/docs/Web/HTTP/Guides/Permissions_Policy) set on your server. {{InheritanceDiagram}} diff --git a/files/en-us/web/api/analysernode/getfloatfrequencydata/index.md b/files/en-us/web/api/analysernode/getfloatfrequencydata/index.md index 555a52d01e33350..4cae137c19f89fb 100644 --- a/files/en-us/web/api/analysernode/getfloatfrequencydata/index.md +++ b/files/en-us/web/api/analysernode/getfloatfrequencydata/index.md @@ -53,25 +53,25 @@ For more complete applied examples/information, check out our [Voice-change-O-ma <script> const audioCtx = new AudioContext(); - //Create audio source - //Here, we use an audio file, but this could also be e.g. microphone input + // Create audio source + // Here, we use an audio file, but this could also be e.g. microphone input const audioEle = new Audio(); - audioEle.src = "my-audio.mp3"; //insert file name here + audioEle.src = "my-audio.mp3"; // Insert file name here audioEle.autoplay = true; audioEle.preload = "auto"; const audioSourceNode = audioCtx.createMediaElementSource(audioEle); - //Create analyser node + // Create analyser node const analyserNode = audioCtx.createAnalyser(); analyserNode.fftSize = 256; const bufferLength = analyserNode.frequencyBinCount; const dataArray = new Float32Array(bufferLength); - //Set up audio node network + // Set up audio node network audioSourceNode.connect(analyserNode); analyserNode.connect(audioCtx.destination); - //Create 2D canvas + // Create 2D canvas const canvas = document.createElement("canvas"); canvas.style.position = "absolute"; canvas.style.top = "0"; @@ -83,17 +83,17 @@ For more complete applied examples/information, check out our [Voice-change-O-ma canvasCtx.clearRect(0, 0, canvas.width, canvas.height); function draw() { - //Schedule next redraw + // Schedule next redraw requestAnimationFrame(draw); - //Get spectrum data + // Get spectrum data analyserNode.getFloatFrequencyData(dataArray); - //Draw black background + // Draw black background canvasCtx.fillStyle = "rgb(0 0 0)"; canvasCtx.fillRect(0, 0, canvas.width, canvas.height); - //Draw spectrum + // Draw spectrum const barWidth = (canvas.width / bufferLength) * 2.5; let posX = 0; for (let i = 0; i < bufferLength; i++) { diff --git a/files/en-us/web/api/animation/cancel_event/index.md b/files/en-us/web/api/animation/cancel_event/index.md index e930979300427ce..af6671f07d1ffe2 100644 --- a/files/en-us/web/api/animation/cancel_event/index.md +++ b/files/en-us/web/api/animation/cancel_event/index.md @@ -19,6 +19,7 @@ Use the event name in methods like {{domxref("EventTarget.addEventListener", "ad ```js-nolint addEventListener("cancel", (event) => { }) + oncancel = (event) => { } ``` diff --git a/files/en-us/web/api/animation/commitstyles/index.md b/files/en-us/web/api/animation/commitstyles/index.md index c2dd929dac0a8f2..641ed734c45657c 100644 --- a/files/en-us/web/api/animation/commitstyles/index.md +++ b/files/en-us/web/api/animation/commitstyles/index.md @@ -8,11 +8,11 @@ browser-compat: api.Animation.commitStyles {{APIRef("Web Animations")}} -The `commitStyles()` method of the [Web Animations API](/en-US/docs/Web/API/Web_Animations_API)'s {{domxref("Animation")}} interface writes the [computed values](/en-US/docs/Web/CSS/CSS_cascade/computed_value) of the animation's current styles into its target element's [`style`](/en-US/docs/Web/HTML/Global_attributes/style) attribute. `commitStyles()` works even if the animation has been [automatically removed](/en-US/docs/Web/API/Web_Animations_API/Using_the_Web_Animations_API#automatically_removing_filling_animations). +The `commitStyles()` method of the [Web Animations API](/en-US/docs/Web/API/Web_Animations_API)'s {{domxref("Animation")}} interface writes the [computed values](/en-US/docs/Web/CSS/CSS_cascade/Value_processing#computed_value) of the animation's current styles into its target element's [`style`](/en-US/docs/Web/HTML/Reference/Global_attributes/style) attribute. `commitStyles()` works even if the animation has been [automatically removed](/en-US/docs/Web/API/Web_Animations_API/Using_the_Web_Animations_API#automatically_removing_filling_animations). `commitStyles()` can be used in combination with `fill` to cause the final state of an animation to persist after the animation ends. The same effect could be achieved with `fill` alone, but [using indefinitely filling animations is discouraged](https://drafts.csswg.org/web-animations-1/#fill-behavior). Animations [take precedence over all static styles](/en-US/docs/Web/CSS/CSS_cascade/Cascade#cascading_order), so an indefinite filling animation can prevent the target element from ever being styled normally. -Using `commitStyles()` writes the styling state into the element's [`style`](/en-US/docs/Web/HTML/Global_attributes/style) attribute, where they can be modified and replaced as normal. +Using `commitStyles()` writes the styling state into the element's [`style`](/en-US/docs/Web/HTML/Reference/Global_attributes/style) attribute, where they can be modified and replaced as normal. ## Syntax diff --git a/files/en-us/web/api/animation/finish/index.md b/files/en-us/web/api/animation/finish/index.md index 5dcbe6f0144089f..c6d57dc86019e5e 100644 --- a/files/en-us/web/api/animation/finish/index.md +++ b/files/en-us/web/api/animation/finish/index.md @@ -43,7 +43,7 @@ interfaceElement.addEventListener("mousedown", () => { if (e instanceof InvalidState) { console.log("finish() called on paused or finished animation."); } else { - logMyErrors(e); //pass exception object to error handler + logMyErrors(e); // Pass exception object to error handler } } }); diff --git a/files/en-us/web/api/animation/finish_event/index.md b/files/en-us/web/api/animation/finish_event/index.md index 535e2542df25f3d..dcd43fd56de4289 100644 --- a/files/en-us/web/api/animation/finish_event/index.md +++ b/files/en-us/web/api/animation/finish_event/index.md @@ -25,6 +25,7 @@ Use the event name in methods like {{domxref("EventTarget.addEventListener", "ad ```js-nolint addEventListener("finish", (event) => { }) + onfinish = (event) => { } ``` diff --git a/files/en-us/web/api/animation/index.md b/files/en-us/web/api/animation/index.md index 148b052a41d069a..38686e9e40491cf 100644 --- a/files/en-us/web/api/animation/index.md +++ b/files/en-us/web/api/animation/index.md @@ -75,12 +75,12 @@ The **`Animation`** interface of the [Web Animations API](/en-US/docs/Web/API/We Blinking and flashing animation can be problematic for people with cognitive concerns such as Attention Deficit Hyperactivity Disorder (ADHD). Additionally, certain kinds of motion can be a trigger for Vestibular disorders, epilepsy, and migraine, and Scotopic sensitivity. -Consider providing a mechanism for pausing or disabling animation, as well as using the [Reduced Motion Media Query](/en-US/docs/Web/CSS/@media/prefers-reduced-motion) (or equivalent [user agent client hint](/en-US/docs/Web/HTTP/Client_hints#user-agent_client_hints) {{HTTPHeader("Sec-CH-Prefers-Reduced-Motion")}}) to create a complimentary experience for users who have expressed a preference for no animated experiences. +Consider providing a mechanism for pausing or disabling animation, as well as using the [Reduced Motion Media Query](/en-US/docs/Web/CSS/@media/prefers-reduced-motion) (or equivalent [user agent client hint](/en-US/docs/Web/HTTP/Guides/Client_hints#user_agent_client_hints) {{HTTPHeader("Sec-CH-Prefers-Reduced-Motion")}}) to create a complimentary experience for users who have expressed a preference for no animated experiences. - [Designing Safer Web Animation For Motion Sensitivity · An A List Apart Article](https://alistapart.com/article/designing-safer-web-animation-for-motion-sensitivity/) - [An Introduction to the Reduced Motion Media Query | CSS-Tricks](https://css-tricks.com/introduction-reduced-motion-media-query/) - [Responsive Design for Motion | WebKit](https://webkit.org/blog/7551/responsive-design-for-motion/) -- [MDN Understanding WCAG, Guideline 2.2 explanations](/en-US/docs/Web/Accessibility/Understanding_WCAG/Operable#guideline_2.2_%e2%80%94_enough_time_provide_users_enough_time_to_read_and_use_content) +- [MDN Understanding WCAG, Guideline 2.2 explanations](/en-US/docs/Web/Accessibility/Guides/Understanding_WCAG/Operable#guideline_2.2_%e2%80%94_enough_time_provide_users_enough_time_to_read_and_use_content) - [Understanding Success Criterion 2.2.2 | W3C Understanding WCAG 2.0](https://www.w3.org/TR/UNDERSTANDING-WCAG20/time-limits-pause.html) ## Specifications diff --git a/files/en-us/web/api/animation/overallprogress/index.md b/files/en-us/web/api/animation/overallprogress/index.md index bf7214bbf8f8ee2..87f3721020d2935 100644 --- a/files/en-us/web/api/animation/overallprogress/index.md +++ b/files/en-us/web/api/animation/overallprogress/index.md @@ -50,7 +50,6 @@ html { } body { - margin: 0; width: 500px; margin: 0 auto; padding: 20px; diff --git a/files/en-us/web/api/animation/remove_event/index.md b/files/en-us/web/api/animation/remove_event/index.md index 57647309b921026..837ee448b87e9c8 100644 --- a/files/en-us/web/api/animation/remove_event/index.md +++ b/files/en-us/web/api/animation/remove_event/index.md @@ -15,7 +15,8 @@ The **`remove`** event of the {{domxref("Animation")}} interface fires when the Use the event name in methods like {{domxref("EventTarget.addEventListener", "addEventListener()")}}, or set an event handler property. ```js-nolint -addEventListener('remove', (event) => { }) +addEventListener("remove", (event) => { }) + onremove = (event) => { } ``` diff --git a/files/en-us/web/api/attribution_reporting_api/generating_reports/index.md b/files/en-us/web/api/attribution_reporting_api/generating_reports/index.md index 8af86149df5d079..0e9ac1bb4b54bd0 100644 --- a/files/en-us/web/api/attribution_reporting_api/generating_reports/index.md +++ b/files/en-us/web/api/attribution_reporting_api/generating_reports/index.md @@ -12,7 +12,7 @@ This article explains how [Attribution Reporting API](/en-US/docs/Web/API/Attrib ## Basic process -When a match occurs between a trigger and a source, the browser generates a report and sends it via an uncredentialed [`POST`](/en-US/docs/Web/HTTP/Methods/POST) request to a specific endpoint on the reporting origin: +When a match occurs between a trigger and a source, the browser generates a report and sends it via an uncredentialed [`POST`](/en-US/docs/Web/HTTP/Reference/Methods/POST) request to a specific endpoint on the reporting origin: - For event-level reports, this is `<reporting-origin>/.well-known/attribution-reporting/report-event-attribution`. - For summary reports, this is `<reporting-origin>/.well-known/attribution-reporting/report-aggregate-attribution`. @@ -23,14 +23,14 @@ The report data is contained in a JSON structure. ## Event-level reports -Event-level reports are generated and scheduled to be sent at the end of their containing **report window**. The length of the report window is determined by the values set in the [`"event_report_window"`](/en-US/docs/Web/HTTP/Headers/Attribution-Reporting-Register-Source#event_report_window) or [`"event_report_windows"`](/en-US/docs/Web/HTTP/Headers/Attribution-Reporting-Register-Source#event_report_windows) field set in the source's {{httpheader("Attribution-Reporting-Register-Source")}} header. +Event-level reports are generated and scheduled to be sent at the end of their containing **report window**. The length of the report window is determined by the values set in the [`"event_report_window"`](/en-US/docs/Web/HTTP/Reference/Headers/Attribution-Reporting-Register-Source#event_report_window) or [`"event_report_windows"`](/en-US/docs/Web/HTTP/Reference/Headers/Attribution-Reporting-Register-Source#event_report_windows) field set in the source's {{httpheader("Attribution-Reporting-Register-Source")}} header. If neither of these fields are specified, the report window falls back to the following defaults: -- For [event-based sources](/en-US/docs/Web/API/Attribution_Reporting_API/Registering_sources#event-based_attribution_sources), the default report window ends at the source's expiry, which is set in the `Attribution-Reporting-Register-Source` [`"expiry"`](/en-US/docs/Web/HTTP/Headers/Attribution-Reporting-Register-Source#expiry) field. This defaults to 30 days after registration if not explicitly set. +- For [event-based sources](/en-US/docs/Web/API/Attribution_Reporting_API/Registering_sources#event-based_attribution_sources), the default report window ends at the source's expiry, which is set in the `Attribution-Reporting-Register-Source` [`"expiry"`](/en-US/docs/Web/HTTP/Reference/Headers/Attribution-Reporting-Register-Source#expiry) field. This defaults to 30 days after registration if not explicitly set. - For [navigation-based sources](/en-US/docs/Web/API/Attribution_Reporting_API/Registering_sources#navigation-based_attribution_sources), the default report windows are 2 days, 7 days, and the source's `"expiry"`. -See [Custom report windows](https://developers.google.com/privacy-sandbox/private-advertising/attribution-reporting/custom-report-windows) for more details. +See [Custom report windows](https://privacysandbox.google.com/private-advertising/attribution-reporting/custom-report-windows) for more details. Once an event-level report is received at the appropriate endpoint, how the data is processed, stored, and displayed is completely up to the developer. A typical event-level report might look like this: @@ -51,11 +51,11 @@ Once an event-level report is received at the appropriate endpoint, how the data The properties are as follows: - `"attribution_destination"` - - : A string, or an array of 2–3 strings, depending on whether the source was registered with multiple destinations or not. These strings represent the attribution [`"destination"`](/en-US/docs/Web/HTTP/Headers/Attribution-Reporting-Register-Source#destination) site(s) set in the source registration via the associated {{httpheader("Attribution-Reporting-Register-Source")}} response header. + - : A string, or an array of 2–3 strings, depending on whether the source was registered with multiple destinations or not. These strings represent the attribution [`"destination"`](/en-US/docs/Web/HTTP/Reference/Headers/Attribution-Reporting-Register-Source#destination) site(s) set in the source registration via the associated {{httpheader("Attribution-Reporting-Register-Source")}} response header. - `"source_event_id"` - - : A string representing the attribution source ID. This is equal to the [`"source_event_id"`](/en-US/docs/Web/HTTP/Headers/Attribution-Reporting-Register-Source#source_event_id) set in the source registration (via the associated {{httpheader("Attribution-Reporting-Register-Source")}} response header). + - : A string representing the attribution source ID. This is equal to the [`"source_event_id"`](/en-US/docs/Web/HTTP/Reference/Headers/Attribution-Reporting-Register-Source#source_event_id) set in the source registration (via the associated {{httpheader("Attribution-Reporting-Register-Source")}} response header). - `"trigger_data"` - - : A string representing data originating from the attribution trigger, set in the trigger registration (the [`"trigger_data"`](/en-US/docs/Web/HTTP/Headers/Attribution-Reporting-Register-Trigger#trigger_data) set via the associated {{httpheader("Attribution-Reporting-Register-Trigger")}} response header). + - : A string representing data originating from the attribution trigger, set in the trigger registration (the [`"trigger_data"`](/en-US/docs/Web/HTTP/Reference/Headers/Attribution-Reporting-Register-Trigger#trigger_data) set via the associated {{httpheader("Attribution-Reporting-Register-Trigger")}} response header). - `"report_id"` - : A string representing a [Universally Unique Identifier (UUID)](/en-US/docs/Glossary/UUID) for this report, which can be used to prevent duplicate counting. - `"source_type"` @@ -65,17 +65,17 @@ The properties are as follows: - `"scheduled_report_time"` - : A string representing the number of seconds from the Unix Epoch until the browser initially scheduled the report to be sent (to avoid inaccuracies as a result of offline devices reporting late). - `"source_debug_key"` {{optional_inline}} - - : A 64 bit unsigned integer representing the debugging key for the attribution source. This mirrors the value set in the associated {{httpheader("Attribution-Reporting-Register-Source")}} header's [`"debug_key"`](/en-US/docs/Web/HTTP/Headers/Attribution-Reporting-Register-Source#debug_key) field. See [Debug reports](#debug_reports) for more information. + - : A 64 bit unsigned integer representing the debugging key for the attribution source. This mirrors the value set in the associated {{httpheader("Attribution-Reporting-Register-Source")}} header's [`"debug_key"`](/en-US/docs/Web/HTTP/Reference/Headers/Attribution-Reporting-Register-Source#debug_key) field. See [Debug reports](#debug_reports) for more information. - `"trigger_debug_key"` {{optional_inline}} - : A 64 bit unsigned integer representing the debugging key for the attribution trigger. This mirrors the value set in the associated {{httpheader("Attribution-Reporting-Register-Trigger")}} header's `"debug_key"` field. See [Debug reports](#debug_reports) for more information. ## Summary reports -A summary report is created from several aggregatable reports received at the appropriate endpoint and then [batched](https://developers.google.com/privacy-sandbox/private-advertising/attribution-reporting/summary-reports-intro#batching) to prepare them to be processed by an [aggregation service](https://developers.google.com/privacy-sandbox/private-advertising/aggregation-service). When this has occurred, how the data is processed, stored, and displayed is completely up to the developer. +A summary report is created from several aggregatable reports received at the appropriate endpoint and then [batched](https://privacysandbox.google.com/private-advertising/attribution-reporting/summary-reports-intro#batching) to prepare them to be processed by an [aggregation service](https://privacysandbox.google.com/private-advertising/aggregation-service). When this has occurred, how the data is processed, stored, and displayed is completely up to the developer. An aggregatable report by default is generated and scheduled to be sent after a trigger is interacted with, with a random delay to help fuzz the timings and improve privacy. For a given registered attribution source, attribution source events will be recorded from registration up until the source expires - this is referred to as the **report window**. -The expiry time is defined by the `expiry` value set in the associated {{httpheader("Attribution-Reporting-Register-Source")}} header, which defaults to 30 days after registration if not explicitly set. Bear in mind that the length of the report window can be further modified by setting an `aggregatable_report_window` value in the `Attribution-Reporting-Register-Source` header. See [Custom report windows](https://developers.google.com/privacy-sandbox/private-advertising/attribution-reporting/custom-report-windows) for more details. +The expiry time is defined by the `expiry` value set in the associated {{httpheader("Attribution-Reporting-Register-Source")}} header, which defaults to 30 days after registration if not explicitly set. Bear in mind that the length of the report window can be further modified by setting an `aggregatable_report_window` value in the `Attribution-Reporting-Register-Source` header. See [Custom report windows](https://privacysandbox.google.com/private-advertising/attribution-reporting/custom-report-windows) for more details. > [!NOTE] > To further protect user privacy, the summary report values associated with each attribution source have a finite total value — this is called the **contribution budget**. This value may very across different implementations of the API; in Chrome it is 65,536. Any conversions that would generate reports adding values over that limit are not recorded. Make sure you keep track of the budget and share it between the different metrics you are trying to measure. @@ -105,7 +105,7 @@ The properties are as follows: - `"api"` - : A enumerated value representing the API that triggered the report generation. Currently this will always be equal to `"attribution-reporting"`, but it may be extended with additional values to support other APIs in the future. - `"attribution_destination"` - - : A string representing the attribution [`"destination"`](/en-US/docs/Web/HTTP/Headers/Attribution-Reporting-Register-Source#destination) URL set in the source registration (via the associated {{httpheader("Attribution-Reporting-Register-Source")}} response header). + - : A string representing the attribution [`"destination"`](/en-US/docs/Web/HTTP/Reference/Headers/Attribution-Reporting-Register-Source#destination) URL set in the source registration (via the associated {{httpheader("Attribution-Reporting-Register-Source")}} response header). - `"report_id"` - : A string representing a [Universally Unique Identifier (UUID)](/en-US/docs/Glossary/UUID) for this report, which can be used to prevent duplicate counting. - `"reporting_origin"` @@ -122,18 +122,23 @@ The properties are as follows: - `"payload"` - - : A [CBOR](https://cbor.io/) map encrypted via [HPKE](https://datatracker.ietf.org/doc/rfc9180/) and then [base64](/en-US/docs/Glossary/Base64)-encoded, with the following structure: + - : A [CBOR](https://cbor.io/) map encrypted via [HPKE](https://datatracker.ietf.org/doc/rfc9180/) and then [base64](/en-US/docs/Glossary/Base64)-encoded, with the following structure (using JSON for notation only): - ```js + ```json { - "operation": "histogram", // Allows for the service to support other operations in the future - "data": [{ - "bucket": <bucket, encoded as a 16-byte (i.e. 128-bit) big-endian bytestring>, - "value": <value, encoded as a 4-byte (i.e. 32-bit) big-endian bytestring> - }, ...] + "operation": "histogram", + "data": [ + { + "bucket": "<Encoded as a 16-byte (i.e. 128-bit) big-endian bytestring>", + "value": "<Encoded as a 4-byte (i.e. 32-bit) big-endian bytestring>" + } + // … + ] } ``` + The `operation` is always `"histogram"`; it allows for the service to support other operations in the future. + - `"key_id"` - : A string identifying the public key used to encrypt the payload. - `"debug_cleartext_payload"` {{optional_inline}} @@ -142,7 +147,7 @@ The properties are as follows: - `"aggregation_coordinator_origin"` - : The deployment option for the aggregation service. - `"source_debug_key"` {{optional_inline}} - - : A 64 bit unsigned integer representing the debugging key for the attribution source. This mirrors the value set in the associated {{httpheader("Attribution-Reporting-Register-Source")}} header's [`"debug_key"`](/en-US/docs/Web/HTTP/Headers/Attribution-Reporting-Register-Source#debug_key) field. See [Debug reports](#debug_reports) for more information. + - : A 64 bit unsigned integer representing the debugging key for the attribution source. This mirrors the value set in the associated {{httpheader("Attribution-Reporting-Register-Source")}} header's [`"debug_key"`](/en-US/docs/Web/HTTP/Reference/Headers/Attribution-Reporting-Register-Source#debug_key) field. See [Debug reports](#debug_reports) for more information. - `"trigger_debug_key"` {{optional_inline}} - : A 64 bit unsigned integer representing the debugging key for the attribution trigger. This mirrors the value set in the associated {{httpheader("Attribution-Reporting-Register-Trigger")}} header's `"debug_key"` field. See [Debug reports](#debug_reports) for more information. @@ -154,7 +159,7 @@ THIS INFORMATION IS NOT COMPLETE; WE HAVE PARKED IT FOR NOW SO THAT WE CAN GET T In the case of event-level reports, this is done using a randomized response algorithm, which works like so: 1. When an attribution source is stored, the browser generates a list of all possible sets of reports that could originate from the source's configuration (including the set consisting of no reports). -2. In a small percentage of cases, the browser prevents the source from being attributed and instead picks a random member of that list to use as the source's reports. The probability of this happening is based on the size of that list, the browser's implementation-specific privacy parameters, and the source's chosen [`"event_level_epsilon"`](/en-US/docs/Web/HTTP/Headers/Attribution-Reporting-Register-Source#event_level_epsilon). +2. In a small percentage of cases, the browser prevents the source from being attributed and instead picks a random member of that list to use as the source's reports. The probability of this happening is based on the size of that list, the browser's implementation-specific privacy parameters, and the source's chosen [`"event_level_epsilon"`](/en-US/docs/Web/HTTP/Reference/Headers/Attribution-Reporting-Register-Source#event_level_epsilon). Typical settings in the {{httpheader("Attribution-Reporting-Register-Source")}} header might look like so: @@ -191,9 +196,9 @@ Noise is added to reports in order to obscure the output associated with a parti For information on how noise works in attribution reporting, see: -- [Understanding noise in summary reports](https://developers.google.com/privacy-sandbox/private-advertising/attribution-reporting/understanding-noise). +- [Understanding noise in summary reports](https://privacysandbox.google.com/private-advertising/attribution-reporting/understanding-noise). - [Data limits and noise](https://github.com/WICG/attribution-reporting-api/blob/main/EVENT.md#data-limits-and-noise) -- [Working with noise](https://developers.google.com/privacy-sandbox/private-advertising/attribution-reporting/working-with-noise) +- [Working with noise](https://privacysandbox.google.com/private-advertising/attribution-reporting/working-with-noise) ## Report priorities and limits @@ -207,7 +212,7 @@ Different source types have different default limits: - [Event-based attribution sources](/en-US/docs/Web/API/Attribution_Reporting_API/Registering_sources#event-based_attribution_sources) have a one-report limit by default. > [!NOTE] -> The report limit can be adjusted by setting a different number of `"end_times"` in the [`"event_report_windows"`](/en-US/docs/Web/HTTP/Headers/Attribution-Reporting-Register-Source#event_report_windows) fields of the associated `Attribution-Reporting-Register-Source` header. +> The report limit can be adjusted by setting a different number of `"end_times"` in the [`"event_report_windows"`](/en-US/docs/Web/HTTP/Reference/Headers/Attribution-Reporting-Register-Source#event_report_windows) fields of the associated `Attribution-Reporting-Register-Source` header. When an attribution is triggered for a given source event, if the maximum number of attributions (three for clicks, one for images/scripts) has been reached for this source the browser will: @@ -343,6 +348,6 @@ Generated success debug reports are identical to attribution reports, and contai For further information and examples, see: -- [Introduction to debug reports](https://developers.google.com/privacy-sandbox/private-advertising/attribution-reporting/attribution-reporting-debugging/) on developers.google.com (2023) -- [Set up debug reports](https://developers.google.com/privacy-sandbox/private-advertising/attribution-reporting/attribution-reporting-debugging/part-2/) on developers.google.com (2023) -- [Debugging cookbook](https://developers.google.com/privacy-sandbox/private-advertising/attribution-reporting/attribution-reporting-debugging/part-3/) on developers.google.com (2023) +- [Introduction to debug reports](https://privacysandbox.google.com/private-advertising/attribution-reporting/attribution-reporting-debugging/) on privacysandbox.google.com (2023) +- [Set up debug reports](https://privacysandbox.google.com/private-advertising/attribution-reporting/attribution-reporting-debugging/part-2/) on privacysandbox.google.com (2023) +- [Debugging cookbook](https://privacysandbox.google.com/private-advertising/attribution-reporting/attribution-reporting-debugging/part-3/) on privacysandbox.google.com (2023) diff --git a/files/en-us/web/api/attribution_reporting_api/index.md b/files/en-us/web/api/attribution_reporting_api/index.md index 0004b6d2832d160..1f38f1cd6219ec2 100644 --- a/files/en-us/web/api/attribution_reporting_api/index.md +++ b/files/en-us/web/api/attribution_reporting_api/index.md @@ -43,13 +43,13 @@ The steps involved are as follows: 1. When a user visits the `news.example` site, an **attribution source** can be registered for specific user interactions with the embedded ad. There are several ways that a user can interact with ads on the page. For an ad interaction to register an attribution source, the ad must send a request with an {{httpheader("Attribution-Reporting-Eligible")}} header to indicate that the response is eligible to register an attribution source. Registration will be completed if the response includes an appropriate {{httpheader("Attribution-Reporting-Register-Source")}} header. The attribution source can be, for example: - A link. In this case, the interaction is the user clicking on the link (directly via an {{htmlelement("a")}} element, or via a {{domxref("Window.open()")}} call). The source is registered via the response to the navigation request. - - An image such as an advertising banner or a 1x1 transparent tracking pixel. In this case, the interaction is the user visiting the page. The source is registered when the image loads, i.e. when the server responds to the image request. - - A fetch request (i.e. a {{domxref("Window/fetch", "fetch()")}} or {{domxref("XMLHttpRequest")}}). In this case the interaction can be specified as whatever makes sense for your app — for example the fetch request could be invoked by a `click` or `submit` event. The source is registered once the response comes back. -2. When the attribution source interaction occurs, the source data returned in the {{httpheader("Attribution-Reporting-Register-Source")}} header is stored in a private local cache accessible only by the browser. This data includes the contextual and first-party data available to the page and the advertiser, the origin of the ad tech company that is collecting the conversion data, and one or more destinations ([eTLD+1](/en-US/docs/Glossary/eTLD)s) where you expect the conversion from that ad to occur (i.e. the advertiser's site(s), for example `shop.example`). + - An image such as an advertising banner or a 1x1 transparent tracking pixel. In this case, the interaction is the user visiting the page. The source is registered when the image loads, i.e., when the server responds to the image request. + - A fetch request (i.e., a {{domxref("Window/fetch", "fetch()")}} or {{domxref("XMLHttpRequest")}}). In this case the interaction can be specified as whatever makes sense for your app — for example the fetch request could be invoked by a `click` or `submit` event. The source is registered once the response comes back. +2. When the attribution source interaction occurs, the source data returned in the {{httpheader("Attribution-Reporting-Register-Source")}} header is stored in a private local cache accessible only by the browser. This data includes the contextual and first-party data available to the page and the advertiser, the origin of the ad tech company that is collecting the conversion data, and one or more destinations ([eTLD+1](/en-US/docs/Glossary/eTLD)s) where you expect the conversion from that ad to occur (i.e., the advertiser's site(s), for example `shop.example`). 3. When the user later visits `shop.example`, this site can register an **attribution trigger** when an interaction indicates that a conversion has occurred (for example, the user clicks the "Add to cart" button on `shop.example`). The browser will then send a request along with an {{httpheader("Attribution-Reporting-Eligible")}} header to indicate that the response is eligible to register an attribution trigger, and registration will be completed if the response includes an appropriate {{httpheader("Attribution-Reporting-Register-Trigger")}} header. The attribution trigger can be, for example: - - An image such as a shopping cart icon or a 1x1 transparent tracking pixel. In this case, the interaction is the user visiting the page. The trigger is registered when the image loads, i.e. when the server responds to the image request. - - A fetch request (i.e. a {{domxref("Window/fetch", "fetch()")}} or {{domxref("XMLHttpRequest")}}). In this case the interaction can be specified as whatever makes sense for your app — for example the fetch request could be invoked by a `click` or `submit` event. The trigger is registered once the response comes back. -4. When the trigger attribution completes, the browser attempts to match the data from the [Attribution-Reporting-Register-Trigger](/en-US/docs/Web/HTTP/Headers/Attribution-Reporting-Register-Trigger) header with a source data entry saved in the private local cache (see 2.). See [Registering attribution triggers](/en-US/docs/Web/API/Attribution_Reporting_API/Registering_triggers) for matching methodology and requirements. + - An image such as a shopping cart icon or a 1x1 transparent tracking pixel. In this case, the interaction is the user visiting the page. The trigger is registered when the image loads, i.e., when the server responds to the image request. + - A fetch request (i.e., a {{domxref("Window/fetch", "fetch()")}} or {{domxref("XMLHttpRequest")}}). In this case the interaction can be specified as whatever makes sense for your app — for example the fetch request could be invoked by a `click` or `submit` event. The trigger is registered once the response comes back. +4. When the trigger attribution completes, the browser attempts to match the data from the [Attribution-Reporting-Register-Trigger](/en-US/docs/Web/HTTP/Reference/Headers/Attribution-Reporting-Register-Trigger) header with a source data entry saved in the private local cache (see 2.). See [Registering attribution triggers](/en-US/docs/Web/API/Attribution_Reporting_API/Registering_triggers) for matching methodology and requirements. 5. If a match is made, the browser sends report data to an endpoint on a reporting server typically owned by the ad tech provider where it can be securely analyzed. Unlike with cookies, the data is only available to the specific site you send it to - there will be no data shared elsewhere. These reports can be either: - **Event-level reports**: Reports based on an attribution source event, where detailed source data is associated with coarse trigger data. For example, a report may look like "Click ID 200498 on `ad.shop.example` led to a purchase on `shop.example`", where "Click ID 200498" is the detailed source data, and "purchase" is the coarse trigger data. The detailed source data may encode first-party or contextual data from the source page, and the trigger data may encode the event from the trigger page. - **Summary reports**: More detailed reports that combine data from multiple conversions on both the source and trigger side. For example "Campaign ID 774653 on `news.example` has led to 654 sales of widgets on `shop.example` from users in Italy, with a total revenue of $9540." Compiling a summary report requires usage of an aggregation service (see for example the [Google aggregation service](https://github.com/privacysandbox/aggregation-service)). @@ -93,7 +93,7 @@ The Attribution Reporting API doesn't define any distinct interfaces of its own. ## Enrollment and local testing -To use the Attribution Reporting API in your sites, you must specify it in the [privacy sandbox enrollment process](/en-US/docs/Web/Privacy/Guides/Privacy_sandbox/Enrollment). If you don't do this, the API flow is blocked at response time, i.e. the response headers are ignored and sources and triggers are not registered. +To use the Attribution Reporting API in your sites, you must specify it in the [privacy sandbox enrollment process](/en-US/docs/Web/Privacy/Guides/Privacy_sandbox/Enrollment). If you don't do this, the API flow is blocked at response time, i.e., the response headers are ignored and sources and triggers are not registered. You can still test your Attribution Reporting API code locally without enrollment. To allow local testing, enable the following Chrome developer flag: @@ -114,6 +114,6 @@ See [Demo: Attribution Reporting API](https://arapi-home.web.app/) for an exampl ## See also - [Attribution Reporting Header Validation tool](https://wicg.github.io/attribution-reporting-api/validate-headers) -- [Attribution reporting](https://developers.google.com/privacy-sandbox/private-advertising/attribution-reporting/) on developers.google.com (2023) -- [Enable conversion measurement](https://developers.google.com/privacy-sandbox/private-advertising/attribution-reporting/enable-conversion-measurement) on developers.google.com (2023) -- [The Privacy Sandbox](https://developers.google.com/privacy-sandbox/) on developers.google.com (2023) +- [Attribution reporting](https://privacysandbox.google.com/private-advertising/attribution-reporting/) on privacysandbox.google.com (2023) +- [Enable conversion measurement](https://privacysandbox.google.com/private-advertising/attribution-reporting/enable-conversion-measurement) on privacysandbox.google.com (2023) +- [The Privacy Sandbox](https://privacysandbox.google.com/) on privacysandbox.google.com (2023) diff --git a/files/en-us/web/api/attribution_reporting_api/registering_sources/index.md b/files/en-us/web/api/attribution_reporting_api/registering_sources/index.md index bd9a67d0c73ee4e..2e4e06e94a05121 100644 --- a/files/en-us/web/api/attribution_reporting_api/registering_sources/index.md +++ b/files/en-us/web/api/attribution_reporting_api/registering_sources/index.md @@ -48,11 +48,11 @@ What happens behind the scenes to register sources and retrieve and store the so The only required field in this context is `destination`, which specifies 1–3 sites on which a trigger is expected to occur. These are used to match the attribution trigger to the source when a trigger is interacted with. The other fields specified above do the following: - `"source_event_id"`: A string representing an ID for the attribution source, which can be used to map it to other information when the attribution source is interacted with, or aggregate information at the reporting endpoint (see [Generating reports > Basic process](/en-US/docs/Web/API/Attribution_Reporting_API/Generating_reports#basic_process) for endpoint information). - - `"trigger_data"`: An array of 32-bit unsigned integers representing data that describes the different trigger events that could match this source. For example, "user added item to shopping cart" or "user signed up to mailing list" could be actions happening at the trigger site that could match this source and indicate a conversion of some kind that the advertiser is trying to measure. These must be matched against `"trigger_data"` specified in [triggers](/en-US/docs/Web/HTTP/Headers/Attribution-Reporting-Register-Trigger#trigger_data) for event-level attribution to take place. + - `"trigger_data"`: An array of 32-bit unsigned integers representing data that describes the different trigger events that could match this source. For example, "user added item to shopping cart" or "user signed up to mailing list" could be actions happening at the trigger site that could match this source and indicate a conversion of some kind that the advertiser is trying to measure. These must be matched against `"trigger_data"` specified in [triggers](/en-US/docs/Web/HTTP/Reference/Headers/Attribution-Reporting-Register-Trigger#trigger_data) for event-level attribution to take place. > [!NOTE] > The values used to represent each event, and the number of elements in the array, are completely arbitrary and defined by you as the developer. The array may contain values that are not used, but values must be present in the array to be attributed to the source by the browser when a trigger is registered. - `"trigger_data_matching"`: A string that specifies how the `"trigger_data"` from the trigger is matched against the source's `"trigger_data"`. `"exact"` is the value you'll nearly always use, which matches exact values. - - `"expiry"`: A string representing an expiry time in seconds for the attribution source, after which it will no longer be active (i.e. subsequent triggers won't be attributable to this source). + - `"expiry"`: A string representing an expiry time in seconds for the attribution source, after which it will no longer be active (i.e., subsequent triggers won't be attributable to this source). - `"priority"`: A string representing a priority value for the attribution source. See [Report priorities and limits](/en-US/docs/Web/API/Attribution_Reporting_API/Generating_reports#report_priorities_and_limits) for more information. - `"debug_key"`: A base-10-formatted 64-bit unsigned integer representing a debug key. Set this if you want to generate a [debug report](/en-US/docs/Web/API/Attribution_Reporting_API/Generating_reports#debug_reports) alongside the associated attribution report. - `"event_report_window"`: A string representing a time in seconds, after which subsequent triggers won't be attributable to this source for the purpose of producing event-level reports. @@ -137,7 +137,7 @@ In this case, the interaction occurs and the browser stores the source data when > When setting up a [`click`](/en-US/docs/Web/API/Element/click_event) event like in the above example, it is advisable to set it on a control where a click is expected, such as a {{htmlelement("button")}} or {{htmlelement("a")}} element. This makes more sense semantically, and is more accessible to both screen reader and keyboard users. > [!NOTE] -> To register an attribution source via `open()`, it must be called with [transient activation](/en-US/docs/Glossary/Transient_activation) (i.e. inside a user interaction event handler such as `click`) within five seconds of user interaction. +> To register an attribution source via `open()`, it must be called with [transient activation](/en-US/docs/Glossary/Transient_activation) (i.e., inside a user interaction event handler such as `click`) within five seconds of user interaction. ## Event-based attribution sources @@ -162,7 +162,7 @@ const imgElem = document.querySelector("img"); imgElem.attributionSrc = ""; ``` -The browser stores the attribution source data when the browser receives the response containing the image file (i.e. when the `load` event occurs). Bear in mind that users might not necessarily be able to perceive the image at all — it might be a 1x1 transparent tracking pixel that is only being used for attribution reporting. +The browser stores the attribution source data when the browser receives the response containing the image file (i.e., when the `load` event occurs). Bear in mind that users might not necessarily be able to perceive the image at all — it might be a 1x1 transparent tracking pixel that is only being used for attribution reporting. A {{htmlelement("script")}} example might look like so: @@ -241,7 +241,7 @@ In this case, the interaction occurs and the browser stores the source data when ## Specifying URLs inside attributionsrc -So far, in all the examples we have seen, the `attributionsrc` attribute/feature or `attributionSrc` property has been left blank, taking the value of an empty string. This is fine if the server that holds the requested resource is the same server that you also want to handle the registration, i.e. receive the {{httpheader("Attribution-Reporting-Eligible")}} header and respond with the {{httpheader("Attribution-Reporting-Register-Source")}} header. +So far, in all the examples we have seen, the `attributionsrc` attribute/feature or `attributionSrc` property has been left blank, taking the value of an empty string. This is fine if the server that holds the requested resource is the same server that you also want to handle the registration, i.e., receive the {{httpheader("Attribution-Reporting-Eligible")}} header and respond with the {{httpheader("Attribution-Reporting-Register-Source")}} header. However, it might be that the requested resource is not on a server you control, or you just want to handle registering the attribution source on a different server. In such cases, you can specify one or more URLs as the value of `attributionsrc`. When the resource request occurs, the {{httpheader("Attribution-Reporting-Eligible")}} header will be sent to the URL(s) specified in `attributionsrc` in addition to the resource origin; these URLs can then respond with the {{httpheader("Attribution-Reporting-Register-Source")}} to register the source. diff --git a/files/en-us/web/api/attribution_reporting_api/registering_triggers/index.md b/files/en-us/web/api/attribution_reporting_api/registering_triggers/index.md index d13d28cd83313a1..2e652b1171cf592 100644 --- a/files/en-us/web/api/attribution_reporting_api/registering_triggers/index.md +++ b/files/en-us/web/api/attribution_reporting_api/registering_triggers/index.md @@ -32,26 +32,26 @@ However, what happens behind the scenes to register triggers, look for matches, res.set( "Attribution-Reporting-Register-Trigger", JSON.stringify({ - "event_trigger_data": [ + event_trigger_data: [ { - "trigger_data": "4", - "priority": "1000000000000", - "deduplication_key": "2345698765", + trigger_data: "4", + priority: "1000000000000", + deduplication_key: "2345698765", }, ], - "debug_key": "1115698977", - }); + debug_key: "1115698977", + }), ); ``` The fields specified here are as follows: - `"event_trigger_data"`: An object representing data about the trigger. This includes: - - `"trigger_data"`: The data associated with the trigger, which is typically used to indicate events such as "user added item to shopping cart" or "user signed up to mailing list". This value will be included in the generated report, if any, although it will be subject to modification based on the attributed source's [`"trigger_data_matching"`](/en-US/docs/Web/HTTP/Headers/Attribution-Reporting-Register-Source#trigger_data_matching) field. + - `"trigger_data"`: The data associated with the trigger, which is typically used to indicate events such as "user added item to shopping cart" or "user signed up to mailing list". This value will be included in the generated report, if any, although it will be subject to modification based on the attributed source's [`"trigger_data_matching"`](/en-US/docs/Web/HTTP/Reference/Headers/Attribution-Reporting-Register-Source#trigger_data_matching) field. > [!NOTE] > The values used to represent each event, and the number of elements in the array, are completely arbitrary and defined by you as the developer. The array may contain values that are not used, but values must be present in the array to be attributed to the source by the browser when a trigger is registered. - `"priority"`: A string representing a priority value for the attribution trigger. See [Report priorities and limits](/en-US/docs/Web/API/Attribution_Reporting_API/Generating_reports#report_priorities_and_limits) for more information. - - `"deduplication_key"`: A string representing a unique key that can be used to prevent attributions from being duplicated — for example if a user were to add the same item to a shopping cart multiple times. See [Prevent duplication in reports](https://developers.google.com/privacy-sandbox/private-advertising/attribution-reporting/prevent-duplication) for more information. + - `"deduplication_key"`: A string representing a unique key that can be used to prevent attributions from being duplicated — for example if a user were to add the same item to a shopping cart multiple times. See [Prevent duplication in reports](https://privacysandbox.google.com/private-advertising/attribution-reporting/prevent-duplication) for more information. - `"debug_key"`: A number representing a debug key. Set this if you want to generate a [debug report](/en-US/docs/Web/API/Attribution_Reporting_API/Generating_reports#debug_reports) alongside the associated attribution report. See {{httpheader("Attribution-Reporting-Register-Trigger")}} for a detailed description of all the available fields. @@ -62,22 +62,22 @@ However, what happens behind the scenes to register triggers, look for matches, res.set( "Attribution-Reporting-Register-Trigger", JSON.stringify({ - "aggregatable_trigger_data": [ + aggregatable_trigger_data: [ { - "key_piece": "0x400", - "source_keys": ["campaignCounts"] + key_piece: "0x400", + source_keys: ["campaignCounts"], }, { - "key_piece": "0xA80", - "source_keys": ["geoValue", "nonMatchingKeyIdsAreIgnored"] - } + key_piece: "0xA80", + source_keys: ["geoValue", "nonMatchingKeyIdsAreIgnored"], + }, ], - "aggregatable_values": { - "campaignCounts": 32768, - "geoValue": 1664 + aggregatable_values: { + campaignCounts: 32768, + geoValue: 1664, }, - "debug_key": "1115698977" - }); + debug_key: "1115698977", + }), ); ``` @@ -88,7 +88,7 @@ However, what happens behind the scenes to register triggers, look for matches, Again, see {{httpheader("Attribution-Reporting-Register-Trigger")}} for a detailed description of all the available fields. -3. When the user interacts with the attribution trigger, the browser attempts to match the trigger against any attribution source entries stored in the browser's private local cache. For a successful match, the `Attribution-Reporting-Register-Trigger`'s [`"trigger_data"`](/en-US/docs/Web/HTTP/Headers/Attribution-Reporting-Register-Trigger#trigger_data) must match one of the values provided in the {{httpheader("Attribution-Reporting-Register-Source")}}'s [`"trigger_data"`](/en-US/docs/Web/HTTP/Headers/Attribution-Reporting-Register-Source#trigger_data), and the site (scheme + [eTLD+1](/en-US/docs/Glossary/eTLD)) of the top-level page on which the trigger is being registered must: +3. When the user interacts with the attribution trigger, the browser attempts to match the trigger against any attribution source entries stored in the browser's private local cache. For a successful match, the `Attribution-Reporting-Register-Trigger`'s [`"trigger_data"`](/en-US/docs/Web/HTTP/Reference/Headers/Attribution-Reporting-Register-Trigger#trigger_data) must match one of the values provided in the {{httpheader("Attribution-Reporting-Register-Source")}}'s [`"trigger_data"`](/en-US/docs/Web/HTTP/Reference/Headers/Attribution-Reporting-Register-Source#trigger_data), and the site (scheme + [eTLD+1](/en-US/docs/Glossary/eTLD)) of the top-level page on which the trigger is being registered must: - match the site of at least one of the `destination`s specified in the source's associated data. - be same-origin with the request that specified the source registration. @@ -99,8 +99,8 @@ However, what happens behind the scenes to register triggers, look for matches, There are many other factors that will prevent a successful match outcome; for example: - The trigger's filters do not match the source's filter data (See [Filters](/en-US/docs/Web/API/Attribution_Reporting_API/Generating_reports#filters) for more details). - - The source's [`"trigger_data_matching"`](/en-US/docs/Web/HTTP/Headers/Attribution-Reporting-Register-Source#trigger_data_matching) setting results in no match occurring. - - The source's [`"max_event_level_reports"`](/en-US/docs/Web/HTTP/Headers/Attribution-Reporting-Register-Source#max_event_level_reports) limit has been reached. + - The source's [`"trigger_data_matching"`](/en-US/docs/Web/HTTP/Reference/Headers/Attribution-Reporting-Register-Source#trigger_data_matching) setting results in no match occurring. + - The source's [`"max_event_level_reports"`](/en-US/docs/Web/HTTP/Reference/Headers/Attribution-Reporting-Register-Source#max_event_level_reports) limit has been reached. - A successful match is not reported due to the browser's randomized response algorithm. See [Adding noise to reports](/en-US/docs/Web/API/Attribution_Reporting_API/Generating_reports#adding_noise_to_reports) for more details. 4. If a successful match is found, the browser [generates a report](/en-US/docs/Web/API/Attribution_Reporting_API/Generating_reports) based on the source and trigger data, and sends it to a reporting endpoint. @@ -208,7 +208,7 @@ In this case, the browser will attempt to match the trigger with a stored attrib ## Specifying a URL inside attributionsrc -In the above examples, the `attributionsrc` attribute is left blank, taking the value of an empty string. This is fine if the server that holds the requested resource is the same server that you also want to handle the registration, i.e. receive the {{httpheader("Attribution-Reporting-Eligible")}} header and respond with the {{httpheader("Attribution-Reporting-Register-Trigger")}} header. +In the above examples, the `attributionsrc` attribute is left blank, taking the value of an empty string. This is fine if the server that holds the requested resource is the same server that you also want to handle the registration, i.e., receive the {{httpheader("Attribution-Reporting-Eligible")}} header and respond with the {{httpheader("Attribution-Reporting-Register-Trigger")}} header. However, it might be the case that the requested resource is not on a server you control, or you just want to handle registering the attribution trigger on a different server. In such cases, you can specify one or more URLs as the value of `attributionsrc`. When the resource request occurs, the {{httpheader("Attribution-Reporting-Eligible")}} header will be sent to the URLs specified in `attributionsrc` in addition to the resource origin; the URLs can then respond with the {{httpheader("Attribution-Reporting-Register-Trigger")}} to complete registration. diff --git a/files/en-us/web/api/audio_output_devices_api/index.md b/files/en-us/web/api/audio_output_devices_api/index.md index 69d01fab11411db..dfdc12e653b971a 100644 --- a/files/en-us/web/api/audio_output_devices_api/index.md +++ b/files/en-us/web/api/audio_output_devices_api/index.md @@ -23,7 +23,7 @@ This API allows applications to provide this same functionality from within a we Even if allowed by a permission policy, access to a particular audio output device still requires explicit user permission, as the user may be in a location where playing audio through some output devices is not appropriate. -The API provides the {{domxref("MediaDevices.selectAudioOutput()")}} method that allows users to select their desired audio output from those that are allowed by the [`speaker-selection`](/en-US/docs/Web/HTTP/Headers/Permissions-Policy/speaker-selection) directive of the {{httpheader("Permissions-Policy")}} HTTP header for the document. +The API provides the {{domxref("MediaDevices.selectAudioOutput()")}} method that allows users to select their desired audio output from those that are allowed by the [`speaker-selection`](/en-US/docs/Web/HTTP/Reference/Headers/Permissions-Policy/speaker-selection) directive of the {{httpheader("Permissions-Policy")}} HTTP header for the document. The selected device then has user permission, allowing it to be enumerated with {{domxref("MediaDevices.enumerateDevices()")}} and set as the audio output device using {{domxref("HTMLMediaElement.setSinkId()")}}. Audio devices may arbitrarily connect and disconnect. @@ -57,13 +57,13 @@ Access to the API is subject to the following constraints: - {{domxref("MediaDevices.selectAudioOutput()")}} grants user permission for a selected device to be used as the audio output sink: - - Access may be gated by the [`speaker-selection`](/en-US/docs/Web/HTTP/Headers/Permissions-Policy/speaker-selection) HTTP [Permission Policy](/en-US/docs/Web/HTTP/Permissions_Policy). + - Access may be gated by the [`speaker-selection`](/en-US/docs/Web/HTTP/Reference/Headers/Permissions-Policy/speaker-selection) HTTP [Permission Policy](/en-US/docs/Web/HTTP/Guides/Permissions_Policy). - [Transient user activation](/en-US/docs/Web/Security/User_activation) is required. The user has to interact with the page or a UI element for the method to be called. - {{domxref("HTMLMediaElement.setSinkId()")}} sets a permitted ID as the audio output: - - Access may be gated by the [`speaker-selection`](/en-US/docs/Web/HTTP/Headers/Permissions-Policy/speaker-selection) HTTP [Permission Policy](/en-US/docs/Web/HTTP/Permissions_Policy). + - Access may be gated by the [`speaker-selection`](/en-US/docs/Web/HTTP/Reference/Headers/Permissions-Policy/speaker-selection) HTTP [Permission Policy](/en-US/docs/Web/HTTP/Guides/Permissions_Policy). - User permission is required to set a non-default device ID. - This can come from selection in the prompt launched by `MediaDevices.selectAudioOutput()` - User permission to set the output device is also implicitly granted if the user has already granted permission to use a media input device in the same group with {{domxref("MediaDevices.getUserMedia()")}}. diff --git a/files/en-us/web/api/audiobuffer/getchanneldata/index.md b/files/en-us/web/api/audiobuffer/getchanneldata/index.md index 972b3ee4c426344..725ce108d61931b 100644 --- a/files/en-us/web/api/audiobuffer/getchanneldata/index.md +++ b/files/en-us/web/api/audiobuffer/getchanneldata/index.md @@ -47,7 +47,7 @@ const myArrayBuffer = audioCtx.createBuffer(2, frameCount, audioCtx.sampleRate); button.onclick = () => { // Fill the buffer with white noise; - //just random values between -1.0 and 1.0 + // just random values between -1.0 and 1.0 for (let channel = 0; channel < channels; channel++) { // This gives us the actual ArrayBuffer that contains the data const nowBuffering = myArrayBuffer.getChannelData(channel); diff --git a/files/en-us/web/api/audiobuffersourcenode/buffer/index.md b/files/en-us/web/api/audiobuffersourcenode/buffer/index.md index ff47bc8eb982ee2..cd58d4d665d78f4 100644 --- a/files/en-us/web/api/audiobuffersourcenode/buffer/index.md +++ b/files/en-us/web/api/audiobuffersourcenode/buffer/index.md @@ -28,7 +28,7 @@ const myArrayBuffer = audioCtx.createBuffer(2, frameCount, audioCtx.sampleRate); button.onclick = () => { // Fill the buffer with white noise; - //just random values between -1.0 and 1.0 + // just random values between -1.0 and 1.0 for (let channel = 0; channel < channels; channel++) { // This gives us the actual ArrayBuffer that contains the data const nowBuffering = myArrayBuffer.getChannelData(channel); diff --git a/files/en-us/web/api/audiobuffersourcenode/index.md b/files/en-us/web/api/audiobuffersourcenode/index.md index e2e6675e01aee81..8bb9fe6ae4c4013 100644 --- a/files/en-us/web/api/audiobuffersourcenode/index.md +++ b/files/en-us/web/api/audiobuffersourcenode/index.md @@ -85,7 +85,7 @@ const myArrayBuffer = audioCtx.createBuffer( ); // Fill the buffer with white noise; -//just random values between -1.0 and 1.0 +// just random values between -1.0 and 1.0 for (let channel = 0; channel < myArrayBuffer.numberOfChannels; channel++) { // This gives us the actual ArrayBuffer that contains the data const nowBuffering = myArrayBuffer.getChannelData(channel); diff --git a/files/en-us/web/api/audiobuffersourcenode/loop/index.md b/files/en-us/web/api/audiobuffersourcenode/loop/index.md index 68da8a3d4f505d7..3c859bfee171bb0 100644 --- a/files/en-us/web/api/audiobuffersourcenode/loop/index.md +++ b/files/en-us/web/api/audiobuffersourcenode/loop/index.md @@ -33,7 +33,7 @@ In this example, when the user presses "Play", we load an audio track, decode it The example then sets the `loop` property to `true`, so the track loops, and plays the track. -The user can set the `loopStart` and `loopEnd` properties using [range controls](/en-US/docs/Web/HTML/Element/input/range). +The user can set the `loopStart` and `loopEnd` properties using [range controls](/en-US/docs/Web/HTML/Reference/Elements/input/range). > [!NOTE] > You can [run the full example live](https://mdn.github.io/webaudio-examples/audio-buffer-source-node/loop/) (or [view the source](https://github.com/mdn/webaudio-examples/tree/main/audio-buffer-source-node/loop).) diff --git a/files/en-us/web/api/audiobuffersourcenode/loopend/index.md b/files/en-us/web/api/audiobuffersourcenode/loopend/index.md index 4f291686f010154..e10d724d08a35e0 100644 --- a/files/en-us/web/api/audiobuffersourcenode/loopend/index.md +++ b/files/en-us/web/api/audiobuffersourcenode/loopend/index.md @@ -33,7 +33,7 @@ In this example, when the user presses "Play", we load an audio track, decode it The example then sets the `loop` property to `true`, so the track loops, and plays the track. -The user can set the `loopStart` and `loopEnd` properties using [range controls](/en-US/docs/Web/HTML/Element/input/range). +The user can set the `loopStart` and `loopEnd` properties using [range controls](/en-US/docs/Web/HTML/Reference/Elements/input/range). > [!NOTE] > You can [run the full example live](https://mdn.github.io/webaudio-examples/audio-buffer-source-node/loop/) (or [view the source](https://github.com/mdn/webaudio-examples/tree/main/audio-buffer-source-node/loop).) diff --git a/files/en-us/web/api/audiobuffersourcenode/loopstart/index.md b/files/en-us/web/api/audiobuffersourcenode/loopstart/index.md index d71cc9addd8d8ca..dfcf05e343f4503 100644 --- a/files/en-us/web/api/audiobuffersourcenode/loopstart/index.md +++ b/files/en-us/web/api/audiobuffersourcenode/loopstart/index.md @@ -26,7 +26,7 @@ In this example, when the user presses "Play", we load an audio track, decode it The example then sets the `loop` property to `true`, so the track loops, and plays the track. -The user can set the `loopStart` and `loopEnd` properties using [range controls](/en-US/docs/Web/HTML/Element/input/range). +The user can set the `loopStart` and `loopEnd` properties using [range controls](/en-US/docs/Web/HTML/Reference/Elements/input/range). > [!NOTE] > You can [run the full example live](https://mdn.github.io/webaudio-examples/audio-buffer-source-node/loop/) (or [view the source](https://github.com/mdn/webaudio-examples/tree/main/audio-buffer-source-node/loop).) diff --git a/files/en-us/web/api/audiobuffersourcenode/playbackrate/index.md b/files/en-us/web/api/audiobuffersourcenode/playbackrate/index.md index 3f9636b3030a85d..0b955cc4137c41b 100644 --- a/files/en-us/web/api/audiobuffersourcenode/playbackrate/index.md +++ b/files/en-us/web/api/audiobuffersourcenode/playbackrate/index.md @@ -39,7 +39,7 @@ In this example, when the user presses "Play", we load an audio track, decode it The example then sets the `loop` property to `true`, so the track loops, and plays the track. -The user can set the `playbackRate` property using a [range control](/en-US/docs/Web/HTML/Element/input/range). +The user can set the `playbackRate` property using a [range control](/en-US/docs/Web/HTML/Reference/Elements/input/range). > [!NOTE] > You can [run the full example live](https://mdn.github.io/webaudio-examples/audio-buffer-source-node/playbackrate/) (or [view the source](https://github.com/mdn/webaudio-examples/tree/main/audio-buffer-source-node/playbackrate).) diff --git a/files/en-us/web/api/audiocontext/baselatency/index.md b/files/en-us/web/api/audiocontext/baselatency/index.md index ba74f3e72277471..a768a1d0ff28020 100644 --- a/files/en-us/web/api/audiocontext/baselatency/index.md +++ b/files/en-us/web/api/audiocontext/baselatency/index.md @@ -11,7 +11,7 @@ browser-compat: api.AudioContext.baseLatency The **`baseLatency`** read-only property of the {{domxref("AudioContext")}} interface returns a double that represents the number of seconds of processing latency incurred by the `AudioContext` passing an audio -buffer from the {{domxref("AudioDestinationNode")}} — i.e. the end of the audio graph — +buffer from the {{domxref("AudioDestinationNode")}} — i.e., the end of the audio graph — into the host system's audio subsystem ready for playing. > [!NOTE] diff --git a/files/en-us/web/api/audiocontext/getoutputtimestamp/index.md b/files/en-us/web/api/audiocontext/getoutputtimestamp/index.md index 2ac95642ab91a4e..d0c3dad1d6b64ae 100644 --- a/files/en-us/web/api/audiocontext/getoutputtimestamp/index.md +++ b/files/en-us/web/api/audiocontext/getoutputtimestamp/index.md @@ -58,9 +58,7 @@ You can see full code of this [example at output-timestamp](https://github.com/m // Press the play button playBtn.addEventListener("click", () => { // We can create the audioCtx as there has been some user action - if (!audioCtx) { - audioCtx = new AudioContext(); - } + audioCtx ??= new AudioContext(); source = new AudioBufferSourceNode(audioCtx); getData(); source.start(0); diff --git a/files/en-us/web/api/audiocontext/setsinkid/index.md b/files/en-us/web/api/audiocontext/setsinkid/index.md index da06beb7e46b81a..55dc2fc9764d091 100644 --- a/files/en-us/web/api/audiocontext/setsinkid/index.md +++ b/files/en-us/web/api/audiocontext/setsinkid/index.md @@ -14,7 +14,7 @@ The **`setSinkId()`** method of the {{domxref("AudioContext")}} interface sets t To set the audio device to a device different than the default one, the developer needs permission to access to audio devices. If required, the user can be prompted to grant the required permission via a {{domxref("MediaDevices.getUserMedia()")}} call. -In addition, this feature may be blocked by a [`speaker-selection`](/en-US/docs/Web/HTTP/Headers/Permissions-Policy/speaker-selection) [Permissions Policy](/en-US/docs/Web/HTTP/Permissions_Policy). +In addition, this feature may be blocked by a [`speaker-selection`](/en-US/docs/Web/HTTP/Reference/Headers/Permissions-Policy/speaker-selection) [Permissions Policy](/en-US/docs/Web/HTTP/Guides/Permissions_Policy). ## Syntax @@ -35,7 +35,7 @@ setSinkId(sinkId) A {{jsxref("Promise")}} that fulfills with a value of `undefined`. -Attempting to set the sink ID to its existing value (i.e. returned by {{domxref("AudioContext.sinkId")}}), throws no errors, but it aborts the process immediately. +Attempting to set the sink ID to its existing value (i.e., returned by {{domxref("AudioContext.sinkId")}}), throws no errors, but it aborts the process immediately. ### Exceptions @@ -50,54 +50,50 @@ Attempting to set the sink ID to its existing value (i.e. returned by {{domxref( In our [SetSinkId test example](https://set-sink-id.glitch.me/) (check out the [source code](https://glitch.com/edit/#!/set-sink-id)), we create an audio graph that generates a three-second burst of white noise via an {{domxref("AudioBufferSourceNode")}}, which we also run through a {{domxref("GainNode")}} to quiet things down a bit. +```js +mediaDeviceBtn.addEventListener("click", async () => { + if ("setSinkId" in AudioContext.prototype) { + selectDiv.textContent = ""; + + const stream = await navigator.mediaDevices.getUserMedia({ + audio: true, + }); + const devices = await navigator.mediaDevices.enumerateDevices(); + + // Most of the DOM scripting to generate the dropdown cut out for brevity + + const audioOutputs = devices.filter( + (device) => + device.kind === "audiooutput" && device.deviceId !== "default", + ); + + audioOutputs.forEach((device) => { + const option = document.createElement("option"); + option.value = device.deviceId; + option.textContent = device.label; + select.appendChild(option); + }); + + const option = document.createElement("option"); + option.value = "none"; + option.textContent = "None"; + select.appendChild(option); + + select.addEventListener("change", async () => { + if (select.value === "none") { + await audioCtx.setSinkId({ type: "none" }); + } else { + await audioCtx.setSinkId(select.value); + } + }); + } +}); +``` + We also provide the user with a dropdown menu to allow them to change the audio output device on the fly. To do this, we: 1. Provide a button to populate the dropdown menu. We first invoke {{domxref("MediaDevices.getUserMedia()")}} to trigger the permissions prompt we need to allow device enumeration, then use {{domxref("MediaDevices.enumerateDevices()")}} to get all the available devices. We loop through the different devices and make each one available as an option in a {{htmlelement("select")}} element. We also create a "None" option for the case where you don't want to play your audio in any output. - - ```js - mediaDeviceBtn.addEventListener('click', async () => { - if ("setSinkId" in AudioContext.prototype) { - selectDiv.textContent = ""; - - const stream = await navigator.mediaDevices.getUserMedia({ audio: true }); - const devices = await navigator.mediaDevices.enumerateDevices(); - - // Most of the DOM scripting to generate the dropdown cut out for brevity - - const audioOutputs = devices.filter( - (device) => device.kind === 'audiooutput' && device.deviceId !== 'default' - ); - - audioOutputs.forEach((device) => { - const option = document.createElement('option') - option.value = device.deviceId; - option.textContent = device.label; - select.appendChild(option); - }); - - const option = document.createElement('option') - option.value = 'none'; - option.textContent = 'None'; - select.appendChild(option); - - //... - ``` - -2. Add a {{domxref("HTMLElement/change_event", "change")}} event listener to the {{htmlelement("select")}} element to change the sink ID and therefore the audio output device when a new value is selected. If "None" is selected in the dropdown, we invoke `setSinkId()` with the `{ type : 'none' }` object parameter to select no audio device, otherwise we run it with the audio device ID contained in the `<select>` element `value` attribute` as the parameter. - - ```js - // ... - - select.addEventListener('change', async () => { - if(select.value === 'none') { - await audioCtx.setSinkId({ type : 'none' }); - } else { - await audioCtx.setSinkId(select.value); - } - }) - } - }); - ``` +2. Add a {{domxref("HTMLElement/change_event", "change")}} event listener to the {{htmlelement("select")}} element to change the sink ID and therefore the audio output device when a new value is selected. If "None" is selected in the dropdown, we invoke `setSinkId()` with the `{ type : 'none' }` object parameter to select no audio device, otherwise we run it with the audio device ID contained in the `<select>` element `value` attribute as the parameter. The output device can be changed during audio playback, as well as before, or between plays. diff --git a/files/en-us/web/api/audiocontext/sinkchange_event/index.md b/files/en-us/web/api/audiocontext/sinkchange_event/index.md index 97cf1b457bf1218..4e05569bd7ada12 100644 --- a/files/en-us/web/api/audiocontext/sinkchange_event/index.md +++ b/files/en-us/web/api/audiocontext/sinkchange_event/index.md @@ -16,10 +16,10 @@ The **`sinkchange`** event of the {{domxref("AudioContext")}} interface is fired Use the event name in methods like {{domxref("EventTarget.addEventListener", "addEventListener()")}}, or set an event handler property. -```js -addEventListener("sinkchange", (event) => {}); +```js-nolint +addEventListener("sinkchange", (event) => { }) -onsinkchange = (event) => {}; +onsinkchange = (event) => { } ``` ## Event type diff --git a/files/en-us/web/api/audiodecoder/configure/index.md b/files/en-us/web/api/audiodecoder/configure/index.md index 90261d02d15f646..6624c40a27e0542 100644 --- a/files/en-us/web/api/audiodecoder/configure/index.md +++ b/files/en-us/web/api/audiodecoder/configure/index.md @@ -21,7 +21,7 @@ configure(config) - `config` - : A dictionary object containing the following members: - `codec` - - : A string containing a [valid codec string](https://www.w3.org/TR/webcodecs-codec-registry/#audio-codec-registry). See ["codecs" parameter](/en-US/docs/Web/Media/Guides/Formats/codecs_parameter#codec_options_by_container) for details on codec string construction. + - : A string containing a [valid codec string](https://w3c.github.io/webcodecs/codec_registry.html#audio-codec-registry). See ["codecs" parameter](/en-US/docs/Web/Media/Guides/Formats/codecs_parameter#codec_options_by_container) for details on codec string construction. - `sampleRate` - : An integer representing the number of frame samples per second. - `numberOfChannels` @@ -30,7 +30,7 @@ configure(config) - : An {{jsxref("ArrayBuffer")}}, a {{jsxref("TypedArray")}}, or a {{jsxref("DataView")}} containing a sequence of codec specific bytes, commonly known as extradata. > [!NOTE] -> The registrations in the [WebCodecs Codec Registry](https://www.w3.org/TR/webcodecs-codec-registry/#audio-codec-registry) link to a specification detailing whether and how to populate the optional `description` member. +> The registrations in the [WebCodecs Codec Registry](https://w3c.github.io/webcodecs/codec_registry.html#audio-codec-registry) link to a specification detailing whether and how to populate the optional `description` member. ### Return value diff --git a/files/en-us/web/api/audiodecoder/decode/index.md b/files/en-us/web/api/audiodecoder/decode/index.md index 7739de227185ca2..9fa4f4edf562915 100644 --- a/files/en-us/web/api/audiodecoder/decode/index.md +++ b/files/en-us/web/api/audiodecoder/decode/index.md @@ -32,8 +32,6 @@ None ({{jsxref("undefined")}}). - `DataError` {{domxref("DOMException")}} - : Thrown if the `chunk` is unable to be decoded due to relying on other frames for decoding. -## Examples - ## Specifications {{Specifications}} diff --git a/files/en-us/web/api/audiodecoder/dequeue_event/index.md b/files/en-us/web/api/audiodecoder/dequeue_event/index.md index 971c1a327183a59..5e0901ea2dd029b 100644 --- a/files/en-us/web/api/audiodecoder/dequeue_event/index.md +++ b/files/en-us/web/api/audiodecoder/dequeue_event/index.md @@ -16,10 +16,10 @@ This eliminates the need for developers to use a {{domxref("Window.setTimeout", Use the event name in methods like {{domxref("EventTarget.addEventListener", "addEventListener()")}}, or set an event handler property. -```js -addEventListener("dequeue", (event) => {}); +```js-nolint +addEventListener("dequeue", (event) => { }) -ondequeue = (event) => {}; +ondequeue = (event) => { } ``` ## Example diff --git a/files/en-us/web/api/audiodestinationnode/index.md b/files/en-us/web/api/audiodestinationnode/index.md index 59f77c9479fa7d7..d9935daa50f42b8 100644 --- a/files/en-us/web/api/audiodestinationnode/index.md +++ b/files/en-us/web/api/audiodestinationnode/index.md @@ -53,7 +53,7 @@ _No specific method; inherits methods from its parent, {{domxref("AudioNode")}}_ ## Example -There is no complex set up for using an `AudioDestinationNode` — by default, this represents the output of the user's system (e.g. their speakers), so you can get it hooked up inside an audio graph using only a few lines of code: +There is no complex set up for using an `AudioDestinationNode` — by default, this represents the output of the user's system (e.g., their speakers), so you can get it hooked up inside an audio graph using only a few lines of code: ```js const audioCtx = new AudioContext(); diff --git a/files/en-us/web/api/audioencoder/audioencoder/index.md b/files/en-us/web/api/audioencoder/audioencoder/index.md index f3b9a9c4d84494d..959b4fc60d88d18 100644 --- a/files/en-us/web/api/audioencoder/audioencoder/index.md +++ b/files/en-us/web/api/audioencoder/audioencoder/index.md @@ -23,7 +23,7 @@ new AudioEncoder(init) - `output` - : A callback which takes a {{domxref("EncodedAudioChunk")}} object as the first argument, and an optional metadata object as the second. The metadata object has one member, `decoderConfig` which has an object as its value containing: - `codec` - - : A string containing a [valid codec string](https://www.w3.org/TR/webcodecs-codec-registry/#audio-codec-registry). + - : A string containing a [valid codec string](https://w3c.github.io/webcodecs/codec_registry.html#audio-codec-registry). - `sampleRate` - : An integer representing the number of frame samples per second. - `numberOfChannels` diff --git a/files/en-us/web/api/audioencoder/configure/index.md b/files/en-us/web/api/audioencoder/configure/index.md index 102c204e1ed7095..6473f36fadc0ef9 100644 --- a/files/en-us/web/api/audioencoder/configure/index.md +++ b/files/en-us/web/api/audioencoder/configure/index.md @@ -23,7 +23,7 @@ configure(config) - : A dictionary object containing the following members: - `codec` - - : A string containing a [valid codec string](https://www.w3.org/TR/webcodecs-codec-registry/#audio-codec-registry). See ["codecs" parameter](/en-US/docs/Web/Media/Guides/Formats/codecs_parameter#codec_options_by_container) for details on codec string construction. + - : A string containing a [valid codec string](https://w3c.github.io/webcodecs/codec_registry.html#audio-codec-registry). See ["codecs" parameter](/en-US/docs/Web/Media/Guides/Formats/codecs_parameter#codec_options_by_container) for details on codec string construction. - `sampleRate` - : An integer representing the number of frame samples per second. - `numberOfChannels` @@ -99,7 +99,7 @@ The following example creates a new {{domxref("AudioEncoder")}} and configures i ```js const init = { output: handleOutput, - error: (e) => { + error(e) { console.log(e.message); }, }; @@ -123,7 +123,7 @@ The following example creates a new {{domxref("AudioEncoder")}} and configures i ```js const init = { output: handleOutput, - error: (e) => { + error(e) { console.log(e.message); }, }; diff --git a/files/en-us/web/api/audioencoder/dequeue_event/index.md b/files/en-us/web/api/audioencoder/dequeue_event/index.md index 2bc9d4de6b04974..b49e3f957dd3d0d 100644 --- a/files/en-us/web/api/audioencoder/dequeue_event/index.md +++ b/files/en-us/web/api/audioencoder/dequeue_event/index.md @@ -16,10 +16,10 @@ This eliminates the need for developers to use a {{domxref("Window.setTimeout", Use the event name in methods like {{domxref("EventTarget.addEventListener", "addEventListener()")}}, or set an event handler property. -```js -addEventListener("dequeue", (event) => {}); +```js-nolint +addEventListener("dequeue", (event) => { }) -ondequeue = (event) => {}; +ondequeue = (event) => { } ``` ## Example diff --git a/files/en-us/web/api/audionode/index.md b/files/en-us/web/api/audionode/index.md index 5680ffd2e849ffc..5caad1e02f01a46 100644 --- a/files/en-us/web/api/audionode/index.md +++ b/files/en-us/web/api/audionode/index.md @@ -11,9 +11,9 @@ The **`AudioNode`** interface is a generic interface for representing an audio p Examples include: -- an audio source (e.g. an HTML {{HTMLElement("audio")}} or {{HTMLElement("video")}} element, an {{domxref("OscillatorNode")}}, etc.), +- an audio source (e.g., an HTML {{HTMLElement("audio")}} or {{HTMLElement("video")}} element, an {{domxref("OscillatorNode")}}, etc.), - the audio destination, -- intermediate processing module (e.g. a filter like {{domxref("BiquadFilterNode")}} or {{domxref("ConvolverNode")}}), or +- intermediate processing module (e.g., a filter like {{domxref("BiquadFilterNode")}} or {{domxref("ConvolverNode")}}), or - volume control (like {{domxref("GainNode")}}) {{InheritanceDiagram}} diff --git a/files/en-us/web/api/audioparam/cancelscheduledvalues/index.md b/files/en-us/web/api/audioparam/cancelscheduledvalues/index.md index d97c3579fa768ae..8ad926ba9cc5053 100644 --- a/files/en-us/web/api/audioparam/cancelscheduledvalues/index.md +++ b/files/en-us/web/api/audioparam/cancelscheduledvalues/index.md @@ -32,7 +32,7 @@ method returns {{jsxref('undefined')}}. ```js const gainNode = audioCtx.createGain(); -gainNode.gain.setValueCurveAtTime(waveArray, audioCtx.currentTime, 2); //'gain' is the AudioParam +gainNode.gain.setValueCurveAtTime(waveArray, audioCtx.currentTime, 2); // 'gain' is the AudioParam gainNode.gain.cancelScheduledValues(audioCtx.currentTime); ``` diff --git a/files/en-us/web/api/audioparamdescriptor/index.md b/files/en-us/web/api/audioparamdescriptor/index.md index 70da255a168481a..040f05d2b8aa4ca 100644 --- a/files/en-us/web/api/audioparamdescriptor/index.md +++ b/files/en-us/web/api/audioparamdescriptor/index.md @@ -2,7 +2,7 @@ title: AudioParamDescriptor slug: Web/API/AudioParamDescriptor page-type: web-api-interface -browser-compat: api.AudioParamDescriptor +spec-urls: https://webaudio.github.io/web-audio-api/#AudioParamDescriptor --- {{APIRef("Web Audio API")}} @@ -51,10 +51,6 @@ class WhiteNoiseProcessor extends AudioWorkletProcessor { {{Specifications}} -## Browser compatibility - -{{Compat}} - ## See also - [Web Audio API](/en-US/docs/Web/API/Web_Audio_API) diff --git a/files/en-us/web/api/audiosinkinfo/index.md b/files/en-us/web/api/audiosinkinfo/index.md index 27d9ab89fb867fa..71b4045e6d6cfce 100644 --- a/files/en-us/web/api/audiosinkinfo/index.md +++ b/files/en-us/web/api/audiosinkinfo/index.md @@ -27,7 +27,7 @@ audioCtx = new window.AudioContext({ sinkId: { type: "none" }, }); -// ... +// … audioCtx.sinkId; ``` diff --git a/files/en-us/web/api/audioworklet/index.md b/files/en-us/web/api/audioworklet/index.md index 81ff870c003580d..31abbf645e5125f 100644 --- a/files/en-us/web/api/audioworklet/index.md +++ b/files/en-us/web/api/audioworklet/index.md @@ -17,7 +17,11 @@ Access the audio context's instance of `AudioWorklet` through the {{domxref("Bas ## Instance properties -_The `AudioWorklet` interface does not define any properties of its own, but does inherit properties of {{domxref("Worklet")}}._ +_This interface also inherits properties defined on its parent interface, {{domxref("Worklet")}}._ + +- {{domxref("AudioWorklet.port", "port")}} {{ReadOnlyInline}} {{experimental_inline}} + - : Returns a {{domxref("MessagePort")}} for custom, asynchronous communication between code in the main thread and the global scope of an audio worklet. + This allows for custom messages, such as sending and receiving control data or global settings. ## Instance methods diff --git a/files/en-us/web/api/audioworklet/port/index.md b/files/en-us/web/api/audioworklet/port/index.md new file mode 100644 index 000000000000000..f8b803df0176ac6 --- /dev/null +++ b/files/en-us/web/api/audioworklet/port/index.md @@ -0,0 +1,58 @@ +--- +title: "AudioWorklet: port" +short-title: port +slug: Web/API/AudioWorklet/port +page-type: web-api-instance-property +status: + - experimental +browser-compat: api.AudioWorklet.port +--- + +{{APIRef("Web Audio API")}}{{SeeCompatTable}} + +The **`port`** read-only property of the {{domxref("AudioWorklet")}} interface returns a {{domxref("MessagePort")}} object that can be used to send and receive messages between the main thread and the associated {{domxref("AudioWorkletGlobalScope")}}. + +This allows for custom, asynchronous communication between code in the main thread and the global scope of an audio worklet, such as receiving control data or global settings. + +## Value + +The {{domxref("MessagePort")}} object connecting the `AudioWorklet` and its associated `AudioWorkletGlobalScope`. + +## Examples + +See [`AudioWorkletNode.port`](/en-US/docs/Web/API/AudioWorkletNode/port#examples) for more examples. + +### Using a port for global messages + +In the following example, we can use `port.onmessage` to receive data and `port.postMessage` to send data: + +```js +const context = new AudioContext(); +// Load the module that contains worklet code +await context.audioWorklet.addModule("processor.js"); + +// Listener for messages from AudioWorkletGlobalScope +context.audioWorklet.port.onmessage = (event) => { + console.log("Message from global worklet:", event.data); +}; + +// Set a global config, for example: +context.audioWorklet.port.postMessage({ + volume: 0.8, +}); +``` + +## Specifications + +{{Specifications}} + +## Browser compatibility + +{{Compat}} + +## See also + +- {{domxref("AudioWorkletGlobalScope")}} — the global execution context of an `AudioWorklet` +- [Web Audio API](/en-US/docs/Web/API/Web_Audio_API) +- [Using the Web Audio API](/en-US/docs/Web/API/Web_Audio_API/Using_Web_Audio_API) +- [Using AudioWorklet](/en-US/docs/Web/API/Web_Audio_API/Using_AudioWorklet) diff --git a/files/en-us/web/api/audioworkletglobalscope/index.md b/files/en-us/web/api/audioworkletglobalscope/index.md index fa5492be1dd30ef..46f6012fd99b3ac 100644 --- a/files/en-us/web/api/audioworkletglobalscope/index.md +++ b/files/en-us/web/api/audioworkletglobalscope/index.md @@ -25,6 +25,9 @@ _This interface also inherits properties defined on its parent interface, {{domx - : Returns a double that represents the ever-increasing context time of the audio block being processed. It is equal to the {{domxref("BaseAudioContext.currentTime", "currentTime")}} property of the {{domxref("BaseAudioContext")}} the worklet belongs to. - {{domxref("AudioWorkletGlobalScope.sampleRate", "sampleRate")}} {{ReadOnlyInline}} - : Returns a float that represents the sample rate of the associated {{domxref("BaseAudioContext")}}. +- {{domxref("AudioWorkletGlobalScope.port", "port")}} {{ReadOnlyInline}} {{experimental_inline}} + - : Returns a {{domxref("MessagePort")}} for custom, asynchronous communication between code in the main thread and the global scope of an audio worklet. + This allows for custom messages, such as sending and receiving control data or global settings. ## Instance methods diff --git a/files/en-us/web/api/audioworkletglobalscope/port/index.md b/files/en-us/web/api/audioworkletglobalscope/port/index.md new file mode 100644 index 000000000000000..acaa46c909a8019 --- /dev/null +++ b/files/en-us/web/api/audioworkletglobalscope/port/index.md @@ -0,0 +1,37 @@ +--- +title: "AudioWorkletGlobalScope: port" +short-title: port +slug: Web/API/AudioWorkletGlobalScope/port +page-type: web-api-instance-property +status: + - experimental +browser-compat: api.AudioWorkletGlobalScope.port +--- + +{{APIRef("Web Audio API")}}{{SeeCompatTable}} + +The **`port`** read-only property of the {{domxref("AudioWorkletGlobalScope")}} interface returns a {{domxref("MessagePort")}} object that can be used to send and receive messages between the main thread and the associated {{domxref("AudioWorklet")}}. + +This allows for custom, asynchronous communication between code in the main thread and the global scope of an audio worklet, such as sending control data or global settings. + +## Value + +The {{domxref("MessagePort")}} object that is connecting the `AudioWorklet` and its associated `AudioWorkletGlobalScope`. + +## Examples + +See [`AudioWorkletNode.port`](/en-US/docs/Web/API/AudioWorkletNode/port#examples) for examples. + +## Specifications + +{{Specifications}} + +## Browser compatibility + +{{Compat}} + +## See also + +- [Web Audio API](/en-US/docs/Web/API/Web_Audio_API) +- [Using the Web Audio API](/en-US/docs/Web/API/Web_Audio_API/Using_Web_Audio_API) +- [Using AudioWorklet](/en-US/docs/Web/API/Web_Audio_API/Using_AudioWorklet) diff --git a/files/en-us/web/api/audioworkletprocessor/audioworkletprocessor/index.md b/files/en-us/web/api/audioworkletprocessor/audioworkletprocessor/index.md index 22fca2b362c2ebd..f46a100f1ac6921 100644 --- a/files/en-us/web/api/audioworkletprocessor/audioworkletprocessor/index.md +++ b/files/en-us/web/api/audioworkletprocessor/audioworkletprocessor/index.md @@ -13,12 +13,12 @@ constructor creates a new {{domxref("AudioWorkletProcessor")}} object, which represents an underlying audio processing mechanism of an {{domxref("AudioWorkletNode")}}. -## Syntax - > [!NOTE] > The `AudioWorkletProcessor` and classes that derive from it > cannot be instantiated directly from a user-supplied code. Instead, they are created -> only internally by the creation of an associated {{domxref("AudioWorkletNode")}}s. +> only internally by the creation of an associated {{domxref("AudioWorkletNode")}}. + +## Syntax ```js-nolint new AudioWorkletProcessor(options) diff --git a/files/en-us/web/api/authenticatorassertionresponse/authenticatordata/index.md b/files/en-us/web/api/authenticatorassertionresponse/authenticatordata/index.md index 4072aa38b97a674..0cdf4dd9168e660 100644 --- a/files/en-us/web/api/authenticatorassertionresponse/authenticatordata/index.md +++ b/files/en-us/web/api/authenticatorassertionresponse/authenticatordata/index.md @@ -16,7 +16,7 @@ An {{jsxref("ArrayBuffer")}} with a {{jsxref("ArrayBuffer.byteLength")}} of at l ## Examples -See [User login using the WebAuthn API](/en-US/docs/Web/API/CredentialsContainer/get#user_login_using_the_webauthn_api) for a detailed example. +See [Retrieving a public key credential](/en-US/docs/Web/API/CredentialsContainer/get#retrieving_a_public_key_credential) for a detailed example. ## Specifications diff --git a/files/en-us/web/api/authenticatorassertionresponse/index.md b/files/en-us/web/api/authenticatorassertionresponse/index.md index e9e65affb6aa4f0..9388364d3672d67 100644 --- a/files/en-us/web/api/authenticatorassertionresponse/index.md +++ b/files/en-us/web/api/authenticatorassertionresponse/index.md @@ -37,7 +37,7 @@ None. ## Examples -See [User login using the WebAuthn API](/en-US/docs/Web/API/CredentialsContainer/get#user_login_using_the_webauthn_api) for a detailed example. +See [Retrieving a public key credential](/en-US/docs/Web/API/CredentialsContainer/get#retrieving_a_public_key_credential) for a detailed example. ## Specifications diff --git a/files/en-us/web/api/authenticatorassertionresponse/signature/index.md b/files/en-us/web/api/authenticatorassertionresponse/signature/index.md index 0576d12712bff5d..8bd598bc7f2a819 100644 --- a/files/en-us/web/api/authenticatorassertionresponse/signature/index.md +++ b/files/en-us/web/api/authenticatorassertionresponse/signature/index.md @@ -29,7 +29,7 @@ available from ## Examples -See [User login using the WebAuthn API](/en-US/docs/Web/API/CredentialsContainer/get#user_login_using_the_webauthn_api) for a detailed example. +See [Retrieving a public key credential](/en-US/docs/Web/API/CredentialsContainer/get#retrieving_a_public_key_credential) for a detailed example. ## Specifications diff --git a/files/en-us/web/api/authenticatorassertionresponse/userhandle/index.md b/files/en-us/web/api/authenticatorassertionresponse/userhandle/index.md index 7d980dbd20ee60c..c15c888f58d05e1 100644 --- a/files/en-us/web/api/authenticatorassertionresponse/userhandle/index.md +++ b/files/en-us/web/api/authenticatorassertionresponse/userhandle/index.md @@ -20,7 +20,7 @@ For {{domxref("CredentialsContainer.create()","navigator.credentials.create()")} ## Examples -See [User login using the WebAuthn API](/en-US/docs/Web/API/CredentialsContainer/get#user_login_using_the_webauthn_api) for a detailed example. +See [Retrieving a public key credential](/en-US/docs/Web/API/CredentialsContainer/get#retrieving_a_public_key_credential) for a detailed example. ## Specifications diff --git a/files/en-us/web/api/authenticatorattestationresponse/attestationobject/index.md b/files/en-us/web/api/authenticatorattestationresponse/attestationobject/index.md index 27068ebe80e98f3..a299028c8da78e5 100644 --- a/files/en-us/web/api/authenticatorattestationresponse/attestationobject/index.md +++ b/files/en-us/web/api/authenticatorattestationresponse/attestationobject/index.md @@ -34,8 +34,8 @@ properties: - `fmt` - - : A text string that indicates the format of the attStmt. The [WebAuthn specification defines a number of formats](https://www.w3.org/TR/webauthn/#defined-attestation-formats); however, formats may also be defined - in other specifications and registered in an [IANA registry](https://www.w3.org/TR/webauthn/#sctn-att-fmt-reg). Formats + - : A text string that indicates the format of the attStmt. The [WebAuthn specification defines a number of formats](https://w3c.github.io/webauthn/#sctn-defined-attestation-formats); however, formats may also be defined + in other specifications and registered in an [IANA registry](https://w3c.github.io/webauthn/#sctn-att-fmt-reg). Formats defined by WebAuthn are: - `"packed"` @@ -47,11 +47,11 @@ properties: - `attStmt` - : An attestation statement that is of the format defined by `"fmt"`. For - now, [see the WebAuthn specification for details on each format](https://www.w3.org/TR/webauthn/#defined-attestation-formats). + now, [see the WebAuthn specification for details on each format](https://w3c.github.io/webauthn/#sctn-defined-attestation-formats). ## Examples -See [Creating a public key credential using the WebAuthn API](/en-US/docs/Web/API/CredentialsContainer/create#creating_a_public_key_credential_using_the_webauthn_api) for a detailed example. +See [Creating a public key credential](/en-US/docs/Web/API/CredentialsContainer/create#creating_a_public_key_credential) for a detailed example. ## Specifications diff --git a/files/en-us/web/api/authenticatorattestationresponse/getauthenticatordata/index.md b/files/en-us/web/api/authenticatorattestationresponse/getauthenticatordata/index.md index 672c157714e6f69..06d0e137bfad2b7 100644 --- a/files/en-us/web/api/authenticatorattestationresponse/getauthenticatordata/index.md +++ b/files/en-us/web/api/authenticatorattestationresponse/getauthenticatordata/index.md @@ -30,7 +30,7 @@ This will be equivalent to the authenticator data contained within the {{domxref ## Examples -See [Creating a public key credential using the WebAuthn API](/en-US/docs/Web/API/CredentialsContainer/create#creating_a_public_key_credential_using_the_webauthn_api) for a detailed example. +See [Creating a public key credential](/en-US/docs/Web/API/CredentialsContainer/create#creating_a_public_key_credential) for a detailed example. ## Specifications diff --git a/files/en-us/web/api/authenticatorattestationresponse/getpublickey/index.md b/files/en-us/web/api/authenticatorattestationresponse/getpublickey/index.md index 865905f54a75b16..213034be81d25fe 100644 --- a/files/en-us/web/api/authenticatorattestationresponse/getpublickey/index.md +++ b/files/en-us/web/api/authenticatorattestationresponse/getpublickey/index.md @@ -28,7 +28,7 @@ An {{jsxref("ArrayBuffer")}} containing the DER `SubjectPublicKeyInfo` of the ne ## Examples -See [Creating a public key credential using the WebAuthn API](/en-US/docs/Web/API/CredentialsContainer/create#creating_a_public_key_credential_using_the_webauthn_api) for a detailed example. +See [Creating a public key credential](/en-US/docs/Web/API/CredentialsContainer/create#creating_a_public_key_credential) for a detailed example. ## Specifications diff --git a/files/en-us/web/api/authenticatorattestationresponse/getpublickeyalgorithm/index.md b/files/en-us/web/api/authenticatorattestationresponse/getpublickeyalgorithm/index.md index d65969ce3178075..97a4a31d99b6194 100644 --- a/files/en-us/web/api/authenticatorattestationresponse/getpublickeyalgorithm/index.md +++ b/files/en-us/web/api/authenticatorattestationresponse/getpublickeyalgorithm/index.md @@ -28,7 +28,7 @@ A number that is equal to a [COSE Algorithm Identifier](https://www.iana.org/ass ## Examples -See [Creating a public key credential using the WebAuthn API](/en-US/docs/Web/API/CredentialsContainer/create#creating_a_public_key_credential_using_the_webauthn_api) for a detailed example. +See [Creating a public key credential](/en-US/docs/Web/API/CredentialsContainer/create#creating_a_public_key_credential) for a detailed example. ## Specifications diff --git a/files/en-us/web/api/authenticatorattestationresponse/gettransports/index.md b/files/en-us/web/api/authenticatorattestationresponse/gettransports/index.md index b82f23e40a5dcb1..58a28d00cf31f3f 100644 --- a/files/en-us/web/api/authenticatorattestationresponse/gettransports/index.md +++ b/files/en-us/web/api/authenticatorattestationresponse/gettransports/index.md @@ -27,7 +27,7 @@ None. An {{jsxref("Array")}} of strings representing the different transports supported by the authenticator, in lexicographical order. Values may include: -- `ble` +- `"ble"` - : The authenticator may be used over [BLE (Bluetooth Low Energy)](https://en.wikipedia.org/wiki/Bluetooth_Low_Energy). - `"hybrid"` - : The authenticator can be used over a combination of (often separate) data transport and proximity mechanisms. This supports, for example, authentication on a desktop computer using a smartphone. @@ -40,7 +40,7 @@ Values may include: ## Examples -See [Creating a public key credential using the WebAuthn API](/en-US/docs/Web/API/CredentialsContainer/create#creating_a_public_key_credential_using_the_webauthn_api) for a detailed example. +See [Creating a public key credential](/en-US/docs/Web/API/CredentialsContainer/create#creating_a_public_key_credential) for a detailed example. ## Specifications diff --git a/files/en-us/web/api/authenticatorattestationresponse/index.md b/files/en-us/web/api/authenticatorattestationresponse/index.md index 968be58d2bd4549..7735e41c75aa77f 100644 --- a/files/en-us/web/api/authenticatorattestationresponse/index.md +++ b/files/en-us/web/api/authenticatorattestationresponse/index.md @@ -42,7 +42,7 @@ _Also inherits properties from its parent, {{domxref("AuthenticatorResponse")}}. ## Examples -See [Creating a public key credential using the WebAuthn API](/en-US/docs/Web/API/CredentialsContainer/create#creating_a_public_key_credential_using_the_webauthn_api) for a detailed example. +See [Creating a public key credential](/en-US/docs/Web/API/CredentialsContainer/create#creating_a_public_key_credential) for a detailed example. ## Specifications diff --git a/files/en-us/web/api/background_fetch_api/index.md b/files/en-us/web/api/background_fetch_api/index.md index 5517012dbdbfbc6..9a1df52ef073a9b 100644 --- a/files/en-us/web/api/background_fetch_api/index.md +++ b/files/en-us/web/api/background_fetch_api/index.md @@ -86,7 +86,7 @@ navigator.serviceWorker.ready.then(async (swReg) => { }); ``` -You can find a demo application which implements Background Fetch [here](https://glitch.com/edit/#!/bgfetch-http203?path=public%2Fclient.js%3A191%3A45). +You can find a demo application which implements Background Fetch [on Glitch](https://glitch.com/edit/#!/bgfetch-http203?path=public%2Fclient.js%3A191%3A45). ## Specifications diff --git a/files/en-us/web/api/background_tasks_api/index.md b/files/en-us/web/api/background_tasks_api/index.md index 6412527f0e46ae4..a16505f4bed6e3d 100644 --- a/files/en-us/web/api/background_tasks_api/index.md +++ b/files/en-us/web/api/background_tasks_api/index.md @@ -196,26 +196,22 @@ Finally, we set up a couple of variables for other items: - `statusRefreshScheduled` is used to track whether or not we've already scheduled an update of the status display box for the upcoming frame, so that we only do it once per frame ```js hidden -requestIdleCallback = - requestIdleCallback || - ((handler) => { - const startTime = Date.now(); - - return setTimeout(() => { - handler({ - didTimeout: false, - timeRemaining() { - return Math.max(0, 50.0 - (Date.now() - startTime)); - }, - }); - }, 1); - }); - -cancelIdleCallback = - cancelIdleCallback || - ((id) => { - clearTimeout(id); - }); +window.requestIdleCallback ||= (handler) => { + const startTime = Date.now(); + + return setTimeout(() => { + handler({ + didTimeout: false, + timeRemaining() { + return Math.max(0, 50.0 - (Date.now() - startTime)); + }, + }); + }, 1); +}; + +window.cancelIdleCallback ||= (id) => { + clearTimeout(id); +}; ``` #### Managing the task queue @@ -235,9 +231,7 @@ function enqueueTask(taskHandler, taskData) { totalTaskCount++; - if (!taskHandle) { - taskHandle = requestIdleCallback(runTaskQueue, { timeout: 1000 }); - } + taskHandle ||= requestIdleCallback(runTaskQueue, { timeout: 1000 }); scheduleStatusRefresh(); } @@ -358,10 +352,7 @@ The `log()` function adds the specified text to the log. Since we don't know at ```js function log(text) { - if (!logFragment) { - logFragment = document.createDocumentFragment(); - } - + logFragment ??= document.createDocumentFragment(); const el = document.createElement("div"); el.textContent = text; logFragment.appendChild(el); diff --git a/files/en-us/web/api/backgroundfetchregistration/progress_event/index.md b/files/en-us/web/api/backgroundfetchregistration/progress_event/index.md index b9b1ff8210cfa2c..a42a3fae2542ce6 100644 --- a/files/en-us/web/api/backgroundfetchregistration/progress_event/index.md +++ b/files/en-us/web/api/backgroundfetchregistration/progress_event/index.md @@ -21,10 +21,11 @@ Practically, this event is fired when any of the following properties will retur ## Syntax -Use the event name in methods like {{domxref("EventTarget.addEventListener", "addEventListener()")}}, or set the `onprogress` event property on the relevant {{domxref("BackgroundFetchRegistration")}} object. +Use the event name in methods like {{domxref("EventTarget.addEventListener", "addEventListener()")}}, or set an event handler property. ```js-nolint addEventListener("progress", (event) => { }) + onprogress = (event) => { } ``` diff --git a/files/en-us/web/api/baseaudiocontext/createbiquadfilter/index.md b/files/en-us/web/api/baseaudiocontext/createbiquadfilter/index.md index 6ef96ee4d2f7df2..51e2619558c0c9b 100644 --- a/files/en-us/web/api/baseaudiocontext/createbiquadfilter/index.md +++ b/files/en-us/web/api/baseaudiocontext/createbiquadfilter/index.md @@ -39,14 +39,14 @@ For more complete applied examples/information, check out our [Voice-change-O-ma ```js const audioCtx = new AudioContext(); -//set up the different audio nodes we will use for the app +// Set up the different audio nodes we will use for the app const analyser = audioCtx.createAnalyser(); const distortion = audioCtx.createWaveShaper(); const gainNode = audioCtx.createGain(); const biquadFilter = audioCtx.createBiquadFilter(); const convolver = audioCtx.createConvolver(); -// connect the nodes together +// Connect the nodes together source = audioCtx.createMediaStreamSource(stream); source.connect(analyser); diff --git a/files/en-us/web/api/baseaudiocontext/createbuffersource/index.md b/files/en-us/web/api/baseaudiocontext/createbuffersource/index.md index 290ed4ed53e8c27..dfaa8498fe22673 100644 --- a/files/en-us/web/api/baseaudiocontext/createbuffersource/index.md +++ b/files/en-us/web/api/baseaudiocontext/createbuffersource/index.md @@ -64,7 +64,7 @@ const myArrayBuffer = audioCtx.createBuffer( button.onclick = () => { // Fill the buffer with white noise; - //just random values between -1.0 and 1.0 + // just random values between -1.0 and 1.0 for (let channel = 0; channel < channels; channel++) { // This gives us the actual ArrayBuffer that contains the data const nowBuffering = myArrayBuffer.getChannelData(channel); diff --git a/files/en-us/web/api/baseaudiocontext/createconvolver/index.md b/files/en-us/web/api/baseaudiocontext/createconvolver/index.md index 0e5445bd4e7c822..80b1b4bf4d4252a 100644 --- a/files/en-us/web/api/baseaudiocontext/createconvolver/index.md +++ b/files/en-us/web/api/baseaudiocontext/createconvolver/index.md @@ -45,10 +45,10 @@ For more complete applied examples/information, check out our [Voice-change-O-ma ```js const audioCtx = new AudioContext(); -// ... +// … const convolver = audioCtx.createConvolver(); -// ... +// … // Grab audio track via fetch() for convolver node try { diff --git a/files/en-us/web/api/baseaudiocontext/createperiodicwave/index.md b/files/en-us/web/api/baseaudiocontext/createperiodicwave/index.md index 915068942d622c2..b264abbc5cdad3a 100644 --- a/files/en-us/web/api/baseaudiocontext/createperiodicwave/index.md +++ b/files/en-us/web/api/baseaudiocontext/createperiodicwave/index.md @@ -70,7 +70,7 @@ This works because a sound that contains only a fundamental tone is by definitio Here, we create a `PeriodicWave` with two values. The first value is the DC offset, which is the value at which the oscillator starts. A value of `0` is good here because it starts the curve at the middle of the `[-1.0; 1.0]` range. The second and subsequent values are sine and cosine components, similar to the result of a Fourier transform, which converts time domain values to frequency domain values. Here, with `createPeriodicWave()`, you specify the frequencies, and the browser performs an inverse Fourier transform to get a time domain buffer for the frequency of the oscillator. In this example, we set only one component at full volume (`1.0`) on the fundamental tone, so we get a sine wave. Bear in mind that the fundamental tone corresponds to the oscillator's frequency (which, by default, is `440 Hz`). Therefore, altering the oscillator's frequency effectively shifts the frequency of this periodic wave along with it. -The coefficients of the Fourier transform should be given in _ascending_ order (i.e. <math><semantics><mrow><mrow><mo>(</mo><mrow><mi>a</mi><mo>+</mo><mi>b</mi><mi>i</mi></mrow><mo>)</mo></mrow><msup><mi>e</mi><mi>i</mi></msup><mo>,</mo><mrow><mo>(</mo><mrow><mi>c</mi><mo>+</mo><mi>d</mi><mi>i</mi></mrow><mo>)</mo></mrow><msup><mi>e</mi><mrow><mn>2</mn><mi>i</mi></mrow></msup><mo>,</mo><mrow><mo>(</mo><mrow><mi>f</mi><mo>+</mo><mi>g</mi><mi>i</mi></mrow><mo>)</mo></mrow><msup><mi>e</mi><mrow><mn>3</mn><mi>i</mi></mrow></msup></mrow><annotation encoding="TeX">\left(a+bi\right)e^{i} , \left(c+di\right)e^{2i} ,\left(f+gi\right)e^{3i} </annotation></semantics></math> etc.) and can be positive or negative. A simple way of manually obtaining such coefficients (though not the best) is to use a graphing calculator. +The coefficients of the Fourier transform should be given in _ascending_ order (i.e., <math><semantics><mrow><mrow><mo>(</mo><mrow><mi>a</mi><mo>+</mo><mi>b</mi><mi>i</mi></mrow><mo>)</mo></mrow><msup><mi>e</mi><mi>i</mi></msup><mo>,</mo><mrow><mo>(</mo><mrow><mi>c</mi><mo>+</mo><mi>d</mi><mi>i</mi></mrow><mo>)</mo></mrow><msup><mi>e</mi><mrow><mn>2</mn><mi>i</mi></mrow></msup><mo>,</mo><mrow><mo>(</mo><mrow><mi>f</mi><mo>+</mo><mi>g</mi><mi>i</mi></mrow><mo>)</mo></mrow><msup><mi>e</mi><mrow><mn>3</mn><mi>i</mi></mrow></msup></mrow><annotation encoding="TeX">\left(a+bi\right)e^{i} , \left(c+di\right)e^{2i} ,\left(f+gi\right)e^{3i} </annotation></semantics></math> etc.) and can be positive or negative. A simple way of manually obtaining such coefficients (though not the best) is to use a graphing calculator. ## Specifications diff --git a/files/en-us/web/api/baseaudiocontext/createwaveshaper/index.md b/files/en-us/web/api/baseaudiocontext/createwaveshaper/index.md index 30e3c9e26a79a7e..8bda98af5aa54c9 100644 --- a/files/en-us/web/api/baseaudiocontext/createwaveshaper/index.md +++ b/files/en-us/web/api/baseaudiocontext/createwaveshaper/index.md @@ -34,7 +34,7 @@ A {{domxref("WaveShaperNode")}}. ## Examples The following example shows basic usage of an AudioContext to create a wave shaper node. -For more complete applied examples/information, check out our [Voice-change-O-matic](https://github.com/mdn/webaudio-examples/tree/main/voice-change-o-matic) demo (see [app.js lines 108–193](https://github.com/mdn/webaudio-examples/blob/main/voice-change-o-matic/scripts/app.js#L108-L193) for relevant code). +For more complete applied examples/information, check out our [Voice-change-O-matic](https://github.com/mdn/webaudio-examples/tree/main/voice-change-o-matic) demo (see [app.js](https://github.com/mdn/webaudio-examples/blob/main/voice-change-o-matic/scripts/app.js) for relevant code). > [!NOTE] > Sigmoid functions are commonly used for distortion curves diff --git a/files/en-us/web/api/baseaudiocontext/state/index.md b/files/en-us/web/api/baseaudiocontext/state/index.md index 5253439cd420aee..a9e609be9bb4898 100644 --- a/files/en-us/web/api/baseaudiocontext/state/index.md +++ b/files/en-us/web/api/baseaudiocontext/state/index.md @@ -39,7 +39,7 @@ audioCtx.onstatechange = () => { ### Resuming interrupted play states in iOS Safari -In iOS Safari, when a user leaves the page (e.g. switches tabs, minimizes the browser, or +In iOS Safari, when a user leaves the page (e.g., switches tabs, minimizes the browser, or turns off the screen) the audio context's state changes to "interrupted" and needs to be resumed. For example: diff --git a/files/en-us/web/api/battery_status_api/index.md b/files/en-us/web/api/battery_status_api/index.md index 61c6401fef18e55..06a36320490db05 100644 --- a/files/en-us/web/api/battery_status_api/index.md +++ b/files/en-us/web/api/battery_status_api/index.md @@ -69,7 +69,7 @@ navigator.getBattery().then((battery) => { }); ``` -See also [the example in the specification](https://www.w3.org/TR/battery-status/#examples). +See also [the example in the specification](https://w3c.github.io/battery/#examples). ## Specifications diff --git a/files/en-us/web/api/biquadfilternode/detune/index.md b/files/en-us/web/api/biquadfilternode/detune/index.md index a147ad5bc8ae6d9..363182ffe0f0695 100644 --- a/files/en-us/web/api/biquadfilternode/detune/index.md +++ b/files/en-us/web/api/biquadfilternode/detune/index.md @@ -25,14 +25,14 @@ For more complete applied examples/information, check out our [Voice-change-O-ma ```js const audioCtx = new AudioContext(); -//set up the different audio nodes we will use for the app +// Set up the different audio nodes we will use for the app const analyser = audioCtx.createAnalyser(); const distortion = audioCtx.createWaveShaper(); const gainNode = audioCtx.createGain(); const biquadFilter = audioCtx.createBiquadFilter(); const convolver = audioCtx.createConvolver(); -// connect the nodes together +// Connect the nodes together source = audioCtx.createMediaStreamSource(stream); source.connect(analyser); diff --git a/files/en-us/web/api/biquadfilternode/frequency/index.md b/files/en-us/web/api/biquadfilternode/frequency/index.md index 1fe71288c753a2a..d364ca73604c193 100644 --- a/files/en-us/web/api/biquadfilternode/frequency/index.md +++ b/files/en-us/web/api/biquadfilternode/frequency/index.md @@ -27,14 +27,14 @@ For a complete working example, check out our [voice-change-o-matic](https://mdn ```js const audioCtx = new AudioContext(); -//set up the different audio nodes we will use for the app +// Set up the different audio nodes we will use for the app const analyser = audioCtx.createAnalyser(); const distortion = audioCtx.createWaveShaper(); const gainNode = audioCtx.createGain(); const biquadFilter = audioCtx.createBiquadFilter(); const convolver = audioCtx.createConvolver(); -// connect the nodes together +// Connect the nodes together source = audioCtx.createMediaStreamSource(stream); source.connect(analyser); diff --git a/files/en-us/web/api/biquadfilternode/gain/index.md b/files/en-us/web/api/biquadfilternode/gain/index.md index a01015d69350a42..008ca47e9d64760 100644 --- a/files/en-us/web/api/biquadfilternode/gain/index.md +++ b/files/en-us/web/api/biquadfilternode/gain/index.md @@ -29,14 +29,14 @@ For more complete applied examples/information, check out our [Voice-change-O-ma ```js const audioCtx = new AudioContext(); -//set up the different audio nodes we will use for the app +// Set up the different audio nodes we will use for the app const analyser = audioCtx.createAnalyser(); const distortion = audioCtx.createWaveShaper(); const gainNode = audioCtx.createGain(); const biquadFilter = audioCtx.createBiquadFilter(); const convolver = audioCtx.createConvolver(); -// connect the nodes together +// Connect the nodes together source = audioCtx.createMediaStreamSource(stream); source.connect(analyser); diff --git a/files/en-us/web/api/biquadfilternode/q/index.md b/files/en-us/web/api/biquadfilternode/q/index.md index cfe465bc925b9bf..ff90381b8b6a2f6 100644 --- a/files/en-us/web/api/biquadfilternode/q/index.md +++ b/files/en-us/web/api/biquadfilternode/q/index.md @@ -32,14 +32,14 @@ For more complete applied examples/information, check out our [Voice-change-O-ma ```js const audioCtx = new AudioContext(); -//set up the different audio nodes we will use for the app +// Set up the different audio nodes we will use for the app const analyser = audioCtx.createAnalyser(); const distortion = audioCtx.createWaveShaper(); const gainNode = audioCtx.createGain(); const biquadFilter = audioCtx.createBiquadFilter(); const convolver = audioCtx.createConvolver(); -// connect the nodes together +// Connect the nodes together source = audioCtx.createMediaStreamSource(stream); source.connect(analyser); diff --git a/files/en-us/web/api/biquadfilternode/type/index.md b/files/en-us/web/api/biquadfilternode/type/index.md index 91939a130c76b3a..bd1ad849311b47b 100644 --- a/files/en-us/web/api/biquadfilternode/type/index.md +++ b/files/en-us/web/api/biquadfilternode/type/index.md @@ -166,14 +166,14 @@ For more complete applied examples/information, check out our [Voice-change-O-ma ```js const audioCtx = new AudioContext(); -//set up the different audio nodes we will use for the app +// Set up the different audio nodes we will use for the app const analyser = audioCtx.createAnalyser(); const distortion = audioCtx.createWaveShaper(); const gainNode = audioCtx.createGain(); const biquadFilter = audioCtx.createBiquadFilter(); const convolver = audioCtx.createConvolver(); -// connect the nodes together +// Connect the nodes together source = audioCtx.createMediaStreamSource(stream); source.connect(analyser); diff --git a/files/en-us/web/api/blob/index.md b/files/en-us/web/api/blob/index.md index b21502ec8bdf70a..b6fd34324f4a69e 100644 --- a/files/en-us/web/api/blob/index.md +++ b/files/en-us/web/api/blob/index.md @@ -67,7 +67,7 @@ The following example creates a JavaScript [typed array](/en-US/docs/Web/JavaScr </p> ``` -The main piece of this code for example purposes is the `typedArrayToURL()` function, which creates a `Blob` from the given typed array and returns an object URL for it. Having converted the data into an object URL, it can be used in a number of ways, including as the value of the {{HTMLElement("img")}} element's [`src`](/en-US/docs/Web/HTML/Element/img#src) attribute (assuming the data contains an image, of course). +The main piece of this code for example purposes is the `typedArrayToURL()` function, which creates a `Blob` from the given typed array and returns an object URL for it. Having converted the data into an object URL, it can be used in a number of ways, including as the value of the {{HTMLElement("img")}} element's [`src`](/en-US/docs/Web/HTML/Reference/Elements/img#src) attribute (assuming the data contains an image, of course). ```js live-sample___url-from-array function showViewLiveResultButton() { diff --git a/files/en-us/web/api/blob/slice/index.md b/files/en-us/web/api/blob/slice/index.md index 64f9ad552ab5cff..a713d7af9a340a7 100644 --- a/files/en-us/web/api/blob/slice/index.md +++ b/files/en-us/web/api/blob/slice/index.md @@ -32,7 +32,7 @@ slice(start, end, contentType) {{domxref("Blob")}}, the returned {{domxref("Blob")}} has size 0 and contains no data. - `end` {{optional_inline}} - : An index into the {{domxref("Blob")}} indicating the first byte that will _not_ be - included in the new {{domxref("Blob")}} (i.e. the byte exactly at this index is not + included in the new {{domxref("Blob")}} (i.e., the byte exactly at this index is not included). If you specify a negative value, it's treated as an offset from the end of the {{domxref("Blob")}} toward the beginning. For example, -10 would be the 10th from last byte in the {{domxref("Blob")}}. The default value is `size`. diff --git a/files/en-us/web/api/bluetooth/getavailability/index.md b/files/en-us/web/api/bluetooth/getavailability/index.md index f72a9b87effadeb..410ccfebfb7d5b4 100644 --- a/files/en-us/web/api/bluetooth/getavailability/index.md +++ b/files/en-us/web/api/bluetooth/getavailability/index.md @@ -12,7 +12,7 @@ browser-compat: api.Bluetooth.getAvailability The **`getAvailability()`** method of the {{DOMxRef("Bluetooth")}} interface _nominally_ returns `true` if the user agent can support Bluetooth (because the device has a Bluetooth adapter), and `false` otherwise. -The word "nominally" is used because if permission to use the Web Bluetooth API is disallowed by the [`Permissions-Policy: bluetooth`](/en-US/docs/Web/HTTP/Headers/Permissions-Policy/bluetooth) permission, the method will always return `false`. +The word "nominally" is used because if permission to use the Web Bluetooth API is disallowed by the [`Permissions-Policy: bluetooth`](/en-US/docs/Web/HTTP/Reference/Headers/Permissions-Policy/bluetooth) permission, the method will always return `false`. In addition, a user can configure their browser to return `false` from a `getAvailability()` call even if the browser does have an operational Bluetooth adapter, and vice versa. This setting value ignored if access is blocked by the permission. Even if `getAvailability()` returns `true` and the device actually has a Bluetooth adaptor, this does not necessarily mean that calling {{DOMxRef("Bluetooth.requestDevice","navigator.bluetooth.requestDevice()")}} will resolve with a {{DOMxRef("BluetoothDevice")}}. @@ -32,7 +32,7 @@ None. A {{JSxRef("Promise")}} that resolves with a {{JSxRef("Boolean")}}. -The {{JSxRef("Promise")}} will resolve with a value of `false` if access is disallowed by [`Permissions-Policy: bluetooth`](/en-US/docs/Web/HTTP/Headers/Permissions-Policy/bluetooth), if the user has configured the browser to always resolve with `false`, or if the device does not have a Bluetooth adapter. +The {{JSxRef("Promise")}} will resolve with a value of `false` if access is disallowed by [`Permissions-Policy: bluetooth`](/en-US/docs/Web/HTTP/Reference/Headers/Permissions-Policy/bluetooth), if the user has configured the browser to always resolve with `false`, or if the device does not have a Bluetooth adapter. Otherwise it will resolve with `true`. ### Exceptions diff --git a/files/en-us/web/api/bluetooth/getdevices/index.md b/files/en-us/web/api/bluetooth/getdevices/index.md index 74e0af587974d3a..36b10a3c16863a9 100644 --- a/files/en-us/web/api/bluetooth/getdevices/index.md +++ b/files/en-us/web/api/bluetooth/getdevices/index.md @@ -29,7 +29,7 @@ A {{JSxRef("Promise")}} that resolves with an array of {{DOMxRef("BluetoothDevic ### Exceptions - `SecurityError` {{domxref("DOMException")}} - - : Thrown if this operation is not permitted in this context due to [security concerns](/en-US/docs/Web/API/Web_Bluetooth_API#security_considerations), such as being called when access to the current document is blocked by the [Permissions Policy](/en-US/docs/Web/HTTP/Permissions_Policy) directive {{HTTPHeader("Permissions-Policy/bluetooth","bluetooth")}}. + - : Thrown if this operation is not permitted in this context due to [security concerns](/en-US/docs/Web/API/Web_Bluetooth_API#security_considerations), such as being called when access to the current document is blocked by the [Permissions Policy](/en-US/docs/Web/HTTP/Guides/Permissions_Policy) directive {{HTTPHeader("Permissions-Policy/bluetooth","bluetooth")}}. ## Specifications diff --git a/files/en-us/web/api/broadcastchannel/message_event/index.md b/files/en-us/web/api/broadcastchannel/message_event/index.md index f4defa72dff3ac8..10f4b9c6838d4f7 100644 --- a/files/en-us/web/api/broadcastchannel/message_event/index.md +++ b/files/en-us/web/api/broadcastchannel/message_event/index.md @@ -16,6 +16,7 @@ Use the event name in methods like {{domxref("EventTarget.addEventListener", "ad ```js-nolint addEventListener("message", (event) => { }) + onmessage = (event) => { } ``` @@ -38,7 +39,7 @@ _In addition to the properties listed below, properties from the parent interfac - {{domxref("MessageEvent.source", "source")}} {{ReadOnlyInline}} - : A _message event source_, which is either a {{glossary("WindowProxy")}}, a {{domxref("MessagePort")}}, or a {{domxref("ServiceWorker")}} object representing the message emitter. - {{domxref("MessageEvent.ports", "ports")}} {{ReadOnlyInline}} - - : An array of {{domxref("MessagePort")}} objects representing the ports associated with the channel the message is being sent through (where appropriate, e.g. in channel messaging or when sending a message to a shared worker). + - : An array of {{domxref("MessagePort")}} objects representing the ports associated with the channel the message is being sent through (where appropriate, e.g., in channel messaging or when sending a message to a shared worker). ## Examples diff --git a/files/en-us/web/api/broadcastchannel/messageerror_event/index.md b/files/en-us/web/api/broadcastchannel/messageerror_event/index.md index 8c582a35bc045bf..a0b4e42846eb6c1 100644 --- a/files/en-us/web/api/broadcastchannel/messageerror_event/index.md +++ b/files/en-us/web/api/broadcastchannel/messageerror_event/index.md @@ -16,6 +16,7 @@ Use the event name in methods like {{domxref("EventTarget.addEventListener", "ad ```js-nolint addEventListener("messageerror", (event) => { }) + onmessageerror = (event) => { } ``` @@ -38,7 +39,7 @@ _In addition to the properties listed below, properties from the parent interfac - {{domxref("MessageEvent.source", "source")}} {{ReadOnlyInline}} - : A _message event source_, which is either a {{glossary("WindowProxy")}}, a {{domxref("MessagePort")}}, or a {{domxref("ServiceWorker")}} object representing the message emitter. - {{domxref("MessageEvent.ports", "ports")}} {{ReadOnlyInline}} - - : An array of {{domxref("MessagePort")}} objects representing the ports associated with the channel the message is being sent through (where appropriate, e.g. in channel messaging or when sending a message to a shared worker). + - : An array of {{domxref("MessagePort")}} objects representing the ports associated with the channel the message is being sent through (where appropriate, e.g., in channel messaging or when sending a message to a shared worker). ## Examples diff --git a/files/en-us/web/api/browsercapturemediastreamtrack/clone/index.md b/files/en-us/web/api/browsercapturemediastreamtrack/clone/index.md index a16b07d0d065033..91b4ec67a961886 100644 --- a/files/en-us/web/api/browsercapturemediastreamtrack/clone/index.md +++ b/files/en-us/web/api/browsercapturemediastreamtrack/clone/index.md @@ -15,7 +15,7 @@ The **`clone()`** method of the {{domxref("BrowserCaptureMediaStreamTrack")}} in This method is functionally identical to {{domxref("MediaStreamTrack.clone()")}}, except that it handles cases where cropping or restriction have been applied to the track. The returned clone is identical to the original `BrowserCaptureMediaStreamTrack`, but with any cropping or restriction removed. > [!NOTE] -> In Chromium, if a track has clones, its {{domxref("BrowserCaptureMediaStreamTrack.cropTo", "cropTo()")}} and {{domxref("BrowserCaptureMediaStreamTrack.restrictTo", "restrictTo()")}} methods will reject (see [Chrome issue 41482026](https://issues.chromium.org/issues/41482026)). +> In Chromium, if a track has clones, its {{domxref("BrowserCaptureMediaStreamTrack.cropTo", "cropTo()")}} and {{domxref("BrowserCaptureMediaStreamTrack.restrictTo", "restrictTo()")}} methods will reject (see [Chrome issue 41482026](https://crbug.com/41482026)). ## Syntax diff --git a/files/en-us/web/api/browsercapturemediastreamtrack/cropto/index.md b/files/en-us/web/api/browsercapturemediastreamtrack/cropto/index.md index 2e59ba6a027f874..ab5da285eb6941f 100644 --- a/files/en-us/web/api/browsercapturemediastreamtrack/cropto/index.md +++ b/files/en-us/web/api/browsercapturemediastreamtrack/cropto/index.md @@ -36,7 +36,7 @@ The promise will reject if: - `cropTarget` was created in a tab other than the one being captured. > [!NOTE] -> In Chromium, if a track has clones, `cropTo()` will reject (see [Chrome issue 41482026](https://issues.chromium.org/issues/41482026)). +> In Chromium, if a track has clones, `cropTo()` will reject (see [Chrome issue 41482026](https://crbug.com/41482026)). ## Examples diff --git a/files/en-us/web/api/browsercapturemediastreamtrack/restrictto/index.md b/files/en-us/web/api/browsercapturemediastreamtrack/restrictto/index.md index 213e3656682b428..6952ceb1a6ae40f 100644 --- a/files/en-us/web/api/browsercapturemediastreamtrack/restrictto/index.md +++ b/files/en-us/web/api/browsercapturemediastreamtrack/restrictto/index.md @@ -36,7 +36,7 @@ The promise will reject if: - `restrictionTarget` was created in a tab other than the one being captured. > [!NOTE] -> In Chromium, if a track has clones, `restrictTo()` will reject (see [Chrome issue 41482026](https://issues.chromium.org/issues/41482026)). +> In Chromium, if a track has clones, `restrictTo()` will reject (see [Chrome issue 41482026](https://crbug.com/41482026)). ## Examples diff --git a/files/en-us/web/api/cache/delete/index.md b/files/en-us/web/api/cache/delete/index.md index 8ac305be74eed89..5a5fbd205851f7f 100644 --- a/files/en-us/web/api/cache/delete/index.md +++ b/files/en-us/web/api/cache/delete/index.md @@ -54,11 +54,12 @@ deleted, or `false` otherwise. ## Examples ```js -caches.open("v1").then((cache) => { - cache.delete("/images/image.png").then((response) => { +caches + .open("v1") + .then((cache) => cache.delete("/images/image.png")) + .then((response) => { someUIUpdateFunction(); }); -}); ``` ## Specifications diff --git a/files/en-us/web/api/cache/index.md b/files/en-us/web/api/cache/index.md index 3cc1e3cf994c1db..06ed21383bdcad2 100644 --- a/files/en-us/web/api/cache/index.md +++ b/files/en-us/web/api/cache/index.md @@ -9,7 +9,7 @@ browser-compat: api.Cache The **`Cache`** interface provides a persistent storage mechanism for {{domxref("Request")}} / {{domxref("Response")}} object pairs that are cached in long lived memory. How long a `Cache` object lives is browser dependent, but a single origin's scripts can typically rely on the presence of a previously populated `Cache` object. Note that the `Cache` interface is exposed to windowed scopes as well as workers. You don't have to use it in conjunction with service workers, even though it is defined in the service worker spec. -An origin can have multiple, named `Cache` objects. You are responsible for implementing how your script (e.g. in a {{domxref("ServiceWorker")}}) handles `Cache` updates. Items in a `Cache` do not get updated unless explicitly requested; they don't expire unless deleted. Use {{domxref("CacheStorage.open", "CacheStorage.open()")}} to open a specific named `Cache` object and then call any of the `Cache` methods to maintain the `Cache`. +An origin can have multiple, named `Cache` objects. You are responsible for implementing how your script (e.g., in a {{domxref("ServiceWorker")}}) handles `Cache` updates. Items in a `Cache` do not get updated unless explicitly requested; they don't expire unless deleted. Use {{domxref("CacheStorage.open", "CacheStorage.open()")}} to open a specific named `Cache` object and then call any of the `Cache` methods to maintain the `Cache`. You are also responsible for periodically purging cache entries. Each browser has a hard limit on the amount of cache storage that a given origin can use. `Cache` quota usage estimates are available via the {{domxref("StorageManager.estimate()")}} method. The browser does its best to manage disk space, but it may delete the `Cache` storage for an origin. The browser will generally delete all of the data for an origin or none of the data for an origin. Make sure to version caches by name and use the caches only from the version of the script that they can safely operate on. See [Deleting old caches](/en-US/docs/Web/API/Service_Worker_API/Using_Service_Workers#deleting_old_caches) for more information. @@ -72,6 +72,7 @@ self.addEventListener("activate", (event) => { console.log("Deleting out of date cache:", cacheName); return caches.delete(cacheName); } + return undefined; }), ), ), @@ -82,86 +83,85 @@ self.addEventListener("fetch", (event) => { console.log("Handling fetch event for", event.request.url); event.respondWith( - caches.open(CURRENT_CACHES.font).then((cache) => { - return cache - .match(event.request) - .then((response) => { - if (response) { - // If there is an entry in the cache for event.request, - // then response will be defined and we can just return it. - // Note that in this example, only font resources are cached. - console.log(" Found response in cache:", response); - - return response; - } - - // Otherwise, if there is no entry in the cache for event.request, - // response will be undefined, and we need to fetch() the resource. + caches + .open(CURRENT_CACHES.font) + .then((cache) => cache.match(event.request)) + .then((response) => { + if (response) { + // If there is an entry in the cache for event.request, + // then response will be defined and we can just return it. + // Note that in this example, only font resources are cached. + console.log(" Found response in cache:", response); + + return response; + } + + // Otherwise, if there is no entry in the cache for event.request, + // response will be undefined, and we need to fetch() the resource. + console.log( + " No response for %s found in cache. About to fetch " + + "from network…", + event.request.url, + ); + + // We call .clone() on the request since we might use it + // in a call to cache.put() later on. + // Both fetch() and cache.put() "consume" the request, + // so we need to make a copy. + // (see https://developer.mozilla.org/en-US/docs/Web/API/Request/clone) + return fetch(event.request.clone()).then((response) => { console.log( - " No response for %s found in cache. About to fetch " + - "from network…", + " Response for %s from network is: %O", event.request.url, + response, ); - // We call .clone() on the request since we might use it - // in a call to cache.put() later on. - // Both fetch() and cache.put() "consume" the request, - // so we need to make a copy. - // (see https://developer.mozilla.org/en-US/docs/Web/API/Request/clone) - return fetch(event.request.clone()).then((response) => { - console.log( - " Response for %s from network is: %O", - event.request.url, - response, - ); - - if ( - response.status < 400 && - response.headers.has("content-type") && - response.headers.get("content-type").match(/^font\//i) - ) { - // This avoids caching responses that we know are errors - // (i.e. HTTP status code of 4xx or 5xx). - // We also only want to cache responses that correspond - // to fonts, i.e. have a Content-Type response header that - // starts with "font/". - // Note that for opaque filtered responses - // https://fetch.spec.whatwg.org/#concept-filtered-response-opaque - // we can't access to the response headers, so this check will - // always fail and the font won't be cached. - // All of the Google Web Fonts are served from a domain that - // supports CORS, so that isn't an issue here. - // It is something to keep in mind if you're attempting - // to cache other resources from a cross-origin - // domain that doesn't support CORS, though! - console.log(" Caching the response to", event.request.url); - // We call .clone() on the response to save a copy of it - // to the cache. By doing so, we get to keep the original - // response object which we will return back to the controlled - // page. - // https://developer.mozilla.org/en-US/docs/Web/API/Request/clone - cache.put(event.request, response.clone()); - } else { - console.log(" Not caching the response to", event.request.url); - } - - // Return the original response object, which will be used to - // fulfill the resource request. - return response; - }); - }) - .catch((error) => { - // This catch() will handle exceptions that arise from the match() - // or fetch() operations. - // Note that a HTTP error response (e.g. 404) will NOT trigger - // an exception. - // It will return a normal response object that has the appropriate - // error code set. - console.error(" Error in fetch handler:", error); - - throw error; + if ( + response.status < 400 && + response.headers.has("content-type") && + response.headers.get("content-type").match(/^font\//i) + ) { + // This avoids caching responses that we know are errors + // (i.e. HTTP status code of 4xx or 5xx). + // We also only want to cache responses that correspond + // to fonts, i.e. have a Content-Type response header that + // starts with "font/". + // Note that for opaque filtered responses + // https://fetch.spec.whatwg.org/#concept-filtered-response-opaque + // we can't access to the response headers, so this check will + // always fail and the font won't be cached. + // All of the Google Web Fonts are served from a domain that + // supports CORS, so that isn't an issue here. + // It is something to keep in mind if you're attempting + // to cache other resources from a cross-origin + // domain that doesn't support CORS, though! + console.log(" Caching the response to", event.request.url); + // We call .clone() on the response to save a copy of it + // to the cache. By doing so, we get to keep the original + // response object which we will return back to the controlled + // page. + // https://developer.mozilla.org/en-US/docs/Web/API/Request/clone + cache.put(event.request, response.clone()); + } else { + console.log(" Not caching the response to", event.request.url); + } + + // Return the original response object, which will be used to + // fulfill the resource request. + return response; }); - }), + }) + .catch((error) => { + // This catch() will handle exceptions that arise from the match() + // or fetch() operations. + // Note that a HTTP error response (e.g. 404) will NOT trigger + // an exception. + // It will return a normal response object that has the appropriate + // error code set. + console.error(" Error in fetch handler:", error); + + throw error; + }), ); }); ``` diff --git a/files/en-us/web/api/cache/keys/index.md b/files/en-us/web/api/cache/keys/index.md index 8bc33162924ad58..cfdf4a910aab1ba 100644 --- a/files/en-us/web/api/cache/keys/index.md +++ b/files/en-us/web/api/cache/keys/index.md @@ -66,13 +66,14 @@ objects. ## Examples ```js -caches.open("v1").then((cache) => { - cache.keys().then((keys) => { +caches + .open("v1") + .then((cache) => cache.keys()) + .then((keys) => { keys.forEach((request, index, array) => { cache.delete(request); }); }); -}); ``` ## Specifications diff --git a/files/en-us/web/api/cache/match/index.md b/files/en-us/web/api/cache/match/index.md index 3058ddc0e3eb01c..abef507779fd3c9 100644 --- a/files/en-us/web/api/cache/match/index.md +++ b/files/en-us/web/api/cache/match/index.md @@ -42,7 +42,7 @@ match(request, options) - `ignoreVary` - : A boolean value that when set to `true` tells the matching operation not to perform `VARY` - header matching — i.e. if the URL matches you will get a match regardless of + header matching — i.e., if the URL matches you will get a match regardless of whether the {{domxref("Response")}} object has a `VARY` header. It defaults to `false`. diff --git a/files/en-us/web/api/cache/matchall/index.md b/files/en-us/web/api/cache/matchall/index.md index 8d6e6e5a6bf543f..4add07427f820e0 100644 --- a/files/en-us/web/api/cache/matchall/index.md +++ b/files/en-us/web/api/cache/matchall/index.md @@ -45,7 +45,7 @@ matchAll(request, options) - `ignoreVary` - : A boolean value that when set to `true` tells the matching operation not to perform `VARY` - header matching — i.e. if the URL matches you will get a match regardless of the + header matching — i.e., if the URL matches you will get a match regardless of the {{domxref("Response")}} object having a `VARY` header or not. It defaults to `false`. @@ -66,11 +66,12 @@ The following example retrieves all responses in the `v1` cache matching the URL It then logs the number of matching responses. ```js -caches.open("v1").then((cache) => { - cache.matchAll("/", { ignoreSearch: true }).then((responses) => { +caches + .open("v1") + .then((cache) => cache.matchAll("/", { ignoreSearch: true })) + .then((responses) => { console.log(`Found ${responses.length} matching responses`); }); -}); ``` ## Specifications diff --git a/files/en-us/web/api/cache/put/index.md b/files/en-us/web/api/cache/put/index.md index e4c6cc0f80420e6..e9eeea6a5ef2877 100644 --- a/files/en-us/web/api/cache/put/index.md +++ b/files/en-us/web/api/cache/put/index.md @@ -79,9 +79,7 @@ const cachedResponse = caches .then((r) => (r !== undefined ? r : fetch(event.request))) .then((r) => { response = r; - caches.open("v1").then((cache) => { - cache.put(event.request, response); - }); + caches.open("v1").then((cache) => cache.put(event.request, response)); return response.clone(); }) .catch(() => caches.match("/gallery/myLittleVader.jpg")); diff --git a/files/en-us/web/api/cachestorage/delete/index.md b/files/en-us/web/api/cachestorage/delete/index.md index bc5044335254780..67785046ce144a3 100644 --- a/files/en-us/web/api/cachestorage/delete/index.md +++ b/files/en-us/web/api/cachestorage/delete/index.md @@ -50,6 +50,7 @@ this.addEventListener("activate", (event) => { if (!cachesToKeep.includes(key)) { return caches.delete(key); } + return undefined; }), ), ), diff --git a/files/en-us/web/api/cachestorage/index.md b/files/en-us/web/api/cachestorage/index.md index 0a1a9ef97468380..85fa401ff0ec2ef 100644 --- a/files/en-us/web/api/cachestorage/index.md +++ b/files/en-us/web/api/cachestorage/index.md @@ -20,7 +20,7 @@ Use {{domxref("CacheStorage.match()")}} to check if a given {{domxref("Request") You can access `CacheStorage` through the {{domxref("Window.caches")}} property in windows or through the {{domxref("WorkerGlobalScope.caches")}} property in workers. -> **Note:** `CacheStorage` always rejects with a `SecurityError` on untrusted origins (i.e. those that aren't using HTTPS, although this definition will likely become more complex in the future.) When testing on Firefox, you can get around this by checking the **Enable Service Workers over HTTP (when toolbox is open)** option in the Firefox DevTools options/gear menu. Furthermore, because `CacheStorage` requires file-system access, it may be unavailable in private mode in Firefox. +> **Note:** `CacheStorage` always rejects with a `SecurityError` on untrusted origins (i.e., those that aren't using HTTPS, although this definition will likely become more complex in the future.) When testing on Firefox, you can get around this by checking the **Enable Service Workers over HTTP (when toolbox is open)** option in the Firefox DevTools options/gear menu. Furthermore, because `CacheStorage` requires file-system access, it may be unavailable in private mode in Firefox. > **Note:** {{domxref("CacheStorage.match()")}} is a convenience method. Equivalent functionality to match a cache entry can be implemented by returning an array of cache names from {{domxref("CacheStorage.keys()")}}, opening each cache with {{domxref("CacheStorage.open()")}}, and matching the one you want with {{domxref("Cache.match()")}}. @@ -46,7 +46,7 @@ In the second code block, we wait for a {{domxref("FetchEvent")}} to fire. We co 1. Check whether a match for the request is found in the CacheStorage. If so, serve that. 2. If not, fetch the request from the network, then also open the cache created in the first block and add a clone of the request to it using {{domxref("Cache.put")}} (`cache.put(event.request, response.clone())`.) -3. If this fails (e.g. because the network is down), return a fallback response. +3. If this fails (e.g., because the network is down), return a fallback response. Finally, return whatever the custom response ended up being equal to, using {{domxref("FetchEvent.respondWith")}}. @@ -78,21 +78,20 @@ self.addEventListener("fetch", (event) => { // but in case of success response will have value if (response !== undefined) { return response; - } else { - return fetch(event.request) - .then((response) => { - // response may be used only once - // we need to save clone to put one copy in cache - // and serve second one - let responseClone = response.clone(); - - caches.open("v1").then((cache) => { - cache.put(event.request, responseClone); - }); - return response; - }) - .catch(() => caches.match("/gallery/myLittleVader.jpg")); } + return fetch(event.request) + .then((response) => { + // response may be used only once + // we need to save clone to put one copy in cache + // and serve second one + let responseClone = response.clone(); + + caches + .open("v1") + .then((cache) => cache.put(event.request, responseClone)); + return response; + }) + .catch(() => caches.match("/gallery/myLittleVader.jpg")); }), ); }); diff --git a/files/en-us/web/api/cachestorage/keys/index.md b/files/en-us/web/api/cachestorage/keys/index.md index 5990411c095d2fe..bd2b81e381929eb 100644 --- a/files/en-us/web/api/cachestorage/keys/index.md +++ b/files/en-us/web/api/cachestorage/keys/index.md @@ -45,6 +45,7 @@ this.addEventListener("activate", (event) => { if (!cacheAllowlist.includes(key)) { return caches.delete(key); } + return undefined; }), ), ), diff --git a/files/en-us/web/api/cachestorage/match/index.md b/files/en-us/web/api/cachestorage/match/index.md index 0be6bec17ba80b1..9105c471fde3725 100644 --- a/files/en-us/web/api/cachestorage/match/index.md +++ b/files/en-us/web/api/cachestorage/match/index.md @@ -84,21 +84,20 @@ self.addEventListener("fetch", (event) => { // but in case of success response will have value if (response !== undefined) { return response; - } else { - return fetch(event.request) - .then((response) => { - // response may be used only once - // we need to save clone to put one copy in cache - // and serve second one - let responseClone = response.clone(); - - caches.open("v1").then((cache) => { - cache.put(event.request, responseClone); - }); - return response; - }) - .catch(() => caches.match("/gallery/myLittleVader.jpg")); } + return fetch(event.request) + .then((response) => { + // response may be used only once + // we need to save clone to put one copy in cache + // and serve second one + let responseClone = response.clone(); + + caches + .open("v1") + .then((cache) => cache.put(event.request, responseClone)); + return response; + }) + .catch(() => caches.match("/gallery/myLittleVader.jpg")); }), ); }); diff --git a/files/en-us/web/api/canvas_api/index.md b/files/en-us/web/api/canvas_api/index.md index 1d22dfdd2bf6d22..ed720189646efb0 100644 --- a/files/en-us/web/api/canvas_api/index.md +++ b/files/en-us/web/api/canvas_api/index.md @@ -75,7 +75,7 @@ ctx.fillRect(10, 10, 150, 100); The Canvas API is extremely powerful, but not always simple to use. The libraries listed below can make the creation of canvas-based projects faster and easier. - [EaselJS](https://createjs.com/easeljs) is an open-source canvas library that makes creating games, generative art, and other highly graphical experiences easy. -- [Fabric.js](http://fabricjs.com/) is an open-source canvas library with SVG parsing capabilities. +- [Fabric.js](https://fabricjs.com/) is an open-source canvas library with SVG parsing capabilities. - [heatmap.js](https://www.patrick-wied.at/static/heatmapjs/) is an open-source library for creating canvas-based data heat maps. - [JavaScript InfoVis Toolkit](https://philogb.github.io/jit/) creates interactive data visualizations. - [Konva.js](https://konvajs.org/) is a 2D canvas library for desktop and mobile applications. diff --git a/files/en-us/web/api/canvas_api/manipulating_video_using_canvas/index.md b/files/en-us/web/api/canvas_api/manipulating_video_using_canvas/index.md index 31a8cc7c38a2f35..e56f797ff22c1cb 100644 --- a/files/en-us/web/api/canvas_api/manipulating_video_using_canvas/index.md +++ b/files/en-us/web/api/canvas_api/manipulating_video_using_canvas/index.md @@ -6,7 +6,7 @@ page-type: guide {{DefaultAPISidebar("Canvas API")}} -By combining the capabilities of the [`video`](/en-US/docs/Web/HTML/Element/video) element with a [`canvas`](/en-US/docs/Web/HTML/Element/canvas), you can manipulate video data in real time to incorporate a variety of visual effects to the video being displayed. This tutorial demonstrates how to perform chroma-keying (also known as the "green screen effect") using JavaScript code. +By combining the capabilities of the [`video`](/en-US/docs/Web/HTML/Reference/Elements/video) element with a [`canvas`](/en-US/docs/Web/HTML/Reference/Elements/canvas), you can manipulate video data in real time to incorporate a variety of visual effects to the video being displayed. This tutorial demonstrates how to perform chroma-keying (also known as the "green screen effect") using JavaScript code. {{EmbedGHLiveSample('dom-examples/canvas/chroma-keying/index.html', 700, 400) }} @@ -45,7 +45,7 @@ The HTML document used to render this content is shown below. id="video" src="media/video.mp4" controls - crossorigin="anonymous" /> + crossorigin="anonymous"></video> </div> <div> <canvas id="c1" width="160" height="96"></canvas> @@ -58,7 +58,7 @@ The HTML document used to render this content is shown below. The key bits to take away from this are: -1. This document establishes two [`canvas`](/en-US/docs/Web/HTML/Element/canvas) elements, with the IDs `c1` and `c2`. Canvas `c1` is used to display the current frame of the original video, while `c2` is used to display the video after performing the chroma-keying effect; `c2` is preloaded with the still image that will be used to replace the green background in the video. +1. This document establishes two [`canvas`](/en-US/docs/Web/HTML/Reference/Elements/canvas) elements, with the IDs `c1` and `c2`. Canvas `c1` is used to display the current frame of the original video, while `c2` is used to display the video after performing the chroma-keying effect; `c2` is preloaded with the still image that will be used to replace the green background in the video. 2. The JavaScript code is imported from a script named `processor.js`. ## The JavaScript code diff --git a/files/en-us/web/api/canvas_api/tutorial/applying_styles_and_colors/index.md b/files/en-us/web/api/canvas_api/tutorial/applying_styles_and_colors/index.md index 4ca8ab4605ae7a5..4ee4ce04340ee53 100644 --- a/files/en-us/web/api/canvas_api/tutorial/applying_styles_and_colors/index.md +++ b/files/en-us/web/api/canvas_api/tutorial/applying_styles_and_colors/index.md @@ -9,7 +9,7 @@ page-type: guide In the chapter about [drawing shapes](/en-US/docs/Web/API/Canvas_API/Tutorial/Drawing_shapes), we used only the default line and fill styles. Here we will explore the canvas options we have at our disposal to make our drawings a little more attractive. You will learn how to add different colors, line styles, gradients, patterns and shadows to your drawings. > [!NOTE] -> Canvas content is not accessible to screen readers. If the canvas is purely decorative, include `role="presentation"` on the `<canvas>` opening tag. Otherwise, include descriptive text as the value of the [`aria-label`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-label) attribute directly on the canvas element itself or include fallback content placed within the opening and closing canvas tag. Canvas content is not part of the DOM, but nested fallback content is. +> Canvas content is not accessible to screen readers. If the canvas is purely decorative, include `role="presentation"` on the `<canvas>` opening tag. Otherwise, include descriptive text as the value of the [`aria-label`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-label) attribute directly on the canvas element itself or include fallback content placed within the opening and closing canvas tag. Canvas content is not part of the DOM, but nested fallback content is. ## Colors @@ -404,7 +404,7 @@ function draw() { ctx.moveTo(0, 100); for (let i = 0; i < 24; i++) { const dy = i % 2 === 0 ? 25 : -25; - ctx.lineTo(Math.pow(i, 1.5) * 2, 75 + dy); + ctx.lineTo(i ** 1.5 * 2, 75 + dy); } ctx.stroke(); return false; diff --git a/files/en-us/web/api/canvas_api/tutorial/basic_usage/index.md b/files/en-us/web/api/canvas_api/tutorial/basic_usage/index.md index 4665901cfb5f1b4..cbba38ceeb822a6 100644 --- a/files/en-us/web/api/canvas_api/tutorial/basic_usage/index.md +++ b/files/en-us/web/api/canvas_api/tutorial/basic_usage/index.md @@ -14,12 +14,12 @@ Let's start this tutorial by looking at the {{HTMLElement("canvas")}} {{Glossary <canvas id="tutorial" width="150" height="150"></canvas> ``` -At first sight a {{HTMLElement("canvas")}} looks like the {{HTMLElement("img")}} element, with the only clear difference being that it doesn't have the `src` and `alt` attributes. Indeed, the `<canvas>` element has only two attributes, [`width`](/en-US/docs/Web/HTML/Element/canvas#width) and [`height`](/en-US/docs/Web/HTML/Element/canvas#height). These are both optional and can also be set using {{Glossary("DOM")}} [properties](/en-US/docs/Web/API/HTMLCanvasElement). When no `width` and `height` attributes are specified, the canvas will initially be **300 pixels** wide and **150 pixels** high. The element can be sized arbitrarily by {{Glossary("CSS")}}, but during rendering the image is scaled to fit its layout size: if the CSS sizing doesn't respect the ratio of the initial canvas, it will appear distorted. +At first sight a {{HTMLElement("canvas")}} looks like the {{HTMLElement("img")}} element, with the only clear difference being that it doesn't have the `src` and `alt` attributes. Indeed, the `<canvas>` element has only two attributes, [`width`](/en-US/docs/Web/HTML/Reference/Elements/canvas#width) and [`height`](/en-US/docs/Web/HTML/Reference/Elements/canvas#height). These are both optional and can also be set using {{Glossary("DOM")}} [properties](/en-US/docs/Web/API/HTMLCanvasElement). When no `width` and `height` attributes are specified, the canvas will initially be **300 pixels** wide and **150 pixels** high. The element can be sized arbitrarily by {{Glossary("CSS")}}, but during rendering the image is scaled to fit its layout size: if the CSS sizing doesn't respect the ratio of the initial canvas, it will appear distorted. > [!NOTE] > If your renderings seem distorted, try specifying your `width` and `height` attributes explicitly in the `<canvas>` attributes, and not using CSS. -The [`id`](/en-US/docs/Web/HTML/Global_attributes/id) attribute isn't specific to the `<canvas>` element but is one of the [global HTML attributes](/en-US/docs/Web/HTML/Global_attributes) which can be applied to any HTML element (like [`class`](/en-US/docs/Web/HTML/Global_attributes/class) for instance). It is always a good idea to supply an `id` because this makes it much easier to identify it in a script. +The [`id`](/en-US/docs/Web/HTML/Reference/Global_attributes/id) attribute isn't specific to the `<canvas>` element but is one of the [global HTML attributes](/en-US/docs/Web/HTML/Reference/Global_attributes) which can be applied to any HTML element (like [`class`](/en-US/docs/Web/HTML/Reference/Global_attributes/class) for instance). It is always a good idea to supply an `id` because this makes it much easier to identify it in a script. The `<canvas>` element can be styled just like any normal image ({{cssxref("margin")}}, {{cssxref("border")}}, {{cssxref("background")}}…). These rules, however, don't affect the actual drawing on the canvas. We'll see how this is done in a [dedicated chapter](/en-US/docs/Web/API/Canvas_API/Tutorial/Applying_styles_and_colors) of this tutorial. When no styling rules are applied to the canvas it will initially be fully transparent. @@ -130,7 +130,7 @@ To begin, let's take a look at an example that draws two intersecting rectangles </head> <body> <canvas id="canvas" width="150" height="150"></canvas> - <script type="application/javascript"> + <script> function draw() { const canvas = document.getElementById("canvas"); if (canvas.getContext) { diff --git a/files/en-us/web/api/canvas_api/tutorial/drawing_shapes/index.md b/files/en-us/web/api/canvas_api/tutorial/drawing_shapes/index.md index 789e57b92bd387b..4b97cb635e0fcea 100644 --- a/files/en-us/web/api/canvas_api/tutorial/drawing_shapes/index.md +++ b/files/en-us/web/api/canvas_api/tutorial/drawing_shapes/index.md @@ -568,7 +568,7 @@ As we have seen in the last example, there can be a series of paths and drawing Let's see how we can construct a `Path2D` object: - {{domxref("Path2D.Path2D", "Path2D()")}} - - : The **`Path2D()`** constructor returns a newly instantiated `Path2D` object, optionally with another path as an argument (creates a copy), or optionally with a string consisting of [SVG path](/en-US/docs/Web/SVG/Tutorial/Paths) data. + - : The **`Path2D()`** constructor returns a newly instantiated `Path2D` object, optionally with another path as an argument (creates a copy), or optionally with a string consisting of [SVG path](/en-US/docs/Web/SVG/Tutorials/SVG_from_scratch/Paths) data. ```js new Path2D(); // empty path object @@ -621,7 +621,7 @@ draw(); ### Using SVG paths -Another powerful feature of the new canvas `Path2D` API is using [SVG path data](/en-US/docs/Web/SVG/Tutorial/Paths) to initialize paths on your canvas. This might allow you to pass around path data and re-use them in both, SVG and canvas. +Another powerful feature of the new canvas `Path2D` API is using [SVG path data](/en-US/docs/Web/SVG/Tutorials/SVG_from_scratch/Paths) to initialize paths on your canvas. This might allow you to pass around path data and re-use them in both, SVG and canvas. The path will move to point (`M10 10`) and then move horizontally 80 points to the right (`h 80`), then 80 points down (`v 80`), then 80 points to the left (`h -80`), and then back to the start (`z`). You can see this example on the [`Path2D` constructor](/en-US/docs/Web/API/Path2D/Path2D#using_svg_paths) page. diff --git a/files/en-us/web/api/canvas_api/tutorial/drawing_text/index.md b/files/en-us/web/api/canvas_api/tutorial/drawing_text/index.md index b8243a072428306..e2439581bd7c43e 100644 --- a/files/en-us/web/api/canvas_api/tutorial/drawing_text/index.md +++ b/files/en-us/web/api/canvas_api/tutorial/drawing_text/index.md @@ -80,50 +80,38 @@ The following diagram from the [HTML spec](https://html.spec.whatwg.org/multipag ![The em-over baseline is roughly at the top of the glyphs in a font, the hanging baseline is where some glyphs like आ are anchored, the middle is half-way between the em-over and em-under baselines, the alphabetic baseline is where characters like Á, ÿ, f, and Ω are anchored, the ideographic-under baseline is where glyphs like 私 and 達 are anchored, and the em-under baseline is roughly at the bottom of the glyphs in a font. The top and bottom of the bounding box can be far from these baselines, due to glyphs extending far outside em-over and em-under baselines.](baselines.png) -### A textBaseline example +### A `textBaseline` example -Edit the code below and see your changes update live in the canvas: +This example demonstrates the various `textBaseline` property values. +See the [`CanvasRenderingContext2D.textBaseline`](/en-US/docs/Web/API/CanvasRenderingContext2D/textBaseline) page for more information and detailed examples. -```html hidden -<canvas id="canvas" width="400" height="200" class="playable-canvas"></canvas> -<div class="playable-buttons"> - <input id="edit" type="button" value="Edit" /> - <input id="reset" type="button" value="Reset" /> -</div> -<textarea id="code" class="playable-code"> -ctx.font = "48px serif"; -ctx.textBaseline = "hanging"; -ctx.strokeText("Hello world", 0, 100); -</textarea> +```html hidden live-sample___textBaseline +<canvas id="canvas" width="400" height="100"></canvas> ``` -```js hidden -const canvas = document.getElementById("canvas"); -const ctx = canvas.getContext("2d"); -const textarea = document.getElementById("code"); -const reset = document.getElementById("reset"); -const edit = document.getElementById("edit"); -const code = textarea.value; - -function drawCanvas() { - ctx.clearRect(0, 0, canvas.width, canvas.height); - eval(textarea.value); -} +```js live-sample___textBaseline +function draw() { + const ctx = document.getElementById("canvas").getContext("2d"); + ctx.font = "48px serif"; -reset.addEventListener("click", () => { - textarea.value = code; - drawCanvas(); -}); + ctx.textBaseline = "hanging"; + ctx.strokeText("hanging", 10, 50); -edit.addEventListener("click", () => { - textarea.focus(); -}); + ctx.textBaseline = "middle"; + ctx.strokeText("middle", 250, 50); -textarea.addEventListener("input", drawCanvas); -window.addEventListener("load", drawCanvas); + ctx.beginPath(); + ctx.moveTo(10, 50); + ctx.lineTo(300, 50); + ctx.stroke(); +} +``` + +```js hidden live-sample___textBaseline +draw(); ``` -{{ EmbedLiveSample('A_textBaseline_example', 700, 400) }} +{{EmbedLiveSample('textBaseline', 310, 110)}} ## Advanced text measurements diff --git a/files/en-us/web/api/canvas_api/tutorial/finale/index.md b/files/en-us/web/api/canvas_api/tutorial/finale/index.md index 01a9c059c83a8fc..bc8b29480e33ad6 100644 --- a/files/en-us/web/api/canvas_api/tutorial/finale/index.md +++ b/files/en-us/web/api/canvas_api/tutorial/finale/index.md @@ -14,8 +14,6 @@ There are a variety of demos and further explanations about canvas on these site - [Canvas Codepens](https://codepen.io/search/pens?q=canvas) - : Front End Developer Playground & Code Editor in the Browser. -- [Canvas Tutorials](https://www.html5canvastutorials.com/) - - : Examples for most canvas APIs. - [Game development](/en-US/docs/Games) - : Gaming is one of the most popular computer activities. New technologies are constantly arriving to make it possible to develop better and more powerful games that can be run in any standards-compliant web browser. diff --git a/files/en-us/web/api/canvas_api/tutorial/index.md b/files/en-us/web/api/canvas_api/tutorial/index.md index 07452743f80d1b8..4a6319f2ce6405b 100644 --- a/files/en-us/web/api/canvas_api/tutorial/index.md +++ b/files/en-us/web/api/canvas_api/tutorial/index.md @@ -6,7 +6,7 @@ page-type: guide {{DefaultAPISidebar("Canvas API")}} -This tutorial describes how to use the [**`<canvas>`**](/en-US/docs/Web/HTML/Element/canvas) element to draw 2D graphics, starting with the basics. The examples provided should give you some clear ideas about what you can do with canvas, and will provide code snippets that may get you started in building your own content. +This tutorial describes how to use the [**`<canvas>`**](/en-US/docs/Web/HTML/Reference/Elements/canvas) element to draw 2D graphics, starting with the basics. The examples provided should give you some clear ideas about what you can do with canvas, and will provide code snippets that may get you started in building your own content. `<canvas>` is an [HTML](/en-US/docs/Web/HTML) element which can be used to draw graphics via scripting (usually [JavaScript](/en-US/docs/Glossary/JavaScript)). This can, for instance, be used to draw graphs, combine photos, or create simple animations. diff --git a/files/en-us/web/api/canvas_api/tutorial/optimizing_canvas/index.md b/files/en-us/web/api/canvas_api/tutorial/optimizing_canvas/index.md index e9c0b4857320a88..52159058efe92f5 100644 --- a/files/en-us/web/api/canvas_api/tutorial/optimizing_canvas/index.md +++ b/files/en-us/web/api/canvas_api/tutorial/optimizing_canvas/index.md @@ -89,7 +89,7 @@ const scaleY = window.innerHeight / canvas.height; const scaleToFit = Math.min(scaleX, scaleY); const scaleToCover = Math.max(scaleX, scaleY); -stage.style.transformOrigin = "0 0"; //scale from top left +stage.style.transformOrigin = "0 0"; // Scale from top left stage.style.transform = `scale(${scaleToFit})`; ``` @@ -133,8 +133,4 @@ canvas.style.height = `${rect.height}px`; - With animations, use {{domxref("Window.requestAnimationFrame()")}} instead of {{domxref("Window.setInterval", "setInterval()")}}. - Be careful with heavy physics libraries. -## See also - -- [Optimizing your JavaScript game for Firefox OS – Mozilla Hacks](https://hacks.mozilla.org/2013/05/optimizing-your-javascript-game-for-firefox-os/) - {{PreviousNext("Web/API/Canvas_API/Tutorial/Pixel_manipulation_with_canvas", "Web/API/Canvas_API/Tutorial/Finale")}} diff --git a/files/en-us/web/api/canvas_api/tutorial/pixel_manipulation_with_canvas/index.md b/files/en-us/web/api/canvas_api/tutorial/pixel_manipulation_with_canvas/index.md index ad9d6538cb0898d..004b96fa9a96dcc 100644 --- a/files/en-us/web/api/canvas_api/tutorial/pixel_manipulation_with_canvas/index.md +++ b/files/en-us/web/api/canvas_api/tutorial/pixel_manipulation_with_canvas/index.md @@ -286,14 +286,14 @@ The {{domxref("HTMLCanvasElement")}} provides a `toDataURL()` method, which is u > [!NOTE] > Be aware that if the canvas contains any pixels that were obtained from another {{Glossary("origin")}} without using CORS, the canvas is **tainted** and its contents can no longer be read and saved. -> See [Security and tainted canvases](/en-US/docs/Web/HTML/CORS_enabled_image#security_and_tainted_canvases). +> See [Security and tainted canvases](/en-US/docs/Web/HTML/How_to/CORS_enabled_image#security_and_tainted_canvases). - {{domxref("HTMLCanvasElement.toDataURL", "canvas.toDataURL('image/png')")}} - : Default setting. Creates a PNG image. - {{domxref("HTMLCanvasElement.toDataURL", "canvas.toDataURL('image/jpeg', quality)")}} - : Creates a JPG image. Optionally, you can provide a quality in the range from 0 to 1, with one being the best quality and with 0 almost not recognizable but small in file size. -Once you have generated a data URL from your canvas, you are able to use it as the source of any {{HTMLElement("img")}} or put it into a hyperlink with a [download attribute](/en-US/docs/Web/HTML/Element/a#download) to save it to disc, for example. +Once you have generated a data URL from your canvas, you are able to use it as the source of any {{HTMLElement("img")}} or put it into a hyperlink with a [download attribute](/en-US/docs/Web/HTML/Reference/Elements/a#download) to save it to disc, for example. You can also create a {{domxref("Blob")}} from the canvas. @@ -305,6 +305,5 @@ You can also create a {{domxref("Blob")}} from the canvas. - {{domxref("ImageData")}} - [Manipulating video using canvas](/en-US/docs/Web/API/Canvas_API/Manipulating_video_using_canvas) - [Download Canvas API-Generated Images Using toBlob](https://www.digitalocean.com/community/tutorials/js-canvas-toblob) -- [HTML5 Canvas Tutorials](https://www.html5canvastutorials.com/) {{PreviousNext("Web/API/Canvas_API/Tutorial/Advanced_animations", "Web/API/Canvas_API/Tutorial/Optimizing_canvas")}} diff --git a/files/en-us/web/api/canvas_api/tutorial/transformations/index.md b/files/en-us/web/api/canvas_api/tutorial/transformations/index.md index 4dcfa261162b6d1..56c0dae8ece59e7 100644 --- a/files/en-us/web/api/canvas_api/tutorial/transformations/index.md +++ b/files/en-us/web/api/canvas_api/tutorial/transformations/index.md @@ -19,7 +19,7 @@ Before we look at the transformation methods, let's look at two other methods wh Canvas states are stored on a stack. Every time the `save()` method is called, the current drawing state is pushed onto the stack. A drawing state consists of -- The transformations that have been applied (i.e. `translate`, `rotate` and `scale` – see below). +- The transformations that have been applied (i.e., `translate`, `rotate` and `scale` – see below). - The current values of the following attributes: - {{domxref("CanvasRenderingContext2D.strokeStyle", "strokeStyle")}} - {{domxref("CanvasRenderingContext2D.fillStyle", "fillStyle")}} diff --git a/files/en-us/web/api/canvas_api/tutorial/using_images/index.md b/files/en-us/web/api/canvas_api/tutorial/using_images/index.md index 857552aacc5cba3..619ad2d35c60db0 100644 --- a/files/en-us/web/api/canvas_api/tutorial/using_images/index.md +++ b/files/en-us/web/api/canvas_api/tutorial/using_images/index.md @@ -46,7 +46,7 @@ We can obtain a reference to images on the same page as the canvas by using one ### Using images from other domains -Using the [`crossorigin`](/en-US/docs/Web/HTML/Element/img#crossorigin) attribute of an {{HTMLElement("img")}} element (reflected by the {{domxref("HTMLImageElement.crossOrigin")}} property), you can request permission to load an image from another domain for use in your call to `drawImage()`. If the hosting domain permits cross-domain access to the image, the image can be used in your canvas without tainting it; otherwise using the image will [taint the canvas](/en-US/docs/Web/HTML/CORS_enabled_image#security_and_tainted_canvases). +Using the [`crossorigin`](/en-US/docs/Web/HTML/Reference/Elements/img#crossorigin) attribute of an {{HTMLElement("img")}} element (reflected by the {{domxref("HTMLImageElement.crossOrigin")}} property), you can request permission to load an image from another domain for use in your call to `drawImage()`. If the hosting domain permits cross-domain access to the image, the image can be used in your canvas without tainting it; otherwise using the image will [taint the canvas](/en-US/docs/Web/HTML/How_to/CORS_enabled_image#security_and_tainted_canvases). ### Using other canvas elements diff --git a/files/en-us/web/api/canvaspattern/settransform/index.md b/files/en-us/web/api/canvaspattern/settransform/index.md index f6f143304b453e7..9ca502a911275a7 100644 --- a/files/en-us/web/api/canvaspattern/settransform/index.md +++ b/files/en-us/web/api/canvaspattern/settransform/index.md @@ -29,22 +29,18 @@ None ({{jsxref("undefined")}}). ### Using the `setTransform` method -This is just a simple code snippet which uses the `setTransform` method to +This is a code snippet which uses the `setTransform` method to create a {{domxref("CanvasPattern")}} with the specified pattern transformation from a {{domxref("DOMMatrix")}}. The pattern gets applied if you set it as the current {{domxref("CanvasRenderingContext2D.fillStyle", "fillStyle")}} and gets drawn onto the canvas when using the {{domxref("CanvasRenderingContext2D.fillRect", "fillRect()")}} method, for example. -#### HTML - -```html +```html live-sample___canvas <canvas id="canvas"></canvas> ``` -#### JavaScript - -```js +```js live-sample___canvas const canvas = document.getElementById("canvas"); const ctx = canvas.getContext("2d"); @@ -61,57 +57,7 @@ img.onload = () => { }; ``` -#### Editable demo - -Here's an editable demo of the code snippet above. Try changing the argument to `SetTransform()` to see the effect it had. - -```html hidden -<canvas id="canvas" width="400" height="200" class="playable-canvas"></canvas> -<div class="playable-buttons"> - <input id="edit" type="button" value="Edit" /> - <input id="reset" type="button" value="Reset" /> -</div> -<textarea id="code" class="playable-code" style="height:120px"> -const img = new Image(); -img.src = 'canvas_create_pattern.png'; -img.onload = () => { - const pattern = ctx.createPattern(img, 'repeat'); - pattern.setTransform(matrix.rotate(-45).scale(1.5)); - ctx.fillStyle = pattern; - ctx.fillRect(0, 0, 400, 400); -}; -</textarea> -``` - -```js hidden -const canvas = document.getElementById("canvas"); -const ctx = canvas.getContext("2d"); -const textarea = document.getElementById("code"); -const reset = document.getElementById("reset"); -const edit = document.getElementById("edit"); -const code = textarea.value; - -const matrix = new DOMMatrix([1, 0.2, 0.8, 1, 0, 0]); - -function drawCanvas() { - ctx.clearRect(0, 0, canvas.width, canvas.height); - eval(textarea.value); -} - -reset.addEventListener("click", () => { - textarea.value = code; - drawCanvas(); -}); - -edit.addEventListener("click", () => { - textarea.focus(); -}); - -textarea.addEventListener("input", drawCanvas); -window.addEventListener("load", drawCanvas); -``` - -{{ EmbedLiveSample('Editable_demo', 700, 400) }} +{{EmbedLiveSample('canvas', , 250)}} ## Specifications diff --git a/files/en-us/web/api/canvasrenderingcontext2d/arcto/index.md b/files/en-us/web/api/canvasrenderingcontext2d/arcto/index.md index 385ce58a276467d..d3dc7fa96776f58 100644 --- a/files/en-us/web/api/canvasrenderingcontext2d/arcto/index.md +++ b/files/en-us/web/api/canvasrenderingcontext2d/arcto/index.md @@ -249,747 +249,734 @@ can be used to change an underlined element that is in focus. <em>T<sub>2</sub></em> = <span id="value-T2"></span> </div> <div><em>C</em> = <span id="value-C"></span></div> +``` -<script> - /* arcTo() demo - * Note: there are browser issues at least in Chrome regarding cursor - * updates. See - * https://stackoverflow.com/questions/37462132/update-mouse-cursor-without-moving-mouse-with-changed-css-cursor-property - * - * Cursor problems were also seen when text was selected before entering - * the canvas. Additional tests which may appear to be redundant in the - * code minimized these issues. - */ - - "use strict"; - - /* Parameters for demo */ - const param = { - canvasWidth: 300, // canvas size - canvasHeight: 300, - hitDistance: 5, // mouse distance to be considered a hit - errorTolCenter: 1e-4, // limit on circle center differences - radiusMax: 250, // largest allowed radius - P0x: 50, // initial point - P0y: 50, - P1x: 275, // First control point - P1y: 150, - P2x: 50, // Second control point - P2y: 275, - radius: 75, // radius of arc - }; +```css hidden +label { + margin: 10px; +} +.input { + color: #00f; + text-decoration: underline; +} +#canvas { + border: 1px solid #000; +} +``` - /* Some math for 2-D vectors */ - class Math2D { - /* Create new point */ - static point(x = 0, y = 0) { - return { x: x, y: y }; - } +```js hidden +/* arcTo() demo + * Note: there are browser issues at least in Chrome regarding cursor + * updates. See + * https://stackoverflow.com/questions/37462132/update-mouse-cursor-without-moving-mouse-with-changed-css-cursor-property + * + * Cursor problems were also seen when text was selected before entering + * the canvas. Additional tests which may appear to be redundant in the + * code minimized these issues. + */ + +/* Parameters for demo */ +const param = { + canvasWidth: 300, // canvas size + canvasHeight: 300, + hitDistance: 5, // mouse distance to be considered a hit + errorTolCenter: 1e-4, // limit on circle center differences + radiusMax: 250, // largest allowed radius + P0x: 50, // initial point + P0y: 50, + P1x: 275, // First control point + P1y: 150, + P2x: 50, // Second control point + P2y: 275, + radius: 75, // radius of arc +}; - /* Create new vector */ - static vector(x = 0, y = 0) { - return this.point(x, y); - } +/* Some math for 2-D vectors */ +class Math2D { + /* Create new point */ + static point(x = 0, y = 0) { + return { x, y }; + } - /* Subtraction: difference = minuend - subtrahend */ - static subtract(difference, minuend, subtrahend) { - difference.x = minuend.x - subtrahend.x; - difference.y = minuend.y - subtrahend.y; - } + /* Create new vector */ + static vector(x = 0, y = 0) { + return this.point(x, y); + } - /* Find L2 norm */ - static L2(a) { - return Math.hypot(a.x, a.y); - } + /* Subtraction: difference = minuend - subtrahend */ + static subtract(difference, minuend, subtrahend) { + difference.x = minuend.x - subtrahend.x; + difference.y = minuend.y - subtrahend.y; + } - /* Dot product */ - static dot(a, b) { - return a.x * b.x + a.y * b.y; - } + /* Find L2 norm */ + static L2(a) { + return Math.hypot(a.x, a.y); + } - /* Find point on line defined parametrically by - * L = P0 + t * direction */ - static linePointAt(P0, t, dir) { - return this.point(P0.x + t * dir.x, P0.y + t * dir.y); - } - } /* end of class Math2D */ - - /* Text values allowing alternate inputs */ - class TextInput { - #valueMax; - #callbackKeydown; - #callbackFocus; - - /* Mutation observer to watch the focused text input */ - static mo = new MutationObserver(TextInput.processInput); - static moOptions = { - subtree: true, // character data in internal node - characterData: true, - }; + /* Dot product */ + static dot(a, b) { + return a.x * b.x + a.y * b.y; + } - /* Symbol to add index information to mutation observer */ - static symbolTextInput = Symbol("textInput"); - - /* Handler for mutations of focused text input */ - static processInput(mrs, mo) { - /* Access textInput object associated with the mutations */ - const textInput = mo[TextInput.symbolTextInput]; - - /* Find the character data mutation and update based on the input */ - for (let i = 0, n = mrs.length; i < n; i++) { - const mr = mrs[i]; - if (mr.type === "characterData") { - const target = mr.target; - if (target.nodeType !== 3) { - console.error( - "Mutation record type CharacterData but " + - "node type = " + - target.nodeType, - ); - return; - } - /* Handle non-digits entered by parsing */ - let value = parseInt(target.textContent); - value = isNaN(value) ? 0 : value; - textInput.updateFull(value); - break; + /* Find point on line defined parametrically by + * L = P0 + t * direction */ + static linePointAt(P0, t, dir) { + return this.point(P0.x + t * dir.x, P0.y + t * dir.y); + } +} /* end of class Math2D */ + +/* Text values allowing alternate inputs */ +class TextInput { + #valueMax; + #callbackKeydown; + #callbackFocus; + + /* Mutation observer to watch the focused text input */ + static mo = new MutationObserver(TextInput.processInput); + static moOptions = { + subtree: true, // character data in internal node + characterData: true, + }; + + /* Symbol to add index information to mutation observer */ + static symbolTextInput = Symbol("textInput"); + + /* Handler for mutations of focused text input */ + static processInput(mrs, mo) { + /* Access textInput object associated with the mutations */ + const textInput = mo[TextInput.symbolTextInput]; + + /* Find the character data mutation and update based on the input */ + for (let i = 0, n = mrs.length; i < n; i++) { + const mr = mrs[i]; + if (mr.type === "characterData") { + const target = mr.target; + if (target.nodeType !== 3) { + console.error( + `Mutation record type CharacterData but node type = ${target.nodeType}`, + ); + return; } + /* Handle non-digits entered by parsing */ + let value = parseInt(target.textContent, 10); + value = isNaN(value) ? 0 : value; + textInput.updateFull(value); + break; } } + } - constructor( - idText, // id of element in document - idControl, // id of control in element, if any (radius ony) - valueMax, // allowed values from 0 to maxValue, inclusive - getStateValue, // function to get value from state object - setStateValue, - ) { - // function to set value on state object - this.#valueMax = valueMax; - this.elementText = document.getElementById(idText); - this.elementControl = - idControl === null ? null : document.getElementById(idControl); - this.getStateValue = getStateValue; - this.setStateValue = setStateValue; - this.#callbackKeydown = (evt) => { - let valueInput; - switch (evt.code) { - case "Enter": // Do not allow since adds <br> nodes - evt.preventDefault(); - return; - case "ArrowUp": - valueInput = Number(this.elementText.textContent) + 1; - evt.preventDefault(); - break; - case "ArrowDown": - valueInput = Number(this.elementText.textContent) - 1; - evt.preventDefault(); - break; - default: // ignore all others - return; - } - TextInput.mo.disconnect(); // suspend while changing value - this.updateFull(valueInput); // do update - const options = { subtree: true, characterData: true }; - TextInput.mo.observe(this.elementText, TextInput.moOptions); - // observe again - }; - this.#callbackFocus = (evt) => { - /* Link mutation observer to the associated text input object */ - TextInput.mo[TextInput.symbolTextInput] = this; - - /* Look for changes in the input. - * subtree: true needed since text is in internal node(s) - * childList: true needed since <enter> becomes a <br> node */ - TextInput.mo.observe(this.elementText, TextInput.moOptions); - - /* Check for up and down arrows to increment/decrement values */ - this.elementText.addEventListener("keydown", this.#callbackKeydown); - - /* When focus is lost, stop watching this input */ - this.elementText.addEventListener("blur", () => { - this.elementText.removeEventListener( - "keydown", - this.#callbackKeydown, - ); - TextInput.mo.disconnect(); - }); - }; - - this.elementText.addEventListener("focus", this.#callbackFocus); - } // end of class TextInput - - /* Function to update based on input received from text input source */ - updateFull(value) { - /* Clamp value in range */ - if (value > this.#valueMax) { - value = this.#valueMax; - } else if (value < 0) { - value = 0; + constructor( + idText, // id of element in document + idControl, // id of control in element, if any (radius ony) + valueMax, // allowed values from 0 to maxValue, inclusive + getStateValue, // function to get value from state object + setStateValue, + ) { + // function to set value on state object + this.#valueMax = valueMax; + this.elementText = document.getElementById(idText); + this.elementControl = + idControl === null ? null : document.getElementById(idControl); + this.getStateValue = getStateValue; + this.setStateValue = setStateValue; + this.#callbackKeydown = (evt) => { + let valueInput; + switch (evt.code) { + case "Enter": // Do not allow since adds <br> nodes + evt.preventDefault(); + return; + case "ArrowUp": + valueInput = Number(this.elementText.textContent) + 1; + evt.preventDefault(); + break; + case "ArrowDown": + valueInput = Number(this.elementText.textContent) - 1; + evt.preventDefault(); + break; + default: // ignore all others + return; } + TextInput.mo.disconnect(); // suspend while changing value + this.updateFull(valueInput); // do update + const options = { subtree: true, characterData: true }; + TextInput.mo.observe(this.elementText, TextInput.moOptions); + // observe again + }; + this.#callbackFocus = (evt) => { + /* Link mutation observer to the associated text input object */ + TextInput.mo[TextInput.symbolTextInput] = this; + + /* Look for changes in the input. + * subtree: true needed since text is in internal node(s) + * childList: true needed since <enter> becomes a <br> node */ + TextInput.mo.observe(this.elementText, TextInput.moOptions); + + /* Check for up and down arrows to increment/decrement values */ + this.elementText.addEventListener("keydown", this.#callbackKeydown); + + /* When focus is lost, stop watching this input */ + this.elementText.addEventListener("blur", () => { + this.elementText.removeEventListener("keydown", this.#callbackKeydown); + TextInput.mo.disconnect(); + }); + }; - /* Make consistent and update */ - const valueTextPrev = this.elementText.textContent; - const valueString = String(value); - if (valueTextPrev !== valueString) { - this.elementText.textContent = valueString; - } + this.elementText.addEventListener("focus", this.#callbackFocus); + } // end of class TextInput - if (this.elementControl) { - const valueControlPrev = this.elementControl.value; - if (valueControlPrev !== valueString) { - this.elementControl.value = valueString; - } - } + /* Function to update based on input received from text input source */ + updateFull(value) { + /* Clamp value in range */ + if (value > this.#valueMax) { + value = this.#valueMax; + } else if (value < 0) { + value = 0; + } + + /* Make consistent and update */ + const valueTextPrev = this.elementText.textContent; + const valueString = String(value); + if (valueTextPrev !== valueString) { + this.elementText.textContent = valueString; + } - const valueStatePrev = this.getStateValue(); - if (valueStatePrev !== value) { - // input caused state change - this.setStateValue(value); - updateResults(); + if (this.elementControl) { + const valueControlPrev = this.elementControl.value; + if (valueControlPrev !== valueString) { + this.elementControl.value = valueString; } } - } /* end of class TextInput */ - - /* Given configuration parameters, initialize the state */ - function initDemoState({ - canvasWidth = 300, - canvasHeight = 300, - hitDistance = 5, - errorTolCenter = 1e-4, - radiusMax = 250, - P0x = 0, - P0y = 0, - P1x = 0, - P1y = 0, - P2x = 0, - P2y = 0, - radius = 0, - } = {}) { - const s = {}; - s.controlPoints = [ - Math2D.point(P0x, P0y), - Math2D.point(P1x, P1y), - Math2D.point(P2x, P2y), - ]; - s.hitDistance = hitDistance; - s.errorTolCenter = errorTolCenter; - s.canvasSize = Math2D.point(canvasWidth, canvasHeight); - - if (radius > radiusMax) { - /* limit param to allowed values */ - radius = radiusMax; + + const valueStatePrev = this.getStateValue(); + if (valueStatePrev !== value) { + // input caused state change + this.setStateValue(value); + updateResults(); } - s.radius = radius; - s.radiusMax = radiusMax; - - [s.haveCircle, s.P0Inf, s.P2Inf, s.T1, s.T2, s.C] = findConstruction( - s.controlPoints, - s.radius, - s.canvasSize, - s.errorTolCenter, - ); - s.pointActiveIndex = -1; // no point currently active - s.pointActiveMoving = false; // Active point hovering (false) or - // moving (true) - s.mouseDelta = Math2D.point(); // offset of mouse pointer - //from point center - return s; } +} /* end of class TextInput */ + +/* Given configuration parameters, initialize the state */ +function initDemoState({ + canvasWidth = 300, + canvasHeight = 300, + hitDistance = 5, + errorTolCenter = 1e-4, + radiusMax = 250, + P0x = 0, + P0y = 0, + P1x = 0, + P1y = 0, + P2x = 0, + P2y = 0, + radius = 0, +} = {}) { + const s = {}; + s.controlPoints = [ + Math2D.point(P0x, P0y), + Math2D.point(P1x, P1y), + Math2D.point(P2x, P2y), + ]; + s.hitDistance = hitDistance; + s.errorTolCenter = errorTolCenter; + s.canvasSize = Math2D.point(canvasWidth, canvasHeight); - function updateResults() { - updateConstruction(); - drawCanvas(); - ConstructionPoints.print(state.T1, state.T2, state.C); + if (radius > radiusMax) { + /* limit param to allowed values */ + radius = radiusMax; } + s.radius = radius; + s.radiusMax = radiusMax; + + [s.haveCircle, s.P0Inf, s.P2Inf, s.T1, s.T2, s.C] = findConstruction( + s.controlPoints, + s.radius, + s.canvasSize, + s.errorTolCenter, + ); + s.pointActiveIndex = -1; // No point currently active + s.pointActiveMoving = false; // Active point hovering (false) or + // moving (true) + // offset of mouse pointer + // from point center + s.mouseDelta = Math2D.point(); + return s; +} - function updateConstruction() { - [state.haveCircle, state.P0Inf, state.P2Inf, state.T1, state.T2, state.C] = - findConstruction( - state.controlPoints, - state.radius, - state.canvasSize, - state.errorTolCenter, - ); - } +function updateResults() { + updateConstruction(); + drawCanvas(); + ConstructionPoints.print(state.T1, state.T2, state.C); +} - /* Find the geometry that arcTo() uses to draw the path */ - function findConstruction([P0, P1, P2], r, canvasSize, errorTolCenter) { - /* Find the center of a circle of radius r having a point T with a - * tangent in the direction d and the center on the same side of - * the tangent as dirTan. */ - function findCenter(T, d, r, dirTan) { - /* Find direction of line normal to tangent line - * Taking larger value to avoid division by 0. - * a . n = 0. Set smaller component to 1 */ - const dn = - Math.abs(d.x) < Math.abs(d.y) - ? Math2D.point(1, -d.x / d.y) - : Math2D.point(-d.y / d.x, 1); - - /* The normal may be pointing towards center or away. - * Make towards center if not */ - if (Math2D.dot(dn, dirTan) < 0) { - dn.x = -dn.x; - dn.y = -dn.y; - } +function updateConstruction() { + [state.haveCircle, state.P0Inf, state.P2Inf, state.T1, state.T2, state.C] = + findConstruction( + state.controlPoints, + state.radius, + state.canvasSize, + state.errorTolCenter, + ); +} - /* Move a distance of the radius along line Tx + t * dn - * to get to the center of the circle */ - return Math2D.linePointAt(T, r / Math2D.L2(dn), dn); +/* Find the geometry that arcTo() uses to draw the path */ +function findConstruction([P0, P1, P2], r, canvasSize, errorTolCenter) { + /* Find the center of a circle of radius r having a point T with a + * tangent in the direction d and the center on the same side of + * the tangent as dirTan. */ + function findCenter(T, d, r, dirTan) { + /* Find direction of line normal to tangent line + * Taking larger value to avoid division by 0. + * a . n = 0. Set smaller component to 1 */ + const dn = + Math.abs(d.x) < Math.abs(d.y) + ? Math2D.point(1, -d.x / d.y) + : Math2D.point(-d.y / d.x, 1); + + /* The normal may be pointing towards center or away. + * Make towards center if not */ + if (Math2D.dot(dn, dirTan) < 0) { + dn.x = -dn.x; + dn.y = -dn.y; } - /* Test for coincidence. Note that points will have small integer - * coordinates, so there is no issue with checking for exact - * equality */ - const dir1 = Math2D.vector(P0.x - P1.x, P0.y - P1.y); // dir line 1 - if (dir1.x === 0 && dir1.y === 0) { - // P0 and P1 coincident - return [false]; - } + /* Move a distance of the radius along line Tx + t * dn + * to get to the center of the circle */ + return Math2D.linePointAt(T, r / Math2D.L2(dn), dn); + } - const dir2 = Math2D.vector(P2.x - P1.x, P2.y - P1.y); // dir of line 2 - if (dir2.x === 0 && dir2.y === 0) { - // P2 and P1 coincident - return [false]; - } + /* Test for coincidence. Note that points will have small integer + * coordinates, so there is no issue with checking for exact + * equality */ + const dir1 = Math2D.vector(P0.x - P1.x, P0.y - P1.y); // dir line 1 + if (dir1.x === 0 && dir1.y === 0) { + // P0 and P1 coincident + return [false]; + } - /* Magnitudes of direction vectors defining lines */ - const dir1Mag = Math2D.L2(dir1); - const dir2Mag = Math2D.L2(dir2); - - /* Make direction vectors unit length */ - const dir1_unit = Math2D.vector(dir1.x / dir1Mag, dir1.y / dir1Mag); - const dir2_unit = Math2D.vector(dir2.x / dir2Mag, dir2.y / dir2Mag); - - /* Angle between lines -- cos angle = a.b/(|a||b|) - * Using unit vectors, so |a| = |b| = 1 */ - const dp = Math2D.dot(dir1_unit, dir2_unit); - /* Test for collinearity */ - if (Math.abs(dp) > 0.999999) { - /* Angle 0 or 180 degrees, or nearly so */ - return [false]; - } - const angle = Math.acos(Math2D.dot(dir1_unit, dir2_unit)); - - /* Distance to tangent points from P1 -- - * (T1, P1, C) form a right triangle (T2, P1, C) same triangle. - * An angle of each triangle is half of the angle between the lines - * tan(angle/2) = r / length(P1,T1) */ - const distToTangent = r / Math.tan(0.5 * angle); - - /* Locate tangent points */ - const T1 = Math2D.linePointAt(P1, distToTangent, dir1_unit); - const T2 = Math2D.linePointAt(P1, distToTangent, dir2_unit); - - /* Center is along normal to tangent at tangent point at - * a distance equal to the radius of the circle. - * Locate center two ways. Should be equal */ - const dirT2_T1 = Math2D.vector(T2.x - T1.x, T2.y - T1.y); - const dirT1_T2 = Math2D.vector(-dirT2_T1.x, -dirT2_T1.y); - const C1 = findCenter(T1, dir1_unit, r, dirT2_T1); - const C2 = findCenter(T2, dir2_unit, r, dirT1_T2); - - /* Error in center calculations */ - const deltaC = Math2D.vector(C2.x - C1.x, C2.y - C1.y); - if (deltaC.x * deltaC.x + deltaC.y * deltaC.y > errorTolCenter) { - console.error( - `Programming or numerical error, ` + - `P0(${P0.x},${P0.y}); ` + - `P1(${P1.x},${P1.y}); ` + - `P2(${P2.x},${P2.y}); ` + - `r=${r};`, - ); - } + const dir2 = Math2D.vector(P2.x - P1.x, P2.y - P1.y); // dir of line 2 + if (dir2.x === 0 && dir2.y === 0) { + // P2 and P1 coincident + return [false]; + } - /* Average the center values */ - const C = Math2D.point(C1.x + 0.5 * deltaC.x, C1.y + 0.5 * deltaC.y); - - /* Find the "infinite values" of the two semi-infinite lines. - * As a practical consideration, anything off the canvas is - * infinite. A distance equal to the height + width of the canvas - * is assured to be sufficiently far away and has the advantage of - * being easily found. */ - const distToInf = canvasSize.x + canvasSize.y; - const L1inf = Math2D.linePointAt(P1, distToInf, dir1_unit); - const L2inf = Math2D.linePointAt(P1, distToInf, dir2_unit); - - return [true, L1inf, L2inf, T1, T2, C]; - } /* end of function findConstruction */ - - /* Finds index and distance delta of first point in an array that is - * closest to the specified point or returns index of -1 if none */ - function hitTestPoints(pointAt, points, hitDistance) { - const n = points.length; - const delta = Math2D.vector(); - for (let i = 0; i < n; i++) { - Math2D.subtract(delta, pointAt, points[i]); - if (Math2D.L2(delta) <= hitDistance) { - return [i, delta]; - } - } - return [-1]; // no hit + /* Magnitudes of direction vectors defining lines */ + const dir1Mag = Math2D.L2(dir1); + const dir2Mag = Math2D.L2(dir2); + + /* Make direction vectors unit length */ + const dir1_unit = Math2D.vector(dir1.x / dir1Mag, dir1.y / dir1Mag); + const dir2_unit = Math2D.vector(dir2.x / dir2Mag, dir2.y / dir2Mag); + + /* Angle between lines -- cos angle = a.b/(|a||b|) + * Using unit vectors, so |a| = |b| = 1 */ + const dp = Math2D.dot(dir1_unit, dir2_unit); + /* Test for collinearity */ + if (Math.abs(dp) > 0.999999) { + /* Angle 0 or 180 degrees, or nearly so */ + return [false]; + } + const angle = Math.acos(Math2D.dot(dir1_unit, dir2_unit)); + + /* Distance to tangent points from P1 -- + * (T1, P1, C) form a right triangle (T2, P1, C) same triangle. + * An angle of each triangle is half of the angle between the lines + * tan(angle/2) = r / length(P1,T1) */ + const distToTangent = r / Math.tan(0.5 * angle); + + /* Locate tangent points */ + const T1 = Math2D.linePointAt(P1, distToTangent, dir1_unit); + const T2 = Math2D.linePointAt(P1, distToTangent, dir2_unit); + + /* Center is along normal to tangent at tangent point at + * a distance equal to the radius of the circle. + * Locate center two ways. Should be equal */ + const dirT2_T1 = Math2D.vector(T2.x - T1.x, T2.y - T1.y); + const dirT1_T2 = Math2D.vector(-dirT2_T1.x, -dirT2_T1.y); + const C1 = findCenter(T1, dir1_unit, r, dirT2_T1); + const C2 = findCenter(T2, dir2_unit, r, dirT1_T2); + + /* Error in center calculations */ + const deltaC = Math2D.vector(C2.x - C1.x, C2.y - C1.y); + if (deltaC.x * deltaC.x + deltaC.y * deltaC.y > errorTolCenter) { + console.error( + `Programming or numerical error, ` + + `P0(${P0.x},${P0.y}); ` + + `P1(${P1.x},${P1.y}); ` + + `P2(${P2.x},${P2.y}); ` + + `r=${r};`, + ); } - /* Handle a mouse move for either a mousemove event or mouseenter */ - function doMouseMove(pointCursor, rBtnDown) { - /* Test for active move. If so, move accordingly based on the - * cursor position. The right button down flag handles the case - * where the cursor leaves the canvas with the right button down - * and enters with it up (not moving) or down (moving). It - * also helps to handle unreliable delivery of mouse events. */ - if (state.pointActiveIndex >= 0 && state.pointActiveMoving && rBtnDown) { - /* A point was moving and is moving more */ - moveActivePointAndUpdate(pointCursor); - return; + /* Average the center values */ + const C = Math2D.point(C1.x + 0.5 * deltaC.x, C1.y + 0.5 * deltaC.y); + + /* Find the "infinite values" of the two semi-infinite lines. + * As a practical consideration, anything off the canvas is + * infinite. A distance equal to the height + width of the canvas + * is assured to be sufficiently far away and has the advantage of + * being easily found. */ + const distToInf = canvasSize.x + canvasSize.y; + const L1inf = Math2D.linePointAt(P1, distToInf, dir1_unit); + const L2inf = Math2D.linePointAt(P1, distToInf, dir2_unit); + + return [true, L1inf, L2inf, T1, T2, C]; +} /* end of function findConstruction */ + +/* Finds index and distance delta of first point in an array that is + * closest to the specified point or returns index of -1 if none */ +function hitTestPoints(pointAt, points, hitDistance) { + const n = points.length; + const delta = Math2D.vector(); + for (let i = 0; i < n; i++) { + Math2D.subtract(delta, pointAt, points[i]); + if (Math2D.L2(delta) <= hitDistance) { + return [i, delta]; } + } + return [-1]; // no hit +} - /* If there is not an active move with the right button down, - * update active state based on hit testing. Mouse events have - * been found to not be reliably delivered sometimes, particularly - * with Chrome, so the programming must handle this issue */ - state.pointActiveMoving = false; // not moving - - const [pointHitIndex, testDelta] = hitTestPoints( - pointCursor, - state.controlPoints, - state.hitDistance, - ); - state.pointActiveIndex = pointHitIndex; - canvas.style.cursor = pointHitIndex < 0 ? "auto" : "pointer"; +/* Handle a mouse move for either a mousemove event or mouseenter */ +function doMouseMove(pointCursor, rBtnDown) { + /* Test for active move. If so, move accordingly based on the + * cursor position. The right button down flag handles the case + * where the cursor leaves the canvas with the right button down + * and enters with it up (not moving) or down (moving). It + * also helps to handle unreliable delivery of mouse events. */ + if (state.pointActiveIndex >= 0 && state.pointActiveMoving && rBtnDown) { + /* A point was moving and is moving more */ + moveActivePointAndUpdate(pointCursor); return; - } /* end of function doMouseMove */ - - class ConstructionPoints { - static #vT1 = document.getElementById("value-T1"); - static #vT2 = document.getElementById("value-T2"); - static #vC = document.getElementById("value-C"); - static print(T1, T2, C) { - function prettyPoint(P) { - return `(${P.x}, ${P.y})`; - } - if (state.haveCircle) { - this.#vT1.textContent = prettyPoint(T1); - this.#vT2.textContent = prettyPoint(T2); - this.#vC.textContent = prettyPoint(C); - } else { - this.#vT1.textContent = "undefined"; - this.#vT2.textContent = "undefined"; - this.#vC.textContent = "undefined"; - } - } } - /* Move the active point, which must exist when called, to - * its new point based on the cursor location and the offset of - * the cursor to the center of the point */ - function moveActivePointAndUpdate(pointCursor) { - let pointAdjusted = Math2D.point(); - Math2D.subtract(pointAdjusted, pointCursor, state.mouseDelta); - - /* Adjust location to keep point on canvas */ - if (pointAdjusted.x < 0) { - pointAdjusted.x = 0; - } else if (pointAdjusted.x >= state.canvasSize.x) { - pointAdjusted.x = state.canvasSize.x; - } - if (pointAdjusted.y < 0) { - pointAdjusted.y = 0; - } else if (pointAdjusted.y >= state.canvasSize.y) { - pointAdjusted.y = state.canvasSize.y; - } + /* If there is not an active move with the right button down, + * update active state based on hit testing. Mouse events have + * been found to not be reliably delivered sometimes, particularly + * with Chrome, so the programming must handle this issue */ + state.pointActiveMoving = false; // not moving + + const [pointHitIndex, testDelta] = hitTestPoints( + pointCursor, + state.controlPoints, + state.hitDistance, + ); + state.pointActiveIndex = pointHitIndex; + canvas.style.cursor = pointHitIndex < 0 ? "auto" : "pointer"; +} - /* Set point */ - const index = state.pointActiveIndex; - const pt = state.controlPoints[index]; - let isPointChanged = false; - let indexTextInput = 1 + 2 * index; - if (pt.x !== pointAdjusted.x) { - isPointChanged = true; - pt.x = pointAdjusted.x; - textInputs[indexTextInput].elementText.textContent = pointAdjusted.x; +class ConstructionPoints { + static #vT1 = document.getElementById("value-T1"); + static #vT2 = document.getElementById("value-T2"); + static #vC = document.getElementById("value-C"); + static print(T1, T2, C) { + function prettyPoint(P) { + return `(${P.x}, ${P.y})`; } - if (pt.y !== pointAdjusted.y) { - isPointChanged = true; - pt.y = pointAdjusted.y; - textInputs[indexTextInput + 1].elementText.textContent = pointAdjusted.y; + if (state.haveCircle) { + this.#vT1.textContent = prettyPoint(T1); + this.#vT2.textContent = prettyPoint(T2); + this.#vC.textContent = prettyPoint(C); + } else { + this.#vT1.textContent = "undefined"; + this.#vT2.textContent = "undefined"; + this.#vC.textContent = "undefined"; } + } +} - if (isPointChanged) { - // Update results if x or y changed - updateResults(); - } +/* Move the active point, which must exist when called, to + * its new point based on the cursor location and the offset of + * the cursor to the center of the point */ +function moveActivePointAndUpdate(pointCursor) { + let pointAdjusted = Math2D.point(); + Math2D.subtract(pointAdjusted, pointCursor, state.mouseDelta); + + /* Adjust location to keep point on canvas */ + if (pointAdjusted.x < 0) { + pointAdjusted.x = 0; + } else if (pointAdjusted.x >= state.canvasSize.x) { + pointAdjusted.x = state.canvasSize.x; + } + if (pointAdjusted.y < 0) { + pointAdjusted.y = 0; + } else if (pointAdjusted.y >= state.canvasSize.y) { + pointAdjusted.y = state.canvasSize.y; } - function drawCanvas() { - const rPoint = 4; - const colorConstruction = "#080"; - const colorDraggable = "#00F"; - const [P0, P1, P2] = state.controlPoints; + /* Set point */ + const index = state.pointActiveIndex; + const pt = state.controlPoints[index]; + let isPointChanged = false; + let indexTextInput = 1 + 2 * index; + if (pt.x !== pointAdjusted.x) { + isPointChanged = true; + pt.x = pointAdjusted.x; + textInputs[indexTextInput].elementText.textContent = pointAdjusted.x; + } + if (pt.y !== pointAdjusted.y) { + isPointChanged = true; + pt.y = pointAdjusted.y; + textInputs[indexTextInput + 1].elementText.textContent = pointAdjusted.y; + } - ctx.font = "italic 14pt sans-serif"; - ctx.clearRect(0, 0, canvas.width, canvas.height); - ctx.lineWidth = 1; + if (isPointChanged) { + // Update results if x or y changed + updateResults(); + } +} - /* Draw construction information if present */ - if (state.haveCircle) { - ctx.strokeStyle = colorConstruction; - ctx.fillStyle = colorConstruction; - ctx.setLineDash([4, 6]); - - /* Draw the construction points */ - const specialPoints = [state.C, state.T1, state.T2]; - specialPoints.forEach((value) => { - ctx.beginPath(); - ctx.arc(value.x, value.y, rPoint, 0, 2 * Math.PI); - ctx.fill(); - }); +function drawCanvas() { + const rPoint = 4; + const colorConstruction = "#080"; + const colorDraggable = "#00F"; + const [P0, P1, P2] = state.controlPoints; - /* Draw the semi-infinite lines, a radius, and the circle */ - ctx.beginPath(); - ctx.moveTo(state.P0Inf.x, state.P0Inf.y); - ctx.lineTo(P1.x, P1.y); - ctx.lineTo(state.P2Inf.x, state.P2Inf.y); - ctx.stroke(); - ctx.beginPath(); - ctx.moveTo(state.C.x, state.C.y); - ctx.lineTo(state.T1.x, state.T1.y); - ctx.stroke(); - ctx.beginPath(); - ctx.arc(state.C.x, state.C.y, state.radius, 0, 2 * Math.PI); - ctx.stroke(); - - ctx.fillStyle = "#000"; - ctx.fillText("C", state.C.x, state.C.y - 15); - ctx.fillText("T\u2081", state.T1.x, state.T1.y - 15); - ctx.fillText("T\u2082", state.T2.x, state.T2.y - 15); - ctx.fillText( - " r", - 0.5 * (state.T1.x + state.C.x), - 0.5 * (state.T1.y + state.C.y), - ); - } else { - // no circle - ctx.beginPath(); - ctx.moveTo(P0.x, P0.y); - ctx.setLineDash([2, 6]); - ctx.lineTo(P1.x, P1.y); - ctx.lineTo(P2.x, P2.y); - ctx.strokeStyle = colorConstruction; - ctx.stroke(); - } + ctx.font = "italic 14pt sans-serif"; + ctx.clearRect(0, 0, canvas.width, canvas.height); + ctx.lineWidth = 1; - /* Draw initial point and control points */ - state.controlPoints.forEach((value) => { + /* Draw construction information if present */ + if (state.haveCircle) { + ctx.strokeStyle = colorConstruction; + ctx.fillStyle = colorConstruction; + ctx.setLineDash([4, 6]); + + /* Draw the construction points */ + const specialPoints = [state.C, state.T1, state.T2]; + specialPoints.forEach((value) => { ctx.beginPath(); ctx.arc(value.x, value.y, rPoint, 0, 2 * Math.PI); - ctx.fillStyle = colorDraggable; ctx.fill(); }); - ctx.fillStyle = "#000"; - ctx.fillText("P\u2080", P0.x, P0.y - 15); - ctx.fillText("P\u2081", P1.x, P1.y - 15); - ctx.fillText("P\u2082", P2.x, P2.y - 15); - /* Draw the arcTo() result */ - ctx.lineWidth = 3; + /* Draw the semi-infinite lines, a radius, and the circle */ ctx.beginPath(); - ctx.moveTo(P0.x, P0.y); - ctx.setLineDash([]); - ctx.arcTo(P1.x, P1.y, P2.x, P2.y, state.radius); - ctx.strokeStyle = "#000"; + ctx.moveTo(state.P0Inf.x, state.P0Inf.y); + ctx.lineTo(P1.x, P1.y); + ctx.lineTo(state.P2Inf.x, state.P2Inf.y); + ctx.stroke(); + ctx.beginPath(); + ctx.moveTo(state.C.x, state.C.y); + ctx.lineTo(state.T1.x, state.T1.y); + ctx.stroke(); + ctx.beginPath(); + ctx.arc(state.C.x, state.C.y, state.radius, 0, 2 * Math.PI); ctx.stroke(); - } /* end of function drawCanvas */ - - function addPointArrowMoves() { - [0, 1, 2].forEach((value) => addPointArrowMove(value)); - } - - /* Allow arrow key presses on the point labels to move the point in - * x and y directions */ - function addPointArrowMove(indexPoint) { - const elem = document.getElementById("value-P" + indexPoint); - let indexTextInput = 2 * indexPoint + 1; - elem.addEventListener("keydown", (evt) => { - let valueNew; - let indexActive = indexTextInput; - switch (evt.code) { - case "ArrowLeft": // left arrow -- dec x by 1 - valueNew = textInputs[indexActive].getStateValue() - 1; - evt.preventDefault(); - break; - case "ArrowUp": // up arrow -- dec y by 1 - valueNew = textInputs[++indexActive].getStateValue() - 1; - evt.preventDefault(); - break; - case "ArrowRight": // right arrow -- inc x by 1 - valueNew = textInputs[indexActive].getStateValue() + 1; - evt.preventDefault(); - break; - case "ArrowDown": // down arrow -- inc y by 1 - valueNew = textInputs[++indexActive].getStateValue() + 1; - evt.preventDefault(); - break; - default: // ignore all others - return; - } - textInputs[indexActive].updateFull(valueNew); // do update - }); + ctx.fillStyle = "#000"; + ctx.fillText("C", state.C.x, state.C.y - 15); + ctx.fillText("T\u2081", state.T1.x, state.T1.y - 15); + ctx.fillText("T\u2082", state.T2.x, state.T2.y - 15); + ctx.fillText( + " r", + 0.5 * (state.T1.x + state.C.x), + 0.5 * (state.T1.y + state.C.y), + ); + } else { + // no circle + ctx.beginPath(); + ctx.moveTo(P0.x, P0.y); + ctx.setLineDash([2, 6]); + ctx.lineTo(P1.x, P1.y); + ctx.lineTo(P2.x, P2.y); + ctx.strokeStyle = colorConstruction; + ctx.stroke(); } - /* Set initial state based on parameters */ - const state = initDemoState(param); - - /* Radius slider update */ - const controlR = document.getElementById("radius-slider"); - controlR.value = state.radius; // match initial value with state - controlR.max = state.radiusMax; - controlR.addEventListener("input", (evt) => { - textInputs[0].elementText.textContent = controlR.value; - state.radius = controlR.value; - updateResults(); + /* Draw initial point and control points */ + state.controlPoints.forEach((value) => { + ctx.beginPath(); + ctx.arc(value.x, value.y, rPoint, 0, 2 * Math.PI); + ctx.fillStyle = colorDraggable; + ctx.fill(); }); + ctx.fillStyle = "#000"; + ctx.fillText("P\u2080", P0.x, P0.y - 15); + ctx.fillText("P\u2081", P1.x, P1.y - 15); + ctx.fillText("P\u2082", P2.x, P2.y - 15); - /* Create text inputs to set point locations and arc radius */ - const textInputs = [ - new TextInput( - "value-r", - "radius-slider", - state.radiusMax, - () => state.radius, - (value) => (state.radius = value), - ), - new TextInput( - "value-P0x", - null, - state.canvasSize.x, - () => state.controlPoints[0].x, - (value) => (state.controlPoints[0].x = value), - ), - new TextInput( - "value-P0y", - null, - state.canvasSize.y, - () => state.controlPoints[0].y, - (value) => (state.controlPoints[0].y = value), - ), - new TextInput( - "value-P1x", - null, - state.canvasSize.x, - () => state.controlPoints[1].x, - (value) => (state.controlPoints[1].x = value), - ), - new TextInput( - "value-P1y", - null, - state.canvasSize.y, - () => state.controlPoints[1].y, - (value) => (state.controlPoints[1].y = value), - ), - new TextInput( - "value-P2x", - null, - state.canvasSize.x, - () => state.controlPoints[2].x, - (value) => (state.controlPoints[2].x = value), - ), - new TextInput( - "value-P2y", - null, - state.canvasSize.y, - () => state.controlPoints[2].y, - (value) => (state.controlPoints[2].y = value), - ), - ]; - - /* Allow arrow keystrokes to alter point location */ - addPointArrowMoves(); - - /* Initialize the text inputs from the associated state values */ - textInputs.forEach((ti) => (ti.elementText.textContent = ti.getStateValue())); - - /* Canvas setup */ - const canvas = document.getElementById("canvas"); - const ctx = canvas.getContext("2d"); - canvas.width = state.canvasSize.x; - canvas.height = state.canvasSize.y; - - /* Mouse may move a moving point, move over and hover an unhovered - * point, move across a hovered point, or move on other parts of - * the canvas */ - canvas.addEventListener("mousemove", (evt) => - doMouseMove( - Math2D.point(evt.offsetX, evt.offsetY), - (evt.buttons & 1) === 1, - ), - ); + /* Draw the arcTo() result */ + ctx.lineWidth = 3; + ctx.beginPath(); + ctx.moveTo(P0.x, P0.y); + ctx.setLineDash([]); + ctx.arcTo(P1.x, P1.y, P2.x, P2.y, state.radius); + ctx.strokeStyle = "#000"; + ctx.stroke(); +} /* end of function drawCanvas */ - /* Left mouse press on hovered point transitions to a moving point */ - canvas.addEventListener("mousedown", (evt) => { - if (evt.button !== 0) { - // ignore all but left clicks - return; - } +function addPointArrowMoves() { + [0, 1, 2].forEach((value) => addPointArrowMove(value)); +} - const [pointHitIndex, testDelta] = hitTestPoints( - Math2D.point(evt.offsetX, evt.offsetY), - state.controlPoints, - state.hitDistance, - ); - if (pointHitIndex < 0) { - // cursor over no point - return; // nothing to do +/* Allow arrow key presses on the point labels to move the point in + * x and y directions */ +function addPointArrowMove(indexPoint) { + const elem = document.getElementById(`value-P${indexPoint}`); + let indexTextInput = 2 * indexPoint + 1; + elem.addEventListener("keydown", (evt) => { + let valueNew; + let indexActive = indexTextInput; + switch (evt.code) { + case "ArrowLeft": // left arrow -- dec x by 1 + valueNew = textInputs[indexActive].getStateValue() - 1; + evt.preventDefault(); + break; + case "ArrowUp": // up arrow -- dec y by 1 + valueNew = textInputs[++indexActive].getStateValue() - 1; + evt.preventDefault(); + break; + case "ArrowRight": // right arrow -- inc x by 1 + valueNew = textInputs[indexActive].getStateValue() + 1; + evt.preventDefault(); + break; + case "ArrowDown": // down arrow -- inc y by 1 + valueNew = textInputs[++indexActive].getStateValue() + 1; + evt.preventDefault(); + break; + default: // ignore all others + return; } - /* Cursor over (hovered) point */ - state.pointActiveMoving = true; // point now moving - canvas.style.cursor = "move"; // Set to moving cursor - state.mouseDelta = testDelta; // dist of cursor from point center + textInputs[indexActive].updateFull(valueNew); // do update }); +} - /* Left mouse release if moving point transitions to a hovering point */ - canvas.addEventListener("mouseup", (evt) => { - if (evt.button !== 0) { - // ignore all but left clicks - return; - } - - /* If there was a moving point, it transitions to a hovering - * point */ - if (state.pointActiveMoving) { - state.pointActiveMoving = false; // point now hovering - canvas.style.cursor = "pointer"; - } - }); +/* Set initial state based on parameters */ +const state = initDemoState(param); + +/* Radius slider update */ +const controlR = document.getElementById("radius-slider"); +controlR.value = state.radius; // match initial value with state +controlR.max = state.radiusMax; +controlR.addEventListener("input", (evt) => { + textInputs[0].elementText.textContent = controlR.value; + state.radius = controlR.value; + updateResults(); +}); + +/* Create text inputs to set point locations and arc radius */ +const textInputs = [ + new TextInput( + "value-r", + "radius-slider", + state.radiusMax, + () => state.radius, + (value) => (state.radius = value), + ), + new TextInput( + "value-P0x", + null, + state.canvasSize.x, + () => state.controlPoints[0].x, + (value) => (state.controlPoints[0].x = value), + ), + new TextInput( + "value-P0y", + null, + state.canvasSize.y, + () => state.controlPoints[0].y, + (value) => (state.controlPoints[0].y = value), + ), + new TextInput( + "value-P1x", + null, + state.canvasSize.x, + () => state.controlPoints[1].x, + (value) => (state.controlPoints[1].x = value), + ), + new TextInput( + "value-P1y", + null, + state.canvasSize.y, + () => state.controlPoints[1].y, + (value) => (state.controlPoints[1].y = value), + ), + new TextInput( + "value-P2x", + null, + state.canvasSize.x, + () => state.controlPoints[2].x, + (value) => (state.controlPoints[2].x = value), + ), + new TextInput( + "value-P2y", + null, + state.canvasSize.y, + () => state.controlPoints[2].y, + (value) => (state.controlPoints[2].y = value), + ), +]; + +/* Allow arrow keystrokes to alter point location */ +addPointArrowMoves(); + +/* Initialize the text inputs from the associated state values */ +textInputs.forEach((ti) => (ti.elementText.textContent = ti.getStateValue())); + +/* Canvas setup */ +const canvas = document.getElementById("canvas"); +const ctx = canvas.getContext("2d"); +canvas.width = state.canvasSize.x; +canvas.height = state.canvasSize.y; + +/* Mouse may move a moving point, move over and hover an unhovered + * point, move across a hovered point, or move on other parts of + * the canvas */ +canvas.addEventListener("mousemove", (evt) => + doMouseMove(Math2D.point(evt.offsetX, evt.offsetY), (evt.buttons & 1) === 1), +); + +/* Left mouse press on hovered point transitions to a moving point */ +canvas.addEventListener("mousedown", (evt) => { + if (evt.button !== 0) { + // ignore all but left clicks + return; + } - /* Handle case that mouse reenters canvas with point moving. - * If left button down on entry, continue move; otherwise stop - * move. May also need to adjust hovering state */ - canvas.addEventListener("mouseenter", (evt) => - doMouseMove( - Math2D.point(evt.offsetX, evt.offsetY), - (evt.buttons & 1) === 1, - ), + const [pointHitIndex, testDelta] = hitTestPoints( + Math2D.point(evt.offsetX, evt.offsetY), + state.controlPoints, + state.hitDistance, ); + if (pointHitIndex < 0) { + // cursor over no point + return; // nothing to do + } - drawCanvas(); // Draw initial canvas - ConstructionPoints.print(state.T1, state.T2, state.C); // output pts -</script> -``` + /* Cursor over (hovered) point */ + state.pointActiveMoving = true; // point now moving + canvas.style.cursor = "move"; // Set to moving cursor + state.mouseDelta = testDelta; // dist of cursor from point center +}); -```css hidden -label { - margin: 10px; -} -.input { - color: #00f; - text-decoration: underline; -} -#canvas { - border: 1px solid #000; -} +/* Left mouse release if moving point transitions to a hovering point */ +canvas.addEventListener("mouseup", (evt) => { + if (evt.button !== 0) { + // ignore all but left clicks + return; + } + + /* If there was a moving point, it transitions to a hovering + * point */ + if (state.pointActiveMoving) { + state.pointActiveMoving = false; // point now hovering + canvas.style.cursor = "pointer"; + } +}); + +/* Handle case that mouse reenters canvas with point moving. + * If left button down on entry, continue move; otherwise stop + * move. May also need to adjust hovering state */ +canvas.addEventListener("mouseenter", (evt) => + doMouseMove(Math2D.point(evt.offsetX, evt.offsetY), (evt.buttons & 1) === 1), +); + +drawCanvas(); // Draw initial canvas +ConstructionPoints.print(state.T1, state.T2, state.C); // output pts ``` {{ EmbedLiveSample("constructing_an_arcto_path", 350, 450) }} diff --git a/files/en-us/web/api/canvasrenderingcontext2d/getimagedata/index.md b/files/en-us/web/api/canvasrenderingcontext2d/getimagedata/index.md index 713b93f327d7487..a5059f9fbf4601b 100644 --- a/files/en-us/web/api/canvasrenderingcontext2d/getimagedata/index.md +++ b/files/en-us/web/api/canvasrenderingcontext2d/getimagedata/index.md @@ -65,7 +65,7 @@ canvas specified. The coordinates of the rectangle's top-left corner are than the one from which the document itself was loaded. To avoid a `SecurityError` {{domxref("DOMException")}} being thrown in this situation, configure CORS to allow the source image to be used in this way. - See [Allowing cross-origin use of images and canvas](/en-US/docs/Web/HTML/CORS_enabled_image). + See [Allowing cross-origin use of images and canvas](/en-US/docs/Web/HTML/How_to/CORS_enabled_image). ## Examples diff --git a/files/en-us/web/api/canvasrenderingcontext2d/globalcompositeoperation/index.md b/files/en-us/web/api/canvasrenderingcontext2d/globalcompositeoperation/index.md index 4fcbbad0fad4dcf..b2eb723d218eb4e 100644 --- a/files/en-us/web/api/canvasrenderingcontext2d/globalcompositeoperation/index.md +++ b/files/en-us/web/api/canvasrenderingcontext2d/globalcompositeoperation/index.md @@ -193,7 +193,6 @@ window.onload = () => { lightMix(); colorSphere(); runComposite(); - return; }; ``` @@ -387,7 +386,7 @@ Color.HSV_RGB = (o) => { case 5: R = V; G = A; - B = B; + // B remains unchanged break; } } diff --git a/files/en-us/web/api/canvasrenderingcontext2d/imagesmoothingenabled/index.md b/files/en-us/web/api/canvasrenderingcontext2d/imagesmoothingenabled/index.md index 8d9aecc0be83bdb..20b78bfcc2630d9 100644 --- a/files/en-us/web/api/canvasrenderingcontext2d/imagesmoothingenabled/index.md +++ b/files/en-us/web/api/canvasrenderingcontext2d/imagesmoothingenabled/index.md @@ -50,8 +50,7 @@ ctx.font = "16px sans-serif"; ctx.textAlign = "center"; const img = new Image(); -img.src = - "https://interactive-examples.mdn.mozilla.net/media/examples/star.png"; +img.src = "/shared-assets/images/examples/big-star.png"; img.onload = () => { const w = img.width, h = img.height; diff --git a/files/en-us/web/api/canvasrenderingcontext2d/putimagedata/index.md b/files/en-us/web/api/canvasrenderingcontext2d/putimagedata/index.md index dde43d3c33c1a50..f0334763bd5d9ff 100644 --- a/files/en-us/web/api/canvasrenderingcontext2d/putimagedata/index.md +++ b/files/en-us/web/api/canvasrenderingcontext2d/putimagedata/index.md @@ -83,18 +83,14 @@ function putImageData( imageData, dx, dy, - dirtyX, - dirtyY, - dirtyWidth, - dirtyHeight, + dirtyX = 0, + dirtyY = 0, + dirtyWidth = imageData.width, + dirtyHeight = imageData.height, ) { const data = imageData.data; const height = imageData.height; const width = imageData.width; - dirtyX = dirtyX || 0; - dirtyY = dirtyY || 0; - dirtyWidth = dirtyWidth !== undefined ? dirtyWidth : width; - dirtyHeight = dirtyHeight !== undefined ? dirtyHeight : height; const limitBottom = dirtyY + dirtyHeight; const limitRight = dirtyX + dirtyWidth; for (let y = dirtyY; y < limitBottom; y++) { diff --git a/files/en-us/web/api/canvasrenderingcontext2d/settransform/index.md b/files/en-us/web/api/canvasrenderingcontext2d/settransform/index.md index ae2b5350603b716..e7802afb7416113 100644 --- a/files/en-us/web/api/canvasrenderingcontext2d/settransform/index.md +++ b/files/en-us/web/api/canvasrenderingcontext2d/settransform/index.md @@ -42,7 +42,7 @@ This transformation matrix gets multiplied on the left of a column vector repres - `f` (`m42`) - : The cell in the second row and third column of the matrix. -Alternatively, you can pass a single parameter which is an object containing the values above as properties. The parameter names are the property keys, and if two synonymous names are both present (e.g. `m11` and `a`), they must be the same number value, or a {{jsxref("TypeError")}} will be thrown. Using the object form allows omitting some parameters — `a` and `d` default to `1`, while the rest default to `0`. +Alternatively, you can pass a single parameter which is an object containing the values above as properties. The parameter names are the property keys, and if two synonymous names are both present (e.g., `m11` and `a`), they must be the same number value, or a {{jsxref("TypeError")}} will be thrown. Using the object form allows omitting some parameters — `a` and `d` default to `1`, while the rest default to `0`. If a point originally had coordinates <math><semantics><mrow><mo>(</mo><mi>x</mi><mo>,</mo><mi>y</mi><mo>)</mo></mrow><annotation encoding="TeX">(x, y)</annotation></semantics></math>, then after the transformation it will have coordinates <math><semantics><mrow><mo>(</mo><mi>a</mi><mi>x</mi><mo>+</mo><mi>c</mi><mi>y</mi><mo>+</mo><mi>e</mi><mo>,</mo><mi>b</mi><mi>x</mi><mo>+</mo><mi>d</mi><mi>y</mi><mo>+</mo><mi>f</mi><mo>)</mo></mrow><annotation encoding="TeX">(ax + cy + e, bx + dy + f)</annotation></semantics></math>. This means: @@ -84,7 +84,7 @@ ctx.fillRect(0, 0, 100, 100); In the following example, we have two {{htmlelement("canvas")}} elements. We apply a transform to the first one's context using the first type of `setTransform()` and draw a square on it, then retrieve the matrix from it using {{domxref("CanvasRenderingContext2D.getTransform()")}}. -We then apply the retrieved matrix directly to the second canvas context by passing the `DOMMatrix` object directly to `setTransform()` (i.e. the second type), and draw a circle on it. +We then apply the retrieved matrix directly to the second canvas context by passing the `DOMMatrix` object directly to `setTransform()` (i.e., the second type), and draw a circle on it. #### HTML diff --git a/files/en-us/web/api/canvasrenderingcontext2d/textrendering/index.md b/files/en-us/web/api/canvasrenderingcontext2d/textrendering/index.md index d5382b6cc3f1e31..1c81707d1a4dab5 100644 --- a/files/en-us/web/api/canvasrenderingcontext2d/textrendering/index.md +++ b/files/en-us/web/api/canvasrenderingcontext2d/textrendering/index.md @@ -10,7 +10,7 @@ browser-compat: api.CanvasRenderingContext2D.textRendering The **`CanvasRenderingContext2D.textRendering`** property of the [Canvas API](/en-US/docs/Web/API/Canvas_API) provides information to the rendering engine about what to optimize for when rendering text. -The values correspond to the SVG [`text-rendering`](/en-US/docs/Web/SVG/Attribute/text-rendering) attribute (and CSS [`text-rendering`](/en-US/docs/Web/CSS/text-rendering) property). +The values correspond to the SVG [`text-rendering`](/en-US/docs/Web/SVG/Reference/Attribute/text-rendering) attribute (and CSS [`text-rendering`](/en-US/docs/Web/CSS/text-rendering) property). ## Value diff --git a/files/en-us/web/api/capturecontroller/capturecontroller/index.md b/files/en-us/web/api/capturecontroller/capturecontroller/index.md index cd3a411146b8ac4..edce3df687bee44 100644 --- a/files/en-us/web/api/capturecontroller/capturecontroller/index.md +++ b/files/en-us/web/api/capturecontroller/capturecontroller/index.md @@ -35,10 +35,10 @@ const stream = await navigator.mediaDevices.getDisplayMedia({ controller }); const [track] = stream.getVideoTracks(); const displaySurface = track.getSettings().displaySurface; -if (displaySurface == "browser") { +if (displaySurface === "browser") { // Focus the captured tab. controller.setFocusBehavior("focus-captured-surface"); -} else if (displaySurface == "window") { +} else if (displaySurface === "window") { // Do not move focus to the captured window. // Keep the capturing page focused. controller.setFocusBehavior("no-focus-change"); diff --git a/files/en-us/web/api/capturecontroller/index.md b/files/en-us/web/api/capturecontroller/index.md index b4fa2cff323722e..4ec777f6446d655 100644 --- a/files/en-us/web/api/capturecontroller/index.md +++ b/files/en-us/web/api/capturecontroller/index.md @@ -36,10 +36,10 @@ const stream = await navigator.mediaDevices.getDisplayMedia({ controller }); const [track] = stream.getVideoTracks(); const displaySurface = track.getSettings().displaySurface; -if (displaySurface == "browser") { +if (displaySurface === "browser") { // Focus the captured tab. controller.setFocusBehavior("focus-captured-surface"); -} else if (displaySurface == "window") { +} else if (displaySurface === "window") { // Do not move focus to the captured window. // Keep the capturing page focused. controller.setFocusBehavior("no-focus-change"); diff --git a/files/en-us/web/api/capturecontroller/setfocusbehavior/index.md b/files/en-us/web/api/capturecontroller/setfocusbehavior/index.md index 86f515d29c39b84..d31d2a032aaceb5 100644 --- a/files/en-us/web/api/capturecontroller/setfocusbehavior/index.md +++ b/files/en-us/web/api/capturecontroller/setfocusbehavior/index.md @@ -50,10 +50,10 @@ const stream = await navigator.mediaDevices.getDisplayMedia({ controller }); const [track] = stream.getVideoTracks(); const displaySurface = track.getSettings().displaySurface; -if (displaySurface == "browser") { +if (displaySurface === "browser") { // Focus the captured tab. controller.setFocusBehavior("focus-captured-surface"); -} else if (displaySurface == "window") { +} else if (displaySurface === "window") { // Do not move focus to the captured window. // Keep the capturing page focused. controller.setFocusBehavior("no-focus-change"); diff --git a/files/en-us/web/api/channelmergernode/index.md b/files/en-us/web/api/channelmergernode/index.md index d525c573af34163..66d01da68695885 100644 --- a/files/en-us/web/api/channelmergernode/index.md +++ b/files/en-us/web/api/channelmergernode/index.md @@ -7,7 +7,7 @@ browser-compat: api.ChannelMergerNode {{APIRef("Web Audio API")}} -The `ChannelMergerNode` interface, often used in conjunction with its opposite, {{domxref("ChannelSplitterNode")}}, reunites different mono inputs into a single output. Each input is used to fill a channel of the output. This is useful for accessing each channels separately, e.g. for performing channel mixing where gain must be separately controlled on each channel. +The `ChannelMergerNode` interface, often used in conjunction with its opposite, {{domxref("ChannelSplitterNode")}}, reunites different mono inputs into a single output. Each input is used to fill a channel of the output. This is useful for accessing each channels separately, e.g., for performing channel mixing where gain must be separately controlled on each channel. ![Default channel merger node with six mono inputs combining to form a single output.](webaudiomerger.png) diff --git a/files/en-us/web/api/channelsplitternode/index.md b/files/en-us/web/api/channelsplitternode/index.md index a7138539129c39d..ec2a06ae4b687b7 100644 --- a/files/en-us/web/api/channelsplitternode/index.md +++ b/files/en-us/web/api/channelsplitternode/index.md @@ -7,7 +7,7 @@ browser-compat: api.ChannelSplitterNode {{APIRef("Web Audio API")}} -The `ChannelSplitterNode` interface, often used in conjunction with its opposite, {{domxref("ChannelMergerNode")}}, separates the different channels of an audio source into a set of mono outputs. This is useful for accessing each channel separately, e.g. for performing channel mixing where gain must be separately controlled on each channel. +The `ChannelSplitterNode` interface, often used in conjunction with its opposite, {{domxref("ChannelMergerNode")}}, separates the different channels of an audio source into a set of mono outputs. This is useful for accessing each channel separately, e.g., for performing channel mixing where gain must be separately controlled on each channel. ![Default channel splitter node with a single input splitting to form 6 mono outputs.](webaudiosplitter.png) diff --git a/files/en-us/web/api/chapterinformation/index.md b/files/en-us/web/api/chapterinformation/index.md index 84488b32cc2c6c1..c6a55d73ed2a6eb 100644 --- a/files/en-us/web/api/chapterinformation/index.md +++ b/files/en-us/web/api/chapterinformation/index.md @@ -9,7 +9,7 @@ browser-compat: api.ChapterInformation {{APIRef("Media Session API")}}{{SeeCompatTable}} -The **`ChapterInformation`** interface of the {{domxref("Media Session API", "", "", "nocode")}} represents the metadata for an individual chapter of a media resource (i.e. a video or audio file). +The **`ChapterInformation`** interface of the {{domxref("Media Session API", "", "", "nocode")}} represents the metadata for an individual chapter of a media resource (i.e., a video or audio file). The chapter information for a given media resource is set when it is first created, via the `chapterInfo` property of the {{domxref("MediaMetadata.MediaMetadata", "MediaMetadata()")}} constructor's initialization object. The property takes an array of `ChapterInformation` objects as its value. @@ -31,49 +31,52 @@ The sample code below from [Video / Media Session Sample](https://googlechrome.g ```js const BASE_URL = "https://storage.googleapis.com/media-session/"; -chapterInfo: [ - { - title: "Chapter 1", - startTime: 0, - artwork: [ - { - src: BASE_URL + "sintel/chapter1-128.png", - sizes: "128x128", - type: "image/png", - }, - { - src: BASE_URL + "sintel/chapter1-512.png", - sizes: "512x512", - type: "image/png", - }, - ], - }, - { - title: "Chapter 2", - startTime: 37, - artwork: [ - { - src: BASE_URL + "sintel/chapter2-128.png", - sizes: "128x128", - type: "image/png", - }, - { - src: BASE_URL + "sintel/chapter2-512.png", - sizes: "512x512", - type: "image/png", - }, - ], - }, -]; +const metadata = { + // … + chapterInfo: [ + { + title: "Chapter 1", + startTime: 0, + artwork: [ + { + src: `${BASE_URL}sintel/chapter1-128.png`, + sizes: "128x128", + type: "image/png", + }, + { + src: `${BASE_URL}sintel/chapter1-512.png`, + sizes: "512x512", + type: "image/png", + }, + ], + }, + { + title: "Chapter 2", + startTime: 37, + artwork: [ + { + src: `${BASE_URL}sintel/chapter2-128.png`, + sizes: "128x128", + type: "image/png", + }, + { + src: `${BASE_URL}sintel/chapter2-512.png`, + sizes: "512x512", + type: "image/png", + }, + ], + }, + ], +}; ``` The following snippet shows how it can be used inside Media Session code (the above object property is part of the `playlist` object referenced below): ```js function updateMetadata() { - let track = playlist[index]; + const track = playlist[index]; - log("Playing " + track.title + " track..."); + log(`Playing ${track.title} track...`); navigator.mediaSession.metadata = new MediaMetadata({ title: track.title, artist: track.artist, @@ -81,7 +84,7 @@ function updateMetadata() { chapterInfo: track.chapterInfo, }); - // ... + // … } ``` diff --git a/files/en-us/web/api/characterboundsupdateevent/index.md b/files/en-us/web/api/characterboundsupdateevent/index.md index b46b8552dbc07d5..1ca865275b8800d 100644 --- a/files/en-us/web/api/characterboundsupdateevent/index.md +++ b/files/en-us/web/api/characterboundsupdateevent/index.md @@ -81,9 +81,10 @@ editContext.addEventListener("characterboundsupdate", (e) => { console.log( "The required character bounds are", charBounds - .map((bound) => { - return `(x: ${bound.x}, y: ${bound.y}, width: ${bound.width}, height: ${bound.height})`; - }) + .map( + (bound) => + `(x: ${bound.x}, y: ${bound.y}, width: ${bound.width}, height: ${bound.height})`, + ) .join(", "), ); }); diff --git a/files/en-us/web/api/clients/index.md b/files/en-us/web/api/clients/index.md index d2b859d27eca342..2cc770de5d8a5c2 100644 --- a/files/en-us/web/api/clients/index.md +++ b/files/en-us/web/api/clients/index.md @@ -48,9 +48,7 @@ addEventListener("notificationclick", (event) => { // If we didn't find an existing chat window, // open a new one: - if (!chatClient) { - chatClient = await clients.openWindow("/chat/"); - } + chatClient ??= await clients.openWindow("/chat/"); // Message the client: chatClient.postMessage("New chat messages!"); diff --git a/files/en-us/web/api/clients/openwindow/index.md b/files/en-us/web/api/clients/openwindow/index.md index e78d2fb7d26e6cc..842d6db025788f1 100644 --- a/files/en-us/web/api/clients/openwindow/index.md +++ b/files/en-us/web/api/clients/openwindow/index.md @@ -70,17 +70,18 @@ self.addEventListener("notificationclick", (e) => { // Get all the Window clients e.waitUntil( clients.matchAll({ type: "window" }).then((clientsArr) => { - // If a Window tab matching the targeted URL already exists, focus that; - const hadWindowToFocus = clientsArr.some((windowClient) => - windowClient.url === e.notification.data.url - ? (windowClient.focus(), true) - : false, + const windowToFocus = clientsArr.find( + (windowClient) => windowClient.url === e.notification.data.url, ); - // Otherwise, open a new tab to the applicable URL and focus it. - if (!hadWindowToFocus) + if (windowToFocus) { + // If a Window tab matching the targeted URL already exists, focus that; + windowToFocus.focus(); + } else { + // Otherwise, open a new tab to the applicable URL and focus it. clients .openWindow(e.notification.data.url) .then((windowClient) => (windowClient ? windowClient.focus() : null)); + } }), ); }); diff --git a/files/en-us/web/api/clipboard/read/index.md b/files/en-us/web/api/clipboard/read/index.md index 251fd129514310a..50aa260f59bf1fc 100644 --- a/files/en-us/web/api/clipboard/read/index.md +++ b/files/en-us/web/api/clipboard/read/index.md @@ -199,7 +199,7 @@ const destinationDiv = document.querySelector("#destination"); destinationDiv.addEventListener("click", pasteData); async function pasteData() { - destinationDiv.innerText = ""; //Clear inner text + destinationDiv.innerText = ""; // Clear inner text try { const clipboardContents = await navigator.clipboard.read(); for (const item of clipboardContents) { @@ -208,8 +208,7 @@ async function pasteData() { mimeTypeElement.innerText = `MIME type: ${mimeType}`; destinationDiv.appendChild(mimeTypeElement); if (mimeType === "image/png") { - const pngImage = new Image(); // Image constructor - pngImage.src = "image1.png"; + const pngImage = new Image(); pngImage.alt = "PNG image from clipboard"; const blob = await item.getType("image/png"); pngImage.src = URL.createObjectURL(blob); @@ -248,7 +247,7 @@ Notes: - Even though the butterfly image is a JPG file, when read from the clipboard it is a PNG. - If prompted, you will need to grant permission in order to paste the image. -- This may not work on chromium browsers as the sample frame is not granted the [Permissions-Policy](/en-US/docs/Web/HTTP/Headers/Permissions-Policy) `clipboard-read` and `clipboard-write` permissions ([required by Chromium browsers](/en-US/docs/Web/API/Clipboard_API#security_considerations)). +- This may not work on chromium browsers as the sample frame is not granted the [Permissions-Policy](/en-US/docs/Web/HTTP/Reference/Headers/Permissions-Policy) `clipboard-read` and `clipboard-write` permissions ([required by Chromium browsers](/en-US/docs/Web/API/Clipboard_API#security_considerations)). ### Reading unsanitized HTML from the clipboard diff --git a/files/en-us/web/api/clipboard/write/index.md b/files/en-us/web/api/clipboard/write/index.md index 1129914340473ca..4c63155f938a26b 100644 --- a/files/en-us/web/api/clipboard/write/index.md +++ b/files/en-us/web/api/clipboard/write/index.md @@ -125,8 +125,7 @@ async function getBlobFromCanvas(canvas) { Next we set up our canvas and add an event listener for the `click` event. -When you click the blue rectangle the code first checks if the clipboard supports data of type `"image/png"`. -If so, the canvas displaying the rectangle is copied into a blob, and then the blob is added to a `ClipboardItem` and then written to the clipboard. +When you click the blue rectangle, the canvas displaying the rectangle is copied into a blob, and then the blob is added to a `ClipboardItem` and then written to the clipboard. ```js const canvas = document.getElementById("canvas"); @@ -140,26 +139,21 @@ canvas.addEventListener("click", copyCanvasContentsToClipboard); const target = document.getElementById("target"); async function copyCanvasContentsToClipboard() { - if (ClipboardItem.supports("image/png")) { - // Copy canvas to blob - try { - const blob = await getBlobFromCanvas(canvas); - // Create ClipboardItem with blob and it's type, and add to an array - const data = [new ClipboardItem({ [blob.type]: blob })]; - // Write the data to the clipboard - await navigator.clipboard.write(data); - log("Copied"); - } catch (error) { - log(error); - } - } else { - log("image/png is not supported"); + // Copy canvas to blob + try { + const blob = await getBlobFromCanvas(canvas); + // Create ClipboardItem with blob and it's type, and add to an array + const data = [new ClipboardItem({ [blob.type]: blob })]; + // Write the data to the clipboard + await navigator.clipboard.write(data); + log("Copied"); + } catch (error) { + log(error); } } ``` -Note that clipboard support for PNG files is a mandatory part of the specification, so we don't actually need the check using {{domxref("ClipboardItem.supports_static", "ClipboardItem.supports()")}} above (it always returns `true`). -The check would be more useful in cases where we're fetching an optional file type, or a resource where we don't know the type in advance. +Note that if you are fetching a less-common file type or a resource that you don't know the type in advance, you may want to use {{domxref("ClipboardItem.supports_static", "ClipboardItem.supports()")}} to check if the file type is supported, and provide a good error message to the user in case it isn't. We then define an event listener for [`paste` events](/en-US/docs/Web/API/Element/paste_event) on then element where we want to display the clipboard contents as an image. The [FileReader API](/en-US/docs/Web/API/FileReader) allows us to read the blob using the [`readAsDataUrl`](/en-US/docs/Web/API/FileReader/readAsDataURL) method and create an `<img>` element with the canvas contents: diff --git a/files/en-us/web/api/clipboard_api/index.md b/files/en-us/web/api/clipboard_api/index.md index fce8c54298f9447..5e02d7aac33c37f 100644 --- a/files/en-us/web/api/clipboard_api/index.md +++ b/files/en-us/web/api/clipboard_api/index.md @@ -71,9 +71,9 @@ Chromium browsers: - Reading requires the [Permissions API](/en-US/docs/Web/API/Permissions_API) `clipboard-read` permission be granted. Transient activation is not required. -- Writing requires either the `clipboard-read` permission or transient activation. +- Writing requires either the `clipboard-write` permission or transient activation. If the permission is granted, it persists, and further transient activation is not required. -- The HTTP [Permissions-Policy](/en-US/docs/Web/HTTP/Headers/Permissions-Policy) permissions `clipboard-read` and `clipboard-write` must be allowed for {{HTMLElement("iframe")}} elements that access the clipboard. +- The HTTP [Permissions-Policy](/en-US/docs/Web/HTTP/Reference/Headers/Permissions-Policy) permissions `clipboard-read` and `clipboard-write` must be allowed for {{HTMLElement("iframe")}} elements that access the clipboard. - No persistent paste-prompt is displayed when a read operation is caused by a browser or OS "paste element". Firefox & Safari: diff --git a/files/en-us/web/api/closeevent/code/index.md b/files/en-us/web/api/closeevent/code/index.md index eaff819b0a74b6c..5a4e487286a05d9 100644 --- a/files/en-us/web/api/closeevent/code/index.md +++ b/files/en-us/web/api/closeevent/code/index.md @@ -70,7 +70,7 @@ An integer [WebSocket connection close code](https://www.rfc-editor.org/rfc/rfc6 </tr> <tr> <td><code>1005</code></td> - <td>No Status Rcvd</td> + <td>No Status Received</td> <td> <strong>Reserved.</strong> Indicates that no status code was provided even though one was expected. </td> @@ -137,7 +137,7 @@ An integer [WebSocket connection close code](https://www.rfc-editor.org/rfc/rfc6 <td><a href="https://mailarchive.ietf.org/arch/msg/hybi/P_1vbD9uyHl63nbIIbFxKMfSwcM/">Try Again Later</a></td> <td> The server is terminating the connection due to a temporary condition, - e.g. it is overloaded and is casting off some of its clients. + e.g., it is overloaded and is casting off some of its clients. </td> </tr> <tr> diff --git a/files/en-us/web/api/closewatcher/cancel_event/index.md b/files/en-us/web/api/closewatcher/cancel_event/index.md index 2bd6a1081f0451b..4baaa71d37e9a8f 100644 --- a/files/en-us/web/api/closewatcher/cancel_event/index.md +++ b/files/en-us/web/api/closewatcher/cancel_event/index.md @@ -10,7 +10,7 @@ browser-compat: api.CloseWatcher.cancel_event {{APIRef("HTML DOM")}} {{SeeCompatTable}} -A `cancel` event is fired at a {{domxref("CloseWatcher")}} object before the `close` event, so that `close` can be prevented from firing, if necessary. It is triggered by all close signals (e.g. the <kbd>Esc</kbd> key) as well as {{domxref("CloseWatcher.requestClose()")}}. +A `cancel` event is fired at a {{domxref("CloseWatcher")}} object before the `close` event, so that `close` can be prevented from firing, if necessary. It is triggered by all close signals (e.g., the <kbd>Esc</kbd> key) as well as {{domxref("CloseWatcher.requestClose()")}}. ## Syntax @@ -40,7 +40,7 @@ watcher.addEventListener("cancel", (e) => { e.preventDefault(); } } -}; +}); // Trigger a close request manually watcher.requestClose(); diff --git a/files/en-us/web/api/closewatcher/close_event/index.md b/files/en-us/web/api/closewatcher/close_event/index.md index d7a357dce2218d6..802d5f57b71f0fd 100644 --- a/files/en-us/web/api/closewatcher/close_event/index.md +++ b/files/en-us/web/api/closewatcher/close_event/index.md @@ -38,7 +38,7 @@ Use the `close` to listen for close requests. watcher.addEventListener("close", () => { // Close your UI component sidebar.hide(); -}; +}); ``` ## Specifications diff --git a/files/en-us/web/api/closewatcher/closewatcher/index.md b/files/en-us/web/api/closewatcher/closewatcher/index.md index 7004fbf32987c51..8836d5d72db6117 100644 --- a/files/en-us/web/api/closewatcher/closewatcher/index.md +++ b/files/en-us/web/api/closewatcher/closewatcher/index.md @@ -46,7 +46,7 @@ Create a new `CloseWatcher` with an {{domxref("AbortSignal")}} that controls des ```js const controller = new AbortController(); -const signalWatcher = new CloseWatcher({ signal: controller.signal }; +const signalWatcher = new CloseWatcher({ signal: controller.signal }); ``` ## Specifications diff --git a/files/en-us/web/api/closewatcher/index.md b/files/en-us/web/api/closewatcher/index.md index 8a88712227ab7d8..76633a9773e1557 100644 --- a/files/en-us/web/api/closewatcher/index.md +++ b/files/en-us/web/api/closewatcher/index.md @@ -59,7 +59,7 @@ In addition, the first close watcher does not necessarily have to be a `CloseWat ### Processing close requests -In this example, you have your own UI component (a picker) and you want to support both, the platform's default close method (e.g. the <kbd>Esc</kbd> key) and your custom close method (a close button). +In this example, you have your own UI component (a picker) and you want to support both, the platform's default close method (e.g., the <kbd>Esc</kbd> key) and your custom close method (a close button). You create a `CloseWatcher` to handle all `close` events. @@ -164,7 +164,7 @@ function openSidebar() { sidebar.classList.add("open"); mainContent.classList.add("open"); - //Add new CloseWatcher + // Add new CloseWatcher const watcher = new CloseWatcher(); sidebarClose.addEventListener("click", () => watcher.close()); diff --git a/files/en-us/web/api/closewatcher/requestclose/index.md b/files/en-us/web/api/closewatcher/requestclose/index.md index ff2974e8261617d..e9ce4ca73f9a71e 100644 --- a/files/en-us/web/api/closewatcher/requestclose/index.md +++ b/files/en-us/web/api/closewatcher/requestclose/index.md @@ -30,7 +30,7 @@ None ({{jsxref("undefined")}}). ### Using the `requestClose()` method -In this example, you have your own UI component (a picker), and you want to support both the platform's default close method (e.g. the <kbd>Esc</kbd> key) and your custom close method (a close button). +In this example, you have your own UI component (a picker), and you want to support both the platform's default close method (e.g., the <kbd>Esc</kbd> key) and your custom close method (a close button). The `onclick` handler of your UI component can call `requestClose` to request a close and to route your close request through the same `onclose` handler the platform close method uses. diff --git a/files/en-us/web/api/commandevent/command/index.md b/files/en-us/web/api/commandevent/command/index.md index 86e3c30b2d41378..f281fa92c923f4c 100644 --- a/files/en-us/web/api/commandevent/command/index.md +++ b/files/en-us/web/api/commandevent/command/index.md @@ -3,12 +3,10 @@ title: "CommandEvent: command property" short-title: command slug: Web/API/CommandEvent/command page-type: web-api-instance-property -status: - - experimental browser-compat: api.CommandEvent.command --- -{{APIRef("Invoker Commands API")}}{{SeeCompatTable}} +{{APIRef("Invoker Commands API")}} The **`command`** read-only property of the {{domxref("CommandEvent")}} interface returns a string containing the value of the {{domxref("HTMLButtonElement.command", "command")}} property at the time the event was dispatched. @@ -26,7 +24,7 @@ document.body.addEventListener( (event) => { const theAction = event.command; - if (theAction == "show-modal") { + if (theAction === "show-modal") { console.log("Showing modal dialog"); } }, diff --git a/files/en-us/web/api/commandevent/commandevent/index.md b/files/en-us/web/api/commandevent/commandevent/index.md index 648f80e7f0a6828..5c2eded4b140bd8 100644 --- a/files/en-us/web/api/commandevent/commandevent/index.md +++ b/files/en-us/web/api/commandevent/commandevent/index.md @@ -3,12 +3,10 @@ title: "CommandEvent: CommandEvent() constructor" short-title: CommandEvent() slug: Web/API/CommandEvent/CommandEvent page-type: web-api-constructor -status: - - experimental browser-compat: api.CommandEvent.CommandEvent --- -{{APIRef("Invoker Commands API")}}{{SeeCompatTable}} +{{APIRef("Invoker Commands API")}} The **`CommandEvent()`** constructor creates a new {{domxref("CommandEvent")}} object. diff --git a/files/en-us/web/api/commandevent/index.md b/files/en-us/web/api/commandevent/index.md index 52e91e114e63a86..e464fcb3587f813 100644 --- a/files/en-us/web/api/commandevent/index.md +++ b/files/en-us/web/api/commandevent/index.md @@ -2,12 +2,10 @@ title: CommandEvent slug: Web/API/CommandEvent page-type: web-api-interface -status: - - experimental browser-compat: api.CommandEvent --- -{{APIRef("Invoker Commands API")}}{{SeeCompatTable}} +{{APIRef("Invoker Commands API")}} The **`CommandEvent`** interface represents an event notifying the user when a {{domxref("HTMLButtonElement", "button")}} element with valid {{domxref("HTMLButtonElement.commandForElement", "commandForElement")}} and {{domxref("HTMLButtonElement.command", "command")}} attributes is about to invoke an interactive element. @@ -17,16 +15,16 @@ This is the event object for the `HTMLElement` {{domxref("HTMLElement.command_ev ## Constructor -- {{domxref("CommandEvent.CommandEvent", "CommandEvent()")}} {{experimental_inline}} +- {{domxref("CommandEvent.CommandEvent", "CommandEvent()")}} - : Creates an `CommandEvent` object. ## Instance properties _This interface inherits properties from its parent, {{DOMxRef("Event")}}._ -- {{domxref("CommandEvent.source")}} {{ReadOnlyInline}} {{experimental_inline}} +- {{domxref("CommandEvent.source")}} {{ReadOnlyInline}} - : An {{domxref("HTMLButtonElement")}} representing the button that caused this invocation. -- {{domxref("CommandEvent.command")}} {{ReadOnlyInline}} {{experimental_inline}} +- {{domxref("CommandEvent.command")}} {{ReadOnlyInline}} - : A string representing the {{domxref("HTMLButtonElement.command", "command")}} value of the source button. ## Examples @@ -45,7 +43,7 @@ _This interface inherits properties from its parent, {{DOMxRef("Event")}}._ ```js const popover = document.getElementById("mypopover"); -// ... +// … popover.addEventListener("command", (event) => { if (event.command === "show-popover") { @@ -68,9 +66,9 @@ popover.addEventListener("command", (event) => { const image = document.getElementById("the-image"); image.addEventListener("command", (event) => { - if (event.command == "--rotate-left") { + if (event.command === "--rotate-left") { event.target.style.rotate = "-90deg"; - } else if (event.command == "--rotate-right") { + } else if (event.command === "--rotate-right") { event.target.style.rotate = "90deg"; } }); diff --git a/files/en-us/web/api/commandevent/source/index.md b/files/en-us/web/api/commandevent/source/index.md index 269fa8426aafcc2..0534c48a1f55129 100644 --- a/files/en-us/web/api/commandevent/source/index.md +++ b/files/en-us/web/api/commandevent/source/index.md @@ -3,12 +3,10 @@ title: "CommandEvent: source property" short-title: source slug: Web/API/CommandEvent/source page-type: web-api-instance-property -status: - - experimental browser-compat: api.CommandEvent.source --- -{{APIRef("Invoker Commands API")}}{{SeeCompatTable}} +{{APIRef("Invoker Commands API")}} The **`source`** read-only property of the {{domxref("CommandEvent")}} interface returns an {{domxref("EventTarget")}} representing the control that invoked the given command. diff --git a/files/en-us/web/api/compressionstream/readable/index.md b/files/en-us/web/api/compressionstream/readable/index.md index 2d9e16741919d00..8832f2c571914d6 100644 --- a/files/en-us/web/api/compressionstream/readable/index.md +++ b/files/en-us/web/api/compressionstream/readable/index.md @@ -20,7 +20,7 @@ The following example returns a {{domxref("ReadableStream")}} from a `Compressio ```js let stream = new CompressionStream("gzip"); -console.log(stream.readable); //a ReadableStream +console.log(stream.readable); // A ReadableStream ``` ## Specifications diff --git a/files/en-us/web/api/compute_pressure_api/index.md b/files/en-us/web/api/compute_pressure_api/index.md index 2f21b0c28bcbe99..2392604c8da6c5c 100644 --- a/files/en-us/web/api/compute_pressure_api/index.md +++ b/files/en-us/web/api/compute_pressure_api/index.md @@ -40,7 +40,7 @@ The Compute Pressure API is available in the following contexts: - {{domxref("Window")}} (main thread) - {{domxref("Worker")}} - {{domxref("SharedWorker")}} -- {{HTMLElement("iFrame")}} (if a suitable [Permissions-Policy](/en-US/docs/Web/HTTP/Headers/Permissions-Policy/compute-pressure) is provided) +- {{HTMLElement("iframe")}} (if a suitable [Permissions-Policy](/en-US/docs/Web/HTTP/Reference/Headers/Permissions-Policy/compute-pressure) is provided) ### Pressure states @@ -55,7 +55,7 @@ The contributing factors (that is, the underlying system metrics) for the pressu ### Security and privacy considerations -The Compute Pressure API is [policy-controlled](/en-US/docs/Web/HTTP/Permissions_Policy) by the `"compute-pressure"` directive. Its default allowlist is `'self'` which allows usage in same-origin nested frames but prevents third-party content from using the feature. +The Compute Pressure API is [policy-controlled](/en-US/docs/Web/HTTP/Guides/Permissions_Policy) by the `"compute-pressure"` directive. Its default allowlist is `'self'` which allows usage in same-origin nested frames but prevents third-party content from using the feature. ## Reference @@ -64,7 +64,7 @@ The Compute Pressure API is [policy-controlled](/en-US/docs/Web/HTTP/Permissions The following interfaces are present in the Compute Pressure API and the API surface is similar to other observers, such as {{domxref("IntersectionObserver")}}, {{domxref("MutationObserver")}}, or {{domxref("PerformanceObserver")}}. - {{domxref("PressureObserver")}} {{experimental_inline}} - - : Notifies when the system's pressure changes for a specified number of sources (e.g. the CPU) at a predefined sample interval. + - : Notifies when the system's pressure changes for a specified number of sources (e.g., the CPU) at a predefined sample interval. - {{domxref("PressureRecord")}} - : Describes the pressure trend at a specific moment of transition. diff --git a/files/en-us/web/api/console/timestamp_static/index.md b/files/en-us/web/api/console/timestamp_static/index.md index 76b071ff6eb351e..9e4222cb871b5c4 100644 --- a/files/en-us/web/api/console/timestamp_static/index.md +++ b/files/en-us/web/api/console/timestamp_static/index.md @@ -10,7 +10,7 @@ browser-compat: api.console.timeStamp_static {{APIRef("Console API")}}{{Non-standard_header}} {{AvailableInWorkers}} -The **`console.timeStamp()`** static method adds a single marker to the browser's Performance tool ([Firefox](https://profiler.firefox.com/docs/#/), [Chrome](https://developer.chrome.com/docs/devtools/performance/reference)). This lets you correlate a point in your code with the other events recorded in the timeline, such as layout and paint events. +The **`console.timeStamp()`** static method adds a single marker to the browser's Performance tool ([Firefox bug 1387528](https://bugzil.la/1387528), [Chrome](https://developer.chrome.com/docs/devtools/performance/reference)). This lets you correlate a point in your code with the other events recorded in the timeline, such as layout and paint events. You can optionally supply an argument to label the timestamp, and this label will then be shown alongside the marker. @@ -38,4 +38,6 @@ None ({{jsxref("undefined")}}). - {{domxref("console/time_static", "console.time()")}} - {{domxref("console/timeLog_static", "console.timeLog()")}} - {{domxref("console/timeEnd_static", "console.timeEnd()")}} +- {{domxref("performance/mark", "performance.mark()")}} +- {{domxref("performance/measure", "performance.measure()")}} - [Adding markers with the console API](https://web.archive.org/web/20211207010020/https://firefox-source-docs.mozilla.org/devtools-user/performance/waterfall/index.html#adding-markers-with-the-console-api) diff --git a/files/en-us/web/api/constantsourcenode/constantsourcenode/index.md b/files/en-us/web/api/constantsourcenode/constantsourcenode/index.md index fc9a4ec13c3f462..ec53cf6bef6cd9e 100644 --- a/files/en-us/web/api/constantsourcenode/constantsourcenode/index.md +++ b/files/en-us/web/api/constantsourcenode/constantsourcenode/index.md @@ -32,7 +32,7 @@ new ConstantSourceNode(context, options) - : A read-only {{domxref("AudioParam")}} specifying the constant value generated by the source. The default is 1.0. The normal range is \-1.0 to 1.0, but the value can be anywhere in the range from - `-Infinity` to `+Infinity`. + `-Infinity` to `Infinity`. ## Examples diff --git a/files/en-us/web/api/contactaddress/addressline/index.md b/files/en-us/web/api/contactaddress/addressline/index.md index 1fd9ba889e36e5a..81f197f561dadd5 100644 --- a/files/en-us/web/api/contactaddress/addressline/index.md +++ b/files/en-us/web/api/contactaddress/addressline/index.md @@ -24,7 +24,7 @@ An array of strings, each containing one line of the address. For example, the ` These, combined with additional values for other properties of the {{domxref("ContactAddress")}}, would represent the full address, which is: -```plaintext +```plain Mozilla Metal Box Factory Suite 441, 4th floor diff --git a/files/en-us/web/api/contentvisibilityautostatechangeevent/index.md b/files/en-us/web/api/contentvisibilityautostatechangeevent/index.md index dcae46a2ae26716..7f3c3671a19dee4 100644 --- a/files/en-us/web/api/contentvisibilityautostatechangeevent/index.md +++ b/files/en-us/web/api/contentvisibilityautostatechangeevent/index.md @@ -11,9 +11,9 @@ The **`ContentVisibilityAutoStateChangeEvent`** interface is the event object fo While the element is not relevant (between the start and end events), the user agent skips an element's rendering, including layout and painting. This can significantly improve page rendering speed. -The {{domxref("element/contentvisibilityautostatechange_event", "contentvisibilityautostatechange")}} event provides a way for an app's code to also start or stop rendering processes (e.g. drawing on a {{htmlelement("canvas")}}) when they are not needed, thereby conserving processing power. +The {{domxref("element/contentvisibilityautostatechange_event", "contentvisibilityautostatechange")}} event provides a way for an app's code to also start or stop rendering processes (e.g., drawing on a {{htmlelement("canvas")}}) when they are not needed, thereby conserving processing power. -Note that even when hidden from view, element contents will remain semantically relevant (e.g. to assistive technology users), so this signal should not be used to skip significant semantic DOM updates. +Note that even when hidden from view, element contents will remain semantically relevant (e.g., to assistive technology users), so this signal should not be used to skip significant semantic DOM updates. {{InheritanceDiagram}} diff --git a/files/en-us/web/api/convolvernode/buffer/index.md b/files/en-us/web/api/convolvernode/buffer/index.md index 4ee5aceb42eccb7..4966012b67c2f63 100644 --- a/files/en-us/web/api/convolvernode/buffer/index.md +++ b/files/en-us/web/api/convolvernode/buffer/index.md @@ -28,10 +28,10 @@ For more complete applied examples/information, check out our [Voice-change-O-ma ```js const audioCtx = new AudioContext(); -// ... +// … const convolver = audioCtx.createConvolver(); -// ... +// … // Grab audio track via fetch() for convolver node try { diff --git a/files/en-us/web/api/convolvernode/normalize/index.md b/files/en-us/web/api/convolvernode/normalize/index.md index 0956607a1ed2d9c..b64d2e577af2580 100644 --- a/files/en-us/web/api/convolvernode/normalize/index.md +++ b/files/en-us/web/api/convolvernode/normalize/index.md @@ -31,10 +31,10 @@ The following example creates a convolver node and assigns it an {{domxref("Audi ```js const audioCtx = new AudioContext(); -// ... +// … const convolver = audioCtx.createConvolver(); -// ... +// … // Grab audio track via fetch() for convolver node try { diff --git a/files/en-us/web/api/cookie_store_api/index.md b/files/en-us/web/api/cookie_store_api/index.md index 5c93aa5c5811a6a..1012989b1f9eb91 100644 --- a/files/en-us/web/api/cookie_store_api/index.md +++ b/files/en-us/web/api/cookie_store_api/index.md @@ -14,11 +14,12 @@ The **Cookie Store API** is an asynchronous API for managing cookies, available ## Concepts and Usage -The existing method of getting and setting cookies involves working with {{domxref("document.cookie")}} as a string of key/value pairs. In addition to this being cumbersome and error prone, it also has a host of issues in the context of modern web development. +The original method of getting and setting cookies involves working with {{domxref("document.cookie")}} to get and set cookie information as a string of key/value pairs. +In addition to this being cumbersome and error prone, it also has a host of issues in the context of modern web development. -The `document.cookie` interface is {{Glossary("synchronous")}}, single-threaded, and blocking. When writing a cookie you must wait for the browser to update the string of all cookies. In addition, the reliance on {{domxref("document")}} means that cookies cannot be accessed by service workers which cannot access the `document` object. +The `document.cookie` interface is {{Glossary("synchronous")}}, single-threaded, and blocking. When writing a cookie you must wait for the browser to update the string of all cookies. In addition, the reliance on {{domxref("document")}} means that cookies cannot be accessed by service workers, as they cannot access the `document` object. -The _Cookie Store API_ provides an updated method of managing cookies. It is {{Glossary("asynchronous")}} and promise-based, therefore does not block the event loop. It does not rely on {{domxref("document")}} and so is available to service workers. The methods for getting and setting cookies also provide more feedback by way of error messages. This means that web developers do not have to set then immediately read back a cookie to check that setting was successful. +The _Cookie Store API_ provides an updated method of managing cookies. It is {{Glossary("asynchronous")}} and promise-based, therefore does not block the event loop. It does not rely on {{domxref("Document")}} and so is available to service workers. The methods for getting and setting cookies also provide more feedback by way of error messages. This means that web developers do not have to set then immediately read back a cookie to check that setting was successful. ## Interfaces diff --git a/files/en-us/web/api/cookiechangeevent/changed/index.md b/files/en-us/web/api/cookiechangeevent/changed/index.md index de44690a3eedea8..b627666cf314c49 100644 --- a/files/en-us/web/api/cookiechangeevent/changed/index.md +++ b/files/en-us/web/api/cookiechangeevent/changed/index.md @@ -30,12 +30,12 @@ An array of objects containing the changed cookie(s). Each object contains the f - : A {{jsxref("boolean")}} indicating whether the cookie is used only in a secure context (HTTPS rather than HTTP). - `sameSite` - - : One of the following [`SameSite`](/en-US/docs/Web/HTTP/Headers/Set-Cookie#samesitesamesite-value) values: + - : One of the following [`SameSite`](/en-US/docs/Web/HTTP/Reference/Headers/Set-Cookie#samesitesamesite-value) values: - `"strict"` - : Cookies will only be sent in a first-party context and not be sent with requests initiated by third party websites. - `"lax"` - - : Cookies are not sent on normal cross-site subrequests (for example to load images or frames into a third party site), but are sent when a user is navigating within the origin site (i.e. when following a link). + - : Cookies are not sent on normal cross-site subrequests (for example to load images or frames into a third party site), but are sent when a user is navigating within the origin site (i.e., when following a link). - `"none"` - : Cookies will be sent in all contexts. diff --git a/files/en-us/web/api/cookiechangeevent/deleted/index.md b/files/en-us/web/api/cookiechangeevent/deleted/index.md index b7c68d71c1c6e8e..80f2b95f921f810 100644 --- a/files/en-us/web/api/cookiechangeevent/deleted/index.md +++ b/files/en-us/web/api/cookiechangeevent/deleted/index.md @@ -30,12 +30,12 @@ An array of objects containing the deleted cookie(s). Each object contains the f - : A {{jsxref("boolean")}} indicating whether the cookie is used only in a secure context (HTTPS rather than HTTP). - `sameSite` - - : One of the following [`SameSite`](/en-US/docs/Web/HTTP/Headers/Set-Cookie#samesitesamesite-value) values: + - : One of the following [`SameSite`](/en-US/docs/Web/HTTP/Reference/Headers/Set-Cookie#samesitesamesite-value) values: - `"strict"` - : Cookies will only be sent in a first-party context and not be sent with requests initiated by third party websites. - `"lax"` - - : Cookies are not sent on normal cross-site subrequests (for example to load images or frames into a third party site), but are sent when a user is navigating within the origin site (i.e. when following a link). + - : Cookies are not sent on normal cross-site subrequests (for example to load images or frames into a third party site), but are sent when a user is navigating within the origin site (i.e., when following a link). - `"none"` - : Cookies will be sent in all contexts. diff --git a/files/en-us/web/api/cookiestore/change_event/index.md b/files/en-us/web/api/cookiestore/change_event/index.md index 63d6ad76dede5d4..ccf880414fe931e 100644 --- a/files/en-us/web/api/cookiestore/change_event/index.md +++ b/files/en-us/web/api/cookiestore/change_event/index.md @@ -15,9 +15,9 @@ A `change` event is fired at a {{domxref("CookieStore")}} object when a change i Use the event name in methods like {{domxref("EventTarget.addEventListener", "addEventListener()")}}, or set an event handler property. ```js-nolint -cookieStore.addEventListener("change", (event) => { }) +addEventListener("change", (event) => { }) -cookieStore.onchange = (event) => { } +onchange = (event) => { } ``` ## Event type diff --git a/files/en-us/web/api/cookiestore/delete/index.md b/files/en-us/web/api/cookiestore/delete/index.md index f1fbeb10e53740f..183e87f4f0d676f 100644 --- a/files/en-us/web/api/cookiestore/delete/index.md +++ b/files/en-us/web/api/cookiestore/delete/index.md @@ -8,7 +8,10 @@ browser-compat: api.CookieStore.delete {{securecontext_header}}{{APIRef("Cookie Store API")}}{{AvailableInWorkers("window_and_service")}} -The **`delete()`** method of the {{domxref("CookieStore")}} interface deletes a cookie with the given `name` or `options` object. The `delete()` method expires the cookie by changing the date to one in the past. +The **`delete()`** method of the {{domxref("CookieStore")}} interface deletes a cookie that matches the given `name` or `options` object. +The method expires the cookie by changing its date to one in the past. + +Note that there is no error if a cookie cannot be matched: the returned promise will fulfill when the matched cookie is deleted or if no cookie is matched. ## Syntax @@ -41,25 +44,219 @@ Or ### Return value -A {{jsxref("Promise")}} that resolves with {{jsxref("undefined")}} when deletion completes. +A {{jsxref("Promise")}} that resolves with {{jsxref("undefined")}} when the deletion operation completes or no cookie is matched. ### Exceptions - `SecurityError` {{domxref("DOMException")}} - : Thrown if the origin can not be {{glossary("Serialization", "serialized")}} to a URL. - {{jsxref("TypeError")}} - - : Thrown if deleting the cookie represented by the given `name` or `options` fails. + - : Thrown if a cookie that matches a given `name` or `options` cannot be deleted. ## Examples -In this example, a cookie is deleted by passing the name to the `delete()` method. +<!-- The examples don't work as live examples in MDN environment (due to unknown errors) --> + +### Delete a named cookie + +This example shows how a cookie can be deleted by passing its name to the `delete()` method. + +This will work if the cookie to be deleted matches the cookie name and the default values of the [`options`](#options) above. +This will be the case if the cookie was {{domxref("CookieStore/set","set()")}} using the just a name and value, but may not be if the cookie was created with options or using {{domxref("Document.cookie")}}. + +The code first defines `setTestCookies()` which creates some test cookies and logs their names. + +```js +async function setTestCookies() { + // Set two cookies + try { + await cookieStore.set("cookie1", "cookie1-value"); + } catch (error) { + console.log(`Error setting cookie1: ${error}`); + } + + try { + await cookieStore.set("cookie2", "cookie2-value"); + } catch (error) { + console.log(`Error setting cookie2: ${error}`); + } + + // Log cookie names + const cookieNames = (await cookieStore.getAll()) + .map((cookie) => cookie.name) + .join(" "); + console.log(`Initial cookies: ${cookieNames}`); +} +``` + +The `cookieTest()` method calls `setTestCookies()`. +It then deletes "cookie1" that we just created, and lists all cookie names again. + +```js +async function cookieTest() { + // Create our test cookies + await setTestCookies(); + + // Delete cookie1 + try { + await cookieStore.delete("cookie1"); + } catch (error) { + console.log(`Error deleting cookie1: ${error}`); + } + + // Log cookie names again (to show cookie1 deleted) + const cookieNames = (await cookieStore.getAll()) + .map((cookie) => cookie.name) + .join(" "); + console.log( + `Cookies remaining after attempting to delete cookie1: ${cookieNames}`, + ); +} + +cookieTest(); +``` + +When run, the console log should initially show that both cookie1 and cookie2 are present, but cookie1 is not listed after it has been deleted. + +### Delete a cookie with options + +This example is almost identical to the previous one, except it demonstrates that the options must match those of the cookie to be deleted. + +The code first defines `setTestCookies()`. +This creates two cookies with the `partitioned` property set to `true`, and logs their names. + +```js +async function setTestCookies() { + // Set two cookies + try { + await cookieStore.set({ + name: "cookie1", + value: `cookie1-value`, + partitioned: true, + }); + } catch (error) { + console.log(`Error setting cookie1: ${error}`); + } + + try { + await cookieStore.set({ + name: "cookie2", + value: `cookie2-value`, + partitioned: true, + }); + } catch (error) { + console.log(`Error setting cookie2: ${error}`); + } + + // Log cookie names + const cookieNames = (await cookieStore.getAll()) + .map((cookie) => cookie.name) + .join(" "); + console.log(`Initial cookies: ${cookieNames}`); +} +``` + +The `cookieTest()` method calls `setTestCookies()`. +It then attempts to delete the cookies named "cookie1", specifying its name, and "cookie2" specifying its name and `partitioned: true`. +The method then lists the cookie names again. ```js -const result = await cookieStore.delete("cookie1"); +async function cookieTest() { + // Create our test cookies + await setTestCookies(); + + // Delete cookie1 specifying just the name + try { + await cookieStore.delete("cookie1"); + } catch (error) { + console.log(`Error deleting cookie1: ${error}`); + } + + // Delete cookie2, setting partitioned to true + try { + await cookieStore.delete({ + name: "cookie2", + partitioned: true, + }); + } catch (error) { + console.log(`Error deleting cookie2: ${error}`); + } -console.log(result); + // Log cookie names again (to show cookie1 deleted) + cookieNames = (await cookieStore.getAll()) + .map((cookie) => cookie.name) + .join(" "); + console.log( + `Cookies remaining after attempted deletions (cookie2 should be deleted): ${cookieNames}`, + ); +} + +cookieTest(); ``` +When run, the console log should show that both "cookie1" and "cookie2" are present initially, but "cookie2" is not listed afterwards. +The cookie named "cookie1" is still present because it does not match the cookies specified in the `delete()` call. + +> [!NOTE] +> The deletion silently fails if no cookie is matched. + +### Delete cookies created using document.cookies + +Deleting a cookie that was created using {{domxref("document.cookie")}} has the same requirements as deleting a cookie created using {{domxref("CookieStore.set()")}}: the cookie either needs to match the passed `options`, or the `name` and the default options. + +> [!NOTE] +> Cookies created with `set()` always have a [default path](/en-US/docs/Web/HTTP/Guides/Cookies#define_where_cookies_are_sent) of `/`, while cookies created with `document.cookie` have a default path equal to the path of the document they are created in. +> Therefore when deleting cookies created with `document.cookie`, you can't assume they have the path `/` (unless it was been explicitly set as such), and hence that it will match the default `delete()` options. + +The code below uses `document.cookie` to create cookies named "doc_cookie1" and "doc_cookie2", with the paths `/some_path` and `/` respectively, and then logs both cookies. +The code then deletes both cookies without specifying a `path` match option, and lists the cookies again. + +```js +async function cookieTest() { + // Create doc_cookie1 with path /some_path + document.cookie = + "doc_cookie1=doc_cookie1_name; SameSite=None; Secure; max-age=10; path='/some_path'"; + + // Create doc_cookie2 with path / (the CookieStore.set() default) + document.cookie = + "doc_cookie2=doc_cookie2_name; SameSite=None; Secure; max-age=10; path=/"; + + // Log cookie names + let cookieNames = (await cookieStore.getAll()) + .map((cookie) => cookie.name) + .join(" "); + console.log(`Initial cookies: ${cookieNames}`); + + // Delete doc_cookie1 (should fail) + try { + await cookieStore.delete("doc_cookie1"); + } catch (error) { + console.log(`Error deleting doc_cookie1: ${error}`); + } + + // Delete doc_cookie2 (should succeed) + try { + await cookieStore.delete("doc_cookie2"); + } catch (error) { + console.log(`Error deleting cookie2: ${error}`); + } + + // Log cookie names again (to show cookie1 deleted) + cookieNames = (await cookieStore.getAll()) + .map((cookie) => cookie.name) + .join(" "); + console.log( + `Cookies remaining after attempted deletions (doc_cookie2 should be deleted): ${cookieNames}`, + ); +} + +cookieTest(); +``` + +When run, the first log should show that both cookies are present. +The second log should not include "doc_cookie2", as it should have matched and been deleted. +It should include "doc_cookie1" because `/some_path` will not match the default deletion path (`/`). + ## Specifications {{Specifications}} diff --git a/files/en-us/web/api/cookiestore/get/index.md b/files/en-us/web/api/cookiestore/get/index.md index 6cf318264bad798..c39d69629f615de 100644 --- a/files/en-us/web/api/cookiestore/get/index.md +++ b/files/en-us/web/api/cookiestore/get/index.md @@ -8,7 +8,7 @@ browser-compat: api.CookieStore.get {{securecontext_header}}{{APIRef("Cookie Store API")}}{{AvailableInWorkers("window_and_service")}} -The **`get()`** method of the {{domxref("CookieStore")}} interface returns a single cookie with the given `name` or `options` object. The method will return the first matching cookie for the passed parameters. +The **`get()`** method of the {{domxref("CookieStore")}} interface returns a {{jsxref("Promise")}} that resolves to a single cookie matching the given `name` or `options` object. The method will return the first cookie that matches. ## Syntax @@ -40,7 +40,9 @@ Or ### Return value -A {{jsxref("Promise")}} that resolves with an object representing the first cookie matching the submitted `name` or `options`. This object contains the following properties: +A {{jsxref("Promise")}} that resolves with an object representing the first cookie matching the submitted `name` or `options`, or `null` if there is no matching cookie. + +The object returned for a match contains the following properties: - `domain` @@ -64,14 +66,7 @@ A {{jsxref("Promise")}} that resolves with an object representing the first cook - `sameSite` - - : One of the following [`SameSite`](/en-US/docs/Web/HTTP/Headers/Set-Cookie#samesitesamesite-value) values: - - - `"strict"` - - : Cookies will only be sent in a first-party context and not be sent with requests initiated by third party websites. - - `"lax"` - - : Cookies are not sent on normal cross-site subrequests (for example to load images or frames into a third party site), but are sent when a user is navigating within the origin site (i.e. when following a link). - - `"none"` - - : Cookies will be sent in all contexts. + - : One of the following [`SameSite`](/en-US/docs/Web/HTTP/Reference/Headers/Set-Cookie#samesitesamesite-value) values: [`"strict"`](/en-US/docs/Web/HTTP/Reference/Headers/Set-Cookie#strict), [`"lax"`](/en-US/docs/Web/HTTP/Reference/Headers/Set-Cookie#lax), or [`"none"`](/en-US/docs/Web/HTTP/Reference/Headers/Set-Cookie#none). - `secure` @@ -87,22 +82,42 @@ A {{jsxref("Promise")}} that resolves with an object representing the first cook - {{jsxref("TypeError")}} - : Thrown if: - The `options` parameter is an empty object. - - The `url` option is present and is not equal with the creation URL, if in main thread. - - The `url` option is present and its origin is not the same as the origin of the creation URL. + - The method is called in the main thread, and the `url` option is specified but does not match the URL of the current window. + - The method is called in a worker and the `url` option is specified, but does not match the origin of the worker. - Querying cookies represented by the given `name` or `options` fails. ## Examples -In this example, we return a cookie named "cookie1". If the cookie is found the result of the Promise is an object containing the details of a single cookie. +<!-- The examples don't work as live examples in MDN environment (due to unknown errors) --> -```js -const cookie = await cookieStore.get("cookie1"); +### Getting a cookie by name + +This example shows how to get a particular cookie by name. -if (cookie) { - console.log(cookie); -} else { - console.log("Cookie not found"); +The code first creates a cookie named "cookie1" using {{domxref("CookieStore.set()")}}, logging any errors to the console. +It then waits on `get()` to retrieve information about that same cookie. +If the returned promise resolves with an object we log the cookie: otherwise we log that no matching cookie was found. + +```js +async function cookieTest() { + // Set test cookie + try { + await cookieStore.set("cookie1", "cookie1-value"); + } catch (error) { + console.log(`Error setting cookie1: ${error}`); + } + + // Get cookie, specifying name + const cookie = await cookieStore.get("cookie1"); + + if (cookie) { + console.log(cookie); + } else { + console.log("cookie1: Cookie not found"); + } } + +cookieTest(); ``` ## Specifications diff --git a/files/en-us/web/api/cookiestore/getall/index.md b/files/en-us/web/api/cookiestore/getall/index.md index 5355f1821657be2..6aa523a1a496f07 100644 --- a/files/en-us/web/api/cookiestore/getall/index.md +++ b/files/en-us/web/api/cookiestore/getall/index.md @@ -8,11 +8,13 @@ browser-compat: api.CookieStore.getAll {{securecontext_header}}{{APIRef("Cookie Store API")}}{{AvailableInWorkers("window_and_service")}} -The **`getAll()`** method of the {{domxref("CookieStore")}} interface returns a list of cookies that match the `name` or `options` passed to it. Passing no parameters will return all cookies for the current context. +The **`getAll()`** method of the {{domxref("CookieStore")}} interface returns a {{jsxref("Promise")}} that resolves as an array of cookies that match the `name` or `options` passed to it. +Passing no parameters will return all cookies for the current context. ## Syntax ```js-nolint +getAll() getAll(name) getAll(options) ``` @@ -64,14 +66,7 @@ Each object contains the following properties: - `sameSite` - - : One of the following [`SameSite`](/en-US/docs/Web/HTTP/Headers/Set-Cookie#samesitesamesite-value) values: - - - `"strict"` - - : Cookies will only be sent in a first-party context and not be sent with requests initiated by third party websites. - - `"lax"` - - : Cookies are not sent on normal cross-site subrequests (for example to load images or frames into a third party site), but are sent when a user is navigating within the origin site (i.e. when following a link). - - `"none"` - - : Cookies will be sent in all contexts. + - : One of the following [`SameSite`](/en-US/docs/Web/HTTP/Reference/Headers/Set-Cookie#samesitesamesite-value) values: [`"strict"`](/en-US/docs/Web/HTTP/Reference/Headers/Set-Cookie#strict), [`"lax"`](/en-US/docs/Web/HTTP/Reference/Headers/Set-Cookie#lax), or [`"none"`](/en-US/docs/Web/HTTP/Reference/Headers/Set-Cookie#none). - `secure` @@ -86,21 +81,56 @@ Each object contains the following properties: - : Thrown if the origin does not {{glossary("Serialization", "serialize")}} to a URL. - {{jsxref("TypeError")}} - : Thrown if: - - The `url` option is present and is not equal with the creation URL, if in main thread. - - The `url` option is present and its origin is not the same as the origin of the creation URL. + - The method is called in the main thread, and the `url` option is specified but does not match the URL of the current window. + - The method is called in a worker and the `url` option is specified, but does not match the origin of the worker. - Querying cookies represented by the given `name` or `options` fails. ## Examples -In this example, we use `getAll()` with no parameters. This returns all of the cookies for this context as an array of objects. +<!-- The examples don't work as live examples in MDN environment (due to unknown errors) --> + +### Get all cookies for this context + +This example shows how to get all cookies in the current context. + +First we define `setTestCookies()` which creates the test cookies "cookie1" and "cookie2", logging any errors. ```js -const cookies = await cookieStore.getAll(); +async function setTestCookies() { + // Set two cookies + try { + await cookieStore.set("cookie1", "cookie1-value"); + } catch (error) { + console.log(`Error setting cookie1: ${error}`); + } + + try { + await cookieStore.set("cookie2", "cookie2-value"); + } catch (error) { + console.log(`Error setting cookie2: ${error}`); + } +} +``` -if (cookies.length > 0) { - console.log(cookies); -} else { - console.log("Cookie not found"); +The `cookieTest()` method calls `setTestCookies()` and then waits on `getAll()`. +This returns a {{jsxref("Promise")}} that resolves with all of the cookies for this context as an array of objects, or an empty array if there are no cookies. +If the returned promise resolves with array containing cookie information we iterate the array and log each cookie ("cookie1" and "cookie2"). + +```js +async function cookieTest() { + // Set our test cookies + await setTestCookies(); + + // Get all cookies + const cookies = await cookieStore.getAll(); + + // Iterate the cookies, or log that none were found + if (cookies.length > 0) { + console.log(`Found cookies: ${cookies.length}:`); + cookies.forEach((cookie) => console.log(cookie)); + } else { + console.log("Cookies not found"); + } } ``` diff --git a/files/en-us/web/api/cookiestore/index.md b/files/en-us/web/api/cookiestore/index.md index d9d39cbb2aff3a2..173a4f496c25add 100644 --- a/files/en-us/web/api/cookiestore/index.md +++ b/files/en-us/web/api/cookiestore/index.md @@ -16,13 +16,17 @@ The `CookieStore` is accessed via attributes in the global scope in a {{domxref( ## Instance methods - {{domxref("CookieStore.delete()")}} - - : The `delete()` method deletes a cookie with the given `name` or `options` object, it returns a {{jsxref("Promise")}} that resolves when the deletion completes. + - : The `delete()` method deletes a cookie with the given `name` or `options` object. + It returns a {{jsxref("Promise")}} that resolves when the deletion completes or if no cookies are matched. - {{domxref("CookieStore.get()")}} - - : The `get()` method gets a single cookie with the given `name` or `options` object, it returns a {{jsxref("Promise")}} that resolves with details of a single cookie. + - : The `get()` method gets a single cookie with the given `name` or `options` object. + It returns a {{jsxref("Promise")}} that resolves with details of a single cookie. - {{domxref("CookieStore.getAll()")}} - - : The `getAll()` method gets all matching cookies, it returns a {{jsxref("Promise")}} that resolves with a list of cookies. + - : The `getAll()` method gets all matching cookies. + It returns a {{jsxref("Promise")}} that resolves with a list of cookies. - {{domxref("CookieStore.set()")}} - - : The `set()` method sets a cookie with the given `name` and `value` or `options` object, it returns a {{jsxref("Promise")}} that resolves when the cookie is set. + - : The `set()` method sets a cookie with the given `name` and `value` or `options` object. + It returns a {{jsxref("Promise")}} that resolves when the cookie is set. ## Events @@ -31,26 +35,149 @@ The `CookieStore` is accessed via attributes in the global scope in a {{domxref( ## Examples -In this example, we set a cookie and write to the console feedback as to whether the operation succeeded or failed. +The examples below can be tested by copying the code into a test harness and running it with a [local server](/en-US/docs/Learn_web_development/Howto/Tools_and_setup/set_up_a_local_testing_server), or deploying it to a website site such as GitHub pages. + +<!-- The examples don't work as live examples in MDN environment (due to unknown errors) --> + +### Setting cookies + +This example shows how to set cookies by passing a `name` and `value`, and by setting an `options` value. + +The `cookieTest()` method sets one cookie with `name` and `value` properties and another with `name`, `value`, and `expires` properties. +We then use the {{domxref("CookieStore.get()")}} method to get each of the cookies, which are then logged. ```js -const day = 24 * 60 * 60 * 1000; - -cookieStore - .set({ - name: "cookie1", - value: "cookie1-value", - expires: Date.now() + day, - domain: "example.com", - }) - .then( - () => { - console.log("It worked!"); - }, - (reason) => { - console.error("It failed: ", reason); - }, +async function cookieTest() { + // Set cookie: passing name and value + try { + await cookieStore.set("cookie1", "cookie1-value"); + } catch (error) { + console.log(`Error setting cookie1: ${error}`); + } + + // Set cookie: passing options + const day = 24 * 60 * 60 * 1000; + + try { + await cookieStore.set({ + name: "cookie2", + value: "cookie2-value", + expires: Date.now() + day, + partitioned: true, + }); + } catch (error) { + log(`Error setting cookie2: ${error}`); + } + + // Get named cookies and log their properties + const cookie1 = await cookieStore.get("cookie1"); + console.log(cookie1); + + const cookie2 = await cookieStore.get("cookie2"); + console.log(cookie2); +} + +cookieTest(); +``` + +### Getting cookies + +This example shows how you can get a particular cookie using {{domxref("CookieStore.get()")}} or all cookies using {{domxref("CookieStore.getAll()")}}. + +The example code first sets three cookies that we'll use for demonstrating the get methods. +First it creates `cookie1` and `cookie2` using the {{domxref("CookieStore.set()")}} method. +Then it creates a third cookie using the older synchronous {{domxref("Document.cookie")}} property (just so we can show that these are also fetched using the `get()` and `getAll()` methods). + +The code then uses {{domxref("CookieStore.get()")}} to fetch "cookie1" and log its properties, and {{domxref("CookieStore.getAll()")}} (without arguments) to fetch all cookies in the current context. + +```js +async function cookieTest() { + // Set a cookie passing name and value + try { + await cookieStore.set("cookie1", "cookie1-value"); + } catch (error) { + console.log(`Error setting cookie1: ${error}`); + } + + // Set a cookie passing an options object + const day = 24 * 60 * 60 * 1000; + try { + await cookieStore.set({ + name: "cookie2", + value: `cookie2-value`, + expires: Date.now() + day, + partitioned: true, + }); + } catch (error) { + console.log(`Error setting cookie2: ${error}`); + } + + // Set cookie using document.cookie + // (to demonstrate these are are fetched too) + document.cookie = "favorite_food=tripe; SameSite=None; Secure"; + + // Get named cookie and log properties + const cookie1 = await cookieStore.get("cookie1"); + console.log(cookie1); + + // Get all cookies and log each + const cookies = await cookieStore.getAll(); + if (cookies.length > 0) { + console.log(`getAll(): ${cookies.length}:`); + cookies.forEach((cookie) => console.log(cookie)); + } else { + console.log("Cookies not found"); + } +} + +cookieTest(); +``` + +The example should log "cookie1" and all three cookies separately. +One thing to note is that the cookie created using {{domxref("Document.cookie")}} may have a different path than those created using {{domxref("CookieStore.set()","set()")}} (which defaults to `/`). + +### Delete a named cookie + +This example shows how to delete a named cookie using the {{domxref("CookieStore.delete()","delete()")}} method. + +The code first sets two cookies and logs them to the console. +We then delete one of the cookies, and then list all cookies again. +The deleted cookie ("cookie1") is present in the first log array, and not in the second. + +```js +async function cookieTest() { + // Set two cookies + try { + await cookieStore.set("cookie1", "cookie1-value"); + } catch (error) { + console.log(`Error setting cookie1: ${error}`); + } + + try { + await cookieStore.set("cookie2", "cookie2-value"); + } catch (error) { + console.log(`Error setting cookie2: ${error}`); + } + + // Log cookie names + let cookieNames = (await cookieStore.getAll()) + .map((cookie) => cookie.name) + .join(" "); + console.log(`Initial cookies: ${cookieNames}`); + + // Delete cookie1 + await cookieStore.delete("cookie1"); + + // Log cookies again (to show cookie1 deleted) + cookieNames = (await cookieStore.getAll()) + .map((cookie) => cookie.name) + .join(" "); + console.log( + `Cookies remaining after attempted deletions (cookie1 should be deleted): ${cookieNames}`, ); +} + +cookieTest(); ``` ## Specifications diff --git a/files/en-us/web/api/cookiestore/set/index.md b/files/en-us/web/api/cookiestore/set/index.md index f6aae4b484e5128..7b50f2646a1bf6e 100644 --- a/files/en-us/web/api/cookiestore/set/index.md +++ b/files/en-us/web/api/cookiestore/set/index.md @@ -43,19 +43,13 @@ Or - `path` {{Optional_Inline}} - : A string containing the path of the cookie. Defaults to `/`. - `sameSite` {{Optional_Inline}} - - - : One of the following [`SameSite`](/en-US/docs/Web/HTTP/Headers/Set-Cookie#samesitesamesite-value) values: - - - `"strict"` - - : Cookies will only be sent in a first-party context and not be sent along with requests initiated by third party websites. This is the default. - - `"lax"` - - : Cookies are not sent on normal cross-site subrequests (for example to load images or frames into a third party site), but are sent when a user is navigating to the origin site (i.e. when following a link). - - `"none"` - - : Cookies will be sent in all contexts. - + - : One of the following [`SameSite`](/en-US/docs/Web/HTTP/Reference/Headers/Set-Cookie#samesitesamesite-value) values: [`"strict"`](/en-US/docs/Web/HTTP/Reference/Headers/Set-Cookie#strict), [`"lax"`](/en-US/docs/Web/HTTP/Reference/Headers/Set-Cookie#lax), or [`"none"`](/en-US/docs/Web/HTTP/Reference/Headers/Set-Cookie#none). - `value` - : A string with the value of the cookie. +> [!NOTE] +> While the values can be set here and will be used internally, some browsers will only return `name` and `value` options from {{domxref("CookieStore.get()")}} and {{domxref("CookieStore.getAll()")}}. + ### Return value A {{jsxref("Promise")}} that resolves with {{jsxref("undefined")}} when setting the cookie completes. @@ -69,17 +63,59 @@ A {{jsxref("Promise")}} that resolves with {{jsxref("undefined")}} when setting ## Examples -The following example sets a cookie by passing an object with `name`, `value`, `expires`, and `domain`. +<!-- The examples don't work as live examples in MDN environment (due to unknown errors) --> + +### Setting a cookie with name and value + +This example sets a cookie by passing a `name` and `value` of "cookie1" and "cookie1-value", respectively. +The other properties of the cookie are set with default values, as defined in the [`options`](#options) parameter. + +The code first waits for the cookie to be set: as this operation can fail, the operation is performed in a `try...catch` block and any errors are logged to the console. +It then gets and logs the cookie that was just set. + +```js +async function cookieTest() { + // Set cookie: passing name and value + try { + await cookieStore.set("cookie1", "cookie1-value"); + } catch (error) { + console.log(`Error setting cookie1: ${error}`); + } + + // Get the cookie and log its values + const cookie = await cookieStore.get("cookie1"); + console.log(cookie); +} +``` + +### Setting a cookie with options + +This example sets a cookie by passing an `options` object with `name`, `value`, `expires`, and `partitioned`. + +The code first waits for the cookie to be set: as this operation can fail, the operation is performed in a `try...catch` block and any errors are logged to the console. +It then gets and logs the cookie that was just set. ```js -const day = 24 * 60 * 60 * 1000; - -cookieStore.set({ - name: "cookie1", - value: "cookie1-value", - expires: Date.now() + day, - domain: "example.com", -}); +async function cookieTest() { + const day = 24 * 60 * 60 * 1000; + const cookieName = "cookie2"; + try { + // Set cookie: passing options + await cookieStore.set({ + name: cookieName, + value: `${cookieName}-value`, + expires: Date.now() + day, + partitioned: true, + }); + } catch (error) { + log(`Error setting ${cookieName}: ${error}`); + console.log(error); + } + + // Log the new cookie + const cookie = await cookieStore.get(cookieName); + console.log(cookie); +} ``` ## Specifications diff --git a/files/en-us/web/api/createmonitor/downloadprogress_event/index.md b/files/en-us/web/api/createmonitor/downloadprogress_event/index.md new file mode 100644 index 000000000000000..f4afcf2148cf576 --- /dev/null +++ b/files/en-us/web/api/createmonitor/downloadprogress_event/index.md @@ -0,0 +1,46 @@ +--- +title: "CreateMonitor: downloadprogress event" +short-title: downloadprogress +slug: Web/API/CreateMonitor/downloadprogress_event +page-type: web-api-event +status: + - experimental +browser-compat: api.CreateMonitor.downloadprogress_event +--- + +{{APIRef("Summarizer API")}}{{SeeCompatTable}} + +The **`downloadprogress`** event of the {{domxref("CreateMonitor")}} interface is fired when progress is made on the AI model download. + +## Syntax + +Use the event name in methods like {{domxref("EventTarget.addEventListener", "addEventListener()")}}, or set an event handler property. + +```js-nolint +addEventListener("downloadprogress", (event) => { }) + +ondownloadprogress = (event) => { } +``` + +## Event type + +A {{domxref("ProgressEvent")}}. Inherits from {{domxref("Event")}}. + +{{InheritanceDiagram("ProgressEvent")}} + +## Examples + +See the main {{domxref("CreateMonitor")}} page for an example. + +## Specifications + +{{Specifications}} + +## Browser compatibility + +{{Compat}} + +## See also + +- [Using the Summarizer API](/en-US/docs/Web/API/Summarizer_API/Using) +- [Web AI demos](https://chrome.dev/web-ai-demos/) on chrome.dev. diff --git a/files/en-us/web/api/createmonitor/index.md b/files/en-us/web/api/createmonitor/index.md new file mode 100644 index 000000000000000..36fcac20d8df4c4 --- /dev/null +++ b/files/en-us/web/api/createmonitor/index.md @@ -0,0 +1,60 @@ +--- +title: CreateMonitor +slug: Web/API/CreateMonitor +page-type: web-api-interface +status: + - experimental +browser-compat: api.CreateMonitor +--- + +{{APIRef("Summarizer API")}}{{SeeCompatTable}} + +The **`CreateMonitor`** interface provides information on the progress of an AI model download or some fine-tuning data for the model. + +It can be used via: + +- {{domxref("Summarizer.create_static", "Summarizer.create()")}} +- {{domxref("LanguageDetector.create_static", "LanguageDetector.create()")}} +- {{domxref("Translator.create_static", "Translator.create()")}} + +{{InheritanceDiagram}} + +## Events + +_Inherits events from its parent, {{DOMxRef("EventTarget")}}._ + +- {{domxref("CreateMonitor/downloadprogress_event", "downloadprogress")}} {{Experimental_Inline}} + - : Fired when progress is made on the AI model download. + +## Examples + +### Basic `CreateMonitor` usage + +A `CreateMonitor` instance is used via the `monitor` property of an AI API's `create()` method ({{domxref("Summarizer.create_static", "Summarizer.create()")}} is shown below). The `monitor` property takes a callback function as a value, the argument of which is the `CreateMonitor` instance. You can then monitor download progress via the instance's {{domxref("CreateMonitor/downloadprogress_event", "downloadprogress")}} event. + +```js +const summarizer = await Summarizer.create({ + sharedContext: + "A general summary to help a user decide if the text is worth reading", + monitor(monitor) { + monitor.addEventListener("downloadprogress", (e) => { + console.log(`download progress: ${e.loaded}/${e.total}`); + }); + }, +}); + +const summary = await summarizer.summarize(myText); +``` + +## Specifications + +{{Specifications}} + +## Browser compatibility + +{{Compat}} + +## See also + +- [Using the Summarizer API](/en-US/docs/Web/API/Summarizer_API/Using) +- [Web AI demos](https://chrome.dev/web-ai-demos/) on chrome.dev. diff --git a/files/en-us/web/api/credential_management_api/credential_types/index.md b/files/en-us/web/api/credential_management_api/credential_types/index.md index db1621be3988d98..8a01fbe54084547 100644 --- a/files/en-us/web/api/credential_management_api/credential_types/index.md +++ b/files/en-us/web/api/credential_management_api/credential_types/index.md @@ -32,7 +32,7 @@ In this guide we'll introduce the different credential types and explain at a hi ## Passwords > [!NOTE] -> Most browsers do not support this credential type and it is not widely used on the web. Instead, browsers automatically offer to store passwords in a password manager, and can automatically retrieve stored passwords to autofill [password input elements](/en-US/docs/Web/HTML/Element/input/password). +> Most browsers do not support this credential type and it is not widely used on the web. Instead, browsers automatically offer to store passwords in a password manager, and can automatically retrieve stored passwords to autofill [password input elements](/en-US/docs/Web/HTML/Reference/Elements/input/password). Modern browsers provide users with a password manager, which enables users to store the passwords they enter on websites, and later retrieve them when they need to log in again. Password managers can help with password security by remembering passwords for users and autofilling them, which allows users to choose stronger passwords. diff --git a/files/en-us/web/api/credentialscontainer/create/index.md b/files/en-us/web/api/credentialscontainer/create/index.md index 648e9343bf67358..af49fefe3644e00 100644 --- a/files/en-us/web/api/credentialscontainer/create/index.md +++ b/files/en-us/web/api/credentialscontainer/create/index.md @@ -45,7 +45,7 @@ create(options) - : A {{domxref("PublicKeyCredentialCreationOptions")}} object containing requirements for creating a public key credential. Causes the `create()` call to request that the user agent creates new credentials via an authenticator — either for registering a new account or for associating a new asymmetric key pair with an existing account. > [!NOTE] - > Usage of `create()` with the `publicKey` parameter may be blocked by a {{HTTPHeader("Permissions-Policy/publickey-credentials-create","publickey-credentials-create")}} [Permissions Policy](/en-US/docs/Web/HTTP/Permissions_Policy) set on your server. + > Usage of `create()` with the `publicKey` parameter may be blocked by a {{HTTPHeader("Permissions-Policy/publickey-credentials-create","publickey-credentials-create")}} [Permissions Policy](/en-US/docs/Web/HTTP/Guides/Permissions_Policy) set on your server. ### Return value @@ -63,8 +63,8 @@ If no credential object can be created, the promise resolves with `null`. - : In the case of a {{domxref("PasswordCredential")}} creation request, `id`, `origin`, or `password` were not provided (empty). - `NotAllowedError` {{domxref("DOMException")}} - : Possible causes include: - - Usage was blocked by a {{HTTPHeader("Permissions-Policy/publickey-credentials-create","publickey-credentials-create")}} [Permissions Policy](/en-US/docs/Web/HTTP/Permissions_Policy). - - The function is called cross-origin but the iframe's [`allow`](/en-US/docs/Web/HTML/Element/iframe#allow) attribute does not set an appropriate {{HTTPHeader("Permissions-Policy/publickey-credentials-create","publickey-credentials-create")}} policy. + - Usage was blocked by a {{HTTPHeader("Permissions-Policy/publickey-credentials-create","publickey-credentials-create")}} [Permissions Policy](/en-US/docs/Web/HTTP/Guides/Permissions_Policy). + - The function is called cross-origin but the iframe's [`allow`](/en-US/docs/Web/HTML/Reference/Elements/iframe#allow) attribute does not set an appropriate {{HTTPHeader("Permissions-Policy/publickey-credentials-create","publickey-credentials-create")}} policy. - The function is called cross-origin and the `<iframe>` does not have {{glossary("transient activation")}}. - An attempt is made to create a [discoverable credential](/en-US/docs/Web/API/Web_Authentication_API#discoverable_credentials_and_conditional_mediation) ([`residentKey`](/en-US/docs/Web/API/PublicKeyCredentialCreationOptions#residentkey) is set to `required` in the `create()` call's {{domxref("PublicKeyCredentialCreationOptions")}} option), but the user does not have a security key that supports discoverable credentials, and cancels the operation. - `AbortError` {{domxref("DOMException")}} diff --git a/files/en-us/web/api/credentialscontainer/get/index.md b/files/en-us/web/api/credentialscontainer/get/index.md index 15bbcc8e26631d2..b42c75a4a7816df 100644 --- a/files/en-us/web/api/credentialscontainer/get/index.md +++ b/files/en-us/web/api/credentialscontainer/get/index.md @@ -128,13 +128,13 @@ If a single credential cannot be unambiguously obtained, the promise resolves wi - The user canceled the request. - - Use of this API was blocked by one of the following [permissions policies](/en-US/docs/Web/HTTP/Permissions_Policy): + - Use of this API was blocked by one of the following [permissions policies](/en-US/docs/Web/HTTP/Guides/Permissions_Policy): - {{HTTPHeader("Permissions-Policy/identity-credentials-get","identity-credentials-get")}} - {{HTTPHeader("Permissions-Policy/publickey-credentials-get","publickey-credentials-get")}} - {{HTTPHeader("Permissions-Policy/otp-credentials","otp-credentials")}} - - The calling origin is an [opaque origin](/en-US/docs/Web/HTTP/Headers/Origin#null). + - The calling origin is an [opaque origin](/en-US/docs/Web/HTTP/Reference/Headers/Origin#null). - `SecurityError` {{domxref("DOMException")}} @@ -214,16 +214,18 @@ The following snippet shows a typical `get()` call with the WebAuthn `publicKey` ```js const publicKey = { - challenge: new Uint8Array([139, 66, 181, 87, 7, 203, ...]), + challenge: new Uint8Array([139, 66, 181, 87, 7, 203 /* ,… */]), rpId: "acme.com", - allowCredentials: [{ - type: "public-key", - id: new Uint8Array([64, 66, 25, 78, 168, 226, 174, ...]) - }], + allowCredentials: [ + { + type: "public-key", + id: new Uint8Array([64, 66, 25, 78, 168, 226, 174 /* ,… */]), + }, + ], userVerification: "required", -} +}; -navigator.credentials.get({ publicKey }) +navigator.credentials.get({ publicKey }); ``` A successful `get()` call returns a promise that resolves with a {{domxref("PublicKeyCredential")}} object instance, representing a public key credential previously created via a WebAuthn {{domxref("CredentialsContainer.create()", "create()")}} that has now been used to authenticate a user. Its {{domxref("PublicKeyCredential.response")}} property contains an {{domxref("AuthenticatorAssertionResponse")}} object providing access to several useful pieces of information including the authenticator data, signature, and user handle. diff --git a/files/en-us/web/api/credentialscontainer/preventsilentaccess/index.md b/files/en-us/web/api/credentialscontainer/preventsilentaccess/index.md index 459577f90097116..efecd13a1fae6d7 100644 --- a/files/en-us/web/api/credentialscontainer/preventsilentaccess/index.md +++ b/files/en-us/web/api/credentialscontainer/preventsilentaccess/index.md @@ -12,7 +12,7 @@ The **`preventSilentAccess()`** method of the {{domxref("CredentialsContainer")} For example, you might call this, after a user signs out of a website to ensure that they aren't automatically signed in on the next site visit. Mediation varies by origin, and is an added check point of browser stored credentials, informing a user of an account login status. This method is typically called after a user signs out of a website, ensuring this user's login information is not automatically passed on the next site visit. -This method [generally has no effect](https://www.w3.org/TR/webauthn-2/#sctn-preventSilentAccessCredential) when using a {{domxref("PublicKeyCredential")}}; such authenticators typically require user interaction. However, it _is possible_ that certain authenticators may be excluded, which could otherwise have operated silently. +When using a {{domxref("PublicKeyCredential")}}, this method generally has no effect; such authenticators typically require user interaction. However, it _is possible_ that certain authenticators may be excluded, which could otherwise have operated silently. Earlier versions of the spec called this method `requireUserMediation()`. The [Browser compatibility](/en-US/docs/Web/API/CredentialsContainer#browser_compatibility) section has support details. diff --git a/files/en-us/web/api/crypto/getrandomvalues/index.md b/files/en-us/web/api/crypto/getrandomvalues/index.md index 01d4b229a8a2aa5..ade377c7a0ee336 100644 --- a/files/en-us/web/api/crypto/getrandomvalues/index.md +++ b/files/en-us/web/api/crypto/getrandomvalues/index.md @@ -28,7 +28,7 @@ getRandomValues(typedArray) - : An integer-based {{jsxref("TypedArray")}}, that is one of: {{jsxref("Int8Array")}}, {{jsxref("Uint8Array")}}, {{jsxref("Uint8ClampedArray")}}, {{jsxref("Int16Array")}}, {{jsxref("Uint16Array")}}, {{jsxref("Int32Array")}}, {{jsxref("Uint32Array")}}, {{jsxref("BigInt64Array")}}, - {{jsxref("BigUint64Array")}} (but **not** `Float32Array` nor `Float64Array`). + {{jsxref("BigUint64Array")}} (but **not** `Float16Array`, `Float32Array` nor `Float64Array`). All elements in the array will be overwritten with random numbers. ### Return value diff --git a/files/en-us/web/api/crypto/index.md b/files/en-us/web/api/crypto/index.md index 586aa02128758aa..c1890e9a1831972 100644 --- a/files/en-us/web/api/crypto/index.md +++ b/files/en-us/web/api/crypto/index.md @@ -42,4 +42,4 @@ _This interface implements methods defined on {{domxref("Crypto/getRandomValues" - [Secure contexts](/en-US/docs/Web/Security/Secure_Contexts) - [Features restricted to secure contexts](/en-US/docs/Web/Security/Secure_Contexts/features_restricted_to_secure_contexts) - [Transport Layer Security](/en-US/docs/Web/Security/Transport_Layer_Security) -- [Strict-Transport-Security](/en-US/docs/Web/HTTP/Headers/Strict-Transport-Security) +- [Strict-Transport-Security](/en-US/docs/Web/HTTP/Reference/Headers/Strict-Transport-Security) diff --git a/files/en-us/web/api/cspviolationreportbody/blockedurl/index.md b/files/en-us/web/api/cspviolationreportbody/blockedurl/index.md index d4962c7f6ca1e87..9d5052175705beb 100644 --- a/files/en-us/web/api/cspviolationreportbody/blockedurl/index.md +++ b/files/en-us/web/api/cspviolationreportbody/blockedurl/index.md @@ -8,7 +8,7 @@ browser-compat: api.CSPViolationReportBody.blockedURL {{APIRef("Reporting API")}} -The **`blockedURL`** read-only property of the {{domxref("CSPViolationReportBody")}} interface is a string value that represents the resource that was blocked because it violates a [Content Security Policy (CSP)](/en-US/docs/Web/HTTP/CSP). +The **`blockedURL`** read-only property of the {{domxref("CSPViolationReportBody")}} interface is a string value that represents the resource that was blocked because it violates a [Content Security Policy (CSP)](/en-US/docs/Web/HTTP/Guides/CSP). ## Value @@ -18,18 +18,18 @@ If the value is not the URL of a resource, it must be one of the following strin - `inline` - : An inline resource. - For example, an inline script that was used when [`'unsafe-inline'`](/en-US/docs/Web/HTTP/Headers/Content-Security-Policy#unsafe-inline) was not specified in the CSP. + For example, an inline script that was used when [`'unsafe-inline'`](/en-US/docs/Web/HTTP/Reference/Headers/Content-Security-Policy#unsafe-inline) was not specified in the CSP. - `eval` - : An `eval()`. - For example, `eval()` was used but [`'unsafe-eval'`](/en-US/docs/Web/HTTP/Headers/Content-Security-Policy#unsafe-eval) was not specified in the CSP. + For example, `eval()` was used but [`'unsafe-eval'`](/en-US/docs/Web/HTTP/Reference/Headers/Content-Security-Policy#unsafe-eval) was not specified in the CSP. - `wasm-eval` - : An Wasm evaluation. - For example, `eval()` was used but [`'wasm-unsafe-eval'`](/en-US/docs/Web/HTTP/Headers/Content-Security-Policy#wasm-unsafe-eval) was not specified in the CSP. + For example, `eval()` was used but [`'wasm-unsafe-eval'`](/en-US/docs/Web/HTTP/Reference/Headers/Content-Security-Policy#wasm-unsafe-eval) was not specified in the CSP. - `trusted-types-policy` - - : A resource that violated the [`trusted-types`](/en-US/docs/Web/HTTP/Headers/Content-Security-Policy/trusted-types) CSP directive. + - : A resource that violated the [`trusted-types`](/en-US/docs/Web/HTTP/Reference/Headers/Content-Security-Policy/trusted-types) CSP directive. For example, a {{domxref("TrustedTypePolicy")}} was created using {{domxref("TrustedTypePolicyFactory/createPolicy", "window.trustedTypes.createPolicy()")}} with a name that wasn't listed in the CSP `trusted-types` directive. - `trusted-types-sink` - - : A resource that violated the [`require-trusted-types-for`](/en-US/docs/Web/HTTP/Headers/Content-Security-Policy/trusted-types) CSP directive. + - : A resource that violated the [`require-trusted-types-for`](/en-US/docs/Web/HTTP/Reference/Headers/Content-Security-Policy/trusted-types) CSP directive. For example, the directive was set to `script` but the document did not use a {{domxref("TrustedTypePolicy")}} to sanitize data before passing it to a sink such as {{domxref("Element.innerHTML")}}. ## Examples @@ -126,10 +126,8 @@ The policy also uses the `trusted-types` directive to specify that a {{domxref(" <script> const policy = trustedTypes.createPolicy("somePolicy", { - createHTML: (string) => { - // Some (insufficient) sanitization code - return string.replace(/</g, "&lt;"); - }, + // Some (insufficient) sanitization code + createHTML: (string) => string.replace(/</g, "&lt;"), }); </script> </html> @@ -193,10 +191,8 @@ In order to avoid the violation we would need to update the script to define a t ```js const policy = trustedTypes.createPolicy("myPolicy", { - createHTML: (string) => { - // Some (insufficient) sanitization code - return string.replace(/</g, "&lt;"); - }, + // Some (insufficient) sanitization code + createHTML: (string) => string.replace(/</g, "&lt;"), }); function updateContent() { diff --git a/files/en-us/web/api/cspviolationreportbody/columnnumber/index.md b/files/en-us/web/api/cspviolationreportbody/columnnumber/index.md index 5eb4e7c9dc59ce9..eefc9d3e4fd086d 100644 --- a/files/en-us/web/api/cspviolationreportbody/columnnumber/index.md +++ b/files/en-us/web/api/cspviolationreportbody/columnnumber/index.md @@ -8,7 +8,7 @@ browser-compat: api.CSPViolationReportBody.columnNumber {{APIRef("Reporting API")}} -The **`columnNumber`** read-only property of the {{domxref("CSPViolationReportBody")}} interface indicates the column number in the source file that triggered the [Content Security Policy (CSP)](/en-US/docs/Web/HTTP/CSP) violation. +The **`columnNumber`** read-only property of the {{domxref("CSPViolationReportBody")}} interface indicates the column number in the source file that triggered the [Content Security Policy (CSP)](/en-US/docs/Web/HTTP/Guides/CSP) violation. Note that the browser extracts the value from _the global object_ of the file that triggered the violation. If the resource that triggers the CSP violation is not loaded, the value will be `null`. @@ -28,7 +28,7 @@ This example triggers a CSP violation using an inline script, and reports the vi #### HTML -The HTML file below uses the [`<meta>`](/en-US/docs/Web/HTML/Element/meta) element to set the {{httpheader('Content-Security-Policy')}} `default-src` to `self`, which allows scripts and other resources to be loaded from the same origin, but does not allow inline scripts to be executed. +The HTML file below uses the [`<meta>`](/en-US/docs/Web/HTML/Reference/Elements/meta) element to set the {{httpheader('Content-Security-Policy')}} `default-src` to `self`, which allows scripts and other resources to be loaded from the same origin, but does not allow inline scripts to be executed. The document also includes an inline script, which should therefore trigger a CSP violation. ```html diff --git a/files/en-us/web/api/cspviolationreportbody/disposition/index.md b/files/en-us/web/api/cspviolationreportbody/disposition/index.md index a63af141c75a9f7..616d9157158d5f9 100644 --- a/files/en-us/web/api/cspviolationreportbody/disposition/index.md +++ b/files/en-us/web/api/cspviolationreportbody/disposition/index.md @@ -8,7 +8,7 @@ browser-compat: api.CSPViolationReportBody.disposition {{APIRef("Reporting API")}} -The **`disposition`** read-only property of the {{domxref("CSPViolationReportBody")}} interface indicates whether the user agent is configured to enforce [Content Security Policy (CSP)](/en-US/docs/Web/HTTP/CSP) violations or only report them. +The **`disposition`** read-only property of the {{domxref("CSPViolationReportBody")}} interface indicates whether the user agent is configured to enforce [Content Security Policy (CSP)](/en-US/docs/Web/HTTP/Guides/CSP) violations or only report them. ## Value @@ -28,7 +28,7 @@ The `disposition` is logged. #### HTML -The HTML file below uses the [`<meta>`](/en-US/docs/Web/HTML/Element/meta) element to set the {{httpheader('Content-Security-Policy')}} `default-src` to `self`, which allows scripts and other resources to be loaded from the same domain, but does not allow inline scripts to be executed. +The HTML file below uses the [`<meta>`](/en-US/docs/Web/HTML/Reference/Elements/meta) element to set the {{httpheader('Content-Security-Policy')}} `default-src` to `self`, which allows scripts and other resources to be loaded from the same domain, but does not allow inline scripts to be executed. The document also includes an inline script, which should therefore trigger a CSP violation. ```html diff --git a/files/en-us/web/api/cspviolationreportbody/documenturl/index.md b/files/en-us/web/api/cspviolationreportbody/documenturl/index.md index 298e2c87221bbf1..581b961f4cff446 100644 --- a/files/en-us/web/api/cspviolationreportbody/documenturl/index.md +++ b/files/en-us/web/api/cspviolationreportbody/documenturl/index.md @@ -8,7 +8,7 @@ browser-compat: api.CSPViolationReportBody.documentURL {{APIRef("Reporting API")}} -The **`documentURL`** read-only property of the {{domxref("CSPViolationReportBody")}} interface is a string that represents the URL of the document or worker that violated the [Content Security Policy (CSP)](/en-US/docs/Web/HTTP/CSP). +The **`documentURL`** read-only property of the {{domxref("CSPViolationReportBody")}} interface is a string that represents the URL of the document or worker that violated the [Content Security Policy (CSP)](/en-US/docs/Web/HTTP/Guides/CSP). ## Value @@ -42,7 +42,7 @@ This page just contains a link to another page `../report_sample/index.html`. ``` The `../report_sample/index.html` HTML file is defined below. -This uses the [`<meta>`](/en-US/docs/Web/HTML/Element/meta) element to set the {{httpheader('Content-Security-Policy')}} `script-src-elem` to `self`, which allows scripts to be loaded from the same domain, but does not allow inline scripts to be executed. +This uses the [`<meta>`](/en-US/docs/Web/HTML/Reference/Elements/meta) element to set the {{httpheader('Content-Security-Policy')}} `script-src-elem` to `self`, which allows scripts to be loaded from the same domain, but does not allow inline scripts to be executed. The document also includes an inline script, which will trigger a CSP violation. ```html diff --git a/files/en-us/web/api/cspviolationreportbody/effectivedirective/index.md b/files/en-us/web/api/cspviolationreportbody/effectivedirective/index.md index c33c8cdc1ec551c..49dc46d6b644748 100644 --- a/files/en-us/web/api/cspviolationreportbody/effectivedirective/index.md +++ b/files/en-us/web/api/cspviolationreportbody/effectivedirective/index.md @@ -8,13 +8,13 @@ browser-compat: api.CSPViolationReportBody.effectiveDirective {{APIRef("Reporting API")}} -The **`effectiveDirective`** read-only property of the {{domxref("CSPViolationReportBody")}} interface is a string that represents the effective [Content Security Policy (CSP)](/en-US/docs/Web/HTTP/CSP) directive that was violated. +The **`effectiveDirective`** read-only property of the {{domxref("CSPViolationReportBody")}} interface is a string that represents the effective [Content Security Policy (CSP)](/en-US/docs/Web/HTTP/Guides/CSP) directive that was violated. -Note that this contains the specific directive that was effectively violated, such as [`script-src-elem`](/en-US/docs/Web/HTTP/Headers/Content-Security-Policy/script-src-elem) for violations related to script elements, and not the policy that was specified, which may have been the (more general) [`default-src`](/en-US/docs/Web/HTTP/Headers/Content-Security-Policy/default-src). +Note that this contains the specific directive that was effectively violated, such as [`script-src-elem`](/en-US/docs/Web/HTTP/Reference/Headers/Content-Security-Policy/script-src-elem) for violations related to script elements, and not the policy that was specified, which may have been the (more general) [`default-src`](/en-US/docs/Web/HTTP/Reference/Headers/Content-Security-Policy/default-src). ## Value -A string representing the effective [`Content-Security-Policy` directive](/en-US/docs/Web/HTTP/Headers/Content-Security-Policy#directives) that was violated. +A string representing the effective [`Content-Security-Policy` directive](/en-US/docs/Web/HTTP/Reference/Headers/Content-Security-Policy#directives) that was violated. ## Examples @@ -25,7 +25,7 @@ In particular, it logs the `effectiveDirective` and the `originalPolicy`, making #### HTML -The HTML file below uses the [`<meta>`](/en-US/docs/Web/HTML/Element/meta) element to set the {{httpheader('Content-Security-Policy')}} `default-src` to `self`, which allows scripts and other resources to be loaded from the same domain, but does not allow inline scripts to be executed. +The HTML file below uses the [`<meta>`](/en-US/docs/Web/HTML/Reference/Elements/meta) element to set the {{httpheader('Content-Security-Policy')}} `default-src` to `self`, which allows scripts and other resources to be loaded from the same domain, but does not allow inline scripts to be executed. The document also includes an inline script, which should trigger a CSP violation. ```html diff --git a/files/en-us/web/api/cspviolationreportbody/index.md b/files/en-us/web/api/cspviolationreportbody/index.md index b3919a74b631e36..47ef8471aac6178 100644 --- a/files/en-us/web/api/cspviolationreportbody/index.md +++ b/files/en-us/web/api/cspviolationreportbody/index.md @@ -14,11 +14,11 @@ CSP violations are thrown when the webpage attempts to load a resource that viol CSP violation reports are returned in the [reports](/en-US/docs/Web/API/ReportingObserver/ReportingObserver#reports) parameter of {{domxref("ReportingObserver")}} callbacks that have a `type` of `"csp-violation"`. The `body` property of those reports is an instance of `CSPViolationReportBody`. -CSP violation reports may also be sent as JSON objects to the endpoint specified in the [`report-to`](/en-US/docs/Web/HTTP/Headers/Content-Security-Policy/report-to) policy directive of the {{HTTPHeader("Content-Security-Policy")}} header. +CSP violation reports may also be sent as JSON objects to the endpoint specified in the [`report-to`](/en-US/docs/Web/HTTP/Reference/Headers/Content-Security-Policy/report-to) policy directive of the {{HTTPHeader("Content-Security-Policy")}} header. These reports similarly have a `type` of `"csp-violation"`, and a `body` property containing a serialization of an instance of this interface. > [!NOTE] -> CSP violation reports sent by the Reporting API, when an endpoint is specified using the CSP [`report-to`](/en-US/docs/Web/HTTP/Headers/Content-Security-Policy/report-to) directive, are similar (but not identical) to the "CSP report" [JSON objects](/en-US/docs/Web/HTTP/Headers/Content-Security-Policy/report-uri#violation_report_syntax) sent when endpoints are specified using the [`report-uri`](/en-US/docs/Web/HTTP/Headers/Content-Security-Policy/report-uri) directive. +> CSP violation reports sent by the Reporting API, when an endpoint is specified using the CSP [`report-to`](/en-US/docs/Web/HTTP/Reference/Headers/Content-Security-Policy/report-to) directive, are similar (but not identical) to the "CSP report" [JSON objects](/en-US/docs/Web/HTTP/Reference/Headers/Content-Security-Policy/report-uri#violation_report_syntax) sent when endpoints are specified using the [`report-uri`](/en-US/docs/Web/HTTP/Reference/Headers/Content-Security-Policy/report-uri) directive. > The Reporting API and `report-to` directive are intended to replace the older report format and the `report-uri` directive. {{InheritanceDiagram}} @@ -70,7 +70,7 @@ First, we will set our {{HTTPHeader("Content-Security-Policy")}} header in the H Content-Security-Policy: default-src 'self'; ``` -or in the HTML [`<meta>`](/en-US/docs/Web/HTML/Element/meta) element: +or in the HTML [`<meta>`](/en-US/docs/Web/HTML/Reference/Elements/meta) element: ```html <meta http-equiv="Content-Security-Policy" content="default-src 'self'" /> @@ -105,23 +105,23 @@ observer.observe(); Above we log the each violation report object and a JSON-string version of the object, which might look similar to the object below. Note that the `body` is an instance of the `CSPViolationReportBody` and the `type` is `"csp-violation"`. -```js +```json { - "type": "csp-violation", - "url": "http://127.0.0.1:9999/", - "body": { - "sourceFile": null, - "lineNumber": null, - "columnNumber": null, - "documentURL": "http://127.0.0.1:9999/", - "referrer": "", - "blockedURL": "https://apis.google.com/js/platform.js", - "effectiveDirective": "script-src-elem", - "originalPolicy": "default-src 'self';", - "sample": "", - "disposition": "enforce", - "statusCode": 200 - } + "type": "csp-violation", + "url": "http://127.0.0.1:9999/", + "body": { + "sourceFile": null, + "lineNumber": null, + "columnNumber": null, + "documentURL": "http://127.0.0.1:9999/", + "referrer": "", + "blockedURL": "https://apis.google.com/js/platform.js", + "effectiveDirective": "script-src-elem", + "originalPolicy": "default-src 'self';", + "sample": "", + "disposition": "enforce", + "statusCode": 200 + } } ``` diff --git a/files/en-us/web/api/cspviolationreportbody/linenumber/index.md b/files/en-us/web/api/cspviolationreportbody/linenumber/index.md index f8fb04d1e4d8e29..5ad71b84f9061a5 100644 --- a/files/en-us/web/api/cspviolationreportbody/linenumber/index.md +++ b/files/en-us/web/api/cspviolationreportbody/linenumber/index.md @@ -8,7 +8,7 @@ browser-compat: api.CSPViolationReportBody.lineNumber {{APIRef("Reporting API")}} -The **`lineNumber`** read-only property of the {{domxref("CSPViolationReportBody")}} interface indicates the line number in the source file that triggered the [Content Security Policy (CSP)](/en-US/docs/Web/HTTP/CSP) violation. +The **`lineNumber`** read-only property of the {{domxref("CSPViolationReportBody")}} interface indicates the line number in the source file that triggered the [Content Security Policy (CSP)](/en-US/docs/Web/HTTP/Guides/CSP) violation. Note that the browser extracts the value from _the global object_ of the file that triggered the violation. If the resource that triggers the CSP violation is not loaded, the value will be `null`. @@ -28,7 +28,7 @@ This example triggers a CSP violation using an inline script, and reports the vi #### HTML -The HTML file below uses the [`<meta>`](/en-US/docs/Web/HTML/Element/meta) element to set the {{httpheader('Content-Security-Policy')}} `default-src` to `self`, which allows scripts and other resources to be loaded from the same origin, but does not allow inline scripts to be executed. +The HTML file below uses the [`<meta>`](/en-US/docs/Web/HTML/Reference/Elements/meta) element to set the {{httpheader('Content-Security-Policy')}} `default-src` to `self`, which allows scripts and other resources to be loaded from the same origin, but does not allow inline scripts to be executed. The document also includes an inline script, which should therefore trigger a CSP violation. ```html diff --git a/files/en-us/web/api/cspviolationreportbody/originalpolicy/index.md b/files/en-us/web/api/cspviolationreportbody/originalpolicy/index.md index 2994349b060e66c..accd2dc8ba04e23 100644 --- a/files/en-us/web/api/cspviolationreportbody/originalpolicy/index.md +++ b/files/en-us/web/api/cspviolationreportbody/originalpolicy/index.md @@ -8,9 +8,9 @@ browser-compat: api.CSPViolationReportBody.originalPolicy {{APIRef("Reporting API")}} -The **`originalPolicy`** read-only property of the {{domxref("CSPViolationReportBody")}} interface is a string that represents the [Content Security Policy (CSP)](/en-US/docs/Web/HTTP/CSP) whose enforcement uncovered the violation. +The **`originalPolicy`** read-only property of the {{domxref("CSPViolationReportBody")}} interface is a string that represents the [Content Security Policy (CSP)](/en-US/docs/Web/HTTP/Guides/CSP) whose enforcement uncovered the violation. -This is the string in the {{HTTPHeader("Content-Security-Policy")}} HTTP response header that contains the list of [directives](/en-US/docs/Web/HTTP/Headers/Content-Security-Policy#directives) and their values that make the CSP policy. +This is the string in the {{HTTPHeader("Content-Security-Policy")}} HTTP response header that contains the list of [directives](/en-US/docs/Web/HTTP/Reference/Headers/Content-Security-Policy#directives) and their values that make the CSP policy. Note that differs from the {{domxref("CSPViolationReportBody.effectiveDirective","effectiveDirective")}}, which is the specific directive that is effectively being violated (and which might not be explicitly listed in the policy if `default-src` is used). ## Value @@ -26,7 +26,7 @@ In particular, it logs the `effectiveDirective` and the `originalPolicy`, making #### HTML -The HTML file below uses the [`<meta>`](/en-US/docs/Web/HTML/Element/meta) element to set the {{httpheader('Content-Security-Policy')}} `default-src` to `self`, which allows scripts and other resources to be loaded from the same domain, but does not allow inline scripts to be executed. +The HTML file below uses the [`<meta>`](/en-US/docs/Web/HTML/Reference/Elements/meta) element to set the {{httpheader('Content-Security-Policy')}} `default-src` to `self`, which allows scripts and other resources to be loaded from the same domain, but does not allow inline scripts to be executed. The document also includes an inline script, which should trigger a CSP violation. ```html diff --git a/files/en-us/web/api/cspviolationreportbody/referrer/index.md b/files/en-us/web/api/cspviolationreportbody/referrer/index.md index f04a3924e4680bd..7496f5df6790449 100644 --- a/files/en-us/web/api/cspviolationreportbody/referrer/index.md +++ b/files/en-us/web/api/cspviolationreportbody/referrer/index.md @@ -8,7 +8,7 @@ browser-compat: api.CSPViolationReportBody.referrer {{APIRef("Reporting API")}} -The **`referrer`** read-only property of the {{domxref("CSPViolationReportBody")}} interface is a string that represents the URL of the referring page of the resource who's [Content Security Policy (CSP)](/en-US/docs/Web/HTTP/CSP) was violated. +The **`referrer`** read-only property of the {{domxref("CSPViolationReportBody")}} interface is a string that represents the URL of the referring page of the resource who's [Content Security Policy (CSP)](/en-US/docs/Web/HTTP/Guides/CSP) was violated. The referrer is the page that caused the page with the CSP violation to be loaded. For example, if we followed a link to a page with a CSP violation, the `referrer` is the page that we navigated from. @@ -47,7 +47,7 @@ This page just contains a link to another page `../report_sample/index.html`. ``` The `../report_sample/index.html` HTML file is defined below. -This uses the [`<meta>`](/en-US/docs/Web/HTML/Element/meta) element to set the {{httpheader('Content-Security-Policy')}} `script-src-elem` to `self`, which allows scripts to be loaded from the same domain, but does not allow inline scripts to be executed. +This uses the [`<meta>`](/en-US/docs/Web/HTML/Reference/Elements/meta) element to set the {{httpheader('Content-Security-Policy')}} `script-src-elem` to `self`, which allows scripts to be loaded from the same domain, but does not allow inline scripts to be executed. The document also includes an inline script, which will trigger a CSP violation. ```html diff --git a/files/en-us/web/api/cspviolationreportbody/sample/index.md b/files/en-us/web/api/cspviolationreportbody/sample/index.md index 8dd858e9fbc3b5f..de43193173b7683 100644 --- a/files/en-us/web/api/cspviolationreportbody/sample/index.md +++ b/files/en-us/web/api/cspviolationreportbody/sample/index.md @@ -8,15 +8,16 @@ browser-compat: api.CSPViolationReportBody.sample {{APIRef("Reporting API")}} -The **`sample`** read-only property of the {{domxref("CSPViolationReportBody")}} interface is a string that contains a part of the resource that violated the [Content Security Policy (CSP)](/en-US/docs/Web/HTTP/CSP). +The **`sample`** read-only property of the {{domxref("CSPViolationReportBody")}} interface is a string that contains a part of the resource that violated the [Content Security Policy (CSP)](/en-US/docs/Web/HTTP/Guides/CSP). This sample is usually the first 40 characters of the inline script, event handler, or style that violated a CSP restriction. If not populated it is the empty string `""`. -Note that this is only populated when attempting to load _inline_ scripts, event handlers, or styles that violate CSP [`script-src*`](/en-US/docs/Web/HTTP/Headers/Content-Security-Policy#script-src) and [`style-src*`](/en-US/docs/Web/HTTP/Headers/Content-Security-Policy#style-src) rules — external resources that violate the CSP will not generate a sample. -In addition, a sample is only included if the `Content-Security-Policy` directive that was violated also contains the [`'report-sample'`](/en-US/docs/Web/HTTP/Headers/Content-Security-Policy#report-sample) keyword. +Note that this is only populated when attempting to load _inline_ scripts, event handlers, or styles that violate CSP [`script-src*`](/en-US/docs/Web/HTTP/Reference/Headers/Content-Security-Policy/script-src) and [`style-src*`](/en-US/docs/Web/HTTP/Reference/Headers/Content-Security-Policy/style-src) rules — external resources that violate the CSP will not generate a sample. +In addition, a sample is only included if the `Content-Security-Policy` directive that was violated also contains the [`'report-sample'`](/en-US/docs/Web/HTTP/Reference/Headers/Content-Security-Policy#report-sample) keyword. -> [!NOTE] Violation reports should be considered attacker-controlled data. +> [!NOTE] +> Violation reports should be considered attacker-controlled data. > The content of this field _in particular_ should be sanitized before storing or rendering. ## Value @@ -32,7 +33,7 @@ We also add `'report-sample'` to the CSP in order to populate a `sample` in the #### HTML -The HTML file below uses the [`<meta>`](/en-US/docs/Web/HTML/Element/meta) element to set the {{httpheader('Content-Security-Policy')}} `script-src-elem` to `self`, which allows scripts to be loaded from the same domain, but does not allow inline scripts to be executed. +The HTML file below uses the [`<meta>`](/en-US/docs/Web/HTML/Reference/Elements/meta) element to set the {{httpheader('Content-Security-Policy')}} `script-src-elem` to `self`, which allows scripts to be loaded from the same domain, but does not allow inline scripts to be executed. We include `'report-sample'` in the directive so that a sample is generated. The document also includes an inline script, which should trigger a CSP violation. diff --git a/files/en-us/web/api/cspviolationreportbody/sourcefile/index.md b/files/en-us/web/api/cspviolationreportbody/sourcefile/index.md index 2aefb6f7067a0de..cdfdfa3857c313e 100644 --- a/files/en-us/web/api/cspviolationreportbody/sourcefile/index.md +++ b/files/en-us/web/api/cspviolationreportbody/sourcefile/index.md @@ -8,7 +8,7 @@ browser-compat: api.CSPViolationReportBody.sourceFile {{APIRef("Reporting API")}} -The **`sourceFile`** read-only property of the {{domxref("CSPViolationReportBody")}} interface indicates the URL of the source file that violated the [Content Security Policy (CSP)](/en-US/docs/Web/HTTP/CSP). +The **`sourceFile`** read-only property of the {{domxref("CSPViolationReportBody")}} interface indicates the URL of the source file that violated the [Content Security Policy (CSP)](/en-US/docs/Web/HTTP/Guides/CSP). For a violation triggered by the use of an inline script, `sourceFile` is the URL of the current document. Similarly, if a document successfully loads a script that then violates the document CSP, the `sourceFile` is the URL of the script. @@ -31,7 +31,7 @@ This example triggers a CSP violation using an inline script, and reports the vi #### HTML -The HTML file below uses the [`<meta>`](/en-US/docs/Web/HTML/Element/meta) element to set the {{httpheader('Content-Security-Policy')}} `default-src` to `self`, which allows scripts and other resources to be loaded from the same origin, but does not allow inline scripts to be executed. +The HTML file below uses the [`<meta>`](/en-US/docs/Web/HTML/Reference/Elements/meta) element to set the {{httpheader('Content-Security-Policy')}} `default-src` to `self`, which allows scripts and other resources to be loaded from the same origin, but does not allow inline scripts to be executed. The document also includes an inline script, which should therefore trigger a CSP violation. ```html diff --git a/files/en-us/web/api/cspviolationreportbody/statuscode/index.md b/files/en-us/web/api/cspviolationreportbody/statuscode/index.md index 845e06a79b8348d..13f0cfd15634ab1 100644 --- a/files/en-us/web/api/cspviolationreportbody/statuscode/index.md +++ b/files/en-us/web/api/cspviolationreportbody/statuscode/index.md @@ -8,7 +8,7 @@ browser-compat: api.CSPViolationReportBody.statusCode {{APIRef("Reporting API")}} -The **`statusCode`** read-only property of the {{domxref("CSPViolationReportBody")}} interface is a number representing the [HTTP status code](/en-US/docs/Web/HTTP/Status) of the response to the request that triggered a [Content Security Policy (CSP)](/en-US/docs/Web/HTTP/CSP) violation (when loading a window or worker). +The **`statusCode`** read-only property of the {{domxref("CSPViolationReportBody")}} interface is a number representing the [HTTP status code](/en-US/docs/Web/HTTP/Reference/Status) of the response to the request that triggered a [Content Security Policy (CSP)](/en-US/docs/Web/HTTP/Guides/CSP) violation (when loading a window or worker). ## Value diff --git a/files/en-us/web/api/css/registerproperty_static/index.md b/files/en-us/web/api/css/registerproperty_static/index.md index 45e802bf9b31782..04cbdba41efd2f0 100644 --- a/files/en-us/web/api/css/registerproperty_static/index.md +++ b/files/en-us/web/api/css/registerproperty_static/index.md @@ -49,7 +49,7 @@ CSS.registerProperty(propertyDefinition) - : The given `name` has already been registered. - `SyntaxError` {{domxref("DOMException")}} - : The given `name` isn't a valid custom property name (starts with two - dashes, e.g. `--foo`). + dashes, e.g., `--foo`). - {{jsxref("TypeError")}} - : The required `name` and/or `inherits` dictionary members were not provided. diff --git a/files/en-us/web/api/css_custom_highlight_api/index.md b/files/en-us/web/api/css_custom_highlight_api/index.md index 466ef74e28d6a47..9704cf10571c36f 100644 --- a/files/en-us/web/api/css_custom_highlight_api/index.md +++ b/files/en-us/web/api/css_custom_highlight_api/index.md @@ -178,9 +178,7 @@ query.addEventListener("input", () => { // Iterate over all text nodes and find matches. const ranges = allTextNodes - .map((el) => { - return { el, text: el.textContent.toLowerCase() }; - }) + .map((el) => ({ el, text: el.textContent.toLowerCase() })) .map(({ text, el }) => { const indices = []; let startPos = 0; @@ -237,5 +235,5 @@ The result is shown below. Type text within the search field to highlight matche ## See also - [CSS Custom Highlight API: The Future of Highlighting Text Ranges on the Web](https://css-tricks.com/css-custom-highlight-api-early-look/) -- HTML [`contentEditable`](/en-US/docs/Web/HTML/Global_attributes/contenteditable) attribute +- HTML [`contentEditable`](/en-US/docs/Web/HTML/Reference/Global_attributes/contenteditable) attribute - CSS {{cssxref("pseudo-elements")}} diff --git a/files/en-us/web/api/css_font_loading_api/index.md b/files/en-us/web/api/css_font_loading_api/index.md index c4259e9fef82d34..55ffd10432bea5f 100644 --- a/files/en-us/web/api/css_font_loading_api/index.md +++ b/files/en-us/web/api/css_font_loading_api/index.md @@ -249,7 +249,7 @@ Unlike the other mechanisms this returns when all fonts defined in the document When the promise resolves we iterate the values in the document's font faces. ```js -document.fonts.ready.then(function () { +document.fonts.ready.then(() => { log.textContent += `\nFontFaces in document: ${document.fonts.size}.\n`; for (const fontFace of document.fonts.values()) { diff --git a/files/en-us/web/api/css_object_model/css_declaration_block/index.md b/files/en-us/web/api/css_object_model/css_declaration_block/index.md index 51ef2ff67d955e6..e786ce566752862 100644 --- a/files/en-us/web/api/css_object_model/css_declaration_block/index.md +++ b/files/en-us/web/api/css_object_model/css_declaration_block/index.md @@ -20,7 +20,7 @@ Each property and value pairing is known as a [CSS declaration](/en-US/docs/Web/ - owner node - : The {{domxref("element")}} that the CSS declaration block is associated with, otherwise null. - updating flag - - : Set when the CSS declaration block is updating the owner node's [`style`](/en-US/docs/Web/HTML/Global_attributes/style) attribute. + - : Set when the CSS declaration block is updating the owner node's [`style`](/en-US/docs/Web/HTML/Reference/Global_attributes/style) attribute. When a {{domxref("CSSStyleDeclaration")}} is returned by a [CSS Object Model (CSSOM)](/en-US/docs/Web/API/CSS_Object_Model) interface these properties are set to appropriate values as defined by the specification. diff --git a/files/en-us/web/api/css_painting_api/guide/index.md b/files/en-us/web/api/css_painting_api/guide/index.md index 92ea6ef12dc8951..08562e11eda4748 100644 --- a/files/en-us/web/api/css_painting_api/guide/index.md +++ b/files/en-us/web/api/css_painting_api/guide/index.md @@ -207,7 +207,7 @@ registerPaint( ); ``` -The three parameters of the `paint()` function include the drawing context, paint size and properties. To be able to access properties, we include the static `inputProperties()` method, which provides live access to CSS properties, including regular properties and [custom properties](/en-US/docs/Web/CSS/CSS_cascading_variables), and returns an {{jsxref("Array", "array", "", 1)}} of property names. We'll take a look at [`inputArguments`](/en-US/docs/Web/API/CSS_Painting_API/Guide#passing_parameters) in the last section. +The three parameters of the `paint()` function include the drawing context, paint size and properties. To be able to access properties, we include the static `inputProperties()` method, which provides live access to CSS properties, including regular properties and [custom properties](/en-US/docs/Web/CSS/CSS_cascading_variables), and returns an {{jsxref("Array", "array", "", 1)}} of property names. We'll take a look at [`inputArguments`](#passing_parameters) in the last section. Let's create a list of items with a background image that rotates between three different colors and three widths. @@ -319,7 +319,7 @@ While you can't play with the worklet's script, you can alter the custom propert ## Adding complexity -The above examples might not seem very exciting, as you could recreate them in a few different ways with existing CSS properties, e.g. by positioning some decorative [generated content](/en-US/docs/Learn_web_development/Howto/Solve_CSS_problems/Generated_content) with `::before`, or including `background: linear-gradient(yellow, yellow) 0 15px / 200px 20px no-repeat;` What makes the CSS Painting API so interesting and powerful is that you can create complex images, passing variables, that automatically resize. +The above examples might not seem very exciting, as you could recreate them in a few different ways with existing CSS properties, e.g., by positioning some decorative [generated content](/en-US/docs/Learn_web_development/Howto/Solve_CSS_problems/Generated_content) with `::before`, or including `background: linear-gradient(yellow, yellow) 0 15px / 200px 20px no-repeat;` What makes the CSS Painting API so interesting and powerful is that you can create complex images, passing variables, that automatically resize. Let's take a look at a more complex paint example. @@ -436,21 +436,29 @@ li { Now we can use the `inputArguments()` method in the `registerPaint()` class to access the custom argument we have added to our `paint()` function. ```js -static get inputArguments() { return ['*']; } +class Worklet { + static get inputArguments() { + return ["*"]; + } + // … +} ``` We then have access to that argument. ```js -paint(ctx, size, props, args) { - - // use our custom arguments - const hasStroke = args[0].toString(); - - // if stroke arg is 'stroke', don't fill - if (hasStroke === 'stroke') { - ctx.fillStyle = 'transparent'; - ctx.strokeStyle = color; +class Worklet { + // … + paint(ctx, size, props, args) { + // use our custom arguments + const hasStroke = args[0].toString(); + + // if stroke arg is 'stroke', don't fill + if (hasStroke === "stroke") { + ctx.fillStyle = "transparent"; + ctx.strokeStyle = color; + } + // … } // … } @@ -469,7 +477,13 @@ li { When we `get` our list of argument values, we can ask specifically for a `<length>` unit. ```js -static get inputArguments() { return ['*', '<length>']; } +class Worklet { + // … + static get inputArguments() { + return ["*", "<length>"]; + } + // … +} ``` In this case, we specifically requested the `<length>` attribute. The first element in the returned array will be a {{domxref('CSSUnparsedValue')}}. The second will be a {{domxref('CSSStyleValue')}}. @@ -479,16 +493,19 @@ If the custom argument is a CSS value, for instance a unit, we can invoke Typed Now we can access the type and value properties, meaning we can get the number of pixels and a number type right out of the box. (Admittedly, `ctx.lineWidth` takes a float as a value rather than a value with length units, but for example's sake…) ```js -paint(ctx, size, props, args) { +class Worklet { + // … + paint(ctx, size, props, args) { + const strokeWidth = args[1]; - const strokeWidth = args[1]; + if (strokeWidth.unit === "px") { + ctx.lineWidth = strokeWidth.value; + } else { + ctx.lineWidth = 1.0; + } - if (strokeWidth.unit === 'px') { - ctx.lineWidth = strokeWidth.value; - } else { - ctx.lineWidth = 1.0; + // … } - // … } ``` @@ -534,7 +551,7 @@ registerPaint( // the values passed in the paint() function in the CSS const color = props.get("--boxColor"); const strokeType = args[0].toString(); - const strokeWidth = parseInt(args[1]); + const strokeWidth = parseInt(args[1], 10); // set the stroke width ctx.lineWidth = strokeWidth ?? 1.0; diff --git a/files/en-us/web/api/css_painting_api/index.md b/files/en-us/web/api/css_painting_api/index.md index ad2716b682e7857..57261d891228941 100644 --- a/files/en-us/web/api/css_painting_api/index.md +++ b/files/en-us/web/api/css_painting_api/index.md @@ -39,7 +39,7 @@ The API defines a {{domxref('worklet')}} that can be used to programmatically ge The following example creates a list of items with a background image that rotates between three different colors and three widths. In [a supporting browser](#browser_compatibility) you will see something like the image below. -![The width and color of the background image changes based on the custom properties](guide/boxbg.png) +![The width and color of the background image changes based on the custom properties](Guide/boxbg.png) To achieve this we'll define two custom CSS properties, `--boxColor` and `--widthSubtractor`. diff --git a/files/en-us/web/api/css_typed_om_api/guide/index.md b/files/en-us/web/api/css_typed_om_api/guide/index.md index d9eda6a36773a7e..740c3f4bc6a3166 100644 --- a/files/en-us/web/api/css_typed_om_api/guide/index.md +++ b/files/en-us/web/api/css_typed_om_api/guide/index.md @@ -59,7 +59,7 @@ for (const [prop, val] of defaultComputedStyles) { } ``` -The `computedStyleMap()` method returns a {{domxref('StylePropertyMapReadOnly')}} object containing the [`size`](/en-US/docs/Web/API/StylePropertyMapReadOnly/size) property, which indicates how many properties are in the map. We iterate through the style map, creating a [`<dt>`](/en-US/docs/Web/HTML/Element/dt) and [`<dd>`](/en-US/docs/Web/HTML/Element/dd) for each property and value respectively. +The `computedStyleMap()` method returns a {{domxref('StylePropertyMapReadOnly')}} object containing the [`size`](/en-US/docs/Web/API/StylePropertyMapReadOnly/size) property, which indicates how many properties are in the map. We iterate through the style map, creating a [`<dt>`](/en-US/docs/Web/HTML/Reference/Elements/dt) and [`<dd>`](/en-US/docs/Web/HTML/Reference/Elements/dd) for each property and value respectively. #### Result @@ -138,9 +138,9 @@ Let's write a plain paragraph, apply no styles, and inspect a few of its CSS pro ```html <p> - This is a paragraph with some content. Open up this example in CodePen or - JSFiddle, and change some features. Try adding some CSS, such as a width - for this paragraph, or adding a CSS property to the ofInterest array. + This is a paragraph with some content. Open up this example in CodePen or + JSFiddle, and change some features. Try adding some CSS, such as a width for + this paragraph, or adding a CSS property to the ofInterest array. </p> <table id="regurgitation"> <thead> @@ -149,6 +149,7 @@ Let's write a plain paragraph, apply no styles, and inspect a few of its CSS pro <th>Value</th> <th>Unit</th> </tr> + </thead> </table> ``` @@ -352,7 +353,7 @@ console.log(parsedUnit.value); // 1.2 ### CSSMathSum -Although the [`<button>`](/en-US/docs/Web/HTML/Element/button) element is an inline element by default, we've added [`display: inline-block;`](/en-US/docs/Web/CSS/CSS_display) to enable sizing. In our CSS we have `width: calc(30% + 20px);`, which is a [`calc()`](/en-US/docs/Web/CSS/calc) function to define the width. +Although the [`<button>`](/en-US/docs/Web/HTML/Reference/Elements/button) element is an inline element by default, we've added [`display: inline-block;`](/en-US/docs/Web/CSS/CSS_display) to enable sizing. In our CSS we have `width: calc(30% + 20px);`, which is a [`calc()`](/en-US/docs/Web/CSS/calc) function to define the width. When we `get()` the `width`, we get a [`CSSMathSum`](/en-US/docs/Web/API/CSSMathSum) returned. {{domxref('CSSMathSum.values')}} is a {{domxref('CSSNumericArray')}} with 2 `CSSUnitValues`. diff --git a/files/en-us/web/api/csscontainerrule/index.md b/files/en-us/web/api/csscontainerrule/index.md index 8ea2472b21d6cdb..cbc6a45d1dd31cd 100644 --- a/files/en-us/web/api/csscontainerrule/index.md +++ b/files/en-us/web/api/csscontainerrule/index.md @@ -104,7 +104,7 @@ log(`CSSContainerRule.conditionText: "${containerRule.conditionText}"`); > [!NOTE] > The styles for this example are defined in an inline HTML `style` element with an id in order to make it easy for the code to find the correct sheet. -> You might also locate the correct sheets for each example from the document by indexing against the length (e.g. `document.styleSheets[document.styleSheets.length-1]` but that makes working out correct sheet for each example more complicated). +> You might also locate the correct sheets for each example from the document by indexing against the length (e.g., `document.styleSheets[document.styleSheets.length-1]` but that makes working out correct sheet for each example more complicated). The example output is shown below. The log section lists the `containerName`, which is an empty string as no name has been defined. diff --git a/files/en-us/web/api/cssfontfacerule/index.md b/files/en-us/web/api/cssfontfacerule/index.md index 8327236a7e78a5a..45ad166ebd13966 100644 --- a/files/en-us/web/api/cssfontfacerule/index.md +++ b/files/en-us/web/api/cssfontfacerule/index.md @@ -37,8 +37,8 @@ This example uses the CSS found as an example on the {{cssxref("@font-face")}} p ``` ```js -let myRules = document.styleSheets[0].cssRules; -console.log(myRules[0]); //a CSSFontFaceRule +const myRules = document.styleSheets[0].cssRules; +console.log(myRules[0]); // A CSSFontFaceRule ``` ## Specifications diff --git a/files/en-us/web/api/cssfontfacerule/style/index.md b/files/en-us/web/api/cssfontfacerule/style/index.md index d2de922796895f2..ff9a624d57b5e1b 100644 --- a/files/en-us/web/api/cssfontfacerule/style/index.md +++ b/files/en-us/web/api/cssfontfacerule/style/index.md @@ -29,8 +29,8 @@ This example uses the CSS found as an example on the {{cssxref("@font-face")}} p ``` ```js -let myRules = document.styleSheets[0].cssRules; -console.log(myRules[0].style); //a CSSStyleDeclaration +const myRules = document.styleSheets[0].cssRules; +console.log(myRules[0].style); // A CSSStyleDeclaration ``` ## Specifications diff --git a/files/en-us/web/api/cssimagevalue/magicwand.png b/files/en-us/web/api/cssimagevalue/magic-wand.png similarity index 100% rename from files/en-us/web/api/cssimagevalue/magicwand.png rename to files/en-us/web/api/cssimagevalue/magic-wand.png diff --git a/files/en-us/web/api/cssimportrule/href/index.md b/files/en-us/web/api/cssimportrule/href/index.md index 1437e767cfbc7e3..7272ef07f42791f 100644 --- a/files/en-us/web/api/cssimportrule/href/index.md +++ b/files/en-us/web/api/cssimportrule/href/index.md @@ -12,7 +12,7 @@ The read-only **`href`** property of the {{domxref("CSSImportRule")}} interface returns the URL specified by the {{cssxref("@import")}} [at-rule](/en-US/docs/Web/CSS/CSS_syntax/At-rule). -The resolved URL will be the [`href`](/en-US/docs/Web/HTML/Element/link#href) attribute of the +The resolved URL will be the [`href`](/en-US/docs/Web/HTML/Reference/Elements/link#href) attribute of the associated stylesheet. ## Value @@ -30,8 +30,8 @@ first item in the list of CSS rules will be a `CSSImportRule`. The ``` ```js -let myRules = document.styleSheets[0].cssRules; -console.log(myRules[0].href); //returns style.css +const myRules = document.styleSheets[0].cssRules; +console.log(myRules[0].href); // 'style.css' ``` ## Specifications diff --git a/files/en-us/web/api/cssimportrule/media/index.md b/files/en-us/web/api/cssimportrule/media/index.md index 99cd6c022096080..c293fe15635efb0 100644 --- a/files/en-us/web/api/cssimportrule/media/index.md +++ b/files/en-us/web/api/cssimportrule/media/index.md @@ -32,8 +32,8 @@ the `mediaText` property with a value of `screen`. ``` ```js -let myRules = document.styleSheets[0].cssRules; -console.log(myRules[0].media); //returns a MediaList +const myRules = document.styleSheets[0].cssRules; +console.log(myRules[0].media); // A MediaList ``` ### Setting the media property @@ -41,7 +41,7 @@ console.log(myRules[0].media); //returns a MediaList To change the `media` attribute of the associated stylesheet, set the value of `media` to a string containing the new value. ```js -let myRules = document.styleSheets[0].cssRules; +const myRules = document.styleSheets[0].cssRules; myRules[0].media = "print"; ``` diff --git a/files/en-us/web/api/cssimportrule/stylesheet/index.md b/files/en-us/web/api/cssimportrule/stylesheet/index.md index ee239789d75fc5d..1da9e63219009d7 100644 --- a/files/en-us/web/api/cssimportrule/stylesheet/index.md +++ b/files/en-us/web/api/cssimportrule/stylesheet/index.md @@ -31,8 +31,8 @@ first item in the list of CSS rules will be a `CSSImportRule`. The ``` ```js -let myRules = document.styleSheets[0].cssRules; -console.log(myRules[0].styleSheet); //returns a CSSStyleSheet object +const myRules = document.styleSheets[0].cssRules; +console.log(myRules[0].styleSheet); // A CSSStyleSheet ``` ## Specifications diff --git a/files/en-us/web/api/csskeyframerule/style/index.md b/files/en-us/web/api/csskeyframerule/style/index.md index 45238fed8b874d0..9ac859fefb10177 100644 --- a/files/en-us/web/api/csskeyframerule/style/index.md +++ b/files/en-us/web/api/csskeyframerule/style/index.md @@ -19,7 +19,7 @@ A {{domxref("CSSStyleDeclaration")}} object, with the following properties: - declarations - : The declared declarations in the rule, in the order they were specified, shorthand properties expanded to longhands. - parent CSS rule - - : The context object, which is an alias for [this](https://heycam.github.io/webidl/#this). + - : The context object, which is an alias for [`this`](https://heycam.github.io/webidl/#this). - owner node - : Null. diff --git a/files/en-us/web/api/csskeywordvalue/csskeywordvalue/index.md b/files/en-us/web/api/csskeywordvalue/csskeywordvalue/index.md index e2288be630778af..ecacf804247effa 100644 --- a/files/en-us/web/api/csskeywordvalue/csskeywordvalue/index.md +++ b/files/en-us/web/api/csskeywordvalue/csskeywordvalue/index.md @@ -32,7 +32,7 @@ new CSSKeywordValue(val) The following example resets the CSS {{cssxref('display')}} property to its defaults, setting the inline -[`style`](/en-US/docs/Web/HTML/Global_attributes/style) attribute +[`style`](/en-US/docs/Web/HTML/Reference/Global_attributes/style) attribute to `style="display: initial"` if viewed in the [developer tools inspector](https://firefox-source-docs.mozilla.org/devtools-user/page_inspector/how_to/select_an_element/index.html). ```css hidden diff --git a/files/en-us/web/api/csskeywordvalue/index.md b/files/en-us/web/api/csskeywordvalue/index.md index 7c1521d3b2c3dab..ccfa8f8560bac17 100644 --- a/files/en-us/web/api/csskeywordvalue/index.md +++ b/files/en-us/web/api/csskeywordvalue/index.md @@ -29,7 +29,7 @@ _Inherits methods from {{domxref('CSSStyleValue')}}._ ## Examples -The following example resets the CSS {{cssxref('display')}} property to its defaults, setting the inline [`style`](/en-US/docs/Web/HTML/Global_attributes/style) attribute to `style="display: initial"` if viewed in the [developer tools inspector](https://firefox-source-docs.mozilla.org/devtools-user/page_inspector/how_to/select_an_element/index.html). +The following example resets the CSS {{cssxref('display')}} property to its defaults, setting the inline [`style`](/en-US/docs/Web/HTML/Reference/Global_attributes/style) attribute to `style="display: initial"` if viewed in the [developer tools inspector](https://firefox-source-docs.mozilla.org/devtools-user/page_inspector/how_to/select_an_element/index.html). ```css hidden #myElement { diff --git a/files/en-us/web/api/cssmathinvert/index.md b/files/en-us/web/api/cssmathinvert/index.md index 2b95b1aecbc1f90..fdd13c1400a263a 100644 --- a/files/en-us/web/api/cssmathinvert/index.md +++ b/files/en-us/web/api/cssmathinvert/index.md @@ -7,7 +7,7 @@ browser-compat: api.CSSMathInvert {{APIRef("CSS Typed Object Model API")}} -The **`CSSMathInvert`** interface of the [CSS Typed Object Model API](/en-US/docs/Web/API/CSS_Object_Model) represents a CSS {{CSSXref('calc','calc()')}} used as `calc(1 / <value>).` It inherits properties and methods from its parent {{domxref('CSSNumericValue')}}. +The **`CSSMathInvert`** interface of the [CSS Typed Object Model API](/en-US/docs/Web/API/CSS_Object_Model) represents a CSS {{CSSXref('calc','calc()')}} used as `calc(1 / <value>)`. It inherits properties and methods from its parent {{domxref('CSSNumericValue')}}. {{InheritanceDiagram}} diff --git a/files/en-us/web/api/cssnamespacerule/index.md b/files/en-us/web/api/cssnamespacerule/index.md index f6b8ec8b5758c85..e6ee479f432a996 100644 --- a/files/en-us/web/api/cssnamespacerule/index.md +++ b/files/en-us/web/api/cssnamespacerule/index.md @@ -33,8 +33,8 @@ The stylesheet includes a namespace as the only rule. Therefore the first {{domx ``` ```js -let myRules = document.styleSheets[0].cssRules; -console.log(myRules[0]); //a CSSNamespaceRule +const myRules = document.styleSheets[0].cssRules; +console.log(myRules[0]); // A CSSNamespaceRule ``` ## Specifications diff --git a/files/en-us/web/api/cssnamespacerule/namespaceuri/index.md b/files/en-us/web/api/cssnamespacerule/namespaceuri/index.md index 3f376c05d69e1c0..77a1cb1b981cf98 100644 --- a/files/en-us/web/api/cssnamespacerule/namespaceuri/index.md +++ b/files/en-us/web/api/cssnamespacerule/namespaceuri/index.md @@ -23,8 +23,8 @@ The stylesheet includes a namespace as the only rule. Therefore the first {{domx ``` ```js -let myRules = document.styleSheets[0].cssRules; -console.log(myRules[0].namespaceURI); //http://www.w3.org/1999/xhtml +const myRules = document.styleSheets[0].cssRules; +console.log(myRules[0].namespaceURI); // 'http://www.w3.org/1999/xhtml' ``` ## Specifications diff --git a/files/en-us/web/api/cssnesteddeclarations/index.md b/files/en-us/web/api/cssnesteddeclarations/index.md index b4eefca2186e8d8..caf114402652f67 100644 --- a/files/en-us/web/api/cssnesteddeclarations/index.md +++ b/files/en-us/web/api/cssnesteddeclarations/index.md @@ -11,7 +11,9 @@ The **`CSSNestedDeclarations`** interface of the [CSS Rule API](/en-US/docs/Web/ The interface allows the [CSS Object Model (CSSOM](/en-US/docs/Web/API/CSS_Object_Model) to mirror the structure of CSS documents with nested CSS rules, and ensure that rules are parsed and evaluated in the order that they are declared. -> [!NOTE] > [Browser versions](#browser_compatibility) with implementations that do not support this interface may parse nested rules in the wrong order. +> [!NOTE] +> Implementations that do not support this interface may parse nested rules in the wrong order. +> See [Browser compatibility](#browser_compatibility) for more information. {{InheritanceDiagram}} @@ -35,7 +37,7 @@ The CSS below includes a selector `.foo` that contains two declarations and a me ```css .foo { background-color: silver; - @media (screen) { + @media screen { color: tomato; } color: black; @@ -46,8 +48,8 @@ This is represented by a number of JavaScript objects in the [CSS Object Model]( - A {{domxref("CSSStyleRule")}} object that represents the `background-color: silver` rule. This can be returned via `document.styleSheets[0].cssRules[0]`. -- A {{domxref("CSSMediaRule")}} object that represents the `@media (screen)` rule, and which can be returned via `document.styleSheets[0].cssRules[0].cssRules[0]`. - - The `CSSMediaRule` object contains a `CSSNestedDeclaration` object which represents the `color: tomato` rule nested by the `@media (screen)` rule. +- A {{domxref("CSSMediaRule")}} object that represents the `@media screen` rule, and which can be returned via `document.styleSheets[0].cssRules[0].cssRules[0]`. + - The `CSSMediaRule` object contains a `CSSNestedDeclaration` object which represents the `color: tomato` rule nested by the `@media screen` rule. This can be returned via `document.styleSheets[0].cssRules[0].cssRules[0].cssRules[0]`. - The final rule is a `CSSNestedDeclaration` object that represents the `color: black` rule in the stylesheet, and which can be returned via `document.styleSheets[0].cssRules[0].cssRules[1]`. @@ -56,7 +58,7 @@ This is represented by a number of JavaScript objects in the [CSS Object Model]( ### CSSOM (CSS Object Model) -```txt +```plain ↳ CSSStyleRule .style - background-color: silver diff --git a/files/en-us/web/api/cssnesteddeclarations/style/index.md b/files/en-us/web/api/cssnesteddeclarations/style/index.md index 9f72d605cc245a0..556881a56b34f08 100644 --- a/files/en-us/web/api/cssnesteddeclarations/style/index.md +++ b/files/en-us/web/api/cssnesteddeclarations/style/index.md @@ -23,7 +23,7 @@ The first `console.log` shows the top-level `style`, the second shows the nested ```css .foo { font-size: 1.2rem; - @media (screen) { + @media screen { color: tomato; background-color: darkgrey; } diff --git a/files/en-us/web/api/cssnumericvalue/type/index.md b/files/en-us/web/api/cssnumericvalue/type/index.md index 2212648dde0aa58..eb31de1b0a62a1c 100644 --- a/files/en-us/web/api/cssnumericvalue/type/index.md +++ b/files/en-us/web/api/cssnumericvalue/type/index.md @@ -26,7 +26,20 @@ None. ### Return value -A {{domxref('CSSNumericType')}} object. +A `CSSNumericType` dictionary, which contains the following properties: + +- `length` +- `angle` +- `time` +- `frequency` +- `resolution` +- `flex` +- `percent` +- `percentHint` + +For each property except `percentHint`, the value is an integer representing the power of that unit. For example, a numeric value of `calc(1px * 1em)` will return `{ length: 2 }`. + +The `percentHint` property is a string that indicates the type of value that the percent is applied to. The string value is the same as the type properties: `"length"`, `"angle"`, `"time"`, `"frequency"`, `"resolution"`, `"flex"`, or `"percent"`. It indicates that the type actually holds a percentage, but that percentage will eventually resolve to the hinted base type, and so has been replaced with it in the type. ### Exceptions diff --git a/files/en-us/web/api/csspagedescriptors/index.md b/files/en-us/web/api/csspagedescriptors/index.md index 70819008a7ba9e3..7bf3f17a808a8fd 100644 --- a/files/en-us/web/api/csspagedescriptors/index.md +++ b/files/en-us/web/api/csspagedescriptors/index.md @@ -110,29 +110,29 @@ if (typeof window.CSSPageDescriptors === "undefined") { } else { // Get stylesheets for example and then get its cssRules const myRules = document.styleSheets[1].cssRules; - for (let i = 0; i < myRules.length; i++) { - if (myRules[i] instanceof CSSPageRule) { - log(`${myRules[i].style}`); - log(`margin: ${myRules[i].style.margin}`); + for (const rule of myRules) { + if (rule instanceof CSSPageRule) { + log(`${rule.style}`); + log(`margin: ${rule.style.margin}`); // Access properties using CamelCase syntax - log(`marginTop: ${myRules[i].style.marginTop}`); - log(`marginRight: ${myRules[i].style.marginRight}`); - log(`marginBottom: ${myRules[i].style.marginBottom}`); - log(`marginLeft: ${myRules[i].style.marginLeft}`); - log(`pageOrientation: ${myRules[i].style.pageOrientation}`); + log(`marginTop: ${rule.style.marginTop}`); + log(`marginRight: ${rule.style.marginRight}`); + log(`marginBottom: ${rule.style.marginBottom}`); + log(`marginLeft: ${rule.style.marginLeft}`); + log(`pageOrientation: ${rule.style.pageOrientation}`); // Access properties using snake-case syntax - log(`margin-top: ${myRules[i].style["margin-top"]}`); - log(`margin-right: ${myRules[i].style["margin-right"]}`); - log(`margin-left: ${myRules[i].style["margin-left"]}`); - log(`margin-bottom: ${myRules[i].style["margin-bottom"]}`); - log(`page-orientation: ${myRules[i].style["page-orientation"]}`); + log(`margin-top: ${rule.style["margin-top"]}`); + log(`margin-right: ${rule.style["margin-right"]}`); + log(`margin-left: ${rule.style["margin-left"]}`); + log(`margin-bottom: ${rule.style["margin-bottom"]}`); + log(`page-orientation: ${rule.style["page-orientation"]}`); - log(`size: ${myRules[i].style.size}`); + log(`size: ${rule.style.size}`); // Log the original CSS text using inherited property: cssText - log(`cssText: ${myRules[i].style.cssText}`); + log(`cssText: ${rule.style.cssText}`); log("\n"); } } diff --git a/files/en-us/web/api/csspagerule/index.md b/files/en-us/web/api/csspagerule/index.md index d44ab303887e2da..64467de70c596a2 100644 --- a/files/en-us/web/api/csspagerule/index.md +++ b/files/en-us/web/api/csspagerule/index.md @@ -77,10 +77,10 @@ for ( const myRules = document.styleSheets[sheetCount].cssRules; log(`rules: ${myRules.length}`); - for (let i = 0; i < myRules.length; i++) { - log(`rule: ${myRules[i]}`); - if (myRules[i] instanceof CSSPageRule) { - //... Do something with CSSPageRule + for (const rule of myRules) { + log(`rule: ${rule}`); + if (rule instanceof CSSPageRule) { + // Do something with CSSPageRule } } } diff --git a/files/en-us/web/api/csspagerule/selectortext/index.md b/files/en-us/web/api/csspagerule/selectortext/index.md index 76b986141f4a0ea..9be3bc08a464a8b 100644 --- a/files/en-us/web/api/csspagerule/selectortext/index.md +++ b/files/en-us/web/api/csspagerule/selectortext/index.md @@ -29,8 +29,8 @@ The stylesheet includes two {{cssxref("@page")}} rules. The `selectorText` prope ``` ```js -let myRules = document.styleSheets[0].cssRules; //returns two myRules -console.log(myRules[1].selectorText); // returns the string ":first" +const myRules = document.styleSheets[0].cssRules; // Two myRules +console.log(myRules[1].selectorText); // ":first" ``` ## Specifications diff --git a/files/en-us/web/api/csspagerule/style/index.md b/files/en-us/web/api/csspagerule/style/index.md index 21fc12c38b77ae5..ee8534528819277 100644 --- a/files/en-us/web/api/csspagerule/style/index.md +++ b/files/en-us/web/api/csspagerule/style/index.md @@ -74,26 +74,26 @@ We then iterate through the rules defined for the live example and match any tha For the matching objects we then log the `style` and all its values. ```js -for (let i = 0; i < myRules.length; i++) { - if (myRules[i] instanceof CSSPageRule) { - log(`${myRules[i].style}`); - log(`margin: ${myRules[i].style.margin}`); +for (const rule of myRules) { + if (rule instanceof CSSPageRule) { + log(`${rule.style}`); + log(`margin: ${rule.style.margin}`); // Access properties using CamelCase properties - log(`marginTop: ${myRules[i].style.marginTop}`); - log(`marginRight: ${myRules[i].style.marginRight}`); - log(`marginBottom: ${myRules[i].style.marginBottom}`); - log(`marginLeft: ${myRules[i].style.marginLeft}`); - log(`pageOrientation: ${myRules[i].style.pageOrientation}`); + log(`marginTop: ${rule.style.marginTop}`); + log(`marginRight: ${rule.style.marginRight}`); + log(`marginBottom: ${rule.style.marginBottom}`); + log(`marginLeft: ${rule.style.marginLeft}`); + log(`pageOrientation: ${rule.style.pageOrientation}`); // Access properties using snake-case properties - log(`margin-top: ${myRules[i].style["margin-top"]}`); - log(`margin-right: ${myRules[i].style["margin-right"]}`); - log(`margin-left: ${myRules[i].style["margin-left"]}`); - log(`margin-bottom: ${myRules[i].style["margin-bottom"]}`); - log(`page-orientation: ${myRules[i].style["page-orientation"]}`); + log(`margin-top: ${rule.style["margin-top"]}`); + log(`margin-right: ${rule.style["margin-right"]}`); + log(`margin-left: ${rule.style["margin-left"]}`); + log(`margin-bottom: ${rule.style["margin-bottom"]}`); + log(`page-orientation: ${rule.style["page-orientation"]}`); - log(`size: ${myRules[i].style.size}`); + log(`size: ${rule.style.size}`); log("\n"); } } diff --git a/files/en-us/web/api/cssprimitivevalue/getcountervalue/index.md b/files/en-us/web/api/cssprimitivevalue/getcountervalue/index.md index d328f8ee0cbadc7..c78c9c3a1cb7ee9 100644 --- a/files/en-us/web/api/cssprimitivevalue/getcountervalue/index.md +++ b/files/en-us/web/api/cssprimitivevalue/getcountervalue/index.md @@ -41,9 +41,9 @@ A {{domxref("Counter")}} object representing the counter value. ### Exceptions -| **Type** | **Description** | -| -------------- | ---------------------------------------------------------------------------------------------------------------------- | -| `DOMException` | An `INVALID_ACCESS_ERR` is raised if the CSS value doesn't contain a `Counter` value (e.g. this is not `CSS_COUNTER`). | +| **Type** | **Description** | +| -------------- | ----------------------------------------------------------------------------------------------------------------------- | +| `DOMException` | An `INVALID_ACCESS_ERR` is raised if the CSS value doesn't contain a `Counter` value (e.g., this is not `CSS_COUNTER`). | ## Specifications diff --git a/files/en-us/web/api/cssprimitivevalue/getrectvalue/index.md b/files/en-us/web/api/cssprimitivevalue/getrectvalue/index.md index 684b405213ff17c..9497a435a63a30e 100644 --- a/files/en-us/web/api/cssprimitivevalue/getrectvalue/index.md +++ b/files/en-us/web/api/cssprimitivevalue/getrectvalue/index.md @@ -41,9 +41,9 @@ A {{domxref("Rect")}} object representing the rect value. ### Exceptions -| **Type** | **Description** | -| -------------- | --------------------------------------------------------------------------------------------------------------- | -| `DOMException` | An `INVALID_ACCESS_ERR` is raised if the CSS value doesn't contain a Rect value. (i.e. this is not `CSS_RECT`). | +| **Type** | **Description** | +| -------------- | ---------------------------------------------------------------------------------------------------------------- | +| `DOMException` | An `INVALID_ACCESS_ERR` is raised if the CSS value doesn't contain a Rect value. (i.e., this is not `CSS_RECT`). | ## Examples diff --git a/files/en-us/web/api/cssprimitivevalue/getrgbcolorvalue/index.md b/files/en-us/web/api/cssprimitivevalue/getrgbcolorvalue/index.md index 82e15b94d384f11..ee2d94b443a9ab5 100644 --- a/files/en-us/web/api/cssprimitivevalue/getrgbcolorvalue/index.md +++ b/files/en-us/web/api/cssprimitivevalue/getrgbcolorvalue/index.md @@ -41,9 +41,9 @@ An {{domxref("RGBColor")}} object representing the color value. ### Exceptions -| **Type** | **Description** | -| -------------- | ----------------------------------------------------------------------------------------------------------------------------- | -| `DOMException` | An `INVALID_ACCESS_ERR` is raised if the attached property can't return an RGB color value (i.e. this is not `CSS_RGBCOLOR`). | +| **Type** | **Description** | +| -------------- | ------------------------------------------------------------------------------------------------------------------------------ | +| `DOMException` | An `INVALID_ACCESS_ERR` is raised if the attached property can't return an RGB color value (i.e., this is not `CSS_RGBCOLOR`). | ## Examples diff --git a/files/en-us/web/api/cssprimitivevalue/setstringvalue/index.md b/files/en-us/web/api/cssprimitivevalue/setstringvalue/index.md index 2a2c0e270494ba2..b9440005bf41f3f 100644 --- a/files/en-us/web/api/cssprimitivevalue/setstringvalue/index.md +++ b/files/en-us/web/api/cssprimitivevalue/setstringvalue/index.md @@ -56,7 +56,7 @@ None ({{jsxref("undefined")}}). - `InvalidAccessError` {{domxref("DOMException")}} - : Thrown if the CSS value doesn't contain a string value or if the string value can't be converted into the specified unit. -- `NoModificationAllowedError' {{domxref("DOMException")}} +- `NoModificationAllowedError` {{domxref("DOMException")}} - : Thrown if the property is read-only. ## Specifications diff --git a/files/en-us/web/api/csspropertyrule/index.md b/files/en-us/web/api/csspropertyrule/index.md index d5d342585461d3d..b5a6f51d56a7c56 100644 --- a/files/en-us/web/api/csspropertyrule/index.md +++ b/files/en-us/web/api/csspropertyrule/index.md @@ -41,8 +41,8 @@ This stylesheet contains a single {{cssxref("@property")}} rule. The first {{dom ``` ```js -let myRules = document.styleSheets[0].cssRules; -console.log(myRules[0]); //a CSSPropertyRule +const myRules = document.styleSheets[0].cssRules; +console.log(myRules[0]); // A CSSPropertyRule ``` ## Specifications diff --git a/files/en-us/web/api/csspropertyrule/inherits/index.md b/files/en-us/web/api/csspropertyrule/inherits/index.md index 8e8c283ae92f7e8..f24098df9eaee91 100644 --- a/files/en-us/web/api/csspropertyrule/inherits/index.md +++ b/files/en-us/web/api/csspropertyrule/inherits/index.md @@ -27,8 +27,8 @@ This stylesheet contains a single {{cssxref("@property")}} rule. The first {{dom ``` ```js -let myRules = document.styleSheets[0].cssRules; -console.log(myRules[0].inherits); //returns false +const myRules = document.styleSheets[0].cssRules; +console.log(myRules[0].inherits); // false ``` ## Specifications diff --git a/files/en-us/web/api/csspropertyrule/initialvalue/index.md b/files/en-us/web/api/csspropertyrule/initialvalue/index.md index 9895955244f5505..5d09e13dd9aa150 100644 --- a/files/en-us/web/api/csspropertyrule/initialvalue/index.md +++ b/files/en-us/web/api/csspropertyrule/initialvalue/index.md @@ -28,8 +28,8 @@ This stylesheet contains a single {{cssxref("@property")}} rule. The first {{dom ``` ```js -let myRules = document.styleSheets[0].cssRules; -console.log(myRules[0].initialValue); //the string "#c0ffee" +const myRules = document.styleSheets[0].cssRules; +console.log(myRules[0].initialValue); // "#c0ffee" ``` ## Specifications diff --git a/files/en-us/web/api/csspropertyrule/name/index.md b/files/en-us/web/api/csspropertyrule/name/index.md index 03822322bf1448b..8dd178b25212af7 100644 --- a/files/en-us/web/api/csspropertyrule/name/index.md +++ b/files/en-us/web/api/csspropertyrule/name/index.md @@ -27,8 +27,8 @@ This stylesheet contains a single {{cssxref("@property")}} rule. The first {{dom ``` ```js -let myRules = document.styleSheets[0].cssRules; -console.log(myRules[0].name); //the string "--property-name" +const myRules = document.styleSheets[0].cssRules; +console.log(myRules[0].name); // "--property-name" ``` ## Specifications diff --git a/files/en-us/web/api/csspropertyrule/syntax/index.md b/files/en-us/web/api/csspropertyrule/syntax/index.md index 9d41df7c66cc420..fe2f9fab3fec96e 100644 --- a/files/en-us/web/api/csspropertyrule/syntax/index.md +++ b/files/en-us/web/api/csspropertyrule/syntax/index.md @@ -27,8 +27,8 @@ This stylesheet contains a single {{cssxref("@property")}} rule. The first {{dom ``` ```js -let myRules = document.styleSheets[0].cssRules; -console.log(myRules[0].syntax); //the string "<color>" +const myRules = document.styleSheets[0].cssRules; +console.log(myRules[0].syntax); // "<color>" ``` ## Specifications diff --git a/files/en-us/web/api/cssrule/index.md b/files/en-us/web/api/cssrule/index.md index 4c24cf4219a984e..2d962256fafe7a5 100644 --- a/files/en-us/web/api/cssrule/index.md +++ b/files/en-us/web/api/cssrule/index.md @@ -32,7 +32,7 @@ The **`CSSRule`** interface represents a single CSS rule. There are several type The `CSSRule` interface specifies the properties common to all rules, while properties unique to specific rule types are specified in the more specialized interfaces for those rules' respective types. - {{domxref("CSSRule.cssText")}} - - : Represents the textual representation of the rule, e.g. `"h1,h2 { font-size: 16pt }"` or `"@import 'url'"`. To access or modify parts of the rule (e.g. the value of "font-size" in the example) use the properties on the specialized interface for the rule's type (see above). + - : Represents the textual representation of the rule, e.g., `"h1,h2 { font-size: 16pt }"` or `"@import 'url'"`. To access or modify parts of the rule (e.g., the value of "font-size" in the example) use the properties on the specialized interface for the rule's type (see above). - {{domxref("CSSRule.parentRule")}} {{ReadOnlyInline}} - : Returns the containing rule, otherwise `null`. E.g. if this rule is a style rule inside an {{cssxref("@media")}} block, the parent rule would be that {{domxref("CSSMediaRule")}}. - {{domxref("CSSRule.parentStyleSheet")}} {{ReadOnlyInline}} diff --git a/files/en-us/web/api/cssrule/parentstylesheet/index.md b/files/en-us/web/api/cssrule/parentstylesheet/index.md index e19ca2efa537b3a..a6bb1df88148a5a 100644 --- a/files/en-us/web/api/cssrule/parentstylesheet/index.md +++ b/files/en-us/web/api/cssrule/parentstylesheet/index.md @@ -20,7 +20,7 @@ A {{domxref("StyleSheet")}} object. ```js const docRules = document.styleSheets[0].cssRules; -console.log(docRules[0].parentStyleSheet == document.styleSheets[0]); // returns true +console.log(docRules[0].parentStyleSheet === document.styleSheets[0]); // returns true ``` ## Specifications diff --git a/files/en-us/web/api/cssstyledeclaration/cssfloat/index.md b/files/en-us/web/api/cssstyledeclaration/cssfloat/index.md index d635df47717092e..ca20f703d5e5dd7 100644 --- a/files/en-us/web/api/cssstyledeclaration/cssfloat/index.md +++ b/files/en-us/web/api/cssstyledeclaration/cssfloat/index.md @@ -34,7 +34,7 @@ let myRules = document.styleSheets[0].cssRules; let rule = myRules[0]; console.log(rule.style.cssFloat); // "left" rule.style.cssFloat = "right"; -console.log(rule.style.cssFloat); //right +console.log(rule.style.cssFloat); // "right" ``` ## Specifications diff --git a/files/en-us/web/api/cssstyledeclaration/getpropertypriority/index.md b/files/en-us/web/api/cssstyledeclaration/getpropertypriority/index.md index fedf18a76a368b4..af1dbf53854963d 100644 --- a/files/en-us/web/api/cssstyledeclaration/getpropertypriority/index.md +++ b/files/en-us/web/api/cssstyledeclaration/getpropertypriority/index.md @@ -25,7 +25,7 @@ getPropertyPriority(property) ### Return value -A string that represents the priority (e.g. `"important"`) if one exists. +A string that represents the priority (e.g., `"important"`) if one exists. If none exists, returns the empty string. ## Examples diff --git a/files/en-us/web/api/cssstyledeclaration/parentrule/index.md b/files/en-us/web/api/cssstyledeclaration/parentrule/index.md index dea7839e45fb7e8..527dd1a82aa63d5 100644 --- a/files/en-us/web/api/cssstyledeclaration/parentrule/index.md +++ b/files/en-us/web/api/cssstyledeclaration/parentrule/index.md @@ -10,7 +10,7 @@ browser-compat: api.CSSStyleDeclaration.parentRule The **CSSStyleDeclaration.parentRule** read-only property returns a {{domxref('CSSRule')}} that is the parent of this style -block, e.g. a {{domxref('CSSStyleRule')}} representing the style for a CSS +block, e.g., a {{domxref('CSSStyleRule')}} representing the style for a CSS selector. ## Value diff --git a/files/en-us/web/api/cssstyledeclaration/setproperty/index.md b/files/en-us/web/api/cssstyledeclaration/setproperty/index.md index 6d092a51f0a775d..19c5dded8c76a47 100644 --- a/files/en-us/web/api/cssstyledeclaration/setproperty/index.md +++ b/files/en-us/web/api/cssstyledeclaration/setproperty/index.md @@ -29,12 +29,12 @@ setProperty(propertyName, value, priority) > **Note:** `value` must not contain `"!important"`, that should be set using the `priority` parameter. - `priority` {{optional_inline}} - - : A string allowing the "important" CSS priority to be set. If not - specified, treated as the empty string. The following values are accepted: + - : A string allowing the CSS priority to be set to important. Only the values listed below are accepted: - - String value `"important"` - - Keyword `undefined` - - String empty value `""` + - `"important"` (case-insensitive) for setting the property as `!important`; + - `""`, `undefined`, or `null` for removing the `!important` flag if present. + + Anything else causes the method to return early and no change to happen (unless `value` is empty, in which case the property is removed regardless of the `priority` value). `false`, for example, is not a valid priority value. ### Return value diff --git a/files/en-us/web/api/cssstylerule/index.md b/files/en-us/web/api/cssstylerule/index.md index a2c5421317de889..d3d2f65dd1ef830 100644 --- a/files/en-us/web/api/cssstylerule/index.md +++ b/files/en-us/web/api/cssstylerule/index.md @@ -16,7 +16,7 @@ The **`CSSStyleRule`** interface represents a single CSS style rule. _Inherits properties from its ancestors {{domxref("CSSGroupingRule")}} and {{domxref("CSSRule")}}._ - {{domxref("CSSStyleRule.selectorText")}} - - : Returns the textual representation of the selector for this rule, e.g. `"h1, h2"`. + - : Returns the textual representation of the selector for this rule, e.g., `"h1, h2"`. - {{domxref("CSSStyleRule.style")}} {{ReadOnlyInline}} - : Returns the {{domxref("CSSStyleDeclaration")}} object for the rule. - {{domxref("CSSStyleRule.styleMap")}} {{ReadOnlyInline}} diff --git a/files/en-us/web/api/cssstylerule/style/index.md b/files/en-us/web/api/cssstylerule/style/index.md index 547082a4e1e41c7..a96df6a46728ae6 100644 --- a/files/en-us/web/api/cssstylerule/style/index.md +++ b/files/en-us/web/api/cssstylerule/style/index.md @@ -19,7 +19,7 @@ A {{domxref("CSSStyleDeclaration")}} object, with the following properties: - declarations - : The declared declarations in the rule, in the order they were specified, shorthand properties expanded to longhands. - parent CSS rule - - : The context object, which is an alias for [this](https://heycam.github.io/webidl/#this). + - : The context object, which is an alias for [`this`](https://heycam.github.io/webidl/#this). - owner node - : Null. diff --git a/files/en-us/web/api/cssstylesheet/cssstylesheet/index.md b/files/en-us/web/api/cssstylesheet/cssstylesheet/index.md index 51694e6a1fad77b..177cbe3eb47c26a 100644 --- a/files/en-us/web/api/cssstylesheet/cssstylesheet/index.md +++ b/files/en-us/web/api/cssstylesheet/cssstylesheet/index.md @@ -63,7 +63,7 @@ We then create a {{domxref("ShadowRoot")}} and pass the sheet object to the {{do const node = document.createElement("div"); const shadow = node.attachShadow({ mode: "open" }); -//Adopt the sheet into the shadow DOM +// Adopt the sheet into the shadow DOM shadow.adoptedStyleSheets = [sheet]; ``` @@ -88,6 +88,7 @@ For more examples see {{domxref("ShadowRoot.adoptedStyleSheets")}}. ## See also +- {{domxref("Document.adoptedStyleSheets")}} - [Constructable Stylesheets](https://web.dev/articles/constructable-stylesheets) (web.dev) - [Using the Shadow DOM](/en-US/docs/Web/API/Web_components/Using_shadow_DOM) - [construct-style-sheets-polyfill](https://www.npmjs.com/package/construct-style-sheets-polyfill) diff --git a/files/en-us/web/api/cssstylesheet/insertrule/index.md b/files/en-us/web/api/cssstylesheet/insertrule/index.md index fc68dcda57fbb6d..b790e0ac9d34cda 100644 --- a/files/en-us/web/api/cssstylesheet/insertrule/index.md +++ b/files/en-us/web/api/cssstylesheet/insertrule/index.md @@ -101,19 +101,18 @@ function addStylesheetRules(rules) { // Grab style element's sheet const styleSheet = styleEl.sheet; - for (let i = 0; i < rules.length; i++) { - let j = 1, - rule = rules[i], + for (let rule of rules) { + let i = 1, selector = rule[0], propStr = ""; // If the second argument of a rule is an array of arrays, correct our variables. if (Array.isArray(rule[1][0])) { rule = rule[1]; - j = 0; + i = 0; } - for (let pl = rule.length; j < pl; j++) { - const prop = rule[j]; + for (; i < rule.length; i++) { + const prop = rule[i]; propStr += `${prop[0]}: ${prop[1]}${prop[2] ? " !important" : ""};\n`; } diff --git a/files/en-us/web/api/cssstylevalue/parse_static/index.md b/files/en-us/web/api/cssstylevalue/parse_static/index.md index d406037454a1524..46a13a92c8af0ca 100644 --- a/files/en-us/web/api/cssstylevalue/parse_static/index.md +++ b/files/en-us/web/api/cssstylevalue/parse_static/index.md @@ -43,7 +43,7 @@ const css = CSSStyleValue.parse( ); ``` -```css +```plain CSSTransformValue {0: CSSTranslate, 1: CSSScale, length: 2, is2D: false} ``` diff --git a/files/en-us/web/api/customstateset/index.md b/files/en-us/web/api/customstateset/index.md index e918ab8d47cdd25..ac3ce4d9eb3c6ea 100644 --- a/files/en-us/web/api/customstateset/index.md +++ b/files/en-us/web/api/customstateset/index.md @@ -302,7 +302,7 @@ class QuestionBox extends HTMLElement { The content of the shadow root is set using [`innerHTML`](/en-US/docs/Web/API/ShadowRoot/innerHTML). This defines a {{HTMLElement("slot")}} element that contains the default prompt text "Question" for the element. We then define a `<labeled-checkbox>` custom element with the default text `"Yes"`. -This checkbox is exposed as a shadow part of the question box with the name `checkbox` using the [`part`](/en-US/docs/Web/HTML/Global_attributes/part) attribute. +This checkbox is exposed as a shadow part of the question box with the name `checkbox` using the [`part`](/en-US/docs/Web/HTML/Reference/Global_attributes/part) attribute. Note that the code and styling for the `<labeled-checkbox>` element are exactly the same as in the [previous example](#matching_the_custom_state_of_a_custom_checkbox_element), and are therefore not repeated here. diff --git a/files/en-us/web/api/datatransfer/files/index.md b/files/en-us/web/api/datatransfer/files/index.md index e8e005381309473..0f25d216bbb3906 100644 --- a/files/en-us/web/api/datatransfer/files/index.md +++ b/files/en-us/web/api/datatransfer/files/index.md @@ -13,7 +13,7 @@ The **`files`** read-only property of [`DataTransfer`](/en-US/docs/Web/API/DataT This feature can be used to drag files from a user's desktop to the browser. > [!NOTE] -> The `files` property of [`DataTransfer`](/en-US/docs/Web/API/DataTransfer) objects can only be accessed from within the `drop` event. For all other events, the `files` property will be empty — because its underlying data store will be in a [protected mode](https://html.spec.whatwg.org/multipage/dnd.html#the-drag-data-store). +> The `files` property of [`DataTransfer`](/en-US/docs/Web/API/DataTransfer) objects can only be accessed from within the {{domxref("HTMLElement/drop_event", "drop")}} and {{domxref("Element/paste_event", "paste")}} events. For all other events, the `files` property will be empty — because its underlying data store will be in a [protected mode](https://html.spec.whatwg.org/multipage/dnd.html#the-drag-data-store). ## Value diff --git a/files/en-us/web/api/datatransfer/types/index.md b/files/en-us/web/api/datatransfer/types/index.md index aeebcf600b3d543..20332dddc524dd9 100644 --- a/files/en-us/web/api/datatransfer/types/index.md +++ b/files/en-us/web/api/datatransfer/types/index.md @@ -38,7 +38,7 @@ This example shows the use of the `types` and </style> <script> function dragstart_handler(ev) { - console.log("dragStart: target.id = " + ev.target.id); + console.log(`dragStart: target.id = ${ev.target.id}`); // Add this element's id to the drag payload so the drop handler will // know which element to add to its tree @@ -47,7 +47,7 @@ This example shows the use of the `types` and } function drop_handler(ev) { - console.log("drop: target.id = " + ev.target.id); + console.log(`drop: target.id = ${ev.target.id}`); ev.preventDefault(); // Get the id of the target and add the moved element to the target's DOM diff --git a/files/en-us/web/api/datatransferitem/getasfile/index.md b/files/en-us/web/api/datatransferitem/getasfile/index.md index 1d00311e72d28b2..86d9d3a6fe484a4 100644 --- a/files/en-us/web/api/datatransferitem/getasfile/index.md +++ b/files/en-us/web/api/datatransferitem/getasfile/index.md @@ -34,25 +34,21 @@ This example shows the use of the `getAsFile()` method in a {{domxref("HTMLEleme function dropHandler(ev) { console.log("Drop"); ev.preventDefault(); - const data = ev.dataTransfer.items; - for (let i = 0; i < data.length; i += 1) { - if (data[i].kind === "string" && data[i].type.match("^text/plain")) { + for (const item of ev.dataTransfer.items) { + if (item.kind === "string" && item.type.match("^text/plain")) { // This item is the target node - data[i].getAsString((s) => { + item.getAsString((s) => { ev.target.appendChild(document.getElementById(s)); }); - } else if (data[i].kind === "string" && data[i].type.match("^text/html")) { + } else if (item.kind === "string" && item.type.match("^text/html")) { // Drag data item is HTML console.log("… Drop: HTML"); - } else if ( - data[i].kind === "string" && - data[i].type.match("^text/uri-list") - ) { + } else if (item.kind === "string" && item.type.match("^text/uri-list")) { // Drag data item is URI console.log("… Drop: URI"); - } else if (data[i].kind === "file" && data[i].type.match("^image/")) { + } else if (item.kind === "file" && item.type.match("^image/")) { // Drag data item is an image file - const f = data[i].getAsFile(); + const f = item.getAsFile(); console.log("… Drop: File"); } } diff --git a/files/en-us/web/api/datatransferitem/getasfilesystemhandle/index.md b/files/en-us/web/api/datatransferitem/getasfilesystemhandle/index.md index 259231cdc7ed28f..ed9726a7a6e01f3 100644 --- a/files/en-us/web/api/datatransferitem/getasfilesystemhandle/index.md +++ b/files/en-us/web/api/datatransferitem/getasfilesystemhandle/index.md @@ -10,10 +10,7 @@ browser-compat: api.DataTransferItem.getAsFileSystemHandle {{securecontext_header}}{{APIRef("File System API")}}{{SeeCompatTable}} -The **`getAsFileSystemHandle()`** method of the -{{domxref("DataTransferItem")}} interface returns a {{domxref('FileSystemFileHandle')}} -if the dragged item is a file, or a {{domxref('FileSystemDirectoryHandle')}} if the -dragged item is a directory. +The **`getAsFileSystemHandle()`** method of the {{domxref("DataTransferItem")}} interface returns a {{jsxref('Promise')}} that fulfills with a {{domxref('FileSystemFileHandle')}} if the dragged item is a file, or fulfills with a {{domxref('FileSystemDirectoryHandle')}} if the dragged item is a directory. ## Syntax diff --git a/files/en-us/web/api/datatransferitem/getasstring/index.md b/files/en-us/web/api/datatransferitem/getasstring/index.md index 276d9c01b056361..b50c44e3b6df5c7 100644 --- a/files/en-us/web/api/datatransferitem/getasstring/index.md +++ b/files/en-us/web/api/datatransferitem/getasstring/index.md @@ -8,7 +8,7 @@ browser-compat: api.DataTransferItem.getAsString {{APIRef("HTML Drag and Drop API")}} -The **`DataTransferItem.getAsString()`** method invokes the given callback with the drag data item's string data as the argument if the item's {{domxref("DataTransferItem.kind","kind")}} is a _Plain unicode string_ (i.e. `kind` is `string`). +The **`DataTransferItem.getAsString()`** method invokes the given callback with the drag data item's string data as the argument if the item's {{domxref("DataTransferItem.kind","kind")}} is a _Plain unicode string_ (i.e., `kind` is `string`). ## Syntax @@ -35,25 +35,21 @@ This example shows the use of the `getAsString()` method as an _inline function_ function dropHandler(ev) { console.log("Drop"); ev.preventDefault(); - const data = ev.dataTransfer.items; - for (let i = 0; i < data.length; i += 1) { - if (data[i].kind === "string" && data[i].type.match("^text/plain")) { + for (const item of ev.dataTransfer.items) { + if (item.kind === "string" && item.type.match("^text/plain")) { // This item is the target node - data[i].getAsString((s) => { + item.getAsString((s) => { ev.target.appendChild(document.getElementById(s)); }); - } else if (data[i].kind === "string" && data[i].type.match("^text/html")) { + } else if (item.kind === "string" && item.type.match("^text/html")) { // Drag data item is HTML console.log("… Drop: HTML"); - } else if ( - data[i].kind === "string" && - data[i].type.match("^text/uri-list") - ) { + } else if (item.kind === "string" && item.type.match("^text/uri-list")) { // Drag data item is URI console.log("… Drop: URI"); - } else if (data[i].kind === "file" && data[i].type.match("^image/")) { + } else if (item.kind === "file" && item.type.match("^image/")) { // Drag data item is an image file - const f = data[i].getAsFile(); + const f = item.getAsFile(); console.log("… Drop: File"); } } diff --git a/files/en-us/web/api/datatransferitem/index.md b/files/en-us/web/api/datatransferitem/index.md index 7c4a1431845c8bc..d817543f4a38ee4 100644 --- a/files/en-us/web/api/datatransferitem/index.md +++ b/files/en-us/web/api/datatransferitem/index.md @@ -25,7 +25,7 @@ This interface has no constructor. - {{domxref("DataTransferItem.getAsFile()")}} - : Returns the {{domxref("File")}} object associated with the drag data item (or null if the drag item is not a file). - {{domxref("DataTransferItem.getAsFileSystemHandle()")}} {{Experimental_Inline}} - - : Returns a {{domxref('FileSystemFileHandle')}} if the dragged item is a file, or a {{domxref('FileSystemDirectoryHandle')}} if the dragged item is a directory. + - : Returns a {{jsxref('Promise')}} that fulfills with a {{domxref('FileSystemFileHandle')}} if the dragged item is a file, or fulfills with a {{domxref('FileSystemDirectoryHandle')}} if the dragged item is a directory. - {{domxref("DataTransferItem.getAsString()")}} - : Invokes the specified callback with the drag data item string as its argument. - {{domxref("DataTransferItem.webkitGetAsEntry()")}} diff --git a/files/en-us/web/api/datatransferitem/kind/index.md b/files/en-us/web/api/datatransferitem/kind/index.md index cd7852272f9fea7..881ba27e2a51688 100644 --- a/files/en-us/web/api/datatransferitem/kind/index.md +++ b/files/en-us/web/api/datatransferitem/kind/index.md @@ -28,19 +28,18 @@ This example shows the use of the `kind` property. function dropHandler(ev) { console.log("Drop"); ev.preventDefault(); - const data = event.dataTransfer.items; - for (let i = 0; i < data.length; i += 1) { - if (data[i].kind === "string" && data[i].type.match("^text/plain")) { + for (const item of ev.dataTransfer.items) { + if (item.kind === "string" && item.type.match("^text/plain")) { // This item is the target node - data[i].getAsString((s) => { + item.getAsString((s) => { ev.target.appendChild(document.getElementById(s)); }); - } else if (data[i].kind === "string" && data[i].type.match("^text/html")) { + } else if (item.kind === "string" && item.type.match("^text/html")) { // Drag data item is HTML console.log("… Drop: HTML"); - } else if (data[i].kind === "file" && data[i].type.match("^image/")) { + } else if (item.kind === "file" && item.type.match("^image/")) { // Drag data item is an image file - const f = data[i].getAsFile(); + const f = item.getAsFile(); console.log("… Drop: File"); } } diff --git a/files/en-us/web/api/datatransferitem/type/index.md b/files/en-us/web/api/datatransferitem/type/index.md index 1e907658398bc34..ac2c2cb754b8096 100644 --- a/files/en-us/web/api/datatransferitem/type/index.md +++ b/files/en-us/web/api/datatransferitem/type/index.md @@ -25,25 +25,21 @@ This example shows the use of the `type` property. function dropHandler(ev) { console.log("Drop"); ev.preventDefault(); - const data = ev.dataTransfer.items; - for (let i = 0; i < data.length; i += 1) { - if (data[i].kind === "string" && data[i].type.match("^text/plain")) { + for (const item of ev.dataTransfer.items) { + if (item.kind === "string" && item.type.match("^text/plain")) { // This item is the target node - data[i].getAsString((s) => { + item.getAsString((s) => { ev.target.appendChild(document.getElementById(s)); }); - } else if (data[i].kind === "string" && data[i].type.match("^text/html")) { + } else if (item.kind === "string" && item.type.match("^text/html")) { // Drag data item is HTML console.log("… Drop: HTML"); - } else if ( - data[i].kind === "string" && - data[i].type.match("^text/uri-list") - ) { + } else if (item.kind === "string" && item.type.match("^text/uri-list")) { // Drag data item is URI console.log("… Drop: URI"); - } else if (data[i].kind === "file" && data[i].type.match("^image/")) { + } else if (item.kind === "file" && item.type.match("^image/")) { // Drag data item is an image file - const f = data[i].getAsFile(); + const f = item.getAsFile(); console.log("… Drop: File"); } } @@ -61,4 +57,4 @@ function dropHandler(ev) { ## See also - {{domxref("DataTransfer.types()")}} -- [List of common MIME types](/en-US/docs/Web/HTTP/MIME_types/Common_types) +- [List of common MIME types](/en-US/docs/Web/HTTP/Guides/MIME_types/Common_types) diff --git a/files/en-us/web/api/datatransferitem/webkitgetasentry/index.md b/files/en-us/web/api/datatransferitem/webkitgetasentry/index.md index 05c748cc29fa486..e42b600e3858a70 100644 --- a/files/en-us/web/api/datatransferitem/webkitgetasentry/index.md +++ b/files/en-us/web/api/datatransferitem/webkitgetasentry/index.md @@ -153,11 +153,11 @@ dropzone.addEventListener( event.preventDefault(); listing.textContent = ""; - for (let i = 0; i < items.length; i++) { - let item = items[i].webkitGetAsEntry(); + for (const item of items) { + const entry = item.webkitGetAsEntry(); - if (item) { - scanFiles(item, listing); + if (entry) { + scanFiles(entry, listing); } } }, diff --git a/files/en-us/web/api/datatransferitemlist/add/index.md b/files/en-us/web/api/datatransferitemlist/add/index.md index 627573abb8ccc58..ed0f60ddff6ee87 100644 --- a/files/en-us/web/api/datatransferitemlist/add/index.md +++ b/files/en-us/web/api/datatransferitemlist/add/index.md @@ -102,25 +102,21 @@ function dragstart_handler(ev) { function drop_handler(ev) { console.log("Drop"); ev.preventDefault(); - const data = event.dataTransfer.items; // Loop through the dropped items and log their data - for (let i = 0; i < data.length; i++) { - if (data[i].kind === "string" && data[i].type.match("^text/plain")) { + for (const item of event.dataTransfer.items) { + if (item.kind === "string" && item.type.match("^text/plain")) { // This item is the target node - data[i].getAsString((s) => { + item.getAsString((s) => { ev.target.appendChild(document.getElementById(s)); }); - } else if (data[i].kind === "string" && data[i].type.match("^text/html")) { + } else if (item.kind === "string" && item.type.match("^text/html")) { // Drag data item is HTML - data[i].getAsString((s) => { + item.getAsString((s) => { console.log(`… Drop: HTML = ${s}`); }); - } else if ( - data[i].kind === "string" && - data[i].type.match("^text/uri-list") - ) { + } else if (item.kind === "string" && item.type.match("^text/uri-list")) { // Drag data item is URI - data[i].getAsString((s) => { + item.getAsString((s) => { console.log(`… Drop: URI = ${s}`); }); } diff --git a/files/en-us/web/api/decompressionstream/readable/index.md b/files/en-us/web/api/decompressionstream/readable/index.md index 07c406ca336f618..967d08d5570e4de 100644 --- a/files/en-us/web/api/decompressionstream/readable/index.md +++ b/files/en-us/web/api/decompressionstream/readable/index.md @@ -19,8 +19,8 @@ A {{domxref("ReadableStream")}}. The following example returns a {{domxref("ReadableStream")}} from a `DecompressionStream`. ```js -let stream = new DecompressionStream("gzip"); -console.log(stream.readable); //a ReadableStream +const stream = new DecompressionStream("gzip"); +console.log(stream.readable); // A ReadableStream ``` ## Specifications diff --git a/files/en-us/web/api/dedicatedworkerglobalscope/message_event/index.md b/files/en-us/web/api/dedicatedworkerglobalscope/message_event/index.md index ec0e24a49bfdb0c..9273580eb9fb96b 100644 --- a/files/en-us/web/api/dedicatedworkerglobalscope/message_event/index.md +++ b/files/en-us/web/api/dedicatedworkerglobalscope/message_event/index.md @@ -8,7 +8,7 @@ browser-compat: api.DedicatedWorkerGlobalScope.message_event {{APIRef("Web Workers API")}}{{AvailableInWorkers("dedicated")}} -The `message` event is fired on a {{domxref('DedicatedWorkerGlobalScope')}} object when the worker receives a message from its parent (i.e. when the parent sends a message using [`Worker.postMessage()`](/en-US/docs/Web/API/Worker/postMessage)). +The `message` event is fired on a {{domxref('DedicatedWorkerGlobalScope')}} object when the worker receives a message from its parent (i.e., when the parent sends a message using [`Worker.postMessage()`](/en-US/docs/Web/API/Worker/postMessage)). This event is not cancellable and does not bubble. @@ -16,10 +16,10 @@ This event is not cancellable and does not bubble. Use the event name in methods like {{domxref("EventTarget.addEventListener", "addEventListener()")}}, or set an event handler property. -```js -addEventListener("message", (event) => {}); +```js-nolint +addEventListener("message", (event) => { }) -onmessage = (event) => {}; +onmessage = (event) => { } ``` ## Event type @@ -41,7 +41,7 @@ _This interface also inherits properties from its parent, {{domxref("Event")}}._ - {{domxref("MessageEvent.source")}} {{ReadOnlyInline}} - : A `MessageEventSource` (which can be a {{domxref("Window")}}, {{domxref("MessagePort")}}, or {{domxref("ServiceWorker")}} object) representing the message emitter. - {{domxref("MessageEvent.ports")}} {{ReadOnlyInline}} - - : An array of {{domxref("MessagePort")}} objects representing the ports associated with the channel the message is being sent through (where appropriate, e.g. in channel messaging or when sending a message to a shared worker). + - : An array of {{domxref("MessagePort")}} objects representing the ports associated with the channel the message is being sent through (where appropriate, e.g., in channel messaging or when sending a message to a shared worker). ## Example diff --git a/files/en-us/web/api/dedicatedworkerglobalscope/messageerror_event/index.md b/files/en-us/web/api/dedicatedworkerglobalscope/messageerror_event/index.md index 8c542ad0ef3e4bd..23fd848f1c6ad47 100644 --- a/files/en-us/web/api/dedicatedworkerglobalscope/messageerror_event/index.md +++ b/files/en-us/web/api/dedicatedworkerglobalscope/messageerror_event/index.md @@ -16,10 +16,10 @@ This event is not cancellable and does not bubble. Use the event name in methods like {{domxref("EventTarget.addEventListener", "addEventListener()")}}, or set an event handler property. -```js -addEventListener("messageerror", (event) => {}); +```js-nolint +addEventListener("messageerror", (event) => { }) -onmessageerror = (event) => {}; +onmessageerror = (event) => { } ``` ## Event type @@ -41,7 +41,7 @@ _This interface also inherits properties from its parent, {{domxref("Event")}}._ - {{domxref("MessageEvent.source")}} {{ReadOnlyInline}} - : A `MessageEventSource` (which can be a {{glossary("WindowProxy")}}, {{domxref("MessagePort")}}, or {{domxref("ServiceWorker")}} object) representing the message emitter. - {{domxref("MessageEvent.ports")}} {{ReadOnlyInline}} - - : An array of {{domxref("MessagePort")}} objects representing the ports associated with the channel the message is being sent through (where appropriate, e.g. in channel messaging or when sending a message to a shared worker). + - : An array of {{domxref("MessagePort")}} objects representing the ports associated with the channel the message is being sent through (where appropriate, e.g., in channel messaging or when sending a message to a shared worker). ## Examples diff --git a/files/en-us/web/api/dedicatedworkerglobalscope/rtctransform_event/index.md b/files/en-us/web/api/dedicatedworkerglobalscope/rtctransform_event/index.md index f4af4ac2318b46d..ea35a5dd4d05d50 100644 --- a/files/en-us/web/api/dedicatedworkerglobalscope/rtctransform_event/index.md +++ b/files/en-us/web/api/dedicatedworkerglobalscope/rtctransform_event/index.md @@ -18,10 +18,10 @@ This event is not cancellable and does not bubble. Use the event name in methods like {{domxref("EventTarget.addEventListener", "addEventListener()")}}, or set an event handler property. -```js -addEventListener("rtctransform", (event) => {}); +```js-nolint +addEventListener("rtctransform", (event) => { }) -onrtctransform = (event) => {}; +onrtctransform = (event) => { } ``` ## Event type @@ -46,13 +46,13 @@ The `event.transformer` is a {{domxref("RTCRtpScriptTransformer")}}, the worker addEventListener("rtctransform", (event) => { let transform; // Select a transform based on passed options - if (event.transformer.options.name == "senderTransform") + if (event.transformer.options.name === "senderTransform") transform = createSenderTransform(); // A TransformStream - else if (event.transformer.options.name == "receiverTransform") + else if (event.transformer.options.name === "receiverTransform") transform = createReceiverTransform(); // A TransformStream else return; - //Pipe frames from the readable to writeable through TransformStream + // Pipe frames from the readable to writeable through TransformStream event.transformer.readable .pipeThrough(transform) .pipeTo(event.transformer.writable); diff --git a/files/en-us/web/api/deferredrequestinit/index.md b/files/en-us/web/api/deferredrequestinit/index.md new file mode 100644 index 000000000000000..f4e8075f41d1536 --- /dev/null +++ b/files/en-us/web/api/deferredrequestinit/index.md @@ -0,0 +1,67 @@ +--- +title: DeferredRequestInit +slug: Web/API/DeferredRequestInit +page-type: web-api-interface +status: + - experimental +browser-compat: api.Window.fetchLater +--- + +{{DefaultAPISidebar("fetchLater API")}}{{SeeCompatTable}} + +The **`DeferredRequestInit`** dictionary of the [`fetchLater()` API](/en-US/docs/Web/API/fetchLater_API) represents the set of options that can be used to configure a deferred fetch request. + +The `DeferredRequestInit` object is passed directly into the {{domxref("window.fetchLater()")}} function call as the second argument. + +## Instance properties + +This dictionary extends the {{domxref("RequestInit")}} dictionary with the addition of the following properties: + +- `activateAfter` {{optional_inline}} + + - : A {{ domxref("DOMHighResTimeStamp") }} indicating a timeout in milliseconds after which the fetch request should be sent. The fetch can be sent earlier on navigating away. The _actual_ sending time is unknown, as the browser may wait for a longer or shorter time, for example, to optimize the batching of deferred fetches. If the `activateAfter` property is not provided, the deferred fetch waits until the end of the page visit (including entering the [bfcache](/en-US/docs/Glossary/bfcache)). + +### Exceptions + +- `RangeError` {{domxref("DOMException")}} + - : Raised when a negative `activateAfter` is provided. + +## Examples + +### Defer a `GET` request until the page is destroyed or enters the bfcache + +In this example, no `DeferredRequestInit` object is provided and no timeout is used: + +```js +fetchLater("/send_beacon"); +``` + +### Defer a `POST` request for around 1 minute + +In this example we create a {{domxref("Request")}}, and provide an `activateAfter` value to delay sending the request for 60,000 milliseconds (or one minute): + +```js +fetchLater("/send_beacon", { + method: "POST", + body: getBeaconData(), + activateAfter: 60000, // 1 minute +}); +``` + +> [!NOTE] +> The actual sending time is unknown, as the browser may wait for a longer or shorter period of time, for example to optimize batching of deferred fetches. + +## Specifications + +{{Specifications}} + +## Browser compatibility + +{{Compat}} + +## See also + +- [Using Fetch](/en-US/docs/Web/API/Fetch_API/Using_Fetch) +- [ServiceWorker API](/en-US/docs/Web/API/Service_Worker_API) +- [HTTP access control (CORS)](/en-US/docs/Web/HTTP/Guides/CORS) +- [HTTP](/en-US/docs/Web/HTTP) diff --git a/files/en-us/web/api/delegatedinktrailpresenter/expectedimprovement/index.md b/files/en-us/web/api/delegatedinktrailpresenter/expectedimprovement/index.md index 3e0a5ecfbb5c9bb..04cd56d14bc5da5 100644 --- a/files/en-us/web/api/delegatedinktrailpresenter/expectedimprovement/index.md +++ b/files/en-us/web/api/delegatedinktrailpresenter/expectedimprovement/index.md @@ -22,10 +22,10 @@ A number. ```js async function inkInit() { const ink = navigator.ink; - let presenter = await ink.requestPresenter({ presentationArea: canvas }); + const presenter = await ink.requestPresenter({ presentationArea: canvas }); console.log(presenter.expectedImprovement); - //... + // … } ``` diff --git a/files/en-us/web/api/delegatedinktrailpresenter/index.md b/files/en-us/web/api/delegatedinktrailpresenter/index.md index a33f2193a5276b7..632d16fda2fa8fb 100644 --- a/files/en-us/web/api/delegatedinktrailpresenter/index.md +++ b/files/en-us/web/api/delegatedinktrailpresenter/index.md @@ -52,20 +52,20 @@ canvas.addEventListener("pointermove", (evt) => { const pointSize = 10; ctx.fillStyle = "#000000"; ctx.fillRect(evt.pageX, evt.pageY, pointSize, pointSize); - if (move_cnt == 50) { + if (move_cnt === 50) { let r = getRandomInt(0, 255); let g = getRandomInt(0, 255); let b = getRandomInt(0, 255); style = { - color: "rgb(" + r + " " + g + " " + b + " / 100%)", + color: `rgb(${r} ${g} ${b} / 100%)`, diameter: 10, }; move_cnt = 0; document.getElementById("div").style.backgroundColor = - "rgb(" + r + " " + g + " " + b + " / 100%)"; + `rgb(${r} ${g} ${b} / 100%)`; } move_cnt += 1; - presenter.then(function (v) { + presenter.then((v) => { v.updateInkTrailStartPoint(evt, style); }); }); diff --git a/files/en-us/web/api/delegatedinktrailpresenter/presentationarea/index.md b/files/en-us/web/api/delegatedinktrailpresenter/presentationarea/index.md index 0fc5ebbcc64ef20..f8dba2ac16a06ec 100644 --- a/files/en-us/web/api/delegatedinktrailpresenter/presentationarea/index.md +++ b/files/en-us/web/api/delegatedinktrailpresenter/presentationarea/index.md @@ -25,10 +25,10 @@ An {{domxref("Element")}}. ```js async function inkInit() { const ink = navigator.ink; - let presenter = await ink.requestPresenter({ presentationArea: canvas }); + const presenter = await ink.requestPresenter({ presentationArea: canvas }); console.log(presenter.presentationArea); - //... + // … } ``` diff --git a/files/en-us/web/api/delegatedinktrailpresenter/updateinktrailstartpoint/index.md b/files/en-us/web/api/delegatedinktrailpresenter/updateinktrailstartpoint/index.md index 33c0bc51455670e..3ea574b8c9ad9a6 100644 --- a/files/en-us/web/api/delegatedinktrailpresenter/updateinktrailstartpoint/index.md +++ b/files/en-us/web/api/delegatedinktrailpresenter/updateinktrailstartpoint/index.md @@ -90,7 +90,7 @@ canvas.addEventListener("pointermove", async (evt) => { const pointSize = 10; ctx.fillStyle = style.color; ctx.fillRect(evt.pageX, evt.pageY, pointSize, pointSize); - if (move_cnt == 20) { + if (move_cnt === 20) { const r = getRandomInt(0, 255); const g = getRandomInt(0, 255); const b = getRandomInt(0, 255); diff --git a/files/en-us/web/api/device_memory_api/index.md b/files/en-us/web/api/device_memory_api/index.md index 427cc9d96903d9f..1ec7088640db4be 100644 --- a/files/en-us/web/api/device_memory_api/index.md +++ b/files/en-us/web/api/device_memory_api/index.md @@ -27,7 +27,7 @@ const RAM = navigator.deviceMemory; ### Client Hints -You may also use the [Client Hints](/en-US/docs/Web/HTTP/Client_hints) HTTP Header with the `Device-Memory` directive to retrieve the same approximate RAM capacity. +You may also use the [Client Hints](/en-US/docs/Web/HTTP/Guides/Client_hints) HTTP Header with the `Device-Memory` directive to retrieve the same approximate RAM capacity. ## Interfaces diff --git a/files/en-us/web/api/devicemotioneventrotationrate/alpha/index.md b/files/en-us/web/api/devicemotioneventrotationrate/alpha/index.md index 7a332f547d419f1..55121b1f8baf395 100644 --- a/files/en-us/web/api/devicemotioneventrotationrate/alpha/index.md +++ b/files/en-us/web/api/devicemotioneventrotationrate/alpha/index.md @@ -13,7 +13,7 @@ The **`alpha`** read-only property of the {{domxref("DeviceMotionEventRotationRa ## Value A `double` indicating the rate of rotation around the Z axis, in degrees per second. -See [Accelerometer values explained](/en-US/docs/Web/API/Device_orientation_events/Detecting_device_orientation#accelerometer_values_explained) for details. +See [Orientation and motion data explained](/en-US/docs/Web/API/Device_orientation_events/Orientation_and_motion_data_explained) for details. ## Specifications diff --git a/files/en-us/web/api/devicemotioneventrotationrate/beta/index.md b/files/en-us/web/api/devicemotioneventrotationrate/beta/index.md index f00adff5146ca23..52a3aec14d1f0ad 100644 --- a/files/en-us/web/api/devicemotioneventrotationrate/beta/index.md +++ b/files/en-us/web/api/devicemotioneventrotationrate/beta/index.md @@ -13,7 +13,7 @@ The **`beta`** read-only property of the {{domxref("DeviceMotionEventRotationRat ## Value A `double` indicating the rate of rotation around the X axis, in degrees per second. -See [Accelerometer values explained](/en-US/docs/Web/API/Device_orientation_events/Detecting_device_orientation#accelerometer_values_explained) for details. +See [Orientation and motion data explained](/en-US/docs/Web/API/Device_orientation_events/Orientation_and_motion_data_explained) for details. ## Specifications diff --git a/files/en-us/web/api/devicemotioneventrotationrate/gamma/index.md b/files/en-us/web/api/devicemotioneventrotationrate/gamma/index.md index 707a6bcfd736266..c103dd3e4f81720 100644 --- a/files/en-us/web/api/devicemotioneventrotationrate/gamma/index.md +++ b/files/en-us/web/api/devicemotioneventrotationrate/gamma/index.md @@ -13,7 +13,7 @@ The **`gamma`** read-only property of the {{domxref("DeviceMotionEventRotationRa ## Value A `double` indicating the rate of rotation around the Y axis, in degrees per second. -See [Accelerometer values explained](/en-US/docs/Web/API/Device_orientation_events/Detecting_device_orientation#accelerometer_values_explained) for details. +See [Orientation and motion data explained](/en-US/docs/Web/API/Device_orientation_events/Orientation_and_motion_data_explained) for details. ## Specifications diff --git a/files/en-us/web/api/deviceposture/change_event/index.md b/files/en-us/web/api/deviceposture/change_event/index.md index 127de9477801c12..7f2d01cc702827e 100644 --- a/files/en-us/web/api/deviceposture/change_event/index.md +++ b/files/en-us/web/api/deviceposture/change_event/index.md @@ -16,10 +16,10 @@ The **`change`** event of the {{domxref("DevicePosture")}} interface fires when Use the event name in methods like {{domxref("EventTarget.addEventListener", "addEventListener()")}}, or set an event handler property. -```js -addEventListener("change", (event) => {}); +```js-nolint +addEventListener("change", (event) => { }) -onchange = (event) => {}; +onchange = (event) => { } ``` ## Event type diff --git a/files/en-us/web/api/directoryreadersync/index.md b/files/en-us/web/api/directoryreadersync/index.md index 2162f9152361934..030f702730c880b 100644 --- a/files/en-us/web/api/directoryreadersync/index.md +++ b/files/en-us/web/api/directoryreadersync/index.md @@ -84,7 +84,7 @@ self.onmessage = (e) => { } try { - const fs = requestFileSystemSync(TEMPORARY, 1024 * 1024 /*1MB*/); + const fs = requestFileSystemSync(TEMPORARY, 1024 * 1024 /* 1MB */); getAllEntries(fs.root.createReader()); diff --git a/files/en-us/web/api/document/adoptedstylesheets/index.md b/files/en-us/web/api/document/adoptedstylesheets/index.md index c28aa873d3e2a22..0b5d7c93ef3b3ef 100644 --- a/files/en-us/web/api/document/adoptedstylesheets/index.md +++ b/files/en-us/web/api/document/adoptedstylesheets/index.md @@ -80,7 +80,7 @@ We can share a stylesheet to a shadow root in a similar way. const node = document.createElement("div"); const shadow = node.attachShadow({ mode: "open" }); -//Adopt the same sheet into the shadow DOM +// Adopt the same sheet into the shadow DOM shadow.adoptedStyleSheets = [sheet]; ``` diff --git a/files/en-us/web/api/document/afterscriptexecute_event/index.md b/files/en-us/web/api/document/afterscriptexecute_event/index.md index 0177997fae4fd9c..9ec217c7588928a 100644 --- a/files/en-us/web/api/document/afterscriptexecute_event/index.md +++ b/files/en-us/web/api/document/afterscriptexecute_event/index.md @@ -17,10 +17,10 @@ The `afterscriptexecute` event fires when a static {{HTMLElement("script")}} ele Use the event name in methods like {{domxref("EventTarget.addEventListener", "addEventListener()")}}, or set an event handler property. -```js -addEventListener("afterscriptexecute", (event) => {}); +```js-nolint +addEventListener("afterscriptexecute", (event) => { }) -onafterscriptexecute = (event) => {}; +onafterscriptexecute = (event) => { } ``` ## Event type diff --git a/files/en-us/web/api/document/anchors/index.md b/files/en-us/web/api/document/anchors/index.md index 576e7b3036199ca..1c7fea46158d78f 100644 --- a/files/en-us/web/api/document/anchors/index.md +++ b/files/en-us/web/api/document/anchors/index.md @@ -40,7 +40,7 @@ on the page: for (const anchor of document.anchors) { const li = document.createElement("li"); const newAnchor = document.createElement("a"); - newAnchor.href = "#" + anchor.name; + newAnchor.href = `#${anchor.name}`; newAnchor.textContent = anchor.text; li.appendChild(newAnchor); toc.appendChild(li); diff --git a/files/en-us/web/api/document/beforescriptexecute_event/index.md b/files/en-us/web/api/document/beforescriptexecute_event/index.md index f58be6f5b75dbee..99c8ac1b49e2614 100644 --- a/files/en-us/web/api/document/beforescriptexecute_event/index.md +++ b/files/en-us/web/api/document/beforescriptexecute_event/index.md @@ -17,10 +17,10 @@ The `beforescriptexecute` event fires when a static {{HTMLElement("script")}} is Use the event name in methods like {{domxref("EventTarget.addEventListener", "addEventListener()")}}, or set an event handler property. -```js -addEventListener("beforescriptexecute", (event) => {}); +```js-nolint +addEventListener("beforescriptexecute", (event) => { }) -onbeforescriptexecute = (event) => {}; +onbeforescriptexecute = (event) => { } ``` ## Event type diff --git a/files/en-us/web/api/document/browsingtopics/index.md b/files/en-us/web/api/document/browsingtopics/index.md index 538b84fa4fc9c60..a13bad7e5108326 100644 --- a/files/en-us/web/api/document/browsingtopics/index.md +++ b/files/en-us/web/api/document/browsingtopics/index.md @@ -54,13 +54,13 @@ A {{jsxref("Promise")}} that fulfills with an array of up to three objects repre The exact property values may vary by browser implementation. An example object from Chrome might look as follows: -```js +```json { - configVersion: "chrome.1", - modelVersion: "1", - taxonomyVersion: "1", - topic: 43, - version: "chrome.1:1:1" + "configVersion": "chrome.1", + "modelVersion": "1", + "taxonomyVersion": "1", + "topic": 43, + "version": "chrome.1:1:1" } ``` @@ -68,7 +68,7 @@ The exact property values may vary by browser implementation. An example object - `NotAllowedError` {{domxref("DOMException")}} - : Thrown if: - - Usage of the [Topics API](/en-US/docs/Web/API/Topics_API) is disallowed by a {{httpheader('Permissions-Policy/browsing-topics','browsing-topics')}} [Permissions Policy](/en-US/docs/Web/HTTP/Permissions_Policy). + - Usage of the [Topics API](/en-US/docs/Web/API/Topics_API) is disallowed by a {{httpheader('Permissions-Policy/browsing-topics','browsing-topics')}} [Permissions Policy](/en-US/docs/Web/HTTP/Guides/Permissions_Policy). - The calling site does not have the Topics API included in a successful [privacy sandbox enrollment process](/en-US/docs/Web/Privacy/Guides/Privacy_sandbox/Enrollment). ## Examples diff --git a/files/en-us/web/api/document/compatmode/index.md b/files/en-us/web/api/document/compatmode/index.md index a27b3d0cc569fab..d31446f4baba76c 100644 --- a/files/en-us/web/api/document/compatmode/index.md +++ b/files/en-us/web/api/document/compatmode/index.md @@ -9,7 +9,7 @@ browser-compat: api.Document.compatMode {{ ApiRef("DOM") }} The **`Document.compatMode`** read-only property indicates -whether the document is rendered in [Quirks mode](/en-US/docs/Web/HTML/Quirks_Mode_and_Standards_Mode) or +whether the document is rendered in [Quirks mode](/en-US/docs/Web/HTML/Guides/Quirks_mode_and_standards_mode) or Standards mode. ## Value diff --git a/files/en-us/web/api/document/cookie/index.md b/files/en-us/web/api/document/cookie/index.md index f67985a06e5a390..5140d14e8559819 100644 --- a/files/en-us/web/api/document/cookie/index.md +++ b/files/en-us/web/api/document/cookie/index.md @@ -8,7 +8,7 @@ browser-compat: api.Document.cookie {{APIRef("DOM")}} -The {{domxref("Document")}} property `cookie` lets you read and write [cookies](/en-US/docs/Web/HTTP/Cookies) associated with the document. +The {{domxref("Document")}} property `cookie` lets you read and write [cookies](/en-US/docs/Web/HTTP/Guides/Cookies) associated with the document. It serves as a getter and setter for the actual values of the cookies. ## Syntax @@ -19,7 +19,7 @@ It serves as a getter and setter for the actual values of the cookies. allCookies = document.cookie; ``` -In the code above `allCookies` is a string containing a semicolon-separated list of all cookies (i.e. `key=value` pairs). +In the code above `allCookies` is a string containing a semicolon-separated list of all cookies (i.e., `key=value` pairs). Note that each _key_ and _value_ may be surrounded by whitespace (space and tab characters): in fact, {{RFC(6265)}} mandates a single space after each semicolon, but some user agents may not abide by this. ### Write a new cookie @@ -53,9 +53,9 @@ In the code above, `newCookie` is a string of form `key=value`, specifying the c - `;partitioned`: Indicates that the cookie should be stored using partitioned storage. See [Cookies Having Independent Partitioned State (CHIPS)](/en-US/docs/Web/Privacy/Guides/Privacy_sandbox/Partitioned_cookies) for more details. - - `;path=path`: The value of the cookie's `Path` attribute (See [Define where cookies are sent](/en-US/docs/Web/HTTP/Cookies#define_where_cookies_are_sent) for more information). + - `;path=path`: The value of the cookie's `Path` attribute (See [Define where cookies are sent](/en-US/docs/Web/HTTP/Guides/Cookies#define_where_cookies_are_sent) for more information). - - `;samesite`: The `SameSite` attribute of a {{httpheader("Set-Cookie")}} header can be set by a server to specify when the cookie will be sent. Possible values are `lax`, `strict` or `none` (see also [Controlling third-party cookies with `SameSite`](/en-US/docs/Web/HTTP/Cookies#controlling_third-party_cookies_with_samesite)). + - `;samesite`: The `SameSite` attribute of a {{httpheader("Set-Cookie")}} header can be set by a server to specify when the cookie will be sent. Possible values are `lax`, `strict` or `none` (see also [Controlling third-party cookies with `SameSite`](/en-US/docs/Web/HTTP/Guides/Cookies#controlling_third-party_cookies_with_samesite)). - The `lax` value will send the cookie for all same-site requests and top-level navigation GET requests. This is sufficient for user tracking, but it will prevent many [Cross-Site Request Forgery](/en-US/docs/Glossary/CSRF) (CSRF) attacks. @@ -357,7 +357,7 @@ Accept: */* ## See also -- [HTTP cookies](/en-US/docs/Web/HTTP/Cookies) +- [HTTP cookies](/en-US/docs/Web/HTTP/Guides/Cookies) - [DOM Storage](/en-US/docs/Web/API/Web_Storage_API) - [`URL.pathname`](/en-US/docs/Web/API/URL/pathname) - {{jsxref("Date.toUTCString()")}} diff --git a/files/en-us/web/api/document/copy_event/index.md b/files/en-us/web/api/document/copy_event/index.md deleted file mode 100644 index dc952acccd53dac..000000000000000 --- a/files/en-us/web/api/document/copy_event/index.md +++ /dev/null @@ -1,61 +0,0 @@ ---- -title: "Document: copy event" -short-title: copy -slug: Web/API/Document/copy_event -page-type: web-api-event -browser-compat: api.Element.copy_event ---- - -{{APIRef}} - -The **`copy`** event fires when the user initiates a copy action through the browser's user interface. - -The original target for this event is the {{domxref("Element")}} that was the intended target of the copy action. You can listen for this event on the {{domxref("Document")}} interface to handle it in the capture or bubbling phases. For full details on this event please see the page on the [Element: copy event](/en-US/docs/Web/API/Element/copy_event). - -## Syntax - -Use the event name in methods like {{domxref("EventTarget.addEventListener", "addEventListener()")}}, or set an event handler property. - -```js -addEventListener("copy", (event) => {}); - -oncopy = (event) => {}; -``` - -## Event type - -A {{domxref("ClipboardEvent")}}. Inherits from {{domxref("Event")}}. - -{{InheritanceDiagram("ClipboardEvent")}} - -## Examples - -To be informed when a user copies data from the webpage to their clipboard, you can add a handler to your {{domxref("Document")}} instance using {{domxref("EventTarget.addEventListener", "addEventListener()")}}, like this: - -```js -document.addEventListener("copy", (event) => { - /* the session has shut down */ -}); -``` - -Alternatively, you can use the `Document.oncopy` event handler property to establish a handler for the `copy` event: - -```js -document.oncopy = (event) => { - /* the session has shut down */ -}; -``` - -## Specifications - -{{Specifications}} - -## Browser compatibility - -{{Compat}} - -## See also - -- Related events: {{domxref("Document/cut_event", "cut")}}, {{domxref("Document/paste_event", "paste")}} -- This event on {{domxref("Element")}} targets: {{domxref("Element/copy_event", "copy")}} -- This event on {{domxref("Window")}} targets: {{domxref("Window/copy_event", "copy")}} diff --git a/files/en-us/web/api/document/createelement/index.md b/files/en-us/web/api/document/createelement/index.md index 41fa7086ae3f84d..dd221e87611aa0c 100644 --- a/files/en-us/web/api/document/createelement/index.md +++ b/files/en-us/web/api/document/createelement/index.md @@ -83,7 +83,7 @@ function addElement() { ### Web component example > [!NOTE] -> Check the [browser compatibility](#browser_compatibility) section for support, and the [`is`](/en-US/docs/Web/HTML/Global_attributes/is) attribute reference for caveats on implementation reality of custom built-in elements. +> Check the [browser compatibility](#browser_compatibility) section for support, and the [`is`](/en-US/docs/Web/HTML/Reference/Global_attributes/is) attribute reference for caveats on implementation reality of custom built-in elements. The following example snippet is taken from our [expanding-list-web-component](https://github.com/mdn/web-components-examples/tree/main/expanding-list-web-component) example ([see it live also](https://mdn.github.io/web-components-examples/expanding-list-web-component/)). In this case, our custom element extends the {{domxref("HTMLUListElement")}}, which represents the {{htmlelement("ul")}} element. @@ -109,10 +109,10 @@ If we wanted to create an instance of this element programmatically, we'd use a let expandingList = document.createElement("ul", { is: "expanding-list" }); ``` -The new element will be given an [`is`](/en-US/docs/Web/HTML/Global_attributes/is) attribute whose value is the custom element's tag name. +The new element will be given an [`is`](/en-US/docs/Web/HTML/Reference/Global_attributes/is) attribute whose value is the custom element's tag name. > [!NOTE] -> For backwards compatibility with previous versions of the [Custom Elements specification](https://www.w3.org/TR/custom-elements/), some browsers will allow you to pass a string here instead of an object, where the string's value is the custom element's tag name. +> For backwards compatibility, some browsers will allow you to pass a string here instead of an object, where the string's value is the custom element's tag name. ## Specifications diff --git a/files/en-us/web/api/document/createelementns/index.md b/files/en-us/web/api/document/createelementns/index.md index 2e1de002efad1a7..da5be4c63b41ab1 100644 --- a/files/en-us/web/api/document/createelementns/index.md +++ b/files/en-us/web/api/document/createelementns/index.md @@ -36,8 +36,7 @@ createElementNS(namespaceURI, qualifiedName, options) - `options` {{Optional_Inline}} - : An optional `ElementCreationOptions` object containing a single property named `is`, whose value is the tag name for a custom element previously defined using `customElements.define()`. - For backwards compatibility with previous versions of the [Custom Elements specification](https://www.w3.org/TR/custom-elements/), - some browsers will allow you to pass a string here instead of an object, where the string's value is the custom element's tag name. + For backwards compatibility, some browsers allow you to pass a string here instead of an object, where the string's value is the custom element's tag name. See [Extending native HTML elements](https://web.dev/articles/web-components) for more information on how to use this parameter. The new element will be given an `is` attribute whose value is the custom element's tag name. Custom elements are an experimental feature only available in some browsers. @@ -66,19 +65,20 @@ elements from two different namespaces within a single document: title="||Working with elements||" onload="init()"> -<script type="application/javascript"><![CDATA[ - let container; - let newDiv; - let textNode; - - function init(){ - container = document.getElementById("ContainerBox"); - newDiv = document.createElementNS("http://www.w3.org/1999/xhtml", "div"); - textNode = document.createTextNode("This is text that was constructed dynamically with createElementNS and createTextNode then inserted into the document using appendChild."); - newDiv.appendChild(textNode); - container.appendChild(newDiv); - } - +<script><![CDATA[ +let container; +let newDiv; +let textNode; + +function init() { + container = document.getElementById("ContainerBox"); + newDiv = document.createElementNS("http://www.w3.org/1999/xhtml", "div"); + textNode = document.createTextNode( + "This is text that was constructed dynamically with createElementNS and createTextNode then inserted into the document using appendChild.", + ); + newDiv.appendChild(textNode); + container.appendChild(newDiv); +} ]]></script> <vbox id="ContainerBox" flex="1"> diff --git a/files/en-us/web/api/document/cut_event/index.md b/files/en-us/web/api/document/cut_event/index.md deleted file mode 100644 index c1dc4eb6465fca9..000000000000000 --- a/files/en-us/web/api/document/cut_event/index.md +++ /dev/null @@ -1,61 +0,0 @@ ---- -title: "Document: cut event" -short-title: cut -slug: Web/API/Document/cut_event -page-type: web-api-event -browser-compat: api.Element.cut_event ---- - -{{APIRef}} - -The **`cut`** event fires when the user initiates a cut action through the browser's user interface. - -The original target for this event is the {{domxref("Element")}} that was the intended target of the cut action. You can listen for this event on the {{domxref("Document")}} interface to handle it in the capture or bubbling phases. For full details on this event please see the page on the [Element: cut event](/en-US/docs/Web/API/Element/cut_event). - -## Syntax - -Use the event name in methods like {{domxref("EventTarget.addEventListener", "addEventListener()")}}, or set an event handler property. - -```js -addEventListener("cut", (event) => {}); - -oncut = (event) => {}; -``` - -## Event type - -A {{domxref("ClipboardEvent")}}. Inherits from {{domxref("Event")}}. - -{{InheritanceDiagram("ClipboardEvent")}} - -## Examples - -To be informed when a user cuts data from the webpage to their clipboard, you can add a handler to your {{domxref("Document")}} instance using {{domxref("EventTarget.addEventListener", "addEventListener()")}}, like this: - -```js -document.addEventListener("cut", (event) => { - /* the session has shut down */ -}); -``` - -Alternatively, you can use the `Document.oncut` event handler property to establish a handler for the `cut` event: - -```js -document.oncut = (event) => { - /* the session has shut down */ -}; -``` - -## Specifications - -{{Specifications}} - -## Browser compatibility - -{{Compat}} - -## See also - -- Related events: {{domxref("Document/copy_event", "copy")}}, {{domxref("Document/paste_event", "paste")}} -- This event on {{domxref("Element")}} targets: {{domxref("Element/cut_event", "cut")}} -- This event on {{domxref("Window")}} targets: {{domxref("Window/cut_event", "cut")}} diff --git a/files/en-us/web/api/document/dir/index.md b/files/en-us/web/api/document/dir/index.md index e9a53e645518196..384a981a3130770 100644 --- a/files/en-us/web/api/document/dir/index.md +++ b/files/en-us/web/api/document/dir/index.md @@ -27,5 +27,5 @@ A string. ## See also -- [`dir`](/en-US/docs/Web/HTML/Global_attributes/dir) global +- [`dir`](/en-US/docs/Web/HTML/Reference/Global_attributes/dir) global attribute diff --git a/files/en-us/web/api/document/domain/index.md b/files/en-us/web/api/document/domain/index.md index c0aef6a8e7382ab..8500dcfe0bc7211 100644 --- a/files/en-us/web/api/document/domain/index.md +++ b/files/en-us/web/api/document/domain/index.md @@ -21,7 +21,7 @@ A string. ### Exceptions - `SecurityError` {{domxref("DOMException")}} - - : Use of this feature was blocked by a [Permissions Policy](/en-US/docs/Web/HTTP/Permissions_Policy). + - : The document is forbidden from setting its domain, for example it is sandboxed or has an opaque origin. See [Failures section](#failures) for details. ## Examples @@ -39,7 +39,7 @@ The getter for this property returns the domain portion of the current document' origin. In most cases, this will be the hostname portion of the document's URL. However, there are some exceptions: -- If the page has an opaque {{glossary("origin")}}, e.g. for a page with a [data URL](/en-US/docs/Web/URI/Reference/Schemes/data), then it will +- If the page has an opaque {{glossary("origin")}}, e.g., for a page with a [data URL](/en-US/docs/Web/URI/Reference/Schemes/data), then it will return the empty string. - If the `document.domain` [setter](#setting_the_domain) has been used, then it will return the value that was set. @@ -118,8 +118,6 @@ blanket exposure of all data caused by `document.domain`. The setter will throw a `SecurityError` {{domxref("DOMException")}} in several cases: -- The {{httpheader('Permissions-Policy/document-domain','document-domain')}} - {{HTTPHeader("Permissions-Policy")}} is disabled. - The document is inside a sandboxed {{htmlelement("iframe")}}. - The document has no {{glossary("browsing context")}}. - The document's [effective domain](https://html.spec.whatwg.org/multipage/origin.html#concept-origin-effective-domain) is `null`. @@ -132,10 +130,10 @@ As an example of this last failure case, trying to set `document.domain` to Additionally, as part of its deprecation, it will do nothing when combined with certain modern isolation features: -- If used on a cross-origin isolated page, i.e. one that uses the appropriate values +- If used on a cross-origin isolated page, i.e., one that uses the appropriate values for the {{httpheader("Cross-Origin-Opener-Policy")}} and {{httpheader("Cross-Origin-Embedder-Policy")}} HTTP headers -- If used on an origin-isolated page, i.e. one that uses the +- If used on an origin-isolated page, i.e., one that uses the {{httpheader("Origin-Agent-Cluster")}} {{experimental_inline}} HTTP header Finally, setting `document.domain` does not change the origin used for diff --git a/files/en-us/web/api/document/domcontentloaded_event/index.md b/files/en-us/web/api/document/domcontentloaded_event/index.md index 56c798779a7f431..344c16147c69b39 100644 --- a/files/en-us/web/api/document/domcontentloaded_event/index.md +++ b/files/en-us/web/api/document/domcontentloaded_event/index.md @@ -8,9 +8,9 @@ browser-compat: api.Document.DOMContentLoaded_event {{APIRef}} -The **`DOMContentLoaded`** event fires when the HTML document has been completely parsed, and all deferred scripts ([`<script defer src="…">`](/en-US/docs/Web/HTML/Element/script#defer) and [`<script type="module">`](/en-US/docs/Web/HTML/Element/script#module)) have downloaded and executed. It doesn't wait for other things like images, subframes, and async scripts to finish loading. +The **`DOMContentLoaded`** event fires when the HTML document has been completely parsed, and all deferred scripts ([`<script defer src="…">`](/en-US/docs/Web/HTML/Reference/Elements/script#defer) and [`<script type="module">`](/en-US/docs/Web/HTML/Reference/Elements/script#module)) have downloaded and executed. It doesn't wait for other things like images, subframes, and async scripts to finish loading. -`DOMContentLoaded` does not wait for stylesheets to load, however deferred scripts _do_ wait for stylesheets, and the `DOMContentLoaded` event is queued after deferred scripts. Also, scripts which aren't deferred or async (e.g. `<script>`) will wait for already-parsed stylesheets to load. +`DOMContentLoaded` does not wait for stylesheets to load, however deferred scripts _do_ wait for stylesheets, and the `DOMContentLoaded` event is queued after deferred scripts. Also, scripts which aren't deferred or async (e.g., `<script>`) will wait for already-parsed stylesheets to load. A different event, {{domxref("Window/load_event", "load")}}, should be used only to detect a fully-loaded page. It is a common mistake to use `load` where `DOMContentLoaded` would be more appropriate. @@ -18,12 +18,15 @@ This event is not cancelable. ## Syntax -Use the event name in methods like {{domxref("EventTarget.addEventListener", "addEventListener()")}}, or set an event handler property. +Use the event name in methods like {{domxref("EventTarget.addEventListener", "addEventListener()")}}. -```js -addEventListener("DOMContentLoaded", (event) => {}); +```js-nolint +addEventListener("DOMContentLoaded", (event) => { }) ``` +> [!NOTE] +> There is no `onDOMContentLoaded` event handler property for this event. + ## Event type A generic {{domxref("Event")}}. diff --git a/files/en-us/web/api/document/execcommand/index.md b/files/en-us/web/api/document/execcommand/index.md index 38b3a8d9db26d3a..cfce0eb7788df0b 100644 --- a/files/en-us/web/api/document/execcommand/index.md +++ b/files/en-us/web/api/document/execcommand/index.md @@ -10,11 +10,11 @@ browser-compat: api.Document.execCommand {{ApiRef("DOM")}}{{deprecated_header}} -The **`execCommand`** method implements multiple different commands. Some of them provide access to the clipboard, while others are for editing [form inputs](/en-US/docs/Web/HTML/Element/input), [`contenteditable`](/en-US/docs/Web/HTML/Global_attributes/contenteditable) elements or entire documents (when switched to [design mode](/en-US/docs/Web/API/Document/designMode)). +The **`execCommand`** method implements multiple different commands. Some of them provide access to the clipboard, while others are for editing [form inputs](/en-US/docs/Web/HTML/Reference/Elements/input), [`contenteditable`](/en-US/docs/Web/HTML/Reference/Global_attributes/contenteditable) elements or entire documents (when switched to [design mode](/en-US/docs/Web/API/Document/designMode)). To access the clipboard, the newer [Clipboard API](/en-US/docs/Web/API/Clipboard_API) is recommended over `execCommand()`. However, there is no replacement for the editing commands: unlike direct DOM manipulation, modifications performed by `execCommand()` preserve the undo buffer (edit history). -Most commands affect the document's [selection](/en-US/docs/Web/API/Selection). For example, some commands (bold, italics, etc.) format the currently selected text, while others delete the selection, insert new elements (replacing the selection) or affect an entire line (indenting). Only the currently active editable element can be modified, but some commands (e.g. `copy`) can work without an editable element. +Most commands affect the document's [selection](/en-US/docs/Web/API/Selection). For example, some commands (bold, italics, etc.) format the currently selected text, while others delete the selection, insert new elements (replacing the selection) or affect an entire line (indenting). Only the currently active editable element can be modified, but some commands (e.g., `copy`) can work without an editable element. > [!NOTE] > Modifications performed by `execCommand()` may or may not trigger {{domxref("Element/beforeinput_event", "beforeinput")}} and {{domxref("Element/input_event", "input")}} events, depending on the browser and configuration. If triggered, the handlers for the events will run before `execCommand()` returns. Authors need to be careful about such recursive calls, especially if they call `execCommand()` in response to these events. From Firefox 82, nested `execCommand()` calls will always fail, see [bug 1634262](https://bugzil.la/1634262). @@ -81,11 +81,11 @@ execCommand(aCommandName, aShowDefaultUI, aValueArgument) - `insertImage` - : Inserts an image at the insertion point (deletes selection). Requires a URL string for the image's `src` as a value argument. The requirements for this string are the same as `createLink`. - `insertOrderedList` - - : Creates a [numbered ordered list](/en-US/docs/Web/HTML/Element/ol) for the selection or at the insertion point. + - : Creates a [numbered ordered list](/en-US/docs/Web/HTML/Reference/Elements/ol) for the selection or at the insertion point. - `insertUnorderedList` - - : Creates a [bulleted unordered list](/en-US/docs/Web/HTML/Element/ul) for the selection or at the insertion point. + - : Creates a [bulleted unordered list](/en-US/docs/Web/HTML/Reference/Elements/ul) for the selection or at the insertion point. - `insertParagraph` - - : Inserts a [paragraph](/en-US/docs/Web/HTML/Element/p) around the selection or the current line. + - : Inserts a [paragraph](/en-US/docs/Web/HTML/Reference/Elements/p) around the selection or the current line. - `insertText` - : Inserts the given plain text at the insertion point (deletes selection). - `italic` @@ -111,15 +111,15 @@ execCommand(aCommandName, aShowDefaultUI, aValueArgument) - `strikeThrough` - : Toggles strikethrough on/off for the selection or at the insertion point. - `subscript` - - : Toggles [subscript](/en-US/docs/Web/HTML/Element/sub) on/off for the selection or at the insertion point. + - : Toggles [subscript](/en-US/docs/Web/HTML/Reference/Elements/sub) on/off for the selection or at the insertion point. - `superscript` - - : Toggles [superscript](/en-US/docs/Web/HTML/Element/sup) on/off for the selection or at the insertion point. + - : Toggles [superscript](/en-US/docs/Web/HTML/Reference/Elements/sup) on/off for the selection or at the insertion point. - `underline` - - : Toggles [underline](/en-US/docs/Web/HTML/Element/u) on/off for the selection or at the insertion point. + - : Toggles [underline](/en-US/docs/Web/HTML/Reference/Elements/u) on/off for the selection or at the insertion point. - `undo` - : Undoes the last executed command. - `unlink` - - : Removes the [anchor element](/en-US/docs/Web/HTML/Element/a) from a selected hyperlink. + - : Removes the [anchor element](/en-US/docs/Web/HTML/Reference/Elements/a) from a selected hyperlink. - `useCSS` {{Deprecated_inline}} - : Toggles the use of HTML tags or CSS for the generated markup. Requires a boolean true/false as a value argument. > [!NOTE] @@ -149,7 +149,7 @@ An example of [how to use execCommand with contentEditable elements](https://cod ### Using insertText -This example shows two very basic HTML editors, one using a {{HTMLElement("textarea")}} element and one using a {{HTMLElement("pre")}} element with the [`contenteditable`](/en-US/docs/Web/HTML/Global_attributes/contenteditable) attribute set. +This example shows two very basic HTML editors, one using a {{HTMLElement("textarea")}} element and one using a {{HTMLElement("pre")}} element with the [`contenteditable`](/en-US/docs/Web/HTML/Reference/Global_attributes/contenteditable) attribute set. Clicking the "Bold" or "Italic" buttons inserts the appropriate tags in the element, using `insertText` to preserve the edit history, so the user can undo the action. diff --git a/files/en-us/web/api/document/exitfullscreen/index.md b/files/en-us/web/api/document/exitfullscreen/index.md index 2d89ea7fdb08e9e..71e04a61f926baf 100644 --- a/files/en-us/web/api/document/exitfullscreen/index.md +++ b/files/en-us/web/api/document/exitfullscreen/index.md @@ -67,5 +67,5 @@ document.onclick = (event) => { - {{ domxref("Element.requestFullscreen()") }} - {{ domxref("Document.fullscreenElement") }} - {{ cssxref(":fullscreen") }} and {{cssxref("::backdrop")}} -- The {{HTMLElement("iframe")}} [`allowfullscreen`](/en-US/docs/Web/HTML/Element/iframe#allowfullscreen) +- The {{HTMLElement("iframe")}} [`allowfullscreen`](/en-US/docs/Web/HTML/Reference/Elements/iframe#allowfullscreen) attribute diff --git a/files/en-us/web/api/document/featurepolicy/index.md b/files/en-us/web/api/document/featurepolicy/index.md index b0e75b1907bc7cf..5cb795382a20470 100644 --- a/files/en-us/web/api/document/featurepolicy/index.md +++ b/files/en-us/web/api/document/featurepolicy/index.md @@ -10,7 +10,7 @@ browser-compat: api.Document.featurePolicy {{APIRef("Feature Policy")}}{{SeeCompatTable}} -The **`featurePolicy`** read-only property of the {{domxref("Document")}} interface returns the {{domxref("FeaturePolicy")}} interface which provides a simple API for inspecting the [Permissions Policies](/en-US/docs/Web/HTTP/Permissions_Policy) applied to a specific document. +The **`featurePolicy`** read-only property of the {{domxref("Document")}} interface returns the {{domxref("FeaturePolicy")}} interface which provides a simple API for inspecting the [Permissions Policies](/en-US/docs/Web/HTTP/Guides/Permissions_Policy) applied to a specific document. ## Value diff --git a/files/en-us/web/api/document/fonts/index.md b/files/en-us/web/api/document/fonts/index.md index dd3735f204f141b..fa3d9e9f4bba9b6 100644 --- a/files/en-us/web/api/document/fonts/index.md +++ b/files/en-us/web/api/document/fonts/index.md @@ -32,7 +32,7 @@ document.fonts.ready.then((fontFaceSet) => { }); ``` -The promise fulfils when loading and layout operations of all used fonts are done. The set of used fonts can be different from the set of _declared_ fonts, e.g. if optional fonts (i.e. fonts declared via `font-display: optional`) were not able to load in time. +The promise fulfils when loading and layout operations of all used fonts are done. The set of used fonts can be different from the set of _declared_ fonts, e.g., if optional fonts (i.e., fonts declared via `font-display: optional`) were not able to load in time. ## Specifications diff --git a/files/en-us/web/api/document/fullscreenchange_event/index.md b/files/en-us/web/api/document/fullscreenchange_event/index.md index dbd46b3c9ae3e78..cc269ddcb86ab7e 100644 --- a/files/en-us/web/api/document/fullscreenchange_event/index.md +++ b/files/en-us/web/api/document/fullscreenchange_event/index.md @@ -20,10 +20,10 @@ This event is not cancelable. Use the event name in methods like {{domxref("EventTarget.addEventListener", "addEventListener()")}}, or set an event handler property. -```js -addEventListener("fullscreenchange", (event) => {}); +```js-nolint +addEventListener("fullscreenchange", (event) => { }) -onfullscreenchange = (event) => {}; +onfullscreenchange = (event) => { } ``` ## Event type diff --git a/files/en-us/web/api/document/fullscreenelement/index.md b/files/en-us/web/api/document/fullscreenelement/index.md index 89a26f90fcd82e2..a859375a63d26f2 100644 --- a/files/en-us/web/api/document/fullscreenelement/index.md +++ b/files/en-us/web/api/document/fullscreenelement/index.md @@ -21,7 +21,7 @@ strict mode); the setter is a no-operation and it will be ignored. The {{domxref("Element")}} object that's currently in fullscreen mode; if fullscreen mode isn't currently in use by the `document`, the returned -value is `null`. +value is `null`. If there are multiple elements in fullscreen mode, the topmost (most recently requested) element is returned. ## Examples @@ -56,5 +56,5 @@ function isVideoInFullscreen() { - {{ domxref("Element.requestFullscreen()") }} - {{ domxref("Document.exitFullscreen()") }} - {{ cssxref(":fullscreen") }} and {{cssxref("::backdrop")}} -- The {{HTMLElement("iframe")}} [`allowfullscreen`](/en-US/docs/Web/HTML/Element/iframe#allowfullscreen) +- The {{HTMLElement("iframe")}} [`allowfullscreen`](/en-US/docs/Web/HTML/Reference/Elements/iframe#allowfullscreen) attribute diff --git a/files/en-us/web/api/document/fullscreenenabled/index.md b/files/en-us/web/api/document/fullscreenenabled/index.md index 309a04c3601093e..aace4b8d2df3ddc 100644 --- a/files/en-us/web/api/document/fullscreenenabled/index.md +++ b/files/en-us/web/api/document/fullscreenenabled/index.md @@ -14,7 +14,7 @@ mode is available. fullscreen mode is available only for a page that has no windowed plug-ins in any of its documents, and if all {{HTMLElement("iframe")}} elements -which contain the document have their [`allowfullscreen`](/en-US/docs/Web/HTML/Element/iframe#allowfullscreen) +which contain the document have their [`allowfullscreen`](/en-US/docs/Web/HTML/Reference/Elements/iframe#allowfullscreen) attribute set. Although this property is read-only, it will not throw if it is modified (even in @@ -59,5 +59,5 @@ function requestFullscreen() { - {{domxref("Document.exitFullscreen()")}} - {{domxref("Document.fullscreenElement")}} - {{cssxref(":fullscreen") }} and {{cssxref("::backdrop")}} -- The {{HTMLElement("iframe")}} [`allowfullscreen`](/en-US/docs/Web/HTML/Element/iframe#allowfullscreen) +- The {{HTMLElement("iframe")}} [`allowfullscreen`](/en-US/docs/Web/HTML/Reference/Elements/iframe#allowfullscreen) attribute diff --git a/files/en-us/web/api/document/fullscreenerror_event/index.md b/files/en-us/web/api/document/fullscreenerror_event/index.md index c9173eeb08aa1b7..d43389e8f6c62ed 100644 --- a/files/en-us/web/api/document/fullscreenerror_event/index.md +++ b/files/en-us/web/api/document/fullscreenerror_event/index.md @@ -20,10 +20,10 @@ This event is not cancelable. Use the event name in methods like {{domxref("EventTarget.addEventListener", "addEventListener()")}}, or set an event handler property. -```js -addEventListener("fullscreenerror", (event) => {}); +```js-nolint +addEventListener("fullscreenerror", (event) => { }) -onfullscreenerror = (event) => {}; +onfullscreenerror = (event) => { } ``` ## Event type diff --git a/files/en-us/web/api/document/getelementsbyclassname/index.md b/files/en-us/web/api/document/getelementsbyclassname/index.md index e88392700688538..1434a344b204357 100644 --- a/files/en-us/web/api/document/getelementsbyclassname/index.md +++ b/files/en-us/web/api/document/getelementsbyclassname/index.md @@ -126,15 +126,15 @@ elements with ALL of the classNames specified are selected. // getElementsByClassName only selects elements that have both given classes const allOrangeJuiceByClass = document.getElementsByClassName("orange juice"); let result = "document.getElementsByClassName('orange juice')"; -for (let i = 0; i < allOrangeJuiceByClass.length; i++) { - result += `\n ${allOrangeJuiceByClass[i].textContent}`; +for (const el of allOrangeJuiceByClass) { + result += `\n ${el.textContent}`; } // querySelector only selects full complete matches const allOrangeJuiceQuery = document.querySelectorAll(".orange.juice"); result += "\n\ndocument.querySelectorAll('.orange.juice')"; -for (let i = 0; i < allOrangeJuiceQuery.length; i++) { - result += `\n ${allOrangeJuiceQuery[i].textContent}`; +for (const el of allOrangeJuiceQuery) { + result += `\n ${el.textContent}`; } document.getElementById("resultArea").value = result; diff --git a/files/en-us/web/api/document/index.md b/files/en-us/web/api/document/index.md index ac552565fcd6360..5a5c8fc61cde60a 100644 --- a/files/en-us/web/api/document/index.md +++ b/files/en-us/web/api/document/index.md @@ -9,11 +9,11 @@ browser-compat: api.Document The **`Document`** interface represents any web page loaded in the browser and serves as an entry point into the web page's content, which is the [DOM tree](/en-US/docs/Web/API/Document_Object_Model/Using_the_Document_Object_Model#what_is_a_dom_tree). -The DOM tree includes elements such as {{HTMLElement("body")}} and {{HTMLElement("table")}}, among [many others](/en-US/docs/Web/HTML/Element). It provides functionality globally to the document, like how to obtain the page's URL and create new elements in the document. +The DOM tree includes elements such as {{HTMLElement("body")}} and {{HTMLElement("table")}}, among [many others](/en-US/docs/Web/HTML/Reference/Elements). It provides functionality globally to the document, like how to obtain the page's URL and create new elements in the document. {{InheritanceDiagram}} -The `Document` interface describes the common properties and methods for any kind of document. Depending on the document's type (e.g. [HTML](/en-US/docs/Web/HTML), [XML](/en-US/docs/Web/XML), SVG, …), a larger API is available: HTML documents, served with the `"text/html"` content type, also implement the {{DOMxRef("HTMLDocument")}} interface, whereas XML and SVG documents implement the {{DOMxRef("XMLDocument")}} interface. +The `Document` interface describes the common properties and methods for any kind of document. Depending on the document's type (e.g., [HTML](/en-US/docs/Web/HTML), [XML](/en-US/docs/Web/XML), SVG, …), a larger API is available: HTML documents, served with the `"text/html"` content type, also implement the {{DOMxRef("HTMLDocument")}} interface, whereas XML and SVG documents implement the {{DOMxRef("XMLDocument")}} interface. ## Constructor @@ -244,6 +244,8 @@ _This interface also inherits from the {{DOMxRef("Node")}} and {{DOMxRef("EventT - : New name for {{DOMxRef("Document.hasStorageAccess()")}}. - {{DOMxRef("Document.importNode()")}} - : Returns a clone of a node from an external document. +- {{DOMxRef("Document.moveBefore()")}} {{Experimental_Inline}} + - : Moves a given {{domxref("Node")}} inside the `Document` DOM node as a direct child, before a given reference node, without removing and then inserting the node. - {{DOMxRef("Document.mozSetImageElement()")}} {{Non-standard_Inline}} - : Allows you to change the element being used as the background image for a specified element ID. - {{DOMxRef("Document.prepend()")}} @@ -259,7 +261,7 @@ _This interface also inherits from the {{DOMxRef("Node")}} and {{DOMxRef("EventT - {{DOMxRef("Document.replaceChildren()")}} - : Replaces the existing children of a document with a specified new set of children. - {{DOMxRef("Document.requestStorageAccess()")}} - - : Allows a document loaded in a third-party context (i.e. embedded in an {{htmlelement("iframe")}}) to request access to unpartitioned cookies, in cases where user agents by default block access to unpartitioned cookies by sites loaded in a third-party context to improve privacy. + - : Allows a document loaded in a third-party context (i.e., embedded in an {{htmlelement("iframe")}}) to request access to unpartitioned cookies, in cases where user agents by default block access to unpartitioned cookies by sites loaded in a third-party context to improve privacy. - {{DOMxRef("Document.requestStorageAccessFor()")}} {{experimental_inline}} - : Allows top-level sites to request third-party cookie access on behalf of embedded content originating from another site in the same [related website set](/en-US/docs/Web/API/Storage_Access_API/Related_website_sets). - {{domxref("Document.startViewTransition()")}} @@ -322,21 +324,12 @@ Listen to these events using `addEventListener()` or by assigning an event liste - {{DOMxRef("Document.beforescriptexecute_event", "beforescriptexecute")}} {{Non-standard_Inline}} {{deprecated_inline}} - : Fired when a static {{HTMLElement("script")}} is about to start executing. - {{domxref("Document.prerenderingchange_event", "prerenderingchange")}} {{experimental_inline}} - - : Fired on a prerendered document when it is activated (i.e. the user views the page). + - : Fired on a prerendered document when it is activated (i.e., the user views the page). - {{DOMxRef("Document.securitypolicyviolation_event", "securitypolicyviolation")}} - : Fired when a content security policy is violated. - {{DOMxRef("Document/visibilitychange_event", "visibilitychange")}} - : Fired when the content of a tab has become visible or has been hidden. -### Clipboard events - -- {{DOMxRef("Document/copy_event", "copy")}} - - : Fired when the user initiates a copy action through the browser's user interface. -- {{DOMxRef("Document/cut_event", "cut")}} - - : Fired when the user initiates a cut action through the browser's user interface. -- {{DOMxRef("Document/paste_event", "paste")}} - - : Fired when the user initiates a paste action through the browser's user interface. - ### Fullscreen events - {{DOMxRef("Document/fullscreenchange_event", "fullscreenchange")}} @@ -367,7 +360,7 @@ Listen to these events using `addEventListener()` or by assigning an event liste - {{domxref("Document/scrollsnapchange_event", "scrollsnapchange")}} {{experimental_inline}} - : Fired on the scroll container at the end of a scrolling operation when a new scroll snap target has been selected. - {{domxref("Document/scrollsnapchanging_event", "scrollsnapchanging")}} {{experimental_inline}} - - : Fired on the scroll container when the browser determines a new scroll snap target is pending, i.e. it will be selected when the current scroll gesture ends. + - : Fired on the scroll container when the browser determines a new scroll snap target is pending, i.e., it will be selected when the current scroll gesture ends. ### Selection events @@ -433,7 +426,7 @@ Not all events that bubble can reach the `Document` object. Only the following d - {{domxref("HTMLMediaElement/progress_event", "progress")}} - {{domxref("HTMLMediaElement/ratechange_event", "ratechange")}} - {{domxref("HTMLFormElement/reset_event", "reset")}} -- {{domxref("HTMLElement/resize_event", "resize")}} +- {{domxref("HTMLVideoElement/resize_event", "resize")}} - {{domxref("Element/scroll_event", "scroll")}} - {{domxref("Element/scrollend_event", "scrollend")}} - {{domxref("Element/securitypolicyviolation_event", "securitypolicyviolation")}} diff --git a/files/en-us/web/api/document/links/index.md b/files/en-us/web/api/document/links/index.md index 01c9f1727021dd0..53841645298df00 100644 --- a/files/en-us/web/api/document/links/index.md +++ b/files/en-us/web/api/document/links/index.md @@ -8,7 +8,7 @@ browser-compat: api.Document.links {{ APIRef("DOM") }} -The **`links`** read-only property of the {{domxref("Document")}} interface returns a collection of all {{HTMLElement("area")}} elements and {{HTMLElement("a")}} elements in a document with a value for the [href](/en-US/docs/Web/HTML/Element/a#href) attribute. +The **`links`** read-only property of the {{domxref("Document")}} interface returns a collection of all {{HTMLElement("area")}} elements and {{HTMLElement("a")}} elements in a document with a value for the [href](/en-US/docs/Web/HTML/Reference/Elements/a#href) attribute. ## Value diff --git a/files/en-us/web/api/document/movebefore/index.md b/files/en-us/web/api/document/movebefore/index.md new file mode 100644 index 000000000000000..ba0064901c5f50e --- /dev/null +++ b/files/en-us/web/api/document/movebefore/index.md @@ -0,0 +1,130 @@ +--- +title: "Document: moveBefore() method" +short-title: moveBefore() +slug: Web/API/Document/moveBefore +page-type: web-api-instance-method +status: + - experimental +browser-compat: api.Document.moveBefore +--- + +{{APIRef("DOM")}}{{SeeCompatTable}} + +The **`moveBefore()`** method of the {{domxref("Document")}} interface moves a given {{domxref("Node")}} inside the `Document` DOM node as a direct child, before a given reference node. + +## Syntax + +```js-nolint +moveBefore(movedNode, referenceNode) +``` + +### Parameters + +- `movedNode` + - : A {{domxref("Node")}} representing the node to be moved. Note that this must be an {{domxref("Element")}} or a {{domxref("CharacterData")}} node. +- `referenceNode` + - : A {{domxref("Node")}} that `movedNode` will be moved before, or `null`. If the value is `null`, `movedNode` is inserted at the end of the `Document`'s child nodes. + +### Return value + +None ({{jsxref("undefined")}}). + +### Exceptions + +- `HierarchyRequestError` {{jsxref("TypeError")}} + - : Thrown in any of the following situations: + - The specified `movedNode` is not part of this document. + - The specified `movedNode` is not an {{domxref("Element")}} or {{domxref("CharacterData")}} node. + - You are trying to move `movedNode` before the document's {{glossary("doctype")}} (represented by a {{domxref("DocumentType")}} object). +- `NotFoundError` {{jsxref("TypeError")}} + - : The specified `referenceNode` is not a child of the node you are calling `moveBefore()` on, that is, the node you are trying to move `movedNode` inside. +- `TypeError` {{jsxref("TypeError")}} + - : The second argument was not supplied. + +## Description + +The `moveBefore()` method moves a given node to a new place in the DOM. It provides similar functionality to the {{domxref("Node.insertBefore()")}} method, except that it doesn't remove and then reinsert the node. This means that the state of the node (which would be reset if moving it with `insertBefore()` and similar mechanisms) is preserved after the move. This includes: + +- [Animation](/en-US/docs/Web/CSS/CSS_animations) and [transition](/en-US/docs/Web/CSS/CSS_transitions) state. +- {{htmlelement("iframe")}} loading state. +- Interactivity states (for example, {{cssxref(":focus")}} and {{cssxref(":active")}}). +- [Fullscreen](/en-US/docs/Web/API/Fullscreen_API) element state. +- Open/close state of [popovers](/en-US/docs/Web/API/Popover_API). +- Modal state of {{htmlelement("dialog")}} elements (modal dialogs will not be closed). + +The play state of {{htmlelement("video")}} and {{htmlelement("audio")}} elements is not included in the above list, as these elements retain their state when removed and reinserted, regardless of the mechanism used. + +When observing changes to the DOM using a {{domxref("MutationObserver")}}, nodes moved with `moveBefore()` will be recorded with a [removed node](/en-US/docs/Web/API/MutationRecord/removedNodes) and an [added node](/en-US/docs/Web/API/MutationRecord/addedNodes). + +The `moveBefore()` method is not particularly useful when invoked on the `Document` node. There are some non-element uses for it, for example you could use `moveBefore()` to move comment nodes around the root of the `Document`. However, you are much more likely to find a use for invoking it on an individual `DocumentFragment` or `Element` — see {{domxref("DocumentFragment.moveBefore()")}} and {{domxref("Element.moveBefore()")}}. + +### `moveBefore()` constraints + +There are some constraints to be aware of when using `moveBefore()`: + +- It can only work when moving a node within the same document. +- It won't work if you try to move a node that is not connected to the DOM to an already connected parent, or vice versa. + +In such cases, `moveBefore()` will fail with a `HierarchyRequestError` exception. If the above constraints are requirements for your particular use case, you should use {{domxref("Node.insertBefore()")}} instead, or use [`try...catch`](/en-US/docs/Web/JavaScript/Reference/Statements/try...catch) to handle the errors that arise from such cases. + +## Examples + +### Moving a comment node with `moveBefore()` + +In this demo we show how to use `document.moveBefore()` to move a comment node within the DOM. + +#### HTML + +The HTML is a minimal template that features a comment inside the {{htmlelement("body")}}. + +```html live-sample___movebefore-comment +<!doctype html> +<html lang="en"> + <head> + <meta charset="utf-8" /> + <title>document.moveBefore() example</title> + </head> + <body> + <!-- This comment should be at the end of the document --> + <p>Some content</p> + </body> +</html> +``` + +#### JavaScript + +In our script, we loop through all the {{domxref("Node.childNodes", "childNodes")}} of the `<body>` element. When we find a node with a {{domxref("Node.nodeType", "nodeType")}} value of `8` (which indicates a comment node), we store a reference to it inside a variable called `commentNode`. We then invoke `document.moveBefore()`, specifying that we want to move the comment node, and specifying a second argument of `null` to insert our comment the end of the `Document`'s child nodes. + +```js live-sample___movebefore-comment +let commentNode; + +for (node of document.querySelector("body").childNodes) { + if (node.nodeType === 8) { + commentNode = node; + } +} + +document.moveBefore(commentNode, null); +``` + +#### Result + +The rendered example looks like this: + +{{EmbedLiveSample("movebefore-comment", "100%", "60px")}} + +If you inspect the example with your browser's developer tools, you'll notice that the comment has been moved to the end of the document, after the closing `</html>` tag. + +## Specifications + +{{Specifications}} + +## Browser compatibility + +{{Compat}} + +## See also + +- {{domxref("DocumentFragment.moveBefore()")}} +- {{domxref("Element.moveBefore()")}} +- {{domxref("Node.insertBefore()")}} diff --git a/files/en-us/web/api/document/open/index.md b/files/en-us/web/api/document/open/index.md index 6d76549619eb9a3..64d44a41de75d0d 100644 --- a/files/en-us/web/api/document/open/index.md +++ b/files/en-us/web/api/document/open/index.md @@ -76,12 +76,12 @@ document.open(type, replace); ``` Where `type` specified the MIME type of the data you are writing (e.g. -`text/html`) and replace if set (i.e. a string of `"replace"`) +`text/html`) and replace if set (i.e., a string of `"replace"`) specified that the history entry for the new document would replace the current history entry of the document being written to. This form is now obsolete; it won't throw an error, but instead just forwards to -`document.open()` (i.e. is the equivalent of just running it with no +`document.open()` (i.e., is the equivalent of just running it with no arguments). The history-replacement behavior now always happens. ## Specifications diff --git a/files/en-us/web/api/document/parsehtmlunsafe_static/index.md b/files/en-us/web/api/document/parsehtmlunsafe_static/index.md index d5ef29ba0b04591..34854d0641bb3b3 100644 --- a/files/en-us/web/api/document/parsehtmlunsafe_static/index.md +++ b/files/en-us/web/api/document/parsehtmlunsafe_static/index.md @@ -8,7 +8,7 @@ browser-compat: api.Document.parseHTMLUnsafe_static {{APIRef("DOM")}} -The **`parseHTMLUnsafe()`** static method of the {{domxref("Document")}} object is used to parse a string of HTML, which may contain [declarative shadow roots](/en-US/docs/Web/HTML/Element/template#declarative_shadow_dom), in order to create a new {{domxref("Document")}} instance. +The **`parseHTMLUnsafe()`** static method of the {{domxref("Document")}} object is used to parse a string of HTML, which may contain [declarative shadow roots](/en-US/docs/Web/HTML/Reference/Elements/template#declarative_shadow_dom), in order to create a new {{domxref("Document")}} instance. The suffix "Unsafe" in the method name indicates that, while `<script>` elements are not evaluated during parsing, the method does not sanitize other potentially unsafe XSS-relevant input. diff --git a/files/en-us/web/api/document/paste_event/index.md b/files/en-us/web/api/document/paste_event/index.md deleted file mode 100644 index 196aab1343db197..000000000000000 --- a/files/en-us/web/api/document/paste_event/index.md +++ /dev/null @@ -1,61 +0,0 @@ ---- -title: "Document: paste event" -short-title: paste -slug: Web/API/Document/paste_event -page-type: web-api-event -browser-compat: api.Element.paste_event ---- - -{{APIRef}} - -The **`paste`** event fires when the user initiates a paste action through the browser's user interface. - -The original target for this event is the {{domxref("Element")}} that was the intended target of the paste action. You can listen for this event on the {{domxref("Document")}} interface to handle it in the capture or bubbling phases. For full details on this event please see the page on the [Element: paste event](/en-US/docs/Web/API/Element/paste_event). - -## Syntax - -Use the event name in methods like {{domxref("EventTarget.addEventListener", "addEventListener()")}}, or set an event handler property. - -```js -addEventListener("paste", (event) => {}); - -onpaste = (event) => {}; -``` - -## Event type - -A {{domxref("ClipboardEvent")}}. Inherits from {{domxref("Event")}}. - -{{InheritanceDiagram("ClipboardEvent")}} - -## Examples - -To be informed when a user pastes data to the webpage from their clipboard, you can add a handler to your {{domxref("Document")}} instance using {{domxref("EventTarget.addEventListener", "addEventListener()")}}, like this: - -```js -document.addEventListener("paste", (event) => { - /* the session has shut down */ -}); -``` - -Alternatively, you can use the `Document.onpaste` event handler property to establish a handler for the `paste` event: - -```js -document.onpaste = (event) => { - /* the session has shut down */ -}; -``` - -## Specifications - -{{Specifications}} - -## Browser compatibility - -{{Compat}} - -## See also - -- Related events: {{domxref("Document/copy_event", "copy")}}, {{domxref("Document/cut_event", "cut")}} -- This event on {{domxref("Element")}} targets: {{domxref("Element/paste_event", "paste")}} -- This event on {{domxref("Window")}} targets: {{domxref("Window/paste_event", "paste")}} diff --git a/files/en-us/web/api/document/pictureinpictureenabled/index.md b/files/en-us/web/api/document/pictureinpictureenabled/index.md index 27052389e2a87f3..f0e074e1ce2bbce 100644 --- a/files/en-us/web/api/document/pictureinpictureenabled/index.md +++ b/files/en-us/web/api/document/pictureinpictureenabled/index.md @@ -14,7 +14,7 @@ The read-only available. Picture-in-Picture mode is available by default unless specified -otherwise by a [Permissions-Policy](/en-US/docs/Web/HTTP/Headers/Permissions-Policy/picture-in-picture). +otherwise by a [Permissions-Policy](/en-US/docs/Web/HTTP/Reference/Headers/Permissions-Policy/picture-in-picture). Although this property is read-only, it will not throw if it is modified (even in strict mode); the setter is a no-operation and will be ignored. diff --git a/files/en-us/web/api/document/pointerlockchange_event/index.md b/files/en-us/web/api/document/pointerlockchange_event/index.md index 188c47630d4ec24..1ae200661d3a67b 100644 --- a/files/en-us/web/api/document/pointerlockchange_event/index.md +++ b/files/en-us/web/api/document/pointerlockchange_event/index.md @@ -18,10 +18,10 @@ This event is not cancelable and does not bubble. Use the event name in methods like {{domxref("EventTarget.addEventListener", "addEventListener()")}}, or set an event handler property. -```js -addEventListener("pointerlockchange", (event) => {}); +```js-nolint +addEventListener("pointerlockchange", (event) => { }) -onpointerlockchange = (event) => {}; +onpointerlockchange = (event) => { } ``` ## Event type diff --git a/files/en-us/web/api/document/pointerlockerror_event/index.md b/files/en-us/web/api/document/pointerlockerror_event/index.md index cfe40ae1cbbf077..55df687ff072f88 100644 --- a/files/en-us/web/api/document/pointerlockerror_event/index.md +++ b/files/en-us/web/api/document/pointerlockerror_event/index.md @@ -16,10 +16,10 @@ This event is not cancelable and does not bubble. Use the event name in methods like {{domxref("EventTarget.addEventListener", "addEventListener()")}}, or set an event handler property. -```js -addEventListener("pointerlockerror", (event) => {}); +```js-nolint +addEventListener("pointerlockerror", (event) => { }) -onpointerlockerror = (event) => {}; +onpointerlockerror = (event) => { } ``` ## Event type diff --git a/files/en-us/web/api/document/prepend/index.md b/files/en-us/web/api/document/prepend/index.md index eeb034445143601..79ab4ec143dea8c 100644 --- a/files/en-us/web/api/document/prepend/index.md +++ b/files/en-us/web/api/document/prepend/index.md @@ -42,7 +42,7 @@ None ({{jsxref("undefined")}}). ### Prepending a root element to a document If you try to prepend an element to an existing HTML document, -it might throw a `HierarchyRequestError' {{domxref("DOMException")}} given a {{HTMLElement("html")}} element already exists. +it might throw a `HierarchyRequestError` {{domxref("DOMException")}} given a {{HTMLElement("html")}} element already exists. ```js let html = document.createElement("html"); diff --git a/files/en-us/web/api/document/prerenderingchange_event/index.md b/files/en-us/web/api/document/prerenderingchange_event/index.md index 2c199aa9c6ee798..14d4ac2eb5260d1 100644 --- a/files/en-us/web/api/document/prerenderingchange_event/index.md +++ b/files/en-us/web/api/document/prerenderingchange_event/index.md @@ -10,16 +10,16 @@ browser-compat: api.Document.prerenderingchange_event {{ APIRef("Speculation Rules API") }}{{seecompattable}} -The **`prerenderingchange`** event is fired on a prerendered document when it is activated (i.e. the user views the page). +The **`prerenderingchange`** event is fired on a prerendered document when it is activated (i.e., the user views the page). ## Syntax Use the event name in methods like {{domxref("EventTarget.addEventListener", "addEventListener()")}}, or set an event handler property. -```js -addEventListener("prerenderingchange", (event) => {}); +```js-nolint +addEventListener("prerenderingchange", (event) => { }) -prerenderingchange = (event) => {}; +onprerenderingchange = (event) => { } ``` ## Event type diff --git a/files/en-us/web/api/document/queryselector/index.md b/files/en-us/web/api/document/queryselector/index.md index c17c1b85136f3f6..271865908c13aaf 100644 --- a/files/en-us/web/api/document/queryselector/index.md +++ b/files/en-us/web/api/document/queryselector/index.md @@ -17,8 +17,7 @@ The matching is done using depth-first pre-order traversal of the document's nod If the specified selector matches an ID that is incorrectly used more than once in the document, the first element with that ID is returned. -[CSS pseudo-elements](/en-US/docs/Web/CSS/Pseudo-elements) will never return -any elements, as specified in the [Selectors API](https://www.w3.org/TR/selectors-api/#grammar). +[CSS pseudo-elements](/en-US/docs/Web/CSS/Pseudo-elements) will never return any elements. ## Syntax @@ -34,7 +33,7 @@ querySelector(selectors) must be a valid CSS selector string; if it isn't, a `SyntaxError` exception is thrown. - Note that the HTML specification does not require attribute values to be valid CSS identifiers. If a [`class`](/en-US/docs/Web/HTML/Global_attributes/class) or [`id`](/en-US/docs/Web/HTML/Global_attributes/id) attribute value is not a valid CSS identifier, then you must escape it before using it in a selector, either by calling {{domxref("CSS.escape_static", "CSS.escape()")}} on the value, or using one of the techniques described in [Escaping characters](/en-US/docs/Web/CSS/ident#escaping_characters). See [Escaping attribute values](#escaping_attribute_values) for an example. + Note that the HTML specification does not require attribute values to be valid CSS identifiers. If a [`class`](/en-US/docs/Web/HTML/Reference/Global_attributes/class) or [`id`](/en-US/docs/Web/HTML/Reference/Global_attributes/id) attribute value is not a valid CSS identifier, then you must escape it before using it in a selector, either by calling {{domxref("CSS.escape_static", "CSS.escape()")}} on the value, or using one of the techniques described in [Escaping characters](/en-US/docs/Web/CSS/ident#escaping_characters). See [Escaping attribute values](#escaping_attribute_values) for an example. ### Return value @@ -87,7 +86,7 @@ not the `main` class. ### Escaping attribute values -This example shows that if an HTML document contains an [`id`](/en-US/docs/Web/HTML/Global_attributes/id) which is not a valid [CSS identifier](/en-US/docs/Web/CSS/ident), then we must escape the attribute value before using it in `querySelector()`. +This example shows that if an HTML document contains an [`id`](/en-US/docs/Web/HTML/Reference/Global_attributes/id) which is not a valid [CSS identifier](/en-US/docs/Web/CSS/ident), then we must escape the attribute value before using it in `querySelector()`. #### HTML diff --git a/files/en-us/web/api/document/queryselectorall/index.md b/files/en-us/web/api/document/queryselectorall/index.md index bebd15936592957..23896d0bc8f8cab 100644 --- a/files/en-us/web/api/document/queryselectorall/index.md +++ b/files/en-us/web/api/document/queryselectorall/index.md @@ -26,7 +26,7 @@ querySelectorAll(selectors) must be a valid CSS selector string; if it isn't, a `SyntaxError` exception is thrown. - Note that the HTML specification does not require attribute values to be valid CSS identifiers. If a [`class`](/en-US/docs/Web/HTML/Global_attributes/class) or [`id`](/en-US/docs/Web/HTML/Global_attributes/id) attribute value is not a valid CSS identifier, then you must escape it before using it in a selector, either by calling {{domxref("CSS.escape_static", "CSS.escape()")}} on the value, or using one of the techniques described in [Escaping characters](/en-US/docs/Web/CSS/ident#escaping_characters). See [Escaping attribute values](#escaping_attribute_values) for an example. + Note that the HTML specification does not require attribute values to be valid CSS identifiers. If a [`class`](/en-US/docs/Web/HTML/Reference/Global_attributes/class) or [`id`](/en-US/docs/Web/HTML/Reference/Global_attributes/id) attribute value is not a valid CSS identifier, then you must escape it before using it in a selector, either by calling {{domxref("CSS.escape_static", "CSS.escape()")}} on the value, or using one of the techniques described in [Escaping characters](/en-US/docs/Web/CSS/ident#escaping_characters). See [Escaping attribute values](#escaping_attribute_values) for an example. ### Return value @@ -105,7 +105,7 @@ highlightedItems.forEach((userItem) => { ### Escaping attribute values -This example shows that if an HTML document contains an [`id`](/en-US/docs/Web/HTML/Global_attributes/id) which is not a valid [CSS identifier](/en-US/docs/Web/CSS/ident), then we must escape the attribute value before using it in `querySelectorAll()`. +This example shows that if an HTML document contains an [`id`](/en-US/docs/Web/HTML/Reference/Global_attributes/id) which is not a valid [CSS identifier](/en-US/docs/Web/CSS/ident), then we must escape the attribute value before using it in `querySelectorAll()`. #### HTML diff --git a/files/en-us/web/api/document/readystatechange_event/index.md b/files/en-us/web/api/document/readystatechange_event/index.md index 12efb6d45b99adf..0313c4bb743049d 100644 --- a/files/en-us/web/api/document/readystatechange_event/index.md +++ b/files/en-us/web/api/document/readystatechange_event/index.md @@ -16,10 +16,10 @@ This event is not cancelable and does not bubble. Use the event name in methods like {{domxref("EventTarget.addEventListener", "addEventListener()")}}, or set an event handler property. -```js -addEventListener("readystatechange", (event) => {}); +```js-nolint +addEventListener("readystatechange", (event) => { }) -onreadystatechange = (event) => {}; +onreadystatechange = (event) => { } ``` ## Event type diff --git a/files/en-us/web/api/document/referrer/index.md b/files/en-us/web/api/document/referrer/index.md index 11ddb118d410e54..33d7841594d220c 100644 --- a/files/en-us/web/api/document/referrer/index.md +++ b/files/en-us/web/api/document/referrer/index.md @@ -21,7 +21,7 @@ Inside an {{HTMLElement("iframe")}}, the `Document.referrer` will initially be set to the {{domxref("HTMLAnchorElement/href", "href")}} of the parent's {{domxref("Window/location", "Window.location")}} in same-origin requests. In cross-origin requests, it's the {{domxref("HTMLAnchorElement/origin", "origin")}} of the parent's `Window.location` by default. -For more information, see the [Referrer-Policy: strict-origin-when-cross-origin](/en-US/docs/Web/HTTP/Headers/Referrer-Policy#strict-origin-when-cross-origin) documentation. +For more information, see the [Referrer-Policy: strict-origin-when-cross-origin](/en-US/docs/Web/HTTP/Reference/Headers/Referrer-Policy#strict-origin-when-cross-origin) documentation. ## Examples diff --git a/files/en-us/web/api/document/requeststorageaccess/index.md b/files/en-us/web/api/document/requeststorageaccess/index.md index 03e49dc228da50d..a74eb8f46ab8977 100644 --- a/files/en-us/web/api/document/requeststorageaccess/index.md +++ b/files/en-us/web/api/document/requeststorageaccess/index.md @@ -13,7 +13,7 @@ The **`requestStorageAccess()`** method of the {{domxref("Document")}} interface To check whether permission to access third-party cookies has already been granted, you can call {{domxref("Permissions.query()")}}, specifying the feature name `"storage-access"`. > [!NOTE] -> Usage of this feature may be blocked by a {{httpheader("Permissions-Policy/storage-access", "storage-access")}} [Permissions Policy](/en-US/docs/Web/HTTP/Permissions_Policy) set on your server. In addition, the document must pass additional browser-specific checks such as allowlists, blocklists, on-device classification, user settings, anti-[clickjacking](/en-US/docs/Web/Security/Attacks/Clickjacking) heuristics, or prompting the user for explicit permission. +> Usage of this feature may be blocked by a {{httpheader("Permissions-Policy/storage-access", "storage-access")}} [Permissions Policy](/en-US/docs/Web/HTTP/Guides/Permissions_Policy) set on your server. In addition, the document must pass additional browser-specific checks such as allowlists, blocklists, on-device classification, user settings, anti-[clickjacking](/en-US/docs/Web/Security/Attacks/Clickjacking) heuristics, or prompting the user for explicit permission. ## Syntax @@ -61,8 +61,8 @@ A {{jsxref("Promise")}} that fulfills with `undefined` if the access to third-pa `requestStorageAccess()` requests are automatically denied unless the embedded content is currently processing a user gesture such as a tap or click ({{Glossary("transient activation")}}), or unless permission was already granted previously. If permission was not previously granted, they need to be run inside a user gesture-based event handler. The user gesture behavior depends on the state of the promise: -- If the promise resolves (i.e. if permission was granted), then the user gesture has not been consumed, so the script can subsequently call APIs that require a user gesture. -- If the promise rejects (i.e. permission was not granted), then the user gesture has been consumed, so the script can't do anything that requires a gesture. This is intentional protection against abuse — it prevents scripts from calling `requestStorageAccess()` in a loop until the user accepts the prompt. +- If the promise resolves (i.e., if permission was granted), then the user gesture has not been consumed, so the script can subsequently call APIs that require a user gesture. +- If the promise rejects (i.e., permission was not granted), then the user gesture has been consumed, so the script can't do anything that requires a gesture. This is intentional protection against abuse — it prevents scripts from calling `requestStorageAccess()` in a loop until the user accepts the prompt. ### Exceptions @@ -73,7 +73,7 @@ A {{jsxref("Promise")}} that fulfills with `undefined` if the access to third-pa - `NotAllowedError` {{domxref("DOMException")}} - : Thrown if: - The document's window is not a [secure context](/en-US/docs/Web/Security/Secure_Contexts). - - Usage is blocked by a {{httpheader("Permissions-Policy/storage-access", "storage-access")}} [Permissions Policy](/en-US/docs/Web/HTTP/Permissions_Policy). + - Usage is blocked by a {{httpheader("Permissions-Policy/storage-access", "storage-access")}} [Permissions Policy](/en-US/docs/Web/HTTP/Guides/Permissions_Policy). - The document or the top-level document has a `null` origin. - The embedding {{htmlelement("iframe")}} is sandboxed, and the `allow-storage-access-by-user-activation` token is not set. - Usage is denied by the user agent's permission request to use the API. diff --git a/files/en-us/web/api/document/requeststorageaccessfor/index.md b/files/en-us/web/api/document/requeststorageaccessfor/index.md index 8f0a189a9b6476c..7a91d9baa74eb18 100644 --- a/files/en-us/web/api/document/requeststorageaccessfor/index.md +++ b/files/en-us/web/api/document/requeststorageaccessfor/index.md @@ -44,14 +44,14 @@ A {{jsxref("Promise")}} that fulfills with `undefined` if the access to third-pa - The supplied `requestedOrigin` is [opaque](https://html.spec.whatwg.org/multipage/browsers.html#concept-origin-opaque). - The top-level and embedded sites are not in the same [related website set](/en-US/docs/Web/API/Storage_Access_API/Related_website_sets). - The embedding {{htmlelement("iframe")}} is sandboxed, and the `allow-storage-access-by-user-activation` token is not set. - - Usage is blocked by a {{httpheader("Permissions-Policy/storage-access", "storage-access")}} [Permissions Policy](/en-US/docs/Web/HTTP/Permissions_Policy). + - Usage is blocked by a {{httpheader("Permissions-Policy/storage-access", "storage-access")}} [Permissions Policy](/en-US/docs/Web/HTTP/Guides/Permissions_Policy). - Usage is denied by the user agent's permission request to use the API. - `TypeError` - : Thrown if `requestedOrigin` is not a valid URL. ## Description -The `requestStorageAccessFor()` method addresses challenges in adopting the Storage Access API on top-level sites that use cross-site images or scripts requiring cookies. It is relevant to user agents that by default block access to [third-party](/en-US/docs/Web/Privacy/Guides/Third-party_cookies), [unpartitioned](/en-US/docs/Web/API/Storage_Access_API#unpartitioned_versus_partitioned_cookies) cookies to improve privacy (e.g. to prevent tracking), and is a proposed extension of the [Storage Access API](/en-US/docs/Web/API/Storage_Access_API). +The `requestStorageAccessFor()` method addresses challenges in adopting the Storage Access API on top-level sites that use cross-site images or scripts requiring cookies. It is relevant to user agents that by default block access to [third-party](/en-US/docs/Web/Privacy/Guides/Third-party_cookies), [unpartitioned](/en-US/docs/Web/API/Storage_Access_API#unpartitioned_versus_partitioned_cookies) cookies to improve privacy (e.g., to prevent tracking), and is a proposed extension of the [Storage Access API](/en-US/docs/Web/API/Storage_Access_API). `requestStorageAccessFor()` can enable third-party cookie access for cross-site resources directly embedded into a top-level site that are unable to request storage access themselves, for example {{htmlelement("img")}} elements. Cross-site content embedded in `<iframe>`s that has its own logic and resources and needs third-party cookie access should request storage access via {{domxref("Document.requestStorageAccess()")}}. @@ -67,7 +67,7 @@ navigator.permissions.query({ ``` > [!NOTE] -> Usage of this feature may be blocked by a {{httpheader("Permissions-Policy/storage-access", "storage-access")}} [Permissions Policy](/en-US/docs/Web/HTTP/Permissions_Policy) set on your server (the same one that controls the rest of the Storage Access API). In addition, the document must pass additional browser-specific checks such as allowlists, blocklists, on-device classification, user settings, or anti-[clickjacking](/en-US/docs/Web/Security/Attacks/Clickjacking) heuristics. +> Usage of this feature may be blocked by a {{httpheader("Permissions-Policy/storage-access", "storage-access")}} [Permissions Policy](/en-US/docs/Web/HTTP/Guides/Permissions_Policy) set on your server (the same one that controls the rest of the Storage Access API). In addition, the document must pass additional browser-specific checks such as allowlists, blocklists, on-device classification, user settings, or anti-[clickjacking](/en-US/docs/Web/Security/Attacks/Clickjacking) heuristics. ## Examples @@ -87,7 +87,7 @@ function rSAFor() { } ``` -After a successful `requestStorageAccessFor()` call, cross-site requests will include cookies if they include [CORS](/en-US/docs/Web/HTTP/CORS) / [`crossorigin`](/en-US/docs/Web/HTML/Attributes/crossorigin), so sites may want to wait before triggering a request. Such requests must use the [`credentials: "include"`](/en-US/docs/Web/API/RequestInit#credentials) option and resources must include the `crossorigin="use-credentials"` attribute. +After a successful `requestStorageAccessFor()` call, cross-site requests will include cookies if they include [CORS](/en-US/docs/Web/HTTP/Guides/CORS) / [`crossorigin`](/en-US/docs/Web/HTML/Reference/Attributes/crossorigin), so sites may want to wait before triggering a request. Such requests must use the [`credentials: "include"`](/en-US/docs/Web/API/RequestInit#credentials) option and resources must include the `crossorigin="use-credentials"` attribute. For example: diff --git a/files/en-us/web/api/document/scroll_event/index.md b/files/en-us/web/api/document/scroll_event/index.md index 9ab978708342162..c366fb56d582f4c 100644 --- a/files/en-us/web/api/document/scroll_event/index.md +++ b/files/en-us/web/api/document/scroll_event/index.md @@ -16,10 +16,10 @@ For element scrolling, see {{domxref("Element/scroll_event", "scroll")}} event o Use the event name in methods like {{domxref("EventTarget.addEventListener", "addEventListener()")}}, or set an event handler property. -```js -addEventListener("scroll", (event) => {}); +```js-nolint +addEventListener("scroll", (event) => { }) -onscroll = (event) => {}; +onscroll = (event) => { } ``` ## Event type diff --git a/files/en-us/web/api/document/scrollend_event/index.md b/files/en-us/web/api/document/scrollend_event/index.md index d3f8bc5b9853308..86c0b3159f379d1 100644 --- a/files/en-us/web/api/document/scrollend_event/index.md +++ b/files/en-us/web/api/document/scrollend_event/index.md @@ -21,10 +21,10 @@ For detecting when scrolling inside an element is complete, see the {{domxref("E Use the event name in methods like {{domxref("EventTarget.addEventListener", "addEventListener()")}}, or set an event handler property. -```js -addEventListener("scrollend", (event) => {}); +```js-nolint +addEventListener("scrollend", (event) => { }) -onscrollend = (event) => {}; +onscrollend = (event) => { } ``` ## Event type diff --git a/files/en-us/web/api/document/scrollsnapchange_event/index.md b/files/en-us/web/api/document/scrollsnapchange_event/index.md index 1a79b97dff40f2e..96b19303a61963f 100644 --- a/files/en-us/web/api/document/scrollsnapchange_event/index.md +++ b/files/en-us/web/api/document/scrollsnapchange_event/index.md @@ -18,10 +18,10 @@ This event works in much the same way as the {{domxref("Element")}} interface's Use the event name in methods like {{domxref("EventTarget.addEventListener", "addEventListener()")}}, or set an event handler property. -```js -addEventListener("scrollsnapchange", (event) => {}); +```js-nolint +addEventListener("scrollsnapchange", (event) => { }) -onscrollsnapchange = (event) => {}; +onscrollsnapchange = (event) => { } ``` ## Event type diff --git a/files/en-us/web/api/document/scrollsnapchanging_event/index.md b/files/en-us/web/api/document/scrollsnapchanging_event/index.md index 1f758b980649c7b..7c2f18262c71a65 100644 --- a/files/en-us/web/api/document/scrollsnapchanging_event/index.md +++ b/files/en-us/web/api/document/scrollsnapchanging_event/index.md @@ -10,7 +10,7 @@ browser-compat: api.Document.scrollsnapchanging_event {{APIRef}}{{SeeCompatTable}} -The **`scrollsnapchanging`** event of the {{domxref("Document")}} interface is fired on the [scroll container](/en-US/docs/Glossary/Scroll_container) when the browser determines a new scroll snap target is pending, i.e. it will be selected when the current scroll gesture ends. +The **`scrollsnapchanging`** event of the {{domxref("Document")}} interface is fired on the [scroll container](/en-US/docs/Glossary/Scroll_container) when the browser determines a new scroll snap target is pending, i.e., it will be selected when the current scroll gesture ends. This event works in much the same way as the {{domxref("Element")}} interface's [`scrollsnapchanging`](/en-US/docs/Web/API/Element/scrollsnapchanging_event) event, except that the overall HTML document has to be set as the scroll snap container (i.e., {{cssxref("scroll-snap-type")}} is set on the {{htmlelement("html")}} element). @@ -18,10 +18,10 @@ This event works in much the same way as the {{domxref("Element")}} interface's Use the event name in methods like {{domxref("EventTarget.addEventListener", "addEventListener()")}}, or set an event handler property. -```js -addEventListener("scrollsnapchanging", (event) => {}); +```js-nolint +addEventListener("scrollsnapchanging", (event) => { }) -onscrollsnapchanging = (event) => {}; +onscrollsnapchanging = (event) => { } ``` ## Event type diff --git a/files/en-us/web/api/document/securitypolicyviolation_event/index.md b/files/en-us/web/api/document/securitypolicyviolation_event/index.md index 4fbdd206f134264..93a05c03eb12026 100644 --- a/files/en-us/web/api/document/securitypolicyviolation_event/index.md +++ b/files/en-us/web/api/document/securitypolicyviolation_event/index.md @@ -8,24 +8,24 @@ browser-compat: api.Document.securitypolicyviolation_event {{APIRef}} -The **`securitypolicyviolation`** event is fired when a [Content Security Policy](/en-US/docs/Web/HTTP/CSP) is violated. +The **`securitypolicyviolation`** event is fired when a [Content Security Policy](/en-US/docs/Web/HTTP/Guides/CSP) is violated. The event is fired on the document when there is a violation of the document CSP policy (and may also bubble from elements in the document). This event [bubbles](/en-US/docs/Learn_web_development/Core/Scripting/Event_bubbling) to the {{domxref("Window")}} object, and is [composed](/en-US/docs/Web/API/Event/composed). > [!NOTE] -> You should add the handler for this event to a top level object (i.e. {{domxref("Window")}} or {{domxref("Document")}}). -> While the property exists in HTML elements, you can't assign a handler to the property until the elements have been loaded, by which time this event will already have fired. +> You should generally add the handler for this event to a top level object (i.e., {{domxref("Window")}} or {{domxref("Document")}}). +> While HTML elements can technically be the target of the `securitypolicyviolation` event, in reality this event does not fire on them—for example, a blocked `<img>` source directly triggers this event on `document` as the target, instead of bubbling from the `<img>` element. ## Syntax Use the event name in methods like {{domxref("EventTarget.addEventListener", "addEventListener()")}}, or set an event handler property. -```js -addEventListener("securitypolicyviolation", (event) => {}); +```js-nolint +addEventListener("securitypolicyviolation", (event) => { }) -onsecuritypolicyviolation = (event) => {}; +onsecuritypolicyviolation = (event) => { } ``` ## Event type @@ -60,4 +60,4 @@ document.addEventListener("securitypolicyviolation", (e) => { - The {{domxref("Element/securitypolicyviolation_event", "securitypolicyviolation")}} event of the {{domxref("Element")}} interface - The {{domxref("WorkerGlobalScope/securitypolicyviolation_event", "securitypolicyviolation")}} event of the {{domxref("WorkerGlobalScope")}} interface -- [HTTP > Content Security Policy](/en-US/docs/Web/HTTP/CSP) +- [HTTP > Content Security Policy](/en-US/docs/Web/HTTP/Guides/CSP) diff --git a/files/en-us/web/api/document/selectionchange_event/index.md b/files/en-us/web/api/document/selectionchange_event/index.md index d2bc56872f919a9..76364558b64b122 100644 --- a/files/en-us/web/api/document/selectionchange_event/index.md +++ b/files/en-us/web/api/document/selectionchange_event/index.md @@ -21,10 +21,10 @@ The event can be handled by adding an event listener for `selectionchange` or us Use the event name in methods like {{domxref("EventTarget.addEventListener", "addEventListener()")}}, or set an event handler property. -```js -addEventListener("selectionchange", (event) => {}); +```js-nolint +addEventListener("selectionchange", (event) => { }) -onselectionchange = (event) => {}; +onselectionchange = (event) => { } ``` ## Event type diff --git a/files/en-us/web/api/document/title/index.md b/files/en-us/web/api/document/title/index.md index 8a106639193999f..1faf700d12915ee 100644 --- a/files/en-us/web/api/document/title/index.md +++ b/files/en-us/web/api/document/title/index.md @@ -9,11 +9,11 @@ browser-compat: api.Document.title {{APIRef("DOM")}} The **`document.title`** property gets or sets the current title of the document. -When present, it defaults to the value of the [`<title>`](/en-US/docs/Web/HTML/Element/title). +When present, it defaults to the value of the [`<title>`](/en-US/docs/Web/HTML/Reference/Elements/title). ## Value -A string containing the _document_'s title. If the title was overridden by setting `document.title`, it contains that value. Otherwise, it contains the title specified in the [`<title>`](/en-US/docs/Web/HTML/Element/title) element. +A string containing the _document_'s title. If the title was overridden by setting `document.title`, it contains that value. Otherwise, it contains the title specified in the [`<title>`](/en-US/docs/Web/HTML/Reference/Elements/title) element. ```js document.title = newTitle; @@ -21,8 +21,8 @@ document.title = newTitle; `newTitle` is the new title of the document. The assignment affects the return value of `document.title`, the title displayed for the -document (e.g. in the titlebar of the window or tab), and it also affects the DOM of the -document (e.g. the content of the `<title>` element in an HTML +document (e.g., in the titlebar of the window or tab), and it also affects the DOM of the +document (e.g., the content of the `<title>` element in an HTML document). ## Examples diff --git a/files/en-us/web/api/document/visibilitychange_event/index.md b/files/en-us/web/api/document/visibilitychange_event/index.md index 7066f39436e38bc..2e0ae751e4c8408 100644 --- a/files/en-us/web/api/document/visibilitychange_event/index.md +++ b/files/en-us/web/api/document/visibilitychange_event/index.md @@ -16,10 +16,10 @@ The event is not cancelable. Use the event name in methods like {{domxref("EventTarget.addEventListener", "addEventListener()")}}, or set an event handler property. -```js -addEventListener("visibilitychange", (event) => {}); +```js-nolint +addEventListener("visibilitychange", (event) => { }) -onvisibilitychange = (event) => {}; +onvisibilitychange = (event) => { } ``` ## Event type @@ -46,11 +46,9 @@ document.addEventListener("visibilitychange", () => { if (document.hidden) { playingOnHide = !audio.paused; audio.pause(); - } else { + } else if (playingOnHide) { // Resume playing if audio was "playing on hide" - if (playingOnHide) { - audio.play(); - } + audio.play(); } }); ``` diff --git a/files/en-us/web/api/document/write/index.md b/files/en-us/web/api/document/write/index.md index ad7437453693066..73163aa38c21ef4 100644 --- a/files/en-us/web/api/document/write/index.md +++ b/files/en-us/web/api/document/write/index.md @@ -15,7 +15,7 @@ browser-compat: api.Document.write > > As [the HTML spec itself warns](<https://html.spec.whatwg.org/multipage/dynamic-markup-insertion.html#document.write()>): > -> > This method has very idiosyncratic behavior. In some cases, this method can affect the state of the [HTML parser](https://html.spec.whatwg.org/multipage/parsing.html#html-parser) while the parser is running, resulting in a DOM that does not correspond to the source of the document (e.g. if the string written is the string "`<plaintext>`" or "`<!--`"). In other cases, the call can clear the current page first, as if [`document.open()`](https://html.spec.whatwg.org/multipage/dynamic-markup-insertion.html#dom-document-open) had been called. In yet more cases, the method is simply ignored, or throws an exception. Users agents are [explicitly allowed to avoid executing `script` elements inserted via this method](https://html.spec.whatwg.org/multipage/parsing.html#document-written-scripts-intervention). And to make matters even worse, the exact behavior of this method can in some cases be dependent on network latency, which can lead to failures that are very hard to debug. For all these reasons, use of this method is strongly discouraged. +> > This method has very idiosyncratic behavior. In some cases, this method can affect the state of the [HTML parser](https://html.spec.whatwg.org/multipage/parsing.html#html-parser) while the parser is running, resulting in a DOM that does not correspond to the source of the document (e.g., if the string written is the string `<plaintext>` or `<!--`). In other cases, the call can clear the current page first, as if [`document.open()`](https://html.spec.whatwg.org/multipage/dynamic-markup-insertion.html#dom-document-open) had been called. In yet more cases, the method is simply ignored, or throws an exception. Users agents are [explicitly allowed to avoid executing `script` elements inserted via this method](https://html.spec.whatwg.org/multipage/parsing.html#document-written-scripts-intervention). And to make matters even worse, the exact behavior of this method can in some cases be dependent on network latency, which can lead to failures that are very hard to debug. For all these reasons, use of this method is strongly discouraged. > > Therefore, avoid using `document.write()` — and if possible, update any existing code that is still using it. The **`document.write()`** method writes a string of text to a document stream opened by {{domxref("document.open()")}}. @@ -71,7 +71,7 @@ If the `document.write()` call is embedded within an inline HTML `<script>` tag, `document.write()` and {{domxref("document.writeln")}} do not work in XHTML documents (you'll get an "Operation is not supported" (`NS_ERROR_DOM_NOT_SUPPORTED_ERR`) error in the error console). This happens when opening a local file with the .xhtml file extension or for any document served with an `application/xhtml+xml` {{Glossary("MIME type")}}. More information is available in the [W3C XHTML FAQ](https://www.w3.org/MarkUp/2004/xhtml-faq#docwrite). -Using `document.write()` in [deferred](/en-US/docs/Web/HTML/Element/script#defer) or [asynchronous](/en-US/docs/Web/HTML/Element/script#async) scripts will be ignored and you'll get a message like "A call to `document.write()` from an asynchronously-loaded external script was ignored" in the error console. +Using `document.write()` in [deferred](/en-US/docs/Web/HTML/Reference/Elements/script#defer) or [asynchronous](/en-US/docs/Web/HTML/Reference/Elements/script#async) scripts will be ignored and you'll get a message like "A call to `document.write()` from an asynchronously-loaded external script was ignored" in the error console. In Edge only, calling `document.write()` more than once in an {{HTMLElement("iframe")}} causes the error "SCRIPT70: Permission denied". diff --git a/files/en-us/web/api/document_object_model/examples/index.md b/files/en-us/web/api/document_object_model/examples/index.md index e4d4f548e7fbc67..dbfd524c7916bb3 100644 --- a/files/en-us/web/api/document_object_model/examples/index.md +++ b/files/en-us/web/api/document_object_model/examples/index.md @@ -13,153 +13,120 @@ This chapter provides some longer examples of web and XML development using the The following example shows the use of the `height` and `width` properties alongside images of varying dimensions: ```html -<!doctype html> -<html lang="en"> - <head> - <title>width/height example</title> - <script> - function init() { - const arrImages = new Array(3); - - arrImages[0] = document.getElementById("image1"); - arrImages[1] = document.getElementById("image2"); - arrImages[2] = document.getElementById("image3"); - - const objOutput = document.getElementById("output"); - let strHtml = "<ul>"; - - for (let i = 0; i < arrImages.length; i++) { - strHtml += - "<li>image" + - (i + 1) + - ": height=" + - arrImages[i].height + - ", width=" + - arrImages[i].width + - ", style.height=" + - arrImages[i].style.height + - ", style.width=" + - arrImages[i].style.width + - "</li>"; - } - - strHtml += "</ul>"; - - objOutput.innerHTML = strHtml; - } - </script> - </head> - <body onload="init();"> - <p> - Image 1: no height, width, or style - <img - id="image1" - src="https://www.mozilla.org/images/mozilla-banner.gif" /> - </p> - - <p> - Image 2: height="50", width="500", but no style - <img - id="image2" - src="https://www.mozilla.org/images/mozilla-banner.gif" - height="50" - width="500" /> - </p> - - <p> - Image 3: no height, width, but style="height: 50px; width: 500px;" - <img - id="image3" - src="https://www.mozilla.org/images/mozilla-banner.gif" - style="height: 50px; width: 500px;" /> - </p> - - <div id="output"></div> - </body> -</html> +<p> + Image 1: no height, width, or style + <img id="image1" src="https://www.mozilla.org/images/mozilla-banner.gif" /> +</p> + +<p> + Image 2: height="50", width="500", but no style + <img + id="image2" + src="https://www.mozilla.org/images/mozilla-banner.gif" + height="50" + width="500" /> +</p> + +<p> + Image 3: no height, width, but style="height: 50px; width: 500px;" + <img + id="image3" + src="https://www.mozilla.org/images/mozilla-banner.gif" + style="height: 50px; width: 500px;" /> +</p> + +<div id="output"></div> ``` +```js +const arrImages = [ + document.getElementById("image1"), + document.getElementById("image2"), + document.getElementById("image3"), +]; + +const objOutput = document.getElementById("output"); +let strHtml = "<ul>"; + +for (const img of arrImages) { + strHtml += `<li>image${i + 1}: height=${img.height}, width=${img.width}, style.height=${img.style.height}, style.width=${img.style.width}</li>`; +} + +strHtml += "</ul>"; + +objOutput.innerHTML = strHtml; +``` + +{{EmbedLiveSample("example_1_height_and_width", "", "300")}} + ## Example 2: Image Attributes ```html -<!doctype html> -<html lang="en"> - <head> - <title>Modifying an image border</title> - - <script> - function setBorderWidth(width) { - document.getElementById("img1").style.borderWidth = width + "px"; - } - </script> - </head> - - <body> - <p> - <img - id="img1" - src="image1.gif" - style="border: 5px solid green;" - width="100" - height="100" - alt="border test" /> - </p> - - <form name="FormName"> - <input - type="button" - value="Make border 20px-wide" - onclick="setBorderWidth(20);" /> - <input - type="button" - value="Make border 5px-wide" - onclick="setBorderWidth(5);" /> - </form> - </body> -</html> +<p> + <img id="img1" src="image1.gif" width="100" height="100" alt="border test" /> +</p> + +<form name="FormName"> + <input type="button" id="btn1" value="Make border 20px-wide" /> + <input type="button" id="btn2" value="Make border 5px-wide" /> +</form> ``` +```css +#img1 { + border: 5px solid green; +} +``` + +```js +function setBorderWidth(width) { + document.getElementById("img1").style.borderWidth = `${width}px`; +} + +document.getElementById("btn1").addEventListener("click", () => { + setBorderWidth(20); +}); +document.getElementById("btn2").addEventListener("click", () => { + setBorderWidth(5); +}); +``` + +{{EmbedLiveSample("example_2_image_attributes", "", "200")}} + ## Example 3: Manipulating Styles In this simple example, some basic style properties of an HTML paragraph element are accessed using the style object on the element and that object's CSS style properties, which can be retrieved and set from the DOM. In this case, you are manipulating the individual styles directly. In the next example (see Example 4), you can use stylesheets and their rules to change styles for whole documents. ```html -<!doctype html> -<html lang="en"> - <head> - <title>Changing color and font-size example</title> - - <script> - function changeText() { - const p = document.getElementById("pid"); - - p.style.color = "blue"; - p.style.fontSize = "18pt"; - } - </script> - </head> - <body> - <p id="pid" onclick="window.location.href = 'http://www.cnn.com/';"> - linker - </p> - - <form> - <p><input value="rec" type="button" onclick="changeText();" /></p> - </form> - </body> -</html> +<p id="pid">Some text</p> +<form> + <p><button type="button">Change text</button></p> +</form> +``` + +```js +function changeText() { + const p = document.getElementById("pid"); + + p.style.color = "blue"; + p.style.fontSize = "18pt"; +} + +document.querySelector("button").addEventListener("click", () => { + changeText(); +}); ``` +{{EmbedLiveSample("example_3_manipulating_styles", "", "200")}} + ## Example 4: Using Stylesheets The {{domxref("document.styleSheets", "styleSheets")}} property on the {{domxref("document")}} object returns a list of the stylesheets that have been loaded on that document. You can access these stylesheets and their rules individually using the stylesheet, style, and {{domxref("CSSRule")}} objects, as demonstrated in this example, which prints out all of the style rule selectors to the console. ```js -const ss = document.styleSheets; - -for (let i = 0; i < ss.length; i++) { - for (let j = 0; j < ss[i].cssRules.length; j++) { - console.log(`${ss[i].cssRules[j].selectorText}\n`); +for (const styleSheet of document.styleSheets) { + for (const rule of styleSheet.cssRules) { + console.log(`${rule.selectorText}\n`); } } ``` @@ -195,50 +162,46 @@ This example demonstrates how events fire and are handled in the DOM in a very s However, stopEvent also calls an event object method, {{domxref("event.stopPropagation")}}, which keeps the event from bubbling any further up into the DOM. Note that the table itself has an {{domxref("Element.click_event","onclick")}} event handler that ought to display a message when the table is clicked. But the stopEvent method has stopped propagation, and so after the data in the table is updated, the event phase is effectively ended, and an alert box is displayed to confirm this. ```html -<!doctype html> -<html lang="en"> - <head> - <title>Event Propagation</title> - - <style> - #t-daddy { - border: 1px solid red; - } - #c1 { - background-color: pink; - } - </style> - - <script> - function stopEvent(event) { - const c2 = document.getElementById("c2"); - c2.textContent = "hello"; - - // this ought to keep t-daddy from getting the click. - event.stopPropagation(); - alert("event propagation halted."); - } - - function load() { - const elem = document.getElementById("tbl1"); - elem.addEventListener("click", stopEvent, false); - } - </script> - </head> - - <body onload="load();"> - <table id="t-daddy" onclick="alert('hi');"> - <tr id="tbl1"> - <td id="c1">one</td> - </tr> - <tr> - <td id="c2">two</td> - </tr> - </table> - </body> -</html> +<table id="t-daddy"> + <tr id="tbl1"> + <td id="c1">one</td> + </tr> + <tr> + <td id="c2">two</td> + </tr> +</table> ``` +```css +#t-daddy { + border: 1px solid red; +} + +#c1 { + background-color: pink; +} +``` + +```js +function stopEvent(event) { + const c2 = document.getElementById("c2"); + c2.textContent = "hello"; + + // this ought to keep t-daddy from getting the click. + event.stopPropagation(); + console.log("event propagation halted."); +} + +const elem = document.getElementById("tbl1"); +elem.addEventListener("click", stopEvent, false); + +document.getElementById("t-daddy").addEventListener("click", () => { + console.log("t-daddy clicked"); +}); +``` + +{{EmbedLiveSample("example_5_event_propagation", "", "300")}} + ## Example 6: getComputedStyle This example demonstrates how the {{domxref("window.getComputedStyle")}} method can be used to get the styles of an element that are not set using the `style` attribute or with JavaScript (e.g., `elt.style.backgroundColor="rgb(173 216 230)"`). These latter types of styles can be retrieved with the more direct {{domxref("HTMLElement.style", "elt.style")}} property, whose properties are listed in the [DOM CSS Properties List](/en-US/docs/Web/CSS/Reference). @@ -246,64 +209,59 @@ This example demonstrates how the {{domxref("window.getComputedStyle")}} method `getComputedStyle()` returns a {{domxref("CSSStyleDeclaration")}} object, whose individual style properties can be referenced with this object's {{domxref("CSSStyleDeclaration.getPropertyValue()", "getPropertyValue()")}} method, as the following example document shows. ```html -<!doctype html> -<html lang="en"> - <head> - <title>getComputedStyle example</title> - - <script> - function cStyles() { - const RefDiv = document.getElementById("d1"); - const txtHeight = document.getElementById("t1"); - const h_style = document.defaultView - .getComputedStyle(RefDiv, null) - .getPropertyValue("height"); - - txtHeight.value = h_style; - - const txtWidth = document.getElementById("t2"); - const w_style = document.defaultView - .getComputedStyle(RefDiv, null) - .getPropertyValue("width"); - - txtWidth.value = w_style; - - const txtBackgroundColor = document.getElementById("t3"); - const b_style = document.defaultView - .getComputedStyle(RefDiv, null) - .getPropertyValue("background-color"); - - txtBackgroundColor.value = b_style; - } - </script> - - <style> - #d1 { - margin-left: 10px; - background-color: rgb(173 216 230); - height: 20px; - max-width: 20px; - } - </style> - </head> - - <body> - <div id="d1">&nbsp;</div> - - <form action=""> - <p> - <button type="button" onclick="cStyles();">getComputedStyle</button> - height<input id="t1" type="text" value="1" /> max-width<input - id="t2" - type="text" - value="2" /> - bg-color<input id="t3" type="text" value="3" /> - </p> - </form> - </body> -</html> +<div id="d1">&nbsp;</div> + +<form action=""> + <p> + <button type="button">getComputedStyle</button> + height<input id="t1" type="text" value="1" /> max-width<input + id="t2" + type="text" + value="2" /> + bg-color<input id="t3" type="text" value="3" /> + </p> +</form> +``` + +```css +#d1 { + margin-left: 10px; + background-color: rgb(173, 216, 230); + height: 20px; + max-width: 20px; +} ``` +```js +function cStyles() { + const refDiv = document.getElementById("d1"); + const txtHeight = document.getElementById("t1"); + const hStyle = document.defaultView + .getComputedStyle(refDiv, null) + .getPropertyValue("height"); + + txtHeight.value = hStyle; + + const txtWidth = document.getElementById("t2"); + const wStyle = document.defaultView + .getComputedStyle(refDiv, null) + .getPropertyValue("width"); + + txtWidth.value = wStyle; + + const txtBackgroundColor = document.getElementById("t3"); + const bStyle = document.defaultView + .getComputedStyle(refDiv, null) + .getPropertyValue("background-color"); + + txtBackgroundColor.value = bStyle; +} + +document.querySelector("button").addEventListener("click", cStyles); +``` + +{{EmbedLiveSample("example_6_getComputedStyle", "", "300")}} + ## Example 7: Displaying Event Object Properties This example uses DOM methods to display all the properties of the {{domxref("Window.load_event", "onload")}} {{domxref("event")}} object and their values in a table. It also shows a useful technique of using a [`for...in`](/en-US/docs/Web/JavaScript/Reference/Statements/for...in) loop to iterate over the properties of an object to get their values. @@ -313,77 +271,69 @@ The properties of event objects differs greatly between browsers, the [WHATWG DO Put the following code into a blank text file and load it into a variety of browsers, you'll be surprised at the different number and names of properties. You might also like to add some elements in the page and call this function from different event handlers. ```html -<!doctype html> -<html lang="en"> - <head> - <meta charset="utf-8" /> - <title>Show Event properties</title> - - <style> - table { - border-collapse: collapse; - } - thead { - font-weight: bold; - } - td { - padding: 2px 10px 2px 10px; - } - - .odd { - background-color: #efdfef; - } - .even { - background-color: #ffffff; - } - </style> - - <script> - function showEventProperties(e) { - function addCell(row, text) { - const cell = row.insertCell(-1); - cell.appendChild(document.createTextNode(text)); - } - - const event = e || window.event; - document.getElementById("eventType").textContent = event.type; - - const table = document.createElement("table"); - const thead = table.createTHead(); - let row = thead.insertRow(-1); - const labelList = ["#", "Property", "Value"]; - const len = labelList.length; - - for (let i = 0; i < len; i++) { - addCell(row, labelList[i]); - } - - const tbody = document.createElement("tbody"); - table.appendChild(tbody); - - for (const p in event) { - row = tbody.insertRow(-1); - row.className = row.rowIndex % 2 ? "odd" : "even"; - addCell(row, row.rowIndex); - addCell(row, p); - addCell(row, event[p]); - } - - document.body.appendChild(table); - } - - window.onload = (event) => { - showEventProperties(event); - }; - </script> - </head> - - <body> - <h1>Properties of the DOM <span id="eventType"></span> Event Object</h1> - </body> -</html> +<h1>Properties of the DOM <span id="eventType"></span> Event Object</h1> +``` + +```css +table { + border-collapse: collapse; +} +thead { + font-weight: bold; +} +td { + padding: 2px 10px 2px 10px; +} + +.odd { + background-color: #efdfef; +} +.even { + background-color: #ffffff; +} ``` +```js +function showEventProperties(e) { + function addCell(row, text) { + const cell = row.insertCell(-1); + cell.appendChild(document.createTextNode(text)); + } + + const event = e || window.event; + document.getElementById("eventType").textContent = event.type; + + const table = document.createElement("table"); + const thead = table.createTHead(); + let row = thead.insertRow(-1); + const labelList = ["#", "Property", "Value"]; + const len = labelList.length; + + for (let i = 0; i < len; i++) { + addCell(row, labelList[i]); + } + + const tbody = document.createElement("tbody"); + table.appendChild(tbody); + + for (const p in event) { + row = tbody.insertRow(-1); + row.className = row.rowIndex % 2 ? "odd" : "even"; + addCell(row, row.rowIndex); + addCell(row, p); + addCell(row, event[p]); + } + + document.body.appendChild(table); +} + +window.onload = (event) => { + showEventProperties(event); +}; +``` + +{{EmbedLiveSample("example_7_displaying_event_object_properties", "", "300")}} + ## Example 8: Using the DOM Table Interface The DOM {{domxref("HTMLTableElement")}} interface provides some convenience methods for creating and manipulating tables. Two frequently used methods are {{domxref("HTMLTableElement.insertRow")}} and {{domxref("HTMLTableRowElement.insertCell")}}. @@ -397,21 +347,23 @@ To add a row and some cells to an existing table: <td>Row 0 Cell 1</td> </tr> </table> +``` -<script> - const table = document.getElementById("table0"); - const row = table.insertRow(-1); - let cell; - let text; - - for (let i = 0; i < 2; i++) { - cell = row.insertCell(-1); - text = "Row " + row.rowIndex + " Cell " + i; - cell.appendChild(document.createTextNode(text)); - } -</script> +```js +const table = document.getElementById("table0"); +const row = table.insertRow(-1); +let cell; +let text; + +for (let i = 0; i < 2; i++) { + cell = row.insertCell(-1); + text = `Row ${row.rowIndex} Cell ${i}`; + cell.appendChild(document.createTextNode(text)); +} ``` +{{EmbedLiveSample("example_8_using_the_dom_table_interface", "", "300")}} + ### Notes - A table's {{domxref("element.innerHTML","innerHTML")}} property should never be used to modify a table, although you can use it to write an entire table or the content of a cell. diff --git a/files/en-us/web/api/document_object_model/introduction/index.md b/files/en-us/web/api/document_object_model/introduction/index.md index 66df9cf215c51f7..ef3017140be24e8 100644 --- a/files/en-us/web/api/document_object_model/introduction/index.md +++ b/files/en-us/web/api/document_object_model/introduction/index.md @@ -62,7 +62,7 @@ doc.nodeName # DOM property of document object p_list = doc.getElementsByTagName("para") ``` -For more information on what technologies are involved in writing JavaScript on the web, see [JavaScript technologies overview](/en-US/docs/Web/JavaScript/JavaScript_technologies_overview). +For more information on what technologies are involved in writing JavaScript on the web, see [JavaScript technologies overview](/en-US/docs/Web/JavaScript/Reference/JavaScript_technologies_overview). ## Accessing the DOM @@ -216,9 +216,9 @@ When you get a reference to a `table` object, as in the following example, you r ```js const table = document.getElementById("table"); const tableAttrs = table.attributes; // Node/Element interface -for (let i = 0; i < tableAttrs.length; i++) { +for (const attr of tableAttrs) { // HTMLTableElement interface: border attribute - if (tableAttrs[i].nodeName.toLowerCase() === "border") { + if (attr.nodeName.toLowerCase() === "border") { table.border = "1"; } } diff --git a/files/en-us/web/api/document_object_model/reflected_attributes/index.md b/files/en-us/web/api/document_object_model/reflected_attributes/index.md new file mode 100644 index 000000000000000..fd6ea2ca237099c --- /dev/null +++ b/files/en-us/web/api/document_object_model/reflected_attributes/index.md @@ -0,0 +1,231 @@ +--- +title: Attribute reflection +slug: Web/API/Document_Object_Model/Reflected_attributes +page-type: guide +--- + +{{DefaultAPISidebar("DOM")}} + +An {{glossary("attribute")}} extends an {{glossary("HTML")}}, {{glossary("XML")}}, {{glossary("SVG")}} or other {{glossary("element")}}, changing its behavior or providing metadata. + +Many attributes are _reflected_ in the corresponding [DOM](/en-US/docs/Web/API/Document_Object_Model) interface. +This means that the value of the attribute can be read or written directly in JavaScript through a property on the corresponding interface, and vice versa. +The reflected properties offer a more natural programming approach than getting and setting attribute values using the {{domxref("Element.getAttribute()","getAttribute()")}} and {{domxref("Element.setAttribute()","setAttribute()")}} methods of the {{domxref("Element")}} interface. + +This guide provides an overview of reflected attributes and how they are used. + +## Attribute getter/setter + +First let's see the default mechanism for getting and setting an attribute, which can be used whether or not the attribute is reflected. +To get the attribute you call the {{domxref("Element.getAttribute()","getAttribute()")}} method of the {{domxref("Element")}} interface, specifying the attribute name. +To set the attribute you call the {{domxref("Element.setAttribute()","setAttribute()")}} methods, specifying the attribute name and new value. + +Consider the following HTML: + +```html +<input placeholder="Original placeholder" /> +``` + +To get and set the [`placeholder`](/en-US/docs/Web/HTML/Reference/Attributes/placeholder) attribute: + +```js +const input = document.querySelector("input"); + +// Get the placeholder attribute +let attr = input.getAttribute("placeholder"); + +// Set the placeholder attribute +input.setAttribute("placeholder", "Modified placeholder"); +``` + +## Reflected attributes + +For an {{htmlelement("input")}} the `placeholder` attribute is reflected by the {{domxref("HTMLInputElement.placeholder")}} property. +Given the same HTML as before: + +```html +<input placeholder="Original placeholder" /> +``` + +The same operation can be performed more naturally using the `placeholder` property: + +```js +const input = document.querySelector("input"); + +// Get the placeholder attribute +let attr = input.placeholder; + +// Set the placeholder attribute +input.placeholder = "Modified placeholder"; +``` + +Note that the name of the reflected attribute and the property are the same: `placeholder`. +This is not always the case: properties are usually named following the {{glossary("Camel case","camelCase")}} convention. +This is particularly true for multi-word attribute names that contain a characters that are not allowed in a property name, such as the hyphen. +For example the [aria-checked](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-checked) attribute is reflected by the [`ariaChecked`](/en-US/docs/Web/API/Element/ariaChecked) property. + +### Boolean reflected attributes + +{{Glossary("Boolean/HTML", "Boolean attributes")}} are a little different than others in that they don't have to be declared with a name and a value. +For example, the checkbox {{htmlelement("input")}} element below has the `checked` attribute, and will be checked on display: + +```html +<input type="checkbox" checked /> +``` + +The {{domxref("Element.getAttribute()")}} will return `""` if the input is checked or `null` if it is not. +The corresponding {{domxref("HTMLInputElement.checked")}} property returns `true` or `false` for the checked state. +Otherwise boolean reflected attributes are the same as any other reflected attributes. + +## Reflected element references + +> [!NOTE] +> This section applies to [reflected ARIA attributes that contain element references](/en-US/docs/Web/API/Element#instance_properties_reflected_from_aria_element_references). +> The same considerations are likely to apply to other/future attributes that reflect element references. + +Some attributes take element _references_ as values: either an element `id` value or a space-separated string of element `id` values. +These `id` values refer to other elements which are related to the attribute, or that contain information needed by the attribute. +These attributes are reflected by a corresponding property as an array of {{domxref("HTMLElement")}}-derived object instances that match the `id` values, with some caveats. + +For example, the [`aria-labelledby`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-labelledby) attribute lists the `id` values of elements that contain the accessible name for an element in their inner text. +The HTML below shows this for an {{htmlelement("input")}} that has a label defined in {{htmlelement("span")}} elements with `id` values of `label_1`, `label_2`, and `label_3`: + +```html +<span id="label_1">(Label 1 Text)</span> +<span id="label_2">(Label 2 Text)</span> +<input aria-labelledby="label_1 label_2 label_3" /> +``` + +This attribute is reflected by {{domxref("Element.ariaLabelledByElements")}} property, which returns the array of elements that have the corresponding `id` values. +The attribute and corresponding property can be returned as shown: + +```js +const inputElement = document.querySelector("input"); + +console.log(inputElement.getAttribute("aria-labelledby")); +// "label_1 label_2 label_3" + +console.log(inputElement.ariaLabelledByElements); +// [HTMLSpanElement, HTMLSpanElement] +``` + +The first thing to note from the code above is that the attribute and the property contain different numbers of elements — the property doesn't _directly_ reflect the attribute because the reference `label_3` does not have a corresponding element. +It is also possible that a reference will not match because it is [out of scope](#element_reference_scope) for the element, as discussed in a following section. + +We can iterate the elements in the property array, in this case to get the accessible name from their inner text (this is more natural than using the attribute, because we don't have to first get the element references and then use them to find the elements, and we only have to work with elements that we know to be available in the current scope): + +```js +const inputElement = document.querySelector("input"); +const accessibleName = inputElement.ariaLabelledByElements + .map((e) => e.textContent.trim()) + .join(" "); +console.log(accessibleName); +// (Label 1 Text) (Label 2 Text) +``` + +### Setting the property and attribute + +For normal reflected properties, updates to the property are reflected in the corresponding attribute and vice versa. +For reflected element references this is not the case. +Instead, setting the property clears (unsets) the attribute, so that the property and attribute no longer reflect each other. +For example, given the following HTML: + +```html +<span id="label_1">(Label 1 Text)</span> +<span id="label_2">(Label 2 Text)</span> +<input aria-labelledby="label_1 label_2" /> +``` + +The initial value of the `aria-labelledby` is `"label_1 label_2"`, but if we set it from the DOM API, the attribute is reset to `""`: + +```js +const inputElement = document.querySelector("input"); + +let attributeValue = inputElement.getAttribute("aria-labelledby"); +console.log(attributeValue); +// "label_1 label_2" + +// Set attribute using the reflected property +inputElement.ariaLabelledByElements = document.querySelectorAll("span"); + +attributeValue = inputElement.getAttribute("aria-labelledby"); +console.log(attributeValue); +// "" +``` + +This makes sense because you could otherwise assign elements to the property that don't have an `id` reference, and hence can't be represented in the attribute. + +Setting the attribute value restores the relationship between the attribute and the property. +Continuing the example from above: + +```js +inputElement.setAttribute("aria-labelledby", "input1"); + +attributeValue = inputElement.getAttribute("aria-labelledby"); +console.log(attributeValue); +// "label_1" + +// Set attribute using the reflected property +console.log(inputElement.ariaLabelledByElements); +// [HTMLSpanElement] - for `label_1` +``` + +The array returned by the property is static, so you can't modify the returned array to cause changes to the corresponding attribute. +When an array is assigned to the property it is copied, so any changes to the attribute will not be reflected in a previously returned property array. + +### Element reference scope + +Element references can only match to elements that are "in scope" with the referencing element. + +An HTML document is represented to JavaScript as a hierarchical tree of objects referred to as the [Document Object Model (DOM)](/en-US/docs/Web/API/Document_Object_Model). +Elements within the model may contain and encapsulate "child" DOMs, referred to as [Shadow DOMs](/en-US/docs/Web/API/Web_components#shadow_dom_2) within a [`ShadowRoot`](/en-US/docs/Web/API/ShadowRoot), which can in turn nest their own Shadow DOMs. + +The scope of a referencing element is the DOM in which it is defined, and any parent DOMs in which that DOM is nested. +Shadow DOMS that are nested children of the DOM in which the referencing element is defined are out of scope. + +What this means is that an element in the DOM can reference other elements in the DOM as they are in-scope, but not in a shadow DOM. +For example, in the HTML below the element with the `id` of `label 3` would not be in scope for the {{htmlelement("input")}} element in the DOM, and would not be reflected in the corresponding property. + +```html +<div id="in_dom"> + <span id="label_1">(Label 1 Text)</span> + <input aria-labelledby="label_1 label_2 label_3" /> + <span id="label_2">(Label 2 Text)</span> +</div> +<div id="host"> + <template shadowrootmode="open"> + <span id="label_3">(Label 3 Text)</span> + </template> +</div> +``` + +However an element in a shadow root can reference elements in both the shadow root or in the DOM. +For the HTML below, `label 3` would be present in the reflected property. + +```html +<div id="in_dom"> + <span id="label_3">(Label 3 Text)</span> +</div> +<div id="host"> + <template shadowrootmode="open"> + <span id="label_1">(Label 1 Text)</span> + <input aria-labelledby="label_1 label_2 label_3" /> + <span id="label_2">(Label 2 Text)</span> + </template> +</div> +``` + +Note that a referenced element may initially be "in scope" and then moved out of scope into a nested shadow root. +In this case the referenced element will still be listed in the attribute, but will not be returned in the property. +Note however that if the element is moved back into scope, it will again be present in the reflected property. + +### Summary of the attribute/property relationship + +The relationship between attributes containing element references and their corresponding property is as follows: + +- Only attribute `id` values that match [in-scope elements](#element_reference_scope) are reflected in the property. +- Setting the property clears the attribute and the property and attribute no longer reflect each other. + If the attributes is read, with {{domxref("Element.getAttribute()")}}, the value is `""`. +- Setting the attribute, with {{domxref("Element.setAttribute()")}}, also sets the property and restores the "reflection relationship". +- Setting the attribute with a value reference that is subsequently moved out of scope will result in removal of the corresponding element from the property array. + Note however that the attribute still contains the reference, and if the element is moved back in-scope the property will again include the element (i.e., the relationship is restored). diff --git a/files/en-us/web/api/document_object_model/transforming_with_xslt/index.md b/files/en-us/web/api/document_object_model/transforming_with_xslt/index.md index d7ceb7e0f24bee4..3092c0015a14a1a 100644 --- a/files/en-us/web/api/document_object_model/transforming_with_xslt/index.md +++ b/files/en-us/web/api/document_object_model/transforming_with_xslt/index.md @@ -67,7 +67,7 @@ To try out the example: This allows you to browse the files in the directory as though they were hosted on the internet. > [!WARNING] - > Opening the XML file directly from the file system will not work, because loading the stylesheet from the file system is a [cross-origin request](/en-US/docs/Web/HTTP/CORS), and will be disallowed by default. + > Opening the XML file directly from the file system will not work, because loading the stylesheet from the file system is a [cross-origin request](/en-US/docs/Web/HTTP/Guides/CORS), and will be disallowed by default. > Hosting the XML and stylesheet on the same local server ensures that they have the same origin. 3. Open **example.xml** from the browser. diff --git a/files/en-us/web/api/document_object_model/traversing_an_html_table_with_javascript_and_dom_interfaces/index.md b/files/en-us/web/api/document_object_model/traversing_an_html_table_with_javascript_and_dom_interfaces/index.md index 609ad2cdd6ed2c1..7cfa0ede7aec53c 100644 --- a/files/en-us/web/api/document_object_model/traversing_an_html_table_with_javascript_and_dom_interfaces/index.md +++ b/files/en-us/web/api/document_object_model/traversing_an_html_table_with_javascript_and_dom_interfaces/index.md @@ -150,10 +150,7 @@ In this example we change the background color of a paragraph when a button is c ```html <body> - <input - type="button" - value="Set paragraph background color" - onclick="setBackground()" /> + <input type="button" value="Set paragraph background color" /> <p>hi</p> <p>hello</p> </body> @@ -172,6 +169,8 @@ function setBackground() { // set the inline style secondParagraph.style.background = "red"; } + +document.querySelector("input").addEventListener("click", setBackground); ``` #### Result diff --git a/files/en-us/web/api/document_object_model/whitespace/index.md b/files/en-us/web/api/document_object_model/whitespace/index.md index 5d45c7b7e31f746..58fd8925bc087ff 100644 --- a/files/en-us/web/api/document_object_model/whitespace/index.md +++ b/files/en-us/web/api/document_object_model/whitespace/index.md @@ -91,7 +91,7 @@ The `<h1>` element contains only inline elements. In fact it contains: - An inline element (the `<span>`, which contains a space, and the word "World!"). - Another text node (consisting only of tabs and spaces). -Because of this, it establishes what is called an [inline formatting context](/en-US/docs/Web/CSS/Inline_formatting_context). This is one of the possible layout rendering contexts that browser engines work with. +Because of this, it establishes what is called an [inline formatting context](/en-US/docs/Web/CSS/CSS_inline_layout/Inline_formatting_context). This is one of the possible layout rendering contexts that browser engines work with. Inside this context, whitespace character processing can be summarized as follows: diff --git a/files/en-us/web/api/document_picture-in-picture_api/using/index.md b/files/en-us/web/api/document_picture-in-picture_api/using/index.md index 6adc23d33fbfa9c..be0d51a35dbc91f 100644 --- a/files/en-us/web/api/document_picture-in-picture_api/using/index.md +++ b/files/en-us/web/api/document_picture-in-picture_api/using/index.md @@ -84,7 +84,7 @@ async function togglePictureInPicture() { height: videoPlayer.clientHeight, }); - // ... + // … // Move the player to the Picture-in-Picture window. pipWindow.document.body.append(videoPlayer); @@ -99,7 +99,7 @@ async function togglePictureInPicture() { To copy all CSS style sheets from the originating window, loop through all style sheets explicitly linked into or embedded in the document (via {{domxref("Document.styleSheets")}}) and append them to the Picture-in-Picture window. Note that this is a one-time copy. ```js -// ... +// … // Copy style sheets over from the initial document // so that the player looks the same. @@ -123,7 +123,7 @@ To copy all CSS style sheets from the originating window, loop through all style } }); -// ... +// … ``` ## Target styles when in Picture-in-Picture mode diff --git a/files/en-us/web/api/documentfragment/getelementbyid/index.md b/files/en-us/web/api/documentfragment/getelementbyid/index.md index 20055fb7a49f7b3..56155f048ac231f 100644 --- a/files/en-us/web/api/documentfragment/getelementbyid/index.md +++ b/files/en-us/web/api/documentfragment/getelementbyid/index.md @@ -57,7 +57,7 @@ List content: Fragment content: <ul id="fragment"></ul> Current status: -<pre id="log" /> +<pre id="log"></pre> ``` ```css hidden diff --git a/files/en-us/web/api/documentfragment/index.md b/files/en-us/web/api/documentfragment/index.md index 07b27d9298a8b00..3bcd826dc6c24a6 100644 --- a/files/en-us/web/api/documentfragment/index.md +++ b/files/en-us/web/api/documentfragment/index.md @@ -43,6 +43,8 @@ _This interface inherits the methods of its parent, {{domxref("Node")}}._ - : Returns the first {{domxref("Element")}} node within the `DocumentFragment`, in document order, that matches the specified selectors. - {{domxref("DocumentFragment.querySelectorAll()")}} - : Returns a {{domxref("NodeList")}} of all the {{domxref("Element")}} nodes within the `DocumentFragment` that match the specified selectors. +- {{DOMxRef("DocumentFragment.moveBefore()")}} {{Experimental_Inline}} + - : Moves a given {{domxref("Node")}} inside the invoking `DocumentFragment` as a direct child, before a given reference node, without removing and then inserting the node. - {{DOMxRef("DocumentFragment.replaceChildren()")}} - : Replaces the existing children of a `DocumentFragment` with a specified new set of children. - {{domxref("DocumentFragment.getElementById()")}} diff --git a/files/en-us/web/api/documentfragment/movebefore/index.md b/files/en-us/web/api/documentfragment/movebefore/index.md new file mode 100644 index 000000000000000..779bd28e75c8df5 --- /dev/null +++ b/files/en-us/web/api/documentfragment/movebefore/index.md @@ -0,0 +1,181 @@ +--- +title: "DocumentFragment: moveBefore() method" +short-title: moveBefore() +slug: Web/API/DocumentFragment/moveBefore +page-type: web-api-instance-method +status: + - experimental +browser-compat: api.DocumentFragment.moveBefore +--- + +{{APIRef("DOM")}}{{SeeCompatTable}} + +The **`moveBefore()`** method of the {{domxref("DocumentFragment")}} interface moves a given {{domxref("Node")}} inside the invoking `DocumentFragment` as a direct child, before a given reference node. + +## Syntax + +```js-nolint +moveBefore(movedNode, referenceNode) +``` + +### Parameters + +- `movedNode` + - : A {{domxref("Node")}} representing the node to be moved. Note that this must be an {{domxref("Element")}} or a {{domxref("CharacterData")}} node. +- `referenceNode` + - : A {{domxref("Node")}} that `movedNode` will be moved before, or `null`. If the value is `null`, `movedNode` is inserted at the end of the invoking `DocumentFragment`'s child nodes. + +### Return value + +None ({{jsxref("undefined")}}). + +### Exceptions + +- `HierarchyRequestError` {{jsxref("TypeError")}} + - : Thrown in any of the following situations: + - The specified `movedNode` is already added to the DOM, and you are trying to move it inside a `DocumentFragment`. + - You are trying to move `movedNode` between two different document fragments. + - The specified `movedNode` is not an {{domxref("Element")}} or {{domxref("CharacterData")}} node. +- `NotFoundError` {{jsxref("TypeError")}} + - : The specified `referenceNode` is not a child of the `DocumentFragment` you are calling `moveBefore()` on, that is, the fragment you are trying to move `movedNode` inside. +- `TypeError` {{jsxref("TypeError")}} + - : The second argument was not supplied. + +## Description + +The `moveBefore()` method moves a given node to a new place in the `DocumentFragment`. It provides similar functionality to the {{domxref("Node.insertBefore()")}} method, except that it doesn't remove and then reinsert the node. This means that the state of the node (which would be reset if moving it with `insertBefore()` and similar mechanisms) is preserved after the move. This includes: + +- [Animation](/en-US/docs/Web/CSS/CSS_animations) and [transition](/en-US/docs/Web/CSS/CSS_transitions) state. +- {{htmlelement("iframe")}} loading state. +- Interactivity states (for example, {{cssxref(":focus")}} and {{cssxref(":active")}}). +- [Fullscreen](/en-US/docs/Web/API/Fullscreen_API) element state. +- Open/close state of [popovers](/en-US/docs/Web/API/Popover_API). +- Modal state of {{htmlelement("dialog")}} elements (modal dialogs will not be closed). + +The play state of {{htmlelement("video")}} and {{htmlelement("audio")}} elements is not included in the above list, as these elements retain their state when removed and reinserted, regardless of the mechanism used. + +When observing changes to the DOM using a {{domxref("MutationObserver")}}, nodes moved with `moveBefore()` will be recorded with a [removed node](/en-US/docs/Web/API/MutationRecord/removedNodes) and an [added node](/en-US/docs/Web/API/MutationRecord/addedNodes). + +### `moveBefore()` constraints + +There are some constraints to be aware of when using `moveBefore()`: + +- It can only work when moving a node within the same document fragment. +- It won't work if you try to move a node that is already added to the DOM inside a `DocumentFragment`. + +In such cases, `moveBefore()` will fail with a `HierarchyRequestError` exception. If the above constraints are requirements for your particular use case, you should use {{domxref("Node.insertBefore()")}} instead, or use [`try...catch`](/en-US/docs/Web/JavaScript/Reference/Statements/try...catch) to handle the errors that arise from such cases. + +## Examples + +### Basic `moveBefore()` usage + +In this demo we illustrate basic usage of `moveBefore()`. + +#### HTML + +The HTML features three {{htmlelement("button")}} elements, and an {{htmlelement("article")}} element. We will use the buttons to control inserting `DocumentFragment` instances into the `<article>` and emptying it. + +```html live-sample___movebefore-basic +<button id="insert1">Insert fragment</button> +<button id="insert2">Insert modified fragment</button> +<button id="clear">Clear</button> +<article id="wrapper"></article> +``` + +#### CSS + +We provide some rudimentary styling for the look and feel and spacing of elements that will later be inserted into the page as children of JavaScript-generated `DocumentFragment`s. + +```css live-sample___movebefore-basic +#section1, +#section2, +#mover { + display: inline-block; + width: 200px; + height: 30px; + border: 5px solid rgb(0 0 0 / 0.25); + margin-top: 10px; +} + +#section1, +#section2 { + background-color: hotpink; +} + +#mover { + background-color: orange; +} +``` + +#### JavaScript + +In our script, we define a function, `createFragment()`, which creates a `DocumentFragment` containing a {{htmlelement("div")}} element and two {{htmlelement("section")}} elements as immediate children. + +We then attach a click event listener to each `<button>` via {{domxref("EventTarget.addEventListener", "addEventListener()")}}: + +- The first button appends the `DocumentFragment` to the `#wrapper` `<article>` element, unmodified. +- The second button appends the `DocumentFragment` to the `#wrapper` `<article>` element, but first uses `moveBefore()` to move the `<div>` to be the second child of the `DocumentFragment` rather than the first. +- The third button empties the `#wrapper` `<article>` element using {{domxref("Element.innerHTML", "innerHTML")}}. + +```js live-sample___movebefore-basic +const wrapper = document.getElementById("wrapper"); +const insertBtn1 = document.getElementById("insert1"); +const insertBtn2 = document.getElementById("insert2"); +const clearBtn = document.getElementById("clear"); + +function createFragment() { + const fragment = new DocumentFragment(); + const divElem = document.createElement("div"); + const section1 = document.createElement("section"); + const section2 = document.createElement("section"); + divElem.id = "mover"; + section1.id = "section1"; + section2.id = "section2"; + fragment.appendChild(divElem); + fragment.appendChild(section1); + fragment.appendChild(section2); + + return fragment; +} + +insertBtn1.addEventListener("click", () => { + const fragment = createFragment(); + wrapper.appendChild(fragment); +}); + +insertBtn2.addEventListener("click", () => { + const fragment = createFragment(); + fragment.moveBefore( + fragment.querySelector("#mover"), + fragment.querySelector("#section2"), + ); + + wrapper.appendChild(fragment); +}); + +clearBtn.addEventListener("click", () => { + wrapper.innerHTML = ""; +}); +``` + +#### Result + +The rendered example looks like this: + +{{EmbedLiveSample("movebefore-basic", "100%", "300px")}} + +Try clicking the first two buttons a few times and note how the `DocumentFragment` structure is modified by the second button. + +## Specifications + +{{Specifications}} + +## Browser compatibility + +{{Compat}} + +## See also + +- {{domxref("Document.moveBefore()")}} +- {{domxref("Element.moveBefore()")}} +- {{domxref("Node.insertBefore()")}} diff --git a/files/en-us/web/api/documentpictureinpicture/enter_event/index.md b/files/en-us/web/api/documentpictureinpicture/enter_event/index.md index e719fe0ee4c4027..12d59dc27a66d33 100644 --- a/files/en-us/web/api/documentpictureinpicture/enter_event/index.md +++ b/files/en-us/web/api/documentpictureinpicture/enter_event/index.md @@ -16,10 +16,10 @@ The **`enter`** event of the {{domxref("DocumentPictureInPicture")}} interface i Use the event name in methods like {{domxref("EventTarget.addEventListener", "addEventListener()")}}, or set an event handler property. -```js -addEventListener("enter", (event) => {}); +```js-nolint +addEventListener("enter", (event) => { }) -onenter = (event) => {}; +onenter = (event) => { } ``` ## Event type diff --git a/files/en-us/web/api/documentpictureinpicture/index.md b/files/en-us/web/api/documentpictureinpicture/index.md index 4e20b9392a77e49..41f4a40c0292231 100644 --- a/files/en-us/web/api/documentpictureinpicture/index.md +++ b/files/en-us/web/api/documentpictureinpicture/index.md @@ -41,7 +41,7 @@ _Inherits events from its parent, {{DOMxRef("EventTarget")}}._ ```js const videoPlayer = document.getElementById("player"); -// ... +// … // Open a Picture-in-Picture window. const pipWindow = await window.documentPictureInPicture.requestWindow({ @@ -49,7 +49,7 @@ const pipWindow = await window.documentPictureInPicture.requestWindow({ height: videoPlayer.clientHeight, }); -// ... +// … ``` See [Document Picture-in-Picture API Example](https://mdn.github.io/dom-examples/document-picture-in-picture/) for a full working demo (see the full [source code](https://github.com/mdn/dom-examples/tree/main/document-picture-in-picture) also). diff --git a/files/en-us/web/api/documentpictureinpicture/requestwindow/index.md b/files/en-us/web/api/documentpictureinpicture/requestwindow/index.md index e439d8f32f4483e..c15fdf77f26661f 100644 --- a/files/en-us/web/api/documentpictureinpicture/requestwindow/index.md +++ b/files/en-us/web/api/documentpictureinpicture/requestwindow/index.md @@ -13,7 +13,7 @@ browser-compat: api.DocumentPictureInPicture.requestWindow The **`requestWindow()`** method of the {{domxref("DocumentPictureInPicture")}} interface opens the Picture-in-Picture window for the current main browsing context. It returns a {{jsxref("Promise")}} that fulfills with a {{domxref("Window")}} instance representing the browsing context inside the Picture-in-Picture window. -The `requestWindow()` method requires [transient activation](/en-US/docs/Glossary/Transient_activation), i.e. it must be invoked in response to a user action such as a mouse click or button press. +The `requestWindow()` method requires [transient activation](/en-US/docs/Glossary/Transient_activation), i.e., it must be invoked in response to a user action such as a mouse click or button press. ## Syntax @@ -59,7 +59,7 @@ A {{jsxref("Promise")}} that fulfills with a {{domxref("Window")}} object instan - `NotAllowedError` {{domxref("DOMException")}} - : Thrown if: - `requestWindow()` is not called from a top-level `window` object. - - `requestWindow()` is called from the `window` object of the Picture-in-Picture window (i.e. {{domxref("DocumentPictureInPicture.window")}}). + - `requestWindow()` is called from the `window` object of the Picture-in-Picture window (i.e., {{domxref("DocumentPictureInPicture.window")}}). - `requestWindow()` is called without {{Glossary("Transient_activation", "transient activation")}}. - `RangeError` {{domxref("DOMException")}} - : Thrown if only one of `height` and `width` are set, or if `height` and `width` are set with negative values. @@ -69,7 +69,7 @@ A {{jsxref("Promise")}} that fulfills with a {{domxref("Window")}} object instan ```js const videoPlayer = document.getElementById("player"); -// ... +// … // Open a Picture-in-Picture window with all options set const pipWindow = await window.documentPictureInPicture.requestWindow({ @@ -79,7 +79,7 @@ const pipWindow = await window.documentPictureInPicture.requestWindow({ preferInitialWindowPlacement: true, }); -// ... +// … ``` ## Specifications diff --git a/files/en-us/web/api/documentpictureinpicture/window/index.md b/files/en-us/web/api/documentpictureinpicture/window/index.md index 3ddc9c3b32d065b..e345b37ba32061f 100644 --- a/files/en-us/web/api/documentpictureinpicture/window/index.md +++ b/files/en-us/web/api/documentpictureinpicture/window/index.md @@ -22,14 +22,14 @@ A {{domxref("Window")}} object instance if the Picture-in-Picture window has alr ```js const videoPlayer = document.getElementById("player"); -// ... +// … await window.documentPictureInPicture.requestWindow({ width: videoPlayer.clientWidth, height: videoPlayer.clientHeight, }); -// ... +// … const pipWindow = window.documentPictureInPicture.window; if (pipWindow) { diff --git a/files/en-us/web/api/domerror/index.md b/files/en-us/web/api/domerror/index.md index cd0bc215555e0bd..349e4105ca62ee6 100644 --- a/files/en-us/web/api/domerror/index.md +++ b/files/en-us/web/api/domerror/index.md @@ -20,29 +20,29 @@ The **`DOMError`** interface describes an error object that contains an error na ## Error types -| Type | Description | -| ---------------------------- | --------------------------------------------------------------------------------------- | -| `IndexSizeError` | The index is not in the allowed range (e.g. thrown in a {{ domxref("range") }} object). | -| `HierarchyRequestError` | The node tree hierarchy is not correct. | -| `WrongDocumentError` | The object is in the wrong {{ domxref("document") }}. | -| `InvalidCharacterError` | The string contains invalid characters. | -| `NoModificationAllowedError` | The object can not be modified. | -| `NotFoundError` | The object can not be found here. | -| `NotSupportedError` | The operation is not supported | -| `InvalidStateError` | The object is in an invalid state. | -| `SyntaxError` | The string did not match the expected pattern. | -| `InvalidModificationError` | The object can not be modified in this way. | -| `NamespaceError` | The operation is not allowed by Namespaces in XML | -| `InvalidAccessError` | The object does not support the operation or argument. | -| `TypeMismatchError` | The type of the object does not match the expected type. | -| `SecurityError` | The operation is insecure. | -| `NetworkError` | A network error occurred. | -| `AbortError` | The operation was aborted. | -| `URLMismatchError` | The given URL does not match another URL. | -| `QuotaExceededError` | The quota has been exceeded. | -| `TimeoutError` | The operation timed out. | -| `InvalidNodeTypeError` | The node is incorrect or has an incorrect ancestor for this operation. | -| `DataCloneError` | The object can not be cloned. | +| Type | Description | +| ---------------------------- | ---------------------------------------------------------------------------------------- | +| `IndexSizeError` | The index is not in the allowed range (e.g., thrown in a {{ domxref("range") }} object). | +| `HierarchyRequestError` | The node tree hierarchy is not correct. | +| `WrongDocumentError` | The object is in the wrong {{ domxref("document") }}. | +| `InvalidCharacterError` | The string contains invalid characters. | +| `NoModificationAllowedError` | The object can not be modified. | +| `NotFoundError` | The object can not be found here. | +| `NotSupportedError` | The operation is not supported | +| `InvalidStateError` | The object is in an invalid state. | +| `SyntaxError` | The string did not match the expected pattern. | +| `InvalidModificationError` | The object can not be modified in this way. | +| `NamespaceError` | The operation is not allowed by Namespaces in XML | +| `InvalidAccessError` | The object does not support the operation or argument. | +| `TypeMismatchError` | The type of the object does not match the expected type. | +| `SecurityError` | The operation is insecure. | +| `NetworkError` | A network error occurred. | +| `AbortError` | The operation was aborted. | +| `URLMismatchError` | The given URL does not match another URL. | +| `QuotaExceededError` | The quota has been exceeded. | +| `TimeoutError` | The operation timed out. | +| `InvalidNodeTypeError` | The node is incorrect or has an incorrect ancestor for this operation. | +| `DataCloneError` | The object can not be cloned. | ## Browser compatibility diff --git a/files/en-us/web/api/domexception/index.md b/files/en-us/web/api/domexception/index.md index af8bdebafcff396..0e243683ba2aa5a 100644 --- a/files/en-us/web/api/domexception/index.md +++ b/files/en-us/web/api/domexception/index.md @@ -89,7 +89,7 @@ Note that the following deprecated historical errors don't have an error name bu - `NotReadableError` {{experimental_inline}} - : The input/output read operation failed (No legacy code value and constant name). - `UnknownError` {{experimental_inline}} - - : The operation failed for an unknown transient reason (e.g. out of memory) (No legacy code value and constant name). + - : The operation failed for an unknown transient reason (e.g., out of memory) (No legacy code value and constant name). - `ConstraintError` {{experimental_inline}} - : A mutation operation in a transaction failed because a constraint was not satisfied (No legacy code value and constant name). - `DataError` {{experimental_inline}} diff --git a/files/en-us/web/api/domimplementation/createhtmldocument/index.md b/files/en-us/web/api/domimplementation/createhtmldocument/index.md index b2e4769f93373df..4336abd9de3ee1c 100644 --- a/files/en-us/web/api/domimplementation/createhtmldocument/index.md +++ b/files/en-us/web/api/domimplementation/createhtmldocument/index.md @@ -40,7 +40,7 @@ Here's the HTML for this example: Click <a href="javascript:makeDocument()">here</a> to create a new document and insert it below. </p> - <iframe id="theFrame" src="about:blank" /> + <iframe id="theFrame" src="about:blank"></iframe> </body> ``` diff --git a/files/en-us/web/api/dommatrix/index.md b/files/en-us/web/api/dommatrix/index.md index 1d0fa2cbca10b05..8b81a7fcadf1b9e 100644 --- a/files/en-us/web/api/dommatrix/index.md +++ b/files/en-us/web/api/dommatrix/index.md @@ -43,7 +43,7 @@ _This interface inherits properties from {{domxref("DOMMatrixReadOnly")}}, thoug _This interface includes the following methods, as well as the methods it inherits from {{domxref("DOMMatrixReadOnly")}}._ - {{domxref("DOMMatrix.invertSelf()")}} - - : Modifies the matrix by inverting it. If the matrix can't be inverted, its components are all set to `NaN`, and [`is2D`](/en-US/docs/Web/API/DOMMatrixReadOnly#is2d) returns `false`. + - : Modifies the matrix by inverting it. If the matrix can't be inverted, its components are all set to `NaN`, and [`is2D`](/en-US/docs/Web/API/DOMMatrixReadOnly/is2D) returns `false`. - {{domxref("DOMMatrix.multiplySelf()")}} - : Modifies the matrix by post-multiplying it with the specified `DOMMatrix`. This is equivalent to the dot product `A⋅B`, where matrix `A` is the source matrix and `B` is the matrix given as an input to the method. Returns itself. - {{domxref("DOMMatrix.preMultiplySelf()")}} @@ -71,11 +71,11 @@ _This interface includes the following methods, as well as the methods it inheri _This interface inherits methods from {{domxref("DOMMatrixReadOnly")}}._ -- {{domxref("DOMMatrix.fromFloat32Array", "fromFloat32Array()")}} +- {{domxref("DOMMatrix.fromFloat32Array_static", "fromFloat32Array()")}} - : Creates a new mutable `DOMMatrix` object given an array of single-precision (32-bit) floating-point values. If the array has six values, the result is a 2D matrix; if the array has 16 values, the result is a 3D matrix. Otherwise, a {{jsxref("TypeError")}} exception is thrown. -- {{domxref("DOMMatrix.fromFloat64Array", "fromFloat64Array()")}} +- {{domxref("DOMMatrix.fromFloat64Array_static", "fromFloat64Array()")}} - : Creates a new mutable `DOMMatrix` object given an array of double-precision (64-bit) floating-point values. If the array has six values, the result is a 2D matrix; if the array has 16 values, the result is a 3D matrix. Otherwise, a {{jsxref("TypeError")}} exception is thrown. -- {{domxref("DOMMatrix.fromMatrix", "fromMatrix()")}} +- {{domxref("DOMMatrix.fromMatrix_static", "fromMatrix()")}} - : Creates a new mutable `DOMMatrix` object given an existing matrix or an object which provides the values for its properties. ## Usage notes diff --git a/files/en-us/web/api/dommatrix/rotateaxisangleself/index.md b/files/en-us/web/api/dommatrix/rotateaxisangleself/index.md index d718746d8f76353..7ed2aba2247eefd 100644 --- a/files/en-us/web/api/dommatrix/rotateaxisangleself/index.md +++ b/files/en-us/web/api/dommatrix/rotateaxisangleself/index.md @@ -73,5 +73,5 @@ console.log(matrix.toString()); - CSS {{cssxref("transform")}} property and {{cssxref("transform-function/rotate3d", "rotate3d()")}} function - CSS {{cssxref("rotate")}} property - [CSS transforms](/en-US/docs/Web/CSS/CSS_transforms) module -- SVG [`transform`](/en-US/docs/Web/SVG/Attribute/transform) attribute +- SVG [`transform`](/en-US/docs/Web/SVG/Reference/Attribute/transform) attribute - {{domxref("CanvasRenderingContext2D")}} interface and {{domxref("CanvasRenderingContext2D.rotate()", "rotate()")}} method diff --git a/files/en-us/web/api/dommatrix/rotatefromvectorself/index.md b/files/en-us/web/api/dommatrix/rotatefromvectorself/index.md index 9e93f0b313efc73..445e297e6e9a54a 100644 --- a/files/en-us/web/api/dommatrix/rotatefromvectorself/index.md +++ b/files/en-us/web/api/dommatrix/rotatefromvectorself/index.md @@ -59,5 +59,5 @@ console.log(matrix.toString()); - CSS {{cssxref("transform")}} property and {{cssxref("transform-function/rotate3d", "rotate3d()")}} function - CSS {{cssxref("rotate")}} property - [CSS transforms](/en-US/docs/Web/CSS/CSS_transforms) module -- SVG [`transform`](/en-US/docs/Web/SVG/Attribute/transform) attribute +- SVG [`transform`](/en-US/docs/Web/SVG/Reference/Attribute/transform) attribute - {{domxref("CanvasRenderingContext2D")}} interface and {{domxref("CanvasRenderingContext2D.rotate()", "rotate()")}} method diff --git a/files/en-us/web/api/dommatrix/rotateself/index.md b/files/en-us/web/api/dommatrix/rotateself/index.md index 81be8b30c8156de..3770f3ebed9f0ba 100644 --- a/files/en-us/web/api/dommatrix/rotateself/index.md +++ b/files/en-us/web/api/dommatrix/rotateself/index.md @@ -30,7 +30,7 @@ rotateSelf(rotX, rotY, rotZ) - `rotZ` {{optional_inline}} - : A number; the z-coordinate of the vector denoting the axis of rotation -If only one parameter is passed, `rotZ` is the value of `rotX`, and both `rotX` and `rotY` are `0`, and the rotation is a 2D rotation. If `rotX` and `rotY` are non-zero, the [`is2D`](/en-US/docs/Web/API/DOMMatrixReadonly/is2D) is `false`. +If only one parameter is passed, `rotZ` is the value of `rotX`, and both `rotX` and `rotY` are `0`, and the rotation is a 2D rotation. If `rotX` and `rotY` are non-zero, the [`is2D`](/en-US/docs/Web/API/DOMMatrixReadOnly/is2D) is `false`. ### Return value @@ -66,7 +66,7 @@ console.log(matrix); // output: "matrix(0.866, 0.5, -0.5, 0.866, 0, 0)" - {{cssxref("transform-function/rotateY", "rotateY()")}} - {{cssxref("transform-function/rotateZ", "rotateZ()")}} - [CSS transforms](/en-US/docs/Web/CSS/CSS_transforms) module -- SVG [`transform`](/en-US/docs/Web/SVG/Attribute/transform) attribute +- SVG [`transform`](/en-US/docs/Web/SVG/Reference/Attribute/transform) attribute - {{domxref("CanvasRenderingContext2D")}} interface methods - {{domxref("CanvasRenderingContext2D.rotate()")}} - {{domxref("CanvasRenderingContext2D.transform()")}} diff --git a/files/en-us/web/api/dommatrix/scale3dself/index.md b/files/en-us/web/api/dommatrix/scale3dself/index.md index 17a28fd8bdc4b6f..cf567262e3ac7f7 100644 --- a/files/en-us/web/api/dommatrix/scale3dself/index.md +++ b/files/en-us/web/api/dommatrix/scale3dself/index.md @@ -75,5 +75,5 @@ console.log(matrix.toString()); - {{domxref("DOMMatrix.scaleSelf()")}} - CSS {{cssxref("transform")}} property and the {{cssxref("transform-function/scale", "scale3d()")}} and {{cssxref("transform-function/matrix3d", "matrix3d()")}} functions - [CSS transforms](/en-US/docs/Web/CSS/CSS_transforms) module -- SVG [`transform`](/en-US/docs/Web/SVG/Attribute/transform) attribute +- SVG [`transform`](/en-US/docs/Web/SVG/Reference/Attribute/transform) attribute - {{domxref("CanvasRenderingContext2D")}} interface {{domxref("CanvasRenderingContext2D.transform()", "transform()")}} method diff --git a/files/en-us/web/api/dommatrix/scaleself/index.md b/files/en-us/web/api/dommatrix/scaleself/index.md new file mode 100644 index 000000000000000..2d4c2f6e2c6eb83 --- /dev/null +++ b/files/en-us/web/api/dommatrix/scaleself/index.md @@ -0,0 +1,91 @@ +--- +title: "DOMMatrix: scaleSelf() method" +short-title: scaleSelf() +slug: Web/API/DOMMatrix/scaleSelf +page-type: web-api-instance-method +browser-compat: api.DOMMatrix.scaleSelf +--- + +{{APIRef("Geometry Interfaces")}}{{AvailableInWorkers}} + +The **`scaleSelf()`** method of the {{domxref("DOMMatrix")}} interface is a mutable transformation method that modifies a matrix by applying a specified scaling factor, centered on the given origin, with a default origin of `(0, 0)`, returning the scaled matrix. + +To scale a matrix without mutating it, see {{domxref("DOMMatrixReadOnly.scale()")}}, which creates a new scaled matrix while leaving the original unchanged. + +## Syntax + +```js-nolint +scaleSelf() +scaleSelf(scaleX) +scaleSelf(scaleX, scaleY) +scaleSelf(scaleX, scaleY, scaleZ) +scaleSelf(scaleX, scaleY, scaleZ, originX) +scaleSelf(scaleX, scaleY, scaleZ, originX, originY) +scaleSelf(scaleX, scaleY, scaleZ, originX, originY, originZ) +``` + +### Parameters + +- `scaleX` {{optional_inline}} + - : A multiplier for the scale value on the x-axis. If not supplied, this defaults to `1`. +- `scaleY` {{optional_inline}} + - : A multiplier for the scale value on the y-axis. If not supplied, this defaults to the value of `scaleX`. +- `scaleZ` {{optional_inline}} + - : A multiplier for the scale value on the z-axis. If this value is anything other than 1, the resulting matrix will be 3D. +- `originX` {{optional_inline}} + - : An x-coordinate for the origin of the transformation. If no origin is supplied, this defaults to 0. +- `originY` {{optional_inline}} + - : A y-coordinate for the origin of the transformation. If no origin is supplied, this defaults to 0. +- `originZ` {{optional_inline}} + - : A z-coordinate for the origin of the transformation. If no origin is supplied, this defaults to 0. If this value is anything other than 0, the resulting matrix will be 3D. + +### Return value + +Returns itself; a {{domxref("DOMMatrix")}}. + +If a scale is applied about the z-axis, the matrix will be a 4✕4 3D matrix. + +## Examples + +This SVG contains two semi-opaque squares, one red and one blue, each positioned at the document origin: + +```html +<svg viewBox="0 0 50 50" height="200"> + <rect width="25" height="25" fill="#f009" /> + <rect id="transformed" width="25" height="25" fill="#00f9" /> +</svg> +``` + +This JavaScript first creates a matrix, then scales the matrix to one that halves the width and doubles the height, using the `scaleSelf()` method. + +The matrix is then applied to the blue square as a +`transform`, changing its dimensions and position. The red square is left +unchanged. + +```js +const matrix = new DOMMatrix(); +matrix.scaleSelf(0.5, 2); + +document + .querySelector("#transformed") + .setAttribute("transform", matrix.toString()); +``` + +{{EmbedLiveSample('Examples', '', '220')}} + +## Specifications + +{{Specifications}} + +## Browser compatibility + +{{Compat}} + +## See also + +- {{domxref("DOMMatrixReadOnly.scale()")}} +- {{domxref("DOMMatrix.scale3dSelf()")}} +- CSS {{cssxref("transform")}} property and the {{cssxref("transform-function/scale", "scaleSelf()")}} and {{cssxref("transform-function/matrix", "matrix()")}} functions +- [CSS transforms](/en-US/docs/Web/CSS/CSS_transforms) module +- SVG [`transform`](/en-US/docs/Web/SVG/Reference/Attribute/transform) attribute +- {{domxref("CanvasRenderingContext2D")}} interface {{domxref("CanvasRenderingContext2D.transform()", "transform()")}} method diff --git a/files/en-us/web/api/dommatrix/skewxself/index.md b/files/en-us/web/api/dommatrix/skewxself/index.md index 11c491fabd0ffc5..8c0a3be455ea31f 100644 --- a/files/en-us/web/api/dommatrix/skewxself/index.md +++ b/files/en-us/web/api/dommatrix/skewxself/index.md @@ -54,9 +54,8 @@ console.log(matrix); // output: "matrix(1, 0, 0.25, 1, 0, 0)" - {{cssxref("transform-function/skew", "skew()")}} - {{cssxref("transform-function/skewX", "skewX()")}} - {{cssxref("transform-function/skewY", "skewY()")}} - - {{cssxref("transform-function/skewZ", "skewZ()")}} - [CSS transforms](/en-US/docs/Web/CSS/CSS_transforms) module -- SVG [`transform`](/en-US/docs/Web/SVG/Attribute/transform) attribute +- SVG [`transform`](/en-US/docs/Web/SVG/Reference/Attribute/transform) attribute - {{domxref("CanvasRenderingContext2D")}} interface methods - {{domxref("CanvasRenderingContext2D.transform()")}} - {{domxref("CanvasRenderingContext2D.setTransform()")}} diff --git a/files/en-us/web/api/dommatrix/skewyself/index.md b/files/en-us/web/api/dommatrix/skewyself/index.md index 07e82e42fb68488..ecd7282dc201735 100644 --- a/files/en-us/web/api/dommatrix/skewyself/index.md +++ b/files/en-us/web/api/dommatrix/skewyself/index.md @@ -54,9 +54,8 @@ console.log(matrix); // output: "matrix(1, -0.25, 0, 1, 0, 0)" - {{cssxref("transform-function/skew", "skew()")}} - {{cssxref("transform-function/skewX", "skewX()")}} - {{cssxref("transform-function/skewY", "skewY()")}} - - {{cssxref("transform-function/skewZ", "skewZ()")}} - [CSS transforms](/en-US/docs/Web/CSS/CSS_transforms) module -- SVG [`transform`](/en-US/docs/Web/SVG/Attribute/transform) attribute +- SVG [`transform`](/en-US/docs/Web/SVG/Reference/Attribute/transform) attribute - {{domxref("CanvasRenderingContext2D")}} interface methods - {{domxref("CanvasRenderingContext2D.transform()")}} - {{domxref("CanvasRenderingContext2D.setTransform()")}} diff --git a/files/en-us/web/api/dommatrix/translateself/index.md b/files/en-us/web/api/dommatrix/translateself/index.md index 076d331fcabe492..77bdb84351de7c2 100644 --- a/files/en-us/web/api/dommatrix/translateself/index.md +++ b/files/en-us/web/api/dommatrix/translateself/index.md @@ -64,7 +64,7 @@ console.log(matrix); // output: "matrix(1, 0, 0, 1, 25, 25)" - {{cssxref("transform-function/translateY", "translateY()")}} - {{cssxref("transform-function/translateZ", "translateZ()")}} - [CSS transforms](/en-US/docs/Web/CSS/CSS_transforms) module -- SVG [`transform`](/en-US/docs/Web/SVG/Attribute/transform) attribute +- SVG [`transform`](/en-US/docs/Web/SVG/Reference/Attribute/transform) attribute - {{domxref("CanvasRenderingContext2D")}} interface methods - {{domxref("CanvasRenderingContext2D.translate()")}} - {{domxref("CanvasRenderingContext2D.transform()")}} diff --git a/files/en-us/web/api/dommatrixreadonly/flipy/index.md b/files/en-us/web/api/dommatrixreadonly/flipy/index.md index c1128380b2751e4..6ec1202f015e98f 100644 --- a/files/en-us/web/api/dommatrixreadonly/flipy/index.md +++ b/files/en-us/web/api/dommatrixreadonly/flipy/index.md @@ -24,7 +24,7 @@ A [`DOMMatrix`](/en-US/docs/Web/API/DOMMatrix). ### Inverting a triangle -In this example, the SVG contains two identical [paths](/en-US/docs/Web/SVG/Attribute/d) in the shape of a triangle; they are both drawn to have the same size and position. The viewbox has a negative y value showing us content from both sides of the y-axis. This enables the flipped triangle to be withing the viewport after it is transformed. +In this example, the SVG contains two identical [paths](/en-US/docs/Web/SVG/Reference/Attribute/d) in the shape of a triangle; they are both drawn to have the same size and position. The view box has a negative y value showing us content from both sides of the y-axis. This enables the flipped triangle to be withing the viewport after it is transformed. #### HTML diff --git a/files/en-us/web/api/dommatrixreadonly/index.md b/files/en-us/web/api/dommatrixreadonly/index.md index acba74aadef7f23..7b5425b085fe5ef 100644 --- a/files/en-us/web/api/dommatrixreadonly/index.md +++ b/files/en-us/web/api/dommatrixreadonly/index.md @@ -82,11 +82,11 @@ _This interface doesn't inherit any methods. None of the following methods alter ## Static methods -- {{domxref("DOMMatrixReadOnly.fromFloat32Array", "fromFloat32Array()")}} +- {{domxref("DOMMatrixReadOnly.fromFloat32Array_static", "fromFloat32Array()")}} - : Creates a new mutable `DOMMatrix` object given an array of single-precision (32-bit) floating-point values. If the array has six values, the result is a 2D matrix; if the array has 16 values, the result is a 3D matrix. Otherwise, a {{jsxref("TypeError")}} exception is thrown. -- {{domxref("DOMMatrixReadOnly.fromFloat64Array", "fromFloat64Array()")}} +- {{domxref("DOMMatrixReadOnly.fromFloat64Array_static", "fromFloat64Array()")}} - : Creates a new mutable `DOMMatrix` object given an array of double-precision (64-bit) floating-point values. If the array has six values, the result is a 2D matrix; if the array has 16 values, the result is a 3D matrix. Otherwise, a {{jsxref("TypeError")}} exception is thrown. -- {{domxref("DOMMatrixReadOnly.fromMatrix", "fromMatrix()")}} +- {{domxref("DOMMatrixReadOnly.fromMatrix_static", "fromMatrix()")}} - : Creates a new mutable `DOMMatrix` object given an existing matrix or an object which provides the values for its properties. If no matrix is specified, the matrix is initialized with every element set to `0` _except_ the bottom-right corner and the element immediately above and to its left: `m33` and `m34`. These have the default value of `1`. ## Specifications diff --git a/files/en-us/web/api/dommatrixreadonly/is2d/index.md b/files/en-us/web/api/dommatrixreadonly/is2d/index.md index fea9ae66c2b2168..8b363d51faeb9ac 100644 --- a/files/en-us/web/api/dommatrixreadonly/is2d/index.md +++ b/files/en-us/web/api/dommatrixreadonly/is2d/index.md @@ -43,5 +43,5 @@ console.log(matrix.rotate(10, 20, 1).is2D); // output: false - CSS {{cssxref("transform-function")}} functions - CSS {{cssxref("transform")}} property - [CSS transforms](/en-US/docs/Web/CSS/CSS_transforms) module -- SVG [`transform`](/en-US/docs/Web/SVG/Attribute/transform) attribute +- SVG [`transform`](/en-US/docs/Web/SVG/Reference/Attribute/transform) attribute - {{domxref("CanvasRenderingContext2D")}} interface diff --git a/files/en-us/web/api/dommatrixreadonly/isidentity/index.md b/files/en-us/web/api/dommatrixreadonly/isidentity/index.md index ad7b8d993e220b7..fc375112d8313af 100644 --- a/files/en-us/web/api/dommatrixreadonly/isidentity/index.md +++ b/files/en-us/web/api/dommatrixreadonly/isidentity/index.md @@ -46,4 +46,4 @@ console.log(matrix.rotate(30).isIdentity); // output: false - CSS {{cssxref("transform-function/matrix()")}} function - CSS {{cssxref("transform")}} property - [CSS transforms](/en-US/docs/Web/CSS/CSS_transforms) module -- SVG [`transform`](/en-US/docs/Web/SVG/Attribute/transform) attribute +- SVG [`transform`](/en-US/docs/Web/SVG/Reference/Attribute/transform) attribute diff --git a/files/en-us/web/api/dommatrixreadonly/rotate/index.md b/files/en-us/web/api/dommatrixreadonly/rotate/index.md index e87934ac42af972..f09c1b9efa52dcb 100644 --- a/files/en-us/web/api/dommatrixreadonly/rotate/index.md +++ b/files/en-us/web/api/dommatrixreadonly/rotate/index.md @@ -24,9 +24,9 @@ rotate(rotX, rotY, rotZ) ### Parameters - `rotX` - - : A number; the x-coordinate of the vector denoting the axis of rotation. If non-zero, [`is2D`](/en-US/docs/Web/API/DOMMatrixReadonly/is2D) is false. + - : A number; the x-coordinate of the vector denoting the axis of rotation. If non-zero, [`is2D`](/en-US/docs/Web/API/DOMMatrixReadOnly/is2D) is false. - `rotY` {{optional_inline}} - - : A number; the y-coordinate of the vector denoting the axis of rotation. If non-zero, [`is2D`](/en-US/docs/Web/API/DOMMatrixReadonly/is2D) is false. + - : A number; the y-coordinate of the vector denoting the axis of rotation. If non-zero, [`is2D`](/en-US/docs/Web/API/DOMMatrixReadOnly/is2D) is false. - `rotZ` {{optional_inline}} - : A number; the z-coordinate of the vector denoting the axis of rotation. @@ -66,5 +66,5 @@ console.log(rotated.toString()); - CSS {{cssxref("transform")}} property and {{cssxref("transform-function/rotate3d", "rotate3d()")}} function - CSS {{cssxref("rotate")}} property - [CSS transforms](/en-US/docs/Web/CSS/CSS_transforms) module -- SVG [`transform`](/en-US/docs/Web/SVG/Attribute/transform) attribute +- SVG [`transform`](/en-US/docs/Web/SVG/Reference/Attribute/transform) attribute - {{domxref("CanvasRenderingContext2D")}} interface and {{domxref("CanvasRenderingContext2D.rotate()", "rotate()")}} method diff --git a/files/en-us/web/api/dommatrixreadonly/rotateaxisangle/index.md b/files/en-us/web/api/dommatrixreadonly/rotateaxisangle/index.md index 12d24b1bb6f38d9..0923925bccc252e 100644 --- a/files/en-us/web/api/dommatrixreadonly/rotateaxisangle/index.md +++ b/files/en-us/web/api/dommatrixreadonly/rotateaxisangle/index.md @@ -74,5 +74,5 @@ console.log(matrix.toString()); // output: "matrix(1, 0, 0, 1, 0, 0)" (unchanged - CSS {{cssxref("transform")}} property and {{cssxref("transform-function/rotate3d", "rotate3d()")}} function - CSS {{cssxref("rotate")}} property - [CSS transforms](/en-US/docs/Web/CSS/CSS_transforms) module -- SVG [`transform`](/en-US/docs/Web/SVG/Attribute/transform) attribute +- SVG [`transform`](/en-US/docs/Web/SVG/Reference/Attribute/transform) attribute - {{domxref("CanvasRenderingContext2D")}} interface and {{domxref("CanvasRenderingContext2D.rotate()", "rotate()")}} method diff --git a/files/en-us/web/api/dommatrixreadonly/rotatefromvector/index.md b/files/en-us/web/api/dommatrixreadonly/rotatefromvector/index.md index 6ada3c2f67e0caa..046a9337c040ac2 100644 --- a/files/en-us/web/api/dommatrixreadonly/rotatefromvector/index.md +++ b/files/en-us/web/api/dommatrixreadonly/rotatefromvector/index.md @@ -67,5 +67,5 @@ console.log(matrix.toString()); // matrix remains unchanged - CSS {{cssxref("transform")}} property and {{cssxref("transform-function/rotate3d", "rotate3d()")}} function - CSS {{cssxref("rotate")}} property - [CSS transforms](/en-US/docs/Web/CSS/CSS_transforms) module -- SVG [`transform`](/en-US/docs/Web/SVG/Attribute/transform) attribute +- SVG [`transform`](/en-US/docs/Web/SVG/Reference/Attribute/transform) attribute - {{domxref("CanvasRenderingContext2D")}} interface and {{domxref("CanvasRenderingContext2D.rotate()", "rotate()")}} method diff --git a/files/en-us/web/api/dommatrixreadonly/scale3d/index.md b/files/en-us/web/api/dommatrixreadonly/scale3d/index.md index cca27b02839246f..8066a86d69d8a42 100644 --- a/files/en-us/web/api/dommatrixreadonly/scale3d/index.md +++ b/files/en-us/web/api/dommatrixreadonly/scale3d/index.md @@ -75,5 +75,5 @@ console.log(matrix.toString()); // original matrix is unchanged - {{domxref("DOMMatrixReadOnly.scale()")}} - CSS {{cssxref("transform")}} property and {{cssxref("transform-function/scale3d", "scale3d()")}} and {{cssxref("transform-function/matrix3d", "matrix3d()")}} functions - [CSS transforms](/en-US/docs/Web/CSS/CSS_transforms) module -- SVG [`transform`](/en-US/docs/Web/SVG/Attribute/transform) attribute +- SVG [`transform`](/en-US/docs/Web/SVG/Reference/Attribute/transform) attribute - {{domxref("CanvasRenderingContext2D")}} interface's {{domxref("CanvasRenderingContext2D.transform()")}} method diff --git a/files/en-us/web/api/dommatrixreadonly/skewx/index.md b/files/en-us/web/api/dommatrixreadonly/skewx/index.md index 95c0333e3a40002..3b9b81e31bcf27b 100644 --- a/files/en-us/web/api/dommatrixreadonly/skewx/index.md +++ b/files/en-us/web/api/dommatrixreadonly/skewx/index.md @@ -36,7 +36,7 @@ console.log(matrix.toString()); // no transform applied // "matrix(1, 0, 0, 1, 0, 0)" console.log(matrix.skewX(14).toString()); -//"matrix(1, 0, 0.25, 1, 0, 0)" +// "matrix(1, 0, 0.25, 1, 0, 0)" console.log(matrix.toString()); // original is unchanged // "matrix(1, 0, 0, 1, 0, 0)" @@ -56,5 +56,5 @@ console.log(matrix.toString()); // original is unchanged - {{domxref("DOMMatrix.skewXSelf()")}} - CSS {{cssxref("transform")}} property and the {{cssxref("transform-function/skew", "skew()")}}, {{cssxref("transform-function/skewX", "skewX()")}}, and {{cssxref("transform-function/matrix", "matrix()")}} functions - [CSS transforms](/en-US/docs/Web/CSS/CSS_transforms) module -- SVG [`transform`](/en-US/docs/Web/SVG/Attribute/transform) attribute +- SVG [`transform`](/en-US/docs/Web/SVG/Reference/Attribute/transform) attribute - {{domxref("CanvasRenderingContext2D")}} interface's {{domxref("CanvasRenderingContext2D.transform()", "transform()")}} method diff --git a/files/en-us/web/api/dommatrixreadonly/skewy/index.md b/files/en-us/web/api/dommatrixreadonly/skewy/index.md index aa9738f52e83ce2..03165e8ba2d3e88 100644 --- a/files/en-us/web/api/dommatrixreadonly/skewy/index.md +++ b/files/en-us/web/api/dommatrixreadonly/skewy/index.md @@ -56,5 +56,5 @@ console.log(matrix.toString()); // original unchanged - {{domxref("DOMMatrixReadOnly.skewX()")}} - CSS {{cssxref("transform")}} property and the {{cssxref("transform-function/skew", "skew()")}}, {{cssxref("transform-function/skewY", "skewY()")}}, and {{cssxref("transform-function/matrix", "matrix()")}} functions - [CSS transforms](/en-US/docs/Web/CSS/CSS_transforms) module -- SVG [`transform`](/en-US/docs/Web/SVG/Attribute/transform) attribute +- SVG [`transform`](/en-US/docs/Web/SVG/Reference/Attribute/transform) attribute - {{domxref("CanvasRenderingContext2D")}} interface's {{domxref("CanvasRenderingContext2D.transform()", "transform()")}} method diff --git a/files/en-us/web/api/dompoint/frompoint_static/index.md b/files/en-us/web/api/dompoint/frompoint_static/index.md index e7166d4031ebefc..4f5d6ac5066f955 100644 --- a/files/en-us/web/api/dompoint/frompoint_static/index.md +++ b/files/en-us/web/api/dompoint/frompoint_static/index.md @@ -62,7 +62,7 @@ use for {{domxref("DOMPointReadOnly.x", "x")}} and {{domxref("DOMPointReadOnly.y The _z_ and _w_ properties are allowed to keep their default values (0 and 1 respectively). ```js -const center = DOMPoint.fromPoint({ x: 75, y: -50, z: -55, w: 0.25 }); +const center = DOMPoint.fromPoint({ x: 75, y: -50 }); ``` ## Specifications diff --git a/files/en-us/web/api/domquad/domquad/index.md b/files/en-us/web/api/domquad/domquad/index.md index 38374e1a88bcb3e..6446b7ffcb5f1a6 100644 --- a/files/en-us/web/api/domquad/domquad/index.md +++ b/files/en-us/web/api/domquad/domquad/index.md @@ -13,7 +13,7 @@ creates and returns a new {{domxref("DOMQuad")}} object, given the values for so all of its properties. You can also create a `DOMQuad` by calling the -{{domxref("DOMQuad.fromRect()")}} or {{domxref("DOMQuad.fromQuad()")}} static function. That function accepts any object with the required parameters, including a `DOMQuad`, {{domxref("DOMPoint")}} or +{{domxref("DOMQuad.fromRect_static", "DOMQuad.fromRect()")}} or {{domxref("DOMQuad.fromQuad_static", "DOMQuad.fromQuad()")}} static function. That function accepts any object with the required parameters, including a `DOMQuad`, {{domxref("DOMPoint")}} or {{domxref("DOMPointReadOnly")}}. ## Syntax diff --git a/files/en-us/web/api/domquad/index.md b/files/en-us/web/api/domquad/index.md index eb8cfe0312e5d8b..22ef8b7c95eae0d 100644 --- a/files/en-us/web/api/domquad/index.md +++ b/files/en-us/web/api/domquad/index.md @@ -27,15 +27,18 @@ A `DOMQuad` is a collection of four `DOMPoint`s defining the corners of an arbit ## Instance methods -- {{domxref("DOMQuad.fromRect()")}} - - : Returns a new `DOMQuad` object based on the passed set of coordinates. -- {{domxref("DOMQuad.fromQuad()")}} - - : Returns a new `DOMQuad` object or a set of quadrilateral coordinates based on the provided input. - {{domxref("DOMQuad.getBounds()")}} - : Returns a {{domxref("DOMRect")}} object with the coordinates and dimensions of the `DOMQuad` object. - {{domxref("DOMQuad.toJSON()")}} - : Returns a JSON representation of the `DOMQuad` object. +## Static methods + +- {{domxref("DOMQuad.fromRect_static", "DOMQuad.fromRect()")}} + - : Returns a new `DOMQuad` object based on the passed set of coordinates. +- {{domxref("DOMQuad.fromQuad_static", "DOMQuad.fromQuad()")}} + - : Returns a new `DOMQuad` object or a set of quadrilateral coordinates based on the provided input. + ## Specifications {{Specifications}} diff --git a/files/en-us/web/api/domquad/p1/index.md b/files/en-us/web/api/domquad/p1/index.md index ab15eb068935873..bdeac744c924844 100644 --- a/files/en-us/web/api/domquad/p1/index.md +++ b/files/en-us/web/api/domquad/p1/index.md @@ -8,7 +8,7 @@ browser-compat: api.DOMQuad.p1 {{APIRef("Geometry Interfaces")}}{{AvailableInWorkers}} -The **`DOMQuad`** interface's **`p1`** property holds the {{domxref("DOMPoint")}} object that represents one of the four corners of the `DOMQuad`. When created from {{domxref("DOMQuad.fromRect()")}}, it is the point (x, y). +The **`DOMQuad`** interface's **`p1`** property holds the {{domxref("DOMPoint")}} object that represents one of the four corners of the `DOMQuad`. When created from {{domxref("DOMQuad.fromRect_static", "DOMQuad.fromRect()")}}, it is the point (x, y). ## Value diff --git a/files/en-us/web/api/domquad/p2/index.md b/files/en-us/web/api/domquad/p2/index.md index 24d2087cf16d91e..7c731bda29186e0 100644 --- a/files/en-us/web/api/domquad/p2/index.md +++ b/files/en-us/web/api/domquad/p2/index.md @@ -8,7 +8,7 @@ browser-compat: api.DOMQuad.p2 {{APIRef("Geometry Interfaces")}}{{AvailableInWorkers}} -The **`DOMQuad`** interface's **`p2`** property holds the {{domxref("DOMPoint")}} object that represents one of the four corners of the `DOMQuad`. When created from {{domxref("DOMQuad.fromRect()")}}, it is the point (x + width, y). +The **`DOMQuad`** interface's **`p2`** property holds the {{domxref("DOMPoint")}} object that represents one of the four corners of the `DOMQuad`. When created from {{domxref("DOMQuad.fromRect_static", "DOMQuad.fromRect()")}}, it is the point (x + width, y). ## Value diff --git a/files/en-us/web/api/domquad/p3/index.md b/files/en-us/web/api/domquad/p3/index.md index c701fe6b6aa146f..2ed8d44123ba974 100644 --- a/files/en-us/web/api/domquad/p3/index.md +++ b/files/en-us/web/api/domquad/p3/index.md @@ -8,7 +8,7 @@ browser-compat: api.DOMQuad.p3 {{APIRef("Geometry Interfaces")}}{{AvailableInWorkers}} -The **`DOMQuad`** interface's **`p3`** property holds the {{domxref("DOMPoint")}} object that represents one of the four corners of the `DOMQuad`. When created from {{domxref("DOMQuad.fromRect()")}}, it is the point (x + width, y + height). +The **`DOMQuad`** interface's **`p3`** property holds the {{domxref("DOMPoint")}} object that represents one of the four corners of the `DOMQuad`. When created from {{domxref("DOMQuad.fromRect_static", "DOMQuad.fromRect()")}}, it is the point (x + width, y + height). ## Value diff --git a/files/en-us/web/api/domquad/p4/index.md b/files/en-us/web/api/domquad/p4/index.md index f3afef7ef44ceb0..c8fc53eb0b431b2 100644 --- a/files/en-us/web/api/domquad/p4/index.md +++ b/files/en-us/web/api/domquad/p4/index.md @@ -8,7 +8,7 @@ browser-compat: api.DOMQuad.p4 {{APIRef("Geometry Interfaces")}}{{AvailableInWorkers}} -The **`DOMQuad`** interface's **`p4`** property holds the {{domxref("DOMPoint")}} object that represents one of the four corners of the `DOMQuad`. When created from {{domxref("DOMQuad.fromRect()")}}, it is the point (x, y + height). +The **`DOMQuad`** interface's **`p4`** property holds the {{domxref("DOMPoint")}} object that represents one of the four corners of the `DOMQuad`. When created from {{domxref("DOMQuad.fromRect_static", "DOMQuad.fromRect()")}}, it is the point (x, y + height). ## Value diff --git a/files/en-us/web/api/domstringmap/index.md b/files/en-us/web/api/domstringmap/index.md index 9507c6656ba1e2d..b072d606772c7df 100644 --- a/files/en-us/web/api/domstringmap/index.md +++ b/files/en-us/web/api/domstringmap/index.md @@ -20,4 +20,4 @@ The **`DOMStringMap`** interface is used for the {{domxref("HTMLElement.dataset" ## See also - {{domxref("HTMLElement.dataset")}} -- [Global attributes - `data-*`](/en-US/docs/Web/HTML/Global_attributes/data-*) +- [Global attributes - `data-*`](/en-US/docs/Web/HTML/Reference/Global_attributes/data-*) diff --git a/files/en-us/web/api/editcontext/characterboundsupdate_event/index.md b/files/en-us/web/api/editcontext/characterboundsupdate_event/index.md index 1249e1be0a3436d..6df2e038e40fa6a 100644 --- a/files/en-us/web/api/editcontext/characterboundsupdate_event/index.md +++ b/files/en-us/web/api/editcontext/characterboundsupdate_event/index.md @@ -22,10 +22,10 @@ See the documentation of the {{domxref("EditContext.updateCharacterBounds()", "u Use the event name in methods like {{domxref("EventTarget.addEventListener", "addEventListener()")}}, or set an event handler property. -```js -addEventListener("characterboundsupdate", (event) => {}); +```js-nolint +addEventListener("characterboundsupdate", (event) => { }) -oncharacterboundsupdate = (event) => {}; +oncharacterboundsupdate = (event) => { } ``` ## Event type diff --git a/files/en-us/web/api/editcontext/compositionend_event/index.md b/files/en-us/web/api/editcontext/compositionend_event/index.md index dbf3e836e42c63b..b1d99f5285e73af 100644 --- a/files/en-us/web/api/editcontext/compositionend_event/index.md +++ b/files/en-us/web/api/editcontext/compositionend_event/index.md @@ -16,10 +16,10 @@ The `compositionend` event of the {{domxref("EditContext")}} interface fires whe Use the event name in methods like {{domxref("EventTarget.addEventListener", "addEventListener()")}}, or set an event handler property. -```js -addEventListener("compositionend", (event) => {}); +```js-nolint +addEventListener("compositionend", (event) => { }) -oncompositionend = (event) => {}; +oncompositionend = (event) => { } ``` ## Examples diff --git a/files/en-us/web/api/editcontext/compositionstart_event/index.md b/files/en-us/web/api/editcontext/compositionstart_event/index.md index c505b08192bf961..1b7ca1dab0aa3c0 100644 --- a/files/en-us/web/api/editcontext/compositionstart_event/index.md +++ b/files/en-us/web/api/editcontext/compositionstart_event/index.md @@ -16,10 +16,10 @@ The `compositionstart` event of the {{domxref("EditContext")}} interface fires w Use the event name in methods like {{domxref("EventTarget.addEventListener", "addEventListener()")}}, or set an event handler property. -```js -addEventListener("compositionstart", (event) => {}); +```js-nolint +addEventListener("compositionstart", (event) => { }) -oncompositionstart = (event) => {}; +oncompositionstart = (event) => { } ``` ## Examples diff --git a/files/en-us/web/api/editcontext/textformatupdate_event/index.md b/files/en-us/web/api/editcontext/textformatupdate_event/index.md index 9b9b4f8001a9958..c080259325ce586 100644 --- a/files/en-us/web/api/editcontext/textformatupdate_event/index.md +++ b/files/en-us/web/api/editcontext/textformatupdate_event/index.md @@ -24,10 +24,10 @@ As a web developer, you should listen for the `textformatupdate` event and updat Use the event name in methods like {{domxref("EventTarget.addEventListener", "addEventListener()")}}, or set an event handler property. -```js -addEventListener("textformatupdate", (event) => {}); +```js-nolint +addEventListener("textformatupdate", (event) => { }) -ontextformatupdate = (event) => {}; +ontextformatupdate = (event) => { } ``` ## Event type diff --git a/files/en-us/web/api/editcontext/textupdate_event/index.md b/files/en-us/web/api/editcontext/textupdate_event/index.md index d9d7ac4f60065fe..8883624988071e3 100644 --- a/files/en-us/web/api/editcontext/textupdate_event/index.md +++ b/files/en-us/web/api/editcontext/textupdate_event/index.md @@ -18,10 +18,10 @@ This event makes it possible to render the updated text and selection in the UI, Use the event name in methods like {{domxref("EventTarget.addEventListener", "addEventListener()")}}, or set an event handler property. -```js -addEventListener("textupdate", (event) => {}); +```js-nolint +addEventListener("textupdate", (event) => { }) -ontextupdate = (event) => {}; +ontextupdate = (event) => { } ``` ## Event type diff --git a/files/en-us/web/api/editcontext/updateselection/index.md b/files/en-us/web/api/editcontext/updateselection/index.md index 25eaf7c2ac7f739..9425d8a20757656 100644 --- a/files/en-us/web/api/editcontext/updateselection/index.md +++ b/files/en-us/web/api/editcontext/updateselection/index.md @@ -48,7 +48,7 @@ const editContext = new EditContext(); canvas.editContext = editContext; canvas.addEventListener("keydown", (e) => { - if (e.key == "ArrowLeft") { + if (e.key === "ArrowLeft") { const newPosition = Math.max(editContext.selectionStart - 1, 0); if (e.shiftKey) { @@ -56,7 +56,7 @@ canvas.addEventListener("keydown", (e) => { } else { editContext.updateSelection(newPosition, newPosition); } - } else if (e.key == "ArrowRight") { + } else if (e.key === "ArrowRight") { const newPosition = Math.min( editContext.selectionEnd + 1, editContext.text.length, diff --git a/files/en-us/web/api/editcontext/updatetext/index.md b/files/en-us/web/api/editcontext/updatetext/index.md index da1d17e77239f3b..6010836888f253b 100644 --- a/files/en-us/web/api/editcontext/updatetext/index.md +++ b/files/en-us/web/api/editcontext/updatetext/index.md @@ -64,7 +64,7 @@ editContext.addEventListener("textupdate", (e) => { }); canvas.addEventListener("keydown", async (e) => { - if (e.key == "v" && (e.ctrlKey || e.metaKey)) { + if (e.key === "v" && (e.ctrlKey || e.metaKey)) { const pastedText = await navigator.clipboard.readText(); console.log( `The user pasted the text: ${pastedText}. Updating the EditContext text.`, diff --git a/files/en-us/web/api/editcontext_api/guide/index.md b/files/en-us/web/api/editcontext_api/guide/index.md index 5019be3952c443d..5f6113ff1c96927 100644 --- a/files/en-us/web/api/editcontext_api/guide/index.md +++ b/files/en-us/web/api/editcontext_api/guide/index.md @@ -26,7 +26,7 @@ To use the live demo, open [Edit Context API: HTML editor demo](https://mdn.gith ## Creating the editor UI -The first step is to create the UI for the editor. The editor is a {{HTMLElement("div")}} element with the [`spellcheck`](/en-US/docs/Web/HTML/Global_attributes/spellcheck) attribute set to `false` to disable spell checking: +The first step is to create the UI for the editor. The editor is a {{HTMLElement("div")}} element with the [`spellcheck`](/en-US/docs/Web/HTML/Reference/Global_attributes/spellcheck) attribute set to `false` to disable spell checking: ```html <div id="html-editor" spellcheck="false"></div> @@ -53,7 +53,7 @@ To style the editor element, the following CSS code is used. The code makes the ## Making the editor editable -To make an element editable on the web, most of the time, you use an {{HTMLElement("input")}} element, a {{HTMLElement("textarea")}} element, or the [`contenteditable`](/en-US/docs/Web/HTML/Global_attributes/contenteditable) attribute. +To make an element editable on the web, most of the time, you use an {{HTMLElement("input")}} element, a {{HTMLElement("textarea")}} element, or the [`contenteditable`](/en-US/docs/Web/HTML/Reference/Global_attributes/contenteditable) attribute. However, with the EditContext API, you can make other types of elements editable without using an attribute. To see the list of elements that can be used with the EditContext API, see [Possible elements](/en-US/docs/Web/API/HTMLElement/editContext#possible_elements) on the HTMLElement `editContext` property page. @@ -122,7 +122,7 @@ function render(text, selectionStart, selectionEnd) { // Code to render the text selection is omitted for brevity. // See "Rendering the selection", below. - // ... + // … } ``` @@ -210,7 +210,7 @@ To render the selection, the demo app uses the {{domxref("Selection.setBaseAndEx ```js function render(text, selectionStart, selectionEnd) { - // ... + // … // The beginning of the render function is omitted for brevity. // Convert the start/end offsets to a DOM selection. diff --git a/files/en-us/web/api/editcontext_api/index.md b/files/en-us/web/api/editcontext_api/index.md index 508b2454a03f42b..f5ef28f6000c9b4 100644 --- a/files/en-us/web/api/editcontext_api/index.md +++ b/files/en-us/web/api/editcontext_api/index.md @@ -30,11 +30,11 @@ Multiple actors are involved when entering text in an editable region of an appl While the three first actors are provided by the operating system, the application is responsible for providing the editable region and the text edit context. -On the web, editable regions are often [`<textarea>`](/en-US/docs/Web/HTML/Element/textarea) elements, [`<input>`](/en-US/docs/Web/HTML/Element/input) elements, or elements with the [`contenteditable`](/en-US/docs/Web/HTML/Global_attributes/contenteditable) attribute set to `true`. For these elements, the browser automatically provides the text edit context, and web authors are not required to write any code to support text input. +On the web, editable regions are often [`<textarea>`](/en-US/docs/Web/HTML/Reference/Elements/textarea) elements, [`<input>`](/en-US/docs/Web/HTML/Reference/Elements/input) elements, or elements with the [`contenteditable`](/en-US/docs/Web/HTML/Reference/Global_attributes/contenteditable) attribute set to `true`. For these elements, the browser automatically provides the text edit context, and web authors are not required to write any code to support text input. ### Creating custom editable regions -Web authors can also create custom editable regions using the EditContext API. For example, a web author could create a rich text editor using a [`<canvas>`](/en-US/docs/Web/HTML/Element/canvas) element to render the text. In this case, the web author needs to write code to support text input. +Web authors can also create custom editable regions using the EditContext API. For example, a web author could create a rich text editor using a [`<canvas>`](/en-US/docs/Web/HTML/Reference/Elements/canvas) element to render the text. In this case, the web author needs to write code to support text input. ### Author's responsibilities @@ -85,9 +85,20 @@ You can then render the text and selection in the view, using the information pr ## Interfaces - {{DOMxRef("EditContext")}} {{experimental_inline}} - - : The **`EditContext`** interface is a JavaScript reflection of the text edit context that's normally provided transparently by the browser when using standard editable regions such as `textarea`. `EditContext` provides the state of the text being edited, with information such as the text itself, the current selection, or the location of the text in the app's UI. -- {{DOMxRef("TextFormat")}} - - : The **`TextFormat`** interface is used to represent certain formats that should be applied to text ranges when the user is composing text within the IME composition window. + - : The `EditContext` interface is a JavaScript reflection of the text edit context that's normally provided transparently by the browser when using standard editable regions such as `textarea`. `EditContext` provides the state of the text being edited, with information such as the text itself, the current selection, or the location of the text in the app's UI. +- {{DOMxRef("TextFormat")}} {{experimental_inline}} + - : The `TextFormat` interface is used to represent certain formats that should be applied to text ranges when the user is composing text within the IME composition window. +- {{domxref("TextUpdateEvent")}} {{experimental_inline}} + - : The `TextUpdateEvent` interface is a [DOM event](/en-US/docs/Web/API/Event) that represents a text or selection update in an editable text region that's attached to an {{domxref("EditContext")}} instance. +- {{domxref("TextFormatUpdateEvent")}} {{experimental_inline}} + - : The `TextFormatUpdateEvent` interface is a [DOM event](/en-US/docs/Web/API/Event) that represents a list of text formats that an {{glossary("Input Method Editor")}} (IME) window wants to apply to the text being composed in an editable region that's attached to an {{domxref("EditContext")}} instance. +- {{domxref("CharacterBoundsUpdateEvent")}} {{experimental_inline}} + - : The `CharacterBoundsUpdateEvent` interface is a [DOM event](/en-US/docs/Web/API/Event) that represents a request from the operating system to know the bounds of certain characters within an editable region that's attached to an {{domxref("EditContext")}} instance. + +## Extensions to other interfaces + +- {{domxref("HTMLElement.editContext")}} {{experimental_inline}} + - : The `editContext` property of the {{domxref("HTMLElement")}} interface gets and sets an element's associated {{domxref("EditContext")}} object. ## Specifications diff --git a/files/en-us/web/api/element/afterscriptexecute_event/index.md b/files/en-us/web/api/element/afterscriptexecute_event/index.md index 00247ee07d8bb2b..a51713cd105d006 100644 --- a/files/en-us/web/api/element/afterscriptexecute_event/index.md +++ b/files/en-us/web/api/element/afterscriptexecute_event/index.md @@ -24,10 +24,10 @@ This event is not cancelable. Use the event name in methods like {{domxref("EventTarget.addEventListener", "addEventListener()")}}, or set an event handler property. -```js -addEventListener("afterscriptexecute", (event) => {}); +```js-nolint +addEventListener("afterscriptexecute", (event) => { }) -onafterscriptexecute = (event) => {}; +onafterscriptexecute = (event) => { } ``` ## Event type diff --git a/files/en-us/web/api/element/animate/index.md b/files/en-us/web/api/element/animate/index.md index 7647672bb63f7dd..ce572fc62612427 100644 --- a/files/en-us/web/api/element/animate/index.md +++ b/files/en-us/web/api/element/animate/index.md @@ -37,35 +37,17 @@ animate(keyframes, options) - : A property unique to `animate()`: A string with which to reference the animation. - `rangeEnd` {{optional_inline}} - - : Specifies the end of an animation's attachment range along its timeline, i.e. where along the timeline an animation will end. The JavaScript equivalent of the CSS {{cssxref("animation-range-end")}} property. `rangeEnd` can take several different value types, as follows: + - : Specifies the end of an animation's attachment range along its timeline, i.e., where along the timeline an animation will end. The JavaScript equivalent of the CSS {{cssxref("animation-range-end")}} property. `rangeEnd` can take several different value types, as follows: - - A string that can be `normal` (meaning no change to the animation's attachment range), a CSS {{cssxref("length-percentage")}} representing an offset, a `<timeline-range-name>`, or a `<timeline-range-name>` with a `<length-percentage>` following it. For example: - - ```plain - "normal" - "entry" - "cover 100%" - ``` + - A string that can be `normal` (meaning no change to the animation's attachment range), a CSS {{cssxref("length-percentage")}} representing an offset, a `<timeline-range-name>`, or a `<timeline-range-name>` with a `<length-percentage>` following it. For example: `"normal"`, `"entry"`, or `"cover 100%"`. See [`animation-range`](/en-US/docs/Web/CSS/animation-range) for a detailed description of the available values. Also check out the [View Timeline Ranges Visualizer](https://scroll-driven-animations.style/tools/view-timeline/ranges/), which shows exactly what the different values mean in an easy visual format. - - An object containing `rangeName` (a string) and `offset` (a {{domxref("CSSNumericValue")}}) properties representing a `<timeline-range-name>` and `<length-percentage>`, as described in the previous bullet. For example: - - ```js - { - rangeName: 'entry', - offset: CSS.percent('100'), - } - ``` - - - A {{domxref("CSSNumericValue")}} representing an offset, for example: - - ```js - CSS.percent("100"); - ``` + - An object containing `rangeName` (a string) and `offset` (a {{domxref("CSSNumericValue")}}) properties representing a `<timeline-range-name>` and `<length-percentage>`, as described in the previous bullet. For example: `{ rangeName: "entry", offset: CSS.percent("100") }`. + - A {{domxref("CSSNumericValue")}} representing an offset, for example: `CSS.percent("100")`. - `rangeStart` {{optional_inline}} - - : Specifies the start of an animation's attachment range along its timeline, i.e. where along the timeline an animation will start. The JavaScript equivalent of the CSS {{cssxref("animation-range-start")}} property. `rangeStart` can take the same value types as `rangeEnd`. + - : Specifies the start of an animation's attachment range along its timeline, i.e., where along the timeline an animation will start. The JavaScript equivalent of the CSS {{cssxref("animation-range-start")}} property. `rangeStart` can take the same value types as `rangeEnd`. - `timeline` {{optional_inline}} - : A property unique to `animate()`: The {{domxref("AnimationTimeline")}} to associate with the animation. Defaults to {{domxref("Document.timeline")}}. The JavaScript equivalent of the CSS {{cssxref("animation-timeline")}} property. @@ -158,7 +140,7 @@ document.getElementById("tunnel").animate( ### Implicit to/from keyframes In newer browser versions, you are able to set a beginning or end state for an -animation only (i.e. a single keyframe), and the browser will infer the other end of the +animation only (i.e., a single keyframe), and the browser will infer the other end of the animation if it is able to. For example, consider [this simple animation](https://mdn.github.io/dom-examples/web-animations-api/implicit-keyframes.html) — the Keyframe object looks like so: ```js diff --git a/files/en-us/web/api/element/animationcancel_event/index.md b/files/en-us/web/api/element/animationcancel_event/index.md index 55ff04044464b19..48fd66f27533cb8 100644 --- a/files/en-us/web/api/element/animationcancel_event/index.md +++ b/files/en-us/web/api/element/animationcancel_event/index.md @@ -16,10 +16,10 @@ An event handler for this event can be added by setting the `onanimationcancel` Use the event name in methods like {{domxref("EventTarget.addEventListener", "addEventListener()")}}, or set an event handler property. -```js -addEventListener("animationcancel", (event) => {}); +```js-nolint +addEventListener("animationcancel", (event) => { }) -onanimationcancel = (event) => {}; +onanimationcancel = (event) => { } ``` ## Event type diff --git a/files/en-us/web/api/element/animationend_event/index.md b/files/en-us/web/api/element/animationend_event/index.md index c5761fb2002ffe9..8e6c46fdb6062f0 100644 --- a/files/en-us/web/api/element/animationend_event/index.md +++ b/files/en-us/web/api/element/animationend_event/index.md @@ -14,10 +14,10 @@ The **`animationend`** event is fired when a [CSS Animation](/en-US/docs/Web/CSS Use the event name in methods like {{domxref("EventTarget.addEventListener", "addEventListener()")}}, or set an event handler property. -```js -addEventListener("animationend", (event) => {}); +```js-nolint +addEventListener("animationend", (event) => { }) -onanimationend = (event) => {}; +onanimationend = (event) => { } ``` ## Event type diff --git a/files/en-us/web/api/element/animationiteration_event/index.md b/files/en-us/web/api/element/animationiteration_event/index.md index f800651dfa7631b..8e6a67ee566e759 100644 --- a/files/en-us/web/api/element/animationiteration_event/index.md +++ b/files/en-us/web/api/element/animationiteration_event/index.md @@ -14,10 +14,10 @@ The **`animationiteration`** event is fired when an iteration of a [CSS Animatio Use the event name in methods like {{domxref("EventTarget.addEventListener", "addEventListener()")}}, or set an event handler property. -```js -addEventListener("animationiteration", (event) => {}); +```js-nolint +addEventListener("animationiteration", (event) => { }) -onanimationiteration = (event) => {}; +onanimationiteration = (event) => { } ``` ## Event type diff --git a/files/en-us/web/api/element/animationstart_event/index.md b/files/en-us/web/api/element/animationstart_event/index.md index 6276e5f68cd0218..c3a33338106cccc 100644 --- a/files/en-us/web/api/element/animationstart_event/index.md +++ b/files/en-us/web/api/element/animationstart_event/index.md @@ -14,10 +14,10 @@ The **`animationstart`** event is fired when a [CSS Animation](/en-US/docs/Web/C Use the event name in methods like {{domxref("EventTarget.addEventListener", "addEventListener()")}}, or set an event handler property. -```js -addEventListener("animationstart", (event) => {}); +```js-nolint +addEventListener("animationstart", (event) => { }) -onanimationstart = (event) => {}; +onanimationstart = (event) => { } ``` ## Event type diff --git a/files/en-us/web/api/element/ariaactivedescendantelement/index.md b/files/en-us/web/api/element/ariaactivedescendantelement/index.md new file mode 100644 index 000000000000000..d3d5af032944358 --- /dev/null +++ b/files/en-us/web/api/element/ariaactivedescendantelement/index.md @@ -0,0 +1,103 @@ +--- +title: "Element: ariaActiveDescendantElement property" +short-title: ariaActiveDescendantElement +slug: Web/API/Element/ariaActiveDescendantElement +page-type: web-api-instance-property +browser-compat: api.Element.ariaActiveDescendantElement +--- + +{{APIRef("DOM")}} + +The **`ariaActiveDescendantElement`** property of the {{domxref("Element")}} interface represents the current active element when focus is on a [`composite`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/composite_role) widget, [`combobox`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/combobox_role), [`textbox`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/textbox_role), [`group`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/group_role), or [`application`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/application_role). + +The [`aria-activedescendant`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-activedescendant) topic contains additional information about how the attribute and property should be used. + +## Value + +An subclass of {{domxref("HTMLElement")}} that represents the active descendant, or `null` if there is no active descendant. + +## Description + +The property is a flexible alternative to using the [`aria-activedescendant`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-activedescendant) attribute. +Unlike `aria-activedescendant`, the element assigned to this property does not have to have an [`id`](/en-US/docs/Web/HTML/Reference/Global_attributes/id) attribute. + +The property reflects the element's [`aria-activedescendant`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-errormessage) attribute when it is defined, but only for reference `id` values that match valid in-scope elements. +If the property is set, then the corresponding attribute is cleared. +For more information about reflected element references and scope see [Reflected element references](/en-US/docs/Web/API/Document_Object_Model/Reflected_attributes#reflected_element_references) in the _Reflected attributes_ guide. + +## Examples + +### Get the active descendant + +This example shows how `ariaActiveDescendantElement` can be used to get the current active descendant. + +#### HTML + +The HTML defines a listbox for selecting different kinds of streets, consisting of a {{htmlelement("div")}} element with the [`listbox` role](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/listbox_role) and nested `<div>` items for each of the options. +The active descendant is initially set to the element with `id` of `avenue` using `aria-activedescendant`. + +```html +<div id="streetType" role="listbox" aria-activedescendant="avenue"> + <div>Street</div> + <div id="avenue">Avenue</div> + <div>Lane</div> +</div> +``` + +```html hidden +<pre id="log"></pre> +``` + +```css hidden +#log { + height: 70px; + overflow: scroll; + padding: 0.5rem; + border: 1px solid black; +} +``` + +#### JavaScript + +The code below first checks whether the `ariaActiveDescendantElement` is supported. +It the property is supported the code then logs the value of `aria-activedescendant` (the `id` of the referenced element) using {{domxref("Element.getAttribute()")}}, the property element, and the element's text content. + +```js hidden +const logElement = document.querySelector("#log"); +function log(text) { + logElement.innerText = `${logElement.innerText}${text}\n`; + logElement.scrollTop = logElement.scrollHeight; +} +``` + +```js +// Feature test for ariaActiveDescendantElement +if ("ariaActiveDescendantElement" in Element.prototype) { + log(`getAttribute(): ${streetType.getAttribute("aria-activedescendant")}`); + log(`ariaActiveDescendantElement: ${streetType.ariaActiveDescendantElement}`); + log(`text: ${streetType.ariaActiveDescendantElement?.textContent.trim()}`); +} else { + log("ariaActiveDescendantElement not supported by browser"); +} +``` + +#### Result + +The log below shows the output of the above code. +The value returned from the `aria-activedescendant` property should be `"avenue"`, the associated element should be a `HTMLDivElement` element, and the text in that element should be `Avenue`. + +{{EmbedLiveSample("Get the active descendant","100%","190px")}} + +## Specifications + +{{Specifications}} + +## Browser compatibility + +{{Compat}} + +## See also + +- [`aria-activedescendant`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-activedescendant) attribute +- {{domxref("ElementInternals.ariaActiveDescendantElement")}} +- [Reflected element references](/en-US/docs/Web/API/Document_Object_Model/Reflected_attributes#reflected_element_references) in the _Attribute reflection_ guide. diff --git a/files/en-us/web/api/element/ariaatomic/index.md b/files/en-us/web/api/element/ariaatomic/index.md index ffef6cd175e5ac2..a44dec33eab414a 100644 --- a/files/en-us/web/api/element/ariaatomic/index.md +++ b/files/en-us/web/api/element/ariaatomic/index.md @@ -8,7 +8,7 @@ browser-compat: api.Element.ariaAtomic {{APIRef("DOM")}} -The **`ariaAtomic`** property of the {{domxref("Element")}} interface reflects the value of the [`aria-atomic`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-atomic) attribute, which indicates whether assistive technologies will present all, or only parts of, the changed region based on the change notifications defined by the [`aria-relevant`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-relevant) attribute. +The **`ariaAtomic`** property of the {{domxref("Element")}} interface reflects the value of the [`aria-atomic`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-atomic) attribute, which indicates whether assistive technologies will present all, or only parts of, the changed region based on the change notifications defined by the [`aria-relevant`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-relevant) attribute. ## Value diff --git a/files/en-us/web/api/element/ariaautocomplete/index.md b/files/en-us/web/api/element/ariaautocomplete/index.md index 9c21979d69c0756..27dd9b81655acfe 100644 --- a/files/en-us/web/api/element/ariaautocomplete/index.md +++ b/files/en-us/web/api/element/ariaautocomplete/index.md @@ -8,7 +8,7 @@ browser-compat: api.Element.ariaAutoComplete {{APIRef("DOM")}} -The **`ariaAutoComplete`** property of the {{domxref("Element")}} interface reflects the value of the [`aria-autocomplete`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-autocomplete) attribute, which indicates whether inputting text could trigger display of one or more predictions of the user's intended value for a combobox, searchbox, or textbox and specifies how predictions would be presented if they were made. +The **`ariaAutoComplete`** property of the {{domxref("Element")}} interface reflects the value of the [`aria-autocomplete`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-autocomplete) attribute, which indicates whether inputting text could trigger display of one or more predictions of the user's intended value for a combobox, searchbox, or textbox and specifies how predictions would be presented if they were made. ## Value diff --git a/files/en-us/web/api/element/ariabraillelabel/index.md b/files/en-us/web/api/element/ariabraillelabel/index.md index cf60b4703465233..c1ec9c792734203 100644 --- a/files/en-us/web/api/element/ariabraillelabel/index.md +++ b/files/en-us/web/api/element/ariabraillelabel/index.md @@ -8,10 +8,10 @@ browser-compat: api.Element.ariaBrailleLabel {{APIRef("DOM")}} -The **`ariaBrailleLabel`** property of the {{domxref("Element")}} interface reflects the value of the [`aria-braillelabel`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-braillelabel) attribute, which defines the ARIA braille label of the element. +The **`ariaBrailleLabel`** property of the {{domxref("Element")}} interface reflects the value of the [`aria-braillelabel`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-braillelabel) attribute, which defines the ARIA braille label of the element. This element label may be used by assistive technologies that can present content in braille, but should only be set if a braille-specific label would improve the user experience. -The [`aria-braillelabel`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-braillelabel) contains additional information about when the property should be set. +The [`aria-braillelabel`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-braillelabel) contains additional information about when the property should be set. ## Value diff --git a/files/en-us/web/api/element/ariabrailleroledescription/index.md b/files/en-us/web/api/element/ariabrailleroledescription/index.md index 79aa00e39badf70..944b9c32091c4e3 100644 --- a/files/en-us/web/api/element/ariabrailleroledescription/index.md +++ b/files/en-us/web/api/element/ariabrailleroledescription/index.md @@ -8,11 +8,11 @@ browser-compat: api.Element.ariaBrailleRoleDescription {{APIRef("DOM")}} -The **`ariaBrailleRoleDescription`** property of the {{domxref("Element")}} interface reflects the value of the [`aria-brailleroledescription`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-brailleroledescription) attribute, which defines the ARIA braille role description of the element. +The **`ariaBrailleRoleDescription`** property of the {{domxref("Element")}} interface reflects the value of the [`aria-brailleroledescription`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-brailleroledescription) attribute, which defines the ARIA braille role description of the element. -This property may be used to provide an abbreviated version of the [`aria-roledescription`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-roledescription) value. +This property may be used to provide an abbreviated version of the [`aria-roledescription`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-roledescription) value. It should only be used if `aria-roledescription` is present and in the rare case where it is too verbose for braille. -The [`aria-brailleroledescription`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-brailleroledescription) contains additional information about when the property should be set. +The [`aria-brailleroledescription`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-brailleroledescription) contains additional information about when the property should be set. ## Value diff --git a/files/en-us/web/api/element/ariabusy/index.md b/files/en-us/web/api/element/ariabusy/index.md index f1604ae29f0f284..92a4d34e6f9ccb8 100644 --- a/files/en-us/web/api/element/ariabusy/index.md +++ b/files/en-us/web/api/element/ariabusy/index.md @@ -8,7 +8,7 @@ browser-compat: api.Element.ariaBusy {{APIRef("DOM")}} -The **`ariaBusy`** property of the {{domxref("Element")}} interface reflects the value of the [`aria-busy`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-busy) attribute, which indicates whether an element is being modified, as assistive technologies may want to wait until the modifications are complete before exposing them to the user. +The **`ariaBusy`** property of the {{domxref("Element")}} interface reflects the value of the [`aria-busy`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-busy) attribute, which indicates whether an element is being modified, as assistive technologies may want to wait until the modifications are complete before exposing them to the user. ## Value diff --git a/files/en-us/web/api/element/ariachecked/index.md b/files/en-us/web/api/element/ariachecked/index.md index 3c4bef725ec05b5..92a2754982365d4 100644 --- a/files/en-us/web/api/element/ariachecked/index.md +++ b/files/en-us/web/api/element/ariachecked/index.md @@ -8,7 +8,7 @@ browser-compat: api.Element.ariaChecked {{APIRef("DOM")}} -The **`ariaChecked`** property of the {{domxref("Element")}} interface reflects the value of the [`aria-checked`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-checked) attribute, which indicates the current "checked" state of checkboxes, radio buttons, and other widgets that have a checked state. +The **`ariaChecked`** property of the {{domxref("Element")}} interface reflects the value of the [`aria-checked`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-checked) attribute, which indicates the current "checked" state of checkboxes, radio buttons, and other widgets that have a checked state. > [!NOTE] > Where possible use an HTML {{htmlelement("input")}} element with `type="checkbox"` as this element has built in semantics and does not require ARIA attributes. @@ -58,4 +58,4 @@ console.log(el.ariaChecked); // "true" ## See also -- [ARIA: checkbox role](/en-US/docs/Web/Accessibility/ARIA/Roles/checkbox_role) +- [ARIA: checkbox role](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/checkbox_role) diff --git a/files/en-us/web/api/element/ariacolcount/index.md b/files/en-us/web/api/element/ariacolcount/index.md index 92921e1f6ea839f..b5f43825750beda 100644 --- a/files/en-us/web/api/element/ariacolcount/index.md +++ b/files/en-us/web/api/element/ariacolcount/index.md @@ -8,7 +8,7 @@ browser-compat: api.Element.ariaColCount {{APIRef("DOM")}} -The **`ariaColCount`** property of the {{domxref("Element")}} interface reflects the value of the [`aria-colcount`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-colcount) attribute, which defines the number of columns in a table, grid, or treegrid. +The **`ariaColCount`** property of the {{domxref("Element")}} interface reflects the value of the [`aria-colcount`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-colcount) attribute, which defines the number of columns in a table, grid, or treegrid. ## Value @@ -75,4 +75,4 @@ console.log(el.ariaColCount); // 3 ## See also -- [ARIA: table role](/en-US/docs/Web/Accessibility/ARIA/Roles/table_role) +- [ARIA: table role](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/table_role) diff --git a/files/en-us/web/api/element/ariacolindex/index.md b/files/en-us/web/api/element/ariacolindex/index.md index c244d4281978a3f..e837ed0b58fea95 100644 --- a/files/en-us/web/api/element/ariacolindex/index.md +++ b/files/en-us/web/api/element/ariacolindex/index.md @@ -8,7 +8,7 @@ browser-compat: api.Element.ariaColIndex {{APIRef("DOM")}} -The **`ariaColIndex`** property of the {{domxref("Element")}} interface reflects the value of the [`aria-colindex`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-colindex) attribute, which defines an element's column index or position with respect to the total number of columns within a table, grid, or treegrid. +The **`ariaColIndex`** property of the {{domxref("Element")}} interface reflects the value of the [`aria-colindex`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-colindex) attribute, which defines an element's column index or position with respect to the total number of columns within a table, grid, or treegrid. ## Value @@ -85,4 +85,4 @@ console.log(el.ariaColIndex); // 2 ## See also -- [ARIA: table role](/en-US/docs/Web/Accessibility/ARIA/Roles/table_role) +- [ARIA: table role](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/table_role) diff --git a/files/en-us/web/api/element/ariacolindextext/index.md b/files/en-us/web/api/element/ariacolindextext/index.md index 75d5216c1306aaf..3bf8c8d14a0224e 100644 --- a/files/en-us/web/api/element/ariacolindextext/index.md +++ b/files/en-us/web/api/element/ariacolindextext/index.md @@ -7,7 +7,7 @@ browser-compat: api.Element.ariaColIndexText {{APIRef("DOM")}} -The **`ariaColIndexText`** property of the {{domxref("Element")}} interface reflects the value of the [`aria-colindextext`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-colindextext) attribute, which defines a human readable text alternative of aria-colindex. +The **`ariaColIndexText`** property of the {{domxref("Element")}} interface reflects the value of the [`aria-colindextext`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-colindextext) attribute, which defines a human readable text alternative of aria-colindex. ## Value @@ -85,4 +85,4 @@ console.log(el.ariaColIndexText); // "New column name" ## See also -- [ARIA: table role](/en-US/docs/Web/Accessibility/ARIA/Roles/table_role) +- [ARIA: table role](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/table_role) diff --git a/files/en-us/web/api/element/ariacolspan/index.md b/files/en-us/web/api/element/ariacolspan/index.md index 7047d1a7a635beb..17c955e6634fdeb 100644 --- a/files/en-us/web/api/element/ariacolspan/index.md +++ b/files/en-us/web/api/element/ariacolspan/index.md @@ -8,7 +8,7 @@ browser-compat: api.Element.ariaColSpan {{APIRef("DOM")}} -The **`ariaColSpan`** property of the {{domxref("Element")}} interface reflects the value of the [`aria-colspan`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-colspan) attribute, which defines the number of columns spanned by a cell or gridcell within a table, grid, or treegrid. +The **`ariaColSpan`** property of the {{domxref("Element")}} interface reflects the value of the [`aria-colspan`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-colspan) attribute, which defines the number of columns spanned by a cell or gridcell within a table, grid, or treegrid. ## Value @@ -23,7 +23,7 @@ In this example the `aria-colspan` attribute on the element with an ID of `spann <tr> <th>Heading 1</th> <th>Heading 2</th> - <th>Heading 3</td> + <th>Heading 3</th> </tr> <tr> <td colspan="2" aria-colspan="2" id="spanning-column">Spanning</td> @@ -49,4 +49,4 @@ console.log(el.ariaColSpan); ## See also -- [ARIA: table role](/en-US/docs/Web/Accessibility/ARIA/Roles/table_role) +- [ARIA: table role](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/table_role) diff --git a/files/en-us/web/api/element/ariacontrolselements/index.md b/files/en-us/web/api/element/ariacontrolselements/index.md new file mode 100644 index 000000000000000..9e7d04f8c781f78 --- /dev/null +++ b/files/en-us/web/api/element/ariacontrolselements/index.md @@ -0,0 +1,148 @@ +--- +title: "Element: ariaControlsElements property" +short-title: ariaControlsElements +slug: Web/API/Element/ariaControlsElements +page-type: web-api-instance-property +browser-compat: api.Element.ariaControlsElements +--- + +{{APIRef("DOM")}} + +The **`ariaControlsElements`** property of the {{domxref("Element")}} interface is an array containing the elements that are controlled by the element it is applied to. +For example, this might be set on a [combobox](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/combobox_role) to indicate the element that it pops up, or on a [`scrollbar`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/scrollbar_role) to indicate the ID of the element it controls. + +The [`aria-controls`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-controls) topic contains additional information about how the attribute and property should be used. + +## Value + +An array of subclasses of {{domxref("HTMLElement")}}, representing the elements that are controlled by this element. + +When read, the returned array is static and read-only. +When written, the assigned array is copied: subsequent changes to the array do not affect the value of the property. + +## Description + +The property is a flexible alternative to using the [`aria-controls`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-controls) attribute to set the controlled elements. +Unlike `aria-controls`, the elements assigned to this property do not have to have an [`id`](/en-US/docs/Web/HTML/Reference/Global_attributes/id) attribute. + +The property reflects the [`aria-controls`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-controls) attribute when it is defined, but only for listed reference `id` values that match valid in-scope elements. +If the property is set, then the corresponding attribute is cleared. +For more information about reflected element references and scope see [Reflected element references](/en-US/docs/Web/API/Document_Object_Model/Reflected_attributes#reflected_element_references) in the _Reflected attributes_ guide. + +## Examples + +### Get the controlled elements + +This example shows how `ariaControlsElements` can be used to get the controlled elements that were set using `aria-controls`. + +#### HTML + +The HTML defines first defines a {{htmlelement("button")}} element and two {{htmlelement("div")}} elements, `panel1` and `panel2`, that it controls. +The references to the controlled panels are listed in the button's `aria-controls` attribute. + +```html +<button id="toggleButton" aria-controls="panel1 panel2" aria-expanded="false"> + Show Details +</button> + +<div class="panel" id="panel1" aria-hidden="true"> + <p>Panel1 opened/closed by button.</p> +</div> + +<div class="panel" id="panel2" aria-hidden="true"> + <p>Panel2 opened/closed by button.</p> +</div> +``` + +```css +.panel { + display: none; /* Initially hidden */ + border: 1px solid #ccc; + padding: 5px; + margin-top: 5px; +} +``` + +```html hidden +<pre id="log"></pre> +``` + +```css hidden +#log { + height: 70px; + overflow: scroll; + padding: 0.5rem; + border: 1px solid black; +} +``` + +#### JavaScript + +The code first sets up the panels to be toggled open or hidden based on the [`aria-expanded`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-expanded) attribute of the button. + +```js hidden +const logElement = document.querySelector("#log"); +function log(text) { + logElement.innerText = `${logElement.innerText}${text}\n`; + logElement.scrollTop = logElement.scrollHeight; +} +``` + +```js +const toggleButton = document.querySelector("#toggleButton"); +const panel1 = document.querySelector("#panel1"); +const panel2 = document.querySelector("#panel2"); + +toggleButton.addEventListener("click", () => { + const isExpanded = toggleButton.getAttribute("aria-expanded") === "true"; + + toggleButton.setAttribute("aria-expanded", !isExpanded); + panel1.style.display = isExpanded ? "none" : "block"; + panel1.setAttribute("aria-hidden", isExpanded); // true when hidden, false when shown. + + panel2.style.display = isExpanded ? "none" : "block"; + panel2.setAttribute("aria-hidden", isExpanded); // true when hidden, false when shown. +}); +``` + +Next the example gets the value of the `aria-controls` attribute with {{domxref("Element.getAttribute()")}} (a string listing the `id` values of the referenced elements). +It then checks whether the `ariaControlsElements` property is supported, and if so, logs its value. +Finally it returns and logs the inner text for each of the controlled elements. + +```js +log(`aria-controls: ${toggleButton.getAttribute("aria-controls")}`); +// Feature test for ariaControlsElements +if ("ariaControlsElements" in Element.prototype) { + // Get ariaControlsElements + const controlledElements = toggleButton.ariaControlsElements; + log(`ariaControlsElements: ${controlledElements}`); + + // List innerText for each of the ariaControlsElements + controlledElements.forEach((controlled) => { + log(` Controlled element text: ${controlled.textContent.trim()}`); + }); +} else { + log("element.ariaControlsElements: not supported by browser"); +} +``` + +#### Result + +Click the button below to show and hide the panels. +The log shows the original element references, the associated/returned elements, and the inner text of each element. + +{{EmbedLiveSample("Get the controlled elements","100%","280px")}} + +## Specifications + +{{Specifications}} + +## Browser compatibility + +{{Compat}} + +## See also + +- [`aria-controls`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-controls) attribute +- {{domxref("ElementInternals.ariaControlsElements")}} +- [Reflected element references](/en-US/docs/Web/API/Document_Object_Model/Reflected_attributes#reflected_element_references) in the _Attribute reflection_ guide diff --git a/files/en-us/web/api/element/ariacurrent/index.md b/files/en-us/web/api/element/ariacurrent/index.md index 4b33151c493fb35..bdaa8f58128c4b0 100644 --- a/files/en-us/web/api/element/ariacurrent/index.md +++ b/files/en-us/web/api/element/ariacurrent/index.md @@ -8,7 +8,7 @@ browser-compat: api.Element.ariaCurrent {{APIRef("DOM")}} -The **`ariaCurrent`** property of the {{domxref("Element")}} interface reflects the value of the [`aria-current`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-current) attribute, which indicates the element that represents the current item within a container or set of related elements. +The **`ariaCurrent`** property of the {{domxref("Element")}} interface reflects the value of the [`aria-current`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-current) attribute, which indicates the element that represents the current item within a container or set of related elements. ## Value diff --git a/files/en-us/web/api/element/ariadescribedbyelements/index.md b/files/en-us/web/api/element/ariadescribedbyelements/index.md new file mode 100644 index 000000000000000..368423032b9547d --- /dev/null +++ b/files/en-us/web/api/element/ariadescribedbyelements/index.md @@ -0,0 +1,122 @@ +--- +title: "Element: ariaDescribedByElements property" +short-title: ariaDescribedByElements +slug: Web/API/Element/ariaDescribedByElements +page-type: web-api-instance-property +browser-compat: api.Element.ariaDescribedByElements +--- + +{{APIRef("DOM")}} + +The **`ariaDescribedByElements`** property of the {{domxref("Element")}} interface is an array containing the element (or elements) that provide an accessible description for the element it is applied to. +The accessible description is similar to the accessible label (see {{domxref("Element/ariaLabelledByElements","ariaLabelledByElements")}}), but provides more verbose information. + +The [`aria-describedby`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-describedby) topic contains additional information about how the attribute and property should be used. + +## Value + +An array of subclasses of {{domxref("HTMLElement")}}. +The inner text of these elements can be joined with spaces to get the accessible description. + +When read, the returned array is a static and read-only. +When written, the assigned array is copied: subsequent changes to the array do not affect the value of the property. + +## Description + +The property is a flexible alternative to using the [`aria-describedby`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-describedby) attribute to set the accessible description. +Unlike `aria-describedby`, the elements assigned to this property do not have to have an [`id`](/en-US/docs/Web/HTML/Reference/Global_attributes/id) attribute. + +The property reflects the element's [`aria-describedby`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-describedby) attribute when it is defined, but only for listed reference `id` values that match valid in-scope elements. +If the property is set, then the corresponding attribute is cleared. +For more information about reflected element references and scope see [Reflected element references](/en-US/docs/Web/API/Document_Object_Model/Reflected_attributes#reflected_element_references) in the _Reflected attributes_ guide. + +## Examples + +### Get the accessible description + +This example shows how `ariaDescribedByElements` can be used to get the accessible description defined using `aria-describedby`. + +#### HTML + +The HTML defines two {{htmlelement("span")}} elements and references their ids in the `aria-describedby` attribute of a {{htmlelement("button")}}. + +```html +<button aria-describedby="trash-desc1 trash-desc2">Move to trash</button> +… +<span id="trash-desc1">Trash will be permanently removed after 30 days.</span> +<span id="trash-desc2">Or Else!</span> +``` + +```html hidden +<pre id="log"></pre> +``` + +#### CSS + +Here we'll just hide the `<span>` elements that contain our accessible text. + +```css +span { + display: none; +} +``` + +```css hidden +#log { + height: 70px; + overflow: scroll; + padding: 0.5rem; + border: 1px solid black; +} +``` + +#### JavaScript + +The code below first logs the value of the `aria-describedby` attribute from {{domxref("Element.getAttribute()")}} (a string listing the `id` values of the referenced elements). +It then checks whether the `ariaDescribedByElements` is supported, and if so, logs its value. +Finally it returns the accessible string, calculated by iterating through the returned elements and concatenating their inner text. + +```js hidden +const logElement = document.querySelector("#log"); +function log(text) { + logElement.innerText = `${logElement.innerText}${text}\n`; + logElement.scrollTop = logElement.scrollHeight; +} +``` + +```js +const buttonElement = document.querySelector("button"); +log(`aria-describedby: ${buttonElement.getAttribute("aria-describedby")}`); +// Feature test for ariaDescribedByElements +if ("ariaDescribedByElements" in Element.prototype) { + // Get ariaDescribedByElements + const buttonElements = buttonElement.ariaDescribedByElements; + log(`ariaDescribedByElements: ${buttonElements}`); + + // Accessible description from the elements + const text = buttonElements.map((e) => e.textContent.trim()).join(" "); + log(`Accessible description: ${text.trim()}`); +} else { + log("element.ariaDescribedByElements: not supported by browser"); +} +``` + +#### Result + +The log below shows the original element references, the associated/returned elements, and the accessible description. + +{{EmbedLiveSample("Get the accessible description","100%","150px")}} + +## Specifications + +{{Specifications}} + +## Browser compatibility + +{{Compat}} + +## See also + +- [`aria-describedby`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-describedby) attribute +- {{domxref("ElementInternals.ariaDescribedByElements")}} +- [Reflected element references](/en-US/docs/Web/API/Document_Object_Model/Reflected_attributes#reflected_element_references) in the _Attribute reflection_ guide diff --git a/files/en-us/web/api/element/ariadescription/index.md b/files/en-us/web/api/element/ariadescription/index.md index 7da963319e428a5..1804cd247903e8f 100644 --- a/files/en-us/web/api/element/ariadescription/index.md +++ b/files/en-us/web/api/element/ariadescription/index.md @@ -8,7 +8,7 @@ browser-compat: api.Element.ariaDescription {{APIRef("DOM")}} -The **`ariaDescription`** property of the {{domxref("Element")}} interface reflects the value of the [`aria-description`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-description) attribute, which defines a string value that describes or annotates the current element. +The **`ariaDescription`** property of the {{domxref("Element")}} interface reflects the value of the [`aria-description`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-description) attribute, which defines a string value that describes or annotates the current element. ## Value diff --git a/files/en-us/web/api/element/ariadetailselements/index.md b/files/en-us/web/api/element/ariadetailselements/index.md new file mode 100644 index 000000000000000..39bfb401ba57fa8 --- /dev/null +++ b/files/en-us/web/api/element/ariadetailselements/index.md @@ -0,0 +1,112 @@ +--- +title: "Element: ariaDetailsElements property" +short-title: ariaDetailsElements +slug: Web/API/Element/ariaDetailsElements +page-type: web-api-instance-property +browser-compat: api.Element.ariaDetailsElements +--- + +{{APIRef("DOM")}} + +The **`ariaDetailsElements`** property of the {{domxref("Element")}} interface is an array containing the element (or elements) that provide an accessible details for the element it is applied to. +The accessible details are similar to the accessible description (see {{domxref("Element/ariaDescribedByElements","ariaDescribedByElements")}}), but provides more verbose information. + +The [`aria-details`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-details) topic contains additional information about how the attribute and property should be used. + +## Value + +An array of subclasses of {{domxref("HTMLElement")}}. +The inner text of these elements can be joined with spaces to get the accessible details. + +When read, the returned array is a static and read-only. +When written, the assigned array is copied: subsequent changes to the array do not affect the value of the property. + +## Description + +The property is a flexible alternative to using the [`aria-details`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-details) attribute to set the accessible details information. +Unlike `aria-details`, the elements assigned to this property do not have to have an [`id`](/en-US/docs/Web/HTML/Reference/Global_attributes/id) attribute. + +The property reflects the element's [`aria-details`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-details) attribute when it is defined, but only for listed reference `id` values that match valid in-scope elements. +If the property is set, then the corresponding attribute is cleared. +For more information about reflected element references and scope see [Reflected element references](/en-US/docs/Web/API/Document_Object_Model/Reflected_attributes#reflected_element_references) in the _Reflected attributes_ guide. + +## Examples + +### Get the accessible details + +This example shows how `ariaDetailsElements` can be used to get the information defined using the `aria-details` attribute in HTML. + +#### HTML + +The HTML defines two {{htmlelement("span")}} elements and references their ids in the `aria-details` attribute of a {{htmlelement("button")}}. + +```html +<button aria-details="details1 details2">Button text</button> +… +<span id="details1">Details 1 information about the element.</span> +<span id="details2">Details 2 information about the element.</span> +``` + +```html hidden +<pre id="log"></pre> +``` + +```css hidden +#log { + height: 70px; + overflow-x: scroll; + padding: 0.5rem; + border: 1px solid black; +} +``` + +#### JavaScript + +The code below first logs the value of the `aria-details` attribute from {{domxref("Element.getAttribute()")}} (a string listing the `id` values of the referenced elements). +It then checks whether the `ariaDetailsElements` is supported, and if so, logs its value. +Finally it returns the accessible string, calculated by iterating through the returned elements and concatenating their inner text. + +```js hidden +const logElement = document.querySelector("#log"); +function log(text) { + logElement.innerText = `${logElement.innerText}${text}\n`; + logElement.scrollTop = logElement.scrollHeight; +} +``` + +```js +const buttonElement = document.querySelector("button"); +log(`aria-details: ${buttonElement.getAttribute("aria-details")}`); +// Feature test for ariaDetailsElements +if ("ariaDetailsElements" in Element.prototype) { + // Get ariaDetailsElements + const buttonElements = buttonElement.ariaDetailsElements; + log(`ariaDetailsElements: ${buttonElements}`); + + // Accessible details from ariaDetailsElements + const text = buttonElements.map((e) => e.textContent.trim()).join(" "); + log(`Accessible details: ${text.trim()}`); +} else { + log("element.ariaDetailsElements: not supported by browser"); +} +``` + +#### Result + +The log below shows the original element references, the associated/returned elements, and the accessible details. + +{{EmbedLiveSample("Get the accessible details","100%","150px")}} + +## Specifications + +{{Specifications}} + +## Browser compatibility + +{{Compat}} + +## See also + +- [`aria-details`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-details) attribute +- {{domxref("ElementInternals.ariaDetailsElements")}} +- [Reflected element references](/en-US/docs/Web/API/Document_Object_Model/Reflected_attributes#reflected_element_references) in the _Attribute reflection_ guide. diff --git a/files/en-us/web/api/element/ariadisabled/index.md b/files/en-us/web/api/element/ariadisabled/index.md index 6b3bedfb8d1c514..713e92b8af48875 100644 --- a/files/en-us/web/api/element/ariadisabled/index.md +++ b/files/en-us/web/api/element/ariadisabled/index.md @@ -8,7 +8,7 @@ browser-compat: api.Element.ariaDisabled {{APIRef("DOM")}} -The **`ariaDisabled`** property of the {{domxref("Element")}} interface reflects the value of the [`aria-disabled`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-disabled) attribute, which indicates that the element is perceivable but disabled, so it is not editable or otherwise operable. +The **`ariaDisabled`** property of the {{domxref("Element")}} interface reflects the value of the [`aria-disabled`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-disabled) attribute, which indicates that the element is perceivable but disabled, so it is not editable or otherwise operable. > [!NOTE] > Where possible, use the {{htmlelement("input")}} element with `type="button"` or the {{htmlelement("button")}} element — because those elements have built in semantics and do not require ARIA attributes. diff --git a/files/en-us/web/api/element/ariaerrormessageelements/index.md b/files/en-us/web/api/element/ariaerrormessageelements/index.md new file mode 100644 index 000000000000000..52ee055c064d52e --- /dev/null +++ b/files/en-us/web/api/element/ariaerrormessageelements/index.md @@ -0,0 +1,144 @@ +--- +title: "Element: ariaErrorMessageElements property" +short-title: ariaErrorMessageElements +slug: Web/API/Element/ariaErrorMessageElements +page-type: web-api-instance-property +browser-compat: api.Element.ariaErrorMessageElements +--- + +{{APIRef("DOM")}} + +The **`ariaErrorMessageElements`** property of the {{domxref("Element")}} interface is an array containing the element (or elements) that provide an error message for the element it is applied to. + +The [`aria-errormessage`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-errormessage) topic contains additional information about how the attribute and property should be used. + +## Value + +An array of subclasses of {{domxref("HTMLElement")}}. +The inner text of these elements can be joined with spaces to get the error message. + +When read, the returned array is a static and read-only. +When written, the assigned array is copied: subsequent changes to the array do not affect the value of the property. + +## Description + +The property is a flexible alternative to using the [`aria-errormessage`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-errormessage) attribute to set the error message for an element. +Unlike `aria-errormessage`, the elements assigned to this property do not have to have an [`id`](/en-US/docs/Web/HTML/Reference/Global_attributes/id) attribute. + +The property reflects the element's [`aria-errormessage`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-errormessage) attribute when it is defined, but only for listed reference `id` values that match valid in-scope elements. +If the property is set, then the corresponding attribute is cleared. +For more information about reflected element references and scope see [Reflected element references](/en-US/docs/Web/API/Document_Object_Model/Reflected_attributes#reflected_element_references) in the _Reflected attributes_ guide. + +## Examples + +### Email input with error message + +This example shows how we use the `aria-errormessage` to set the error message for reporting entry of an invalid email address, and demonstrates how we can get and set the message using `ariaErrorMessageElements`. + +#### HTML + +First we define an HTML email input, setting its `aria-errormessage` attribute to reference an element with the `id` of `err1`. +We then define a `<span>` element that has this id, and which contains an error message. + +```html +<p> + <label for="email">Email address:</label> + <input type="email" name="email" id="email" aria-errormessage="err1" /> + <span id="err1" class="errormessage">Error: Enter a valid email address</span> +</p> +``` + +#### CSS + +We create some styles to hide the error message by default, but make it visible and styled as an error when `aria-invalid` is set on the element. + +```css +.errormessage { + visibility: hidden; +} + +[aria-invalid="true"] { + outline: 2px solid red; +} + +[aria-invalid="true"] ~ .errormessage { + visibility: visible; +} +``` + +#### JavaScript + +We then check for input, and set {{domxref("Element/ariaInvalid", "ariaInvalid")}} to `true` or `false` based on the [`typeMismatch`](/en-US/docs/Web/API/ValidityState/typeMismatch) constraint violation. +`ariaInvalid` is in turn reflected in the `aria-invalid` attribute, which hides and displays the error as needed. + +```js +const email = document.querySelector("#email"); + +email.addEventListener("input", (event) => { + if (email.validity.typeMismatch) { + email.ariaInvalid = true; + } else { + email.ariaInvalid = false; + } +}); +``` + +```html hidden +<pre id="log"></pre> +``` + +```css hidden +#log { + height: 70px; + overflow: scroll; + padding: 0.5rem; + border: 1px solid black; +} +``` + +```js hidden +const logElement = document.querySelector("#log"); +function log(text) { + logElement.innerText = `${logElement.innerText}${text}\n`; + logElement.scrollTop = logElement.scrollHeight; +} +``` + +We then log the value of the `aria-errormessage` attribute, the `ariaErrorMessageElements` and the inner text of the `ariaErrorMessageElements` + +```js +log(`aria-errormessage: ${email.getAttribute("aria-errormessage")}`); +// Feature test for ariaErrorMessageElements +if ("ariaErrorMessageElements" in Element.prototype) { + // Get ariaErrorMessageElements + const propElements = email.ariaErrorMessageElements; + log(`ariaErrorMessageElements: ${propElements}`); + + // Accessible text from element inner text + const text = propElements.map((e) => e.textContent.trim).join(" "); + log(`Error message details: ${text.trim()}`); +} else { + log("element.ariaErrorMessageElements: not supported by browser"); +} +``` + +#### Result + +As you enter an email address, the error text will be displayed until the email address is valid. +Note that the log shows the error message reference read from the attribute, the element from `ariaErrorMessageElements`, and the inner text of the element, which is its error message. + +{{EmbedLiveSample("Email input with error message","100%","180px")}} + +## Specifications + +{{Specifications}} + +## Browser compatibility + +{{Compat}} + +## See also + +- [`aria-errormessage`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-errormessage) attribute +- {{domxref("ElementInternals.ariaErrorMessageElements")}} +- [Reflected element references](/en-US/docs/Web/API/Document_Object_Model/Reflected_attributes#reflected_element_references) in the _Attribute reflection_ guide. diff --git a/files/en-us/web/api/element/ariaexpanded/index.md b/files/en-us/web/api/element/ariaexpanded/index.md index 09430400c0fa772..29da3206fbe24ea 100644 --- a/files/en-us/web/api/element/ariaexpanded/index.md +++ b/files/en-us/web/api/element/ariaexpanded/index.md @@ -8,7 +8,7 @@ browser-compat: api.Element.ariaExpanded {{APIRef("DOM")}} -The **`ariaExpanded`** property of the {{domxref("Element")}} interface reflects the value of the [`aria-expanded`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-expanded) attribute, which indicates whether a grouping element owned or controlled by this element is expanded or collapsed. +The **`ariaExpanded`** property of the {{domxref("Element")}} interface reflects the value of the [`aria-expanded`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-expanded) attribute, which indicates whether a grouping element owned or controlled by this element is expanded or collapsed. ## Value diff --git a/files/en-us/web/api/element/ariaflowtoelements/index.md b/files/en-us/web/api/element/ariaflowtoelements/index.md new file mode 100644 index 000000000000000..fc4e317a070dc23 --- /dev/null +++ b/files/en-us/web/api/element/ariaflowtoelements/index.md @@ -0,0 +1,131 @@ +--- +title: "Element: ariaFlowToElements property" +short-title: ariaFlowToElements +slug: Web/API/Element/ariaFlowToElements +page-type: web-api-instance-property +browser-compat: api.Element.ariaFlowToElements +--- + +{{APIRef("DOM")}} + +The **`ariaFlowToElements`** property of the {{domxref("Element")}} interface is an array containing the element (or elements) that provide an alternate reading order of content, overriding the general default reading order at the user's discretion. +If just one element is provided this is the next element in the reading order. +If multiple elements are provided, then each element represents a possible path that should be offered to the user for selection. + +The [`aria-flowto`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-flowto) topic contains additional information about how the attribute and property should be used. + +## Value + +An array of subclasses of {{domxref("HTMLElement")}}. + +When read, the returned array is a static and read-only. +When written, the assigned array is copied: subsequent changes to the array do not affect the value of the property. + +## Description + +The property is a flexible alternative to using the [`aria-flowto`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-flowto) attribute to set an alternative reading order. +Unlike `aria-flowto`, the elements assigned to this property do not have to have an [`id`](/en-US/docs/Web/HTML/Reference/Global_attributes/id) attribute. + +The property reflects the element's [`aria-flowto`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-flowto) attribute when it is defined, but only for listed reference `id` values that match valid in-scope elements. +If the property is set, then the corresponding attribute is cleared. +For more information about reflected element references and scope see [Reflected element references](/en-US/docs/Web/API/Document_Object_Model/Reflected_attributes#reflected_element_references) in the _Reflected attributes_ guide. + +## Examples + +### Get the flow-to element + +This example demonstrates the normal flow through three elements `section1`, `section2`, `section3` in order, and an alternative order that jumps from `section1` to `section3`, and back again. +Note that the example is illustrative unless you have accessibility tools running: we don't actually follow this alternate path. + +#### HTML + +The HTML defines three {{htmlelement("div")}} elements that define sections, with a class `"section"`, and `id` values: `section1`, `section2`, and `section3`. +Each section has a normal flow defined by it's order, starting from `section1` and ending at `section3`. +An alternative flow is defined in sections 1 and 3 using the `aria-flowto` attribute. + +```html hidden +<pre id="log"></pre> +``` + +```css hidden +#log { + height: 200px; + overflow: scroll; + padding: 0.5rem; + margin: 5px; + border: 1px solid black; +} +``` + +```html +<div id="section1" class="section" aria-flowto="section3"> + <h2>Section 1</h2> + <p>First section in normal flow. Section 3 is alternate flow.</p> + <a href="#section2">Jump to Section 2 (normal flow)</a> +</div> + +<div id="section2" class="section"> + <h2>Section 2</h2> + <p>Second section in normal flow.</p> + <a href="#section3">Jump to Section 3 (normal flow)</a> +</div> + +<div id="section3" class="section" aria-flowto="section1"> + <h2>Section 3</h2> + <p> + Third section in normal flow (end of flow). Section 1 is alternate flow. + </p> +</div> +``` + +#### JavaScript + +The code first checks whether the `ariaFlowToElements` is supported, and if so, logs its value. +It then iterates through the sections, logging the section `id`, `aria-flowto` attribute value, and `ariaFlowToElements` property value. + +```js hidden +const logElement = document.querySelector("#log"); +function log(text) { + logElement.innerText = `${logElement.innerText}${text}\n`; + logElement.scrollTop = logElement.scrollHeight; +} +``` + +```js +// Feature test for ariaFlowToElements +if ("ariaFlowToElements" in Element.prototype) { + const sections = document.querySelectorAll(".section"); + sections.forEach((sectionDivElement) => { + log(`${sectionDivElement.id}`); + log(` aria-flowto: ${sectionDivElement.getAttribute("aria-flowto")}`); + log(" ariaFlowToElements:"); + // Get the ids of each of the elements in the array + sectionDivElement.ariaFlowToElements?.forEach((elem) => { + log(` id: ${elem.id}`); + }); + }); +} else { + log("element.ariaFlowToElements: not supported by browser"); +} +``` + +#### Result + +The log below shows each of the sections (identified by `id`) and the corresponding flow-to element ids that might be selected by accessibility tools. +We note here that the attribute and property identify the same flow-to elements. + +{{EmbedLiveSample("Get the flow-to element","100%","570px")}} + +## Specifications + +{{Specifications}} + +## Browser compatibility + +{{Compat}} + +## See also + +- [`aria-flowto`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-flowto) attribute +- {{domxref("ElementInternals.ariaFlowToElements")}} +- [Reflected element references](/en-US/docs/Web/API/Document_Object_Model/Reflected_attributes#reflected_element_references) in the _Attribute reflection_ guide. diff --git a/files/en-us/web/api/element/ariahaspopup/index.md b/files/en-us/web/api/element/ariahaspopup/index.md index 90191781354f708..e27e02b70d097f6 100644 --- a/files/en-us/web/api/element/ariahaspopup/index.md +++ b/files/en-us/web/api/element/ariahaspopup/index.md @@ -8,7 +8,7 @@ browser-compat: api.Element.ariaHasPopup {{APIRef("DOM")}} -The **`ariaHasPopup`** property of the {{domxref("Element")}} interface reflects the value of the [`aria-haspopup`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-haspopup) attribute, which indicates the availability and type of interactive popup element, such as menu or dialog, that can be triggered by an element. +The **`ariaHasPopup`** property of the {{domxref("Element")}} interface reflects the value of the [`aria-haspopup`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-haspopup) attribute, which indicates the availability and type of interactive popup element, such as menu or dialog, that can be triggered by an element. ## Value diff --git a/files/en-us/web/api/element/ariahidden/index.md b/files/en-us/web/api/element/ariahidden/index.md index a4addd53aa49c68..ee29a900d3734fc 100644 --- a/files/en-us/web/api/element/ariahidden/index.md +++ b/files/en-us/web/api/element/ariahidden/index.md @@ -8,7 +8,7 @@ browser-compat: api.Element.ariaHidden {{APIRef("DOM")}} -The **`ariaHidden`** property of the {{domxref("Element")}} interface reflects the value of the [`aria-hidden`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-hidden)) attribute, which indicates whether the element is exposed to an accessibility API. +The **`ariaHidden`** property of the {{domxref("Element")}} interface reflects the value of the [`aria-hidden`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-hidden)) attribute, which indicates whether the element is exposed to an accessibility API. ## Value @@ -23,7 +23,7 @@ A string with one of the following values: ## Examples -In this example the [`aria-hidden`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-hidden) attribute on the element with an ID of `hidden` is set to "true". Using `ariaHidden` we update the value to "false". +In this example the [`aria-hidden`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-hidden) attribute on the element with an ID of `hidden` is set to "true". Using `ariaHidden` we update the value to "false". ```html <div id="hidden" aria-hidden="true">Some things are better left unsaid.</div> diff --git a/files/en-us/web/api/element/ariainvalid/index.md b/files/en-us/web/api/element/ariainvalid/index.md new file mode 100644 index 000000000000000..65f4164b8e177d2 --- /dev/null +++ b/files/en-us/web/api/element/ariainvalid/index.md @@ -0,0 +1,71 @@ +--- +title: "Element: ariaInvalid property" +short-title: ariaInvalid +slug: Web/API/Element/ariaInvalid +page-type: web-api-instance-property +browser-compat: api.Element.ariaInvalid +--- + +{{APIRef("DOM")}} + +The **`ariaInvalid`** property of the {{domxref("Element")}} interface reflects the value of the [`aria-invalid`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-invalid) attribute. Relevant for the [`application`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/application_role), [`checkbox`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/checkbox_role), [`combobox`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/combobox_role), [`gridcell`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/gridcell_role), [`listbox`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/listbox_role), [`radiogroup`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/radiogroup_role), [`slider`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/slider_role), [`spinbutton`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/spinbutton_role), [`textbox`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/textbox_role), and [`tree`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/tree_role) roles, it indicates to the accessibility API whether the entered value does not conform to the format expected by the application. + +If the attribute is not present, or is set to the empty string, assistive technology will treat the value as if it were set to `false`. If the attribute is present but set to a value other than `false`, `grammar`, `spelling` or the empty string (`""`), assistive technology treats the value as `true`. The property reflects the attribute value as set, not as handled by assistive technology. + +## Value + +A string with one of the following values: + +- `"true"` + - : The element is invalid. +- `"false"` (default) + - : The element is not in an invalid state. +- `"grammar"` + - : The element is in an invalid state because grammatical error was detected. +- `"spelling"` + - : The element is in an invalid state because spelling error was detected. + +## Examples + +In this example the [`aria-invalid`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-invalid) attribute on the element with an ID of `quote` is omitted, returning `null` and treated as `false`. Using `ariaInvalid` we update the value to `grammar` (because there are two errors). + +```html +<div id="quote" role="textbox" contenteditable>you are your best thing..</div> +``` + +```html hidden +<hr /> +<pre id="log"></pre> +``` + +```js hidden +const logElement = document.querySelector("#log"); +function log(text) { + logElement.innerText = `${logElement.innerText}${text}\n`; + logElement.scrollTop = logElement.scrollHeight; +} +``` + +```js +const el = document.getElementById("quote"); +log(`Initial value: ${el.ariaInvalid}`); +el.ariaInvalid = "grammar"; +log(`Updated value: ${el.ariaInvalid}`); +``` + +{{EmbedLiveSample("Examples", "", "100")}} + +## Specifications + +{{Specifications}} + +## Browser compatibility + +{{Compat}} + +## See also + +- {{domxref("Element.ariaRequired")}} +- [`aria-required`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-required) +- [`aria-errormessage`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-errormessage) +- {{domxref("Element.ariaErrorMessageElements")}} diff --git a/files/en-us/web/api/element/arialabel/index.md b/files/en-us/web/api/element/arialabel/index.md index 76d267f7c3a6325..da522bab1d2ee2f 100644 --- a/files/en-us/web/api/element/arialabel/index.md +++ b/files/en-us/web/api/element/arialabel/index.md @@ -8,7 +8,7 @@ browser-compat: api.Element.ariaLabel {{APIRef("DOM")}} -The **`ariaLabel`** property of the {{domxref("Element")}} interface reflects the value of the [`aria-label`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-label) attribute, which defines a string value that labels the current element. +The **`ariaLabel`** property of the {{domxref("Element")}} interface reflects the value of the [`aria-label`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-label) attribute, which defines a string value that labels the current element. ## Value @@ -16,7 +16,7 @@ A string or `null`. ## Examples -In this example the [`aria-label`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-label) attribute on the element with an ID of `close-button` is set to "Close". Using `ariaLabel` we update the value to "Close dialog". +In this example the [`aria-label`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-label) attribute on the element with an ID of `close-button` is set to "Close". Using `ariaLabel` we update the value to "Close dialog". ```html <button aria-label="Close" id="close-button">X</button> diff --git a/files/en-us/web/api/element/arialabelledbyelements/index.md b/files/en-us/web/api/element/arialabelledbyelements/index.md new file mode 100644 index 000000000000000..130b317f40a93f2 --- /dev/null +++ b/files/en-us/web/api/element/arialabelledbyelements/index.md @@ -0,0 +1,116 @@ +--- +title: "Element: ariaLabelledByElements property" +short-title: ariaLabelledByElements +slug: Web/API/Element/ariaLabelledByElements +page-type: web-api-instance-property +browser-compat: api.Element.ariaLabelledByElements +--- + +{{APIRef("DOM")}} + +The **`ariaLabelledByElements`** property of the {{domxref("Element")}} interface is an array containing the element (or elements) that provide an accessible name for the element it is applied to. + +The property is primarily intended to provide a label for elements that don't have a standard method for defining their accessible name. +For example, this might be used to name a generic container element, such as a {{htmlelement("div")}} or {{htmlelement("span")}}, or a grouping of elements, such as an image with a slider that can be used to change its opacity. +The property takes precedence over other mechanisms for providing an accessible name for elements, and may therefore also be used to provide a name for elements that would normally get it from their inner content or from an associated element such as a label. + +The [`aria-labelledby`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-labelledby) topic contains additional information about how the attribute and property should be used. + +## Value + +An array of elements. +The inner text of these elements can be joined with spaces to get the accessible name. + +When read, the returned array is a static and read-only. +When written, the assigned array is copied: subsequent changes to the array do not affect the value of the property. + +## Description + +The property is a flexible alternative to using the [`aria-labelledby`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-labelledby) attribute to set the accessible name. +Unlike `aria-labelledby`, the elements assigned to this property do not have to have an [`id`](/en-US/docs/Web/HTML/Reference/Global_attributes/id) attribute. + +The property reflects the element's [`aria-labelledby`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-labelledby) attribute when it is defined, but only for listed reference `id` values that match valid in-scope elements. +If the property is set, then the corresponding attribute is cleared. +For more information about reflected element references and scope see [Reflected element references](/en-US/docs/Web/API/Document_Object_Model/Reflected_attributes#reflected_element_references) in the _Reflected attributes_ guide. + +## Examples + +### Get the accessible name + +This example shows how `ariaLabelledByElements` can be used to get an ARIA label defined using `aria-labelledby`. + +#### HTML + +The HTML defines two {{htmlelement("span")}} elements and references their ids in the `aria-labelledby` attribute of an {{htmlelement("input")}}. +The accessible name of the `<input>` is the concatenation of the inner text of the two referenced elements, separated by a space. + +```html +<span id="label_1">Street name</span> +<input aria-labelledby="label_1 label_2" /> +<span id="label_2">(just the name, no "Street" or "Road" or "Place")</span> +``` + +```html hidden +<pre id="log"></pre> +``` + +```css hidden +#log { + height: 70px; + overflow: scroll; + padding: 0.5rem; + border: 1px solid black; +} +``` + +#### JavaScript + +The code below first logs the value of the `aria-labelledby` attribute from {{domxref("Element.getAttribute()")}} (a string listing the `id` values of the referenced elements). +It then checks whether the `ariaLabelledByElements` is supported, and if so, logs its value. +Finally it returns the accessible string, calculated by iterating through the elements and concatenating their inner text. + +```js hidden +const logElement = document.querySelector("#log"); +function log(text) { + logElement.innerText = `${logElement.innerText}${text}\n`; + logElement.scrollTop = logElement.scrollHeight; +} +``` + +```js +const inputElement = document.querySelector("input"); +log(`aria-labelledby: ${inputElement.getAttribute("aria-labelledby")}`); +// Feature test for ariaLabelledByElements +if ("ariaLabelledByElements" in Element.prototype) { + // Get ariaLabelledByElements + const labelElements = inputElement.ariaLabelledByElements; + log(`ariaLabelledByElements: ${labelElements}`); + + // Log inner text of elements to get accessible name + const text = labelElements.map((e) => e.textContent.trim()).join(" "); + log(`Accessible name: ${text.trim()}`); +} else { + log("element.ariaLabelledByElements: not supported by browser"); +} +``` + +#### Result + +The log below shows the original element references, the associated/returned elements, and the accessible name. +Note that the example doesn't do anything with text entered into the street name `<input>`. + +{{EmbedLiveSample("Get the accessible name","100%","150px")}} + +## Specifications + +{{Specifications}} + +## Browser compatibility + +{{Compat}} + +## See also + +- [`aria-labelledby`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-labelledby) attribute +- {{domxref("ElementInternals.ariaLabelledByElements")}} +- [Reflected element references](/en-US/docs/Web/API/Document_Object_Model/Reflected_attributes#reflected_element_references) in the _Attribute reflection_ guide. diff --git a/files/en-us/web/api/element/arialevel/index.md b/files/en-us/web/api/element/arialevel/index.md index fc41732e1af5c7d..93a54d19e598e32 100644 --- a/files/en-us/web/api/element/arialevel/index.md +++ b/files/en-us/web/api/element/arialevel/index.md @@ -44,4 +44,4 @@ console.log(el.ariaLevel); // "2" ## See also -- [ARIA: heading role](/en-US/docs/Web/Accessibility/ARIA/Roles/heading_role) +- [ARIA: heading role](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/heading_role) diff --git a/files/en-us/web/api/element/arialive/index.md b/files/en-us/web/api/element/arialive/index.md index 3e063dbdf373edc..1add74c6fd977bf 100644 --- a/files/en-us/web/api/element/arialive/index.md +++ b/files/en-us/web/api/element/arialive/index.md @@ -8,7 +8,7 @@ browser-compat: api.Element.ariaLive {{APIRef("DOM")}} -The **`ariaLive`** property of the {{domxref("Element")}} interface reflects the value of the [`aria-live`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-live) attribute, which indicates that an element will be updated, and describes the types of updates the user agents, assistive technologies, and user can expect from the [live region](/en-US/docs/Web/Accessibility/ARIA/ARIA_Live_Regions). +The **`ariaLive`** property of the {{domxref("Element")}} interface reflects the value of the [`aria-live`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-live) attribute, which indicates that an element will be updated, and describes the types of updates the user agents, assistive technologies, and user can expect from the [live region](/en-US/docs/Web/Accessibility/ARIA/Guides/Live_regions). ## Value @@ -23,7 +23,7 @@ A string with one of the following values: ## Examples -In this example the [`aria-live`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-live) attribute on the element with an ID of `planetInfo` is set to `"polite"`. We then update the value to `"assertive"`. +In this example the [`aria-live`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-live) attribute on the element with an ID of `planetInfo` is set to `"polite"`. We then update the value to `"assertive"`. ```html <div role="region" id="planetInfo" aria-live="polite"> diff --git a/files/en-us/web/api/element/ariamodal/index.md b/files/en-us/web/api/element/ariamodal/index.md index daa03746e0f27e5..d8d084e0ae3bd69 100644 --- a/files/en-us/web/api/element/ariamodal/index.md +++ b/files/en-us/web/api/element/ariamodal/index.md @@ -49,4 +49,4 @@ console.log(el.ariaModal); // "false" ## See also -- [ARIA: dialog role](/en-US/docs/Web/Accessibility/ARIA/Roles/dialog_role) +- [ARIA: dialog role](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/dialog_role) diff --git a/files/en-us/web/api/element/ariamultiline/index.md b/files/en-us/web/api/element/ariamultiline/index.md index 2957923813cb50a..b984018269919ee 100644 --- a/files/en-us/web/api/element/ariamultiline/index.md +++ b/files/en-us/web/api/element/ariamultiline/index.md @@ -8,7 +8,7 @@ browser-compat: api.Element.ariaMultiLine {{APIRef("DOM")}} -The **`ariaMultiLine`** property of the {{domxref("Element")}} interface reflects the value of the [`aria-multiline`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-multiline) attribute, which indicates whether a text box accepts multiple lines of input or only a single line. +The **`ariaMultiLine`** property of the {{domxref("Element")}} interface reflects the value of the [`aria-multiline`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-multiline) attribute, which indicates whether a text box accepts multiple lines of input or only a single line. > [!NOTE] > Where possible use an HTML {{htmlelement("input")}} element with `type="text"` or a {{htmlelement("textarea")}} as these have built in semantics and do not require ARIA attributes. @@ -54,4 +54,4 @@ console.log(el.ariaMultiLine); // "false" ## See also -- [ARIA: textbox role](/en-US/docs/Web/Accessibility/ARIA/Roles/textbox_role) +- [ARIA: textbox role](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/textbox_role) diff --git a/files/en-us/web/api/element/ariamultiselectable/index.md b/files/en-us/web/api/element/ariamultiselectable/index.md index ade451bff3c028a..02a78b5dea5d6b2 100644 --- a/files/en-us/web/api/element/ariamultiselectable/index.md +++ b/files/en-us/web/api/element/ariamultiselectable/index.md @@ -8,7 +8,7 @@ browser-compat: api.Element.ariaMultiSelectable {{APIRef("DOM")}} -The **`ariaMultiSelectable`** property of the {{domxref("Element")}} interface reflects the value of the [`aria-multiselectable`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-multiselectable) attribute, which indicates that the user may select more than one item from the current selectable descendants. +The **`ariaMultiSelectable`** property of the {{domxref("Element")}} interface reflects the value of the [`aria-multiselectable`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-multiselectable) attribute, which indicates that the user may select more than one item from the current selectable descendants. > [!NOTE] > Where possible use an HTML {{htmlelement("select")}} element as this has built in semantics and does not require ARIA attributes. @@ -59,4 +59,4 @@ console.log(el.ariaMultiSelectable); // "false" ## See also -- [ARIA: listbox role](/en-US/docs/Web/Accessibility/ARIA/Roles/listbox_role) +- [ARIA: listbox role](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/listbox_role) diff --git a/files/en-us/web/api/element/ariaorientation/index.md b/files/en-us/web/api/element/ariaorientation/index.md index f9a672c193be93b..bf4e03821e5fd02 100644 --- a/files/en-us/web/api/element/ariaorientation/index.md +++ b/files/en-us/web/api/element/ariaorientation/index.md @@ -8,7 +8,7 @@ browser-compat: api.Element.ariaOrientation {{APIRef("DOM")}} -The **`ariaOrientation`** property of the {{domxref("Element")}} interface reflects the value of the [`aria-orientation`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-orientation) attribute, which indicates whether the element's orientation is horizontal, vertical, or unknown/ambiguous. +The **`ariaOrientation`** property of the {{domxref("Element")}} interface reflects the value of the [`aria-orientation`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-orientation) attribute, which indicates whether the element's orientation is horizontal, vertical, or unknown/ambiguous. ## Value @@ -23,7 +23,7 @@ A string with one of the following values: ## Examples -In this example the [`aria-orientation`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-orientation) attribute on the element with an ID of `handle_zoomSlider` is set to `"vertical"`. Using `ariaOrientation` we update the value to `"horizontal"`. +In this example the [`aria-orientation`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-orientation) attribute on the element with an ID of `handle_zoomSlider` is set to `"vertical"`. Using `ariaOrientation` we update the value to `"horizontal"`. ```html <div diff --git a/files/en-us/web/api/element/ariaownselements/index.md b/files/en-us/web/api/element/ariaownselements/index.md new file mode 100644 index 000000000000000..97590124eac7b66 --- /dev/null +++ b/files/en-us/web/api/element/ariaownselements/index.md @@ -0,0 +1,163 @@ +--- +title: "Element: ariaOwnsElements property" +short-title: ariaOwnsElements +slug: Web/API/Element/ariaOwnsElements +page-type: web-api-instance-property +browser-compat: api.Element.ariaOwnsElements +--- + +{{APIRef("DOM")}} + +The **`ariaOwnsElements`** property of the {{domxref("Element")}} interface is an array containing the element (or elements) that define a visual, functional, or contextual relationship between a parent element that it is applied to, and its child elements. +This is used when the DOM hierarchy cannot be used to represent the relationship, and it would not otherwise be available to assistive technology, + +The [`aria-owns`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-owns) topic contains additional information about how the attribute and property should be used. + +## Value + +An array of subclasses of {{domxref("HTMLElement")}}. + +When read, the returned array is a static and read-only. +When written, the assigned array is copied: subsequent changes to the array do not affect the value of the property. + +## Description + +The property is a flexible alternative to using the [`aria-owns`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-owns) attribute to indicate ownership of an element. +Unlike `aria-owns`, the elements assigned to this property do not have to have an [`id`](/en-US/docs/Web/HTML/Reference/Global_attributes/id) attribute. + +The property reflects the element's [`aria-owns`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-owns) attribute when it is defined, but only for listed reference `id` values that match valid in-scope elements. +If the property is set, then the corresponding attribute is cleared. +For more information about reflected element references and scope see [Reflected element references](/en-US/docs/Web/API/Document_Object_Model/Reflected_attributes#reflected_element_references) in the _Reflected attributes_ guide. + +## Examples + +### Get the owned element + +This example demonstrates how the `aria-owns` attribute and property are used. + +The code defines a menu and its associated submenu in separate and non-nested {{htmlelement("div")}} elements. +Because these elements are not nested the ownership relationship between the menu and submenu is not captured by the DOM. +Here we provide that information to accessibility tools using the `aria-owns` attribute, but we could also do it using the reflected property. + +Note that we could construct a menu where the submenu was nested: the example has been _contrived_ to make it easier to demonstrate a case where the relationship needs to be defined. + +#### HTML + +The HTML defines {{htmlelement("div")}} elements for the menu, with `id=parentMenu` and the submenu with `id="subMenu1"`. +We've added a `<div>` in between just to make it even more obvious that there is no direct ownership model defined in the DOM. + +The parent menu `<div>` includes the attribute `aria-owns="subMenu1"` to create this ownership relationship. + +```html +<div class="menu" id="parentMenu" role="menubar" aria-owns="subMenu1"> + Top level menu (hover over) +</div> + +<div>Some other element</div> + +<div class="submenu" id="subMenu1" role="menu"> + <a href="#" role="menuitem">Menu item 1</a> + <a href="#" role="menuitem">Menu item 2</a> + <a href="#" role="menuitem">Menu item 3</a> +</div> +``` + +#### CSS + +The CSS styles the menu and submenu, and displays the submenu when the menu is hovered over. + +```css +.menu { + position: relative; + display: inline-block; + color: purple; +} + +.submenu { + display: none; + position: absolute; + background-color: #f9f9f9; + min-width: 160px; + box-shadow: 0px 6px 14px 0px rgba(0, 0, 0, 0.2); + z-index: 1; + top: 20px; + left: 0; +} + +.menu:hover ~ .submenu { + display: block; +} + +.submenu a { + color: black; + padding: 12px 16px; + text-decoration: none; + display: block; +} + +.submenu a:hover { + background-color: #f1f1f1; +} +``` + +```html hidden +<pre id="log"></pre> +``` + +```css hidden +#log { + height: 80px; + overflow: scroll; + padding: 0.5rem; + margin: 5px; + border: 1px solid black; +} +``` + +#### JavaScript + +The code first checks whether the `ariaOwnsElements` is supported. +If it is, we log the attribute, the elements in the property, and the `id` value for each element. + +```js hidden +const logElement = document.querySelector("#log"); +function log(text) { + logElement.innerText = `${logElement.innerText}${text}\n`; + logElement.scrollTop = logElement.scrollHeight; +} +``` + +```js +// Feature test for ariaOwnsElements +if ("ariaOwnsElements" in Element.prototype) { + const parentMenu = document.querySelector("#parentMenu"); + log(`parentMenu.getAttribute(): ${parentMenu.getAttribute("aria-owns")}`); + log(`parentMenu.ariaOwnsElements: ${parentMenu.ariaOwnsElements}`); + parentMenu.ariaOwnsElements?.forEach((elem) => { + log(` id: ${elem.id}`); + }); +} else { + log("element.ariaOwnsElements: not supported by browser"); +} +``` + +#### Result + +The result of running the code is shown below. +The log shows that the relationship defined using the `aria-owns` attribute is reflected in the `ariaOwnsElements` property (elements in the array match the attribute element references). + +{{EmbedLiveSample("Get the flow-to element","100%","200px")}} + +## Specifications + +{{Specifications}} + +## Browser compatibility + +{{Compat}} + +## See also + +- [`aria-owns`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-flowto) attribute +- {{domxref("ElementInternals.ariaOwnsElements")}} +- [Reflected element references](/en-US/docs/Web/API/Document_Object_Model/Reflected_attributes#reflected_element_references) in the _Attribute reflection_ guide. diff --git a/files/en-us/web/api/element/ariaplaceholder/index.md b/files/en-us/web/api/element/ariaplaceholder/index.md index c6b26e6d3e55608..0de806be6c44d93 100644 --- a/files/en-us/web/api/element/ariaplaceholder/index.md +++ b/files/en-us/web/api/element/ariaplaceholder/index.md @@ -48,4 +48,4 @@ console.log(el.ariaPlaceholder); // "12345" ## See also -- [ARIA: textbox role](/en-US/docs/Web/Accessibility/ARIA/Roles/textbox_role) +- [ARIA: textbox role](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/textbox_role) diff --git a/files/en-us/web/api/element/ariaposinset/index.md b/files/en-us/web/api/element/ariaposinset/index.md index 86d9112006a794f..144509bdb3bf9d0 100644 --- a/files/en-us/web/api/element/ariaposinset/index.md +++ b/files/en-us/web/api/element/ariaposinset/index.md @@ -8,7 +8,7 @@ browser-compat: api.Element.ariaPosInSet {{APIRef("DOM")}} -The **`ariaPosInSet`** property of the {{domxref("Element")}} interface reflects the value of the [`aria-posinset`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-posinset) attribute, which defines an element's number or position in the current set of listitems or treeitems. +The **`ariaPosInSet`** property of the {{domxref("Element")}} interface reflects the value of the [`aria-posinset`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-posinset) attribute, which defines an element's number or position in the current set of listitems or treeitems. ## Value diff --git a/files/en-us/web/api/element/ariapressed/index.md b/files/en-us/web/api/element/ariapressed/index.md index c13bc3e6d08dfad..c6e24943710decf 100644 --- a/files/en-us/web/api/element/ariapressed/index.md +++ b/files/en-us/web/api/element/ariapressed/index.md @@ -8,7 +8,7 @@ browser-compat: api.Element.ariaPressed {{APIRef("DOM")}} -The **`ariaPressed`** property of the {{domxref("Element")}} interface reflects the value of the [`aria-pressed`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-pressed) attribute, which indicates the current "pressed" state of toggle buttons. +The **`ariaPressed`** property of the {{domxref("Element")}} interface reflects the value of the [`aria-pressed`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-pressed) attribute, which indicates the current "pressed" state of toggle buttons. > [!NOTE] > Where possible use an HTML {{htmlelement("input")}} element with `type="button"` or the {{htmlelement("button")}} element as these have built in semantics and do not require ARIA attributes. @@ -51,4 +51,4 @@ console.log(el.ariaPressed); // "true" ## See also -- [ARIA: button role](/en-US/docs/Web/Accessibility/ARIA/Roles/button_role) +- [ARIA: button role](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/button_role) diff --git a/files/en-us/web/api/element/ariareadonly/index.md b/files/en-us/web/api/element/ariareadonly/index.md index 11509d412007845..3903da0c341743d 100644 --- a/files/en-us/web/api/element/ariareadonly/index.md +++ b/files/en-us/web/api/element/ariareadonly/index.md @@ -8,7 +8,7 @@ browser-compat: api.Element.ariaReadOnly {{APIRef("DOM")}} -The **`ariaReadOnly`** property of the {{domxref("Element")}} interface reflects the value of the [`aria-readonly`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-readonly) attribute, which indicates that the element is not editable, but is otherwise operable. +The **`ariaReadOnly`** property of the {{domxref("Element")}} interface reflects the value of the [`aria-readonly`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-readonly) attribute, which indicates that the element is not editable, but is otherwise operable. > [!NOTE] > Where possible use an HTML {{htmlelement("input")}} element with `type="text"` or a {{htmlelement("textarea")}} as these have built in semantics and do not require ARIA attributes. @@ -54,4 +54,4 @@ console.log(el.ariaReadOnly); // "false" ## See also -- [ARIA: textbox role](/en-US/docs/Web/Accessibility/ARIA/Roles/textbox_role) +- [ARIA: textbox role](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/textbox_role) diff --git a/files/en-us/web/api/element/ariarelevant/index.md b/files/en-us/web/api/element/ariarelevant/index.md index 00370da88e3b167..4007425241af646 100644 --- a/files/en-us/web/api/element/ariarelevant/index.md +++ b/files/en-us/web/api/element/ariarelevant/index.md @@ -10,7 +10,7 @@ browser-compat: api.Element.ariaRelevant {{APIRef("DOM")}}{{Non-standard_Header}} -The **`ariaRelevant`** property of the {{domxref("Element")}} interface reflects the value of the [`aria-relevant`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-relevant) attribute, which indicates what notifications the user agent will trigger when the accessibility tree within a live region is modified. This is used to describe what changes in an `aria-live` region are relevant and should be announced. +The **`ariaRelevant`** property of the {{domxref("Element")}} interface reflects the value of the [`aria-relevant`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-relevant) attribute, which indicates what notifications the user agent will trigger when the accessibility tree within a live region is modified. This is used to describe what changes in an `aria-live` region are relevant and should be announced. ## Value @@ -27,7 +27,7 @@ A string containing one or more of the following values, space separated: ## Examples -In this example the [`aria-relevant`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-relevant) attribute on the element with an ID of `text` is set to "all". Using `ariaRelevant` we update the value to "text". +In this example the [`aria-relevant`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-relevant) attribute on the element with an ID of `text` is set to "all". Using `ariaRelevant` we update the value to "text". ```html <div diff --git a/files/en-us/web/api/element/ariarequired/index.md b/files/en-us/web/api/element/ariarequired/index.md index 1180c1bef3cae51..9e914734588362b 100644 --- a/files/en-us/web/api/element/ariarequired/index.md +++ b/files/en-us/web/api/element/ariarequired/index.md @@ -54,4 +54,4 @@ console.log(el.ariaRequired); // "false" ## See also -- [ARIA: textbox role](/en-US/docs/Web/Accessibility/ARIA/Roles/textbox_role) +- [ARIA: textbox role](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/textbox_role) diff --git a/files/en-us/web/api/element/ariaroledescription/index.md b/files/en-us/web/api/element/ariaroledescription/index.md index 83d725d6a3d7bc2..fd60152d2649de9 100644 --- a/files/en-us/web/api/element/ariaroledescription/index.md +++ b/files/en-us/web/api/element/ariaroledescription/index.md @@ -8,7 +8,7 @@ browser-compat: api.Element.ariaRoleDescription {{APIRef("DOM")}} -The **`ariaRoleDescription`** property of the {{domxref("Element")}} interface reflects the value of the [`aria-roledescription`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-roledescription) attribute, which defines a human-readable, author-localized description for the role of an element. +The **`ariaRoleDescription`** property of the {{domxref("Element")}} interface reflects the value of the [`aria-roledescription`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-roledescription) attribute, which defines a human-readable, author-localized description for the role of an element. ## Value @@ -44,4 +44,4 @@ console.log(el.ariaRoleDescription); // "an updated description of this widget" ## See also -- [ARIA: application role](/en-US/docs/Web/Accessibility/ARIA/Roles/application_role) +- [ARIA: application role](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/application_role) diff --git a/files/en-us/web/api/element/ariarowcount/index.md b/files/en-us/web/api/element/ariarowcount/index.md index 7acfe7840559e49..ba1f3c64bcbf373 100644 --- a/files/en-us/web/api/element/ariarowcount/index.md +++ b/files/en-us/web/api/element/ariarowcount/index.md @@ -8,7 +8,7 @@ browser-compat: api.Element.ariaRowCount {{APIRef("DOM")}} -The **`ariaRowCount`** property of the {{domxref("Element")}} interface reflects the value of the [`aria-rowcount`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-rowcount) attribute, which defines the total number of rows in a table, grid, or treegrid. +The **`ariaRowCount`** property of the {{domxref("Element")}} interface reflects the value of the [`aria-rowcount`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-rowcount) attribute, which defines the total number of rows in a table, grid, or treegrid. ## Value @@ -74,4 +74,4 @@ console.log(el.ariaRowCount); // 101 ## See also -- [ARIA: table role](/en-US/docs/Web/Accessibility/ARIA/Roles/table_role) +- [ARIA: table role](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/table_role) diff --git a/files/en-us/web/api/element/ariarowindex/index.md b/files/en-us/web/api/element/ariarowindex/index.md index f9edcd21171a23d..e1b66a2ecd8ace1 100644 --- a/files/en-us/web/api/element/ariarowindex/index.md +++ b/files/en-us/web/api/element/ariarowindex/index.md @@ -8,7 +8,7 @@ browser-compat: api.Element.ariaRowIndex {{APIRef("DOM")}} -The **`ariaRowIndex`** property of the {{domxref("Element")}} interface reflects the value of the [`aria-rowindex`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-rowindex) attribute, which defines an element's row index or position with respect to the total number of rows within a table, grid, or treegrid. +The **`ariaRowIndex`** property of the {{domxref("Element")}} interface reflects the value of the [`aria-rowindex`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-rowindex) attribute, which defines an element's row index or position with respect to the total number of rows within a table, grid, or treegrid. ## Value @@ -84,4 +84,4 @@ console.log(el.ariaRowIndex); // 2 ## See also -- [ARIA: table role](/en-US/docs/Web/Accessibility/ARIA/Roles/table_role) +- [ARIA: table role](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/table_role) diff --git a/files/en-us/web/api/element/ariarowindextext/index.md b/files/en-us/web/api/element/ariarowindextext/index.md index e87e718ecaf3bad..d516d9b311fecf3 100644 --- a/files/en-us/web/api/element/ariarowindextext/index.md +++ b/files/en-us/web/api/element/ariarowindextext/index.md @@ -7,7 +7,7 @@ browser-compat: api.Element.ariaRowIndexText {{APIRef("DOM")}} -The **`ariaRowIndexText`** property of the {{domxref("Element")}} interface reflects the value of the [`aria-rowindextext`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-rowindextext) attribute, which defines a human readable text alternative of aria-rowindex. +The **`ariaRowIndexText`** property of the {{domxref("Element")}} interface reflects the value of the [`aria-rowindextext`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-rowindextext) attribute, which defines a human readable text alternative of aria-rowindex. ## Value @@ -84,4 +84,4 @@ console.log(el.ariaRowIndexText); // "Updated heading row" ## See also -- [ARIA: table role](/en-US/docs/Web/Accessibility/ARIA/Roles/table_role) +- [ARIA: table role](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/table_role) diff --git a/files/en-us/web/api/element/ariarowspan/index.md b/files/en-us/web/api/element/ariarowspan/index.md index 4269927e0c8b1f8..3947461fe9b0320 100644 --- a/files/en-us/web/api/element/ariarowspan/index.md +++ b/files/en-us/web/api/element/ariarowspan/index.md @@ -8,7 +8,7 @@ browser-compat: api.Element.ariaRowSpan {{APIRef("DOM")}} -The **`ariaRowSpan`** property of the {{domxref("Element")}} interface reflects the value of the [`aria-rowspan`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-rowspan) attribute, which defines the number of rows spanned by a cell or gridcell within a table, grid, or treegrid. +The **`ariaRowSpan`** property of the {{domxref("Element")}} interface reflects the value of the [`aria-rowspan`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-rowspan) attribute, which defines the number of rows spanned by a cell or gridcell within a table, grid, or treegrid. ## Value @@ -50,4 +50,4 @@ console.log(el.ariaRowSpan); ## See also -- [ARIA: table role](/en-US/docs/Web/Accessibility/ARIA/Roles/table_role) +- [ARIA: table role](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/table_role) diff --git a/files/en-us/web/api/element/ariaselected/index.md b/files/en-us/web/api/element/ariaselected/index.md index 545a447140b016b..da78c83d45f73bf 100644 --- a/files/en-us/web/api/element/ariaselected/index.md +++ b/files/en-us/web/api/element/ariaselected/index.md @@ -8,7 +8,7 @@ browser-compat: api.Element.ariaSelected {{APIRef("DOM")}} -The **`ariaSelected`** property of the {{domxref("Element")}} interface reflects the value of the [`aria-selected`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-selected) attribute, which indicates the current "selected" state of elements that have a selected state. +The **`ariaSelected`** property of the {{domxref("Element")}} interface reflects the value of the [`aria-selected`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-selected) attribute, which indicates the current "selected" state of elements that have a selected state. ## Value @@ -48,4 +48,4 @@ console.log(el.ariaSelected); // false ## See also -- [ARIA: tab role](/en-US/docs/Web/Accessibility/ARIA/Roles/tab_role) +- [ARIA: tab role](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/tab_role) diff --git a/files/en-us/web/api/element/ariasetsize/index.md b/files/en-us/web/api/element/ariasetsize/index.md index f8c25efe6ec5d41..82e11632a2fa8ba 100644 --- a/files/en-us/web/api/element/ariasetsize/index.md +++ b/files/en-us/web/api/element/ariasetsize/index.md @@ -8,7 +8,7 @@ browser-compat: api.Element.ariaSetSize {{APIRef("DOM")}} -The **`ariaSetSize`** property of the {{domxref("Element")}} interface reflects the value of the [`aria-setsize`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-setsize) attribute, which defines the number of items in the current set of listitems or treeitems. +The **`ariaSetSize`** property of the {{domxref("Element")}} interface reflects the value of the [`aria-setsize`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-setsize) attribute, which defines the number of items in the current set of listitems or treeitems. ## Value @@ -46,4 +46,4 @@ console.log(el.ariaSetSize); // 4 ## See also -- [ARIA: tab role](/en-US/docs/Web/Accessibility/ARIA/Roles/tab_role) +- [ARIA: tab role](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/tab_role) diff --git a/files/en-us/web/api/element/ariasort/index.md b/files/en-us/web/api/element/ariasort/index.md index a1e2418a669e344..25b35321f54c279 100644 --- a/files/en-us/web/api/element/ariasort/index.md +++ b/files/en-us/web/api/element/ariasort/index.md @@ -8,7 +8,7 @@ browser-compat: api.Element.ariaSort {{APIRef("DOM")}} -The **`ariaSort`** property of the {{domxref("Element")}} interface reflects the value of the [`aria-sort`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-sort) attribute, which indicates if items in a table or grid are sorted in ascending or descending order. +The **`ariaSort`** property of the {{domxref("Element")}} interface reflects the value of the [`aria-sort`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-sort) attribute, which indicates if items in a table or grid are sorted in ascending or descending order. ## Value @@ -94,4 +94,4 @@ console.log(el.ariaSort); // ascending ## See also -- [ARIA: table role](/en-US/docs/Web/Accessibility/ARIA/Roles/table_role) +- [ARIA: table role](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/table_role) diff --git a/files/en-us/web/api/element/ariavaluemax/index.md b/files/en-us/web/api/element/ariavaluemax/index.md index 7d1b1f1da37070c..f66b49dfc70ab25 100644 --- a/files/en-us/web/api/element/ariavaluemax/index.md +++ b/files/en-us/web/api/element/ariavaluemax/index.md @@ -8,7 +8,7 @@ browser-compat: api.Element.ariaValueMax {{APIRef("DOM")}} -The **`ariaValueMax`** property of the {{domxref("Element")}} interface reflects the value of the [`aria-valuemax`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-valuemax) attribute, which defines the maximum allowed value for a range widget. +The **`ariaValueMax`** property of the {{domxref("Element")}} interface reflects the value of the [`aria-valuemax`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-valuemax) attribute, which defines the maximum allowed value for a range widget. ## Value @@ -16,7 +16,7 @@ A string which contains a number. ## Examples -In this example the [`aria-valuemax`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-valuemax) attribute on the element with an ID of `slider` is set to "7". Using `ariaValueMax` we update the value to "6". +In this example the [`aria-valuemax`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-valuemax) attribute on the element with an ID of `slider` is set to "7". Using `ariaValueMax` we update the value to "6". ```html <div diff --git a/files/en-us/web/api/element/ariavaluemin/index.md b/files/en-us/web/api/element/ariavaluemin/index.md index d74a4a29496c3a5..37ea97cad7463ed 100644 --- a/files/en-us/web/api/element/ariavaluemin/index.md +++ b/files/en-us/web/api/element/ariavaluemin/index.md @@ -8,7 +8,7 @@ browser-compat: api.Element.ariaValueMin {{APIRef("DOM")}} -The **`ariaValueMin`** property of the {{domxref("Element")}} interface reflects the value of the [`aria-valuemin`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-valuemin) attribute, which defines the minimum allowed value for a range widget. +The **`ariaValueMin`** property of the {{domxref("Element")}} interface reflects the value of the [`aria-valuemin`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-valuemin) attribute, which defines the minimum allowed value for a range widget. ## Value diff --git a/files/en-us/web/api/element/ariavaluenow/index.md b/files/en-us/web/api/element/ariavaluenow/index.md index e2e239cc36857ca..7bdf0b5a5f13134 100644 --- a/files/en-us/web/api/element/ariavaluenow/index.md +++ b/files/en-us/web/api/element/ariavaluenow/index.md @@ -8,7 +8,7 @@ browser-compat: api.Element.ariaValueNow {{APIRef("DOM")}} -The **`ariaValueNow`** property of the {{domxref("Element")}} interface reflects the value of the [`aria-valuenow`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-valuenow) attribute, which defines the current value for a range widget. +The **`ariaValueNow`** property of the {{domxref("Element")}} interface reflects the value of the [`aria-valuenow`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-valuenow) attribute, which defines the current value for a range widget. ## Value @@ -16,7 +16,7 @@ A string which contains a number. ## Examples -In this example the [`aria-valuenow`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-valuenow) attribute on the element with an ID of `slider` is set to "1". Using `ariaValueNow` we update the value to "2". +In this example the [`aria-valuenow`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-valuenow) attribute on the element with an ID of `slider` is set to "1". Using `ariaValueNow` we update the value to "2". ```html <div diff --git a/files/en-us/web/api/element/ariavaluetext/index.md b/files/en-us/web/api/element/ariavaluetext/index.md index e2e66075595c87c..664bac34fcb7de9 100644 --- a/files/en-us/web/api/element/ariavaluetext/index.md +++ b/files/en-us/web/api/element/ariavaluetext/index.md @@ -8,7 +8,7 @@ browser-compat: api.Element.ariaValueText {{APIRef("DOM")}} -The **`ariaValueText`** property of the {{domxref("Element")}} interface reflects the value of the [`aria-valuetext`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-valuetext) attribute, which defines the human-readable text alternative of aria-valuenow for a range widget. +The **`ariaValueText`** property of the {{domxref("Element")}} interface reflects the value of the [`aria-valuetext`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-valuetext) attribute, which defines the human-readable text alternative of aria-valuenow for a range widget. ## Value diff --git a/files/en-us/web/api/element/assignedslot/index.md b/files/en-us/web/api/element/assignedslot/index.md index c10660c7db098b4..e9bbe877c3419dc 100644 --- a/files/en-us/web/api/element/assignedslot/index.md +++ b/files/en-us/web/api/element/assignedslot/index.md @@ -28,7 +28,7 @@ using the contents of a template that contains a slot named `my-text`. When `<my-paragraph>` is used in the document, the slot is populated by a slottable element by including it inside the element with a -[`slot`](/en-US/docs/Web/HTML/Global_attributes/slot) attribute +[`slot`](/en-US/docs/Web/HTML/Reference/Global_attributes/slot) attribute with the value `my-text`. Here is one such example: ```html diff --git a/files/en-us/web/api/element/attachshadow/index.md b/files/en-us/web/api/element/attachshadow/index.md index 6a48c2f883663f9..1c092dda9ebad68 100644 --- a/files/en-us/web/api/element/attachshadow/index.md +++ b/files/en-us/web/api/element/attachshadow/index.md @@ -39,7 +39,7 @@ The following is a list of elements you _can_ attach a shadow root to: ## Calling this method on an element that is already a shadow host -The method may be called on an element that already has a [declarative shadow root](/en-US/docs/Web/HTML/Element/template#declarative_shadow_dom), provided the specified mode `mode` matches the existing mode. +The method may be called on an element that already has a [declarative shadow root](/en-US/docs/Web/HTML/Reference/Elements/template#declarative_shadow_dom), provided the specified mode `mode` matches the existing mode. In this case the {{domxref("ShadowRoot")}} that was already present will be cleared and returned. This allows for cases where, for example, server-side rendering has already declaratively created a shadow root, and then client-side code attempts to attach the root again. @@ -120,7 +120,7 @@ Returns a {{domxref("ShadowRoot")}} object. - outside the HTML namespace or that can't have a shadow attached to it. - where the element definition static property `disabledFeatures` has been given a value of `"shadow"`. - that already has a shadow root that was not created declaratively. - - that has a [declarative shadow root](/en-US/docs/Web/HTML/Element/template#declarative_shadow_dom) but the specified `mode` does not match the existing mode. + - that has a [declarative shadow root](/en-US/docs/Web/HTML/Reference/Elements/template#declarative_shadow_dom) but the specified `mode` does not match the existing mode. ## Examples @@ -209,5 +209,5 @@ customElements.define("my-custom-element", MyCustomElement); - {{domxref("ShadowRoot.mode")}} - {{domxref("ShadowRoot.delegatesFocus")}} - {{domxref("ShadowRoot.slotAssignment")}} -- Declaratively attach a shadow root with the [`shadowrootmode`](/en-US/docs/Web/HTML/Element/template#shadowrootmode) attribute of the [`<template>` element](/en-US/docs/Web/HTML/Element/template) +- Declaratively attach a shadow root with the [`shadowrootmode`](/en-US/docs/Web/HTML/Reference/Elements/template#shadowrootmode) attribute of the [`<template>` element](/en-US/docs/Web/HTML/Reference/Elements/template) - [Declarative shadow DOM](https://web.dev/articles/declarative-shadow-dom) on web.dev (2023) diff --git a/files/en-us/web/api/element/auxclick_event/index.md b/files/en-us/web/api/element/auxclick_event/index.md index cea059f33c0a9f1..2479b830d21c8a2 100644 --- a/files/en-us/web/api/element/auxclick_event/index.md +++ b/files/en-us/web/api/element/auxclick_event/index.md @@ -16,10 +16,10 @@ The **`auxclick`** event is fired at an {{domxref("Element")}} when a non-primar Use the event name in methods like {{domxref("EventTarget.addEventListener", "addEventListener()")}}, or set an event handler property. -```js -addEventListener("auxclick", (event) => {}); +```js-nolint +addEventListener("auxclick", (event) => { }) -onauxclick = (event) => {}; +onauxclick = (event) => { } ``` ## Event type @@ -50,11 +50,11 @@ _This interface inherits properties from {{domxref("MouseEvent")}} and {{domxref - {{domxref('PointerEvent.tangentialPressure')}} {{ReadOnlyInline}} - : The normalized tangential pressure of the pointer input (also known as barrel pressure or [cylinder stress](https://en.wikipedia.org/wiki/Cylinder_stress)) in the range `-1` to `1`, where `0` is the neutral position of the control. - {{domxref('PointerEvent.tiltX')}} {{ReadOnlyInline}} - - : The plane angle (in degrees, in the range of `-90` to `90`) between the Y–Z plane and the plane containing both the pointer (e.g. pen stylus) axis and the Y axis. + - : The plane angle (in degrees, in the range of `-90` to `90`) between the Y–Z plane and the plane containing both the pointer (e.g., pen stylus) axis and the Y axis. - {{domxref('PointerEvent.tiltY')}} {{ReadOnlyInline}} - - : The plane angle (in degrees, in the range of `-90` to `90`) between the X–Z plane and the plane containing both the pointer (e.g. pen stylus) axis and the X axis. + - : The plane angle (in degrees, in the range of `-90` to `90`) between the X–Z plane and the plane containing both the pointer (e.g., pen stylus) axis and the X axis. - {{domxref('PointerEvent.twist')}} {{ReadOnlyInline}} - - : The clockwise rotation of the pointer (e.g. pen stylus) around its major axis in degrees, with a value in the range `0` to `359`. + - : The clockwise rotation of the pointer (e.g., pen stylus) around its major axis in degrees, with a value in the range `0` to `359`. - {{domxref('PointerEvent.pointerType')}} {{ReadOnlyInline}} - : Indicates the device type that caused the event (mouse, pen, touch, etc.). - {{domxref('PointerEvent.isPrimary')}} {{ReadOnlyInline}} diff --git a/files/en-us/web/api/element/beforeinput_event/index.md b/files/en-us/web/api/element/beforeinput_event/index.md index cbf7a551ad42985..05f2efe9034e1ae 100644 --- a/files/en-us/web/api/element/beforeinput_event/index.md +++ b/files/en-us/web/api/element/beforeinput_event/index.md @@ -21,10 +21,10 @@ In the case of `contenteditable` and `designMode`, the event target is the **edi Use the event name in methods like {{domxref("EventTarget.addEventListener", "addEventListener()")}}, or set an event handler property. -```js -addEventListener("beforeinput", (event) => {}); +```js-nolint +addEventListener("beforeinput", (event) => { }) -onbeforeinput = (event) => {}; +onbeforeinput = (event) => { } ``` ## Event type diff --git a/files/en-us/web/api/element/beforematch_event/index.md b/files/en-us/web/api/element/beforematch_event/index.md index 46b7c4c6182787c..7df60b49fb34203 100644 --- a/files/en-us/web/api/element/beforematch_event/index.md +++ b/files/en-us/web/api/element/beforematch_event/index.md @@ -3,12 +3,10 @@ title: "Element: beforematch event" short-title: beforematch slug: Web/API/Element/beforematch_event page-type: web-api-event -status: - - experimental browser-compat: api.Element.beforematch_event --- -{{APIRef}}{{SeeCompatTable}} +{{APIRef}} An element receives a **`beforematch`** event when it is in the _hidden until found_ state and the browser is about to reveal its content because the user has found the content through the "find in page" feature or through fragment navigation. @@ -16,10 +14,10 @@ An element receives a **`beforematch`** event when it is in the _hidden until fo Use the event name in methods like {{domxref("EventTarget.addEventListener", "addEventListener()")}}, or set an event handler property. -```js -addEventListener("beforematch", (event) => {}); +```js-nolint +addEventListener("beforematch", (event) => { }) -onbeforematch = (event) => {}; +onbeforematch = (event) => { } ``` ## Event type @@ -28,22 +26,22 @@ A generic {{domxref("Event")}}. ## Usage notes -The HTML [`hidden`](/en-US/docs/Web/HTML/Global_attributes/hidden) attribute accepts a value `until-found`: when this value is specified, the element is hidden but its content will be accessible to the browser's "find in page" feature or to fragment navigation. When these features cause a scroll to an element in a "hidden until found" subtree, the browser will: +The HTML [`hidden`](/en-US/docs/Web/HTML/Reference/Global_attributes/hidden) attribute accepts a value `until-found`: when this value is specified, the element is hidden but its content will be accessible to the browser's "find in page" feature or to fragment navigation. When these features cause a scroll to an element in a "hidden until found" subtree, the browser will: -- fire a `beforematch` event on the hidden element -- remove the `hidden` attribute from the element -- scroll to the element +1. Fire a `beforematch` event on the hidden element +2. Remove the `hidden` attribute from the element +3. Scroll to the element ## Examples ### Using beforematch -In this example we have: - -- Two {{HTMLElement("div")}} elements. The first is not hidden, while the second has `hidden="until-found"` and `id="until-found-box"` attributes. -- A link whose target is the `"until-found-box"` fragment. +In this example, we have two {{HTMLElement("div")}} elements. +The first is visible, while the second has the `hidden="until-found"` and `id="until-found-box"` attributes. +The element with a `until-found-box` id has a dotted red border and a gray background. -We also have some JavaScript that listens for the `beforematch` event firing on the hidden until found element. The event handler changes the text content of the box. +We also have a link that targets the `"until-found-box"` fragment and JavaScript that listens for the `beforematch` event firing on that hidden element. +The event handler changes the text content of the box to illustrate an action that can occur when the _hidden until found_ state is about to be removed. #### HTML @@ -69,11 +67,11 @@ div { padding: 1rem; font-size: 2rem; } -``` -```css hidden -#until-found-box { - scroll-margin-top: 200px; +div#until-found-box { + color: red; + border: 5px dotted red; + background-color: lightgray; } ``` @@ -96,7 +94,8 @@ document.querySelector("#reset").addEventListener("click", () => { #### Result -Clicking the "Go to hidden content" button navigates to the hidden-until-found element. The `beforematch` event fires, the text content is updated, and then the element's content is displayed. +Clicking the "Go to hidden content" button navigates to the element in the _hidden until found_ state. +The `beforematch` event fires, the text content is updated, and then the element's content is displayed (the `hidden` attribute is removed). To run the example again, click "Reload". @@ -114,4 +113,4 @@ If your browser does not support the `"until-found"` enumerated value of the `hi ## See also -- The HTML [`hidden`](/en-US/docs/Web/HTML/Global_attributes/hidden) attribute +- The HTML [`hidden`](/en-US/docs/Web/HTML/Reference/Global_attributes/hidden) attribute diff --git a/files/en-us/web/api/element/beforescriptexecute_event/index.md b/files/en-us/web/api/element/beforescriptexecute_event/index.md index a8724e98dc0bd92..f5a317f16208133 100644 --- a/files/en-us/web/api/element/beforescriptexecute_event/index.md +++ b/files/en-us/web/api/element/beforescriptexecute_event/index.md @@ -22,10 +22,10 @@ It is a proprietary event specific to Gecko (Firefox). Use the event name in methods like {{domxref("EventTarget.addEventListener", "addEventListener()")}}, or set an event handler property. -```js -addEventListener("NameOfTheEvent", (event) => {}); +```js-nolint +addEventListener("beforescriptexecute", (event) => { }) -onNameOfTheEvent = (event) => {}; +onbeforescriptexecute = (event) => { } ``` ## Event type diff --git a/files/en-us/web/api/element/beforexrselect_event/index.md b/files/en-us/web/api/element/beforexrselect_event/index.md index aa7b45bcb094c65..817da073a57ec22 100644 --- a/files/en-us/web/api/element/beforexrselect_event/index.md +++ b/files/en-us/web/api/element/beforexrselect_event/index.md @@ -18,10 +18,10 @@ This event [bubbles](/en-US/docs/Learn_web_development/Core/Scripting/Event_bubb Use the event name in methods like {{domxref("EventTarget.addEventListener", "addEventListener()")}}, or set an event handler property. -```js -addEventListener("beforexrselect", (event) => {}); +```js-nolint +addEventListener("beforexrselect", (event) => { }) -onbeforexrselect = (event) => {}; +onbeforexrselect = (event) => { } ``` ## Event type diff --git a/files/en-us/web/api/element/blur_event/index.md b/files/en-us/web/api/element/blur_event/index.md index b6cfbf67d877ce5..8153c4cc1e8c2b9 100644 --- a/files/en-us/web/api/element/blur_event/index.md +++ b/files/en-us/web/api/element/blur_event/index.md @@ -24,10 +24,10 @@ The `blur` event is not cancelable. Use the event name in methods like {{domxref("EventTarget.addEventListener", "addEventListener()")}}, or set an event handler property. -```js -addEventListener("blur", (event) => {}); +```js-nolint +addEventListener("blur", (event) => { }) -onblur = (event) => {}; +onblur = (event) => { } ``` ## Event type diff --git a/files/en-us/web/api/element/checkvisibility/index.md b/files/en-us/web/api/element/checkvisibility/index.md index 89b3484c27c4282..c5c9fea32080acd 100644 --- a/files/en-us/web/api/element/checkvisibility/index.md +++ b/files/en-us/web/api/element/checkvisibility/index.md @@ -173,7 +173,7 @@ function updateCSS() { The results are shown below. If you change the selection the results will be applied to the test element (blue outline) and the results of the `checkVisibility()` for each setting should be displayed. So for example, if you set the `opacity: 0` that test (only) should indicate `false`. -However if you set `display: none` then all tests should return `false. +However if you set `display: none` then all tests should return `false`. {{ EmbedLiveSample('Test checkVisibility() with varied CSS', "100%", "200" ) }} diff --git a/files/en-us/web/api/element/classlist/index.md b/files/en-us/web/api/element/classlist/index.md index 9eb98299f654ace..109690dc8d8ed37 100644 --- a/files/en-us/web/api/element/classlist/index.md +++ b/files/en-us/web/api/element/classlist/index.md @@ -19,7 +19,7 @@ of classes as a space-delimited string via {{domxref("element.className")}}. A {{domxref("DOMTokenList")}} representing the contents of the element's `class` attribute. If the `class` attribute is not set or empty, -it returns an empty `DOMTokenList`, i.e. a `DOMTokenList` with +it returns an empty `DOMTokenList`, i.e., a `DOMTokenList` with the `length` property equal to `0`. Although the `classList` property itself is read-only, you can modify its associated `DOMTokenList` using the {{domxref("DOMTokenList/add", "add()")}}, {{domxref("DOMTokenList/remove", "remove()")}}, {{domxref("DOMTokenList/replace", "replace()")}}, and {{domxref("DOMTokenList/toggle", "toggle()")}} methods. diff --git a/files/en-us/web/api/element/classname/index.md b/files/en-us/web/api/element/classname/index.md index 4697d24e72cbc6c..e20ee5fdd1d9075 100644 --- a/files/en-us/web/api/element/classname/index.md +++ b/files/en-us/web/api/element/classname/index.md @@ -9,7 +9,7 @@ browser-compat: api.Element.className {{APIRef("DOM")}} The **`className`** property of the -{{domxref("Element")}} interface gets and sets the value of the [`class` attribute](/en-US/docs/Web/HTML/Global_attributes/class) +{{domxref("Element")}} interface gets and sets the value of the [`class` attribute](/en-US/docs/Web/HTML/Reference/Global_attributes/class) of the specified element. ## Value @@ -35,7 +35,7 @@ the `element` is an {{domxref("SVGElement")}}. It is easier to get/set the {{domxref("Element.setAttribute")}} if you are dealing with SVG elements. However, take into account that {{domxref("Element.getAttribute")}} returns [`null`](/en-US/docs/Web/JavaScript/Reference/Operators/null) -instead of `""` if the `element` has an empty [`class` attribute](/en-US/docs/Web/HTML/Global_attributes/class). +instead of `""` if the `element` has an empty [`class` attribute](/en-US/docs/Web/HTML/Reference/Global_attributes/class). ```js elm.setAttribute("class", "my-class"); diff --git a/files/en-us/web/api/element/click_event/index.md b/files/en-us/web/api/element/click_event/index.md index 84dd872cd50adcb..6046331a063f18e 100644 --- a/files/en-us/web/api/element/click_event/index.md +++ b/files/en-us/web/api/element/click_event/index.md @@ -12,7 +12,7 @@ An element receives a **`click`** event when any of the following occurs: - A pointing-device button (such as a mouse's primary button) is both pressed and released while the pointer is located inside the element. - A touch gesture is performed on the element. -- Any user interaction that is equivalent to a click, such as pressing the <kbd>Space</kbd> key or <kbd>Enter</kbd> key while the element is focused. Note that this only applies to elements with a default key event handler, and therefore, excludes other elements that have been made focusable by setting the [`tabindex`](/en-US/docs/Web/HTML/Global_attributes/tabindex) attribute. +- Any user interaction that is equivalent to a click, such as pressing the <kbd>Space</kbd> key or <kbd>Enter</kbd> key while the element is focused. Note that this only applies to elements with a default key event handler, and therefore, excludes other elements that have been made focusable by setting the [`tabindex`](/en-US/docs/Web/HTML/Reference/Global_attributes/tabindex) attribute. If the button is pressed on one element and the pointer is moved outside the element before the button is released, the event is fired on the most specific ancestor element that contained both elements. @@ -24,10 +24,10 @@ The event is a device-independent event — meaning it can be activated by touch Use the event name in methods like {{domxref("EventTarget.addEventListener", "addEventListener()")}}, or set an event handler property. -```js -addEventListener("click", (event) => {}); +```js-nolint +addEventListener("click", (event) => { }) -onclick = (event) => {}; +onclick = (event) => { } ``` ## Event type @@ -58,11 +58,11 @@ _This interface inherits properties from {{domxref("MouseEvent")}} and {{domxref - {{domxref('PointerEvent.tangentialPressure')}} {{ReadOnlyInline}} - : The normalized tangential pressure of the pointer input (also known as barrel pressure or [cylinder stress](https://en.wikipedia.org/wiki/Cylinder_stress)) in the range `-1` to `1`, where `0` is the neutral position of the control. - {{domxref('PointerEvent.tiltX')}} {{ReadOnlyInline}} - - : The plane angle (in degrees, in the range of `-90` to `90`) between the Y–Z plane and the plane containing both the pointer (e.g. pen stylus) axis and the Y axis. + - : The plane angle (in degrees, in the range of `-90` to `90`) between the Y–Z plane and the plane containing both the pointer (e.g., pen stylus) axis and the Y axis. - {{domxref('PointerEvent.tiltY')}} {{ReadOnlyInline}} - - : The plane angle (in degrees, in the range of `-90` to `90`) between the X–Z plane and the plane containing both the pointer (e.g. pen stylus) axis and the X axis. + - : The plane angle (in degrees, in the range of `-90` to `90`) between the X–Z plane and the plane containing both the pointer (e.g., pen stylus) axis and the X axis. - {{domxref('PointerEvent.twist')}} {{ReadOnlyInline}} - - : The clockwise rotation of the pointer (e.g. pen stylus) around its major axis in degrees, with a value in the range `0` to `359`. + - : The clockwise rotation of the pointer (e.g., pen stylus) around its major axis in degrees, with a value in the range `0` to `359`. - {{domxref('PointerEvent.pointerType')}} {{ReadOnlyInline}} - : Indicates the device type that caused the event (mouse, pen, touch, etc.). - {{domxref('PointerEvent.isPrimary')}} {{ReadOnlyInline}} diff --git a/files/en-us/web/api/element/clientheight/index.md b/files/en-us/web/api/element/clientheight/index.md index a789a329a0bbe4f..d9abc8914861801 100644 --- a/files/en-us/web/api/element/clientheight/index.md +++ b/files/en-us/web/api/element/clientheight/index.md @@ -8,25 +8,15 @@ browser-compat: api.Element.clientHeight {{APIRef("DOM")}} -The **`Element.clientHeight`** read-only property is zero for -elements with no CSS or inline layout boxes; otherwise, it's the inner height of an -element in pixels. It includes padding but excludes borders, margins, and horizontal -scrollbars (if present). +The **`clientHeight`** read-only property of the {{domxref("Element")}} interface is zero for elements with no CSS or inline layout boxes; otherwise, it's the inner height of an element in pixels. It includes padding but excludes borders, margins, and horizontal scrollbars (if present). -`clientHeight` can be calculated as: CSS `height` + CSS -`padding` - height of horizontal scrollbar (if present). +`clientHeight` can be calculated as: CSS `height` + CSS `padding` - height of horizontal scrollbar (if present). -When `clientHeight` is used on the root element (the -`<html>` element), (or on `<body>` if the document is -in quirks mode), the viewport's height (excluding any scrollbar) is returned. - -> [!NOTE] -> This property will round the value to an integer. If you need -> a fractional value, use {{ domxref("element.getBoundingClientRect()") }}. +When `clientHeight` is used on the root element (the `<html>` element), (or on `<body>` if the document is in quirks mode), the viewport's height (excluding any scrollbar) is returned. ## Value -A number. +An integer. ## Examples @@ -42,6 +32,10 @@ A number. ## See also +- [Determining the dimensions of elements](/en-US/docs/Web/API/CSS_Object_Model/Determining_the_dimensions_of_elements) - {{domxref("HTMLElement.offsetHeight")}} - {{domxref("Element.scrollHeight")}} -- [Determining the dimensions of elements](/en-US/docs/Web/API/CSS_Object_Model/Determining_the_dimensions_of_elements) +- {{domxref("Element.clientWidth")}} +- {{domxref("Element.clientLeft")}} +- {{domxref("Element.clientTop")}} +- {{domxref("Element.getBoundingClientRect()")}} diff --git a/files/en-us/web/api/element/clientleft/index.md b/files/en-us/web/api/element/clientleft/index.md index a6f4a2b0a28d8d0..ea260be0c5312a0 100644 --- a/files/en-us/web/api/element/clientleft/index.md +++ b/files/en-us/web/api/element/clientleft/index.md @@ -8,24 +8,14 @@ browser-compat: api.Element.clientLeft {{ APIRef("DOM") }} -The width of the left border of an element in pixels. It includes the width of the -vertical scrollbar if the text direction of the element is right-to-left and if there -is an overflow causing a left vertical scrollbar to be rendered. -`clientLeft` does not include the left margin or the left padding. -`clientLeft` is read-only. +The **`clientLeft`** read-only property of the {{domxref("Element")}} interface returns the width of the left border of an element in pixels. It includes the width of the vertical scrollbar if the text direction of the element is right-to-left and if there is an overflow causing a left vertical scrollbar to be rendered. `clientLeft` does not include the left margin or the left padding. > [!NOTE] -> This property will round the value to an integer. If you -> need a fractional value, use {{ domxref("element.getBoundingClientRect()") }}. - -> [!NOTE] -> When an element has -> `display: inline`, `clientLeft` returns `0` -> regardless of the element's border. +> When an element has `display: inline`, `clientLeft` returns `0` regardless of the element's border. ## Value -A number. +An integer. ## Examples @@ -75,3 +65,13 @@ In the following example, the client area has a white background and a 24px blac ## Browser compatibility {{Compat}} + +## See also + +- [Determining the dimensions of elements](/en-US/docs/Web/API/CSS_Object_Model/Determining_the_dimensions_of_elements) +- {{domxref("HTMLElement.offsetLeft")}} +- {{domxref("Element.scrollLeft")}} +- {{domxref("Element.clientHeight")}} +- {{domxref("Element.clientWidth")}} +- {{domxref("Element.clientTop")}} +- {{domxref("Element.getBoundingClientRect()")}} diff --git a/files/en-us/web/api/element/clienttop/index.md b/files/en-us/web/api/element/clienttop/index.md index 21a6280a16724cd..c69ee22c916978e 100644 --- a/files/en-us/web/api/element/clienttop/index.md +++ b/files/en-us/web/api/element/clienttop/index.md @@ -8,25 +8,13 @@ browser-compat: api.Element.clientTop {{ APIRef("DOM") }} -The width of the top border of an element in pixels. It is a read-only, integer -property of element. - -As it happens, all that lies between the two locations (`offsetTop` and -client area top) is the element's border. This is because the `offsetTop` -indicates the location of the top of the border (not the margin) while the client area -starts immediately below the border, (client area includes padding.) Therefore, the -**clientTop** value will always equal the integer portion of the -`.getComputedStyle()` value for "border-top-width". (Actually might be -Math.round(parseFloat()).) For example, if the computed "border-top-width" is zero, -then **`clientTop`** is also zero. - -> [!NOTE] -> This property will round the value to an integer. If you -> need a fractional value, use {{ domxref("element.getBoundingClientRect()") }}. +The **`clientTop`** read-only property of the {{domxref("Element")}} interface returns the width of the top border of an element in pixels. + +All that lies between the `offsetTop` and `clientTop` is the element's border. This is because the `offsetTop` indicates the location of the top of the border (not the margin) while the client area starts immediately below the border, including padding. Therefore, the `clientTop` value is always equal to the `border-top-width`, rounded to integer. For example, if the computed `border-top-width` is zero, then `clientTop` is also zero. ## Value -A number. +An integer. ## Examples @@ -69,10 +57,6 @@ In the following example, the client area has a white background and a 24px blac {{EmbedLiveSample("Examples", 400, 350)}} -## Notes - -`clientTop` was first introduced in the MS IE DHTML object model. - ## Specifications {{Specifications}} @@ -80,3 +64,13 @@ In the following example, the client area has a white background and a 24px blac ## Browser compatibility {{Compat}} + +## See also + +- [Determining the dimensions of elements](/en-US/docs/Web/API/CSS_Object_Model/Determining_the_dimensions_of_elements) +- {{domxref("HTMLElement.offsetTop")}} +- {{domxref("Element.scrollTop")}} +- {{domxref("Element.clientHeight")}} +- {{domxref("Element.clientWidth")}} +- {{domxref("Element.clientLeft")}} +- {{domxref("Element.getBoundingClientRect()")}} diff --git a/files/en-us/web/api/element/clientwidth/index.md b/files/en-us/web/api/element/clientwidth/index.md index b68ec4ca2a002c8..1827feb1c5b3284 100644 --- a/files/en-us/web/api/element/clientwidth/index.md +++ b/files/en-us/web/api/element/clientwidth/index.md @@ -8,22 +8,13 @@ browser-compat: api.Element.clientWidth {{APIRef("DOM")}} -The **`Element.clientWidth`** property is zero for inline -elements and elements with no CSS; otherwise, it's the inner width of an element in -pixels. It includes padding but excludes borders, margins, and vertical scrollbars (if -present). +The **`clientWidth`** read-only property of the {{domxref("Element")}} interface is zero for inline elements and elements with no CSS; otherwise, it's the inner width of an element in pixels. It includes padding but excludes borders, margins, and vertical scrollbars (if present). -When `clientWidth` is used on the root element (the -`<html>` element), (or on `<body>` if the document is -in quirks mode), the viewport's width (excluding any scrollbar) is returned. - -> [!NOTE] -> This property will round the value to an integer. If you need -> a fractional value, use {{ domxref("element.getBoundingClientRect()") }}. +When `clientWidth` is used on the root element (the `<html>` element), (or on `<body>` if the document is in quirks mode), the viewport's width (excluding any scrollbar) is returned. ## Value -A number. +An integer. ## Examples @@ -39,6 +30,10 @@ A number. ## See also +- [Determining the dimensions of elements](/en-US/docs/Web/API/CSS_Object_Model/Determining_the_dimensions_of_elements) - {{domxref("HTMLElement.offsetWidth")}} - {{domxref("Element.scrollWidth")}} -- [Determining the dimensions of elements](/en-US/docs/Web/API/CSS_Object_Model/Determining_the_dimensions_of_elements) +- {{domxref("Element.clientHeight")}} +- {{domxref("Element.clientLeft")}} +- {{domxref("Element.clientTop")}} +- {{domxref("Element.getBoundingClientRect()")}} diff --git a/files/en-us/web/api/element/compositionend_event/index.md b/files/en-us/web/api/element/compositionend_event/index.md index aa7f9aa7af5103b..0ca982725947e45 100644 --- a/files/en-us/web/api/element/compositionend_event/index.md +++ b/files/en-us/web/api/element/compositionend_event/index.md @@ -16,10 +16,10 @@ For example, this event could be fired after a user finishes entering a Chinese Use the event name in methods like {{domxref("EventTarget.addEventListener", "addEventListener()")}}, or set an event handler property. -```js -addEventListener("compositionend", (event) => {}); +```js-nolint +addEventListener("compositionend", (event) => { }) -oncompositionend = (event) => {}; +oncompositionend = (event) => { } ``` ## Event type diff --git a/files/en-us/web/api/element/compositionstart_event/index.md b/files/en-us/web/api/element/compositionstart_event/index.md index c4411011451e4aa..1c0e3c0a06f2439 100644 --- a/files/en-us/web/api/element/compositionstart_event/index.md +++ b/files/en-us/web/api/element/compositionstart_event/index.md @@ -16,10 +16,10 @@ For example, this event could be fired after a user starts entering a Chinese ch Use the event name in methods like {{domxref("EventTarget.addEventListener", "addEventListener()")}}, or set an event handler property. -```js -addEventListener("compositionstart", (event) => {}); +```js-nolint +addEventListener("compositionstart", (event) => { }) -oncompositionstart = (event) => {}; +oncompositionstart = (event) => { } ``` ## Event type diff --git a/files/en-us/web/api/element/compositionupdate_event/index.md b/files/en-us/web/api/element/compositionupdate_event/index.md index e5e05c08aacd5ed..3418a5d2876cd3c 100644 --- a/files/en-us/web/api/element/compositionupdate_event/index.md +++ b/files/en-us/web/api/element/compositionupdate_event/index.md @@ -16,10 +16,10 @@ For example, this event could be fired while a user enters a Chinese character u Use the event name in methods like {{domxref("EventTarget.addEventListener", "addEventListener()")}}, or set an event handler property. -```js -addEventListener("compositionupdate", (event) => {}); +```js-nolint +addEventListener("compositionupdate", (event) => { }) -oncompositionupdate = (event) => {}; +oncompositionupdate = (event) => { } ``` ## Event type diff --git a/files/en-us/web/api/element/computedstylemap/index.md b/files/en-us/web/api/element/computedstylemap/index.md index c8144ffb0608911..8f2d734cb384f50 100644 --- a/files/en-us/web/api/element/computedstylemap/index.md +++ b/files/en-us/web/api/element/computedstylemap/index.md @@ -25,10 +25,14 @@ None. ### Return value -A {{domxref("StylePropertyMapReadOnly")}} interface. +A {{domxref("StylePropertyMapReadOnly")}} object. + +Unlike {{domxref("Window.getComputedStyle")}}, the return value contains [computed values](/en-US/docs/Web/CSS/CSS_cascade/Value_processing#computed_value), not [resolved values](/en-US/docs/Web/CSS/CSS_cascade/Value_processing#resolved_value). For most properties, they are the same, except a few layout-related properties, where the resolved value is the [used value](/en-US/docs/Web/CSS/CSS_cascade/Value_processing#used_value) instead of the computed value. See the [comparison with `getComputedStyle()`](#comparison_with_getcomputedstyle) example for details. ## Examples +### Getting default styles + We start with some simple HTML: a paragraph with a link, and a definition list to which we will add all the CSS Property / Value pairs. @@ -49,7 +53,7 @@ a { ``` We add JavaScript to grab our link and return back a definition list of all the CSS -property values using `computedStyleMap().` +property values using `computedStyleMap()`. ```js // get the element @@ -79,12 +83,60 @@ In [browsers that support `computedStyleMap()`](#browser_compatibility), you'll see a list of all the CSS properties and values. In other browsers you'll just see a link. -{{EmbedLiveSample("Examples", 300, 300)}} +{{EmbedLiveSample("getting_default_styles", 300, 300)}} Did you realize how many default CSS properties a link had? Update the `document.querySelector("a")` to `document.querySelector("p")`, and you'll notice a difference in the `margin-top` and `margin-bottom` default computed values. +### Comparison with getComputedStyle() + +{{domxref("Window.getComputedStyle()")}} returns [resolved values](/en-US/docs/Web/CSS/CSS_cascade/Value_processing#resolved_value), while `computedStyleMap()` returns [computed values](/en-US/docs/Web/CSS/CSS_cascade/Value_processing#computed_value). These are usually the same, but for some properties, the resolved value is the [used value](/en-US/docs/Web/CSS/CSS_cascade/Value_processing#used_value) instead of the computed value. For example, percentage values for widths are resolved to pixel values _post-layout_, so the used values are in pixels, while the computed values are still in percentages. + +Note that the way we present it makes the two APIs seem more similar than they are. `computedStyleMap()` contains [CSS Typed OM](/en-US/docs/Web/API/CSS_Typed_OM_API) objects, while `getComputedStyle()` contains strings. The former presents the same information in a more structured and processable way. + +In this example, the `width` property is specified as a percentage, so the computed value is given as a percentage, but the resolved value is given in pixels. The `height` is always in pixels. The `background-color` is a named color, but it is computed to an RGB value. + +```html +<div class="container"> + <div class="item"></div> +</div> +<pre id="result"></pre> +``` + +```css +.container { + width: 200px; + height: 200px; +} + +.item { + width: 50%; + height: 100px; + background-color: tomato; +} +``` + +```js +const item = document.querySelector(".item"); +const result = document.querySelector("#result"); +const resolvedValues = getComputedStyle(item); +const computedValues = item.computedStyleMap(); + +result.textContent = `resolvedValues.width = ${resolvedValues.width} +computedValues.get("width") = ${computedValues.get("width")} + +resolvedValues.height = ${resolvedValues.height} +computedValues.get("height") = ${computedValues.get("height")} + +resolvedValues.backgroundColor = ${resolvedValues.backgroundColor} +computedValues.get("background-color") = ${computedValues.get( + "background-color", +)}`; +``` + +{{EmbedLiveSample("comparison_with_getcomputedstyle", "", 350)}} + ## Specifications {{Specifications}} @@ -92,3 +144,7 @@ and `margin-bottom` default computed values. ## Browser compatibility {{Compat}} + +## See also + +- {{domxref("Window.getComputedStyle()")}} diff --git a/files/en-us/web/api/element/contentvisibilityautostatechange_event/index.md b/files/en-us/web/api/element/contentvisibilityautostatechange_event/index.md index 1ed2c5c03992d28..0f817897dfc3c43 100644 --- a/files/en-us/web/api/element/contentvisibilityautostatechange_event/index.md +++ b/files/en-us/web/api/element/contentvisibilityautostatechange_event/index.md @@ -11,21 +11,23 @@ browser-compat: api.Element.contentvisibilityautostatechange_event The **`contentvisibilityautostatechange`** event fires on any element with {{cssxref("content-visibility", "content-visibility: auto")}} set on it when it starts or stops being [relevant to the user](/en-US/docs/Web/CSS/CSS_containment/Using_CSS_containment#relevant_to_the_user) and [skipping its contents](/en-US/docs/Web/CSS/CSS_containment/Using_CSS_containment#skips_its_contents). While the element is not relevant (between the start and end events), the user agent skips an element's rendering, including layout and painting, which can significantly improve page rendering speed. -The `contentvisibilityautostatechange` event provides a way for an app's code to also start or stop rendering processes (e.g. drawing on a {{htmlelement("canvas")}}) when they are not needed, thereby conserving processing power. +The `contentvisibilityautostatechange` event provides a way for an app's code to also start or stop rendering processes (e.g., drawing on a {{htmlelement("canvas")}}) when they are not needed, thereby conserving processing power. -Note that even when hidden from view, element contents will remain semantically relevant (e.g. to assistive technology users), so this signal should not be used to skip significant semantic DOM updates. +Note that even when hidden from view, element contents will remain semantically relevant (e.g., to assistive technology users), so this signal should not be used to skip significant semantic DOM updates. ## Syntax Use the event name in methods like {{domxref("EventTarget.addEventListener", "addEventListener()")}}, or set an event handler property. -```js -addEventListener("contentvisibilityautostatechange", (event) => {}); -oncontentvisibilityautostatechange = (event) => {}; +```js-nolint +addEventListener("contentvisibilityautostatechange", (event) => { }) + +oncontentvisibilityautostatechange = (event) => { } ``` -> [!NOTE] -> The event object is of type {{domxref("ContentVisibilityAutoStateChangeEvent")}}. +## Event type + +A {{domxref("ContentVisibilityAutoStateChangeEvent")}}. ## Examples diff --git a/files/en-us/web/api/element/contextmenu_event/index.md b/files/en-us/web/api/element/contextmenu_event/index.md index b61ed03bd58bc08..fce86bae92e9e72 100644 --- a/files/en-us/web/api/element/contextmenu_event/index.md +++ b/files/en-us/web/api/element/contextmenu_event/index.md @@ -21,10 +21,10 @@ Any right-click event that is not disabled (by calling the click event's {{domxr Use the event name in methods like {{domxref("EventTarget.addEventListener", "addEventListener()")}}, or set an event handler property. -```js -addEventListener("contextmenu", (event) => {}); +```js-nolint +addEventListener("contextmenu", (event) => { }) -oncontextmenu = (event) => {}; +oncontextmenu = (event) => { } ``` ## Event type @@ -55,11 +55,11 @@ _This interface inherits properties from {{domxref("MouseEvent")}} and {{domxref - {{domxref('PointerEvent.tangentialPressure')}} {{ReadOnlyInline}} - : The normalized tangential pressure of the pointer input (also known as barrel pressure or [cylinder stress](https://en.wikipedia.org/wiki/Cylinder_stress)) in the range `-1` to `1`, where `0` is the neutral position of the control. - {{domxref('PointerEvent.tiltX')}} {{ReadOnlyInline}} - - : The plane angle (in degrees, in the range of `-90` to `90`) between the Y–Z plane and the plane containing both the pointer (e.g. pen stylus) axis and the Y axis. + - : The plane angle (in degrees, in the range of `-90` to `90`) between the Y–Z plane and the plane containing both the pointer (e.g., pen stylus) axis and the Y axis. - {{domxref('PointerEvent.tiltY')}} {{ReadOnlyInline}} - - : The plane angle (in degrees, in the range of `-90` to `90`) between the X–Z plane and the plane containing both the pointer (e.g. pen stylus) axis and the X axis. + - : The plane angle (in degrees, in the range of `-90` to `90`) between the X–Z plane and the plane containing both the pointer (e.g., pen stylus) axis and the X axis. - {{domxref('PointerEvent.twist')}} {{ReadOnlyInline}} - - : The clockwise rotation of the pointer (e.g. pen stylus) around its major axis in degrees, with a value in the range `0` to `359`. + - : The clockwise rotation of the pointer (e.g., pen stylus) around its major axis in degrees, with a value in the range `0` to `359`. - {{domxref('PointerEvent.pointerType')}} {{ReadOnlyInline}} - : Indicates the device type that caused the event (mouse, pen, touch, etc.). - {{domxref('PointerEvent.isPrimary')}} {{ReadOnlyInline}} diff --git a/files/en-us/web/api/element/copy_event/index.md b/files/en-us/web/api/element/copy_event/index.md index e3213e4d6c039cb..c610863cb12476f 100644 --- a/files/en-us/web/api/element/copy_event/index.md +++ b/files/en-us/web/api/element/copy_event/index.md @@ -18,16 +18,16 @@ However, the handler cannot _read_ the clipboard data. It's possible to construct and dispatch a [synthetic](/en-US/docs/Web/Events/Creating_and_triggering_events) `copy` event, but this will not affect the system clipboard. -This event [bubbles](/en-US/docs/Learn_web_development/Core/Scripting/Event_bubbling), is [cancelable](/en-US/docs/Web/API/Event/cancelable) and is [composed](/en-US/docs/Web/API/Event/composed). +This event [bubbles](/en-US/docs/Learn_web_development/Core/Scripting/Event_bubbling) up the DOM tree, eventually to {{domxref("Document")}} and {{domxref("Window")}}, is [cancelable](/en-US/docs/Web/API/Event/cancelable) and is [composed](/en-US/docs/Web/API/Event/composed). ## Syntax Use the event name in methods like {{domxref("EventTarget.addEventListener", "addEventListener()")}}, or set an event handler property. -```js -addEventListener("copy", (event) => {}); +```js-nolint +addEventListener("copy", (event) => { }) -oncopy = (event) => {}; +oncopy = (event) => { } ``` ## Event type @@ -84,6 +84,5 @@ source.addEventListener("copy", (event) => { ## See also -- Related events: {{domxref("Element/cut_event", "cut")}}, {{domxref("Element/paste_event", "paste")}} -- This event on {{domxref("Document")}} targets: {{domxref("Document/copy_event", "copy")}} -- This event on {{domxref("Window")}} targets: {{domxref("Window/copy_event", "copy")}} +- {{domxref("Element/cut_event", "cut")}} event +- {{domxref("Element/paste_event", "paste")}} event diff --git a/files/en-us/web/api/element/cut_event/index.md b/files/en-us/web/api/element/cut_event/index.md index bacad277de964c9..6fcd59c87becbd6 100644 --- a/files/en-us/web/api/element/cut_event/index.md +++ b/files/en-us/web/api/element/cut_event/index.md @@ -22,16 +22,16 @@ The handler cannot _read_ the clipboard data. It's possible to construct and dispatch a [synthetic](/en-US/docs/Web/Events/Creating_and_triggering_events) `cut` event, but this will not affect the system clipboard or the document's contents. -This event [bubbles](/en-US/docs/Learn_web_development/Core/Scripting/Event_bubbling), is [cancelable](/en-US/docs/Web/API/Event/cancelable) and is [composed](/en-US/docs/Web/API/Event/composed). +This event [bubbles](/en-US/docs/Learn_web_development/Core/Scripting/Event_bubbling) up the DOM tree, eventually to {{domxref("Document")}} and {{domxref("Window")}}, is [cancelable](/en-US/docs/Web/API/Event/cancelable) and is [composed](/en-US/docs/Web/API/Event/composed). ## Syntax Use the event name in methods like {{domxref("EventTarget.addEventListener", "addEventListener()")}}, or set an event handler property. -```js -addEventListener("cut", (event) => {}); +```js-nolint +addEventListener("cut", (event) => { }) -oncut = (event) => {}; +oncut = (event) => { } ``` ## Event type @@ -89,6 +89,5 @@ source.addEventListener("cut", (event) => { ## See also -- Related events: {{domxref("Element/copy_event", "copy")}}, {{domxref("Element/paste_event", "paste")}} -- This event on {{domxref("Document")}} targets: {{domxref("Document/cut_event", "cut")}} -- This event on {{domxref("Window")}} targets: {{domxref("Window/cut_event", "cut")}} +- {{domxref("Element/copy_event", "copy")}} event +- {{domxref("Element/paste_event", "paste")}} event diff --git a/files/en-us/web/api/element/dblclick_event/index.md b/files/en-us/web/api/element/dblclick_event/index.md index faedcfe953c6d3d..34d6adb6cfcc4be 100644 --- a/files/en-us/web/api/element/dblclick_event/index.md +++ b/files/en-us/web/api/element/dblclick_event/index.md @@ -16,10 +16,10 @@ The **`dblclick`** event fires when a pointing device button (such as a mouse's Use the event name in methods like {{domxref("EventTarget.addEventListener", "addEventListener()")}}, or set an event handler property. -```js -addEventListener("dblclick", (event) => {}); +```js-nolint +addEventListener("dblclick", (event) => { }) -ondblclick = (event) => {}; +ondblclick = (event) => { } ``` ## Event type diff --git a/files/en-us/web/api/element/domactivate_event/index.md b/files/en-us/web/api/element/domactivate_event/index.md index 0b96992cda78c77..93cf7fa910c82b0 100644 --- a/files/en-us/web/api/element/domactivate_event/index.md +++ b/files/en-us/web/api/element/domactivate_event/index.md @@ -16,10 +16,10 @@ The **`DOMActivate`** event is fired at an element when it becomes active, such Use the event name in methods like {{domxref("EventTarget.addEventListener", "addEventListener()")}}, or set an event handler property. -```js -addEventListener("DOMActivate", (event) => {}); +```js-nolint +addEventListener("DOMActivate", (event) => { }) -onDOMActivate = (event) => {}; +onDOMActivate = (event) => { } ``` ## Event type @@ -43,19 +43,26 @@ A {{domxref("MouseEvent")}}. Inherits from {{domxref("UIEvent")}} and {{domxref( width="6cm" height="5cm" viewBox="0 0 600 500"> - <desc>Example: invoke an ECMAScript function from a DOMActivate event</desc> - - <!-- ECMAScript to change the radius --> - <script type="application/ecmascript"> - <![CDATA[ function change(evt) { const circle = evt.target; const - currentRadius = circle.getFloatTrait("r"); if (currentRadius === 100) { - circle.setFloatTrait("r", currentRadius * 2); } else { - circle.setFloatTrait("r", currentRadius * 0.5); } } ]]> + <desc>Example: invoke an JavaScript function from a DOMActivate event</desc> + + <!-- JavaScript to change the radius --> + <script> + <![CDATA[ + function change(evt) { + const circle = evt.target; + const currentRadius = circle.getFloatTrait("r"); + if (currentRadius === 100) { + circle.setFloatTrait("r", currentRadius * 2); + } else { + circle.setFloatTrait("r", currentRadius * 0.5); + } + } + ]]> </script> <!-- Act on each DOMActivate event --> <circle cx="300" cy="225" r="100" fill="red"> - <handler type="application/ecmascript" ev:event="DOMActivate"> + <handler type="text/javascript" ev:event="DOMActivate"> change(evt); </handler> </circle> diff --git a/files/en-us/web/api/element/dommousescroll_event/index.md b/files/en-us/web/api/element/dommousescroll_event/index.md index fb02e38bffa1b9e..a2d0aa73b0c409f 100644 --- a/files/en-us/web/api/element/dommousescroll_event/index.md +++ b/files/en-us/web/api/element/dommousescroll_event/index.md @@ -23,10 +23,10 @@ Use the standardized {{domxref("Element/wheel_event","wheel")}} event if availab Use the event name in methods like {{domxref("EventTarget.addEventListener", "addEventListener()")}}, or set an event handler property. -```js -addEventListener("DOMMouseScroll", (event) => {}); +```js-nolint +addEventListener("DOMMouseScroll", (event) => { }) -onDOMMouseScroll = (event) => {}; +onDOMMouseScroll = (event) => { } ``` ## Event type diff --git a/files/en-us/web/api/element/elementtiming/index.md b/files/en-us/web/api/element/elementtiming/index.md index 4b99e576b0244de..79658bdb2840163 100644 --- a/files/en-us/web/api/element/elementtiming/index.md +++ b/files/en-us/web/api/element/elementtiming/index.md @@ -10,7 +10,7 @@ browser-compat: api.Element.elementTiming {{APIRef("DOM")}}{{SeeCompatTable}} -The **`elementTiming`** property of the {{domxref("Element")}} interface identifies elements for observation in the {{domxref("PerformanceElementTiming")}} API. The `elementTiming` property reflects the value of the [`elementtiming`](/en-US/docs/Web/HTML/Attributes/elementtiming) attribute. +The **`elementTiming`** property of the {{domxref("Element")}} interface identifies elements for observation in the {{domxref("PerformanceElementTiming")}} API. The `elementTiming` property reflects the value of the [`elementtiming`](/en-US/docs/Web/HTML/Reference/Attributes/elementtiming) attribute. ## Value @@ -20,7 +20,7 @@ A string. ### Logging the value of `elementTiming` -In this example, adding the [`elementtiming`](/en-US/docs/Web/HTML/Attributes/elementtiming) attribute to the {{HTMLElement("img")}} element sets the image to be observed. +In this example, adding the [`elementtiming`](/en-US/docs/Web/HTML/Reference/Attributes/elementtiming) attribute to the {{HTMLElement("img")}} element sets the image to be observed. ```html <img @@ -50,4 +50,4 @@ For a more complete example on how to use the Element Timing API, see {{domxref( ## See also - {{domxref("PerformanceElementTiming")}} -- [`elementtiming`](/en-US/docs/Web/HTML/Attributes/elementtiming) HTML attribute +- [`elementtiming`](/en-US/docs/Web/HTML/Reference/Attributes/elementtiming) HTML attribute diff --git a/files/en-us/web/api/element/focus_event/index.md b/files/en-us/web/api/element/focus_event/index.md index 4f07b997220e390..386ae1e1f7184d6 100644 --- a/files/en-us/web/api/element/focus_event/index.md +++ b/files/en-us/web/api/element/focus_event/index.md @@ -18,10 +18,10 @@ The `focus` event is not cancelable. Use the event name in methods like {{domxref("EventTarget.addEventListener", "addEventListener()")}}, or set an event handler property. -```js -addEventListener("focus", (event) => {}); +```js-nolint +addEventListener("focus", (event) => { }) -onfocus = (event) => {}; +onfocus = (event) => { } ``` ## Event type diff --git a/files/en-us/web/api/element/focusin_event/index.md b/files/en-us/web/api/element/focusin_event/index.md index cb606d6b61c6c94..81a3cf2e403ae25 100644 --- a/files/en-us/web/api/element/focusin_event/index.md +++ b/files/en-us/web/api/element/focusin_event/index.md @@ -18,10 +18,13 @@ The `focusin` event is not cancelable. Use the event name in methods like {{domxref("EventTarget.addEventListener", "addEventListener()")}}. -```js -addEventListener("focusin", (event) => {}); +```js-nolint +addEventListener("focusin", (event) => { }) ``` +> [!NOTE] +> There is no `onfocusin` event handler property for this event. + ## Event type A {{domxref("FocusEvent")}}. Inherits from {{domxref("UIEvent")}} and {{domxref("Event")}}. diff --git a/files/en-us/web/api/element/focusout_event/index.md b/files/en-us/web/api/element/focusout_event/index.md index 8d642161d2cde1f..3116a4b439448e5 100644 --- a/files/en-us/web/api/element/focusout_event/index.md +++ b/files/en-us/web/api/element/focusout_event/index.md @@ -18,10 +18,13 @@ The `focusout` event is not cancelable. Use the event name in methods like {{domxref("EventTarget.addEventListener", "addEventListener()")}}. -```js -addEventListener("focusout", (event) => {}); +```js-nolint +addEventListener("focusout", (event) => { }) ``` +> [!NOTE] +> There is no `onfocusout` event handler property for this event. + ## Event type A {{domxref("FocusEvent")}}. Inherits from {{domxref("UIEvent")}} and {{domxref("Event")}}. diff --git a/files/en-us/web/api/element/fullscreenchange_event/index.md b/files/en-us/web/api/element/fullscreenchange_event/index.md index c858c49999a809f..dd4f7b1be856067 100644 --- a/files/en-us/web/api/element/fullscreenchange_event/index.md +++ b/files/en-us/web/api/element/fullscreenchange_event/index.md @@ -20,10 +20,10 @@ This event is not cancelable. Use the event name in methods like {{domxref("EventTarget.addEventListener", "addEventListener()")}}, or set an event handler property. -```js -addEventListener("fullscreenchange", (event) => {}); +```js-nolint +addEventListener("fullscreenchange", (event) => { }) -onfullscreenchange = (event) => {}; +onfullscreenchange = (event) => { } ``` ## Event type diff --git a/files/en-us/web/api/element/fullscreenerror_event/index.md b/files/en-us/web/api/element/fullscreenerror_event/index.md index 0e0b9cf02f3522a..988b3b0b1e3168b 100644 --- a/files/en-us/web/api/element/fullscreenerror_event/index.md +++ b/files/en-us/web/api/element/fullscreenerror_event/index.md @@ -20,10 +20,10 @@ This event is not cancelable. Use the event name in methods like {{domxref("EventTarget.addEventListener", "addEventListener()")}}, or set an event handler property. -```js -addEventListener("fullscreenchange", (event) => {}); +```js-nolint +addEventListener("fullscreenerror", (event) => { }) -onfullscreenchange = (event) => {}; +onfullscreenerror = (event) => { } ``` ## Event type diff --git a/files/en-us/web/api/element/gesturechange_event/index.md b/files/en-us/web/api/element/gesturechange_event/index.md index cac75d8915ffa3b..faa213353815227 100644 --- a/files/en-us/web/api/element/gesturechange_event/index.md +++ b/files/en-us/web/api/element/gesturechange_event/index.md @@ -18,10 +18,10 @@ It is a proprietary event specific to WebKit. Use the event name in methods like {{domxref("EventTarget.addEventListener", "addEventListener()")}}, or set an event handler property. -```js -addEventListener("gesturechange", (event) => {}); +```js-nolint +addEventListener("gesturechange", (event) => { }) -ongesturechange = (event) => {}; +ongesturechange = (event) => { } ``` ## Event type diff --git a/files/en-us/web/api/element/gestureend_event/index.md b/files/en-us/web/api/element/gestureend_event/index.md index a1c5e4a98539f63..84bb33df6d0be26 100644 --- a/files/en-us/web/api/element/gestureend_event/index.md +++ b/files/en-us/web/api/element/gestureend_event/index.md @@ -18,10 +18,10 @@ It is a proprietary event specific to WebKit. Use the event name in methods like {{domxref("EventTarget.addEventListener", "addEventListener()")}}, or set an event handler property. -```js -addEventListener("gestureend", (event) => {}); +```js-nolint +addEventListener("gestureend", (event) => { }) -ongestureend = (event) => {}; +ongestureend = (event) => { } ``` ## Event type diff --git a/files/en-us/web/api/element/gesturestart_event/index.md b/files/en-us/web/api/element/gesturestart_event/index.md index 6b73069ad3eb2a4..5d023e133fb3b13 100644 --- a/files/en-us/web/api/element/gesturestart_event/index.md +++ b/files/en-us/web/api/element/gesturestart_event/index.md @@ -18,10 +18,10 @@ It is a proprietary event specific to WebKit. Use the event name in methods like {{domxref("EventTarget.addEventListener", "addEventListener()")}}, or set an event handler property. -```js -addEventListener("gesturestart", (event) => {}); +```js-nolint +addEventListener("gesturestart", (event) => { }) -ongesturestart = (event) => {}; +ongesturestart = (event) => { } ``` ## Event type diff --git a/files/en-us/web/api/element/getattribute/index.md b/files/en-us/web/api/element/getattribute/index.md index 09a138809c6483f..f7c46c322602713 100644 --- a/files/en-us/web/api/element/getattribute/index.md +++ b/files/en-us/web/api/element/getattribute/index.md @@ -39,15 +39,14 @@ A string containing the value of `attributeName` if the attribute exists, otherw ``` ```js -// in a console const div1 = document.getElementById("div1"); -//=> <div id="div1">Hi Champ!</div> +// <div id="div1">Hi Champ!</div> const exampleAttr = div1.getAttribute("id"); -//=> "div1" +// "div1" const align = div1.getAttribute("align"); -//=> null +// null ``` ## Description @@ -59,7 +58,7 @@ When called on an HTML element in a DOM flagged as an HTML document, ### Retrieving nonce values -For security reasons, [CSP](/en-US/docs/Web/HTTP/CSP) nonces from non-script +For security reasons, [CSP](/en-US/docs/Web/HTTP/Guides/CSP) nonces from non-script sources, such as CSS selectors, and `.getAttribute("nonce")` calls are hidden. diff --git a/files/en-us/web/api/element/getclientrects/index.md b/files/en-us/web/api/element/getclientrects/index.md index f33123aa0a1d765..1faa1b57f802dcc 100644 --- a/files/en-us/web/api/element/getclientrects/index.md +++ b/files/en-us/web/api/element/getclientrects/index.md @@ -244,9 +244,9 @@ function addClientRectsOverlay(elt) { (() => { /* Call function addClientRectsOverlay(elt) for all elements with assigned class "withClientRectsOverlay" */ - const elts = document.getElementsByClassName("withClientRectsOverlay"); - for (const elt of elts) { - addClientRectsOverlay(elt); + const elems = document.getElementsByClassName("withClientRectsOverlay"); + for (const elem of elems) { + addClientRectsOverlay(elem); } })(); ``` diff --git a/files/en-us/web/api/element/getelementsbyclassname/index.md b/files/en-us/web/api/element/getelementsbyclassname/index.md index afe27a5557f2069..2d0a76f3ef8e918 100644 --- a/files/en-us/web/api/element/getelementsbyclassname/index.md +++ b/files/en-us/web/api/element/getelementsbyclassname/index.md @@ -47,7 +47,7 @@ The opposite is also true; as elements no longer match the set of names, they ar immediately removed from the collection. > [!NOTE] -> In [quirks mode](/en-US/docs/Web/HTML/Quirks_Mode_and_Standards_Mode), the +> In [quirks mode](/en-US/docs/Web/HTML/Guides/Quirks_mode_and_standards_mode), the > class names are compared in a case-insensitive fashion. Otherwise, they're case > sensitive. diff --git a/files/en-us/web/api/element/getelementsbytagname/index.md b/files/en-us/web/api/element/getelementsbytagname/index.md index 995572ebe24c7c4..44c686966b41508 100644 --- a/files/en-us/web/api/element/getelementsbytagname/index.md +++ b/files/en-us/web/api/element/getelementsbytagname/index.md @@ -21,7 +21,7 @@ the same element and arguments repeatedly if the DOM changes in between calls. When called on an HTML element in an HTML document, `getElementsByTagName` lower-cases the argument before searching for it. This is undesirable when trying to match {{Glossary("camel_case", "camel-cased")}} SVG elements (such as -[`<linearGradient>`](/en-US/docs/Web/SVG/Element/linearGradient)) +[`<linearGradient>`](/en-US/docs/Web/SVG/Reference/Element/linearGradient)) in an HTML document. Instead, use {{ domxref("Element.getElementsByTagNameNS()") }}, which preserves the capitalization of the tag name. diff --git a/files/en-us/web/api/element/gethtml/index.md b/files/en-us/web/api/element/gethtml/index.md index 162a03b52ea4069..b38441ce953420f 100644 --- a/files/en-us/web/api/element/gethtml/index.md +++ b/files/en-us/web/api/element/gethtml/index.md @@ -15,6 +15,9 @@ The options can be used to include nested shadow roots that have been set as {{d Without arguments, child nodes that are shadow roots are not serialized, and this method behaves in the same way as reading the value of {{domxref("Element.innerHTML")}}. +Note that some browsers serialize the `<` and `>` characters as `&lt;` and `&gt;` when they appear in attribute values (see [Browser compatibility](#browser_compatibility)). +This is to prevent a potential security vulnerability ([mutation XSS](https://research.securitum.com/dompurify-bypass-using-mxss/)) in which an attacker can craft input that bypasses a [sanitization function](/en-US/docs/Web/Security/Attacks/XSS#sanitization), enabling a cross-site scripting (XSS) attack. + ## Syntax ```js-nolint diff --git a/files/en-us/web/api/element/gotpointercapture_event/index.md b/files/en-us/web/api/element/gotpointercapture_event/index.md index e7e33242125e1ed..bd32400124dbaee 100644 --- a/files/en-us/web/api/element/gotpointercapture_event/index.md +++ b/files/en-us/web/api/element/gotpointercapture_event/index.md @@ -14,10 +14,10 @@ The **`gotpointercapture`** event is fired when an element captures a pointer us Use the event name in methods like {{domxref("EventTarget.addEventListener", "addEventListener()")}}, or set an event handler property. -```js -addEventListener("gotpointercapture", (event) => {}); +```js-nolint +addEventListener("gotpointercapture", (event) => { }) -ongotpointercapture = (event) => {}; +ongotpointercapture = (event) => { } ``` ## Event type @@ -47,11 +47,11 @@ _This interface inherits properties from {{domxref("MouseEvent")}} and {{domxref - {{domxref('PointerEvent.tangentialPressure')}} {{ReadOnlyInline}} - : The normalized tangential pressure of the pointer input (also known as barrel pressure or [cylinder stress](https://en.wikipedia.org/wiki/Cylinder_stress)) in the range `-1` to `1`, where `0` is the neutral position of the control. - {{domxref('PointerEvent.tiltX')}} {{ReadOnlyInline}} - - : The plane angle (in degrees, in the range of `-90` to `90`) between the Y–Z plane and the plane containing both the pointer (e.g. pen stylus) axis and the Y axis. + - : The plane angle (in degrees, in the range of `-90` to `90`) between the Y–Z plane and the plane containing both the pointer (e.g., pen stylus) axis and the Y axis. - {{domxref('PointerEvent.tiltY')}} {{ReadOnlyInline}} - - : The plane angle (in degrees, in the range of `-90` to `90`) between the X–Z plane and the plane containing both the pointer (e.g. pen stylus) axis and the X axis. + - : The plane angle (in degrees, in the range of `-90` to `90`) between the X–Z plane and the plane containing both the pointer (e.g., pen stylus) axis and the X axis. - {{domxref('PointerEvent.twist')}} {{ReadOnlyInline}} - - : The clockwise rotation of the pointer (e.g. pen stylus) around its major axis in degrees, with a value in the range `0` to `359`. + - : The clockwise rotation of the pointer (e.g., pen stylus) around its major axis in degrees, with a value in the range `0` to `359`. - {{domxref('PointerEvent.pointerType')}} {{ReadOnlyInline}} - : Indicates the device type that caused the event (mouse, pen, touch, etc.). - {{domxref('PointerEvent.isPrimary')}} {{ReadOnlyInline}} diff --git a/files/en-us/web/api/element/id/index.md b/files/en-us/web/api/element/id/index.md index 788705480c805f2..7f7a9e48f2fa917 100644 --- a/files/en-us/web/api/element/id/index.md +++ b/files/en-us/web/api/element/id/index.md @@ -10,7 +10,7 @@ browser-compat: api.Element.id The **`id`** property of the {{domxref("Element")}} interface represents the element's identifier, reflecting the -[**`id`**](/en-US/docs/Web/HTML/Global_attributes/id) +[**`id`**](/en-US/docs/Web/HTML/Reference/Global_attributes/id) global attribute. If the `id` value is not the empty string, it must be unique in a document. @@ -36,5 +36,5 @@ A string. ## See also -- The DOM [**id**](/en-US/docs/Web/HTML/Global_attributes/id) +- The DOM [**id**](/en-US/docs/Web/HTML/Reference/Global_attributes/id) global attribute. diff --git a/files/en-us/web/api/element/index.md b/files/en-us/web/api/element/index.md index 125e905b94b12cc..209d1f903dc7b78 100644 --- a/files/en-us/web/api/element/index.md +++ b/files/en-us/web/api/element/index.md @@ -7,7 +7,7 @@ browser-compat: api.Element {{APIRef("DOM")}} -**`Element`** is the most general base class from which all element objects (i.e. objects that represent elements) in a {{DOMxRef("Document")}} inherit. It only has methods and properties common to all kinds of elements. More specific classes inherit from `Element`. +**`Element`** is the most general base class from which all element objects (i.e., objects that represent elements) in a {{DOMxRef("Document")}} inherit. It only has methods and properties common to all kinds of elements. More specific classes inherit from `Element`. For example, the {{DOMxRef("HTMLElement")}} interface is the base interface for HTML elements. Similarly, the {{DOMxRef("SVGElement")}} interface is the basis for all SVG elements, and the {{DOMxRef("MathMLElement")}} interface is the base interface for MathML elements. Most functionality is specified further down the class hierarchy. @@ -42,7 +42,7 @@ _`Element` inherits properties from its parent interface, {{DOMxRef("Node")}}, a - {{DOMxRef("Element.currentCSSZoom")}} {{ReadOnlyInline}} - : A number indicating the effective zoom size of the element, or 1.0 if the element is not rendered. - {{DOMxRef("Element.elementTiming")}} {{Experimental_Inline}} - - : A string reflecting the [`elementtiming`](/en-US/docs/Web/HTML/Attributes/elementtiming) attribute which marks an element for observation in the {{domxref("PerformanceElementTiming")}} API. + - : A string reflecting the [`elementtiming`](/en-US/docs/Web/HTML/Reference/Attributes/elementtiming) attribute which marks an element for observation in the {{domxref("PerformanceElementTiming")}} API. - {{domxref("Element.firstElementChild")}} {{ReadOnlyInline}} - : Returns the first child element of this element. - {{DOMxRef("Element.id")}} @@ -54,18 +54,13 @@ _`Element` inherits properties from its parent interface, {{DOMxRef("Node")}}, a - {{DOMxRef("Element.localName")}} {{ReadOnlyInline}} - : A string representing the local part of the qualified name of the element. - {{DOMxRef("Element.namespaceURI")}} {{ReadOnlyInline}} - - : The namespace URI of the element, or `null` if it is no namespace. - - > [!NOTE] - > In Firefox 3.5 and earlier, HTML elements are in no namespace. In later versions, HTML elements are in the [`http://www.w3.org/1999/xhtml`](https://www.w3.org/1999/xhtml/) namespace in both HTML and XML trees. - - {{DOMxRef("Element.nextElementSibling")}} {{ReadOnlyInline}} - : An `Element`, the element immediately following the given one in the tree, or `null` if there's no sibling node. - {{DOMxRef("Element.outerHTML")}} - : A string representing the markup of the element including its content. When used as a setter, replaces the element with nodes parsed from the given string. - {{DOMxRef("Element.part")}} - - : Represents the part identifier(s) of the element (i.e. set using the `part` attribute), returned as a {{domxref("DOMTokenList")}}. + - : Represents the part identifier(s) of the element (i.e., set using the `part` attribute), returned as a {{domxref("DOMTokenList")}}. - {{DOMxRef("Element.prefix")}} {{ReadOnlyInline}} - : A string representing the namespace prefix of the element, or `null` if no prefix is specified. - {{DOMxRef("Element.previousElementSibling")}} {{ReadOnlyInline}} @@ -94,89 +89,123 @@ _`Element` inherits properties from its parent interface, {{DOMxRef("Node")}}, a _The `Element` interface also includes the following properties._ - {{domxref("Element.ariaAtomic")}} - - : A string reflecting the [`aria-atomic`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-atomic) attribute, which indicates whether assistive technologies will present all, or only parts of, the changed region based on the change notifications defined by the [`aria-relevant`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-relevant) attribute. + - : A string reflecting the [`aria-atomic`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-atomic) attribute, which indicates whether assistive technologies will present all, or only parts of, the changed region based on the change notifications defined by the [`aria-relevant`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-relevant) attribute. - {{domxref("Element.ariaAutoComplete")}} - - : A string reflecting the [`aria-autocomplete`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-autocomplete) attribute, which indicates whether inputting text could trigger display of one or more predictions of the user's intended value for a combobox, searchbox, or textbox and specifies how predictions would be presented if they were made. + - : A string reflecting the [`aria-autocomplete`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-autocomplete) attribute, which indicates whether inputting text could trigger display of one or more predictions of the user's intended value for a combobox, searchbox, or textbox and specifies how predictions would be presented if they were made. - {{domxref("Element.ariaBrailleLabel")}} - - : A string reflecting the [`aria-braillelabel`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-braillelabel) attribute, which defines the braille label of the element. + - : A string reflecting the [`aria-braillelabel`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-braillelabel) attribute, which defines the braille label of the element. - {{domxref("Element.ariaBrailleRoleDescription")}} - - : A string reflecting the [`aria-brailleroledescription`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-brailleroledescription) attribute, which defines the ARIA braille role description of the element. + - : A string reflecting the [`aria-brailleroledescription`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-brailleroledescription) attribute, which defines the ARIA braille role description of the element. - {{domxref("Element.ariaBusy")}} - - : A string reflecting the [`aria-busy`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-busy) attribute, which indicates whether an element is being modified, as assistive technologies may want to wait until the modifications are complete before exposing them to the user. + - : A string reflecting the [`aria-busy`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-busy) attribute, which indicates whether an element is being modified, as assistive technologies may want to wait until the modifications are complete before exposing them to the user. - {{domxref("Element.ariaChecked")}} - - : A string reflecting the [`aria-checked`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-checked) attribute, which indicates the current "checked" state of checkboxes, radio buttons, and other widgets that have a checked state. + - : A string reflecting the [`aria-checked`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-checked) attribute, which indicates the current "checked" state of checkboxes, radio buttons, and other widgets that have a checked state. - {{domxref("Element.ariaColCount")}} - - : A string reflecting the [`aria-colcount`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-colcount) attribute, which defines the number of columns in a table, grid, or treegrid. + - : A string reflecting the [`aria-colcount`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-colcount) attribute, which defines the number of columns in a table, grid, or treegrid. - {{domxref("Element.ariaColIndex")}} - - : A string reflecting the [`aria-colindex`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-colindex) attribute, which defines an element's column index or position with respect to the total number of columns within a table, grid, or treegrid. + - : A string reflecting the [`aria-colindex`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-colindex) attribute, which defines an element's column index or position with respect to the total number of columns within a table, grid, or treegrid. - {{domxref("Element.ariaColIndexText")}} - - : A string reflecting the [`aria-colindextext`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-colindextext) attribute, which defines a human readable text alternative of aria-colindex. + - : A string reflecting the [`aria-colindextext`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-colindextext) attribute, which defines a human readable text alternative of aria-colindex. - {{domxref("Element.ariaColSpan")}} - - : A string reflecting the [`aria-colspan`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-colspan) attribute, which defines the number of columns spanned by a cell or gridcell within a table, grid, or treegrid. + - : A string reflecting the [`aria-colspan`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-colspan) attribute, which defines the number of columns spanned by a cell or gridcell within a table, grid, or treegrid. - {{domxref("Element.ariaCurrent")}} - - : A string reflecting the [`aria-current`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-current) attribute, which indicates the element that represents the current item within a container or set of related elements. + - : A string reflecting the [`aria-current`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-current) attribute, which indicates the element that represents the current item within a container or set of related elements. - {{domxref("Element.ariaDescription")}} - - : A string reflecting the [`aria-description`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-description) attribute, which defines a string value that describes or annotates the current element. + - : A string reflecting the [`aria-description`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-description) attribute, which defines a string value that describes or annotates the current element. - {{domxref("Element.ariaDisabled")}} - - : A string reflecting the [`aria-disabled`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-disabled) attribute, which indicates that the element is perceivable but disabled, so it is not editable or otherwise operable. + - : A string reflecting the [`aria-disabled`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-disabled) attribute, which indicates that the element is perceivable but disabled, so it is not editable or otherwise operable. - {{domxref("Element.ariaExpanded")}} - - : A string reflecting the [`aria-expanded`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-expanded) attribute, which indicates whether a grouping element owned or controlled by this element is expanded or collapsed. + - : A string reflecting the [`aria-expanded`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-expanded) attribute, which indicates whether a grouping element owned or controlled by this element is expanded or collapsed. - {{domxref("Element.ariaHasPopup")}} - - : A string reflecting the [`aria-haspopup`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-haspopup) attribute, which indicates the availability and type of interactive popup element, such as menu or dialog, that can be triggered by an element. + - : A string reflecting the [`aria-haspopup`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-haspopup) attribute, which indicates the availability and type of interactive popup element, such as menu or dialog, that can be triggered by an element. - {{domxref("Element.ariaHidden")}} - - : A string reflecting the [`aria-hidden`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-hidden) attribute, which indicates whether the element is exposed to an accessibility API. + - : A string reflecting the [`aria-hidden`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-hidden) attribute, which indicates whether the element is exposed to an accessibility API. +- {{domxref("Element.ariaInvalid")}} + - : A string reflecting the [`aria-invalid`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-invalid) attribute, which indicates the entered value does not conform to the format expected by the application. - {{domxref("Element.ariaKeyShortcuts")}} - - : A string reflecting the [`aria-keyshortcuts`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-keyshortcuts) attribute, which indicates keyboard shortcuts that an author has implemented to activate or give focus to an element. + - : A string reflecting the [`aria-keyshortcuts`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-keyshortcuts) attribute, which indicates keyboard shortcuts that an author has implemented to activate or give focus to an element. - {{domxref("Element.ariaLabel")}} - - : A string reflecting the [`aria-label`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-label) attribute, which defines a string value that labels the current element. + - : A string reflecting the [`aria-label`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-label) attribute, which defines a string value that labels the current element. - {{domxref("Element.ariaLevel")}} - - : A string reflecting the [`aria-level`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-level) attribute, which defines the hierarchical level of an element within a structure. + - : A string reflecting the [`aria-level`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-level) attribute, which defines the hierarchical level of an element within a structure. - {{domxref("Element.ariaLive")}} - - : A string reflecting the [`aria-live`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-live) attribute, which indicates that an element will be updated, and describes the types of updates the user agents, assistive technologies, and user can expect from the live region. + - : A string reflecting the [`aria-live`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-live) attribute, which indicates that an element will be updated, and describes the types of updates the user agents, assistive technologies, and user can expect from the live region. - {{domxref("Element.ariaModal")}} - - : A string reflecting the [`aria-modal`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-modal) attribute, which indicates whether an element is modal when displayed. + - : A string reflecting the [`aria-modal`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-modal) attribute, which indicates whether an element is modal when displayed. - {{domxref("Element.ariaMultiline")}} - - : A string reflecting the [`aria-multiline`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-multiline) attribute, which indicates whether a text box accepts multiple lines of input or only a single line. + - : A string reflecting the [`aria-multiline`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-multiline) attribute, which indicates whether a text box accepts multiple lines of input or only a single line. - {{domxref("Element.ariaMultiSelectable")}} - - : A string reflecting the [`aria-multiselectable`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-multiselectable) attribute, which indicates that the user may select more than one item from the current selectable descendants. + - : A string reflecting the [`aria-multiselectable`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-multiselectable) attribute, which indicates that the user may select more than one item from the current selectable descendants. - {{domxref("Element.ariaOrientation")}} - - : A string reflecting the [`aria-orientation`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-orientation) attribute, which indicates whether the element's orientation is horizontal, vertical, or unknown/ambiguous. + - : A string reflecting the [`aria-orientation`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-orientation) attribute, which indicates whether the element's orientation is horizontal, vertical, or unknown/ambiguous. - {{domxref("Element.ariaPlaceholder")}} - - : A string reflecting the [`aria-placeholder`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-placeholder) attribute, which defines a short hint intended to aid the user with data entry when the control has no value. + - : A string reflecting the [`aria-placeholder`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-placeholder) attribute, which defines a short hint intended to aid the user with data entry when the control has no value. - {{domxref("Element.ariaPosInSet")}} - - : A string reflecting the [`aria-posinset`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-posinset) attribute, which defines an element's number or position in the current set of listitems or treeitems. + - : A string reflecting the [`aria-posinset`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-posinset) attribute, which defines an element's number or position in the current set of listitems or treeitems. - {{domxref("Element.ariaPressed")}} - - : A string reflecting the [`aria-pressed`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-pressed) attribute, which indicates the current "pressed" state of toggle buttons. + - : A string reflecting the [`aria-pressed`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-pressed) attribute, which indicates the current "pressed" state of toggle buttons. - {{domxref("Element.ariaReadOnly")}} - - : A string reflecting the [`aria-readonly`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-readonly) attribute, which indicates that the element is not editable, but is otherwise operable. + - : A string reflecting the [`aria-readonly`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-readonly) attribute, which indicates that the element is not editable, but is otherwise operable. - {{domxref("Element.ariaRelevant")}} {{Non-standard_Inline}} - - : A string reflecting the [`aria-relevant`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-relevant) attribute, which indicates what notifications the user agent will trigger when the accessibility tree within a live region is modified. This is used to describe what changes in an `aria-live` region are relevant and should be announced. + - : A string reflecting the [`aria-relevant`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-relevant) attribute, which indicates what notifications the user agent will trigger when the accessibility tree within a live region is modified. This is used to describe what changes in an `aria-live` region are relevant and should be announced. - {{domxref("Element.ariaRequired")}} - - : A string reflecting the [`aria-required`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-required) attribute, which indicates that user input is required on the element before a form may be submitted. + - : A string reflecting the [`aria-required`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-required) attribute, which indicates that user input is required on the element before a form may be submitted. - {{domxref("Element.ariaRoleDescription")}} - - : A string reflecting the [`aria-roledescription`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-roledescription) attribute, which defines a human-readable, author-localized description for the role of an element. + - : A string reflecting the [`aria-roledescription`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-roledescription) attribute, which defines a human-readable, author-localized description for the role of an element. - {{domxref("Element.ariaRowCount")}} - - : A string reflecting the [`aria-rowcount`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-rowcount) attribute, which defines the total number of rows in a table, grid, or treegrid. + - : A string reflecting the [`aria-rowcount`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-rowcount) attribute, which defines the total number of rows in a table, grid, or treegrid. - {{domxref("Element.ariaRowIndex")}} - - : A string reflecting the [`aria-rowindex`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-rowindex) attribute, which defines an element's row index or position with respect to the total number of rows within a table, grid, or treegrid. + - : A string reflecting the [`aria-rowindex`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-rowindex) attribute, which defines an element's row index or position with respect to the total number of rows within a table, grid, or treegrid. - {{domxref("Element.ariaRowIndexText")}} - - : A string reflecting the [`aria-rowindextext`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-rowindextext) attribute, which defines a human readable text alternative of aria-rowindex. + - : A string reflecting the [`aria-rowindextext`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-rowindextext) attribute, which defines a human readable text alternative of aria-rowindex. - {{domxref("Element.ariaRowSpan")}} - - : A string reflecting the [`aria-rowspan`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-rowspan) attribute, which defines the number of rows spanned by a cell or gridcell within a table, grid, or treegrid. + - : A string reflecting the [`aria-rowspan`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-rowspan) attribute, which defines the number of rows spanned by a cell or gridcell within a table, grid, or treegrid. - {{domxref("Element.ariaSelected")}} - - : A string reflecting the [`aria-selected`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-selected) attribute, which indicates the current "selected" state of elements that have a selected state. + - : A string reflecting the [`aria-selected`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-selected) attribute, which indicates the current "selected" state of elements that have a selected state. - {{domxref("Element.ariaSetSize")}} - - : A string reflecting the [`aria-setsize`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-setsize) attribute, which defines the number of items in the current set of listitems or treeitems. + - : A string reflecting the [`aria-setsize`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-setsize) attribute, which defines the number of items in the current set of listitems or treeitems. - {{domxref("Element.ariaSort")}} - - : A string reflecting the [`aria-sort`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-sort) attribute, which indicates if items in a table or grid are sorted in ascending or descending order. + - : A string reflecting the [`aria-sort`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-sort) attribute, which indicates if items in a table or grid are sorted in ascending or descending order. - {{domxref("Element.ariaValueMax")}} - - : A string reflecting the [`aria-valueMax`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-valuemax) attribute, which defines the maximum allowed value for a range widget. + - : A string reflecting the [`aria-valueMax`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-valuemax) attribute, which defines the maximum allowed value for a range widget. - {{domxref("Element.ariaValueMin")}} - - : A string reflecting the [`aria-valueMin`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-valuemin) attribute, which defines the minimum allowed value for a range widget. + - : A string reflecting the [`aria-valueMin`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-valuemin) attribute, which defines the minimum allowed value for a range widget. - {{domxref("Element.ariaValueNow")}} - - : A string reflecting the [`aria-valueNow`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-valuenow) attribute, which defines the current value for a range widget. + - : A string reflecting the [`aria-valueNow`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-valuenow) attribute, which defines the current value for a range widget. - {{domxref("Element.ariaValueText")}} - - : A string reflecting the [`aria-valuetext`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-valuetext) attribute, which defines the human-readable text alternative of aria-valuenow for a range widget. + - : A string reflecting the [`aria-valuetext`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-valuetext) attribute, which defines the human-readable text alternative of `aria-valuenow` for a range widget. +- {{domxref("Element.role")}} + - : A string reflecting the explicitly set [`role`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles) attribute, which provides the semantic role of the element. + +#### Instance properties reflected from ARIA element references + +The properties reflect the elements specified by `id` reference in the corresponding attributes, but with some caveats. See [Reflected element references](/en-US/docs/Web/API/Document_Object_Model/Reflected_attributes#reflected_element_references) in the _Reflected attributes_ guide for more information. + +- {{domxref("Element.ariaActiveDescendantElement")}} + - : An element that represents the current active element when focus is on a [`composite`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/composite_role) widget, [`combobox`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/combobox_role), [`textbox`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/textbox_role), [`group`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/group_role), or [`application`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/application_role). + Reflects the [`aria-activedescendant`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-activedescendant) attribute. +- {{domxref("Element.ariaControlsElements")}} + - : An array of elements whose contents or presence are controlled by the element it is applied to. + Reflects the [`aria-controls`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-controls) attribute. +- {{domxref("Element.ariaDescribedByElements")}} + - : An array of elements that contain the accessible description for the element it is applied to. + Reflects the [`aria-describedby`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-describedby) attribute. +- {{domxref("Element.ariaDetailsElements")}} + - : An array of elements that provide accessible details for the element it is applied to. + Reflects the [`aria-details`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-details) attribute. +- {{domxref("Element.ariaErrorMessageElements")}} + - : An array of elements that provide an error message for the element it is applied to. + Reflects the [`aria-errormessage`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-errormessage) attribute. +- {{domxref("Element.ariaFlowToElements")}} + - : An array of elements that identify the next element (or elements) in an alternate reading order of content, overriding the general default reading order at the user's discretion. + Reflects the [`aria-flowto`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-flowto) attribute. +- {{domxref("Element.ariaLabelledByElements")}} + - : An array of elements that provide the accessible name for the element it is applied to. + Reflects the [`aria-labelledby`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-labelledby) attribute. +- {{domxref("Element.ariaOwnsElements")}} + - : An array of elements owned by the element this is applied to. + This is used to define a visual, functional, or contextual relationship between a parent and its child elements when the DOM hierarchy cannot be used to represent the relationship. + Reflects the [`aria-owns`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-owns) attribute. ## Instance methods @@ -240,6 +269,8 @@ _`Element` inherits methods from its parents {{DOMxRef("Node")}}, and its own pa - : Inserts a given text node at a given position relative to the element it is invoked upon. - {{DOMxRef("Element.matches()")}} - : Returns a boolean value indicating whether or not the element would be selected by the specified selector string. +- {{DOMxRef("Element.moveBefore()")}} {{Experimental_Inline}} + - : Moves a given {{domxref("Node")}} inside the invoking node as a direct child, before a given reference node, without removing and then inserting the node. - {{DOMxRef("Element.prepend()")}} - : Inserts a set of {{domxref("Node")}} objects or strings before the first child of the element. - {{DOMxRef("Element.querySelector()")}} @@ -285,7 +316,7 @@ _`Element` inherits methods from its parents {{DOMxRef("Node")}}, and its own pa - {{DOMxRef("Element.setCapture()")}} {{Non-standard_Inline}} {{Deprecated_Inline}} - : Sets up mouse event capture, redirecting all mouse events to this element. - {{DOMxRef("Element.setHTMLUnsafe()")}} - - : Parses a string of HTML into a document fragment, without sanitization, which then replaces the element's original subtree in the DOM. The HTML string may include declarative shadow roots, which would be parsed as template elements if the HTML was set using [`Element.innerHTML`](#element.innerhtml). + - : Parses a string of HTML into a document fragment, without sanitization, which then replaces the element's original subtree in the DOM. The HTML string may include declarative shadow roots, which would be parsed as template elements if the HTML was set using [`Element.innerHTML`](/en-US/docs/Web/API/Element/innerHTML). - {{DOMxRef("Element.setPointerCapture()")}} - : Designates a specific element as the capture target of future [pointer events](/en-US/docs/Web/API/Pointer_events). - {{DOMxRef("Element.toggleAttribute()")}} @@ -299,8 +330,8 @@ Listen to these events using `addEventListener()` or by assigning an event liste - : Fired when a script has been executed. - {{domxref("Element/beforeinput_event", "beforeinput")}} - : Fired when the value of an input element is about to be modified. -- {{domxref("Element/beforematch_event", "beforematch")}} {{Experimental_Inline}} - - : Fires on an element that is in the [_hidden until found_](/en-US/docs/Web/HTML/Global_attributes/hidden) state, when the browser is about to reveal its content because the user has found the content through the "find in page" feature or through fragment navigation. +- {{domxref("Element/beforematch_event", "beforematch")}} + - : Fires on an element that is in the [_hidden until found_](/en-US/docs/Web/HTML/Reference/Global_attributes/hidden) state, when the browser is about to reveal its content because the user has found the content through the "find in page" feature or through fragment navigation. - {{domxref("Element/beforescriptexecute_event","beforescriptexecute")}} {{Non-standard_Inline}} {{deprecated_inline}} - : Fired when a script is about to be executed. - {{domxref("Element/beforexrselect_event", "beforexrselect")}} {{Experimental_Inline}} @@ -310,7 +341,7 @@ Listen to these events using `addEventListener()` or by assigning an event liste - {{domxref("Element/input_event","input")}} - : Fires when an element's value is changed as a direct result of a user action. - {{domxref("Element/securitypolicyviolation_event","securitypolicyviolation")}} - - : Fired when a [Content Security Policy](/en-US/docs/Web/HTTP/CSP) is violated. + - : Fired when a [Content Security Policy](/en-US/docs/Web/HTTP/Guides/CSP) is violated. - {{domxref("Element/wheel_event","wheel")}} - : Fired when the user rotates a wheel button on a pointing device (typically a mouse). @@ -431,7 +462,7 @@ Listen to these events using `addEventListener()` or by assigning an event liste - : Fired when a pointer is moved out of the _hit test_ boundaries of an element (among other reasons). - {{domxref("Element/pointerover_event", "pointerover")}} - : Fired when a pointer is moved into an element's hit test boundaries. -- {{domxref("Element/pointerrawupdate_event", "pointerrawupdate")}} {{Experimental_Inline}} +- {{domxref("Element/pointerrawupdate_event", "pointerrawupdate")}} - : Fired when a pointer changes any properties that don't fire {{domxref("Element/pointerdown_event", "pointerdown")}} or {{domxref("Element/pointerup_event", "pointerup")}} events. - {{domxref("Element/pointerup_event", "pointerup")}} - : Fired when a pointer is no longer active. @@ -445,7 +476,7 @@ Listen to these events using `addEventListener()` or by assigning an event liste - {{domxref("Element/scrollsnapchange_event", "scrollsnapchange")}} {{experimental_inline}} - : Fired on the scroll container at the end of a scrolling operation when a new scroll snap target has been selected. - {{domxref("Element/scrollsnapchanging_event", "scrollsnapchanging")}} {{experimental_inline}} - - : Fired on the scroll container when the browser determines a new scroll snap target is pending, i.e. it will be selected when the current scroll gesture ends. + - : Fired on the scroll container when the browser determines a new scroll snap target is pending, i.e., it will be selected when the current scroll gesture ends. ### Touch events diff --git a/files/en-us/web/api/element/innerhtml/index.md b/files/en-us/web/api/element/innerhtml/index.md index acbe5bc93ec745f..84b010738f7a8fa 100644 --- a/files/en-us/web/api/element/innerhtml/index.md +++ b/files/en-us/web/api/element/innerhtml/index.md @@ -8,7 +8,7 @@ browser-compat: api.Element.innerHTML {{APIRef("DOM")}} -The {{domxref("Element")}} property **`innerHTML`** gets or sets the HTML or XML markup contained within the element. +The **`innerHTML`** property of the {{domxref("Element")}} interface gets or sets the HTML or XML markup contained within the element. More precisely, `innerHTML` gets a serialization of the nested child DOM elements within the element, or sets HTML or XML that should be parsed to replace the DOM tree within the element. @@ -17,9 +17,12 @@ To insert the HTML into the document rather than replace the contents of an elem The serialization of the DOM tree read from the property does not include {{glossary("shadow tree", "shadow roots")}} — if you want to get a HTML string that includes shadow roots, you must instead use the {{domxref("Element.getHTML()")}} or {{domxref("ShadowRoot.getHTML()")}} methods. Similarly, when setting element content using `innerHTML`, the HTML string is parsed into DOM elements that do not contain shadow roots. -So for example [`<template>`](/en-US/docs/Web/HTML/Element/template) is parsed into as {{domxref("HTMLTemplateElement")}}, whether or not the [`shadowrootmode`](/en-US/docs/Web/HTML/Element/template#shadowrootmode) attribute is specified +So for example [`<template>`](/en-US/docs/Web/HTML/Reference/Elements/template) is parsed into as {{domxref("HTMLTemplateElement")}}, whether or not the [`shadowrootmode`](/en-US/docs/Web/HTML/Reference/Elements/template#shadowrootmode) attribute is specified In order to set an element's contents from an HTML string that includes declarative shadow roots, you must use either {{domxref("Element.setHTMLUnsafe()")}} or {{domxref("ShadowRoot.setHTMLUnsafe()")}}. +Note that some browsers serialize `<` and `>` in attributes as `&lt;` and `&gt;` when reading the HTML (see [Browser compatibility](#browser_compatibility)). +This prevents certain exploits where code becomes executable when serialized and then deserialized into HTML. + ## Value A string containing the HTML serialization of the element's descendants. @@ -42,7 +45,7 @@ Reading `innerHTML` causes the user agent to serialize the HTML or XML fragment The resulting string is returned. ```js -let contents = myElement.innerHTML; +const contents = myElement.innerHTML; ``` This lets you look at the HTML markup of the element's content nodes. @@ -109,7 +112,7 @@ const list = document.getElementById("list"); list.innerHTML += `<li><a href="#">Item ${list.children.length + 1}</a></li>`; ``` -Please note that using `innerHTML` to append HTML elements (e.g. `el.innerHTML += "<a href='…'>link</a>"`) will result in the removal of any previously set event listeners. +Please note that using `innerHTML` to append HTML elements (e.g., `el.innerHTML += "<a href='…'>link</a>"`) will result in the removal of any previously set event listeners. That is, after you append any HTML element that way you won't be able to listen to the previously set event listeners. ### Security considerations diff --git a/files/en-us/web/api/element/input_event/index.md b/files/en-us/web/api/element/input_event/index.md index 9a22043cac7bc22..66384905ef920c0 100644 --- a/files/en-us/web/api/element/input_event/index.md +++ b/files/en-us/web/api/element/input_event/index.md @@ -22,10 +22,10 @@ The `input` event is fired every time the `value` of the element changes. This i Use the event name in methods like {{domxref("EventTarget.addEventListener", "addEventListener()")}}, or set an event handler property. -```js -addEventListener("input", (event) => {}); +```js-nolint +addEventListener("input", (event) => { }) -oninput = (event) => {}; +oninput = (event) => { } ``` ## Event type diff --git a/files/en-us/web/api/element/insertadjacentelement/index.md b/files/en-us/web/api/element/insertadjacentelement/index.md index c9856f67226acc9..a5fea0bce1b9629 100644 --- a/files/en-us/web/api/element/insertadjacentelement/index.md +++ b/files/en-us/web/api/element/insertadjacentelement/index.md @@ -68,31 +68,103 @@ The element that was inserted, or `null`, if the insertion failed. ## Examples +### Inserting before and after + +In this example we have a row of square boxes. The user can select a box by clicking on it: this gives the box a different border, to show that it is selected. + +If a box is selected, and the user presses the "Insert before" or "Insert after" buttons, then the code creates a new box, gives it a random color, and inserts it before or after the selected box. + +#### HTML + +```html +<p> + Click colored box to select it, then use the first two buttons below to insert + elements before and after your selection. +</p> + +<section> + <div></div> + <div></div> + <div></div> + <div></div> +</section> + +<button class="before">Insert before</button> +<button class="after">Insert after</button> +<button class="reset">Reset demo</button> +``` + +#### CSS + +```css +div { + width: 50px; + height: 50px; + margin: 3px; + border: 3px solid black; + display: inline-block; + background-color: red; +} + +.selected { + border-color: aqua; +} +``` + +#### JavaScript + ```js -beforeBtn.addEventListener("click", () => { - const tempDiv = document.createElement("div"); - tempDiv.style.backgroundColor = randomColor(); - if (activeElem) { - activeElem.insertAdjacentElement("beforebegin", tempDiv); +let selectedElem; + +// Function to select a new element +function selectElement(newSelection) { + if (selectedElem !== newSelection) { + if (selectedElem) { + selectedElem.classList.remove("selected"); + } + selectedElem = newSelection; + newSelection.classList.add("selected"); + } +} + +// Add click handlers that select the clicked element +const initElems = Array.from(document.querySelectorAll("section div")); +for (const initElem of initElems) { + initElem.addEventListener("click", (e) => selectElement(e.target)); +} + +// Add click handlers to "beforeBtn" and "afterBtn" +// to insert a new element before/after the selected element +const beforeBtn = document.querySelector(".before"); +const afterBtn = document.querySelector(".after"); +beforeBtn.addEventListener("click", () => insertNewElement("beforebegin")); +afterBtn.addEventListener("click", () => insertNewElement("afterend")); + +function insertNewElement(position) { + function random() { + return Math.floor(Math.random() * 255); } - setListener(tempDiv); -}); - -afterBtn.addEventListener("click", () => { - const tempDiv = document.createElement("div"); - tempDiv.style.backgroundColor = randomColor(); - if (activeElem) { - activeElem.insertAdjacentElement("afterend", tempDiv); + + if (!selectedElem) { + return; } - setListener(tempDiv); -}); + + const newElement = document.createElement("div"); + const randomColor = `rgb(${random(255)} ${random(255)} ${random(255)})`; + newElement.style.backgroundColor = randomColor; + newElement.addEventListener("click", (e) => selectElement(e.target)); + + selectedElem.insertAdjacentElement(position, newElement); +} + +// Reset the example +const resetBtn = document.querySelector(".reset"); +resetBtn.addEventListener("click", () => window.location.reload(true)); ``` -Have a look at our [insertAdjacentElement.html](https://mdn.github.io/dom-examples/insert-adjacent/insertAdjacentElement.html) -demo on GitHub (see the [source code](https://github.com/mdn/dom-examples/blob/main/insert-adjacent/insertAdjacentElement.html) too.) Here, we have a sequence of {{htmlelement("div")}} elements inside a -container. When one is clicked, it becomes selected and you can then press the -_Insert before_ and _Insert after_ buttons to insert new divs before or -after the selected element using `insertAdjacentElement()`. +#### Result + +{{embedlivesample("Inserting before and after", "", "200")}} ## Specifications diff --git a/files/en-us/web/api/element/keydown_event/index.md b/files/en-us/web/api/element/keydown_event/index.md index e191c5c368be258..d8c937c3a013149 100644 --- a/files/en-us/web/api/element/keydown_event/index.md +++ b/files/en-us/web/api/element/keydown_event/index.md @@ -14,7 +14,7 @@ Unlike the deprecated {{domxref("Element/keypress_event", "keypress")}} event, t The `keydown` and [`keyup`](/en-US/docs/Web/API/Element/keyup_event) events provide a code indicating which key is pressed, while `keypress` indicates which character was entered. For example, a lowercase "a" will be reported as 65 by `keydown` and `keyup`, but as 97 by `keypress`. An uppercase "A" is reported as 65 by all events. -The event target of a key event is the currently focused element which is processing the keyboard activity. This includes: {{HTMLElement("input")}}, {{HTMLElement("textarea")}}, anything that is [`contentEditable`](/en-US/docs/Web/HTML/Global_attributes/contenteditable), and anything else that can be interacted with the keyboard, such as {{HTMLElement("a")}}, {{HTMLElement("button")}}, and {{HTMLElement("summary")}}. If no suitable element is in focus, the event target will be the {{HTMLElement("body")}} or the root. The event [bubbles](/en-US/docs/Learn_web_development/Core/Scripting/Event_bubbling). It can reach {{domxref("Document")}} and {{domxref("Window")}}. +The event target of a key event is the currently focused element which is processing the keyboard activity. This includes: {{HTMLElement("input")}}, {{HTMLElement("textarea")}}, anything that is [`contentEditable`](/en-US/docs/Web/HTML/Reference/Global_attributes/contenteditable), and anything else that can be interacted with the keyboard, such as {{HTMLElement("a")}}, {{HTMLElement("button")}}, and {{HTMLElement("summary")}}. If no suitable element is in focus, the event target will be the {{HTMLElement("body")}} or the root. The event [bubbles](/en-US/docs/Learn_web_development/Core/Scripting/Event_bubbling). It can reach {{domxref("Document")}} and {{domxref("Window")}}. The event target might change between different key events. For example, the `keydown` target for pressing the <kbd>Tab</kbd> key would be different from the `keyup` target, because the focus has changed. @@ -22,10 +22,10 @@ The event target might change between different key events. For example, the `ke Use the event name in methods like {{domxref("EventTarget.addEventListener", "addEventListener()")}}, or set an event handler property. -```js -addEventListener("keydown", (event) => {}); +```js-nolint +addEventListener("keydown", (event) => { }) -onkeydown = (event) => {}; +onkeydown = (event) => { } ``` ## Event type diff --git a/files/en-us/web/api/element/keypress_event/index.md b/files/en-us/web/api/element/keypress_event/index.md index 89aa19412312265..afa9a6f356e199f 100644 --- a/files/en-us/web/api/element/keypress_event/index.md +++ b/files/en-us/web/api/element/keypress_event/index.md @@ -21,10 +21,10 @@ The event [bubbles](/en-US/docs/Learn_web_development/Core/Scripting/Event_bubbl Use the event name in methods like {{domxref("EventTarget.addEventListener", "addEventListener()")}}, or set an event handler property. -```js -addEventListener("keypress", (event) => {}); +```js-nolint +addEventListener("keypress", (event) => { }) -onkeypress = (event) => {}; +onkeypress = (event) => { } ``` ## Event type diff --git a/files/en-us/web/api/element/keyup_event/index.md b/files/en-us/web/api/element/keyup_event/index.md index 27ce981b3650499..5da84c8b96e9b97 100644 --- a/files/en-us/web/api/element/keyup_event/index.md +++ b/files/en-us/web/api/element/keyup_event/index.md @@ -12,7 +12,7 @@ The **`keyup`** event is fired when a key is released. The [`keydown`](/en-US/docs/Web/API/Element/keydown_event) and `keyup` events provide a code indicating which key is pressed, while `keypress` indicates which character was entered. For example, a lowercase "a" will be reported as 65 by `keydown` and `keyup`, but as 97 by `keypress`. An uppercase "A" is reported as 65 by all events. -The event target of a key event is the currently focused element which is processing the keyboard activity. This includes: {{HTMLElement("input")}}, {{HTMLElement("textarea")}}, anything that is [`contentEditable`](/en-US/docs/Web/HTML/Global_attributes/contenteditable), and anything else that can be interacted with the keyboard, such as {{HTMLElement("a")}}, {{HTMLElement("button")}}, and {{HTMLElement("summary")}}. If no suitable element is in focus, the event target will be the {{HTMLElement("body")}} or the root. The event [bubbles](/en-US/docs/Learn_web_development/Core/Scripting/Event_bubbling). It can reach {{domxref("Document")}} and {{domxref("Window")}}. +The event target of a key event is the currently focused element which is processing the keyboard activity. This includes: {{HTMLElement("input")}}, {{HTMLElement("textarea")}}, anything that is [`contentEditable`](/en-US/docs/Web/HTML/Reference/Global_attributes/contenteditable), and anything else that can be interacted with the keyboard, such as {{HTMLElement("a")}}, {{HTMLElement("button")}}, and {{HTMLElement("summary")}}. If no suitable element is in focus, the event target will be the {{HTMLElement("body")}} or the root. The event [bubbles](/en-US/docs/Learn_web_development/Core/Scripting/Event_bubbling). It can reach {{domxref("Document")}} and {{domxref("Window")}}. The event target might change between different key events. For example, the `keydown` target for pressing the <kbd>Tab</kbd> key would be different from the `keyup` target, because the focus has changed. @@ -20,10 +20,10 @@ The event target might change between different key events. For example, the `ke Use the event name in methods like {{domxref("EventTarget.addEventListener", "addEventListener()")}}, or set an event handler property. -```js -addEventListener("keyup", (event) => {}); +```js-nolint +addEventListener("keyup", (event) => { }) -onkeyup = (event) => {}; +onkeyup = (event) => { } ``` ## Event type diff --git a/files/en-us/web/api/element/localname/index.md b/files/en-us/web/api/element/localname/index.md index f0a2d296ef6fccb..2d30d677949ec9f 100644 --- a/files/en-us/web/api/element/localname/index.md +++ b/files/en-us/web/api/element/localname/index.md @@ -24,15 +24,15 @@ A string representing the local part of the element's qualified name. <html xmlns="http://www.w3.org/1999/xhtml" xmlns:svg="http://www.w3.org/2000/svg"> <head> - <script type="application/javascript"><![CDATA[ - function test() { - const text = document.getElementById('text'); - const circle = document.getElementById('circle'); - - text.value = "<svg:circle> has:\n" + - "localName = '" + circle.localName + "'\n" + - "namespaceURI = '" + circle.namespaceURI + "'"; - } + <script><![CDATA[ +function test() { + const text = document.getElementById("text"); + const circle = document.getElementById("circle"); + + text.value = `<svg:circle> has: +localName = "${circle.localName}" +namespaceURI = "${circle.namespaceURI}"`; +} ]]></script> </head> <body onload="test()"> @@ -51,16 +51,16 @@ A string representing the local part of the element's qualified name. The local name of a node is that part of the node's qualified name that comes after the colon. Qualified names are typically used in XML as part of the namespace(s) of the particular XML documents. For example, in the qualified name -`ecomm:partners`, `partners` is the local name and -`ecomm` is the prefix: +`comm:partners`, `partners` is the local name and +`comm` is the prefix: ```xml -<ecomm:business id="soda_shop" type="brick_n_mortar" xmlns:ecomm="http://example.com/ecomm"> - <ecomm:partners> - <ecomm:partner id="1001">Tony's Syrup Warehouse - </ecomm:partner> - </ecomm:partner> -</ecomm:business> +<comm:business id="soda_shop" type="brick_n_mortar" xmlns:comm="http://example.com/comm"> + <comm:partners> + <comm:partner id="1001">Tony's Syrup Warehouse + </comm:partner> + </comm:partner> +</comm:business> ``` > [!NOTE] diff --git a/files/en-us/web/api/element/lostpointercapture_event/index.md b/files/en-us/web/api/element/lostpointercapture_event/index.md index bd414fccfc3d1c2..7abc838c21df4d5 100644 --- a/files/en-us/web/api/element/lostpointercapture_event/index.md +++ b/files/en-us/web/api/element/lostpointercapture_event/index.md @@ -14,10 +14,10 @@ The **`lostpointercapture`** event is fired when a [captured pointer](/en-US/doc Use the event name in methods like {{domxref("EventTarget.addEventListener", "addEventListener()")}}, or set an event handler property. -```js -addEventListener("lostpointercapture", (event) => {}); +```js-nolint +addEventListener("lostpointercapture", (event) => { }) -onlostpointercapture = (event) => {}; +onlostpointercapture = (event) => { } ``` ## Event type @@ -47,11 +47,11 @@ _This interface inherits properties from {{domxref("MouseEvent")}} and {{domxref - {{domxref('PointerEvent.tangentialPressure')}} {{ReadOnlyInline}} - : The normalized tangential pressure of the pointer input (also known as barrel pressure or [cylinder stress](https://en.wikipedia.org/wiki/Cylinder_stress)) in the range `-1` to `1`, where `0` is the neutral position of the control. - {{domxref('PointerEvent.tiltX')}} {{ReadOnlyInline}} - - : The plane angle (in degrees, in the range of `-90` to `90`) between the Y–Z plane and the plane containing both the pointer (e.g. pen stylus) axis and the Y axis. + - : The plane angle (in degrees, in the range of `-90` to `90`) between the Y–Z plane and the plane containing both the pointer (e.g., pen stylus) axis and the Y axis. - {{domxref('PointerEvent.tiltY')}} {{ReadOnlyInline}} - - : The plane angle (in degrees, in the range of `-90` to `90`) between the X–Z plane and the plane containing both the pointer (e.g. pen stylus) axis and the X axis. + - : The plane angle (in degrees, in the range of `-90` to `90`) between the X–Z plane and the plane containing both the pointer (e.g., pen stylus) axis and the X axis. - {{domxref('PointerEvent.twist')}} {{ReadOnlyInline}} - - : The clockwise rotation of the pointer (e.g. pen stylus) around its major axis in degrees, with a value in the range `0` to `359`. + - : The clockwise rotation of the pointer (e.g., pen stylus) around its major axis in degrees, with a value in the range `0` to `359`. - {{domxref('PointerEvent.pointerType')}} {{ReadOnlyInline}} - : Indicates the device type that caused the event (mouse, pen, touch, etc.). - {{domxref('PointerEvent.isPrimary')}} {{ReadOnlyInline}} diff --git a/files/en-us/web/api/element/mousedown_event/index.md b/files/en-us/web/api/element/mousedown_event/index.md index 6b0bb90265c4882..a87f120af49ae3a 100644 --- a/files/en-us/web/api/element/mousedown_event/index.md +++ b/files/en-us/web/api/element/mousedown_event/index.md @@ -18,10 +18,10 @@ This behavior is different from {{domxref("Element/pointerdown_event", "pointerd Use the event name in methods like {{domxref("EventTarget.addEventListener", "addEventListener()")}}, or set an event handler property. -```js -addEventListener("mousedown", (event) => {}); +```js-nolint +addEventListener("mousedown", (event) => { }) -onmousedown = (event) => {}; +onmousedown = (event) => { } ``` ## Event type diff --git a/files/en-us/web/api/element/mouseenter_event/index.md b/files/en-us/web/api/element/mouseenter_event/index.md index d90ebf24ee7d7db..05b8e0d0bf9d47c 100644 --- a/files/en-us/web/api/element/mouseenter_event/index.md +++ b/files/en-us/web/api/element/mouseenter_event/index.md @@ -16,10 +16,10 @@ Note that "moving into an element" refers to the element's position in the DOM t Use the event name in methods like {{domxref("EventTarget.addEventListener", "addEventListener()")}}, or set an event handler property. -```js -addEventListener("mouseenter", (event) => {}); +```js-nolint +addEventListener("mouseenter", (event) => { }) -onmouseenter = (event) => {}; +onmouseenter = (event) => { } ``` ## Event type diff --git a/files/en-us/web/api/element/mouseleave_event/index.md b/files/en-us/web/api/element/mouseleave_event/index.md index f720c582d4c7f42..c68d87fa7cc04c8 100644 --- a/files/en-us/web/api/element/mouseleave_event/index.md +++ b/files/en-us/web/api/element/mouseleave_event/index.md @@ -20,10 +20,10 @@ Note that "moving out of an element" refers to the element's position in the DOM Use the event name in methods like {{domxref("EventTarget.addEventListener", "addEventListener()")}}, or set an event handler property. -```js -addEventListener("mouseleave", (event) => {}); +```js-nolint +addEventListener("mouseleave", (event) => { }) -onmouseleave = (event) => {}; +onmouseleave = (event) => { } ``` ## Event type diff --git a/files/en-us/web/api/element/mousemove_event/index.md b/files/en-us/web/api/element/mousemove_event/index.md index 7daa373b617f4f8..37d7d63c19eb681 100644 --- a/files/en-us/web/api/element/mousemove_event/index.md +++ b/files/en-us/web/api/element/mousemove_event/index.md @@ -16,10 +16,10 @@ These events happen whether or not any mouse buttons are pressed. They can fire Use the event name in methods like {{domxref("EventTarget.addEventListener", "addEventListener()")}}, or set an event handler property. -```js -addEventListener("mousemove", (event) => {}); +```js-nolint +addEventListener("mousemove", (event) => { }) -onmousemove = (event) => {}; +onmousemove = (event) => { } ``` ## Event type diff --git a/files/en-us/web/api/element/mouseout_event/index.md b/files/en-us/web/api/element/mouseout_event/index.md index 690011cc614e53e..2b56d4daf94967b 100644 --- a/files/en-us/web/api/element/mouseout_event/index.md +++ b/files/en-us/web/api/element/mouseout_event/index.md @@ -18,10 +18,10 @@ If the target element has child elements, `mouseout` and `mouseover` events fire Use the event name in methods like {{domxref("EventTarget.addEventListener", "addEventListener()")}}, or set an event handler property. -```js -addEventListener("mouseout", (event) => {}); +```js-nolint +addEventListener("mouseout", (event) => { }) -onmouseout = (event) => {}; +onmouseout = (event) => { } ``` ## Event type diff --git a/files/en-us/web/api/element/mouseover_event/index.md b/files/en-us/web/api/element/mouseover_event/index.md index b625d1ad66fa99a..46f2a7250b382e7 100644 --- a/files/en-us/web/api/element/mouseover_event/index.md +++ b/files/en-us/web/api/element/mouseover_event/index.md @@ -16,10 +16,10 @@ If the target element has child elements, `mouseout` and `mouseover` events fire Use the event name in methods like {{domxref("EventTarget.addEventListener", "addEventListener()")}}, or set an event handler property. -```js -addEventListener("mouseover", (event) => {}); +```js-nolint +addEventListener("mouseover", (event) => { }) -onmouseover = (event) => {}; +onmouseover = (event) => { } ``` ## Event type diff --git a/files/en-us/web/api/element/mouseup_event/index.md b/files/en-us/web/api/element/mouseup_event/index.md index 653290952c7ca06..5df7235080ceafb 100644 --- a/files/en-us/web/api/element/mouseup_event/index.md +++ b/files/en-us/web/api/element/mouseup_event/index.md @@ -18,10 +18,10 @@ This behavior is different from {{domxref("Element/pointerup_event", "pointerup" Use the event name in methods like {{domxref("EventTarget.addEventListener", "addEventListener()")}}, or set an event handler property. -```js -addEventListener("mouseup", (event) => {}); +```js-nolint +addEventListener("mouseup", (event) => { }) -onmouseup = (event) => {}; +onmouseup = (event) => { } ``` ## Event type diff --git a/files/en-us/web/api/element/mousewheel_event/index.md b/files/en-us/web/api/element/mousewheel_event/index.md index 4c5dba0276dd1db..69e49d0a4727045 100644 --- a/files/en-us/web/api/element/mousewheel_event/index.md +++ b/files/en-us/web/api/element/mousewheel_event/index.md @@ -20,10 +20,10 @@ The _obsolete_ and _non-standard_ **`mousewheel`** event is fired asynchronously Use the event name in methods like {{domxref("EventTarget.addEventListener", "addEventListener()")}}, or set an event handler property. -```js -addEventListener("mousewheel", (event) => {}); +```js-nolint +addEventListener("mousewheel", (event) => { }) -onmousewheel = (event) => {}; +onmousewheel = (event) => { } ``` ## Event type diff --git a/files/en-us/web/api/element/movebefore/index.md b/files/en-us/web/api/element/movebefore/index.md new file mode 100644 index 000000000000000..114d11dbc9762a4 --- /dev/null +++ b/files/en-us/web/api/element/movebefore/index.md @@ -0,0 +1,284 @@ +--- +title: "Element: moveBefore() method" +short-title: moveBefore() +slug: Web/API/Element/moveBefore +page-type: web-api-instance-method +status: + - experimental +browser-compat: api.Element.moveBefore +--- + +{{APIRef("DOM")}}{{SeeCompatTable}} + +The **`moveBefore()`** method of the {{domxref("Element")}} interface moves a given {{domxref("Node")}} inside the invoking node as a direct child, before a given reference node. + +## Syntax + +```js-nolint +moveBefore(movedNode, referenceNode) +``` + +### Parameters + +- `movedNode` + - : A {{domxref("Node")}} representing the node to be moved. Note that this must be an {{domxref("Element")}} or a {{domxref("CharacterData")}} node. +- `referenceNode` + - : A {{domxref("Node")}} that `movedNode` will be moved before, or `null`. If the value is `null`, `movedNode` is inserted at the end of the invoking node's child nodes. + +### Return value + +None ({{jsxref("undefined")}}). + +### Exceptions + +- `HierarchyRequestError` {{jsxref("TypeError")}} + - : Thrown in any of the following situations: + - The specified `movedNode` is not part of the DOM, and you are trying to move it inside a node that is part of the DOM, or vice versa. + - The specified `movedNode` is an ancestor of the Element `moveBefore()` is being called on. + - You are trying to move `movedNode` between two different documents. + - The specified `movedNode` is not an {{domxref("Element")}} or {{domxref("CharacterData")}} node. +- `NotFoundError` {{jsxref("TypeError")}} + - : The specified `referenceNode` is not a child of the node you are calling `moveBefore()` on, that is, the node you are trying to move `movedNode` inside. +- `TypeError` {{jsxref("TypeError")}} + - : The second argument was not supplied. + +## Description + +The `moveBefore()` method moves a given node to a new place in the DOM. It provides similar functionality to the {{domxref("Node.insertBefore()")}} method, except that it doesn't remove and then reinsert the node. This means that the state of the node (which would be reset if moving it with `insertBefore()` and similar mechanisms) is preserved after the move. This includes: + +- [Animation](/en-US/docs/Web/CSS/CSS_animations) and [transition](/en-US/docs/Web/CSS/CSS_transitions) state. +- {{htmlelement("iframe")}} loading state. +- Interactivity states (for example, {{cssxref(":focus")}} and {{cssxref(":active")}}). +- [Fullscreen](/en-US/docs/Web/API/Fullscreen_API) element state. +- Open/close state of [popovers](/en-US/docs/Web/API/Popover_API). +- Modal state of {{htmlelement("dialog")}} elements (modal dialogs will not be closed). + +The play state of {{htmlelement("video")}} and {{htmlelement("audio")}} elements is not included in the above list, as these elements retain their state when removed and reinserted, regardless of the mechanism used. + +When observing changes to the DOM using a {{domxref("MutationObserver")}}, nodes moved with `moveBefore()` will be recorded with a [removed node](/en-US/docs/Web/API/MutationRecord/removedNodes) and an [added node](/en-US/docs/Web/API/MutationRecord/addedNodes). + +### `moveBefore()` constraints + +There are some constraints to be aware of when using `moveBefore()`: + +- It can only work when moving a node within the same document. +- It won't work if you try to move a node that is not connected to the DOM to an already connected parent, or vice versa. + +In such cases, `moveBefore()` will fail with a `HierarchyRequestError` exception. If the above constraints are requirements for your particular use case, you should use {{domxref("Node.insertBefore()")}} instead, or use [`try...catch`](/en-US/docs/Web/JavaScript/Reference/Statements/try...catch) to handle the errors that arise from such cases. + +### Moving custom elements while preserving state + +Each time a [custom element's](/en-US/docs/Web/API/Web_components/Using_custom_elements) position in the DOM is updated via `Element.moveBefore()`, or similar methods such as {{domxref("Node.insertBefore()")}}, its `disconnectedCallback()` and `connectedCallback()` lifecycle callbacks are fired. Since these callbacks are typically used to implement any required initialization or cleanup code to run at the start or end of the element's lifecycle, running them when the element is moved (rather than removed or inserted) may cause problems with its state. + +You can use the `connectedMoveCallback()` callback to preserve a custom element's state. When using `moveBefore()` to move a custom element, `connectedMoveCallback()` is run instead of `connectedCallback()` and `disconnectedCallback()`. + +See [Moving custom elements](/en-US/docs/Web/API/Web_components/Using_custom_elements#lifecycle_callbacks_and_state-preserving_moves) for further information. + +## Examples + +### Basic `moveBefore()` usage + +In this demo we illustrate basic usage of `moveBefore()`. + +#### HTML + +The HTML features an {{htmlelement("article")}} element containing a {{htmlelement("div")}} element and two {{htmlelement("section")}} elements. The `<div>` contains a {{htmlelement("button")}}, which we later use to move it. + +```html live-sample___movebefore-basic +<article id="wrapper"> + <div id="mover"> + <button>Move me!</button> + </div> + <section id="section1"> + <h2>Section 1</h2> + </section> + <section id="section2"> + <h2>Section 2</h2> + </section> +</article> +``` + +#### CSS + +We provide some rudimentary styling for the look and feel and spacing of the boxes, and use [flexbox](/en-US/docs/Web/CSS/CSS_flexible_box_layout) to center their content. + +```css live-sample___movebefore-basic +#section1, +#section2, +#mover { + width: 200px; + height: 80px; + border: 5px solid rgb(0 0 0 / 0.25); + margin-bottom: 10px; + display: flex; + align-items: center; + justify-content: center; +} + +#section1, +#section2 { + background-color: hotpink; +} + +#mover { + background-color: orange; +} +``` + +#### JavaScript + +In our script, we attach a click event listener to the `<button>` via {{domxref("EventTarget.addEventListener", "addEventListener()")}}. When the button is clicked, we check whether the {{domxref("Element.nextElementSibling", "nextElementSibling")}} of our `mover` `<div>` is the first `<section>` element. If so, we invoke `moveBefore()` on the `wrapper` `<article>` and specify to move the `<div>` before the second `<section>`. If not, we use `moveBefore()` to move the `<div>` before the first `<section>`. + +```js live-sample___movebefore-basic +const wrapper = document.getElementById("wrapper"); +const section1 = document.getElementById("section1"); +const section2 = document.getElementById("section2"); +const mover = document.getElementById("mover"); +const moveBtn = document.querySelector("button"); + +moveBtn.addEventListener("click", () => { + if (mover.nextElementSibling === section1) { + wrapper.moveBefore(mover, section2); + } else { + wrapper.moveBefore(mover, section1); + } +}); +``` + +#### Result + +The rendered example looks like this: + +{{EmbedLiveSample("movebefore-basic", "100%", "300px")}} + +Try clicking the `<button>` a few times and note how it toggles between the two positions. + +### Demonstrating state preservation + +In this demo we provide multiple mechanisms to move a `<div>` element containing a YouTube embed between two different containers, demonstrating how `moveBefore()` preserves the play state of the embed, but the other mechanisms do not. + +#### HTML + +The HTML features an {{htmlelement("article")}} element containing two {{htmlelement("section")}} elements. The first `<section>` element contains a {{htmlelement("div")}} element containing the YouTube embed code. We also have a {{htmlelement("div")}} element containing three {{htmlelement("button")}} elements, to which we will add functionality to move the embed `<div>` between sections via JavaScript later on. + +```html live-sample___movebefore-state +<article id="wrapper"> + <section id="section1"> + <div id="mover"> + <iframe + width="300" + height="200" + src="https://www.youtube.com/embed/XvoENpR9cCQ?si=o2i6MvxugD-O5yyv" + title="YouTube video player" + frameborder="0" + allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture; web-share" + referrerpolicy="strict-origin-when-cross-origin" + allowfullscreen></iframe> + </div> + </section> + <section id="section2"></section> +</article> +<div id="controls"> + <button id="move-before">move with <code>moveBefore()</code></button> + <button id="insertbefore">move with <code>insertBefore()</code></button> + <button id="prepend">move with <code>prepend()</code></button> +</div> +``` + +#### CSS + +We use [flexbox](/en-US/docs/Web/CSS/CSS_flexible_box_layout) for the layout to make the two `<section>` elements sit side-by-side, and space the buttons evenly inside the `controls` `<div>`. + +```css live-sample___movebefore-state +#wrapper, +#controls { + width: 100%; + display: flex; +} + +#wrapper { + margin-bottom: 10px; +} + +section { + flex: 1; + padding: 10px; +} + +#controls { + display: flex; + justify-content: space-around; +} + +#section1 { + background-color: hotpink; +} + +#section2 { + background-color: orange; +} + +#mover { + max-width: 100%; + background-color: black; +} +``` + +#### JavaScript + +In our script, we attach `click` event listeners to each `<button>` via {{domxref("EventTarget.addEventListener", "addEventListener()")}}. When the buttons are clicked, we check which `<section>` element is the {{domxref("Node.parentElement", "parentElement")}} of our embed `<div>`, and then use the relevant function (`moveBefore()`, {{domxref("Node.insertBefore", "insertBefore()")}}, or {{domxref("Element.prepend", "prepend()")}}) to move it inside the _other_ `<section>` element. + +```js live-sample___movebefore-state +const section1 = document.getElementById("section1"); +const section2 = document.getElementById("section2"); +const mover = document.getElementById("mover"); +const moveBeforeBtn = document.getElementById("move-before"); +const insertbeforeBtn = document.getElementById("insertbefore"); +const prependBtn = document.getElementById("prepend"); + +moveBeforeBtn.addEventListener("click", () => { + if (mover.parentElement === section1) { + section2.moveBefore(mover, null); + } else { + section1.moveBefore(mover, null); + } +}); + +insertbeforeBtn.addEventListener("click", () => { + if (mover.parentElement === section1) { + section2.insertBefore(mover, null); + } else { + section1.insertBefore(mover, null); + } +}); + +prependBtn.addEventListener("click", () => { + if (mover.parentElement === section1) { + section2.prepend(mover); + } else { + section1.prepend(mover); + } +}); +``` + +#### Result + +The rendered example looks like this: + +{{EmbedLiveSample("movebefore-state", "100%", "260px")}} + +Try playing the YouTube embed and then clicking each `<button>` a couple of times to toggle the `<div>` element screen position from left to right. Note how, in the case of `insertBefore()` and `prepend()`, the embed state is reset after each move so it needs to be restarted. However, in the case of `moveBefore()`, the state is preserved after each move. + +## Specifications + +{{Specifications}} + +## Browser compatibility + +{{Compat}} + +## See also + +- {{domxref("Document.moveBefore()")}} +- {{domxref("DocumentFragment.moveBefore()")}} +- {{domxref("Node.insertBefore()")}} diff --git a/files/en-us/web/api/element/mozmousepixelscroll_event/index.md b/files/en-us/web/api/element/mozmousepixelscroll_event/index.md index facfed09c3b44b4..880b8ee691e83f0 100644 --- a/files/en-us/web/api/element/mozmousepixelscroll_event/index.md +++ b/files/en-us/web/api/element/mozmousepixelscroll_event/index.md @@ -20,10 +20,10 @@ The Firefox-only, _non-standard_, and _obsolete_ **`MozMousePixelScroll`** event Use the event name in methods like {{domxref("EventTarget.addEventListener", "addEventListener()")}}, or set an event handler property. -```js -addEventListener("MozMousePixelScroll", (event) => {}); +```js-nolint +addEventListener("MozMousePixelScroll", (event) => { }) -onMozMousePixelScroll = (event) => {}; +onMozMousePixelScroll = (event) => { } ``` ## Event type diff --git a/files/en-us/web/api/element/outerhtml/index.md b/files/en-us/web/api/element/outerhtml/index.md index ce245285370324e..63185cd428546eb 100644 --- a/files/en-us/web/api/element/outerhtml/index.md +++ b/files/en-us/web/api/element/outerhtml/index.md @@ -9,32 +9,27 @@ browser-compat: api.Element.outerHTML {{APIRef("DOM")}} The **`outerHTML`** attribute of the {{ domxref("Element") }} -DOM interface gets the serialized HTML fragment describing the element including its -descendants. It can also be set to replace the element with nodes parsed from the given -string. +DOM interface gets the serialized HTML fragment describing the element including its descendants. +It can also be set to replace the element with nodes parsed from the given string. -To only obtain the HTML representation of the contents of an element, or to replace the -contents of an element, use the {{domxref("Element.innerHTML", "innerHTML")}} property -instead. +To only obtain the HTML representation of the contents of an element, or to replace the contents of an element, use the {{domxref("Element.innerHTML", "innerHTML")}} property instead. + +Note that some browsers serialize `<` and `>` in attributes as `&lt;` and `&gt;` when reading the HTML (see [Browser compatibility](#browser_compatibility)). +This prevents certain exploits where code becomes executable when serialized and then deserialized into HTML. ## Value -Reading the value of `outerHTML` returns a string -containing an HTML serialization of the `element` and its descendants. -Setting the value of `outerHTML` replaces the element and all of its -descendants with a new DOM tree constructed by parsing the specified -`htmlString`. +Reading the value of `outerHTML` returns a string containing an HTML serialization of the `element` and its descendants. +Setting the value of `outerHTML` replaces the element and all of its descendants with a new DOM tree constructed by parsing the specified `htmlString`. When set to the `null` value, that `null` value is converted to the empty string (`""`), so `elt.outerHTML = null` is equivalent to `elt.outerHTML = ""`. ### Exceptions - `SyntaxError` {{domxref("DOMException")}} - - : Thrown if an attempt was made to set `outerHTML` using an HTML string which is not - valid. + - : Thrown if an attempt was made to set `outerHTML` using an HTML string which is not valid. - `NoModificationAllowedError` {{domxref("DOMException")}} - - : Thrown if an attempt was made to set `outerHTML` on an element which is a direct - child of a {{domxref("Document")}}, such as {{domxref("Document.documentElement")}}. + - : Thrown if an attempt was made to set `outerHTML` on an element which is a direct child of a {{domxref("Document")}}, such as {{domxref("Document.documentElement")}}. ## Examples diff --git a/files/en-us/web/api/element/part/index.md b/files/en-us/web/api/element/part/index.md index a44202596e32a3c..bd43fd03c3c9d36 100644 --- a/files/en-us/web/api/element/part/index.md +++ b/files/en-us/web/api/element/part/index.md @@ -9,7 +9,7 @@ browser-compat: api.Element.part {{ ApiRef("DOM") }} The **`part`** property of the {{domxref("Element")}} interface -represents the part identifier(s) of the element (i.e. set using the `part` +represents the part identifier(s) of the element (i.e., set using the `part` attribute), returned as a {{domxref("DOMTokenList")}}. These can be used to style parts of a shadow DOM, via the {{cssxref("::part")}} pseudo-element. @@ -57,4 +57,4 @@ tabs.forEach((tab) => { ## See also - {{cssxref("::part")}} -- [part](/en-US/docs/Web/HTML/Global_attributes/part) +- [part](/en-US/docs/Web/HTML/Reference/Global_attributes/part) diff --git a/files/en-us/web/api/element/paste_event/index.md b/files/en-us/web/api/element/paste_event/index.md index c30cef7dab03f7a..370e44fbe24d0fa 100644 --- a/files/en-us/web/api/element/paste_event/index.md +++ b/files/en-us/web/api/element/paste_event/index.md @@ -10,7 +10,7 @@ browser-compat: api.Element.paste_event The **`paste`** event of the [Clipboard API](/en-US/docs/Web/API/Clipboard_API) is fired when the user has initiated a "paste" action through the browser's user interface. -If the cursor is in an editable context (for example, in a {{HTMLElement("textarea")}} or an element with [`contenteditable`](/en-US/docs/Web/HTML/Global_attributes/contenteditable) attribute set to `true`) then the default action is to insert the contents of the clipboard into the document at the cursor position. +If the cursor is in an editable context (for example, in a {{HTMLElement("textarea")}} or an element with [`contenteditable`](/en-US/docs/Web/HTML/Reference/Global_attributes/contenteditable) attribute set to `true`) then the default action is to insert the contents of the clipboard into the document at the cursor position. A handler for this event can access the clipboard contents by calling {{domxref("DataTransfer/getData", "getData()")}} on the event's `clipboardData` property. @@ -18,16 +18,16 @@ To override the default behavior (for example to insert some different data or a It's possible to construct and dispatch a [synthetic](/en-US/docs/Web/Events/Creating_and_triggering_events) `paste` event, but this will not affect the document's contents. -This event [bubbles](/en-US/docs/Learn_web_development/Core/Scripting/Event_bubbling), is [cancelable](/en-US/docs/Web/API/Event/cancelable) and is [composed](/en-US/docs/Web/API/Event/composed). +This event [bubbles](/en-US/docs/Learn_web_development/Core/Scripting/Event_bubbling) up the DOM tree, eventually to {{domxref("Document")}} and {{domxref("Window")}}, is [cancelable](/en-US/docs/Web/API/Event/cancelable) and is [composed](/en-US/docs/Web/API/Event/composed). ## Syntax Use the event name in methods like {{domxref("EventTarget.addEventListener", "addEventListener()")}}, or set an event handler property. -```js -addEventListener("paste", (event) => {}); +```js-nolint +addEventListener("paste", (event) => { }) -onpaste = (event) => {}; +onpaste = (event) => { } ``` ## Event type @@ -90,6 +90,5 @@ target.addEventListener("paste", (event) => { ## See also -- Related events: {{domxref("Element/cut_event", "cut")}}, {{domxref("Element/copy_event", "copy")}} -- This event on {{domxref("Document")}} targets: {{domxref("Document/paste_event", "paste")}} -- This event on {{domxref("Window")}} targets: {{domxref("Window/paste_event", "paste")}} +- {{domxref("Element/cut_event", "cut")}} event +- {{domxref("Element/copy_event", "copy")}} event diff --git a/files/en-us/web/api/element/pointercancel_event/index.md b/files/en-us/web/api/element/pointercancel_event/index.md index 10b83bc1852b548..756bab15ca15249 100644 --- a/files/en-us/web/api/element/pointercancel_event/index.md +++ b/files/en-us/web/api/element/pointercancel_event/index.md @@ -25,10 +25,10 @@ Some examples of situations that will trigger a `pointercancel` event: Use the event name in methods like {{domxref("EventTarget.addEventListener", "addEventListener()")}}, or set an event handler property. -```js -addEventListener("pointercancel", (event) => {}); +```js-nolint +addEventListener("pointercancel", (event) => { }) -onpointercancel = (event) => {}; +onpointercancel = (event) => { } ``` ## Event type @@ -58,11 +58,11 @@ _This interface inherits properties from {{domxref("MouseEvent")}} and {{domxref - {{domxref('PointerEvent.tangentialPressure')}} {{ReadOnlyInline}} - : The normalized tangential pressure of the pointer input (also known as barrel pressure or [cylinder stress](https://en.wikipedia.org/wiki/Cylinder_stress)) in the range `-1` to `1`, where `0` is the neutral position of the control. - {{domxref('PointerEvent.tiltX')}} {{ReadOnlyInline}} - - : The plane angle (in degrees, in the range of `-90` to `90`) between the Y–Z plane and the plane containing both the pointer (e.g. pen stylus) axis and the Y axis. + - : The plane angle (in degrees, in the range of `-90` to `90`) between the Y–Z plane and the plane containing both the pointer (e.g., pen stylus) axis and the Y axis. - {{domxref('PointerEvent.tiltY')}} {{ReadOnlyInline}} - - : The plane angle (in degrees, in the range of `-90` to `90`) between the X–Z plane and the plane containing both the pointer (e.g. pen stylus) axis and the X axis. + - : The plane angle (in degrees, in the range of `-90` to `90`) between the X–Z plane and the plane containing both the pointer (e.g., pen stylus) axis and the X axis. - {{domxref('PointerEvent.twist')}} {{ReadOnlyInline}} - - : The clockwise rotation of the pointer (e.g. pen stylus) around its major axis in degrees, with a value in the range `0` to `359`. + - : The clockwise rotation of the pointer (e.g., pen stylus) around its major axis in degrees, with a value in the range `0` to `359`. - {{domxref('PointerEvent.pointerType')}} {{ReadOnlyInline}} - : Indicates the device type that caused the event (mouse, pen, touch, etc.). - {{domxref('PointerEvent.isPrimary')}} {{ReadOnlyInline}} diff --git a/files/en-us/web/api/element/pointerdown_event/index.md b/files/en-us/web/api/element/pointerdown_event/index.md index 42c800e8b84625f..f321f2dd0d285b4 100644 --- a/files/en-us/web/api/element/pointerdown_event/index.md +++ b/files/en-us/web/api/element/pointerdown_event/index.md @@ -19,10 +19,10 @@ This behavior is different from {{domxref("Element/mousedown_event", "mousedown" Use the event name in methods like {{domxref("EventTarget.addEventListener", "addEventListener()")}}, or set an event handler property. -```js -addEventListener("pointerdown", (event) => {}); +```js-nolint +addEventListener("pointerdown", (event) => { }) -onpointerdown = (event) => {}; +onpointerdown = (event) => { } ``` ## Event type @@ -52,11 +52,11 @@ _This interface inherits properties from {{domxref("MouseEvent")}} and {{domxref - {{domxref('PointerEvent.tangentialPressure')}} {{ReadOnlyInline}} - : The normalized tangential pressure of the pointer input (also known as barrel pressure or [cylinder stress](https://en.wikipedia.org/wiki/Cylinder_stress)) in the range `-1` to `1`, where `0` is the neutral position of the control. - {{domxref('PointerEvent.tiltX')}} {{ReadOnlyInline}} - - : The plane angle (in degrees, in the range of `-90` to `90`) between the Y–Z plane and the plane containing both the pointer (e.g. pen stylus) axis and the Y axis. + - : The plane angle (in degrees, in the range of `-90` to `90`) between the Y–Z plane and the plane containing both the pointer (e.g., pen stylus) axis and the Y axis. - {{domxref('PointerEvent.tiltY')}} {{ReadOnlyInline}} - - : The plane angle (in degrees, in the range of `-90` to `90`) between the X–Z plane and the plane containing both the pointer (e.g. pen stylus) axis and the X axis. + - : The plane angle (in degrees, in the range of `-90` to `90`) between the X–Z plane and the plane containing both the pointer (e.g., pen stylus) axis and the X axis. - {{domxref('PointerEvent.twist')}} {{ReadOnlyInline}} - - : The clockwise rotation of the pointer (e.g. pen stylus) around its major axis in degrees, with a value in the range `0` to `359`. + - : The clockwise rotation of the pointer (e.g., pen stylus) around its major axis in degrees, with a value in the range `0` to `359`. - {{domxref('PointerEvent.pointerType')}} {{ReadOnlyInline}} - : Indicates the device type that caused the event (mouse, pen, touch, etc.). - {{domxref('PointerEvent.isPrimary')}} {{ReadOnlyInline}} diff --git a/files/en-us/web/api/element/pointerenter_event/index.md b/files/en-us/web/api/element/pointerenter_event/index.md index fbfbebc2a6a6760..20064f87a665389 100644 --- a/files/en-us/web/api/element/pointerenter_event/index.md +++ b/files/en-us/web/api/element/pointerenter_event/index.md @@ -14,10 +14,10 @@ The `pointerenter` event fires when a pointing device is moved into the hit test Use the event name in methods like {{domxref("EventTarget.addEventListener", "addEventListener()")}}, or set an event handler property. -```js -addEventListener("pointerenter", (event) => {}); +```js-nolint +addEventListener("pointerenter", (event) => { }) -onpointerenter = (event) => {}; +onpointerenter = (event) => { } ``` ## Event type @@ -47,11 +47,11 @@ _This interface inherits properties from {{domxref("MouseEvent")}} and {{domxref - {{domxref('PointerEvent.tangentialPressure')}} {{ReadOnlyInline}} - : The normalized tangential pressure of the pointer input (also known as barrel pressure or [cylinder stress](https://en.wikipedia.org/wiki/Cylinder_stress)) in the range `-1` to `1`, where `0` is the neutral position of the control. - {{domxref('PointerEvent.tiltX')}} {{ReadOnlyInline}} - - : The plane angle (in degrees, in the range of `-90` to `90`) between the Y–Z plane and the plane containing both the pointer (e.g. pen stylus) axis and the Y axis. + - : The plane angle (in degrees, in the range of `-90` to `90`) between the Y–Z plane and the plane containing both the pointer (e.g., pen stylus) axis and the Y axis. - {{domxref('PointerEvent.tiltY')}} {{ReadOnlyInline}} - - : The plane angle (in degrees, in the range of `-90` to `90`) between the X–Z plane and the plane containing both the pointer (e.g. pen stylus) axis and the X axis. + - : The plane angle (in degrees, in the range of `-90` to `90`) between the X–Z plane and the plane containing both the pointer (e.g., pen stylus) axis and the X axis. - {{domxref('PointerEvent.twist')}} {{ReadOnlyInline}} - - : The clockwise rotation of the pointer (e.g. pen stylus) around its major axis in degrees, with a value in the range `0` to `359`. + - : The clockwise rotation of the pointer (e.g., pen stylus) around its major axis in degrees, with a value in the range `0` to `359`. - {{domxref('PointerEvent.pointerType')}} {{ReadOnlyInline}} - : Indicates the device type that caused the event (mouse, pen, touch, etc.). - {{domxref('PointerEvent.isPrimary')}} {{ReadOnlyInline}} diff --git a/files/en-us/web/api/element/pointerleave_event/index.md b/files/en-us/web/api/element/pointerleave_event/index.md index 3d7e77ffedb9294..4d9dc8a2dfdd898 100644 --- a/files/en-us/web/api/element/pointerleave_event/index.md +++ b/files/en-us/web/api/element/pointerleave_event/index.md @@ -14,10 +14,10 @@ The `pointerleave` event is fired when a pointing device is moved out of the hit Use the event name in methods like {{domxref("EventTarget.addEventListener", "addEventListener()")}}, or set an event handler property. -```js -addEventListener("pointerleave", (event) => {}); +```js-nolint +addEventListener("pointerleave", (event) => { }) -onpointerleave = (event) => {}; +onpointerleave = (event) => { } ``` ## Event type @@ -47,11 +47,11 @@ _This interface inherits properties from {{domxref("MouseEvent")}} and {{domxref - {{domxref('PointerEvent.tangentialPressure')}} {{ReadOnlyInline}} - : The normalized tangential pressure of the pointer input (also known as barrel pressure or [cylinder stress](https://en.wikipedia.org/wiki/Cylinder_stress)) in the range `-1` to `1`, where `0` is the neutral position of the control. - {{domxref('PointerEvent.tiltX')}} {{ReadOnlyInline}} - - : The plane angle (in degrees, in the range of `-90` to `90`) between the Y–Z plane and the plane containing both the pointer (e.g. pen stylus) axis and the Y axis. + - : The plane angle (in degrees, in the range of `-90` to `90`) between the Y–Z plane and the plane containing both the pointer (e.g., pen stylus) axis and the Y axis. - {{domxref('PointerEvent.tiltY')}} {{ReadOnlyInline}} - - : The plane angle (in degrees, in the range of `-90` to `90`) between the X–Z plane and the plane containing both the pointer (e.g. pen stylus) axis and the X axis. + - : The plane angle (in degrees, in the range of `-90` to `90`) between the X–Z plane and the plane containing both the pointer (e.g., pen stylus) axis and the X axis. - {{domxref('PointerEvent.twist')}} {{ReadOnlyInline}} - - : The clockwise rotation of the pointer (e.g. pen stylus) around its major axis in degrees, with a value in the range `0` to `359`. + - : The clockwise rotation of the pointer (e.g., pen stylus) around its major axis in degrees, with a value in the range `0` to `359`. - {{domxref('PointerEvent.pointerType')}} {{ReadOnlyInline}} - : Indicates the device type that caused the event (mouse, pen, touch, etc.). - {{domxref('PointerEvent.isPrimary')}} {{ReadOnlyInline}} diff --git a/files/en-us/web/api/element/pointermove_event/index.md b/files/en-us/web/api/element/pointermove_event/index.md index 62cb2fbc2a473e0..968688b1c5fcd66 100644 --- a/files/en-us/web/api/element/pointermove_event/index.md +++ b/files/en-us/web/api/element/pointermove_event/index.md @@ -16,10 +16,10 @@ These events happen whether or not any pointer buttons are pressed. They can fir Use the event name in methods like {{domxref("EventTarget.addEventListener", "addEventListener()")}}, or set an event handler property. -```js -addEventListener("pointermove", (event) => {}); +```js-nolint +addEventListener("pointermove", (event) => { }) -onpointermove = (event) => {}; +onpointermove = (event) => { } ``` ## Event type @@ -49,11 +49,11 @@ _This interface inherits properties from {{domxref("MouseEvent")}} and {{domxref - {{domxref('PointerEvent.tangentialPressure')}} {{ReadOnlyInline}} - : The normalized tangential pressure of the pointer input (also known as barrel pressure or [cylinder stress](https://en.wikipedia.org/wiki/Cylinder_stress)) in the range `-1` to `1`, where `0` is the neutral position of the control. - {{domxref('PointerEvent.tiltX')}} {{ReadOnlyInline}} - - : The plane angle (in degrees, in the range of `-90` to `90`) between the Y–Z plane and the plane containing both the pointer (e.g. pen stylus) axis and the Y axis. + - : The plane angle (in degrees, in the range of `-90` to `90`) between the Y–Z plane and the plane containing both the pointer (e.g., pen stylus) axis and the Y axis. - {{domxref('PointerEvent.tiltY')}} {{ReadOnlyInline}} - - : The plane angle (in degrees, in the range of `-90` to `90`) between the X–Z plane and the plane containing both the pointer (e.g. pen stylus) axis and the X axis. + - : The plane angle (in degrees, in the range of `-90` to `90`) between the X–Z plane and the plane containing both the pointer (e.g., pen stylus) axis and the X axis. - {{domxref('PointerEvent.twist')}} {{ReadOnlyInline}} - - : The clockwise rotation of the pointer (e.g. pen stylus) around its major axis in degrees, with a value in the range `0` to `359`. + - : The clockwise rotation of the pointer (e.g., pen stylus) around its major axis in degrees, with a value in the range `0` to `359`. - {{domxref('PointerEvent.pointerType')}} {{ReadOnlyInline}} - : Indicates the device type that caused the event (mouse, pen, touch, etc.). - {{domxref('PointerEvent.isPrimary')}} {{ReadOnlyInline}} diff --git a/files/en-us/web/api/element/pointerout_event/index.md b/files/en-us/web/api/element/pointerout_event/index.md index bcb6cb8e17b03a7..2a477e03d396019 100644 --- a/files/en-us/web/api/element/pointerout_event/index.md +++ b/files/en-us/web/api/element/pointerout_event/index.md @@ -16,10 +16,10 @@ The `pointerout` event is fired for several reasons including: pointing device i Use the event name in methods like {{domxref("EventTarget.addEventListener", "addEventListener()")}}, or set an event handler property. -```js -addEventListener("pointerout", (event) => {}); +```js-nolint +addEventListener("pointerout", (event) => { }) -onpointerout = (event) => {}; +onpointerout = (event) => { } ``` ## Event type @@ -49,11 +49,11 @@ _This interface inherits properties from {{domxref("MouseEvent")}} and {{domxref - {{domxref('PointerEvent.tangentialPressure')}} {{ReadOnlyInline}} - : The normalized tangential pressure of the pointer input (also known as barrel pressure or [cylinder stress](https://en.wikipedia.org/wiki/Cylinder_stress)) in the range `-1` to `1`, where `0` is the neutral position of the control. - {{domxref('PointerEvent.tiltX')}} {{ReadOnlyInline}} - - : The plane angle (in degrees, in the range of `-90` to `90`) between the Y–Z plane and the plane containing both the pointer (e.g. pen stylus) axis and the Y axis. + - : The plane angle (in degrees, in the range of `-90` to `90`) between the Y–Z plane and the plane containing both the pointer (e.g., pen stylus) axis and the Y axis. - {{domxref('PointerEvent.tiltY')}} {{ReadOnlyInline}} - - : The plane angle (in degrees, in the range of `-90` to `90`) between the X–Z plane and the plane containing both the pointer (e.g. pen stylus) axis and the X axis. + - : The plane angle (in degrees, in the range of `-90` to `90`) between the X–Z plane and the plane containing both the pointer (e.g., pen stylus) axis and the X axis. - {{domxref('PointerEvent.twist')}} {{ReadOnlyInline}} - - : The clockwise rotation of the pointer (e.g. pen stylus) around its major axis in degrees, with a value in the range `0` to `359`. + - : The clockwise rotation of the pointer (e.g., pen stylus) around its major axis in degrees, with a value in the range `0` to `359`. - {{domxref('PointerEvent.pointerType')}} {{ReadOnlyInline}} - : Indicates the device type that caused the event (mouse, pen, touch, etc.). - {{domxref('PointerEvent.isPrimary')}} {{ReadOnlyInline}} diff --git a/files/en-us/web/api/element/pointerover_event/index.md b/files/en-us/web/api/element/pointerover_event/index.md index 49ca9923f7e7742..5aa913bf6539d0e 100644 --- a/files/en-us/web/api/element/pointerover_event/index.md +++ b/files/en-us/web/api/element/pointerover_event/index.md @@ -16,10 +16,10 @@ The `pointerover` event is fired when a pointing device is moved into an element Use the event name in methods like {{domxref("EventTarget.addEventListener", "addEventListener()")}}, or set an event handler property. -```js -addEventListener("pointerover", (event) => {}); +```js-nolint +addEventListener("pointerover", (event) => { }) -onpointerover = (event) => {}; +onpointerover = (event) => { } ``` ## Event type @@ -49,11 +49,11 @@ _This interface inherits properties from {{domxref("MouseEvent")}} and {{domxref - {{domxref('PointerEvent.tangentialPressure')}} {{ReadOnlyInline}} - : The normalized tangential pressure of the pointer input (also known as barrel pressure or [cylinder stress](https://en.wikipedia.org/wiki/Cylinder_stress)) in the range `-1` to `1`, where `0` is the neutral position of the control. - {{domxref('PointerEvent.tiltX')}} {{ReadOnlyInline}} - - : The plane angle (in degrees, in the range of `-90` to `90`) between the Y–Z plane and the plane containing both the pointer (e.g. pen stylus) axis and the Y axis. + - : The plane angle (in degrees, in the range of `-90` to `90`) between the Y–Z plane and the plane containing both the pointer (e.g., pen stylus) axis and the Y axis. - {{domxref('PointerEvent.tiltY')}} {{ReadOnlyInline}} - - : The plane angle (in degrees, in the range of `-90` to `90`) between the X–Z plane and the plane containing both the pointer (e.g. pen stylus) axis and the X axis. + - : The plane angle (in degrees, in the range of `-90` to `90`) between the X–Z plane and the plane containing both the pointer (e.g., pen stylus) axis and the X axis. - {{domxref('PointerEvent.twist')}} {{ReadOnlyInline}} - - : The clockwise rotation of the pointer (e.g. pen stylus) around its major axis in degrees, with a value in the range `0` to `359`. + - : The clockwise rotation of the pointer (e.g., pen stylus) around its major axis in degrees, with a value in the range `0` to `359`. - {{domxref('PointerEvent.pointerType')}} {{ReadOnlyInline}} - : Indicates the device type that caused the event (mouse, pen, touch, etc.). - {{domxref('PointerEvent.isPrimary')}} {{ReadOnlyInline}} diff --git a/files/en-us/web/api/element/pointerrawupdate_event/index.md b/files/en-us/web/api/element/pointerrawupdate_event/index.md index 75df761421d352e..7e50ac441ca0215 100644 --- a/files/en-us/web/api/element/pointerrawupdate_event/index.md +++ b/files/en-us/web/api/element/pointerrawupdate_event/index.md @@ -3,30 +3,31 @@ title: "Element: pointerrawupdate event" short-title: pointerrawupdate slug: Web/API/Element/pointerrawupdate_event page-type: web-api-event -status: - - experimental browser-compat: api.Element.pointerrawupdate_event --- -{{APIRef}}{{SeeCompatTable}}{{secureContext_header}} +{{APIRef}}{{secureContext_header}} -The **`pointerrawupdate`** {{DOMxRef('PointerEvent')}} is fired when a pointer changes any properties that don't fire {{domxref('Element/pointerdown_event', 'pointerdown')}} or {{domxref('Element/pointerup_event', 'pointerup')}} events. +The **`pointerrawupdate`** event is fired when a pointer changes any properties that don't fire {{domxref('Element/pointerdown_event', 'pointerdown')}} or {{domxref('Element/pointerup_event', 'pointerup')}} events. See {{domxref('Element/pointermove_event', 'pointermove')}} for a list of these properties. The `pointerrawupdate` event may have coalesced events if there is already another `pointerrawupdate` event with the same pointer ID that hasn't been dispatched in the event loop. -For information on coalesced events, see the {{domxref("PointerEvent.getCoalescedEvents")}} documentation. +For information on coalesced events, see the {{domxref("PointerEvent.getCoalescedEvents()")}} documentation. -Listeners for `pointerrawupdate` events should only be added if your JavaScript needs high-frequency events and can handle them as quickly as they are dispatched. -For most use cases, other pointer event types should suffice as there may be performance implications to adding listeners for `pointerrawupdate` events. +`pointerrawupdate` is intended for applications that require high-precision input handling and cannot achieve smooth interaction using coalesced [`pointermove`](/en-US/docs/Web/API/Element/pointermove_event) events alone. +However, because listening to `pointerrawupdate` events can affect performance, you should add these listeners only if your JavaScript needs high-frequency events and can handle them as quickly as they are dispatched. +For most use cases, other pointer event types should suffice. + +This event [bubbles](/en-US/docs/Learn_web_development/Core/Scripting/Event_bubbling) and is [composed](/en-US/docs/Web/API/Event/composed), but is not [cancelable](/en-US/docs/Web/API/Event/cancelable) and has no default action. ## Syntax Use the event name in methods like {{domxref("EventTarget.addEventListener", "addEventListener()")}}, or set an event handler property. -```js -addEventListener("pointerrawupdate", (event) => {}); +```js-nolint +addEventListener("pointerrawupdate", (event) => { }) -onpointerrawupdate = (event) => {}; +onpointerrawupdate = (event) => { } ``` ## Event type @@ -56,11 +57,11 @@ _This interface inherits properties from {{domxref("MouseEvent")}} and {{domxref - {{domxref('PointerEvent.tangentialPressure')}} {{ReadOnlyInline}} - : The normalized tangential pressure of the pointer input (also known as barrel pressure or [cylinder stress](https://en.wikipedia.org/wiki/Cylinder_stress)) in the range `-1` to `1`, where `0` is the neutral position of the control. - {{domxref('PointerEvent.tiltX')}} {{ReadOnlyInline}} - - : The plane angle (in degrees, in the range of `-90` to `90`) between the Y–Z plane and the plane containing both the pointer (e.g. pen stylus) axis and the Y axis. + - : The plane angle (in degrees, in the range of `-90` to `90`) between the Y–Z plane and the plane containing both the pointer (e.g., pen stylus) axis and the Y axis. - {{domxref('PointerEvent.tiltY')}} {{ReadOnlyInline}} - - : The plane angle (in degrees, in the range of `-90` to `90`) between the X–Z plane and the plane containing both the pointer (e.g. pen stylus) axis and the X axis. + - : The plane angle (in degrees, in the range of `-90` to `90`) between the X–Z plane and the plane containing both the pointer (e.g., pen stylus) axis and the X axis. - {{domxref('PointerEvent.twist')}} {{ReadOnlyInline}} - - : The clockwise rotation of the pointer (e.g. pen stylus) around its major axis in degrees, with a value in the range `0` to `359`. + - : The clockwise rotation of the pointer (e.g., pen stylus) around its major axis in degrees, with a value in the range `0` to `359`. - {{domxref('PointerEvent.pointerType')}} {{ReadOnlyInline}} - : Indicates the device type that caused the event (mouse, pen, touch, etc.). - {{domxref('PointerEvent.isPrimary')}} {{ReadOnlyInline}} diff --git a/files/en-us/web/api/element/pointerup_event/index.md b/files/en-us/web/api/element/pointerup_event/index.md index 60308a7169573ae..8deddd4baf600df 100644 --- a/files/en-us/web/api/element/pointerup_event/index.md +++ b/files/en-us/web/api/element/pointerup_event/index.md @@ -16,10 +16,10 @@ This behavior is different from {{domxref("Element/mouseup_event", "mouseup")}} Use the event name in methods like {{domxref("EventTarget.addEventListener", "addEventListener()")}}, or set an event handler property. -```js -addEventListener("pointerup", (event) => {}); +```js-nolint +addEventListener("pointerup", (event) => { }) -onpointerup = (event) => {}; +onpointerup = (event) => { } ``` ## Event type @@ -49,11 +49,11 @@ _This interface inherits properties from {{domxref("MouseEvent")}} and {{domxref - {{domxref('PointerEvent.tangentialPressure')}} {{ReadOnlyInline}} - : The normalized tangential pressure of the pointer input (also known as barrel pressure or [cylinder stress](https://en.wikipedia.org/wiki/Cylinder_stress)) in the range `-1` to `1`, where `0` is the neutral position of the control. - {{domxref('PointerEvent.tiltX')}} {{ReadOnlyInline}} - - : The plane angle (in degrees, in the range of `-90` to `90`) between the Y–Z plane and the plane containing both the pointer (e.g. pen stylus) axis and the Y axis. + - : The plane angle (in degrees, in the range of `-90` to `90`) between the Y–Z plane and the plane containing both the pointer (e.g., pen stylus) axis and the Y axis. - {{domxref('PointerEvent.tiltY')}} {{ReadOnlyInline}} - - : The plane angle (in degrees, in the range of `-90` to `90`) between the X–Z plane and the plane containing both the pointer (e.g. pen stylus) axis and the X axis. + - : The plane angle (in degrees, in the range of `-90` to `90`) between the X–Z plane and the plane containing both the pointer (e.g., pen stylus) axis and the X axis. - {{domxref('PointerEvent.twist')}} {{ReadOnlyInline}} - - : The clockwise rotation of the pointer (e.g. pen stylus) around its major axis in degrees, with a value in the range `0` to `359`. + - : The clockwise rotation of the pointer (e.g., pen stylus) around its major axis in degrees, with a value in the range `0` to `359`. - {{domxref('PointerEvent.pointerType')}} {{ReadOnlyInline}} - : Indicates the device type that caused the event (mouse, pen, touch, etc.). - {{domxref('PointerEvent.isPrimary')}} {{ReadOnlyInline}} diff --git a/files/en-us/web/api/element/prefix/index.md b/files/en-us/web/api/element/prefix/index.md index 694a8699deaf489..1a13cd8be44c247 100644 --- a/files/en-us/web/api/element/prefix/index.md +++ b/files/en-us/web/api/element/prefix/index.md @@ -26,7 +26,7 @@ The following logs "x" to the console. ## Notes -This will only work when a namespace-aware parser is used, i.e. when a document is +This will only work when a namespace-aware parser is used, i.e., when a document is served with an XML MIME type. This will not work for HTML documents. ## Specifications diff --git a/files/en-us/web/api/element/previouselementsibling/index.md b/files/en-us/web/api/element/previouselementsibling/index.md index d05618fff932951..1d4bb67fab2f5f3 100644 --- a/files/en-us/web/api/element/previouselementsibling/index.md +++ b/files/en-us/web/api/element/previouselementsibling/index.md @@ -29,7 +29,7 @@ An {{domxref("Element")}} object, or `null`. let el = document.getElementById("div-03").previousElementSibling; document.write("<p>Siblings of div-03</p><ol>"); while (el) { - document.write("<li>" + el.nodeName + "</li>"); + document.write(`<li>${el.nodeName}</li>`); el = el.previousElementSibling; } document.write("</ol>"); diff --git a/files/en-us/web/api/element/queryselector/index.md b/files/en-us/web/api/element/queryselector/index.md index 5cf6082bdaad7a4..414ae545e721c78 100644 --- a/files/en-us/web/api/element/queryselector/index.md +++ b/files/en-us/web/api/element/queryselector/index.md @@ -26,7 +26,7 @@ querySelector(selectors) must be a valid CSS selector string; if it isn't, a `SyntaxError` exception is thrown. - Note that the HTML specification does not require attribute values to be valid CSS identifiers. If a [`class`](/en-US/docs/Web/HTML/Global_attributes/class) or [`id`](/en-US/docs/Web/HTML/Global_attributes/id) attribute value is not a valid CSS identifier, then you must escape it before using it in a selector, either by calling {{domxref("CSS.escape_static", "CSS.escape()")}} on the value, or using one of the techniques described in [Escaping characters](/en-US/docs/Web/CSS/ident#escaping_characters). See [Escaping attribute values](#escaping_attribute_values) for an example. + Note that the HTML specification does not require attribute values to be valid CSS identifiers. If a [`class`](/en-US/docs/Web/HTML/Reference/Global_attributes/class) or [`id`](/en-US/docs/Web/HTML/Reference/Global_attributes/id) attribute value is not a valid CSS identifier, then you must escape it before using it in a selector, either by calling {{domxref("CSS.escape_static", "CSS.escape()")}} on the value, or using one of the techniques described in [Escaping characters](/en-US/docs/Web/CSS/ident#escaping_characters). See [Escaping attribute values](#escaping_attribute_values) for an example. ### Return value @@ -151,7 +151,7 @@ selector). ### Escaping attribute values -This example shows that if an HTML document contains an [`id`](/en-US/docs/Web/HTML/Global_attributes/id) which is not a valid [CSS identifier](/en-US/docs/Web/CSS/ident), then we must escape the attribute value before using it in `querySelector()`. +This example shows that if an HTML document contains an [`id`](/en-US/docs/Web/HTML/Reference/Global_attributes/id) which is not a valid [CSS identifier](/en-US/docs/Web/CSS/ident), then we must escape the attribute value before using it in `querySelector()`. #### HTML diff --git a/files/en-us/web/api/element/queryselectorall/index.md b/files/en-us/web/api/element/queryselectorall/index.md index 236715b9bf71fdf..2bb409fa82a8227 100644 --- a/files/en-us/web/api/element/queryselectorall/index.md +++ b/files/en-us/web/api/element/queryselectorall/index.md @@ -27,7 +27,7 @@ querySelectorAll(selectors) must be a valid CSS selector string; if it isn't, a `SyntaxError` exception is thrown. - Note that the HTML specification does not require attribute values to be valid CSS identifiers. If a [`class`](/en-US/docs/Web/HTML/Global_attributes/class) or [`id`](/en-US/docs/Web/HTML/Global_attributes/id) attribute value is not a valid CSS identifier, then you must escape it before using it in a selector, either by calling {{domxref("CSS.escape_static", "CSS.escape()")}} on the value, or using one of the techniques described in [Escaping characters](/en-US/docs/Web/CSS/ident#escaping_characters). See [Escaping attribute values](#escaping_attribute_values) for an example. + Note that the HTML specification does not require attribute values to be valid CSS identifiers. If a [`class`](/en-US/docs/Web/HTML/Reference/Global_attributes/class) or [`id`](/en-US/docs/Web/HTML/Reference/Global_attributes/id) attribute value is not a valid CSS identifier, then you must escape it before using it in a selector, either by calling {{domxref("CSS.escape_static", "CSS.escape()")}} on the value, or using one of the techniques described in [Escaping characters](/en-US/docs/Web/CSS/ident#escaping_characters). See [Escaping attribute values](#escaping_attribute_values) for an example. The selectors are applied to the entire document, not just the particular element on which `querySelectorAll()` is called. To restrict the selector to the element on which `querySelectorAll()` is called, include the [`:scope`](/en-US/docs/Web/CSS/:scope) pseudo-class at the start of the selector. See the [selector scope](#selector_scope) example. @@ -204,7 +204,7 @@ When we press "Select with :scope", the `:scope` pseudo-class restricts the sele ### Escaping attribute values -This example shows that if an HTML document contains an [`id`](/en-US/docs/Web/HTML/Global_attributes/id) which is not a valid [CSS identifier](/en-US/docs/Web/CSS/ident), then we must escape the attribute value before using it in `querySelectorAll()`. +This example shows that if an HTML document contains an [`id`](/en-US/docs/Web/HTML/Reference/Global_attributes/id) which is not a valid [CSS identifier](/en-US/docs/Web/CSS/ident), then we must escape the attribute value before using it in `querySelectorAll()`. #### HTML diff --git a/files/en-us/web/api/element/requestfullscreen/index.md b/files/en-us/web/api/element/requestfullscreen/index.md index 0fe7ebe2759e4fc..e2b72858a0ce5cb 100644 --- a/files/en-us/web/api/element/requestfullscreen/index.md +++ b/files/en-us/web/api/element/requestfullscreen/index.md @@ -66,7 +66,7 @@ returned. The rejection handler receives one of the following exception values:_ current active document. - The element is not contained by a document. - The element is not permitted to use the `fullscreen` feature, - either because of [Permissions Policy](/en-US/docs/Web/HTTP/Permissions_Policy) configuration or other access control features. + either because of [Permissions Policy](/en-US/docs/Web/HTTP/Guides/Permissions_Policy) configuration or other access control features. - The element and its document are the same node. - The element is a [popover](/en-US/docs/Web/API/Popover_API) that is already being shown via {{domxref("HTMLElement.showPopover()")}}. @@ -85,7 +85,7 @@ simple requirements: {{MathMLElement("math")}}. - It is _not_ a {{HTMLElement("dialog")}} element. - It must either be located within the top-level document or in an - {{HTMLElement("iframe")}} which has the [`allowfullscreen`](/en-US/docs/Web/HTML/Element/iframe#allowfullscreen) + {{HTMLElement("iframe")}} which has the [`allowfullscreen`](/en-US/docs/Web/HTML/Reference/Elements/iframe#allowfullscreen) attribute applied to it. Additionally, any set Permissions Policies must allow the use of this feature. @@ -191,4 +191,4 @@ The {{domxref("Window.getScreenDetails()")}} method is used to retrieve the {{do - {{DOMxRef("Document.fullscreen")}} - {{DOMxRef("Document.fullscreenElement")}} - {{CSSxRef(":fullscreen")}} -- [`allowfullscreen`](/en-US/docs/Web/HTML/Element/iframe#allowfullscreen) +- [`allowfullscreen`](/en-US/docs/Web/HTML/Reference/Elements/iframe#allowfullscreen) diff --git a/files/en-us/web/api/element/requestpointerlock/index.md b/files/en-us/web/api/element/requestpointerlock/index.md index dda7df972253e53..8730c1771e7faa5 100644 --- a/files/en-us/web/api/element/requestpointerlock/index.md +++ b/files/en-us/web/api/element/requestpointerlock/index.md @@ -41,7 +41,7 @@ If calling `requestPointerLock()` immediately after releasing the pointer lock v If calling `requestPointerLock()` with {{domxref("Element.requestFullscreen()", "requestFullscreen()")}}, the `requestPointerLock()` must be called first, because the {{domxref("Element.requestFullscreen()", "requestFullscreen()")}} will consume the state of {{Glossary("Transient activation", "transient activation")}}. -The `allow-pointer-lock` [sandbox token](/en-US/docs/Web/HTML/Element/iframe#sandbox) must be added when calling `requestPointerLock()` in an {{htmlelement("iframe")}} element. Also, no other elements in other {{htmlelement("iframe")}} elements may be in pointer lock mode. +The `allow-pointer-lock` [sandbox token](/en-US/docs/Web/HTML/Reference/Elements/iframe#sandbox) must be added when calling `requestPointerLock()` in an {{htmlelement("iframe")}} element. Also, no other elements in other {{htmlelement("iframe")}} elements may be in pointer lock mode. ## Examples diff --git a/files/en-us/web/api/element/role/index.md b/files/en-us/web/api/element/role/index.md new file mode 100644 index 000000000000000..25a819c31053f15 --- /dev/null +++ b/files/en-us/web/api/element/role/index.md @@ -0,0 +1,45 @@ +--- +title: "Element: role property" +short-title: role +slug: Web/API/Element/role +page-type: web-api-instance-property +browser-compat: api.Element.role +--- + +{{ ApiRef("DOM") }} + +The **`role`** property of the {{domxref("Element")}} interface returns the explicitly set [WAI-ARIA role](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles) for the element. + +All HTML elements have an implicit ARIA role, even if that role is [`generic`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/generic_role). This semantic association allows tools to present and support interaction with the object in a manner that is consistent with user expectations about other objects of that type. The `role` attribute is used to explicitly set the element's ARIA role, overriding the implicit role. For example, a {{htmlelement("ul")}}, which has an implicit [`list`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/list_role) role, might have [`role="treegrid"`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/treegrid_role) explicitly set. The `role` property reflects the explicitly set value of the `role` attribute—in this case `treegrid`; it does not return the element's implicit `list` role unless explicitly set. + +The full list of defined ARIA roles can be found on the [ARIA roles](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles) reference page. + +## Value + +A string; the value of the `role` attribute or `null` if not explicitly set. + +## Examples + +In this example, images with empty or missing `alt` attributes are given a `role` of [`presentation`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/presentation_role): + +```js +const images = document.querySelectorAll("img"); +images.forEach((image) => { + if (!image.alt) { + image.role = "presentation"; + } +}); +``` + +## Specifications + +{{Specifications}} + +## Browser compatibility + +{{Compat}} + +## See also + +- {{domxref("ElementInternals.role")}} +- [ARIA attributes](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes) diff --git a/files/en-us/web/api/element/scroll_event/index.md b/files/en-us/web/api/element/scroll_event/index.md index 8e31c3446e8a07d..319dcd127ef8301 100644 --- a/files/en-us/web/api/element/scroll_event/index.md +++ b/files/en-us/web/api/element/scroll_event/index.md @@ -15,10 +15,10 @@ To detect when scrolling has completed, see the {{domxref("Element/scrollend_eve Use the event name in methods like {{domxref("EventTarget.addEventListener", "addEventListener()")}}, or set an event handler property. -```js -addEventListener("scroll", (event) => {}); +```js-nolint +addEventListener("scroll", (event) => { }) -onscroll = (event) => {}; +onscroll = (event) => { } ``` ## Event type diff --git a/files/en-us/web/api/element/scrollend_event/index.md b/files/en-us/web/api/element/scrollend_event/index.md index 5534b7f41e7d40a..14b1f0ab3d0f6d0 100644 --- a/files/en-us/web/api/element/scrollend_event/index.md +++ b/files/en-us/web/api/element/scrollend_event/index.md @@ -21,10 +21,10 @@ For detecting when scrolling inside a Document is complete, see the {{domxref("D Use the event name in methods like {{domxref("EventTarget.addEventListener", "addEventListener()")}}, or set an event handler property. -```js -addEventListener("scrollend", (event) => {}); +```js-nolint +addEventListener("scrollend", (event) => { }) -onscrollend = (event) => {}; +onscrollend = (event) => { } ``` ## Event type diff --git a/files/en-us/web/api/element/scrollheight/index.md b/files/en-us/web/api/element/scrollheight/index.md index 1981092127f1505..85e67e7faef5e50 100644 --- a/files/en-us/web/api/element/scrollheight/index.md +++ b/files/en-us/web/api/element/scrollheight/index.md @@ -8,28 +8,15 @@ browser-compat: api.Element.scrollHeight {{APIRef("DOM")}} -The **`Element.scrollHeight`** read-only property is a -measurement of the height of an element's content, including content not visible on the -screen due to overflow. +The **`scrollHeight`** read-only property of the {{domxref("Element")}} interface is a measurement of the height of an element's content, including content not visible on the screen due to overflow. ![The user's viewport is an element with four regions labeled padding-top, border-top, border-bottom, padding-bottom. The scroll height goes from the container's padding top to the end of the padding bottom, well beyond the top and bottom of the viewport.](scrollheight.png) -The `scrollHeight` value is equal to the minimum height the element would -require in order to fit all the content in the viewport without using a vertical -scrollbar. The height is measured in the same way as {{domxref("Element.clientHeight", "clientHeight")}}: -it includes the element's padding, but not its border, margin or -horizontal scrollbar (if present). It can also include the height of pseudo-elements -such as {{cssxref("::before")}} or {{cssxref("::after")}}. If the element's content can -fit without a need for vertical scrollbar, its `scrollHeight` is equal to -{{domxref("Element.clientHeight", "clientHeight")}} - -> [!NOTE] -> This property will round the value to an integer. If you need a fractional value, use -> {{domxref("Element.getBoundingClientRect()")}}. +The `scrollHeight` value is equal to the minimum height the element would require in order to fit all the content in the viewport without using a vertical scrollbar. The height is measured in the same way as {{domxref("Element.clientHeight", "clientHeight")}}: it includes the element's padding, but not its border, margin or horizontal scrollbar (if present). It can also include the height of pseudo-elements such as {{cssxref("::before")}} or {{cssxref("::after")}}. If the element's content can fit without a need for vertical scrollbar, its `scrollHeight` is equal to {{domxref("Element.clientHeight", "clientHeight")}}. ## Value -An integer corresponding to the scrollHeight pixel value of the element. +An integer. ## Problems and solutions @@ -72,13 +59,9 @@ function isScrollable(element) { ### Checking that the user has read a text -Associated with the {{domxref("Element.scroll_event", "scroll")}} event, this -equivalence can be useful to determine whether a user has read a text or not (see also -the {{domxref("element.scrollTop")}} and {{domxref("element.clientHeight")}} -properties). +Associated with the {{domxref("Element.scroll_event", "scroll")}} event, this equivalence can be useful to determine whether a user has read a text or not (see also the {{domxref("element.scrollTop")}} and {{domxref("element.clientHeight")}} properties). -The checkbox in the demo below is disabled, and so cannot be checked to show agreement -until the content of the paragraph has been scrolled through. Once checked, the "Next" button can be clicked to continue. +The checkbox in the demo below is disabled, and so cannot be checked to show agreement until the content of the paragraph has been scrolled through. Once checked, the "Next" button can be clicked to continue. #### HTML @@ -216,6 +199,11 @@ toNextStep.addEventListener("click", () => { ## See also -- {{domxref("Element.clientHeight")}} -- {{domxref("HTMLElement.offsetHeight")}} - [Determining the dimensions of elements](/en-US/docs/Web/API/CSS_Object_Model/Determining_the_dimensions_of_elements) +- {{domxref("HTMLElement.offsetHeight")}} +- {{domxref("Element.clientHeight")}} +- {{domxref("Element.scrollWidth")}} +- {{domxref("Element.scrollLeft")}} +- {{domxref("Element.scrollTop")}} +- {{domxref("Element.getBoundingClientRect()")}} +- {{domxref("Element.scrollTo()")}} diff --git a/files/en-us/web/api/element/scrollleft/index.md b/files/en-us/web/api/element/scrollleft/index.md index d6cd4e3195270d7..186865764e14a00 100644 --- a/files/en-us/web/api/element/scrollleft/index.md +++ b/files/en-us/web/api/element/scrollleft/index.md @@ -8,7 +8,7 @@ browser-compat: api.Element.scrollLeft {{APIRef("DOM")}} -The **`Element.scrollLeft`** property gets or sets the number of pixels by which an element's content is scrolled from its left edge. This value is subpixel precise in modern browsers, meaning that it isn't necessarily a whole number. +The **`scrollLeft`** property of the {{domxref("Element")}} interface gets or sets the number of pixels by which an element's content is scrolled from its left edge. This value is subpixel precise in modern browsers, meaning that it isn't necessarily a whole number. ## Value @@ -72,5 +72,11 @@ button.onclick = () => { ## See also +- [Determining the dimensions of elements](/en-US/docs/Web/API/CSS_Object_Model/Determining_the_dimensions_of_elements) +- {{domxref("HTMLElement.offsetLeft")}} +- {{domxref("Element.clientLeft")}} +- {{domxref("Element.scrollHeight")}} +- {{domxref("Element.scrollWidth")}} - {{domxref("Element.scrollTop")}} +- {{domxref("Element.getBoundingClientRect()")}} - {{domxref("Element.scrollTo()")}} diff --git a/files/en-us/web/api/element/scrollsnapchange_event/index.md b/files/en-us/web/api/element/scrollsnapchange_event/index.md index 62f7ece416792f4..db4c26bea6de812 100644 --- a/files/en-us/web/api/element/scrollsnapchange_event/index.md +++ b/files/en-us/web/api/element/scrollsnapchange_event/index.md @@ -18,10 +18,10 @@ A scrolling operation ends when the user finishes scrolling within a scroll cont Use the event name in methods like {{domxref("EventTarget.addEventListener", "addEventListener()")}}, or set an event handler property. -```js -addEventListener("scrollsnapchange", (event) => {}); +```js-nolint +addEventListener("scrollsnapchange", (event) => { }) -onscrollsnapchange = (event) => {}; +onscrollsnapchange = (event) => { } ``` ## Event type diff --git a/files/en-us/web/api/element/scrollsnapchanging_event/index.md b/files/en-us/web/api/element/scrollsnapchanging_event/index.md index 4840223fb8c445d..b5e4364d3b7ae65 100644 --- a/files/en-us/web/api/element/scrollsnapchanging_event/index.md +++ b/files/en-us/web/api/element/scrollsnapchanging_event/index.md @@ -10,7 +10,7 @@ browser-compat: api.Element.scrollsnapchanging_event {{APIRef}}{{SeeCompatTable}} -The **`scrollsnapchanging`** event of the {{domxref("Element")}} interface is fired on the [scroll container](/en-US/docs/Glossary/Scroll_container) when the browser determines a new scroll snap target is pending, i.e. it will be selected when the current scroll gesture ends. +The **`scrollsnapchanging`** event of the {{domxref("Element")}} interface is fired on the [scroll container](/en-US/docs/Glossary/Scroll_container) when the browser determines a new scroll snap target is pending, i.e., it will be selected when the current scroll gesture ends. Specifically, this event fires during a scrolling gesture, each time the user moves over potential new snap targets. For example, the user could scroll slowly by dragging their finger on a touch screen device, or hold down the mouse button on a scroll bar and move the mouse. `scrollsnapchanging` can therefore fire multiple times for each scrolling gesture. @@ -20,10 +20,10 @@ However, it does not fire on all potential snap targets for a scrolling gesture Use the event name in methods like {{domxref("EventTarget.addEventListener", "addEventListener()")}}, or set an event handler property. -```js -addEventListener("scrollsnapchanging", (event) => {}); +```js-nolint +addEventListener("scrollsnapchanging", (event) => { }) -onscrollsnapchanging = (event) => {}; +onscrollsnapchanging = (event) => { } ``` ## Event type diff --git a/files/en-us/web/api/element/scrolltop/index.md b/files/en-us/web/api/element/scrolltop/index.md index 589c55f2d23de96..38f9dbbd19e762e 100644 --- a/files/en-us/web/api/element/scrolltop/index.md +++ b/files/en-us/web/api/element/scrolltop/index.md @@ -8,7 +8,7 @@ browser-compat: api.Element.scrollTop {{APIRef("DOM")}} -The **`Element.scrollTop`** property gets or sets the number of pixels by which an element's content is scrolled from its top edge. This value is subpixel precise in modern browsers, meaning that it isn't necessarily a whole number. +The **`scrollTop`** property of the {{domxref("Element")}} interface gets or sets the number of pixels by which an element's content is scrolled from its top edge. This value is subpixel precise in modern browsers, meaning that it isn't necessarily a whole number. ## Value @@ -83,5 +83,11 @@ container.addEventListener("scroll", (event) => { ## See also +- [Determining the dimensions of elements](/en-US/docs/Web/API/CSS_Object_Model/Determining_the_dimensions_of_elements) +- {{domxref("HTMLElement.offsetTop")}} +- {{domxref("Element.clientTop")}} +- {{domxref("Element.scrollHeight")}} +- {{domxref("Element.scrollWidth")}} - {{domxref("Element.scrollLeft")}} +- {{domxref("Element.getBoundingClientRect()")}} - {{domxref("Element.scrollTo()")}} diff --git a/files/en-us/web/api/element/scrollwidth/index.md b/files/en-us/web/api/element/scrollwidth/index.md index 246149f5a99c74d..3b870b9737eb60d 100644 --- a/files/en-us/web/api/element/scrollwidth/index.md +++ b/files/en-us/web/api/element/scrollwidth/index.md @@ -8,22 +8,9 @@ browser-compat: api.Element.scrollWidth {{APIRef("DOM")}} -The **`Element.scrollWidth`** read-only property is a -measurement of the width of an element's content, including content not visible on the -screen due to overflow. - -The `scrollWidth` value is equal to the minimum width the element would -require in order to fit all the content in the viewport without using a horizontal -scrollbar. The width is measured in the same way as {{domxref("Element.clientWidth", "clientWidth")}}: -it includes the element's padding, but not its border, margin or -vertical scrollbar (if present). It can also include the width of pseudo-elements such -as {{cssxref("::before")}} or {{cssxref("::after")}}. If the element's content can fit -without a need for horizontal scrollbar, its `scrollWidth` is equal to -{{domxref("Element.clientWidth", "clientWidth")}}. - -> [!NOTE] -> This property will round the value to an integer. If you need a fractional value, -> use {{domxref("Element.getBoundingClientRect()")}}. +The **`scrollWidth`** read-only property of the {{domxref("Element")}} interface is a measurement of the width of an element's content, including content not visible on the screen due to overflow. + +The `scrollWidth` value is equal to the minimum width the element would require in order to fit all the content in the viewport without using a horizontal scrollbar. The width is measured in the same way as {{domxref("Element.clientWidth", "clientWidth")}}: it includes the element's padding, but not its border, margin or vertical scrollbar (if present). It can also include the width of pseudo-elements such as {{cssxref("::before")}} or {{cssxref("::after")}}. If the element's content can fit without a need for horizontal scrollbar, its `scrollWidth` is equal to {{domxref("Element.clientWidth", "clientWidth")}}. ## Value @@ -123,5 +110,11 @@ Click the buttons to check if the content is overflowing the containers. ## See also -- {{domxref("Element.clientWidth")}} - [Determining the dimensions of elements](/en-US/docs/Web/API/CSS_Object_Model/Determining_the_dimensions_of_elements) +- {{domxref("HTMLElement.offsetWidth")}} +- {{domxref("Element.clientWidth")}} +- {{domxref("Element.scrollHeight")}} +- {{domxref("Element.scrollLeft")}} +- {{domxref("Element.scrollTop")}} +- {{domxref("Element.getBoundingClientRect()")}} +- {{domxref("Element.scrollTo()")}} diff --git a/files/en-us/web/api/element/securitypolicyviolation_event/index.md b/files/en-us/web/api/element/securitypolicyviolation_event/index.md index ef416faef38aa5c..3d4c041bd07d9d3 100644 --- a/files/en-us/web/api/element/securitypolicyviolation_event/index.md +++ b/files/en-us/web/api/element/securitypolicyviolation_event/index.md @@ -8,25 +8,24 @@ browser-compat: api.Element.securitypolicyviolation_event {{APIRef}} -The **`securitypolicyviolation`** event is fired when a [Content Security Policy](/en-US/docs/Web/HTTP/CSP) is violated. +The **`securitypolicyviolation`** event is fired when a [Content Security Policy](/en-US/docs/Web/HTTP/Guides/CSP) is violated. The event is fired on the element when there is a violation of the CSP policy. -This event [bubbles](/en-US/docs/Learn_web_development/Core/Scripting/Event_bubbling) and is [composed](/en-US/docs/Web/API/Event/composed). -It is normally handled by an event handler on the {{domxref("Window")}} or {{domxref("Document")}} object. +This event [bubbles](/en-US/docs/Learn_web_development/Core/Scripting/Event_bubbling) to the {{domxref("Window")}} object, and is [composed](/en-US/docs/Web/API/Event/composed). > [!NOTE] -> You should add the handler for this event to a top level object (i.e. {{domxref("Window")}} or {{domxref("Document")}}). -> While the property exists in HTML elements, you can't assign a handler to the property until the elements have been loaded, by which time this event will already have fired. +> You should generally add the handler for this event to a top level object (i.e., {{domxref("Window")}} or {{domxref("Document")}}). +> While HTML elements can technically be the target of the `securitypolicyviolation` event, in reality this event does not fire on them—for example, a blocked `<img>` source directly triggers this event on `document` as the target, instead of bubbling from the `<img>` element. ## Syntax Use the event name in methods like {{domxref("EventTarget.addEventListener", "addEventListener()")}}, or set an event handler property. -```js -addEventListener("securitypolicyviolation", (event) => {}); +```js-nolint +addEventListener("securitypolicyviolation", (event) => { }) -onsecuritypolicyviolation = (event) => {}; +onsecuritypolicyviolation = (event) => { } ``` ## Event type @@ -37,11 +36,9 @@ A {{domxref("SecurityPolicyViolationEvent")}}. Inherits from {{domxref("Event")} ## Examples -The code below shows how you might add an event handler function using the `onsecuritypolicyviolation` global event handler property or `addEventListener()` on the top level `Window` (you could use exactly the same approach on `Document`). +### Listening for securitypolicyviolation on Window -> [!NOTE] -> The example doesn't assign the handler directly to an element because, as noted above, for elements defined in HTML, the event would fired before this code could run. -> You might however add the event listener directly to an element that is dynamically constructed! +The code below shows how you might add an event handler function using the `onsecuritypolicyviolation` global event handler property or `addEventListener()` on the top level `Window` (you could use exactly the same approach on `Document`). ```js window.onsecuritypolicyviolation = (e) => { @@ -65,4 +62,4 @@ window.addEventListener("securitypolicyviolation", (e) => { - The {{domxref("Document/securitypolicyviolation_event", "securitypolicyviolation")}} event of the {{domxref("Document")}} interface - The {{domxref("WorkerGlobalScope/securitypolicyviolation_event", "securitypolicyviolation")}} event of the {{domxref("WorkerGlobalScope")}} interface -- [HTTP > Content Security Policy](/en-US/docs/Web/HTTP/CSP) +- [HTTP > Content Security Policy](/en-US/docs/Web/HTTP/Guides/CSP) diff --git a/files/en-us/web/api/element/setattributens/index.md b/files/en-us/web/api/element/setattributens/index.md index 042149318d63602..e634ad6cf4f5942 100644 --- a/files/en-us/web/api/element/setattributens/index.md +++ b/files/en-us/web/api/element/setattributens/index.md @@ -47,7 +47,7 @@ d.setAttributeNS( ## Notes `setAttributeNS` is the only method for namespaced attributes which expects -the fully qualified name, i.e. `"namespace:localname"`. +the fully qualified name, i.e., `"namespace:local-name"`. ## Specifications diff --git a/files/en-us/web/api/element/setcapture/index.md b/files/en-us/web/api/element/setcapture/index.md index b0cb97ffd01d2dd..10668950f4beaaf 100644 --- a/files/en-us/web/api/element/setcapture/index.md +++ b/files/en-us/web/api/element/setcapture/index.md @@ -16,7 +16,7 @@ to this element until the mouse button is released or {{domxref("document.releas > [!WARNING] > This interface never had much cross-browser -> support and you probably looking for {{domxref("element.setPointerCapture")}} instead, +> support and you are probably looking for {{domxref("element.setPointerCapture")}} instead, > from the Pointer Events API. ## Syntax diff --git a/files/en-us/web/api/element/sethtmlunsafe/index.md b/files/en-us/web/api/element/sethtmlunsafe/index.md index 794939d08196c7b..918d8057f4e2f3b 100644 --- a/files/en-us/web/api/element/sethtmlunsafe/index.md +++ b/files/en-us/web/api/element/sethtmlunsafe/index.md @@ -9,11 +9,11 @@ browser-compat: api.Element.setHTMLUnsafe {{APIRef("DOM")}} The **`setHTMLUnsafe()`** method of the {{domxref("Element")}} interface is used to parse a string of HTML into a {{domxref("DocumentFragment")}}, which then replaces the element's subtree in the DOM. -The input HTML may include [declarative shadow roots](/en-US/docs/Web/HTML/Element/template#declarative_shadow_dom). +The input HTML may include [declarative shadow roots](/en-US/docs/Web/HTML/Reference/Elements/template#declarative_shadow_dom). The suffix "Unsafe" in the method name indicates that the method does not sanitize or remove potentially unsafe XSS-relevant input, such as `<script>` elements, and script or event handler content attributes. -If the string of HTML defines more than one [declarative shadow root](/en-US/docs/Web/HTML/Element/template#declarative_shadow_dom) in a particular shadow host then only the first {{domxref("ShadowRoot")}} is created — subsequent declarations are parsed as `<template>` elements within that shadow root. +If the string of HTML defines more than one [declarative shadow root](/en-US/docs/Web/HTML/Reference/Elements/template#declarative_shadow_dom) in a particular shadow host then only the first {{domxref("ShadowRoot")}} is created — subsequent declarations are parsed as `<template>` elements within that shadow root. > [!NOTE] > This method should be used instead of {{domxref("Element.innerHTML")}} when a string of HTML may contain declarative shadow roots. diff --git a/files/en-us/web/api/element/setpointercapture/index.md b/files/en-us/web/api/element/setpointercapture/index.md index 2aed47b0064b1ec..af527be37f8a946 100644 --- a/files/en-us/web/api/element/setpointercapture/index.md +++ b/files/en-us/web/api/element/setpointercapture/index.md @@ -60,6 +60,7 @@ div { align-items: center; justify-content: center; background: #fbe; + touch-action: none; } ``` diff --git a/files/en-us/web/api/element/slot/index.md b/files/en-us/web/api/element/slot/index.md index dfde49e71e85ee4..9af35a9683f19d7 100644 --- a/files/en-us/web/api/element/slot/index.md +++ b/files/en-us/web/api/element/slot/index.md @@ -25,7 +25,7 @@ using the contents of a template that contains a slot named `my-text`. When `<my-paragraph>` is used in the document, the slot is populated by a slottable element by including it inside the element with a -[`slot`](/en-US/docs/Web/HTML/Global_attributes/slot) attribute +[`slot`](/en-US/docs/Web/HTML/Reference/Global_attributes/slot) attribute with the value `my-text`. Here is one such example: ```html diff --git a/files/en-us/web/api/element/touchcancel_event/index.md b/files/en-us/web/api/element/touchcancel_event/index.md index 0f7f5dffb4d6943..d36e6ead02a93ff 100644 --- a/files/en-us/web/api/element/touchcancel_event/index.md +++ b/files/en-us/web/api/element/touchcancel_event/index.md @@ -22,10 +22,10 @@ Some examples of situations that will trigger a `touchcancel` event: Use the event name in methods like {{domxref("EventTarget.addEventListener", "addEventListener()")}}, or set an event handler property. -```js -addEventListener("touchcancel", (event) => {}); +```js-nolint +addEventListener("touchcancel", (event) => { }) -ontouchcancel = (event) => {}; +ontouchcancel = (event) => { } ``` ## Event type diff --git a/files/en-us/web/api/element/touchend_event/index.md b/files/en-us/web/api/element/touchend_event/index.md index 7b26f074475ef02..93d1ae28a9212ae 100644 --- a/files/en-us/web/api/element/touchend_event/index.md +++ b/files/en-us/web/api/element/touchend_event/index.md @@ -14,10 +14,10 @@ The `touchend` event fires when one or more touch points are removed from the to Use the event name in methods like {{domxref("EventTarget.addEventListener", "addEventListener()")}}, or set an event handler property. -```js -addEventListener("touchend", (event) => {}); +```js-nolint +addEventListener("touchend", (event) => { }) -ontouchend = (event) => {}; +ontouchend = (event) => { } ``` ## Event type diff --git a/files/en-us/web/api/element/touchmove_event/index.md b/files/en-us/web/api/element/touchmove_event/index.md index e7868d33800132a..0eb5d2bf90fe294 100644 --- a/files/en-us/web/api/element/touchmove_event/index.md +++ b/files/en-us/web/api/element/touchmove_event/index.md @@ -14,10 +14,10 @@ The `touchmove` event is fired when one or more touch points are moved along the Use the event name in methods like {{domxref("EventTarget.addEventListener", "addEventListener()")}}, or set an event handler property. -```js -addEventListener("touchmove", (event) => {}); +```js-nolint +addEventListener("touchmove", (event) => { }) -ontouchmove = (event) => {}; +ontouchmove = (event) => { } ``` ## Event type diff --git a/files/en-us/web/api/element/touchstart_event/index.md b/files/en-us/web/api/element/touchstart_event/index.md index 2d7651afd0a7812..b827e5de8225473 100644 --- a/files/en-us/web/api/element/touchstart_event/index.md +++ b/files/en-us/web/api/element/touchstart_event/index.md @@ -14,10 +14,10 @@ The `touchstart` event is fired when one or more touch points are placed on the Use the event name in methods like {{domxref("EventTarget.addEventListener", "addEventListener()")}}, or set an event handler property. -```js -addEventListener("touchstart", (event) => {}); +```js-nolint +addEventListener("touchstart", (event) => { }) -ontouchstart = (event) => {}; +ontouchstart = (event) => { } ``` ## Event type diff --git a/files/en-us/web/api/element/transitioncancel_event/index.md b/files/en-us/web/api/element/transitioncancel_event/index.md index c2f2d8f2c555ea0..f3513f67e3776b3 100644 --- a/files/en-us/web/api/element/transitioncancel_event/index.md +++ b/files/en-us/web/api/element/transitioncancel_event/index.md @@ -14,10 +14,10 @@ The **`transitioncancel`** event is fired when a [CSS transition](/en-US/docs/We Use the event name in methods like {{domxref("EventTarget.addEventListener", "addEventListener()")}}, or set an event handler property. -```js -addEventListener("transitioncancel", (event) => {}); +```js-nolint +addEventListener("transitioncancel", (event) => { }) -ontransitioncancel = (event) => {}; +ontransitioncancel = (event) => { } ``` ## Event type diff --git a/files/en-us/web/api/element/transitionend_event/index.md b/files/en-us/web/api/element/transitionend_event/index.md index f342259bbcfda0b..47b64b8e70a623e 100644 --- a/files/en-us/web/api/element/transitionend_event/index.md +++ b/files/en-us/web/api/element/transitionend_event/index.md @@ -18,10 +18,10 @@ This event is not cancelable. Use the event name in methods like {{domxref("EventTarget.addEventListener", "addEventListener()")}}, or set an event handler property. -```js -addEventListener("transitionend", (event) => {}); +```js-nolint +addEventListener("transitionend", (event) => { }) -ontransitionend = (event) => {}; +ontransitionend = (event) => { } ``` ## Event type diff --git a/files/en-us/web/api/element/transitionrun_event/index.md b/files/en-us/web/api/element/transitionrun_event/index.md index b3619bd51986ec0..e382cc0f715996a 100644 --- a/files/en-us/web/api/element/transitionrun_event/index.md +++ b/files/en-us/web/api/element/transitionrun_event/index.md @@ -8,7 +8,7 @@ browser-compat: api.Element.transitionrun_event {{APIRef}} -The **`transitionrun`** event is fired when a [CSS transition](/en-US/docs/Web/CSS/CSS_transitions/Using_CSS_transitions) is first created, i.e. before any {{cssxref("transition-delay")}} has begun. +The **`transitionrun`** event is fired when a [CSS transition](/en-US/docs/Web/CSS/CSS_transitions/Using_CSS_transitions) is first created, i.e., before any {{cssxref("transition-delay")}} has begun. This event is not cancelable. @@ -16,10 +16,10 @@ This event is not cancelable. Use the event name in methods like {{domxref("EventTarget.addEventListener", "addEventListener()")}}, or set an event handler property. -```js -addEventListener("transitionrun", (event) => {}); +```js-nolint +addEventListener("transitionrun", (event) => { }) -ontransitionrun = (event) => {}; +ontransitionrun = (event) => { } ``` ## Event type @@ -109,8 +109,8 @@ el.addEventListener("transitionend", () => { The difference is that: -- `transitionrun` fires when the transition is created (i.e. at the start of any delay). -- `transitionstart` fires when the actual animation has begun (i.e. at the end of any delay). +- `transitionrun` fires when the transition is created (i.e., at the start of any delay). +- `transitionstart` fires when the actual animation has begun (i.e., at the end of any delay). The `transitionrun` will occur even if the transition is canceled before the delay expires. If there is no transition delay or if transition-delay is negative, both `transitionrun` and `transitionstart` are fired. diff --git a/files/en-us/web/api/element/transitionstart_event/index.md b/files/en-us/web/api/element/transitionstart_event/index.md index 374457ecd7e10a0..d488cf27fe14bb0 100644 --- a/files/en-us/web/api/element/transitionstart_event/index.md +++ b/files/en-us/web/api/element/transitionstart_event/index.md @@ -16,10 +16,10 @@ This event is not cancelable. Use the event name in methods like {{domxref("EventTarget.addEventListener", "addEventListener()")}}, or set an event handler property. -```js -addEventListener("transitionstart", (event) => {}); +```js-nolint +addEventListener("transitionstart", (event) => { }) -ontransitionstart = (event) => {}; +ontransitionstart = (event) => { } ``` ## Event type @@ -105,8 +105,8 @@ transition.addEventListener("transitionend", () => { The difference is that: -- transitionrun fires when the transition is created (i.e. at the start of any delay). -- transitionstart fires when the actual animation has begun (i.e. at the end of any delay). +- transitionrun fires when the transition is created (i.e., at the start of any delay). +- transitionstart fires when the actual animation has begun (i.e., at the end of any delay). ## Specifications diff --git a/files/en-us/web/api/element/webkitmouseforcechanged_event/index.md b/files/en-us/web/api/element/webkitmouseforcechanged_event/index.md index f2430c428d53584..860f00753f9939f 100644 --- a/files/en-us/web/api/element/webkitmouseforcechanged_event/index.md +++ b/files/en-us/web/api/element/webkitmouseforcechanged_event/index.md @@ -20,10 +20,10 @@ This event first fires after the {{domxref("Element/mousedown_event", "mousedown Use the event name in methods like {{domxref("EventTarget.addEventListener", "addEventListener()")}}, or set an event handler property. -```js -addEventListener("webkitmouseforcechanged", (event) => {}); +```js-nolint +addEventListener("webkitmouseforcechanged", (event) => { }) -onwebkitmouseforcechanged = (event) => {}; +onwebkitmouseforcechanged = (event) => { } ``` ## Event type diff --git a/files/en-us/web/api/element/webkitmouseforcedown_event/index.md b/files/en-us/web/api/element/webkitmouseforcedown_event/index.md index e65045e1e873b58..d783097db6f6e7a 100644 --- a/files/en-us/web/api/element/webkitmouseforcedown_event/index.md +++ b/files/en-us/web/api/element/webkitmouseforcedown_event/index.md @@ -18,10 +18,10 @@ After a {{domxref("Element.mousedown_event", "mousedown")}} event has been fired Use the event name in methods like {{domxref("EventTarget.addEventListener", "addEventListener()")}}, or set an event handler property. -```js -addEventListener("webkitmouseforcedown", (event) => {}); +```js-nolint +addEventListener("webkitmouseforcedown", (event) => { }) -onwebkitmouseforcedown = (event) => {}; +onwebkitmouseforcedown = (event) => { } ``` ## Event type diff --git a/files/en-us/web/api/element/webkitmouseforceup_event/index.md b/files/en-us/web/api/element/webkitmouseforceup_event/index.md index bbb926881c2b733..f11a407e21faaaa 100644 --- a/files/en-us/web/api/element/webkitmouseforceup_event/index.md +++ b/files/en-us/web/api/element/webkitmouseforceup_event/index.md @@ -18,10 +18,10 @@ The non-standard **`webkitmouseforceup`** event is fired by Safari at an {{domxr Use the event name in methods like {{domxref("EventTarget.addEventListener", "addEventListener()")}}, or set an event handler property. -```js -addEventListener("webkitmouseforceup", (event) => {}); +```js-nolint +addEventListener("webkitmouseforceup", (event) => { }) -onwebkitmouseforceup = (event) => {}; +onwebkitmouseforceup = (event) => { } ``` ## Event type diff --git a/files/en-us/web/api/element/webkitmouseforcewillbegin_event/index.md b/files/en-us/web/api/element/webkitmouseforcewillbegin_event/index.md index 0bea841f29ee0bc..8abd34942016664 100644 --- a/files/en-us/web/api/element/webkitmouseforcewillbegin_event/index.md +++ b/files/en-us/web/api/element/webkitmouseforcewillbegin_event/index.md @@ -22,10 +22,10 @@ To instruct macOS not to engage any default Force Touch actions if the user appl Use the event name in methods like {{domxref("EventTarget.addEventListener", "addEventListener()")}}, or set an event handler property. -```js -addEventListener("webkitmouseforceup", (event) => {}); +```js-nolint +addEventListener("webkitmouseforcewillbegin", (event) => { }) -onwebkitmouseforceup = (event) => {}; +onwebkitmouseforcewillbegin = (event) => { } ``` ## Event type diff --git a/files/en-us/web/api/element/wheel_event/index.md b/files/en-us/web/api/element/wheel_event/index.md index 35c7eddacf8c517..e1e0b14e6c6c0c1 100644 --- a/files/en-us/web/api/element/wheel_event/index.md +++ b/files/en-us/web/api/element/wheel_event/index.md @@ -26,10 +26,10 @@ The `wheel` event is cancelable. If the event is canceled, no scrolling or zoomi Use the event name in methods like {{domxref("EventTarget.addEventListener", "addEventListener()")}}, or set an event handler property. -```js -addEventListener("wheel", (event) => {}); +```js-nolint +addEventListener("wheel", (event) => { }) -onwheel = (event) => {}; +onwheel = (event) => { } ``` ## Event type diff --git a/files/en-us/web/api/elementinternals/ariaactivedescendantelement/index.md b/files/en-us/web/api/elementinternals/ariaactivedescendantelement/index.md new file mode 100644 index 000000000000000..4114eff155f01d6 --- /dev/null +++ b/files/en-us/web/api/elementinternals/ariaactivedescendantelement/index.md @@ -0,0 +1,40 @@ +--- +title: "Element: ariaActiveDescendantElement property" +short-title: ariaActiveDescendantElement +slug: Web/API/ElementInternals/ariaActiveDescendantElement +page-type: web-api-instance-property +browser-compat: api.ElementInternals.ariaActiveDescendantElement +--- + +{{APIRef("DOM")}} + +The **`ariaActiveDescendantElement`** property of the {{domxref("ElementInternals")}} interface represents the current active element when focus is on a [`composite`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/composite_role) widget, [`combobox`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/combobox_role), [`textbox`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/textbox_role), [`group`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/group_role), or [`application`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/application_role). + +The [`aria-activedescendant`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-activedescendant) topic contains additional information about how the attribute and property should be used. + +## Value + +An subclass of {{domxref("HTMLElement")}} that represents the active descendant, or `null` if there is no active descendant. + +## Description + +The property is a flexible alternative to using the [`aria-activedescendant`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-activedescendant) attribute. +Unlike `aria-activedescendant`, the element assigned to this property does not have to have an [`id`](/en-US/docs/Web/HTML/Reference/Global_attributes/id) attribute. + +The property reflects the element's [`aria-activedescendant`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-errormessage) attribute when it is defined, but only for reference `id` values that match valid in-scope elements. +If the property is set, then the corresponding attribute is cleared. +For more information about reflected element references and scope see [Reflected element references](/en-US/docs/Web/API/Document_Object_Model/Reflected_attributes#reflected_element_references) in the _Reflected attributes_ guide. + +## Specifications + +{{Specifications}} + +## Browser compatibility + +{{Compat}} + +## See also + +- [`aria-activedescendant`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-activedescendant) attribute +- {{domxref("Element.ariaActiveDescendantElement")}} +- [Reflected element references](/en-US/docs/Web/API/Document_Object_Model/Reflected_attributes#reflected_element_references) in the _Attribute reflection_ guide. diff --git a/files/en-us/web/api/elementinternals/ariaatomic/index.md b/files/en-us/web/api/elementinternals/ariaatomic/index.md index e6b52fc7ab4c2fd..ea527a8b432301b 100644 --- a/files/en-us/web/api/elementinternals/ariaatomic/index.md +++ b/files/en-us/web/api/elementinternals/ariaatomic/index.md @@ -8,7 +8,7 @@ browser-compat: api.ElementInternals.ariaAtomic {{APIRef("Web Components")}} -The **`ariaAtomic`** property of the {{domxref("ElementInternals")}} interface reflects the value of the [`aria-atomic`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-atomic) attribute, which indicates whether assistive technologies will present all, or only parts of, the changed region based on the change notifications defined by the `aria-relevant` attribute. +The **`ariaAtomic`** property of the {{domxref("ElementInternals")}} interface reflects the value of the [`aria-atomic`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-atomic) attribute, which indicates whether assistive technologies will present all, or only parts of, the changed region based on the change notifications defined by the `aria-relevant` attribute. > [!NOTE] > Setting aria attributes on `ElementInternals` allows default semantics to be defined on a custom element. These may be overwritten by author-defined attributes, but ensure that default semantics are retained should the author delete those attributes, or fail to add them at all. For more information see the [Accessibility Object Model explainer](https://wicg.github.io/aom/explainer.html#default-semantics-for-custom-elements-via-the-elementinternals-object). diff --git a/files/en-us/web/api/elementinternals/ariaautocomplete/index.md b/files/en-us/web/api/elementinternals/ariaautocomplete/index.md index 33aa8ae70182fef..63c6837c98af23e 100644 --- a/files/en-us/web/api/elementinternals/ariaautocomplete/index.md +++ b/files/en-us/web/api/elementinternals/ariaautocomplete/index.md @@ -8,7 +8,7 @@ browser-compat: api.ElementInternals.ariaAutoComplete {{APIRef("Web Components")}} -The **`ariaAutoComplete`** property of the {{domxref("ElementInternals")}} interface reflects the value of the [`aria-autocomplete`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-autocomplete) attribute, which indicates whether inputting text could trigger display of one or more predictions of the user's intended value for a combobox, searchbox, or textbox and specifies how predictions would be presented if they were made. +The **`ariaAutoComplete`** property of the {{domxref("ElementInternals")}} interface reflects the value of the [`aria-autocomplete`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-autocomplete) attribute, which indicates whether inputting text could trigger display of one or more predictions of the user's intended value for a combobox, searchbox, or textbox and specifies how predictions would be presented if they were made. > [!NOTE] > Setting aria attributes on `ElementInternals` allows default semantics to be defined on a custom element. These may be overwritten by author-defined attributes, but ensure that default semantics are retained should the author delete those attributes, or fail to add them at all. For more information see the [Accessibility Object Model explainer](https://wicg.github.io/aom/explainer.html#default-semantics-for-custom-elements-via-the-elementinternals-object). @@ -31,7 +31,14 @@ A string with one of the following values: In this example the value of `ariaAutoComplete` is set to "inline". ```js -this.internals_.ariaAutoComplete = "inline"; +class CustomControl extends HTMLElement { + constructor() { + super(); + this.internals_ = this.attachInternals(); + this.internals_.ariaAutoComplete = "inline"; + } + // … +} ``` ## Specifications diff --git a/files/en-us/web/api/elementinternals/ariabraillelabel/index.md b/files/en-us/web/api/elementinternals/ariabraillelabel/index.md new file mode 100644 index 000000000000000..2725f1ce40486d1 --- /dev/null +++ b/files/en-us/web/api/elementinternals/ariabraillelabel/index.md @@ -0,0 +1,90 @@ +--- +title: "ElementInternals: ariaBrailleLabel property" +short-title: ariaBrailleLabel +slug: Web/API/ElementInternals/ariaBrailleLabel +page-type: web-api-instance-property +browser-compat: api.ElementInternals.ariaBrailleLabel +--- + +{{APIRef("Web Components")}} + +The **`ariaBrailleLabel`** property of the {{domxref("ElementInternals")}} interface reflects the value of the [`aria-braillelabel`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-braillelabel) attribute, which defines the ARIA braille label of the element. + +This element label may be used by assistive technologies that can present content in braille, but should only be set if a braille-specific label would improve the user experience. +The [`aria-braillelabel`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-braillelabel) contains additional information about when the property should be set. + +## Value + +A string that is intended to be converted into braille. + +## Examples + +This example shows how to get and set the `ariaBrailleLabel` property. + +Assuming we have defined a custom element called `<star-rating>`, in which the element internal's braille label is set to be the value of the element's `aria-braillelabel` attribute: + +```js +class StarRating extends HTMLElement { + constructor() { + super(); + this._internals = this.attachInternals(); + this._internals.ariaRole = "slider"; + this._internals.ariaBrailleLabel = this.ariaBrailleLabel; + } + + // … +} + +customElements.define("star-rating", StarRating); +``` + +And we include the custom element with label text "3 out of 5 stars" and an `aria-braillelabel` attribute with a value of `"3"`. +This allows a braille display to show "slider 3" in braille rather than the more verbose "slider gra 3 out of 5 stars". + +```html +<star-rating id="rate" aria-braillelabel="3">3 out of 5 stars</star-rating> +``` + +```html hidden +<pre id="log"></pre> +``` + +```css hidden +#log { + height: 100px; + overflow: scroll; + padding: 0.5rem; + border: 1px solid black; +} +``` + +```js hidden +const logInternals = document.querySelector("#log"); +function log(text) { + logInternals.innerText = `${logInternals.innerText}${text}\n`; + logInternals.scrollTop = logInternals.scrollHeight; +} +``` + +The code uses the `ariaBrailleLabel` property to get and set the braille label. + +```js +const el = document.querySelector("star-rating"); +log(el._internals.ariaBrailleLabel); +el._internals.ariaBrailleLabel += "*"; +log(el._internals.ariaBrailleLabel); +``` + +{{EmbedLiveSample("Examples")}} + +## Specifications + +{{Specifications}} + +## Browser compatibility + +{{Compat}} + +## See also + +- {{domxref("ElementInternals.ariaBrailleRoleDescription")}} diff --git a/files/en-us/web/api/elementinternals/ariabrailleroledescription/index.md b/files/en-us/web/api/elementinternals/ariabrailleroledescription/index.md new file mode 100644 index 000000000000000..b59aa6d5d17322a --- /dev/null +++ b/files/en-us/web/api/elementinternals/ariabrailleroledescription/index.md @@ -0,0 +1,62 @@ +--- +title: "ElementInternals: ariaBrailleRoleDescription property" +short-title: ariaBrailleRoleDescription +slug: Web/API/ElementInternals/ariaBrailleRoleDescription +page-type: web-api-instance-property +browser-compat: api.ElementInternals.ariaBrailleRoleDescription +--- + +{{APIRef("Web Components")}} + +The **`ariaBrailleRoleDescription`** property of the {{domxref("ElementInternals")}} interface reflects the value of the [`aria-brailleroledescription`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-brailleroledescription) attribute, which defines the ARIA braille role description of the element. + +This property may be used to provide an abbreviated version of the [`aria-roledescription`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-roledescription) value. +It should only be used if `aria-roledescription` is present and in the rare case where it is too verbose for braille. +The [`aria-brailleroledescription`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-brailleroledescription) contains additional information about when the property should be set. + +## Value + +A string that is intended to be converted into braille. + +## Examples + +Assuming we have a custom slide element: + +```js +class CustomSlide extends HTMLElement { + constructor() { + super(); + this._internals = this.attachInternals(); + this._internals.role = "slide"; + } + + // … +} + +customElements.define("custom-slide", CustomSlide); +``` + +We can retrieve and set the value of the custom element's `aria-brailleroledescription` value: + +```js +const customEl = document.querySelector("custom-slide"); +log(customEl.ariaBrailleRoleDescription); +customEl.ariaBrailleRoleDescription = "sd"; +log(customEl.ariaBrailleRoleDescription); +``` + +### Result + +{{EmbedLiveSample("Getting and setting ariaBrailleRoleDescription")}} + +## Specifications + +{{Specifications}} + +## Browser compatibility + +{{Compat}} + +### See also + +- [ARIA roles](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles) diff --git a/files/en-us/web/api/elementinternals/ariabusy/index.md b/files/en-us/web/api/elementinternals/ariabusy/index.md index 52596e94ba8004c..ac05ff80f9c77b5 100644 --- a/files/en-us/web/api/elementinternals/ariabusy/index.md +++ b/files/en-us/web/api/elementinternals/ariabusy/index.md @@ -8,7 +8,7 @@ browser-compat: api.ElementInternals.ariaBusy {{APIRef("Web Components")}} -The **`ariaBusy`** property of the {{domxref("ElementInternals")}} interface reflects the value of the [`aria-busy`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-busy) attribute, which indicates whether an element is being modified, as assistive technologies may want to wait until the modifications are complete before exposing them to the user. +The **`ariaBusy`** property of the {{domxref("ElementInternals")}} interface reflects the value of the [`aria-busy`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-busy) attribute, which indicates whether an element is being modified, as assistive technologies may want to wait until the modifications are complete before exposing them to the user. > [!NOTE] > Setting aria attributes on `ElementInternals` allows default semantics to be defined on a custom element. These may be overwritten by author-defined attributes, but ensure that default semantics are retained should the author delete those attributes, or fail to add them at all. For more information see the [Accessibility Object Model explainer](https://wicg.github.io/aom/explainer.html#default-semantics-for-custom-elements-via-the-elementinternals-object). @@ -27,7 +27,14 @@ A string with one of the following values: In this example the value of `ariaBusy` is set to "true". ```js -this.internals_.ariaBusy = "true"; +class CustomControl extends HTMLElement { + constructor() { + super(); + this.internals_ = this.attachInternals(); + this.internals_.ariaBusy = "true"; + } + // … +} ``` ## Specifications diff --git a/files/en-us/web/api/elementinternals/ariachecked/index.md b/files/en-us/web/api/elementinternals/ariachecked/index.md index 430a69b5b59fe0a..f17ccf69b1db7cd 100644 --- a/files/en-us/web/api/elementinternals/ariachecked/index.md +++ b/files/en-us/web/api/elementinternals/ariachecked/index.md @@ -8,7 +8,7 @@ browser-compat: api.ElementInternals.ariaChecked {{APIRef("Web Components")}} -The **`ariaChecked`** property of the {{domxref("ElementInternals")}} interface reflects the value of the [`aria-checked`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-checked) attribute, which indicates the current "checked" state of checkboxes, radio buttons, and other widgets that have a checked state. +The **`ariaChecked`** property of the {{domxref("ElementInternals")}} interface reflects the value of the [`aria-checked`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-checked) attribute, which indicates the current "checked" state of checkboxes, radio buttons, and other widgets that have a checked state. > [!NOTE] > Setting aria attributes on `ElementInternals` allows default semantics to be defined on a custom element. These may be overwritten by author-defined attributes, but ensure that default semantics are retained should the author delete those attributes, or fail to add them at all. For more information see the [Accessibility Object Model explainer](https://wicg.github.io/aom/explainer.html#default-semantics-for-custom-elements-via-the-elementinternals-object). @@ -31,7 +31,14 @@ A string with one of the following values: In this example the value of `ariaChecked` is set to "true". ```js -this.internals_.ariaChecked = "true"; +class CustomControl extends HTMLElement { + constructor() { + super(); + this.internals_ = this.attachInternals(); + this.internals_.ariaChecked = "true"; + } + // … +} ``` ## Specifications @@ -44,4 +51,4 @@ this.internals_.ariaChecked = "true"; ## See also -- [ARIA: checkbox role](/en-US/docs/Web/Accessibility/ARIA/Roles/checkbox_role) +- [ARIA: checkbox role](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/checkbox_role) diff --git a/files/en-us/web/api/elementinternals/ariacolcount/index.md b/files/en-us/web/api/elementinternals/ariacolcount/index.md index 3a5464dc827caf7..918b7cadc1e5c24 100644 --- a/files/en-us/web/api/elementinternals/ariacolcount/index.md +++ b/files/en-us/web/api/elementinternals/ariacolcount/index.md @@ -8,7 +8,7 @@ browser-compat: api.ElementInternals.ariaColCount {{APIRef("Web Components")}} -The **`ariaColCount`** property of the {{domxref("ElementInternals")}} interface reflects the value of the [`aria-colcount`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-colcount) attribute, which defines the number of columns in a table, grid, or treegrid. +The **`ariaColCount`** property of the {{domxref("ElementInternals")}} interface reflects the value of the [`aria-colcount`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-colcount) attribute, which defines the number of columns in a table, grid, or treegrid. > [!NOTE] > Setting aria attributes on `ElementInternals` allows default semantics to be defined on a custom element. These may be overwritten by author-defined attributes, but ensure that default semantics are retained should the author delete those attributes, or fail to add them at all. For more information see the [Accessibility Object Model explainer](https://wicg.github.io/aom/explainer.html#default-semantics-for-custom-elements-via-the-elementinternals-object). @@ -19,10 +19,17 @@ A string. ## Examples -In this example the [`aria-colcount`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-colcount) attribute is set to "3". +In this example the [`aria-colcount`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-colcount) attribute is set to "3". ```js -this.internals_.ariaColCount = "3"; +class CustomControl extends HTMLElement { + constructor() { + super(); + this.internals_ = this.attachInternals(); + this.internals_.ariaColCount = "3"; + } + // … +} ``` ## Specifications @@ -35,4 +42,4 @@ this.internals_.ariaColCount = "3"; ## See also -- [ARIA: table role](/en-US/docs/Web/Accessibility/ARIA/Roles/table_role) +- [ARIA: table role](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/table_role) diff --git a/files/en-us/web/api/elementinternals/ariacolindex/index.md b/files/en-us/web/api/elementinternals/ariacolindex/index.md index 99b3123899f7b15..89c43d39d96ea4f 100644 --- a/files/en-us/web/api/elementinternals/ariacolindex/index.md +++ b/files/en-us/web/api/elementinternals/ariacolindex/index.md @@ -8,7 +8,7 @@ browser-compat: api.ElementInternals.ariaColIndex {{APIRef("Web Components")}} -The **`ariaColIndex`** property of the {{domxref("ElementInternals")}} interface reflects the value of the [`aria-colindex`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-colindex) attribute, which defines an element's column index or position with respect to the total number of columns within a table, grid, or treegrid. +The **`ariaColIndex`** property of the {{domxref("ElementInternals")}} interface reflects the value of the [`aria-colindex`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-colindex) attribute, which defines an element's column index or position with respect to the total number of columns within a table, grid, or treegrid. > [!NOTE] > Setting aria attributes on `ElementInternals` allows default semantics to be defined on a custom element. These may be overwritten by author-defined attributes, but ensure that default semantics are retained should the author delete those attributes, or fail to add them at all. For more information see the [Accessibility Object Model explainer](https://wicg.github.io/aom/explainer.html#default-semantics-for-custom-elements-via-the-elementinternals-object). @@ -22,7 +22,14 @@ A string which contains an integer. In this example the value of `ariaColIndex` is set to "2". ```js -this.internals_.ariaColIndex = "2"; +class CustomControl extends HTMLElement { + constructor() { + super(); + this.internals_ = this.attachInternals(); + this.internals_.ariaColIndex = "2"; + } + // … +} ``` ## Specifications @@ -35,4 +42,4 @@ this.internals_.ariaColIndex = "2"; ## See also -- [ARIA: table role](/en-US/docs/Web/Accessibility/ARIA/Roles/table_role) +- [ARIA: table role](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/table_role) diff --git a/files/en-us/web/api/elementinternals/ariacolindextext/index.md b/files/en-us/web/api/elementinternals/ariacolindextext/index.md index 60801859bd2e3d9..1eae4c2497d213b 100644 --- a/files/en-us/web/api/elementinternals/ariacolindextext/index.md +++ b/files/en-us/web/api/elementinternals/ariacolindextext/index.md @@ -7,7 +7,7 @@ browser-compat: api.ElementInternals.ariaColIndexText {{APIRef("Web Components")}} -The **`ariaColIndexText`** property of the {{domxref("ElementInternals")}} interface reflects the value of the [`aria-colindextext`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-colindextext) attribute, which defines a human readable text alternative of aria-colindex. +The **`ariaColIndexText`** property of the {{domxref("ElementInternals")}} interface reflects the value of the [`aria-colindextext`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-colindextext) attribute, which defines a human readable text alternative of aria-colindex. > [!NOTE] > Setting aria attributes on `ElementInternals` allows default semantics to be defined on a custom element. These may be overwritten by author-defined attributes, but ensure that default semantics are retained should the author delete those attributes, or fail to add them at all. For more information see the [Accessibility Object Model explainer](https://wicg.github.io/aom/explainer.html#default-semantics-for-custom-elements-via-the-elementinternals-object). @@ -21,7 +21,14 @@ A string. In this example the value of `ariaColIndexText` is set to "Column name". ```js -this.internals_.ariaColIndexText = "Column name"; +class CustomEl extends HTMLElement { + constructor() { + super(); + this.internals_ = this.attachInternals(); + this.internals_.ariaColIndexText = "Column name"; + } + // … +} ``` ## Specifications @@ -34,4 +41,4 @@ this.internals_.ariaColIndexText = "Column name"; ## See also -- [ARIA: table role](/en-US/docs/Web/Accessibility/ARIA/Roles/table_role) +- [ARIA: table role](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/table_role) diff --git a/files/en-us/web/api/elementinternals/ariacolspan/index.md b/files/en-us/web/api/elementinternals/ariacolspan/index.md index 91da7409a96f9eb..824f5b0bda24b12 100644 --- a/files/en-us/web/api/elementinternals/ariacolspan/index.md +++ b/files/en-us/web/api/elementinternals/ariacolspan/index.md @@ -8,7 +8,7 @@ browser-compat: api.ElementInternals.ariaColSpan {{APIRef("Web Components")}} -The **`ariaColSpan`** property of the {{domxref("ElementInternals")}} interface reflects the value of the [`aria-colspan`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-colspan) attribute, which defines the number of columns spanned by a cell or gridcell within a table, grid, or treegrid. +The **`ariaColSpan`** property of the {{domxref("ElementInternals")}} interface reflects the value of the [`aria-colspan`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-colspan) attribute, which defines the number of columns spanned by a cell or gridcell within a table, grid, or treegrid. > [!NOTE] > Setting aria attributes on `ElementInternals` allows default semantics to be defined on a custom element. These may be overwritten by author-defined attributes, but ensure that default semantics are retained should the author delete those attributes, or fail to add them at all. For more information see the [Accessibility Object Model explainer](https://wicg.github.io/aom/explainer.html#default-semantics-for-custom-elements-via-the-elementinternals-object). @@ -22,7 +22,14 @@ A string which contains an integer. In this example the value of `ariaColspan` is set to "2". ```js -this.internals_.ariaColspan = "2"; +class CustomEl extends HTMLElement { + constructor() { + super(); + this.internals_ = this.attachInternals(); + this.internals_.ariaColspan = "2"; + } + // … +} ``` ## Specifications @@ -35,4 +42,4 @@ this.internals_.ariaColspan = "2"; ## See also -- [ARIA: table role](/en-US/docs/Web/Accessibility/ARIA/Roles/table_role) +- [ARIA: table role](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/table_role) diff --git a/files/en-us/web/api/elementinternals/ariacontrolselements/index.md b/files/en-us/web/api/elementinternals/ariacontrolselements/index.md new file mode 100644 index 000000000000000..0b8b5f2754b3ff8 --- /dev/null +++ b/files/en-us/web/api/elementinternals/ariacontrolselements/index.md @@ -0,0 +1,44 @@ +--- +title: "ElementInternals: ariaControlsElements property" +short-title: ariaControlsElements +slug: Web/API/ElementInternals/ariaControlsElements +page-type: web-api-instance-property +browser-compat: api.ElementInternals.ariaControlsElements +--- + +{{APIRef("DOM")}} + +The **`ariaControlsElements`** property of the {{domxref("ElementInternals")}} interface is an array containing the element (or elements) that are controlled by the element it is applied to. +For example, this might be set on a [combobox](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/combobox_role) to indicate the element that it pops up, or on a [`scrollbar`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/scrollbar_role) to indicate the ID of the element it controls. + +The [`aria-controls`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-controls) topic contains additional information about how the attribute and property should be used. + +## Value + +An array of subclasses of {{domxref("HTMLElement")}}, representing the elements that are controlled by this element. + +When read, the returned array is a static and read-only. +When written, the assigned array is copied: subsequent changes to the array do not affect the value of the property. + +## Description + +The property is a flexible alternative to using the [`aria-controls`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-controls) attribute to set the controlled elements. +Unlike `aria-controls`, the elements assigned to this property do not have to have an [`id`](/en-US/docs/Web/HTML/Reference/Global_attributes/id) attribute. + +The property reflects the [`aria-controls`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-controls) attribute when it is defined, but only for listed reference `id` values that match valid in-scope elements. +If the property is set, then the corresponding attribute is cleared. +For more information about reflected element references and scope see [Reflected element references](/en-US/docs/Web/API/Document_Object_Model/Reflected_attributes#reflected_element_references) in the _Reflected attributes_ guide. + +## Specifications + +{{Specifications}} + +## Browser compatibility + +{{Compat}} + +## See also + +- [`aria-controls`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-controls) attribute +- {{domxref("Element.ariaControlsElements")}} +- [Reflected element references](/en-US/docs/Web/API/Document_Object_Model/Reflected_attributes#reflected_element_references) in the _Attribute reflection_ guide diff --git a/files/en-us/web/api/elementinternals/ariacurrent/index.md b/files/en-us/web/api/elementinternals/ariacurrent/index.md index 4c4b2cfd3db2370..f8b6cf0f78d2c28 100644 --- a/files/en-us/web/api/elementinternals/ariacurrent/index.md +++ b/files/en-us/web/api/elementinternals/ariacurrent/index.md @@ -8,7 +8,7 @@ browser-compat: api.ElementInternals.ariaCurrent {{APIRef("Web Components")}} -The **`ariaCurrent`** property of the {{domxref("ElementInternals")}} interface reflects the value of the [`aria-current`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-current) attribute, which indicates the element that represents the current item within a container or set of related elements. +The **`ariaCurrent`** property of the {{domxref("ElementInternals")}} interface reflects the value of the [`aria-current`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-current) attribute, which indicates the element that represents the current item within a container or set of related elements. > [!NOTE] > Setting aria attributes on `ElementInternals` allows default semantics to be defined on a custom element. These may be overwritten by author-defined attributes, but ensure that default semantics are retained should the author delete those attributes, or fail to add them at all. For more information see the [Accessibility Object Model explainer](https://wicg.github.io/aom/explainer.html#default-semantics-for-custom-elements-via-the-elementinternals-object). @@ -37,7 +37,14 @@ A string with one of the following values: In this example the value of `ariaCurrent` is set to "page". ```js -this.internals_.ariaCurrent = "page"; +class CustomControl extends HTMLElement { + constructor() { + super(); + this.internals_ = this.attachInternals(); + this.internals_.ariaCurrent = "page"; + } + // … +} ``` ## Specifications diff --git a/files/en-us/web/api/elementinternals/ariadescribedbyelements/index.md b/files/en-us/web/api/elementinternals/ariadescribedbyelements/index.md new file mode 100644 index 000000000000000..24cf6f899b53e0a --- /dev/null +++ b/files/en-us/web/api/elementinternals/ariadescribedbyelements/index.md @@ -0,0 +1,52 @@ +--- +title: "ElementInternals: ariaDescribedByElements property" +short-title: ariaDescribedByElements +slug: Web/API/ElementInternals/ariaDescribedByElements +page-type: web-api-instance-property +browser-compat: api.ElementInternals.ariaDescribedByElements +--- + +{{APIRef("DOM")}} + +The **`ariaDescribedByElements`** property of the {{domxref("ElementInternals")}} interface is an array containing the element (or elements) that provide an accessible description for the element it is applied to. +The accessible description is similar to the accessible label (see {{domxref("Element/ariaLabelledByElements","ariaLabelledByElements")}}), but provides more verbose information. + +The [`aria-describedby`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-describedby) topic contains additional information about how the attribute and property should be used. + +## Value + +An array of subclasses of {{domxref("HTMLElement")}}. +The inner text of these elements can be joined with spaces to get the accessible description. + +When read, the returned array is a static and read-only. +When written, the assigned array is copied: subsequent changes to the array do not affect the value of the property. + +## Description + +The property is a flexible alternative to using the [`aria-describedby`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-describedby) attribute to set the accessible description. +Unlike `aria-describedby`, the elements assigned to this property do not have to have an [`id`](/en-US/docs/Web/HTML/Reference/Global_attributes/id) attribute. + +The property reflects the element's [`aria-describedby`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-describedby) attribute when it is defined, but only for listed reference `id` values that match valid in-scope elements. +If the property is set, then the corresponding attribute is cleared. +For more information about reflected element references and scope see [Reflected element references](/en-US/docs/Web/API/Document_Object_Model/Reflected_attributes#reflected_element_references) in the _Reflected attributes_ guide. + +## Examples + +The examples in the following documents are relevant: + +- {{domxref("Element.ariaDescribedByElements")}} is the DOM equivalent of this property. + It is used in the same way, but within the DOM instead of a shadow DOM and/or custom element. + +## Specifications + +{{Specifications}} + +## Browser compatibility + +{{Compat}} + +## See also + +- [`aria-describedby`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-describedby) attribute +- {{domxref("Element.ariaDescribedByElements")}} +- [Reflected element references](/en-US/docs/Web/API/Document_Object_Model/Reflected_attributes#reflected_element_references) in the _Attribute reflection_ guide diff --git a/files/en-us/web/api/elementinternals/ariadescription/index.md b/files/en-us/web/api/elementinternals/ariadescription/index.md index b4ff49d58f11742..77e892dcfbf0e3d 100644 --- a/files/en-us/web/api/elementinternals/ariadescription/index.md +++ b/files/en-us/web/api/elementinternals/ariadescription/index.md @@ -8,7 +8,7 @@ browser-compat: api.ElementInternals.ariaDescription {{APIRef("Web Components")}} -The **`ariaDescription`** property of the {{domxref("ElementInternals")}} interface reflects the value of the [`aria-description`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-description) attribute, which defines a string value that describes or annotates the current element. +The **`ariaDescription`** property of the {{domxref("ElementInternals")}} interface reflects the value of the [`aria-description`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-description) attribute, which defines a string value that describes or annotates the current element. > [!NOTE] > Setting aria attributes on `ElementInternals` allows default semantics to be defined on a custom element. These may be overwritten by author-defined attributes, but ensure that default semantics are retained should the author delete those attributes, or fail to add them at all. For more information see the [Accessibility Object Model explainer](https://wicg.github.io/aom/explainer.html#default-semantics-for-custom-elements-via-the-elementinternals-object). @@ -22,7 +22,14 @@ A string. In this example the value of `ariaDescription` is set to "A description of this widget". ```js -this.internals_.ariaDescription = "A description of this widget"; +class CustomControl extends HTMLElement { + constructor() { + super(); + this.internals_ = this.attachInternals(); + this.internals_.ariaDescription = "A description of this widget"; + } + // … +} ``` ## Specifications diff --git a/files/en-us/web/api/elementinternals/ariadetailselements/index.md b/files/en-us/web/api/elementinternals/ariadetailselements/index.md new file mode 100644 index 000000000000000..9ce789d6651346b --- /dev/null +++ b/files/en-us/web/api/elementinternals/ariadetailselements/index.md @@ -0,0 +1,52 @@ +--- +title: "ElementInternals: ariaDetailsElements property" +short-title: ariaDetailsElements +slug: Web/API/ElementInternals/ariaDetailsElements +page-type: web-api-instance-property +browser-compat: api.ElementInternals.ariaDetailsElements +--- + +{{APIRef("DOM")}} + +The **`ariaDetailsElements`** property of the {{domxref("ElementInternals")}} interface is an array containing the element (or elements) that provide an accessible details for the element it is applied to. +The accessible details are similar to the accessible description (see {{domxref("ElementInternals/ariaDescribedByElements","ariaDescribedByElements")}}), but provides more verbose information. + +The [`aria-details`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-details) topic contains additional information about how the attribute and property should be used. + +## Value + +An array of subclasses of {{domxref("HTMLElement")}}. +The inner text of these elements can be joined with spaces to get the accessible details. + +When read, the returned array is a static and read-only. +When written, the assigned array is copied: subsequent changes to the array do not affect the value of the property. + +## Description + +The property is a flexible alternative to using the [`aria-details`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-details) attribute to set the accessible details information. +Unlike `aria-details`, the elements assigned to this property do not have to have an [`id`](/en-US/docs/Web/HTML/Reference/Global_attributes/id) attribute. + +The property reflects the element's [`aria-details`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-details) attribute when it is defined, but only for listed reference `id` values that match valid in-scope elements. +If the property is set, then the corresponding attribute is cleared. +For more information about reflected element references and scope see [Reflected element references](/en-US/docs/Web/API/Document_Object_Model/Reflected_attributes#reflected_element_references) in the _Reflected attributes_ guide. + +## Examples + +The examples in the following documents are relevant: + +- {{domxref("Element.ariaDetailsElements")}} is the DOM equivalent of this property. + It is used in the same way, but within the DOM instead of a shadow DOM and/or custom element. + +## Specifications + +{{Specifications}} + +## Browser compatibility + +{{Compat}} + +## See also + +- [`aria-details`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-details) attribute +- {{domxref("Element.ariaDetailsElements")}} +- [Reflected element references](/en-US/docs/Web/API/Document_Object_Model/Reflected_attributes#reflected_element_references) in the _Attribute reflection_ guide. diff --git a/files/en-us/web/api/elementinternals/ariadisabled/index.md b/files/en-us/web/api/elementinternals/ariadisabled/index.md index ebef99aad75295d..c07ca2a2a75d897 100644 --- a/files/en-us/web/api/elementinternals/ariadisabled/index.md +++ b/files/en-us/web/api/elementinternals/ariadisabled/index.md @@ -8,7 +8,7 @@ browser-compat: api.ElementInternals.ariaDisabled {{APIRef("Web Components")}} -The **`ariaDisabled`** property of the {{domxref("ElementInternals")}} interface reflects the value of the [`aria-disabled`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-disabled) attribute, which indicates that the element is perceivable but disabled, so it is not editable or otherwise operable. +The **`ariaDisabled`** property of the {{domxref("ElementInternals")}} interface reflects the value of the [`aria-disabled`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-disabled) attribute, which indicates that the element is perceivable but disabled, so it is not editable or otherwise operable. > [!NOTE] > Setting aria attributes on `ElementInternals` allows default semantics to be defined on a custom element. These may be overwritten by author-defined attributes, but ensure that default semantics are retained should the author delete those attributes, or fail to add them at all. For more information see the [Accessibility Object Model explainer](https://wicg.github.io/aom/explainer.html#default-semantics-for-custom-elements-via-the-elementinternals-object). @@ -27,7 +27,14 @@ A string with one of the following values: In this example the value of `ariaDisabled` is set to "true". ```js -this.internals_.ariaDisabled = "true"; +class CustomControl extends HTMLElement { + constructor() { + super(); + this.internals_ = this.attachInternals(); + this.internals_.ariaDisabled = "true"; + } + // … +} ``` ## Specifications diff --git a/files/en-us/web/api/elementinternals/ariaerrormessageelements/index.md b/files/en-us/web/api/elementinternals/ariaerrormessageelements/index.md new file mode 100644 index 000000000000000..5689966bdcece01 --- /dev/null +++ b/files/en-us/web/api/elementinternals/ariaerrormessageelements/index.md @@ -0,0 +1,51 @@ +--- +title: "ElementInternals: ariaErrorMessageElements property" +short-title: ariaErrorMessageElements +slug: Web/API/ElementInternals/ariaErrorMessageElements +page-type: web-api-instance-property +browser-compat: api.ElementInternals.ariaErrorMessageElements +--- + +{{APIRef("DOM")}} + +The **`ariaErrorMessageElements`** property of the {{domxref("ElementInternals")}} interface is an array containing the element (or elements) that provide an error message for the element it is applied to. + +The [`aria-errormessage`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-errormessage) topic contains additional information about how the attribute and property should be used. + +## Value + +An array of subclasses of {{domxref("HTMLElement")}}. +The inner text of these elements can be joined with spaces to get the error message. + +When read, the returned array is a static and read-only. +When written, the assigned array is copied: subsequent changes to the array do not affect the value of the property. + +## Description + +The property is a flexible alternative to using the [`aria-errormessage`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-errormessage) attribute to set the error message for an element. +Unlike `aria-errormessage`, the elements assigned to this property do not have to have an [`id`](/en-US/docs/Web/HTML/Reference/Global_attributes/id) attribute. + +The property reflects the element's [`aria-errormessage`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-errormessage) attribute when it is defined, but only for listed reference `id` values that match valid in-scope elements. +If the property is set, then the corresponding attribute is cleared. +For more information about reflected element references and scope see [Reflected element references](/en-US/docs/Web/API/Document_Object_Model/Reflected_attributes#reflected_element_references) in the _Reflected attributes_ guide. + +## Examples + +The examples in the following documents are relevant: + +- {{domxref("Element.ariaErrorMessageElements")}} is the DOM equivalent of this property. + It is used in the same way, but within the DOM instead of a shadow DOM and/or custom element. + +## Specifications + +{{Specifications}} + +## Browser compatibility + +{{Compat}} + +## See also + +- [`aria-errormessage`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-errormessage) attribute +- {{domxref("Element.ariaErrorMessageElements")}} +- [Reflected element references](/en-US/docs/Web/API/Document_Object_Model/Reflected_attributes#reflected_element_references) in the _Attribute reflection_ guide. diff --git a/files/en-us/web/api/elementinternals/ariaexpanded/index.md b/files/en-us/web/api/elementinternals/ariaexpanded/index.md index fba07863cf3c89b..903254fcd88cb54 100644 --- a/files/en-us/web/api/elementinternals/ariaexpanded/index.md +++ b/files/en-us/web/api/elementinternals/ariaexpanded/index.md @@ -8,7 +8,7 @@ browser-compat: api.ElementInternals.ariaExpanded {{APIRef("Web Components")}} -The **`ariaExpanded`** property of the {{domxref("ElementInternals")}} interface reflects the value of the [`aria-expanded`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-expanded) attribute, which indicates whether a grouping element owned or controlled by this element is expanded or collapsed. +The **`ariaExpanded`** property of the {{domxref("ElementInternals")}} interface reflects the value of the [`aria-expanded`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-expanded) attribute, which indicates whether a grouping element owned or controlled by this element is expanded or collapsed. > [!NOTE] > Setting aria attributes on `ElementInternals` allows default semantics to be defined on a custom element. These may be overwritten by author-defined attributes, but ensure that default semantics are retained should the author delete those attributes, or fail to add them at all. For more information see the [Accessibility Object Model explainer](https://wicg.github.io/aom/explainer.html#default-semantics-for-custom-elements-via-the-elementinternals-object). @@ -29,7 +29,14 @@ A string with one of the following values: In this example the value of `ariaExpanded` is set to "true". ```js -this.internals_.ariaExpanded = "true"; +class CustomControl extends HTMLElement { + constructor() { + super(); + this.internals_ = this.attachInternals(); + this.internals_.ariaInvalid = "true"; + } + // … +} ``` ## Specifications diff --git a/files/en-us/web/api/elementinternals/ariaflowtoelements/index.md b/files/en-us/web/api/elementinternals/ariaflowtoelements/index.md new file mode 100644 index 000000000000000..6df6bf8e7649dc3 --- /dev/null +++ b/files/en-us/web/api/elementinternals/ariaflowtoelements/index.md @@ -0,0 +1,52 @@ +--- +title: "ElementInternals: ariaFlowToElements property" +short-title: ariaFlowToElements +slug: Web/API/ElementInternals/ariaFlowToElements +page-type: web-api-instance-property +browser-compat: api.ElementInternals.ariaFlowToElements +--- + +{{APIRef("DOM")}} + +The **`ariaFlowToElements`** property of the {{domxref("ElementInternals")}} interface is an array containing the element (or elements) that provide an alternate reading order of content, overriding the general default reading order at the user's discretion. +If just one element is provided this is the next element in the reading order. +If multiple elements are provided, then each element represents a possible path that should be offered to the user for selection. + +The [`aria-flowto`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-flowto) topic contains additional information about how the attribute and property should be used. + +## Value + +An array of subclasses of {{domxref("HTMLElement")}}. + +When read, the returned array is a static and read-only. +When written, the assigned array is copied: subsequent changes to the array do not affect the value of the property. + +## Description + +The property is a flexible alternative to using the [`aria-flowto`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-flowto) attribute to set an alternative reading order. +Unlike `aria-flowto`, the elements assigned to this property do not have to have an [`id`](/en-US/docs/Web/HTML/Reference/Global_attributes/id) attribute. + +The property reflects the element's [`aria-flowto`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-flowto) attribute when it is defined, but only for listed reference `id` values that match valid in-scope elements. +If the property is set, then the corresponding attribute is cleared. +For more information about reflected element references and scope see [Reflected element references](/en-US/docs/Web/API/Document_Object_Model/Reflected_attributes#reflected_element_references) in the _Reflected attributes_ guide. + +## Examples + +The examples in the following documents are relevant: + +- {{domxref("Element.ariaFlowToElements")}} is the DOM equivalent of this property. + It is used in the same way, but within the DOM instead of a shadow DOM and/or custom element. + +## Specifications + +{{Specifications}} + +## Browser compatibility + +{{Compat}} + +## See also + +- [`aria-flowto`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-flowto) attribute +- {{domxref("Element.ariaFlowToElements")}} +- [Reflected element references](/en-US/docs/Web/API/Document_Object_Model/Reflected_attributes#reflected_element_references) in the _Attribute reflection_ guide. diff --git a/files/en-us/web/api/elementinternals/ariahaspopup/index.md b/files/en-us/web/api/elementinternals/ariahaspopup/index.md index bb2b663c2304c32..9ddf0f1dc31022b 100644 --- a/files/en-us/web/api/elementinternals/ariahaspopup/index.md +++ b/files/en-us/web/api/elementinternals/ariahaspopup/index.md @@ -8,7 +8,7 @@ browser-compat: api.ElementInternals.ariaHasPopup {{APIRef("Web Components")}} -The **`ariaHasPopup`** property of the {{domxref("ElementInternals")}} interface reflects the value of the [`aria-haspopup`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-haspopup) attribute, which indicates the availability and type of interactive popup element, such as menu or dialog, that can be triggered by an element. +The **`ariaHasPopup`** property of the {{domxref("ElementInternals")}} interface reflects the value of the [`aria-haspopup`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-haspopup) attribute, which indicates the availability and type of interactive popup element, such as menu or dialog, that can be triggered by an element. > [!NOTE] > Setting aria attributes on `ElementInternals` allows default semantics to be defined on a custom element. These may be overwritten by author-defined attributes, but ensure that default semantics are retained should the author delete those attributes, or fail to add them at all. For more information see the [Accessibility Object Model explainer](https://wicg.github.io/aom/explainer.html#default-semantics-for-custom-elements-via-the-elementinternals-object). @@ -37,7 +37,14 @@ A string with one of the following values: In this example the value of `ariaHasPopup` is set to "true". ```js -this.internals_.ariaHasPopup = "true"; +class CustomControl extends HTMLElement { + constructor() { + super(); + this.internals_ = this.attachInternals(); + this.internals_.ariaHasPopup = "true"; + } + // … +} ``` ## Specifications diff --git a/files/en-us/web/api/elementinternals/ariahidden/index.md b/files/en-us/web/api/elementinternals/ariahidden/index.md index 2ad4a22fc710b24..7908d93673a5be0 100644 --- a/files/en-us/web/api/elementinternals/ariahidden/index.md +++ b/files/en-us/web/api/elementinternals/ariahidden/index.md @@ -8,7 +8,7 @@ browser-compat: api.ElementInternals.ariaHidden {{APIRef("Web Components")}} -The **`ariaHidden`** property of the {{domxref("ElementInternals")}} interface reflects the value of the [`aria-hidden`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-hidden) attribute, which indicates whether the element is exposed to an accessibility API. +The **`ariaHidden`** property of the {{domxref("ElementInternals")}} interface reflects the value of the [`aria-hidden`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-hidden) attribute, which indicates whether the element is exposed to an accessibility API. > [!NOTE] > Setting aria attributes on `ElementInternals` allows default semantics to be defined on a custom element. These may be overwritten by author-defined attributes, but ensure that default semantics are retained should the author delete those attributes, or fail to add them at all. For more information see the [Accessibility Object Model explainer](https://wicg.github.io/aom/explainer.html#default-semantics-for-custom-elements-via-the-elementinternals-object). @@ -29,7 +29,14 @@ A string with one of the following values: In this example the value of `ariaHidden` is set to "true". ```js -this.internals_.ariaHidden = "true"; +class CustomControl extends HTMLElement { + constructor() { + super(); + this.internals_ = this.attachInternals(); + this.internals_.ariaHidden = "true"; + } + // … +} ``` ## Specifications diff --git a/files/en-us/web/api/elementinternals/ariainvalid/index.md b/files/en-us/web/api/elementinternals/ariainvalid/index.md new file mode 100644 index 000000000000000..b016845f8ef6a35 --- /dev/null +++ b/files/en-us/web/api/elementinternals/ariainvalid/index.md @@ -0,0 +1,61 @@ +--- +title: "ElementInternals: ariaInvalid property" +short-title: ariaInvalid +slug: Web/API/ElementInternals/ariaInvalid +page-type: web-api-instance-property +browser-compat: api.ElementInternals.ariaInvalid +--- + +{{APIRef("Web Components")}} + +The **`ariaInvalid`** property of the {{domxref("ElementInternals")}} interface reflects the value of the [`aria-invalid`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-invalid) attribute. Relevant for the [`application`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/application_role), [`checkbox`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/checkbox_role), [`combobox`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/combobox_role), [`gridcell`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/gridcell_role), [`listbox`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/listbox_role), [`radiogroup`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/radiogroup_role), [`slider`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/slider_role), [`spinbutton`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/spinbutton_role), [`textbox`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/textbox_role), and [`tree`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/tree_role) roles, it indicates to the accessibility API whether the entered value does not conform to the format expected by the application. + +> [!NOTE] +> Setting ARIA attributes on `ElementInternals` allows default semantics to be defined on a custom element. These may be overwritten by author-defined attributes, but ensure that default semantics are retained should the author delete those attributes, or fail to add them at all. For more information see the [Accessibility Object Model explainer](https://wicg.github.io/aom/explainer.html#default-semantics-for-custom-elements-via-the-elementinternals-object). + +## Value + +A string with one of the following values: + +- `"true"` + - : The element is invalid. +- `"false"` (default) + - : The element is not in an invalid state. +- `"grammar"` + - : The element is in an invalid state because grammatical error was detected. +- `"spelling"` + - : The element is in an invalid state because spelling error was detected. + +## Examples + +In this example, we define and create a `<custom-text>` element, and then retrieve the value of `ariaInvalid` from the first `<custom-text>` element in the document. + +```js +class CustomControl extends HTMLElement { + constructor() { + super(); + this._internals = this.attachInternals(); + this._internals.ariaInvalid = "false"; + } + // … +} + +window.customElements.define("custom-text", CustomControl); + +const element = document.querySelector("custom-text"); +console.log(element._internals.ariaInvalid); +``` + +## Specifications + +{{Specifications}} + +## Browser compatibility + +{{Compat}} + +## See also + +- {{domxref("ElementInternals.ariaRequired")}} +- [`aria-required`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-required) +- [`aria-errormessage`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-errormessage) diff --git a/files/en-us/web/api/elementinternals/ariakeyshortcuts/index.md b/files/en-us/web/api/elementinternals/ariakeyshortcuts/index.md index 2fef6e2504fc5d1..79d1b9521cd6039 100644 --- a/files/en-us/web/api/elementinternals/ariakeyshortcuts/index.md +++ b/files/en-us/web/api/elementinternals/ariakeyshortcuts/index.md @@ -8,7 +8,7 @@ browser-compat: api.ElementInternals.ariaKeyShortcuts {{APIRef("Web Components")}} -The **`ariaKeyShortcuts`** property of the {{domxref("ElementInternals")}} interface reflects the value of the [`aria-keyshortcuts`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-keyshortcuts) attribute, which indicates keyboard shortcuts that an author has implemented to activate or give focus to an element. +The **`ariaKeyShortcuts`** property of the {{domxref("ElementInternals")}} interface reflects the value of the [`aria-keyshortcuts`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-keyshortcuts) attribute, which indicates keyboard shortcuts that an author has implemented to activate or give focus to an element. > [!NOTE] > Setting aria attributes on `ElementInternals` allows default semantics to be defined on a custom element. These may be overwritten by author-defined attributes, but ensure that default semantics are retained should the author delete those attributes, or fail to add them at all. For more information see the [Accessibility Object Model explainer](https://wicg.github.io/aom/explainer.html#default-semantics-for-custom-elements-via-the-elementinternals-object). diff --git a/files/en-us/web/api/elementinternals/arialabel/index.md b/files/en-us/web/api/elementinternals/arialabel/index.md index 9a14c72dafbc79f..ae606b9c3f62d58 100644 --- a/files/en-us/web/api/elementinternals/arialabel/index.md +++ b/files/en-us/web/api/elementinternals/arialabel/index.md @@ -8,7 +8,7 @@ browser-compat: api.ElementInternals.ariaLabel {{APIRef("Web Components")}} -The **`ariaLabel`** property of the {{domxref("ElementInternals")}} interface reflects the value of the [`aria-label`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-label) attribute, which defines a string value that labels the current Element. +The **`ariaLabel`** property of the {{domxref("ElementInternals")}} interface reflects the value of the [`aria-label`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-label) attribute, which defines a string value that labels the current Element. > [!NOTE] > Setting aria attributes on `ElementInternals` allows default semantics to be defined on a custom element. These may be overwritten by author-defined attributes, but ensure that default semantics are retained should the author delete those attributes, or fail to add them at all. For more information see the [Accessibility Object Model explainer](https://wicg.github.io/aom/explainer.html#default-semantics-for-custom-elements-via-the-elementinternals-object). @@ -22,7 +22,14 @@ A string. In this example the value of `ariaLabel` is set to "close". ```js -this.internals_.ariaLabel = "close"; +class CustomControl extends HTMLElement { + constructor() { + super(); + this.internals_ = this.attachInternals(); + this.internals_.ariaLabel = "close"; + } + // … +} ``` ## Specifications diff --git a/files/en-us/web/api/elementinternals/arialabelledbyelements/index.md b/files/en-us/web/api/elementinternals/arialabelledbyelements/index.md new file mode 100644 index 000000000000000..42e65503a45d27a --- /dev/null +++ b/files/en-us/web/api/elementinternals/arialabelledbyelements/index.md @@ -0,0 +1,126 @@ +--- +title: "ElementInternals: ariaLabelledByElements property" +short-title: ariaLabelledByElements +slug: Web/API/ElementInternals/ariaLabelledByElements +page-type: web-api-instance-property +browser-compat: api.ElementInternals.ariaLabelledByElements +--- + +{{APIRef("DOM")}} + +The **`ariaLabelledByElements`** property of the {{domxref("ElementInternals")}} interface is an array containing the element (or elements) that provide an accessible name for the element it is applied to. + +The property is primarily intended to provide a label for elements that don't have a standard method for defining their accessible name. +For example, this might be used to name a generic container element, such as a {{htmlelement("div")}} or {{htmlelement("span")}}, or a grouping of elements, such as an image with a slider that can be used to change its opacity. +The property takes precedence over other mechanisms for providing an accessible name for elements, and may therefore also be used to provide a name for elements that would normally get it from their inner content or from an associated element such as a label. + +The [`aria-labelledby`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-labelledby) topic contains additional information about how the attribute and property should be used. + +## Value + +An array of elements. +The inner text of these elements can be joined with spaces to get the accessible name. + +When read, the returned array is a static and read-only. +When written, the assigned array is copied: subsequent changes to the array do not affect the value of the property. + +## Description + +The property is a flexible alternative to using the [`aria-labelledby`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-labelledby) attribute to set the accessible name. +Unlike `aria-labelledby`, the elements assigned to this property do not have to have an [`id`](/en-US/docs/Web/HTML/Reference/Global_attributes/id) attribute. + +The property reflects the element's [`aria-labelledby`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-labelledby) attribute when it is defined, but only for listed reference `id` values that match valid in-scope elements. +If the property is set, then the corresponding attribute is cleared. +For more information about reflected element references and scope see [Reflected element references](/en-US/docs/Web/API/Document_Object_Model/Reflected_attributes#reflected_element_references) in the _Reflected attributes_ guide. + +## Examples + +### Get the accessible name + +This example shows how `ariaLabelledByElements` can be used to programmatically get a label defined using `aria-labelledby` within the shadow root. + +#### HTML + +The HTML defines two {{htmlelement("span")}} elements and references their ids in the `aria-labelledby` attribute of an {{htmlelement("input")}}. +The accessible name of the `<input>` is therefore the concatenation of the inner text of the two referenced elements. + +```html +<div id="host"> + <template shadowrootmode="open"> + <span id="label_1">Street name</span> + <input aria-labelledby="label_1 label_2" /> + <span id="label_2">(just the name, no "Street" or "Road" or "Place")</span> + </template> +</div> +``` + +```html hidden +<pre id="log"></pre> +``` + +```css hidden +#log { + height: 70px; + overflow: scroll; + padding: 0.5rem; + border: 1px solid black; +} +``` + +#### JavaScript + +The code below first checks whether the `ariaLabelledByElements` is supported and if not, logs the result and exits. +If the property is supported it first logs the value of the property. +It then iterates through the returned elements, concatenating their inner text, and logs the resulting accessible name of the element. + +```js hidden +const logElement = document.querySelector("#log"); +function log(text) { + logElement.innerText = `${logElement.innerText}${text}\n`; + logElement.scrollTop = logElement.scrollHeight; +} +``` + +```js +// Get access to the input within shadowRoot +const hostElement = document.getElementById("host"); +const shadowRoot = hostElement.shadowRoot; +const inputElement = shadowRoot.querySelector("input"); + +// Feature test for ariaLabelledByElements +if ("ariaLabelledByElements" in ElementInternals.prototype) { + // Get and log attribute that provides the accessible name + log(`aria-labelledby: ${inputElement.getAttribute("aria-labelledby")}`); + + // Get and log elements that provide the accessible name + const labelElements = inputElement.ariaLabelledByElements; + log(`ariaLabelledByElements: ${labelElements}`); + + // Log inner text of elements to get accessible name + const text = labelElements.map((e) => e.textContent.trim()).join(" "); + log(`Accessible name: ${text.trim()}`); +} else { + log("ariaLabelledByElements not supported by browser"); +} +``` + +#### Result + +The log below shows the output of the above code. +This should show the array of referenced {{domxref("HTMLSpanElement")}} elements, and the resulting accessible name from their inner text. + +{{EmbedLiveSample("Get the accessible name","100%","150px")}} + +## Specifications + +{{Specifications}} + +## Browser compatibility + +{{Compat}} + +## See also + +- [`aria-labelledby`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-labelledby) attribute +- {{domxref("Element.ariaLabelledByElements")}} +- [Reflected element references](/en-US/docs/Web/API/Document_Object_Model/Reflected_attributes#reflected_element_references) in the _Attribute reflection_ guide. diff --git a/files/en-us/web/api/elementinternals/arialevel/index.md b/files/en-us/web/api/elementinternals/arialevel/index.md index 5c6cde48bd4a07c..2bd6f774b19448c 100644 --- a/files/en-us/web/api/elementinternals/arialevel/index.md +++ b/files/en-us/web/api/elementinternals/arialevel/index.md @@ -8,7 +8,7 @@ browser-compat: api.ElementInternals.ariaLevel {{APIRef("Web Components")}} -The **`ariaLevel`** property of the {{domxref("ElementInternals")}} interface reflects the value of the [`aria-level`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-level) attribute, which defines the hierarchical level of an element within a structure. +The **`ariaLevel`** property of the {{domxref("ElementInternals")}} interface reflects the value of the [`aria-level`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-level) attribute, which defines the hierarchical level of an element within a structure. > [!NOTE] > Setting aria attributes on `ElementInternals` allows default semantics to be defined on a custom element. These may be overwritten by author-defined attributes, but ensure that default semantics are retained should the author delete those attributes, or fail to add them at all. For more information see the [Accessibility Object Model explainer](https://wicg.github.io/aom/explainer.html#default-semantics-for-custom-elements-via-the-elementinternals-object). @@ -22,7 +22,14 @@ A string containing an integer. In this example the value of `ariaLevel` is set to "1". ```js -this.internals_.ariaLevel = "1"; +class CustomEl extends HTMLElement { + constructor() { + super(); + this.internals_ = this.attachInternals(); + this.internals_.ariaLevel = "1"; + } + // … +} ``` ## Specifications @@ -35,4 +42,4 @@ this.internals_.ariaLevel = "1"; ## See also -- [ARIA: heading role](/en-US/docs/Web/Accessibility/ARIA/Roles/heading_role) +- [ARIA: heading role](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/heading_role) diff --git a/files/en-us/web/api/elementinternals/arialive/index.md b/files/en-us/web/api/elementinternals/arialive/index.md index a0f7c493014eb5a..634823be17b4ec6 100644 --- a/files/en-us/web/api/elementinternals/arialive/index.md +++ b/files/en-us/web/api/elementinternals/arialive/index.md @@ -8,7 +8,7 @@ browser-compat: api.ElementInternals.ariaLive {{APIRef("Web Components")}} -The **`ariaLive`** property of the {{domxref("ElementInternals")}} interface reflects the value of the [`aria-live`](/en-US/docs/Web/Accessibility/ARIA/ARIA_Live_Regions) attribute, which indicates that an element will be updated, and describes the types of updates the user agents, assistive technologies, and user can expect from the live region. +The **`ariaLive`** property of the {{domxref("ElementInternals")}} interface reflects the value of the [`aria-live`](/en-US/docs/Web/Accessibility/ARIA/Guides/Live_regions) attribute, which indicates that an element will be updated, and describes the types of updates the user agents, assistive technologies, and user can expect from the live region. > [!NOTE] > Setting aria attributes on `ElementInternals` allows default semantics to be defined on a custom element. These may be overwritten by author-defined attributes, but ensure that default semantics are retained should the author delete those attributes, or fail to add them at all. For more information see the [Accessibility Object Model explainer](https://wicg.github.io/aom/explainer.html#default-semantics-for-custom-elements-via-the-elementinternals-object). @@ -29,7 +29,14 @@ A string with one of the following values: In this example the value of `ariaLive` is set to "assertive". ```js -this.internals_.ariaLive = "assertive"; +class CustomControl extends HTMLElement { + constructor() { + super(); + this.internals_ = this.attachInternals(); + this.internals_.ariaLive = "assertive"; + } + // … +} ``` ## Specifications diff --git a/files/en-us/web/api/elementinternals/ariamodal/index.md b/files/en-us/web/api/elementinternals/ariamodal/index.md index 93b1e8a5aa8f22f..d43610618371da3 100644 --- a/files/en-us/web/api/elementinternals/ariamodal/index.md +++ b/files/en-us/web/api/elementinternals/ariamodal/index.md @@ -8,7 +8,7 @@ browser-compat: api.ElementInternals.ariaModal {{APIRef("Web Components")}} -The **`ariaModal`** property of the {{domxref("ElementInternals")}} interface reflects the value of the [`aria-modal`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-modal) attribute, which indicates whether an element is modal when displayed. +The **`ariaModal`** property of the {{domxref("ElementInternals")}} interface reflects the value of the [`aria-modal`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-modal) attribute, which indicates whether an element is modal when displayed. > [!NOTE] > Setting aria attributes on `ElementInternals` allows default semantics to be defined on a custom element. These may be overwritten by author-defined attributes, but ensure that default semantics are retained should the author delete those attributes, or fail to add them at all. For more information see the [Accessibility Object Model explainer](https://wicg.github.io/aom/explainer.html#default-semantics-for-custom-elements-via-the-elementinternals-object). @@ -27,7 +27,14 @@ A string with one of the following values: In this example the value of `ariaModal` is set to "true". ```js -this.internals_.ariaModal = "true"; +class CustomEl extends HTMLElement { + constructor() { + super(); + this.internals_ = this.attachInternals(); + this.internals_.ariaModal = "true"; + } + // … +} ``` ## Specifications @@ -40,4 +47,4 @@ this.internals_.ariaModal = "true"; ## See also -- [ARIA: dialog role](/en-US/docs/Web/Accessibility/ARIA/Roles/dialog_role) +- [ARIA: dialog role](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/dialog_role) diff --git a/files/en-us/web/api/elementinternals/ariamultiline/index.md b/files/en-us/web/api/elementinternals/ariamultiline/index.md index 8e9648ef2f941dd..defebfb5c250f97 100644 --- a/files/en-us/web/api/elementinternals/ariamultiline/index.md +++ b/files/en-us/web/api/elementinternals/ariamultiline/index.md @@ -8,7 +8,7 @@ browser-compat: api.ElementInternals.ariaMultiLine {{APIRef("Web Components")}} -The **`ariaMultiLine`** property of the {{domxref("ElementInternals")}} interface reflects the value of the [`aria-multiline`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-multiline) attribute, which indicates whether a text box accepts multiple lines of input or only a single line. +The **`ariaMultiLine`** property of the {{domxref("ElementInternals")}} interface reflects the value of the [`aria-multiline`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-multiline) attribute, which indicates whether a text box accepts multiple lines of input or only a single line. > [!NOTE] > Setting aria attributes on `ElementInternals` allows default semantics to be defined on a custom element. These may be overwritten by author-defined attributes, but ensure that default semantics are retained should the author delete those attributes, or fail to add them at all. For more information see the [Accessibility Object Model explainer](https://wicg.github.io/aom/explainer.html#default-semantics-for-custom-elements-via-the-elementinternals-object). @@ -27,7 +27,14 @@ A string with one of the following values: In this example the value of `ariaMultiLine` is set to "true". ```js -this.internals_.ariaMultiLine = "true"; +class CustomControl extends HTMLElement { + constructor() { + super(); + this.internals_ = this.attachInternals(); + this.internals_.ariaMultiLine = "true"; + } + // … +} ``` ## Specifications @@ -40,4 +47,4 @@ this.internals_.ariaMultiLine = "true"; ## See also -- [ARIA: textbox role](/en-US/docs/Web/Accessibility/ARIA/Roles/textbox_role) +- [ARIA: textbox role](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/textbox_role) diff --git a/files/en-us/web/api/elementinternals/ariamultiselectable/index.md b/files/en-us/web/api/elementinternals/ariamultiselectable/index.md index 74620cd9721019d..00ed748816e8935 100644 --- a/files/en-us/web/api/elementinternals/ariamultiselectable/index.md +++ b/files/en-us/web/api/elementinternals/ariamultiselectable/index.md @@ -8,7 +8,7 @@ browser-compat: api.ElementInternals.ariaMultiSelectable {{APIRef("Web Components")}} -The **`ariaMultiSelectable`** property of the {{domxref("ElementInternals")}} interface reflects the value of the [`aria-multiselectable`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-multiselectable) attribute, which indicates that the user may select more than one item from the current selectable descendants. +The **`ariaMultiSelectable`** property of the {{domxref("ElementInternals")}} interface reflects the value of the [`aria-multiselectable`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-multiselectable) attribute, which indicates that the user may select more than one item from the current selectable descendants. > [!NOTE] > Setting aria attributes on `ElementInternals` allows default semantics to be defined on a custom element. These may be overwritten by author-defined attributes, but ensure that default semantics are retained should the author delete those attributes, or fail to add them at all. For more information see the [Accessibility Object Model explainer](https://wicg.github.io/aom/explainer.html#default-semantics-for-custom-elements-via-the-elementinternals-object). @@ -27,7 +27,14 @@ A string with one of the following values: In this example the value of `ariaMultiSelectable` is set to "true". ```js -this.internals_.ariaMultiSelectable = "true"; +class CustomControl extends HTMLElement { + constructor() { + super(); + this.internals_ = this.attachInternals(); + this.internals_.ariaMultiSelectable = "true"; + } + // … +} ``` ## Specifications @@ -40,4 +47,4 @@ this.internals_.ariaMultiSelectable = "true"; ## See also -- [ARIA: listbox role](/en-US/docs/Web/Accessibility/ARIA/Roles/listbox_role) +- [ARIA: listbox role](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/listbox_role) diff --git a/files/en-us/web/api/elementinternals/ariaorientation/index.md b/files/en-us/web/api/elementinternals/ariaorientation/index.md index d92c4049a139760..e8aa286f2d9208d 100644 --- a/files/en-us/web/api/elementinternals/ariaorientation/index.md +++ b/files/en-us/web/api/elementinternals/ariaorientation/index.md @@ -8,7 +8,7 @@ browser-compat: api.ElementInternals.ariaOrientation {{APIRef("Web Components")}} -The **`ariaOrientation`** property of the {{domxref("ElementInternals")}} interface reflects the value of the [`aria-orientation`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-orientation) attribute, which indicates whether the element's orientation is horizontal, vertical, or unknown/ambiguous. +The **`ariaOrientation`** property of the {{domxref("ElementInternals")}} interface reflects the value of the [`aria-orientation`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-orientation) attribute, which indicates whether the element's orientation is horizontal, vertical, or unknown/ambiguous. > [!NOTE] > Setting aria attributes on `ElementInternals` allows default semantics to be defined on a custom element. These may be overwritten by author-defined attributes, but ensure that default semantics are retained should the author delete those attributes, or fail to add them at all. For more information see the [Accessibility Object Model explainer](https://wicg.github.io/aom/explainer.html#default-semantics-for-custom-elements-via-the-elementinternals-object). @@ -29,7 +29,14 @@ A string with one of the following values: In this example the value of `ariaOrientation` is set to "vertical". ```js -this.internals_.ariaOrientation = "vertical"; +class CustomEl extends HTMLElement { + constructor() { + super(); + this.internals_ = this.attachInternals(); + this.internals_.ariaOrientation = "vertical"; + } + // … +} ``` ## Specifications diff --git a/files/en-us/web/api/elementinternals/ariaownselements/index.md b/files/en-us/web/api/elementinternals/ariaownselements/index.md new file mode 100644 index 000000000000000..3ed5f37f23fd866 --- /dev/null +++ b/files/en-us/web/api/elementinternals/ariaownselements/index.md @@ -0,0 +1,51 @@ +--- +title: "ElementInternals: ariaOwnsElements property" +short-title: ariaOwnsElements +slug: Web/API/ElementInternals/ariaOwnsElements +page-type: web-api-instance-property +browser-compat: api.ElementInternals.ariaOwnsElements +--- + +{{APIRef("DOM")}} + +The **`ariaOwnsElements`** property of the {{domxref("ElementInternals")}} interface is an array containing the element (or elements) that define a visual, functional, or contextual relationship between a parent element that it is applied to, and its child elements. +This is used when the shadow DOM hierarchy cannot be used to represent the relationship, and it would not otherwise be available to assistive technology, + +The [`aria-owns`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-owns) topic contains additional information about how the attribute and property should be used. + +## Value + +An array of subclasses of {{domxref("HTMLElement")}}. + +When read, the returned array is a static and read-only. +When written, the assigned array is copied: subsequent changes to the array do not affect the value of the property. + +## Description + +The property is a flexible alternative to using the [`aria-owns`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-owns) attribute to indicate ownership of an element. +Unlike `aria-owns`, the elements assigned to this property do not have to have an [`id`](/en-US/docs/Web/HTML/Reference/Global_attributes/id) attribute. + +The property reflects the element's [`aria-owns`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-owns) attribute when it is defined, but only for listed reference `id` values that match valid in-scope elements. +If the property is set, then the corresponding attribute is cleared. +For more information about reflected element references and scope see [Reflected element references](/en-US/docs/Web/API/Document_Object_Model/Reflected_attributes#reflected_element_references) in the _Reflected attributes_ guide. + +## Examples + +The examples in the following documents are relevant: + +- {{domxref("Element.ariaOwnsElements")}} is the DOM equivalent of this property. + It is used in the same way, but within the DOM instead of a shadow DOM and/or custom element. + +## Specifications + +{{Specifications}} + +## Browser compatibility + +{{Compat}} + +## See also + +- [`aria-owns`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-owns) attribute +- {{domxref("Element.ariaOwnsElements")}} +- [Reflected element references](/en-US/docs/Web/API/Document_Object_Model/Reflected_attributes#reflected_element_references) in the _Attribute reflection_ guide. diff --git a/files/en-us/web/api/elementinternals/ariaplaceholder/index.md b/files/en-us/web/api/elementinternals/ariaplaceholder/index.md index 5652205c0336cf0..d027859e28185f4 100644 --- a/files/en-us/web/api/elementinternals/ariaplaceholder/index.md +++ b/files/en-us/web/api/elementinternals/ariaplaceholder/index.md @@ -8,7 +8,7 @@ browser-compat: api.ElementInternals.ariaPlaceholder {{APIRef("Web Components")}} -The **`ariaPlaceholder`** property of the {{domxref("ElementInternals")}} interface reflects the value of the [`aria-placeholder`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-placeholder) attribute, which defines a short hint intended to aid the user with data entry when the control has no value. +The **`ariaPlaceholder`** property of the {{domxref("ElementInternals")}} interface reflects the value of the [`aria-placeholder`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-placeholder) attribute, which defines a short hint intended to aid the user with data entry when the control has no value. > [!NOTE] > Setting aria attributes on `ElementInternals` allows default semantics to be defined on a custom element. These may be overwritten by author-defined attributes, but ensure that default semantics are retained should the author delete those attributes, or fail to add them at all. For more information see the [Accessibility Object Model explainer](https://wicg.github.io/aom/explainer.html#default-semantics-for-custom-elements-via-the-elementinternals-object). @@ -22,7 +22,14 @@ A string. In this example the value of `ariaPlaceholder` is set to "12345". ```js -this.internals_.ariaPlaceholder = "12345"; +class CustomControl extends HTMLElement { + constructor() { + super(); + this.internals_ = this.attachInternals(); + this.internals_.ariaPlaceholder = "12345"; + } + // … +} ``` ## Specifications @@ -35,4 +42,4 @@ this.internals_.ariaPlaceholder = "12345"; ## See also -- [ARIA: textbox role](/en-US/docs/Web/Accessibility/ARIA/Roles/textbox_role) +- [ARIA: textbox role](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/textbox_role) diff --git a/files/en-us/web/api/elementinternals/ariaposinset/index.md b/files/en-us/web/api/elementinternals/ariaposinset/index.md index a02fda221de206f..e6b572531ea1bb9 100644 --- a/files/en-us/web/api/elementinternals/ariaposinset/index.md +++ b/files/en-us/web/api/elementinternals/ariaposinset/index.md @@ -8,7 +8,7 @@ browser-compat: api.ElementInternals.ariaPosInSet {{APIRef("Web Components")}} -The **`ariaPosInSet`** property of the {{domxref("ElementInternals")}} interface reflects the value of the [`aria-posinset`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-posinset) attribute, which defines an element's number or position in the current set of listitems or treeitems. +The **`ariaPosInSet`** property of the {{domxref("ElementInternals")}} interface reflects the value of the [`aria-posinset`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-posinset) attribute, which defines an element's number or position in the current set of listitems or treeitems. > [!NOTE] > Setting aria attributes on `ElementInternals` allows default semantics to be defined on a custom element. These may be overwritten by author-defined attributes, but ensure that default semantics are retained should the author delete those attributes, or fail to add them at all. For more information see the [Accessibility Object Model explainer](https://wicg.github.io/aom/explainer.html#default-semantics-for-custom-elements-via-the-elementinternals-object). @@ -22,7 +22,14 @@ A string containing an integer. In this example the value of `ariaPosInSet` is set to "2". ```js -this.internals_.ariaPosInSet = "2"; +class CustomControl extends HTMLElement { + constructor() { + super(); + this.internals_ = this.attachInternals(); + this.internals_.ariaPosInSet = "2"; + } + // … +} ``` ## Specifications diff --git a/files/en-us/web/api/elementinternals/ariapressed/index.md b/files/en-us/web/api/elementinternals/ariapressed/index.md index 71ac95e3bfe99af..1befb8aa1bf191a 100644 --- a/files/en-us/web/api/elementinternals/ariapressed/index.md +++ b/files/en-us/web/api/elementinternals/ariapressed/index.md @@ -8,7 +8,7 @@ browser-compat: api.ElementInternals.ariaPressed {{APIRef("Web Components")}} -The **`ariaPressed`** property of the {{domxref("ElementInternals")}} interface reflects the value of the [`aria-pressed`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-pressed) attribute, which indicates the current "pressed" state of toggle buttons. +The **`ariaPressed`** property of the {{domxref("ElementInternals")}} interface reflects the value of the [`aria-pressed`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-pressed) attribute, which indicates the current "pressed" state of toggle buttons. > [!NOTE] > Setting aria attributes on `ElementInternals` allows default semantics to be defined on a custom element. These may be overwritten by author-defined attributes, but ensure that default semantics are retained should the author delete those attributes, or fail to add them at all. For more information see the [Accessibility Object Model explainer](https://wicg.github.io/aom/explainer.html#default-semantics-for-custom-elements-via-the-elementinternals-object). @@ -31,7 +31,14 @@ A string with one of the following values: In this example the value of `ariaPressed` is set to "true". ```js -this.internals_.ariaPressed = "true"; +class CustomControl extends HTMLElement { + constructor() { + super(); + this.internals_ = this.attachInternals(); + this.internals_.ariaPressed = "true"; + } + // … +} ``` ## Specifications @@ -44,4 +51,4 @@ this.internals_.ariaPressed = "true"; ## See also -- [ARIA: button role](/en-US/docs/Web/Accessibility/ARIA/Roles/button_role) +- [ARIA: button role](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/button_role) diff --git a/files/en-us/web/api/elementinternals/ariareadonly/index.md b/files/en-us/web/api/elementinternals/ariareadonly/index.md index dc8f5091b9e0a84..abba7d85d58b0c0 100644 --- a/files/en-us/web/api/elementinternals/ariareadonly/index.md +++ b/files/en-us/web/api/elementinternals/ariareadonly/index.md @@ -8,7 +8,7 @@ browser-compat: api.ElementInternals.ariaReadOnly {{APIRef("Web Components")}} -The **`ariaReadOnly`** property of the {{domxref("ElementInternals")}} interface reflects the value of the [`aria-readonly`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-readonly) attribute, which indicates that the element is not editable, but is otherwise operable. +The **`ariaReadOnly`** property of the {{domxref("ElementInternals")}} interface reflects the value of the [`aria-readonly`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-readonly) attribute, which indicates that the element is not editable, but is otherwise operable. > [!NOTE] > Setting aria attributes on `ElementInternals` allows default semantics to be defined on a custom element. These may be overwritten by author-defined attributes, but ensure that default semantics are retained should the author delete those attributes, or fail to add them at all. For more information see the [Accessibility Object Model explainer](https://wicg.github.io/aom/explainer.html#default-semantics-for-custom-elements-via-the-elementinternals-object). @@ -27,7 +27,14 @@ A string with one of the following values: In this example the value of `ariaReadOnly` is set to "true". ```js -this.internals_.ariaReadonly = "true"; +class CustomControl extends HTMLElement { + constructor() { + super(); + this.internals_ = this.attachInternals(); + this.internals_.ariaReadonly = "true"; + } + // … +} ``` ## Specifications @@ -40,4 +47,4 @@ this.internals_.ariaReadonly = "true"; ## See also -- [ARIA: textbox role](/en-US/docs/Web/Accessibility/ARIA/Roles/textbox_role) +- [ARIA: textbox role](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/textbox_role) diff --git a/files/en-us/web/api/elementinternals/ariarelevant/index.md b/files/en-us/web/api/elementinternals/ariarelevant/index.md index b586a475aa2bcf4..02c690b87ab7dc9 100644 --- a/files/en-us/web/api/elementinternals/ariarelevant/index.md +++ b/files/en-us/web/api/elementinternals/ariarelevant/index.md @@ -10,7 +10,7 @@ browser-compat: api.ElementInternals.ariaRelevant {{APIRef("Web Components")}}{{Non-standard_header}} -The **`ariaRelevant`** property of the {{domxref("ElementInternals")}} interface reflects the value of the [`aria-relevant`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-relevant) attribute, which indicates what notifications the user agent will trigger when the accessibility tree within a live region is modified. This is used to describe what changes in an `aria-live` region are relevant and should be announced. +The **`ariaRelevant`** property of the {{domxref("ElementInternals")}} interface reflects the value of the [`aria-relevant`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-relevant) attribute, which indicates what notifications the user agent will trigger when the accessibility tree within a live region is modified. This is used to describe what changes in an `aria-live` region are relevant and should be announced. > [!NOTE] > Setting aria attributes on `ElementInternals` allows default semantics to be defined on a custom element. These may be overwritten by author-defined attributes, but ensure that default semantics are retained should the author delete those attributes, or fail to add them at all. For more information see the [Accessibility Object Model explainer](https://wicg.github.io/aom/explainer.html#default-semantics-for-custom-elements-via-the-elementinternals-object). @@ -33,7 +33,14 @@ A string containing one or more of the following values, space separated: In this example the value of `ariaRelevant` is set to "all". ```js -this.internals_.ariaRelevant = "all"; +class CustomEl extends HTMLElement { + constructor() { + super(); + this.internals_ = this.attachInternals(); + this.internals_.ariaRelevant = "all"; + } + // … +} ``` ## Browser compatibility diff --git a/files/en-us/web/api/elementinternals/ariarequired/index.md b/files/en-us/web/api/elementinternals/ariarequired/index.md index 21e32fbcfe29f2b..e113618a1e67962 100644 --- a/files/en-us/web/api/elementinternals/ariarequired/index.md +++ b/files/en-us/web/api/elementinternals/ariarequired/index.md @@ -8,7 +8,7 @@ browser-compat: api.ElementInternals.ariaRequired {{APIRef("Web Components")}} -The **`ariaRequired`** property of the {{domxref("ElementInternals")}} interface reflects the value of the [`aria-required`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-required) attribute, which indicates that user input is required on the element before a form may be submitted. +The **`ariaRequired`** property of the {{domxref("ElementInternals")}} interface reflects the value of the [`aria-required`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-required) attribute, which indicates that user input is required on the element before a form may be submitted. > [!NOTE] > Setting aria attributes on `ElementInternals` allows default semantics to be defined on a custom element. These may be overwritten by author-defined attributes, but ensure that default semantics are retained should the author delete those attributes, or fail to add them at all. For more information see the [Accessibility Object Model explainer](https://wicg.github.io/aom/explainer.html#default-semantics-for-custom-elements-via-the-elementinternals-object). @@ -27,7 +27,14 @@ A string with one of the following values: In this example the value of `ariaRequired` is set to "true". ```js -this.internals_.ariaRequired = "true"; +class CustomControl extends HTMLElement { + constructor() { + super(); + this.internals_ = this.attachInternals(); + this.internals_.ariaRequired = "true"; + } + // … +} ``` ## Specifications @@ -40,4 +47,4 @@ this.internals_.ariaRequired = "true"; ## See also -- [ARIA: textbox role](/en-US/docs/Web/Accessibility/ARIA/Roles/textbox_role) +- [ARIA: textbox role](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/textbox_role) diff --git a/files/en-us/web/api/elementinternals/ariaroledescription/index.md b/files/en-us/web/api/elementinternals/ariaroledescription/index.md index d11b191b6da04a5..2984ed138ca8959 100644 --- a/files/en-us/web/api/elementinternals/ariaroledescription/index.md +++ b/files/en-us/web/api/elementinternals/ariaroledescription/index.md @@ -8,7 +8,7 @@ browser-compat: api.ElementInternals.ariaRoleDescription {{APIRef("Web Components")}} -The **`ariaRoleDescription`** property of the {{domxref("ElementInternals")}} interface reflects the value of the [`aria-roledescription`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-roledescription) attribute, which defines a human-readable, author-localized description for the role of an element. +The **`ariaRoleDescription`** property of the {{domxref("ElementInternals")}} interface reflects the value of the [`aria-roledescription`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-roledescription) attribute, which defines a human-readable, author-localized description for the role of an element. > [!NOTE] > Setting aria attributes on `ElementInternals` allows default semantics to be defined on a custom element. These may be overwritten by author-defined attributes, but ensure that default semantics are retained should the author delete those attributes, or fail to add them at all. For more information see the [Accessibility Object Model explainer](https://wicg.github.io/aom/explainer.html#default-semantics-for-custom-elements-via-the-elementinternals-object). @@ -22,7 +22,14 @@ A string. In this example the value of `ariaRoleDescription` is set to "My custom widget". ```js -this.internals_.ariaRoleDescription = "My custom widget"; +class CustomEl extends HTMLElement { + constructor() { + super(); + this.internals_ = this.attachInternals(); + this.internals_.ariaRoleDescription = "My custom widget"; + } + // … +} ``` ## Specifications @@ -35,4 +42,4 @@ this.internals_.ariaRoleDescription = "My custom widget"; ## See also -- [ARIA: application role](/en-US/docs/Web/Accessibility/ARIA/Roles/application_role) +- [ARIA: application role](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/application_role) diff --git a/files/en-us/web/api/elementinternals/ariarowcount/index.md b/files/en-us/web/api/elementinternals/ariarowcount/index.md index 2ea37dcc85bdfbc..c8165fc97ecd72e 100644 --- a/files/en-us/web/api/elementinternals/ariarowcount/index.md +++ b/files/en-us/web/api/elementinternals/ariarowcount/index.md @@ -8,7 +8,7 @@ browser-compat: api.ElementInternals.ariaRowCount {{APIRef("Web Components")}} -The **`ariaRowCount`** property of the {{domxref("ElementInternals")}} interface reflects the value of the [`aria-rowcount`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-rowcount) attribute, which defines the total number of rows in a table, grid, or treegrid. +The **`ariaRowCount`** property of the {{domxref("ElementInternals")}} interface reflects the value of the [`aria-rowcount`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-rowcount) attribute, which defines the total number of rows in a table, grid, or treegrid. > [!NOTE] > Setting aria attributes on `ElementInternals` allows default semantics to be defined on a custom element. These may be overwritten by author-defined attributes, but ensure that default semantics are retained should the author delete those attributes, or fail to add them at all. For more information see the [Accessibility Object Model explainer](https://wicg.github.io/aom/explainer.html#default-semantics-for-custom-elements-via-the-elementinternals-object). @@ -22,7 +22,14 @@ A string which contains an integer. In this example the value of `ariaRowCount` is set to "100". ```js -this.internals_.ariaRowCount = "100"; +class CustomEl extends HTMLElement { + constructor() { + super(); + this.internals_ = this.attachInternals(); + this.internals_.ariaRowCount = "100"; + } + // … +} ``` ## Specifications @@ -35,4 +42,4 @@ this.internals_.ariaRowCount = "100"; ## See also -- [ARIA: table role](/en-US/docs/Web/Accessibility/ARIA/Roles/table_role) +- [ARIA: table role](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/table_role) diff --git a/files/en-us/web/api/elementinternals/ariarowindex/index.md b/files/en-us/web/api/elementinternals/ariarowindex/index.md index 9bac7e6c8452d92..2378b9c2d0c6c1c 100644 --- a/files/en-us/web/api/elementinternals/ariarowindex/index.md +++ b/files/en-us/web/api/elementinternals/ariarowindex/index.md @@ -8,7 +8,7 @@ browser-compat: api.ElementInternals.ariaRowIndex {{APIRef("Web Components")}} -The **`ariaRowIndex`** property of the {{domxref("ElementInternals")}} interface reflects the value of the [`aria-rowindex`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-rowindex) attribute, which defines an element's row index or position with respect to the total number of rows within a table, grid, or treegrid. +The **`ariaRowIndex`** property of the {{domxref("ElementInternals")}} interface reflects the value of the [`aria-rowindex`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-rowindex) attribute, which defines an element's row index or position with respect to the total number of rows within a table, grid, or treegrid. > [!NOTE] > Setting aria attributes on `ElementInternals` allows default semantics to be defined on a custom element. These may be overwritten by author-defined attributes, but ensure that default semantics are retained should the author delete those attributes, or fail to add them at all. For more information see the [Accessibility Object Model explainer](https://wicg.github.io/aom/explainer.html#default-semantics-for-custom-elements-via-the-elementinternals-object). @@ -22,7 +22,14 @@ A string which contains an integer. In this example the value of `ariaRowIndex` is set to "1". ```js -this.internals_.ariaRowIndex = "1"; +class CustomEl extends HTMLElement { + constructor() { + super(); + this.internals_ = this.attachInternals(); + this.internals_.ariaRowIndex = "1"; + } + // … +} ``` ## Specifications @@ -35,4 +42,4 @@ this.internals_.ariaRowIndex = "1"; ## See also -- [ARIA: table role](/en-US/docs/Web/Accessibility/ARIA/Roles/table_role) +- [ARIA: table role](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/table_role) diff --git a/files/en-us/web/api/elementinternals/ariarowindextext/index.md b/files/en-us/web/api/elementinternals/ariarowindextext/index.md index c02bdd6f68ccec8..6ce8eca78109ef9 100644 --- a/files/en-us/web/api/elementinternals/ariarowindextext/index.md +++ b/files/en-us/web/api/elementinternals/ariarowindextext/index.md @@ -7,7 +7,7 @@ browser-compat: api.ElementInternals.ariaRowIndexText {{APIRef("Web Components")}} -The **`ariaRowIndexText`** property of the {{domxref("ElementInternals")}} interface reflects the value of the [`aria-rowindextext`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-rowindextext) attribute, which defines a human readable text alternative of aria-rowindex. +The **`ariaRowIndexText`** property of the {{domxref("ElementInternals")}} interface reflects the value of the [`aria-rowindextext`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-rowindextext) attribute, which defines a human readable text alternative of aria-rowindex. > [!NOTE] > Setting aria attributes on `ElementInternals` allows default semantics to be defined on a custom element. These may be overwritten by author-defined attributes, but ensure that default semantics are retained should the author delete those attributes, or fail to add them at all. For more information see the [Accessibility Object Model explainer](https://wicg.github.io/aom/explainer.html#default-semantics-for-custom-elements-via-the-elementinternals-object). @@ -21,7 +21,14 @@ A string. In this example the value of `ariaRowIndexText` is set to "Heading row". ```js -this.internals_.ariaRowIndexText = "Heading row"; +class CustomEl extends HTMLElement { + constructor() { + super(); + this.internals_ = this.attachInternals(); + this.internals_.ariaRowIndexText = "Heading row"; + } + // … +} ``` ## Specifications @@ -34,4 +41,4 @@ this.internals_.ariaRowIndexText = "Heading row"; ## See also -- [ARIA: table role](/en-US/docs/Web/Accessibility/ARIA/Roles/table_role) +- [ARIA: table role](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/table_role) diff --git a/files/en-us/web/api/elementinternals/ariarowspan/index.md b/files/en-us/web/api/elementinternals/ariarowspan/index.md index 0c9679bc7b2e2c0..424003b102a2d77 100644 --- a/files/en-us/web/api/elementinternals/ariarowspan/index.md +++ b/files/en-us/web/api/elementinternals/ariarowspan/index.md @@ -8,7 +8,7 @@ browser-compat: api.ElementInternals.ariaRowSpan {{APIRef("Web Components")}} -The **`ariaRowSpan`** property of the {{domxref("ElementInternals")}} interface reflects the value of the [`aria-rowspan`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-rowspan) attribute, which defines the number of rows spanned by a cell or gridcell within a table, grid, or treegrid. +The **`ariaRowSpan`** property of the {{domxref("ElementInternals")}} interface reflects the value of the [`aria-rowspan`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-rowspan) attribute, which defines the number of rows spanned by a cell or gridcell within a table, grid, or treegrid. > [!NOTE] > Setting aria attributes on `ElementInternals` allows default semantics to be defined on a custom element. These may be overwritten by author-defined attributes, but ensure that default semantics are retained should the author delete those attributes, or fail to add them at all. For more information see the [Accessibility Object Model explainer](https://wicg.github.io/aom/explainer.html#default-semantics-for-custom-elements-via-the-elementinternals-object). @@ -22,7 +22,14 @@ A string which contains an integer. In this example the value of `ariaRowSpan` is set to "2". ```js -this.internals_.ariaRowSpan = "2"; +class CustomEl extends HTMLElement { + constructor() { + super(); + this.internals_ = this.attachInternals(); + this.internals_.ariaRowSpan = "2"; + } + // … +} ``` ## Specifications @@ -35,4 +42,4 @@ this.internals_.ariaRowSpan = "2"; ## See also -- [ARIA: table role](/en-US/docs/Web/Accessibility/ARIA/Roles/table_role) +- [ARIA: table role](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/table_role) diff --git a/files/en-us/web/api/elementinternals/ariaselected/index.md b/files/en-us/web/api/elementinternals/ariaselected/index.md index 87380ee001f5a75..48c6b21912f3d68 100644 --- a/files/en-us/web/api/elementinternals/ariaselected/index.md +++ b/files/en-us/web/api/elementinternals/ariaselected/index.md @@ -8,7 +8,7 @@ browser-compat: api.ElementInternals.ariaSelected {{APIRef("Web Components")}} -The **`ariaSelected`** property of the {{domxref("ElementInternals")}} interface reflects the value of the [`aria-selected`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-selected) attribute, which indicates the current "selected" state of elements that have a selected state. +The **`ariaSelected`** property of the {{domxref("ElementInternals")}} interface reflects the value of the [`aria-selected`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-selected) attribute, which indicates the current "selected" state of elements that have a selected state. > [!NOTE] > Setting aria attributes on `ElementInternals` allows default semantics to be defined on a custom element. These may be overwritten by author-defined attributes, but ensure that default semantics are retained should the author delete those attributes, or fail to add them at all. For more information see the [Accessibility Object Model explainer](https://wicg.github.io/aom/explainer.html#default-semantics-for-custom-elements-via-the-elementinternals-object). @@ -29,7 +29,14 @@ A string with one of the following values: In this example the value of `ariaSelected` is set to "true". ```js -this.internals_.ariaSelected = "true"; +class CustomControl extends HTMLElement { + constructor() { + super(); + this.internals_ = this.attachInternals(); + this.internals_.ariaSelected = "true"; + } + // … +} ``` ## Specifications @@ -42,4 +49,4 @@ this.internals_.ariaSelected = "true"; ## See also -- [ARIA: tab role](/en-US/docs/Web/Accessibility/ARIA/Roles/tab_role) +- [ARIA: tab role](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/tab_role) diff --git a/files/en-us/web/api/elementinternals/ariasetsize/index.md b/files/en-us/web/api/elementinternals/ariasetsize/index.md index 99fdf4d5b4c8b0d..1c958ff86fef34c 100644 --- a/files/en-us/web/api/elementinternals/ariasetsize/index.md +++ b/files/en-us/web/api/elementinternals/ariasetsize/index.md @@ -8,7 +8,7 @@ browser-compat: api.ElementInternals.ariaSetSize {{APIRef("Web Components")}} -The **`ariaSetSize`** property of the {{domxref("ElementInternals")}} interface reflects the value of the [`aria-setsize`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-setsize) attribute, which defines the number of items in the current set of listitems or treeitems. +The **`ariaSetSize`** property of the {{domxref("ElementInternals")}} interface reflects the value of the [`aria-setsize`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-setsize) attribute, which defines the number of items in the current set of listitems or treeitems. > [!NOTE] > Setting aria attributes on `ElementInternals` allows default semantics to be defined on a custom element. These may be overwritten by author-defined attributes, but ensure that default semantics are retained should the author delete those attributes, or fail to add them at all. For more information see the [Accessibility Object Model explainer](https://wicg.github.io/aom/explainer.html#default-semantics-for-custom-elements-via-the-elementinternals-object). @@ -22,7 +22,14 @@ A string containing an integer. In this example the value of `ariaSetSize` is set to "4". ```js -this.internals_.ariaSetSize = "4"; +class CustomControl extends HTMLElement { + constructor() { + super(); + this.internals_ = this.attachInternals(); + this.internals_.ariaSetSize = "4"; + } + // … +} ``` ## Specifications @@ -35,4 +42,4 @@ this.internals_.ariaSetSize = "4"; ## See also -- [ARIA: tab role](/en-US/docs/Web/Accessibility/ARIA/Roles/tab_role) +- [ARIA: tab role](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/tab_role) diff --git a/files/en-us/web/api/elementinternals/ariasort/index.md b/files/en-us/web/api/elementinternals/ariasort/index.md index 7d0e2115ddc12f2..4ef5cfe284271b7 100644 --- a/files/en-us/web/api/elementinternals/ariasort/index.md +++ b/files/en-us/web/api/elementinternals/ariasort/index.md @@ -8,7 +8,7 @@ browser-compat: api.ElementInternals.ariaSort {{APIRef("Web Components")}} -The **`ariaSort`** property of the {{domxref("ElementInternals")}} interface reflects the value of the [`aria-sort`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-sort) attribute, which indicates if items in a table or grid are sorted in ascending or descending order. +The **`ariaSort`** property of the {{domxref("ElementInternals")}} interface reflects the value of the [`aria-sort`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-sort) attribute, which indicates if items in a table or grid are sorted in ascending or descending order. > [!NOTE] > Setting aria attributes on `ElementInternals` allows default semantics to be defined on a custom element. These may be overwritten by author-defined attributes, but ensure that default semantics are retained should the author delete those attributes, or fail to add them at all. For more information see the [Accessibility Object Model explainer](https://wicg.github.io/aom/explainer.html#default-semantics-for-custom-elements-via-the-elementinternals-object). @@ -31,7 +31,14 @@ A string with one of the following values: In this example the value of `ariaSort` is set to "ascending". ```js -this.internals_.ariaSort = "ascending"; +class CustomControl extends HTMLElement { + constructor() { + super(); + this.internals_ = this.attachInternals(); + this.internals_.ariaSort = "ascending"; + } + // … +} ``` ## Specifications @@ -44,4 +51,4 @@ this.internals_.ariaSort = "ascending"; ## See also -- [ARIA: table role](/en-US/docs/Web/Accessibility/ARIA/Roles/table_role) +- [ARIA: table role](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/table_role) diff --git a/files/en-us/web/api/elementinternals/ariavaluemax/index.md b/files/en-us/web/api/elementinternals/ariavaluemax/index.md index 72abfff85cfa7a5..3031d7566d6c8ed 100644 --- a/files/en-us/web/api/elementinternals/ariavaluemax/index.md +++ b/files/en-us/web/api/elementinternals/ariavaluemax/index.md @@ -8,7 +8,7 @@ browser-compat: api.ElementInternals.ariaValueMax {{APIRef("Web Components")}} -The **`ariaValueMax`** property of the {{domxref("ElementInternals")}} interface reflects the value of the [`aria-valuemax`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-valuemax) attribute, which defines the maximum allowed value for a range widget. +The **`ariaValueMax`** property of the {{domxref("ElementInternals")}} interface reflects the value of the [`aria-valuemax`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-valuemax) attribute, which defines the maximum allowed value for a range widget. > [!NOTE] > Setting aria attributes on `ElementInternals` allows default semantics to be defined on a custom element. These may be overwritten by author-defined attributes, but ensure that default semantics are retained should the author delete those attributes, or fail to add them at all. For more information see the [Accessibility Object Model explainer](https://wicg.github.io/aom/explainer.html#default-semantics-for-custom-elements-via-the-elementinternals-object). @@ -22,7 +22,14 @@ A string which contains a number. In this example the value of `ariaValueMax` is set to "20". ```js -this.internals_.ariaValueMax = "20"; +class CustomControl extends HTMLElement { + constructor() { + super(); + this.internals_ = this.attachInternals(); + this.internals_.ariaValueMax = "20"; + } + // … +} ``` ## Specifications diff --git a/files/en-us/web/api/elementinternals/ariavaluemin/index.md b/files/en-us/web/api/elementinternals/ariavaluemin/index.md index 3ece0405e137480..9a60d1de166ea3e 100644 --- a/files/en-us/web/api/elementinternals/ariavaluemin/index.md +++ b/files/en-us/web/api/elementinternals/ariavaluemin/index.md @@ -8,7 +8,7 @@ browser-compat: api.ElementInternals.ariaValueMin {{APIRef("Web Components")}} -The **`ariaValueMin`** property of the {{domxref("ElementInternals")}} interface reflects the value of the [`aria-valuemin`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-valuemin) attribute, which defines the minimum allowed value for a range widget. +The **`ariaValueMin`** property of the {{domxref("ElementInternals")}} interface reflects the value of the [`aria-valuemin`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-valuemin) attribute, which defines the minimum allowed value for a range widget. > [!NOTE] > Setting aria attributes on `ElementInternals` allows default semantics to be defined on a custom element. These may be overwritten by author-defined attributes, but ensure that default semantics are retained should the author delete those attributes, or fail to add them at all. For more information see the [Accessibility Object Model explainer](https://wicg.github.io/aom/explainer.html#default-semantics-for-custom-elements-via-the-elementinternals-object). @@ -22,7 +22,14 @@ A string which contains a number. In this example the value of `ariaValueMin` is set to "10". ```js -this.internals_.ariaValueMin = "10"; +class CustomControl extends HTMLElement { + constructor() { + super(); + this.internals_ = this.attachInternals(); + this.internals_.ariaValueMin = "10"; + } + // … +} ``` ## Specifications diff --git a/files/en-us/web/api/elementinternals/ariavaluenow/index.md b/files/en-us/web/api/elementinternals/ariavaluenow/index.md index 29b3670f81d0ec4..d1c3c52d80ed1c9 100644 --- a/files/en-us/web/api/elementinternals/ariavaluenow/index.md +++ b/files/en-us/web/api/elementinternals/ariavaluenow/index.md @@ -8,7 +8,7 @@ browser-compat: api.ElementInternals.ariaValueNow {{APIRef("Web Components")}} -The **`ariaValueNow`** property of the {{domxref("ElementInternals")}} interface reflects the value of the [`aria-valuenow`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-valuenow) attribute, which defines the current value for a range widget. +The **`ariaValueNow`** property of the {{domxref("ElementInternals")}} interface reflects the value of the [`aria-valuenow`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-valuenow) attribute, which defines the current value for a range widget. > [!NOTE] > Setting aria attributes on `ElementInternals` allows default semantics to be defined on a custom element. These may be overwritten by author-defined attributes, but ensure that default semantics are retained should the author delete those attributes, or fail to add them at all. For more information see the [Accessibility Object Model explainer](https://wicg.github.io/aom/explainer.html#default-semantics-for-custom-elements-via-the-elementinternals-object). @@ -22,7 +22,14 @@ A string which contains a number. In this example the value of `ariaValueNow` is set to "1". ```js -this.internals_.ariaValueNow = "1"; +class CustomControl extends HTMLElement { + constructor() { + super(); + this.internals_ = this.attachInternals(); + this.internals_.ariaValueNow = "1"; + } + // … +} ``` ## Specifications diff --git a/files/en-us/web/api/elementinternals/ariavaluetext/index.md b/files/en-us/web/api/elementinternals/ariavaluetext/index.md index 57b8187f9135de2..be59b8cef5da0ac 100644 --- a/files/en-us/web/api/elementinternals/ariavaluetext/index.md +++ b/files/en-us/web/api/elementinternals/ariavaluetext/index.md @@ -8,7 +8,7 @@ browser-compat: api.ElementInternals.ariaValueText {{APIRef("Web Components")}} -The **`ariaValueText`** property of the {{domxref("ElementInternals")}} interface reflects the value of the [`aria-valuetext`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-valuetext) attribute, which defines the human-readable text alternative of aria-valuenow for a range widget. +The **`ariaValueText`** property of the {{domxref("ElementInternals")}} interface reflects the value of the [`aria-valuetext`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-valuetext) attribute, which defines the human-readable text alternative of aria-valuenow for a range widget. > [!NOTE] > Setting aria attributes on `ElementInternals` allows default semantics to be defined on a custom element. These may be overwritten by author-defined attributes, but ensure that default semantics are retained should the author delete those attributes, or fail to add them at all. For more information see the [Accessibility Object Model explainer](https://wicg.github.io/aom/explainer.html#default-semantics-for-custom-elements-via-the-elementinternals-object). @@ -22,7 +22,14 @@ A string. In this example the value of `ariaValueText` is set to "Sunday". ```js -this.internals_.ariaValueText = "Sunday"; +class CustomControl extends HTMLElement { + constructor() { + super(); + this.internals_ = this.attachInternals(); + this.internals_.ariaValueText = "Sunday"; + } + // … +} ``` ## Specifications diff --git a/files/en-us/web/api/elementinternals/checkvalidity/index.md b/files/en-us/web/api/elementinternals/checkvalidity/index.md index 9542d39d70c4f50..0e3afef4cb88b39 100644 --- a/files/en-us/web/api/elementinternals/checkvalidity/index.md +++ b/files/en-us/web/api/elementinternals/checkvalidity/index.md @@ -8,7 +8,7 @@ browser-compat: api.ElementInternals.checkValidity {{APIRef("Web Components")}} -The **`checkValidity()`** method of the {{domxref("ElementInternals")}} interface checks if the element meets any [constraint validation](/en-US/docs/Web/HTML/Constraint_validation) rules applied to it. +The **`checkValidity()`** method of the {{domxref("ElementInternals")}} interface checks if the element meets any [constraint validation](/en-US/docs/Web/HTML/Guides/Constraint_validation) rules applied to it. If `checkValidity` returns `false` then a cancelable [invalid event](/en-US/docs/Web/API/HTMLInputElement/invalid_event) is fired on the element. diff --git a/files/en-us/web/api/elementinternals/index.md b/files/en-us/web/api/elementinternals/index.md index 1f2d04a1232d8d3..b325e6217c0c836 100644 --- a/files/en-us/web/api/elementinternals/index.md +++ b/files/en-us/web/api/elementinternals/index.md @@ -23,7 +23,7 @@ This interface has no constructor. An `ElementInternals` object is returned when - : Returns the {{domxref("CustomStateSet")}} associated with this element. - {{domxref("ElementInternals.willValidate")}} {{ReadOnlyInline}} - : A boolean value which returns true if the element is a submittable element that is a candidate for - [constraint validation](/en-US/docs/Web/HTML/Constraint_validation). + [constraint validation](/en-US/docs/Web/HTML/Guides/Constraint_validation). - {{domxref("ElementInternals.validity")}} {{ReadOnlyInline}} - : Returns a {{domxref("ValidityState")}} object which represents the different validity states the element can be in, with respect to constraint validation. - {{domxref("ElementInternals.validationMessage")}} {{ReadOnlyInline}} @@ -39,87 +39,123 @@ The `ElementInternals` interface also includes the following properties. > These are included in order that default accessibility semantics can be defined on a custom element. These may be overwritten by author-defined attributes, but ensure that default semantics are retained should the author delete those attributes, or fail to add them at all. For more information see the [Accessibility Object Model explainer](https://wicg.github.io/aom/explainer.html#default-semantics-for-custom-elements-via-the-elementinternals-object). - {{domxref("ElementInternals.ariaAtomic")}} - - : A string reflecting the [`aria-atomic`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-atomic) attribute, which indicates whether assistive technologies will present all, or only parts of, the changed region based on the change notifications defined by the [`aria-relevant`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-relevant) attribute. + - : A string reflecting the [`aria-atomic`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-atomic) attribute, which indicates whether assistive technologies will present all, or only parts of, the changed region based on the change notifications defined by the [`aria-relevant`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-relevant) attribute. - {{domxref("ElementInternals.ariaAutoComplete")}} - - : A string reflecting the [`aria-autocomplete`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-autocomplete) attribute, which indicates whether inputting text could trigger display of one or more predictions of the user's intended value for a combobox, searchbox, or textbox and specifies how predictions would be presented if they were made. + - : A string reflecting the [`aria-autocomplete`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-autocomplete) attribute, which indicates whether inputting text could trigger display of one or more predictions of the user's intended value for a combobox, searchbox, or textbox and specifies how predictions would be presented if they were made. +- {{domxref("ElementInternals.ariaBrailleLabel")}} + - : A string reflecting the [`aria-braillelabel`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-braillelabel) attribute, which defines the braille label of the element. +- {{domxref("ElementInternals.ariaBrailleRoleDescription")}} + - : A string reflecting the [`aria-brailleroledescription`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-brailleroledescription) attribute, which defines the ARIA braille role description of the element. - {{domxref("ElementInternals.ariaBusy")}} - - : A string reflecting the [`aria-busy`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-busy) attribute, which indicates whether an element is being modified, as assistive technologies may want to wait until the modifications are complete before exposing them to the user. + - : A string reflecting the [`aria-busy`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-busy) attribute, which indicates whether an element is being modified, as assistive technologies may want to wait until the modifications are complete before exposing them to the user. - {{domxref("ElementInternals.ariaChecked")}} - - : A string reflecting the [`aria-checked`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-checked) attribute, which indicates the current "checked" state of checkboxes, radio buttons, and other widgets that have a checked state. + - : A string reflecting the [`aria-checked`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-checked) attribute, which indicates the current "checked" state of checkboxes, radio buttons, and other widgets that have a checked state. - {{domxref("ElementInternals.ariaColCount")}} - - : A string reflecting the [`aria-colcount`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-colcount) attribute, which defines the number of columns in a table, grid, or treegrid. + - : A string reflecting the [`aria-colcount`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-colcount) attribute, which defines the number of columns in a table, grid, or treegrid. - {{domxref("ElementInternals.ariaColIndex")}} - - : A string reflecting the [`aria-colindex`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-colindex) attribute, which defines an element's column index or position with respect to the total number of columns within a table, grid, or treegrid. + - : A string reflecting the [`aria-colindex`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-colindex) attribute, which defines an element's column index or position with respect to the total number of columns within a table, grid, or treegrid. - {{domxref("ElementInternals.ariaColIndexText")}} - - : A string reflecting the [`aria-colindextext`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-colindextext) attribute, which defines a human readable text alternative of aria-colindex. + - : A string reflecting the [`aria-colindextext`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-colindextext) attribute, which defines a human readable text alternative of aria-colindex. - {{domxref("ElementInternals.ariaColSpan")}} - - : A string reflecting the [`aria-colspan`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-colspan) attribute, which defines the number of columns spanned by a cell or gridcell within a table, grid, or treegrid. + - : A string reflecting the [`aria-colspan`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-colspan) attribute, which defines the number of columns spanned by a cell or gridcell within a table, grid, or treegrid. - {{domxref("ElementInternals.ariaCurrent")}} - - : A string reflecting the [`aria-current`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-current) attribute, which indicates the element that represents the current item within a container or set of related elements. + - : A string reflecting the [`aria-current`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-current) attribute, which indicates the element that represents the current item within a container or set of related elements. - {{domxref("ElementInternals.ariaDescription")}} - - : A string reflecting the [`aria-description`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-description) attribute, which defines a string value that describes or annotates the current ElementInternals. + - : A string reflecting the [`aria-description`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-description) attribute, which defines a string value that describes or annotates the current ElementInternals. - {{domxref("ElementInternals.ariaDisabled")}} - - : A string reflecting the [`aria-disabled`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-disabled) attribute, which indicates that the element is perceivable but disabled, so it is not editable or otherwise operable. + - : A string reflecting the [`aria-disabled`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-disabled) attribute, which indicates that the element is perceivable but disabled, so it is not editable or otherwise operable. - {{domxref("ElementInternals.ariaExpanded")}} - - : A string reflecting the [`aria-expanded`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-expanded) attribute, which indicates whether a grouping element owned or controlled by this element is expanded or collapsed. + - : A string reflecting the [`aria-expanded`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-expanded) attribute, which indicates whether a grouping element owned or controlled by this element is expanded or collapsed. - {{domxref("ElementInternals.ariaHasPopup")}} - - : A string reflecting the [`aria-haspopup`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-haspopup) attribute, which indicates the availability and type of interactive popup element, such as menu or dialog, that can be triggered by an ElementInternals. + - : A string reflecting the [`aria-haspopup`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-haspopup) attribute, which indicates the availability and type of interactive popup element, such as menu or dialog, that can be triggered by an ElementInternals. - {{domxref("ElementInternals.ariaHidden")}} - - : A string reflecting the [`aria-hidden`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-hidden) attribute, which indicates whether the element is exposed to an accessibility API. + - : A string reflecting the [`aria-hidden`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-hidden) attribute, which indicates whether the element is exposed to an accessibility API. +- {{domxref("ElementInternals.ariaInvalid")}} + - : A string reflecting the [`aria-invalid`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-invalid) attribute, which indicates the entered value does not conform to the format expected by the application. - {{domxref("ElementInternals.ariaKeyShortcuts")}} - - : A string reflecting the [`aria-keyshortcuts`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-keyshortcuts) attribute, which indicates keyboard shortcuts that an author has implemented to activate or give focus to an ElementInternals. + - : A string reflecting the [`aria-keyshortcuts`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-keyshortcuts) attribute, which indicates keyboard shortcuts that an author has implemented to activate or give focus to an object. - {{domxref("ElementInternals.ariaLabel")}} - - : A string reflecting the [`aria-label`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-label) attribute, which defines a string value that labels the current ElementInternals. + - : A string reflecting the [`aria-label`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-label) attribute, which defines a string value that labels the current object. - {{domxref("ElementInternals.ariaLevel")}} - - : A string reflecting the [`aria-level`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-level) attribute, which defines the hierarchical level of an element within a structure. + - : A string reflecting the [`aria-level`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-level) attribute, which defines the hierarchical level of an element within a structure. - {{domxref("ElementInternals.ariaLive")}} - - : A string reflecting the [`aria-live`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-live) attribute, which indicates that an element will be updated, and describes the types of updates the user agents, assistive technologies, and user can expect from the live region. + - : A string reflecting the [`aria-live`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-live) attribute, which indicates that an element will be updated, and describes the types of updates the user agents, assistive technologies, and user can expect from the live region. - {{domxref("ElementInternals.ariaModal")}} - - : A string reflecting the [`aria-modal`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-modal) attribute, which indicates whether an element is modal when displayed. + - : A string reflecting the [`aria-modal`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-modal) attribute, which indicates whether an element is modal when displayed. - {{domxref("ElementInternals.ariaMultiline")}} - - : A string reflecting the [`aria-multiline`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-multiline) attribute, which indicates whether a text box accepts multiple lines of input or only a single line. + - : A string reflecting the [`aria-multiline`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-multiline) attribute, which indicates whether a text box accepts multiple lines of input or only a single line. - {{domxref("ElementInternals.ariaMultiSelectable")}} - - : A string reflecting the [`aria-multiselectable`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-multiselectable) attribute, which indicates that the user may select more than one item from the current selectable descendants. + - : A string reflecting the [`aria-multiselectable`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-multiselectable) attribute, which indicates that the user may select more than one item from the current selectable descendants. - {{domxref("ElementInternals.ariaOrientation")}} - - : A string reflecting the [`aria-orientation`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-orientation) attribute, which indicates whether the element's orientation is horizontal, vertical, or unknown/ambiguous. + - : A string reflecting the [`aria-orientation`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-orientation) attribute, which indicates whether the element's orientation is horizontal, vertical, or unknown/ambiguous. - {{domxref("ElementInternals.ariaPlaceholder")}} - - : A string reflecting the [`aria-placeholder`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-placeholder) attribute, which defines a short hint intended to aid the user with data entry when the control has no value. + - : A string reflecting the [`aria-placeholder`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-placeholder) attribute, which defines a short hint intended to aid the user with data entry when the control has no value. - {{domxref("ElementInternals.ariaPosInSet")}} - - : A string reflecting the [`aria-posinset`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-posinset) attribute, which defines an element's number or position in the current set of listitems or treeitems. + - : A string reflecting the [`aria-posinset`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-posinset) attribute, which defines an element's number or position in the current set of listitems or treeitems. - {{domxref("ElementInternals.ariaPressed")}} - - : A string reflecting the [`aria-pressed`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-pressed) attribute, which indicates the current "pressed" state of toggle buttons. + - : A string reflecting the [`aria-pressed`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-pressed) attribute, which indicates the current "pressed" state of toggle buttons. - {{domxref("ElementInternals.ariaReadOnly")}} - - : A string reflecting the [`aria-readonly`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-readonly) attribute, which indicates that the element is not editable, but is otherwise operable. + - : A string reflecting the [`aria-readonly`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-readonly) attribute, which indicates that the element is not editable, but is otherwise operable. - {{domxref("ElementInternals.ariaRelevant")}} {{Non-standard_Inline}} - - : A string reflecting the [`aria-relevant`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-relevant) attribute, which indicates what notifications the user agent will trigger when the accessibility tree within a live region is modified. This is used to describe what changes in an `aria-live` region are relevant and should be announced. + - : A string reflecting the [`aria-relevant`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-relevant) attribute, which indicates what notifications the user agent will trigger when the accessibility tree within a live region is modified. This is used to describe what changes in an `aria-live` region are relevant and should be announced. - {{domxref("ElementInternals.ariaRequired")}} - - : A string reflecting the [`aria-required`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-required) attribute, which indicates that user input is required on the element before a form may be submitted. + - : A string reflecting the [`aria-required`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-required) attribute, which indicates that user input is required on the element before a form may be submitted. - {{domxref("ElementInternals.role")}} - - : A string which contains an ARIA role. A full list of ARIA roles can be found on the [ARIA techniques page](/en-US/docs/Web/Accessibility/ARIA/ARIA_Techniques). + - : A string which contains an ARIA role. A full list of ARIA roles can be found on the [ARIA techniques page](/en-US/docs/Web/Accessibility/ARIA/Guides/Techniques). - {{domxref("ElementInternals.ariaRoleDescription")}} - - : A string reflecting the [`aria-roledescription`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-roledescription) attribute, which defines a human-readable, author-localized description for the role of an Element. + - : A string reflecting the [`aria-roledescription`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-roledescription) attribute, which defines a human-readable, author-localized description for the role of an Element. - {{domxref("ElementInternals.ariaRowCount")}} - - : A string reflecting the [`aria-rowcount`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-rowcount) attribute, which defines the total number of rows in a table, grid, or treegrid. + - : A string reflecting the [`aria-rowcount`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-rowcount) attribute, which defines the total number of rows in a table, grid, or treegrid. - {{domxref("ElementInternals.ariaRowIndex")}} - - : A string reflecting the [`aria-rowindex`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-rowindex) attribute, which defines an element's row index or position with respect to the total number of rows within a table, grid, or treegrid. + - : A string reflecting the [`aria-rowindex`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-rowindex) attribute, which defines an element's row index or position with respect to the total number of rows within a table, grid, or treegrid. - {{domxref("ElementInternals.ariaRowIndexText")}} - - : A string reflecting the [`aria-rowindextext`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-rowindextext) attribute, which defines a human readable text alternative of aria-rowindex. + - : A string reflecting the [`aria-rowindextext`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-rowindextext) attribute, which defines a human readable text alternative of aria-rowindex. - {{domxref("ElementInternals.ariaRowSpan")}} - - : A string reflecting the [`aria-rowspan`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-rowspan) attribute, which defines the number of rows spanned by a cell or gridcell within a table, grid, or treegrid. + - : A string reflecting the [`aria-rowspan`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-rowspan) attribute, which defines the number of rows spanned by a cell or gridcell within a table, grid, or treegrid. - {{domxref("ElementInternals.ariaSelected")}} - - : A string reflecting the [`aria-selected`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-selected) attribute, which indicates the current "selected" state of elements that have a selected state. + - : A string reflecting the [`aria-selected`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-selected) attribute, which indicates the current "selected" state of elements that have a selected state. - {{domxref("ElementInternals.ariaSetSize")}} - - : A string reflecting the [`aria-setsize`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-setsize) attribute, which defines the number of items in the current set of listitems or treeitems. + - : A string reflecting the [`aria-setsize`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-setsize) attribute, which defines the number of items in the current set of listitems or treeitems. - {{domxref("ElementInternals.ariaSort")}} - - : A string reflecting the [`aria-sort`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-sort) attribute, which indicates if items in a table or grid are sorted in ascending or descending order. + - : A string reflecting the [`aria-sort`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-sort) attribute, which indicates if items in a table or grid are sorted in ascending or descending order. - {{domxref("ElementInternals.ariaValueMax")}} - - : A string reflecting the [`aria-valueMax`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-valuemax) attribute, which defines the maximum allowed value for a range widget. + - : A string reflecting the [`aria-valueMax`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-valuemax) attribute, which defines the maximum allowed value for a range widget. - {{domxref("ElementInternals.ariaValueMin")}} - - : A string reflecting the [`aria-valueMin`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-valuemin) attribute, which defines the minimum allowed value for a range widget. + - : A string reflecting the [`aria-valueMin`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-valuemin) attribute, which defines the minimum allowed value for a range widget. - {{domxref("ElementInternals.ariaValueNow")}} - - : A string reflecting the [`aria-valueNow`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-valuenow) attribute, which defines the current value for a range widget. + - : A string reflecting the [`aria-valueNow`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-valuenow) attribute, which defines the current value for a range widget. - {{domxref("ElementInternals.ariaValueText")}} - - : A string reflecting the [`aria-valuetext`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-valuetext) attribute, which defines the human-readable text alternative of aria-valuenow for a range widget. + - : A string reflecting the [`aria-valuetext`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-valuetext) attribute, which defines the human-readable text alternative of aria-valuenow for a range widget. + +#### Instance properties reflected from ARIA element references + +The properties reflect the elements specified by `id` reference in the corresponding attributes, but with some caveats. See [Reflected element references](/en-US/docs/Web/API/Document_Object_Model/Reflected_attributes#reflected_element_references) in the _Reflected attributes_ guide for more information. + +- {{domxref("ElementInternals.ariaActiveDescendantElement")}} + - : An element that represents the current active element when focus is on a [`composite`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/composite_role) widget, [`combobox`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/combobox_role), [`textbox`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/textbox_role), [`group`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/group_role), or [`application`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/application_role). + Reflects the [`aria-activedescendant`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-activedescendant) attribute. +- {{domxref("ElementInternals.ariaControlsElements")}} + - : An array of elements whose contents or presence are controlled by the element it is applied to. + Reflects the [`aria-controls`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-controls) attribute. +- {{domxref("ElementInternals.ariaDescribedByElements")}} + - : An array of elements that contain the accessible description for the element it is applied to. + Reflects the [`aria-describedby`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-describedby) attribute. +- {{domxref("ElementInternals.ariaDetailsElements")}} + - : An array of elements that provide accessible details for the element it is applied to. + Reflects the [`aria-details`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-details) attribute. +- {{domxref("ElementInternals.ariaErrorMessageElements")}} + - : An array of elements that provide an error message for the element it is applied to. + Reflects the [`aria-errormessage`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-errormessage) attribute. +- {{domxref("ElementInternals.ariaFlowToElements")}} + - : An array of elements that identify the next element (or elements) in an alternate reading order of content, overriding the general default reading order at the user's discretion. + Reflects the [`aria-flowto`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-flowto) attribute. +- {{domxref("ElementInternals.ariaLabelledByElements")}} + - : An array of elements that provide the accessible name for the element it is applied to. + Reflects the [`aria-labelledby`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-labelledby) attribute. +- {{domxref("ElementInternals.ariaOwnsElements")}} + - : An array of elements owned by the element this is applied to. + This is used to define a visual, functional, or contextual relationship between a parent and its child elements when the DOM hierarchy cannot be used to represent the relationship. + Reflects the [`aria-owns`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-owns) attribute. ## Instance methods @@ -128,9 +164,9 @@ The `ElementInternals` interface also includes the following properties. - {{domxref("ElementInternals.setValidity()")}} - : Sets the validity of the element. - {{domxref("ElementInternals.checkValidity()")}} - - : Checks if an element meets any [constraint validation](/en-US/docs/Web/HTML/Constraint_validation) rules applied to it. + - : Checks if an element meets any [constraint validation](/en-US/docs/Web/HTML/Guides/Constraint_validation) rules applied to it. - {{domxref("ElementInternals.reportValidity()")}} - - : Checks if an element meets any [constraint validation](/en-US/docs/Web/HTML/Constraint_validation) rules applied to it, and also sends a validation message to the user agent. + - : Checks if an element meets any [constraint validation](/en-US/docs/Web/HTML/Guides/Constraint_validation) rules applied to it, and also sends a validation message to the user agent. ## Examples @@ -170,6 +206,5 @@ console.log(element.internals_.form); ## See also -- [More capable form controls](https://web.dev/articles/more-capable-form-controls) -- [Creating custom form controls with ElementInternals](https://css-tricks.com/creating-custom-form-controls-with-elementinternals/) -- [ElementInternals polyfill](https://www.npmjs.com/package/element-internals-polyfill) +- [More capable form controls](https://web.dev/articles/more-capable-form-controls) via web.dev (2019) +- [Creating custom form controls with ElementInternals](https://css-tricks.com/creating-custom-form-controls-with-elementinternals/) via CSS-tricks (2021) diff --git a/files/en-us/web/api/elementinternals/reportvalidity/index.md b/files/en-us/web/api/elementinternals/reportvalidity/index.md index a9ab05a29388042..e0013245f0a796f 100644 --- a/files/en-us/web/api/elementinternals/reportvalidity/index.md +++ b/files/en-us/web/api/elementinternals/reportvalidity/index.md @@ -8,7 +8,7 @@ browser-compat: api.ElementInternals.reportValidity {{APIRef("Web Components")}} -The **`reportValidity()`** method of the {{domxref("ElementInternals")}} interface checks if the element meets any [constraint validation](/en-US/docs/Web/HTML/Constraint_validation) rules applied to it. +The **`reportValidity()`** method of the {{domxref("ElementInternals")}} interface checks if the element meets any [constraint validation](/en-US/docs/Web/HTML/Guides/Constraint_validation) rules applied to it. If `reportValidity` returns `false` then a cancelable [invalid event](/en-US/docs/Web/API/HTMLInputElement/invalid_event) is fired on the element. diff --git a/files/en-us/web/api/elementinternals/role/index.md b/files/en-us/web/api/elementinternals/role/index.md index 72061d34d406a87..401b80083056466 100644 --- a/files/en-us/web/api/elementinternals/role/index.md +++ b/files/en-us/web/api/elementinternals/role/index.md @@ -8,13 +8,11 @@ browser-compat: api.ElementInternals.role {{APIRef("Web Components")}} -The **`role`** read-only property of the {{domxref("ElementInternals")}} interface returns the [WAI-ARIA role](/en-US/docs/Web/Accessibility/ARIA/Roles) for the element. For example, a checkbox might have [`role="checkbox"`](/en-US/docs/Web/Accessibility/ARIA/Roles/checkbox_role). It reflects the `role` attribute; it does not return the element's implicit ARIA role, if any, unless explicitly set. +The **`role`** read-only property of the {{domxref("ElementInternals")}} interface returns the [WAI-ARIA role](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles) for the element. For example, a checkbox might have [`role="checkbox"`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/checkbox_role). It reflects the `role` attribute; it does not return the element's implicit ARIA role, if any, unless explicitly set. ## Value -A string which contains an ARIA role. A full list of ARIA roles can be found on the [ARIA techniques page](/en-US/docs/Web/Accessibility/ARIA/ARIA_Techniques). - -## Examples +A string which contains an ARIA role. A full list of ARIA roles can be found on the [ARIA techniques page](/en-US/docs/Web/Accessibility/ARIA/Guides/Techniques). ## Specifications diff --git a/files/en-us/web/api/elementinternals/setvalidity/index.md b/files/en-us/web/api/elementinternals/setvalidity/index.md index cfd8bfb6218278a..f3c4e0bb3e899b8 100644 --- a/files/en-us/web/api/elementinternals/setvalidity/index.md +++ b/files/en-us/web/api/elementinternals/setvalidity/index.md @@ -25,21 +25,21 @@ setValidity(flags, message, anchor) - : A dictionary object containing one or more flags indicating the validity state of the element: - `valueMissing` - - : A boolean value that is `true` if the element has a [`required`](/en-US/docs/Web/HTML/Element/input#required) attribute, but no value, or `false` otherwise. If `true`, the element matches the {{cssxref(":invalid")}} CSS pseudo-class. + - : A boolean value that is `true` if the element has a [`required`](/en-US/docs/Web/HTML/Reference/Elements/input#required) attribute, but no value, or `false` otherwise. If `true`, the element matches the {{cssxref(":invalid")}} CSS pseudo-class. - `typeMismatch` - - : A boolean value that is `true` if the value is not in the required syntax (when [`type`](/en-US/docs/Web/HTML/Element/input#type) is `email` or `url`), or `false` if the syntax is correct. If `true`, the element matches the {{cssxref(":invalid")}} CSS pseudo-class. + - : A boolean value that is `true` if the value is not in the required syntax (when [`type`](/en-US/docs/Web/HTML/Reference/Elements/input#type) is `email` or `url`), or `false` if the syntax is correct. If `true`, the element matches the {{cssxref(":invalid")}} CSS pseudo-class. - `patternMismatch` - - : A boolean value that is `true` if the value does not match the specified [`pattern`](/en-US/docs/Web/HTML/Element/input#pattern), and `false` if it does match. If `true`, the element matches the {{cssxref(":invalid")}} CSS pseudo-class. + - : A boolean value that is `true` if the value does not match the specified [`pattern`](/en-US/docs/Web/HTML/Reference/Elements/input#pattern), and `false` if it does match. If `true`, the element matches the {{cssxref(":invalid")}} CSS pseudo-class. - `tooLong` - : A boolean value that is `true` if the value exceeds the specified `maxlength` for {{domxref("HTMLInputElement")}} or {{domxref("HTMLTextAreaElement")}} objects, or `false` if its length is less than or equal to the maximum length. If `true`, the element matches the {{cssxref(":invalid")}} and {{cssxref(":out-of-range")}} CSS pseudo-classes. - `tooShort` - : A boolean value that is `true` if the value fails to meet the specified `minlength` for {{domxref("HTMLInputElement")}} or {{domxref("HTMLTextAreaElement")}} objects, or `false` if its length is greater than or equal to the minimum length. If `true`, the element matches the {{cssxref(":invalid")}} and {{cssxref(":out-of-range")}} CSS pseudo-classes. - `rangeUnderflow` - - : A boolean value that is `true` if the value is less than the minimum specified by the [`min`](/en-US/docs/Web/HTML/Element/input#min) attribute, or `false` if it is greater than or equal to the minimum. If `true`, the element matches the {{cssxref(":invalid")}} and {{cssxref(":out-of-range")}} CSS pseudo-classes. + - : A boolean value that is `true` if the value is less than the minimum specified by the [`min`](/en-US/docs/Web/HTML/Reference/Elements/input#min) attribute, or `false` if it is greater than or equal to the minimum. If `true`, the element matches the {{cssxref(":invalid")}} and {{cssxref(":out-of-range")}} CSS pseudo-classes. - `rangeOverflow` - - : A boolean value that is `true` if the value is greater than the maximum specified by the [`max`](/en-US/docs/Web/HTML/Element/input#max) attribute, or `false` if it is less than or equal to the maximum. If `true`, the element matches the {{cssxref(":invalid")}} and {{cssxref(":out-of-range")}} and CSS pseudo-classes. + - : A boolean value that is `true` if the value is greater than the maximum specified by the [`max`](/en-US/docs/Web/HTML/Reference/Elements/input#max) attribute, or `false` if it is less than or equal to the maximum. If `true`, the element matches the {{cssxref(":invalid")}} and {{cssxref(":out-of-range")}} and CSS pseudo-classes. - `stepMismatch` - - : A boolean value that is `true` if the value does not fit the rules determined by the [`step`](/en-US/docs/Web/HTML/Element/input#step) attribute (that is, it's not evenly divisible by the step value), or `false` if it does fit the step rule. If `true`, the element matches the {{cssxref(":invalid")}} and {{cssxref(":out-of-range")}} CSS pseudo-classes. + - : A boolean value that is `true` if the value does not fit the rules determined by the [`step`](/en-US/docs/Web/HTML/Reference/Elements/input#step) attribute (that is, it's not evenly divisible by the step value), or `false` if it does fit the step rule. If `true`, the element matches the {{cssxref(":invalid")}} and {{cssxref(":out-of-range")}} CSS pseudo-classes. - `badInput` - : A boolean value that is `true` if the user has provided input that the browser is unable to convert. - `customError` diff --git a/files/en-us/web/api/elementinternals/states/index.md b/files/en-us/web/api/elementinternals/states/index.md index f7bd25cf2b39925..b205e135d99d6f7 100644 --- a/files/en-us/web/api/elementinternals/states/index.md +++ b/files/en-us/web/api/elementinternals/states/index.md @@ -19,14 +19,16 @@ A {{domxref("CustomStateSet")}} which is a {{jsxref("Set")}} of strings. The following function adds and removes the state `--checked` to a `CustomStateSet`, then prints to the console `true` or `false` as the custom checkbox is checked or unchecked. ```js -set checked(flag) { - if (flag) { - this._internals.states.add('--checked'); - } else { - this._internals.states.delete('--checked'); +class MyElement extends HTMLElement { + set checked(flag) { + if (flag) { + this._internals.states.add("--checked"); + } else { + this._internals.states.delete("--checked"); + } + + console.log(this._internals.states.has("--checked")); } - - console.log(this._internals.states.has('--checked')); } ``` diff --git a/files/en-us/web/api/elementinternals/willvalidate/index.md b/files/en-us/web/api/elementinternals/willvalidate/index.md index 64bd70a67f09cc1..453bfe153d199d2 100644 --- a/files/en-us/web/api/elementinternals/willvalidate/index.md +++ b/files/en-us/web/api/elementinternals/willvalidate/index.md @@ -8,7 +8,7 @@ browser-compat: api.ElementInternals.willValidate {{APIRef("Web Components")}} -The **`willValidate`** read-only property of the {{domxref("ElementInternals")}} interface returns `true` if the element is a submittable element that is a candidate for [constraint validation](/en-US/docs/Web/HTML/Constraint_validation). +The **`willValidate`** read-only property of the {{domxref("ElementInternals")}} interface returns `true` if the element is a submittable element that is a candidate for [constraint validation](/en-US/docs/Web/HTML/Guides/Constraint_validation). Elements that are barred from being candidates for constraint validation include those that have the attributes: `disabled`, `hidden` or `readonly`, input elements of `type=button` or `type=reset`, or any element that is a {{htmlelement("datalist")}} element or has a `<datalist>` element ancestor. diff --git a/files/en-us/web/api/encodedaudiochunk/bytelength/index.md b/files/en-us/web/api/encodedaudiochunk/bytelength/index.md index a85cf4306c9a056..e78ed24fe90f8d2 100644 --- a/files/en-us/web/api/encodedaudiochunk/bytelength/index.md +++ b/files/en-us/web/api/encodedaudiochunk/bytelength/index.md @@ -25,9 +25,9 @@ const init = { timestamp: 23000000, duration: 2000000, }; -chunk = EncodedAudioChunk(init); +const chunk = new EncodedAudioChunk(init); -console.log(chunk.byteLength); //352800 +console.log(chunk.byteLength); // 352800 ``` ## Specifications diff --git a/files/en-us/web/api/encodedaudiochunk/copyto/index.md b/files/en-us/web/api/encodedaudiochunk/copyto/index.md index 2a369362ec58b02..0c58b9c121b5682 100644 --- a/files/en-us/web/api/encodedaudiochunk/copyto/index.md +++ b/files/en-us/web/api/encodedaudiochunk/copyto/index.md @@ -36,7 +36,7 @@ const init = { timestamp: 23000000, duration: 2000000, }; -chunk = EncodedAudioChunk(init); +const chunk = new EncodedAudioChunk(init); chunk.copyTo(newBuffer); ``` diff --git a/files/en-us/web/api/encodedaudiochunk/duration/index.md b/files/en-us/web/api/encodedaudiochunk/duration/index.md index 0284c94da79622d..71d0aff09006a80 100644 --- a/files/en-us/web/api/encodedaudiochunk/duration/index.md +++ b/files/en-us/web/api/encodedaudiochunk/duration/index.md @@ -25,9 +25,9 @@ const init = { timestamp: 23000000, duration: 2000000, }; -chunk = EncodedAudioChunk(init); +const chunk = new EncodedAudioChunk(init); -console.log(chunk.duration); //2000000 +console.log(chunk.duration); // 2000000 ``` ## Specifications diff --git a/files/en-us/web/api/encodedaudiochunk/timestamp/index.md b/files/en-us/web/api/encodedaudiochunk/timestamp/index.md index 442fe9a969fa9c4..e08d3e81073a1c2 100644 --- a/files/en-us/web/api/encodedaudiochunk/timestamp/index.md +++ b/files/en-us/web/api/encodedaudiochunk/timestamp/index.md @@ -25,9 +25,9 @@ const init = { timestamp: 23000000, duration: 2000000, }; -chunk = EncodedAudioChunk(init); +const chunk = new EncodedAudioChunk(init); -console.log(chunk.timestamp); //23000000 +console.log(chunk.timestamp); // 23000000 ``` ## Specifications diff --git a/files/en-us/web/api/encodedaudiochunk/type/index.md b/files/en-us/web/api/encodedaudiochunk/type/index.md index be84e3596600e34..64a679090f9f055 100644 --- a/files/en-us/web/api/encodedaudiochunk/type/index.md +++ b/files/en-us/web/api/encodedaudiochunk/type/index.md @@ -30,9 +30,9 @@ const init = { timestamp: 23000000, duration: 2000000, }; -chunk = EncodedAudioChunk(init); +const chunk = new EncodedAudioChunk(init); -console.log(chunk.type); //"key" +console.log(chunk.type); // "key" ``` ## Specifications diff --git a/files/en-us/web/api/encodedvideochunk/bytelength/index.md b/files/en-us/web/api/encodedvideochunk/bytelength/index.md index a62bd33d2a33719..2b75492dd5a74db 100644 --- a/files/en-us/web/api/encodedvideochunk/bytelength/index.md +++ b/files/en-us/web/api/encodedvideochunk/bytelength/index.md @@ -25,9 +25,9 @@ const init = { timestamp: 23000000, duration: 2000000, }; -chunk = EncodedVideoChunk(init); +const chunk = new EncodedVideoChunk(init); -console.log(chunk.byteLength); //352800 +console.log(chunk.byteLength); // 352800 ``` ## Specifications diff --git a/files/en-us/web/api/encodedvideochunk/copyto/index.md b/files/en-us/web/api/encodedvideochunk/copyto/index.md index 22ceb5a2a7e878b..c87da85cb4a9a46 100644 --- a/files/en-us/web/api/encodedvideochunk/copyto/index.md +++ b/files/en-us/web/api/encodedvideochunk/copyto/index.md @@ -36,7 +36,7 @@ const init = { timestamp: 23000000, duration: 2000000, }; -chunk = EncodedVideoChunk(init); +const chunk = new EncodedVideoChunk(init); chunk.copyTo(newBuffer); ``` diff --git a/files/en-us/web/api/encodedvideochunk/duration/index.md b/files/en-us/web/api/encodedvideochunk/duration/index.md index 21a25659c0616a4..d5f8412ba124838 100644 --- a/files/en-us/web/api/encodedvideochunk/duration/index.md +++ b/files/en-us/web/api/encodedvideochunk/duration/index.md @@ -25,9 +25,9 @@ const init = { timestamp: 23000000, duration: 2000000, }; -chunk = EncodedVideoChunk(init); +const chunk = new EncodedVideoChunk(init); -console.log(chunk.duration); //2000000 +console.log(chunk.duration); // 2000000 ``` ## Specifications diff --git a/files/en-us/web/api/encodedvideochunk/timestamp/index.md b/files/en-us/web/api/encodedvideochunk/timestamp/index.md index 20c88828ae9ca99..f0a95184cdd6903 100644 --- a/files/en-us/web/api/encodedvideochunk/timestamp/index.md +++ b/files/en-us/web/api/encodedvideochunk/timestamp/index.md @@ -25,8 +25,8 @@ const init = { timestamp: 23000000, duration: 2000000, }; -chunk = EncodedVideoChunk(init); -console.log(chunk.timestamp); //23000000 +const chunk = new EncodedVideoChunk(init); +console.log(chunk.timestamp); // 23000000 ``` ## Specifications diff --git a/files/en-us/web/api/encodedvideochunk/type/index.md b/files/en-us/web/api/encodedvideochunk/type/index.md index 537459e2eda08fe..405c1666b2ef14f 100644 --- a/files/en-us/web/api/encodedvideochunk/type/index.md +++ b/files/en-us/web/api/encodedvideochunk/type/index.md @@ -30,9 +30,9 @@ const init = { timestamp: 23000000, duration: 2000000, }; -chunk = EncodedVideoChunk(init); +const chunk = new EncodedVideoChunk(init); -console.log(chunk.type); //"key" +console.log(chunk.type); // "key" ``` ## Specifications diff --git a/files/en-us/web/api/encoding_api/encodings/index.md b/files/en-us/web/api/encoding_api/encodings/index.md index 7c65c70d0c246a5..7520e06b646adea 100644 --- a/files/en-us/web/api/encoding_api/encodings/index.md +++ b/files/en-us/web/api/encoding_api/encodings/index.md @@ -22,15 +22,15 @@ These are generally applicable anywhere character encodings are used. <tbody> <tr> <td> - "<code>unicode-1-1-utf-8</code>", "<code>utf-8</code>", - "<code>utf8</code>" + <code>"unicode-1-1-utf-8"</code>, <code>"utf-8"</code>, + <code>"utf8"</code> </td> - <td><code>'utf-8'</code></td> + <td><code>"utf-8"</code></td> </tr> <tr> <td> - "<code>866</code>", "<code>cp866</code>", "<code>csibm866</code>", - "<code>ibm866</code>" + <code>"866"</code>, <code>"cp866"</code>, <code>"csibm866"</code>, + <code>"ibm866"</code> </td> <td> <a href="https://en.wikipedia.org/wiki/Code_page_866">ibm866</a> @@ -38,10 +38,10 @@ These are generally applicable anywhere character encodings are used. </tr> <tr> <td> - "<code>csisolatin2</code>", "<code>iso-8859-2</code>", - "<code>iso-ir-101</code>", "<code>iso8859-2</code>", - "<code>iso88592</code>", "<code>iso_8859-2</code>", - "<code>iso_8859-2:1987</code>", "<code>l2</code>", "<code>latin2</code>" + <code>"csisolatin2"</code>, <code>"iso-8859-2"</code>, + <code>"iso-ir-101"</code>, <code>"iso8859-2"</code>, + <code>"iso88592"</code>, <code>"iso_8859-2"</code>, + <code>"iso_8859-2:1987"</code>, <code>"l2"</code>, <code>"latin2"</code> </td> <td> <a href="https://en.wikipedia.org/wiki/ISO/IEC_8859-2">iso-8859-2</a> @@ -49,10 +49,10 @@ These are generally applicable anywhere character encodings are used. </tr> <tr> <td> - "<code>csisolatin3</code>", "<code>iso-8859-3</code>", - "<code>iso-ir-109</code>", "<code>iso8859-3</code>", - "<code>iso88593</code>", "<code>iso_8859-3</code>", - "<code>iso_8859-3:1988</code>", "<code>l3</code>", "<code>latin3</code>" + <code>"csisolatin3"</code>, <code>"iso-8859-3"</code>, + <code>"iso-ir-109"</code>, <code>"iso8859-3"</code>, + <code>"iso88593"</code>, <code>"iso_8859-3"</code>, + <code>"iso_8859-3:1988"</code>, <code>"l3"</code>, <code>"latin3"</code> </td> <td> <a href="https://en.wikipedia.org/wiki/ISO/IEC_8859-3">iso-8859-3</a> @@ -60,10 +60,10 @@ These are generally applicable anywhere character encodings are used. </tr> <tr> <td> - "<code>csisolatin4</code>", "<code>iso-8859-4</code>", - "<code>iso-ir-110</code>", "<code>iso8859-4</code>", - "<code>iso88594</code>", "<code>iso_8859-4</code>", - "<code>iso_8859-4:1988</code>", "<code>l4</code>", "<code>latin4</code>" + <code>"csisolatin4"</code>, <code>"iso-8859-4"</code>, + <code>"iso-ir-110"</code>, <code>"iso8859-4"</code>, + <code>"iso88594"</code>, <code>"iso_8859-4"</code>, + <code>"iso_8859-4:1988"</code>, <code>"l4"</code>, <code>"latin4"</code> </td> <td> <a href="https://en.wikipedia.org/wiki/ISO/IEC_8859-4">iso-8859-4</a> @@ -71,10 +71,10 @@ These are generally applicable anywhere character encodings are used. </tr> <tr> <td> - "<code>csisolatincyrillic</code>", "<code>cyrillic</code>", - "<code>iso-8859-5</code>", "<code>iso-ir-144</code>", - "<code>iso88595</code>", "<code>iso_8859-5</code>", - "<code>iso_8859-5:1988</code>" + <code>"csisolatincyrillic"</code>, <code>"cyrillic"</code>, + <code>"iso-8859-5"</code>, <code>"iso-ir-144"</code>, + <code>"iso88595"</code>, <code>"iso_8859-5"</code>, + <code>"iso_8859-5:1988"</code> </td> <td> <a href="https://en.wikipedia.org/wiki/ISO/IEC_8859-5">iso-8859-5</a> @@ -82,13 +82,13 @@ These are generally applicable anywhere character encodings are used. </tr> <tr> <td> - "<code>arabic</code>", "<code>asmo-708</code>", - "<code>csiso88596e</code>", "<code>csiso88596i</code>", - "<code>csisolatinarabic</code>", "<code>ecma-114</code>", - "<code>iso-8859-6</code>", "<code>iso-8859-6-e</code>", - "<code>iso-8859-6-i</code>", "<code>iso-ir-127</code>", - "<code>iso8859-6</code>", "<code>iso88596</code>", - "<code>iso_8859-6</code>", "<code>iso_8859-6:1987</code>" + <code>"arabic"</code>, <code>"asmo-708"</code>, + <code>"csiso88596e"</code>, <code>"csiso88596i"</code>, + <code>"csisolatinarabic"</code>, <code>"ecma-114"</code>, + <code>"iso-8859-6"</code>, <code>"iso-8859-6-e"</code>, + <code>"iso-8859-6-i"</code>, <code>"iso-ir-127"</code>, + <code>"iso8859-6"</code>, <code>"iso88596"</code>, + <code>"iso_8859-6"</code>, <code>"iso_8859-6:1987"</code> </td> <td> <a href="https://en.wikipedia.org/wiki/ISO/IEC_8859-6">iso-8859-6</a> @@ -96,12 +96,12 @@ These are generally applicable anywhere character encodings are used. </tr> <tr> <td> - "<code>csisolatingreek</code>", "<code>ecma-118</code>", - "<code>elot_928</code>", "<code>greek</code>", "<code>greek8</code>", - "<code>iso-8859-7</code>", "<code>iso-ir-126</code>", - "<code>iso8859-7</code>", "<code>iso88597</code>", - "<code>iso_8859-7</code>", "<code>iso_8859-7:1987</code>", - "<code>sun_eu_greek</code>" + <code>"csisolatingreek"</code>, <code>"ecma-118"</code>, + <code>"elot_928"</code>, <code>"greek"</code>, <code>"greek8"</code>, + <code>"iso-8859-7"</code>, <code>"iso-ir-126"</code>, + <code>"iso8859-7"</code>, <code>"iso88597"</code>, + <code>"iso_8859-7"</code>, <code>"iso_8859-7:1987"</code>, + <code>"sun_eu_greek"</code> </td> <td> <a href="https://en.wikipedia.org/wiki/ISO/IEC_8859-7">iso-8859-7</a> @@ -109,12 +109,12 @@ These are generally applicable anywhere character encodings are used. </tr> <tr> <td> - "<code>csiso88598e</code>", "<code>csisolatinhebrew</code>", - "<code>hebrew</code>", "<code>iso-8859-8</code>", - "<code>iso-8859-8-e</code>", "<code>iso-ir-138</code>", - "<code>iso8859-8</code>", "<code>iso88598</code>", - "<code>iso_8859-8</code>", "<code>iso_8859-8:1988</code>", - "<code>visual</code>" + <code>"csiso88598e"</code>, <code>"csisolatinhebrew"</code>, + <code>"hebrew"</code>, <code>"iso-8859-8"</code>, + <code>"iso-8859-8-e"</code>, <code>"iso-ir-138"</code>, + <code>"iso8859-8"</code>, <code>"iso88598"</code>, + <code>"iso_8859-8"</code>, <code>"iso_8859-8:1988"</code>, + <code>"visual"</code> </td> <td> <a href="https://en.wikipedia.org/wiki/ISO/IEC_8859-8">iso-8859-8</a> @@ -122,8 +122,8 @@ These are generally applicable anywhere character encodings are used. </tr> <tr> <td> - "<code>csiso88598i</code>", "<code>iso-8859-8-i</code>", - "<code>logical</code>" + <code>"csiso88598i"</code>, <code>"iso-8859-8-i"</code>, + <code>"logical"</code> </td> <td> <a href="https://en.wikipedia.org/wiki/ISO-8859-8-I">iso-8859-8i</a> @@ -131,9 +131,9 @@ These are generally applicable anywhere character encodings are used. </tr> <tr> <td> - "<code>csisolatin6</code>", "<code>iso-8859-10</code>", - "<code>iso-ir-157</code>", "<code>iso8859-10</code>", - "<code>iso885910</code>", "<code>l6</code>", "<code>latin6</code>" + <code>"csisolatin6"</code>, <code>"iso-8859-10"</code>, + <code>"iso-ir-157"</code>, <code>"iso8859-10"</code>, + <code>"iso885910"</code>, <code>"l6"</code>, <code>"latin6"</code> </td> <td> <a href="https://en.wikipedia.org/wiki/ISO/IEC_8859-10">iso-8859-10</a> @@ -141,8 +141,8 @@ These are generally applicable anywhere character encodings are used. </tr> <tr> <td> - "<code>iso-8859-13</code>", "<code>iso8859-13</code>", - "<code>iso885913</code>" + <code>"iso-8859-13"</code>, <code>"iso8859-13"</code>, + <code>"iso885913"</code> </td> <td> <a href="https://en.wikipedia.org/wiki/ISO/IEC_8859-13">iso-8859-13</a> @@ -150,8 +150,8 @@ These are generally applicable anywhere character encodings are used. </tr> <tr> <td> - "<code>iso-8859-14</code>", "<code>iso8859-14</code>", - "<code>iso885914</code>" + <code>"iso-8859-14"</code>, <code>"iso8859-14"</code>, + <code>"iso885914"</code> </td> <td> <a href="https://en.wikipedia.org/wiki/ISO/IEC_8859-14">iso-8859-14</a> @@ -159,39 +159,39 @@ These are generally applicable anywhere character encodings are used. </tr> <tr> <td> - "<code>csisolatin9</code>", "<code>iso-8859-15</code>", - "<code>iso8859-15</code>", "<code>iso885915</code>", "<code>l9</code>", - "<code>latin9</code>" + <code>"csisolatin9"</code>, <code>"iso-8859-15"</code>, + <code>"iso8859-15"</code>, <code>"iso885915"</code>, <code>"l9"</code>, + <code>"latin9"</code> </td> <td> <a href="https://en.wikipedia.org/wiki/ISO/IEC_8859-15">iso-8859-15</a> </td> </tr> <tr> - <td>"<code>iso-8859-16</code>"</td> + <td><code>"iso-8859-16"</code></td> <td> <a href="https://en.wikipedia.org/wiki/ISO/IEC_8859-16">iso-8859-16</a> </td> </tr> <tr> <td> - "<code>cskoi8r</code>", "<code>koi</code>", "<code>koi8</code>", - "<code>koi8-r</code>", "<code>koi8_r</code>" + <code>"cskoi8r"</code>, <code>"koi"</code>, <code>"koi8"</code>, + <code>"koi8-r"</code>, <code>"koi8_r"</code> </td> <td> <a href="https://en.wikipedia.org/wiki/KOI8-R">koi8-r</a> </td> </tr> <tr> - <td>"<code>koi8-u</code>"</td> + <td><code>"koi8-u"</code></td> <td> <a href="https://en.wikipedia.org/wiki/KOI8-U">koi8-u</a> </td> </tr> <tr> <td> - "<code>csmacintosh</code>", "<code>mac</code>", - "<code>macintosh</code>", "<code>x-mac-roman</code>" + <code>"csmacintosh"</code>, <code>"mac"</code>, + <code>"macintosh"</code>, <code>"x-mac-roman"</code> </td> <td> <a href="https://en.wikipedia.org/wiki/Mac_OS_Roman">macintosh</a> @@ -199,9 +199,9 @@ These are generally applicable anywhere character encodings are used. </tr> <tr> <td> - "<code>dos-874</code>", "<code>iso-8859-11</code>", - "<code>iso8859-11</code>", "<code>iso885911</code>", - "<code>tis-620</code>", "<code>windows-874</code>" + <code>"dos-874"</code>, <code>"iso-8859-11"</code>, + <code>"iso8859-11"</code>, <code>"iso885911"</code>, + <code>"tis-620"</code>, <code>"windows-874"</code> </td> <td> <a href="https://en.wikipedia.org/wiki/Windows-874">windows-874</a> @@ -209,8 +209,8 @@ These are generally applicable anywhere character encodings are used. </tr> <tr> <td> - "<code>cp1250</code>", "<code>windows-1250</code>", - "<code>x-cp1250</code>" + <code>"cp1250"</code>, <code>"windows-1250"</code>, + <code>"x-cp1250"</code> </td> <td> <a href="https://en.wikipedia.org/wiki/Windows-1250">windows-1250</a> @@ -218,8 +218,8 @@ These are generally applicable anywhere character encodings are used. </tr> <tr> <td> - "<code>cp1251</code>", "<code>windows-1251</code>", - "<code>x-cp1251</code>" + <code>"cp1251"</code>, <code>"windows-1251"</code>, + <code>"x-cp1251"</code> </td> <td> <a href="https://en.wikipedia.org/wiki/Windows-1251">windows-1251</a> @@ -227,14 +227,14 @@ These are generally applicable anywhere character encodings are used. </tr> <tr> <td> - "<code>ansi_x3.4-1968</code>", "<code>ascii</code>", - "<code>cp1252</code>", "<code>cp819</code>", "<code>csisolatin1</code>", - "<code>ibm819</code>", "<code>iso-8859-1</code>", - "<code>iso-ir-100</code>", "<code>iso8859-1</code>", - "<code>iso88591</code>", "<code>iso_8859-1</code>", - "<code>iso_8859-1:1987</code>", "<code>l1</code>", - "<code>latin1</code>", "<code>us-ascii</code>", - "<code>windows-1252</code>", "<code>x-cp1252</code>" + <code>"ansi_x3.4-1968"</code>, <code>"ascii"</code>, + <code>"cp1252"</code>, <code>"cp819"</code>, <code>"csisolatin1"</code>, + <code>"ibm819"</code>, <code>"iso-8859-1"</code>, + <code>"iso-ir-100"</code>, <code>"iso8859-1"</code>, + <code>"iso88591"</code>, <code>"iso_8859-1"</code>, + <code>"iso_8859-1:1987"</code>, <code>"l1"</code>, + <code>"latin1"</code>, <code>"us-ascii"</code>, + <code>"windows-1252"</code>, <code>"x-cp1252"</code> </td> <td> <a href="https://en.wikipedia.org/wiki/Windows-1252">windows-1252</a> @@ -242,8 +242,8 @@ These are generally applicable anywhere character encodings are used. </tr> <tr> <td> - "<code>cp1253</code>", "<code>windows-1253</code>", - "<code>x-cp1253</code>" + <code>"cp1253"</code>, <code>"windows-1253"</code>, + <code>"x-cp1253"</code> </td> <td> <a href="https://en.wikipedia.org/wiki/Windows-1253">windows-1253</a> @@ -251,12 +251,12 @@ These are generally applicable anywhere character encodings are used. </tr> <tr> <td> - "<code>cp1254</code>", "<code>csisolatin5</code>", - "<code>iso-8859-9</code>", "<code>iso-ir-148</code>", - "<code>iso8859-9</code>", "<code>iso88599</code>", - "<code>iso_8859-9</code>", "<code>iso_8859-9:1989</code>", - "<code>l5</code>", "<code>latin5</code>", "<code>windows-1254</code>", - "<code>x-cp1254</code>" + <code>"cp1254"</code>, <code>"csisolatin5"</code>, + <code>"iso-8859-9"</code>, <code>"iso-ir-148"</code>, + <code>"iso8859-9"</code>, <code>"iso88599"</code>, + <code>"iso_8859-9"</code>, <code>"iso_8859-9:1989"</code>, + <code>"l5"</code>, <code>"latin5"</code>, <code>"windows-1254"</code>, + <code>"x-cp1254"</code> </td> <td> <a href="https://en.wikipedia.org/wiki/Windows-1254">windows-1254</a> @@ -264,8 +264,8 @@ These are generally applicable anywhere character encodings are used. </tr> <tr> <td> - "<code>cp1255</code>", "<code>windows-1255</code>", - "<code>x-cp1255</code>" + <code>"cp1255"</code>, <code>"windows-1255"</code>, + <code>"x-cp1255"</code> </td> <td> <a href="https://en.wikipedia.org/wiki/Windows-1255">windows-1255</a> @@ -273,8 +273,8 @@ These are generally applicable anywhere character encodings are used. </tr> <tr> <td> - "<code>cp1256</code>", "<code>windows-1256</code>", - "<code>x-cp1256</code>" + <code>"cp1256"</code>, <code>"windows-1256"</code>, + <code>"x-cp1256"</code> </td> <td> <a href="https://en.wikipedia.org/wiki/Windows-1256">windows-1256</a> @@ -282,8 +282,8 @@ These are generally applicable anywhere character encodings are used. </tr> <tr> <td> - "<code>cp1257</code>", "<code>windows-1257</code>", - "<code>x-cp1257</code>" + <code>"cp1257"</code>, <code>"windows-1257"</code>, + <code>"x-cp1257"</code> </td> <td> <a href="https://en.wikipedia.org/wiki/Windows-1257">windows-1257</a> @@ -291,46 +291,46 @@ These are generally applicable anywhere character encodings are used. </tr> <tr> <td> - "<code>cp1258</code>", "<code>windows-1258</code>", - "<code>x-cp1258</code>" + <code>"cp1258"</code>, <code>"windows-1258"</code>, + <code>"x-cp1258"</code> </td> <td> <a href="https://en.wikipedia.org/wiki/Windows-1258">windows-1258</a> </td> </tr> <tr> - <td>"<code>x-mac-cyrillic</code>", "<code>x-mac-ukrainian</code>"</td> + <td><code>"x-mac-cyrillic"</code>, <code>"x-mac-ukrainian"</code></td> <td> <a href="https://en.wikipedia.org/wiki/Macintosh_Cyrillic_encoding">x-mac-cyrillic</a> </td> </tr> <tr> <td> - "<code>chinese</code>", "<code>csgb2312</code>", - "<code>csiso58gb231280</code>", "<code>gb2312</code>", - "<code>gb_2312</code>", "<code>gb_2312-80</code>", "<code>gbk</code>", - "<code>iso-ir-58</code>", "<code>x-gbk</code>" + <code>"chinese"</code>, <code>"csgb2312"</code>, + <code>"csiso58gb231280"</code>, <code>"gb2312"</code>, + <code>"gb_2312"</code>, <code>"gb_2312-80"</code>, <code>"gbk"</code>, + <code>"iso-ir-58"</code>, <code>"x-gbk"</code> </td> <td> <a href="https://en.wikipedia.org/wiki/GBK_(character_encoding)">gbk</a> </td> </tr> <tr> - <td>"<code>gb18030</code>"</td> + <td><code>"gb18030"</code></td> <td> <a href="https://en.wikipedia.org/wiki/GB_18030">gb18030</a> </td> </tr> <tr> - <td>"<code>hz-gb-2312</code>"</td> + <td><code>"hz-gb-2312"</code></td> <td> <a href="https://en.wikipedia.org/wiki/HZ_(character_encoding)">hz-gb-2312</a> </td> </tr> <tr> <td> - "<code>big5</code>", "<code>big5-hkscs</code>", "<code>cn-big5</code>", - "<code>csbig5</code>", "<code>x-x-big5</code>" + <code>"big5"</code>, <code>"big5-hkscs"</code>, <code>"cn-big5"</code>, + <code>"csbig5"</code>, <code>"x-x-big5"</code> </td> <td> <a href="https://en.wikipedia.org/wiki/Big5">big5</a> @@ -338,24 +338,24 @@ These are generally applicable anywhere character encodings are used. </tr> <tr> <td> - "<code>cseucpkdfmtjapanese</code>", "<code>euc-jp</code>", - "<code>x-euc-jp</code>" + <code>"cseucpkdfmtjapanese"</code>, <code>"euc-jp"</code>, + <code>"x-euc-jp"</code> </td> <td> <a href="https://en.wikipedia.org/wiki/Extended_Unix_Code#EUC-JP">euc-jp</a> </td> </tr> <tr> - <td>"<code>csiso2022jp</code>", "<code>iso-2022-jp</code>"</td> + <td><code>"csiso2022jp"</code>, <code>"iso-2022-jp"</code></td> <td> <a href="https://en.wikipedia.org/wiki/ISO/IEC_2022#ISO-2022-JP">iso-2022-jp</a> </td> </tr> <tr> <td> - "<code>csshiftjis</code>", "<code>ms_kanji</code>", - "<code>shift-jis</code>", "<code>shift_jis</code>", "<code>sjis</code>", - "<code>windows-31j</code>", "<code>x-sjis</code>" + <code>"csshiftjis"</code>, <code>"ms_kanji"</code>, + <code>"shift-jis"</code>, <code>"shift_jis"</code>, <code>"sjis"</code>, + <code>"windows-31j"</code>, <code>"x-sjis"</code> </td> <td> <a href="https://en.wikipedia.org/wiki/Shift_JIS">shift-jis</a> @@ -363,41 +363,41 @@ These are generally applicable anywhere character encodings are used. </tr> <tr> <td> - "<code>cseuckr</code>", "<code>csksc56011987</code>", - "<code>euc-kr</code>", "<code>iso-ir-149</code>", "<code>korean</code>", - "<code>ks_c_5601-1987</code>", "<code>ks_c_5601-1989</code>", - "<code>ksc5601</code>", "<code>ksc_5601</code>", - "<code>windows-949</code>" + <code>"cseuckr"</code>, <code>"csksc56011987"</code>, + <code>"euc-kr"</code>, <code>"iso-ir-149"</code>, <code>"korean"</code>, + <code>"ks_c_5601-1987"</code>, <code>"ks_c_5601-1989"</code>, + <code>"ksc5601"</code>, <code>"ksc_5601"</code>, + <code>"windows-949"</code> </td> <td> <a href="https://en.wikipedia.org/wiki/Extended_Unix_Code#EUC-KR">euc-kr</a> </td> </tr> <tr> - <td>"<code>csiso2022kr</code>", "<code>iso-2022-kr</code>"</td> + <td><code>"csiso2022kr"</code>, <code>"iso-2022-kr"</code></td> <td> <a href="https://en.wikipedia.org/wiki/ISO/IEC_2022#ISO-2022-KR">iso-2022-kr</a> </td> </tr> <tr> - <td>"<code>utf-16be</code>"</td> + <td><code>"utf-16be"</code></td> <td> <a href="https://en.wikipedia.org/wiki/UTF-16#Byte_order_encoding_schemes">utf-16be</a> </td> </tr> <tr> - <td>"<code>utf-16</code>", "<code>utf-16le</code>"</td> + <td><code>"utf-16"</code>, <code>"utf-16le"</code></td> <td> <a href="https://en.wikipedia.org/wiki/UTF-16#Byte_order_encoding_schemes">utf-16le</a> </td> </tr> <tr> - <td>"<code>x-user-defined</code>"</td> - <td><code>'x-user-defined'</code></td> + <td><code>"x-user-defined"</code></td> + <td><code>"x-user-defined"</code></td> </tr> <tr> - <td>"<code>iso-2022-cn</code>", "<code>iso-2022-cn-ext</code>"</td> - <td><code>'replacement'</code></td> + <td><code>"iso-2022-cn"</code>, <code>"iso-2022-cn-ext"</code></td> + <td><code>"replacement"</code></td> </tr> </tbody> </table> diff --git a/files/en-us/web/api/errorevent/colno/index.md b/files/en-us/web/api/errorevent/colno/index.md index 4680f23ba039b5a..1e137dcfa5655ed 100644 --- a/files/en-us/web/api/errorevent/colno/index.md +++ b/files/en-us/web/api/errorevent/colno/index.md @@ -18,7 +18,7 @@ An integer. ```js window.addEventListener("error", (ev) => { - console.log("The error occur in column: " + ev.colno); + console.log(`The error occur in column: ${ev.colno}`); }); ``` diff --git a/files/en-us/web/api/errorevent/error/index.md b/files/en-us/web/api/errorevent/error/index.md index c339228b241becc..befd6ae9f026f89 100644 --- a/files/en-us/web/api/errorevent/error/index.md +++ b/files/en-us/web/api/errorevent/error/index.md @@ -18,7 +18,7 @@ Any valid JavaScript value. ```js window.addEventListener("error", (ev) => { - console.log("The error instance: " + ev.error); + console.log(`The error instance: ${ev.error}`); }); ``` diff --git a/files/en-us/web/api/errorevent/filename/index.md b/files/en-us/web/api/errorevent/filename/index.md index ec2fc88ee13004a..11edd99bc52d66b 100644 --- a/files/en-us/web/api/errorevent/filename/index.md +++ b/files/en-us/web/api/errorevent/filename/index.md @@ -18,7 +18,7 @@ A string. ```js window.addEventListener("error", (ev) => { - console.log("The error occur in file: " + ev.filename); + console.log(`The error occur in file: ${ev.filename}`); }); ``` diff --git a/files/en-us/web/api/errorevent/lineno/index.md b/files/en-us/web/api/errorevent/lineno/index.md index 8975a9de46930dc..12adf575bd90b91 100644 --- a/files/en-us/web/api/errorevent/lineno/index.md +++ b/files/en-us/web/api/errorevent/lineno/index.md @@ -18,7 +18,7 @@ An integer. ```js window.addEventListener("error", (ev) => { - console.log("The error occur in line: " + ev.lineno); + console.log(`The error occur in line: ${ev.lineno}`); }); ``` diff --git a/files/en-us/web/api/errorevent/message/index.md b/files/en-us/web/api/errorevent/message/index.md index 989c4dd369c96b6..9561432b5d4a41b 100644 --- a/files/en-us/web/api/errorevent/message/index.md +++ b/files/en-us/web/api/errorevent/message/index.md @@ -18,7 +18,7 @@ A string. ```js window.addEventListener("error", (ev) => { - console.log("The error message: " + ev.message); + console.log(`The error message: ${ev.message}`); }); ``` diff --git a/files/en-us/web/api/event/index.md b/files/en-us/web/api/event/index.md index e61b2067d9582f2..0724fa60021ffd6 100644 --- a/files/en-us/web/api/event/index.md +++ b/files/en-us/web/api/event/index.md @@ -9,11 +9,11 @@ browser-compat: api.Event The **`Event`** interface represents an event which takes place on an [`EventTarget`](/en-US/docs/Web/API/EventTarget). -An event can be triggered by the user action e.g. clicking the mouse button or tapping keyboard, or generated by APIs to represent the progress of an asynchronous task. It can also be triggered programmatically, such as by calling the [`HTMLElement.click()`](/en-US/docs/Web/API/HTMLElement/click) method of an element, or by defining the event, then sending it to a specified target using [`EventTarget.dispatchEvent()`](/en-US/docs/Web/API/EventTarget/dispatchEvent). +An event can be triggered by the user action e.g., clicking the mouse button or tapping keyboard, or generated by APIs to represent the progress of an asynchronous task. It can also be triggered programmatically, such as by calling the [`HTMLElement.click()`](/en-US/docs/Web/API/HTMLElement/click) method of an element, or by defining the event, then sending it to a specified target using [`EventTarget.dispatchEvent()`](/en-US/docs/Web/API/EventTarget/dispatchEvent). There are many types of events, some of which use other interfaces based on the main `Event` interface. `Event` itself contains the properties and methods which are common to all events. -Many DOM elements can be set up to accept (or "listen" for) these events, and execute code in response to process (or "handle") them. Event-handlers are usually connected (or "attached") to various [HTML elements](/en-US/docs/Web/HTML/Element) (such as `<button>`, `<div>`, `<span>`, etc.) using [`EventTarget.addEventListener()`](/en-US/docs/Web/API/EventTarget/addEventListener), and this generally replaces using the old HTML [event handler attributes](/en-US/docs/Web/HTML/Global_attributes). Further, when properly added, such handlers can also be disconnected if needed using [`removeEventListener()`](/en-US/docs/Web/API/EventTarget/removeEventListener). +Many DOM elements can be set up to accept (or "listen" for) these events, and execute code in response to process (or "handle") them. Event-handlers are usually connected (or "attached") to various [HTML elements](/en-US/docs/Web/HTML/Reference/Elements) (such as `<button>`, `<div>`, `<span>`, etc.) using [`EventTarget.addEventListener()`](/en-US/docs/Web/API/EventTarget/addEventListener), and this generally replaces using the old HTML [event handler attributes](/en-US/docs/Web/HTML/Reference/Global_attributes). Further, when properly added, such handlers can also be disconnected if needed using [`removeEventListener()`](/en-US/docs/Web/API/EventTarget/removeEventListener). > [!NOTE] > One element can have several such handlers, even for the exact same event—particularly if separate, independent code modules attach them, each for its own independent purposes. (For example, a webpage with an advertising-module and statistics-module both monitoring video-watching.) @@ -62,7 +62,6 @@ Note that all event interfaces have names which end in "Event". - {{domxref("RTCPeerConnectionIceEvent")}} - {{domxref("StorageEvent")}} - {{domxref("SubmitEvent")}} -- {{domxref("SVGEvent")}} {{Deprecated_Inline}} - {{domxref("TimeEvent")}} - {{domxref("TouchEvent")}} - {{domxref("TrackEvent")}} diff --git a/files/en-us/web/api/event/preventdefault/index.md b/files/en-us/web/api/event/preventdefault/index.md index 17a07955627b405..5bf350cfb96fef1 100644 --- a/files/en-us/web/api/event/preventdefault/index.md +++ b/files/en-us/web/api/event/preventdefault/index.md @@ -23,6 +23,9 @@ non-cancelable event, such as one dispatched via If a passive listener calls `preventDefault()`, nothing will happen and a console warning may be generated. +> [!NOTE] +> Look for better alternatives than using `preventDefault()` to block default actions. For example, you can use the `disabled` or `readonly` attribute on a form control to prevent it from being interacted with, use [HTML constraint validation](/en-US/docs/Web/HTML/Guides/Constraint_validation) to reject invalid input, or use the {{cssxref("overflow")}} property to prevent scrolling. + ## Syntax ```js-nolint @@ -67,96 +70,6 @@ function checkboxClick(event) { {{EmbedLiveSample("Blocking_default_click_handling")}} -### Stopping keystrokes from reaching an edit field - -The following example demonstrates how invalid text input can be stopped from reaching -the input field with `preventDefault()`. Nowadays, you should usually use [native HTML form validation](/en-US/docs/Learn_web_development/Extensions/Forms/Form_validation) -instead. - -#### HTML - -The HTML form below captures user input. -Since we're only interested in keystrokes, we're disabling `autocomplete` to prevent the browser from filling in the input field with cached values. - -```html -<div class="container"> - <p>Please enter your name using lowercase letters only.</p> - - <form> - <input type="text" id="my-textbox" autocomplete="off" /> - </form> -</div> -``` - -#### CSS - -We use a little bit of CSS for the warning box we'll draw when the user presses an -invalid key: - -```css -.warning { - border: 2px solid #f39389; - border-radius: 2px; - padding: 10px; - position: absolute; - background-color: #fbd8d4; - color: #3b3c40; -} -``` - -#### JavaScript - -And here's the JavaScript code that does the job. First, listen for -{{domxref("Element/keydown_event", "keydown")}} events: - -```js -const myTextbox = document.getElementById("my-textbox"); -myTextbox.addEventListener("keydown", checkName, false); -``` - -The `checkName()` function, which looks at the pressed key and decides -whether to allow it: - -```js -function checkName(evt) { - const key = evt.key; - const lowerCaseAlphabet = "abcdefghijklmnopqrstuvwxyz"; - if (!lowerCaseAlphabet.includes(key)) { - evt.preventDefault(); - displayWarning(`Please use lowercase letters only.\nKey pressed: ${key}\n`); - } -} -``` - -The `displayWarning()` function presents a notification of a problem. It's -not an elegant function but does the job for the purposes of this example: - -```js -let warningTimeout; -const warningBox = document.createElement("div"); -warningBox.className = "warning"; - -function displayWarning(msg) { - warningBox.innerText = msg; - - if (document.body.contains(warningBox)) { - clearTimeout(warningTimeout); - } else { - // insert warningBox after myTextbox - myTextbox.parentNode.insertBefore(warningBox, myTextbox.nextSibling); - } - - warningTimeout = setTimeout(() => { - warningBox.parentNode.removeChild(warningBox); - warningTimeout = -1; - }, 2000); -} -``` - -#### Result - -{{ EmbedLiveSample('Stopping_keystrokes_from_reaching_an_edit_field', 600, 200) }} - ## Notes Calling `preventDefault()` during any stage of event flow cancels the event, diff --git a/files/en-us/web/api/eventsource/error_event/index.md b/files/en-us/web/api/eventsource/error_event/index.md index d4f0de22ec73229..0d88f1b733f5331 100644 --- a/files/en-us/web/api/eventsource/error_event/index.md +++ b/files/en-us/web/api/eventsource/error_event/index.md @@ -16,10 +16,10 @@ This event is not cancelable and does not bubble. Use the event name in methods like {{domxref("EventTarget.addEventListener", "addEventListener()")}}, or set an event handler property. -```js -addEventListener("error", (event) => {}); +```js-nolint +addEventListener("error", (event) => { }) -onerror = (event) => {}; +onerror = (event) => { } ``` ## Event type diff --git a/files/en-us/web/api/eventsource/index.md b/files/en-us/web/api/eventsource/index.md index 0e06a23ed41d544..59f2fa9e43c7add 100644 --- a/files/en-us/web/api/eventsource/index.md +++ b/files/en-us/web/api/eventsource/index.md @@ -34,7 +34,7 @@ _This interface also inherits properties from its parent, {{domxref("EventTarget - {{domxref("EventSource.url")}} {{ReadOnlyInline}} - : A string representing the URL of the source. - {{domxref("EventSource.withCredentials")}} {{ReadOnlyInline}} - - : A boolean value indicating whether the `EventSource` object was instantiated with cross-origin ([CORS](/en-US/docs/Web/HTTP/CORS)) credentials set (`true`), or not (`false`, the default). + - : A boolean value indicating whether the `EventSource` object was instantiated with cross-origin ([CORS](/en-US/docs/Web/HTTP/Guides/CORS)) credentials set (`true`), or not (`false`, the default). ## Instance methods diff --git a/files/en-us/web/api/eventsource/message_event/index.md b/files/en-us/web/api/eventsource/message_event/index.md index c5b33cc55745e3d..394ce55a83ea3f6 100644 --- a/files/en-us/web/api/eventsource/message_event/index.md +++ b/files/en-us/web/api/eventsource/message_event/index.md @@ -16,10 +16,10 @@ This event is not cancelable and does not bubble. Use the event name in methods like {{domxref("EventTarget.addEventListener", "addEventListener()")}}, or set an event handler property. -```js -addEventListener("message", (event) => {}); +```js-nolint +addEventListener("message", (event) => { }) -onmessage = (event) => {}; +onmessage = (event) => { } ``` ## Event type @@ -41,7 +41,7 @@ _This interface also inherits properties from its parent, {{domxref("Event")}}._ - {{domxref("MessageEvent.source")}} {{ReadOnlyInline}} - : A `MessageEventSource` (which can be a {{glossary("WindowProxy")}}, {{domxref("MessagePort")}}, or {{domxref("ServiceWorker")}} object) representing the message emitter. - {{domxref("MessageEvent.ports")}} {{ReadOnlyInline}} - - : An array of {{domxref("MessagePort")}} objects representing the ports associated with the channel the message is being sent through (where appropriate, e.g. in channel messaging or when sending a message to a shared worker). + - : An array of {{domxref("MessagePort")}} objects representing the ports associated with the channel the message is being sent through (where appropriate, e.g., in channel messaging or when sending a message to a shared worker). ## Examples diff --git a/files/en-us/web/api/eventsource/open_event/index.md b/files/en-us/web/api/eventsource/open_event/index.md index 77b7759fc43f95e..5d046b2606214d3 100644 --- a/files/en-us/web/api/eventsource/open_event/index.md +++ b/files/en-us/web/api/eventsource/open_event/index.md @@ -16,10 +16,10 @@ This event is not cancelable and does not bubble. Use the event name in methods like {{domxref("EventTarget.addEventListener", "addEventListener()")}}, or set an event handler property. -```js -addEventListener("open", (event) => {}); +```js-nolint +addEventListener("open", (event) => { }) -onopen = (event) => {}; +onopen = (event) => { } ``` ## Event type diff --git a/files/en-us/web/api/eventtarget/addeventlistener/index.md b/files/en-us/web/api/eventtarget/addeventlistener/index.md index a653aed657b27cc..91ceaea74a19cb0 100644 --- a/files/en-us/web/api/eventtarget/addeventlistener/index.md +++ b/files/en-us/web/api/eventtarget/addeventlistener/index.md @@ -277,7 +277,7 @@ myObject.register(); Event listeners only take one argument, an {{domxref("Event")}} or a subclass of `Event`, which is automatically passed to the listener, and the return value is ignored. -Therefore, to get data into and out of an event listener, instead of passing the data through parameters and return values, you need to create [closures](/en-US/docs/Web/JavaScript/Closures) instead. +Therefore, to get data into and out of an event listener, instead of passing the data through parameters and return values, you need to create [closures](/en-US/docs/Web/JavaScript/Guide/Closures) instead. The functions passed as event listeners have access to all variables declared in the outer scopes that contain the function. @@ -301,11 +301,11 @@ Read [the function guide](/en-US/docs/Web/JavaScript/Guide/Functions#function_sc ### Memory issues ```js -const elts = document.getElementsByTagName("*"); +const elems = document.getElementsByTagName("*"); // Case 1 -for (const elt of elts) { - elt.addEventListener( +for (const elem of elems) { + elem.addEventListener( "click", (e) => { // Do something @@ -319,8 +319,8 @@ function processEvent(e) { // Do something } -for (const elt of elts) { - elt.addEventListener("click", processEvent, false); +for (const elem of elems) { + elem.addEventListener("click", processEvent, false); } ``` @@ -460,9 +460,9 @@ event listener. ```js // Function to change the content of t2 -function modifyText(new_text) { +function modifyText(newText) { const t2 = document.getElementById("t2"); - t2.firstChild.nodeValue = new_text; + t2.firstChild.nodeValue = newText; } // Function to add event listener to table @@ -506,9 +506,9 @@ notation. ```js // Function to change the content of t2 -function modifyText(new_text) { +function modifyText(newText) { const t2 = document.getElementById("t2"); - t2.firstChild.nodeValue = new_text; + t2.firstChild.nodeValue = newText; } // Add event listener to table with an arrow function @@ -650,7 +650,7 @@ function noneOnceHandler(event) { log("outer, none-once, default\n"); } function captureHandler(event) { - //event.stopImmediatePropagation(); + // event.stopImmediatePropagation(); log("middle, capture"); } function noneCaptureHandler(event) { @@ -663,7 +663,7 @@ function passiveHandler(event) { } function nonePassiveHandler(event) { event.preventDefault(); - //event.stopPropagation(); + // event.stopPropagation(); log("inner2, none-passive, default, not open new page"); } ``` diff --git a/files/en-us/web/api/eventtarget/dispatchevent/index.md b/files/en-us/web/api/eventtarget/dispatchevent/index.md index 9ed8feea44d330f..006e4bafc3b9bdb 100644 --- a/files/en-us/web/api/eventtarget/dispatchevent/index.md +++ b/files/en-us/web/api/eventtarget/dispatchevent/index.md @@ -20,7 +20,7 @@ should have already been created and initialized using an {{domxref("Event/Event > When calling this method, the {{domxref("Event.target")}} property is initialized to the current `EventTarget`. Unlike "native" events, which are fired by the browser and invoke event handlers -asynchronously via the [event loop](/en-US/docs/Web/JavaScript/Event_loop), +asynchronously via the [event loop](/en-US/docs/Web/JavaScript/Reference/Execution_model), `dispatchEvent()` invokes event handlers _synchronously_. All applicable event handlers are called and return before `dispatchEvent()` returns. diff --git a/files/en-us/web/api/ext_color_buffer_half_float/index.md b/files/en-us/web/api/ext_color_buffer_half_float/index.md index 8351f67d55f5abb..c18cd292e2e62a4 100644 --- a/files/en-us/web/api/ext_color_buffer_half_float/index.md +++ b/files/en-us/web/api/ext_color_buffer_half_float/index.md @@ -32,7 +32,7 @@ WebGL extensions are available using the {{domxref("WebGLRenderingContext.getExt This extension extends {{domxref("WebGLRenderingContext.renderbufferStorage()")}}: -- The `internalformat` parameter now accepts `ext.RGBA16F_EXT` and `ext.RGBA16F_EXT`. +- The `internalformat` parameter now accepts `ext.RGBA16F_EXT` and `ext.RGB16F_EXT`. ## Examples diff --git a/files/en-us/web/api/ext_shader_texture_lod/index.md b/files/en-us/web/api/ext_shader_texture_lod/index.md index 3128da8b779d102..18e098b9c8bca2b 100644 --- a/files/en-us/web/api/ext_shader_texture_lod/index.md +++ b/files/en-us/web/api/ext_shader_texture_lod/index.md @@ -19,7 +19,7 @@ WebGL extensions are available using the {{domxref("WebGLRenderingContext.getExt The following new functions can be used in GLSL shader code, if this extension is enabled: -```cpp +```c vec4 texture2DLodEXT(sampler2D sampler, vec2 coord, float lod) vec4 texture2DProjLodEXT(sampler2D sampler, vec3 coord, float lod) vec4 texture2DProjLodEXT(sampler2D sampler, vec4 coord, float lod) diff --git a/files/en-us/web/api/extendablecookiechangeevent/changed/index.md b/files/en-us/web/api/extendablecookiechangeevent/changed/index.md index fc68cae1c66820d..f0f90513a6676ff 100644 --- a/files/en-us/web/api/extendablecookiechangeevent/changed/index.md +++ b/files/en-us/web/api/extendablecookiechangeevent/changed/index.md @@ -28,12 +28,12 @@ An array of objects containing the changed cookie(s). Each object contains the f - : A {{jsxref("boolean")}} indicating whether the cookie is used only in a secure context (HTTPS rather than HTTP). - `sameSite` - - : One of the following [`SameSite`](/en-US/docs/Web/HTTP/Headers/Set-Cookie#samesitesamesite-value) values: + - : One of the following [`SameSite`](/en-US/docs/Web/HTTP/Reference/Headers/Set-Cookie#samesitesamesite-value) values: - `"strict"` - : Cookies will only be sent in a first-party context and not be sent with requests initiated by third party websites. - `"lax"` - - : Cookies are not sent on normal cross-site subrequests (for example to load images or frames into a third party site), but are sent when a user is navigating within the origin site (i.e. when following a link). + - : Cookies are not sent on normal cross-site subrequests (for example to load images or frames into a third party site), but are sent when a user is navigating within the origin site (i.e., when following a link). - `"none"` - : Cookies will be sent in all contexts. diff --git a/files/en-us/web/api/extendablecookiechangeevent/deleted/index.md b/files/en-us/web/api/extendablecookiechangeevent/deleted/index.md index 25e62063e73b686..bfc038d41837b75 100644 --- a/files/en-us/web/api/extendablecookiechangeevent/deleted/index.md +++ b/files/en-us/web/api/extendablecookiechangeevent/deleted/index.md @@ -28,12 +28,12 @@ An array of objects containing the deleted cookie(s). Each object contains the f - : A {{jsxref("boolean")}} indicating whether the cookie is used only in a secure context (HTTPS rather than HTTP). - `sameSite` - - : One of the following [`SameSite`](/en-US/docs/Web/HTTP/Headers/Set-Cookie#samesitesamesite-value) values: + - : One of the following [`SameSite`](/en-US/docs/Web/HTTP/Reference/Headers/Set-Cookie#samesitesamesite-value) values: - `"strict"` - : Cookies will only be sent in a first-party context and not be sent with requests initiated by third party websites. - `"lax"` - - : Cookies are not sent on normal cross-site subrequests (for example to load images or frames into a third party site), but are sent when a user is navigating within the origin site (i.e. when following a link). + - : Cookies are not sent on normal cross-site subrequests (for example to load images or frames into a third party site), but are sent when a user is navigating within the origin site (i.e., when following a link). - `"none"` - : Cookies will be sent in all contexts. diff --git a/files/en-us/web/api/extendableevent/index.md b/files/en-us/web/api/extendableevent/index.md index 2b88b86a6cf2b0d..6e109a6f8c9e748 100644 --- a/files/en-us/web/api/extendableevent/index.md +++ b/files/en-us/web/api/extendableevent/index.md @@ -64,16 +64,15 @@ self.addEventListener("install", (event) => { event.waitUntil( caches .open(CURRENT_CACHES["prefetch"]) - .then((cache) => { - return cache - .addAll( - urlsToPrefetch.map((urlToPrefetch) => { - return new Request(urlToPrefetch, { mode: "no-cors" }); - }), - ) - .then(() => { - console.log("All resources have been fetched and cached."); - }); + .then((cache) => + cache.addAll( + urlsToPrefetch.map( + (urlToPrefetch) => new Request(urlToPrefetch, { mode: "no-cors" }), + ), + ), + ) + .then(() => { + console.log("All resources have been fetched and cached."); }) .catch((error) => { console.error("Pre-fetching failed:", error); diff --git a/files/en-us/web/api/featurepolicy/allowedfeatures/index.md b/files/en-us/web/api/featurepolicy/allowedfeatures/index.md index bc3c3365e9f46fd..7a0c4cd6e2470b7 100644 --- a/files/en-us/web/api/featurepolicy/allowedfeatures/index.md +++ b/files/en-us/web/api/featurepolicy/allowedfeatures/index.md @@ -12,7 +12,7 @@ browser-compat: api.FeaturePolicy.allowedFeatures The **`allowedFeatures()`** method of the {{DOMxRef("FeaturePolicy")}} interface returns a list of directive names of all -features allowed by the [Permissions Policy](/en-US/docs/Web/HTTP/Permissions_Policy). This enables introspection of individual directives +features allowed by the [Permissions Policy](/en-US/docs/Web/HTTP/Guides/Permissions_Policy). This enables introspection of individual directives of the Permissions Policy it is run on. As such, `allowedFeatures()` method returns a subset of directives returned by {{DOMxRef("FeaturePolicy.features", "features()")}}. diff --git a/files/en-us/web/api/featurepolicy/allowsfeature/index.md b/files/en-us/web/api/featurepolicy/allowsfeature/index.md index 9b0d56d648bee35..b27e12d33be7c69 100644 --- a/files/en-us/web/api/featurepolicy/allowsfeature/index.md +++ b/files/en-us/web/api/featurepolicy/allowsfeature/index.md @@ -12,7 +12,7 @@ browser-compat: api.FeaturePolicy.allowsFeature The **`allowsFeature()`** method of the {{DOMxRef("FeaturePolicy")}} interface enables introspection of individual -directives of the [Permissions Policy](/en-US/docs/Web/HTTP/Permissions_Policy) it is run on. It returns a {{JSxRef("Boolean")}} +directives of the [Permissions Policy](/en-US/docs/Web/HTTP/Guides/Permissions_Policy) it is run on. It returns a {{JSxRef("Boolean")}} that is `true` if and only if the specified feature is allowed in the specified context (or the default context if no context is specified). diff --git a/files/en-us/web/api/featurepolicy/features/index.md b/files/en-us/web/api/featurepolicy/features/index.md index 9ed3d48d15177c6..1f156cdf01b8818 100644 --- a/files/en-us/web/api/featurepolicy/features/index.md +++ b/files/en-us/web/api/featurepolicy/features/index.md @@ -13,7 +13,7 @@ browser-compat: api.FeaturePolicy.features The **`features()`** method of the {{DOMxRef("FeaturePolicy")}} interface returns a list of names of all features supported by the User Agent. Feature whose name appears on the list might not be -allowed by the [Permissions Policy](/en-US/docs/Web/HTTP/Permissions_Policy) of the current execution context and/or might not be +allowed by the [Permissions Policy](/en-US/docs/Web/HTTP/Guides/Permissions_Policy) of the current execution context and/or might not be accessible because of user's permissions. ## Syntax diff --git a/files/en-us/web/api/featurepolicy/index.md b/files/en-us/web/api/featurepolicy/index.md index 2c8fae48cf4ac67..efa73df5dc33401 100644 --- a/files/en-us/web/api/featurepolicy/index.md +++ b/files/en-us/web/api/featurepolicy/index.md @@ -9,7 +9,7 @@ browser-compat: api.FeaturePolicy {{APIRef("Feature Policy")}}{{SeeCompatTable}} -The `FeaturePolicy` interface represents the set of [Permissions Policies](/en-US/docs/Web/HTTP/Permissions_Policy) applied to the current execution context. +The `FeaturePolicy` interface represents the set of [Permissions Policies](/en-US/docs/Web/HTTP/Guides/Permissions_Policy) applied to the current execution context. ## Instance methods diff --git a/files/en-us/web/api/fedcm_api/idp_integration/index.md b/files/en-us/web/api/fedcm_api/idp_integration/index.md index e6e06d17e873844..ef785559c035812 100644 --- a/files/en-us/web/api/fedcm_api/idp_integration/index.md +++ b/files/en-us/web/api/fedcm_api/idp_integration/index.md @@ -20,7 +20,7 @@ To integrate with FedCM, an IdP needs to do the following: There is a potential privacy issue whereby an [IdP is able to discern whether a user visited an RP without explicit consent](https://github.com/w3c-fedid/FedCM/issues/230). This has tracking implications, so an IdP is required to provide a well-known file to verify its identity and mitigate this issue. -The well-known file is requested via an uncredentialed [`GET`](/en-US/docs/Web/HTTP/Methods/GET) request, which doesn't follow redirects. This effectively prevents the IdP from learning who made the request and which RP is attempting to connect. +The well-known file is requested via an uncredentialed [`GET`](/en-US/docs/Web/HTTP/Reference/Methods/GET) request, which doesn't follow redirects. This effectively prevents the IdP from learning who made the request and which RP is attempting to connect. The well-known file must be served from the [eTLD+1](https://web.dev/articles/same-site-same-origin#site) of the IdP at `/.well-known/web-identity`. For example, if the IdP endpoints are served under `https://accounts.idp.example/`, they must serve a well-known file at `https://idp.example/.well-known/web-identity`. The well-known file's content should have the following JSON structure: @@ -34,13 +34,13 @@ The `provider_urls` member should contain an array of URLs pointing to valid IdP ## The `Sec-Fetch-Dest` HTTP header -All requests sent from the browser via FedCM include a `{{httpheader("Sec-Fetch-Dest")}}: webidentity` header. All IdP endpoints that receive credentialed requests (i.e. `accounts_endpoint` and `id_assertion_endpoint`) must confirm this header is included to protect against {{glossary("CSRF")}} attacks. +All requests sent from the browser via FedCM include a `{{httpheader("Sec-Fetch-Dest")}}: webidentity` header. All IdP endpoints that receive credentialed requests (i.e., `accounts_endpoint` and `id_assertion_endpoint`) must confirm this header is included to protect against {{glossary("CSRF")}} attacks. ## Provide a config file and endpoints The IdP config file provides a list of the endpoints the browser needs to process the identity federation flow and manage the sign-ins. The endpoints need to be same-origin with the config. -The browser makes an uncredentialed request for the config file via the [`GET`](/en-US/docs/Web/HTTP/Methods/GET) method, which doesn't follow redirects. This effectively prevents the IdP from learning who made the request and which RP is attempting to connect. +The browser makes an uncredentialed request for the config file via the [`GET`](/en-US/docs/Web/HTTP/Reference/Methods/GET) method, which doesn't follow redirects. This effectively prevents the IdP from learning who made the request and which RP is attempting to connect. The config file (hosted at `https://accounts.idp.example/config.json` in our example) should have the following JSON structure: @@ -93,7 +93,7 @@ The following table summarizes the different requests made by the FedCM API: ### The accounts list endpoint -The browser sends credentialed requests (i.e. with a cookie that identifies the user that is signed in) to this endpoint via the `GET` method. The request has no `client_id` parameter, {{httpheader("Origin")}} header, or {{httpheader("Referer")}} header. This effectively prevents the IdP from learning which RP the user is trying to sign in to. The list of accounts returned is RP-agnostic. +The browser sends credentialed requests (i.e., with a cookie that identifies the user that is signed in) to this endpoint via the `GET` method. The request has no `client_id` parameter, {{httpheader("Origin")}} header, or {{httpheader("Referer")}} header. This effectively prevents the IdP from learning which RP the user is trying to sign in to. The list of accounts returned is RP-agnostic. For example: @@ -147,10 +147,10 @@ This includes the following information: - `approved_clients` {{optional_inline}} - : An array of RP clients that the user has registered with. - `login_hints` {{optional_inline}} - - : An array of strings representing the account. These strings are used to filter the list of account options that the browser offers for the user to sign-in. This occurs when the `loginHint` property is provided within [`identity.providers`](/en-US/docs/Web/API/CredentialsContainer/get#providers_2) in a related `get()` call. Any account with a string in its `login_hints` array that matches the provided `loginHint` is included. + - : An array of strings representing the account. These strings are used to filter the list of account options that the browser offers for the user to sign-in. This occurs when the `loginHint` property is provided within [`identity.providers`](/en-US/docs/Web/API/IdentityCredentialRequestOptions#providers) in a related `get()` call. Any account with a string in its `login_hints` array that matches the provided `loginHint` is included. > [!NOTE] -> If the user is not signed in to any IdP accounts, the endpoint should respond with [HTTP 401 (Unauthorized)](/en-US/docs/Web/HTTP/Status/401). +> If the user is not signed in to any IdP accounts, the endpoint should respond with [HTTP 401 (Unauthorized)](/en-US/docs/Web/HTTP/Reference/Status/401). ### The client metadata endpoint @@ -177,7 +177,7 @@ The response to a successful request includes URLs pointing to the RP's metadata ### The ID assertion endpoint -The browser sends credentialed requests to this endpoint via the [`POST`](/en-US/docs/Web/HTTP/Methods/POST) method, with a content type of `application/x-www-form-urlencoded`. The request also includes a payload including details about the attempted sign-in and the account to be validated. +The browser sends credentialed requests to this endpoint via the [`POST`](/en-US/docs/Web/HTTP/Reference/Methods/POST) method, with a content type of `application/x-www-form-urlencoded`. The request also includes a payload including details about the attempted sign-in and the account to be validated. It should look something like this: @@ -210,11 +210,24 @@ The request payload contains the following params: - `disclosure_text_shown` - : A string of `"true"` or `"false"` indicating whether the disclosure text was shown or not. The disclosure text is the information shown to the user (which can include the terms of service and privacy policy links, if provided) if the user is signed in to the IdP but doesn't have an account specifically on the current RP (in which case they'd need to choose to "Continue as..." their IdP identity and then create a corresponding account on the RP). - `is_auto_selected` - - : A string of `"true"` or `"false"` indicating whether the authentication validation request has been issued as a result of [auto-reauthentication](/en-US/docs/Web/API/FedCM_API/RP_sign-in#auto-reauthentication), i.e. without user mediation. This can occur when the {{domxref("CredentialsContainer.get", "get()")}} call is issued with a [`mediation`](/en-US/docs/Web/API/CredentialsContainer/get#mediation) option value of `"optional"` or `"silent"`. It is useful for the IdP to know whether auto reauthentication occurred for performance evaluation and in case higher security is desired. For example, the IdP could return an error code telling the RP that it requires explicit user mediation (`mediation="required"`). + - : A string of `"true"` or `"false"` indicating whether the authentication validation request has been issued as a result of [auto-reauthentication](/en-US/docs/Web/API/FedCM_API/RP_sign-in#auto-reauthentication), i.e., without user mediation. This can occur when the {{domxref("CredentialsContainer.get", "get()")}} call is issued with a [`mediation`](/en-US/docs/Web/API/CredentialsContainer/get#mediation) option value of `"optional"` or `"silent"`. It is useful for the IdP to know whether auto reauthentication occurred for performance evaluation and in case higher security is desired. For example, the IdP could return an error code telling the RP that it requires explicit user mediation (`mediation="required"`). > [!NOTE] > If the {{domxref("CredentialsContainer.get", "get()")}} call succeeds, the `is_auto_selected` value is also communicated to the RP via the {{domxref("IdentityCredential.isAutoSelected")}} property. +#### CORS headers for the ID assertion endpoint + +The ID assertion endpoint response must include the {{httpheader("Access-Control-Allow-Origin")}} and {{httpheader("Access-Control-Allow-Credentials")}} headers, and the `Access-Control-Allow-Origin` must include the requester's origin: + +```http +Access-Control-Allow-Origin: https://rp.example +Access-Control-Allow-Credentials: true +``` + +Note that the `Access-Control-Allow-Origin` must be set to the specific origin of the requester (the RP) and cannot be the wildcard value `*`. + +Without these headers, the request will fail with a network error. + #### ID assertion error responses If the IdP cannot issue a token — for example if the client is unauthorized — the ID assertion endpoint will respond with an error response containing information about the nature of the error. For example: @@ -237,7 +250,7 @@ The error response fields are as follows: This information can be used in a couple of different ways: -- The browser can display a custom UI to the user informing them of what went wrong (see the [Chrome documentation](https://developers.google.com/privacy-sandbox/blog/fedcm-chrome-120-updates#error-api) for an example). Bear in mind that if the request failed because the IdP server is unavailable, it obviously can't return any information. In such cases, the browser will report this via a generic message. +- The browser can display a custom UI to the user informing them of what went wrong (see the [Chrome documentation](https://privacysandbox.google.com/blog/fedcm-chrome-120-updates#error-api) for an example). Bear in mind that if the request failed because the IdP server is unavailable, it obviously can't return any information. In such cases, the browser will report this via a generic message. - The associated RP {{domxref("CredentialsContainer.get", "navigator.credentials.get()")}} call used to attempt sign-in will reject its promise with an `IdentityCredentialError`, which contains the error information. An RP can catch this error and then follow up the browser's custom UI with some information to help the user succeed in a future sign-in attempt. ## Update login status using the Login Status API @@ -286,7 +299,7 @@ When an [RP attempts federated sign-in](/en-US/docs/Web/API/FedCM_API/RP_sign-in Despite the Login Status API informing the browser of the IdP's login status, it is possible for the browser and IdP to become out of sync. For example, the IdP sessions might expire, meaning that all user accounts end up signed out but the login status is still set to `"logged-in"` (the application was not able to set the login status to `"logged-out"`). In such a case, when federated sign-in is attempted, a request will be made to the IdP's accounts list endpoint but no available accounts will be returned because the session is no longer available. -When this occurs, the browser can dynamically let a user sign into the IdP by opening the IdP's sign-in page in a dialog (the sign-in URL is found in the IdP's [config file](#provide_a_config_file_and_endpoints) `login_url` ). The exact nature of this flow is up to the browser; for example, [Chrome handles it like this](https://developers.google.com/privacy-sandbox/blog/fedcm-chrome-120-updates#what_if_the_user_session_expires_let_the_user_sign_in_through_a_dynamic_login_flow). +When this occurs, the browser can dynamically let a user sign into the IdP by opening the IdP's sign-in page in a dialog (the sign-in URL is found in the IdP's [config file](#provide_a_config_file_and_endpoints) `login_url` ). The exact nature of this flow is up to the browser; for example, [Chrome handles it like this](https://privacysandbox.google.com/blog/fedcm-chrome-120-updates#what_if_the_user_session_expires_let_the_user_sign_in_through_a_dynamic_login_flow). Once the user is signed in to the IdP, the IdP should: @@ -295,4 +308,4 @@ Once the user is signed in to the IdP, the IdP should: ## See also -- [Federated Credential Management API](https://developers.google.com/privacy-sandbox/cookies/fedcm) on developers.google.com (2023) +- [Federated Credential Management API](https://privacysandbox.google.com/cookies/fedcm) on privacysandbox.google.com (2023) diff --git a/files/en-us/web/api/fedcm_api/index.md b/files/en-us/web/api/fedcm_api/index.md index be24401328ef06c..afe5c887236a498 100644 --- a/files/en-us/web/api/fedcm_api/index.md +++ b/files/en-us/web/api/fedcm_api/index.md @@ -37,7 +37,7 @@ There are two parts to using the FedCM API, which are covered in the linked guid ## Permissions Policy integration and `<iframe>` support -The {{httpheader("Permissions-Policy/identity-credentials-get", "identity-credentials-get")}} [Permissions-Policy](/en-US/docs/Web/HTTP/Permissions_Policy) can be used to control permission to use FedCM, more specifically usage of the {{domxref("CredentialsContainer.get", "get()")}} method. +The {{httpheader("Permissions-Policy/identity-credentials-get", "identity-credentials-get")}} [Permissions-Policy](/en-US/docs/Web/HTTP/Guides/Permissions_Policy) can be used to control permission to use FedCM, more specifically usage of the {{domxref("CredentialsContainer.get", "get()")}} method. Developers can explicitly grant permission for an {{htmlelement("iframe")}} to use FedCM via the `allow` attribute: @@ -90,4 +90,4 @@ The availability of FedCM within `<iframe>`s enables a couple of use cases: ## See also -- [Federated Credential Management API](https://developers.google.com/privacy-sandbox/cookies/fedcm) +- [Federated Credential Management API](https://privacysandbox.google.com/cookies/fedcm) diff --git a/files/en-us/web/api/fedcm_api/rp_sign-in/index.md b/files/en-us/web/api/fedcm_api/rp_sign-in/index.md index e29a37f328502e3..4e7fd678487cc66 100644 --- a/files/en-us/web/api/fedcm_api/rp_sign-in/index.md +++ b/files/en-us/web/api/fedcm_api/rp_sign-in/index.md @@ -44,7 +44,7 @@ async function signIn() { The `identity.providers` property takes an array containing a single object specifying the path to an IdP config file (`configURL`) and the RP's client identifier (`clientId`) issued by the IdP. > [!NOTE] -> Currently FedCM only allows the API to be invoked with a single IdP, i.e. the `identity.providers` array has to have a length of 1. To offer users a choice of identity provider, the RP will need to call `get()` separately for each. This may change in the future. +> Currently FedCM only allows the API to be invoked with a single IdP, i.e., the `identity.providers` array has to have a length of 1. To offer users a choice of identity provider, the RP will need to call `get()` separately for each. This may change in the future. The example above also includes a couple of optional features: @@ -52,7 +52,7 @@ The example above also includes a couple of optional features: - The `nonce` property provides a random nonce value that ensures the response is issued for this specific request, preventing {{glossary("replay attack", "replay attacks")}}. - The `loginHint` property provides a hint about the account option(s) the browser should present for user sign-in. This hint is matched against the `login_hints` values that the IdP provides from the [accounts list endpoint](/en-US/docs/Web/API/FedCM_API/IDP_integration#the_accounts_list_endpoint). -The browser requests the IdP config file and carries out the sign-in flow detailed below. For more information on the kind of interaction a user might expect from the browser-supplied UI, see [Sign in to the relying party with the identity provider](https://developers.google.com/privacy-sandbox/cookies/fedcm#sign-in). +The browser requests the IdP config file and carries out the sign-in flow detailed below. For more information on the kind of interaction a user might expect from the browser-supplied UI, see [Sign in to the relying party with the identity provider](https://privacysandbox.google.com/cookies/fedcm#sign-in). ## FedCM sign-in flow @@ -69,13 +69,13 @@ The flow is as follows: 1. The well-known file (`/.well-known/web-identity`), available from `/.well-known/web-identity` at the [eTLD+1](https://web.dev/articles/same-site-same-origin#site) of the `configURL`. 2. The [IdP config file](/en-US/docs/Web/API/FedCM_API/IDP_integration#provide_a_config_file_and_endpoints) (`/config.json`), available at the `configURL`. - These are both [`GET`](/en-US/docs/Web/HTTP/Methods/GET) requests, which don't have cookies and don't follow redirects. This effectively prevents the IdP from learning who made the request and which RP is attempting to connect. + These are both [`GET`](/en-US/docs/Web/HTTP/Reference/Methods/GET) requests, which don't have cookies and don't follow redirects. This effectively prevents the IdP from learning who made the request and which RP is attempting to connect. All requests sent from the browser via FedCM include a `{{httpheader("Sec-Fetch-Dest")}}: webidentity` header to prevent {{glossary("CSRF")}} attacks. All IdP endpoints must confirm this header is included. 3. The IdP responds with the requested well-known file and `config.json` files. The browser validates the config file URL in the `get()` request against the list of valid config URLs inside the well-known file. -4. If the browser has the [IdP's login status](/en-US/docs/Web/API/FedCM_API/IDP_integration#update_login_status_using_the_login_status_api) set to `"logged-in"`, it makes a credentialed request (i.e. with a cookie that identifies the user that is signed in) to the [`accounts_endpoint`](/en-US/docs/Web/API/FedCM_API/IDP_integration#the_accounts_list_endpoint) inside the IdP config file for the user's account details. This is a `GET` request with cookies, but without a `client_id` parameter or the {{httpheader("Origin")}} header. This effectively prevents the IdP from learning which RP the user is trying to sign in to. As a result, the list of accounts returned is RP-agnostic. +4. If the browser has the [IdP's login status](/en-US/docs/Web/API/FedCM_API/IDP_integration#update_login_status_using_the_login_status_api) set to `"logged-in"`, it makes a credentialed request (i.e., with a cookie that identifies the user that is signed in) to the [`accounts_endpoint`](/en-US/docs/Web/API/FedCM_API/IDP_integration#the_accounts_list_endpoint) inside the IdP config file for the user's account details. This is a `GET` request with cookies, but without a `client_id` parameter or the {{httpheader("Origin")}} header. This effectively prevents the IdP from learning which RP the user is trying to sign in to. As a result, the list of accounts returned is RP-agnostic. > [!NOTE] > If the IdP login status is `"logged-out"`, the `get()` call rejects with a `NetworkError` {{domxref("DOMException")}} and does not make a request to the IdP's `accounts_endpoint`. In this case it is up to the developer to handle the flow, for example by prompting the user to go and sign in to a suitable IdP. Note that there may be some delay in the rejection to avoid leaking the IdP login status to the RP. @@ -89,11 +89,11 @@ The flow is as follows: 8. The browser uses the information obtained by the previous two requests to create the UI asking the user to choose an account to sign in to the RP with (in the case where there is more than one available). The UI also asks the user for permission to sign in to the RP using their chosen federated IdP account. > [!NOTE] - > At this stage, if the user has previously authenticated with a federated RP account in the current browser instance (i.e. created a new account with the RP or signed into the RP's website using an existing account), they may be able to **auto-reauthenticate**, depending on what the [`mediation`](/en-US/docs/Web/API/CredentialsContainer/get#mediation) option is set to in the `get()` call. If so the user will be signed in automatically without entering their credentials, as soon as `get()` is invoked. See the [Auto-reauthentication](#auto-reauthentication) section for more details. + > At this stage, if the user has previously authenticated with a federated RP account in the current browser instance (i.e., created a new account with the RP or signed into the RP's website using an existing account), they may be able to **auto-reauthenticate**, depending on what the [`mediation`](/en-US/docs/Web/API/CredentialsContainer/get#mediation) option is set to in the `get()` call. If so the user will be signed in automatically without entering their credentials, as soon as `get()` is invoked. See the [Auto-reauthentication](#auto-reauthentication) section for more details. 9. If the user grants permission to do so, the browser makes a credentialed request to the [`id_assertion_endpoint`](/en-US/docs/Web/API/FedCM_API/IDP_integration#the_id_assertion_endpoint) to request a validation token from the IdP for the selected account. - The credentials are sent in an HTTP [`POST`](/en-US/docs/Web/HTTP/Methods/POST) request with cookies and a content type of `application/x-www-form-urlencoded`. + The credentials are sent in an HTTP [`POST`](/en-US/docs/Web/HTTP/Reference/Methods/POST) request with cookies and a content type of `application/x-www-form-urlencoded`. If the call fails, an error payload is returned as explained in [ID assertion error responses](/en-US/docs/Web/API/FedCM_API/IDP_integration#id_assertion_error_responses) and the promise returned by `get()` will reject with the error. @@ -153,4 +153,4 @@ If auto-reauthentication fails, the behavior depends on the `mediation` value th ## See also -- [Federated Credential Management API](https://developers.google.com/privacy-sandbox/cookies/fedcm) on developers.google.com (2023) +- [Federated Credential Management API](https://privacysandbox.google.com/cookies/fedcm) on privacysandbox.google.com (2023) diff --git a/files/en-us/web/api/fence/getnestedconfigs/index.md b/files/en-us/web/api/fence/getnestedconfigs/index.md index 9df1cd85f3d58e2..d2ae338edae0983 100644 --- a/files/en-us/web/api/fence/getnestedconfigs/index.md +++ b/files/en-us/web/api/fence/getnestedconfigs/index.md @@ -27,7 +27,7 @@ None. `getNestedConfigs()` has two possible return values: -- An array of 20 {{domxref("FencedFrameConfig")}} objects, if the current `<fencedframe>`'s config was created using an API that supports nested configs (for example [Protected Audience](https://developers.google.com/privacy-sandbox/private-advertising/protected-audience)). Of these 20 configs, the first N configs are those registered through the API and the rest are padding configs that will navigate to `about:blank`, so that the number of configs is hidden and cannot leak any information. +- An array of 20 {{domxref("FencedFrameConfig")}} objects, if the current `<fencedframe>`'s config was created using an API that supports nested configs (for example [Protected Audience](https://privacysandbox.google.com/private-advertising/protected-audience)). Of these 20 configs, the first N configs are those registered through the API and the rest are padding configs that will navigate to `about:blank`, so that the number of configs is hidden and cannot leak any information. - `null` if the current `<fencedframe>`'s config was created using an API that does not support nested configs (for example [Shared Storage](/en-US/docs/Web/API/Shared_Storage_API)). ## Examples @@ -53,5 +53,5 @@ frame.config = configs[0]; ## See also -- [Fenced frames](https://developers.google.com/privacy-sandbox/private-advertising/fenced-frame) on developers.google.com -- [The Privacy Sandbox](https://developers.google.com/privacy-sandbox) on developers.google.com +- [Fenced frames](https://privacysandbox.google.com/private-advertising/fenced-frame) on privacysandbox.google.com +- [The Privacy Sandbox](https://privacysandbox.google.com/) on privacysandbox.google.com diff --git a/files/en-us/web/api/fence/index.md b/files/en-us/web/api/fence/index.md index a30b230dcd07fb7..062b6a1d409612b 100644 --- a/files/en-us/web/api/fence/index.md +++ b/files/en-us/web/api/fence/index.md @@ -23,9 +23,9 @@ The **`Fence`** interface of the {{domxref("Fenced Frame API", "Fenced Frame API - {{domxref("Fence.getNestedConfigs", "getNestedConfigs()")}} {{Experimental_Inline}} - : Returns the {{domxref("FencedFrameConfig")}}s loaded into `<fencedframe>`s embedded inside the current `<fencedframe>`. - {{domxref("Fence.reportEvent", "reportEvent()")}} {{Experimental_Inline}} - - : Triggers the submission of report data via a [beacon](/en-US/docs/Web/API/Beacon_API) to one ore more specific URLs registered via the {{domxref("InterestGroupReportingScriptRunnerGlobalScope.registerAdBeacon", "registerAdBeacon()")}} method of the [Protected Audience API](https://developers.google.com/privacy-sandbox/private-advertising/protected-audience), for the purpose of collecting ad auction results. + - : Triggers the submission of report data via a [beacon](/en-US/docs/Web/API/Beacon_API) to one ore more specific URLs registered via the {{domxref("InterestGroupReportingScriptRunnerGlobalScope.registerAdBeacon", "registerAdBeacon()")}} method of the [Protected Audience API](https://privacysandbox.google.com/private-advertising/protected-audience), for the purpose of collecting ad auction results. - {{domxref("Fence.setReportEventDataForAutomaticBeacons", "setReportEventDataForAutomaticBeacons()")}} {{Experimental_Inline}} - - : Specifies event data that will be sent when a navigation occurs inside a `<fencedframe>`. This data will be sent via an automatic beacon to one or more specific URLs registered via the {{domxref("InterestGroupReportingScriptRunnerGlobalScope.registerAdBeacon", "registerAdBeacon()")}} method of the [Protected Audience API](https://developers.google.com/privacy-sandbox/private-advertising/protected-audience), for the purpose of collecting reporting data for ad auction results. + - : Specifies event data that will be sent when a navigation occurs inside a `<fencedframe>`. This data will be sent via an automatic beacon to one or more specific URLs registered via the {{domxref("InterestGroupReportingScriptRunnerGlobalScope.registerAdBeacon", "registerAdBeacon()")}} method of the [Protected Audience API](https://privacysandbox.google.com/private-advertising/protected-audience), for the purpose of collecting reporting data for ad auction results. ## Examples @@ -47,5 +47,5 @@ window.fence.reportEvent({ ## See also -- [Fenced frames](https://developers.google.com/privacy-sandbox/private-advertising/fenced-frame) on developers.google.com -- [The Privacy Sandbox](https://developers.google.com/privacy-sandbox) on developers.google.com +- [Fenced frames](https://privacysandbox.google.com/private-advertising/fenced-frame) on privacysandbox.google.com +- [The Privacy Sandbox](https://privacysandbox.google.com/) on privacysandbox.google.com diff --git a/files/en-us/web/api/fence/reportevent/index.md b/files/en-us/web/api/fence/reportevent/index.md index 2963de844f63064..11128688aace2f9 100644 --- a/files/en-us/web/api/fence/reportevent/index.md +++ b/files/en-us/web/api/fence/reportevent/index.md @@ -11,7 +11,7 @@ browser-compat: api.Fence.reportEvent {{SeeCompatTable}}{{APIRef("Fenced Frame API")}} The **`reportEvent()`** method of the -{{domxref("Fence")}} interface triggers the submission of report data via a [beacon](/en-US/docs/Web/API/Beacon_API) to one or more specific URLs registered via the {{domxref("InterestGroupReportingScriptRunnerGlobalScope.registerAdBeacon", "registerAdBeacon()")}} method of the [Protected Audience API](https://developers.google.com/privacy-sandbox/private-advertising/protected-audience), for the purpose of collecting ad auction results. +{{domxref("Fence")}} interface triggers the submission of report data via a [beacon](/en-US/docs/Web/API/Beacon_API) to one or more specific URLs registered via the {{domxref("InterestGroupReportingScriptRunnerGlobalScope.registerAdBeacon", "registerAdBeacon()")}} method of the [Protected Audience API](https://privacysandbox.google.com/private-advertising/protected-audience), for the purpose of collecting ad auction results. > **Note:** {{domxref("Fence.setReportEventDataForAutomaticBeacons", "setReportEventDataForAutomaticBeacons()")}} provides similar report data submission, except in that case the submission is triggered via a navigation rather than by an explicit method call. @@ -27,16 +27,16 @@ reportEvent(event) - : An object or string representing the data to send. - An object value defines a specific report event that you want to send. The required properties are as follows: - `eventType` - - : A string representing the type of event that is being reported — for example you might be interested in how many times an ad is clicked on. This string can be any relevant event name (for example [`click`](/en-US/docs/Web/API/Element/click_event)). This needs to match the event type specified in the associated {{domxref("InterestGroupReportingScriptRunnerGlobalScope.registerAdBeacon", "registerAdBeacon()")}} call in a [Protected Audience API](https://developers.google.com/privacy-sandbox/private-advertising/protected-audience) worklet. + - : A string representing the type of event that is being reported — for example you might be interested in how many times an ad is clicked on. This string can be any relevant event name (for example [`click`](/en-US/docs/Web/API/Element/click_event)). This needs to match the event type specified in the associated {{domxref("InterestGroupReportingScriptRunnerGlobalScope.registerAdBeacon", "registerAdBeacon()")}} call in a [Protected Audience API](https://privacysandbox.google.com/private-advertising/protected-audience) worklet. - `eventData` - : A string representing the data to be sent. - `destination` - - : An array containing one or more enumerated values representing destination types. These are the involved parties that will receive the data to their registered URLs (i.e. via {{domxref("InterestGroupReportingScriptRunnerGlobalScope.registerAdBeacon", "registerAdBeacon()")}}). The possible values are: + - : An array containing one or more enumerated values representing destination types. These are the involved parties that will receive the data to their registered URLs (i.e., via {{domxref("InterestGroupReportingScriptRunnerGlobalScope.registerAdBeacon", "registerAdBeacon()")}}). The possible values are: - `"buyer"`: The bidder in the ad auction. - `"seller"`: The top-level seller running the ad auction. - `"component-seller"`: The seller for a component auction in a multi-level auction. - `"direct-seller"`: The seller that directly ran the auction the buyer bid in. If the ad was a single-level auction, the value used will be `"seller"`. If the ad was a multi-level auction, the value used will be `"component-seller"`. - - `"shared-storage-select-url"`: A [Shared Storage API](https://developers.google.com/privacy-sandbox/private-advertising/shared-storage) storage location, as defined in a {{domxref("WindowSharedStorage.selectURL", "Window.sharedStorage.selectURL()")}} method call. + - `"shared-storage-select-url"`: A [Shared Storage API](https://privacysandbox.google.com/private-advertising/shared-storage) storage location, as defined in a {{domxref("WindowSharedStorage.selectURL", "Window.sharedStorage.selectURL()")}} method call. - A string value represents an `eventType`, for example `"click"` (see the earlier definition of `eventType`). When an `eventType` string is passed as the value of `reportEvent()`, it triggers all Private Aggregation contributions that were made conditional on that event type (for example via {{domxref("PrivateAggregation.contributeToHistogramOnEvent()")}}) to be sent. ### Return value @@ -63,5 +63,5 @@ window.fence.reportEvent({ ## See also -- [Fenced frames](https://developers.google.com/privacy-sandbox/private-advertising/fenced-frame) on developers.google.com -- [The Privacy Sandbox](https://developers.google.com/privacy-sandbox) on developers.google.com +- [Fenced frames](https://privacysandbox.google.com/private-advertising/fenced-frame) on privacysandbox.google.com +- [The Privacy Sandbox](https://privacysandbox.google.com/) on privacysandbox.google.com diff --git a/files/en-us/web/api/fence/setreporteventdataforautomaticbeacons/index.md b/files/en-us/web/api/fence/setreporteventdataforautomaticbeacons/index.md index 748187e35064032..998636de10909fc 100644 --- a/files/en-us/web/api/fence/setreporteventdataforautomaticbeacons/index.md +++ b/files/en-us/web/api/fence/setreporteventdataforautomaticbeacons/index.md @@ -11,7 +11,7 @@ browser-compat: api.Fence.setReportEventDataForAutomaticBeacons {{SeeCompatTable}}{{APIRef("Fenced Frame API")}} The **`setReportEventDataForAutomaticBeacons()`** method of the -{{domxref("Fence")}} interface specifies event data that will be sent when a navigation occurs inside a {{htmlelement("fencedframe")}}. This data will be sent via an automatic [beacon](/en-US/docs/Web/API/Beacon_API) to one or more specific URLs registered via the {{domxref("InterestGroupReportingScriptRunnerGlobalScope.registerAdBeacon", "registerAdBeacon()")}} method of the [Protected Audience API](https://developers.google.com/privacy-sandbox/private-advertising/protected-audience), for the purpose of collecting reporting data for ad auction results. +{{domxref("Fence")}} interface specifies event data that will be sent when a navigation occurs inside a {{htmlelement("fencedframe")}}. This data will be sent via an automatic [beacon](/en-US/docs/Web/API/Beacon_API) to one or more specific URLs registered via the {{domxref("InterestGroupReportingScriptRunnerGlobalScope.registerAdBeacon", "registerAdBeacon()")}} method of the [Protected Audience API](https://privacysandbox.google.com/private-advertising/protected-audience), for the purpose of collecting reporting data for ad auction results. > **Note:** {{domxref("Fence.reportEvent", "reportEvent()")}} provides similar report data submission, except in that case the submission is triggered via an explicit method call rather than a navigation. @@ -32,12 +32,12 @@ setReportEventDataForAutomaticBeacons(event) - `eventData` - : A string representing the data to be sent. - `destination` - - : An array containing one or more enumerated values representing destination types. These are the involved parties that will receive the data to their registered URLs (i.e. via {{domxref("InterestGroupReportingScriptRunnerGlobalScope.registerAdBeacon", "registerAdBeacon()")}}). The possible values are: + - : An array containing one or more enumerated values representing destination types. These are the involved parties that will receive the data to their registered URLs (i.e., via {{domxref("InterestGroupReportingScriptRunnerGlobalScope.registerAdBeacon", "registerAdBeacon()")}}). The possible values are: - `"buyer"`: The bidder in the ad auction. - `"seller"`: The top-level seller running the ad auction. - `"component-seller"`: The seller for a component auction in a multi-level auction. - `"direct-seller"`: The seller that directly ran the auction the buyer bid in. If the ad was a single-level auction, the value used will be `"seller"`. If the ad was a multi-level auction, the value used will be `"component-seller"`. - - `"shared-storage-select-url"`: A [Shared Storage API](https://developers.google.com/privacy-sandbox/private-advertising/shared-storage) storage location, as defined in a {{domxref("WindowSharedStorage.selectURL", "Window.sharedStorage.selectURL()")}} method call. + - `"shared-storage-select-url"`: A [Shared Storage API](https://privacysandbox.google.com/private-advertising/shared-storage) storage location, as defined in a {{domxref("WindowSharedStorage.selectURL", "Window.sharedStorage.selectURL()")}} method call. - `once` {{optional_inline}} - : A boolean value. If set to `true`, the automatic beacon will only be sent for the next event, and beacons will not be sent for subsequent events until `setReportEventDataForAutomaticBeacons()` is invoked again. For example, when used with a `click` handler this can be used to send beacon data only for specific top-level navigations, rather than for every top-level navigation. This property defaults to `false`. @@ -65,5 +65,5 @@ window.fence.setReportEventDataForAutomaticBeacons({ ## See also -- [Fenced frames](https://developers.google.com/privacy-sandbox/private-advertising/fenced-frame) on developers.google.com -- [The Privacy Sandbox](https://developers.google.com/privacy-sandbox) on developers.google.com +- [Fenced frames](https://privacysandbox.google.com/private-advertising/fenced-frame) on privacysandbox.google.com +- [The Privacy Sandbox](https://privacysandbox.google.com/) on privacysandbox.google.com diff --git a/files/en-us/web/api/fenced_frame_api/communication_with_embedded_frames/index.md b/files/en-us/web/api/fenced_frame_api/communication_with_embedded_frames/index.md index fb2690a2ae272b8..0e7cc1f5ac52c7c 100644 --- a/files/en-us/web/api/fenced_frame_api/communication_with_embedded_frames/index.md +++ b/files/en-us/web/api/fenced_frame_api/communication_with_embedded_frames/index.md @@ -6,7 +6,7 @@ page-type: guide {{DefaultAPISidebar("Fenced Frame API")}} -This article provides information on how communication differs between an embedder and content embedded inside different types of frame (i.e. an {{htmlelement("iframe")}} and a {{htmlelement("fencedframe")}}), and how passed data can be stored. +This article provides information on how communication differs between an embedder and content embedded inside different types of frame (i.e., an {{htmlelement("iframe")}} and a {{htmlelement("fencedframe")}}), and how passed data can be stored. ## How to communicate between the embedder and an `<iframe>` @@ -18,7 +18,7 @@ From the `<iframe>`, you can listen to a [`message`](/en-US/docs/Web/API/Window/ ## How to communicate between the embedder and a `<fencedframe>` -Fenced frames are intended to be used for cases such as displaying targeted ads selected via the [Protected Audience API](https://developers.google.com/privacy-sandbox/private-advertising/protected-audience) and {{domxref("WindowSharedStorage.selectURL()")}}. Communicating between `<fencedframe>`s and other pages outside the `<fencedframe>` on the page is intentionally limited, but one method of communication between the embedder and shared storage worklets does exist — {{domxref("FencedFrameConfig.setSharedStorageContext()")}}. +Fenced frames are intended to be used for cases such as displaying targeted ads selected via the [Protected Audience API](https://privacysandbox.google.com/private-advertising/protected-audience) and {{domxref("WindowSharedStorage.selectURL()")}}. Communicating between `<fencedframe>`s and other pages outside the `<fencedframe>` on the page is intentionally limited, but one method of communication between the embedder and shared storage worklets does exist — {{domxref("FencedFrameConfig.setSharedStorageContext()")}}. > [!NOTE] > Within the same `<fencedframe>` tree, communication between frames is allowed. For example, a root `<fencedframe>` can send a message to a child `<iframe>` in its own tree, and a child `<iframe>` can send a message to the parent `<fencedframe>`. diff --git a/files/en-us/web/api/fenced_frame_api/index.md b/files/en-us/web/api/fenced_frame_api/index.md index 367b57c899340ca..33ad6536219f803 100644 --- a/files/en-us/web/api/fenced_frame_api/index.md +++ b/files/en-us/web/api/fenced_frame_api/index.md @@ -9,13 +9,17 @@ browser-compat: html.elements.fencedframe {{SeeCompatTable}}{{DefaultAPISidebar("Fenced Frame API")}} +> [!WARNING] +> This feature is currently opposed by one browser vendor. +> See the [Standards positions](#standards_positions) section below for details. + The **Fenced Frame API** provides functionality for controlling content embedded in {{htmlelement("fencedframe")}} elements. ## Concepts and usage One major source of [privacy](/en-US/docs/Web/Privacy) and [security](/en-US/docs/Web/Security) problems on the web is content embedded in {{htmlelement("iframe")}} elements. Historically `<iframe>`s have been used to set third-party cookies, which can be used to share information and track users across sites. In addition, content embedded in an `<iframe>` can communicate with its embedding document (for example, using {{domxref("Window.postMessage()")}}). -The embedding document can also use scripting to read various forms of information from the `<iframe>` — for example you can potentially get significant tracking/fingerprinting data from reading the embedded URL from the `src` property, especially if it contains [URL parameters](/en-US/docs/Web/URI#query). The `<iframe>` can also access the embedding context's DOM, and vice versa. +The embedding document can also use scripting to read various forms of information from the `<iframe>` — for example you can potentially get significant tracking/fingerprinting data from reading the embedded URL from the `src` property, especially if it contains [URL parameters](/en-US/docs/Web/URI/Reference/Query). The `<iframe>` can also access the embedding context's DOM, and vice versa. Most modern browsers are working on mechanisms to partition storage so that cookie data can no longer be used for tracking (for example see [Cookies Having Independent Partitioned State (CHIPS)](/en-US/docs/Web/Privacy/Guides/Privacy_sandbox/Partitioned_cookies) or [Firefox State Partitioning](/en-US/docs/Web/Privacy/Guides/State_Partitioning)). @@ -32,24 +36,24 @@ For more information about the communication model of fenced frames, read the [c `<fencedframe>`s are used by other APIs to embed different types of cross-site content or collect data, fulfilling different use cases in a privacy-preserving manner. Most of these previously relied on third-party cookies or other mechanisms that were bad for privacy. -- The [Shared Storage API](https://developers.google.com/privacy-sandbox/private-advertising/shared-storage) provides access to unpartitioned cross-site data in a secure environment, calculating and/or displaying results in a `<fencedframe>`. For example: +- The [Shared Storage API](https://privacysandbox.google.com/private-advertising/shared-storage) provides access to unpartitioned cross-site data in a secure environment, calculating and/or displaying results in a `<fencedframe>`. For example: - Advertisers can measure the reach of an ad, or serve subsequent ads based on which ones users have already seen on other sites. - Developers can do A/B testing, showing variants to a user based on a group they are assigned to, or based on how many users have seen each one already. - Businesses can customize the user's experience based on what they have seen on other sites. For example, if they have already purchased membership, you might not want to show them membership sign-up ads across your other properties. -- The [Protected Audience API](https://developers.google.com/privacy-sandbox/private-advertising/protected-audience) allows developers to implement interest group-based advertising, namely remarketing and custom audience use cases. It can evaluate multiple bids for ad space and display the winning ad in a `<fencedframe>`. -- The [Private Aggregation API](https://developers.google.com/privacy-sandbox/private-advertising/private-aggregation) can gather data from `<fencedframe>`s (originating from shared storage or the Protected Audience API) and create aggregated reports. +- The [Protected Audience API](https://privacysandbox.google.com/private-advertising/protected-audience) allows developers to implement interest group-based advertising, namely remarketing and custom audience use cases. It can evaluate multiple bids for ad space and display the winning ad in a `<fencedframe>`. +- The [Private Aggregation API](https://privacysandbox.google.com/private-advertising/private-aggregation) can gather data from `<fencedframe>`s (originating from shared storage or the Protected Audience API) and create aggregated reports. ## How do `<fencedframe>`s work? As mentioned above, you don't control the content embedded in a {{htmlelement("fencedframe")}} directly via regular script. -To set what content will be shown in a `<fencedframe>`, a utilizing API (such as [Protected Audience](https://developers.google.com/privacy-sandbox/private-advertising/protected-audience) or [Shared Storage](https://developers.google.com/privacy-sandbox/private-advertising/shared-storage)) generates a {{domxref("FencedFrameConfig")}} object, which is then set via JavaScript as the value of the `<fencedframe>`'s {{domxref("HTMLFencedFrameElement.config")}} property. +To set what content will be shown in a `<fencedframe>`, a utilizing API (such as [Protected Audience](https://privacysandbox.google.com/private-advertising/protected-audience) or [Shared Storage](https://privacysandbox.google.com/private-advertising/shared-storage)) generates a {{domxref("FencedFrameConfig")}} object, which is then set via JavaScript as the value of the `<fencedframe>`'s {{domxref("HTMLFencedFrameElement.config")}} property. The following example gets a `FencedFrameConfig` from a Protected Audience API's ad auction, which is then used to display the winning ad in a `<fencedframe>`: ```js const frameConfig = await navigator.runAdAuction({ - // ...auction configuration + // … auction configuration resolveToConfig: true, }); @@ -57,14 +61,14 @@ const frame = document.createElement("fencedframe"); frame.config = frameConfig; ``` -`resolveToConfig: true` must be passed in to the `runAdAuction()` call to obtain a `FencedFrameConfig` object. If `resolveToConfig` is set to `false`, the resulting {{jsxref("Promise")}} will resolve to an opaque [URN](/en-US/docs/Web/URI#urns) (for example `urn:uuid:c36973b5-e5d9-de59-e4c4-364f137b3c7a`) that can only be used in an `<iframe>`. +`resolveToConfig: true` must be passed in to the `runAdAuction()` call to obtain a `FencedFrameConfig` object. If `resolveToConfig` is set to `false`, the resulting {{jsxref("Promise")}} will resolve to an opaque [URN](/en-US/docs/Web/URI/Reference/Schemes/urn) (for example `urn:uuid:c36973b5-e5d9-de59-e4c4-364f137b3c7a`) that can only be used in an `<iframe>`. Either way, the browser stores a URL containing the target location of the content to embed — mapped to the opaque URN, or the `FencedFrameConfig`'s internal `url` property. The URL value cannot be read by JavaScript running in the embedding context. > [!NOTE] -> Support is provided for opaque URNs in `<iframe>`s to ease migration of existing implementations over to [privacy sandbox](https://developers.google.com/privacy-sandbox) APIs. This support is intended to be temporary and will be removed in the future as adoption grows. +> Support is provided for opaque URNs in `<iframe>`s to ease migration of existing implementations over to [privacy sandbox](https://privacysandbox.google.com/) APIs. This support is intended to be temporary and will be removed in the future as adoption grows. -> **Note:** `FencedFrameConfig` has a {{domxref("FencedFrameConfig.setSharedStorageContext", "setSharedStorageContext()")}} method that is used to pass in data from the embedding document to the `<fencedframe>`'s shared storage. It could for example be accessed in a {{domxref("Worklet")}} via the `<fencedframe>` and used to generate a report. See the [Shared Storage API](https://developers.google.com/privacy-sandbox/private-advertising/shared-storage) for more details. +> **Note:** `FencedFrameConfig` has a {{domxref("FencedFrameConfig.setSharedStorageContext", "setSharedStorageContext()")}} method that is used to pass in data from the embedding document to the `<fencedframe>`'s shared storage. It could for example be accessed in a {{domxref("Worklet")}} via the `<fencedframe>` and used to generate a report. See the [Shared Storage API](https://privacysandbox.google.com/private-advertising/shared-storage) for more details. ### Accessing fenced frame functionality on the `Fence` object @@ -73,7 +77,7 @@ For example, {{domxref("Fence.reportEvent()")}} provides a way to trigger the su ### Permissions policy -Only specific features designed to be used in `<fencedframe>`s can be enabled via permissions policies set on them; other policy-controlled features are not available in this context. See [Permissions policies available to fenced frames](/en-US/docs/Web/HTML/Element/fencedframe#permissions_policies_available_to_fenced_frames) for more details. +Only specific features designed to be used in `<fencedframe>`s can be enabled via permissions policies set on them; other policy-controlled features are not available in this context. See [Permissions policies available to fenced frames](/en-US/docs/Web/HTML/Reference/Elements/fencedframe#permissions_policies_available_to_fenced_frames) for more details. ### HTTP headers @@ -91,10 +95,10 @@ Supports-Loading-Mode: fenced-frame Other effects of fenced frames on HTTP headers are as follows: -- [User-agent client hints](/en-US/docs/Web/HTTP/Client_hints#user-agent_client_hints) are not available inside fenced frames because they rely on [permissions policy](/en-US/docs/Web/HTTP/Permissions_Policy) delegation, which could be used to leak data. -- Strict [`Cross-Origin-Opener-Policy`](/en-US/docs/Web/HTTP/Headers/Cross-Origin-Opener-Policy) settings are enforced on new browsing contexts opened from inside fenced frames, otherwise they could be used to leak information to other origins. Any new window opened from inside a fenced frame will have [`rel="noopener"`](/en-US/docs/Web/HTML/Attributes/rel/noopener) and `Cross-Origin-Opener-Policy: same-origin` set to ensure that {{domxref("Window.opener")}} returns `null` and place it in its own browsing context group. -- [`Content-Security-Policy: fenced-frame-src`](/en-US/docs/Web/HTTP/Headers/Content-Security-Policy/fenced-frame-src) has been added for specifying valid sources for nested browsing contexts loaded into `<fencedframe>` elements. -- [`Content-Security-Policy: sandbox`](/en-US/docs/Web/HTTP/Headers/Content-Security-Policy/sandbox) custom settings cannot be inherited by fenced frames, to mitigate privacy issues. For a fenced frame to load, you need to specify no `sandbox` CSP (which implies the below values), or specify the following sandbox values: +- [User-agent client hints](/en-US/docs/Web/HTTP/Guides/Client_hints#user_agent_client_hints) are not available inside fenced frames because they rely on [permissions policy](/en-US/docs/Web/HTTP/Guides/Permissions_Policy) delegation, which could be used to leak data. +- Strict [`Cross-Origin-Opener-Policy`](/en-US/docs/Web/HTTP/Reference/Headers/Cross-Origin-Opener-Policy) settings are enforced on new browsing contexts opened from inside fenced frames, otherwise they could be used to leak information to other origins. Any new window opened from inside a fenced frame will have [`rel="noopener"`](/en-US/docs/Web/HTML/Reference/Attributes/rel/noopener) and `Cross-Origin-Opener-Policy: same-origin` set to ensure that {{domxref("Window.opener")}} returns `null` and place it in its own browsing context group. +- [`Content-Security-Policy: fenced-frame-src`](/en-US/docs/Web/HTTP/Reference/Headers/Content-Security-Policy/fenced-frame-src) has been added for specifying valid sources for nested browsing contexts loaded into `<fencedframe>` elements. +- [`Content-Security-Policy: sandbox`](/en-US/docs/Web/HTTP/Reference/Headers/Content-Security-Policy/sandbox) custom settings cannot be inherited by fenced frames, to mitigate privacy issues. For a fenced frame to load, you need to specify no `sandbox` CSP (which implies the below values), or specify the following sandbox values: - `allow-same-origin` - `allow-forms` - `allow-scripts` @@ -109,7 +113,7 @@ Other effects of fenced frames on HTTP headers are as follows: ## Interfaces - {{domxref("FencedFrameConfig")}} - - : Represents the navigation of a {{htmlelement("fencedframe")}}, i.e. what content will be displayed in it. A `FencedFrameConfig` is returned from a source such as the [Protected Audience API](https://developers.google.com/privacy-sandbox/private-advertising/protected-audience) and set as the value of {{domxref("HTMLFencedFrameElement.config")}}. + - : Represents the navigation of a {{htmlelement("fencedframe")}}, i.e., what content will be displayed in it. A `FencedFrameConfig` is returned from a source such as the [Protected Audience API](https://privacysandbox.google.com/private-advertising/protected-audience) and set as the value of {{domxref("HTMLFencedFrameElement.config")}}. - {{domxref("Fence")}} - : Contains several functions relevant to fenced frame functionality. Available only to documents embedded inside a `<fencedframe>`. - {{domxref("HTMLFencedFrameElement")}} @@ -124,7 +128,7 @@ Other effects of fenced frames on HTTP headers are as follows: ## Enrollment and local testing -Certain API features that create {{domxref("FencedFrameConfig")}}s such as {{domxref("Navigator.runAdAuction()")}} ([Protected Audience API](https://developers.google.com/privacy-sandbox/private-advertising/protected-audience)) and {{domxref("WindowSharedStorage.selectURL()")}} ([Shared Storage API](/en-US/docs/Web/API/Shared_Storage_API)), as well as other features such as {{domxref("Fence.reportEvent()")}}, require you to enroll your site in a [privacy sandbox enrollment process](/en-US/docs/Web/Privacy/Guides/Privacy_sandbox/Enrollment). If you don't do this, the API calls will fail with a console warning. +Certain API features that create {{domxref("FencedFrameConfig")}}s such as {{domxref("Navigator.runAdAuction()")}} ([Protected Audience API](https://privacysandbox.google.com/private-advertising/protected-audience)) and {{domxref("WindowSharedStorage.selectURL()")}} ([Shared Storage API](/en-US/docs/Web/API/Shared_Storage_API)), as well as other features such as {{domxref("Fence.reportEvent()")}}, require you to enroll your site in a [privacy sandbox enrollment process](/en-US/docs/Web/Privacy/Guides/Privacy_sandbox/Enrollment). If you don't do this, the API calls will fail with a console warning. > [!NOTE] > In Chrome, you can still test your fenced frame code locally without enrollment. To allow local testing, enable the following Chrome developer flag: @@ -142,11 +146,18 @@ The following demos all make use of `<fencedframe>`s: {{Specifications}} +### Standards positions + +One browser vendor [opposes](/en-US/docs/Glossary/Web_standards#opposing_standards) this specification. +Known standards positions are as follows: + +- Mozilla (Firefox): [Negative](https://github.com/mozilla/standards-positions/issues/781) + ## Browser compatibility {{Compat}} ## See also -- [Fenced frames](https://developers.google.com/privacy-sandbox/private-advertising/fenced-frame) on developers.google.com -- [The Privacy Sandbox](https://developers.google.com/privacy-sandbox) on developers.google.com +- [Fenced frames](https://privacysandbox.google.com/private-advertising/fenced-frame) on privacysandbox.google.com +- [The Privacy Sandbox](https://privacysandbox.google.com/) on privacysandbox.google.com diff --git a/files/en-us/web/api/fencedframeconfig/index.md b/files/en-us/web/api/fencedframeconfig/index.md index 050da2b8147ab38..f29ec65086efaa3 100644 --- a/files/en-us/web/api/fencedframeconfig/index.md +++ b/files/en-us/web/api/fencedframeconfig/index.md @@ -9,9 +9,9 @@ browser-compat: api.FencedFrameConfig {{SeeCompatTable}}{{APIRef("Fenced Frame API")}} -The **`FencedFrameConfig`** interface represents the navigation of a {{htmlelement("fencedframe")}}, i.e. what content will be displayed in it. +The **`FencedFrameConfig`** interface represents the navigation of a {{htmlelement("fencedframe")}}, i.e., what content will be displayed in it. -`FencedFrameConfig` objects cannot be constructed manually via JavaScript. They are returned from a source such as the [Protected Audience API](https://developers.google.com/privacy-sandbox/private-advertising/protected-audience) and set as the value of {{domxref("HTMLFencedFrameElement.config")}}. +`FencedFrameConfig` objects cannot be constructed manually via JavaScript. They are returned from a source such as the [Protected Audience API](https://privacysandbox.google.com/private-advertising/protected-audience) and set as the value of {{domxref("HTMLFencedFrameElement.config")}}. A `FencedFrameConfig` object instance has an exposed method, but it also maps to internal config information containing opaque properties not accessible from JavaScript. This includes information such as the source of the loaded content and interest groups for advertising purposes. It is key to how fenced frames help to implement key use cases while respecting user privacy. @@ -26,13 +26,13 @@ A `FencedFrameConfig` object instance has an exposed method, but it also maps to ### Basic usage -To set what content will be shown in a `<fencedframe>`, a utilizing API (such as [Protected Audience](https://developers.google.com/privacy-sandbox/private-advertising/protected-audience) or [Shared Storage](https://developers.google.com/privacy-sandbox/private-advertising/shared-storage)) generates a `FencedFrameConfig` object, which is then set as the value of the `<fencedframe>`'s `config` property. +To set what content will be shown in a `<fencedframe>`, a utilizing API (such as [Protected Audience](https://privacysandbox.google.com/private-advertising/protected-audience) or [Shared Storage](https://privacysandbox.google.com/private-advertising/shared-storage)) generates a `FencedFrameConfig` object, which is then set as the value of the `<fencedframe>`'s `config` property. The following example gets a `FencedFrameConfig` from a Protected Audience API's ad auction, which is then used to display the winning ad in a `<fencedframe>`: ```js const frameConfig = await navigator.runAdAuction({ - // ...auction configuration + // … auction configuration resolveToConfig: true, }); @@ -44,9 +44,9 @@ frame.config = frameConfig; ### Passing contextual data via `setSharedStorageContext()` -You can use the [Private Aggregation API](https://developers.google.com/privacy-sandbox/private-advertising/private-aggregation) to create reports that combine event-level data inside fenced frames with contextual data from the embedding document. `setSharedStorageContext()` can be used to pass contextual data from the embedder to shared storage worklets initiated by the [Protected Audience API](https://developers.google.com/privacy-sandbox/private-advertising/protected-audience). +You can use the [Private Aggregation API](https://privacysandbox.google.com/private-advertising/private-aggregation) to create reports that combine event-level data inside fenced frames with contextual data from the embedding document. `setSharedStorageContext()` can be used to pass contextual data from the embedder to shared storage worklets initiated by the [Protected Audience API](https://privacysandbox.google.com/private-advertising/protected-audience). -In the following example, we store data from both the embedding page and the fenced frame in [shared storage](https://developers.google.com/privacy-sandbox/private-advertising/shared-storage). +In the following example, we store data from both the embedding page and the fenced frame in [shared storage](https://privacysandbox.google.com/private-advertising/shared-storage). In the embedding page, we will set a mock event ID as the shared storage context using `setSharedStorageContext()`: @@ -76,12 +76,16 @@ await window.sharedStorage.run("send-report", { }); ``` -In the `reporting-worklet.js` worklet, we read the embedding document's event ID from `sharedStorage.context` and the frame's event-level data from the data object, then report them through [Private Aggregation](https://developers.google.com/privacy-sandbox/private-advertising/private-aggregation): +In the `reporting-worklet.js` worklet, we read the embedding document's event ID from `sharedStorage.context` and the frame's event-level data from the data object, then report them through [Private Aggregation](https://privacysandbox.google.com/private-advertising/private-aggregation): ```js class ReportingOperation { - convertEventIdToBucket(eventId) { ... } - convertEventPayloadToValue(info) { ... } + convertEventIdToBucket(eventId) { + // … + } + convertEventPayloadToValue(info) { + // … + } async run(data) { // Data from the embedder @@ -92,12 +96,12 @@ class ReportingOperation { privateAggregation.sendHistogramReport({ bucket: convertEventIdToBucket(eventId), - value: convertEventPayloadToValue(eventPayload) + value: convertEventPayloadToValue(eventPayload), }); } } -register('send-report', ReportingOperation); +register("send-report", ReportingOperation); ``` ## Specifications @@ -110,5 +114,5 @@ register('send-report', ReportingOperation); ## See also -- [Fenced frames](https://developers.google.com/privacy-sandbox/private-advertising/fenced-frame) on developers.google.com -- [The Privacy Sandbox](https://developers.google.com/privacy-sandbox) on developers.google.com +- [Fenced frames](https://privacysandbox.google.com/private-advertising/fenced-frame) on privacysandbox.google.com +- [The Privacy Sandbox](https://privacysandbox.google.com/) on privacysandbox.google.com diff --git a/files/en-us/web/api/fencedframeconfig/setsharedstoragecontext/index.md b/files/en-us/web/api/fencedframeconfig/setsharedstoragecontext/index.md index 52a2068cc78d126..efaff45b63e83a8 100644 --- a/files/en-us/web/api/fencedframeconfig/setsharedstoragecontext/index.md +++ b/files/en-us/web/api/fencedframeconfig/setsharedstoragecontext/index.md @@ -11,7 +11,7 @@ browser-compat: api.FencedFrameConfig.setSharedStorageContext {{APIRef("Fenced Frame API")}}{{SeeCompatTable}} The **`setSharedStorageContext()`** method of the -{{domxref("FencedFrameConfig")}} interface passes in contextual data from the embedding document to the `<fencedframe>`'s [shared storage](https://developers.google.com/privacy-sandbox/private-advertising/shared-storage). +{{domxref("FencedFrameConfig")}} interface passes in contextual data from the embedding document to the `<fencedframe>`'s [shared storage](https://privacysandbox.google.com/private-advertising/shared-storage). ## Syntax @@ -32,9 +32,9 @@ None (`Undefined`). ### Passing contextual data via `setSharedStorageContext()` -You can use the [Private Aggregation API](https://developers.google.com/privacy-sandbox/private-advertising/private-aggregation) to create reports that combine event-level data inside fenced frames with contextual data from the embedding document. `setSharedStorageContext()` can be used to pass contextual data from the embedder to shared storage worklets initiated by the [Protected Audience API](https://developers.google.com/privacy-sandbox/private-advertising/protected-audience). +You can use the [Private Aggregation API](https://privacysandbox.google.com/private-advertising/private-aggregation) to create reports that combine event-level data inside fenced frames with contextual data from the embedding document. `setSharedStorageContext()` can be used to pass contextual data from the embedder to shared storage worklets initiated by the [Protected Audience API](https://privacysandbox.google.com/private-advertising/protected-audience). -In the following example, we store data from both the embedding page and the fenced frame in [shared storage](https://developers.google.com/privacy-sandbox/private-advertising/shared-storage). +In the following example, we store data from both the embedding page and the fenced frame in [shared storage](https://privacysandbox.google.com/private-advertising/shared-storage). In the embedding page, we will set a mock event ID as the shared storage context using `setSharedStorageContext()`: @@ -68,8 +68,12 @@ In the `reporting-worklet.js` worklet, we read the embedding document's event ID ```js class ReportingOperation { - convertEventIdToBucket(eventId) { ... } - convertEventPayloadToValue(info) { ... } + convertEventIdToBucket(eventId) { + // … + } + convertEventPayloadToValue(info) { + // … + } async run(data) { // Data from the embedder @@ -80,12 +84,12 @@ class ReportingOperation { privateAggregation.sendHistogramReport({ bucket: convertEventIdToBucket(eventId), - value: convertEventPayloadToValue(eventPayload) + value: convertEventPayloadToValue(eventPayload), }); } } -register('send-report', ReportingOperation); +register("send-report", ReportingOperation); ``` ## Specifications @@ -98,5 +102,5 @@ register('send-report', ReportingOperation); ## See also -- [Fenced frames](https://developers.google.com/privacy-sandbox/private-advertising/fenced-frame) on developers.google.com -- [The Privacy Sandbox](https://developers.google.com/privacy-sandbox) on developers.google.com +- [Fenced frames](https://privacysandbox.google.com/private-advertising/fenced-frame) on privacysandbox.google.com +- [The Privacy Sandbox](https://privacysandbox.google.com/) on privacysandbox.google.com diff --git a/files/en-us/web/api/fetch_api/index.md b/files/en-us/web/api/fetch_api/index.md index f06d3d7ec063186..bfb555c00bfc853 100644 --- a/files/en-us/web/api/fetch_api/index.md +++ b/files/en-us/web/api/fetch_api/index.md @@ -23,7 +23,7 @@ You can create a request and response directly using the {{DOMxRef("Request.Requ Find out more about using the Fetch API features in [Using Fetch](/en-US/docs/Web/API/Fetch_API/Using_Fetch). -## Fetch Interfaces +## Interfaces - {{domxref("Window.fetch()")}} and {{domxref("WorkerGlobalScope.fetch()")}} - : The `fetch()` method used to fetch a resource. @@ -46,5 +46,5 @@ Find out more about using the Fetch API features in [Using Fetch](/en-US/docs/We - [Using Fetch](/en-US/docs/Web/API/Fetch_API/Using_Fetch) - [Service Worker API](/en-US/docs/Web/API/Service_Worker_API) -- [HTTP access control (CORS)](/en-US/docs/Web/HTTP/CORS) +- [HTTP access control (CORS)](/en-US/docs/Web/HTTP/Guides/CORS) - [HTTP](/en-US/docs/Web/HTTP) diff --git a/files/en-us/web/api/fetch_api/using_fetch/index.md b/files/en-us/web/api/fetch_api/using_fetch/index.md index c470f21c32aad14..ace06d6e4ea0a32 100644 --- a/files/en-us/web/api/fetch_api/using_fetch/index.md +++ b/files/en-us/web/api/fetch_api/using_fetch/index.md @@ -8,7 +8,7 @@ page-type: guide The [Fetch API](/en-US/docs/Web/API/Fetch_API) provides a JavaScript interface for making HTTP requests and processing the responses. -Fetch is the modern replacement for {{domxref("XMLHttpRequest")}}: unlike `XMLHttpRequest`, which uses callbacks, Fetch is promise-based and is integrated with features of the modern web such as [service workers](/en-US/docs/Web/API/Service_Worker_API) and [Cross-Origin Resource Sharing (CORS)](/en-US/docs/Web/HTTP/CORS). +Fetch is the modern replacement for {{domxref("XMLHttpRequest")}}: unlike `XMLHttpRequest`, which uses callbacks, Fetch is promise-based and is integrated with features of the modern web such as [service workers](/en-US/docs/Web/API/Service_Worker_API) and [Cross-Origin Resource Sharing (CORS)](/en-US/docs/Web/HTTP/Guides/CORS). With the Fetch API, you make a request by calling {{domxref("Window/fetch", "fetch()")}}, which is available as a global function in both {{domxref("Window", "window")}} and {{domxref("WorkerGlobalScope", "worker")}} contexts. You pass it a {{domxref("Request")}} object or a string containing the URL to fetch, along with an optional argument to configure the request. @@ -47,7 +47,7 @@ To make a request, call `fetch()`, passing in: 1. a definition of the resource to fetch. This can be any one of: - a string containing the URL - - an object, such an instance of {{domxref("URL")}}, which has a {{glossary("stringifier")}} that produces a string containing the URL + - an object, such as an instance of {{domxref("URL")}}, which has a {{glossary("stringifier")}} that produces a string containing the URL - a {{domxref("Request")}} instance 2. optionally, an object containing options to configure the request. @@ -55,12 +55,12 @@ In this section we'll look at some of the most commonly-used options. To read ab ### Setting the method -By default, `fetch()` makes a {{httpmethod("GET")}} request, but you can use the `method` option to use a different [request method](/en-US/docs/Web/HTTP/Methods): +By default, `fetch()` makes a {{httpmethod("GET")}} request, but you can use the `method` option to use a different [request method](/en-US/docs/Web/HTTP/Reference/Methods): ```js const response = await fetch("https://example.org/post", { method: "POST", - // ... + // … }); ``` @@ -76,7 +76,7 @@ To set a request body, pass it as the `body` option: const response = await fetch("https://example.org/post", { method: "POST", body: JSON.stringify({ username: "example" }), - // ... + // … }); ``` @@ -102,7 +102,7 @@ const response = await fetch("https://example.org/post", { }, // Automatically converted to "username=example&password=password" body: new URLSearchParams({ username: "example", password: "password" }), - // ... + // … }); ``` @@ -156,7 +156,7 @@ const response = await fetch("https://example.org/post", { "Content-Type": "application/json", }, body: JSON.stringify({ username: "example" }), - // ... + // … }); ``` @@ -170,7 +170,7 @@ const response = await fetch("https://example.org/post", { method: "POST", headers: myHeaders, body: JSON.stringify({ username: "example" }), - // ... + // … }); ``` @@ -192,10 +192,10 @@ const response = await fetch(`https://example.org/login?${params}`); Whether a request can be made cross-origin or not is determined by the value of the {{domxref("RequestInit", "", "mode")}} option. This may take one of three values: `cors`, `same-origin`, or `no-cors`. -- For fetch requests the default value of `mode` is `cors`, meaning that if the request is cross-origin then it will use the [Cross-Origin Resource Sharing (CORS)](/en-US/docs/Web/HTTP/CORS) mechanism. This means that: +- For fetch requests the default value of `mode` is `cors`, meaning that if the request is cross-origin then it will use the [Cross-Origin Resource Sharing (CORS)](/en-US/docs/Web/HTTP/Guides/CORS) mechanism. This means that: - - if the request is a [simple request](/en-US/docs/Web/HTTP/CORS#simple_requests), then the request will always be sent, but the server must respond with the correct {{httpheader("Access-Control-Allow-Origin")}} header or the browser will not share the response with the caller. - - if the request is not a simple request, then the browser will send a [preflighted request](/en-US/docs/Web/HTTP/CORS#preflighted_requests) to check that the server understands CORS and allows the request, and the real request will not be sent unless the server responds to the preflighted request with the appropriate CORS headers. + - if the request is a [simple request](/en-US/docs/Web/HTTP/Guides/CORS#simple_requests), then the request will always be sent, but the server must respond with the correct {{httpheader("Access-Control-Allow-Origin")}} header or the browser will not share the response with the caller. + - if the request is not a simple request, then the browser will send a [preflighted request](/en-US/docs/Web/HTTP/Guides/CORS#preflighted_requests) to check that the server understands CORS and allows the request, and the real request will not be sent unless the server responds to the preflighted request with the appropriate CORS headers. - Setting `mode` to `same-origin` disallows cross-origin requests completely. @@ -213,15 +213,15 @@ To control whether or not the browser sends credentials, as well as whether the - `same-origin` (the default): only send and include credentials for same-origin requests. - `include`: always include credentials, even cross-origin. -Note that if a cookie's [`SameSite`](/en-US/docs/Web/HTTP/Headers/Set-Cookie#samesitesamesite-value) attribute is set to `Strict` or `Lax`, then the cookie will not be sent cross-site, even if `credentials` is set to `include`. +Note that if a cookie's [`SameSite`](/en-US/docs/Web/HTTP/Reference/Headers/Set-Cookie#samesitesamesite-value) attribute is set to `Strict` or `Lax`, then the cookie will not be sent cross-site, even if `credentials` is set to `include`. Including credentials in cross-origin requests can make a site vulnerable to {{glossary("CSRF")}} attacks, so even if `credentials` is set to `include`, the server must also agree to their inclusion by including the {{httpheader("Access-Control-Allow-Credentials")}} header in its response. Additionally, in this situation the server must explicitly specify the client's origin in the {{httpheader("Access-Control-Allow-Origin")}} response header (that is, `*` is not allowed). This means that if `credentials` is set to `include` and the request is cross-origin, then: -- If the request is a [simple request](/en-US/docs/Web/HTTP/CORS#simple_requests), then the request will be sent with credentials, but the server must set the {{httpheader("Access-Control-Allow-Credentials")}} and {{httpheader("Access-Control-Allow-Origin")}} response headers, or the browser will return a network error to the caller. If the server does set the correct headers, then the response, including credentials, will be delivered to the caller. +- If the request is a [simple request](/en-US/docs/Web/HTTP/Guides/CORS#simple_requests), then the request will be sent with credentials, but the server must set the {{httpheader("Access-Control-Allow-Credentials")}} and {{httpheader("Access-Control-Allow-Origin")}} response headers, or the browser will return a network error to the caller. If the server does set the correct headers, then the response, including credentials, will be delivered to the caller. -- If the request is not a simple request, then the browser will send a [preflighted request](/en-US/docs/Web/HTTP/CORS#preflighted_requests) without credentials, and the server must set the {{httpheader("Access-Control-Allow-Credentials")}} and {{httpheader("Access-Control-Allow-Origin")}} response headers, or the browser will return a network error to the caller. If the server does set the correct headers, then the browser will follow up with the real request, including credentials, and will deliver the real response, including credentials, to the caller. +- If the request is not a simple request, then the browser will send a [preflighted request](/en-US/docs/Web/HTTP/Guides/CORS#preflighted_requests) without credentials, and the server must set the {{httpheader("Access-Control-Allow-Credentials")}} and {{httpheader("Access-Control-Allow-Origin")}} response headers, or the browser will return a network error to the caller. If the server does set the correct headers, then the browser will follow up with the real request, including credentials, and will deliver the real response, including credentials, to the caller. ### Creating a `Request` object @@ -338,7 +338,7 @@ As soon as the browser has received the response status and headers from the ser The promise returned by `fetch()` will reject on some errors, such as a network error or a bad scheme. However, if the server responds with an error like {{httpstatus("404")}}, then `fetch()` fulfills with a `Response`, so we have to check the status before we can read the response body. -The {{domxref("Response.status")}} property tells us the numerical status code, and the {{domxref("Response.ok")}} property returns `true` if the status is in the [200 range](/en-US/docs/Web/HTTP/Status#successful_responses). +The {{domxref("Response.status")}} property tells us the numerical status code, and the {{domxref("Response.ok")}} property returns `true` if the status is in the [200 range](/en-US/docs/Web/HTTP/Reference/Status#successful_responses). A common pattern is to check the value of `ok` and throw if it is `false`: @@ -350,7 +350,7 @@ async function getData() { if (!response.ok) { throw new Error(`Response status: ${response.status}`); } - // ... + // … } catch (error) { console.error(error.message); } @@ -364,7 +364,7 @@ Responses have a {{domxref("Response.type", "type")}} property that can be one o - `basic`: the request was a same-origin request. - `cors`: the request was a cross-origin CORS request. - `opaque`: the request was a cross-origin simple request made with the `no-cors` mode. -- `opaqueredirect`: the request set the `redirect` option to `manual`, and the server returned a [redirect status](/en-US/docs/Web/HTTP/Status#redirection_messages). +- `opaqueredirect`: the request set the `redirect` option to `manual`, and the server returned a [redirect status](/en-US/docs/Web/HTTP/Reference/Status#redirection_messages). The type determines the possible contents of the response, as follows: @@ -494,10 +494,9 @@ async function* makeTextFileLineIterator(fileURL) { const response = await fetch(fileURL); const reader = response.body.pipeThrough(new TextDecoderStream()).getReader(); - let { value: chunk, done: readerDone } = await reader.read(); - chunk = chunk || ""; + let { value: chunk = "", done: readerDone } = await reader.read(); - const newline = /\r?\n/gm; + const newline = /\r?\n/g; let startIndex = 0; while (true) { @@ -611,6 +610,6 @@ self.addEventListener("fetch", (event) => { - [Service Worker API](/en-US/docs/Web/API/Service_Worker_API) - [Streams API](/en-US/docs/Web/API/Streams_API) -- [CORS](/en-US/docs/Web/HTTP/CORS) +- [CORS](/en-US/docs/Web/HTTP/Guides/CORS) - [HTTP](/en-US/docs/Web/HTTP) - [Fetch examples on GitHub](https://github.com/mdn/dom-examples/tree/main/fetch) diff --git a/files/en-us/web/api/fetchevent/isreload/index.md b/files/en-us/web/api/fetchevent/isreload/index.md index 837d69c4994f115..f1b2a8abb5a4245 100644 --- a/files/en-us/web/api/fetchevent/isreload/index.md +++ b/files/en-us/web/api/fetchevent/isreload/index.md @@ -27,9 +27,9 @@ A boolean value. self.addEventListener("fetch", (event) => { event.respondWith(async () => { if (event.isReload) { - //Return something + // Return something } else { - //Return something else + // Return something else } })(); }); diff --git a/files/en-us/web/api/fetchlater_api/fetchlater_quotas/index.md b/files/en-us/web/api/fetchlater_api/fetchlater_quotas/index.md new file mode 100644 index 000000000000000..81cf4bc80e03088 --- /dev/null +++ b/files/en-us/web/api/fetchlater_api/fetchlater_quotas/index.md @@ -0,0 +1,225 @@ +--- +title: fetchLater() quotas +slug: Web/API/fetchLater_API/fetchLater_quotas +page-type: guide +status: + - experimental +browser-compat: + - http.headers.Permissions-Policy.deferred-fetch + - http.headers.Permissions-Policy.deferred-fetch-minimal +--- + +{{DefaultAPISidebar("fetchLater API")}}{{SeeCompatTable}} + +Deferred [`fetchLater()` API](/en-US/docs/Web/API/fetchLater_API) fetches are batched and sent once the tab is closed. At this point, there is no way for the user to abort them. To avoid situations where documents abuse this bandwidth to send unlimited amounts of data over the network the API sets quotas on how much data can be deferred to be sent later. + +These quotas can be managed through {{HTTPHeader("Permissions-Policy/deferred-fetch", "deferred-fetch")}} and {{HTTPHeader("Permissions-Policy/deferred-fetch-minimal", "deferred-fetch-minimal")}} [Permissions Policy](/en-US/docs/Web/HTTP/Guides/Permissions_Policy) directives. + +## Overview + +The overall quota for `fetchLater()` is 640KiB per document. By default, this is divided into a 512KiB top-level quota and a 128KiB shared quota: + +- The 512KiB top-level quota by default is for any `fetchLater()` requests made from the top-level document and direct subframes using that origin. +- The 128KiB shared quota by default is for any `fetchLater()` requests made in cross-origin subframes (for example, `<iframe>`, `<object>`, `<embed>`, and `<frame>` elements). + +`fetchLater()` requests can be made to any URL and are not restricted to the same origin as the document or the subframe, so it's important to differentiate between requests made in the top-level document content (whether to first-party or third-party origins) and those made in subframes. + +For example, if a top-level `a.com` document includes a `<script>` that makes a `fetchLater()` request to `analytics.example.com`, this request would be bound by the top-level 512KiB limit. Alternatively, if the top-level document embeds an `<iframe>` with a source of `analytics.example.com` that makes a `fetchLater()` request, that request would be bound by the 128KiB limit. + +## Quota limits by reporting origin and subframe + +Only 64KiB of the top-level 512KiB quota can be used concurrently for the same reporting origin (the request URL's origin). This prevents third-party libraries from reserving quota opportunistically before they have data to send. + +Each cross-origin subframe gets an 8KiB quota out of the shared 128KiB quota by default, allocated when the subframe is added to the DOM (whether `fetchLater()` will be used in that subframe or not). This means that, in general, only the first 16 cross-origin subframes added to a page can use `fetchLater()` as they will use up the 128KiB quota. + +## Increasing subframe quotas by sharing the top-level quota + +The top-level origin can give selected cross-origin subframes an increased quota of 64KiB, taking it out of the larger top-level 512KiB limit. It does this by listing those origins in the {{HTTPHeader("Permissions-Policy/deferred-fetch", "deferred-fetch")}} Permissions Policy directive. This is allocated when the subframe is added to the DOM, leaving less quota for the top-level document and direct same-origin subframes. Multiple same-origin subdomains can each get a 64KiB quota. + +## Restricting the shared quota + +The top-level origin can also restrict the 128KiB shared quota to named cross-origin subframes by listing those origins in the {{HTTPHeader("Permissions-Policy/deferred-fetch-minimal", "deferred-fetch-minimal")}} Permissions Policy. It can also revoke the entire 128KiB default subframe quota and instead keep the full 640KiB quota for itself and any named `deferred-fetch` cross-origins by setting the {{HTTPHeader("Permissions-Policy/deferred-fetch-minimal", "deferred-fetch-minimal")}} Permissions Policy to `()`. + +## Delegating quotes to subframes of subframes + +By default, subframes of subframes are not allocated a quota and so cannot use `fetchLater()`. Subframes allocated the increased 64KiB quota can delegate the full 64KiB quota to further subframes and allow them to use `fetchLater()` by setting their own `deferred-fetch` Permissions Policy. They can only delegate their full quota to further subframes, not parts of it, and cannot specify new quotas. Subframes using the minimal 8KiB quota cannot delegate quotas to subframes. To be delegated quota, sub-subframes must be included in both the top-level and the subframe `deferred-fetch` {{httpheader('Permissions-Policy')}} directives. + +## When quotas are exceeded + +When quotas are exceeded, a `QuotaExceededError` is thrown when the {{domxref('Window.fetchLater()','fetchLater()')}} method is called to initiate the deferred request. + +Permissions Policy checks are not discernable from quota checks. Calling `fetchLater()` will throw a `QuotaExceededError` both if the quota is actually exceeded and if the quota was restricted for that origin via a Permissions Policy. + +Callers of `fetchLater()` should be defensive and catch `QuotaExceededError` errors in almost all cases, especially if they embed third-party JavaScript. + +## Examples + +### Using up the minimal quota + +```http +Permissions-Policy: deferred-fetch=(self "https://b.com") +``` + +1. A `<iframe src="https://b.com/page">` receives 64KiB upon being added to the top-level document, from the top-level's 512KiB limit. +2. A `<iframe src="https://c.com/page">` is not listed and so receives 8KiB upon being added to the top-level document from the 128KiB shared limit. +3. 15 more cross-origin iframes would each receive 8KiB upon being added to the top-level document (similar to `c.com`). +4. The next cross-origin iframe would not be granted any quota. +5. If one of the cross-origin iframes is removed, its deferred fetches will be sent. +6. The next cross-origin iframe _would_ receive an 8KiB quota, as there is quota available again. + +### Revoke Restricting the minimal quota to named origins + +```http +Permissions-Policy: deferred-fetch-minimal=("https://b.com") +``` + +1. `<iframe src="https://b.com/page">` receives 8KiB upon being added to the top-level document. +2. `<iframe src="https://c.com/page">` receives no quota upon being added to the top-level document. +3. The top-level document and its same-origin descendants can use up to 512KiB. + +### Revoking the minimal quota altogether with top-level exceptions + +```http +Permissions-Policy: deferred-fetch=(self "https://b.com") +Permissions-Policy: deferred-fetch-minimal=() +``` + +1. `<iframe src="https://b.com/page">` receives 64KiB upon being added to the top-level document. +2. `<iframe src="https://c.com/page">` receives no quota upon being added to the top-level document. +3. The top-level document and its same-origin descendants can use up to the full 640KiB but that is reduced to 574KiB if a `b.com` subframe is created (or even less if multiple `b.com` subframes are created, each of which will be allocated a 64KiB quota). + +### Revoking the minimal quota altogether with no exceptions + +```http +Permissions-Policy: deferred-fetch-minimal=() +``` + +1. The top-level document and its same-origin descendants can use up the full 640KiB. +2. Subframes are not allocated any quota and cannot use `fetchLater()`. + +### Same-origin subframes share quota with the top-level and can delegate to subframes + +Assuming a top-level document on `a.com`, which embeds a subframe of `a.com`, which embeds a subframe of `b.com`, and no explicit Permission Policies. + +1. The top-level document of `a.com` has the default 512KiB quota. +2. `<iframe src="https://a.com/embed">` shares the 512KiB quota upon being added to the top-level document. +3. `<iframe src="https://b.com/embed">` receives an 8KiB quota upon being added to the top-level document. + +### Same-origin subframes can not share quota with the top-level when separated by a cross-origin subframe + +Assuming a top-level document on `a.com`, which embeds a `<iframe src="https://b.com/">`, which embeds a subframe of `<iframe src="https://a.com/embed">`, and no explicit Permission Policies. + +1. The top-level document of `a.com` has the default 512KiB quota. +2. `<iframe src="https://b.com/">` shares the 8KiB quota. +3. `<iframe src="https://a.com/embed">` receives no quota; even though this is same-origin with the top origin, it is separated by a cross-origin. + +### Secondary subframes of subframes do not get quota by default + +Assuming a top-level document on `a.com`, which embeds a `<iframe src="https://b.com/">`, which embeds a `<iframe src="https://c.com/">`, and no explicit Permission Policies. + +1. The top-level frame of `a.com` has the default 512KiB quota. +2. `<iframe src="https://b.com/">` receives 8KiB of the default shared quota. +3. `<iframe src="https://c.com/">` receives no quota. + +### Granting the full quota to a further subframe + +Assuming a top-level document on `a.com`, which embeds a `<iframe src="https://b.com/">`, which embeds a `<iframe src="https://c.com/">`. + +Assuming that `a.com` has the following Permissions Policy: + +```http +Permissions-Policy: deferred-fetch=("https://c.com" "https://c.com") +``` + +And, assuming that `b.com` has the following Permissions Policy: + +```http +Permissions-Policy: deferred-fetch=("https://c.com") +``` + +1. The top-level frame of `a.com` has the default 512KiB quota. +2. `<iframe src="https://b.com/">` receives 64KiB of the default quota. +3. `<iframe src="https://b.com/">` delegates its full quota of 8KiB to `c.com`. `b.com` cannot use `fetchLater()`. +4. `<iframe src="https://c.com/">` receives 8KiB of quota. + +### Redirects do not transfer quota + +Assuming a top-level document on `a.com`, which embeds a `<iframe src="https://b.com/">`, which redirects to `c.com`, and no explicit top-level Permission Policies. + +1. The top-level frame of `a.com` has the default 512KiB quota. +2. `<iframe src="https://b.com/">` receives 8KiB of the default shared quota. +3. The 8KiB is not transferred to `c.com` when `<iframe src="https://b.com/">` redirects to there, but the 8KiB is not released. + +### Sandboxed same-origin iframes are effectively separate origins + +As an example, if the following `<iframe>` is embedded on `https://www.example.com`: + +```html +<iframe src="https://www.example.com/iframe" sandbox="allow-scripts"></iframe> +``` + +This would not be considered "same-origin", despite being hosted on the same origin as the top-level document, as the `<iframe>` is in a sandboxed environment. Therefore, by default, it should be allocated an 8KiB quota from the total shared 128KiB quota. + +### Disallowing `fetchLater()` from iframes + +You can use the `<iframe>` [`allow`](/en-US/docs/Web/HTML/Reference/Elements/iframe#allow) attribute to prevent `fetchLater()` quota from being allocated to the `<iframe>`: + +```html +<iframe + src="https://www.example.com/iframe" + allow="deferred-fetch;deferred-fetch-minimal;"></iframe> +``` + +The `allow="deferred-fetch"` directive is needed to prevent same-origin iframes from using up the 512KiB quota, and the `allow="deferred-fetch-minimal"` directive is needed to prevent cross-origin iframes from using up the 128KiB quota. Including both directives will prevent both quotas from being used, regardless of the `src` value. + +### Examples which throw a `QuotaExceededError` + +```js +// Maximum of 64KiB per origin +fetchLater(a_72_kb_url); + +// Maximum of 64KiB per origin including headers +fetchLater("https://origin.example.com", { headers: headers_exceeding_64kb }); + +// Maximum of 64KiB per origin including body and headers +fetchLater(a_32_kib_url, { headers: headers_exceeding_32kib }); + +// Maximum of 64KiB per origin including body +fetchLater("https://origin.example.com", { + method: "POST", + body: body_exceeding_64_kib, +}); + +// Maximum of 64KiB per origin including body and automatically added headers +fetchLater(a_62_kib_url /* with a 3kb referrer */); +``` + +### Examples which eventually throw a `QuotaExceededError` + +In the following sequence, contained in the top-level document, the first two requests would succeed, but the third would throw. That's because, even though the overall 640KiB quota was not exceeded, the third request exceeds the reporting-origin quota for `https://a.example.com` and would throw. + +```js +fetchLater("https://a.example.com", { method: "POST", body: a_40kb_body }); +fetchLater("https://b.example.com", { method: "POST", body: a_40kb_body }); +fetchLater("https://a.example.com", { method: "POST", body: a_40kb_body }); +``` + +### Redirects of subframes back to the top-level origin allow use of the top-level quota + +Assuming a top-level document at `a.com`, which embeds `<iframe src="https://b.com/">`, which redirects to `a.com`, and no explicit top-level Permission Policies: + +1. The top-level frame of `a.com` has the default 512KiB quota. +2. `<iframe src="https://b.com/">` receives 8KiB of the default shared quota of 128KiB. +3. The 8KiB is not transferred to `a.com` when `<iframe src="https://b.com/">` redirects there, but it can share the full top-level quota again, and the previously-allocated 8KiB quota is released. + +## Specifications + +{{Specifications}} + +## Browser compatibility + +{{Compat}} + +## See also + +- [`fetchLater()` API](/en-US/docs/Web/API/fetchLater_API) diff --git a/files/en-us/web/api/fetchlater_api/index.md b/files/en-us/web/api/fetchlater_api/index.md new file mode 100644 index 000000000000000..3a421ff63a309df --- /dev/null +++ b/files/en-us/web/api/fetchlater_api/index.md @@ -0,0 +1,75 @@ +--- +title: fetchLater() API +slug: Web/API/fetchLater_API +page-type: web-api-overview +status: + - experimental +browser-compat: api.Window.fetchLater +--- + +{{DefaultAPISidebar("fetchLater API")}}{{SeeCompatTable}} + +The **`fetchLater()` API** provides an interface to request a deferred fetch that can be sent after a specified period of time, or when the page is closed or navigated away from. + +## Concepts and usage + +Developers often need to send (or beacon) data back to the server, particularly at the end of a user's visit to a page — for example, for analytics services. There are several ways to do this: from adding 1 pixel {{HTMLElement("img")}} elements to the page, to {{domxref("XMLHttpRequest")}}, to the dedicated {{domxref("Beacon API", "Beacon API", "", "nocode")}}, and the {{domxref("Fetch API", "Fetch API", "", "nocode")}} itself. + +The issue is that all of these methods suffer from reliability problems for end-of-visit beaconing. While the Beacon API and the {{domxref("Request.keepalive", "keepalive")}} property of the Fetch API will send data, even if the document is destroyed (to the best efforts that can be made in this scenario), this only solves part of the problem. + +The other — more difficult — part to solve concerns deciding _when_ to send the data, since there is not an ideal time in a page's lifecycle to make the JavaScript call to send out the beacon: + +- The {{domxref("Window.unload_event", "unload")}} and {{domxref("Window.beforeunload_event", "beforeunload")}} events are unreliable, and outright ignored by several major browsers. +- The {{domxref("Window.pagehide_event", "pagehide")}} and {{domxref("document.visibilitychange_event", "visibilitychange")}} events are more reliable, but still have issues on mobile platforms. + +This means developers looking to reliably send out data via a beacon need to do so more frequently than is ideal. For example, they may send a beacon on each change, even if the final value for the page has not yet been reached. This has costs in network usage, server processing, and merging or discarding outdated beacons on the server. + +Alternatively, developers can choose to accept some level of missing data — either by: + +- Beaconing after a designated cut-off time and not collecting later data. +- Beaconing at the end of the page lifecycle but accepting that sometimes this will not be reliable. + +The `fetchLater()` API extends the {{domxref("Fetch API", "Fetch API", "", "nocode")}} to allow setting fetch requests up in advance. These deferred fetches can be updated before they have been sent, allowing the payload to reflect the latest data to be beaconed. + +The browser then sends the beacon when the tab is closed or navigated away from, or after a set time if specified. This avoids sending multiple beacons but still ensures a reliable beacon within reasonable expectations (i.e., excluding when the browser process shuts down unexpectedly during a crash). + +Deferred fetches can also be aborted using an {{domxref("AbortController")}} if they are no longer required, avoiding further unnecessary costs. + +### Quotas + +Deferred fetches are batched and sent once the tab is closed; at this point, there is no way for the user to abort them. To avoid situations where documents abuse this bandwidth to send unlimited amounts of data over the network, the overall quota for a top-level document is capped at 640KiB. + +Callers of `fetchLater()` should be defensive and catch `QuotaExceededError` errors in almost all cases, especially if they embed third-party JavaScript. + +Since this cap makes deferred fetch bandwidth a scarce resource, which needs to be shared between multiple reporting origins (for example, several RUM libraries) and subframes from multiple origins, the platform provides a reasonable default division of this quota. In addition, it provides {{HTTPHeader("Permissions-Policy/deferred-fetch", "deferred-fetch")}} and {{HTTPHeader("Permissions-Policy/deferred-fetch-minimal", "deferred-fetch-minimal")}} [Permissions Policy](/en-US/docs/Web/HTTP/Guides/Permissions_Policy) directives to allow dividing it differently when desired. + +See [fetchLater() quotas](/en-US/docs/Web/API/fetchLater_API/fetchLater_quotas) for more details and examples. + +## Interfaces + +- {{domxref("Window.fetchLater()")}} + - : Used to queue a resource for sending at a later point. +- {{domxref("DeferredRequestInit")}} + - : Represents the set of options that can be used to configure a deferred fetch request. +- {{domxref("FetchLaterResult")}} + - : Represents the result of requesting a deferred fetch. + +## HTTP headers + +- {{HTTPHeader("Permissions-Policy/deferred-fetch", "deferred-fetch")}} + - : Controls [top-level quota](/en-US/docs/Web/API/fetchLater_API/fetchLater_quotas) for the `fetchLater()` API. +- {{HTTPHeader("Permissions-Policy/deferred-fetch-minimal", "deferred-fetch-minimal")}} + - : Controls [shared cross-origin subframe quota](/en-US/docs/Web/API/fetchLater_API/fetchLater_quotas) for the `fetchLater()` API. + +## Specifications + +{{Specifications}} + +## Browser compatibility + +{{Compat}} + +## See also + +- [`fetchLater()` quotas](/en-US/docs/Web/API/fetchLater_API/fetchLater_quotas) +- [Fetch API](/en-US/docs/Web/API/Fetch_API) diff --git a/files/en-us/web/api/fetchlaterresult/activated/index.md b/files/en-us/web/api/fetchlaterresult/activated/index.md new file mode 100644 index 000000000000000..824724c2ef29c0e --- /dev/null +++ b/files/en-us/web/api/fetchlaterresult/activated/index.md @@ -0,0 +1,41 @@ +--- +title: "FetchLaterResult: activated property" +short-title: activated +slug: Web/API/FetchLaterResult/activated +page-type: web-api-instance-property +status: + - experimental +browser-compat: api.FetchLaterResult.activated +--- + +{{APIRef("fetchLater API")}}{{SeeCompatTable}} + +The **`activated`** read-only property of the {{domxref("FetchLaterResult")}} interface returns a boolean specifying whether the deferred fetch has been sent. + +## Value + +A {{jsxref('Boolean')}}. + +## Examples + +### Defer a `POST` request for around one minute and create a function to check if sent + +```js +const result = fetchLater("https://report.example.com", { + method: "POST", + body: JSON.stringify(myReport), + activateAfter: 60000 /* 1 minute */, +}); + +function check_if_fetched() { + return result.activated; +} +``` + +## Specifications + +{{Specifications}} + +## Browser compatibility + +{{Compat}} diff --git a/files/en-us/web/api/fetchlaterresult/index.md b/files/en-us/web/api/fetchlaterresult/index.md new file mode 100644 index 000000000000000..581b08a3f0bb054 --- /dev/null +++ b/files/en-us/web/api/fetchlaterresult/index.md @@ -0,0 +1,50 @@ +--- +title: FetchLaterResult +slug: Web/API/FetchLaterResult +page-type: web-api-interface +status: + - experimental +browser-compat: api.FetchLaterResult +--- + +{{APIRef("fetchLater API")}}{{SeeCompatTable}} + +The **`FetchLaterResult`** interface of the [`fetchLater()` API](/en-US/docs/Web/API/fetchLater_API) is returned by the {{domxref("Window.FetchLater()")}} method after a deferred fetch has been created. + +It contains a single `activated` property that indicates whether the deferred request has been sent out or not. + +After a successful sending, the whole response is ignored — including body and headers — so the response of the deferred fetch is never returned to the `FetchLaterResult` interface. + +## Instance properties + +- {{domxref('FetchLaterResult.activated')}} {{ReadOnlyInline}} {{Experimental_Inline}} + - : A read-only boolean field that indicates whether the deferred request has been sent out. This is initially set to `false` and will then be updated by the browser once the deferred fetch has been sent. + +## Examples + +### Defer a `POST` request for around one minute and create a function to check if sent + +```js +const result = fetchLater("https://report.example.com", { + method: "POST", + body: JSON.stringify(myReport), + activateAfter: 60000 /* 1 minute */, +}); + +function check_if_fetched() { + return result.activated; +} +``` + +## Specifications + +{{Specifications}} + +## Browser compatibility + +{{Compat}} + +## See also + +- [`fetchLater()` API](/en-US/docs/Web/API/fetchLater_API) +- [Fetch API](/en-US/docs/Web/API/Fetch_API) diff --git a/files/en-us/web/api/file/webkitrelativepath/index.md b/files/en-us/web/api/file/webkitrelativepath/index.md index 44ecfe7076aac0a..a0644eaff83a46c 100644 --- a/files/en-us/web/api/file/webkitrelativepath/index.md +++ b/files/en-us/web/api/file/webkitrelativepath/index.md @@ -11,7 +11,7 @@ browser-compat: api.File.webkitRelativePath The **`webkitRelativePath`** read-only property of the {{domxref("File")}} interface contains a string which specifies the file's path relative to the directory selected by the user in an {{HTMLElement("input")}} element with its -[`webkitdirectory`](/en-US/docs/Web/HTML/Element/input#webkitdirectory) attribute set. +[`webkitdirectory`](/en-US/docs/Web/HTML/Reference/Elements/input#webkitdirectory) attribute set. ## Value diff --git a/files/en-us/web/api/file_and_directory_entries_api/index.md b/files/en-us/web/api/file_and_directory_entries_api/index.md index f80ed457a9b7449..9b8c4d3d72b3835 100644 --- a/files/en-us/web/api/file_and_directory_entries_api/index.md +++ b/files/en-us/web/api/file_and_directory_entries_api/index.md @@ -46,7 +46,7 @@ The File and Directory Entries API includes the following interfaces: - {{domxref("File.webkitRelativePath")}} - : Returns the path the URL of the `File` is relative to. - {{domxref("HTMLInputElement.webkitdirectory")}} - - : A boolean that represents the [`webkitdirectory`](/en-US/docs/Web/HTML/Element/input#webkitdirectory) attribute. If `true`, the file-system-picker interface only accepts directories instead of files. + - : A boolean that represents the [`webkitdirectory`](/en-US/docs/Web/HTML/Reference/Elements/input#webkitdirectory) attribute. If `true`, the file-system-picker interface only accepts directories instead of files. - {{domxref("HTMLInputElement.webkitEntries")}} - : Describes the currently selected files or directories. diff --git a/files/en-us/web/api/file_api/index.md b/files/en-us/web/api/file_api/index.md index fe47ba6aa9503f6..3291ebfbcbd72e7 100644 --- a/files/en-us/web/api/file_api/index.md +++ b/files/en-us/web/api/file_api/index.md @@ -11,7 +11,7 @@ spec-urls: https://w3c.github.io/FileAPI/ The File API enables web applications to access files and their contents. -Web applications can access files when the user makes them available, either using a [file `<input>` element](/en-US/docs/Web/HTML/Element/input/file) or [via drag and drop](/en-US/docs/Web/API/DataTransfer/files). +Web applications can access files when the user makes them available, either using a [file `<input>` element](/en-US/docs/Web/HTML/Reference/Elements/input/file) or [via drag and drop](/en-US/docs/Web/API/DataTransfer/files). Sets of files made available in this way are represented as {{domxref("FileList")}} objects, which enable a web application to retrieve individual {{domxref("File")}} objects. In turn {{domxref("File")}} objects provide access to metadata such as the file's name, size, type, and last modified date. @@ -51,7 +51,7 @@ The File System API provides a virtual file system for web applications, so that ### Reading a file -In this example, we provide a [file `<input>` element](/en-US/docs/Web/HTML/Element/input/file), and when the user selects a file, we read the contents of the first file selected as text, and display the result in a {{HTMLElement("div")}}. +In this example, we provide a [file `<input>` element](/en-US/docs/Web/HTML/Reference/Elements/input/file), and when the user selects a file, we read the contents of the first file selected as text, and display the result in a {{HTMLElement("div")}}. #### HTML @@ -95,6 +95,6 @@ fileInput.addEventListener("change", async () => { ## See also -- [`<input type="file">`](/en-US/docs/Web/HTML/Element/input/file): the file input element +- [`<input type="file">`](/en-US/docs/Web/HTML/Reference/Elements/input/file): the file input element - {{domxref("Blob.text()")}} - The {{domxref("DataTransfer")}} interface diff --git a/files/en-us/web/api/file_api/using_files_from_web_applications/index.md b/files/en-us/web/api/file_api/using_files_from_web_applications/index.md index 1b59d6744fbac5a..e1061a6a325ecf3 100644 --- a/files/en-us/web/api/file_api/using_files_from_web_applications/index.md +++ b/files/en-us/web/api/file_api/using_files_from_web_applications/index.md @@ -251,9 +251,7 @@ Let's say you're developing the next great photo-sharing website and want to use ```js function handleFiles(files) { - for (let i = 0; i < files.length; i++) { - const file = files[i]; - + for (const file of files) { if (!file.type.startsWith("image/")) { continue; } @@ -344,19 +342,16 @@ function handleFiles() { } else { const list = document.createElement("ul"); fileList.appendChild(list); - for (let i = 0; i < this.files.length; i++) { + for (const file of this.files) { const li = document.createElement("li"); list.appendChild(li); const img = document.createElement("img"); - img.src = URL.createObjectURL(this.files[i]); + img.src = URL.createObjectURL(file); img.height = 60; - img.onload = () => { - URL.revokeObjectURL(img.src); - }; li.appendChild(img); const info = document.createElement("span"); - info.textContent = `${this.files[i].name}: ${this.files[i].size} bytes`; + info.textContent = `${file.name}: ${file.size} bytes`; li.appendChild(info); } } @@ -365,7 +360,7 @@ function handleFiles() { This starts by fetching the URL of the {{HTMLElement("div")}} with the ID `fileList`. This is the block into which we'll insert our file list, including thumbnails. -If the {{DOMxRef("FileList")}} object passed to `handleFiles()` is `null`, we set the inner HTML of the block to display "No files selected!". Otherwise, we start building our file list, as follows: +If the {{DOMxRef("FileList")}} object passed to `handleFiles()` is empty, we set the inner HTML of the block to display "No files selected!". Otherwise, we start building our file list, as follows: 1. A new unordered list ({{HTMLElement("ul")}}) element is created. 2. The new list element is inserted into the {{HTMLElement("div")}} block by calling its {{DOMxRef("Node.appendChild()")}} method. @@ -375,13 +370,14 @@ If the {{DOMxRef("FileList")}} object passed to `handleFiles()` is `null`, we se 2. Create a new image ({{HTMLElement("img")}}) element. 3. Set the image's source to a new object URL representing the file, using {{DOMxref("URL.createObjectURL_static", "URL.createObjectURL()")}} to create the blob URL. 4. Set the image's height to 60 pixels. - 5. Set up the image's load event handler to release the object URL since it's no longer needed once the image has been loaded. This is done by calling the {{DOMxref("URL.revokeObjectURL_static", "URL.revokeObjectURL()")}} method and passing in the object URL string as specified by `img.src`. - 6. Append the new list item to the list. + 5. Append the new list item to the list. Here is a live demo of the code above: {{EmbedLiveSample('Example_Using_object_URLs_to_display_images', '100%', '300px')}} +Note that we don't immediately revoke the object URL after the image has loaded, because doing so would make the image unusable for user interactions (such as right-clicking to save the image or opening it in a new tab). For long-lived applications, you should revoke object URLs when they're no longer needed (such as when the image is removed from the DOM) to free up memory by calling the {{DOMxref("URL.revokeObjectURL_static", "URL.revokeObjectURL()")}} method and passing in the object URL string. + ## Example: Uploading a user-selected file This example shows how to let the user upload files (such as the images selected using the previous example) to a server. @@ -399,8 +395,8 @@ Continuing with the code that built the thumbnails in the previous example, reca function sendFiles() { const imgs = document.querySelectorAll(".obj"); - for (let i = 0; i < imgs.length; i++) { - new FileUpload(imgs[i], imgs[i].file); + for (const img of imgs) { + new FileUpload(img, img.file); } } ``` @@ -418,13 +414,12 @@ function FileUpload(img, file) { const xhr = new XMLHttpRequest(); this.xhr = xhr; - const self = this; this.xhr.upload.addEventListener( "progress", (e) => { if (e.lengthComputable) { const percentage = Math.round((e.loaded * 100) / e.total); - self.ctrl.update(percentage); + this.ctrl.update(percentage); } }, false, @@ -433,8 +428,8 @@ function FileUpload(img, file) { xhr.upload.addEventListener( "load", (e) => { - self.ctrl.update(100); - const canvas = self.ctrl.ctx.canvas; + this.ctrl.update(100); + const canvas = this.ctrl.ctx.canvas; canvas.parentNode.removeChild(canvas); }, false, @@ -493,57 +488,61 @@ This example, which uses PHP on the server side and JavaScript on the client sid ```php <?php -if (isset($_FILES['myFile'])) { - // Example: - move_uploaded_file($_FILES['myFile']['tmp_name'], "uploads/" . $_FILES['myFile']['name']); - exit; +if (isset($_FILES["myFile"])) { + // Example: + move_uploaded_file($_FILES["myFile"]["tmp_name"], "uploads/" . $_FILES["myFile"]["name"]); + exit; } ?><!doctype html> <html lang="en-US"> -<head> - <meta charset="UTF-8"> - <title>dnd binary upload</title> - <script type="application/javascript"> - function sendFile(file) { - const uri = "/index.php"; - const xhr = new XMLHttpRequest(); - const fd = new FormData(); - - xhr.open("POST", uri, true); - xhr.onreadystatechange = () => { - if (xhr.readyState === 4 && xhr.status === 200) { - alert(xhr.responseText); // handle response. - } - }; - fd.append('myFile', file); - // Initiate a multipart/form-data upload - xhr.send(fd); - } - - window.onload = () => { - const dropzone = document.getElementById("dropzone"); - dropzone.ondragover = dropzone.ondragenter = (event) => { - event.stopPropagation(); - event.preventDefault(); - } - - dropzone.ondrop = (event) => { - event.stopPropagation(); - event.preventDefault(); - - const filesArray = event.dataTransfer.files; - for (let i=0; i<filesArray.length; i++) { - sendFile(filesArray[i]); - } - } - } + <head> + <meta charset="UTF-8" /> + <title>dnd binary upload</title> + <script> + function sendFile(file) { + const uri = "/index.php"; + const xhr = new XMLHttpRequest(); + const fd = new FormData(); + + xhr.open("POST", uri, true); + xhr.onreadystatechange = () => { + if (xhr.readyState === 4 && xhr.status === 200) { + alert(xhr.responseText); // handle response. + } + }; + fd.append("myFile", file); + // Initiate a multipart/form-data upload + xhr.send(fd); + } + + window.onload = () => { + const dropzone = document.getElementById("dropzone"); + dropzone.ondragover = dropzone.ondragenter = (event) => { + event.stopPropagation(); + event.preventDefault(); + }; + + dropzone.ondrop = (event) => { + event.stopPropagation(); + event.preventDefault(); + + const filesArray = event.dataTransfer.files; + for (let i = 0; i < filesArray.length; i++) { + sendFile(filesArray[i]); + } + }; + }; </script> -</head> -<body> + </head> + <body> <div> - <div id="dropzone" style="margin:30px; width:500px; height:300px; border:1px dotted grey;">Drag & drop your file here</div> + <div + id="dropzone" + style="margin:30px; width:500px; height:300px; border:1px dotted grey;"> + Drag & drop your file here + </div> </div> -</body> + </body> </html> ``` @@ -560,10 +559,12 @@ In Firefox, to have the PDF appear embedded in the iframe (rather than proposed And here is the change of the `src` attribute: ```js -const obj_url = URL.createObjectURL(blob); +const objURL = URL.createObjectURL(blob); const iframe = document.getElementById("viewer"); -iframe.setAttribute("src", obj_url); -URL.revokeObjectURL(obj_url); +iframe.setAttribute("src", objURL); + +// Later: +URL.revokeObjectURL(objURL); ``` ## Example: Using object URLs with other file types @@ -572,10 +573,12 @@ You can manipulate files of other formats the same way. Here is how to preview u ```js const video = document.getElementById("video"); -const obj_url = URL.createObjectURL(blob); -video.src = obj_url; +const objURL = URL.createObjectURL(blob); +video.src = objURL; video.play(); -URL.revokeObjectURL(obj_url); + +// Later: +URL.revokeObjectURL(objURL); ``` ## See also diff --git a/files/en-us/web/api/file_system_api/index.md b/files/en-us/web/api/file_system_api/index.md index 6bf4addb1167370..b7b7100f43d8ab2 100644 --- a/files/en-us/web/api/file_system_api/index.md +++ b/files/en-us/web/api/file_system_api/index.md @@ -103,7 +103,7 @@ Read our [Origin private file system](/en-US/docs/Web/API/File_System_API/Origin - {{domxref("Window.showSaveFilePicker()")}} - : Shows a file picker that allows a user to save a file. - {{domxref("DataTransferItem.getAsFileSystemHandle()")}} - - : Returns a {{domxref('FileSystemFileHandle')}} if the dragged item is a file, or a {{domxref('FileSystemDirectoryHandle')}} if the dragged item is a directory. + - : Returns a {{jsxref('Promise')}} that fulfills with a {{domxref('FileSystemFileHandle')}} if the dragged item is a file, or fulfills with a {{domxref('FileSystemDirectoryHandle')}} if the dragged item is a directory. - {{domxref("StorageManager.getDirectory()")}} - : Used to obtain a reference to a {{domxref("FileSystemDirectoryHandle")}} object allowing access to a directory and its contents, stored in the [origin private file system](/en-US/docs/Web/API/File_System_API/Origin_private_file_system). Returns a {{jsxref('Promise')}} that fulfills with a {{domxref("FileSystemDirectoryHandle")}} object. diff --git a/files/en-us/web/api/file_system_api/origin_private_file_system/index.md b/files/en-us/web/api/file_system_api/origin_private_file_system/index.md index 598b4caa08e6824..120a48e9ae68bdf 100644 --- a/files/en-us/web/api/file_system_api/origin_private_file_system/index.md +++ b/files/en-us/web/api/file_system_api/origin_private_file_system/index.md @@ -19,7 +19,7 @@ The [File System Access API](https://wicg.github.io/file-system-access/), which This works, but it has some restrictions. These changes are being made to the user-visible file system, so there are a lot of security checks in place (for example, [safe browsing](https://developers.google.com/safe-browsing) in Chrome) to guard against malicious content being written to that file system. These writes are not in-place, and instead use a temporary file. The original is not modified unless it passes all the security checks. -As a result, these operations are fairly slow. It is not so noticeable when you are making small text updates, but the performance suffers when making more significant, large-scale file updates such as [SQLite](https://www.sqlite.org/wasm) database modifications. +As a result, these operations are fairly slow. It is not so noticeable when you are making small text updates, but the performance suffers when making more significant, large-scale file updates such as [SQLite](https://sqlite.org/wasm) database modifications. ## How does the OPFS solve such problems? diff --git a/files/en-us/web/api/fileentrysync/index.md b/files/en-us/web/api/fileentrysync/index.md index 3e2b502f77ac41b..09211ff7a9e52fd 100644 --- a/files/en-us/web/api/fileentrysync/index.md +++ b/files/en-us/web/api/fileentrysync/index.md @@ -26,14 +26,12 @@ To write content to file, create a FileWriter object by calling [`createWriter() <tbody> <tr> <td> - <code>FileWriterSync - <a href="#createreader" title="#createWriter">createWriter</a> ()); - </code> + <code>FileWriterSync <a href="#createwriter">createWriter</a> ();</code> </td> </tr> <tr> <td> - <code>File <a href="#file">file</a> ());</code> + <code>File <a href="#file">file</a> ();</code> </td> </tr> </tbody> diff --git a/files/en-us/web/api/filereader/abort_event/index.md b/files/en-us/web/api/filereader/abort_event/index.md index 26943f4b386e320..954275fe1ad48aa 100644 --- a/files/en-us/web/api/filereader/abort_event/index.md +++ b/files/en-us/web/api/filereader/abort_event/index.md @@ -16,10 +16,10 @@ This event is not cancelable and does not bubble. Use the event name in methods like {{domxref("EventTarget.addEventListener", "addEventListener()")}}, or set an event handler property. -```js -addEventListener("abort", (event) => {}); +```js-nolint +addEventListener("abort", (event) => { }) -onabort = (event) => {}; +onabort = (event) => { } ``` ## Event type diff --git a/files/en-us/web/api/filereader/error_event/index.md b/files/en-us/web/api/filereader/error_event/index.md index 6febd11bf0ca6e2..578792ff5ca718b 100644 --- a/files/en-us/web/api/filereader/error_event/index.md +++ b/files/en-us/web/api/filereader/error_event/index.md @@ -16,10 +16,10 @@ This event is not cancelable and does not bubble. Use the event name in methods like {{domxref("EventTarget.addEventListener", "addEventListener()")}}, or set an event handler property. -```js -addEventListener("error", (event) => {}); +```js-nolint +addEventListener("error", (event) => { }) -onerror = (event) => {}; +onerror = (event) => { } ``` ## Event type diff --git a/files/en-us/web/api/filereader/index.md b/files/en-us/web/api/filereader/index.md index 12d45bf963843db..c3286e567ddfd85 100644 --- a/files/en-us/web/api/filereader/index.md +++ b/files/en-us/web/api/filereader/index.md @@ -9,7 +9,7 @@ browser-compat: api.FileReader The **`FileReader`** interface lets web applications asynchronously read the contents of files (or raw data buffers) stored on the user's computer, using {{domxref("File")}} or {{domxref("Blob")}} objects to specify the file or data to read. -File objects may be obtained from a {{domxref("FileList")}} object returned as a result of a user selecting files using the `<input type="file">` element, or from a drag and drop operation's {{domxref("DataTransfer")}} object. `FileReader` can only access the contents of files that the user has explicitly selected; it cannot be used to read a file by pathname from the user's file system. To read files on the client's file system by pathname, use the [File System Access API](/en-US/docs/Web/API/File_System_API). To read server-side files, use {{domxref("Window/fetch", "fetch()")}}, with [CORS](/en-US/docs/Web/HTTP/CORS) permission if reading cross-origin. +File objects may be obtained from a {{domxref("FileList")}} object returned as a result of a user selecting files using the `<input type="file">` element, or from a drag and drop operation's {{domxref("DataTransfer")}} object. `FileReader` can only access the contents of files that the user has explicitly selected; it cannot be used to read a file by pathname from the user's file system. To read files on the client's file system by pathname, use the [File System Access API](/en-US/docs/Web/API/File_System_API). To read server-side files, use {{domxref("Window/fetch", "fetch()")}}, with [CORS](/en-US/docs/Web/HTTP/Guides/CORS) permission if reading cross-origin. {{InheritanceDiagram}} diff --git a/files/en-us/web/api/filereader/load_event/index.md b/files/en-us/web/api/filereader/load_event/index.md index b364f851dd567e6..a864fb588256142 100644 --- a/files/en-us/web/api/filereader/load_event/index.md +++ b/files/en-us/web/api/filereader/load_event/index.md @@ -16,10 +16,10 @@ This event is not cancelable and does not bubble. Use the event name in methods like {{domxref("EventTarget.addEventListener", "addEventListener()")}}, or set an event handler property. -```js -addEventListener("load", (event) => {}); +```js-nolint +addEventListener("load", (event) => { }) -onload = (event) => {}; +onload = (event) => { } ``` ## Event type diff --git a/files/en-us/web/api/filereader/loadend_event/index.md b/files/en-us/web/api/filereader/loadend_event/index.md index 77749508c80ddc4..c4fe26efe5982a9 100644 --- a/files/en-us/web/api/filereader/loadend_event/index.md +++ b/files/en-us/web/api/filereader/loadend_event/index.md @@ -16,10 +16,10 @@ This event is not cancelable and does not bubble. Use the event name in methods like {{domxref("EventTarget.addEventListener", "addEventListener()")}}, or set an event handler property. -```js -addEventListener("loadend", (event) => {}); +```js-nolint +addEventListener("loadend", (event) => { }) -onloadend = (event) => {}; +onloadend = (event) => { } ``` ## Event type diff --git a/files/en-us/web/api/filereader/loadstart_event/index.md b/files/en-us/web/api/filereader/loadstart_event/index.md index 2a1b33fe22b330b..0ae43bacefcaa2c 100644 --- a/files/en-us/web/api/filereader/loadstart_event/index.md +++ b/files/en-us/web/api/filereader/loadstart_event/index.md @@ -16,10 +16,10 @@ This event is not cancelable and does not bubble. Use the event name in methods like {{domxref("EventTarget.addEventListener", "addEventListener()")}}, or set an event handler property. -```js -addEventListener("loadstart", (event) => {}); +```js-nolint +addEventListener("loadstart", (event) => { }) -onloadstart = (event) => {}; +onloadstart = (event) => { } ``` ## Event type diff --git a/files/en-us/web/api/filereader/progress_event/index.md b/files/en-us/web/api/filereader/progress_event/index.md index 329be43867d6613..a2091d8808e9328 100644 --- a/files/en-us/web/api/filereader/progress_event/index.md +++ b/files/en-us/web/api/filereader/progress_event/index.md @@ -16,10 +16,10 @@ This event is not cancelable and does not bubble. Use the event name in methods like {{domxref("EventTarget.addEventListener", "addEventListener()")}}, or set an event handler property. -```js -addEventListener("progress", (event) => {}); +```js-nolint +addEventListener("progress", (event) => { }) -onprogress = (event) => {}; +onprogress = (event) => { } ``` ## Event type diff --git a/files/en-us/web/api/filereader/readasdataurl/index.md b/files/en-us/web/api/filereader/readasdataurl/index.md index 7806b04a5da8e3b..dce35eddd73a9a4 100644 --- a/files/en-us/web/api/filereader/readasdataurl/index.md +++ b/files/en-us/web/api/filereader/readasdataurl/index.md @@ -92,7 +92,7 @@ function previewFiles() { function readAndPreview(file) { // Make sure `file.name` matches our extensions criteria - if (/\.(jpe?g|png|gif)$/i.test(file.name)) { + if (/\.(?:jpe?g|png|gif)$/i.test(file.name)) { const reader = new FileReader(); reader.addEventListener( diff --git a/files/en-us/web/api/filereader/result/index.md b/files/en-us/web/api/filereader/result/index.md index a1f501c11cfe5f9..eba91e167707f86 100644 --- a/files/en-us/web/api/filereader/result/index.md +++ b/files/en-us/web/api/filereader/result/index.md @@ -68,7 +68,7 @@ The result types are described below. ## Examples -This example presents a function `reader()` which reads a file from a [file input](/en-US/docs/Web/HTML/Element/input/file). It works by creating a {{domxref("FileReader")}} object and creating a listener for {{domxref("FileReader/load_event", "load")}} events, such that when then file is read, the `result` is obtained and passed to the callback function provided to `reader()`. +This example presents a function `reader()` which reads a file from a [file input](/en-US/docs/Web/HTML/Reference/Elements/input/file). It works by creating a {{domxref("FileReader")}} object and creating a listener for {{domxref("FileReader/load_event", "load")}} events, such that when then file is read, the `result` is obtained and passed to the callback function provided to `reader()`. The content is handled as raw text data. @@ -94,7 +94,7 @@ document.querySelector("#image").addEventListener("change", (evt) => { }); ``` -Given the asynchronous nature of {{domxref("FileReader")}}, you could use a Promise-based approach. Here's an example for a [file input](/en-US/docs/Web/HTML/Element/input/file) with attribute `multiple` that returns a {{jsxref("Promise")}}. +Given the asynchronous nature of {{domxref("FileReader")}}, you could use a Promise-based approach. Here's an example for a [file input](/en-US/docs/Web/HTML/Reference/Elements/input/file) with attribute `multiple` that returns a {{jsxref("Promise")}}. ```js // Given this HTMLInputElement: diff --git a/files/en-us/web/api/filereadersync/readasarraybuffer/index.md b/files/en-us/web/api/filereadersync/readasarraybuffer/index.md index eb7169ce3789845..6a01a5ae2f43be7 100644 --- a/files/en-us/web/api/filereadersync/readasarraybuffer/index.md +++ b/files/en-us/web/api/filereadersync/readasarraybuffer/index.md @@ -30,7 +30,7 @@ An {{jsxref("ArrayBuffer")}} representing the file's data. The following exceptions can be raised by this method: - `NotFoundError` {{domxref("DOMException")}} - - : Thrown if the resource represented by the DOM {{DOMxRef("File")}} or {{DOMxRef("Blob")}} cannot be found, e.g. because it has been erased. + - : Thrown if the resource represented by the DOM {{DOMxRef("File")}} or {{DOMxRef("Blob")}} cannot be found, e.g., because it has been erased. - `SecurityError` {{domxref("DOMException")}} - : Thrown if one of the following problematic situation is detected: - the resource has been modified by a third party; diff --git a/files/en-us/web/api/filereadersync/readasbinarystring/index.md b/files/en-us/web/api/filereadersync/readasbinarystring/index.md index f01b4c3bd811a4e..e887f2276113bf4 100644 --- a/files/en-us/web/api/filereadersync/readasbinarystring/index.md +++ b/files/en-us/web/api/filereadersync/readasbinarystring/index.md @@ -33,7 +33,7 @@ A string representing the input data. ### Exceptions - `NotFoundError` {{domxref("DOMException")}} - - : Thrown if the resource represented by the DOM {{DOMxRef("File")}} or {{DOMxRef("Blob")}} cannot be found, e.g. because it has been erased. + - : Thrown if the resource represented by the DOM {{DOMxRef("File")}} or {{DOMxRef("Blob")}} cannot be found, e.g., because it has been erased. - `SecurityError` {{domxref("DOMException")}} - : Thrown if one of the following problematic situation is detected: - the resource has been modified by a third party; diff --git a/files/en-us/web/api/filereadersync/readasdataurl/index.md b/files/en-us/web/api/filereadersync/readasdataurl/index.md index 32f0aa287ca7899..ad698824124aaa9 100644 --- a/files/en-us/web/api/filereadersync/readasdataurl/index.md +++ b/files/en-us/web/api/filereadersync/readasdataurl/index.md @@ -30,11 +30,11 @@ A string representing the input data as a data URL. The following exceptions can be raised by this method: - `NotFoundError` {{domxref("DOMException")}} - - : Thrown if the resource represented by the DOM {{DOMxRef("File")}} or {{DOMxRef("Blob")}} cannot be found, e.g. because it has been erased. + - : Thrown if the resource represented by the DOM {{DOMxRef("File")}} or {{DOMxRef("Blob")}} cannot be found, e.g., because it has been erased. - `SecurityError` {{domxref("DOMException")}} - : Thrown if one of the following problematic situation is detected: - the resource has been modified by a third party; - - too many read are performed simultaneously; + - too many read operations are performed simultaneously; - the file pointed by the resource is unsafe for a use from the Web (like it is a system file). - `NotReadableError` {{domxref("DOMException")}} - : Thrown if the resource cannot be read due to a permission problem, like a concurrent lock. diff --git a/files/en-us/web/api/filereadersync/readastext/index.md b/files/en-us/web/api/filereadersync/readastext/index.md index 9b636590f4c6d04..ab9cfa38dd36b52 100644 --- a/files/en-us/web/api/filereadersync/readastext/index.md +++ b/files/en-us/web/api/filereadersync/readastext/index.md @@ -33,7 +33,7 @@ A string representing the input data. The following exceptions can be raised by this method: - `NotFoundError` {{domxref("DOMException")}} - - : Thrown if the resource represented by the DOM {{DOMxRef("File")}} or {{DOMxRef("Blob")}} cannot be found, e.g. because it has been erased. + - : Thrown if the resource represented by the DOM {{DOMxRef("File")}} or {{DOMxRef("Blob")}} cannot be found, e.g., because it has been erased. - `SecurityError` {{domxref("DOMException")}} - : Thrown if one of the following problematic situation is detected: - the resource has been modified by a third party; diff --git a/files/en-us/web/api/filesystem/index.md b/files/en-us/web/api/filesystem/index.md index 2583e700281d380..1acf0313ca520da 100644 --- a/files/en-us/web/api/filesystem/index.md +++ b/files/en-us/web/api/filesystem/index.md @@ -9,7 +9,7 @@ browser-compat: api.FileSystem The File and Directory Entries API interface **`FileSystem`** is used to represent a file system. These objects can be obtained from the {{domxref("FileSystemEntry.filesystem", "filesystem")}} property on any file system entry. Some browsers offer additional APIs to create and manage file systems, such as Chrome's {{domxref("Window.requestFileSystem", "requestFileSystem()")}} method. -This interface will not grant you access to the users' filesystem. Instead, you will have a "virtual drive" within the browser sandbox if you want to gain access to the users' file system, you need to invoke the user, for example by installing a Chrome extension. The relevant Chrome API can be found [here](https://developer.chrome.com/docs/apps/reference/fileSystem). +This interface will not grant you access to the users' filesystem. Instead, you will have a "virtual drive" within the browser sandbox if you want to gain access to the users' file system, you need to invoke the user, for example by installing a Chrome extension. The relevant Chrome API can be found [in the Chrome developer docs](https://developer.chrome.com/docs/apps/reference/fileSystem). ## Basic concepts diff --git a/files/en-us/web/api/filesystemdirectoryentry/getdirectory/index.md b/files/en-us/web/api/filesystemdirectoryentry/getdirectory/index.md index a11f5d27dd6c42f..605de7d2583f763 100644 --- a/files/en-us/web/api/filesystemdirectoryentry/getdirectory/index.md +++ b/files/en-us/web/api/filesystemdirectoryentry/getdirectory/index.md @@ -63,7 +63,7 @@ The table below describes the result of each possible combination of these flags | `false` | _Ignored_ | Path exists but is a file | The `errorCallback` is called with an appropriate error code (if the callback was provided). | | `true` | `false` | Path exists | The existing directory is removed and replaced with a new one, then the `successCallback` is called with a {{domxref("FileSystemDirectoryEntry")}}. | | `true` | `false` | Path doesn't exist | The directory is created, then a {{domxref("FileSystemDirectoryEntry")}} is passed to the `successCallback`. | -| `true` | `true` | Path exists | The `errorCallback` is called with an appropriate error, such as `FileError.PATH_EXISTS_ERR`. | +| `true` | `true` | Path exists | The `errorCallback` is called with an appropriate error, such as `DOMException.PATH_EXISTS_ERR`. | | `true` | `true` | Path doesn't exist | The directory is created, then a {{domxref("FileSystemDirectoryEntry")}} is passed to the `successCallback`. | ### Return value diff --git a/files/en-us/web/api/filesystemdirectoryentry/getfile/index.md b/files/en-us/web/api/filesystemdirectoryentry/getfile/index.md index cb9612822f83fa3..0f24f82d1b29272 100644 --- a/files/en-us/web/api/filesystemdirectoryentry/getfile/index.md +++ b/files/en-us/web/api/filesystemdirectoryentry/getfile/index.md @@ -62,7 +62,7 @@ The table below describes the result of each possible combination of these flags | `false` | _Ignored_ | Path exists but is a directory | The `errorCallback` is called with an appropriate error code (if the callback was provided). | | `true` | `false` | Path exists | The existing file is removed and replaced with a new one, then the `successCallback` is called with a {{domxref("FileSystemFileEntry")}}. | | `true` | `false` | Path doesn't exist | The file is created, then a {{domxref("FileSystemFileEntry")}} is passed to the `successCallback`. | -| `true` | `true` | Path exists | The `errorCallback` is called with an appropriate error, such as `FileError.PATH_EXISTS_ERR`. | +| `true` | `true` | Path exists | The `errorCallback` is called with an appropriate error, such as `DOMException.PATH_EXISTS_ERR`. | | `true` | `true` | Path doesn't exist | The file is created, then a {{domxref("FileSystemFileEntry")}} is passed to the `successCallback`. | ### Return value diff --git a/files/en-us/web/api/filesystemdirectoryentry/index.md b/files/en-us/web/api/filesystemdirectoryentry/index.md index b545b28744eaa92..567215dd307443b 100644 --- a/files/en-us/web/api/filesystemdirectoryentry/index.md +++ b/files/en-us/web/api/filesystemdirectoryentry/index.md @@ -32,17 +32,17 @@ function onFs(fs) { "Documents", { create: true }, (directoryEntry) => { - //directoryEntry.isFile === false - //directoryEntry.isDirectory === true - //directoryEntry.name === 'Documents' - //directoryEntry.fullPath === '/Documents' + // directoryEntry.isFile === false + // directoryEntry.isDirectory === true + // directoryEntry.name === 'Documents' + // directoryEntry.fullPath === '/Documents' }, onError, ); } // Opening a file system with temporary storage -window.requestFileSystem(TEMPORARY, 1024 * 1024 /*1MB*/, onFs, onError); +window.requestFileSystem(TEMPORARY, 1024 * 1024 /* 1MB */, onFs, onError); ``` ## Instance properties diff --git a/files/en-us/web/api/filesystemdirectoryentry/removerecursively/index.md b/files/en-us/web/api/filesystemdirectoryentry/removerecursively/index.md index 9dff332df074b80..e2d1e25acfeb431 100644 --- a/files/en-us/web/api/filesystemdirectoryentry/removerecursively/index.md +++ b/files/en-us/web/api/filesystemdirectoryentry/removerecursively/index.md @@ -33,7 +33,7 @@ removeRecursively(successCallback, errorCallback) has no parameters. - `errorCallback` {{optional_inline}} - : A function to be called if an error occurs while attempting to remove the directory - subtree. Receives a {{domxref("FileError")}} describing the error which occurred as + subtree. Receives a {{domxref("DOMException")}} describing the error which occurred as input. ### Return value @@ -43,20 +43,20 @@ None ({{jsxref("undefined")}}). ### Exceptions If an error occurs and an `errorCallback` was specified, it gets called with -a single parameter: a {{domxref("FileError")}} object describing the error. The -{{domxref("FileError.code")}} specifies what type of error occurred, as follows: +a single parameter: a {{domxref("DOMException")}} object describing the error. The +{{domxref("DOMException.code")}} specifies what type of error occurred, as follows: -- `FileError.INVALID_MODIFICATION_ERR` +- `DOMException.INVALID_MODIFICATION_ERR` - : An attempt was made to remove the root directory; this is not permitted. -- `FileError.NO_MODIFICATION_ALLOWED_ERR` +- `DOMException.NO_MODIFICATION_ALLOWED_ERR` - : The file system's state doesn't permit modification. -- `FileError.NOT_FOUND_ERR` +- `DOMException.NOT_FOUND_ERR` - : The directory represented by the {{domxref("FileSystemDirectoryEntry")}} no longer exists. -- `FileError.NOT_READABLE_ERR` +- `DOMException.NOT_READABLE_ERR` - : The directory is not accessible; perhaps it's in use by another application or is locked at the operating system level. -- `FileError.SECURITY_ERR` +- `DOMException.SECURITY_ERR` - : The directory could not be removed for security reasons. Possible reasons include: diff --git a/files/en-us/web/api/filesystementry/copyto/index.md b/files/en-us/web/api/filesystementry/copyto/index.md index 708b24f1cba5d29..3ee1b64dc143fae 100644 --- a/files/en-us/web/api/filesystementry/copyto/index.md +++ b/files/en-us/web/api/filesystementry/copyto/index.md @@ -46,7 +46,7 @@ copyTo(newParent, newName, successCallback, errorCallback) providing the copied item's new details. - `errorCallback` {{optional_inline}} - : An optional callback which is executed if an error occurs while copying the items. - There's a single parameter: a {{domxref("FileError")}} describing what went wrong. + There's a single parameter: a {{domxref("DOMException")}} describing what went wrong. ### Return value @@ -54,11 +54,11 @@ None ({{jsxref("undefined")}}). ### Exceptions -- `FileError.INVALID_MODIFICATION_ERR` +- `DOMException.INVALID_MODIFICATION_ERR` - : The requested operation involves an impossible change, such as moving a directory inside itself or one of its own child directories, or copying an item within the same directory without renaming it. -- `FileError.QUOTA_EXCEEDED_ERR` +- `DOMException.QUOTA_EXCEEDED_ERR` - : The operation exceeded the user's storage quota, or there isn't enough storage space left to complete the operation. diff --git a/files/en-us/web/api/filesystementry/getmetadata/index.md b/files/en-us/web/api/filesystementry/getmetadata/index.md index ef50f6116f30989..91e93c4ddd31bdb 100644 --- a/files/en-us/web/api/filesystementry/getmetadata/index.md +++ b/files/en-us/web/api/filesystementry/getmetadata/index.md @@ -31,7 +31,7 @@ getMetadata(successCallback, errorCallback) about the file. - `errorCallback` {{optional_inline}} - : An optional callback which is executed if an error occurs while looking up the - metadata. There's a single parameter: a {{domxref("FileError")}} describing what went + metadata. There's a single parameter: a {{domxref("DOMException")}} describing what went wrong. ### Return value @@ -40,9 +40,9 @@ None ({{jsxref("undefined")}}). ### Exceptions -- `FileError.NOT_FOUND_ERR` +- `DOMException.NOT_FOUND_ERR` - : The {{domxref("FileSystemEntry")}} refers to an item which doesn't exist. -- `FileError.SECURITY_ERR` +- `DOMException.SECURITY_ERR` - : Security restrictions prohibit obtaining the requested metadata. ## Examples diff --git a/files/en-us/web/api/filesystementry/getparent/index.md b/files/en-us/web/api/filesystementry/getparent/index.md index 0b2fa549b50d465..a9c99e8a2fb3c95 100644 --- a/files/en-us/web/api/filesystementry/getparent/index.md +++ b/files/en-us/web/api/filesystementry/getparent/index.md @@ -36,13 +36,13 @@ None ({{jsxref("undefined")}}). ### Exceptions -- `FileError.INVALID_STATE_ERR` +- `DOMException.INVALID_STATE_ERR` - : The operation failed because the file system's state doesn't permit it. This can happen, for example, if the file system's cached state differs from the actual state of the file system. -- `FileError.NOT_FOUND_ERR` +- `DOMException.NOT_FOUND_ERR` - : The specified path could not be found. -- `FileError.SECURITY_ERR` +- `DOMException.SECURITY_ERR` - : Security restrictions prohibit obtaining the parent directory's information. ## Examples diff --git a/files/en-us/web/api/filesystementry/index.md b/files/en-us/web/api/filesystementry/index.md index 42ef89f4bce98b4..a13fe316b0d49ad 100644 --- a/files/en-us/web/api/filesystementry/index.md +++ b/files/en-us/web/api/filesystementry/index.md @@ -13,13 +13,13 @@ The **`FileSystemEntry`** interface of the File and Directory Entries API repres You don't create `FileSystemEntry` objects directly. Instead, you will receive an object based on this interface through other APIs. This interface serves as a base class for the {{domxref("FileSystemFileEntry")}} and {{domxref("FileSystemDirectoryEntry")}} interfaces, which provide features specific to file system entries representing files and directories, respectively. -The `FileSystemEntry` interface includes methods that you would expect for manipulating files and directories, but it also includes a convenient method for obtaining the URL of the entry: [`toURL()`](#tourl). It also introduces a new URL scheme: `filesystem:`. +The `FileSystemEntry` interface includes methods that you would expect for manipulating files and directories, but it also includes a convenient method for obtaining the URL of the entry: [`toURL()`](/en-US/docs/Web/API/FileSystemEntry/toURL). It also introduces a new URL scheme: `filesystem:`. You can use the `filesystem:` scheme on Google Chrome to see all the files and folders that are stored in the origin of your app. Just use `filesystem:` scheme for the root directory of the origin of the app. For example, if your app is in [`http://www.example.com`](https://www.example.com/), open `filesystem:http://www.example.com/temporary/` in a tab. Chrome shows a read-only list of all the files and folders stored the origin of your app. ### Example -To see an example of how `toURL()` works, see the [method description](#tourl). The snippet below shows you how you can remove a file by name. +To see an example of how `toURL()` works, see the [method description](/en-US/docs/Web/API/FileSystemEntry/toURL). The snippet below shows you how you can remove a file by name. ```js // Taking care of the browser-specific prefixes. @@ -31,7 +31,7 @@ window.requestFileSystem = // Opening a file system with temporary storage window.requestFileSystem( TEMPORARY, - 1024 * 1024 /*1MB*/, + 1024 * 1024 /* 1MB */, (fs) => { fs.root.getFile( "log.txt", diff --git a/files/en-us/web/api/filesystementry/moveto/index.md b/files/en-us/web/api/filesystementry/moveto/index.md index dcb742ea8410f95..8c487f6c527588a 100644 --- a/files/en-us/web/api/filesystementry/moveto/index.md +++ b/files/en-us/web/api/filesystementry/moveto/index.md @@ -51,7 +51,7 @@ moveTo(newParent, newName, successCallback, errorCallback) providing the moved item's new details. - `errorCallback` {{optional_inline}} - : An optional callback which is executed if an error occurs while moving the items. - There's a single parameter: a {{domxref("FileError")}} describing what went wrong. + There's a single parameter: a {{domxref("DOMException")}} describing what went wrong. ### Return value @@ -59,11 +59,11 @@ None ({{jsxref("undefined")}}). ### Exceptions -- `FileError.INVALID_MODIFICATION_ERR` +- `DOMException.INVALID_MODIFICATION_ERR` - : The requested operation involves an impossible change, such as moving a directory inside itself or one of its own child directories, or copying an item within the same directory without renaming it. -- `FileError.QUOTA_EXCEEDED_ERR` +- `DOMException.QUOTA_EXCEEDED_ERR` - : The operation exceeded the user's storage quota, or there isn't enough storage space left to complete the operation. diff --git a/files/en-us/web/api/filesystementry/remove/index.md b/files/en-us/web/api/filesystementry/remove/index.md index f0c7cceff2acd59..00cfeac6f90f941 100644 --- a/files/en-us/web/api/filesystementry/remove/index.md +++ b/files/en-us/web/api/filesystementry/remove/index.md @@ -40,17 +40,17 @@ None ({{jsxref("undefined")}}). ### Exceptions -- `FileError.INVALID_MODIFICATION_ERR` +- `DOMException.INVALID_MODIFICATION_ERR` - : The specified entry was the file system's root directory, or the specified entry is a directory which isn't empty. -- `FileError.INVALID_STATE_ERR` +- `DOMException.INVALID_STATE_ERR` - : The file system's cached state is inconsistent with its state on disk, so the file could not be deleted for safety reasons. -- `FileError.NO_MODIFICATION_ALLOWED_ERR` +- `DOMException.NO_MODIFICATION_ALLOWED_ERR` - : The file system's state doesn't permit removing the file or directory. -- `FileError.NOT_FOUND_ERR` +- `DOMException.NOT_FOUND_ERR` - : The file or directory doesn't exist. -- `FileError.SECURITY_ERR` +- `DOMException.SECURITY_ERR` - : The entry couldn't be removed due to permissions or other access constraints, or because there are too many calls being made on file resources. diff --git a/files/en-us/web/api/filesystemfileentry/createwriter/index.md b/files/en-us/web/api/filesystemfileentry/createwriter/index.md index 0cab7f01187ebc6..b8922af7f7b5372 100644 --- a/files/en-us/web/api/filesystemfileentry/createwriter/index.md +++ b/files/en-us/web/api/filesystemfileentry/createwriter/index.md @@ -31,7 +31,7 @@ createWriter(successCallback, errorCallback) - `errorCallback` {{optional_inline}} - : If provided, this must be a method which is called when an error occurs while trying to create the {{domxref("FileWriter")}}. This callback receives as input a - {{domxref("FileError")}} object describing the error. + {{domxref("DOMException")}} object describing the error. ### Return value @@ -50,7 +50,7 @@ function writeToFileEntry(entry, text) { fileWriter.write(data); }, - (fileError) => { + (error) => { /* do whatever to handle the error */ }, ); diff --git a/files/en-us/web/api/filesystemfilehandle/createsyncaccesshandle/index.md b/files/en-us/web/api/filesystemfilehandle/createsyncaccesshandle/index.md index c1ce70f34cb181a..00072c5a9db4f1c 100644 --- a/files/en-us/web/api/filesystemfilehandle/createsyncaccesshandle/index.md +++ b/files/en-us/web/api/filesystemfilehandle/createsyncaccesshandle/index.md @@ -199,14 +199,14 @@ onmessage = function (e) { accessHandle.read(dataView, { at: 0 }); // Log the current file contents to the console - console.log("File contents: " + textDecoder.decode(dataView)); + console.log(`File contents: ${textDecoder.decode(dataView)}`); // Flush the changes accessHandle.flush(); } // Log the size of the file to the console - console.log("Size: " + size); + console.log(`Size: ${size}`); }; ``` diff --git a/files/en-us/web/api/filesystemfilehandle/createwritable/index.md b/files/en-us/web/api/filesystemfilehandle/createwritable/index.md index 1fadfb9c1443743..f525833d1f04f4c 100644 --- a/files/en-us/web/api/filesystemfilehandle/createwritable/index.md +++ b/files/en-us/web/api/filesystemfilehandle/createwritable/index.md @@ -103,7 +103,7 @@ The two {{htmlelement("button")}} elements and text {{htmlelement("input")}} fie </ol> ``` -The text input field and the write text button are set to be disabled initially via the [`disabled`](/en-US/docs/Web/HTML/Attributes/disabled) attribute — they shouldn't be used until the user has selected a file to write to. +The text input field and the write text button are set to be disabled initially via the [`disabled`](/en-US/docs/Web/HTML/Reference/Attributes/disabled) attribute — they shouldn't be used until the user has selected a file to write to. ```css hidden li { diff --git a/files/en-us/web/api/filesystemhandle/remove/index.md b/files/en-us/web/api/filesystemhandle/remove/index.md index cefaf227cd9d5f5..9a0ad32a2da9d24 100644 --- a/files/en-us/web/api/filesystemhandle/remove/index.md +++ b/files/en-us/web/api/filesystemhandle/remove/index.md @@ -64,10 +64,10 @@ When the "Delete" button is pressed, the `deleteFile()` function is run, which l ```js async function deleteFile(e) { for (const handle of savedFileRefs) { - if (handle.name === e.target.id + ".txt") { + if (handle.name === `${e.target.id}.txt`) { await handle.remove(); savedFileRefs = savedFileRefs.filter( - (handle) => handle.name !== e.target.id + ".txt", + (handle) => handle.name !== `${e.target.id}.txt`, ); e.target.parentElement.parentElement.removeChild(e.target.parentElement); } diff --git a/files/en-us/web/api/filesystemhandle/requestpermission/index.md b/files/en-us/web/api/filesystemhandle/requestpermission/index.md index dbbe12472d00b70..8b1f5abcedfe950 100644 --- a/files/en-us/web/api/filesystemhandle/requestpermission/index.md +++ b/files/en-us/web/api/filesystemhandle/requestpermission/index.md @@ -41,7 +41,7 @@ A {{jsxref("Promise")}} that resolves with {{domxref('PermissionStatus.state')}} `'read'` or `'readwrite'` - `SecurityError` {{domxref("DOMException")}} - : Thrown in one of the following cases: - - The method was called in a context that's not [same-origin](/en-US/docs/Web/Security/Same-origin_policy) as the top-level context (i.e. a cross-origin iframe). + - The method was called in a context that's not [same-origin](/en-US/docs/Web/Security/Same-origin_policy) as the top-level context (i.e., a cross-origin iframe). - There was no transient user activation such as a button press. This includes when the handle is in a non-Window context which cannot consume user activation, such as a worker. ## Security diff --git a/files/en-us/web/api/filesystemobserver/filesystemobserver/index.md b/files/en-us/web/api/filesystemobserver/filesystemobserver/index.md index 8cc921100c695d8..80474dd57c2992e 100644 --- a/files/en-us/web/api/filesystemobserver/filesystemobserver/index.md +++ b/files/en-us/web/api/filesystemobserver/filesystemobserver/index.md @@ -35,7 +35,7 @@ A new {{domxref("FileSystemObserver")}} object. ## Examples > [!NOTE] -> For a complete working example, check out [File System Observer Demo](https://file-system-observer.glitch.me/) ([source code](https://glitch.com/edit/#!/file-system-observer)). +> For a complete working example, check out [File System Observer Demo](https://mdn.github.io/dom-examples/filesystemobserver/) ([source code](https://github.com/mdn/dom-examples/tree/main/filesystemobserver)). ### Initializing a `FileSystemObserver` diff --git a/files/en-us/web/api/filesystemobserver/index.md b/files/en-us/web/api/filesystemobserver/index.md index 994f604727bf66c..61b946337709f93 100644 --- a/files/en-us/web/api/filesystemobserver/index.md +++ b/files/en-us/web/api/filesystemobserver/index.md @@ -27,7 +27,7 @@ The **`FileSystemObserver`** interface of the {{domxref("File System API", "File ## Examples > [!NOTE] -> For a complete working example, check out [File System Observer Demo](https://file-system-observer.glitch.me/) ([source code](https://glitch.com/edit/#!/file-system-observer)). +> For a complete working example, check out [File System Observer Demo](https://mdn.github.io/dom-examples/filesystemobserver/) ([source code](https://github.com/mdn/dom-examples/tree/main/filesystemobserver)). ### Initialize a `FileSystemObserver` diff --git a/files/en-us/web/api/filesystemsyncaccesshandle/index.md b/files/en-us/web/api/filesystemsyncaccesshandle/index.md index 1e59412e88335f7..40ad1d1a8d44e1e 100644 --- a/files/en-us/web/api/filesystemsyncaccesshandle/index.md +++ b/files/en-us/web/api/filesystemsyncaccesshandle/index.md @@ -11,7 +11,7 @@ The **`FileSystemSyncAccessHandle`** interface of the {{domxref("File System API This class is only accessible inside dedicated [Web Workers](/en-US/docs/Web/API/Web_Workers_API) (so that its methods do not block execution on the main thread) for files within the [origin private file system](/en-US/docs/Web/API/File_System_API/Origin_private_file_system), which is not visible to end-users. -As a result, its methods are not subject to the same security checks as methods running on files within the user-visible file system, and so are much more performant. This makes them suitable for significant, large-scale file updates such as [SQLite](https://www.sqlite.org/wasm) database modifications. +As a result, its methods are not subject to the same security checks as methods running on files within the user-visible file system, and so are much more performant. This makes them suitable for significant, large-scale file updates such as [SQLite](https://sqlite.org/wasm) database modifications. The interface is accessed through the {{domxref('FileSystemFileHandle.createSyncAccessHandle()')}} method. diff --git a/files/en-us/web/api/filesystemsyncaccesshandle/write/index.md b/files/en-us/web/api/filesystemsyncaccesshandle/write/index.md index 51f992c8ec164c0..973a59e8c1420d0 100644 --- a/files/en-us/web/api/filesystemsyncaccesshandle/write/index.md +++ b/files/en-us/web/api/filesystemsyncaccesshandle/write/index.md @@ -11,7 +11,7 @@ browser-compat: api.FileSystemSyncAccessHandle.write The **`write()`** method of the {{domxref("FileSystemSyncAccessHandle")}} interface writes the content of a specified buffer to the file associated with the handle, optionally at a given offset. -Files within the [origin private file system](/en-US/docs/Web/API/File_System_API/Origin_private_file_system) are not visible to end-users, therefore are not subject to the same security checks as methods running on files within the user-visible file system. As a result, writes performed using `FileSystemSyncAccessHandle.write()` are much more performant. This makes them suitable for significant, large-scale file updates such as [SQLite](https://www.sqlite.org/wasm) database modifications. +Files within the [origin private file system](/en-US/docs/Web/API/File_System_API/Origin_private_file_system) are not visible to end-users, therefore are not subject to the same security checks as methods running on files within the user-visible file system. As a result, writes performed using `FileSystemSyncAccessHandle.write()` are much more performant. This makes them suitable for significant, large-scale file updates such as [SQLite](https://sqlite.org/wasm) database modifications. ## Syntax diff --git a/files/en-us/web/api/fontface/index.md b/files/en-us/web/api/fontface/index.md index 73e9487d07cc50a..1259ef10c5ed7fa 100644 --- a/files/en-us/web/api/fontface/index.md +++ b/files/en-us/web/api/fontface/index.md @@ -56,7 +56,7 @@ The code below defines a font face using data at the URL "my-font.woff" with a f Just to show how it works, we then define the `stretch` descriptor using a property. ```js -//Define a FontFace +// Define a FontFace const font = new FontFace("my-font", "url(my-font.woff)", { style: "italic", weight: "400", @@ -68,7 +68,7 @@ font.stretch = "condensed"; Next we load the font using {{domxref("FontFace.load()")}} and use the returned promise to track completion or report an error. ```js -//Load the font +// Load the font font.load().then( () => { // Resolved - add font to document.fonts diff --git a/files/en-us/web/api/fontfaceset/check/index.md b/files/en-us/web/api/fontfaceset/check/index.md index ea56ab66f47b694..0067c5cf6750a2c 100644 --- a/files/en-us/web/api/fontfaceset/check/index.md +++ b/files/en-us/web/api/fontfaceset/check/index.md @@ -40,15 +40,11 @@ Otherwise, this function returns `false`. In the following example, we create a new `FontFace` and add it to the `FontFaceSet`: ```js -const font = new FontFace( - "molot", - "url(https://interactive-examples.mdn.mozilla.net/media/fonts/molot.woff2)", - { - style: "normal", - weight: "400", - stretch: "condensed", - }, -); +const font = new FontFace("molot", "url(/shared-assets/fonts/molot.woff2)", { + style: "normal", + weight: "400", + stretch: "condensed", +}); document.fonts.add(font); ``` diff --git a/files/en-us/web/api/fontfaceset/load/index.md b/files/en-us/web/api/fontfaceset/load/index.md index be844640954339b..5f08d119d0c5ed5 100644 --- a/files/en-us/web/api/fontfaceset/load/index.md +++ b/files/en-us/web/api/fontfaceset/load/index.md @@ -20,7 +20,7 @@ load(font, text) ### Parameters - `font` - - : a font specification using the CSS value syntax, e.g. "italic bold 16px Roboto" + - : a font specification using the CSS value syntax, e.g., "italic bold 16px Roboto" - `text` - : limit the font faces to those whose Unicode range contains at least one of the characters in text. This [does not check for individual glyph coverage](https://lists.w3.org/Archives/Public/www-style/2015Aug/0330.html). diff --git a/files/en-us/web/api/fontfaceset/loading_event/index.md b/files/en-us/web/api/fontfaceset/loading_event/index.md index a40567acd7c5019..0f9bf2be6f86477 100644 --- a/files/en-us/web/api/fontfaceset/loading_event/index.md +++ b/files/en-us/web/api/fontfaceset/loading_event/index.md @@ -14,10 +14,10 @@ The `loading` event fires when the document begins loading fonts. Use the event name in methods like {{domxref("EventTarget.addEventListener", "addEventListener()")}}, or set an event handler property. -```js -addEventListener("loading", (event) => {}); +```js-nolint +addEventListener("loading", (event) => { }) -onloading = (event) => {}; +onloading = (event) => { } ``` ## Example diff --git a/files/en-us/web/api/fontfaceset/loadingdone_event/index.md b/files/en-us/web/api/fontfaceset/loadingdone_event/index.md index b1e35c2a9868339..77fd85e16439515 100644 --- a/files/en-us/web/api/fontfaceset/loadingdone_event/index.md +++ b/files/en-us/web/api/fontfaceset/loadingdone_event/index.md @@ -14,10 +14,10 @@ The `loadingdone` event fires when the document has loaded all fonts. Use the event name in methods like {{domxref("EventTarget.addEventListener", "addEventListener()")}}, or set an event handler property. -```js -addEventListener("loadingdone", (event) => {}); +```js-nolint +addEventListener("loadingdone", (event) => { }) -onloadingdone = (event) => {}; +onloadingdone = (event) => { } ``` ## Example diff --git a/files/en-us/web/api/fontfaceset/loadingerror_event/index.md b/files/en-us/web/api/fontfaceset/loadingerror_event/index.md index c5f29b4cef6723f..08203b1d71a19c3 100644 --- a/files/en-us/web/api/fontfaceset/loadingerror_event/index.md +++ b/files/en-us/web/api/fontfaceset/loadingerror_event/index.md @@ -14,10 +14,10 @@ The `loadingerror` event fires when fonts have finished loading, but some or all Use the event name in methods like {{domxref("EventTarget.addEventListener", "addEventListener()")}}, or set an event handler property. -```js -addEventListener("loadingerror", (event) => {}); +```js-nolint +addEventListener("loadingerror", (event) => { }) -onloadingerror = (event) => {}; +onloadingerror = (event) => { } ``` ## Example diff --git a/files/en-us/web/api/formdata/formdata/index.md b/files/en-us/web/api/formdata/formdata/index.md index 4adbc8f8b2386c1..b3b23a9d96216fa 100644 --- a/files/en-us/web/api/formdata/formdata/index.md +++ b/files/en-us/web/api/formdata/formdata/index.md @@ -23,7 +23,7 @@ new FormData(form, submitter) - `form` {{optional_inline}} - : An HTML {{HTMLElement("form")}} element — when specified, the {{domxref("FormData")}} object will be populated with the `form`'s current keys/values using the name property of each element for the keys and their submitted value for the values. It will also encode file input content. A {{domxref("HTMLFormElement/formdata_event", "formdata")}} event is fired on the form when the `FormData` object is created, allowing the form to modify the formdata if necessary. - `submitter` {{optional_inline}} - - : A {{Glossary("submit button")}} that is a member of the `form`. If the `submitter` has a `name` attribute or is an `{{HtmlElement('input/image', '&lt;input type="image"&gt;')}}`, its data [will be included](/en-US/docs/Glossary/Submit_button#form_data_entries) in the {{domxref("FormData")}} object (e.g. `btnName=btnValue`). + - : A {{Glossary("submit button")}} that is a member of the `form`. If the `submitter` has a `name` attribute or is an `{{HtmlElement('input/image', '&lt;input type="image"&gt;')}}`, its data [will be included](/en-US/docs/Glossary/Submit_button#form_data_entries) in the {{domxref("FormData")}} object (e.g., `btnName=btnValue`). ### Exceptions @@ -31,7 +31,7 @@ new FormData(form, submitter) - : Thrown if the specified `submitter` is not a {{Glossary("submit button")}}. - `NotFoundError` {{domxref("DOMException")}} - : Thrown if the specified `submitter` isn't a member of the `form`. The `submitter` must be either a - descendant of the form element or must have a [`form`](/en-US/docs/Web/HTML/Element/input#form) + descendant of the form element or must have a [`form`](/en-US/docs/Web/HTML/Reference/Elements/input#form) attribute referring to the form. ## Examples @@ -55,7 +55,7 @@ formData.append("username", "Chris"); You can specify the optional `form` and `submitter` arguments when creating the `FormData` object, to prepopulate it with values from the specified form. > [!NOTE] -> Only successful form controls are included in a FormData object, i.e. those with a name and not in a disabled state. +> Only successful form controls are included in a FormData object, i.e., those with a name and not in a disabled state. #### HTML diff --git a/files/en-us/web/api/formdataevent/formdata/index.md b/files/en-us/web/api/formdataevent/formdata/index.md index 2c575648616876e..4b35aa9fc024390 100644 --- a/files/en-us/web/api/formdataevent/formdata/index.md +++ b/files/en-us/web/api/formdataevent/formdata/index.md @@ -61,7 +61,7 @@ formElem.addEventListener("formdata", (e) => { ## See also -- {{domxref("XMLHTTPRequest")}} +- {{domxref("XMLHttpRequest")}} - [Using XMLHttpRequest](/en-US/docs/Web/API/XMLHttpRequest_API/Using_XMLHttpRequest) - [Using FormData objects](/en-US/docs/Web/API/XMLHttpRequest_API/Using_FormData_Objects) - {{HTMLElement("Form")}} diff --git a/files/en-us/web/api/fullscreen_api/guide/index.md b/files/en-us/web/api/fullscreen_api/guide/index.md index caa05e87c80f539..7f97262f74c8869 100644 --- a/files/en-us/web/api/fullscreen_api/guide/index.md +++ b/files/en-us/web/api/fullscreen_api/guide/index.md @@ -35,13 +35,17 @@ if (elem.requestFullscreen) { This code checks for the existence of the `requestFullscreen()` method before calling it. +Once an element is in fullscreen mode, it is matched by {{cssxref(":fullscreen")}}, which gives it some default styles like taking up the entire screen. It is also placed in the {{glossary("top layer")}}. + +If multiple elements are requested to be displayed in fullscreen mode, they all get matched by {{cssxref(":fullscreen")}} and are all in the top layer. They stack on top each other, with more recently requested elements on top of older ones. The most recently requested element gets displayed and is returned by {{domxref("Document.fullscreenElement")}}. + ### Notification When fullscreen mode is successfully engaged, the document which contains the element receives a {{domxref("Element/fullscreenchange_event", "fullscreenchange")}} event. When fullscreen mode is exited, the document again receives a {{domxref("Document/fullscreenchange_event", "fullscreenchange")}} event. Note that the {{domxref("Document/fullscreenchange_event", "fullscreenchange")}} event doesn't provide any information itself as to whether the document is entering or exiting fullscreen mode, but if the document has a non null {{DOMxRef("document.fullscreenElement", "fullscreenElement")}}, you know you're in fullscreen mode. ### When a fullscreen request fails -It's not guaranteed that you'll be able to switch into fullscreen mode. For example, {{HTMLElement("iframe")}} elements have the [`allowfullscreen`](/en-US/docs/Web/HTML/Element/iframe#allowfullscreen) attribute in order to opt-in to allowing their content to be displayed in fullscreen mode. In addition, certain kinds of content, such as windowed plug-ins, cannot be presented in fullscreen mode. Attempting to put an element which can't be displayed in fullscreen mode (or the parent or descendant of such an element) won't work. Instead, the element which requested fullscreen will receive a `fullscreenerror` event. When a fullscreen request fails, Firefox will log an error message to the Web Console explaining why the request failed. In Chrome and newer versions of Opera however, no such warning is generated. +It's not guaranteed that you'll be able to switch into fullscreen mode. For example, {{HTMLElement("iframe")}} elements have the [`allowfullscreen`](/en-US/docs/Web/HTML/Reference/Elements/iframe#allowfullscreen) attribute in order to opt-in to allowing their content to be displayed in fullscreen mode. In addition, certain kinds of content, such as windowed plug-ins, cannot be presented in fullscreen mode. Attempting to put an element which can't be displayed in fullscreen mode (or the parent or descendant of such an element) won't work. Instead, the element which requested fullscreen will receive a `fullscreenerror` event. When a fullscreen request fails, Firefox will log an error message to the Web Console explaining why the request failed. In Chrome and newer versions of Opera however, no such warning is generated. > [!NOTE] > Fullscreen requests need to be called from within an event handler or otherwise they will be denied. @@ -50,6 +54,8 @@ It's not guaranteed that you'll be able to switch into fullscreen mode. For exam The user always has the ability to exit fullscreen mode of their own accord; see [Things your users want to know](#things_your_users_want_to_know). You can also do so programmatically by calling the {{DOMxRef("Document.exitFullscreen()")}} method. +If there are multiple elements in fullscreen mode, calling `exitFullscreen()` only exits the topmost element, revealing the next element below it. Pressing <kbd>Esc</kbd> or <kbd>F11</kbd> exits all fullscreen elements. + ## Other information The {{DOMxRef("Document")}} provides some additional information that can be useful when developing fullscreen web applications: @@ -71,43 +77,9 @@ In addition, navigating to another page, changing tabs, or switching to another ## Example -In this example, a video is presented in a web page. Pressing the <kbd>Return</kbd> or <kbd>Enter</kbd> key lets the user toggle between windowed and fullscreen presentation of the video. - -[View Live Examples](https://mdn.dev/archives/media/samples/domref/fullscreen.html) - -### Watching for the Enter key - -When the page is loaded, this code is run to set up an event listener to watch for the <kbd>Enter</kbd> key. - -```js -document.addEventListener( - "keydown", - (e) => { - if (e.key === "Enter") { - toggleFullScreen(); - } - }, - false, -); -``` - -### Toggling fullscreen mode - -This code is called when the user hits the <kbd>Enter</kbd> key, as seen above. - -```js -function toggleFullScreen() { - if (!document.fullscreenElement) { - document.documentElement.requestFullscreen(); - } else if (document.exitFullscreen) { - document.exitFullscreen(); - } -} -``` - -This starts by looking at the value of the `fullscreenElement` attribute on the {{DOMxRef("document")}}. If it's `null`, the document is currently in windowed mode, so we need to switch to fullscreen mode. Switching to fullscreen mode is done by calling {{DOMxRef("Element.requestFullscreen()")}}. +The [mdn/dom-examples GitHub repo](https://github.com/mdn/) has a complete example of the Fullscreen API. -If fullscreen mode is already active (`fullscreenElement` is non-`null`), we call {{DOMxRef("document.exitFullscreen()")}}. +[Run the example](https://mdn.github.io/dom-examples/fullscreen-api/index.html) and [browse the source code](https://github.com/mdn/dom-examples/tree/main/fullscreen-api). ## Specifications @@ -125,4 +97,4 @@ If fullscreen mode is already active (`fullscreenElement` is non-`null`), we cal - {{DOMxRef("Document.fullscreen")}} - {{DOMxRef("Document.fullscreenElement")}} - {{CSSxRef(":fullscreen")}}, {{CSSxRef("::backdrop")}} -- [`allowfullscreen`](/en-US/docs/Web/HTML/Element/iframe#allowfullscreen) +- [`allowfullscreen`](/en-US/docs/Web/HTML/Reference/Elements/iframe#allowfullscreen) diff --git a/files/en-us/web/api/fullscreen_api/index.md b/files/en-us/web/api/fullscreen_api/index.md index 293d016c6f5b0ad..88be72d26d6df6a 100644 --- a/files/en-us/web/api/fullscreen_api/index.md +++ b/files/en-us/web/api/fullscreen_api/index.md @@ -59,7 +59,7 @@ The Fullscreen API adds methods to the {{DOMxRef("Document")}} and {{DOMxRef("El ## Controlling access -The availability of fullscreen mode can be controlled using a [Permissions Policy](/en-US/docs/Web/HTTP/Permissions_Policy). The fullscreen mode feature is identified by the string `"fullscreen"`, with a default allowlist value of `"self"`, meaning that fullscreen mode is permitted in top-level document contexts, as well as to nested browsing contexts loaded from the same origin as the top-most document. +The availability of fullscreen mode can be controlled using a [Permissions Policy](/en-US/docs/Web/HTTP/Guides/Permissions_Policy). The fullscreen mode feature is identified by the string `"fullscreen"`, with a default allowlist value of `"self"`, meaning that fullscreen mode is permitted in top-level document contexts, as well as to nested browsing contexts loaded from the same origin as the top-most document. ## Usage notes @@ -81,15 +81,14 @@ In this example, a video is presented in a web page. Pressing the <kbd>Enter</kb When the page is loaded, this code is run to set up an event listener to watch for the <kbd>Enter</kbd> key. ```js -document.addEventListener( - "keydown", - (e) => { - if (e.key === "Enter") { - toggleFullScreen(); - } - }, - false, -); +const video = document.getElementById("video"); + +// On pressing ENTER call toggleFullScreen method +document.addEventListener("keydown", (e) => { + if (e.key === "Enter") { + toggleFullScreen(video); + } +}); ``` #### Toggling fullscreen mode @@ -97,16 +96,19 @@ document.addEventListener( This code is called by the event handler above when the user hits the <kbd>Enter</kbd> key. ```js -function toggleFullScreen() { +function toggleFullScreen(video) { if (!document.fullscreenElement) { - document.documentElement.requestFullscreen(); - } else if (document.exitFullscreen) { - document.exitFullscreen(); + // If the document is not in full screen mode + // make the video full screen + video.requestFullscreen(); + } else { + // Otherwise exit the full screen + document.exitFullscreen?.(); } } ``` -This starts by looking at the value of the {{DOMxRef("Document", "document")}}'s `fullscreenElement` attribute. In a real-world deployment, at this time, you'll want to check for prefixed versions of this (`mozFullScreenElement`, `msFullscreenElement`, or `webkitFullscreenElement`, for example). If the value is `null`, the document is currently in windowed mode, so we need to switch to fullscreen mode; otherwise, it's the element that's currently in fullscreen mode. Switching to fullscreen mode is done by calling {{DOMxRef("Element.requestFullscreen()")}} on the {{HTMLElement("video")}} element. +This starts by looking at the value of the {{DOMxRef("Document", "document")}}'s `fullscreenElement` attribute. If the value is `null`, the document is currently in windowed mode, so we need to switch to fullscreen mode; otherwise, it's the element that's currently in fullscreen mode. Switching to fullscreen mode is done by calling {{DOMxRef("Element.requestFullscreen()")}} on the {{HTMLElement("video")}} element. If fullscreen mode is already active (`fullscreenElement` is not `null`), we call {{DOMxRef("Document.exitFullscreen", "exitFullscreen()")}} on the `document` to shut off fullscreen mode. @@ -125,4 +127,4 @@ If fullscreen mode is already active (`fullscreenElement` is not `null`), we cal - {{DOMxRef("Document.fullscreen")}} - {{DOMxRef("Document.fullscreenElement")}} - {{CSSxRef(":fullscreen")}}, {{CSSxRef("::backdrop")}} -- [`allowfullscreen`](/en-US/docs/Web/HTML/Element/iframe#allowfullscreen) +- [`allowfullscreen`](/en-US/docs/Web/HTML/Reference/Elements/iframe#allowfullscreen) diff --git a/files/en-us/web/api/gainnode/gainnode/index.md b/files/en-us/web/api/gainnode/gainnode/index.md index 4dff5d3e2e7e4a8..3e8acc4d00e6ecb 100644 --- a/files/en-us/web/api/gainnode/gainnode/index.md +++ b/files/en-us/web/api/gainnode/gainnode/index.md @@ -21,7 +21,7 @@ new GainNode(context, options) ### Parameters - `context` - - : A reference to a {{domxref("BaseAudioContext")}}, e.g. an {{domxref("AudioContext")}}. + - : A reference to a {{domxref("BaseAudioContext")}}, e.g., an {{domxref("AudioContext")}}. - `options` {{optional_inline}} - : Options are as follows: diff --git a/files/en-us/web/api/gamepad/axes/index.md b/files/en-us/web/api/gamepad/axes/index.md index 89cbaa6350c4f09..a627828d312aec7 100644 --- a/files/en-us/web/api/gamepad/axes/index.md +++ b/files/en-us/web/api/gamepad/axes/index.md @@ -10,7 +10,7 @@ browser-compat: api.Gamepad.axes The **`Gamepad.axes`** property of the {{domxref("Gamepad") }} interface returns an array representing the controls with axes present on the device -(e.g. analog thumb sticks). +(e.g., analog thumb sticks). Each entry in the array is a floating point value in the range -1.0 – 1.0, representing the axis position from the lowest value (-1.0) to the highest value (1.0). diff --git a/files/en-us/web/api/gamepad/buttons/index.md b/files/en-us/web/api/gamepad/buttons/index.md index 16f070b829da850..54dbb2b3f9fe39c 100644 --- a/files/en-us/web/api/gamepad/buttons/index.md +++ b/files/en-us/web/api/gamepad/buttons/index.md @@ -8,23 +8,13 @@ browser-compat: api.Gamepad.buttons {{APIRef("Gamepad API")}}{{SecureContext_Header}} -The **`buttons`** property of the {{domxref("Gamepad")}} interface returns an array of {{domxref("gamepadButton")}} objects representing the buttons present on the device. +The **`buttons`** property of the {{domxref("Gamepad")}} interface returns an array of {{domxref("GamepadButton")}} objects representing the buttons present on the device. Each entry in the array is `0` if the button is not pressed, and non-zero (typically `1.0`) if the button is pressed. -Each {{domxref("gamepadButton")}} object has two properties: - -- `pressed` - - - : A boolean indicating whether the button is currently pressed (`true`) or unpressed (`false`). - -- `value` - - - : A floating point value used to enable representing analog buttons, such as the triggers on many modern gamepads. The values are normalized to the range 0.0 – 1.0, with 0.0 representing a button that is not pressed, and 1.0 representing a button that is fully pressed. - ## Value -An array of {{domxref("gamepadButton")}} objects. +An array of {{domxref("GamepadButton")}} objects. ## Examples diff --git a/files/en-us/web/api/gamepad/index.md b/files/en-us/web/api/gamepad/index.md index 8b1a926b44d6b00..a7868e5a93b3f43 100644 --- a/files/en-us/web/api/gamepad/index.md +++ b/files/en-us/web/api/gamepad/index.md @@ -17,7 +17,7 @@ A Gamepad object can be returned in one of two ways: via the `gamepad` property ## Instance properties - {{domxref("Gamepad.axes")}} {{ReadOnlyInline}} - - : An array representing the controls with axes present on the device (e.g. analog thumb sticks). + - : An array representing the controls with axes present on the device (e.g., analog thumb sticks). - {{domxref("Gamepad.buttons")}} {{ReadOnlyInline}} - : An array of {{domxref("gamepadButton")}} objects representing the buttons present on the device. - {{domxref("Gamepad.connected")}} {{ReadOnlyInline}} @@ -37,7 +37,7 @@ A Gamepad object can be returned in one of two ways: via the `gamepad` property - {{domxref("Gamepad.mapping")}} {{ReadOnlyInline}} - : A string indicating whether the browser has remapped the controls on the device to a known layout. - {{domxref("Gamepad.pose")}} {{ReadOnlyInline}} {{Experimental_Inline}} - - : A {{domxref("GamepadPose")}} object representing the pose information associated with a WebVR controller (e.g. its position and orientation in 3D space). + - : A {{domxref("GamepadPose")}} object representing the pose information associated with a WebVR controller (e.g., its position and orientation in 3D space). - {{domxref("Gamepad.timestamp")}} {{ReadOnlyInline}} - : A {{domxref("DOMHighResTimeStamp")}} representing the last time the data for this gamepad was updated. diff --git a/files/en-us/web/api/gamepad/pose/index.md b/files/en-us/web/api/gamepad/pose/index.md index cb3ccf518b093d6..035df81813039f9 100644 --- a/files/en-us/web/api/gamepad/pose/index.md +++ b/files/en-us/web/api/gamepad/pose/index.md @@ -10,7 +10,7 @@ browser-compat: api.Gamepad.pose {{APIRef("Gamepad")}}{{SeeCompatTable}}{{SecureContext_Header}} -The **`pose`** read-only property of the {{domxref("Gamepad")}} interface returns a {{domxref("GamepadPose")}} object representing the pose information associated with a WebVR controller (e.g. its position and orientation in 3D space). +The **`pose`** read-only property of the {{domxref("Gamepad")}} interface returns a {{domxref("GamepadPose")}} object representing the pose information associated with a WebVR controller (e.g., its position and orientation in 3D space). ## Value diff --git a/files/en-us/web/api/gamepad_api/index.md b/files/en-us/web/api/gamepad_api/index.md index 5d01a61447b694b..5fd81b361e834d8 100644 --- a/files/en-us/web/api/gamepad_api/index.md +++ b/files/en-us/web/api/gamepad_api/index.md @@ -23,7 +23,7 @@ The **Gamepad API** is a way for developers to access and respond to signals fro - [`GamepadHapticActuator`](/en-US/docs/Web/API/GamepadHapticActuator) - : Represents hardware in the controller designed to provide haptic feedback to the user (if available), most commonly vibration hardware. - [`GamepadPose`](/en-US/docs/Web/API/GamepadPose) - - : Represents the pose of a controller (e.g. position and orientation in 3D space) in the case of a [WebVR](/en-US/docs/Web/API/WebVR_API) controller. This is _not_ used by the newer [WebXR](/en-US/docs/Web/API/WebXR_Device_API) standard. + - : Represents the pose of a controller (e.g., position and orientation in 3D space) in the case of a [WebVR](/en-US/docs/Web/API/WebVR_API) controller. This is _not_ used by the newer [WebXR](/en-US/docs/Web/API/WebXR_Device_API) standard. ### Extensions to other interfaces diff --git a/files/en-us/web/api/gamepad_api/using_the_gamepad_api/index.md b/files/en-us/web/api/gamepad_api/using_the_gamepad_api/index.md index 7863b826314690e..1456db729f6dceb 100644 --- a/files/en-us/web/api/gamepad_api/using_the_gamepad_api/index.md +++ b/files/en-us/web/api/gamepad_api/using_the_gamepad_api/index.md @@ -36,7 +36,7 @@ Each gamepad has a unique ID associated with it, which is available on the event ## Disconnecting a gamepad -When a gamepad is disconnected, and if a page has previously received data for that gamepad (e.g. {{ domxref("Window/gamepadconnected_event", "gamepadconnected") }}), a second event is dispatched to the focused window, {{domxref("Window.gamepaddisconnected_event", "gamepaddisconnected")}}: +When a gamepad is disconnected, and if a page has previously received data for that gamepad (e.g., {{ domxref("Window/gamepadconnected_event", "gamepadconnected") }}), a second event is dispatched to the focused window, {{domxref("Window.gamepaddisconnected_event", "gamepaddisconnected")}}: ```js window.addEventListener("gamepaddisconnected", (e) => { @@ -115,7 +115,7 @@ The {{ domxref("Gamepad") }} object's properties are as follows: - The `pressed` property is a boolean indicating whether the button is currently pressed (`true`) or unpressed (`false`). - The `value` property is a floating point value used to enable representing analog buttons, such as the triggers on many modern gamepads. The values are normalized to the range 0.0..1.0, with 0.0 representing a button that is not pressed, and 1.0 representing a button that is fully pressed. -- `axes`: An array representing the controls with axes present on the device (e.g. analog thumb sticks). Each entry in the array is a floating point value in the range -1.0 - 1.0, representing the axis position from the lowest value (-1.0) to the highest value (1.0). +- `axes`: An array representing the controls with axes present on the device (e.g., analog thumb sticks). Each entry in the array is a floating point value in the range -1.0 - 1.0, representing the axis position from the lowest value (-1.0) to the highest value (1.0). - `timestamp`: This returns a {{ domxref("DOMHighResTimeStamp") }} representing the last time the data for this gamepad was updated, allowing developers to determine if the `axes` and `button` data have been updated from the hardware. The value must be relative to the `navigationStart` attribute of the {{ domxref("PerformanceTiming") }} interface. Values are monotonically increasing, meaning that they can be compared to determine the ordering of updates, as newer values will always be greater than or equal to older values. Note that this property is not currently supported in Firefox. > [!NOTE] diff --git a/files/en-us/web/api/geolocation/getcurrentposition/index.md b/files/en-us/web/api/geolocation/getcurrentposition/index.md index 94ae0d810e6a389..2f06ab0444d6211 100644 --- a/files/en-us/web/api/geolocation/getcurrentposition/index.md +++ b/files/en-us/web/api/geolocation/getcurrentposition/index.md @@ -10,7 +10,7 @@ browser-compat: api.Geolocation.getCurrentPosition The **`getCurrentPosition()`** method of the {{domxref("Geolocation")}} interface is used to get the current position of the device. -Note that in addition to requiring a secure context this feature may be blocked by the [`geolocation`](/en-US/docs/Web/HTTP/Headers/Permissions-Policy/geolocation) `Permissions-Policy`, and also requires that explicit permission be granted by the user. +Note that in addition to requiring a secure context this feature may be blocked by the [`geolocation`](/en-US/docs/Web/HTTP/Reference/Headers/Permissions-Policy/geolocation) `Permissions-Policy`, and also requires that explicit permission be granted by the user. If required, the user will be prompted when this method is called. The permission state can be queried using the `geolocation` user permission in the [Permissions API](/en-US/docs/Web/API/Permissions_API). diff --git a/files/en-us/web/api/geolocation/watchposition/index.md b/files/en-us/web/api/geolocation/watchposition/index.md index dfe21f94cc03db6..2a3d990f8888347 100644 --- a/files/en-us/web/api/geolocation/watchposition/index.md +++ b/files/en-us/web/api/geolocation/watchposition/index.md @@ -11,7 +11,7 @@ browser-compat: api.Geolocation.watchPosition The **`watchPosition()`** method of the {{domxref("Geolocation")}} interface is used to register a handler function that will be called automatically each time the position of the device changes. You can also, optionally, specify an error handling callback function. -Note that in addition to requiring a secure context this feature may be blocked by the [`geolocation`](/en-US/docs/Web/HTTP/Headers/Permissions-Policy/geolocation) `Permissions-Policy`, and also requires that explicit permission be granted by the user. +Note that in addition to requiring a secure context this feature may be blocked by the [`geolocation`](/en-US/docs/Web/HTTP/Reference/Headers/Permissions-Policy/geolocation) `Permissions-Policy`, and also requires that explicit permission be granted by the user. If required, the user will be prompted when this method is called. The permission state can be queried using the `geolocation` user permission in the [Permissions API](/en-US/docs/Web/API/Permissions_API). diff --git a/files/en-us/web/api/geolocation_api/index.md b/files/en-us/web/api/geolocation_api/index.md index a8d9b78e53b0a8d..f02bc045fedb59f 100644 --- a/files/en-us/web/api/geolocation_api/index.md +++ b/files/en-us/web/api/geolocation_api/index.md @@ -50,7 +50,7 @@ For further information on Geolocation usage, read [Using the Geolocation API](/ The Geolocation API allows users to programmatically access location information in [secure contexts](/en-US/docs/Web/Security/Secure_Contexts). -Access may further be controlled by the [Permissions Policy](/en-US/docs/Web/HTTP/Permissions_Policy) directive {{HTTPHeader("Permissions-Policy/geolocation","geolocation")}}. +Access may further be controlled by the [Permissions Policy](/en-US/docs/Web/HTTP/Guides/Permissions_Policy) directive {{HTTPHeader("Permissions-Policy/geolocation","geolocation")}}. The default allowlist for `geolocation` is `self`, which allows access to location information in same-origin nested frames only. Third party usage is enabled by setting a `Permissions-Policy` response header to grant permission to a particular third party origin: @@ -61,7 +61,7 @@ Permissions-Policy: geolocation=(self b.example.com) The `allow="geolocation"` attribute must then be added to the iframe element with sources from that origin: ```html -<iframe src="https://b.example.com" allow="geolocation"/></iframe> +<iframe src="https://b.example.com" allow="geolocation"></iframe> ``` Geolocation data may reveal information that the device owner does not want to share. @@ -88,5 +88,4 @@ As Wi-Fi-based locating is often provided by Google, the vanilla Geolocation API ## See also - [Using the Geolocation API](/en-US/docs/Web/API/Geolocation_API/Using_the_Geolocation_API) -- [Geolocation API on w3.org](https://www.w3.org/TR/geolocation/) - [Who moved my geolocation?](https://hacks.mozilla.org/2013/10/who-moved-my-geolocation/) (Hacks blog) diff --git a/files/en-us/web/api/geolocationpositionerror/index.md b/files/en-us/web/api/geolocationpositionerror/index.md index c6a4f944d68d3d7..4c9d1e8b1ad5fcd 100644 --- a/files/en-us/web/api/geolocationpositionerror/index.md +++ b/files/en-us/web/api/geolocationpositionerror/index.md @@ -17,11 +17,11 @@ _The `GeolocationPositionError` interface doesn't inherit any property._ - : Returns an `unsigned short` representing the error code. The following values are possible: - | Value | Associated constant | Description | - | ----- | ---------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | - | `1` | `PERMISSION_DENIED` | The acquisition of the geolocation information failed because the page didn't have the necessary permissions, for example because it is blocked by a [Permissions Policy](/en-US/docs/Web/HTTP/Permissions_Policy) | - | `2` | `POSITION_UNAVAILABLE` | The acquisition of the geolocation failed because at least one internal source of position returned an internal error. | - | `3` | `TIMEOUT` | The time allowed to acquire the geolocation was reached before the information was obtained. | + | Value | Associated constant | Description | + | ----- | ---------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | + | `1` | `PERMISSION_DENIED` | The acquisition of the geolocation information failed because the page didn't have the necessary permissions, for example because it is blocked by a [Permissions Policy](/en-US/docs/Web/HTTP/Guides/Permissions_Policy) | + | `2` | `POSITION_UNAVAILABLE` | The acquisition of the geolocation failed because at least one internal source of position returned an internal error. | + | `3` | `TIMEOUT` | The time allowed to acquire the geolocation was reached before the information was obtained. | - {{domxref("GeolocationPositionError.message")}} {{ReadOnlyInline}} - : Returns a human-readable string describing the details of the error. Specifications note that this is primarily intended for debugging use and not to be shown directly in a user interface. diff --git a/files/en-us/web/api/gpu/getpreferredcanvasformat/index.md b/files/en-us/web/api/gpu/getpreferredcanvasformat/index.md index b42a5ea9af065f2..14afcbbe7646786 100644 --- a/files/en-us/web/api/gpu/getpreferredcanvasformat/index.md +++ b/files/en-us/web/api/gpu/getpreferredcanvasformat/index.md @@ -40,7 +40,7 @@ const canvas = document.querySelector("#gpuCanvas"); const context = canvas.getContext("webgpu"); context.configure({ - device: device, + device, format: navigator.gpu.getPreferredCanvasFormat(), alphaMode: "premultiplied", }); diff --git a/files/en-us/web/api/gpu/index.md b/files/en-us/web/api/gpu/index.md index b5bf883c4e56183..b6e3d841dd9bcf7 100644 --- a/files/en-us/web/api/gpu/index.md +++ b/files/en-us/web/api/gpu/index.md @@ -44,7 +44,7 @@ async function init() { const device = await adapter.requestDevice(); - //... + // … } ``` @@ -55,7 +55,7 @@ const canvas = document.querySelector("#gpuCanvas"); const context = canvas.getContext("webgpu"); context.configure({ - device: device, + device, format: navigator.gpu.getPreferredCanvasFormat(), alphaMode: "premultiplied", }); diff --git a/files/en-us/web/api/gpu/requestadapter/index.md b/files/en-us/web/api/gpu/requestadapter/index.md index cc8be5d7e70d57d..2d4a924095f70cf 100644 --- a/files/en-us/web/api/gpu/requestadapter/index.md +++ b/files/en-us/web/api/gpu/requestadapter/index.md @@ -75,7 +75,7 @@ async function init() { const device = await adapter.requestDevice(); - //... + // … } ``` diff --git a/files/en-us/web/api/gpu/wgsllanguagefeatures/index.md b/files/en-us/web/api/gpu/wgsllanguagefeatures/index.md index 416bb27410c38cf..46f534bf643f484 100644 --- a/files/en-us/web/api/gpu/wgsllanguagefeatures/index.md +++ b/files/en-us/web/api/gpu/wgsllanguagefeatures/index.md @@ -38,7 +38,7 @@ for (const value of valueIterator) { console.log(value); } -// ... +// … ``` ## Specifications diff --git a/files/en-us/web/api/gpuadapter/features/index.md b/files/en-us/web/api/gpuadapter/features/index.md index 57cb6849476c1a8..a403557d1f35e25 100644 --- a/files/en-us/web/api/gpuadapter/features/index.md +++ b/files/en-us/web/api/gpuadapter/features/index.md @@ -49,7 +49,7 @@ async function init() { requiredFeatures, }); - // ... + // … } ``` diff --git a/files/en-us/web/api/gpuadapter/index.md b/files/en-us/web/api/gpuadapter/index.md index 7f5c4284c5400c1..9dea4d8aa1333d0 100644 --- a/files/en-us/web/api/gpuadapter/index.md +++ b/files/en-us/web/api/gpuadapter/index.md @@ -48,7 +48,7 @@ async function init() { const device = await adapter.requestDevice(); - //... + // … } ``` diff --git a/files/en-us/web/api/gpuadapter/info/index.md b/files/en-us/web/api/gpuadapter/info/index.md index 0dc3a7eb01eb289..dbdb5563b7e8a09 100644 --- a/files/en-us/web/api/gpuadapter/info/index.md +++ b/files/en-us/web/api/gpuadapter/info/index.md @@ -13,14 +13,14 @@ browser-compat: api.GPUAdapter.info The **`info`** read-only property of the {{domxref("GPUAdapter")}} interface returns a {{domxref("GPUAdapterInfo")}} object containing identifying information about the adapter. -The intention behind this property is to allow developers to request specific details about the user's GPU so that they can preemptively apply workarounds for GPU-specific bugs, or provide different codepaths to better suit different GPU architectures. Providing such information does present a security risk — it could be used for fingerprinting — therefore the information shared is to be kept at a minimum, and different browser vendors are likely to share different information types and granularities. - ## Value A {{domxref("GPUAdapterInfo")}} object instance. ## Examples +### Basic info usage + ```js const adapter = await navigator.gpu.requestAdapter(); if (!adapter) { diff --git a/files/en-us/web/api/gpuadapter/isfallbackadapter/index.md b/files/en-us/web/api/gpuadapter/isfallbackadapter/index.md index 32690a41bf48d76..8f5a4ec2c027090 100644 --- a/files/en-us/web/api/gpuadapter/isfallbackadapter/index.md +++ b/files/en-us/web/api/gpuadapter/isfallbackadapter/index.md @@ -22,19 +22,19 @@ A boolean. ```js async function init() { if (!navigator.gpu) { - throw Error('WebGPU not supported.'); + throw Error("WebGPU not supported."); } const adapter = await navigator.gpu.requestAdapter(); if (!adapter) { - throw Error('Couldn\'t request WebGPU adapter.'); + throw Error("Couldn't request WebGPU adapter."); } const fallback = adapter.isFallbackAdapter; console.log(fallback); - // ... - + // … +} ``` ## Specifications diff --git a/files/en-us/web/api/gpuadapter/limits/index.md b/files/en-us/web/api/gpuadapter/limits/index.md index d9cdc64d9aa7bec..085436850dd99d0 100644 --- a/files/en-us/web/api/gpuadapter/limits/index.md +++ b/files/en-us/web/api/gpuadapter/limits/index.md @@ -47,7 +47,7 @@ async function init() { requiredLimits, }); - // ... + // … } ``` diff --git a/files/en-us/web/api/gpuadapter/requestadapterinfo/index.md b/files/en-us/web/api/gpuadapter/requestadapterinfo/index.md index 4fcbd881bf58c27..4378741982725e8 100644 --- a/files/en-us/web/api/gpuadapter/requestadapterinfo/index.md +++ b/files/en-us/web/api/gpuadapter/requestadapterinfo/index.md @@ -47,7 +47,7 @@ async function init() { console.log(adapterInfo.vendor); console.log(adapterInfo.architecture); - // ... + // … } ``` diff --git a/files/en-us/web/api/gpuadapter/requestdevice/index.md b/files/en-us/web/api/gpuadapter/requestdevice/index.md index 1a79479abf786d6..3868158d57d0e94 100644 --- a/files/en-us/web/api/gpuadapter/requestdevice/index.md +++ b/files/en-us/web/api/gpuadapter/requestdevice/index.md @@ -31,16 +31,17 @@ requestDevice(descriptor) - `requiredFeatures` {{optional_inline}} - : An array of strings representing additional functionality that you want supported by the returned {{domxref("GPUDevice")}}. The `requestDevice()` call will fail if the `GPUAdapter` cannot provide these features. See {{domxref("GPUSupportedFeatures")}} for a full list of possible features. This defaults to an empty array if no value is provided. - `requiredLimits` {{optional_inline}} - - : An object containing properties representing the limits that you want supported by the returned {{domxref("GPUDevice")}}. The `requestDevice()` call will fail if the `GPUAdapter` cannot provide these limits. Each key must be the name of a member of {{domxref("GPUSupportedLimits")}}. This defaults to an empty object if no value is provided. + - : An object containing properties representing the limits that you want supported by the returned {{domxref("GPUDevice")}}. The `requestDevice()` call will fail if the `GPUAdapter` cannot provide these limits. Each key with a non-`undefined` value must be the name of a member of {{domxref("GPUSupportedLimits")}}. + > [!NOTE] + > You can request unknown limits when requesting a GPU device without causing an error. Such limits will be `undefined`. This is useful because it makes WebGPU code less brittle — a codebase won't stop working because a limit no longer exists in the adapter. -> [!NOTE] -> Not all features and limits will be available to WebGPU in all browsers that support it, even if they are supported by the underlying hardware. See the {{domxref("GPUAdapter.features", "features")}} and {{domxref("GPUAdapter.limits", "limits")}} pages for more information. +Not all features and limits will be available to WebGPU in all browsers that support it, even if they are supported by the underlying hardware. See the {{domxref("GPUAdapter.features", "features")}} and {{domxref("GPUAdapter.limits", "limits")}} pages for more information. ### Return value A {{jsxref("Promise")}} that fulfills with a {{domxref("GPUDevice")}} object instance. -If you make a duplicate call, i.e. call `requestDevice()` on a {{domxref("GPUAdapter")}} that `requestDevice()` was already called on, the promise fulfills with a device that is immediately lost. You can then get information on how the device was lost via {{domxref("GPUDevice.lost")}}. +If you make a duplicate call, i.e., call `requestDevice()` on a {{domxref("GPUAdapter")}} that `requestDevice()` was already called on, the promise fulfills with a device that is immediately lost. You can then get information on how the device was lost via {{domxref("GPUDevice.lost")}}. ### Exceptions @@ -66,7 +67,7 @@ async function init() { const device = await adapter.requestDevice(); - // ... + // … } ``` @@ -110,7 +111,7 @@ async function init() { requiredLimits, }); - // ... + // … } ``` diff --git a/files/en-us/web/api/gpuadapterinfo/index.md b/files/en-us/web/api/gpuadapterinfo/index.md index 6daa7e6cf1f69c2..ebea9bf83f7dd1c 100644 --- a/files/en-us/web/api/gpuadapterinfo/index.md +++ b/files/en-us/web/api/gpuadapterinfo/index.md @@ -11,7 +11,9 @@ browser-compat: api.GPUAdapterInfo The **`GPUAdapterInfo`** interface of the {{domxref("WebGPU API", "WebGPU API", "", "nocode")}} contains identifying information about a {{domxref("GPUAdapter")}}. -A `GPUAdapterInfo` object instance is retrieved using the {{domxref("GPUAdapter.info")}} property. +An adapter's `GPUAdapterInfo` can be retrieved using the {{domxref("GPUAdapter.info")}} property of the adapter itself, or the {{domxref("GPUDevice.adapterInfo")}} property of a device that originated from the adapter. + +This object allows developers to access specific details about the user's GPU so that they can preemptively apply workarounds for GPU-specific bugs, or provide different codepaths to better suit different GPU architectures. Providing such information does present a security risk — it could be used for fingerprinting — therefore the information shared is kept at a minimum, and different browser vendors are likely to share different information types and granularities. {{InheritanceDiagram}} @@ -25,9 +27,15 @@ A `GPUAdapterInfo` object instance is retrieved using the {{domxref("GPUAdapter. - : A vendor-specific identifier for the adapter. Returns an empty string if it is not available. - {{domxref("GPUAdapterInfo.vendor", "vendor")}} {{Experimental_Inline}} {{ReadOnlyInline}} - : The name of the adapter vendor. Returns an empty string if it is not available. +- {{domxref("GPUAdapterInfo.subgroupMaxSize", "subgroupMaxSize")}} {{Experimental_Inline}} {{ReadOnlyInline}} + - : The maximum supported [subgroup size](https://gpuweb.github.io/gpuweb/wgsl/#subgroup-size) for the {{domxref("GPUAdapter")}}. +- {{domxref("GPUAdapterInfo.subgroupMinSize", "subgroupMinSize")}} {{Experimental_Inline}} {{ReadOnlyInline}} + - : The minimum supported [subgroup size](https://gpuweb.github.io/gpuweb/wgsl/#subgroup-size) for the {{domxref("GPUAdapter")}}. ## Examples +### Access GPUAdapterInfo via GPUAdapter.info + ```js const adapter = await navigator.gpu.requestAdapter(); if (!adapter) { @@ -39,6 +47,27 @@ console.log(adapterInfo.vendor); console.log(adapterInfo.architecture); ``` +### Access GPUAdapterInfo via GPUDevice.adapterInfo + +```js +const adapter = await navigator.gpu.requestAdapter(); +if (!adapter) { + throw Error("Couldn't request WebGPU adapter."); +} + +const myDevice = await adapter.requestDevice(); + +function optimizeForGpuDevice(device) { + if (device.adapterInfo.vendor === "amd") { + // Use AMD-specific optimizations + } else if (device.adapterInfo.architecture.includes("turing")) { + // Optimize for NVIDIA Turing architecture + } +} + +optimizeForGpuDevice(myDevice); +``` + ## Specifications {{Specifications}} diff --git a/files/en-us/web/api/gpuadapterinfo/subgroupmaxsize/index.md b/files/en-us/web/api/gpuadapterinfo/subgroupmaxsize/index.md new file mode 100644 index 000000000000000..664aa487601bb53 --- /dev/null +++ b/files/en-us/web/api/gpuadapterinfo/subgroupmaxsize/index.md @@ -0,0 +1,41 @@ +--- +title: "GPUAdapterInfo: subgroupMaxSize property" +short-title: subgroupMaxSize +slug: Web/API/GPUAdapterInfo/subgroupMaxSize +page-type: web-api-instance-property +status: + - experimental +browser-compat: api.GPUAdapterInfo.subgroupMaxSize +--- + +{{APIRef("WebGPU API")}}{{SeeCompatTable}}{{SecureContext_Header}}{{AvailableInWorkers}} + +The **`subgroupMaxSize`** read-only property of the {{domxref("GPUAdapterInfo")}} interface returns the maximum supported [subgroup size](https://gpuweb.github.io/gpuweb/wgsl/#subgroup-size) for the {{domxref("GPUAdapter")}}. This can be used along with the `subgroups` [feature](/en-US/docs/Web/API/GPUSupportedFeatures). + +## Value + +A number. + +## Examples + +```js +const adapter = await navigator.gpu.requestAdapter(); +if (!adapter) { + throw Error("Couldn't request WebGPU adapter."); +} + +const adapterInfo = adapter.info; +console.log(adapterInfo.subgroupMaxSize); +``` + +## Specifications + +{{Specifications}} + +## Browser compatibility + +{{Compat}} + +## See also + +- The [WebGPU API](/en-US/docs/Web/API/WebGPU_API) diff --git a/files/en-us/web/api/gpuadapterinfo/subgroupminsize/index.md b/files/en-us/web/api/gpuadapterinfo/subgroupminsize/index.md new file mode 100644 index 000000000000000..a81464ddd01632c --- /dev/null +++ b/files/en-us/web/api/gpuadapterinfo/subgroupminsize/index.md @@ -0,0 +1,41 @@ +--- +title: "GPUAdapterInfo: subgroupMinSize property" +short-title: subgroupMinSize +slug: Web/API/GPUAdapterInfo/subgroupMinSize +page-type: web-api-instance-property +status: + - experimental +browser-compat: api.GPUAdapterInfo.subgroupMinSize +--- + +{{APIRef("WebGPU API")}}{{SeeCompatTable}}{{SecureContext_Header}}{{AvailableInWorkers}} + +The **`subgroupMinSize`** read-only property of the {{domxref("GPUAdapterInfo")}} interface returns the minimum supported [subgroup size](https://gpuweb.github.io/gpuweb/wgsl/#subgroup-size) for the {{domxref("GPUAdapter")}}. This can be used along with the `subgroups` [feature](/en-US/docs/Web/API/GPUSupportedFeatures). + +## Value + +A number. + +## Examples + +```js +const adapter = await navigator.gpu.requestAdapter(); +if (!adapter) { + throw Error("Couldn't request WebGPU adapter."); +} + +const adapterInfo = adapter.info; +console.log(adapterInfo.subgroupMinSize); +``` + +## Specifications + +{{Specifications}} + +## Browser compatibility + +{{Compat}} + +## See also + +- The [WebGPU API](/en-US/docs/Web/API/WebGPU_API) diff --git a/files/en-us/web/api/gpubindgroup/index.md b/files/en-us/web/api/gpubindgroup/index.md index 1457fa1f254a2e4..557f653af75cc58 100644 --- a/files/en-us/web/api/gpubindgroup/index.md +++ b/files/en-us/web/api/gpubindgroup/index.md @@ -30,7 +30,7 @@ A `GPUBindGroup` object instance is created using the {{domxref("GPUDevice.creat Our [basic compute demo](https://mdn.github.io/dom-examples/webgpu-compute-demo/) shows an example of creating a bind group layout and then using that as a template when creating a bind group. ```js -// ... +// … const bindGroupLayout = device.createBindGroupLayout({ entries: [ @@ -56,7 +56,7 @@ const bindGroup = device.createBindGroup({ ], }); -// ... +// … ``` ## Specifications diff --git a/files/en-us/web/api/gpubindgroup/label/index.md b/files/en-us/web/api/gpubindgroup/label/index.md index 337e371c73ccbf6..28ac7e4bb6a8f9f 100644 --- a/files/en-us/web/api/gpubindgroup/label/index.md +++ b/files/en-us/web/api/gpubindgroup/label/index.md @@ -24,7 +24,7 @@ A string. If this has not been previously set as described above, it will be an Setting and getting a label via `GPUBindGroup.label`: ```js -// ... +// … const bindGroup = device.createBindGroup({ layout: bindGroupLayout, @@ -46,7 +46,7 @@ console.log(bindGroup.label); // "my_bind_group" Setting a label via the originating {{domxref("GPUDevice.createBindGroup()")}} call, and then getting it via `GPUBindGroup.label`: ```js -// ... +// … const bindGroup = device.createBindGroup({ layout: bindGroupLayout, diff --git a/files/en-us/web/api/gpubindgrouplayout/index.md b/files/en-us/web/api/gpubindgrouplayout/index.md index 92a726585b3b1a8..f99bf7be16d297d 100644 --- a/files/en-us/web/api/gpubindgrouplayout/index.md +++ b/files/en-us/web/api/gpubindgrouplayout/index.md @@ -30,7 +30,7 @@ A `GPUBindGroupLayout` object instance is created using the {{domxref("GPUDevice Our [basic compute demo](https://mdn.github.io/dom-examples/webgpu-compute-demo/) shows an example of creating a bind group layout and then using that as a template when creating a bind group. ```js -// ... +// … const bindGroupLayout = device.createBindGroupLayout({ entries: [ @@ -56,7 +56,7 @@ const bindGroup = device.createBindGroup({ ], }); -// ... +// … ``` ## Specifications diff --git a/files/en-us/web/api/gpubindgrouplayout/label/index.md b/files/en-us/web/api/gpubindgrouplayout/label/index.md index 5b750554aa0c085..0fee9cb61ec5eaf 100644 --- a/files/en-us/web/api/gpubindgrouplayout/label/index.md +++ b/files/en-us/web/api/gpubindgrouplayout/label/index.md @@ -24,7 +24,7 @@ A string. If this has not been previously set as described above, it will be an Setting and getting a label via `GPUBindGroupLayout.label`: ```js -// ... +// … const bindGroupLayout = device.createBindGroupLayout({ entries: [ @@ -46,7 +46,7 @@ console.log(bindGroupLayout.label); // "my_bind_group_layout" Setting a label via the originating {{domxref("GPUDevice.createBindGroupLayout()")}} call, and then getting it via `GPUBindGroupLayout.label`: ```js -// ... +// … const bindGroupLayout = device.createBindGroupLayout({ entries: [ diff --git a/files/en-us/web/api/gpubuffer/mapasync/index.md b/files/en-us/web/api/gpubuffer/mapasync/index.md index 5e090746e8dd545..5d9ad4f03e95438 100644 --- a/files/en-us/web/api/gpubuffer/mapasync/index.md +++ b/files/en-us/web/api/gpubuffer/mapasync/index.md @@ -34,13 +34,13 @@ mapAsync(mode, offset, size) - : The `GPUBuffer` is mapped for reading. Values can be read, but any changes made to the {{jsxref("ArrayBuffer")}} returned by {{domxref("GPUBuffer.getMappedRange()")}} will be discarded once {{domxref("GPUBuffer.unmap()")}} is called. - Read-mode mapping can only be used on `GPUBuffer`s that have a usage of `GPUBufferUsage.MAP_READ` set on them (i.e. when created with {{domxref("GPUDevice.createBuffer()")}}). + Read-mode mapping can only be used on `GPUBuffer`s that have a usage of `GPUBufferUsage.MAP_READ` set on them (i.e., when created with {{domxref("GPUDevice.createBuffer()")}}). - `GPUMapMode.WRITE` - : The `GPUBuffer` is mapped for writing. Values can be read and updated — any changes made to the {{jsxref("ArrayBuffer")}} returned by {{domxref("GPUBuffer.getMappedRange()")}} will be saved to the `GPUBuffer` once {{domxref("GPUBuffer.unmap()")}} is called. - Write-mode mapping can only be used on `GPUBuffer`s that have a usage of `GPUBufferUsage.MAP_WRITE` set on them (i.e. when created with {{domxref("GPUDevice.createBuffer()")}}). + Write-mode mapping can only be used on `GPUBuffer`s that have a usage of `GPUBufferUsage.MAP_WRITE` set on them (i.e., when created with {{domxref("GPUDevice.createBuffer()")}}). - `offset` {{optional_inline}} - : A number representing the offset, in bytes, from the start of the buffer to the start of the range to be mapped. If `offset` is omitted, it defaults to 0. diff --git a/files/en-us/web/api/gpubuffer/mapstate/index.md b/files/en-us/web/api/gpubuffer/mapstate/index.md index 3db8c2d25857e75..078bdee6715899b 100644 --- a/files/en-us/web/api/gpubuffer/mapstate/index.md +++ b/files/en-us/web/api/gpubuffer/mapstate/index.md @@ -36,7 +36,7 @@ const stagingBuffer = device.createBuffer({ console.log(stagingBuffer.mapState); // "unmapped" -// ... +// … await stagingBuffer.mapAsync( GPUMapMode.READ, diff --git a/files/en-us/web/api/gpubuffer/size/index.md b/files/en-us/web/api/gpubuffer/size/index.md index 1a2f1c0b94dbcef..ea9b8f76b312bc2 100644 --- a/files/en-us/web/api/gpubuffer/size/index.md +++ b/files/en-us/web/api/gpubuffer/size/index.md @@ -25,7 +25,7 @@ A number. // Define global buffer size const BUFFER_SIZE = 1000; -// ... +// … const output = device.createBuffer({ size: BUFFER_SIZE, diff --git a/files/en-us/web/api/gpucanvascontext/configure/index.md b/files/en-us/web/api/gpucanvascontext/configure/index.md index d94fad47349b70e..ca04477ab62156a 100644 --- a/files/en-us/web/api/gpucanvascontext/configure/index.md +++ b/files/en-us/web/api/gpucanvascontext/configure/index.md @@ -75,7 +75,7 @@ const canvas = document.querySelector("#gpuCanvas"); const context = canvas.getContext("webgpu"); context.configure({ - device: device, + device, format: navigator.gpu.getPreferredCanvasFormat(), alphaMode: "premultiplied", }); diff --git a/files/en-us/web/api/gpucanvascontext/getconfiguration/index.md b/files/en-us/web/api/gpucanvascontext/getconfiguration/index.md index 542ff0cb87a3402..b0f13d8a69ede69 100644 --- a/files/en-us/web/api/gpucanvascontext/getconfiguration/index.md +++ b/files/en-us/web/api/gpucanvascontext/getconfiguration/index.md @@ -45,7 +45,7 @@ if (!adapter) { const device = await adapter.requestDevice(); context.configure({ - device: device, + device, format: navigator.gpu.getPreferredCanvasFormat(), alphaMode: "premultiplied", }); diff --git a/files/en-us/web/api/gpucanvascontext/getcurrenttexture/index.md b/files/en-us/web/api/gpucanvascontext/getcurrenttexture/index.md index 2e9f2437dd0a5f8..d4f9f881f5cb56d 100644 --- a/files/en-us/web/api/gpucanvascontext/getcurrenttexture/index.md +++ b/files/en-us/web/api/gpucanvascontext/getcurrenttexture/index.md @@ -30,7 +30,7 @@ A {{domxref("GPUTexture")}} object instance. ### Exceptions - `InvalidStateError` {{domxref("DOMException")}} - - : Thrown if `getCurrentTexture()` is called on the canvas context before it is configured (i.e. before {{domxref("GPUCanvasContext.configure()")}} has been called). + - : Thrown if `getCurrentTexture()` is called on the canvas context before it is configured (i.e., before {{domxref("GPUCanvasContext.configure()")}} has been called). ## Examples @@ -39,12 +39,12 @@ const canvas = document.querySelector("#gpuCanvas"); const context = canvas.getContext("webgpu"); context.configure({ - device: device, + device, format: navigator.gpu.getPreferredCanvasFormat(), alphaMode: "premultiplied", }); -//... +// … // Later on const commandEncoder = device.createCommandEncoder(); diff --git a/files/en-us/web/api/gpucanvascontext/index.md b/files/en-us/web/api/gpucanvascontext/index.md index bc2c0ad8b46a2cc..88bd306cefc50db 100644 --- a/files/en-us/web/api/gpucanvascontext/index.md +++ b/files/en-us/web/api/gpucanvascontext/index.md @@ -36,7 +36,7 @@ const canvas = document.querySelector("#gpuCanvas"); const context = canvas.getContext("webgpu"); context.configure({ - device: device, + device, format: navigator.gpu.getPreferredCanvasFormat(), alphaMode: "premultiplied", }); diff --git a/files/en-us/web/api/gpucanvascontext/unconfigure/index.md b/files/en-us/web/api/gpucanvascontext/unconfigure/index.md index 8c0b9a8e8e74029..b7baaed34959a38 100644 --- a/files/en-us/web/api/gpucanvascontext/unconfigure/index.md +++ b/files/en-us/web/api/gpucanvascontext/unconfigure/index.md @@ -34,7 +34,7 @@ const canvas = document.querySelector("#gpuCanvas"); const context = canvas.getContext("webgpu"); context.configure({ - device: device, + device, format: navigator.gpu.getPreferredCanvasFormat(), alphaMode: "premultiplied", }); diff --git a/files/en-us/web/api/gpucommandbuffer/index.md b/files/en-us/web/api/gpucommandbuffer/index.md index 6a965f791aa9bd8..d7bc7e731ee144a 100644 --- a/files/en-us/web/api/gpucommandbuffer/index.md +++ b/files/en-us/web/api/gpucommandbuffer/index.md @@ -26,7 +26,7 @@ A `GPUCommandBuffer` is created via the {{domxref("GPUCommandEncoder.finish()")} ## Examples ```js -// ... +// … const commandBuffer = commandEncoder.finish(); device.queue.submit([commandBuffer]); diff --git a/files/en-us/web/api/gpucommandencoder/begincomputepass/index.md b/files/en-us/web/api/gpucommandencoder/begincomputepass/index.md index 73c3f33c326abb3..54ffa9abd1729ff 100644 --- a/files/en-us/web/api/gpucommandencoder/begincomputepass/index.md +++ b/files/en-us/web/api/gpucommandencoder/begincomputepass/index.md @@ -58,7 +58,7 @@ The following criteria must be met when calling **`beginComputePass()`**, otherw In our [basic compute demo](https://mdn.github.io/dom-examples/webgpu-compute-demo/), several commands are recorded via a {{domxref("GPUCommandEncoder")}}. Most of these commands originate from the {{domxref("GPUComputePassEncoder")}} created via `beginComputePass()`. ```js -// ... +// … // Create GPUCommandEncoder to encode commands to issue to the GPU const commandEncoder = device.createCommandEncoder(); @@ -86,7 +86,7 @@ commandEncoder.copyBufferToBuffer( // End frame by passing array of command buffers to command queue for execution device.queue.submit([commandEncoder.finish()]); -// ... +// … ``` ## Specifications diff --git a/files/en-us/web/api/gpucommandencoder/beginrenderpass/index.md b/files/en-us/web/api/gpucommandencoder/beginrenderpass/index.md index b24300859b9fb17..e1319fe035b6b40 100644 --- a/files/en-us/web/api/gpucommandencoder/beginrenderpass/index.md +++ b/files/en-us/web/api/gpucommandencoder/beginrenderpass/index.md @@ -56,24 +56,9 @@ Color attachment objects can have the following properties: - : A color value to clear the `view` texture to, prior to executing the render pass. This value is ignored if `loadOp` is not set to `"clear"`. `clearValue` takes an array or object representing the four color components `r`, `g`, `b`, and `a` as decimals. - What follows is a sample array: + For example, you can pass an array like `[0.0, 0.5, 1.0, 1.0]`, or its equivalent object `{ r: 0.0, g: 0.5, b: 1.0, a: 1.0 }`. - ```js - clearValue: [0.0, 0.5, 1.0, 1.0]; - ``` - - The object equivalent would look like this: - - ```js - clearValue: { - r: 0.0, - g: 0.5, - b: 1.0, - a: 1.0 - } - ``` - - If `clearValue` is omitted, it defaults to `{r: 0, g: 0, b: 0, a: 0}`. + If `clearValue` is omitted, it defaults to `{ r: 0, g: 0, b: 0, a: 0 }`. - `depthSlice` {{optional_inline}} @@ -170,7 +155,7 @@ General: For color attachment objects -- The `view` is renderable, and the `view`'s format (i.e. specified in the descriptor of the originating {{domxref("GPUTexture.createView()")}} call) is a color renderable format. +- The `view` is renderable, and the `view`'s format (i.e., specified in the descriptor of the originating {{domxref("GPUTexture.createView()")}} call) is a color renderable format. - If `resolveTarget` is provided: - The `view`'s originating {{domxref("GPUTexture")}}'s {{domxref("GPUTexture.sampleCount", "sampleCount")}} is greater than 1. - The `resolveTarget`'s originating {{domxref("GPUTexture")}}'s {{domxref("GPUTexture.sampleCount", "sampleCount")}} is 1. @@ -201,7 +186,7 @@ For timestamp queries: In our [basic render demo](https://mdn.github.io/dom-examples/webgpu-render-demo/), a number of commands are recorded via a {{domxref("GPUCommandEncoder")}}. These commands originate from the {{domxref("GPURenderPassEncoder")}} created via `beginRenderPass()` : ```js -// ... +// … // Create GPUCommandEncoder const commandEncoder = device.createCommandEncoder(); @@ -233,7 +218,7 @@ passEncoder.end(); device.queue.submit([commandEncoder.finish()]); -// ... +// … ``` ## Specifications diff --git a/files/en-us/web/api/gpucommandencoder/clearbuffer/index.md b/files/en-us/web/api/gpucommandencoder/clearbuffer/index.md index 9a35a1bb0911e60..d7e1e92071b6992 100644 --- a/files/en-us/web/api/gpucommandencoder/clearbuffer/index.md +++ b/files/en-us/web/api/gpucommandencoder/clearbuffer/index.md @@ -45,7 +45,7 @@ The following criteria must be met when calling **`clearBuffer()`**, otherwise a ## Examples ```js -// ... +// … const buffer = device.createBuffer({ size: 1000, @@ -57,7 +57,7 @@ const buffer = device.createBuffer({ const commandBuffer = device.createCommandEncoder(); commandEncoder.clearBuffer(buffer); -// ... +// … ``` ## Specifications diff --git a/files/en-us/web/api/gpucommandencoder/copybuffertobuffer/index.md b/files/en-us/web/api/gpucommandencoder/copybuffertobuffer/index.md index 91215a3cd8c4ced..29603616968f6e1 100644 --- a/files/en-us/web/api/gpucommandencoder/copybuffertobuffer/index.md +++ b/files/en-us/web/api/gpucommandencoder/copybuffertobuffer/index.md @@ -52,7 +52,7 @@ The following criteria must be met when calling **`copyBufferToBuffer()`**, othe In our [basic compute demo](https://mdn.github.io/dom-examples/webgpu-compute-demo/), we use `copyBufferToBuffer()` to copy the contents of our `output` buffer to the `stagingBuffer`. ```js -// ... +// … // Create an output buffer to read GPU calculations to, and a staging buffer to be mapped for JavaScript access @@ -66,12 +66,12 @@ const stagingBuffer = device.createBuffer({ usage: GPUBufferUsage.MAP_READ | GPUBufferUsage.COPY_DST, }); -// ... +// … // Create GPUCommandEncoder to encode commands to issue to the GPU const commandEncoder = device.createCommandEncoder(); -// ... +// … // Copy output buffer to staging buffer commandEncoder.copyBufferToBuffer( @@ -82,7 +82,7 @@ commandEncoder.copyBufferToBuffer( BUFFER_SIZE, ); -// ... +// … ``` ## Specifications diff --git a/files/en-us/web/api/gpucommandencoder/copybuffertotexture/index.md b/files/en-us/web/api/gpucommandencoder/copybuffertotexture/index.md index 6fa2ea7d431cb19..1b89c85c6a11f53 100644 --- a/files/en-us/web/api/gpucommandencoder/copybuffertotexture/index.md +++ b/files/en-us/web/api/gpucommandencoder/copybuffertotexture/index.md @@ -28,7 +28,7 @@ copyBufferToTexture(source, destination, copySize) - `offset` {{optional_inline}} - : The offset, in bytes, from the beginning of `data` to the start of the image data to be copied. If omitted, `offset` defaults to 0. - `bytesPerRow` {{optional_inline}} - - : A number representing the stride, in bytes, between the start of each block row (i.e. a row of complete texel blocks) and the subsequent block row. This is required if there are multiple block rows (i.e. the copy height or depth is more than one block). + - : A number representing the stride, in bytes, between the start of each block row (i.e., a row of complete texel blocks) and the subsequent block row. This is required if there are multiple block rows (i.e., the copy height or depth is more than one block). - `rowsPerImage` {{optional_inline}} - : The number of block rows per single image inside the data. `bytesPerRow` &times; `rowsPerImage` will give you the stride, in bytes, between the start of each complete image. This is required if there are multiple images to copy. - `destination` @@ -54,21 +54,7 @@ copyBufferToTexture(source, destination, copySize) - : An object or array specifying the origin of the copy — the minimum corner of the texture region to write the data to. Together with `size`, this defines the full extent of the region to copy to. The `x`, `y`, and `z` values default to 0 if any of all of `origin` is omitted. - What follows is a sample array: - - ```js - [0, 0, 0]; - ``` - - The object equivalent would look like this: - - ```js - { - x: 0, - y: 0, - z: 0 - } - ``` + For example, you can pass an array like `[0, 0, 0]`, or its equivalent object `{ x: 0, y: 0, z: 0 }`. - `texture` - : A {{domxref("GPUTexture")}} object representing the texture to write the data to. @@ -77,21 +63,7 @@ copyBufferToTexture(source, destination, copySize) - : An object or array specifying the width, height, and depth/array layer count of the copied data. The width value must always be specified, while the height and depth/array layer count values are optional and will default to 1 if omitted. - What follows is a sample `copySize` array: - - ```js - [16, 16, 2]; - ``` - - The object equivalent would look like this: - - ```js - { - width: 16, - height: 16, - depthOrArrayLayers: 2 - } - ``` + For example, you can pass an array `[16, 16, 2]`, or its equivalent object `{ width: 16, height: 16, depthOrArrayLayers: 2 }`. ### Return value diff --git a/files/en-us/web/api/gpucommandencoder/copytexturetobuffer/index.md b/files/en-us/web/api/gpucommandencoder/copytexturetobuffer/index.md index 895d9106c5e9241..6ae13e8e09e7dbb 100644 --- a/files/en-us/web/api/gpucommandencoder/copytexturetobuffer/index.md +++ b/files/en-us/web/api/gpucommandencoder/copytexturetobuffer/index.md @@ -44,21 +44,7 @@ copyTextureToBuffer(source, destination, copySize) - : An object or array specifying the origin of the copy — the minimum corner of the texture region to copy the data from. Together with `size`, this defines the full extent of the region to copy from. The `x`, `y`, and `z` values default to 0 if any of all of `origin` is omitted. - What follows is a sample array: - - ```js - [0, 0, 0]; - ``` - - The object equivalent would look like this: - - ```js - { - x: 0, - y: 0, - z: 0 - } - ``` + For example, you can pass an array `[0, 0, 0]`, or its equivalent object `{ x: 0, y: 0, z: 0 }`. - `texture` - : A {{domxref("GPUTexture")}} object representing the texture to copy the data from. @@ -71,7 +57,7 @@ copyTextureToBuffer(source, destination, copySize) - `offset` {{optional_inline}} - : The offset, in bytes, from the beginning of `data` to the start position to write the copied data to. If omitted, `offset` defaults to 0. - `bytesPerRow` {{optional_inline}} - - : A number representing the stride, in bytes, between the start of each block row (i.e. a row of complete texel blocks) and the subsequent block row. This is required if there are multiple block rows (i.e. the copy height or depth is more than one block). + - : A number representing the stride, in bytes, between the start of each block row (i.e., a row of complete texel blocks) and the subsequent block row. This is required if there are multiple block rows (i.e., the copy height or depth is more than one block). - `rowsPerImage` {{optional_inline}} - : The number of block rows per single image inside the data. `bytesPerRow` &times; `rowsPerImage` will give you the stride, in bytes, between the start of each complete image. This is required if there are multiple images to copy. @@ -79,21 +65,7 @@ copyTextureToBuffer(source, destination, copySize) - : An object or array specifying the width, height, and depth/array layer count of the copied data. The width value must always be specified, while the height and depth/array layer count values are optional and will default to 1 if omitted. - What follows is a sample `copySize` array: - - ```js - [16, 16, 2]; - ``` - - The object equivalent would look like this: - - ```js - { - width: 16, - height: 16, - depthOrArrayLayers: 2 - } - ``` + For example, you can pass an array `[16, 16, 2]`, or its equivalent object `{ width: 16, height: 16, depthOrArrayLayers: 2 }`. ### Return value diff --git a/files/en-us/web/api/gpucommandencoder/copytexturetotexture/index.md b/files/en-us/web/api/gpucommandencoder/copytexturetotexture/index.md index 6d088810e750757..b67aaeb990ec3e4 100644 --- a/files/en-us/web/api/gpucommandencoder/copytexturetotexture/index.md +++ b/files/en-us/web/api/gpucommandencoder/copytexturetotexture/index.md @@ -29,21 +29,7 @@ copyTextureToTexture(source, destination, copySize) - : An object or array specifying the width, height, and depth/array layer count of the copied data. The width value must always be specified, while the height and depth/array layer count values are optional and will default to 1 if omitted. - What follows is a sample `copySize` array: - - ```js - [16, 16, 2]; - ``` - - The object equivalent would look like this: - - ```js - { - width: 16, - height: 16, - depthOrArrayLayers: 2 - } - ``` + For example, you can pass an array `[16, 16, 2]`, or its equivalent object `{ width: 16, height: 16, depthOrArrayLayers: 2 }`. ### Copy texture object structure @@ -68,21 +54,7 @@ A copy texture object has the following structure: - : An object or array specifying the origin of the copy/destination — the minimum corner of the texture region to copy the data from/to. Together with `size`, this defines the full extent of the region to copy from/to. The `x`, `y`, and `z` values default to 0 if any of all of `origin` is omitted. - What follows is a sample array: - - ```js - [0, 0, 0]; - ``` - - The object equivalent would look like this: - - ```js - { - x: 0, - y: 0, - z: 0 - } - ``` + For example, you can pass an array like `[0, 0, 0]`, or its equivalent object `{ x: 0, y: 0, z: 0 }`. - `texture` - : A {{domxref("GPUTexture")}} object representing the texture to copy the data from/to. diff --git a/files/en-us/web/api/gpucommandencoder/finish/index.md b/files/en-us/web/api/gpucommandencoder/finish/index.md index 72e6004b86a5119..27b4ee514af9af9 100644 --- a/files/en-us/web/api/gpucommandencoder/finish/index.md +++ b/files/en-us/web/api/gpucommandencoder/finish/index.md @@ -35,7 +35,7 @@ A {{domxref("GPUCommandBuffer")}} object instance. The following criteria must be met when calling **`finish()`**, otherwise a {{domxref("GPUValidationError")}} is generated and the {{domxref("GPUCommandEncoder")}} becomes invalid: -- There are no active debug groups (i.e. started via {{domxref("GPUCommandEncoder.pushDebugGroup", "pushDebugGroup()")}}). +- There are no active debug groups (i.e., started via {{domxref("GPUCommandEncoder.pushDebugGroup", "pushDebugGroup()")}}). - The {{domxref("GPUCommandEncoder")}} is in an open state — this means that: - There are no child {{domxref("GPUComputePassEncoder")}} or {{domxref("GPURenderPassEncoder")}}s active that have not been ended (by calling `end()`). - The {{domxref("GPUCommandEncoder")}} has not already had `finish()` called on it (in which case it cannot be used to encode any more commands). @@ -43,12 +43,12 @@ The following criteria must be met when calling **`finish()`**, otherwise a {{do ## Examples ```js -// ... +// … const commandBuffer = commandEncoder.finish(); device.queue.submit([commandBuffer]); -// ... +// … ``` ## Specifications diff --git a/files/en-us/web/api/gpucommandencoder/index.md b/files/en-us/web/api/gpucommandencoder/index.md index 249067cf6a80462..03cd886cd790a1c 100644 --- a/files/en-us/web/api/gpucommandencoder/index.md +++ b/files/en-us/web/api/gpucommandencoder/index.md @@ -58,7 +58,7 @@ A `GPUCommandEncoder` object instance is created via the {{domxref("GPUDevice.cr In our [basic render demo](https://mdn.github.io/dom-examples/webgpu-render-demo/), several commands are recorded via a `GPUCommandEncoder`: ```js -// ... +// … // Create GPUCommandEncoder const commandEncoder = device.createCommandEncoder(); @@ -88,7 +88,7 @@ passEncoder.draw(3); passEncoder.end(); -// ... +// … ``` The commands encoded by the `GPUCommandEncoder` are recoded into a {{domxref("GPUCommandBuffer")}} using the {{domxref("GPUCommandEncoder.finish()")}} method. The command buffer is then passed into the queue via a {{domxref("GPUQueue.submit", "submit()")}} call, ready to be processed by the GPU. diff --git a/files/en-us/web/api/gpucommandencoder/insertdebugmarker/index.md b/files/en-us/web/api/gpucommandencoder/insertdebugmarker/index.md index 836011ad318d254..d8c11f20ced1858 100644 --- a/files/en-us/web/api/gpucommandencoder/insertdebugmarker/index.md +++ b/files/en-us/web/api/gpucommandencoder/insertdebugmarker/index.md @@ -33,11 +33,11 @@ None ({{jsxref("Undefined")}}). ## Examples ```js -// ... +// … commandEncoder.insertDebugMarker("my_marker"); -// ... +// … ``` ## Specifications diff --git a/files/en-us/web/api/gpucommandencoder/popdebuggroup/index.md b/files/en-us/web/api/gpucommandencoder/popdebuggroup/index.md index e7234c778922041..bbd508e88175eb4 100644 --- a/files/en-us/web/api/gpucommandencoder/popdebuggroup/index.md +++ b/files/en-us/web/api/gpucommandencoder/popdebuggroup/index.md @@ -33,12 +33,12 @@ None ({{jsxref("Undefined")}}). The following criteria must be met when calling **`popDebugGroup()`**, otherwise a {{domxref("GPUValidationError")}} is generated and the {{domxref("GPUCommandEncoder")}} becomes invalid: -- The command encoder's debug stack is not empty (i.e. at least one debug group was previously started with {{domxref("GPUCommandEncoder.pushDebugGroup", "pushDebugGroup()")}}). +- The command encoder's debug stack is not empty (i.e., at least one debug group was previously started with {{domxref("GPUCommandEncoder.pushDebugGroup", "pushDebugGroup()")}}). ## Examples ```js -// ... +// … commandEncoder.pushDebugGroup("my_group_marker"); // Start labeled debug group @@ -52,7 +52,7 @@ passEncoder.end(); commandEncoder.popDebugGroup(); // End labeled debug group -// ... +// … ``` ## Specifications diff --git a/files/en-us/web/api/gpucommandencoder/pushdebuggroup/index.md b/files/en-us/web/api/gpucommandencoder/pushdebuggroup/index.md index 505803b6dcf1bf4..a6869353c71acd1 100644 --- a/files/en-us/web/api/gpucommandencoder/pushdebuggroup/index.md +++ b/files/en-us/web/api/gpucommandencoder/pushdebuggroup/index.md @@ -33,7 +33,7 @@ None ({{jsxref("Undefined")}}). ## Examples ```js -// ... +// … commandEncoder.pushDebugGroup("my_group_marker"); // Start labeled debug group @@ -47,7 +47,7 @@ passEncoder.end(); commandEncoder.popDebugGroup(); // End labeled debug group -// ... +// … ``` ## Specifications diff --git a/files/en-us/web/api/gpucommandencoder/resolvequeryset/index.md b/files/en-us/web/api/gpucommandencoder/resolvequeryset/index.md index e5cbc283d9bb992..34375ad96518fed 100644 --- a/files/en-us/web/api/gpucommandencoder/resolvequeryset/index.md +++ b/files/en-us/web/api/gpucommandencoder/resolvequeryset/index.md @@ -49,7 +49,7 @@ The following criteria must be met when calling **`resolveQuerySet()`**, otherwi ## Examples ```js -// ... +// … const queryBuffer = device.createBuffer({ size: 1024, @@ -61,17 +61,17 @@ const querySet = device.createQuerySet({ count: 32, }); -// ... +// … const commandEncoder = device.createCommandEncoder(); // Write timestamps to querySet commandEncoder.writeTimestamp(querySet, 0); -// ... +// … commandEncoder.writeTimestamp(querySet, 1); // etc. -// ... +// … commandEncoder.resolveQuerySet( querySet, @@ -81,7 +81,7 @@ commandEncoder.resolveQuerySet( 0, // Buffer offset ); -// ... +// … ``` ## Specifications diff --git a/files/en-us/web/api/gpucommandencoder/writetimestamp/index.md b/files/en-us/web/api/gpucommandencoder/writetimestamp/index.md index fd3efc507eafd05..a050184218a3893 100644 --- a/files/en-us/web/api/gpucommandencoder/writetimestamp/index.md +++ b/files/en-us/web/api/gpucommandencoder/writetimestamp/index.md @@ -45,18 +45,18 @@ The following criteria must be met when calling **`writeTimestamp()`**, otherwis ## Examples ```js -// ... +// … const querySet = device.createQuerySet({ type: "timestamp", count: 32, }); -// ... +// … commandEncoder.writeTimestamp(querySet, 0); -// ... +// … ``` ## Specifications diff --git a/files/en-us/web/api/gpucompilationinfo/index.md b/files/en-us/web/api/gpucompilationinfo/index.md index cf2dd964e36e476..74bb26cf9bbd590 100644 --- a/files/en-us/web/api/gpucompilationinfo/index.md +++ b/files/en-us/web/api/gpucompilationinfo/index.md @@ -53,7 +53,7 @@ When we compile the shader module, we use `getCompilationInfo()` to grab some in ```js async function init() { - // ... + // … const shaderModule = device.createShaderModule({ code: shaders, @@ -65,7 +65,7 @@ async function init() { console.log(firstMessage.lineNum); // 9 console.log(firstMessage.message); // "expected ')' for function declaration" console.log(firstMessage.type); // "error" - // ... + // … } ``` diff --git a/files/en-us/web/api/gpucompilationmessage/length/index.md b/files/en-us/web/api/gpucompilationmessage/length/index.md index 7c3b8e99c339058..603d3287490e149 100644 --- a/files/en-us/web/api/gpucompilationmessage/length/index.md +++ b/files/en-us/web/api/gpucompilationmessage/length/index.md @@ -22,16 +22,13 @@ To be precise, `length` is the number of UTF-16 code units in the shader code su ## Examples ```js - // ... - const shaderModule = device.createShaderModule({ - code: shaders, - }); - - const shaderInfo = await shaderModule.getCompilationInfo(); - const firstMessage = shaderInfo.messages[0]; - console.log(firstMessage.length); - // ... -} +const shaderModule = device.createShaderModule({ + code: shaders, +}); + +const shaderInfo = await shaderModule.getCompilationInfo(); +const firstMessage = shaderInfo.messages[0]; +console.log(firstMessage.length); ``` See the main [`GPUCompilationInfo` page](/en-US/docs/Web/API/GPUCompilationInfo#examples) for a more detailed example. diff --git a/files/en-us/web/api/gpucompilationmessage/linenum/index.md b/files/en-us/web/api/gpucompilationmessage/linenum/index.md index e30cb45287dbf55..bf426ee19c959b7 100644 --- a/files/en-us/web/api/gpucompilationmessage/linenum/index.md +++ b/files/en-us/web/api/gpucompilationmessage/linenum/index.md @@ -27,16 +27,13 @@ Note that: ## Examples ```js - // ... - const shaderModule = device.createShaderModule({ - code: shaders, - }); - - const shaderInfo = await shaderModule.getCompilationInfo(); - const firstMessage = shaderInfo.messages[0]; - console.log(firstMessage.lineNum); - // ... -} +const shaderModule = device.createShaderModule({ + code: shaders, +}); + +const shaderInfo = await shaderModule.getCompilationInfo(); +const firstMessage = shaderInfo.messages[0]; +console.log(firstMessage.lineNum); ``` See the main [`GPUCompilationInfo` page](/en-US/docs/Web/API/GPUCompilationInfo#examples) for a more detailed example. diff --git a/files/en-us/web/api/gpucompilationmessage/linepos/index.md b/files/en-us/web/api/gpucompilationmessage/linepos/index.md index cd48c37441e7d4b..e204fc8494d7115 100644 --- a/files/en-us/web/api/gpucompilationmessage/linepos/index.md +++ b/files/en-us/web/api/gpucompilationmessage/linepos/index.md @@ -28,16 +28,13 @@ Note that: ## Examples ```js - // ... - const shaderModule = device.createShaderModule({ - code: shaders, - }); - - const shaderInfo = await shaderModule.getCompilationInfo(); - const firstMessage = shaderInfo.messages[0]; - console.log(firstMessage.linePos); - // ... -} +const shaderModule = device.createShaderModule({ + code: shaders, +}); + +const shaderInfo = await shaderModule.getCompilationInfo(); +const firstMessage = shaderInfo.messages[0]; +console.log(firstMessage.linePos); ``` See the main [`GPUCompilationInfo` page](/en-US/docs/Web/API/GPUCompilationInfo#examples) for a more detailed example. diff --git a/files/en-us/web/api/gpucompilationmessage/message/index.md b/files/en-us/web/api/gpucompilationmessage/message/index.md index 6bf9acc2503463a..f788a7771a030cb 100644 --- a/files/en-us/web/api/gpucompilationmessage/message/index.md +++ b/files/en-us/web/api/gpucompilationmessage/message/index.md @@ -20,16 +20,13 @@ A string. ## Examples ```js - // ... - const shaderModule = device.createShaderModule({ - code: shaders, - }); - - const shaderInfo = await shaderModule.getCompilationInfo(); - const firstMessage = shaderInfo.messages[0]; - console.log(firstMessage.message); - // ... -} +const shaderModule = device.createShaderModule({ + code: shaders, +}); + +const shaderInfo = await shaderModule.getCompilationInfo(); +const firstMessage = shaderInfo.messages[0]; +console.log(firstMessage.message); ``` See the main [`GPUCompilationInfo` page](/en-US/docs/Web/API/GPUCompilationInfo#examples) for a more detailed example. diff --git a/files/en-us/web/api/gpucompilationmessage/offset/index.md b/files/en-us/web/api/gpucompilationmessage/offset/index.md index b4e3ece44904db2..7e1020150708e1f 100644 --- a/files/en-us/web/api/gpucompilationmessage/offset/index.md +++ b/files/en-us/web/api/gpucompilationmessage/offset/index.md @@ -24,16 +24,13 @@ If the message does not correspond to a specific code position (perhaps it refer ## Examples ```js - // ... - const shaderModule = device.createShaderModule({ - code: shaders, - }); - - const shaderInfo = await shaderModule.getCompilationInfo(); - const firstMessage = shaderInfo.messages[0]; - console.log(firstMessage.offset); - // ... -} +const shaderModule = device.createShaderModule({ + code: shaders, +}); + +const shaderInfo = await shaderModule.getCompilationInfo(); +const firstMessage = shaderInfo.messages[0]; +console.log(firstMessage.offset); ``` See the main [`GPUCompilationInfo` page](/en-US/docs/Web/API/GPUCompilationInfo#examples) for a more detailed example. diff --git a/files/en-us/web/api/gpucompilationmessage/type/index.md b/files/en-us/web/api/gpucompilationmessage/type/index.md index cda32b917f95703..6ffd098686d2a58 100644 --- a/files/en-us/web/api/gpucompilationmessage/type/index.md +++ b/files/en-us/web/api/gpucompilationmessage/type/index.md @@ -27,16 +27,13 @@ A enumerated value. Possible values are: ## Examples ```js - // ... - const shaderModule = device.createShaderModule({ - code: shaders, - }); - - const shaderInfo = await shaderModule.getCompilationInfo(); - const firstMessage = shaderInfo.messages[0]; - console.log(firstMessage.type); - // ... -} +const shaderModule = device.createShaderModule({ + code: shaders, +}); + +const shaderInfo = await shaderModule.getCompilationInfo(); +const firstMessage = shaderInfo.messages[0]; +console.log(firstMessage.type); ``` See the main [`GPUCompilationInfo` page](/en-US/docs/Web/API/GPUCompilationInfo#examples) for a more detailed example. diff --git a/files/en-us/web/api/gpucomputepassencoder/dispatchworkgroups/index.md b/files/en-us/web/api/gpucomputepassencoder/dispatchworkgroups/index.md index c1c189266aaab9f..99919a4c48e1258 100644 --- a/files/en-us/web/api/gpucomputepassencoder/dispatchworkgroups/index.md +++ b/files/en-us/web/api/gpucomputepassencoder/dispatchworkgroups/index.md @@ -11,7 +11,7 @@ browser-compat: api.GPUComputePassEncoder.dispatchWorkgroups {{APIRef("WebGPU API")}}{{SeeCompatTable}}{{SecureContext_Header}}{{AvailableInWorkers}} The **`dispatchWorkgroups()`** method of the -{{domxref("GPUComputePassEncoder")}} interface dispatches a specific grid of workgroups to perform the work being done by the current {{domxref("GPUComputePipeline")}} (i.e. set via {{domxref("GPUComputePassEncoder.setPipeline()")}}). +{{domxref("GPUComputePassEncoder")}} interface dispatches a specific grid of workgroups to perform the work being done by the current {{domxref("GPUComputePipeline")}} (i.e., set via {{domxref("GPUComputePassEncoder.setPipeline()")}}). ## Syntax @@ -67,7 +67,7 @@ var<storage, read_write> output: array<f32>; Later in the code, the `dispatchWorkgroups()` `workgroupCountX` parameter is set based on the global buffer size and the shader workgroup count. ```js -// ... +// … // Create GPUCommandEncoder to encode commands to issue to the GPU const commandEncoder = device.createCommandEncoder(); @@ -95,7 +95,7 @@ commandEncoder.copyBufferToBuffer( // End frame by passing array of command buffers to command queue for execution device.queue.submit([commandEncoder.finish()]); -// ... +// … ``` ## Specifications diff --git a/files/en-us/web/api/gpucomputepassencoder/dispatchworkgroupsindirect/index.md b/files/en-us/web/api/gpucomputepassencoder/dispatchworkgroupsindirect/index.md index 1eadfacf8924f59..b0294a501c8722c 100644 --- a/files/en-us/web/api/gpucomputepassencoder/dispatchworkgroupsindirect/index.md +++ b/files/en-us/web/api/gpucomputepassencoder/dispatchworkgroupsindirect/index.md @@ -11,7 +11,7 @@ browser-compat: api.GPUComputePassEncoder.dispatchWorkgroupsIndirect {{APIRef("WebGPU API")}}{{SeeCompatTable}}{{SecureContext_Header}}{{AvailableInWorkers}} The **`dispatchWorkgroupsIndirect()`** method of the -{{domxref("GPUComputePassEncoder")}} interface dispatches a grid of workgroups, defined by the parameters of a {{domxref("GPUBuffer")}}, to perform the work being done by the current {{domxref("GPUComputePipeline")}} (i.e. set via {{domxref("GPUComputePassEncoder.setPipeline()")}}). +{{domxref("GPUComputePassEncoder")}} interface dispatches a grid of workgroups, defined by the parameters of a {{domxref("GPUBuffer")}}, to perform the work being done by the current {{domxref("GPUComputePipeline")}} (i.e., set via {{domxref("GPUComputePassEncoder.setPipeline()")}}). ## Syntax @@ -70,7 +70,7 @@ var<storage, read_write> output: array<f32>; `; -// ... +// … // Create GPUCommandEncoder to encode commands to issue to the GPU const commandEncoder = device.createCommandEncoder(); @@ -111,7 +111,7 @@ commandEncoder.copyBufferToBuffer( // End frame by passing array of command buffers to command queue for execution device.queue.submit([commandEncoder.finish()]); -// ... +// … ``` ## Specifications diff --git a/files/en-us/web/api/gpucomputepassencoder/end/index.md b/files/en-us/web/api/gpucomputepassencoder/end/index.md index 314a52b3cf59d2b..6c6af43e721578b 100644 --- a/files/en-us/web/api/gpucomputepassencoder/end/index.md +++ b/files/en-us/web/api/gpucomputepassencoder/end/index.md @@ -31,7 +31,7 @@ None ({{jsxref("Undefined")}}). The following criteria must be met when calling **`end()`**, otherwise a {{domxref("GPUValidationError")}} is generated and the {{domxref("GPUComputePassEncoder")}} becomes invalid: -- The {{domxref("GPUComputePassEncoder")}} is open (i.e. not already ended via an `end()` call). +- The {{domxref("GPUComputePassEncoder")}} is open (i.e., not already ended via an `end()` call). - any {{domxref("GPUComputePassEncoder.pushDebugGroup", "pushDebugGroup()")}} calls made on this encoder have a corresponding {{domxref("GPUComputePassEncoder.popDebugGroup", "popDebugGroup()")}} call before `end()` is called. ## Examples @@ -41,7 +41,7 @@ In our [basic compute demo](https://mdn.github.io/dom-examples/webgpu-compute-de ```js const BUFFER_SIZE = 1000; -// ... +// … // Create GPUCommandEncoder to encode commands to issue to the GPU const commandEncoder = device.createCommandEncoder(); @@ -69,7 +69,7 @@ commandEncoder.copyBufferToBuffer( // End frame by passing array of command buffers to command queue for execution device.queue.submit([commandEncoder.finish()]); -// ... +// … ``` ## Specifications diff --git a/files/en-us/web/api/gpucomputepassencoder/index.md b/files/en-us/web/api/gpucomputepassencoder/index.md index f149db97be29ee2..15c3b5503c90613 100644 --- a/files/en-us/web/api/gpucomputepassencoder/index.md +++ b/files/en-us/web/api/gpucomputepassencoder/index.md @@ -46,7 +46,7 @@ A `GPUComputePassEncoder` object instance is created via the {{domxref("GPUComma In our [basic compute demo](https://mdn.github.io/dom-examples/webgpu-compute-demo/), several commands are recorded via a {{domxref("GPUCommandEncoder")}}. Most of these commands originate from the `GPUComputePassEncoder` created via {{domxref("GPUCommandEncoder.beginComputePass()")}}. ```js -// ... +// … // Create GPUCommandEncoder to encode commands to issue to the GPU const commandEncoder = device.createCommandEncoder(); @@ -74,7 +74,7 @@ commandEncoder.copyBufferToBuffer( // End frame by passing array of command buffers to command queue for execution device.queue.submit([commandEncoder.finish()]); -// ... +// … ``` ## Specifications diff --git a/files/en-us/web/api/gpucomputepassencoder/insertdebugmarker/index.md b/files/en-us/web/api/gpucomputepassencoder/insertdebugmarker/index.md index ae5af7b70e65f9d..199a94e28942beb 100644 --- a/files/en-us/web/api/gpucomputepassencoder/insertdebugmarker/index.md +++ b/files/en-us/web/api/gpucomputepassencoder/insertdebugmarker/index.md @@ -33,11 +33,11 @@ None ({{jsxref("Undefined")}}). ## Examples ```js -// ... +// … passEncoder.insertDebugMarker("my_marker"); -// ... +// … ``` ## Specifications diff --git a/files/en-us/web/api/gpucomputepassencoder/popdebuggroup/index.md b/files/en-us/web/api/gpucomputepassencoder/popdebuggroup/index.md index 3a5a9513e40da09..157e10cb5f267ca 100644 --- a/files/en-us/web/api/gpucomputepassencoder/popdebuggroup/index.md +++ b/files/en-us/web/api/gpucomputepassencoder/popdebuggroup/index.md @@ -33,12 +33,12 @@ None ({{jsxref("Undefined")}}). The following criteria must be met when calling **`popDebugGroup()`**, otherwise a {{domxref("GPUValidationError")}} is generated and the {{domxref("GPUComputePassEncoder")}} becomes invalid: -- The compute pass encoder's debug stack is not empty (i.e. at least one compute pass debug group was previously started with {{domxref("GPUComputePassEncoder.pushDebugGroup", "pushDebugGroup()")}}). +- The compute pass encoder's debug stack is not empty (i.e., at least one compute pass debug group was previously started with {{domxref("GPUComputePassEncoder.pushDebugGroup", "pushDebugGroup()")}}). ## Examples ```js -// ... +// … const passEncoder = commandEncoder.beginComputePass(); @@ -50,7 +50,7 @@ passEncoder.dispatchWorkgroups(Math.ceil(BUFFER_SIZE / 64)); passEncoder.popDebugGroup(); -// ... +// … ``` ## Specifications diff --git a/files/en-us/web/api/gpucomputepassencoder/pushdebuggroup/index.md b/files/en-us/web/api/gpucomputepassencoder/pushdebuggroup/index.md index 557315770690e8c..eb02b21de47e119 100644 --- a/files/en-us/web/api/gpucomputepassencoder/pushdebuggroup/index.md +++ b/files/en-us/web/api/gpucomputepassencoder/pushdebuggroup/index.md @@ -33,7 +33,7 @@ None ({{jsxref("Undefined")}}). ## Examples ```js -// ... +// … const passEncoder = commandEncoder.beginComputePass(); @@ -45,7 +45,7 @@ passEncoder.dispatchWorkgroups(Math.ceil(BUFFER_SIZE / 64)); passEncoder.popDebugGroup(); -// ... +// … ``` ## Specifications diff --git a/files/en-us/web/api/gpucomputepassencoder/setbindgroup/index.md b/files/en-us/web/api/gpucomputepassencoder/setbindgroup/index.md index 8512eb933b83a6a..5f7ace8be16facf 100644 --- a/files/en-us/web/api/gpucomputepassencoder/setbindgroup/index.md +++ b/files/en-us/web/api/gpucomputepassencoder/setbindgroup/index.md @@ -29,7 +29,7 @@ setBindGroup(index, bindGroup, dynamicOffsets, dynamicOffsetsStart, - `bindGroup` - : The {{domxref("GPUBindGroup")}} to use for subsequent compute commands, or `null`, in which case any previously-set bind group in the given slot is unset. - `dynamicOffsets` {{optional_inline}} - - : A value specifying the offset, in bytes, for each entry in `bindGroup` with `hasDynamicOffset: true` set (i.e. in the descriptor of the {{domxref("GPUDevice.createBindGroupLayout()")}} call that created the {{domxref("GPUBindGroupLayout")}} object that the `bindGroup` is based on). This value can be: + - : A value specifying the offset, in bytes, for each entry in `bindGroup` with `hasDynamicOffset: true` set (i.e., in the descriptor of the {{domxref("GPUDevice.createBindGroupLayout()")}} call that created the {{domxref("GPUBindGroupLayout")}} object that the `bindGroup` is based on). This value can be: - An array of numbers specifying the different offsets. - A {{jsxref("Uint32Array")}} containing numbers specifying the offsets. @@ -70,7 +70,7 @@ In our [basic compute demo](https://mdn.github.io/dom-examples/webgpu-compute-de ```js const BUFFER_SIZE = 1000; -// ... +// … // Create GPUCommandEncoder to encode commands to issue to the GPU const commandEncoder = device.createCommandEncoder(); @@ -98,7 +98,7 @@ commandEncoder.copyBufferToBuffer( // End frame by passing array of command buffers to command queue for execution device.queue.submit([commandEncoder.finish()]); -// ... +// … ``` ### Unset bind group diff --git a/files/en-us/web/api/gpucomputepassencoder/setpipeline/index.md b/files/en-us/web/api/gpucomputepassencoder/setpipeline/index.md index 73fe32ac17fa204..9bf7d3aa0edadc7 100644 --- a/files/en-us/web/api/gpucomputepassencoder/setpipeline/index.md +++ b/files/en-us/web/api/gpucomputepassencoder/setpipeline/index.md @@ -35,7 +35,7 @@ In our [basic compute demo](https://mdn.github.io/dom-examples/webgpu-compute-de ```js const BUFFER_SIZE = 1000; -// ... +// … // Create GPUCommandEncoder to encode commands to issue to the GPU const commandEncoder = device.createCommandEncoder(); @@ -63,7 +63,7 @@ commandEncoder.copyBufferToBuffer( // End frame by passing array of command buffers to command queue for execution device.queue.submit([commandEncoder.finish()]); -// ... +// … ``` ## Specifications diff --git a/files/en-us/web/api/gpucomputepipeline/getbindgrouplayout/index.md b/files/en-us/web/api/gpucomputepipeline/getbindgrouplayout/index.md index 4f2be5bc1efe559..2ea3e8866183a4b 100644 --- a/files/en-us/web/api/gpucomputepipeline/getbindgrouplayout/index.md +++ b/files/en-us/web/api/gpucomputepipeline/getbindgrouplayout/index.md @@ -11,7 +11,7 @@ browser-compat: api.GPUComputePipeline.getBindGroupLayout {{APIRef("WebGPU API")}}{{SeeCompatTable}}{{SecureContext_Header}}{{AvailableInWorkers}} The **`getBindGroupLayout()`** method of the -{{domxref("GPUComputePipeline")}} interface returns the pipeline's {{domxref("GPUBindGroupLayout")}} object with the given index (i.e. included in the originating {{domxref("GPUDevice.createComputePipeline()")}} or {{domxref("GPUDevice.createComputePipelineAsync()")}} call's pipeline layout). +{{domxref("GPUComputePipeline")}} interface returns the pipeline's {{domxref("GPUBindGroupLayout")}} object with the given index (i.e., included in the originating {{domxref("GPUDevice.createComputePipeline()")}} or {{domxref("GPUDevice.createComputePipelineAsync()")}} call's pipeline layout). If the {{domxref("GPUComputePipeline")}} was created with `layout: "auto"`, this method is the only way to retrieve the {{domxref("GPUBindGroupLayout")}}s generated by the pipeline. @@ -43,7 +43,7 @@ The following criteria must be met when calling **`getBindGroupLayout()`**, othe > You can see complete working examples with `getBindGroupLayout()` in action in the [WebGPU samples](https://webgpu.github.io/webgpu-samples/). ```js -// ... +// … // Create a compute pipeline using layout: "auto" to automatically generate // appropriate bind group layouts @@ -66,7 +66,7 @@ const computeBindGroup = device.createBindGroup({ ], }); -// ... +// … ``` ## Specifications diff --git a/files/en-us/web/api/gpucomputepipeline/index.md b/files/en-us/web/api/gpucomputepipeline/index.md index 9d0f01cbbd082ba..0459765e3957b7c 100644 --- a/files/en-us/web/api/gpucomputepipeline/index.md +++ b/files/en-us/web/api/gpucomputepipeline/index.md @@ -23,7 +23,7 @@ A `GPUComputePipeline` object instance can be created using the {{domxref("GPUDe ## Instance methods - {{domxref("GPUComputePipeline.getBindGroupLayout", "getBindGroupLayout()")}} {{Experimental_Inline}} - - : Returns the pipeline's {{domxref("GPUBindGroupLayout")}} object with the given index (i.e. included in the originating {{domxref("GPUDevice.createComputePipeline()")}} or {{domxref("GPUDevice.createComputePipelineAsync()")}} call's pipeline layout). + - : Returns the pipeline's {{domxref("GPUBindGroupLayout")}} object with the given index (i.e., included in the originating {{domxref("GPUDevice.createComputePipeline()")}} or {{domxref("GPUDevice.createComputePipelineAsync()")}} call's pipeline layout). ## Examples @@ -39,7 +39,7 @@ Our [basic compute demo](https://mdn.github.io/dom-examples/webgpu-compute-demo/ - Using that value immediately in a `createComputePipeline()` call to create a `GPUComputePipeline`. ```js -// ... +// … const bindGroupLayout = device.createBindGroupLayout({ entries: [ @@ -63,7 +63,7 @@ const computePipeline = device.createComputePipeline({ }, }); -// ... +// … ``` ## Specifications diff --git a/files/en-us/web/api/gpucomputepipeline/label/index.md b/files/en-us/web/api/gpucomputepipeline/label/index.md index 023641c1020be72..b5088c5b25a7c7e 100644 --- a/files/en-us/web/api/gpucomputepipeline/label/index.md +++ b/files/en-us/web/api/gpucomputepipeline/label/index.md @@ -24,7 +24,7 @@ A string. If this has not been previously set as described above, it will be an Setting and getting a label via `GPUComputePipeline.label`: ```js -// ... +// … const computePipeline = device.createComputePipeline({ layout: device.createPipelineLayout({ @@ -44,7 +44,7 @@ console.log(computePipeline.label); // "my_compute_pipeline" Setting a label via a {{domxref("GPUDevice.createComputePipeline()")}} call, and then getting it via `GPUComputePipeline.label`: ```js -// ... +// … const computePipeline = device.createComputePipeline({ layout: device.createPipelineLayout({ diff --git a/files/en-us/web/api/gpudevice/adapterinfo/index.md b/files/en-us/web/api/gpudevice/adapterinfo/index.md new file mode 100644 index 000000000000000..8abea1b96914d72 --- /dev/null +++ b/files/en-us/web/api/gpudevice/adapterinfo/index.md @@ -0,0 +1,53 @@ +--- +title: "GPUDevice: adapterInfo property" +short-title: adapterInfo +slug: Web/API/GPUDevice/adapterInfo +page-type: web-api-instance-property +status: + - experimental +browser-compat: api.GPUDevice.adapterInfo +--- + +{{APIRef("WebGPU API")}}{{SeeCompatTable}}{{SecureContext_Header}}{{AvailableInWorkers}} + +The **`adapterInfo`** read-only property of the +{{domxref("GPUDevice")}} interface returns a {{domxref("GPUAdapterInfo")}} object containing identifying information about the device's originating adapter. + +## Value + +A {{domxref("GPUAdapterInfo")}} object instance. + +## Examples + +### Basic adapterInfo usage + +```js +const adapter = await navigator.gpu.requestAdapter(); +if (!adapter) { + throw Error("Couldn't request WebGPU adapter."); +} + +const myDevice = await adapter.requestDevice(); + +function optimizeForGpuDevice(device) { + if (device.adapterInfo.vendor === "amd") { + // Use AMD-specific optimizations + } else if (device.adapterInfo.architecture.includes("turing")) { + // Optimize for NVIDIA Turing architecture + } +} + +optimizeForGpuDevice(myDevice); +``` + +## Specifications + +{{Specifications}} + +## Browser compatibility + +{{Compat}} + +## See also + +- The [WebGPU API](/en-US/docs/Web/API/WebGPU_API) diff --git a/files/en-us/web/api/gpudevice/createbindgroup/index.md b/files/en-us/web/api/gpudevice/createbindgroup/index.md index a667797034cbca3..7bdddb90bee35e4 100644 --- a/files/en-us/web/api/gpudevice/createbindgroup/index.md +++ b/files/en-us/web/api/gpudevice/createbindgroup/index.md @@ -93,7 +93,7 @@ The following criteria must be met when calling **`createBindGroup()`**, otherwi Our [basic compute demo](https://mdn.github.io/dom-examples/webgpu-compute-demo/) shows an example of creating a bind group layout and then using that as a template when creating a bind group. ```js -// ... +// … const bindGroupLayout = device.createBindGroupLayout({ entries: [ @@ -119,7 +119,7 @@ const bindGroup = device.createBindGroup({ ], }); -// ... +// … ``` ## Specifications diff --git a/files/en-us/web/api/gpudevice/createbindgrouplayout/index.md b/files/en-us/web/api/gpudevice/createbindgrouplayout/index.md index 0f7e34afff244a5..f5a3f52e6361147 100644 --- a/files/en-us/web/api/gpudevice/createbindgrouplayout/index.md +++ b/files/en-us/web/api/gpudevice/createbindgrouplayout/index.md @@ -42,11 +42,7 @@ An entry object includes the following properties: - `GPUShaderStage.FRAGMENT`: The bind group entry will be accessible to fragment shaders. - `GPUShaderStage.VERTEX`: The bind group entry will be accessible to vertex shaders. - Note that multiple stages can be specified by separating values with pipe symbols, for example: - - ```js - visibility: GPUShaderStage.FRAGMENT | GPUShaderStage.VERTEX; - ``` + Note that multiple stages can be specified by separating values with [bitwise OR](/en-US/docs/Web/JavaScript/Reference/Operators/Bitwise_OR), for example: `GPUShaderStage.FRAGMENT | GPUShaderStage.VERTEX`. - "Resource layout object" - : An object that defines the required binding resource type and structure of the {{domxref("GPUBindGroup")}} entry corresponding to this entry. This property can be one of `buffer`, `externalTexture`, `sampler`, `storageTexture`, or `texture`, the object structures of which are described in the next section. @@ -169,7 +165,7 @@ The following criteria must be met when calling **`createBindGroupLayout()`**, o Our [basic compute demo](https://mdn.github.io/dom-examples/webgpu-compute-demo/) shows an example of creating a bind group layout and then using that as a template when creating a bind group. ```js -// ... +// … const bindGroupLayout = device.createBindGroupLayout({ entries: [ @@ -195,7 +191,7 @@ const bindGroup = device.createBindGroup({ ], }); -// ... +// … ``` ## Specifications diff --git a/files/en-us/web/api/gpudevice/createbuffer/index.md b/files/en-us/web/api/gpudevice/createbuffer/index.md index c42abc5822aa409..76a570a1c786240 100644 --- a/files/en-us/web/api/gpudevice/createbuffer/index.md +++ b/files/en-us/web/api/gpudevice/createbuffer/index.md @@ -39,11 +39,7 @@ createBuffer(descriptor) - : The {{glossary("Bitwise flags", "bitwise flags")}} representing the allowed usages for the `GPUBuffer`. The possible values are in the [`GPUBuffer.usage` value table](/en-US/docs/Web/API/GPUBuffer/usage#value). - Note that multiple possible usages can be specified by separating values with pipe symbols, for example: - - ```js - usage: GPUBufferUsage.COPY_SRC | GPUBufferUsage.MAP_WRITE; - ``` + Note that multiple possible usages can be specified by separating values with [bitwise OR](/en-US/docs/Web/JavaScript/Reference/Operators/Bitwise_OR), for example: `GPUBufferUsage.COPY_SRC | GPUBufferUsage.MAP_WRITE`. ### Return value diff --git a/files/en-us/web/api/gpudevice/createcommandencoder/index.md b/files/en-us/web/api/gpudevice/createcommandencoder/index.md index e5631848f7c6084..c75ff797153ec73 100644 --- a/files/en-us/web/api/gpudevice/createcommandencoder/index.md +++ b/files/en-us/web/api/gpudevice/createcommandencoder/index.md @@ -36,7 +36,7 @@ A {{domxref("GPUCommandEncoder")}} object instance. In our [basic render demo](https://mdn.github.io/dom-examples/webgpu-render-demo/), several commands are recorded via a {{domxref("GPUCommandEncoder")}} created via `createCommandEncoder()`: ```js -// ... +// … // Create GPUCommandEncoder const commandEncoder = device.createCommandEncoder(); @@ -63,7 +63,7 @@ passEncoder.draw(3); // End the render pass passEncoder.end(); -// ... +// … ``` The commands encoded by the {{domxref("GPUCommandEncoder")}} are recoded into a {{domxref("GPUCommandBuffer")}} using the {{domxref("GPUCommandEncoder.finish()")}} method. The command buffer is then passed into the queue via a {{domxref("GPUQueue.submit", "submit()")}} call, ready to be processed by the GPU. diff --git a/files/en-us/web/api/gpudevice/createcomputepipeline/index.md b/files/en-us/web/api/gpudevice/createcomputepipeline/index.md index 17576b032c3d40c..ca39db85b40ece8 100644 --- a/files/en-us/web/api/gpudevice/createcomputepipeline/index.md +++ b/files/en-us/web/api/gpudevice/createcomputepipeline/index.md @@ -38,8 +38,8 @@ createComputePipeline(descriptor) A code snippet providing override values for several overridable constants might look like this: ```js - { - // ... + ({ + // … constants: { 0: false, 1200: 3.0, @@ -47,8 +47,8 @@ createComputePipeline(descriptor) width: 20, depth: -1, height: 15, - } - } + }, + }); ``` - `entryPoint` {{optional_inline}} @@ -94,7 +94,7 @@ Our [basic compute demo](https://mdn.github.io/dom-examples/webgpu-compute-demo/ - Using that value immediately in a `createComputePipeline()` call to create a {{domxref("GPUComputePipeline")}}. ```js -// ... +// … const bindGroupLayout = device.createBindGroupLayout({ entries: [ @@ -118,7 +118,7 @@ const computePipeline = device.createComputePipeline({ }, }); -// ... +// … ``` ## Specifications diff --git a/files/en-us/web/api/gpudevice/createcomputepipelineasync/index.md b/files/en-us/web/api/gpudevice/createcomputepipelineasync/index.md index 47c7dbb4a8c4792..1212ef7e4bd5d6d 100644 --- a/files/en-us/web/api/gpudevice/createcomputepipelineasync/index.md +++ b/files/en-us/web/api/gpudevice/createcomputepipelineasync/index.md @@ -60,7 +60,7 @@ The following example shows a process of: ```js async function init() { - // ... + // … const bindGroupLayout = device.createBindGroupLayout({ entries: [ @@ -84,7 +84,7 @@ async function init() { }, }); - // ... + // … } ``` diff --git a/files/en-us/web/api/gpudevice/createpipelinelayout/index.md b/files/en-us/web/api/gpudevice/createpipelinelayout/index.md index 8b3c0b8f0c8b6e1..2f8ad89d9d11efe 100644 --- a/files/en-us/web/api/gpudevice/createpipelinelayout/index.md +++ b/files/en-us/web/api/gpudevice/createpipelinelayout/index.md @@ -52,7 +52,7 @@ The following snippet: - Creates a {{domxref("GPUPipelineLayout")}} based on the {{domxref("GPUBindGroupLayout")}}. ```js -// ... +// … const bindGroupLayout = device.createBindGroupLayout({ entries: [ @@ -78,7 +78,7 @@ const pipelineLayout = device.createPipelineLayout({ bindGroupLayouts: [bindGroupLayout], }); -// ... +// … ``` ## Specifications diff --git a/files/en-us/web/api/gpudevice/createrenderbundleencoder/index.md b/files/en-us/web/api/gpudevice/createrenderbundleencoder/index.md index 0701862fc3dc1cf..5840702f5347b4c 100644 --- a/files/en-us/web/api/gpudevice/createrenderbundleencoder/index.md +++ b/files/en-us/web/api/gpudevice/createrenderbundleencoder/index.md @@ -81,7 +81,7 @@ const renderBundle = renderBundleEncoder.finish(); {{domxref("GPURenderPassEncoder.executeBundles()")}} is then used to reuse the work across multiple render passes to improve performance. Study the example code listing for the full context. ```js -// ... +// … return function doDraw(timestamp) { if (startTime === undefined) { @@ -107,7 +107,7 @@ return function doDraw(timestamp) { device.queue.submit([commandEncoder.finish()]); }; -// ... +// … ``` ## Specifications diff --git a/files/en-us/web/api/gpudevice/createrenderpipeline/index.md b/files/en-us/web/api/gpudevice/createrenderpipeline/index.md index 8cd6a64c7065e50..c638f26cef7eb98 100644 --- a/files/en-us/web/api/gpudevice/createrenderpipeline/index.md +++ b/files/en-us/web/api/gpudevice/createrenderpipeline/index.md @@ -126,8 +126,8 @@ The `fragment` object contains an array of objects, each of which can contain th A code snippet providing override values for several overridable constants might look like this: ```js - { - // ... + ({ + // … constants: { 0: false, 1200: 3.0, @@ -135,8 +135,8 @@ The `fragment` object contains an array of objects, each of which can contain th width: 20, depth: -1, height: 15, - } - } + }, + }); ``` - `entryPoint` {{optional_inline}} @@ -208,7 +208,12 @@ The `fragment` object contains an array of objects, each of which can contain th > For a detailed explanation of the algorithms defined by each `dstFactor`/`srcFactor` and `operation` enumerated value, see the [Blend State](https://gpuweb.github.io/gpuweb/#blend-state) section of the specification. - `format` + - : An enumerated value specifying the required format for output colors. See the specification's [Texture Formats](https://gpuweb.github.io/gpuweb/#enumdef-gputextureformat) section for all the available `format` values. + + > [!NOTE] + > For the `r32float`, `rg32float`, and `rgba32float` formats to be used with [blending](#blend), the `float32-blendable` [feature](/en-US/docs/Web/API/GPUSupportedFeatures) must be available in the device. + - `writeMask` {{optional_inline}} - : One or more {{glossary("bitwise flags")}} defining the write mask to apply to the color target state. Possible flag values are: @@ -221,11 +226,7 @@ The `fragment` object contains an array of objects, each of which can contain th If omitted, `writeMask` defaults to `GPUColorWrite.ALL`. - Note that multiple flags can be specified by separating values with pipe symbols, for example: - - ```js - writeMask: GPUColorWrite.RED | GPUColorWrite.ALPHA; - ``` + Note that multiple flags can be specified by separating values with [bitwise OR](/en-US/docs/Web/JavaScript/Reference/Operators/Bitwise_OR), for example: `GPUColorWrite.RED | GPUColorWrite.ALPHA`. ### `multisample` object structure @@ -267,7 +268,8 @@ The `primitive` object can contain the following properties: If omitted, `frontFace` defaults to `"ccw"`. - > [!NOTE] > `frontFace` and `cullMode` have no effect on `"point-list"`, `"line-list"`, or `"line-strip"` topologies. + > [!NOTE] + > The `frontFace` and `cullMode` values have no effect on the `"point-list"`, `"line-list"`, or `"line-strip"` topologies. - `stripIndexFormat` {{optional_inline}} @@ -310,8 +312,8 @@ The `vertex` object can contain the following properties: A code snippet providing override values for several overridable constants might look like this: ```js - { - // ... + ({ + // … constants: { 0: false, 1200: 3.0, @@ -319,8 +321,8 @@ The `vertex` object can contain the following properties: width: 20, depth: -1, height: 15, - } - } + }, + }); ``` - `entryPoint` {{optional_inline}} @@ -336,7 +338,7 @@ The `vertex` object can contain the following properties: - : An array of objects, each representing the expected layout of a vertex buffer used in the pipeline. Each object can contain the following properties: - `arrayStride` - - : A number representing the stride, in bytes, between the different structures (e.g. vertices) inside the buffer. + - : A number representing the stride, in bytes, between the different structures (e.g., vertices) inside the buffer. - `attributes` - : An array of objects defining the layout of the vertex attributes within each structure. Each object has the following properties: - `format` @@ -388,7 +390,7 @@ The following criteria must be met when calling **`createRenderPipeline()`**, ot Our [basic render demo](https://mdn.github.io/dom-examples/webgpu-render-demo/) provides an example of the construction of a valid render pipeline descriptor object, which is then used to create a {{domxref("GPURenderPipeline")}} via a `createRenderPipeline()` call. ```js -// ... +// … const vertexBuffers = [ { @@ -432,7 +434,7 @@ const pipelineDescriptor = { const renderPipeline = device.createRenderPipeline(pipelineDescriptor); -// ... +// … ``` ## Specifications diff --git a/files/en-us/web/api/gpudevice/createrenderpipelineasync/index.md b/files/en-us/web/api/gpudevice/createrenderpipelineasync/index.md index 034cdbf5def3ba2..908ffee9fb89e76 100644 --- a/files/en-us/web/api/gpudevice/createrenderpipelineasync/index.md +++ b/files/en-us/web/api/gpudevice/createrenderpipelineasync/index.md @@ -42,7 +42,7 @@ A validation error can occur if any of the following are false: - For `depthStencil` objects: - `format` is a [`depth-or-stencil`](https://gpuweb.github.io/gpuweb/#depth-or-stencil-format) format. - - The [`depthBias`](#depthbias), [`depthBiasClamp`](#depthbiasclamp), and [`depthBiasSlopeScale`](#depthbiasslopescale) properties are set to <code>0</code> for line and point topologies, i.e., if [`topology`](#topology) is set to `"line-list"`, `"line-strip"`, or `"point-list"`. + - The [`depthBias`](/en-US/docs/Web/API/GPUDevice/createRenderPipeline#depthbias), [`depthBiasClamp`](/en-US/docs/Web/API/GPUDevice/createRenderPipeline#depthbiasclamp), and [`depthBiasSlopeScale`](/en-US/docs/Web/API/GPUDevice/createRenderPipeline#depthbiasslopescale) properties are set to <code>0</code> for line and point topologies, i.e., if [`topology`](/en-US/docs/Web/API/GPUDevice/createRenderPipeline#topology) is set to `"line-list"`, `"line-strip"`, or `"point-list"`. - If `depthWriteEnabled` is `true` or `depthCompare` is not `"always"`, `format` has a depth component. - If `stencilFront` or `stencilBack`'s properties are not at their default values, `format` has a stencil component. - For `fragment` objects: @@ -66,7 +66,7 @@ The following example shows a basic example of the construction of a valid rende ```js async function init() { - // ... + // … const vertexBuffers = [ { @@ -111,7 +111,7 @@ async function init() { const renderPipeline = await device.createRenderPipelineAsync(pipelineDescriptor); - // ... + // … } ``` diff --git a/files/en-us/web/api/gpudevice/createsampler/index.md b/files/en-us/web/api/gpudevice/createsampler/index.md index 46907ae3b4d4343..6864fd455796141 100644 --- a/files/en-us/web/api/gpudevice/createsampler/index.md +++ b/files/en-us/web/api/gpudevice/createsampler/index.md @@ -108,7 +108,7 @@ The following criteria must be met when calling **`createSampler()`**, otherwise The following snippet creates a `GPUSampler` that does trilinear filtering and repeats texture coordinates: ```js -// ... +// … const sampler = device.createSampler({ addressModeU: "repeat", diff --git a/files/en-us/web/api/gpudevice/createshadermodule/index.md b/files/en-us/web/api/gpudevice/createshadermodule/index.md index 082a0da392e77ae..b6c1c9ecb946a52 100644 --- a/files/en-us/web/api/gpudevice/createshadermodule/index.md +++ b/files/en-us/web/api/gpudevice/createshadermodule/index.md @@ -93,16 +93,16 @@ async function init() { throw Error("Couldn't request WebGPU adapter."); } - let device = await adapter.requestDevice(); + const device = await adapter.requestDevice(); - // ... + // … // later on const shaderModule = device.createShaderModule({ code: shaders, }); - // ... + // … } ``` diff --git a/files/en-us/web/api/gpudevice/createtexture/index.md b/files/en-us/web/api/gpudevice/createtexture/index.md index 99594c26658ba2f..5de6bb9070b239a 100644 --- a/files/en-us/web/api/gpudevice/createtexture/index.md +++ b/files/en-us/web/api/gpudevice/createtexture/index.md @@ -56,31 +56,13 @@ createTexture(descriptor) - : An object or array specifying the width, height, and depth/array layer count of the texture. The width value must always be specified, while the height and depth/array layer count values are optional and will default to 1 if omitted. - What follows is a sample `size` array: - - ```js - size: [16, 16, 2]; - ``` - - The object equivalent would look like this: - - ```js - size: { - width: 16, - height: 16, - depthOrArrayLayers: 2 - } - ``` + For example, you can pass an array like `[16, 16, 2]`, or its equivalent object `{ width: 16, height: 16, depthOrArrayLayers: 2 }`. - `usage` - : The {{glossary("Bitwise_flags", "bitwise flags")}} representing the allowed usages for the `GPUTexture`. The possible values are in the [`GPUTexture.usage` value table](/en-US/docs/Web/API/GPUTexture/usage#value). - Note that multiple possible usages can be specified by separating values with pipe symbols, for example: - - ```js - usage: GPUTextureUsage.COPY_DST | GPUTextureUsage.RENDER_ATTACHMENT; - ``` + Note that multiple possible usages can be specified by separating values with [bitwise OR](/en-US/docs/Web/JavaScript/Reference/Operators/Bitwise_OR), for example: `GPUTextureUsage.COPY_DST | GPUTextureUsage.RENDER_ATTACHMENT`. > [!NOTE] > @@ -139,7 +121,7 @@ In the WebGPU samples [Textured Cube sample](https://webgpu.github.io/webgpu-sam - Copying the image bitmap into the texture using {{domxref("GPUQueue.copyExternalImageToTexture()")}}. ```js -//... +// … let cubeTexture; @@ -167,7 +149,7 @@ let cubeTexture; ); } -//... +// … ``` ## Specifications diff --git a/files/en-us/web/api/gpudevice/features/index.md b/files/en-us/web/api/gpudevice/features/index.md index f0e321d454669a0..a55a3b4ef5cfd1f 100644 --- a/files/en-us/web/api/gpudevice/features/index.md +++ b/files/en-us/web/api/gpudevice/features/index.md @@ -11,7 +11,7 @@ browser-compat: api.GPUDevice.features {{APIRef("WebGPU API")}}{{SeeCompatTable}}{{SecureContext_Header}}{{AvailableInWorkers}} The **`features`** read-only property of the -{{domxref("GPUDevice")}} interface returns a {{domxref("GPUSupportedFeatures")}} object that describes additional functionality supported by the device. Only features requested during the creation of the device (i.e. when {{domxref("GPUAdapter.requestDevice()")}} is called) are included. +{{domxref("GPUDevice")}} interface returns a {{domxref("GPUSupportedFeatures")}} object that describes additional functionality supported by the device. Only features requested during the creation of the device (i.e., when {{domxref("GPUAdapter.requestDevice()")}} is called) are included. > [!NOTE] > Not all features will be available to WebGPU in all browsers that support it, even if the features are supported by the underlying hardware. See {{domxref("GPUAdapter.features")}} for more details. @@ -51,7 +51,7 @@ async function init() { console.log(value); }); - // ... + // … } ``` diff --git a/files/en-us/web/api/gpudevice/importexternaltexture/index.md b/files/en-us/web/api/gpudevice/importexternaltexture/index.md index 2a218c66d699e74..fbf7615464d538d 100644 --- a/files/en-us/web/api/gpudevice/importexternaltexture/index.md +++ b/files/en-us/web/api/gpudevice/importexternaltexture/index.md @@ -43,7 +43,7 @@ Note that the moment when the {{domxref("GPUExternalTexture")}} object expires ( The following criteria must be met when calling **`importExternalTexture()`**, otherwise a {{domxref("GPUValidationError")}} is generated and an invalid {{domxref("GPUExternalTexture")}} object is returned: -- The video snapshot is usable (e.g. the video source is loaded properly, and doesn't have a width or height of 0). +- The video snapshot is usable (e.g., the video source is loaded properly, and doesn't have a width or height of 0). ### Exceptions @@ -55,7 +55,7 @@ The following criteria must be met when calling **`importExternalTexture()`**, o In the WebGPU samples [Video Uploading sample](https://webgpu.github.io/webgpu-samples/samples/videoUploading/), an `importExternalTexture()` call is used as the value of a bind group entry `resource`, specified when creating a {{domxref("GPUBindGroup")}} via a {{domxref("GPUDevice.createBindGroup()")}} call: ```js -//... +// … const uniformBindGroup = device.createBindGroup({ layout: pipeline.getBindGroupLayout(0), @@ -73,7 +73,7 @@ const uniformBindGroup = device.createBindGroup({ ], }); -//... +// … ``` ## Specifications diff --git a/files/en-us/web/api/gpudevice/index.md b/files/en-us/web/api/gpudevice/index.md index 2d8e9eb52f0c87f..363cc490e02e068 100644 --- a/files/en-us/web/api/gpudevice/index.md +++ b/files/en-us/web/api/gpudevice/index.md @@ -19,6 +19,10 @@ A `GPUDevice` object is requested using the {{domxref("GPUAdapter.requestDevice( _Inherits properties from its parent, {{DOMxRef("EventTarget")}}._ +- {{domxref("GPUDevice.adapterInfo", "adapterInfo")}} {{Experimental_Inline}} {{ReadOnlyInline}} + + - : A {{domxref("GPUAdapterInfo")}} object containing identifying information about the device's originating adapter. + - {{domxref("GPUDevice.features", "features")}} {{Experimental_Inline}} {{ReadOnlyInline}} - : A {{domxref("GPUSupportedFeatures")}} object that describes additional functionality supported by the device. @@ -137,7 +141,7 @@ async function init() { code: shaders, }); - //... + // … } ``` diff --git a/files/en-us/web/api/gpudevice/label/index.md b/files/en-us/web/api/gpudevice/label/index.md index 521e14002a883f3..9810b3272b281fc 100644 --- a/files/en-us/web/api/gpudevice/label/index.md +++ b/files/en-us/web/api/gpudevice/label/index.md @@ -39,7 +39,7 @@ async function init() { // Get a label console.log(device.label); - // ... + // … } ``` diff --git a/files/en-us/web/api/gpudevice/limits/index.md b/files/en-us/web/api/gpudevice/limits/index.md index 55eacce58ff6feb..d47655aa9fec551 100644 --- a/files/en-us/web/api/gpudevice/limits/index.md +++ b/files/en-us/web/api/gpudevice/limits/index.md @@ -11,7 +11,7 @@ browser-compat: api.GPUDevice.limits {{APIRef("WebGPU API")}}{{SeeCompatTable}}{{SecureContext_Header}}{{AvailableInWorkers}} The **`limits`** read-only property of the -{{domxref("GPUDevice")}} interface returns a {{domxref("GPUSupportedLimits")}} object that describes the limits supported by the device. All limit values will be included, and the limits requested during the creation of the device (i.e. when {{domxref("GPUAdapter.requestDevice()")}} is called) will be reflected in those values. +{{domxref("GPUDevice")}} interface returns a {{domxref("GPUSupportedLimits")}} object that describes the limits supported by the device. All limit values will be included, and the limits requested during the creation of the device (i.e., when {{domxref("GPUAdapter.requestDevice()")}} is called) will be reflected in those values. > [!NOTE] > Not all limits will be reported as expected, even if they are supported by the underlying hardware. See {{domxref("GPUAdapter.limits")}} for more details. @@ -50,7 +50,7 @@ async function init() { console.log(device.limits.maxBindGroups); - // ... + // … } ``` diff --git a/files/en-us/web/api/gpudevice/lost/index.md b/files/en-us/web/api/gpudevice/lost/index.md index 717c07f421538ba..78b4021ad2e8ba4 100644 --- a/files/en-us/web/api/gpudevice/lost/index.md +++ b/files/en-us/web/api/gpudevice/lost/index.md @@ -13,12 +13,12 @@ browser-compat: api.GPUDevice.lost The **`lost`** read-only property of the {{domxref("GPUDevice")}} interface contains a {{jsxref("Promise")}} that remains pending throughout the device's lifetime and resolves with a {{domxref("GPUDeviceLostInfo")}} object when the device is lost. -{{domxref("GPUAdapter.requestDevice()")}} will never return `null`, and it will reject only if the request is invalid, i.e. it exceeds the capabilities of the {{domxref("GPUAdapter")}}. If a valid device request can't be fulfilled for some reason however it may resolve to a device that has already been lost. Additionally, devices can be lost at any time after creation for a variety of reasons (such as browser resource management or driver updates), so it's a good idea to always handle lost devices gracefully. +{{domxref("GPUAdapter.requestDevice()")}} will never return `null`, and it will reject only if the request is invalid, i.e., it exceeds the capabilities of the {{domxref("GPUAdapter")}}. If a valid device request can't be fulfilled for some reason however it may resolve to a device that has already been lost. Additionally, devices can be lost at any time after creation for a variety of reasons (such as browser resource management or driver updates), so it's a good idea to always handle lost devices gracefully. -Many causes for lost devices are transient, so you should try getting a new device once a previous one has been lost unless the loss was caused by the application intentionally destroying the device (i.e. with {{domxref("GPUDevice.destroy()")}}). Note that any WebGPU resources created with a previous device (buffers, textures, etc.) will need to be re-created with the new one. +Many causes for lost devices are transient, so you should try getting a new device once a previous one has been lost unless the loss was caused by the application intentionally destroying the device (i.e., with {{domxref("GPUDevice.destroy()")}}). Note that any WebGPU resources created with a previous device (buffers, textures, etc.) will need to be re-created with the new one. > [!NOTE] -> Also bear in mind that a `GPUAdapter` may become unavailable, e.g. if the physical GPU is unplugged from the system or disabled to save power. From then on, the adapter can no longer return valid devices, and will always return already-lost devices. +> Also bear in mind that a `GPUAdapter` may become unavailable, e.g., if the physical GPU is unplugged from the system or disabled to save power. From then on, the adapter can no longer return valid devices, and will always return already-lost devices. ## Value @@ -50,7 +50,7 @@ async function init() { } }); - // ... + // … } ``` diff --git a/files/en-us/web/api/gpudevice/queue/index.md b/files/en-us/web/api/gpudevice/queue/index.md index b604b8972d26226..6d11615023172f3 100644 --- a/files/en-us/web/api/gpudevice/queue/index.md +++ b/files/en-us/web/api/gpudevice/queue/index.md @@ -35,13 +35,13 @@ async function init() { // Create a GPUDevice const device = await adapter.requestDevice(); - // ... + // … // Common queue use — end current frame by passing array of // command buffers to queue for execution device.queue.submit([commandEncoder.finish()]); - // ... + // … } ``` diff --git a/files/en-us/web/api/gpudevice/uncapturederror_event/index.md b/files/en-us/web/api/gpudevice/uncapturederror_event/index.md index a3be981fcb69d13..87b5de83d89ac6a 100644 --- a/files/en-us/web/api/gpudevice/uncapturederror_event/index.md +++ b/files/en-us/web/api/gpudevice/uncapturederror_event/index.md @@ -18,10 +18,10 @@ Known error cases should be handled using {{domxref("GPUDevice.pushErrorScope", Use the event name in methods like {{domxref("EventTarget.addEventListener", "addEventListener()")}}, or set an event handler property. -```js -addEventListener("uncapturederror", (event) => {}); +```js-nolint +addEventListener("uncapturederror", (event) => { }) -onuncapturederror = (event) => {}; +onuncapturederror = (event) => { } ``` ## Event type diff --git a/files/en-us/web/api/gpudevicelostinfo/index.md b/files/en-us/web/api/gpudevicelostinfo/index.md index 8af221dd5a4e397..db93524229562d7 100644 --- a/files/en-us/web/api/gpudevicelostinfo/index.md +++ b/files/en-us/web/api/gpudevicelostinfo/index.md @@ -45,7 +45,7 @@ async function init() { init(); } }); - // ... + // … } ``` diff --git a/files/en-us/web/api/gpuexternaltexture/index.md b/files/en-us/web/api/gpuexternaltexture/index.md index 1e4c4ee3cdf82f5..652fadc202b371c 100644 --- a/files/en-us/web/api/gpuexternaltexture/index.md +++ b/files/en-us/web/api/gpuexternaltexture/index.md @@ -25,7 +25,7 @@ A `GPUExternalTexture` object instance is created using {{domxref("GPUDevice.imp In the WebGPU samples [Video Uploading sample](https://webgpu.github.io/webgpu-samples/samples/videoUploading/), a `GPUExternalTexture` object (created via a {{domxref("GPUDevice.importExternalTexture()")}} call) is used as the value of a bind group entry `resource`, specified when creating a {{domxref("GPUBindGroup")}} via a {{domxref("GPUDevice.createBindGroup()")}} call: ```js -//... +// … const uniformBindGroup = device.createBindGroup({ layout: pipeline.getBindGroupLayout(0), entries: [ @@ -41,7 +41,7 @@ const uniformBindGroup = device.createBindGroup({ }, ], }); -//... +// … ``` ## Specifications diff --git a/files/en-us/web/api/gpuexternaltexture/label/index.md b/files/en-us/web/api/gpuexternaltexture/label/index.md index 43b24daa801e929..5a09d9e9a58905a 100644 --- a/files/en-us/web/api/gpuexternaltexture/label/index.md +++ b/files/en-us/web/api/gpuexternaltexture/label/index.md @@ -24,7 +24,7 @@ A string. If this has not been previously set as described above, it will be an Setting and getting a label via `GPUExternalTexture.label`: ```js -// ... +// … const externalTexture = device.importExternalTexture({ source: video, @@ -38,7 +38,7 @@ console.log(externalTexture.label); // "my_ext_texture" Setting a label via the originating {{domxref("GPUDevice.importExternalTexture()")}} call, and then getting it via `GPUExternalTexture.label`: ```js -// ... +// … const externalTexture = device.importExternalTexture({ source: video, diff --git a/files/en-us/web/api/gpuinternalerror/index.md b/files/en-us/web/api/gpuinternalerror/index.md index a2aca3a607d090b..1e0c93d708c171a 100644 --- a/files/en-us/web/api/gpuinternalerror/index.md +++ b/files/en-us/web/api/gpuinternalerror/index.md @@ -36,7 +36,7 @@ The following example uses an error scope to capture a suspected validation erro ```js device.pushErrorScope("internal"); -const module = device.createShaderModule({ +let module = device.createShaderModule({ code: shader, // REALLY complex shader }); diff --git a/files/en-us/web/api/gpupipelineerror/index.md b/files/en-us/web/api/gpupipelineerror/index.md index 434ff18d5c3b544..70077a5c88bfd9c 100644 --- a/files/en-us/web/api/gpupipelineerror/index.md +++ b/files/en-us/web/api/gpupipelineerror/index.md @@ -32,7 +32,7 @@ _Inherits properties from its parent, {{domxref("DOMException")}}._ In the following snippet we are attempting to create a {{domxref("GPUComputePipeline")}} using {{domxref("GPUDevice.createComputePipelineAsync()")}}. However, we have misspelt our compute pipeline `entryPoint` as `"maijn"` (it should be `"main"`), therefore pipeline creation fails, and our `catch` block prints the resulting reason and error message to the console. ```js -// ... +// … let computePipeline; @@ -52,7 +52,7 @@ try { console.error(`Pipeline creation failed: ${error.message}`); } -// ... +// … ``` In this case, the given `reason` is `"Validation"`, and the `message` is `"Entry point "maijn" doesn't exist in the shader module [ShaderModule]."` diff --git a/files/en-us/web/api/gpupipelinelayout/index.md b/files/en-us/web/api/gpupipelinelayout/index.md index 1d22e1c917a085c..7c164c0790a0220 100644 --- a/files/en-us/web/api/gpupipelinelayout/index.md +++ b/files/en-us/web/api/gpupipelinelayout/index.md @@ -33,7 +33,7 @@ The following snippet: - Creates a `GPUPipelineLayout` based on the {{domxref("GPUBindGroupLayout")}}. ```js -// ... +// … const bindGroupLayout = device.createBindGroupLayout({ entries: [ @@ -59,7 +59,7 @@ const pipelineLayout = device.createPipelineLayout({ bindGroupLayouts: [bindGroupLayout], }); -// ... +// … ``` ## Specifications diff --git a/files/en-us/web/api/gpupipelinelayout/label/index.md b/files/en-us/web/api/gpupipelinelayout/label/index.md index 2d00a17024acbb4..d007f687a552fec 100644 --- a/files/en-us/web/api/gpupipelinelayout/label/index.md +++ b/files/en-us/web/api/gpupipelinelayout/label/index.md @@ -24,7 +24,7 @@ A string. If this has not been previously set as described above, it will be an Setting and getting a label via `GPUPipelineLayout.label`: ```js -// ... +// … const pipelineLayout = device.createPipelineLayout({ bindGroupLayouts: [bindGroupLayout], @@ -38,7 +38,7 @@ console.log(pipelineLayout.label); // "my_pipeline_layout" Setting a label via the originating {{domxref("GPUDevice.createPipelineLayout()")}} call, and then getting it via `GPUPipelineLayout.label`: ```js -// ... +// … const pipelineLayout = device.createPipelineLayout({ bindGroupLayouts: [bindGroupLayout], diff --git a/files/en-us/web/api/gpuqueue/copyexternalimagetotexture/index.md b/files/en-us/web/api/gpuqueue/copyexternalimagetotexture/index.md index f9bc92f5dbf7dd9..0f8bb2e58058c94 100644 --- a/files/en-us/web/api/gpuqueue/copyexternalimagetotexture/index.md +++ b/files/en-us/web/api/gpuqueue/copyexternalimagetotexture/index.md @@ -33,20 +33,7 @@ copyExternalImageToTexture(source, destination, copySize) - : An object or array specifying the origin of the copy — the top-left corner of the source sub-region to copy from. Together with `copySize`, this defines the full extent of the source sub-region. The `x` and `y` values default to 0 if any of all of `origin` is omitted. - What follows is a sample array: - - ```js - origin: [0, 0]; - ``` - - The object equivalent would look like this: - - ```js - origin: { - x: 0, - y: 0 - } - ``` + For example, you can pass an array like `[0, 0]`, or its equivalent object `{ x: 0, y: 0 }`. - `flipY` {{optional_inline}} - : A boolean. If set to `true`, the image capture is flipped vertically. If omitted, `flipY` defaults to `false`. @@ -81,21 +68,7 @@ copyExternalImageToTexture(source, destination, copySize) - : An object or array specifying the origin of the copy — the minimum corner of the texture region to write the image data to. Together with `copySize`, this defines the full extent of the region to copy to. The `x`, `y`, and `z` values default to 0 if any of all of `origin` is omitted. - What follows is a sample array: - - ```js - origin: [0, 0, 0]; - ``` - - The object equivalent would look like this: - - ```js - origin: { - x: 0, - y: 0, - z: 0 - } - ``` + For example, you can pass an array like `[0, 0, 0]`, or its equivalent object `{ x: 0, y: 0, z: 0 }`. - `premultipliedAlpha` {{optional_inline}} @@ -111,21 +84,7 @@ copyExternalImageToTexture(source, destination, copySize) - : An object or array specifying `width`, `height`, and `depthOrArrayLayers` — of the region to copy from/to. - What follows is a sample array: - - ```js - origin: [16, 1, 1]; - ``` - - The object equivalent would look like this: - - ```js - origin: { - width: 16, - height: 1, - depthOrArrayLayers: 1 - } - ``` + For example, you can pass an array like `[16, 1, 1]`, or its equivalent object `{ width: 16, height: 1, depthOrArrayLayers: 1 }`. The `width` value has to be included. If the `height` or `depthOrArrayLayers` values are omitted, they default to 1. diff --git a/files/en-us/web/api/gpuqueue/onsubmittedworkdone/index.md b/files/en-us/web/api/gpuqueue/onsubmittedworkdone/index.md index b636787bfcd2dd8..b89ff7ea02fd86c 100644 --- a/files/en-us/web/api/gpuqueue/onsubmittedworkdone/index.md +++ b/files/en-us/web/api/gpuqueue/onsubmittedworkdone/index.md @@ -15,8 +15,7 @@ The **`onSubmittedWorkDone()`** method of the This includes the completion of any {{domxref("GPUBuffer.mapAsync", "mapAsync()")}} calls made on `GPUBuffer`s used in commands submitted to the queue, before `onSubmittedWorkDone()` is called. -Note: In most cases, you do _not_ need to call `onSubmittedWorkDone()`. You do **_not_** need to call it for mapping a buffer. `mapAsync` guarantees work submitted -to the queue before calling `mapAsync` happens before the `mapAsync` returns (see [WebGPU spec: section 5.2](https://www.w3.org/TR/webgpu/#buffer-mapping)) +Note: In most cases, you do _not_ need to call `onSubmittedWorkDone()`. You do **_not_** need to call it for mapping a buffer. `mapAsync` guarantees work submitted to the queue before calling `mapAsync` happens before the `mapAsync` returns (see [WebGPU spec](https://gpuweb.github.io/gpuweb/#buffer-mapping)). The two use cases for `onSubmittedWorkDone` diff --git a/files/en-us/web/api/gpuqueue/submit/index.md b/files/en-us/web/api/gpuqueue/submit/index.md index 56ae00ff88e9fe8..d7d4575cd3453b0 100644 --- a/files/en-us/web/api/gpuqueue/submit/index.md +++ b/files/en-us/web/api/gpuqueue/submit/index.md @@ -33,7 +33,7 @@ None ({{jsxref("Undefined")}}). The following criteria must be met when calling **`submit()`**, otherwise a {{domxref("GPUValidationError")}} is generated and the {{domxref("GPUQueue")}} becomes invalid: - The array of {{domxref("GPUCommandBuffer")}} objects referenced in the `submit()` call does not contain duplicates. -- Any {{domxref("GPUBuffer")}}, {{domxref("GPUTexture")}}, and {{domxref("GPUQuerySet")}} objects used in the encoded commands are available for use, i.e. not unavailable (`GPUBuffer`s are unavailable if they are currently {{domxref("GPUBuffer.mapAsync", "mapped", "", "nocode")}}) or destroyed (with the `destroy()` method). +- Any {{domxref("GPUBuffer")}}, {{domxref("GPUTexture")}}, and {{domxref("GPUQuerySet")}} objects used in the encoded commands are available for use, i.e., not unavailable (`GPUBuffer`s are unavailable if they are currently {{domxref("GPUBuffer.mapAsync", "mapped", "", "nocode")}}) or destroyed (with the `destroy()` method). - Any {{domxref("GPUExternalTexture")}} objects used in the encoded commands are not expired (they expire automatically shortly after being imported via {{domxref("GPUDevice.importExternalTexture", "importExternalTexture()")}}). - If a {{domxref("GPUQuerySet")}} object used in an encoded command is of type `"occlusion"` query, it is not already used, except by {{domxref("GPURenderPassEncoder.beginOcclusionQuery()")}}. @@ -42,7 +42,7 @@ The following criteria must be met when calling **`submit()`**, otherwise a {{do In our [basic render demo](https://mdn.github.io/dom-examples/webgpu-render-demo/), a number of commands are recorded via a {{domxref("GPUCommandEncoder")}}: ```js -// ... +// … // Create GPUCommandEncoder const commandEncoder = device.createCommandEncoder(); @@ -72,7 +72,7 @@ passEncoder.draw(3); passEncoder.end(); -// ... +// … ``` The commands encoded by the {{domxref("GPUCommandEncoder")}} are recoded into a {{domxref("GPUCommandBuffer")}} using the {{domxref("GPUCommandEncoder.finish()")}} method. The command buffer is then passed into the queue via a `submit()` call, ready to be processed by the GPU. diff --git a/files/en-us/web/api/gpuqueue/writebuffer/index.md b/files/en-us/web/api/gpuqueue/writebuffer/index.md index 1dbed95c3f58a23..fc8ee25911a17eb 100644 --- a/files/en-us/web/api/gpuqueue/writebuffer/index.md +++ b/files/en-us/web/api/gpuqueue/writebuffer/index.md @@ -50,7 +50,7 @@ None ({{jsxref("Undefined")}}). The following criteria must be met when calling **`writeBuffer()`**, otherwise a {{domxref("GPUValidationError")}} is generated and the {{domxref("GPUQueue")}} becomes invalid: -- `buffer` is available for use, i.e. not unavailable (`GPUBuffer`s are unavailable if they are currently {{domxref("GPUBuffer.mapAsync", "mapped", "", "nocode")}}) or destroyed (with the {{domxref("GPUBuffer.destroy()")}} method). +- `buffer` is available for use, i.e., not unavailable (`GPUBuffer`s are unavailable if they are currently {{domxref("GPUBuffer.mapAsync", "mapped", "", "nocode")}}) or destroyed (with the {{domxref("GPUBuffer.destroy()")}} method). - The `buffer`'s {{domxref("GPUBuffer.usage")}} includes the `GPUBufferUsage.COPY_DST` flag. - `bufferOffset`, when converted to bytes, is a multiple of 4. - The size of `data` - `dataOffset` + `bufferOffset`, when converted to bytes, is equal to or less than the `buffer`'s {{domxref("GPUBuffer.size")}}. diff --git a/files/en-us/web/api/gpuqueue/writetexture/index.md b/files/en-us/web/api/gpuqueue/writetexture/index.md index b788c8900c37c8b..7b33209763f98c8 100644 --- a/files/en-us/web/api/gpuqueue/writetexture/index.md +++ b/files/en-us/web/api/gpuqueue/writetexture/index.md @@ -46,21 +46,7 @@ writeTexture(destination, data, dataLayout, size) - : An object or array specifying the origin of the copy — the minimum corner of the texture region to write the data to. Together with `size`, this defines the full extent of the region to copy to. The `x`, `y`, and `z` values default to 0 if any of all of `origin` is omitted. - What follows is a sample array: - - ```js - origin: [0, 0, 0]; - ``` - - The object equivalent would look like this: - - ```js - origin: { - x: 0, - y: 0, - z: 0 - } - ``` + For example, you can pass an array like `[0, 0, 0]`, or its equivalent object `{ x: 0, y: 0, z: 0 }`. - `texture` - : A {{domxref("GPUTexture")}} object representing the texture to write the data to. @@ -72,7 +58,7 @@ writeTexture(destination, data, dataLayout, size) - `offset` {{optional_inline}} - : The offset, in bytes, from the beginning of `data` to the start of the image data to be copied. If omitted, `offset` defaults to 0. - `bytesPerRow` {{optional_inline}} - - : A number representing the stride, in bytes, between the start of each block row (i.e. a row of complete texel blocks) and the subsequent block row. This is required if there are multiple block rows (i.e. the copy height or depth is more than one block). + - : A number representing the stride, in bytes, between the start of each block row (i.e., a row of complete texel blocks) and the subsequent block row. This is required if there are multiple block rows (i.e., the copy height or depth is more than one block). - `rowsPerImage` {{optional_inline}} - : The number of block rows per single image of the texture. `bytesPerRow` &times; `rowsPerImage` will give you the stride, in bytes, between the start of each complete image. This is required if there are multiple images to copy. - `size` diff --git a/files/en-us/web/api/gpurenderbundle/index.md b/files/en-us/web/api/gpurenderbundle/index.md index 8c390093eec51ed..a304dfdc4fc4170 100644 --- a/files/en-us/web/api/gpurenderbundle/index.md +++ b/files/en-us/web/api/gpurenderbundle/index.md @@ -65,7 +65,7 @@ const renderBundle = renderBundleEncoder.finish(); {{domxref("GPURenderPassEncoder.executeBundles()")}} is then used to reuse the work across multiple render passes to improve performance. Study the example code listing for the full context. ```js -// ... +// … return function doDraw(timestamp) { if (startTime === undefined) { @@ -91,7 +91,7 @@ return function doDraw(timestamp) { device.queue.submit([commandEncoder.finish()]); }; -// ... +// … ``` ## Specifications diff --git a/files/en-us/web/api/gpurenderbundleencoder/drawindexed/index.md b/files/en-us/web/api/gpurenderbundleencoder/drawindexed/index.md index 3dd4f02ec07f634..63cb7462593d3c2 100644 --- a/files/en-us/web/api/gpurenderbundleencoder/drawindexed/index.md +++ b/files/en-us/web/api/gpurenderbundleencoder/drawindexed/index.md @@ -46,7 +46,7 @@ None ({{jsxref("Undefined")}}). ## Examples ```js -// ... +// … const bundleEncoder = device.createRenderBundleEncoder(descriptor); @@ -59,7 +59,7 @@ bundleEncoder.drawIndexed(indexCount); const renderBundle = bundleEncoder.finish(); -// ... +// … ``` ## Specifications diff --git a/files/en-us/web/api/gpurenderbundleencoder/drawindexedindirect/index.md b/files/en-us/web/api/gpurenderbundleencoder/drawindexedindirect/index.md index 06790f2e83eb612..31674fe44a6d1bd 100644 --- a/files/en-us/web/api/gpurenderbundleencoder/drawindexedindirect/index.md +++ b/files/en-us/web/api/gpurenderbundleencoder/drawindexedindirect/index.md @@ -61,7 +61,7 @@ The following criteria must be met when calling **`drawIndirect()`**, otherwise ## Examples ```js -// ... +// … // Create GPURenderBundleEncoder const bundleEncoder = device.createRenderBundleEncoder(descriptor); @@ -92,7 +92,7 @@ bundleEncoder.drawIndexedIndirect(drawValues, 0); // End the bundle recording const renderBundle = bundleEncoder.finish(); -// ... +// … ``` ## Specifications diff --git a/files/en-us/web/api/gpurenderbundleencoder/drawindirect/index.md b/files/en-us/web/api/gpurenderbundleencoder/drawindirect/index.md index 2df5a2fc8a9ca48..d4144584678aaab 100644 --- a/files/en-us/web/api/gpurenderbundleencoder/drawindirect/index.md +++ b/files/en-us/web/api/gpurenderbundleencoder/drawindirect/index.md @@ -60,7 +60,7 @@ The following criteria must be met when calling **`drawIndirect()`**, otherwise ## Examples ```js -// ... +// … // Create GPURenderBundleEncoder const bundleEncoder = device.createRenderBundleEncoder(descriptor); @@ -89,7 +89,7 @@ bundleEncoder.drawIndirect(drawValues, 0); // End the bundle recording const renderBundle = bundleEncoder.finish(); -// ... +// … ``` ## Specifications diff --git a/files/en-us/web/api/gpurenderbundleencoder/finish/index.md b/files/en-us/web/api/gpurenderbundleencoder/finish/index.md index deaa26caa6da74f..6beae08af92661c 100644 --- a/files/en-us/web/api/gpurenderbundleencoder/finish/index.md +++ b/files/en-us/web/api/gpurenderbundleencoder/finish/index.md @@ -34,8 +34,8 @@ A {{domxref("GPURenderBundle")}} object instance. The following criteria must be met when calling **`finish()`**, otherwise a {{domxref("GPUValidationError")}} is generated and the {{domxref("GPURenderBundleEncoder")}} becomes invalid: -- The {{domxref("GPURenderBundleEncoder")}} is open (i.e. not already ended via a `finish()` call). -- The debug stack for the current render pass is empty (i.e. no render pass debug group is currently open, as opened by {{domxref("GPURenderBundleEncoder.pushDebugGroup", "pushDebugGroup()")}}). +- The {{domxref("GPURenderBundleEncoder")}} is open (i.e., not already ended via a `finish()` call). +- The debug stack for the current render pass is empty (i.e., no render pass debug group is currently open, as opened by {{domxref("GPURenderBundleEncoder.pushDebugGroup", "pushDebugGroup()")}}). ## Examples diff --git a/files/en-us/web/api/gpurenderbundleencoder/index.md b/files/en-us/web/api/gpurenderbundleencoder/index.md index 1ea5fc95d094095..b52c9f65c80c648 100644 --- a/files/en-us/web/api/gpurenderbundleencoder/index.md +++ b/files/en-us/web/api/gpurenderbundleencoder/index.md @@ -110,7 +110,7 @@ const renderBundle = renderBundleEncoder.finish(); {{domxref("GPURenderPassEncoder.executeBundles()")}} is then used to reuse the work across multiple render passes to improve performance. Study the example code listing for the full context. ```js -// ... +// … return function doDraw(timestamp) { if (startTime === undefined) { @@ -136,7 +136,7 @@ return function doDraw(timestamp) { device.queue.submit([commandEncoder.finish()]); }; -// ... +// … ``` ## Specifications diff --git a/files/en-us/web/api/gpurenderbundleencoder/insertdebugmarker/index.md b/files/en-us/web/api/gpurenderbundleencoder/insertdebugmarker/index.md index 586c8efa514c677..294bb6ee76054f7 100644 --- a/files/en-us/web/api/gpurenderbundleencoder/insertdebugmarker/index.md +++ b/files/en-us/web/api/gpurenderbundleencoder/insertdebugmarker/index.md @@ -36,11 +36,11 @@ None ({{jsxref("Undefined")}}). ## Examples ```js -// ... +// … bundleEncoder.insertDebugMarker("my_marker"); -// ... +// … ``` ## Specifications diff --git a/files/en-us/web/api/gpurenderbundleencoder/popdebuggroup/index.md b/files/en-us/web/api/gpurenderbundleencoder/popdebuggroup/index.md index 0eaffc24fa62588..ebfdbc27827361e 100644 --- a/files/en-us/web/api/gpurenderbundleencoder/popdebuggroup/index.md +++ b/files/en-us/web/api/gpurenderbundleencoder/popdebuggroup/index.md @@ -36,12 +36,12 @@ None ({{jsxref("Undefined")}}). The following criteria must be met when calling **`popDebugGroup()`**, otherwise a {{domxref("GPUValidationError")}} is generated and the {{domxref("GPURenderBundleEncoder")}} becomes invalid: -- The render bundle encoder's debug stack is not empty (i.e. at least one render bundle debug group was previously started with {{domxref("GPURenderBundleEncoder.pushDebugGroup", "pushDebugGroup()")}}). +- The render bundle encoder's debug stack is not empty (i.e., at least one render bundle debug group was previously started with {{domxref("GPURenderBundleEncoder.pushDebugGroup", "pushDebugGroup()")}}). ## Examples ```js -// ... +// … const bundleEncoder = device.createRenderBundleEncoder(renderBundleDescriptor); @@ -53,7 +53,7 @@ bundleEncoder.draw(3); bundleEncoder.popDebugGroup(); -// ... +// … ``` ## Specifications diff --git a/files/en-us/web/api/gpurenderbundleencoder/pushdebuggroup/index.md b/files/en-us/web/api/gpurenderbundleencoder/pushdebuggroup/index.md index cb1aa3c73a6f12a..7ca1feb5523153a 100644 --- a/files/en-us/web/api/gpurenderbundleencoder/pushdebuggroup/index.md +++ b/files/en-us/web/api/gpurenderbundleencoder/pushdebuggroup/index.md @@ -36,7 +36,7 @@ None ({{jsxref("Undefined")}}). ## Examples ```js -// ... +// … const bundleEncoder = device.createRenderBundleEncoder(renderBundleDescriptor); @@ -48,7 +48,7 @@ bundleEncoder.draw(3); bundleEncoder.popDebugGroup(); -// ... +// … ``` ## Specifications diff --git a/files/en-us/web/api/gpurenderbundleencoder/setbindgroup/index.md b/files/en-us/web/api/gpurenderbundleencoder/setbindgroup/index.md index 049297418196f83..7c5a21f4cb908f9 100644 --- a/files/en-us/web/api/gpurenderbundleencoder/setbindgroup/index.md +++ b/files/en-us/web/api/gpurenderbundleencoder/setbindgroup/index.md @@ -32,7 +32,7 @@ setBindGroup(index, bindGroup, dynamicOffsets, dynamicOffsetsStart, - `bindGroup` - : The {{domxref("GPUBindGroup")}} to use for subsequent render bundle commands, or `null`, in which case any previously-set bind group in the given slot is unset. - `dynamicOffsets` {{optional_inline}} - - : A value specifying the offset, in bytes, for each entry in `bindGroup` with `hasDynamicOffset: true` set (i.e. in the descriptor of the {{domxref("GPUDevice.createBindGroupLayout()")}} call that created the {{domxref("GPUBindGroupLayout")}} object that the `bindGroup` is based on). This value can be: + - : A value specifying the offset, in bytes, for each entry in `bindGroup` with `hasDynamicOffset: true` set (i.e., in the descriptor of the {{domxref("GPUDevice.createBindGroupLayout()")}} call that created the {{domxref("GPUBindGroupLayout")}} object that the `bindGroup` is based on). This value can be: - An array of numbers specifying the different offsets. - A {{jsxref("Uint32Array")}} containing numbers specifying the offsets. diff --git a/files/en-us/web/api/gpurenderbundleencoder/setindexbuffer/index.md b/files/en-us/web/api/gpurenderbundleencoder/setindexbuffer/index.md index 4f90f65fd36005c..6658331216baf13 100644 --- a/files/en-us/web/api/gpurenderbundleencoder/setindexbuffer/index.md +++ b/files/en-us/web/api/gpurenderbundleencoder/setindexbuffer/index.md @@ -54,7 +54,7 @@ The following criteria must be met when calling **`setIndexBuffer()`**, otherwis ## Examples ```js -// ... +// … const bundleEncoder = device.createRenderBundleEncoder(descriptor); @@ -67,7 +67,7 @@ bundleEncoder.drawIndexed(indexCount); const renderBundle = bundleEncoder.finish(); -// ... +// … ``` ## Specifications diff --git a/files/en-us/web/api/gpurenderpassencoder/beginocclusionquery/index.md b/files/en-us/web/api/gpurenderpassencoder/beginocclusionquery/index.md index 37f14f6ccd2f9e8..cb9f47517d2c30a 100644 --- a/files/en-us/web/api/gpurenderpassencoder/beginocclusionquery/index.md +++ b/files/en-us/web/api/gpurenderpassencoder/beginocclusionquery/index.md @@ -35,12 +35,12 @@ The following criteria must be met when calling **`beginOcclusionQuery()`**, oth - A {{domxref("GPUQuerySet")}} was specified in the `occlusionQuerySet` descriptor property when invoking the originating {{domxref("GPUCommandEncoder.beginRenderPass()")}}. - `queryIndex` is smaller than {{domxref("GPUQuerySet.count")}}. - The `queryIndex` has not already been written to in the same render pass. -- An occlusion query is not already active for this render pass (i.e. via a previous `beginOcclusionQuery()` call). +- An occlusion query is not already active for this render pass (i.e., via a previous `beginOcclusionQuery()` call). ## Examples ```js -// ... +// … // Create a query set to hold the occlusion queries const querySet = device.createQuerySet({ @@ -75,7 +75,7 @@ passEncoder.draw(3); // End the occlusion query passEncoder.endOcclusionQuery(); -// ... +// … ``` ## Specifications diff --git a/files/en-us/web/api/gpurenderpassencoder/draw/index.md b/files/en-us/web/api/gpurenderpassencoder/draw/index.md index a9256e51264a610..43447a21b94a5c5 100644 --- a/files/en-us/web/api/gpurenderpassencoder/draw/index.md +++ b/files/en-us/web/api/gpurenderpassencoder/draw/index.md @@ -42,7 +42,7 @@ None ({{jsxref("Undefined")}}). In our [basic render demo](https://mdn.github.io/dom-examples/webgpu-render-demo/), several commands are recorded via a {{domxref("GPUCommandEncoder")}}. Most of these commands originate from the `GPURenderPassEncoder` created via {{domxref("GPUCommandEncoder.beginRenderPass()")}}. `draw()` is used to specify that three vertices should be drawn to create our triangle. ```js -// ... +// … const renderPipeline = device.createRenderPipeline(pipelineDescriptor); @@ -75,7 +75,7 @@ passEncoder.end(); // End frame by passing array of command buffers to command queue for execution device.queue.submit([commandEncoder.finish()]); -// ... +// … ``` ## Specifications diff --git a/files/en-us/web/api/gpurenderpassencoder/drawindexed/index.md b/files/en-us/web/api/gpurenderpassencoder/drawindexed/index.md index d9be6a8a108ddee..a676290f8e94306 100644 --- a/files/en-us/web/api/gpurenderpassencoder/drawindexed/index.md +++ b/files/en-us/web/api/gpurenderpassencoder/drawindexed/index.md @@ -45,7 +45,7 @@ None ({{jsxref("Undefined")}}). In the WebGPU Samples [Shadow Mapping](https://webgpu.github.io/webgpu-samples/samples/shadowMapping/) example, `drawIndexed()` is used in two separate render passes in each animation frame, one to populate the shadow buffer and one to draw the primary view of the scene. Study the example code listing for the full context. ```js -// ... +// … const commandEncoder = device.createCommandEncoder(); { @@ -71,7 +71,7 @@ const commandEncoder = device.createCommandEncoder(); renderPass.end(); } -// ... +// … ``` ## Specifications diff --git a/files/en-us/web/api/gpurenderpassencoder/drawindexedindirect/index.md b/files/en-us/web/api/gpurenderpassencoder/drawindexedindirect/index.md index 2e184072906ae36..57f552d32ddf266 100644 --- a/files/en-us/web/api/gpurenderpassencoder/drawindexedindirect/index.md +++ b/files/en-us/web/api/gpurenderpassencoder/drawindexedindirect/index.md @@ -58,7 +58,7 @@ The following criteria must be met when calling **`drawIndirect()`**, otherwise ## Examples ```js -// ... +// … // Create GPURenderPassEncoder const passEncoder = commandEncoder.beginRenderPass(renderPassDescriptor); @@ -92,7 +92,7 @@ passEncoder.end(); // End frame by passing array of GPUCommandBuffers to command queue for execution device.queue.submit([commandEncoder.finish()]); -// ... +// … ``` ## Specifications diff --git a/files/en-us/web/api/gpurenderpassencoder/drawindirect/index.md b/files/en-us/web/api/gpurenderpassencoder/drawindirect/index.md index 982fc73dee2cb55..e9ac440b4e26a9c 100644 --- a/files/en-us/web/api/gpurenderpassencoder/drawindirect/index.md +++ b/files/en-us/web/api/gpurenderpassencoder/drawindirect/index.md @@ -57,7 +57,7 @@ The following criteria must be met when calling **`drawIndirect()`**, otherwise ## Examples ```js -// ... +// … // Create GPURenderPassEncoder const passEncoder = commandEncoder.beginRenderPass(renderPassDescriptor); @@ -89,7 +89,7 @@ passEncoder.end(); // End frame by passing array of GPUCommandBuffers to command queue for execution device.queue.submit([commandEncoder.finish()]); -// ... +// … ``` ## Specifications diff --git a/files/en-us/web/api/gpurenderpassencoder/end/index.md b/files/en-us/web/api/gpurenderpassencoder/end/index.md index bdad102b1aa24c9..7cc869c2aa1d60d 100644 --- a/files/en-us/web/api/gpurenderpassencoder/end/index.md +++ b/files/en-us/web/api/gpurenderpassencoder/end/index.md @@ -31,9 +31,9 @@ None ({{jsxref("Undefined")}}). The following criteria must be met when calling **`end()`**, otherwise a {{domxref("GPUValidationError")}} is generated and the {{domxref("GPURenderPassEncoder")}} becomes invalid: -- The {{domxref("GPURenderPassEncoder")}} is open (i.e. not already ended via an `end()` call). -- There is no occlusion query (i.e. started via {{domxref("GPURenderPassEncoder.beginOcclusionQuery", "beginOcclusionQuery()")}}) active on the current render pass. -- The debug stack for the current render pass is empty (i.e. no render pass debug group is currently open, as opened by {{domxref("GPURenderPassEncoder.pushDebugGroup", "pushDebugGroup()")}}). +- The {{domxref("GPURenderPassEncoder")}} is open (i.e., not already ended via an `end()` call). +- There is no occlusion query (i.e., started via {{domxref("GPURenderPassEncoder.beginOcclusionQuery", "beginOcclusionQuery()")}}) active on the current render pass. +- The debug stack for the current render pass is empty (i.e., no render pass debug group is currently open, as opened by {{domxref("GPURenderPassEncoder.pushDebugGroup", "pushDebugGroup()")}}). - The number of draw commands encoded in this render pass is less than or equal to the `maxDrawCount` property set in the {{domxref("GPUCommandEncoder.beginRenderPass()")}} descriptor. ## Examples @@ -41,7 +41,7 @@ The following criteria must be met when calling **`end()`**, otherwise a {{domxr In our [basic render demo](https://mdn.github.io/dom-examples/webgpu-render-demo/), several commands are recorded via a {{domxref("GPUCommandEncoder")}}. Most of these commands originate from the `GPURenderPassEncoder` created via {{domxref("GPUCommandEncoder.beginRenderPass()")}}. `end()` is called in an appropriate place to end the render pass. ```js -// ... +// … const renderPipeline = device.createRenderPipeline(pipelineDescriptor); @@ -74,7 +74,7 @@ passEncoder.end(); // End frame by passing array of command buffers to command queue for execution device.queue.submit([commandEncoder.finish()]); -// ... +// … ``` ## Specifications diff --git a/files/en-us/web/api/gpurenderpassencoder/endocclusionquery/index.md b/files/en-us/web/api/gpurenderpassencoder/endocclusionquery/index.md index 199766a79990dc0..5495a5a7dbfe0dc 100644 --- a/files/en-us/web/api/gpurenderpassencoder/endocclusionquery/index.md +++ b/files/en-us/web/api/gpurenderpassencoder/endocclusionquery/index.md @@ -31,12 +31,12 @@ None ({{jsxref("Undefined")}}). The following criteria must be met when calling **`endOcclusionQuery()`**, otherwise a {{domxref("GPUValidationError")}} is generated and the {{domxref("GPURenderPassEncoder")}} becomes invalid: -- An occlusion query is active for this render pass (i.e. via a previous `beginOcclusionQuery()` call). +- An occlusion query is active for this render pass (i.e., via a previous `beginOcclusionQuery()` call). ## Examples ```js -// ... +// … // Create a query set to hold the occlusion queries const querySet = device.createQuerySet({ @@ -71,7 +71,7 @@ passEncoder.draw(3); // End the occlusion query passEncoder.endOcclusionQuery(); -// ... +// … ``` ## Specifications diff --git a/files/en-us/web/api/gpurenderpassencoder/executebundles/index.md b/files/en-us/web/api/gpurenderpassencoder/executebundles/index.md index 3eb98de098d5a69..cfc43ce5c51def8 100644 --- a/files/en-us/web/api/gpurenderpassencoder/executebundles/index.md +++ b/files/en-us/web/api/gpurenderpassencoder/executebundles/index.md @@ -46,7 +46,7 @@ For each {{domxref("GPURenderBundle")}}: In the WebGPU Samples [Animometer example](https://webgpu.github.io/webgpu-samples/samples/animometer/), a lot of like operations are done on many different objects simultaneously. `executeBundles()` is used to reuse the work on multiple render passes to improve performance. Study the example code listing for the full context. ```js -// ... +// … return function doDraw(timestamp) { if (startTime === undefined) { @@ -72,7 +72,7 @@ return function doDraw(timestamp) { device.queue.submit([commandEncoder.finish()]); }; -// ... +// … ``` ## Specifications diff --git a/files/en-us/web/api/gpurenderpassencoder/index.md b/files/en-us/web/api/gpurenderpassencoder/index.md index 4d323ecf3315c76..40e6137d67fefeb 100644 --- a/files/en-us/web/api/gpurenderpassencoder/index.md +++ b/files/en-us/web/api/gpurenderpassencoder/index.md @@ -80,7 +80,7 @@ A `GPURenderPassEncoder` object instance is created via the {{domxref("GPUComman In our [basic render demo](https://mdn.github.io/dom-examples/webgpu-render-demo/), several commands are recorded via a {{domxref("GPUCommandEncoder")}}. Most of these commands originate from the `GPURenderPassEncoder` created via {{domxref("GPUCommandEncoder.beginRenderPass()")}}. ```js -// ... +// … const renderPipeline = device.createRenderPipeline(pipelineDescriptor); @@ -113,7 +113,7 @@ passEncoder.end(); // End frame by passing array of command buffers to command queue for execution device.queue.submit([commandEncoder.finish()]); -// ... +// … ``` ## Specifications diff --git a/files/en-us/web/api/gpurenderpassencoder/insertdebugmarker/index.md b/files/en-us/web/api/gpurenderpassencoder/insertdebugmarker/index.md index a1ba127e3294c98..618c5227a4b43e5 100644 --- a/files/en-us/web/api/gpurenderpassencoder/insertdebugmarker/index.md +++ b/files/en-us/web/api/gpurenderpassencoder/insertdebugmarker/index.md @@ -33,11 +33,11 @@ None ({{jsxref("Undefined")}}). ## Examples ```js -// ... +// … passEncoder.insertDebugMarker("my_marker"); -// ... +// … ``` ## Specifications diff --git a/files/en-us/web/api/gpurenderpassencoder/popdebuggroup/index.md b/files/en-us/web/api/gpurenderpassencoder/popdebuggroup/index.md index 1b23f42148a581b..cc933fff22ebf09 100644 --- a/files/en-us/web/api/gpurenderpassencoder/popdebuggroup/index.md +++ b/files/en-us/web/api/gpurenderpassencoder/popdebuggroup/index.md @@ -33,12 +33,12 @@ None ({{jsxref("Undefined")}}). The following criteria must be met when calling **`popDebugGroup()`**, otherwise a {{domxref("GPUValidationError")}} is generated and the {{domxref("GPURenderPassEncoder")}} becomes invalid: -- The render pass encoder's debug stack is not empty (i.e. at least one render pass debug group was previously started with {{domxref("GPURenderPassEncoder.pushDebugGroup", "pushDebugGroup()")}}). +- The render pass encoder's debug stack is not empty (i.e., at least one render pass debug group was previously started with {{domxref("GPURenderPassEncoder.pushDebugGroup", "pushDebugGroup()")}}). ## Examples ```js -// ... +// … const passEncoder = commandEncoder.beginRenderPass(renderPassDescriptor); @@ -50,7 +50,7 @@ passEncoder.draw(3); passEncoder.popDebugGroup(); -// ... +// … ``` ## Specifications diff --git a/files/en-us/web/api/gpurenderpassencoder/pushdebuggroup/index.md b/files/en-us/web/api/gpurenderpassencoder/pushdebuggroup/index.md index adebd62755f7a59..6fa1f644b0f632b 100644 --- a/files/en-us/web/api/gpurenderpassencoder/pushdebuggroup/index.md +++ b/files/en-us/web/api/gpurenderpassencoder/pushdebuggroup/index.md @@ -33,7 +33,7 @@ None ({{jsxref("Undefined")}}). ## Examples ```js -// ... +// … const passEncoder = commandEncoder.beginRenderPass(renderPassDescriptor); @@ -45,7 +45,7 @@ passEncoder.draw(3); passEncoder.popDebugGroup(); -// ... +// … ``` ## Specifications diff --git a/files/en-us/web/api/gpurenderpassencoder/setbindgroup/index.md b/files/en-us/web/api/gpurenderpassencoder/setbindgroup/index.md index 9c00088eeebe24d..62dfe6fe18587fb 100644 --- a/files/en-us/web/api/gpurenderpassencoder/setbindgroup/index.md +++ b/files/en-us/web/api/gpurenderpassencoder/setbindgroup/index.md @@ -29,7 +29,7 @@ setBindGroup(index, bindGroup, dynamicOffsets, dynamicOffsetsStart, - `bindGroup` - : The {{domxref("GPUBindGroup")}} to use for subsequent render commands, or `null`, in which case any previously-set bind group in the given slot is unset. - `dynamicOffsets` {{optional_inline}} - - : A value specifying the offset, in bytes, for each entry in `bindGroup` with `hasDynamicOffset: true` set (i.e. in the descriptor of the {{domxref("GPUDevice.createBindGroupLayout()")}} call that created the {{domxref("GPUBindGroupLayout")}} object that the `bindGroup` is based on). This value can be: + - : A value specifying the offset, in bytes, for each entry in `bindGroup` with `hasDynamicOffset: true` set (i.e., in the descriptor of the {{domxref("GPUDevice.createBindGroupLayout()")}} call that created the {{domxref("GPUBindGroupLayout")}} object that the `bindGroup` is based on). This value can be: - An array of numbers specifying the different offsets. - A {{jsxref("Uint32Array")}} containing numbers specifying the offsets. @@ -68,7 +68,7 @@ The following criteria must be met when calling **`setBindGroup()`**, otherwise In the WebGPU Samples [Textured Cube example](https://webgpu.github.io/webgpu-samples/samples/texturedCube/), `setBindGroup()` is used to bind the `uniformBindGroup` to index position 0. Check out the example for the full context. ```js -// ... +// … const commandEncoder = device.createCommandEncoder(); const passEncoder = commandEncoder.beginRenderPass(renderPassDescriptor); @@ -79,7 +79,7 @@ passEncoder.draw(cubeVertexCount, 1, 0, 0); passEncoder.end(); device.queue.submit([commandEncoder.finish()]); -// ... +// … ``` > [!NOTE] diff --git a/files/en-us/web/api/gpurenderpassencoder/setblendconstant/index.md b/files/en-us/web/api/gpurenderpassencoder/setblendconstant/index.md index f04af11c6442452..2fef334c5a73f11 100644 --- a/files/en-us/web/api/gpurenderpassencoder/setblendconstant/index.md +++ b/files/en-us/web/api/gpurenderpassencoder/setblendconstant/index.md @@ -47,7 +47,7 @@ None ({{jsxref("Undefined")}}). ## Examples ```js -// ... +// … const passEncoder = commandEncoder.beginRenderPass(renderPassDescriptor); @@ -58,7 +58,7 @@ passEncoder.draw(3); passEncoder.end(); -// ... +// … ``` ## Specifications diff --git a/files/en-us/web/api/gpurenderpassencoder/setindexbuffer/index.md b/files/en-us/web/api/gpurenderpassencoder/setindexbuffer/index.md index 1650980c90a469b..e1dcfbb16c572b6 100644 --- a/files/en-us/web/api/gpurenderpassencoder/setindexbuffer/index.md +++ b/files/en-us/web/api/gpurenderpassencoder/setindexbuffer/index.md @@ -53,7 +53,7 @@ The following criteria must be met when calling **`setIndexBuffer()`**, otherwis In the WebGPU Samples [Shadow Mapping](https://webgpu.github.io/webgpu-samples/samples/shadowMapping/) example, `setIndexBuffer()` is used in two separate render passes in each animation frame, one to draw the main model and one to draw its shadow. Study the example code listing for the full context. ```js -// ... +// … const commandEncoder = device.createCommandEncoder(); { @@ -79,7 +79,7 @@ const commandEncoder = device.createCommandEncoder(); renderPass.end(); } -// ... +// … ``` ## Specifications diff --git a/files/en-us/web/api/gpurenderpassencoder/setpipeline/index.md b/files/en-us/web/api/gpurenderpassencoder/setpipeline/index.md index dffd8b4ba5f5a9a..38f5c3affc66e2a 100644 --- a/files/en-us/web/api/gpurenderpassencoder/setpipeline/index.md +++ b/files/en-us/web/api/gpurenderpassencoder/setpipeline/index.md @@ -40,7 +40,7 @@ The following criteria must be met when calling **`setPipeline()`**, otherwise a In our [basic render demo](https://mdn.github.io/dom-examples/webgpu-render-demo/), several commands are recorded via a {{domxref("GPUCommandEncoder")}}. Most of these commands originate from the `GPURenderPassEncoder` created via {{domxref("GPUCommandEncoder.beginRenderPass()")}}. `setPipeline()` is called in an appropriate place to set the render pipeline. ```js -// ... +// … const renderPipeline = device.createRenderPipeline(pipelineDescriptor); @@ -73,7 +73,7 @@ passEncoder.end(); // End frame by passing array of command buffers to command queue for execution device.queue.submit([commandEncoder.finish()]); -// ... +// … ``` ## Specifications diff --git a/files/en-us/web/api/gpurenderpassencoder/setstencilreference/index.md b/files/en-us/web/api/gpurenderpassencoder/setstencilreference/index.md index 88505f1d876e4e0..47c168a8df0147f 100644 --- a/files/en-us/web/api/gpurenderpassencoder/setstencilreference/index.md +++ b/files/en-us/web/api/gpurenderpassencoder/setstencilreference/index.md @@ -34,7 +34,7 @@ None ({{jsxref("Undefined")}}). ## Examples ```js -// ... +// … const passEncoder = commandEncoder.beginRenderPass(renderPassDescriptor); @@ -45,7 +45,7 @@ passEncoder.draw(3); passEncoder.end(); -// ... +// … ``` ## Specifications diff --git a/files/en-us/web/api/gpurenderpassencoder/setvertexbuffer/index.md b/files/en-us/web/api/gpurenderpassencoder/setvertexbuffer/index.md index 32e2b3322431f36..32a132a7d6e1703 100644 --- a/files/en-us/web/api/gpurenderpassencoder/setvertexbuffer/index.md +++ b/files/en-us/web/api/gpurenderpassencoder/setvertexbuffer/index.md @@ -50,7 +50,7 @@ The following criteria must be met when calling **`setVertexBuffer()`**, otherwi In our [basic render demo](https://mdn.github.io/dom-examples/webgpu-render-demo/), several commands are recorded via a {{domxref("GPUCommandEncoder")}}. Most of these commands originate from the `GPURenderPassEncoder` created via {{domxref("GPUCommandEncoder.beginRenderPass()")}}. `setVertexBuffer()` is used as appropriate to set the source of vertex data. ```js -// ... +// … const renderPipeline = device.createRenderPipeline(pipelineDescriptor); @@ -83,7 +83,7 @@ passEncoder.end(); // End frame by passing array of command buffers to command queue for execution device.queue.submit([commandEncoder.finish()]); -// ... +// … ``` ### Unset vertex buffer diff --git a/files/en-us/web/api/gpurenderpassencoder/setviewport/index.md b/files/en-us/web/api/gpurenderpassencoder/setviewport/index.md index 1afe4b6297b43e3..809a0dbf16ef99e 100644 --- a/files/en-us/web/api/gpurenderpassencoder/setviewport/index.md +++ b/files/en-us/web/api/gpurenderpassencoder/setviewport/index.md @@ -71,7 +71,7 @@ In the WebGPU Samples [reversedZ example](https://webgpu.github.io/webgpu-sample For example: ```js -// ... +// … colorPass.setViewport( (canvas.width * m) / 2, @@ -82,7 +82,7 @@ colorPass.setViewport( 1, ); -// ... +// … ``` ## Specifications diff --git a/files/en-us/web/api/gpurenderpipeline/getbindgrouplayout/index.md b/files/en-us/web/api/gpurenderpipeline/getbindgrouplayout/index.md index f8e8536f6775a7c..153d8daba0a1db1 100644 --- a/files/en-us/web/api/gpurenderpipeline/getbindgrouplayout/index.md +++ b/files/en-us/web/api/gpurenderpipeline/getbindgrouplayout/index.md @@ -11,7 +11,7 @@ browser-compat: api.GPURenderPipeline.getBindGroupLayout {{APIRef("WebGPU API")}}{{SeeCompatTable}}{{SecureContext_Header}}{{AvailableInWorkers}} The **`getBindGroupLayout()`** method of the -{{domxref("GPURenderPipeline")}} interface returns the pipeline's {{domxref("GPUBindGroupLayout")}} object with the given index (i.e. included in the originating {{domxref("GPUDevice.createRenderPipeline()")}} or {{domxref("GPUDevice.createRenderPipelineAsync()")}} call's pipeline layout). +{{domxref("GPURenderPipeline")}} interface returns the pipeline's {{domxref("GPUBindGroupLayout")}} object with the given index (i.e., included in the originating {{domxref("GPUDevice.createRenderPipeline()")}} or {{domxref("GPUDevice.createRenderPipelineAsync()")}} call's pipeline layout). If the {{domxref("GPURenderPipeline")}} was created with `layout: "auto"`, this method is the only way to retrieve the {{domxref("GPUBindGroupLayout")}}s generated by the pipeline. @@ -43,7 +43,7 @@ The following criteria must be met when calling **`getBindGroupLayout()`**, othe > You can see complete working examples with `getBindGroupLayout()` in action in the [WebGPU samples](https://webgpu.github.io/webgpu-samples/). ```js -// ... +// … // Create a render pipeline using layout: "auto" to automatically generate // appropriate bind group layouts @@ -71,7 +71,7 @@ const fullscreenQuadPipeline = device.createRenderPipeline({ }, }); -// ... +// … // Create a bind group with the auto-generated layout from the render pipeline const showResultBindGroup = device.createBindGroup({ @@ -88,7 +88,7 @@ const showResultBindGroup = device.createBindGroup({ ], }); -// ... +// … ``` ## Specifications diff --git a/files/en-us/web/api/gpurenderpipeline/index.md b/files/en-us/web/api/gpurenderpipeline/index.md index a64cee3a544db08..6ca7aec0f1141ca 100644 --- a/files/en-us/web/api/gpurenderpipeline/index.md +++ b/files/en-us/web/api/gpurenderpipeline/index.md @@ -23,7 +23,7 @@ A `GPURenderPipeline` object instance can be created using the {{domxref("GPUDev ## Instance methods - {{domxref("GPURenderPipeline.getBindGroupLayout", "getBindGroupLayout()")}} {{Experimental_Inline}} - - : Returns the pipeline's {{domxref("GPUBindGroupLayout")}} object with the given index (i.e. included in the originating {{domxref("GPUDevice.createRenderPipeline()")}} or {{domxref("GPUDevice.createRenderPipelineAsync()")}} call's pipeline layout). + - : Returns the pipeline's {{domxref("GPUBindGroupLayout")}} object with the given index (i.e., included in the originating {{domxref("GPUDevice.createRenderPipeline()")}} or {{domxref("GPUDevice.createRenderPipelineAsync()")}} call's pipeline layout). ## Examples @@ -35,7 +35,7 @@ A `GPURenderPipeline` object instance can be created using the {{domxref("GPUDev Our [basic render demo](https://mdn.github.io/dom-examples/webgpu-render-demo/) provides an example of the construction of a valid render pipeline descriptor object, which is then used to create a `GPURenderPipeline` via a `createRenderPipeline()` call. ```js -// ... +// … const vertexBuffers = [ { @@ -79,7 +79,7 @@ const pipelineDescriptor = { const renderPipeline = device.createRenderPipeline(pipelineDescriptor); -// ... +// … ``` ## Specifications diff --git a/files/en-us/web/api/gpurenderpipeline/label/index.md b/files/en-us/web/api/gpurenderpipeline/label/index.md index 201cc27aabfde6d..d83489cba01898a 100644 --- a/files/en-us/web/api/gpurenderpipeline/label/index.md +++ b/files/en-us/web/api/gpurenderpipeline/label/index.md @@ -24,7 +24,7 @@ A string. If this has not been previously set as described above, it will be an Setting and getting a label via `GPURenderPipeline.label`: ```js -// ... +// … const pipelineDescriptor = { vertex: { @@ -57,7 +57,7 @@ console.log(renderPipeline.label); // "my_render_pipeline" Setting a label via a {{domxref("GPUDevice.createRenderPipeline()")}} call, and then getting it via `GPURenderPipeline.label`: ```js -// ... +// … const pipelineDescriptor = { vertex: { diff --git a/files/en-us/web/api/gpusampler/index.md b/files/en-us/web/api/gpusampler/index.md index 2a8546cce7cd534..1f3655f9275fb59 100644 --- a/files/en-us/web/api/gpusampler/index.md +++ b/files/en-us/web/api/gpusampler/index.md @@ -25,7 +25,7 @@ A `GPUSampler` object instance is created using the {{domxref("GPUDevice.createS The following snippet creates a `GPUSampler` that does trilinear filtering and repeats texture coordinates: ```js -// ... +// … const sampler = device.createSampler({ addressModeU: "repeat", addressModeV: "repeat", diff --git a/files/en-us/web/api/gpusampler/label/index.md b/files/en-us/web/api/gpusampler/label/index.md index a39ad0ea08dc675..34c1928955b3649 100644 --- a/files/en-us/web/api/gpusampler/label/index.md +++ b/files/en-us/web/api/gpusampler/label/index.md @@ -24,7 +24,7 @@ A string. If this has not been previously set as described above, it will be an Setting and getting a label via `GPUSampler.label`: ```js -// ... +// … const sampler = device.createSampler({ compare: "less", @@ -38,7 +38,7 @@ console.log(sampler.label); // "my_sampler" Setting a label via the originating {{domxref("GPUDevice.createSampler()")}} call, and then getting it via `GPUSampler.label`: ```js -// ... +// … const sampler = device.createSampler({ compare: "less", diff --git a/files/en-us/web/api/gpushadermodule/getcompilationinfo/index.md b/files/en-us/web/api/gpushadermodule/getcompilationinfo/index.md index 890b8ce607d7426..acf62eb048ff149 100644 --- a/files/en-us/web/api/gpushadermodule/getcompilationinfo/index.md +++ b/files/en-us/web/api/gpushadermodule/getcompilationinfo/index.md @@ -62,7 +62,7 @@ When we compile the shader module, we use `getCompilationInfo()` to grab some in ```js async function init() { - // ... + // … const shaderModule = device.createShaderModule({ code: shaders, @@ -75,7 +75,7 @@ async function init() { console.log(firstMessage.message); // "expected ')' for function declaration" console.log(firstMessage.type); // "error" - // ... + // … } ``` diff --git a/files/en-us/web/api/gpushadermodule/index.md b/files/en-us/web/api/gpushadermodule/index.md index bb08ddef074a9e8..a67d7a549967352 100644 --- a/files/en-us/web/api/gpushadermodule/index.md +++ b/files/en-us/web/api/gpushadermodule/index.md @@ -64,16 +64,16 @@ async function init() { throw Error("Couldn't request WebGPU adapter."); } - let device = await adapter.requestDevice(); + const device = await adapter.requestDevice(); - // ... + // … // later on const shaderModule = device.createShaderModule({ code: shaders, }); - // ... + // … } ``` diff --git a/files/en-us/web/api/gpushadermodule/label/index.md b/files/en-us/web/api/gpushadermodule/label/index.md index a31a6c8dae66320..b169d75b6f2a1df 100644 --- a/files/en-us/web/api/gpushadermodule/label/index.md +++ b/files/en-us/web/api/gpushadermodule/label/index.md @@ -24,7 +24,7 @@ A string. If this has not been previously set as described above, it will be an Setting and getting a label via `GPUShaderModule.label`: ```js -// ... +// … const shaderModule = device.createShaderModule({ code: shaders, @@ -38,7 +38,7 @@ console.log(shaderModule.label); // "my_shader" Setting a label via the originating {{domxref("GPUDevice.createShaderModule()")}} call, and then getting it via `GPUShaderModule.label`: ```js -// ... +// … const shaderModule = device.createShaderModule({ code: shaders, diff --git a/files/en-us/web/api/gpusupportedfeatures/index.md b/files/en-us/web/api/gpusupportedfeatures/index.md index 3b6858bcb5fb7bd..016d2047c1a119c 100644 --- a/files/en-us/web/api/gpusupportedfeatures/index.md +++ b/files/en-us/web/api/gpusupportedfeatures/index.md @@ -33,11 +33,12 @@ The following additional features are defined in WebGPU. Bear in mind that the e | `depth-clip-control` | Allows [depth-clipping](https://gpuweb.github.io/gpuweb/#depth-clipping) to be disabled. If `depth-clip-control` is enabled, the [`unclippedDepth`](/en-US/docs/Web/API/GPUDevice/createRenderPipeline#unclippeddepth) property is available on the `primitive` object included as part of the {{domxref("GPUDevice.createRenderPipeline", "createRenderPipeline()")}} or {{domxref("GPUDevice.createRenderPipelineAsync", "createRenderPipelineAsync()")}} descriptor when creating a {{domxref("GPURenderPipeline")}}. `primitive` describes how a pipeline constructs and rasterizes primitives from its vertex inputs. Set `unclipped-depth` to `true` to disable depth-clipping. | | `depth32float-stencil8` | Allows creation of textures with the format `depth32float-stencil8`. If `depth32float-stencil8` is enabled, the `depth32float-stencil8` value can be used for the [`format`](/en-US/docs/Web/API/GPUDevice/createTexture#format) property of the {{domxref("GPUDevice.createTexture", "createTexture()")}} descriptor when creating a {{domxref("GPUTexture")}}. | | `dual-source-blending` | When enabled, allows the use of [`dual_source_blending`](https://gpuweb.github.io/gpuweb/wgsl/#extension-dual_source_blending) in WGSL, which uses both pixel shader outputs (`@blend_src(0)` and `@blend_src(1)`) as inputs to a blending operation with the single color attachment at `@location(0)`. Over in WebGPU, `dual-source-blending` enables the following blend factor operations (specified in the [`dstFactor`](/en-US/docs/Web/API/GPUDevice/createRenderPipeline#dstfactor) and [`srcFactor`](/en-US/docs/Web/API/GPUDevice/createRenderPipeline#srcfactor) properties of {{domxref("GPUDevice.createRenderPipeline", "createRenderPipeline()")}} and {{domxref("GPUDevice.createRenderPipelineAsync", "createRenderPipelineAsync()")}} descriptors): `src1`, `one-minus-src1`, `src1-alpha`, and `one-minus-src1-alpha`. | -| `float32-blendable` | When enabled, allows blending of `r32float`-, `rg32float`-, and `rgba32float`-[`format`](/en-US/docs/Web/API/GPUDevice/createTexture#format) {{domxref("GPUTexture")}}s. | +| `float32-blendable` | When enabled, allows [blending](/en-US/docs/Web/API/GPUDevice/createRenderPipeline#blend) of `r32float`-, `rg32float`-, and `rgba32float`-[`format`](/en-US/docs/Web/API/GPUDevice/createTexture#format) {{domxref("GPUTexture")}}s. | | `float32-filterable` | When enabled, allows [filtering](/en-US/docs/Web/API/GPUDevice/createSampler#magfilter) of `r32float`-, `rg32float`-, and `rgba32float`-[`format`](/en-US/docs/Web/API/GPUDevice/createTexture#format) {{domxref("GPUTexture")}}s. | | `indirect-first-instance` | When enabled, allows the use of non-zero `firstInstance` values in the `indirectBuffer` property of the `drawIndirect()` and `drawIndexedIndirect()` methods available on {{domxref("GPURenderPassEncoder")}} and {{domxref("GPURenderBundleEncoder")}} instances. | | `rg11b10ufloat-renderable` | When enabled, allows `RENDER_ATTACHMENT` [`usage`](/en-US/docs/Web/API/GPUDevice/createTexture#usage) of `rg11b10ufloat`-[`format`](/en-US/docs/Web/API/GPUDevice/createTexture#format) {{domxref("GPUTexture")}}s, as well as their blending and multisampling. | | `shader-f16` | When enabled, allows the use of the half-precision floating-point type [`f16`](https://gpuweb.github.io/gpuweb/wgsl/#extension-f16) in WGSL. | +| `subgroups` | When enabled, allows the use of [subgroups](https://gpuweb.github.io/gpuweb/wgsl/#extension-subgroups) in WGSL. Subgroups enable SIMD-level parallelism, allowing threads in a workgroup to communicate and execute collective math operations such as calculating a sum of numbers, and offering an efficient method for cross-thread data sharing. Note that the {{domxref("GPUAdapterInfo.subgroupMinSize", "subgroupMinSize")}} and {{domxref("GPUAdapterInfo.subgroupMaxSize", "subgroupMaxSize")}} properties can be useful to check if, for example, you have a hardcoded algorithm that requires a subgroup of a certain size. You can use f16 values with subgroups when you request a GPUDevice with both the `shader-f16` and `subgroups` features. | | `texture-compression-bc` | Allows creation of two-dimensional BC compressed textures. If `texture-compression-bc` is enabled, the following values can be used for the [`format`](/en-US/docs/Web/API/GPUDevice/createTexture#format) property of the {{domxref("GPUDevice.createTexture", "createTexture()")}} descriptor when creating a {{domxref("GPUTexture")}}: `bc1-rgba-unorm`, `bc1-rgba-unorm-srgb`, `bc2-rgba-unorm`, `bc2-rgba-unorm-srgb`, `bc3-rgba-unorm`, `bc3-rgba-unorm-srgb`, `bc4-r-unorm`, `bc4-r-snorm`, `bc5-rg-unorm`, `bc5-rg-snorm`, `bc6h-rgb-ufloat`, `bc6h-rgb-float`, `bc7-rgba-unorm`, and `bc7-rgba-unorm-srgb`. | | `texture-compression-bc-sliced-3d` | Allows creation of three-dimensional BC compressed textures. If `texture-compression-bc-sliced-3d` is enabled, `texture-compression-bc` must also be enabled, as it enables the BC texture formats to be used (see `texture-compression-bc`, above) in the first two dimensions. `texture-compression-bc-sliced-3d` enables those same textures to be used in the third dimension. Adapters that support `texture-compression-bc` always support `texture-compression-bc-sliced-3d`. **Note that this feature is not currently supported in any browser.** | | `texture-compression-astc` | Allows creation of two-dimensional ASTC compressed textures. If `texture-compression-astc` is enabled, the following values can be used for the [`format`](/en-US/docs/Web/API/GPUDevice/createTexture#format) property of the {{domxref("GPUDevice.createTexture", "createTexture()")}} descriptor when creating a {{domxref("GPUTexture")}}: `astc-4x4-unorm`, `astc-4x4-unorm-srgb`, `astc-5x4-unorm`, `astc-5x4-unorm-srgb`, `astc-5x5-unorm`, `astc-5x5-unorm-srgb`, `astc-6x5-unorm`, `astc-6x5-unorm-srgb`, `astc-6x6-unorm`, `astc-6x6-unorm-srgb`, `astc-8x5-unorm`, `astc-8x5-unorm-srgb`, `astc-8x6-unorm`, `astc-8x6-unorm-srgb`, `astc-8x8-unorm`, `astc-8x8-unorm-srgb`, `astc-10x5-unorm`, `astc-10x5-unorm-srgb`, `astc-10x6-unorm`, `astc-10x6-unorm-srgb`, `astc-10x8-unorm`, `astc-10x8-unorm-srgb`, `astc-10x10-unorm`, `astc-10x10-unorm-srgb`, `astc-12x10-unorm`, `astc-12x10-unorm-srgb`, and `astc-12x12-unorm``astc-12x12-unorm-srgb`. | @@ -111,7 +112,7 @@ async function init() { console.log(value); }); - //... + // … } ``` diff --git a/files/en-us/web/api/gpusupportedlimits/index.md b/files/en-us/web/api/gpusupportedlimits/index.md index e6af36c40fa7224..8e6384a0d14f763 100644 --- a/files/en-us/web/api/gpusupportedlimits/index.md +++ b/files/en-us/web/api/gpusupportedlimits/index.md @@ -23,39 +23,39 @@ Given that different browsers will handle this differently and the tier values m The following limits are represented by properties in a `GPUSupportedLimits` object. See the [Limits](https://gpuweb.github.io/gpuweb/#limits) section of the specification for detailed descriptions of what the limits relate to. -| Limit name | Default value | -| ------------------------------------------- | ------------------------ | -| `maxTextureDimension1D` | 8192 | -| `maxTextureDimension2D` | 8192 | -| `maxTextureDimension3D` | 2048 | -| `maxTextureArrayLayers` | 256 | -| `maxBindGroups` | 4 | -| `maxBindingsPerBindGroup` | 640 | -| `maxDynamicUniformBuffersPerPipelineLayout` | 8 | -| `maxDynamicStorageBuffersPerPipelineLayout` | 4 | -| `maxSampledTexturesPerShaderStage` | 16 | -| `maxSamplersPerShaderStage` | 16 | -| `maxStorageBuffersPerShaderStage` | 8 | -| `maxStorageTexturesPerShaderStage` | 4 | -| `maxUniformBuffersPerShaderStage` | 12 | -| `maxUniformBufferBindingSize` | 65536 bytes | -| `maxStorageBufferBindingSize` | 134217728 bytes (128 MB) | -| `minUniformBufferOffsetAlignment` | 256 bytes | -| `minStorageBufferOffsetAlignment` | 256 bytes | -| `maxVertexBuffers` | 8 | -| `maxBufferSize` | 268435456 bytes (256 MB) | -| `maxVertexAttributes` | 16 | -| `maxVertexBufferArrayStride` | 2048 bytes | -| `maxInterStageShaderComponents` | 60 | -| `maxInterStageShaderVariables` | 16 | -| `maxColorAttachments` | 8 | -| `maxColorAttachmentBytesPerSample` | 32 | -| `maxComputeWorkgroupStorageSize` | 16384 bytes | -| `maxComputeInvocationsPerWorkgroup` | 256 | -| `maxComputeWorkgroupSizeX` | 256 | -| `maxComputeWorkgroupSizeY` | 256 | -| `maxComputeWorkgroupSizeZ` | 64 | -| `maxComputeWorkgroupsPerDimension` | 65535 | +| Limit name | Default value | +| --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------ | +| `maxTextureDimension1D` | 8192 | +| `maxTextureDimension2D` | 8192 | +| `maxTextureDimension3D` | 2048 | +| `maxTextureArrayLayers` | 256 | +| `maxBindGroups` | 4 | +| `maxBindingsPerBindGroup` | 640 | +| `maxDynamicUniformBuffersPerPipelineLayout` | 8 | +| `maxDynamicStorageBuffersPerPipelineLayout` | 4 | +| `maxSampledTexturesPerShaderStage` | 16 | +| `maxSamplersPerShaderStage` | 16 | +| `maxStorageBuffersPerShaderStage` | 8 | +| `maxStorageTexturesPerShaderStage` | 4 | +| `maxUniformBuffersPerShaderStage` | 12 | +| `maxUniformBufferBindingSize` | 65536 bytes | +| `maxStorageBufferBindingSize` | 134217728 bytes (128 MB) | +| `minUniformBufferOffsetAlignment` | 256 bytes | +| `minStorageBufferOffsetAlignment` | 256 bytes | +| `maxVertexBuffers` | 8 | +| `maxBufferSize` | 268435456 bytes (256 MB) | +| `maxVertexAttributes` | 16 | +| `maxVertexBufferArrayStride` | 2048 bytes | +| `maxInterStageShaderComponents` {{deprecated_inline}} {{non-standard_inline}} (use `maxInterStageShaderVariables` instead, see [deprecation notice](https://developer.chrome.com/blog/new-in-webgpu-133#deprecate_maxinterstageshadercomponents_limit) for more info) | 60 | +| `maxInterStageShaderVariables` | 16 | +| `maxColorAttachments` | 8 | +| `maxColorAttachmentBytesPerSample` | 32 | +| `maxComputeWorkgroupStorageSize` | 16384 bytes | +| `maxComputeInvocationsPerWorkgroup` | 256 | +| `maxComputeWorkgroupSizeX` | 256 | +| `maxComputeWorkgroupSizeY` | 256 | +| `maxComputeWorkgroupSizeZ` | 64 | +| `maxComputeWorkgroupsPerDimension` | 65535 | ## Examples @@ -83,7 +83,7 @@ async function init() { requiredLimits, }); - // ... + // … } ``` diff --git a/files/en-us/web/api/gputexture/createview/index.md b/files/en-us/web/api/gputexture/createview/index.md index 3593787b16c384f..fca956678ef6e9c 100644 --- a/files/en-us/web/api/gputexture/createview/index.md +++ b/files/en-us/web/api/gputexture/createview/index.md @@ -88,6 +88,12 @@ createView(descriptor) If `mipLevelCount` is omitted, it will be given a value of {{domxref("GPUTexture.mipLevelCount")}} - `baseMipLevel`. + - `usage` {{optional_inline}} + + - : A set of {{glossary("bitwise flags")}} representing a subset of the source texture's usage flags (available in the {{domxref("GPUTexture.usage")}} property) that are compatible with the chosen view format. This can be used to restrict the allowed view usage in cases where the view format is incompatible with certain usages. The available usage flags are listed in the [`GPUTexture.usage` value table](/en-US/docs/Web/API/GPUTexture/usage#value). + + The default value is `0`, which represents the source texture's full set of usage flags. If the view's [`format`](#format) doesn't support all of the texture's usages, the default will fail, and the view's usage must be specified explicitly. + ### Return value A {{domxref("GPUTextureView")}} object instance. @@ -123,9 +129,12 @@ The following criteria must be met when calling **`createView()`**, otherwise a - `"3d"` - {{domxref("GPUTexture.dimension")}} is `"3d"` - `arrayLayerCount` is 1 +- The view's [`format`](#format) supports all of the usages specified in the [`usage`](#usage) property. ## Examples +### Typical `createView()` usage + In the WebGPU Samples [Cubemap demo](https://webgpu.github.io/webgpu-samples/samples/cubemap/), you will see multiple examples of how `createView()` is used, both as to create a view `resource` for a {{domxref("GPUDevice.createBindGroup()")}} call, and to provide a `view` in the `depthStencilAttachment` object of a {{domxref("GPUCommandEncoder.beginRenderPass()")}} descriptor. ```js @@ -170,12 +179,33 @@ const renderPassDescriptor: GPURenderPassDescriptor = { }, }; -// ... +// … const commandEncoder = device.createCommandEncoder(); const passEncoder = commandEncoder.beginRenderPass(renderPassDescriptor); -// ... +// … +``` + +### `createView()` with usage restriction + +In this snippet, we create a texture and then create a view that has its usage restricted via the `usage` property. + +```js +const texture = myDevice.createTexture({ + size: [4, 4], + format: "rgba8unorm", + usage: + GPUTextureUsage.RENDER_ATTACHMENT | + GPUTextureUsage.TEXTURE_BINDING | + GPUTextureUsage.STORAGE_BINDING, + viewFormats: ["rgba8unorm-srgb"], +}); + +const view = texture.createView({ + format: "rgba8unorm-srgb", + usage: GPUTextureUsage.RENDER_ATTACHMENT, // Restrict allowed usage +}); ``` ## Specifications diff --git a/files/en-us/web/api/gputexture/depthorarraylayers/index.md b/files/en-us/web/api/gputexture/depthorarraylayers/index.md index 7859a73dd770989..a83b02410f70135 100644 --- a/files/en-us/web/api/gputexture/depthorarraylayers/index.md +++ b/files/en-us/web/api/gputexture/depthorarraylayers/index.md @@ -27,7 +27,7 @@ In cases where the `GPUTexture` does not have a depth or layers, the value is 1. ## Examples ```js -// ... +// … const test = device.createTexture({ size: [128], diff --git a/files/en-us/web/api/gputexture/destroy/index.md b/files/en-us/web/api/gputexture/destroy/index.md index c8f688e23b223a0..696fd8279a964c7 100644 --- a/files/en-us/web/api/gputexture/destroy/index.md +++ b/files/en-us/web/api/gputexture/destroy/index.md @@ -30,7 +30,7 @@ None ({{jsxref("Undefined")}}). ## Examples ```js -// ... +// … const depthTexture = device.createTexture({ size: [canvas.width, canvas.height], diff --git a/files/en-us/web/api/gputexture/dimension/index.md b/files/en-us/web/api/gputexture/dimension/index.md index 82f37662371131b..e8d2b5607109160 100644 --- a/files/en-us/web/api/gputexture/dimension/index.md +++ b/files/en-us/web/api/gputexture/dimension/index.md @@ -26,7 +26,7 @@ An enumerated value. Possible values are: ## Examples ```js -// ... +// … const depthTexture = device.createTexture({ size: [canvas.width, canvas.height], diff --git a/files/en-us/web/api/gputexture/format/index.md b/files/en-us/web/api/gputexture/format/index.md index 4de6916e50d2c64..a2f770824ad6449 100644 --- a/files/en-us/web/api/gputexture/format/index.md +++ b/files/en-us/web/api/gputexture/format/index.md @@ -22,7 +22,7 @@ An enumerated value. See the [Texture formats](https://gpuweb.github.io/gpuweb/# ## Examples ```js -// ... +// … const depthTexture = device.createTexture({ size: [canvas.width, canvas.height], diff --git a/files/en-us/web/api/gputexture/height/index.md b/files/en-us/web/api/gputexture/height/index.md index 7141201501d46e1..ef7ac3606192111 100644 --- a/files/en-us/web/api/gputexture/height/index.md +++ b/files/en-us/web/api/gputexture/height/index.md @@ -22,7 +22,7 @@ A number. ## Examples ```js -// ... +// … const depthTexture = device.createTexture({ size: [640, 480], diff --git a/files/en-us/web/api/gputexture/index.md b/files/en-us/web/api/gputexture/index.md index 7c1b9ac8967a12e..197655bad366f35 100644 --- a/files/en-us/web/api/gputexture/index.md +++ b/files/en-us/web/api/gputexture/index.md @@ -52,7 +52,7 @@ In the WebGPU samples [Textured Cube sample](https://webgpu.github.io/webgpu-sam - Copying the image bitmap into the texture using {{domxref("GPUQueue.copyExternalImageToTexture()")}}. ```js -//... +// … let cubeTexture; { const img = document.createElement("img"); @@ -81,7 +81,7 @@ let cubeTexture; [imageBitmap.width, imageBitmap.height], ); } -//... +// … ``` ## Specifications diff --git a/files/en-us/web/api/gputexture/label/index.md b/files/en-us/web/api/gputexture/label/index.md index eb6c3ca72082c11..e70827fad5cd615 100644 --- a/files/en-us/web/api/gputexture/label/index.md +++ b/files/en-us/web/api/gputexture/label/index.md @@ -24,7 +24,7 @@ A string. If this has not been previously set as described above, it will be an Setting and getting a label via `GPUTexture.label`: ```js -// ... +// … const depthTexture = device.createTexture({ size: [canvas.width, canvas.height], @@ -40,7 +40,7 @@ console.log(depthTexture.label); // "my_texture" Setting a label via the originating {{domxref("GPUDevice.createTexture()")}} call, and then getting it via `GPUTexture.label`: ```js -// ... +// … const depthTexture = device.createTexture({ size: [canvas.width, canvas.height], diff --git a/files/en-us/web/api/gputexture/miplevelcount/index.md b/files/en-us/web/api/gputexture/miplevelcount/index.md index 72e557228bf1430..6076dda44bf03e8 100644 --- a/files/en-us/web/api/gputexture/miplevelcount/index.md +++ b/files/en-us/web/api/gputexture/miplevelcount/index.md @@ -22,7 +22,7 @@ A number. ## Examples ```js -// ... +// … const depthTexture = device.createTexture({ size: [canvas.width, canvas.height], diff --git a/files/en-us/web/api/gputexture/samplecount/index.md b/files/en-us/web/api/gputexture/samplecount/index.md index 6350771217d59ae..eaf65cb4fff525d 100644 --- a/files/en-us/web/api/gputexture/samplecount/index.md +++ b/files/en-us/web/api/gputexture/samplecount/index.md @@ -25,7 +25,7 @@ A number. Possible values are: ## Examples ```js -// ... +// … const depthTexture = device.createTexture({ size: [canvas.width, canvas.height], diff --git a/files/en-us/web/api/gputexture/usage/index.md b/files/en-us/web/api/gputexture/usage/index.md index 2957bc4578f0e7c..a35ffbec1a9b380 100644 --- a/files/en-us/web/api/gputexture/usage/index.md +++ b/files/en-us/web/api/gputexture/usage/index.md @@ -30,7 +30,7 @@ The bitwise flags representing the original usages set when the `GPUTexture` was ## Examples ```js -// ... +// … const depthTexture = device.createTexture({ size: [canvas.width, canvas.height], diff --git a/files/en-us/web/api/gputexture/width/index.md b/files/en-us/web/api/gputexture/width/index.md index 0c4a91344a5df0d..18787a90634a063 100644 --- a/files/en-us/web/api/gputexture/width/index.md +++ b/files/en-us/web/api/gputexture/width/index.md @@ -22,7 +22,7 @@ A number. ## Examples ```js -// ... +// … const depthTexture = device.createTexture({ size: [640, 480], diff --git a/files/en-us/web/api/gputextureview/index.md b/files/en-us/web/api/gputextureview/index.md index 0227a95243d8f2c..6146f7564bf2814 100644 --- a/files/en-us/web/api/gputextureview/index.md +++ b/files/en-us/web/api/gputextureview/index.md @@ -65,12 +65,12 @@ const renderPassDescriptor: GPURenderPassDescriptor = { }, }; -// ... +// … const commandEncoder = device.createCommandEncoder(); const passEncoder = commandEncoder.beginRenderPass(renderPassDescriptor); -// ... +// … ``` ## Specifications diff --git a/files/en-us/web/api/gputextureview/label/index.md b/files/en-us/web/api/gputextureview/label/index.md index 925ec088bf2871a..1891970b476bd61 100644 --- a/files/en-us/web/api/gputextureview/label/index.md +++ b/files/en-us/web/api/gputextureview/label/index.md @@ -24,7 +24,7 @@ A string. If this has not been previously set as described above, it will be an Setting and getting a label via `GPUTextureView.label`: ```js -// ... +// … const depthTexture = device.createTexture({ size: [canvas.width, canvas.height], @@ -42,7 +42,7 @@ console.log(view.label); // "my_view" Setting a label via the originating {{domxref("GPUTexture.createView()")}} call, and then getting it via `GPUTextureView.label`: ```js -// ... +// … const depthTexture = device.createTexture({ size: [canvas.width, canvas.height], diff --git a/files/en-us/web/api/gpuuncapturederrorevent/index.md b/files/en-us/web/api/gpuuncapturederrorevent/index.md index b1387dbd9ad236d..0404c097f6a4bcf 100644 --- a/files/en-us/web/api/gpuuncapturederrorevent/index.md +++ b/files/en-us/web/api/gpuuncapturederrorevent/index.md @@ -32,7 +32,7 @@ _Inherits properties from its parent, {{domxref("Event")}}._ You could use something like the following as a global mechanism to pick up any errors that aren't handled by error scopes and capture them. ```js -// ... +// … device.addEventListener("uncapturederror", (event) => { // Re-surface the error @@ -43,7 +43,7 @@ device.addEventListener("uncapturederror", (event) => { }); }); -// ... +// … ``` ## Specifications diff --git a/files/en-us/web/api/gravitysensor/gravitysensor/index.md b/files/en-us/web/api/gravitysensor/gravitysensor/index.md index 4b5beba12eaf825..a8d31414e13b41e 100644 --- a/files/en-us/web/api/gravitysensor/gravitysensor/index.md +++ b/files/en-us/web/api/gravitysensor/gravitysensor/index.md @@ -40,7 +40,7 @@ new GravitySensor(options) ### Exceptions - `SecurityError` {{domxref("DOMException")}} - - : Use of this feature was blocked by a [Permissions Policy](/en-US/docs/Web/HTTP/Permissions_Policy). + - : Use of this feature was blocked by a [Permissions Policy](/en-US/docs/Web/HTTP/Guides/Permissions_Policy). ## Specifications diff --git a/files/en-us/web/api/gravitysensor/index.md b/files/en-us/web/api/gravitysensor/index.md index 4c8cae20629f6e1..3e55571f1c66505 100644 --- a/files/en-us/web/api/gravitysensor/index.md +++ b/files/en-us/web/api/gravitysensor/index.md @@ -9,7 +9,7 @@ browser-compat: api.GravitySensor The **`GravitySensor`** interface of the [Sensor APIs](/en-US/docs/Web/API/Sensor_APIs) provides on each reading the gravity applied to the device along all three axes. -To use this sensor, the user must grant permission to the `'accelerometer'` device sensor through the [Permissions API](/en-US/docs/Web/API/Permissions_API). In addition, this feature may be blocked by a [Permissions Policy](/en-US/docs/Web/HTTP/Permissions_Policy) set on your server. +To use this sensor, the user must grant permission to the `'accelerometer'` device sensor through the [Permissions API](/en-US/docs/Web/API/Permissions_API). In addition, this feature may be blocked by a [Permissions Policy](/en-US/docs/Web/HTTP/Guides/Permissions_Policy) set on your server. {{InheritanceDiagram}} diff --git a/files/en-us/web/api/gyroscope/gyroscope/index.md b/files/en-us/web/api/gyroscope/gyroscope/index.md index c107a2ff16f2146..590e79b10e5d7c0 100644 --- a/files/en-us/web/api/gyroscope/gyroscope/index.md +++ b/files/en-us/web/api/gyroscope/gyroscope/index.md @@ -38,7 +38,7 @@ new Gyroscope(options) ### Exceptions - `SecurityError` {{domxref("DOMException")}} - - : Use of this feature was blocked by a [Permissions Policy](/en-US/docs/Web/HTTP/Permissions_Policy). + - : Use of this feature was blocked by a [Permissions Policy](/en-US/docs/Web/HTTP/Guides/Permissions_Policy). ## Specifications diff --git a/files/en-us/web/api/gyroscope/index.md b/files/en-us/web/api/gyroscope/index.md index 5f3bcc3943de98a..0ab63e215d3c60f 100644 --- a/files/en-us/web/api/gyroscope/index.md +++ b/files/en-us/web/api/gyroscope/index.md @@ -9,7 +9,7 @@ browser-compat: api.Gyroscope The **`Gyroscope`** interface of the [Sensor APIs](/en-US/docs/Web/API/Sensor_APIs) provides on each reading the angular velocity of the device along all three axes. -To use this sensor, the user must grant permission to the `'gyroscope'` device sensor through the [Permissions API](/en-US/docs/Web/API/Permissions_API). In addition, this feature may be blocked by a [Permissions Policy](/en-US/docs/Web/HTTP/Permissions_Policy) set on your server. +To use this sensor, the user must grant permission to the `'gyroscope'` device sensor through the [Permissions API](/en-US/docs/Web/API/Permissions_API). In addition, this feature may be blocked by a [Permissions Policy](/en-US/docs/Web/HTTP/Guides/Permissions_Policy) set on your server. {{InheritanceDiagram}} diff --git a/files/en-us/web/api/headers/append/index.md b/files/en-us/web/api/headers/append/index.md index 952c53be033dff8..ecfb8a8e3ca0f6f 100644 --- a/files/en-us/web/api/headers/append/index.md +++ b/files/en-us/web/api/headers/append/index.md @@ -76,5 +76,5 @@ To overwrite the old value with a new one, use {{domxref("Headers.set")}}. ## See also - [ServiceWorker API](/en-US/docs/Web/API/Service_Worker_API) -- [HTTP access control (CORS)](/en-US/docs/Web/HTTP/CORS) +- [HTTP access control (CORS)](/en-US/docs/Web/HTTP/Guides/CORS) - [HTTP](/en-US/docs/Web/HTTP) diff --git a/files/en-us/web/api/headers/delete/index.md b/files/en-us/web/api/headers/delete/index.md index 80dc1beb609ee35..9d30ed75d6caa67 100644 --- a/files/en-us/web/api/headers/delete/index.md +++ b/files/en-us/web/api/headers/delete/index.md @@ -63,5 +63,5 @@ myHeaders.get("Content-Type"); // Returns null, as it has been deleted ## See also - [ServiceWorker API](/en-US/docs/Web/API/Service_Worker_API) -- [HTTP access control (CORS)](/en-US/docs/Web/HTTP/CORS) +- [HTTP access control (CORS)](/en-US/docs/Web/HTTP/Guides/CORS) - [HTTP](/en-US/docs/Web/HTTP) diff --git a/files/en-us/web/api/headers/entries/index.md b/files/en-us/web/api/headers/entries/index.md index e33bf41a21ad332..a52135bc7858375 100644 --- a/files/en-us/web/api/headers/entries/index.md +++ b/files/en-us/web/api/headers/entries/index.md @@ -55,5 +55,5 @@ vary: Accept-Language ## See also - [ServiceWorker API](/en-US/docs/Web/API/Service_Worker_API) -- [HTTP access control (CORS)](/en-US/docs/Web/HTTP/CORS) +- [HTTP access control (CORS)](/en-US/docs/Web/HTTP/Guides/CORS) - [HTTP](/en-US/docs/Web/HTTP) diff --git a/files/en-us/web/api/headers/foreach/index.md b/files/en-us/web/api/headers/foreach/index.md index ec6a9eb0a2f08c6..4734bb72c3d4f1d 100644 --- a/files/en-us/web/api/headers/foreach/index.md +++ b/files/en-us/web/api/headers/foreach/index.md @@ -73,5 +73,5 @@ cookie ==> This is a demo cookie - [`Map.prototype.forEach()`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Map/forEach) - [ServiceWorker API](/en-US/docs/Web/API/Service_Worker_API) -- [HTTP access control (CORS)](/en-US/docs/Web/HTTP/CORS) +- [HTTP access control (CORS)](/en-US/docs/Web/HTTP/Guides/CORS) - [HTTP](/en-US/docs/Web/HTTP) diff --git a/files/en-us/web/api/headers/get/index.md b/files/en-us/web/api/headers/get/index.md index a8cfd5ca9d5c6ae..ebf725a20e8eb05 100644 --- a/files/en-us/web/api/headers/get/index.md +++ b/files/en-us/web/api/headers/get/index.md @@ -76,5 +76,5 @@ myHeaders ## See also - [ServiceWorker API](/en-US/docs/Web/API/Service_Worker_API) -- [HTTP access control (CORS)](/en-US/docs/Web/HTTP/CORS) +- [HTTP access control (CORS)](/en-US/docs/Web/HTTP/Guides/CORS) - [HTTP](/en-US/docs/Web/HTTP) diff --git a/files/en-us/web/api/headers/has/index.md b/files/en-us/web/api/headers/has/index.md index 40f2ce910a2b10a..ad89c95b205a128 100644 --- a/files/en-us/web/api/headers/has/index.md +++ b/files/en-us/web/api/headers/has/index.md @@ -60,5 +60,5 @@ myHeaders.has("Accept-Encoding"); // Returns false ## See also - [ServiceWorker API](/en-US/docs/Web/API/Service_Worker_API) -- [HTTP access control (CORS)](/en-US/docs/Web/HTTP/CORS) +- [HTTP access control (CORS)](/en-US/docs/Web/HTTP/Guides/CORS) - [HTTP](/en-US/docs/Web/HTTP) diff --git a/files/en-us/web/api/headers/headers/index.md b/files/en-us/web/api/headers/headers/index.md index ea5404c647495fd..6a576219d6e89e6 100644 --- a/files/en-us/web/api/headers/headers/index.md +++ b/files/en-us/web/api/headers/headers/index.md @@ -21,7 +21,7 @@ new Headers(init) ### Parameters - `init` {{optional_inline}} - - : An object containing any [HTTP headers](/en-US/docs/Web/HTTP/Headers) + - : An object containing any [HTTP headers](/en-US/docs/Web/HTTP/Reference/Headers) that you want to pre-populate your `Headers` object with. This can be a simple object literal with {{jsxref("String")}} values, an array of name-value pairs, where each pair is a 2-element string array; or an existing `Headers` object. In the last case, the new `Headers` object @@ -85,5 +85,5 @@ const myHeaders = new Headers(headers); ## See also - [ServiceWorker API](/en-US/docs/Web/API/Service_Worker_API) -- [HTTP access control (CORS)](/en-US/docs/Web/HTTP/CORS) +- [HTTP access control (CORS)](/en-US/docs/Web/HTTP/Guides/CORS) - [HTTP](/en-US/docs/Web/HTTP) diff --git a/files/en-us/web/api/headers/index.md b/files/en-us/web/api/headers/index.md index b57b82df3e22ecb..4b30807015ad3de 100644 --- a/files/en-us/web/api/headers/index.md +++ b/files/en-us/web/api/headers/index.md @@ -7,12 +7,12 @@ browser-compat: api.Headers {{APIRef("Fetch API")}} {{AvailableInWorkers}} -The **`Headers`** interface of the [Fetch API](/en-US/docs/Web/API/Fetch_API) allows you to perform various actions on [HTTP request and response headers](/en-US/docs/Web/HTTP/Headers). These actions include retrieving, setting, adding to, and removing headers from the list of the request's headers. +The **`Headers`** interface of the [Fetch API](/en-US/docs/Web/API/Fetch_API) allows you to perform various actions on [HTTP request and response headers](/en-US/docs/Web/HTTP/Reference/Headers). These actions include retrieving, setting, adding to, and removing headers from the list of the request's headers. You can retrieve a `Headers` object via the {{domxref("Request.headers")}} and {{domxref("Response.headers")}} properties, and create a new `Headers` object using the {{domxref("Headers.Headers", "Headers()")}} constructor. Compared to using plain objects, using `Headers` objects to send requests provides some additional input sanitization. For example, it normalizes header names to lowercase, strips leading and trailing whitespace from header values, and prevents certain headers from being set. > [!NOTE] -> You can find out more about the available headers by reading our [HTTP headers](/en-US/docs/Web/HTTP/Headers) reference. +> You can find out more about the available headers by reading our [HTTP headers](/en-US/docs/Web/HTTP/Reference/Headers) reference. ## Description @@ -103,5 +103,5 @@ myHeaders.get("Content-Type"); // should return 'text/xml' ## See also - [ServiceWorker API](/en-US/docs/Web/API/Service_Worker_API) -- [HTTP access control (CORS)](/en-US/docs/Web/HTTP/CORS) +- [HTTP access control (CORS)](/en-US/docs/Web/HTTP/Guides/CORS) - [HTTP](/en-US/docs/Web/HTTP) diff --git a/files/en-us/web/api/headers/keys/index.md b/files/en-us/web/api/headers/keys/index.md index eae2284360d34e8..d05efdf1f87e2b8 100644 --- a/files/en-us/web/api/headers/keys/index.md +++ b/files/en-us/web/api/headers/keys/index.md @@ -54,5 +54,5 @@ vary ## See also - [ServiceWorker API](/en-US/docs/Web/API/Service_Worker_API) -- [HTTP access control (CORS)](/en-US/docs/Web/HTTP/CORS) +- [HTTP access control (CORS)](/en-US/docs/Web/HTTP/Guides/CORS) - [HTTP](/en-US/docs/Web/HTTP) diff --git a/files/en-us/web/api/headers/set/index.md b/files/en-us/web/api/headers/set/index.md index 52bd6d425bb0d42..e86acf335bd96e2 100644 --- a/files/en-us/web/api/headers/set/index.md +++ b/files/en-us/web/api/headers/set/index.md @@ -80,5 +80,5 @@ overwrite it. ## See also - [ServiceWorker API](/en-US/docs/Web/API/Service_Worker_API) -- [HTTP access control (CORS)](/en-US/docs/Web/HTTP/CORS) +- [HTTP access control (CORS)](/en-US/docs/Web/HTTP/Guides/CORS) - [HTTP](/en-US/docs/Web/HTTP) diff --git a/files/en-us/web/api/headers/values/index.md b/files/en-us/web/api/headers/values/index.md index 323dde7462fb0c8..09bef377d52dacb 100644 --- a/files/en-us/web/api/headers/values/index.md +++ b/files/en-us/web/api/headers/values/index.md @@ -54,5 +54,5 @@ Accept-Language ## See also - [ServiceWorker API](/en-US/docs/Web/API/Service_Worker_API) -- [HTTP access control (CORS)](/en-US/docs/Web/HTTP/CORS) +- [HTTP access control (CORS)](/en-US/docs/Web/HTTP/Guides/CORS) - [HTTP](/en-US/docs/Web/HTTP) diff --git a/files/en-us/web/api/hid/connect_event/index.md b/files/en-us/web/api/hid/connect_event/index.md index 19a70cbab3e2497..53b7b8f572f2790 100644 --- a/files/en-us/web/api/hid/connect_event/index.md +++ b/files/en-us/web/api/hid/connect_event/index.md @@ -16,10 +16,10 @@ The **`connect`** event of the {{domxref("HID")}} interface fires when the user Use the event name in methods like {{domxref("EventTarget.addEventListener", "addEventListener()")}}, or set an event handler property. -```js -addEventListener("connect", (event) => {}); +```js-nolint +addEventListener("connect", (event) => { }) -onconnect = (event) => {}; +onconnect = (event) => { } ``` ## Event type diff --git a/files/en-us/web/api/hid/disconnect_event/index.md b/files/en-us/web/api/hid/disconnect_event/index.md index 28ae16defbf47cd..af276ebdef2e494 100644 --- a/files/en-us/web/api/hid/disconnect_event/index.md +++ b/files/en-us/web/api/hid/disconnect_event/index.md @@ -16,10 +16,10 @@ The **`disconnect`** event of the {{domxref("HID")}} interface fires when the us Use the event name in methods like {{domxref("EventTarget.addEventListener", "addEventListener()")}}, or set an event handler property. -```js -addEventListener("disconnect", (event) => {}); +```js-nolint +addEventListener("disconnect", (event) => { }) -ondisconnect = (event) => {}; +ondisconnect = (event) => { } ``` ## Event type diff --git a/files/en-us/web/api/hid/requestdevice/index.md b/files/en-us/web/api/hid/requestdevice/index.md index bf5deda7805c285..c7ed2b970480e1b 100644 --- a/files/en-us/web/api/hid/requestdevice/index.md +++ b/files/en-us/web/api/hid/requestdevice/index.md @@ -34,7 +34,7 @@ requestDevice(options) - : An integer representing the usage page component of the HID usage of the requested device. The usage for a top level collection is used to identify the device type. - Standard HID usage values can be found in the [HID Usage Tables](https://usb.org/document-library/hid-usage-tables-15) document + Standard HID usage values can be found in the [HID Usage Tables](https://usb.org/document-library/hid-usage-tables-16) document - `usage` {{optional_inline}} - : An integer representing the usage ID component of the HID usage of the requested device. diff --git a/files/en-us/web/api/hiddevice/collections/index.md b/files/en-us/web/api/hiddevice/collections/index.md index cc0599cdf76a302..f24143956c2f3b3 100644 --- a/files/en-us/web/api/hiddevice/collections/index.md +++ b/files/en-us/web/api/hiddevice/collections/index.md @@ -20,7 +20,7 @@ An array of report formats. Each entry contains the following: - : An integer representing the usage page component of the HID usage associated with this collection. The usage for a top level collection is used to identify the device type. - Standard HID usage values can be found in the [HID Usage Tables](https://usb.org/document-library/hid-usage-tables-15) document + Standard HID usage values can be found in the [HID Usage Tables](https://usb.org/document-library/hid-usage-tables-16) document - `usage` - : An integer representing the usage ID component of the HID usage associated with this collection. diff --git a/files/en-us/web/api/hiddevice/inputreport_event/index.md b/files/en-us/web/api/hiddevice/inputreport_event/index.md index 261186d19471ee5..86fa0d60494ac2d 100644 --- a/files/en-us/web/api/hiddevice/inputreport_event/index.md +++ b/files/en-us/web/api/hiddevice/inputreport_event/index.md @@ -16,10 +16,10 @@ The **`inputreport`** event of the {{domxref("HIDDevice")}} interface fires when Use the event name in methods like {{domxref("EventTarget.addEventListener", "addEventListener()")}}, or set an event handler property. -```js -addEventListener("inputreport", (event) => {}); +```js-nolint +addEventListener("inputreport", (event) => { }) -oninputreport = (event) => {}; +oninputreport = (event) => { } ``` ## Event type diff --git a/files/en-us/web/api/history/pushstate/index.md b/files/en-us/web/api/history/pushstate/index.md index be28e34af49ca81..123e28fa70004dd 100644 --- a/files/en-us/web/api/history/pushstate/index.md +++ b/files/en-us/web/api/history/pushstate/index.md @@ -53,7 +53,7 @@ None ({{jsxref("undefined")}}). ### Exceptions - `SecurityError` {{domxref("DOMException")}} - - : Thrown if the associated document is not fully active, or if the provided `url` parameter is not a valid URL. Browsers also throttle navigations and may throw this error, generate a warning, or ignore the call if it's called too frequently. + - : Thrown if the associated document is not fully active, or if the provided `url` parameter is not a valid URL, or if the method is called too frequently. - `DataCloneError` {{domxref("DOMException")}} - : Thrown if the provided `state` parameter is not serializable. diff --git a/files/en-us/web/api/history/replacestate/index.md b/files/en-us/web/api/history/replacestate/index.md index a268367fbecc94a..5a6d293ef2a6907 100644 --- a/files/en-us/web/api/history/replacestate/index.md +++ b/files/en-us/web/api/history/replacestate/index.md @@ -40,7 +40,7 @@ None ({{jsxref("undefined")}}). ### Exceptions - `SecurityError` {{domxref("DOMException")}} - - : Thrown if the associated document is not fully active, or if the provided `url` parameter is not a valid URL. Browsers also throttle navigations and may throw this error, generate a warning, or ignore the call if it's called too frequently. + - : Thrown if the associated document is not fully active, or if the provided `url` parameter is not a valid URL, or if the method is called too frequently. - `DataCloneError` {{domxref("DOMException")}} - : Thrown if the provided `state` parameter is not serializable. diff --git a/files/en-us/web/api/history/scrollrestoration/index.md b/files/en-us/web/api/history/scrollrestoration/index.md index df01f418ec02379..663a4825e79266d 100644 --- a/files/en-us/web/api/history/scrollrestoration/index.md +++ b/files/en-us/web/api/history/scrollrestoration/index.md @@ -38,9 +38,7 @@ if (scrollRestoration === "manual") { ### Prevent automatic page location restoration ```js -if (history.scrollRestoration) { - history.scrollRestoration = "manual"; -} +history.scrollRestoration = "manual"; ``` ## Specifications diff --git a/files/en-us/web/api/html_dom_api/index.md b/files/en-us/web/api/html_dom_api/index.md index 971e1515acd62c4..ff239e118d5f71b 100644 --- a/files/en-us/web/api/html_dom_api/index.md +++ b/files/en-us/web/api/html_dom_api/index.md @@ -41,9 +41,9 @@ Among the things added to `Document` by the HTML standard are: - Support for accessing various information provided by the {{Glossary("HTTP")}} headers when loading the page, such as the {{DOMxRef("Document/location", "location", "", "1")}} from which the document was loaded, {{DOMxRef("Document/cookie", "cookies", "", "1")}}, {{DOMxRef("Document/lastModified", "modification date", "", "1")}}, {{DOMxRef("Document/referrer", "referring site", "", "1")}}, and so forth. - Access to lists of elements in the document's {{HTMLElement("head")}} block and {{DOMxRef("Document/body", "body", "", "1")}}, as well as lists of the {{DOMxRef("Document/images", "images", "", "1")}}, {{DOMxRef("Document/links", "links", "", "1")}}, {{DOMxRef("Document/scripts", "scripts", "", "1")}}, etc. contained in the document. -- Support for interacting with the user by examining {{DOMxRef("Document/hasFocus", "focus", "", "1")}} and by executing commands on [editable content](/en-US/docs/Web/HTML/Global_attributes/contenteditable). +- Support for interacting with the user by examining {{DOMxRef("Document/hasFocus", "focus", "", "1")}} and by executing commands on [editable content](/en-US/docs/Web/HTML/Reference/Global_attributes/contenteditable). - Event handlers for document events defined by the HTML standard to allow access to {{DOMxRef("MouseEvent", "mouse", "", "1")}} and {{DOMxRef("KeyboardEvent", "keyboard", "", "1")}} events, {{DOMxRef("HTML_Drag_and_Drop_API", "drag and drop", "", "1")}}, {{DOMxRef("HTMLMediaElement", "media control", "", "1")}}, and more. -- Event handlers for events that can be delivered to both elements and documents; these presently include only {{DOMxRef("HTMLElement/copy_event", "copy", "", "1")}}, {{DOMxRef("HTMLElement/cut_event", "cut", "", "1")}}, and {{DOMxRef("HTMLElement/paste_event", "paste", "", "1")}} actions. +- Event handlers for events that can be delivered to both elements and documents; these presently include only {{DOMxRef("Element/copy_event", "copy")}}, {{DOMxRef("Element/cut_event", "cut")}}, and {{DOMxRef("Element/paste_event", "paste")}} actions. ### HTML element interfaces @@ -59,7 +59,7 @@ The overall inheritance for HTML element classes looks like this: ![Hierarchy of interfaces for HTML elements](html-dom-hierarchy.svg) -As such, an element inherits the properties and methods of all of its ancestors. For example, consider a {{HTMLElement("a")}} element, which is represented in the DOM by an object of type {{domxref("HTMLAnchorElement")}}. The element, then, includes the anchor-specific properties and methods described in that class's documentation, but also those defined by {{domxref("HTMLElement")}} and {{domxref("Element")}}, as well as from {{domxref("Node")}} and, finally, {{domxref("EventTarget")}}. +As such, an element inherits the properties and methods of all of its ancestors. For example, consider an {{HTMLElement("a")}} element, which is represented in the DOM by an object of type {{domxref("HTMLAnchorElement")}}. The element, then, includes the anchor-specific properties and methods described in that class's documentation, but also those defined by {{domxref("HTMLElement")}} and {{domxref("Element")}}, as well as from {{domxref("Node")}} and, finally, {{domxref("EventTarget")}}. Each level defines a key aspect of the utility of the element. From `Node`, the element inherits concepts surrounding the ability for the element to be contained by another element, and to contain other elements itself. Of special importance is what is gained by inheriting from `EventTarget`: the ability to receive and handle events such as mouse clicks, play and pause events, and so forth. @@ -307,7 +307,7 @@ const sendButton = document.getElementById("sendButton"); sendButton.disabled = true; // [note: this is disabled since it causes this article to always load with this example focused and scrolled into view] -//nameField.focus(); +// nameField.focus(); nameField.addEventListener("input", (event) => { const elem = event.target; @@ -364,8 +364,8 @@ The HTML for the form looks like this: ### References -- [HTML elements reference](/en-US/docs/Web/HTML/Element) -- [HTML attribute reference](/en-US/docs/Web/HTML/Attributes) +- [HTML elements reference](/en-US/docs/Web/HTML/Reference/Elements) +- [HTML attribute reference](/en-US/docs/Web/HTML/Reference/Attributes) - {{DOMxRef("Document_Object_Model", "Document Object Model (DOM)", "", "1")}} reference ### Guides diff --git a/files/en-us/web/api/html_dom_api/microtask_guide/in_depth/index.md b/files/en-us/web/api/html_dom_api/microtask_guide/in_depth/index.md index a8a46661d0bcc1e..e0382f14d8799b1 100644 --- a/files/en-us/web/api/html_dom_api/microtask_guide/in_depth/index.md +++ b/files/en-us/web/api/html_dom_api/microtask_guide/in_depth/index.md @@ -92,7 +92,7 @@ Here we look at how the runtime functions in slightly more detail. ### Event loops -Each agent is driven by an [event loop](/en-US/docs/Web/JavaScript/Event_loop), which is repeatedly processed. During each iteration, it runs at most one pending JavaScript task, then any pending microtasks, then performs any needed rendering and painting before looping again. +Each agent is driven by an [event loop](/en-US/docs/Web/JavaScript/Reference/Execution_model), which is repeatedly processed. During each iteration, it runs at most one pending JavaScript task, then any pending microtasks, then performs any needed rendering and painting before looping again. Your website or app's code runs in the same **{{Glossary("thread")}}**, sharing the same **event loop**, as the user interface of the web browser itself. This is the **{{Glossary("main thread")}}**, and in addition to running your site's main code body, it handles receiving and dispatching user and other events, rendering and painting web content, and so forth. @@ -146,7 +146,7 @@ The microtask queue has been around for a while, but it's historically been used - [Microtask guide](/en-US/docs/Web/API/HTML_DOM_API/Microtask_guide) - {{domxref("Window.queueMicrotask()")}} -- [The Event Loop](/en-US/docs/Web/JavaScript/Event_loop) +- [The Event Loop](/en-US/docs/Web/JavaScript/Reference/Execution_model) - [Asynchronous JavaScript](/en-US/docs/Learn_web_development/Extensions/Async_JS) - [Introducing asynchronous JavaScript](/en-US/docs/Learn_web_development/Extensions/Async_JS/Introducing) - [Graceful asynchronous programming with Promises](/en-US/docs/Learn_web_development/Extensions/Async_JS/Promises) diff --git a/files/en-us/web/api/html_dom_api/microtask_guide/index.md b/files/en-us/web/api/html_dom_api/microtask_guide/index.md index 6372dbaa666bbaf..82cce927ebad840 100644 --- a/files/en-us/web/api/html_dom_api/microtask_guide/index.md +++ b/files/en-us/web/api/html_dom_api/microtask_guide/index.md @@ -6,7 +6,7 @@ page-type: guide {{DefaultAPISidebar("HTML DOM")}} -A **microtask** is a short function which is executed after the function or program which created it exits _and_ only if the [JavaScript execution stack](/en-US/docs/Web/JavaScript/Event_loop#stack) is empty, but before returning control to the event loop being used by the {{Glossary("user agent")}} to drive the script's execution environment. +A **microtask** is a short function which is executed after the function or program which created it exits _and_ only if the [JavaScript execution stack](/en-US/docs/Web/JavaScript/Reference/Execution_model#stack_and_execution_contexts) is empty, but before returning control to the event loop being used by the {{Glossary("user agent")}} to drive the script's execution environment. This event loop may be either the browser's main event loop or the event loop driving a [web worker](/en-US/docs/Web/API/Web_Workers_API). This lets the given function run without the risk of interfering with another script's execution, yet also ensures that the microtask runs before the user agent has the opportunity to react to actions taken by the microtask. diff --git a/files/en-us/web/api/html_drag_and_drop_api/drag_operations/index.md b/files/en-us/web/api/html_drag_and_drop_api/drag_operations/index.md index 508410db2c8e8a7..fd4f544ead2adf6 100644 --- a/files/en-us/web/api/html_drag_and_drop_api/drag_operations/index.md +++ b/files/en-us/web/api/html_drag_and_drop_api/drag_operations/index.md @@ -18,7 +18,7 @@ In HTML, apart from the default behavior for images, links, and selections, no o To make other HTML elements draggable, three things must be done: -1. Set the [`draggable`](/en-US/docs/Web/HTML/Global_attributes/draggable) attribute to `"true"` on the element that you wish to make draggable. +1. Set the [`draggable`](/en-US/docs/Web/HTML/Reference/Global_attributes/draggable) attribute to `"true"` on the element that you wish to make draggable. 2. Add a listener for the {{domxref("HTMLElement/dragstart_event", "dragstart")}} event. 3. [Set the drag data](/en-US/docs/Web/API/DataTransfer/setData) in the above listener. @@ -36,9 +36,9 @@ draggableElement.addEventListener("dragstart", (event) => ); ``` -The [`draggable`](/en-US/docs/Web/HTML/Global_attributes/draggable) attribute is set to `"true"`, so this element becomes draggable. If this attribute were omitted or set to `"false"`, the element would not be dragged, and instead the text would be selected. +The [`draggable`](/en-US/docs/Web/HTML/Reference/Global_attributes/draggable) attribute is set to `"true"`, so this element becomes draggable. If this attribute were omitted or set to `"false"`, the element would not be dragged, and instead the text would be selected. -The [`draggable`](/en-US/docs/Web/HTML/Global_attributes/draggable) attribute may be used on any element, including images and links. However, for these last two, the default value is `true`, so you would only use the [`draggable`](/en-US/docs/Web/HTML/Global_attributes/draggable) attribute with a value of `false` to disable dragging of these elements. +The [`draggable`](/en-US/docs/Web/HTML/Reference/Global_attributes/draggable) attribute may be used on any element, including images and links. However, for these last two, the default value is `true`, so you would only use the [`draggable`](/en-US/docs/Web/HTML/Reference/Global_attributes/draggable) attribute with a value of `false` to disable dragging of these elements. > [!NOTE] > When an element is made draggable, text or other elements within it can no longer be selected in the normal way by clicking and dragging with the mouse. Instead, the user must hold down the <kbd>Alt</kbd> key to select text with the mouse, or use the keyboard. @@ -240,7 +240,7 @@ There are several ways in which you can indicate to the user that a drop is allo Although the exact appearance depends on the user's platform, typically a plus sign icon will appear for a `copy` for example, and a 'cannot drop here' icon will appear when a drop is not allowed. This mouse pointer feedback is sufficient in many cases. -For more complex visual effects, you can perform other operations during the {{domxref("HTMLElement/dragenter_event", "dragenter")}} event. For example, by inserting an element at the location where the drop will occur. This might be an insertion marker, or an element that represents the dragged element in its new location. To do this, you could create an [`<img>`](/en-US/docs/Web/HTML/Element/img) element and insert it into the document during the {{domxref("HTMLElement/dragenter_event", "dragenter")}} event. +For more complex visual effects, you can perform other operations during the {{domxref("HTMLElement/dragenter_event", "dragenter")}} event. For example, by inserting an element at the location where the drop will occur. This might be an insertion marker, or an element that represents the dragged element in its new location. To do this, you could create an [`<img>`](/en-US/docs/Web/HTML/Reference/Elements/img) element and insert it into the document during the {{domxref("HTMLElement/dragenter_event", "dragenter")}} event. The {{domxref("HTMLElement/dragover_event", "dragover")}} event will fire at the element the mouse is pointing at. Naturally, you may need to move the insertion marker around a {{domxref("HTMLElement/dragover_event", "dragover")}} event as well. You can use the event's {{domxref("MouseEvent.clientX","clientX")}} and {{domxref("MouseEvent.clientY","clientY")}} properties as with other mouse events to determine the location of the mouse pointer. diff --git a/files/en-us/web/api/html_drag_and_drop_api/file_drag_and_drop/index.md b/files/en-us/web/api/html_drag_and_drop_api/file_drag_and_drop/index.md index ff13e71f311796b..ae19acb7e01f73d 100644 --- a/files/en-us/web/api/html_drag_and_drop_api/file_drag_and_drop/index.md +++ b/files/en-us/web/api/html_drag_and_drop_api/file_drag_and_drop/index.md @@ -8,7 +8,7 @@ page-type: guide HTML Drag and Drop interfaces enable web applications to drag and drop files on a web page. This document describes how an application can accept one or more files that are dragged from the underlying platform's _file manager_ and dropped on a web page. -The main steps to drag and drop are to define a _drop zone_ (i.e. a target element for the file drop) and to define event handlers for the {{domxref("HTMLElement/drop_event", "drop")}} and {{domxref("HTMLElement/dragover_event", "dragover")}} events. These steps are described below, including example code snippets. The full source code is available in [MDN's drag-and-drop repository](https://github.com/mdn/dom-examples/tree/main/drag-and-drop) (pull requests and/or issues are welcome). +The main steps to drag and drop are to define a _drop zone_ (i.e., a target element for the file drop) and to define event handlers for the {{domxref("HTMLElement/drop_event", "drop")}} and {{domxref("HTMLElement/dragover_event", "dragover")}} events. These steps are described below, including example code snippets. The full source code is available in [MDN's drag-and-drop repository](https://github.com/mdn/dom-examples/tree/main/drag-and-drop) (pull requests and/or issues are welcome). Note that [HTML drag and drop](/en-US/docs/Web/API/HTML_Drag_and_Drop_API) defines two different APIs to support dragging and dropping files. One API is the {{domxref("DataTransfer")}} interface and the second API is the {{domxref("DataTransferItem")}} and {{domxref("DataTransferItemList")}} interfaces. This example illustrates the use of both APIs (and does not use any Gecko specific interfaces). diff --git a/files/en-us/web/api/html_drag_and_drop_api/index.md b/files/en-us/web/api/html_drag_and_drop_api/index.md index 34ad718d96cc778..1332f7290e03a43 100644 --- a/files/en-us/web/api/html_drag_and_drop_api/index.md +++ b/files/en-us/web/api/html_drag_and_drop_api/index.md @@ -44,7 +44,7 @@ This section is a summary of the basic steps to add drag-and-drop functionality #### Identify what is draggable -Making an element _draggable_ requires adding the [`draggable`](/en-US/docs/Web/HTML/Global_attributes/draggable) attribute and the {{domxref("HTMLElement.dragstart_event","dragstart")}} event handler, as shown in the following code sample: +Making an element _draggable_ requires adding the [`draggable`](/en-US/docs/Web/HTML/Reference/Global_attributes/draggable) attribute and the {{domxref("HTMLElement.dragstart_event","dragstart")}} event handler, as shown in the following code sample: ```html <script> @@ -66,7 +66,7 @@ Making an element _draggable_ requires adding the [`draggable`](/en-US/docs/Web/ For more information, see: -- [Draggable attribute reference](/en-US/docs/Web/HTML/Global_attributes/draggable) +- [Draggable attribute reference](/en-US/docs/Web/HTML/Reference/Global_attributes/draggable) - [Drag operations guide](/en-US/docs/Web/API/HTML_Drag_and_Drop_API/Drag_operations#the_draggable_attribute) #### Define the drag's data @@ -232,15 +232,13 @@ The {{domxref("DataTransferItemList")}} object is a list of {{domxref("DataTrans A key difference between the {{domxref("DataTransfer")}} and {{domxref("DataTransferItem")}} interfaces is that the former uses the synchronous {{domxref("DataTransfer.getData","getData()")}} method to access a drag item's data, but the latter instead uses the asynchronous {{domxref("DataTransferItem.getAsString","getAsString()")}} method. -> **Note:** {{domxref("DragEvent")}} and {{domxref("DataTransfer")}} are broadly supported on desktop browsers. However, the {{domxref("DataTransferItem")}} and {{domxref("DataTransferItemList")}} interfaces have limited browser support. See [Interoperability](#interoperability) for more information about drag-and-drop interoperability. - ## Examples - [Copying and moving elements with the `DataTransfer` interface](https://mdn.github.io/dom-examples/drag-and-drop/copy-move-DataTransfer.html) - [Copying and moving elements with the `DataTransferListItem` interface](https://mdn.github.io/dom-examples/drag-and-drop/copy-move-DataTransferItemList.html) - Dragging and dropping files (Firefox only): <https://jsfiddle.net/9C2EF/> - Dragging and dropping files (All browsers): [https://jsbin.com/hiqasek/](https://jsbin.com/hiqasek/edit?html,js,output) -- A parking project using the Drag and Drop API: <https://park.glitch.me/> (You can edit [here](https://glitch.com/edit/#!/park)) +- A parking project using the Drag and Drop API: <https://park.glitch.me/> ([Edit it here](https://glitch.com/edit/#!/park)) ## Specifications diff --git a/files/en-us/web/api/htmlallcollection/index.md b/files/en-us/web/api/htmlallcollection/index.md index 885bbef7046c9ac..c6cfbd3c8b847d2 100644 --- a/files/en-us/web/api/htmlallcollection/index.md +++ b/files/en-us/web/api/htmlallcollection/index.md @@ -7,7 +7,7 @@ browser-compat: api.HTMLAllCollection {{APIRef("DOM")}}{{Deprecated_Header}} -The **`HTMLAllCollection`** interface represents a collection of _all_ of the document's elements, accessible by index (like an array) and by the element's [`id`](/en-US/docs/Web/HTML/Global_attributes/id). It is returned by the {{domxref("document.all")}} property. +The **`HTMLAllCollection`** interface represents a collection of _all_ of the document's elements, accessible by index (like an array) and by the element's [`id`](/en-US/docs/Web/HTML/Reference/Global_attributes/id). It is returned by the {{domxref("document.all")}} property. `HTMLAllCollection` has a very similar shape to {{domxref("HTMLCollection")}}, but there are many subtle behavior differences — for example, `HTMLAllCollection` can be called as a function, and its `item()` method can be called with a string representing an element's `id` or `name` attribute. @@ -21,7 +21,7 @@ The **`HTMLAllCollection`** interface represents a collection of _all_ of the do - {{domxref("HTMLAllCollection.item()")}} - : Returns the element located at the specified offset into the collection, or the element with the specified value for its `id` or `name` attribute. Returns `null` if no element is found. - {{domxref("HTMLAllCollection.namedItem()")}} - - : Returns the first [element](/en-US/docs/Web/API/Element) in the collection whose [`id`](/en-US/docs/Web/HTML/Global_attributes/id) or `name` attribute match the given string name, or `null` if no element matches. + - : Returns the first [element](/en-US/docs/Web/API/Element) in the collection whose [`id`](/en-US/docs/Web/HTML/Reference/Global_attributes/id) or `name` attribute match the given string name, or `null` if no element matches. ## Usage in JavaScript diff --git a/files/en-us/web/api/htmlanchorelement/attributionsrc/index.md b/files/en-us/web/api/htmlanchorelement/attributionsrc/index.md index 99214179e004611..4346648cc27c234 100644 --- a/files/en-us/web/api/htmlanchorelement/attributionsrc/index.md +++ b/files/en-us/web/api/htmlanchorelement/attributionsrc/index.md @@ -10,7 +10,7 @@ browser-compat: api.HTMLAnchorElement.attributionSrc {{APIRef("Attribution Reporting API")}}{{securecontext_header}}{{SeeCompatTable}} -The **`attributionSrc`** property of the {{domxref("HTMLAnchorElement")}} interface gets and sets the [`attributionsrc`](/en-US/docs/Web/HTML/Element/a#attributionsrc) attribute on an {{htmlelement("a")}} element programmatically, reflecting the value of that attribute. `attributionsrc` specifies that you want the browser to send an {{httpheader("Attribution-Reporting-Eligible")}} header. On the server-side this is used to trigger sending an {{httpheader("Attribution-Reporting-Register-Source")}} header in the response, to register of a [navigation-based attribution source](/en-US/docs/Web/API/Attribution_Reporting_API/Registering_sources#navigation-based_attribution_sources). +The **`attributionSrc`** property of the {{domxref("HTMLAnchorElement")}} interface gets and sets the [`attributionsrc`](/en-US/docs/Web/HTML/Reference/Elements/a#attributionsrc) attribute on an {{htmlelement("a")}} element programmatically, reflecting the value of that attribute. `attributionsrc` specifies that you want the browser to send an {{httpheader("Attribution-Reporting-Eligible")}} header. On the server-side this is used to trigger sending an {{httpheader("Attribution-Reporting-Register-Source")}} header in the response, to register of a [navigation-based attribution source](/en-US/docs/Web/API/Attribution_Reporting_API/Registering_sources#navigation-based_attribution_sources). The browser stores the source data associated with the navigation-based attribution source (as provided in the {{httpheader("Attribution-Reporting-Register-Source")}} response header) when it receives the navigation response. @@ -22,7 +22,7 @@ See the [Attribution Reporting API](/en-US/docs/Web/API/Attribution_Reporting_AP A string. There are two versions of this property that you can get and set: -- Empty string, i.e. `aElem.attributionSrc=""`. This specifies that you want the {{httpheader("Attribution-Reporting-Eligible")}} header sent to the same server that the `href` attribute points to. This is fine when you are handling the attribution source registration on the same server. +- Empty string, i.e., `aElem.attributionSrc=""`. This specifies that you want the {{httpheader("Attribution-Reporting-Eligible")}} header sent to the same server that the `href` attribute points to. This is fine when you are handling the attribution source registration on the same server. - Value containing one or more URLs, for example: ```js diff --git a/files/en-us/web/api/htmlanchorelement/index.md b/files/en-us/web/api/htmlanchorelement/index.md index 21928d832e60284..a74808bffb0b781 100644 --- a/files/en-us/web/api/htmlanchorelement/index.md +++ b/files/en-us/web/api/htmlanchorelement/index.md @@ -7,7 +7,7 @@ browser-compat: api.HTMLAnchorElement {{APIRef("HTML DOM")}} -The **`HTMLAnchorElement`** interface represents hyperlink elements and provides special properties and methods (beyond those of the regular {{domxref("HTMLElement")}} object interface that they inherit from) for manipulating the layout and presentation of such elements. This interface corresponds to [`<a>`](/en-US/docs/Web/HTML/Element/a) element; not to be confused with [`<link>`](/en-US/docs/Web/HTML/Element/link), which is represented by [`HTMLLinkElement`](/en-US/docs/Web/API/HTMLLinkElement). +The **`HTMLAnchorElement`** interface represents hyperlink elements and provides special properties and methods (beyond those of the regular {{domxref("HTMLElement")}} object interface that they inherit from) for manipulating the layout and presentation of such elements. This interface corresponds to [`<a>`](/en-US/docs/Web/HTML/Reference/Elements/a) element; not to be confused with [`<link>`](/en-US/docs/Web/HTML/Reference/Elements/link), which is represented by [`HTMLLinkElement`](/en-US/docs/Web/API/HTMLLinkElement). {{InheritanceDiagram}} @@ -16,7 +16,7 @@ The **`HTMLAnchorElement`** interface represents hyperlink elements and provides _Inherits properties from its parent, {{domxref("HTMLElement")}}._ - {{domxref("HTMLAnchorElement.attributionSrc")}} {{securecontext_inline}} {{experimental_inline}} - - : Gets and sets the [`attributionsrc`](/en-US/docs/Web/HTML/Element/a#attributionsrc) attribute on an {{htmlelement("a")}} element programmatically, reflecting the value of that attribute. `attributionsrc` specifies that you want the browser to send an {{httpheader("Attribution-Reporting-Eligible")}} header. On the server-side this is used to trigger sending an {{httpheader("Attribution-Reporting-Register-Source")}} header in the response, to register a navigation-based attribution source. + - : Gets and sets the [`attributionsrc`](/en-US/docs/Web/HTML/Reference/Elements/a#attributionsrc) attribute on an {{htmlelement("a")}} element programmatically, reflecting the value of that attribute. `attributionsrc` specifies that you want the browser to send an {{httpheader("Attribution-Reporting-Eligible")}} header. On the server-side this is used to trigger sending an {{httpheader("Attribution-Reporting-Register-Source")}} header in the response, to register a navigation-based attribution source. - {{domxref("HTMLAnchorElement.download")}} - : A string indicating that the linked resource is intended to be downloaded rather than displayed in the browser. The value represents the proposed name of the file. If the name is not a valid filename of the underlying OS, the browser will adapt it. - {{domxref("HTMLAnchorElement.hash")}} @@ -26,9 +26,9 @@ _Inherits properties from its parent, {{domxref("HTMLElement")}}._ - {{domxref("HTMLAnchorElement.hostname")}} - : A string representing the hostname in the referenced URL. - {{domxref("HTMLAnchorElement.href")}} - - : A string that is the result of parsing the [`href`](/en-US/docs/Web/HTML/Element/a#href) HTML attribute relative to the document, containing a valid URL of a linked resource. + - : A string that is the result of parsing the [`href`](/en-US/docs/Web/HTML/Reference/Elements/a#href) HTML attribute relative to the document, containing a valid URL of a linked resource. - {{domxref("HTMLAnchorElement.hreflang")}} - - : A string that reflects the [`hreflang`](/en-US/docs/Web/HTML/Element/a#hreflang) HTML attribute, indicating the language of the linked resource. + - : A string that reflects the [`hreflang`](/en-US/docs/Web/HTML/Reference/Elements/a#hreflang) HTML attribute, indicating the language of the linked resource. - {{domxref("HTMLAnchorElement.origin")}} {{ReadOnlyInline}} - : Returns a string containing the origin of the URL, that is its scheme, its domain and its port. - {{domxref("HTMLAnchorElement.password")}} @@ -42,19 +42,19 @@ _Inherits properties from its parent, {{domxref("HTMLElement")}}._ - {{domxref("HTMLAnchorElement.protocol")}} - : A string representing the protocol component, including trailing colon (`:`), of the referenced URL. - {{domxref("HTMLAnchorElement.referrerPolicy")}} - - : A string that reflects the [`referrerpolicy`](/en-US/docs/Web/HTML/Element/a#referrerpolicy) HTML attribute indicating which referrer to use. + - : A string that reflects the [`referrerpolicy`](/en-US/docs/Web/HTML/Reference/Elements/a#referrerpolicy) HTML attribute indicating which referrer to use. - {{domxref("HTMLAnchorElement.rel")}} - - : A string that reflects the [`rel`](/en-US/docs/Web/HTML/Element/a#rel) HTML attribute, specifying the relationship of the target object to the linked object. + - : A string that reflects the [`rel`](/en-US/docs/Web/HTML/Reference/Elements/a#rel) HTML attribute, specifying the relationship of the target object to the linked object. - {{domxref("HTMLAnchorElement.relList")}} {{ReadOnlyInline}} - - : Returns a {{domxref("DOMTokenList")}} that reflects the [`rel`](/en-US/docs/Web/HTML/Element/a#rel) HTML attribute, as a list of tokens. + - : Returns a {{domxref("DOMTokenList")}} that reflects the [`rel`](/en-US/docs/Web/HTML/Reference/Elements/a#rel) HTML attribute, as a list of tokens. - {{domxref("HTMLAnchorElement.search")}} - : A string representing the search element, including leading question mark (`?`), if any, of the referenced URL. - {{domxref("HTMLAnchorElement.target")}} - - : A string that reflects the [`target`](/en-US/docs/Web/HTML/Element/a#target) HTML attribute, indicating where to display the linked resource. + - : A string that reflects the [`target`](/en-US/docs/Web/HTML/Reference/Elements/a#target) HTML attribute, indicating where to display the linked resource. - {{domxref("HTMLAnchorElement.text")}} - : A string being a synonym for the {{domxref("Node.textContent")}} property. - {{domxref("HTMLAnchorElement.type")}} - - : A string that reflects the [`type`](/en-US/docs/Web/HTML/Element/a#type) HTML attribute, indicating the MIME type of the linked resource. + - : A string that reflects the [`type`](/en-US/docs/Web/HTML/Reference/Elements/a#type) HTML attribute, indicating the MIME type of the linked resource. - {{domxref("HTMLAnchorElement.username")}} - : A string containing the username specified before the domain name. @@ -67,7 +67,7 @@ _Inherits properties from its parent, {{domxref("HTMLElement")}}._ - `HTMLAnchorElement.name` {{deprecated_inline}} - : A string representing the anchor name. - `HTMLAnchorElement.rev` {{deprecated_inline}} - - : A string representing that the [`rev`](/en-US/docs/Web/HTML/Element/a#rev) HTML attribute, specifying the relationship of the link object to the target object. + - : A string representing that the [`rev`](/en-US/docs/Web/HTML/Reference/Elements/a#rev) HTML attribute, specifying the relationship of the link object to the target object. - `HTMLAnchorElement.shape` {{deprecated_inline}} - : A string representing the shape of the active area. diff --git a/files/en-us/web/api/htmlanchorelement/protocol/index.md b/files/en-us/web/api/htmlanchorelement/protocol/index.md index da8203f85c3c17c..9b9eddf532fd610 100644 --- a/files/en-us/web/api/htmlanchorelement/protocol/index.md +++ b/files/en-us/web/api/htmlanchorelement/protocol/index.md @@ -8,7 +8,7 @@ browser-compat: api.HTMLAnchorElement.protocol {{ApiRef("HTML DOM")}} -The **`protocol`** property of the {{domxref("HTMLAnchorElement")}} interface is a string containing the protocol or scheme of the `<area>` element's `href`, including the final `":"`. If the port is the default for the protocol (`80` for `ws:` and `http:`, `443` for `wss:` and `https:`, and `21` for `ftp:`), this property contains an empty string, `""`. +The **`protocol`** property of the {{domxref("HTMLAnchorElement")}} interface is a string containing the protocol or scheme of the `<area>` element's `href`, including the final `":"`. This property can be set to change the protocol of the URL. A `":"` is appended to the provided string if not provided. The provided scheme has to be compatible with the rest of the URL to be considered valid. diff --git a/files/en-us/web/api/htmlanchorelement/referrerpolicy/index.md b/files/en-us/web/api/htmlanchorelement/referrerpolicy/index.md index 63236575fa491ba..7af9f64f7a6fffb 100644 --- a/files/en-us/web/api/htmlanchorelement/referrerpolicy/index.md +++ b/files/en-us/web/api/htmlanchorelement/referrerpolicy/index.md @@ -10,7 +10,7 @@ browser-compat: api.HTMLAnchorElement.referrerPolicy The **`HTMLAnchorElement.referrerPolicy`** -property reflect the HTML [`referrerpolicy`](/en-US/docs/Web/HTML/Element/a#referrerpolicy) attribute of the +property reflect the HTML [`referrerpolicy`](/en-US/docs/Web/HTML/Reference/Elements/a#referrerpolicy) attribute of the {{HTMLElement("a")}} element defining which referrer is sent when fetching the resource. ## Value @@ -23,7 +23,7 @@ A string; one of the following: - `no-referrer-when-downgrade` - : The URL is sent as a referrer when the protocol security level stays the same (e.g.HTTP→HTTP, - HTTPS→HTTPS), but isn't sent to a less secure destination (e.g. HTTPS→HTTP). + HTTPS→HTTPS), but isn't sent to a less secure destination (e.g., HTTPS→HTTP). - `origin` - : Only send the origin of the document as the referrer in all cases. The document `https://example.com/page.html` will send the referrer @@ -36,12 +36,12 @@ A string; one of the following: cross-origin requests will contain no referrer information. - `strict-origin` - : Only send the origin of the document as the referrer when the protocol security - level stays the same (e.g. HTTPS→HTTPS), but don't send it to a less secure - destination (e.g. HTTPS→HTTP). + level stays the same (e.g., HTTPS→HTTPS), but don't send it to a less secure + destination (e.g., HTTPS→HTTP). - `strict-origin-when-cross-origin` (default) - : This is the user agent's default behavior if no policy is specified. Send a full URL when performing a same-origin request, only send the origin when the - protocol security level stays the same (e.g. HTTPS→HTTPS), and send no header to a - less secure destination (e.g. HTTPS→HTTP). + protocol security level stays the same (e.g., HTTPS→HTTPS), and send no header to a + less secure destination (e.g., HTTPS→HTTP). - `unsafe-url` - : Send a full URL when performing a same-origin or cross-origin request. This policy will leak origins and paths from TLS-protected resources to insecure origins. diff --git a/files/en-us/web/api/htmlanchorelement/rel/index.md b/files/en-us/web/api/htmlanchorelement/rel/index.md index ebf9b7c61d347f4..a7eacfa6433c606 100644 --- a/files/en-us/web/api/htmlanchorelement/rel/index.md +++ b/files/en-us/web/api/htmlanchorelement/rel/index.md @@ -8,7 +8,7 @@ browser-compat: api.HTMLAnchorElement.rel {{APIRef("HTML DOM")}} -The **`HTMLAnchorElement.rel`** property reflects the [`rel`](/en-US/docs/Web/HTML/Attributes/rel) attribute. It is a string containing a space-separated list of link types indicating the relationship between the resource represented by the {{HTMLElement("a")}} element and the current document. +The **`HTMLAnchorElement.rel`** property reflects the [`rel`](/en-US/docs/Web/HTML/Reference/Attributes/rel) attribute. It is a string containing a space-separated list of link types indicating the relationship between the resource represented by the {{HTMLElement("a")}} element and the current document. ## Value diff --git a/files/en-us/web/api/htmlanchorelement/rellist/index.md b/files/en-us/web/api/htmlanchorelement/rellist/index.md index 110559c47b2dd5e..fd896f77ecf1ea4 100644 --- a/files/en-us/web/api/htmlanchorelement/rellist/index.md +++ b/files/en-us/web/api/htmlanchorelement/rellist/index.md @@ -8,7 +8,7 @@ browser-compat: api.HTMLAnchorElement.relList {{APIRef("HTML DOM")}} -The **`HTMLAnchorElement.relList`** read-only property reflects the [`rel`](/en-US/docs/Web/HTML/Attributes/rel) attribute. It is a live {{domxref("DOMTokenList")}} containing the set of link types indicating the relationship between the resource represented by the {{HTMLElement("a")}} element and the current document. +The **`HTMLAnchorElement.relList`** read-only property reflects the [`rel`](/en-US/docs/Web/HTML/Reference/Attributes/rel) attribute. It is a live {{domxref("DOMTokenList")}} containing the set of link types indicating the relationship between the resource represented by the {{HTMLElement("a")}} element and the current document. The property itself is read-only, meaning you can't substitute the {{domxref("DOMTokenList")}} with another one, but its contents can still be changed. diff --git a/files/en-us/web/api/htmlanchorelement/search/index.md b/files/en-us/web/api/htmlanchorelement/search/index.md index b1b582f11961166..e3a5e4bd51a991f 100644 --- a/files/en-us/web/api/htmlanchorelement/search/index.md +++ b/files/en-us/web/api/htmlanchorelement/search/index.md @@ -42,7 +42,7 @@ Alternatively, [`URLSearchParams`](/en-US/docs/Web/API/URLSearchParams/get#examp ```js let params = new URLSearchParams(queryString); -let q = parseInt(params.get("q")); // returns the number 123 +let q = parseInt(params.get("q"), 10); // returns the number 123 ``` ## Specifications diff --git a/files/en-us/web/api/htmlanchorelement/target/index.md b/files/en-us/web/api/htmlanchorelement/target/index.md index 2d4a3e5fe333b34..3c201a4f0e7c4fd 100644 --- a/files/en-us/web/api/htmlanchorelement/target/index.md +++ b/files/en-us/web/api/htmlanchorelement/target/index.md @@ -10,14 +10,14 @@ browser-compat: api.HTMLAnchorElement.target The **`target`** property of the {{domxref("HTMLAnchorElement")}} interface is a string that indicates where to display the linked resource. -It reflects the [`target`](/en-US/docs/Web/HTML/Element/a#target) attribute of the {{HTMLElement("a")}} element. +It reflects the [`target`](/en-US/docs/Web/HTML/Reference/Elements/a#target) attribute of the {{HTMLElement("a")}} element. ## Value A string representing the target. Its value can be: - The name of a {{HTMLElement("frame")}}. -- One of the [keyword with specific values](/en-US/docs/Web/HTML/Element/a#target): `_blank`, `_self`, `_parent`, or `_top`. +- One of the [keyword with specific values](/en-US/docs/Web/HTML/Reference/Elements/a#target): `_blank`, `_self`, `_parent`, or `_top`. ## Example diff --git a/files/en-us/web/api/htmlareaelement/alt/index.md b/files/en-us/web/api/htmlareaelement/alt/index.md index 7083334a1a4e9ee..0b74f649b7937a9 100644 --- a/files/en-us/web/api/htmlareaelement/alt/index.md +++ b/files/en-us/web/api/htmlareaelement/alt/index.md @@ -8,7 +8,7 @@ browser-compat: api.HTMLAreaElement.alt {{APIRef("HTML DOM")}} -The **`alt`** property of the {{DOMxRef("HTMLAreaElement")}} interface specifies the text of the hyperlink, defining the textual label for an image map's link. It reflects the {{htmlelement("area")}} element's [`alt`](/en-US/docs/Web/HTML/Element/area#alt) attribute. +The **`alt`** property of the {{DOMxRef("HTMLAreaElement")}} interface specifies the text of the hyperlink, defining the textual label for an image map's link. It reflects the {{htmlelement("area")}} element's [`alt`](/en-US/docs/Web/HTML/Reference/Elements/area#alt) attribute. The `alt` value must be text that, when presented with the `alt` text of the other `<area>` hyperlinks within the same {{htmlelement("map")}}, along with the `alt` text of the {{htmlelement("img")}} itself, provides the user with the same kind of choice as the hyperlink would when used without its text but with its shape applied to the image. diff --git a/files/en-us/web/api/htmlareaelement/coords/index.md b/files/en-us/web/api/htmlareaelement/coords/index.md index ff8d1dc28d0d41d..1dfae63dccc1ae6 100644 --- a/files/en-us/web/api/htmlareaelement/coords/index.md +++ b/files/en-us/web/api/htmlareaelement/coords/index.md @@ -8,7 +8,7 @@ browser-compat: api.HTMLAreaElement.coords {{APIRef("HTML DOM")}} -The **`coords`** property of the {{DOMxRef("HTMLAreaElement")}} interface specifies the coordinates of the element's shape as a list of floating-point numbers. It reflects the {{htmlelement("area")}} element's [`coords`](/en-US/docs/Web/HTML/Element/area#coords) attribute. +The **`coords`** property of the {{DOMxRef("HTMLAreaElement")}} interface specifies the coordinates of the element's shape as a list of floating-point numbers. It reflects the {{htmlelement("area")}} element's [`coords`](/en-US/docs/Web/HTML/Reference/Elements/area#coords) attribute. If the `shape` is `rect`, the shape is a rectangle and the string value's four comma separated numbers specify the coordinates of the top-left and bottom-right corners of the rectangle. For example, `0,0,200,20` defines the coordinates as `0,0`, which is the top-left of the image map, and `200,20`, which is 200px from the left and 20px from the top of the top-left corner of the image map. diff --git a/files/en-us/web/api/htmlareaelement/index.md b/files/en-us/web/api/htmlareaelement/index.md index fcf645c189ca1a5..94dd2b66aea45cb 100644 --- a/files/en-us/web/api/htmlareaelement/index.md +++ b/files/en-us/web/api/htmlareaelement/index.md @@ -16,9 +16,9 @@ The **`HTMLAreaElement`** interface provides special properties and methods (bey _Inherits properties from its parent {{domxref("HTMLElement")}}._ - {{domxref("HTMLAreaElement.alt")}} - - : A string that reflects the [`alt`](/en-US/docs/Web/HTML/Element/area#alt) HTML attribute, containing alternative text for the element. + - : A string that reflects the [`alt`](/en-US/docs/Web/HTML/Reference/Elements/area#alt) HTML attribute, containing alternative text for the element. - {{domxref("HTMLAreaElement.coords")}} - - : A string that reflects the [`coords`](/en-US/docs/Web/HTML/Element/area#coords) HTML attribute, containing coordinates to define the hot-spot region. + - : A string that reflects the [`coords`](/en-US/docs/Web/HTML/Reference/Elements/area#coords) HTML attribute, containing coordinates to define the hot-spot region. - {{domxref("HTMLAreaElement.download")}} - : A string indicating that the linked resource is intended to be downloaded rather than displayed in the browser. The value represent the proposed name of the file. If the name is not a valid filename of the underlying OS, browser will adjust it accordingly. - {{domxref("HTMLAreaElement.hash")}} @@ -28,7 +28,7 @@ _Inherits properties from its parent {{domxref("HTMLElement")}}._ - {{domxref("HTMLAreaElement.hostname")}} - : A string containing the hostname in the referenced URL. - {{domxref("HTMLAreaElement.href")}} - - : A string containing that reflects the [`href`](/en-US/docs/Web/HTML/Element/area#href) HTML attribute, containing a valid URL of a linked resource. + - : A string containing that reflects the [`href`](/en-US/docs/Web/HTML/Reference/Elements/area#href) HTML attribute, containing a valid URL of a linked resource. - {{domxref("HTMLAreaElement.noHref")}} {{deprecated_inline}} - : A boolean flag indicating if the area is inactive (`true`) or active (`false`). - {{domxref("HTMLAreaElement.origin")}} {{ReadOnlyInline}} @@ -44,17 +44,17 @@ _Inherits properties from its parent {{domxref("HTMLElement")}}._ - {{domxref("HTMLAreaElement.protocol")}} - : A string containing the protocol component (including trailing colon `':'`), of the referenced URL. - {{domxref("HTMLAreaElement.referrerPolicy")}} - - : A string that reflects the [`referrerpolicy`](/en-US/docs/Web/HTML/Element/area#referrerpolicy) HTML attribute indicating which referrer to use when fetching the linked resource. + - : A string that reflects the [`referrerpolicy`](/en-US/docs/Web/HTML/Reference/Elements/area#referrerpolicy) HTML attribute indicating which referrer to use when fetching the linked resource. - {{domxref("HTMLAreaElement.rel")}} - - : A string that reflects the [`rel`](/en-US/docs/Web/HTML/Element/area#rel) HTML attribute, indicating relationships of the current document to the linked resource. + - : A string that reflects the [`rel`](/en-US/docs/Web/HTML/Reference/Elements/area#rel) HTML attribute, indicating relationships of the current document to the linked resource. - {{domxref("HTMLAreaElement.relList")}} {{ReadOnlyInline}} - - : Returns a {{domxref("DOMTokenList")}} that reflects the [`rel`](/en-US/docs/Web/HTML/Element/area#rel) HTML attribute, indicating relationships of the current document to the linked resource, as a list of tokens. + - : Returns a {{domxref("DOMTokenList")}} that reflects the [`rel`](/en-US/docs/Web/HTML/Reference/Elements/area#rel) HTML attribute, indicating relationships of the current document to the linked resource, as a list of tokens. - {{domxref("HTMLAreaElement.search")}} - : A string containing the search element (including leading question mark `'?'`), if any, of the referenced URL. - {{domxref("HTMLAreaElement.shape")}} - - : A string that reflects the [`shape`](/en-US/docs/Web/HTML/Element/area#shape) HTML attribute, indicating the shape of the hot-spot, limited to known values. + - : A string that reflects the [`shape`](/en-US/docs/Web/HTML/Reference/Elements/area#shape) HTML attribute, indicating the shape of the hot-spot, limited to known values. - {{domxref("HTMLAreaElement.target")}} - - : A string that reflects the [`target`](/en-US/docs/Web/HTML/Element/area#target) HTML attribute, indicating the browsing context in which to open the linked resource. + - : A string that reflects the [`target`](/en-US/docs/Web/HTML/Reference/Elements/area#target) HTML attribute, indicating the browsing context in which to open the linked resource. - {{domxref("HTMLAreaElement.username")}} - : A string containing the username specified before the domain name. diff --git a/files/en-us/web/api/htmlareaelement/protocol/index.md b/files/en-us/web/api/htmlareaelement/protocol/index.md index 492665973290fc0..d8e223dcdd8ec93 100644 --- a/files/en-us/web/api/htmlareaelement/protocol/index.md +++ b/files/en-us/web/api/htmlareaelement/protocol/index.md @@ -8,7 +8,7 @@ browser-compat: api.HTMLAreaElement.protocol {{ApiRef("HTML DOM")}} -The **`protocol`** property of the {{domxref("HTMLAreaElement")}} interface is a string containing the protocol or scheme of the `<area>` element's `href`, including the final `":"`. If the port is the default for the protocol (`80` for `ws:` and `http:`, `443` for `wss:` and `https:`, and `21` for `ftp:`), this property contains an empty string, `""`. +The **`protocol`** property of the {{domxref("HTMLAreaElement")}} interface is a string containing the protocol or scheme of the `<area>` element's `href`, including the final `":"`. This property can be set to change the protocol of the URL. A `":"` is appended to the provided string if not provided. The provided scheme has to be compatible with the rest of the URL to be considered valid. diff --git a/files/en-us/web/api/htmlareaelement/referrerpolicy/index.md b/files/en-us/web/api/htmlareaelement/referrerpolicy/index.md index 28dfcf14af76f55..de6a2e28e872b62 100644 --- a/files/en-us/web/api/htmlareaelement/referrerpolicy/index.md +++ b/files/en-us/web/api/htmlareaelement/referrerpolicy/index.md @@ -10,7 +10,7 @@ browser-compat: api.HTMLAreaElement.referrerPolicy The **`HTMLAreaElement.referrerPolicy`** -property reflect the HTML [`referrerpolicy`](/en-US/docs/Web/HTML/Element/area#referrerpolicy) attribute of the +property reflect the HTML [`referrerpolicy`](/en-US/docs/Web/HTML/Reference/Elements/area#referrerpolicy) attribute of the {{HTMLElement("area")}} element defining which referrer is sent when fetching the resource. @@ -24,7 +24,7 @@ A string; one of the following: - `no-referrer-when-downgrade` - : The URL is sent as a referrer when the protocol security level stays the same (e.g.HTTP→HTTP, - HTTPS→HTTPS), but isn't sent to a less secure destination (e.g. HTTPS→HTTP). + HTTPS→HTTPS), but isn't sent to a less secure destination (e.g., HTTPS→HTTP). - `origin` - : Only send the origin of the document as the referrer in all cases. The document `https://example.com/page.html` will send the referrer @@ -37,12 +37,12 @@ A string; one of the following: cross-origin requests will contain no referrer information. - `strict-origin` - : Only send the origin of the document as the referrer when the protocol security - level stays the same (e.g. HTTPS→HTTPS), but don't send it to a less secure - destination (e.g. HTTPS→HTTP). + level stays the same (e.g., HTTPS→HTTPS), but don't send it to a less secure + destination (e.g., HTTPS→HTTP). - `strict-origin-when-cross-origin` (default) - : This is the user agent's default behavior if no policy is specified. Send a full URL when performing a same-origin request, only send the origin when the - protocol security level stays the same (e.g. HTTPS→HTTPS), and send no header to a - less secure destination (e.g. HTTPS→HTTP). + protocol security level stays the same (e.g., HTTPS→HTTPS), and send no header to a + less secure destination (e.g., HTTPS→HTTP). - `unsafe-url` - : Send a full URL when performing a same-origin or cross-origin request. This policy will leak origins and paths from TLS-protected resources to insecure origins. @@ -52,7 +52,7 @@ A string; one of the following: ```html <img usemap="#mapAround" width="100" height="100" src="/img/logo@2x.png" /> -<map id="myMap" name="mapAround" />> +<map id="myMap" name="mapAround"></map> ``` ```js diff --git a/files/en-us/web/api/htmlareaelement/rel/index.md b/files/en-us/web/api/htmlareaelement/rel/index.md index c1a8eaa5d15b944..b3899fe8ce81747 100644 --- a/files/en-us/web/api/htmlareaelement/rel/index.md +++ b/files/en-us/web/api/htmlareaelement/rel/index.md @@ -8,7 +8,7 @@ browser-compat: api.HTMLAreaElement.rel {{APIRef("HTML DOM")}} -The **`HTMLAreaElement.rel`** property reflects the [`rel`](/en-US/docs/Web/HTML/Attributes/rel) attribute. It is a string containing a space-separated list of link types indicating the relationship between the resource represented by the {{HTMLElement("area")}} element and the current document. +The **`HTMLAreaElement.rel`** property reflects the [`rel`](/en-US/docs/Web/HTML/Reference/Attributes/rel) attribute. It is a string containing a space-separated list of link types indicating the relationship between the resource represented by the {{HTMLElement("area")}} element and the current document. ## Value diff --git a/files/en-us/web/api/htmlareaelement/rellist/index.md b/files/en-us/web/api/htmlareaelement/rellist/index.md index 2d8ec4a47d53121..a0998a175d9bd15 100644 --- a/files/en-us/web/api/htmlareaelement/rellist/index.md +++ b/files/en-us/web/api/htmlareaelement/rellist/index.md @@ -8,7 +8,7 @@ browser-compat: api.HTMLAreaElement.relList {{APIRef("HTML DOM")}} -The **`HTMLAreaElement.relList`** read-only property reflects the [`rel`](/en-US/docs/Web/HTML/Attributes/rel) attribute. It is a live {{domxref("DOMTokenList")}} containing the set of link types indicating the relationship between the resource represented by the {{HTMLElement("area")}} element and the current document. +The **`HTMLAreaElement.relList`** read-only property reflects the [`rel`](/en-US/docs/Web/HTML/Reference/Attributes/rel) attribute. It is a live {{domxref("DOMTokenList")}} containing the set of link types indicating the relationship between the resource represented by the {{HTMLElement("area")}} element and the current document. The property itself is read-only, meaning you can't substitute the {{domxref("DOMTokenList")}} by another one, but the content of the returned list can be diff --git a/files/en-us/web/api/htmlareaelement/search/index.md b/files/en-us/web/api/htmlareaelement/search/index.md index a2158578d995635..9795a91aae78609 100644 --- a/files/en-us/web/api/htmlareaelement/search/index.md +++ b/files/en-us/web/api/htmlareaelement/search/index.md @@ -42,7 +42,7 @@ Alternatively, [`URLSearchParams`](/en-US/docs/Web/API/URLSearchParams/get#examp ```js let params = new URLSearchParams(queryString); -let q = parseInt(params.get("q")); // returns the number 123 +let q = parseInt(params.get("q"), 10); // returns the number 123 ``` ## Specifications diff --git a/files/en-us/web/api/htmlareaelement/shape/index.md b/files/en-us/web/api/htmlareaelement/shape/index.md index 45d189200f498f8..7c947238877d65a 100644 --- a/files/en-us/web/api/htmlareaelement/shape/index.md +++ b/files/en-us/web/api/htmlareaelement/shape/index.md @@ -8,7 +8,7 @@ browser-compat: api.HTMLAreaElement.shape {{APIRef("HTML DOM")}} -The **`shape`** property of the {{DOMxRef("HTMLAreaElement")}} interface specifies the shape of an image map area. It reflects the {{htmlelement("area")}} element's [`shape`](/en-US/docs/Web/HTML/Element/area#shape) attribute. +The **`shape`** property of the {{DOMxRef("HTMLAreaElement")}} interface specifies the shape of an image map area. It reflects the {{htmlelement("area")}} element's [`shape`](/en-US/docs/Web/HTML/Reference/Elements/area#shape) attribute. ## Value diff --git a/files/en-us/web/api/htmlareaelement/target/index.md b/files/en-us/web/api/htmlareaelement/target/index.md index ca7b8ef81a17c20..6a7b21222f289b5 100644 --- a/files/en-us/web/api/htmlareaelement/target/index.md +++ b/files/en-us/web/api/htmlareaelement/target/index.md @@ -10,14 +10,14 @@ browser-compat: api.HTMLAreaElement.target The **`target`** property of the {{domxref("HTMLAreaElement")}} interface is a string that indicates where to display the linked resource. -It reflects the [`target`](/en-US/docs/Web/HTML/Element/area#target) attribute of the {{HTMLElement("area")}} element. +It reflects the [`target`](/en-US/docs/Web/HTML/Reference/Elements/area#target) attribute of the {{HTMLElement("area")}} element. ## Value A string representing the target. Its value can be: - The name of a {{HTMLElement("frame")}}. -- One of the [keyword with specific values](/en-US/docs/Web/HTML/Element/area#target): `_blank`, `_self`, `_parent`, or `_top`. +- One of the [keyword with specific values](/en-US/docs/Web/HTML/Reference/Elements/area#target): `_blank`, `_self`, `_parent`, or `_top`. ## Example diff --git a/files/en-us/web/api/htmlaudioelement/index.md b/files/en-us/web/api/htmlaudioelement/index.md index 8e4173a737134de..9442669c3043540 100644 --- a/files/en-us/web/api/htmlaudioelement/index.md +++ b/files/en-us/web/api/htmlaudioelement/index.md @@ -43,7 +43,7 @@ audioElement.play(); ``` > [!NOTE] -> A common gotcha is trying to play an audio element immediately on page load. Modern browser's default autoplay policy will block that from happening. Refer to [Firefox](https://hacks.mozilla.org/2019/02/firefox-66-to-block-automatically-playing-audible-video-and-audio/) and [chrome](https://developer.chrome.com/blog/autoplay/) for best practices and work arounds. +> A common gotcha is trying to play an audio element immediately on page load. Modern browser's default autoplay policy will block that from happening. Refer to [Firefox](https://hacks.mozilla.org/2019/02/firefox-66-to-block-automatically-playing-audible-video-and-audio/) and [chrome](https://developer.chrome.com/blog/autoplay/) for best practices and workarounds. Some of the more commonly used properties of the audio element include {{domxref("HTMLMediaElement.src", "src")}}, {{domxref("HTMLMediaElement.currentTime", "currentTime")}}, {{domxref("HTMLMediaElement.duration", "duration")}}, {{domxref("HTMLMediaElement.paused", "paused")}}, {{domxref("HTMLMediaElement.muted", "muted")}}, and {{domxref("HTMLMediaElement.volume", "volume")}}. This snippet copies the audio file's duration to a variable: diff --git a/files/en-us/web/api/htmlbaseelement/index.md b/files/en-us/web/api/htmlbaseelement/index.md index 893a1f5708a50ca..79e7843cde555b4 100644 --- a/files/en-us/web/api/htmlbaseelement/index.md +++ b/files/en-us/web/api/htmlbaseelement/index.md @@ -16,9 +16,9 @@ The **`HTMLBaseElement`** interface contains the base URI for a document. This o _Inherits properties from its parent, {{domxref("HTMLElement")}}._ - {{domxref("HTMLBaseElement.href")}} - - : A string that reflects the [`href`](/en-US/docs/Web/HTML/Element/base#href) HTML attribute, containing a base URL for relative URLs in the document. + - : A string that reflects the [`href`](/en-US/docs/Web/HTML/Reference/Elements/base#href) HTML attribute, containing a base URL for relative URLs in the document. - {{domxref("HTMLBaseElement.target")}} - - : A string that reflects the [`target`](/en-US/docs/Web/HTML/Element/base#target) HTML attribute, containing a default target browsing context or frame for elements that do not have a target reference specified. + - : A string that reflects the [`target`](/en-US/docs/Web/HTML/Reference/Elements/base#target) HTML attribute, containing a default target browsing context or frame for elements that do not have a target reference specified. ## Instance methods diff --git a/files/en-us/web/api/htmlbaseelement/target/index.md b/files/en-us/web/api/htmlbaseelement/target/index.md index 32f48de9a9edceb..bef2638fb4fae4d 100644 --- a/files/en-us/web/api/htmlbaseelement/target/index.md +++ b/files/en-us/web/api/htmlbaseelement/target/index.md @@ -10,14 +10,14 @@ browser-compat: api.HTMLBaseElement.target The `target` property of the {{domxref("HTMLBaseElement")}} interface is a string that represents the default target tab to show the resulting output for hyperlinks and form elements. -It reflects the [`target`](/en-US/docs/Web/HTML/Element/base#target) attribute of the {{HTMLElement("base")}} element. +It reflects the [`target`](/en-US/docs/Web/HTML/Reference/Elements/base#target) attribute of the {{HTMLElement("base")}} element. ## Value A string representing the target. Its value can be: - The name of a {{HTMLElement("frame")}}. -- One of the [keyword with specific values](/en-US/docs/Web/HTML/Element/base#target): `_blank`, `_self`, `_parent`, or `_top`. +- One of the [keyword with specific values](/en-US/docs/Web/HTML/Reference/Elements/base#target): `_blank`, `_self`, `_parent`, or `_top`. ## Example diff --git a/files/en-us/web/api/htmlbuttonelement/checkvalidity/index.md b/files/en-us/web/api/htmlbuttonelement/checkvalidity/index.md index 78eca4453faff13..ca3ffdf10dd45e0 100644 --- a/files/en-us/web/api/htmlbuttonelement/checkvalidity/index.md +++ b/files/en-us/web/api/htmlbuttonelement/checkvalidity/index.md @@ -8,7 +8,7 @@ browser-compat: api.HTMLButtonElement.checkValidity {{APIRef("HTML DOM")}} -The **`checkValidity()`** method of the {{domxref("HTMLButtonElement")}} interface returns a boolean value which indicates if the element meets any [constraint validation](/en-US/docs/Web/HTML/Constraint_validation) rules applied to it. If false, the method also fires an {{domxref("HTMLElement/invalid_event", "invalid")}} event on the element. Because there's no default browser behavior for `checkValidity()`, canceling this `invalid` event has no effect. It always returns true if the {{HTMLElement("button")}} element's {{domxref("HTMLButtonElement/type", "type")}} is `"button"` or `"reset"`, because such buttons are never candidates for [constraint validation](/en-US/docs/Web/HTML/Constraint_validation). +The **`checkValidity()`** method of the {{domxref("HTMLButtonElement")}} interface returns a boolean value which indicates if the element meets any [constraint validation](/en-US/docs/Web/HTML/Guides/Constraint_validation) rules applied to it. If false, the method also fires an {{domxref("HTMLElement/invalid_event", "invalid")}} event on the element. Because there's no default browser behavior for `checkValidity()`, canceling this `invalid` event has no effect. It always returns true if the {{HTMLElement("button")}} element's {{domxref("HTMLButtonElement/type", "type")}} is `"button"` or `"reset"`, because such buttons are never candidates for [constraint validation](/en-US/docs/Web/HTML/Guides/Constraint_validation). > [!NOTE] > An HTML {{htmlelement("button")}} element of the `"submit"` type with a non-null {{domxref("HTMLButtonElement.validationMessage", "validationMessage")}} is considered invalid, will match the CSS {{cssxref(":invalid")}} pseudo-class, and will cause `checkValidity()` to return false. Use the {{domxref("HTMLButtonElement.setCustomValidity()")}} method to set the {{domxref("HTMLButtonElement.validationMessage")}} to the empty string to set the {{domxref("HTMLButtonElement.validity", "validity")}} state to be valid. @@ -50,5 +50,5 @@ console.log(element.checkValidity()); - {{HTMLElement("button")}} - {{HTMLElement("form")}} - [Learn: Client-side form validation](/en-US/docs/Learn_web_development/Extensions/Forms/Form_validation) -- [Guide: Constraint validation](/en-US/docs/Web/HTML/Constraint_validation) +- [Guide: Constraint validation](/en-US/docs/Web/HTML/Guides/Constraint_validation) - CSS {{cssxref(":valid")}} and {{cssxref(":invalid")}} pseudo-classes diff --git a/files/en-us/web/api/htmlbuttonelement/command/index.md b/files/en-us/web/api/htmlbuttonelement/command/index.md index 95655f404022543..96d530d32f2975f 100644 --- a/files/en-us/web/api/htmlbuttonelement/command/index.md +++ b/files/en-us/web/api/htmlbuttonelement/command/index.md @@ -3,20 +3,18 @@ title: "HTMLButtonElement: command property" short-title: command slug: Web/API/HTMLButtonElement/command page-type: web-api-instance-property -status: - - experimental browser-compat: api.HTMLButtonElement.command --- -{{APIRef("Invoker Commands API")}}{{SeeCompatTable}} +{{APIRef("Invoker Commands API")}} -The **`command`** property of the {{domxref("HTMLButtonElement")}} interface gets and sets the action to be performed on an element being controlled by this button. For this to have an effect, [`commandfor`](/en-US/docs/Web/HTML/Element/button#commandfor) must be set. +The **`command`** property of the {{domxref("HTMLButtonElement")}} interface gets and sets the action to be performed on an element being controlled by this button. For this to have an effect, [`commandfor`](/en-US/docs/Web/HTML/Reference/Elements/button#commandfor) must be set. -It reflects the [`command`](/en-US/docs/Web/HTML/Element/button#command) HTML attribute. +It reflects the [`command`](/en-US/docs/Web/HTML/Reference/Elements/button#command) HTML attribute. ## Value -A string. See the [`command`](/en-US/docs/Web/HTML/Element/button#command) attribute for valid values. +A string. See the [`command`](/en-US/docs/Web/HTML/Reference/Elements/button#command) attribute for valid values. ## Examples @@ -53,9 +51,9 @@ toggleBtn.command = "show-popover"; const image = document.getElementById("the-image"); image.addEventListener("command", (event) => { - if (event.command == "--rotate-left") { + if (event.command === "--rotate-left") { event.target.style.rotate = "-90deg"; - } else if (event.command == "--rotate-right") { + } else if (event.command === "--rotate-right") { event.target.style.rotate = "90deg"; } }); diff --git a/files/en-us/web/api/htmlbuttonelement/commandforelement/index.md b/files/en-us/web/api/htmlbuttonelement/commandforelement/index.md index 4db975b978bc10d..a8a904c329b3601 100644 --- a/files/en-us/web/api/htmlbuttonelement/commandforelement/index.md +++ b/files/en-us/web/api/htmlbuttonelement/commandforelement/index.md @@ -3,16 +3,14 @@ title: "HTMLButtonElement: commandForElement property" short-title: commandForElement slug: Web/API/HTMLButtonElement/commandForElement page-type: web-api-instance-property -status: - - experimental browser-compat: api.HTMLButtonElement.commandForElement --- -{{APIRef("Invoker Commands API")}}{{SeeCompatTable}} +{{APIRef("Invoker Commands API")}} The **`commandForElement`** property of the {{domxref("HTMLButtonElement")}} interface gets and sets the element to control via a button. -It is the JavaScript equivalent of the [`commandfor`](/en-US/docs/Web/HTML/Element/button#commandfor) HTML attribute. +It is the JavaScript equivalent of the [`commandfor`](/en-US/docs/Web/HTML/Reference/Elements/button#commandfor) HTML attribute. ## Value diff --git a/files/en-us/web/api/htmlbuttonelement/form/index.md b/files/en-us/web/api/htmlbuttonelement/form/index.md index f30b28e0ee8a0a2..deaf13807c1a36f 100644 --- a/files/en-us/web/api/htmlbuttonelement/form/index.md +++ b/files/en-us/web/api/htmlbuttonelement/form/index.md @@ -27,5 +27,5 @@ An {{domxref("HTMLFormElement")}} or `null`. - {{domxref("HTMLButtonElement")}} - {{domxref("HTMLFormElement")}} - {{HTMLElement("button")}} -- HTML [`form`](/en-US/docs/Web/HTML/Element/button#form) attribute +- HTML [`form`](/en-US/docs/Web/HTML/Reference/Elements/button#form) attribute - [HTML forms guide](/en-US/docs/Learn_web_development/Extensions/Forms) diff --git a/files/en-us/web/api/htmlbuttonelement/formaction/index.md b/files/en-us/web/api/htmlbuttonelement/formaction/index.md index 54e396ca31c09fd..cacdfeb62e80dae 100644 --- a/files/en-us/web/api/htmlbuttonelement/formaction/index.md +++ b/files/en-us/web/api/htmlbuttonelement/formaction/index.md @@ -8,7 +8,7 @@ browser-compat: api.HTMLButtonElement.formAction {{APIRef("HTML DOM")}} -The **`formAction`** property of the {{domxref("HTMLButtonElement")}} interface is the URL of the program that is executed on the server when the form that owns this control is submitted. It reflects the value of the `<button>`'s [`formaction`](/en-US/docs/Web/HTML/Element/button#formaction) attribute. +The **`formAction`** property of the {{domxref("HTMLButtonElement")}} interface is the URL of the program that is executed on the server when the form that owns this control is submitted. It reflects the value of the `<button>`'s [`formaction`](/en-US/docs/Web/HTML/Reference/Elements/button#formaction) attribute. The value overrides the {{domxref("HTMLFormElement.action", "action")}} property of the {{domxref("HTMLFormElement")}} interface if the form is submitted via the button. This property can be retrieved or set. diff --git a/files/en-us/web/api/htmlbuttonelement/formenctype/index.md b/files/en-us/web/api/htmlbuttonelement/formenctype/index.md index 82f2f070f194065..5559edd07dfa66d 100644 --- a/files/en-us/web/api/htmlbuttonelement/formenctype/index.md +++ b/files/en-us/web/api/htmlbuttonelement/formenctype/index.md @@ -8,7 +8,7 @@ browser-compat: api.HTMLButtonElement.formEnctype {{APIRef("HTML DOM")}} -The **`formEnctype`** property of the {{domxref("HTMLButtonElement")}} interface is the {{Glossary("MIME_type", "MIME type")}} of the content sent to the server when the form is submitted. It reflects the value of the `<button>`'s [`formenctype`](/en-US/docs/Web/HTML/Element/button#formenctype) attribute. +The **`formEnctype`** property of the {{domxref("HTMLButtonElement")}} interface is the {{Glossary("MIME_type", "MIME type")}} of the content sent to the server when the form is submitted. It reflects the value of the `<button>`'s [`formenctype`](/en-US/docs/Web/HTML/Reference/Elements/button#formenctype) attribute. The value overrides the {{domxref("HTMLFormElement.enctype", "enctype")}} property of the {{domxref("HTMLFormElement")}} interface if the form is submitted via the submit button. This property can be retrieved or set. If not set, the value is the empty string (`""`). diff --git a/files/en-us/web/api/htmlbuttonelement/formmethod/index.md b/files/en-us/web/api/htmlbuttonelement/formmethod/index.md index dec789fd54e343d..cbea116c5b5df0b 100644 --- a/files/en-us/web/api/htmlbuttonelement/formmethod/index.md +++ b/files/en-us/web/api/htmlbuttonelement/formmethod/index.md @@ -8,7 +8,7 @@ browser-compat: api.HTMLButtonElement.formMethod {{APIRef("HTML DOM")}} -The **`formMethod`** property of the {{domxref("HTMLButtonElement")}} interface is the {{Glossary("HTTP")}} method used to submit the {{HtmlElement("form")}} if the {{HTMLElement("button")}} element is the control that submits the form. It reflects the value of the `<button>`'s [`formmethod`](/en-US/docs/Web/HTML/Element/button#formmethod) attribute. +The **`formMethod`** property of the {{domxref("HTMLButtonElement")}} interface is the {{Glossary("HTTP")}} method used to submit the {{HtmlElement("form")}} if the {{HTMLElement("button")}} element is the control that submits the form. It reflects the value of the `<button>`'s [`formmethod`](/en-US/docs/Web/HTML/Reference/Elements/button#formmethod) attribute. The value overrides the {{domxref("HTMLFormElement.method", "method")}} property of the {{domxref("HTMLFormElement")}} interface if the form is submitted via the button. This property can be retrieved or set. If set with an empty or invalid value, the invalid default value is `"get"`. If not set at all, the value is the empty string (`""`). diff --git a/files/en-us/web/api/htmlbuttonelement/formnovalidate/index.md b/files/en-us/web/api/htmlbuttonelement/formnovalidate/index.md index 3e00c85b9cfeddb..d8df9ea4449bdad 100644 --- a/files/en-us/web/api/htmlbuttonelement/formnovalidate/index.md +++ b/files/en-us/web/api/htmlbuttonelement/formnovalidate/index.md @@ -8,7 +8,7 @@ browser-compat: api.HTMLButtonElement.formNoValidate {{APIRef("HTML DOM")}} -The **`formNoValidate`** property of the {{domxref("HTMLButtonElement")}} interface is a boolean value indicating if the {{htmlelement("form")}} will bypass [constraint validation](/en-US/docs/Web/HTML/Constraint_validation) when submitted via the {{htmlelement("button")}}. It reflects the `<button>` element's [`formnovalidate`](/en-US/docs/Web/HTML/Element/button#formnovalidate) attribute. +The **`formNoValidate`** property of the {{domxref("HTMLButtonElement")}} interface is a boolean value indicating if the {{htmlelement("form")}} will bypass [constraint validation](/en-US/docs/Web/HTML/Guides/Constraint_validation) when submitted via the {{htmlelement("button")}}. It reflects the `<button>` element's [`formnovalidate`](/en-US/docs/Web/HTML/Reference/Elements/button#formnovalidate) attribute. Its value overrides the {{domxref("HTMLFormElement.noValidate", "noValidate")}} property of the {{domxref("HTMLFormElement")}} interface if the form is submitted via the button. This property can be retrieved or set. @@ -43,4 +43,4 @@ console.log(buttonElement.formNoValidate); - {{domxref("HTMLFormElement.noValidate")}} - {{domxref("HTMLInputElement.formNoValidate")}} - [Learn: Client-side form validation](/en-US/docs/Learn_web_development/Extensions/Forms/Form_validation) -- [Guide: Constraint validation](/en-US/docs/Web/HTML/Constraint_validation) +- [Guide: Constraint validation](/en-US/docs/Web/HTML/Guides/Constraint_validation) diff --git a/files/en-us/web/api/htmlbuttonelement/formtarget/index.md b/files/en-us/web/api/htmlbuttonelement/formtarget/index.md index f47a94118a8f91a..8b7c67728324a90 100644 --- a/files/en-us/web/api/htmlbuttonelement/formtarget/index.md +++ b/files/en-us/web/api/htmlbuttonelement/formtarget/index.md @@ -8,7 +8,7 @@ browser-compat: api.HTMLButtonElement.formTarget {{APIRef("HTML DOM")}} -The **`formTarget`** property of the {{domxref("HTMLButtonElement")}} interface is the tab, window, or iframe where the response of the submitted {{HtmlElement("form")}} is to be displayed. It reflects the value of the {{HTMLElement("button")}} element's [`formtarget`](/en-US/docs/Web/HTML/Element/button#formtarget) attribute. +The **`formTarget`** property of the {{domxref("HTMLButtonElement")}} interface is the tab, window, or iframe where the response of the submitted {{HtmlElement("form")}} is to be displayed. It reflects the value of the {{HTMLElement("button")}} element's [`formtarget`](/en-US/docs/Web/HTML/Reference/Elements/button#formtarget) attribute. The value overrides the {{domxref("HTMLFormElement.target", "target")}} property of the {{domxref("HTMLFormElement")}} interface if the form is submitted via the button. This property can be retrieved or set. If not set, the value is the empty string (`""`). diff --git a/files/en-us/web/api/htmlbuttonelement/index.md b/files/en-us/web/api/htmlbuttonelement/index.md index 57a814dfe5725f7..4b5ab7beff40679 100644 --- a/files/en-us/web/api/htmlbuttonelement/index.md +++ b/files/en-us/web/api/htmlbuttonelement/index.md @@ -15,29 +15,33 @@ The **`HTMLButtonElement`** interface provides properties and methods (beyond th _Inherits properties from its parent, {{domxref("HTMLElement")}}._ +- {{domxref("HTMLButtonElement.command")}} + - : A string value indicating the action to be performed on an element being controlled by this button. +- {{domxref("HTMLButtonElement.commandForElement")}} + - : A reference to an existing {{domxref("Element")}} that the button controls. - {{domxref("HTMLButtonElement.disabled")}} - : A boolean value indicating whether or not the control is disabled, meaning that it does not accept any clicks. - {{domxref("HTMLButtonElement.form")}} {{ReadOnlyInline}} - : An {{domxref("HTMLFormElement")}} reflecting the form that this button is associated with. If the button is a descendant of a form element, then this attribute is a reference to that form's associated `HTMLFormElement`. If the button is not a descendant of a form element, then the attribute can be a reference to any `HTMLFormElement` element in the same document it is related to, or the `null` value if none matches. - {{domxref("HTMLButtonElement.formAction")}} - - : A string reflecting the URI of a resource that processes information submitted by the button. If specified, this attribute overrides the [`action`](/en-US/docs/Web/HTML/Element/form#action) attribute of the {{HTMLElement("form")}} element that owns this element. + - : A string reflecting the URI of a resource that processes information submitted by the button. If specified, this attribute overrides the [`action`](/en-US/docs/Web/HTML/Reference/Elements/form#action) attribute of the {{HTMLElement("form")}} element that owns this element. - {{domxref("HTMLButtonElement.formEnctype")}} - - : A string reflecting the type of content that is used to submit the form to the server. If specified, this attribute overrides the [`enctype`](/en-US/docs/Web/HTML/Element/form#enctype) attribute of the {{HTMLElement("form")}} element that owns this element. + - : A string reflecting the type of content that is used to submit the form to the server. If specified, this attribute overrides the [`enctype`](/en-US/docs/Web/HTML/Reference/Elements/form#enctype) attribute of the {{HTMLElement("form")}} element that owns this element. - {{domxref("HTMLButtonElement.formMethod")}} - - : A string reflecting the HTTP method that the browser uses to submit the form. If specified, this attribute overrides the [`method`](/en-US/docs/Web/HTML/Element/form#method) attribute of the {{HTMLElement("form")}} element that owns this element. + - : A string reflecting the HTTP method that the browser uses to submit the form. If specified, this attribute overrides the [`method`](/en-US/docs/Web/HTML/Reference/Elements/form#method) attribute of the {{HTMLElement("form")}} element that owns this element. - {{domxref("HTMLButtonElement.formNoValidate")}} - - : A boolean value indicating that the form is not to be validated when it is submitted. If specified, this attribute overrides the [`novalidate`](/en-US/docs/Web/HTML/Element/form#novalidate) attribute of the {{HTMLElement("form")}} element that owns this element. + - : A boolean value indicating that the form is not to be validated when it is submitted. If specified, this attribute overrides the [`novalidate`](/en-US/docs/Web/HTML/Reference/Elements/form#novalidate) attribute of the {{HTMLElement("form")}} element that owns this element. - {{domxref("HTMLButtonElement.formTarget")}} - - : A string reflecting a name or keyword indicating where to display the response received after submitting the form. If specified, this attribute overrides the [`target`](/en-US/docs/Web/HTML/Element/form#target) attribute of the {{HTMLElement("form")}} element that owns this element. + - : A string reflecting a name or keyword indicating where to display the response received after submitting the form. If specified, this attribute overrides the [`target`](/en-US/docs/Web/HTML/Reference/Elements/form#target) attribute of the {{HTMLElement("form")}} element that owns this element. - {{domxref("HTMLButtonElement.labels")}} {{ReadOnlyInline}} - : A {{domxref("NodeList")}} that represents a list of {{HTMLElement("label")}} elements that are labels for this button. - {{domxref("HTMLButtonElement.name")}} - : A string representing the object's name when submitted with a form. If specified, it must not be the empty string. - {{domxref("HTMLButtonElement.popoverTargetAction")}} - - : Gets and sets the action to be performed (`"hide"`, `"show"`, or `"toggle"`) on a popover element being controlled by a control button. It reflects the value of the [`popovertargetaction`](/en-US/docs/Web/HTML/Element/button#popovertargetaction) HTML attribute. + - : Gets and sets the action to be performed (`"hide"`, `"show"`, or `"toggle"`) on a popover element being controlled by a control button. It reflects the value of the [`popovertargetaction`](/en-US/docs/Web/HTML/Reference/Elements/button#popovertargetaction) HTML attribute. - {{domxref("HTMLButtonElement.popoverTargetElement")}} - - : Gets and sets the popover element to control via a button. The JavaScript equivalent of the [`popovertarget`](/en-US/docs/Web/HTML/Element/button#popovertarget) HTML attribute. + - : Gets and sets the popover element to control via a button. The JavaScript equivalent of the [`popovertarget`](/en-US/docs/Web/HTML/Reference/Elements/button#popovertarget) HTML attribute. - {{domxref("HTMLButtonElement.type")}} - : A string indicating the behavior of the button. This is an enumerated attribute with the following possible values: @@ -64,6 +68,8 @@ _Inherits methods from its parent, {{domxref("HTMLElement")}}_. - : Returns `true` if the element's value has no validity problems; otherwise, returns `false`. - {{domxref("HTMLButtonElement.reportValidity()")}} - : Performs the same action as `checkValidity()`, but also reports the result to the user if the `invalid` event was not canceled. +- {{domxref("HTMLButtonElement.setCustomValidity()")}} + - : Sets the custom validity message for the element. Use the empty string to indicate that the element does _not_ have a custom validity error. ## Specifications diff --git a/files/en-us/web/api/htmlbuttonelement/name/index.md b/files/en-us/web/api/htmlbuttonelement/name/index.md index fddda9d6f201a13..76ab892cad2c307 100644 --- a/files/en-us/web/api/htmlbuttonelement/name/index.md +++ b/files/en-us/web/api/htmlbuttonelement/name/index.md @@ -8,7 +8,7 @@ browser-compat: api.HTMLButtonElement.name {{ApiRef("HTML DOM")}} -The **`name`** property of the {{domxref("HTMLButtonElement")}} interface indicates the name of the {{HTMLElement("button")}} element or the empty string if the element has no name. It reflects the element's [`name`](/en-US/docs/Web/HTML/Element/button#name) attribute. +The **`name`** property of the {{domxref("HTMLButtonElement")}} interface indicates the name of the {{HTMLElement("button")}} element or the empty string if the element has no name. It reflects the element's [`name`](/en-US/docs/Web/HTML/Reference/Elements/button#name) attribute. ## Value diff --git a/files/en-us/web/api/htmlbuttonelement/popovertargetaction/index.md b/files/en-us/web/api/htmlbuttonelement/popovertargetaction/index.md index ae8ffe96488e49b..180f259fee4f8ae 100644 --- a/files/en-us/web/api/htmlbuttonelement/popovertargetaction/index.md +++ b/files/en-us/web/api/htmlbuttonelement/popovertargetaction/index.md @@ -10,7 +10,7 @@ browser-compat: api.HTMLButtonElement.popoverTargetAction The **`popoverTargetAction`** property of the {{domxref("HTMLButtonElement")}} interface gets and sets the action to be performed (`"hide"`, `"show"`, or `"toggle"`) on a popover element being controlled by a button. -It reflects the value of the [`popovertargetaction`](/en-US/docs/Web/HTML/Element/button#popovertargetaction) HTML attribute. +It reflects the value of the [`popovertargetaction`](/en-US/docs/Web/HTML/Reference/Elements/button#popovertargetaction) HTML attribute. ## Value @@ -31,7 +31,7 @@ This example shows the basic use of the popover API with a "toggle" value set fo The `popover` attribute is set to [`"auto"`](/en-US/docs/Web/API/Popover_API/Using#auto_state_and_light_dismiss), so the popover can be closed ("light-dismissed") by clicking outside the popover area. First we define an HTML `<button>` element that we will use to show and hide the popover, and a `<div>` that will be the popover. -In this case we don't set the [`popovertargetaction`](/en-US/docs/Web/HTML/Element/button#popovertargetaction) HTML attribute on the `<button>` or the [`popover`](/en-US/docs/Web/HTML/Global_attributes/popover) attribute on the `<div>`, as we will be doing so programmatically. +In this case we don't set the [`popovertargetaction`](/en-US/docs/Web/HTML/Reference/Elements/button#popovertargetaction) HTML attribute on the `<button>` or the [`popover`](/en-US/docs/Web/HTML/Reference/Global_attributes/popover) attribute on the `<div>`, as we will be doing so programmatically. ```html <button id="toggleBtn">Toggle popover</button> @@ -47,7 +47,7 @@ const toggleBtn = document.getElementById("toggleBtn"); // Check for popover API support. function supportsPopover() { - return HTMLElement.prototype.hasOwnProperty("popover"); + return Object.hasOwn(HTMLElement.prototype, "popover"); } ``` @@ -94,7 +94,7 @@ A `manual` popover must be closed explicitly, and not "light dismissed" by selec ```js function supportsPopover() { - return HTMLElement.prototype.hasOwnProperty("popover"); + return Object.hasOwn(HTMLElement.prototype, "popover"); } const popover = document.getElementById("mypopover"); diff --git a/files/en-us/web/api/htmlbuttonelement/popovertargetelement/index.md b/files/en-us/web/api/htmlbuttonelement/popovertargetelement/index.md index 76104c79f605580..47464c20c47d9c4 100644 --- a/files/en-us/web/api/htmlbuttonelement/popovertargetelement/index.md +++ b/files/en-us/web/api/htmlbuttonelement/popovertargetelement/index.md @@ -10,11 +10,11 @@ browser-compat: api.HTMLButtonElement.popoverTargetElement The **`popoverTargetElement`** property of the {{domxref("HTMLButtonElement")}} interface gets and sets the popover element to control via a button. -It is the JavaScript equivalent of the [`popovertarget`](/en-US/docs/Web/HTML/Element/button#popovertarget) HTML attribute. +It is the JavaScript equivalent of the [`popovertarget`](/en-US/docs/Web/HTML/Reference/Elements/button#popovertarget) HTML attribute. Establishing a relationship between a popover and its invoker button using the `popoverTargetElement` property has two additional useful effects: -- The browser creates an implicit [`aria-details`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-details) and [`aria-expanded`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-expanded) relationship between popover and invoker, and places the popover in a logical position in the keyboard focus navigation order when shown. This makes the popover more accessible to keyboard and assistive technology (AT) users (see also [Popover accessibility features](/en-US/docs/Web/API/Popover_API/Using#popover_accessibility_features)). +- The browser creates an implicit [`aria-details`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-details) and [`aria-expanded`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-expanded) relationship between popover and invoker, and places the popover in a logical position in the keyboard focus navigation order when shown. This makes the popover more accessible to keyboard and assistive technology (AT) users (see also [Popover accessibility features](/en-US/docs/Web/API/Popover_API/Using#popover_accessibility_features)). - The browser creates an implicit anchor reference between the two, making it very convenient to position popovers relative to their controls using [CSS anchor positioning](/en-US/docs/Web/CSS/CSS_anchor_positioning). See [Popover anchor positioning](/en-US/docs/Web/API/Popover_API/Using#popover_anchor_positioning) for more details. ## Value @@ -29,7 +29,7 @@ This example shows the basic use of the popover API, setting a `<div>` element a The `popover` attribute is set to [`"manual"`](/en-US/docs/Web/API/Popover_API/Using#using_manual_popover_state), so the popover must be closed using a button, and not "light dismissed" by selecting outside the popover area. First we define an HTML `<button>` element that we will use to show and hide the popover, and a `<div>` that will be the popover. -In this case we don't set the [`popovertargetaction`](/en-US/docs/Web/HTML/Element/button#popovertargetaction) HTML attribute on the `<button>` or the [`popover`](/en-US/docs/Web/HTML/Global_attributes/popover) attribute on the `<div>`, as we will be doing so programmatically. +In this case we don't set the [`popovertargetaction`](/en-US/docs/Web/HTML/Reference/Elements/button#popovertargetaction) HTML attribute on the `<button>` or the [`popover`](/en-US/docs/Web/HTML/Reference/Global_attributes/popover) attribute on the `<div>`, as we will be doing so programmatically. ```html <button id="toggleBtn">Toggle popover</button> @@ -45,7 +45,7 @@ const toggleBtn = document.getElementById("toggleBtn"); // Check for popover API support. function supportsPopover() { - return HTMLElement.prototype.hasOwnProperty("popover"); + return Object.hasOwn(HTMLElement.prototype, "popover"); } ``` diff --git a/files/en-us/web/api/htmlbuttonelement/reportvalidity/index.md b/files/en-us/web/api/htmlbuttonelement/reportvalidity/index.md index 26f46fab758449e..1e3366fdc3fa02d 100644 --- a/files/en-us/web/api/htmlbuttonelement/reportvalidity/index.md +++ b/files/en-us/web/api/htmlbuttonelement/reportvalidity/index.md @@ -87,7 +87,7 @@ exampleButton.addEventListener("invalid", () => { exampleButton.addEventListener("click", (e) => { e.preventDefault(); - if (exampleButton.value == "error") { + if (exampleButton.value === "error") { breakOrFixButton("fixed"); } else { breakOrFixButton("error"); @@ -97,7 +97,7 @@ exampleButton.addEventListener("click", (e) => { const breakOrFixButton = () => { const state = toggleButton(); - if (state == "error") { + if (state === "error") { exampleButton.setCustomValidity("This is a custom error message"); } else { exampleButton.setCustomValidity(""); @@ -105,7 +105,7 @@ const breakOrFixButton = () => { }; const toggleButton = () => { - if (exampleButton.value == "error") { + if (exampleButton.value === "error") { exampleButton.value = "fixed"; exampleButton.innerHTML = "No error"; } else { @@ -136,5 +136,5 @@ The button is by default valid. Activate "THIS BUTTON" to change the value, cont - {{HTMLElement("button")}} - {{HTMLElement("form")}} - [Learn: Client-side form validation](/en-US/docs/Learn_web_development/Extensions/Forms/Form_validation) -- [Guide: Constraint validation](/en-US/docs/Web/HTML/Constraint_validation) +- [Guide: Constraint validation](/en-US/docs/Web/HTML/Guides/Constraint_validation) - CSS {{cssxref(":valid")}} and {{cssxref(":invalid")}} pseudo-classes diff --git a/files/en-us/web/api/htmlbuttonelement/setcustomvalidity/index.md b/files/en-us/web/api/htmlbuttonelement/setcustomvalidity/index.md index 2a1391f45f6a9f2..20c687686794999 100644 --- a/files/en-us/web/api/htmlbuttonelement/setcustomvalidity/index.md +++ b/files/en-us/web/api/htmlbuttonelement/setcustomvalidity/index.md @@ -52,7 +52,7 @@ if (errors) { - {{domxref("HTMLButtonElement.validity")}} - {{domxref("HTMLButtonElement.checkValidity()")}} - {{domxref("HTMLButtonElement.reportValidity()")}} -- [Form validation](/en-US/docs/Web/HTML/Constraint_validation). +- [Form validation](/en-US/docs/Web/HTML/Guides/Constraint_validation). - [Learn: Client-side form validation](/en-US/docs/Learn_web_development/Extensions/Forms/Form_validation) -- [Guide: Constraint validation](/en-US/docs/Web/HTML/Constraint_validation) +- [Guide: Constraint validation](/en-US/docs/Web/HTML/Guides/Constraint_validation) - CSS {{cssxref(":valid")}} and {{cssxref(":invalid")}} pseudo-classes diff --git a/files/en-us/web/api/htmlbuttonelement/type/index.md b/files/en-us/web/api/htmlbuttonelement/type/index.md index 69f7c0a3e26d214..2c0ea054a2f29db 100644 --- a/files/en-us/web/api/htmlbuttonelement/type/index.md +++ b/files/en-us/web/api/htmlbuttonelement/type/index.md @@ -10,13 +10,13 @@ browser-compat: api.HTMLButtonElement.type The **`type`** property of the {{domxref("HTMLButtonElement")}} interface is a string that indicates the behavior type of the {{HTMLElement("button")}} element. -It reflects the [`type`](/en-US/docs/Web/HTML/Element/button#type) attribute of the {{HTMLElement("button")}} element. +It reflects the [`type`](/en-US/docs/Web/HTML/Reference/Elements/button#type) attribute of the {{HTMLElement("button")}} element. ## Value A string representing the type. -Its possible values are listed in the attribute's [button types](/en-US/docs/Web/API/HTMLButtonElement#htmlbuttonelement.type) section. +Its possible values are listed in the attribute's [button types](/en-US/docs/Web/HTML/Reference/Elements/button#type) section. ## Example diff --git a/files/en-us/web/api/htmlbuttonelement/validationmessage/index.md b/files/en-us/web/api/htmlbuttonelement/validationmessage/index.md index df5d1e3886164bb..5683fe5b275c3f4 100644 --- a/files/en-us/web/api/htmlbuttonelement/validationmessage/index.md +++ b/files/en-us/web/api/htmlbuttonelement/validationmessage/index.md @@ -8,7 +8,7 @@ browser-compat: api.HTMLButtonElement.validationMessage {{APIRef("HTML DOM")}} -The **`validationMessage`** read-only property of the {{domxref("HTMLButtonElement")}} interface returns a string representing a localized message that describes the validation constraints that the {{htmlelement("button")}} control does not satisfy (if any). This is the empty string if the control is not a candidate for constraint validation (the `<button>`'s [`type`](/en-US/docs/Web/HTML/Element/button#type) is `button` or `reset`), or it satisfies its constraints. +The **`validationMessage`** read-only property of the {{domxref("HTMLButtonElement")}} interface returns a string representing a localized message that describes the validation constraints that the {{htmlelement("button")}} control does not satisfy (if any). This is the empty string if the control is not a candidate for constraint validation (the `<button>`'s [`type`](/en-US/docs/Web/HTML/Reference/Elements/button#type) is `button` or `reset`), or it satisfies its constraints. If the `<button>` is a candidate for constraint validation (the `type` is set or defaults to `submit` and {{domxref("HTMLButtonElement.willValidate")}} is `true`) and the constraints are not met (there is a non-null {{domxref("ValidityState.customError")}}), the value is the error message that would be shown to the user during element validation. @@ -34,5 +34,5 @@ A string. - {{domxref("HTMLButtonElement.reportValidity()")}} - {{domxref("HTMLButtonElement.setCustomValidity()")}} - [Learn: Client-side form validation](/en-US/docs/Learn_web_development/Extensions/Forms/Form_validation) -- [Guide: Constraint validation](/en-US/docs/Web/HTML/Constraint_validation) +- [Guide: Constraint validation](/en-US/docs/Web/HTML/Guides/Constraint_validation) - CSS {{cssxref(":valid")}} and {{cssxref(":invalid")}} pseudo-classes diff --git a/files/en-us/web/api/htmlbuttonelement/validity/index.md b/files/en-us/web/api/htmlbuttonelement/validity/index.md index 5fa3cee8eceb5ce..042a67f98794880 100644 --- a/files/en-us/web/api/htmlbuttonelement/validity/index.md +++ b/files/en-us/web/api/htmlbuttonelement/validity/index.md @@ -16,7 +16,7 @@ A {{domxref("ValidityState")}} object. ## Examples -The following example demonstrates that a `<button>` is in an invalid state when a {{domxref("ValidityState/customError", "customError")}} is set; in this state, the `validityState`'s `validity` property is `false`, while {{domxref("HTMLButtonElement/checkValidity", "checkValidity()")}} returns `true` if the button's {{domxref("HTMLButtonElement/type", "type")}} is not `"submit"`, because such buttons are not candidates for [constraint validation](/en-US/docs/Web/HTML/Constraint_validation). +The following example demonstrates that a `<button>` is in an invalid state when a {{domxref("ValidityState/customError", "customError")}} is set; in this state, the `validityState`'s `validity` property is `false`, while {{domxref("HTMLButtonElement/checkValidity", "checkValidity()")}} returns `true` if the button's {{domxref("HTMLButtonElement/type", "type")}} is not `"submit"`, because such buttons are not candidates for [constraint validation](/en-US/docs/Web/HTML/Guides/Constraint_validation). ```js const button = document.getElementById("myButton"); @@ -41,4 +41,4 @@ console.log(button.checkValidity()); // false if the button is of the "submit" t - {{HTMLElement("button")}} - {{HTMLElement("form")}} - [Learn: Client-side form validation](/en-US/docs/Learn_web_development/Extensions/Forms/Form_validation) -- [Guide: Constraint validation](/en-US/docs/Web/HTML/Constraint_validation) +- [Guide: Constraint validation](/en-US/docs/Web/HTML/Guides/Constraint_validation) diff --git a/files/en-us/web/api/htmlbuttonelement/value/index.md b/files/en-us/web/api/htmlbuttonelement/value/index.md index 51ffcb910c5b67f..7a5344afa2ceddc 100644 --- a/files/en-us/web/api/htmlbuttonelement/value/index.md +++ b/files/en-us/web/api/htmlbuttonelement/value/index.md @@ -8,7 +8,7 @@ browser-compat: api.HTMLButtonElement.value {{ APIRef("HTML DOM") }} -The **`value`** property of the {{DOMxRef("HTMLButtonElement")}} interface represents the value of the {{htmlelement("button")}} element as a string, or the empty string if no value is set. It reflects the element's [`value`](/en-US/docs/Web/HTML/Element/button#value) attribute. +The **`value`** property of the {{DOMxRef("HTMLButtonElement")}} interface represents the value of the {{htmlelement("button")}} element as a string, or the empty string if no value is set. It reflects the element's [`value`](/en-US/docs/Web/HTML/Reference/Elements/button#value) attribute. ## Value diff --git a/files/en-us/web/api/htmlbuttonelement/willvalidate/index.md b/files/en-us/web/api/htmlbuttonelement/willvalidate/index.md index 21460c02978ee64..91ccc09c2f8ddbd 100644 --- a/files/en-us/web/api/htmlbuttonelement/willvalidate/index.md +++ b/files/en-us/web/api/htmlbuttonelement/willvalidate/index.md @@ -8,7 +8,7 @@ browser-compat: api.HTMLButtonElement.willValidate {{APIRef("HTML DOM")}} -The **`willValidate`** read-only property of the {{domxref("HTMLButtonElement")}} interface indicates whether the {{htmlelement("button")}} element is a candidate for [constraint validation](/en-US/docs/Web/HTML/Constraint_validation). It is `false` if any conditions bar it from constraint validation, including: +The **`willValidate`** read-only property of the {{domxref("HTMLButtonElement")}} interface indicates whether the {{htmlelement("button")}} element is a candidate for [constraint validation](/en-US/docs/Web/HTML/Guides/Constraint_validation). It is `false` if any conditions bar it from constraint validation, including: - Its {{domxref("HTMLButtonElement.type", "type")}} is `reset` or `button`; - It has a {{HTMLElement("datalist")}} ancestor; @@ -32,4 +32,4 @@ A boolean value. - {{HTMLElement("button")}} - {{HTMLElement("form")}} - [Learn: Client-side form validation](/en-US/docs/Learn_web_development/Extensions/Forms/Form_validation) -- [Guide: Constraint validation](/en-US/docs/Web/HTML/Constraint_validation) +- [Guide: Constraint validation](/en-US/docs/Web/HTML/Guides/Constraint_validation) diff --git a/files/en-us/web/api/htmlcanvaselement/contextlost_event/index.md b/files/en-us/web/api/htmlcanvaselement/contextlost_event/index.md index 3383e875fffc8cb..f8c905c36cc30f1 100644 --- a/files/en-us/web/api/htmlcanvaselement/contextlost_event/index.md +++ b/files/en-us/web/api/htmlcanvaselement/contextlost_event/index.md @@ -18,10 +18,10 @@ User code can prevent the context from being restored by calling [`Event.prevent Use the event name in methods like {{domxref("EventTarget.addEventListener", "addEventListener()")}}, or set an event handler property. -```js -addEventListener("contextlost", (event) => {}); +```js-nolint +addEventListener("contextlost", (event) => { }) -oncontextlost = (event) => {}; +oncontextlost = (event) => { } ``` ## Event type diff --git a/files/en-us/web/api/htmlcanvaselement/contextrestored_event/index.md b/files/en-us/web/api/htmlcanvaselement/contextrestored_event/index.md index 1b795ed0a0ab3fb..44d57e1011c54ed 100644 --- a/files/en-us/web/api/htmlcanvaselement/contextrestored_event/index.md +++ b/files/en-us/web/api/htmlcanvaselement/contextrestored_event/index.md @@ -16,10 +16,10 @@ You can redraw, re-retrieve resources, and reinitialize the state of your contex Use the event name in methods like {{domxref("EventTarget.addEventListener", "addEventListener()")}}, or set an event handler property. -```js -addEventListener("contextrestored", (event) => {}); +```js-nolint +addEventListener("contextrestored", (event) => { }) -oncontextrestored = (event) => {}; +oncontextrestored = (event) => { } ``` ## Event type @@ -53,6 +53,6 @@ canvas.addEventListener( ## See also -- [`HTMLCanvasElement: contextlost` event](/en-US/docs/Web/API/HTMLCanvasElement/contextlost_event) +- [`HTMLCanvasElement`: `contextlost` event](/en-US/docs/Web/API/HTMLCanvasElement/contextlost_event) - [`CanvasRenderingContext2D.isContextLost()`](/en-US/docs/Web/API/CanvasRenderingContext2D/isContextLost) -- [OffscreenCanvas: contextlost` event](/en-US/docs/Web/API/OffscreenCanvas/contextlost_event) +- [`OffscreenCanvas`: `contextlost` event](/en-US/docs/Web/API/OffscreenCanvas/contextlost_event) diff --git a/files/en-us/web/api/htmlcanvaselement/height/index.md b/files/en-us/web/api/htmlcanvaselement/height/index.md index 3891f3b42186bb4..45f7d7d31a49899 100644 --- a/files/en-us/web/api/htmlcanvaselement/height/index.md +++ b/files/en-us/web/api/htmlcanvaselement/height/index.md @@ -9,12 +9,12 @@ browser-compat: api.HTMLCanvasElement.height {{APIRef("Canvas API")}} The **`HTMLCanvasElement.height`** property is a -positive `integer` reflecting the [`height`](/en-US/docs/Web/HTML/Element/canvas#height) HTML +positive `integer` reflecting the [`height`](/en-US/docs/Web/HTML/Reference/Elements/canvas#height) HTML attribute of the {{HTMLElement("canvas")}} element interpreted in CSS pixels. When the attribute is not specified, or if it is set to an invalid value, like a negative, the default value of `150` is used. -When the `height` property is set the drawing buffer is always reset to blank — this is true for all context types, and even when the height is set to the same value. If you need to restore the previous content, you can save it via {{domxref("CanvasRenderingContext2D.getImageData()")}} and restore it via {{domxref("CanvasRenderingContext2D.putImageData()")}}. +Setting the `height` property resets the entire rendering context to its default state. This includes clearing the canvas (backing buffer), resetting the current path, and resetting _all_ properties like `fillStyle` and `globalCompositeOperation`. This reset occurs for all context types, and occurs even when setting `height` to its current value. To restore the previous content after changing the height, use {{domxref("CanvasRenderingContext2D.getImageData()")}} and {{domxref("CanvasRenderingContext2D.putImageData()")}}. Context properties must be separately tracked and restored. This is one of the two properties, the other being {{domxref("HTMLCanvasElement.width")}}, that controls the size of the canvas. diff --git a/files/en-us/web/api/htmlcanvaselement/index.md b/files/en-us/web/api/htmlcanvaselement/index.md index 3960193eb2278c9..e686b62c158bcd0 100644 --- a/files/en-us/web/api/htmlcanvaselement/index.md +++ b/files/en-us/web/api/htmlcanvaselement/index.md @@ -16,11 +16,11 @@ The **`HTMLCanvasElement`** interface provides properties and methods for manipu _Inherits properties from its parent, {{domxref("HTMLElement")}}._ - {{domxref("HTMLCanvasElement.height")}} - - : The [`height`](/en-US/docs/Web/HTML/Element/canvas#height) HTML attribute of the {{HTMLElement("canvas")}} element is a non-negative `integer` reflecting the number of logical pixels (or RGBA values) going down one column of the canvas. When the attribute is not specified, or if it is set to an invalid value, like a negative, the default value of `150` is used. If no \[separate] CSS height is assigned to the {{HTMLElement("canvas")}}, then this value will also be used as the height of the canvas in the length-unit CSS Pixel. + - : The [`height`](/en-US/docs/Web/HTML/Reference/Elements/canvas#height) HTML attribute of the {{HTMLElement("canvas")}} element is a non-negative `integer` reflecting the number of logical pixels (or RGBA values) going down one column of the canvas. When the attribute is not specified, or if it is set to an invalid value, like a negative, the default value of `150` is used. If no \[separate] CSS height is assigned to the {{HTMLElement("canvas")}}, then this value will also be used as the height of the canvas in the length-unit CSS Pixel. - {{domxref("HTMLCanvasElement.width")}} - - : The [`width`](/en-US/docs/Web/HTML/Element/canvas#width) HTML attribute of the {{HTMLElement("canvas")}} element is a non-negative `integer` reflecting the number of logical pixels (or RGBA values) going across one row of the canvas. When the attribute is not specified, or if it is set to an invalid value, like a negative, the default value of `300` is used. If no \[separate] CSS width is assigned to the {{HTMLElement("canvas")}}, then this value will also be used as the width of the canvas in the length-unit CSS Pixel. + - : The [`width`](/en-US/docs/Web/HTML/Reference/Elements/canvas#width) HTML attribute of the {{HTMLElement("canvas")}} element is a non-negative `integer` reflecting the number of logical pixels (or RGBA values) going across one row of the canvas. When the attribute is not specified, or if it is set to an invalid value, like a negative, the default value of `300` is used. If no \[separate] CSS width is assigned to the {{HTMLElement("canvas")}}, then this value will also be used as the width of the canvas in the length-unit CSS Pixel. - {{domxref("HTMLCanvasElement.mozOpaque")}} {{non-standard_inline}} {{deprecated_inline}} - - : A boolean value reflecting the [`moz-opaque`](/en-US/docs/Web/HTML/Element/canvas#moz-opaque) HTML attribute of the {{HTMLElement("canvas")}} element. It lets the canvas know whether or not translucency will be a factor. If the canvas knows there's no translucency, painting performance can be optimized. This is only supported in Mozilla-based browsers; use the standardized {{domxref("HTMLCanvasElement.getContext()", "canvas.getContext('2d', { alpha: false })")}} instead. + - : A boolean value reflecting the [`moz-opaque`](/en-US/docs/Web/HTML/Reference/Elements/canvas#moz-opaque) HTML attribute of the {{HTMLElement("canvas")}} element. It lets the canvas know whether or not translucency will be a factor. If the canvas knows there's no translucency, painting performance can be optimized. This is only supported in Mozilla-based browsers; use the standardized {{domxref("HTMLCanvasElement.getContext()", "canvas.getContext('2d', { alpha: false })")}} instead. - {{domxref("HTMLCanvasElement.mozPrintCallback")}} {{non-standard_inline}} - : A `function` that is Initially null. Web content can set this to a JavaScript function that will be called when the canvas is to be redrawn while the page is being printed. When called, the callback is passed a "printState" object that implements the [MozCanvasPrintState](https://searchfox.org/mozilla-central/search?q=interface%20MozCanvasPrintState&path=HTMLCanvasElement.webidl) interface. The callback can get the context to draw to from the printState object and must then call done() on it when finished. The purpose of `mozPrintCallback` is to obtain a higher resolution rendering of the canvas at the resolution of the printer being used. [See this blog post.](https://blog.mozilla.org/labs/2012/09/a-new-way-to-control-printing-output/) diff --git a/files/en-us/web/api/htmlcanvaselement/mozopaque/index.md b/files/en-us/web/api/htmlcanvaselement/mozopaque/index.md index 181cc0bc3701071..d8e9e65ce4dcd77 100644 --- a/files/en-us/web/api/htmlcanvaselement/mozopaque/index.md +++ b/files/en-us/web/api/htmlcanvaselement/mozopaque/index.md @@ -12,7 +12,7 @@ browser-compat: api.HTMLCanvasElement.mozOpaque {{APIRef("Canvas API")}}{{deprecated_header}}{{non-standard_header}} The non-standard **`HTMLCanvasElement.mozOpaque`** property is -a boolean value reflecting the [`moz-opaque`](/en-US/docs/Web/HTML/Element/canvas#moz-opaque) HTML +a boolean value reflecting the [`moz-opaque`](/en-US/docs/Web/HTML/Reference/Elements/canvas#moz-opaque) HTML attribute of the {{HTMLElement("canvas")}} element. It lets the canvas know whether or not translucency will be a factor. If the canvas knows there's no translucency, painting performance can be optimized. @@ -57,5 +57,5 @@ Not part of any standard. ## See also - {{domxref("HTMLCanvasElement")}}: Interface used to define the `HTMLCanvasElement.mozOpaque` property -- [`moz-opaque`](/en-US/docs/Web/HTML/Element/canvas#moz-opaque): HTML attribute of the {{HTMLElement("canvas")}} element +- [`moz-opaque`](/en-US/docs/Web/HTML/Reference/Elements/canvas#moz-opaque): HTML attribute of the {{HTMLElement("canvas")}} element - [Optimizing your JavaScript game for Firefox OS](https://hacks.mozilla.org/2013/05/optimizing-your-javascript-game-for-firefox-os/) diff --git a/files/en-us/web/api/htmlcanvaselement/toblob/index.md b/files/en-us/web/api/htmlcanvaselement/toblob/index.md index ff0732c92b6c1fe..75dc1443fb5474d 100644 --- a/files/en-us/web/api/htmlcanvaselement/toblob/index.md +++ b/files/en-us/web/api/htmlcanvaselement/toblob/index.md @@ -60,11 +60,6 @@ canvas.toBlob((blob) => { const newImg = document.createElement("img"); const url = URL.createObjectURL(blob); - newImg.onload = () => { - // no longer need to read the blob so it's revoked - URL.revokeObjectURL(url); - }; - newImg.src = url; document.body.appendChild(newImg); }); @@ -83,6 +78,8 @@ canvas.toBlob( ); // JPEG at 95% quality ``` +Note that we don't immediately revoke the object URL after the image has loaded, because doing so would make the image unusable for user interactions (such as right-clicking to save the image or opening it in a new tab). For long-lived applications, you should revoke object URLs when they're no longer needed (such as when the image is removed from the DOM) to free up memory by calling the {{DOMxref("URL.revokeObjectURL_static", "URL.revokeObjectURL()")}} method and passing in the object URL string. + ### Convert a canvas to an ico (Mozilla only) This uses `-moz-parse` to convert the canvas to ico, and hence only works on Firefox. diff --git a/files/en-us/web/api/htmlcanvaselement/todataurl/index.md b/files/en-us/web/api/htmlcanvaselement/todataurl/index.md index 9f2ea2e4d033127..ffc0bf90b1ec686 100644 --- a/files/en-us/web/api/htmlcanvaselement/todataurl/index.md +++ b/files/en-us/web/api/htmlcanvaselement/todataurl/index.md @@ -41,7 +41,7 @@ toDataURL(type, quality) A string containing the requested [data URL](/en-US/docs/Web/URI/Reference/Schemes/data). -If the height or width of the canvas is `0` or larger than the [maximum canvas size](/en-US/docs/Web/HTML/Element/canvas#maximum_canvas_size), the string `"data:,"` is returned. +If the height or width of the canvas is `0` or larger than the [maximum canvas size](/en-US/docs/Web/HTML/Reference/Elements/canvas#maximum_canvas_size), the string `"data:,"` is returned. ### Exceptions diff --git a/files/en-us/web/api/htmlcanvaselement/transfercontroltooffscreen/index.md b/files/en-us/web/api/htmlcanvaselement/transfercontroltooffscreen/index.md index 623c0125c0c8b94..b1dc93d11a01b40 100644 --- a/files/en-us/web/api/htmlcanvaselement/transfercontroltooffscreen/index.md +++ b/files/en-us/web/api/htmlcanvaselement/transfercontroltooffscreen/index.md @@ -29,7 +29,7 @@ An {{domxref("OffscreenCanvas")}} object. - `InvalidStateError` {{domxref("DOMException")}} - : Throws if: - the canvas has been set a context mode by calling {{domxref("HTMLCanvasElement.getContext()")}} - - the canvas has transferred its control to offscreen by calling {{domxref("HTMLCanvasElement.transferControlToOffscreen()")}}. + - the canvas has already transferred its control to offscreen. ## Examples diff --git a/files/en-us/web/api/htmlcanvaselement/webglcontextcreationerror_event/index.md b/files/en-us/web/api/htmlcanvaselement/webglcontextcreationerror_event/index.md index adeea0c08569919..110d77d42c3241f 100644 --- a/files/en-us/web/api/htmlcanvaselement/webglcontextcreationerror_event/index.md +++ b/files/en-us/web/api/htmlcanvaselement/webglcontextcreationerror_event/index.md @@ -18,10 +18,10 @@ This event does not bubble. Use the event name in methods like {{domxref("EventTarget.addEventListener", "addEventListener()")}}, or set an event handler property. -```js -addEventListener("webglcontextcreationerror", (event) => {}); +```js-nolint +addEventListener("webglcontextcreationerror", (event) => { }) -onwebglcontextcreationerror = (event) => {}; +onwebglcontextcreationerror = (event) => { } ``` ## Event type diff --git a/files/en-us/web/api/htmlcanvaselement/webglcontextlost_event/index.md b/files/en-us/web/api/htmlcanvaselement/webglcontextlost_event/index.md index b7f691d41b874db..572803243f2fa77 100644 --- a/files/en-us/web/api/htmlcanvaselement/webglcontextlost_event/index.md +++ b/files/en-us/web/api/htmlcanvaselement/webglcontextlost_event/index.md @@ -16,10 +16,10 @@ This event does not bubble. Use the event name in methods like {{domxref("EventTarget.addEventListener", "addEventListener()")}}, or set an event handler property. -```js -addEventListener("webglcontextlost", (event) => {}); +```js-nolint +addEventListener("webglcontextlost", (event) => { }) -onwebglcontextlost = (event) => {}; +onwebglcontextlost = (event) => { } ``` ## Event type diff --git a/files/en-us/web/api/htmlcanvaselement/webglcontextrestored_event/index.md b/files/en-us/web/api/htmlcanvaselement/webglcontextrestored_event/index.md index 6d5eb1d5e22420a..14c76b53a64a36e 100644 --- a/files/en-us/web/api/htmlcanvaselement/webglcontextrestored_event/index.md +++ b/files/en-us/web/api/htmlcanvaselement/webglcontextrestored_event/index.md @@ -18,10 +18,10 @@ This event does not bubble. Use the event name in methods like {{domxref("EventTarget.addEventListener", "addEventListener()")}}, or set an event handler property. -```js -addEventListener("webglcontextrestored", (event) => {}); +```js-nolint +addEventListener("webglcontextrestored", (event) => { }) -onwebglcontextrestored = (event) => {}; +onwebglcontextrestored = (event) => { } ``` ## Event type diff --git a/files/en-us/web/api/htmlcanvaselement/width/index.md b/files/en-us/web/api/htmlcanvaselement/width/index.md index 0b6a2ceb62cb9d1..0ced8e694995a50 100644 --- a/files/en-us/web/api/htmlcanvaselement/width/index.md +++ b/files/en-us/web/api/htmlcanvaselement/width/index.md @@ -9,12 +9,12 @@ browser-compat: api.HTMLCanvasElement.width {{APIRef("Canvas API")}} The **`HTMLCanvasElement.width`** property is a -positive `integer` reflecting the [`width`](/en-US/docs/Web/HTML/Element/canvas#width) HTML +positive `integer` reflecting the [`width`](/en-US/docs/Web/HTML/Reference/Elements/canvas#width) HTML attribute of the {{HTMLElement("canvas")}} element interpreted in CSS pixels. When the attribute is not specified, or if it is set to an invalid value, like a negative, the default value of `300` is used. -When the `width` property is set the drawing buffer is always reset to blank — this is true for all context types, and even when the width is set to the same value. If you need to restore the previous content, you can save it via {{domxref("CanvasRenderingContext2D.getImageData()")}} and restore it via {{domxref("CanvasRenderingContext2D.putImageData()")}}. +Setting the `width` property resets the entire rendering context to its default state. This includes clearing the canvas (backing buffer), resetting the current path, and resetting _all_ properties like `fillStyle` and `globalCompositeOperation`. This reset occurs for all context types, and occurs even when setting `width` to its current value. To restore the previous content after changing the width, use {{domxref("CanvasRenderingContext2D.getImageData()")}} and {{domxref("CanvasRenderingContext2D.putImageData()")}}. Context properties must be separately tracked and restored. This is one of the two properties, the other being {{domxref("HTMLCanvasElement.height")}}, that controls the size of the canvas. diff --git a/files/en-us/web/api/htmldataelement/index.md b/files/en-us/web/api/htmldataelement/index.md index 3dd47c54863365e..cb0b23041ec0fee 100644 --- a/files/en-us/web/api/htmldataelement/index.md +++ b/files/en-us/web/api/htmldataelement/index.md @@ -16,7 +16,7 @@ The **`HTMLDataElement`** interface provides special properties (beyond the regu _Inherits properties from its parent, {{domxref("HTMLElement")}}._ - {{domxref("HTMLDataElement.value")}} - - : A string reflecting the [`value`](/en-US/docs/Web/HTML/Element/data#value) HTML attribute, containing a machine-readable form of the element's value. + - : A string reflecting the [`value`](/en-US/docs/Web/HTML/Reference/Elements/data#value) HTML attribute, containing a machine-readable form of the element's value. ## Instance methods diff --git a/files/en-us/web/api/htmldataelement/value/index.md b/files/en-us/web/api/htmldataelement/value/index.md index 1dfb2033f7cfe06..cb3906eb0dfd760 100644 --- a/files/en-us/web/api/htmldataelement/value/index.md +++ b/files/en-us/web/api/htmldataelement/value/index.md @@ -9,7 +9,7 @@ browser-compat: api.HTMLDataElement.value {{APIRef("HTML DOM")}} The **`value`** property of the {{domxref("HTMLDataElement")}} -interface returns a string reflecting the [`value`](/en-US/docs/Web/HTML/Element/data#value) HTML attribute. +interface returns a string reflecting the [`value`](/en-US/docs/Web/HTML/Reference/Elements/data#value) HTML attribute. ## Value diff --git a/files/en-us/web/api/htmldetailselement/index.md b/files/en-us/web/api/htmldetailselement/index.md index 82c9a088d3dd6cf..b46a22fc7b192cd 100644 --- a/files/en-us/web/api/htmldetailselement/index.md +++ b/files/en-us/web/api/htmldetailselement/index.md @@ -18,9 +18,9 @@ The **`HTMLDetailsElement`** interface provides special properties (beyond the r _Inherits properties from its parent, {{domxref("HTMLElement")}}._ - {{domxref("HTMLDetailsElement.name")}} - - : A string reflecting the [`name`](/en-US/docs/Web/HTML/Element/details#name) HTML attribute, which allows you to create a group of mutually-exclusive {{htmlelement("details")}} elements. Opening one of the named `<details>` elements of this group causes other elements of the group to close. + - : A string reflecting the [`name`](/en-US/docs/Web/HTML/Reference/Elements/details#name) HTML attribute, which allows you to create a group of mutually-exclusive {{htmlelement("details")}} elements. Opening one of the named `<details>` elements of this group causes other elements of the group to close. - {{domxref("HTMLDetailsElement.open")}} - - : A boolean value reflecting the [`open`](/en-US/docs/Web/HTML/Element/details#open) HTML attribute, indicating whether or not the element's contents (not counting the {{HTMLElement("summary")}}) is to be shown to the user. + - : A boolean value reflecting the [`open`](/en-US/docs/Web/HTML/Reference/Elements/details#open) HTML attribute, indicating whether or not the element's contents (not counting the {{HTMLElement("summary")}}) is to be shown to the user. ## Instance methods diff --git a/files/en-us/web/api/htmldetailselement/name/index.md b/files/en-us/web/api/htmldetailselement/name/index.md index 7b124238aff07ae..ff9ff9e4c6d6075 100644 --- a/files/en-us/web/api/htmldetailselement/name/index.md +++ b/files/en-us/web/api/htmldetailselement/name/index.md @@ -8,7 +8,7 @@ browser-compat: api.HTMLDetailsElement.name {{ APIRef("HTML DOM") }} -The **`name`** property of the {{domxref("HTMLDetailsElement")}} interface reflects the [`name`](/en-US/docs/Web/HTML/Element/details#name) attribute of {{htmlelement("details")}} elements. It enables multiple `<details>` elements to be connected together, where only one for the `<details>` elements can be open at once. This allows developers to easily create UI features such as accordions without scripting. +The **`name`** property of the {{domxref("HTMLDetailsElement")}} interface reflects the [`name`](/en-US/docs/Web/HTML/Reference/Elements/details#name) attribute of {{htmlelement("details")}} elements. It enables multiple `<details>` elements to be connected together, where only one for the `<details>` elements can be open at once. This allows developers to easily create UI features such as accordions without scripting. The name attribute specifies a group name — give multiple `<details>` elements the same name value to group them. Only one of the grouped `<details>` elements can be open at a time — opening one will cause another to close. If multiple grouped `<details>` elements are given the `open` attribute, only the first one in the source order will be rendered open. diff --git a/files/en-us/web/api/htmldetailselement/open/index.md b/files/en-us/web/api/htmldetailselement/open/index.md index 260294293f7a226..2cd1624df87c3ab 100644 --- a/files/en-us/web/api/htmldetailselement/open/index.md +++ b/files/en-us/web/api/htmldetailselement/open/index.md @@ -10,13 +10,13 @@ browser-compat: api.HTMLDetailsElement.open The **`open`** property of the {{domxref("HTMLDetailsElement")}} interface is a boolean value reflecting the -[`open`](/en-US/docs/Web/HTML/Element/details#open) HTML attribute, indicating whether the {{htmlelement("details")}}'s contents (not counting the {{htmlelement("summary")}}) is to be shown to the user. +[`open`](/en-US/docs/Web/HTML/Reference/Elements/details#open) HTML attribute, indicating whether the {{htmlelement("details")}}'s contents (not counting the {{htmlelement("summary")}}) is to be shown to the user. ## Value A boolean value. -The boolean value represents the state of the [`open`](/en-US/docs/Web/HTML/Element/details#open) HTML attribute. The value of `true` means it is set with both the summary and the additional information shown to the user. The `false` value means it not set, with only the summary shown. +The boolean value represents the state of the [`open`](/en-US/docs/Web/HTML/Reference/Elements/details#open) HTML attribute. The value of `true` means it is set with both the summary and the additional information shown to the user. The `false` value means it not set, with only the summary shown. ## Specifications diff --git a/files/en-us/web/api/htmldialogelement/cancel_event/index.md b/files/en-us/web/api/htmldialogelement/cancel_event/index.md index 8730fae02203af4..9e1258446192a9f 100644 --- a/files/en-us/web/api/htmldialogelement/cancel_event/index.md +++ b/files/en-us/web/api/htmldialogelement/cancel_event/index.md @@ -18,10 +18,10 @@ When a `<dialog>` is dismissed with the <kbd>Esc</kbd> key, both the `cancel` an Use the event name in methods like {{domxref("EventTarget.addEventListener", "addEventListener()")}}, or set an event handler property. -```js -addEventListener("cancel", (event) => {}); +```js-nolint +addEventListener("cancel", (event) => { }) -oncancel = (event) => {}; +oncancel = (event) => { } ``` ## Event type diff --git a/files/en-us/web/api/htmldialogelement/close/index.md b/files/en-us/web/api/htmldialogelement/close/index.md index cdaa4973d08b72f..d206f3a17cb7c35 100644 --- a/files/en-us/web/api/htmldialogelement/close/index.md +++ b/files/en-us/web/api/htmldialogelement/close/index.md @@ -90,7 +90,7 @@ From there you can click the _X_ button to close the dialog (via the `HTMLDialog ``` If the "X" button was of `type="submit"`, the dialog would have closed without requiring JavaScript. -A form submission closes the `<dialog>` it is nested within if the [form's method is `dialog`](/en-US/docs/Web/HTML/Element/form#method), so no "close" button is required. +A form submission closes the `<dialog>` it is nested within if the [form's method is `dialog`](/en-US/docs/Web/HTML/Reference/Elements/form#method), so no "close" button is required. ### Result diff --git a/files/en-us/web/api/htmldialogelement/close_event/index.md b/files/en-us/web/api/htmldialogelement/close_event/index.md index 2964f3678025b42..26e80388acdcc1a 100644 --- a/files/en-us/web/api/htmldialogelement/close_event/index.md +++ b/files/en-us/web/api/htmldialogelement/close_event/index.md @@ -16,10 +16,10 @@ This event is not cancelable and does not bubble. Use the event name in methods like {{domxref("EventTarget.addEventListener", "addEventListener()")}}, or set an event handler property. -```js -addEventListener("close", (event) => {}); +```js-nolint +addEventListener("close", (event) => { }) -onclose = (event) => {}; +onclose = (event) => { } ``` ## Event type @@ -89,5 +89,5 @@ closeButton.addEventListener("click", () => { ## See also -- HTML [`<dialog>`](/en-US/docs/Web/HTML/Element/dialog) element +- HTML [`<dialog>`](/en-US/docs/Web/HTML/Reference/Elements/dialog) element - The [`Event`](/en-US/docs/Web/API/Event) interface diff --git a/files/en-us/web/api/htmldialogelement/closedby/index.md b/files/en-us/web/api/htmldialogelement/closedby/index.md new file mode 100644 index 000000000000000..00acb5d617c8f59 --- /dev/null +++ b/files/en-us/web/api/htmldialogelement/closedby/index.md @@ -0,0 +1,58 @@ +--- +title: "HTMLDialogElement: closedBy property" +short-title: closedBy +slug: Web/API/HTMLDialogElement/closedBy +page-type: web-api-instance-property +status: + - experimental +browser-compat: api.HTMLDialogElement.closedBy +--- + +{{ APIRef("HTML DOM") }}{{SeeCompatTable}} + +The **`closedBy`** property of the +{{domxref("HTMLDialogElement")}} interface indicates the types of user actions that can be used to close the associated {{htmlelement("dialog")}} element. It sets or returns the dialog's [`closedby`](/en-US/docs/Web/HTML/Reference/Elements/dialog#closedby) attribute value. + +## Value + +A string; possible values are: + +- `any` + - : The dialog can be dismissed with a light dismiss user action, a platform-specific user action, or a developer-specified mechanism. +- `closerequest` + - : The dialog can be dismissed with a platform-specific user action or a developer-specified mechanism. +- `none` + - : The dialog can only be dismissed with a developer-specified mechanism. + +## Examples + +### Basic `closedBy` usage + +```html +<dialog open closedby="any"> + <h2>My dialog</h2> + <p> + Closable using the Esc key, or by clicking outside the dialog. "Light + dismiss" behavior. + </p> +</dialog> +``` + +```js +const dialogElem = document.querySelector("dialog"); + +// Logs "any" to the console +console.log(dialogElem.closedBy); +``` + +## Specifications + +{{Specifications}} + +## Browser compatibility + +{{Compat}} + +## See also + +- {{ HTMLElement("dialog") }} diff --git a/files/en-us/web/api/htmldialogelement/index.md b/files/en-us/web/api/htmldialogelement/index.md index a7e1d00610ac3ba..0040a7e53b19dad 100644 --- a/files/en-us/web/api/htmldialogelement/index.md +++ b/files/en-us/web/api/htmldialogelement/index.md @@ -18,8 +18,10 @@ The **`HTMLDialogElement`** interface provides methods to manipulate {{HTMLEleme _Also inherits properties from its parent interface, {{domxref("HTMLElement")}}._ +- {{domxref("HTMLDialogElement.closedBy")}} {{experimental_inline}} + - : A string that sets or returns the [`closedby`](/en-US/docs/Web/HTML/Reference/Elements/dialog#closedby) attribute value of the `<dialog>` element, which indicates the types of user actions that can be used to close the dialog. - {{domxref("HTMLDialogElement.open")}} - - : A boolean value reflecting the [`open`](/en-US/docs/Web/HTML/Element/dialog#open) HTML attribute, indicating whether the dialog is available for interaction. + - : A boolean value reflecting the [`open`](/en-US/docs/Web/HTML/Reference/Elements/dialog#open) HTML attribute, indicating whether the dialog is available for interaction. - {{domxref("HTMLDialogElement.returnValue")}} - : A string that sets or returns the return value for the dialog. @@ -29,10 +31,10 @@ _Also inherits methods from its parent interface, {{domxref("HTMLElement")}}._ - {{domxref("HTMLDialogElement.close()")}} - : Closes the dialog. An optional string may be passed as an argument, updating the `returnValue` of the dialog. -- {{domxref("HTMLDialogElement.requestClose()")}} {{experimental_inline}} +- {{domxref("HTMLDialogElement.requestClose()")}} - : Requests to close the dialog. An optional string may be passed as an argument, updating the `returnValue` of the dialog. - {{domxref("HTMLDialogElement.show()")}} - - : Displays the dialog modelessly, i.e. still allowing interaction with content outside of the dialog. + - : Displays the dialog modelessly, i.e., still allowing interaction with content outside of the dialog. - {{domxref("HTMLDialogElement.showModal()")}} - : Displays the dialog as a modal, over the top of any other dialogs that might be present. Everything outside the dialog are [inert](/en-US/docs/Web/API/HTMLElement/inert) with interactions outside the dialog being blocked. @@ -45,7 +47,7 @@ Listen to these events using {{DOMxRef("EventTarget.addEventListener", "addEvent - {{domxref("HTMLDialogElement/cancel_event", "cancel")}} - : Fired when the dialog is requested to close, whether with the escape key, or via the `HTMLDialogElement.requestClose()` method. - {{domxref("HTMLDialogElement/close_event", "close")}} - - : Fired when the dialog is closed, whether with the escape key, the `HTMLDialogElement.close()` method, or via submitting a form within the dialog with [`method="dialog"`](/en-US/docs/Web/HTML/Element/form#method). + - : Fired when the dialog is closed, whether with the escape key, the `HTMLDialogElement.close()` method, or via submitting a form within the dialog with [`method="dialog"`](/en-US/docs/Web/HTML/Reference/Elements/form#method). ## Examples @@ -135,7 +137,7 @@ The handlers call {{domxref("HTMLDialogElement.close()")}} with the selection va // Confirm button closes dialog if there is a selection. confirmButton.addEventListener("click", () => { if (selectElement.value) { - //Set dialog.returnValue to selected value + // Set dialog.returnValue to selected value dialog.close(selectElement.value); } }); @@ -165,7 +167,7 @@ Here we just treat the cancel as a "close" operation, and reset the {{domxref("H ```js dialog.addEventListener("cancel", (event) => { log(`cancel_event: (dialog.returnValue: "${dialog.returnValue}")`); - dialog.returnValue = ""; //Reset value + dialog.returnValue = ""; // Reset value }); ``` @@ -195,7 +197,7 @@ In this case we just log the old and new state. ```js dialog.addEventListener("beforetoggle", (event) => { log( - `beforetoggle event: oldstate: ${event.oldState}, newState: ${event.newState}`, + `beforetoggle event: oldState: ${event.oldState}, newState: ${event.newState}`, ); // Call event.preventDefault() to prevent a dialog opening diff --git a/files/en-us/web/api/htmldialogelement/open/index.md b/files/en-us/web/api/htmldialogelement/open/index.md index 0a3f515601fd13e..587a31c8604856b 100644 --- a/files/en-us/web/api/htmldialogelement/open/index.md +++ b/files/en-us/web/api/htmldialogelement/open/index.md @@ -10,16 +10,15 @@ browser-compat: api.HTMLDialogElement.open The **`open`** property of the {{domxref("HTMLDialogElement")}} interface is a boolean value reflecting the -[`open`](/en-US/docs/Web/HTML/Element/dialog#open) HTML attribute, indicating whether the {{htmlelement("dialog")}} is +[`open`](/en-US/docs/Web/HTML/Reference/Elements/dialog#open) HTML attribute, indicating whether the {{htmlelement("dialog")}} is available for interaction. ## Value -A boolean value representing the state of the [`open`](/en-US/docs/Web/HTML/Element/dialog#open) HTML attribute. `true` means it is set, and therefore the dialog -is shown. `false` means it not set, and therefore the dialog is not shown. +A boolean value representing the state of the [`open`](/en-US/docs/Web/HTML/Reference/Elements/dialog#open) HTML attribute. A value of `true` means that the dialog is showing, while `false` means it's not showing. -The property is not read only — it is possible to set the value to programmatically -show or hide the dialog. +> [!WARNING] +> While the `open` property is technically not read-only and can be set directly, doing so is strongly discouraged by [the HTML specification](https://html.spec.whatwg.org/multipage/interactive-elements.html#attr-dialog-closedby), as it can break normal dialog interactions in unexpected ways. For example, the [`close`](/en-US/docs/Web/API/HTMLDialogElement/close_event) event won't fire when programmatically setting `open` to `false`, and subsequent calls to the [`close()`](/en-US/docs/Web/API/HTMLDialogElement/close) and [`requestClose()`](/en-US/docs/Web/API/HTMLDialogElement/requestClose) methods will have no effect. Instead, it's better to use methods such as [`show()`](/en-US/docs/Web/API/HTMLDialogElement/show), [`showModal()`](/en-US/docs/Web/API/HTMLDialogElement/showModal), `close()`, and `requestClose()` to change the value of the `open` attribute. ## Examples diff --git a/files/en-us/web/api/htmldialogelement/requestclose/index.md b/files/en-us/web/api/htmldialogelement/requestclose/index.md index ec6429c435547ec..bb26ae3c86f2f47 100644 --- a/files/en-us/web/api/htmldialogelement/requestclose/index.md +++ b/files/en-us/web/api/htmldialogelement/requestclose/index.md @@ -3,18 +3,18 @@ title: "HTMLDialogElement: requestClose() method" short-title: requestClose() slug: Web/API/HTMLDialogElement/requestClose page-type: web-api-instance-method -status: - - experimental browser-compat: api.HTMLDialogElement.requestClose --- -{{ APIRef("HTML DOM") }}{{SeeCompatTable}} +{{ APIRef("HTML DOM") }} The **`requestClose()`** method of the {{domxref("HTMLDialogElement")}} interface requests to close the {{htmlelement("dialog")}}. An optional string may be passed as an argument, updating the `returnValue` of the dialog. -This method differs from the `HTMLDialogElement.close()` method by firing a `cancel` event before firing the `close` event. This allows -authors to prevent the dialog from closing. This method exposes the same behavior as the dialog's internal close watcher. +This method differs from the {{domxref("HTMLDialogElement.close()")}} method in that it fires a `cancel` event before firing the `close` event. +Authors can call {{domxref("Event.preventDefault()")}} in the handler for the `cancel` event to prevent the dialog from closing. + +This method exposes the same behavior as the dialog's internal close watcher. ## Syntax @@ -34,14 +34,20 @@ None ({{jsxref("undefined")}}). ## Examples +### Using requestClose() + The following example shows a simple button that, when clicked, opens a {{htmlelement("dialog")}} containing a form, via the `showModal()` method. -From there you can click the _X_ button to request to close the dialog (via the `HTMLDialogElement.requestClose()` method), or submit the form via the submit button. +Once open you can click the **X** button to request to close the dialog (via the `HTMLDialogElement.requestClose()` method), or submit the form via the **Confirm** button. + +#### HTML ```html <!-- Simple pop-up dialog box, containing a form --> <dialog id="favDialog"> <form method="dialog"> - <button id="close" aria-label="close" formnovalidate>X</button> + <button type="button" id="close" aria-label="close" formnovalidate> + X + </button> <section> <p> <label for="favAnimal">Favorite animal:</label> @@ -63,39 +69,44 @@ From there you can click the _X_ button to request to close the dialog (via the <menu> <button id="updateDetails">Update details</button> </menu> +``` -<script> - (() => { - const updateButton = document.getElementById("updateDetails"); - const closeButton = document.getElementById("close"); - const dialog = document.getElementById("favDialog"); - - // Update button opens a modal dialog - updateButton.addEventListener("click", () => { - dialog.showModal(); - }); - - // Form close button requests to close the dialog box - closeButton.addEventListener("click", () => { - dialog.requestClose("animalNotChosen"); - }); - - function dialogShouldNotClose() { - // Add logic to decide whether to prevent the dialog from closing - } - - dialog.addEventListener("cancel", (event) => { - if (!event.cancelable) return; - if (dialogShouldNotClose()) event.preventDefault(); - }); - })(); -</script> +#### JavaScript + +```js +const updateButton = document.getElementById("updateDetails"); +const closeButton = document.getElementById("close"); +const dialog = document.getElementById("favDialog"); + +// Update button opens a modal dialog +updateButton.addEventListener("click", () => { + dialog.showModal(); +}); + +// Form close button requests to close the dialog box +closeButton.addEventListener("click", () => { + dialog.requestClose("animalNotChosen"); +}); + +function dialogShouldNotClose() { + // Add logic to decide whether to allow the dialog to close. + // Closing prevented by default + return true; +} + +dialog.addEventListener("cancel", (event) => { + if (!event.cancelable) return; + if (dialogShouldNotClose()) { + console.log("Closing prevented"); + event.preventDefault(); + } +}); ``` If the "X" button was of `type="submit"`, the dialog would have closed without requiring JavaScript. -A form submission closes the `<dialog>` it is nested within if the [form's method is `dialog`](/en-US/docs/Web/HTML/Element/form#method), so no "close" button is required. +A form submission closes the `<dialog>` it is nested within if the [form's method is `dialog`](/en-US/docs/Web/HTML/Reference/Elements/form#method), so no "close" button is required. -### Result +#### Result {{ EmbedLiveSample('Examples', '100%', '200px') }} diff --git a/files/en-us/web/api/htmldialogelement/returnvalue/index.md b/files/en-us/web/api/htmldialogelement/returnvalue/index.md index 5c0377b2a2ca5a3..69d838d09f9362f 100644 --- a/files/en-us/web/api/htmldialogelement/returnvalue/index.md +++ b/files/en-us/web/api/htmldialogelement/returnvalue/index.md @@ -18,63 +18,64 @@ Defaults to an empty string (`""`). ## Examples -The following example displays a button to open a dialog containing a Terms of Service prompt via the `showModal()` method. -The script handles the user's input by assigning the `returnValue` when the Accept or Decline button is clicked. -The "Decline" button sets the `returnValue` to "declined", while the "Accept" button sets it to "accepted". Additionally, closing the dialog (e.g., using the close event) updates the status text with the dialog's `returnValue`. -Closing the dialog with the <kbd>Esc</kbd> key does not set the `returnValue`. +### Checking the return value + +The following example displays a button to open a dialog. The dialog asks the user if they want to accept a Terms of Service prompt. + +The dialog contains "Accept" or "Decline" buttons: when the user clicks one of the buttons, the button's click handler closes the dialog, passing their choice into the {{domxref("HTMLDialogElement.close()", "close()")}} function. This assigns the choice to the dialog's `returnValue` property. + +In the dialog's {{domxref("HTMLDialogElement.close_event", "close")}} event handler, the example updates the main page's status text to record the `returnValue`. + +If the user dismisses the dialog without clicking a button (for example, by pressing the <kbd>Esc</kbd> key), then the return value is not set. + +#### HTML ```html -<!-- Simple pop-up dialog box --> <dialog id="termsDialog"> - <p>Do you agree to the Terms of Service(link)?</p> + <p>Do you agree to the Terms of Service (link)?</p> <button id="declineButton" value="declined">Decline</button> <button id="acceptButton" value="accepted">Accept</button> </dialog> <p> - <button id="openDialog">Review ToS</button> + <button id="openDialogButton">Review ToS</button> </p> <p id="statusText"></p> +``` + +#### JavaScript -<script> - const dialog = document.getElementById("termsDialog"); - const openDialog = document.getElementById("openDialog"); - const statusText = document.getElementById("statusText"); - const declineButton = document.getElementById("declineButton"); - const acceptButton = document.getElementById("acceptButton"); - - function handleUserInput(returnValue) { - if (returnValue === "") { - statusText.innerText = "There was no return value"; - } else { - statusText.innerText = "Return value: " + returnValue; - } - } - - openDialog.addEventListener("click", () => { - dialog.showModal(); - handleUserInput(dialog.returnValue); - }); - - declineButton.addEventListener("click", closeDialog); - acceptButton.addEventListener("click", closeDialog); - - function closeDialog(event) { - const button = event.target; - const returnValue = button.value; - dialog.close(returnValue); - handleUserInput(dialog.returnValue); - } - - dialog.addEventListener("close", () => { - openCheck(dialog); - handleUserInput(dialog.returnValue); - }); -</script> +```js +const dialog = document.getElementById("termsDialog"); +const statusText = document.getElementById("statusText"); + +const openDialogButton = document.getElementById("openDialogButton"); +const declineButton = document.getElementById("declineButton"); +const acceptButton = document.getElementById("acceptButton"); + +openDialogButton.addEventListener("click", () => { + dialog.showModal(); +}); + +declineButton.addEventListener("click", closeDialog); +acceptButton.addEventListener("click", closeDialog); + +function closeDialog(event) { + const button = event.target; + dialog.close(button.value); +} + +dialog.addEventListener("close", () => { + statusText.innerText = dialog.returnValue + ? `Return value: ${dialog.returnValue}` + : "There was no return value"; +}); ``` -### Result +#### Result + +Try clicking "Review ToS", then choosing the "Accept" or "Decline" buttons in the dialog, or dismissing the dialog by pressing the <kbd>Esc</kbd> key, and observe the different status updates. -{{ EmbedLiveSample('Examples', '100%', '200px') }} +{{ EmbedLiveSample('Checking the return value', '100%', '200px') }} ## Specifications diff --git a/files/en-us/web/api/htmldialogelement/show/index.md b/files/en-us/web/api/htmldialogelement/show/index.md index 90eee99e7d6832a..1080e50436f0b90 100644 --- a/files/en-us/web/api/htmldialogelement/show/index.md +++ b/files/en-us/web/api/htmldialogelement/show/index.md @@ -9,7 +9,7 @@ browser-compat: api.HTMLDialogElement.show {{ APIRef("HTML DOM") }} The **`show()`** method of the {{domxref("HTMLDialogElement")}} -interface displays the dialog modelessly, i.e. still allowing interaction with content +interface displays the dialog modelessly, i.e., still allowing interaction with content outside of the dialog. ## Syntax @@ -29,7 +29,7 @@ None ({{jsxref("undefined")}}). ### Exceptions - `InvalidStateError` {{domxref("DOMException")}} - - : Thrown if the dialog is already open and modal (i.e. if the dialog has already been opened with {{domxref("HTMLDialogElement.showModal()")}}). + - : Thrown if the dialog is already open and modal (i.e., if the dialog has already been opened with {{domxref("HTMLDialogElement.showModal()")}}). ## Examples diff --git a/files/en-us/web/api/htmldialogelement/showmodal/index.md b/files/en-us/web/api/htmldialogelement/showmodal/index.md index 409d08c116cf764..08c808c5c48c7a3 100644 --- a/files/en-us/web/api/htmldialogelement/showmodal/index.md +++ b/files/en-us/web/api/htmldialogelement/showmodal/index.md @@ -11,7 +11,7 @@ browser-compat: api.HTMLDialogElement.showModal The **`showModal()`** method of the {{domxref("HTMLDialogElement")}} interface displays the dialog as a modal, over the top of any other dialogs that might be present. It displays in the {{glossary("top layer")}}, along with a -{{cssxref('::backdrop')}} pseudo-element. Elements inside the same document as the dialog, except the dialog and its descendants, become _inert_ (as if the [`inert`](/en-US/docs/Web/HTML/Global_attributes/inert) attribute is specified). Only the containing document becomes blocked; if the dialog is rendered inside an iframe, the rest of the page remains interactive. +{{cssxref('::backdrop')}} pseudo-element. Elements inside the same document as the dialog, except the dialog and its descendants, become _inert_ (as if the [`inert`](/en-US/docs/Web/HTML/Reference/Global_attributes/inert) attribute is specified). Only the containing document becomes blocked; if the dialog is rendered inside an iframe, the rest of the page remains interactive. ## Syntax @@ -30,7 +30,7 @@ None ({{jsxref("undefined")}}). ### Exceptions - `InvalidStateError` {{domxref("DOMException")}} - - : Thrown if the dialog is already open and non-modal (i.e. if the dialog has already been opened with {{domxref("HTMLDialogElement.show()")}}). + - : Thrown if the dialog is already open and non-modal (i.e., if the dialog has already been opened with {{domxref("HTMLDialogElement.show()")}}). ## Examples diff --git a/files/en-us/web/api/htmlelement/accesskey/index.md b/files/en-us/web/api/htmlelement/accesskey/index.md index 4914ee9b4083e9e..0e7ae3fee7edaf2 100644 --- a/files/en-us/web/api/htmlelement/accesskey/index.md +++ b/files/en-us/web/api/htmlelement/accesskey/index.md @@ -23,4 +23,4 @@ The **`HTMLElement.accessKey`** property sets the keystroke which a user can pre ## See also -- [HTML global attribute: accesskey](/en-US/docs/Web/HTML/Global_attributes/accesskey) +- [HTML global attribute: accesskey](/en-US/docs/Web/HTML/Reference/Global_attributes/accesskey) diff --git a/files/en-us/web/api/htmlelement/accesskeylabel/index.md b/files/en-us/web/api/htmlelement/accesskeylabel/index.md index 7c9565dab9d3748..ccafd20c87ddf90 100644 --- a/files/en-us/web/api/htmlelement/accesskeylabel/index.md +++ b/files/en-us/web/api/htmlelement/accesskeylabel/index.md @@ -49,5 +49,5 @@ btn.onclick = () => { ## See also - {{domxref("HTMLElement.accessKey")}} -- The [accesskey](/en-US/docs/Web/HTML/Global_attributes/accesskey) global +- The [accesskey](/en-US/docs/Web/HTML/Reference/Global_attributes/accesskey) global attribute. diff --git a/files/en-us/web/api/htmlelement/anchorelement/index.md b/files/en-us/web/api/htmlelement/anchorelement/index.md index 735e29acf5ddb9a..cd058f88b414f75 100644 --- a/files/en-us/web/api/htmlelement/anchorelement/index.md +++ b/files/en-us/web/api/htmlelement/anchorelement/index.md @@ -11,7 +11,7 @@ browser-compat: api.HTMLElement.anchorElement {{APIRef("HTML DOM")}}{{Non-standard_Header}}{{SeeCompatTable}} -The **`anchorElement`** property of the {{domxref("HTMLElement")}} interface returns a reference to the element's anchor element. This works only in the case of elements associated with their anchors via the [`anchor`](/en-US/docs/Web/HTML/Global_attributes/anchor) HTML attribute, not elements associated with their anchors via the CSS {{cssxref("anchor-name")}} and {{cssxref("position-anchor")}} properties. +The **`anchorElement`** property of the {{domxref("HTMLElement")}} interface returns a reference to the element's anchor element. This works only in the case of elements associated with their anchors via the [`anchor`](/en-US/docs/Web/HTML/Reference/Global_attributes/anchor) HTML attribute, not elements associated with their anchors via the CSS {{cssxref("anchor-name")}} and {{cssxref("position-anchor")}} properties. ## Value @@ -25,7 +25,7 @@ This example associates an element with an anchor in HTML, and uses JavaScript t #### HTML -In the HTML, we create a {{htmlelement("div")}} element with an [`id`](/en-US/docs/Web/HTML/Global_attributes/id) of `example-anchor`. This will be our anchor element. We then include another `<div>` with a class of `infobox` and an [`anchor`](/en-US/docs/Web/HTML/Global_attributes/anchor) attribute set to `example-anchor`. This designates the first `<div>` as the anchor of the second `<div>`, associating the two together. +In the HTML, we create a {{htmlelement("div")}} element with an [`id`](/en-US/docs/Web/HTML/Reference/Global_attributes/id) of `example-anchor`. This will be our anchor element. We then include another `<div>` with a class of `infobox` and an [`anchor`](/en-US/docs/Web/HTML/Reference/Global_attributes/anchor) attribute set to `example-anchor`. This designates the first `<div>` as the anchor of the second `<div>`, associating the two together. We also include a {{htmlelement("p")}} element to output some results into. @@ -70,6 +70,6 @@ This attribute is not currently part of the HTML specification. Read the discuss ## See also -- HTML [`anchor`](/en-US/docs/Web/HTML/Global_attributes/anchor) attribute +- HTML [`anchor`](/en-US/docs/Web/HTML/Reference/Global_attributes/anchor) attribute - CSS {{cssxref("anchor-name")}} and {{cssxref("position-anchor")}} properties - [CSS anchor positioning](/en-US/docs/Web/CSS/CSS_anchor_positioning) module diff --git a/files/en-us/web/api/htmlelement/autocapitalize/index.md b/files/en-us/web/api/htmlelement/autocapitalize/index.md index cdef171838763eb..4835a78966f2e83 100644 --- a/files/en-us/web/api/htmlelement/autocapitalize/index.md +++ b/files/en-us/web/api/htmlelement/autocapitalize/index.md @@ -11,11 +11,11 @@ browser-compat: api.HTMLElement.autocapitalize The **`autocapitalize`** property of the {{domxref("HTMLElement")}} interface represents the element's capitalization behavior for user input. It is available on all HTML elements, though it doesn't affect all of them, including: - {{htmlelement("input")}} and {{htmlelement("textarea")}} elements. -- Any element with [`contenteditable`](/en-US/docs/Web/HTML/Global_attributes/contenteditable) set on it. +- Any element with [`contenteditable`](/en-US/docs/Web/HTML/Reference/Global_attributes/contenteditable) set on it. `autocapitalize` doesn't affect behavior when typing on a physical keyboard. It affects the behavior of other input mechanisms such as virtual keyboards on mobile devices and voice input. This can assist users by making data entry quicker and easier, for example by automatically capitalizing the first letter of each sentence. -It reflects the value of the [`autocapitalize`](/en-US/docs/Web/HTML/Global_attributes/autocapitalize) HTML global attribute. +It reflects the value of the [`autocapitalize`](/en-US/docs/Web/HTML/Reference/Global_attributes/autocapitalize) HTML global attribute. ## Value @@ -72,4 +72,4 @@ controller.addEventListener("input", (e) => { ## See also -- [`autocapitalize`](/en-US/docs/Web/HTML/Global_attributes/autocapitalize) HTML global attribute +- [`autocapitalize`](/en-US/docs/Web/HTML/Reference/Global_attributes/autocapitalize) HTML global attribute diff --git a/files/en-us/web/api/htmlelement/autocorrect/index.md b/files/en-us/web/api/htmlelement/autocorrect/index.md index 8544438b62283e1..d22dbcdb48eb9f4 100644 --- a/files/en-us/web/api/htmlelement/autocorrect/index.md +++ b/files/en-us/web/api/htmlelement/autocorrect/index.md @@ -14,7 +14,7 @@ The specific autocorrection behavior, including which words are substituted, dep For example, on macOS a user agent might rely on [registered replacement text and punctuation](https://support.apple.com/en-vn/guide/mac-help/mh35735/mac). Other devices and browsers may use a different approach. -The property reflects the value of the [`autocorrect`](/en-US/docs/Web/HTML/Global_attributes/autocorrect) HTML global attribute. +The property reflects the value of the [`autocorrect`](/en-US/docs/Web/HTML/Reference/Global_attributes/autocorrect) HTML global attribute. ## Value @@ -28,7 +28,7 @@ This example shows how you can enable and disable autocorrection. #### HTML -The HTML markup defines a toggle button and an {{htmlelement("input")}} element of [`type="search"`](/en-US/docs/Web/HTML/Element/input/search). +The HTML markup defines a toggle button and an {{htmlelement("input")}} element of [`type="search"`](/en-US/docs/Web/HTML/Reference/Elements/input/search). Note that if auto-correction is supported, it will be enabled by default. ```html @@ -106,4 +106,4 @@ When the autocorrect is enabled, and if the implementation has the appropriate s ## See also -- [`autocapitalize`](/en-US/docs/Web/HTML/Global_attributes/autocapitalize) HTML global attribute +- [`autocapitalize`](/en-US/docs/Web/HTML/Reference/Global_attributes/autocapitalize) HTML global attribute diff --git a/files/en-us/web/api/htmlelement/autofocus/index.md b/files/en-us/web/api/htmlelement/autofocus/index.md index 6f04bdf03710b8f..439e299fcc2ce66 100644 --- a/files/en-us/web/api/htmlelement/autofocus/index.md +++ b/files/en-us/web/api/htmlelement/autofocus/index.md @@ -8,7 +8,7 @@ browser-compat: api.HTMLElement.autofocus {{APIRef("HTML DOM")}} -The **`autofocus`** property of the {{domxref("HTMLElement")}} interface represents a boolean value reflecting the [`autofocus`](/en-US/docs/Web/HTML/Element/select#autofocus) HTML global attribute, which indicates whether the control should be focused when the page loads, or when dialog or popover become shown if specified in an element inside {{htmlelement("dialog")}} elements or elements whose popover attribute is set. +The **`autofocus`** property of the {{domxref("HTMLElement")}} interface represents a boolean value reflecting the [`autofocus`](/en-US/docs/Web/HTML/Reference/Elements/select#autofocus) HTML global attribute, which indicates whether the control should be focused when the page loads, or when dialog or popover become shown if specified in an element inside {{htmlelement("dialog")}} elements or elements whose popover attribute is set. Only one form-associated element inside a document, or a {{htmlelement("dialog")}} element, or an element whose `popover` attribute is set, can have this attribute specified. If there are several, the first element with the attribute set inserted, usually the first such element on the page, gets the initial focus. diff --git a/files/en-us/web/api/htmlelement/beforetoggle_event/index.md b/files/en-us/web/api/htmlelement/beforetoggle_event/index.md index 607b1585bdc49a5..d727d458e1b3b8f 100644 --- a/files/en-us/web/api/htmlelement/beforetoggle_event/index.md +++ b/files/en-us/web/api/htmlelement/beforetoggle_event/index.md @@ -17,17 +17,17 @@ This event is [cancelable](/en-US/docs/Web/API/Event/cancelable) when an element Among other things, this event can be used to: - prevent an element from being shown. -- add or remove classes or properties from the element or associated elements, for example to control the animation behaviour of a dialog as it is opened and closed. +- add or remove classes or properties from the element or associated elements, for example to control the animation behavior of a dialog as it is opened and closed. - clear the state of the element before it is opened or after it is hidden, for example to reset a dialog form and return value to an empty state, or hide any nested manual popovers when reopening a popup. ## Syntax Use the event name in methods like {{domxref("EventTarget.addEventListener", "addEventListener()")}}, or set an event handler property. -```js -addEventListener("beforetoggle", (event) => {}); +```js-nolint +addEventListener("beforetoggle", (event) => { }) -onbeforetoggle = (event) => {}; +onbeforetoggle = (event) => { } ``` ## Event type @@ -188,7 +188,7 @@ For example: ```js popover.addEventListener("beforetoggle", () => { - //... + // … }); popover.showPopover(); @@ -210,6 +210,6 @@ popover.hidePopover(); ## See also -- [`popover`](/en-US/docs/Web/HTML/Global_attributes/popover) HTML global attribute +- [`popover`](/en-US/docs/Web/HTML/Reference/Global_attributes/popover) HTML global attribute - [Popover API](/en-US/docs/Web/API/Popover_API) - Related event: [`toggle`](/en-US/docs/Web/API/HTMLElement/toggle_event) diff --git a/files/en-us/web/api/htmlelement/change_event/index.md b/files/en-us/web/api/htmlelement/change_event/index.md index e9c9c8a773744fa..8bba3c3b2c5c178 100644 --- a/files/en-us/web/api/htmlelement/change_event/index.md +++ b/files/en-us/web/api/htmlelement/change_event/index.md @@ -23,10 +23,10 @@ The HTML specification lists [the `<input>` types that should fire the `change` Use the event name in methods like {{domxref("EventTarget.addEventListener", "addEventListener()")}}, or set an event handler property. -```js -addEventListener("change", (event) => {}); +```js-nolint +addEventListener("change", (event) => { }) -onchange = (event) => {}; +onchange = (event) => { } ``` ## Event type diff --git a/files/en-us/web/api/htmlelement/click/index.md b/files/en-us/web/api/htmlelement/click/index.md index 8ba7e32c42979d2..92850f02ddbca12 100644 --- a/files/en-us/web/api/htmlelement/click/index.md +++ b/files/en-us/web/api/htmlelement/click/index.md @@ -8,7 +8,7 @@ browser-compat: api.HTMLElement.click {{ APIRef("HTML DOM") }} -The **`HTMLElement.click()`** method simulates a mouse click on an element. When called on an element, the element's {{domxref("Element/click_event", "click")}} event is fired (unless its [`disabled`](/en-US/docs/Web/HTML/Attributes/disabled) attribute is set). +The **`HTMLElement.click()`** method simulates a mouse click on an element. When called on an element, the element's {{domxref("Element/click_event", "click")}} event is fired (unless its [`disabled`](/en-US/docs/Web/HTML/Reference/Attributes/disabled) attribute is set). ## Syntax diff --git a/files/en-us/web/api/htmlelement/command_event/index.md b/files/en-us/web/api/htmlelement/command_event/index.md index 3c3d0665ae368c7..7b3066bf99e29d9 100644 --- a/files/en-us/web/api/htmlelement/command_event/index.md +++ b/files/en-us/web/api/htmlelement/command_event/index.md @@ -2,23 +2,21 @@ title: "HTMLElement: command event" slug: Web/API/HTMLElement/command_event page-type: web-api-event -status: - - experimental browser-compat: api.HTMLElement.command_event --- -{{APIRef("Invoker Commands API")}}{{SeeCompatTable}} +{{APIRef("Invoker Commands API")}} -The **`command`** event of the {{domxref("HTMLElement")}} interface fires on an element that is controlled via a {{domxref("HTMLButtonElement", "button")}} with valid {{domxref("HTMLButtonElement.commandForElement", "commandForElement")}} and {{domxref("HTMLButtonElement.command", "command")}} values, whenever the button is interacted with (e.g. it is clicked). +The **`command`** event of the {{domxref("HTMLElement")}} interface fires on an element that is controlled via a {{domxref("HTMLButtonElement", "button")}} with valid {{domxref("HTMLButtonElement.commandForElement", "commandForElement")}} and {{domxref("HTMLButtonElement.command", "command")}} values, whenever the button is interacted with (e.g., it is clicked). ## Syntax Use the event name in methods like {{domxref("EventTarget.addEventListener", "addEventListener()")}}, or set an event handler property. -```js -addEventListener("command", (event) => {}); +```js-nolint +addEventListener("command", (event) => { }) -oncommand = (event) => {}; +oncommand = (event) => { } ``` ## Event type @@ -34,7 +32,7 @@ A {{domxref("CommandEvent")}}. Inherits from {{domxref("Event")}}. ```js const popover = document.getElementById("mypopover"); -// ... +// … popover.addEventListener("command", (event) => { if (event.action === "show-popover") { diff --git a/files/en-us/web/api/htmlelement/contenteditable/index.md b/files/en-us/web/api/htmlelement/contenteditable/index.md index 2738bd13a0c24aa..86bfbae02cff788 100644 --- a/files/en-us/web/api/htmlelement/contenteditable/index.md +++ b/files/en-us/web/api/htmlelement/contenteditable/index.md @@ -39,4 +39,4 @@ A string. ## See also - {{domxref("HTMLElement.isContentEditable")}} -- The [`contenteditable`](/en-US/docs/Web/HTML/Global_attributes/contenteditable) global attribute. +- The [`contenteditable`](/en-US/docs/Web/HTML/Reference/Global_attributes/contenteditable) global attribute. diff --git a/files/en-us/web/api/htmlelement/copy_event/index.md b/files/en-us/web/api/htmlelement/copy_event/index.md deleted file mode 100644 index 810a42769985501..000000000000000 --- a/files/en-us/web/api/htmlelement/copy_event/index.md +++ /dev/null @@ -1,89 +0,0 @@ ---- -title: "HTMLElement: copy event" -short-title: copy -slug: Web/API/HTMLElement/copy_event -page-type: web-api-event -browser-compat: api.Element.copy_event ---- - -{{ APIRef("HTML DOM") }} - -The **`copy`** event fires when the user initiates a copy action through the browser's user interface. - -## Syntax - -Use the event name in methods like {{domxref("EventTarget.addEventListener", "addEventListener()")}}, or set an event handler property. - -```js -addEventListener("copy", (event) => {}); - -oncopy = (event) => {}; -``` - -## Event type - -A {{domxref("ClipboardEvent")}}. Inherits from {{domxref("Event")}}. - -{{InheritanceDiagram("ClipboardEvent")}} - -## Event properties - -_Also inherits properties from its parent {{domxref("Event")}}_. - -- {{domxref("ClipboardEvent.clipboardData")}} {{ReadOnlyInline}} - - : A {{domxref("DataTransfer")}} object containing the data affected by the user-initiated {{domxref("HTMLElement/cut_event", "cut")}}, `copy`, or {{domxref("HTMLElement/paste_event", "paste")}} operation, along with its MIME type. - -## Example - -This example blocks every copy and paste attempt from the {{htmlElement("textarea")}}. - -### HTML - -```html -<h3>Play with this text area:</h3> -<textarea id="editor" rows="3"> -Try copying and pasting text into this field! -</textarea> - -<h3>Log:</h3> -<p id="log"></p> -``` - -### JavaScript - -```js -const log = document.getElementById("log"); - -function logCopy(event) { - log.innerText = `Copy blocked!\n${log.innerText}`; - event.preventDefault(); -} - -function logPaste(event) { - log.innerText = `Paste blocked!\n${log.innerText}`; - event.preventDefault(); -} - -const editor = document.getElementById("editor"); - -editor.oncopy = logCopy; -editor.onpaste = logPaste; -``` - -### Result - -{{EmbedLiveSample("Example", 700, 300)}} - -## Specifications - -{{Specifications}} - -## Browser compatibility - -{{Compat}} - -## See also - -- Related events - - {{domxref("HTMLElement.cut_event", "cut")}} event - - {{domxref("HTMLElement.paste_event", "paste")}} event diff --git a/files/en-us/web/api/htmlelement/cut_event/index.md b/files/en-us/web/api/htmlelement/cut_event/index.md deleted file mode 100644 index 3896d59eb73e269..000000000000000 --- a/files/en-us/web/api/htmlelement/cut_event/index.md +++ /dev/null @@ -1,88 +0,0 @@ ---- -title: "HTMLElement: cut event" -short-title: cut -slug: Web/API/HTMLElement/cut_event -page-type: web-api-event -browser-compat: api.Element.cut_event ---- - -{{ APIRef("HTML DOM") }} - -The **`cut`** event fires when the user initiates a cut action through the browser's user interface. - -## Syntax - -Use the event name in methods like {{domxref("EventTarget.addEventListener", "addEventListener()")}}, or set an event handler property. - -```js -addEventListener("cut", (event) => {}); - -oncut = (event) => {}; -``` - -## Event type - -A {{domxref("ClipboardEvent")}}. Inherits from {{domxref("Event")}}. - -{{InheritanceDiagram("ClipboardEvent")}} - -## Event properties - -_Also inherits properties from its parent {{domxref("Event")}}_. - -- {{domxref("ClipboardEvent.clipboardData")}} {{ReadOnlyInline}} - - : A {{domxref("DataTransfer")}} object containing the data affected by the user-initiated `cut`, {{domxref("HTMLElement/copy_event", "copy")}}, or {{domxref("HTMLElement/paste_event", "paste")}} operation, along with its MIME type. - -## Example - -This example allows text to be copied from the {{htmlElement("textarea")}}, but doesn't -allow text to be cut. It also logs each copy and cut attempt. - -### HTML - -```html -<h3>Play with this text area:</h3> -<textarea id="editor" rows="3"> -Try copying and cutting the text in this field! -</textarea> - -<h3>Log:</h3> -<p id="log"></p> -``` - -### JavaScript - -```js -function logCopy(event) { - log.innerText = `Copied!\n${log.innerText}`; -} - -function preventCut(event) { - event.preventDefault(); - log.innerText = `Cut blocked!\n${log.innerText}`; -} - -const editor = document.getElementById("editor"); -const log = document.getElementById("log"); - -editor.oncopy = logCopy; -editor.oncut = preventCut; -``` - -### Result - -{{EmbedLiveSample("Example", 700, 300)}} - -## Specifications - -{{Specifications}} - -## Browser compatibility - -{{Compat}} - -## See also - -- Related events - - {{domxref("HTMLElement.copy_event", "copy")}} event - - {{domxref("HTMLElement.paste_event", "paste")}} event diff --git a/files/en-us/web/api/htmlelement/dataset/index.md b/files/en-us/web/api/htmlelement/dataset/index.md index d38ea9d2edd1823..47500ef4cc809f5 100644 --- a/files/en-us/web/api/htmlelement/dataset/index.md +++ b/files/en-us/web/api/htmlelement/dataset/index.md @@ -9,7 +9,7 @@ browser-compat: api.HTMLElement.dataset {{APIRef("HTML DOM")}} The **`dataset`** read-only property -of the {{DOMxRef("HTMLElement")}} interface provides read/write access to [custom data attributes](/en-US/docs/Web/HTML/Global_attributes/data-*) +of the {{DOMxRef("HTMLElement")}} interface provides read/write access to [custom data attributes](/en-US/docs/Web/HTML/Reference/Global_attributes/data-*) (`data-*`) on elements. It exposes a map of strings ({{domxref("DOMStringMap")}}) with an entry for each `data-*` attribute. @@ -35,7 +35,7 @@ they are read or written: Details and examples of converting between the HTML and JavaScript forms is described in more detail in the next section. In addition to the information below, you'll find a how-to guide for using HTML data -attributes in our article [_Using data attributes_](/en-US/docs/Learn_web_development/Howto/Solve_HTML_problems/Use_data_attributes). +attributes in our article [_Using data attributes_](/en-US/docs/Web/HTML/How_to/Use_data_attributes). ### Name conversion @@ -74,7 +74,7 @@ For example, a `data-abc-def` attribute corresponds to - Attributes can also be set and read using bracket syntax: `element.dataset['keyname']`. - The [`in` operator](/en-US/docs/Web/JavaScript/Reference/Operators/in) can check if a given attribute exists: - `'keyname' in element.dataset`. Note that this will walk the [prototype chain](/en-US/docs/Web/JavaScript/Inheritance_and_the_prototype_chain) of `dataset` and may be unsafe if you have external code that may pollute the prototype chain. Several alternatives exist, such as {{jsxref("Object/hasOwn", "Object.hasOwn(element.dataset, 'keyname')")}}, or just checking if `element.dataset.keyname !== undefined`. + `'keyname' in element.dataset`. Note that this will walk the [prototype chain](/en-US/docs/Web/JavaScript/Guide/Inheritance_and_the_prototype_chain) of `dataset` and may be unsafe if you have external code that may pollute the prototype chain. Several alternatives exist, such as {{jsxref("Object/hasOwn", "Object.hasOwn(element.dataset, 'keyname')")}}, or just checking if `element.dataset.keyname !== undefined`. ### Setting values @@ -130,7 +130,7 @@ if (el.dataset.someDataAttr === undefined) { ## See also -- The HTML [`data-*`](/en-US/docs/Web/HTML/Global_attributes/data-*) class +- The HTML [`data-*`](/en-US/docs/Web/HTML/Reference/Global_attributes/data-*) class of global attributes -- [Using data attributes](/en-US/docs/Learn_web_development/Howto/Solve_HTML_problems/Use_data_attributes) +- [Using data attributes](/en-US/docs/Web/HTML/How_to/Use_data_attributes) - {{DOMxRef("Element.getAttribute()")}} and {{DOMxRef("Element.setAttribute()")}} diff --git a/files/en-us/web/api/htmlelement/dir/index.md b/files/en-us/web/api/htmlelement/dir/index.md index bbde19073ba5107..672cadb66ba670b 100644 --- a/files/en-us/web/api/htmlelement/dir/index.md +++ b/files/en-us/web/api/htmlelement/dir/index.md @@ -8,7 +8,7 @@ browser-compat: api.HTMLElement.dir {{ApiRef("HTML DOM")}} -The **`HTMLElement.dir`** property indicates the text writing directionality of the content of the current element. It reflects the element's [`dir`](/en-US/docs/Web/HTML/Global_attributes/dir) attribute. +The **`HTMLElement.dir`** property indicates the text writing directionality of the content of the current element. It reflects the element's [`dir`](/en-US/docs/Web/HTML/Reference/Global_attributes/dir) attribute. Note that if the `dir` attribute is unspecified, the element itself may still inherit directionality from its parent. However, that inherited directionality is not reflected by this property's value. @@ -46,7 +46,7 @@ para.dir = "rtl"; ## See also - {{domxref("document.dir")}} -- HTML [`dir`](/en-US/docs/Web/HTML/Global_attributes/dir) +- HTML [`dir`](/en-US/docs/Web/HTML/Reference/Global_attributes/dir) global attribute - CSS {{cssxref("direction")}} property - CSS {{cssxref(":dir")}} pseudo-class diff --git a/files/en-us/web/api/htmlelement/drag_event/index.md b/files/en-us/web/api/htmlelement/drag_event/index.md index c90a79ae36a5eb8..1b1c1f41ede1843 100644 --- a/files/en-us/web/api/htmlelement/drag_event/index.md +++ b/files/en-us/web/api/htmlelement/drag_event/index.md @@ -16,10 +16,10 @@ This event is cancelable and may bubble up to the {{domxref("Document")}} and {{ Use the event name in methods like {{domxref("EventTarget.addEventListener", "addEventListener()")}}, or set an event handler property. -```js -addEventListener("drag", (event) => {}); +```js-nolint +addEventListener("drag", (event) => { }) -ondrag = (event) => {}; +ondrag = (event) => { } ``` ## Event type diff --git a/files/en-us/web/api/htmlelement/dragend_event/index.md b/files/en-us/web/api/htmlelement/dragend_event/index.md index c1715c2511fd1a9..2de863dc3997081 100644 --- a/files/en-us/web/api/htmlelement/dragend_event/index.md +++ b/files/en-us/web/api/htmlelement/dragend_event/index.md @@ -16,10 +16,10 @@ This event is cancelable and may bubble up to the {{domxref("Document")}} and {{ Use the event name in methods like {{domxref("EventTarget.addEventListener", "addEventListener()")}}, or set an event handler property. -```js -addEventListener("dragend", (event) => {}); +```js-nolint +addEventListener("dragend", (event) => { }) -ondragend = (event) => {}; +ondragend = (event) => { } ``` ## Event type diff --git a/files/en-us/web/api/htmlelement/dragenter_event/index.md b/files/en-us/web/api/htmlelement/dragenter_event/index.md index 623a2f06d25e8a1..3a7cf5c284693ab 100644 --- a/files/en-us/web/api/htmlelement/dragenter_event/index.md +++ b/files/en-us/web/api/htmlelement/dragenter_event/index.md @@ -16,10 +16,10 @@ This event is cancelable and may bubble up to the {{domxref("Document")}} and {{ Use the event name in methods like {{domxref("EventTarget.addEventListener", "addEventListener()")}}, or set an event handler property. -```js -addEventListener("dragenter", (event) => {}); +```js-nolint +addEventListener("dragenter", (event) => { }) -ondragenter = (event) => {}; +ondragenter = (event) => { } ``` ## Event type diff --git a/files/en-us/web/api/htmlelement/draggable/index.md b/files/en-us/web/api/htmlelement/draggable/index.md index 77805ded93645ba..08fddcf71b5fb7a 100644 --- a/files/en-us/web/api/htmlelement/draggable/index.md +++ b/files/en-us/web/api/htmlelement/draggable/index.md @@ -10,7 +10,7 @@ browser-compat: api.HTMLElement.draggable The **`draggable`** property of the {{domxref("HTMLElement")}} interface gets and sets a {{jsxref("Boolean")}} primitive indicating if the element is draggable. -It reflects the value of the [`draggable`](/en-US/docs/Web/HTML/Global_attributes/draggable) HTML global attribute. +It reflects the value of the [`draggable`](/en-US/docs/Web/HTML/Reference/Global_attributes/draggable) HTML global attribute. ## Value @@ -25,14 +25,10 @@ const draggableElement = document.querySelector(".draggable-element"); const notDraggableElement = document.querySelector(".not-draggable-element"); // enable the target element's ability to drag -if (!draggableElement.draggable) { - draggableElement.draggable = true; -} +draggableElement.draggable = true; // disable the target element's ability to drag -if (notDraggableElement.draggable) { - notDraggableElement.draggable = false; -} +notDraggableElement.draggable = false; ``` ## Specifications @@ -45,5 +41,5 @@ if (notDraggableElement.draggable) { ## See also -- [`draggable`](/en-US/docs/Web/HTML/Global_attributes/draggable) HTML global attribute +- [`draggable`](/en-US/docs/Web/HTML/Reference/Global_attributes/draggable) HTML global attribute - [HTML Drag and Drop API](/en-US/docs/Web/API/HTML_Drag_and_Drop_API) overview diff --git a/files/en-us/web/api/htmlelement/dragleave_event/index.md b/files/en-us/web/api/htmlelement/dragleave_event/index.md index 5eca9959052908e..cab928d31509d48 100644 --- a/files/en-us/web/api/htmlelement/dragleave_event/index.md +++ b/files/en-us/web/api/htmlelement/dragleave_event/index.md @@ -16,10 +16,10 @@ This event is not cancelable and may bubble up to the {{domxref("Document")}} an Use the event name in methods like {{domxref("EventTarget.addEventListener", "addEventListener()")}}, or set an event handler property. -```js -addEventListener("dragleave", (event) => {}); +```js-nolint +addEventListener("dragleave", (event) => { }) -ondragleave = (event) => {}; +ondragleave = (event) => { } ``` ## Event type diff --git a/files/en-us/web/api/htmlelement/dragover_event/index.md b/files/en-us/web/api/htmlelement/dragover_event/index.md index ed5f3229ee6118d..03a4536038cda8a 100644 --- a/files/en-us/web/api/htmlelement/dragover_event/index.md +++ b/files/en-us/web/api/htmlelement/dragover_event/index.md @@ -16,10 +16,10 @@ This event is cancelable and may bubble up to the {{domxref("Document")}} and {{ Use the event name in methods like {{domxref("EventTarget.addEventListener", "addEventListener()")}}, or set an event handler property. -```js -addEventListener("dragover", (event) => {}); +```js-nolint +addEventListener("dragover", (event) => { }) -ondragover = (event) => {}; +ondragover = (event) => { } ``` ## Event type diff --git a/files/en-us/web/api/htmlelement/dragstart_event/index.md b/files/en-us/web/api/htmlelement/dragstart_event/index.md index 9359bcf01945b50..20bc3510f34787e 100644 --- a/files/en-us/web/api/htmlelement/dragstart_event/index.md +++ b/files/en-us/web/api/htmlelement/dragstart_event/index.md @@ -16,10 +16,10 @@ This event is cancelable and may bubble up to the {{domxref("Document")}} and {{ Use the event name in methods like {{domxref("EventTarget.addEventListener", "addEventListener()")}}, or set an event handler property. -```js -addEventListener("dragstart", (event) => {}); +```js-nolint +addEventListener("dragstart", (event) => { }) -ondragstart = (event) => {}; +ondragstart = (event) => { } ``` ## Event type diff --git a/files/en-us/web/api/htmlelement/drop_event/index.md b/files/en-us/web/api/htmlelement/drop_event/index.md index fca5b17fd4718d4..ce6edb371723e21 100644 --- a/files/en-us/web/api/htmlelement/drop_event/index.md +++ b/files/en-us/web/api/htmlelement/drop_event/index.md @@ -16,10 +16,10 @@ This event is cancelable and may bubble up to the {{domxref("Document")}} and {{ Use the event name in methods like {{domxref("EventTarget.addEventListener", "addEventListener()")}}, or set an event handler property. -```js -addEventListener("drop", (event) => {}); +```js-nolint +addEventListener("drop", (event) => { }) -ondrop = (event) => {}; +ondrop = (event) => { } ``` ## Event type diff --git a/files/en-us/web/api/htmlelement/editcontext/index.md b/files/en-us/web/api/htmlelement/editcontext/index.md index 871b5bb51b693e9..27f6bb717445593 100644 --- a/files/en-us/web/api/htmlelement/editcontext/index.md +++ b/files/en-us/web/api/htmlelement/editcontext/index.md @@ -18,9 +18,9 @@ The {{domxref("EditContext API", "", "", "nocode")}} can be used to build rich t Setting the `editContext` property only works on certain types of elements: -- One of these HTML elements: [`<article>`](/en-US/docs/Web/HTML/Element/article), [`<aside>`](/en-US/docs/Web/HTML/Element/aside), [`<blockquote>`](/en-US/docs/Web/HTML/Element/blockquote), [`<body>`](/en-US/docs/Web/HTML/Element/body), [`<div>`](/en-US/docs/Web/HTML/Element/div), [`<footer>`](/en-US/docs/Web/HTML/Element/footer), [`<h1>`](/en-US/docs/Web/HTML/Element/Heading_Elements), [`<h2>`](/en-US/docs/Web/HTML/Element/Heading_Elements), [`<h3>`](/en-US/docs/Web/HTML/Element/Heading_Elements), [`<h4>`](/en-US/docs/Web/HTML/Element/Heading_Elements), [`<h5>`](/en-US/docs/Web/HTML/Element/Heading_Elements), [`<h6>`](/en-US/docs/Web/HTML/Element/Heading_Elements), [`<header>`](/en-US/docs/Web/HTML/Element/header), [`<main>`](/en-US/docs/Web/HTML/Element/main), [`<nav>`](/en-US/docs/Web/HTML/Element/nav), [`<p>`](/en-US/docs/Web/HTML/Element/p), [`<section>`](/en-US/docs/Web/HTML/Element/section), or [`<span>`](/en-US/docs/Web/HTML/Element/span). +- One of these HTML elements: [`<article>`](/en-US/docs/Web/HTML/Reference/Elements/article), [`<aside>`](/en-US/docs/Web/HTML/Reference/Elements/aside), [`<blockquote>`](/en-US/docs/Web/HTML/Reference/Elements/blockquote), [`<body>`](/en-US/docs/Web/HTML/Reference/Elements/body), [`<div>`](/en-US/docs/Web/HTML/Reference/Elements/div), [`<footer>`](/en-US/docs/Web/HTML/Reference/Elements/footer), [`<h1>`](/en-US/docs/Web/HTML/Reference/Elements/Heading_Elements), [`<h2>`](/en-US/docs/Web/HTML/Reference/Elements/Heading_Elements), [`<h3>`](/en-US/docs/Web/HTML/Reference/Elements/Heading_Elements), [`<h4>`](/en-US/docs/Web/HTML/Reference/Elements/Heading_Elements), [`<h5>`](/en-US/docs/Web/HTML/Reference/Elements/Heading_Elements), [`<h6>`](/en-US/docs/Web/HTML/Reference/Elements/Heading_Elements), [`<header>`](/en-US/docs/Web/HTML/Reference/Elements/header), [`<main>`](/en-US/docs/Web/HTML/Reference/Elements/main), [`<nav>`](/en-US/docs/Web/HTML/Reference/Elements/nav), [`<p>`](/en-US/docs/Web/HTML/Reference/Elements/p), [`<section>`](/en-US/docs/Web/HTML/Reference/Elements/section), or [`<span>`](/en-US/docs/Web/HTML/Reference/Elements/span). - A valid [custom element](/en-US/docs/Web/API/Web_components/Using_custom_elements). -- A [`<canvas>`](/en-US/docs/Web/HTML/Element/canvas) element. +- A [`<canvas>`](/en-US/docs/Web/HTML/Reference/Elements/canvas) element. If you try to set the `editContext` property on an element that is not one of the above, a `NotSupportedError` {{domxref("DOMException")}} is thrown. diff --git a/files/en-us/web/api/htmlelement/enterkeyhint/index.md b/files/en-us/web/api/htmlelement/enterkeyhint/index.md index 292458fd55f025b..ec5ad305e09d056 100644 --- a/files/en-us/web/api/htmlelement/enterkeyhint/index.md +++ b/files/en-us/web/api/htmlelement/enterkeyhint/index.md @@ -10,7 +10,7 @@ browser-compat: api.HTMLElement.enterKeyHint The **`enterKeyHint`** property is an enumerated property defining what action label (or icon) to present for the enter key on virtual keyboards. -It reflects the [`enterkeyhint`](/en-US/docs/Web/HTML/Global_attributes/enterkeyhint) +It reflects the [`enterkeyhint`](/en-US/docs/Web/HTML/Reference/Global_attributes/enterkeyhint) HTML global attribute and is an enumerated property, only accepting the following values as a string: @@ -46,4 +46,4 @@ search.enterKeyHint = "search"; ## See also -- [`enterkeyhint`](/en-US/docs/Web/HTML/Global_attributes/enterkeyhint) HTML global attribute +- [`enterkeyhint`](/en-US/docs/Web/HTML/Reference/Global_attributes/enterkeyhint) HTML global attribute diff --git a/files/en-us/web/api/htmlelement/error_event/index.md b/files/en-us/web/api/htmlelement/error_event/index.md index 6f86984f96b0fc6..4a40a85328db11c 100644 --- a/files/en-us/web/api/htmlelement/error_event/index.md +++ b/files/en-us/web/api/htmlelement/error_event/index.md @@ -16,10 +16,10 @@ This event is not cancelable and does not bubble. Use the event name in methods like {{domxref("EventTarget.addEventListener", "addEventListener()")}}, or set an event handler property. -```js -addEventListener("error", (event) => {}); +```js-nolint +addEventListener("error", (event) => { }) -onerror = (event) => {}; +onerror = (event) => { } ``` ## Event type diff --git a/files/en-us/web/api/htmlelement/focus/index.md b/files/en-us/web/api/htmlelement/focus/index.md index 37eb390650b8305..1e96e69549e2744 100644 --- a/files/en-us/web/api/htmlelement/focus/index.md +++ b/files/en-us/web/api/htmlelement/focus/index.md @@ -161,7 +161,7 @@ Selecting the second button set's the focus, but scrolling is disabled. ## Notes - If you call `HTMLElement.focus()` from a mousedown event handler, you must call `event.preventDefault()` to keep the focus from leaving the `HTMLElement` -- Behavior of the focus in relation to different HTML features like [`tabindex`](/en-US/docs/Web/HTML/Global_attributes/tabindex) or {{Glossary("shadow tree", "shadow dom")}}, which previously remained under-specified, were updated in October 2019. +- Behavior of the focus in relation to different HTML features like [`tabindex`](/en-US/docs/Web/HTML/Reference/Global_attributes/tabindex) or {{Glossary("shadow tree", "shadow dom")}}, which previously remained under-specified, were updated in October 2019. See the [WHATWG blog](https://blog.whatwg.org/focusing-on-focus) for more information. ## Browser compatibility diff --git a/files/en-us/web/api/htmlelement/hidden/index.md b/files/en-us/web/api/htmlelement/hidden/index.md index 9afb29b907bada2..141c28e798519cc 100644 --- a/files/en-us/web/api/htmlelement/hidden/index.md +++ b/files/en-us/web/api/htmlelement/hidden/index.md @@ -8,7 +8,7 @@ browser-compat: api.HTMLElement.hidden {{ APIRef("HTML DOM") }} -The {{domxref("HTMLElement")}} property **`hidden`** reflects the value of the element's [`hidden`](/en-US/docs/Web/HTML/Global_attributes/hidden) attribute. +The {{domxref("HTMLElement")}} property **`hidden`** reflects the value of the element's [`hidden`](/en-US/docs/Web/HTML/Reference/Global_attributes/hidden) attribute. ## Value @@ -21,7 +21,7 @@ This attribute may have one of three values: - `"until-found"` - : The element is _hidden until found_, meaning that it is hidden but will be revealed if found through in page search or reached through fragment navigation. -For details on the usage of this attribute, see the page for the [`hidden`](/en-US/docs/Web/HTML/Global_attributes/hidden) HTML attribute that this property reflects. +For details on the usage of this attribute, see the page for the [`hidden`](/en-US/docs/Web/HTML/Reference/Global_attributes/hidden) HTML attribute that this property reflects. ## Examples @@ -106,5 +106,5 @@ document.getElementById("okButton").addEventListener( ## See also -- [hidden](/en-US/docs/Web/HTML/Global_attributes/hidden) attribute +- [hidden](/en-US/docs/Web/HTML/Reference/Global_attributes/hidden) attribute - {{cssxref("display")}} diff --git a/files/en-us/web/api/htmlelement/hidepopover/index.md b/files/en-us/web/api/htmlelement/hidepopover/index.md index 01f7f15fa5ed749..4f904e209036df0 100644 --- a/files/en-us/web/api/htmlelement/hidepopover/index.md +++ b/files/en-us/web/api/htmlelement/hidepopover/index.md @@ -8,9 +8,9 @@ browser-compat: api.HTMLElement.hidePopover {{APIRef("Popover API")}} -The **`hidePopover()`** method of the {{domxref("HTMLElement")}} interface hides a [popover](/en-US/docs/Web/API/Popover_API) element (i.e. one that has a valid [`popover`](/en-US/docs/Web/HTML/Global_attributes/popover) attribute) by removing it from the {{glossary("top layer")}} and styling it with `display: none`. +The **`hidePopover()`** method of the {{domxref("HTMLElement")}} interface hides a [popover](/en-US/docs/Web/API/Popover_API) element (i.e., one that has a valid [`popover`](/en-US/docs/Web/HTML/Reference/Global_attributes/popover) attribute) by removing it from the {{glossary("top layer")}} and styling it with `display: none`. -When `hidePopover()` is called on a showing element with the [`popover`](/en-US/docs/Web/HTML/Global_attributes/popover) attribute, a {{domxref("HTMLElement/beforetoggle_event", "beforetoggle")}} event will be fired, followed by the popover being hidden, and then the {{domxref("HTMLElement/toggle_event", "toggle")}} event firing. If the element is already hidden, an error is thrown. +When `hidePopover()` is called on a showing element with the [`popover`](/en-US/docs/Web/HTML/Reference/Global_attributes/popover) attribute, a {{domxref("HTMLElement/beforetoggle_event", "beforetoggle")}} event will be fired, followed by the popover being hidden, and then the {{domxref("HTMLElement/toggle_event", "toggle")}} event firing. If the element is already hidden, an error is thrown. ## Syntax diff --git a/files/en-us/web/api/htmlelement/index.md b/files/en-us/web/api/htmlelement/index.md index ec307fea2fd3d83..344fa4ca9119601 100644 --- a/files/en-us/web/api/htmlelement/index.md +++ b/files/en-us/web/api/htmlelement/index.md @@ -22,18 +22,18 @@ _Also inherits properties from its parent, {{DOMxRef("Element")}}._ - {{DOMxRef("HTMLElement.anchorElement")}} {{ReadOnlyInline}}&nbsp;{{non-standard_inline}} {{experimental_inline}} - : Returns a reference to the element's anchor element, or `null` if it doesn't have one. - {{DOMxRef("HTMLElement.attributeStyleMap")}} {{ReadOnlyInline}} - - : A {{DOMxRef("StylePropertyMap")}} representing the declarations of the element's [`style`](/en-US/docs/Web/HTML/Global_attributes/style) attribute. + - : A {{DOMxRef("StylePropertyMap")}} representing the declarations of the element's [`style`](/en-US/docs/Web/HTML/Reference/Global_attributes/style) attribute. - {{domxref("HTMLElement.autocapitalize")}} - : A string that represents the element's capitalization behavior for user input. Valid values are: `none`, `off`, `on`, `characters`, `words`, `sentences`. - {{domxref("HTMLElement.autofocus")}} - - : A boolean value reflecting the [`autofocus`](/en-US/docs/Web/HTML/Element/select#autofocus) HTML global attribute, which indicates whether the control should be focused when the page loads, or when dialog or popover become shown if specified in an element inside {{htmlelement("dialog")}} elements or elements whose popover attribute is set. + - : A boolean value reflecting the [`autofocus`](/en-US/docs/Web/HTML/Reference/Elements/select#autofocus) HTML global attribute, which indicates whether the control should be focused when the page loads, or when dialog or popover become shown if specified in an element inside {{htmlelement("dialog")}} elements or elements whose popover attribute is set. - {{domxref("HTMLElement.autocorrect")}} - : A boolean that represents whether or not text input by a user should be automatically corrected. - This reflects the [`autocorrect`](/en-US/docs/Web/HTML/Global_attributes/autocorrect) HTML global attribute. + This reflects the [`autocorrect`](/en-US/docs/Web/HTML/Reference/Global_attributes/autocorrect) HTML global attribute. - {{DOMxRef("HTMLElement.contentEditable")}} - : A string, where a value of `true` means the element is editable and a value of `false` means it isn't. - {{DOMxRef("HTMLElement.dataset")}} {{ReadOnlyInline}} - - : Returns a {{DOMxRef("DOMStringMap")}} with which script can read and write the element's [custom data attributes](/en-US/docs/Learn_web_development/Howto/Solve_HTML_problems/Use_data_attributes) (`data-*`). + - : Returns a {{DOMxRef("DOMStringMap")}} with which script can read and write the element's [custom data attributes](/en-US/docs/Web/HTML/How_to/Use_data_attributes) (`data-*`). - {{DOMxRef("HTMLElement.dir")}} - : A string, reflecting the `dir` global attribute, representing the directionality of the element. Possible values are `"ltr"`, `"rtl"`, and `"auto"`. - {{DOMxRef("HTMLElement.draggable")}} @@ -43,7 +43,7 @@ _Also inherits properties from its parent, {{DOMxRef("Element")}}._ - {{DOMxRef("HTMLElement.enterKeyHint")}} - : A string defining what action label (or icon) to present for the enter key on virtual keyboards. - {{DOMxRef("HTMLElement.hidden")}} - - : A string or boolean value reflecting the value of the element's [`hidden`](/en-US/docs/Web/HTML/Global_attributes/hidden) attribute. + - : A string or boolean value reflecting the value of the element's [`hidden`](/en-US/docs/Web/HTML/Reference/Global_attributes/hidden) attribute. - {{DOMxRef("HTMLElement.inert")}} - : A boolean value indicating whether the user agent must act as though the given node is absent for the purposes of user interaction events, in-page text searches ("find in page"), and text selection. - {{DOMxRef("HTMLElement.innerText")}} @@ -51,7 +51,7 @@ _Also inherits properties from its parent, {{DOMxRef("Element")}}._ As a getter, it approximates the text the user would get if they highlighted the contents of the element with the cursor and then copied it to the clipboard. As a setter, it replaces the content inside the selected element, converting any line breaks into {{HTMLElement("br")}} elements. - {{DOMxRef("HTMLElement.inputMode")}} - - : A string value reflecting the value of the element's [`inputmode`](/en-US/docs/Web/HTML/Global_attributes/inputmode) attribute. + - : A string value reflecting the value of the element's [`inputmode`](/en-US/docs/Web/HTML/Reference/Global_attributes/inputmode) attribute. - {{DOMxRef("HTMLElement.isContentEditable")}} {{ReadOnlyInline}} - : Returns a boolean value indicating whether or not the content of the element can be edited. - {{DOMxRef("HTMLElement.lang")}} @@ -73,11 +73,11 @@ _Also inherits properties from its parent, {{DOMxRef("Element")}}._ As a getter, it is the same as {{DOMxRef("HTMLElement.innerText")}} (it represents the rendered text content of an element and its descendants). As a setter, it replaces the selected node and its contents with the given value, converting any line breaks into {{HTMLElement("br")}} elements. - {{domxref("HTMLElement.popover")}} - - : Gets and sets an element's popover state via JavaScript (`"auto"`, `"hint"`, or `"manual"`), and can be used for feature detection. Reflects the value of the [`popover`](/en-US/docs/Web/HTML/Global_attributes/popover) global HTML attribute. + - : Gets and sets an element's popover state via JavaScript (`"auto"`, `"hint"`, or `"manual"`), and can be used for feature detection. Reflects the value of the [`popover`](/en-US/docs/Web/HTML/Reference/Global_attributes/popover) global HTML attribute. - {{DOMxRef("HTMLElement.spellcheck")}} - - : A boolean value that controls the [spell-checking](/en-US/docs/Web/HTML/Global_attributes/spellcheck) hint. It is available on all HTML elements, though it doesn't affect all of them. + - : A boolean value that controls the [spell-checking](/en-US/docs/Web/HTML/Reference/Global_attributes/spellcheck) hint. It is available on all HTML elements, though it doesn't affect all of them. - {{DOMxRef("HTMLElement.style")}} - - : A {{DOMxRef("CSSStyleDeclaration")}} representing the declarations of the element's [`style`](/en-US/docs/Web/HTML/Global_attributes/style) attribute. + - : A {{DOMxRef("CSSStyleDeclaration")}} representing the declarations of the element's [`style`](/en-US/docs/Web/HTML/Reference/Global_attributes/style) attribute. - {{DOMxRef("HTMLElement.tabIndex")}} - : A `long` representing the position of the element in the tabbing order. - {{DOMxRef("HTMLElement.title")}} @@ -85,7 +85,7 @@ _Also inherits properties from its parent, {{DOMxRef("Element")}}._ - {{DOMxRef("HTMLElement.translate")}} - : A boolean value representing the translation. - {{DOMxRef("HTMLElement.virtualKeyboardPolicy")}} {{Experimental_Inline}} - - : A string indicating the on-screen virtual keyboard behavior on devices such as tablets, mobile phones, or other devices where a hardware keyboard may not be available, if the element's content is editable (for example, it is an {{htmlelement("input")}} or {{htmlelement("textarea")}} element, or an element with the [`contenteditable`](/en-US/docs/Web/HTML/Global_attributes/contenteditable) attribute set). + - : A string indicating the on-screen virtual keyboard behavior on devices such as tablets, mobile phones, or other devices where a hardware keyboard may not be available, if the element's content is editable (for example, it is an {{htmlelement("input")}} or {{htmlelement("textarea")}} element, or an element with the [`contenteditable`](/en-US/docs/Web/HTML/Reference/Global_attributes/contenteditable) attribute set). - {{DOMxRef("HTMLElement.writingSuggestions")}} - : A string indicating if browser-provided writing suggestions should be enabled under the scope of the element or not. @@ -114,24 +114,15 @@ Listen to these events using {{domxref("EventTarget.addEventListener", "addEvent _Also, inherits events from its parent, {{DOMxRef("Element")}}._ -- {{DOMxRef("HTMLElement/cancel_event", "cancel")}} - - : Fired for {{HTMLElement("input")}} and {{HTMLElement("dialog")}} elements when the user cancels the currently open dialog by closing it with the <kbd>Esc</kbd> key. - {{DOMxRef("HTMLElement/change_event", "change")}} - : Fired when the `value` of an {{HTMLElement("input")}}, {{HTMLElement("select")}}, or {{HTMLElement("textarea")}} element has been changed and committed by the user. Unlike the {{domxref("Element/input_event", "input")}} event, the `change` event is not necessarily fired for each alteration to an element's `value`. +- {{domxref("HTMLElement/command_event", "command")}} + - : Fires on an element that is controlled via a {{domxref("HTMLButtonElement", "button")}} with valid {{domxref("HTMLButtonElement.commandForElement", "commandForElement")}} and {{domxref("HTMLButtonElement.command", "command")}} values, whenever the button is interacted with (e.g., it is clicked). - {{DOMxRef("HTMLElement/error_event", "error")}} - : Fired when a resource failed to load, or can't be used. - {{DOMxRef("HTMLElement/load_event", "load")}} - : Fires for elements containing a resource when the resource has successfully loaded. -### Clipboard events - -- {{DOMxRef("HTMLElement/copy_event", "copy")}} - - : Fired when the user initiates a copy action through the browser's user interface. -- {{DOMxRef("HTMLElement/cut_event", "cut")}} - - : Fired when the user initiates a cut action through the browser's user interface. -- {{DOMxRef("HTMLElement/paste_event", "paste")}} - - : Fired when the user initiates a paste action through the browser's user interface. - ### Drag & drop events - {{DOMxRef("HTMLElement/drag_event", "drag")}} diff --git a/files/en-us/web/api/htmlelement/inert/index.md b/files/en-us/web/api/htmlelement/inert/index.md index 9cbc1215f16e879..119fae9cdff7db2 100644 --- a/files/en-us/web/api/htmlelement/inert/index.md +++ b/files/en-us/web/api/htmlelement/inert/index.md @@ -8,7 +8,7 @@ browser-compat: api.HTMLElement.inert {{ APIRef("HTML DOM") }} -The {{domxref("HTMLElement")}} property **`inert`** reflects the value of the element's [`inert`](/en-US/docs/Web/HTML/Global_attributes/inert) attribute. It is a boolean value that, when present, makes the browser "ignore" user input events for the element, including focus events and events from assistive technologies. The browser may also ignore page search and text selection in the element. This can be useful when building UIs such as modals where you would want to "trap" the focus inside the modal when it's visible. +The {{domxref("HTMLElement")}} property **`inert`** reflects the value of the element's [`inert`](/en-US/docs/Web/HTML/Reference/Global_attributes/inert) attribute. It is a boolean value that, when present, makes the browser "ignore" user input events for the element, including focus events and events from assistive technologies. The browser may also ignore page search and text selection in the element. This can be useful when building UIs such as modals where you would want to "trap" the focus inside the modal when it's visible. Note that if the `inert` attribute is unspecified, the element itself may still inherit inertness from its parent. However, that inherited inertness is not reflected by this property's value. @@ -54,7 +54,7 @@ A Boolean which is `true` if the element is inert; otherwise, the value is `fals ## See also -- [Global attribute: `inert`](/en-US/docs/Web/HTML/Global_attributes/inert) +- [Global attribute: `inert`](/en-US/docs/Web/HTML/Reference/Global_attributes/inert) - {{HTMLElement("dialog")}} - [Inert Polyfill](https://github.com/WICG/inert) - {{domxref("HTMLInputElement.disabled", "disabled")}} diff --git a/files/en-us/web/api/htmlelement/inputmode/index.md b/files/en-us/web/api/htmlelement/inputmode/index.md index 7484f9faac9f35d..d9442c7faa22626 100644 --- a/files/en-us/web/api/htmlelement/inputmode/index.md +++ b/files/en-us/web/api/htmlelement/inputmode/index.md @@ -8,11 +8,11 @@ browser-compat: api.HTMLElement.inputMode {{ APIRef("HTML DOM") }} -The {{domxref("HTMLElement")}} property **`inputMode`** reflects the value of the element's [`inputmode`](/en-US/docs/Web/HTML/Global_attributes/inputmode) attribute. +The {{domxref("HTMLElement")}} property **`inputMode`** reflects the value of the element's [`inputmode`](/en-US/docs/Web/HTML/Reference/Global_attributes/inputmode) attribute. It provides a hint about the type of data that might be entered by the user while editing the element or its contents. This allows the browser to display an appropriate virtual keyboard. -It is used primarily on {{HTMLElement("input")}} elements, but is usable on any element in [`contenteditable`](/en-US/docs/Web/HTML/Global_attributes/contenteditable) mode. +It is used primarily on {{HTMLElement("input")}} elements, but is usable on any element in [`contenteditable`](/en-US/docs/Web/HTML/Reference/Global_attributes/contenteditable) mode. ## Value @@ -39,9 +39,7 @@ This attribute may have one of the following values: - : A keypad optimized for entering URLs. This may have the <kbd>/</kbd> key more prominent, for example. -For details on the usage of this attribute, see the page for the [`inputmode`](/en-US/docs/Web/HTML/Global_attributes/inputmode) HTML attribute that this property reflects. - -## Examples +For details on the usage of this attribute, see the page for the [`inputmode`](/en-US/docs/Web/HTML/Reference/Global_attributes/inputmode) HTML attribute that this property reflects. ## Specifications @@ -53,4 +51,4 @@ For details on the usage of this attribute, see the page for the [`inputmode`](/ ## See also -- [inputmode](/en-US/docs/Web/HTML/Global_attributes/inputmode) attribute +- [inputmode](/en-US/docs/Web/HTML/Reference/Global_attributes/inputmode) attribute diff --git a/files/en-us/web/api/htmlelement/iscontenteditable/index.md b/files/en-us/web/api/htmlelement/iscontenteditable/index.md index dca29374fcff4ff..640cf6240b84fdd 100644 --- a/files/en-us/web/api/htmlelement/iscontenteditable/index.md +++ b/files/en-us/web/api/htmlelement/iscontenteditable/index.md @@ -37,8 +37,8 @@ const secondParagraph = document.getElementById("secondParagraph"); const infoText1 = document.getElementById("infoText1"); const infoText2 = document.getElementById("infoText2"); -infoText1.textContent += " " + firstParagraph.isContentEditable; -infoText2.textContent += " " + secondParagraph.isContentEditable; +infoText1.textContent += ` ${firstParagraph.isContentEditable}`; +infoText2.textContent += ` ${secondParagraph.isContentEditable}`; ``` ### Result @@ -56,4 +56,4 @@ infoText2.textContent += " " + secondParagraph.isContentEditable; ## See also - {{domxref("HTMLElement/contentEditable")}} -- The [`contenteditable`](/en-US/docs/Web/HTML/Global_attributes/contenteditable) global attribute. +- The [`contenteditable`](/en-US/docs/Web/HTML/Reference/Global_attributes/contenteditable) global attribute. diff --git a/files/en-us/web/api/htmlelement/lang/index.md b/files/en-us/web/api/htmlelement/lang/index.md index 78059142c268e97..c30aaf9f5ed7c03 100644 --- a/files/en-us/web/api/htmlelement/lang/index.md +++ b/files/en-us/web/api/htmlelement/lang/index.md @@ -8,7 +8,7 @@ browser-compat: api.HTMLElement.lang {{ APIRef("HTML DOM") }} -The **`lang`** property of the {{domxref("HTMLElement")}} interface indicates the base language of an element's attribute values and text content, in the form of a {{RFC(5646, "BCP 47 language identifier tag")}}. It reflects the element's [`lang`](/en-US/docs/Web/HTML/Global_attributes/lang) attribute; the `xml:lang` attribute does not affect this property. +The **`lang`** property of the {{domxref("HTMLElement")}} interface indicates the base language of an element's attribute values and text content, in the form of a {{RFC(5646, "BCP 47 language identifier tag")}}. It reflects the element's [`lang`](/en-US/docs/Web/HTML/Reference/Global_attributes/lang) attribute; the `xml:lang` attribute does not affect this property. Note that if the `lang` attribute is unspecified, the element itself may still inherit the language from its parent. However, that inherited language is not reflected by this property's value. diff --git a/files/en-us/web/api/htmlelement/load_event/favicon144.png b/files/en-us/web/api/htmlelement/load_event/favicon144.png deleted file mode 100644 index e30b574b6540f52..000000000000000 Binary files a/files/en-us/web/api/htmlelement/load_event/favicon144.png and /dev/null differ diff --git a/files/en-us/web/api/htmlelement/load_event/index.md b/files/en-us/web/api/htmlelement/load_event/index.md index f12d5b68bedf690..6f3ad4457c977b9 100644 --- a/files/en-us/web/api/htmlelement/load_event/index.md +++ b/files/en-us/web/api/htmlelement/load_event/index.md @@ -19,10 +19,10 @@ This event is not cancelable and does not bubble. Use the event name in methods like {{domxref("EventTarget.addEventListener", "addEventListener()")}}, or set an event handler property. -```js -elt.addEventListener("load", (event) => { ... }); -// or -elt.onload = (event) => { ... }; +```js-nolint +addEventListener("load", (event) => { }) + +onload = (event) => { } ``` ## Event type @@ -36,7 +36,11 @@ This example prints to the screen whenever the {{HtmlElement("img")}} element su ### HTML ```html -<img id="image" src="favicon144.png" alt="MDN logo" width="72" /> +<img + id="image" + src="/shared-assets/images/examples/favicon144.png" + alt="MDN logo" + width="72" /> <div><button onclick="reload()">Reload</button></div> ``` @@ -50,7 +54,7 @@ image.onload = () => { }; function reload() { - image.src = "favicon144.png"; + image.src = "/shared-assets/images/examples/favicon144.png"; } ``` diff --git a/files/en-us/web/api/htmlelement/nonce/index.md b/files/en-us/web/api/htmlelement/nonce/index.md index 398176cb5a341a5..9e96f337f87c6b2 100644 --- a/files/en-us/web/api/htmlelement/nonce/index.md +++ b/files/en-us/web/api/htmlelement/nonce/index.md @@ -8,7 +8,7 @@ browser-compat: api.HTMLElement.nonce {{APIRef("HTML DOM")}} -The **`nonce`** property of the {{DOMxRef("HTMLElement")}} interface returns the cryptographic number used once that is used by [Content Security Policy](/en-US/docs/Web/HTTP/CSP) to determine whether a given fetch will be allowed to proceed. +The **`nonce`** property of the {{DOMxRef("HTMLElement")}} interface returns the cryptographic number used once that is used by [Content Security Policy](/en-US/docs/Web/HTTP/Guides/CSP) to determine whether a given fetch will be allowed to proceed. In later implementations, elements only expose their `nonce` attribute to scripts (and not to side-channels like CSS attribute selectors). @@ -42,6 +42,6 @@ script[nonce~="whatever"] { ## See also -- [`nonce` global attribute](/en-US/docs/Web/HTML/Global_attributes/nonce) -- [Content Security Policy](/en-US/docs/Web/HTTP/CSP) +- [`nonce` global attribute](/en-US/docs/Web/HTML/Reference/Global_attributes/nonce) +- [Content Security Policy](/en-US/docs/Web/HTTP/Guides/CSP) - CSP: {{CSP("script-src")}} diff --git a/files/en-us/web/api/htmlelement/offsetheight/index.md b/files/en-us/web/api/htmlelement/offsetheight/index.md index edd915d2695d250..f05a9e7b5e48fdf 100644 --- a/files/en-us/web/api/htmlelement/offsetheight/index.md +++ b/files/en-us/web/api/htmlelement/offsetheight/index.md @@ -8,38 +8,21 @@ browser-compat: api.HTMLElement.offsetHeight {{ APIRef("HTML DOM") }} -The **`HTMLElement.offsetHeight`** read-only property returns -the height of an element, including vertical padding and borders, as an integer. +The **`offsetHeight`** read-only property of the {{domxref("HTMLElement")}} interface returns the height of an element, including vertical padding and borders, as an integer. -Typically, `offsetHeight` is a measurement in pixels of the element's CSS -height, including any borders, padding, and horizontal scrollbars (if rendered). It does -not include the height of pseudo-elements such as `::before` or -`::after`. For the document body object, the measurement includes total -linear content height instead of the element's CSS height. Floated elements extending -below other linear content are ignored. +Typically, `offsetHeight` is a measurement in pixels of the element's CSS height, including any borders, padding, and horizontal scrollbars (if rendered). It does not include the height of pseudo-elements such as `::before` or `::after`. For the document body object, the measurement includes total linear content height instead of the element's CSS height. Floated elements extending below other linear content are ignored. -If the element is hidden (for example, by setting `style.display` on the -element or one of its ancestors to `"none"`), then `0` is -returned. - -> [!NOTE] -> This property will round the value to an integer. If you need a fractional value, use -> {{ domxref("element.getBoundingClientRect()") }}. +If the element is hidden (for example, by setting `style.display` on the element or one of its ancestors to `"none"`), then `0` is returned. ## Value -A number. +An integer. ## Examples ![An example element with large padding, border and margin. `offsetHeight` is the layout height of the element including its padding and border, and excluding its margin.](dimensions-offset.png) -The example image above shows a scrollbar and an `offsetHeight` which fits -on the window. However, non-scrollable elements may have large `offsetHeight` -values, much larger than the visible content. These elements are typically contained -within scrollable elements; consequently, these non-scrollable elements may be -completely or partly invisible, depending on the `scrollTop` setting of the -scrollable container. +The example image above shows a scrollbar and an `offsetHeight` which fits on the window. However, non-scrollable elements may have large `offsetHeight` values, much larger than the visible content. These elements are typically contained within scrollable elements; consequently, these non-scrollable elements may be completely or partly invisible, depending on the `scrollTop` setting of the scrollable container. ## Specifications @@ -51,7 +34,10 @@ scrollable container. ## See also +- [Determining the dimensions of elements](/en-US/docs/Web/API/CSS_Object_Model/Determining_the_dimensions_of_elements) - {{domxref("Element.clientHeight")}} - {{domxref("Element.scrollHeight")}} - {{domxref("HTMLElement.offsetWidth")}} -- [Determining the dimensions of elements](/en-US/docs/Web/API/CSS_Object_Model/Determining_the_dimensions_of_elements) +- {{domxref("HTMLElement.offsetLeft")}} +- {{domxref("HTMLElement.offsetTop")}} +- {{domxref("Element.getBoundingClientRect()")}} diff --git a/files/en-us/web/api/htmlelement/offsetleft/index.md b/files/en-us/web/api/htmlelement/offsetleft/index.md index fe22fd70dbec1c5..765b504000b5963 100644 --- a/files/en-us/web/api/htmlelement/offsetleft/index.md +++ b/files/en-us/web/api/htmlelement/offsetleft/index.md @@ -8,11 +8,11 @@ browser-compat: api.HTMLElement.offsetLeft {{ APIRef("HTML DOM") }} -The **`HTMLElement.offsetLeft`** read-only property returns the number of pixels that the _upper left corner_ of the current element is offset to the left within the {{domxref("HTMLElement.offsetParent")}} node. +The **`offsetLeft`** read-only property of the {{domxref("HTMLElement")}} interface returns the number of pixels that the _upper left corner_ of the current element is offset to the left within the {{domxref("HTMLElement.offsetParent")}} node. For block-level elements, `offsetTop`, `offsetLeft`, `offsetWidth`, and `offsetHeight` describe the border box of an element relative to the `offsetParent`. -However, for inline-level elements (such as **span**) that can wrap from one line to the next, `offsetTop` and `offsetLeft` describe the positions of the _first_ border box (use {{domxref("Element.getClientRects()")}} to get its width and height), while `offsetWidth` and `offsetHeight` describe the dimensions of the _bounding_ border box (use {{domxref("Element.getBoundingClientRect()")}} to get its position). Therefore, a box with the left, top, width and height of `offsetLeft`, `offsetTop`, `offsetWidth` and `offsetHeight` will not be a bounding box for a span with wrapped text. +However, for inline-level elements (such as `<span>`) that can wrap from one line to the next, `offsetTop` and `offsetLeft` describe the positions of the _first_ border box (use {{domxref("Element.getClientRects()")}} to get its width and height), while `offsetWidth` and `offsetHeight` describe the dimensions of the _bounding_ border box (use {{domxref("Element.getBoundingClientRect()")}} to get its position). Therefore, a box with the left, top, width and height of `offsetLeft`, `offsetTop`, `offsetWidth` and `offsetHeight` will not be a bounding box for a span with wrapped text. ## Value @@ -47,10 +47,10 @@ This example shows a 'long' sentence that wraps within a div with a blue border, <script> const box = document.getElementById("box"); const longSpan = document.getElementById("long-span"); - box.style.left = longSpan.offsetLeft + document.body.scrollLeft + "px"; - box.style.top = longSpan.offsetTop + document.body.scrollTop + "px"; - box.style.width = longSpan.offsetWidth + "px"; - box.style.height = longSpan.offsetHeight + "px"; + box.style.left = `${longSpan.offsetLeft}${document.body.scrollLeft}px`; + box.style.top = `${longSpan.offsetTop}${document.body.scrollTop}px`; + box.style.width = `${longSpan.offsetWidth}px`; + box.style.height = `${longSpan.offsetHeight}px`; </script> ``` @@ -64,4 +64,10 @@ This example shows a 'long' sentence that wraps within a div with a blue border, ## See also -- {{domxref("HTMLElement.offsetParent")}}, {{domxref("HTMLElement.offsetTop")}}, {{domxref("HTMLElement.offsetWidth")}}, {{domxref("HTMLElement.offsetHeight")}} +- [Determining the dimensions of elements](/en-US/docs/Web/API/CSS_Object_Model/Determining_the_dimensions_of_elements) +- {{domxref("Element.clientLeft")}} +- {{domxref("Element.scrollLeft")}} +- {{domxref("HTMLElement.offsetHeight")}} +- {{domxref("HTMLElement.offsetWidth")}} +- {{domxref("HTMLElement.offsetTop")}} +- {{domxref("Element.getBoundingClientRect()")}} diff --git a/files/en-us/web/api/htmlelement/offsettop/index.md b/files/en-us/web/api/htmlelement/offsettop/index.md index dce8b0a85048e44..1044e30d3af5310 100644 --- a/files/en-us/web/api/htmlelement/offsettop/index.md +++ b/files/en-us/web/api/htmlelement/offsettop/index.md @@ -8,9 +8,7 @@ browser-compat: api.HTMLElement.offsetTop {{ APIRef("HTML DOM") }} -The **`HTMLElement.offsetTop`** read-only property returns the -distance from the outer border of the current element (including its margin) to the top padding edge of the {{domxref("HTMLelement.offsetParent","offsetParent")}}, the _closest positioned_ -ancestor element. +The **`offsetTop`** read-only property of the {{domxref("HTMLElement")}} interface returns the distance from the outer border of the current element (including its margin) to the top padding edge of the {{domxref("HTMLelement.offsetParent","offsetParent")}}, the _closest positioned_ ancestor element. ## Value @@ -35,3 +33,13 @@ if (topPos > 10) { ## Browser compatibility {{Compat}} + +## See also + +- [Determining the dimensions of elements](/en-US/docs/Web/API/CSS_Object_Model/Determining_the_dimensions_of_elements) +- {{domxref("Element.clientTop")}} +- {{domxref("Element.scrollTop")}} +- {{domxref("HTMLElement.offsetHeight")}} +- {{domxref("HTMLElement.offsetWidth")}} +- {{domxref("HTMLElement.offsetLeft")}} +- {{domxref("Element.getBoundingClientRect()")}} diff --git a/files/en-us/web/api/htmlelement/offsetwidth/index.md b/files/en-us/web/api/htmlelement/offsetwidth/index.md index 243226b73f572a6..9c09a1b3c654247 100644 --- a/files/en-us/web/api/htmlelement/offsetwidth/index.md +++ b/files/en-us/web/api/htmlelement/offsetwidth/index.md @@ -8,25 +8,15 @@ browser-compat: api.HTMLElement.offsetWidth {{ APIRef("HTML DOM") }} -The **`HTMLElement.offsetWidth`** read-only property returns -the layout width of an element as an integer. +The **`offsetWidth`** read-only property of the {{domxref("HTMLElement")}} interface returns the layout width of an element as an integer. -Typically, `offsetWidth` is a measurement in pixels of the element's CSS -width, including any borders, padding, and vertical scrollbars (if rendered). It does -not include the width of pseudo-elements such as `::before` or -`::after`. +Typically, `offsetWidth` is a measurement in pixels of the element's CSS width, including any borders, padding, and vertical scrollbars (if rendered). It does not include the width of pseudo-elements such as `::before` or `::after`. -If the element is hidden (for example, by setting `style.display` on the -element or one of its ancestors to `"none"`), then `0` is -returned. +If the element is hidden (for example, by setting `style.display` on the element or one of its ancestors to `"none"`), then `0` is returned. ## Value -An integer corresponding to the `offsetWidth` pixel value of the element. The `offsetWidth` property is a read-only. - -> [!NOTE] -> This property will round the value to an integer. If you need a fractional value, use -> {{ domxref("element.getBoundingClientRect()") }}. +An integer. ## Examples @@ -42,6 +32,10 @@ An integer corresponding to the `offsetWidth` pixel value of the element. The `o ## See also +- [Determining the dimensions of elements](/en-US/docs/Web/API/CSS_Object_Model/Determining_the_dimensions_of_elements) - {{domxref("Element.clientWidth")}} - {{domxref("Element.scrollWidth")}} -- [Determining the dimensions of elements](/en-US/docs/Web/API/CSS_Object_Model/Determining_the_dimensions_of_elements) +- {{domxref("HTMLElement.offsetHeight")}} +- {{domxref("HTMLElement.offsetLeft")}} +- {{domxref("HTMLElement.offsetTop")}} +- {{domxref("Element.getBoundingClientRect()")}} diff --git a/files/en-us/web/api/htmlelement/paste_event/index.md b/files/en-us/web/api/htmlelement/paste_event/index.md deleted file mode 100644 index 662fdd8f0ce7d02..000000000000000 --- a/files/en-us/web/api/htmlelement/paste_event/index.md +++ /dev/null @@ -1,86 +0,0 @@ ---- -title: "HTMLElement: paste event" -short-title: paste -slug: Web/API/HTMLElement/paste_event -page-type: web-api-event -browser-compat: api.Element.paste_event ---- - -{{ APIRef("HTML DOM") }} - -The **`paste`** event fires when the user initiates a paste action through the browser's user interface. - -## Syntax - -Use the event name in methods like {{domxref("EventTarget.addEventListener", "addEventListener()")}}, or set an event handler property. - -```js -addEventListener("paste", (event) => {}); - -onpaste = (event) => {}; -``` - -## Event type - -A {{domxref("ClipboardEvent")}}. Inherits from {{domxref("Event")}}. - -{{InheritanceDiagram("ClipboardEvent")}} - -## Event properties - -_Also inherits properties from its parent {{domxref("Event")}}_. - -- {{domxref("ClipboardEvent.clipboardData")}} {{ReadOnlyInline}} - - : A {{domxref("DataTransfer")}} object containing the data affected by the user-initiated {{domxref("HTMLElement/cut_event", "cut")}}, {{domxref("HTMLElement/copy_event", "copy")}}, or `paste` operation, along with its MIME type. - -## Example - -This example logs every copy and paste attempt to the {{htmlElement("textarea")}}. - -### HTML - -```html -<h3>Play with this text area:</h3> -<textarea id="editor" rows="3"> -Try copying and pasting text into this field! -</textarea> - -<h3>Log:</h3> -<p id="log"></p> -``` - -### JavaScript - -```js -function logCopy(event) { - log.innerText = `Copied!\n${log.innerText}`; -} - -function logPaste(event) { - log.innerText = `Pasted!\n${log.innerText}`; -} - -const editor = document.getElementById("editor"); -const log = document.getElementById("log"); - -editor.oncopy = logCopy; -editor.onpaste = logPaste; -``` - -### Result - -{{EmbedLiveSample("Example", 700, 300)}} - -## Specifications - -{{Specifications}} - -## Browser compatibility - -{{Compat}} - -## See also - -- Related events - - {{domxref("HTMLElement.copy_event", "copy")}} event - - {{domxref("HTMLElement.cut_event", "cut")}} event diff --git a/files/en-us/web/api/htmlelement/popover/index.md b/files/en-us/web/api/htmlelement/popover/index.md index 4e56933bc33b332..003ae414fecbaab 100644 --- a/files/en-us/web/api/htmlelement/popover/index.md +++ b/files/en-us/web/api/htmlelement/popover/index.md @@ -10,7 +10,7 @@ browser-compat: api.HTMLElement.popover The **`popover`** property of the {{domxref("HTMLElement")}} interface gets and sets an element's popover state via JavaScript (`"auto"`, `"hint"`, or `"manual"`), and can be used for feature detection. -It reflects the value of the [`popover`](/en-US/docs/Web/HTML/Global_attributes/popover) global HTML attribute. +It reflects the value of the [`popover`](/en-US/docs/Web/HTML/Reference/Global_attributes/popover) global HTML attribute. ## Value @@ -32,7 +32,7 @@ An enumerated value; possible values are: - `"manual"` - - : [`manual`](/en-US/docs/Web/API/Popover_API/Using#using_manual_popover_state) popovers cannot be "light dismissed" are not automatically closed. Popovers must explicitly be displayed and closed using declarative show/hide/toggle buttons or JavaScript. Multiple independent `manual` popovers can be shown simultaneously. + - : [`manual`](/en-US/docs/Web/API/Popover_API/Using#using_manual_popover_state) popovers cannot be "light dismissed" and are not automatically closed. Popovers must explicitly be displayed and closed using declarative show/hide/toggle buttons or JavaScript. Multiple independent `manual` popovers can be shown simultaneously. ## Examples @@ -42,7 +42,7 @@ You can use the `popover` attribute to feature detect the [Popover API](/en-US/d ```js function supportsPopover() { - return HTMLElement.prototype.hasOwnProperty("popover"); + return Object.hasOwn(HTMLElement.prototype, "popover"); } ``` @@ -73,5 +73,5 @@ if (popoverSupported) { ## See also -- [`popover`](/en-US/docs/Web/HTML/Global_attributes/popover) HTML global attribute +- [`popover`](/en-US/docs/Web/HTML/Reference/Global_attributes/popover) HTML global attribute - [Popover API](/en-US/docs/Web/API/Popover_API) diff --git a/files/en-us/web/api/htmlelement/showpopover/index.md b/files/en-us/web/api/htmlelement/showpopover/index.md index c122f19d911465e..77a7e195027d785 100644 --- a/files/en-us/web/api/htmlelement/showpopover/index.md +++ b/files/en-us/web/api/htmlelement/showpopover/index.md @@ -8,9 +8,9 @@ browser-compat: api.HTMLElement.showPopover {{APIRef("Popover API")}} -The **`showPopover()`** method of the {{domxref("HTMLElement")}} interface shows a {{domxref("Popover_API", "popover", "", "nocode")}} element (i.e. one that has a valid [`popover`](/en-US/docs/Web/HTML/Global_attributes/popover) attribute) by adding it to the {{glossary("top layer")}}. +The **`showPopover()`** method of the {{domxref("HTMLElement")}} interface shows a {{domxref("Popover_API", "popover", "", "nocode")}} element (i.e., one that has a valid [`popover`](/en-US/docs/Web/HTML/Reference/Global_attributes/popover) attribute) by adding it to the {{glossary("top layer")}}. -When `showPopover()` is called on an element with the [`popover`](/en-US/docs/Web/HTML/Global_attributes/popover) attribute that is currently hidden, a {{domxref("HTMLElement/beforetoggle_event", "beforetoggle")}} event will be fired, followed by the popover showing, and then the {{domxref("HTMLElement/toggle_event", "toggle")}} event firing. If the element is already showing, an error will be thrown. +When `showPopover()` is called on an element with the [`popover`](/en-US/docs/Web/HTML/Reference/Global_attributes/popover) attribute that is currently hidden, a {{domxref("HTMLElement/beforetoggle_event", "beforetoggle")}} event will be fired, followed by the popover showing, and then the {{domxref("HTMLElement/toggle_event", "toggle")}} event firing. If the element is already showing, an error will be thrown. ## Syntax diff --git a/files/en-us/web/api/htmlelement/spellcheck/index.md b/files/en-us/web/api/htmlelement/spellcheck/index.md index e9e420de9f52c3c..2d1ef9b6b382896 100644 --- a/files/en-us/web/api/htmlelement/spellcheck/index.md +++ b/files/en-us/web/api/htmlelement/spellcheck/index.md @@ -8,9 +8,9 @@ browser-compat: api.HTMLElement.spellcheck {{APIRef("HTML DOM")}} -The **`spellcheck`** property of the {{domxref("HTMLElement")}} interface represents a boolean value that controls the [spell-checking](/en-US/docs/Web/HTML/Global_attributes/spellcheck) hint. It is available on all HTML elements, though it doesn't affect all of them. +The **`spellcheck`** property of the {{domxref("HTMLElement")}} interface represents a boolean value that controls the [spell-checking](/en-US/docs/Web/HTML/Reference/Global_attributes/spellcheck) hint. It is available on all HTML elements, though it doesn't affect all of them. -It reflects the value of the [`spellcheck`](/en-US/docs/Web/HTML/Global_attributes/spellcheck) HTML global attribute. +It reflects the value of the [`spellcheck`](/en-US/docs/Web/HTML/Reference/Global_attributes/spellcheck) HTML global attribute. ## Value @@ -18,7 +18,7 @@ A boolean value that is `true` if the spelling and grammar of the text content i ## Examples -The following example shows how to control the [spell-checking](/en-US/docs/Web/HTML/Global_attributes/spellcheck) hint via script: +The following example shows how to control the [spell-checking](/en-US/docs/Web/HTML/Reference/Global_attributes/spellcheck) hint via script: ```html <div> @@ -59,4 +59,4 @@ Note that you must enable the browser setting to check spelling and grammar. ## See also -- [`spellcheck`](/en-US/docs/Web/HTML/Global_attributes/spellcheck) HTML global attribute +- [`spellcheck`](/en-US/docs/Web/HTML/Reference/Global_attributes/spellcheck) HTML global attribute diff --git a/files/en-us/web/api/htmlelement/style/index.md b/files/en-us/web/api/htmlelement/style/index.md index 5f4e5a94d61b812..056da8bceb860ac 100644 --- a/files/en-us/web/api/htmlelement/style/index.md +++ b/files/en-us/web/api/htmlelement/style/index.md @@ -8,7 +8,7 @@ browser-compat: api.HTMLElement.style {{APIRef("CSSOM")}} -The read-only **`style`** property of the {{domxref("HTMLElement")}} returns the _inline_ style of an element in the form of a live {{domxref("CSSStyleDeclaration")}} object that contains a list of all styles properties for that element with values assigned only for the attributes that are defined in the element's inline [`style`](/en-US/docs/Web/HTML/Global_attributes/style) attribute. +The read-only **`style`** property of the {{domxref("HTMLElement")}} returns the _inline_ style of an element in the form of a live {{domxref("CSSStyleDeclaration")}} object that contains a list of all styles properties for that element with values assigned only for the attributes that are defined in the element's inline [`style`](/en-US/docs/Web/HTML/Reference/Global_attributes/style) attribute. Shorthand properties are expanded. If you set `style="border-top: 1px solid black"`, the longhand properties ({{cssxref("border-top-color")}}, {{cssxref("border-top-style")}}, and {{cssxref("border-top-width")}}) are set instead. @@ -59,7 +59,7 @@ for (const prop in elementStyle) { // We also ensure that the property is a numeric index (indicating an inline style) if ( Object.hasOwn(elementStyle, prop) && - !Number.isNaN(Number.parseInt(prop)) + !Number.isNaN(Number.parseInt(prop, 10)) ) { out.textContent += `${ elementStyle[prop] @@ -86,4 +86,4 @@ Note `font-weight` is not listed as a value for `elementStyle` as it is not defi - {{domxref("SVGElement.style")}} - {{domxref("MathMLElement.style")}} - {{domxref("HTMLElement.attributeStyleMap")}} -- HTML [`style`](/en-US/docs/Web/HTML/Global_attributes/style) attribute +- HTML [`style`](/en-US/docs/Web/HTML/Reference/Global_attributes/style) attribute diff --git a/files/en-us/web/api/htmlelement/tabindex/index.md b/files/en-us/web/api/htmlelement/tabindex/index.md index 5e8655598408599..e19f5e3ccbad171 100644 --- a/files/en-us/web/api/htmlelement/tabindex/index.md +++ b/files/en-us/web/api/htmlelement/tabindex/index.md @@ -46,7 +46,7 @@ b1.tabIndex = 1; ## See also -- [Accessibility of keyboard-navigable JavaScript widgets](/en-US/docs/Web/Accessibility/Keyboard-navigable_JavaScript_widgets) +- [Accessibility of keyboard-navigable JavaScript widgets](/en-US/docs/Web/Accessibility/Guides/Keyboard-navigable_JavaScript_widgets) - The HTML - [`tabindex`](/en-US/docs/Web/HTML/Global_attributes/tabindex) + [`tabindex`](/en-US/docs/Web/HTML/Reference/Global_attributes/tabindex) global attribute. diff --git a/files/en-us/web/api/htmlelement/title/index.md b/files/en-us/web/api/htmlelement/title/index.md index 081b736d34112ec..074eca2de716e2d 100644 --- a/files/en-us/web/api/htmlelement/title/index.md +++ b/files/en-us/web/api/htmlelement/title/index.md @@ -35,5 +35,5 @@ link.title = "Wikipedia page on grapes"; ## See also -- The HTML [**title**](/en-US/docs/Web/HTML/Global_attributes/title) +- The HTML [**title**](/en-US/docs/Web/HTML/Reference/Global_attributes/title) global attribute. diff --git a/files/en-us/web/api/htmlelement/toggle_event/index.md b/files/en-us/web/api/htmlelement/toggle_event/index.md index 91299ca1256daa5..9dac8536e2f13a6 100644 --- a/files/en-us/web/api/htmlelement/toggle_event/index.md +++ b/files/en-us/web/api/htmlelement/toggle_event/index.md @@ -18,10 +18,10 @@ This event is not [cancelable](/en-US/docs/Web/API/Event/cancelable). Use the event name in methods like {{domxref("EventTarget.addEventListener", "addEventListener()")}}, or set an event handler property. -```js -addEventListener("toggle", (event) => {}); +```js-nolint +addEventListener("toggle", (event) => { }) -ontoggle = (event) => {}; +ontoggle = (event) => { } ``` ## Event type @@ -98,7 +98,7 @@ For example: ```js popover.addEventListener("toggle", () => { - //... + // … }); popover.showPopover(); @@ -120,6 +120,6 @@ popover.hidePopover(); ## See also -- [`popover`](/en-US/docs/Web/HTML/Global_attributes/popover) HTML global attribute +- [`popover`](/en-US/docs/Web/HTML/Reference/Global_attributes/popover) HTML global attribute - [Popover API](/en-US/docs/Web/API/Popover_API) - Related event: [`beforetoggle`](/en-US/docs/Web/API/HTMLElement/beforetoggle_event) diff --git a/files/en-us/web/api/htmlelement/togglepopover/index.md b/files/en-us/web/api/htmlelement/togglepopover/index.md index ae86af73c76b964..27bdb4d0d506dfd 100644 --- a/files/en-us/web/api/htmlelement/togglepopover/index.md +++ b/files/en-us/web/api/htmlelement/togglepopover/index.md @@ -8,9 +8,9 @@ browser-compat: api.HTMLElement.togglePopover {{APIRef("Popover API")}} -The **`togglePopover()`** method of the {{domxref("HTMLElement")}} interface toggles a {{domxref("Popover_API", "popover", "", "nocode")}} element (i.e. one that has a valid [`popover`](/en-US/docs/Web/HTML/Global_attributes/popover) attribute) between the hidden and showing states. +The **`togglePopover()`** method of the {{domxref("HTMLElement")}} interface toggles a {{domxref("Popover_API", "popover", "", "nocode")}} element (i.e., one that has a valid [`popover`](/en-US/docs/Web/HTML/Reference/Global_attributes/popover) attribute) between the hidden and showing states. -When `togglePopover()` is called on an element with the [`popover`](/en-US/docs/Web/HTML/Global_attributes/popover) attribute: +When `togglePopover()` is called on an element with the [`popover`](/en-US/docs/Web/HTML/Reference/Global_attributes/popover) attribute: 1. A {{domxref("HTMLElement/beforetoggle_event", "beforetoggle")}} event is fired. 2. The popover toggles between hidden and showing: @@ -72,7 +72,7 @@ This first element defines instructions on how to invoke the popup, which we nee ``` We then define a `<div>` element which is the popup. -The actual content doesn't matter, but note that we need the [`popover`](/en-US/docs/Web/HTML/Global_attributes/popover) attribute to make the `<div>` into a popover so that it is hidden by default (or we could set this element in the JavaScript). +The actual content doesn't matter, but note that we need the [`popover`](/en-US/docs/Web/HTML/Reference/Global_attributes/popover) attribute to make the `<div>` into a popover so that it is hidden by default (or we could set this element in the JavaScript). ```html <div id="mypopover" popover> @@ -95,7 +95,7 @@ First we check whether popovers are supported, and if they aren't we hide the po const instructions = document.getElementById("instructions"); const popover = document.getElementById("mypopover"); -if (!HTMLElement.prototype.hasOwnProperty("popover")) { +if (!Object.hasOwn(HTMLElement.prototype, "popover")) { popover.innerText = ""; instructions.innerText = "Popovers not supported"; } @@ -105,7 +105,7 @@ If popovers are supported we add a listener for the `h` key to be pressed, and u We also log whether the popup was open or closed after the call, but only if a `true` or `false` was returned. ```js -if (HTMLElement.prototype.hasOwnProperty("popover")) { +if (Object.hasOwn(HTMLElement.prototype, "popover")) { document.addEventListener("keydown", (event) => { if (event.key === "h") { const popupOpened = popover.togglePopover(); @@ -134,5 +134,5 @@ You can test this out using the live example below. ## See also -- [`popover`](/en-US/docs/Web/HTML/Global_attributes/popover) HTML global attribute +- [`popover`](/en-US/docs/Web/HTML/Reference/Global_attributes/popover) HTML global attribute - [Popover API](/en-US/docs/Web/API/Popover_API) diff --git a/files/en-us/web/api/htmlelement/translate/index.md b/files/en-us/web/api/htmlelement/translate/index.md index 5bbe1489f3df4e7..ffe1368196e4f4b 100644 --- a/files/en-us/web/api/htmlelement/translate/index.md +++ b/files/en-us/web/api/htmlelement/translate/index.md @@ -10,7 +10,7 @@ browser-compat: api.HTMLElement.translate The **`translate`** property of the {{domxref("HTMLElement")}} interface indicates whether an element's attribute values and the values of its {{domxref("Text")}} node children are to be translated when the page is localized, or whether to leave them unchanged. -It reflects the value of the [`translate`](/en-US/docs/Web/HTML/Global_attributes/translate) HTML global attribute. +It reflects the value of the [`translate`](/en-US/docs/Web/HTML/Reference/Global_attributes/translate) HTML global attribute. ## Value @@ -23,11 +23,13 @@ The following example shows how to enable or disable translation via script: ```html <div> <span>The content may always be translated: </span> - <span translate="yes">El contenido será traducido</div> + <span translate="yes">El contenido será traducido</span> </div> <div> <span id="translate-label">The content may be translated:</span> - <span id="translate-element" translate="no">El contenido puede ser traducido.</div> + <span id="translate-element" translate="no"> + El contenido puede ser traducido. + </span> </div> <input id="translate-controller" type="checkbox" /> Enable translation ``` @@ -60,4 +62,4 @@ controller.addEventListener("change", (e) => { ## See also -- [`translate`](/en-US/docs/Web/HTML/Global_attributes/translate) HTML global attribute +- [`translate`](/en-US/docs/Web/HTML/Reference/Global_attributes/translate) HTML global attribute diff --git a/files/en-us/web/api/htmlelement/virtualkeyboardpolicy/index.md b/files/en-us/web/api/htmlelement/virtualkeyboardpolicy/index.md index c9281f5f9af9354..814f473b0174acf 100644 --- a/files/en-us/web/api/htmlelement/virtualkeyboardpolicy/index.md +++ b/files/en-us/web/api/htmlelement/virtualkeyboardpolicy/index.md @@ -10,9 +10,9 @@ browser-compat: api.HTMLElement.virtualKeyboardPolicy {{APIRef("VirtualKeyboard API")}}{{SeeCompatTable}} -The **`virtualKeyboardPolicy`** property of the {{domxref("HTMLElement")}} interface gets and sets a string indicating the on-screen virtual keyboard behavior on devices such as tablets, mobile phones, or other devices where a hardware keyboard may not be available, if the element's content is editable (for example, it is an {{htmlelement("input")}} or {{htmlelement("textarea")}} element, or an element with the [`contenteditable`](/en-US/docs/Web/HTML/Global_attributes/contenteditable) attribute set). +The **`virtualKeyboardPolicy`** property of the {{domxref("HTMLElement")}} interface gets and sets a string indicating the on-screen virtual keyboard behavior on devices such as tablets, mobile phones, or other devices where a hardware keyboard may not be available, if the element's content is editable (for example, it is an {{htmlelement("input")}} or {{htmlelement("textarea")}} element, or an element with the [`contenteditable`](/en-US/docs/Web/HTML/Reference/Global_attributes/contenteditable) attribute set). -It reflects the value of the [`virtualkeyboardpolicy`](/en-US/docs/Web/HTML/Global_attributes/virtualkeyboardpolicy) HTML global attribute. +It reflects the value of the [`virtualkeyboardpolicy`](/en-US/docs/Web/HTML/Reference/Global_attributes/virtualkeyboardpolicy) HTML global attribute. ## Value @@ -44,4 +44,4 @@ element.virtualKeyboardPolicy = "manual"; ## See also -- [`virtualkeyboardpolicy`](/en-US/docs/Web/HTML/Global_attributes/virtualkeyboardpolicy) HTML global attribute +- [`virtualkeyboardpolicy`](/en-US/docs/Web/HTML/Reference/Global_attributes/virtualkeyboardpolicy) HTML global attribute diff --git a/files/en-us/web/api/htmlelement/writingsuggestions/index.md b/files/en-us/web/api/htmlelement/writingsuggestions/index.md index 91f67985ff8874a..fbb933c05a1d6c0 100644 --- a/files/en-us/web/api/htmlelement/writingsuggestions/index.md +++ b/files/en-us/web/api/htmlelement/writingsuggestions/index.md @@ -10,7 +10,7 @@ browser-compat: api.HTMLElement.writingSuggestions The **`writingSuggestions`** property of the {{domxref("HTMLElement")}} interface is a string indicating if browser-provided writing suggestions should be enabled under the scope of the element or not. -It reflects the value of the [`writingsuggestions`](/en-US/docs/Web/HTML/Global_attributes/writingsuggestions) HTML global attribute. +It reflects the value of the [`writingsuggestions`](/en-US/docs/Web/HTML/Reference/Global_attributes/writingsuggestions) HTML global attribute. ## Value @@ -42,4 +42,4 @@ element.writingSuggestions = "false"; ## See also -- [`writingsuggestions`](/en-US/docs/Web/HTML/Global_attributes/writingsuggestions) HTML global attribute +- [`writingsuggestions`](/en-US/docs/Web/HTML/Reference/Global_attributes/writingsuggestions) HTML global attribute diff --git a/files/en-us/web/api/htmlembedelement/index.md b/files/en-us/web/api/htmlembedelement/index.md index 6a4bc07484b1cde..faabcfab9f436e9 100644 --- a/files/en-us/web/api/htmlembedelement/index.md +++ b/files/en-us/web/api/htmlembedelement/index.md @@ -21,15 +21,15 @@ _Inherits properties from its parent, {{domxref("HTMLElement")}}._ - {{domxref("HTMLEmbedElement.align")}} {{deprecated_inline}} - : A string representing an enumerated property indicating alignment of the element's contents with respect to the surrounding context. The possible values are `"left"`, `"right"`, `"center"`, and `"justify"`. - {{domxref("HTMLEmbedElement.height")}} - - : A string reflecting the [`height`](/en-US/docs/Web/HTML/Element/embed#height) HTML attribute, containing the displayed height of the resource. + - : A string reflecting the [`height`](/en-US/docs/Web/HTML/Reference/Elements/embed#height) HTML attribute, containing the displayed height of the resource. - {{domxref("HTMLEmbedElement.name")}} {{deprecated_inline}} - : A string representing the name of the embedded object. - {{domxref("HTMLEmbedElement.src")}} - - : A string that reflects the [`src`](/en-US/docs/Web/HTML/Element/embed#src) HTML attribute, containing the address of the resource. + - : A string that reflects the [`src`](/en-US/docs/Web/HTML/Reference/Elements/embed#src) HTML attribute, containing the address of the resource. - {{domxref("HTMLEmbedElement.type")}} - - : A string that reflects the [`type`](/en-US/docs/Web/HTML/Element/embed#type) HTML attribute, containing the type of the resource. + - : A string that reflects the [`type`](/en-US/docs/Web/HTML/Reference/Elements/embed#type) HTML attribute, containing the type of the resource. - {{domxref("HTMLEmbedElement.width")}} - - : A string that reflects the [`width`](/en-US/docs/Web/HTML/Element/embed#width) HTML attribute, containing the displayed width of the resource. + - : A string that reflects the [`width`](/en-US/docs/Web/HTML/Reference/Elements/embed#width) HTML attribute, containing the displayed width of the resource. ## Instance methods diff --git a/files/en-us/web/api/htmlembedelement/type/index.md b/files/en-us/web/api/htmlembedelement/type/index.md index 317e2646547d9f2..19a58a086d293bd 100644 --- a/files/en-us/web/api/htmlembedelement/type/index.md +++ b/files/en-us/web/api/htmlembedelement/type/index.md @@ -8,7 +8,7 @@ browser-compat: api.HTMLEmbedElement.type {{APIRef("HTML DOM")}} -The **`type`** property of the {{domxref("HTMLEmbedElement")}} interface returns a string that reflects the `type` attribute of the {{HTMLElement("embed")}} element, indicating the {{glossary("MIME type")}} of the resource. It reflects the {{htmlelement("embed")}} element's [`type`](/en-US/docs/Web/HTML/Element/embed#type) attribute +The **`type`** property of the {{domxref("HTMLEmbedElement")}} interface returns a string that reflects the `type` attribute of the {{HTMLElement("embed")}} element, indicating the {{glossary("MIME type")}} of the resource. It reflects the {{htmlelement("embed")}} element's [`type`](/en-US/docs/Web/HTML/Reference/Elements/embed#type) attribute ## Value @@ -34,4 +34,4 @@ console.log(el.type); // Output: "video/webp" - {{domxref("HTMLObjectElement.type")}} - {{domxref("HTMLSourceElement.type")}} - [Media types found on the web](/en-US/docs/Web/Media/Guides/Formats) -- [Important MIME types for web developers](/en-US/docs/Web/HTTP/MIME_types#important_mime_types_for_web_developers) +- [Important MIME types for web developers](/en-US/docs/Web/HTTP/Guides/MIME_types#important_mime_types_for_web_developers) diff --git a/files/en-us/web/api/htmlfencedframeelement/allow/index.md b/files/en-us/web/api/htmlfencedframeelement/allow/index.md index 7a924a2a5f9110b..bcb89b8544d1409 100644 --- a/files/en-us/web/api/htmlfencedframeelement/allow/index.md +++ b/files/en-us/web/api/htmlfencedframeelement/allow/index.md @@ -10,13 +10,13 @@ browser-compat: api.HTMLFencedFrameElement.allow {{SeeCompatTable}}{{APIRef("Fenced Frame API")}} -The **`allow`** property of the {{domxref("HTMLFencedFrameElement")}} gets and sets the value of the corresponding {{htmlelement("fencedframe")}} `allow` attribute, which represents a [Permissions Policy](/en-US/docs/Web/HTTP/Permissions_Policy) applied to the content when it is first embedded. +The **`allow`** property of the {{domxref("HTMLFencedFrameElement")}} gets and sets the value of the corresponding {{htmlelement("fencedframe")}} `allow` attribute, which represents a [Permissions Policy](/en-US/docs/Web/HTTP/Guides/Permissions_Policy) applied to the content when it is first embedded. -Not all permissions policies are allowed in fenced frames. The allowed permissions are listed at [Permissions policies available to fenced frames](/en-US/docs/Web/HTML/Element/fencedframe#permissions_policies_available_to_fenced_frames) — these are required for fenced frame content originating from the specified APIs to load. If you don't set the `allow` attribute, those permissions will be allowed by default. If you want to narrow down the permissions set, you need to make sure that all of the required permissions for the APIs you are using are set in the `allow` attribute. +Not all permissions policies are allowed in fenced frames. The allowed permissions are listed at [Permissions policies available to fenced frames](/en-US/docs/Web/HTML/Reference/Elements/fencedframe#permissions_policies_available_to_fenced_frames) — these are required for fenced frame content originating from the specified APIs to load. If you don't set the `allow` attribute, those permissions will be allowed by default. If you want to narrow down the permissions set, you need to make sure that all of the required permissions for the APIs you are using are set in the `allow` attribute. ## Value -A string representing a [Permissions Policy](/en-US/docs/Web/HTTP/Permissions_Policy). +A string representing a [Permissions Policy](/en-US/docs/Web/HTTP/Guides/Permissions_Policy). ## Examples @@ -35,5 +35,5 @@ console.log(frame.allow); ## See also -- [Fenced frames](https://developers.google.com/privacy-sandbox/private-advertising/fenced-frame) on developers.google.com -- [The Privacy Sandbox](https://developers.google.com/privacy-sandbox) on developers.google.com +- [Fenced frames](https://privacysandbox.google.com/private-advertising/fenced-frame) on privacysandbox.google.com +- [The Privacy Sandbox](https://privacysandbox.google.com/) on privacysandbox.google.com diff --git a/files/en-us/web/api/htmlfencedframeelement/config/index.md b/files/en-us/web/api/htmlfencedframeelement/config/index.md index 955640a6177262f..ce609a8b356dbc6 100644 --- a/files/en-us/web/api/htmlfencedframeelement/config/index.md +++ b/files/en-us/web/api/htmlfencedframeelement/config/index.md @@ -10,7 +10,7 @@ browser-compat: api.HTMLFencedFrameElement.config {{SeeCompatTable}}{{APIRef("Fenced Frame API")}} -The **`config`** property of the {{domxref("HTMLFencedFrameElement")}} contains a {{domxref("FencedFrameConfig")}} object, which represents the navigation of a {{htmlelement("fencedframe")}}, i.e. what content will be displayed in it. A `FencedFrameConfig` is returned from a source such as the [Protected Audience API](https://developers.google.com/privacy-sandbox/private-advertising/protected-audience). +The **`config`** property of the {{domxref("HTMLFencedFrameElement")}} contains a {{domxref("FencedFrameConfig")}} object, which represents the navigation of a {{htmlelement("fencedframe")}}, i.e., what content will be displayed in it. A `FencedFrameConfig` is returned from a source such as the [Protected Audience API](https://privacysandbox.google.com/private-advertising/protected-audience). ## Value @@ -23,13 +23,13 @@ When its value is set to a {{domxref("FencedFrameConfig")}} object instance, the ## Examples -To set what content will be shown in a `<fencedframe>`, a utilizing API (such as [Protected Audience](https://developers.google.com/privacy-sandbox/private-advertising/protected-audience) or [Shared Storage](https://developers.google.com/privacy-sandbox/private-advertising/shared-storage)) generates a {{domxref("FencedFrameConfig")}} object, which is then set as the value of the `<fencedframe>`'s `config` property. +To set what content will be shown in a `<fencedframe>`, a utilizing API (such as [Protected Audience](https://privacysandbox.google.com/private-advertising/protected-audience) or [Shared Storage](https://privacysandbox.google.com/private-advertising/shared-storage)) generates a {{domxref("FencedFrameConfig")}} object, which is then set as the value of the `<fencedframe>`'s `config` property. The following example gets a `FencedFrameConfig` from a Protected Audience API's ad auction, which is then used to display the winning ad in a `<fencedframe>`: ```js const frameConfig = await navigator.runAdAuction({ - // ...auction configuration + // … auction configuration resolveToConfig: true, }); @@ -49,5 +49,5 @@ frame.config = frameConfig; ## See also -- [Fenced frames](https://developers.google.com/privacy-sandbox/private-advertising/fenced-frame) on developers.google.com -- [The Privacy Sandbox](https://developers.google.com/privacy-sandbox) on developers.google.com +- [Fenced frames](https://privacysandbox.google.com/private-advertising/fenced-frame) on privacysandbox.google.com +- [The Privacy Sandbox](https://privacysandbox.google.com/) on privacysandbox.google.com diff --git a/files/en-us/web/api/htmlfencedframeelement/height/index.md b/files/en-us/web/api/htmlfencedframeelement/height/index.md index 85e2b3244c91a30..36753faa2645415 100644 --- a/files/en-us/web/api/htmlfencedframeelement/height/index.md +++ b/files/en-us/web/api/htmlfencedframeelement/height/index.md @@ -12,7 +12,7 @@ browser-compat: api.HTMLFencedFrameElement.height The **`height`** property of the {{domxref("HTMLFencedFrameElement")}} gets and sets the value of the corresponding {{htmlelement("fencedframe")}} `height` attribute, which specifies the height of the element. -The size of the embedded content may be set by internal `contentWidth` and `contentHeight` properties of the `<fencedframe>`'s {{domxref("HTMLFencedFrameElement.config", "config")}} object. In such cases, changing the {{domxref("HTMLFencedFrameElement.width", "width")}} or `height` of the `<fencedframe>` will change the size of the embedded container on the page, but the document inside the container will be visually scaled to fit. The reported width and height of the embedded document (i.e. {{domxref("Window.innerWidth")}} and {{domxref("Window.innerHeight")}}) will be unchanged. +The size of the embedded content may be set by internal `contentWidth` and `contentHeight` properties of the `<fencedframe>`'s {{domxref("HTMLFencedFrameElement.config", "config")}} object. In such cases, changing the {{domxref("HTMLFencedFrameElement.width", "width")}} or `height` of the `<fencedframe>` will change the size of the embedded container on the page, but the document inside the container will be visually scaled to fit. The reported width and height of the embedded document (i.e., {{domxref("Window.innerWidth")}} and {{domxref("Window.innerHeight")}}) will be unchanged. ## Value @@ -35,5 +35,5 @@ frame.height = "320"; ## See also -- [Fenced frames](https://developers.google.com/privacy-sandbox/private-advertising/fenced-frame) on developers.google.com -- [The Privacy Sandbox](https://developers.google.com/privacy-sandbox) on developers.google.com +- [Fenced frames](https://privacysandbox.google.com/private-advertising/fenced-frame) on privacysandbox.google.com +- [The Privacy Sandbox](https://privacysandbox.google.com/) on privacysandbox.google.com diff --git a/files/en-us/web/api/htmlfencedframeelement/index.md b/files/en-us/web/api/htmlfencedframeelement/index.md index 4cd07fcafcb21d5..4a8e34f423ae03c 100644 --- a/files/en-us/web/api/htmlfencedframeelement/index.md +++ b/files/en-us/web/api/htmlfencedframeelement/index.md @@ -18,9 +18,9 @@ The **`HTMLFencedFrameElement`** interface represents a {{htmlelement("fencedfra _Inherits properties from its parent, {{domxref("HTMLElement")}}._ - {{domxref("HTMLFencedFrameElement.allow")}} {{experimental_inline}} - - : Gets and sets the value of the corresponding `<fencedframe>` `allow` attribute, which represents a [Permissions Policy](/en-US/docs/Web/HTTP/Permissions_Policy) applied to the content when it is first embedded. + - : Gets and sets the value of the corresponding `<fencedframe>` `allow` attribute, which represents a [Permissions Policy](/en-US/docs/Web/HTTP/Guides/Permissions_Policy) applied to the content when it is first embedded. - {{domxref("HTMLFencedFrameElement.config")}} {{experimental_inline}} - - : a {{domxref("FencedFrameConfig")}} object, which represents the navigation of a {{htmlelement("fencedframe")}}, i.e. what content will be displayed in it. A `FencedFrameConfig` is returned from a source such as the [Protected Audience API](https://developers.google.com/privacy-sandbox/private-advertising/protected-audience). + - : a {{domxref("FencedFrameConfig")}} object, which represents the navigation of a {{htmlelement("fencedframe")}}, i.e., what content will be displayed in it. A `FencedFrameConfig` is returned from a source such as the [Protected Audience API](https://privacysandbox.google.com/private-advertising/protected-audience). - {{domxref("HTMLFencedFrameElement.height")}} {{experimental_inline}} - : Gets and sets the value of the corresponding `<fencedframe>` `height` attribute, which specifies the height of the element. - {{domxref("HTMLFencedFrameElement.width")}} {{experimental_inline}} @@ -28,13 +28,13 @@ _Inherits properties from its parent, {{domxref("HTMLElement")}}._ ## Examples -To set what content will be shown in a `<fencedframe>`, a utilizing API (such as [Protected Audience](https://developers.google.com/privacy-sandbox/private-advertising/protected-audience) or [Shared Storage](https://developers.google.com/privacy-sandbox/private-advertising/shared-storage)) generates a {{domxref("FencedFrameConfig")}} object, which is then set as the value of the `<fencedframe>`'s `config` property. +To set what content will be shown in a `<fencedframe>`, a utilizing API (such as [Protected Audience](https://privacysandbox.google.com/private-advertising/protected-audience) or [Shared Storage](https://privacysandbox.google.com/private-advertising/shared-storage)) generates a {{domxref("FencedFrameConfig")}} object, which is then set as the value of the `<fencedframe>`'s `config` property. The following example gets a `FencedFrameConfig` from a Protected Audience API's ad auction, which is then used to display the winning ad in a `<fencedframe>`: ```js const frameConfig = await navigator.runAdAuction({ - // ...auction configuration + // … auction configuration resolveToConfig: true, }); @@ -54,5 +54,5 @@ frame.config = frameConfig; ## See also -- [Fenced frames](https://developers.google.com/privacy-sandbox/private-advertising/fenced-frame) on developers.google.com -- [The Privacy Sandbox](https://developers.google.com/privacy-sandbox) on developers.google.com +- [Fenced frames](https://privacysandbox.google.com/private-advertising/fenced-frame) on privacysandbox.google.com +- [The Privacy Sandbox](https://privacysandbox.google.com/) on privacysandbox.google.com diff --git a/files/en-us/web/api/htmlfencedframeelement/width/index.md b/files/en-us/web/api/htmlfencedframeelement/width/index.md index 7af66df1bdebbd3..ce2a3e9e8765b1a 100644 --- a/files/en-us/web/api/htmlfencedframeelement/width/index.md +++ b/files/en-us/web/api/htmlfencedframeelement/width/index.md @@ -12,7 +12,7 @@ browser-compat: api.HTMLFencedFrameElement.width The **`width`** property of the {{domxref("HTMLFencedFrameElement")}} gets and sets the value of the corresponding {{htmlelement("fencedframe")}} `width` attribute, which specifies the width of the element. -The size of the embedded content may be set by internal `contentWidth` and `contentHeight` properties of the `<fencedframe>`'s {{domxref("HTMLFencedFrameElement.config", "config")}} object. In such cases, changing the `width` or {{domxref("HTMLFencedFrameElement.height", "height")}} of the `<fencedframe>` will change the size of the embedded container on the page, but the document inside the container will be visually scaled to fit. The reported width and height of the embedded document (i.e. {{domxref("Window.innerWidth")}} and {{domxref("Window.innerHeight")}}) will be unchanged. +The size of the embedded content may be set by internal `contentWidth` and `contentHeight` properties of the `<fencedframe>`'s {{domxref("HTMLFencedFrameElement.config", "config")}} object. In such cases, changing the `width` or {{domxref("HTMLFencedFrameElement.height", "height")}} of the `<fencedframe>` will change the size of the embedded container on the page, but the document inside the container will be visually scaled to fit. The reported width and height of the embedded document (i.e., {{domxref("Window.innerWidth")}} and {{domxref("Window.innerHeight")}}) will be unchanged. ## Value @@ -35,5 +35,5 @@ frame.width = "480"; ## See also -- [Fenced frames](https://developers.google.com/privacy-sandbox/private-advertising/fenced-frame) on developers.google.com -- [The Privacy Sandbox](https://developers.google.com/privacy-sandbox) on developers.google.com +- [Fenced frames](https://privacysandbox.google.com/private-advertising/fenced-frame) on privacysandbox.google.com +- [The Privacy Sandbox](https://privacysandbox.google.com/) on privacysandbox.google.com diff --git a/files/en-us/web/api/htmlfieldsetelement/checkvalidity/index.md b/files/en-us/web/api/htmlfieldsetelement/checkvalidity/index.md index bd2a9b4da717610..ae44afdee7c114c 100644 --- a/files/en-us/web/api/htmlfieldsetelement/checkvalidity/index.md +++ b/files/en-us/web/api/htmlfieldsetelement/checkvalidity/index.md @@ -8,7 +8,7 @@ browser-compat: api.HTMLFieldSetElement.checkValidity {{APIRef("HTML DOM")}} -The **`checkValidity()`** method of the {{domxref("HTMLFieldSetElement")}} interface checks if the element is valid, but always returns true because {{HTMLElement("fieldset")}} elements are never candidates for [constraint validation](/en-US/docs/Web/HTML/Constraint_validation). +The **`checkValidity()`** method of the {{domxref("HTMLFieldSetElement")}} interface checks if the element is valid, but always returns true because {{HTMLElement("fieldset")}} elements are never candidates for [constraint validation](/en-US/docs/Web/HTML/Guides/Constraint_validation). > [!NOTE] > The {{cssxref(":valid")}} and {{cssxref(":invalid")}} CSS pseudo-classes are applied to `<fieldset>` elements based on the validity of its descendant form controls, not the fieldset itself. @@ -50,4 +50,4 @@ console.log(element.checkValidity()); - {{HTMLElement("fieldset")}} - {{HTMLElement("form")}} - [Learn: Client-side form validation](/en-US/docs/Learn_web_development/Extensions/Forms/Form_validation) -- [Guide: Constraint validation](/en-US/docs/Web/HTML/Constraint_validation) +- [Guide: Constraint validation](/en-US/docs/Web/HTML/Guides/Constraint_validation) diff --git a/files/en-us/web/api/htmlfieldsetelement/disabled/index.md b/files/en-us/web/api/htmlfieldsetelement/disabled/index.md index dc619fa0e5274b5..8d9590dd06c2c37 100644 --- a/files/en-us/web/api/htmlfieldsetelement/disabled/index.md +++ b/files/en-us/web/api/htmlfieldsetelement/disabled/index.md @@ -8,7 +8,7 @@ browser-compat: api.HTMLFieldSetElement.disabled {{ APIRef("HTML DOM") }} -The **`disabled`** property of the {{domxref("HTMLFieldSetElement")}} interface is a boolean value that reflects the {{htmlelement("fieldset")}} element's [`disabled`](/en-US/docs/Web/HTML/Element/fieldset#disabled) attribute, which indicates whether the control is disabled. +The **`disabled`** property of the {{domxref("HTMLFieldSetElement")}} interface is a boolean value that reflects the {{htmlelement("fieldset")}} element's [`disabled`](/en-US/docs/Web/HTML/Reference/Elements/fieldset#disabled) attribute, which indicates whether the control is disabled. When disabled, all the form control descendants of the `<fieldset>` element, excluding elements that are descendants of the {{htmlelement("legend")}} child of the `<fieldset>`, if any, are disabled. A disabled element is unusable and un-clickable, and match the {{cssxref(":disabled")}} selector, even if their `disabled` property value is false. @@ -34,5 +34,5 @@ fs.disabled = true; ## See also -- HTML [`disabled`](/en-US/docs/Web/HTML/Attributes/disabled) attribute +- HTML [`disabled`](/en-US/docs/Web/HTML/Reference/Attributes/disabled) attribute - CSS {{cssxref(":disabled")}} and {{cssxref(":enabled")}} pseudoclasses diff --git a/files/en-us/web/api/htmlfieldsetelement/form/index.md b/files/en-us/web/api/htmlfieldsetelement/form/index.md index 56d95939693bc89..83340334eb67c5b 100644 --- a/files/en-us/web/api/htmlfieldsetelement/form/index.md +++ b/files/en-us/web/api/htmlfieldsetelement/form/index.md @@ -27,5 +27,5 @@ An {{domxref("HTMLFormElement")}} or `null`. - {{domxref("HTMLFieldSetElement")}} - {{domxref("HTMLFormElement")}} - {{HTMLElement("fieldset")}} -- HTML [`form`](/en-US/docs/Web/HTML/Element/fieldset#form) attribute +- HTML [`form`](/en-US/docs/Web/HTML/Reference/Elements/fieldset#form) attribute - [HTML forms guide](/en-US/docs/Learn_web_development/Extensions/Forms) diff --git a/files/en-us/web/api/htmlfieldsetelement/index.md b/files/en-us/web/api/htmlfieldsetelement/index.md index 2d990fd108c8949..706d27e69015174 100644 --- a/files/en-us/web/api/htmlfieldsetelement/index.md +++ b/files/en-us/web/api/htmlfieldsetelement/index.md @@ -16,14 +16,14 @@ The **`HTMLFieldSetElement`** interface provides special properties and methods _Inherits properties from its parent, {{domxref("HTMLElement")}}._ - {{domxref("HTMLFieldSetElement.disabled")}} - - : A boolean value reflecting the [`disabled`](/en-US/docs/Web/HTML/Element/fieldset#disabled) HTML attribute, indicating whether the user can interact with the control. + - : A boolean value reflecting the [`disabled`](/en-US/docs/Web/HTML/Reference/Elements/fieldset#disabled) HTML attribute, indicating whether the user can interact with the control. - {{domxref("HTMLFieldSetElement.elements")}} {{ReadOnlyInline}} - : The elements belonging to this field set. The type of this property depends on the version of the spec that is implemented by the browser. - {{domxref("HTMLFieldSetElement.form")}} {{ReadOnlyInline}} - : An {{domxref("HTMLFormControlsCollection")}} or {{domxref("HTMLCollection")}} referencing the containing form element, if this element is in a form. If the field set is not a descendant of a form element, then the attribute can be the ID of any form element in the same document it is related to, or the `null` value if none matches. - {{domxref("HTMLFieldSetElement.name")}} - - : A string reflecting the [`name`](/en-US/docs/Web/HTML/Element/fieldset#name) HTML attribute, containing the name of the field set. This can be used when accessing the field set in JavaScript. It is _not_ part of the data which is sent to the server. + - : A string reflecting the [`name`](/en-US/docs/Web/HTML/Reference/Elements/fieldset#name) HTML attribute, containing the name of the field set. This can be used when accessing the field set in JavaScript. It is _not_ part of the data which is sent to the server. - {{domxref("HTMLFieldSetElement.type")}} {{ReadOnlyInline}} - : The string `"fieldset"`. - {{domxref("HTMLFieldSetElement.validationMessage")}} diff --git a/files/en-us/web/api/htmlfieldsetelement/name/index.md b/files/en-us/web/api/htmlfieldsetelement/name/index.md index 2d8067ae7343151..3218cc8c1014782 100644 --- a/files/en-us/web/api/htmlfieldsetelement/name/index.md +++ b/files/en-us/web/api/htmlfieldsetelement/name/index.md @@ -8,7 +8,7 @@ browser-compat: api.HTMLFieldSetElement.name {{ApiRef("HTML DOM")}} -The **`name`** property of the {{domxref("HTMLFieldSetElement")}} interface indicates the name of the {{HTMLElement("fieldset")}} element. It reflects the element's [`name`](/en-US/docs/Web/HTML/Element/fieldset#name) attribute. +The **`name`** property of the {{domxref("HTMLFieldSetElement")}} interface indicates the name of the {{HTMLElement("fieldset")}} element. It reflects the element's [`name`](/en-US/docs/Web/HTML/Reference/Elements/fieldset#name) attribute. ## Value diff --git a/files/en-us/web/api/htmlfieldsetelement/reportvalidity/index.md b/files/en-us/web/api/htmlfieldsetelement/reportvalidity/index.md index d38dbfe01249dd1..97f4f9a41153928 100644 --- a/files/en-us/web/api/htmlfieldsetelement/reportvalidity/index.md +++ b/files/en-us/web/api/htmlfieldsetelement/reportvalidity/index.md @@ -8,7 +8,7 @@ browser-compat: api.HTMLFieldSetElement.reportValidity {{APIRef("HTML DOM")}} -The **`reportValidity()`** method of the {{domxref("HTMLFieldSetElement")}} interface performs the same validity checking steps as the {{domxref("HTMLFieldSetElement.checkValidity", "checkValidity()")}} method. It always returns true because {{HTMLElement("fieldset")}} elements are never candidates for [constraint validation](/en-US/docs/Web/HTML/Constraint_validation). +The **`reportValidity()`** method of the {{domxref("HTMLFieldSetElement")}} interface performs the same validity checking steps as the {{domxref("HTMLFieldSetElement.checkValidity", "checkValidity()")}} method. It always returns true because {{HTMLElement("fieldset")}} elements are never candidates for [constraint validation](/en-US/docs/Web/HTML/Guides/Constraint_validation). ## Syntax @@ -38,4 +38,4 @@ A boolean value, `true`. - {{HTMLElement("fieldset")}} - {{HTMLElement("form")}} - [Learn: Client-side form validation](/en-US/docs/Learn_web_development/Extensions/Forms/Form_validation) -- [Guide: Constraint validation](/en-US/docs/Web/HTML/Constraint_validation) +- [Guide: Constraint validation](/en-US/docs/Web/HTML/Guides/Constraint_validation) diff --git a/files/en-us/web/api/htmlfieldsetelement/setcustomvalidity/index.md b/files/en-us/web/api/htmlfieldsetelement/setcustomvalidity/index.md index 972523ed974f1b7..e91fb393e242fdf 100644 --- a/files/en-us/web/api/htmlfieldsetelement/setcustomvalidity/index.md +++ b/files/en-us/web/api/htmlfieldsetelement/setcustomvalidity/index.md @@ -54,7 +54,7 @@ if (errors) { - {{domxref("HTMLFieldSetElement.validity")}} - {{domxref("HTMLFieldSetElement.checkValidity()")}} - {{domxref("HTMLFieldSetElement.reportValidity()")}} -- [Form validation](/en-US/docs/Web/HTML/Constraint_validation). +- [Form validation](/en-US/docs/Web/HTML/Guides/Constraint_validation). - [Learn: Client-side form validation](/en-US/docs/Learn_web_development/Extensions/Forms/Form_validation) -- [Guide: Constraint validation](/en-US/docs/Web/HTML/Constraint_validation) +- [Guide: Constraint validation](/en-US/docs/Web/HTML/Guides/Constraint_validation) - CSS {{cssxref(":valid")}} and {{cssxref(":invalid")}} pseudo-classes diff --git a/files/en-us/web/api/htmlfieldsetelement/validationmessage/index.md b/files/en-us/web/api/htmlfieldsetelement/validationmessage/index.md index 339276dcb7a3013..55cffcd848550d3 100644 --- a/files/en-us/web/api/htmlfieldsetelement/validationmessage/index.md +++ b/files/en-us/web/api/htmlfieldsetelement/validationmessage/index.md @@ -32,5 +32,5 @@ The empty string, `""`; - {{domxref("HTMLFieldSetElement.reportValidity()")}} - {{domxref("HTMLFieldSetElement.setCustomValidity()")}} - [Learn: Client-side form validation](/en-US/docs/Learn_web_development/Extensions/Forms/Form_validation) -- [Guide: Constraint validation](/en-US/docs/Web/HTML/Constraint_validation) +- [Guide: Constraint validation](/en-US/docs/Web/HTML/Guides/Constraint_validation) - CSS {{cssxref(":valid")}} and {{cssxref(":invalid")}} pseudo-classes diff --git a/files/en-us/web/api/htmlfieldsetelement/validity/index.md b/files/en-us/web/api/htmlfieldsetelement/validity/index.md index 35eaeebecea70e8..7d1a4cecacb884a 100644 --- a/files/en-us/web/api/htmlfieldsetelement/validity/index.md +++ b/files/en-us/web/api/htmlfieldsetelement/validity/index.md @@ -8,7 +8,7 @@ browser-compat: api.HTMLFieldSetElement.validity {{APIRef("HTML DOM")}} -The **`validity`** read-only property of the {{domxref("HTMLFieldSetElement")}} interface returns a {{domxref("ValidityState")}} object that represents the validity states this element is in. Although {{HTMLElement("fieldset")}} elements are never candidates for [constraint validation](/en-US/docs/Web/HTML/Constraint_validation), the validity state may still be invalid if a custom validity message has been set. +The **`validity`** read-only property of the {{domxref("HTMLFieldSetElement")}} interface returns a {{domxref("ValidityState")}} object that represents the validity states this element is in. Although {{HTMLElement("fieldset")}} elements are never candidates for [constraint validation](/en-US/docs/Web/HTML/Guides/Constraint_validation), the validity state may still be invalid if a custom validity message has been set. > [!NOTE] > The {{cssxref(":valid")}} and {{cssxref(":invalid")}} CSS pseudo-classes are applied to `<fieldset>` elements based on the validity of its descendant form controls, not the fieldset itself. @@ -47,4 +47,4 @@ console.log(fieldSet.checkValidity()); // true - {{HTMLElement("fieldset")}} - {{HTMLElement("form")}} - [Learn: Client-side form validation](/en-US/docs/Learn_web_development/Extensions/Forms/Form_validation) -- [Guide: Constraint validation](/en-US/docs/Web/HTML/Constraint_validation) +- [Guide: Constraint validation](/en-US/docs/Web/HTML/Guides/Constraint_validation) diff --git a/files/en-us/web/api/htmlfieldsetelement/willvalidate/index.md b/files/en-us/web/api/htmlfieldsetelement/willvalidate/index.md index 663c179b6e538be..5866fc341d2d8fe 100644 --- a/files/en-us/web/api/htmlfieldsetelement/willvalidate/index.md +++ b/files/en-us/web/api/htmlfieldsetelement/willvalidate/index.md @@ -8,7 +8,7 @@ browser-compat: api.HTMLFieldSetElement.willValidate {{APIRef("HTML DOM")}} -The **`willValidate`** read-only property of the {{domxref("HTMLFieldSetElement")}} interface returns `false`, because {{HTMLElement("fieldset")}} elements are not candidates for [constraint validation](/en-US/docs/Web/HTML/Constraint_validation). +The **`willValidate`** read-only property of the {{domxref("HTMLFieldSetElement")}} interface returns `false`, because {{HTMLElement("fieldset")}} elements are not candidates for [constraint validation](/en-US/docs/Web/HTML/Guides/Constraint_validation). ## Value @@ -28,4 +28,4 @@ The boolean value `false`. - {{HTMLElement("fieldset")}} - {{HTMLElement("form")}} - [Learn: Client-side form validation](/en-US/docs/Learn_web_development/Extensions/Forms/Form_validation) -- [Guide: Constraint validation](/en-US/docs/Web/HTML/Constraint_validation) +- [Guide: Constraint validation](/en-US/docs/Web/HTML/Guides/Constraint_validation) diff --git a/files/en-us/web/api/htmlfontelement/color/index.md b/files/en-us/web/api/htmlfontelement/color/index.md index 4951ded3f082998..f405a1a891279ab 100644 --- a/files/en-us/web/api/htmlfontelement/color/index.md +++ b/files/en-us/web/api/htmlfontelement/color/index.md @@ -12,7 +12,7 @@ browser-compat: api.HTMLFontElement.color The obsolete **`HTMLFontElement.color`** -property is a string that reflects the [`color`](/en-US/docs/Web/HTML/Element/font#color) HTML attribute, containing either a named color or a color specified in the +property is a string that reflects the [`color`](/en-US/docs/Web/HTML/Reference/Elements/font#color) HTML attribute, containing either a named color or a color specified in the hexadecimal #RRGGBB format. The format of the string must follow one of the following HTML microsyntaxes (see [`<color>`](/en-US/docs/Web/CSS/color_value)): diff --git a/files/en-us/web/api/htmlfontelement/face/index.md b/files/en-us/web/api/htmlfontelement/face/index.md index 7ccade456c926b3..1ca4b6d59d2b741 100644 --- a/files/en-us/web/api/htmlfontelement/face/index.md +++ b/files/en-us/web/api/htmlfontelement/face/index.md @@ -12,7 +12,7 @@ browser-compat: api.HTMLFontElement.face The obsolete **`HTMLFontElement.face`** -property is a string that reflects the [`face`](/en-US/docs/Web/HTML/Element/font#face) HTML attribute, containing a comma-separated list of one or more font +property is a string that reflects the [`face`](/en-US/docs/Web/HTML/Reference/Elements/font#face) HTML attribute, containing a comma-separated list of one or more font names. The document text, in the default style, is rendered as the first font face that the diff --git a/files/en-us/web/api/htmlfontelement/index.md b/files/en-us/web/api/htmlfontelement/index.md index f8abda97c5a77e8..2fe86644a9cac91 100644 --- a/files/en-us/web/api/htmlfontelement/index.md +++ b/files/en-us/web/api/htmlfontelement/index.md @@ -18,11 +18,11 @@ Implements the document object model (DOM) representation of the font element. T _Inherits properties from its parent, {{domxref("HTMLElement")}}._ - {{domxref("HTMLFontElement.color")}} {{Deprecated_Inline}} - - : A string that reflects the [`color`](/en-US/docs/Web/HTML/Element/font#color) HTML attribute, containing either a named color or a color specified in the hexadecimal #RRGGBB format. + - : A string that reflects the [`color`](/en-US/docs/Web/HTML/Reference/Elements/font#color) HTML attribute, containing either a named color or a color specified in the hexadecimal #RRGGBB format. - {{domxref("HTMLFontElement.face")}} {{Deprecated_Inline}} - - : A string that reflects the [`face`](/en-US/docs/Web/HTML/Element/font#face) HTML attribute, containing a comma-separated list of one or more font names. + - : A string that reflects the [`face`](/en-US/docs/Web/HTML/Reference/Elements/font#face) HTML attribute, containing a comma-separated list of one or more font names. - {{domxref("HTMLFontElement.size")}} {{Deprecated_Inline}} - - : A string that reflects the [`size`](/en-US/docs/Web/HTML/Element/font#size) HTML attribute, containing either a font size ranging from 1 to 7 or a number relative to the default value 3, for example -2 or +1. + - : A string that reflects the [`size`](/en-US/docs/Web/HTML/Reference/Elements/font#size) HTML attribute, containing either a font size ranging from 1 to 7 or a number relative to the default value 3, for example -2 or +1. ## Instance methods diff --git a/files/en-us/web/api/htmlfontelement/size/index.md b/files/en-us/web/api/htmlfontelement/size/index.md index 8de3b104eabc304..f4dd00753804d1c 100644 --- a/files/en-us/web/api/htmlfontelement/size/index.md +++ b/files/en-us/web/api/htmlfontelement/size/index.md @@ -12,7 +12,7 @@ browser-compat: api.HTMLFontElement.size The obsolete **`HTMLFontElement.size`** property is a -string that reflects the [`size`](/en-US/docs/Web/HTML/Element/font#size) HTML +string that reflects the [`size`](/en-US/docs/Web/HTML/Reference/Elements/font#size) HTML attribute. It contains either a font size ranging from 1 to 7 or a number relative to the default value 3, for example -2 or +1. diff --git a/files/en-us/web/api/htmlformelement/acceptcharset/index.md b/files/en-us/web/api/htmlformelement/acceptcharset/index.md index 64e785724e42f14..0564be8fccb3a51 100644 --- a/files/en-us/web/api/htmlformelement/acceptcharset/index.md +++ b/files/en-us/web/api/htmlformelement/acceptcharset/index.md @@ -12,7 +12,7 @@ The **`HTMLFormElement.acceptCharset`** property represents the {{glossary("char The specification allows a single case-insensitive value of `"UTF-8"`, reflecting the ubiquity of this encoding (historically multiple character encodings could be specified as a comma-separated or space-separated list). -This reflects the value of the form's [`accept-charset`](/en-US/docs/Web/HTML/Element/form#accept-charset) HTML attribute. +This reflects the value of the form's [`accept-charset`](/en-US/docs/Web/HTML/Reference/Elements/form#accept-charset) HTML attribute. ## Value diff --git a/files/en-us/web/api/htmlformelement/autocomplete/index.md b/files/en-us/web/api/htmlformelement/autocomplete/index.md index 769498ae7251cc7..321d1cafc675a4d 100644 --- a/files/en-us/web/api/htmlformelement/autocomplete/index.md +++ b/files/en-us/web/api/htmlformelement/autocomplete/index.md @@ -8,7 +8,7 @@ browser-compat: api.HTMLFormElement.autocomplete {{ APIRef("HTML DOM") }} -The **`autocomplete`** property of the {{DOMxRef("HTMLFormElement")}} interface indicates whether the value of the form's controls can be automatically completed by the browser. It reflects the {{htmlelement("form")}} element's [`autocomplete`](/en-US/docs/Web/HTML/Attributes/autocomplete) attribute. +The **`autocomplete`** property of the {{DOMxRef("HTMLFormElement")}} interface indicates whether the value of the form's controls can be automatically completed by the browser. It reflects the {{htmlelement("form")}} element's [`autocomplete`](/en-US/docs/Web/HTML/Reference/Attributes/autocomplete) attribute. ## Value @@ -32,6 +32,6 @@ console.log(formElement.autocomplete); ## See also - {{HTMLElement("form")}} -- HTML [`autocomplete`](/en-US/docs/Web/HTML/Attributes/autocomplete) attribute -- ARIA [`aria-autocomplete`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-autocomplete) attribute +- HTML [`autocomplete`](/en-US/docs/Web/HTML/Reference/Attributes/autocomplete) attribute +- ARIA [`aria-autocomplete`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-autocomplete) attribute - [Turning off autocompletion](/en-US/docs/Web/Security/Practical_implementation_guides/Turning_off_form_autocompletion) diff --git a/files/en-us/web/api/htmlformelement/checkvalidity/index.md b/files/en-us/web/api/htmlformelement/checkvalidity/index.md index 116892548642355..c21deb82ea44aec 100644 --- a/files/en-us/web/api/htmlformelement/checkvalidity/index.md +++ b/files/en-us/web/api/htmlformelement/checkvalidity/index.md @@ -8,7 +8,7 @@ browser-compat: api.HTMLFormElement.checkValidity {{APIRef("HTML DOM")}} -The **`checkValidity()`** method of the {{domxref("HTMLFormElement")}} interface returns a boolean value which indicates if all associated controls meet any [constraint validation](/en-US/docs/Web/HTML/Constraint_validation) rules applied to them. The method also fires an {{domxref("HTMLElement/invalid_event", "invalid")}} event on each invalid element, but not on the form element itself. Because there's no default browser behavior for `checkValidity()`, canceling this `invalid` event has no effect. +The **`checkValidity()`** method of the {{domxref("HTMLFormElement")}} interface returns a boolean value which indicates if all associated controls meet any [constraint validation](/en-US/docs/Web/HTML/Guides/Constraint_validation) rules applied to them. The method also fires an {{domxref("HTMLElement/invalid_event", "invalid")}} event on each invalid element, but not on the form element itself. Because there's no default browser behavior for `checkValidity()`, canceling this `invalid` event has no effect. > [!NOTE] > The {{cssxref(":valid")}} and {{cssxref(":invalid")}} CSS pseudo-classes are applied to `<form>` elements based on the validity of its owned form controls, not the validity of the `<form>` element itself. @@ -49,4 +49,4 @@ console.log(element.checkValidity()); - {{domxref("HTMLFormElement.reportValidity()")}} - {{HTMLElement("form")}} - [Learn: Client-side form validation](/en-US/docs/Learn_web_development/Extensions/Forms/Form_validation) -- [Guide: Constraint validation](/en-US/docs/Web/HTML/Constraint_validation) +- [Guide: Constraint validation](/en-US/docs/Web/HTML/Guides/Constraint_validation) diff --git a/files/en-us/web/api/htmlformelement/elements/index.md b/files/en-us/web/api/htmlformelement/elements/index.md index d220327d0ef775b..7045477f9867ba8 100644 --- a/files/en-us/web/api/htmlformelement/elements/index.md +++ b/files/en-us/web/api/htmlformelement/elements/index.md @@ -38,7 +38,7 @@ Only the following elements are returned: - {{HTMLElement("button")}} - {{HTMLElement("fieldset")}} -- {{HTMLElement("input")}} (with the exception that any whose [`type`](/en-US/docs/Web/HTML/Element/input#type) is `"image"` are omitted for historical reasons) +- {{HTMLElement("input")}} (with the exception that any whose [`type`](/en-US/docs/Web/HTML/Reference/Elements/input#type) is `"image"` are omitted for historical reasons) - {{HTMLElement("object")}} - {{HTMLElement("output")}} - {{HTMLElement("select")}} @@ -78,17 +78,17 @@ const inputByName = inputs["username"]; This example gets the form's element list, then iterates over the list, looking for {{HTMLElement("input")}} elements of type -[`"text"`](/en-US/docs/Web/HTML/Element/input/text) so that some +[`"text"`](/en-US/docs/Web/HTML/Reference/Elements/input/text) so that some form of processing can be performed on them. ```js const inputs = document.getElementById("my-form").elements; // Iterate over the form controls -for (let i = 0; i < inputs.length; i++) { - if (inputs[i].nodeName === "INPUT" && inputs[i].type === "text") { +for (const input of inputs) { + if (input.nodeName === "INPUT" && input.type === "text") { // Update text input - inputs[i].value.toLocaleUpperCase(); + input.value = input.value.toLocaleUpperCase(); } } ``` @@ -99,9 +99,9 @@ for (let i = 0; i < inputs.length; i++) { const inputs = document.getElementById("my-form").elements; // Iterate over the form controls -for (let i = 0; i < inputs.length; i++) { +for (const input of inputs) { // Disable all form controls - inputs[i].setAttribute("disabled", ""); + input.setAttribute("disabled", ""); } ``` diff --git a/files/en-us/web/api/htmlformelement/enctype/index.md b/files/en-us/web/api/htmlformelement/enctype/index.md index fcca079af262f76..6df79686f62f8f7 100644 --- a/files/en-us/web/api/htmlformelement/enctype/index.md +++ b/files/en-us/web/api/htmlformelement/enctype/index.md @@ -16,7 +16,7 @@ to submit the form to the server. Possible values are: element(s) to upload file data. - `text/plain`: Ambiguous format, human-readable content not reliably interpretable by computer. -This value can be overridden by a [`formenctype`](/en-US/docs/Web/HTML/Element/button#formenctype) attribute +This value can be overridden by a [`formenctype`](/en-US/docs/Web/HTML/Reference/Elements/button#formenctype) attribute on a {{HTMLElement("button")}} or {{HTMLElement("input")}} element. ## Value diff --git a/files/en-us/web/api/htmlformelement/formdata_event/index.md b/files/en-us/web/api/htmlformelement/formdata_event/index.md index 870c55b317f5c7d..f9f4a0ced4107ee 100644 --- a/files/en-us/web/api/htmlformelement/formdata_event/index.md +++ b/files/en-us/web/api/htmlformelement/formdata_event/index.md @@ -16,10 +16,10 @@ This event is not cancelable and does not bubble. Use the event name in methods like {{domxref("EventTarget.addEventListener", "addEventListener()")}}, or set an event handler property. -```js -addEventListener("formdata", (event) => {}); +```js-nolint +addEventListener("formdata", (event) => { }) -onformdata = (event) => {}; +onformdata = (event) => { } ``` ## Event type diff --git a/files/en-us/web/api/htmlformelement/index.md b/files/en-us/web/api/htmlformelement/index.md index e61e8c749989a9b..b51d6c3d81e313d 100644 --- a/files/en-us/web/api/htmlformelement/index.md +++ b/files/en-us/web/api/htmlformelement/index.md @@ -15,37 +15,41 @@ The **`HTMLFormElement`** interface represents a {{HTMLElement("form")}} element _This interface also inherits properties from its parent, {{domxref("HTMLElement")}}._ +- {{domxref("HTMLFormElement.acceptCharset")}} + - : A string reflecting the value of the form's [`accept-charset`](/en-US/docs/Web/HTML/Reference/Elements/form#accept-charset) HTML attribute. +- {{domxref("HTMLFormElement.action")}} + - : A string reflecting the value of the form's [`action`](/en-US/docs/Web/HTML/Reference/Elements/form#action) HTML attribute, containing the URI of a program that processes the information submitted by the form. +- {{domxref("HTMLFormElement.autocomplete")}} + - : A string reflecting the value of the form's [`autocomplete`](/en-US/docs/Web/HTML/Reference/Attributes/autocomplete) HTML attribute, indicating whether the controls in this form can have their values automatically populated by the browser. +- {{domxref("HTMLFormElement.encoding")}} or {{domxref("HTMLFormElement.enctype")}} + - : A string reflecting the value of the form's [`enctype`](/en-US/docs/Web/HTML/Reference/Elements/form#enctype) HTML attribute, indicating the type of content that is used to transmit the form to the server. Only specified values can be set. The two properties are synonyms. - {{domxref("HTMLFormElement.elements")}} {{ReadOnlyInline}} - : A {{domxref("HTMLFormControlsCollection")}} holding all form controls belonging to this form element. - {{domxref("HTMLFormElement.length")}} {{ReadOnlyInline}} - : A `long` reflecting the number of controls in the form. - {{domxref("HTMLFormElement.name")}} - - : A string reflecting the value of the form's [`name`](/en-US/docs/Web/HTML/Element/form#name) HTML attribute, containing the name of the form. + - : A string reflecting the value of the form's [`name`](/en-US/docs/Web/HTML/Reference/Elements/form#name) HTML attribute, containing the name of the form. +- {{domxref("HTMLFormElement.noValidate")}} + - : A boolean value reflecting the value of the form's [`novalidate`](/en-US/docs/Web/HTML/Reference/Elements/form#novalidate) HTML attribute, indicating whether the form should not be validated. - {{domxref("HTMLFormElement.method")}} - - : A string reflecting the value of the form's [`method`](/en-US/docs/Web/HTML/Element/form#method) HTML attribute, indicating the HTTP method used to submit the form. Only specified values can be set. + - : A string reflecting the value of the form's [`method`](/en-US/docs/Web/HTML/Reference/Elements/form#method) HTML attribute, indicating the HTTP method used to submit the form. Only specified values can be set. +- {{domxref("HTMLFormElement.rel")}} + - : A string reflecting the value of the form's [`rel`](/en-US/docs/Web/HTML/Reference/Attributes/rel) HTML attribute, which represents what kinds of links the form creates as a space-separated list of enumerated values. +- {{domxref("HTMLFormElement.relList")}} {{ReadOnlyInline}} + - : A {{domxref("DOMTokenList")}} that reflects the [`rel`](/en-US/docs/Web/HTML/Reference/Attributes/rel) HTML attribute, as a list of tokens. - {{domxref("HTMLFormElement.target")}} - - : A string reflecting the value of the form's [`target`](/en-US/docs/Web/HTML/Element/form#target) HTML attribute, indicating where to display the results received from submitting the form. -- {{domxref("HTMLFormElement.action")}} - - : A string reflecting the value of the form's [`action`](/en-US/docs/Web/HTML/Element/form#action) HTML attribute, containing the URI of a program that processes the information submitted by the form. -- {{domxref("HTMLFormElement.encoding")}} or {{domxref("HTMLFormElement.enctype")}} - - : A string reflecting the value of the form's [`enctype`](/en-US/docs/Web/HTML/Element/form#enctype) HTML attribute, indicating the type of content that is used to transmit the form to the server. Only specified values can be set. The two properties are synonyms. -- {{domxref("HTMLFormElement.acceptCharset")}} - - : A string reflecting the value of the form's [`accept-charset`](/en-US/docs/Web/HTML/Element/form#accept-charset) HTML attribute. -- {{domxref("HTMLFormElement.autocomplete")}} - - : A string reflecting the value of the form's [`autocomplete`](/en-US/docs/Web/HTML/Element/form#autocomplete) HTML attribute, indicating whether the controls in this form can have their values automatically populated by the browser. -- {{domxref("HTMLFormElement.noValidate")}} - - : A boolean value reflecting the value of the form's [`novalidate`](/en-US/docs/Web/HTML/Element/form#novalidate) HTML attribute, indicating whether the form should not be validated. + - : A string reflecting the value of the form's [`target`](/en-US/docs/Web/HTML/Reference/Elements/form#target) HTML attribute, indicating where to display the results received from submitting the form. -Named inputs are added to their owner form instance as properties, and can overwrite native properties if they share the same name (e.g. a form with an input named `action` will have its `action` property return that input instead of the form's [`action`](/en-US/docs/Web/HTML/Element/form#action) HTML attribute). +Named inputs are added to their owner form instance as properties, and can overwrite native properties if they share the same name (e.g., a form with an input named `action` will have its `action` property return that input instead of the form's [`action`](/en-US/docs/Web/HTML/Reference/Elements/form#action) HTML attribute). ## Instance methods _This interface also inherits methods from its parent, {{domxref("HTMLElement")}}._ - {{domxref("HTMLFormElement.checkValidity", "checkValidity()")}} - - : Returns `true` if the element's child controls are subject to [constraint validation](/en-US/docs/Web/HTML/Constraint_validation) and satisfy those constraints; returns `false` if some controls do not satisfy their constraints. Fires an event named {{domxref("HTMLInputElement/invalid_event", "invalid")}} at any control that does not satisfy its constraints; such controls are considered invalid if the event is not canceled. It is up to the programmer to decide how to respond to `false`. + - : Returns `true` if the element's child controls are subject to [constraint validation](/en-US/docs/Web/HTML/Guides/Constraint_validation) and satisfy those constraints; returns `false` if some controls do not satisfy their constraints. Fires an event named {{domxref("HTMLInputElement/invalid_event", "invalid")}} at any control that does not satisfy its constraints; such controls are considered invalid if the event is not canceled. It is up to the programmer to decide how to respond to `false`. - {{domxref("HTMLFormElement.reportValidity", "reportValidity()")}} - - : Returns `true` if the element's child controls satisfy their [validation constraints](/en-US/docs/Web/HTML/Constraint_validation). When `false` is returned, cancelable {{domxref("HTMLInputElement/invalid_event", "invalid")}} events are fired for each invalid child and validation problems are reported to the user. + - : Returns `true` if the element's child controls satisfy their [validation constraints](/en-US/docs/Web/HTML/Guides/Constraint_validation). When `false` is returned, cancelable {{domxref("HTMLInputElement/invalid_event", "invalid")}} events are fired for each invalid child and validation problems are reported to the user. - {{domxref("HTMLFormElement.requestSubmit", "requestSubmit()")}} - : Requests that the form be submitted using the specified submit button and its corresponding configuration. - {{domxref("HTMLFormElement.reset", "reset()")}} @@ -107,7 +111,7 @@ The elements included by `HTMLFormElement.elements` and `HTMLFormElement.length` - {{HTMLElement("button")}} - {{HTMLElement("fieldset")}} -- {{HTMLElement("input")}} (with the exception that any whose [`type`](/en-US/docs/Web/HTML/Element/input#type) is `"image"` are omitted for historical reasons) +- {{HTMLElement("input")}} (with the exception that any whose [`type`](/en-US/docs/Web/HTML/Reference/Elements/input#type) is `"image"` are omitted for historical reasons) - {{HTMLElement("object")}} - {{HTMLElement("output")}} - {{HTMLElement("select")}} diff --git a/files/en-us/web/api/htmlformelement/novalidate/index.md b/files/en-us/web/api/htmlformelement/novalidate/index.md index a0fb9694684bc45..a22d568d1f8e9f8 100644 --- a/files/en-us/web/api/htmlformelement/novalidate/index.md +++ b/files/en-us/web/api/htmlformelement/novalidate/index.md @@ -8,7 +8,7 @@ browser-compat: api.HTMLFormElement.noValidate {{APIRef("HTML DOM")}} -The **`noValidate`** property of the {{domxref("HTMLFormElement")}} interface is a boolean value indicating if the {{htmlelement("form")}} will bypass [constraint validation](/en-US/docs/Web/HTML/Constraint_validation) when submitted. It reflects the `<form>` element's [`novalidate`](/en-US/docs/Web/HTML/Element/form#novalidate) attribute; if the attribute present, the value is `true`. +The **`noValidate`** property of the {{domxref("HTMLFormElement")}} interface is a boolean value indicating if the {{htmlelement("form")}} will bypass [constraint validation](/en-US/docs/Web/HTML/Guides/Constraint_validation) when submitted. It reflects the `<form>` element's [`novalidate`](/en-US/docs/Web/HTML/Reference/Elements/form#novalidate) attribute; if the attribute present, the value is `true`. If this attribute is not set or the value is set to `false`, the form is validated. This can be overridden by setting the {{domxref("HTMLInputElement.formNoValidate")}} or {{domxref("HTMLButtonElement.formNoValidate")}} property to `true`, either via JavaScript or the HTML `formnovalidate` attribute, for the control used to submit the form. @@ -43,4 +43,4 @@ console.log(element.noValidate); - {{domxref("HTMLFormElement.target")}} - {{HTMLElement("form")}} - [Learn: Client-side form validation](/en-US/docs/Learn_web_development/Extensions/Forms/Form_validation) -- [Guide: Constraint validation](/en-US/docs/Web/HTML/Constraint_validation) +- [Guide: Constraint validation](/en-US/docs/Web/HTML/Guides/Constraint_validation) diff --git a/files/en-us/web/api/htmlformelement/rel/index.md b/files/en-us/web/api/htmlformelement/rel/index.md new file mode 100644 index 000000000000000..8ac5f84ed436bf5 --- /dev/null +++ b/files/en-us/web/api/htmlformelement/rel/index.md @@ -0,0 +1,40 @@ +--- +title: "HTMLFormElement: rel property" +short-title: rel +slug: Web/API/HTMLFormElement/rel +page-type: web-api-instance-property +browser-compat: api.HTMLFormElement.rel +--- + +{{APIRef("HTML DOM")}} + +The **`rel`** property of the {{domxref("HTMLFormElement")}} interface reflects the [`rel`](/en-US/docs/Web/HTML/Reference/Attributes/rel) attribute. It is a string containing what kinds of links the HTML {{HTMLElement("form")}} element creates, as a space-separated list of enumerated values. + +To retrieve the value as an array of tokens, use {{domxref("HTMLFormElement.relList")}}. + +## Value + +A string. + +## Examples + +```js +const form = document.querySelector("form"); +console.log(form.rel); + +form.rel = "noopener noreferrer"; +``` + +## Specifications + +{{Specifications}} + +## Browser compatibility + +{{Compat}} + +## See also + +- {{domxref("HTMLFormElement.relList")}} +- {{domxref("HTMLLinkElement.rel")}} +- {{domxref("HTMLAnchorElement.rel")}} diff --git a/files/en-us/web/api/htmlformelement/rellist/index.md b/files/en-us/web/api/htmlformelement/rellist/index.md new file mode 100644 index 000000000000000..d37d2cf403e4a0e --- /dev/null +++ b/files/en-us/web/api/htmlformelement/rellist/index.md @@ -0,0 +1,42 @@ +--- +title: "HTMLFormElement: relList property" +short-title: relList +slug: Web/API/HTMLFormElement/relList +page-type: web-api-instance-property +browser-compat: api.HTMLFormElement.relList +--- + +{{APIRef("HTML DOM")}} + +The **`relList`** read-only property of the {{domxref("HTMLFormElement")}} interface reflects the [`rel`](/en-US/docs/Web/HTML/Reference/Attributes/rel) attribute. It is a live {{domxref("DOMTokenList")}} containing the set of link types indicating the relationship between the resource represented by the {{HTMLElement("form")}} element and the current document. + +The property itself is read-only, meaning you can not reassign the property with another {{domxref("DOMTokenList")}}, but the content of the returned list can be changed. + +To retrieve a string containing the values as space-separated tokens, use {{domxref("HTMLFormElement.rel")}}. The `rel` property can also be used to set the `rel` attribute value. + +## Value + +A live {{domxref("DOMTokenList")}} of strings. + +## Examples + +```js +const form = document.querySelector("form"); +form.relList.forEach((relEntry) => { + console.log(relEntry); +}); +``` + +## Specifications + +{{Specifications}} + +## Browser compatibility + +{{Compat}} + +## See also + +- {{domxref("HTMLAnchorElement.relList")}} +- {{domxref("HTMLLinkElement.relList")}} +- {{domxref("HTMLFormElement.rel")}} diff --git a/files/en-us/web/api/htmlformelement/reportvalidity/index.md b/files/en-us/web/api/htmlformelement/reportvalidity/index.md index 21035d01fd2d6bd..d2993a2f2573c39 100644 --- a/files/en-us/web/api/htmlformelement/reportvalidity/index.md +++ b/files/en-us/web/api/htmlformelement/reportvalidity/index.md @@ -49,4 +49,4 @@ document.forms["my-form"].addEventListener( - {{domxref("HTMLFormElement.checkValidity()")}} - {{HTMLElement("form")}} - [Learn: Client-side form validation](/en-US/docs/Learn_web_development/Extensions/Forms/Form_validation) -- [Guide: Constraint validation](/en-US/docs/Web/HTML/Constraint_validation) +- [Guide: Constraint validation](/en-US/docs/Web/HTML/Guides/Constraint_validation) diff --git a/files/en-us/web/api/htmlformelement/requestsubmit/index.md b/files/en-us/web/api/htmlformelement/requestsubmit/index.md index e68467ce97e02c5..3d15d8976ebb495 100644 --- a/files/en-us/web/api/htmlformelement/requestsubmit/index.md +++ b/files/en-us/web/api/htmlformelement/requestsubmit/index.md @@ -24,9 +24,9 @@ requestSubmit(submitter) - : A {{Glossary("submit button")}} that is a member of the form. - If the `submitter` specifies `form*` attributes, they [will override](/en-US/docs/Glossary/Submit_button#overriding_the_forms_behavior) the form's submission behavior (e.g. `formmethod="POST"`). + If the `submitter` specifies `form*` attributes, they [will override](/en-US/docs/Glossary/Submit_button#overriding_the_forms_behavior) the form's submission behavior (e.g., `formmethod="POST"`). - If the `submitter` has a `name` attribute or is an `{{HtmlElement('input/image', '&lt;input type="image"&gt;')}}`, its data [will be included](/en-US/docs/Glossary/Submit_button#form_data_entries) in the form submission (e.g. `btnName=btnValue`). + If the `submitter` has a `name` attribute or is an `{{HtmlElement('input/image', '&lt;input type="image"&gt;')}}`, its data [will be included](/en-US/docs/Glossary/Submit_button#form_data_entries) in the form submission (e.g., `btnName=btnValue`). If you omit the `submitter` parameter, the form element itself is used as the submitter. @@ -41,7 +41,7 @@ None ({{jsxref("undefined")}}). - `NotFoundError` {{domxref("DOMException")}} - : Thrown if the specified `submitter` isn't a member of the form on which `requestSubmit()` was called. The submitter must be either a - descendant of the form element or must have a [`form`](/en-US/docs/Web/HTML/Element/input#form) + descendant of the form element or must have a [`form`](/en-US/docs/Web/HTML/Reference/Elements/input#form) attribute referring to the form. ## Usage notes diff --git a/files/en-us/web/api/htmlformelement/reset/index.md b/files/en-us/web/api/htmlformelement/reset/index.md index c1a734386b3e1a1..9c01977cb48d326 100644 --- a/files/en-us/web/api/htmlformelement/reset/index.md +++ b/files/en-us/web/api/htmlformelement/reset/index.md @@ -10,7 +10,7 @@ browser-compat: api.HTMLFormElement.reset The **`HTMLFormElement.reset()`** method restores a form element's default values. This method does the same thing as clicking the form's -[`<input type="reset">`](/en-US/docs/Web/HTML/Element/input/reset) control. +[`<input type="reset">`](/en-US/docs/Web/HTML/Reference/Elements/input/reset) control. If a form control (such as a reset button) has a name or id of _reset_ it will mask the form's reset method. It does not reset other attributes in the input, such as diff --git a/files/en-us/web/api/htmlformelement/reset_event/index.md b/files/en-us/web/api/htmlformelement/reset_event/index.md index 7dc3f477f386b9e..35e37d50891fc77 100644 --- a/files/en-us/web/api/htmlformelement/reset_event/index.md +++ b/files/en-us/web/api/htmlformelement/reset_event/index.md @@ -14,10 +14,10 @@ The **`reset`** event fires when a {{HTMLElement("form")}} is reset. Use the event name in methods like {{domxref("EventTarget.addEventListener", "addEventListener()")}}, or set an event handler property. -```js -addEventListener("reset", (event) => {}); +```js-nolint +addEventListener("reset", (event) => { }) -onreset = (event) => {}; +onreset = (event) => { } ``` ## Event type diff --git a/files/en-us/web/api/htmlformelement/submit/index.md b/files/en-us/web/api/htmlformelement/submit/index.md index 13aa4152f482e12..5f089a3bb53043b 100644 --- a/files/en-us/web/api/htmlformelement/submit/index.md +++ b/files/en-us/web/api/htmlformelement/submit/index.md @@ -15,7 +15,7 @@ This method is similar, but not identical to, activating a form's submit {{HtmlElement("button")}}. When invoking this method directly, however: - No {{domxref("HTMLFormElement/submit_event", "submit")}} event is raised. In particular, the form's `onsubmit` event handler is not run. -- [Constraint validation](/en-US/docs/Web/HTML/Constraint_validation) is not triggered. +- [Constraint validation](/en-US/docs/Web/HTML/Guides/Constraint_validation) is not triggered. The {{domxref("HTMLFormElement.requestSubmit()")}} method is identical to activating a form's submit {{HtmlElement("button")}} and does not have these differences. diff --git a/files/en-us/web/api/htmlformelement/submit_event/index.md b/files/en-us/web/api/htmlformelement/submit_event/index.md index 53e57f1ec78ab85..b2e2848e2bf7aaa 100644 --- a/files/en-us/web/api/htmlformelement/submit_event/index.md +++ b/files/en-us/web/api/htmlformelement/submit_event/index.md @@ -15,7 +15,7 @@ Note that the `submit` event fires on the `<form>` element itself, and not on an The `submit` event fires when: - the user clicks a {{Glossary("submit button")}}, -- the user presses <kbd>Enter</kbd> while editing a field (e.g. {{HtmlElement('input/text', '&lt;input type="text"&gt;')}}) in a form, +- the user presses <kbd>Enter</kbd> while editing a field (e.g., {{HtmlElement('input/text', '&lt;input type="text"&gt;')}}) in a form, - a script calls the {{domxref("HTMLFormElement.requestSubmit()", "form.requestSubmit()")}} method However, the event is _not_ sent to the form when a script calls the {{domxref("HTMLFormElement.submit()", "form.submit()")}} method directly. @@ -27,10 +27,10 @@ However, the event is _not_ sent to the form when a script calls the {{domxref(" Use the event name in methods like {{domxref("EventTarget.addEventListener", "addEventListener()")}}, or set an event handler property. -```js -addEventListener("submit", (event) => {}); +```js-nolint +addEventListener("submit", (event) => { }) -onsubmit = (event) => {}; +onsubmit = (event) => { } ``` ## Event type diff --git a/files/en-us/web/api/htmlheadelement/index.md b/files/en-us/web/api/htmlheadelement/index.md index 9e850a32303dccb..e64580c8b975d84 100644 --- a/files/en-us/web/api/htmlheadelement/index.md +++ b/files/en-us/web/api/htmlheadelement/index.md @@ -13,10 +13,7 @@ The **`HTMLHeadElement`** interface contains the descriptive information, or met ## Instance properties -_Inherits properties from its parent, {{domxref("HTMLElement")}}._ - -- {{domxref("HTMLHeadElement.profile")}} {{deprecated_inline}} - - : A string representing the URIs of one or more metadata profiles (white space separated). +_No specific properties; inherits properties from its parent, {{domxref("HTMLElement")}}._ ## Instance methods diff --git a/files/en-us/web/api/htmlheadingelement/index.md b/files/en-us/web/api/htmlheadingelement/index.md index 97da65ffae66c47..a3f2b52dc82b641 100644 --- a/files/en-us/web/api/htmlheadingelement/index.md +++ b/files/en-us/web/api/htmlheadingelement/index.md @@ -7,7 +7,7 @@ browser-compat: api.HTMLHeadingElement {{ APIRef("HTML DOM") }} -The **`HTMLHeadingElement`** interface represents the different heading elements, [`<h1>` through `<h6>`](/en-US/docs/Web/HTML/Element/Heading_Elements). It inherits methods and properties from the {{domxref("HTMLElement")}} interface. +The **`HTMLHeadingElement`** interface represents the different heading elements, [`<h1>` through `<h6>`](/en-US/docs/Web/HTML/Reference/Elements/Heading_Elements). It inherits methods and properties from the {{domxref("HTMLElement")}} interface. {{InheritanceDiagram}} diff --git a/files/en-us/web/api/htmliframeelement/allow/index.md b/files/en-us/web/api/htmliframeelement/allow/index.md index eceda512ed05928..ed89d0644baba90 100644 --- a/files/en-us/web/api/htmliframeelement/allow/index.md +++ b/files/en-us/web/api/htmliframeelement/allow/index.md @@ -8,17 +8,17 @@ browser-compat: api.HTMLIFrameElement.allow {{APIRef("HTML DOM")}} -The **`allow`** property of the {{domxref("HTMLIFrameElement")}} interface indicates the [Permissions Policy](/en-US/docs/Web/HTTP/Permissions_Policy) specified for this `<iframe>` element. The policy defines what features are available to the `<iframe>` element (for example, access to the `microphone`, `camera`, `battery`, `web-share`, etc.) based on the origin of the request. +The **`allow`** property of the {{domxref("HTMLIFrameElement")}} interface indicates the [Permissions Policy](/en-US/docs/Web/HTTP/Guides/Permissions_Policy) specified for this `<iframe>` element. The policy defines what features are available to the `<iframe>` element (for example, access to the `microphone`, `camera`, `battery`, `web-share`, etc.) based on the origin of the request. The Permissions Policy specified by the `allow` attribute implements a further restriction on top of the policy specified in the {{HTTPHeader("Permissions-Policy")}} header. It doesn't replace it. -See [`<iframe>`'s Permissions Policy syntax](/en-US/docs/Web/HTTP/Headers/Permissions-Policy#iframes) for more details. +See [`<iframe>`'s Permissions Policy syntax](/en-US/docs/Web/HTTP/Reference/Headers/Permissions-Policy#iframes) for more details. It reflects the `allow` attribute of the {{HTMLElement("iframe")}} element. ## Value -A string indicates the [Permissions Policy](/en-US/docs/Web/HTTP/Permissions_Policy) specified for this {{HTMLElement("iframe")}} element, each policy must be separated by space. +A string indicates the [Permissions Policy](/en-US/docs/Web/HTTP/Guides/Permissions_Policy) specified for this {{HTMLElement("iframe")}} element, each policy must be separated by space. ## Examples @@ -34,7 +34,7 @@ const el = document.getElementById("el"); console.log(el.allow); // Output: "geolocation 'self' https://a.example.com https://b.example.com; fullscreen 'none'" ``` -See [Permissions Policy in `<iframe>` element](/en-US/docs/Web/HTTP/Headers/Permissions-Policy#iframes) for more available examples. +See [Permissions Policy in `<iframe>` element](/en-US/docs/Web/HTTP/Reference/Headers/Permissions-Policy#iframes) for more available examples. ## Specifications @@ -46,4 +46,4 @@ See [Permissions Policy in `<iframe>` element](/en-US/docs/Web/HTTP/Headers/Perm ## See also -- [Permissions Policy](/en-US/docs/Web/HTTP/Permissions_Policy) +- [Permissions Policy](/en-US/docs/Web/HTTP/Guides/Permissions_Policy) diff --git a/files/en-us/web/api/htmliframeelement/allowfullscreen/index.md b/files/en-us/web/api/htmliframeelement/allowfullscreen/index.md index 29049dbf8f4a215..d90b942b66d5156 100644 --- a/files/en-us/web/api/htmliframeelement/allowfullscreen/index.md +++ b/files/en-us/web/api/htmliframeelement/allowfullscreen/index.md @@ -40,5 +40,5 @@ console.log(el.allowFullscreen); // Output: true - [Fullscreen API](/en-US/docs/Web/API/Fullscreen_API) - {{domxref("Element.requestFullscreen()")}} -- [Permissions Policy](/en-US/docs/Web/HTTP/Permissions_Policy) +- [Permissions Policy](/en-US/docs/Web/HTTP/Guides/Permissions_Policy) - {{httpheader("Permissions-Policy/fullscreen", "fullscreen")}} Permissions Policy directive diff --git a/files/en-us/web/api/htmliframeelement/csp/index.md b/files/en-us/web/api/htmliframeelement/csp/index.md index 9a439872ea201e1..234dfa44797c660 100644 --- a/files/en-us/web/api/htmliframeelement/csp/index.md +++ b/files/en-us/web/api/htmliframeelement/csp/index.md @@ -11,7 +11,7 @@ browser-compat: api.HTMLIFrameElement.csp {{APIRef("HTML DOM")}}{{SeeCompatTable}} The **`csp`** property of the {{domxref("HTMLIFrameElement")}} -interface specifies the [Content Security Policy](/en-US/docs/Web/HTTP/CSP) that an +interface specifies the [Content Security Policy](/en-US/docs/Web/HTTP/Guides/CSP) that an embedded document must agree to enforce upon itself. ## Value diff --git a/files/en-us/web/api/htmliframeelement/featurepolicy/index.md b/files/en-us/web/api/htmliframeelement/featurepolicy/index.md index d7e70f4a4a22bd0..49870932fc05e42 100644 --- a/files/en-us/web/api/htmliframeelement/featurepolicy/index.md +++ b/files/en-us/web/api/htmliframeelement/featurepolicy/index.md @@ -13,7 +13,7 @@ browser-compat: api.HTMLIFrameElement.featurePolicy The **`featurePolicy`** read-only property of the {{DOMxRef("HTMLIFrameElement")}} interface returns the {{DOMxRef("FeaturePolicy")}} interface which provides a simple API for introspecting -the [Permissions Policies](/en-US/docs/Web/HTTP/Permissions_Policy) applied to a specific frame. +the [Permissions Policies](/en-US/docs/Web/HTTP/Guides/Permissions_Policy) applied to a specific frame. ## Value diff --git a/files/en-us/web/api/htmliframeelement/getsvgdocument/index.md b/files/en-us/web/api/htmliframeelement/getsvgdocument/index.md index 4f093a94e08ac1a..7cacf4adbdfad5b 100644 --- a/files/en-us/web/api/htmliframeelement/getsvgdocument/index.md +++ b/files/en-us/web/api/htmliframeelement/getsvgdocument/index.md @@ -1,14 +1,14 @@ --- -title: "HTMLIframeElement: getSVGDocument() method" +title: "HTMLIFrameElement: getSVGDocument() method" short-title: getSVGDocument() -slug: Web/API/HTMLIframeElement/getSVGDocument +slug: Web/API/HTMLIFrameElement/getSVGDocument page-type: web-api-instance-method -browser-compat: api.HTMLIframeElement.getSVGDocument +browser-compat: api.HTMLIFrameElement.getSVGDocument --- {{APIRef("HTML DOM")}} -The **`getSVGDocument()`** method of the {{domxref("HTMLIframeElement")}} interface returns the {{domxref("Document")}} object of the embedded SVG. +The **`getSVGDocument()`** method of the {{domxref("HTMLIFrameElement")}} interface returns the {{domxref("Document")}} object of the embedded SVG. ## Syntax diff --git a/files/en-us/web/api/htmliframeelement/index.md b/files/en-us/web/api/htmliframeelement/index.md index e6544a0b5d0aa90..69e56b71623b4d7 100644 --- a/files/en-us/web/api/htmliframeelement/index.md +++ b/files/en-us/web/api/htmliframeelement/index.md @@ -18,7 +18,7 @@ _Inherits properties from its parent, {{domxref("HTMLElement")}}_. - {{domxref("HTMLIFrameElement.align")}} {{Deprecated_Inline}} - : A string that specifies the alignment of the frame with respect to the surrounding context. - {{domxref("HTMLIFrameElement.allow")}} - - : A string that indicates the [Permissions Policy](/en-US/docs/Web/HTTP/Permissions_Policy) specified for this `<iframe>`. + - : A string that indicates the [Permissions Policy](/en-US/docs/Web/HTTP/Guides/Permissions_Policy) specified for this `<iframe>`. - {{domxref("HTMLIFrameElement.allowFullscreen")}} - : A boolean value indicating whether the inline frame is willing to be placed into full screen mode. See [Using fullscreen mode](/en-US/docs/Web/API/Fullscreen_API) for details. - {{domxref("HTMLIFrameElement.allowPaymentRequest")}} {{Deprecated_Inline}} {{Non-standard_Inline}} @@ -34,14 +34,14 @@ _Inherits properties from its parent, {{domxref("HTMLElement")}}_. - {{domxref("HTMLIFrameElement.csp")}} {{Experimental_Inline}} - : Specifies the Content Security Policy that an embedded document must agree to enforce upon itself. - {{domxref("HTMLIFrameElement.featurePolicy")}} {{ReadOnlyInline}} {{Experimental_Inline}} - - : Returns the {{domxref("FeaturePolicy")}} interface which provides a simple API for introspecting the [Permissions Policies](/en-US/docs/Web/HTTP/Permissions_Policy) applied to a specific document. + - : Returns the {{domxref("FeaturePolicy")}} interface which provides a simple API for introspecting the [Permissions Policies](/en-US/docs/Web/HTTP/Guides/Permissions_Policy) applied to a specific document. - {{domxref("HTMLIFrameElement.frameBorder")}} {{Deprecated_Inline}} - : A string that indicates whether to create borders between frames. - {{domxref("HTMLIFrameElement.height")}} - - : A string that reflects the [`height`](/en-US/docs/Web/HTML/Element/iframe#height) HTML attribute, indicating the height of the frame. + - : A string that reflects the [`height`](/en-US/docs/Web/HTML/Reference/Elements/iframe#height) HTML attribute, indicating the height of the frame. - {{domxref("HTMLIFrameElement.loading")}} - : A string providing a hint to the browser that the iframe should be loaded immediately (`eager`) or on an as-needed basis (`lazy`). - This reflects the [`loading`](/en-US/docs/Web/HTML/Element/iframe#loading) HTML attribute. + This reflects the [`loading`](/en-US/docs/Web/HTML/Reference/Elements/iframe#loading) HTML attribute. - {{domxref("HTMLIFrameElement.longDesc")}} {{Deprecated_Inline}} - : A string that contains the URI of a long description of the frame. - {{domxref("HTMLIFrameElement.marginHeight")}} {{Deprecated_Inline}} @@ -49,25 +49,25 @@ _Inherits properties from its parent, {{domxref("HTMLElement")}}_. - {{domxref("HTMLIFrameElement.marginWidth")}} {{Deprecated_Inline}} - : A string being the width of the frame margin. - {{domxref("HTMLIFrameElement.name")}} - - : A string that reflects the [`name`](/en-US/docs/Web/HTML/Element/iframe#name) HTML attribute, containing a name by which to refer to the frame. + - : A string that reflects the [`name`](/en-US/docs/Web/HTML/Reference/Elements/iframe#name) HTML attribute, containing a name by which to refer to the frame. - {{domxref("HTMLIFrameElement.referrerPolicy")}} - - : A string that reflects the [`referrerPolicy`](/en-US/docs/Web/HTML/Element/iframe#referrerpolicy) HTML attribute indicating which referrer to use when fetching the linked resource. + - : A string that reflects the [`referrerPolicy`](/en-US/docs/Web/HTML/Reference/Elements/iframe#referrerpolicy) HTML attribute indicating which referrer to use when fetching the linked resource. - {{domxref("HTMLIFrameElement.sandbox")}} {{ReadOnlyInline}} - - : Returns a {{domxref("DOMTokenList")}} that reflects the [`sandbox`](/en-US/docs/Web/HTML/Element/iframe#sandbox) HTML attribute, indicating extra restrictions on the behavior of the nested content. + - : Returns a {{domxref("DOMTokenList")}} that reflects the [`sandbox`](/en-US/docs/Web/HTML/Reference/Elements/iframe#sandbox) HTML attribute, indicating extra restrictions on the behavior of the nested content. - {{domxref("HTMLIFrameElement.scrolling")}} {{Deprecated_Inline}} - : A string that indicates whether the browser should provide scrollbars for the frame. - {{domxref("HTMLIFrameElement.src")}} - - : A string that reflects the [`src`](/en-US/docs/Web/HTML/Element/iframe#src) HTML attribute, containing the address of the content to be embedded. Note that programmatically removing an `<iframe>`'s src attribute (e.g. via {{domxref("Element.removeAttribute()")}}) causes `about:blank` to be loaded in the frame in Firefox (from version 65), Chromium-based browsers, and Safari/iOS. + - : A string that reflects the [`src`](/en-US/docs/Web/HTML/Reference/Elements/iframe#src) HTML attribute, containing the address of the content to be embedded. Note that programmatically removing an `<iframe>`'s src attribute (e.g., via {{domxref("Element.removeAttribute()")}}) causes `about:blank` to be loaded in the frame in Firefox (from version 65), Chromium-based browsers, and Safari/iOS. - {{domxref("HTMLIFrameElement.srcdoc")}} - : A string that represents the content to display in the frame. - {{domxref("HTMLIFrameElement.width")}} - - : A string that reflects the [`width`](/en-US/docs/Web/HTML/Element/iframe#width) HTML attribute, indicating the width of the frame. + - : A string that reflects the [`width`](/en-US/docs/Web/HTML/Reference/Elements/iframe#width) HTML attribute, indicating the width of the frame. ## Instance methods _Also inherits methods from its parent interface, {{domxref("HTMLElement")}}._ -- {{domxref("HTMLIframeElement.getSVGDocument()")}} +- {{domxref("HTMLIFrameElement.getSVGDocument()")}} - : Returns the embedded SVG as a {{domxref("Document")}}. ## Specifications diff --git a/files/en-us/web/api/htmliframeelement/loading/index.md b/files/en-us/web/api/htmliframeelement/loading/index.md index fe06858ebcec0fa..1c1010d9ac1c10e 100644 --- a/files/en-us/web/api/htmliframeelement/loading/index.md +++ b/files/en-us/web/api/htmliframeelement/loading/index.md @@ -8,7 +8,7 @@ browser-compat: api.HTMLIFrameElement.loading {{APIRef("HTML DOM")}} -The **`loading`** property of the {{domxref("HTMLIFrameElement")}} interface is a string that provides a hint to the {{Glossary("user agent")}} indicating whether the [iframe](/en-US/docs/Web/HTML/Element/iframe) should be loaded immediately on page load, or only when it is needed. +The **`loading`** property of the {{domxref("HTMLIFrameElement")}} interface is a string that provides a hint to the {{Glossary("user agent")}} indicating whether the [iframe](/en-US/docs/Web/HTML/Reference/Elements/iframe) should be loaded immediately on page load, or only when it is needed. This can be used to optimize the loading of the document's contents. Iframes that are visible when the page loads can be downloaded immediately (eagerly), while iframes that are likely to be offscreen on initial page load can be downloaded lazily — just before they will appear in the window's {{Glossary("visual viewport")}}. diff --git a/files/en-us/web/api/htmliframeelement/referrerpolicy/index.md b/files/en-us/web/api/htmliframeelement/referrerpolicy/index.md index 119fc7a228b66c8..7110c5a33e0051e 100644 --- a/files/en-us/web/api/htmliframeelement/referrerpolicy/index.md +++ b/files/en-us/web/api/htmliframeelement/referrerpolicy/index.md @@ -10,7 +10,7 @@ browser-compat: api.HTMLIFrameElement.referrerPolicy The **`HTMLIFrameElement.referrerPolicy`** -property reflects the HTML [`referrerpolicy`](/en-US/docs/Web/HTML/Element/iframe#referrerpolicy) attribute of the +property reflects the HTML [`referrerpolicy`](/en-US/docs/Web/HTML/Reference/Elements/iframe#referrerpolicy) attribute of the {{HTMLElement("iframe")}} element defining which referrer is sent when fetching the resource. diff --git a/files/en-us/web/api/htmliframeelement/src/index.md b/files/en-us/web/api/htmliframeelement/src/index.md index 52d26363c2df233..32b4cea70730eb4 100644 --- a/files/en-us/web/api/htmliframeelement/src/index.md +++ b/files/en-us/web/api/htmliframeelement/src/index.md @@ -9,9 +9,9 @@ browser-compat: api.HTMLIFrameElement.src {{APIRef}} The **`HTMLIFrameElement.src`** -A string that reflects the [`src`](/en-US/docs/Web/HTML/Element/iframe#src) HTML attribute, containing the address of the content to be embedded. +A string that reflects the [`src`](/en-US/docs/Web/HTML/Reference/Elements/iframe#src) HTML attribute, containing the address of the content to be embedded. -Note that programmatically removing an `<iframe>`'s src attribute (e.g. via {{domxref("Element.removeAttribute()")}}) causes `about:blank` to be loaded in the frame. +Note that programmatically removing an `<iframe>`'s src attribute (e.g., via {{domxref("Element.removeAttribute()")}}) causes `about:blank` to be loaded in the frame. ## Example diff --git a/files/en-us/web/api/htmlimageelement/align/index.md b/files/en-us/web/api/htmlimageelement/align/index.md index e7f240f349b4d50..403f803e4931501 100644 --- a/files/en-us/web/api/htmlimageelement/align/index.md +++ b/files/en-us/web/api/htmlimageelement/align/index.md @@ -19,7 +19,7 @@ CSS property {{cssxref("vertical-align")}}, which does in fact also work on imag despite its name. You can also use the {{cssxref("float")}} property to float the image to the left or right margin. -The `align` property reflects the HTML [`align`](/en-US/docs/Web/HTML/Element/img#align) +The `align` property reflects the HTML [`align`](/en-US/docs/Web/HTML/Reference/Elements/img#align) content attribute. ## Value diff --git a/files/en-us/web/api/htmlimageelement/alt/index.md b/files/en-us/web/api/htmlimageelement/alt/index.md index 7aa41f321d8794a..d96f9fb9d965a48 100644 --- a/files/en-us/web/api/htmlimageelement/alt/index.md +++ b/files/en-us/web/api/htmlimageelement/alt/index.md @@ -178,7 +178,7 @@ Note the use of the `alt` attribute on the {{HTMLElement("img")}}, providing a g <img src="https://www.bitstampede.com/mdn-test/new-page.svg" alt="New Page!" - class="pageinfo-badge" /> + class="page-info-badge" /> <p class="contents"> Lorem ipsum dolor sit amet, consectetur adipiscing elit. Quisque quis orci ligula. Lorem ipsum dolor sit amet, consectetur adipiscing elit. In ac neque @@ -199,7 +199,7 @@ The main feature of the CSS here is the use of {{cssxref("clip-path")}} and {{cs max-width: 500px; } -.pageinfo-badge { +.page-info-badge { width: 9em; padding-right: 1em; float: left; diff --git a/files/en-us/web/api/htmlimageelement/attributionsrc/index.md b/files/en-us/web/api/htmlimageelement/attributionsrc/index.md index a729d450a5dd6ec..277f453480d9fa9 100644 --- a/files/en-us/web/api/htmlimageelement/attributionsrc/index.md +++ b/files/en-us/web/api/htmlimageelement/attributionsrc/index.md @@ -11,7 +11,7 @@ browser-compat: api.HTMLImageElement.attributionSrc {{APIRef("Attribution Reporting API")}}{{securecontext_header}}{{SeeCompatTable}} The -**`attributionSrc`** property of the {{domxref("HTMLImageElement")}} interface gets and sets the [`attributionsrc`](/en-US/docs/Web/HTML/Element/img#attributionsrc) attribute on an {{htmlelement("img")}} element programmatically, reflecting the value of that attribute. `attributionsrc` specifies that you want the browser to send an {{httpheader("Attribution-Reporting-Eligible")}} header along with the image request. +**`attributionSrc`** property of the {{domxref("HTMLImageElement")}} interface gets and sets the [`attributionsrc`](/en-US/docs/Web/HTML/Reference/Elements/img#attributionsrc) attribute on an {{htmlelement("img")}} element programmatically, reflecting the value of that attribute. `attributionsrc` specifies that you want the browser to send an {{httpheader("Attribution-Reporting-Eligible")}} header along with the image request. On the server-side this is used to trigger sending an {{httpheader("Attribution-Reporting-Register-Source")}} or {{httpheader("Attribution-Reporting-Register-Trigger")}} header in the response, to register an image-based [attribution source](/en-US/docs/Web/API/Attribution_Reporting_API/Registering_sources#html-based_event_sources) or [attribution trigger](/en-US/docs/Web/API/Attribution_Reporting_API/Registering_triggers#html-based_attribution_triggers), respectively. Which response header should be sent back depends on the value of the `Attribution-Reporting-Eligible` header that triggered the registration. @@ -26,7 +26,7 @@ See the [Attribution Reporting API](/en-US/docs/Web/API/Attribution_Reporting_AP A string. There are two versions of this property that you can get and set: -- Empty string, i.e. `imgElem.attributionSrc=""`. This specifies that you want the {{httpheader("Attribution-Reporting-Eligible")}} header sent to the same server as the `src` attribute points to. This is fine when you are handling the attribution source or trigger registration on the same server. When registering an attribution trigger this property is optional, and an empty string value will be used if it is omitted. +- Empty string, i.e., `imgElem.attributionSrc=""`. This specifies that you want the {{httpheader("Attribution-Reporting-Eligible")}} header sent to the same server as the `src` attribute points to. This is fine when you are handling the attribution source or trigger registration on the same server. When registering an attribution trigger this property is optional, and an empty string value will be used if it is omitted. - Value containing one or more URLs, for example: ```js diff --git a/files/en-us/web/api/htmlimageelement/complete/index.md b/files/en-us/web/api/htmlimageelement/complete/index.md index fc84376c79e24c8..51abc7973a992c2 100644 --- a/files/en-us/web/api/htmlimageelement/complete/index.md +++ b/files/en-us/web/api/htmlimageelement/complete/index.md @@ -19,7 +19,7 @@ otherwise, the value is `false`. The image is considered completely loaded if any of the following are true: -- Neither the [`src`](/en-US/docs/Web/HTML/Element/img#src) nor the [`srcset`](/en-US/docs/Web/HTML/Element/img#srcset) +- Neither the [`src`](/en-US/docs/Web/HTML/Reference/Elements/img#src) nor the [`srcset`](/en-US/docs/Web/HTML/Reference/Elements/img#srcset) attribute is specified. - The `srcset` attribute is absent and the `src` attribute, while specified, is the empty string (`""`). diff --git a/files/en-us/web/api/htmlimageelement/crossorigin/index.md b/files/en-us/web/api/htmlimageelement/crossorigin/index.md index 0762425f491f350..49759f0adf61a0a 100644 --- a/files/en-us/web/api/htmlimageelement/crossorigin/index.md +++ b/files/en-us/web/api/htmlimageelement/crossorigin/index.md @@ -48,7 +48,6 @@ The code below demonstrates setting the `crossOrigin` property on an newly-created image. ```js -const imageUrl = "clock-demo-400px.png"; const container = document.querySelector(".container"); function loadImage(url) { @@ -66,7 +65,7 @@ function loadImage(url) { image.src = url; } -loadImage(imageUrl); +loadImage("clock-demo-400px.png"); ``` ### HTML @@ -86,8 +85,7 @@ loadImage(imageUrl); ```css body { font: - 1.125rem/1.5, - Helvetica, + 1.125rem/1.5 Helvetica, sans-serif; } diff --git a/files/en-us/web/api/htmlimageelement/currentsrc/index.md b/files/en-us/web/api/htmlimageelement/currentsrc/index.md index ef930b78ee88c34..9f1113708b0163a 100644 --- a/files/en-us/web/api/htmlimageelement/currentsrc/index.md +++ b/files/en-us/web/api/htmlimageelement/currentsrc/index.md @@ -24,7 +24,7 @@ determine which image from the set of provided images was selected by the browse ## Examples In this example, two different sizes are provided for an image of a clock. One is 200px -wide and the other is 400px wide. The [`sizes`](/en-US/docs/Web/HTML/Element/img#sizes) attribute is +wide and the other is 400px wide. The [`sizes`](/en-US/docs/Web/HTML/Reference/Elements/img#sizes) attribute is provided to indicate that the image should be drawn at 50% of the document width if the viewport is under 400px wide; otherwise, the image is drawn at 90% width of the document. @@ -33,11 +33,11 @@ document. ```html <img - src="/en-US/docs/Web/HTML/Element/img/clock-demo-400px.png" + src="/en-US/docs/Web/HTML/Reference/Elements/img/clock-demo-400px.png" alt="Clock" srcset=" - /en-US/docs/Web/HTML/Element/img/clock-demo-200px.png 200w, - /en-US/docs/Web/HTML/Element/img/clock-demo-400px.png 400w + /en-US/docs/Web/HTML/Reference/Elements/img/clock-demo-200px.png 200w, + /en-US/docs/Web/HTML/Reference/Elements/img/clock-demo-400px.png 400w " sizes="(max-width: 400px) 50%, 90%" /> ``` diff --git a/files/en-us/web/api/htmlimageelement/fetchpriority/index.md b/files/en-us/web/api/htmlimageelement/fetchpriority/index.md index e1ddae007db41ad..c22b12f370274b5 100644 --- a/files/en-us/web/api/htmlimageelement/fetchpriority/index.md +++ b/files/en-us/web/api/htmlimageelement/fetchpriority/index.md @@ -9,14 +9,14 @@ browser-compat: api.HTMLImageElement.fetchPriority {{APIRef("HTML DOM")}} The **`fetchPriority`** property of the {{domxref("HTMLImageElement")}} interface represents a hint to the browser indicating how it should prioritize fetching a particular image relative to other images. -It reflects the [`fetchpriority`](/en-US/docs/Web/HTML/Element/img#fetchpriority) attribute of the corresponding {{htmlelement("img")}} element. +It reflects the [`fetchpriority`](/en-US/docs/Web/HTML/Reference/Elements/img#fetchpriority) attribute of the corresponding {{htmlelement("img")}} element. The property allows a developer to signal that fetching a particular image early in the loading process has more or less impact on user experience than a browser can reasonably infer when assigning an internal priority. This in turn allows the browser to increase or decrease the priority, and potentially load the image earlier or later than it would otherwise. The property should be used sparingly, as excessive or incorrect prioritization can degrade performance. -The fetch priority can be used to complement [preloading](/en-US/docs/Web/HTML/Attributes/rel/preload), allowing a developer to boost the priority ahead of less-impactful resources that have a higher default priority. -For example, if a developer knows that a particular image significantly contributes to the website's {{glossary("Largest Contentful Paint")}} (LCP) they could add [`<link rel="preload">`](/en-US/docs/Web/HTML/Attributes/rel/preload) for the image and then further boost the priority using the `fetchpriority` property. +The fetch priority can be used to complement [preloading](/en-US/docs/Web/HTML/Reference/Attributes/rel/preload), allowing a developer to boost the priority ahead of less-impactful resources that have a higher default priority. +For example, if a developer knows that a particular image significantly contributes to the website's {{glossary("Largest Contentful Paint")}} (LCP) they could add [`<link rel="preload">`](/en-US/docs/Web/HTML/Reference/Attributes/rel/preload) for the image and then further boost the priority using the `fetchpriority` property. Note that both the internal priority of any fetch operation, and the impact of `fetchPriority` on the priority, are entirely browser dependent. diff --git a/files/en-us/web/api/htmlimageelement/height/index.md b/files/en-us/web/api/htmlimageelement/height/index.md index ff043a37c38beb9..42bb0457b279385 100644 --- a/files/en-us/web/api/htmlimageelement/height/index.md +++ b/files/en-us/web/api/htmlimageelement/height/index.md @@ -28,8 +28,8 @@ defined depends on whether the image is being rendered to a visual medium or not ## Examples In this example, two different sizes are provided for an image of a clock using the -[`srcset`](/en-US/docs/Web/HTML/Element/img#srcset) attribute. One is 200px wide and the other is 400px -wide. Further, the [`sizes`](/en-US/docs/Web/HTML/Element/img#sizes) attribute is provided to specify the +[`srcset`](/en-US/docs/Web/HTML/Reference/Elements/img#srcset) attribute. One is 200px wide and the other is 400px +wide. Further, the [`sizes`](/en-US/docs/Web/HTML/Reference/Elements/img#sizes) attribute is provided to specify the width at which the image should be drawn given the viewport's width. ### HTML @@ -40,11 +40,11 @@ otherwise, it's drawn at 300px. ```html <p>Image height: <span class="size">?</span>px (resize to update)</p> <img - src="/en-US/docs/Web/HTML/Element/img/clock-demo-200px.png" + src="/en-US/docs/Web/HTML/Reference/Elements/img/clock-demo-200px.png" alt="Clock" srcset=" - /en-US/docs/Web/HTML/Element/img/clock-demo-200px.png 200w, - /en-US/docs/Web/HTML/Element/img/clock-demo-400px.png 400w + /en-US/docs/Web/HTML/Reference/Elements/img/clock-demo-200px.png 200w, + /en-US/docs/Web/HTML/Reference/Elements/img/clock-demo-400px.png 400w " sizes="(max-width: 400px) 200px, 300px" /> ``` diff --git a/files/en-us/web/api/htmlimageelement/hspace/index.md b/files/en-us/web/api/htmlimageelement/hspace/index.md index 6dc899f1804bf42..40669985c551a06 100644 --- a/files/en-us/web/api/htmlimageelement/hspace/index.md +++ b/files/en-us/web/api/htmlimageelement/hspace/index.md @@ -16,7 +16,7 @@ _obsolete_ **`hspace`** property of the space to leave empty on the left and right sides of the {{HTMLElement("img")}} element when laying out the page. -This property reflects the {{Glossary("HTML")}} [`hspace`](/en-US/docs/Web/HTML/Element/img#hspace) +This property reflects the {{Glossary("HTML")}} [`hspace`](/en-US/docs/Web/HTML/Reference/Elements/img#hspace) attribute. ## Value diff --git a/files/en-us/web/api/htmlimageelement/image/index.md b/files/en-us/web/api/htmlimageelement/image/index.md index 3b47653ac175a3f..f94bc911c28b03e 100644 --- a/files/en-us/web/api/htmlimageelement/image/index.md +++ b/files/en-us/web/api/htmlimageelement/image/index.md @@ -26,10 +26,10 @@ new Image(width, height) ### Parameters - `width` {{optional_inline}} - - : The width of the image (i.e., the value for the [`width`](/en-US/docs/Web/HTML/Element/img#width) + - : The width of the image (i.e., the value for the [`width`](/en-US/docs/Web/HTML/Reference/Elements/img#width) attribute). - `height` {{optional_inline}} - - : The height of the image (i.e., the value for the [`height`](/en-US/docs/Web/HTML/Element/img#height) + - : The height of the image (i.e., the value for the [`height`](/en-US/docs/Web/HTML/Reference/Elements/img#height) attribute). ## Usage note diff --git a/files/en-us/web/api/htmlimageelement/index.md b/files/en-us/web/api/htmlimageelement/index.md index 18b6a8456426a67..0b2e382a475f294 100644 --- a/files/en-us/web/api/htmlimageelement/index.md +++ b/files/en-us/web/api/htmlimageelement/index.md @@ -21,13 +21,13 @@ The **`HTMLImageElement`** interface represents an HTML {{HTMLElement("img")}} e _Inherits properties from its parent, {{domxref("HTMLElement")}}._ - {{domxref("HTMLImageElement.alt")}} - - : A string that reflects the [`alt`](/en-US/docs/Web/HTML/Element/img#alt) HTML attribute, thus indicating the alternate fallback content to be displayed if the image has not been loaded. + - : A string that reflects the [`alt`](/en-US/docs/Web/HTML/Reference/Elements/img#alt) HTML attribute, thus indicating the alternate fallback content to be displayed if the image has not been loaded. - {{domxref("HTMLImageElement.attributionSrc")}} {{securecontext_inline}} {{experimental_inline}} - - : Gets and sets the [`attributionsrc`](/en-US/docs/Web/HTML/Element/img#attributionsrc) attribute on an {{htmlelement("img")}} element programmatically, reflecting the value of that attribute. `attributionsrc` specifies that you want the browser to send an {{httpheader("Attribution-Reporting-Eligible")}} header along with the image request. On the server-side this is used to trigger sending an {{httpheader("Attribution-Reporting-Register-Source")}} or {{httpheader("Attribution-Reporting-Register-Trigger")}} header in the response, to register an image-based [attribution source](/en-US/docs/Web/API/Attribution_Reporting_API/Registering_sources#html-based_event_sources) or [attribution trigger](/en-US/docs/Web/API/Attribution_Reporting_API/Registering_triggers#html-based_attribution_triggers), respectively. + - : Gets and sets the [`attributionsrc`](/en-US/docs/Web/HTML/Reference/Elements/img#attributionsrc) attribute on an {{htmlelement("img")}} element programmatically, reflecting the value of that attribute. `attributionsrc` specifies that you want the browser to send an {{httpheader("Attribution-Reporting-Eligible")}} header along with the image request. On the server-side this is used to trigger sending an {{httpheader("Attribution-Reporting-Register-Source")}} or {{httpheader("Attribution-Reporting-Register-Trigger")}} header in the response, to register an image-based [attribution source](/en-US/docs/Web/API/Attribution_Reporting_API/Registering_sources#html-based_event_sources) or [attribution trigger](/en-US/docs/Web/API/Attribution_Reporting_API/Registering_triggers#html-based_attribution_triggers), respectively. - {{domxref("HTMLImageElement.complete")}} {{ReadOnlyInline}} - : Returns a boolean value that is `true` if the browser has finished fetching the image, whether successful or not. That means this value is also `true` if the image has no {{domxref("HTMLImageElement.src", "src")}} value indicating an image to load. - {{domxref("HTMLImageElement.crossOrigin")}} - - : A string specifying the CORS setting for this image element. See [CORS settings attributes](/en-US/docs/Web/HTML/Attributes/crossorigin) for further details. This may be `null` if CORS is not used. + - : A string specifying the CORS setting for this image element. See [CORS settings attributes](/en-US/docs/Web/HTML/Reference/Attributes/crossorigin) for further details. This may be `null` if CORS is not used. - {{domxref("HTMLImageElement.currentSrc")}} {{ReadOnlyInline}} - : Returns a string representing the URL from which the currently displayed image was loaded. This may change as the image is adjusted due to changing conditions, as directed by any [media queries](/en-US/docs/Web/CSS/CSS_media_queries) which are in place. - {{domxref("HTMLImageElement.decoding")}} @@ -35,9 +35,9 @@ _Inherits properties from its parent, {{domxref("HTMLElement")}}._ - {{domxref("HTMLImageElement.fetchPriority")}} - : An optional string representing a hint given to the browser on how it should prioritize fetching of the image relative to other images. If this value is provided, it must be one of the possible permitted values: `high` to fetch at a high priority, `low` to fetch at a low priority, or `auto` to indicate no preference (which is the default). - {{domxref("HTMLImageElement.height")}} - - : An integer value that reflects the [`height`](/en-US/docs/Web/HTML/Element/img#height) HTML attribute, indicating the rendered height of the image in CSS pixels. + - : An integer value that reflects the [`height`](/en-US/docs/Web/HTML/Reference/Elements/img#height) HTML attribute, indicating the rendered height of the image in CSS pixels. - {{domxref("HTMLImageElement.isMap")}} - - : A boolean value that reflects the [`ismap`](/en-US/docs/Web/HTML/Element/img#ismap) HTML attribute, indicating that the image is part of a server-side image map. This is different from a client-side image map, specified using an `<img>` element and a corresponding {{HTMLElement("map")}} which contains {{HTMLElement("area")}} elements indicating the clickable areas in the image. The image _must_ be contained within an {{HTMLElement("a")}} element; see the `ismap` page for details. + - : A boolean value that reflects the [`ismap`](/en-US/docs/Web/HTML/Reference/Elements/img#ismap) HTML attribute, indicating that the image is part of a server-side image map. This is different from a client-side image map, specified using an `<img>` element and a corresponding {{HTMLElement("map")}} which contains {{HTMLElement("area")}} elements indicating the clickable areas in the image. The image _must_ be contained within an {{HTMLElement("a")}} element; see the `ismap` page for details. - {{domxref("HTMLImageElement.loading")}} - : A string providing a hint to the browser used to optimize loading the document by determining whether to load the image immediately (`eager`) or on an as-needed basis (`lazy`). - {{domxref("HTMLImageElement.naturalHeight")}} {{ReadOnlyInline}} @@ -45,17 +45,17 @@ _Inherits properties from its parent, {{domxref("HTMLElement")}}._ - {{domxref("HTMLImageElement.naturalWidth")}} {{ReadOnlyInline}} - : An integer value representing the intrinsic width of the image in CSS pixels, if it is available; otherwise, it will show `0`. This is the width the image would be if it were rendered at its natural full size. - {{domxref("HTMLImageElement.referrerPolicy")}} - - : A string that reflects the [`referrerpolicy`](/en-US/docs/Web/HTML/Element/img#referrerpolicy) HTML attribute, which tells the {{Glossary("user agent")}} how to decide which referrer to use in order to fetch the image. Read this article for details on the possible values of this string. + - : A string that reflects the [`referrerpolicy`](/en-US/docs/Web/HTML/Reference/Elements/img#referrerpolicy) HTML attribute, which tells the {{Glossary("user agent")}} how to decide which referrer to use in order to fetch the image. Read this article for details on the possible values of this string. - {{domxref("HTMLImageElement.sizes")}} - - : A string reflecting the [`sizes`](/en-US/docs/Web/HTML/Element/img#sizes) HTML attribute. This string specifies a list of comma-separated conditional sizes for the image; that is, for a given viewport size, a particular image size is to be used. Read the documentation on the {{domxref("HTMLImageElement.sizes", "sizes")}} page for details on the format of this string. + - : A string reflecting the [`sizes`](/en-US/docs/Web/HTML/Reference/Elements/img#sizes) HTML attribute. This string specifies a list of comma-separated conditional sizes for the image; that is, for a given viewport size, a particular image size is to be used. Read the documentation on the {{domxref("HTMLImageElement.sizes", "sizes")}} page for details on the format of this string. - {{domxref("HTMLImageElement.src")}} - - : A string that reflects the [`src`](/en-US/docs/Web/HTML/Element/img#src) HTML attribute, which contains the full URL of the image including base URI. You can load a different image into the element by changing the URL in the `src` attribute. + - : A string that reflects the [`src`](/en-US/docs/Web/HTML/Reference/Elements/img#src) HTML attribute, which contains the full URL of the image including base URI. You can load a different image into the element by changing the URL in the `src` attribute. - {{domxref("HTMLImageElement.srcset")}} - - : A string reflecting the [`srcset`](/en-US/docs/Web/HTML/Element/img#srcset) HTML attribute. This specifies a list of candidate images, separated by commas (`',', U+002C COMMA`). Each candidate image is a URL followed by a space, followed by a specially-formatted string indicating the size of the image. The size may be specified either the width or a size multiple. Read the {{domxref("HTMLImageElement.srcset", "srcset")}} page for specifics on the format of the size substring. + - : A string reflecting the [`srcset`](/en-US/docs/Web/HTML/Reference/Elements/img#srcset) HTML attribute. This specifies a list of candidate images, separated by commas (`',', U+002C COMMA`). Each candidate image is a URL followed by a space, followed by a specially-formatted string indicating the size of the image. The size may be specified either the width or a size multiple. Read the {{domxref("HTMLImageElement.srcset", "srcset")}} page for specifics on the format of the size substring. - {{domxref("HTMLImageElement.useMap")}} - - : A string reflecting the [`usemap`](/en-US/docs/Web/HTML/Element/img#usemap) HTML attribute, containing the page-local URL of the {{HTMLElement("map")}} element describing the image map to use. The page-local URL is a pound (hash) symbol (`#`) followed by the ID of the `<map>` element, such as `#my-map-element`. The `<map>` in turn contains {{HTMLElement("area")}} elements indicating the clickable areas in the image. + - : A string reflecting the [`usemap`](/en-US/docs/Web/HTML/Reference/Elements/img#usemap) HTML attribute, containing the page-local URL of the {{HTMLElement("map")}} element describing the image map to use. The page-local URL is a pound (hash) symbol (`#`) followed by the ID of the `<map>` element, such as `#my-map-element`. The `<map>` in turn contains {{HTMLElement("area")}} elements indicating the clickable areas in the image. - {{domxref("HTMLImageElement.width")}} - - : An integer value that reflects the [`width`](/en-US/docs/Web/HTML/Element/img#width) HTML attribute, indicating the rendered width of the image in CSS pixels. + - : An integer value that reflects the [`width`](/en-US/docs/Web/HTML/Reference/Elements/img#width) HTML attribute, indicating the rendered width of the image in CSS pixels. - {{domxref("HTMLImageElement.x")}} {{ReadOnlyInline}} - : An integer indicating the horizontal offset of the left border edge of the image's CSS layout box relative to the origin of the {{HTMLElement("html")}} element's containing block. - {{domxref("HTMLImageElement.y")}} {{ReadOnlyInline}} @@ -87,7 +87,7 @@ _Inherits methods from its parent, {{domxref("HTMLElement")}}._ If an error occurs while trying to load or render the image, and an `onerror` event handler has been configured to handle the {{domxref("HTMLElement/error_event", "error")}} event, that event handler will get called. This can happen in a number of situations, including: -- The [`src`](/en-US/docs/Web/HTML/Element/img#src) attribute is empty or `null`. +- The [`src`](/en-US/docs/Web/HTML/Reference/Elements/img#src) attribute is empty or `null`. - The specified `src` URL is the same as the URL of the page the user is currently on. - The specified image is corrupted in some way that prevents it from being loaded. - The specified image's metadata is corrupted in such a way that it's impossible to retrieve its dimensions, and no dimensions were specified in the `<img>` element's attributes. diff --git a/files/en-us/web/api/htmlimageelement/ismap/index.md b/files/en-us/web/api/htmlimageelement/ismap/index.md index 9ca09711325fb8d..93a5d8b9a79dafc 100644 --- a/files/en-us/web/api/htmlimageelement/ismap/index.md +++ b/files/en-us/web/api/htmlimageelement/ismap/index.md @@ -14,7 +14,7 @@ This may only be used on images located within an {{HTMLElement("a")}} element. > [!NOTE] > For accessibility reasons, you should generally avoid using -> server-side image maps, as they require the use of a mouse. Use a [client-side image map](/en-US/docs/Learn_web_development/Howto/Solve_HTML_problems/Add_a_hit_map_on_top_of_an_image) instead. +> server-side image maps, as they require the use of a mouse. Use a [client-side image map](/en-US/docs/Web/HTML/How_to/Add_a_hit_map_on_top_of_an_image) instead. ## Value @@ -29,7 +29,7 @@ mouse was clicked as offsets from the top-left corner of the image, specified in pixels. The browser then fetches that URL from the server and displays or downloads it -depending on the value of the [`download`](/en-US/docs/Web/HTML/Element/a#download) attribute. +depending on the value of the [`download`](/en-US/docs/Web/HTML/Reference/Elements/a#download) attribute. Unlike server-side image maps, client-side image maps don't cause the {{HTMLElement("img")}} element to adopt interactive content mode. diff --git a/files/en-us/web/api/htmlimageelement/loading/index.md b/files/en-us/web/api/htmlimageelement/loading/index.md index 39b0588e421e88f..48ac556246bee9f 100644 --- a/files/en-us/web/api/htmlimageelement/loading/index.md +++ b/files/en-us/web/api/htmlimageelement/loading/index.md @@ -47,8 +47,8 @@ That means that when `load` fires, it's possible that any lazy-loaded images loc When an image whose loading has been delayed by the `loading` attribute being set to `lazy` is finally loaded, the browser will determine the final size of the {{HTMLElement("img")}} element based on the style and intrinsic size of the image, then reflow the document as needed to update the positions of elements based on any size change made to the element to fit the image. -To prevent this reflow from occurring, you should explicitly specify the size of the image's presentation using the image element's [`width`](/en-US/docs/Web/HTML/Element/img#width) and -[`height`](/en-US/docs/Web/HTML/Element/img#height) attributes. +To prevent this reflow from occurring, you should explicitly specify the size of the image's presentation using the image element's [`width`](/en-US/docs/Web/HTML/Reference/Elements/img#width) and +[`height`](/en-US/docs/Web/HTML/Reference/Elements/img#height) attributes. By establishing the intrinsic {{glossary("aspect ratio")}} in this manner, you prevent elements from shifting around while the document loads, which can be disconcerting or off-putting at best and can cause users to click the wrong thing at worst, depending on the exact timing of the deferred loads and reflows. ## Examples diff --git a/files/en-us/web/api/htmlimageelement/longdesc/index.md b/files/en-us/web/api/htmlimageelement/longdesc/index.md index de7b9c1f0455523..3f7694be9728203 100644 --- a/files/en-us/web/api/htmlimageelement/longdesc/index.md +++ b/files/en-us/web/api/htmlimageelement/longdesc/index.md @@ -14,7 +14,7 @@ The _deprecated_ property **`longDesc`** on the {{domxref("HTMLImageElement")}} interface specifies the URL of a text or HTML file which contains a long-form description of the image. This can be used to provide optional added details beyond the short description provided in the -[`title`](/en-US/docs/Web/HTML/Global_attributes/title) attribute. +[`title`](/en-US/docs/Web/HTML/Reference/Global_attributes/title) attribute. ## Value @@ -66,4 +66,4 @@ With that, the image is a link to the HTML file describing the image in more det ## See also -- [`aria-details`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-details) +- [`aria-details`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-details) diff --git a/files/en-us/web/api/htmlimageelement/name/index.md b/files/en-us/web/api/htmlimageelement/name/index.md index 3b92ae9cfeed1ef..9a17ad7dc1698ed 100644 --- a/files/en-us/web/api/htmlimageelement/name/index.md +++ b/files/en-us/web/api/htmlimageelement/name/index.md @@ -22,7 +22,7 @@ A string providing a name by which the image can be referenced. > [!WARNING] > This property is deprecated and is only in the > specification still for backward compatibility purposes. Since it functions -> identically to [`id`](/en-US/docs/Web/HTML/Global_attributes/id), you can and should use it instead. +> identically to [`id`](/en-US/docs/Web/HTML/Reference/Global_attributes/id), you can and should use it instead. ## Specifications diff --git a/files/en-us/web/api/htmlimageelement/naturalheight/index.md b/files/en-us/web/api/htmlimageelement/naturalheight/index.md index 3c4592de34f88c5..352a0dee0a493cd 100644 --- a/files/en-us/web/api/htmlimageelement/naturalheight/index.md +++ b/files/en-us/web/api/htmlimageelement/naturalheight/index.md @@ -45,7 +45,7 @@ its rendered size as altered by the page's CSS and other factors. ```html <div class="box"> <img - src="/en-US/docs/Web/HTML/Element/img/clock-demo-400px.png" + src="/en-US/docs/Web/HTML/Reference/Elements/img/clock-demo-400px.png" class="image" alt="A round wall clock with a white dial and black numbers" /> </div> diff --git a/files/en-us/web/api/htmlimageelement/referrerpolicy/index.md b/files/en-us/web/api/htmlimageelement/referrerpolicy/index.md index 59a1ad5f0f01e97..f27a44d88089acc 100644 --- a/files/en-us/web/api/htmlimageelement/referrerpolicy/index.md +++ b/files/en-us/web/api/htmlimageelement/referrerpolicy/index.md @@ -10,7 +10,7 @@ browser-compat: api.HTMLImageElement.referrerPolicy The **`HTMLImageElement.referrerPolicy`** -property reflects the HTML [`referrerpolicy`](/en-US/docs/Web/HTML/Element/img#referrerpolicy) attribute of the +property reflects the HTML [`referrerpolicy`](/en-US/docs/Web/HTML/Reference/Elements/img#referrerpolicy) attribute of the {{HTMLElement("img")}} element defining which referrer is sent when fetching the resource. @@ -24,7 +24,7 @@ A string; one of the following: - `no-referrer-when-downgrade` - : The URL is sent as a referrer when the protocol security level stays the same (e.g.HTTP→HTTP, - HTTPS→HTTPS), but isn't sent to a less secure destination (e.g. HTTPS→HTTP). + HTTPS→HTTPS), but isn't sent to a less secure destination (e.g., HTTPS→HTTP). - `origin` - : Only send the origin of the document as the referrer in all cases. The document `https://example.com/page.html` will send the referrer @@ -37,12 +37,12 @@ A string; one of the following: cross-origin requests will contain no referrer information. - `strict-origin` - : Only send the origin of the document as the referrer when the protocol security - level stays the same (e.g. HTTPS→HTTPS), but don't send it to a less secure - destination (e.g. HTTPS→HTTP). + level stays the same (e.g., HTTPS→HTTPS), but don't send it to a less secure + destination (e.g., HTTPS→HTTP). - `strict-origin-when-cross-origin` (default) - : This is the user agent's default behavior if no policy is specified. Send a full URL when performing a same-origin request, only send the origin when the - protocol security level stays the same (e.g. HTTPS→HTTPS), and send no header to a - less secure destination (e.g. HTTPS→HTTP). + protocol security level stays the same (e.g., HTTPS→HTTPS), and send no header to a + less secure destination (e.g., HTTPS→HTTP). - `unsafe-url` - : Send a full URL when performing a same-origin or cross-origin request. This policy will leak origins and paths from TLS-protected resources to insecure origins. diff --git a/files/en-us/web/api/htmlimageelement/sizes/index.md b/files/en-us/web/api/htmlimageelement/sizes/index.md index b2ceccb25bd1010..4c2721d89de06f2 100644 --- a/files/en-us/web/api/htmlimageelement/sizes/index.md +++ b/files/en-us/web/api/htmlimageelement/sizes/index.md @@ -10,7 +10,7 @@ browser-compat: api.HTMLImageElement.sizes The {{domxref("HTMLImageElement")}} property **`sizes`** allows you to specify the layout width of the -[image](/en-US/docs/Web/HTML/Element/img) for each of a list of media conditions. This provides the ability to +[image](/en-US/docs/Web/HTML/Reference/Elements/img) for each of a list of media conditions. This provides the ability to automatically select among different images—even images of different orientations or aspect ratios—as the document state changes to match different media conditions. @@ -24,7 +24,9 @@ A string containing a comma-separated list of source size descriptors followed by an optional fallback size. Each source size descriptor is comprised of a media condition, then at least one whitespace character, then the source size value to use for the image when the media condition -evaluates to `true`. For more information about the syntax of the `sizes` attribute, see [`<img>`](/en-US/docs/Web/HTML/Element/img#sizes). +evaluates to `true`. +You can use the value `auto` to replace the whole list of sizes or the first entry in the list. +For more information about the syntax of the `sizes` attribute, see [`<img>`](/en-US/docs/Web/HTML/Reference/Elements/img#sizes). ## Examples @@ -142,5 +144,5 @@ The page is best {{LiveSampleLink('Selecting an image to fit window width', 'vie - [Media queries](/en-US/docs/Web/CSS/CSS_media_queries) - [Using media queries](/en-US/docs/Web/CSS/CSS_media_queries/Using_media_queries) - [HTML images](/en-US/docs/Learn_web_development/Core/Structuring_content/HTML_images) -- [Responsive images](/en-US/docs/Web/HTML/Responsive_images) -- [Using the `srcset` and `sizes` attributes](/en-US/docs/Web/HTML/Element/img#using_the_srcset_and_sizes_attributes) +- [Responsive images](/en-US/docs/Web/HTML/Guides/Responsive_images) +- [Using the `srcset` and `sizes` attributes](/en-US/docs/Web/HTML/Reference/Elements/img#using_the_srcset_and_sizes_attributes) diff --git a/files/en-us/web/api/htmlimageelement/src/index.md b/files/en-us/web/api/htmlimageelement/src/index.md index f0b94892a5b927f..03de7acdc1d2509 100644 --- a/files/en-us/web/api/htmlimageelement/src/index.md +++ b/files/en-us/web/api/htmlimageelement/src/index.md @@ -9,7 +9,7 @@ browser-compat: api.HTMLImageElement.src {{APIRef("HTML DOM")}} The {{domxref("HTMLImageElement")}} property -**`src`**, which reflects the HTML [`src`](/en-US/docs/Web/HTML/Element/img#src) attribute, specifies the image to display in the {{HTMLElement("img")}} +**`src`**, which reflects the HTML [`src`](/en-US/docs/Web/HTML/Reference/Elements/img#src) attribute, specifies the image to display in the {{HTMLElement("img")}} element. ## Value @@ -18,10 +18,10 @@ When providing only a single image, rather than a set of images from which the b selects the best match for the viewport size and display pixel density, the `src` attribute is a string specifying the URL of the desired image. This can be set either within the HTML itself using the -[`src`](/en-US/docs/Web/HTML/Element/img#src) content attribute, or programmatically by setting the +[`src`](/en-US/docs/Web/HTML/Reference/Elements/img#src) content attribute, or programmatically by setting the element's `src` property. -If you use the [`srcset`](/en-US/docs/Web/HTML/Element/img#srcset) content attribute to provide multiple +If you use the [`srcset`](/en-US/docs/Web/HTML/Reference/Elements/img#srcset) content attribute to provide multiple image options for different display pixel densities, the URL specified by the `src` attribute is used in one of two ways: @@ -32,7 +32,7 @@ image options for different display pixel densities, the URL specified by the Additionally, if you use `src` along with _both_ {{domxref("HTMLImageElement.sizes", "sizes")}} (or the -corresponding [`sizes`](/en-US/docs/Web/HTML/Element/img#sizes) content attribute) _and_ +corresponding [`sizes`](/en-US/docs/Web/HTML/Reference/Elements/img#sizes) content attribute) _and_ `srcset` in order to choose an image based on the viewport size, the `src` attribute is only used as a fallback for browsers that don't support `sizes` and `srcset`; otherwise, it's not used at all. diff --git a/files/en-us/web/api/htmlimageelement/srcset/index.md b/files/en-us/web/api/htmlimageelement/srcset/index.md index 9108fa9d16f229d..bb9e116d8197a08 100644 --- a/files/en-us/web/api/htmlimageelement/srcset/index.md +++ b/files/en-us/web/api/htmlimageelement/srcset/index.md @@ -24,7 +24,7 @@ can be used together to make pages that use appropriate images for the rendering situation. > [!NOTE] -> If the [`srcset`](/en-US/docs/Web/HTML/Element/img#srcset) attribute uses width descriptors, the `sizes` attribute must also be present, or the `srcset` itself will be ignored. +> If the [`srcset`](/en-US/docs/Web/HTML/Reference/Elements/img#srcset) attribute uses width descriptors, the `sizes` attribute must also be present, or the `srcset` itself will be ignored. ## Value @@ -97,9 +97,11 @@ a `2x` descriptor) should be used for 2x displays. ```html <div class="box"> <img - src="/en-US/docs/Web/HTML/Element/img/clock-demo-200px.png" + src="/en-US/docs/Web/HTML/Reference/Elements/img/clock-demo-200px.png" alt="Clock" - srcset="/en-US/docs/Web/HTML/Element/img/clock-demo-400px.png 2x" /> + srcset=" + /en-US/docs/Web/HTML/Reference/Elements/img/clock-demo-400px.png 2x + " /> </div> ``` @@ -153,7 +155,7 @@ reloading the page to see the results change. {{EmbedLiveSample("Examples", 640, 320)}} -For additional examples, see our guide to [responsive images](/en-US/docs/Web/HTML/Responsive_images). +For additional examples, see our guide to [responsive images](/en-US/docs/Web/HTML/Guides/Responsive_images). ## Specifications @@ -166,5 +168,5 @@ For additional examples, see our guide to [responsive images](/en-US/docs/Web/HT ## See also - [HTML images](/en-US/docs/Learn_web_development/Core/Structuring_content/HTML_images) -- [Responsive images](/en-US/docs/Web/HTML/Responsive_images) +- [Responsive images](/en-US/docs/Web/HTML/Guides/Responsive_images) - [Image file type and format guide](/en-US/docs/Web/Media/Guides/Formats/Image_types) diff --git a/files/en-us/web/api/htmlimageelement/usemap/index.md b/files/en-us/web/api/htmlimageelement/usemap/index.md index 5e63007e046decd..a768c8b1f635971 100644 --- a/files/en-us/web/api/htmlimageelement/usemap/index.md +++ b/files/en-us/web/api/htmlimageelement/usemap/index.md @@ -10,7 +10,7 @@ browser-compat: api.HTMLImageElement.useMap The **`useMap`** property on the {{domxref("HTMLImageElement")}} interface reflects the value of the -{{Glossary("HTML")}} [`usemap`](/en-US/docs/Web/HTML/Element/img#usemap) attribute, which is a string +{{Glossary("HTML")}} [`usemap`](/en-US/docs/Web/HTML/Reference/Elements/img#usemap) attribute, which is a string providing the name of the client-side image map to apply to the image. ## Value @@ -19,13 +19,13 @@ A string providing the page-local URL (that is, a URL that begins with the hash or pound symbol, `#`) of the {{HTMLElement("map")}} element which defines the image map to apply to the image. -You can learn more about client-side image maps in our learning article [Add a hitmap on top of an image](/en-US/docs/Learn_web_development/Howto/Solve_HTML_problems/Add_a_hit_map_on_top_of_an_image). +You can learn more about client-side image maps in our learning article [Add a hitmap on top of an image](/en-US/docs/Web/HTML/How_to/Add_a_hit_map_on_top_of_an_image). ## Usage notes The string value of `useMap` must be a valid anchor for a {{HTMLElement("map")}} element. In other words, this string should be the value of the -appropriate `<map>`'s [`name`](/en-US/docs/Web/HTML/Element/map#name) attribute with a +appropriate `<map>`'s [`name`](/en-US/docs/Web/HTML/Reference/Elements/map#name) attribute with a pound or hash symbol prepended to it. Consider a `<map>` that looks like this: @@ -49,7 +49,7 @@ look something like the following: ``` For additional examples (including interactive ones), see the articles about the -{{HTMLElement("map")}} and {{HTMLElement("area")}} elements, as well as the [guide to using image maps](/en-US/docs/Learn_web_development/Howto/Solve_HTML_problems/Add_a_hit_map_on_top_of_an_image). +{{HTMLElement("map")}} and {{HTMLElement("area")}} elements, as well as the [guide to using image maps](/en-US/docs/Web/HTML/How_to/Add_a_hit_map_on_top_of_an_image). ## Examples diff --git a/files/en-us/web/api/htmlimageelement/width/index.md b/files/en-us/web/api/htmlimageelement/width/index.md index c346223aaf0c92f..4c9d1850c17b141 100644 --- a/files/en-us/web/api/htmlimageelement/width/index.md +++ b/files/en-us/web/api/htmlimageelement/width/index.md @@ -29,8 +29,8 @@ screen or printer: ## Examples In this example, two different sizes are provided for an image of a clock using the -[`srcset`](/en-US/docs/Web/HTML/Element/img#srcset) attribute. One is 200px wide and the other is 400px -wide. The [`sizes`](/en-US/docs/Web/HTML/Element/img#sizes) attribute is used to specify the width at +[`srcset`](/en-US/docs/Web/HTML/Reference/Elements/img#srcset) attribute. One is 200px wide and the other is 400px +wide. The [`sizes`](/en-US/docs/Web/HTML/Reference/Elements/img#sizes) attribute is used to specify the width at which the image should be drawn given the viewport's width. ### HTML @@ -41,11 +41,11 @@ drawn at 400px. ```html <p>Image width: <span class="size">?</span>px (resize to update)</p> <img - src="/en-US/docs/Web/HTML/Element/img/clock-demo-200px.png" + src="/en-US/docs/Web/HTML/Reference/Elements/img/clock-demo-200px.png" alt="Clock" srcset=" - /en-US/docs/Web/HTML/Element/img/clock-demo-200px.png 200w, - /en-US/docs/Web/HTML/Element/img/clock-demo-400px.png 400w + /en-US/docs/Web/HTML/Reference/Elements/img/clock-demo-200px.png 200w, + /en-US/docs/Web/HTML/Reference/Elements/img/clock-demo-400px.png 400w " sizes="(max-width: 400px) 200px, 400px" /> ``` diff --git a/files/en-us/web/api/htmlimageelement/x/index.md b/files/en-us/web/api/htmlimageelement/x/index.md index a01df96753079dd..8c9cbdd19496857 100644 --- a/files/en-us/web/api/htmlimageelement/x/index.md +++ b/files/en-us/web/api/htmlimageelement/x/index.md @@ -55,8 +55,8 @@ including their user ID, their full name, and their avatar image. ```html <table id="userinfo"> <colgroup> - <col span="2" class="group1"> - <col> + <col span="2" class="group1" /> + <col /> </colgroup> <tr> <th>UserID</th> @@ -66,11 +66,12 @@ including their user ID, their full name, and their avatar image. <tr> <td>12345678</td> <td>Johnny Rocket</td> - <td><img src="https://interactive-examples.mdn.mozilla.net/media/examples/grapefruit-slice-332-332.jpg"></td> - </th> + <td> + <img src="/shared-assets/images/examples/grapefruit-slice.jpg" /> + </td> + </tr> </table> -<pre id="log"> -</pre> +<pre id="log"></pre> ``` ### JavaScript diff --git a/files/en-us/web/api/htmlinputelement/accept/index.md b/files/en-us/web/api/htmlinputelement/accept/index.md index f14ec80646d29cf..d9269adb90a1909 100644 --- a/files/en-us/web/api/htmlinputelement/accept/index.md +++ b/files/en-us/web/api/htmlinputelement/accept/index.md @@ -8,7 +8,7 @@ browser-compat: api.HTMLInputElement.accept {{ApiRef("HTML DOM")}} -The **`accept`** property of the {{domxref("HTMLInputElement")}} interface reflects the {{HTMLElement("input")}} element's [`accept`](/en-US/docs/Web/HTML/Element/input#accept) attribute, generally a comma-separated list of unique file type specifiers providing a hint for the expected file type for an [`<input>` of type `file`](/en-US/docs/Web/HTML/Element/input/file). If the attribute is not explicitly set, the `accept` property is an empty string. +The **`accept`** property of the {{domxref("HTMLInputElement")}} interface reflects the {{HTMLElement("input")}} element's [`accept`](/en-US/docs/Web/HTML/Reference/Elements/input#accept) attribute, generally a comma-separated list of unique file type specifiers providing a hint for the expected file type for an [`<input>` of type `file`](/en-US/docs/Web/HTML/Reference/Elements/input/file). If the attribute is not explicitly set, the `accept` property is an empty string. ## Value @@ -35,6 +35,6 @@ inputElement.accept = ".doc,.docx,.xml,application/msword"; // sets the accept v - {{domxref("HTMLInputElement.type")}} - {{domxref("HTMLInputElement.multiple")}} - {{domxref("HTMLInputElement.capture")}} -- [File type specifiers](/en-US/docs/Web/HTML/Element/input/file#unique_file_type_specifiers) +- [File type specifiers](/en-US/docs/Web/HTML/Reference/Elements/input/file#unique_file_type_specifiers) - [Using files from web applications](/en-US/docs/Web/API/File_API/Using_files_from_web_applications) - [File API](/en-US/docs/Web/API/File_API) diff --git a/files/en-us/web/api/htmlinputelement/alt/index.md b/files/en-us/web/api/htmlinputelement/alt/index.md index 60a5064eaac1c75..1aaee548d9a9350 100644 --- a/files/en-us/web/api/htmlinputelement/alt/index.md +++ b/files/en-us/web/api/htmlinputelement/alt/index.md @@ -8,9 +8,9 @@ browser-compat: api.HTMLInputElement.alt {{APIRef("HTML DOM")}} -The **`alt`** property of the {{DOMxRef("HTMLInputElement")}} interface defines the textual label for the button for users and user agents who cannot use the image. It reflects the {{htmlelement("input")}} element's [`alt`](/en-US/docs/Web/HTML/Element/input#alt) attribute. +The **`alt`** property of the {{DOMxRef("HTMLInputElement")}} interface defines the textual label for the button for users and user agents who cannot use the image. It reflects the {{htmlelement("input")}} element's [`alt`](/en-US/docs/Web/HTML/Reference/Elements/input#alt) attribute. -The `alt` property is valid for the [`image`](/en-US/docs/Web/HTML/Element/input/image) type only. It should be a non-empty string giving the label that would be appropriate for an equivalent button if the image was unavailable. +The `alt` property is valid for the [`image`](/en-US/docs/Web/HTML/Reference/Elements/input/image) type only. It should be a non-empty string giving the label that would be appropriate for an equivalent button if the image was unavailable. ## Value diff --git a/files/en-us/web/api/htmlinputelement/autocomplete/index.md b/files/en-us/web/api/htmlinputelement/autocomplete/index.md index 2d4d53ac84959a6..9de97ec4a647390 100644 --- a/files/en-us/web/api/htmlinputelement/autocomplete/index.md +++ b/files/en-us/web/api/htmlinputelement/autocomplete/index.md @@ -8,11 +8,11 @@ browser-compat: api.HTMLInputElement.autocomplete {{ APIRef("HTML DOM") }} -The **`autocomplete`** property of the {{DOMxRef("HTMLInputElement")}} interface indicates whether the value of the control can be automatically completed by the browser. It reflects the {{htmlelement("input")}} element's [`autocomplete`](/en-US/docs/Web/HTML/Attributes/autocomplete) attribute. +The **`autocomplete`** property of the {{DOMxRef("HTMLInputElement")}} interface indicates whether the value of the control can be automatically completed by the browser. It reflects the {{htmlelement("input")}} element's [`autocomplete`](/en-US/docs/Web/HTML/Reference/Attributes/autocomplete) attribute. ## Value -A string; the value of the `autocomplete` attribute (`"on"`, `"off"`, a [`<token-list>`](/en-US/docs/Web/HTML/Attributes/autocomplete#token_list_tokens)), or the empty string `""` if unspecified. +A string; the value of the `autocomplete` attribute (`"on"`, `"off"`, a [`<token-list>`](/en-US/docs/Web/HTML/Reference/Attributes/autocomplete#token_list_tokens)), or the empty string `""` if unspecified. ## Examples @@ -33,6 +33,6 @@ console.log(inputElement.autocomplete); - {{HTMLElement("input")}} - {{DOMxRef("HTMLInputElement.value")}} -- HTML [`autocomplete`](/en-US/docs/Web/HTML/Attributes/autocomplete) attribute -- ARIA [`aria-autocomplete`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-autocomplete) attribute +- HTML [`autocomplete`](/en-US/docs/Web/HTML/Reference/Attributes/autocomplete) attribute +- ARIA [`aria-autocomplete`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-autocomplete) attribute - [Turning off autocompletion](/en-US/docs/Web/Security/Practical_implementation_guides/Turning_off_form_autocompletion) diff --git a/files/en-us/web/api/htmlinputelement/cancel_event/index.md b/files/en-us/web/api/htmlinputelement/cancel_event/index.md index 1084ed2057151dc..6a54c990ea3a598 100644 --- a/files/en-us/web/api/htmlinputelement/cancel_event/index.md +++ b/files/en-us/web/api/htmlinputelement/cancel_event/index.md @@ -16,10 +16,10 @@ This event is not cancelable but can bubble. Use the event name in methods like {{domxref("EventTarget.addEventListener", "addEventListener()")}}, or set an event handler property. -```js -addEventListener("cancel", (event) => {}); +```js-nolint +addEventListener("cancel", (event) => { }) -oncancel = (event) => {}; +oncancel = (event) => { } ``` ## Event type @@ -57,7 +57,7 @@ elem.addEventListener("cancel", () => { }); elem.addEventListener("change", () => { - if (elem.files.length == 1) { + if (elem.files.length === 1) { result.textContent = "File Selected."; } }); diff --git a/files/en-us/web/api/htmlinputelement/capture/index.md b/files/en-us/web/api/htmlinputelement/capture/index.md index 2efbae78b72190b..282271e81feefd2 100644 --- a/files/en-us/web/api/htmlinputelement/capture/index.md +++ b/files/en-us/web/api/htmlinputelement/capture/index.md @@ -8,7 +8,7 @@ browser-compat: api.HTMLInputElement.capture {{ApiRef("HTML DOM")}} -The **`capture`** property of the {{domxref("HTMLInputElement")}} interface reflects the {{HTMLElement("input")}} element's [`capture`](/en-US/docs/Web/HTML/Attributes/capture) attribute. Only relevant to the [`<input>` of type `file`](/en-US/docs/Web/HTML/Element/input/file), the property and attribute specify whether, a new file should be captured from a user-facing (`user`) or outward facing (`environment`) camera or microphone. The type of file is defined the [`accept`](/en-US/docs/Web/HTML/Attributes/accept) attribute. If the attribute is not explicitly set, the `capture` property is an empty string. +The **`capture`** property of the {{domxref("HTMLInputElement")}} interface reflects the {{HTMLElement("input")}} element's [`capture`](/en-US/docs/Web/HTML/Reference/Attributes/capture) attribute. Only relevant to the [`<input>` of type `file`](/en-US/docs/Web/HTML/Reference/Elements/input/file), the property and attribute specify whether, a new file should be captured from a user-facing (`user`) or outward facing (`environment`) camera or microphone. The type of file is defined the [`accept`](/en-US/docs/Web/HTML/Reference/Attributes/accept) attribute. If the attribute is not explicitly set, the `capture` property is an empty string. ## Value @@ -36,6 +36,6 @@ inputElement.capture = "user"; // sets the capture value - {{domxref("HTMLInputElement.multiple")}} - {{domxref("HTMLInputElement.accept")}} - {{domxref("HTMLInputElement.files")}} -- [File type specifiers](/en-US/docs/Web/HTML/Element/input/file#unique_file_type_specifiers) +- [File type specifiers](/en-US/docs/Web/HTML/Reference/Elements/input/file#unique_file_type_specifiers) - [Using files from web applications](/en-US/docs/Web/API/File_API/Using_files_from_web_applications) - [File API](/en-US/docs/Web/API/File_API) diff --git a/files/en-us/web/api/htmlinputelement/checked/index.md b/files/en-us/web/api/htmlinputelement/checked/index.md index fa8dba41a093e53..e354adbff7b95cb 100644 --- a/files/en-us/web/api/htmlinputelement/checked/index.md +++ b/files/en-us/web/api/htmlinputelement/checked/index.md @@ -10,9 +10,9 @@ browser-compat: api.HTMLInputElement.checked The **`checked`** property of the {{DOMxRef("HTMLInputElement")}} interface specifies the current checkedness of the element; that is, whether the form control is checked or not. -The boolean `checked` property is relevant to the `radio` ([`<input type="radio">`](/en-US/docs/Web/HTML/Element/input/radio)) and `checkbox` ([`<input type="checkbox">`](/en-US/docs/Web/HTML/Element/input/checkbox)) input types. +The boolean `checked` property is relevant to the `radio` ([`<input type="radio">`](/en-US/docs/Web/HTML/Reference/Elements/input/radio)) and `checkbox` ([`<input type="checkbox">`](/en-US/docs/Web/HTML/Reference/Elements/input/checkbox)) input types. -The presence of the HTML [`checked`](/en-US/docs/Web/HTML/Element/input#checked) attribute indicates the checkbox is checked by default. It does not indicate whether this checkbox is currently checked: if the checkbox's state is changed, this content attribute does not reflect the change; only the `HTMLInputElement`'s `checked` IDL property is updated. The `checked` attribute is reflected by the {{domxref("HTMLInputElement.defaultChecked", "defaultChecked")}} property. +The presence of the HTML [`checked`](/en-US/docs/Web/HTML/Reference/Elements/input#checked) attribute indicates the checkbox is checked by default. It does not indicate whether this checkbox is currently checked: if the checkbox's state is changed, this content attribute does not reflect the change; only the `HTMLInputElement`'s `checked` IDL property is updated. The `checked` attribute is reflected by the {{domxref("HTMLInputElement.defaultChecked", "defaultChecked")}} property. When a radio input `checked` property is `true`, all other radio inputs with the same {{DOMxRef("HTMLInputElement.name", "name")}} are `false`. If any radio button in a same-named group of radio buttons is {{DOMxRef("HTMLInputElement.required", "required")}}, as long as one button in the group is `checked`, the {{domxref('ValidityState')}} object's read-only {{domxref('ValidityState.valueMissing','valueMissing')}} property for each radio button in the group will be `false`. diff --git a/files/en-us/web/api/htmlinputelement/checkvalidity/index.md b/files/en-us/web/api/htmlinputelement/checkvalidity/index.md index 53e95abdef265e6..c992ed8af0503f1 100644 --- a/files/en-us/web/api/htmlinputelement/checkvalidity/index.md +++ b/files/en-us/web/api/htmlinputelement/checkvalidity/index.md @@ -8,7 +8,7 @@ browser-compat: api.HTMLInputElement.checkValidity {{APIRef("HTML DOM")}} -The **`checkValidity()`** method of the {{domxref("HTMLInputElement")}} interface returns a boolean value which indicates if the element meets any [constraint validation](/en-US/docs/Web/HTML/Constraint_validation) rules applied to it. If false, the method also fires an {{domxref("HTMLElement/invalid_event", "invalid")}} event on the element. Because there's no default browser behavior for `checkValidity()`, canceling this `invalid` event has no effect. +The **`checkValidity()`** method of the {{domxref("HTMLInputElement")}} interface returns a boolean value which indicates if the element meets any [constraint validation](/en-US/docs/Web/HTML/Guides/Constraint_validation) rules applied to it. If false, the method also fires an {{domxref("HTMLElement/invalid_event", "invalid")}} event on the element. Because there's no default browser behavior for `checkValidity()`, canceling this `invalid` event has no effect. > [!NOTE] > An HTML {{htmlelement("input")}} element with a non-null {{domxref("HTMLInputElement.validationMessage", "validationMessage")}} is considered invalid, will match the CSS {{cssxref(":invalid")}} pseudo-class, and will cause `checkValidity()` to return false. Use the {{domxref("HTMLInputElement.setCustomValidity()")}} method to set the {{domxref("HTMLInputElement.validationMessage")}} to the empty string to set the {{domxref("HTMLInputElement.validity", "validity")}} state to be valid. @@ -84,5 +84,5 @@ When `false`, if the value is missing, below 21, above 65, or otherwise invalid, - {{HTMLElement("input")}} - {{HTMLElement("form")}} - [Learn: Client-side form validation](/en-US/docs/Learn_web_development/Extensions/Forms/Form_validation) -- [Guide: Constraint validation](/en-US/docs/Web/HTML/Constraint_validation) +- [Guide: Constraint validation](/en-US/docs/Web/HTML/Guides/Constraint_validation) - CSS {{cssxref(":valid")}} and {{cssxref(":invalid")}} pseudo-classes diff --git a/files/en-us/web/api/htmlinputelement/defaultchecked/index.md b/files/en-us/web/api/htmlinputelement/defaultchecked/index.md index 870fdafc5f31671..b762fab4c33cb7d 100644 --- a/files/en-us/web/api/htmlinputelement/defaultchecked/index.md +++ b/files/en-us/web/api/htmlinputelement/defaultchecked/index.md @@ -8,9 +8,9 @@ browser-compat: api.HTMLInputElement.defaultChecked {{ APIRef("HTML DOM") }} -The **`defaultChecked`** property of the {{DOMxRef("HTMLInputElement")}} interface specifies the default checkedness state of the element. This property reflects the {{htmlelement("input")}} element's [`checked`](/en-US/docs/Web/HTML/Element/input#checked) attribute. +The **`defaultChecked`** property of the {{DOMxRef("HTMLInputElement")}} interface specifies the default checkedness state of the element. This property reflects the {{htmlelement("input")}} element's [`checked`](/en-US/docs/Web/HTML/Reference/Elements/input#checked) attribute. -The boolean [`checked`](/en-US/docs/Web/HTML/Element/input#checked) attribute is valid for the `radio` ([`<input type="radio">`](/en-US/docs/Web/HTML/Element/input/radio)) and `checkbox` ([`<input type="checkbox">`](/en-US/docs/Web/HTML/Element/input/checkbox)) input types. The presence of the attribute sets the `defaultChecked` property to `true`. +The boolean [`checked`](/en-US/docs/Web/HTML/Reference/Elements/input#checked) attribute is valid for the `radio` ([`<input type="radio">`](/en-US/docs/Web/HTML/Reference/Elements/input/radio)) and `checkbox` ([`<input type="checkbox">`](/en-US/docs/Web/HTML/Reference/Elements/input/checkbox)) input types. The presence of the attribute sets the `defaultChecked` property to `true`. ## Value diff --git a/files/en-us/web/api/htmlinputelement/defaultvalue/index.md b/files/en-us/web/api/htmlinputelement/defaultvalue/index.md index 4d00563a3347a4e..90e5b0f65e0bd05 100644 --- a/files/en-us/web/api/htmlinputelement/defaultvalue/index.md +++ b/files/en-us/web/api/htmlinputelement/defaultvalue/index.md @@ -8,7 +8,7 @@ browser-compat: api.HTMLInputElement.defaultValue {{ApiRef("HTML DOM")}} -The **`defaultValue`** property of the {{domxref("HTMLInputElement")}} interface indicates the original (or default) value of the {{HTMLElement("input")}} element. It reflects the element's [`value`](/en-US/docs/Web/HTML/Element/input#value) attribute. +The **`defaultValue`** property of the {{domxref("HTMLInputElement")}} interface indicates the original (or default) value of the {{HTMLElement("input")}} element. It reflects the element's [`value`](/en-US/docs/Web/HTML/Reference/Elements/input#value) attribute. ## Value diff --git a/files/en-us/web/api/htmlinputelement/dirname/index.md b/files/en-us/web/api/htmlinputelement/dirname/index.md new file mode 100644 index 000000000000000..cbe4691ca2bff4e --- /dev/null +++ b/files/en-us/web/api/htmlinputelement/dirname/index.md @@ -0,0 +1,37 @@ +--- +title: "HTMLInputElement: dirName property" +short-title: dirName +slug: Web/API/HTMLInputElement/dirName +page-type: web-api-instance-property +browser-compat: api.HTMLInputElement.dirName +--- + +{{APIRef("HTML DOM")}} + +The **`dirName`** property of the {{domxref("HTMLInputElement")}} interface is the directionality of the element and enables the submission of that value. It reflects the value of the {{htmlelement("input")}} element's [`dirName`](/en-US/docs/Web/HTML/Reference/Attributes/dirname) attribute. This property can be retrieved or set. + +Valid only for [`hidden`](/en-US/docs/Web/HTML/Reference/Elements/input/hidden), [`text`](/en-US/docs/Web/HTML/Reference/Elements/input/text), [`search`](/en-US/docs/Web/HTML/Reference/Elements/input/search), [`url`](/en-US/docs/Web/HTML/Reference/Elements/input/url), [`tel`](/en-US/docs/Web/HTML/Reference/Elements/input/tel), and [`email`](/en-US/docs/Web/HTML/Reference/Elements/input/email) `<input>` types, the `dirname` attribute controls how the element's directionality is submitted. When included, the form control will submit with two name/value pairs: the first being the [`name`](/en-US/docs/Web/HTML/Reference/Elements/input#name) and [`value`](/en-US/docs/Web/HTML/Reference/Elements/input#value), and the second being the value of the [`dirname`](/en-US/docs/Web/HTML/Reference/Elements/input#dirname) attribute as the name, with a value of `ltr` or `rtl` as set by the browser. + +## Value + +A string. The direction of the element. + +## Examples + +```js +inputElement.dirName = "rtl"; +``` + +## Specifications + +{{Specifications}} + +## Browser compatibility + +{{Compat}} + +## See also + +- {{domxref("HTMLTextAreaElement.dirName")}} +- [`dir` attribute](/en-US/docs/Web/HTML/Reference/Global_attributes/dir) +- [Sending form data](/en-US/docs/Learn_web_development/Extensions/Forms/Sending_and_retrieving_form_data) diff --git a/files/en-us/web/api/htmlinputelement/disabled/index.md b/files/en-us/web/api/htmlinputelement/disabled/index.md index ab8f9bdefc5e2a4..ad5c77af6fd0cee 100644 --- a/files/en-us/web/api/htmlinputelement/disabled/index.md +++ b/files/en-us/web/api/htmlinputelement/disabled/index.md @@ -8,7 +8,7 @@ browser-compat: api.HTMLInputElement.disabled {{ APIRef("HTML DOM") }} -The **`HTMLInputElement.disabled`** property is a boolean value that reflects the [`disabled`](/en-US/docs/Web/HTML/Element/input#disabled) HTML attribute, which indicates whether the control is disabled. If it is disabled, it does not accept clicks. A disabled element is unusable and un-clickable. +The **`HTMLInputElement.disabled`** property is a boolean value that reflects the [`disabled`](/en-US/docs/Web/HTML/Reference/Elements/input#disabled) HTML attribute, which indicates whether the control is disabled. If it is disabled, it does not accept clicks. A disabled element is unusable and un-clickable. ## Value diff --git a/files/en-us/web/api/htmlinputelement/files/index.md b/files/en-us/web/api/htmlinputelement/files/index.md index 49e9e6176abc0e9..66ae8a4ee7bc31c 100644 --- a/files/en-us/web/api/htmlinputelement/files/index.md +++ b/files/en-us/web/api/htmlinputelement/files/index.md @@ -8,7 +8,7 @@ browser-compat: api.HTMLInputElement.files {{APIRef("File and Directory Entries API")}} -The **`HTMLInputElement.files`** property allows you to access the {{domxref("FileList")}} selected with the [`<input type="file">`](/en-US/docs/Web/HTML/Element/input/file) element. +The **`HTMLInputElement.files`** property allows you to access the {{domxref("FileList")}} selected with the [`<input type="file">`](/en-US/docs/Web/HTML/Reference/Elements/input/file) element. ## Value @@ -40,7 +40,7 @@ for (const file of fileInput.files) { let fileDate = new Date(file.lastModified); console.log(fileDate.toLocaleDateString()); // prints legible date console.log( - file.size < 1000 ? file.size : Math.round(file.size / 1000) + "KB", + file.size < 1000 ? file.size : `${Math.round(file.size / 1000)}KB`, ); console.log(file.type); // prints MIME type } diff --git a/files/en-us/web/api/htmlinputelement/form/index.md b/files/en-us/web/api/htmlinputelement/form/index.md index af464e7f756b377..168c785a3a0ba8a 100644 --- a/files/en-us/web/api/htmlinputelement/form/index.md +++ b/files/en-us/web/api/htmlinputelement/form/index.md @@ -27,5 +27,5 @@ An {{domxref("HTMLFormElement")}} or `null`. - {{domxref("HTMLInputElement")}} - {{domxref("HTMLFormElement")}} - {{HTMLElement("input")}} -- HTML [`form`](/en-US/docs/Web/HTML/Element/input#form) attribute +- HTML [`form`](/en-US/docs/Web/HTML/Reference/Elements/input#form) attribute - [HTML forms guide](/en-US/docs/Learn_web_development/Extensions/Forms) diff --git a/files/en-us/web/api/htmlinputelement/formaction/index.md b/files/en-us/web/api/htmlinputelement/formaction/index.md index 379e2dfeb954393..ba5d1f27c1b99eb 100644 --- a/files/en-us/web/api/htmlinputelement/formaction/index.md +++ b/files/en-us/web/api/htmlinputelement/formaction/index.md @@ -8,9 +8,9 @@ browser-compat: api.HTMLInputElement.formAction {{APIRef("HTML DOM")}} -The **`formAction`** property of the {{domxref("HTMLInputElement")}} interface is the URL of the program that is executed on the server when the form that owns this control is submitted. It reflects the value of the `<input>`'s [`formaction`](/en-US/docs/Web/HTML/Element/input#formaction) attribute. +The **`formAction`** property of the {{domxref("HTMLInputElement")}} interface is the URL of the program that is executed on the server when the form that owns this control is submitted. It reflects the value of the `<input>`'s [`formaction`](/en-US/docs/Web/HTML/Reference/Elements/input#formaction) attribute. -This property is valid only for [`submit`](/en-US/docs/Web/HTML/Element/input/submit) and [`image`](/en-US/docs/Web/HTML/Element/input/image) `<input>` elements. +This property is valid only for [`submit`](/en-US/docs/Web/HTML/Reference/Elements/input/submit) and [`image`](/en-US/docs/Web/HTML/Reference/Elements/input/image) `<input>` elements. Its value overrides the {{domxref("HTMLFormElement.action", "action")}} property of the {{domxref("HTMLFormElement")}} interface if the form is submitted via the input. This property can be retrieved or set. @@ -38,6 +38,6 @@ inputElement.formAction = "/cgi-bin/publish"; - {{domxref("HTMLInputElement.formMethod")}} - {{domxref("HTMLInputElement.formNoValidate")}} - {{domxref("HTMLInputElement.formTarget")}} -- [`<input type="submit">`](/en-US/docs/Web/HTML/Element/input/submit) -- [`<input type="image">`](/en-US/docs/Web/HTML/Element/input/image) +- [`<input type="submit">`](/en-US/docs/Web/HTML/Reference/Elements/input/submit) +- [`<input type="image">`](/en-US/docs/Web/HTML/Reference/Elements/input/image) - [Sending form data](/en-US/docs/Learn_web_development/Extensions/Forms/Sending_and_retrieving_form_data) diff --git a/files/en-us/web/api/htmlinputelement/formenctype/index.md b/files/en-us/web/api/htmlinputelement/formenctype/index.md index 192bc19a847f1bb..b6a75110b22abc9 100644 --- a/files/en-us/web/api/htmlinputelement/formenctype/index.md +++ b/files/en-us/web/api/htmlinputelement/formenctype/index.md @@ -8,9 +8,9 @@ browser-compat: api.HTMLInputElement.formEnctype {{APIRef("HTML DOM")}} -The **`formEnctype`** property of the {{domxref("HTMLInputElement")}} interface is the {{Glossary("MIME_type", "MIME type")}} of the content sent to the server when the `<input>` with the `formEnctype` is the method of form submission. It reflects the value of the `<input>`'s [`formenctype`](/en-US/docs/Web/HTML/Element/input#formenctype) attribute. +The **`formEnctype`** property of the {{domxref("HTMLInputElement")}} interface is the {{Glossary("MIME_type", "MIME type")}} of the content sent to the server when the `<input>` with the `formEnctype` is the method of form submission. It reflects the value of the `<input>`'s [`formenctype`](/en-US/docs/Web/HTML/Reference/Elements/input#formenctype) attribute. -This property is valid only for [`submit`](/en-US/docs/Web/HTML/Element/input/submit) and [`image`](/en-US/docs/Web/HTML/Element/input/image) `<input>` elements. +This property is valid only for [`submit`](/en-US/docs/Web/HTML/Reference/Elements/input/submit) and [`image`](/en-US/docs/Web/HTML/Reference/Elements/input/image) `<input>` elements. Its value overrides the {{domxref("HTMLFormElement.enctype", "enctype")}} property of the {{domxref("HTMLFormElement")}} interface if the form is submitted via the input. This property can be retrieved or set. If not set, the value is the empty string (`""`). @@ -39,6 +39,6 @@ inputElement.formEnctype = "application/x-www-form-urlencoded"; - {{domxref("HTMLInputElement.formNoValidate")}} - {{domxref("HTMLInputElement.formTarget")}} - {{domxref("HTMLFormElement.enctype")}} -- [`<input type="submit">`](/en-US/docs/Web/HTML/Element/input/submit) -- [`<input type="image">`](/en-US/docs/Web/HTML/Element/input/image) +- [`<input type="submit">`](/en-US/docs/Web/HTML/Reference/Elements/input/submit) +- [`<input type="image">`](/en-US/docs/Web/HTML/Reference/Elements/input/image) - [Sending form data](/en-US/docs/Learn_web_development/Extensions/Forms/Sending_and_retrieving_form_data) diff --git a/files/en-us/web/api/htmlinputelement/formmethod/index.md b/files/en-us/web/api/htmlinputelement/formmethod/index.md index bae2aacf64ecd0c..43ddd761bffa5ad 100644 --- a/files/en-us/web/api/htmlinputelement/formmethod/index.md +++ b/files/en-us/web/api/htmlinputelement/formmethod/index.md @@ -8,9 +8,9 @@ browser-compat: api.HTMLInputElement.formMethod {{APIRef("HTML DOM")}} -The **`formMethod`** property of the {{domxref("HTMLInputElement")}} interface is the {{Glossary("HTTP")}} method used to submit the {{HtmlElement("form")}} if the {{HTMLElement("input")}} element is the control that submits the form. It reflects the value of the `<input>`'s [`formmethod`](/en-US/docs/Web/HTML/Element/input#formmethod) attribute. +The **`formMethod`** property of the {{domxref("HTMLInputElement")}} interface is the {{Glossary("HTTP")}} method used to submit the {{HtmlElement("form")}} if the {{HTMLElement("input")}} element is the control that submits the form. It reflects the value of the `<input>`'s [`formmethod`](/en-US/docs/Web/HTML/Reference/Elements/input#formmethod) attribute. -This property is valid only for [`submit`](/en-US/docs/Web/HTML/Element/input/submit) and [`image`](/en-US/docs/Web/HTML/Element/input/image) `<input>` elements. +This property is valid only for [`submit`](/en-US/docs/Web/HTML/Reference/Elements/input/submit) and [`image`](/en-US/docs/Web/HTML/Reference/Elements/input/image) `<input>` elements. The value overrides the {{domxref("HTMLFormElement.method", "method")}} property of the {{domxref("HTMLFormElement")}} interface if the form is submitted via the input. This property can be retrieved or set. If set with an empty or invalid value, the invalid default value is `"get"`. If not set at all, the value is the empty string (`""`). @@ -39,6 +39,6 @@ inputElement.formMethod = "post"; - {{domxref("HTMLInputElement.formNoValidate")}} - {{domxref("HTMLInputElement.formTarget")}} - {{domxref("HTMLFormElement.method")}} -- [`<input type="submit">`](/en-US/docs/Web/HTML/Element/input/submit) -- [`<input type="image">`](/en-US/docs/Web/HTML/Element/input/image) +- [`<input type="submit">`](/en-US/docs/Web/HTML/Reference/Elements/input/submit) +- [`<input type="image">`](/en-US/docs/Web/HTML/Reference/Elements/input/image) - [Sending form data](/en-US/docs/Learn_web_development/Extensions/Forms/Sending_and_retrieving_form_data) diff --git a/files/en-us/web/api/htmlinputelement/formnovalidate/index.md b/files/en-us/web/api/htmlinputelement/formnovalidate/index.md index 6cd9f553d96f897..c29cff62dbb9fde 100644 --- a/files/en-us/web/api/htmlinputelement/formnovalidate/index.md +++ b/files/en-us/web/api/htmlinputelement/formnovalidate/index.md @@ -8,9 +8,9 @@ browser-compat: api.HTMLInputElement.formNoValidate {{APIRef("HTML DOM")}} -The **`formNoValidate`** property of the {{domxref("HTMLInputElement")}} interface is a boolean value indicating if the {{htmlelement("form")}} will bypass [constraint validation](/en-US/docs/Web/HTML/Constraint_validation) when submitted via the {{htmlelement("input")}}. It reflects the `<input>` element's [`formnovalidate`](/en-US/docs/Web/HTML/Element/input#formnovalidate) attribute. +The **`formNoValidate`** property of the {{domxref("HTMLInputElement")}} interface is a boolean value indicating if the {{htmlelement("form")}} will bypass [constraint validation](/en-US/docs/Web/HTML/Guides/Constraint_validation) when submitted via the {{htmlelement("input")}}. It reflects the `<input>` element's [`formnovalidate`](/en-US/docs/Web/HTML/Reference/Elements/input#formnovalidate) attribute. -This property is valid only for [`submit`](/en-US/docs/Web/HTML/Element/input/submit) and [`image`](/en-US/docs/Web/HTML/Element/input/image) `<input>` elements. +This property is valid only for [`submit`](/en-US/docs/Web/HTML/Reference/Elements/input/submit) and [`image`](/en-US/docs/Web/HTML/Reference/Elements/input/image) `<input>` elements. Its value overrides the {{domxref("HTMLFormElement.noValidate", "noValidate")}} property of the {{domxref("HTMLFormElement")}} interface if the form is submitted via the input. This property can be retrieved or set. @@ -41,10 +41,10 @@ console.log(inputElement.formNoValidate); - {{domxref("HTMLInputElement.formEnctype")}} - {{domxref("HTMLInputElement.formMethod")}} - {{domxref("HTMLInputElement.formTarget")}} -- [`<input type="submit">`](/en-US/docs/Web/HTML/Element/input/submit) -- [`<input type="image">`](/en-US/docs/Web/HTML/Element/input/image) +- [`<input type="submit">`](/en-US/docs/Web/HTML/Reference/Elements/input/submit) +- [`<input type="image">`](/en-US/docs/Web/HTML/Reference/Elements/input/image) - {{HTMLElement("form")}} - {{domxref("HTMLFormElement.noValidate")}} - {{domxref("HTMLButtonElement.formNoValidate")}} - [Learn: Client-side form validation](/en-US/docs/Learn_web_development/Extensions/Forms/Form_validation) -- [Guide: Constraint validation](/en-US/docs/Web/HTML/Constraint_validation) +- [Guide: Constraint validation](/en-US/docs/Web/HTML/Guides/Constraint_validation) diff --git a/files/en-us/web/api/htmlinputelement/formtarget/index.md b/files/en-us/web/api/htmlinputelement/formtarget/index.md index 357f2940b43207a..e682da446af1570 100644 --- a/files/en-us/web/api/htmlinputelement/formtarget/index.md +++ b/files/en-us/web/api/htmlinputelement/formtarget/index.md @@ -8,9 +8,9 @@ browser-compat: api.HTMLInputElement.formTarget {{APIRef("HTML DOM")}} -The **`formTarget`** property of the {{domxref("HTMLInputElement")}} interface is the tab, window, or iframe where the response of the submitted {{HtmlElement("form")}} is to be displayed. It reflects the value of the {{HTMLElement("input")}} element's [`formtarget`](/en-US/docs/Web/HTML/Element/input#formtarget) attribute. +The **`formTarget`** property of the {{domxref("HTMLInputElement")}} interface is the tab, window, or iframe where the response of the submitted {{HtmlElement("form")}} is to be displayed. It reflects the value of the {{HTMLElement("input")}} element's [`formtarget`](/en-US/docs/Web/HTML/Reference/Elements/input#formtarget) attribute. -This property is valid only for [`submit`](/en-US/docs/Web/HTML/Element/input/submit) and [`image`](/en-US/docs/Web/HTML/Element/input/image) `<input>` elements. +This property is valid only for [`submit`](/en-US/docs/Web/HTML/Reference/Elements/input/submit) and [`image`](/en-US/docs/Web/HTML/Reference/Elements/input/image) `<input>` elements. Its value overrides the {{domxref("HTMLFormElement.target", "target")}} property of the {{domxref("HTMLFormElement")}} interface if the form is submitted via the input. This property can be retrieved or set. If not set, the value is the empty string (`""`). @@ -39,6 +39,6 @@ inputElement.formTarget = "_blank"; - {{domxref("HTMLInputElement.formNoValidate")}} - {{domxref("HTMLInputElement.formMethod")}} - {{domxref("HTMLFormElement.target")}} -- [`<input type="submit">`](/en-US/docs/Web/HTML/Element/input/submit) -- [`<input type="image">`](/en-US/docs/Web/HTML/Element/input/image) +- [`<input type="submit">`](/en-US/docs/Web/HTML/Reference/Elements/input/submit) +- [`<input type="image">`](/en-US/docs/Web/HTML/Reference/Elements/input/image) - [Sending form data](/en-US/docs/Learn_web_development/Extensions/Forms/Sending_and_retrieving_form_data) diff --git a/files/en-us/web/api/htmlinputelement/height/index.md b/files/en-us/web/api/htmlinputelement/height/index.md index 80db816cc2ed2e1..6db3487ccbc06f7 100644 --- a/files/en-us/web/api/htmlinputelement/height/index.md +++ b/files/en-us/web/api/htmlinputelement/height/index.md @@ -8,9 +8,9 @@ browser-compat: api.HTMLInputElement.height {{APIRef("HTML DOM")}} -The **`height`** property of the {{DOMxRef("HTMLInputElement")}} interface specifies the height of a control. It reflects the {{htmlelement("input")}} element's [`height`](/en-US/docs/Web/HTML/Element/input#height) attribute. +The **`height`** property of the {{DOMxRef("HTMLInputElement")}} interface specifies the height of a control. It reflects the {{htmlelement("input")}} element's [`height`](/en-US/docs/Web/HTML/Reference/Elements/input#height) attribute. -The `height` property is valid for the [`image`](/en-US/docs/Web/HTML/Element/input/image) type only. It defines the vertical dimension of the image button, in pixels. If CSS sizing properties apply to the control, the value is the height of the content box of the rendered control, not the value of the `height` attribute. If no `height` is set and CSS does not impact the control's size, the `height` will be the intrinsic height of the image. If the image didn't load, the value will be the height of the `alt` text. The `height` will be `0` if the height is not known; if no `height` is set, CSS doesn't impact the height, the image didn't load, and either the value of the {{DOMxRef("HTMLInputElement.alt", "alt")}} is the empty string or no `src` is set. +The `height` property is valid for the [`image`](/en-US/docs/Web/HTML/Reference/Elements/input/image) type only. It defines the vertical dimension of the image button, in pixels. If CSS sizing properties apply to the control, the value is the height of the content box of the rendered control, not the value of the `height` attribute. If no `height` is set and CSS does not impact the control's size, the `height` will be the intrinsic height of the image. If the image didn't load, the value will be the height of the `alt` text. The `height` will be `0` if the height is not known; if no `height` is set, CSS doesn't impact the height, the image didn't load, and either the value of the {{DOMxRef("HTMLInputElement.alt", "alt")}} is the empty string or no `src` is set. ## Value diff --git a/files/en-us/web/api/htmlinputelement/indeterminate/index.md b/files/en-us/web/api/htmlinputelement/indeterminate/index.md index 1239df32e6454b3..2e6a91ba27677ff 100644 --- a/files/en-us/web/api/htmlinputelement/indeterminate/index.md +++ b/files/en-us/web/api/htmlinputelement/indeterminate/index.md @@ -8,7 +8,7 @@ browser-compat: api.HTMLInputElement.indeterminate {{APIRef("HTML DOM")}} -The **`indeterminate`** property of the {{domxref("HTMLInputElement")}} interface returns a boolean value that indicates whether the checkbox is in the _indeterminate_ state. For example, a "select all/deselect all" checkbox may be in the indeterminate state when some but not all of its sub-controls are checked. The `indeterminate` state can only be set via JavaScript and is only relevant to [`checkbox`](/en-US/docs/Web/HTML/Element/input/checkbox) controls. +The **`indeterminate`** property of the {{domxref("HTMLInputElement")}} interface returns a boolean value that indicates whether the checkbox is in the _indeterminate_ state. For example, a "select all/deselect all" checkbox may be in the indeterminate state when some but not all of its sub-controls are checked. The `indeterminate` state can only be set via JavaScript and is only relevant to [`checkbox`](/en-US/docs/Web/HTML/Reference/Elements/input/checkbox) controls. It is unrelated to the {{domxref("HTMLInputElement.checked")}} property, and an indeterminate checkbox can be either checked or unchecked. Being indeterminate only affects the checkbox's appearance (see example below), not its presence when submitted (which is controlled by the checkedness). @@ -43,5 +43,5 @@ checkbox.indeterminate = true; - {{domxref("HTMLInputElement")}} - {{domxref("HTMLInputElement.checked")}} - {{HTMLElement("input")}} -- [Indeterminate state checkboxes](/en-US/docs/Web/HTML/Element/input/checkbox#indeterminate_state_checkboxes) +- [Indeterminate state checkboxes](/en-US/docs/Web/HTML/Reference/Elements/input/checkbox#indeterminate_state_checkboxes) - CSS {{cssxref(":indeterminate")}} property diff --git a/files/en-us/web/api/htmlinputelement/index.md b/files/en-us/web/api/htmlinputelement/index.md index 0aa7621e8ef5d9d..7900719092c8294 100644 --- a/files/en-us/web/api/htmlinputelement/index.md +++ b/files/en-us/web/api/htmlinputelement/index.md @@ -39,31 +39,31 @@ Some properties only apply to input element types that support the corresponding - {{domxref("HTMLInputElement.list", "list")}} {{ReadOnlyInline}} - - : Returns the element pointed to by the [`list`](/en-US/docs/Web/HTML/Element/input#list) attribute. The property may be `null` if no HTML element is found in the same tree. + - : Returns the element pointed to by the [`list`](/en-US/docs/Web/HTML/Reference/Elements/input#list) attribute. The property may be `null` if no HTML element is found in the same tree. - {{domxref("HTMLInputElement.multiple", "multiple")}} - - : A boolean that represents the element's [`multiple`](/en-US/docs/Web/HTML/Element/input#multiple) attribute, indicating whether more than one value is possible (e.g., multiple files). + - : A boolean that represents the element's [`multiple`](/en-US/docs/Web/HTML/Reference/Elements/input#multiple) attribute, indicating whether more than one value is possible (e.g., multiple files). - {{domxref("HTMLInputElement.name", "name")}} - - : A string that represents the element's [`name`](/en-US/docs/Web/HTML/Element/input#name) attribute, containing a name that identifies the element when submitting the form. + - : A string that represents the element's [`name`](/en-US/docs/Web/HTML/Reference/Elements/input#name) attribute, containing a name that identifies the element when submitting the form. - {{domxref("HTMLInputElement.popoverTargetAction", "popoverTargetAction")}} - - : Gets and sets the action to be performed (`"hide"`, `"show"`, or `"toggle"`) on a popover element being controlled by an {{HTMLElement("input")}} element of `type="button"`. It reflects the value of the [`popovertargetaction`](/en-US/docs/Web/HTML/Element/input#popovertargetaction) HTML attribute. + - : Gets and sets the action to be performed (`"hide"`, `"show"`, or `"toggle"`) on a popover element being controlled by an {{HTMLElement("input")}} element of `type="button"`. It reflects the value of the [`popovertargetaction`](/en-US/docs/Web/HTML/Reference/Elements/input#popovertargetaction) HTML attribute. - {{domxref("HTMLInputElement.popoverTargetElement", "popoverTargetElement")}} - - : Gets and sets the popover element to control via an {{HTMLElement("input")}} element of `type="button"`. The JavaScript equivalent of the [`popovertarget`](/en-US/docs/Web/HTML/Element/input#popovertarget) HTML attribute. + - : Gets and sets the popover element to control via an {{HTMLElement("input")}} element of `type="button"`. The JavaScript equivalent of the [`popovertarget`](/en-US/docs/Web/HTML/Reference/Elements/input#popovertarget) HTML attribute. - {{domxref("HTMLInputElement.step", "step")}} - - : A string that represents the element's [`step`](/en-US/docs/Web/HTML/Element/input#step) attribute, which works with [`min`](/en-US/docs/Web/HTML/Element/input#min) and [`max`](/en-US/docs/Web/HTML/Element/input#max) to limit the increments at which a numeric or date-time value can be set. It can be the string `any` or a positive floating point number. If this is not set to `any`, the control accepts only values at multiples of the step value greater than the minimum. + - : A string that represents the element's [`step`](/en-US/docs/Web/HTML/Reference/Elements/input#step) attribute, which works with [`min`](/en-US/docs/Web/HTML/Reference/Elements/input#min) and [`max`](/en-US/docs/Web/HTML/Reference/Elements/input#max) to limit the increments at which a numeric or date-time value can be set. It can be the string `any` or a positive floating point number. If this is not set to `any`, the control accepts only values at multiples of the step value greater than the minimum. - {{domxref("HTMLInputElement.type", "type")}} - - : A string that represents the element's [`type`](/en-US/docs/Web/HTML/Element/input#type) attribute, indicating the type of control to display. For possible values, see the documentation for the [`type`](/en-US/docs/Web/HTML/Element/input#type) attribute. + - : A string that represents the element's [`type`](/en-US/docs/Web/HTML/Reference/Elements/input#type) attribute, indicating the type of control to display. For possible values, see the documentation for the [`type`](/en-US/docs/Web/HTML/Reference/Elements/input#type) attribute. - {{domxref("HTMLInputElement.useMap", "useMap")}} {{Deprecated_Inline}} @@ -88,32 +88,32 @@ Some properties only apply to input element types that support the corresponding - {{domxref("HTMLInputElement.formAction", "formAction")}} - - : A string that represents the element's [`formaction`](/en-US/docs/Web/HTML/Element/input#formaction) attribute, containing the URL of a program that processes information submitted by the element. This overrides the [`action`](/en-US/docs/Web/HTML/Element/form#action) attribute of the parent form. + - : A string that represents the element's [`formaction`](/en-US/docs/Web/HTML/Reference/Elements/input#formaction) attribute, containing the URL of a program that processes information submitted by the element. This overrides the [`action`](/en-US/docs/Web/HTML/Reference/Elements/form#action) attribute of the parent form. - {{domxref("HTMLInputElement.formEnctype", "formEnctype")}} - - : A string that represents the element's [`formenctype`](/en-US/docs/Web/HTML/Element/input#formenctype) attribute, containing the type of content that is used to submit the form to the server. This overrides the [`enctype`](/en-US/docs/Web/HTML/Element/form#enctype) attribute of the parent form. + - : A string that represents the element's [`formenctype`](/en-US/docs/Web/HTML/Reference/Elements/input#formenctype) attribute, containing the type of content that is used to submit the form to the server. This overrides the [`enctype`](/en-US/docs/Web/HTML/Reference/Elements/form#enctype) attribute of the parent form. - {{domxref("HTMLInputElement.formMethod", "formMethod")}} - - : A string that represents the element's [`formmethod`](/en-US/docs/Web/HTML/Element/input#formmethod) attribute, containing the HTTP method that the browser uses to submit the form. This overrides the [`method`](/en-US/docs/Web/HTML/Element/form#method) attribute of the parent form. + - : A string that represents the element's [`formmethod`](/en-US/docs/Web/HTML/Reference/Elements/input#formmethod) attribute, containing the HTTP method that the browser uses to submit the form. This overrides the [`method`](/en-US/docs/Web/HTML/Reference/Elements/form#method) attribute of the parent form. - {{domxref("HTMLInputElement.formNoValidate", "formNoValidate")}} - - : A boolean that represents the element's [`formnovalidate`](/en-US/docs/Web/HTML/Element/input#formnovalidate) attribute, indicating that the form is not to be validated when it is submitted. This overrides the [`novalidate`](/en-US/docs/Web/HTML/Element/form#novalidate) attribute of the parent form. + - : A boolean that represents the element's [`formnovalidate`](/en-US/docs/Web/HTML/Reference/Elements/input#formnovalidate) attribute, indicating that the form is not to be validated when it is submitted. This overrides the [`novalidate`](/en-US/docs/Web/HTML/Reference/Elements/form#novalidate) attribute of the parent form. - {{domxref("HTMLInputElement.formTarget", "formTarget")}} - - : A string that represents the element's [`formtarget`](/en-US/docs/Web/HTML/Element/input#formtarget) attribute, containing a name or keyword indicating where to display the response that is received after submitting the form. This overrides the [`target`](/en-US/docs/Web/HTML/Element/form#target) attribute of the parent form. + - : A string that represents the element's [`formtarget`](/en-US/docs/Web/HTML/Reference/Elements/input#formtarget) attribute, containing a name or keyword indicating where to display the response that is received after submitting the form. This overrides the [`target`](/en-US/docs/Web/HTML/Reference/Elements/form#target) attribute of the parent form. ### Instance properties that apply to any type of input element that is not hidden - {{domxref("HTMLInputElement.disabled", "disabled")}} - - : A boolean that represents the element's [`disabled`](/en-US/docs/Web/HTML/Element/input#disabled) attribute, indicating that the control is not available for interaction. The input values will not be submitted with the form. See also [`readonly`](/en-US/docs/Web/HTML/Element/input#readonly). + - : A boolean that represents the element's [`disabled`](/en-US/docs/Web/HTML/Reference/Elements/input#disabled) attribute, indicating that the control is not available for interaction. The input values will not be submitted with the form. See also [`readonly`](/en-US/docs/Web/HTML/Reference/Elements/input#readonly). - {{domxref("HTMLInputElement.required", "required")}} - - : A boolean that represents the element's [`required`](/en-US/docs/Web/HTML/Element/input#required) attribute, indicating that the user must fill in a value before submitting a form. + - : A boolean that represents the element's [`required`](/en-US/docs/Web/HTML/Reference/Elements/input#required) attribute, indicating that the user must fill in a value before submitting a form. - {{domxref("HTMLInputElement.validationMessage", "validationMessage")}} {{ReadOnlyInline}} @@ -143,28 +143,28 @@ Some properties only apply to input element types that support the corresponding - {{domxref("HTMLInputElement.alt", "alt")}} - - : A string that represents the element's [`alt`](/en-US/docs/Web/HTML/Element/input#alt) attribute, containing alternative text to use. + - : A string that represents the element's [`alt`](/en-US/docs/Web/HTML/Reference/Elements/input#alt) attribute, containing alternative text to use. - {{domxref("HTMLInputElement.height", "height")}} - - : A string that represents the element's [`height`](/en-US/docs/Web/HTML/Element/input#height) attribute, which defines the height of the image displayed for the button. + - : A string that represents the element's [`height`](/en-US/docs/Web/HTML/Reference/Elements/input#height) attribute, which defines the height of the image displayed for the button. - {{domxref("HTMLInputElement.src", "src")}} - - : A string that represents the element's [`src`](/en-US/docs/Web/HTML/Element/input#src) attribute, which specifies a URI for the location of an image to display on the graphical submit button. + - : A string that represents the element's [`src`](/en-US/docs/Web/HTML/Reference/Elements/input#src) attribute, which specifies a URI for the location of an image to display on the graphical submit button. - {{domxref("HTMLInputElement.width", "width")}} - - : A string that represents the element's [`width`](/en-US/docs/Web/HTML/Element/input#width) attribute, which defines the width of the image displayed for the button. + - : A string that represents the element's [`width`](/en-US/docs/Web/HTML/Reference/Elements/input#width) attribute, which defines the width of the image displayed for the button. ### Instance properties that apply only to elements of type file - {{domxref("HTMLInputElement.accept", "accept")}} - - : A string that represents the element's [`accept`](/en-US/docs/Web/HTML/Element/input#accept) attribute, containing comma-separated list of file types that can be selected. + - : A string that represents the element's [`accept`](/en-US/docs/Web/HTML/Reference/Elements/input#accept) attribute, containing comma-separated list of file types that can be selected. - {{domxref("HTMLInputElement.capture", "capture")}} - - : A string that represents the element's [`capture`](/en-US/docs/Web/HTML/Element/input#capture) attribute, indicating the media capture input method in file upload controls. + - : A string that represents the element's [`capture`](/en-US/docs/Web/HTML/Reference/Elements/input#capture) attribute, indicating the media capture input method in file upload controls. - {{domxref("HTMLInputElement.files", "files")}} @@ -172,7 +172,7 @@ Some properties only apply to input element types that support the corresponding - {{domxref("HTMLInputElement.webkitdirectory", "webkitdirectory")}} - - : A boolean that represents the [`webkitdirectory`](/en-US/docs/Web/HTML/Element/input#webkitdirectory) attribute. If `true`, the file-system-picker interface only accepts directories instead of files. + - : A boolean that represents the [`webkitdirectory`](/en-US/docs/Web/HTML/Reference/Elements/input#webkitdirectory) attribute. If `true`, the file-system-picker interface only accepts directories instead of files. - {{domxref("HTMLInputElement.webkitEntries", "webkitEntries")}} {{ReadOnlyInline}} - : Describes the currently selected files or directories. @@ -181,35 +181,35 @@ Some properties only apply to input element types that support the corresponding - {{domxref("HTMLInputElement.autocomplete", "autocomplete")}} - - : A string that represents the element's [`autocomplete`](/en-US/docs/Web/HTML/Element/input#autocomplete) attribute, indicating whether the value of the control can be automatically completed by the browser. + - : A string that represents the element's [`autocomplete`](/en-US/docs/Web/HTML/Reference/Elements/input#autocomplete) attribute, indicating whether the value of the control can be automatically completed by the browser. - {{domxref("HTMLInputElement.max", "max")}} - - : A string that represents the element's [`max`](/en-US/docs/Web/HTML/Element/input#max) attribute, containing the maximum (numeric or date-time) value for this item, which must not be less than its minimum ([`min`](/en-US/docs/Web/HTML/Element/input#min) attribute) value. + - : A string that represents the element's [`max`](/en-US/docs/Web/HTML/Reference/Elements/input#max) attribute, containing the maximum (numeric or date-time) value for this item, which must not be less than its minimum ([`min`](/en-US/docs/Web/HTML/Reference/Elements/input#min) attribute) value. - {{domxref("HTMLInputElement.maxLength", "maxLength")}} - - : A number that represents the element's [`maxlength`](/en-US/docs/Web/HTML/Element/input#maxlength) attribute, containing the maximum number of characters (in Unicode code points) that the value can have. + - : A number that represents the element's [`maxlength`](/en-US/docs/Web/HTML/Reference/Elements/input#maxlength) attribute, containing the maximum number of characters (in Unicode code points) that the value can have. - {{domxref("HTMLInputElement.min", "min")}} - - : A string that represents the element's [`min`](/en-US/docs/Web/HTML/Element/input#min) attribute, containing the minimum (numeric or date-time) value for this item, which must not be greater than its maximum ([`max`](/en-US/docs/Web/HTML/Element/input#max) attribute) value. + - : A string that represents the element's [`min`](/en-US/docs/Web/HTML/Reference/Elements/input#min) attribute, containing the minimum (numeric or date-time) value for this item, which must not be greater than its maximum ([`max`](/en-US/docs/Web/HTML/Reference/Elements/input#max) attribute) value. - {{domxref("HTMLInputElement.minLength", "minLength")}} - - : A number that represents the element's [`minlength`](/en-US/docs/Web/HTML/Element/input#minlength) attribute, containing the minimum number of characters (in Unicode code points) that the value can have. + - : A number that represents the element's [`minlength`](/en-US/docs/Web/HTML/Reference/Elements/input#minlength) attribute, containing the minimum number of characters (in Unicode code points) that the value can have. - {{domxref("HTMLInputElement.pattern", "pattern")}} - - : A string that represents the element's [`pattern`](/en-US/docs/Web/HTML/Element/input#pattern) attribute, containing a regular expression that the control's value is checked against. Use the [`title`](/en-US/docs/Web/HTML/Element/input#title) attribute to describe the pattern to help the user. This attribute only applies when the value of the [`type`](/en-US/docs/Web/HTML/Element/input#type) attribute is `text`, `search`, `tel`, `url` or `email`. + - : A string that represents the element's [`pattern`](/en-US/docs/Web/HTML/Reference/Elements/input#pattern) attribute, containing a regular expression that the control's value is checked against. Use the [`title`](/en-US/docs/Web/HTML/Reference/Elements/input#title) attribute to describe the pattern to help the user. This attribute only applies when the value of the [`type`](/en-US/docs/Web/HTML/Reference/Elements/input#type) attribute is `text`, `search`, `tel`, `url` or `email`. - {{domxref("HTMLInputElement.placeholder", "placeholder")}} - - : A string that represents the element's [`placeholder`](/en-US/docs/Web/HTML/Element/input#placeholder) attribute, containing a hint to the user of what can be entered in the control. The placeholder text must not contain carriage returns or line-feeds. This attribute only applies when the value of the [`type`](/en-US/docs/Web/HTML/Element/input#type) attribute is `text`, `search`, `tel`, `url` or `email`. + - : A string that represents the element's [`placeholder`](/en-US/docs/Web/HTML/Reference/Elements/input#placeholder) attribute, containing a hint to the user of what can be entered in the control. The placeholder text must not contain carriage returns or line-feeds. This attribute only applies when the value of the [`type`](/en-US/docs/Web/HTML/Reference/Elements/input#type) attribute is `text`, `search`, `tel`, `url` or `email`. - {{domxref("HTMLInputElement.readOnly", "readOnly")}} - - : A boolean that represents the element's [`readonly`](/en-US/docs/Web/HTML/Element/input#readonly) attribute, indicating that the user cannot modify the value of the control. This is ignored if the [`type`](/en-US/docs/Web/HTML/Element/input#type) is `hidden`, `range`, `color`, `checkbox`, `radio`, `file`, or a button type. + - : A boolean that represents the element's [`readonly`](/en-US/docs/Web/HTML/Reference/Elements/input#readonly) attribute, indicating that the user cannot modify the value of the control. This is ignored if the [`type`](/en-US/docs/Web/HTML/Reference/Elements/input#type) is `hidden`, `range`, `color`, `checkbox`, `radio`, `file`, or a button type. - {{domxref("HTMLInputElement.selectionDirection", "selectionDirection")}} @@ -224,7 +224,7 @@ Some properties only apply to input element types that support the corresponding - : A number that represents the beginning index of the selected text. When nothing is selected, this returns the position of the text input cursor (caret) inside of the {{HTMLElement("input")}} element. - {{domxref("HTMLInputElement.size", "size")}} - - : A number that represents the element's [`size`](/en-US/docs/Web/HTML/Element/input#size) attribute, containing visual size of the control. This value is in pixels unless the value of [`type`](/en-US/docs/Web/HTML/Element/input#type) is `text` or `password`, in which case, it is an integer number of characters. Applies only when [`type`](/en-US/docs/Web/HTML/Element/input#type) is set to `text`, `search`, `tel`, `url`, `email`, or `password`. + - : A number that represents the element's [`size`](/en-US/docs/Web/HTML/Reference/Elements/input#size) attribute, containing visual size of the control. This value is in pixels unless the value of [`type`](/en-US/docs/Web/HTML/Reference/Elements/input#type) is `text` or `password`, in which case, it is an integer number of characters. Applies only when [`type`](/en-US/docs/Web/HTML/Reference/Elements/input#type) is set to `text`, `search`, `tel`, `url`, `email`, or `password`. ## Instance methods @@ -260,10 +260,10 @@ _Also inherits methods from its parent interface, {{domxref("HTMLElement")}}._ - {{domxref("HTMLInputElement.stepDown()", "stepDown()")}} - - : Decrements the [`value`](/en-US/docs/Web/HTML/Element/input#value) by ([`step`](/en-US/docs/Web/HTML/Element/input#step) \* n), where n defaults to 1 if not specified. + - : Decrements the [`value`](/en-US/docs/Web/HTML/Reference/Elements/input#value) by ([`step`](/en-US/docs/Web/HTML/Reference/Elements/input#step) \* n), where n defaults to 1 if not specified. - {{domxref("HTMLInputElement.stepUp()", "stepUp()")}} - - : Increments the [`value`](/en-US/docs/Web/HTML/Element/input#value) by ([`step`](/en-US/docs/Web/HTML/Element/input#step) \* n), where n defaults to 1 if not specified. + - : Increments the [`value`](/en-US/docs/Web/HTML/Reference/Elements/input#value) by ([`step`](/en-US/docs/Web/HTML/Reference/Elements/input#step) \* n), where n defaults to 1 if not specified. ## Events @@ -279,8 +279,8 @@ Listen to these events using {{domxref("EventTarget.addEventListener", "addEvent - : Fired when a search is initiated on an {{HTMLElement("input")}} of `type="search"`. - {{domxref("HTMLInputElement/select_event", "select")}} event - : Fired when some text has been selected. -- {{domxref("HTMLInputElement/selectionchange_event", "selectionchange")}} event {{Experimental_Inline}} - - : Fires when the text selection in a {{HTMLElement("input")}} element has been changed. +- {{domxref("HTMLInputElement/selectionchange_event", "selectionchange")}} event + - : Fires when the text selection in an {{HTMLElement("input")}} element has been changed. ## Specifications diff --git a/files/en-us/web/api/htmlinputelement/invalid_event/index.md b/files/en-us/web/api/htmlinputelement/invalid_event/index.md index 1a78c22f44c0314..c4a6455f3dd541c 100644 --- a/files/en-us/web/api/htmlinputelement/invalid_event/index.md +++ b/files/en-us/web/api/htmlinputelement/invalid_event/index.md @@ -18,10 +18,10 @@ It is not checked on {{domxref("Element/blur_event", "blur")}}. Use the event name in methods like {{domxref("EventTarget.addEventListener", "addEventListener()")}}, or set an event handler property. -```js -addEventListener("invalid", (event) => {}); +```js-nolint +addEventListener("invalid", (event) => { }) -oninvalid = (event) => {}; +oninvalid = (event) => { } ``` ## Event type diff --git a/files/en-us/web/api/htmlinputelement/list/index.md b/files/en-us/web/api/htmlinputelement/list/index.md index 840e2563c898b18..79fee4846bf3ebe 100644 --- a/files/en-us/web/api/htmlinputelement/list/index.md +++ b/files/en-us/web/api/htmlinputelement/list/index.md @@ -8,7 +8,7 @@ browser-compat: api.HTMLInputElement.list {{ApiRef("HTML DOM")}} -The **`list`** read-only property of the {{domxref("HTMLInputElement")}} interface returns the {{domxref("HTMLDataListElement")}} pointed to by the [`list`](/en-US/docs/Web/HTML/Element/input#list) attribute of the element, or `null` if the `list` attribute is not defined or the `list` attribute's value is not associated with any `<datalist>` in the same tree. +The **`list`** read-only property of the {{domxref("HTMLInputElement")}} interface returns the {{domxref("HTMLDataListElement")}} pointed to by the [`list`](/en-US/docs/Web/HTML/Reference/Elements/input#list) attribute of the element, or `null` if the `list` attribute is not defined or the `list` attribute's value is not associated with any `<datalist>` in the same tree. > [!NOTE] > This is a read-only property. To associate a `<datalist>` with an element, set the value of the `list` attribute with {{domxref("Element.setAttribute", "setAttribute()")}}. @@ -25,9 +25,9 @@ Given the following HTML: <label for="planet">Which planet are you from?</label> <input id="planet" type="text" list="superhero" /> <datalist id="superhero"> - <option value="Azarath" /> - <option value="Krypton" /> - <option value="Tamaran" /> + <option value="Azarath"></option> + <option value="Krypton"></option> + <option value="Tamaran"></option> </datalist> ``` diff --git a/files/en-us/web/api/htmlinputelement/max/index.md b/files/en-us/web/api/htmlinputelement/max/index.md index 091a40de37d367b..0979fdef6fddc63 100644 --- a/files/en-us/web/api/htmlinputelement/max/index.md +++ b/files/en-us/web/api/htmlinputelement/max/index.md @@ -8,7 +8,7 @@ browser-compat: api.HTMLInputElement.max {{ApiRef("HTML DOM")}} -The **`max`** property of the {{domxref("HTMLInputElement")}} interface reflects the {{HTMLElement("input")}} element's [`max`](/en-US/docs/Web/HTML/Element/input#max) attribute, which generally defines the maximum valid value for a numeric or date-time input. If the attribute is not explicitly set, the `max` property is an empty string. +The **`max`** property of the {{domxref("HTMLInputElement")}} interface reflects the {{HTMLElement("input")}} element's [`max`](/en-US/docs/Web/HTML/Reference/Elements/input#max) attribute, which generally defines the maximum valid value for a numeric or date-time input. If the attribute is not explicitly set, the `max` property is an empty string. ## Value diff --git a/files/en-us/web/api/htmlinputelement/maxlength/index.md b/files/en-us/web/api/htmlinputelement/maxlength/index.md index 9f741151c6cf215..beeceb696b3c591 100644 --- a/files/en-us/web/api/htmlinputelement/maxlength/index.md +++ b/files/en-us/web/api/htmlinputelement/maxlength/index.md @@ -8,7 +8,7 @@ browser-compat: api.HTMLInputElement.maxLength {{ApiRef("HTML DOM")}} -The **`maxLength`** property of the {{domxref("HTMLInputElement")}} interface indicates the maximum number of characters (in UTF-16 code units) allowed to be entered for the value of the {{HTMLElement("input")}} element, and the maximum number of characters allowed for the value to be valid. It reflects the element's [`maxlength`](/en-US/docs/Web/HTML/Element/input#maxlength) attribute. `-1` means there is no limit on the length of the value. +The **`maxLength`** property of the {{domxref("HTMLInputElement")}} interface indicates the maximum number of characters (in UTF-16 code units) allowed to be entered for the value of the {{HTMLElement("input")}} element, and the maximum number of characters allowed for the value to be valid. It reflects the element's [`maxlength`](/en-US/docs/Web/HTML/Reference/Elements/input#maxlength) attribute. `-1` means there is no limit on the length of the value. > [!NOTE] > Browser generally prevent users from entering more characters than the `maxlength` attribute allows. Should the length be longer, the element is considered invalid and the {{domxref("ValidityState")}} object's {{domxref("ValidityState.tooLong", "tooLong")}} property will be `true`. diff --git a/files/en-us/web/api/htmlinputelement/min/index.md b/files/en-us/web/api/htmlinputelement/min/index.md index 102f3455ff5905e..1423e00c6e4e7dc 100644 --- a/files/en-us/web/api/htmlinputelement/min/index.md +++ b/files/en-us/web/api/htmlinputelement/min/index.md @@ -8,7 +8,7 @@ browser-compat: api.HTMLInputElement.min {{ApiRef("HTML DOM")}} -The **`min`** property of the {{domxref("HTMLInputElement")}} interface reflects the {{HTMLElement("input")}} element's [`min`](/en-US/docs/Web/HTML/Element/input#min) attribute, which generally defines the minimum valid value for a numeric or date-time input. If the attribute is not explicitly set, the `min` property is an empty string. +The **`min`** property of the {{domxref("HTMLInputElement")}} interface reflects the {{HTMLElement("input")}} element's [`min`](/en-US/docs/Web/HTML/Reference/Elements/input#min) attribute, which generally defines the minimum valid value for a numeric or date-time input. If the attribute is not explicitly set, the `min` property is an empty string. ## Value diff --git a/files/en-us/web/api/htmlinputelement/minlength/index.md b/files/en-us/web/api/htmlinputelement/minlength/index.md index 64a9ce05071c330..cb0ffba78c54a49 100644 --- a/files/en-us/web/api/htmlinputelement/minlength/index.md +++ b/files/en-us/web/api/htmlinputelement/minlength/index.md @@ -8,7 +8,7 @@ browser-compat: api.HTMLInputElement.minLength {{ApiRef("HTML DOM")}} -The **`minLength`** property of the {{domxref("HTMLInputElement")}} interface indicates the minimum number of characters (in UTF-16 code units) required for the value of the {{HTMLElement("input")}} element to be valid. It reflects the element's [`minlength`](/en-US/docs/Web/HTML/Element/input#minlength) attribute. `-1` means there is no minimum length requirement. +The **`minLength`** property of the {{domxref("HTMLInputElement")}} interface indicates the minimum number of characters (in UTF-16 code units) required for the value of the {{HTMLElement("input")}} element to be valid. It reflects the element's [`minlength`](/en-US/docs/Web/HTML/Reference/Elements/input#minlength) attribute. `-1` means there is no minimum length requirement. > [!NOTE] > If the input has a value, and that value has fewer characters than the `minlength` attribute requires, the element is considered invalid and the {{domxref("ValidityState")}} object's {{domxref("ValidityState.tooShort", "tooShort")}} property will be `true`. diff --git a/files/en-us/web/api/htmlinputelement/name/index.md b/files/en-us/web/api/htmlinputelement/name/index.md index ee5e3ed319432c3..bd4e404fb9c5fca 100644 --- a/files/en-us/web/api/htmlinputelement/name/index.md +++ b/files/en-us/web/api/htmlinputelement/name/index.md @@ -8,7 +8,7 @@ browser-compat: api.HTMLInputElement.name {{ApiRef("HTML DOM")}} -The **`name`** property of the {{domxref("HTMLInputElement")}} interface indicates the name of the {{HTMLElement("input")}} element. It reflects the element's [`name`](/en-US/docs/Web/HTML/Element/input#name) attribute. +The **`name`** property of the {{domxref("HTMLInputElement")}} interface indicates the name of the {{HTMLElement("input")}} element. It reflects the element's [`name`](/en-US/docs/Web/HTML/Reference/Elements/input#name) attribute. ## Value diff --git a/files/en-us/web/api/htmlinputelement/pattern/index.md b/files/en-us/web/api/htmlinputelement/pattern/index.md index 2eea00b32f22866..ffc106acd15df38 100644 --- a/files/en-us/web/api/htmlinputelement/pattern/index.md +++ b/files/en-us/web/api/htmlinputelement/pattern/index.md @@ -8,9 +8,9 @@ browser-compat: api.HTMLInputElement.pattern {{ APIRef("HTML DOM") }} -The **`pattern`** property of the {{DOMxRef("HTMLInputElement")}} interface represents a [regular expression](/en-US/docs/Web/JavaScript/Guide/Regular_expressions) a non-null {{HTMLElement("input")}} value should match. It reflects the {{htmlelement("input")}} element's [`pattern`](/en-US/docs/Web/HTML/Attributes/pattern) attribute. +The **`pattern`** property of the {{DOMxRef("HTMLInputElement")}} interface represents a [regular expression](/en-US/docs/Web/JavaScript/Guide/Regular_expressions) a non-null {{HTMLElement("input")}} value should match. It reflects the {{htmlelement("input")}} element's [`pattern`](/en-US/docs/Web/HTML/Reference/Attributes/pattern) attribute. -The `pattern` property is valid for `text`, `search`, `url`, `tel`, `email`, and `password` types. It defines a regular expression that the input's {{DOMxRef("HTMLInputElement.value", "value")}} must match in order for the value to pass [constraint validation](/en-US/docs/Web/HTML/Constraint_validation). +The `pattern` property is valid for `text`, `search`, `url`, `tel`, `email`, and `password` types. It defines a regular expression that the input's {{DOMxRef("HTMLInputElement.value", "value")}} must match in order for the value to pass [constraint validation](/en-US/docs/Web/HTML/Guides/Constraint_validation). If a non-`null` value doesn't conform to the constraints set by the `pattern` value, the {{domxref('ValidityState')}} object's read-only {{domxref('ValidityState.patternMismatch','patternMismatch')}} property will be true. @@ -37,5 +37,5 @@ console.log(input.pattern); - {{HTMLElement("input")}} - {{DOMXref("HTMLInputElement.value")}} -- [Client-side validation](/en-US/docs/Web/HTML/Element/input#client-side_validation) +- [Client-side validation](/en-US/docs/Web/HTML/Reference/Elements/input#client-side_validation) - {{CSSXref(":valid")}} and {{CSSXref(":invalid")}} pseudo-classes diff --git a/files/en-us/web/api/htmlinputelement/placeholder/index.md b/files/en-us/web/api/htmlinputelement/placeholder/index.md index a06f77be31b5ac9..2df71679c149f5c 100644 --- a/files/en-us/web/api/htmlinputelement/placeholder/index.md +++ b/files/en-us/web/api/htmlinputelement/placeholder/index.md @@ -8,7 +8,7 @@ browser-compat: api.HTMLInputElement.placeholder {{ APIRef("HTML DOM") }} -The **`placeholder`** property of the {{DOMxRef("HTMLInputElement")}} interface represents a hint to the user of what can be entered in the control. It reflects the {{htmlelement("input")}} element's [`placeholder`](/en-US/docs/Web/HTML/Element/input#placeholder) attribute. +The **`placeholder`** property of the {{DOMxRef("HTMLInputElement")}} interface represents a hint to the user of what can be entered in the control. It reflects the {{htmlelement("input")}} element's [`placeholder`](/en-US/docs/Web/HTML/Reference/Elements/input#placeholder) attribute. ## Value diff --git a/files/en-us/web/api/htmlinputelement/popovertargetaction/index.md b/files/en-us/web/api/htmlinputelement/popovertargetaction/index.md index e17623aa9365727..53d16c263c0cc6a 100644 --- a/files/en-us/web/api/htmlinputelement/popovertargetaction/index.md +++ b/files/en-us/web/api/htmlinputelement/popovertargetaction/index.md @@ -10,7 +10,7 @@ browser-compat: api.HTMLInputElement.popoverTargetAction The **`popoverTargetAction`** property of the {{domxref("HTMLInputElement")}} interface gets and sets the action to be performed (`"hide"`, `"show"`, or `"toggle"`) on a popover element being controlled by an {{htmlelement("input")}} element of `type="button"`. -It reflects the value of the [`popovertargetaction`](/en-US/docs/Web/HTML/Element/button#popovertargetaction) HTML attribute. +It reflects the value of the [`popovertargetaction`](/en-US/docs/Web/HTML/Reference/Elements/button#popovertargetaction) HTML attribute. ## Value @@ -30,8 +30,8 @@ An enumerated value. Possible values are: This example shows the basic use of the popover API with a "toggle" value set for the `popoverTargetAction` property. The `popover` attribute is set to [`"auto"`](/en-US/docs/Web/API/Popover_API/Using#auto_state_and_light_dismiss), so the popover can be closed ("light-dismissed") by clicking outside the popover area. -First we define an [`<input>`](/en-US/docs/Web/HTML/Element/input/button) of `type="button"` that we will use to show and hide the popover, and a `<div>` that will be the popover. -In this case we don't set the [`popovertargetaction`](/en-US/docs/Web/HTML/Element/button#popovertargetaction) HTML attribute on the button or the [`popover`](/en-US/docs/Web/HTML/Global_attributes/popover) attribute on the `<div>`, as we will be doing so programmatically. +First we define an [`<input>`](/en-US/docs/Web/HTML/Reference/Elements/input/button) of `type="button"` that we will use to show and hide the popover, and a `<div>` that will be the popover. +In this case we don't set the [`popovertargetaction`](/en-US/docs/Web/HTML/Reference/Elements/button#popovertargetaction) HTML attribute on the button or the [`popover`](/en-US/docs/Web/HTML/Reference/Global_attributes/popover) attribute on the `<div>`, as we will be doing so programmatically. ```html <input id="toggleBtn" type="button" value="Toggle popover" /> @@ -47,7 +47,7 @@ const toggleBtn = document.getElementById("toggleBtn"); // Check for popover API support. function supportsPopover() { - return HTMLElement.prototype.hasOwnProperty("popover"); + return Object.hasOwn(HTMLElement.prototype, "popover"); } ``` @@ -94,7 +94,7 @@ A `manual` popover must be closed explicitly, and not "light dismissed" by selec ```js function supportsPopover() { - return HTMLElement.prototype.hasOwnProperty("popover"); + return Object.hasOwn(HTMLElement.prototype, "popover"); } const popover = document.getElementById("mypopover"); @@ -135,5 +135,5 @@ The popover can be displayed by selecting the "Show popover" button, and dismiss ## See also -- [`popover`](/en-US/docs/Web/HTML/Global_attributes/popover) HTML global attribute +- [`popover`](/en-US/docs/Web/HTML/Reference/Global_attributes/popover) HTML global attribute - [Popover API](/en-US/docs/Web/API/Popover_API) diff --git a/files/en-us/web/api/htmlinputelement/popovertargetelement/index.md b/files/en-us/web/api/htmlinputelement/popovertargetelement/index.md index c2c32a21d08186f..9b828d027e85d27 100644 --- a/files/en-us/web/api/htmlinputelement/popovertargetelement/index.md +++ b/files/en-us/web/api/htmlinputelement/popovertargetelement/index.md @@ -10,11 +10,11 @@ browser-compat: api.HTMLInputElement.popoverTargetElement The **`popoverTargetElement`** property of the {{domxref("HTMLInputElement")}} interface gets and sets the popover element to control via an {{htmlelement("input")}} element of `type="button"`. -It is the JavaScript equivalent of the [`popovertarget`](/en-US/docs/Web/HTML/Element/button#popovertarget) HTML attribute. +It is the JavaScript equivalent of the [`popovertarget`](/en-US/docs/Web/HTML/Reference/Elements/button#popovertarget) HTML attribute. Establishing a relationship between a popover and its invoker button using the `popoverTargetElement` property has two additional useful effects: -- The browser creates an implicit [`aria-details`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-details) and [`aria-expanded`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-expanded) relationship between popover and invoker, and places the popover in a logical position in the keyboard focus navigation order when shown. This makes the popover more accessible to keyboard and assistive technology (AT) users (see also [Popover accessibility features](/en-US/docs/Web/API/Popover_API/Using#popover_accessibility_features)). +- The browser creates an implicit [`aria-details`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-details) and [`aria-expanded`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-expanded) relationship between popover and invoker, and places the popover in a logical position in the keyboard focus navigation order when shown. This makes the popover more accessible to keyboard and assistive technology (AT) users (see also [Popover accessibility features](/en-US/docs/Web/API/Popover_API/Using#popover_accessibility_features)). - The browser creates an implicit anchor reference between the two, making it very convenient to position popovers relative to their controls using [CSS anchor positioning](/en-US/docs/Web/CSS/CSS_anchor_positioning). See [Popover anchor positioning](/en-US/docs/Web/API/Popover_API/Using#popover_anchor_positioning) for more details. ## Value @@ -25,7 +25,7 @@ A reference to a popover element in the DOM. ```js function supportsPopover() { - return HTMLElement.prototype.hasOwnProperty("popover"); + return Object.hasOwn(HTMLElement.prototype, "popover"); } const popover = document.getElementById("mypopover"); @@ -44,11 +44,11 @@ if (popoverSupported) { ### Toggle popover action with an auto popover -This example shows the basic use of the popover API, setting a `<div>` element as a popover, and then setting it as the `popoverTargetElement` of an [`<input>`](/en-US/docs/Web/HTML/Element/input/button) of `type="button"`. +This example shows the basic use of the popover API, setting a `<div>` element as a popover, and then setting it as the `popoverTargetElement` of an [`<input>`](/en-US/docs/Web/HTML/Reference/Elements/input/button) of `type="button"`. The `popover` attribute is set to [`"auto"`](/en-US/docs/Web/API/Popover_API/Using#auto_state_and_light_dismiss), so the popover can be closed ("light-dismissed") by clicking outside the popover area. First we define an `<input>` that we will use to display and hide the popover, and a `<div>` that will be the popover. -In this case we don't set the [`popovertargetaction`](/en-US/docs/Web/HTML/Element/button#popovertargetaction) HTML attribute on the `<input>` or the [`popover`](/en-US/docs/Web/HTML/Global_attributes/popover) attribute on the `<div>`, as we will be doing so programmatically. +In this case we don't set the [`popovertargetaction`](/en-US/docs/Web/HTML/Reference/Elements/button#popovertargetaction) HTML attribute on the `<input>` or the [`popover`](/en-US/docs/Web/HTML/Reference/Global_attributes/popover) attribute on the `<div>`, as we will be doing so programmatically. ```html <input id="toggleBtn" type="button" value="Toggle popover" /> @@ -64,7 +64,7 @@ const toggleBtn = document.getElementById("toggleBtn"); // Check for popover API support. function supportsPopover() { - return HTMLElement.prototype.hasOwnProperty("popover"); + return Object.hasOwn(HTMLElement.prototype, "popover"); } ``` @@ -107,5 +107,5 @@ The "auto" popover can also be light dismissed by selecting outside the bounds o ## See also -- [`popover`](/en-US/docs/Web/HTML/Global_attributes/popover) HTML global attribute +- [`popover`](/en-US/docs/Web/HTML/Reference/Global_attributes/popover) HTML global attribute - [Popover API](/en-US/docs/Web/API/Popover_API) diff --git a/files/en-us/web/api/htmlinputelement/readonly/index.md b/files/en-us/web/api/htmlinputelement/readonly/index.md index b9b020e7b275b36..8f7e5f82a8ea35a 100644 --- a/files/en-us/web/api/htmlinputelement/readonly/index.md +++ b/files/en-us/web/api/htmlinputelement/readonly/index.md @@ -8,7 +8,7 @@ browser-compat: api.HTMLInputElement.readOnly {{ APIRef("HTML DOM") }} -The **`readOnly`** property of the {{DOMxRef("HTMLInputElement")}} interface indicates that the user cannot modify the value of the {{htmlelement("input")}}. It reflects the {{htmlelement("input")}} element's [`readonly`](/en-US/docs/Web/HTML/Element/input#readonly) boolean attribute; returning `true` if the attribute is present and `false` when omitted. +The **`readOnly`** property of the {{DOMxRef("HTMLInputElement")}} interface indicates that the user cannot modify the value of the {{htmlelement("input")}}. It reflects the {{htmlelement("input")}} element's [`readonly`](/en-US/docs/Web/HTML/Reference/Elements/input#readonly) boolean attribute; returning `true` if the attribute is present and `false` when omitted. Unlike a form control with a true {{domxref("HTMLInputElement.disabled", "disabled")}} property, a true `readOnly` property value does not prevent the user from clicking or selecting in the control. diff --git a/files/en-us/web/api/htmlinputelement/reportvalidity/index.md b/files/en-us/web/api/htmlinputelement/reportvalidity/index.md index 3fbc24f03fc2ada..ae9f5b7793c32d2 100644 --- a/files/en-us/web/api/htmlinputelement/reportvalidity/index.md +++ b/files/en-us/web/api/htmlinputelement/reportvalidity/index.md @@ -91,17 +91,9 @@ We add a "Fix me" button to the HTML from the previous example. <p> <button type="submit">Submit</button> <button type="button" id="report">reportValidity()</button> + <button type="button" id="fix">Fix issues</button> </p> -</form> -``` - -```html -<button type="button" id="fix">Fix issues</button> -``` - -```html hidden - </p> -<p id="log"></p> + <p id="log"></p> </form> ``` @@ -109,7 +101,7 @@ We add a "Fix me" button to the HTML from the previous example. We expand on the JavaScript from the basic example above, adding a function that used the {{domxref("HTMLInputElement.setCustomValidity()")}} method to provide custom error messages. The `validateAge()` function only sets the error message to an empty string if the input is valid AND the `enableValidation` variable is `true`, with `enableValidation` being `false` until the "fix issues" button has been activated. -```javascript +```js const output = document.querySelector("#log"); const reportButton = document.querySelector("#report"); const ageInput = document.querySelector("#age"); @@ -166,5 +158,5 @@ If you activate the "reportValidity()" button before entering an age, the `repor - {{HTMLElement("input")}} - {{HTMLElement("form")}} - [Learn: Client-side form validation](/en-US/docs/Learn_web_development/Extensions/Forms/Form_validation) -- [Guide: Constraint validation](/en-US/docs/Web/HTML/Constraint_validation) +- [Guide: Constraint validation](/en-US/docs/Web/HTML/Guides/Constraint_validation) - CSS {{cssxref(":valid")}} and {{cssxref(":invalid")}} pseudo-classes diff --git a/files/en-us/web/api/htmlinputelement/required/index.md b/files/en-us/web/api/htmlinputelement/required/index.md index 5be32f7e326a2c7..aeab9b5cf064106 100644 --- a/files/en-us/web/api/htmlinputelement/required/index.md +++ b/files/en-us/web/api/htmlinputelement/required/index.md @@ -8,7 +8,7 @@ browser-compat: api.HTMLInputElement.required {{ APIRef("HTML DOM") }} -The **`required`** property of the {{DOMxRef("HTMLInputElement")}} interface specifies that the user must fill in a value before submitting a form. It reflects the {{htmlelement("input")}} element's [`required`](/en-US/docs/Web/HTML/Element/input#required) attribute. +The **`required`** property of the {{DOMxRef("HTMLInputElement")}} interface specifies that the user must fill in a value before submitting a form. It reflects the {{htmlelement("input")}} element's [`required`](/en-US/docs/Web/HTML/Reference/Elements/input#required) attribute. While the HTML boolean `required` attribute is ignored if the type is `hidden`, `range`, `color`, `submit`, `reset`, `button`, and `image`, the `required` property is `true` for these input types if the attribute is present, `false` otherwise. diff --git a/files/en-us/web/api/htmlinputelement/search_event/index.md b/files/en-us/web/api/htmlinputelement/search_event/index.md index 184ee2756680ec3..6ac4b5c5edb9605 100644 --- a/files/en-us/web/api/htmlinputelement/search_event/index.md +++ b/files/en-us/web/api/htmlinputelement/search_event/index.md @@ -12,7 +12,7 @@ browser-compat: api.HTMLInputElement.search_event The **`search`** event is fired when a search is initiated using an {{HTMLElement("input")}} element of `type="search"`. -There are several ways a search can be initiated, such as by pressing <kbd>Enter</kbd> while the {{HTMLElement("input")}} is focused, or, if the [`incremental`](/en-US/docs/Web/HTML/Element/input#incremental) attribute is present, after a UA-defined timeout elapses since the most recent keystroke (with new keystrokes resetting the timeout so the firing of the event is {{glossary("debounce", "debounced")}}). +There are several ways a search can be initiated, such as by pressing <kbd>Enter</kbd> while the {{HTMLElement("input")}} is focused, or, if the [`incremental`](/en-US/docs/Web/HTML/Reference/Elements/input#incremental) attribute is present, after a UA-defined timeout elapses since the most recent keystroke (with new keystrokes resetting the timeout so the firing of the event is {{glossary("debounce", "debounced")}}). Current UA implementations of `<input type="search">` have an additional control to clear the field. Using this control also fires the `search` event. In that case the `value` of the {{HTMLElement("input")}} element will be the empty string. @@ -22,10 +22,10 @@ This event is not cancelable. Use the event name in methods like {{domxref("EventTarget.addEventListener", "addEventListener()")}}, or set an event handler property. -```js -addEventListener("search", (event) => {}); +```js-nolint +addEventListener("search", (event) => { }) -onsearch = (event) => {}; +onsearch = (event) => { } ``` ## Event type diff --git a/files/en-us/web/api/htmlinputelement/select_event/index.md b/files/en-us/web/api/htmlinputelement/select_event/index.md index 7dd67fe8514e351..d23f7a1551388bb 100644 --- a/files/en-us/web/api/htmlinputelement/select_event/index.md +++ b/files/en-us/web/api/htmlinputelement/select_event/index.md @@ -14,10 +14,10 @@ The **`select`** event fires when some text has been selected. Use the event name in methods like {{domxref("EventTarget.addEventListener", "addEventListener()")}}, or set an event handler property. -```js -addEventListener("select", (event) => {}); +```js-nolint +addEventListener("select", (event) => { }) -onselect = (event) => {}; +onselect = (event) => { } ``` ## Event type diff --git a/files/en-us/web/api/htmlinputelement/selectionchange_event/index.md b/files/en-us/web/api/htmlinputelement/selectionchange_event/index.md index 6cd114f73fd3bd2..9a3b7757e9c9b17 100644 --- a/files/en-us/web/api/htmlinputelement/selectionchange_event/index.md +++ b/files/en-us/web/api/htmlinputelement/selectionchange_event/index.md @@ -3,12 +3,10 @@ title: "HTMLInputElement: selectionchange event" short-title: selectionchange slug: Web/API/HTMLInputElement/selectionchange_event page-type: web-api-event -status: - - experimental browser-compat: api.HTMLInputElement.selectionchange_event --- -{{APIRef}}{{SeeCompatTable}} +{{APIRef}} The **`selectionchange`** event of the [Selection API](/en-US/docs/Web/API/Selection) is fired when the text selection within an {{HTMLElement("input")}} element is changed. This includes both changes in the selected range of characters, or if the caret moves. @@ -23,10 +21,10 @@ It is also possible to add a listener on the `onselectionchange` event handler, Use the event name in methods like {{domxref("EventTarget.addEventListener", "addEventListener()")}}, or set an event handler property. -```js -addEventListener("selectionchange", (event) => {}); +```js-nolint +addEventListener("selectionchange", (event) => { }) -onselectionchange = (event) => {}; +onselectionchange = (event) => { } ``` ## Event type diff --git a/files/en-us/web/api/htmlinputelement/selectiondirection/index.md b/files/en-us/web/api/htmlinputelement/selectiondirection/index.md index 596c3d954663136..d25920aaf08625a 100644 --- a/files/en-us/web/api/htmlinputelement/selectiondirection/index.md +++ b/files/en-us/web/api/htmlinputelement/selectiondirection/index.md @@ -42,8 +42,7 @@ A string. It can have one of the following values: ```js const textSelectionDirection = document.querySelector("#selectionDirection"); const pConsole = document.querySelector("#direction"); -pConsole.textContent = - "Selection direction : " + textSelectionDirection.selectionDirection; +pConsole.textContent = `Selection direction : ${textSelectionDirection.selectionDirection}`; ``` ### Result diff --git a/files/en-us/web/api/htmlinputelement/selectionend/index.md b/files/en-us/web/api/htmlinputelement/selectionend/index.md index f38e2400c51b845..31b7a673939427e 100644 --- a/files/en-us/web/api/htmlinputelement/selectionend/index.md +++ b/files/en-us/web/api/htmlinputelement/selectionend/index.md @@ -44,7 +44,7 @@ A non-negative number. const colorEnd = document.getElementById("color"); const text = document.querySelector("#pin"); const pinBtn = document.querySelector("#pin-btn"); -const validPinChecker = /[^\d{3}-\d{2}-\d{3}]/g; +const validPinChecker = /^\d{3}-\d{2}-\d{3}/g; const selectionEnd = text.value.length; const selectedText = text.value.substring(text.selectionStart, selectionEnd); diff --git a/files/en-us/web/api/htmlinputelement/setcustomvalidity/index.md b/files/en-us/web/api/htmlinputelement/setcustomvalidity/index.md index 400df90b5268310..772e14bcafdbeda 100644 --- a/files/en-us/web/api/htmlinputelement/setcustomvalidity/index.md +++ b/files/en-us/web/api/htmlinputelement/setcustomvalidity/index.md @@ -72,5 +72,5 @@ submitted. ## See also - [Learn: Client-side form validation](/en-US/docs/Learn_web_development/Extensions/Forms/Form_validation) -- [Guide: Constraint validation](/en-US/docs/Web/HTML/Constraint_validation) +- [Guide: Constraint validation](/en-US/docs/Web/HTML/Guides/Constraint_validation) - {{domxref('ValidityState')}} diff --git a/files/en-us/web/api/htmlinputelement/setselectionrange/index.md b/files/en-us/web/api/htmlinputelement/setselectionrange/index.md index bf546270a0cc913..3c1efb81a8655c1 100644 --- a/files/en-us/web/api/htmlinputelement/setselectionrange/index.md +++ b/files/en-us/web/api/htmlinputelement/setselectionrange/index.md @@ -16,7 +16,7 @@ Optionally, you can specify the direction in which selection should be considere This method updates the {{domxref("HTMLInputElement.selectionStart")}}, {{domxref("HTMLInputElement.selectionEnd")}}, and {{domxref("HTMLInputElement.selectionDirection")}} properties in one call. -The element must be of one of the following input types: [`password`](/en-US/docs/Web/HTML/Element/input/password), [`search`](/en-US/docs/Web/HTML/Element/input/search), [`tel`](/en-US/docs/Web/HTML/Element/input/tel), [`text`](/en-US/docs/Web/HTML/Element/input/text), or [`url`](/en-US/docs/Web/HTML/Element/input/url). Otherwise the browser throws an `InvalidStateError` exception. +The element must be of one of the following input types: [`password`](/en-US/docs/Web/HTML/Reference/Elements/input/password), [`search`](/en-US/docs/Web/HTML/Reference/Elements/input/search), [`tel`](/en-US/docs/Web/HTML/Reference/Elements/input/tel), [`text`](/en-US/docs/Web/HTML/Reference/Elements/input/text), or [`url`](/en-US/docs/Web/HTML/Reference/Elements/input/url). Otherwise the browser throws an `InvalidStateError` exception. If you wish to select **all** text of an input element, you can use the [HTMLInputElement.select()](/en-US/docs/Web/API/HTMLInputElement/select) method instead. @@ -54,7 +54,7 @@ None ({{jsxref("undefined")}}). ### Exceptions - `InvalidStateError` {{domxref("DOMException")}} - - : Thrown if the element is not one of the following input types: [`password`](/en-US/docs/Web/HTML/Element/input/password), [`search`](/en-US/docs/Web/HTML/Element/input/search), [`tel`](/en-US/docs/Web/HTML/Element/input/tel), [`text`](/en-US/docs/Web/HTML/Element/input/text), or [`url`](/en-US/docs/Web/HTML/Element/input/url). + - : Thrown if the element is not one of the following input types: [`password`](/en-US/docs/Web/HTML/Reference/Elements/input/password), [`search`](/en-US/docs/Web/HTML/Reference/Elements/input/search), [`tel`](/en-US/docs/Web/HTML/Reference/Elements/input/tel), [`text`](/en-US/docs/Web/HTML/Reference/Elements/input/text), or [`url`](/en-US/docs/Web/HTML/Reference/Elements/input/url). ## Examples diff --git a/files/en-us/web/api/htmlinputelement/showpicker/index.md b/files/en-us/web/api/htmlinputelement/showpicker/index.md index e6eb87a502a5ac1..e15faf0caa160e2 100644 --- a/files/en-us/web/api/htmlinputelement/showpicker/index.md +++ b/files/en-us/web/api/htmlinputelement/showpicker/index.md @@ -13,7 +13,7 @@ The **`HTMLInputElement.showPicker()`** method displays the browser picker for a This is the same picker that would normally be displayed when the element is selected, but can be triggered from a button press or other user interaction. Commonly browsers implement it for inputs of these types: `"date"`, `"month"`, `"week"`, `"time"`, `"datetime-local"`, `"color"`, or `"file"`. -It can also be prepopulated with items from a {{htmlelement("datalist")}} element or [`autocomplete`](/en-US/docs/Web/HTML/Attributes/autocomplete) attribute. +It can also be prepopulated with items from a {{htmlelement("datalist")}} element or [`autocomplete`](/en-US/docs/Web/HTML/Reference/Attributes/autocomplete) attribute. More generally, this method should ideally display the picker for any input element on the platform that has a picker. @@ -103,7 +103,7 @@ Click the button next to each input type to show its picker. ### showPicker() for a datalist input -`showPicker()` can launch the picker for a list of options defined in a [`<datalist>`](/en-US/docs/Web/HTML/Element/datalist). +`showPicker()` can launch the picker for a list of options defined in a [`<datalist>`](/en-US/docs/Web/HTML/Reference/Elements/datalist). First we define a `<datalist>` in HTML consisting of a number of internet browsers, an input of type `text` that uses it, and a button. @@ -137,7 +137,7 @@ button.addEventListener("click", () => { ### showPicker() for autocomplete -`showPicker()` can launch a picker for an [`autocomplete`](/en-US/docs/Web/HTML/Attributes/autocomplete) input. +`showPicker()` can launch a picker for an [`autocomplete`](/en-US/docs/Web/HTML/Reference/Attributes/autocomplete) input. Here we define an input that takes an autocomplete option of "name". @@ -174,4 +174,4 @@ button.addEventListener("click", () => { - {{ domxref("HTMLInputElement") }} - {{ domxref("HTMLSelectElement.showPicker()") }} - {{htmlelement("datalist")}} -- [`autocomplete`](/en-US/docs/Web/HTML/Attributes/autocomplete) +- [`autocomplete`](/en-US/docs/Web/HTML/Reference/Attributes/autocomplete) diff --git a/files/en-us/web/api/htmlinputelement/size/index.md b/files/en-us/web/api/htmlinputelement/size/index.md index 48ce4aa1f8da0f9..bf5ec7c5e4c57a9 100644 --- a/files/en-us/web/api/htmlinputelement/size/index.md +++ b/files/en-us/web/api/htmlinputelement/size/index.md @@ -8,9 +8,9 @@ browser-compat: api.HTMLInputElement.size {{APIRef("HTML DOM")}} -The **`size`** property of the {{DOMxRef("HTMLInputElement")}} interface defines the number of visible characters displayed. It reflects the {{htmlelement("input")}} element's [`size`](/en-US/docs/Web/HTML/Element/input#size) attribute. +The **`size`** property of the {{DOMxRef("HTMLInputElement")}} interface defines the number of visible characters displayed. It reflects the {{htmlelement("input")}} element's [`size`](/en-US/docs/Web/HTML/Reference/Elements/input#size) attribute. -The `size` property is relevant to the [`text`](/en-US/docs/Web/HTML/Element/input/text), [`search`](/en-US/docs/Web/HTML/Element/input/search), [`tel`](/en-US/docs/Web/HTML/Element/input/tel), [`email`](/en-US/docs/Web/HTML/Element/input/email), [`url`](/en-US/docs/Web/HTML/Element/input/url), and [`password`](/en-US/docs/Web/HTML/Element/input/password) input type only. The value is a non-negative integer greater than zero. If omitted or invalid, the value is `20`. +The `size` property is relevant to the [`text`](/en-US/docs/Web/HTML/Reference/Elements/input/text), [`search`](/en-US/docs/Web/HTML/Reference/Elements/input/search), [`tel`](/en-US/docs/Web/HTML/Reference/Elements/input/tel), [`email`](/en-US/docs/Web/HTML/Reference/Elements/input/email), [`url`](/en-US/docs/Web/HTML/Reference/Elements/input/url), and [`password`](/en-US/docs/Web/HTML/Reference/Elements/input/password) input type only. The value is a non-negative integer greater than zero. If omitted or invalid, the value is `20`. ## Value diff --git a/files/en-us/web/api/htmlinputelement/src/index.md b/files/en-us/web/api/htmlinputelement/src/index.md index c7b31619287ba88..6f603e1ca4b5450 100644 --- a/files/en-us/web/api/htmlinputelement/src/index.md +++ b/files/en-us/web/api/htmlinputelement/src/index.md @@ -8,9 +8,9 @@ browser-compat: api.HTMLInputElement.src {{APIRef("HTML DOM")}} -The **`src`** property of the {{DOMxRef("HTMLInputElement")}} interface specifies the source of an image to display as the graphical submit button. It reflects the {{htmlelement("input")}} element's [`src`](/en-US/docs/Web/HTML/Element/input#src) attribute. +The **`src`** property of the {{DOMxRef("HTMLInputElement")}} interface specifies the source of an image to display as the graphical submit button. It reflects the {{htmlelement("input")}} element's [`src`](/en-US/docs/Web/HTML/Reference/Elements/input#src) attribute. -The `src` property is valid for the [`image`](/en-US/docs/Web/HTML/Element/input/image) type only. +The `src` property is valid for the [`image`](/en-US/docs/Web/HTML/Reference/Elements/input/image) type only. ## Value diff --git a/files/en-us/web/api/htmlinputelement/step/index.md b/files/en-us/web/api/htmlinputelement/step/index.md index 45d78a73266c990..05bac31ee01f6e7 100644 --- a/files/en-us/web/api/htmlinputelement/step/index.md +++ b/files/en-us/web/api/htmlinputelement/step/index.md @@ -8,7 +8,7 @@ browser-compat: api.HTMLInputElement.step {{ApiRef("HTML DOM")}} -The **`step`** property of the {{domxref("HTMLInputElement")}} interface indicates the step by which numeric or date-time {{HTMLElement("input")}} elements can change. It reflects the element's [`step`](/en-US/docs/Web/HTML/Element/input#step) attribute. Valid values include the string `"any"` or a string containing a positive floating point number. If the attribute is not explicitly set, the `step` property is an empty string. +The **`step`** property of the {{domxref("HTMLInputElement")}} interface indicates the step by which numeric or date-time {{HTMLElement("input")}} elements can change. It reflects the element's [`step`](/en-US/docs/Web/HTML/Reference/Elements/input#step) attribute. Valid values include the string `"any"` or a string containing a positive floating point number. If the attribute is not explicitly set, the `step` property is an empty string. ## Value diff --git a/files/en-us/web/api/htmlinputelement/stepdown/index.md b/files/en-us/web/api/htmlinputelement/stepdown/index.md index b0c149e1bcc206a..23f854a1850263f 100644 --- a/files/en-us/web/api/htmlinputelement/stepdown/index.md +++ b/files/en-us/web/api/htmlinputelement/stepdown/index.md @@ -11,14 +11,14 @@ browser-compat: api.HTMLInputElement.stepDown The **`HTMLInputElement.stepDown()`** method decrements the value of a numeric type of {{HTMLElement("input")}} element by the value of the -[`step`](/en-US/docs/Web/HTML/Attributes/step) attribute or up +[`step`](/en-US/docs/Web/HTML/Reference/Attributes/step) attribute or up to `n` multiples of the step attribute if a number is passed as the parameter. The method, when invoked, decrements the -[`value`](/en-US/docs/Web/HTML/Element/input#value) by ([`step`](/en-US/docs/Web/HTML/Element/input#step) \* n), where n +[`value`](/en-US/docs/Web/HTML/Reference/Elements/input#value) by ([`step`](/en-US/docs/Web/HTML/Reference/Elements/input#step) \* n), where n defaults to 1 if not specified, and -[`step`](/en-US/docs/Web/HTML/Attributes/step) defaults to the +[`step`](/en-US/docs/Web/HTML/Reference/Attributes/step) defaults to the default value for `step` if not specified. Valid on all numeric, date, and time input types that support the step attribute, @@ -72,11 +72,11 @@ The method, when invoked, changes the form control's value by the value given in `step` attribute, multiplied by the parameter, within the constraints set within the form control. The default value for the parameter, if not is passed, is 1. The method will not cause the value to go below the -[`min`](/en-US/docs/Web/HTML/Attributes/min) value set or defy the +[`min`](/en-US/docs/Web/HTML/Reference/Attributes/min) value set or defy the constraints set by the -[`step`](/en-US/docs/Web/HTML/Attributes/step) attribute. A +[`step`](/en-US/docs/Web/HTML/Reference/Attributes/step) attribute. A negative value for `n` will increment the value, but will not increment -beyond the [`max`](/en-US/docs/Web/HTML/Attributes/max) value. +beyond the [`max`](/en-US/docs/Web/HTML/Reference/Attributes/max) value. If the value before invoking the `stepDown()` method is invalid, for example, if it doesn't match the constraints set by the `step` attribute, @@ -114,11 +114,11 @@ None ({{jsxref("undefined")}}). - `InvalidStateError` {{domxref("DOMException")}} - : Thrown in one of the following cases: - if the method is not applicable to for the current - [`type`](/en-US/docs/Web/HTML/Element/input#type) value, - - if the element has no [`step`](/en-US/docs/Web/HTML/Element/input#step) value, - - if the [`value`](/en-US/docs/Web/HTML/Element/input#value) cannot be converted to a number, - - if the resulting value is above the [`max`](/en-US/docs/Web/HTML/Element/input#max) or below the - [`min`](/en-US/docs/Web/HTML/Element/input#min). + [`type`](/en-US/docs/Web/HTML/Reference/Elements/input#type) value, + - if the element has no [`step`](/en-US/docs/Web/HTML/Reference/Elements/input#step) value, + - if the [`value`](/en-US/docs/Web/HTML/Reference/Elements/input#value) cannot be converted to a number, + - if the resulting value is above the [`max`](/en-US/docs/Web/HTML/Reference/Elements/input#max) or below the + [`min`](/en-US/docs/Web/HTML/Reference/Elements/input#min). ## Examples @@ -205,6 +205,6 @@ invoke the method? - {{HTMLElement("input")}} - {{domxref("HTMLInputElement")}} - {{domxref("HTMLInputElement.stepUp", "HTMLInputElement.stepUp()")}} -- [`step`](/en-US/docs/Web/HTML/Attributes/step), - [`min`](/en-US/docs/Web/HTML/Attributes/min) and - [`max`](/en-US/docs/Web/HTML/Attributes/max) attributes +- [`step`](/en-US/docs/Web/HTML/Reference/Attributes/step), + [`min`](/en-US/docs/Web/HTML/Reference/Attributes/min) and + [`max`](/en-US/docs/Web/HTML/Reference/Attributes/max) attributes diff --git a/files/en-us/web/api/htmlinputelement/stepup/index.md b/files/en-us/web/api/htmlinputelement/stepup/index.md index 3853dbfca5ce1e6..136b9a461cd2943 100644 --- a/files/en-us/web/api/htmlinputelement/stepup/index.md +++ b/files/en-us/web/api/htmlinputelement/stepup/index.md @@ -10,12 +10,12 @@ browser-compat: api.HTMLInputElement.stepUp The **`HTMLInputElement.stepUp()`** method increments the value of a numeric type of {{HTMLElement("input")}} element by the value of the -[`step`](/en-US/docs/Web/HTML/Attributes/step) attribute, or the +[`step`](/en-US/docs/Web/HTML/Reference/Attributes/step) attribute, or the default `step` value if the step attribute is not explicitly set. The method, -when invoked, increments the [`value`](/en-US/docs/Web/HTML/Element/input#value) by -([`step`](/en-US/docs/Web/HTML/Element/input#step) \* n), where `n` defaults to +when invoked, increments the [`value`](/en-US/docs/Web/HTML/Reference/Elements/input#value) by +([`step`](/en-US/docs/Web/HTML/Reference/Elements/input#step) \* n), where `n` defaults to `1` if not specified, and -[`step`](/en-US/docs/Web/HTML/Attributes/step) defaults to the +[`step`](/en-US/docs/Web/HTML/Reference/Attributes/step) defaults to the default value for `step` if not specified. <table class="no-markdown"> @@ -91,9 +91,9 @@ The method, when invoked, changes the form control's value by the value given in `step` attribute, multiplied by the parameter, within the constraints set on the form control. The default value for the parameter, if no value is passed, is `1`. The method will not cause the value to exceed the -set [`max`](/en-US/docs/Web/HTML/Attributes/max) value, or defy +set [`max`](/en-US/docs/Web/HTML/Reference/Attributes/max) value, or defy the constraints set by the -[`step`](/en-US/docs/Web/HTML/Attributes/step) attribute. +[`step`](/en-US/docs/Web/HTML/Reference/Attributes/step) attribute. If the value before invoking the `stepUp()` method is invalid—for example, if it doesn't match the constraints set by the step attribute—invoking the @@ -207,6 +207,6 @@ invoke the method? - {{HTMLElement("input")}} - {{domxref("HTMLInputElement")}} - {{domxref("HTMLInputElement.stepDown")}} -- [`step`](/en-US/docs/Web/HTML/Attributes/step), - [`min`](/en-US/docs/Web/HTML/Attributes/min) and - [`max`](/en-US/docs/Web/HTML/Attributes/max) attributes +- [`step`](/en-US/docs/Web/HTML/Reference/Attributes/step), + [`min`](/en-US/docs/Web/HTML/Reference/Attributes/min) and + [`max`](/en-US/docs/Web/HTML/Reference/Attributes/max) attributes diff --git a/files/en-us/web/api/htmlinputelement/type/index.md b/files/en-us/web/api/htmlinputelement/type/index.md index 10d054922ef2baf..ac5e7e9738f5fb7 100644 --- a/files/en-us/web/api/htmlinputelement/type/index.md +++ b/files/en-us/web/api/htmlinputelement/type/index.md @@ -10,13 +10,13 @@ browser-compat: api.HTMLInputElement.type The **`type`** property of the {{domxref("HTMLInputElement")}} interface indicates the kind of data allowed in the {{HTMLElement("input")}} element, for example a number, a date, or an email. Browsers will select the appropriate widget and behavior to help users to enter a valid value. -It reflects the [`type`](/en-US/docs/Web/HTML/Element/input#type) attribute of the {{HTMLElement("input")}} element. +It reflects the [`type`](/en-US/docs/Web/HTML/Reference/Elements/input#type) attribute of the {{HTMLElement("input")}} element. ## Value A string representing the type. -Its possible values are listed in the attribute's [input types](/en-US/docs/Web/HTML/Element/input#input_types) section. +Its possible values are listed in the attribute's [input types](/en-US/docs/Web/HTML/Reference/Elements/input#input_types) section. ## Example diff --git a/files/en-us/web/api/htmlinputelement/validationmessage/index.md b/files/en-us/web/api/htmlinputelement/validationmessage/index.md index 03d85646019cd39..74648dd77fab7a2 100644 --- a/files/en-us/web/api/htmlinputelement/validationmessage/index.md +++ b/files/en-us/web/api/htmlinputelement/validationmessage/index.md @@ -43,5 +43,5 @@ const errorMessage = input.validationMessage; - {{domxref("HTMLInputElement.reportValidity()")}} - {{domxref("HTMLInputElement.setCustomValidity()")}} - [Learn: Client-side form validation](/en-US/docs/Learn_web_development/Extensions/Forms/Form_validation) -- [Guide: Constraint validation](/en-US/docs/Web/HTML/Constraint_validation) +- [Guide: Constraint validation](/en-US/docs/Web/HTML/Guides/Constraint_validation) - CSS {{cssxref(":valid")}} and {{cssxref(":invalid")}} pseudo-classes diff --git a/files/en-us/web/api/htmlinputelement/validity/index.md b/files/en-us/web/api/htmlinputelement/validity/index.md index 4183eb4d20e018f..d9cb64175941bf5 100644 --- a/files/en-us/web/api/htmlinputelement/validity/index.md +++ b/files/en-us/web/api/htmlinputelement/validity/index.md @@ -40,4 +40,4 @@ if (!validityState.valid) { - {{HTMLElement("input")}} - {{HTMLElement("form")}} - [Learn: Client-side form validation](/en-US/docs/Learn_web_development/Extensions/Forms/Form_validation) -- [Guide: Constraint validation](/en-US/docs/Web/HTML/Constraint_validation) +- [Guide: Constraint validation](/en-US/docs/Web/HTML/Guides/Constraint_validation) diff --git a/files/en-us/web/api/htmlinputelement/value/index.md b/files/en-us/web/api/htmlinputelement/value/index.md index e21ff82b9473645..d7385003c9cea63 100644 --- a/files/en-us/web/api/htmlinputelement/value/index.md +++ b/files/en-us/web/api/htmlinputelement/value/index.md @@ -14,7 +14,7 @@ This property can also be set directly, for example to set a default value based ## Value -A string containing the value of the {{htmlelement("input")}} element, or the empty string if the input element has no value set. +A string specifying the default value of the {{htmlelement("input")}} element. ## Examples diff --git a/files/en-us/web/api/htmlinputelement/valueasdate/index.md b/files/en-us/web/api/htmlinputelement/valueasdate/index.md index b4de116f4e62b00..06af38a62c5478d 100644 --- a/files/en-us/web/api/htmlinputelement/valueasdate/index.md +++ b/files/en-us/web/api/htmlinputelement/valueasdate/index.md @@ -18,9 +18,9 @@ This property always returns `null` when accessed on an input that isn't date- o A {{jsxref("Date")}} object or `null` if a conversion is impossible. The date returned should always be interpreted as a UTC time—for example, using methods like `getUTCDate()` instead of `getDate()`. If you are not careful, the result may be off by 1—for example, if the user lives in a negative UTC offset (the US, for example), then interpreting the date as a local date will result in the previous day from what the user selected. -The [`month`](/en-US/docs/Web/HTML/Element/input/month), [`date`](/en-US/docs/Web/HTML/Element/input/date), and [`week`](/en-US/docs/Web/HTML/Element/input/week) input types return a UTC date that represents the first instant of the inputted time span—that is, they are always midnight in UTC. For `month`, the date is the first day of the month. For `week`, the date is the Monday of the week. The [`time`](/en-US/docs/Web/HTML/Element/input/time) input type always has the date set to `1970-01-01`. +The [`month`](/en-US/docs/Web/HTML/Reference/Elements/input/month), [`date`](/en-US/docs/Web/HTML/Reference/Elements/input/date), and [`week`](/en-US/docs/Web/HTML/Reference/Elements/input/week) input types return a UTC date that represents the first instant of the inputted time span—that is, they are always midnight in UTC. For `month`, the date is the first day of the month. For `week`, the date is the Monday of the week. The [`time`](/en-US/docs/Web/HTML/Reference/Elements/input/time) input type always has the date set to `1970-01-01`. -The [`datetime-local`](/en-US/docs/Web/HTML/Element/input/datetime-local) input type does not support the `valueAsDate` property, because it represents a date and time in the local time zone (a [wall clock time](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Temporal/PlainDateTime)), but `Date` objects represent an absolute point in time. However, some browsers may provide a non-standard implementation. [WHATWG is working on integrating](https://github.com/whatwg/html/issues/10882) the {{jsxref("Temporal")}} API with the date/time inputs to account for this use case. +The [`datetime-local`](/en-US/docs/Web/HTML/Reference/Elements/input/datetime-local) input type does not support the `valueAsDate` property, because it represents a date and time in the local time zone (a [wall clock time](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Temporal/PlainDateTime)), but `Date` objects represent an absolute point in time. However, some browsers may provide a non-standard implementation. [WHATWG is working on integrating](https://github.com/whatwg/html/issues/10882) the {{jsxref("Temporal")}} API with the date/time inputs to account for this use case. ## Examples diff --git a/files/en-us/web/api/htmlinputelement/webkitdirectory/index.md b/files/en-us/web/api/htmlinputelement/webkitdirectory/index.md index 2bc503c5aff2b38..32e52e92fa4c4ce 100644 --- a/files/en-us/web/api/htmlinputelement/webkitdirectory/index.md +++ b/files/en-us/web/api/htmlinputelement/webkitdirectory/index.md @@ -9,7 +9,7 @@ browser-compat: api.HTMLInputElement.webkitdirectory {{APIRef("File and Directory Entries API")}} The **`HTMLInputElement.webkitdirectory`** is a property -that reflects the [`webkitdirectory`](/en-US/docs/Web/HTML/Element/input/file#webkitdirectory) HTML attribute +that reflects the [`webkitdirectory`](/en-US/docs/Web/HTML/Reference/Elements/input/file#webkitdirectory) HTML attribute and indicates that the {{HTMLElement("input")}} element should let the user select directories instead of files. When a directory is selected, the directory and its entire hierarchy of contents are included in the set of selected items. The selected file system entries can be obtained using the {{domxref("HTMLInputElement.webkitEntries", "webkitEntries")}} property. diff --git a/files/en-us/web/api/htmlinputelement/width/index.md b/files/en-us/web/api/htmlinputelement/width/index.md index 21b62806d92ee34..ea33cbccdac19c7 100644 --- a/files/en-us/web/api/htmlinputelement/width/index.md +++ b/files/en-us/web/api/htmlinputelement/width/index.md @@ -8,9 +8,9 @@ browser-compat: api.HTMLInputElement.width {{APIRef("HTML DOM")}} -The **`width`** property of the {{DOMxRef("HTMLInputElement")}} interface specifies the width of a control. It reflects the {{htmlelement("input")}} element's [`width`](/en-US/docs/Web/HTML/Element/input#width) attribute. +The **`width`** property of the {{DOMxRef("HTMLInputElement")}} interface specifies the width of a control. It reflects the {{htmlelement("input")}} element's [`width`](/en-US/docs/Web/HTML/Reference/Elements/input#width) attribute. -The `width` property is valid for the [`image`](/en-US/docs/Web/HTML/Element/input/image) type only. It defines the preferred horizontal size of the image button, in pixels. The property value is the width of the [content-box](/en-US/docs/Web/CSS/box-edge#content-box) of the rendered button. CSS box model properties impacting the size of the control take precedence. +The `width` property is valid for the [`image`](/en-US/docs/Web/HTML/Reference/Elements/input/image) type only. It defines the preferred horizontal size of the image button, in pixels. The property value is the width of the [content-box](/en-US/docs/Web/CSS/box-edge#content-box) of the rendered button. CSS box model properties impacting the size of the control take precedence. If no `width` is set and no CSS width properties impact the control, the `width` will be the intrinsic width of the image. If the image didn't load, the value will be the maximum intrinsic width of the `alt` text. The `width` will be `0` if the width is not known; if no `width` is set, no CSS dimensions apply, no image loaded, and either the value of the {{DOMxRef("HTMLInputElement.alt", "alt")}} is the empty string or no `src` is set. diff --git a/files/en-us/web/api/htmlinputelement/willvalidate/index.md b/files/en-us/web/api/htmlinputelement/willvalidate/index.md index b2e5b2470d2d582..38d57ae6b708778 100644 --- a/files/en-us/web/api/htmlinputelement/willvalidate/index.md +++ b/files/en-us/web/api/htmlinputelement/willvalidate/index.md @@ -8,7 +8,7 @@ browser-compat: api.HTMLInputElement.willValidate {{APIRef("HTML DOM")}} -The **`willValidate`** read-only property of the {{domxref("HTMLInputElement")}} interface indicates whether the {{htmlelement("input")}} element is a candidate for [constraint validation](/en-US/docs/Web/HTML/Constraint_validation). It is `false` if any conditions bar it from constraint validation, including: +The **`willValidate`** read-only property of the {{domxref("HTMLInputElement")}} interface indicates whether the {{htmlelement("input")}} element is a candidate for [constraint validation](/en-US/docs/Web/HTML/Guides/Constraint_validation). It is `false` if any conditions bar it from constraint validation, including: - Its {{domxref("HTMLInputElement.type", "type")}} is one of `hidden`, `reset` or `button`; - It has a {{HTMLElement("datalist")}} ancestor; @@ -32,4 +32,4 @@ A boolean value. - {{HTMLElement("input")}} - {{HTMLElement("form")}} - [Learn: Client-side form validation](/en-US/docs/Learn_web_development/Extensions/Forms/Form_validation) -- [Guide: Constraint validation](/en-US/docs/Web/HTML/Constraint_validation) +- [Guide: Constraint validation](/en-US/docs/Web/HTML/Guides/Constraint_validation) diff --git a/files/en-us/web/api/htmllabelelement/htmlfor/index.md b/files/en-us/web/api/htmllabelelement/htmlfor/index.md index 9b70db1335459d4..7206eae6a3f5ad7 100644 --- a/files/en-us/web/api/htmllabelelement/htmlfor/index.md +++ b/files/en-us/web/api/htmllabelelement/htmlfor/index.md @@ -9,7 +9,7 @@ browser-compat: api.HTMLLabelElement.htmlFor {{APIRef("HTML DOM")}} The **`HTMLLabelElement.htmlFor`** property reflects the value -of the [`for`](/en-US/docs/Web/HTML/Element/label#for) content property. That means that this +of the [`for`](/en-US/docs/Web/HTML/Reference/Elements/label#for) content property. That means that this script-accessible property is used to set and read the value of the content property `for`, which is the ID of the label's associated control element. diff --git a/files/en-us/web/api/htmllabelelement/index.md b/files/en-us/web/api/htmllabelelement/index.md index a11ab384d563be8..346119c592b950e 100644 --- a/files/en-us/web/api/htmllabelelement/index.md +++ b/files/en-us/web/api/htmllabelelement/index.md @@ -20,7 +20,7 @@ _Inherits properties from its parent, {{domxref("HTMLElement")}}._ - {{domxref("HTMLLabelElement.form")}} {{ReadOnlyInline}} - : A {{domxref("HTMLFormElement")}} object representing the form with which the labeled control is associated, or `null` if there is no associated control, or if that control isn't associated with a form. In other words, this is just a shortcut for `HTMLLabelElement.control.form`. - {{domxref("HTMLLabelElement.htmlFor")}} - - : A string containing the ID of the labeled control. This reflects the [`for`](/en-US/docs/Web/HTML/Element/label#for) attribute. + - : A string containing the ID of the labeled control. This reflects the [`for`](/en-US/docs/Web/HTML/Reference/Elements/label#for) attribute. > [!NOTE] > To programmatically set the `for` attribute, use [`htmlFor`](/en-US/docs/Web/API/HTMLLabelElement/htmlFor). diff --git a/files/en-us/web/api/htmllielement/value/index.md b/files/en-us/web/api/htmllielement/value/index.md index 365e7f7f421c1fd..9f154e9adffb349 100644 --- a/files/en-us/web/api/htmllielement/value/index.md +++ b/files/en-us/web/api/htmllielement/value/index.md @@ -10,7 +10,7 @@ browser-compat: api.HTMLLIElement.value The **`value`** property of the {{domxref("HTMLLIElement")}} interface indicates the ordinal position of the _list element_ inside a given {{HTMLElement("ol")}}. It can be smaller than `0`. If the {{HTMLElement("li")}} element is not a child of an {{HTMLElement("ol")}} element, the property has no meaning. -It reflects the [`value`](/en-US/docs/Web/HTML/Element/li#value) attribute of the corresponding {{htmlelement("li")}} element. If the `<li>` element does not have a `value` content attribute specified, then this property returns `0` by default even when the element may have a default serially-assigned ordinal value when rendered. +It reflects the [`value`](/en-US/docs/Web/HTML/Reference/Elements/li#value) attribute of the corresponding {{htmlelement("li")}} element. If the `<li>` element does not have a `value` content attribute specified, then this property returns `0` by default even when the element may have a default serially-assigned ordinal value when rendered. ## Value diff --git a/files/en-us/web/api/htmllinkelement/as/index.md b/files/en-us/web/api/htmllinkelement/as/index.md index 3daccc94565750f..0ea01cc3cce04b3 100644 --- a/files/en-us/web/api/htmllinkelement/as/index.md +++ b/files/en-us/web/api/htmllinkelement/as/index.md @@ -10,11 +10,11 @@ browser-compat: api.HTMLLinkElement.as The **`as`** property of the {{domxref("HTMLLinkElement")}} interface returns a string representing the type of content to be preloaded by a link element. -The `as` property must have a value for link elements when [`rel="preload"`](/en-US/docs/Web/HTML/Attributes/rel/preload), or the resource will not be fetched. -It may also be applied to link elements where [`rel="modulepreload"`](/en-US/docs/Web/HTML/Attributes/rel/modulepreload), but if omitted, will default to `script`. +The `as` property must have a value for link elements when [`rel="preload"`](/en-US/docs/Web/HTML/Reference/Attributes/rel/preload), or the resource will not be fetched. +It may also be applied to link elements where [`rel="modulepreload"`](/en-US/docs/Web/HTML/Reference/Attributes/rel/modulepreload), but if omitted, will default to `script`. The property should not be set for other types of link elements, such as `rel="prefetch"`. -This property reflects the value of the [`as` attribute](/en-US/docs/Web/HTML/Element/link#as) of the [`<link>`](/en-US/docs/Web/HTML/Element/link) HTML element. +This property reflects the value of the [`as` attribute](/en-US/docs/Web/HTML/Reference/Elements/link#as) of the [`<link>`](/en-US/docs/Web/HTML/Reference/Elements/link) HTML element. ## Value diff --git a/files/en-us/web/api/htmllinkelement/fetchpriority/index.md b/files/en-us/web/api/htmllinkelement/fetchpriority/index.md index d25df2ae44edd00..a35048682d3fb13 100644 --- a/files/en-us/web/api/htmllinkelement/fetchpriority/index.md +++ b/files/en-us/web/api/htmllinkelement/fetchpriority/index.md @@ -9,13 +9,13 @@ browser-compat: api.HTMLLinkElement.fetchPriority {{APIRef("HTML DOM")}} The **`fetchPriority`** property of the {{domxref("HTMLLinkElement")}} interface represents a hint to the browser indicating how it should prioritize fetching a particular resource relative to other resources of the same type. -It reflects the [`fetchpriority`](/en-US/docs/Web/HTML/Element/link#fetchpriority) attribute of the corresponding {{htmlelement("link")}} element. +It reflects the [`fetchpriority`](/en-US/docs/Web/HTML/Reference/Elements/link#fetchpriority) attribute of the corresponding {{htmlelement("link")}} element. The property allows a developer to signal that fetching a particular resource early in the loading process has more or less impact on user experience than a browser can reasonably infer when assigning an internal priority, in particular when preloading resources. This in turn allows the browser to increase or decrease the priority, and potentially load the resource earlier or later than it would otherwise. The property should be used sparingly, as excessive or incorrect prioritization can degrade performance. -The fetch priority can be used to complement [preloading](/en-US/docs/Web/HTML/Attributes/rel/preload), allowing a developer to boost the priority of a resource ahead of less-impactful resources that are by default preloaded with a higher priority. +The fetch priority can be used to complement [preloading](/en-US/docs/Web/HTML/Reference/Attributes/rel/preload), allowing a developer to boost the priority of a resource ahead of less-impactful resources that are by default preloaded with a higher priority. For example, if a particular image significantly contributes to the website's {{glossary("Largest Contentful Paint")}} (LCP) it might be set to be preloaded and with a high fetch priority. Note that both the internal priority of any fetch operation, and the impact of `fetchPriority` on the priority, are entirely browser dependent. diff --git a/files/en-us/web/api/htmllinkelement/href/index.md b/files/en-us/web/api/htmllinkelement/href/index.md index 13f120351cea9ae..4a919daf853ff17 100644 --- a/files/en-us/web/api/htmllinkelement/href/index.md +++ b/files/en-us/web/api/htmllinkelement/href/index.md @@ -13,7 +13,7 @@ The **`href`** property of the {{domxref("HTMLLinkElement")}} interface contains It reflects the `href` attribute of the {{HTMLElement("link")}} element. If the element does not have an `href` attribute, then this property's value is the empty string (`""`). > [!NOTE] -> Every `<link>` element must contain either one or both of the `href` or [`imagesrcset`](/en-US/docs/Web/HTML/Element/link#imagesrcset) attributes. This means, for each valid `<link>`, either this property or {{domxref("HTMLLinkElement.imageSrcset", "imageSrcset")}} will not be empty. +> Every `<link>` element must contain either one or both of the `href` or [`imagesrcset`](/en-US/docs/Web/HTML/Reference/Elements/link#imagesrcset) attributes. This means, for each valid `<link>`, either this property or {{domxref("HTMLLinkElement.imageSrcset", "imageSrcset")}} will not be empty. ## Value diff --git a/files/en-us/web/api/htmllinkelement/hreflang/index.md b/files/en-us/web/api/htmllinkelement/hreflang/index.md index 2f82b3236d55aa3..c134b6a701aa019 100644 --- a/files/en-us/web/api/htmllinkelement/hreflang/index.md +++ b/files/en-us/web/api/htmllinkelement/hreflang/index.md @@ -31,7 +31,7 @@ A string that contains a language tag, or the empty string (`""`) if there is no ```css .tag { margin-left: 20px; - font: bold; + font-weight: bold; font-size: 24px; } ``` diff --git a/files/en-us/web/api/htmllinkelement/imagesizes/index.md b/files/en-us/web/api/htmllinkelement/imagesizes/index.md new file mode 100644 index 000000000000000..d1ac7dd94560f35 --- /dev/null +++ b/files/en-us/web/api/htmllinkelement/imagesizes/index.md @@ -0,0 +1,79 @@ +--- +title: "HTMLLinkElement: imageSizes property" +short-title: imageSizes +slug: Web/API/HTMLLinkElement/imageSizes +page-type: web-api-instance-property +browser-compat: api.HTMLLinkElement.imageSizes +--- + +{{APIRef("HTML DOM")}} + +The **`imageSizes`** property of the {{domxref("HTMLLinkElement")}} interface indicates the size and conditions for the preloaded images defined by the {{domxref("HTMLLinkElement.imageSrcset", "imageSrcset")}} property. It reflects the value of the {{htmlelement("link")}} element's [`imagesizes`](/en-US/docs/Web/HTML/Reference/Elements/link#imagesizes) attribute. This property can retrieve or set the `imagesizes` attribute value. + +The `<link>` element's `imagesizes` attribute is the same as the {{htmlelement("img")}} element's `sizes` attribute: a comma-separated **source size** list. Each source size includes a [media condition](/en-US/docs/Web/CSS/CSS_media_queries), the size of the image as a {{cssxref("length")}}, or the keyword `auto`, which must come first. For more information about the syntax of the `sizes` attribute, see [`<img>`](/en-US/docs/Web/HTML/Reference/Elements/img#sizes). + +The `imagesrcset` and `imagesizes` attributes are only relevant on `<link>` elements that have both a `rel` attribute set to `preload` and the `as` attribute set to `image`. + +## Value + +A string composed of comma-separated source sizes, or the empty string `""` if unspecified. + +## Examples + +Given the following `<link>` element: + +```html +<link + rel="preload" + as="image" + imagesrcset="narrow.png, medium.png 600w, wide.png 1200w" + imagesizes="(max-width: 400px) 200px, (width < 600px) 75vw, 50vw" /> +``` + +```html hidden +<pre id="log"></pre> +``` + +```css hidden +#log { + padding: 0 0.25rem; + font-size: 1.2em; + line-height: 1.4; +} +``` + +```js hidden +const logElement = document.querySelector("#log"); +function log(text) { + logElement.innerText = `${logElement.innerText}${text}\n`; + logElement.scrollTop = logElement.scrollHeight; +} +``` + +…we can retrieve and update the `imagesizes` attribute value with the `imageSizes` property: + +```js +const link = document.querySelector("link"); +log(`Original: ${link.imageSizes}`); + +// Change the value +link.imageSizes = "50vw"; +log(`Updated: ${link.imageSizes}`); +``` + +{{EmbedLiveSample('Examples',"","80")}} + +## Specifications + +{{Specifications}} + +## Browser compatibility + +{{Compat}} + +## See also + +- {{domxref("HTMLLinkElement.imageSrcset")}} +- {{domxref("HTMLImageElement.sizes")}} +- [Media queries](/en-US/docs/Web/CSS/CSS_media_queries) +- [Using the `srcset` and `sizes` attributes](/en-US/docs/Web/HTML/Reference/Elements/img#using_the_srcset_and_sizes_attributes) diff --git a/files/en-us/web/api/htmllinkelement/imagesrcset/index.md b/files/en-us/web/api/htmllinkelement/imagesrcset/index.md new file mode 100644 index 000000000000000..49038112749f89b --- /dev/null +++ b/files/en-us/web/api/htmllinkelement/imagesrcset/index.md @@ -0,0 +1,85 @@ +--- +title: "HTMLLinkElement: imageSrcset property" +short-title: imageSrcset +slug: Web/API/HTMLLinkElement/imageSrcset +page-type: web-api-instance-property +browser-compat: api.HTMLLinkElement.imageSrcset +--- + +{{APIRef("HTML DOM")}} + +The **`imageSrcset`** property of the {{domxref("HTMLLinkElement")}} interface is a string which identifies one or more comma-separated **image candidate strings**. This property reflects the value of the {{htmlelement("link")}} element's [`imagesrcset`](/en-US/docs/Web/HTML/Reference/Elements/link#imagesrcset) attribute. This property can retrieved or set the `imagesrcset` attribute value. + +Each image candidate string contains an image URL and an optional width and/or pixel density descriptor indicating the conditions under which that candidate image should be used. + +```plain +"images/team-photo.jpg, images/team-photo-retina.jpg 2x, images/team-photo-large.jpg 1400w" +``` + +For HTML {{htmlelement("link")}} elements with [`rel="preload"`](/en-US/docs/Web/HTML/Reference/Attributes/rel/preload) and [`as="image"`](/en-US/docs/Web/HTML/Reference/Elements/link#as) set, the `imagesrcset` attribute has similar syntax and semantics as the {{htmlelement("img")}} element's [`srcset`](/en-US/docs/Web/HTML/Reference/Elements/img#srcset) attribute, which indicates to preload the appropriate resource used by an `<img>` element with corresponding values for its `srcset` and `sizes` attributes. + +If the `imageSrcset` property includes width descriptors, the {{domxref("HTMLLinkElement.imageSizes", "imageSizes")}} property must be non-null, or the `imageSrcset` value will be ignored. + +## Value + +A string composed of a comma-separated list of one or more image candidate strings, or the empty string `""` if unspecified.. + +## Examples + +Given the following `<link>` element: + +```html +<link + rel="preload" + as="image" + imagesizes="50vw" + imagesrcset="bg-narrow.png, bg-wide.png 800w" /> +``` + +```html hidden +<pre id="log"></pre> +``` + +```css hidden +#log { + padding: 0 0.25rem; + font-size: 1.2em; + line-height: 1.4; +} +``` + +```js hidden +const logElement = document.querySelector("#log"); +function log(text) { + logElement.innerText = `${logElement.innerText}${text}\n`; + logElement.scrollTop = logElement.scrollHeight; +} +``` + +…we can access the `imagesrcset` attribute value, and update it, using the `imageSrcset` property: + +```js +const link = document.querySelector("link"); +log(`Original: ${link.imageSrcset}`); + +// add an image candidate string +link.imageSrcset += ", bg-huge.png 1200w"; +log(`Updated: ${link.imageSrcset}`); +``` + +{{EmbedLiveSample('Examples',"","80")}} + +## Specifications + +{{Specifications}} + +## Browser compatibility + +{{Compat}} + +## See also + +- {{domxref("HTMLLinkElement.imageSizes")}} +- {{domxref("HTMLImageElement.srcset")}} +- [Speculative loading](/en-US/docs/Web/Performance/Guides/Speculative_loading#link_relpreload) +- [Responsive images](/en-US/docs/Web/HTML/Guides/Responsive_images) diff --git a/files/en-us/web/api/htmllinkelement/index.md b/files/en-us/web/api/htmllinkelement/index.md index 103bdf55668e5bc..9b7afc3f09cabb1 100644 --- a/files/en-us/web/api/htmllinkelement/index.md +++ b/files/en-us/web/api/htmllinkelement/index.md @@ -7,7 +7,7 @@ browser-compat: api.HTMLLinkElement {{ APIRef("HTML DOM") }} -The **`HTMLLinkElement`** interface represents reference information for external resources and the relationship of those resources to a document and vice versa (corresponds to [`<link>`](/en-US/docs/Web/HTML/Element/link) element; not to be confused with [`<a>`](/en-US/docs/Web/HTML/Element/a), which is represented by [`HTMLAnchorElement`](/en-US/docs/Web/API/HTMLAnchorElement)). This object inherits all of the properties and methods of the {{domxref("HTMLElement")}} interface. +The **`HTMLLinkElement`** interface represents reference information for external resources and the relationship of those resources to a document and vice versa (corresponds to [`<link>`](/en-US/docs/Web/HTML/Reference/Elements/link) element; not to be confused with [`<a>`](/en-US/docs/Web/HTML/Reference/Elements/a), which is represented by [`HTMLAnchorElement`](/en-US/docs/Web/API/HTMLAnchorElement)). This object inherits all of the properties and methods of the {{domxref("HTMLElement")}} interface. {{InheritanceDiagram}} @@ -16,11 +16,11 @@ The **`HTMLLinkElement`** interface represents reference information for externa _Inherits properties from its parent, {{domxref("HTMLElement")}}._ - {{domxref("HTMLLinkElement.as")}} - - : A string representing the type of content being loaded by the HTML link when [`rel="preload"`](/en-US/docs/Web/HTML/Attributes/rel/preload) or [`rel="modulepreload"`](/en-US/docs/Web/HTML/Attributes/rel/modulepreload). + - : A string representing the type of content being loaded by the HTML link when [`rel="preload"`](/en-US/docs/Web/HTML/Reference/Attributes/rel/preload) or [`rel="modulepreload"`](/en-US/docs/Web/HTML/Reference/Attributes/rel/modulepreload). - {{domxref("HTMLLinkElement.blocking")}} - : A string indicating that certain operations should be blocked on the fetching of an external resource. It reflects the `blocking` attribute of the {{HTMLElement("link")}} element. - {{domxref("HTMLLinkElement.crossOrigin")}} - - : A string that corresponds to the CORS setting for this link element. See [CORS settings attributes](/en-US/docs/Web/HTML/Attributes/crossorigin) for details. + - : A string that corresponds to the CORS setting for this link element. See [CORS settings attributes](/en-US/docs/Web/HTML/Reference/Attributes/crossorigin) for details. - {{domxref("HTMLLinkElement.disabled")}} - : A boolean value which represents whether the link is disabled; currently only used with style sheet links. - {{domxref("HTMLLinkElement.fetchPriority")}} @@ -29,18 +29,22 @@ _Inherits properties from its parent, {{domxref("HTMLElement")}}._ - : A string representing the URI for the target resource. - {{domxref("HTMLLinkElement.hreflang")}} - : A string representing the language code for the linked resource. +- {{domxref("HTMLLinkElement.imageSizes")}} + - : A string reflecting the [`imagesizes`](/en-US/docs/Web/HTML/Reference/Elements/link#imagesizes) HTML attribute; a list of comma-separated image conditions and sizes. +- {{domxref("HTMLLinkElement.imageSrcset")}} + - : A string reflecting the [`imagesrcset`](/en-US/docs/Web/HTML/Reference/Elements/link#imagesrcset) HTML attribute; a comma-separated list of image candidate strings. - {{domxref("HTMLLinkElement.integrity")}} - : A string that contains inline metadata that a browser can use to verify that a fetched resource has been delivered without unexpected manipulation. It reflects the `integrity` attribute of the {{HTMLElement("link")}} element. - {{domxref("HTMLLinkElement.media")}} - : A string representing a list of one or more media formats to which the resource applies. It reflects the `media` attribute of the {{HTMLElement("link")}} element. - {{domxref("HTMLLinkElement.referrerPolicy")}} - - : A string that reflects the [`referrerpolicy`](/en-US/docs/Web/HTML/Element/link#referrerpolicy) HTML attribute indicating which referrer to use. + - : A string that reflects the [`referrerpolicy`](/en-US/docs/Web/HTML/Reference/Elements/link#referrerpolicy) HTML attribute indicating which referrer to use. - {{domxref("HTMLLinkElement.rel")}} - : A string representing the forward relationship of the linked resource from the document to the resource. - {{domxref("HTMLLinkElement.relList")}} {{ReadOnlyInline}} - - : A {{domxref("DOMTokenList")}} that reflects the [`rel`](/en-US/docs/Web/HTML/Element/link#rel) HTML attribute, as a list of tokens. + - : A {{domxref("DOMTokenList")}} that reflects the [`rel`](/en-US/docs/Web/HTML/Reference/Elements/link#rel) HTML attribute, as a list of tokens. - {{domxref("HTMLLinkElement.sizes")}} {{ReadOnlyInline}} - - : A {{domxref("DOMTokenList")}} that reflects the [`sizes`](/en-US/docs/Web/HTML/Element/link#sizes) HTML attribute, as a list of tokens. + - : A {{domxref("DOMTokenList")}} that reflects the [`sizes`](/en-US/docs/Web/HTML/Reference/Elements/link#sizes) HTML attribute, as a list of tokens. - {{domxref("HTMLLinkElement.sheet")}} {{ReadOnlyInline}} - : Returns the {{domxref("StyleSheet")}} object associated with the given element, or `null` if there is none. - {{domxref("HTMLLinkElement.type")}} diff --git a/files/en-us/web/api/htmllinkelement/referrerpolicy/index.md b/files/en-us/web/api/htmllinkelement/referrerpolicy/index.md index 6c8186ff4978e93..5c2c58bddd2180a 100644 --- a/files/en-us/web/api/htmllinkelement/referrerpolicy/index.md +++ b/files/en-us/web/api/htmllinkelement/referrerpolicy/index.md @@ -9,7 +9,7 @@ browser-compat: api.HTMLLinkElement.referrerPolicy {{APIRef("HTML DOM")}} The **`referrerPolicy`** property of the {{domxref("HTMLLinkElement")}} interface -reflects the HTML [`referrerpolicy`](/en-US/docs/Web/HTML/Element/link#referrerpolicy) attribute of the +reflects the HTML [`referrerpolicy`](/en-US/docs/Web/HTML/Reference/Elements/link#referrerpolicy) attribute of the {{HTMLElement("link")}} element defining which referrer is sent when fetching the resource. @@ -25,7 +25,7 @@ A string; one of the following: - `no-referrer-when-downgrade` - : The URL is sent as a referrer when the protocol security level stays the same (e.g.HTTP→HTTP, - HTTPS→HTTPS), but isn't sent to a less secure destination (e.g. HTTPS→HTTP). + HTTPS→HTTPS), but isn't sent to a less secure destination (e.g., HTTPS→HTTP). - `origin` - : Only send the origin of the document as the referrer in all cases. The document `https://example.com/page.html` will send the referrer @@ -38,12 +38,12 @@ A string; one of the following: cross-origin requests will contain no referrer information. - `strict-origin` - : Only send the origin of the document as the referrer when the protocol security - level stays the same (e.g. HTTPS→HTTPS), but don't send it to a less secure - destination (e.g. HTTPS→HTTP). + level stays the same (e.g., HTTPS→HTTPS), but don't send it to a less secure + destination (e.g., HTTPS→HTTP). - `strict-origin-when-cross-origin` (default) - : This is the user agent's default behavior if no policy is specified. Send a full URL when performing a same-origin request, only send the origin when the - protocol security level stays the same (e.g. HTTPS→HTTPS), and send no header to a - less secure destination (e.g. HTTPS→HTTP). + protocol security level stays the same (e.g., HTTPS→HTTPS), and send no header to a + less secure destination (e.g., HTTPS→HTTP). - `unsafe-url` - : Send a full URL when performing a same-origin or cross-origin request. This policy will leak origins and paths from TLS-protected resources to insecure origins. diff --git a/files/en-us/web/api/htmllinkelement/rel/index.md b/files/en-us/web/api/htmllinkelement/rel/index.md index e6a2cc1cf7249d3..a9f986f0e35af0a 100644 --- a/files/en-us/web/api/htmllinkelement/rel/index.md +++ b/files/en-us/web/api/htmllinkelement/rel/index.md @@ -8,10 +8,10 @@ browser-compat: api.HTMLLinkElement.rel {{APIRef("HTML DOM")}} -The **`rel`** property of the {{domxref("HTMLLinkElement")}} interface reflects the [`rel`](/en-US/docs/Web/HTML/Attributes/rel) attribute. It is a string containing a space-separated list of link types indicating the relationship between the resource represented by the {{HTMLElement("link")}} element and the current document. +The **`rel`** property of the {{domxref("HTMLLinkElement")}} interface reflects the [`rel`](/en-US/docs/Web/HTML/Reference/Attributes/rel) attribute. It is a string containing a space-separated list of link types indicating the relationship between the resource represented by the {{HTMLElement("link")}} element and the current document. The most common use of this attribute is to specify a link to an external style sheet: -the property is set to `stylesheet`, and the [`href`](/en-US/docs/Web/HTML/Element/link#href) +the property is set to `stylesheet`, and the [`href`](/en-US/docs/Web/HTML/Reference/Elements/link#href) attribute is set to the URL of an external style sheet to format the page. ## Value diff --git a/files/en-us/web/api/htmllinkelement/rellist/index.md b/files/en-us/web/api/htmllinkelement/rellist/index.md index 9204808e7409e89..285682601ee3595 100644 --- a/files/en-us/web/api/htmllinkelement/rellist/index.md +++ b/files/en-us/web/api/htmllinkelement/rellist/index.md @@ -8,7 +8,7 @@ browser-compat: api.HTMLLinkElement.relList {{APIRef("HTML DOM")}} -The **`relList`** read-only property of the {{domxref("HTMLLinkElement")}} interface reflects the [`rel`](/en-US/docs/Web/HTML/Attributes/rel) attribute. It is a live {{domxref("DOMTokenList")}} containing the set of link types indicating the relationship between the resource represented by the {{HTMLElement("link")}} element and the current document. +The **`relList`** read-only property of the {{domxref("HTMLLinkElement")}} interface reflects the [`rel`](/en-US/docs/Web/HTML/Reference/Attributes/rel) attribute. It is a live {{domxref("DOMTokenList")}} containing the set of link types indicating the relationship between the resource represented by the {{HTMLElement("link")}} element and the current document. The property itself is read-only, meaning you can not substitute the {{domxref("DOMTokenList")}} by another one, but the content of the returned list can be diff --git a/files/en-us/web/api/htmllinkelement/sizes/index.md b/files/en-us/web/api/htmllinkelement/sizes/index.md index a93bde390781060..beece51c7dbf7ad 100644 --- a/files/en-us/web/api/htmllinkelement/sizes/index.md +++ b/files/en-us/web/api/htmllinkelement/sizes/index.md @@ -8,7 +8,7 @@ browser-compat: api.HTMLLinkElement.sizes {{APIRef("HTML DOM")}} -The **`sizes`** read-only property of the {{domxref("HTMLLinkElement")}} interfaces defines the sizes of the icons for visual media contained in the resource. It reflects the {{HTMLElement("link")}} element's [`sizes`](/en-US/docs/Web/HTML/Element/link#sizes) attribute, which takes a list of space-separated sizes, each in the format `<width in pixels>x<height in pixels>`, or the keyword `any`. +The **`sizes`** read-only property of the {{domxref("HTMLLinkElement")}} interfaces defines the sizes of the icons for visual media contained in the resource. It reflects the {{HTMLElement("link")}} element's [`sizes`](/en-US/docs/Web/HTML/Reference/Elements/link#sizes) attribute, which takes a list of space-separated sizes, each in the format `<width in pixels>x<height in pixels>`, or the keyword `any`. It is only relevant if the {{domxref("HTMLLinkElement.rel", "rel")}} is `icon` or a non-standard type like `apple-touch-icon`. @@ -52,4 +52,4 @@ console.log(link.sizes[1]); // output: '114x114' - {{domxref("HTMLLinkElement.type")}} - {{domxref("HTMLLinkElement.href")}} - {{HTMLElement("link")}} -- [`rel`](/en-US/docs/Web/HTML/Attributes/rel) attribute +- [`rel`](/en-US/docs/Web/HTML/Reference/Attributes/rel) attribute diff --git a/files/en-us/web/api/htmlmediaelement/abort_event/index.md b/files/en-us/web/api/htmlmediaelement/abort_event/index.md index d76edf1680b875a..3a17d955767323f 100644 --- a/files/en-us/web/api/htmlmediaelement/abort_event/index.md +++ b/files/en-us/web/api/htmlmediaelement/abort_event/index.md @@ -16,10 +16,10 @@ This event is not cancelable and does not bubble. Use the event name in methods like {{domxref("EventTarget.addEventListener", "addEventListener()")}}, or set an event handler property. -```js -addEventListener("abort", (event) => {}); +```js-nolint +addEventListener("abort", (event) => { }) -onabort = (event) => {}; +onabort = (event) => { } ``` ## Event type diff --git a/files/en-us/web/api/htmlmediaelement/audiotracks/index.md b/files/en-us/web/api/htmlmediaelement/audiotracks/index.md index dc8edaa1d38b2a3..eb7ea094d76052b 100644 --- a/files/en-us/web/api/htmlmediaelement/audiotracks/index.md +++ b/files/en-us/web/api/htmlmediaelement/audiotracks/index.md @@ -50,8 +50,8 @@ The JavaScript code handles muting the video element's audio tracks. ```js const video = document.getElementById("video"); -for (let i = 0; i < video.audioTracks.length; i += 1) { - video.audioTracks[i].enabled = false; +for (const track of video.audioTracks) { + track.enabled = false; } ``` diff --git a/files/en-us/web/api/htmlmediaelement/autoplay/index.md b/files/en-us/web/api/htmlmediaelement/autoplay/index.md index 39b3e1d6101ee82..b34f2375325fad8 100644 --- a/files/en-us/web/api/htmlmediaelement/autoplay/index.md +++ b/files/en-us/web/api/htmlmediaelement/autoplay/index.md @@ -9,7 +9,7 @@ browser-compat: api.HTMLMediaElement.autoplay {{APIRef("HTML DOM")}} The **`HTMLMediaElement.autoplay`** -property reflects the [`autoplay`](/en-US/docs/Web/HTML/Element/video#autoplay) HTML attribute, indicating +property reflects the [`autoplay`](/en-US/docs/Web/HTML/Reference/Elements/video#autoplay) HTML attribute, indicating whether playback should automatically begin as soon as enough media is available to do so without interruption. diff --git a/files/en-us/web/api/htmlmediaelement/canplay_event/index.md b/files/en-us/web/api/htmlmediaelement/canplay_event/index.md index 0cb5cd1edc4530a..27e0e946d9f927c 100644 --- a/files/en-us/web/api/htmlmediaelement/canplay_event/index.md +++ b/files/en-us/web/api/htmlmediaelement/canplay_event/index.md @@ -16,10 +16,10 @@ This event is not cancelable and does not bubble. Use the event name in methods like {{domxref("EventTarget.addEventListener", "addEventListener()")}}, or set an event handler property. -```js -addEventListener("canplay", (event) => {}); +```js-nolint +addEventListener("canplay", (event) => { }) -oncanplay = (event) => {}; +oncanplay = (event) => { } ``` ## Event type diff --git a/files/en-us/web/api/htmlmediaelement/canplaythrough_event/index.md b/files/en-us/web/api/htmlmediaelement/canplaythrough_event/index.md index 9aca2a4e35f45e4..d45be832bb0ac2f 100644 --- a/files/en-us/web/api/htmlmediaelement/canplaythrough_event/index.md +++ b/files/en-us/web/api/htmlmediaelement/canplaythrough_event/index.md @@ -16,10 +16,10 @@ This event is not cancelable and does not bubble. Use the event name in methods like {{domxref("EventTarget.addEventListener", "addEventListener()")}}, or set an event handler property. -```js -addEventListener("canplaythrough", (event) => {}); +```js-nolint +addEventListener("canplaythrough", (event) => { }) -oncanplaythrough = (event) => {}; +oncanplaythrough = (event) => { } ``` ## Event type diff --git a/files/en-us/web/api/htmlmediaelement/canplaytype/index.md b/files/en-us/web/api/htmlmediaelement/canplaytype/index.md index 53a77252175d445..87aa2524770098e 100644 --- a/files/en-us/web/api/htmlmediaelement/canplaytype/index.md +++ b/files/en-us/web/api/htmlmediaelement/canplaytype/index.md @@ -8,7 +8,7 @@ browser-compat: api.HTMLMediaElement.canPlayType {{APIRef("HTML DOM")}} -The {{domxref("HTMLMediaElement")}} method **`canPlayType()`** reports how likely it is that the current browser will be able to play media of a given [MIME type](/en-US/docs/Web/HTTP/MIME_types). +The {{domxref("HTMLMediaElement")}} method **`canPlayType()`** reports how likely it is that the current browser will be able to play media of a given [MIME type](/en-US/docs/Web/HTTP/Guides/MIME_types). ## Syntax @@ -19,7 +19,7 @@ canPlayType(type) ### Parameters - `type` - - : A string specifying the [MIME type](/en-US/docs/Web/HTTP/MIME_types) of the media and (optionally) a [`codecs` parameter](/en-US/docs/Web/Media/Guides/Formats/codecs_parameter) containing a comma-separated list of the supported codecs. + - : A string specifying the [MIME type](/en-US/docs/Web/HTTP/Guides/MIME_types) of the media and (optionally) a [`codecs` parameter](/en-US/docs/Web/Media/Guides/Formats/codecs_parameter) containing a comma-separated list of the supported codecs. ### Return value diff --git a/files/en-us/web/api/htmlmediaelement/controls/index.md b/files/en-us/web/api/htmlmediaelement/controls/index.md index 8c4c0edbffe1361..fdf5e1d76c643d0 100644 --- a/files/en-us/web/api/htmlmediaelement/controls/index.md +++ b/files/en-us/web/api/htmlmediaelement/controls/index.md @@ -9,7 +9,7 @@ browser-compat: api.HTMLMediaElement.controls {{APIRef("HTML DOM")}} The **`HTMLMediaElement.controls`** property reflects the -[`controls`](/en-US/docs/Web/HTML/Element/video#controls) HTML attribute, which controls whether user +[`controls`](/en-US/docs/Web/HTML/Reference/Elements/video#controls) HTML attribute, which controls whether user interface controls for playing the media item will be displayed. ## Value diff --git a/files/en-us/web/api/htmlmediaelement/crossorigin/index.md b/files/en-us/web/api/htmlmediaelement/crossorigin/index.md index 091b30d5fb64696..d3f33b9a5d4defd 100644 --- a/files/en-us/web/api/htmlmediaelement/crossorigin/index.md +++ b/files/en-us/web/api/htmlmediaelement/crossorigin/index.md @@ -8,7 +8,7 @@ browser-compat: api.HTMLMediaElement.crossOrigin {{APIRef("HTML DOM")}} -The **`HTMLMediaElement.crossOrigin`** property is the CORS setting for this media element. See [CORS settings attributes](/en-US/docs/Web/HTML/Attributes/crossorigin) for details. +The **`HTMLMediaElement.crossOrigin`** property is the CORS setting for this media element. See [CORS settings attributes](/en-US/docs/Web/HTML/Reference/Attributes/crossorigin) for details. ## Value diff --git a/files/en-us/web/api/htmlmediaelement/defaultmuted/index.md b/files/en-us/web/api/htmlmediaelement/defaultmuted/index.md index 0c967c520cc27fe..7c2d5dacb91e93d 100644 --- a/files/en-us/web/api/htmlmediaelement/defaultmuted/index.md +++ b/files/en-us/web/api/htmlmediaelement/defaultmuted/index.md @@ -8,7 +8,7 @@ browser-compat: api.HTMLMediaElement.defaultMuted {{APIRef("HTML DOM")}} -The **`HTMLMediaElement.defaultMuted`** property reflects the [`muted`](/en-US/docs/Web/HTML/Element/video#muted) HTML attribute, which indicates whether the media element's audio output should be muted by default. This property has no dynamic effect. To mute and unmute the audio output, use the {{domxref("HTMLMediaElement.muted", "muted")}} property. +The **`HTMLMediaElement.defaultMuted`** property reflects the [`muted`](/en-US/docs/Web/HTML/Reference/Elements/video#muted) HTML attribute, which indicates whether the media element's audio output should be muted by default. This property has no dynamic effect. To mute and unmute the audio output, use the {{domxref("HTMLMediaElement.muted", "muted")}} property. ## Value diff --git a/files/en-us/web/api/htmlmediaelement/disableremoteplayback/index.md b/files/en-us/web/api/htmlmediaelement/disableremoteplayback/index.md index 8b80088488d2175..26ad5a7cea879b2 100644 --- a/files/en-us/web/api/htmlmediaelement/disableremoteplayback/index.md +++ b/files/en-us/web/api/htmlmediaelement/disableremoteplayback/index.md @@ -32,5 +32,5 @@ obj.disableRemotePlayback = true; ## See also -- [The `disableremoteplayback` attribute of the `<audio>` element](/en-US/docs/Web/HTML/Element/audio#disableremoteplayback) -- [The `disableremoteplayback` attribute of the `<video>` element](/en-US/docs/Web/HTML/Element/video#disableremoteplayback) +- [The `disableremoteplayback` attribute of the `<audio>` element](/en-US/docs/Web/HTML/Reference/Elements/audio#disableremoteplayback) +- [The `disableremoteplayback` attribute of the `<video>` element](/en-US/docs/Web/HTML/Reference/Elements/video#disableremoteplayback) diff --git a/files/en-us/web/api/htmlmediaelement/duration/index.md b/files/en-us/web/api/htmlmediaelement/duration/index.md index 2e52204965cea57..63a5ac7cc28d6c9 100644 --- a/files/en-us/web/api/htmlmediaelement/duration/index.md +++ b/files/en-us/web/api/htmlmediaelement/duration/index.md @@ -17,7 +17,7 @@ media in seconds. A double-precision floating-point value indicating the duration of the media in seconds. If no media data is available, the value `NaN` is returned. If the element's media doesn't have a known duration—such as for live media streams—the value -of `duration` is `+Infinity`. +of `duration` is `Infinity`. ## Examples diff --git a/files/en-us/web/api/htmlmediaelement/durationchange_event/index.md b/files/en-us/web/api/htmlmediaelement/durationchange_event/index.md index 76241698cc0dc3f..914395613556007 100644 --- a/files/en-us/web/api/htmlmediaelement/durationchange_event/index.md +++ b/files/en-us/web/api/htmlmediaelement/durationchange_event/index.md @@ -14,10 +14,10 @@ The `durationchange` event is fired when the `duration` attribute has been updat Use the event name in methods like {{domxref("EventTarget.addEventListener", "addEventListener()")}}, or set an event handler property. -```js -addEventListener("durationchange", (event) => {}); +```js-nolint +addEventListener("durationchange", (event) => { }) -ondurationchange = (event) => {}; +ondurationchange = (event) => { } ``` ## Event type diff --git a/files/en-us/web/api/htmlmediaelement/emptied_event/index.md b/files/en-us/web/api/htmlmediaelement/emptied_event/index.md index 30965a604507914..948667628e70067 100644 --- a/files/en-us/web/api/htmlmediaelement/emptied_event/index.md +++ b/files/en-us/web/api/htmlmediaelement/emptied_event/index.md @@ -16,10 +16,10 @@ This event is not cancelable and does not bubble. Use the event name in methods like {{domxref("EventTarget.addEventListener", "addEventListener()")}}, or set an event handler property. -```js -addEventListener("emptied", (event) => {}); +```js-nolint +addEventListener("emptied", (event) => { }) -onemptied = (event) => {}; +onemptied = (event) => { } ``` ## Event type diff --git a/files/en-us/web/api/htmlmediaelement/encrypted_event/index.md b/files/en-us/web/api/htmlmediaelement/encrypted_event/index.md index f8aca9551968d4f..9a36fb83bc9be34 100644 --- a/files/en-us/web/api/htmlmediaelement/encrypted_event/index.md +++ b/files/en-us/web/api/htmlmediaelement/encrypted_event/index.md @@ -16,10 +16,10 @@ This event is not cancelable and does not bubble. Use the event name in methods like {{domxref("EventTarget.addEventListener", "addEventListener()")}}, or set an event handler property. -```js -addEventListener("encrypted", (event) => {}); +```js-nolint +addEventListener("encrypted", (event) => { }) -onencrypted = (event) => {}; +onencrypted = (event) => { } ``` ## Event type diff --git a/files/en-us/web/api/htmlmediaelement/ended_event/index.md b/files/en-us/web/api/htmlmediaelement/ended_event/index.md index 495c16454852d29..c36c40706fc8636 100644 --- a/files/en-us/web/api/htmlmediaelement/ended_event/index.md +++ b/files/en-us/web/api/htmlmediaelement/ended_event/index.md @@ -21,10 +21,10 @@ This event is not cancelable and does not bubble. Use the event name in methods like {{domxref("EventTarget.addEventListener", "addEventListener()")}}, or set an event handler property. -```js -addEventListener("ended", (event) => {}); +```js-nolint +addEventListener("ended", (event) => { }) -onended = (event) => {}; +onended = (event) => { } ``` ## Event type diff --git a/files/en-us/web/api/htmlmediaelement/error_event/index.md b/files/en-us/web/api/htmlmediaelement/error_event/index.md index 199abd7415f792e..2584744fb396fb9 100644 --- a/files/en-us/web/api/htmlmediaelement/error_event/index.md +++ b/files/en-us/web/api/htmlmediaelement/error_event/index.md @@ -16,10 +16,10 @@ This event is not cancelable and does not bubble. Use the event name in methods like {{domxref("EventTarget.addEventListener", "addEventListener()")}}, or set an event handler property. -```js -addEventListener("error", (event) => {}); +```js-nolint +addEventListener("error", (event) => { }) -onerror = (event) => {}; +onerror = (event) => { } ``` ## Event type diff --git a/files/en-us/web/api/htmlmediaelement/index.md b/files/en-us/web/api/htmlmediaelement/index.md index c1052df7b4a75c8..fbff26cec9ae51f 100644 --- a/files/en-us/web/api/htmlmediaelement/index.md +++ b/files/en-us/web/api/htmlmediaelement/index.md @@ -21,7 +21,7 @@ _This interface also inherits properties from its ancestors {{domxref("HTMLEleme - : An {{domxref("AudioTrackList")}} that lists the {{domxref("AudioTrack")}} objects contained in the element. - {{domxref("HTMLMediaElement.autoplay")}} - - : A boolean value that reflects the [`autoplay`](/en-US/docs/Web/HTML/Element/video#autoplay) HTML attribute, indicating whether playback should automatically begin as soon as enough media is available to do so without interruption. + - : A boolean value that reflects the [`autoplay`](/en-US/docs/Web/HTML/Reference/Elements/video#autoplay) HTML attribute, indicating whether playback should automatically begin as soon as enough media is available to do so without interruption. > [!NOTE] > Automatically playing audio when the user doesn't expect or desire it is a poor user experience and should be avoided in most cases, though there are exceptions. See the [Autoplay guide for media and Web Audio APIs](/en-US/docs/Web/Media/Guides/Autoplay) for more information. Keep in mind that browsers may ignore autoplay requests, so you should ensure that your code isn't dependent on autoplay working. @@ -29,29 +29,29 @@ _This interface also inherits properties from its ancestors {{domxref("HTMLEleme - {{domxref("HTMLMediaElement.buffered")}} {{ReadOnlyInline}} - : Returns a {{domxref("TimeRanges")}} object that indicates the ranges of the media source that the browser has buffered (if any) at the moment the `buffered` property is accessed. - {{domxref("HTMLMediaElement.controls")}} - - : A boolean that reflects the [`controls`](/en-US/docs/Web/HTML/Element/video#controls) HTML attribute, indicating whether user interface items for controlling the resource should be displayed. + - : A boolean that reflects the [`controls`](/en-US/docs/Web/HTML/Reference/Elements/video#controls) HTML attribute, indicating whether user interface items for controlling the resource should be displayed. - {{domxref("HTMLMediaElement.controlsList")}} - : Returns a {{domxref("DOMTokenList")}} that helps the user agent select what controls to show on the media element whenever the user agent shows its own set of controls. The `DOMTokenList` takes one or more of three possible values: `nodownload`, `nofullscreen`, and `noremoteplayback`. - {{domxref("HTMLMediaElement.crossOrigin")}} - - : A string indicating the [CORS setting](/en-US/docs/Web/HTML/Attributes/crossorigin) for this media element. + - : A string indicating the [CORS setting](/en-US/docs/Web/HTML/Reference/Attributes/crossorigin) for this media element. - {{domxref("HTMLMediaElement.currentSrc")}} {{ReadOnlyInline}} - : Returns a string with the absolute URL of the chosen media resource. - {{domxref("HTMLMediaElement.currentTime")}} - : A double-precision floating-point value indicating the current playback time in seconds; if the media has not started to play and has not been seeked, this value is the media's initial playback time. Setting this value seeks the media to the new time. The time is specified relative to the media's timeline. - {{domxref("HTMLMediaElement.defaultMuted")}} - - : A boolean that reflects the [`muted`](/en-US/docs/Web/HTML/Element/video#muted) HTML attribute, which indicates whether the media element's audio output should be muted by default. + - : A boolean that reflects the [`muted`](/en-US/docs/Web/HTML/Reference/Elements/video#muted) HTML attribute, which indicates whether the media element's audio output should be muted by default. - {{domxref("HTMLMediaElement.defaultPlaybackRate")}} - : A `double` indicating the default playback rate for the media. - {{domxref("HTMLMediaElement.disableRemotePlayback")}} - : A boolean that sets or returns the remote playback state, indicating whether the media element is allowed to have a remote playback UI. - {{domxref("HTMLMediaElement.duration")}} {{ReadOnlyInline}} - - : A read-only double-precision floating-point value indicating the total duration of the media in seconds. If no media data is available, the returned value is `NaN`. If the media is of indefinite length (such as streamed live media, a WebRTC call's media, or similar), the value is `+Infinity`. + - : A read-only double-precision floating-point value indicating the total duration of the media in seconds. If no media data is available, the returned value is `NaN`. If the media is of indefinite length (such as streamed live media, a WebRTC call's media, or similar), the value is `Infinity`. - {{domxref("HTMLMediaElement.ended")}} {{ReadOnlyInline}} - : Returns a boolean that indicates whether the media element has finished playing. - {{domxref("HTMLMediaElement.error")}} {{ReadOnlyInline}} - : Returns a {{domxref("MediaError")}} object for the most recent error, or `null` if there has not been an error. - {{domxref("HTMLMediaElement.loop")}} - - : A boolean that reflects the [`loop`](/en-US/docs/Web/HTML/Element/video#loop) HTML attribute, which indicates whether the media element should start over when it reaches the end. + - : A boolean that reflects the [`loop`](/en-US/docs/Web/HTML/Reference/Elements/video#loop) HTML attribute, which indicates whether the media element should start over when it reaches the end. - {{domxref("HTMLMediaElement.mediaKeys")}} {{ReadOnlyInline}} {{SecureContext_Inline}} - : Returns a {{domxref("MediaKeys")}} object, that is a set of keys that the element can use for decryption of media data during playback. If no key is available, it can be `null`. - {{domxref("HTMLMediaElement.muted")}} @@ -65,7 +65,7 @@ _This interface also inherits properties from its ancestors {{domxref("HTMLEleme - {{domxref("HTMLMediaElement.played")}} {{ReadOnlyInline}} - : Returns a {{domxref('TimeRanges')}} object that contains the ranges of the media source that the browser has played, if any. - {{domxref("HTMLMediaElement.preload")}} - - : A string that reflects the [`preload`](/en-US/docs/Web/HTML/Element/video#preload) HTML attribute, indicating what data should be preloaded, if any. Possible values are: `none`, `metadata`, `auto`. + - : A string that reflects the [`preload`](/en-US/docs/Web/HTML/Reference/Elements/video#preload) HTML attribute, indicating what data should be preloaded, if any. Possible values are: `none`, `metadata`, `auto`. - {{domxref("HTMLMediaElement.preservesPitch")}} - : A boolean value that determines if the pitch of the sound will be preserved. If set to `false`, the pitch will adjust to the speed of the audio. - {{domxref("HTMLMediaElement.readyState")}} {{ReadOnlyInline}} @@ -79,9 +79,9 @@ _This interface also inherits properties from its ancestors {{domxref("HTMLEleme - {{domxref("HTMLMediaElement.sinkId")}} {{ReadOnlyInline}} {{SecureContext_Inline}} - : Returns a string that is the unique ID of the audio device delivering output, or an empty string if the user agent default audio device is being used. - {{domxref("HTMLMediaElement.src")}} - - : A string that reflects the [`src`](/en-US/docs/Web/HTML/Element/video#src) HTML attribute, which contains the URL of a media resource to use. + - : A string that reflects the [`src`](/en-US/docs/Web/HTML/Reference/Elements/video#src) HTML attribute, which contains the URL of a media resource to use. - {{domxref("HTMLMediaElement.srcObject")}} - - : An object which serves as the source of the media associated with the {{domxref("HTMLMediaElement")}}, or `null` if not assigned. + - : An object which serves as the source of the media associated with the `HTMLMediaElement`, or `null` if not assigned. - {{domxref("HTMLMediaElement.textTracks")}} {{ReadOnlyInline}} - : Returns a {{domxref('TextTrackList')}} object containing the list of {{domxref("TextTrack")}} objects contained in the element. - {{domxref("HTMLMediaElement.videoTracks")}} {{ReadOnlyInline}} @@ -115,7 +115,7 @@ _This interface also inherits methods from its ancestors {{domxref("HTMLElement" - {{domxref("HTMLMediaElement.fastSeek()")}} - : Quickly seeks to the given time with low precision. - {{domxref("HTMLMediaElement.load()")}} - - : Resets the media to the beginning and selects the best available source from the sources provided using the [`src`](/en-US/docs/Web/HTML/Element/video#src) attribute or the {{HTMLElement("source")}} element. + - : Resets the media to the beginning and selects the best available source from the sources provided using the [`src`](/en-US/docs/Web/HTML/Reference/Elements/video#src) attribute or the {{HTMLElement("source")}} element. - {{domxref("HTMLMediaElement.pause()")}} - : Pauses the media playback. - {{domxref("HTMLMediaElement.play()")}} diff --git a/files/en-us/web/api/htmlmediaelement/load/index.md b/files/en-us/web/api/htmlmediaelement/load/index.md index f17a02848f7a5b3..1f05313952341a6 100644 --- a/files/en-us/web/api/htmlmediaelement/load/index.md +++ b/files/en-us/web/api/htmlmediaelement/load/index.md @@ -14,11 +14,11 @@ begins the process of selecting a media source and loading the media in preparat for playback to begin at the beginning. The amount of media data that is -prefetched is determined by the value of the element's [`preload`](/en-US/docs/Web/HTML/Element/video#preload) attribute. +prefetched is determined by the value of the element's [`preload`](/en-US/docs/Web/HTML/Reference/Elements/video#preload) attribute. This method is generally only useful when you've made dynamic changes to the set of sources available for the media element, either by changing the element's -[`src`](/en-US/docs/Web/HTML/Element/video#src) attribute or by adding or removing +[`src`](/en-US/docs/Web/HTML/Reference/Elements/video#src) attribute or by adding or removing {{HTMLElement("source")}} elements nested within the media element itself. `load()` will reset the element and rescan the available sources, thereby causing the changes to take effect. @@ -42,7 +42,7 @@ None ({{jsxref("undefined")}}). Calling `load()` aborts all ongoing operations involving this media element, then begins the process of selecting and loading an appropriate media resource given the options specified in the {{HTMLElement("audio")}} or {{HTMLElement("video")}} element -and its [`src`](/en-US/docs/Web/HTML/Element/video#src) attribute or child {{HTMLElement("source")}} +and its [`src`](/en-US/docs/Web/HTML/Reference/Elements/video#src) attribute or child {{HTMLElement("source")}} element(s). This is described in more detail in the [HTML video and audio](/en-US/docs/Learn_web_development/Core/Structuring_content/HTML_video_and_audio#using_multiple_source_formats_to_improve_compatibility) page. diff --git a/files/en-us/web/api/htmlmediaelement/loadeddata_event/index.md b/files/en-us/web/api/htmlmediaelement/loadeddata_event/index.md index cc76d480612da3f..e88a5aee142c2f4 100644 --- a/files/en-us/web/api/htmlmediaelement/loadeddata_event/index.md +++ b/files/en-us/web/api/htmlmediaelement/loadeddata_event/index.md @@ -17,10 +17,10 @@ The **`loadeddata`** event is fired when the frame at the current playback posit Use the event name in methods like {{domxref("EventTarget.addEventListener", "addEventListener()")}}, or set an event handler property. -```js -addEventListener("loadeddata", (event) => {}); +```js-nolint +addEventListener("loadeddata", (event) => { }) -onloadeddata = (event) => {}; +onloadeddata = (event) => { } ``` ## Event type diff --git a/files/en-us/web/api/htmlmediaelement/loadedmetadata_event/index.md b/files/en-us/web/api/htmlmediaelement/loadedmetadata_event/index.md index b641eb16edc341c..67f92b197d32541 100644 --- a/files/en-us/web/api/htmlmediaelement/loadedmetadata_event/index.md +++ b/files/en-us/web/api/htmlmediaelement/loadedmetadata_event/index.md @@ -14,10 +14,10 @@ The `loadedmetadata` event is fired when the metadata has been loaded. Use the event name in methods like {{domxref("EventTarget.addEventListener", "addEventListener()")}}, or set an event handler property. -```js -addEventListener("loadedmetadata", (event) => {}); +```js-nolint +addEventListener("loadedmetadata", (event) => { }) -onloadedmetadata = (event) => {}; +onloadedmetadata = (event) => { } ``` ## Event type diff --git a/files/en-us/web/api/htmlmediaelement/loadstart_event/index.md b/files/en-us/web/api/htmlmediaelement/loadstart_event/index.md index c1f5ba3be6f97c7..95a3f2f60923b8e 100644 --- a/files/en-us/web/api/htmlmediaelement/loadstart_event/index.md +++ b/files/en-us/web/api/htmlmediaelement/loadstart_event/index.md @@ -14,10 +14,10 @@ The **`loadstart`** event is fired when the browser has started to load a resour Use the event name in methods like {{domxref("EventTarget.addEventListener", "addEventListener()")}}, or set an event handler property. -```js -addEventListener("loadstart", (event) => {}); +```js-nolint +addEventListener("loadstart", (event) => { }) -onloadstart = (event) => {}; +onloadstart = (event) => { } ``` ## Event type @@ -100,10 +100,7 @@ loadVideo.addEventListener("click", () => { } else { loadVideo.textContent = "Reset example"; source = document.createElement("source"); - source.setAttribute( - "src", - "https://interactive-examples.mdn.mozilla.net/media/cc0-videos/flower.webm", - ); + source.setAttribute("src", "/shared-assets/videos/flower.webm"); source.setAttribute("type", "video/webm"); video.appendChild(source); diff --git a/files/en-us/web/api/htmlmediaelement/loop/index.md b/files/en-us/web/api/htmlmediaelement/loop/index.md index fe58028f6d202e4..760ed033922e082 100644 --- a/files/en-us/web/api/htmlmediaelement/loop/index.md +++ b/files/en-us/web/api/htmlmediaelement/loop/index.md @@ -8,7 +8,7 @@ browser-compat: api.HTMLMediaElement.loop {{APIRef("HTML DOM")}} -The **`HTMLMediaElement.loop`** property reflects the [`loop`](/en-US/docs/Web/HTML/Element/video#loop) HTML attribute, which controls whether the media element should start over when it reaches the end. +The **`HTMLMediaElement.loop`** property reflects the [`loop`](/en-US/docs/Web/HTML/Reference/Elements/video#loop) HTML attribute, which controls whether the media element should start over when it reaches the end. ## Value diff --git a/files/en-us/web/api/htmlmediaelement/pause_event/index.md b/files/en-us/web/api/htmlmediaelement/pause_event/index.md index 3ee586aa161004f..ad56ac525fb94a2 100644 --- a/files/en-us/web/api/htmlmediaelement/pause_event/index.md +++ b/files/en-us/web/api/htmlmediaelement/pause_event/index.md @@ -18,10 +18,10 @@ This event is not cancelable and does not bubble. Use the event name in methods like {{domxref("EventTarget.addEventListener", "addEventListener()")}}, or set an event handler property. -```js -addEventListener("pause", (event) => {}); +```js-nolint +addEventListener("pause", (event) => { }) -onpause = (event) => {}; +onpause = (event) => { } ``` ## Event type diff --git a/files/en-us/web/api/htmlmediaelement/play/index.md b/files/en-us/web/api/htmlmediaelement/play/index.md index b45a54b90c11908..8ca8fbc11fd5d18 100644 --- a/files/en-us/web/api/htmlmediaelement/play/index.md +++ b/files/en-us/web/api/htmlmediaelement/play/index.md @@ -44,7 +44,7 @@ thrown). Possible errors include: - `NotAllowedError` {{domxref("DOMException")}} - : Provided if the user agent (browser) or operating system doesn't allow playback of media in the current context or situation. The browser may require the user to explicitly start - media playback by clicking a "play" button, for example because of a [Permissions Policy](/en-US/docs/Web/HTTP/Permissions_Policy). + media playback by clicking a "play" button, for example because of a [Permissions Policy](/en-US/docs/Web/HTTP/Guides/Permissions_Policy). - `NotSupportedError` {{domxref("DOMException")}} - : Provided if the media source (which may be specified as a {{domxref("MediaStream")}}, {{domxref("MediaSource")}}, {{domxref("Blob")}}, or {{domxref("File")}}, for example) diff --git a/files/en-us/web/api/htmlmediaelement/play_event/index.md b/files/en-us/web/api/htmlmediaelement/play_event/index.md index c61502585850f7e..b91013542abd5ea 100644 --- a/files/en-us/web/api/htmlmediaelement/play_event/index.md +++ b/files/en-us/web/api/htmlmediaelement/play_event/index.md @@ -16,10 +16,10 @@ This event is not cancelable and does not bubble. Use the event name in methods like {{domxref("EventTarget.addEventListener", "addEventListener()")}}, or set an event handler property. -```js -addEventListener("play", (event) => {}); +```js-nolint +addEventListener("play", (event) => { }) -onplay = (event) => {}; +onplay = (event) => { } ``` ## Event type diff --git a/files/en-us/web/api/htmlmediaelement/playing_event/index.md b/files/en-us/web/api/htmlmediaelement/playing_event/index.md index 7209dfe3ab315e2..fa60daf3c0a79a3 100644 --- a/files/en-us/web/api/htmlmediaelement/playing_event/index.md +++ b/files/en-us/web/api/htmlmediaelement/playing_event/index.md @@ -16,10 +16,10 @@ This event is not cancelable and does not bubble. Use the event name in methods like {{domxref("EventTarget.addEventListener", "addEventListener()")}}, or set an event handler property. -```js -addEventListener("playing", (event) => {}); +```js-nolint +addEventListener("playing", (event) => { }) -onplaying = (event) => {}; +onplaying = (event) => { } ``` ## Event type diff --git a/files/en-us/web/api/htmlmediaelement/preload/index.md b/files/en-us/web/api/htmlmediaelement/preload/index.md index a846bac9253c702..c0011b353807cf6 100644 --- a/files/en-us/web/api/htmlmediaelement/preload/index.md +++ b/files/en-us/web/api/htmlmediaelement/preload/index.md @@ -19,7 +19,7 @@ A string. Possible values are as follows: - `none` - : Indicates that the media should not be preloaded. - `metadata` - - : Indicates that only media metadata (e.g. length) is fetched. + - : Indicates that only media metadata (e.g., length) is fetched. - `auto` - : Indicates that the whole media file can be downloaded, even if the user is not expected to use it. - _empty string_ diff --git a/files/en-us/web/api/htmlmediaelement/progress_event/index.md b/files/en-us/web/api/htmlmediaelement/progress_event/index.md index 275fc2510bb5056..3d1a7651371a359 100644 --- a/files/en-us/web/api/htmlmediaelement/progress_event/index.md +++ b/files/en-us/web/api/htmlmediaelement/progress_event/index.md @@ -16,10 +16,10 @@ This event is not cancelable and does not bubble. Use the event name in methods like {{domxref("EventTarget.addEventListener", "addEventListener()")}}, or set an event handler property. -```js -addEventListener("progress", (event) => {}); +```js-nolint +addEventListener("progress", (event) => { }) -onprogress = (event) => {}; +onprogress = (event) => { } ``` ## Event type diff --git a/files/en-us/web/api/htmlmediaelement/ratechange_event/index.md b/files/en-us/web/api/htmlmediaelement/ratechange_event/index.md index d11b92b30eb0dc7..dd70fb1fec8fb5b 100644 --- a/files/en-us/web/api/htmlmediaelement/ratechange_event/index.md +++ b/files/en-us/web/api/htmlmediaelement/ratechange_event/index.md @@ -16,10 +16,10 @@ This event is not cancelable and does not bubble. Use the event name in methods like {{domxref("EventTarget.addEventListener", "addEventListener()")}}, or set an event handler property. -```js -addEventListener("ratechange", (event) => {}); +```js-nolint +addEventListener("ratechange", (event) => { }) -onratechange = (event) => {}; +onratechange = (event) => { } ``` ## Event type diff --git a/files/en-us/web/api/htmlmediaelement/seekable/index.md b/files/en-us/web/api/htmlmediaelement/seekable/index.md index e4141f17d9bd44f..5277557a0a165d0 100644 --- a/files/en-us/web/api/htmlmediaelement/seekable/index.md +++ b/files/en-us/web/api/htmlmediaelement/seekable/index.md @@ -20,7 +20,7 @@ A new static [normalized TimeRanges object](/en-US/docs/Web/API/TimeRanges#norma const video = document.querySelector("video"); const timeRangesObject = video.seekable; const timeRanges = []; -//Go through the object and output an array +// Go through the object and output an array for (let count = 0; count < timeRangesObject.length; count++) { timeRanges.push([timeRangesObject.start(count), timeRangesObject.end(count)]); } diff --git a/files/en-us/web/api/htmlmediaelement/seeked_event/index.md b/files/en-us/web/api/htmlmediaelement/seeked_event/index.md index 0668a6624efc365..107c2d931098328 100644 --- a/files/en-us/web/api/htmlmediaelement/seeked_event/index.md +++ b/files/en-us/web/api/htmlmediaelement/seeked_event/index.md @@ -16,10 +16,10 @@ This event is not cancelable and does not bubble. Use the event name in methods like {{domxref("EventTarget.addEventListener", "addEventListener()")}}, or set an event handler property. -```js -addEventListener("seeked", (event) => {}); +```js-nolint +addEventListener("seeked", (event) => { }) -onseeked = (event) => {}; +onseeked = (event) => { } ``` ## Event type diff --git a/files/en-us/web/api/htmlmediaelement/seeking_event/index.md b/files/en-us/web/api/htmlmediaelement/seeking_event/index.md index 93ea59307ce0c11..d899f634da5bdfa 100644 --- a/files/en-us/web/api/htmlmediaelement/seeking_event/index.md +++ b/files/en-us/web/api/htmlmediaelement/seeking_event/index.md @@ -16,10 +16,10 @@ This event is not cancelable and does not bubble. Use the event name in methods like {{domxref("EventTarget.addEventListener", "addEventListener()")}}, or set an event handler property. -```js -addEventListener("seeking", (event) => {}); +```js-nolint +addEventListener("seeking", (event) => { }) -onseeking = (event) => {}; +onseeking = (event) => { } ``` ## Event type diff --git a/files/en-us/web/api/htmlmediaelement/setsinkid/index.md b/files/en-us/web/api/htmlmediaelement/setsinkid/index.md index f3a3db7f4490445..49b9a644261f36b 100644 --- a/files/en-us/web/api/htmlmediaelement/setsinkid/index.md +++ b/files/en-us/web/api/htmlmediaelement/setsinkid/index.md @@ -31,7 +31,7 @@ A {{jsxref("Promise")}} that resolves to {{jsxref("undefined")}}. ### Exceptions - `NotAllowedError` {{domxref("DOMException")}} - - : Returned if a [`speaker-selection`](/en-US/docs/Web/HTTP/Headers/Permissions-Policy/speaker-selection) [Permissions Policy](/en-US/docs/Web/HTTP/Permissions_Policy) is used to block use of audio outputs. + - : Returned if a [`speaker-selection`](/en-US/docs/Web/HTTP/Reference/Headers/Permissions-Policy/speaker-selection) [Permissions Policy](/en-US/docs/Web/HTTP/Guides/Permissions_Policy) is used to block use of audio outputs. - `NotFoundError` {{domxref("DOMException")}} - : Returned if the `deviceId` does not match any audio output device. - `AbortError` {{domxref("DOMException")}} @@ -42,7 +42,7 @@ A {{jsxref("Promise")}} that resolves to {{jsxref("undefined")}}. Access to the API is subject to the following constraints: - The method must be called in a [secure context](/en-US/docs/Web/Security/Secure_Contexts). -- Access may be gated by the [`speaker-selection`](/en-US/docs/Web/HTTP/Headers/Permissions-Policy/speaker-selection) HTTP [Permission Policy](/en-US/docs/Web/HTTP/Permissions_Policy). +- Access may be gated by the [`speaker-selection`](/en-US/docs/Web/HTTP/Reference/Headers/Permissions-Policy/speaker-selection) HTTP [Permission Policy](/en-US/docs/Web/HTTP/Guides/Permissions_Policy). - User permission is required to access a non-default device. The user grants permission by selecting the device associated with the ID in the prompt displayed by {{domxref("MediaDevices.selectAudioOutput()")}}. diff --git a/files/en-us/web/api/htmlmediaelement/srcobject/index.md b/files/en-us/web/api/htmlmediaelement/srcobject/index.md index 0b3b6be5ef5a870..717ba7aa9ab3279 100644 --- a/files/en-us/web/api/htmlmediaelement/srcobject/index.md +++ b/files/en-us/web/api/htmlmediaelement/srcobject/index.md @@ -16,7 +16,7 @@ The object can be a {{domxref("MediaStream")}}, a {{domxref("MediaSource")}}, a {{domxref("Blob")}}, or a {{domxref("File")}} (which inherits from `Blob`). > [!NOTE] -> As of March 2020, only Safari has full support for `srcObject`, i.e. using `MediaSource`, `MediaStream`, `Blob`, and `File` objects as values. Other browsers support `MediaStream` objects; until they catch up, consider falling back to creating a URL with {{domxref("URL.createObjectURL_static", "URL.createObjectURL()")}} and assigning it to {{domxref("HTMLMediaElement.src")}} (see below for an example). In addition, as of version 108 Chromium supports attaching a dedicated worker `MediaSource` object by assigning that object's {{domxref("MediaSourceHandle")}} instance (transferred from the worker) to `srcObject`. +> As of March 2020, only Safari has full support for `srcObject`, i.e., using `MediaSource`, `MediaStream`, `Blob`, and `File` objects as values. Other browsers support `MediaStream` objects; until they catch up, consider falling back to creating a URL with {{domxref("URL.createObjectURL_static", "URL.createObjectURL()")}} and assigning it to {{domxref("HTMLMediaElement.src")}} (see below for an example). In addition, as of version 108 Chromium supports attaching a dedicated worker `MediaSource` object by assigning that object's {{domxref("MediaSourceHandle")}} instance (transferred from the worker) to `srcObject`. ## Value diff --git a/files/en-us/web/api/htmlmediaelement/stalled_event/index.md b/files/en-us/web/api/htmlmediaelement/stalled_event/index.md index 4e12f2667d289fb..1b6a1c410ddf33e 100644 --- a/files/en-us/web/api/htmlmediaelement/stalled_event/index.md +++ b/files/en-us/web/api/htmlmediaelement/stalled_event/index.md @@ -16,10 +16,10 @@ This event is not cancelable and does not bubble. Use the event name in methods like {{domxref("EventTarget.addEventListener", "addEventListener()")}}, or set an event handler property. -```js -addEventListener("stalled", (event) => {}); +```js-nolint +addEventListener("stalled", (event) => { }) -onstalled = (event) => {}; +onstalled = (event) => { } ``` ## Event type diff --git a/files/en-us/web/api/htmlmediaelement/suspend_event/index.md b/files/en-us/web/api/htmlmediaelement/suspend_event/index.md index 80a603f5df3954c..11a12e82c0b12fb 100644 --- a/files/en-us/web/api/htmlmediaelement/suspend_event/index.md +++ b/files/en-us/web/api/htmlmediaelement/suspend_event/index.md @@ -16,10 +16,10 @@ This event is not cancelable and does not bubble. Use the event name in methods like {{domxref("EventTarget.addEventListener", "addEventListener()")}}, or set an event handler property. -```js -addEventListener("suspend", (event) => {}); +```js-nolint +addEventListener("suspend", (event) => { }) -onsuspend = (event) => {}; +onsuspend = (event) => { } ``` ## Event type diff --git a/files/en-us/web/api/htmlmediaelement/texttracks/index.md b/files/en-us/web/api/htmlmediaelement/texttracks/index.md index b5c1cc4cfbd5642..5726b9907ddb28b 100644 --- a/files/en-us/web/api/htmlmediaelement/texttracks/index.md +++ b/files/en-us/web/api/htmlmediaelement/texttracks/index.md @@ -15,8 +15,8 @@ objects representing the media element's text tracks, in the same order as in the list of text tracks. You can detect when tracks are added to and removed from an -[`<audio>`](/en-US/docs/Web/HTML/Element/audio) or -[`<video>`](/en-US/docs/Web/HTML/Element/video) element +[`<audio>`](/en-US/docs/Web/HTML/Reference/Elements/audio) or +[`<video>`](/en-US/docs/Web/HTML/Reference/Elements/video) element using the `addtrack` and `removetrack` events. However, these events aren't sent directly to the media element itself. Instead, they're sent to the track list object of the [`HTMLMediaElement`](/en-US/docs/Web/API/HTMLMediaElement) @@ -41,8 +41,8 @@ information about the track. ## Examples We start with a -[`<video>`](/en-US/docs/Web/HTML/Element/video) that has -several [`<track>`](/en-US/docs/Web/HTML/Element/track) +[`<video>`](/en-US/docs/Web/HTML/Reference/Elements/video) that has +several [`<track>`](/en-US/docs/Web/HTML/Reference/Elements/track) children ```html diff --git a/files/en-us/web/api/htmlmediaelement/timeupdate_event/index.md b/files/en-us/web/api/htmlmediaelement/timeupdate_event/index.md index 71bc8679044b676..0f0b873f837fec9 100644 --- a/files/en-us/web/api/htmlmediaelement/timeupdate_event/index.md +++ b/files/en-us/web/api/htmlmediaelement/timeupdate_event/index.md @@ -18,10 +18,10 @@ This event is not cancelable and does not bubble. Use the event name in methods like {{domxref("EventTarget.addEventListener", "addEventListener()")}}, or set an event handler property. -```js -addEventListener("timeupdate", (event) => {}); +```js-nolint +addEventListener("timeupdate", (event) => { }) -ontimeupdate = (event) => {}; +ontimeupdate = (event) => { } ``` ## Event type diff --git a/files/en-us/web/api/htmlmediaelement/volumechange_event/index.md b/files/en-us/web/api/htmlmediaelement/volumechange_event/index.md index 21ec40db70cb737..8bb7fda072b7632 100644 --- a/files/en-us/web/api/htmlmediaelement/volumechange_event/index.md +++ b/files/en-us/web/api/htmlmediaelement/volumechange_event/index.md @@ -16,10 +16,10 @@ This event is not cancelable and does not bubble. Use the event name in methods like {{domxref("EventTarget.addEventListener", "addEventListener()")}}, or set an event handler property. -```js -addEventListener("volumechange", (event) => {}); +```js-nolint +addEventListener("volumechange", (event) => { }) -onvolumechange = (event) => {}; +onvolumechange = (event) => { } ``` ## Event type diff --git a/files/en-us/web/api/htmlmediaelement/waiting_event/index.md b/files/en-us/web/api/htmlmediaelement/waiting_event/index.md index 7148dfccce7ee1f..33fd85f3ccd7e97 100644 --- a/files/en-us/web/api/htmlmediaelement/waiting_event/index.md +++ b/files/en-us/web/api/htmlmediaelement/waiting_event/index.md @@ -16,10 +16,10 @@ This event is not cancelable and does not bubble. Use the event name in methods like {{domxref("EventTarget.addEventListener", "addEventListener()")}}, or set an event handler property. -```js -addEventListener("waiting", (event) => {}); +```js-nolint +addEventListener("waiting", (event) => { }) -onwaiting = (event) => {}; +onwaiting = (event) => { } ``` ## Event type diff --git a/files/en-us/web/api/htmlmediaelement/waitingforkey_event/index.md b/files/en-us/web/api/htmlmediaelement/waitingforkey_event/index.md index 3f739c27f73d2b8..6e8472c25e7f462 100644 --- a/files/en-us/web/api/htmlmediaelement/waitingforkey_event/index.md +++ b/files/en-us/web/api/htmlmediaelement/waitingforkey_event/index.md @@ -17,10 +17,10 @@ Otherwise, including if the data was previously available but isn't anymore, the Use the event name in methods like {{domxref("EventTarget.addEventListener", "addEventListener()")}}, or set an event handler property. -```js -addEventListener("waitingforkey", (event) => {}); +```js-nolint +addEventListener("waitingforkey", (event) => { }) -onwaitingforkey = (event) => {}; +onwaitingforkey = (event) => { } ``` ## Event type diff --git a/files/en-us/web/api/htmlmetaelement/content/index.md b/files/en-us/web/api/htmlmetaelement/content/index.md index bd6b7bc91356ee0..71d88c12f8bc017 100644 --- a/files/en-us/web/api/htmlmetaelement/content/index.md +++ b/files/en-us/web/api/htmlmetaelement/content/index.md @@ -9,7 +9,7 @@ browser-compat: api.HTMLMetaElement.content {{APIRef("HTML DOM")}} The **`HTMLMetaElement.content`** property gets or sets the `content` attribute of pragma directives and named {{htmlelement("meta")}} data in conjunction with {{domxref("HTMLMetaElement.name")}} or {{domxref("HTMLMetaElement.httpEquiv")}}. -For more information, see the [content](/en-US/docs/Web/HTML/Element/meta#content) attribute. +For more information, see the [content](/en-US/docs/Web/HTML/Reference/Elements/meta#content) attribute. ## Value @@ -20,7 +20,7 @@ A string. ### Reading meta element content The following example queries a `<meta>` element that contains a `name` attribute with the value of `keywords`. -The `content` value is logged to the console to display the [keywords](/en-US/docs/Web/HTML/Element/meta/name#standard_metadata_names_defined_in_the_html_specification) of the document: +The `content` value is logged to the console to display the [keywords](/en-US/docs/Web/HTML/Reference/Elements/meta/name#standard_metadata_names_defined_in_the_html_specification) of the document: ```js // given <meta name="keywords" content="documentation, HTML, web"> @@ -31,7 +31,7 @@ console.log(meta.content); ### Creating a meta element with content -The following example creates a new `<meta>` element with a `name` attribute set to [`description`](/en-US/docs/Web/HTML/Element/meta/name#standard_metadata_names_defined_in_the_html_specification). +The following example creates a new `<meta>` element with a `name` attribute set to [`description`](/en-US/docs/Web/HTML/Reference/Elements/meta/name#standard_metadata_names_defined_in_the_html_specification). The `content` attribute sets a description of the document and is appended to the document `<head>`: ```js diff --git a/files/en-us/web/api/htmlmetaelement/httpequiv/index.md b/files/en-us/web/api/htmlmetaelement/httpequiv/index.md index 92480739b3470cf..0913367f50d336d 100644 --- a/files/en-us/web/api/htmlmetaelement/httpequiv/index.md +++ b/files/en-us/web/api/htmlmetaelement/httpequiv/index.md @@ -9,7 +9,7 @@ browser-compat: api.HTMLMetaElement.httpEquiv {{APIRef("HTML DOM")}} The **`HTMLMetaElement.httpEquiv`** property gets or sets the pragma directive or an HTTP response header name for the {{domxref("HTMLMetaElement.content")}} attribute. -For more details on the possible values, see the [http-equiv](/en-US/docs/Web/HTML/Element/meta#http-equiv) attribute. +For more details on the possible values, see the [http-equiv](/en-US/docs/Web/HTML/Reference/Elements/meta#http-equiv) attribute. ## Value @@ -20,7 +20,7 @@ A string. ### Reading the `http-equiv` value of a meta element The following example queries a `<meta>` element with an `http-equiv` attribute. -The `http-equiv` attribute is logged to the console showing a `refresh` [pragma directive](/en-US/docs/Web/HTML/Element/meta#http-equiv) that instructs the browser to refresh the page after a number of seconds defined by the `content` attribute: +The `http-equiv` attribute is logged to the console showing a `refresh` [pragma directive](/en-US/docs/Web/HTML/Reference/Elements/meta#http-equiv) that instructs the browser to refresh the page after a number of seconds defined by the `content` attribute: ```js // given <meta http-equiv="refresh" content="10" /> diff --git a/files/en-us/web/api/htmlmetaelement/index.md b/files/en-us/web/api/htmlmetaelement/index.md index 17993ce43db7f75..6d6ee26d8876497 100644 --- a/files/en-us/web/api/htmlmetaelement/index.md +++ b/files/en-us/web/api/htmlmetaelement/index.md @@ -7,7 +7,7 @@ browser-compat: api.HTMLMetaElement {{ APIRef("HTML DOM") }} -The **`HTMLMetaElement`** interface contains descriptive metadata about a document provided in HTML as [`<meta>`](/en-US/docs/Web/HTML/Element/meta) elements. +The **`HTMLMetaElement`** interface contains descriptive metadata about a document provided in HTML as [`<meta>`](/en-US/docs/Web/HTML/Reference/Elements/meta) elements. This interface inherits all of the properties and methods described in the {{domxref("HTMLElement")}} interface. {{InheritanceDiagram}} @@ -41,7 +41,7 @@ For specific examples, see the pages for the individual properties as described ### Setting the page description metadata -The following example creates a new `<meta>` element with a `name` attribute set to [`description`](/en-US/docs/Web/HTML/Element/meta/name#standard_metadata_names_defined_in_the_html_specification). +The following example creates a new `<meta>` element with a `name` attribute set to [`description`](/en-US/docs/Web/HTML/Reference/Elements/meta/name#standard_metadata_names_defined_in_the_html_specification). The `content` attribute sets a description of the document and is appended to the document `<head>`: ```js @@ -54,7 +54,7 @@ document.head.appendChild(meta); ### Setting the viewport metadata -The following example shows how to create a new `<meta>` element with a `name` attribute set to [`viewport`](/en-US/docs/Web/HTML/Element/meta/name#standard_metadata_names_defined_in_other_specifications). +The following example shows how to create a new `<meta>` element with a `name` attribute set to [`viewport`](/en-US/docs/Web/HTML/Reference/Elements/meta/name#standard_metadata_names_defined_in_other_specifications). The `content` attribute sets the viewport size and is appended to the document `<head>`: ```js @@ -64,7 +64,7 @@ meta.content = "width=device-width, initial-scale=1"; document.head.appendChild(meta); ``` -For more information on setting the viewport, see [Viewport basics](/en-US/docs/Web/HTML/Viewport_meta_tag#viewport_basics). +For more information on setting the viewport, see [Viewport basics](/en-US/docs/Web/HTML/Guides/Viewport_meta_element#viewport_basics). ## Specifications diff --git a/files/en-us/web/api/htmlmetaelement/media/index.md b/files/en-us/web/api/htmlmetaelement/media/index.md index ca6394df973dd74..a47bdf641eb40d0 100644 --- a/files/en-us/web/api/htmlmetaelement/media/index.md +++ b/files/en-us/web/api/htmlmetaelement/media/index.md @@ -21,7 +21,7 @@ A string. ### Setting the theme color for dark mode -The following example creates a new `<meta>` element with a `name` attribute set to [`theme-color`](/en-US/docs/Web/HTML/Element/meta/name#standard_metadata_names_defined_in_the_html_specification). +The following example creates a new `<meta>` element with a `name` attribute set to [`theme-color`](/en-US/docs/Web/HTML/Reference/Elements/meta/name#standard_metadata_names_defined_in_the_html_specification). The `content` attribute is set to `#3c790a`, the `media` attribute is set to `prefers-color-scheme: dark`, and the element is appended to the document `<head>`. When a user has specified a dark mode in their operating system, the `media` property can be used to set a different `theme-color`: diff --git a/files/en-us/web/api/htmlmetaelement/name/index.md b/files/en-us/web/api/htmlmetaelement/name/index.md index 5bda402da3f2918..f3ee48b53faec7d 100644 --- a/files/en-us/web/api/htmlmetaelement/name/index.md +++ b/files/en-us/web/api/htmlmetaelement/name/index.md @@ -20,7 +20,7 @@ A string. ### Reading the metadata name of a meta element The following example queries the first `<meta>` element in a document. -The `name` value is logged to the console, showing that [keywords](/en-US/docs/Web/HTML/Element/meta/name#standard_metadata_names_defined_in_the_html_specification) have been specified for the document: +The `name` value is logged to the console, showing that [keywords](/en-US/docs/Web/HTML/Reference/Elements/meta/name#standard_metadata_names_defined_in_the_html_specification) have been specified for the document: ```js // given <meta name="keywords" content="documentation, HTML, web technologies"> @@ -31,7 +31,7 @@ console.log(meta.name); ### Creating a meta element with `author` metadata -The following example creates a new `<meta>` element with a `name` attribute set to [`author`](/en-US/docs/Web/HTML/Element/meta/name#standard_metadata_names_defined_in_the_html_specification). +The following example creates a new `<meta>` element with a `name` attribute set to [`author`](/en-US/docs/Web/HTML/Reference/Elements/meta/name#standard_metadata_names_defined_in_the_html_specification). The `content` attribute sets the author of the document and the element is appended to the document `<head>`: ```js @@ -52,4 +52,4 @@ document.head.appendChild(meta); ## See also - {{HTMLElement("meta")}} -- [Possible values for the name attribute](/en-US/docs/Web/HTML/Element/meta/name#standard_metadata_names_defined_in_the_html_specification) +- [Possible values for the name attribute](/en-US/docs/Web/HTML/Reference/Elements/meta/name#standard_metadata_names_defined_in_the_html_specification) diff --git a/files/en-us/web/api/htmlmetaelement/scheme/index.md b/files/en-us/web/api/htmlmetaelement/scheme/index.md index f59bb8a5fd64bfd..bad9667853408ae 100644 --- a/files/en-us/web/api/htmlmetaelement/scheme/index.md +++ b/files/en-us/web/api/htmlmetaelement/scheme/index.md @@ -11,7 +11,7 @@ browser-compat: api.HTMLMetaElement.scheme {{APIRef("HTML DOM")}}{{Deprecated_Header}} The **`HTMLMetaElement.scheme`** property defines the scheme of the value in the {{domxref("HTMLMetaElement.content")}} attribute. -The `scheme` property was created to enable providing additional information to be used to interpret the value of the `content` property. The `scheme` property takes as its value a scheme format (i.e. `YYYY-MM-DD`) or scheme format name (i.e. `ISBN`), or a URI providing more information regarding the scheme format. The scheme defines the format of the value of the `content` attribute. +The `scheme` property was created to enable providing additional information to be used to interpret the value of the `content` property. The `scheme` property takes as its value a scheme format (i.e., `YYYY-MM-DD`) or scheme format name (i.e., `ISBN`), or a URI providing more information regarding the scheme format. The scheme defines the format of the value of the `content` attribute. The `scheme` content is interpreted as an extension of the element's {{domxref("HTMLMetaElement.name")}} if a browser or user agent recognizes the scheme. This property is deprecated and should not be used on new web pages. diff --git a/files/en-us/web/api/htmlmeterelement/high/index.md b/files/en-us/web/api/htmlmeterelement/high/index.md index a39b5701351b268..c20b127ec3f59ab 100644 --- a/files/en-us/web/api/htmlmeterelement/high/index.md +++ b/files/en-us/web/api/htmlmeterelement/high/index.md @@ -8,7 +8,7 @@ browser-compat: api.HTMLMeterElement.high {{ APIRef("HTML DOM") }} -The **`high`** property of the {{DOMxRef("HTMLMeterElement")}} interface represents the high boundary of the {{htmlelement("meter")}} element as a floating-point number. It reflects the element's [`high`](/en-US/docs/Web/HTML/Element/meter#high) attribute, or the value of `max` if not defined. The value of `high` is clamped by the `low` and `max` values. +The **`high`** property of the {{DOMxRef("HTMLMeterElement")}} interface represents the high boundary of the {{htmlelement("meter")}} element as a floating-point number. It reflects the element's [`high`](/en-US/docs/Web/HTML/Reference/Elements/meter#high) attribute, or the value of `max` if not defined. The value of `high` is clamped by the `low` and `max` values. This property can also be set directly, for example to set a default value based on some condition. diff --git a/files/en-us/web/api/htmlmeterelement/index.md b/files/en-us/web/api/htmlmeterelement/index.md index 5cf82168b30f4e7..857cc96cfae5674 100644 --- a/files/en-us/web/api/htmlmeterelement/index.md +++ b/files/en-us/web/api/htmlmeterelement/index.md @@ -16,17 +16,17 @@ The HTML {{HTMLElement("meter")}} elements expose the **`HTMLMeterElement`** int _Also inherits properties from its parent, {{domxref("HTMLElement")}}._ - {{domxref("HTMLMeterElement.high")}} - - : A `double` representing the value of the high boundary, reflecting the [`high`](/en-US/docs/Web/HTML/Element/meter#high) attribute. + - : A `double` representing the value of the high boundary, reflecting the [`high`](/en-US/docs/Web/HTML/Reference/Elements/meter#high) attribute. - {{domxref("HTMLMeterElement.low")}} - - : A `double` representing the value of the low boundary, reflecting the [`low`](/en-US/docs/Web/HTML/Element/meter#low) attribute. + - : A `double` representing the value of the low boundary, reflecting the [`low`](/en-US/docs/Web/HTML/Reference/Elements/meter#low) attribute. - {{domxref("HTMLMeterElement.max")}} - - : A `double` representing the maximum value, reflecting the [`max`](/en-US/docs/Web/HTML/Element/meter#max) attribute. + - : A `double` representing the maximum value, reflecting the [`max`](/en-US/docs/Web/HTML/Reference/Elements/meter#max) attribute. - {{domxref("HTMLMeterElement.min")}} - - : A `double` representing the minimum value, reflecting the [`min`](/en-US/docs/Web/HTML/Element/meter#min) attribute. + - : A `double` representing the minimum value, reflecting the [`min`](/en-US/docs/Web/HTML/Reference/Elements/meter#min) attribute. - {{domxref("HTMLMeterElement.optimum")}} - - : A `double` representing the optimum, reflecting the [`optimum`](/en-US/docs/Web/HTML/Element/meter#optimum) attribute. + - : A `double` representing the optimum, reflecting the [`optimum`](/en-US/docs/Web/HTML/Reference/Elements/meter#optimum) attribute. - {{domxref("HTMLMeterElement.value")}} - - : A `double` representing the current value, reflecting the [`value`](/en-US/docs/Web/HTML/Element/meter#value) attribute. + - : A `double` representing the current value, reflecting the [`value`](/en-US/docs/Web/HTML/Reference/Elements/meter#value) attribute. - {{domxref("HTMLMeterElement.labels")}} {{ReadOnlyInline}} - : A {{domxref("NodeList")}} of {{HTMLElement("label")}} elements that are associated with the element. diff --git a/files/en-us/web/api/htmlmeterelement/low/index.md b/files/en-us/web/api/htmlmeterelement/low/index.md index 8721a3c70659437..c5a37df85865a0d 100644 --- a/files/en-us/web/api/htmlmeterelement/low/index.md +++ b/files/en-us/web/api/htmlmeterelement/low/index.md @@ -8,7 +8,7 @@ browser-compat: api.HTMLMeterElement.low {{ APIRef("HTML DOM") }} -The **`low`** property of the {{DOMxRef("HTMLMeterElement")}} interface represents the low boundary of the {{htmlelement("meter")}} element as a floating-point number. It reflects the element's [`low`](/en-US/docs/Web/HTML/Element/meter#low) attribute, or the value of `min` if not defined. The value of `low` is clamped by the `min` and `max` values. +The **`low`** property of the {{DOMxRef("HTMLMeterElement")}} interface represents the low boundary of the {{htmlelement("meter")}} element as a floating-point number. It reflects the element's [`low`](/en-US/docs/Web/HTML/Reference/Elements/meter#low) attribute, or the value of `min` if not defined. The value of `low` is clamped by the `min` and `max` values. This property can also be set directly, for example to set a default value based on some condition. diff --git a/files/en-us/web/api/htmlmeterelement/max/index.md b/files/en-us/web/api/htmlmeterelement/max/index.md index dd29663fee0f01c..d4d17c7823e5cdd 100644 --- a/files/en-us/web/api/htmlmeterelement/max/index.md +++ b/files/en-us/web/api/htmlmeterelement/max/index.md @@ -8,7 +8,7 @@ browser-compat: api.HTMLMeterElement.max {{ APIRef("HTML DOM") }} -The **`max`** property of the {{DOMxRef("HTMLMeterElement")}} interface represents the maximum value of the {{htmlelement("meter")}} element as a floating-point number. It reflects the element's [`max`](/en-US/docs/Web/HTML/Element/meter#max) attribute, or the `min` value if no `max` is set, or `1` if neither the `min` or the `max` is defined. +The **`max`** property of the {{DOMxRef("HTMLMeterElement")}} interface represents the maximum value of the {{htmlelement("meter")}} element as a floating-point number. It reflects the element's [`max`](/en-US/docs/Web/HTML/Reference/Elements/meter#max) attribute, or the `min` value if no `max` is set, or `1` if neither the `min` or the `max` is defined. This property can also be set directly, for example to set a default value based on some condition. diff --git a/files/en-us/web/api/htmlmeterelement/min/index.md b/files/en-us/web/api/htmlmeterelement/min/index.md index 21873197d203475..f03518bf28dd1b2 100644 --- a/files/en-us/web/api/htmlmeterelement/min/index.md +++ b/files/en-us/web/api/htmlmeterelement/min/index.md @@ -8,7 +8,7 @@ browser-compat: api.HTMLMeterElement.min {{ APIRef("HTML DOM") }} -The **`min`** property of the {{DOMxRef("HTMLMeterElement")}} interface represents the minimum value of the {{htmlelement("meter")}} element as a floating-point number. It reflects the element's [`min`](/en-US/docs/Web/HTML/Element/meter#min) attribute, or `0` if no `min` is defined. +The **`min`** property of the {{DOMxRef("HTMLMeterElement")}} interface represents the minimum value of the {{htmlelement("meter")}} element as a floating-point number. It reflects the element's [`min`](/en-US/docs/Web/HTML/Reference/Elements/meter#min) attribute, or `0` if no `min` is defined. This property can also be set directly, for example to set a default value based on some condition. diff --git a/files/en-us/web/api/htmlmeterelement/optimum/index.md b/files/en-us/web/api/htmlmeterelement/optimum/index.md index 88058ac5fbfdc2f..8b7951ce47ac439 100644 --- a/files/en-us/web/api/htmlmeterelement/optimum/index.md +++ b/files/en-us/web/api/htmlmeterelement/optimum/index.md @@ -8,7 +8,7 @@ browser-compat: api.HTMLMeterElement.optimum {{ APIRef("HTML DOM") }} -The **`optimum`** property of the {{DOMxRef("HTMLMeterElement")}} interface represents the optimum boundary of the {{htmlelement("meter")}} element as a floating-point number. It reflects the element's [`optimum`](/en-US/docs/Web/HTML/Element/meter#optimum) attribute, or the midpoint between `min` and `max` values if not defined. The value of `optimum` is clamped by the `min` and `max` values. +The **`optimum`** property of the {{DOMxRef("HTMLMeterElement")}} interface represents the optimum boundary of the {{htmlelement("meter")}} element as a floating-point number. It reflects the element's [`optimum`](/en-US/docs/Web/HTML/Reference/Elements/meter#optimum) attribute, or the midpoint between `min` and `max` values if not defined. The value of `optimum` is clamped by the `min` and `max` values. This property can also be set directly, for example to set a default value based on some condition. diff --git a/files/en-us/web/api/htmlmeterelement/value/index.md b/files/en-us/web/api/htmlmeterelement/value/index.md index 9cb8bfd74a81803..c6f40a6c5482035 100644 --- a/files/en-us/web/api/htmlmeterelement/value/index.md +++ b/files/en-us/web/api/htmlmeterelement/value/index.md @@ -8,7 +8,7 @@ browser-compat: api.HTMLMeterElement.value {{ APIRef("HTML DOM") }} -The **`value`** property of the {{DOMxRef("HTMLMeterElement")}} interface represents the current value of the {{htmlelement("meter")}} element as a floating-point number. It reflects the element's [`value`](/en-US/docs/Web/HTML/Element/meter#value) attribute. If no `value` is set, it is the {{DOMxRef("HTMLMeterElement.min")}} value or `0`, whichever is greater. +The **`value`** property of the {{DOMxRef("HTMLMeterElement")}} interface represents the current value of the {{htmlelement("meter")}} element as a floating-point number. It reflects the element's [`value`](/en-US/docs/Web/HTML/Reference/Elements/meter#value) attribute. If no `value` is set, it is the {{DOMxRef("HTMLMeterElement.min")}} value or `0`, whichever is greater. This property can also be set directly, for example to set a default value based on some condition. diff --git a/files/en-us/web/api/htmlmodelement/datetime/index.md b/files/en-us/web/api/htmlmodelement/datetime/index.md index 14ef48acb0d85fa..35dd486a8e11055 100644 --- a/files/en-us/web/api/htmlmodelement/datetime/index.md +++ b/files/en-us/web/api/htmlmodelement/datetime/index.md @@ -8,11 +8,11 @@ browser-compat: api.HTMLModElement.dateTime {{ APIRef("HTML DOM") }} -The **`dateTime`** property of the {{domxref("HTMLModElement")}} interface is a string containing a machine-readable date with an optional time value. It reflects the [`datetime`](/en-US/docs/Web/HTML/Element/time#datetime) HTML attribute of the {{HTMLElement("del")}} and {{HTMLElement("ins")}} elements. +The **`dateTime`** property of the {{domxref("HTMLModElement")}} interface is a string containing a machine-readable date with an optional time value. It reflects the [`datetime`](/en-US/docs/Web/HTML/Reference/Elements/time#datetime) HTML attribute of the {{HTMLElement("del")}} and {{HTMLElement("ins")}} elements. ## Value -A string. For valid string formats, see the [`datetime` valid values](/en-US/docs/Web/HTML/Element/time#valid_datetime_values). +A string. For valid string formats, see the [`datetime` valid values](/en-US/docs/Web/HTML/Reference/Elements/time#valid_datetime_values). ## Examples @@ -63,7 +63,7 @@ If our script ran on January 9, 2025, our HTML would be as follows: - {{domxref("HTMLModElement")}} - {{domxref("HTMLModElement.cite")}} - {{domxref("HTMLTimeElement.dateTime")}} -- [Date strings](/en-US/docs/Web/HTML/Date_and_time_formats#date_strings) -- [Local date and time strings](/en-US/docs/Web/HTML/Date_and_time_formats#local_date_and_time_strings) +- [Date strings](/en-US/docs/Web/HTML/Guides/Date_and_time_formats#date_strings) +- [Local date and time strings](/en-US/docs/Web/HTML/Guides/Date_and_time_formats#local_date_and_time_strings) - {{jsxref("Date")}} - {{domxref("Element.insertAdjacentElement()")}} diff --git a/files/en-us/web/api/htmlmodelement/index.md b/files/en-us/web/api/htmlmodelement/index.md index 413c4da0038fab5..aabbbb1f0300027 100644 --- a/files/en-us/web/api/htmlmodelement/index.md +++ b/files/en-us/web/api/htmlmodelement/index.md @@ -16,9 +16,9 @@ The **`HTMLModElement`** interface provides special properties (beyond the regul _Inherits properties from its parent, {{domxref("HTMLElement")}}._ - {{domxref("HTMLModElement.cite")}} - - : A string reflecting the [`cite`](/en-US/docs/Web/HTML/Element/del#cite) HTML attribute, containing a URI of a resource explaining the change. + - : A string reflecting the [`cite`](/en-US/docs/Web/HTML/Reference/Elements/del#cite) HTML attribute, containing a URI of a resource explaining the change. - {{domxref("HTMLModElement.dateTime")}} - - : A string reflecting the [`datetime`](/en-US/docs/Web/HTML/Element/del#datetime) HTML attribute, containing a date-and-time string representing a timestamp for the change. + - : A string reflecting the [`datetime`](/en-US/docs/Web/HTML/Reference/Elements/del#datetime) HTML attribute, containing a date-and-time string representing a timestamp for the change. ## Specifications diff --git a/files/en-us/web/api/htmlobjectelement/checkvalidity/index.md b/files/en-us/web/api/htmlobjectelement/checkvalidity/index.md index b564975ef2e8a6d..e8eb2d15ba7ae42 100644 --- a/files/en-us/web/api/htmlobjectelement/checkvalidity/index.md +++ b/files/en-us/web/api/htmlobjectelement/checkvalidity/index.md @@ -8,7 +8,7 @@ browser-compat: api.HTMLObjectElement.checkValidity {{APIRef("HTML DOM")}} -The **`checkValidity()`** method of the {{domxref("HTMLObjectElement")}} interface checks if the element is valid, but always returns true because {{HTMLElement("object")}} elements are never candidates for [constraint validation](/en-US/docs/Web/HTML/Constraint_validation). +The **`checkValidity()`** method of the {{domxref("HTMLObjectElement")}} interface checks if the element is valid, but always returns true because {{HTMLElement("object")}} elements are never candidates for [constraint validation](/en-US/docs/Web/HTML/Guides/Constraint_validation). ## Syntax @@ -47,4 +47,4 @@ console.log(element.checkValidity()); - {{HTMLElement("object")}} - {{HTMLElement("form")}} - [Learn: Client-side form validation](/en-US/docs/Learn_web_development/Extensions/Forms/Form_validation) -- [Guide: Constraint validation](/en-US/docs/Web/HTML/Constraint_validation) +- [Guide: Constraint validation](/en-US/docs/Web/HTML/Guides/Constraint_validation) diff --git a/files/en-us/web/api/htmlobjectelement/data/index.md b/files/en-us/web/api/htmlobjectelement/data/index.md index 6e4aab6c29e5e89..98400b192f1cb7c 100644 --- a/files/en-us/web/api/htmlobjectelement/data/index.md +++ b/files/en-us/web/api/htmlobjectelement/data/index.md @@ -10,7 +10,7 @@ browser-compat: api.HTMLObjectElement.data The **`data`** property of the {{domxref("HTMLObjectElement")}} interface returns a string that -reflects the [`data`](/en-US/docs/Web/HTML/Element/object#data) HTML attribute, specifying the address +reflects the [`data`](/en-US/docs/Web/HTML/Reference/Elements/object#data) HTML attribute, specifying the address of a resource's data. ## Value diff --git a/files/en-us/web/api/htmlobjectelement/height/index.md b/files/en-us/web/api/htmlobjectelement/height/index.md index 6843bc846380755..b6b90e6e9fef887 100644 --- a/files/en-us/web/api/htmlobjectelement/height/index.md +++ b/files/en-us/web/api/htmlobjectelement/height/index.md @@ -10,7 +10,7 @@ browser-compat: api.HTMLObjectElement.height The **`height`** property of the {{domxref("HTMLObjectElement")}} interface Returns a string that -reflects the [`height`](/en-US/docs/Web/HTML/Element/object#height) HTML attribute, specifying the +reflects the [`height`](/en-US/docs/Web/HTML/Reference/Elements/object#height) HTML attribute, specifying the displayed height of the resource in CSS pixels. ## Value diff --git a/files/en-us/web/api/htmlobjectelement/index.md b/files/en-us/web/api/htmlobjectelement/index.md index 20ada56929dbb0b..5804c46fc6d725b 100644 --- a/files/en-us/web/api/htmlobjectelement/index.md +++ b/files/en-us/web/api/htmlobjectelement/index.md @@ -18,37 +18,37 @@ _Inherits properties from its parent, {{domxref("HTMLElement")}}._ - {{domxref("HTMLObjectElement.align")}} {{deprecated_inline}} - : A string representing an enumerated property indicating alignment of the element's contents with respect to the surrounding context. The possible values are `"left"`, `"right"`, `"justify"`, and `"center"`. - {{domxref("HTMLObjectElement.archive")}} {{deprecated_inline}} - - : A string that reflects the [`archive`](/en-US/docs/Web/HTML/Element/object#archive) HTML attribute, containing a list of archives for resources for this object. + - : A string that reflects the [`archive`](/en-US/docs/Web/HTML/Reference/Elements/object#archive) HTML attribute, containing a list of archives for resources for this object. - {{domxref("HTMLObjectElement.border")}} {{deprecated_inline}} - - : A string that reflects the [`border`](/en-US/docs/Web/HTML/Element/object#border) HTML attribute, specifying the width of a border around the object. + - : A string that reflects the [`border`](/en-US/docs/Web/HTML/Reference/Elements/object#border) HTML attribute, specifying the width of a border around the object. - {{domxref("HTMLObjectElement.code")}} {{deprecated_inline}} - : A string representing the name of an applet class file, containing either the applet's subclass, or the path to get to the class, including the class file itself. - {{domxref("HTMLObjectElement.codeBase")}} {{deprecated_inline}} - - : A string that reflects the [`codebase`](/en-US/docs/Web/HTML/Element/object#codebase) HTML attribute, specifying the base path to use to resolve relative URIs. + - : A string that reflects the [`codebase`](/en-US/docs/Web/HTML/Reference/Elements/object#codebase) HTML attribute, specifying the base path to use to resolve relative URIs. - {{domxref("HTMLObjectElement.codeType")}} {{deprecated_inline}} - - : A string that reflects the [`codetype`](/en-US/docs/Web/HTML/Element/object#codetype) HTML attribute, specifying the content type of the data. + - : A string that reflects the [`codetype`](/en-US/docs/Web/HTML/Reference/Elements/object#codetype) HTML attribute, specifying the content type of the data. - {{domxref("HTMLObjectElement.contentDocument")}} {{ReadOnlyInline}} - : Returns a {{domxref("Document")}} representing the active document of the object element's nested browsing context, if any; otherwise `null`. - {{domxref("HTMLObjectElement.contentWindow")}} {{ReadOnlyInline}} - : Returns a {{glossary("WindowProxy")}} representing the window proxy of the object element's nested browsing context, if any; otherwise `null`. - {{domxref("HTMLObjectElement.data")}} - - : Returns a string that reflects the [`data`](/en-US/docs/Web/HTML/Element/object#data) HTML attribute, specifying the address of a resource's data. + - : Returns a string that reflects the [`data`](/en-US/docs/Web/HTML/Reference/Elements/object#data) HTML attribute, specifying the address of a resource's data. - {{domxref("HTMLObjectElement.declare")}} {{deprecated_inline}} - - : A boolean value that reflects the [`declare`](/en-US/docs/Web/HTML/Element/object#declare) HTML attribute, indicating that this is a declaration, not an instantiation, of the object. + - : A boolean value that reflects the [`declare`](/en-US/docs/Web/HTML/Reference/Elements/object#declare) HTML attribute, indicating that this is a declaration, not an instantiation, of the object. - {{domxref("HTMLObjectElement.form")}} {{ReadOnlyInline}} - : Returns a {{domxref("HTMLFormElement")}} representing the object element's form owner, or null if there isn't one. - {{domxref("HTMLObjectElement.height")}} - - : Returns a string that reflects the [`height`](/en-US/docs/Web/HTML/Element/object#height) HTML attribute, specifying the displayed height of the resource in CSS pixels. + - : Returns a string that reflects the [`height`](/en-US/docs/Web/HTML/Reference/Elements/object#height) HTML attribute, specifying the displayed height of the resource in CSS pixels. - {{domxref("HTMLObjectElement.hspace")}} {{deprecated_inline}} - : A `long` representing the horizontal space in pixels around the control. - {{domxref("HTMLObjectElement.name")}} - - : Returns a string that reflects the [`name`](/en-US/docs/Web/HTML/Element/object#name) HTML attribute, specifying the name of the browsing context. + - : Returns a string that reflects the [`name`](/en-US/docs/Web/HTML/Reference/Elements/object#name) HTML attribute, specifying the name of the browsing context. - {{domxref("HTMLObjectElement.standby")}} {{deprecated_inline}} - - : A string that reflects the [`standby`](/en-US/docs/Web/HTML/Element/object#standby) HTML attribute, specifying a message to display while the object loads. + - : A string that reflects the [`standby`](/en-US/docs/Web/HTML/Reference/Elements/object#standby) HTML attribute, specifying a message to display while the object loads. - {{domxref("HTMLObjectElement.type")}} - - : A string that reflects the [`type`](/en-US/docs/Web/HTML/Element/object#type) HTML attribute, specifying the MIME type of the resource. + - : A string that reflects the [`type`](/en-US/docs/Web/HTML/Reference/Elements/object#type) HTML attribute, specifying the MIME type of the resource. - {{domxref("HTMLObjectElement.useMap")}} {{deprecated_inline}} - - : A string that reflects the [`usemap`](/en-US/docs/Web/HTML/Element/object#usemap) HTML attribute, specifying a {{HTMLElement("map")}} element to use. + - : A string that reflects the [`usemap`](/en-US/docs/Web/HTML/Reference/Elements/object#usemap) HTML attribute, specifying a {{HTMLElement("map")}} element to use. - {{domxref("HTMLObjectElement.validationMessage")}} {{ReadOnlyInline}} - : Returns a string representing a localized message that describes the validation constraints that the control does not satisfy (if any). This is the empty string if the control is not a candidate for constraint validation (`willValidate` is `false`), or it satisfies its constraints. - {{domxref("HTMLObjectElement.validity")}} {{ReadOnlyInline}} @@ -56,7 +56,7 @@ _Inherits properties from its parent, {{domxref("HTMLElement")}}._ - {{domxref("HTMLObjectElement.vspace")}} {{deprecated_inline}} - : A `long` representing the horizontal space in pixels around the control. - {{domxref("HTMLObjectElement.width")}} - - : A string that reflects the [`width`](/en-US/docs/Web/HTML/Element/object#width) HTML attribute, specifying the displayed width of the resource in CSS pixels. + - : A string that reflects the [`width`](/en-US/docs/Web/HTML/Reference/Elements/object#width) HTML attribute, specifying the displayed width of the resource in CSS pixels. - {{domxref("HTMLObjectElement.willValidate")}} {{ReadOnlyInline}} - : Returns a boolean value that indicates whether the element is a candidate for constraint validation. Always `false` for `HTMLObjectElement` objects. diff --git a/files/en-us/web/api/htmlobjectelement/name/index.md b/files/en-us/web/api/htmlobjectelement/name/index.md index 29ce8e2c2b7b8f3..6f1a8a25747cb6a 100644 --- a/files/en-us/web/api/htmlobjectelement/name/index.md +++ b/files/en-us/web/api/htmlobjectelement/name/index.md @@ -10,7 +10,7 @@ browser-compat: api.HTMLObjectElement.name The **`name`** property of the {{domxref("HTMLObjectElement")}} interface returns a string that -reflects the [`name`](/en-US/docs/Web/HTML/Element/object#name) HTML attribute, specifying the name of +reflects the [`name`](/en-US/docs/Web/HTML/Reference/Elements/object#name) HTML attribute, specifying the name of the browsing context. ## Value diff --git a/files/en-us/web/api/htmlobjectelement/reportvalidity/index.md b/files/en-us/web/api/htmlobjectelement/reportvalidity/index.md index 18c71822d8f35a2..14f39d96316be27 100644 --- a/files/en-us/web/api/htmlobjectelement/reportvalidity/index.md +++ b/files/en-us/web/api/htmlobjectelement/reportvalidity/index.md @@ -8,7 +8,7 @@ browser-compat: api.HTMLObjectElement.reportValidity {{APIRef("HTML DOM")}} -The **`reportValidity()`** method of the {{domxref("HTMLObjectElement")}} interface performs the same validity checking steps as the {{domxref("HTMLObjectElement.checkValidity", "checkValidity()")}} method. It always returns true because {{HTMLElement("object")}} elements are never candidates for [constraint validation](/en-US/docs/Web/HTML/Constraint_validation). +The **`reportValidity()`** method of the {{domxref("HTMLObjectElement")}} interface performs the same validity checking steps as the {{domxref("HTMLObjectElement.checkValidity", "checkValidity()")}} method. It always returns true because {{HTMLElement("object")}} elements are never candidates for [constraint validation](/en-US/docs/Web/HTML/Guides/Constraint_validation). ## Syntax @@ -38,4 +38,4 @@ A boolean value, `true`. - {{HTMLElement("object")}} - {{HTMLElement("form")}} - [Learn: Client-side form validation](/en-US/docs/Learn_web_development/Extensions/Forms/Form_validation) -- [Guide: Constraint validation](/en-US/docs/Web/HTML/Constraint_validation) +- [Guide: Constraint validation](/en-US/docs/Web/HTML/Guides/Constraint_validation) diff --git a/files/en-us/web/api/htmlobjectelement/type/index.md b/files/en-us/web/api/htmlobjectelement/type/index.md index ac620498af4952a..b1284447453235b 100644 --- a/files/en-us/web/api/htmlobjectelement/type/index.md +++ b/files/en-us/web/api/htmlobjectelement/type/index.md @@ -10,7 +10,7 @@ browser-compat: api.HTMLObjectElement.type The **`type`** property of the {{domxref("HTMLObjectElement")}} interface returns a string that -reflects the [`type`](/en-US/docs/Web/HTML/Element/object#type) HTML attribute, specifying the MIME type +reflects the [`type`](/en-US/docs/Web/HTML/Reference/Elements/object#type) HTML attribute, specifying the MIME type of the resource. ## Value diff --git a/files/en-us/web/api/htmlobjectelement/usemap/index.md b/files/en-us/web/api/htmlobjectelement/usemap/index.md index 82b534bef5434fb..955f271ab79c3c9 100644 --- a/files/en-us/web/api/htmlobjectelement/usemap/index.md +++ b/files/en-us/web/api/htmlobjectelement/usemap/index.md @@ -12,7 +12,7 @@ browser-compat: api.HTMLObjectElement.useMap The **`useMap`** property of the {{domxref("HTMLObjectElement")}} interface returns a string that -reflects the [`usemap`](/en-US/docs/Web/HTML/Element/object#usemap) HTML attribute, specifying a +reflects the [`usemap`](/en-US/docs/Web/HTML/Reference/Elements/object#usemap) HTML attribute, specifying a {{HTMLElement("map")}} element to use. ## Value diff --git a/files/en-us/web/api/htmlobjectelement/validity/index.md b/files/en-us/web/api/htmlobjectelement/validity/index.md index 7a6335bca1a2863..96dc7ca7b8e7bee 100644 --- a/files/en-us/web/api/htmlobjectelement/validity/index.md +++ b/files/en-us/web/api/htmlobjectelement/validity/index.md @@ -8,7 +8,7 @@ browser-compat: api.HTMLObjectElement.validity {{APIRef("HTML DOM")}} -The **`validity`** read-only property of the {{domxref("HTMLObjectElement")}} interface returns a {{domxref("ValidityState")}} object that represents the validity states this element is in. Although {{HTMLElement("object")}} elements are never candidates for [constraint validation](/en-US/docs/Web/HTML/Constraint_validation), the validity state may still be invalid if a custom validity message has been set. +The **`validity`** read-only property of the {{domxref("HTMLObjectElement")}} interface returns a {{domxref("ValidityState")}} object that represents the validity states this element is in. Although {{HTMLElement("object")}} elements are never candidates for [constraint validation](/en-US/docs/Web/HTML/Guides/Constraint_validation), the validity state may still be invalid if a custom validity message has been set. ## Value @@ -41,4 +41,4 @@ console.log(objectElem.checkValidity()); // true - {{HTMLElement("object")}} - {{HTMLElement("form")}} - [Learn: Client-side form validation](/en-US/docs/Learn_web_development/Extensions/Forms/Form_validation) -- [Guide: Constraint validation](/en-US/docs/Web/HTML/Constraint_validation) +- [Guide: Constraint validation](/en-US/docs/Web/HTML/Guides/Constraint_validation) diff --git a/files/en-us/web/api/htmlobjectelement/width/index.md b/files/en-us/web/api/htmlobjectelement/width/index.md index 948022429c1caad..0c5a4d38331bc8a 100644 --- a/files/en-us/web/api/htmlobjectelement/width/index.md +++ b/files/en-us/web/api/htmlobjectelement/width/index.md @@ -10,7 +10,7 @@ browser-compat: api.HTMLObjectElement.width The **`width`** property of the {{domxref("HTMLObjectElement")}} interface returns a string that -reflects the [`width`](/en-US/docs/Web/HTML/Element/object#width) HTML attribute, specifying the +reflects the [`width`](/en-US/docs/Web/HTML/Reference/Elements/object#width) HTML attribute, specifying the displayed width of the resource in CSS pixels. ## Value diff --git a/files/en-us/web/api/htmlobjectelement/willvalidate/index.md b/files/en-us/web/api/htmlobjectelement/willvalidate/index.md index 4c6c6566cc3aa45..bf6c6e3d87a63ea 100644 --- a/files/en-us/web/api/htmlobjectelement/willvalidate/index.md +++ b/files/en-us/web/api/htmlobjectelement/willvalidate/index.md @@ -8,7 +8,7 @@ browser-compat: api.HTMLObjectElement.willValidate {{APIRef("HTML DOM")}} -The **`willValidate`** read-only property of the {{domxref("HTMLObjectElement")}} interface returns `false`, because {{HTMLElement("object")}} elements are not candidates for [constraint validation](/en-US/docs/Web/HTML/Constraint_validation). +The **`willValidate`** read-only property of the {{domxref("HTMLObjectElement")}} interface returns `false`, because {{HTMLElement("object")}} elements are not candidates for [constraint validation](/en-US/docs/Web/HTML/Guides/Constraint_validation). ## Value @@ -28,4 +28,4 @@ The boolean value `false`. - {{HTMLElement("object")}} - {{HTMLElement("form")}} - [Learn: Client-side form validation](/en-US/docs/Learn_web_development/Extensions/Forms/Form_validation) -- [Guide: Constraint validation](/en-US/docs/Web/HTML/Constraint_validation) +- [Guide: Constraint validation](/en-US/docs/Web/HTML/Guides/Constraint_validation) diff --git a/files/en-us/web/api/htmlolistelement/index.md b/files/en-us/web/api/htmlolistelement/index.md index 0015f91f7e15349..08e94fe03f25d8e 100644 --- a/files/en-us/web/api/htmlolistelement/index.md +++ b/files/en-us/web/api/htmlolistelement/index.md @@ -16,12 +16,12 @@ The **`HTMLOListElement`** interface provides special properties (beyond those d _Inherits properties from its parent, {{domxref("HTMLElement")}}._ - {{domxref("HTMLOListElement.reversed")}} - - : A boolean value reflecting the [`reversed`](/en-US/docs/Web/HTML/Element/ol#reversed) and defining if the numbering is descending, that is its value is `true`, or ascending (`false`). + - : A boolean value reflecting the [`reversed`](/en-US/docs/Web/HTML/Reference/Elements/ol#reversed) and defining if the numbering is descending, that is its value is `true`, or ascending (`false`). - {{domxref("HTMLOListElement.start")}} - - : A `long` value reflecting the [`start`](/en-US/docs/Web/HTML/Element/ol#start) and defining the value of the first number of the first element of the list. + - : A `long` value reflecting the [`start`](/en-US/docs/Web/HTML/Reference/Elements/ol#start) and defining the value of the first number of the first element of the list. - {{domxref("HTMLOListElement.type")}} - - : A string value reflecting the [`type`](/en-US/docs/Web/HTML/Element/ol#type) and defining the kind of marker to be used to display. It can have the following values: + - : A string value reflecting the [`type`](/en-US/docs/Web/HTML/Reference/Elements/ol#type) and defining the kind of marker to be used to display. It can have the following values: - `'1'` meaning that decimal numbers are used: `1`, `2`, `3`, `4`, `5`, … - `'a'` meaning that the lowercase latin alphabet is used: `a`, `b`, `c`, `d`, `e`, … @@ -30,7 +30,7 @@ _Inherits properties from its parent, {{domxref("HTMLElement")}}._ - `'I'` meaning that the uppercase latin numerals are used: `I`, `II`, `III`, `IV`, `V`, … - {{domxref("HTMLOListElement.compact")}} {{deprecated_inline}} - - : A boolean value indicating that spacing between list items should be reduced. This property reflects the [`compact`](/en-US/docs/Web/HTML/Element/ol#compact) attribute only, it doesn't consider the {{cssxref("line-height")}} CSS property used for that behavior in modern pages. + - : A boolean value indicating that spacing between list items should be reduced. This property reflects the [`compact`](/en-US/docs/Web/HTML/Reference/Elements/ol#compact) attribute only, it doesn't consider the {{cssxref("line-height")}} CSS property used for that behavior in modern pages. ## Instance methods diff --git a/files/en-us/web/api/htmlolistelement/reversed/index.md b/files/en-us/web/api/htmlolistelement/reversed/index.md index 579b8d2c862c7f5..ed24115de61744b 100644 --- a/files/en-us/web/api/htmlolistelement/reversed/index.md +++ b/files/en-us/web/api/htmlolistelement/reversed/index.md @@ -10,7 +10,7 @@ browser-compat: api.HTMLOListElement.reversed The **`reversed`** property of the {{domxref("HTMLOListElement")}} interface indicates order of a list. -It reflects the [`reversed`](/en-US/docs/Web/HTML/Element/ol#reversed) attribute of the {{HTMLElement("ol")}} element. +It reflects the [`reversed`](/en-US/docs/Web/HTML/Reference/Elements/ol#reversed) attribute of the {{HTMLElement("ol")}} element. ## Value diff --git a/files/en-us/web/api/htmlolistelement/start/index.md b/files/en-us/web/api/htmlolistelement/start/index.md index 0a4fb653574a9af..2a3edb1e97a231d 100644 --- a/files/en-us/web/api/htmlolistelement/start/index.md +++ b/files/en-us/web/api/htmlolistelement/start/index.md @@ -10,7 +10,7 @@ browser-compat: api.HTMLOListElement.start The **`start`** property of the {{domxref("HTMLOListElement")}} interface indicates starting value of the ordered list, with default value of 1. -It reflects the [`start`](/en-US/docs/Web/HTML/Element/ol#start) attribute of the {{HTMLElement("ol")}} element. +It reflects the [`start`](/en-US/docs/Web/HTML/Reference/Elements/ol#start) attribute of the {{HTMLElement("ol")}} element. > [!NOTE] > The `start` property value is independent of the {{domxref("HTMLOListElement.type")}} property; it is always numeric, even when type is letters or Roman numerals. diff --git a/files/en-us/web/api/htmlolistelement/type/index.md b/files/en-us/web/api/htmlolistelement/type/index.md index 054cd2a39389c08..f09bf461e750f37 100644 --- a/files/en-us/web/api/htmlolistelement/type/index.md +++ b/files/en-us/web/api/htmlolistelement/type/index.md @@ -10,7 +10,7 @@ browser-compat: api.HTMLOListElement.type The **`type`** property of the {{domxref("HTMLOListElement")}} interface indicates the kind of marker to be used to display ordered list. -It reflects the [`type`](/en-US/docs/Web/HTML/Element/ol#type) attribute of the {{HTMLElement("ol")}} element. +It reflects the [`type`](/en-US/docs/Web/HTML/Reference/Elements/ol#type) attribute of the {{HTMLElement("ol")}} element. > [!NOTE] > The `type` can be defined in CSS with the {{CSSxRef("list-style-type")}} property. The `list-style-type` property provides many more values. @@ -19,7 +19,7 @@ It reflects the [`type`](/en-US/docs/Web/HTML/Element/ol#type) attribute of the A string representing the type. -Its possible values are listed in the attribute [marker types](/en-US/docs/Web/HTML/Element/ol#type) section. +Its possible values are listed in the attribute [marker types](/en-US/docs/Web/HTML/Reference/Elements/ol#type) section. ## Examples diff --git a/files/en-us/web/api/htmloptgroupelement/disabled/index.md b/files/en-us/web/api/htmloptgroupelement/disabled/index.md index e068628ff97337f..d7be337fe0474b9 100644 --- a/files/en-us/web/api/htmloptgroupelement/disabled/index.md +++ b/files/en-us/web/api/htmloptgroupelement/disabled/index.md @@ -8,7 +8,7 @@ browser-compat: api.HTMLOptGroupElement.disabled {{ APIRef("HTML DOM") }} -The **`disabled`** property of the {{domxref("HTMLOptGroupElement")}} interface is a boolean value that reflects the {{htmlelement("optgroup")}} element's [`disabled`](/en-US/docs/Web/HTML/Element/optgroup#disabled) attribute, which indicates whether the control is disabled. +The **`disabled`** property of the {{domxref("HTMLOptGroupElement")}} interface is a boolean value that reflects the {{htmlelement("optgroup")}} element's [`disabled`](/en-US/docs/Web/HTML/Reference/Elements/optgroup#disabled) attribute, which indicates whether the control is disabled. When disabled, the {{htmlelement("option")}} element descendants of the `<optgroup>` element are unusable, un-clickable, and unselectable. These disabled `<option>`s will match the {{cssxref(":disabled")}} selector, even if their `disabled` property value is false. @@ -34,5 +34,5 @@ optionGroup.disabled = true; ## See also -- HTML [`disabled`](/en-US/docs/Web/HTML/Attributes/disabled) attribute +- HTML [`disabled`](/en-US/docs/Web/HTML/Reference/Attributes/disabled) attribute - CSS {{cssxref(":disabled")}} and {{cssxref(":enabled")}} pseudoclasses diff --git a/files/en-us/web/api/htmloptgroupelement/label/index.md b/files/en-us/web/api/htmloptgroupelement/label/index.md index 24d00de7483e4b4..e6109b982001f35 100644 --- a/files/en-us/web/api/htmloptgroupelement/label/index.md +++ b/files/en-us/web/api/htmloptgroupelement/label/index.md @@ -8,7 +8,7 @@ browser-compat: api.HTMLOptGroupElement.label {{ APIRef("HTML DOM") }} -The **`label`** property of the {{domxref("HTMLOptGroupElement")}} interface is a string value that reflects the {{htmlelement("optgroup")}} element's [`label`](/en-US/docs/Web/HTML/Element/optgroup#label) attribute, which provides a textual label to the group of options. +The **`label`** property of the {{domxref("HTMLOptGroupElement")}} interface is a string value that reflects the {{htmlelement("optgroup")}} element's [`label`](/en-US/docs/Web/HTML/Reference/Elements/optgroup#label) attribute, which provides a textual label to the group of options. ## Value @@ -33,4 +33,4 @@ optionGroup.label = `${optionGroup.label} (${optionGroup.children.length})`; ## See also - {{htmlelement("optgroup")}} -- HTML [`label`](/en-US/docs/Web/HTML/Element/optgroup#label) attribute +- HTML [`label`](/en-US/docs/Web/HTML/Reference/Elements/optgroup#label) attribute diff --git a/files/en-us/web/api/htmloptionelement/defaultselected/index.md b/files/en-us/web/api/htmloptionelement/defaultselected/index.md index c4505e034fd3628..0e1270e6512e166 100644 --- a/files/en-us/web/api/htmloptionelement/defaultselected/index.md +++ b/files/en-us/web/api/htmloptionelement/defaultselected/index.md @@ -8,7 +8,7 @@ browser-compat: api.HTMLOptionElement.defaultSelected {{ APIRef("HTML DOM") }} -The **`defaultSelected`** property of the {{DOMxRef("HTMLOptionElement")}} interface specifies the default selected state of the element. This property reflects the {{htmlelement("option")}} element's [`selected`](/en-US/docs/Web/HTML/Element/option#selected) attribute. The presence of the `selected` attribute sets the `defaultSelected` property to `true`. +The **`defaultSelected`** property of the {{DOMxRef("HTMLOptionElement")}} interface specifies the default selected state of the element. This property reflects the {{htmlelement("option")}} element's [`selected`](/en-US/docs/Web/HTML/Reference/Elements/option#selected) attribute. The presence of the `selected` attribute sets the `defaultSelected` property to `true`. ## Value diff --git a/files/en-us/web/api/htmloptionelement/disabled/index.md b/files/en-us/web/api/htmloptionelement/disabled/index.md index a0ae402e03ad1ec..3f7114f53af55de 100644 --- a/files/en-us/web/api/htmloptionelement/disabled/index.md +++ b/files/en-us/web/api/htmloptionelement/disabled/index.md @@ -8,7 +8,7 @@ browser-compat: api.HTMLOptionElement.disabled {{ APIRef("HTML DOM") }} -The **`disabled`** property of the {{domxref("HTMLOptionElement")}} is a boolean value that indicates whether the {{htmlelement("option")}} element is unavailable to be selected. The property reflects the value of the [`disabled`](/en-US/docs/Web/HTML/Element/option#disabled) HTML attribute. +The **`disabled`** property of the {{domxref("HTMLOptionElement")}} is a boolean value that indicates whether the {{htmlelement("option")}} element is unavailable to be selected. The property reflects the value of the [`disabled`](/en-US/docs/Web/HTML/Reference/Elements/option#disabled) HTML attribute. The property reflects the value of the `disabled` attribute on the `<option>` element itself. If an option is disabled because it is a child of an {{HTMLElement("optgroup")}} element that is disabled, the `true` of the {{domxref("HTMLOptGroupElement.disabled")}} property is not inherited by the option itself. @@ -27,7 +27,7 @@ A boolean value. <option value="lemonade">Lemonade</option> <option value="beer">Beer</option> <option value="whisky" disabled>Whisky</option> -</option> +</select> ``` ### JavaScript diff --git a/files/en-us/web/api/htmloptionelement/index.md b/files/en-us/web/api/htmloptionelement/index.md index d631c7c0da26e48..1abda610cbeeb3f 100644 --- a/files/en-us/web/api/htmloptionelement/index.md +++ b/files/en-us/web/api/htmloptionelement/index.md @@ -21,21 +21,21 @@ The **`HTMLOptionElement`** interface represents {{HTMLElement("option")}} eleme _Inherits properties from its parent, {{domxref("HTMLElement")}}._ - {{domxref("HTMLOptionElement.defaultSelected")}} - - : Has a value of either `true` or `false` that shows the initial value of the [`selected`](/en-US/docs/Web/HTML/Element/option#selected) HTML attribute, indicating whether the option is selected by default or not. + - : Has a value of either `true` or `false` that shows the initial value of the [`selected`](/en-US/docs/Web/HTML/Reference/Elements/option#selected) HTML attribute, indicating whether the option is selected by default or not. - {{domxref("HTMLOptionElement.disabled")}} - - : Has a value of either `true` or `false` representing the value of the [`disabled`](/en-US/docs/Web/HTML/Element/option#disabled) HTML attribute, which indicates that the option is unavailable to be selected. + - : Has a value of either `true` or `false` representing the value of the [`disabled`](/en-US/docs/Web/HTML/Reference/Elements/option#disabled) HTML attribute, which indicates that the option is unavailable to be selected. - {{domxref("HTMLOptionElement.form")}} {{ReadOnlyInline}} - : A {{domxref("HTMLFormElement")}} representing the same value as the `form` of the corresponding {{HTMLElement("select")}} element, if the option is a descendant of a {{HTMLElement("select")}} element, or null if none is found. - {{domxref("HTMLOptionElement.index")}} {{ReadOnlyInline}} - : A `long` representing the position of the option within the list of options it belongs to, in tree-order. If the option is not part of a list of options, like when it is part of the {{HTMLElement("datalist")}} element, the value is `0`. - {{domxref("HTMLOptionElement.label")}} - - : A string that reflects the value of the [`label`](/en-US/docs/Web/HTML/Element/option#label) HTML attribute, which provides a label for the option. If this attribute isn't specifically set, reading it returns the element's {{domxref("HTMLOptionElement.text", "text")}} content. + - : A string that reflects the value of the [`label`](/en-US/docs/Web/HTML/Reference/Elements/option#label) HTML attribute, which provides a label for the option. If this attribute isn't specifically set, reading it returns the element's {{domxref("HTMLOptionElement.text", "text")}} content. - {{domxref("HTMLOptionElement.selected")}} - : Has a value of either `true` or `false` that indicates whether the option is currently selected. - {{domxref("HTMLOptionElement.text")}} - : A string that contains the text content of the element. - {{domxref("HTMLOptionElement.value")}} - - : A string that reflects the value of the [`value`](/en-US/docs/Web/HTML/Element/option#value) HTML attribute, if it exists; otherwise reflects value of the {{domxref("Node.textContent")}} property. + - : A string that reflects the value of the [`value`](/en-US/docs/Web/HTML/Reference/Elements/option#value) HTML attribute, if it exists; otherwise reflects value of the {{domxref("Node.textContent")}} property. ## Instance methods diff --git a/files/en-us/web/api/htmloptionelement/label/index.md b/files/en-us/web/api/htmloptionelement/label/index.md index 5f9a204f55c00df..dbeed976ee27a80 100644 --- a/files/en-us/web/api/htmloptionelement/label/index.md +++ b/files/en-us/web/api/htmloptionelement/label/index.md @@ -8,7 +8,7 @@ browser-compat: api.HTMLOptionElement.label {{ApiRef("HTML DOM")}} -The **`label`** property of the {{domxref("HTMLOptionElement")}} represents the text displayed for an option in a {{htmlelement("select")}} element or as part of a list of suggestions in a {{htmlelement("datalist")}} element. It reflects the {{htmlelement("option")}} element's [`label`](/en-US/docs/Web/HTML/Element/option#label) attribute. +The **`label`** property of the {{domxref("HTMLOptionElement")}} represents the text displayed for an option in a {{htmlelement("select")}} element or as part of a list of suggestions in a {{htmlelement("datalist")}} element. It reflects the {{htmlelement("option")}} element's [`label`](/en-US/docs/Web/HTML/Reference/Elements/option#label) attribute. If the attribute is omitted or the empty string, the `label` property returns the element's {{domxref("HTMLOptionElement.text", "text")}} content. diff --git a/files/en-us/web/api/htmloptionelement/option/index.md b/files/en-us/web/api/htmloptionelement/option/index.md index cd852d4e5bb0657..e1adbe281f5532c 100644 --- a/files/en-us/web/api/htmloptionelement/option/index.md +++ b/files/en-us/web/api/htmloptionelement/option/index.md @@ -24,18 +24,18 @@ new Option(text, value, defaultSelected, selected) ### Parameters - `text` {{optional_inline}} - - : A string representing the content of the element, i.e. the + - : A string representing the content of the element, i.e., the displayed text. If this is not specified, a default value of "" (empty string) is used. - `value` {{optional_inline}} - : A string representing the value of the - {{domxref("HTMLOptionElement")}}, i.e. the value attribute of the equivalent + {{domxref("HTMLOptionElement")}}, i.e., the value attribute of the equivalent {{htmlelement("option")}}. If this is not specified, the value of text is used as the - value, e.g. for the associated {{htmlelement("select")}} element's value when the form + value, e.g., for the associated {{htmlelement("select")}} element's value when the form is submitted to the server. - `defaultSelected` {{optional_inline}} - - : A value of either `true` or `false` that sets the [`selected`](/en-US/docs/Web/HTML/Element/option#selected) - attribute value, i.e. so that this {{htmlelement("option")}} will be the default value + - : A value of either `true` or `false` that sets the [`selected`](/en-US/docs/Web/HTML/Reference/Elements/option#selected) + attribute value, i.e., so that this {{htmlelement("option")}} will be the default value selected in the {{htmlelement("select")}} element when the page is first loaded. If this is not specified, a default value of false is used. Note that a value of true does not set the option to selected if it is not already selected. diff --git a/files/en-us/web/api/htmloptionelement/selected/index.md b/files/en-us/web/api/htmloptionelement/selected/index.md index 369e112804ac2a6..9b637b8f5df9a97 100644 --- a/files/en-us/web/api/htmloptionelement/selected/index.md +++ b/files/en-us/web/api/htmloptionelement/selected/index.md @@ -10,7 +10,7 @@ browser-compat: api.HTMLOptionElement.selected The **`selected`** property of the {{DOMxRef("HTMLOptionElement")}} interface specifies the current selectedness of the element; that is, whether the {{HTMLElement("option")}} is selected or not. -The presence of the HTML [`selected`](/en-US/docs/Web/HTML/Element/option#selected) attribute indicates the option is selected by default. It does not indicate whether this option is currently selected: if the option's state changes, the `selected` content attribute does not reflect the change; only the `HTMLOptionElement`'s `selected` IDL property is updated. The `selected` attribute is reflected by the {{domxref("HTMLOptionElement.defaultSelected", "defaultSelected")}} property. +The presence of the HTML [`selected`](/en-US/docs/Web/HTML/Reference/Elements/option#selected) attribute indicates the option is selected by default. It does not indicate whether this option is currently selected: if the option's state changes, the `selected` content attribute does not reflect the change; only the `HTMLOptionElement`'s `selected` IDL property is updated. The `selected` attribute is reflected by the {{domxref("HTMLOptionElement.defaultSelected", "defaultSelected")}} property. ## Value diff --git a/files/en-us/web/api/htmloptionelement/value/index.md b/files/en-us/web/api/htmloptionelement/value/index.md index 444341998853236..166f35809952354 100644 --- a/files/en-us/web/api/htmloptionelement/value/index.md +++ b/files/en-us/web/api/htmloptionelement/value/index.md @@ -8,7 +8,7 @@ browser-compat: api.HTMLOptionElement.value {{ APIRef("HTML DOM") }} -The **`value`** property of the {{DOMxRef("HTMLOptionElement")}} interface represents the value of the {{htmlelement("option")}} element as a string, or the empty string if no value is set. It reflects the element's [`value`](/en-US/docs/Web/HTML/Element/option#value) attribute, if present. Otherwise, it returns or sets the contents of the element, similar to the {{domxref("Node.textContent","textContent")}} property. +The **`value`** property of the {{DOMxRef("HTMLOptionElement")}} interface represents the value of the {{htmlelement("option")}} element as a string, or the empty string if no value is set. It reflects the element's [`value`](/en-US/docs/Web/HTML/Reference/Elements/option#value) attribute, if present. Otherwise, it returns or sets the contents of the element, similar to the {{domxref("Node.textContent","textContent")}} property. ## Value diff --git a/files/en-us/web/api/htmloptionscollection/index.md b/files/en-us/web/api/htmloptionscollection/index.md index 7f8b356a2f01635..f5c4b358587b53d 100644 --- a/files/en-us/web/api/htmloptionscollection/index.md +++ b/files/en-us/web/api/htmloptionscollection/index.md @@ -7,7 +7,7 @@ browser-compat: api.HTMLOptionsCollection {{ APIRef("HTML DOM") }} -The **`HTMLOptionsCollection`** interface represents a collection of [`<option>`](/en-US/docs/Web/HTML/Element/option) HTML elements (in document order) and offers methods and properties for selecting from the list as well as optionally altering its items. This object is returned only by the `options` property of [select](/en-US/docs/Web/API/HTMLSelectElement). +The **`HTMLOptionsCollection`** interface represents a collection of [`<option>`](/en-US/docs/Web/HTML/Reference/Elements/option) HTML elements (in document order) and offers methods and properties for selecting from the list as well as optionally altering its items. This object is returned only by the `options` property of [select](/en-US/docs/Web/API/HTMLSelectElement). {{InheritanceDiagram}} diff --git a/files/en-us/web/api/htmloutputelement/checkvalidity/index.md b/files/en-us/web/api/htmloutputelement/checkvalidity/index.md index 48482b831b758ef..87d9fa7ff74bea5 100644 --- a/files/en-us/web/api/htmloutputelement/checkvalidity/index.md +++ b/files/en-us/web/api/htmloutputelement/checkvalidity/index.md @@ -8,7 +8,7 @@ browser-compat: api.HTMLOutputElement.checkValidity {{APIRef("HTML DOM")}} -The **`checkValidity()`** method of the {{domxref("HTMLOutputElement")}} interface checks if the element is valid, but always returns true because {{HTMLElement("output")}} elements are never candidates for [constraint validation](/en-US/docs/Web/HTML/Constraint_validation). +The **`checkValidity()`** method of the {{domxref("HTMLOutputElement")}} interface checks if the element is valid, but always returns true because {{HTMLElement("output")}} elements are never candidates for [constraint validation](/en-US/docs/Web/HTML/Guides/Constraint_validation). ## Syntax @@ -47,4 +47,4 @@ console.log(element.checkValidity()); - {{HTMLElement("output")}} - {{HTMLElement("form")}} - [Learn: Client-side form validation](/en-US/docs/Learn_web_development/Extensions/Forms/Form_validation) -- [Guide: Constraint validation](/en-US/docs/Web/HTML/Constraint_validation) +- [Guide: Constraint validation](/en-US/docs/Web/HTML/Guides/Constraint_validation) diff --git a/files/en-us/web/api/htmloutputelement/form/index.md b/files/en-us/web/api/htmloutputelement/form/index.md index 4e0310c22264bf4..0d67eb5050a3eba 100644 --- a/files/en-us/web/api/htmloutputelement/form/index.md +++ b/files/en-us/web/api/htmloutputelement/form/index.md @@ -27,5 +27,5 @@ An {{domxref("HTMLFormElement")}} or `null`. - {{domxref("HTMLOutputElement")}} - {{domxref("HTMLFormElement")}} - {{HTMLElement("output")}} -- HTML [`form`](/en-US/docs/Web/HTML/Element/output#form) attribute +- HTML [`form`](/en-US/docs/Web/HTML/Reference/Elements/output#form) attribute - [HTML forms guide](/en-US/docs/Learn_web_development/Extensions/Forms) diff --git a/files/en-us/web/api/htmloutputelement/htmlfor/index.md b/files/en-us/web/api/htmloutputelement/htmlfor/index.md index 1ea23125045c040..4e1f36f76d077cc 100644 --- a/files/en-us/web/api/htmloutputelement/htmlfor/index.md +++ b/files/en-us/web/api/htmloutputelement/htmlfor/index.md @@ -8,7 +8,7 @@ browser-compat: api.HTMLOutputElement.htmlFor {{ APIRef("HTML DOM") }} -The **`htmlFor`** property of the {{DOMxRef("HTMLOutputElement")}} interface is a string containing a space-separated list of other elements' `id`s, indicating that those elements contributed input values to (or otherwise affected) the calculation. It reflects the [`for`](/en-US/docs/Web/HTML/Element/output#for) attribute of the {{HTMLElement("output")}} element. +The **`htmlFor`** property of the {{DOMxRef("HTMLOutputElement")}} interface is a string containing a space-separated list of other elements' `id`s, indicating that those elements contributed input values to (or otherwise affected) the calculation. It reflects the [`for`](/en-US/docs/Web/HTML/Reference/Elements/output#for) attribute of the {{HTMLElement("output")}} element. ## Value diff --git a/files/en-us/web/api/htmloutputelement/index.md b/files/en-us/web/api/htmloutputelement/index.md index bea73dcaf8b2946..8cd5129598839f4 100644 --- a/files/en-us/web/api/htmloutputelement/index.md +++ b/files/en-us/web/api/htmloutputelement/index.md @@ -18,13 +18,13 @@ _This interface also inherits properties from its parent, {{domxref("HTMLElement - {{domxref("HTMLOutputElement.defaultValue")}} - : A string representing the default value of the element, initially the empty string. - {{domxref("HTMLOutputElement.form")}} {{ReadOnlyInline}} - - : An {{domxref("HTMLFormElement")}} indicating the form associated with the control, reflecting the [`form`](/en-US/docs/Web/HTML/Element/output#form) HTML attribute if it is defined. + - : An {{domxref("HTMLFormElement")}} indicating the form associated with the control, reflecting the [`form`](/en-US/docs/Web/HTML/Reference/Elements/output#form) HTML attribute if it is defined. - {{domxref("HTMLOutputElement.htmlFor")}} {{ReadOnlyInline}} - - : A {{domxref("DOMTokenList")}} reflecting the [`for`](/en-US/docs/Web/HTML/Element/output#for) HTML attribute, containing a list of IDs of other elements in the same document that contribute to (or otherwise affect) the calculated `value`. + - : A {{domxref("DOMTokenList")}} reflecting the [`for`](/en-US/docs/Web/HTML/Reference/Elements/output#for) HTML attribute, containing a list of IDs of other elements in the same document that contribute to (or otherwise affect) the calculated `value`. - {{domxref("HTMLOutputElement.labels")}} {{ReadOnlyInline}} - : A {{domxref("NodeList")}} of {{HTMLElement("label")}} elements associated with the element. - {{domxref("HTMLOutputElement.name")}} - - : A string reflecting the [`name`](/en-US/docs/Web/HTML/Element/output#name) HTML attribute, containing the name for the control that is submitted with form data. + - : A string reflecting the [`name`](/en-US/docs/Web/HTML/Reference/Elements/output#name) HTML attribute, containing the name for the control that is submitted with form data. - {{domxref("HTMLOutputElement.type")}} {{ReadOnlyInline}} - : The string `"output"`. - {{domxref("HTMLOutputElement.validationMessage")}} {{ReadOnlyInline}} diff --git a/files/en-us/web/api/htmloutputelement/name/index.md b/files/en-us/web/api/htmloutputelement/name/index.md index 99d8a5bc5044e98..055ccaef3c93dae 100644 --- a/files/en-us/web/api/htmloutputelement/name/index.md +++ b/files/en-us/web/api/htmloutputelement/name/index.md @@ -8,7 +8,7 @@ browser-compat: api.HTMLOutputElement.name {{ApiRef("HTML DOM")}} -The **`name`** property of the {{domxref("HTMLOutputElement")}} interface indicates the name of the {{HTMLElement("output")}} element. It reflects the element's [`name`](/en-US/docs/Web/HTML/Element/output#name) attribute. +The **`name`** property of the {{domxref("HTMLOutputElement")}} interface indicates the name of the {{HTMLElement("output")}} element. It reflects the element's [`name`](/en-US/docs/Web/HTML/Reference/Elements/output#name) attribute. ## Value diff --git a/files/en-us/web/api/htmloutputelement/reportvalidity/index.md b/files/en-us/web/api/htmloutputelement/reportvalidity/index.md index aaf88d764359adc..19af7fb8ccf7ee6 100644 --- a/files/en-us/web/api/htmloutputelement/reportvalidity/index.md +++ b/files/en-us/web/api/htmloutputelement/reportvalidity/index.md @@ -8,7 +8,7 @@ browser-compat: api.HTMLOutputElement.reportValidity {{APIRef("HTML DOM")}} -The **`reportValidity()`** method of the {{domxref("HTMLOutputElement")}} interface performs the same validity checking steps as the {{domxref("HTMLOutputElement.checkValidity", "checkValidity()")}} method. It always returns true because {{HTMLElement("output")}} elements are never candidates for [constraint validation](/en-US/docs/Web/HTML/Constraint_validation). +The **`reportValidity()`** method of the {{domxref("HTMLOutputElement")}} interface performs the same validity checking steps as the {{domxref("HTMLOutputElement.checkValidity", "checkValidity()")}} method. It always returns true because {{HTMLElement("output")}} elements are never candidates for [constraint validation](/en-US/docs/Web/HTML/Guides/Constraint_validation). ## Syntax @@ -38,4 +38,4 @@ A boolean value, `true`. - {{HTMLElement("output")}} - {{HTMLElement("form")}} - [Learn: Client-side form validation](/en-US/docs/Learn_web_development/Extensions/Forms/Form_validation) -- [Guide: Constraint validation](/en-US/docs/Web/HTML/Constraint_validation) +- [Guide: Constraint validation](/en-US/docs/Web/HTML/Guides/Constraint_validation) diff --git a/files/en-us/web/api/htmloutputelement/setcustomvalidity/index.md b/files/en-us/web/api/htmloutputelement/setcustomvalidity/index.md index 0e6ca9fe9f6111a..86a181345da10f8 100644 --- a/files/en-us/web/api/htmloutputelement/setcustomvalidity/index.md +++ b/files/en-us/web/api/htmloutputelement/setcustomvalidity/index.md @@ -56,7 +56,7 @@ if (parseFloat(total.value)) { - {{domxref("HTMLOutputElement.validity")}} - {{domxref("HTMLOutputElement.checkValidity()")}} - {{domxref("HTMLOutputElement.reportValidity()")}} -- [Form validation](/en-US/docs/Web/HTML/Constraint_validation). +- [Form validation](/en-US/docs/Web/HTML/Guides/Constraint_validation). - [Learn: Client-side form validation](/en-US/docs/Learn_web_development/Extensions/Forms/Form_validation) -- [Guide: Constraint validation](/en-US/docs/Web/HTML/Constraint_validation) +- [Guide: Constraint validation](/en-US/docs/Web/HTML/Guides/Constraint_validation) - CSS {{cssxref(":valid")}} and {{cssxref(":invalid")}} pseudo-classes diff --git a/files/en-us/web/api/htmloutputelement/validationmessage/index.md b/files/en-us/web/api/htmloutputelement/validationmessage/index.md index d7f21206b4f5439..e840d497c4a5537 100644 --- a/files/en-us/web/api/htmloutputelement/validationmessage/index.md +++ b/files/en-us/web/api/htmloutputelement/validationmessage/index.md @@ -32,5 +32,5 @@ The empty string, `""`; - {{domxref("HTMLOutputElement.reportValidity()")}} - {{domxref("HTMLOutputElement.setCustomValidity()")}} - [Learn: Client-side form validation](/en-US/docs/Learn_web_development/Extensions/Forms/Form_validation) -- [Guide: Constraint validation](/en-US/docs/Web/HTML/Constraint_validation) +- [Guide: Constraint validation](/en-US/docs/Web/HTML/Guides/Constraint_validation) - CSS {{cssxref(":valid")}} and {{cssxref(":invalid")}} pseudo-classes diff --git a/files/en-us/web/api/htmloutputelement/validity/index.md b/files/en-us/web/api/htmloutputelement/validity/index.md index 49688b5ef00679b..8ff03972977b2d0 100644 --- a/files/en-us/web/api/htmloutputelement/validity/index.md +++ b/files/en-us/web/api/htmloutputelement/validity/index.md @@ -8,7 +8,7 @@ browser-compat: api.HTMLOutputElement.validity {{APIRef("HTML DOM")}} -The **`validity`** read-only property of the {{domxref("HTMLOutputElement")}} interface returns a {{domxref("ValidityState")}} object that represents the validity states this element is in. Although {{HTMLElement("output")}} elements are never candidates for [constraint validation](/en-US/docs/Web/HTML/Constraint_validation), the validity state may still be invalid if a custom validity message has been set. +The **`validity`** read-only property of the {{domxref("HTMLOutputElement")}} interface returns a {{domxref("ValidityState")}} object that represents the validity states this element is in. Although {{HTMLElement("output")}} elements are never candidates for [constraint validation](/en-US/docs/Web/HTML/Guides/Constraint_validation), the validity state may still be invalid if a custom validity message has been set. ## Value @@ -41,4 +41,4 @@ console.log(output.checkValidity()); // true - {{HTMLElement("output")}} - {{HTMLElement("form")}} - [Learn: Client-side form validation](/en-US/docs/Learn_web_development/Extensions/Forms/Form_validation) -- [Guide: Constraint validation](/en-US/docs/Web/HTML/Constraint_validation) +- [Guide: Constraint validation](/en-US/docs/Web/HTML/Guides/Constraint_validation) diff --git a/files/en-us/web/api/htmloutputelement/willvalidate/index.md b/files/en-us/web/api/htmloutputelement/willvalidate/index.md index d4693af8bcf8cd0..06fed1d6231e501 100644 --- a/files/en-us/web/api/htmloutputelement/willvalidate/index.md +++ b/files/en-us/web/api/htmloutputelement/willvalidate/index.md @@ -8,7 +8,7 @@ browser-compat: api.HTMLOutputElement.willValidate {{APIRef("HTML DOM")}} -The **`willValidate`** read-only property of the {{domxref("HTMLOutputElement")}} interface returns `false`, because {{HTMLElement("output")}} elements are not candidates for [constraint validation](/en-US/docs/Web/HTML/Constraint_validation). +The **`willValidate`** read-only property of the {{domxref("HTMLOutputElement")}} interface returns `false`, because {{HTMLElement("output")}} elements are not candidates for [constraint validation](/en-US/docs/Web/HTML/Guides/Constraint_validation). ## Value @@ -28,4 +28,4 @@ The boolean value `false`. - {{HTMLElement("output")}} - {{HTMLElement("form")}} - [Learn: Client-side form validation](/en-US/docs/Learn_web_development/Extensions/Forms/Form_validation) -- [Guide: Constraint validation](/en-US/docs/Web/HTML/Constraint_validation) +- [Guide: Constraint validation](/en-US/docs/Web/HTML/Guides/Constraint_validation) diff --git a/files/en-us/web/api/htmlparamelement/index.md b/files/en-us/web/api/htmlparamelement/index.md index d57b4e1208e7e72..f21d4b9ca52b0d1 100644 --- a/files/en-us/web/api/htmlparamelement/index.md +++ b/files/en-us/web/api/htmlparamelement/index.md @@ -18,13 +18,13 @@ The **`HTMLParamElement`** interface provides special properties (beyond those o _Inherits properties from its parent, {{domxref("HTMLElement")}}._ - {{domxref("HTMLParamElement.name")}} {{Deprecated_Inline}} - - : A string representing the name of the parameter. It reflects the [`name`](/en-US/docs/Web/HTML/Element/param#name) attribute. + - : A string representing the name of the parameter. It reflects the [`name`](/en-US/docs/Web/HTML/Reference/Elements/param#name) attribute. - {{domxref("HTMLParamElement.value")}} {{Deprecated_Inline}} - - : A string representing the value associated to the parameter. It reflects the [`value`](/en-US/docs/Web/HTML/Element/param#value) attribute. + - : A string representing the value associated to the parameter. It reflects the [`value`](/en-US/docs/Web/HTML/Reference/Elements/param#value) attribute. - {{domxref("HTMLParamElement.type")}} {{Deprecated_Inline}} - - : A string containing the type of the parameter when `valueType` has the `"ref"` value. It reflects the [`type`](/en-US/docs/Web/HTML/Element/param#type) attribute. + - : A string containing the type of the parameter when `valueType` has the `"ref"` value. It reflects the [`type`](/en-US/docs/Web/HTML/Reference/Elements/param#type) attribute. - {{domxref("HTMLParamElement.valueType")}} {{Deprecated_Inline}} - - : A string containing the type of the `value`. It reflects the [valuetype](/en-US/docs/Web/HTML/Element/param#valuetype) attribute and has one of the values: `"data"`, `"ref"`, or `"object"`. + - : A string containing the type of the `value`. It reflects the [valuetype](/en-US/docs/Web/HTML/Reference/Elements/param#valuetype) attribute and has one of the values: `"data"`, `"ref"`, or `"object"`. ## Instance methods diff --git a/files/en-us/web/api/htmlpreelement/index.md b/files/en-us/web/api/htmlpreelement/index.md index 0a04f8265456ae1..e7878cc2962c781 100644 --- a/files/en-us/web/api/htmlpreelement/index.md +++ b/files/en-us/web/api/htmlpreelement/index.md @@ -16,7 +16,7 @@ The **`HTMLPreElement`** interface exposes specific properties and methods (beyo _Inherits properties from its parent, {{domxref("HTMLElement")}}._ - {{domxref("HTMLPreElement.width")}} {{deprecated_inline}} - - : A `long` value reflecting the obsolete [`width`](/en-US/docs/Web/HTML/Element/pre#width) attribute, containing a fixed-size length for the {{HTMLElement("pre")}} element. + - : A `long` value reflecting the obsolete [`width`](/en-US/docs/Web/HTML/Reference/Elements/pre#width) attribute, containing a fixed-size length for the {{HTMLElement("pre")}} element. ## Instance methods diff --git a/files/en-us/web/api/htmlquoteelement/cite/index.md b/files/en-us/web/api/htmlquoteelement/cite/index.md index 2cca17d55ff25ca..b9d6821d42be5d3 100644 --- a/files/en-us/web/api/htmlquoteelement/cite/index.md +++ b/files/en-us/web/api/htmlquoteelement/cite/index.md @@ -8,7 +8,7 @@ browser-compat: api.HTMLQuoteElement.cite {{ApiRef("HTML DOM")}} -The **`cite`** property of the {{domxref("HTMLQuoteElement")}} interface indicates the URL for the source of the quotation. It reflects the {{HTMLElement("q")}} element's [`cite`](/en-US/docs/Web/HTML/Element/q#cite) attribute. +The **`cite`** property of the {{domxref("HTMLQuoteElement")}} interface indicates the URL for the source of the quotation. It reflects the {{HTMLElement("q")}} element's [`cite`](/en-US/docs/Web/HTML/Reference/Elements/q#cite) attribute. ## Value diff --git a/files/en-us/web/api/htmlquoteelement/index.md b/files/en-us/web/api/htmlquoteelement/index.md index 58f5b33f84b990c..2e29b8d355c9c37 100644 --- a/files/en-us/web/api/htmlquoteelement/index.md +++ b/files/en-us/web/api/htmlquoteelement/index.md @@ -16,7 +16,7 @@ The **`HTMLQuoteElement`** interface provides special properties and methods (be _Inherits properties from its parent, {{domxref("HTMLElement")}}._ - {{domxref("HTMLQuoteElement.cite")}} - - : A string reflecting the [`cite`](/en-US/docs/Web/HTML/Element/blockquote#cite) HTML attribute, containing a URL for the source of the quotation. + - : A string reflecting the [`cite`](/en-US/docs/Web/HTML/Reference/Elements/blockquote#cite) HTML attribute, containing a URL for the source of the quotation. ## Instance methods diff --git a/files/en-us/web/api/htmlscriptelement/attributionsrc/index.md b/files/en-us/web/api/htmlscriptelement/attributionsrc/index.md index b8b7e15b19b0053..f278d3bc17e298d 100644 --- a/files/en-us/web/api/htmlscriptelement/attributionsrc/index.md +++ b/files/en-us/web/api/htmlscriptelement/attributionsrc/index.md @@ -10,7 +10,7 @@ browser-compat: api.HTMLScriptElement.attributionSrc {{APIRef("Attribution Reporting API")}}{{securecontext_header}}{{SeeCompatTable}} -The **`attributionSrc`** property of the {{domxref("HTMLScriptElement")}} interface gets and sets the [`attributionsrc`](/en-US/docs/Web/HTML/Element/script#attributionsrc) attribute on an {{htmlelement("script")}} element programmatically, reflecting the value of that attribute. `attributionsrc` specifies that you want the browser to send an {{httpheader("Attribution-Reporting-Eligible")}} header along with the script resource request. +The **`attributionSrc`** property of the {{domxref("HTMLScriptElement")}} interface gets and sets the [`attributionsrc`](/en-US/docs/Web/HTML/Reference/Elements/script#attributionsrc) attribute on a {{htmlelement("script")}} element programmatically, reflecting the value of that attribute. `attributionsrc` specifies that you want the browser to send an {{httpheader("Attribution-Reporting-Eligible")}} header along with the script resource request. On the server-side this is used to trigger sending an {{httpheader("Attribution-Reporting-Register-Source")}} or {{httpheader("Attribution-Reporting-Register-Trigger")}} header in the response, to register a JavaScript-based [attribution source](/en-US/docs/Web/API/Attribution_Reporting_API/Registering_sources#javascript-based_event_sources) or [attribution trigger](/en-US/docs/Web/API/Attribution_Reporting_API/Registering_triggers#javascript-based_attribution_triggers), respectively. Which response header should be sent back depends on the value of the `Attribution-Reporting-Eligible` header that triggered the registration. @@ -23,7 +23,7 @@ See the [Attribution Reporting API](/en-US/docs/Web/API/Attribution_Reporting_AP A string. There are two versions of this property that you can get and set: -- Empty string, i.e. `scriptElem.attributionSrc=""`. This specifies that you want the {{httpheader("Attribution-Reporting-Eligible")}} header sent to the same server as the `src` attribute points to. This is fine when you are handling the attribution source or trigger registration on the same server. When registering an attribution trigger this property is optional, and an empty string value will be used if it is omitted. +- Empty string, i.e., `scriptElem.attributionSrc=""`. This specifies that you want the {{httpheader("Attribution-Reporting-Eligible")}} header sent to the same server as the `src` attribute points to. This is fine when you are handling the attribution source or trigger registration on the same server. When registering an attribution trigger this property is optional, and an empty string value will be used if it is omitted. - Value containing one or more URLs, for example: ```js diff --git a/files/en-us/web/api/htmlscriptelement/crossorigin/index.md b/files/en-us/web/api/htmlscriptelement/crossorigin/index.md index 386cd205cfbc2c7..bd3644ded58e47a 100644 --- a/files/en-us/web/api/htmlscriptelement/crossorigin/index.md +++ b/files/en-us/web/api/htmlscriptelement/crossorigin/index.md @@ -8,7 +8,7 @@ browser-compat: api.HTMLScriptElement.crossOrigin {{APIRef("HTML DOM")}} -The **`crossOrigin`** property of the {{domxref("HTMLScriptElement")}} interface reflects the {{Glossary("CORS", "Cross-Origin Resource Sharing")}} settings for the script element. For classic scripts from other [origins](/en-US/docs/Glossary/Origin), this controls if full error information will be exposed. For module scripts, it controls the script itself and any script it imports. See [CORS settings attributes](/en-US/docs/Web/HTML/Attributes/crossorigin) for details. +The **`crossOrigin`** property of the {{domxref("HTMLScriptElement")}} interface reflects the {{Glossary("CORS", "Cross-Origin Resource Sharing")}} settings for the script element. For classic scripts from other [origins](/en-US/docs/Glossary/Origin), this controls if full error information will be exposed. For module scripts, it controls the script itself and any script it imports. See [CORS settings attributes](/en-US/docs/Web/HTML/Reference/Attributes/crossorigin) for details. ## Value diff --git a/files/en-us/web/api/htmlscriptelement/fetchpriority/index.md b/files/en-us/web/api/htmlscriptelement/fetchpriority/index.md index e0fb5f0635366e2..c5fc8c0b7de82fb 100644 --- a/files/en-us/web/api/htmlscriptelement/fetchpriority/index.md +++ b/files/en-us/web/api/htmlscriptelement/fetchpriority/index.md @@ -9,13 +9,13 @@ browser-compat: api.HTMLScriptElement.fetchPriority {{APIRef("HTML DOM")}} The **`fetchPriority`** property of the {{domxref("HTMLScriptElement")}} interface represents a hint to the browser indicating how it should prioritize fetching an external script relative to other external scripts. -It reflects the [`fetchpriority`](/en-US/docs/Web/HTML/Element/script#fetchpriority) attribute of the {{HTMLElement("script")}} element. +It reflects the [`fetchpriority`](/en-US/docs/Web/HTML/Reference/Elements/script#fetchpriority) attribute of the {{HTMLElement("script")}} element. The property allows a developer to signal that fetching a particular script early or late in the loading process has more or less impact on user experience than a browser can reasonably infer when assigning an internal priority. This in turn allows the browser to increase or decrease the priority, and potentially load the script earlier or later than it would otherwise. The property should be used sparingly, as excessive or incorrect prioritization can degrade performance. -The fetch priority allows you to decrease the priority of late-body scripts, or to increase the priority of `async` scripts without having to use [preloading](/en-US/docs/Web/HTML/Attributes/rel/preload). +The fetch priority allows you to decrease the priority of late-body scripts, or to increase the priority of `async` scripts without having to use [preloading](/en-US/docs/Web/HTML/Reference/Attributes/rel/preload). When early loading of a script is important, the priority can be used to complement preloading, boosting the priority ahead of less-impactful resources that have a higher default priority. Note that both the internal priority of any fetch operation, and the impact of `fetchPriority` on the priority, are entirely browser dependent. diff --git a/files/en-us/web/api/htmlscriptelement/index.md b/files/en-us/web/api/htmlscriptelement/index.md index 96954acebe8ea16..9c2f760de2b57f5 100644 --- a/files/en-us/web/api/htmlscriptelement/index.md +++ b/files/en-us/web/api/htmlscriptelement/index.md @@ -9,7 +9,7 @@ browser-compat: api.HTMLScriptElement HTML {{HTMLElement("script")}} elements expose the **`HTMLScriptElement`** interface, which provides special properties and methods for manipulating the behavior and execution of `<script>` elements (beyond the inherited {{domxref("HTMLElement")}} interface). -JavaScript files should be served with the `text/javascript` [MIME type](/en-US/docs/Web/HTTP/MIME_types), but browsers are lenient and block them only if the script is served with an image type (`image/*`), video type (`video/*`), audio type (`audio/*`), or `text/csv`. If the script is blocked, its element receives an {{domxref("HTMLElement/error_event", "error")}} event; otherwise, it receives a {{domxref("Window/load_event", "load")}} event. +JavaScript files should be served with the `text/javascript` [MIME type](/en-US/docs/Web/HTTP/Guides/MIME_types), but browsers are lenient and block them only if the script is served with an image type (`image/*`), video type (`video/*`), audio type (`audio/*`), or `text/csv`. If the script is blocked, its element receives an {{domxref("HTMLElement/error_event", "error")}} event; otherwise, it receives a {{domxref("Window/load_event", "load")}} event. {{InheritanceDiagram}} @@ -18,15 +18,15 @@ JavaScript files should be served with the `text/javascript` [MIME type](/en-US/ _Inherits properties from its parent, {{domxref("HTMLElement")}}._ - {{domxref("HTMLScriptElement.attributionSrc")}} {{securecontext_inline}} {{experimental_inline}} - - : Gets and sets the [`attributionsrc`](/en-US/docs/Web/HTML/Element/script#attributionsrc) attribute on an {{htmlelement("script")}} element programmatically, reflecting the value of that attribute. `attributionsrc` specifies that you want the browser to send an {{httpheader("Attribution-Reporting-Eligible")}} header along with the script resource request. On the server-side this is used to trigger sending an {{httpheader("Attribution-Reporting-Register-Source")}} or {{httpheader("Attribution-Reporting-Register-Trigger")}} header in the response, to register a JavaScript-based [attribution source](/en-US/docs/Web/API/Attribution_Reporting_API/Registering_sources#javascript-based_event_sources) or [attribution trigger](/en-US/docs/Web/API/Attribution_Reporting_API/Registering_triggers#javascript-based_attribution_triggers), respectively. + - : Gets and sets the [`attributionsrc`](/en-US/docs/Web/HTML/Reference/Elements/script#attributionsrc) attribute on a {{htmlelement("script")}} element programmatically, reflecting the value of that attribute. `attributionsrc` specifies that you want the browser to send an {{httpheader("Attribution-Reporting-Eligible")}} header along with the script resource request. On the server-side this is used to trigger sending an {{httpheader("Attribution-Reporting-Register-Source")}} or {{httpheader("Attribution-Reporting-Register-Trigger")}} header in the response, to register a JavaScript-based [attribution source](/en-US/docs/Web/API/Attribution_Reporting_API/Registering_sources#javascript-based_event_sources) or [attribution trigger](/en-US/docs/Web/API/Attribution_Reporting_API/Registering_triggers#javascript-based_attribution_triggers), respectively. - {{domxref("HTMLScriptElement.async")}} - : A boolean value that controls how the script should be executed. For classic scripts, if the `async` property is set to `true`, the external script will be fetched in parallel to parsing and evaluated as soon as it is available. For [module scripts](/en-US/docs/Web/JavaScript/Guide/Modules), if the `async` property is set to `true`, the script and all their dependencies will be fetched in parallel to parsing and evaluated as soon as they are available. - {{domxref("HTMLScriptElement.blocking")}} - : A string indicating that certain operations should be blocked on the fetching of the script. It reflects the `blocking` attribute of the {{HTMLElement("script")}} element. - `HTMLScriptElement.charset` {{deprecated_inline}} - - : A string representing the character encoding of an external script. It reflects the [`charset`](/en-US/docs/Web/HTML/Element/script#charset) attribute. + - : A string representing the character encoding of an external script. It reflects the [`charset`](/en-US/docs/Web/HTML/Reference/Elements/script#charset) attribute. - {{domxref("HTMLScriptElement.crossOrigin")}} - - : A string reflecting the [CORS setting](/en-US/docs/Web/HTML/Attributes/crossorigin) for the script element. For classic scripts from other [origins](/en-US/docs/Glossary/Origin), this controls if error information will be exposed. + - : A string reflecting the [CORS setting](/en-US/docs/Web/HTML/Reference/Attributes/crossorigin) for the script element. For classic scripts from other [origins](/en-US/docs/Glossary/Origin), this controls if error information will be exposed. - {{domxref("HTMLScriptElement.defer")}} - : A boolean value that controls how the script should be executed. For classic scripts, if the `defer` property is set to `true`, the external script will be executed after the document has been parsed, but before firing {{domxref("Document/DOMContentLoaded_event", "DOMContentLoaded")}} event. For [module scripts](/en-US/docs/Web/JavaScript/Guide/Modules), the `defer` property has no effect. - `HTMLScriptElement.event` {{deprecated_inline}} @@ -38,7 +38,7 @@ _Inherits properties from its parent, {{domxref("HTMLElement")}}._ - {{domxref("HTMLScriptElement.noModule")}} - : A boolean value that if true, stops the script's execution in browsers that support [ES modules](/en-US/docs/Web/JavaScript/Guide/Modules) — used to run fallback scripts in older browsers that do _not_ support JavaScript modules. - {{domxref("HTMLScriptElement.referrerPolicy")}} - - : A string that reflects the [`referrerPolicy`](/en-US/docs/Web/HTML/Element/script#referrerpolicy) HTML attribute indicating which referrer to use when fetching the script, and fetches done by that script. + - : A string that reflects the [`referrerPolicy`](/en-US/docs/Web/HTML/Reference/Elements/script#referrerpolicy) HTML attribute indicating which referrer to use when fetching the script, and fetches done by that script. - {{domxref("HTMLScriptElement.src")}} - : A string representing the URL of an external script; this can be used as an alternative to embedding a script directly within a document. It reflects the `src` attribute of the {{HTMLElement("script")}} element. - {{domxref("HTMLScriptElement.text")}} diff --git a/files/en-us/web/api/htmlscriptelement/referrerpolicy/index.md b/files/en-us/web/api/htmlscriptelement/referrerpolicy/index.md index 849bf3d51b9ad5e..9460af9c9f200f4 100644 --- a/files/en-us/web/api/htmlscriptelement/referrerpolicy/index.md +++ b/files/en-us/web/api/htmlscriptelement/referrerpolicy/index.md @@ -10,7 +10,7 @@ browser-compat: api.HTMLScriptElement.referrerPolicy The **`referrerPolicy`** property of the {{domxref("HTMLScriptElement")}} interface reflects the HTML -[`referrerpolicy`](/en-US/docs/Web/HTML/Element/script#referrerpolicy) of the {{HTMLElement("script")}} element, which defines how the referrer is set when fetching the script and any scripts it imports. +[`referrerpolicy`](/en-US/docs/Web/HTML/Reference/Elements/script#referrerpolicy) of the {{HTMLElement("script")}} element, which defines how the referrer is set when fetching the script and any scripts it imports. ## Value @@ -22,7 +22,7 @@ A string; one of the following: - `no-referrer-when-downgrade` - : The URL is sent as a referrer when the protocol security level stays the same (e.g.HTTP→HTTP, - HTTPS→HTTPS), but isn't sent to a less secure destination (e.g. HTTPS→HTTP). + HTTPS→HTTPS), but isn't sent to a less secure destination (e.g., HTTPS→HTTP). - `origin` - : Only send the origin of the document as the referrer in all cases. The document `https://example.com/page.html` will send the referrer @@ -35,12 +35,12 @@ A string; one of the following: cross-origin requests will contain no referrer information. - `strict-origin` - : Only send the origin of the document as the referrer when the protocol security - level stays the same (e.g. HTTPS→HTTPS), but don't send it to a less secure - destination (e.g. HTTPS→HTTP). + level stays the same (e.g., HTTPS→HTTPS), but don't send it to a less secure + destination (e.g., HTTPS→HTTP). - `strict-origin-when-cross-origin` (default) - : This is the user agent's default behavior if no policy is specified. Send a full URL when performing a same-origin request, only send the origin when the - protocol security level stays the same (e.g. HTTPS→HTTPS), and send no header to a - less secure destination (e.g. HTTPS→HTTP). + protocol security level stays the same (e.g., HTTPS→HTTPS), and send no header to a + less secure destination (e.g., HTTPS→HTTP). - `unsafe-url` - : Send a full URL when performing a same-origin or cross-origin request. This policy will leak origins and paths from TLS-protected resources to insecure origins. @@ -51,7 +51,7 @@ A string; one of the following: > value, and a fallback value if `referrerpolicy` is not supported. If > `referrerpolicy` is not explicitly specified on the > `<script>` element, it will adopt a higher-level referrer policy, -> i.e. one set on the whole document or domain. If a higher-level policy is not +> i.e., one set on the whole document or domain. If a higher-level policy is not > available, the empty string is treated as being equivalent to > `no-referrer-when-downgrade`. diff --git a/files/en-us/web/api/htmlscriptelement/supports_static/index.md b/files/en-us/web/api/htmlscriptelement/supports_static/index.md index 0c5805148bc659a..c9d69a91121fd94 100644 --- a/files/en-us/web/api/htmlscriptelement/supports_static/index.md +++ b/files/en-us/web/api/htmlscriptelement/supports_static/index.md @@ -31,7 +31,7 @@ HTMLScriptElement.supports(type) - `"module"` - : Test if [module scripts](/en-US/docs/Web/JavaScript/Guide/Modules) are supported. - `"importmap"` - - : Test if [import maps](/en-US/docs/Web/HTML/Element/script/type/importmap) are supported. + - : Test if [import maps](/en-US/docs/Web/HTML/Reference/Elements/script/type/importmap) are supported. - `"speculationrules"` - : Test if [speculation rules](/en-US/docs/Web/API/Speculation_Rules_API) are supported and enabled. diff --git a/files/en-us/web/api/htmlscriptelement/type/index.md b/files/en-us/web/api/htmlscriptelement/type/index.md index da44d61fa351ffe..ee8936822c23284 100644 --- a/files/en-us/web/api/htmlscriptelement/type/index.md +++ b/files/en-us/web/api/htmlscriptelement/type/index.md @@ -27,7 +27,7 @@ A string. The value of this property can be one of the following: - **Any other value** - : The embedded content is treated as a data block, and won't be processed by the browser. -For more information, please refer to the [`type`](/en-US/docs/Web/HTML/Element/script/type) attribute of the {{HTMLElement("script")}} element. +For more information, please refer to the [`type`](/en-US/docs/Web/HTML/Reference/Elements/script/type) attribute of the {{HTMLElement("script")}} element. ## Examples diff --git a/files/en-us/web/api/htmlselectedcontentelement/index.md b/files/en-us/web/api/htmlselectedcontentelement/index.md new file mode 100644 index 000000000000000..f3e7dbde7586480 --- /dev/null +++ b/files/en-us/web/api/htmlselectedcontentelement/index.md @@ -0,0 +1,32 @@ +--- +title: HTMLSelectedContentElement +slug: Web/API/HTMLSelectedContentElement +page-type: web-api-interface +browser-compat: api.HTMLSelectedContentElement +--- + +{{APIRef("HTML DOM")}} + +The **`HTMLSelectedContentElement`** interface represents a {{HTMLElement("selectedcontent")}} element in the [DOM](/en-US/docs/Web/API/Document_Object_Model). + +{{InheritanceDiagram}} + +## Instance properties + +_This interface has no properties, but inherits properties from: {{DOMxRef("HTMLElement")}}._ + +## Instance methods + +_This interface has no methods, but inherits methods from: {{DOMxRef("HTMLElement")}}._ + +## Specifications + +Not currently part of a specification. See https://github.com/whatwg/html/pull/10633 for the relevant specification PR. + +## Browser compatibility + +{{Compat}} + +## See also + +- The HTML element implementing this interface: {{HTMLElement("selectedcontent")}}. diff --git a/files/en-us/web/api/htmlselectelement/autocomplete/index.md b/files/en-us/web/api/htmlselectelement/autocomplete/index.md index b0d23d33d393b2e..2752fea47b5eff9 100644 --- a/files/en-us/web/api/htmlselectelement/autocomplete/index.md +++ b/files/en-us/web/api/htmlselectelement/autocomplete/index.md @@ -8,11 +8,11 @@ browser-compat: api.HTMLSelectElement.autocomplete {{ APIRef("HTML DOM") }} -The **`autocomplete`** property of the {{DOMxRef("HTMLSelectElement")}} interface indicates whether the value of the control can be automatically completed by the browser. It reflects the `<select>` element's [`autocomplete`](/en-US/docs/Web/HTML/Element/select#autocomplete) attribute. +The **`autocomplete`** property of the {{DOMxRef("HTMLSelectElement")}} interface indicates whether the value of the control can be automatically completed by the browser. It reflects the `<select>` element's [`autocomplete`](/en-US/docs/Web/HTML/Reference/Elements/select#autocomplete) attribute. ## Value -A string representing the value of the `autocomplete` attribute (`"on"`, `"off"`, or a [`<token-list>`](/en-US/docs/Web/HTML/Attributes/autocomplete#token_list_tokens)) or the empty string (`""`) if unspecified. +A string representing the value of the `autocomplete` attribute (`"on"`, `"off"`, or a [`<token-list>`](/en-US/docs/Web/HTML/Reference/Attributes/autocomplete#token_list_tokens)) or the empty string (`""`) if unspecified. ## Examples @@ -33,6 +33,6 @@ console.log(textArea.autocomplete); - {{HTMLElement("select")}} - {{HTMLElement("option")}} -- HTML [`autocomplete`](/en-US/docs/Web/HTML/Attributes/autocomplete) attribute -- ARIA [`aria-autocomplete`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-autocomplete) attribute +- HTML [`autocomplete`](/en-US/docs/Web/HTML/Reference/Attributes/autocomplete) attribute +- ARIA [`aria-autocomplete`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-autocomplete) attribute - [Turning off autocompletion](/en-US/docs/Web/Security/Practical_implementation_guides/Turning_off_form_autocompletion) diff --git a/files/en-us/web/api/htmlselectelement/checkvalidity/index.md b/files/en-us/web/api/htmlselectelement/checkvalidity/index.md index 698507c890333fe..26079eb7b27e245 100644 --- a/files/en-us/web/api/htmlselectelement/checkvalidity/index.md +++ b/files/en-us/web/api/htmlselectelement/checkvalidity/index.md @@ -8,7 +8,7 @@ browser-compat: api.HTMLSelectElement.checkValidity {{APIRef("HTML DOM")}} -The **`checkValidity()`** method of the {{domxref("HTMLSelectElement")}} interface returns a boolean value which indicates if the element meets any [constraint validation](/en-US/docs/Web/HTML/Constraint_validation) rules applied to it. If false, the method also fires an {{domxref("HTMLElement/invalid_event", "invalid")}} event on the element. Because there's no default browser behavior for `checkValidity()`, canceling this `invalid` event has no effect. +The **`checkValidity()`** method of the {{domxref("HTMLSelectElement")}} interface returns a boolean value which indicates if the element meets any [constraint validation](/en-US/docs/Web/HTML/Guides/Constraint_validation) rules applied to it. If false, the method also fires an {{domxref("HTMLElement/invalid_event", "invalid")}} event on the element. Because there's no default browser behavior for `checkValidity()`, canceling this `invalid` event has no effect. > [!NOTE] > An HTML {{htmlelement("select")}} element with a non-null {{domxref("HTMLSelectElement.validationMessage", "validationMessage")}} is considered invalid, will match the CSS {{cssxref(":invalid")}} pseudo-class, and will cause `checkValidity()` to return false. Use the {{domxref("HTMLSelectElement.setCustomValidity()")}} method to set the {{domxref("HTMLSelectElement.validationMessage")}} to the empty string to set the {{domxref("HTMLSelectElement.validity", "validity")}} state to be valid. @@ -50,5 +50,5 @@ console.log(element.checkValidity()); - {{HTMLElement("textarea")}} - {{HTMLElement("form")}} - [Learn: Client-side form validation](/en-US/docs/Learn_web_development/Extensions/Forms/Form_validation) -- [Guide: Constraint validation](/en-US/docs/Web/HTML/Constraint_validation) +- [Guide: Constraint validation](/en-US/docs/Web/HTML/Guides/Constraint_validation) - CSS {{cssxref(":valid")}} and {{cssxref(":invalid")}} pseudo-classes diff --git a/files/en-us/web/api/htmlselectelement/disabled/index.md b/files/en-us/web/api/htmlselectelement/disabled/index.md index 064b02b13ed5e4d..546fbb79ce7df42 100644 --- a/files/en-us/web/api/htmlselectelement/disabled/index.md +++ b/files/en-us/web/api/htmlselectelement/disabled/index.md @@ -9,7 +9,7 @@ browser-compat: api.HTMLSelectElement.disabled {{ APIRef("HTML DOM") }} The **`HTMLSelectElement.disabled`** property is a boolean value that reflects the -[`disabled`](/en-US/docs/Web/HTML/Element/select#disabled) +[`disabled`](/en-US/docs/Web/HTML/Reference/Elements/select#disabled) HTML attribute, which indicates whether the control is disabled. If it is disabled, it does not accept clicks. A disabled element is unusable and un-clickable. diff --git a/files/en-us/web/api/htmlselectelement/form/index.md b/files/en-us/web/api/htmlselectelement/form/index.md index 46495f414fb1e5c..6e4d4fbaa432db3 100644 --- a/files/en-us/web/api/htmlselectelement/form/index.md +++ b/files/en-us/web/api/htmlselectelement/form/index.md @@ -27,5 +27,5 @@ An {{domxref("HTMLFormElement")}} or `null`. - {{domxref("HTMLSelectElement")}} - {{domxref("HTMLFormElement")}} - {{HTMLElement("select")}} -- HTML [`form`](/en-US/docs/Web/HTML/Element/select#form) attribute +- HTML [`form`](/en-US/docs/Web/HTML/Reference/Elements/select#form) attribute - [HTML forms guide](/en-US/docs/Learn_web_development/Extensions/Forms) diff --git a/files/en-us/web/api/htmlselectelement/index.md b/files/en-us/web/api/htmlselectelement/index.md index c749a10dc0f3f3e..4b03bf8736ce7b8 100644 --- a/files/en-us/web/api/htmlselectelement/index.md +++ b/files/en-us/web/api/htmlselectelement/index.md @@ -15,8 +15,10 @@ The **`HTMLSelectElement`** interface represents a {{HTMLElement("select")}} HTM _This interface inherits the properties of {{domxref("HTMLElement")}}, and of {{domxref("Element")}} and {{domxref("Node")}}._ +- {{domxref("HTMLSelectElement.autocomplete")}} + - : A string value reflecting the [`autocomplete`](/en-US/docs/Web/HTML/Reference/Elements/select#autocomplete), which indicates whether the value of the control can be automatically completed by the browser. - {{domxref("HTMLSelectElement.disabled")}} - - : A boolean value reflecting the [`disabled`](/en-US/docs/Web/HTML/Element/select#disabled) HTML attribute, which indicates whether the control is disabled. If it is disabled, it does not accept clicks. + - : A boolean value reflecting the [`disabled`](/en-US/docs/Web/HTML/Reference/Elements/select#disabled) HTML attribute, which indicates whether the control is disabled. If it is disabled, it does not accept clicks. - {{domxref("HTMLSelectElement.form")}} {{ReadOnlyInline}} - : An {{domxref("HTMLFormElement")}} referencing the form that this element is associated with. If the element is not associated with of a {{HTMLElement("form")}} element, then it returns `null`. - {{domxref("HTMLSelectElement.labels")}} {{ReadOnlyInline}} @@ -24,19 +26,19 @@ _This interface inherits the properties of {{domxref("HTMLElement")}}, and of {{ - {{domxref("HTMLSelectElement.length")}} - : An `unsigned long` The number of {{HTMLElement("option")}} elements in this `select` element. - {{domxref("HTMLSelectElement.multiple")}} - - : A boolean value reflecting the [`multiple`](/en-US/docs/Web/HTML/Element/select#multiple) HTML attribute, which indicates whether multiple items can be selected. + - : A boolean value reflecting the [`multiple`](/en-US/docs/Web/HTML/Reference/Elements/select#multiple) HTML attribute, which indicates whether multiple items can be selected. - {{domxref("HTMLSelectElement.name")}} - - : A string reflecting the [`name`](/en-US/docs/Web/HTML/Element/select#name) HTML attribute, containing the name of this control used by servers and DOM search functions. + - : A string reflecting the [`name`](/en-US/docs/Web/HTML/Reference/Elements/select#name) HTML attribute, containing the name of this control used by servers and DOM search functions. - {{domxref("HTMLSelectElement.options")}} {{ReadOnlyInline}} - : An {{domxref("HTMLOptionsCollection")}} representing the set of {{HTMLElement("option")}} ({{domxref("HTMLOptionElement")}}) elements contained by this element. - {{domxref("HTMLSelectElement.required")}} - - : A boolean value reflecting the [`required`](/en-US/docs/Web/HTML/Element/select#required) HTML attribute, which indicates whether the user is required to select a value before submitting the form. + - : A boolean value reflecting the [`required`](/en-US/docs/Web/HTML/Reference/Elements/select#required) HTML attribute, which indicates whether the user is required to select a value before submitting the form. - {{domxref("HTMLSelectElement.selectedIndex")}} - : A `long` reflecting the index of the first selected {{HTMLElement("option")}} element. The value `-1` indicates no element is selected. - {{domxref("HTMLSelectElement.selectedOptions")}} {{ReadOnlyInline}} - : An {{domxref("HTMLCollection")}} representing the set of {{HTMLElement("option")}} elements that are selected. - {{domxref("HTMLSelectElement.size")}} - - : A `long` reflecting the [`size`](/en-US/docs/Web/HTML/Element/select#size) HTML attribute, which contains the number of visible items in the control. The default is 1, unless `multiple` is `true`, in which case it is 4. + - : A `long` reflecting the [`size`](/en-US/docs/Web/HTML/Reference/Elements/select#size) HTML attribute, which contains the number of visible items in the control. The default is 1, unless `multiple` is `true`, in which case it is 4. - {{domxref("HTMLSelectElement.type")}} {{ReadOnlyInline}} - : A string representing the form control's type. When `multiple` is `true`, it returns `"select-multiple"`; otherwise, it returns `"select-one"`. - {{domxref("HTMLSelectElement.validationMessage")}} {{ReadOnlyInline}} diff --git a/files/en-us/web/api/htmlselectelement/multiple/index.md b/files/en-us/web/api/htmlselectelement/multiple/index.md index 4c74063a107e65d..ccd5450dc07674c 100644 --- a/files/en-us/web/api/htmlselectelement/multiple/index.md +++ b/files/en-us/web/api/htmlselectelement/multiple/index.md @@ -8,7 +8,7 @@ browser-compat: api.HTMLSelectElement.multiple {{ APIRef("HTML DOM") }} -The **`multiple`** property of the {{DOMxRef("HTMLSelectElement")}} interface specifies that the user may select more than one option from the list of options. It reflects the {{htmlelement("select")}} element's [`multiple`](/en-US/docs/Web/HTML/Element/select#multiple) attribute. +The **`multiple`** property of the {{DOMxRef("HTMLSelectElement")}} interface specifies that the user may select more than one option from the list of options. It reflects the {{htmlelement("select")}} element's [`multiple`](/en-US/docs/Web/HTML/Reference/Elements/select#multiple) attribute. ## Value diff --git a/files/en-us/web/api/htmlselectelement/name/index.md b/files/en-us/web/api/htmlselectelement/name/index.md index 6dac3baab7dd495..f121c6930336e9a 100644 --- a/files/en-us/web/api/htmlselectelement/name/index.md +++ b/files/en-us/web/api/htmlselectelement/name/index.md @@ -8,7 +8,7 @@ browser-compat: api.HTMLSelectElement.name {{ApiRef("HTML DOM")}} -The **`name`** property of the {{domxref("HTMLSelectElement")}} interface indicates the name of the {{HTMLElement("select")}} element. It reflects the element's [`name`](/en-US/docs/Web/HTML/Element/select#name) attribute. +The **`name`** property of the {{domxref("HTMLSelectElement")}} interface indicates the name of the {{HTMLElement("select")}} element. It reflects the element's [`name`](/en-US/docs/Web/HTML/Reference/Elements/select#name) attribute. ## Value diff --git a/files/en-us/web/api/htmlselectelement/reportvalidity/index.md b/files/en-us/web/api/htmlselectelement/reportvalidity/index.md index 41fc6d0e70cf97a..1d036dc30126626 100644 --- a/files/en-us/web/api/htmlselectelement/reportvalidity/index.md +++ b/files/en-us/web/api/htmlselectelement/reportvalidity/index.md @@ -38,5 +38,5 @@ Returns `true` if the element's value has no validity problems; otherwise, retur - {{HTMLElement("select")}} - {{HTMLElement("form")}} - [Learn: Client-side form validation](/en-US/docs/Learn_web_development/Extensions/Forms/Form_validation) -- [Guide: Constraint validation](/en-US/docs/Web/HTML/Constraint_validation) +- [Guide: Constraint validation](/en-US/docs/Web/HTML/Guides/Constraint_validation) - CSS {{cssxref(":valid")}} and {{cssxref(":invalid")}} pseudo-classes diff --git a/files/en-us/web/api/htmlselectelement/required/index.md b/files/en-us/web/api/htmlselectelement/required/index.md index e5e507121c78d0e..03bfe3437260415 100644 --- a/files/en-us/web/api/htmlselectelement/required/index.md +++ b/files/en-us/web/api/htmlselectelement/required/index.md @@ -8,7 +8,7 @@ browser-compat: api.HTMLSelectElement.required {{ APIRef("HTML DOM") }} -The **`required`** property of the {{DOMxRef("HTMLSelectElement")}} interface specifies that the user must select an option with a non-empty string value before submitting a form. It reflects the {{htmlelement("select")}} element's [`required`](/en-US/docs/Web/HTML/Element/select#required) attribute. +The **`required`** property of the {{DOMxRef("HTMLSelectElement")}} interface specifies that the user must select an option with a non-empty string value before submitting a form. It reflects the {{htmlelement("select")}} element's [`required`](/en-US/docs/Web/HTML/Reference/Elements/select#required) attribute. ## Value diff --git a/files/en-us/web/api/htmlselectelement/setcustomvalidity/index.md b/files/en-us/web/api/htmlselectelement/setcustomvalidity/index.md index e1cb94836cc3cca..952b0f820a1a1ce 100644 --- a/files/en-us/web/api/htmlselectelement/setcustomvalidity/index.md +++ b/files/en-us/web/api/htmlselectelement/setcustomvalidity/index.md @@ -38,4 +38,4 @@ None ({{jsxref("undefined")}}). ## See also -- [Form validation](/en-US/docs/Web/HTML/Constraint_validation). +- [Form validation](/en-US/docs/Web/HTML/Guides/Constraint_validation). diff --git a/files/en-us/web/api/htmlselectelement/size/index.md b/files/en-us/web/api/htmlselectelement/size/index.md index 5fb26d698cfdf48..03b08d5dc42d389 100644 --- a/files/en-us/web/api/htmlselectelement/size/index.md +++ b/files/en-us/web/api/htmlselectelement/size/index.md @@ -8,7 +8,7 @@ browser-compat: api.HTMLSelectElement.size {{ APIRef("HTML DOM") }} -The **`size`** property of the {{DOMxRef("HTMLSelectElement")}} interface specifies the number of options, or rows, that should be visible at one time. It reflects the {{htmlelement("select")}} element's [`size`](/en-US/docs/Web/HTML/Element/select#size) attribute. If omitted, the value is `0`. +The **`size`** property of the {{DOMxRef("HTMLSelectElement")}} interface specifies the number of options, or rows, that should be visible at one time. It reflects the {{htmlelement("select")}} element's [`size`](/en-US/docs/Web/HTML/Reference/Elements/select#size) attribute. If omitted, the value is `0`. > [!NOTE] > While by default a `<select>` displays a single row unless {{DOMxRef("HTMLSelectElement.multiple", "multiple")}} is true, in which case four rows are displayed, the default value for the `size` property is `0`. diff --git a/files/en-us/web/api/htmlselectelement/validationmessage/index.md b/files/en-us/web/api/htmlselectelement/validationmessage/index.md index b7a5d2041df96ba..693696826cfc9a5 100644 --- a/files/en-us/web/api/htmlselectelement/validationmessage/index.md +++ b/files/en-us/web/api/htmlselectelement/validationmessage/index.md @@ -41,5 +41,5 @@ const errorMessage = select.validationMessage; - {{domxref("HTMLSelectElement.reportValidity()")}} - {{domxref("HTMLSelectElement.setCustomValidity()")}} - [Learn: Client-side form validation](/en-US/docs/Learn_web_development/Extensions/Forms/Form_validation) -- [Guide: Constraint validation](/en-US/docs/Web/HTML/Constraint_validation) +- [Guide: Constraint validation](/en-US/docs/Web/HTML/Guides/Constraint_validation) - CSS {{cssxref(":valid")}} and {{cssxref(":invalid")}} pseudo-classes diff --git a/files/en-us/web/api/htmlselectelement/validity/index.md b/files/en-us/web/api/htmlselectelement/validity/index.md index c3ffae744ed5e6a..85585c20cbc3433 100644 --- a/files/en-us/web/api/htmlselectelement/validity/index.md +++ b/files/en-us/web/api/htmlselectelement/validity/index.md @@ -40,4 +40,4 @@ if (!validityState.valid) { - {{HTMLElement("select")}} - {{HTMLElement("form")}} - [Learn: Client-side form validation](/en-US/docs/Learn_web_development/Extensions/Forms/Form_validation) -- [Guide: Constraint validation](/en-US/docs/Web/HTML/Constraint_validation) +- [Guide: Constraint validation](/en-US/docs/Web/HTML/Guides/Constraint_validation) diff --git a/files/en-us/web/api/htmlselectelement/willvalidate/index.md b/files/en-us/web/api/htmlselectelement/willvalidate/index.md index 586055fcc47d260..0b2b1545fe40f02 100644 --- a/files/en-us/web/api/htmlselectelement/willvalidate/index.md +++ b/files/en-us/web/api/htmlselectelement/willvalidate/index.md @@ -8,7 +8,7 @@ browser-compat: api.HTMLSelectElement.willValidate {{APIRef("HTML DOM")}} -The **`willValidate`** read-only property of the {{domxref("HTMLSelectElement")}} interface indicates whether the {{htmlelement("select")}} element is a candidate for [constraint validation](/en-US/docs/Web/HTML/Constraint_validation). It is `false` if any conditions bar it from constraint validation, such as when its {{domxref("HTMLSelectElement.disabled", "disabled")}} property is `true`. +The **`willValidate`** read-only property of the {{domxref("HTMLSelectElement")}} interface indicates whether the {{htmlelement("select")}} element is a candidate for [constraint validation](/en-US/docs/Web/HTML/Guides/Constraint_validation). It is `false` if any conditions bar it from constraint validation, such as when its {{domxref("HTMLSelectElement.disabled", "disabled")}} property is `true`. ## Value @@ -28,4 +28,4 @@ A boolean value. - {{HTMLElement("select")}} - {{HTMLElement("form")}} - [Learn: Client-side form validation](/en-US/docs/Learn_web_development/Extensions/Forms/Form_validation) -- [Guide: Constraint validation](/en-US/docs/Web/HTML/Constraint_validation) +- [Guide: Constraint validation](/en-US/docs/Web/HTML/Guides/Constraint_validation) diff --git a/files/en-us/web/api/htmlslotelement/index.md b/files/en-us/web/api/htmlslotelement/index.md index dc435fcdabbcbbc..24aabc4b2cc6890 100644 --- a/files/en-us/web/api/htmlslotelement/index.md +++ b/files/en-us/web/api/htmlslotelement/index.md @@ -36,7 +36,7 @@ _Also inherits events from its parent interface, {{domxref("HTMLElement")}}._ Listen to these events using {{DOMxRef("EventTarget.addEventListener", "addEventListener()")}} or by assigning an event listener to the `oneventname` property of this interface. - {{domxref('HTMLSlotElement.slotchange_event', 'slotchange')}} - - : Fired on an `HTMLSlotElement` instance ([`<slot>`](/en-US/docs/Web/HTML/Element/slot) element) when the node(s) contained in that slot change. + - : Fired on an `HTMLSlotElement` instance ([`<slot>`](/en-US/docs/Web/HTML/Reference/Elements/slot) element) when the node(s) contained in that slot change. ## Examples diff --git a/files/en-us/web/api/htmlslotelement/slotchange_event/index.md b/files/en-us/web/api/htmlslotelement/slotchange_event/index.md index fc013b1f8394853..2c81c7e4551264c 100644 --- a/files/en-us/web/api/htmlslotelement/slotchange_event/index.md +++ b/files/en-us/web/api/htmlslotelement/slotchange_event/index.md @@ -11,7 +11,7 @@ browser-compat: api.HTMLSlotElement.slotchange_event The **`slotchange`** event is fired on an {{DOMxRef("HTMLSlotElement")}} instance ({{HTMLElement("slot")}} element) when the node(s) contained in that slot change. > [!NOTE] -> The `slotchange` event doesn't fire if the children of a slotted node change — only if you change (e.g. add or delete) the actual nodes themselves. +> The `slotchange` event doesn't fire if the children of a slotted node change — only if you change (e.g., add or delete) the actual nodes themselves. In order to trigger a **slotchange** event, one has to set or remove the `slot` attribute. @@ -21,10 +21,10 @@ This event is not cancelable. Use the event name in methods like {{domxref("EventTarget.addEventListener", "addEventListener()")}}, or set an event handler property. -```js -addEventListener("slotchange", (event) => {}); +```js-nolint +addEventListener("slotchange", (event) => { }) -onslotchange = (event) => {}; +onslotchange = (event) => { } ``` ## Event type diff --git a/files/en-us/web/api/htmlsourceelement/index.md b/files/en-us/web/api/htmlsourceelement/index.md index d998fd3e2c64fa4..74d78f4c84fe747 100644 --- a/files/en-us/web/api/htmlsourceelement/index.md +++ b/files/en-us/web/api/htmlsourceelement/index.md @@ -16,24 +16,24 @@ The **`HTMLSourceElement`** interface provides special properties (beyond the re _Inherits properties from its parent, {{domxref("HTMLElement")}}._ - {{domxref("HTMLSourceElement.height")}} - - : A number that reflects the [`height`](/en-US/docs/Web/HTML/Element/source#height) HTML attribute, indicating the height of the image resource in CSS pixels. The property has a meaning only if the parent of the current {{HTMLElement("source")}} element is a {{HTMLElement("picture")}} element. + - : A number that reflects the [`height`](/en-US/docs/Web/HTML/Reference/Elements/source#height) HTML attribute, indicating the height of the image resource in CSS pixels. The property has a meaning only if the parent of the current {{HTMLElement("source")}} element is a {{HTMLElement("picture")}} element. - {{domxref("HTMLSourceElement.media")}} - - : A string reflecting the [`media`](/en-US/docs/Web/HTML/Element/source#media) HTML attribute, containing the intended type of the media resource. + - : A string reflecting the [`media`](/en-US/docs/Web/HTML/Reference/Elements/source#media) HTML attribute, containing the intended type of the media resource. - {{domxref("HTMLSourceElement.sizes")}} - : A string representing image sizes between breakpoints - {{domxref("HTMLSourceElement.src")}} - - : A string reflecting the [`src`](/en-US/docs/Web/HTML/Element/source#src) HTML attribute, containing the URL for the media resource. The {{domxref("HTMLSourceElement.src")}} property has a meaning only when the associated {{HTMLElement("source")}} element is nested in a media element that is a {{htmlelement("video")}} or an {{htmlelement("audio")}} element. It has no meaning and is ignored when it is nested in a {{HTMLElement("picture")}} element. + - : A string reflecting the [`src`](/en-US/docs/Web/HTML/Reference/Elements/source#src) HTML attribute, containing the URL for the media resource. The {{domxref("HTMLSourceElement.src")}} property has a meaning only when the associated {{HTMLElement("source")}} element is nested in a media element that is a {{htmlelement("video")}} or an {{htmlelement("audio")}} element. It has no meaning and is ignored when it is nested in a {{HTMLElement("picture")}} element. > [!NOTE] > If the `src` property is updated (along with any siblings), the parent {{domxref("HTMLMediaElement")}}'s `load` method should be called when done, since `<source>` elements are not re-scanned automatically. - {{domxref("HTMLSourceElement.srcset")}} - - : A string reflecting the [`srcset`](/en-US/docs/Web/HTML/Element/source#srcset) HTML attribute, containing a list of candidate images, separated by a comma (`',', U+002C COMMA`). A candidate image is a URL followed by a `'w'` with the width of the images, or an `'x'` followed by the pixel density. + - : A string reflecting the [`srcset`](/en-US/docs/Web/HTML/Reference/Elements/source#srcset) HTML attribute, containing a list of candidate images, separated by a comma (`',', U+002C COMMA`). A candidate image is a URL followed by a `'w'` with the width of the images, or an `'x'` followed by the pixel density. - {{domxref("HTMLSourceElement.type")}} - - : A string reflecting the [`type`](/en-US/docs/Web/HTML/Element/source#type) HTML attribute, containing the type of the media resource. + - : A string reflecting the [`type`](/en-US/docs/Web/HTML/Reference/Elements/source#type) HTML attribute, containing the type of the media resource. - {{domxref("HTMLSourceElement.width")}} - - : A number that reflects the [`width`](/en-US/docs/Web/HTML/Element/source#width) HTML attribute, indicating the width of the image resource in CSS pixels. The property has a meaning only if the parent of the current {{HTMLElement("source")}} element is a {{HTMLElement("picture")}} element. + - : A number that reflects the [`width`](/en-US/docs/Web/HTML/Reference/Elements/source#width) HTML attribute, indicating the width of the image resource in CSS pixels. The property has a meaning only if the parent of the current {{HTMLElement("source")}} element is a {{HTMLElement("picture")}} element. ## Instance methods diff --git a/files/en-us/web/api/htmlsourceelement/type/index.md b/files/en-us/web/api/htmlsourceelement/type/index.md index 10df23fee91aac7..d54f799aa7cd988 100644 --- a/files/en-us/web/api/htmlsourceelement/type/index.md +++ b/files/en-us/web/api/htmlsourceelement/type/index.md @@ -50,5 +50,5 @@ console.log(el.type); // Output: "video/webp" - {{htmlelement("audio")}} - {{htmlelement("video")}} - [Media types found on the web](/en-US/docs/Web/Media/Guides/Formats) -- [Important MIME types for web developers](/en-US/docs/Web/HTTP/MIME_types#important_mime_types_for_web_developers) -- {{domxref("Media Capabilities API")}} +- [Important MIME types for web developers](/en-US/docs/Web/HTTP/Guides/MIME_types#important_mime_types_for_web_developers) +- [Media Capabilities API](/en-US/docs/Web/API/Media_Capabilities_API) diff --git a/files/en-us/web/api/htmlstyleelement/disabled/index.md b/files/en-us/web/api/htmlstyleelement/disabled/index.md index c66e9182d4cf478..a5ce0d5e2f750a2 100644 --- a/files/en-us/web/api/htmlstyleelement/disabled/index.md +++ b/files/en-us/web/api/htmlstyleelement/disabled/index.md @@ -10,7 +10,7 @@ browser-compat: api.HTMLStyleElement.disabled The **`HTMLStyleElement.disabled`** property can be used to get and set whether the stylesheet is disabled (`true`) or not (`false`). -Note that there is no corresponding `disabled` attribute on the [HTML `<style>` element](/en-US/docs/Web/HTML/Element/style). +Note that there is no corresponding `disabled` attribute on the [HTML `<style>` element](/en-US/docs/Web/HTML/Reference/Elements/style). ## Value @@ -24,12 +24,12 @@ Setting the property to `true` when there is no associated stylesheet has no eff ### Disabling an inline style -This example demonstrates programmatically setting the disabled property on a style that was defined in the HTML using the [HTML `<style>` element](/en-US/docs/Web/HTML/Element/style). +This example demonstrates programmatically setting the disabled property on a style that was defined in the HTML using the [HTML `<style>` element](/en-US/docs/Web/HTML/Reference/Elements/style). Note that you can also access any/all stylesheets in the document using [`Document.styleSheets`](/en-US/docs/Web/API/Document/styleSheets). #### HTML -The HTML contains an HTML [`<style>`](/en-US/docs/Web/HTML/Element/style) element that makes paragraph elements blue, a paragraph element, and a button that will be used to enabled and disable the style. +The HTML contains an HTML [`<style>`](/en-US/docs/Web/HTML/Reference/Elements/style) element that makes paragraph elements blue, a paragraph element, and a button that will be used to enabled and disable the style. ```html <button>Enable</button> @@ -103,7 +103,7 @@ Note that this is the earliest point at which setting the property to `true` wil Before this point the document did not have an associated style, and so the value defaults to `false`. ```js -//Disable the style +// Disable the style style.disabled = true; ``` diff --git a/files/en-us/web/api/htmlstyleelement/media/index.md b/files/en-us/web/api/htmlstyleelement/media/index.md index f9887cda3552087..b70f4c2089e455d 100644 --- a/files/en-us/web/api/htmlstyleelement/media/index.md +++ b/files/en-us/web/api/htmlstyleelement/media/index.md @@ -38,8 +38,14 @@ A string describing a single medium or a comma-separated list. </head> <body> <script> - alert("LinkedStyle: " + document.getElementById("LinkedStyle").media); // 'screen' - alert("InlineStyle: " + document.getElementById("InlineStyle").media); // 'screen, print' + console.log( + "LinkedStyle: ", + document.getElementById("LinkedStyle").media, + ); // 'screen' + console.log( + "InlineStyle: ", + document.getElementById("InlineStyle").media, + ); // 'screen, print' </script> </body> </html> diff --git a/files/en-us/web/api/htmlstyleelement/sheet/index.md b/files/en-us/web/api/htmlstyleelement/sheet/index.md index 080d7931b9d7b03..b9ce89ad427088f 100644 --- a/files/en-us/web/api/htmlstyleelement/sheet/index.md +++ b/files/en-us/web/api/htmlstyleelement/sheet/index.md @@ -22,7 +22,7 @@ A {{DOMxRef("StyleSheet")}} object, or `null` if none is associated with the ele ```html <html> <header> - <style media="print" /> + <style media="print"></style> … </header> </html> diff --git a/files/en-us/web/api/htmlstyleelement/type/index.md b/files/en-us/web/api/htmlstyleelement/type/index.md index 57dded7b26d34ea..f93a01032982e96 100644 --- a/files/en-us/web/api/htmlstyleelement/type/index.md +++ b/files/en-us/web/api/htmlstyleelement/type/index.md @@ -11,7 +11,7 @@ browser-compat: api.HTMLStyleElement.type {{APIRef("HTML DOM")}} {{Deprecated_Header}} The **`HTMLStyleElement.type`** property returns the type of the current style. -The value mirrors the [HTML `<style>` element's `type` attribute](/en-US/docs/Web/HTML/Element/style#type). +The value mirrors the [HTML `<style>` element's `type` attribute](/en-US/docs/Web/HTML/Reference/Elements/style#type). Authors should not use this property or rely on the value. diff --git a/files/en-us/web/api/htmltablecellelement/bgcolor/index.md b/files/en-us/web/api/htmltablecellelement/bgcolor/index.md index 5fc8781dc5bdd1b..0891d4ba3534fc4 100644 --- a/files/en-us/web/api/htmltablecellelement/bgcolor/index.md +++ b/files/en-us/web/api/htmltablecellelement/bgcolor/index.md @@ -10,7 +10,7 @@ browser-compat: api.HTMLTableCellElement.bgColor {{APIRef("HTML DOM")}}{{deprecated_header}} -The **`HTMLTableCellElement.bgColor`** property is used to set the background color of a cell or get the value of the obsolete [`bgColor`](/en-US/docs/Web/HTML/Element/td#bgcolor) attribute, if present. +The **`HTMLTableCellElement.bgColor`** property is used to set the background color of a cell or get the value of the obsolete [`bgColor`](/en-US/docs/Web/HTML/Reference/Elements/td#bgcolor) attribute, if present. > [!NOTE] > This property is deprecated and CSS should be used to set the background color. Use the {{cssxref("background-color")}} property instead. diff --git a/files/en-us/web/api/htmltablecellelement/colspan/index.md b/files/en-us/web/api/htmltablecellelement/colspan/index.md index cfcb93e3930b9b9..d03775cde1a909f 100644 --- a/files/en-us/web/api/htmltablecellelement/colspan/index.md +++ b/files/en-us/web/api/htmltablecellelement/colspan/index.md @@ -8,7 +8,7 @@ browser-compat: api.HTMLTableCellElement.colSpan {{ APIRef("HTML DOM") }} -The **`colSpan`** read-only property of the {{domxref("HTMLTableCellElement")}} interface represents the number of columns this cell must span; this lets the cell occupy space across multiple columns of the table. It reflects the [`colspan`](/en-US/docs/Web/HTML/Element/td#colspan) attribute. +The **`colSpan`** read-only property of the {{domxref("HTMLTableCellElement")}} interface represents the number of columns this cell must span; this lets the cell occupy space across multiple columns of the table. It reflects the [`colspan`](/en-US/docs/Web/HTML/Reference/Elements/td#colspan) attribute. ## Value @@ -82,14 +82,14 @@ const increaseButton = document.getElementById("increase"); const decreaseButton = document.getElementById("decrease"); increaseButton.addEventListener("click", () => { - cell.colSpan = cell.colSpan + 1; + cell.colSpan += 1; // Update the display output.textContent = cell.colSpan; }); decreaseButton.addEventListener("click", () => { - cell.colSpan = cell.colSpan - 1; + cell.colSpan -= 1; // Update the display output.textContent = cell.colSpan; diff --git a/files/en-us/web/api/htmltablecellelement/index.md b/files/en-us/web/api/htmltablecellelement/index.md index 169c415f967fb18..1045d19e6e5d330 100644 --- a/files/en-us/web/api/htmltablecellelement/index.md +++ b/files/en-us/web/api/htmltablecellelement/index.md @@ -20,11 +20,11 @@ _Inherits properties from its parent, {{domxref("HTMLElement")}}._ - {{domxref("HTMLTableCellElement.cellIndex")}} {{ReadOnlyInline}} - : A number representing the cell's position in the {{domxref("HTMLTableRowElement.cells", "cells")}} collection of the {{HTMLElement("tr")}} the cell is contained within. If the cell doesn't belong to a `<tr>`, it returns `-1`. - {{domxref("HTMLTableCellElement.colSpan")}} - - : A positive number indicating the number of columns this cell must span; this lets the cell occupy space across multiple columns of the table. It reflects the [`colspan`](/en-US/docs/Web/HTML/Element/td#colspan) attribute. + - : A positive number indicating the number of columns this cell must span; this lets the cell occupy space across multiple columns of the table. It reflects the [`colspan`](/en-US/docs/Web/HTML/Reference/Elements/td#colspan) attribute. - {{domxref("HTMLTableCellElement.headers")}} {{ReadOnlyInline}} - - : A {{domxref("DOMTokenList")}} describing a list of `id` of {{HTMLElement("th")}} elements that represent headers associated with the cell. It reflects the [`headers`](/en-US/docs/Web/HTML/Element/td#headers) attribute. + - : A {{domxref("DOMTokenList")}} describing a list of `id` of {{HTMLElement("th")}} elements that represent headers associated with the cell. It reflects the [`headers`](/en-US/docs/Web/HTML/Reference/Elements/td#headers) attribute. - {{domxref("HTMLTableCellElement.rowSpan")}} - - : A positive number indicating the number of rows this cell must span; this lets a cell occupy space across multiple rows of the table. It reflects the [`rowspan`](/en-US/docs/Web/HTML/Element/td#rowspan) attribute. + - : A positive number indicating the number of rows this cell must span; this lets a cell occupy space across multiple rows of the table. It reflects the [`rowspan`](/en-US/docs/Web/HTML/Reference/Elements/td#rowspan) attribute. - {{domxref("HTMLTableCellElement.scope")}} - : A string indicating the scope of a {{HTMLElement("th")}} cell. Possible values for `scope` are: `col`, `colgroup`, `row`, `rowgroup`, or the empty string (`""`). @@ -38,23 +38,23 @@ _No specific method; inherits methods from its parent, {{domxref("HTMLElement")} > These properties have been deprecated and should no longer be used. They are documented primarily to help understand older code bases. - {{domxref("HTMLTableCellElement.align")}} {{deprecated_inline}} - - : A string containing the value of the [`align`](/en-US/docs/Web/HTML/Element/td#align) attribute, if present, or empty string if not set. It can be used to set the alignment of the element's contents to the surrounding context of `"left"`, `"right"`, and `"center"`. Use the CSS {{cssxref("text-align")}} property instead. + - : A string containing the value of the [`align`](/en-US/docs/Web/HTML/Reference/Elements/td#align) attribute, if present, or empty string if not set. It can be used to set the alignment of the element's contents to the surrounding context of `"left"`, `"right"`, and `"center"`. Use the CSS {{cssxref("text-align")}} property instead. - {{domxref("HTMLTableCellElement.axis")}} {{deprecated_inline}} - - : A string containing a name grouping cells in virtual. It reflects the obsolete [`axis`](/en-US/docs/Web/HTML/Element/td#axis) attribute. + - : A string containing a name grouping cells in virtual. It reflects the obsolete [`axis`](/en-US/docs/Web/HTML/Reference/Elements/td#axis) attribute. - {{domxref("HTMLTableCellElement.bgColor")}} {{deprecated_inline}} - - : A string containing the background color of the cells. It reflects the obsolete [`bgColor`](/en-US/docs/Web/HTML/Element/td#bgcolor) attribute. + - : A string containing the background color of the cells. It reflects the obsolete [`bgColor`](/en-US/docs/Web/HTML/Reference/Elements/td#bgcolor) attribute. - {{domxref("HTMLTableCellElement.ch")}} {{deprecated_inline}} - - : A string containing one single character. This character is the one to align all the cells of a column on. It reflects the [`char`](/en-US/docs/Web/HTML/Element/td#char) and defaults to the decimal points associated with the language, e.g. `'.'` for English, or `','` for French. This property was optional and was not very well supported. + - : A string containing one single character. This character is the one to align all the cells of a column on. It reflects the [`char`](/en-US/docs/Web/HTML/Reference/Elements/td#char) and defaults to the decimal points associated with the language, e.g., `'.'` for English, or `','` for French. This property was optional and was not very well supported. - {{domxref("HTMLTableCellElement.chOff")}} {{deprecated_inline}} - : A string containing an integer indicating how many characters must be left at the right (for left-to-right scripts; or at the left for right-to-left scripts) of the character defined by `HTMLTableCellElement.ch`. This property was optional and was not very well supported. - {{domxref("HTMLTableCellElement.height")}} {{deprecated_inline}} - - : A string containing a length of pixel of the hinted height of the cell. It reflects the obsolete [`height`](/en-US/docs/Web/HTML/Element/td#height) attribute. + - : A string containing a length of pixel of the hinted height of the cell. It reflects the obsolete [`height`](/en-US/docs/Web/HTML/Reference/Elements/td#height) attribute. - {{domxref("HTMLTableCellElement.noWrap")}} {{deprecated_inline}} - : A boolean value reflecting the `nowrap` attribute and indicating if cell content can be broken into several lines. - {{domxref("HTMLTableCellElement.vAlign")}} {{deprecated_inline}} - - : A string representing an enumerated value indicating how the content of the cell must be vertically aligned. It reflects the [`valign`](/en-US/docs/Web/HTML/Element/td#valign) attribute and can have one of the following values: `"top"`, `"middle"`, `"bottom"`, or `"baseline"`. Use the CSS {{cssxref("vertical-align")}} property instead. + - : A string representing an enumerated value indicating how the content of the cell must be vertically aligned. It reflects the [`valign`](/en-US/docs/Web/HTML/Reference/Elements/td#valign) attribute and can have one of the following values: `"top"`, `"middle"`, `"bottom"`, or `"baseline"`. Use the CSS {{cssxref("vertical-align")}} property instead. - {{domxref("HTMLTableCellElement.width")}} {{deprecated_inline}} - - : A string specifying the number of pixels wide the cell should be drawn, if possible. This property reflects the also obsolete [`width`](/en-US/docs/Web/HTML/Element/td#width) attribute. Use the CSS {{cssxref("width")}} property instead. + - : A string specifying the number of pixels wide the cell should be drawn, if possible. This property reflects the also obsolete [`width`](/en-US/docs/Web/HTML/Reference/Elements/td#width) attribute. Use the CSS {{cssxref("width")}} property instead. ## Specifications diff --git a/files/en-us/web/api/htmltablecellelement/rowspan/index.md b/files/en-us/web/api/htmltablecellelement/rowspan/index.md index cb4ce943fd3605d..b42af000fed9d84 100644 --- a/files/en-us/web/api/htmltablecellelement/rowspan/index.md +++ b/files/en-us/web/api/htmltablecellelement/rowspan/index.md @@ -8,7 +8,7 @@ browser-compat: api.HTMLTableCellElement.rowSpan {{ APIRef("HTML DOM") }} -The **`rowSpan`** read-only property of the {{domxref("HTMLTableCellElement")}} interface represents the number of rows this cell must span; this lets the cell occupy space across multiple rows of the table. It reflects the [`rowspan`](/en-US/docs/Web/HTML/Element/td#colspan) attribute. +The **`rowSpan`** read-only property of the {{domxref("HTMLTableCellElement")}} interface represents the number of rows this cell must span; this lets the cell occupy space across multiple rows of the table. It reflects the [`rowspan`](/en-US/docs/Web/HTML/Reference/Elements/td#colspan) attribute. ## Value @@ -83,17 +83,17 @@ const increaseButton = document.getElementById("increase"); const decreaseButton = document.getElementById("decrease"); increaseButton.addEventListener("click", () => { - cell.rowSpan = cell.rowSpan + 1; + cell.rowSpan += 1; // Update the display output.textContent = cell.rowSpan; }); decreaseButton.addEventListener("click", () => { - cell.rowSpan = cell.rowSpan - 1; + cell.rowSpan -= 1; // Update the display - output.textContent = `${cell.rowSpan == 0 ? "all remaining" : cell.rowSpan}`; + output.textContent = `${cell.rowSpan === 0 ? "all remaining" : cell.rowSpan}`; }); ``` diff --git a/files/en-us/web/api/htmltablecolelement/index.md b/files/en-us/web/api/htmltablecolelement/index.md index 77d33c2befece59..9a0f343d928e3a7 100644 --- a/files/en-us/web/api/htmltablecolelement/index.md +++ b/files/en-us/web/api/htmltablecolelement/index.md @@ -22,7 +22,7 @@ _Inherits properties from its parent, {{domxref("HTMLElement")}}_. - {{domxref("HTMLTableColElement.chOff")}} {{deprecated_inline}} - : A string representing the offset for the alignment character. - {{domxref("HTMLTableColElement.span")}} - - : A positive number that reflects the [`span`](/en-US/docs/Web/HTML/Element/col#span) HTML attribute, indicating the number of columns to apply this object's attributes to. + - : A positive number that reflects the [`span`](/en-US/docs/Web/HTML/Reference/Elements/col#span) HTML attribute, indicating the number of columns to apply this object's attributes to. - {{domxref("HTMLTableColElement.vAlign")}} {{deprecated_inline}} - : A string that indicates the vertical alignment of the cell data in the column. - {{domxref("HTMLTableColElement.width")}} {{deprecated_inline}} diff --git a/files/en-us/web/api/htmltablecolelement/span/index.md b/files/en-us/web/api/htmltablecolelement/span/index.md index 128549c057e0ca1..d3fbd2282d958d7 100644 --- a/files/en-us/web/api/htmltablecolelement/span/index.md +++ b/files/en-us/web/api/htmltablecolelement/span/index.md @@ -8,7 +8,7 @@ browser-compat: api.HTMLTableColElement.span {{ APIRef("HTML DOM") }} -The **`span`** read-only property of the {{domxref("HTMLTableColElement")}} interface represents the number of columns this {{htmlelement("col")}} or {{htmlelement("colgroup")}} must span; this lets the column occupy space across multiple columns of the table. It reflects the [`span`](/en-US/docs/Web/HTML/Element/col#span) attribute. +The **`span`** read-only property of the {{domxref("HTMLTableColElement")}} interface represents the number of columns this {{htmlelement("col")}} or {{htmlelement("colgroup")}} must span; this lets the column occupy space across multiple columns of the table. It reflects the [`span`](/en-US/docs/Web/HTML/Reference/Elements/col#span) attribute. ## Value @@ -86,14 +86,14 @@ const increaseButton = document.getElementById("increase"); const decreaseButton = document.getElementById("decrease"); increaseButton.addEventListener("click", () => { - col.span = col.span + 1; + col.span += 1; // Update the display output.textContent = col.span; }); decreaseButton.addEventListener("click", () => { - col.span = col.span - 1; + col.span -= 1; // Update the display output.textContent = col.span; diff --git a/files/en-us/web/api/htmltableelement/index.md b/files/en-us/web/api/htmltableelement/index.md index b97f9c76deae9e6..b1c6bdae8669c13 100644 --- a/files/en-us/web/api/htmltableelement/index.md +++ b/files/en-us/web/api/htmltableelement/index.md @@ -32,23 +32,23 @@ _Inherits properties from its parent, {{DOMxRef("HTMLElement")}}._ > The following properties are obsolete. You should avoid using them. - {{DOMxRef("HTMLTableElement.align")}} {{deprecated_inline}} - - : A string containing an enumerated value reflecting the [`align`](/en-US/docs/Web/HTML/Element/table#align) attribute. It indicates the alignment of the element's contents with respect to the surrounding context. The possible values are `"left"`, `"right"`, and `"center"`. + - : A string containing an enumerated value reflecting the [`align`](/en-US/docs/Web/HTML/Reference/Elements/table#align) attribute. It indicates the alignment of the element's contents with respect to the surrounding context. The possible values are `"left"`, `"right"`, and `"center"`. - {{DOMxRef("HTMLTableElement.bgColor")}} {{deprecated_inline}} - - : A string containing the background color of the cells. It reflects the obsolete [`bgColor`](/en-US/docs/Web/HTML/Element/table#bgcolor) attribute. + - : A string containing the background color of the cells. It reflects the obsolete [`bgColor`](/en-US/docs/Web/HTML/Reference/Elements/table#bgcolor) attribute. - {{DOMxRef("HTMLTableElement.border")}} {{deprecated_inline}} - - : A string containing the width in pixels of the border of the table. It reflects the obsolete [`border`](/en-US/docs/Web/HTML/Element/table#border) attribute. + - : A string containing the width in pixels of the border of the table. It reflects the obsolete [`border`](/en-US/docs/Web/HTML/Reference/Elements/table#border) attribute. - {{DOMxRef("HTMLTableElement.cellPadding")}} {{deprecated_inline}} - - : A string containing the width in pixels of the horizontal and vertical space between cell content and cell borders. It reflects the obsolete [`cellpadding`](/en-US/docs/Web/HTML/Element/table#cellpadding) attribute. + - : A string containing the width in pixels of the horizontal and vertical space between cell content and cell borders. It reflects the obsolete [`cellpadding`](/en-US/docs/Web/HTML/Reference/Elements/table#cellpadding) attribute. - {{DOMxRef("HTMLTableElement.cellSpacing")}} {{deprecated_inline}} - - : A string containing the width in pixels of the horizontal and vertical separation between cells. It reflects the obsolete [`cellspacing`](/en-US/docs/Web/HTML/Element/table#cellspacing) attribute. + - : A string containing the width in pixels of the horizontal and vertical separation between cells. It reflects the obsolete [`cellspacing`](/en-US/docs/Web/HTML/Reference/Elements/table#cellspacing) attribute. - {{DOMxRef("HTMLTableElement.frame")}} {{deprecated_inline}} - - : A string containing the type of the external borders of the table. It reflects the obsolete [`frame`](/en-US/docs/Web/HTML/Element/table#frame) attribute and can take one of the following values: `"void"`, `"above"`, `"below"`, `"hsides"`, `"vsides"`, `"lhs"`, `"rhs"`, `"box"`, or `"border"`. + - : A string containing the type of the external borders of the table. It reflects the obsolete [`frame`](/en-US/docs/Web/HTML/Reference/Elements/table#frame) attribute and can take one of the following values: `"void"`, `"above"`, `"below"`, `"hsides"`, `"vsides"`, `"lhs"`, `"rhs"`, `"box"`, or `"border"`. - {{DOMxRef("HTMLTableElement.rules")}} {{deprecated_inline}} - - : A string containing the type of the internal borders of the table. It reflects the obsolete [`rules`](/en-US/docs/Web/HTML/Element/table#rules) attribute and can take one of the following values: `"none"`, `"groups"`, `"rows"`, `"cols"`, or `"all"`. + - : A string containing the type of the internal borders of the table. It reflects the obsolete [`rules`](/en-US/docs/Web/HTML/Reference/Elements/table#rules) attribute and can take one of the following values: `"none"`, `"groups"`, `"rows"`, `"cols"`, or `"all"`. - {{DOMxRef("HTMLTableElement.summary")}} {{deprecated_inline}} - - : A string containing a description of the purpose or the structure of the table. It reflects the obsolete [`summary`](/en-US/docs/Web/HTML/Element/table#summary) attribute. + - : A string containing a description of the purpose or the structure of the table. It reflects the obsolete [`summary`](/en-US/docs/Web/HTML/Reference/Elements/table#summary) attribute. - {{DOMxRef("HTMLTableElement.width")}} {{deprecated_inline}} - - : A string containing the length in pixels or in percentage of the desired width of the entire table. It reflects the obsolete [`width`](/en-US/docs/Web/HTML/Element/table#width) attribute. + - : A string containing the length in pixels or in percentage of the desired width of the entire table. It reflects the obsolete [`width`](/en-US/docs/Web/HTML/Reference/Elements/table#width) attribute. ## Instance methods diff --git a/files/en-us/web/api/htmltablerowelement/bgcolor/index.md b/files/en-us/web/api/htmltablerowelement/bgcolor/index.md index a9328d02363008b..bc258870f9893fb 100644 --- a/files/en-us/web/api/htmltablerowelement/bgcolor/index.md +++ b/files/en-us/web/api/htmltablerowelement/bgcolor/index.md @@ -10,7 +10,7 @@ browser-compat: api.HTMLTableRowElement.bgColor {{APIRef("HTML DOM")}}{{deprecated_header}} -The **`HTMLTableRowElement.bgColor`** property is used to set the background color of a row or retrieve the value of the obsolete [`bgColor`](/en-US/docs/Web/HTML/Element/tr#bgcolor) attribute, if present. +The **`HTMLTableRowElement.bgColor`** property is used to set the background color of a row or retrieve the value of the obsolete [`bgColor`](/en-US/docs/Web/HTML/Reference/Elements/tr#bgcolor) attribute, if present. > [!NOTE] > This property is deprecated and CSS should be used to set the background color. Use the {{cssxref("background-color")}} property instead. diff --git a/files/en-us/web/api/htmltablerowelement/index.md b/files/en-us/web/api/htmltablerowelement/index.md index 7d13d90edc1ad2d..f234d7c267f7efa 100644 --- a/files/en-us/web/api/htmltablerowelement/index.md +++ b/files/en-us/web/api/htmltablerowelement/index.md @@ -37,15 +37,15 @@ _Inherits methods from its parent, {{domxref("HTMLElement")}}_. > These properties have been deprecated and should no longer be used. They are documented primarily to help understand older code bases. - {{domxref("HTMLTableRowElement.align")}} {{deprecated_inline}} - - : A string containing an enumerated value reflecting the [`align`](/en-US/docs/Web/HTML/Element/tr#align) attribute. It indicates the alignment of the element's contents to the surrounding context. The possible values are `"left"`, `"right"`, and `"center"`. + - : A string containing an enumerated value reflecting the [`align`](/en-US/docs/Web/HTML/Reference/Elements/tr#align) attribute. It indicates the alignment of the element's contents to the surrounding context. The possible values are `"left"`, `"right"`, and `"center"`. - {{domxref("HTMLTableRowElement.bgColor")}} {{deprecated_inline}} - - : A string containing the background color of the cells. It reflects the obsolete [`bgColor`](/en-US/docs/Web/HTML/Element/tr#bgcolor) attribute. + - : A string containing the background color of the cells. It reflects the obsolete [`bgColor`](/en-US/docs/Web/HTML/Reference/Elements/tr#bgcolor) attribute. - {{domxref("HTMLTableRowElement.ch")}} {{deprecated_inline}} - - : A string containing one single character. This character is the one to align all the cell of a column on. It reflects the [`char`](/en-US/docs/Web/HTML/Element/tr#char) and defaults to the decimal points associated with the language, e.g. `'.'` for English, or `','` for French. This property was optional and was not very well supported. + - : A string containing one single character. This character is the one to align all the cell of a column on. It reflects the [`char`](/en-US/docs/Web/HTML/Reference/Elements/tr#char) and defaults to the decimal points associated with the language, e.g., `'.'` for English, or `','` for French. This property was optional and was not very well supported. - {{domxref("HTMLTableRowElement.chOff")}} {{deprecated_inline}} - : A string containing an integer indicating how many characters must be left at the right (for left-to-right scripts; or at the left for right-to-left scripts) of the character defined by `HTMLTableRowElement.ch`. This property was optional and was not very well supported. - {{domxref("HTMLTableRowElement.vAlign")}} {{deprecated_inline}} - - : A string representing an enumerated value indicating how the content of the cell must be vertically aligned. It reflects the [`valign`](/en-US/docs/Web/HTML/Element/tr#valign) attribute and can have one of the following values: `"top"`, `"middle"`, `"bottom"`, or `"baseline"`. + - : A string representing an enumerated value indicating how the content of the cell must be vertically aligned. It reflects the [`valign`](/en-US/docs/Web/HTML/Reference/Elements/tr#valign) attribute and can have one of the following values: `"top"`, `"middle"`, `"bottom"`, or `"baseline"`. ## Specifications diff --git a/files/en-us/web/api/htmltablesectionelement/deleterow/index.md b/files/en-us/web/api/htmltablesectionelement/deleterow/index.md index 31a647063457535..a645af1a28d4293 100644 --- a/files/en-us/web/api/htmltablesectionelement/deleterow/index.md +++ b/files/en-us/web/api/htmltablesectionelement/deleterow/index.md @@ -35,7 +35,7 @@ None ({{jsxref("undefined")}}). ## Examples -In this example, two buttons allow you to add and remove rows from the table body section; it also updates a {{HTMLElement("output")}} element with the number of rows currently in the table. +In this example, two buttons allow you to add and remove rows from the table body section; it also updates an {{HTMLElement("output")}} element with the number of rows currently in the table. ### HTML diff --git a/files/en-us/web/api/htmltablesectionelement/index.md b/files/en-us/web/api/htmltablesectionelement/index.md index 42318ed4dea1652..007b2c221d48f75 100644 --- a/files/en-us/web/api/htmltablesectionelement/index.md +++ b/files/en-us/web/api/htmltablesectionelement/index.md @@ -16,15 +16,15 @@ The **`HTMLTableSectionElement`** interface provides special properties and meth _Inherits properties from its parent, {{domxref("HTMLElement")}}._ - {{domxref("HTMLTableSectionElement.align")}} {{deprecated_inline}} - - : A string containing an enumerated value reflecting the [`align`](/en-US/docs/Web/HTML/Element/tr#align) attribute. It indicates the alignment of the element's contents with respect to the surrounding context. The possible values are `"left"`, `"right"`, and `"center"`. + - : A string containing an enumerated value reflecting the [`align`](/en-US/docs/Web/HTML/Reference/Elements/tr#align) attribute. It indicates the alignment of the element's contents with respect to the surrounding context. The possible values are `"left"`, `"right"`, and `"center"`. - {{domxref("HTMLTableSectionElement.rows")}} {{ReadOnlyInline}} - : Returns a live {{domxref("HTMLCollection")}} containing the rows in the section. The `HTMLCollection` is live and is automatically updated when rows are added or removed. - {{domxref("HTMLTableSectionElement.ch")}} {{deprecated_inline}} - - : A string containing one single character. This character is the one to align all the cell of a column on. It reflects the [`char`](/en-US/docs/Web/HTML/Element/tr#char) and default to the decimal points associated with the language, e.g. `'.'` for English, or `','` for French. This property was optional and was not very well supported. + - : A string containing one single character. This character is the one to align all the cell of a column on. It reflects the [`char`](/en-US/docs/Web/HTML/Reference/Elements/tr#char) and default to the decimal points associated with the language, e.g., `'.'` for English, or `','` for French. This property was optional and was not very well supported. - {{domxref("HTMLTableSectionElement.chOff")}} {{deprecated_inline}} - : A string containing an integer indicating how many characters must be left at the right (for left-to-right scripts; or at the left for right-to-left scripts) of the character defined by `HTMLTableRowElement.ch`. This property was optional and was not very well supported. - {{domxref("HTMLTableSectionElement.vAlign")}} {{deprecated_inline}} - - : A string representing an enumerated value indicating how the content of the cell must be vertically aligned. It reflects the [`valign`](/en-US/docs/Web/HTML/Element/tr#valign) attribute and can have one of the following values: `"top"`, `"middle"`, `"bottom"`, or `"baseline"`. + - : A string representing an enumerated value indicating how the content of the cell must be vertically aligned. It reflects the [`valign`](/en-US/docs/Web/HTML/Reference/Elements/tr#valign) attribute and can have one of the following values: `"top"`, `"middle"`, `"bottom"`, or `"baseline"`. ## Instance methods diff --git a/files/en-us/web/api/htmltablesectionelement/insertrow/index.md b/files/en-us/web/api/htmltablesectionelement/insertrow/index.md index d2f81c4de81d962..a695186dfc0e071 100644 --- a/files/en-us/web/api/htmltablesectionelement/insertrow/index.md +++ b/files/en-us/web/api/htmltablesectionelement/insertrow/index.md @@ -42,7 +42,7 @@ An {{domxref("HTMLTableRowElement")}} that references the new row. ## Examples -In this example, two buttons allow you to add and remove rows from the table body section; it also updates a {{HTMLElement("output")}} element with the number of rows currently in the table. +In this example, two buttons allow you to add and remove rows from the table body section; it also updates an {{HTMLElement("output")}} element with the number of rows currently in the table. ### HTML diff --git a/files/en-us/web/api/htmltablesectionelement/rows/index.md b/files/en-us/web/api/htmltablesectionelement/rows/index.md index 0041eab03334bf0..be9b502a05f9b71 100644 --- a/files/en-us/web/api/htmltablesectionelement/rows/index.md +++ b/files/en-us/web/api/htmltablesectionelement/rows/index.md @@ -16,7 +16,7 @@ A live {{domxref("HTMLCollection")}} of {{domxref("HTMLTableRowElement")}} objec ## Examples -In this example, two buttons allow you to add and remove rows from the table body section; it also updates a {{HTMLElement("output")}} element with the number of rows currently in the table. +In this example, two buttons allow you to add and remove rows from the table body section; it also updates an {{HTMLElement("output")}} element with the number of rows currently in the table. ### HTML diff --git a/files/en-us/web/api/htmltemplateelement/index.md b/files/en-us/web/api/htmltemplateelement/index.md index 878729aa3e3e84a..f2064dd52da856a 100644 --- a/files/en-us/web/api/htmltemplateelement/index.md +++ b/files/en-us/web/api/htmltemplateelement/index.md @@ -23,13 +23,13 @@ _This interface inherits the properties of {{domxref("HTMLElement")}}._ - {{domxref("HTMLTemplateElement.content", "content")}} {{ReadOnlyInline}} - : A read-only {{domxref("DocumentFragment")}} which contains the DOM subtree representing the {{HTMLElement("template")}} element's template contents. - {{domxref("HTMLTemplateElement.shadowRootMode", "shadowRootMode")}} - - : A string that reflects the value of the [`shadowrootmode`](/en-US/docs/Web/HTML/Element/template#shadowrootmode) attribute of the associated `<template>` element. + - : A string that reflects the value of the [`shadowrootmode`](/en-US/docs/Web/HTML/Reference/Elements/template#shadowrootmode) attribute of the associated `<template>` element. - {{domxref("HTMLTemplateElement.shadowRootDelegatesFocus", "shadowRootDelegatesFocus")}} - - : A boolean that reflects the value of the [`shadowrootdelegatesfocus`](/en-US/docs/Web/HTML/Element/template#shadowrootdelegatesfocus) attribute of the associated `<template>` element. + - : A boolean that reflects the value of the [`shadowrootdelegatesfocus`](/en-US/docs/Web/HTML/Reference/Elements/template#shadowrootdelegatesfocus) attribute of the associated `<template>` element. - {{domxref("HTMLTemplateElement.shadowRootClonable", "shadowRootClonable")}} - - : A boolean that reflects the value of the [`shadowrootclonable`](/en-US/docs/Web/HTML/Element/template#shadowrootclonable) attribute of the associated `<template>` element. + - : A boolean that reflects the value of the [`shadowrootclonable`](/en-US/docs/Web/HTML/Reference/Elements/template#shadowrootclonable) attribute of the associated `<template>` element. - {{domxref("HTMLTemplateElement.shadowRootSerializable", "shadowRootSerializable")}} - - : A boolean that reflects the value of the [`shadowrootserializable`](/en-US/docs/Web/HTML/Element/template#shadowrootserializable) attribute of the associated `<template>` element. + - : A boolean that reflects the value of the [`shadowrootserializable`](/en-US/docs/Web/HTML/Reference/Elements/template#shadowrootserializable) attribute of the associated `<template>` element. ## Instance methods diff --git a/files/en-us/web/api/htmltemplateelement/shadowrootclonable/index.md b/files/en-us/web/api/htmltemplateelement/shadowrootclonable/index.md index db0b749cf83aae7..345db860b9108ca 100644 --- a/files/en-us/web/api/htmltemplateelement/shadowrootclonable/index.md +++ b/files/en-us/web/api/htmltemplateelement/shadowrootclonable/index.md @@ -8,7 +8,7 @@ browser-compat: api.HTMLTemplateElement.shadowRootClonable {{APIRef("Web Components")}} -The **`shadowRootClonable`** property reflects the value of the [`shadowrootclonable`](/en-US/docs/Web/HTML/Element/template#shadowrootclonable) attribute of the associated [`<template>`](/en-US/docs/Web/HTML/Element/template) element. +The **`shadowRootClonable`** property reflects the value of the [`shadowrootclonable`](/en-US/docs/Web/HTML/Reference/Elements/template#shadowrootclonable) attribute of the associated [`<template>`](/en-US/docs/Web/HTML/Reference/Elements/template) element. Note that this property is not useful for developers. If a `<template>` element is used to declaratively create a [`ShadowRoot`](/en-US/docs/Web/API/ShadowRoot), then this object and property do not exist. @@ -16,7 +16,7 @@ Otherwise, if an `HTMLTemplateElement` is created, the value of this property is ## Value -Reflects the value of the [`shadowrootclonable`](/en-US/docs/Web/HTML/Element/template#shadowrootclonable) attribute of the associated [`<template>`](/en-US/docs/Web/HTML/Element/template) element. +Reflects the value of the [`shadowrootclonable`](/en-US/docs/Web/HTML/Reference/Elements/template#shadowrootclonable) attribute of the associated [`<template>`](/en-US/docs/Web/HTML/Reference/Elements/template) element. ## Specifications @@ -28,5 +28,5 @@ Reflects the value of the [`shadowrootclonable`](/en-US/docs/Web/HTML/Element/te ## See also -- [`shadowrootclonable`](/en-US/docs/Web/HTML/Element/template#shadowrootclonable) attribute of the `<template>` element +- [`shadowrootclonable`](/en-US/docs/Web/HTML/Reference/Elements/template#shadowrootclonable) attribute of the `<template>` element - [`ShadowRoot.clonable`](/en-US/docs/Web/API/ShadowRoot/clonable) diff --git a/files/en-us/web/api/htmltemplateelement/shadowrootdelegatesfocus/index.md b/files/en-us/web/api/htmltemplateelement/shadowrootdelegatesfocus/index.md index 67ed2f857a05f9b..e74c213af84894e 100644 --- a/files/en-us/web/api/htmltemplateelement/shadowrootdelegatesfocus/index.md +++ b/files/en-us/web/api/htmltemplateelement/shadowrootdelegatesfocus/index.md @@ -8,7 +8,7 @@ browser-compat: api.HTMLTemplateElement.shadowRootDelegatesFocus {{APIRef("Web Components")}} -The **`shadowRootDelegatesFocus`** property of the {{domxref("HTMLTemplateElement")}} interface reflects the value of the [`shadowrootdelegatesfocus`](/en-US/docs/Web/HTML/Element/template#shadowrootdelegatesfocus) attribute of the associated [`<template>`](/en-US/docs/Web/HTML/Element/template) element. +The **`shadowRootDelegatesFocus`** property of the {{domxref("HTMLTemplateElement")}} interface reflects the value of the [`shadowrootdelegatesfocus`](/en-US/docs/Web/HTML/Reference/Elements/template#shadowrootdelegatesfocus) attribute of the associated [`<template>`](/en-US/docs/Web/HTML/Reference/Elements/template) element. Note that this property is not useful for developers. If a `<template>` element is used to declaratively create a [`ShadowRoot`](/en-US/docs/Web/API/ShadowRoot), then this object and property do not exist. @@ -16,7 +16,7 @@ Otherwise, if an `HTMLTemplateElement` is created, the value of this property is ## Value -Reflects the value of the [`shadowrootdelegatesfocus`](/en-US/docs/Web/HTML/Element/template#shadowrootdelegatesfocus) attribute of the associated [`<template>`](/en-US/docs/Web/HTML/Element/template) element. +Reflects the value of the [`shadowrootdelegatesfocus`](/en-US/docs/Web/HTML/Reference/Elements/template#shadowrootdelegatesfocus) attribute of the associated [`<template>`](/en-US/docs/Web/HTML/Reference/Elements/template) element. ## Specifications @@ -28,5 +28,5 @@ Reflects the value of the [`shadowrootdelegatesfocus`](/en-US/docs/Web/HTML/Elem ## See also -- [`shadowrootdelegatesfocus`](/en-US/docs/Web/HTML/Element/template#shadowrootdelegatesfocus) attribute of the `<template>` element +- [`shadowrootdelegatesfocus`](/en-US/docs/Web/HTML/Reference/Elements/template#shadowrootdelegatesfocus) attribute of the `<template>` element - [`ShadowRoot.delegatesFocus`](/en-US/docs/Web/API/ShadowRoot/delegatesFocus) diff --git a/files/en-us/web/api/htmltemplateelement/shadowrootmode/index.md b/files/en-us/web/api/htmltemplateelement/shadowrootmode/index.md index d6857ef1afc4dae..e2e276c2ac3e284 100644 --- a/files/en-us/web/api/htmltemplateelement/shadowrootmode/index.md +++ b/files/en-us/web/api/htmltemplateelement/shadowrootmode/index.md @@ -8,7 +8,7 @@ browser-compat: api.HTMLTemplateElement.shadowRootMode {{APIRef("Web Components")}} -The **`shadowRootMode`** property of the {{domxref("HTMLTemplateElement")}} interface reflects the value of the [`shadowrootmode`](/en-US/docs/Web/HTML/Element/template#shadowrootmode) attribute of the associated [`<template>`](/en-US/docs/Web/HTML/Element/template) element. +The **`shadowRootMode`** property of the {{domxref("HTMLTemplateElement")}} interface reflects the value of the [`shadowrootmode`](/en-US/docs/Web/HTML/Reference/Elements/template#shadowrootmode) attribute of the associated [`<template>`](/en-US/docs/Web/HTML/Reference/Elements/template) element. Note that this property is not useful for developers. If a `<template>` element is used to declaratively create a [`ShadowRoot`](/en-US/docs/Web/API/ShadowRoot), then this object and property do not exist. @@ -16,7 +16,7 @@ Otherwise, if an `HTMLTemplateElement` is created, the value of this property is ## Value -Reflects the value of the [`shadowrootmode`](/en-US/docs/Web/HTML/Element/template#shadowrootmode) attribute of the associated [`<template>`](/en-US/docs/Web/HTML/Element/template) element. +Reflects the value of the [`shadowrootmode`](/en-US/docs/Web/HTML/Reference/Elements/template#shadowrootmode) attribute of the associated [`<template>`](/en-US/docs/Web/HTML/Reference/Elements/template) element. ## Specifications @@ -28,5 +28,5 @@ Reflects the value of the [`shadowrootmode`](/en-US/docs/Web/HTML/Element/templa ## See also -- [`shadowrootmode`](/en-US/docs/Web/HTML/Element/template#shadowrootmode) attribute of the `<template>` element +- [`shadowrootmode`](/en-US/docs/Web/HTML/Reference/Elements/template#shadowrootmode) attribute of the `<template>` element - [`ShadowRoot.mode`](/en-US/docs/Web/API/ShadowRoot/mode) diff --git a/files/en-us/web/api/htmltemplateelement/shadowrootserializable/index.md b/files/en-us/web/api/htmltemplateelement/shadowrootserializable/index.md index 131ce10bd2f3b0d..34aa1b16cb0651d 100644 --- a/files/en-us/web/api/htmltemplateelement/shadowrootserializable/index.md +++ b/files/en-us/web/api/htmltemplateelement/shadowrootserializable/index.md @@ -8,7 +8,7 @@ browser-compat: api.HTMLTemplateElement.shadowRootSerializable {{APIRef("Web Components")}} -The **`shadowRootSerializable`** property reflects the value of the [`shadowrootserializable`](/en-US/docs/Web/HTML/Element/template#shadowrootserializable) attribute of the associated [`<template>`](/en-US/docs/Web/HTML/Element/template) element. +The **`shadowRootSerializable`** property reflects the value of the [`shadowrootserializable`](/en-US/docs/Web/HTML/Reference/Elements/template#shadowrootserializable) attribute of the associated [`<template>`](/en-US/docs/Web/HTML/Reference/Elements/template) element. Note that this property is not useful for developers. If a `<template>` element is used to declaratively create a [`ShadowRoot`](/en-US/docs/Web/API/ShadowRoot), then this object and property do not exist. @@ -16,7 +16,7 @@ Otherwise, if an `HTMLTemplateElement` is created, the value of this property is ## Value -Reflects the value of the [`shadowrootserializable`](/en-US/docs/Web/HTML/Element/template#shadowrootserializable) attribute of the associated [`<template>`](/en-US/docs/Web/HTML/Element/template) element. +Reflects the value of the [`shadowrootserializable`](/en-US/docs/Web/HTML/Reference/Elements/template#shadowrootserializable) attribute of the associated [`<template>`](/en-US/docs/Web/HTML/Reference/Elements/template) element. ## Specifications @@ -28,5 +28,5 @@ Reflects the value of the [`shadowrootserializable`](/en-US/docs/Web/HTML/Elemen ## See also -- [`shadowrootserializable`](/en-US/docs/Web/HTML/Element/template#shadowrootserializable) attribute of the `<template>` element +- [`shadowrootserializable`](/en-US/docs/Web/HTML/Reference/Elements/template#shadowrootserializable) attribute of the `<template>` element - [`ShadowRoot.serializable`](/en-US/docs/Web/API/ShadowRoot/serializable) diff --git a/files/en-us/web/api/htmltextareaelement/autocomplete/index.md b/files/en-us/web/api/htmltextareaelement/autocomplete/index.md index 6245ffad6a4c78e..48dd1d7b571261e 100644 --- a/files/en-us/web/api/htmltextareaelement/autocomplete/index.md +++ b/files/en-us/web/api/htmltextareaelement/autocomplete/index.md @@ -8,11 +8,11 @@ browser-compat: api.HTMLTextAreaElement.autocomplete {{ APIRef("HTML DOM") }} -The **`autocomplete`** property of the {{DOMxRef("HTMLTextAreaElement")}} interface indicates whether the value of the control can be automatically completed by the browser. It reflects the `<textarea>` element's [`autocomplete`](/en-US/docs/Web/HTML/Element/textarea#autocomplete) attribute. +The **`autocomplete`** property of the {{DOMxRef("HTMLTextAreaElement")}} interface indicates whether the value of the control can be automatically completed by the browser. It reflects the `<textarea>` element's [`autocomplete`](/en-US/docs/Web/HTML/Reference/Elements/textarea#autocomplete) attribute. ## Value -A string representing the value of the `autocomplete` attribute (`"on"`, `"off"`, or a [`<token-list>`](/en-US/docs/Web/HTML/Attributes/autocomplete#token_list_tokens)) or the empty string (`""`) if unspecified. +A string representing the value of the `autocomplete` attribute (`"on"`, `"off"`, or a [`<token-list>`](/en-US/docs/Web/HTML/Reference/Attributes/autocomplete#token_list_tokens)) or the empty string (`""`) if unspecified. ## Examples @@ -32,6 +32,6 @@ console.log(textArea.autocomplete); ## See also - {{HTMLElement("textarea")}} -- HTML [`autocomplete`](/en-US/docs/Web/HTML/Attributes/autocomplete) attribute -- ARIA [`aria-autocomplete`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-autocomplete) attribute +- HTML [`autocomplete`](/en-US/docs/Web/HTML/Reference/Attributes/autocomplete) attribute +- ARIA [`aria-autocomplete`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-autocomplete) attribute - [Turning off autocompletion](/en-US/docs/Web/Security/Practical_implementation_guides/Turning_off_form_autocompletion) diff --git a/files/en-us/web/api/htmltextareaelement/checkvalidity/index.md b/files/en-us/web/api/htmltextareaelement/checkvalidity/index.md index 047cf5c4e133a99..a3ba70a7d4920dd 100644 --- a/files/en-us/web/api/htmltextareaelement/checkvalidity/index.md +++ b/files/en-us/web/api/htmltextareaelement/checkvalidity/index.md @@ -8,7 +8,7 @@ browser-compat: api.HTMLTextAreaElement.checkValidity {{APIRef("HTML DOM")}} -The **`checkValidity()`** method of the {{domxref("HTMLTextAreaElement")}} interface returns a boolean value which indicates if the element meets any [constraint validation](/en-US/docs/Web/HTML/Constraint_validation) rules applied to it. If false, the method also fires an {{domxref("HTMLElement/invalid_event", "invalid")}} event on the element. Because there's no default browser behavior for `checkValidity()`, canceling this `invalid` event has no effect. +The **`checkValidity()`** method of the {{domxref("HTMLTextAreaElement")}} interface returns a boolean value which indicates if the element meets any [constraint validation](/en-US/docs/Web/HTML/Guides/Constraint_validation) rules applied to it. If false, the method also fires an {{domxref("HTMLElement/invalid_event", "invalid")}} event on the element. Because there's no default browser behavior for `checkValidity()`, canceling this `invalid` event has no effect. > [!NOTE] > An HTML {{htmlelement("textarea")}} element with a non-null {{domxref("HTMLTextAreaElement.validationMessage", "validationMessage")}} is considered invalid, will match the CSS {{cssxref(":invalid")}} pseudo-class, and will cause `checkValidity()` to return false. Use the {{domxref("HTMLTextAreaElement.setCustomValidity()")}} method to set the {{domxref("HTMLTextAreaElement.validationMessage")}} to the empty string to set the {{domxref("HTMLTextAreaElement.validity", "validity")}} state to be valid. @@ -50,5 +50,5 @@ console.log(element.checkValidity()); - {{HTMLElement("textarea")}} - {{HTMLElement("form")}} - [Learn: Client-side form validation](/en-US/docs/Learn_web_development/Extensions/Forms/Form_validation) -- [Guide: Constraint validation](/en-US/docs/Web/HTML/Constraint_validation) +- [Guide: Constraint validation](/en-US/docs/Web/HTML/Guides/Constraint_validation) - CSS {{cssxref(":valid")}} and {{cssxref(":invalid")}} pseudo-classes diff --git a/files/en-us/web/api/htmltextareaelement/cols/index.md b/files/en-us/web/api/htmltextareaelement/cols/index.md index 96cc7c6d48fefd2..9ec6f281a34c87a 100644 --- a/files/en-us/web/api/htmltextareaelement/cols/index.md +++ b/files/en-us/web/api/htmltextareaelement/cols/index.md @@ -8,7 +8,7 @@ browser-compat: api.HTMLTextAreaElement.cols {{ APIRef("HTML DOM") }} -The **`cols`** property of the {{DOMxRef("HTMLTextAreaElement")}} interface is a positive integer representing the visible width of the multi-line text control, in average character widths. It reflects the `<textarea>` element's [`cols`](/en-US/docs/Web/HTML/Element/textarea#cols) attribute. +The **`cols`** property of the {{DOMxRef("HTMLTextAreaElement")}} interface is a positive integer representing the visible width of the multi-line text control, in average character widths. It reflects the `<textarea>` element's [`cols`](/en-US/docs/Web/HTML/Reference/Elements/textarea#cols) attribute. ## Value diff --git a/files/en-us/web/api/htmltextareaelement/dirname/index.md b/files/en-us/web/api/htmltextareaelement/dirname/index.md new file mode 100644 index 000000000000000..2a7c2035d9743e0 --- /dev/null +++ b/files/en-us/web/api/htmltextareaelement/dirname/index.md @@ -0,0 +1,37 @@ +--- +title: "HTMLTextAreaElement: dirName property" +short-title: dirName +slug: Web/API/HTMLTextAreaElement/dirName +page-type: web-api-instance-property +browser-compat: api.HTMLTextAreaElement.dirName +--- + +{{APIRef("HTML DOM")}} + +The **`dirName`** property of the {{domxref("HTMLTextAreaElement")}} interface is the directionality of the element. It reflects the value of the {{htmlelement("textarea")}} element's [`dirName`](/en-US/docs/Web/HTML/Reference/Attributes/dirname) attribute. This property can be retrieved or set. + +The `dirname` attribute controls how the element's directionality is submitted. When included, the form control will submit with two name/value pairs: the first being the [`name`](/en-US/docs/Web/API/HTMLTextAreaElement/name) and [`value`](/en-US/docs/Web/API/HTMLTextAreaElement/value) of the `<textarea>`, and the second being the value of the [`dirname`](/en-US/docs/Web/HTML/Reference/Elements/textarea#dirname) attribute as the name, with a value of `ltr` or `rtl` as set by the browser. + +## Value + +A string. The direction of the element. + +## Examples + +```js +textareaElement.dirName = "rtl"; +``` + +## Specifications + +{{Specifications}} + +## Browser compatibility + +{{Compat}} + +## See also + +- {{domxref("HTMLInputElement.dirName")}} +- [`dir` attribute](/en-US/docs/Web/HTML/Reference/Global_attributes/dir) +- [Sending form data](/en-US/docs/Learn_web_development/Extensions/Forms/Sending_and_retrieving_form_data) diff --git a/files/en-us/web/api/htmltextareaelement/disabled/index.md b/files/en-us/web/api/htmltextareaelement/disabled/index.md index 65d7939d22b449c..101b6502b3766d8 100644 --- a/files/en-us/web/api/htmltextareaelement/disabled/index.md +++ b/files/en-us/web/api/htmltextareaelement/disabled/index.md @@ -8,7 +8,7 @@ browser-compat: api.HTMLTextAreaElement.disabled {{ APIRef("HTML DOM") }} -The **`disabled`** property of the {{DOMxRef("HTMLTextAreaElement")}} interface indicates whether this multi-line text control is disabled and cannot be interacted with. It reflects the {{htmlelement("textarea")}} element's [`disabled`](/en-US/docs/Web/HTML/Element/textarea#autocomplete) attribute. When `false`, this `textarea` may still be disabled if its containing element, such as a {{htmlelement("fieldset")}}, is disabled. +The **`disabled`** property of the {{DOMxRef("HTMLTextAreaElement")}} interface indicates whether this multi-line text control is disabled and cannot be interacted with. It reflects the {{htmlelement("textarea")}} element's [`disabled`](/en-US/docs/Web/HTML/Reference/Elements/textarea#autocomplete) attribute. When `false`, this `textarea` may still be disabled if its containing element, such as a {{htmlelement("fieldset")}}, is disabled. ## Value diff --git a/files/en-us/web/api/htmltextareaelement/form/index.md b/files/en-us/web/api/htmltextareaelement/form/index.md index 7fae00c22e6d302..2b553e43ee4d62c 100644 --- a/files/en-us/web/api/htmltextareaelement/form/index.md +++ b/files/en-us/web/api/htmltextareaelement/form/index.md @@ -27,5 +27,5 @@ An {{domxref("HTMLFormElement")}} or `null`. - {{domxref("HTMLTextAreaElement")}} - {{domxref("HTMLFormElement")}} - {{HTMLElement("textarea")}} -- HTML [`form`](/en-US/docs/Web/HTML/Element/textarea#form) attribute +- HTML [`form`](/en-US/docs/Web/HTML/Reference/Elements/textarea#form) attribute - [HTML forms guide](/en-US/docs/Learn_web_development/Extensions/Forms) diff --git a/files/en-us/web/api/htmltextareaelement/index.md b/files/en-us/web/api/htmltextareaelement/index.md index 28def63a75c43f1..19f657023e7819b 100644 --- a/files/en-us/web/api/htmltextareaelement/index.md +++ b/files/en-us/web/api/htmltextareaelement/index.md @@ -16,33 +16,33 @@ The **`HTMLTextAreaElement`** interface provides properties and methods for mani _Also inherits properties from its parent interface, {{DOMxRef("HTMLElement")}}._ - {{domxref("HTMLTextAreaElement.autocomplete", "autocomplete")}} - - : A string that represents the element's [`autocomplete`](/en-US/docs/Web/HTML/Element/textarea#autocomplete) attribute. + - : A string that represents the element's [`autocomplete`](/en-US/docs/Web/HTML/Reference/Elements/textarea#autocomplete) attribute. - {{domxref("HTMLTextAreaElement.cols", "cols")}} - - : A number that represents the element's [`cols`](/en-US/docs/Web/HTML/Element/textarea#cols) attribute, indicating the visible width of the text area. + - : A number that represents the element's [`cols`](/en-US/docs/Web/HTML/Reference/Elements/textarea#cols) attribute, indicating the visible width of the text area. - {{domxref("HTMLTextAreaElement.defaultValue", "defaultValue")}} - : A string that represents the control's default value, which behaves like the {{domxref("Node.textContent")}} property. - {{domxref("HTMLTextAreaElement.dirName", "dirName")}} - : A string that represents the directionality of the element. - {{domxref("HTMLTextAreaElement.disabled", "disabled")}} - - : A boolean that represents the element's [`disabled`](/en-US/docs/Web/HTML/Element/textarea#disabled) attribute, indicating that the control is not available for interaction. + - : A boolean that represents the element's [`disabled`](/en-US/docs/Web/HTML/Reference/Elements/textarea#disabled) attribute, indicating that the control is not available for interaction. - {{domxref("HTMLTextAreaElement.form", "form")}} {{ReadOnlyInline}} - - : Returns a reference to the parent form element. If this element is not contained in a form element, it can be the [`id`](/en-US/docs/Web/HTML/Global_attributes/id) attribute of any {{HTMLElement("form")}} element in the same document or the value `null`. + - : Returns a reference to the parent form element. If this element is not contained in a form element, it can be the [`id`](/en-US/docs/Web/HTML/Reference/Global_attributes/id) attribute of any {{HTMLElement("form")}} element in the same document or the value `null`. - {{domxref("HTMLTextAreaElement.labels", "labels")}} {{ReadOnlyInline}} - : Returns a {{domxref("NodeList")}} of the {{HTMLElement("label")}} elements associated with this element. - {{domxref("HTMLTextAreaElement.maxLength", "maxLength")}} - - : A number that represents the element's [`maxlength`](/en-US/docs/Web/HTML/Element/textarea#maxlength) attribute, indicating the maximum number of characters the user can enter. This constraint is evaluated only when the value changes. + - : A number that represents the element's [`maxlength`](/en-US/docs/Web/HTML/Reference/Elements/textarea#maxlength) attribute, indicating the maximum number of characters the user can enter. This constraint is evaluated only when the value changes. - {{domxref("HTMLTextAreaElement.minLength", "minLength")}} - - : A number that represents the element's [`minlength`](/en-US/docs/Web/HTML/Element/textarea#minlength) attribute, indicating the minimum number of characters the user can enter. This constraint is evaluated only when the value changes. + - : A number that represents the element's [`minlength`](/en-US/docs/Web/HTML/Reference/Elements/textarea#minlength) attribute, indicating the minimum number of characters the user can enter. This constraint is evaluated only when the value changes. - {{domxref("HTMLTextAreaElement.name", "name")}} - - : A string that represents the element's [`name`](/en-US/docs/Web/HTML/Element/textarea#name) attribute, containing the name of the control. + - : A string that represents the element's [`name`](/en-US/docs/Web/HTML/Reference/Elements/textarea#name) attribute, containing the name of the control. - {{domxref("HTMLTextAreaElement.placeholder", "placeholder")}} - - : A string that represents the element's [`placeholder`](/en-US/docs/Web/HTML/Element/textarea#placeholder) attribute, containing a hint to the user about what to enter in the control. + - : A string that represents the element's [`placeholder`](/en-US/docs/Web/HTML/Reference/Elements/textarea#placeholder) attribute, containing a hint to the user about what to enter in the control. - {{domxref("HTMLTextAreaElement.readOnly", "readOnly")}} - - : A boolean that represents the element's [`readonly`](/en-US/docs/Web/HTML/Element/textarea#readonly) attribute, indicating that the user cannot modify the value of the control. + - : A boolean that represents the element's [`readonly`](/en-US/docs/Web/HTML/Reference/Elements/textarea#readonly) attribute, indicating that the user cannot modify the value of the control. - {{domxref("HTMLTextAreaElement.required", "required")}} - - : A boolean that represents the element's [`required`](/en-US/docs/Web/HTML/Element/textarea#required) attribute, indicating that the user must specify a value before submitting the form. + - : A boolean that represents the element's [`required`](/en-US/docs/Web/HTML/Reference/Elements/textarea#required) attribute, indicating that the user must specify a value before submitting the form. - {{domxref("HTMLTextAreaElement.rows", "rows")}} - - : A number that represents the element's [`rows`](/en-US/docs/Web/HTML/Element/textarea#rows) attribute, indicating the number of visible text lines for the control. + - : A number that represents the element's [`rows`](/en-US/docs/Web/HTML/Reference/Elements/textarea#rows) attribute, indicating the number of visible text lines for the control. - {{domxref("HTMLTextAreaElement.selectionDirection", "selectionDirection")}} - : A string that represents the direction in which selection occurred. This is `forward` if selection was performed in the start-to-end direction of the current locale, or `backward` for the opposite direction. This can also be `none` if the direction is unknown. - {{domxref("HTMLTextAreaElement.selectionEnd", "selectionEnd")}} @@ -62,7 +62,7 @@ _Also inherits properties from its parent interface, {{DOMxRef("HTMLElement")}}. - {{domxref("HTMLTextAreaElement.willValidate", "willValidate")}} {{ReadOnlyInline}} - : Returns whether the element is a candidate for constraint validation. `false` if any conditions bar it from constraint validation, including its `readOnly` or `disabled` property is `true`. - {{domxref("HTMLTextAreaElement.wrap", "wrap")}} - - : A string that represents the element's [`wrap`](/en-US/docs/Web/HTML/Element/textarea#wrap) attribute, indicating how the control wraps text. + - : A string that represents the element's [`wrap`](/en-US/docs/Web/HTML/Reference/Elements/textarea#wrap) attribute, indicating how the control wraps text. ## Instance methods @@ -89,7 +89,7 @@ Listen to these events using {{domxref("EventTarget/addEventListener", "addEvent - {{domxref("HTMLTextAreaElement/select_event", "select")}} event - : Fires when some text has been selected. -- {{domxref("HTMLTextAreaElement/selectionchange_event", "selectionchange")}} event {{experimental_inline}} +- {{domxref("HTMLTextAreaElement/selectionchange_event", "selectionchange")}} event - : Fires when the text selection in a {{HTMLElement("textarea")}} element has been changed. ## Examples diff --git a/files/en-us/web/api/htmltextareaelement/maxlength/index.md b/files/en-us/web/api/htmltextareaelement/maxlength/index.md index 064bbc02ccb3ebd..4ab0cb976de7a88 100644 --- a/files/en-us/web/api/htmltextareaelement/maxlength/index.md +++ b/files/en-us/web/api/htmltextareaelement/maxlength/index.md @@ -8,7 +8,7 @@ browser-compat: api.HTMLTextAreaElement.maxLength {{ApiRef("HTML DOM")}} -The **`maxLength`** property of the {{domxref("HTMLTextAreaElement")}} interface indicates the maximum number of characters (in UTF-16 code units) allowed to be entered for the value of the {{HTMLElement("textarea")}} element, and the maximum number of characters allowed for the value to be valid. It reflects the element's [`maxlength`](/en-US/docs/Web/HTML/Element/textarea#maxlength) attribute. `-1` means there is no limit on the length of the value. +The **`maxLength`** property of the {{domxref("HTMLTextAreaElement")}} interface indicates the maximum number of characters (in UTF-16 code units) allowed to be entered for the value of the {{HTMLElement("textarea")}} element, and the maximum number of characters allowed for the value to be valid. It reflects the element's [`maxlength`](/en-US/docs/Web/HTML/Reference/Elements/textarea#maxlength) attribute. `-1` means there is no limit on the length of the value. > [!NOTE] > Browsers generally prevent users from entering more characters than the `maxlength` attribute allows. Should the length be longer, the element is considered invalid and the {{domxref("ValidityState")}} object's {{domxref("ValidityState.tooLong", "tooLong")}} property will be `true`. @@ -24,7 +24,7 @@ Given the following HTML: ```html <p> <label for="comment">Comment</label> - <textarea id="comment" minlength="10" maxlength="200" /></textarea> + <textarea id="comment" minlength="10" maxlength="200"></textarea> </p> ``` diff --git a/files/en-us/web/api/htmltextareaelement/minlength/index.md b/files/en-us/web/api/htmltextareaelement/minlength/index.md index 0ef8d037b5900c9..27522c3e48e3579 100644 --- a/files/en-us/web/api/htmltextareaelement/minlength/index.md +++ b/files/en-us/web/api/htmltextareaelement/minlength/index.md @@ -8,7 +8,7 @@ browser-compat: api.HTMLTextAreaElement.minLength {{ApiRef("HTML DOM")}} -The **`minLength`** property of the {{domxref("HTMLTextAreaElement")}} interface indicates the minimum number of characters (in UTF-16 code units) required for the value of the {{HTMLElement("textarea")}} element to be valid. It reflects the element's [`minlength`](/en-US/docs/Web/HTML/Element/textarea#minlength) attribute. `-1` means there is no minimum length requirement. +The **`minLength`** property of the {{domxref("HTMLTextAreaElement")}} interface indicates the minimum number of characters (in UTF-16 code units) required for the value of the {{HTMLElement("textarea")}} element to be valid. It reflects the element's [`minlength`](/en-US/docs/Web/HTML/Reference/Elements/textarea#minlength) attribute. `-1` means there is no minimum length requirement. > [!NOTE] > If the textarea has a value, and that value has fewer characters than the `minlength` attribute requires, the element is considered invalid and the {{domxref("ValidityState")}} object's {{domxref("ValidityState.tooShort", "tooShort")}} property will be `true`. @@ -24,7 +24,7 @@ Given the following HTML: ```html <p> <label for="comment">Comment</label> - <textarea id="comment" minlength="10" maxlength="200" /></textarea> + <textarea id="comment" minlength="10" maxlength="200"></textarea> </p> ``` diff --git a/files/en-us/web/api/htmltextareaelement/name/index.md b/files/en-us/web/api/htmltextareaelement/name/index.md index e2e758c7ba3e0ba..027bb11ff2d7aaf 100644 --- a/files/en-us/web/api/htmltextareaelement/name/index.md +++ b/files/en-us/web/api/htmltextareaelement/name/index.md @@ -8,7 +8,7 @@ browser-compat: api.HTMLTextAreaElement.name {{ApiRef("HTML DOM")}} -The **`name`** property of the {{domxref("HTMLTextAreaElement")}} interface indicates the name of the {{HTMLElement("textarea")}} element. It reflects the element's [`name`](/en-US/docs/Web/HTML/Element/textarea#name) attribute. +The **`name`** property of the {{domxref("HTMLTextAreaElement")}} interface indicates the name of the {{HTMLElement("textarea")}} element. It reflects the element's [`name`](/en-US/docs/Web/HTML/Reference/Elements/textarea#name) attribute. ## Value diff --git a/files/en-us/web/api/htmltextareaelement/placeholder/index.md b/files/en-us/web/api/htmltextareaelement/placeholder/index.md index 9b171dc755f3875..576fd8200c0bd0c 100644 --- a/files/en-us/web/api/htmltextareaelement/placeholder/index.md +++ b/files/en-us/web/api/htmltextareaelement/placeholder/index.md @@ -8,7 +8,7 @@ browser-compat: api.HTMLTextAreaElement.placeholder {{ APIRef("HTML DOM") }} -The **`placeholder`** property of the {{DOMxRef("HTMLTextAreaElement")}} interface represents a hint to the user of what can be entered in the control. It reflects the {{htmlelement("textarea")}} element's [`placeholder`](/en-US/docs/Web/HTML/Element/textarea#placeholder) attribute. +The **`placeholder`** property of the {{DOMxRef("HTMLTextAreaElement")}} interface represents a hint to the user of what can be entered in the control. It reflects the {{htmlelement("textarea")}} element's [`placeholder`](/en-US/docs/Web/HTML/Reference/Elements/textarea#placeholder) attribute. ## Value diff --git a/files/en-us/web/api/htmltextareaelement/readonly/index.md b/files/en-us/web/api/htmltextareaelement/readonly/index.md index 57a9cdb47a13012..ec2cc48ff1a73d6 100644 --- a/files/en-us/web/api/htmltextareaelement/readonly/index.md +++ b/files/en-us/web/api/htmltextareaelement/readonly/index.md @@ -8,7 +8,7 @@ browser-compat: api.HTMLTextAreaElement.readOnly {{ APIRef("HTML DOM") }} -The **`readOnly`** property of the {{DOMxRef("HTMLTextAreaElement")}} interface indicates that the user cannot modify the value of the control. Unlike the {{domxref("HTMLTextAreaElement.disabled", "disabled")}} attribute, the `readonly` attribute does not prevent the user from clicking or selecting in the control. It reflects the {{htmlelement("textarea")}} element's [`readonly`](/en-US/docs/Web/HTML/Element/textarea#readonly) attribute. +The **`readOnly`** property of the {{DOMxRef("HTMLTextAreaElement")}} interface indicates that the user cannot modify the value of the control. Unlike the {{domxref("HTMLTextAreaElement.disabled", "disabled")}} attribute, the `readonly` attribute does not prevent the user from clicking or selecting in the control. It reflects the {{htmlelement("textarea")}} element's [`readonly`](/en-US/docs/Web/HTML/Reference/Elements/textarea#readonly) attribute. ## Value diff --git a/files/en-us/web/api/htmltextareaelement/reportvalidity/index.md b/files/en-us/web/api/htmltextareaelement/reportvalidity/index.md index 6e46e2a9010033d..0af857c4136347a 100644 --- a/files/en-us/web/api/htmltextareaelement/reportvalidity/index.md +++ b/files/en-us/web/api/htmltextareaelement/reportvalidity/index.md @@ -38,5 +38,5 @@ Returns `true` if the element's value has no validity problems; otherwise, retur - {{HTMLElement("textarea")}} - {{HTMLElement("form")}} - [Learn: Client-side form validation](/en-US/docs/Learn_web_development/Extensions/Forms/Form_validation) -- [Guide: Constraint validation](/en-US/docs/Web/HTML/Constraint_validation) +- [Guide: Constraint validation](/en-US/docs/Web/HTML/Guides/Constraint_validation) - CSS {{cssxref(":valid")}} and {{cssxref(":invalid")}} pseudo-classes diff --git a/files/en-us/web/api/htmltextareaelement/required/index.md b/files/en-us/web/api/htmltextareaelement/required/index.md index d4cf15b35102ab9..a7aff489c64baf5 100644 --- a/files/en-us/web/api/htmltextareaelement/required/index.md +++ b/files/en-us/web/api/htmltextareaelement/required/index.md @@ -8,7 +8,7 @@ browser-compat: api.HTMLTextAreaElement.required {{ APIRef("HTML DOM") }} -The **`required`** property of the {{DOMxRef("HTMLTextAreaElement")}} interface specifies that the user must fill in a value before submitting a form. It reflects the {{htmlelement("textarea")}} element's [`required`](/en-US/docs/Web/HTML/Element/textarea#required) attribute. +The **`required`** property of the {{DOMxRef("HTMLTextAreaElement")}} interface specifies that the user must fill in a value before submitting a form. It reflects the {{htmlelement("textarea")}} element's [`required`](/en-US/docs/Web/HTML/Reference/Elements/textarea#required) attribute. ## Value diff --git a/files/en-us/web/api/htmltextareaelement/rows/index.md b/files/en-us/web/api/htmltextareaelement/rows/index.md index 88648f54e819be7..5781477e1b5901c 100644 --- a/files/en-us/web/api/htmltextareaelement/rows/index.md +++ b/files/en-us/web/api/htmltextareaelement/rows/index.md @@ -8,7 +8,7 @@ browser-compat: api.HTMLTextAreaElement.rows {{ APIRef("HTML DOM") }} -The **`rows`** property of the {{DOMxRef("HTMLTextAreaElement")}} interface is a positive integer representing the visible text lines of the text control. It reflects the `<textarea>` element's [`rows`](/en-US/docs/Web/HTML/Element/textarea#rows) attribute. +The **`rows`** property of the {{DOMxRef("HTMLTextAreaElement")}} interface is a positive integer representing the visible text lines of the text control. It reflects the `<textarea>` element's [`rows`](/en-US/docs/Web/HTML/Reference/Elements/textarea#rows) attribute. ## Value diff --git a/files/en-us/web/api/htmltextareaelement/select_event/index.md b/files/en-us/web/api/htmltextareaelement/select_event/index.md index e8826d780a4e810..9076b3cbfbae1b3 100644 --- a/files/en-us/web/api/htmltextareaelement/select_event/index.md +++ b/files/en-us/web/api/htmltextareaelement/select_event/index.md @@ -14,10 +14,10 @@ The **`select`** event fires when some text has been selected. Use the event name in methods like {{domxref("EventTarget.addEventListener", "addEventListener()")}}, or set an event handler property. -```js -addEventListener("select", (event) => {}); +```js-nolint +addEventListener("select", (event) => { }) -onselect = (event) => {}; +onselect = (event) => { } ``` ## Event type diff --git a/files/en-us/web/api/htmltextareaelement/selectionchange_event/index.md b/files/en-us/web/api/htmltextareaelement/selectionchange_event/index.md index 0e05f956a0dd341..d76dc8c25d12308 100644 --- a/files/en-us/web/api/htmltextareaelement/selectionchange_event/index.md +++ b/files/en-us/web/api/htmltextareaelement/selectionchange_event/index.md @@ -3,14 +3,12 @@ title: "HTMLTextAreaElement: selectionchange event" short-title: selectionchange slug: Web/API/HTMLTextAreaElement/selectionchange_event page-type: web-api-event -status: - - experimental browser-compat: api.HTMLTextAreaElement.selectionchange_event --- -{{APIRef}}{{SeeCompatTable}} +{{APIRef}} -The **`selectionchange`** event of the [Selection API](/en-US/docs/Web/API/Selection) is fired when the text selection within an {{HTMLElement("textarea")}} element is changed. +The **`selectionchange`** event of the [Selection API](/en-US/docs/Web/API/Selection) is fired when the text selection within a {{HTMLElement("textarea")}} element is changed. This includes both changes in the selected range of characters, or if the caret moves. This event is not cancelable. @@ -23,10 +21,10 @@ It is also possible to add a listener on the global `onselectionchange` event ha Use the event name in methods like {{domxref("EventTarget.addEventListener", "addEventListener()")}}, or set an event handler property. -```js -addEventListener("selectionchange", (event) => {}); +```js-nolint +addEventListener("selectionchange", (event) => { }) -onselectionchange = (event) => {}; +onselectionchange = (event) => { } ``` ## Event type @@ -35,7 +33,7 @@ A generic {{domxref("Event")}}. ## Examples -The example below shows how to get the text selected in an {{HTMLElement("textarea")}} element. +The example below shows how to get the text selected in a {{HTMLElement("textarea")}} element. ### HTML diff --git a/files/en-us/web/api/htmltextareaelement/selectionstart/index.md b/files/en-us/web/api/htmltextareaelement/selectionstart/index.md index 8907ffb6b7b5918..8fe62d9598bd0c9 100644 --- a/files/en-us/web/api/htmltextareaelement/selectionstart/index.md +++ b/files/en-us/web/api/htmltextareaelement/selectionstart/index.md @@ -16,7 +16,7 @@ Setting `selectionStart` to a value greater then the current value of {{domxref( The property value can be retrieved and set without the `<textarea>` having focus, but the element does need to have focus for the {{cssxref("::selection")}} pseudo-element to match the selected text. -Setting the `selectionStart` to a new value fires the {{domxref("HTMLTextAreaElement.selectionchange_event", "selectchange")}} and {{domxref("HTMLTextAreaElement.select_event", "select")}}events. +Setting the `selectionStart` to a new value fires the {{domxref("HTMLTextAreaElement.selectionchange_event", "selectchange")}} and {{domxref("HTMLTextAreaElement.select_event", "select")}} events. ## Value diff --git a/files/en-us/web/api/htmltextareaelement/setcustomvalidity/index.md b/files/en-us/web/api/htmltextareaelement/setcustomvalidity/index.md index 31cee8a21128b66..e9e74b3af62bb51 100644 --- a/files/en-us/web/api/htmltextareaelement/setcustomvalidity/index.md +++ b/files/en-us/web/api/htmltextareaelement/setcustomvalidity/index.md @@ -59,7 +59,7 @@ if (comment.validity.valueMissing) { - {{domxref("HTMLTextAreaElement.validity")}} - {{domxref("HTMLTextAreaElement.checkValidity()")}} - {{domxref("HTMLTextAreaElement.reportValidity()")}} -- [Form validation](/en-US/docs/Web/HTML/Constraint_validation). +- [Form validation](/en-US/docs/Web/HTML/Guides/Constraint_validation). - [Learn: Client-side form validation](/en-US/docs/Learn_web_development/Extensions/Forms/Form_validation) -- [Guide: Constraint validation](/en-US/docs/Web/HTML/Constraint_validation) +- [Guide: Constraint validation](/en-US/docs/Web/HTML/Guides/Constraint_validation) - CSS {{cssxref(":valid")}} and {{cssxref(":invalid")}} pseudo-classes diff --git a/files/en-us/web/api/htmltextareaelement/setrangetext/index.md b/files/en-us/web/api/htmltextareaelement/setrangetext/index.md index 16f554001d87713..c6fc2cb58dee61d 100644 --- a/files/en-us/web/api/htmltextareaelement/setrangetext/index.md +++ b/files/en-us/web/api/htmltextareaelement/setrangetext/index.md @@ -9,7 +9,7 @@ browser-compat: api.HTMLTextAreaElement.setRangeText {{APIRef("HTML DOM")}} The **`setRangeText()`** method of the {{domxref("HTMLTextAreaElement")}} interface replaces a -range of text in an {{HTMLElement("textarea")}} element with new text passed as the argument. +range of text in a {{HTMLElement("textarea")}} element with new text passed as the argument. Additional optional parameters include the start of the section of text to change, the end of the section, and a keyword defining what part of the `<textarea>` should be selected after the text is updated. If the `startSelection` and `endSelection` arguments are not provided, the range is assumed to be the selection. diff --git a/files/en-us/web/api/htmltextareaelement/setselectionrange/index.md b/files/en-us/web/api/htmltextareaelement/setselectionrange/index.md index d9cefcd021ad5dc..981424aad631065 100644 --- a/files/en-us/web/api/htmltextareaelement/setselectionrange/index.md +++ b/files/en-us/web/api/htmltextareaelement/setselectionrange/index.md @@ -8,7 +8,7 @@ browser-compat: api.HTMLTextAreaElement.setSelectionRange {{APIRef("HTML DOM")}} -The **`setSelectionRange()`** method of the {{domxref("HTMLTextAreaElement")}} interface sets the start and end positions of the current text selection, and optionally the direction, in an {{HTMLElement("textarea")}} element. The direction indicates the in which selection should be considered to have occurred; for example, that the selection was set by the user clicking and dragging from the end of the selected text toward the beginning. In addition, the {{domxref("HTMLTextAreaElement.select_event", "select")}} and {{domxref("HTMLTextAreaElement.selectionchange_event", "selectchange")}} events are fired. +The **`setSelectionRange()`** method of the {{domxref("HTMLTextAreaElement")}} interface sets the start and end positions of the current text selection, and optionally the direction, in a {{HTMLElement("textarea")}} element. The direction indicates the in which selection should be considered to have occurred; for example, that the selection was set by the user clicking and dragging from the end of the selected text toward the beginning. In addition, the {{domxref("HTMLTextAreaElement.select_event", "select")}} and {{domxref("HTMLTextAreaElement.selectionchange_event", "selectchange")}} events are fired. This method also updates the {{domxref("HTMLTextAreaElement.selectionStart")}}, {{domxref("HTMLTextAreaElement.selectionEnd")}}, and {{domxref("HTMLTextAreaElement.selectionDirection")}} properties. diff --git a/files/en-us/web/api/htmltextareaelement/validationmessage/index.md b/files/en-us/web/api/htmltextareaelement/validationmessage/index.md index ae6cfa1636089b6..7a72fcf27541562 100644 --- a/files/en-us/web/api/htmltextareaelement/validationmessage/index.md +++ b/files/en-us/web/api/htmltextareaelement/validationmessage/index.md @@ -41,5 +41,5 @@ const errorMessage = textarea.validationMessage; - {{domxref("HTMLTextAreaElement.reportValidity()")}} - {{domxref("HTMLTextAreaElement.setCustomValidity()")}} - [Learn: Client-side form validation](/en-US/docs/Learn_web_development/Extensions/Forms/Form_validation) -- [Guide: Constraint validation](/en-US/docs/Web/HTML/Constraint_validation) +- [Guide: Constraint validation](/en-US/docs/Web/HTML/Guides/Constraint_validation) - CSS {{cssxref(":valid")}} and {{cssxref(":invalid")}} pseudo-classes diff --git a/files/en-us/web/api/htmltextareaelement/validity/index.md b/files/en-us/web/api/htmltextareaelement/validity/index.md index 8e564074321892e..297c4af12612c5f 100644 --- a/files/en-us/web/api/htmltextareaelement/validity/index.md +++ b/files/en-us/web/api/htmltextareaelement/validity/index.md @@ -40,4 +40,4 @@ if (!validityState.valid) { - {{HTMLElement("textarea")}} - {{HTMLElement("form")}} - [Learn: Client-side form validation](/en-US/docs/Learn_web_development/Extensions/Forms/Form_validation) -- [Guide: Constraint validation](/en-US/docs/Web/HTML/Constraint_validation) +- [Guide: Constraint validation](/en-US/docs/Web/HTML/Guides/Constraint_validation) diff --git a/files/en-us/web/api/htmltextareaelement/willvalidate/index.md b/files/en-us/web/api/htmltextareaelement/willvalidate/index.md index ead0b5d09501bba..b2ea8ba39d2d018 100644 --- a/files/en-us/web/api/htmltextareaelement/willvalidate/index.md +++ b/files/en-us/web/api/htmltextareaelement/willvalidate/index.md @@ -8,7 +8,7 @@ browser-compat: api.HTMLTextAreaElement.willValidate {{APIRef("HTML DOM")}} -The **`willValidate`** read-only property of the {{domxref("HTMLTextAreaElement")}} interface indicates whether the {{htmlelement("textarea")}} element is a candidate for [constraint validation](/en-US/docs/Web/HTML/Constraint_validation). It is `false` if any conditions bar it from constraint validation, such as when its {{domxref("HTMLTextAreaElement.disabled", "disabled")}} or {{domxref("HTMLTextAreaElement.readOnly", "readOnly")}} property is `true`. +The **`willValidate`** read-only property of the {{domxref("HTMLTextAreaElement")}} interface indicates whether the {{htmlelement("textarea")}} element is a candidate for [constraint validation](/en-US/docs/Web/HTML/Guides/Constraint_validation). It is `false` if any conditions bar it from constraint validation, such as when its {{domxref("HTMLTextAreaElement.disabled", "disabled")}} or {{domxref("HTMLTextAreaElement.readOnly", "readOnly")}} property is `true`. ## Value @@ -28,4 +28,4 @@ A boolean value. - {{HTMLElement("textarea")}} - {{HTMLElement("form")}} - [Learn: Client-side form validation](/en-US/docs/Learn_web_development/Extensions/Forms/Form_validation) -- [Guide: Constraint validation](/en-US/docs/Web/HTML/Constraint_validation) +- [Guide: Constraint validation](/en-US/docs/Web/HTML/Guides/Constraint_validation) diff --git a/files/en-us/web/api/htmltextareaelement/wrap/index.md b/files/en-us/web/api/htmltextareaelement/wrap/index.md index 20ca52704e46143..1b01f347f6bcfd4 100644 --- a/files/en-us/web/api/htmltextareaelement/wrap/index.md +++ b/files/en-us/web/api/htmltextareaelement/wrap/index.md @@ -8,11 +8,11 @@ browser-compat: api.HTMLTextAreaElement.wrap {{ APIRef("HTML DOM") }} -The **`wrap`** property of the {{DOMxRef("HTMLTextAreaElement")}} interface indicates how the control should wrap the value for form submission. It reflects the `<textarea>` element's [`wrap`](/en-US/docs/Web/HTML/Element/textarea#wrap) attribute. Note that the `"hard"` value only has an effect when the {{domxref("HTMLTextAreaElement.cols", "cols")}} attribute is also set. +The **`wrap`** property of the {{DOMxRef("HTMLTextAreaElement")}} interface indicates how the control should wrap the value for form submission. It reflects the `<textarea>` element's [`wrap`](/en-US/docs/Web/HTML/Reference/Elements/textarea#wrap) attribute. Note that the `"hard"` value only has an effect when the {{domxref("HTMLTextAreaElement.cols", "cols")}} attribute is also set. ## Value -See [`wrap`](/en-US/docs/Web/HTML/Element/textarea#wrap) for the possible values. Defaults to `"soft"`. +See [`wrap`](/en-US/docs/Web/HTML/Reference/Elements/textarea#wrap) for the possible values. Defaults to `"soft"`. ## Examples diff --git a/files/en-us/web/api/htmltimeelement/datetime/index.md b/files/en-us/web/api/htmltimeelement/datetime/index.md index 737066945d3dc24..b3ec03282fba51a 100644 --- a/files/en-us/web/api/htmltimeelement/datetime/index.md +++ b/files/en-us/web/api/htmltimeelement/datetime/index.md @@ -10,12 +10,12 @@ browser-compat: api.HTMLTimeElement.dateTime The **`dateTime`** -property of the {{domxref("HTMLTimeElement")}} interface is a string that reflects the [`datetime`](/en-US/docs/Web/HTML/Element/time#datetime) HTML attribute, containing a machine-readable form of the element's date and +property of the {{domxref("HTMLTimeElement")}} interface is a string that reflects the [`datetime`](/en-US/docs/Web/HTML/Reference/Elements/time#datetime) HTML attribute, containing a machine-readable form of the element's date and time value. ## Value -A string. For valid string formats, see the [`datetime` valid values](/en-US/docs/Web/HTML/Element/time#valid_datetime_values). +A string. For valid string formats, see the [`datetime` valid values](/en-US/docs/Web/HTML/Reference/Elements/time#valid_datetime_values). ## Examples @@ -38,5 +38,5 @@ t.dateTime = "6w 5h 34m 5s"; - {{domxref("HTMLTimeElement")}} - {{domxref("HTMLModElement.dateTime")}} -- [Date strings](/en-US/docs/Web/HTML/Date_and_time_formats#date_strings) -- [Local date and time strings](/en-US/docs/Web/HTML/Date_and_time_formats#local_date_and_time_strings) +- [Date strings](/en-US/docs/Web/HTML/Guides/Date_and_time_formats#date_strings) +- [Local date and time strings](/en-US/docs/Web/HTML/Guides/Date_and_time_formats#local_date_and_time_strings) diff --git a/files/en-us/web/api/htmltimeelement/index.md b/files/en-us/web/api/htmltimeelement/index.md index b8125dfb12ce0ba..e28a9491b69def4 100644 --- a/files/en-us/web/api/htmltimeelement/index.md +++ b/files/en-us/web/api/htmltimeelement/index.md @@ -16,7 +16,7 @@ The **`HTMLTimeElement`** interface provides special properties (beyond the regu _Inherits properties from its parent, {{domxref("HTMLElement")}}._ - {{domxref("HTMLTimeElement.dateTime")}} - - : A string that reflects the [`datetime`](/en-US/docs/Web/HTML/Element/time#datetime) HTML attribute, containing a machine-readable form of the element's date and time value. + - : A string that reflects the [`datetime`](/en-US/docs/Web/HTML/Reference/Elements/time#datetime) HTML attribute, containing a machine-readable form of the element's date and time value. ## Instance methods diff --git a/files/en-us/web/api/htmltrackelement/cuechange_event/index.md b/files/en-us/web/api/htmltrackelement/cuechange_event/index.md index b74493ac812e4f9..d00fd5a39469261 100644 --- a/files/en-us/web/api/htmltrackelement/cuechange_event/index.md +++ b/files/en-us/web/api/htmltrackelement/cuechange_event/index.md @@ -14,10 +14,10 @@ The **`cuechange`** event fires when a {{domxref("TextTrack")}} has changed the Use the event name in methods like {{domxref("EventTarget.addEventListener", "addEventListener()")}}, or set an event handler property. -```js -addEventListener("cuechange", (event) => {}); +```js-nolint +addEventListener("cuechange", (event) => { }) -oncuechange = (event) => {}; +oncuechange = (event) => { } ``` ## Event type diff --git a/files/en-us/web/api/htmltrackelement/default/index.md b/files/en-us/web/api/htmltrackelement/default/index.md index 8b6d510f70e8393..03baaa7ebb495c1 100644 --- a/files/en-us/web/api/htmltrackelement/default/index.md +++ b/files/en-us/web/api/htmltrackelement/default/index.md @@ -8,7 +8,7 @@ browser-compat: api.HTMLTrackElement.default {{ApiRef("HTML DOM")}} -The **`default`** property of the {{domxref("HTMLTrackElement")}} interface represents whether the track will be enabled if the user's preferences do not indicate that another track would be more appropriate. It reflects the {{htmlelement("track")}} element's boolean [`default`](/en-US/docs/Web/HTML/Element/track#default) attribute, returning `true` if present and `false` otherwise. +The **`default`** property of the {{domxref("HTMLTrackElement")}} interface represents whether the track will be enabled if the user's preferences do not indicate that another track would be more appropriate. It reflects the {{htmlelement("track")}} element's boolean [`default`](/en-US/docs/Web/HTML/Reference/Elements/track#default) attribute, returning `true` if present and `false` otherwise. ## Value diff --git a/files/en-us/web/api/htmltrackelement/index.md b/files/en-us/web/api/htmltrackelement/index.md index 6037863307f7ea9..0d21a14f2da090d 100644 --- a/files/en-us/web/api/htmltrackelement/index.md +++ b/files/en-us/web/api/htmltrackelement/index.md @@ -16,15 +16,15 @@ The **`HTMLTrackElement`** interface represents an {{Glossary("HTML")}} {{HTMLEl _Inherits properties from its parent, {{domxref("HTMLElement")}}._ - {{domxref("HTMLTrackElement.kind")}} - - : A string that reflects the [`kind`](/en-US/docs/Web/HTML/Element/track#kind) HTML attribute, indicating how the text track is meant to be used. Possible values are: `subtitles`, `captions`, `descriptions`, `chapters`, or `metadata`. + - : A string that reflects the [`kind`](/en-US/docs/Web/HTML/Reference/Elements/track#kind) HTML attribute, indicating how the text track is meant to be used. Possible values are: `subtitles`, `captions`, `descriptions`, `chapters`, or `metadata`. - {{domxref("HTMLTrackElement.src")}} - - : A string that reflects the [`src`](/en-US/docs/Web/HTML/Element/track#src) HTML attribute, indicating the address of the text track data. + - : A string that reflects the [`src`](/en-US/docs/Web/HTML/Reference/Elements/track#src) HTML attribute, indicating the address of the text track data. - {{domxref("HTMLTrackElement.srclang")}} - - : A string that reflects the [`srclang`](/en-US/docs/Web/HTML/Element/track#srclang) HTML attribute, indicating the language of the text track data. + - : A string that reflects the [`srclang`](/en-US/docs/Web/HTML/Reference/Elements/track#srclang) HTML attribute, indicating the language of the text track data. - {{domxref("HTMLTrackElement.label")}} - - : A string that reflects the [`label`](/en-US/docs/Web/HTML/Element/track#label) HTML attribute, indicating a user-readable title for the track. + - : A string that reflects the [`label`](/en-US/docs/Web/HTML/Reference/Elements/track#label) HTML attribute, indicating a user-readable title for the track. - {{domxref("HTMLTrackElement.default")}} - - : A boolean value reflecting the [`default`](/en-US/docs/Web/HTML/Element/track#default) attribute, indicating that the track is to be enabled if the user's preferences do not indicate that another track would be more appropriate. + - : A boolean value reflecting the [`default`](/en-US/docs/Web/HTML/Reference/Elements/track#default) attribute, indicating that the track is to be enabled if the user's preferences do not indicate that another track would be more appropriate. - {{domxref("HTMLTrackElement.readyState")}} {{ReadOnlyInline}} - : Returns an `unsigned short` that show the readiness state of the track: diff --git a/files/en-us/web/api/htmltrackelement/kind/index.md b/files/en-us/web/api/htmltrackelement/kind/index.md index 8ffc10a9bfb4fae..d2c47f40b063e26 100644 --- a/files/en-us/web/api/htmltrackelement/kind/index.md +++ b/files/en-us/web/api/htmltrackelement/kind/index.md @@ -8,7 +8,7 @@ browser-compat: api.HTMLTrackElement.kind {{ApiRef("HTML DOM")}} -The **`kind`** property of the {{domxref("HTMLTrackElement")}} interface represents the type of track, or how the text track is meant to be used. It reflects the {{htmlelement("track")}} element's enumerated [`kind`](/en-US/docs/Web/HTML/Element/track#kind) attribute. +The **`kind`** property of the {{domxref("HTMLTrackElement")}} interface represents the type of track, or how the text track is meant to be used. It reflects the {{htmlelement("track")}} element's enumerated [`kind`](/en-US/docs/Web/HTML/Reference/Elements/track#kind) attribute. If no `kind` is set, `subtitles` is used. If the attribute is not set to one of the valid enumerated values, it is invalid and `metadata` is used. Other valid values include `captions`, `descriptions`, and `chapters`. diff --git a/files/en-us/web/api/htmltrackelement/label/index.md b/files/en-us/web/api/htmltrackelement/label/index.md index 8accf12c074cac8..0d1733e72c2addc 100644 --- a/files/en-us/web/api/htmltrackelement/label/index.md +++ b/files/en-us/web/api/htmltrackelement/label/index.md @@ -8,7 +8,7 @@ browser-compat: api.HTMLTrackElement.label {{ApiRef("HTML DOM")}} -The **`label`** property of the {{domxref("HTMLTrackElement")}} represents the user-readable title displayed when listing subtitle, caption, and audio descriptions for a track. It reflects the {{htmlelement("track")}} element's [`label`](/en-US/docs/Web/HTML/Element/track#label) attribute. +The **`label`** property of the {{domxref("HTMLTrackElement")}} represents the user-readable title displayed when listing subtitle, caption, and audio descriptions for a track. It reflects the {{htmlelement("track")}} element's [`label`](/en-US/docs/Web/HTML/Reference/Elements/track#label) attribute. ## Value diff --git a/files/en-us/web/api/htmltrackelement/src/index.md b/files/en-us/web/api/htmltrackelement/src/index.md index a252e81ce474228..2c32ce73867766e 100644 --- a/files/en-us/web/api/htmltrackelement/src/index.md +++ b/files/en-us/web/api/htmltrackelement/src/index.md @@ -9,7 +9,7 @@ browser-compat: api.HTMLTrackElement.src {{APIRef("HTML DOM")}} The **`src`** property of the {{domxref("HTMLTrackElement")}} interface reflects the value of -the {{HTMLElement("track")}} element's [`src`](/en-US/docs/Web/HTML/Element/track#src) attribute, which +the {{HTMLElement("track")}} element's [`src`](/en-US/docs/Web/HTML/Reference/Elements/track#src) attribute, which indicates the URL of the text track's data. ## Value diff --git a/files/en-us/web/api/htmltrackelement/srclang/index.md b/files/en-us/web/api/htmltrackelement/srclang/index.md index c7292b54bcee044..0225fccf6a1f6a0 100644 --- a/files/en-us/web/api/htmltrackelement/srclang/index.md +++ b/files/en-us/web/api/htmltrackelement/srclang/index.md @@ -9,9 +9,9 @@ browser-compat: api.HTMLTrackElement.srclang {{APIRef("HTML DOM")}} The **`srclang`** property of the {{domxref("HTMLTrackElement")}} interface reflects the value of -the {{HTMLElement("track")}} element's [`srclang`](/en-US/docs/Web/HTML/Element/track#srclang) attribute or the empty string if not defined. +the {{HTMLElement("track")}} element's [`srclang`](/en-US/docs/Web/HTML/Reference/Elements/track#srclang) attribute or the empty string if not defined. -The `srclang` attribute is a [BCP 47 language tag](/en-US/docs/Web/HTML/Global_attributes/lang#language_tag_syntax) +The `srclang` attribute is a [BCP 47 language tag](/en-US/docs/Web/HTML/Reference/Global_attributes/lang#language_tag_syntax) indicating the language of the text track's data. ## Value @@ -38,4 +38,4 @@ trackElement.srclang = "en-US"; - {{domxref("HTMLTrackElement")}} - {{HTMLElement("track")}} -- [`lang` syntax](/en-US/docs/Web/HTML/Global_attributes/lang#language_tag_syntax) +- [`lang` syntax](/en-US/docs/Web/HTML/Reference/Global_attributes/lang#language_tag_syntax) diff --git a/files/en-us/web/api/htmlulistelement/index.md b/files/en-us/web/api/htmlulistelement/index.md index 59f1556637fd6af..77475fa35a052ff 100644 --- a/files/en-us/web/api/htmlulistelement/index.md +++ b/files/en-us/web/api/htmlulistelement/index.md @@ -16,9 +16,9 @@ The **`HTMLUListElement`** interface provides special properties (beyond those d _Inherits properties from its parent, {{domxref("HTMLElement")}}._ - {{domxref("HTMLUListElement.type")}} {{deprecated_inline}} - - : A string value reflecting the [`type`](/en-US/docs/Web/HTML/Element/ul#type) and defining the kind of marker to be used to display. The values are browser dependent and have never been standardized. + - : A string value reflecting the [`type`](/en-US/docs/Web/HTML/Reference/Elements/ul#type) and defining the kind of marker to be used to display. The values are browser dependent and have never been standardized. - {{domxref("HTMLUListElement.compact")}} {{deprecated_inline}} - - : A boolean value indicating that spacing between list items should be reduced. This property reflects the [`compact`](/en-US/docs/Web/HTML/Element/ul#compact) attribute only, it doesn't consider the {{cssxref("line-height")}} CSS property used for that behavior in modern pages. + - : A boolean value indicating that spacing between list items should be reduced. This property reflects the [`compact`](/en-US/docs/Web/HTML/Reference/Elements/ul#compact) attribute only, it doesn't consider the {{cssxref("line-height")}} CSS property used for that behavior in modern pages. ## Instance methods diff --git a/files/en-us/web/api/htmlvideoelement/cancelvideoframecallback/index.md b/files/en-us/web/api/htmlvideoelement/cancelvideoframecallback/index.md index 58eb02605c10e36..e6c824611b8a02b 100644 --- a/files/en-us/web/api/htmlvideoelement/cancelvideoframecallback/index.md +++ b/files/en-us/web/api/htmlvideoelement/cancelvideoframecallback/index.md @@ -35,7 +35,7 @@ This example shows how to use `cancelVideoFrameCallback()` to cancel a previousl const updateCanvas = (now, metadata) => { // Do something with the frame - // ... + // … // Re-register the callback to run on the next frame // It's important to update the videoCallbackId on each iteration @@ -46,7 +46,7 @@ const updateCanvas = (now, metadata) => { // Initial registration of the callback to run on the first frame let videoCallbackId = video.requestVideoFrameCallback(updateCanvas); -// ... +// … // Cancel video frame callback using the latest videoCallbackId video.cancelVideoFrameCallback(videoCallbackId); diff --git a/files/en-us/web/api/htmlvideoelement/enterpictureinpicture_event/index.md b/files/en-us/web/api/htmlvideoelement/enterpictureinpicture_event/index.md index 8bdf04e1f6ced43..9c7c8bb918f3cd3 100644 --- a/files/en-us/web/api/htmlvideoelement/enterpictureinpicture_event/index.md +++ b/files/en-us/web/api/htmlvideoelement/enterpictureinpicture_event/index.md @@ -16,10 +16,10 @@ This event is not cancelable and does not bubble. Use the event name in methods like {{domxref("EventTarget.addEventListener", "addEventListener()")}}, or set an event handler property. -```js -addEventListener("enterpictureinpicture", (event) => {}); +```js-nolint +addEventListener("enterpictureinpicture", (event) => { }) -onenterpictureinpicture = (event) => {}; +onenterpictureinpicture = (event) => { } ``` ## Event type diff --git a/files/en-us/web/api/htmlvideoelement/index.md b/files/en-us/web/api/htmlvideoelement/index.md index 4c6e617f8995477..aa8b59a7a8c9135 100644 --- a/files/en-us/web/api/htmlvideoelement/index.md +++ b/files/en-us/web/api/htmlvideoelement/index.md @@ -20,15 +20,15 @@ _Inherits properties from its parent interface, {{domxref("HTMLMediaElement")}}, - {{DOMxRef("HTMLVideoElement.disablePictureInPicture")}} - : Indicates if the user agent should suggest the picture-in-picture to users, or not. - {{domxref("HTMLVideoElement.height")}} - - : A string that reflects the [`height`](/en-US/docs/Web/HTML/Element/video#height) HTML attribute, which specifies the height of the display area, in CSS pixels. + - : A string that reflects the [`height`](/en-US/docs/Web/HTML/Reference/Elements/video#height) HTML attribute, which specifies the height of the display area, in CSS pixels. - {{domxref("HTMLVideoElement.poster")}} - - : A string that reflects the [`poster`](/en-US/docs/Web/HTML/Element/video#poster) HTML attribute, which specifies an image to show while no video data is available. + - : A string that reflects the [`poster`](/en-US/docs/Web/HTML/Reference/Elements/video#poster) HTML attribute, which specifies an image to show while no video data is available. - {{domxref("HTMLVideoElement.videoHeight")}} {{ReadOnlyInline}} - : Returns an unsigned integer value indicating the intrinsic height of the resource in CSS pixels, or 0 if no media is available yet. - {{domxref("HTMLVideoElement.videoWidth")}} {{ReadOnlyInline}} - : Returns an unsigned integer value indicating the intrinsic width of the resource in CSS pixels, or 0 if no media is available yet. - {{domxref("HTMLVideoElement.width")}} - - : A string that reflects the [`width`](/en-US/docs/Web/HTML/Element/video#width) HTML attribute, which specifies the width of the display area, in CSS pixels. + - : A string that reflects the [`width`](/en-US/docs/Web/HTML/Reference/Elements/video#width) HTML attribute, which specifies the width of the display area, in CSS pixels. ### Firefox-specific properties diff --git a/files/en-us/web/api/htmlvideoelement/leavepictureinpicture_event/index.md b/files/en-us/web/api/htmlvideoelement/leavepictureinpicture_event/index.md index 16f0f3f255f0110..7b38742fa50bfbe 100644 --- a/files/en-us/web/api/htmlvideoelement/leavepictureinpicture_event/index.md +++ b/files/en-us/web/api/htmlvideoelement/leavepictureinpicture_event/index.md @@ -16,10 +16,10 @@ This event is not cancelable and does not bubble. Use the event name in methods like {{domxref("EventTarget.addEventListener", "addEventListener()")}}, or set an event handler property. -```js -addEventListener("leavepictureinpicture", (event) => {}); +```js-nolint +addEventListener("leavepictureinpicture", (event) => { }) -onleavepictureinpicture = (event) => {}; +onleavepictureinpicture = (event) => { } ``` ## Event type diff --git a/files/en-us/web/api/htmlvideoelement/requestpictureinpicture/index.md b/files/en-us/web/api/htmlvideoelement/requestpictureinpicture/index.md index 3fcc0b0ee542280..a902f199c757bad 100644 --- a/files/en-us/web/api/htmlvideoelement/requestpictureinpicture/index.md +++ b/files/en-us/web/api/htmlvideoelement/requestpictureinpicture/index.md @@ -36,7 +36,7 @@ object that can be used to listen when a user will resize that floating window. - `NotSupportedError` {{domxref("DOMException")}} - : Thrown if the feature is not supported (for example, disabled by a user preference or by a platform limitation). - `SecurityError` {{domxref("DOMException")}} - - : Thrown if the feature is blocked by a [Permissions Policy](/en-US/docs/Web/HTTP/Permissions_Policy). + - : Thrown if the feature is blocked by a [Permissions Policy](/en-US/docs/Web/HTTP/Guides/Permissions_Policy). - `InvalidStateError` {{domxref("DOMException")}} - : Thrown if the video element's `readState` is `HAVE_NOTHING`, or if the video element has no video track, or if the video element's `disablePictureInPicture` attribute is `true`. - `NotAllowedError` {{domxref("DOMException")}} diff --git a/files/en-us/web/api/htmlvideoelement/resize_event/index.md b/files/en-us/web/api/htmlvideoelement/resize_event/index.md index d07cfda735d30c9..72fd2f09012cd74 100644 --- a/files/en-us/web/api/htmlvideoelement/resize_event/index.md +++ b/files/en-us/web/api/htmlvideoelement/resize_event/index.md @@ -16,10 +16,10 @@ This event is not cancelable but may bubble. Use the event name in methods like {{domxref("EventTarget.addEventListener", "addEventListener()")}}, or set an event handler property. -```js -addEventListener("resize", (event) => {}); +```js-nolint +addEventListener("resize", (event) => { }) -onresize = (event) => {}; +onresize = (event) => { } ``` ## Event type diff --git a/files/en-us/web/api/idbdatabase/close_event/index.md b/files/en-us/web/api/idbdatabase/close_event/index.md index d338bb805f022cc..4cf4f8a68f90908 100644 --- a/files/en-us/web/api/idbdatabase/close_event/index.md +++ b/files/en-us/web/api/idbdatabase/close_event/index.md @@ -16,9 +16,10 @@ Note that it is not fired if the database connection is closed normally using [` Use the event name in methods like {{domxref("EventTarget.addEventListener", "addEventListener()")}}, or set an event handler property. -```js -addEventListener("close", (event) => {}); -onclose = (event) => {}; +```js-nolint +addEventListener("close", (event) => { }) + +onclose = (event) => { } ``` ## Event type diff --git a/files/en-us/web/api/idbdatabase/version/index.md b/files/en-us/web/api/idbdatabase/version/index.md index e65b7e0dbba9d86..146427e22c877df 100644 --- a/files/en-us/web/api/idbdatabase/version/index.md +++ b/files/en-us/web/api/idbdatabase/version/index.md @@ -9,7 +9,7 @@ browser-compat: api.IDBDatabase.version {{ APIRef("IndexedDB") }} {{AvailableInWorkers}} The **`version`** property of the {{domxref("IDBDatabase")}} -interface is a [64-bit integer](/en-US/docs/NSPR_API_Reference/Long_Long_%2864-bit%29_Integers) +interface is a 64-bit integer that contains the version of the connected database. When a database is first created, this attribute is an empty string. diff --git a/files/en-us/web/api/idbdatabase/versionchange_event/index.md b/files/en-us/web/api/idbdatabase/versionchange_event/index.md index 161229ff9c2bd35..b97b1f69291e19c 100644 --- a/files/en-us/web/api/idbdatabase/versionchange_event/index.md +++ b/files/en-us/web/api/idbdatabase/versionchange_event/index.md @@ -15,9 +15,10 @@ another window/tab on the same computer). Use the event name in methods like {{domxref("EventTarget.addEventListener", "addEventListener()")}}, or set an event handler property. -```js -addEventListener("versionchange", (event) => {}); -onversionchange = (event) => {}; +```js-nolint +addEventListener("versionchange", (event) => { }) + +onversionchange = (event) => { } ``` ## Event type diff --git a/files/en-us/web/api/idbobjectstore/createindex/index.md b/files/en-us/web/api/idbobjectstore/createindex/index.md index 42655e654ae07e8..16f70b7eb313d7f 100644 --- a/files/en-us/web/api/idbobjectstore/createindex/index.md +++ b/files/en-us/web/api/idbobjectstore/createindex/index.md @@ -46,7 +46,7 @@ createIndex(indexName, keyPath, options) - : Allows you to specify a locale for the index. Any sorting operations performed on the data via key ranges will then obey sorting rules of that locale. You can specify its value in one of three ways: - - `string`: A string containing a specific locale code, e.g. `en-US`, or `pl`. + - `string`: A string containing a specific locale code, e.g., `en-US`, or `pl`. - `auto`: The platform default locale will be used (may be changed by user agent settings). - `null` or `undefined`: If no locale is specified, normal JavaScript sorting will be used — not locale-aware. @@ -64,13 +64,13 @@ This method may raise a {{domxref("DOMException")}} of one of the following type - : Thrown if the provided key path is a sequence, and `multiEntry` is set to `true` in the `objectParameters` object. - `InvalidStateError` {{domxref("DOMException")}} - : Thrown if: - - The method was not called from a `versionchange` transaction mode callback, i.e. from inside a {{domxref("IDBOpenDBRequest.upgradeneeded_event", "onupgradeneeded")}} handler. + - The method was not called from a `versionchange` transaction mode callback, i.e., from inside a {{domxref("IDBOpenDBRequest.upgradeneeded_event", "onupgradeneeded")}} handler. - The object store has been deleted. - `SyntaxError` {{domxref("DOMException")}} - - : Thrown if the provided `keyPath` is not a <a href="https://www.w3.org/TR/IndexedDB/#dfn-valid-key-path">valid key path</a>. + - : Thrown if the provided `keyPath` is not a [valid key path](https://w3c.github.io/IndexedDB/#valid-key-path). - `TransactionInactiveError` {{domxref("DOMException")}} - : Thrown if the transaction this {{domxref("IDBObjectStore")}} - belongs to is not active (e.g. has been deleted or removed.) In Firefox + belongs to is not active (e.g., has been deleted or removed.) In Firefox previous to version 41, an `InvalidStateError` was raised in this case as well, which was misleading; this has now been fixed (see [Firefox bug 1176165](https://bugzil.la/1176165).) diff --git a/files/en-us/web/api/idbobjectstore/deleteindex/index.md b/files/en-us/web/api/idbobjectstore/deleteindex/index.md index eb387539ad401df..b2399cc32338996 100644 --- a/files/en-us/web/api/idbobjectstore/deleteindex/index.md +++ b/files/en-us/web/api/idbobjectstore/deleteindex/index.md @@ -36,7 +36,7 @@ None ({{jsxref("undefined")}}). - `InvalidStateError` {{domxref("DOMException")}} - : Thrown if the method was not called from a `versionchange` transaction mode callback. - `TransactionInactiveError` {{domxref("DOMException")}} - - : Thrown if the transaction this {{domxref("IDBObjectStore")}} belongs to is not active (e.g. has been deleted or removed.) + - : Thrown if the transaction this {{domxref("IDBObjectStore")}} belongs to is not active (e.g., has been deleted or removed.) - `NotFoundError` {{domxref("DOMException")}} - : Thrown if there is no index with the given name (case-sensitive) in the database. @@ -76,7 +76,7 @@ DBOpenRequest.onsuccess = (event) => { // This event handles the event whereby a new version of the database needs to be created // Either one has not been created before, or a new version number has been submitted via the // window.indexedDB.open line above -//it is only implemented in recent browsers +// it is only implemented in recent browsers DBOpenRequest.onupgradeneeded = (event) => { const db = event.target.result; diff --git a/files/en-us/web/api/idbobjectstore/opencursor/index.md b/files/en-us/web/api/idbobjectstore/opencursor/index.md index 651a773add07023..ad940c1197cc82f 100644 --- a/files/en-us/web/api/idbobjectstore/opencursor/index.md +++ b/files/en-us/web/api/idbobjectstore/opencursor/index.md @@ -13,9 +13,6 @@ The **`openCursor()`** method of the and, in a separate thread, returns a new {{domxref("IDBCursorWithValue")}} object. Used for iterating through an object store with a cursor. -To determine if the add operation has completed successfully, listen for the results's -`success` event. - ## Syntax ```js-nolint diff --git a/files/en-us/web/api/idbobjectstore/put/index.md b/files/en-us/web/api/idbobjectstore/put/index.md index a3fbb0bd565bd0c..dd3a4aef85cd218 100644 --- a/files/en-us/web/api/idbobjectstore/put/index.md +++ b/files/en-us/web/api/idbobjectstore/put/index.md @@ -32,7 +32,7 @@ put(item, key) - `item` - : The item you wish to update (or insert). - `key` {{optional_inline}} - - : The primary key of the record you want to update (e.g. from + - : The primary key of the record you want to update (e.g., from {{domxref("IDBCursor.primaryKey")}}). ### Return value diff --git a/files/en-us/web/api/idbopendbrequest/blocked_event/index.md b/files/en-us/web/api/idbopendbrequest/blocked_event/index.md index 55ca793e0d343a5..375e2d72865d3c1 100644 --- a/files/en-us/web/api/idbopendbrequest/blocked_event/index.md +++ b/files/en-us/web/api/idbopendbrequest/blocked_event/index.md @@ -16,10 +16,10 @@ This event is not cancelable and does not bubble. Use the event name in methods like {{domxref("EventTarget.addEventListener", "addEventListener()")}}, or set an event handler property. -```js -addEventListener("blocked", (event) => {}); +```js-nolint +addEventListener("blocked", (event) => { }) -onblocked = (event) => {}; +onblocked = (event) => { } ``` ## Event type diff --git a/files/en-us/web/api/idbopendbrequest/upgradeneeded_event/index.md b/files/en-us/web/api/idbopendbrequest/upgradeneeded_event/index.md index 4514a50c85a2697..5b736ecf3d1df81 100644 --- a/files/en-us/web/api/idbopendbrequest/upgradeneeded_event/index.md +++ b/files/en-us/web/api/idbopendbrequest/upgradeneeded_event/index.md @@ -16,10 +16,10 @@ This event is not cancelable and does not bubble. Use the event name in methods like {{domxref("EventTarget.addEventListener", "addEventListener()")}}, or set an event handler property. -```js -addEventListener("upgradeneeded", (event) => {}); +```js-nolint +addEventListener("upgradeneeded", (event) => { }) -onupgradeneeded = (event) => {}; +onupgradeneeded = (event) => { } ``` ## Event type diff --git a/files/en-us/web/api/idbrequest/error/index.md b/files/en-us/web/api/idbrequest/error/index.md index 3b374d5eb97bdc8..40adb437907bfd9 100644 --- a/files/en-us/web/api/idbrequest/error/index.md +++ b/files/en-us/web/api/idbrequest/error/index.md @@ -16,7 +16,7 @@ request. A {{domxref("DOMException")}} or `null` if there is no error. The exception object will have one of the following names, depending on what caused the error. -These errors are asynchronous, meaning that they can't be handled via [`try...catch`](/en-US/docs/Web/JavaScript/Reference/Statements/try...catch). However, if an `IDBRequest` has an {{domxref("IDBRequest.error", "error")}} event handler assigned, you can still inspect such errors by querying the request's `error` property via the event object, for example [`event.target.error.name`](/en-US/docs/Web/API/DOMException/name) or [`event.target.error.message`](/en-US/docs/Web/API/DOMException/message). +These errors are asynchronous, meaning that they can't be handled via [`try...catch`](/en-US/docs/Web/JavaScript/Reference/Statements/try...catch). However, if an `IDBRequest` has an {{domxref("IDBRequest.error_event", "error")}} event handler assigned, you can still inspect such errors by querying the request's `error` property via the event object, for example [`event.target.error.name`](/en-US/docs/Web/API/DOMException/name) or [`event.target.error.message`](/en-US/docs/Web/API/DOMException/message). - `AbortError` - : If you abort the transaction, then all requests still in progress receive this error. diff --git a/files/en-us/web/api/idbrequest/error_event/index.md b/files/en-us/web/api/idbrequest/error_event/index.md index 37ab11f669cd0f5..06310e5f8f8a75f 100644 --- a/files/en-us/web/api/idbrequest/error_event/index.md +++ b/files/en-us/web/api/idbrequest/error_event/index.md @@ -16,10 +16,10 @@ This event is not cancelable and does not bubble. Use the event name in methods like {{domxref("EventTarget.addEventListener", "addEventListener()")}}, or set an event handler property. -```js -addEventListener("error", (event) => {}); +```js-nolint +addEventListener("error", (event) => { }) -onerror = (event) => {}; +onerror = (event) => { } ``` ## Event type diff --git a/files/en-us/web/api/idbrequest/success_event/index.md b/files/en-us/web/api/idbrequest/success_event/index.md index a71f20e83df1850..d548ddec3062cee 100644 --- a/files/en-us/web/api/idbrequest/success_event/index.md +++ b/files/en-us/web/api/idbrequest/success_event/index.md @@ -16,10 +16,10 @@ This event is not cancelable and does not bubble. Use the event name in methods like {{domxref("EventTarget.addEventListener", "addEventListener()")}}, or set an event handler property. -```js -addEventListener("success", (event) => {}); +```js-nolint +addEventListener("success", (event) => { }) -onsuccess = (event) => {}; +onsuccess = (event) => { } ``` ## Event type diff --git a/files/en-us/web/api/idbtransaction/abort_event/index.md b/files/en-us/web/api/idbtransaction/abort_event/index.md index f66ca6440661fc2..b9281b116f5e989 100644 --- a/files/en-us/web/api/idbtransaction/abort_event/index.md +++ b/files/en-us/web/api/idbtransaction/abort_event/index.md @@ -24,9 +24,10 @@ This non-cancelable event [bubbles](/en-US/docs/Learn_web_development/Core/Scrip Use the event name in methods like {{domxref("EventTarget.addEventListener", "addEventListener()")}}, or set an event handler property. -```js -addEventListener("abort", (event) => {}); -onabort = (event) => {}; +```js-nolint +addEventListener("abort", (event) => { }) + +onabort = (event) => { } ``` ## Event type diff --git a/files/en-us/web/api/idbtransaction/complete_event/index.md b/files/en-us/web/api/idbtransaction/complete_event/index.md index cad6b395caea0ba..acd547cc422f127 100644 --- a/files/en-us/web/api/idbtransaction/complete_event/index.md +++ b/files/en-us/web/api/idbtransaction/complete_event/index.md @@ -14,9 +14,10 @@ The **`complete`** event of the [IndexedDB API](/en-US/docs/Web/API/IndexedDB_AP Use the event name in methods like {{domxref("EventTarget.addEventListener", "addEventListener()")}}, or set an event handler property. -```js -addEventListener("complete", (event) => {}); -oncomplete = (event) => {}; +```js-nolint +addEventListener("complete", (event) => { }) + +oncomplete = (event) => { } ``` ## Event type diff --git a/files/en-us/web/api/idbtransaction/error_event/index.md b/files/en-us/web/api/idbtransaction/error_event/index.md index 300c1b7ec1dbc89..692ecbdd4dbf84a 100644 --- a/files/en-us/web/api/idbtransaction/error_event/index.md +++ b/files/en-us/web/api/idbtransaction/error_event/index.md @@ -17,9 +17,10 @@ The `error` event is fired on `IDBTransaction` when a request returns an error a Use the event name in methods like {{domxref("EventTarget.addEventListener", "addEventListener()")}}, or set an event handler property. -```js -addEventListener("error", (event) => {}); -onerror = (event) => {}; +```js-nolint +addEventListener("error", (event) => { }) + +onerror = (event) => { } ``` ## Event type diff --git a/files/en-us/web/api/idbtransaction/index.md b/files/en-us/web/api/idbtransaction/index.md index 35a4208edcfff15..95a6b1615cc2c66 100644 --- a/files/en-us/web/api/idbtransaction/index.md +++ b/files/en-us/web/api/idbtransaction/index.md @@ -7,7 +7,7 @@ browser-compat: api.IDBTransaction {{APIRef("IndexedDB")}} {{AvailableInWorkers}} -The **`IDBTransaction`** interface of the [IndexedDB API](/en-US/docs/Web/API/IndexedDB_API) provides a static, asynchronous transaction on a database using event handler attributes. All reading and writing of data is done within transactions. You use {{domxref("IDBDatabase")}} to start transactions, `IDBTransaction` to set the mode of the transaction (e.g. is it `readonly` or `readwrite`), and you access an {{domxref("IDBObjectStore")}} to make a request. You can also use an `IDBTransaction` object to abort transactions. +The **`IDBTransaction`** interface of the [IndexedDB API](/en-US/docs/Web/API/IndexedDB_API) provides a static, asynchronous transaction on a database using event handler attributes. All reading and writing of data is done within transactions. You use {{domxref("IDBDatabase")}} to start transactions, `IDBTransaction` to set the mode of the transaction (e.g., is it `readonly` or `readwrite`), and you access an {{domxref("IDBObjectStore")}} to make a request. You can also use an `IDBTransaction` object to abort transactions. {{InheritanceDiagram}} @@ -30,10 +30,10 @@ A transaction alternates between _active_ and _inactive_ states between event lo Transactions can fail for a fixed number of reasons, all of which (except the user agent crash) will trigger an abort callback: -- Abort due to bad requests, e.g. trying to `add()` the same key twice, or `put()` with the same index key with a uniqueness constraint. This causes an error on the request, which can bubble up to an error on the transaction, which aborts the transaction. This can be prevented by using `preventDefault()` on the error event on the request. +- Abort due to bad requests, e.g., trying to `add()` the same key twice, or `put()` with the same index key with a uniqueness constraint. This causes an error on the request, which can bubble up to an error on the transaction, which aborts the transaction. This can be prevented by using `preventDefault()` on the error event on the request. - An explicit `abort()` call from script. - An uncaught exception in the request's `success`/`error` handler. -- An I/O error (e.g. an actual failure to write to disk, or other OS/hardware failure). +- An I/O error (e.g., an actual failure to write to disk, or other OS/hardware failure). - Quota exceeded. - A user agent crash. @@ -41,7 +41,7 @@ Transactions can fail for a fixed number of reasons, all of which (except the us Note that as of Firefox 40, IndexedDB transactions have relaxed durability guarantees to increase performance (see [Firefox bug 1112702](https://bugzil.la/1112702).) Previously in a `readwrite` transaction, a {{domxref("IDBTransaction.complete_event","complete")}} event was fired only when all data was guaranteed to have been flushed to disk. In Firefox 40+ the `complete` event is fired after the OS has been told to write the data but potentially before that data has actually been flushed to disk. The `complete` event may thus be delivered quicker than before, however, there exists a small chance that the entire transaction will be lost if the OS crashes or there is a loss of system power before the data is flushed to disk. Since such catastrophic events are rare, most consumers should not need to concern themselves further. -If you must ensure durability for some reason (e.g. you're storing critical data that cannot be recomputed later) you can force a transaction to flush to disk before delivering the `complete` event by creating a transaction using the experimental (non-standard) `readwriteflush` mode (see {{domxref("IDBDatabase.transaction")}}. +If you must ensure durability for some reason (e.g., you're storing critical data that cannot be recomputed later) you can force a transaction to flush to disk before delivering the `complete` event by creating a transaction using the experimental (non-standard) `readwriteflush` mode (see {{domxref("IDBDatabase.transaction")}}. ## Instance properties diff --git a/files/en-us/web/api/idbtransaction/mode/index.md b/files/en-us/web/api/idbtransaction/mode/index.md index e2611fea3d58dc2..14cc85027213625 100644 --- a/files/en-us/web/api/idbtransaction/mode/index.md +++ b/files/en-us/web/api/idbtransaction/mode/index.md @@ -10,7 +10,7 @@ browser-compat: api.IDBTransaction.mode The **`mode`** read-only property of the {{domxref("IDBTransaction")}} interface returns the current mode for accessing the -data in the object stores in the scope of the transaction (i.e. is the mode to be +data in the object stores in the scope of the transaction (i.e., is the mode to be read-only, or do you want to write to the object stores?) The default value is `readonly`. diff --git a/files/en-us/web/api/identitycredential/index.md b/files/en-us/web/api/identitycredential/index.md index 415936f753fedb0..4334ec8a1ddf3a2 100644 --- a/files/en-us/web/api/identitycredential/index.md +++ b/files/en-us/web/api/identitycredential/index.md @@ -19,8 +19,8 @@ A successful {{domxref("CredentialsContainer.get", "navigator.credentials.get()" _Inherits properties from its ancestor, {{domxref("Credential")}}._ -- {{domxref("IdentityCredential.isAutoSelected")}} {{ReadOnlyInline}} {{experimental_inline}} {{non-standard_inline}} - - : A boolean value that indicates whether the federated sign-in was carried out using [auto-reauthentication](/en-US/docs/Web/API/FedCM_API/RP_sign-in#auto-reauthentication) (i.e. without user mediation) or not. +- {{domxref("IdentityCredential.isAutoSelected")}} {{ReadOnlyInline}} {{experimental_inline}} + - : A boolean value that indicates whether the federated sign-in was carried out using [auto-reauthentication](/en-US/docs/Web/API/FedCM_API/RP_sign-in#auto-reauthentication) (i.e., without user mediation) or not. - {{domxref("IdentityCredential.token")}} {{experimental_inline}} - : Returns the token used to validate the associated sign-in. @@ -62,4 +62,4 @@ Check out [Federated Credential Management API (FedCM)](/en-US/docs/Web/API/FedC ## See also -- [Federated Credential Management API](https://developers.google.com/privacy-sandbox/cookies/fedcm) +- [Federated Credential Management API](https://privacysandbox.google.com/cookies/fedcm) diff --git a/files/en-us/web/api/identitycredential/isautoselected/index.md b/files/en-us/web/api/identitycredential/isautoselected/index.md index 88ed93918c76147..eda42a0f99f800c 100644 --- a/files/en-us/web/api/identitycredential/isautoselected/index.md +++ b/files/en-us/web/api/identitycredential/isautoselected/index.md @@ -5,13 +5,12 @@ slug: Web/API/IdentityCredential/isAutoSelected page-type: web-api-instance-property status: - experimental - - non-standard browser-compat: api.IdentityCredential.isAutoSelected --- -{{securecontext_header}}{{APIRef("FedCM API")}}{{SeeCompatTable}}{{non-standard_header}} +{{securecontext_header}}{{APIRef("FedCM API")}}{{SeeCompatTable}} -The **`isAutoSelected`** read-only property of the {{domxref("IdentityCredential")}} interface indicates whether the federated sign-in flow was carried out using [auto-reauthentication](/en-US/docs/Web/API/FedCM_API/RP_sign-in#auto-reauthentication) (i.e. without user mediation) or not. +The **`isAutoSelected`** read-only property of the {{domxref("IdentityCredential")}} interface indicates whether the federated sign-in flow was carried out using [auto-reauthentication](/en-US/docs/Web/API/FedCM_API/RP_sign-in#auto-reauthentication) (i.e., without user mediation) or not. Automatic reauthentication can occur when a {{domxref("CredentialsContainer.get", "navigator.credentials.get()")}} call is issued with a [`mediation`](/en-US/docs/Web/API/CredentialsContainer/get#mediation) option value of `"optional"` or `"silent"`. It is useful for a relying party (RP) to know whether auto reauthentication occurred for analytics/performance evaluation and for UX purposes — automatic sign-in may warrant a different UI flow to non-automatic sign-in. @@ -54,4 +53,4 @@ Check out [Federated Credential Management API (FedCM)](/en-US/docs/Web/API/FedC ## See also -- [Federated Credential Management API](https://developers.google.com/privacy-sandbox/cookies/fedcm) +- [Federated Credential Management API](https://privacysandbox.google.com/cookies/fedcm) diff --git a/files/en-us/web/api/identitycredential/token/index.md b/files/en-us/web/api/identitycredential/token/index.md index 73d7b9441b47ab0..169d243b5bb4432 100644 --- a/files/en-us/web/api/identitycredential/token/index.md +++ b/files/en-us/web/api/identitycredential/token/index.md @@ -61,4 +61,4 @@ Check out [Federated Credential Management API (FedCM)](/en-US/docs/Web/API/FedC ## See also -- [Federated Credential Management API](https://developers.google.com/privacy-sandbox/cookies/fedcm) +- [Federated Credential Management API](https://privacysandbox.google.com/cookies/fedcm) diff --git a/files/en-us/web/api/identitycredentialrequestoptions/index.md b/files/en-us/web/api/identitycredentialrequestoptions/index.md index adc34bddb7597dc..42a8e005b9d673f 100644 --- a/files/en-us/web/api/identitycredentialrequestoptions/index.md +++ b/files/en-us/web/api/identitycredentialrequestoptions/index.md @@ -57,7 +57,7 @@ It is used to request an {{domxref("IdentityCredential")}} provided by a {{gloss - : A random string that can be included to ensure the response is issued specifically for this request and prevent {{glossary("replay attack", "replay attacks")}}. > [!NOTE] - > Currently FedCM only allows the API to be invoked with a single IdP, i.e. the `providers` array has to have a length of 1. Multiple IdPs must be supported via different `get()` calls. + > Currently FedCM only allows the API to be invoked with a single IdP, i.e., the `providers` array has to have a length of 1. Multiple IdPs must be supported via different `get()` calls. ## Specifications diff --git a/files/en-us/web/api/identityprovider/close_static/index.md b/files/en-us/web/api/identityprovider/close_static/index.md index 69c9dd16a4a6598..a4b5ed12043535c 100644 --- a/files/en-us/web/api/identityprovider/close_static/index.md +++ b/files/en-us/web/api/identityprovider/close_static/index.md @@ -48,4 +48,4 @@ IdentityProvider.close(); ## See also -- [Federated Credential Management API](https://developers.google.com/privacy-sandbox/cookies/fedcm) on developers.google.com (2023) +- [Federated Credential Management API](https://privacysandbox.google.com/cookies/fedcm) on privacysandbox.google.com (2023) diff --git a/files/en-us/web/api/identityprovider/getuserinfo_static/index.md b/files/en-us/web/api/identityprovider/getuserinfo_static/index.md index 405f6626a944130..a4b90e19980766f 100644 --- a/files/en-us/web/api/identityprovider/getuserinfo_static/index.md +++ b/files/en-us/web/api/identityprovider/getuserinfo_static/index.md @@ -21,7 +21,7 @@ When `getUserInfo()` is called, the browser will make a request to the IdP [acco - The user has previously signed in to the RP with the IdP via FedCM on the same browser instance, and the data hasn't been cleared. - The user is signed in to the IdP on the same browser instance. -`getUserInfo()` must be called from within an embedded `<iframe>`, and the embedded site's origin must match the `configURL` of the IdP. In addition, the embedding HTML must explicitly allow its use via the {{httpheader("Permissions-Policy/identity-credentials-get", "identity-credentials-get")}} [Permissions-Policy](/en-US/docs/Web/HTTP/Permissions_Policy): +`getUserInfo()` must be called from within an embedded `<iframe>`, and the embedded site's origin must match the `configURL` of the IdP. In addition, the embedding HTML must explicitly allow its use via the {{httpheader("Permissions-Policy/identity-credentials-get", "identity-credentials-get")}} [Permissions-Policy](/en-US/docs/Web/HTTP/Guides/Permissions_Policy): ```html <iframe @@ -64,28 +64,28 @@ A {{jsxref("Promise")}} that fulfills with an array of objects, each containing - `NetworkError` {{domxref("DOMException")}} - : Thrown if the browser is unable to connect to the IdP or if `getUserInfo()` is invoked from the top-level document. - `NotAllowedError` {{domxref("DOMException")}} - - : Thrown if the embedding `<iframe>` does not have a {{httpheader("Permissions-Policy/identity-credentials-get", "identity-credentials-get")}} [Permissions-Policy](/en-US/docs/Web/HTTP/Permissions_Policy) set to allow the use of `getUserInfo()` or if the FedCM API is disabled globally by a policy set on the top-level document. + - : Thrown if the embedding `<iframe>` does not have a {{httpheader("Permissions-Policy/identity-credentials-get", "identity-credentials-get")}} [Permissions-Policy](/en-US/docs/Web/HTTP/Guides/Permissions_Policy) set to allow the use of `getUserInfo()` or if the FedCM API is disabled globally by a policy set on the top-level document. ## Examples ```js // Iframe displaying a page from the https://idp.example origin -const user_info = await IdentityProvider.getUserInfo({ - configUrl: "https://idp.example/fedcm.json", +const userInfo = await IdentityProvider.getUserInfo({ + configURL: "https://idp.example/fedcm.json", clientId: "client1234", }); // IdentityProvider.getUserInfo() returns an array of user information. -if (user_info.length > 0) { +if (userInfo.length > 0) { // Returning accounts should be first, so the first account received // is guaranteed to be a returning account - const name = user_info[0].name; - const given_name = user_info[0].given_name; - const display_name = given_name ? given_name : name; - const picture = user_info[0].picture; - const email = user_info[0].email; + const name = userInfo[0].name; + const givenName = userInfo[0].given_name; + const displayName = givenName || name; + const picture = userInfo[0].picture; + const email = userInfo[0].email; - // ... + // … // Render the personalized sign-in button using the information above } @@ -101,4 +101,4 @@ if (user_info.length > 0) { ## See also -- [Federated Credential Management API](https://developers.google.com/privacy-sandbox/cookies/fedcm) on developers.google.com (2023) +- [Federated Credential Management API](https://privacysandbox.google.com/cookies/fedcm) on privacysandbox.google.com (2023) diff --git a/files/en-us/web/api/identityprovider/index.md b/files/en-us/web/api/identityprovider/index.md index a89ea671df9ebe7..012f2ee29752c42 100644 --- a/files/en-us/web/api/identityprovider/index.md +++ b/files/en-us/web/api/identityprovider/index.md @@ -24,22 +24,22 @@ The **`IdentityProvider`** interface of the [Federated Credential Management (Fe ```js // Iframe displaying a page from the https://idp.example origin -const user_info = await IdentityProvider.getUserInfo({ - configUrl: "https://idp.example/fedcm.json", +const userInfo = await IdentityProvider.getUserInfo({ + configURL: "https://idp.example/fedcm.json", clientId: "client1234", }); // IdentityProvider.getUserInfo() returns an array of user information. -if (user_info.length > 0) { +if (userInfo.length > 0) { // Returning accounts should be first, so the first account received // is guaranteed to be a returning account - const name = user_info[0].name; - const given_name = user_info[0].given_name; - const display_name = given_name ? given_name : name; - const picture = user_info[0].picture; - const email = user_info[0].email; + const name = userInfo[0].name; + const givenName = userInfo[0].given_name; + const displayName = givenName || name; + const picture = userInfo[0].picture; + const email = userInfo[0].email; - // ... + // … // Render a personalized sign-in button using the information returned above } @@ -55,4 +55,4 @@ if (user_info.length > 0) { ## See also -- [Federated Credential Management API](https://developers.google.com/privacy-sandbox/cookies/fedcm) on developers.google.com (2023) +- [Federated Credential Management API](https://privacysandbox.google.com/cookies/fedcm) on privacysandbox.google.com (2023) diff --git a/files/en-us/web/api/idledetector/change_event/index.md b/files/en-us/web/api/idledetector/change_event/index.md index 48b049f3f65dfad..0bcd4a3cabca601 100644 --- a/files/en-us/web/api/idledetector/change_event/index.md +++ b/files/en-us/web/api/idledetector/change_event/index.md @@ -16,10 +16,10 @@ The **`change`** event of the {{domxref("IdleDetector")}} interface fires when t Use the event name in methods like {{domxref("EventTarget.addEventListener", "addEventListener()")}}, or set an event handler property. -```js -addEventListener("change", (event) => {}); +```js-nolint +addEventListener("change", (event) => { }) -onchange = (event) => {}; +onchange = (event) => { } ``` ## Event type diff --git a/files/en-us/web/api/idledetector/start/index.md b/files/en-us/web/api/idledetector/start/index.md index f1e9453d7a821df..af3f194a9a1ae00 100644 --- a/files/en-us/web/api/idledetector/start/index.md +++ b/files/en-us/web/api/idledetector/start/index.md @@ -40,7 +40,7 @@ A {{jsxref("Promise")}}. ### Exceptions - `NotAllowedError` {{domxref("DOMException")}} - - : Use of this feature was blocked by a [Permissions Policy](/en-US/docs/Web/HTTP/Permissions_Policy). + - : Use of this feature was blocked by a [Permissions Policy](/en-US/docs/Web/HTTP/Guides/Permissions_Policy). ## Examples diff --git a/files/en-us/web/api/imagebitmap/index.md b/files/en-us/web/api/imagebitmap/index.md index 25ed6ea89c1eec6..ee66eb5c7dcc19a 100644 --- a/files/en-us/web/api/imagebitmap/index.md +++ b/files/en-us/web/api/imagebitmap/index.md @@ -14,9 +14,9 @@ The **`ImageBitmap`** interface represents a bitmap image which can be drawn to ## Instance properties - {{domxref("ImageBitmap.height")}} {{ReadOnlyInline}} - - : An `unsigned long` representing the height, in CSS pixels, of the `ImageData`. + - : An `unsigned long` representing the height, in CSS pixels, of the `ImageBitmap`. - {{domxref("ImageBitmap.width")}} {{ReadOnlyInline}} - - : An `unsigned long` representing the width, in CSS pixels, of the `ImageData`. + - : An `unsigned long` representing the width, in CSS pixels, of the `ImageBitmap`. ## Instance methods diff --git a/files/en-us/web/api/imagedecoder/imagedecoder/index.md b/files/en-us/web/api/imagedecoder/imagedecoder/index.md index 5c889f7ce246ead..869c32bc754bf76 100644 --- a/files/en-us/web/api/imagedecoder/imagedecoder/index.md +++ b/files/en-us/web/api/imagedecoder/imagedecoder/index.md @@ -21,7 +21,7 @@ new ImageDecoder(init) - `init` - : An object containing the following members: - `type` - - : A string containing the [MIME type](/en-US/docs/Web/HTTP/MIME_types) of the image file to be decoded. + - : A string containing the [MIME type](/en-US/docs/Web/HTTP/Guides/MIME_types) of the image file to be decoded. - `data` - : An {{jsxref("ArrayBuffer")}}, a {{jsxref("TypedArray")}}, a {{jsxref("DataView")}}, or a {{domxref("ReadableStream")}} of bytes representing an encoded image type as described by `type`. - `premultiplyAlpha` {{optional_inline}} diff --git a/files/en-us/web/api/imagedecoder/index.md b/files/en-us/web/api/imagedecoder/index.md index be9bae5c125b5de..eaa230142554fa8 100644 --- a/files/en-us/web/api/imagedecoder/index.md +++ b/files/en-us/web/api/imagedecoder/index.md @@ -23,12 +23,12 @@ The **`ImageDecoder`** interface of the {{domxref('WebCodecs API','','','true')} - {{domxref("ImageDecoder.tracks")}} {{ReadOnlyInline}} - : Returns an {{domxref("ImageTrackList")}} object listing the available tracks and providing a method for selecting a track to decode. - {{domxref("ImageDecoder.type")}} {{ReadOnlyInline}} - - : Returns a string reflecting the [MIME type](/en-US/docs/Web/HTTP/MIME_types) configured during construction. + - : Returns a string reflecting the [MIME type](/en-US/docs/Web/HTTP/Guides/MIME_types) configured during construction. ## Static methods - {{domxref("ImageDecoder.isTypeSupported_static", "ImageDecoder.isTypeSupported()")}} - - : Indicates if the provided [MIME type](/en-US/docs/Web/HTTP/MIME_types) is supported for unpacking and decoding. + - : Indicates if the provided [MIME type](/en-US/docs/Web/HTTP/Guides/MIME_types) is supported for unpacking and decoding. ## Instance methods diff --git a/files/en-us/web/api/imagedecoder/istypesupported_static/index.md b/files/en-us/web/api/imagedecoder/istypesupported_static/index.md index c9174e15db4a3d2..49d65f9b1230ef4 100644 --- a/files/en-us/web/api/imagedecoder/istypesupported_static/index.md +++ b/files/en-us/web/api/imagedecoder/istypesupported_static/index.md @@ -8,7 +8,7 @@ browser-compat: api.ImageDecoder.isTypeSupported_static {{securecontext_header}}{{APIRef("WebCodecs API")}}{{AvailableInWorkers("window_and_dedicated")}} -The **`ImageDecoder.isTypeSupported()`** static method checks if a given [MIME type](/en-US/docs/Web/HTTP/MIME_types) can be decoded by the user agent. +The **`ImageDecoder.isTypeSupported()`** static method checks if a given [MIME type](/en-US/docs/Web/HTTP/Guides/MIME_types) can be decoded by the user agent. ## Syntax @@ -19,7 +19,7 @@ ImageDecoder.isTypeSupported(type) ### Parameters - `type` - - : A string containing the [MIME type](/en-US/docs/Web/HTTP/MIME_types) to check for decoding support. + - : A string containing the [MIME type](/en-US/docs/Web/HTTP/Guides/MIME_types) to check for decoding support. ### Return value diff --git a/files/en-us/web/api/imagedecoder/type/index.md b/files/en-us/web/api/imagedecoder/type/index.md index 12aa5c9f746d4de..34f334f4f0b905c 100644 --- a/files/en-us/web/api/imagedecoder/type/index.md +++ b/files/en-us/web/api/imagedecoder/type/index.md @@ -8,11 +8,11 @@ browser-compat: api.ImageDecoder.type {{securecontext_header}}{{APIRef("WebCodecs API")}}{{AvailableInWorkers("window_and_dedicated")}} -The **`type`** read-only property of the {{domxref("ImageDecoder")}} interface reflects the [MIME type](/en-US/docs/Web/HTTP/MIME_types) configured during construction. +The **`type`** read-only property of the {{domxref("ImageDecoder")}} interface reflects the [MIME type](/en-US/docs/Web/HTTP/Guides/MIME_types) configured during construction. ## Value -A string containing the configured [MIME type](/en-US/docs/Web/HTTP/MIME_types). +A string containing the configured [MIME type](/en-US/docs/Web/HTTP/Guides/MIME_types). ## Examples diff --git a/files/en-us/web/api/indexeddb_api/basic_terminology/index.md b/files/en-us/web/api/indexeddb_api/basic_terminology/index.md index 52ea2806c2e6631..52155290122d122 100644 --- a/files/en-us/web/api/indexeddb_api/basic_terminology/index.md +++ b/files/en-us/web/api/indexeddb_api/basic_terminology/index.md @@ -40,7 +40,7 @@ If you have assumptions from working with other types of databases, you might ge The security boundary imposed on IndexedDB prevents applications from accessing data with a different origin. For example, while an app or a page in `http://www.example.com/app/` can retrieve data from `http://www.example.com/dir/`, because they have the same origin, it cannot retrieve data from `http://www.example.com:8080/dir/` (different port) or `https://www.example.com/dir/` (different protocol), because they have different origins. > [!NOTE] - > Third party window content (e.g. {{htmlelement("iframe")}} content) can access the IndexedDB store for the origin it is embedded into, unless the browser is set to [never accept third party cookies](https://support.mozilla.org/en-US/kb/third-party-cookies-firefox-tracking-protection) (see [Firefox bug 1147821](https://bugzil.la/1147821).) + > Third party window content (e.g., {{htmlelement("iframe")}} content) can access the IndexedDB store for the origin it is embedded into, unless the browser is set to [never accept third party cookies](https://support.mozilla.org/en-US/kb/third-party-cookies-firefox-tracking-protection) (see [Firefox bug 1147821](https://bugzil.la/1147821).) ### Limitations @@ -84,7 +84,7 @@ In Firefox, IndexedDB used to be **durable**, meaning that in a readwrite transa As of Firefox 40, IndexedDB transactions have relaxed durability guarantees to increase performance (see [Firefox bug 1112702](https://bugzil.la/1112702)), which is the same behavior as other IndexedDB-supporting browsers. In this case the {{domxref("IDBTransaction.complete_event", "complete")}} event is fired after the OS has been told to write the data but potentially before that data has actually been flushed to disk. The event may thus be delivered quicker than before, however, there exists a small chance that the entire transaction will be lost if the OS crashes or there is a loss of system power before the data is flushed to disk. Since such catastrophic events are rare, most consumers should not need to concern themselves further. > [!NOTE] -> In Firefox, if you wish to ensure durability for some reason (e.g. you're storing critical data that cannot be recomputed later) you can force a transaction to flush to disk before delivering the `complete` event by creating a transaction using the experimental (non-standard) `readwriteflush` mode (see {{domxref("IDBDatabase.transaction")}}.) This is currently experimental, and can only be used if the `dom.indexedDB.experimental` pref is set to `true` in `about:config`. +> In Firefox, if you wish to ensure durability for some reason (e.g., you're storing critical data that cannot be recomputed later) you can force a transaction to flush to disk before delivering the `complete` event by creating a transaction using the experimental (non-standard) `readwriteflush` mode (see {{domxref("IDBDatabase.transaction")}}.) This is currently experimental, and can only be used if the `dom.indexedDB.experimental` pref is set to `true` in `about:config`. #### index @@ -178,7 +178,7 @@ With an understanding of IndexedDB's key characteristics and core terminology un ## See also -- [Indexed Database API Specification](https://www.w3.org/TR/IndexedDB/) +- [Indexed Database API Specification](https://w3c.github.io/IndexedDB/) - [IndexedDB API Reference](/en-US/docs/Web/API/IndexedDB_API) - [Using IndexedDB](/en-US/docs/Web/API/IndexedDB_API/Using_IndexedDB) - [IndexedDB — The Store in Your Browser](<https://learn.microsoft.com/en-us/previous-versions/msdn10/gg679063(v=msdn.10)>) diff --git a/files/en-us/web/api/indexeddb_api/checking_when_a_deadline_is_due/index.md b/files/en-us/web/api/indexeddb_api/checking_when_a_deadline_is_due/index.md index 2019c884c14e15a..5dbf554de67833f 100644 --- a/files/en-us/web/api/indexeddb_api/checking_when_a_deadline_is_due/index.md +++ b/files/en-us/web/api/indexeddb_api/checking_when_a_deadline_is_due/index.md @@ -34,8 +34,16 @@ When the form's submit button is pressed, we run the `addData()` function, which function addData(e) { e.preventDefault(); - if (!title.value || !hours.value || !minutes.value || !day.value || !month.value || !year.value) { - note.appendChild(document.createElement("li")).textContent = "Data not submitted — form incomplete."; + if ( + !title.value || + !hours.value || + !minutes.value || + !day.value || + !month.value || + !year.value + ) { + note.appendChild(document.createElement("li")).textContent = + "Data not submitted — form incomplete."; return; } ``` @@ -43,17 +51,17 @@ function addData(e) { In this segment, we check to see if the form fields have all been filled in. If not, we drop a message into our developer notifications pane (see the bottom left of the app UI) to tell the user what is going on, and exit out of the function. This step is mainly for browsers that don't support HTML form validation (I have used the `required` attribute in my HTML to force validation, in those that do.) ```js - else { + else { const newItem = [ { taskTitle: title.value, - hours : hours.value, - minutes : minutes.value, - day : day.value, - month : month.value, - year : year.value, - notified : "no" - } + hours: hours.value, + minutes: minutes.value, + day: day.value, + month: month.value, + year: year.value, + notified: "no", + }, ]; // open a read/write db transaction, ready for adding the data @@ -84,8 +92,8 @@ In this section we create an object called `newItem` that stores the data in the ```js request.onsuccess = (event) => { - - note.appendChild(document.createElement("li")).textContent = "New item added to database."; + note.appendChild(document.createElement("li")).textContent = + "New item added to database."; title.value = ""; hours.value = null; @@ -102,7 +110,7 @@ This next section creates a log message to say the new item addition is successf ```js // update the display of data to show the newly added item, by running displayData() again. displayData(); -}; +} ``` Last of all, we run the `displayData()` function, which updates the display of data in the app to show the new task that was just entered. @@ -129,7 +137,9 @@ const yearCheck = now.getFullYear(); The `Date` object has a number of methods to extract various parts of the date and time inside it. Here we fetch the current minutes (gives an easy numerical value), hours (gives an easy numerical value), day of the month (`getDate()` is needed for this, as `getDay()` returns the day of the week, 1-7), month (returns a number from 0-11, see below), and year (`getFullYear()` is needed; `getYear()` is deprecated, and returns a weird value that is not much use to anyone!) ```js - const objectStore = db.transaction(['toDoList'], "readwrite").objectStore('toDoList'); + const objectStore = db + .transaction(["toDoList"], "readwrite") + .objectStore("toDoList"); objectStore.openCursor().onsuccess = (event) => { const cursor = event.target.result; @@ -178,7 +188,7 @@ if ( With the current time and date segments that we want to check against the IndexedDB stored values all assembled, it is time to perform the checks. We want all the values to match before we show the user some kind of notification to tell them their deadline is up. -The `+` operator in this case converts numbers with leading zeros into their non leading zero equivalents, e.g. 09 -> 9. This is needed because JavaScript `Date` number values never have leading zeros, but our data might. +The `+` operator in this case converts numbers with leading zeros into their non leading zero equivalents, e.g., 09 -> 9. This is needed because JavaScript `Date` number values never have leading zeros, but our data might. The `notified === "no"` check is designed to make sure you will only get one notification per to-do item. When a notification is fired for each item object, its `notification` property is set to `"yes"` so this check will not pass on the next iteration, via the following code inside the `createNotification()` function (read [Using IndexedDB](/en-US/docs/Web/API/IndexedDB_API/Using_IndexedDB) for an explanation): @@ -187,7 +197,9 @@ The `notified === "no"` check is designed to make sure you will only get one not // notification won't be set off on it again // first open up a transaction as usual - const objectStore = db.transaction(['toDoList'], "readwrite").objectStore('toDoList'); + const objectStore = db + .transaction(["toDoList"], "readwrite") + .objectStore("toDoList"); // get the to-do list object that has this title as its title const request = objectStore.get(title); @@ -205,7 +217,7 @@ The `notified === "no"` check is designed to make sure you will only get one not // when this new request succeeds, run the displayData() function again to update the display requestUpdate.onsuccess = () => { displayData(); - } + }; ``` If the checks all match, we then run the `createNotification()` function to provide a notification to the user. diff --git a/files/en-us/web/api/indexeddb_api/index.md b/files/en-us/web/api/indexeddb_api/index.md index ea244c84bb576a9..4f619e5b01b9f9c 100644 --- a/files/en-us/web/api/indexeddb_api/index.md +++ b/files/en-us/web/api/indexeddb_api/index.md @@ -26,7 +26,7 @@ Operations performed using IndexedDB are done asynchronously, so as not to block ### Storage limits and eviction criteria -There are a number of web technologies that store data of one kind or another on the client side (i.e. on your local disk). IndexedDB is most commonly talked about. The process by which the browser works out how much space to allocate to web data storage and what to delete when that limit is reached is not simple, and differs between browsers. [Browser storage quotas and eviction criteria](/en-US/docs/Web/API/Storage_API/Storage_quotas_and_eviction_criteria) attempts to explain how this works, at least in the case of Firefox. +There are a number of web technologies that store data of one kind or another on the client side (i.e., on your local disk). IndexedDB is most commonly talked about. The process by which the browser works out how much space to allocate to web data storage and what to delete when that limit is reached is not simple, and differs between browsers. [Browser storage quotas and eviction criteria](/en-US/docs/Web/API/Storage_API/Storage_quotas_and_eviction_criteria) attempts to explain how this works, at least in the case of Firefox. ## Interfaces diff --git a/files/en-us/web/api/indexeddb_api/using_indexeddb/index.md b/files/en-us/web/api/indexeddb_api/using_indexeddb/index.md index 89bca133149f1c4..6eecef7e52348f8 100644 --- a/files/en-us/web/api/indexeddb_api/using_indexeddb/index.md +++ b/files/en-us/web/api/indexeddb_api/using_indexeddb/index.md @@ -261,7 +261,7 @@ request.onupgradeneeded = (event) => { }; ``` -For more details about the key generator, please see ["W3C Key Generators"](https://www.w3.org/TR/IndexedDB/#key-generator-concept). +For more details about the key generator, see [Key generators](https://w3c.github.io/IndexedDB/#key-generator-construct) in the spec. ## Adding, retrieving, and removing data @@ -272,7 +272,7 @@ To change the "schema" or structure of the database—which involves creating or To read the records of an existing object store, the transaction can either be in `readonly` or `readwrite` mode. To make changes to an existing object store, the transaction must be in `readwrite` mode. You open such transactions with {{domxref("IDBDatabase.transaction")}}. The method accepts two parameters: the `storeNames` (the scope, defined as an array of object stores that you want to access) and the `mode` (`readonly` or `readwrite`) for the transaction. The method returns a transaction object containing the {{domxref("IDBIndex.objectStore")}} method, which you can use to access your object store. By default, where no mode is specified, transactions open in `readonly` mode. > [!NOTE] -> As of Firefox 40, IndexedDB transactions have relaxed durability guarantees to increase performance (see [Firefox bug 1112702](https://bugzil.la/1112702).) Previously in a `readwrite` transaction, a {{domxref("IDBTransaction.complete_event", "complete")}} event was fired only when all data was guaranteed to have been flushed to disk. In Firefox 40+ the `complete` event is fired after the OS has been told to write the data but potentially before that data has actually been flushed to disk. The `complete` event may thus be delivered quicker than before, however, there exists a small chance that the entire transaction will be lost if the OS crashes or there is a loss of system power before the data is flushed to disk. Since such catastrophic events are rare most consumers should not need to concern themselves further. If you must ensure durability for some reason (e.g. you're storing critical data that cannot be recomputed later) you can force a transaction to flush to disk before delivering the `complete` event by creating a transaction using the experimental (non-standard) `readwriteflush` mode (see {{domxref("IDBDatabase.transaction")}}). +> As of Firefox 40, IndexedDB transactions have relaxed durability guarantees to increase performance (see [Firefox bug 1112702](https://bugzil.la/1112702).) Previously in a `readwrite` transaction, a {{domxref("IDBTransaction.complete_event", "complete")}} event was fired only when all data was guaranteed to have been flushed to disk. In Firefox 40+ the `complete` event is fired after the OS has been told to write the data but potentially before that data has actually been flushed to disk. The `complete` event may thus be delivered quicker than before, however, there exists a small chance that the entire transaction will be lost if the OS crashes or there is a loss of system power before the data is flushed to disk. Since such catastrophic events are rare most consumers should not need to concern themselves further. If you must ensure durability for some reason (e.g., you're storing critical data that cannot be recomputed later) you can force a transaction to flush to disk before delivering the `complete` event by creating a transaction using the experimental (non-standard) `readwriteflush` mode (see {{domxref("IDBDatabase.transaction")}}). You can speed up data access by using the right scope and mode in the transaction. Here are a couple of tips: @@ -580,7 +580,6 @@ openReq.onupgradeneeded = (event) => { openReq.onsuccess = (event) => { const db = event.target.result; useDatabase(db); - return; }; function useDatabase(db) { @@ -604,7 +603,7 @@ You should also listen for `VersionError` errors to handle the situation where a IndexedDB uses the same-origin principle, which means that it ties the store to the origin of the site that creates it (typically, this is the site domain or subdomain), so it cannot be accessed by any other origin. -Third party window content (e.g. {{htmlelement("iframe")}} content) cannot access IndexedDB if the browser is set to [never accept third party cookies](https://support.mozilla.org/en-US/kb/third-party-cookies-firefox-tracking-protection) (see [Firefox bug 1147821](https://bugzil.la/1147821)). +Third party window content (e.g., {{htmlelement("iframe")}} content) cannot access IndexedDB if the browser is set to [never accept third party cookies](https://support.mozilla.org/en-US/kb/third-party-cookies-firefox-tracking-protection) (see [Firefox bug 1147821](https://bugzil.la/1147821)). ## Warning about browser shutdown @@ -642,7 +641,7 @@ Further reading for you to find out more information if desired. ### Reference - [IndexedDB API Reference](/en-US/docs/Web/API/IndexedDB_API) -- [Indexed Database API Specification](https://www.w3.org/TR/IndexedDB/) +- [Indexed Database API Specification](https://w3c.github.io/IndexedDB/) - IndexedDB [interface files](https://searchfox.org/mozilla-central/search?q=dom%2FindexedDB%2F.*%5C.idl&path=&case=false&regexp=true) in the Firefox source code ### Tutorials and guides diff --git a/files/en-us/web/api/ink/index.md b/files/en-us/web/api/ink/index.md index b5daccf45943c16..874f99b0aa4f595 100644 --- a/files/en-us/web/api/ink/index.md +++ b/files/en-us/web/api/ink/index.md @@ -25,7 +25,7 @@ async function inkInit() { const ink = navigator.ink; let presenter = await ink.requestPresenter({ presentationArea: canvas }); - //... + // … } ``` diff --git a/files/en-us/web/api/ink/requestpresenter/index.md b/files/en-us/web/api/ink/requestpresenter/index.md index 2f094e00e3e4589..706938d3b48a134 100644 --- a/files/en-us/web/api/ink/requestpresenter/index.md +++ b/files/en-us/web/api/ink/requestpresenter/index.md @@ -41,7 +41,7 @@ async function inkInit() { const ink = navigator.ink; let presenter = await ink.requestPresenter({ presentationArea: canvas }); - //... + // … } ``` diff --git a/files/en-us/web/api/ink_api/index.md b/files/en-us/web/api/ink_api/index.md index 91adfc984d2fb44..a34ed13bbd37119 100644 --- a/files/en-us/web/api/ink_api/index.md +++ b/files/en-us/web/api/ink_api/index.md @@ -85,7 +85,7 @@ canvas.addEventListener("pointermove", async (evt) => { const pointSize = 10; ctx.fillStyle = style.color; ctx.fillRect(evt.pageX, evt.pageY, pointSize, pointSize); - if (move_cnt == 20) { + if (move_cnt === 20) { const r = getRandomInt(0, 255); const g = getRandomInt(0, 255); const b = getRandomInt(0, 255); diff --git a/files/en-us/web/api/inputevent/gettargetranges/index.md b/files/en-us/web/api/inputevent/gettargetranges/index.md index 844989ec19aaf75..63ce371fa7098a9 100644 --- a/files/en-us/web/api/inputevent/gettargetranges/index.md +++ b/files/en-us/web/api/inputevent/gettargetranges/index.md @@ -40,8 +40,8 @@ Depending on the value of `inputType` and the current editing host, the expected <tr> <td>All remaining</td> <td> - <a href="/en-US/docs/Web/HTML/Element/input"><code>input</code></a> - or <a href="/en-US/docs/Web/HTML/Element/textarea"><code>textarea</code></a> + <a href="/en-US/docs/Web/HTML/Reference/Elements/input"><code>input</code></a> + or <a href="/en-US/docs/Web/HTML/Reference/Elements/textarea"><code>textarea</code></a> </td> <td> an empty Array diff --git a/files/en-us/web/api/insertable_streams_for_mediastreamtrack_api/index.md b/files/en-us/web/api/insertable_streams_for_mediastreamtrack_api/index.md index 387a8088eb001c8..2f08bfa2b73f6ac 100644 --- a/files/en-us/web/api/insertable_streams_for_mediastreamtrack_api/index.md +++ b/files/en-us/web/api/insertable_streams_for_mediastreamtrack_api/index.md @@ -4,42 +4,47 @@ slug: Web/API/Insertable_Streams_for_MediaStreamTrack_API page-type: web-api-overview --- -{{DefaultAPISidebar("Insertable Streams for MediaStreamTrack API")}} +{{DefaultAPISidebar("Insertable Streams for MediaStreamTrack API")}}{{SeeCompatTable}}{{AvailableInWorkers("dedicated")}} -The **Insertable Streams for MediaStreamTrack API** provides a method of adding new components to a {{domxref("MediaStreamTrack")}}. +The **Insertable Streams for MediaStreamTrack API** provides a way to process the video frames of a {{domxref("MediaStreamTrack")}} as they are consumed. ## Concepts and Usage -When processing video or audio, you sometimes want to insert additional elements or otherwise process the stream. For example, an application might include two tracks that need to be combined, such as a weather map and video of a presenter explaining the map. Or, you may want to do processing on a track to blur backgrounds, remove background noise, or introduce other elements (such as adding funny hats to people, and so on). This API provides a method to do this by giving direct access to the stream, thus allowing it to be manipulated. +When processing real-time video, you sometimes want to insert visual elements or otherwise process the stream of video frames. For example, an application might include two tracks that need to be combined, such as a weather map and video of a presenter explaining the map. Or, you may want to do processing on a track to blur backgrounds, or introduce other elements (such as adding funny hats to people, and so on). The APIs described here provide direct access to the video stream, allowing you to manipulate it in real time. + +To ensure optimal performance, the APIs are only available in [dedicated workers](/en-US/docs/Web/API/DedicatedWorkerGlobalScope) (unless otherwise stated). ## Interfaces -- {{domxref("MediaStreamTrackGenerator")}} - - : Creates a {{domxref("WritableStream")}} that acts as a {{domxref("MediaStreamTrack")}} source. -- {{domxref("MediaStreamTrackProcessor")}} - - : Consumes a {{domxref("MediaStreamTrack")}} object's source and generates a stream of media frames. +- {{domxref("MediaStreamTrackProcessor")}} {{Experimental_Inline}} + - : Consumes a {{domxref("MediaStreamTrack")}} object's source and produces a stream of video frames. +- {{domxref("VideoTrackGenerator")}} {{Experimental_Inline}} + - : Creates a {{domxref("WritableStream")}} that acts as a {{domxref("MediaStreamTrack")}} video source. +- {{domxref("MediaStreamTrackGenerator")}} {{Experimental_Inline}} {{Non-standard_Inline}} + - : Creates a {{domxref("WritableStream")}} that acts as a {{domxref("MediaStreamTrack")}} source for either video or audio. Only available on the {{Glossary("main thread")}}. ## Examples -The following example is from the article [Insertable streams for MediaStreamTrack](https://developer.chrome.com/docs/capabilities/web-apis/mediastreamtrack-insertable-media-processing), and demonstrates a barcode scanner application that highlights a barcode in a video stream. This transforms the stream accessed via {{domxref("MediaStreamTrackProcessor.readable")}}. +The following example is from the article [Unbundling MediaStreamTrackProcessor and VideoTrackGenerator](https://blog.mozilla.org/webrtc/unbundling-mediastreamtrackprocessor-and-videotrackgenerator/). It [transfers](/en-US/docs/Web/API/Web_Workers_API/Transferable_objects) a camera {{domxref("MediaStreamTrack")}} to a worker for processing. The worker creates a pipeline that applies a sepia tone filter to the video frames and mirrors them. The pipeline culminates in a {{domxref("VideoTrackGenerator")}} whose {{domxref("MediaStreamTrack")}} is transferred back and played. The media now flows in real time through the transform off the {{Glossary("main thread")}}. + +```js +const stream = await navigator.mediaDevices.getUserMedia({ video: true }); +const [track] = stream.getVideoTracks(); +const worker = new Worker("worker.js"); +worker.postMessage({ track }, [track]); +const { data } = await new Promise((r) => (worker.onmessage = r)); +video.srcObject = new MediaStream([data.track]); +``` + +worker.js: ```js -const stream = await getUserMedia({ video: true }); -const videoTrack = stream.getVideoTracks()[0]; - -const trackProcessor = new MediaStreamTrackProcessor({ track: videoTrack }); -const trackGenerator = new MediaStreamTrackGenerator({ kind: "video" }); - -const transformer = new TransformStream({ - async transform(videoFrame, controller) { - const barcodes = await detectBarcodes(videoFrame); - const newFrame = highlightBarcodes(videoFrame, barcodes); - videoFrame.close(); - controller.enqueue(newFrame); - }, -}); - -trackProcessor.readable - .pipeThrough(transformer) - .pipeTo(trackGenerator.writable); +onmessage = async ({ data: { track } }) => { + const vtg = new VideoTrackGenerator(); + self.postMessage({ track: vtg.track }, [vtg.track]); + const { readable } = new MediaStreamTrackProcessor({ track }); + await readable + .pipeThrough(new TransformStream({ transform })) + .pipeTo(vtg.writable); +}; ``` diff --git a/files/en-us/web/api/installevent/addroutes/index.md b/files/en-us/web/api/installevent/addroutes/index.md index 24f7dc1439e24b6..2ed9d8b34ebec52 100644 --- a/files/en-us/web/api/installevent/addroutes/index.md +++ b/files/en-us/web/api/installevent/addroutes/index.md @@ -32,11 +32,11 @@ addRoutes(routerRules) - `or` {{optional_inline}} - : An array of `condition` objects. One set of these defined conditions must be met to match the rule. Conditions defined inside an `or` condition are mutually exclusive with other conditions. - `requestMethod` {{optional_inline}} - - : A string representing the [HTTP method](/en-US/docs/Web/HTTP/Methods) a request should be sent by for it to match the rule, such as `"get"`, `"put"`, or `"head"`. + - : A string representing the [HTTP method](/en-US/docs/Web/HTTP/Reference/Methods) a request should be sent by for it to match the rule, such as `"get"`, `"put"`, or `"head"`. - `requestMode` {{optional_inline}} - : A string representing the [mode](/en-US/docs/Web/API/Request/mode) a request should have for it to match the rule, for example `"same-origin"`, `"no-cors"`, or `"cors"`. - `requestDestination` {{optional_inline}} - - : A string representing the [destination](/en-US/docs/Web/API/Request/destination) of a request, i.e. what content type should be requested, for it to match the rule. Examples include `"audio"`, `"document"`, `"script"`, and `"worker"`. + - : A string representing the [destination](/en-US/docs/Web/API/Request/destination) of a request, i.e., what content type should be requested, for it to match the rule. Examples include `"audio"`, `"document"`, `"script"`, and `"worker"`. - `runningStatus` {{optional_inline}} - : An enumerated value representing the required running status of the service worker for a request to match the rule. Values can be `"running"` or `"not-running"`. - `urlPattern` {{optional_inline}} @@ -86,7 +86,7 @@ addEventListener("install", (event) => { ### Route form post requests to the network -In the following example, [`POST`](/en-US/docs/Web/HTTP/Methods/POST) requests to a form are sent directly to the network and bypass the service worker: +In the following example, [`POST`](/en-US/docs/Web/HTTP/Reference/Methods/POST) requests to a form are sent directly to the network and bypass the service worker: ```js addEventListener("install", (event) => { diff --git a/files/en-us/web/api/installevent/index.md b/files/en-us/web/api/installevent/index.md index 9b969938c93ef3d..059c238cea40e5c 100644 --- a/files/en-us/web/api/installevent/index.md +++ b/files/en-us/web/api/installevent/index.md @@ -59,16 +59,15 @@ self.addEventListener("install", (event) => { event.waitUntil( caches .open(CURRENT_CACHES["prefetch"]) - .then((cache) => { - return cache - .addAll( - urlsToPrefetch.map((urlToPrefetch) => { - return new Request(urlToPrefetch, { mode: "no-cors" }); - }), - ) - .then(() => { - console.log("All resources have been fetched and cached."); - }); + .then((cache) => + cache.addAll( + urlsToPrefetch.map( + (urlToPrefetch) => new Request(urlToPrefetch, { mode: "no-cors" }), + ), + ), + ) + .then(() => { + console.log("All resources have been fetched and cached."); }) .catch((error) => { console.error("Pre-fetching failed:", error); diff --git a/files/en-us/web/api/intersection_observer_api/index.md b/files/en-us/web/api/intersection_observer_api/index.md index eeb32a5fb6eb936..32a06b8601e62b2 100644 --- a/files/en-us/web/api/intersection_observer_api/index.md +++ b/files/en-us/web/api/intersection_observer_api/index.md @@ -60,7 +60,7 @@ The `options` object passed into the {{domxref("IntersectionObserver.Intersectio - `root` - : The element that is used as the viewport for checking visibility of the target. Must be the ancestor of the target. Defaults to the browser viewport if not specified or if `null`. - `rootMargin` - - : Margin around the root. A string of one to four values similar to the CSS {{cssxref("margin")}} property, e.g. `"10px 20px 30px 40px"` (top, right, bottom, left). The values can only be [absolute lengths](/en-US/docs/Learn_web_development/Core/Styling_basics/Values_and_units#absolute_length_units) or percentages. This set of values serves to grow or shrink each side of the root element's bounding box before computing intersections. Negative values will shrink the bounding box of the root element and positive values will expand it. The default value, if not specified, is `"0px 0px 0px 0px"`. + - : Margin around the root. A string of one to four values similar to the CSS {{cssxref("margin")}} property, e.g., `"10px 20px 30px 40px"` (top, right, bottom, left). The values can only be [absolute lengths](/en-US/docs/Learn_web_development/Core/Styling_basics/Values_and_units#absolute_length_units) or percentages. This set of values serves to grow or shrink each side of the root element's bounding box before computing intersections. Negative values will shrink the bounding box of the root element and positive values will expand it. The default value, if not specified, is `"0px 0px 0px 0px"`. - `threshold` - : Either a single number or an array of numbers which indicate at what percentage of the target's visibility the observer's callback should be executed. If you only want to detect when visibility passes the 50% mark, you can use a value of 0.5. If you want the callback to run every time visibility passes another 25%, you would specify the array \[0, 0.25, 0.5, 0.75, 1]. The default is 0 (meaning as soon as even one pixel is visible, the callback will be run). A value of 1.0 means that the threshold isn't considered passed until every pixel is visible. @@ -88,7 +88,7 @@ The list of entries received by the callback includes one {{domxref("Intersectio Be aware that your callback is executed on the main thread. It should operate as quickly as possible; if anything time-consuming needs to be done, use {{domxref("Window.requestIdleCallback()")}}. -The code snippet below shows a callback which keeps a counter of how many times elements transition from not intersecting the root to intersecting by at least 75%. For a threshold value of 0.0 (default) the callback is called [approximately](https://www.w3.org/TR/intersection-observer/#dom-intersectionobserverentry-isintersecting) upon transition of the boolean value of {{domxref("IntersectionObserverEntry.isIntersecting", "isIntersecting")}}. The snippet thus first checks that the transition is a positive one, then determines whether {{domxref("IntersectionObserverEntry.intersectionRatio", "intersectionRatio")}} is above 75%, in which case it increments the counter. +The code snippet below shows a callback which keeps a counter of how many times elements transition from not intersecting the root to intersecting by at least 75%. For a threshold value of 0.0 (default) the callback is called approximately upon transition of the boolean value of {{domxref("IntersectionObserverEntry.isIntersecting", "isIntersecting")}}. The snippet thus first checks that the transition is a positive one, then determines whether {{domxref("IntersectionObserverEntry.intersectionRatio", "intersectionRatio")}} is above 75%, in which case it increments the counter. ```js const intersectionCallback = (entries) => { diff --git a/files/en-us/web/api/intersection_observer_api/timing_element_visibility/index.md b/files/en-us/web/api/intersection_observer_api/timing_element_visibility/index.md index cf7c4fb265ad092..d22f028b3baa509 100644 --- a/files/en-us/web/api/intersection_observer_api/timing_element_visibility/index.md +++ b/files/en-us/web/api/intersection_observer_api/timing_element_visibility/index.md @@ -199,7 +199,7 @@ That brings us to the JavaScript code which makes everything work. Let's start w let contentBox; let nextArticleID = 1; -const visibleAds = new Set(); +let visibleAds = new Set(); let previouslyVisibleAds = null; let adObserver; @@ -265,7 +265,7 @@ function handleVisibilityChange() { if (document.hidden) { if (!previouslyVisibleAds) { previouslyVisibleAds = visibleAds; - visibleAds = []; + visibleAds = new Set(); previouslyVisibleAds.forEach((adBox) => { updateAdTimer(adBox); adBox.dataset.lastViewStarted = 0; @@ -371,7 +371,7 @@ function updateAdTimer(adBox) { } ``` -To track an element's visible time, we use two custom data attributes (see [`data-*`](/en-US/docs/Web/HTML/Global_attributes/data-*)) on every ad: +To track an element's visible time, we use two custom data attributes (see [`data-*`](/en-US/docs/Web/HTML/Reference/Global_attributes/data-*)) on every ad: - `lastViewStarted` - : The time in milliseconds, relative to the time at which the document was created, at which the ad's visibility count was last updated, or the ad last became visible. 0 if the ad was not visible as of the last time it was checked. diff --git a/files/en-us/web/api/invoker_commands_api/index.md b/files/en-us/web/api/invoker_commands_api/index.md index 421dc9a83d32696..00d94442ae4ffcc 100644 --- a/files/en-us/web/api/invoker_commands_api/index.md +++ b/files/en-us/web/api/invoker_commands_api/index.md @@ -2,15 +2,13 @@ title: Invoker Commands API slug: Web/API/Invoker_Commands_API page-type: web-api-overview -status: - - experimental browser-compat: - api.CommandEvent - api.HTMLButtonElement.commandForElement - api.HTMLButtonElement.command --- -{{DefaultAPISidebar("Invoker Commands API")}}{{SeeCompatTable}} +{{DefaultAPISidebar("Invoker Commands API")}} The **Invoker Commands API** provides a way to declaratively assign behaviors to buttons, allowing control of interactive elements when the button is enacted (clicked or invoked via a keypress, such as the spacebar or return key). @@ -22,14 +20,14 @@ Historically creating these kinds of controls has required JavaScript event list ## HTML attributes -- [`commandfor`](/en-US/docs/Web/HTML/Element/button#commandfor) {{experimental_inline}} +- [`commandfor`](/en-US/docs/Web/HTML/Reference/Elements/button#commandfor) - : Turns a {{htmlelement("button")}} element into a button, controlling the given interactive element; takes the ID of the element to control as its value. -- [`command`](/en-US/docs/Web/HTML/Element/button#command) {{experimental_inline}} +- [`command`](/en-US/docs/Web/HTML/Reference/Elements/button#command) - : Specifies the action to be performed on an element being controlled by a control `<button>`, specified via the `commandfor` attribute. ## Interfaces -- {{domxref("CommandEvent")}} {{experimental_inline}} +- {{domxref("CommandEvent")}} - : Represents an event notifying the user that a command has been issued. It is the event object for the {{domxref("HTMLElement/command_event", "command")}} event. The event fires on element referenced by {{domxref("HTMLButtonElement.commandForElement", "commandForElement")}}. ## Extensions to other interfaces @@ -37,9 +35,9 @@ Historically creating these kinds of controls has required JavaScript event list ### Instance properties - {{domxref("HTMLButtonElement.commandForElement")}} - - : Gets and sets the element being controlled by the button. The JavaScript equivalent of the [`commandfor`](/en-US/docs/Web/HTML/Element/button#commandfor) HTML attribute. + - : Gets and sets the element being controlled by the button. The JavaScript equivalent of the [`commandfor`](/en-US/docs/Web/HTML/Reference/Elements/button#commandfor) HTML attribute. - {{domxref("HTMLButtonElement.command")}} - - : Gets and sets the action to be performed on the element being controlled by the button. Reflects the value of the [`command`](/en-US/docs/Web/HTML/Element/button#command) HTML attribute. + - : Gets and sets the action to be performed on the element being controlled by the button. Reflects the value of the [`command`](/en-US/docs/Web/HTML/Reference/Elements/button#command) HTML attribute. ### Events @@ -82,9 +80,9 @@ Historically creating these kinds of controls has required JavaScript event list const myImg = document.getElementById("my-img"); myImg.addEventListener("command", (event) => { - if (event.command == "--rotate-left") { + if (event.command === "--rotate-left") { myImg.style.rotate = "-90deg"; - } else if (event.command == "--rotate-right") { + } else if (event.command === "--rotate-right") { myImg.style.rotate = "90deg"; } }); diff --git a/files/en-us/web/api/js_self-profiling_api/index.md b/files/en-us/web/api/js_self-profiling_api/index.md new file mode 100644 index 000000000000000..b14002ffb072183 --- /dev/null +++ b/files/en-us/web/api/js_self-profiling_api/index.md @@ -0,0 +1,65 @@ +--- +title: JS Self-Profiling API +slug: Web/API/JS_Self-Profiling_API +page-type: web-api-overview +status: + - experimental +browser-compat: api.Profiler +spec-urls: https://wicg.github.io/js-self-profiling/ +--- + +{{DefaultAPISidebar("JS Self-Profiling API")}}{{SeeCompatTable}} + +The JS Self-Profiling API enables a website to run a sampling profiler, to understand where it is spending JavaScript execution time. + +## Concepts and usage + +To start a profile, a website creates a {{domxref("Profiler")}} instance. As soon as the instance is created, it starts sampling the JavaScript execution context. + +To stop collecting samples and retrieve the profile, the website calls {{domxref("Profiler.stop()")}}. This returns a {{jsxref("Promise")}} which resolves to an object containing the profile data. + +For example, the following function creates a profiler, then calls a function `genPrimes()`, then stops the profiler and retrieves the profile data: + +```js +async function profileGeneratePrimes() { + const profiler = new Profiler({ sampleInterval: 10, maxBufferSize: 10000 }); + + genPrimes(); + + const trace = await profiler.stop(); + console.log(trace); +} +``` + +The profiler is a _sampling profiler_: this means that it periodically records (or _samples_) the current state of the JavaScript {{glossary("call stack")}}. The profile consists of the collection of these samples. This enables you to understand where, statistically, the program is spending most of its time. + +To understand exactly what a profile contains and how it is formatted, see [Profile anatomy and format](/en-US/docs/Web/API/JS_Self-Profiling_API/Profile_content_and_format). + +### Profiling best practices + +Collecting and processing profile data incurs a performance overhead of its own, and developers should be careful to manage this. Practices to minimize performance overhead include: + +- Use the [`maxBufferSize`](/en-US/docs/Web/API/Profiler/Profiler#maxbuffersize) and [`sampleInterval`](/en-US/docs/Web/API/Profiler/Profiler#sampleinterval) options to control how many samples to take and how often to sample. +- Sample for short periods in a sampled manner: for example, trace for 5 seconds out of every 60 seconds. +- Process the samples in a web worker to avoid impacting performance on the main thread. +- Aggregate samples on the client before sending them to a telemetry endpoint. + +If the JavaScript in your site is {{glossary("Minification", "minified")}}, you will need to transform the profile data based on a {{glossary("Source map", "source map")}}, either on the client or on the server, before the data will be usable. + +## Interfaces + +- {{domxref("Profiler")}} {{Experimental_Inline}} + + - : The `Profiler` interface is used to create profiles. + +## Security requirements + +To use this API, the document must be served with a [document policy](https://wicg.github.io/document-policy/) that includes the `"js-profiling"` configuration point. + +## Specifications + +{{Specifications}} + +## Browser compatibility + +{{Compat}} diff --git a/files/en-us/web/api/js_self-profiling_api/profile_content_and_format/index.md b/files/en-us/web/api/js_self-profiling_api/profile_content_and_format/index.md new file mode 100644 index 000000000000000..d4143052639c174 --- /dev/null +++ b/files/en-us/web/api/js_self-profiling_api/profile_content_and_format/index.md @@ -0,0 +1,186 @@ +--- +title: Profile anatomy and format +slug: Web/API/JS_Self-Profiling_API/Profile_content_and_format +page-type: guide +--- + +{{DefaultAPISidebar("JS Self-Profiling API")}} + +In this page we'll describe how to interpret a profile captured using the Self-Profiling API. + +The format of the object returned by {{domxref("Profiler.stop()")}} is designed to be space-efficient: for example, the format aims to avoid duplicating URL values for functions which are defined in the same script. This means that some interpretation is needed to understand how a sample in the profile object maps to a location in the program, and this guide page aims to explain how to perform this interpretation. + +In the first section, we'll describe the [abstract structure of a profile](#anatomy_of_a_profile). In the next section we'll describe [the format of the profile object](#profile_format) returned by {{domxref("Profiler.stop()")}}. Finally we'll [walk through an example](#example) to show what a profile for a given program looks like and how it can be interpreted. + +## Anatomy of a profile + +In this section we'll describe the abstract structure of a profile. Note that this isn't the same as the format of the object returned by returned by {{domxref("Profiler.stop()")}}: we'll describe that format in the next section of this guide. + +A profile consists of an array of samples. Each sample consists of a timestamp and a call stack. Each call stack consists of an array of stack frames, and each stack frame contains information about the location of its corresponding function in the program: + +![Diagram of a profile](profile.svg) + +The timestamp is a {{domxref("DOMHighResTimeStamp")}} which measures milliseconds since the _time origin_: for a window context, this is the time the window was created (if the window is new) or the time the browser started navigating to this document. + +The call stack is a representation of the JavaScript call stack, which enables you to understand the execution path to the program's location at the point that the sample was taken. + +The call stack consists of an array of stack frames. A stack frame essentially represents a nested function call, so if function `a()` calls function `b()`, which calls function `c()`, and a sample is taken while the browser is executing `c()`, then the call stack will consist of frames `[a, b, c]`: + +```js +function c() { + // sample taken here +} + +function b() { + c(); +} + +function a() { + b(); +} +``` + +Each stack frame contains information about the location of its corresponding function in the program: + +- The URL of the script +- The name of the function +- The line number of the function definition in the script +- The column number of the function definition in the line + +## Profile format + +Although the section above describes the _logical_ structure of a profile, the format of the object returned by {{domxref("Profiler.stop()")}} is different. The reason is that the format is designed to be space-efficient: for example, the format aims to avoid duplicating URL values for functions which are defined in the same script. + +The profile object contains four properties, all arrays: + +- `frames` + + - : An array of objects, each containing information about a stack frame: + + - `column`: the column number of the function definition. + - `line`: the line number of the function definition. + - `name`: the name of the function. + - `resourceId`: the index of an item in `resources`, representing the URL of the script in which the function is defined. + + Only `name` is always present: if the function is not defined in a script (for example, if it is a function that's built into the browser) then the other three properties are omitted. + +- `resources` + - : An array of strings, each representing the URL of a script. +- `samples` + - : An array of object, each containing two properties: + - `timestamp`: the time at which the sample was taken. + - `stackId`: the index of an element in the `stacks` array. +- `stacks` + - : An array of objects, each containing two properties: + - `frameId`: the index of an element in `frames` which represents the most-nested frame in the stack. + - `parentId`: the index of another entry in `stacks`, which represents the call stack up to but not including the frame represented by `frameId`. This is not present if the frame represented by `frameId` was at the top level of the stack. + +## Example + +In the following example we have a web page that contains a button: when the user presses the button, the page generates some prime numbers. + +The HTML contains only the button: + +```html +<button id="generate">generate!</button> +``` + +The JavaScript is split across two files. The "main.js" script contains the click handler for the button. This starts a profile, then calls the code to generate the primes, then logs the resulting profile: + +```js +// main.js + +import { genPrimes } from "./generate.js"; + +async function handleClick() { + const profiler = new Profiler({ sampleInterval: 10, maxBufferSize: 10000 }); + + const primes = genPrimes(); + console.log(`Finished generating ${primes.length} primes!`); + + const trace = await profiler.stop(); + console.log(JSON.stringify(trace)); +} + +document.querySelector("#generate").addEventListener("click", handleClick); +``` + +The "generate.js" script generates the primes, organized into two functions, `genPrimes()` and `isPrime()`: + +```js +// generate.js + +const MAX_PRIME = 1000000000; +const PRIMES_QUOTA = 10000; + +function isPrime(n) { + for (let i = 2; i <= Math.sqrt(n); i++) { + if (n % i === 0) { + return false; + } + } + return n > 1; +} + +export function genPrimes() { + const primes = []; + while (primes.length < PRIMES_QUOTA) { + const candidate = Math.floor(Math.random() * MAX_PRIME); + if (isPrime(candidate)) { + primes.push(candidate); + } + } + return primes; +} +``` + +If we run this code, a profile such as the one below will be logged to the developer tools console: + +```json +{ + "frames": [ + { "name": "Profiler" }, + { "column": 27, "line": 5, "name": "handleClick", "resourceId": 0 }, + { "column": 17, "line": 6, "name": "isPrime", "resourceId": 1 }, + { "column": 26, "line": 15, "name": "genPrimes", "resourceId": 1 } + ], + "resources": [ + "http://localhost:3000/main.js", + "http://localhost:3000/generate.js" + ], + "samples": [ + { "stackId": 1, "timestamp": 2972.734999999404 }, + { "stackId": 3, "timestamp": 2973.4899999946356 }, + { "stackId": 3, "timestamp": 2974.5700000077486 }, + { "stackId": 3, "timestamp": 2977.8649999946356 }, + { "stackId": 3, "timestamp": 2978.4899999946356 }, + { "stackId": 3, "timestamp": 2978.6950000077486 }, + { "stackId": 3, "timestamp": 2978.9500000029802 }, + { "stackId": 3, "timestamp": 2979.405000001192 }, + { "stackId": 2, "timestamp": 2980.030000001192 }, + { "stackId": 2, "timestamp": 2980.655000001192 } + ], + "stacks": [ + { "frameId": 1 }, + { "frameId": 0, "parentId": 0 }, + { "frameId": 3, "parentId": 0 }, + { "frameId": 2, "parentId": 2 } + ] +} +``` + +This profile captured 10 samples, listed in the `samples` property. + +The `stackId` property of each sample enables us to understand where the program was at the point the sample was taken, and in this case we've taken samples in three different places: + +- `stackId: 1`: one sample +- `stackId: 3`: seven samples +- `stackId: 2`: two samples + +To find the complete call stack for a sample, we retrieve the stack given the `stackId`, then use the `frameId` value in the stack to find the most-nested function, then recursively fetch parent stacks using `parentId`, until we reach the top level, which doesn't have a `parentId` value. + +For example, the diagram below shows how we could derive the complete call stack for the seven samples whose `stackId` is 3: + +![Deriving a call stack from a sample](profile-format.svg) + +Note also that the first item in `frames`, which has a `name` value of `Profiler`, represents a sample taken in the {{domxref("Profiler.Profiler", "Profiler()")}} constructor: since this is a function provided by the browser, the frame doesn't include script information. diff --git a/files/en-us/web/api/js_self-profiling_api/profile_content_and_format/profile-format.svg b/files/en-us/web/api/js_self-profiling_api/profile_content_and_format/profile-format.svg new file mode 100644 index 000000000000000..0eb2affb1240a61 --- /dev/null +++ b/files/en-us/web/api/js_self-profiling_api/profile_content_and_format/profile-format.svg @@ -0,0 +1,3 @@ +<?xml version="1.0" encoding="UTF-8"?> +<!DOCTYPE svg PUBLIC "-//W3C//DTD SVG 1.1//EN" "http://www.w3.org/Graphics/SVG/1.1/DTD/svg11.dtd"> +<svg xmlns="http://www.w3.org/2000/svg" style="background: #ffffff; background-color: light-dark(#ffffff, var(--ge-dark-color, #121212)); color-scheme: light dark;" xmlns:xlink="http://www.w3.org/1999/xlink" version="1.1" width="492px" height="474px" viewBox="-0.5 -0.5 492 474"><defs/><rect fill="#ffffff" style="fill: light-dark(#ffffff, var(--ge-dark-color, #121212));" width="100%" height="100%" x="0" y="0"/><g><g data-cell-id="0"><g data-cell-id="1"><g data-cell-id="IkmhDn_4ef8kqVBRZHeY-5"><g><rect x="20" y="115" width="120" height="75" fill="#ffffff" style="fill: light-dark(#ffffff, var(--ge-dark-color, #121212)); stroke: light-dark(rgb(0, 0, 0), rgb(255, 255, 255));" stroke="#000000" pointer-events="all"/></g></g><g data-cell-id="IkmhDn_4ef8kqVBRZHeY-1"><g><rect x="40" y="20" width="80" height="30" fill="none" stroke="none" pointer-events="all"/></g><g><g transform="translate(-0.5 -0.5)"><switch><foreignObject style="overflow: visible; text-align: left;" pointer-events="none" width="100%" height="100%" requiredFeatures="http://www.w3.org/TR/SVG11/feature#Extensibility"><div xmlns="http://www.w3.org/1999/xhtml" style="display: flex; align-items: unsafe center; justify-content: unsafe flex-start; width: 78px; height: 1px; padding-top: 35px; margin-left: 42px;"><div style="box-sizing: border-box; font-size: 0; text-align: left; color: #000000; "><div style="display: inline-block; font-size: 12px; font-family: &quot;Courier New&quot;; color: light-dark(#000000, #ffffff); line-height: 1.2; pointer-events: all; white-space: normal; word-wrap: normal; "><b>stackId:3</b></div></div></div></foreignObject><image x="42" y="28.5" width="78" height="17" xlink:href="data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAATgAAABECAYAAAAV6ClkAAARvUlEQVR4Xu2dBbAtORGG3+LurhdncS+cg7surg9nscJd3uKwuDuLu7s/3HVxvSzu7rDwf9SdqnmhY3My556Z213V9d6dSTJJJ/nT6e7k7LfLySXgEnAJzFQC+820Xd4sl4BLwCWwywHOB4FLwCUwWwk4wM22a71hLgGXgAOcjwGXgEtgthJwgJtt13rDXAIuAQc4HwMuAZfAbCXgADfbrvWGuQRcAg5wPgZcAi6B2UrAAW62XesN2yESOL7aeQbxacUbW3wk/ftt8TfF3xJviv+5Q+SxTzMd4ObZ61dTs+4nPpP4JEYTf6FnJ51n04tadQKleqT4CuITi49t5Lq5nr20qLTtSXRGffae4jsUfJ7+vqP49QVpZ5VknQGOlemy4k+IfzwrqY/bmBOq+F8VfGKd+76g+ksleYhyH5Qp4c56/4ylvjJO5lOo2IPFNx5Q/LuVh3Z9Z0DeSWZZ10F+O0nzOT2JPkL/f/AkJbz6St9UnyzRPMbqe7QiwOPsYkszKpUIWsenxGiiXyvNVJjuh0p3qgkC3FlU5w+LLa28sOm7kOv+4t+UZphyurEG+bIy+YMxOdBMdkSnLCm8cyr/lwvKGKPvj6LvAh7LTMCw6mgdVypoT02Styjx1ScGcPQXgH/BmoZG0rJVvW6Dcta+iDEG+bKNZmtqAdl59PxLyxa+Q/K/Tu08INPWMfoe7Q1Aak0nV4E/a1joJVXWhyYGcKdRfX+QqfMf9f6L4iOLcxr0LZTmJQ1lupZFjTHIl20oNgbL5nYRPf/ksoXvoPznVVvPKr6y+GZGu8fo+1PrO4c1ljFbqlOK/9W43JOpPGR0oshEXzcbHPX8ZUQGbONfaLzHhv1osaX1vVnPr9VYpmtX3BiDfNlGOsAtK8F9899Qf75yRQDHZ54vvnXDJtxJZT2zYXlWUT/Xw3BbvW4AR73pR/qzI2yT/H1oQj7YQT8qPleQBm3vOCPLdduLd4Db9i4YvQKrBjgahGZ0evExgtZdQH/f1Wgxz34XPOfvr4tX4fGbCsAhz+uL0cq/In6yGKDKEfa21xqJ0Lh/lMs85fc1AHcENRS1fkN8OjGxRNjKsI3ABBW22EZspwaH/Y+JSWwUfDzxX8SbW4wB/R8jdDiBmTgH2IqxFWHVZYL/VMzkYxD+duB3twPgYlVd6MUHjZdjOJCwQ51PzHhCO2Osf09MACzb6H/36jEVgBs4BHZdRxmtGDi0upT2N/R7a5OvBODOr9o+VJzzOrGSvFj8DTEC/buYOKK3Z1rL4L6X+EJiJvexxIBMSNhicoZm6sAAfpK4xJNIqACG8YuKLyE+c0HPsBIStlJSfq44vnsX8VXFuZCKdyrNy8UsKrcUH038PPE7xP3JGn6zBOAuvFUPS+vqykO2eB+fKw61rVw7u/cL/WdsgEN7ZDwxXlMypR+xT31B3BrgqMOBYmygnCDAOfYUcc5JUCrH2nQ4Eyw77FH1fIwFu7Z+o6VPAdzZ9NWHiXPeuFzlLq8E70skeurW5MqVU/OelZoo/sMjmWj3E8R3ryk0SPsa/Q3QoOHVElsDwOmKtRmN9MQMUlaMcgB3TGVEU8wBbFf+Y/UfjNpDaKFMYwEc2jdjiTjAGmIBZoEJaagNLuVJZkyuYsvdbwvxo8zjkD6gBzghZk0xgCuNpSoRzqOU6IGRhMRNoemNQZdSoQRFWgR4f7XBR1+mMjjS85+KstAUmVSlgJIrOucNywHcDfSBV+U+0nuPJgeYpLTGWHELvRgD4ACOt4lLNPDSpg4FuE/rA7FYtWfrHZrdGMRcZlwzp44oRovktAMyt2iPHuZOc4xRz5WWaQEctqfPi3OR3qUVfYES3iaSGLseW0prS1pafiwdnY2R2iJAJgZ+td+9mzKw/SghtvufLUlYkeYzSsv2PkY5gGMh2FvxPUwFxKXFtONUUQu9bA1waMPItGVwMW0YCnCpxe6NKhfzTWsiEBpzUOk8og+xv7E1nzVZAHcrtRhQakWHqCC2cjEiDODprT62VQ72qqskysQA/WtxTotCW8mlwVVPUGWOONyO3a71RGQxAjhjlAO4kqDXftkc2n5WrrGR9ws9bwlweBU5qxyGQAys3j7ZhgIczraYJondDy9oa2I3woJeSmiYrRfa0m+vNJ0FcIAbIBfSe/WAdwxQwIEtCl5Grmm5tvgeYgsMStRyjO2cVMAziwZphRK8Qs9xYKToz3r5XTGG99z1MNy4gYqOpw0vJYZgwAIQwrNEOZ1XmHYBmNh4LIDi/Z8ydXua3jNpYoQjB1slGi0BnWw18FpfRnx7MY4Ai5YBuNuqQJwGKSIGDRsdfc63OC40lBbK2BLgHqDyuBUkRjiDWOxYhBgbbGXpb5wLuR3KUIC7j8rGTmnRNfTwrUOFF8kXizqIfQZ7LXbbHUEWwBEUeLGg9WgyaCB/TUiF1RQACIM8GYQMqFJadZgI2lwODLu6AzbvNxqCvD6eaCBbBwDTIoy9AFjO+BwDyKEAx8KTu2qHRSDnBS/tV9ItxK0AjoWQrZZFLFK7xXhILWJBwjacWnCGAhwhP/cW31/cLfjUk6uNsNmOQSmt0frejfSwxu46Rp1XUqYFcKzorOwh4Zmkgz4nRqB9DadLi/EZ1bezBXDZ3kKMBlBKqwa4fr2YNN3FgcT6AdpcPYStAsalbh0XI/DyXYkGot3itQ0JzYLt5d8KhENdmLDh9ifnDYttUVOfpK/xLOY05oJq75OEsdAK4FhIOTURUs1tGSmteijA9etDCBS7gN/XCqoy/eW2xlfNVh0P/nsqvzO55BbA4RBIhR30G8kE5XAvxnyADXsIN4EwaVnJeFcyeftlrhrgMJgT9mBti0s7NAdwTGomd0hsl2JahvVtyz6K/ZJYuhjVAhwaGzFTQwOLUzJDBq0ALnYjSM3EJeYS04RlnG8BcKXjp1U6rlPC6cLBfBxpuxMFsyvj0syYFtyqTttajgVw2NXQ0ko9MmEDPqIH2CCwg9WET3TlrArg0DaJg2txz1wO4Kzrn4ZcWcOEfIOY2EIIWXMrxPcTo6gG4B6zJY8WJ1KsKi30sBXAWcG5OW3WqlPs/rwpAlzYvnPrAfGaMafHg/QuZcPcVnBq8fFYHBwxNNh2liHCF7it4CeVhawC4DAwA+KtPJopgOPEgWW7XGZwISO2rDm7HaKvATgCQveIhyxMJd3cCuCI87JAGFsvNt8aisVEzgHgkAOB3IQxWRcg4FxD2xurv2v6YZS0qZMMhD6w/WFQDiUEiKq8WVHA2ACHp5atdMug0BTA4ZyxjpgBPK+ukMvQpDUAxzcOEeNlK3W81NSLsdRCg2OXYW2hCUei/jWEKcVq61wADlkQb/oxseWJZ3zOdptachaV83S4t4mXgnNxYeHgqr2RdWyAe5MqeM2CGdDd0lDS3hTAoWkRohASjgfOzI5NtQBHfegz4rXYWrekhQprAXAxUMJzyTa7hmLjbU4AhzzwiFshKrV24BrZbntaC+AwUmLXgbgZNvSk4RnCw8hPlWGkJLaIyyhTGhHhFdbAtgQwJsBt6IMpexXOFX4LAi9xF9fGFpNVDmcE+a271YbY4Ijru8kKRkAM4PAGx2LrqBahFrSr1sSQatIiMg6G3CZi2TWHnBSITfy5AVzsFA1KC7bcWVIIcMRzEQfXEVoMYEaQZ44AO4JVrcPOGPIJuiyhGMDlYs1Kysbu9XAjIfZCgpVzv96FNmdpNTmAi51PBGCGBs5yXhj7CQtH6sB/6iQDmjlnWWOEiYHD47EjbyUy76dZbNU3zDcE4HBiIfeQOECOs6GEYqE35J0bwBFrSexjSCgqhAXNkkKAs+KC0DQ4nlMSyxMz/vIrTxxKL6EYwF1PmdEoc0R+rsrp4rjo1K4DqYcFwMS/Ee8WI66VITgSoLa8yzmAi0W3Y/vAoVOjJeH9xUvdxSqyCHGhYSymKXdUC5Alb2wrTvmc4ugvfLk+iL1f6EWLLSrlxyYsMuVsbu5qIk6KoK3vjlS2BcBh4MeAP+TGmbBazFXs2ZS5V5wKug/zsg0lj9XHBLqP5TUfOk6a5QsBLmafYpAzuQmstOxJCOnSYmLJrKtnan727+iRAYGRFLuQBQaETwBqbK3DK4gY8N2d/rHATuLIOF/ZvyEDw+yGGPDidzRTHlduVkVr4EygtRqmTjLQmeTH07WZ6FnaCJBxWiQcqMjm4kHec+jv7hid5UHr9z1mBgKVU6FBXCqAhkv/o3WmfuEMuy2aP5OxTwAPUf4hAVZhedw5h6mAS0Yt4u5AZB0DZnYTTxRbR+gYK8g81V7CKwhsP0zMdr3U04hcUQj6Y4Z67hGX/Jyj1VY0TXYZ3XlT5iP2W5yAsd9poB6cOeVw/30jMszdRBPJNp3HIcDF1P5+iwAMrkum4xnAaExEUKeM8WgAnAkspdiWjvx7xd2gx17I1jh3rrAL/kQLZOBaxHaM41astkzQlH0q1Q4GHg6EkB6nB9bk7qdDtkwG2kecF5rjcbfqk4tSRyPpvIF4Z3OHusO+j3l7Y20lGNg6epQ7c5uSnfUOTdU6sUBajj89PlMgp2kASjQeQJe+LXEc9YutcZTFNEvKY4Ei/rGWsNXGjnnRPk4VAeQsymz3WYyZG7l2tjD71LZlpenDQc6dWpYGtkylmLAEHOYOo/e/gScstuoMqUtn66LjV3FFDBpjqGmm7D1D2tTP078yibYSBpOjsO/R4pgspWRdKspCE9O4SssN07HwAEzWNoqdA1qIZYsb+r1YvlIwIL6SLaFFnBLBqVFLaKLLXM7asi61dd/W9OEgf5Fqs7thjVClsTHFDprHPsXKw9GvFrFqYXR7zGvWsNn/2y6zWISEJ5atYE4bq60LHrIuMLs0LCTs+9gPk6Tqwm0n/QUjdZttbZv66dklxM4z88tQ7DzCCyKW+Z6Vt9QmZ52w6MobctKCvAeIS+zPpW3Ga8quqkbpKC17rdKFg5wATwyvLYiYG7SwoR64/ZUXW09OzU7VFTvIweLwPCyDla3UGASoo8F1cXThN3ASsI3tQnGWqQOhHpwd7t9OzIQvcQiFfY+ND62zVN57lRa7a5/YUmMTKi2jpO0loMDWjCBf5Nry2/36WVq5VX9umyEsyiJu8MBZNYRaaXFceYY9dfbghpDDQc4APVCM0R3PIhf0oXXUbAEAtoPEqOrLEqcOUM0J7yglYqGIVcPml+pEDLbYxUq25IAVA4PtUCqeDy2KupbYG3HP8+MouSuLrHZjXMYuxUFxiwhk5pr42NXZtAcgDAntlnwp+yN5sVVi/7KufWes4FSKbdMiVf6/x3wHAEdGGPlLiDHLca3S32Wln1jokGfM4cCFEtj52N2UUOoC0WWDatkNMR+wf9YQsmRecqPNskcwa7677WlLTjJQSYCGA94bYozRrGZ4sYiPwxYDb4o5GzlGTA3fxEWOV7C7zogA3O4aI4KRcUwwGGtd3oAAl23irEBr5BgQdiTCDGDahEo/1q8PIUfAth84zZbscDHbMjyX/Atz5ItJvyNWX7VzKAHe9CcmDpwKyJd+xTGGuYRgb0wgJWd5h9QBICKigOOOeOYPFaOBtbp+CocScZAAJnODtrEzQHvFSca8xCtN6BOKBrf61M6LIe1euzylALd2FfcKuQRcAi6BnAQc4HIS8vcuAZfAZCXgADfZrvOKuwRcAjkJOMDlJOTvXQIugclKwAFusl3nFXcJuARyEnCAy0nI37sEXAKTlYAD3GS7zivuEnAJ5CTgAJeTkL93CbgEJisBB7jJdp1X3CXgEshJwAEuJyF/7xJwCUxWAg5wk+06r7hLwCWQk4ADXE5C/t4l4BKYrAQc4CbbdV5xl4BLICcBB7ichPy9S8AlMFkJOMBNtuu84i4Bl0BOAg5wOQn5e5eAS2CyEnCAm2zXecVdAi6BnAQc4HIS8vcuAZfAZCXgADfZrvOKuwRcAjkJOMDlJOTvXQIugclKwAFusl3nFXcJuARyEnCAy0nI37sEXAKTlYAD3GS7zivuEnAJ5CTgAJeTkL93CbgEJisBB7jJdp1X3CXgEshJwAEuJyF/7xJwCUxWAv8FVEQcchdVWzAAAAAASUVORK5CYII="/></switch></g></g></g><g data-cell-id="IkmhDn_4ef8kqVBRZHeY-2"><g><rect x="35" y="120" width="80" height="30" fill="none" stroke="none" pointer-events="all"/></g><g><g transform="translate(-0.5 -0.5)"><switch><foreignObject style="overflow: visible; text-align: left;" pointer-events="none" width="100%" height="100%" requiredFeatures="http://www.w3.org/TR/SVG11/feature#Extensibility"><div xmlns="http://www.w3.org/1999/xhtml" style="display: flex; align-items: unsafe center; justify-content: unsafe flex-start; width: 78px; height: 1px; padding-top: 135px; margin-left: 37px;"><div style="box-sizing: border-box; font-size: 0; text-align: left; color: #000000; "><div style="display: inline-block; font-size: 12px; font-family: &quot;Courier New&quot;; color: light-dark(#000000, #ffffff); line-height: 1.2; pointer-events: all; white-space: normal; word-wrap: normal; "><b>frameId:2</b></div></div></div></foreignObject><image x="37" y="128.5" width="78" height="17" xlink:href="data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAATgAAABECAYAAAAV6ClkAAAQdElEQVR4Xu2dBbAkSRGG93B318XtcIcDBnd3jYcH7m57uBzuvjiBBO62hx/uLg93d+f/jtdBU2RJd9fU9cxkRmTsvpnSv6v/qsrMqtlvl4sj4Ag4AmuKwH5r2i/vliPgCDgCu5zgfBA4Ao7A2iLgBLe2j9Y75gg4Ak5wPgYcAUdgbRFwglvbR+sdcwQcASc4HwOOgCOwtgg4wa3to/WOOQKOgBOcjwFHwBFYWwSc4Nb20XrHNgSBo6qfC+lppaeUnlD6A+mXpV+Rfk36hw3B4v+6OZbgjqCSriM9p/R0O3oG/fsn6Y+lP5H+bOffz+vfT0o/t6kge79nh8Dx1KJHSC+3QwjHNFp4M332ktm1/L8NOpP+e1fpjaVW+/tNf77+uI/0FzPuz1KaNpTgSH916WOkZxzYoo8q/eWlvx2Yz5M7ArUReLAKPDBT6B31/dNrV1yhPBYXd5I+YWBZv1P6O0hfKv3XwLwrm3wowT1HPb31hN7OddBM6JJnDRBgVQR5nE2aW1mkwPupvjxEel/plyqj/D2Vd4oVJDjeVwjqRhPweJzy3ntC/pXKOoTgWLK/aGLvXq3815tYhmefLwJHUtMgjxNVbOI7VNYVKpZHUW+UXnUFCa5k5VkCFTupd5YkXPU0pQR3UnX0hxU6e0uV8YIK5XgR80SA1RuEVFsYf9h2a8nFVdDBK0Zw51B7P5tpM6ver0tPLU2tUEm3vxQ7+VpLKcFhd3t9BIk36fOPS38tPf4OuKfSv7uleHY6eZ3+c4uddGsN6gZ3Di/edyv3n5fx5NK/Vy73JCrv3NITSF9slD03c8pr1MZrRzB4qj5/uBSsOqFf95feLZIHM8KeypjOrrhSggMMlsehHKAPPpTo1eH0HduVfwbgzw4Ib1A1BJ6nklip1xIM48+oVVikHLz+4bZ6TgR3NLUvFupxFX33lgQ+scXJMrb+S35Mw4svJThr9nibqrvS8Co9xwYgwMqI1TsvZl/Opz/ubPSfz9gB9IW/ieX6RgO85k5w4PkpA4dSmzYrPAi7L3hVjy1da49qKcGxPWUm6AuxNbdqMPhSVdB+4vB4cY4jJbCRuLux8T7HVV5eTIIlUcr8o3R7RzGg/7Vin9nSM3jPIv2llNUwdfUFkjir9OzSI0q/JSV4c+pW8Fgqg1gq6sbb+XMpWxwIhX4uQxYq9H1GweBA/2sKWJ1HejIpqzPGCthhowK7f/QqmzvBMS4tfDAFlTwrHCo4VkI5jT7Yrgn63MqyCI4X/J5SjJAwPIKB05JU8C4zxBelB+0Mqljfj6wvmF0uLcXWEhPsCd1SHFK7nxSPrBWKwJbmIVJe2pRgiMUwfhHpxaQlsX3Mmtg7coHLV1aam0sZhPSxL/v0B6uTZxqN62yVvIAPlMZc+i/Xdw+Qbmf62P+aF56wiwtLU0Zo+vZaKQ6h7w8oP5d0oQTLJjgmDMYvL3UqTIXn+Cjpp6W1CY423E56ZunfpDgHniz9Tg6gxPehB3XIFvoGKvcVRtlMbiwK1lYsgmMAMhBrCQ6ICyQKw/HAajAnt1WCl0kfKr17LrG+h2CxT7zfSEu/Hy+NGWALit/1KiWCwFjhhcKpDlZZY4W2cyokF25BOlZ3ORLC4AxuvHRDhYDSh0nDLeTQcki/kC6L4FjlPEV6k4ENY9JkMgplCIH086Y8yYyLKVtuJiXs3pDyVwv7eXilw2N8USM9mNV4roVNaZ8sJLjTqwks4WsL26svRAr9mD4/f0GFzLjnlfY9swXZDvXmhjMnpMDqcqoQdEl8YGjH2KPPWEG2ELa1l5SyUrCECeRJ0ilBt2ztMFHEnmFpPxdKuAyCgzjeLC1ZgZe2dSzBpcbzs1T5mEmmtM1WOnYAnDwKhUkRr/daS0hwnNEba79KAcXWMxZHl3J/1wDfGqhsR62V3Zj6OA/I9qMvW/rjhWMKG5mHrToTQCg31QdWCMSYarDPcfZ4SjzaQvlrExwv6SekudXu0D6PJbiU0R7zw7WGNmRC+tso77Mj+VmVW5ERE6qbX1Zri8r5u9tXbCqnH3jhY3IJfbGvYn3WS85Kqy8YoCHy3KqGLWAuDceIOJbUFxwD35bWfuliMDFDY1vry4X0x0cq4/oBlXcp6diYtIXy1iQ4cKaPMRvxlO6PJTi2jrGVZKnXc0q7u7wpcmNcs1vrx83VqHN2ZVgER+zaZaR42PAiIjzs8GVl27I30SNA5GFzJKTvsbKyYIzFtnBiKfVjLyoVbGnYXn4vZSvGqqUT2kBAp2Unwz5HfB+Gd5brGIJxxWNgxxP7TWn3IkNyhMRQj0VafE/9fcGxwJEYHAWxLfhz9R3tJ8aJFzVm+OfFwKmCXQ6SCbfp+/QZ29ROiPz/TKStpIGUnyZlW/cjKf2kDxA1W+7UNmrKLRsLlV2T4HA8cStITHAGEc5Ef8GYrSzPG+fCss6ixraEtPFqUgLjly04n+h7THKxc8tuX7Py5xomwo0juZUTtqctaWi0ZRDxAPmc1SMespSwmovZr8J8rF7eYxSGAffDkUqeqM/ZxobC531niRWrRB6cGRyu7iYJtsNhLFm4isR5Ertt4tH67kHS1CqMyY2wAmslwmQAUfw5g6v19UIf1iI4wnhiKxAmqS0pxnhLGFuPlIaxYf20Y1dw3PZxLykTUjeGaec9pOFOYgSEySw4FBhX3DYSE9rFGNgIWVWCY1XEtmzsVin2cHlpOMe3W0qMEFsgQk0gSZQYOK59CuWK+uDtkUItgoOQsGf120+fsIv0hReDdvRXoNaqJSS4DyqP5TXjTrDHFo5sVu/c42c5dVjNsjIaKgtlqEVwnJbg1EQoYNbFFebaF5tUyDeW4Pp1Et/HM/5NriEVvufiy73S1GUWG3E8q4/lqhEcW06MtO+uMCC6ItjOYb+yIuxLqxlKcO9VwcT99cUiOMu+lyM4tvkxRwDkxrG5UqGN1vZ6CFH261roj1oEF7sRZMhNGcdQezBNWCReg+BKcZ6ajokZB4Y1qXVlW3baqfXOPv8qERwvO9tPbGM1hBggtnJs16bKnAju+urMK6d2KJOfIGNukh0qNQnOCs61Jo5cG4mbs27uXRWCw5zw1ghJd31n8kzZKnMYrez3q0RwBPpy4WYNwcDM9quWl3NOBMfhdBwIyxSCmHmxhkotgsPWZJkncB6wwh0isZjIVSA4rn3CUZSyV3NBrbWVH4LRyqbdRIIj1g+PZc2g0DkR3F3UN7zJy5bSsdNvRy2Cwz74K6ODnCzZO7DjOAUsJ9PcCa4kxnFjvKWxZ146SFsftre8qLVWcFZfLHyw9yE5by5p5kRwbB2X7a2jz6VjZxkEFyOlMR5CDuPzK1ShzJXgWL0SAhLGPfbbz9jF408A9EZL6SBdF4LbradNAG5MiEsj8pv4vS6u7Sj6P4Z7nBHktw4tz4ngYqEs9NnyAI95AfAKjrlGfKF8tZwM1iQ45qQAqxwrNm2OBMdki70wvNmn/wwxH+Bo2R7zYNctz6YRnOWp5JlyIcA1pdZM3n/mDDDrV8HmRHBcg2SFJTCrsy2fctRq6vivSXAY1sE9FDy/OBtKhDAgYuUsc8XcCI7wJTzHqVMb9Juf87S27yV4rF2aTSM4Zj/rtgnc7KmrlTiVcEMpHlcrpGBOBMcgxfBs3ZDB7M7nQ2+0YJywlcP2xTVPQ0JN+i/NQn/UWsFhsuDweijEwXF7TXjBQpiOH8hhtb4VeatrENzRVTZnU62TNEPIhGN3nAhKmUu4kYcjlrn7CiH1qe0Z0vbDNK1FcABwLinbMvb7CC7mcJZj1RMLGsXDxUqB2fEvmR5CLvtLMf537bEOjhOawBbEEuogwp7jSanDzrHATiK/uZutf6SMI2O7pZAXh5JTHleM+sye3FDCEbZOyIPnN9xSEPICYfbvlLNWl/SJe/jBuuuXFQfHS839Z1261GUCrOR4btjptk00//PsCUTmWBNkwdG97uWif1tSjozFhKN3BCjzgveFsojyDwWyCi905BofTAWxCx25Aoq2xF56bnPhNEd4hI66wYpnlrqZhhMkYMTlmDyn0ptvGcMQTX/M0M49UiscJYZh9zk49seUlZ6Ji/GTaiOT9HWljEVMFeCz9r+sFRIcy2Cue6kVPsELypI6tmTmxXlX7gkP+J6yuI8rJjxgBq4ltJXjVsxuvKDMmmOEkwsYuznZsMgUwMCEjCCo2PaZIhjgbL22panzl6S77E56+kl/UwLRQiCcR0WIvL+gNPf8U/f5p04HjMEzFebA8aeDCjCGKDnHC1nwbEscR/1ih/x+QWxlSXlsH7lIdIiU/JrWkPK6tKlz2mPKm2WekOA4n8fLWVM4IcCgt6T25ZrUkToXyoubO5tao++EaoRXKMXK7Tx/KYIjbxfjlTtg3kWss53kvC5xXssQVvfhVpX4wpIrtIe0h4kHYrLi3jhH/AapZYsbUkdJ2tS46ucnvpKVryVcrolTY4gsi+Bow8bd6MuqAw9MTWFZzg0UlpQu+4e0J2c7iXnNhtSRS4unlS1oieDB44RGjuDYEhLYmSM4SO2AnYq5K41jbTVj/ig65q1c1u+iYv/rVpkhpjhVcDikjimVPIdcmty46vJbJyy678actFgmwXF1fS3Peg6/w+T7cAVXEjw4tKGpg9m1tzO0LXW5Ztd2BmtsVTm0f2F6lv5svQ8pLKi7fihHcN0LliM47In9kwyct8S+aDlXCpv4P8mw83G7ieWowM7DjwkP3QKm2lFCCthLCfLFPFCz7n67SsYV6blthlAdSzhCVzrxdfmd4MaM0p08IcFxIwEG6GtI2W5MEbYWGGl5cWP3wVEHhmAuvczZfXJtwZ7FNTClN+mydaOvlrcxrAvSwkvFdsjyAnbpuU+O/nLTBneqcU1SbPUEPtjJCNgkkp6rk7gbLhTsc9ht+CEV7IOUyYscS4cR3/oNTWyK1JWKoTKKPfQjZnnsm8RDWj9f18/HdpFA1Ng2LVZH+DmYUy/9zv3AT5cXhxVbeW4aKRGeExMdE0LM4YCdEjtf6bhilX1wpHIwiV3hFGvv1N/3SOGAM5HLBtZWSsNE1hYAdYzbMnjQ3HCKTQLbFXYkwgxQVipsD3Pu91XBCG81vyKGM4HgZbyRrHoIk9mWQrzEA3aKN9yyf825v2xbeZ5MLjgVmMx4rnhEuayBYG+i/IeGy5T2mV/VwvbMBaJM7lygykS+1r9gVQpOy3ROcC3R9rocAUegKQJOcE3h9socAUegJQJOcC3R9rocAUegKQJOcE3h9socAUegJQJOcC3R9rocAUegKQJOcE3h9socAUegJQJOcC3R9rocAUegKQJOcE3h9socAUegJQJOcC3R9rocAUegKQJOcE3h9socAUegJQJOcC3R9rocAUegKQJOcE3h9socAUegJQJOcC3R9rocAUegKQJOcE3h9socAUegJQJOcC3R9rocAUegKQJOcE3h9socAUegJQJOcC3R9rocAUegKQJOcE3h9socAUegJQJOcC3R9rocAUegKQJOcE3h9socAUegJQJOcC3R9rocAUegKQJOcE3h9socAUegJQJOcC3R9rocAUegKQJOcE3h9socAUegJQJOcC3R9rocAUegKQJOcE3h9socAUegJQL/BnC7JnIzfCkmAAAAAElFTkSuQmCC"/></switch></g></g></g><g data-cell-id="IkmhDn_4ef8kqVBRZHeY-3"><g><rect x="35" y="150" width="90" height="30" fill="none" stroke="none" pointer-events="all"/></g><g><g transform="translate(-0.5 -0.5)"><switch><foreignObject style="overflow: visible; text-align: left;" pointer-events="none" width="100%" height="100%" requiredFeatures="http://www.w3.org/TR/SVG11/feature#Extensibility"><div xmlns="http://www.w3.org/1999/xhtml" style="display: flex; align-items: unsafe center; justify-content: unsafe flex-start; width: 88px; height: 1px; padding-top: 165px; margin-left: 37px;"><div style="box-sizing: border-box; font-size: 0; text-align: left; color: #000000; "><div style="display: inline-block; font-size: 12px; font-family: &quot;Courier New&quot;; color: light-dark(#000000, #ffffff); line-height: 1.2; pointer-events: all; white-space: normal; word-wrap: normal; "><b>parentId:2</b></div></div></div></foreignObject><image x="37" y="158.5" width="88" height="17" xlink:href="data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAWAAAABECAYAAAC/K+/YAAASVUlEQVR4Xu2dBbAkSRGG9w53dzgWd3d/uB3ugW2gx+HusLi7++IeuLu7Hq6Pw90dDvI7piOKipKsnu6Zntd/RmTsvume6qq/uv6qyszK2W+XRAgIASEgBNaCwH5reaoeKgSEgBAQArtEwHoJhIAQEAJrQkAEvCbg9VghIASEgAhY74AQEAJCYE0IiIDXBLweKwSEgBAQAesdEAJCQAisCQER8JqA12OFgBAQAiJgvQNCQAgIgTUhIAJeE/B6rBDYYAROZHXfMj3A9JSmxzL9junXTb9h+j3Tf25w+1ZWdRHwyqDWg2aOwDms/Y8wPc+CtGI4/mgfnHdBZFOF6nJWsTuYXsNRwXvaPU8REZeREgE73iTdsjQCR7YSLm/6E9MvLF3aZhbwaav2BSpVP7dd/9IEm3dcq9PjTW/ZWLevLb7zycbvzeZ2EfBsunptDb2QPfnNpide1OD99u+VBl4Z3dXKO8j0jEu2kq3zu03vZ/rbJcsKv34G++NbjvKmSMDHs3pDoMtge3X7/lsc7Z/dLSLg2XX5yhv8anvi9aOnHmh/v22gmpzTyhl61XgfK/MxA9WPYo5m+nNTbKUlmRoBH2nRT+xelhHMK2c2ZQckCRAQAet1GBuBz9kDsG2Ggh3xGQM9+GFWzgMGKqsrhtXqmQYu8+5WHtv4TSLggx39BFa/MT2baWmCeY9dZ+dz2MC4bnRxIuCN7r6NqPw3rZbx9vXe9tljB6r9DaycVw1UVlfMK+w/Nx64TIo7tekFTc9i+pBE+VNaAbNq3zbtTEdhdVnRYqZ5gelfgwuQMDuHq2aww4n3vhFw3dgiRcAb23UbU/GxCRgH3yEJkl8GIEjyM8sUUPnu6ew6YVuxTImAL22Vw14fC+R7VtMfFdr4RLuGXT6WISfeEbtndUWLgFeH9VyfNDYBgyu2ygubnmLx/xDrm9ofsQ0TErl91CH/sb9/YUqUxi9H7qxNIGDMRE9L4IBZ4lkVfOiPLy6IOrz1tfZH7A8YGeppF9+HgNmanNb09KanMv3L4sXdtn+/asqLPIQc1QrBe8wWiMDvE5j+3fRQU2bfH5oykFYtR7QHEtNJPCdt/cqi3eDQV45iXwRPVhYnNcUDDxnQToLbh8I0VT9wxd6JmYB6QJgE0/+sb2Oi762CgEtVfZBdjLf7X7bPzjVQ+8Jijm1/YO8+iekJTXknvm3KajfEcxMIGHMBdttQPm9/ENXyLwd22Luxe4fC+wxnSBYIQMDYuq63AAZyiQVvNU4OQkmw+5RiGSGNl5s+wfTHjSjz8tLpFzO9qCkrmpoQHsPgepdpC0mdzO6/hymD5fiFh1zZrnWe20va//GO81ksTAQM9Gea/qNW6cV16gCelzGFeHMCpkQSvMT0s86yIdS7maYcI0xiW6b05+NMOcmUEtr0ItP7m/7J+Vzen9uaglE30IhSSAkkWBIG+Q8WdVgmhGlsAmYMcTCBlWEpWgA8n236ZFMWMUObIFgQ3M6UaANOoREZwkEIMOwjtItxFbaJ8eKN42aVTGhgKGDAOJcsEABkD3ERUF0iiRSgEOPDTT2z5Y3sPhwffYWZ+YamrDY88jq76TqOGyGwP5visc85FsJi8AhDPsST5gSbJYP1SY7nx7e8yT7AjsaqMif72wVsoqX+op7euE7acnPTjzrqC6ZgO7Scxgrc7lnomAQMxvtMawcs4qpjW2XijaWvDfgKVhBkmRJ2kSmy98IJ6YL/R0xZDHiExQXvaBwVwTg9n6eAudzjJeC+eLCFgRgJU8kJdfh9orNanwmp4DyhrJKwNfTa+LCB3bGxIkxWbG9TEw8re1aVXvLLPfq6duH1mYtg8KnGOntu9wTTv90KSu0QPOWX7nmgXWQy7yNjETAT8lv7VKjwnb4EXDplx6qblfGqhF3QG01TCxaiJm61qopswnPGJmAwwJu8ZZqzkWJ3/NtAYLFCvGalLJ4HAdeC4pepUmqrxmoae/FQgpf6g4nCTm6ftZp/PHXCfsf2lh1BTp5vF1qPq3qefRu76XmeGxP3jEHApRVnz2oe/rW+BFzaxb7Byr32MpVq+C7k+0JTHJ8pwZzx3obydvytqyBgQGS1xqotJ16TgKdDcNrVVrjYXkmMMpbgpPx+UDiOLlYpfD6UYE8jnjRFtvvsc8wGQ0ttJYodkm3mkEI7mVS8duj42UMTMJMQfTnGBN6XgFOOzg6HVUUeQL5MwLn3DrMLBKyDGMEbCgHjdeeECv/e2rRGEpAphIkxHpsr0QrYwjC4l1Y/17LrbE1SwurwUaZXM2XAcXoKxenEc4h46FbQ2FDZyrMlxWEXyxXtA87z14RV6pbp0U13V+oelkX9sMO+0hRieKlpeNLrHfb3VYIvYJPFFJOy+XEbdrXnmHKYAHsruwFW6dSJkB3CgVLB8HyX1UYOc2xtbD1LfUJbOEn2cVNwxkGHvQ8HXmrbyiC6bNC21H/x8G+ZEglwBNOHJm7CeYq5oiQ4M5lccAIvk5dhaALmIEGuL8GTLGC0D1Kk/YwN8PAcPOlLwPey8nNHpz2mo0pXVC8zhvDh5LKkgQtjnHEsCRCIw9BqW0jCSgiyzgnOCOxiKcKAXHAIlGZAyNUbRXAcu/d3iYr0OcfPqoZwr5qwDSZ64g/BjdQZuxZtZ3AyQYWng85vf+eC+iHrm5iWbOR4jfeZMoGl5Oz2IeF/KUmFEnX3QRLsSnLmCux1t4gKZbKAWFtkJ4WhlUwPrDSZLHOOKhY2YLpVAK8vAbP6hPjva9qtzKkH4/VlLZ3V416S9RClkloMdcUxYX2gR9k7/istBMyqDsKoCfGsuWiEi9g1b2o6XiSObqK7TYkFhnBJasLLhbKKisOoWEljYmiRGgEzg2PXwsbcKnvtCw9OfImVHSuGfzsKZBXNijsVxP5o+5yBl5IcAePRxklSiqPGlo79MBbC9lpWpDuJgNntMGHGwrgAz1pEETsbzBe50Ly+BBzWB3MXDuCaM9rx2lVvIdTwnaaliBucstwjSSDgJWCiAe7UgCCnjJ6euJ/QtL2FcoiPJI4UQsltu2vVGJqAiVdl9VkKLSvVidVp6gVlMLc4y5iAUuYEwo8wIaUkR8CYm5jISkIc9icSN3DarCWr1U4hYE53/do0tv0yibVk+iplbxuCgGvjY6jrmN2YeErjlAUGqUglGQS8BMzg/1UDityf2opBOjdLlMMWihUmq7m+xNsVOyQBv8YKZRte8vyXYIGsSmfmGyDN3loKbs8RMAm2ayskEfD/Q57b2XFIqdWhmzP1bQoB46upEavXFzPEGNjYMjwEzMoPx0qrfNe+EDv0cEZhRwulFDfY+kzuH5KAcRwQ19tXxshVm6oLzsCfJi6IgP93QnGIo8g4fj+WwLjPFpuwOhyvsWwCARMX/9TCgGBBwHuHqUVSQcBDwACK3c9zoi18XGrrnYrTxbyB82IomRIBs00jmmNs4Xx+6oUXAQ9HwLmDF31OmrE1T0UETZmAWSjhgC8dTGKxxsp3mZN3Y4+VSZXvIWAq3LqdyDm1sAuHHUioE/kTPIJJw2OemBIB40Dc9jRuyXswF6ROv4mAhyPgixvGOC9jwftPGF+LkHsF81YsUyVgIh1wAsMDOcG5zsTiPa7cgteOvddLwKyC2U57yAT7ImSQOm4L4XI0spOUmaK7hrmCjEoE9nf2Z2ZhSBgnEufN2QrFZo4pETBOxdwJQG80SO3lI4qC4HewjEUEPBwBk+CILHGxsKBIOZxL/UZMMGFjsUyRgLF9E7FTOj5P6CW+nWUyAtbe8x153UvANJ5cCzjKSrYdOovDAZfIoEUMaTdD5laHkD1efc+qInUGfkoEDAwksVnmwMgyL95UCZgoFxyuq5ChbMC5I/O8r5CTN30nETG5uO2pETDH3TEblk79kVGP/vSEU66ivzfqGS0E3DWMYPLnLgiZuNxjLF5AgvpL8bcvtut7AnRyGdCIdSWovSScxupSOcb3TY2AOVVGes5YGLi0tU+MJDZ5HG/Y3EqrjqkScGyKyvX1Me0C215ikomxZffkmZjD8oYiYMpM/cAonxMKSL6F2gqQRFAfMs3FzQ5BwIxHsKrVpTzCdu3KOQrD7xEyChfUhJNyy9an9oyNvN6HgMOGQiKeM/GsennpiKPsJGcHI1TtYNP47D9mBzzRnHQrpf/DdEH6SGJVMV+kZmaiOnCeMMAR/v/IRA+SCzf3c+IcGab8Wkws9jNysuZwglTYNeROy/G9LgE8p+rIS9yZXbpj0fEvFEDQDGbslnEEAM2E+MlVQYRHamCw2sOskfLUswvigIY3NI8TUFsRttT7Uqap3LKYmbifPNV7ou/xJ/6FOB0n3yEPBZMS8bqhUEacmYvnx6f8IC1yiBD3nTphSZlM/LlkMt3JM2yl8TsHnpjfOJZdGi8c2OGd4gi+d0VNvRjHjBkmm85PwuS815Tx1Cqe39ljQVXLBsd7CEnjjMbmTf1KqVRb67nx9y9LwB4AciaFWtYutj7Yfg8wxcnkIfq4PgwmSIsE1Z2kVkSeduTu8Rx99jgbiRfGe8y/5GTgCDJpLWupK8GXyakjUhL0YIP34MXkgrkodJxgm/TkLWAH4/kxTCa23Ek9yIY2U3fMU0yMtfaSA4SkQJ1AuBBW7nRZa9+WJgfKgnRquaFpFzZ5JgZsx6WTYrn60Q+1X1HuvgvJhb6VsMxS6tLcsyFzFjFDS5wnZejyN668sQmYgY09N5dFP2XDHRrE8AVkdVA7Adb6fE+2LnBmlbuntXDn/aEn3kMQYbH8eCK/0oCwYgl3KaXHQ96sRmvHb4mTrSXecTbz8NtiYsrtpFrKjO+NzWXhdRYOvM+eiJxl6sB7haPZs9Mg1DFMCBU+FwfagY0VGYuAS4eGGqu4M273ErA3BCxEhZUKcYOlvAFk3uKnUzyrtb6IswLDlICMkS6RcjGJ1H4uiKQ9rBhzSXX6to++2W3aJQDi+LDn55y65/HLHNipkdacxd68EPycUi5HbEu7GcA4b8N3ilNorbk/as9kcmHlmhMSIJF4aWwS9rxX1JFFRa4ungx2cTvHImCeE3NOrS929HUPAWMK4FctUFYfpe0UA4TVA46wmm20Axa7Lo6osUg4dGzQXkKJatvclk7H1sZg9RxU4fmQnXdrWasH5IutNnTkecwdYbnYlMP4ViZEz3a+lIMirjeOoQ+b5lZptXZynaxepF2MT/yNcdqQCTvlEwjryfvKMWTqNIa0vFelFJlM+piLWkQE3ILWEvd6CTj8lQmcStjqUOyzpFLEsB7/8mtLtfAOs4phO+wRDPo4F7C/5tLg8QLjnIrJjtXhXtNSULmnDkw22JgZgK2e+d32nTub3sXzoOgeVmfkOyYFIA6u0L7NrTgWsXNDzKUVGviQXjMOB2PVheMu99NCtJvQOvqqxaGCrZZYUYjNu3Lk6C9OLZx+pQmdFKFMPLVc1jW4mdCwUzJJllKEhuUwAXCYqJSOMbyfqAHMRLlcCn3eKyZRoitSkvp1lhoOe+wGfjprDNEKOEC1DwGP0SldmQwgVsTEE7OqJN0dg2LblEgC/mUl1ZIOccz6Lls2BzVwEhKtwGRGKkGUQXioKQmsUbKmsfKDhDY9nIc2kx9296LNmKFoM7ZnPP9EZ+AbwM66SW3Fidi9t9jGu50iEx26bcq76yX21ncL8xoZCzEjEYVxiCkmwNThkdaydf9ICEyNgEdqpooVAkJACEwPARHw9PpENRICQmAmCIiAZ9LRaqYQEALTQwACJlick1YE8+O8iUOYOC3Fj1AixHwS8sJZ9vB3z6bXMtVICAgBITBxBCDg0k9a56qPY4wctNsTb5+qJwSEgBCYLAIQcO0kU67ypR+DnGyDVTEhIASEwFQQWIaACd4n/lAiBISAEBACPRBYhoAPsuelsmX1qIa+IgSEgBCYHwIQMCfFOKfvPZ3EIQHy9XKSK04ZOT8E1WIhIASEQE8EwjA0oiH2r5RzmF335DzoWR19TQgIASEwHwR0Lns+fa2WCgEhMDEERMAT6xBVRwgIgfkgIAKeT1+rpUJACEwMARHwxDpE1RECQmA+CIiA59PXaqkQEAITQ0AEPLEOUXWEgBCYDwIi4Pn0tVoqBITAxBAQAU+sQ1QdISAE5oOACHg+fa2WCgEhMDEERMAT6xBVRwgIgfkgIAKeT1+rpUJACEwMARHwxDpE1RECQmA+CIiA59PXaqkQEAITQ0AEPLEOUXWEgBCYDwIi4Pn0tVoqBITAxBAQAU+sQ1QdISAE5oPAfwHleohyQC69rQAAAABJRU5ErkJggg=="/></switch></g></g></g><g data-cell-id="IkmhDn_4ef8kqVBRZHeY-6"><g><path d="M 80 50 Q 80 50 80 108.63" fill="none" stroke="#000000" style="stroke: light-dark(rgb(0, 0, 0), rgb(255, 255, 255));" stroke-miterlimit="10" pointer-events="stroke"/><path d="M 80 113.88 L 76.5 106.88 L 80 108.63 L 83.5 106.88 Z" fill="#000000" style="fill: light-dark(rgb(0, 0, 0), rgb(255, 255, 255)); stroke: light-dark(rgb(0, 0, 0), rgb(255, 255, 255));" stroke="#000000" stroke-miterlimit="10" pointer-events="all"/></g></g><g data-cell-id="IkmhDn_4ef8kqVBRZHeY-13"><g><rect x="20" y="246" width="120" height="75" fill="#ffffff" style="fill: light-dark(#ffffff, var(--ge-dark-color, #121212)); stroke: light-dark(rgb(0, 0, 0), rgb(255, 255, 255));" stroke="#000000" pointer-events="all"/></g></g><g data-cell-id="IkmhDn_4ef8kqVBRZHeY-14"><g><rect x="35" y="260" width="80" height="21" fill="none" stroke="none" pointer-events="all"/></g><g><g transform="translate(-0.5 -0.5)"><switch><foreignObject style="overflow: visible; text-align: left;" pointer-events="none" width="100%" height="100%" requiredFeatures="http://www.w3.org/TR/SVG11/feature#Extensibility"><div xmlns="http://www.w3.org/1999/xhtml" style="display: flex; align-items: unsafe center; justify-content: unsafe flex-start; width: 78px; height: 1px; padding-top: 271px; margin-left: 37px;"><div style="box-sizing: border-box; font-size: 0; text-align: left; color: #000000; "><div style="display: inline-block; font-size: 12px; font-family: &quot;Courier New&quot;; color: light-dark(#000000, #ffffff); line-height: 1.2; pointer-events: all; white-space: normal; word-wrap: normal; "><b>frameId:3</b></div></div></div></foreignObject><image x="37" y="264.5" width="78" height="17" xlink:href="data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAATgAAABECAYAAAAV6ClkAAAQq0lEQVR4Xu2dBZAltxGG7TAz44XjxA4zvjAz84aZmR0mh5kdTgUqzHQOO8wMG0aHmf+vslM11rVG0oxmT2+2u6rrbt/TaKRfUqtJevvu4+QIOAKOwEIR2Heh/fJuOQKOgCOwjws4nwSOgCOwWARcwC12aL1jjoAj4ALO54Aj4AgsFgEXcIsdWu+YI+AIuIDzOeAIOAKLRcAF3GKH1jvmCDgCLuB8DjgCjsBiEXABt9ih9Y7tEASOr36eQXxa8a4tPpL+/bb4m+JviTfF/9wheByum2MFHABeV3zOLXAB+Eziv4p/Lv6F+Fdb/35Z/35W/KWdCLD3uUkETqBWPUZ8efGJxcc2WnlzffaKJlv//0adUXxv8R0y2vhLlbmT+I0ZZRdVpFTAUf4a4ieIz1yIxCdV/griPxQ+58UdgdoIPEwVPiJR6V30/bNrv7hCfadQHU8S33hEXe/RM/TrOyOeXctHSgXcC9TL207oaauTZkKX/NEAAbQihMfZxZZmlAsYWseh4geIv5b7UGa5H6ncqdZQwJ1Fbf6w+CSZ/bSKget+4t9MqGNtHi0RcKjsL5vYs9fr+etPrMMfbxeBo6hpCI8pCzDsHVrHFSt3+a2q72prJuBYqwj881fAAlMVF9PiKVfAnVxI/LQCGrdWHS+pUI9X0SYCaG8IpNrE/MO3W4suoYoOWTMBdxq19weJNv9R339BfGRxSoO+hcq8vBagrdaTK+Dwu7050om36fNPi38nPqGYaA6DsUt8+t4zb9L/b7VVrlU8vF3TEDi1Hv/htCr2eBqT6pTif1Wu92Sq79ziE0UWemvuFNpJ4M4izHgUh/D7y+izx4ktre8t+vyalTFtrrpcAYdPBcdsSBfTBx8b6NUR9B3myn/ETFSn5SPwInURTb0W3VkVPadWZZF6iPqHZnVrAo6mv0Z8w14f8E3yN5kKMcIP+lHxOYICaHvHmRnXvV59roB7g1p6naC179LfV97rPfAGtIgAmhHa+zGCxp1Pf9/NaDCfYQH0ib+/Lt6OiN+6CDjwxId9JfFXxE8TI6hShL8N/3dIaNw/Tj28zt/nCjjMU8zUPr1Yf9xmL3ee9pODx8I5nvgbYnazw0a2i6RJFia5UTB1/kW8ucU40P8xsm7rMUx6hEEX1UIb5l19YlKfTXyAGN/K98Qkb041Bdm9icrxbnb5X4vRshEo9HMOWqnSDxkVg0PtqB5YnUdMWgXaGXMF7EiABbt/99qxLgJu7JhcWw9aOXBodUPa39j3NfOcJeBY4PcR7y8+7lZLQ/W268BQ8i47y1fFB21Nqlinj6ovMAfwF+BridGD9MU7tr5EqD1QzG5mpSJg0jxczKIdIlIFcIxfRHxxcU5uHzvho8WpxOWrqMwtxfgj6WOfdusPtJPnGo3rfJUswIeI7xfpwKv1+YPFm4k+9r9mweOvubB4KE2CvrEg8OvU3OFXqm9uAceGwfwlSjqUpsI44p/6vLi2gKMNdxSfVcwJgi+Kny5OBQkKhrKoKMGEmxlPMC9rbthFjdqOwpaAYwIyEWsRAYgLDFRG4AFtMEW3V4FXiR8pvleqsL5HwF5VTN5QSPT7yeJ7ZtQTK/I6fYEAQ8MLiVMdaFljibZzKiSVbkE5tLuUEMJBDW4sulJ6ih54lDg0IUvrofxKPJeAQ/t+hvimhQ1j02QzCmmsD24oksy82A6Tu9+Xh26Nfdi/D+oDlIpFUyjgOP6BCl+bMK/wGVj0KX2Yk9vDjntecT8ym9POXSoU7pwIBbTLqfRKVUB+4H+Dig7U32iQ20GYtZcSx84asoHgq5mSdItph4siNoa5/Vyp4BwCDsHxdnGOBp7b1rECbmg+P08vH7PJ5LSZtcy8JhfxiGK0SE47gLlFzNHUaY6c9zZdJhRwnNEb678a6iimZyyPzgpg1ATNmqiYo5ZmN+a999BDmB992tAfLx1T2chnMNUtJzJmSa1cJ/xznD2eko/GYqst4HCUf0ac0nZLoR0r4MLNrv9e3A/4w2oTidAcK8vd/BlL3E6Y5osmy0QFKA7m1iJOP2wMVHZJfbe71suMeljkaFp9wgGNIE9pNZiAqTKE6kmq7BOBge+Lay+6GEycDca31qcL6Y9PVMb1I6rv0uKxOWkrPVtTwIEzfYz5iKd0f6yA4waPmCY510kerBG0t1zCYmJTWDxZAo7ctcuKibARRYQY7HCxYrYcPIAQwoHBfq+4H7GyHsEZS07dScW8H39RLuFLw/fyJzGmWN+ZShtI6LT8ZPjnUNFxvOPDwhH8OTEOdiJL3xV3CxkhR0oM77GEFt/z/j7hwOVyAQIFMRP8hfqO9v9ZzEKNOf5ZGARV8MshZMKderc+w0ztiMx/MtpjAhah/CwxZt3PtvpJHxDUmNxDZtSUWzZWqrumgCPwxK0gMSIYRDoT/QVjTFnGm+DCXGdRCQqx4Vh0dX1IYnxNIkr8k4IKmXO3Kyi/1kVbTRPhxpGU5oTvaUMcOm2ZRAgvPkd7TKnhaHO5d2WhvXzAGPGL6rOPR2bCU/U5ZmxIfN4PljxTf7ORhEQwA19Kt0lgDoe5ZKEWSfCE4IBFj9eHOJ6HtDA2N85rWpoImwGC4m+R+oc+XunLWgKONJ5Y8jib1IaYCKlFzK3HRvDuyo/V4LhK7L5iNqRuDtNOrjYKLYkREJqPDGmN1gM30oevrfXylutZVwGHVsQuOdZUio0Ji6a7OPB0+j8mEKkmCEmYkDrXPoVE4uW7I5VaAg6BhD+r3376RLSyTywM2tHXQC2tJRRwZK4jdEO6vz54YuaERHvnHj/Lr4M2i2ZUSis9UEvAcVqCUxMhldyWEdtUqHOsgOu3h/w+xvj3pUAVlsfiwhIoMdWxLrCuFk3rJuAwOXHSvr/iqGDO4b+yMuxzX1Mq4KwQvSXgLP9eSsBh5scCAQg3js3lEmkElnldIij771rpj1oCLnYjSMnCPZbag2vCEuI1BFwuzrXKoXkTdCH3kkDaxkDFrCWyJhZ9hHKdBByLHfMT31gNIm8KUw5zbSq1JOBuoM7MbX6QZHyTEaDVFHBWcu6Y3C7y5qybe9dRwIVDgpWAiyMW9GBTHfJhjhjith5ZJwFHoi8XbtYgHMyYX7WinC0JOA6nE0CYk0hiRlsopVoCjjwvyz1B8AANt4RiOZFLEHDgcEwxflvrAgT8qWh7Q6ktJVg2V3YnCjhy/YhY1kwKbUnA3V19I5o8N+XOnX47agk4/IO/NTrIyZKDCztOUMAKMi1FwAEHmQkE5UgdCgmXxmLN1NxJut2H7a0oai0NzuqLtSa6WxpS0VyebUnAYTrOFa3r45Q7d+YQcDGhROSSKHEJxdIsliTgwIPMAitFhbSZWLS5BMcmy+ZO0qUIuF0aBRJwY0SO0PPFhN27vLaj6f/scgQjeJ47uUJqScDFUllosxUBHjMxiQqOuUZ8pedqBRmsTXDMSYHYwl+agOOYo5Xcy+3G5FYuknaagLMilQwsFwJcS5xKmESbs34VrCUBxzVIVloCGilm+ZSjVlMXQU0B9041BtxDIvJLsCGHSANCe7HcFUsTcFhAnIUNiZt5SNpfJO00AUe0zLptgvy3oauVOJVAciQRVyuloCUBx0TlhIJ1QwbBAT4vvdGCeYIph++La55KUk36C2elP2ppcLEFiz+J22vCCxbCBcyhdLT1jcjKriHgcPDjwLdO0pQKFMaA1A/q3C3mVEsuYYbyjOVuIdG9dj5pbrtmL2cJOHa1c4kxy4hWQYSSw10OrSeWNApgaArsjn9P9ALhsr8Y53/XHuvgOKkJmCAW8Q4iQhxPGooIxRI776rnuJutf6QMx+wuMcKL69qHIq449dEaOBPY3w15hshveFkoKS8IzP6dcpZ2SZ+4SRmsu35ZeXAsau4/68oNXSaAJse44afbjODJ2JNiwMJAWJBI2i0O+rchHjJrOHpHgjKLsU/URZZ/SAir8MJLrmfCVRC7fJMroGhLzEfKbS6c5giP0PFusGLMhg6nk14BRlyOyTjlRhqZw5zl7s8Z2nmg2EpHMeDY4yPWJGPbnTdlDEkgJ1oe+50G2kEOI3mj5C1atPjfZQgFHFn8XPdSK32CBUp2tRXxAnAWzvtyRjizDHVxH1eMrqcvmLgW0VaOW7HbskCtiFNOM5h4OLs52bBKPIBGhTBCQMXMZ6pggWB6bYqHzl9S7nJb5ekn/R0iBC0ChPOoEJn3FxSnxn/op/yGTgfk4BeW4Xd4rRMLlOP400EZGCMo0XgQuoxtTuCoX23JTxfGNEvq4+pw62bdFC5DgSPmELmhCHI2ZcaQ8SPhN9XPoSOGqTatxfehgON8HouzJnFCgElvUe3LNXnH0KAx8KmzqTX6TqpGeIVSrN4u8jck4Hi2y/FKHTDvbhbBnCQ1oOSWiZK+o92Hpir5hbWvO2fjQTBZZhTmFVqI5Ysr6UtO2VxhQH4lmq9FXK5JUKOU0ESnXM5asy2lbd+r5UMBh9bBUZeahFrODRQW5ar9Je1J+U5iUbOSd6TKEmnFBM0hQvec0EgJOExCIl4pAYdQ42YWiF2cY201c/6oNxatnOt3UfH/dVpmiClBFQIO1tnbHPxzy6TmVVePdcKi+27MSQuexU3BvYm1iLnEeWLLfK/1jibqCQVczQsSuw4OHcyubc7wzqHLNbs2MVljWuXUgcE/gul9aGZF3fVDKQHXLbCUgMOf2D/JwHlL/ItWcCWziYcrhi+I202sQAXBGHxCKdOo5L05QgHTjCRf3AM1391vZ868ojy3zZCqYxFH6HI3vvD5WlocPw/A7TaLF24AGAq4o+szHND8ICzmxhTCtMBJy8KN3QfHOxg4Lr1M+X1SbcEXQZJn7k26mG701Yo2hu9CaDExMIesKGBXnvvk6C83bXCnGhMppj2BD34yDvqTSc/VSdwIERL+Ofw2/JAK/kHqZCHHyuHE5+6zkPAp8q4w4GEU3eMj8ufwb5IPSR+HCHORe9hiZlrO+ygD5ryXfqd+4Kerk4AVprx1LMl6L+PERseGEAs44KfEz5c7r9CyD4l0cmpSLdeQY6paPyAzhCtYYikwv1Ljlzs+a1EuN01kLTozspFEmogac7PCfmJ8V/iRSDOA0VRQ6Zfy60NEq/kVMYIJJC8TjUTrIU1mU4zgJR+wY6Lh65ZGgNnKeLK5EFRgM2NciYjikCfZm6TX0nQZPZJFCCJ8z1wgyubOBaps5PysZQ0ixeUAMQKTiDd94/IIxpFN8DAxUWnGFJ8g2QXrNoY1cNpDg6tSqVfiCDgCjkALCLgG18IoeBscAUdgFgRcwM0Cq1fqCDgCLSDgAq6FUfA2OAKOwCwIuICbBVav1BFwBFpAwAVcC6PgbXAEHIFZEHABNwusXqkj4Ai0gIALuBZGwdvgCDgCsyDgAm4WWL1SR8ARaAEBF3AtjIK3wRFwBGZBwAXcLLB6pY6AI9ACAi7gWhgFb4Mj4AjMgoALuFlg9UodAUegBQRcwLUwCt4GR8ARmAUBF3CzwOqVOgKOQAsIuIBrYRS8DY6AIzALAi7gZoHVK3UEHIEWEHAB18IoeBscAUdgFgRcwM0Cq1fqCDgCLSDgAq6FUfA2OAKOwCwIuICbBVav1BFwBFpAwAVcC6PgbXAEHIFZEHABNwusXqkj4Ai0gIALuBZGwdvgCDgCsyDgAm4WWL1SR8ARaAEBF3AtjIK3wRFwBGZB4H91RixyiAYR0gAAAABJRU5ErkJggg=="/></switch></g></g></g><g data-cell-id="IkmhDn_4ef8kqVBRZHeY-15"><g><rect x="35" y="281" width="90" height="30" fill="none" stroke="none" pointer-events="all"/></g><g><g transform="translate(-0.5 -0.5)"><switch><foreignObject style="overflow: visible; text-align: left;" pointer-events="none" width="100%" height="100%" requiredFeatures="http://www.w3.org/TR/SVG11/feature#Extensibility"><div xmlns="http://www.w3.org/1999/xhtml" style="display: flex; align-items: unsafe center; justify-content: unsafe flex-start; width: 88px; height: 1px; padding-top: 296px; margin-left: 37px;"><div style="box-sizing: border-box; font-size: 0; text-align: left; color: #000000; "><div style="display: inline-block; font-size: 12px; font-family: &quot;Courier New&quot;; color: light-dark(#000000, #ffffff); line-height: 1.2; pointer-events: all; white-space: normal; word-wrap: normal; "><b>parentId:0</b></div></div></div></foreignObject><image x="37" y="289.5" width="88" height="17" xlink:href="data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAWAAAABECAYAAAC/K+/YAAASu0lEQVR4Xu2dBbDtVhWGX3F314u7u1/ciruVN2gpWty5xd1dH8UpXtwLFJfBi98Wd3f9v3IyEzZbVuwmOVlrZs179yTZ8if5995Ldvba5eIIOAKOgCMwCgJ7jVKrV+oIOAKOgCOwywnYHwJHwBFwBEZCwAl4JOC9WkfAEXAEnID9GXAEHAFHYCQEnIBHAt6rdQQcAUfACdifAUfAEXAERkLACXgk4L1aR8ARcAScgP0ZcAQcAUdgJAScgEcC3qt1BGaOwAXU/stITy89hfQ30m3pt6UfkP5t5v3bkeY7Ae8IzF6JI7DrfMLgMdILSU8XweP3+u3CKwKbMlxXUeOesGprqp0/04GnSp8i/ceUOzN225yAx74Dy6j/GOrmVaU/kn5hGV3+v15+Wr9crND3C+r4FyeKD1zxcOlWg/a9WefeUvqXBtcs6lQn4EXd7lE6ewnV+jYpy1Tkg9JrSP/eY2v2V1n7Ss/esczv6vr3Sh8s/XXHsuqXn01/fNNQ3pQJ+L5q/5MMfQhPeY9+uJb0Xy2uXftLnIDX/haP3sHXqQU3DVqxt/5+R08tO7/K6XvW+ECVyTK7Lzm2Cvqp9PiFAqdKwJdXuw/pAAaD4ws6XL+2lzoBr+2tnUzHPqeWYNusy930x3N6auGjVM5DeyqrKobZ6jl6LvM+Ku/JMyXgj6ndONxS8iUdOFNhgMFZ94OeMZ19cU7As7+Fk+/AN9TC0DTwAP32xJ5afjOV89qeyqqKebX+c6uey6S4M0ovLj2X9IBI+VOcAV9a7Tw0gcXD9DuOtj+vjkPSb5JW5qb6Za/QH/sMgOmsi3QCnvXtm0XjhyZgHHxfjpB8F3Agyc90KaBw7Vl0nHCtUKZIwBDqDSJtvaN+e3Hkd2a6RyT6f1L9/qsBcZ1d0U7As7tls2vw0AQMIEeXXlJ62tX/6yDdRn8QgVEXQr7uGvz2b/1N+BRRGj8fGOW5EDBmmMMiWHxev11UCmYxeYR+3Ioc2E+/PW9gbGdVfBsCxqFwZulZpYx2f1o9uNv696uZm9IUmGPpArzHLGdOLmX0/KuU0RVb0velvEg7LUdThcR0Es/JA/iVVb/Boa0cc4XnufXvqaR44CED+vn1HjGNtQ9cedEwE9AOCJOX7idtOxNctxMEnGsqoVPhch+bJYkEfcsJVCD27lNKTyblmfiWlNluHc+5EHDKbn1N9efdGfBOrGOHS0On41C4930fd6w8CBhb102kkCnkEgreapwc15USnpOLZYQ0XiXFLvTDhr3g4SXIGzsSdidmNCX5pE7g5SLUJTUax8o4tX4krIaX5SSZSnjQiF1F8ATjHee3UBgIeNGfK7VmANEG8LySFOJNCZgSSXCg9LOZ8+qHINR7S88jDV8CBrFNKfeTsKJYUgBl0aeXSR8i/YOxXp6fO0vBiOcJIUohJryMOSGAn5eYNhxsrD922tAEzDt0PSmzu3CmXW8PeD5f+nQpk5i+TRBMCO4iPaeUED8iQ56xwrAtfEQu3Cm42EqiJJ3wfIdyXP3QZbLSti+TvI6Hx0JcX9N5OZKIdQ5ifLTUkglzC52H46OtsCS6uZTZhkXeoJNuZDgRAvujFI/9tQ3n4z2HfIgnTQk2S17WpxnKC095q37AgcWsMiVH0QFsorn7RTutMbP05bZSPOElAVOw7VvwsG+3LHRIAgbjPdJSgkXYdGKhGXhDaWsDvpoKYhISE1aRMbK3wPkRnXS54MSX6u/bGy6+sc45KHIez531PTVUM+9TrATctpfv04UQY87wTht+Ky3FSJbaAKngPKGsnLA0tNr4nqVz716qODjOYMXyNjbwMLNnRmclv1TVPNxvTBwEg081bLPldGbMpZnoO3VObIVgKT93Dt52BvM2MhQBMyC/vU2DMte0JeBclh2zbmbGbeR3uih8Lx+k3x5vKIwZOROjUBh4PmS4fhGnDE3AgIg3eVOaWnZgd+wrVZEZ4vULd476IOCuhJ+rBtNGmHLLbBp7cV9yRRX04Uhhp9FvTc0/ljZhj2Z5y4ogJXjFLbMjS331c1gGv6jpRavzhyDg3IyzZTOPvKwtAedWsaQD37BFozAJxiYzJNXEZrZhFanrc5OHFs2c9yU7QcAgxGwN4FNiNQlY0MZpV5rhYpvCRjWU4KT8Xq1wHF3MUvi9L8GmSDxpjGz36HfMBn1LaSaamvV0aQf9ZFCx2qHDuvomYAYh7uUQA3hbAo45OiscIMswE9FyP1IrxSvoYkwTFokNDAzQmDFchAAEjNed3Hz+JbavRBKQKYTJDA9bDtEK2MJIN8zNfoglfEsCdWaHj5NeR8oLR/YUitOJeoh4qGbQ2FBZyrMkjWXnXF2/k89fEmapm9LjSDcKba+XRfuww75GCjEQYF7P9HqX/ib3vRJssphiYjY/zsHJhrODZALsrawGmKXTJl4cssZige1cm7PHXUTHWXrm7gl9IZPs41JwxkGHvRUHXmzZiu3yyrW+xf6Lh39TSiTAUaWPjJyE8xRzRU5wZjK44ATusi9D3wTMVoupewme95PSP0iR/vNugIcl8aQtAd9f5adSpy2mo9h9cAIuPKB9HA7D0EpLSMJS2GYuJTgjsIvFCANywSGQ25QDcrVGEZxQ57IHaSht8viZ1RDuVRKWwURPYBurhDbfQUrfeTkZoKrMIM4hXjIV1A9Z31qas5GzlNsjjQXDU/55pYT/xYSoEsg/JpAEq5KUueIlOna74EIGC4i1iaxTGFrO9MBMk8ESjGLCxAZMNzPgtSVgok8gfuyz1cycdvC+vrLJzaqd6wTcErgmlzUhYGZ1EEZJiA9OeTkvpWO8+BbhQSJ1E92QEgsM4bKpCQ8XyiwqDKNiJh0Lf8nVWSJgZjYE9GNjbipbuoDA9FCY2RG+9E9DgcyimXHHlpI4RHjxYpIi4I/qZJxIuThqbOnYD0MhbK/JjHSdCJjVDgNmKLwX4FmKKGJlg/kiFZrXloDr7cHchQO45IwuPXZOwCWEejhuJWCiAe7RoD6yjJ4dOZ/QtK1MOcRHEkcKoaSW3aVm9E3AxD0y+8yFluXaxOw0FhLGy9zEWcYAFDMnEH6ECSkmKQLG3MRAlhPisD8ROYFssyo2unQvOL4uBEy23S+loe2XQYwB3IpJbve2PgjYck8s5zgBW1DqeI6VgHn5f9GgLs6PLcVSG3KwhGKGyWyuLfFWzeuTgF+vQlmG5zz/OVggq6F3gIIAMFPEJEXAJ9LJpRmSE/D/Ippa2ZGk1NShmzL1TYmAeUZiKx1rFMTxdH1shcV73tYs0oCC5nGqhYCZ+eFYaSrf0QWhQw97JHa0ukC+OOcsiQ6WNvRJwDgHiettK0PsVRtrC87AH0cOOAH/N0Oxj1Tk1K5gpbTc2P0irC62P+6UCJh2x0wqZEY+1vBCkK4fy3YkscOS1GOoYv6nWAiYUQy7nyWjrY5IbOkdi9PFvIHzoi+ZEgETHUE0x9DCVyewLYbiBNwfAacSL9pkmmH7j0UETY2AY+/wy9X23YYHmuiLmM+kqQnLUNV8T7EQML2zhnZVSKScWtiF65llhDqxf4JFMGlYzBNTImAciNuWznU8B3NBLPvNCbg/Ar6sMMZ5GQqhkITxNRH2XsG8FcrUCJhPSREaWhdWhKwMS4JphhDHUHAol5yVpbLX5riVgJkFs5zeNvQc2xFkEEu3hXBJjawkZqaojmGu4AsCpDNW9mfMFZAwTiQ2s3mmNDRzTImAcSqmMgCt0SAlyImiIOkCLENxAu6PgFNbMzKhiDmcc/eNmGDCxkKZGgFjboilgJfMLth/cUqGDkveZeLTXVYIWAmY09lrAQN6bKlbAYqjguSAcAOP6jgxpJVzLjU7hOzx6ltmFbEc+CkRMP3G3tUlYaTLwzpVArbuJ9Cl79W1fdmAUynzPK9MNqzbdxIRk4rbnhoBb6it9YzOClOIlLj3VEw/iUqx/SJKmZR93O9ZldGEgKuOEUz+whUhE5fL9nI8gAT15+JvQ9tRagc0i5eVbKxqK8cQ8KkRMFllbM8ZCi8ufc3tq5p6mLDJ43jDQZrb2m+qBByaolL9ZCaF+YuYZJatrJ4sA3O9vL4ImDJjHxjld0IB2W+htM0ioV2HSFM71fVBwLyPYFVqSwrz8HeySmPbbPK5eWLTQ2FixW58sVTtptFU1jbO9rw2BFzvLCRiyYln1stDRxxlJSk7GKFq+0nD3H/MDniiyXTLbf+H6YLtI1kCMVLHEh2I6sB5wguO8P+YZ5clWOpz4qQMU34p/jO1OXWFA6TCqiGVLQe+1QbwZNWxL3FldqnSosOvDEDQvMzYLcMIAOqF+JnZYM+LvajM9jBrxDz1rIJI0LCG5rHz1WbV2dW/tJs9BcINiziMmYnz2ad6d3Adf+JfCLfj5Br2oWBQIl63LpQRRthQf5jlB2mxhwie+1iGJWUy8L8/0iZ+qjLPIKXwmQNPzG+kZefeFxJ2eKZIwbfOqKmb95h3hsGm8pMwOG9JeZ+6SOo9pUxi9skOrWy6vJ88GzFfDduvMhlxqSHQlYAtYKZMCqVdu/CgYvs9gxQnk4Xow/bwMkFabFBdSWxGZOlH6hxL6rPF2Ui8MPu28i97MhDby7aWpa0rwZfBqSJSNujBBm/Bi8EFc1E9ZhvbpGXfAlYwlo9hMrClMvUgG/pM2zFPMTCW+otNkqVsJRAuhJXKLmt6b3ODA2WRal8KmaRf2OQZGLAdp2a8ubZxH0pfUa6uhwjrvpV6uV13H8NpxuY7MTMa9YAX71n19ZpUn8INqprel7U8f2gC5sXGnhub6QBozIbbN9D1B5CRuZQB1rR+y25d4Mwsd3fTwo3n1z3xFoKoF7u//uArDQgz5/oqJVc95M1stOTRxmFT2njH2M0jTwuJKTdDa1Ju/dxcqBUTB55nS0RO2/q5jucKR7NlpUGoY31DqHq9pLzv3aUhupZBvUs8vNXk1LGZ87vcSsDWELA6AsxU2Lgnt28AO2/x6RTLbK0tuszAMCUgQ2yXSLmYREqfC2LTHmaMqU112vaPe7MhrTYAIn3Y8jmnqr760rDpnsXWfSEOVGWYLroKpISNsf5MpT5906UuBhdmrilhAyQ2XhqahC3PFW1kUpFqi2UHOwtWbELFJ6yaCqY1zGZ97fndtP5Jn28hYEwBfNUCZfaRW07xgjB7wBFWso1WwGA3whE1FAnXHRv09zBpaZnb5KZha+NltSSqUD92MOvSstQOyBdbbd2RZzF31Mvl5ajHtzIgWpbzuT0ownbjGGIZm5qllfrJcdJX2XYxzPgbItvQku3F80qsK20aQpo8V7ktMhn0MRf1IfQ1te1lrHxCLXFOxrI0+2jP7MuwEnD9KxM4lbDVodhn2UoRp0j45dcm4OAdJqqB5bBFCGLHuYD9NWWb4gHGORWSHbPDLSne9S5S2b54KJt65jd0zT2l92rRAGZneKYPluLgqtu3KQ7HInZuiDk3QwMfHChhuBCzLhx3qU8L0W9C67hXuW/ThV3DVruPlBWJdeZ4qM7FqYVjJzegMztj4CntZV2CmwGNnc0YJHNbhNbLYQAgmSj1HIZ1EkGEmYgkh5i0ea4YRImuiEns6ywlHHLHMflsSUsTMVa/rE7C57NL3Wt3bRsCHhIEXiBmxMQTM6vky7q8FNvSw1f/MpNqsh3ikO3tWjaJGjgJiVZgMGMrQZSX8AgpG9Gj7JrGLAIS6iu8qGvb215Pn9nQfGPVZ8xQ9BnbM55/ojPwDWBnnVNfcSJWzy228YqgGOjQbSnPrpXYm+KLeY0dCzEjEYVBKBgkyIqvb4E3IH3q5Lklvbh6ZolxxuZf3xO77/rXprypEfDaAOsdcQQcAUeghIATcAkhP+4IOAKOwEAIOAEPBKwX6wg4Ao5ACQEImGBxMq0I5sd5E4YwEf9HbjdCzCchL9h53MZTQtePOwKOgCOQQQACzn3SOnUpjjH2oN12dB0BR8ARcATaIQABlzKZUiXnPgbZrjV+lSPgCDgCC0KgCwETvE8oiosj4Ag4Ao5ACwS6EPC+qi+2W1aLZvgljoAj4AgsDwEImEwx8vSt2UkEXB8kJZMr3DJyeQh6jx0BR8ARaIlAPQyNaAi2nssJO+Bb9jxo2Ry/zBFwBByB5SAQxgEvp+feU0fAEXAERkbACXjkG+DVOwKOwHIRcAJe7r33njsCjsDICDgBj3wDvHpHwBFYLgJOwMu9995zR8ARGBkBJ+CRb4BX7wg4AstFwAl4uffee+4IOAIjI+AEPPIN8OodAUdguQg4AS/33nvPHQFHYGQEnIBHvgFevSPgCCwXASfg5d5777kj4AiMjIAT8Mg3wKt3BByB5SLgBLzce+89dwQcgZERcAIe+QZ49Y6AI7BcBJyAl3vvveeOgCMwMgJOwCPfAK/eEXAElovAfwAhUqhy5mSaEQAAAABJRU5ErkJggg=="/></switch></g></g></g><g data-cell-id="IkmhDn_4ef8kqVBRZHeY-16"><g><path d="M 80 180 L 80 239.63" fill="none" stroke="#000000" style="stroke: light-dark(rgb(0, 0, 0), rgb(255, 255, 255));" stroke-miterlimit="10" pointer-events="stroke"/><path d="M 80 244.88 L 76.5 237.88 L 80 239.63 L 83.5 237.88 Z" fill="#000000" style="fill: light-dark(rgb(0, 0, 0), rgb(255, 255, 255)); stroke: light-dark(rgb(0, 0, 0), rgb(255, 255, 255));" stroke="#000000" stroke-miterlimit="10" pointer-events="all"/></g></g><g data-cell-id="IkmhDn_4ef8kqVBRZHeY-17"><g><rect x="20" y="378" width="120" height="75" fill="#ffffff" style="fill: light-dark(#ffffff, var(--ge-dark-color, #121212)); stroke: light-dark(rgb(0, 0, 0), rgb(255, 255, 255));" stroke="#000000" pointer-events="all"/></g></g><g data-cell-id="IkmhDn_4ef8kqVBRZHeY-18"><g><rect x="35" y="383" width="80" height="30" fill="none" stroke="none" pointer-events="all"/></g><g><g transform="translate(-0.5 -0.5)"><switch><foreignObject style="overflow: visible; text-align: left;" pointer-events="none" width="100%" height="100%" requiredFeatures="http://www.w3.org/TR/SVG11/feature#Extensibility"><div xmlns="http://www.w3.org/1999/xhtml" style="display: flex; align-items: unsafe center; justify-content: unsafe flex-start; width: 78px; height: 1px; padding-top: 398px; margin-left: 37px;"><div style="box-sizing: border-box; font-size: 0; text-align: left; color: #000000; "><div style="display: inline-block; font-size: 12px; font-family: &quot;Courier New&quot;; color: light-dark(#000000, #ffffff); line-height: 1.2; pointer-events: all; white-space: normal; word-wrap: normal; "><b>frameId:1</b></div></div></div></foreignObject><image x="37" y="391.5" width="78" height="17" xlink:href="data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAATgAAABECAYAAAAV6ClkAAAPnklEQVR4Xu2dBdAsRxWFE9zd9eHubmFx9wCF1o8VhbtbcClcgkNwCneXBA8Ed3+4BHeH84WdqqHpnu6Z7e2a3f/cqlvv/TOtZ3rOdN97u3fffSxGwAgYgS1FYN8t7Ze7ZQSMgBHYxwTnQWAEjMDWImCC29pH644ZASNggvMYMAJGYGsRMMFt7aN1x4yAETDBeQwYASOwtQiY4Lb20bpjRsAImOA8BoyAEdhaBExwW/to3bFdisDR1O8LSy8r/bL0LbsUhyO6PZXgjqK8+0vPJz3TUs+if/8s/an0Z9LDl/9+Uf9+WvqF3Qy0+z4rBE6k1jxaemXpSaXHjbTulrr2slm1Ot6YI+vyeZeEdkX9e41esufo/3fYgD6srYljCY7015E+XnrWka36hNJfRfq7kfmc3AjURuChKvDhmULvrPvPql1xhfJ4B88h3U96eelVEwRNVSa4kYA/T+lvNzJPP/lcB80KXXLWAAFmRZDHuQZevBLQfq5Eh0rvL/1KSYYRaX6gtKfZMII7htp7T+ndpCcr7KsJrhAokjFlf8mI9LGkr9XFG61YhrPPFwHsP5BH6QtY0pN3KxGzlJqCXepaG0Zw91F7nzASBBNcIWCnVLofF6YdSnYb3XxRhXJcxDwRYPYGIdUWxh+23VrC8u6QDSO4D6m9lxkJgAmuEDDsbm9KpH2rrn9K+hvpiaWnl55Oukd6xl6eN+r/t16mK6zWyTYMgdOqvd+v3GaWqqeW/qNyuadQeReQnkT60kjZczOnvHD5/oyBwQRXiBY2FQyzoVxaFz46UMaRdI/lyr+kDFTL9iPwAnWRmXotuZMKOrBWYYly8PqHy+q5Edyl1MaPRNr/AV17r/SB0tAbbIIrHDivU7obBGnfqb+vXpjfyXYXAsyMmL0fK+g28Vl3jUDBNVYAfeHvr0q/1QC6TSA4YNgjvbn099LPSz8p/dMSn7fp336ICJdNcIWDh+Upy9S+MGW+bWH+dSXDZU4cHi/OCaRfkxJ398uJFZ5Q+XgxiY1CKZMBtHepGND/NrHsWDaW9JABbv9fSZkNU1dfIIlzSs8jPar0O9JvSFddCh5PZZxtWTdf/l9ImWVDKPRzHbJQoR+MFAwO9L+mgNUFpaeSMjtjrIDdN5fY/bNX2aYQ3BA+JrgIOrE4OF7we0vPLT3+Mg+BhDEZCt7lK0Mk9ROXgyr1cI6uGywHriDF1pISpuBvX96E1B4gxSMbC9JkSfMwKS/tkBAqgGH8klIMuCWxfXiCHyXNBS7zNb2VFHskfezLwfqD2cmzI43rbJW8gA+W3jfRgVfq+oOkezN97N/mhSfs4hLSoTAJ+vZ6KQ6hH44oP5d0oQTrJjg+GIxfvKSxsdG1kef4WOlnpbUJjjYQYHt26d+lzLaeJv1eDqAV7pvgIuDFCI4ByECsJTggLjpQGI4HZoM5ub0SvEL6CCnxQDmBYK8pxfsUCv1+kvQeuUIG7r9G9yCwbonQT8quDmZZU4W2syskF25BOmZ3ORLCkA5uU6Lan6x8j5SGS8gpfVso07oIjtn306Us4cYIH81waUf+qTa4IU8y42JdS24TXOSphwR3ZqVhCl9bWF59KVEodoSLFFTIF/dC0r5ntiDbEXaL8MsJKTC7XFVergKID/x3UNAB+psZZAthWXs5KTOFmPABeap0aDaTaydLO0wUqWeYy9/dX+g/6yA4iIMXvGQGXtrWqQQ3NJ7XaRMzwUWebEhw7NGbar8aGjgsPVNxdDEHRukgLEkXG6gsR2Mzu5LywjR31wWWH33Z0R8vnlLYxDws1fkAhHILXYiFQEypBvsce49XiUdbB8ERmnKYNDfbHdvnqQQXfuz69WJ+uP7YhhSmN8FFgIotUdl/d8dCUEuSsfuBFz4lnHpwcElBE9PwkjPT6gsGaIg8N6thCZhLwzYitiX1BcfAd6W1X7oUBOwNxrbWl4vrj49PxCyV7cO6wf7HqTFpC+WtOYMDZ/qYshGv0v2pBPd1VZqaSa5zJ48JLvK0YwRH7BqnEuBhw4uI8LDDl5Vly0EDIwhy4GG/R9r3WMWyYIwlpu7kUurHXlQq2NKwvfxBylIMQuuENhDQGbOTYZ8jvg/DOzYsDMGfkWJgxxP7bWn3IkNyhMRQT4y0uE/9fcGxwOECOApSS/Dn6x7t/6OUFzVl+OfFwKmCXQ6SCZfpB+say9ROiPz/XKKtpIGUnynlpfiJlH7SB4iaJfeQrW6VUzYWKrsmweF44lSQlOAMIpyJ/oIxS1meN86Fde1FxSnEBycm19ZFAuPXISa4CKqlp4m0DhPhxJHczAnb0440NNoyiCAvrjN7xEM2JMzmUvarMB+zl/dHCiMI82OJSp6i6yxjQ+F631nyDP3NhyQUnBk3lXYfCZbDYSxZOIvEeYJzICaP08WHSIdmYXzc2K8Zm4nwMYAo/jIEauLeQtdrERxhPKngcT5SO1I8pDFhbD0mgXeXfuoMjqPE2DfKB6kbw7TzXtJwJTEBwmQWE1wEmk0lOGZFfCWnLpVSo4SXhq1me6RnkLIEItQEkkSJgePYp1CupgvvShQaIzgICXtWv/30CW9lX3gxaEd/BhqbtYQER8Q7pBvK/XShdMM2s3fO8Ys5dZjNMjMaKwtlqEVw7JZg10QoYNbFFebal/qokG8qwfXrJL6PZ/zbXEMq3DfBRUDcNIJjyYmR9n0VBkRXBMs57FexCPvSasYSHNtriPvrS4zgYva9HMGxzE85AiA3ts2VCm2MLa/HEGW/roX+qEVwqRNBMAtgFimR4ygRpokYidcguJI21EpjgttwguNlZ/mJbayGEDfFUo7l2qoyJ4K7sTrz6lU7lMlPkPHNJtRRk+BiwbmxD0eumcTNxU7uNcHlkNuA+5s0gyPQlwM3awgGZpZftbyccyI4NqfjQFinEMSMnW6s1CI4jumOmSdwHjDDHSOpmEgT3BgUZ5p2NxIcsX54LGsGhc6J4DjxFW/yuqV07PTbUYvgsA/+OtJBdpYcNLLjOAViTiYT3Egg55i8dJDOwYtaawYX60vs2WDvQ3LeXNLMieBYOq7TW9dhVTp21kFwKVLCc4mXeIywGf9HkQwmuDEozjRt6SDdFoLbo+dAAG5KiEt7rpT4vS6ujbPwMdzjjCD/qyKZ50RwqVAWmh3zAE8ZmngFpxwjvlC+Wk6GWCjRlJ0ChBTFYtNMcFNGxszy7DaCi3kqeSQcCHC9xJe8/8iYzcV+FWxOBMcxSLGwBGakLMtX2Wq16vCtSXDvUGPAPRQ8vzgbSoQwIGLlYuYKE1wJgjNPs9sIDm9Z7LQJ4t+GjlZiV8JNpHhcYyEFcyI4hlwsZIDrOAc4OWPsiRaME5Zy2L445mlMqEn/FahJcJgs2LweCnFwnF6TO5qIH8hhtr6TeEdrENyxVTZ7U2M7aWpTg8NEIojGCI6v2vmlLMvwViFshwm/csx6UkGjeLiYKfB1/GvmSUIunD2H8b9rT2zjOKEJLEFiQh1E2LM9aWizcyqw8y7Kx9ls/S1lbBnbI4W8OK59yOOKUZ9ZAyeUsIWtE/Lg+Q0PCyXkBcLsnykXm13SJ05SBuuuX7E4OF5qzj/r0g0dJsBMjueGnW5vFM3/PnsCkdnWBFmwda+zRdK/HSlbxlLC1jsClHnB+0JZRPmHAlmFB15yPBOmgtThmxwBRVtSNlJOc2E3R7iFjrrBimc2dDINO0jAiINFeU5D46rfH8Ywe7n7Y4Z2HiBd9YekwbN7NxmffSHwPewPJgm2AvaFjxPvJvemfqiCIuf7Z0hwRPFz3Eut8AleUDZCxzxeoMKLw3nytYSyOI8rJTfUDQZuTGgr26342vKCsll9irBzAWM3OxsWmQKYUUFGEFRq+UwRvCAsvfZKh/Zfku5Ky/T0k/4OCUQLgbAfFSHy/mLS3PMf+im/od0BU/Dkd3hjOxYoi+1PHKg6JGAMUbKPF9Ll2ZY4jvpljvnpwtTMkvL2l3KQ6BThkFcmDGPbnqqLscLxYzXO+ZvSnyZ5QoJjfx4vZ01hhwCDPia1D9ekjqF9oby4ub2pNfpOqEZ4hFKq3M7zN0Rw5O1ivHIbzLuTRVhOsl+XOK91CLP7cAZAfGHt48758EBMsbg39hG/WRqzxdXu89C46tdFfCUz35hwuCZOjSlyoDJNObB0qK4ay/ApfWmWJyQ4Zh1sdakpTMs5gSImpdP+Me3JPbSU12xMHbm0eFpZgpYIHjx2aOQIjiXhftIcwUFqnMyCcFYa29pqxvxRbspbua7fRcX+180yQ0xxquBwiO29LcG/NE1uXHXlxHZYdPem7LTo8rL9jNl5TZm6I6VmG9ZaVkhwNQ9I7Bo+tDG79nKGOocO1+zaxGBNzSpXBRwbF0vvQwsL6o4fyhFc94LlCA57Yn8nA/stsS/GnCuFTfyfZNj5ON0k5qjAGXO4tNYyiopLSAF7FEG+mAdq1t3veMm4Ij2nzRCqExO20JV++ML8O7pQ+xBV7LtvmDIINiVPSHDHVMMxQF9XmjsvK9dHlhYYaXlxU+fBUQeGYA69zNl9cvVhayHIs3QQsHSjr7Hz+MO6IC1+N4LlUCyOq0vPeXL0l5M2WE5wTFJq9gQ+2MnY6E8kPUcnhQZhysU+h92GH1LBPkiZvMihdOkw4nP2WSjYFKkrdHhEkv7fJQzS2DeJh6SPQ8JykXPYUsu0kvpIA+bUS79zP/DTlYnDiqU8J42UCM+JDx0fhJTDATsldr7SccUs+5BE5WCSOsIp117eTbz49G3Vd4Wxx8qK8nJnNebaNev7pWEis+7Eio3jtAw8U/weBcfsYLvCjkSYAcpMheVhzZ8LXLHJK2XHW82viOFMIHgZbySzHsJk9koZ/ET2d4rHrfaxVCt1oCAzy1aeJx8XnAp8zHiueEQ5rIFg78OWz7aguNFJ+FUtbM8cIAqBcIAqH3J+1tLSEAETXEOwXZURMAJtETDBtcXbtRkBI9AQARNcQ7BdlREwAm0RMMG1xdu1GQEj0BABE1xDsF2VETACbREwwbXF27UZASPQEAETXEOwXZURMAJtETDBtcXbtRkBI9AQARNcQ7BdlREwAm0RMMG1xdu1GQEj0BABE1xDsF2VETACbREwwbXF27UZASPQEAETXEOwXZURMAJtETDBtcXbtRkBI9AQARNcQ7BdlREwAm0RMMG1xdu1GQEj0BABE1xDsF2VETACbREwwbXF27UZASPQEAETXEOwXZURMAJtETDBtcXbtRkBI9AQARNcQ7BdlREwAm0RMMG1xdu1GQEj0BABE1xDsF2VETACbREwwbXF27UZASPQEAETXEOwXZURMAJtETDBtcXbtRkBI9AQgf8Az8IRcsSOV0UAAAAASUVORK5CYII="/></switch></g></g></g><g data-cell-id="IkmhDn_4ef8kqVBRZHeY-23"><g><rect x="83" y="199" width="80" height="30" fill="none" stroke="none" pointer-events="all"/></g><g><g transform="translate(-0.5 -0.5)"><switch><foreignObject style="overflow: visible; text-align: left;" pointer-events="none" width="100%" height="100%" requiredFeatures="http://www.w3.org/TR/SVG11/feature#Extensibility"><div xmlns="http://www.w3.org/1999/xhtml" style="display: flex; align-items: unsafe center; justify-content: unsafe flex-start; width: 78px; height: 1px; padding-top: 214px; margin-left: 85px;"><div style="box-sizing: border-box; font-size: 0; text-align: left; color: #000000; "><div style="display: inline-block; font-size: 12px; font-family: &quot;Courier New&quot;; color: light-dark(#000000, #ffffff); line-height: 1.2; pointer-events: all; white-space: normal; word-wrap: normal; "><b>stacks[2]</b></div></div></div></foreignObject><image x="85" y="207.5" width="78" height="17" xlink:href="data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAATgAAABECAYAAAAV6ClkAAAPwUlEQVR4Xu2dBZAtRxWGE9w1uC1OcCkonIe7B3cnuASCk+AQ3LV4OMHd5QV3d13c3Z3/q9qhhn6nu8/MHdu7p6tOvX132ubvnn+6j/Tsu0+kQCAQCATWFIF91/S+4rYCgUAgENgnCC4mQSAQCKwtAkFwazu0cWOBQCAQBBdzIBAIBNYWgSC4tR3auLFAIBAIgos5EAgEAmuLQBDc2g5t3FggEAgEwcUcCAQCgbVFIAhubYc2bmwGBI6pNndJziA5jeQkkh9Jvir5muQbkj/N0K8d22QQ3HoO/dV0W/eTnFlyUuMWf67fTraet77XXd1dvxxUuNe/69pPJO+WHCb5cw9czqoy95DcRHLcSvkX6PrBkl/1aIcix5DcR3JFySkkRyvU82xde2TPdtai2JIJ7oRC+LKSj0p4C0byIXBiZfulI+uSx97RfXeWxyrnfZ25D1Q+SMGbjqKMd5U80VtgK98f9O+dJS+V/Kdj2Tsp/zOcZbgX7mnHpqVO8ttrRJ7TGpVH6O8H79hR6nbjN1X2lziKLHXsHV3vlKULwX1GNV/AWTv4QVA3dua3srFi9JJvU/7T+uP8zjaD4JxATZ3t92owXeqzMvn11B3Zhu2dS33+gqPfQXB7g/Rq/XR9B3ZkeYjkUGfeUja2mu/qUM+LlfdmzvxBcE6gpszG1tQisvPq989P2ZFt3NZr1PfrVvofBLc3QBfXTx92jPu5HXMRPec3JaeTnLpQJ/nOKfmFo12yXFDyCWfeIDgnUFNmO6Uas3RuF9HvH5uyI9u8rfOp/2eTXFlivfF3MsGhA2MFRkIHBsmg6910jnnpBfI01YFKhTqbtJ/+eIDknpn6WQke4mybbOxmGFf+PdJWOYxKqUEpCK4DqFNlDYIbFukbqrpXGFXuZIJjlcZqrU86lgrlXD2wXr+1UOk1de0NxvV36rcr9elMq8xb9PdVkzqC4FYEdYziQXDDohoEt7cifxWCY2WMMSJNXv0dK7y7JIVZUR5f0tWi2q4mCG7FtzhL4ZNLNiSnl5xIgq7sp1vydf37zwGezTkJDv0fTpo4aCInkOAXtbklP9C/+E0NnXA3wDhwKgnbGQwsv5Xgn/UzyQ8lv+nZ6FIIbqr5k8JkWVFXIbicjvi0apj5UUtXV4Y3GZl4pphnfVMQnIGcZ5uC2fyhEgamlHgLvUiCx/Z1JH+T4K9TWrJTH3oEHDEvJOHhPo4EkkkTOg3ItNYHFLtPkngsiSh/ryC5qOQSkrNU6ucyb2p0LJ76a9XRLn5UbC1qDqJvV56XSXip3EqCw+fzJG+T/KvQkIfgLrzVD3BnC2YlxpcH87kSyNebxp4/tX4MTXC0l1pQWZF5fdNy47G/6uDZ6ZuC4AzkSgR3duV/mKRmjasNyOWV4T2FTE/derhq9XS5/h1lxov/35lC3PcTJDmlr6etVykTRNPH850wHsgJF4FVEz6D1JVLNYI7tgqyUqwRbFM/hIFCu5ammj+1foxBcLTJyxE93mcl7F486cjKdITkYkZmVoZdXhxpFUFwBqg5gvP6UnkG9VHK9MBMRsJMWOmNkS6lSj+QqZiH78sDNIqj580lXXQnrBRZ1XoJpdbNNyrDtQqZagR3A5V9Za2R1nVWcjyMpVXjVPPH0+2xCM7TdpoHp176kyZUELz0VklBcAZ6FsGhe0KJWvLd6TIQxN7dNlMAvQxbSmtL2qUNKy8kRpCzlSCZHPl1bZcYxKc4C7Fd+5QzrzfbJ5WR7X0u1QiOF8Eeb2PKh6qAGMjc6njK+ePp9lIILo3Oaff94fpP47biuScrTxCcgYpFcLdWPkhpqLRbFbGVyyVi8p4+VGNb9aCvukqhzqPqGsHOtVUUq5Vanq8ozzkc/Se4Hb2dFfzuKJ7NUgsvqhHcJVUz2yZvIhbyWYXMU8+fWr+XQHAlcmOOnUnS9pur3ZN1PQjOQMUiOMiNSZomTlvg2vu3yIEtClZGPLWvLblXhgw8vjgo24lUwDLLCuBuRvsv1281JSz+Sd+WoHj/R2WW4LOEgyVxfWwRiJKALCChL27V01iFITkIE32hRVBc/2OlPcs9oF0EQw66Sla0eLWzfcdqfRnJHSQYAqy0CsHdThViNCilZ+oiOjpeCLT18Ur+OeZPqUtzExzqGYxSuVTznavA/b/LQXAGUhbBfUj5UiUobxlWIH8poI31DQK4TZIHD+5He0dJ+aZ2E2E1VyPDpvuQzXuNewGvjxTukS04xGul9+lHCOxbFYxyBNmX4Hjx3LHSZp+Hb+75k97SXASHQQFrPlbyXLq/Ljymw7NRyhoEZ6BjERxvdN7sacIyiVKd0wywGvHApn5vKJ/RMTU6NQ742yVhBeBNUxNcu1+sHlmRbkjwS4K0OXoIXzQEHzgrXIywmXcUbpDVLVbbNLG9RS/3Vwc49AWLXerKAkFyrFQu5baopSYZa1xXaitmq46550/apzkIjoMvd0tKgftdw7NqUyQIzkDIIjgMAiW3g3Y1PKCfk6DMh9iI5+MkEB5anFe55nl423VOTXAozHF7sLbFtUnVXK8RHNv6XUZlbI8hLW+y9FvoL0urhK4Eh4WX2NW+jsVzz58Uy6kJjpfk6yWWK0jTN6+rjXdekC8IzkDLIjj0aqzS+lo2P6iyDCB6sC7uE033piI4Vpv4wQ1xzlyN4Kzjn16rtg/oMoOVFyfo10nwLSSB9S0k3y3U04Xg2C6BxyoRKXPPnzkJjpN9mfelZ+dBuj7GKbtBcE6CI1su3q7L84j7Av5ZP+5SSHmnIDhcYCDxoSyaJYIj4sDSXa4y0cGILWtNbwf0XQgOx+5DJH1eTO1hnnP+zEVwWKMhmZLVHdXP8zs+D97sQXAdCI6suD6w/dnlRdjIh3USn7PNDnWMTXBYatlKe8KyvN0uERzGGSvEDOI53NvACvm6EBzN7Jbg1uA1vOS6Ntf8mYPg2NJzEGUp9THYdBn2ILiOBNdk50yxa0h4QyE1v7C0ma5HwYxNcBxXw7E1tYTlmOS53xLB5Y7XwfCAlW3s1JXg6A9jhoKcrfWqaer5k/Z3TB0cllJcQEqha8wjrO9DO3in9xkEZ8xUSwdHyAh6HRIH+6WWNILjsTCeUYKDIjGfHEZZWhExwCjaPWlMgttQB0r6KowrfAsCK3Hj18YWk1UYxgjKW2er9dHB4dfHV5jGTjmCwxqc862jT/gDcl9dVQxzz58Uz7EIjhcf374ovSzxIiDeeHPsQVb9QXAGyCnBYfnBj6lJvH0gM5w8awmyw1mVj56kCcV1ydmxnT9HcDVfs1r/uI7ei7CYNKEvxFm59vUuJrW1qqkRHEdMc9R0miCYmuNs7r6I9+SIHl4cpYD/UiQDK3NiWXMJFQOnreRC3tJyS5g/aZ/GIDhciThZhaPLcwn3HYxIfa3RharNS0FwBiwpwVnOpKw0CM/5nQNxluyWBY43HUHpnpQjuOupMCvKWqI8Rzs1flw4tOLXRaIfFgFj2i99au/oun4jCURtWchqBJcLsiY8B4V8l1US1l8e2sZXkZcQD1LuwyW1UC1IlrK5rTj1E8XRfvHlxmAJ8yft29AEV8OL9onm4JmpnR2I+qLPaTQW/kFwBiopweX0U0xyHm4sQNZxzUQDXFqCL1l6bDLNdvnsH06S1qBzSCF6IYsMcJ+A1Nhap0cQQSIcJAnx5qIB8CMjvrJ9QgYHAWxIIC8CoUsW1yfrOm9sTihpyLQNdymSgXyUJ2B/s10o+Zt7hMiIFknJyDrAkQ+ZNGF0aXQJVbfHHjUDjsol9wYOFWCFy/iz6rQ+DLSE+ZNCOCTBsZuxxrfdJttSdgolSzQvTF7YbG9RFbDzyb2gClPi/y4FwRlIpQSHDw8PdClBGF+SfF/CWWKsmFiql5TxrAAIgPem3JaO8nskzcmp6HvYGtdOPmk+zcak4hw3K7EdI9wKckUxXtJPle4DwwEGhDQ9Tj/wRfJSAlseIO6PyAkeBI6ypj+l7RB1ErvaWD6xztY+f5eOfc7am+svlkMiW9ppKfOn3achCc7zNa3KEJuXWUAQd7zKai4IzoA2neQWSH0GrF2GB/Y8klowersMDqcHr9pwq3yj62IVBnGMnVgxpivNXKjVEH1pH5nEveIGU0vp2LOKY/XhTdahokuZP9uN4Ojv/pI+oXHNvQbBOQjuhcpzS+8Md+TjzYSOKRdonquC1SBm9SF81dJYTfyR3uzo+ypZ2C4z4dKEJZatYG011rVtQuOaD6F43UJSgmP7y3HsXRKrjvYLYynzp30P22EFR39X/SxmEJyD4ErnVnWZ+OSFRFiFeS1waf280dD1ePzQcn1Dd3aYJI2H5Qx99HFjJEidFVzjR5e2gZGAbWzjirNKH9DfEPvZPp34ePq/xyCUEhw6PladXrz3KC9613Za0vxp+hUEt8oM2+Zl00mOzudACUp3LIu80Vl11PRybRggNk5KIBRq1UTUAfGiKG29iUBnfNXQ+ZW2xZz4i17MMoqkbUFWWMZwqSj587GKoq8efSN+hAdJakcWWfdNhAkGH86wsxLKa84hs1xTyM/9QIRpYnVLuZL+kbLoKu8tSY99X9r84f6GJLiu2/jM8Jg/cx5ibjw99cQKzkDJcvS1wIRoCPDekKCMbj5vh38cuhhkU0JsZM3K5BmsNA9tEvKFVbA5zggHXLZHCLoLDBOcbtI1UBwSYHJhrGDVSLA4Sv7vbQn3RFB7zeTf574os58Esm07TmO44UhwjpnCcsm/CCFfrNq66DP79mvIcnPOnyEJbkhMhq4rCM5A1EtwQw9G1BcITIVAENxUSC+wnSC4BQ5KdGlQBCyCo4G2xRjdI6qHx0tWcdUYtOOZynAHwt8UtVHbPcoyyOHkjsppx6YguB079DvmxnMEZwEAcYxlfBoK8C4f9QmCGwr1qCcQWCgCXQjO+4W0OW/V+uZFrj9BcHOOVLQdCEyAQBeCwwOAAwiWnHJfLbP6HAS35JGMvgUCAyDQheAup/asr6YN0I3BquA7Hl4XrCC4wWCPigKBZSKATx8HteYSQfF8h5bwNs4B3A4JH1V8FnExKunRcZQ/Yjvc0Fh9DCPDWMhGvYFAIDA7AkFwsw9BdCAQCATGQiAIbixko95AIBCYHYEguNmHIDoQCAQCYyEQBDcWslFvIBAIzI5AENzsQxAdCAQCgbEQCIIbC9moNxAIBGZHIAhu9iGIDgQCgcBYCATBjYVs1BsIBAKzIxAEN/sQRAcCgUBgLASC4MZCNuoNBAKB2REIgpt9CKIDgUAgMBYCQXBjIRv1BgKBwOwIBMHNPgTRgUAgEBgLgSC4sZCNegOBQGB2BILgZh+C6EAgEAiMhUAQ3FjIRr2BQCAwOwJBcLMPQXQgEAgExkIgCG4sZKPeQCAQmB2B/wKZnEhy9tn9xAAAAABJRU5ErkJggg=="/></switch></g></g></g><g data-cell-id="IkmhDn_4ef8kqVBRZHeY-24"><g><rect x="82" y="334" width="80" height="30" fill="none" stroke="none" pointer-events="all"/></g><g><g transform="translate(-0.5 -0.5)"><switch><foreignObject style="overflow: visible; text-align: left;" pointer-events="none" width="100%" height="100%" requiredFeatures="http://www.w3.org/TR/SVG11/feature#Extensibility"><div xmlns="http://www.w3.org/1999/xhtml" style="display: flex; align-items: unsafe center; justify-content: unsafe flex-start; width: 78px; height: 1px; padding-top: 349px; margin-left: 84px;"><div style="box-sizing: border-box; font-size: 0; text-align: left; color: #000000; "><div style="display: inline-block; font-size: 12px; font-family: &quot;Courier New&quot;; color: light-dark(#000000, #ffffff); line-height: 1.2; pointer-events: all; white-space: normal; word-wrap: normal; "><b>stacks[0]</b></div></div></div></foreignObject><image x="84" y="342.5" width="78" height="17" xlink:href="data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAATgAAABECAYAAAAV6ClkAAAP70lEQVR4Xu2dBZAltxGGz2FGh8EbrDAnFc6FmZkZHAaH6QIOOcxYcZjRAceJk3OYmXHtMDPj/1W9qUxpWzTzNPP2bXdV1+3NaCTNL71fUndLs88uF0fAEXAE1hSBfdb0vfy1HAFHwBHY5QTnncARcATWFgEnuLVtWn8xR8ARcILzPuAIOAJri4AT3No2rb+YI+AIOMF5H3AEHIG1RcAJbm2b1l/MEXAEnOC8DzgCjsDaIuAEt7ZN6y82EwKnU7lXkZ5Ryt9/l/5QeqT0MOlvZ6rXjizWCW49m/1aeq2HSM8mPaXxir/QtVOt56tveav76MoBiXf9h+79VPp+6UHSvwzE5Sx67mnS62aef77u75H+cmA5x9FzD5ReVXoa6bES+bxQ9w4cWM5aPLbKBHdSIXxF6SekP14LtKd5iZOrmF8VFLXKbV9Q/eIkT1bKBxWm3l/pIIVauY4eeLX0hIUPflvpriw9qjB9P9nd9Z/nFT7Hu/BOO1ZWtZPfRS3yol6rPF5/P3LHtlLdi99KyV9V8Miqtn1B1auS1BDc55Xzhaty37Xrkkr/scpnSM4s+nzSn1c++zmlv1DhM05whUBNnewPKjAcDZmZ/GbqimzD8s6rOn+5oN5OcFtBepMu3aQAuy7JKfTHV6WWGaAkmzcq0U1LEvbSvFJ/37rwGSe4QqCmTMbS1CKyC+j6l6asyDYu682q+w0z9XeC2wrQpXWpZja2R+kfncD5+7qHjez0iTQsbw+p6GsXVdpPF6Z3gisEaspkp1Vhls3tErr+ySkrss3LuqDqfw7p1SMj/k4muD8Kk0ct2ve/+pflIrbezYo2P4HS/kRq2d3eoet3kna20DPo79dJL2Xk/yNdO5P0XxVls5qhXfn3aIvncCqFM0knuApQp0rqBLdcpG+2+HGFue5kgmOWxmxtjNxTDz/HyOAVunZH6b+De8fW/z8iZQYWCmR16JjK6Nl3Sa8Z5OEENxLUFo87wS0XVSe4rV7UsQR3TDURy09r6Un/JezEkivo4uHGjVrbn5W3E5yBSs0ozlT41NINKVPqk0mxlf1sod/SvzXT7NjPeE6Cw/53ZinGY/QkUuKiNhdKwCZxU8uWYyhDnAMEhu4rZdnzOyk/FLxsLGOGBoiuCsFN1X/CtrG8qGMJ7mIq5FNGJ3iirj0s0zk+pPu7jTQsL4fGxpGdE5wBagnB4TbHkHrtTMNh12B6/k3pDaREcBOv8+7Mc9gRCMSk0/DjxrYByYSCnQQyTQl1+I70GdISTyIjMFHnuPovIz17Jn9uM9oStlKSfy47yr2XlKVFLobqvUrzGimDyu2lBHy+RPoeabgc6pdbQnAXX9QD3I8XqTTYvlP6YinkWyqt+0+uHi0I7uYq9LVGwQyKuRhE+tv7jGeJi/tA7mUS953gDHBSBHcupX+sNOeNy7VJruGevfhx5fKpuc/ygSj+/0Qe4r2JOr9fTaZBWlz8EM2QyHeMzpAT0ehjhZhB8opJjuCOrweZKeYItssfwsCgnZOp+k+uHi0IDgfFY4KCS3eHsPsA50Qod9CFl+deJnHfCc4AJ0ZwpbFUJe3xBCV6eCQhLnRmei3kcsr0w5GM+fF9bQmFEr1+GymeuFJhpsistpRQcvnisbteIlGO4IjDen2ukN59ZnIs5VOzxqn6T0m1WxAcM+lbBIWz1YvZWU74zVkDL6skJhRDxQnOQM4iOKbZRHSnYndqGuFlSozL3BLsMiwprSVpTRlWWkjsG5FMIJkY+dWWe1898KzCh1iufbYwbWmyzyghy/uY5AiOgWBvaWFKx0yFWUhsdjxl/ympdguCIw4t9IY+V9cwN5SI9Twe2XuXPBxJ4wRnAGMRHFNlSGlZcrAyYikXk3voBp1jmYK96hqJDPGC/Vqam0UxW8ml+brSnLug8mxux243NOo9VkRue1GO4C6rjI8oqH+XhL2QL0ikn7r/5KreguCY/TOA9oWthNhmS+TtShRuymd7HauBoeIEZyBnERzkRicNhSk49/ACQQ4sUfAy7ie9vvT+UosMSmJxMLazUwHPLDMAayTDqIsDIyV/1s3vSTG8/zOTlhM3sKOwrw8vJbskIAtI6CuLfDqvMO8FYWIvtAiK+3/KlMcITexUTFiiYGRmRos3jeU7XmtCC+4qxRFgyRiCu7MyxGmQEk6/wEZHm1OW5T3sPz9H/0nV3wku08DrfNsiuI/qhcOIa2YyzED+mgAD7xsEQJBjX3Cb4z4vlanDRJjN5ciwq3ssjgm8Pp54QZbgEK8lH9RFCOy7GYBiBDmU4Bh47pYpk0Eg5wUPs5i7/4T1cYIr/eWtYTqL4BjRGdlDwTOJUZ3TDIh54wcbxr1hfMbG1NnUOBZmtzQW+GhBOjXB9evA7JEZ6YaUWD9IG7c/sWgoMXDWdrFcJDqzW7y2obC8xS73NwuI4Bp1+YI0DGWBIDlWKiaxJWqqSNqa0JXcjNnKY+7+E9bJCa6gc61rEovgcAikwg76WPAD/aIUYz7Exn4+TgLhR0vwKvdKfrz9PKcmOAzmhD2MMfDmCC4W3MnyGNIqFcu+lTNu1xIcMzZOqxgaWDx3/3GC+z8CJeah0r63LdNZBIddjVnaUM8m++0YNbGD1YRPdABORXDMNomDW8Y5czmCs45/eovKvlFlryEI+q1SYgsRsL6t9AeJfGoI7kkLPMbsSJm7/0xBcNaZbLmBpl8vJgKhTTUVbVDSTdzJYKAUi4PjJApsO2OE8AXis6ygxlS+UxAcITB00mV5NFMEx44Dy3b5CF0fepw0GLFkzdntwLmG4IjD2iMdMjD123TO/jMFwTHI4FjrS85U0E9rDXjEihIzOlSc4AzkUjsZCH1gVNo9FHE9h3eSmLPNijxaExyeWkbQkm1ZpdVOERzOGWuLGcTzhtICRqSrITiKOVjK7ohSx0usanP1n7A+LWxwT1ch4S6Y0p0MsSPlOWiTbYBDxQmukuC65JwpxqF8xEuhubiwsBj23V2totVaE5wVg2RVD88xUvK+KYJjpkX4Sig4Htgz21pqCY760Gb84JhpjJWp+09Y3xYER3C31XYMZhBdSmJxh7X22LAMJzgDdWsGxz5J7DoIJ8OGnjRGIDyMfEXorFL2fHIYZWpGRHgFhvYSaUlwG6pAyl6Fc4VvQeAl7uLaWGLScXFG8DwHF4YyxAZHXN8tSwAZmSZGcHiDY7F1FEk8IO9Va2KYu/+EcLUguNhOmJLTRCwios7YLn8/oq2d4AzwQoIjnos4pk6YxUBmBHnmBLIjWJWPnoRSE+UdI7hcrFmuftzH7vU4IyH2Qmwqua93MZuzZjU5grO25lANCCYXOBt7L/Z78u1NBo7Uhv/UTgZm5uxljQkmBvZXxra8hc+tQv8J69SC4FJbDDnyKjYoxD5Qs1fPXL6kAyfSOMEZ4IQEZwWTMtNge07J6HJ0pbM8cDXbUGIEd2PlzYwyJzzP0U5dHBeucuK6EOphEXDumBtOY+WIHIja8i7nCI7P1vFDC4XlDAb5mlkS3l/y6mIVGYTwxh4WASa3VQuS5dnYUpz82cXRH/hibbAK/SesWwuCo4yHSi2nQCw0A1MFOFvHluf6Twzv/nUnOAOlkOBi9ik6OT/ul0otexK7ARiBiCULj02m2JrP/h1X6a0ZCYcUYheyyIDwCUiNpXV4BBEkwqgK8cZ2A7BJmv2V/RMyGKU3pHQ+jsdJeVyfqft40dij2JFpH+7UTgbS8Twb9jf7DwV/844QGbtFQjKyDnA8j9J12+jC3SVk3W97zAyHSlOhQdidmOHS/sw6rQ8DrUL/CSFsRXDMno+MtBemDj443XnP6X8MzpZJgFhS2mqs59oJzmiMkOCIXeMHnRIIg0+lHSXlLDFmTHzfMWWMZwbABvhSiS3peH6vlJN1Eew9LI1zJ59AeoyezAI5x80SlmNst4JcMYyn7FOp98D4jAMhlKfoAl8kTwnYQpC8HzsnmDmeeFEfME4Je1c7zyfe2dzn78K2j3l7Y2USDMzOlr6sSv/p16kVwVEGYTWpOEpCrRiYUvZpjl2y7LqZ5t5y2wnOQCzs5DEDaC3Y/fT8YM8vzW1G7z9DwOmDxxQaPNvZupiFQRytxbLDxLZaLaMu/SOTeFfCYHIStj2zOLbWlYp1qOiq9J/+O7QkOFYbDPZDg+Jx5FxEOjYkh/d1gisgOE4UvV1pDy9Ix9IWG1Nso3ksC2aDbP1aRqxaGIDJBvJDCuo+JgnLZTpcKHhiWQrmZmO1ZbM1rgvMLg0LCQmO5W9tHBannfQHjFXpP1MRHOWEjpXSthv624jl7wRXQHAEeBImsQyBRJiFlXrgwjLPqQvYekri0GL1xXZ2kDTcDxv75Nsy3puOywyui6ML88RJwDK2C8UZUyahHuz97J9OfCL9v8QhFBJc6jufVh336mLo+Vul/tPVueUMrisjdspMrG0xRXAe3DK/8+sEV0Bw2Hz2l2J0x7PIiM6sI2eX62cNsXHOGluhxgq7DogYJ7yjVN6mhNg0sPmllsUcWIhdzHKKhGVBVuwVJKQiFc/HLIq6ltgbiSM8QJo7ssh6b3aY4PDhDDtL+PGw9cf6BifpeR+IMBRmtzyXsj/yLLbKB0jDY99Xrf/wflMQHOWwUiEOLvedDaIS6NO5gOBI00YvO8EZ0KS2avWTQzRs8N6QYoxmhrKvlPg4bDHoppS9kZYXsbaxwvSUSXAlXsHuOCMCcFkeoQQj45jAI1W7URwS4LBNnBXMGgm4xMiPhwzlndjUzlFJLQQcIdt+4DSOG44E55gpPJf8i7Lli1G/xp7Zos61ec7Zf6YiuA4T+tBuKV5WFM88/YnfBYP/somtK9cJzuiVpQRX26E9vSOwKghMTXBzvbcTnBPcXH3Py50RAYvgqE7fY0xsJaaHp0qHfAZyytcjHIh4U8xG/fAoyyHn58FN2TJeliMwAwIxgrOqAnEQDL7KUvNRHye4VW5Jr5sjsAQEagiu9AtpS6jW4Cysb17EMnOCGwyzP+gIbA8EaggOJwAHEKyyxL5aZtXZCW6VW9Lr5ggsAYEagruSyjt8CWW2zIJz40pDsJzgWraE5+0IrAACxPRxyGRM2OTOd2jZ3sY5gNtBiFElZpEQo1QkBIHyR2yHF2pVRw8TaYWs5+sIOAKzI+AEN3sTeAUcAUegFQJOcK2Q9XwdAUdgdgSc4GZvAq+AI+AItELACa4Vsp6vI+AIzI6AE9zsTeAVcAQcgVYIOMG1QtbzdQQcgdkRcIKbvQm8Ao6AI9AKASe4Vsh6vo6AIzA7Ak5wszeBV8ARcARaIeAE1wpZz9cRcARmR8AJbvYm8Ao4Ao5AKwSc4Foh6/k6Ao7A7Ag4wc3eBF4BR8ARaIWAE1wrZD1fR8ARmB0BJ7jZm8Ar4Ag4Aq0QcIJrhazn6wg4ArMj4AQ3exN4BRwBR6AVAk5wrZD1fB0BR2B2BP4HiBhmctgbI6MAAAAASUVORK5CYII="/></switch></g></g></g><g data-cell-id="IkmhDn_4ef8kqVBRZHeY-25"><g><rect x="375" y="120" width="80" height="30" fill="none" stroke="none" pointer-events="all"/></g><g><g transform="translate(-0.5 -0.5)"><switch><foreignObject style="overflow: visible; text-align: left;" pointer-events="none" width="100%" height="100%" requiredFeatures="http://www.w3.org/TR/SVG11/feature#Extensibility"><div xmlns="http://www.w3.org/1999/xhtml" style="display: flex; align-items: unsafe center; justify-content: unsafe flex-start; width: 78px; height: 1px; padding-top: 135px; margin-left: 377px;"><div style="box-sizing: border-box; font-size: 0; text-align: left; color: #000000; "><div style="display: inline-block; font-size: 12px; font-family: &quot;Courier New&quot;; color: light-dark(#000000, #ffffff); line-height: 1.2; pointer-events: all; white-space: normal; word-wrap: normal; "><b>isPrime()</b></div></div></div></foreignObject><image x="377" y="128.5" width="78" height="17" xlink:href="data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAATgAAABECAYAAAAV6ClkAAAQRElEQVR4Xu2dBbAtRxGGX3B314tb4e6vcAjuHtyhcIc83CVBgvNwgmtwUoW7uwZ3d+f/UnfJMtWz07O759yzu91VXe++PaP/zPbMtMzusysoEAgEAoGZIrDPTPsV3QoEAoFAYFcIuJgEgUAgMFsEQsDNdmijY4FAIBACLuZAIBAIzBaBEHCzHdroWCAQCISAizkQCAQCs0UgBNxshzY6FggEAiHgYg4EAoHAbBEIATfboY2ObTACJ1fbLiX+sPinPdp5AuW5nPjz4m/3yL+YLDUC7kNC5ZIGMtfRszctBrF5dPQx6saDja48Rc/uO48ubmwv9qhl+7da9xD9/diK1t5CaV/aSv88/X0n8X8qylhM0hoBx0pxRgOZ/RLAFwPehDv6bLX9zkb79+rZrSfcr01vOpuBNxiNPL6e/d7R+CMrzTeM9/CeenaAI//ikixRwJ1Eo/wk8RXEp6kc8e8o/RfFXxN/Xcyu9puVZWxC8hBw6x+F46rKb4lPZlR9Pj3juFmiEyrBrzOJTqvnPywVsLTflyjgHq9BfsCIA/0ElcURw7MCj1jtoKJCwA2Cr1fmxynXA42cP9ezU4r/7Sz1A0p3aSPtK/XsZs4yFpNsiQLuZ5lVdMigM0nvKJ6KLjIE3JDRrs97KmX5USYbQo9F0ks3UMLXZBJfQM8/6y1oCelqBBy7lDMYoDxdzz4+IbCYHEySVdCFVeinVlHwyGWy0l/dKPNderZ35LqiuF27nioQ7mUAwcLIO/XnCpCOpLSfFCPMUnq9Hly/oqzZJ60RcHMB4xLqCOb5VRA6uvOLp3RcXQUOUeYRCJxaf+Z0Y7fRby/uARYuIu/L5Duvnn+hR5mzzLJEAcdAHke8W4w/0cuMkUWf8c7k+dH0/9OJzyy+acdseI5+syyUs5xA0akiAjmdL9bQc4n/WSzBTnCIHl/V+IkTyo16ljm7bJsu4I4qxLEObW3zMfUv2/qfiH8sZsc0lCz/oZLrC46ajxLf3qj8D3qG2X9Mv6SjqLxzi9kdUu6XxF8W1xxthuLUNz9tP7sYS+GJxZ8Rc4z/S1Igiwd95MiGnhS3pK8a6WrawXHu9OJzire2y6JsmF3O32sK65H26MrzCzEW1JRurAcH9yizyXJR/fGxTH50frwji6ecgON8j2/NWcTHKqD0N/1+GfFfR0KTSXkt8UPFlp6hXQ2r4CvEWKD2FeO+8TRxzRa9j4CjDWD3crG1m+MlPSzBA0sZTrT06UQdWLEqI7whcEUJba3UCNKHizEYdL2o1Hs/McKxq96mSfjBIYQ8hMsNfUL3yN8p0XYcWVMHcdp+c/FbxJcV46x6ViM/ixltZ4z/5WmQ0rAI3kN8bfHFCnnYqb9a/Hax14rpbMbhya4nfp2Rgf7jLjL0ncG15DxG+YwJTtuLJ0vAsWtCZ2D56+QAO55+YNCGEi/yo8UlwVaqh51Czl8ozdtXwFHOlvi7RmOs6A4mOhO+RBxb/iR+lhihXSKEPLjldrM4ltIeL1FWejzP5c1ZY711fUUJ2V2VCAMXgrJE4HWg2HJI78rLgngf8XtLFVT+jgC/hpEHq6nlMlJZ/OGWe1QiKTEnzlZb2BzTWwKOCc75vobGEHC3VIUvqam0I+2V9du7nWUNEXDo5djBpoTFDOtyQ+xuOKp46BlKdHdPwlYaBAXK5VSfwyLFcayGvAKOndI6j8hYfdlpWYQa4yCxZ0HowgJB+jDxGLs5Ngq5nTVHdhzFhxI65N9kCuFo/v2hFUw9vyXgeFE+V9mxoQJubMsm8XocHz00RMDl9CBp/V26GE8bPWksH6g+9XoFHGFDh4lro0E8fbHSsEM9k/EDVkp0UWO1A9UIsbpD6SIqwHKfGnt3ldsl3lD1v3ZoJ6aeP6eDwwSNKdpLQwUcwcMIhbGoZCRo19NXwB1bhRwqRv+UErqzDyYPCW4f48XJYcSxzDouP0jPa4K5vQKOdtxNzI5zXYQOsb1jQT+MY6ulvxvSppoTQK4edvH4v6XEsf6uQxqX5EXfRuhhSowLushFU07AcfS6mpiXhhe5IXZ3lh5pqIDLRRc8X/W9ansS/1b/0l6OXRg/UIbjR2TRTfQQ5bGH+gg4XEWeKeZFSAld5EnF1tGVXdZuMS/mlvi2ngYqDWUSXgYWWMhwbWnrKd+h/zNeOWLcLr9dbzPmHDERfinVCDjyYlG+rpgX1yIMBdx28X4xOqOc1z59ZExRLYALxqKUMEgQqtQQRpZHZOrl8QvF+JkRP4xvIhZd2ksfceXJ6XrZLXKM/EdH2aWfcrpPjFKM41iUO/2gV2TcF021biJXElp4u6c0RMDldDnoWyxv+3bdWAhRiKeWpOauLc/gWgLu/srYPuJy1OMIhF6DIP1bdRTMqo3CukS8QLhBlAghzyrddh5mAbqdmN0ju2082FO3i1K5LFx/NBLVCjiKyOn6EFoIEYLMoa6QJY50eOhDCCHrnjQE6Ru303TpFxFQGFa6rOlY69lV4+5j0R30EOz7Us7CyeLc4NG37Ha+Y+g/ubGvfb/HaM9GlVELwCoEHID8QGzpUDjmMaGbGzyI50sFEq4ArPqNrxF6B1ZJrwPlmP5q7FYQXDnFb3vwSwIO4cCx/c0rmjHrEHCprxc7KGtXxJGtvQNEv2eNX1vAsdt7kYENY4Al+pdO3O6idFisU0LYInT7Uu5UAu5jG2fWWVdfPHYk36YIOPycuqID2uCgUMbJFf6oGJ8tVmMEHZMai2KNFWwsAYdA4gjlDXbuEnDsPNiBjOHInJtY6xBw3HrBlVIN5QQcPmttQe4RcLkjIOOP4t1LvAO522WwhHoXynZ9zMec317tO+fpR263uPgrlGrBXtUO7oIaxSFB6jhsotupcfBtJs4YAo56CY/B0dhLOQFHqA26RXzhVklTF3AscB4fuiEYUr5HjZDWQSig5ReKfylCZ2ziBHNFo9C+7R+7fTtW3qYIOADIOS3WgINSmSNHTQjOEAHHJEZf9wJx7UqfE3Acr9iFrJqmLuDQSVohUGPixq0zViRCqY4ctusWcGPr+0r93rjfN0nAAc41xVjPaj3R28BiUURX4w2D6SPgEEBvFRMO43XgTQc/BNwRiPQ5ovYZt9oXsG/IU+6ITf2175ynzZ9WIssivHhn31qwV3VEbQ8i+gusoLhgoNOyPnRTGnTcH7jFwUPWi4KQTVduLFW4qhAC9jtPwYU0IeCGCbicYWqEoflfEcTBPrlngbkdJl4D3sXXW3XOyMBRedWqDm8bdyTdpgi4C6n3eF7jqIpgae+KEHi4gxDAjv8Z3uzE2V1F3HVE4f56BFKJ+vjBlcr0/B4CbpiAy33ljd1126XGMxa5NDjQWh+J8ZSZ0xFuKfP3PAU40+QMN2Svfb+dVU4nWS0Aq9jBYcFq77ZwDSESoEQcA/ADw8Rvbc9Tp9BceSHg/h+ZMf3gVmlFxcEXR9+UuKyBeNKdplwIFY7yfYWm1SfmPkfUlMYOCdtpPHvVvwkCjqDjNNTm3npGqIlHcZ+L+cMb3vKTSoEKATdNAcfi9onMrEdFgVW9Vk9HhAn30qGGwJ9uCGF8sqI2UH8wv8cifAiJqkkJJ2WclRdNloDjGIj1pR2i1YBEWIh1tzxuDZZZnInCVr3rRovcJGQFQsmL0cASdFwqyVU0rNZWLGJXPCHHVy5XJKTKspLt1fP05gocVPFApz99iKM1uKIXgfjbihHlWiD6bhG6G/z+mvviSu0gIgBXAa6PSol2EMaUEregWFe6UzfuMOkNFeykCQOzIlywaLPINGFrueMUfebFbzzyc0p6xppIkcZRtitmmvbw4vOv5VzM3Geu46LEIonetx1XvFf/Z17XCskGT8pL45H5bewQqtw3RmounDCmwTwepQKOsBVuUxibEERvyxTqmUC88Hx/FN0cwomQHyvIvV0FV8lYxoA08qG2rzikYvWroVLMZE1ZpPV8iQmL9CqiIB6pcvffbjAfOEGAldw12LEgwLr0RRRJuZTfZYUkHcfTPWLPzTcsvAgVFgX+Rtgzf9CBltp9caXJ3ZpbGjN2gzkFP7tEjCRDiToIabP6wYK6SkfxoW1fS/62gOOmhl+tqFYmCZPFIo+Aq21W1zciiV21guRr6mjHTZby9bmTrVQmLyovqRVLSl7GFafjsW/ZaNqFkCAcjavTPc62TXvZBZYC2Lk7D+NQST3B7pvIlVzIVglDz+9DrKiUn9thshNFVziU+DqadS3YqvzthrZ37fnbAo6dDaFPq6Jc2EvOxN23HRyv8OrOBSCP4V7ANUFW/KLVZq4K914BXtNndrC56I/STqmmHivt7u26cwLWysNuCwtnScBxtGNBLAm49pVUuSuDhvZzaCQA17JbHzVCv8c9dqU+ltqfsyTvUcauW1ZK5c7m97aA41jAUXCIk20OmL36gZXWIq6OISh7DEJ/xBGnK9h9jOPilurwmvpXsZvi6IGrTNcLQnSF9zqmGux5OXEgZTd2sBj3nhIxrzgSMse6BFzz4rOr7+qbJSC45QXrZOnYWWorv7PjZJd1gCdxR5pcRANZum4o9lRLxAs7aItydwN6yp1VmlQHh2sFLhuAN9ZE4R4wDBP4uFmEjxsfuOF+LnRsKPdx7s3d1WWVcaAePlGc+3p4Ow9HIHQ9+/XoIzsQLGNc0FlD7I73iIcejRt9Eha6jxQagBCiTtwSxhpLDCxcMXTodt0YStCtsZuy6kjb26Vb4/YOyua7CF3B6u10KQRc28U1UrgeoRqoIYQm0SnvEWOY8PhQesrHG4Adf0rsUjHa9VXRsDNkh5gSbcdHNEgI1LqJrBM0VqHdYrbypxAjCLGcIsSwZiIwDxOja+obLrXO/kRd60MAQcoijR8eO0cWNfSG7ApRUcDoqWCMD/BYAi3t5db2XLV6377+qQadnO8bZbCTzX0UuqaOWaTdZAE3C4CjE4GAEHiu2PJJ63tzcO72EK+T/GIGJQTcYoY6OrqDCHAa4UPWFnGdOwLQS7loIvJ7o3e8dU0+XQi4yQ9hdGAiCOR0cbmvheW6dYh+IJwupdC9GaCEgJvI2xHNnDwC6ADRG1vGGO8dgBhRcjfZnEO/1Vy4OnlAPR0IAedBKdIEAuMgkHNKxuLrMZThS4phJLUQE4FkXTwwTqsnXEoIuAkPXjR9kggcpFajd2uo9jupfLGtfUcdbi37iksO1JMEa2ijQ8ANRTDyBwL1CBDgj0EAf0LvR4rateB/iFDDJxB/yL6+dPUtn1iOEHATG7BobiAQCPgRCAHnxypSBgKBwMQQCAE3sQGL5gYCgYAfgRBwfqwiZSAQCEwMgRBwExuwaG4gEAj4EQgB58cqUgYCgcDEEAgBN7EBi+YGAoGAH4EQcH6sImUgEAhMDIEQcBMbsGhuIBAI+BEIAefHKlIGAoHAxBAIATexAYvmBgKBgB+BEHB+rCJlIBAITAyBEHATG7BobiAQCPgRCAHnxypSBgKBwMQQCAE3sQGL5gYCgYAfgRBwfqwiZSAQCEwMgRBwExuwaG4gEAj4EQgB58cqUgYCgcDEEAgBN7EBi+YGAoGAH4H/AombG3LoKznIAAAAAElFTkSuQmCC"/></switch></g></g></g><g data-cell-id="IkmhDn_4ef8kqVBRZHeY-27"><g><rect x="375" y="254" width="80" height="30" fill="none" stroke="none" pointer-events="all"/></g><g><g transform="translate(-0.5 -0.5)"><switch><foreignObject style="overflow: visible; text-align: left;" pointer-events="none" width="100%" height="100%" requiredFeatures="http://www.w3.org/TR/SVG11/feature#Extensibility"><div xmlns="http://www.w3.org/1999/xhtml" style="display: flex; align-items: unsafe center; justify-content: unsafe flex-start; width: 78px; height: 1px; padding-top: 269px; margin-left: 377px;"><div style="box-sizing: border-box; font-size: 0; text-align: left; color: #000000; "><div style="display: inline-block; font-size: 12px; font-family: &quot;Courier New&quot;; color: light-dark(#000000, #ffffff); line-height: 1.2; pointer-events: all; white-space: normal; word-wrap: normal; "><b>genPrimes()</b></div></div></div></foreignObject><image x="377" y="262.5" width="78" height="17" xlink:href="data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAATgAAABECAYAAAAV6ClkAAAU7klEQVR4Xu2dBZRuNxGAX3G34rrF3R0KD3d37Ra34m59WIHixb2F4k5x/VuguBa3vuLu7vOVzWtIZ5LJvfffd3eZOWfO7n9vMkkmyWQyM8ndZUtAcCA4EBzYpBzYZZO2K5oVHAgOBAe2hICLQRAcCA5sWg6EgNu0XRsNCw4EB0LAxRgIDgQHNi0HQsBt2q6NhgUHggMh4GIMBAeCA5uWAyHgNm3XRsOCA8GBEHAxBoIDwYFNy4EQcJu2a6NhwYGdzoHzSg3OLvgBwT8NqM0lJc/JBBeCfxuQP+LghjAt8gziwEcl1+WUnDeSZ28dRDEyzZUDx5WKvUXwWmsV/L38vang+5wVPr6kY7xcNMt/efn/S878O5KFBtfLsUg/lAPfkYxnVTLvIc9eMZRo5JslB54htbpvUbOF/L6Ss7a3lXSvLNL+QH5fQPA3ThpHJgsB18Ot4WlPKVmfInhVwTN2kvmupD9M8OuC3xBkZftWJ405JA8BN4deWH4dLiZFfMYoxitvniz5H6zQeLo8e0BPE7wF9tCMtEfnwJPk0UMmZAwDYB/B301Ic9mkQsAtm8M7nz7y5JOCl1CqgkZ2e2cV0fQ+ZKQ9vzz/ipNOaHBeRo1M91PJf+qRNMrsP5MHdxXcKParEHATD4AZkru+1OltRr2wvx7qrPOx1oTYOZX02PZu7KQTAs7LqJHpXi/5bzaShpWd1dLaEiypyEFk0Th3U3I+U56x6gdsbA4cQ6r/ecELjhVKa/mvK38PMlhyYXn+RQ+7Yovq4dL4NJcVEh8bT0algI3uIoIbabu6JFYE2Z3IAbzhbzbKP488x4bcC4dIht2VTG+QZzf3EAsB5+HSNGlOJGS2ChLXU3qIKOHVgu8pijqO/D6zILFEt65U4wXy7u7TVDOoBAcGceCzkiuFdeQEni8/7jGI4pYtl5J8nzDy4lH9couuV8CdXAihhZxe8FSC/xb8dobEuSwDUHvPIkjA4IrgnwWxZ4HExAwK/nNW9ISSDhsAiBd0u+DXBI8Q/KeThpUM/pXQCpc4jWR4nOCdlbzw/6SCGt2hVUUgoxkykH4piCf3m4L/GEpwHfOdQMpiqwQyxj8uiGE67zfsPOdYS0P/fk8QOyGaxr9G1JUYMBYkxuxpBX8tiL2UMAfGz5R9lKrJWGWeYAJgQaSdPxFknhy+Vv6IJjWzMk4+Z6SiPt9vUrATvEtepXi6PBWmjfu16LYEHIQfJqipiTltNBIm39UF72IUSiPfLfhCwdokIcjv3oI3FLx0owFoPa8VfKegZ1AiqGEKdBEYJdxRHiBUcUdrQakpPeXtJcjgGQJDBBzl0F8HCmraHIN7e1EZBt59BM8lyKTX4Ify8NprL5j00CaPthqzHebdOxqNJi9xUAgQq9xE4q/yzxUE/+JkJF40+pA2nbjIQ7T8QwWxeZZOHYQzY4q/q4LEapX5IfdpwfsLEo7jhdNJwocLXlkQwWYBgu51gsT9jbWbwlecTNS1FXr0EUnDto7+YFwzfp8niBCcAvYTIsyHEnA4wPMxYDkuWNSZwyg9JlgCDk3tVYJbx9TMyFuLXL+O5IFZWkBorSpoc8THcCSkBs+SlwjPqQBh/hLB3lV5qICj3iuCmmAt+cpCsV2w5b1loJxEkEWMtmieq5JfDFwEoXb85tjyHG2lVW5Ok/I9uwAWH7QgTx2tPkZIe8YXi3tpMihpYkJg+4Ww7AV4SOgQsY09AH/vJLitk8dlGdiEOR0wFuDBLwS1xQJHAcJ0DNTGE3Y4BLcJmoBj9UXT6hmgPQ2gwTQ8hzPJD/bqCLgxgKfuUYKaNndMeb6M7dW+Qrc3xm2MgGNAofWUgFaD2p6g5rIv8zJBm+p+kek58ltbtREMbCt6wCvg0D56NKueOpRpEbhoi2xdNcBk83LBMcIWuhxhepOzomjYKB4uA7uDJkLpD450tSSWnQxt9QyCU8y5bUJnb6USL5JnaLEmlAJuRVKiDWnSeCQfdmR/qfzHCpQAJmBIbKnZ3vIfKQmfYCTGDlPbQnjLKNNdaI1v3vxjBJw1oG4nhbN9TYD9yeVK91ZaSceiUS4m8OILnTS9Ag7b1nqe4mAbd0+lLeeTZ00DdwcPCGxdONKzeD/Wkc6bBE12qJkllcHO6alKgc+WZ1PtlqzTEWjjZ6s1NhdwqILYBbQ4Fi/DPOnQEImXAbAj8P/YVbAs9xryQDvYuyrPWXWnBgan95wdZQ8VcBiTPyyoRYpjx8LWksMH5Qd2oWUA21AMyFpbesv1CjjaQSgC2/H1AAznTK4cdpUfnxL0bHO9dURbJJQCe6gFOC9+Ljil8sGCgWNlDLxdMl9PIdDcPnYUimyyHIrYP01bYi7g8M6h8lnwQHmB3QCpCdDBNAyDfA3oPI4qUYmDC4Y+Wn4/ppIZbQ+BhAePOC9UdAyLbIMIi9AM4ZCjjucW/LtCG2/TTQSf1qg327b3C2J0xouI95ijJpwp1YCto1aelnaIgGMwsi1EeJcAj6lfuXWFX1cTxBPKBNkq6BV4aPIYzjkyQ57XCOaT60HyW1u5qRu8wHHBGEEoJ0C7g/cl9Ag48tK3ODvuptDiEfYlzjJir3uxUSbpvip4B0E8p4Ta3FKhhy0zOUCwATImLB6yLcOJhuOLMUg++L4iyIS/l6Bl+nmZvMPJZYGludP32JaxRRHZgF2UfmdnBL8pkzGgAaYhFqqhAD+siALmmbW9H1Ie9lBt7N9AniNkVUgCjq3GjwQ15rOKYVC2jKF4ZuhQS9gs5J2m3VAWbmwNGBys0rXrUWAuExDvrQY4ABjcGqA5/tF4x4DBG2zF37AV1G6/YNJ5DcaagGNC5ltMJgbbdgYKh/RXjfry2HsIGdOAxZOcPLY1bKL54KW/MKizYuKlRJP0eK5zuvD1vUo7egUcJKzAUvrtKoLJAcIJEupbAmMMTfhXay84/qPZwlhQEVzAxQVZ8DTAbs0tGImeloZ27r9Wd+197ZwlbdKcaLWFJpVhbfFy4W00q/qYqAStvfBLi1IYUkbKY23P2QazHVYhCTir45js2BtacSysFqyWmvq8kOeagNtTnrNqlQBzKBPPjAeYdM9VEjIQuTBPA0vAUfYVBWtR12hKacDntHs8Rr1e1xofqAvClXirFrQEHBoNmob7MHOrwOL9egg4FoV8q8fWnZ1DCaXdFI9iucUnTy7gtslvzdiN4wxNwhMfycKMNqw5CtjpEJalAQvdduMdAhyTDHOQRZYdRwlocrkgIIwHzW8MWDbRqTy0ed1W5YdmXkLBYSeoQhJwaA/cUFECKxJeGw/cQhKhyZWwkAeagLNsKUwyU+VU6NMGy4vJ3l3z4lgCju2TddwkL1oTUD02h6kEHAsQAjnZNFv9VBNw9B3vLc22Rdvzfj0EHNuzXNBYAo6FKl9EPQLOclIRB1qzn5W8oWxtO4p2e80KIzHTeGxwjAtOFjCX+Ittnf8JBic2EiHYUlo8/Uk8KUHUJUwR/1bSxBymyYXqKZ4k4JDsSPgSeuxKDCzNBrWQ55qAW5ZHM28DHlNWtRIsAYfdiK1GC+Yg4Ni+s6j0nPGzBBwLBLbFqQSvxb+NLODYpYyxV7XGFO9TTKKVFo8udtghAG28wtiWLdNQL11MJ9gkSygjJXrpaumtECGC/W9jFZAEHCpuedsFtozLdNYM71Lp4VvIM03AeVejzir8T3La9EaFwEYWcAxUNG6CcntjjDQB15pUY/hf5t3IAm49wm7gF0H2P64wne2t5gzp6ScEJcJuLGwVAthiS2jGpw0o2Lqw4gChtWrRSwJO2y5ij0C97wHtwO1CCGgCbtnaAvXG86t5SzeigGOLcdBaewgXGAIh4I7iWu8WFSca43vZgLcURcECHIIIOOx1Y2JHsSWOjamzhE7XnW1OhnIIQDsiWBWmScDhMdNc7logp1UfaP1WsLQRWAIOG8CYDvLwxfIwzVHAsXUotU3O2XEHPZ4qeDsWQsANF3A1I//YfsnzY9fy3I+H+YhJT8hK6wysVb+eSyg1GpwH1kwky3AyEKKFtlbC4+UBHlYVkoCz4tFwTVtXB5cELWPuQhJqGhxHbrQD7WgqU91thl1JcxrMUcDtIXXVwk+mnDwh4IYLOEIqtLO3ULRCinr7DucI40ALvsXGTfwnwuxQQbT5/IIC3iOEdxPEu0n4FsHD2k0cqV5Ddml5m7iFRdtNYKskxm5K4BKFJyoEq97gJOBgGtHnJVBRYnNa2gNaG8dztOjuhTzXBBwBvpp7tyqRJ+JYCLijGBk2uP/ywuNFtRZl6+TMRMP1SDJloOs2eVYLkk9lM9ZxnhGSpXlgx8TC1c53c1XUVM4M2sLV/ITilFCNXkgCjqBS67oaXL6rgtbnunA94zXRItSpzEJQE3A4IyxbA7FAhK302unoTI4PsaXTYtXyTtfCIXamFzU0OGX0Vh5Zgb7LDBPhaiLNpssiwURr3T6iNecU8hDHAoHHlobIey0MhXnF/PKAdWa0J0BdK8c6YcA1SciOKQBBSpynJqBX5PkRViFJwPG+dmwKYbEqiEs4ee4YSLiJiYyv2dLoAE3AUWbtzCIxQbjE+auFn1B3VHGitAnoZQXOPbj7y2+O4eRC8njyG2MxLn8tup0VkYBJDnRrqjdlch88pztKYOCDlgeMqG+OTGHc1jy71Le8WoZ2c/xmSOBtqit9wwIGsAIS21hC6UHP32MuwKbijY9L26P8iFaih1Fau7WEfkJIlMBCRdtLTYCFDGGjnWJhPBAXmPrdMp1wfAnzSzqNYWlwaGeMU7aP9CGTyYpFIyYLTck67UA+xgCxaATXU7e066H9hOtgDy+h5uBgzGCDYgelKQQs+PQvTgWt3mOPa3GaSLvcAvMQ3v4pAJ5pp5qaW+FcwHGMhIltnZVLFU2dV4aDWA1ZyAtLwHlunqDjaRxHyfh/V0FWNFaeVtAjYS7JPsKEw3bhvUwgz0vbsEcSc9PiD84CJl8OGI4RnK36WjzsDZwkWp5JudUi2PkcvrMit+yxCBxuc5kaCPJMHjTPJxhZkIkRXAhaAo46ko6AW2hbAi6lw36J3Ysz0K0QCyYeCxN/OR/M3GKsty6VgM9s7UpNzjqHWvKZeUIQL/kZp9jkiAW1AK2ROnlOYFg0CDRfKC+hzWLXuwvTysFZuK/yonV+92hf1bIikys8ar6i8ZaAI/OegtqRrSZhR4Lci2qp6BYZBjN3qiUgYrt1w3BKWx4XstR4RxN2JEFLtTSDko7lUu8pr0yL9k4cmwVstbQjQmPKTHlTTKa1VdPKSPWtCTjypSN9NQFHunSzCEoB43V1ioYpNDTPJn3v8az2VoljjprG2EPHsmdDA+F3SA8xJS2LNYqXZt/Hs8opEhNyDS4lwpambaGG1nMhGWsCDrrEq1m3dAwtl3z5SQZifkx3slII3lzOxCboCUzONQ7yTxESw0kT7cytxp/y3OEYHuZ5tfGS3i9jcczL5tgdwkpzhlnto74tAUdetvAIEe0sak4bEwcaGSEaHG2b+tomNMoVwfIabuvM55h+xW7OhRRpiz6GFkHn2tGzA+U5l1OMAeuSAWjyAaeqA9QasHQ2GkxrO+ap+EIStQQcdLDnEdIxdBuX1wVVH2GWHya29vFWG8qLM7GvlVtPLS9lY+PLbUo1+6aHh6RZETSNqQWRZRwram0HMATzvYMp70lLzdpf/kHT77kOneOH3DTREnBoAGgCLQ2unKzMHcaDdWWUt19TOoQbjibNUdHT7la5aW5g3x6zNc3LsY5RkaYMqG7Vr3zPNyy0iwlcx8FqKzJfVeJIxyMEW0KHvT/2FwbTXkUNF/LbI+DIhq0CWwfG1l7hygBBKLM1wTGheX1RyblHrGYLSXTY0uarA9ujbYJEkVv8YBuDYCzPsxIvhJGXAdziZdnBaJJ4lHtj5HAmsEX32hzLctNv+HGwIJO5dRaTLQk2MjTf3nZq5TMZsfvhmDh8LQHbZEKJLBtwqi958Dxa3npoL9ZoE3eGc0L7EAzp2GYRb4VdrYQVecCY4n0vsCBgm2XccuSpdp8gjgl2OlxdxraaLSt2UW+wPO1gDBL573UYeduDHCHgV5tX+8hzZMgQII6P8a+BK0i5JuASUVYPNDqEF5Oc62MwHGLMpIP4y8DgGVsohEgOC/nhFXApH9oAk2R3QZwJCAicC3hw2e6BTDYQ5wNohbEU1YmfwYGlcIB4MjyjaIJ4LhmvIIKFix/TuEXo4mlnzFphId4KMn8pk/nJvGR+4qQgwgFtH0M/yP9csT62vFq9WPg5J6vBUE+tFfvmPinhEXBeZpOOlQ6hlEOvB7CnvEgbHAgOzIMDCFVCejQtzrWdLJpRMxmgMC08zZ5SwKFpaVcT7SfPUeEDggPBgc3NAa4twlapAaaSw5zNRy4R0qVFLSDY3DvCqQQc8TY4CLRry/msV+1bD842R7LgQHBg5hxAi+NLblrsHeEopfnKak4t7s9le0uEWwIOdzhnUdnfYxfLgbx467CVaZdlprTYz5YVHzXz/o7qBQf+7zhgBf5ii8SJ6AErYPwAybzqIeARcLh38Qp6vTRaudbHgXvqGGmDA8GBjcUBPP5l/FsKlPa0hF0fx95yQEBi3zM/EagRrmlw1vEITwVJQ+gIx52W6bnx1iXSBQeCA+vHAe1Y5K2keO2bLVqtuMCDCI08VGzQjS01AWd9FMbDJuJ0+AxbK27KQyvSBAeCAxuPA4SXEbxP4DfhHj0f5aG1nC7hRBCnFbgheJCZqybgrK9ktVjNNzq5YaD8CHErX7wPDgQHggOTcqAm4HAwcDMGe+laVDpaGuokZwQ5k1a7h23Sygex4EBwIDhQ40DLi5ry4v7lVH8JHNTt/bJT9EhwIDgQHFgXDngF3LpUJgoJDgQHggNTciAE3JTcDFrBgeDArDgQAm5W3RGVCQ4EB6bkQAi4KbkZtIIDwYFZcSAE3Ky6IyoTHAgOTMmBEHBTcjNoBQeCA7PiQAi4WXVHVCY4EByYkgMh4KbkZtAKDgQHZsWBEHCz6o6oTHAgODAlB0LATcnNoBUcCA7MigMh4GbVHVGZ4EBwYEoOhICbkptBKzgQHJgVB0LAzao7ojLBgeDAlBwIATclN4NWcCA4MCsOhICbVXdEZYIDwYEpORACbkpuBq3gQHBgVhz4D38kE4GiangBAAAAAElFTkSuQmCC"/></switch></g></g></g><g data-cell-id="IkmhDn_4ef8kqVBRZHeY-28"><g><rect x="375" y="382" width="80" height="30" fill="none" stroke="none" pointer-events="all"/></g><g><g transform="translate(-0.5 -0.5)"><switch><foreignObject style="overflow: visible; text-align: left;" pointer-events="none" width="100%" height="100%" requiredFeatures="http://www.w3.org/TR/SVG11/feature#Extensibility"><div xmlns="http://www.w3.org/1999/xhtml" style="display: flex; align-items: unsafe center; justify-content: unsafe flex-start; width: 78px; height: 1px; padding-top: 397px; margin-left: 377px;"><div style="box-sizing: border-box; font-size: 0; text-align: left; color: #000000; "><div style="display: inline-block; font-size: 12px; font-family: &quot;Courier New&quot;; color: light-dark(#000000, #ffffff); line-height: 1.2; pointer-events: all; white-space: normal; word-wrap: normal; "><b>handleClick()</b></div></div></div></foreignObject><image x="377" y="390.5" width="78" height="17" xlink:href="data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAATgAAABECAYAAAAV6ClkAAASaElEQVR4Xu2dBbQlRxGGN8EtuNsLbsFdN7g7BIIt7hYgOFkkuEvwwwa34K4PdwjusAHCBnfX/9tzO2e2t9rmzuybO6fqnDqbzPRtqe7+p7qk316bnFwCLgGXwEwlsNdMx+XDcgm4BFwCmxzgfBG4BFwCs5WAA9xsp9YH5hJwCTjA+RpwCbgEZisBB7jZTq0PzCXgEnCA8zXgEnAJzFYCDnCznVofmEvAJeAA52vAJeASmK0EHOBmO7U+MJeASyAA3EMligPF+4pPZohlm57d0cW1xyWwn1o8VHwx8VmM1v+kZxcX/yDTs3Pp3RPFl0vUEf90fz1Y3+MjXb0GT6ouP158XfEZE/umO6pHLeZy6JFeRxW+x6j0y3p2iaEbG7G+g1X3bcQpDDpc77a0tg/AXUn88cIP36n3N2yt3MsvLYHPq4ZLFWq5qN5/NVPmfXp3rYaeMM/M9xxoTYPg48C/bJxTi48Rbxf/RPxD8Td6DpQN+ZSG3z5DZR/cUL626AEq+Hqj8C/17PS1lWxwuSuo/U8W+vBuvb9+az8BuBeK71H4oQNcq2SXL39uVfG9impyAHca/f5XFXV0i6w6wB1XgwHQ7ym+XsXYv6AyzxS/X/w08S3FR4qfLn5H5vff1LsLVNQfijjApYV12GK+cuLsDXD3Vq3Pd4BrWKp7puiJ1MwvxJbJoNuDHMAdZwGS52jo8ioDHMfxI8QXbhhvruj59PK7iQIv0fO7NrTjAJcWFh8jQG4UgDv5YhOcLlO7a3ANK3nAog9SXWgSOSodUW+vH2O/qKVVBbgba4CvFJc+CLVyoBx26dclfoB99FMN7TnApSW/j159X5zDoN4aHM2eWHxZMcbSg8QYrrvkANeyLYYte3ZVd2nx+cWPNaouARw/YeFcRYxWuPeijuPpX7SQmFYR4LZoEK8YVuw7a7uvOHe6QZ5XFZ9KjLYcCNtcvFnHAjhsjNgDYzpaD8aw+Y0g5p1VIkscYSkMWgrgup22VG8HuLGmtb7ec6qo5S2tATirlePr4T+MF6sGcBwjv10hRryKvxHzobA80lYV99PD51XUHRfBaYfzrktjAVyP7k3+J5ZfwAFu8tO2XAcd4HaX3wn16HPilM0NJ83jxG8X/7nz81Pqvy8k3ipGA0uRA9xya7bvrzcU4Fgca2IM16iTfxHjkka7SBlk+wyUxYsnEVX/tGJc/GgcuPd/Jv6pmDiwsegkqvg8C8YbuV2MpnCU+D8DNor9AZMALn3a+asYewTyJKQh0BwAjjGiQZ13MSjWDYxH8vc9ZJozTnMSeeBCnqmqiSIg9goDt2W7c4BLTwpmLY7H7E/W7QnEvxbvWKxb9unfeswpP9njAId6+GzxA8Q51/uPFosFu4V1/MmNl41+dTExMZcXYxMs0WdVALsULv7/lQrrPeDMoqduK0boznqOjYqwAfqRIuSBfebHFW1aRdhYNxLfS3yNTB0A+IvEyB4bxaodURnnzcV4G5F5zgHwQb1/s/jVYkC+hoj/s7S3bXreEph+A5W3QkKmBnB89O8jRus8c4WA2IcvrShXW4QQHObzToV1G+pjHnDSnFV8MzFRAfTpS4UGawCOD9MtFnXTr5j+rQc7rFStVve31VeOBthyajW6W6vsa2ulbJTDvnIrMZpPjp6jlyzaoehuquhl4hpwDW0SO7VNXArgjfv4ET2wjlNTtcFdUP19bqLPOfmj0fHRAtj/mylIlP4XE2vhinreoj2wQTDKx46B2+kZgNtKY9ngALcWm+CTVP4RrZ1PlMemyFrnVLMssTa+lamkBHBojuz5Io0FcDTMQmURcpzMEX34g3hZ9z6gireRuizCywWqD01PVYWkutUQ2u+7ago2lJkawKFpPkGMN34ZQksGYH6XqOTJCbmjGecCdFN9sj5+aIdf7zGIsQCuNbh4KICriZVtEVNJMy4BHCcsTmJFGhPgaLzG88HZ/e/FntYVwJhMPFSKWhdIXaubNl1EBb9WKHxNvecoPTRNCeDwzHLM5Mg3BCEv0nOsD9Pb9Bww6xImEjSMPjbSM+h3aI3UST2AAxpLHxoL4N6iztykoUNDABxZTgDOkFTqVwngHq3O4Dwq0tgARwdqNj+bgjP6EMQxI5WetEXvxoiXWle9JKmniFAG8kqX1VKt+qcEcMgWGQ9JaIMs6Jgs+xv2HWyjyxAaKPbj3PG4VP9YAHdlNfyxUuOd9yUgKVVF7OR6qVCP98QJPizzuxLAcXnEw2va7QNwnJ3J2SOH7ztiNDAEQcS9lZv3GD3n1oUccSZnMvjyY1jHCAljY/mKGI9pMDyjJeCEYOFbjgDyED+QaYzAWcCUuKQcPUsvMXwzTuKn8OSSFcDYLaJf/0q8+7Cep8IRGO9DxDhMsFlylEaOm8Ucf0s0FYAD4LETpui9eoHB+xMLeVKOAFmCO+8ijrWxbj1oZbF91bJ7kvnB8WWjaSyAY1xnWsiKqILu/mUNxR/QZQAOuyQfkVS+LSYo7HvYwpgbwnCIPMChgJaJAy0Vb9gX4Ni32HWxfaeI/cTe5SN1TCvA4c0DeS0PKSEjbNBYyNv0rNajBUj8M9P57itSzKzQAvpXuuUBFzfhLRYhII6TAI5F2IVICYoplbeYO5q+SZVgOGaxWEQozsvFmzMymQrA8UGKM2BCt0lgZ6w5wj6Jx83ScnFA4TULlApSxqvGaWCjaUyAS43tM3oRRx4sA3DIO+VgwdGBVp2yd9NHFJ9PJ9ZEH4BDscIem4tu2M252QJwfCFKeZEYd2P7y7qe5Y5vqQljoaNtwWtiNCgADVdziJ/iHqz4K1EzqSmAo160UTTTFNEPC5CwFWFzjOlVenBb4zkaDZu65IFloXC8TQWzTgHgcjefsCBZ6DUEQKZCCE6hd2FDTT0LYw4AhzPMCgkjyuLuNZOpMmh/2L1jKt2NV3PDUVwn2VYoH7uAbi3AsRm52K9EqI+xDYSEZNz2NYT9A+Fxvs4l3ubqWgbgUIEx5JbIAiVLSyHfk+NtrJWgJaLx/bzU0OI94Ja6820KAJcLX8Db2UIp2wxH2aBVO8DtLtEhNbiUAkBEBOakPzZMKKcdgKdLJU27FeAwgRFatJtzqRbganNRLfdtDcBx3kcIbIa+wBYEuAzAAeKAeYlqAY7re6zYvNIXzGofjx6ByDFNAeCq3fYlwWbeY3cJQaspgOsbt7ZEt8yfrroGB4hZF4HyIXtBo7D4OGOeCPFznGhYxyl7NdW3AFwWLKcAcIAbLv+aywlrZDslgMMZAsDHxDXT3LTbQmzwF08U4N6gfqHBjkmxhxQtItaMp5LQvuoAh0MMx1hMeHFxEvUh0vOCian0+xaAwySWjC2dAsBhsOTLMBRNCeBSgb3YrHJ/R8GSBV5GPgQxTUGDs2LShprPUE8cU2kdydh8bMKNplUHuJtKgEcYQsTeTcbH2NQCcPSFWD3r47+Lmzl0epnrklqPqDU3eYZ+YdivOb5OCeCwPVpfvBbDexg/qvgbJwpwQ6T3lTZNbAdOxdwRsIsjaiNp1QGOnHBCpGIivdBKjxta1q0AR/vExmH62cV8tNEaHH/0g1AIixAwXlvibLilAOI4C8ixiAlLwakR/35KAIdabnlkSxcpWvIgJg5PdkxT0OAOUae2JuYxFW6TKJ58/CG96Qb8pj6OACEe7b6BulzIwM0tZKbUhizFnV51gNtvMf54XFya0De7o2W+UwAHFqRCkagf+x4xlcfO20YCHOEf241R42G8trgmtIDwiThpfUoAl0pDY4wYXbvXIeUWQMrdzm+mAHCpLz72R46MfcEmJxPsbxyXrLg58hSJ2WylA/SD8BeqODGQg9knrm7VAY6QHCsHGC8qmUm/bRWsyqOc4AkHc/gLWrk1kcpkwN6Gt9TKbAldQjHitLMzXGQjAS51g0hNUOjV1HeiqK3sgCkBHDJOGeDJs8TWUboaiLu2SM9JRZRPAeAActLjLLDBlrNF3L1wsmZ/sCH4CHLkIDfUIhY7mTIWod2Tr0iYTg2xnvgbtF0C5LiWqPWShlUHOGSQ+nOTRFSwR1vyxwmJQvMLQboE5LKHUxdxlFK1Ug63MHdo30REHN0FODqBas5RKN5MqIacb7nEzgrcIxwCwznpU7EKyeLk9gDSrbiZIZyRUzYl1EzSPOINwbEUryRxUrmrhkBwXNnEmNHvbmwM92nRPxatZc9iw5DmRWiHlc+KvAAU66oWPHjwDnGXmEiOVxaxgUgvIoI/juEBNDiGsUlzOawcD+kPtpFYIyQomZtrSYmKP2bUb0Wq46208h3JXmHhHJUYyyP1nPm3iAXNugLsUhdbYnJgbphb5rl7Tx52TLSrWLbc6cdcpeSDpsx64djK+ouBitQiNh23waRS6axcauLEWAe03/1bDGHspArFAejremaFWNAnZEpKYo5KbVJ3bKNmL1h/d4M2ucsw9/d0CU5nL1rEuiUbgSybXDYD8rm/2MobZa9t7VROzCjzzzpgPuKsjNjJhBkCsE0RfTwoLPrq7Hz9CK9n90417El8LWvocBUibQuQI6cu55HhZhBsb2dbDDa3yVNtsyEvKSbmhsXMsTeVERDX0Q0s5R1ARcpQydHB4o6vCkpFhXfbBKSwSaK5YLtLaWw5OXezTQhFIdNjaCJW0VqwbEBS9VL5h6EfjBOwYW73EbMOws3Nub6y6AHJmDbrwUcrBwnQ0kfi6AD/nD0nVMm66WrZjI9si9I6qOzSscU4zpNFY92EsqbnXM0+dJvrqpN1bR0XWYfsl5wyQedRYFB8mFPAjnVAnixXpeXWAm2HDCdkzF5N2eNpJwY4nm0WZ+cegAM4WiKTqZiEWtRLhJAL2KNsTFxZHQzvlg3N+s0yz7iBFM0BTamUatZtJw5utsISUv2K3elsYr7QQy/QuH00Fr6A5NmmbrtdRpbht6kbW9B2jhyiAaOOXDYNGn9rAGpNN7nBmnviusQaYi2NQal0PytDaKj2c5dT5Gy/y7bfNSXhvLA0zW4bFsBtUYHs7UAA3Jq49ert4C7G49RqcAS11xc933exEftoZ7UCxn3M8YmjXs44GddHci8R3YGswNJUH6zgQ46KBE+ODXJhbko5rrXys8pxfEwduznqERc39JyWPHglu0zreFkzrJ2Yxoz5I+XIsimiiaORj0Gl234wF2CPG3I+0aQvIw7mipqwEAvgijG04YiKVyOXpd8VLCopR4qg1rZMOOditJuu1jeGALv9DUb4lOs7tWjidCrsazW31KJFYePj35hYJNR78BgrVXUyNxxvsbGg0aDZDE2MC3tozjmCLRcbZ80RsKZ/XESJ1lRyyGBHfs2S7XIywQTz1kTHUrbjmnGUynCss+y7OXtYqc7S+5pbi/k4HyaO/xRiqW7rPWYeAvu7Xtqae+csgAOzwK4kBYDjjnNUb77+OYMt52TsL93gVY6cbH6CWnMoz71qbG7rrjY8hXixqq4hVjk2DwZQDMgpYGaz82XoHkvZ8Bg9Q16cJRhAmOMpG6prQOWYuVXM335IjTM4Y0r5rCwqFkztRwX1HTset7VYBOgwNwBnCK/hQ4Ihlw051NeXOWSeUtpbt2+YL7gXjDmvtXt2fw/A4GmGtyfGbT3eWw/5aB4oBhhqx047hISwrqzrwEJb2O/Q7oieH0obR6NhPcTH4dAmzjFOH8R4Ddkm7dFuLbHHmf9WbZKPBu1gg7cumACHcJaRS5yyw7HncTTFhAZ6h9TvrDCR2sGOUY7BsTjxyqKJYOsDcLaL8TTxLy741D39Y/RpzDrxMoWxon0ExwLgDIfxtpoBxuxzn7rX9CM2Bx9SjPt80ABAFjsGajYADif+n39xQAwRO8ftNByFAHsYzRqZY24g2wGvMzLGa9xqh+4jh7n8BtMSpzjWLozCQOwcGjYyZR7xePPfOB9wkPS5Rn5peU0N4JYekFfgEnAJuASCBBzgfC24BFwCs5WAA9xsp9YH5hJwCTjA+RpwCbgEZisBB7jZTq0PzCXgEnCA8zXgEnAJzFYCDnCznVofmEvAJeAA52vAJeASmK0EHOBmO7U+MJeAS8ABzteAS8AlMFsJOMDNdmp9YC4Bl4ADnK8Bl4BLYLYScICb7dT6wFwCLgEHOF8DLgGXwGwl4AA326n1gbkEXAIOcL4GXAIugdlKwAFutlPrA3MJuAQc4HwNuARcArOVgAPcbKfWB+YScAk4wPkacAm4BGYrAQe42U6tD8wl4BJwgPM14BJwCcxWAg5ws51aH5hLwCXgAOdrwCXgEpitBBzgZju1PjCXgEvAAc7XgEvAJTBbCfwf7NH42oaLLkUAAAAASUVORK5CYII="/></switch></g></g></g><g data-cell-id="IkmhDn_4ef8kqVBRZHeY-29"><g><path d="M 115 135 L 368.63 135" fill="none" stroke="#000000" style="stroke: light-dark(rgb(0, 0, 0), rgb(255, 255, 255));" stroke-miterlimit="10" pointer-events="stroke"/><path d="M 373.88 135 L 366.88 138.5 L 368.63 135 L 366.88 131.5 Z" fill="#000000" style="fill: light-dark(rgb(0, 0, 0), rgb(255, 255, 255)); stroke: light-dark(rgb(0, 0, 0), rgb(255, 255, 255));" stroke="#000000" stroke-miterlimit="10" pointer-events="all"/></g></g><g data-cell-id="IkmhDn_4ef8kqVBRZHeY-31"><g><rect x="235" y="111" width="80" height="30" fill="none" stroke="none" pointer-events="all"/></g><g><g transform="translate(-0.5 -0.5)"><switch><foreignObject style="overflow: visible; text-align: left;" pointer-events="none" width="100%" height="100%" requiredFeatures="http://www.w3.org/TR/SVG11/feature#Extensibility"><div xmlns="http://www.w3.org/1999/xhtml" style="display: flex; align-items: unsafe center; justify-content: unsafe flex-start; width: 78px; height: 1px; padding-top: 126px; margin-left: 237px;"><div style="box-sizing: border-box; font-size: 0; text-align: left; color: #000000; "><div style="display: inline-block; font-size: 12px; font-family: &quot;Courier New&quot;; color: light-dark(#000000, #ffffff); line-height: 1.2; pointer-events: all; white-space: normal; word-wrap: normal; "><b>frames[2]</b></div></div></div></foreignObject><image x="237" y="119.5" width="78" height="17" xlink:href="data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAATgAAABECAYAAAAV6ClkAAAQTklEQVR4Xu2dBbAlRxWGEyQQXILb4gR3l8Xdg9viFRwqwSXB3V2DU0AKCa4J7u76gkNwd/i/5U1qtjnd02Nv7nv7n6pTb/fe1n9m/jl9zum+e+5hMQJGwAhsUQT23KLz8rSMgBEwAnuY4HwTGAEjsGURMMFt2UvriRkBI2CC8z1gBIzAlkXABLdlL60nZgSMgAnO94ARMAJbFgET3Ja9tJ6YETACJjjfA0bACGxZBExwW/bSemILILC3+twuPYv0DNJTSH8s/br0G9JvSf+0wLh22y6HEtyxhNh+0gtIz7quZ9ffv0h/Jv259Kj1v1/W389Kv7TbouyJL4nAvdX5AYUB/F3f/VT6XumTpH8eMNhzqs59pLeSnrCj/kv0/QOkvxrQD1WOKz1QenXpaaR7Fdp5vr57zMB+tkS1vgRH+etLnyA9R08EPrF+UX7fs56LG4ExCHCv3r+ygf1VDlKoFV7095Q+tbbCerk/6O/dpa+S/qdn3bup/HMq6zAX5rTbSl+Ce6GQuvMItO7R4+KM6MZVjcDRCPQhuM+p1kUqsePZgaBuWVk+KobFWEu+TX1WQxeu7NMEVwkUxW4rfXmP8lHRN+jDm45sw9WNQB8E+hBcn/vz4RrEwX0GkinLUvM9Pdp5hcreprK8Ca4SKNb6P6ksWyp2R3350gnacRNGoBaBPgR3WTX60YqGz68yX+wo9wt9/23pmaSnL5Sl3Hml+Kxr5GIq9KmagipjgqsECr/bmzNlD9Pnn5b+Vnry9Qt6Rv3dJiWa1Mib9I87rJer7NbFjMBoBCKCwweGBYbgA4NkPi5dq+ztjSp340zZZ+nzR6+32RTZR/94sPS+mTpYggdV9k0xnrNrrv89xnq9B+rvKZM2THCVoHIBmhuiXaXrjQf4gP7v5IJXdutiRmA0AhHBYaVx7w6R46lSLtXjOvru7YVGc4bCu1XnGkMG06rzNv372ia4XRGoDTJEb6x3qqlrjbworm4E5kZgaoK7kAZMMCKVWv8dFh7BtrZgUZ5Y2jei2m7DBBdclFqCY3nK26ct5PPcae67s6N9xk8e3kWlJ5GSTEne3dAco5OqLstqEjRR2iQvam1df6i/5E1NJSw1eGD2lf5aimVBX23BYji39HzSY0u/JyVh9AcjB3Ei1Sd/i77J3fqllKXad6TMc2rBmj+1dJv0zNKTrc+ZvEn0m9J/Tt2p2pua4LhHuFap4Japwe26KvfWoD6YrI2YvwkuAC8iOB5wEiNxfPJWQXCqRlJK3uWt9FXpk6U4W3NyHH3BG+3K0tMVyuHDaMx/SO1BUiKyUWLlc/X5I6Q8tCXB+Xs16aWll5PW5PbxpsbH0pW4zHLh9lJufObYlsP1H7LbnxcMrvFV/kvfPVSaSyN4jb57iHStY47tr0kvwFdzKWnJ8c3cDpUSEPpRj/ajoqRdcC14sEvC/UKUnpfUjaR/k5LvVVry1QxtaoKjzzSC2if96eaq/9pg4LxomPtQMcEFyEUE90GV2z4U5aAeAYiLF9oj8IA12CV3VYFXSx8pvV9XYX3PA4NP5EOZeT9Fn+ecvhXN7/F6FYLAosx3dnVgZQ0Vxs6ukNRpnLZHOay7LhLCyQ1uQ5I+SWJ9lJQgUh9hXPSZc8bXtnVVFXxfbeGg3BwERze8IPDjfV6K9Vkjx1ShI6SXCQpjGfbFuN2MCS4ANSW4s6lMydqquYhRGZZXX8lUJuRN6LtLsJywBtqR2a46fL9NemRSkIcP63KskOhJfmDqOzlIn2G1bISwrL2i9B+ZzniBPF3atYWoNFaWxbgoctcwrcv17rJwa7F5rApiqQ6VuQhuyHiwxhlPKryg2Ls6RkxwAXopweEXGeq/Kl0clp65PLpSyH3MBW/qRssHlqORZTekP/YgPiOpuEP/f9mQxgbWYanOCyAVEkJJDJ1C8M+x9xh/WUnwXeKELy2B+4xnrK93VQjuLpr0CzITx0KOshT64GSCC9CKlqj4PdjvNpXgV9lRaOwK+u7wqToL2uEhx9JqC856iLzLqmEJ2FXmaypznqR9AgPfl3YtMaeaNg8xvrW2XFL/IbdrSvmwGruStBQMqHU51I7rEBXEFTBUVoHgSuTGPcbKiRfIGDHBBehFBEe06ypSImxEERGsoPRhZdnCzZcTLhy+Cbah4DAvybn0Jf6MU0npH99NreBLe6b0j1KWYu1tLIyByF3kJ8M/R34fjneWCGSmY3mwtCIS+11p8yBDcqTE0E9EWnxP/20hsMA2HAIFuSX4i/Qd4yevCjLKWT1YZwRV8MtBMuky/XB9xjK1EXaefCEzVspAys+W8lBwkgbzZA4QNUvukq+O71+5y0x3/Q8WFySXCqd18B0+Xl4u3BPcX2T631CKXzV6mYxNVl2a4FheE5TKSVfuXKHqLl+Z4AKkVjVNhBNHuiwnfE87pKQ1tOV6+g83DZ9jPXJ0U0mw5nL+q7Qe1sv7g8ZwGn8s08nT9DnL2FT4vB0sifKjqEMwgw3dzUuC5fC9ksZSK5LgSe6Ei8fru4dJS1YYLzdSGaKoMi8Dgih/zcz3I/o8daLzouHlBUHnBKuXFwjb+dpC9PxxhXpdXy1FcAQUuMacNpITXlpcjynEBBeguFkJDquIG3fqvCn8R1gU26TkJfHQkWoCSaLkwHHsUypsm3lX5i6NCA5Cwp/VHj9zwhfTFpYtjKNtgfLAp2d8pQQXkQztcg7ZEzPjTD/GuuLkiiiogzVLonckuRNnsPhxFdAmln3bQm7aIZL4mVafRKK3S7Eyh8oSBLe3BnuItHSwRN/tWV3zN8EFCG02gsMSIEdqTNpACgPLOfxXqVXUdUO1v+9LcB9QZfL+2hIRXOTf6yI4LKVcIAByY9tcrTDGaHldIkqSv1l61wjzYylNTiDExjId651oOWet8V3OUqxpnzIbTXC8JMlljFJBmjFHPtPa+eTKmeACZDYTwfEwsPzkzT+FYC2wlGO5NlZWieBupsm8buyEOuqTZMzptZGULL+aYeFjhADeIR2zdalNJmmy9Ji9qKU5sLRn3KVUJl5kc5yya4Lb5ARHoi/LnykEZz5LpaminKtEcJwUSwBhTmHpyMOck9x+zT5jIkH8BtKxx3RtlAV3eY0Vkin5jjks9sV9QOhR1gRngtuJALl+LIVqtmXV3l+rRHD8BgHR5Lmly/onIgvRbh8xEAIa5CyujWhjIwiuJt9wqmhpDgoTnAluJwLRwQHRTYO/D+mK5lJmlQiOpWOa9zeCH7JVuwiuqUgKEK4FLBy0Bs92p2OPEpqT4IiUkgKS5iC2x899RPQdH+OcYoIzwe2MjpKAmxOc42SbE+Vr8tr4FSMc9wQjqB9tlF4lgsulsjDnKAI85KH7nSrlzi9jy9Ht1htll0q6gZwTVIgMc2ACCa6knLD5v2RRMyfy54bIXAQHUZMPmJ6y0x4jS3lyIdeGDLxnHRNcAFjtW3ijj0uK8uCm8MFFkUpgwd9Dsim/YVkSburoV8FWieA4BgkCSgVLAhLp2mrV87napTiRQ1JUGqFPyKxm+x9kx/7dWwcDIBBUSpYtjXkOgiOViDzB3Ck7jIdI+X7S34wBtEddE1wA1u5GcLxxoweI0H7paCV2JdxCyoMWRchWieC4zNHNzudYFBzjlCZHdz1H3CenlRIhJaUjl2oSJSsTcWXrX0S6ab8s+aLcRq4bOyiGyNQExxY4dueUltrs2GDOXWcHkmcZ7bIZMk8TXCXBAfoFpSzLuOEQwtrpEgKrJ5c0yk2KpcBRMpzrVRLIhbPncP43hBttHOdBIb8oEvrAIU3eVCm1ILdbgGxzzmZrbyljy9g2KeTFRuhSxBWnPm9sTighobUR6hD5TZcxpLxAmO0TNyLrkjlx3BBYN/OK8uBICOa8taZc6TABrCquG366tRDN/117EpHZxsZRV2zdax5o5rdDSjpHKjn/Jn3yciCCGB33zW4StpqRi5geu00fWG9D03mmJDis0fb1jeDjJcK1LN2HvDBvIuW+wG2A5drnl7Wifk1wASqpBYfpzfFFU6VP8IBixufMdB4c9ihOJbTFAZY54aZi61MkjJXtVrxRcYzzph4i7FxgCw47G7Z3NMDDABlBULnlM03wUJF0uyaNCK7phnKcn8Zf5sl8SwLRcgpts1MA/9glpF3XP+f4JweMF0JJmCvHLnEi8fGlWIbcIyWLqLRzoqO7SRN9a35Nq2s80felPdO17ZngAqRSguPsLR7OKYW3MpZTJFMfrkkfpX2hPLhde1OnmDupGukRSrl2m/2IJYKjLvsxIbcSwVGuyZJnOUlCK2ffzSFY9+lSNbc0HtM/ZI01mR5mUNvmlBbcXATHXPaV+kTf2qtaWS4lOKwOoj5TSsl/MkWmejrWruOjyUc6bMoJBm0RaWUJWiOMhTSKLoJjSUiaRRfBtbP0iWiyrW3KnD/mhKuALXOpcAbejppJV5bBsiFpeMzulc1CcESSx0S5bcEFN1VKcDUJi5X35tHFSsuLnE+sbx/t8qXDNZtykGDOqhzTN3V5KFl6f7Kyoeb4oS6Ca4i7i+DwJ7Z3MpxA/8e/GAVXKoe4SzH8fJxuEgUqSuee9e0L4mfPK0GNMWKCG4PeJq+bEhynIOCAZotM7myy2inj08KRzYObOw+OPjjWh0Mvu/w+Xf3iz+LomdqTdFm6MdfIqZ32BWkRGXuLtJSPxXlyzJeTNvaXckxSznoCH/xkJIlyXBNHJ3E2XCr4rA6VHiDFP0ib+Ply5Q7UF5EjH58ifZXytoJmd36EZYF/kyBC9JN5TT2c58wbkiV4RLCI/MEuv1y7X4iNkzbYSjeFTElwY39rozQfAnucSThUbMEFyNWmiQwFfTPU47QMbi7ysPCD4LvC8X7kumKpsDzsCvlvhrkyRqLV/IoYwQTIZx8pDn7SZNakEC/5gI0SDR97LBV9EvzYJiVCi5VNv+TH4WND6Rusu6KUfXGekuD69r2R5U1wAdomuI28Bd3XEgiY4JZAfUX6NMGtyIXwMGZDICI4Omv/rCMnluB64Dd8p0q8nWtCe6lhMhNY9rfdSJErZOxx73PNYcPaNcFtGNTuaCEEcgQXDaeU0rTQ8P+v2z4/6mOCW5Wr5nEYgZkQ6ENw0QnKMw1rcLO54+ijBk1wg2F2RSOwORDoQ3BNTuIqzyz3q2UmuAABL1FX+Vb22KZAoA/Bkb8Y/WraFOOYqg32B9em0NiCmwp1t2MEVhQB8v/YAZITdtMcJeWUZ84B3AxCjiE7cki1KRkpJJsfsRkmNNcYbcHNhazbNQJGYHEETHCLXwIPwAgYgbkQMMHNhazbNQJGYHEETHCLXwIPwAgYgbkQMMHNhazbNQJGYHEETHCLXwIPwAgYgbkQMMHNhazbNQJGYHEETHCLXwIPwAgYgbkQMMHNhazbNQJGYHEETHCLXwIPwAgYgbkQMMHNhazbNQJGYHEETHCLXwIPwAgYgbkQMMHNhazbNQJGYHEETHCLXwIPwAgYgbkQMMHNhazbNQJGYHEETHCLXwIPwAgYgbkQMMHNhazbNQJGYHEETHCLXwIPwAgYgbkQMMHNhazbNQJGYHEE/gu6nlhy+DSzDQAAAABJRU5ErkJggg=="/></switch></g></g></g><g data-cell-id="IkmhDn_4ef8kqVBRZHeY-32"><g><path d="M 115 270.5 L 368.63 269.04" fill="none" stroke="#000000" style="stroke: light-dark(rgb(0, 0, 0), rgb(255, 255, 255));" stroke-miterlimit="10" pointer-events="stroke"/><path d="M 373.88 269.01 L 366.9 272.55 L 368.63 269.04 L 366.86 265.55 Z" fill="#000000" style="fill: light-dark(rgb(0, 0, 0), rgb(255, 255, 255)); stroke: light-dark(rgb(0, 0, 0), rgb(255, 255, 255));" stroke="#000000" stroke-miterlimit="10" pointer-events="all"/></g></g><g data-cell-id="IkmhDn_4ef8kqVBRZHeY-33"><g><path d="M 115 398 L 368.63 397.02" fill="none" stroke="#000000" style="stroke: light-dark(rgb(0, 0, 0), rgb(255, 255, 255));" stroke-miterlimit="10" pointer-events="stroke"/><path d="M 373.88 397 L 366.9 400.53 L 368.63 397.02 L 366.87 393.53 Z" fill="#000000" style="fill: light-dark(rgb(0, 0, 0), rgb(255, 255, 255)); stroke: light-dark(rgb(0, 0, 0), rgb(255, 255, 255));" stroke="#000000" stroke-miterlimit="10" pointer-events="all"/></g></g><g data-cell-id="IkmhDn_4ef8kqVBRZHeY-34"><g><rect x="235" y="374" width="80" height="30" fill="none" stroke="none" pointer-events="all"/></g><g><g transform="translate(-0.5 -0.5)"><switch><foreignObject style="overflow: visible; text-align: left;" pointer-events="none" width="100%" height="100%" requiredFeatures="http://www.w3.org/TR/SVG11/feature#Extensibility"><div xmlns="http://www.w3.org/1999/xhtml" style="display: flex; align-items: unsafe center; justify-content: unsafe flex-start; width: 78px; height: 1px; padding-top: 389px; margin-left: 237px;"><div style="box-sizing: border-box; font-size: 0; text-align: left; color: #000000; "><div style="display: inline-block; font-size: 12px; font-family: &quot;Courier New&quot;; color: light-dark(#000000, #ffffff); line-height: 1.2; pointer-events: all; white-space: normal; word-wrap: normal; "><b>frames[1]</b></div></div></div></foreignObject><image x="237" y="382.5" width="78" height="17" xlink:href="data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAATgAAABECAYAAAAV6ClkAAAPSElEQVR4Xu2dBZA1RxWFEyS4u2ZxgrvLj7tb4YuFCg5FcIckuLs7FBAsuP64Q3CHDQ7B3eF88Iaav+me6Znp2Zk3e27Vrd33pvX0zJnu27fv23svixEwAkZgoQjsvdB+uVtGwAgYgb1McL4JjIARWCwCJrjFDq07ZgSMgAnO94ARMAKLRcAEt9ihdceMgBEwwfkeMAJGYLEImOAWO7TumBEwAiY43wNGwAgsFgET3GKH1h2bAQL7qA0Xkl5W+mXpm2fQph3VhL4EdzShdEPpeaVnWulZ9PdP0p9Ifyo9cvX3i/r7GekXdhSy7uxcELi7GnLvhsb8Vdd+LH239HHSPw5o+FGV9zwrQrui/l6jVtaz9f8BA8qush5T/xwovYr0VFJINCXUeVCBOte2iK4ER/rrSB8jPWvHXn98NSi/7ZjPyY3AEAS4V++TWQAEBCnkCs/DftLLSC8vvar0eInMpQjuTir/GZkNLFVnZnXzS9aV4J6rLtxhQDfu0mFwBlTjrEbgfwh0IbjPKtcFM7BjFnUvKbPDk2ekJ0kpsmE1dIFtrjOzuvkl60Jwt1LzXzKwC69V/hsPLMPZjUAXBLoQXO79yRLxsV0aUZDgXqqybplZdylSzaxufslyCY61/o8KNP92KuOFBcpxEUYgF4EuBHcpFfqRjII/qDSXzkhXT1KKbC6sQj+ZWXepOjOrm1+yXILD7vbGRPMP0/efkv5aehLpvtLTSzekZ6zleYP+v+0q3fyQcIuWikCM4H6nzj5k1eF/6e/PpB+TbmWC8ILVvZyZ/D/JSpINz9nVVs/bUVaNuJ/+hsvlknV26ets0uYS3MNrN0S98W1vPMAH9H+ubqLZdNwN2TEIxAiOWRr3bl+5pDJ+OJL5ffqO3dgHSMPNhrHJ5i2qs75rW5pU+2I1ab5cgnudWnmDoKVv1+erT9p6V24E2hEYg+CodUN6Cymzwc9LWTZWLiZTkM0UdbajP3GKXIJjecoytS5M028/g/bjh4cz5QmlX5Pid/eLnu06kfKxrD7ZSimTm3Zrpd/XX/ymSglLjfNLcTX4pZSZBXXV5dj6cA7puaVHl35H+g3p9wY24vjKf7ZV3cw2fi5lqfYtKf0sLczmTyndkJ5BeuJVn/GbRL8u/XvpSlXeWATX1NQpyGaKOkcYrrJFxgiOBxzHyHNJT7CqDufFmDQ57/Jmw3v78dJvNjT7GLqG+8gVpKdpSMe0/62r65Da/aXsyMb8jp6p7x8q5aFtktPq4pWll5BiNM7x7WOn7VHSNsdllgu3kWKPpI912a0PX5U+K9K4ylb5D117kDTlw/VKXXugdKulj/XLuBdgq7m4lL6nhL4dKmVD6Acdyo8lxe2CsbhWSzncL+zS85K6vvQvUvy9qjHv2wwTXF/kFpAvRnDvV792FewbGxAXaSiPjQdmg21yRyV4hfQRUnyQ2oQH5ppSdrxCod9PkN6zrZCG66/RNQgs5vnOqQ5mWX2FtnMqpM3HinTM7tpI6KQr3Pp40j9ReR8pZROpi9Auxio0bXQpg7RXkr6na6ZaehPcAPDWPWtIcGdWh5pmW337y/LqS4nM2C7Y+m4TZk7MBuo7s215uL4hPSJIyMPH7HKovFwF4B/ITlxdHqYPzFq2Q1jWXk76t0RlvECeLE152Oe0kWUxJorUGIZlMN5tM9yceklzsJSZal8xwfVFbgH5QoLDLtLXftUEB0vPlB9dbAOjJLSx0xMsR2Mzuz713kOZnhJk3NTnF/UprGceluq8AELBIRTH0BKCfY6zx9jLmgT7JScCmpbAXdoz1NZrguuC9sLSxpao2D0471ZKsKvwwKeESAu7S1UWKYeHnJlWXTDWQ+RtsxqWgG1pvqI05wzKZ2Pgu9K2JWapbvMQY1ury8X0Ad+ukvIhFcaZy6bNgFyTQ267XqyEmAL6igmuL3ILyBcjOHa7iITADhu7iAizoPBhZdnCzZcSyIGdsXdJMZg3ydl1Eb+kU0ipH9tNrmBLe6r091KWYvVjLLSBnbuYnQz7HP59GN6xYbHVz8yDpRU7sd+WVg8yJIdLDPXESIvr1F8XNhaI+MBGQWoJ/jxdo/1/kEJGqVkPszM2VbDLQTLhMn23vmOZWgknTw5PtJU0kPLTpey8EUmDftIHiJold5Otjusv26One35IOcHiH8Y1bLy8XLgnuL9wDL+eFLtq7GUy1H/MBNcwWEu/NFc3ESKOtM2csD1tSnFrqMu19QHy4ntmj4RuahJmcyn7VZiP2ct7I4Xh+PnRRCVP0vcsY0Ph+/pmydP0mRdJKGxm3ExavSRYDt8tSBTOItk8YXMgJo/Wlw+WNs3CeLkRuyy2q8zLgE2UPyfKxwEWPOrCi4aXFwSdEma9vEA4zlcXds8PacjXdskE14bQgq+vK8ExK+LGLe03hf2IGcWGFF8tHjpcTSBJFB84wj6FwrGZdyTukxjBQUjYs+rtp0/sVtYFuxftqM9AeeDDGF8hwcVIhnLvK809JM7sisgVsU0dZrM4esckFXGGGT+mAspkZl+fIVfl4If46Vqd7ETvkjLL7CsmuL7ILSDfuhEcMwF8pIa4DYTDxnIO+1U4K+oyvF0JjiM9+P3VJUZwMfteG8ExU0ptBEBuHJvLFdoYW143ESXO3yy9c4T+sZTGJxBiY5nO7J3dcoKqci01U8wpnzQmuFykFphunQiOh4HlJ2/+EsJsgaUcy7WhMieCu4k68+qhHWrJj5PxzRNpmmZ+Oc3CxggpvU0aut/k5A/TmOD6oLaQPOtEcDj6svwpIRjzWSqV2uWcE8HdWf1iA2FMYemInS4lHD9jw2aI4CB+XenQMF0muCGjsOZ5dyLB4evHUijnWFbu8M6J4Igyy27y2NJ277AjC9HuGtAQNjTwWdwaUIYJbgB465617Sat+rfdh+1ju6ilZnCxvsTGEXsf0rabS5o5ERxLx9Dvb4z7NPfewQUI0wK/W4Dm4Flv7zv1gd866CsmuL7ILSBf7k26FILb0JjhgJsSjOPPkbLLV/m1EX8fwz2bEeR/VSTznAgu5cpCs2M7wH1u4980kM7pdO3Wq0I5pcLh+boQQYWdYQImcDQQlxMO/zfNqOkT/nN9xATXB7WF5NlpBBfbqWQosffgbPrDlnFl9hH7VbA5ERxhkCCgUJiRQiJtR62G3NphIEjqhMxyjv9BdpzfJcZaKGwEEcGlj5jg+qC2kDw7jeDwwI89QPi/NYVW4lTCTaU8aDG/sDkRHLdmLDYY37M5QBin0Dm67XbmPjm1lB1SXDpSriYxZ2V2XDn6FyPdsF5+VzTm28i4cYKij5jg+qC2kDwxgsO59XxSlmXccAiOpeESgllPymmUm5SZwuekxPVqEsiF2HMY/6v2xA6O86AQKy0m1IFBGr+pJteC1GmBuyofsdnqR8o4MrYhhbyI39+044pRH982IpTg0FoJedj5DYOF4vICYdYjbsRml/SJcENgXfUr5geHQzDx1qp0TcEEmFUxbtjptqJo/nfscUTmGBuhrji6V9nO6N+mFHeOUFL2Terk5fB8KcfSQuE0CUfN8EUMw26TltlbX3eesQjuOGpT9ZxUv4tQ9Ys6wxch5gGO5dWFFwXPCde6+CdGIIy+1IYec4vVs1bfhQSHFz/hi0q5T/CAEizzVwlUeHA4o1hKKIsAlim5kS5w9CkmtJXjVpwawDDOYfU+wskFzo1ysmFXSwHMqCAjCCq1fKYISAWn2y1pjOCqakhH/DT+0k/62yQQLdF7q5MC2McuKm0b/5ThH981XghNQl8Ju0REYkiCmSH3SNPmQ9PJiZbqRnH0xX7Iy7vrhkmqrYwXzs1dY+7Vy3NE3wi6IcERe4uHs6TwVmbmFJPSwTWpo+lcKA9u29nUEn3HVSMMoZQqF7w5H9pEcOTlPCbk1kRwpGP2wMkMlpOc1yX23RjC7D6cdaSWxkPq5+FnNhkGM8gtc4wZHBGjD8htQGa6oT+KboKLAB0SHLMOImCUlCb7SQlP9bCtbTcKB/EPK9nBSFnstLIEzRHaghtFG8GxJMTNoo3g6r8YxY4mx9pK+vzRJ0wFHJkLhRh4mzmdzkzD0han4SGnV8YgOCLkMFMuKU2nQ3LqMcFFUAoJrmSAxKq6puVFyiaWM6CpNE3BNas8kGBqVjmkbvLyULL0/kRmQVX4oTaCq4i7jeCwJ9ZPMhxXn7EvxjZXMpu4RzLsfEQ3iW1U7K/vcbMpIRA/Z17Z1BgiYxDcphpUOqApttbXD+ioCS4CXkhwx1IaDNAckRkakRWbFoZsHtxUPDjqIKwPQS/b7D5tY489i6Ve7o3H0o2+xozaYV2QFrHM3iRt8sfieBL9JdIGSxjCJKVmT+CDnYzlJOGaCJ0UGqFpBzarQ6X8EBD2QcrEzhdKle5AXYgZ8rEpUle44REp6v++wgiOfZNNhKYjWOw2029Ils0jNovwH2yzy9UrhNiI08dRuhIyBsHxnLDpQWinofct9wGrHMpri5vYhIcJLoJOrptIiRttrmUQLYPdMPyw9pNiu8LwfsRKmamwPCz5c4FTYsFuNb8ixmYC5MMP0mAsx01mS8oDhz9gpezyDQ1LRZ0s6Tak7NAyy6Ze/OOwsaHUDdb1XegSOI1BcCXaVboME1wEURNc6dvM5c0NARPc3EZkG9tjgttGsF3VJAjECI6G1H/WkYglmB74Dd9YePtJGp6odB99j2cCy/66GSlmCrEf3JxGzm0xAiMgkCK4WFVNLk0jNK1XkV1+1McE1wtiZzIC64NAF4KLRVCeW09T4ehj7TTBzW303B4jUBiBLgRX+SQWbkLR4lK/WmaCiyBgG1zRe8+FzRCBLgSH/2LsV9Pm1C3OB+e60HgGN6eRc1uMwAgI4P/HCZCUcJrmSClRnokDuA6CjyEncnC1aZqk4Gz+gXXo0Fht9AxuLGRdrhEwApMjYIKbfAjcACNgBMZCwAQ3FrIu1wgYgckRMMFNPgRugBEwAmMhYIIbC1mXawSMwOQImOAmHwI3wAgYgbEQMMGNhazLNQJGYHIETHCTD4EbYASMwFgImODGQtblGgEjMDkCJrjJh8ANMAJGYCwETHBjIetyjYARmBwBE9zkQ+AGGAEjMBYCJrixkHW5RsAITI6ACW7yIXADjIARGAsBE9xYyLpcI2AEJkfABDf5ELgBRsAIjIWACW4sZF2uETACkyNggpt8CNwAI2AExkLABDcWsi7XCBiByRH4N5UeQ3JTyzAMAAAAAElFTkSuQmCC"/></switch></g></g></g><g data-cell-id="IkmhDn_4ef8kqVBRZHeY-35"><g><rect x="235" y="246" width="80" height="30" fill="none" stroke="none" pointer-events="all"/></g><g><g transform="translate(-0.5 -0.5)"><switch><foreignObject style="overflow: visible; text-align: left;" pointer-events="none" width="100%" height="100%" requiredFeatures="http://www.w3.org/TR/SVG11/feature#Extensibility"><div xmlns="http://www.w3.org/1999/xhtml" style="display: flex; align-items: unsafe center; justify-content: unsafe flex-start; width: 78px; height: 1px; padding-top: 261px; margin-left: 237px;"><div style="box-sizing: border-box; font-size: 0; text-align: left; color: #000000; "><div style="display: inline-block; font-size: 12px; font-family: &quot;Courier New&quot;; color: light-dark(#000000, #ffffff); line-height: 1.2; pointer-events: all; white-space: normal; word-wrap: normal; "><b>frames[3]</b></div></div></div></foreignObject><image x="237" y="254.5" width="78" height="17" xlink:href="data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAATgAAABECAYAAAAV6ClkAAAQk0lEQVR4Xu2dBbAtRxGGE9w1uD2cAMFdH+7u/nCCS4K7u7s7FJDC3R5OcHe5Ce7u+n+ps9Rm6JmdtXv23vd3Vde95+zs7My/s//2dPfM2XsvixEwAkZgmyKw9zbtl7tlBIyAEdjLBOdBYASMwLZFwAS3bW+tO2YEjIAJzmPACBiBbYuACW7b3lp3zAgYAROcx4ARMALbFgET3La9te6YETACJjiPASNgBLYtAia4bXtr3bE1IHB8XfP00tNId6z0SPr7bek3pd+Sbkj/sYa27ZGXHEpw3LTrSs+5uqHc1DNK/yL9qfRn0l+s/n5Zfz8r/dIeibA7vW4E7qYGHFBoxN917CfS90qfIP3zgAafQefcS3qHinN/rjJ3lB5UUTYqcjR9eaD0CtKTSY9SqOe5OvaogdfZFqf1JTjKX0P6OOmZeiLwydVN+X3P81zcCIxBgLF678oK9lc5SKFWTq6CkOKNa09olXu3/r+z9Ds9z4Ucn1V5Dn2hT3us9CW45wup245Aixtae3NGXManGoH/IdCH4D6ns85bid2ZVe7D0hNXlo+KYc3tK/11jzqYDZ2nsrwJrhIoit1c+rIe5aOir9eX1x9Zh083An0Q6ENwteMTw+Bg6fn7NCRTlqkq7p5aebkK3qyysAmuEijm+j+uLFsqdmsdfPEE9bgKI1CLQB+Cu5gq/VhFxadWmUM6yv1Bx78gPbL0bNJjF8rfQscgrhqBVD9VU1BlTHCVQOF3e1Om7Fv1/aelv5WeUEoEiQGwQ3q61jlv1P+3WpWrvKyLGYHRCEQEB/k8eFXzf/SXqeInpBuVV9tH5QiiRXJffclLPD1+GX33GGlk9b1Z31+z8toU4zm70urvEVbncd10umyCqwT1Ya0B0T6l640H+ID+79UgqrycixmByRCICA4rjbE7Rl6jk2/YquBrq89kDeQEK+6j0nMkBSDc44xpjM59m/QqSR0muEpQ36By10nKvlOfr1x5vosZgXUhMBfBHUMdwp+MJfUV6VOlEFWX4G/D15fKqfTFD7tOLhw3wQXg1EZRmZ4yTW3Li/ThNiNuyBSn0n5y8M4nPZ70G1LeoL8aWDmJmkyrT7RS6iQvamOlP9Bf8qamEqYa55Y2kTQsC67VFh6ks0r3k+LP+Z6UhNFDRzYCi4FIINfGsvillKkaaQv0c2rBmj+pdIf0tNITSIkekjeJkgj7z6kvqvrmIrihTb22Toxy4LDqStZf1/VMcAFCEcHxgJMYeXbpcVfnpCZ1U1UpeZe32VelT5SSyZ2To+oA6SP4KE5RKHd/HXv76jikdj8pb9DIeftsff8QKQ9tSU6pg5eXXkR6cWlNbh9v30dKuxKXmS7cUoo/kj62Zbc+fF36nKBxja/yXzr2QGkuh+vVOvYA6UZHH9uHSS/AV3NhKX3PCX3jIcSXNMaqoH7SLrgXV+toJ+OFKD0vKUjgb1JSipp73qObhyu6NILLRUEZI2Nenia4YIREBPdBlds5dDQF5xGAuEChPgIPWINdcnsVeJX04dJ7dhXWcR6Yq0rJVUqFfj9Jeo+KenJFXqcDEFiU+c6qDqysoULbWRXSlWNFOay7LhLCKQ5uQ5I+n6zzHiEliNRHaBfXTF0bfeqg7OWk7+t7Uqv8kgjuQStM0u58QF/wgh8jJrgAvZTgWHJSsraG3gCmV/gpIiHkXZNPhOWENdCOzNa0Z4cKpSF9Hj6sy7HySlVAfiCRuLY8VB+wWjZDmNZeSppb38gLBP9QKU2hq51Mi3FR5O5hej73u8vC7bpmc/zR+gdLdaisg+B4rhhjLKM6ohQ3BKsddmY6wXghkDdGTHABeinB4RcZ6r8q3Rymnrk8uiiAMeZGp+dGqyeYjkaW3ZDr3l0nPS05cZc+v2RIZQPPYaoeOa5JCK3Nr+q6NP451h7jLysJ/ktWBJSmwF3Xah8f6+vdbIK7ohrP1Lr2RQyuuIBYvz1GTHABetEUlZvDerepBL8KD3xOLqkDu6e6WFAPDzmWVltw1kPkXVYNU8CuMqQHkMjZFgID35d2TTGn6jYPMb61tlxIH8jtmlI+osouLS0FA2pdDrXteqkK4goYKptNcMwMsN5qhdnLZ2oLF8qZ4AJwIoIj2nVZKRE2oogIVlD6sDJtYfDlBHIgMvYeKQ7zkpxFB8lLOomU6+O7qRV8aU+X/lHKVKy9jIU2ELmL/GT455gW4HjHh/VFKZYHUyuiWd+VNg8yJEdKDNeJSIvjXL8tOI3Z8YFAQW4K/gIdo/1/kkJGOasH64ygCn45SCa1DnbrO6apjbDyhCz6HMFCys+U8lCwkwb9pA8QNVPukq+O469I+tr+iMUFyaXCbh0cw8fLy4UxwfgiMfxaUvyq0ctkbC7XZhIci+9/VMAmPcT9v12P8qWiJrgAnaWmibDjSJflhO9plzTdjeHq+g7y4nusxy7TH2uudn8urJf3BzheVN99PDP6nqLvmcamwvftYMkz9JkXSSoEM/DfNC8JpsN3TQqlViTBE4IDkTxWX+LsLllhvNzeIo2iyrwMCKL8NVM/iazg0RZeNLy8IOicYPXyAmE5X1uInrMCYKhsJsHRRl7qNdH4pj830j+vHdq51nkmuADErUpwWEUM3KnzpvAfNZsVkqvFQ0eqCSSJEsZn26dUSPZ8V2aQRgQHIeHParefPhGtbAv+GdrRtkB54NM9vlKCi0iGeu8jfXzlw4R1xc4VkS8Ja5ZE70hyO85g8eMqoE5IoG0hN/WQh8h0rbkmkeidUqzMobLZBMfsB6s8l1oV9QNLn5nOGDHBBehtNYLDEiBHakzaQAoD0zn8V6lV1Gew9SW4KC0gIrjIv9dFcFhKuUAA5MayuVohdSGaXpeIkuRvpl41Qv+YSpMTCLExTcd6J1rOpqocy1mKNfVTZrMJrmkXVjCrE8iDJKi1q9BgxjUZDLzQhooJLkBuKxEcDwPTT978UwjWAlM5pmtjZUkEdwN1ZoopTwkTkoxvkilQsvxqcMbHCCm9Q5qm39Scn5ZZF8Gl7cBix92Qm77yghuz+64JbosTHIm+TH+mEJz5TJWminIuieDupH4RQJhTmDpioeSEvC8CNmOEBHF22Bi7TddSCA4sjinFh5r6GTmGbxNrbyipm+CC0baVLLipCI5cP6ZCfRzBXQ/qkgiO3yAgmjy3dI0dIrIQ7c4RDeGhZ3q3MaKOJREc3SBLgAAZaTyp4F4YOk01wZngDkMg2jggen6anSG6ormcuySCY+qY5v2N4IfsqV0E15xIChCuhUustAbP9kX57QKSZ4fK0giOfhDlZx/FVEhZ+vzAjprgTHCH7WRBAm5OcI4/T0qUr8lr41eMeLMSjOB89gFLZUkEl0tloc1RBHjI8/Q7nZQjHRzr7FCLsEqFxfNtYQcVIsNsmIBjnZQTFv+XLGr6RP7cEFkiwRFEiZJ7eQnggxwiJrgAtdq38GZvlxTlwU0xRY0ilcCCv4dk064kTayP6FfBlkRwbIMEAaWCRQqJdC21GvJwNeeQ/0aKSiNcEzKrWf4H2bF+96ZBAwgEsYPLEFkiwTGWo1/vgvRJpxkiJrgAtT2N4MjAjx4g8t9KWyuxKoGETB60KC9sSQTHbY4GO98THGAbp74/Vcc4IUufCCkpHblUkyhZmYgrS/8i0k2HJAvTo9xG7hsrKIbIHAQHHvgGCRrslpYSmNM2Mw3lnGiqTtL50NxOE1wwOiKCI7n1XFKmZQw4hPB1OoXA6skljXKTsBTwJ7CvV0kgF/aew/nftCdaOM6Dwl5pkXANHNLkTZWiULnVAnfReezN1l5ShjN4hxTyYv/+UsQVpz65baxDbL+BOYfIb7pZKCkvEGZ7x43IuqRPbDcE1k2/ojw4HNPst9aUK20mgFXFfcNPt5HBk3tPWgMPI1tdkbzaPJD0b5c0mkrl/Jtck5fDC6UsS0uFB5ulZuQipttuUxbrbWg6z9QEx/MBzs16U/pGMjcBldzvNDCuySckh5Mcwkj6/i5DWocJLkA1JTiy+Nm+aKr0CR5QMrp/k7mpPDisUZxKqIsNLHNyPR0gFykS2spyK1YN4BiPolw17WSws26UlQ07O07AooKMIKjc9JkqIBWSbjekEcE1l6Ec+6fxl37S35JAtOze26wUwD92QWnX/c85/sld44VQEvrKtkuHSrGAsAwZI6XgQ2nlRMflJk/0LQVxuJ/kaeK/5QUJnmCJX7IruFJa7tfVR46b4AKUUoJj7y0ezimFtzKWUyRTb67JNUoDhcHWtTZ1ir6TqpFuoZSrF7xZH1oiOM5lPSbkViI4yjU7izCdJB2hz84WffqOdZ9OVXNT4z71pmUha6zJdDOD2jqntuBY4ztmo9So3exaTGR1jJjgAvRSgsPqYF3clFLynwxNaiy1L9r/rV0+F6Kfss9EWpmC1gjpAqRRdBEcU0KibF0E1/7FKCwHlrVNmfNHn3AVMN1KhT3wdtV0urIM0z+ShsesXpma4HAZEB2eSrivWKhDCbxphwkuuCMpwU25QWJzudL0IucTGzN4SptrNvVCgjmrcsy1OZeHkqn3wZUVNdsPdRFcQ9xdBIc/sb2S4Vj6jH8xCq5UNvFwxfA/sbtJFKhg6x/SbKYQiB9/FUGNMTI1wdGWqaw4to9ip5mx5EabTHDBKEkJ7ugqgwOaJTK5vclqBxs+LRzZPLi5/eC4BoOFTS+7/D5d18X/wVSvdiddpm70NXJqp9eCtBiMOIJL+VgsT6K/7LSx/2rw5qwn8MFPxkJ/tmti6yR2oUgFn9VB0gOk+Ad5IPDz5codqAORIx+fItdKAx5BVf/3Fflz+DcJIpSWYBFtpt+QLMEjgkXkD3b55doXhNjYp4+ldFPIHARHu7Asmaq29x+saS9jiT5yr8cuZ2tfzwQXoF+bJlJz47ZqGaJbRI3Jw9pXiu8Kx/shK8VSYRox5hePloQN0Wp+RYxgAuSzjxQHOGkyG1KIl3zARomGD01daPrNNQl+7JASocXK5rrkx+FjQ7k2WA/NA8thPBfBNdfjdxf2kxJxpm+MHzZyAFNeSPSRn0cEX0ibSP9YPKO+muACVExwucfC328XBOYmuKXgZIIzwS1lLLodm4hARHBcvv2zjuxYguuB3/CNtrffxOZ2XgqLkcwEpv1tN1LkChm73XtnY5ZewBbc0u+Q2zcWgRzBRfWWUprGtmOq8/v8qI8JbirUXY8RWCgCfQgu2kF5ad3KbUcftdMEt7S75/YYgYkR6ENwTU7ixE2YtLrcr5aZ4AIEPEWddOy5sgUi0IfgyF+MfjVtSd0iWlubQmMLbkl3zm0xAjMgQP4fK0BywmoaFsmzyzP7AG4FIceQFTmk2pSMFJLNP7QVOjRXG23BzYWs6zUCRmDtCJjg1n4L3AAjYATmQsAENxeyrtcIGIG1I2CCW/stcAOMgBGYCwET3FzIul4jYATWjoAJbu23wA0wAkZgLgRMcHMh63qNgBFYOwImuLXfAjfACBiBuRAwwc2FrOs1AkZg7QiY4NZ+C9wAI2AE5kLABDcXsq7XCBiBtSNgglv7LXADjIARmAsBE9xcyLpeI2AE1o6ACW7tt8ANMAJGYC4ETHBzIet6jYARWDsCJri13wI3wAgYgbkQMMHNhazrNQJGYO0ImODWfgvcACNgBOZCwAQ3F7Ku1wgYgbUj8F93Vl5yoT7eDQAAAABJRU5ErkJggg=="/></switch></g></g></g><g data-cell-id="IkmhDn_4ef8kqVBRZHeY-21"><g><rect x="87" y="60" width="80" height="30" fill="none" stroke="none" pointer-events="all"/></g><g><g transform="translate(-0.5 -0.5)"><switch><foreignObject style="overflow: visible; text-align: left;" pointer-events="none" width="100%" height="100%" requiredFeatures="http://www.w3.org/TR/SVG11/feature#Extensibility"><div xmlns="http://www.w3.org/1999/xhtml" style="display: flex; align-items: unsafe center; justify-content: unsafe flex-start; width: 78px; height: 1px; padding-top: 75px; margin-left: 89px;"><div style="box-sizing: border-box; font-size: 0; text-align: left; color: #000000; "><div style="display: inline-block; font-size: 12px; font-family: &quot;Courier New&quot;; color: light-dark(#000000, #ffffff); line-height: 1.2; pointer-events: all; white-space: normal; word-wrap: normal; "><b>stacks[3]</b></div></div></div></foreignObject><image x="89" y="68.5" width="78" height="17" xlink:href="data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAATgAAABECAYAAAAV6ClkAAAQCklEQVR4Xu2dBdAmRxGGL7hrcDuc4FJQOIe7uwcnOCRIoSE4wd0J7u5+wd1d/+Du7u+T+rZqa65npvdbve/vrur6776dHXln9t2Z7p7ZfXaEBAKBQCCwoQjss6HtimYFAoFAILAjCC4GQSAQCGwsAkFwG9u10bBAIBAIgosxEAgEAhuLQBDcxnZtNCwQCASC4GIMBAKBwMYiEAS3sV0bDQsEAoEguBgDgUAgsLEIBMFtbNdGw2ZA4MQq88zSM0h3rvRo+vsd6bek35ZuSf81Q922ZZFBcJvZ7ddQsx4gPav05EYTf6nfTrGZTd+jVffULwcV2vpPXfuZ9H3SQ6V/XQOXs+ieA6V3dtwL9neRvsGR1kpyLP14X+mVpaeSHqOQz3N07VFrlrMRty2Z4HgbXl76CelPNgLtaRpxUhXza0dRS+57R/XdSR6nlPdzpj5A6SAFr5xaCSHFm3lvaKV7j/59N+l3O94LOT7TeQ9toU3bVpY6yO+oHnluq1ceqX8/ZNv2UreG30LJX+a4Zal976h6pyRdCO7zyvlCztzPrnQfllozZGcWO5jN7Sf9rfcGpfuc9ILO9EFwTqCmTvZHFXj8pFBmJl0GwtR1Xkp551FFvuyoTBDcniC9Tj/dyIndp5Tuwo60tSQsVW9QS9S6/lL9+5bO9EFwTqCmTMbS1CKy8+v3L01Zkb24rNer7tev1D8Ibk+ALqmfPubo99MrzRGVdH/S9S9Kjy49lzR9Ybdvv7X+A3F5BFL9tCeh0gTBOYGaMhl2DcvmdjH9/skpK7KXl3UB1f8c0qtKrTf+diY4yOehq/79n/6yVMTWu+Xs832V7leZtDh3XmRcx578GKk163uLfr+Os2ySsZqhX/l7lNV9lJsul4PgOoA6VdIguGGRvomye5WR5XYmOGZpzNb6CJiCbSNfX/3/K4VMmcV9VHreJA2Ee4I+ldG9b5dePckjCK4nqGPcHgQ3LKpBcHt6UYcguOOom7DXMZP6qvQpUoiqJtjbsPWlcjr98OPazYXrQXAGOF3e4kyFTyndKT2j9CRSbGU/XymBjP/u0UHNrXMSHPa/M0lPttIT6S9xUVsr/ZH+Ejc1tBAMinPgNFKWP7zpfy8lPusXUgb+79YsdCkEN9X4SWGyvKhDENya3bHjerrRioFjVlea/dXKC4IzEPIQHG7zh0mvWUGYt9dLpN+U0on/kBKv847KfdgRCMS8yOrhPp7+QjKpYCeBTEtCHYgaf7LU40k8rdJdSXpx6aWkZ6uNIl3n7UvYiif/WnaUe3cpS4uSEZp83iV9hZSXym2kBHw+X/pO6X8KBXkI7qKreoA7MxNLwPat0udJIV+vjD1+avVYGsHlvKDHVEP6vDyD4IyRUCK4cyr9IdKaN642wK6oBO8vJHra6uGq5dPl+veVmCj+/2Zuot1PlN67S6ZJ2tfq/xDNOpHvLEcgJ6LR+woxg+SVkxrBHVc3MlOsEWyTP4SBQbsmU42fWj2WRHDEcvJMpfJB/YAToo8EwRno5QjOG0vl6ZBHK9GDMgnZZsJMbwy5jDIlENMSHr6vDVDoy5XHraR44rzCTJFZrZdQavnWPHA1gruxCnh1rZDWdWZyLOVLs8apxo+n2nMQHM8VY4zxfVQpHm12O+zKVPhg/f5wT2MKaYLgDHAsgsP+REQ3y7ch5IXK5PaZjLDLsKS0lqR9y2aAfSOTCSSTI7+u5d5LNzzVeRPLtc8603qTfUYJWd7npEZwvAh2ewtTOkwF7IHMzY6nHD+eak9NcFdRpTDNeMc0eGJ/w9baR4LgDPQsgrut0kFKQ8lhyoilXE7uqgvPGKqwVT7Yq65WyJPgy99Ia7MoZiu1NIQHEMhZEza3Y7frs7XHKqO2vahGcJdWpofXKt+6zl7IZxfSTz1+alWfmuBYGfBy9QpxcUO89ILgDMQtgoPcGKSpcNoC1z60IgeWKHgZORrmutL7SC0y8MTiYGxnpwKeWWYA9zDKf6V+w4FRkr/o4vekGN5rR9Jw4gbLAvb14aVklwRkAQnhzSKfxitMuyBM7IUWQXH9z5W6PV3X2VydExw52CqZ0RJEyvIGr/XlpHeS4giwpA/B3UEZ4jQoybN0ERsdLwTKYotSSeYYP6X6TElwuQiAXP2wnWJDHUKC4AwULYIjEPESSVpmMsxA/lboCbxvEMDtkjQP1P+J4PbK1GEizOZqZNjUHbL5gNEQ8Pp4oYEsVyBMSzAwQ2C1UyVyBLkuwfHiqR3vw0ug5gVP2zT3+EnrMyXBUTbhUh5vfFPPm+ofXWyguWEWBGcgYxEcb3Te7KngmcSozmkGdGJ7htOkxfjMdLuxP3DA3y4pMwCvTE1w7Xoxe2wOKyTWD9Lm6CHsIyhufGu7GMGe7y40kNktXttUWN5il/u7Axzq8gVp+vDUPHC5JWqpSPqa0JXajNnKY+7xk9ZpaoK7wqqv090KJbzxpr/XMQZKSYLgDHQsgsMhUAo7aGfDA8qGYoz5EBv7+TgJhIeW4FWueR7edp5TExwGc8IerGWxd8zVCI5l/S4jM5bHkJZXLPsW9kti6XLSleCYsbF3dd3A4rnHT4rD1ATXlM9xSoQDsTEfp9b+hT5ihcShmTgc1pUgOAM5i+CwqzFL83qB0mw/oh8YVNjBuoRPNPlMRXDMNomDG+KcuRrBWcc/dT0mB3wIgn6jlNhCBKw5ieIHhaeiC8E9doVHnx0pc4+fFIq5CC6tx/n0A7GTueXrg3Wtz+m7QXBOgiMZcTvYdvoI4QuckPDTjplMQXCEwEDiQ3k0SwTHjgPLdtlnQIMRS9aa3Q7ouxAcQagHS9d5MbW7ec7xs1SCo14EVRNSlNqpuYaji9neutgHwXUgOJIS+sDyZ1dHgmonp9OYnm91yGNsgsNTy1K6iyG4Vv0SweGcsbaYQTyvqWU8wPUuBEdxh0nx7HkdL7kqzjV+0vosZQbX1IvYT/bCWl5xxsq6y9QguI4E1yTnTLFrSYmXQmtxYWkxnD1P8KNXxia4N6si13ZUpjkZwtPeEsEx0yJ8JRUcD+yZHVu6Ehz1oc84KYOldV+Zevyk9V0awVE/vNNvM4DtapNtZxEEZwBq2eAwjGLXQTgZNvWksTkeDyOfR8Mwyp5PDqMszYgIr8DQ7pExCW6nKlCyV+Fc4VsQeImbuDaWmLxZcUZwv3W22jo2OOL6bu4BpGeaHMHhDc7F1lEk8YC0q6uJYe7xk8K1RILL7WhhAoFddR0JgjNQSwmOeC7imBphFgOZEeRZE8iOYFU+epIKhnxO4PBIjuBqsWaevLF7PcJIiL2QYOXa17uYzVmzmhrBccS0dZIrBFMLnM21i/2e2Gx4cZQ2/Jd2MjAzZy9rTjAxcNpKbstbet8Sxk9apyUSHHGPxCGmwqSBEJ11JAjOQC0lOCuYlJkG23P+4ECdjcWWB46vPLEp3SM5gruhbmZGWRPu52inJo6LgdQMGuphETDxb6VP7XGUDQGZELXlXa4RHJ+t40FLBXsLBvkusyS8v+TVxCryEuIQxVwcVW2rFiTLvbmlOPmzi6P94sv1wRLGT1q3MQiO5wbbMk6D3dJSAHxaH5ah3GPhTdD5uh7sIDhjVKYEl7NPMch5uF8gtexJdMxlpcSSpccmU2yXz/4dW+mtGQmGWexCFhkQPgGpsbROjyCCRDhIkoGT2w1AHBn7K9snZGAM3imFvDi/v+Rx5TRXAm7Zh2i9gUs7GcCH+/GubfGfjNBGiIzdIunDYR3geG6la7bRWV67dt9jZiBQuRQaxKECzHDpf2ad1oeBljB+UviGJjhsqsz4m/2mPBvYUnHI5b7TANbM4Dkn8f6Z/q2dClMYGkdeCoIzEEoJjtg1HuiSQBgc0fxDKW8wZkxEbZeM8cwA2ADvldySjvt3SzlZF8Hew9K4dvJJEynOLJBYJEtYjrHdCnLFMF6yT5XawWDHgZDK4/UDXyQvCdhCkLSPnRPMHE+4qk8tMp69q43nE+9s7fN3ad/nvL25+hIMzM6Wtixl/LTrNDTBYTdN292Ux84ddvhgv+UFib2aFyPjtOas6muCCYIzRmo6yC2QKs9k9TIPLEGOtc3o7YwIOM296aoFGgkaWxeDDeIYW5gxpjPN3FarIerSPjKJthIGU5O075nF8YB6xTpUdCnjp92GoQnuScq8z0GpFr7sHsGz2keC4Az00kH+YqXZvw/Kyb1M37Ex5Taa54ribcfWryFi1dK9mjkX/YDNPnK5zIBLBU8sS8HabKxrXfDKNYHZ3rCQtO9Z/lofQynVhdNO2i+MpYyfMQmOE649tmBvH+I1ZYXTZQJg5R0E5yA4AjwJkxhCiPNhFub1wKVl7qcfsPXUpvalumI7O1Sa7ofl2CLscWMIpM4MromjS8vAScAytgnF6VMHQj3Y+9k+nZjPz3kcQinBYeNj1unFe7fSYndty5LGT1OvoWdw5DvULI6jpbBt9iU36hQEZzxJ6SDH5nOAFKM7nkXe6Mw6ana5dtYQG+essRWqr7DrgOUA4R1eeZMSEquGza80cDASYxeznCJpWZAVgxFDcCmej1kUdfXYGwkJOEhaO7LIajcGbRw+nGFnCYHMHBNvhaaQnvZY3+Fkdst9Jfsj92KrPFCaHvu+tPFDW8cgOPJlZcLYxBbZRcCPZ4TTZfpuh2yXGwRn9IIV6Gt1FkTDBu+dUozRzeftiI/DFoNuSdkbuW4cT2mQUCZuebyCzXFGBOCyPEIJRsYxwekmXd3skACHbeKsYNbIZnGM/EeslDaxjOjzxaNS2/bVRci2HTiN44YjwTlmCs8lf1G2fDFrG+KNX6rT0NfmHD9jEVyDEc4dYhIJ/2CcMn6YpTMTxmHFM4LHmTAkXvqcsNN1jHr6IwjOQMlLcB6AI00gsEQExia4pbQ5CC4IbiljMeoxIQIWwVF822OM7RHTwxNWs64Jq9e5KGaMxJtiNmqHR1kOOYLcMTltW4kZ3Lbt+m3T8BzBWQBAHGM5n4YCvMtHfYLghkI98gkEFopAF4LzfiFtzqZa37zI1ScIbs6eirIDgQkQ6EJweDc5gGDJkvtqmVXnILgl92TULRAYAIEuBMcHY6yvpg1QjcGywFvrDcEKghsM9sgoEFgmAsT0cc5aTjginE3ybG/jHMC9QYhRJWaREKOSHZ1A+cP3hgaNVcdwMoyFbOQbCAQCsyMQBDd7F0QFAoFAYCwEguDGQjbyDQQCgdkRCIKbvQuiAoFAIDAWAkFwYyEb+QYCgcDsCATBzd4FUYFAIBAYC4EguLGQjXwDgUBgdgSC4GbvgqhAIBAIjIVAENxYyEa+gUAgMDsCQXCzd0FUIBAIBMZCIAhuLGQj30AgEJgdgSC42bsgKhAIBAJjIRAENxaykW8gEAjMjkAQ3OxdEBUIBAKBsRAIghsL2cg3EAgEZkcgCG72LogKBAKBwFgIBMGNhWzkGwgEArMjEAQ3exdEBQKBQGAsBILgxkI28g0EAoHZEfg/VlROcimshJQAAAAASUVORK5CYII="/></switch></g></g></g><g data-cell-id="IkmhDn_4ef8kqVBRZHeY-39"><g><path d="M 80 311 L 80 371.63" fill="none" stroke="#000000" style="stroke: light-dark(rgb(0, 0, 0), rgb(255, 255, 255));" stroke-miterlimit="10" pointer-events="stroke"/><path d="M 80 376.88 L 76.5 369.88 L 80 371.63 L 83.5 369.88 Z" fill="#000000" style="fill: light-dark(rgb(0, 0, 0), rgb(255, 255, 255)); stroke: light-dark(rgb(0, 0, 0), rgb(255, 255, 255));" stroke="#000000" stroke-miterlimit="10" pointer-events="all"/></g></g></g></g></g></svg> \ No newline at end of file diff --git a/files/en-us/web/api/js_self-profiling_api/profile_content_and_format/profile.svg b/files/en-us/web/api/js_self-profiling_api/profile_content_and_format/profile.svg new file mode 100644 index 000000000000000..2124d1622379c73 --- /dev/null +++ b/files/en-us/web/api/js_self-profiling_api/profile_content_and_format/profile.svg @@ -0,0 +1,3 @@ +<?xml version="1.0" encoding="UTF-8"?> +<!DOCTYPE svg PUBLIC "-//W3C//DTD SVG 1.1//EN" "http://www.w3.org/Graphics/SVG/1.1/DTD/svg11.dtd"> +<svg xmlns="http://www.w3.org/2000/svg" style="background-color: rgb(255, 255, 255);" xmlns:xlink="http://www.w3.org/1999/xlink" version="1.1" width="452px" height="297px" viewBox="-0.5 -0.5 452 297" class="ge-export-svg-auto"><defs><style type="text/css">@media (prefers-color-scheme: dark) {&#xa;svg.ge-export-svg-auto:not(mjx-container &gt; svg) { filter: invert(100%) hue-rotate(180deg); }&#xa;svg.ge-export-svg-auto foreignObject img,&#xa;svg.ge-export-svg-auto image:not(svg.ge-export-svg-auto switch image),&#xa;svg.ge-export-svg-auto svg:not(mjx-container &gt; svg)&#xa;{ filter: invert(100%) hue-rotate(180deg) }&#xa;svg.ge-export-svg-auto { background-color: #000000 !important; }&#xa;}</style></defs><rect fill="#ffffff" width="100%" height="100%" x="0" y="0"/><g><g data-cell-id="0"><g data-cell-id="1"><g data-cell-id="nHGAu0euJ4534aWflK35-1"><g><rect x="25" y="75" width="30" height="30" fill="rgb(255, 255, 255)" stroke="rgb(0, 0, 0)" pointer-events="all"/></g></g><g data-cell-id="nHGAu0euJ4534aWflK35-2"><g><rect x="63" y="75" width="30" height="30" fill="rgb(255, 255, 255)" stroke="rgb(0, 0, 0)" pointer-events="all"/></g></g><g data-cell-id="nHGAu0euJ4534aWflK35-3"><g><rect x="101" y="75" width="30" height="30" fill="rgb(255, 255, 255)" stroke="rgb(0, 0, 0)" pointer-events="all"/></g></g><g data-cell-id="nHGAu0euJ4534aWflK35-4"><g><rect x="139" y="75" width="30" height="30" fill="rgb(255, 255, 255)" stroke="rgb(0, 0, 0)" pointer-events="all"/></g></g><g data-cell-id="nHGAu0euJ4534aWflK35-5"><g><rect x="215" y="75" width="30" height="30" fill="rgb(255, 255, 255)" stroke="rgb(0, 0, 0)" pointer-events="all"/></g></g><g data-cell-id="nHGAu0euJ4534aWflK35-6"><g><rect x="177" y="75" width="30" height="30" fill="rgb(255, 255, 255)" stroke="rgb(0, 0, 0)" pointer-events="all"/></g></g><g data-cell-id="nHGAu0euJ4534aWflK35-9"><g><ellipse cx="116" cy="90" rx="5" ry="5" fill="rgb(255, 255, 255)" stroke="rgb(0, 0, 0)" pointer-events="all"/></g></g><g data-cell-id="nHGAu0euJ4534aWflK35-12"><g><rect x="20" y="20" width="60" height="30" fill="none" stroke="none" pointer-events="all"/></g><g><g transform="translate(-0.5 -0.5)"><switch><foreignObject style="overflow: visible; text-align: left;" pointer-events="none" width="100%" height="100%" requiredFeatures="http://www.w3.org/TR/SVG11/feature#Extensibility"><div xmlns="http://www.w3.org/1999/xhtml" style="display: flex; align-items: unsafe center; justify-content: unsafe center; width: 58px; height: 1px; padding-top: 35px; margin-left: 21px;"><div style="box-sizing: border-box; font-size: 0px; text-align: center;" data-drawio-colors="color: rgb(0, 0, 0); "><div style="display: inline-block; font-size: 12px; font-family: &quot;Helvetica&quot;; color: rgb(0, 0, 0); line-height: 1.2; pointer-events: all; white-space: normal; overflow-wrap: normal;">Samples</div></div></div></foreignObject><image x="21" y="28.5" width="58" height="17" xlink:href="data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAOgAAABECAYAAACLd3ntAAAP1UlEQVR4Xu2dBawkuRGG78LMrMCGmZlfSGG6MG+YmZNLsnfhC1yYYcPMzC+MF2bckMLMnP87TeusUtltT/f09DxVSaW30+1222X/dpF7998vKCQQEpitBPafbcuiYSGBkMB+AdCYBCGBGUsgADrjwYmmhQQCoDEHQgIzlkAAdMaDE00LCQRAYw6EBGYsgTkAlDacVXx68RnFZ178Po3+/lz8bfG+Bf9Afw8T/2fGMo2mhQRGk8C6AXph9eRp4os19AjAPlb8KvE/Gp6LotNK4Fh63V/MK1+i37unbcZmv21dAD2VxPbogYP1ywVQnx1AneUkPL5a9XvTsjfp9wGzbO1MG7UOgF5goaaOJZL3qaLrif80VoVRzygSCICOIMapAYpd+TnxyXra/v3F6os9etyKfn5UZbbE/60oG0WmkUAAdAQ5Tw3Q16jNN8y0+8G6/jIxjqHUCXRy/T6T+OLiJxT6fAfde/4IMokqxpFAAHQEOU4J0Jxq+w7149biX1X0hx31FWKcS5ZQcU8k/ndFPVFk9RIIgI4g4ykB+ki190DTZhw9Zxf/tqEvR1XZF4lv7jxzSV37RENdUXR1EgiAjiDbKQH6JbX3PKbNN9HvVy/RD7zAP3Wee4SuHbxEffHI+BIIgI4g0ykB+ke11zp8TqdrP1qyHy/Uc7cxz3LtdkvUd3Q9c2ox9u7fxD8To3KvMiHi2Kqf/v9vIQMbM8x143i6cUrxMcS/EaOF/HOJPpceObJunkKMUw/HG34BZPKvhveMCVDm6QnEOBcZH9rxi0XbGppULHqURX8ZE/qPVod8fzLye5raOxVAmUwI1hJC/0NTi48ojN2KqpsS9uw1Kuu7qMrdVXzlxcB7jzE47xID/E9X1vt4U99X9ftJi2dPor93WbzXerIB2ovFOMKYGCmdVj/oL4sPC4klQk0vFZO8UVpUWIDubB7mmW8trl1af+8rvrbzDmz814mJO+OJ76OhAAUwtOM6i7+eN//jukfywxvELWZS1/aT6h84J68uPkumQ/Sb+hmbj/R1euz76wYo4Hjvkp0iLRCVNqVP6cezeuoja+lQcUv2ElV+XYynmElRIqspUP5S4luKmUw1dBkVInQEeQtRro736Aa2+a8zBWhHV29X5Bb6BxMQoHrA9Kp6ji4C5L8WOjMEoCwUzxBbk6gkO9pDVlqNk/CYKncP8eNqBiMpQ6LF7cV2AW2spr74VAClRZ6Ky2Rh9ZoqyeCcetcnxTWx1ZwUL6Ibny2I2APoW1T+kPphOVxtZXKyILTa1ID0amIvJuwBFC2CRI/LN7SPoiw81xT/LvPcsgC9o+pjAViGGJdriVHJc8ScJ9x3g2VeoGe+LL6ceJkdu/mVUwL0Q2rdltNCdj1W8e82t77tARxLqKmeitjVxELRB17KnFv8w8zrvYWoraXDSyPPlzvVeAAd8jZU3lxcexmA3l31sQsOoc8v5llu0X+I7pNmmqOaOYBjEwfnymlKgLIbPLfQo23de734A+JvrqDnT1ad93bqfa2usbuxQHT2MI6YK4rZXbydBVsQu9SjPoAygfaKvyJG1SKme1Blf1H7WGR+LMZRhLrltY9d9CpOnTUAfbqeI2Fkn/hIYk4Z4YzjXR6hjn7MudEKUHwCLNYevVIX3ypm96JN5xdTnsXBy0pjcWKRsnRiXfDUfxYa5sAXxajI2L8s5IwN88Zb1C+o64zlSmlKgB5HPSHUcoaKHqHiYZtilDMhsf9qbItS1ai21u5k0r2g8BCTYa/YDnbJW1wC6EMXE8H2BZvzw4V2MHGxRb2FCzt8j/MsSRtW/SwBlJ2DODILh0dMVhZPq2GgViJXq1K3ABQn4tfEdm7QJvqNjezRLl3ETPIAdF5dB9Ap3Vg/sLVTwi/AO/Cme8S8xQF3XXMTNdw63DJVLH95SoDSytwg1/SAXYGVelvMhG0B7NFU3h5Nq/X4sptaTzNH3jjD6lEOoHgLS04JForbOhUySdnFco4JVnvOydpJSubWF0x9JYAyNn3e2dzzN9WzduK3ADTnQPP6YEVEWIR5YfsP8Habwnv1+1bmGotLn4eeHdvulp3zLzMNxrk8NUBpNZlDqLLnGNCFzvWNwEs7T/cKT8CsmjxfQ99ToXR1Z4cnZOGRB1DCNQC65PX0VnfqB7Q2nGTfi5punR5X0rX3m4I5gHmTOScXL5/6bSqMcyalWoAyBwlF2fnAYsaiVkOXVaFtU5A5Qhgv3dnRAKxJcFVde3fFS2yiDQc6iCSslNYBUDqE6oj39oFi1KohRJzyAYtBztWDnWLtT+J5tUkSFnStAMWGI45WImxe4pmWSKLoS0RgMiPLlAA8YEopB1BPHcy1lR0HcyElT6OoBSj51TyfEuAiUaK0oKXlmcf4EKyKbPvlLWSo6NjrfV5ZwM4h9I7+XvFMTobV19cF0LSBZKtcQUxMFND2eVFznfN2jGpBZAqSUXIv8RPN/VaA1jgULqR32PANOy/y6SOcTA83hTxPrgdQb6cpvQ+Vmslsx4kc6dTsqAUo7cTGS4lFl1BRC3lOQLQKtLWOcPrhaLPEAnGg+O1iL6GmpR2jlp0DQNMOMfiowMQaLyHeEtc4lbo6zqV/4GxopRPqAYAAY9PA2H2oTp6XsBWgqMM8UyJPDc95Y209QwBaCpXk2vtm3bBJDbt0LQ091QIUr/HdzItwwj2scRBx+Flv+P10rcviojrCY9ZxZF9DMgIhQWxMyrb4Ohqb3F98bgD1Wkz8kh2WFbVvh0WouP1zHrmufsDAbkK92CStu3YrQFHpa9pkHRGcbyU81UdDALrMAQMPVATvt5OG1gL0jXrGekj7+lt7n29XEfdM6UH6wfUaQrvAPsX0eKfYO6BRU8/SZTYBoGnncMffbCH03M5a8vxh1DO5cAwMoRaA1joTvB201pU/BKCo8E9tFMYelbdplqQYcla3o1qAEkpjUV0FofaSAmipBaTps9v6wY5MBKBvwR2lP5sG0K7TqMKsvKSaWcIW4+yppZZc2PRZVB67wrcAlBguKYZ9tC6AEnawNmBfW9mBmOQpkTSAutxRLUC9Y4h976+9j71JdpJHpFKiAnsJDX31kzjBcyv/xM4UAMWes4DBKH9UnxR67jMBUAntTkoWDGBMqcb2wCGD/UpI5TtiskqwQXCIDAmzzB2gLeGmTqbImB0zJUwQnDsd1QLUSyChjlxWUcu0ITzV9xkcTrTgQaf92NW15g47KQBfKU0BUOJ/NgOmtAO1dBjVjFMJKX1QP7AtO2K3ZZX24q44YTj9gu1aOqGwkwFqHSk18icxwIbH7NcsagGK5xTfQkp9GV41bVymDHjASYnKTVSAQwQlIt3wM8u8qPaZKQCay3/0UtFq292V8/J7t3UTh0VHeHa99DXsEyZnjS0xJA469x30KZKBl6NcGgsOS1vvNhlXaYJ6LUCJD+82L+NMrVWhW+fGGOXJQNsSY6d7fgvCNn3HGwe1YwqAEkv0XNW5ExctHeLw8zPNA9gHOJI6IhZGgDol1Ce+ElhDBKft1w52kg1aSlv05MMOw6KTkpf2VgtQFgcWy5SWiYOSqng+Uw9Oqy7ZgUPvxNpTIkaaOy6XlgMnnLKx4aC9uoaJsDKaAqA0Hle1FQ6DzO5Ws4PlBOBlhljbYI8eth5HvlpA9lENoeakwW6e2UkApT98TQC7u4a8Hc8L1dQCNHeKhU+tYlrUEN592m/zcfFPkKcMeQkRtWl+PO99B2vl+bhTATSXwQFISt+6LQ2Ol3JGeetN9NLgalUojoNhbxG6SWmnAdRzrHmy35VM+PT+ln7YnOhagKJGcgTMOmdqQ0y0455iVPWUrJaE1xZfREo4KmsTItiB00QM6rHamiezQdemAij25j5nEGg8+j2xyRaXNcezcC54Hjeu/TmRirdyMng4AkpZIoBzr9g7kLzTAIq4+PYPX37IEb4EQk5ezBIzwKbI1QKU93EMz/Pqb+m6Bb5tH84/xtPOBcwf8q07IhXR5jRjM7NT92V5UQfqLfM0JfuOgviWuzUVQGkdQDw000xyUMmF5GxfLheSdDzCJXhtc941T3X14os0A2HfX2yPoeH1xe2Ohzj3ISmezyWxW4fS3J1E6ZCg6XDszU7ks+kawXkvOYREAGtDUmcLQAE/qqi34AIM62egfubuncSek4aQGXPF/udNnqkFOG8k3k4Fkfyb9xAr9g471ByHy1Rbd3lKgJaSC9LW4iBAlSD+iGeQFRJb1cuJTZ8DCCScW4CjQn1D7E0uBpJVlsnBuwAk8b2+d/FejliRBUOsNP3w2SYDlH4xYTkFw+RmUcRG9L7kT1l2VBZLz4/QAlDq4muMyNQjHFl8kLxTUQEfqZq5BRQHoBdH9dTc7n18xoS4OrYsnxhF62PuESnw3oO2QQLLEB9KprtHXJ4SoLwVVYhVbOzULgR7gNjaCF1PSbzv+xpfTlhMWALeObc/jipW4I42HaC9k2ZRgBRGFsScF7QVoFSbU3Vr20S53I7e1eFlQbXUT1nmBOBd+df9pgYoncMWIB0PlXYMOkSV7BH3HRPq+1iU1xaSHvj+EDZtzk7ZdIDiRCPJoGXRRBacobRfbEhluAxAeZ6zs5xmWYZQeZ8nLu1qbBJ45ZfNx6bvZByNkenU28d1ALRrFLYhMbBlciFRK4lLoYqlDqG+DpPAgI3Vd4StS0Xk41PdYBNb5bclC1A+6JW6+2tjrth5qOIpYbPfp69Tuu8lf19f1+23fLzzoOxahKYOFteEngipUL7vS/h8Od+OTa23mN2JM7i1IEI1ZgHmyww1xLzn856pE6nmOTy+2Nu1B8lr6iyWWSdAu4bxdTq8sqihnAPF/iM/EocBXjZsAmxE1Fe+gMCE7/uGTKnTeGexd0hgxybhhAv2LvXzHrzDh2UqoCzhHf7iXOL4EY6tnGpdFP4abuYA+phFW7C7+JwkXyLYJeYcK31j4mPjc05yyiNXJEWQBsjcYNFjrrCDsQjCtAk7uPQd3JKY8Tswnpz7hamfuQcx7/hKA7FYGNNsyr4f3og5ADQnQNq2UgO8NHI79F4fQHdotze3W3MG6OZKdb4tD4DOd2zclgVAN2zABjY3ADpQgFM/HgCdWuLrfV8AdL3yb357ALRZZBv9QAB0w4YvALphAzawuQHQgQKc+vEA6NQSX+/7AqDrlX/z2wOgzSLb6AcCoBs2fAHQDRuwgc3lC/f2P0gim8uepRz4mnh8LAkEQMeS5ObUY8c8kkFmPHYB0BkPTjQtJBAAjTkQEpixBAKgMx6caFpIIAAacyAkMGMJBEBnPDjRtJBAADTmQEhgxhIIgM54cKJpIYEAaMyBkMCMJRAAnfHgRNNCAgHQmAMhgRlLIAA648GJpoUEAqAxB0ICM5ZAAHTGgxNNCwkEQGMOhARmLIH/AyxWanIdOnFsAAAAAElFTkSuQmCC"/></switch></g></g></g><g data-cell-id="nHGAu0euJ4534aWflK35-14"><g><rect x="173" y="156" width="30" height="30" fill="rgb(255, 255, 255)" stroke="rgb(0, 0, 0)" pointer-events="all"/></g></g><g data-cell-id="nHGAu0euJ4534aWflK35-15"><g><rect x="211" y="156" width="30" height="30" fill="rgb(255, 255, 255)" stroke="rgb(0, 0, 0)" pointer-events="all"/></g></g><g data-cell-id="nHGAu0euJ4534aWflK35-16"><g><rect x="249" y="156" width="30" height="30" fill="rgb(255, 255, 255)" stroke="rgb(0, 0, 0)" pointer-events="all"/></g></g><g data-cell-id="nHGAu0euJ4534aWflK35-19"><g><ellipse cx="226" cy="171" rx="5" ry="5" fill="rgb(255, 255, 255)" stroke="rgb(0, 0, 0)" pointer-events="all"/></g></g><g data-cell-id="nHGAu0euJ4534aWflK35-21"><g><path d="M 116 95 L 116.04 171 L 166.63 171" fill="none" stroke="rgb(0, 0, 0)" stroke-miterlimit="10" pointer-events="stroke"/><path d="M 171.88 171 L 164.88 174.5 L 166.63 171 L 164.88 167.5 Z" fill="rgb(0, 0, 0)" stroke="rgb(0, 0, 0)" stroke-miterlimit="10" pointer-events="all"/></g></g><g data-cell-id="nHGAu0euJ4534aWflK35-22"><g><rect x="172" y="131" width="60" height="30" fill="none" stroke="none" pointer-events="all"/></g><g><g transform="translate(-0.5 -0.5)"><switch><foreignObject style="overflow: visible; text-align: left;" pointer-events="none" width="100%" height="100%" requiredFeatures="http://www.w3.org/TR/SVG11/feature#Extensibility"><div xmlns="http://www.w3.org/1999/xhtml" style="display: flex; align-items: unsafe center; justify-content: unsafe center; width: 58px; height: 1px; padding-top: 146px; margin-left: 173px;"><div style="box-sizing: border-box; font-size: 0px; text-align: center;" data-drawio-colors="color: rgb(0, 0, 0); "><div style="display: inline-block; font-size: 12px; font-family: &quot;Helvetica&quot;; color: rgb(0, 0, 0); line-height: 1.2; pointer-events: all; white-space: normal; overflow-wrap: normal;">Call stack</div></div></div></foreignObject><image x="173" y="139.5" width="58" height="17" xlink:href="data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAOgAAABECAYAAACLd3ntAAAQlUlEQVR4Xu2dBbDkuBGG78JQwQvjhhkrjL4wM+OFmbGCG04uzJy8MDPzC3MuzMnthZmZ/y83utL2tmzJ9szZa3VV15vxyHKrpV/qbrX89t2nUtVA1cBkNbDvZCWrglUNVA3sUwFaB0HVwIQ1UAE64c6polUNVIDWMVA1MGENVIBOuHOqaFUDFaB1DFQNTFgDmwDocdT+y4gvKT6Z+OTiE4n/ttLLr/X3p+JPiT8hPkj8jwnrrIpWNbAxDawToADyfuIrFrbmFyr/ePELxb8tvHcTxT+gh1wqehDynth58DF07c/m+kv0/YBNCFmfMVgDF1ANnza1sNDQ/xujdQD0FCuA3WBgK/6o+68nfvfAesa+/fOq8LymUk+PWA6/M+XepO/XGlugWt9aNNCo1g+Zmq+m729by9MSlY4N0IvoOR8fuQEPUn2PGrnOIdUtCaBnk6KwgmJ6sTNwh+hzqvfudQDFpN3O0Pb3VebH4n+LTy9mxe2iu6vAU7sKbej3JQH06tLpm41e76XvT9qQrg/Px+xVAD2fNPnZFm0SAHqm+D3iX5pyR9H304nvKr59Sx34slMwdytAK0A3NnGMYeIeXdJ+UXxGR2r8yDuIXyX+T0arzqAyTxdf3in7I107i/hPGfWss0gFaAXoOsfXbnWPAdDHqcb7OhIT3dxf/PXC1hD93Baf37nvgbr26ML6xi5eAVoBOvaYStY3FKCnVM0/SNTOivqdni1hv5T9UPZLY2IVPY34Xz3rHeO2CtAK0DHGUVYdQwH6cD3lwc6T8CWfmyVButDt9NNznJ8vrGv4tCV0VBUmGMV+5V/FJEbgCxOoKqU5ABQr5NRiJtC/i38jxqL5eWFj1xEk2k8ynEqMa4RM9IXdLy4Uc4/iR9KVM636+wj6S//vEh8iznWRGpWd9TYLCqbDj2XU8wV9J2j034FaPt5qYNlqcsF/Qd14JzH+rF2JQ52syO8SkxRhN6VT4k8VoOeQwEyWRNNT7f22fmMf71lioukeETNgkx5im8W6GtRBxlegl+qDHchxvcfWl5uKbym2+8ehHLGKr4m3xK8R2/3jhKh7XEYHdxbfUGzHZSjMpPAiMZFoG7CMK2ycduXug95D957TEZpEle3cxlBuyAp6ad3/fudht9W155cI0VKWyO91zO+s2lxP0YX0w5PF/C0hfGVk79rHnRpAcQd2im9T0liVfeTqPmtFvFPXS7K/7qPyT3CezQSOXF58oktUAoVs5/yzq+DqdywG2gMwSoh7GE/ecxpd77OCPlb32b1jZPqy+LJiJohsGgJQEgge4TyJla/vDJgteKIgM/4nxanZM6d+Vo+2LaMpAZR2fk7sRdBz2spKwqQUg3QMgCIX+6dxSmSOPHGZV+rLzYxsXh2s0G8RN6UPWJUnrdSbRKivBKBgibqYWCxhVV5OTN55EQ0BKHuSdjuE1ediRRKMV5iVBDO1LfEBU6oLvJTBVMJf8WhKAH2FBLxRiwpz2mtdhjEAigmNqdxGObKlwBPqxdfcFl904DDC136rqaPR91yAgqMnir0VnMkenPTKKx8C0D84gx3T8p4DldX3dnwKT0Gv1fUDxd8V/35VObMuic/4qN4sf2tdxy/1aCoAvaaEe6MjICYWATomGOIAmH8EZa4s9kxRTC4SRULw5Dyr8lSNG3MX84zX6TsTQyBWhx9G3zmthG9vKeyJ478S+WfVBmA8+8ZissXs5Jk6iBDqTllxPOsxYvoe2ciL5jk3F3vJMJQnqBaDqNH3HIAShCLLDd/XEsFM3IXeFmVfgB5RD/W2OggGvNwRdBOXMG2t34lf9oKWh6PcLTFyxwQ4AalHUwEokyGDOqZb6Qtma4p26AdOY5zWFCCo8mrnpj5RXCa9Z5i6WEWuIf5Ji2wEkNCtJbbVdjnXSWohYGWJa0ws3iRBWQCDlWDJrqKNCnQBlPFDWz1r4aO6fhUxC1lv6gvQVIQVJ9gLHPUWMPNG0gXZTojpHSsFdVXBahpW1lCWTiZM79FUAOpNSEeWwF17xKyITzMNI5bwEKexfQDqTRxE1D/T1RH6nUMRDzDlrq3vnqWASelZa6yEqb35ULUXyMECi/3HRt/bAMoi9WyxF5z7oK6ju9wtnaRq+gJ0h2o82Km1zx5lRr91FsEsw9SK6Rb6stV556EFvieOV5U202oKAE1ZMMdVO+xkY1VwQl2wkURWT1ZRS30Aan3YLjM1fiZHFEkLjQmzlK2cmDDbfya2JnFuppk3KRNlPVf0kEafUwBF/88Ts3Vk6X26gLXwF+e34kt9AcopFC9LiODKV4ulGH4D+37W/2R265pJw5OtPz11gGJa4dfYAcqguaO4KwEDfeH/BeLtFiQzWOoDUEAWD3SsEY6o5RCmIgGmmDyAXlwFPuJUeFJdA7g55AU54wmuUSUeQNk3x21CLktYbdcVkwwzCvUF6An0dG+Tl2havIk9ipBrrISZED/OBk+mDlBU8nox5p8lTgxhsmIC5xxQaFNvH4D27S6i7x8WW//YAyimqO0z/NyQYJEjw1lViIUmEJMaAAvU6IMFKPomOHcT5wHcy559eJVPjgydZfoClNnX29xNBRs6BVlzAXxm0t5gfBSY4EMq62YOAPVWm1iNtOHtYgY9kyZR7FIaG6CMG6K8cT/s0HfAktoq8QDqbS+RRUXiwVjUqKK2DCn7HHx7GxwbLEtfgPJgb5sFB5/w9uFN+KTsxxLNYxula+/TyjsHgJJfSlocIMohopokD2DaAdqcAMZQgAJITD426XnbRp+ECg+g9r1QtH/sxaFRnSUARQYmnlT0OKeP9igzBKA2sELlpPiRmTIWEQyw0VSCIKk8Uva6SBMrSVXzZJ0DQJG7FKRxWzmIwP7dN1s6awhA2WLgKCKr4xDyAOoF6sbeQegDUPKcydcdjYYAFPOJze+YCC+zao1FXlSPnFlS+iyRFkYycinxIi/8ipjmAlBkJmBEP2DieWdou/SBqeydGuK+PgDFnSD1jkBOCYXIsk309wBK8oHNGOOAhrePWiJDXLbRl9IVlPsZs1g2o9AQgHqOOkIdX9wrrclpEeF1m0RAdJZIZUxEjwmTtxGmBycmWPmJQPMWCO4hejm3bZZUO/GrryC+qrjEivBS3XhGKUAZT28Q2wnPyktAhz7AEqJPvrT6ThDGJkx4AOUeuzIzIXysYwyU/NyocAqg7PWSZP8tsZ1QyEoi0PWrkoelyg4BqPfeUJ4z1lv48F8Aj/Uf8WmIYAaiHB3smVJENAnbkyPclqi8twA07meSN8jOIRAGaBlwbUR5G/grBSgpe14mGYOWqCvgZVCnkimur99yAMoKxStZY9qUDxrHWVLpli+TYFh0g2kIQMla8d4AT2dgfgxKcdL9hLJpqCUOXccb7WfX96845cgMubeYfNQumts+aFd7vN/Z48M/4iiUN5mxd2mtkFKAesChr5gk2nzdIC+pijY101tBH6ZyNvMpdewtpSuCVlhegZg02K8NW1ONPtsV1Ft8PFePOkd5yd0QgCIEOateNgXHdziJ0JeYzVnVrJ9hsz2onxWVpOiYSFImqymHCETZE/1T90HJOY4HFxvjuTnQJI4TybV5yx4QSgCaSp7gJMd7czpCZbw3dHhyeZN3aYCG1EPrs2Otheh2o89dubg0C7fCC1riUjERsmD1pqEATSUsI9SZxW3J0W1Cp04psCKSgxnTTn15qLnWdUwpLo7fE5vM/DZ1gHoTI+lruYPBC76hQwASUwlAU8kr8aBv63PGIqus3YrxAJp6QTq+38EZaPBARYoe20GBGn3IASjlWb0PdJ5LzvPdMuRJFhkKUCreEntpT6R4XUJc+h4cb/DwHHJtmfWtn+QlPhPev3+GYjj1T2DBvopj6gAlSGbfKlGyUnkrENfiY2SorwSgqQMUbAXl/DMszxJCBg+gR9N1gkzWwuKNj+TjdhHH8ex2IKmiT4lubPQ5F6BYfAeJPddhUHbdGABN5eXSVpZ+jh/lvHAanxZQ2Vk86MzzkfiNKK9NpsbEJarXdrIDcG6JbbCBOqcOUCYqUvli4ngTSRldp1noc8502jRBtq7sK1I9gJKtw5aOR0zGNqp5JV0jf7WNSCpBfo88gFIuFaMggo1fmKLUcTNiGUSHAzX6kAtQ7gGIXhSZhYqx2ysFcAyAIhz7cG1KoYN4hYX3ZvmT6Dr/UAggpza1PfMrKNI7ycJvJCxgethjaER9OazNJn1bZktq5p/CaRb8Zu80B4Oc6OGuaKDFH2kTWwTe+UXvqBrBnW1TF5MugOJtfJY4Fma3WDC7Ke9tg/EWDI6Mea8JCXUzaWMRWSKPGqvKezkXb5kgGhwHCClPuxkXlrwX3TUqVAJQ6uSwgnf8jKDWTue5nZfGAigP8g7qegLQYeEEPqlRXWl4JD8w66XMJMyLb4htkjXPxlFn3xS/BB8NQDLzpt56F8tL0IETEwysOMgxBYAiJ28GoG0ekROKP4cZSISayDdBM0xjT99c9+oiMyuVw4tuOVLFtgPbJ9ABYiKhHhGRZ4XhHoDZiHP2arFmSKQgeINpGu8O4DMy6XvEOGPssCryvFSqIeVwcWw7ka8UoPvpHsaap+OUBZgQ/9DLYwKU+nCIYzu+9eEZP9KpzEh2FbS3poIGGY/4vznLWwhSPisRYvbnAk0FoKwIDPjStxdanTARYcp621FYGww46+vFdcTbG4wn6rMZZjn9QBlWSs7xpiZQ7zhj6uB27jM5u0nmk6VGF0oBSh2pjDaSMxinXS7IbnKMDVAqJ3SNeeGtaLlKY1bDzyEKlrOPSb3M5KX/ppAZllebMDvHe6uxnFMFKDISKSfxPcci8HSPrw44U23nni7LyO4/ciaTLK1SmcIq3gY4D6CMYeIWRP5LiDHGdmAqzbHRb30Aijz0iZfqiClf9J/h1gFQlIQ/Q/AF0JQkS6M0fASyTvqkC+6v+9jo7poccNwJdrB3GCaAVBaMBShmb6z8VEDpmCpnT4yMlmESjUQAgdXiBbtSAxaZsXZoW9eZUcYI/3kuZRl5CQK4EzvFOe+p3VI5kg6C20OqKG/Y846ftb0QAEuCCT0nH5mVmm0R75B60BmvabH/wSA3IZ8xHwecQp2Mb6LdXQfqD+u3dQE0PID68fvYbmF5ZzDBdALKIdDAYMGHZB+KUHW28Ie1YvcPRGc5SUFUkgACfhTPOkSMuUYwK5VUTVk6mr+Y1fwfUwIv3Dt1Ym8Pnw75aTsrGEkJEH50yH3lLwAofSUHfhUReyY//H4GG2+soO9SL5hG/0xmoS/oG4DIfbzPF9PSe0UL2yiMl3OLmejwO0nnJGWz62XWyEhqI3Jy9hRXAP8SJvkF4LRZDPp5OrRugE6npVWSqoEZaqACdIadVkVejgYqQJfT17WlM9RABegMO62KvBwNVIAup69rS2eogQrQGXZaFXk5GqgAXU5f15bOUAMVoDPstCrycjRQAbqcvq4tnaEGKkBn2GlV5OVooAJ0OX1dWzpDDVSAzrDTqsjL0UAF6HL6urZ0hhqoAJ1hp1WRl6OBCtDl9HVt6Qw1UAE6w06rIi9HAxWgy+nr2tIZaqACdIadVkVejgYqQJfT17WlM9RABegMO62KvBwNVIAup69rS2eogQrQGXZaFXk5GqgAXU5f15bOUAMVoDPstCrycjTwP1ebkXJ/SRbGAAAAAElFTkSuQmCC"/></switch></g></g></g><g data-cell-id="nHGAu0euJ4534aWflK35-23"><g><rect x="301" y="196" width="130" height="80" fill="rgb(255, 255, 255)" stroke="rgb(0, 0, 0)" pointer-events="all"/></g></g><g data-cell-id="nHGAu0euJ4534aWflK35-25"><g><rect x="317" y="222" width="100" height="30" fill="none" stroke="none" pointer-events="all"/></g><g><g transform="translate(-0.5 -0.5)"><switch><foreignObject style="overflow: visible; text-align: left;" pointer-events="none" width="100%" height="100%" requiredFeatures="http://www.w3.org/TR/SVG11/feature#Extensibility"><div xmlns="http://www.w3.org/1999/xhtml" style="display: flex; align-items: unsafe center; justify-content: unsafe flex-start; width: 98px; height: 1px; padding-top: 237px; margin-left: 319px;"><div style="box-sizing: border-box; font-size: 0px; text-align: left;" data-drawio-colors="color: rgb(0, 0, 0); "><div style="display: inline-block; font-size: 12px; font-family: &quot;Helvetica&quot;; color: rgb(0, 0, 0); line-height: 1.2; pointer-events: all; white-space: normal; overflow-wrap: normal;"><div>- resource URL</div><div>- function name</div><div>- line number</div><div>- column number</div></div></div></div></foreignObject><image x="319" y="208.5" width="98" height="61" xlink:href="data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAYgAAAD0CAYAAACB1LEoAAAgAElEQVR4Xu2dBbTsuLG1/xeYMNMEJjlhnDDjCTMzT5hfmGnCzMwTZmaa3DAz84SZ88Lw15dpr6tVKdnlBne7vWstrXPalmRpS9aWSqXy//w/iRAQAkJACAiBAIH/ESpCQAgIASEgBCIERBDqF0JACAgBIRAiIIJQxxACQkAICAERhPqAEBACQkAI5BHQCiKPlWIKASEgBCaFgAhiUs2tygoBISAE8giIIPJYKaYQEAJCYFIIiCAm1dyq7AgROIKV+S9Buc9i176wYH2eYulv7/J4nP2+WyXfI9v1/1vwmST/uYUfWviZhc9ZeJuFj1n4R4+8P21xz+7iX9p+v6tHHoragYAIQl1ECGw2ArVB+XyzQXWR0h9kiW/sMnim/b5NJdOj2fXfL/LAlrR/sHsPtABpZYji2xbvFC6/q9nv16+ofJPMVgQxyWZXpUeEwFQIommSz9g/V7Hwg442EkEM0IlFEAOArEcIgQUQmBpBABWqswtaYFVRExHEAp0qm1QEkUVK8YTAehAYA0G8zKBhT6FLGG+OYuF4FthDOU1LgjZVF8lEEF1oL+G+CGIJICoLIbBCBMZAEKe2+n9rDgzOZGleaeEMlbTHtuu/qdwTQcwBeN8kIoi+iCm+EBgWgW0mCJA8roV3WvAWSdy7uYXniSCG7XDl00QQ68NeTxYCGQS2nSDA4KQWvheA8Ri7dg8RRKabrCbOmAjiRAbBCWZLzkN6wIEdOTrPw1rYx8KPLSzDlrssAi/xySzsZ+GvFn5tAVtv7LyXJSe3jE44q0tT/l/Y76/Nnrms56wrn3na95QzTI5hf/9u4VcWGGh+ucRKDNF/2oo7BYKg/rwrx3dAvMp+X7sCjlRMS+zktaw2gSCYIZy+KOCn7P+nzX4fy/4+3ML1LWCDjWDZcPQObBg4rmPhWhbOHMRl8KbzvdTCxy38ew6s97c097dwkaBjN9l9w/55s4WnW/jOHM+AdG5r4RoWvM13mR2232zqZQ8JXcbi+heP2dpXkmW87AzbMvp97Qfk62XZ7QvZ38ECfaINE9r3wRa+nKxTGW2I/pMt1lQIgr0I3tdS9tiPi1aAEkFke9AC8TaBIPyJSPSRDGAXs/ByC35W0UYQkMi9ZyELy4ctIrpOZuIZYaZ7oIVbZCIXcR46S/fPRLrDz+rwoETcMgp1OcBC14bhAyyOzxvb8zcmn0da8ijl3Pbjk0H6ZbYvmHPSt5ksZIqLhc3dLUTk5dMP0X8yZS7jTIUg2Gu4qQPntfabyVEkIoi+PWmO+JtKEA+zunygUp8aQaB+YgYdrRgy0NzaIj2rIyIDCCucNvO8tiyebzdvaaGNJI5k95lNXTFT6CAO+DATe0dL+nUTRN/2pZ8+ygID/TyCGwdWen9rSTxE/5mn7FMhiI8aOOd1AD3Bft+lApoIYp7e1DPNJhIEqhjUCLVZYkQQrDLoYG0qhww017NIrFpqgkqKODWhbF2z2zYiOoylf4sFVDhtknlOmyuGdRLEPO2LmpGV4SLyeEt810oGQ/Wfeco/BYKo1RE/UY262WMngpinN/VMs4kE0VYFTliyAVzqJakDqpFoxs1ewyMsfNYCm5cQCKqQXQs49ooE2+xIb31Vu/66IMEj7RorD/JnL4POjlXG5S08NohPmdBx/zG4h279ycF1CAF9Ovsl1IW0R7RwcQu3sxARCs9hNRVtlK+TICqw/+dy1L7M/PdUEj3Drj/HAns9kCvte4kK7mRBv/F5DdV/2urddm8KBHGQAeB9QoHJiS3UVIMiiHl7VI90YyCIe1l9GJiZeUaqmZvYdVQ3Xti4RWeNZUsk0SBJvFdb8JtlXGe5eyeX0c0qz26i7dg/77XgVzbXtWuvcHnVTP0Y6BnYahvItCHlYobsBbUM+HnZJIJoa9/DWcG/a+EkQR3Yo3pf1LB27VSzez5dtIoYqv9Uitp5eZsJgoNwqA2jPsreEYYINRFBdHadxSNsMkEwMF7JArPmmtQGkNog7/O5n114SJB5dDI00pGymdzleTJaFfBMv8mLXv4+rixggE+abyaa+kkW53+DeMexa6y6StkEgsi0L+0fbZxf3a5Hq7myjqzgUNeVwgoFFw+NDNl/Ek0YRhkDQTCh6jKMoHK8L/tagLhpB/bjIsFtx7ks/LQFNBHEvD2qR7pNJoi2GWJTRSxvvHtf1DGns5CxWiEfZqG7DjO/T8AZiogIjmnXf9eBN/spDIalsHpgFdEIG9Oogvz+xZ3t2hOT7clAwgvl88Dcl03vUjaBIDLty0a7VwW+265dKonJhyzeBVxcTu42q8qh+k+yuGG0MRDEIvXzabtWzE18EcQyUa/ktakE0WbeVlblRfbjhq5uLFkj3X8NTs4DeHWPX4Gg3/5tMPg+265xTqHLdJVNUGarjfABmHJWzyDGYOYFculz6Ou5Fh+1VymcwWCfopR1E0Smfdlj+XOASWb10CTjDAZqtlIuZz/ePrswVP8JqpG+NCWCYC/p/BZqauESNBFEugvNH7EhCP4ys8oKs+maE61sHk286MtQbLq2mWk2aaPTl5jKtamlfPmoNyeSS6GjntZde439ZnDywrkNVEaooP7Vt/Kz+JjyYd9fyovtx4165gdufJ2rFK9W4d66CSLTvhgTRO3I4UnIOiOYrp7HRcR8ukk/ZP/JlDeKMyWCoP5PtYC1WZtJMvFEEPP2qB7pGoK4sKV5f490RMUFQVcjZrKMCGLHEka+Wcr8OLD2o+AB7B/0daURqaNQK5UDPl/ZYjZeE5bG6LzB8SMWMjrZJi9Ma1EFlXID+4FZbR+JNropFwNlKesmiEz7YmDACq2UPfajdrK2D07EHbr/9C1fE39qBEG932rhyhbaVuYiiHl7VI90DUGgD8bapo+gN4++ldsnD+JGBOEH5yhPNrn4nu2qBHce5QdLIER0+XTcjLDR9gYLrIQgjcistckH7GmDUjDvrB0WrD2/NpigIivdiaybIDLty4Y9G/eldH0jINMuTZyh+0+fspVxabtooFzVJ0fbvkld++Qok5mMIQVqVvxmYb3ESp/Nbe8poak7Bgq4qamJCGLeHtUj3aYSRGZvZNfqWTNz7AFBNWq5mdlE6ksSfnDD0ihy6fF5u+5PgM/rYz/yK8VHWv5UFGZRguBMBn6oSsm62iBNpn3ZO/CePCPrr3nbeh39Z96y8h1ob3wwzwTCPz86+Akxc3YokhpBzNtX21x9s4q4QgtgIoh5e1OPdGMmiJoJZI/qt0atHdJhRocJJQMkpnh9BVUVM+FS+P6ut9nPWEj5Z2NGGKn9lr2CiM6ELJsgOHzozSD7WHV1tcu6+k9XuaL7HNw8g7vB7BtjikUkWrmCOYcPI1k2QfAM+jl7Td59DStwvCPXRASxSMsn0zYEcUaL3+WHqMwSl9aYH3adAcgUI1IxZWaYmDqyQewFvzuLCqozZi9dexkntzg4FuQUd5d7jLJMqKneVFyIMGA/oevD7b6ekJr/9CMH7GjfUhZdQUTWP8smCA61QQil4DEWtxvLkE3oP9l6RKbYyyDLiHhwjoeVWSSrIAiew8qQM0le2tTYIohs71kgXmYgXiD7VNJ5CYLZ+yfcEzKuwFOFmiMS35rgq1gs/SGN3Y48iM83DJBoqY/pK5vdfeScFtl7VOWcyNVcJosSBJvxrKJKWTZBcBYFVxqlLHMPYtP6T1s7R66w2/YKMn2Gd58zPF51FbkjafJbFUHgHoXzLV7kaiPTkiuMM2aCwJ1CtDHWxwxyhdD+Z+mMGuOeFrx6gOeySYoJKvJACwe6wsyjQjjA8niBy+fRszKUlxcliMg8dNkEEQ0anF/gHENWdiyiP2iH4QDl3/T+U9YxWk3hegbd/7ym1TUz4tNbnjXX96siCDato7MP+CyjnpFoBZF9CxaIN2aCwCKimYGXEPQ9B0E+DKwlFrwgHywyJc/9i98c4HpJEnesNrBk8q6McU6GqgbBCoRzD6Vg4nmr5DOaaLg7v6RLE+15RATBs7xZafT42sC6bIJAfecHB1aImOxGB+iisrLZ6v38QDzo3ofsPz2b8b+iR+dbiIR5etlP+zwHJ5NMXkpBPYlqs/YBrVURRK0tUI3WfJCJIPq09pxxx0wQVJlDYV73z4dH+ABQVojrN+V8Hvz2HzPxZrBtz+OMg3cjzqoBayAE8uCgnRcGQ++mo/YcPkcaneeIVFXor71zv6z6puZxdtkEURs0sudD6Nvft+A3/zEFbghmqP6T7Yu1eOjiSyu0Jl6XQ7tafpiWck7Hq5favr9AXqsiCPKOSOkcdv0zlUqIIBbtVYn0YycIXEhw8tLLjl3oOmhHGsw/maV6W2xm4e8pMsWdhvdLj+oi+4nPaIVQDnSQDbM3/8L22ZSNzg2wYY+9vBe8ZPoVEC8iL2SboDZj0PXlJM2yCYI8owOEtTr5cuPrigG0FOzqUfs1MlT/6YA1dftVFuuaQczIM3Bbhli0YSDh95BI0+Ufa5UEEZny4qiSryRGIoJIdZvFIo2dIGoDKx5A+bBPNOtqEGOGyiyaGXEpqDHQiZYWWtEMn6U9L1SXJRcYY47o3XT45fMdLU7kmC9DRFieRCaPNZcWtU3BtmdxBgQ1WDRIgd8qCKKmznqoPc+fwyjbkM3Nr1rwROadMA7VfxZ7Sw9NDe6QRCTZ/Sp8e7Fajg570u/x/BupbZtnrpIgogEfS0LOQ0QiglhGr+rIY+wEQfVq33VgRoy3zshUdMeuo/+/UIAP31bgQFspNU+pkAT+kg6p4MygyrKdfQAv3lU4cdG3+m9HkO4mFg6qPKOmn8aaCT9E0dKdgbHmhZb8WBmVm5/kg856t1IGLq+CIMg3OnPBdT6shM8eT9CQHxv10TckuObdswzRf1pgS99i5o9KrPahK1ZLDP70SX/ymo9gYcnGiql2cjnzTfJVEkRkzdjW7yOC4J1vDD/SwLqIpKfPSQyBbSAIzEVxZeE3gZsG5qwEHecQCzsWzmqhdmYBFQSzq2hQjcwum2eg5mJjG6sqlsrsHaDaQTUVqWO47k04yYtVBk4BI4E82Kf4kgXIBGsTvigXDYSkb5t9cb/t86nMJlHlsALjOZlvcK+KIBjQsDqqyR67gbkzJH42C969d5OuZt8/VP9pqUL6Fv6j6GdRn2oyoe2YFGEVxIqAw2Zt8UkHsdS+zVAWbpUEEZ31eIo9PPrGCWWKCCINZEtEVFqotiSGwDYQBA3JS8CZgdpgmWlsNoMZDP3HdZq0+A/CJXeNiDLPIE4bCdEe2LzX1DjZZ+CmIvpKV5meWeUXsxm6eJjOejcYqyIIHl373Gu2+F2br0P0n2xZu+KxQuJjSV2Dflc+zf2D7R9WD6XfsVraVRIEdaKdS6FMkGLkx0wEkW3hBeJtC0EAAbN2Bt953F8wO+c0dM3muoGYDxGxWqkt07uaglk5K5Q2yyT2RjjV7q2muvJu7qMKuncycrSR25WUZT8b6v5g0yoJgjJFH/fpKiv3WamhNuzyPDxE/8mUNxMHNSTfMJmnr5f5o17DFLhrH61Js0qCqH0RkRk9K2W8N5Qigsj0lAXjbAJB4LG03AuI3FNnq4m6ADfRdPrMDIsBm41qDk+1bc6Vz8eclM1kNgazQp3YhGaTMXuwCWsbZr7RnkT0XPYcbm/Bny7vKiOWS5x/4BR4m6Djxh0C34iOTiFzTgT1l5dlti8rxMdY8K7Ro3JzghzLrtqhryjNEP2nqz2y91EzYqLNRKKr7XyeGBs83UJftzQ1b8HzuIXxZWpbJUZ+ySIHl1ns2uKhksYTgsQQ2ASCWEVDYL7KrIO9BvTnDCzMzDHRRD+LCSzuIqIP0mTLw0Eu8kflhEUSqwoOxSFsdLEfwYqEv5gVtllU1Z5JmdnLwCSRvRPIaV8LfPAGvfxPLKBa4yDe17MFr8TjA0lghgUQs2n6Brby5IsqKuPOecEipJPjBRTswR0VBJvutCsfegJzytznexz+wUP0n3RlExFpOyYU9EnwQGVGn0c1Q5/nfAyb82wE0++7fIwlHqkoU0BgWwliCm2nOgoBISAEVoqACGKl8CpzISAEhMB4ERBBjLftVHIhIASEwEoREEGsFF5lLgSEgBAYLwIiiPG2nUouBISAEFgpAiKIlcKrzIWAEBAC40VABDHetlPJhYAQEAIrRUAEsVJ4lbkQEAJCYLwIiCDG23YquRAQAkJgpQiIIFYKrzIXAkJACIwXARHEeNtOJRcCQkAIrBQBEcRK4VXmQkAICIHxIiCCGG/bqeRCQAgIgZUiIIJYKbzKXAgIASEwXgREEONtO5VcCAgBIbBSBEQQK4VXmQsBISAExouACGK8baeSCwEhIARWioAIYqXwKnMhIASEwHgREEGMt+1UciEgBITAShEQQawUXmUuBISAEBgvAptIEIc1OPng+qlm4Yj2l4+sv9DC38cLtUouBISAEBgXAptGEDc1+J5XgfCYdv1344J3K0r7gxlhN5X5hv1z2q2omSohBIRAKwKbQhCsGl5g4YYtpRVBrKcz/94ee7Ti0T+3/0+wnqLoqUJACAyJwKYQxCWs0u/uqLgIYvGecUbL4p4uG4j5fS1ZiyAWx105CIFRIrApBPEMQ+/WLQj+we6d0AJ7EZL5EbiyJX2DS35X+/14EcT8oCqlENhWBDaFIN5lAF/Sgfxq+30nCz+x8O9tbYCB6yWCGBhwPU4IjBmBTSGIrxuIp3FAnsF+f3XM4G5g2echiItbPY5e1OW39n+bSmoDq60iCQEhMA8Cm0IQ37bCn8JVAPPWv85TKaWpIjAPQQhOISAEJorAJhPEppRtm7qGCGKbWlN1EQIrRmBTBmG/gmBTulRrrBiGpWTPimdfC8eyQPkxB8UCaBlyOMuEsweYlx7GwhEsHGLhexb+2OMB6ySIk1s5MTQ4noXG2OAX9v/XLKxqpUj/PvasXTCl5nmEf/TAbJVRhyjfcawCJ7VwpFmfZE9v1cYePJPDrvTN71vIHHAFC9LxDiG8P7+y8M8lNsBRLa/jW/jXLM8f29+/LTH/rctqXQTBKekbFGg+MED2QcU1Otijihf7Mvb/tV2ax9jvryRb6LIW71ou7n3tNx3GC8+lUzXyTvvnFbMfDHac3bi+hbMHaenkmJE+18K3kmUro+1vP25v4boWyrMIZRye8XwLWCIx+Hm5jV049+wiZq7nchE4+PaR4tqL7P9yj+EO9psXtxGe8bRkXU5m8W5r4RoWvAqxzOL19uOZFjBWyMh5LdKtiogMIhg0NGSJ2TRtckAls7fb9ZdaoB2XOQA1j1tn+ZhY0Sc5dBr1ScrIBObLFg6y8EoL7Ct1CX3gsS7Sq+w3WCKns4AJ9dUt+L5KH3vc7Hl+QKZv3sQC7RX18ZfY9edY+EBXASv3z2/X6X/kX77HTXTK9mILL7fARFVSILAugmBwbwbZbIOU5yAeYIlKAiGPq1h4YzIz0pJHKXTUTwbp/TkABjIG3etYeLaF2sDts+IlOChZviNbvIdauHMyfhONNA+2UM7Y3ma/IcSs3N0ilgPBPOcgDm953NuCb6OuMnzYIhxgoYtMb2lxnuUyY5ZMvZ9qgUEqIwdbJCYqzKqXKesoHyuEAy3cY46KPMXSYO7cNtPHaARSKYW+9hALTM4g6C75jkU4nwUmNZSX/nqXrkSz+0zU7mchu/pjxQopXTWZP9Hw4kD//02PNFsdVQSxt3n7EAQzrnvN0TMyJMYMEKLbnSN/kvCyloPE0ATBi8+s9Ipzlp/ZLau7d7SkjwZgrK2YBUazxLaiMCm4gIWMGiRbpaHLxySF8y0XyxYwiPcyu3YjC7UVVUQQDNqsHFBdZoUVOIM2q8ZLZxPN4t3H/j4ikeY8FoeDt9nJW5kl5EX5ylV14pHbGUUEsbddswSxSE9g8EM3W9ubYK9hjwUGrEWEF/ZNswyGJAj2R95ioWvFAg5dLy8zzY9VQIgG4EXwQjXy6EUycGmHLt/T7fmsatskg7mfXJT5RQSxRMjSWZ3aYratMFEpsRJdRMAKNWFWZb3IszY67boIAn3mBQtk/OleGqj0y8SykoGuOTC3ThWTb1BmHE+w8EUL/I+unQEe3X0k17SLr6ncYwnNkt0LeDBzQueL87xjWDilhRtbiE6gEx/9P0vls1lA/YIwy/bl4kAi+vhGPjN7RvO7j4qJvJ9cKT/qiI9b+KwF9grY1Kc8t7MQEQpYntnCz4L8MgMwM1TqBl4QFxMAVE+8+F6W7YBwyPKd2CrzwwrmkAYzYTaKWRkwAaHfoI9HJeRJus3PVoYgwPzNFsDzRBY4/HqLoGz+Es+F5HiH6LOciWIVHO1bsXJn5RIJBiIYPUSrSCYb7AV+zgIagDNZYKXBZIq6eQFTyOgvifJvbZR1EYQH1FsxwdxsqNZkUwgCfTc6y6gTXcGu87J4YdMtckpIZ+TF8sI1BtJoECAugyvk6aVcRTT35rFiyhIEJIRVlRde/otaqM3G6IMMVpG7DwaCSJXXNgDzPLCP9pNQf6HiuFBQTlQlHNhchgxZPgiWflgKdUedGRldNPHYwP50UFl094cE19sIggkJ6ik/0SMb9jb85naZfU3vD5nRVl5tRt0aowtfTAwsonfrQLv+MAvR/gV94rUWokkK2EJckxURxN6m76tiYtXQtcGG6uKRrnfVZqtsqEX5sRJgBtgmPMM74WPA5eUsZZUEwQuIjrgUBmtWit9MvGFPsjj/G8Rjtflrd702ADNQsWJqs0ZhlgmR+dkz+x6sOJYhQ5aPfug3iJkZfyJRkajNWGW9LkjbRhCsmNt09t5lfJP9HvsHAqi50mG1E6mTonELy8ion2UGeVazrOov7+pN/8XsdrKufkQQe3tEH4Lo2ktoco2W/6T1ZzywWvppMGhhevvwxItOfv5bGV+wa2dxaVdFEMzCUAX5QRcrrCcmyk+UGgZYi7HpXUptAEYtgR69SyKdPao6bxnVlU/t/pDl83tMfdyxgy0b+6WgtmQm7qVGEKg9vcm5T1tzxomWoEvP71ew5H0UC39yD2FC5K3+UCsxQcmYMkfvEI9AFeWtt+btF6NLJ4LY22R9CIKzCdmzAAycXieKGWi53EXlEdl5c7AM4sgIVj/eKsS7SF8VQTCD/FBQSM6J/DJT+FkcdMQ3c/EZzJkFlhINwAyMqEf8wBE9HjWEHwTZ/2FGvQwZsnwM8uVEgBUqZ28ywh6FV6H0JQj2C7pWiJFZ+R5Lh+qxS1CD+fMcGHr8yCWM3jP2m9j3yko0ccisQLL5jy5eQxD8PW6P0jO4LdNWeGx7EAz40aG0CMKog3O6t8Qv0tO26Vqj5zDDY5ndCLOmt7qIqyIIVGOoyErh8BF66T4S7adEK6FoAM6o/JqyRM9ps+DpUwfibnr5KCOD7Pst+I3gvgSRmWQys/d7TJwhKg871jBm4uGt+ijzd4sE/I7Uin4i1tWO0fvB/k7N4KQrv9Hfbxr3wrPO0qdCuHtY1jH1MRFEpCJqw+29dtNvtHm9OlZE13OZ3N9+c5BombIqgkBNwUy2FA6gldZRmXpEG92RyiQagPvM9FA7fNAVCIK7W6aQiTibUj42elFz7meBvSzCjgUmEzVT6j4E0WVM0kAVWbe1WSOVEGcIAstAVF2lsJLaTbRVGQV3Nt5TMZMsjB4mKQ1BMIAxkPUR9M7LMgEbE0FgTcQLl5UMQURxcK/R97R5V5lWRRBR+S9ihenrHoF9iMhPEGaq5UZhNAD3IaR1EMQQ5YMQGCwvZYHzAKh/+kofgsgOnhFBZPHIEERkydW33rX4fVfyy3ruRuQzVYLAJp8ZeinZPYi+NvMZgojUUNiQv2fJvWRVBPF5KydnFkrpOtBUq1pkMeI3JSOCqFnfRM9ZB0GsunzMcjELjmz6+3SjPgQR7Q9Fz4oIIjsByhBEZPbep85tcSMV57Ly3vh8pkoQkWlgliCyy+qm8TMEEZkBntMyiOzUF+lUqyKIqPzzfEMcnXGktsysIDJuTBrs1kEQqyofZru4ZonOdrT1FVR3iDeg6EMQ2X2fVRNEzUR8kXelSdt3QriMZ25MHg1BYG7Wx8QP98xYzGQdZ3VVeGgVU3SgZp0EgRmdn/nxwkeWQV1Ytt1fFUFEKyD2EyCOPhKZBUeEHK0gVjUA9yl/E3eo8vH+csiryyEdahIsjXCWR19jxcdvVjVejTlGgsD7AFZoXmquWvq0KSevu9yY9MlvVHEzFghDVGhogsBfkD8Us06CwM6fg1qlZJfgfdpnVQQRbbJ3HZ6Kys2qyZ+Axn3D1VzkoQbgPtiWcYcqHy4zOJnvBUMKTi9DHpwOr03kIq/KYySIyIruZVZv8JEsgMBUCSKymV4nQUR24t7tdlczsym5fxGJQQF7+ObjKNxaFUHwPY8DXQHnOZl8wKzMZVY40fOnxIcagLswr90fqnzRxALVEQYC+CTqEs6ccPaklDESRNRv8Cl2ji4AdL8dgW0iCGyqsa3uktqR/HUSBBYdnBsoBT9OV+qqTHEf1wr+Y0CcbC6/OLcqgojKn7VzL6vIB4PYnC+F5T3f4ChlqAG4B/yDl499GZzO+dPrqH6zH16KjDXGSBDRypMG2cdCHzfuqDgv5xods9c277Hz9pFRpBsrQUQHb5oP+XQBX/M4uk6CqLko9geCanXjBDH65VLwh4+5YymrIghOrH40KByfSG02Q7vahVPjkXO5SFUlgjj0YGt0WNNPCmq48+6zyvCmsGMkiJpxAyfmIxVcDZNIVdo3j65+Pqr7YyWISPeaWVJiWYPju+hbBOskCJyFsWnI6dZS8MOEP6YuwcCAQbOUyA/SqggCPzacD/G4Zn1JUW4c/XlXF2wy8l0ILyKIQ7997p0YglP2AGt0uIz0YyQIyo2DQb9ZjwUSxh8ZX0yooz4V9DVwznyStesdHeX9sRIE3xxmhuylbXnNi4MahxcjknUSBOWJ1DRcv6IFNtVrUi4GgeYAACAASURBVHP3HTkZiwiC09r+TEj5rKy77ztaosgxX0blwTeDI0+q1C36spwI4tAWivbSUJE034mu9ZnIzLeJO1aCqPkz49O33qOyxwUSQKXrT5fTJ73xSMuruH23xkoQNc+LtBCDCjrYcnMW98d0kt2WJlw3QRzWysYqyB84o8i44cAcsTxERnz0808J6kQ+6GX9oTM2L/e4+KimGDBq32XOEgQEjElq9JGXm9j1gyrY1wgOaybaLTo4J4I4FMxo1owFE+3JAS8vfMQHix/vBr6MV3OBEXlz3ZRzEE35ObkfnQeh793Wwp8DTHgncNPhz4MQtTYmVLry9l0eK0HQEpG+sGkhXhLUE3j2PL2FjMuBdRMEZWfPgI+kREKdDraAHTsves2VAvHwfhltrNX86/M8VETghaoH88hGsgRBfOzqa1/LgzzYp/iSBciEduFDSF6t1jyXk8He2WBzTwRxKBIHWKh5bmW1zDka2pT+smsh+ihO0dT/+Zc9I/bzMG5Addl8HncMBIGvKb5KF6mQqRfOCTnXgKNMPhCFWqnmkwoSjT5i5fHa6t9jJghUKHSGeQTTyXu4hJtAEBRp0VOhbQfG8NWDF8zaoMzzvXltH4KgP2F6WVPjZduq9iW5Jr0I4lAkwBvViD/T0wdnVnfR7Jk8MJuG0JExEATlrKmfs5gQD0xRx0ar1z75jD7umAkC8DlMxoGYPsILwWzZ72FsCkHQJpgfRidD2+rJygHS8yahPk2XY7NFCIJnQULMPG/ap1GKuKgC0Ru3iQhiLzpYfzErrg3yNRxRufAhn7YJyRgJgvryLuPHLFpJdHVLMMGrLyuvycumEIR3NdHHgyLLRGzu/UdFfONCJAy6zKA5L8C5gVLKl6G87v0M1Sxrap3pTXaDjeZSjmE/mqV7LR2mo0+elbWrozLjZlUUWbX4tLQ5n/asfenNE4SvP3sWqKq6hDMc6KijPYkoLW3Oh5h8u0Rxow39zGZ4k1dksQIpc+BvGTJ0+diTO9CC/6JaVJeD7CLO7Ro3KHybhD4aqVrKdyL65kKXgUPz/JvbP89xhcm6RonOxnBeITKJLh+BGTBWdP5zrLX2Zd+OPoBfK8kMgU0hiGU0CL7c0WnTebC/p27o4XE1gCqq66tXyyjDKvLgYN9lLPCCUjc2p6kXARclkGv2rEFZPmZX5E2+HChiBYIJ8Fct9Dlc1FZnVhOYqaICOasFZrt84xezQSxw2Bj/iAUslWgnyWIIYODAJi2+1fgfl/wQAe2KCSeDn/80LU/EzJo9LdoIz7lMXvDX9GELy+oLi9Vs/tT0N94fDmCyR0EfxMsAE0Vw4S8EOdnPirZBu00EMX8XUkohIASEgBD4LwREEOoUQkAICAEhECIgglDHEAJCQAgIARGE+oAQEAJCQAjkEdAKIo+VYgoBISAEJoWACGJSza3KCgEhIATyCIgg8lgpphAQAkJgUgiIICbV3KqsEBACQiCPgAgij5ViCgEhIAQmhYAIYlLNrcoKASEgBPIIiCDyWCmmEBACQmBSCIggJtXcqqwQEAJCII+ACCKPlWIKASEgBCaFgAhiUs2tygoBISAE8giIIPJYKaYQEAJCYFIIiCAm1dyqrBAQAkIgj4AIIo+VYgoBISAEJoWACGJSza3KCgEhIATyCIgg8lgpphAQAkJgUgiIICbV3KqsEBACQiCPgAgij5ViCgEhIAQmhYAIYlLNrcoOhMBR7TlHKZ71F/v/dwM9W48RAktDYBMI4r1Wm4sVNfq5/X+CoIYnt2vfcdefar/vsDQ0lJEQWA4C77BsLl1kRb895XKyVi5CYDgENoEgPm3VPburclSuM1icL7t4L7TfBwwHl54kBFII+EnPDy3VfqmUiiQENggBEcQGNYaKsjUIiCC2pimnXRERxLTbX7VfDQIiiNXgqlwHRkAEMTDgetwkEBBBTKKZt7+SYyKIfaw5LmehLPM37feXtr+ZVMORISCCGFmDqbgxAmMiCLWhEBgLAiKIsbSUytmKgAhCHUQILB8BEcTyMVWOa0Bg6gRB/Y9tYV8Lh7Xwi1n4xxLb4giW1/Fm+aMm+7GF/1ti/svK6ogzHI5lf/9ggfMov19W5mvK5zD23BNaOL6Fn1n4qYV/JcpyuFka2o1DbmDxWwv/TqQlSoYgjmTxTjorH8/7lYWfzMqYfEwq2tD9j/eIM0scFKSv805JRorAmAji6IbxnS2UZf64/X57gP157dqtiuv/tP/vZOGPs2uXsL/Xt3BApd3I86UWXmGBtH2FQ1HXsXAtC2cOEjPgvGr2DOqQHXj6loP4j7LAANnIO2f14jcD4A1nWPizKNynnC+w8FwL3+p4OIPCA1ycN9nv1ycLDWb3c3E557InSO/blygPtfDtWVza9x4WLhmk/bBde7CFd7l7kMmVLdx49tcnBYsXW3hmAos2gji/pb+1BXCP5Ct2kX7HIdDfJLHz0VbR/5jcPMUCfxsBj4NnP05vfx9n4bLF/Vfb/7wDkpEiMCaC6HNQ7pbWHs9ybcJs7e+zF+/qyfai89/AAjO7jBzNIt17FjLxicOAdXMLX8sm6BmPVQDlaoQB7jYWILBnu3ttWd/Ebh7UEmHX7r3P3X+C/b5LsrwM6u92ce9qvx8fpI/aFzL4vAWIl7J0CcR1TQtMAE5sASKMCCXK57p2kUG8JhFBMIA+2gLYZ4RV3G0tvCQTeRZnlf3vGPYMVlGl3HNWJyZftLUXEUSPxtvEqFMiiItbA7zcQjmbzrTJJy3SBSxALm2CexBmpdGKIfMcZpWe1DLpuuJEBMGLfq+uhMH9q9i1N1bS7dr1dRIEBHZ/C6foUa/7WlxWKZ+Zo19cyNJ8qPIsTxAM9vSj0qVMtpjUidVRl6y6/9UIApXdYyqFE0F0tdqG358SQSzSFM1MqZYHpPPRnoNTlNf17CIktkzxBLFI3gx0J7EQ7U3s2vV1EsQi9ZonLe4zdixEKkhPEPPkX6bBr5NXiZX3h+h/EUF8wQrRNiESQSza8mtOP2WCQMVAB/6BBfTP57aA6gn9tpdv2IXTVtoKDJlVXzG4j976ERY+a+F7Fpjd8pxdC6UztzLpmeyH9zm1SDfpIgjKiHrgixb4nzKyYqo5QUQt85qgQNRpkwjiiVaej1hgo/TUFtD5Z2bwrCZeZoG9AAb/81i4u4VSTddUH5x4hpcuggDnx1rADxmO/HZmz7mp/T1NkB8DMXtEERkN1f8iggiK+p9LTCS+a+EtFlilSUaKwBQJgpfzChZY8nvBsoRNXNQHXk5nF74eXEe18fzgOgR0CwtYp0TChu6DghvLnnW1EQQboQx+WOp4AaM3B9fRiUcbrLt2fRMIggGejWZ/gBJrHgwP2vaf2C9hI9ZbsWEJRdt7knikXWPPyUsbQbBHwt5C1C+wIANziMfLjewCm8Jehup/XQQBKdzMAntqkLJkCxCYGkHQic9mobF2iZqQl5TZvh8MsMZg8C4F80RmSqhdSskO8ljtPCQoBDPeLquhbPerEURmAxnVGoNgKbXV1K5FWjdB0L4YI/jN1Kb8O7P2irCDsKO2aOIyQLNfUQqTgKsFmdUIAqOA0rouKgfmoUxSPEkwscFS7E9FoiH7XxtB7LEyYRUoYohadMTXpkYQmD7WNtTKZny6/fDWJtEmMpu23oyTQYrVRvZlYVDddX1omRvWEUG07SWURcG6B117KaTF5NgLdVg3QdBmWGm1CZMDv5GNmgfV3p9bEqJrx0qqFGbLFwzSRAQBbqeywEDfJRhUvCeIdD679rHi+pD9r0YQ1As8f9lVKd0fHwJTIohoBlZrMVQoL3I3me0/zF0jjle3oLJBv5yVa1tEbzKZXYFknhERxO0t4dMyiS0OB8y85dfh7ZpXw+zatXUSBETGDLvrkCOWR352nrEUigbI2oeAIoLgDA/7IhnhvURFhml3Kd68dsj+VyOIPn0pU3fF2SAEGoLg73F7lIuXcN5DPP4xq/hgUGQnn1GpNGXjsM/bXEFZebACKSUaPNnk5vBbVsDdnzZt2xTP5tvEiwiCAT97wjVqH06f+/bftWvrJAgMBZhRdwmH97xBQcZ67MiWzp+Ar30IKCKIk1n673cVrrh/O/ufPaJS7mM/MHpoZMj+VyMIVpOsIiRbiEBDEBe2ur2/Z/3Y9PtbzzRR9KEIghcO1VFGUBt80EXklOjdimsnsv9/FGTG/kFfVxqROgqXBRm3EF318QRRUxHV8okGu+NY5F+7BLv2e50EweycWXqXvMEicGK6lJo1UhlnUYKIVl1tZcXiCuxLeZ794FAlMnT/iwhCX8rr6m0jv98QRNQZu6qGxU9k/dKVzt8fiiA4EY0VS0YyBHEWy+hzmczmjLOsmZkniL4v9VgIonbq2sMfEcSORcIwoU0WIYh5vkmNWbU/Xb/Hrl10Vsih+19EEG+1smDtJtlSBKZEEJg3vi7ZjhmC2LW8/Iw5mX0qGqqnmolsKoNZJE8QfdVXYyGIyMoswikiCCyfOA+zKoLAKukyfRrN4h7VglfdlOQ+dP+LCKJmxdWzqoq+qQhMiSDa3ET49skQxJUsUc3txDLaGwuirCVU2/M8QXAA7Iw9CjgUQVw1IPA+vpiy7bsOguBsA/2lj7CC/J1LwBmPc8yuDd3/RBB9Wm9L4jYEwYDRxw/QXy0+J4G7LEYyMA2lYsoOIJQ5QxCXsnjMDL2UZoiZ+kdxUN2xdO+7lxHlNRaCiA58bQtB1Mxh2/pHpGLikB1Wb8jQ/U8EMe/bPOJ0UzJzXTZBnMva/ROu7ftuAA/RdcZCEJxixhCglG0hiL5qPTDYteBVmFgwYcmEDN3/RBBDvK0b9gwRRNwgmRUEh574JrYXTmLXTvKuo/nHQhBY6OCLaBsJgjod04JXGbX1h+jkNq5b+DYHMnT/E0Gs4+1d8zNFEPMTBG4OIhfgfc9BkM8BFsq2wHrFm9nO21XWSRAcAORwV0Yim/5tWUFQf1SGWP1khXM45cd3SMf3KpoT1kP3PxFEtuW2KJ4IYn6CIGX0Epe26pmugl37c1zEvnm0PWcogjinFcI7QMyad+Ifiw1YL9tEEH3alC/CRb64vOHCkP1PBJF5m7csjghiMYKITruS446FLrt64uGYjUHUu7IoZ4qLdrmhCIKTwocEhY1OXfto77ALkfvzbSII6ry/Be9lNmpfHCTiKLGUiGCG7H8iiEXfxBGmF0EsRhCYImKb7j2/Yv6K+4bS86Z/EioCPqfpv7vARjeD6jIsxHjmUAQRHSTj+Xz/+YEt7wYkUPNdtW0EwSoJ66O28y019918J8LveQ3Z/0QQIxzgFy2yCGIxgiB17bsODAZYTkUHsHbsOo7Wou9O8H3fJy3asEX6oQiCR0aO8LjONxNwhVGevGfFgW8rvo1Qk20jCOrJORS8zn7AVRrXNXjxjRz61b7BMWT/E0Es8aUcS1YiiLilMlZMTcp97B/8WEVfoiMOZyUgi0Ms7Fg4qwW/+djkxYEq/AT9e4kdaEiCwMqGbx7UhDMiECY4YKbZJdtIEE2d+UocezYQA2QZTRaauG1fGRyq/4kgunrrFt4XQcSN2ocgyGE/C3x60n84qE+XwR356S14J3h98ojiDkkQuIfg4GP02cyueqB3v5eLtM0E0YVHcx8jBvYf2mSI/ieCyLbYFsUTQSyHIMjlBBZYAWRmxv6pqB1wQc2G9bJlSIKg7Mx2IcvoG861urHq4KDcH7eUIDD3xcQ1+mRoW3v3UTeuuv+JIJb9Zo4gv00gCHSx5fKamTSd3QtfrfKfCn2GXYt02Hhu9S8jVjLvSrYJ/m4+5eJ2bbYSneU+ahZOvGYGSFQubFTjHyg6U5Esbms0VDrlyoZn8mWyrETfT2CwgHhqsq/deLKFa3Y8BBULqwTOfIAdXyUrcat9IW6R9sWjLwYEpVBezmG0Caog7724dkLaY9ZYIO1aHpwWP3sCFz5N+tlsI83irbL/YXHnCZx3jAN9ki1FYBMIYhuh5WXis5HsNaBuYYDGaokPxjBgYwL7Fgt9Piw0RpyOZ4XGiynkziAMLodYYGD9ugXUUcv45sWYsOGdw70+kyJw2bGAtRvWcJx9wALuqwtWSP1vQQCV/FAERBDqCUJACAgBIRAiIIJQxxACQkAICAERhPqAEBACQkAI5BHQCiKPlWIKASEgBCaFgAhiUs2tygoBISAE8giIIPJYKaYQEAJCYFIIiCAm1dyqrBAQAkIgj4AIIo+VYgoBISAEJoWACGJSza3KCgEhIATyCIgg8lgpphAQAkJgUgiIICbV3KqsEBACQiCPgAgij5ViCgEhIAQmhYAIYlLNrcoKASEgBPIIiCDyWCmmEBACQmBSCIggJtXcqqwQEAJCII+ACCKPlWIKASEgBCaFgAhiUs2tygoBISAE8giIIPJYKaYQEAJCYFIIiCAm1dyqrBAQAkIgj4AIIo+VYgoBISAEJoWACGJSza3KCgEhIATyCIgg8lgpphAQAsMgcFR7zFGKR/3F/v/dMI/WU0oERBDL6w9Htqz+z2X3Qvt9wPIeoZyEwCQQeIfV8tJFTb9j/59yEjXfsEqKIJbXIMewrH7rsnu9/b7a8h6hnITAJBB4r9XyYkVNf2j/7zeJmm9YJUUQy2sQEcTysFRO00ZABLEh7S+CWF5DiCCWh6VymjYCIogNaX8RxPIaQgSxPCyV07QREEFsSPuLIJbXECKI5WGpnKaNgAhiQ9pfBLG8hhBBLA9L5TRtBEQQG9L+IojlNYQIYnlYKqdpIyCC2JD233SCwPb5hBYYfP9u4VcWvmfhl0vC7/iWz8ks8Jf8DzvL+1v29zc9nzF2guBgElj828L3LfgzHTU4jj5royPO2ufn9vdvPbHLRCf/fS0cy8IfLPCc32cSDhRn08s3DwyHmbUt78fPLPzUwr8SGR1u9k4dz/5yyI22wgScvpWRDEEcyTI66ax8PI+x4SezMmaekY1zBItIPRgb9rHwYwvZdyP7jDIezzm5Bd5HnvWLeTJZVppNJAga4w4Wrm/hFC0VfZXde7CFL/cEg1Oat7JwbQvnakn7Qbv3olnIDHh9COIys+eXj3+M/fhKsi6XtXjXcnHvO+tQPotH2QVe8Ea+ZP88bvbjuPb3thZu5+Jwm5f6BRYoFy9fKbyYN7FwcwsnCcr87hluL7e//+yoky/fOy3+K2Zp6As3tEBfOHuQT1PG59o9SH0VMlT5GBQe4CrwJvvNWZqMMJm6n4vIQc09QeLz2jXegVIeaj++PbtwCft7DwuXDNJ+2K7x3r3L3YNMrmzhxrO/Pilt9WILz7TQ1VZtBHF+S39rC/SLSHiH6D9PtdB3ktfkB5bXscA7dubgIdSF8eelFj5uIUN8kMtTLPC3EfA4ePbj9PaX95J3u5FXz8pQqerqL28aQdxiBtLRelT9ZRb37hZg2y65pkWg45QDZlcaDulQLk53tkkfgmAgeJDL7Cr2+41dhZndJ60fTM5t1z4ZpGeWXeLJC35BCzeywACSkQtbJAgTgRien0lkcRjsb2ChbcXny8cAchsLvKDPdmVveyzlOihZrj7RhirfrhXqfa5gT7Dfd0kWlkEdYi7lrvbj8UH6W9q1Z7nrkMHnLTDwUZYugbh4n5gAnNgCk4mIUKJ8rmsXm0lAdD8iCAbQR1ugb2SEVSaTn5dkIs/i8J7cexayyXifmCh9rSNBND7cc1anO9lf2tqLCGKGCETFTI2Bfh75mCW6iIW2mf597P7D5sl8lob0j2hJPyaCgIh42bLCjImZFAMLs8c+AklczkJNNRENwKgj7tXnIbO4fUg2m/1Q5du1Aq2TICDY+1toW7V7zFi1Msn4jIU+ky7yuZCFD1UawRMEgz2Tn/J0dbb9qBOroy45gUVgVRStGLrScp9VjSfdMl2NIHgvWKVHIoKYofJw+wtzLyLMlJgxRQJTP7Ijczph18qF2VzE9GQ9FoJYBON506IOqM3k/AA87zNIRxui8lrm3sRQ5du1cq+TIBbBfZ60rMx3LEQqSE8Q8+RfpsGvk1eJlfcht49a6EOOUZmuZxdRq0YSjQ9fsIhthCSCMICY+e+pgPoMu/4cC9+wgI6TBmQp/dhK/IsGeZ3TrkWqF7JgFv0BC5+ywCYcm11nsXBTCyxPI4meQbyxEgSzv4MsfNECG3/sy3j1VwWK/6jr0MH+wALGBKjiolkeqwj2XSLpGoBZvUDKlI//6QMXsMA+VSSoPV5TK/Ac14cq366VbZMI4olWno9YQHV7aguQfGYGT39C7cteAIP/eSygGYgmX7Qjz/DSRRD0A8aAT1vAkd/O7Dm8t6cJ8mMgZg8rIiO0F6yorxik4zloDT5rAeMY+h6q3F0LpTPBMumZ7Ee0LxqND8Ej/3OJic53LbzFAqu0tcm69yAYkAEi2uikM/oXpgHqVLN7Pp1fRUAqDCxnCBBmAwqGrsnF7QZ6Vt+xeQHOESQaI0HQ+SDJf7j6sOfw/hZsUOmhkoj0rg+06wcGaY9t16JNw7YBGAJicMESxssV7MKbg+usVGobmC1Vqt4aqny7VoJNIAj6NxvNGDOUgjUPm7JXbwGRFTYbsb4/MXn4ugX/LrGqjzQHbQTBHgmTN284QbGwcKNPQDxe2HNjU9hLbU+Nd58JT/Qc8oj2Eblem/V3EQSkcDML7Glk9lNbmmF5t9ZNEFeyqkQbs3TC13VU8/J2H4YthZkCK4BGLmX/MHv1grUFFiJdgifW1waR2Ix7j7s+NoLgxWxTu2EZRIf1QkfG4qb24tRInxkcMzEvtQE4s0EbqQ5ZbZ62q2F73B+qfLtWpnUTBG2LhZr3StzAtWP/MKGLhAHzIS24RkYRDMKRt+MaQWC04K2v/CMxD+Wd9yTBaoB++6ciQa2vZlU7WI1FdWbF5S212ghij8XHUm9jiKHBaN0E4f2+Uy4sMRjYM8Iml+8ImG42gxck4JeOzDAgpqy8zSKWpmekQ/XlVVBjIgj0vwyi5cvi8cCKKNKnQhpdVkzM8lD1lBKRKvejATi7l4D1DHUphbSczViWDFW+XSvwugkCCyGsyNoEU1ivq0fNg2rlzy0J0bVjJVVKY1Hnk0UEQbuiOWCg7xJW/34CR5rzWWD12whGDd6MmOeczkJ2sKbNdl2Bog3rGkHwPPBc1tmuLmx63V8nQXCwKOpQmdVDU0lstbF+KgWLmbdbYEkcqSaa+1mgMNP0S9PoAyZjIgh0tZgltklkNkl8cO06F8LKhNl9KRDOK4MHRgPw7S3e05INxN6Rt6A5vF3zao5kdv8Vbajy7dqT10kQEC0z7C7coklZxlIoej9qHwKKCOLOVjb2RTLCuIaKzKuWvXkt55y8OhKVZm2PM3o256m8yW60AqkRRJ++nqn7UuM0BMFfZt5ZoRNF+uRseuKx2cMGpxf0iLUlro+LaRqbYKWw6Ux6Nls/4e5lX4IyGeX5dVDO47jrYyII9lDQNbdJtLmf/XBLdE6jZskUDcAM+NkTpGxUor4qpbbf0VHl8PZQ5du1p6+TIFD1MqPukmhV3ma90+R3ZPvHn0Cu9aeIIDjlzwn/rHD4kz2sUrypejS54BBhNC7Vnsu46ftqpOasEQSrXVYRGykNQXRtSkaFz8wk2yrNBhA6xVL22A+shJYh0WEgLKK43lew0vEb4ixD2XhrZEwEAbF2LdXPZnE8ibRZI5WYLkIQfVVE0WDiybtve5fxPUGsqny79tB1EgSzc2bpXfIGi8AeXik1a6QyzqIE0XdViJELfaOU59kPDrUhJ7Lwo6Cy7B/0daURqaNwmVGe/YnGh+yEq6tNVna/IYgIzK6HYhIZqXC60jX3o4NrzSnabB5t8bDQ8QdkMkvhKE9spJlZlOJnGmMiCKy7utwDRASRJdhFCKLvSzM0QayqfLvWJuskiNqpa/8+RASxY5EwA22TRQhinm9Ss8fmrez22LVmAooxy+eWMdBU8vArg2h8eKulxRpvY2WdBMHeAXsIpWAR4F1IzAseekR/cA6TtoPmyDBaVvtN1yEJgtPMkF0pWVcb2ZctIogsgS9CEH2tkIYmiFWVb9cac50E0WX23fS1iCCwfGKV3SaLEER25Vo+H59rXnVTknuE9xxDQzVJaSxDpD7jwzLLsVBe6yQIjqV7dU+fjaiuiqO+Qo1VCmwNa/eVaBBCR4/+u5E+HWBRX0yYgOK/pZQsQXCA6YwJANZFENnyNVUYmiBWVb5owMqY+jY4XNX+8abhtVVBpH7NuilZB0H0tTwEE2bwv3P9vDzDVDOxT7waqShY2JWqpz7jQ+oBQ0RqCIIBo82PiC/LX+0CJwm7LB7a6sChNq/zRC2E241lSGRJ0+UkrPbcyLQPT6OlaVqfDrAoQUTWFyKIva23yj2ITSWI6MDXthBEzRy2bZyIVEyYX2N1hNTOSJVmsPOOQ6jemYyWexl9xod5n7v0dOs0c8VWmPMEpWRVGBkgok1wHMB5s9iuvMAocjTnsevTARYlCA4IclCwFBHEtAmCU8yNG/cGiW0hiL5qPeq/a8Gr7HCbwd4nElk59jVA6Bo7yvt9xoc++a407joJIrKz5/wC5xSysmMRvU8UlsCYr0Ub70+365i/9REO53zTJYjcbfTpAIsSRGSeJ4LY20hTXEFgocP5llK2hSCo0zEteJVR23scndxm0oiHACR6r7nex8y+zzjSZ3zok+9K466TIDiUw4ZpKTA4JphtJzLL+MwIvFtoiAe99I4F7xaA5+HMK3LaVQOa/L2b73Kp2qTr0wEigsCFgDf7jcpU69giiL1obQtBcAALtWhGoknDNhFE3/3DyANCaViCmw2+Iuml7zkI8jnAQjmWYj3VfD9lnvEh096DxFknQdQaiJPLOAXrEsrOwRl/PgFrCQimln/fjsZZB+8hMvJj1Icg2HvxH3LJqtfwYvrkABwRxLgJIjqYuIjFGWhsE0GUZxi6xga+CBd9fQg8WwAABi9JREFUtc5vHEck0uc5lINzFZh/lxLl0Wd86KrfYPfXSRBUEl8/uGAohU0ifKZ0CTMr3AqX4q0d8AHvv3J1sF3DV0tG+PKanwmQzm9Qc61PB8AxF15HS6l5iS3jsMyGFCPXySKIvUiNcQXBSeFDgk6ZORUe+TQjq20iCOqzvwXvZTZ6jyMDlWjQjk5bk9+Oha5zHcTDMSAk7l29LOrMMzM2DRJn3QRRU5dwwM3b+ZeAMBP4ajBQeidZuGAoTVGbPLq+Dkc8rCD4joQfjMuNrrJMfQii5ueo7cMmnFzHJ5R3gteUQQSxtzXGSBDROQFqxJkXXKjXBBKo+Q7aNoJgEoX1Uc2TMBhF1lxcRwvg9xIxheVshH/HcTuC+5A2Z5ZoKNAC+O+SoCaH1L2FZ5/xoaW5h721boKgtpFNP9dRo9DBPdAMrjiai74hwTV/fP4gu4Z/ey+odGjcyFR3x67jjyX6jGLNTUWfDhDZaDflw3MsK5/Scgp/U8yKdlu6hwhiLzhjJAhKHznC4zoqTVxhlJ4LWHFw0LT2YSvSbRtBUCfMjPE6i8+1UphAMUGMHPqxWq99I6T2XQfIiLMh0QHAHbuOqfmFgveR80lPCq73GR9aXvNhb20CQTAIs8FWkz12A6d7zLA4vBV9DIS017AQfbthP7tec/KFP6L3W2i+OEdcvnBX+wwgJrK1byX37QDsszBLiYRZCKo2ZjB8rD36SpZPJ4LYi8hYCSIyzS7bmT7BgLVjATPNLtlGgmjqzLdfeG8hBsgyGqybuLWvvHF/HwuMAd6VTpOWU9yQxSEz3M9qf737/yYuKm78VEVubPqOD11tO8j9TSAIKhqdAu0DQNeJ05qusc8z9lhkzh7Ulp19OwCd9ot9ClDE5Stw3k2JCGIvQGMlCNxDoBLNTAh812GF6Scv20wQ2VeHTWT2H9qEiSGfPo20EtnnMNlkMhd5fiaPvuND9rkrjbcpBEElo493ZCrPYTuWdV3fKIisDTL5E4ePGPHlqz+2JJinA0Qb7V1lQseK3pQylSKC2IvGWAmCGjBxYLCKDBFqfQPzaA7K+f65LQSBuS8ucqJPhra9LzV1T5QG1TErgMzKzKdH7cWHybzZfhlvnvGhayxY+f1NIggqC4M/xoK3bIqAeL1dZLM5+i5yDThUR6w2Mh9fJw9mBXe0wIduuryfYtHgX1A6NAd22uQcdpMX3H/TwKfBYotPHHK2IzoFWrPw8K7Ks1ZiuDPHEKCUrpVaEzc6O1JTAc5bvuZZkSNFXkbcdC9D1lG+fa3g7MHVDBKaeqFigQSwtENVguuXklhqX4iLPoLVZiBR4hipRilvm5qY9NEHvGonpH2bNhZIu5YPp8W73hVw4VzRZ3t2ADBEzYchSoageZfYqOZwbnSmonz8vONDzyosN/qmEURTOzwhoufDRxR+29nU5UWlQ8HSnE2I7Jyz6DBLI3/2M8ifj6ojzMzp6HwakVPdn7KwiL+pbHmIh9UU5rdYaDGboW2oI3VFFeUtMPrkrbjjRABz6stY4JOUDMIMModY4D2gX6COitzAjLO2uVLzXjDBY88BXHYsoPbl3eV9wQLJT2xyOe+NBc68i4wRqPuYuGK1xF4m4xAmsLi76fNhob5l2Ij4m0oQGwGOCiEEhIAQmDICIogpt77qLgSEgBBoQUAEoe4hBISAEBACIQIiCHUMISAEhIAQEEGoDwgBISAEhEAeAa0g8lgpphAQAkJgUgiIICbV3KqsEBACQiCPgAgij5ViCgEhIAQmhYAIYlLNrcoKASEgBPIIiCDyWCmmEBACQmBSCIggJtXcqqwQEAJCII+ACCKPlWIKASEgBCaFgAhiUs2tygoBISAE8giIIPJYKaYQEAJCYFIIiCAm1dyqrBAQAkIgj4AIIo+VYgoBISAEJoWACGJSza3KCgEhIATyCIgg8lgpphAQAkJgUgiIICbV3KqsEBACQiCPgAgij5ViCgEhIAQmhYAIYlLNrcoKASEgBPIIiCDyWCmmEBACQmBSCIggJtXcqqwQEAJCII+ACCKPlWIKASEgBCaFgAhiUs2tygoBISAE8giIIPJYKaYQEAJCYFIIiCAm1dyqrBAQAkIgj8D/B+j13AMNpm6YAAAAAElFTkSuQmCC"/></switch></g></g></g><g data-cell-id="nHGAu0euJ4534aWflK35-27"><g><rect x="301" y="171" width="70" height="30" fill="none" stroke="none" pointer-events="all"/></g><g><g transform="translate(-0.5 -0.5)"><switch><foreignObject style="overflow: visible; text-align: left;" pointer-events="none" width="100%" height="100%" requiredFeatures="http://www.w3.org/TR/SVG11/feature#Extensibility"><div xmlns="http://www.w3.org/1999/xhtml" style="display: flex; align-items: unsafe center; justify-content: unsafe center; width: 68px; height: 1px; padding-top: 186px; margin-left: 302px;"><div style="box-sizing: border-box; font-size: 0px; text-align: center;" data-drawio-colors="color: rgb(0, 0, 0); "><div style="display: inline-block; font-size: 12px; font-family: &quot;Helvetica&quot;; color: rgb(0, 0, 0); line-height: 1.2; pointer-events: all; white-space: normal; overflow-wrap: normal;">Stack frame</div></div></div></foreignObject><image x="302" y="179.5" width="68" height="17" xlink:href="data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAARAAAABECAYAAABJYmpAAAATp0lEQVR4Xu2dBbQlRxGGExxy0CAHX9zdfXAI7g4bnAAJ7pAN7hDcWdwtuAQWd3fNBncI7vB/OW84vZXq6e65Mzf37a06p867d253T3d1z99lPW/PPYJCAiGBkMBICew5sl5UCwmEBEICewSAxCIICYQERksgAGS06KJiSCAkEAASayAkEBIYLYEAkNGii4ohgZBAAEisgZBASGC0BKYEkNOpF2cTn0V8VvHZNz7/UX9/IP6eeKf4cPHnxX8a3euouMoSOKY6x1pgDcDHE/9Z/DLxP1e549G3dglMASCn1W0fI75dw+0BlSeJnyv+dUO9dS56cQ3+00YAV9H3Q1dIKLdXX16c6c9JdP2IFeprdGUCCSwCICfQ/Q8QP3bBfjxN9Z8o/vmC7ezu1TsN8ENmkNfV97evwMDROl4qvs1AXwJAVmCipu7CWAA5qTryMfG5J+rQj9UOu+m3C+2dR78/0JRh4doHa6JurVQzqwwgzN37C9IKAFmp5TRNZ8YAyLF16/eJWdBD9Ev9CDBgD5+yoruYNfhNhjSR6+n3t5q27qvvT61of7MXWWUAwRS964CAmdtTi/GFBO1GEhgDIHfR+J+XkcELdR2TBKfp35MyJ9JnHGpoLI/bABWviVfr4q0G5BsAsqtwVsWEYUO5qpm3N+j7vcQ/E/93N3pmYiiJBFoB5Piq+wvxCY0U0TSuKf5ahXRPrDJPF2/NlD3fQDsBIKsJIJieaI8psVl8s2I9RJFNLIFWALmaxvpeZ7yX0rVPNcrhbir/HKfOg3Xt8Zm2AkBWE0C+r26d2cwZ4dtUC21cHlF8M0igFUCIltzfDAxzBjBopWOowhfF5zcVP6rvlw8AOYoEOl1Z1SiMByCta6t1/UT5FZBA6yS/Xn2+ien3LfX9NSPHQtjv5aYu5tDplwgge+teZxBjnuH4xWaf2tl3LLV5DvGpxADnccU7xSTV1SbUbSYAwWmK32tRQovBdwYhr1pZIV+c98j7rxtz+iv9/feiHRqov5d+O6MYf88PxbVrCDnhYGasvxGzBv8xYT+RxSnEhNqPI/5pQ9+K3WgFEEK3lzGtYlYcUryTX4DM1e84P6X9QrshiQoijHsxU576n0iuAUhDYV0mDOAi6enCmX7zAHxdvF38OvHvR44Pf849xLcQW79R3yQL5iViIkks8hx1zrhqnaj3Vl2r6XEfskN3jBgbD/Wtk3oHOm0clFwjA/UJ4n9tXANMH2TqPEzff7Jx7Vr6+0hxOj9313fP5O2buYQ+UObq4lzUj83p3WKS3WxSXk4M9DttDz/fUzYKn1x/99u4r70n80qKAQmTAENKbFj7iu8oBugsERJnHbMxjwE9ssFvLr6p2Jt3+oYy8KoNOYx2crcCyEd0w8uZ0T5a3x+ek37hOvd/kZjQcE9kK+4v7gf1Ln3GQVtLmFhPdgqjYWwTP6C2oaTcM/WZcHFtKjZJdsiFB7eFqMOD492n0/UxJgz+JJs7Q5++IiZywmJqpZupwmsbK6V5IMwn85oSfrQviwkJe1nNOQC5pMoT+eNvC31Dhe8s/nih0h/0ewr+lL+s+LZiALiGMMkxzSGAgw2jhvA3AtS12dr0Ex8iXEuMByD7Vm2FtFwrgICIIFtKLMArjO1ARaenABAES/7IlSrulytCiJlFU9oR0HDeJu5G3osdywM52msBEOaWtgA+S1/QBRzidmes7fIcAMIauo8YjdYjD0DQSD8pzml3NeNBu/3sQEEPQJhf/IG1xDOCJgBgsUG0ECCyj/g/hUqYa4TTPY2j5n7k8Ty/pmBaphVA0DQ8AaDyM/FzZIROASCoviVHL2MoLcTcw93LFF/HDrE181rnxTMLO0e+OROGeUXN9jQgHhbU/N+1diopPweAoBENLX4LIKdRecwQzwTou1ozp5TB1MQf5ZEFkAXENroqJvcrB2pjPgGkNhLWesNmf2YrgBDbxzeQI/wR2FUg4efEvc3bOpC0/IX0BZsRurL4nqYxEpa4Z0/srj9KvnPYD9vXEgsHUMF/gtMLzQIAwH4kmY0kKAso7CQgfY6w4x+VuRcJdNid9I1cGO6Dqu5lcNI3HHLpQ97pe40GgpP2YDG+F0uE2jEfxvp0+vZwPKPG92Szg+l/ei6GdcBG0JulngmTkylz9xfx/cTpuR98Rh5AImO0A05/94f30ApJtweEPC0UFT53CLAEIKy37eKvijGT8dGl/p/cuLj+LDEgyJrAkXqnTP/QQq6RaYhnGI3oOs7vrFfWHdFOABKAQePqxGwiHp1XF4ee8V3qtAIIlXlYQaoaeqcK7RCDjgyChbAIjckDYdEwUSmxC19fjEc6RzjweO2ApTPpwk7nes4hDKgCfB6I0UzuYbJaSKeyJQABPBirp21hg19bzAMxNdkwLv4FzIsclQCEhxJw4KHMaUqsKev34AHEp5Yj5LNdbA/9AR6AiEdDAPJQVQCs7EaJz+PDA/0AyPGFeH4HHNLbnLony8gi51N5i8ojj5yZ+gj95gEdGzLO1yoaAyAcpEMANvOw5obUwxFLNIeHoTYs17c9BkBwsKFNpITH/jMVHeY1BQ8x5W6k72926mIyYMNbQpNAwxkiz9HJDpv6L7oNmaXtpCYMYTockCwaSx/UBWTXKu8KER1ZZEoAeYbawwc0lIRGONL+zmYFQJYIbcS+VgCQJzLkUQ5AhhIeaQcgu4PTINoZm1DuwUYLPkxsTTM2NDbhlHJla0EgpzGzGaLBFWkMgNAoHnU8yTco3mG4ACopYVK4xtwZAyDWh1IyQ9Ie4zC2OS6YHTZ3hagLhwCtycMOVfO6A29R4xO4QNKZTp9zGgjg8QIxoWlLhATRthbV/oZmcioAQUvCmVoKK2LWoqWkxE68fXi5/f9X29+hNeEBCNokgDMkU2/t0AFApRSF8fKtiJh9wIyPeUXTSAmAOqd4SLtOy7OmOtNGtUN1LID09wMV2SVrTZrc/LID0M47CgtgDIAwkemDyL2Iz9eQl27vAQihbTQrS9i1te85eY/KWrs0DX0yyR6AkNfAbueFPtmVSfwjmWpOmgpALqhOEsotEU5D6/9A+yppen27FhRaAQSgLq2h3CsOSOwqJYp5GinrmI02JTYya47l0hhyMvUc4rUazGT/F4aFjt0HSoKKQ57xocVRUgvHAEhpMeZ+ZwzYsdaz7QEI4GdzT/Cz9AlwNX3AQd1nXVIepy4A0FOnDxZAMKfQAtOkrr48dW8s/lvNzRcsMwWAtMprTJfR1DBn7Vy1AshF1IbVgGx/LqoLNjw8lGWd1sc3gY8iJS8Sw8FWm8CGX6g2SY72SYazCYxDJt0unVpUA8lN4hb9gDea5CBU0lzGp1d/SMWbGkCwIYnSkDqPrwKm7zzMuVCsByCeY5mQN4lhU1GnhlrC5ESrrPN4qr7YdqYAEF4FQZ7EFISfjjlN5xW/A2vRy1JtBRAicaUEPM/MGoqmpOOuARDC2H3mbloX/0VtGn1fzzN3ANtS7slkGkhp0vENoKEQiippKNhwCAF0tbQogAAYqPQkUV1aPMYR7AHIoWrLhgdJX2/N1hySY6cfWwCEtniActGf0py1/D4FgBCm7VPEW+5NWR5WwspEu5iHUj6Pbb8VQIjmjPHT1IJkDYBgln+pVVAN5fHL8SwO0lwayNBNuSemDh5gmxbf18vtnosACB56zjWgXSxCHoAQ7rValuf0WuS+nSq3AghOaiI1c9MUAELeyrMbO0ouDccMWo46eLdoARBelsV9S+RpILUn12sAZMx6KPU5/R3TppipfHQASNpJzmh47/7YoetXdEY7BkBQZ0m0yYFVTqi9impVXg9ASASyfh9sYC+PpGUS07JjF4znfBvbh1y9owNAWs6ipP0mamGjhy0AUspx6e81N4CwMbCu5yJM+2IkpwVACBNy5Dgl/BW1B8y8gXJ/1HybuJKb0FYAof03OQvG9gVn13fF7C5k4REJ4DtOSmuGeABCHavZAFjku0xFnRrKaSDkunDEgDeDWcBDDcURXHsga0x/lw0gpJ4T5h4iTDfmhb4xl6j71PntxrXUOb4ZAST3cq/WF3t5MsTxjsZe9KW0AIgXDyfeXHqTemlB3lAFeMgtcULX5oa0Aggp6d4ZAh4qPPHcl/7nclC8EJcHIITXLAguywdCohvpyhA7q5fk9gpdZ8eei5YJIPixAHjPFMVJybknTpgOqd+L5IGsigZCkMImQ7Kup3gPS/U6aQEQJs0ediL/vpS7UepM7nwN2YZWu2kFEO/BZrfBG19zfBkNy6ZGewDi2ayt8XicuuysPQFq5Br0nvBOn60Ggh+JbNmUmA/ep2EJPwG5JnPQMgGEsxqkuFsicxdHbMm5Sb1F8kBWBUAI+aNZWcJkX/SsU/UaaQEQ71Ts0BmC2k4ASjZ5KIekLQCCpxxBWo88yVoc9qshzALCsSl5AEIeBrt8Sq0OTHYT+7Ik+t6nn3f6nMtETe9LuBJTzBIqPWBd9KzXCMaUWSaAEEUjUzMl1HZSBmqIrGGrmm9GEwZNzHMftOaB0M5WcYoFbK79+0sGZdoCIJxPIIphqcrZMtCL/fSb9b7bNO6+eguAeAkytJM+lEPCQTYI0oZ6PQBBe/BeTIOdfVjFqvYeelLQsXN76vShBkAoj/bDIS9LnDM5oKI/rUWWCSDb1LkDTQdLr1lIi+PXeqOpvxkBhCFMsalziJDwckrVikELgHiaAjfFE0zGY81ZFrswUbd4SK3jDzuWU7SWWgCEtnGYWapJJaaOt9Nx3QMQnMuokzYSwzkYzsOUiBe52CQqUrX59xc9dfpQCyCYfxy88vwEJMilr4As9a3m92UCiJfmzcZmX5Ho9Zvj9ji2bch9swKId9KccW8RH14xcXupDNqqff6qUxBaAIT+sIBZyJZQ3xlMi3pMkhM2ubfI8VF4Z0s8ACHb05oZff+8VN999CPnR4aIpKScCucBCG15ZgzXS36i3NF2+14G5F4LINwXoPCiQKQpk4Q0ZYr7MgGElG57mBEThqjX0CYGeGwXe0fVNyuA4DDFNLVmOps659OGDvthuuA3su/X4Rnm1QFVCkErgHj5/f2DyCSQ13GI2Nv5KYf9ifOHiEB6VL1vg7+EVLFnOQtiCWDZYS6CoDzwvE3dEhEJG/NHQJT3woCkB3MkP9c32men80w5Un85H+G9VYvJJBycOvgoz2E9EqEs0Q6yTst3+t4CILRJ6N073o/Td5tz37GXlgkgXn4F/UaOmG72mD8PCgfbDhYPZR7nNFPrcF0VJ2o/V7n3erCGyPpOX67V19miD4CwlxvFWSFkVUWtAEKjOV9IekN2BGLw5B7gzCTcywtmal65NhQaJgMw954CkBjEJazZh4W36jORDI/QmtihqQNwdOKajEaAkoxCnJuYHukLenKxee4PcPFeDuTC/XKp9JRDxbbjpH+tALK36uCD8VK70UJKuRQZ0R3l8jIBBPOM/3jnrSXWAKdyGTO7M4CBZuidf7GDwOmN1otMUif7qgMI8uDQZ+6l0oS2AZOd4i1iTjzn1jkyQMuviWQdKb8xAEI9HHSg/ZTEg0N23Y6BRnMvUEmrpOFTxodQvLBmTd/RNPYV5xYgYVf77zxzLxaquR9l2DW8DMNO11sBhPZyGZtoeoBYlapa6PwyAYSu5JzWNTJmA+B9HDmfCREe8n96WnUAoZ+4A/BrjT0FTxvI5VzinPXgynYsgNAYQsZ723pwyesI7x/AbPDULVs+5zjqy9n8C97JQRZizS6U3ovoELvZECB4AIJMCf+So9FCACjaHdqNR50ujgEQ+sMO5amryBw7eFFaNoDQXzRNmwNTGgcaIFEHtMf+qIKtsxkBhDFwQpjN0qYClGTC75hl+Oq88P9g/UUAhIZRxTkEBbcCCRPIcXNMjJYTo/R5f3EaoUgH6SVwoc5uE9uX0HjC2a6L2JU9mOFQwq/jHe/3AKRvE5WSsGnNhKLpoNUNoT+vYbRpyrXe8lyyHqBFtMrzNw0uHPOjTeUvvdujU30LhjVv6rJ94rwUiX4l0xjHMc52spJ79TyXpWwBxJ5zqs05wRS3/1ycIwfeay/tuNCO+uzi/jcinV7GdloXcwafF3VrnkfGwgbCS7FHHUlZFED6zhMO4rg+Dw0OSlQpdv5+EEwgYU5CSzALDjtzVKc3bkrbOGRZPAiOh4E3UjFpuXZxcLIT44/hM555Fgj1eIs8psMR/aCSv4RpUZuxHxkrai3Jb+R+lMZAH3mNAf0kZwbnKf4NmJ0bWeR2Q6crcclIgDnk3EY/p/jJAGLWGb4QMnNzhxopy5rlL85X3q9B9K0mBLrKE8Ea5dUG+DrwA/E8Yv6zzlnvjA+5tLx4yB3vVACyysKMvoUEQgIzSSAAZCbBRrMhgXWQQADIOsxyjDEkMJMEAkBmEmw0GxJYBwkEgKzDLMcYQwIzSSAAZCbBRrMhgXWQQADIOsxyjDEkMJMEAkBmEmw0GxJYBwkEgKzDLMcYQwIzSSAAZCbBRrMhgXWQQADIOsxyjDEkMJMEAkBmEmw0GxJYBwkEgKzDLMcYQwIzSSAAZCbBRrMhgXWQQADIOsxyjDEkMJMEAkBmEmw0GxJYBwkEgKzDLMcYQwIzSSAAZCbBRrMhgXWQQADIOsxyjDEkMJMEAkBmEmw0GxJYBwkEgKzDLMcYQwIzSSAAZCbBRrMhgXWQQADIOsxyjDEkMJMEAkBmEmw0GxJYBwn8D3IOYIFrYk+0AAAAAElFTkSuQmCC"/></switch></g></g></g><g data-cell-id="nHGAu0euJ4534aWflK35-28"><g><path d="M 226 176 L 226.04 236.04 L 294.63 236" fill="none" stroke="rgb(0, 0, 0)" stroke-miterlimit="10" pointer-events="stroke"/><path d="M 299.88 236 L 292.88 239.5 L 294.63 236 L 292.88 232.5 Z" fill="rgb(0, 0, 0)" stroke="rgb(0, 0, 0)" stroke-miterlimit="10" pointer-events="all"/></g></g><g data-cell-id="nHGAu0euJ4534aWflK35-30"><g><rect x="25" y="45" width="30" height="30" fill="rgb(255, 255, 255)" stroke="rgb(0, 0, 0)" pointer-events="all"/></g><g><g transform="translate(-0.5 -0.5)"><switch><foreignObject style="overflow: visible; text-align: left;" pointer-events="none" width="100%" height="100%" requiredFeatures="http://www.w3.org/TR/SVG11/feature#Extensibility"><div xmlns="http://www.w3.org/1999/xhtml" style="display: flex; align-items: unsafe center; justify-content: unsafe center; width: 28px; height: 1px; padding-top: 60px; margin-left: 26px;"><div style="box-sizing: border-box; font-size: 0px; text-align: center;" data-drawio-colors="color: rgb(0, 0, 0); "><div style="display: inline-block; font-size: 12px; font-family: &quot;Helvetica&quot;; color: rgb(0, 0, 0); line-height: 1.2; pointer-events: all; white-space: normal; overflow-wrap: normal;">t1</div></div></div></foreignObject><image x="26" y="53.5" width="28" height="17" xlink:href="data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAHAAAABECAYAAABZC7HwAAAC9ElEQVR4Xu2bz6tNURiG75XM+AtkgKQMZMBAysDISBmaGCgl+VFCKZFMlESZMFHKSEoGpu5ImZgqiUL5A5SJiXcVtVvtc/dZa7/Ht9e9z66vu/fZa73f2u9z3nv3Ofec5SW2ph1Ybnr1LH4JgI0/CQAIwMYdaHz5JBCAjTvQ+PJJIAAbd6Dx5a/nBF4Xu1sdfhe1/6A1nlMHuEeGXs1MfaLjNyONTtf9SbW9o5OA3h6p+9+nTx3gMTnyMnPlko7vjXTqgOa/yzQAONLUvumLALhRjV6pjgJwAcQySTfADdJ/rDrVs3QSuACeDoApcbtVx1Uns7973SUDcEIAD2ot6a5yr2rXnOsC4JxGlQyrTeBpNXlU0khjAVho2KzhZ3Qi3SWmLb2M2J8N/Kjjt53Hnmo/f1kBQBOMGpnXmpTfIa6mc1kn72YDAFjjvGmOA+AWrSXduMzaLujEiewkv0InBHBoKTc04CYAh2yqO79P07b9nXpEP89lMs91/Kzz2HvtfytsBcBCw2qH196FDvUD4JBDpvMAHDByvb6ZTQJNCRuSIYEksNcBEjgUHdN5EkgCSaApTFUyJJAEksCq6JgmkUASSAJNYaqSIYEkkARWRcc0iQSSQBJoClOVTF8C08ff03/Px2y8lTbGvYK5hzV2JRv/WceHVD8KdPKhABxhXsnUHRqcvoTSt33Xg79U11QvSkQ1FoCFhtUOT5+q/qLauopA36fShvoBcMgh4/mz0noIwH4Hpv4f+bTqtMbzqvszINYk8Iq07mR6jq+tGZ+380m1APDflWzWzk5V+lLmJtVP1VfVB9Xv+S537Y1qCeDac99wRQA0mBgpAcBI9w29AWgwMVICgJHuG3oD0GBipAQAI9039AagwcRICQBGum/oDUCDiZESAIx039AbgAYTIyUAGOm+oTcADSZGSgAw0n1DbwAaTIyUAGCk+4beADSYGCkBwEj3Db0BaDAxUgKAke4begPQYGKkBAAj3Tf0BqDBxEiJP3l1kUXurN51AAAAAElFTkSuQmCC"/></switch></g></g></g><g data-cell-id="nHGAu0euJ4534aWflK35-31"><g><rect x="215" y="45" width="30" height="30" fill="rgb(255, 255, 255)" stroke="rgb(0, 0, 0)" pointer-events="all"/></g><g><g transform="translate(-0.5 -0.5)"><switch><foreignObject style="overflow: visible; text-align: left;" pointer-events="none" width="100%" height="100%" requiredFeatures="http://www.w3.org/TR/SVG11/feature#Extensibility"><div xmlns="http://www.w3.org/1999/xhtml" style="display: flex; align-items: unsafe center; justify-content: unsafe center; width: 28px; height: 1px; padding-top: 60px; margin-left: 216px;"><div style="box-sizing: border-box; font-size: 0px; text-align: center;" data-drawio-colors="color: rgb(0, 0, 0); "><div style="display: inline-block; font-size: 12px; font-family: &quot;Helvetica&quot;; color: rgb(0, 0, 0); line-height: 1.2; pointer-events: all; white-space: normal; overflow-wrap: normal;">t6</div></div></div></foreignObject><image x="216" y="53.5" width="28" height="17" xlink:href="data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAHAAAABECAYAAABZC7HwAAAFgklEQVR4Xu1bachVRRjWEEtFoh9qYIqWEaFiuYRELlEpFhVh6g/9YVBguSCIZZGpIIoUFZGKgmbbnzIIgkrN3FDDJQq1DTV3RcSljfZ6HrkHDsOce+a999x73zO+Aw98M+eZOXOf58w5M+/M17aNpVIr0LbUvbfOtzEDS/4QmIFmYMkVKHn3bQSagSVXoOTdtxFoBpZSgY7odS/gX6ATcBI4U8ZfciWNwDth0NPAIOAGj1mHUfYZsA14D/izDIZqN7AvRHzGEfIN5DcJxO0H7iLgQUGdL8B9tDIyBdWaT9Vu4MOQ5ENHllnIvxwo1e3gfRnIdWk/o+BeYFeN9ZtSLWYD+1TM61yHkj+gLt8Cf9fRRkOrxmogJyn7gBs96nFEvgLwW/cHcAswGJgH+MyegvIVDXWhjsZjNfBJaLLMo8sSlD2fMaJo5Mce0/kqvR74rQ6dG1Y1RgOvhlrHgK6OasuRfypHSc5Oj3s4Q1C2p2Eu1NFwjAY+Bj1WO5qcRb5n5ZWZJ9drIEx3SGxzTV7FVlzXaCBff3dUxOAEgk9/OnFisSNV8Bb+Ti8rdiI/1KnzHPKLAwUeBd46h7sQ+bmB9ZtK02ggv0NjBCrMBvelCp+Tl189dbuj7FRgm3wF93e4R5A/F1i/qbTYDBwO9bY4CjKqMqGpqjbxZrEZ+Cy0Y9QlncYj836GphyxKmeXoc+ARgMZPeGEg+kewJ1Q0Ix3Uz+Q67pk5uh7/SYzyA7gjQbGAoyLJmtELhN2A18D+wGO2F9CBWw1T6OBaU2kobRDKWOSdrrhD67x1niu+fTnjHUasBb4r9UG5d0/NgN/wg92oykzUfZqnhCe65+jbHJqdNfQROOrxGRgO8j1V8GSbUd7IwGLhdYorOQVeh3ucT7gPt+AsxX4DrgWuA3gd9K3R8jmJGvIgNsXS4lpBPaGNNyUzUqcrMwAuPDnTnw6XYUMF+rzMyoz2L23WOmLaS0mAwdAkq8yZKF5twI8OlEtTcLFtz2EVSh7vBjJi23lSjGw2lrQVXQ9Cu5zCrnMSMJ7xTpQZ2sxGXgTtDjo0WMzyu4W6MRd+A0ePidJ/wjaaQo1JgO53vOdLOMe4ByBmtTE/UayOh+Qat9YwS2Ko8ZkYFYgu5atIE5YBjoyM8D+aXHSF9NSTAZSEd9C/iGUfySUy/cd5HeRxw5VpdgM9AnPWOrrQtV9ITnGZ3279cKmi6XHZiB3IrgjkU4hRynSfO4H/u60wWUIF/3qYqOxGeiL3FB8jp6Lgc/+RPDecbgMqd0VWL+ptNgMvAbqcTfBDWi/iDIeq89LXCp8D7jHEaUz2bz7FHa9jAbmnU+h2D6z7kf5J1WUYziNbbuvYI5gHhLmg6EuaTdwBBTb7KjGtRhfZ6cz1OyB8gOeUUg6RyJjnjzQm04csW8Cj3ja5N7gUnXOVTqk3cCs6Aq7fwLgcQjuFnzgCDwOee6s+1KyA8/TbRx1jJEOy+By54IxVttOqvEJ5jfpRyBrq4fNpk+lpW+zAJkXarwvq9FohuBU7kIkv0v7CGQ/pwLV1nFZBrLuE8DKGkzk947nQ3lORnUqg4HsI/fxso5FVDOQ4t8M8NvHJUZI4iSIuBBCbjWnDAYmGnGiwdkgp/jtAb7i+D8Q3wIhRylY7wGAJ9I40ekCXAI42o4CGwGegwldL7bau8v3L5OBKgTT1gkzUJsjwv6YgULBtNHNQG2OCPtjBgoF00Y3A7U5IuyPGSgUTBvdDNTmiLA/ZqBQMG10M1CbI8L+mIFCwbTRzUBtjgj7YwYKBdNGNwO1OSLsjxkoFEwb3QzU5oiwP2agUDBtdDNQmyPC/piBQsG00c1AbY4I+2MGCgXTRjcDtTki7I8ZKBRMG90M1OaIsD//A3/b6UU/mVloAAAAAElFTkSuQmCC"/></switch></g></g></g><g data-cell-id="nHGAu0euJ4534aWflK35-32"><g><rect x="177" y="45" width="30" height="30" fill="rgb(255, 255, 255)" stroke="rgb(0, 0, 0)" pointer-events="all"/></g><g><g transform="translate(-0.5 -0.5)"><switch><foreignObject style="overflow: visible; text-align: left;" pointer-events="none" width="100%" height="100%" requiredFeatures="http://www.w3.org/TR/SVG11/feature#Extensibility"><div xmlns="http://www.w3.org/1999/xhtml" style="display: flex; align-items: unsafe center; justify-content: unsafe center; width: 28px; height: 1px; padding-top: 60px; margin-left: 178px;"><div style="box-sizing: border-box; font-size: 0px; text-align: center;" data-drawio-colors="color: rgb(0, 0, 0); "><div style="display: inline-block; font-size: 12px; font-family: &quot;Helvetica&quot;; color: rgb(0, 0, 0); line-height: 1.2; pointer-events: all; white-space: normal; overflow-wrap: normal;">t5</div></div></div></foreignObject><image x="178" y="53.5" width="28" height="17" xlink:href="data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAHAAAABECAYAAABZC7HwAAAE9klEQVR4Xu2baahOQRjH77VFkshS1rJli+xC1iIKZfmG7kVKIrKLTxRlyQe+2aVky1J8EVeyJWvZhaxliYjs/P+3+9Zp7jn3Pe97n3tmzvRMPTUz5znPnPP7vzPnnJl5Cws0pZpAYaqvXi++QAVM+Y9ABVQBU04g5ZevPVAFTDmBlF++9kAVMOUEUn75PvfAYmjTTkCfrYjxWiBOlYRwXcAuuOulxp3vRPlsDBoP4NMhhl82lxFwOJPNydZx1wUcDzBHDTgLUd6UBVgNHP8lBFUFrATIfAVsjTafVaLd4KkqYCVA5ivgMMFhbzBina/EPVTpqb4OoTNAbVuA3Bfk2SvzSR/zOSmpc3wVcC0ALgtAvID8oKSgJtmOrwIeAsSJAZDbkZ+ZJNik2nJRwNm4+b5lAPgZ0ceA8RDli4G6PcibnxV3UNc54LMI+Y1JQU2yHRcFPAkAo3OAsBi+GwL+1ZH/bZw/DuUTOcRMjauPArYE/eeGAuyN91KjSg4X6qOAfO0/ZzCog/L3QF195NvDfsAeGcdywGff1UUBewBLqzI0/Iiea2A6iPK+QN115F8EykXIc7otk54g0x82C9YLxmdqCyPmXZQZpwS2G2YOwfaVirgCFwUMXmo+H/KrEWClcb/8DqwXUwUKyTfWGzH9rbr5KOABEJ0sQHV92Q/hp0CsKgvho4C3QKubELFdiDMd9k8onngY3wSsBkJ/IihxGKUgx2Fc3+OLTUdYb9j8CsguwLHN4uSFAvomYDNweRXChi8po2AvI7hx4XdLmY/pQuHbwt4JMRcN45uAfNu8ZBDiYiyn1T5lIUcWx2BjQ/yWo26dKHmhYL4JyIXcJjC+cdLqwi7D+L0XJzWFE78LzTfWq6jLTO/FiZOYj28CSoCbgyAcTs1UCxVSq/wS11kaQwUsj3IAqrj8ZKbmqHBuc5MKWF6ohqj6ECJgJ9TdF+s6QoFUwPChMuyZ2QCu2V6EhGSJH8YnAWvithsZt/4Z5a/xcZR6sqfxsyOY3qLAFxznkk8CTgHdvQZhlqflSH0S/DlhHkynUBiTY5xE3H0SsDuI3Qyhxk+JbzFpkscVmLkLgPOiS2LGSNTNJwG5Es8dZOY3HHvU4ZhUJ0T4svexFzqX0ijgGlBcFUEybCWCU2EjYfygryhxrZDbOTgREEycyeG6pJPJdQGHgFqJQY4LtNwi+CaEaNhzMOM2FZn9sLDF2mLU74hQqCfqnV0bdF1ATiI/jgDLiWk+21bAMkMk74dCFFXQXfiD4NTYXxiXnfhjiFrsdX47ousCcm7zKczcAhHUx9yVVhsHT8MGViBinEO34cSh830cZ1s+rgtILlFzkxlmpoCsbwzjcDk8T7D8LwS3czi9rZ73lgYBeY3zYFGLqmECZnQbigxfeuL2Rj5f+X/EIzAOsc6nNAiYgcjnFBde28C4MsC3S+7/5H7PbKsE/eDTFcY/fHKmhX904fkcHmnXYCUwznU6u30i7NeUJgGd7w02LlAFtEFdsE0VUBCmjVAqoA3qgm2qgIIwbYRSAW1QF2xTBRSEaSOUCmiDumCbKqAgTBuhVEAb1AXbVAEFYdoIpQLaoC7YpgooCNNGKBXQBnXBNlVAQZg2QqmANqgLtqkCCsK0EUoFtEFdsE0VUBCmjVAqoA3qgm2qgIIwbYRSAW1QF2xTBRSEaSOUCmiDumCb/wGvqsdF/8GKAwAAAABJRU5ErkJggg=="/></switch></g></g></g><g data-cell-id="nHGAu0euJ4534aWflK35-33"><g><rect x="139" y="45" width="30" height="30" fill="rgb(255, 255, 255)" stroke="rgb(0, 0, 0)" pointer-events="all"/></g><g><g transform="translate(-0.5 -0.5)"><switch><foreignObject style="overflow: visible; text-align: left;" pointer-events="none" width="100%" height="100%" requiredFeatures="http://www.w3.org/TR/SVG11/feature#Extensibility"><div xmlns="http://www.w3.org/1999/xhtml" style="display: flex; align-items: unsafe center; justify-content: unsafe center; width: 28px; height: 1px; padding-top: 60px; margin-left: 140px;"><div style="box-sizing: border-box; font-size: 0px; text-align: center;" data-drawio-colors="color: rgb(0, 0, 0); "><div style="display: inline-block; font-size: 12px; font-family: &quot;Helvetica&quot;; color: rgb(0, 0, 0); line-height: 1.2; pointer-events: all; white-space: normal; overflow-wrap: normal;">t4</div></div></div></foreignObject><image x="140" y="53.5" width="28" height="17" xlink:href="data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAHAAAABECAYAAABZC7HwAAAD4klEQVR4Xu2bTegNURjG718oRRYkShQ2UoqilJIUYSELC2FFIpFIIlaUlK9kgXwUkUgpYocNoXyVfEehiI1SNhLPm+vf9DZzz8w58+iOnqlT93y8z3vm+d1z7z0zc3taOhrtQE+jZ6/JtwSw4W8CARTAhjvQ8OlrBQpgwx1o+PS1AgWw4Q78mf4IlOGZM/mE1x+bcGZaga3WYIB6gjIyA+wsXi8RwHQHJkBis5M5ifqNdOlehVN4tczpnUN9cY05aFLdvgIX4MwvubPfiPq+mhxZCp3TOVoCWJPBTIDjMMdXBfMUwC4H2A/zu4UyRQBrIlUgw1qBO5BvW4epawXWxJUBcCbmdj0wPwHsUoBDMK+nKMMEsCZCOTKr0Ta13W7bCP899RJttzNxtg0os62wX9wXURa6nCtRP+ratAIT+F5F7NwK8Zswdk+J8QbqiBu3C/UTKP7XqACWMLRoCAOgrWS72pI9HqAyDWWUACbQygmtG+AA5LiDMtHlGo/6c5S8/aBWYALTSe1VYRKzUNY6rQuon8m02Up63yHffvStd/2rUP/7cSqACbBCoanbiPlIcMUluYy66f5qtwtgiEJCfwpAu0X0AmVQJv+39kfm50ybACYACoXGAuwDYfsuneMSzEP9mmsTwBCFhP5YgBuQc6/Lewh1/31qQwQwAVAoNAbgZIjed8K2+bcfR99zEgpgiEJCf1WAA5HrMcoYl9OgPiyYhwAmAAqFVgV4DILLnWjoSo0Ahigk9FcBuAh5zrtcdtdhNsrPDnMQwARAodAqAO9BzF/43o22t4Eko9G/Jec70z+28Qhj7oYm/K/7/6dnYvIA1unnYYjZnZKuOgSwPA4BLO9V78jUj9CIlIUhAhjhZhWAB6Fv24Wqh11q83cqTMMeesoedofCLgZ01fE/fYTGGjsUgV9yYOnB3lhHM3FVVmBsOgGMda5EXB7AnYjbXiK27BABLOtUxLgZiLnp4t6gPh2lrn8PCWAEmLIhYzHwdcHgD2i3i9NbUexps9hDAGOdKxHXF2PsSkr2r18+LHStM5RGAEMOJfavQXynn+8CmGgwO9y2OutQDhQkSgVof/D86rSPo76CfWJ16Hf7PjB7jrbhtjsHdq+vP4o93/IO5RnKjzrMaKJGkwA20V/6nAWQbjE3gQBy/aWrCyDdYm4CAeT6S1cXQLrF3AQCyPWXri6AdIu5CQSQ6y9dXQDpFnMTCCDXX7q6ANIt5iYQQK6/dHUBpFvMTSCAXH/p6gJIt5ibQAC5/tLVBZBuMTeBAHL9pasLIN1ibgIB5PpLVxdAusXcBALI9ZeuLoB0i7kJfgNMSLVF+xnnKAAAAABJRU5ErkJggg=="/></switch></g></g></g><g data-cell-id="nHGAu0euJ4534aWflK35-34"><g><rect x="101" y="45" width="30" height="30" fill="rgb(255, 255, 255)" stroke="rgb(0, 0, 0)" pointer-events="all"/></g><g><g transform="translate(-0.5 -0.5)"><switch><foreignObject style="overflow: visible; text-align: left;" pointer-events="none" width="100%" height="100%" requiredFeatures="http://www.w3.org/TR/SVG11/feature#Extensibility"><div xmlns="http://www.w3.org/1999/xhtml" style="display: flex; align-items: unsafe center; justify-content: unsafe center; width: 28px; height: 1px; padding-top: 60px; margin-left: 102px;"><div style="box-sizing: border-box; font-size: 0px; text-align: center;" data-drawio-colors="color: rgb(0, 0, 0); "><div style="display: inline-block; font-size: 12px; font-family: &quot;Helvetica&quot;; color: rgb(0, 0, 0); line-height: 1.2; pointer-events: all; white-space: normal; overflow-wrap: normal;">t3</div></div></div></foreignObject><image x="102" y="53.5" width="28" height="17" xlink:href="data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAHAAAABECAYAAABZC7HwAAAFLElEQVR4Xu2beehOWRjHMWiSrWiYrGGMIWMomrEvEZOSIRokMjEzxkSSJbJEEaGsWZKtlCz/MGOZzGI0UhOyDcYe4g9/KMqW77fet67j3J97Xedxzn2fU0+/3zn3Oc+59/t5771nu+XLaQpagfJBn72efDkFGPiPQAEqwMAVCPz09Q5UgIErEPjp6x2oAINToDrOuDbsCewu7FlwVxA54VK4A5vheofAhsI+t8C6grLzsP9g62EXQgLqO8BWEHOqIegm5I8kELkKfBbDfkzgG3XZjMwC2KWU9d6Lu+8AB0CVvYYyk5Ff+ga16uL4b7CWGVTtj7r7MtQXqZpHgB9AuV9gvTMq+BD1W8OuZ4zjtHoeAU4q4w49jWP/wP6FsQPTENavYDah6dsV9tQphQzB8waQd99t2EcWTb5F2Y4YrTqjnO++JpbjnVB2LIPGTqvmDWAfqHXAotjXhcdqWWJ+hoPnLA7jULbOKYUMwfMGcAO0GGPoMRv5eQk1Yo93oeG7GvnxCeuLu/kI8Aeo0KGgBIcR7Q1VLhqPtC3IF4cVf+L/Lob/J8hfTqhsT/ix9xpNfA9+lbC+uJuPAPdDBXYskqYpcFxScL6Jv/UjFdmT5MxL0tQRjn8bzieQL/6gksYR88sTQF7Li4zi/4T6K4wYW5EfKUYkZUN5AshLHwGrEdHgGv5PMxjnpAEnD6JpFjLzU+oq5u4jwLa4eo7PmHrBJhhq7ER+e6SMYzo+OrMk6sDps+mWIF+g7FSW4C7r+ggwer1vO5WWRrNP4TwNNspSaSPKvksTTNq31ABylqYb7DGsFqwpzDZ4J4e/YINg96WhpGmv1ADa3nE2vWaikOPB52nEfB++CtCu+j0Us+OyBub1gq8CLPu22YbDo32GWGoAOdPCXuWHsI9hDWBcMop7DxLvWhhnh7xMpQbQBoEacDXie9iwGEotUM4tF94lBfgqEk58z7FQ4l6Zsd7RwwkpwFepVEB2N8ycjeHGJw45vEsK8HUkg1HE2R4zVUKBdz3SPAHk9NqXhurdkU87zRa3sFsPsbja71XKE8CDUNbcyMT84ZSK14T/A0sd9lq5j8arlCeAy6DsRENdLg+tSqk41/6OG3U4sK+TMo6Ie54AchjAmZNo4v6YvimV5PaJlUadPch/kzKOiHueAHLpyfa4bI7ypLusObA/C6tmqM/VikUiRFI2EiJAzlFykdVM3Ep/FWZuKeQQgHfhmyBWhc+vMG4jNJO3Wwt9B8iln98NNQmEMyd3LEIPRxnnL83EvTEDYX/AzKEA95KyHr+jsO0n9XpN0HeAHDzH7Si7hWOPYDNguwrEOBDnJqR2FojFIu4yO1kAycXcNjHg6M82+H0FfwBeJt8BVoRqfCxGd5qZQkZ3pfEYH3dH35Ha3j46i9fnO0Cep61XGOVjAuSxuB3aSbkegiOHJLad2kljiPiFAJDn+DNseYwiNoB05Yedc2FxKwy2cBzv8XvC4iNZBEKWRkIAWLw+du0JhWt3lWF8L92A8evasr4eaoTjPWDsEDWGsaPCjgwfz2dgXCZiD/V/GN+NfK8Gk0ICGIyokieqACXVdtCWAnQgqmRIBSiptoO2FKADUSVDKkBJtR20pQAdiCoZUgFKqu2gLQXoQFTJkApQUm0HbSlAB6JKhlSAkmo7aEsBOhBVMqQClFTbQVsK0IGokiEVoKTaDtpSgA5ElQypACXVdtCWAnQgqmRIBSiptoO2FKADUSVDKkBJtR20pQAdiCoZUgFKqu2grZexe9BFD+hePAAAAABJRU5ErkJggg=="/></switch></g></g></g><g data-cell-id="nHGAu0euJ4534aWflK35-35"><g><rect x="63" y="45" width="30" height="30" fill="rgb(255, 255, 255)" stroke="rgb(0, 0, 0)" pointer-events="all"/></g><g><g transform="translate(-0.5 -0.5)"><switch><foreignObject style="overflow: visible; text-align: left;" pointer-events="none" width="100%" height="100%" requiredFeatures="http://www.w3.org/TR/SVG11/feature#Extensibility"><div xmlns="http://www.w3.org/1999/xhtml" style="display: flex; align-items: unsafe center; justify-content: unsafe center; width: 28px; height: 1px; padding-top: 60px; margin-left: 64px;"><div style="box-sizing: border-box; font-size: 0px; text-align: center;" data-drawio-colors="color: rgb(0, 0, 0); "><div style="display: inline-block; font-size: 12px; font-family: &quot;Helvetica&quot;; color: rgb(0, 0, 0); line-height: 1.2; pointer-events: all; white-space: normal; overflow-wrap: normal;">t2</div></div></div></foreignObject><image x="64" y="53.5" width="28" height="17" xlink:href="data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAHAAAABECAYAAABZC7HwAAAEjklEQVR4Xu1bachNQRj22VKWhBRJWVO2KJI1IVG28se+lZIQEilJWRLJDylJZPljz17WbCUiskSWssYPJVtCeR7uyTHNuPece+5t3rnv1NN3Z847873zPOedc2Y5VdU0iWagSrT36nw1FVD4TaACqoDCGRDuvkagCiicAeHuawSqgOIYqAOPmwJNgK/AU+CbuF7kHK6ECKyJvg4AxgITgPoWsSjibeABsB+4JUVQ3wXsCCIXG2RuR/58gQR3gt0eoEuB9pHZcvxYA3xPWK/s5r4LOAqMHDZYWYj8hgKYmgibXQXYuUxu4sIk4H4RbZS8aqgC9gRz1zJg7yXa6AB8zqCtkjQRooANwNQ9oIWFsY8o2w2cBd4BjXICjcbfXg6GV6J8WUnYz6DREAWcCl74nDTTcRRMBt5brtVA2Qxgi4NTRuHDDPjOvIkQBbwIlvoZTF1CfiDwMw+DfFPdZ7HZjLLZmbOfQYOhCdganDyx8NIOZY8L5Osg7MYYtteR53PVu+SjgLNiZHEa0cNg7RHyV2NlO/E7mlbwWXbIEn39EzA/ArZHLPa1UPYjQTtlMfVRwBPo+bAEvV8E2/U5ew5zm4y685HfmKA9RitvEjN5+RwMTUBOvpcYzI9E/mgCAZvB9rXFvjPK7iZopyymoQm4A6xNMZjjEHwjAZuDYHvGYs81VO/WTH0UsBuIapkjkGTOMcjkWyKXx6LEFZMXuQyHOSKeTiOTZCLOVR4Ou/F0B5muCW6Cspn6KGC888UspaUhsTcqXbFU3IqymWkaLHUdFfAvw4x6imdbweG88nKpxUjTvgr4h7U+wEnAttXEIZUL6F6mShewHlRZASxwqMPpBJ/JX7xUD05VsoB8vnLOaBsyqRcXu4cAfIHxNlWigNzk5bBIcVzpHC6MB956q1zOsUoSsDH6zJ12c1piasSVHa7ceLdsZruZKkVArsZwH9D2khLxwvklX1aiOaXvwffbv9AFrIs+rgO4QO5KPDIxD7CtvngvYsgCtgL7p4D2DhX4ksIDU4xMEcNlJQ2hDdFZnolxicdF79XAJ+9DLI+DIUYgz4EeA4Za+s4pwTjA65NmSW6qEAVcCgJWWUjYi7JpgLeT8iTCRbahCcjo46El822T87rhgHfbQWlEi9cJTcDB6By3j+KJx+a7Ax+KJcvH+hIF/N85zW0gebpBNDd4eW4myOS7gPwo5YIlovqi7I1RXh1527FBzgOLfe7xG4m1gHfTDd8FbAPSXMcBeeydwvCl5QDQHHhVwjDj1MS7Ydh3AflS8gxw7RhQr+hUmms3PStNVcCUTNqOCsabigQs9mukfO6pgPkYclznKDEXcJ3tjATkmRXXtw0p//U/1bj5m+RwVBb/M28bvg+h8Q5wbtcW4PH52gC/NHoO8Kta7z/EzKtESgNJAqbsYtjVVEDh+qqAKqBwBoS7rxGoAgpnQLj7GoEqoHAGhLuvEagCCmdAuPsagSqgcAaEu68RqAIKZ0C4+xqBKqBwBoS7rxGoAgpnQLj7GoEqoHAGhLuvEagCCmdAuPsagSqgcAaEu/8LchLARUNxUwUAAAAASUVORK5CYII="/></switch></g></g></g></g></g></g></svg> \ No newline at end of file diff --git a/files/en-us/web/api/keyboard/getlayoutmap/index.md b/files/en-us/web/api/keyboard/getlayoutmap/index.md index c2fcebe9bd370c1..8b278d62b2ed363 100644 --- a/files/en-us/web/api/keyboard/getlayoutmap/index.md +++ b/files/en-us/web/api/keyboard/getlayoutmap/index.md @@ -33,7 +33,7 @@ A {{jsxref('Promise')}} that resolves with an instance of ### Exceptions - `SecurityError` {{domxref("DOMException")}} - - : Thrown if the call is blocked by a [permission policy](/en-US/docs/Web/HTTP/Permissions_Policy). + - : Thrown if the call is blocked by a [permission policy](/en-US/docs/Web/HTTP/Guides/Permissions_Policy). ## Examples diff --git a/files/en-us/web/api/keyboard/index.md b/files/en-us/web/api/keyboard/index.md index faae3968c50d872..abbea224c2b28cf 100644 --- a/files/en-us/web/api/keyboard/index.md +++ b/files/en-us/web/api/keyboard/index.md @@ -11,7 +11,7 @@ browser-compat: api.Keyboard The **`Keyboard`** interface of the {{domxref("Keyboard API", "", "", "nocode")}} provides functions that retrieve keyboard layout maps and toggle capturing of key presses from the physical keyboard. -A list of valid code values is found in the [UI Events KeyboardEvent code Values](https://www.w3.org/TR/uievents-code/#key-alphanumeric-writing-system) spec. +A list of valid code values is found in the [UI Events KeyboardEvent code Values](https://w3c.github.io/uievents-code/) spec. {{InheritanceDiagram}} @@ -26,7 +26,7 @@ _Also inherits methods from its parent interface, {{DOMxRef("EventTarget")}}._ - {{domxref('Keyboard.getLayoutMap()')}} {{experimental_inline}} - : Returns a {{jsxref('Promise')}} that resolves with an instance of {{domxref('KeyboardLayoutMap')}} which is a map-like object with functions for retrieving the strings associated with specific physical keys. - {{domxref('Keyboard.lock()')}} {{experimental_inline}} - - : Returns a {{jsxref('Promise')}} that resolves after enabling the capture of keypresses for any or all of the keys on the physical keyboard. + - : Returns a {{jsxref('Promise')}} that resolves after enabling the capture of key presses for any or all of the keys on the physical keyboard. - {{domxref('Keyboard.unlock()')}} {{experimental_inline}} - : Unlocks all keys captured by the `lock()` method and returns synchronously. diff --git a/files/en-us/web/api/keyboard/lock/index.md b/files/en-us/web/api/keyboard/lock/index.md index 867c0315f2a342d..998525fd06f9ef7 100644 --- a/files/en-us/web/api/keyboard/lock/index.md +++ b/files/en-us/web/api/keyboard/lock/index.md @@ -12,7 +12,7 @@ browser-compat: api.Keyboard.lock The **`lock()`** method of the {{domxref("Keyboard")}} interface returns a {{jsxref('Promise')}} that resolves after enabling the -capture of keypresses for any or all of the keys on the physical keyboard. This method +capture of key presses for any or all of the keys on the physical keyboard. This method can only capture keys that are granted access by the underlying operating system. @@ -41,7 +41,7 @@ A {{jsxref('Promise')}} that resolves with {{jsxref('undefined')}} when the lock - `AbortError` {{domxref("DOMException")}} - : Thrown if a new call to `lock()` is made before the current one has finished. - `InvalidAccessError` {{domxref("DOMException")}} - - : Thrown if any key in `keyCodes` is not a valid [key code attribute value](https://www.w3.org/TR/uievents-code/#key-code-attribute-value). + - : Thrown if any key in `keyCodes` is not a valid [key code attribute value](https://w3c.github.io/uievents-code/#key-code-attribute-value). - `InvalidStateError` {{domxref("DOMException")}} - : Thrown if `lock()` is not called in an active top-level browsing context. @@ -53,7 +53,7 @@ A {{jsxref('Promise')}} that resolves with {{jsxref('undefined')}} when the lock ### Capturing all keys -The following example captures all keypresses. +The following example captures all key presses. ```js navigator.keyboard.lock(); diff --git a/files/en-us/web/api/keyboardevent/altkey/index.md b/files/en-us/web/api/keyboardevent/altkey/index.md index 1114ef9b25ef4a5..d6d2df891be5298 100644 --- a/files/en-us/web/api/keyboardevent/altkey/index.md +++ b/files/en-us/web/api/keyboardevent/altkey/index.md @@ -19,39 +19,27 @@ A boolean value. ## Examples ```html -<!doctype html> -<html lang="en-US"> - <head> - <meta charset="utf-8" /> - <meta name="viewport" content="width=device-width" /> - <title>altKey example</title> - - <script> - function showChar(e) { - alert( - "Key KeyDown: " + - String.fromCharCode(e.charCode) + - "\n" + - "charCode: " + - e.charCode + - "\n" + - "ALT key KeyDown: " + - e.altKey + - "\n", - ); - } - </script> - </head> - - <body onkeydown="showChar(event);"> - <p> - Press any character key, with or without holding down the ALT key.<br /> - You can also use the SHIFT key together with the ALT key. - </p> - </body> -</html> +<p> + Press any character key, with or without holding down the ALT key.<br /> + You can also use the SHIFT key together with the ALT key. +</p> +<pre id="output"></pre> ``` +```js +const output = document.getElementById("output"); + +function showChar(e) { + output.textContent = `Key KeyDown: "${e.key}" +ALT key KeyDown: ${e.altKey} +`; +} + +document.addEventListener("keydown", showChar); +``` + +{{EmbedLiveSample("examples", "", "400")}} + ## Specifications {{Specifications}} diff --git a/files/en-us/web/api/keyboardevent/code/index.md b/files/en-us/web/api/keyboardevent/code/index.md index 3994f2fa0d2be45..65a6bb5cbd5ba5f 100644 --- a/files/en-us/web/api/keyboardevent/code/index.md +++ b/files/en-us/web/api/keyboardevent/code/index.md @@ -153,7 +153,7 @@ function updatePosition(offset) { } ``` -The `refresh()` function handles applying the rotation and position by using an [SVG transform](/en-US/docs/Web/SVG/Attribute/transform). +The `refresh()` function handles applying the rotation and position by using an [SVG transform](/en-US/docs/Web/SVG/Reference/Attribute/transform). ```js function refresh() { diff --git a/files/en-us/web/api/keyboardevent/ctrlkey/index.md b/files/en-us/web/api/keyboardevent/ctrlkey/index.md index 95f07d437081af6..24979de3affb6dc 100644 --- a/files/en-us/web/api/keyboardevent/ctrlkey/index.md +++ b/files/en-us/web/api/keyboardevent/ctrlkey/index.md @@ -19,24 +19,27 @@ A boolean value. ## Examples ```html -<html lang="en"> - <head> - <title>ctrlKey example</title> - <script> - function showChar(e) { - alert(`Key Pressed: ${e.key}\nCTRL key pressed: ${e.ctrlKey}\n`); - } - </script> - </head> - <body onkeypress="showChar(event);"> - <p> - Press any character key, with or without holding down the CTRL key.<br /> - You can also use the SHIFT key together with the CTRL key. - </p> - </body> -</html> +<p> + Press any character key, with or without holding down the CTRL key.<br /> + You can also use the SHIFT key together with the CTRL key. +</p> +<pre id="output"></pre> ``` +```js +const output = document.getElementById("output"); + +function showChar(e) { + output.textContent = `Key KeyDown: "${e.key}" +CTRL key KeyDown: ${e.ctrlKey} +`; +} + +document.addEventListener("keydown", showChar); +``` + +{{EmbedLiveSample("examples", "", "400")}} + ## Specifications {{Specifications}} diff --git a/files/en-us/web/api/keyboardevent/index.md b/files/en-us/web/api/keyboardevent/index.md index ec718deabff21a8..6629af722140e50 100644 --- a/files/en-us/web/api/keyboardevent/index.md +++ b/files/en-us/web/api/keyboardevent/index.md @@ -161,8 +161,6 @@ _This interface also inherits methods of its parents, {{domxref("UIEvent")}} and ### Obsolete methods -- {{domxref("KeyboardEvent.initKeyEvent()")}} {{deprecated_inline}} - - : Initializes a `KeyboardEvent` object. This was implemented only by Firefox, and is no longer supported even there; instead, you should use the {{domxref("KeyboardEvent.KeyboardEvent", "KeyboardEvent()")}} constructor. - {{domxref("KeyboardEvent.initKeyboardEvent()")}} {{deprecated_inline}} - : Initializes a `KeyboardEvent` object. This is now deprecated. You should instead use the {{domxref("KeyboardEvent.KeyboardEvent", "KeyboardEvent()")}} constructor. @@ -212,7 +210,7 @@ This is what the DOM Level 3 specification says should happen. There are some ca #### Auto-repeat on some GTK environments such as Ubuntu 9.4 -In some GTK-based environments, auto-repeat dispatches a native key-up event automatically during auto-repeat, and there's no way for Gecko to know the difference between a repeated series of keypresses and an auto-repeat. On those platforms, then, an auto-repeat key will generate the following sequence of events: +In some GTK-based environments, auto-repeat dispatches a native key-up event automatically during auto-repeat, and there's no way for Gecko to know the difference between a repeated series of key presses and an auto-repeat. On those platforms, then, an auto-repeat key will generate the following sequence of events: 1. `keydown` 2. `keypress` @@ -268,7 +266,7 @@ document.addEventListener( {{Specifications}} -The `KeyboardEvent` interface specification went through numerous draft versions, first under DOM Events Level 2 where it was dropped as no consensus arose, then under DOM Events Level 3. This led to the implementation of non-standard initialization methods, the early DOM Events Level 2 version, {{domxref("KeyboardEvent.initKeyEvent()")}} by Gecko browsers and the early DOM Events Level 3 version, {{domxref("KeyboardEvent.initKeyboardEvent()")}} by others. Both have been superseded by the modern usage of a constructor: {{domxref("KeyboardEvent.KeyboardEvent", "KeyboardEvent()")}}. +The `KeyboardEvent` interface specification went through numerous draft versions, first under DOM Events Level 2 where it was dropped as no consensus arose, then under DOM Events Level 3. This led to the implementation of non-standard initialization methods, the early DOM Events Level 2 version, `KeyboardEvent.initKeyEvent()` by Gecko browsers and the early DOM Events Level 3 version, {{domxref("KeyboardEvent.initKeyboardEvent()")}} by others. Both have been superseded by the modern usage of a constructor: {{domxref("KeyboardEvent.KeyboardEvent", "KeyboardEvent()")}}. ## Browser compatibility diff --git a/files/en-us/web/api/keyboardevent/initkeyboardevent/index.md b/files/en-us/web/api/keyboardevent/initkeyboardevent/index.md index 7afd2083922a9aa..f51ba0e931819d7 100644 --- a/files/en-us/web/api/keyboardevent/initkeyboardevent/index.md +++ b/files/en-us/web/api/keyboardevent/initkeyboardevent/index.md @@ -56,7 +56,7 @@ None ({{jsxref("undefined")}}). {{Specifications}} -The `KeyboardEvent` interface specification went through numerous draft versions, first under DOM Events Level 2 where it was dropped as no consensus arose, then under DOM Events Level 3. This led to the implementation of non-standard initialization methods, the early DOM Events Level 2 version, {{domxref("KeyboardEvent.initKeyEvent()")}} by Gecko browsers and the early DOM Events Level 3 version, `KeyboardEvent.initKeyboardEvent()` by others. Both have been superseded by the modern usage of a constructor: {{domxref("KeyboardEvent.KeyboardEvent", "KeyboardEvent()")}}. +The `KeyboardEvent` interface specification went through numerous draft versions, first under DOM Events Level 2 where it was dropped as no consensus arose, then under DOM Events Level 3. This led to the implementation of non-standard initialization methods, the early DOM Events Level 2 version, `KeyboardEvent.initKeyEvent()` by Gecko browsers and the early DOM Events Level 3 version, `KeyboardEvent.initKeyboardEvent()` by others. Both have been superseded by the modern usage of a constructor: {{domxref("KeyboardEvent.KeyboardEvent", "KeyboardEvent()")}}. ## Browser compatibility diff --git a/files/en-us/web/api/keyboardevent/initkeyevent/index.md b/files/en-us/web/api/keyboardevent/initkeyevent/index.md deleted file mode 100644 index 20ccc9b19b1be2c..000000000000000 --- a/files/en-us/web/api/keyboardevent/initkeyevent/index.md +++ /dev/null @@ -1,94 +0,0 @@ ---- -title: "KeyboardEvent: initKeyEvent() method" -short-title: initKeyEvent() -slug: Web/API/KeyboardEvent/initKeyEvent -page-type: web-api-instance-method -status: - - deprecated - - non-standard ---- - -{{APIRef("UI Events")}} - -> [!WARNING] -> Do NOT use this method; Use the {{domxref("KeyboardEvent.KeyboardEvent", "KeyboardEvent()")}} constructor instead! -> -> The method has been removed from the DOM specification and is not supported by any current browser. -> Firefox hides this method behind the preference (`dom.keyboardevent.init_key_event.enabled`) from version 93 and plans to remove it shortly afterwards. - -{{deprecated_header}} - -The **`KeyboardEvent.initKeyEvent()`** method is used to -initialize the value of an event created using -{{domxref("document.createEvent")}} `("KeyboardEvent")`. Events initialized in -this way must have been created with the -{{domxref("document.createEvent")}} `("KeyboardEvent")` method. -`initKeyEvent()` must be called to set the event before it is [dispatched](/en-US/docs/Web/API/EventTarget/dispatchEvent). - -## Syntax - -```js-nolint -initKeyEvent(type, bubbles, cancelable, view, - ctrlKey, altKey, shiftKey, metaKey, - keyCode, charCode) -``` - -### Parameters - -- `type` - - : A string representing the type of event. -- `bubbles` - - : A boolean value indicating whether the event should bubble up through the - event chain or not (see [bubbles](/en-US/docs/Web/API/Event/bubbles)). -- `cancelable` - - : A boolean value indicating whether the event can be canceled (see [cancelable](/en-US/docs/Web/API/Event/cancelable)). -- `view` - - : Specifies the {{domxref("UIEvent.view")}}; this value may be `null`. -- `ctrlKey` - - : A boolean value that is `true` if the virtual key to be - generated is a combination of keys containing the <kbd>Ctrl</kbd> key. -- `altKey` - - : A boolean value that is `true` if the virtual key to be - generated is a combination of keys containing the <kbd>Alt</kbd> key. -- `shiftKey` - - : A boolean value that is `true` if the virtual key to be generated - is a combination of keys containing the <kbd>Shift</kbd>key. -- `metaKey` - - : A boolean value that is `true` if the virtual key to be - generated is a combination of keys containing the <kbd>Meta</kbd> key. -- `keyCode` - - : An `unsigned long` representing the virtual key code value of the key - which was pressed, otherwise `0`. See {{domxref("KeyboardEvent.keyCode")}} for the list of key codes. -- `charCode` - - : An `unsigned long` representing the Unicode character associated with - the pressed key otherwise `0`. - -### Return value - -None ({{jsxref("undefined")}}). - -## Examples - -```js -const event = document.createEvent("KeyboardEvent"); // create a key event -// define the event -event.initKeyEvent( - "keypress", // typeArg, - true, // canBubbleArg, - true, // cancelableArg, - null, // viewArg, Specifies UIEvent.view. This value may be null. - false, // ctrlKeyArg, - false, // altKeyArg, - false, // shiftKeyArg, - false, // metaKeyArg, - 9, // keyCodeArg, - 0, -); // charCodeArg); - -document.getElementById("blah").dispatchEvent(event); -``` - -## Specifications - -This implementation of keyboard events is based on the key events spec in the [early versions of DOM 2 Events](https://www.w3.org/TR/1999/WD-DOM-Level-2-19990923/events.html), later removed from that spec in favor of -{{domxref("KeyboardEvent.KeyboardEvent", "KeyboardEvent()")}} that should be used instead. diff --git a/files/en-us/web/api/keyboardevent/iscomposing/index.md b/files/en-us/web/api/keyboardevent/iscomposing/index.md index c4f51187937cd52..63de7ac383ac736 100644 --- a/files/en-us/web/api/keyboardevent/iscomposing/index.md +++ b/files/en-us/web/api/keyboardevent/iscomposing/index.md @@ -10,7 +10,7 @@ browser-compat: api.KeyboardEvent.isComposing The **`KeyboardEvent.isComposing`** read-only property returns a boolean value indicating if the event is fired within a composition -session, i.e. after {{domxref("Element/compositionstart_event", "compositionstart")}} +session, i.e., after {{domxref("Element/compositionstart_event", "compositionstart")}} and before {{domxref("Element/compositionend_event", "compositionend")}}. ## Value diff --git a/files/en-us/web/api/keyboardevent/keycode/index.md b/files/en-us/web/api/keyboardevent/keycode/index.md index 6ea24abede7ab5d..a9a52e17605866a 100644 --- a/files/en-us/web/api/keyboardevent/keycode/index.md +++ b/files/en-us/web/api/keyboardevent/keycode/index.md @@ -847,7 +847,7 @@ Gecko sets `keyCode` values of punctuation keys as far as possible (when points <td><code>0xBD (189)</code></td> <td colspan="3" rowspan="2"><code>0xAD (173)</code></td> <td rowspan="2"><code>0xAD (173)</code></td> - <td rowspan="2"><code>0xAD (173)</code>[1]</td> + <td rowspan="2"><code>0xAD (173)</code> [1]</td> <td rowspan="2"><code>0xAD (173)</code></td> <td colspan="3" rowspan="2"><code>0xAD (173)</code></td> </tr> @@ -874,7 +874,7 @@ Gecko sets `keyCode` values of punctuation keys as far as possible (when points <td><code>0x36 (54)</code>⚠️</td> <td rowspan="2"><code>0xBB (187)</code></td> <td><code>0xBB (187)</code></td> - <td><code>0xBB (187)</code>[1]</td> + <td><code>0xBB (187)</code> [1]</td> <td><code>0xBB (187)</code></td> <td rowspan="2"><code>0x3D (61)</code></td> <td rowspan="2"><code>0xA0 (160)</code>⚠️</td> @@ -2524,7 +2524,7 @@ Gecko defines a lot of `keyCode` values in `KeyboardEvent` for making the mappin <tr> <td><code>DOM_VK_AT</code></td> <td>0x40 (64)</td> - <td>Atmark ("@") key.</td> + <td>At sign ("@") key.</td> </tr> <tr> <td><code>DOM_VK_A</code></td> diff --git a/files/en-us/web/api/keyboardevent/shiftkey/index.md b/files/en-us/web/api/keyboardevent/shiftkey/index.md index 37491f1c7ae4deb..5be9d81ff108393 100644 --- a/files/en-us/web/api/keyboardevent/shiftkey/index.md +++ b/files/en-us/web/api/keyboardevent/shiftkey/index.md @@ -21,41 +21,27 @@ A boolean value. ## Examples ```html -<html lang="en-US"> - <head> - <meta charset="utf-8" /> - <meta name="viewport" content="width=device-width" /> - <title>shiftKey example</title> - - <script> - function showChar(e) { - alert( - "Key Pressed: " + - String.fromCharCode(e.charCode) + - "\n" + - "charCode: " + - e.charCode + - "\n" + - "SHIFT key pressed: " + - e.shiftKey + - "\n" + - "ALT key pressed: " + - e.altKey + - "\n", - ); - } - </script> - </head> - - <body onkeypress="showChar(event);"> - <p> - Press any character key, with or without holding down the SHIFT key.<br /> - You can also use the SHIFT key together with the ALT key. - </p> - </body> -</html> +<p> + Press any character key, with or without holding down the SHIFT key.<br /> + You can also use the SHIFT key together with the ALT key. +</p> +<pre id="output"></pre> ``` +```js +const output = document.getElementById("output"); + +function showChar(e) { + output.textContent = `Key KeyDown: "${e.key}" +SHIFT key KeyDown: ${e.shiftKey} +`; +} + +document.addEventListener("keydown", showChar); +``` + +{{EmbedLiveSample("examples", "", "400")}} + ## Specifications {{Specifications}} diff --git a/files/en-us/web/api/keyboardlayoutmap/get/index.md b/files/en-us/web/api/keyboardlayoutmap/get/index.md index e8483ec3434b1c1..50156f2df43f15d 100644 --- a/files/en-us/web/api/keyboardlayoutmap/get/index.md +++ b/files/en-us/web/api/keyboardlayoutmap/get/index.md @@ -15,7 +15,7 @@ The **`get()`** method of the {{domxref('KeyboardLayoutMap')}} interface returns the element with the given key. -A list of valid keys is found in the [UI Events KeyboardEvent code Values](https://www.w3.org/TR/uievents-code/#key-alphanumeric-writing-system) spec. +A list of valid keys is found in the [UI Events KeyboardEvent code Values](https://w3c.github.io/uievents-code/) specification. The method is otherwise the same as {{jsxref("Map.prototype.get()")}}. diff --git a/files/en-us/web/api/keyboardlayoutmap/has/index.md b/files/en-us/web/api/keyboardlayoutmap/has/index.md index 1602188e4c01516..8b5a6b8248744aa 100644 --- a/files/en-us/web/api/keyboardlayoutmap/has/index.md +++ b/files/en-us/web/api/keyboardlayoutmap/has/index.md @@ -16,7 +16,7 @@ The **`has()`** method of the object has an element with the specified key. A list of valid keys is found in -the [UI Events KeyboardEvent code Values](https://www.w3.org/TR/uievents-code/#key-alphanumeric-writing-system) spec. +the [UI Events KeyboardEvent code Values](https://w3c.github.io/uievents-code/) specification. The method is otherwise the same as {{jsxref("Map.prototype.has()")}}. diff --git a/files/en-us/web/api/keyboardlayoutmap/index.md b/files/en-us/web/api/keyboardlayoutmap/index.md index 38851c66f44fe26..4031191bf3f9230 100644 --- a/files/en-us/web/api/keyboardlayoutmap/index.md +++ b/files/en-us/web/api/keyboardlayoutmap/index.md @@ -13,7 +13,7 @@ The **`KeyboardLayoutMap`** interface of the {{domxref("Keyboard API", "", "", " A `KeyboardLayoutMap` instance is a read-only [`Map`-like object](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Map#map-like_browser_apis), in which each key is a string identifying the unique physical key on the keyboard (a "key code"), and the corresponding value is the associated key attribute value (which may be affected by the keyboard layout, and so on). -A list of valid keys is found in the [UI Events KeyboardEvent code Values](https://www.w3.org/TR/uievents-code/#key-alphanumeric-writing-system) specification. +A list of valid keys is found in the [UI Events KeyboardEvent code Values](https://w3c.github.io/uievents-code/) specification. ## Instance properties diff --git a/files/en-us/web/api/languagedetector/availability_static/index.md b/files/en-us/web/api/languagedetector/availability_static/index.md new file mode 100644 index 000000000000000..8b8917e726f31d1 --- /dev/null +++ b/files/en-us/web/api/languagedetector/availability_static/index.md @@ -0,0 +1,117 @@ +--- +title: "LanguageDetector: availability() static method" +short-title: availability() +slug: Web/API/LanguageDetector/availability_static +page-type: web-api-static-method +status: + - experimental +browser-compat: api.LanguageDetector.availability_static +--- + +{{APIRef("Translator and Language Detector APIs")}}{{securecontext_header}}{{SeeCompatTable}} + +The **`availability()`** static method of the {{domxref("LanguageDetector")}} interface returns an enumerated value that indicates whether the browser AI model supports a given `LanguageDetector` configuration. + +## Syntax + +```js-nolint +LanguageDetector.availability(options) +``` + +### Parameters + +- `options` + + - : An object specifying configuration options for the `LanguageDetector`. Possible values include: + + - `expectedInputLanguages` + - : An array of strings specifying the expected languages of the input text to have its language detected. These should be valid [BCP 47 language tags](https://en.wikipedia.org/wiki/IETF_language_tag#List_of_common_primary_language_subtags) (as specified in [RFC 5646](https://datatracker.ietf.org/doc/html/rfc5646)). Defaults to `["en"]` + +### Return value + +A {{jsxref("Promise")}} that fulfills with an enumerated value indicating whether support is available (or will be available) for a given `LanguageDetector` configuration, or `null` if support could not be determined. + +Possible values include: + +- `available` + - : The browser supports the given configuration and it can be used immediately. +- `downloadable` + - : The browser supports the given configuration, but it first needs to download an AI model, or some fine-tuning data for the model. +- `downloading` + - : The browser supports the given configuration, but it has to finish an ongoing download before it can proceed. +- `unavailable` + - : The browser does not support the given configuration. + +### Exceptions + +- `InvalidStateError` {{domxref("DOMException")}} + - : Thrown if the page's {{domxref("Document")}} is not yet active. +- `OperationError` {{domxref("DOMException")}} + - : Thrown if initialization of the AI model failed for any reason. +- `UnknownError` {{domxref("DOMException")}} + - : Thrown if the `availability()` call failed for any other reason, or a reason the user agent did not wish to disclose. + +If usage of the method is blocked by a {{httpheader('Permissions-Policy/language-detector','language-detector')}} {{httpheader("Permissions-Policy")}}, the promise rejects with a value of `unavailable`. + +## Examples + +### Basic `availability()` usage + +In the following snippet, we start by checking the availability of the model for detecting a couple of languages using the `availability()` method: + +- If it returns `unavailable`, we print an appropriate error message to the console. +- If it returns `available`, we create a language detector using the {{domxref("LanguageDetector.create_static", "create()")}} method, passing it the `expectedInputLanguages`. The required AI model is available, so we can use it immediately. +- If it returns a different value (that is, `downloadable` or `downloading`), we run the same `create()` method call, but this time we include a `monitor` that logs the percentage of the model downloaded each time the {{domxref("CreateMonitor/downloadprogress_event", "downloadprogress")}} event fires. + +```js +async function getDetector(languages) { + const availability = await LanguageDetector.availability({ + expectedInputLanguages: languages, + }); + if (availability === "unavailable") { + console.log(`Detection not supported; try a different set of languages.`); + return undefined; + } else if (availability === "available") { + return await LanguageDetector.create({ + expectedInputLanguages: languages, + }); + } + return await LanguageDetector.create({ + expectedInputLanguages: languages, + monitor(monitor) { + monitor.addEventListener("downloadprogress", (e) => { + console.log(`Downloaded ${Math.floor(e.loaded * 100)}%`); + }); + }, + }); +} + +const detector = await getDetector(["en-US", "zh"]); +``` + +### Detecting language support + +```js +async function langSupport(language) { + const availability = await LanguageDetector.availability({ + expectedInputLanguages: [language], + }); + return availability; +} + +await langSupport("en"); +await langSupport("pt"); +await langSupport("zh"); +``` + +## Specifications + +{{Specifications}} + +## Browser compatibility + +{{Compat}} + +## See also + +- [Using the Translator and Language Detector APIs](/en-US/docs/Web/API/Translator_and_Language_Detector_APIs/Using) diff --git a/files/en-us/web/api/languagedetector/create_static/index.md b/files/en-us/web/api/languagedetector/create_static/index.md new file mode 100644 index 000000000000000..bfd5085e5f3a6ea --- /dev/null +++ b/files/en-us/web/api/languagedetector/create_static/index.md @@ -0,0 +1,81 @@ +--- +title: "LanguageDetector: create() static method" +short-title: create() +slug: Web/API/LanguageDetector/create_static +page-type: web-api-static-method +status: + - experimental +browser-compat: api.LanguageDetector.create_static +--- + +{{APIRef("Translator and Language Detector APIs")}}{{securecontext_header}}{{SeeCompatTable}} + +The **`create()`** static method of the {{domxref("LanguageDetector")}} interface creates a new `LanguageDetector` instance to detect languages. + +> [!NOTE] +> The `create()` method requires [transient activation](/en-US/docs/Glossary/Transient_activation), that is, it must be invoked in response to a user action such as a mouse click or button press. + +## Syntax + +```js-nolint +LanguageDetector.create(options) +``` + +### Parameters + +- `options` + + - : An object specifying configuration options for the `LanguageDetector`. Possible values include: + + - `expectedInputLanguages` + - : An array of strings specifying the expected languages of the input text, which helps improve the accuracy of the language detection. These should be valid [BCP 47 language tags](https://en.wikipedia.org/wiki/IETF_language_tag#List_of_common_primary_language_subtags) (as specified in [RFC 5646](https://datatracker.ietf.org/doc/html/rfc5646)). Defaults to `["en"]`. + - `monitor` {{optional_inline}} + - : A callback function with a {{domxref("CreateMonitor")}} argument that enables monitoring download progress of the AI model. + - `signal` {{optional_inline}} + - : An {{domxref("AbortSignal")}} object instance, which allows the `create()` operation to be aborted via the associated {{domxref("AbortController")}}. + +### Return value + +A {{jsxref("Promise")}} that fulfills with a `LanguageDetector` object instance. + +### Exceptions + +- `InvalidStateError` {{domxref("DOMException")}} + - : Thrown if the page's {{domxref("Document")}} is not yet active. +- `NetworkError` {{domxref("DOMException")}} + - : Thrown if: + - The network was not available to download the AI model. + - The user has cancelled the AI model download. +- `NotAllowedError` {{domxref("DOMException")}} + - : Thrown if: + - Usage of the method is blocked by a {{httpheader('Permissions-Policy/language-detector','language-detector')}} {{httpheader("Permissions-Policy")}}. + - The user has blocked the AI model download in some way. + - The `create()` method wasn't called via {{glossary("transient activation")}}. +- `NotSupportedError` {{domxref("DOMException")}} + - : Thrown if: + - The language tags specified in `expectedInputLanguages` are invalid, or not supported. + - An AI model to support the specified `expectedInputLanguages` is not available. +- `OperationError` {{domxref("DOMException")}} + - : General-purpose exception thrown if `LanguageDetector` creation failed for any other reason. + +## Examples + +### Basic `LanguageDetector` creation + +```js +const detector = await LanguageDetector.create({ + expectedInputLanguages: ["en-US", "zh"], +}); +``` + +## Specifications + +{{Specifications}} + +## Browser compatibility + +{{Compat}} + +## See also + +- [Using the Translator and Language Detector APIs](/en-US/docs/Web/API/Translator_and_Language_Detector_APIs/Using) diff --git a/files/en-us/web/api/languagedetector/destroy/index.md b/files/en-us/web/api/languagedetector/destroy/index.md new file mode 100644 index 000000000000000..37750a01e0584b7 --- /dev/null +++ b/files/en-us/web/api/languagedetector/destroy/index.md @@ -0,0 +1,53 @@ +--- +title: "LanguageDetector: destroy() method" +short-title: destroy() +slug: Web/API/LanguageDetector/destroy +page-type: web-api-instance-method +status: + - experimental +browser-compat: api.LanguageDetector.destroy +--- + +{{APIRef("Translator and Language Detector APIs")}}{{SeeCompatTable}} + +The **`destroy()`** method of the {{domxref("LanguageDetector")}} interface destroys the `LanguageDetector` instance it is called on. It makes sense to destroy these objects if they are no longer going to be used, as they tie up significant resources in their handling. + +## Syntax + +```js-nolint +destroy() +``` + +### Parameters + +None. + +### Return value + +None ({{jsxref("undefined")}}). + +## Examples + +### Basic `destroy()` usage + +```js +const detector = await LanguageDetector.create({ + expectedInputLanguages: ["en-US", "zh"], +}); + +// ... + +detector.destroy(); +``` + +## Specifications + +{{Specifications}} + +## Browser compatibility + +{{Compat}} + +## See also + +- [Using the Translator and Language Detector APIs](/en-US/docs/Web/API/Translator_and_Language_Detector_APIs/Using) diff --git a/files/en-us/web/api/languagedetector/detect/index.md b/files/en-us/web/api/languagedetector/detect/index.md new file mode 100644 index 000000000000000..774eb0ee3226fa8 --- /dev/null +++ b/files/en-us/web/api/languagedetector/detect/index.md @@ -0,0 +1,84 @@ +--- +title: "LanguageDetector: detect() method" +short-title: detect() +slug: Web/API/LanguageDetector/detect +page-type: web-api-instance-method +status: + - experimental +browser-compat: api.LanguageDetector.detect +--- + +{{APIRef("Translator and Language Detector APIs")}}{{SeeCompatTable}} + +The **`detect()`** method of the {{domxref("LanguageDetector")}} interface detects the closest matching language or languages that a given text string is most likely to be written in. + +## Syntax + +```js-nolint +detect(input) +detect(input, options) +``` + +### Parameters + +- `input` + - : A string representing the text to have its language detected. +- `options` {{optional_inline}} + - : An object specifying configuration options for the `detect()` operation. Possible values include: + - `signal` + - : An {{domxref("AbortSignal")}} object instance, which allows the `detect()` operation to be aborted via the associated {{domxref("AbortController")}}. + +### Return value + +A {{jsxref("Promise")}} that fulfills with an array of objects representing the detected languages. Each object contains the following properties: + +- `detectedLanguage` + - : A [BCP 47 language tag](https://en.wikipedia.org/wiki/IETF_language_tag#List_of_common_primary_language_subtags) representing the detected language. +- `confidence` + - : A number between `0` and `1` representing the AI model's confidence that the detected language is correct. + +The sum of all the returned `confidence` values should theoretically be 1, however, it may be lower because very low confidence values are excluded from the results. + +The last array element returned will always have a `detectedLanguage` value of `und` — this is an abbreviation of "undetermined", and represents the probability that the text is not written in a language the model knows. + +### Exceptions + +- `InvalidStateError` {{domxref("DOMException")}} + - : Thrown if the current {{domxref("Document")}} is not active. +- `QuotaExceededError` {{domxref("DOMException")}} + - : Thrown if the language detection operation exceeds the available {{domxref("LanguageDetector.inputQuota", "inputQuota")}}. + +## Examples + +### Basic `detect()` usage + +```js +const detector = await LanguageDetector.create({ + expectedInputLanguages: ["en-US", "zh"], +}); + +const results = await detector.detect(myTextString); + +results.forEach((result) => { + console.log(`${result.detectedLanguage}: ${result.confidence}`); +}); + +// Results in logs like this: +// la: 0.8359838724136353 +// es: 0.017705978825688362 +// sv: 0.012977192178368568 +// en: 0.011148443445563316 +// und: 0.0003214875760022551 +``` + +## Specifications + +{{Specifications}} + +## Browser compatibility + +{{Compat}} + +## See also + +- [Using the Translator and Language Detector APIs](/en-US/docs/Web/API/Translator_and_Language_Detector_APIs/Using) diff --git a/files/en-us/web/api/languagedetector/expectedinputlanguages/index.md b/files/en-us/web/api/languagedetector/expectedinputlanguages/index.md new file mode 100644 index 000000000000000..b7830d6be78037f --- /dev/null +++ b/files/en-us/web/api/languagedetector/expectedinputlanguages/index.md @@ -0,0 +1,42 @@ +--- +title: "LanguageDetector: expectedInputLanguages property" +short-title: expectedInputLanguages +slug: Web/API/LanguageDetector/expectedInputLanguages +page-type: web-api-instance-property +status: + - experimental +browser-compat: api.LanguageDetector.expectedInputLanguages +--- + +{{APIRef("Translator and Language Detector APIs")}}{{SeeCompatTable}} + +The **`expectedInputLanguages`** read-only property of the {{domxref("LanguageDetector")}} interface returns the expected languages to be detected in the input text. Specifying expected input languages helps improve the accuracy of the language detection. + +A `LanguageDetector` instance's `expectedInputLanguages` are set when creating it via a {{domxref("LanguageDetector.create_static", "create()")}} call. + +## Value + +An array of strings specifying the expected input languages. These will be valid [BCP 47 language tags](https://en.wikipedia.org/wiki/IETF_language_tag#List_of_common_primary_language_subtags) (as specified in [RFC 5646](https://datatracker.ietf.org/doc/html/rfc5646)). + +## Examples + +```js +const detector = await LanguageDetector.create({ + expectedInputLanguages: ["en-US", "zh"], +}); + +// Logs ["en-US", "zh"] +console.log(detector.expectedInputLanguages); +``` + +## Specifications + +{{Specifications}} + +## Browser compatibility + +{{Compat}} + +## See also + +- [Using the Translator and Language Detector APIs](/en-US/docs/Web/API/Translator_and_Language_Detector_APIs/Using) diff --git a/files/en-us/web/api/languagedetector/index.md b/files/en-us/web/api/languagedetector/index.md new file mode 100644 index 000000000000000..1612b35f24b957f --- /dev/null +++ b/files/en-us/web/api/languagedetector/index.md @@ -0,0 +1,80 @@ +--- +title: LanguageDetector +slug: Web/API/LanguageDetector +page-type: web-api-interface +status: + - experimental +browser-compat: api.LanguageDetector +--- + +{{APIRef("Translator and Language Detector APIs")}}{{SeeCompatTable}} + +The **`LanguageDetector`** interface of the {{domxref("Translator and Language Detector APIs", "Translator and Language Detector APIs", "", "nocode")}} contains all the language detection functionality, including checking AI model availability, creating a new `LanguageDetector` instance, using it to detect a language, and more. + +{{InheritanceDiagram}} + +## Instance properties + +- {{domxref("LanguageDetector.inputQuota", "inputQuota")}} {{ReadOnlyInline}} {{Experimental_Inline}} + - : The input quota available to the browser for detecting languages. +- {{domxref("LanguageDetector.expectedInputLanguages", "expectedInputLanguages")}} {{ReadOnlyInline}} {{Experimental_Inline}} + - : The expected languages to be detected in the input text. + +## Static methods + +- {{domxref("LanguageDetector.availability_static", "availability()")}} {{Experimental_Inline}} + - : Returns an enumerated value that indicates whether the browser AI model supports a given `LanguageDetector` configuration. +- {{domxref("LanguageDetector.create_static", "create()")}} {{Experimental_Inline}} + - : Creates a new `LanguageDetector` instance to detect languages. + +## Instance methods + +- {{domxref("LanguageDetector.destroy", "destroy()")}} {{Experimental_Inline}} + - : Destroys the `LanguageDetector` instance it is called on. +- {{domxref("LanguageDetector.detect", "detect()")}} {{Experimental_Inline}} + - : Detects the closest matching language or languages that a given text string is most likely to be written in. +- {{domxref("LanguageDetector.measureInputUsage", "measureInputUsage()")}} {{Experimental_Inline}} + - : Reports how much input quota would be used by a language detection operation for a given text input. + +## Examples + +See [Using the Translator and Language Detector APIs](/en-US/docs/Web/API/Translator_and_Language_Detector_APIs/Using) for a complete example. + +### Creating a `LanguageDetector` instance + +```js +const detector = await LanguageDetector.create({ + expectedInputLanguages: ["en-US", "zh"], +}); +``` + +> [!NOTE] +> Different implementations will likely support different languages. + +### Detecting languages + +```js +const results = await detector.detect(myTextString); + +results.forEach((result) => { + console.log(`${result.detectedLanguage}: ${result.confidence}`); +}); + +// Results in logs like this: +// la: 0.8359838724136353 +// es: 0.017705978825688362 +// sv: 0.012977192178368568 +// en: 0.011148443445563316 +``` + +## Specifications + +{{Specifications}} + +## Browser compatibility + +{{Compat}} + +## See also + +- [Using the Translator and Language Detector APIs](/en-US/docs/Web/API/Translator_and_Language_Detector_APIs/Using) diff --git a/files/en-us/web/api/languagedetector/inputquota/index.md b/files/en-us/web/api/languagedetector/inputquota/index.md new file mode 100644 index 000000000000000..fc30972a893e215 --- /dev/null +++ b/files/en-us/web/api/languagedetector/inputquota/index.md @@ -0,0 +1,58 @@ +--- +title: "LanguageDetector: inputQuota property" +short-title: inputQuota +slug: Web/API/LanguageDetector/inputQuota +page-type: web-api-instance-property +status: + - experimental +browser-compat: api.LanguageDetector.inputQuota +--- + +{{APIRef("Translator and Language Detector APIs")}}{{SeeCompatTable}} + +The **`inputQuota`** read-only property of the {{domxref("LanguageDetector")}} interface returns the input quota available to the browser for detecting languages. + +## Value + +A number specifying the available input quota. + +This number is implementation-dependant. For example, it might be {{jsxref("Infinity")}} if there are no limits beyond the user's memory and the maximum length of JavaScript strings, or it might be a number of tokens in the case of AI models that use a token/credits scheme. + +The only guarantee is that `inputQuota` - {{domxref("LanguageDetector.measureInputUsage", "measureInputUsage()")}} will be non-negative if there is sufficient quota to detect the text's language. + +## Examples + +### Checking if you have enough quota + +In the below snippet, we create a new `LanguageDetector` instance using {{domxref("LanguageDetector.create_static", "create()")}}, then return the total input quota via `inputQuota` and the input quota usage for detecting a particular text string's language via {{domxref("LanguageDetector.measureInputUsage", "measureInputUsage()")}}. + +We then test to see if the individual input usage for that string is greater than the total available quota. If so, we throw an appropriate error; it not, we commence detecting the string's language using {{domxref("LanguageDetector.detect", "detect()")}}. + +```js +const detector = await LanguageDetector.create({ + expectedInputLanguages: ["en-US", "zh"], +}); + +const totalInputQuota = detector.inputQuota; +const inputUsage = await detector.measureInputUsage(myTextString); + +if (inputUsage > totalInputQuota) { + throw new Error("Insufficient quota to detect languages."); +} else { + console.log("Quota available to detect languages."); + const results = await detector.detect(myTextString); + // ... +} +``` + +## Specifications + +{{Specifications}} + +## Browser compatibility + +{{Compat}} + +## See also + +- [Using the Translator and Language Detector APIs](/en-US/docs/Web/API/Translator_and_Language_Detector_APIs/Using) diff --git a/files/en-us/web/api/languagedetector/measureinputusage/index.md b/files/en-us/web/api/languagedetector/measureinputusage/index.md new file mode 100644 index 000000000000000..289cf4de1e109b1 --- /dev/null +++ b/files/en-us/web/api/languagedetector/measureinputusage/index.md @@ -0,0 +1,79 @@ +--- +title: "LanguageDetector: measureInputUsage() method" +short-title: measureInputUsage() +slug: Web/API/LanguageDetector/measureInputUsage +page-type: web-api-instance-method +status: + - experimental +browser-compat: api.LanguageDetector.measureInputUsage +--- + +{{APIRef("Translator and Language Detector APIs")}}{{SeeCompatTable}} + +The **`measureInputUsage()`** method of the {{domxref("LanguageDetector")}} interface reports how much input quota would be used by a language detection operation for a given text input. + +## Syntax + +```js-nolint +measureInputUsage(input) +measureInputUsage(input, options) +``` + +### Parameters + +- `input` + - : A string representing the input text you want an input usage measurement for. +- `options` {{optional_inline}} + - : An object specifying configuration options for the `measureInputUsage()` operation. Possible values include: + - `signal` + - : An {{domxref("AbortSignal")}} object instance, which allows the `measureInputUsage()` operation to be aborted via the associated {{domxref("AbortController")}}. + +### Return value + +A {{jsxref("Promise")}} that fulfills with a number specifying the {{domxref("LanguageDetector.inputQuota", "inputQuota")}} usage of the given input text. + +This number is implementation-dependant; if it is less than the {{domxref("LanguageDetector.inputQuota", "inputQuota")}}, the string's language can be detected. + +### Exceptions + +- `NotAllowedError` {{domxref("DOMException")}} + - : Thrown if usage of the `LanguageDetector` API is blocked by a {{httpheader('Permissions-Policy/language-detector','language-detector')}} {{httpheader("Permissions-Policy")}}. +- `UnknownError` {{domxref("DOMException")}} + - : Thrown if the `measureInputUsage()` call failed for any other reason, or a reason the user agent did not wish to disclose. + +## Examples + +### Checking if you have enough quota + +In the below snippet, we create a new `LanguageDetector` instance using {{domxref("LanguageDetector.create_static", "create()")}}, then return the total input quota via {{domxref("LanguageDetector.inputQuota", "inputQuota")}} and the input quota usage for a detecting a particular text string's language via `measureInputUsage()`. + +We then test to see if the individual input usage for that string is greater than the total available quota. If so, we throw an appropriate error; it not, we commence detecting the string's language using {{domxref("LanguageDetector.detect", "detect()")}}. + +```js +const detector = await LanguageDetector.create({ + expectedInputLanguages: ["en-US", "zh"], +}); + +const totalInputQuota = detector.inputQuota; +const inputUsage = await detector.measureInputUsage(myTextString); + +if (inputUsage > totalInputQuota) { + throw new Error("Insufficient quota to detect languages."); +} else { + console.log("Quota available to detect languages."); + const results = await detector.detect(myTextString); + // ... +} +``` + +## Specifications + +{{Specifications}} + +## Browser compatibility + +{{Compat}} + +## See also + +- [Using the Translator and Language Detector APIs](/en-US/docs/Web/API/Translator_and_Language_Detector_APIs/Using) diff --git a/files/en-us/web/api/largestcontentfulpaint/index.md b/files/en-us/web/api/largestcontentfulpaint/index.md index e5a7bdf12eff72b..1ec995790f0565d 100644 --- a/files/en-us/web/api/largestcontentfulpaint/index.md +++ b/files/en-us/web/api/largestcontentfulpaint/index.md @@ -14,7 +14,7 @@ The `LargestContentfulPaint` interface provides timing information about the lar The key moment this API provides is the {{Glossary("Largest Contentful Paint")}} (LCP) metric. It provides the render time of the largest image or text block visible within the viewport, recorded from when the page first begins to load. The following elements are considered when determining the LCP: - {{HTMLElement("img")}} elements. -- [`<image>`](/en-US/docs/Web/SVG/Element/image) elements inside an SVG. +- [`<image>`](/en-US/docs/Web/SVG/Reference/Element/image) elements inside an SVG. - The poster images of {{HTMLElement("video")}} elements. - Elements with a {{cssxref("background-image")}}. - Groups of text nodes, such as {{HTMLElement("p")}}. @@ -102,7 +102,7 @@ Like in the code example, you can use {{domxref("PerformanceEntry.startTime", "s If you use `startTime`, you can flag any inaccuracies by checking if `renderTime` was used: ```js -const isAccurateLCP = entry.renderTime ? true : false; +const isAccurateLCP = Boolean(entry.renderTime); ``` ## Specifications diff --git a/files/en-us/web/api/largestcontentfulpaint/rendertime/index.md b/files/en-us/web/api/largestcontentfulpaint/rendertime/index.md index fc08d94fa3c0efe..e51dd077413bec7 100644 --- a/files/en-us/web/api/largestcontentfulpaint/rendertime/index.md +++ b/files/en-us/web/api/largestcontentfulpaint/rendertime/index.md @@ -34,7 +34,7 @@ observer.observe({ type: "largest-contentful-paint", buffered: true }); ### Cross-origin image render time -For security reasons, the value of the {{domxref("LargestContentfulPaint.renderTime", "renderTime")}} property was originally `0` if the resource is a cross-origin request. Instead the {{domxref("LargestContentfulPaint.loadTime", "loadTime")}} property should be used as a fallback. +For security reasons, the value of the `renderTime` property was originally `0` if the resource is a cross-origin request. Instead the {{domxref("LargestContentfulPaint.loadTime", "loadTime")}} property should be used as a fallback. Browsers [may now expose a slightly coarsened render time](https://github.com/w3c/paint-timing/issues/104) in these situations. Check for [browser support](#browser_compatibility). @@ -51,7 +51,7 @@ Alternatively, you can use {{domxref("PerformanceEntry.startTime", "startTime")} If you use `startTime`, you can flag any inaccuracies by checking if `renderTime` was used: ```js -const isAccurateLCP = entry.renderTime ? true : false; +const isAccurateLCP = Boolean(entry.renderTime); ``` ## Specifications diff --git a/files/en-us/web/api/launch_handler_api/index.md b/files/en-us/web/api/launch_handler_api/index.md index 7b63df81e09a442..6e490472d68c8be 100644 --- a/files/en-us/web/api/launch_handler_api/index.md +++ b/files/en-us/web/api/launch_handler_api/index.md @@ -40,7 +40,7 @@ window.launchQueue.setConsumer((launchParams) => { }); ``` -> **Note:** {{domxref("LaunchParams")}} also has a {{domxref("LaunchParams.files")}} property, which returns a read-only array of {{domxref("FileSystemHandle")}} objects representing any files passed along with the launch navigation via the [`POST`](/en-US/docs/Web/HTTP/Methods/POST) method. This allows custom file handling to be implemented. +> **Note:** {{domxref("LaunchParams")}} also has a {{domxref("LaunchParams.files")}} property, which returns a read-only array of {{domxref("FileSystemHandle")}} objects representing any files passed along with the launch navigation via the [`POST`](/en-US/docs/Web/HTTP/Reference/Methods/POST) method. This allows custom file handling to be implemented. ## Interfaces diff --git a/files/en-us/web/api/launchparams/files/index.md b/files/en-us/web/api/launchparams/files/index.md index 77dd7334cd7064e..feac4f76ddfa116 100644 --- a/files/en-us/web/api/launchparams/files/index.md +++ b/files/en-us/web/api/launchparams/files/index.md @@ -10,7 +10,7 @@ browser-compat: api.LaunchParams.files {{APIRef("Launch Handler API")}}{{SeeCompatTable}} -The **`files`** read-only property of the {{domxref("LaunchParams")}} interface returns an array of {{domxref("FileSystemHandle")}} objects representing any files passed along with the launch navigation via the [`POST`](/en-US/docs/Web/HTTP/Methods/POST) method. +The **`files`** read-only property of the {{domxref("LaunchParams")}} interface returns an array of {{domxref("FileSystemHandle")}} objects representing any files passed along with the launch navigation via the [`POST`](/en-US/docs/Web/HTTP/Reference/Methods/POST) method. ## Value diff --git a/files/en-us/web/api/launchparams/index.md b/files/en-us/web/api/launchparams/index.md index c0b9dccaeb425b1..152317e97721dfb 100644 --- a/files/en-us/web/api/launchparams/index.md +++ b/files/en-us/web/api/launchparams/index.md @@ -18,7 +18,7 @@ Such custom navigation handling is initiated via {{domxref("Window.launchQueue") ## Instance properties - {{domxref("LaunchParams.files")}} {{ReadOnlyInline}}{{Experimental_Inline}} - - : Returns a read-only array of {{domxref("FileSystemHandle")}} objects representing any files passed along with the launch navigation via the [`POST`](/en-US/docs/Web/HTTP/Methods/POST) method. + - : Returns a read-only array of {{domxref("FileSystemHandle")}} objects representing any files passed along with the launch navigation via the [`POST`](/en-US/docs/Web/HTTP/Reference/Methods/POST) method. - {{domxref("LaunchParams.targetURL")}} {{ReadOnlyInline}}{{Experimental_Inline}} - : Returns the target URL of the launch. diff --git a/files/en-us/web/api/linearaccelerationsensor/index.md b/files/en-us/web/api/linearaccelerationsensor/index.md index 87caa22802b78e5..55f2c77b241308b 100644 --- a/files/en-us/web/api/linearaccelerationsensor/index.md +++ b/files/en-us/web/api/linearaccelerationsensor/index.md @@ -9,7 +9,7 @@ browser-compat: api.LinearAccelerationSensor The **`LinearAccelerationSensor`** interface of the [Sensor APIs](/en-US/docs/Web/API/Sensor_APIs) provides on each reading the acceleration applied to the device along all three axes, but without the contribution of gravity. -To use this sensor, the user must grant permission to the `'accelerometer'` device sensor through the [Permissions API](/en-US/docs/Web/API/Permissions_API). In addition, this feature may be blocked by a [Permissions Policy](/en-US/docs/Web/HTTP/Permissions_Policy) set on your server. +To use this sensor, the user must grant permission to the `'accelerometer'` device sensor through the [Permissions API](/en-US/docs/Web/API/Permissions_API). In addition, this feature may be blocked by a [Permissions Policy](/en-US/docs/Web/HTTP/Guides/Permissions_Policy) set on your server. {{InheritanceDiagram}} diff --git a/files/en-us/web/api/linearaccelerationsensor/linearaccelerationsensor/index.md b/files/en-us/web/api/linearaccelerationsensor/linearaccelerationsensor/index.md index c7ae8cf61ac7e6b..6870778b207833a 100644 --- a/files/en-us/web/api/linearaccelerationsensor/linearaccelerationsensor/index.md +++ b/files/en-us/web/api/linearaccelerationsensor/linearaccelerationsensor/index.md @@ -39,7 +39,7 @@ new LinearAccelerationSensor(options) ### Exceptions - `SecurityError` {{domxref("DOMException")}} - - : Use of this feature was blocked by a [Permissions Policy](/en-US/docs/Web/HTTP/Permissions_Policy). + - : Use of this feature was blocked by a [Permissions Policy](/en-US/docs/Web/HTTP/Guides/Permissions_Policy). ## Specifications diff --git a/files/en-us/web/api/local_font_access_api/index.md b/files/en-us/web/api/local_font_access_api/index.md index c3e88b3a09b2822..409de9178367427 100644 --- a/files/en-us/web/api/local_font_access_api/index.md +++ b/files/en-us/web/api/local_font_access_api/index.md @@ -28,7 +28,7 @@ In terms of privacy and security: - The Local Font Access API is designed to only provide access to the data required to solve the above problems. There is also no requirement for browsers to provide the full list of available local fonts, nor to provide the data in the same order as it appears on disk. - When {{domxref("Window.queryLocalFonts()")}} is invoked, the user is asked for permission to access their local fonts. The status of this permission can be queried via the [Permissions API](/en-US/docs/Web/API/Permissions_API) (the `local-fonts` permission). -- You can control access to this feature using a {{httpheader("Permissions-Policy/local-fonts", "local-fonts")}} [Permissions Policy](/en-US/docs/Web/HTTP/Permissions_Policy). +- You can control access to this feature using a {{httpheader("Permissions-Policy/local-fonts", "local-fonts")}} [Permissions Policy](/en-US/docs/Web/HTTP/Guides/Permissions_Policy). ## Interfaces @@ -122,4 +122,4 @@ async function computeOutlineFormat() { - [Use advanced typography with local fonts](https://developer.chrome.com/docs/capabilities/web-apis/local-fonts) - {{cssxref("@font-face")}} -- The {{httpheader("Permissions-Policy/local-fonts", "local-fonts")}} [Permissions Policy](/en-US/docs/Web/HTTP/Permissions_Policy) directive +- The {{httpheader("Permissions-Policy/local-fonts", "local-fonts")}} [Permissions Policy](/en-US/docs/Web/HTTP/Guides/Permissions_Policy) directive diff --git a/files/en-us/web/api/location/protocol/index.md b/files/en-us/web/api/location/protocol/index.md index dc8c198aaac87f0..0e4976955eee394 100644 --- a/files/en-us/web/api/location/protocol/index.md +++ b/files/en-us/web/api/location/protocol/index.md @@ -8,7 +8,7 @@ browser-compat: api.Location.protocol {{ApiRef("Location")}} -The **`protocol`** property of the {{domxref("Location")}} interface is a string containing the protocol or scheme of the location's URL, including the final `":"`. If the port is the default for the protocol (`80` for `ws:` and `http:`, `443` for `wss:` and `https:`, and `21` for `ftp:`), this property contains an empty string, `""`. +The **`protocol`** property of the {{domxref("Location")}} interface is a string containing the protocol or scheme of the location's URL, including the final `":"`. This property can be set to change the protocol of the URL. A `":"` is appended to the provided string if not provided. The provided scheme has to be compatible with the rest of the URL to be considered valid. diff --git a/files/en-us/web/api/location/search/index.md b/files/en-us/web/api/location/search/index.md index b881d5994991567..1433e3cfc1ad3f6 100644 --- a/files/en-us/web/api/location/search/index.md +++ b/files/en-us/web/api/location/search/index.md @@ -35,7 +35,7 @@ const queryString = anchor.search; // Returns:'?q=123' // Further parsing: const params = new URLSearchParams(queryString); -const q = parseInt(params.get("q")); // is the number 123 +const q = parseInt(params.get("q"), 10); // is the number 123 ``` ## Specifications diff --git a/files/en-us/web/api/magnetometer/index.md b/files/en-us/web/api/magnetometer/index.md index 7b6313d30b27615..e3e62ae5f6d747a 100644 --- a/files/en-us/web/api/magnetometer/index.md +++ b/files/en-us/web/api/magnetometer/index.md @@ -11,7 +11,7 @@ browser-compat: api.Magnetometer The **`Magnetometer`** interface of the [Sensor APIs](/en-US/docs/Web/API/Sensor_APIs) provides information about the magnetic field as detected by the device's primary magnetometer sensor. -To use this sensor, the user must grant permission to the `'magnetometer'` device sensor through the [Permissions API](/en-US/docs/Web/API/Permissions_API). In addition, this feature may be blocked by a [Permissions Policy](/en-US/docs/Web/HTTP/Permissions_Policy) set on your server. +To use this sensor, the user must grant permission to the `'magnetometer'` device sensor through the [Permissions API](/en-US/docs/Web/API/Permissions_API). In addition, this feature may be blocked by a [Permissions Policy](/en-US/docs/Web/HTTP/Guides/Permissions_Policy) set on your server. {{InheritanceDiagram}} diff --git a/files/en-us/web/api/magnetometer/magnetometer/index.md b/files/en-us/web/api/magnetometer/magnetometer/index.md index 0648113b1e8354b..82248bace8cb5b2 100644 --- a/files/en-us/web/api/magnetometer/magnetometer/index.md +++ b/files/en-us/web/api/magnetometer/magnetometer/index.md @@ -40,7 +40,7 @@ new Magnetometer(options) ### Exceptions - `SecurityError` {{domxref("DOMException")}} - - : Use of this feature was blocked by a [Permissions Policy](/en-US/docs/Web/HTTP/Permissions_Policy). + - : Use of this feature was blocked by a [Permissions Policy](/en-US/docs/Web/HTTP/Guides/Permissions_Policy). ## Specifications diff --git a/files/en-us/web/api/mathmlelement/autofocus/index.md b/files/en-us/web/api/mathmlelement/autofocus/index.md new file mode 100644 index 000000000000000..7eb2258a2a04b44 --- /dev/null +++ b/files/en-us/web/api/mathmlelement/autofocus/index.md @@ -0,0 +1,29 @@ +--- +title: "MathMLElement: autofocus property" +short-title: autofocus +slug: Web/API/MathMLElement/autofocus +page-type: web-api-instance-property +browser-compat: api.MathMLElement.autofocus +--- + +{{APIRef("MathML")}} + +The **`autofocus`** property of the {{domxref("MathMLElement")}} interface contains a boolean value reflecting the [`autofocus`](/en-US/docs/Web/HTML/Reference/Global_attributes/autofocus) HTML global attribute. It indicates whether the MathML element should be focused when the page loads or when the element becomes shown if the MathML element is inside a {{htmlelement("dialog")}} or a [popover](/en-US/docs/Web/HTML/Reference/Global_attributes/popover). + +## Value + +A boolean value. + +## Specifications + +{{Specifications}} + +## Browser compatibility + +{{Compat}} + +## See also + +- {{domxref("MathMLElement.focus()")}} +- {{domxref("HTMLElement.autofocus")}} +- [Popover API](/en-US/docs/Web/API/Popover_API) diff --git a/files/en-us/web/api/mathmlelement/blur/index.md b/files/en-us/web/api/mathmlelement/blur/index.md new file mode 100644 index 000000000000000..0d0721deb66e898 --- /dev/null +++ b/files/en-us/web/api/mathmlelement/blur/index.md @@ -0,0 +1,79 @@ +--- +title: "MathMLElement: blur() method" +short-title: blur() +slug: Web/API/MathMLElement/blur +page-type: web-api-instance-method +browser-compat: api.MathMLElement.blur +--- + +{{APIRef("MathML")}} + +The **`blur()`** method of the {{domxref("MathMLElement")}} interface removes keyboard focus from the current MathML element. + +## Syntax + +```js-nolint +blur() +``` + +### Parameters + +None. + +### Return value + +None ({{jsxref("undefined")}}). + +## Examples + +### Remove focus from a MathML element + +#### HTML + +```html +<div> + <math> + <msup id="myMath" tabindex="0"> + <mi>x</mi> + <mn>2</mn> + </msup> + </math> + <button id="focusButton">Focus the Math</button> + <button id="blurButton">Blur the Math</button> +</div> +``` + +#### JavaScript + +```js +const mathElement = document.getElementById("myMath"); +const focusButton = document.getElementById("focusButton"); +const blurButton = document.getElementById("blurButton"); + +// Focus the MathMLElement when the "Focus" button is clicked +focusButton.addEventListener("click", () => { + mathElement.focus(); +}); + +// Blur the MathMLElement when the "Blur" button is clicked +blurButton.addEventListener("click", () => { + mathElement.blur(); +}); +``` + +### Result + +{{EmbedLiveSample("blur",100,100)}} + +## Specifications + +{{Specifications}} + +## Browser compatibility + +{{Compat}} + +## See also + +- {{domxref("MathMLElement.focus()")}} +- {{domxref("HTMLElement.blur()")}} diff --git a/files/en-us/web/api/mathmlelement/dataset/index.md b/files/en-us/web/api/mathmlelement/dataset/index.md new file mode 100644 index 000000000000000..28024e3f9520c3d --- /dev/null +++ b/files/en-us/web/api/mathmlelement/dataset/index.md @@ -0,0 +1,59 @@ +--- +title: "MathMLElement: dataset property" +short-title: dataset +slug: Web/API/MathMLElement/dataset +page-type: web-api-instance-property +browser-compat: api.MathMLElement.dataset +--- + +{{APIRef("MathML")}} + +The **`dataset`** read-only property of the {{DOMxRef("MathMLElement")}} interface provides read/write access to [custom data attributes](/en-US/docs/Web/MathML/Reference/Global_attributes/data-*) (`data-*`) on elements. It exposes a map of strings ({{domxref("DOMStringMap")}}) with an entry for each `data-*` attribute. + +The `dataset` property itself can be read, but not directly written. Instead, all writes must be to the individual properties within the `dataset`, which in turn represent the data attributes. + +## Value + +A {{domxref("DOMStringMap")}}. + +## Examples + +```html +<div> + <math> + <msup id="equation" data-value="-1" data-equation="euler"> + <mi>e</mi> + <mi>iπ</mi> + </msup> + <mo>+</mo> + <mn>1</mn> + <mo>=</mo> + <mn>0</mn> + </math> +</div> +``` + +```js +const el = document.querySelector("#equation"); + +console.log(el.dataset.value); // "-1" +console.log(el.dataset.equation); // "euler" +``` + +### Result + +{{EmbedLiveSample("dataset",100,100)}} + +## Specifications + +{{Specifications}} + +## Browser compatibility + +{{Compat}} + +## See also + +- {{domxref("HTMLElement.dataset")}} +- [`data-*`](/en-US/docs/Web/MathML/Reference/Global_attributes/data-*) +- [Using data attributes](/en-US/docs/Web/HTML/How_to/Use_data_attributes) diff --git a/files/en-us/web/api/mathmlelement/focus/index.md b/files/en-us/web/api/mathmlelement/focus/index.md new file mode 100644 index 000000000000000..d65a2b412dceffa --- /dev/null +++ b/files/en-us/web/api/mathmlelement/focus/index.md @@ -0,0 +1,79 @@ +--- +title: "MathMLElement: focus() method" +short-title: focus() +slug: Web/API/MathMLElement/focus +page-type: web-api-instance-method +browser-compat: api.MathMLElement.focus +--- + +{{APIRef("MathML")}} + +The **`focus()`** method of the {{domxref("MathMLElement")}} interface sets focus on the specified MathML element, if it can be focused. The focused element is the element that will receive keyboard and similar events by default. + +By default the browser will scroll the element into view after focusing it, and it may also provide visible indication of the focused element (typically by displaying a "focus ring" around the element). Parameter options are provided to disable the default scrolling and force visible indication on elements. If you call `focus()` from a `mousedown` event handler, you must call `event.preventDefault()` to keep the focus from leaving the `MathMLElement`. + +## Syntax + +```js-nolint +focus() +focus(options) +``` + +### Parameters + +- `options` {{optional_inline}} + - : An object for controlling aspects of the focusing process. + This object may contain the following properties: + - `preventScroll` {{optional_inline}} + - : A boolean value indicating whether or not the browser should scroll the document to bring the newly-focused element into view. A value of `false` for `preventScroll` (the default) means that the browser will scroll the element into view after focusing it. If `preventScroll` is set to `true`, no scrolling will occur. + +### Return value + +None ({{jsxref("undefined")}}). + +## Examples + +### Focusing a MathML element + +This example uses a button to set the focus on a MathML circle element. + +#### HTML + +```html +<div> + <math> + <msup id="myMath" tabindex="0"> + <mi>x</mi> + <mn>2</mn> + </msup> + </math> + <button id="focusButton">Focus the Math</button> +</div> +``` + +#### JavaScript + +```js +const mathElement = document.getElementById("myMath"); + +document.getElementById("focusButton").addEventListener("click", () => { + mathElement.focus(); +}); +``` + +### Result + +{{EmbedLiveSample("focus",100,100)}} + +## Specifications + +{{Specifications}} + +## Browser compatibility + +{{Compat}} + +## See also + +- {{domxref("MathMLElement.blur()")}} +- {{domxref("HTMLElement.focus()")}} diff --git a/files/en-us/web/api/mathmlelement/index.md b/files/en-us/web/api/mathmlelement/index.md index 845e1d4501fead8..9a44899cf0fbc9f 100644 --- a/files/en-us/web/api/mathmlelement/index.md +++ b/files/en-us/web/api/mathmlelement/index.md @@ -17,12 +17,23 @@ _Also inherits properties from its parent, {{DOMxRef("Element")}}_. - {{DOMxRef("MathMLElement.attributeStyleMap")}} {{ReadOnlyInline}} - : A {{DOMxRef("StylePropertyMap")}} representing the declarations of the element's `style` attribute. +- {{DOMxRef("MathMLElement.autofocus")}} + - : Whether the control should be focused when the page loads, or when a {{htmlelement("dialog")}} or [popover](/en-US/docs/Web/HTML/Reference/Global_attributes/popover) become shown. +- {{DOMxRef("MathMLElement.dataset")}} {{ReadOnlyInline}} + - : A {{DOMxRef("DOMStringMap")}} object which provides a list of key/value pairs of named data attributes which correspond to [custom data attributes](/en-US/docs/Web/HTML/How_to/Use_data_attributes) attached to the element. This works just like HTML's {{DOMxRef("HTMLElement.dataset")}} property and HTML's [`data-*`](/en-US/docs/Web/HTML/Reference/Global_attributes/data-*) global attribute. - {{DOMxRef("MathMLElement.style")}} - : A {{DOMxRef("CSSStyleDeclaration")}} representing the declarations of the element's `style` attribute. +- {{DOMxRef("MathMLElement.tabIndex")}} + - : The position of the element in the tabbing order. ## Instance methods -_This interface has no methods, but inherits methods from its parent, {{DOMxRef("Element")}}_. +_This interface also inherits methods from its parent, {{DOMxRef("Element")}}_. + +- {{DOMxRef("MathMLElement.blur()")}} + - : Removes keyboard focus from the currently focused element. +- {{DOMxRef("MathMLElement.focus()")}} + - : Makes the element the current keyboard focus. ## Examples diff --git a/files/en-us/web/api/mathmlelement/style/index.md b/files/en-us/web/api/mathmlelement/style/index.md index 8c73e32a4ab40ff..ea8e4a97ffec961 100644 --- a/files/en-us/web/api/mathmlelement/style/index.md +++ b/files/en-us/web/api/mathmlelement/style/index.md @@ -8,7 +8,7 @@ browser-compat: api.MathMLElement.style {{APIRef("CSSOM")}} -The read-only **`style`** property of the {{domxref("MathMLElement")}} returns the _inline_ style of an element in the form of a live {{domxref("CSSStyleDeclaration")}} object that contains a list of all styles properties for that element with values assigned only for the attributes that are defined in the element's inline [`style`](/en-US/docs/Web/HTML/Global_attributes/style) attribute. +The read-only **`style`** property of the {{domxref("MathMLElement")}} returns the _inline_ style of an element in the form of a live {{domxref("CSSStyleDeclaration")}} object that contains a list of all styles properties for that element with values assigned only for the attributes that are defined in the element's inline [`style`](/en-US/docs/Web/HTML/Reference/Global_attributes/style) attribute. Shorthand properties are expanded. If you set `style="border-top: 1px solid black"`, the longhand properties ({{cssxref("border-top-color")}}, {{cssxref("border-top-style")}}, and {{cssxref("border-top-width")}}) are set instead. @@ -62,7 +62,7 @@ for (const prop in elementStyle) { // We also ensure that the property is a numeric index (indicating an inline style) if ( Object.hasOwn(elementStyle, prop) && - !Number.isNaN(Number.parseInt(prop)) + !Number.isNaN(Number.parseInt(prop, 10)) ) { out.textContent += `${ elementStyle[prop] diff --git a/files/en-us/web/api/mathmlelement/tabindex/index.md b/files/en-us/web/api/mathmlelement/tabindex/index.md new file mode 100644 index 000000000000000..735c9f535061942 --- /dev/null +++ b/files/en-us/web/api/mathmlelement/tabindex/index.md @@ -0,0 +1,73 @@ +--- +title: "MathMLElement: tabIndex property" +short-title: tabIndex +slug: Web/API/MathMLElement/tabIndex +page-type: web-api-instance-property +browser-compat: api.MathMLElement.tabIndex +--- + +{{APIRef("MathML")}} + +The **`tabIndex`** property of the {{DOMxRef("MathMLElement")}} interface represents the tab order of the current MathML element. + +Tab order is as follows: + +1. Elements with a positive `tabIndex`. Elements that have identical `tabIndex` values should be navigated in the order they appear. Navigation proceeds from the lowest `tabIndex` to the highest `tabIndex`. +2. Elements that do not support the `tabIndex` attribute or support it and assign `tabIndex` to `0`, in the order they appear. + +Elements that are disabled do not participate in the tabbing order. Values don't need to be sequential, nor must they begin with any particular value. They may even be negative, though each browser trims very large values. + +## Value + +An integer. + +## Examples + +### Using the tabIndex property + +```html +<math id="math1" tabindex="2"> + <msup> + <mi>a</mi> + <mn>2</mn> + </msup> +</math> + +<math id="math2"> + <mfrac> + <mn>1</mn> + <mn>2</mn> + </mfrac> +</math> +``` + +```js +const math1 = document.getElementById("math1"); +const math2 = document.getElementById("math2"); + +// Access and modify the tabIndex +console.log(math1.tabIndex); // 2 +math2.tabIndex = 1; // Add math2 to the tab order before math1 + +// Programmatically focus on an element with negative tabIndex +math1.tabIndex = -1; +math1.focus(); // Works, even though it is not in the tabbing order +``` + +### Result + +{{EmbedLiveSample("tabindex",100,100)}} + +## Specifications + +{{Specifications}} + +## Browser compatibility + +{{Compat}} + +## See also + +- {{domxref("HTMLElement.tabIndex")}} +- [Accessibility of keyboard-navigable JavaScript widgets](/en-US/docs/Web/Accessibility/Guides/Keyboard-navigable_JavaScript_widgets) +- [`tabindex`](/en-US/docs/Web/MathML/Reference/Global_attributes/tabindex) diff --git a/files/en-us/web/api/media_capabilities_api/using_the_media_capabilities_api/index.md b/files/en-us/web/api/media_capabilities_api/using_the_media_capabilities_api/index.md index b20dc7a2a144104..73d5caadac201ea 100644 --- a/files/en-us/web/api/media_capabilities_api/using_the_media_capabilities_api/index.md +++ b/files/en-us/web/api/media_capabilities_api/using_the_media_capabilities_api/index.md @@ -38,7 +38,7 @@ Taking video as an example, to obtain information about video decoding abilities The {{domxref("MediaCapabilities.decodingInfo()")}} method takes as a parameter a media decoding configuration. -In our example, we are testing the decoding capabilities of a video configuration. The configuration requires the type of media being tested — e.g. a plain `file` or {{domxref("MediaSource")}} — and a video configuration object that includes values for the `contentType`, `width`, `height`, `bitrate`, and `framerate`: +In our example, we are testing the decoding capabilities of a video configuration. The configuration requires the type of media being tested — e.g., a plain `file` or {{domxref("MediaSource")}} — and a video configuration object that includes values for the `contentType`, `width`, `height`, `bitrate`, and `framerate`: - The `contentType` must be a string specifying a [valid video MIME type](/en-US/docs/Web/Media/Guides/Formats/Video_codecs). - The `width` and `height` are the horizontal and vertical dimensions of the video; these are also used to determine the {{glossary("aspect ratio")}}. @@ -73,7 +73,7 @@ const audioConfiguration = { ``` Had we been testing encoding capabilities, we would have created a slightly different configuration. -In this case the type of media being tested is either `record` (for recording media, i.e. a {{domxref("MediaRecorder")}} object) or `transmission` (for media transmitted over electronic means like [`RTCPeerConnection`](/en-US/docs/Web/API/RTCPeerConnection)) — plus either an audio or video configuration as described above. +In this case the type of media being tested is either `record` (for recording media, i.e., a {{domxref("MediaRecorder")}} object) or `transmission` (for media transmitted over electronic means like [`RTCPeerConnection`](/en-US/docs/Web/API/RTCPeerConnection)) — plus either an audio or video configuration as described above. ### Querying the browser about decoding abilities @@ -190,7 +190,7 @@ li { ```js let mc = { - videoConfiguration: new Object(), + videoConfiguration: {}, tryIt() { mc.createConfiguration(); diff --git a/files/en-us/web/api/media_capture_and_streams_api/constraints/index.md b/files/en-us/web/api/media_capture_and_streams_api/constraints/index.md index 72b821caf12032d..b32ac018eb79999 100644 --- a/files/en-us/web/api/media_capture_and_streams_api/constraints/index.md +++ b/files/en-us/web/api/media_capture_and_streams_api/constraints/index.md @@ -103,7 +103,7 @@ Here, after ensuring that the constrainable properties for which matches must be ### Advanced constraints -So-called advanced constraints are created by adding an `advanced` property to the constraint set; this property's value is an array of additional constraint sets which are considered optional. There are few if any use cases for this feature, and there is some interest in removing it from the specification, so it will not be discussed here. If you wish to learn more, see [section 11 of the Media Capture and Streams specification](https://www.w3.org/TR/mediacapture-streams/#idl-def-Constraints), past example 2. +So-called advanced constraints are created by adding an `advanced` property to the constraint set; this property's value is an array of additional constraint sets which are considered optional. There are few if any use cases for this feature, and there is some interest in removing it from the specification, so it will not be discussed here. If you wish to learn more, see [section 11 of the Media Capture and Streams specification](https://w3c.github.io/mediacapture-main/#constrainable-interface), past example 2. ## Checking capabilities @@ -122,26 +122,17 @@ navigator.mediaDevices An example capabilities object looks like this: -```js +```json { - "autoGainControl": [ - true, - false - ], + "autoGainControl": [true, false], "channelCount": { "max": 1, "min": 1 }, "deviceId": "jjxEMqxIhGdryqbTjDrXPWrkjy55Vte70kWpMe3Lge8=", - "echoCancellation": [ - true, - false - ], + "echoCancellation": [true, false], "groupId": "o2tZiEj4MwOdG/LW3HwkjpLm1D8URat4C5kt742xrVQ=", - "noiseSuppression": [ - true, - false - ] + "noiseSuppression": [true, false] } ``` @@ -448,11 +439,12 @@ function startVideo() { videoTrack = videoTracks[0]; } }) - .then(() => { - return new Promise((resolve) => { - videoElement.onloadedmetadata = resolve; - }); - }) + .then( + () => + new Promise((resolve) => { + videoElement.onloadedmetadata = resolve; + }), + ) .then(() => { getCurrentSettings(); }) diff --git a/files/en-us/web/api/media_capture_and_streams_api/index.md b/files/en-us/web/api/media_capture_and_streams_api/index.md index f827ce501dc6985..a4eaf7fbff3bd88 100644 --- a/files/en-us/web/api/media_capture_and_streams_api/index.md +++ b/files/en-us/web/api/media_capture_and_streams_api/index.md @@ -60,6 +60,10 @@ The [Capabilities, constraints, and settings](/en-US/docs/Web/API/Media_Capture_ The [Taking still photos with getUserMedia()](/en-US/docs/Web/API/Media_Capture_and_Streams_API/Taking_still_photos) article shows how to use [`getUserMedia()`](/en-US/docs/Web/API/MediaDevices/getUserMedia) to access the camera on a computer or mobile phone with `getUserMedia()` support and take a photo with it. +## Specifications + +{{Specifications}} + ## Browser compatibility {{Compat}} diff --git a/files/en-us/web/api/media_capture_and_streams_api/taking_still_photos/index.md b/files/en-us/web/api/media_capture_and_streams_api/taking_still_photos/index.md index 1167a0714400c99..da056f5fd53d768 100644 --- a/files/en-us/web/api/media_capture_and_streams_api/taking_still_photos/index.md +++ b/files/en-us/web/api/media_capture_and_streams_api/taking_still_photos/index.md @@ -88,10 +88,10 @@ First, we grab references to the major elements we need to be able to access. ```js function startup() { - video = document.getElementById('video'); - canvas = document.getElementById('canvas'); - photo = document.getElementById('photo'); - startButton = document.getElementById('start-button'); + video = document.getElementById("video"); + canvas = document.getElementById("canvas"); + photo = document.getElementById("photo"); + startButton = document.getElementById("start-button"); ``` #### Get the media stream @@ -114,13 +114,13 @@ Here, we're calling {{domxref("MediaDevices.getUserMedia()")}} and requesting a The success callback receives a `stream` object as input. It is the {{HTMLElement("video")}} element's source to our new stream. -Once the stream is linked to the `<video>` element, we start it playing by calling [`HTMLMediaElement.play()`](/en-US/docs/Web/API/HTMLMediaElement#play). +Once the stream is linked to the `<video>` element, we start it playing by calling [`HTMLMediaElement.play()`](/en-US/docs/Web/API/HTMLMediaElement/play_event). The error callback is called if opening the stream doesn't work. This will happen for example if there's no compatible camera connected, or the user denied access. #### Listen for the video to start playing -After calling [`HTMLMediaElement.play()`](/en-US/docs/Web/API/HTMLMediaElement#play) on the {{HTMLElement("video")}}, there's a (hopefully brief) period of time that elapses before the stream of video begins to flow. To avoid blocking until that happens, we add an event listener to `video` for the {{domxref("HTMLMediaElement/canplay_event", "canplay")}} event, which is delivered when the video playback actually begins. At that point, all the properties in the `video` object have been configured based on the stream's format. +After calling [`HTMLMediaElement.play()`](/en-US/docs/Web/API/HTMLMediaElement/play_event) on the {{HTMLElement("video")}}, there's a (hopefully brief) period of time that elapses before the stream of video begins to flow. To avoid blocking until that happens, we add an event listener to `video` for the {{domxref("HTMLMediaElement/canplay_event", "canplay")}} event, which is delivered when the video playback actually begins. At that point, all the properties in the `video` object have been configured based on the stream's format. ```js video.addEventListener( @@ -442,7 +442,250 @@ If there isn't a valid image available (that is, the `width` and `height` are bo ## Fun with filters -Since we're capturing images from the user's webcam by grabbing frames from a {{HTMLElement("video")}} element, we can very easily apply filters and fun effects to the video. As it turns out, any CSS filters you apply to the element using the {{cssxref("filter")}} property affect the captured photo. These filters can range from the simple (making the image black and white) to the extreme (gaussian blurs and hue rotation). +Since we're capturing images from the user's webcam by grabbing frames from a {{HTMLElement("video")}} element, we can apply fun effects to the video with filters. These filters range from basic (making the image black and white) to complex (Gaussian blurs and hue rotation). + +For the video filters to be applied to the photo, the `takePicture()` function needs the following changes. Note that, while CSS {{cssxref("filter")}} effects applied to the video element affect its display, they do not automatically apply to the captured photo unless handled in the canvas drawing process. + +```js +function takePicture() { + const context = canvas.getContext("2d"); + if (width && height) { + canvas.width = width; + canvas.height = height; + + // Get the computed CSS filter from the video element. + // For example, it might return "grayscale(100%)" + const videoStyles = window.getComputedStyle(video); + const filterValue = videoStyles.getPropertyValue("filter"); + + // Apply the filter to the canvas drawing context. + // If there's no filter (i.e., it returns "none"), default to "none". + context.filter = filterValue !== "none" ? filterValue : "none"; + + context.drawImage(video, 0, 0, width, height); + + const dataUrl = canvas.toDataURL("image/png"); + photo.setAttribute("src", dataUrl); + } else { + clearPhoto(); + } +} +``` + +```html hidden live-sample___photo-capture-with-filters +<div class="content-area"> + <h1>MDN - navigator.mediaDevices.getUserMedia(): Still photo capture demo</h1> + <p> + This example demonstrates how to set up a media stream using your built-in + webcam, fetch an image from that stream, and create a PNG using that image. + </p> + <div class="camera"> + <video id="video">Video stream not available.</video> + <button id="start-button">Take photo</button> + </div> + <canvas id="canvas"> </canvas> + <div class="output"> + <img id="photo" alt="The screen capture will appear in this box." /> + </div> + <p> + Visit our article + <a + href="https://developer.mozilla.org/en-US/docs/Web/API/Media_Capture_and_Streams_API/Taking_still_photos"> + Taking still photos with WebRTC + </a> + to learn more about the technologies used here. + </p> +</div> +``` + +```css hidden live-sample___photo-capture-with-filters +#video { + border: 1px solid black; + box-shadow: 2px 2px 3px black; + width: 320px; + height: 240px; + filter: grayscale(100%); +} + +#photo { + border: 1px solid black; + box-shadow: 2px 2px 3px black; + width: 320px; + height: 240px; +} + +#canvas { + display: none; +} + +.camera { + width: 340px; + display: inline-block; +} + +.output { + width: 340px; + display: inline-block; + vertical-align: top; +} + +#start-button { + display: block; + position: relative; + margin-left: auto; + margin-right: auto; + bottom: 32px; + background-color: rgb(0 150 0 / 50%); + border: 1px solid rgb(255 255 255 / 70%); + box-shadow: 0px 0px 1px 2px rgb(0 0 0 / 20%); + font-size: 14px; + font-family: "Lucida Grande", "Arial", sans-serif; + color: rgb(255 255 255 / 100%); +} + +.content-area { + font: + 1.2rem "Lucida Grande", + "Arial", + sans-serif; + width: 760px; + padding: 2rem; +} +``` + +```js hidden live-sample___photo-capture-with-filters +(() => { + // The width and height of the captured photo. We will set the + // width to the value defined here, but the height will be + // calculated based on the aspect ratio of the input stream. + const width = 320; // We will scale the photo width to this + let height = 0; // This will be computed based on the input stream + + // |streaming| indicates whether or not we're currently streaming + // video from the camera. Obviously, we start at false. + let streaming = false; + + // The various HTML elements we need to configure or control. These + // will be set by the startup() function. + let video = null; + let canvas = null; + let photo = null; + let startButton = null; + + function showViewLiveResultButton() { + if (window.self !== window.top) { + // Ensure that if our document is in a frame, we get the user + // to first open it in its own tab or window. Otherwise, it + // won't be able to request permission for camera access. + document.querySelector(".content-area").remove(); + const button = document.createElement("button"); + button.textContent = "Open example in new window"; + document.body.append(button); + button.addEventListener("click", () => + window.open( + location.href, + "MDN", + "width=850,height=700,left=150,top=150", + ), + ); + return true; + } + return false; + } + + function startup() { + if (showViewLiveResultButton()) { + return; + } + video = document.getElementById("video"); + canvas = document.getElementById("canvas"); + photo = document.getElementById("photo"); + startButton = document.getElementById("start-button"); + + navigator.mediaDevices + .getUserMedia({ video: true, audio: false }) + .then((stream) => { + video.srcObject = stream; + video.play(); + }) + .catch((err) => { + console.error(`An error occurred: ${err}`); + }); + + video.addEventListener( + "canplay", + (ev) => { + if (!streaming) { + height = video.videoHeight / (video.videoWidth / width); + + // Firefox currently has a bug where the height can't be read from + // the video, so we will make assumptions if this happens. + if (isNaN(height)) { + height = width / (4 / 3); + } + + video.setAttribute("width", width); + video.setAttribute("height", height); + canvas.setAttribute("width", width); + canvas.setAttribute("height", height); + streaming = true; + } + }, + false, + ); + + startButton.addEventListener( + "click", + (ev) => { + takePicture(); + ev.preventDefault(); + }, + false, + ); + + clearPhoto(); + } + + // Fill the photo with an indication that none has been captured. + function clearPhoto() { + const context = canvas.getContext("2d"); + context.fillStyle = "#AAA"; + context.fillRect(0, 0, canvas.width, canvas.height); + + const data = canvas.toDataURL("image/png"); + photo.setAttribute("src", data); + } + + // Capture a photo by fetching the current contents of the video + // and drawing it into a canvas, then converting that to a PNG + // format data URL. By drawing it on an offscreen canvas and then + // drawing that to the screen, we can change its size and/or apply + // other changes before drawing it. + function takePicture() { + const context = canvas.getContext("2d"); + if (width && height) { + canvas.width = width; + canvas.height = height; + + const videoStyles = window.getComputedStyle(video); + const filterValue = videoStyles.getPropertyValue("filter"); + context.filter = filterValue !== "none" ? filterValue : "none"; + context.drawImage(video, 0, 0, width, height); + + const data = canvas.toDataURL("image/png"); + photo.setAttribute("src", data); + } else { + clearPhoto(); + } + } + + // Set up our event listener to run the startup process + // once loading is complete. + window.addEventListener("load", startup, false); +})(); +``` + +{{EmbedLiveSample('photo-capture-with-filters', '100%', '30', , , , , 'allow-popups')}} You can play with this effect using, for example, the Firefox developer tools' [style editor](https://firefox-source-docs.mozilla.org/devtools-user/style_editor/index.html); see [Edit CSS filters](https://firefox-source-docs.mozilla.org/devtools-user/page_inspector/how_to/edit_css_filters/index.html) for details on how to do so. diff --git a/files/en-us/web/api/media_source_extensions_api/dash_adaptive_streaming/index.md b/files/en-us/web/api/media_source_extensions_api/dash_adaptive_streaming/index.md new file mode 100644 index 000000000000000..e28a7e369a85e76 --- /dev/null +++ b/files/en-us/web/api/media_source_extensions_api/dash_adaptive_streaming/index.md @@ -0,0 +1,86 @@ +--- +title: DASH Adaptive Streaming for HTML video +slug: Web/API/Media_Source_Extensions_API/DASH_Adaptive_Streaming +page-type: guide +--- + +{{DefaultAPISidebar("Media Source Extensions")}} + +Dynamic Adaptive Streaming over HTTP (DASH) is an adaptive streaming protocol. This means that it allows for a video stream to switch between bit rates on the basis of network performance, in order to keep a video playing. + +First you'll need to convert your WebM video to a DASH manifest with the accompanying video files in various bit rates. To start with you'll only need the FFmpeg program from [ffmpeg.org](https://www.ffmpeg.org/), with libvpx and libvorbis support for WebM video and audio, at least version 2.5 (probably; this was tested with 3.2.5). + +First, use your existing WebM file to create one audio file and multiple video files. In the example below, the file **_in.video_** can be any container with at least one audio and one video stream that can be decoded by FFmpeg. + +Create the audio using: + +```bash +ffmpeg -i in.video -vn -acodec libvorbis -ab 128k -dash 1 my_audio.webm +``` + +Create each video variant. + +```bash +ffmpeg -i in.video -c:v libvpx-vp9 -keyint_min 150 -g 150 -tile-columns 4 -frame-parallel 1 -f webm -dash 1 \ +-an -vf scale=160:90 -b:v 250k -dash 1 video_160x90_250k.webm +``` + +```bash +ffmpeg -i in.video -c:v libvpx-vp9 -keyint_min 150 -g 150 -tile-columns 4 -frame-parallel 1 -f webm -dash 1 \ +-an -vf scale=320:180 -b:v 500k -dash 1 video_320x180_500k.webm +``` + +```bash +ffmpeg -i in.video -c:v libvpx-vp9 -keyint_min 150 -g 150 -tile-columns 4 -frame-parallel 1 -f webm -dash 1 \ +-an -vf scale=640:360 -b:v 750k -dash 1 video_640x360_750k.webm +``` + +```bash +ffmpeg -i in.video -c:v libvpx-vp9 -keyint_min 150 -g 150 -tile-columns 4 -frame-parallel 1 -f webm -dash 1 \ +-an -vf scale=640:360 -b:v 1000k -dash 1 video_640x360_1000k.webm +``` + +```bash +ffmpeg -i in.video -c:v libvpx-vp9 -keyint_min 150 -g 150 -tile-columns 4 -frame-parallel 1 -f webm -dash 1 \ +-an -vf scale=1280:720 -b:v 1500k -dash 1 video_1280x720_1500k.webm +``` + +Or do it in all in one command. + +```bash +ffmpeg -i in.video -c:v libvpx-vp9 -keyint_min 150 \ +-g 150 -tile-columns 4 -frame-parallel 1 -f webm -dash 1 \ +-an -vf scale=160:90 -b:v 250k -dash 1 video_160x90_250k.webm \ +-an -vf scale=320:180 -b:v 500k -dash 1 video_320x180_500k.webm \ +-an -vf scale=640:360 -b:v 750k -dash 1 video_640x360_750k.webm \ +-an -vf scale=640:360 -b:v 1000k -dash 1 video_640x360_1000k.webm \ +-an -vf scale=1280:720 -b:v 1500k -dash 1 video_1280x720_1500k.webm +``` + +Then, create the manifest file. + +```bash +ffmpeg \ + -f webm_dash_manifest -i video_160x90_250k.webm \ + -f webm_dash_manifest -i video_320x180_500k.webm \ + -f webm_dash_manifest -i video_640x360_750k.webm \ + -f webm_dash_manifest -i video_1280x720_1500k.webm \ + -f webm_dash_manifest -i my_audio.webm \ + -c copy \ + -map 0 -map 1 -map 2 -map 3 -map 4 \ + -f webm_dash_manifest \ + -adaptation_sets "id=0,streams=0,1,2,3 id=1,streams=4" \ + my_video_manifest.mpd +``` + +The `-map` arguments correspond to the input files in the sequence they are given; you should have one for each file. The `-adaptation_sets` argument assigns them into adaptation sets; for example, this creates one set (0) that contains the streams 0, 1, 2 and 3 (the videos), and another set (1) that contains only stream 4, the audio stream. + +Put the manifest and the associated video files on your web server or CDN. DASH works via HTTP, so as long as your HTTP server supports byte range requests, and it's set up to serve `.mpd` files with `Content-Type: application/dash+xml`, then you're all set. + +Then, in order to correctly connect this `.mpd` file to your `<video>` element, you need a JavaScript library like dash.js, because no browser has native support for DASH. Read [dash.js quickstart](https://dashif.org/dash.js/pages/quickstart/) for how to set up your page to use it. + +## See also + +- [WebM DASH Specification at The WebM Project](https://wiki.webmproject.org/adaptive-streaming/webm-dash-specification) +- [DASH Industry Forum](https://dashif.org/) +- [WebM project description of how to create DASH files with FFMPEG](https://wiki.webmproject.org/adaptive-streaming/instructions-to-playback-adaptive-webm-using-dash) diff --git a/files/en-us/web/api/media_source_extensions_api/index.md b/files/en-us/web/api/media_source_extensions_api/index.md index 18008e38e82ead7..2aaa521cef87562 100644 --- a/files/en-us/web/api/media_source_extensions_api/index.md +++ b/files/en-us/web/api/media_source_extensions_api/index.md @@ -35,7 +35,7 @@ The two most common use cases for DASH involve watching content "on demand" or " Live profile content can introduce latency due to its transcoding and broadcasting, so DASH is not suitable for real time communication like [WebRTC](/en-US/docs/Web/API/WebRTC_API) is. It can however support significantly more client connections than WebRTC. -There are numerous available free and open source tools for transcoding content and preparing it for use with DASH, DASH file servers, and DASH client libraries written in JavaScript. +There are numerous available free and open source tools for transcoding content and preparing it for use with DASH, DASH file servers, and DASH client libraries written in JavaScript. The [DASH Adaptive Streaming for HTML video](/en-US/docs/Web/API/Media_Source_Extensions_API/DASH_Adaptive_Streaming) article provides an example of how to use DASH with MSE. ### Availability in workers diff --git a/files/en-us/web/api/media_source_extensions_api/transcoding_assets_for_mse/index.md b/files/en-us/web/api/media_source_extensions_api/transcoding_assets_for_mse/index.md index cf5ed1c1af455b4..798053dcc63edf8 100644 --- a/files/en-us/web/api/media_source_extensions_api/transcoding_assets_for_mse/index.md +++ b/files/en-us/web/api/media_source_extensions_api/transcoding_assets_for_mse/index.md @@ -25,7 +25,7 @@ If you're looking to follow the steps listed here, but don't have any media to e When working with MSE, the following tools are a must have: 1. [ffmpeg](https://ffmpeg.org/) — A command-line utility for transcoding your media into the required formats. You can download a version for your system at the [Download FFmpeg page](https://ffmpeg.org/download.html). Extract the executable from the archive file and add it's location to your PATH statement. OSX users can also use [homebrew](https://brew.sh/) to install ffmpeg. -2. [Bento4](https://github.com/axiomatic-systems/Bento4) — A set of command-line utilities for getting asset metadata and creating content for DASH. To install, you'll need to build/compile the application yourself from the provided project files/source files, depending on your OS and preferences. See the [Building instructions](https://github.com/axiomatic-systems/Bento4#building) for more details. The prebuilt file is [here](https://www.bento4.com/downloads/). Put the contents of the `bin` directory in the same place as ffmpeg. +2. [Bento4](https://github.com/axiomatic-systems/Bento4) — A set of command-line utilities for getting asset metadata and creating content for DASH. To install, you'll need to build/compile the application yourself from the provided project files/source files, depending on your OS and preferences. See the [Building instructions](https://github.com/axiomatic-systems/Bento4#building) for more details, or download the [prebuilt file](https://www.bento4.com/downloads/). Put the contents of the `bin` directory in the same place as ffmpeg. 3. python2 — Bento4 uses it. Get these installed successfully before moving to the next step. diff --git a/files/en-us/web/api/mediacapabilities/decodinginfo/index.md b/files/en-us/web/api/mediacapabilities/decodinginfo/index.md index 1170e5910521c41..08310ba354e4d4c 100644 --- a/files/en-us/web/api/mediacapabilities/decodinginfo/index.md +++ b/files/en-us/web/api/mediacapabilities/decodinginfo/index.md @@ -224,7 +224,7 @@ function log(text) { ``` ```js -//Create media configuration to be tested +// Create media configuration to be tested const audioConfig = { type: "file", // or 'media-source' or 'webrtc' audio: { @@ -400,13 +400,13 @@ This will be the supported configuration that was found last, which because of t let keys = null; if (bestConfig) { keys = await bestConfig.keySystemAccess.createMediaKeys(); - // ... use keys to decode media using best config + // … use keys to decode media using best config } else if (nonSmoothConfig) { console.log( "No smooth configs found. Using lowest resolution configuration!", ); keys = await nonSmoothConfig.keySystemAccess.createMediaKeys(); - // ... use keys to decode media using lowest framerate config + // … use keys to decode media using lowest framerate config } else { console.log("No supported configs!"); // Fail! diff --git a/files/en-us/web/api/mediacapabilities/encodinginfo/index.md b/files/en-us/web/api/mediacapabilities/encodinginfo/index.md index bdf89116228957e..a986c6523c91f6f 100644 --- a/files/en-us/web/api/mediacapabilities/encodinginfo/index.md +++ b/files/en-us/web/api/mediacapabilities/encodinginfo/index.md @@ -28,9 +28,9 @@ encodingInfo(configuration) - : The type of media being tested. This takes one of two values: - `record` - - : Represents a configuration for recording of media, e.g. using {{domxref("MediaRecorder")}}. + - : Represents a configuration for recording of media, e.g., using {{domxref("MediaRecorder")}}. - `webrtc` - - : Represents a configuration meant to be transmitted over electronic means (e.g. using {{domxref("RTCPeerConnection")}}). **Note:** Firefox uses `transmission` for this type, and `webrtc` does not work. + - : Represents a configuration meant to be transmitted over electronic means (e.g., using {{domxref("RTCPeerConnection")}}). **Note:** Firefox uses `transmission` for this type, and `webrtc` does not work. - `transmission` {{non-standard_inline}} - : The synonym of `webrtc` to be used in Firefox. @@ -89,7 +89,7 @@ All supported audio codecs are reported to be power efficient. ## Examples ```js -//Create media configuration to be tested +// Create media configuration to be tested const mediaConfig = { type: "record", // or 'transmission' video: { diff --git a/files/en-us/web/api/mediadevices/devicechange_event/index.md b/files/en-us/web/api/mediadevices/devicechange_event/index.md index 5733ba7b3a4e96b..38ecdeff102a12b 100644 --- a/files/en-us/web/api/mediadevices/devicechange_event/index.md +++ b/files/en-us/web/api/mediadevices/devicechange_event/index.md @@ -16,10 +16,10 @@ This event is not cancelable and does not bubble. Use the event name in methods like {{domxref("EventTarget.addEventListener", "addEventListener()")}}, or set an event handler property. -```js -addEventListener("devicechange", (event) => {}); +```js-nolint +addEventListener("devicechange", (event) => { }) -ondevicechange = (event) => {}; +ondevicechange = (event) => { } ``` ## Event type @@ -192,7 +192,7 @@ display it to the user. The line `let [kind, type, direction] = device.kind.match(/(\w+)(input|output)/i);` -deserves special notice. This uses [destructuring assignment](/en-US/docs/Web/JavaScript/Reference/Operators/Destructuring_assignment) to assign the values of the first three items in the array returned by +deserves special notice. This uses [destructuring assignment](/en-US/docs/Web/JavaScript/Reference/Operators/Destructuring) to assign the values of the first three items in the array returned by {{jsxref("String.match()")}} to the variables `kind`, `type`, and `direction`. We do this because the value of {{domxref("MediaDeviceInfo.kind")}} is a single string that includes both the media type diff --git a/files/en-us/web/api/mediadevices/enumeratedevices/index.md b/files/en-us/web/api/mediadevices/enumeratedevices/index.md index 68d714b4c3a81a8..fadd9008c3ab4f9 100644 --- a/files/en-us/web/api/mediadevices/enumeratedevices/index.md +++ b/files/en-us/web/api/mediadevices/enumeratedevices/index.md @@ -11,7 +11,7 @@ browser-compat: api.MediaDevices.enumerateDevices The **`enumerateDevices()`** method of the {{domxref("MediaDevices")}} interface requests a list of the currently available media input and output devices, such as microphones, cameras, headsets, and so forth. The returned {{jsxref("Promise")}} is resolved with an array of {{domxref("MediaDeviceInfo")}} objects describing the devices. -The returned list will omit any devices that are blocked by the document [Permission Policy](/en-US/docs/Web/HTTP/Headers/Permissions-Policy): [`microphone`](/en-US/docs/Web/HTTP/Headers/Permissions-Policy/microphone), [`camera`](/en-US/docs/Web/HTTP/Headers/Permissions-Policy/camera), [`speaker-selection`](/en-US/docs/Web/HTTP/Headers/Permissions-Policy/speaker-selection) (for output devices), and so on. +The returned list will omit any devices that are blocked by the document [Permission Policy](/en-US/docs/Web/HTTP/Reference/Headers/Permissions-Policy): [`microphone`](/en-US/docs/Web/HTTP/Reference/Headers/Permissions-Policy/microphone), [`camera`](/en-US/docs/Web/HTTP/Reference/Headers/Permissions-Policy/camera), [`speaker-selection`](/en-US/docs/Web/HTTP/Reference/Headers/Permissions-Policy/speaker-selection) (for output devices), and so on. Access to particular non-default devices is also gated by the [Permissions API](/en-US/docs/Web/API/Permissions_API), and the list will omit devices for which the user has not granted explicit permission. ## Syntax diff --git a/files/en-us/web/api/mediadevices/getdisplaymedia/index.md b/files/en-us/web/api/mediadevices/getdisplaymedia/index.md index ba80ebeb3b23df5..bfb063906f8b7dc 100644 --- a/files/en-us/web/api/mediadevices/getdisplaymedia/index.md +++ b/files/en-us/web/api/mediadevices/getdisplaymedia/index.md @@ -43,7 +43,7 @@ getDisplayMedia(options) > You cannot set `monitorTypeSurfaces: "exclude"` at the same time as [`displaySurface: "monitor"`](/en-US/docs/Web/API/MediaTrackConstraints/displaySurface) as the two settings are contradictory. Trying to do so will result in the `getDisplayMedia()` call failing with a `TypeError`. - `preferCurrentTab` {{non-standard_inline}} {{Experimental_Inline}} {{optional_inline}} - - : A boolean; a value of `true` instructs the browser to offer the current tab as the most prominent capture source, i.e. as a separate "This Tab" option in the "Choose what to share" options presented to the user. This is useful as many app types generally just want to share the current tab. For example, a slide deck app might want to let the user stream the current tab containing the presentation to a virtual conference. A default value is not mandated by the spec; see the [Browser compatibility](#browser_compatibility) section for browser-specific defaults. + - : A boolean; a value of `true` instructs the browser to offer the current tab as the most prominent capture source, i.e., as a separate "This Tab" option in the "Choose what to share" options presented to the user. This is useful as many app types generally just want to share the current tab. For example, a slide deck app might want to let the user stream the current tab containing the presentation to a virtual conference. A default value is not mandated by the spec; see the [Browser compatibility](#browser_compatibility) section for browser-specific defaults. - `selfBrowserSurface` {{Experimental_Inline}} {{optional_inline}} - : An enumerated value specifying whether the browser should allow the user to select the current tab for capture. This helps to avoid the "infinite hall of mirrors" effect experienced when a video conferencing app inadvertently shares its own display. Possible values are `include`, which hints that the browser should include the current tab in the choices offered for capture, and `exclude`, which hints that it should be excluded. A default value is not mandated by the spec; see the [Browser compatibility](#browser_compatibility) section for browser-specific defaults. - `surfaceSwitching` {{Experimental_Inline}} {{optional_inline}} @@ -73,7 +73,7 @@ audio track. not fully active or does not focused. Or if the `controller` options has been already used in creating another {{domxref("MediaStream")}}. - `NotAllowedError` {{domxref("DOMException")}} - - : Thrown if the permission to access a screen area was denied by the user, or the current browsing instance is not permitted access to screen sharing (for example by a [Permissions Policy](/en-US/docs/Web/HTTP/Permissions_Policy)). + - : Thrown if the permission to access a screen area was denied by the user, or the current browsing instance is not permitted access to screen sharing (for example by a [Permissions Policy](/en-US/docs/Web/HTTP/Guides/Permissions_Policy)). - `NotFoundError` {{domxref("DOMException")}} - : Thrown if no sources of screen video are available for capture. - `NotReadableError` {{domxref("DOMException")}} diff --git a/files/en-us/web/api/mediadevices/getusermedia/index.md b/files/en-us/web/api/mediadevices/getusermedia/index.md index c715ce074c01972..0b8e78ee2fe5295 100644 --- a/files/en-us/web/api/mediadevices/getusermedia/index.md +++ b/files/en-us/web/api/mediadevices/getusermedia/index.md @@ -67,7 +67,7 @@ object when the requested media has successfully been obtained. rather than HTTPS). It also happens if the user has specified that the current browsing instance is not permitted access to the device, the user has denied access for the current session, or the user has denied all access to user media devices - globally. On browsers that support managing media permissions with [Permissions Policy](/en-US/docs/Web/HTTP/Permissions_Policy), this error is + globally. On browsers that support managing media permissions with [Permissions Policy](/en-US/docs/Web/HTTP/Guides/Permissions_Policy), this error is returned if Permissions Policy is not configured to allow access to the input source(s). > [!NOTE] @@ -119,7 +119,7 @@ using HTTPS or the `file:///` URL scheme, or a page loaded from In addition, user permission is always required to access the user's audio and video inputs. Only a window's top-level document context for a valid origin can even request permission to use `getUserMedia()`, unless the top-level context expressly -grants permission for a given {{HTMLElement("iframe")}} to do so using [Permissions Policy](/en-US/docs/Web/HTTP/Permissions_Policy). Otherwise, the user +grants permission for a given {{HTMLElement("iframe")}} to do so using [Permissions Policy](/en-US/docs/Web/HTTP/Guides/Permissions_Policy). Otherwise, the user will never even be asked for permission to use the input devices. For additional details on these requirements and rules, how they are reflected in the @@ -156,7 +156,7 @@ There are a number of ways security management and controls in a {{Glossary("use #### Permissions Policy -The two [Permissions Policy](/en-US/docs/Web/HTTP/Permissions_Policy) directives that apply to `getUserMedia()` are `camera` +The two [Permissions Policy](/en-US/docs/Web/HTTP/Guides/Permissions_Policy) directives that apply to `getUserMedia()` are `camera` and `microphone`. For example, this HTTP header will enable use of a camera by the document @@ -205,13 +205,13 @@ situations in which `getUserMedia()` is not permitted to be called: - A document loaded into a sandboxed {{HTMLElement("iframe")}} element cannot call `getUserMedia()` unless the `<iframe>` has its - [`sandbox`](/en-US/docs/Web/HTML/Element/iframe#sandbox) attribute set to `allow-same-origin`. + [`sandbox`](/en-US/docs/Web/HTML/Reference/Elements/iframe#sandbox) attribute set to `allow-same-origin`. - A document loaded using a `data://` or `blob://` URL which has no origin (such as when one of these URLs is typed by the user into the address bar) cannot call `getUserMedia()`. These kinds of URLs loaded from JavaScript code inherit the script's permissions. - Any other situation in which there is no origin, such as when the - [`srcdoc`](/en-US/docs/Web/HTML/Element/iframe#srcdoc) attribute is used to specify the contents of a + [`srcdoc`](/en-US/docs/Web/HTML/Reference/Elements/iframe#srcdoc) attribute is used to specify the contents of a frame. ## Examples diff --git a/files/en-us/web/api/mediadevices/selectaudiooutput/index.md b/files/en-us/web/api/mediadevices/selectaudiooutput/index.md index e8f77f82c77f0bb..2a65c84c9e9b65b 100644 --- a/files/en-us/web/api/mediadevices/selectaudiooutput/index.md +++ b/files/en-us/web/api/mediadevices/selectaudiooutput/index.md @@ -49,7 +49,7 @@ A {{ jsxref("Promise") }} that is fulfilled with a {{domxref("MediaDeviceInfo")} ### Exceptions - `NotAllowedError` {{domxref("DOMException")}} - - : Returned if a [`speaker-selection`](/en-US/docs/Web/HTTP/Headers/Permissions-Policy/speaker-selection) [Permissions Policy](/en-US/docs/Web/HTTP/Permissions_Policy) is used to block use of audio outputs (in addition the popup for selecting an audio output won't be displayed), or the user closed the selection prompt without choosing a device. + - : Returned if a [`speaker-selection`](/en-US/docs/Web/HTTP/Reference/Headers/Permissions-Policy/speaker-selection) [Permissions Policy](/en-US/docs/Web/HTTP/Guides/Permissions_Policy) is used to block use of audio outputs (in addition the popup for selecting an audio output won't be displayed), or the user closed the selection prompt without choosing a device. - `NotFoundError` {{domxref("DOMException")}} - : Returned if there are no available audio output devices. - `InvalidStateError` {{domxref("DOMException")}} @@ -62,7 +62,7 @@ Access to the API is subject to the following constraints: - The method must be called in a [secure context](/en-US/docs/Web/Security/Secure_Contexts). - [Transient user activation](/en-US/docs/Web/Security/User_activation) is required. The user has to interact with the page or a UI element for this feature to work. -- Access may be gated by the [`speaker-selection`](/en-US/docs/Web/HTTP/Headers/Permissions-Policy/speaker-selection) HTTP [Permission Policy](/en-US/docs/Web/HTTP/Permissions_Policy). +- Access may be gated by the [`speaker-selection`](/en-US/docs/Web/HTTP/Reference/Headers/Permissions-Policy/speaker-selection) HTTP [Permission Policy](/en-US/docs/Web/HTTP/Guides/Permissions_Policy). The permission status can be queried using the [Permissions API](/en-US/docs/Web/API/Permissions_API) method {{domxref("Permissions.query", "navigator.permissions.query()")}}, passing a permission descriptor with the `speaker-selection` permission. diff --git a/files/en-us/web/api/mediaerror/code/index.md b/files/en-us/web/api/mediaerror/code/index.md index bf65cdfbaf23626..f6aad4f291f5b1d 100644 --- a/files/en-us/web/api/mediaerror/code/index.md +++ b/files/en-us/web/api/mediaerror/code/index.md @@ -67,7 +67,7 @@ values are described below, in [Media error code constants](#media_error_code_co ## Examples This example creates a {{HTMLElement("video")}} element, establishes an error handler -for it, and then sets the element's [`src`](/en-US/docs/Web/HTML/Element/video#src) attribute to the +for it, and then sets the element's [`src`](/en-US/docs/Web/HTML/Reference/Elements/video#src) attribute to the video resource to present in the element. The error handler outputs a message ```js diff --git a/files/en-us/web/api/mediaerror/message/index.md b/files/en-us/web/api/mediaerror/message/index.md index 9fc13c1c5ba023f..5a0a6ec4b877769 100644 --- a/files/en-us/web/api/mediaerror/message/index.md +++ b/files/en-us/web/api/mediaerror/message/index.md @@ -24,9 +24,9 @@ available, this string is empty. ## Examples -This example creates a {{HTMLElement("audio")}} element, establishes an error handler +This example creates an {{HTMLElement("audio")}} element, establishes an error handler for it, then lets the user click buttons to choose whether to assign a valid audio file -or a missing file to the element's [`src`](/en-US/docs/Web/HTML/Element/audio#src) attribute. The error +or a missing file to the element's [`src`](/en-US/docs/Web/HTML/Reference/Elements/audio#src) attribute. The error handler outputs a message to a box onscreen describing the error, including both the `code` and the `message`. diff --git a/files/en-us/web/api/mediakeysession/generaterequest/index.md b/files/en-us/web/api/mediakeysession/generaterequest/index.md index bdb054893ad8289..07ba759eaad7faf 100644 --- a/files/en-us/web/api/mediakeysession/generaterequest/index.md +++ b/files/en-us/web/api/mediakeysession/generaterequest/index.md @@ -8,22 +8,44 @@ browser-compat: api.MediaKeySession.generateRequest {{APIRef("Encrypted Media Extensions")}}{{SecureContext_Header}} -The `generateRequest()` method of the {{domxref('MediaKeySession')}} interface returns a {{jsxref('Promise')}} after generating a media request based on initialization data. +The `generateRequest()` method of the {{domxref('MediaKeySession')}} interface returns a {{jsxref('Promise')}} after generating a license request based on initialization data. ## Syntax ```js-nolint -generateRequest() +generateRequest(initDataType, initData) ``` ### Parameters -None. +- `initDataType` + - : A string that specifies the format of the `initData` parameter. This must be one of the following values: + - `"cenc"`: The `initData` parameter uses the [`"cenc"`](https://www.w3.org/TR/eme-initdata-cenc/) format. + - `"keyids"`: The `initData` parameter uses the [`"keyids"`](https://www.w3.org/TR/eme-initdata-keyids/) format. + - `"webm"`: The `initData` parameter uses the [`"webm"`](https://www.w3.org/TR/eme-initdata-webm/) format. +- `initData` + + - : Initialization data for the request, in the format specified by `initDataType`. It is an instance of any of the following types: + + - {{jsxref("ArrayBuffer")}} + - {{jsxref("DataView")}} + - {{jsxref("TypedArray")}} ### Return value A {{jsxref('Promise')}}. +### Exceptions + +- {{jsxref("TypeError")}} + - : Raised if `initDataType` is an empty string, if `initData` is an empty array, or if the provided `initData` is not valid according to the specified `initDataType`. +- {{domxref("DOMException")}} `NotSupportedError` + - : Raised if the Key System implementation associated with the `MediaKeySession` object does not support the provided `initDataType`, if the sanitized initialization data is empty, or if the sanitized initialization data is not supported by the content decryption module (CDM). +- {{domxref("DOMException")}} `QuotaExceededError` + - : Raised if the operation fails due to a lack of resources on the user agent or CDM. +- {{domxref("DOMException")}} `InvalidStateError` + - : Raised if the `MediaKeySession` object is in a `closing` or `closed` state, or if it has already been initialized. + ## Specifications {{Specifications}} diff --git a/files/en-us/web/api/mediakeysession/index.md b/files/en-us/web/api/mediakeysession/index.md index 043acd49554442d..38ddf1537c9e35a 100644 --- a/files/en-us/web/api/mediakeysession/index.md +++ b/files/en-us/web/api/mediakeysession/index.md @@ -34,7 +34,7 @@ The **`MediaKeySession`** interface of the [Encrypted Media Extensions API](/en- - {{domxref("MediaKeySession.close()")}} - : Returns a {{jsxref("Promise")}} after notifying the current media session is no longer needed and that the CDM should release any resources associated with this object and close it. - {{domxref("MediaKeySession.generateRequest()")}} - - : Returns a {{jsxref("Promise")}} after generating a media request based on initialization data. + - : Returns a {{jsxref("Promise")}} after generating a license request based on initialization data. - {{domxref("MediaKeySession.load()")}} - : Returns a {{jsxref("Promise")}} that resolves to a boolean value after loading data for a specified session object. - {{domxref("MediaKeySession.remove()")}} diff --git a/files/en-us/web/api/mediakeysession/keystatuseschange_event/index.md b/files/en-us/web/api/mediakeysession/keystatuseschange_event/index.md index aedde65b24f1171..e94b556279cdf7c 100644 --- a/files/en-us/web/api/mediakeysession/keystatuseschange_event/index.md +++ b/files/en-us/web/api/mediakeysession/keystatuseschange_event/index.md @@ -14,10 +14,10 @@ The **`keystatuseschange`** event of the {{domxref("MediaKeySession")}} API fire Use the event name in methods like {{domxref("EventTarget.addEventListener", "addEventListener()")}}, or set an event handler property. -```js -addEventListener("keystatuseschange", (event) => {}); +```js-nolint +addEventListener("keystatuseschange", (event) => { }) -onkeystatuseschange = (event) => {}; +onkeystatuseschange = (event) => { } ``` ## Event type diff --git a/files/en-us/web/api/mediakeysession/message_event/index.md b/files/en-us/web/api/mediakeysession/message_event/index.md index d6ee7edb7e6b705..8b2b411298350b7 100644 --- a/files/en-us/web/api/mediakeysession/message_event/index.md +++ b/files/en-us/web/api/mediakeysession/message_event/index.md @@ -16,10 +16,10 @@ content decryption module. Use the event name in methods like {{domxref("EventTarget.addEventListener", "addEventListener()")}}, or set an event handler property. -```js -addEventListener("message", (event) => {}); +```js-nolint +addEventListener("message", (event) => { }) -onmessage = (event) => {}; +onmessage = (event) => { } ``` ## Event type diff --git a/files/en-us/web/api/mediakeystatusmap/entries/index.md b/files/en-us/web/api/mediakeystatusmap/entries/index.md index d98ccfbd851a706..adf0339f65758f5 100644 --- a/files/en-us/web/api/mediakeystatusmap/entries/index.md +++ b/files/en-us/web/api/mediakeystatusmap/entries/index.md @@ -25,6 +25,8 @@ None. ### Return value +A new Iterator object. Each element in the Iterator is an array containing a key and a value. + ### Exceptions ## Specifications diff --git a/files/en-us/web/api/medialist/index.md b/files/en-us/web/api/medialist/index.md index d1b1ab86862f2ee..6fe20ae70c68bd0 100644 --- a/files/en-us/web/api/medialist/index.md +++ b/files/en-us/web/api/medialist/index.md @@ -7,7 +7,7 @@ browser-compat: api.MediaList {{APIRef("CSSOM")}} -The **`MediaList`** interface represents the media queries of a stylesheet, e.g. those set using a {{htmlelement("link")}} element's `media` attribute. +The **`MediaList`** interface represents the media queries of a stylesheet, e.g., those set using a {{htmlelement("link")}} element's `media` attribute. > **Note:** `MediaList` is a live list; updating the list using properties or methods listed below will immediately update the behavior of the document. diff --git a/files/en-us/web/api/medialist/mediatext/index.md b/files/en-us/web/api/medialist/mediatext/index.md index bc83cd72fc2b5d8..9dc5bb73e9d81b2 100644 --- a/files/en-us/web/api/medialist/mediatext/index.md +++ b/files/en-us/web/api/medialist/mediatext/index.md @@ -19,7 +19,7 @@ separated by a comma, for example `screen and (min-width: 480px), print`. If you wish to set new media queries on the document, the string value must have the -different queries separated by commas, e.g. `screen, print`. Note that the +different queries separated by commas, e.g., `screen, print`. Note that the `MediaList` is a live list; updating the list via `mediaText` will immediately update the behavior of the document. diff --git a/files/en-us/web/api/mediaquerylist/change_event/index.md b/files/en-us/web/api/mediaquerylist/change_event/index.md index bc257184ecf7ebe..6f20d8b15fc884c 100644 --- a/files/en-us/web/api/mediaquerylist/change_event/index.md +++ b/files/en-us/web/api/mediaquerylist/change_event/index.md @@ -14,10 +14,10 @@ The **`change`** event of the {{DOMxRef("MediaQueryList")}} interface fires when Use the event name in methods like {{domxref("EventTarget.addEventListener", "addEventListener()")}}, or set an event handler property. -```js -addEventListener("change", (event) => {}); +```js-nolint +addEventListener("change", (event) => { }) -onchange = (event) => {}; +onchange = (event) => { } ``` ## Event type diff --git a/files/en-us/web/api/mediaquerylist/index.md b/files/en-us/web/api/mediaquerylist/index.md index c83358f10455ffc..f8db07ab96f6641 100644 --- a/files/en-us/web/api/mediaquerylist/index.md +++ b/files/en-us/web/api/mediaquerylist/index.md @@ -9,7 +9,7 @@ browser-compat: api.MediaQueryList A **`MediaQueryList`** object stores information on a [media query](/en-US/docs/Web/CSS/CSS_media_queries) applied to a document, with support for both immediate and event-driven matching against the state of the document. -You can create a `MediaQueryList` by calling {{DOMxRef("Window.matchMedia", "matchMedia()")}} on the {{DOMxRef("window")}} object. The resulting object handles sending notifications to listeners when the media query state changes (i.e. when the media query test starts or stops evaluating to `true`). +You can create a `MediaQueryList` by calling {{DOMxRef("Window.matchMedia", "matchMedia()")}} on the {{DOMxRef("window")}} object. The resulting object handles sending notifications to listeners when the media query state changes (i.e., when the media query test starts or stops evaluating to `true`). This is very useful for adaptive design, since this makes it possible to observe a document to detect when its media queries change, instead of polling the values periodically, and allows you to programmatically make changes to a document based on media query status. diff --git a/files/en-us/web/api/mediarecorder/dataavailable_event/index.md b/files/en-us/web/api/mediarecorder/dataavailable_event/index.md index 18f85bb4177db24..8c874a925f060f3 100644 --- a/files/en-us/web/api/mediarecorder/dataavailable_event/index.md +++ b/files/en-us/web/api/mediarecorder/dataavailable_event/index.md @@ -44,10 +44,10 @@ The {{domxref("Blob")}} containing the media data is available in the `dataavail Use the event name in methods like {{domxref("EventTarget.addEventListener", "addEventListener()")}}, or set an event handler property. -```js -addEventListener("dataavailable", (event) => {}); +```js-nolint +addEventListener("dataavailable", (event) => { }) -ondataavailable = (event) => {}; +ondataavailable = (event) => { } ``` ## Event type diff --git a/files/en-us/web/api/mediarecorder/error_event/index.md b/files/en-us/web/api/mediarecorder/error_event/index.md index 6300955aa9fb29e..2e2f5ec87fe0573 100644 --- a/files/en-us/web/api/mediarecorder/error_event/index.md +++ b/files/en-us/web/api/mediarecorder/error_event/index.md @@ -16,10 +16,10 @@ This event is not cancelable and does not bubble. Use the event name in methods like {{domxref("EventTarget.addEventListener", "addEventListener()")}}, or set an event handler property. -```js -addEventListener("event", (event) => {}); +```js-nolint +addEventListener("error", (event) => { }) -onevent = (event) => {}; +onerror = (event) => { } ``` ## Event type diff --git a/files/en-us/web/api/mediarecorder/istypesupported_static/index.md b/files/en-us/web/api/mediarecorder/istypesupported_static/index.md index 3892cc47d6ec219..8b4492e3bcae873 100644 --- a/files/en-us/web/api/mediarecorder/istypesupported_static/index.md +++ b/files/en-us/web/api/mediarecorder/istypesupported_static/index.md @@ -38,12 +38,22 @@ const types = [ "video/webm;codecs=h264", "audio/webm;codecs=opus", "video/mp4", + "video/mp4;codecs=avc1.64003E,mp4a.40.2", + "video/mp4;codecs=avc1.64003E,opus", + "video/mp4;codecs=avc3.64003E,mp4a.40.2", + "video/mp4;codecs=avc3.64003E,opus", + "video/mp4;codecs=hvc1.1.6.L186.B0,mp4a.40.2", + "video/mp4;codecs=hvc1.1.6.L186.B0,opus", + "video/mp4;codecs=hev1.1.6.L186.B0,mp4a.40.2", + "video/mp4;codecs=hev1.1.6.L186.B0,opus", + "video/mp4;codecs=av01.0.19M.08,mp4a.40.2", + "video/mp4;codecs=av01.0.19M.08,opus", ]; for (const type of types) { console.log( `Is ${type} supported? ${ - MediaRecorder.isTypeSupported(type) ? "Maybe!" : "Nope :(" + MediaRecorder.isTypeSupported(type) ? "Yes!" : "Nope :(" }`, ); } diff --git a/files/en-us/web/api/mediarecorder/mimetype/index.md b/files/en-us/web/api/mediarecorder/mimetype/index.md index 2951573edc47abb..d51183d9b231092 100644 --- a/files/en-us/web/api/mediarecorder/mimetype/index.md +++ b/files/en-us/web/api/mediarecorder/mimetype/index.md @@ -25,7 +25,7 @@ This string _may_ include the [`codecs` parameter,](/en-US/docs/Web/Media/Guides The media type strings are standardized by the Internet Assigned Numbers Authority (IANA). For their official list of defined media type strings, see the article [Media Types](https://www.iana.org/assignments/media-types/media-types.xhtml) on the IANA site. -See also [media types](/en-US/docs/Web/HTTP/MIME_types) to learn more about media types and how they're used in web content and by web browsers. +See also [media types](/en-US/docs/Web/HTTP/Guides/MIME_types) to learn more about media types and how they're used in web content and by web browsers. ## Examples diff --git a/files/en-us/web/api/mediarecorder/pause_event/index.md b/files/en-us/web/api/mediarecorder/pause_event/index.md index 86f1ca752ec03eb..cf255fc30c823ce 100644 --- a/files/en-us/web/api/mediarecorder/pause_event/index.md +++ b/files/en-us/web/api/mediarecorder/pause_event/index.md @@ -15,10 +15,10 @@ The **`pause`** event of the {{domxref("MediaRecorder")}} interface is fired whe Use the event name in methods like {{domxref("EventTarget.addEventListener", "addEventListener()")}}, or set an event handler property. -```js -addEventListener("pause", (event) => {}); +```js-nolint +addEventListener("pause", (event) => { }) -onpause = (event) => {}; +onpause = (event) => { } ``` ## Event type diff --git a/files/en-us/web/api/mediarecorder/resume_event/index.md b/files/en-us/web/api/mediarecorder/resume_event/index.md index 00e996a25b7fbe1..3565b9dea8df764 100644 --- a/files/en-us/web/api/mediarecorder/resume_event/index.md +++ b/files/en-us/web/api/mediarecorder/resume_event/index.md @@ -15,10 +15,10 @@ The **`resume`** event of the {{domxref("MediaRecorder")}} interface is fired wh Use the event name in methods like {{domxref("EventTarget.addEventListener", "addEventListener()")}}, or set an event handler property. -```js -addEventListener("resume", (event) => {}); +```js-nolint +addEventListener("resume", (event) => { }) -onresume = (event) => {}; +onresume = (event) => { } ``` ## Event type diff --git a/files/en-us/web/api/mediarecorder/start_event/index.md b/files/en-us/web/api/mediarecorder/start_event/index.md index cd9eaf3138ecbdf..18a0257ac3458ac 100644 --- a/files/en-us/web/api/mediarecorder/start_event/index.md +++ b/files/en-us/web/api/mediarecorder/start_event/index.md @@ -16,10 +16,10 @@ starts being gathered into a {{domxref("Blob")}}. Use the event name in methods like {{domxref("EventTarget.addEventListener", "addEventListener()")}}, or set an event handler property. -```js -addEventListener("start", (event) => {}); +```js-nolint +addEventListener("start", (event) => { }) -onstart = (event) => {}; +onstart = (event) => { } ``` ## Event type diff --git a/files/en-us/web/api/mediarecorder/stop_event/index.md b/files/en-us/web/api/mediarecorder/stop_event/index.md index dea81326e244409..e3c9fe1c5af6a1a 100644 --- a/files/en-us/web/api/mediarecorder/stop_event/index.md +++ b/files/en-us/web/api/mediarecorder/stop_event/index.md @@ -18,10 +18,10 @@ point available for you to use in your application. Use the event name in methods like {{domxref("EventTarget.addEventListener", "addEventListener()")}}, or set an event handler property. -```js -addEventListener("stop", (event) => {}); +```js-nolint +addEventListener("stop", (event) => { }) -onstop = (event) => {}; +onstop = (event) => { } ``` ## Event type diff --git a/files/en-us/web/api/mediasource/duration/index.md b/files/en-us/web/api/mediasource/duration/index.md index c0f5b16fd6d7e53..2f8f39e31ddfa79 100644 --- a/files/en-us/web/api/mediasource/duration/index.md +++ b/files/en-us/web/api/mediasource/duration/index.md @@ -26,7 +26,7 @@ The following exceptions may be thrown when setting a new value for this propert `open`, or one or more of the {{domxref("SourceBuffer")}} objects in {{domxref("MediaSource.sourceBuffers")}} are being updated - (i.e. their {{domxref("SourceBuffer.updating")}} property is + (i.e., their {{domxref("SourceBuffer.updating")}} property is `true`.) ## Examples diff --git a/files/en-us/web/api/mediasource/endofstream/index.md b/files/en-us/web/api/mediasource/endofstream/index.md index ef53802080353f6..0482b7cad32890d 100644 --- a/files/en-us/web/api/mediasource/endofstream/index.md +++ b/files/en-us/web/api/mediasource/endofstream/index.md @@ -47,7 +47,7 @@ None ({{jsxref("undefined")}}). ### Exceptions - `InvalidStateError` {{domxref("DOMException")}} - - : Thrown if {{domxref("MediaSource.readyState")}} is not equal to `open`, or one or more of the {{domxref("SourceBuffer")}} objects in {{domxref("MediaSource.sourceBuffers")}} are being updated (i.e. their {{domxref("SourceBuffer.updating")}} property is + - : Thrown if {{domxref("MediaSource.readyState")}} is not equal to `open`, or one or more of the {{domxref("SourceBuffer")}} objects in {{domxref("MediaSource.sourceBuffers")}} are being updated (i.e., their {{domxref("SourceBuffer.updating")}} property is `true`.) ## Examples diff --git a/files/en-us/web/api/mediasource/mediasource/index.md b/files/en-us/web/api/mediasource/mediasource/index.md index 01afdf9f7386d2f..e212533a74f5d8b 100644 --- a/files/en-us/web/api/mediasource/mediasource/index.md +++ b/files/en-us/web/api/mediasource/mediasource/index.md @@ -36,7 +36,7 @@ const mimeCodec = 'video/mp4; codecs="avc1.42E01E, mp4a.40.2"'; if ("MediaSource" in window && MediaSource.isTypeSupported(mimeCodec)) { const mediaSource = new MediaSource(); - //console.log(mediaSource.readyState); // closed + // console.log(mediaSource.readyState); // closed video.src = URL.createObjectURL(mediaSource); mediaSource.addEventListener("sourceopen", sourceOpen); } else { diff --git a/files/en-us/web/api/mediastream/addtrack/index.md b/files/en-us/web/api/mediastream/addtrack/index.md index 0c99cf86fc42d6a..efb34b88e8ab916 100644 --- a/files/en-us/web/api/mediastream/addtrack/index.md +++ b/files/en-us/web/api/mediastream/addtrack/index.md @@ -30,8 +30,6 @@ addTrack(track) None ({{jsxref("undefined")}}). -## Examples - ## Specifications {{Specifications}} diff --git a/files/en-us/web/api/mediastream/addtrack_event/index.md b/files/en-us/web/api/mediastream/addtrack_event/index.md index 570ea34599f2040..827f0fc05be672b 100644 --- a/files/en-us/web/api/mediastream/addtrack_event/index.md +++ b/files/en-us/web/api/mediastream/addtrack_event/index.md @@ -16,10 +16,10 @@ This event is not cancelable and does not bubble. Use the event name in methods like {{domxref("EventTarget.addEventListener", "addEventListener()")}}, or set an event handler property. -```js -addEventListener("addtrack", (event) => {}); +```js-nolint +addEventListener("addtrack", (event) => { }) -onaddtrack = (event) => {}; +onaddtrack = (event) => { } ``` ## Event type diff --git a/files/en-us/web/api/mediastream/getaudiotracks/index.md b/files/en-us/web/api/mediastream/getaudiotracks/index.md index e0aca631966ef45..4fecd46ce830570 100644 --- a/files/en-us/web/api/mediastream/getaudiotracks/index.md +++ b/files/en-us/web/api/mediastream/getaudiotracks/index.md @@ -11,7 +11,7 @@ browser-compat: api.MediaStream.getAudioTracks The **`getAudioTracks()`** method of the {{domxref("MediaStream")}} interface returns a sequence that represents all the {{domxref("MediaStreamTrack")}} objects in this -stream's [track set](https://www.w3.org/TR/mediacapture-streams/#dfn-track-set) where {{domxref("MediaStreamTrack.kind")}} +stream's [track set](https://w3c.github.io/mediacapture-main/#dfn-track-set) where {{domxref("MediaStreamTrack.kind")}} is `audio`. ## Syntax diff --git a/files/en-us/web/api/mediastream/gettracks/index.md b/files/en-us/web/api/mediastream/gettracks/index.md index 8d0807342aaac6e..25d5a2984e38ae9 100644 --- a/files/en-us/web/api/mediastream/gettracks/index.md +++ b/files/en-us/web/api/mediastream/gettracks/index.md @@ -11,7 +11,7 @@ browser-compat: api.MediaStream.getTracks The **`getTracks()`** method of the {{domxref("MediaStream")}} interface returns a sequence that represents all the {{domxref("MediaStreamTrack")}} objects in this -stream's [track set](https://www.w3.org/TR/mediacapture-streams/#dfn-track-set), +stream's [track set](https://w3c.github.io/mediacapture-main/#dfn-track-set), regardless of {{domxref("MediaStreamTrack.kind")}}. ## Syntax diff --git a/files/en-us/web/api/mediastream/removetrack_event/index.md b/files/en-us/web/api/mediastream/removetrack_event/index.md index c2b2f51ff5783d9..b787d5ac85eb186 100644 --- a/files/en-us/web/api/mediastream/removetrack_event/index.md +++ b/files/en-us/web/api/mediastream/removetrack_event/index.md @@ -16,10 +16,10 @@ This event is not cancelable and does not bubble. Use the event name in methods like {{domxref("EventTarget.addEventListener", "addEventListener()")}}, or set an event handler property. -```js -addEventListener("removetrack", (event) => {}); +```js-nolint +addEventListener("removetrack", (event) => { }) -onremovetrack = (event) => {}; +onremovetrack = (event) => { } ``` ## Event type diff --git a/files/en-us/web/api/mediastream_recording_api/index.md b/files/en-us/web/api/mediastream_recording_api/index.md index 5e31c524636377a..21a10541114dbdb 100644 --- a/files/en-us/web/api/mediastream_recording_api/index.md +++ b/files/en-us/web/api/mediastream_recording_api/index.md @@ -68,7 +68,7 @@ function download() { a.href = url; a.download = "test.webm"; a.click(); - window.URL.revokeObjectURL(url); + URL.revokeObjectURL(url); } // demo: to download after 9sec diff --git a/files/en-us/web/api/mediastream_recording_api/recording_a_media_element/index.md b/files/en-us/web/api/mediastream_recording_api/recording_a_media_element/index.md index f9f47f8246e13de..fdf9865c3ca40b3 100644 --- a/files/en-us/web/api/mediastream_recording_api/recording_a_media_element/index.md +++ b/files/en-us/web/api/mediastream_recording_api/recording_a_media_element/index.md @@ -32,7 +32,7 @@ Let's start by looking at the key bits of the HTML. There's a little more than t </div> ``` -We present our main interface in two columns. On the left is a start button and a {{HTMLElement("video")}} element which displays the video preview; this is the video the user's camera sees. Note that the [`autoplay`](/en-US/docs/Web/HTML/Element/video#autoplay) attribute is used so that as soon as the stream starts to arrive from the camera, it immediately gets displayed, and the [`muted`](/en-US/docs/Web/HTML/Element/video#muted) attribute is specified to ensure that the sound from the user's microphone isn't output to their speakers, causing an ugly feedback loop. +We present our main interface in two columns. On the left is a start button and a {{HTMLElement("video")}} element which displays the video preview; this is the video the user's camera sees. Note that the [`autoplay`](/en-US/docs/Web/HTML/Reference/Elements/video#autoplay) attribute is used so that as soon as the stream starts to arrive from the camera, it immediately gets displayed, and the [`muted`](/en-US/docs/Web/HTML/Reference/Elements/video#muted) attribute is specified to ensure that the sound from the user's microphone isn't output to their speakers, causing an ugly feedback loop. ```html <div class="right"> @@ -43,7 +43,7 @@ We present our main interface in two columns. On the left is a start button and </div> ``` -On the right we see a stop button and the `<video>` element which will be used to play back the recorded video. Notice that the playback panel doesn't have autoplay set (so the playback doesn't start as soon as media arrives), and it has [`controls`](/en-US/docs/Web/HTML/Element/video#controls) set, which tells it to show the user controls to play, pause, and so forth. +On the right we see a stop button and the `<video>` element which will be used to play back the recorded video. Notice that the playback panel doesn't have autoplay set (so the playback doesn't start as soon as media arrives), and it has [`controls`](/en-US/docs/Web/HTML/Reference/Elements/video#controls) set, which tells it to show the user controls to play, pause, and so forth. Below the playback element is a button for downloading the recorded video. @@ -211,7 +211,9 @@ startButton.addEventListener( downloadButton.href = stream; preview.captureStream = preview.captureStream || preview.mozCaptureStream; - return new Promise((resolve) => (preview.onplaying = resolve)); + return new Promise((resolve) => { + preview.onplaying = resolve; + }); }) .then(() => startRecording(preview.captureStream(), recordingTimeMS)) .then((recordedChunks) => { @@ -241,9 +243,9 @@ When a {{domxref("Element/click_event", "click")}} event occurs, here's what hap - {{domxref("MediaDevices.getUserMedia")}} is called to request a new {{domxref("MediaStream")}} that has both video and audio tracks. This is the stream we'll record. - When the Promise returned by `getUserMedia()` is resolved, the preview {{HTMLElement("video")}} element's {{domxref("HTMLMediaElement.srcObject","srcObject")}} property is set to be the input stream, which causes the video being captured by the user's camera to be displayed in the preview box. Since the `<video>` element is muted, the audio won't play. The "Download" button's link is then set to refer to the stream as well. Then, we arrange for `preview.captureStream()` to call `preview.mozCaptureStream()` so that our code will work on Firefox, on which the {{domxref("HTMLMediaElement.captureStream()")}} method is prefixed. Then a new {{jsxref("Promise")}} which resolves when the preview video starts to play is created and returned. - When the preview video begins to play, we know there's media to record, so we respond by calling the [`startRecording()`](#starting_media_recording) function we created earlier, passing in the preview video stream (as the source media to be recorded) and `recordingTimeMS` as the number of milliseconds of media to record. As mentioned before, `startRecording()` returns a {{jsxref("Promise")}} whose resolution handler is called (receiving as input an array of {{domxref("Blob")}} objects containing the chunks of recorded media data) once recording has completed. -- The recording process's resolution handler receives as input an array of media data `Blob`s locally known as `recordedChunks`. The first thing we do is merge the chunks into a single {{domxref("Blob")}} whose MIME type is `"video/webm"` by taking advantage of the fact that the {{domxref("Blob.Blob", "Blob()")}} constructor concatenates arrays of objects into one object. Then {{domxref("URL.createObjectURL_static", "URL.createObjectURL()")}} is used to create a URL that references the blob; this is then made the value of the recorded video playback element's [`src`](/en-US/docs/Web/HTML/Element/video#src) attribute (so that you can play the video from the blob) as well as the target of the download button's link. +- The recording process's resolution handler receives as input an array of media data `Blob`s locally known as `recordedChunks`. The first thing we do is merge the chunks into a single {{domxref("Blob")}} whose MIME type is `"video/webm"` by taking advantage of the fact that the {{domxref("Blob.Blob", "Blob()")}} constructor concatenates arrays of objects into one object. Then {{domxref("URL.createObjectURL_static", "URL.createObjectURL()")}} is used to create a URL that references the blob; this is then made the value of the recorded video playback element's [`src`](/en-US/docs/Web/HTML/Reference/Elements/video#src) attribute (so that you can play the video from the blob) as well as the target of the download button's link. - Then the download button's [`download`](/en-US/docs/Web/HTML/Element/a#download) attribute is set. While the `download` attribute can be a Boolean, you can also set it to a string to use as the name for the downloaded file. So by setting the download link's `download` attribute to "RecordedVideo.webm", we tell the browser that clicking the button should download a file named `"RecordedVideo.webm"` whose contents are the recorded video. + Then the download button's [`download`](/en-US/docs/Web/HTML/Reference/Elements/a#download) attribute is set. While the `download` attribute can be a Boolean, you can also set it to a string to use as the name for the downloaded file. So by setting the download link's `download` attribute to "RecordedVideo.webm", we tell the browser that clicking the button should download a file named `"RecordedVideo.webm"` whose contents are the recorded video. - The size and type of the recorded media are output to the log area below the two videos and the download button. - The `catch()` for all the `Promise`s outputs the error to the logging area by calling our `log()` function. diff --git a/files/en-us/web/api/mediastream_recording_api/using_the_mediastream_recording_api/index.md b/files/en-us/web/api/mediastream_recording_api/using_the_mediastream_recording_api/index.md index 4933694bffaace1..440cbf8654d5f73 100644 --- a/files/en-us/web/api/mediastream_recording_api/using_the_mediastream_recording_api/index.md +++ b/files/en-us/web/api/mediastream_recording_api/using_the_mediastream_recording_api/index.md @@ -198,7 +198,7 @@ stop.onclick = () => { }; ``` -Note that the recording may also stop naturally if the media stream ends (e.g. if you were grabbing a song track and the track ended, or the user stopped sharing their microphone). +Note that the recording may also stop naturally if the media stream ends (e.g., if you were grabbing a song track and the track ended, or the user stopped sharing their microphone). ## Grabbing and using the blob @@ -251,7 +251,7 @@ Next, we create an HTML structure like the following, inserting it into our clip </article> ``` -After that, we create a combined {{domxref("Blob")}} out of the recorded audio chunks, and create an object URL pointing to it, using `window.URL.createObjectURL(blob)`. We then set the value of the {{HTMLElement("audio")}} element's [`src`](/en-US/docs/Web/HTML/Element/audio#src) attribute to the object URL, so that when the play button is pressed on the audio player, it will play the `Blob`. +After that, we create a combined {{domxref("Blob")}} out of the recorded audio chunks, and create an object URL pointing to it, using `window.URL.createObjectURL(blob)`. We then set the value of the {{HTMLElement("audio")}} element's [`src`](/en-US/docs/Web/HTML/Reference/Elements/audio#src) attribute to the object URL, so that when the play button is pressed on the audio player, it will play the `Blob`. Finally, we set an `onclick` handler on the delete button to be a function that deletes the whole clip HTML structure. diff --git a/files/en-us/web/api/mediastreamtrack/ended_event/index.md b/files/en-us/web/api/mediastreamtrack/ended_event/index.md index 38686b3e650a243..ea7066a010185d6 100644 --- a/files/en-us/web/api/mediastreamtrack/ended_event/index.md +++ b/files/en-us/web/api/mediastreamtrack/ended_event/index.md @@ -16,10 +16,10 @@ This event is not cancelable and does not bubble. Use the event name in methods like {{domxref("EventTarget.addEventListener", "addEventListener()")}}, or set an event handler property. -```js -addEventListener("ended", (event) => {}); +```js-nolint +addEventListener("ended", (event) => { }) -onended = (event) => {}; +onended = (event) => { } ``` ## Event type diff --git a/files/en-us/web/api/mediastreamtrack/getcapabilities/index.md b/files/en-us/web/api/mediastreamtrack/getcapabilities/index.md index 2a37b0dc0c3add1..8aa83e91d608669 100644 --- a/files/en-us/web/api/mediastreamtrack/getcapabilities/index.md +++ b/files/en-us/web/api/mediastreamtrack/getcapabilities/index.md @@ -78,26 +78,17 @@ navigator.mediaDevices An example capabilities object looks like this: -```js +```json { - "autoGainControl": [ - true, - false - ], + "autoGainControl": [true, false], "channelCount": { "max": 1, "min": 1 }, "deviceId": "jjxEMqxIhGdryqbTjDrXPWrkjy55Vte70kWpMe3Lge8=", - "echoCancellation": [ - true, - false - ], + "echoCancellation": [true, false], "groupId": "o2tZiEj4MwOdG/LW3HwkjpLm1D8URat4C5kt742xrVQ=", - "noiseSuppression": [ - true, - false - ] + "noiseSuppression": [true, false] } ``` diff --git a/files/en-us/web/api/mediastreamtrack/mute_event/index.md b/files/en-us/web/api/mediastreamtrack/mute_event/index.md index 8064a7c5cf1a5c2..219d92dbb15d707 100644 --- a/files/en-us/web/api/mediastreamtrack/mute_event/index.md +++ b/files/en-us/web/api/mediastreamtrack/mute_event/index.md @@ -23,10 +23,10 @@ This event is not cancelable and does not bubble. Use the event name in methods like {{domxref("EventTarget.addEventListener", "addEventListener()")}}, or set an event handler property. -```js -addEventListener("mute", (event) => {}); +```js-nolint +addEventListener("mute", (event) => { }) -onmute = (event) => {}; +onmute = (event) => { } ``` ## Event type diff --git a/files/en-us/web/api/mediastreamtrack/unmute_event/index.md b/files/en-us/web/api/mediastreamtrack/unmute_event/index.md index 2faff3f02a7b5ce..940fab014d6f125 100644 --- a/files/en-us/web/api/mediastreamtrack/unmute_event/index.md +++ b/files/en-us/web/api/mediastreamtrack/unmute_event/index.md @@ -21,10 +21,10 @@ This event is not cancelable and does not bubble. Use the event name in methods like {{domxref("EventTarget.addEventListener", "addEventListener()")}}, or set an event handler property. -```js -addEventListener("unmute", (event) => {}); +```js-nolint +addEventListener("unmute", (event) => { }) -onunmute = (event) => {}; +onunmute = (event) => { } ``` ## Event type diff --git a/files/en-us/web/api/mediastreamtrackgenerator/index.md b/files/en-us/web/api/mediastreamtrackgenerator/index.md index d5df2e222de794d..64cd06faa0999f7 100644 --- a/files/en-us/web/api/mediastreamtrackgenerator/index.md +++ b/files/en-us/web/api/mediastreamtrackgenerator/index.md @@ -10,6 +10,9 @@ browser-compat: api.MediaStreamTrackGenerator {{APIRef("Insertable Streams for MediaStreamTrack API")}}{{SeeCompatTable}}{{Non-standard_Header}} +> [!NOTE] +> Consider using {{domxref("VideoTrackGenerator")}} instead. + The **`MediaStreamTrackGenerator`** interface of the [Insertable Streams for MediaStreamTrack API](/en-US/docs/Web/API/Insertable_Streams_for_MediaStreamTrack_API) creates a {{domxref("WritableStream")}} that acts as a {{domxref("MediaStreamTrack")}} source. The object consumes a stream of media frames as input, which can be audio or video frames. @@ -54,6 +57,10 @@ trackProcessor.readable .pipeTo(trackGenerator.writable); ``` +## See also + +- {{domxref("VideoTrackGenerator")}} + ## Specifications {{Specifications}} diff --git a/files/en-us/web/api/mediastreamtrackgenerator/mediastreamtrackgenerator/index.md b/files/en-us/web/api/mediastreamtrackgenerator/mediastreamtrackgenerator/index.md index c7ac3a189eb33d9..d7f088037e9fe14 100644 --- a/files/en-us/web/api/mediastreamtrackgenerator/mediastreamtrackgenerator/index.md +++ b/files/en-us/web/api/mediastreamtrackgenerator/mediastreamtrackgenerator/index.md @@ -21,7 +21,7 @@ new MediaStreamTrackGenerator(options) ### Parameters -- `options` +- `options` {{Experimental_Inline}} {{Non-standard_Inline}} - : An object containing the property `kind`, which is one of the following strings: - `"audio"` - : Specifies that the stream accepts {{domxref("AudioTrack")}} objects. diff --git a/files/en-us/web/api/mediastreamtrackprocessor/index.md b/files/en-us/web/api/mediastreamtrackprocessor/index.md index b9dc603296d90d2..6738be38177ac5a 100644 --- a/files/en-us/web/api/mediastreamtrackprocessor/index.md +++ b/files/en-us/web/api/mediastreamtrackprocessor/index.md @@ -5,14 +5,19 @@ page-type: web-api-interface browser-compat: api.MediaStreamTrackProcessor --- -{{APIRef("Insertable Streams for MediaStreamTrack API")}} +{{APIRef("Insertable Streams for MediaStreamTrack API")}}{{AvailableInWorkers("dedicated")}} -The **`MediaStreamTrackProcessor`** interface of the [Insertable Streams for MediaStreamTrack API](/en-US/docs/Web/API/Insertable_Streams_for_MediaStreamTrack_API) consumes a {{domxref("MediaStreamTrack")}} object's source and generates a stream of media frames. +> [!WARNING] +> Browsers differ on which global context they expose this interface in (e.g., only window in some browsers and only dedicated worker in others), making them incompatible. Keep this in mind when comparing support. + +The **`MediaStreamTrackProcessor`** interface of the [Insertable Streams for MediaStreamTrack API](/en-US/docs/Web/API/Insertable_Streams_for_MediaStreamTrack_API) consumes a video {{domxref("MediaStreamTrack")}} object's source and generates a stream of {{domxref("VideoFrame")}} objects. ## Constructor - {{domxref("MediaStreamTrackProcessor.MediaStreamTrackProcessor", "MediaStreamTrackProcessor()")}} - : Creates a new `MediaStreamTrackProcessor` object. +- {{domxref("MediaStreamTrackProcessor.MediaStreamTrackProcessor", "window.MediaStreamTrackProcessor()")}} {{Experimental_Inline}} {{Non-standard_Inline}} + - : Creates a new `MediaStreamTrackProcessor` object on the {{Glossary("main thread")}} that can process both video and audio. ## Instance properties @@ -21,27 +26,30 @@ The **`MediaStreamTrackProcessor`** interface of the [Insertable Streams for Med ## Examples -The following example is from the article [Insertable streams for MediaStreamTrack](https://developer.chrome.com/docs/capabilities/web-apis/mediastreamtrack-insertable-media-processing), and demonstrates a barcode scanner application, which transforms the stream accessed via {{domxref("MediaStreamTrackProcessor.readable")}} by highlighting the barcode. +The following example is from the article [Unbundling MediaStreamTrackProcessor and VideoTrackGenerator](https://blog.mozilla.org/webrtc/unbundling-mediastreamtrackprocessor-and-videotrackgenerator/). It [transfers](/en-US/docs/Web/API/Web_Workers_API/Transferable_objects) a camera {{domxref("MediaStreamTrack")}} to a worker for processing. The worker creates a pipeline that applies a sepia tone filter to the video frames and mirrors them. The pipeline culminates in a {{domxref("VideoTrackGenerator")}} whose {{domxref("MediaStreamTrack")}} is transferred back and played. The media now flows in real time through the transform off the {{Glossary("main thread")}}. ```js -const stream = await getUserMedia({ video: true }); -const videoTrack = stream.getVideoTracks()[0]; - -const trackProcessor = new MediaStreamTrackProcessor({ track: videoTrack }); -const trackGenerator = new MediaStreamTrackGenerator({ kind: "video" }); - -const transformer = new TransformStream({ - async transform(videoFrame, controller) { - const barcodes = await detectBarcodes(videoFrame); - const newFrame = highlightBarcodes(videoFrame, barcodes); - videoFrame.close(); - controller.enqueue(newFrame); - }, +const stream = await navigator.mediaDevices.getUserMedia({ video: true }); +const [track] = stream.getVideoTracks(); +const worker = new Worker("worker.js"); +worker.postMessage({ track }, [track]); +const { data } = await new Promise((r) => { + worker.onmessage = r; }); +video.srcObject = new MediaStream([data.track]); +``` + +worker.js: -trackProcessor.readable - .pipeThrough(transformer) - .pipeTo(trackGenerator.writable); +```js +onmessage = async ({ data: { track } }) => { + const vtg = new VideoTrackGenerator(); + self.postMessage({ track: vtg.track }, [vtg.track]); + const { readable } = new MediaStreamTrackProcessor({ track }); + await readable + .pipeThrough(new TransformStream({ transform })) + .pipeTo(vtg.writable); +}; ``` ## Specifications @@ -51,3 +59,10 @@ trackProcessor.readable ## Browser compatibility {{Compat}} + +## See also + +- {{domxref("VideoTrackGenerator")}} +- [Insertable streams for MediaStreamTrack](https://developer.chrome.com/docs/capabilities/web-apis/mediastreamtrack-insertable-media-processing) on developer.chrome.com + > [!NOTE] + > This article was written before the API was restricted to workers and video. Beware its use of the non-standard version of `MediaStreamTrackProcessor` which blocks on the {{Glossary("main thread")}}. diff --git a/files/en-us/web/api/mediastreamtrackprocessor/mediastreamtrackprocessor/index.md b/files/en-us/web/api/mediastreamtrackprocessor/mediastreamtrackprocessor/index.md index 0f0a315c13137e7..47145a2877669c0 100644 --- a/files/en-us/web/api/mediastreamtrackprocessor/mediastreamtrackprocessor/index.md +++ b/files/en-us/web/api/mediastreamtrackprocessor/mediastreamtrackprocessor/index.md @@ -8,7 +8,7 @@ browser-compat: api.MediaStreamTrackProcessor.MediaStreamTrackProcessor {{APIRef("Insertable Streams for MediaStreamTrack API")}} -The **`MediaStreamTrackProcessor()`** constructor creates a new {{domxref("MediaStreamTrackProcessor")}} object which consumes a {{domxref("MediaStreamTrack")}} object's source and generates a stream of media frames. +The **`MediaStreamTrackProcessor()`** constructor creates a new {{domxref("MediaStreamTrackProcessor")}} object which consumes a video {{domxref("MediaStreamTrack")}} object's source and generates a stream of {{domxref("VideoFrame")}}s. ## Syntax diff --git a/files/en-us/web/api/mediastreamtrackprocessor/readable/index.md b/files/en-us/web/api/mediastreamtrackprocessor/readable/index.md index 9c751b516ddfdfe..d5743070f3f4699 100644 --- a/files/en-us/web/api/mediastreamtrackprocessor/readable/index.md +++ b/files/en-us/web/api/mediastreamtrackprocessor/readable/index.md @@ -8,7 +8,7 @@ browser-compat: api.MediaStreamTrackProcessor.readable {{APIRef("Insertable Streams for MediaStreamTrack API")}} -The **`readable`** property of the {{domxref("MediaStreamTrackProcessor")}} interface returns a {{domxref("ReadableStream")}}. +The **`readable`** property of the {{domxref("MediaStreamTrackProcessor")}} interface returns a {{domxref("ReadableStream")}} of {{domxref("VideoFrame")}}s. ## Value @@ -16,18 +16,7 @@ A {{domxref("ReadableStream")}}. ## Examples -In the following example video frames from the {{domxref("ReadableStream")}} are transformed. - -```js -const trackProcessor = new MediaStreamTrackProcessor({ track: videoTrack }); -const trackGenerator = new MediaStreamTrackGenerator({ kind: "video" }); - -/* */ - -trackProcessor.readable - .pipeThrough(transformer) - .pipeTo(trackGenerator.writable); -``` +See the [Insertable Streams for MediaStreamTrack API](/en-US/docs/Web/API/Insertable_Streams_for_MediaStreamTrack_API#examples) for an example. ## Specifications diff --git a/files/en-us/web/api/mediatracksettings/index.md b/files/en-us/web/api/mediatracksettings/index.md index 757f8d7e479c2a7..356b13653d9c78e 100644 --- a/files/en-us/web/api/mediatracksettings/index.md +++ b/files/en-us/web/api/mediatracksettings/index.md @@ -40,6 +40,8 @@ Some or all of the following will be included in the object, either because it's - : A long integer value indicating the current value of the {{domxref("MediaTrackConstraints.sampleRate", "sampleRate")}} property, specifying the sample rate in samples per second of the audio data. Standard CD-quality audio, for example, has a sample rate of 41,000 samples per second. - {{domxref("MediaTrackSettings.sampleSize", "sampleSize")}} - : A long integer value indicating the current value of the {{domxref("MediaTrackConstraints.sampleSize", "sampleSize")}} property, specifying the linear size, in bits, of each audio sample. CD-quality audio, for example, is 16-bit, so this value would be 16 in that case. +- {{domxref("MediaTrackSettings.suppressLocalAudioPlayback", "suppressLocalAudioPlayback")}} + - : Controls whether the audio playing in a tab will continue to be played out of a user's local speakers when the tab is captured. - {{domxref("MediaTrackSettings.volume", "volume")}} {{Deprecated_Inline}} {{Non-standard_Inline}} - : A double-precision floating point value indicating the current value of the {{domxref("MediaTrackConstraints.volume", "volume")}} property, specifying the volume level of the track. This value will be between 0.0 (silent) to 1.0 (maximum supported volume). diff --git a/files/en-us/web/api/mediatracksupportedconstraints/index.md b/files/en-us/web/api/mediatracksupportedconstraints/index.md index cba2b0ffce828b1..3a517118c19ce36 100644 --- a/files/en-us/web/api/mediatracksupportedconstraints/index.md +++ b/files/en-us/web/api/mediatracksupportedconstraints/index.md @@ -20,37 +20,39 @@ To learn more about how constraints work, see [Capabilities, constraints, and se Some combination—but not necessarily all—of the following properties will exist on the object. - {{domxref("MediaTrackSupportedConstraints.autoGainControl", "autoGainControl")}} - - : A Boolean whose value is `true` if the [`autoGainControl`](/en-US/docs/Web/API/MediaTrackConstraints#autogaincontrol) constraint is supported in the current environment. + - : A Boolean whose value is `true` if the [`autoGainControl`](/en-US/docs/Web/API/MediaTrackConstraints/autoGainControl) constraint is supported in the current environment. - {{domxref("MediaTrackSupportedConstraints.width", "width")}} - - : A Boolean value whose value is `true` if the [`width`](/en-US/docs/Web/API/MediaTrackConstraints#width) constraint is supported in the current environment. + - : A Boolean value whose value is `true` if the [`width`](/en-US/docs/Web/API/MediaTrackConstraints/width) constraint is supported in the current environment. - {{domxref("MediaTrackSupportedConstraints.height", "height")}} - - : A Boolean value whose value is `true` if the [`height`](/en-US/docs/Web/API/MediaTrackConstraints#height) constraint is supported in the current environment. + - : A Boolean value whose value is `true` if the [`height`](/en-US/docs/Web/API/MediaTrackConstraints/height) constraint is supported in the current environment. - {{domxref("MediaTrackSupportedConstraints.aspectRatio", "aspectRatio")}} - - : A Boolean value whose value is `true` if the [`aspectRatio`](/en-US/docs/Web/API/MediaTrackConstraints#aspectratio) constraint is supported in the current environment. + - : A Boolean value whose value is `true` if the [`aspectRatio`](/en-US/docs/Web/API/MediaTrackConstraints/aspectRatio) constraint is supported in the current environment. - {{domxref("MediaTrackSupportedConstraints.frameRate", "frameRate")}} - - : A Boolean value whose value is `true` if the [`frameRate`](/en-US/docs/Web/API/MediaTrackConstraints#framerate) constraint is supported in the current environment. + - : A Boolean value whose value is `true` if the [`frameRate`](/en-US/docs/Web/API/MediaTrackConstraints/frameRate) constraint is supported in the current environment. - {{domxref("MediaTrackSupportedConstraints.facingMode", "facingMode")}} - - : A Boolean value whose value is `true` if the [`facingMode`](/en-US/docs/Web/API/MediaTrackConstraints#facingmode) constraint is supported in the current environment. + - : A Boolean value whose value is `true` if the [`facingMode`](/en-US/docs/Web/API/MediaTrackConstraints/facingMode) constraint is supported in the current environment. - {{domxref("MediaTrackSupportedConstraints.resizeMode", "resizeMode")}} - - : A Boolean value whose value is `true` if the [`resizeMode`](/en-US/docs/Web/API/MediaTrackConstraints#resizemode) constraint is supported in the current environment. + - : A Boolean value whose value is `true` if the [`resizeMode`](/en-US/docs/Web/API/MediaTrackConstraints/resizeMode) constraint is supported in the current environment. - {{domxref("MediaTrackSupportedConstraints.volume", "volume")}} {{Deprecated_Inline}} {{Non-standard_Inline}} - - : A Boolean value whose value is `true` if the [`volume`](/en-US/docs/Web/API/MediaTrackConstraints#volume) constraint is supported in the current environment. + - : A Boolean value whose value is `true` if the [`volume`](/en-US/docs/Web/API/MediaTrackConstraints/volume) constraint is supported in the current environment. - {{domxref("MediaTrackSupportedConstraints.sampleRate", "sampleRate")}} - - : A Boolean value whose value is `true` if the [`sampleRate`](/en-US/docs/Web/API/MediaTrackConstraints#samplerate) constraint is supported in the current environment. + - : A Boolean value whose value is `true` if the [`sampleRate`](/en-US/docs/Web/API/MediaTrackConstraints/sampleRate) constraint is supported in the current environment. - {{domxref("MediaTrackSupportedConstraints.sampleSize", "sampleSize")}} - - : A Boolean value whose value is `true` if the [`sampleSize`](/en-US/docs/Web/API/MediaTrackConstraints#samplesize) constraint is supported in the current environment. + - : A Boolean value whose value is `true` if the [`sampleSize`](/en-US/docs/Web/API/MediaTrackConstraints/sampleSize) constraint is supported in the current environment. - {{domxref("MediaTrackSupportedConstraints.echoCancellation", "echoCancellation")}} - - : A Boolean value whose value is `true` if the [`echoCancellation`](/en-US/docs/Web/API/MediaTrackConstraints#echocancellation) constraint is supported in the current environment. + - : A Boolean value whose value is `true` if the [`echoCancellation`](/en-US/docs/Web/API/MediaTrackConstraints/echoCancellation) constraint is supported in the current environment. - {{domxref("MediaTrackSupportedConstraints.latency", "latency")}} - - : A Boolean value whose value is `true` if the [`latency`](/en-US/docs/Web/API/MediaTrackConstraints#latency) constraint is supported in the current environment. + - : A Boolean value whose value is `true` if the [`latency`](/en-US/docs/Web/API/MediaTrackConstraints/latency) constraint is supported in the current environment. - {{domxref("MediaTrackSupportedConstraints.noiseSuppression", "noiseSuppression")}} - - : A Boolean whose value is `true` if the [`noiseSuppression`](/en-US/docs/Web/API/MediaTrackConstraints#noisesuppression) constraint is supported in the current environment. + - : A Boolean whose value is `true` if the [`noiseSuppression`](/en-US/docs/Web/API/MediaTrackConstraints/noiseSuppression) constraint is supported in the current environment. +- {{domxref("MediaTrackSupportedConstraints.suppressLocalAudioPlayback", "suppressLocalAudioPlayback")}} + - : A Boolean whose value is `true` if the [`suppressLocalAudioPlayback`](/en-US/docs/Web/API/MediaTrackConstraints/suppressLocalAudioPlayback) constraint is supported in the current environment. - {{domxref("MediaTrackSupportedConstraints.channelCount", "channelCount")}} - - : A Boolean value whose value is `true` if the [`channelCount`](/en-US/docs/Web/API/MediaTrackConstraints#channelcount) constraint is supported in the current environment. + - : A Boolean value whose value is `true` if the [`channelCount`](/en-US/docs/Web/API/MediaTrackConstraints/channelCount) constraint is supported in the current environment. - {{domxref("MediaTrackSupportedConstraints.deviceId", "deviceId")}} - - : A Boolean value whose value is `true` if the [`deviceId`](/en-US/docs/Web/API/MediaTrackConstraints#deviceid) constraint is supported in the current environment. + - : A Boolean value whose value is `true` if the [`deviceId`](/en-US/docs/Web/API/MediaTrackConstraints/deviceId) constraint is supported in the current environment. - {{domxref("MediaTrackSupportedConstraints.groupId", "groupId")}} - - : A Boolean value whose value is `true` if the [`groupId`](/en-US/docs/Web/API/MediaTrackConstraints#groupid) constraint is supported in the current environment. + - : A Boolean value whose value is `true` if the [`groupId`](/en-US/docs/Web/API/MediaTrackConstraints/groupId) constraint is supported in the current environment. ### Instance properties specific to shared screen tracks diff --git a/files/en-us/web/api/messageport/message_event/index.md b/files/en-us/web/api/messageport/message_event/index.md index 3d4e2e262c00359..a37497d8f5417fa 100644 --- a/files/en-us/web/api/messageport/message_event/index.md +++ b/files/en-us/web/api/messageport/message_event/index.md @@ -16,10 +16,10 @@ This event is not cancellable and does not bubble. Use the event name in methods like {{domxref("EventTarget.addEventListener", "addEventListener()")}}, or set an event handler property. -```js -addEventListener("message", (event) => {}); +```js-nolint +addEventListener("message", (event) => { }) -onmessage = (event) => {}; +onmessage = (event) => { } ``` ## Event type @@ -45,7 +45,7 @@ _This interface also inherits properties from its parent, {{domxref("Event")}}._ ## Examples -Suppose a script creates a [`MessageChannel`](/en-US/docs/Web/API/MessageChannel) and sends one of the ports to a different browsing context, such as another [`<iframe>`](/en-US/docs/Web/HTML/Element/iframe), using code like this: +Suppose a script creates a [`MessageChannel`](/en-US/docs/Web/API/MessageChannel) and sends one of the ports to a different browsing context, such as another [`<iframe>`](/en-US/docs/Web/HTML/Reference/Elements/iframe), using code like this: ```js const channel = new MessageChannel(); diff --git a/files/en-us/web/api/messageport/messageerror_event/index.md b/files/en-us/web/api/messageport/messageerror_event/index.md index 176312354c261c4..a74de8f1aafc8c8 100644 --- a/files/en-us/web/api/messageport/messageerror_event/index.md +++ b/files/en-us/web/api/messageport/messageerror_event/index.md @@ -16,10 +16,10 @@ This event is not cancellable and does not bubble. Use the event name in methods like {{domxref("EventTarget.addEventListener", "addEventListener()")}}, or set an event handler property. -```js -addEventListener("messageerror", (event) => {}); +```js-nolint +addEventListener("messageerror", (event) => { }) -onmessageerror = (event) => {}; +onmessageerror = (event) => { } ``` ## Event type @@ -45,7 +45,7 @@ _This interface also inherits properties from its parent, {{domxref("Event")}}._ ## Examples -Suppose a script creates a [`MessageChannel`](/en-US/docs/Web/API/MessageChannel) and sends one of the ports to a different browsing context, such as another [`<iframe>`](/en-US/docs/Web/HTML/Element/iframe), using code like this: +Suppose a script creates a [`MessageChannel`](/en-US/docs/Web/API/MessageChannel) and sends one of the ports to a different browsing context, such as another [`<iframe>`](/en-US/docs/Web/HTML/Reference/Elements/iframe), using code like this: ```js const channel = new MessageChannel(); diff --git a/files/en-us/web/api/midiaccess/statechange_event/index.md b/files/en-us/web/api/midiaccess/statechange_event/index.md index 443cf63944b8db7..6672110bcec4f52 100644 --- a/files/en-us/web/api/midiaccess/statechange_event/index.md +++ b/files/en-us/web/api/midiaccess/statechange_event/index.md @@ -14,10 +14,10 @@ The **`statechange`** event of the {{domxref("MIDIAccess")}} interface is fired Use the event name in methods like {{domxref("EventTarget.addEventListener", "addEventListener()")}}, or set an event handler property. -```js -addEventListener("statechange", (event) => {}); +```js-nolint +addEventListener("statechange", (event) => { }) -onstatechange = (event) => {}; +onstatechange = (event) => { } ``` ## Event type diff --git a/files/en-us/web/api/midiinput/midimessage_event/index.md b/files/en-us/web/api/midiinput/midimessage_event/index.md index 64b7d0283f6954b..401fd01f7054dbf 100644 --- a/files/en-us/web/api/midiinput/midimessage_event/index.md +++ b/files/en-us/web/api/midiinput/midimessage_event/index.md @@ -14,10 +14,10 @@ The `midimessage` event of the [Web MIDI API](/en-US/docs/Web/API/Web_MIDI_API) Use the event name in methods like {{domxref("EventTarget.addEventListener", "addEventListener()")}}, or set an event handler property. -```js -addEventListener("midimessage", (event) => {}); +```js-nolint +addEventListener("midimessage", (event) => { }) -onmidimessage = (event) => {}; +onmidimessage = (event) => { } ``` ## Event type diff --git a/files/en-us/web/api/midioutput/send/index.md b/files/en-us/web/api/midioutput/send/index.md index 746fc62fe387f72..4bbac4df5de7f04 100644 --- a/files/en-us/web/api/midioutput/send/index.md +++ b/files/en-us/web/api/midioutput/send/index.md @@ -43,9 +43,9 @@ In the following example a middle C note is sent immediately, followed by a note ```js function sendMiddleC(midiAccess, portID) { - const noteOnMessage = [0x90, 60, 0x7f]; // note on middle C, full velocity + const noteOnMessage = [0x90, 60, 0x7f]; // Note on middle C, full velocity const output = midiAccess.outputs.get(portID); - output.send(noteOnMessage); //omitting the timestamp means send immediately. + output.send(noteOnMessage); // Omitting the timestamp means send immediately. output.send([0x80, 60, 0x40], window.performance.now() + 1000.0); // timestamp = now + 1000ms. } ``` diff --git a/files/en-us/web/api/midiport/statechange_event/index.md b/files/en-us/web/api/midiport/statechange_event/index.md index 90d694a84770694..71892e31c4d73f5 100644 --- a/files/en-us/web/api/midiport/statechange_event/index.md +++ b/files/en-us/web/api/midiport/statechange_event/index.md @@ -14,10 +14,10 @@ The **`statechange`** event of the {{domxref("MIDIPort")}} interface is fired wh Use the event name in methods like {{domxref("EventTarget.addEventListener", "addEventListener()")}}, or set an event handler property. -```js -addEventListener("statechange", (event) => {}); +```js-nolint +addEventListener("statechange", (event) => { }) -onstatechange = (event) => {}; +onstatechange = (event) => { } ``` ## Event type diff --git a/files/en-us/web/api/mouseevent/button/index.md b/files/en-us/web/api/mouseevent/button/index.md index 737543febb15dba..8d25c65ea150a66 100644 --- a/files/en-us/web/api/mouseevent/button/index.md +++ b/files/en-us/web/api/mouseevent/button/index.md @@ -8,9 +8,9 @@ browser-compat: api.MouseEvent.button {{APIRef("UI Events")}} -The **`MouseEvent.button`** read-only property indicates which button was pressed on the mouse to trigger the event. +The **`MouseEvent.button`** read-only property indicates which button was pressed or released on the mouse to trigger the event. -This property only guarantees to indicate which buttons are pressed during events caused by pressing or releasing one or multiple buttons. +This property only guarantees to indicate which buttons are pressed or released during events caused by pressing or releasing one or multiple buttons. As such, it is not reliable for events such as {{domxref("Element/mouseenter_event", "mouseenter")}}, {{domxref("Element/mouseleave_event", "mouseleave")}}, {{domxref("Element/mouseover_event", "mouseover")}}, {{domxref("Element/mouseout_event", "mouseout")}}, or {{domxref("Element/mousemove_event", "mousemove")}}. Users may change the configuration of buttons on their pointing device so that if an event's button property is zero, it may not have been caused by the button that is physically left–most on the pointing device; however, it should behave as if the left button was clicked in the standard button layout. @@ -22,11 +22,11 @@ Users may change the configuration of buttons on their pointing device so that i A number representing a given button: -- `0`: Main button pressed, usually the left button or the un-initialized +- `0`: Main button, usually the left button or the un-initialized state -- `1`: Auxiliary button pressed, usually the wheel button or the middle +- `1`: Auxiliary button, usually the wheel button or the middle button (if present) -- `2`: Secondary button pressed, usually the right button +- `2`: Secondary button, usually the right button - `3`: Fourth button, typically the _Browser Back_ button - `4`: Fifth button, typically the _Browser Forward_ button diff --git a/files/en-us/web/api/mouseevent/index.md b/files/en-us/web/api/mouseevent/index.md index 5a560124a26c7d7..b28ccd1640d727c 100644 --- a/files/en-us/web/api/mouseevent/index.md +++ b/files/en-us/web/api/mouseevent/index.md @@ -36,7 +36,7 @@ _This interface also inherits properties of its parents, {{domxref("UIEvent")}} - {{domxref("MouseEvent.altKey")}} {{ReadOnlyInline}} - : Returns `true` if the <kbd>alt</kbd> key was down when the mouse event was fired. - {{domxref("MouseEvent.button")}} {{ReadOnlyInline}} - - : The button number that was pressed (if applicable) when the mouse event was fired. + - : The button number that was pressed or released (if applicable) when the mouse event was fired. - {{domxref("MouseEvent.buttons")}} {{ReadOnlyInline}} - : The buttons being pressed (if any) when the mouse event was fired. - {{domxref("MouseEvent.clientX")}} {{ReadOnlyInline}} diff --git a/files/en-us/web/api/mouseevent/movementx/index.md b/files/en-us/web/api/mouseevent/movementx/index.md index 316afd7a6156569..1baf787bf4d2786 100644 --- a/files/en-us/web/api/mouseevent/movementx/index.md +++ b/files/en-us/web/api/mouseevent/movementx/index.md @@ -12,7 +12,7 @@ The **`movementX`** read-only property of the {{domxref("MouseEvent")}} interfac In other words, the value of the property is computed like this: `currentEvent.movementX = currentEvent.screenX - previousEvent.screenX`. > [!WARNING] -> Browsers [use different units for `movementX` and {{domxref("MouseEvent.screenX", "screenX")}}](https://github.com/w3c/pointerlock/issues/42) than what the specification defines. Depending on the browser and operating system, the `movementX` units may be a physical pixel, a logical pixel, or a CSS pixel. You may want to avoid the movement properties, and instead calculate the delta between the current client values ({{domxref("MouseEvent.screenX", "screenX")}}, {{domxref("MouseEvent.screenY", "screenY")}}) and the previous client values. +> Browsers [use different units for `movementX` and `screenX`](https://github.com/w3c/pointerlock/issues/42) than what the specification defines. Depending on the browser and operating system, the `movementX` units may be a physical pixel, a logical pixel, or a CSS pixel. You may want to avoid the movement properties, and instead calculate the delta between the current client values ({{domxref("MouseEvent.screenX", "screenX")}}, {{domxref("MouseEvent.screenY", "screenY")}}) and the previous client values. ## Value diff --git a/files/en-us/web/api/mouseevent/movementy/index.md b/files/en-us/web/api/mouseevent/movementy/index.md index 3fbc4be1116b156..e85b6f5daecb6fb 100644 --- a/files/en-us/web/api/mouseevent/movementy/index.md +++ b/files/en-us/web/api/mouseevent/movementy/index.md @@ -12,7 +12,7 @@ The **`movementY`** read-only property of the {{domxref("MouseEvent")}} interfac In other words, the value of the property is computed like this: `currentEvent.movementY = currentEvent.screenY - previousEvent.screenY`. > [!WARNING] -> Browsers [use different units for `movementY` and {{domxref("MouseEvent.screenY", "screenY")}}](https://github.com/w3c/pointerlock/issues/42) than what the specification defines. Depending on the browser and operating system, the `movementY` units may be a physical pixel, a logical pixel, or a CSS pixel. You may want to avoid the movement properties, and instead calculate the delta between the current client values ({{domxref("MouseEvent.screenX", "screenX")}}, {{domxref("MouseEvent.screenY", "screenY")}}) and the previous client values. +> Browsers [use different units for `movementY` and `screenY`](https://github.com/w3c/pointerlock/issues/42) than what the specification defines. Depending on the browser and operating system, the `movementY` units may be a physical pixel, a logical pixel, or a CSS pixel. You may want to avoid the movement properties, and instead calculate the delta between the current client values ({{domxref("MouseEvent.screenX", "screenX")}}, {{domxref("MouseEvent.screenY", "screenY")}}) and the previous client values. ## Value diff --git a/files/en-us/web/api/mutationobserver/observe/index.md b/files/en-us/web/api/mutationobserver/observe/index.md index cfcf82064f8d8f7..85ed836a29cc68f 100644 --- a/files/en-us/web/api/mutationobserver/observe/index.md +++ b/files/en-us/web/api/mutationobserver/observe/index.md @@ -178,7 +178,7 @@ observer.observe(userListElement, { ### Monitoring attribute values -In this example we observe an element for attribute value changes, and add a button which toggles the element's [`dir`](/en-US/docs/Web/HTML/Global_attributes/dir) attribute between `"ltr"` and `"rtl"`. Inside the observer's callback, we log the old value of the attribute. +In this example we observe an element for attribute value changes, and add a button which toggles the element's [`dir`](/en-US/docs/Web/HTML/Reference/Global_attributes/dir) attribute between `"ltr"` and `"rtl"`. Inside the observer's callback, we log the old value of the attribute. #### HTML diff --git a/files/en-us/web/api/mutationrecord/addednodes/index.md b/files/en-us/web/api/mutationrecord/addednodes/index.md index dc94a5ba1a3a9c2..b0a8dcf32f202ae 100644 --- a/files/en-us/web/api/mutationrecord/addednodes/index.md +++ b/files/en-us/web/api/mutationrecord/addednodes/index.md @@ -69,7 +69,7 @@ function logNewNodes(records) { for (const record of records) { // Check if the childlist of the target node has been mutated if (record.type === "childList") { - totalAddedNodes = totalAddedNodes + record.addedNodes.length; + totalAddedNodes += record.addedNodes.length; // Log the number of nodes added counter.textContent = `Total added nodes: ${totalAddedNodes}`; } diff --git a/files/en-us/web/api/mutationrecord/removednodes/index.md b/files/en-us/web/api/mutationrecord/removednodes/index.md index 3d7bc2b325de3e1..e68d0cc96a3bafe 100644 --- a/files/en-us/web/api/mutationrecord/removednodes/index.md +++ b/files/en-us/web/api/mutationrecord/removednodes/index.md @@ -69,7 +69,7 @@ function logRemovedNodes(records) { for (const record of records) { // Check if the childlist of the target node has been mutated if (record.type === "childList") { - totalRemovedNodes = totalRemovedNodes + record.removedNodes.length; + totalRemovedNodes += record.removedNodes.length; // Log the number of nodes added counter.textContent = `Total removed nodes: ${totalRemovedNodes}`; } diff --git a/files/en-us/web/api/mutationrecord/target/index.md b/files/en-us/web/api/mutationrecord/target/index.md index d09f2fdb797d0ea..737c8918ba8fdf3 100644 --- a/files/en-us/web/api/mutationrecord/target/index.md +++ b/files/en-us/web/api/mutationrecord/target/index.md @@ -8,7 +8,7 @@ browser-compat: api.MutationRecord.target {{APIRef("DOM")}} -The {{domxref("MutationRecord")}} read-only property **`target`** is the target (i.e. the mutated/changed node) of a mutation observed with a {{domxref("MutationObserver")}}. +The {{domxref("MutationRecord")}} read-only property **`target`** is the target (i.e., the mutated/changed node) of a mutation observed with a {{domxref("MutationObserver")}}. ## Value diff --git a/files/en-us/web/api/navigateevent/downloadrequest/index.md b/files/en-us/web/api/navigateevent/downloadrequest/index.md index 925b0791b6d6148..1fdfd5bfe902625 100644 --- a/files/en-us/web/api/navigateevent/downloadrequest/index.md +++ b/files/en-us/web/api/navigateevent/downloadrequest/index.md @@ -11,7 +11,7 @@ browser-compat: api.NavigateEvent.downloadRequest {{APIRef("Navigation API")}}{{SeeCompatTable}} The **`downloadRequest`** read-only property of the -{{domxref("NavigateEvent")}} interface returns the filename of the file requested for download, in the case of a download navigation (e.g. an {{htmlelement("a")}} or {{htmlelement("area")}} element with a `download` attribute), or `null` otherwise. +{{domxref("NavigateEvent")}} interface returns the filename of the file requested for download, in the case of a download navigation (e.g., an {{htmlelement("a")}} or {{htmlelement("area")}} element with a `download` attribute), or `null` otherwise. ## Value diff --git a/files/en-us/web/api/navigateevent/formdata/index.md b/files/en-us/web/api/navigateevent/formdata/index.md index d3b30228e8893fc..c7b403bcb14b5a1 100644 --- a/files/en-us/web/api/navigateevent/formdata/index.md +++ b/files/en-us/web/api/navigateevent/formdata/index.md @@ -11,7 +11,7 @@ browser-compat: api.NavigateEvent.formData {{APIRef("Navigation API")}}{{SeeCompatTable}} The **`formData`** read-only property of the -{{domxref("NavigateEvent")}} interface returns the {{domxref("FormData")}} object representing the submitted data in the case of a [`POST`](/en-US/docs/Web/HTTP/Methods/POST) form submission, or `null` otherwise. +{{domxref("NavigateEvent")}} interface returns the {{domxref("FormData")}} object representing the submitted data in the case of a [`POST`](/en-US/docs/Web/HTTP/Reference/Methods/POST) form submission, or `null` otherwise. ## Value diff --git a/files/en-us/web/api/navigateevent/hashchange/index.md b/files/en-us/web/api/navigateevent/hashchange/index.md index 6e155c8e9776df5..60736e0bf164608 100644 --- a/files/en-us/web/api/navigateevent/hashchange/index.md +++ b/files/en-us/web/api/navigateevent/hashchange/index.md @@ -11,7 +11,7 @@ browser-compat: api.NavigateEvent.hashChange {{APIRef("Navigation API")}}{{SeeCompatTable}} The **`hashChange`** read-only property of the -{{domxref("NavigateEvent")}} interface returns `true` if the navigation is a fragment navigation (i.e. to a fragment identifier in the same document), or `false` otherwise. +{{domxref("NavigateEvent")}} interface returns `true` if the navigation is a fragment navigation (i.e., to a fragment identifier in the same document), or `false` otherwise. ## Value diff --git a/files/en-us/web/api/navigateevent/index.md b/files/en-us/web/api/navigateevent/index.md index 8fcc74e6de0a35d..1b8a54f92446eb1 100644 --- a/files/en-us/web/api/navigateevent/index.md +++ b/files/en-us/web/api/navigateevent/index.md @@ -23,25 +23,27 @@ The **`NavigateEvent`** interface of the {{domxref("Navigation API", "Navigation _Inherits properties from its parent, {{DOMxRef("Event")}}._ - {{domxref("NavigateEvent.canIntercept", "canIntercept")}} {{ReadOnlyInline}} {{Experimental_Inline}} - - : Returns `true` if the navigation can be intercepted, or `false` otherwise (e.g. you can't intercept a cross-origin navigation). + - : Returns `true` if the navigation can be intercepted, or `false` otherwise (e.g., you can't intercept a cross-origin navigation). - {{domxref("NavigateEvent.destination", "destination")}} {{ReadOnlyInline}} {{Experimental_Inline}} - : Returns a {{domxref("NavigationDestination")}} object representing the destination being navigated to. - {{domxref("NavigateEvent.downloadRequest", "downloadRequest")}} {{ReadOnlyInline}} {{Experimental_Inline}} - - : Returns the filename of the file requested for download, in the case of a download navigation (e.g. an {{htmlelement("a")}} or {{htmlelement("area")}} element with a `download` attribute), or `null` otherwise. + - : Returns the filename of the file requested for download, in the case of a download navigation (e.g., an {{htmlelement("a")}} or {{htmlelement("area")}} element with a `download` attribute), or `null` otherwise. - {{domxref("NavigateEvent.formData", "formData")}} {{ReadOnlyInline}} {{Experimental_Inline}} - : Returns the {{domxref("FormData")}} object representing the submitted data in the case of a `POST` form submission, or `null` otherwise. - {{domxref("NavigateEvent.hashChange", "hashChange")}} {{ReadOnlyInline}} {{Experimental_Inline}} - - : Returns `true` if the navigation is a fragment navigation (i.e. to a fragment identifier in the same document), or `false` otherwise. + - : Returns `true` if the navigation is a fragment navigation (i.e., to a fragment identifier in the same document), or `false` otherwise. - {{domxref("NavigateEvent.hasUAVisualTransition", "hasUAVisualTransition")}} {{ReadOnlyInline}} {{Experimental_Inline}} - : Returns `true` if the user agent performed a visual transition for this navigation before dispatching this event, or `false` otherwise. - {{domxref("NavigateEvent.info", "info")}} {{ReadOnlyInline}} {{Experimental_Inline}} - - : Returns the `info` data value passed by the initiating navigation operation (e.g. {{domxref("Navigation.back()")}}, or {{domxref("Navigation.navigate()")}}), or `undefined` if no `info` data was passed. + - : Returns the `info` data value passed by the initiating navigation operation (e.g., {{domxref("Navigation.back()")}}, or {{domxref("Navigation.navigate()")}}), or `undefined` if no `info` data was passed. - {{domxref("NavigateEvent.navigationType", "navigationType")}} {{ReadOnlyInline}} {{Experimental_Inline}} - : Returns the type of the navigation — `push`, `reload`, `replace`, or `traverse`. - {{domxref("NavigateEvent.signal", "signal")}} {{ReadOnlyInline}} {{Experimental_Inline}} - - : Returns an {{domxref("AbortSignal")}}, which will become aborted if the navigation is cancelled (e.g. by the user pressing the browser's "Stop" button, or another navigation starting and thus cancelling the ongoing one). + - : Returns an {{domxref("AbortSignal")}}, which will become aborted if the navigation is cancelled (e.g., by the user pressing the browser's "Stop" button, or another navigation starting and thus cancelling the ongoing one). +- {{domxref("NavigateEvent.sourceElement", "sourceElement")}} {{ReadOnlyInline}} {{Experimental_Inline}} + - : When the navigation was initiated by an element (for example clicking a link), returns an {{domxref("Element")}} object representing the initiating element. - {{domxref("NavigateEvent.userInitiated", "userInitiated")}} {{ReadOnlyInline}} {{Experimental_Inline}} - - : Returns `true` if the navigation was initiated by the user (e.g. by clicking a link, submitting a form, or pressing the browser's "Back"/"Forward" buttons), or `false` otherwise. + - : Returns `true` if the navigation was initiated by the user (e.g., by clicking a link, submitting a form, or pressing the browser's "Back"/"Forward" buttons), or `false` otherwise. ## Instance methods diff --git a/files/en-us/web/api/navigateevent/info/index.md b/files/en-us/web/api/navigateevent/info/index.md index 22bcf5fa479920c..687636946973728 100644 --- a/files/en-us/web/api/navigateevent/info/index.md +++ b/files/en-us/web/api/navigateevent/info/index.md @@ -11,7 +11,7 @@ browser-compat: api.NavigateEvent.info {{APIRef("Navigation API")}}{{SeeCompatTable}} The **`info`** read-only property of the -{{domxref("NavigateEvent")}} interface returns the `info` data value passed by the initiating navigation operation (e.g. {{domxref("Navigation.back()")}}, or {{domxref("Navigation.navigate()")}}), or `undefined` if no `info` data was passed. +{{domxref("NavigateEvent")}} interface returns the `info` data value passed by the initiating navigation operation (e.g., {{domxref("Navigation.back()")}}, or {{domxref("Navigation.navigate()")}}), or `undefined` if no `info` data was passed. ## Value diff --git a/files/en-us/web/api/navigateevent/intercept/index.md b/files/en-us/web/api/navigateevent/intercept/index.md index d47fd5c3ef8e9ae..b63963fcc8a6c01 100644 --- a/files/en-us/web/api/navigateevent/intercept/index.md +++ b/files/en-us/web/api/navigateevent/intercept/index.md @@ -29,7 +29,7 @@ intercept(options) - `focusReset` {{optional_inline}} - : Defines the navigation's focus behavior. This may take one of the following values: - `after-transition` - - : Once the promise returned by your handler function resolves, the browser will focus the first element with the [`autofocus`](/en-US/docs/Web/HTML/Global_attributes/autofocus) attribute, or the {{htmlelement("body")}} element if no element has `autofocus` set. This is the default value. + - : Once the promise returned by your handler function resolves, the browser will focus the first element with the [`autofocus`](/en-US/docs/Web/HTML/Reference/Global_attributes/autofocus) attribute, or the {{htmlelement("body")}} element if no element has `autofocus` set. This is the default value. - `manual` - : Disable the default behavior. - `scroll` {{optional_inline}} @@ -48,7 +48,7 @@ None (`undefined`). - `InvalidStateError` {{domxref("DOMException")}} - : Thrown if the current {{domxref("Document")}} is not yet active, or if the navigation has been cancelled. - `SecurityError` {{domxref("DOMException")}} - - : Thrown if the event was dispatched by a {{domxref("EventTarget.dispatchEvent", "dispatchEvent()")}} call, rather than the user agent, or if the navigation cannot be intercepted (i.e. {{domxref("NavigateEvent.canIntercept")}} is `false`). + - : Thrown if the event was dispatched by a {{domxref("EventTarget.dispatchEvent", "dispatchEvent()")}} call, rather than the user agent, or if the navigation cannot be intercepted (i.e., {{domxref("NavigateEvent.canIntercept")}} is `false`). ## Examples diff --git a/files/en-us/web/api/navigateevent/navigateevent/index.md b/files/en-us/web/api/navigateevent/navigateevent/index.md index ffce53d317cc99a..28c8989948d9632 100644 --- a/files/en-us/web/api/navigateevent/navigateevent/index.md +++ b/files/en-us/web/api/navigateevent/navigateevent/index.md @@ -25,25 +25,27 @@ new NavigateEvent(type, init) - `init` - : An object that, _in addition to the properties defined in {{domxref("Event/Event", "Event()")}}_, has the following properties: - `canIntercept` {{optional_inline}} - - : A boolean defining whether the navigation can be intercepted or not (e.g. you can't intercept a cross-origin navigation). Defaults to `false`. + - : A boolean defining whether the navigation can be intercepted or not (e.g., you can't intercept a cross-origin navigation). Defaults to `false`. - `destination` - : A {{domxref("NavigationDestination")}} object representing the location being navigated to. - `downloadRequest` {{optional_inline}} - - : The filename of the file requested for download, in the case of a download navigation (e.g. an {{htmlelement("a")}} or {{htmlelement("area")}} element with a `download` attribute). Defaults to `null`. + - : The filename of the file requested for download, in the case of a download navigation (e.g., an {{htmlelement("a")}} or {{htmlelement("area")}} element with a `download` attribute). Defaults to `null`. - `formData` {{optional_inline}} - : The {{domxref("FormData")}} object representing the submitted data in the case of a `POST` form submission. Defaults to `null`. - `hashChange` {{optional_inline}} - - : A boolean defining if the navigation is a fragment navigation (i.e. to a fragment identifier in the same document). Defaults to `false`. + - : A boolean defining if the navigation is a fragment navigation (i.e., to a fragment identifier in the same document). Defaults to `false`. - `hasUAVisualTransition` {{optional_inline}} - : A boolean defining whether the user agent has performed a visual transition for this navigation before dispatching this event. Defaults to `false`. - `info` {{optional_inline}} - - : The `info` data value passed by the initiating navigation operation (e.g. {{domxref("Navigation.back()")}}, or {{domxref("Navigation.navigate()")}}). + - : The `info` data value passed by the initiating navigation operation (e.g., {{domxref("Navigation.back()")}}, or {{domxref("Navigation.navigate()")}}). - `navigationType` {{optional_inline}} - : The type of the navigation. Possible values — `push`, `reload`, `replace`, and `traverse`. Defaults to `push`. - `signal` - - : An {{domxref("AbortSignal")}}, which will become aborted if the navigation is cancelled (e.g. by the user pressing the browser's "Stop" button, or another navigation starting and thus cancelling the ongoing one). + - : An {{domxref("AbortSignal")}}, which will become aborted if the navigation is cancelled (e.g., by the user pressing the browser's "Stop" button, or another navigation starting and thus cancelling the ongoing one). + - `sourceElement` {{optional_inline}} + - : An {{domxref("Element")}} object representing the initiating element in cases where the navigation was initiated by an element, or `null` if the navigation was not initiated by an element. Defaults to `null`. - `userInitiated` {{optional_inline}} - - : A boolean defining whether the navigation was initiated by the user (e.g. by clicking a link, submitting a form, or pressing the browser's "Back"/"Forward" buttons). Defaults to `false`. + - : A boolean defining whether the navigation was initiated by the user (e.g., by clicking a link, submitting a form, or pressing the browser's "Back"/"Forward" buttons). Defaults to `false`. ### Return value diff --git a/files/en-us/web/api/navigateevent/navigationtype/index.md b/files/en-us/web/api/navigateevent/navigationtype/index.md index 7f7bfb135d417e0..3d4c4dc7985a957 100644 --- a/files/en-us/web/api/navigateevent/navigationtype/index.md +++ b/files/en-us/web/api/navigateevent/navigationtype/index.md @@ -28,7 +28,7 @@ The possible values are: ### Async transitions with special back/forward handling -Sometimes it's desirable to handle back/forward navigations specially, e.g. reusing cached views by transitioning them onto the screen. This can be done by branching as follows: +Sometimes it's desirable to handle back/forward navigations specially, e.g., reusing cached views by transitioning them onto the screen. This can be done by branching as follows: ```js navigation.addEventListener("navigate", (event) => { diff --git a/files/en-us/web/api/navigateevent/signal/index.md b/files/en-us/web/api/navigateevent/signal/index.md index 472e52b62621178..2b950cc6f02f6e8 100644 --- a/files/en-us/web/api/navigateevent/signal/index.md +++ b/files/en-us/web/api/navigateevent/signal/index.md @@ -11,7 +11,7 @@ browser-compat: api.NavigateEvent.signal {{APIRef("Navigation API")}}{{SeeCompatTable}} The **`signal`** read-only property of the -{{domxref("NavigateEvent")}} interface returns an {{domxref("AbortSignal")}}, which will become aborted if the navigation is cancelled (e.g. by the user pressing the browser's "Stop" button, or another navigation starting and thus cancelling the ongoing one). +{{domxref("NavigateEvent")}} interface returns an {{domxref("AbortSignal")}}, which will become aborted if the navigation is cancelled (e.g., by the user pressing the browser's "Stop" button, or another navigation starting and thus cancelling the ongoing one). ## Value @@ -25,11 +25,11 @@ The general idea here is that the `signal` property can be passed to an associat navigation.addEventListener("navigate", (event) => { event.intercept({ async handler() { - // ... + // … await fetch(`/img/some-image.jpg`, { signal: event.signal }); - // ... + // … }, }); }); diff --git a/files/en-us/web/api/navigateevent/sourceelement/index.md b/files/en-us/web/api/navigateevent/sourceelement/index.md new file mode 100644 index 000000000000000..b05e5afc23fa694 --- /dev/null +++ b/files/en-us/web/api/navigateevent/sourceelement/index.md @@ -0,0 +1,47 @@ +--- +title: "NavigateEvent: sourceElement property" +short-title: sourceElement +slug: Web/API/NavigateEvent/sourceElement +page-type: web-api-instance-property +status: + - experimental +browser-compat: api.NavigateEvent.sourceElement +--- + +{{APIRef("Navigation API")}}{{SeeCompatTable}} + +The **`sourceElement`** read-only property of the +{{domxref("NavigateEvent")}} interface returns an {{domxref("Element")}} object representing the initiating element, in cases where the navigation was initiated by an element. + +The initiating element can be: + +- An HTML {{htmlelement("a")}} element (or SVG [`<a>`](/en-US/docs/Web/SVG/Reference/Element/a) element). +- An {{htmlelement("area")}} element. +- A submit button ([`<input type="submit">`](/en-US/docs/Web/HTML/Reference/Elements/input/submit) or [`<button type="submit">`](/en-US/docs/Web/HTML/Reference/Elements/button)). +- A submitted {{htmlelement("form")}} element. + +## Value + +An {{domxref("Element")}} object representing the element that initiated the navigation, or `null` if the navigation was not initiated by an element. + +## Examples + +```js +navigation.addEventListener("navigate", (event) => { + console.log(event.sourceElement); +}); +``` + +## Specifications + +{{Specifications}} + +## Browser compatibility + +{{Compat}} + +## See also + +- [Modern client-side routing: the Navigation API](https://developer.chrome.com/docs/web-platform/navigation-api/) +- [Navigation API explainer](https://github.com/WICG/navigation-api/blob/main/README.md) +- Domenic Denicola's [Navigation API live demo](https://gigantic-honored-octagon.glitch.me/) diff --git a/files/en-us/web/api/navigateevent/userinitiated/index.md b/files/en-us/web/api/navigateevent/userinitiated/index.md index a320cd5d061bb21..222c73e0cf700f1 100644 --- a/files/en-us/web/api/navigateevent/userinitiated/index.md +++ b/files/en-us/web/api/navigateevent/userinitiated/index.md @@ -11,7 +11,7 @@ browser-compat: api.NavigateEvent.userInitiated {{APIRef("Navigation API")}}{{SeeCompatTable}} The **`userInitiated`** read-only property of the -{{domxref("NavigateEvent")}} interface returns `true` if the navigation was initiated by the user (e.g. by clicking a link, submitting a form, or pressing the browser's "Back"/"Forward" buttons), or `false` otherwise. +{{domxref("NavigateEvent")}} interface returns `true` if the navigation was initiated by the user (e.g., by clicking a link, submitting a form, or pressing the browser's "Back"/"Forward" buttons), or `false` otherwise. > [!NOTE] > The table found at [Appendix: types of navigations](https://github.com/WICG/navigation-api#appendix-types-of-navigations) shows which navigation types are user-initiated. diff --git a/files/en-us/web/api/navigation/back/index.md b/files/en-us/web/api/navigation/back/index.md index 07b8225627064ef..3687c9a43be04bf 100644 --- a/files/en-us/web/api/navigation/back/index.md +++ b/files/en-us/web/api/navigation/back/index.md @@ -40,7 +40,7 @@ Either one of these promises rejects if the navigation has failed for some reaso ### Exceptions - `InvalidStateError` {{domxref("DOMException")}} - - : Thrown if the {{domxref("Navigation.currentEntry")}}'s {{domxref("NavigationHistoryEntry.index")}} value is -1 or 0, i.e. either the current {{domxref("Document")}} is not yet active, or the current history entry is the first one in the history, meaning that backwards navigation is not possible, or if the current {{domxref("Document")}} is unloading. + - : Thrown if the {{domxref("Navigation.currentEntry")}}'s {{domxref("NavigationHistoryEntry.index")}} value is -1 or 0, i.e., either the current {{domxref("Document")}} is not yet active, or the current history entry is the first one in the history, meaning that backwards navigation is not possible, or if the current {{domxref("Document")}} is unloading. ## Examples diff --git a/files/en-us/web/api/navigation/cangoback/index.md b/files/en-us/web/api/navigation/cangoback/index.md index 30e9a58b882a080..898bdd8e1c03120 100644 --- a/files/en-us/web/api/navigation/cangoback/index.md +++ b/files/en-us/web/api/navigation/cangoback/index.md @@ -13,7 +13,7 @@ browser-compat: api.Navigation.canGoBack The **`canGoBack`** read-only property of the {{domxref("Navigation")}} interface returns `true` if it is possible to navigate backwards in the navigation history -(i.e. the {{domxref("Navigation.currentEntry", "currentEntry")}} is +(i.e., the {{domxref("Navigation.currentEntry", "currentEntry")}} is not the first one in the history entry list), and `false` if it is not. diff --git a/files/en-us/web/api/navigation/cangoforward/index.md b/files/en-us/web/api/navigation/cangoforward/index.md index d7928e2f593b19b..80c1d332c88f31c 100644 --- a/files/en-us/web/api/navigation/cangoforward/index.md +++ b/files/en-us/web/api/navigation/cangoforward/index.md @@ -12,7 +12,7 @@ browser-compat: api.Navigation.canGoForward The **`canGoForward`** read-only property of the {{domxref("Navigation")}} interface returns `true` if it is possible to navigate forwards in the navigation history -(i.e. the {{domxref("Navigation.currentEntry", "currentEntry")}} is not the last one in the history entry list), +(i.e., the {{domxref("Navigation.currentEntry", "currentEntry")}} is not the last one in the history entry list), and `false` if it is not. ## Value diff --git a/files/en-us/web/api/navigation/currententrychange_event/index.md b/files/en-us/web/api/navigation/currententrychange_event/index.md index 7e38e6bd6d1db98..e903a922da8a5c7 100644 --- a/files/en-us/web/api/navigation/currententrychange_event/index.md +++ b/files/en-us/web/api/navigation/currententrychange_event/index.md @@ -14,11 +14,11 @@ The **`currententrychange`** event of the {{domxref("Navigation")}} interface is This event will fire for: -- Same-document navigations (e.g. {{domxref("Navigation.back", "back()")}} or {{domxref("Navigation.traverseTo", "traverseTo()")}}). +- Same-document navigations (e.g., {{domxref("Navigation.back", "back()")}} or {{domxref("Navigation.traverseTo", "traverseTo()")}}). -- Replacements (i.e. a {{domxref("Navigation.navigate", "navigate()")}} call with `history` set to `replace`). +- Replacements (i.e., a {{domxref("Navigation.navigate", "navigate()")}} call with `history` set to `replace`). -- Other calls that change the entry's state (e.g. {{domxref("Navigation.updateCurrentEntry", "updateCurrentEntry()")}}, or the {{domxref("History API", "History API", "", "nocode")}}'s {{domxref("History.replaceState()")}}). +- Other calls that change the entry's state (e.g., {{domxref("Navigation.updateCurrentEntry", "updateCurrentEntry()")}}, or the {{domxref("History API", "History API", "", "nocode")}}'s {{domxref("History.replaceState()")}}). This event fires after the navigation is committed, meaning that the visible URL has changed and the {{domxref("NavigationHistoryEntry")}} update has occurred. It is useful for migrating from usage of older API features like the {{domxref("Window/hashchange_event", "hashchange")}} or {{domxref("Window/popstate_event", "popstate")}} events. @@ -26,10 +26,10 @@ This event fires after the navigation is committed, meaning that the visible URL Use the event name in methods like {{domxref("EventTarget.addEventListener", "addEventListener()")}}, or set an event handler property. -```js -addEventListener("currententrychange", (event) => {}); +```js-nolint +addEventListener("currententrychange", (event) => { }) -oncurrententrychange = (event) => {}; +oncurrententrychange = (event) => { } ``` ## Event type diff --git a/files/en-us/web/api/navigation/forward/index.md b/files/en-us/web/api/navigation/forward/index.md index 7a6bd4ab02704b8..da2211f20ae5a25 100644 --- a/files/en-us/web/api/navigation/forward/index.md +++ b/files/en-us/web/api/navigation/forward/index.md @@ -40,7 +40,7 @@ Either one of these promises rejects if the navigation has failed for some reaso ### Exceptions - `InvalidStateError` {{domxref("DOMException")}} - - : Thrown if the {{domxref("Navigation.currentEntry")}}'s {{domxref("NavigationHistoryEntry.index")}} value is -1 or {{domxref("Navigation.entries", "navigation.entries().length - 1")}}, i.e. either the current {{domxref("Document")}} is not yet active, or the current history entry is the last one in the history, meaning that forwards navigation is not possible, or if the current {{domxref("Document")}} is unloading. + - : Thrown if the {{domxref("Navigation.currentEntry")}}'s {{domxref("NavigationHistoryEntry.index")}} value is -1 or {{domxref("Navigation.entries", "navigation.entries().length - 1")}}, i.e., either the current {{domxref("Document")}} is not yet active, or the current history entry is the last one in the history, meaning that forwards navigation is not possible, or if the current {{domxref("Document")}} is unloading. ## Examples diff --git a/files/en-us/web/api/navigation/index.md b/files/en-us/web/api/navigation/index.md index dfbca3393f45c6f..017b45cfe1ab356 100644 --- a/files/en-us/web/api/navigation/index.md +++ b/files/en-us/web/api/navigation/index.md @@ -13,7 +13,7 @@ The **`Navigation`** interface of the {{domxref("Navigation API", "Navigation AP It is accessed via the {{domxref("Window.navigation")}} property. -The Navigation API only exposes history entries created in the current browsing context that have the same origin as the current page (e.g. not navigations inside embedded {{htmlelement("iframe")}}s, or cross-origin navigations), providing an accurate list of all previous history entries just for your app. This makes traversing the history a much less fragile proposition than with the older {{domxref("History API", "History API", "", "nocode")}}. +The Navigation API only exposes history entries created in the current browsing context that have the same origin as the current page (e.g., not navigations inside embedded {{htmlelement("iframe")}}s, or cross-origin navigations), providing an accurate list of all previous history entries just for your app. This makes traversing the history a much less fragile proposition than with the older {{domxref("History API", "History API", "", "nocode")}}. {{InheritanceDiagram}} @@ -25,11 +25,11 @@ _Inherits properties from its parent, {{DOMxRef("EventTarget")}}._ - : Returns a {{domxref("NavigationActivation")}} object containing information about the most recent cross-document navigation, which "activated" this Document. - {{domxref("Navigation.canGoBack", "canGoBack")}} {{ReadOnlyInline}} {{Experimental_Inline}} - : Returns `true` if it is possible to navigate backwards in the navigation history - (i.e. the {{domxref("Navigation.currentEntry", "currentEntry")}} is not the first one in the history entry list), + (i.e., the {{domxref("Navigation.currentEntry", "currentEntry")}} is not the first one in the history entry list), and `false` if it is not. - {{domxref("Navigation.canGoForward", "canGoForward")}} {{ReadOnlyInline}} {{Experimental_Inline}} - : Returns `true` if it is possible to navigate forwards in the navigation history - (i.e. the {{domxref("Navigation.currentEntry", "currentEntry")}} is not the last one in the history entry list), + (i.e., the {{domxref("Navigation.currentEntry", "currentEntry")}} is not the last one in the history entry list), and `false` if it is not. - {{domxref("Navigation.currentEntry", "currentEntry")}} {{ReadOnlyInline}} {{Experimental_Inline}} - : Returns a {{domxref("NavigationHistoryEntry")}} object representing the location the user is currently diff --git a/files/en-us/web/api/navigation/navigate/index.md b/files/en-us/web/api/navigation/navigate/index.md index 190a822294e9982..27df308fa16c725 100644 --- a/files/en-us/web/api/navigation/navigate/index.md +++ b/files/en-us/web/api/navigation/navigate/index.md @@ -112,7 +112,7 @@ async function navigateHandler() { }).finished; // Update application state - // ... + // … } ``` diff --git a/files/en-us/web/api/navigation/navigate_event/index.md b/files/en-us/web/api/navigation/navigate_event/index.md index eda5b7925b664b7..9e1ca5bd4d3c097 100644 --- a/files/en-us/web/api/navigation/navigate_event/index.md +++ b/files/en-us/web/api/navigation/navigate_event/index.md @@ -16,10 +16,10 @@ The **`navigate`** event of the {{domxref("Navigation")}} interface is fired whe Use the event name in methods like {{domxref("EventTarget.addEventListener", "addEventListener()")}}, or set an event handler property. -```js -addEventListener("navigate", (event) => {}); +```js-nolint +addEventListener("navigate", (event) => { }) -onnavigate = (event) => {}; +onnavigate = (event) => { } ``` ## Event type diff --git a/files/en-us/web/api/navigation/navigateerror_event/index.md b/files/en-us/web/api/navigation/navigateerror_event/index.md index 13450da2be2c44c..596e38dab29915c 100644 --- a/files/en-us/web/api/navigation/navigateerror_event/index.md +++ b/files/en-us/web/api/navigation/navigateerror_event/index.md @@ -18,10 +18,10 @@ For example, if the network is down, any {{domxref("Window/fetch", "fetch()")}} Use the event name in methods like {{domxref("EventTarget.addEventListener", "addEventListener()")}}, or set an event handler property. -```js -addEventListener("navigateerror", (event) => {}); +```js-nolint +addEventListener("navigateerror", (event) => { }) -onnavigateerror = (event) => {}; +onnavigateerror = (event) => { } ``` ## Event type diff --git a/files/en-us/web/api/navigation/navigatesuccess_event/index.md b/files/en-us/web/api/navigation/navigatesuccess_event/index.md index 9f32e0686f92e36..b411c9a46ecfcd2 100644 --- a/files/en-us/web/api/navigation/navigatesuccess_event/index.md +++ b/files/en-us/web/api/navigation/navigatesuccess_event/index.md @@ -18,10 +18,10 @@ In the case of an intercepted navigation, this would occur after any promises re Use the event name in methods like {{domxref("EventTarget.addEventListener", "addEventListener()")}}, or set an event handler property. -```js -addEventListener("navigatesuccess", (event) => {}); +```js-nolint +addEventListener("navigatesuccess", (event) => { }) -onnavigatesuccess = (event) => {}; +onnavigatesuccess = (event) => { } ``` ## Event type diff --git a/files/en-us/web/api/navigation/reload/index.md b/files/en-us/web/api/navigation/reload/index.md index b1c9c092b583459..6c500be66dfb1eb 100644 --- a/files/en-us/web/api/navigation/reload/index.md +++ b/files/en-us/web/api/navigation/reload/index.md @@ -16,6 +16,7 @@ The **`reload()`** method of the ## Syntax ```js-nolint +reload() reload(options) ``` @@ -56,7 +57,7 @@ async function handleReload() { }).finished; // Update application state - // ... + // … } ``` @@ -69,7 +70,7 @@ async function handleReload() { }).finished; // Update application state - // ... + // … } ``` diff --git a/files/en-us/web/api/navigation/updatecurrententry/index.md b/files/en-us/web/api/navigation/updatecurrententry/index.md index ce6c72e956ee8b7..bff1655473fad10 100644 --- a/files/en-us/web/api/navigation/updatecurrententry/index.md +++ b/files/en-us/web/api/navigation/updatecurrententry/index.md @@ -34,7 +34,7 @@ None (`undefined`). - `DataCloneError` {{domxref("DOMException")}} - : Thrown if the `state` parameter had values included in it that are not structured-cloneable. - `InvalidStateError` {{domxref("DOMException")}} - - : Thrown if the {{domxref("Navigation.currentEntry")}} is `null`, i.e. there is no current history entry. This could occur for example if the current page is `about:blank`. + - : Thrown if the {{domxref("Navigation.currentEntry")}} is `null`, i.e., there is no current history entry. This could occur for example if the current page is `about:blank`. ## Examples diff --git a/files/en-us/web/api/navigation_api/index.md b/files/en-us/web/api/navigation_api/index.md index b1247206db12994..676a35e4f596d1f 100644 --- a/files/en-us/web/api/navigation_api/index.md +++ b/files/en-us/web/api/navigation_api/index.md @@ -29,7 +29,7 @@ The `navigation` interface has several associated events, the most notable being The `NavigationEvent` object also provides two methods: - {{domxref("NavigateEvent.intercept", "intercept()")}} takes as an argument a callback handler function returning a promise. It allows you to control what happens when the navigation is initiated. For example, in the case of an SPA, it can be used to load relevant new content into the UI based on the path of the URL navigated to. -- {{domxref("NavigateEvent.scroll", "scroll()")}} allows you to manually initiate the browser's scroll behavior (e.g. to a fragment identifier in the URL), if it makes sense for your code, rather than waiting for the browser to handle it automatically. +- {{domxref("NavigateEvent.scroll", "scroll()")}} allows you to manually initiate the browser's scroll behavior (e.g., to a fragment identifier in the URL), if it makes sense for your code, rather than waiting for the browser to handle it automatically. Once a navigation is initiated, and your `intercept()` handler is called, a {{domxref("NavigationTransition")}} object instance is created (accessible via {{domxref("Navigation.transition")}}), which can be used to track the process of the ongoing navigation. @@ -49,7 +49,7 @@ When the `intercept()` handler function's promise fulfills, the `Navigation` obj As the user navigates through your application, each new location navigated to results in the creation of a navigation history entry. Each history entry is represented by a distinct {{domxref("NavigationHistoryEntry")}} object instance. These contain several properties such as the entry's key, URL, and state information. You can get the entry that the user is currently on right now using {{domxref("Navigation.currentEntry")}}, and an array of all existing history entries using {{domxref("Navigation.entries()")}}. Each `NavigationHistoryEntry` object has a {{domxref("NavigationHistoryEntry/dispose_event", "dispose")}} event, which fires when the entry is no longer part of the browser history. For example, if the user navigates back three times, then navigates forward to somewhere else, those three history entries will be disposed of. > [!NOTE] -> The Navigation API only exposes history entries created in the current browsing context that have the same origin as the current page (e.g. not navigations inside embedded {{htmlelement("iframe")}}s, or cross-origin navigations), providing an accurate list of all previous history entries just for your app. This makes traversing the history a much less fragile proposition than with the older {{domxref("History API", "", "", "nocode")}}. +> The Navigation API only exposes history entries created in the current browsing context that have the same origin as the current page (e.g., not navigations inside embedded {{htmlelement("iframe")}}s, or cross-origin navigations), providing an accurate list of all previous history entries just for your app. This makes traversing the history a much less fragile proposition than with the older {{domxref("History API", "", "", "nocode")}}. The `Navigation` object contains all the methods you'll need to update and traverse through the navigation history: diff --git a/files/en-us/web/api/navigationcurrententrychangeevent/index.md b/files/en-us/web/api/navigationcurrententrychangeevent/index.md index 7f5ea44b64df230..1e97b8e6a93f726 100644 --- a/files/en-us/web/api/navigationcurrententrychangeevent/index.md +++ b/files/en-us/web/api/navigationcurrententrychangeevent/index.md @@ -11,7 +11,7 @@ browser-compat: api.NavigationCurrentEntryChangeEvent The **`NavigationCurrentEntryChangeEvent`** interface of the {{domxref("Navigation API", "Navigation API", "", "nocode")}} is the event object for the {{domxref("Navigation/currententrychange_event", "currententrychange")}} event, which fires when the {{domxref("Navigation.currentEntry")}} has changed. -This event will fire for same-document navigations (e.g. {{domxref("Navigation.back", "back()")}} or {{domxref("Navigation.traverseTo", "traverseTo()")}}), replacements (i.e. a {{domxref("Navigation.navigate", "navigate()")}} call with `history` set to `replace`), or other calls that change the entry's state (e.g. {{domxref("Navigation.updateCurrentEntry", "updateCurrentEntry()")}}, or the {{domxref("History API", "History API", "", "nocode")}}'s {{domxref("History.replaceState()")}}). +This event will fire for same-document navigations (e.g., {{domxref("Navigation.back", "back()")}} or {{domxref("Navigation.traverseTo", "traverseTo()")}}), replacements (i.e., a {{domxref("Navigation.navigate", "navigate()")}} call with `history` set to `replace`), or other calls that change the entry's state (e.g., {{domxref("Navigation.updateCurrentEntry", "updateCurrentEntry()")}}, or the {{domxref("History API", "History API", "", "nocode")}}'s {{domxref("History.replaceState()")}}). This event fires after the navigation is committed, meaning that the visible URL has changed and the {{domxref("NavigationHistoryEntry")}} update has occurred. It is useful for migrating from usage of older API features like the {{domxref("Window/hashchange_event", "hashchange")}} or {{domxref("Window/popstate_event", "popstate")}} events. diff --git a/files/en-us/web/api/navigationdestination/getstate/index.md b/files/en-us/web/api/navigationdestination/getstate/index.md index 3ece0f451aaf984..c0ab5e802b60689 100644 --- a/files/en-us/web/api/navigationdestination/getstate/index.md +++ b/files/en-us/web/api/navigationdestination/getstate/index.md @@ -11,7 +11,7 @@ browser-compat: api.NavigationDestination.getState {{APIRef("Navigation API")}}{{SeeCompatTable}} The **`getState()`** method of the -{{domxref("NavigationDestination")}} interface returns a clone of the developer-supplied state associated with the destination {{domxref("NavigationHistoryEntry")}}, or navigation operation (e.g. {{domxref("Navigation.navigate()", "navigate()")}}) as appropriate. +{{domxref("NavigationDestination")}} interface returns a clone of the developer-supplied state associated with the destination {{domxref("NavigationHistoryEntry")}}, or navigation operation (e.g., {{domxref("Navigation.navigate()", "navigate()")}}) as appropriate. ## Syntax diff --git a/files/en-us/web/api/navigationdestination/index.md b/files/en-us/web/api/navigationdestination/index.md index 755a568da403932..f72eb75c3df67ec 100644 --- a/files/en-us/web/api/navigationdestination/index.md +++ b/files/en-us/web/api/navigationdestination/index.md @@ -31,7 +31,7 @@ It is accessed via the {{domxref("NavigateEvent.destination")}} property. ## Instance methods - {{domxref("NavigationDestination.getState", "getState()")}} {{Experimental_Inline}} - - : Returns a clone of the available state associated with the destination {{domxref("NavigationHistoryEntry")}}, or navigation operation (e.g. {{domxref("Navigation.navigate()", "navigate()")}}) as appropriate. + - : Returns a clone of the available state associated with the destination {{domxref("NavigationHistoryEntry")}}, or navigation operation (e.g., {{domxref("Navigation.navigate()", "navigate()")}}) as appropriate. ## Examples diff --git a/files/en-us/web/api/navigationdestination/key/index.md b/files/en-us/web/api/navigationdestination/key/index.md index e3e71c0430f24e2..bce46baa95dc19e 100644 --- a/files/en-us/web/api/navigationdestination/key/index.md +++ b/files/en-us/web/api/navigationdestination/key/index.md @@ -13,7 +13,7 @@ browser-compat: api.NavigationDestination.key The **`key`** read-only property of the {{domxref("NavigationDestination")}} interface returns the {{domxref("NavigationHistoryEntry.key", "key")}} value of the destination {{domxref("NavigationHistoryEntry")}} if the {{domxref("NavigateEvent.navigationType")}} is `traverse`, or an empty string otherwise. -The `key` is a unique, UA-generated value that represents the history entry's slot in the history entries list, used to navigate to this place in the history via {{domxref("Navigation.traverseTo()")}}. It will be reused by other entries that replace the entry in the list (i.e. if the {{domxref("NavigateEvent.navigationType")}} is `replace`). +The `key` is a unique, UA-generated value that represents the history entry's slot in the history entries list, used to navigate to this place in the history via {{domxref("Navigation.traverseTo()")}}. It will be reused by other entries that replace the entry in the list (i.e., if the {{domxref("NavigateEvent.navigationType")}} is `replace`). ## Value diff --git a/files/en-us/web/api/navigationhistoryentry/dispose_event/index.md b/files/en-us/web/api/navigationhistoryentry/dispose_event/index.md index d2f6569029f7f17..7ff9d6e3795c5ce 100644 --- a/files/en-us/web/api/navigationhistoryentry/dispose_event/index.md +++ b/files/en-us/web/api/navigationhistoryentry/dispose_event/index.md @@ -22,10 +22,10 @@ Disposal occurs when: Use the event name in methods like {{domxref("EventTarget.addEventListener", "addEventListener()")}}, or set an event handler property. -```js -addEventListener("dispose", (event) => {}); +```js-nolint +addEventListener("dispose", (event) => { }) -ondispose = (event) => {}; +ondispose = (event) => { } ``` ## Event type diff --git a/files/en-us/web/api/navigationhistoryentry/index.md b/files/en-us/web/api/navigationhistoryentry/index.md index 2e8c1c095ac485f..20ab86106b22eb5 100644 --- a/files/en-us/web/api/navigationhistoryentry/index.md +++ b/files/en-us/web/api/navigationhistoryentry/index.md @@ -13,7 +13,7 @@ The **`NavigationHistoryEntry`** interface of the {{domxref("Navigation API", "N These objects are commonly accessed via the {{domxref("Navigation.currentEntry")}} property and {{domxref("Navigation.entries()")}} method. -The Navigation API only exposes history entries created in the current browsing context that have the same origin as the current page (e.g. not navigations inside embedded {{htmlelement("iframe")}}s, or cross-origin navigations), providing an accurate list of all previous history entries just for your app. This makes traversing the history a much less fragile proposition than with the older {{domxref("History API", "History API", "", "nocode")}}. +The Navigation API only exposes history entries created in the current browsing context that have the same origin as the current page (e.g., not navigations inside embedded {{htmlelement("iframe")}}s, or cross-origin navigations), providing an accurate list of all previous history entries just for your app. This makes traversing the history a much less fragile proposition than with the older {{domxref("History API", "History API", "", "nocode")}}. {{InheritanceDiagram}} diff --git a/files/en-us/web/api/navigator/buildid/index.md b/files/en-us/web/api/navigator/buildid/index.md index 653ef12ade1adca..f6c09ea4a98ab62 100644 --- a/files/en-us/web/api/navigator/buildid/index.md +++ b/files/en-us/web/api/navigator/buildid/index.md @@ -10,7 +10,7 @@ browser-compat: api.Navigator.buildID {{ApiRef("HTML DOM")}}{{Non-standard_Header}} -Returns the build identifier of the browser. In modern browsers this property now returns a fixed timestamp as a privacy measure, e.g. `20181001000000` in Firefox 64 onwards. +Returns the build identifier of the browser. In modern browsers this property now returns a fixed timestamp as a privacy measure, e.g., `20181001000000` in Firefox 64 onwards. ## Value diff --git a/files/en-us/web/api/navigator/canshare/index.md b/files/en-us/web/api/navigator/canshare/index.md index 9e01ea7a5831bb3..6f6e803d3585caf 100644 --- a/files/en-us/web/api/navigator/canshare/index.md +++ b/files/en-us/web/api/navigator/canshare/index.md @@ -17,7 +17,7 @@ The method returns `false` if the data cannot be _validated_. Reasons the data m - Files are specified but the implementation does not support file sharing. - Sharing the specified data would be considered a "hostile share" by the user-agent. -The [Web Share API](/en-US/docs/Web/API/Web_Share_API) is gated by the [web-share](/en-US/docs/Web/HTTP/Headers/Permissions-Policy/web-share) permission policy. +The [Web Share API](/en-US/docs/Web/API/Web_Share_API) is gated by the [web-share](/en-US/docs/Web/HTTP/Reference/Headers/Permissions-Policy/web-share) permission policy. The `canShare()` method will return `false` if the permission is supported but has not been granted. ## Syntax diff --git a/files/en-us/web/api/navigator/cookieenabled/index.md b/files/en-us/web/api/navigator/cookieenabled/index.md index 3ebb743258ac194..cb0d42d3e011c93 100644 --- a/files/en-us/web/api/navigator/cookieenabled/index.md +++ b/files/en-us/web/api/navigator/cookieenabled/index.md @@ -17,7 +17,7 @@ The property is read-only. A boolean. > [!NOTE] -> Web browsers may prevent writing certain cookies in certain scenarios. For example, Chrome-based browsers, as well as some experimental version of Firefox, does not allow creating cookies with [`SameSite=None`](/en-US/docs/Web/HTTP/Headers/Set-Cookie#samesitesamesite-value) attribute, unless they are created over HTTPS and with `Secure` attribute. +> Web browsers may prevent writing certain cookies in certain scenarios. For example, Chrome-based browsers, as well as some experimental version of Firefox, does not allow creating cookies with [`SameSite=None`](/en-US/docs/Web/HTTP/Reference/Headers/Set-Cookie#samesitesamesite-value) attribute, unless they are created over HTTPS and with `Secure` attribute. ## Examples diff --git a/files/en-us/web/api/navigator/credentials/index.md b/files/en-us/web/api/navigator/credentials/index.md index bc4030688076bb9..408e6afefd31ac3 100644 --- a/files/en-us/web/api/navigator/credentials/index.md +++ b/files/en-us/web/api/navigator/credentials/index.md @@ -19,10 +19,10 @@ A {{domxref("CredentialsContainer")}} object. ```js if ("credentials" in navigator) { navigator.credentials.get({ password: true }).then((creds) => { - //Do something with the credentials. + // Do something with the credentials. }); } else { - //Handle sign-in the way you did before. + // Handle sign-in the way you did before. } ``` diff --git a/files/en-us/web/api/navigator/deprecatedreplaceinurn/index.md b/files/en-us/web/api/navigator/deprecatedreplaceinurn/index.md index 756e4481fedef80..0037a90ebb496ad 100644 --- a/files/en-us/web/api/navigator/deprecatedreplaceinurn/index.md +++ b/files/en-us/web/api/navigator/deprecatedreplaceinurn/index.md @@ -12,9 +12,9 @@ browser-compat: api.Navigator.deprecatedReplaceInURN The **`deprecatedReplaceInURN()`** method of the {{domxref("Navigator")}} interface substitutes specified strings inside the mapped URL corresponding to a given opaque URN or `FencedFrameConfig`'s internal `url` property. -A `FencedFrameConfig` or opaque URN is returned from a source such as the [Protected Audience API](https://developers.google.com/privacy-sandbox/private-advertising/protected-audience) `runAdAuction()` method, and then set as the value of {{domxref("HTMLFencedFrameElement.config")}}. The content URL associated with the `FencedFrameConfig` or opaque URN is mapped to it internally by the browser, and can't be accessed via JavaScript. +A `FencedFrameConfig` or opaque URN is returned from a source such as the [Protected Audience API](https://privacysandbox.google.com/private-advertising/protected-audience) `runAdAuction()` method, and then set as the value of {{domxref("HTMLFencedFrameElement.config")}}. The content URL associated with the `FencedFrameConfig` or opaque URN is mapped to it internally by the browser, and can't be accessed via JavaScript. -However, you may wish to substitute parts of that internal URL. This is a common approach for passing runtime data into ad creatives to use in rendering. `deprecatedReplaceInURN()` has been made available as a temporary measure to enable that substitution for fenced frame URLs, helping ad tech providers to migrate existing implementations across to [privacy sandbox](https://developers.google.com/privacy-sandbox) APIs. +However, you may wish to substitute parts of that internal URL. This is a common approach for passing runtime data into ad creatives to use in rendering. `deprecatedReplaceInURN()` has been made available as a temporary measure to enable that substitution for fenced frame URLs, helping ad tech providers to migrate existing implementations across to [privacy sandbox](https://privacysandbox.google.com/) APIs. ## Syntax diff --git a/files/en-us/web/api/navigator/deviceposture/index.md b/files/en-us/web/api/navigator/deviceposture/index.md index 1b15f78826708aa..d0c44f3da53ab01 100644 --- a/files/en-us/web/api/navigator/deviceposture/index.md +++ b/files/en-us/web/api/navigator/deviceposture/index.md @@ -8,7 +8,7 @@ status: browser-compat: api.Navigator.devicePosture --- -{{APIRef("WebdevicePosture API")}}{{SeeCompatTable}} +{{APIRef("Device Posture API")}}{{SeeCompatTable}} The **`Navigator.devicePosture`** read-only property returns the browser's {{domxref("DevicePosture")}} object, which allows developers to query the device's current posture (that is, whether the viewport is in a flat or folded state) and run code in response to posture changes. diff --git a/files/en-us/web/api/navigator/donottrack/index.md b/files/en-us/web/api/navigator/donottrack/index.md index 326ef5ae23fa7f5..09337a61364783c 100644 --- a/files/en-us/web/api/navigator/donottrack/index.md +++ b/files/en-us/web/api/navigator/donottrack/index.md @@ -13,7 +13,7 @@ browser-compat: api.Navigator.doNotTrack The **`Navigator.doNotTrack`** property returns the user's Do Not Track setting, which indicates whether the user is requesting websites and advertisers to not track them. -The value of the property reflects that of the {{httpheader("DNT")}} HTTP header, i.e. values of `"1"`, `"0"`, or `null`. +The value of the property reflects that of the {{httpheader("DNT")}} HTTP header, i.e., values of `"1"`, `"0"`, or `null`. The whole DNT (Do Not Track) specification has been discontinued. The mechanism design was flawed, because it was a cooperative feature between users, websites, and browsers. The idea is that the user tells the _website_ to not track them, and the _website_ would comply. However, there is no strict enforcement of this policy, so advertisement websites ignored the DNT header and tracked users anyway. The feature is therefore useless. Moreover, it is harmful as it leaves more user [fingerprint](/en-US/docs/Glossary/Fingerprinting) in the header, which can be used to track users even more. diff --git a/files/en-us/web/api/navigator/getautoplaypolicy/index.md b/files/en-us/web/api/navigator/getautoplaypolicy/index.md index ef8067ead21a3d9..ba9a45c6b0d8d1a 100644 --- a/files/en-us/web/api/navigator/getautoplaypolicy/index.md +++ b/files/en-us/web/api/navigator/getautoplaypolicy/index.md @@ -81,7 +81,7 @@ Once the user has interacted with the page/site, on some browsers individual ite ## Description "Autoplay" refers to any feature that causes content to begin to play without the user specifically requesting that playback begin. -This includes the `autoplay` attribute in the HTML [`<video>`](/en-US/docs/Web/HTML/Element/video#autoplay) and [`<audio>`](/en-US/docs/Web/HTML/Element/audio#autoplay) elements, and using JavaScript code to start playback without any user interaction. +This includes the `autoplay` attribute in the HTML [`<video>`](/en-US/docs/Web/HTML/Reference/Elements/video#autoplay) and [`<audio>`](/en-US/docs/Web/HTML/Reference/Elements/audio#autoplay) elements, and using JavaScript code to start playback without any user interaction. User agents commonly block autoplay, or only allow inaudible content to autoplay, because unexpected sounds when a page first loads can result in a jarring and unpleasant user experience. The mechanisms used to determine whether content can autoplay or not, or only play for inaudible content, differ between user agents. @@ -160,7 +160,7 @@ If the autoplay policy is "allowed-muted", the video will be muted to allow it t #### HTML -The HTML below has a `div` element that is used as a reporting log, and also displays a [`<video>`](/en-US/docs/Web/HTML/Element/video) that has the [`autoplay`](/en-US/docs/Web/API/HTMLMediaElement/autoplay) attribute. +The HTML below has a `div` element that is used as a reporting log, and also displays a [`<video>`](/en-US/docs/Web/HTML/Reference/Elements/video) that has the [`autoplay`](/en-US/docs/Web/API/HTMLMediaElement/autoplay) attribute. This should not be muted by default, and should play automatically if autoplay is not blocked. ```html @@ -233,7 +233,7 @@ If the autoplay policy is "allowed-muted", the video will be muted to allow it t #### HTML -The HTML below has a `div` element that is used as a reporting log, and also displays a [`<video>`](/en-US/docs/Web/HTML/Element/video) that has the [`autoplay`](/en-US/docs/Web/API/HTMLMediaElement/autoplay) attribute. +The HTML below has a `div` element that is used as a reporting log, and also displays a [`<video>`](/en-US/docs/Web/HTML/Reference/Elements/video) that has the [`autoplay`](/en-US/docs/Web/API/HTMLMediaElement/autoplay) attribute. This should not be muted by default, and should play automatically if autoplay is not blocked. ```html @@ -269,7 +269,7 @@ if (!navigator.getAutoplayPolicy) { "navigator.getAutoplayPolicy() not supported. It may or may not autoplay, depending on the browser!"; } else { // Here we pass in the HTMLVideoElement to check - log.textContent = `navigator.getAutoplayPolicy(video) == ${navigator.getAutoplayPolicy( + log.textContent = `navigator.getAutoplayPolicy(video) === ${navigator.getAutoplayPolicy( "mediaelement", )}`; diff --git a/files/en-us/web/api/navigator/getbattery/index.md b/files/en-us/web/api/navigator/getbattery/index.md index 8d989f126c9b931..8c255f007a3410d 100644 --- a/files/en-us/web/api/navigator/getbattery/index.md +++ b/files/en-us/web/api/navigator/getbattery/index.md @@ -35,7 +35,7 @@ A {{JSxRef("Promise")}} that fulfills with a {{DOMxRef("BatteryManager")}} objec - `NotAllowedError` {{domxref("DOMException")}} - - : Use of this feature was blocked by a [Permissions Policy](/en-US/docs/Web/HTTP/Permissions_Policy). + - : Use of this feature was blocked by a [Permissions Policy](/en-US/docs/Web/HTTP/Guides/Permissions_Policy). - `SecurityError` {{domxref("DOMException")}} - : The User Agent does not expose battery information to insecure contexts and this method was called from an insecure context. diff --git a/files/en-us/web/api/navigator/getgamepads/index.md b/files/en-us/web/api/navigator/getgamepads/index.md index 6688d2f355893a4..58cad291fc11803 100644 --- a/files/en-us/web/api/navigator/getgamepads/index.md +++ b/files/en-us/web/api/navigator/getgamepads/index.md @@ -31,7 +31,7 @@ An {{jsxref("Array")}} of {{domxref("Gamepad")}} objects, eventually empty. ### Exceptions - `SecurityError` {{domxref("DOMException")}} - - : Use of this feature was blocked by a [Permissions Policy](/en-US/docs/Web/HTTP/Permissions_Policy). + - : Use of this feature was blocked by a [Permissions Policy](/en-US/docs/Web/HTTP/Guides/Permissions_Policy). ## Examples diff --git a/files/en-us/web/api/navigator/getinstalledrelatedapps/index.md b/files/en-us/web/api/navigator/getinstalledrelatedapps/index.md index 28336fd90f81814..b43856df49e8d16 100644 --- a/files/en-us/web/api/navigator/getinstalledrelatedapps/index.md +++ b/files/en-us/web/api/navigator/getinstalledrelatedapps/index.md @@ -27,7 +27,7 @@ To associate the invoking web app with a platform-specific app or PWA, two thing Defining the relationship is done in a different way depending on the type of app: - An Android app does this via the [Digital Asset Links system](https://developers.google.com/digital-asset-links/v1/getting-started). -- A Windows UWP app does this via [URI Handlers](https://learn.microsoft.com/en-us/windows/uwp/launch-resume/web-to-app-linking). +- A Windows UWP app does this via [URI Handlers](https://learn.microsoft.com/en-us/windows/apps/develop/launch/web-to-app-linking). - A PWA does this via: - A self-defining entry inside its own `related_applications` manifest member in the case of a PWA checking if it is installed on the underlying platform. - An `assetlinks.json` file in its [`/.well-known/`](https://datatracker.ietf.org/doc/html/rfc5785) directory in the case of an app outside the scope of the PWA checking whether it is installed. diff --git a/files/en-us/web/api/navigator/gpu/index.md b/files/en-us/web/api/navigator/gpu/index.md index 33133cfb961b67e..769ffa58d42a125 100644 --- a/files/en-us/web/api/navigator/gpu/index.md +++ b/files/en-us/web/api/navigator/gpu/index.md @@ -31,7 +31,7 @@ async function init() { const device = await adapter.requestDevice(); - //... + // … } ``` diff --git a/files/en-us/web/api/navigator/hid/index.md b/files/en-us/web/api/navigator/hid/index.md index d216c37cdbb00ae..abbab0a4b098eb4 100644 --- a/files/en-us/web/api/navigator/hid/index.md +++ b/files/en-us/web/api/navigator/hid/index.md @@ -13,7 +13,7 @@ browser-compat: api.Navigator.hid The **`Navigator.hid`** read-only property returns an {{domxref("HID")}} object providing methods for accessing HID device connections and events that fire when the user agent connects to or disconnects from a device. -Where a defined [Permissions Policy](/en-US/docs/Web/HTTP/Permissions_Policy) blocks WebHID usage, the `Navigator.hid` property will not be available. +Where a defined [Permissions Policy](/en-US/docs/Web/HTTP/Guides/Permissions_Policy) blocks WebHID usage, the `Navigator.hid` property will not be available. ## Value diff --git a/files/en-us/web/api/navigator/index.md b/files/en-us/web/api/navigator/index.md index cdb41641ed2595f..7a52edd5eea1775 100644 --- a/files/en-us/web/api/navigator/index.md +++ b/files/en-us/web/api/navigator/index.md @@ -51,7 +51,7 @@ _Doesn't inherit any properties._ - : Returns an array of strings representing the languages known to the user, by order of preference. - {{domxref("Navigator.locks")}} {{ReadOnlyInline}} {{SecureContext_Inline}} - : Returns a {{domxref("LockManager")}} object that provides methods for requesting a new {{domxref('Lock')}} object and querying for an existing {{domxref('Lock')}} object. -- {{domxref("Navigator.login")}} {{ReadOnlyInline}} {{Experimental_Inline}} {{SecureContext_Inline}} +- {{domxref("Navigator.login")}} {{ReadOnlyInline}} {{SecureContext_Inline}} - : Provides access to the browser's {{domxref("NavigatorLogin")}} object, which a federated identity provider (IdP) can use to set a user's login status when they sign into or out of the IdP. See [Federated Credential Management (FedCM) API](/en-US/docs/Web/API/FedCM_API) for more details. - {{domxref("Navigator.maxTouchPoints")}} {{ReadOnlyInline}} - : Returns the maximum number of simultaneous touch contact points are supported by the current device. @@ -99,7 +99,7 @@ _Doesn't inherit any properties._ ### Non-standard properties - {{domxref("Navigator.buildID")}} {{ReadOnlyInline}} {{Non-standard_Inline}} - - : Returns the build identifier of the browser. In modern browsers this property now returns a fixed timestamp as a privacy measure, e.g. `20181001000000` in Firefox 64 onwards. + - : Returns the build identifier of the browser. In modern browsers this property now returns a fixed timestamp as a privacy measure, e.g., `20181001000000` in Firefox 64 onwards. - {{domxref("Navigator.globalPrivacyControl")}} {{ReadOnlyInline}} {{Experimental_Inline}} - : Returns a boolean indicating a user's consent to their information being shared or sold. - {{domxref("Navigator.standalone")}} {{Non-standard_Inline}} @@ -143,7 +143,7 @@ _Doesn't inherit any method._ - {{domxref("Navigator.clearAppBadge()")}} {{SecureContext_Inline}} - : Clears a badge on the current app's icon and returns a {{jsxref("Promise")}} that resolves with {{jsxref("undefined")}}. - {{domxref("Navigator.deprecatedReplaceInURN()")}} {{Experimental_Inline}} - - : Substitutes specified strings inside the mapped URL corresponding to a given opaque URN or `FencedFrameConfig`'s internal `url` property. This method has been made available as a temporary measure (hence "deprecated") to enable that substitution for fenced frame URLs, helping ad tech providers to migrate existing implementations across to [privacy sandbox](https://developers.google.com/privacy-sandbox) APIs. + - : Substitutes specified strings inside the mapped URL corresponding to a given opaque URN or `FencedFrameConfig`'s internal `url` property. This method has been made available as a temporary measure (hence "deprecated") to enable that substitution for fenced frame URLs, helping ad tech providers to migrate existing implementations across to [privacy sandbox](https://privacysandbox.google.com/) APIs. - {{domxref("Navigator.getAutoplayPolicy()")}} {{Experimental_Inline}} - : Returns a value indicating whether the specified media element, audio context, or media feature "type" is allowed to autoplay. - {{domxref("Navigator.getBattery()")}} {{SecureContext_Inline}} diff --git a/files/en-us/web/api/navigator/ink/index.md b/files/en-us/web/api/navigator/ink/index.md index 62df5f01d809bb4..4451d3b7bfb0960 100644 --- a/files/en-us/web/api/navigator/ink/index.md +++ b/files/en-us/web/api/navigator/ink/index.md @@ -23,7 +23,7 @@ async function inkInit() { const ink = navigator.ink; let presenter = await ink.requestPresenter({ presentationArea: canvas }); - //... + // … } ``` diff --git a/files/en-us/web/api/navigator/login/index.md b/files/en-us/web/api/navigator/login/index.md index 56641f07594108d..6753c1698f2b0a5 100644 --- a/files/en-us/web/api/navigator/login/index.md +++ b/files/en-us/web/api/navigator/login/index.md @@ -3,12 +3,10 @@ title: "Navigator: login property" short-title: login slug: Web/API/Navigator/login page-type: web-api-instance-property -status: - - experimental browser-compat: api.Navigator.login --- -{{securecontext_header}}{{APIRef("FedCM API")}}{{SeeCompatTable}} +{{securecontext_header}}{{APIRef("FedCM API")}} The **`login`** read-only property of the {{domxref("Navigator")}} interface provides access to the browser's {{domxref("NavigatorLogin")}} object, which a federated identity provider (IdP) can use to set its login status when a user signs into or out of the IdP. diff --git a/files/en-us/web/api/navigator/presentation/index.md b/files/en-us/web/api/navigator/presentation/index.md index 8c8e934115c37bb..a79dedcc8e3bc34 100644 --- a/files/en-us/web/api/navigator/presentation/index.md +++ b/files/en-us/web/api/navigator/presentation/index.md @@ -16,6 +16,21 @@ returns a reference to {{DOMxRef("Presentation")}} object. A reference to {{DOMxRef("Presentation")}} object. +## Examples + +Currently, the `navigator.presentation` property is most useful for feature checking, and, for the receiving user agent, to access the {{domxref("PresentationReceiver")}}. + +```js +// Check if the Presentation API is available in the current browser +if ("presentation" in navigator) { + footer.textContent = navigator.presentation.receiver + ? "Receiving presentation" + : "(idle)"; +} else { + console.error("Presentation API is not available in this browser."); +} +``` + ## Specifications {{Specifications}} diff --git a/files/en-us/web/api/navigator/registerprotocolhandler/index.md b/files/en-us/web/api/navigator/registerprotocolhandler/index.md index b95ba189ab7ae0a..f868c9aa811cbff 100644 --- a/files/en-us/web/api/navigator/registerprotocolhandler/index.md +++ b/files/en-us/web/api/navigator/registerprotocolhandler/index.md @@ -14,7 +14,7 @@ For example, this API lets webmail sites open `mailto:` URLs, or VoIP sites open To register a protocol handler, a website calls `registerProtocolHandler()`, passing in the protocol to register and a template URL. -When the user activates a link that uses the registered protocol, the browser will insert the [`href`](/en-US/docs/Web/HTML/Element/a#href) from the activated link into the URL template supplied during handler registration, and navigate the current page to the resulting URL. +When the user activates a link that uses the registered protocol, the browser will insert the [`href`](/en-US/docs/Web/HTML/Reference/Elements/a#href) from the activated link into the URL template supplied during handler registration, and navigate the current page to the resulting URL. The browser may ask the user to confirm that they want the page to be allowed to handle the protocol, either when the protocol is registered or when the user activates the link. diff --git a/files/en-us/web/api/navigator/requestmediakeysystemaccess/index.md b/files/en-us/web/api/navigator/requestmediakeysystemaccess/index.md index 40506d0b0d28700..91e4b12195a0055 100644 --- a/files/en-us/web/api/navigator/requestmediakeysystemaccess/index.md +++ b/files/en-us/web/api/navigator/requestmediakeysystemaccess/index.md @@ -108,7 +108,7 @@ In case of an error, the returned {{jsxref('Promise')}} is rejected with a {{dom - `NotSupportedError` {{domxref("DOMException")}} - : Either the specified `keySystem` isn't supported by the platform or the browser, or none of the configurations specified by `supportedConfigurations` can be satisfied (if, for example, none of the `codecs` specified in `contentType` are available). - `SecurityError` {{domxref("DOMException")}} - - : Use of this feature was blocked by [`Permissions-Policy: encrypted-media`](/en-US/docs/Web/HTTP/Headers/Permissions-Policy/encrypted-media). + - : Use of this feature was blocked by [`Permissions-Policy: encrypted-media`](/en-US/docs/Web/HTTP/Reference/Headers/Permissions-Policy/encrypted-media). - {{jsxref("TypeError")}} - : Either `keySystem` is an empty string or the `supportedConfigurations` array is empty. diff --git a/files/en-us/web/api/navigator/requestmidiaccess/index.md b/files/en-us/web/api/navigator/requestmidiaccess/index.md index 5232badc4cc26ee..3b44fc7c32bcdf9 100644 --- a/files/en-us/web/api/navigator/requestmidiaccess/index.md +++ b/files/en-us/web/api/navigator/requestmidiaccess/index.md @@ -43,14 +43,14 @@ A {{jsxref('Promise')}} that resolves with a [`MIDIAccess`](/en-US/docs/Web/API/ - `NotSupportedError` {{domxref("DOMException")}} - : Thrown if the feature or options are not supported by the system. - `SecurityError` {{domxref("DOMException")}} - - : Thrown if the user or system denies the application from creating a [MIDIAccess](/en-US/docs/Web/API/MIDIAccess) object with the requested options, or if the document is not allowed to use the feature (for example, because of a [Permission Policy](/en-US/docs/Web/HTTP/Permissions_Policy), or because the user previously denied a permission request). + - : Thrown if the user or system denies the application from creating a [MIDIAccess](/en-US/docs/Web/API/MIDIAccess) object with the requested options, or if the document is not allowed to use the feature (for example, because of a [Permission Policy](/en-US/docs/Web/HTTP/Guides/Permissions_Policy), or because the user previously denied a permission request). ## Security requirements Access to the API is subject to the following constraints: - The method must be called in a [secure context](/en-US/docs/Web/Security/Secure_Contexts). -- Access may be gated by the [`midi`](/en-US/docs/Web/HTTP/Headers/Permissions-Policy/midi) HTTP [Permission Policy](/en-US/docs/Web/HTTP/Permissions_Policy). +- Access may be gated by the [`midi`](/en-US/docs/Web/HTTP/Reference/Headers/Permissions-Policy/midi) HTTP [Permission Policy](/en-US/docs/Web/HTTP/Guides/Permissions_Policy). - The user must explicitly grant permission to use the API though a user-agent specific mechanism, or have previously granted permission. Note that if access is denied by a permission policy it cannot be granted by a user permission. diff --git a/files/en-us/web/api/navigator/sendbeacon/index.md b/files/en-us/web/api/navigator/sendbeacon/index.md index 7acedde7899be49..9ff0dfd81f1f3df 100644 --- a/files/en-us/web/api/navigator/sendbeacon/index.md +++ b/files/en-us/web/api/navigator/sendbeacon/index.md @@ -9,7 +9,7 @@ browser-compat: api.Navigator.sendBeacon {{APIRef("HTML DOM")}} The **`navigator.sendBeacon()`** -method {{glossary("Asynchronous", "asynchronously")}} sends an [HTTP POST](/en-US/docs/Web/HTTP/Methods/POST) request containing a small amount of data to a web server. +method {{glossary("Asynchronous", "asynchronously")}} sends an [HTTP POST](/en-US/docs/Web/HTTP/Reference/Methods/POST) request containing a small amount of data to a web server. It's intended to be used for sending analytics data to a web server, and avoids some of the problems with @@ -70,7 +70,7 @@ This means: - It's sent asynchronously - It doesn't impact the loading of the next page -The data is sent as an [HTTP POST](/en-US/docs/Web/HTTP/Methods/POST) request. +The data is sent as an [HTTP POST](/en-US/docs/Web/HTTP/Reference/Methods/POST) request. ### Sending analytics at the end of a session @@ -78,7 +78,7 @@ Websites often want to send analytics or diagnostics to the server when the user The most reliable way to do this is to send the data on the [`visibilitychange`](/en-US/docs/Web/API/Document/visibilitychange_event) event: ```js -document.addEventListener("visibilitychange", function logData() { +document.addEventListener("visibilitychange", () => { if (document.visibilityState === "hidden") { navigator.sendBeacon("/log", analyticsData); } @@ -112,7 +112,7 @@ Like `beforeunload` and `unload`, this event is not reliably fired, especially o The following example specifies a handler for the {{domxref("document.visibilitychange_event", "visibilitychange")}} event. The handler calls `sendBeacon()` to send analytics. ```js -document.addEventListener("visibilitychange", function logData() { +document.addEventListener("visibilitychange", () => { if (document.visibilityState === "hidden") { navigator.sendBeacon("/log", analyticsData); } diff --git a/files/en-us/web/api/navigator/share/index.md b/files/en-us/web/api/navigator/share/index.md index c06102fc30013de..6d48884a98f3608 100644 --- a/files/en-us/web/api/navigator/share/index.md +++ b/files/en-us/web/api/navigator/share/index.md @@ -13,7 +13,7 @@ The **`share()`** method of the {{domxref("Navigator")}} interface invokes the n The method resolves a {{jsxref("Promise")}} with `undefined`. On Windows this happens when the share popup is launched, while on Android the promise resolves once the data has successfully been passed to the _share target_. -The [Web Share API](/en-US/docs/Web/API/Web_Share_API) is gated by the [web-share](/en-US/docs/Web/HTTP/Headers/Permissions-Policy/web-share) permission policy. +The [Web Share API](/en-US/docs/Web/API/Web_Share_API) is gated by the [web-share](/en-US/docs/Web/HTTP/Reference/Headers/Permissions-Policy/web-share) permission policy. The `share()` method will throw exceptions if the permission is supported but has not been granted. ## Syntax @@ -53,7 +53,7 @@ The {{jsxref("Promise")}} may be rejected with one of the following `DOMExceptio - `InvalidStateError` {{domxref("DOMException")}} - : The document is not fully active, or other sharing operations are in progress. - `NotAllowedError` {{domxref("DOMException")}} - - : A `web-share` [Permissions Policy](/en-US/docs/Web/HTTP/Permissions_Policy) has been used to block the use of this feature, the window does not have {{Glossary("transient activation")}}, or a file share is being blocked due to security considerations. + - : A `web-share` [Permissions Policy](/en-US/docs/Web/HTTP/Guides/Permissions_Policy) has been used to block the use of this feature, the window does not have {{Glossary("transient activation")}}, or a file share is being blocked due to security considerations. - {{jsxref("TypeError")}} - : The specified share data cannot be validated. Possible reasons include: @@ -121,7 +121,7 @@ The following is a list of usually shareable file types. However, you should alw ## Security -This method requires that the current document have the [web-share](/en-US/docs/Web/HTTP/Headers/Permissions-Policy/web-share) Permissions Policy and {{Glossary("transient activation")}}. (It must be triggered off a UI event like a button click and cannot be launched at arbitrary points by a script.) Further, the method must specify valid data that is supported for sharing by the native implementation. +This method requires that the current document have the [web-share](/en-US/docs/Web/HTTP/Reference/Headers/Permissions-Policy/web-share) Permissions Policy and {{Glossary("transient activation")}}. (It must be triggered off a UI event like a button click and cannot be launched at arbitrary points by a script.) Further, the method must specify valid data that is supported for sharing by the native implementation. ## Examples diff --git a/files/en-us/web/api/navigator/unregisterprotocolhandler/index.md b/files/en-us/web/api/navigator/unregisterprotocolhandler/index.md index a659694b6172067..d074d6f1f183d9d 100644 --- a/files/en-us/web/api/navigator/unregisterprotocolhandler/index.md +++ b/files/en-us/web/api/navigator/unregisterprotocolhandler/index.md @@ -25,7 +25,7 @@ unregisterProtocolHandler(scheme, url) For example, you can unregister the handler for SMS text message links by passing the `"sms"` scheme. - `url` - : A string containing the URL of the handler. - **This URL should match the one that was used to register the handler (e.g. it must include `%s`)**. + **This URL should match the one that was used to register the handler (e.g., it must include `%s`)**. ### Return value diff --git a/files/en-us/web/api/navigator/useragentdata/index.md b/files/en-us/web/api/navigator/useragentdata/index.md index c61071db7622d74..c48bc5271416cbd 100644 --- a/files/en-us/web/api/navigator/useragentdata/index.md +++ b/files/en-us/web/api/navigator/useragentdata/index.md @@ -35,4 +35,5 @@ console.log(navigator.userAgentData.brands); ## See also +- [HTTP Client hints](/en-US/docs/Web/HTTP/Guides/Client_hints) - [Improving user privacy and developer experience with User-Agent Client Hints](https://developer.chrome.com/docs/privacy-security/user-agent-client-hints) diff --git a/files/en-us/web/api/navigatorlogin/index.md b/files/en-us/web/api/navigatorlogin/index.md index 78c55cdf3a035a3..c68645c81a213c6 100644 --- a/files/en-us/web/api/navigatorlogin/index.md +++ b/files/en-us/web/api/navigatorlogin/index.md @@ -2,12 +2,10 @@ title: NavigatorLogin slug: Web/API/NavigatorLogin page-type: web-api-interface -status: - - experimental browser-compat: api.NavigatorLogin --- -{{securecontext_header}}{{APIRef("FedCM API")}}{{SeeCompatTable}} +{{securecontext_header}}{{APIRef("FedCM API")}} The **`NavigatorLogin`** interface of the [Federated Credential Management (FedCM) API](/en-US/docs/Web/API/FedCM_API) defines login functionality for federated identity providers (IdPs). Specifically, it enables a federated identity provider (IdP) to set its login status when a user signs into or out of the IdP. @@ -19,7 +17,7 @@ See [Update login status using the Login Status API](/en-US/docs/Web/API/FedCM_A ## Instance methods -- {{domxref("NavigatorLogin.setStatus", "setStatus()")}} {{Experimental_Inline}} +- {{domxref("NavigatorLogin.setStatus", "setStatus()")}} - : Sets the login status of a federated identity provider (IdP), when called from the IdP's origin. By "login status", we mean "whether any users are logged into the IdP on the current browser or not". ## Examples diff --git a/files/en-us/web/api/navigatorlogin/setstatus/index.md b/files/en-us/web/api/navigatorlogin/setstatus/index.md index 8baad3ea22a583d..808d6c90db8726b 100644 --- a/files/en-us/web/api/navigatorlogin/setstatus/index.md +++ b/files/en-us/web/api/navigatorlogin/setstatus/index.md @@ -3,16 +3,14 @@ title: "NavigatorLogin: setStatus() method" short-title: setStatus() slug: Web/API/NavigatorLogin/setStatus page-type: web-api-instance-method -status: - - experimental browser-compat: api.NavigatorLogin.setStatus --- -{{securecontext_header}}{{APIRef("FedCM API")}}{{SeeCompatTable}} +{{securecontext_header}}{{APIRef("FedCM API")}} The **`setStatus()`** method of the {{domxref("NavigatorLogin")}} interface sets the login status of a federated identity provider (IdP), when called from the IdP's origin. By this, we mean "whether any users are logged into the IdP on the current browser or not". This should be called by the IdP site following a user login or logout. -The browser stores this state for each IdP; the [FedCM API](/en-US/docs/Web/API/FedCM_API) API then uses it to reduce the number of requests it makes to the IdP (because it does not need to waste time requesting accounts when there are no users logged in to the IdP). It also mitigates [potential timing attacks](https://github.com/w3c-fedid/FedCM/issues/447). +The browser stores this state for each IdP; the [FedCM API](/en-US/docs/Web/API/FedCM_API) then uses it to reduce the number of requests it makes to the IdP (because it does not need to waste time requesting accounts when there are no users logged in to the IdP). It also mitigates [potential timing attacks](https://github.com/w3c-fedid/FedCM/issues/447). See [Update login status using the Login Status API](/en-US/docs/Web/API/FedCM_API/IDP_integration#update_login_status_using_the_login_status_api) for more information about FedCM login status. diff --git a/files/en-us/web/api/navigatoruadata/brands/index.md b/files/en-us/web/api/navigatoruadata/brands/index.md index 62d4a08a2ca6682..4f784ec80b20cc7 100644 --- a/files/en-us/web/api/navigatoruadata/brands/index.md +++ b/files/en-us/web/api/navigatoruadata/brands/index.md @@ -39,4 +39,4 @@ console.log(navigator.userAgentData.brands); ## See also -- {{HTTPHeader("Sec-CH-UA")}} (a [low-entropy client hint](/en-US/docs/Web/HTTP/Client_hints#low_entropy_hints)) contains the same information. +- {{HTTPHeader("Sec-CH-UA")}} (a [low-entropy client hint](/en-US/docs/Web/HTTP/Guides/Client_hints#low_entropy_hints)) contains the same information. diff --git a/files/en-us/web/api/navigatoruadata/gethighentropyvalues/index.md b/files/en-us/web/api/navigatoruadata/gethighentropyvalues/index.md index 45e4d78ad0743d5..873bf65a00ab1d8 100644 --- a/files/en-us/web/api/navigatoruadata/gethighentropyvalues/index.md +++ b/files/en-us/web/api/navigatoruadata/gethighentropyvalues/index.md @@ -45,13 +45,13 @@ A {{jsxref("Promise")}} that resolves to an object containing some or all of the - `brands` - : Returns an array of objects containing `brand` and `version` specifying the browser brand and its version (the same information as provided by {{domxref("NavigatorUAData.brands")}}). - Note that this information can be sent to a server in the {{HTTPHeader("Sec-CH-UA")}} header (a [low-entropy client hint](/en-US/docs/Web/HTTP/Client_hints#low_entropy_hints)). + Note that this information can be sent to a server in the {{HTTPHeader("Sec-CH-UA")}} header (a [low-entropy client hint](/en-US/docs/Web/HTTP/Guides/Client_hints#low_entropy_hints)). - `mobile` - : Returns `true` if the user agent is running on a mobile device (the same information as provided by {{domxref("NavigatorUAData.mobile")}}). - Note that this information can be sent to a server in the {{HTTPHeader("Sec-CH-UA-Mobile")}} header (a [low-entropy client hint](/en-US/docs/Web/HTTP/Client_hints#low_entropy_hints)). + Note that this information can be sent to a server in the {{HTTPHeader("Sec-CH-UA-Mobile")}} header (a [low-entropy client hint](/en-US/docs/Web/HTTP/Guides/Client_hints#low_entropy_hints)). - `platform` - : Returns a string describing the platform the user agent is running on, like `"Windows"` (the same information as provided by {{domxref("NavigatorUAData.platform")}}). - Note that this information can be sent to a server in the {{HTTPHeader("Sec-CH-UA-Platform")}} header (a [low-entropy client hint](/en-US/docs/Web/HTTP/Client_hints#low_entropy_hints)). + Note that this information can be sent to a server in the {{HTTPHeader("Sec-CH-UA-Platform")}} header (a [low-entropy client hint](/en-US/docs/Web/HTTP/Guides/Client_hints#low_entropy_hints)). - `architecture` - : A string containing the platform architecture. For example, `"x86"`. Note that this information can be sent to a server in the {{HTTPHeader("Sec-CH-UA-Arch")}} header after the server explicitly requests it in the {{HTTPHeader("Accept-CH")}} header. @@ -111,7 +111,7 @@ navigator.userAgentData ## See also - These values are also available as via HTTP request headers: - - [Low-entropy client hints](/en-US/docs/Web/HTTP/Client_hints#low_entropy_hints) are sent automatically: + - [Low-entropy client hints](/en-US/docs/Web/HTTP/Guides/Client_hints#low_entropy_hints) are sent automatically: - {{HTTPHeader("Sec-CH-UA")}} - {{HTTPHeader("Sec-CH-UA-Mobile")}} - {{HTTPHeader("Sec-CH-UA-Platform")}} diff --git a/files/en-us/web/api/navigatoruadata/mobile/index.md b/files/en-us/web/api/navigatoruadata/mobile/index.md index 9cfae83b5dd65de..6446cd4a7d8ce2b 100644 --- a/files/en-us/web/api/navigatoruadata/mobile/index.md +++ b/files/en-us/web/api/navigatoruadata/mobile/index.md @@ -34,4 +34,4 @@ console.log(navigator.userAgentData.mobile); ## See also -- The {{HTTPHeader("Sec-CH-UA-Mobile")}} header (a [low-entropy client hint](/en-US/docs/Web/HTTP/Client_hints#low_entropy_hints)) contains the same information. +- The {{HTTPHeader("Sec-CH-UA-Mobile")}} header (a [low-entropy client hint](/en-US/docs/Web/HTTP/Guides/Client_hints#low_entropy_hints)) contains the same information. diff --git a/files/en-us/web/api/navigatoruadata/platform/index.md b/files/en-us/web/api/navigatoruadata/platform/index.md index 5ed3e28e6118e20..94a1a104a3966e3 100644 --- a/files/en-us/web/api/navigatoruadata/platform/index.md +++ b/files/en-us/web/api/navigatoruadata/platform/index.md @@ -35,4 +35,4 @@ console.log(navigator.userAgentData.platform); ## See also -- The {{HTTPHeader("Sec-CH-UA-Platform")}} header (a [low-entropy client hint](/en-US/docs/Web/HTTP/Client_hints#low_entropy_hints)) contains the same information. +- The {{HTTPHeader("Sec-CH-UA-Platform")}} header (a [low-entropy client hint](/en-US/docs/Web/HTTP/Guides/Client_hints#low_entropy_hints)) contains the same information. diff --git a/files/en-us/web/api/ndefmessage/ndefmessage/index.md b/files/en-us/web/api/ndefmessage/ndefmessage/index.md index 9a89521d7be4407..5ff8b0304fa9483 100644 --- a/files/en-us/web/api/ndefmessage/ndefmessage/index.md +++ b/files/en-us/web/api/ndefmessage/ndefmessage/index.md @@ -33,21 +33,15 @@ new NDEFMessage(records) - `lang` {{optional_inline}} - : A valid language tag according to {{RFC(5646, "Tags for Identifying Languages (also known as BCP 47)")}}. - `mediaType` {{optional_inline}} - - : A valid [MIME type](/en-US/docs/Web/HTTP/MIME_types). + - : A valid [MIME type](/en-US/docs/Web/HTTP/Guides/MIME_types). - `recordType` - - : A string indicating the type of data stored in `data`. It must be one of the following values: - - `"absolute-url"` - - An absolute URL to the data. - - `"empty"` - + - : An absolute URL to the data. + - `"empty"` - : An empty {{domxref("NDEFRecord")}}. - - `"mime"` - - : A valid [MIME type](/en-US/docs/Web/HTTP/MIME_types). + - : A valid [MIME type](/en-US/docs/Web/HTTP/Guides/MIME_types). - `"smart-poster"` - : A smart poster as defined by the [NDEF-SMARTPOSTER](https://w3c.github.io/web-nfc/#bib-ndef-smartposter) specification. - `"text"` diff --git a/files/en-us/web/api/ndefreader/index.md b/files/en-us/web/api/ndefreader/index.md index 7c7a67fa26b584d..9bc6eec17013eeb 100644 --- a/files/en-us/web/api/ndefreader/index.md +++ b/files/en-us/web/api/ndefreader/index.md @@ -9,7 +9,7 @@ browser-compat: api.NDEFReader {{SecureContext_Header}}{{SeeCompatTable}}{{APIRef("Web NFC API")}} -The **`NDEFReader`** interface of the [Web NFC API](/en-US/docs/Web/API/Web_NFC_API) is used to read from and write data to compatible NFC devices, e.g. NFC tags supporting NDEF, when these devices are within the reader's magnetic induction field. +The **`NDEFReader`** interface of the [Web NFC API](/en-US/docs/Web/API/Web_NFC_API) is used to read from and write data to compatible NFC devices, e.g., NFC tags supporting NDEF, when these devices are within the reader's magnetic induction field. {{InheritanceDiagram}} diff --git a/files/en-us/web/api/ndefreader/ndefreader/index.md b/files/en-us/web/api/ndefreader/ndefreader/index.md index 1e7229baadecb5b..6c06035a32936c1 100644 --- a/files/en-us/web/api/ndefreader/ndefreader/index.md +++ b/files/en-us/web/api/ndefreader/ndefreader/index.md @@ -13,7 +13,7 @@ browser-compat: api.NDEFReader.NDEFReader The **`NDEFReader()`** constructor of the {{domxref("NDEFReader")}} interface returns a new `NDEFReader` object, which is used to read NDEF messages from -compatible NFC devices, e.g. NDEF tags, within the reader's magnetic induction +compatible NFC devices, e.g., NDEF tags, within the reader's magnetic induction field. ## Syntax diff --git a/files/en-us/web/api/ndefreader/reading_event/index.md b/files/en-us/web/api/ndefreader/reading_event/index.md index 47d7e4ce1c42532..2b94f4215697994 100644 --- a/files/en-us/web/api/ndefreader/reading_event/index.md +++ b/files/en-us/web/api/ndefreader/reading_event/index.md @@ -10,16 +10,16 @@ browser-compat: api.NDEFReader.reading_event {{SecureContext_Header}}{{SeeCompatTable}}{{APIRef("Web NFC API")}} -The `reading` event of the {{DOMxRef("NDEFReader")}} interface is fired whenever a new reading is available from compatible NFC devices (e.g. NFC tags supporting NDEF) when these devices are within the reader's magnetic induction field. +The `reading` event of the {{DOMxRef("NDEFReader")}} interface is fired whenever a new reading is available from compatible NFC devices (e.g., NFC tags supporting NDEF) when these devices are within the reader's magnetic induction field. ## Syntax Use the event name in methods like {{domxref("EventTarget.addEventListener", "addEventListener()")}}, or set an event handler property. -```js -addEventListener("reading", (event) => {}); +```js-nolint +addEventListener("reading", (event) => { }) -onreading = (event) => {}; +onreading = (event) => { } ``` ## Event type diff --git a/files/en-us/web/api/ndefreader/readingerror_event/index.md b/files/en-us/web/api/ndefreader/readingerror_event/index.md index 3d7a50da1f04023..21a70fb570e0343 100644 --- a/files/en-us/web/api/ndefreader/readingerror_event/index.md +++ b/files/en-us/web/api/ndefreader/readingerror_event/index.md @@ -10,16 +10,16 @@ browser-compat: api.NDEFReader.readingerror_event {{SecureContext_Header}}{{SeeCompatTable}}{{APIRef("Web NFC API")}} -The `readingerror` event of the {{DOMxRef("NDEFReader")}} interface is fired whenever an error occurs during reading of NFC tags, e.g. when tags leave the reader's magnetic induction field. +The `readingerror` event of the {{DOMxRef("NDEFReader")}} interface is fired whenever an error occurs during reading of NFC tags, e.g., when tags leave the reader's magnetic induction field. ## Syntax Use the event name in methods like {{domxref("EventTarget.addEventListener", "addEventListener()")}}, or set an event handler property. -```js -addEventListener("readingerror", (event) => {}); +```js-nolint +addEventListener("readingerror", (event) => { }) -onreadingerror = (event) => {}; +onreadingerror = (event) => { } ``` ## Event type diff --git a/files/en-us/web/api/ndefreader/write/index.md b/files/en-us/web/api/ndefreader/write/index.md index fa6920bb6b3791d..e21fd30e4f0fb65 100644 --- a/files/en-us/web/api/ndefreader/write/index.md +++ b/files/en-us/web/api/ndefreader/write/index.md @@ -36,7 +36,7 @@ write(message, options) - `lang` {{optional_inline}} - : A valid language tag according to {{RFC(5646, "Tags for Identifying Languages (also known as BCP 47)")}}. - `mediaType` {{optional_inline}} - - : A valid [MIME type](/en-US/docs/Web/HTTP/MIME_types). + - : A valid [MIME type](/en-US/docs/Web/HTTP/Guides/MIME_types). - `recordType` - : A string indicating the type of data stored in `data`. It must be one of the following values: @@ -46,7 +46,7 @@ write(message, options) - `"empty"` - : An empty {{domxref("NDEFRecord")}}. - `"mime"` - - : A valid [MIME type](/en-US/docs/Web/HTTP/MIME_types). + - : A valid [MIME type](/en-US/docs/Web/HTTP/Guides/MIME_types). - `"smart-poster"` - : A smart poster as defined by the [NDEF-SMARTPOSTER](https://w3c.github.io/web-nfc/#bib-ndef-smartposter) specification. - `"text"` @@ -134,7 +134,8 @@ ndef.onreading = (event) => console.log("We read a tag!"); function write(data, { timeout } = {}) { return new Promise((resolve, reject) => { const controller = new AbortController(); - controller.signal.onabort = () => reject("Time is up, bailing out!"); + controller.signal.onabort = () => + reject(new Error("Time is up, bailing out!")); setTimeout(() => controller.abort(), timeout); ndef.addEventListener( diff --git a/files/en-us/web/api/ndefreadingevent/ndefreadingevent/index.md b/files/en-us/web/api/ndefreadingevent/ndefreadingevent/index.md index 89b564de9e16f7f..69c9c09a31afe68 100644 --- a/files/en-us/web/api/ndefreadingevent/ndefreadingevent/index.md +++ b/files/en-us/web/api/ndefreadingevent/ndefreadingevent/index.md @@ -42,21 +42,15 @@ new NDEFReadingEvent(type, options) - `lang` {{optional_inline}} - : A valid language tag according to {{RFC(5646, "Tags for Identifying Languages (also known as BCP 47)")}}. - `mediaType` {{optional_inline}} - - : A valid [MIME type](/en-US/docs/Web/HTTP/MIME_types). + - : A valid [MIME type](/en-US/docs/Web/HTTP/Guides/MIME_types). - `recordType` - - : A string indicating the type of data stored in `data`. It must be one of the following values: - - `"absolute-url"` - - An absolute URL to the data. - - `"empty"` - + - : An absolute URL to the data. + - `"empty"` - : An empty {{domxref("NDEFRecord")}}. - - `"mime"` - - : A valid [MIME type](/en-US/docs/Web/HTTP/MIME_types). + - : A valid [MIME type](/en-US/docs/Web/HTTP/Guides/MIME_types). - `"smart-poster"` - : A smart poster as defined by the [NDEF-SMARTPOSTER](https://w3c.github.io/web-nfc/#bib-ndef-smartposter) specification. - `"text"` diff --git a/files/en-us/web/api/ndefrecord/index.md b/files/en-us/web/api/ndefrecord/index.md index 5156458bf23daab..eecf64f8d83ff7a 100644 --- a/files/en-us/web/api/ndefrecord/index.md +++ b/files/en-us/web/api/ndefrecord/index.md @@ -9,7 +9,7 @@ browser-compat: api.NDEFRecord {{SecureContext_Header}}{{SeeCompatTable}}{{APIRef("Web NFC API")}} -The **`NDEFRecord`** interface of the [Web NFC API](/en-US/docs/Web/API/Web_NFC_API) provides data that can be read from, or written to, compatible NFC devices, e.g. NFC tags supporting NDEF. +The **`NDEFRecord`** interface of the [Web NFC API](/en-US/docs/Web/API/Web_NFC_API) provides data that can be read from, or written to, compatible NFC devices, e.g., NFC tags supporting NDEF. ## Constructor diff --git a/files/en-us/web/api/ndefrecord/lang/index.md b/files/en-us/web/api/ndefrecord/lang/index.md index 989f4a37c152d35..b1ccab53697ea58 100644 --- a/files/en-us/web/api/ndefrecord/lang/index.md +++ b/files/en-us/web/api/ndefrecord/lang/index.md @@ -31,5 +31,5 @@ A string. ## See also -- [HTML `lang` attribute](/en-US/docs/Web/HTML/Global_attributes/lang), that declares content language of the document or its elements +- [HTML `lang` attribute](/en-US/docs/Web/HTML/Reference/Global_attributes/lang), that declares content language of the document or its elements - HTTP headers that declare content language: {{HTTPHeader("Content-Language")}} and {{HTTPHeader("Accept-Language")}} diff --git a/files/en-us/web/api/ndefrecord/ndefrecord/index.md b/files/en-us/web/api/ndefrecord/ndefrecord/index.md index 3e4b2242a4d2481..a90fa1df07a1d63 100644 --- a/files/en-us/web/api/ndefrecord/ndefrecord/index.md +++ b/files/en-us/web/api/ndefrecord/ndefrecord/index.md @@ -13,7 +13,7 @@ browser-compat: api.NDEFRecord.NDEFRecord The **`NDEFRecord()`** constructor of the [Web NFC API](/en-US/docs/Web/API/Web_NFC_API) returns a newly constructed {{DOMxRef("NDEFRecord")}} object that represents data that can be -read from, or written to, compatible NFC devices; e.g. NFC tags supporting NDEF. +read from, or written to, compatible NFC devices; e.g., NFC tags supporting NDEF. ## Syntax @@ -36,21 +36,15 @@ new NDEFRecord(options) - `lang` {{optional_inline}} - : A valid language tag according to {{RFC(5646, "Tags for Identifying Languages (also known as BCP 47)")}}. - `mediaType` {{optional_inline}} - - : A valid [MIME type](/en-US/docs/Web/HTTP/MIME_types). + - : A valid [MIME type](/en-US/docs/Web/HTTP/Guides/MIME_types). - `recordType` - - : A string indicating the type of data stored in `data`. It must be one of the following values: - - `"absolute-url"` - - An absolute URL to the data. - - `"empty"` - + - : An absolute URL to the data. + - `"empty"` - : An empty {{domxref("NDEFRecord")}}. - - `"mime"` - - : A valid [MIME type](/en-US/docs/Web/HTTP/MIME_types). + - : A valid [MIME type](/en-US/docs/Web/HTTP/Guides/MIME_types). - `"smart-poster"` - : A smart poster as defined by the [NDEF-SMARTPOSTER](https://w3c.github.io/web-nfc/#bib-ndef-smartposter) specification. - `"text"` diff --git a/files/en-us/web/api/network_information_api/index.md b/files/en-us/web/api/network_information_api/index.md index 4f27f7f8fc5dea4..90efe402ba54b19 100644 --- a/files/en-us/web/api/network_information_api/index.md +++ b/files/en-us/web/api/network_information_api/index.md @@ -2,9 +2,7 @@ title: Network Information API slug: Web/API/Network_Information_API page-type: web-api-overview -browser-compat: - - api.NetworkInformation - - api.Navigator.connection +browser-compat: api.NetworkInformation spec-urls: https://wicg.github.io/netinfo/ --- diff --git a/files/en-us/web/api/networkinformation/change_event/index.md b/files/en-us/web/api/networkinformation/change_event/index.md index 4e5af9d43a250cc..888ee8ca7d14120 100644 --- a/files/en-us/web/api/networkinformation/change_event/index.md +++ b/files/en-us/web/api/networkinformation/change_event/index.md @@ -14,10 +14,10 @@ The **`change`** event of the {{domxref("NetworkInformation")}} interface fires Use the event name in methods like {{domxref("EventTarget.addEventListener", "addEventListener()")}}, or set an event handler property. -```js -addEventListener("change", (event) => {}); +```js-nolint +addEventListener("change", (event) => { }) -onchange = (event) => {}; +onchange = (event) => { } ``` ## Event type diff --git a/files/en-us/web/api/node/index.md b/files/en-us/web/api/node/index.md index 17e61e0eb6a7670..650356d40b25e23 100644 --- a/files/en-us/web/api/node/index.md +++ b/files/en-us/web/api/node/index.md @@ -44,7 +44,7 @@ _In addition to the properties below, `Node` inherits properties from its parent or `null` if the node has no child. - {{DOMxRef("Node.isConnected")}} {{ReadOnlyInline}} - : A boolean indicating whether or not the Node is connected (directly or indirectly) - to the context object, e.g. the {{DOMxRef("Document")}} object in the case of the + to the context object, e.g., the {{DOMxRef("Document")}} object in the case of the normal DOM, or the {{DOMxRef("ShadowRoot")}} in the case of a shadow DOM. - {{DOMxRef("Node.lastChild")}} {{ReadOnlyInline}} - : Returns a `Node` representing the last direct child node of the node, @@ -145,6 +145,11 @@ _In addition to the methods below, `Node` inherits methods from its parent, {{DO - : Replaces one child `Node` of the current one with the second one given in parameter. +## Events + +- {{domxref("Node/selectstart_event", "selectstart")}} + - : Fires when the user starts a new selection in this node. + ## Examples ### Remove all children nested within a node diff --git a/files/en-us/web/api/node/lookupprefix/index.md b/files/en-us/web/api/node/lookupprefix/index.md index 5d9ab858165dd5d..104fce385db82b2 100644 --- a/files/en-us/web/api/node/lookupprefix/index.md +++ b/files/en-us/web/api/node/lookupprefix/index.md @@ -88,4 +88,4 @@ button.addEventListener("click", () => { ## See also -- [http://www.w3.org/TR/DOM-Level-3-Cor...amespacePrefix](https://www.w3.org/TR/DOM-Level-3-Core/core.html#Node3-lookupNamespacePrefix) +- [https://www.w3.org/TR/DOM-Level-3-Cor...amespacePrefix](https://www.w3.org/TR/DOM-Level-3-Core/core.html#Node3-lookupNamespacePrefix) diff --git a/files/en-us/web/api/node/removechild/index.md b/files/en-us/web/api/node/removechild/index.md index 4045624793f22b4..5a894732370d6b9 100644 --- a/files/en-us/web/api/node/removechild/index.md +++ b/files/en-us/web/api/node/removechild/index.md @@ -17,7 +17,7 @@ removes a child node from the DOM and returns the removed node. > It can still be reused later in the code. > > If the return value of `removeChild()` is not stored, and no other reference is kept, -> it will be [automatically deleted](/en-US/docs/Web/JavaScript/Memory_management) from memory after a short time. +> it will be [automatically deleted](/en-US/docs/Web/JavaScript/Guide/Memory_management) from memory after a short time. Unlike {{domxref("Node.cloneNode()")}} the return value preserves the `EventListener` objects associated with it. @@ -108,8 +108,8 @@ const child = document.getElementById("child"); // This first call correctly removes the node const garbage = parent.removeChild(child); -// Throws NotFoundError -garbage = parent.removeChild(child); +// Second call throws NotFoundError +parent.removeChild(child); ``` ## Specifications diff --git a/files/en-us/web/api/node/selectstart_event/index.md b/files/en-us/web/api/node/selectstart_event/index.md index 43b08fbf50ad4e1..543fd18d1adef86 100644 --- a/files/en-us/web/api/node/selectstart_event/index.md +++ b/files/en-us/web/api/node/selectstart_event/index.md @@ -16,10 +16,10 @@ If the event is canceled, the selection is not changed. Use the event name in methods like {{domxref("EventTarget.addEventListener", "addEventListener()")}}, or set an event handler property. -```js -addEventListener("selectstart", (event) => {}); +```js-nolint +addEventListener("selectstart", (event) => { }) -onselectstart = (event) => {}; +onselectstart = (event) => { } ``` ## Event type diff --git a/files/en-us/web/api/notification/click_event/index.md b/files/en-us/web/api/notification/click_event/index.md index 4c4bcabf9e1b2fd..22fe187e0eaaea3 100644 --- a/files/en-us/web/api/notification/click_event/index.md +++ b/files/en-us/web/api/notification/click_event/index.md @@ -19,10 +19,10 @@ If you don't want that behavior, call {{domxref("Event/preventDefault", "prevent Use the event name in methods like {{domxref("EventTarget.addEventListener", "addEventListener()")}}, or set an event handler property. -```js -addEventListener("click", (event) => {}); +```js-nolint +addEventListener("click", (event) => { }) -onclick = (event) => {}; +onclick = (event) => { } ``` ## Event type diff --git a/files/en-us/web/api/notification/close/index.md b/files/en-us/web/api/notification/close/index.md index a0f4351837612f2..b290f7cb13f0760 100644 --- a/files/en-us/web/api/notification/close/index.md +++ b/files/en-us/web/api/notification/close/index.md @@ -16,7 +16,7 @@ close/remove a previously displayed notification. > removed from the screen after a fixed delay since this method will also remove the > notification from any notification tray, preventing users from interacting with it > after it was initially shown. A valid use for this API would be to remove a -> notification that is no longer relevant (e.g. the user already read the notification +> notification that is no longer relevant (e.g., the user already read the notification > on the webpage in the case of a messaging app or the following song is already playing > in a music app). diff --git a/files/en-us/web/api/notification/close_event/index.md b/files/en-us/web/api/notification/close_event/index.md index 43a446437f8a436..e125ecf69bfa832 100644 --- a/files/en-us/web/api/notification/close_event/index.md +++ b/files/en-us/web/api/notification/close_event/index.md @@ -14,10 +14,10 @@ The **`close`** event of the {{domxref("Notification")}} interface fires when a Use the event name in methods like {{domxref("EventTarget.addEventListener", "addEventListener()")}}, or set an event handler property. -```js -addEventListener("close", (event) => {}); +```js-nolint +addEventListener("close", (event) => { }) -onclose = (event) => {}; +onclose = (event) => { } ``` ## Event type diff --git a/files/en-us/web/api/notification/error_event/index.md b/files/en-us/web/api/notification/error_event/index.md index 7321714fd8d9221..c60335f33e5c5d0 100644 --- a/files/en-us/web/api/notification/error_event/index.md +++ b/files/en-us/web/api/notification/error_event/index.md @@ -14,10 +14,10 @@ The **`error`** event of the {{domxref("Notification")}} interface fires when so Use the event name in methods like {{domxref("EventTarget.addEventListener", "addEventListener()")}}, or set an event handler property. -```js -addEventListener("error", (event) => {}); +```js-nolint +addEventListener("error", (event) => { }) -onerror = (event) => {}; +onerror = (event) => { } ``` ## Event type diff --git a/files/en-us/web/api/notification/index.md b/files/en-us/web/api/notification/index.md index a10cad439b026be..e95a3442a2ea9fa 100644 --- a/files/en-us/web/api/notification/index.md +++ b/files/en-us/web/api/notification/index.md @@ -30,7 +30,7 @@ _Also inherits properties from its parent interface, {{domxref("EventTarget")}}_ - `granted` — The user accepts having notifications displayed. - `default` — The user choice is unknown and therefore the browser will act as if the value were denied. -- {{domxref("Notification.maxActions_static", "Notification.maxActions")}} {{ReadOnlyInline}} {{Experimental_Inline}} +- {{domxref("Notification.maxActions_static", "Notification.maxActions")}} {{ReadOnlyInline}} {{experimental_inline}} - : The maximum number of actions supported by the device and the User Agent. ## Instance properties diff --git a/files/en-us/web/api/notification/maxactions_static/index.md b/files/en-us/web/api/notification/maxactions_static/index.md index cfefe0bcef00f3c..c6a871fd447bcf3 100644 --- a/files/en-us/web/api/notification/maxactions_static/index.md +++ b/files/en-us/web/api/notification/maxactions_static/index.md @@ -8,7 +8,7 @@ status: browser-compat: api.Notification.maxActions_static --- -{{APIRef("Web Notifications")}}{{SecureContext_Header}}{{SeeCompatTable}} {{AvailableInWorkers}} +{{APIRef("Web Notifications")}}{{SecureContext_Header}} {{AvailableInWorkers}}{{SeeCompatTable}} The **`maxActions`** read-only static property of the {{domxref("Notification")}} interface returns the maximum number of actions supported by diff --git a/files/en-us/web/api/notification/show_event/index.md b/files/en-us/web/api/notification/show_event/index.md index c69f325a26f18c4..d5a49650bfc4f2b 100644 --- a/files/en-us/web/api/notification/show_event/index.md +++ b/files/en-us/web/api/notification/show_event/index.md @@ -14,10 +14,10 @@ The **`show`** event of the {{domxref("Notification")}} interface fires when a { Use the event name in methods like {{domxref("EventTarget.addEventListener", "addEventListener()")}}, or set an event handler property. -```js -addEventListener("show", (event) => {}); +```js-nolint +addEventListener("show", (event) => { }) -onshow = (event) => {}; +onshow = (event) => { } ``` ## Event type diff --git a/files/en-us/web/api/notifications_api/using_the_notifications_api/index.md b/files/en-us/web/api/notifications_api/using_the_notifications_api/index.md index 2acca0e3bd9b5f3..303257f93c4fd9d 100644 --- a/files/en-us/web/api/notifications_api/using_the_notifications_api/index.md +++ b/files/en-us/web/api/notifications_api/using_the_notifications_api/index.md @@ -24,9 +24,9 @@ We've written a real-world example — a to-do list app — to give more of an i Before an app can send a notification, the user must grant the application the right to do so. This is a common requirement when an API tries to interact with something outside a web page — at least once, the user needs to specifically grant that application permission to present notifications, thereby letting the user control which apps/sites are allowed to display notifications. -Because of abuses of push notifications in the past, web browsers and developers have begun to implement strategies to help mitigate this problem. You should only request consent to display notifications in response to a user gesture (e.g. clicking a button). This is not only best practice — you should not be spamming users with notifications they didn't agree to — but going forward browsers will explicitly disallow notification permission requests not triggered in response to a user gesture. Firefox is already doing this from version 72, for example, and Safari has done it for some time. +Because of abuses of push notifications in the past, web browsers and developers have begun to implement strategies to help mitigate this problem. You should only request consent to display notifications in response to a user gesture (e.g., clicking a button). This is not only best practice — you should not be spamming users with notifications they didn't agree to — but going forward browsers will explicitly disallow notification permission requests not triggered in response to a user gesture. Firefox is already doing this from version 72, for example, and Safari has done it for some time. -In addition, In Chrome and Firefox you cannot request notifications at all unless the site is a secure context (i.e. HTTPS), and you can no longer allow notification permissions to be requested from cross-origin {{htmlelement("iframe")}}s. +In addition, In Chrome and Firefox you cannot request notifications at all unless the site is a secure context (i.e., HTTPS), and you can no longer allow notification permissions to be requested from cross-origin {{htmlelement("iframe")}}s. ### Checking current permission status @@ -104,7 +104,7 @@ const notification = new Notification("To do list", { body: text, icon: img }); ## Closing notifications -Use {{domxref("Notification.close", "close()")}} to remove a notification that is no longer relevant to the user (e.g. the user already read the notification on the webpage, in the case of a messaging app, or the following song is already playing in a music app to notifies upon song changes). Most modern browsers dismiss notifications automatically after a few moments (around four seconds) but this isn't something you should generally be concerned about as it's up to the user and user agent. The dismissal may also happen at the operating system level and users should remain in control of this. Old versions of Chrome didn't remove notifications automatically so you can do so after a {{domxref("Window.setTimeout", "setTimeout()")}} only for those legacy versions in order to not remove notifications from notification trays on other browsers. +Use {{domxref("Notification.close", "close()")}} to remove a notification that is no longer relevant to the user (e.g., the user already read the notification on the webpage, in the case of a messaging app, or the following song is already playing in a music app to notifies upon song changes). Most modern browsers dismiss notifications automatically after a few moments (around four seconds) but this isn't something you should generally be concerned about as it's up to the user and user agent. The dismissal may also happen at the operating system level and users should remain in control of this. Old versions of Chrome didn't remove notifications automatically so you can do so after a {{domxref("Window.setTimeout", "setTimeout()")}} only for those legacy versions in order to not remove notifications from notification trays on other browsers. ```js const n = new Notification("My Great Song"); diff --git a/files/en-us/web/api/notrestoredreasondetails/reason/index.md b/files/en-us/web/api/notrestoredreasondetails/reason/index.md index 8d4815ed39d7302..29da72852ee431b 100644 --- a/files/en-us/web/api/notrestoredreasondetails/reason/index.md +++ b/files/en-us/web/api/notrestoredreasondetails/reason/index.md @@ -22,7 +22,7 @@ There are many different reasons why blocking could occur, and browsers can choo The initial values listed in the specification are: - `"fetch"` - - : While unloading, a fetch initiated by the current document (e.g. via {{domxref("Window/fetch", "fetch()")}}) was canceled while ongoing. As a result, the page was not in a stable state that could be stored in the bfcache. + - : While unloading, a fetch initiated by the current document (e.g., via {{domxref("Window/fetch", "fetch()")}}) was canceled while ongoing. As a result, the page was not in a stable state that could be stored in the bfcache. - `"lock"` - : While unloading, held locks and lock requests were terminated, so the page was not in a stable state that could be stored in the bfcache. - `"masked"` diff --git a/files/en-us/web/api/oes_standard_derivatives/index.md b/files/en-us/web/api/oes_standard_derivatives/index.md index c8b5425a2184396..1ad6161eb02f07c 100644 --- a/files/en-us/web/api/oes_standard_derivatives/index.md +++ b/files/en-us/web/api/oes_standard_derivatives/index.md @@ -26,7 +26,7 @@ This extension exposes one new constant, which can be used in the {{domxref("Web The following new functions can be used in GLSL shader code, if this extension is enabled: -```cpp +```c genType dFdx(genType p) genType dFdy(genType p) genType fwidth(genType p) diff --git a/files/en-us/web/api/offlineaudiocontext/complete_event/index.md b/files/en-us/web/api/offlineaudiocontext/complete_event/index.md index a420c6352d89e6e..60fa2d959cf317a 100644 --- a/files/en-us/web/api/offlineaudiocontext/complete_event/index.md +++ b/files/en-us/web/api/offlineaudiocontext/complete_event/index.md @@ -16,10 +16,10 @@ This event is not cancelable and does not bubble. Use the event name in methods like {{domxref("EventTarget.addEventListener", "addEventListener()")}}, or set an event handler property. -```js -addEventListener("complete", (event) => {}); +```js-nolint +addEventListener("complete", (event) => { }) -oncomplete = (event) => {}; +oncomplete = (event) => { } ``` ## Event type @@ -44,7 +44,7 @@ const offlineAudioCtx = new OfflineAudioContext(); offlineAudioCtx.addEventListener("complete", () => { console.log("Offline audio processing now complete"); - showModalDialog("Song processed and ready to play"); + alert("Song processed and ready to play"); playBtn.disabled = false; }); ``` @@ -56,7 +56,7 @@ const offlineAudioCtx = new OfflineAudioContext(); offlineAudioCtx.oncomplete = () => { console.log("Offline audio processing now complete"); - showModalDialog("Song processed and ready to play"); + alert("Song processed and ready to play"); playBtn.disabled = false; }; ``` diff --git a/files/en-us/web/api/offscreencanvas/contextlost_event/index.md b/files/en-us/web/api/offscreencanvas/contextlost_event/index.md index 16b4516317abd53..6770b0b875e8ad7 100644 --- a/files/en-us/web/api/offscreencanvas/contextlost_event/index.md +++ b/files/en-us/web/api/offscreencanvas/contextlost_event/index.md @@ -18,10 +18,10 @@ User code can prevent the context from being restored by calling [`Event.prevent Use the event name in methods like {{domxref("EventTarget.addEventListener", "addEventListener()")}}, or set an event handler property. -```js -addEventListener("contextlost", (event) => {}); +```js-nolint +addEventListener("contextlost", (event) => { }) -oncontextlost = (event) => {}; +oncontextlost = (event) => { } ``` ## Event type diff --git a/files/en-us/web/api/offscreencanvas/contextrestored_event/index.md b/files/en-us/web/api/offscreencanvas/contextrestored_event/index.md index edb06b547a90c43..77df5561fcd4283 100644 --- a/files/en-us/web/api/offscreencanvas/contextrestored_event/index.md +++ b/files/en-us/web/api/offscreencanvas/contextrestored_event/index.md @@ -16,10 +16,10 @@ You can redraw, re-retrieve resources, and reinitialize the state of your contex Use the event name in methods like {{domxref("EventTarget.addEventListener", "addEventListener()")}}, or set an event handler property. -```js -addEventListener("contextrestored", (event) => {}); +```js-nolint +addEventListener("contextrestored", (event) => { }) -oncontextrestored = (event) => {}; +oncontextrestored = (event) => { } ``` ## Event type diff --git a/files/en-us/web/api/offscreencanvas/height/index.md b/files/en-us/web/api/offscreencanvas/height/index.md index 4698b9df70f51ec..860d46ef5b79c1c 100644 --- a/files/en-us/web/api/offscreencanvas/height/index.md +++ b/files/en-us/web/api/offscreencanvas/height/index.md @@ -12,6 +12,8 @@ The **`height`** property returns and sets the height of an {{domxref("Offscreen ## Value +A positive integer representing the height of the offscreen canvas in CSS pixels. + ## Examples Creating a new offscreen canvas and returning or setting the height of the offscreen canvas: diff --git a/files/en-us/web/api/offscreencanvas/width/index.md b/files/en-us/web/api/offscreencanvas/width/index.md index c11ca049cad4867..ebec032a5b1cafa 100644 --- a/files/en-us/web/api/offscreencanvas/width/index.md +++ b/files/en-us/web/api/offscreencanvas/width/index.md @@ -12,6 +12,8 @@ The **`width`** property returns and sets the width of an {{domxref("OffscreenCa ## Value +A positive integer representing the width of the offscreen canvas in CSS pixels. + ## Examples Creating a new offscreen canvas and returning or setting the width of the offscreen canvas: diff --git a/files/en-us/web/api/orientationsensor/index.md b/files/en-us/web/api/orientationsensor/index.md index f8dd74eedda0470..c63976f87d36fcc 100644 --- a/files/en-us/web/api/orientationsensor/index.md +++ b/files/en-us/web/api/orientationsensor/index.md @@ -9,7 +9,7 @@ browser-compat: api.OrientationSensor The **`OrientationSensor`** interface of the [Sensor APIs](/en-US/docs/Web/API/Sensor_APIs) is the base class for orientation sensors. This interface cannot be used directly. Instead it provides properties and methods accessed by interfaces that inherit from it. -This feature may be blocked by a [Permissions Policy](/en-US/docs/Web/HTTP/Permissions_Policy) set on your server. +This feature may be blocked by a [Permissions Policy](/en-US/docs/Web/HTTP/Guides/Permissions_Policy) set on your server. {{InheritanceDiagram}} diff --git a/files/en-us/web/api/otpcredential/index.md b/files/en-us/web/api/otpcredential/index.md index 90ab9885875be27..9c31301cb305559 100644 --- a/files/en-us/web/api/otpcredential/index.md +++ b/files/en-us/web/api/otpcredential/index.md @@ -9,7 +9,7 @@ browser-compat: api.OTPCredential {{APIRef("WebOTP API")}}{{SecureContext_Header}}{{SeeCompatTable}} -The **`OTPCredential`** interface of the {{domxref('WebOTP API','','',' ')}} is returned when a WebOTP {{domxref("CredentialsContainer.get", "navigator.credentials.get()")}} call (i.e. invoked with an `otp` option) fulfills. It includes a `code` property that contains the retrieved one-time password (OTP). +The **`OTPCredential`** interface of the {{domxref('WebOTP API','','',' ')}} is returned when a WebOTP {{domxref("CredentialsContainer.get", "navigator.credentials.get()")}} call (i.e., invoked with an `otp` option) fulfills. It includes a `code` property that contains the retrieved one-time password (OTP). {{InheritanceDiagram}} diff --git a/files/en-us/web/api/ovr_multiview2/index.md b/files/en-us/web/api/ovr_multiview2/index.md index 4c68127a69c7345..4686896be569ce4 100644 --- a/files/en-us/web/api/ovr_multiview2/index.md +++ b/files/en-us/web/api/ovr_multiview2/index.md @@ -14,7 +14,7 @@ For more information, see also: - [Multiview on WebXR](https://error.ghost.org/) - [Multiview in babylon.js](https://doc.babylonjs.com/features/featuresDeepDive/cameras/multiViewsPart1) -- [Optimizing Virtual Reality: Understanding Multiview](https://community.arm.com/arm-community-blogs/b/graphics-gaming-and-vr-blog/posts/optimizing-virtual-reality-understanding-multiview) +- [Optimizing Virtual Reality: Understanding Multiview](https://community.arm.com/arm-community-blogs/b/mobile-graphics-and-gaming-blog/posts/optimizing-virtual-reality-understanding-multiview) - [Multiview WebGL Rendering for Meta Quest](https://developers.meta.com/horizon/documentation/web/web-multiview/) WebGL extensions are available using the {{domxref("WebGLRenderingContext.getExtension()")}} method. For more information, see also [Using Extensions](/en-US/docs/Web/API/WebGL_API/Using_Extensions) in the [WebGL tutorial](/en-US/docs/Web/API/WebGL_API/Tutorial). @@ -85,7 +85,7 @@ gl.drawElements(/* … */); // draw will be broadcasted to the layers of colorTe Shader code -```cpp +```glsl #version 300 es #extension GL_OVR_multiview2 : require precision mediump float; diff --git a/files/en-us/web/api/page_visibility_api/index.md b/files/en-us/web/api/page_visibility_api/index.md index 7f0c06c3d5fdb1b..f0ccce62364b119 100644 --- a/files/en-us/web/api/page_visibility_api/index.md +++ b/files/en-us/web/api/page_visibility_api/index.md @@ -107,11 +107,9 @@ document.addEventListener("visibilitychange", () => { if (document.hidden) { playingOnHide = !audio.paused; audio.pause(); - } else { + } else if (playingOnHide) { // Page became visible! Resume playing if audio was "playing on hide" - if (playingOnHide) { - audio.play(); - } + audio.play(); } }); ``` diff --git a/files/en-us/web/api/paintworkletglobalscope/registerpaint/index.md b/files/en-us/web/api/paintworkletglobalscope/registerpaint/index.md index 6764ded35b051cb..0003212a1d68dd6 100644 --- a/files/en-us/web/api/paintworkletglobalscope/registerpaint/index.md +++ b/files/en-us/web/api/paintworkletglobalscope/registerpaint/index.md @@ -80,7 +80,7 @@ the `CSS.paintWorklet.addModule()` method: </script> ``` -You can then use the `{{cssxref('image/paint', 'paint()')}}` CSS function in your +You can then use the {{cssxref('image/paint', 'paint()')}} CSS function in your CSS anywhere an {{cssxref('&lt;image&gt;')}} value is valid. ```css diff --git a/files/en-us/web/api/pannernode/refdistance/index.md b/files/en-us/web/api/pannernode/refdistance/index.md index 874a154ab95d679..b02cbf9f2eed944 100644 --- a/files/en-us/web/api/pannernode/refdistance/index.md +++ b/files/en-us/web/api/pannernode/refdistance/index.md @@ -8,7 +8,7 @@ browser-compat: api.PannerNode.refDistance {{ APIRef("Web Audio API") }} -The `refDistance` property of the {{ domxref("PannerNode") }} interface is a double value representing the reference distance for reducing volume as the audio source moves further from the listener – i.e. the distance at which the volume reduction starts taking effect. This value is used by all distance models. +The `refDistance` property of the {{ domxref("PannerNode") }} interface is a double value representing the reference distance for reducing volume as the audio source moves further from the listener – i.e., the distance at which the volume reduction starts taking effect. This value is used by all distance models. The `refDistance` property's default value is `1`. diff --git a/files/en-us/web/api/passwordcredentialinit/index.md b/files/en-us/web/api/passwordcredentialinit/index.md index 5a5186f4f3b7068..aed5d15f6177a99 100644 --- a/files/en-us/web/api/passwordcredentialinit/index.md +++ b/files/en-us/web/api/passwordcredentialinit/index.md @@ -11,7 +11,7 @@ The **`PasswordCredentialInit`** dictionary represents the object passed to {{do ## Initialization from a form -Instead of passing this dictionary directly, a website can pass an {{domxref("HTMLFormElement")}}, and the implementation of `create()` will populate the credential's data from the values of the form's submittable elements, based on the value of the element's [`autocomplete`](/en-US/docs/Web/HTML/Attributes/autocomplete) attribute. +Instead of passing this dictionary directly, a website can pass an {{domxref("HTMLFormElement")}}, and the implementation of `create()` will populate the credential's data from the values of the form's submittable elements, based on the value of the element's [`autocomplete`](/en-US/docs/Web/HTML/Reference/Attributes/autocomplete) attribute. | `autocomplete` value | Credential property targeted | | ---------------------------------------- | ---------------------------- | diff --git a/files/en-us/web/api/path2d/path2d/index.md b/files/en-us/web/api/path2d/path2d/index.md index e7f615e6855bf00..b6174a03ab0e319 100644 --- a/files/en-us/web/api/path2d/path2d/index.md +++ b/files/en-us/web/api/path2d/path2d/index.md @@ -10,7 +10,7 @@ browser-compat: api.Path2D.Path2D The **`Path2D()`** constructor returns a newly instantiated `Path2D` object, optionally with another path as an argument (creates a -copy), or optionally with a string consisting of [SVG path](/en-US/docs/Web/SVG/Tutorial/Paths) data. +copy), or optionally with a string consisting of [SVG path](/en-US/docs/Web/SVG/Tutorials/SVG_from_scratch/Paths) data. ## Syntax @@ -26,7 +26,7 @@ new Path2D(d) - : When invoked with another `Path2D` object, a copy of the `path` argument is created. - `d` {{optional_inline}} - - : When invoked with a string consisting of [SVG path](/en-US/docs/Web/SVG/Tutorial/Paths) data, a new path is created + - : When invoked with a string consisting of [SVG path](/en-US/docs/Web/SVG/Tutorials/SVG_from_scratch/Paths) data, a new path is created from that description. ## Examples @@ -57,7 +57,7 @@ ctx.stroke(path2); ### Using SVG paths -This example creates a `Path2D` path using [SVG path data](/en-US/docs/Web/SVG/Tutorial/Paths). The path will move to +This example creates a `Path2D` path using [SVG path data](/en-US/docs/Web/SVG/Tutorials/SVG_from_scratch/Paths). The path will move to point (`M10 10`) and then move horizontally 80 points to the right (`h 80`), then 80 points down (`v 80`), then 80 points to the left (`h -80`), and then back to the start (`Z`). diff --git a/files/en-us/web/api/payment_handler_api/index.md b/files/en-us/web/api/payment_handler_api/index.md index fc58350ec3d262a..45e6f0642fa22f4 100644 --- a/files/en-us/web/api/payment_handler_api/index.md +++ b/files/en-us/web/api/payment_handler_api/index.md @@ -139,7 +139,7 @@ The Payment Request API's {{domxref("PaymentRequest.canMakePayment()")}} method ```js async function checkCanMakePayment() { - // ... + // … const canMakePayment = await request.canMakePayment(); if (!canMakePayment) { @@ -186,7 +186,7 @@ self.addEventListener("paymentrequest", async (e) => { // Preserve the event for future use payment_request_event = e; - // ... + // … }); ``` @@ -209,10 +209,10 @@ navigator.serviceWorker.register("serviceworker.js").then((registration) => { registration.paymentManager .enableDelegations(["shippingAddress", "payerName"]) .then(() => { - // ... + // … }); - // ... + // … }); ``` diff --git a/files/en-us/web/api/payment_request_api/concepts/index.md b/files/en-us/web/api/payment_request_api/concepts/index.md index d79b59d0e295e08..65eb542830b3a56 100644 --- a/files/en-us/web/api/payment_request_api/concepts/index.md +++ b/files/en-us/web/api/payment_request_api/concepts/index.md @@ -34,7 +34,7 @@ Payment handlers are identified by **payment method identifiers**, which are str ### Standardized payment method identifiers -Standardized payment method identifiers are those listed in the [payment method registry](https://www.w3.org/TR/payment-method-id/#registry). +Standardized payment method identifiers are those listed in the [payment method registry](https://w3c.github.io/payment-method-id/#registry). - `secure-payment-confirmation` diff --git a/files/en-us/web/api/payment_request_api/index.md b/files/en-us/web/api/payment_request_api/index.md index ed09402eff7f267..2973d60643abcbd 100644 --- a/files/en-us/web/api/payment_request_api/index.md +++ b/files/en-us/web/api/payment_request_api/index.md @@ -18,7 +18,7 @@ To request a payment, a web page creates a {{domxref("PaymentRequest")}} object You can find a complete guide in [Using the Payment Request API](/en-US/docs/Web/API/Payment_Request_API/Using_the_Payment_Request_API). > [!NOTE] -> The API is available inside cross-origin {{htmlelement("iframe")}} elements only if they have had the [`allowpaymentrequest`](/en-US/docs/Web/HTML/Element/iframe#allowpaymentrequest) attribute set on them. +> The API is available inside cross-origin {{htmlelement("iframe")}} elements only if they have had the [`allowpaymentrequest`](/en-US/docs/Web/HTML/Reference/Elements/iframe#allowpaymentrequest) attribute set on them. ## Interfaces diff --git a/files/en-us/web/api/payment_request_api/using_secure_payment_confirmation/index.md b/files/en-us/web/api/payment_request_api/using_secure_payment_confirmation/index.md index 24b2ded6172d8fd..542594d5363a75f 100644 --- a/files/en-us/web/api/payment_request_api/using_secure_payment_confirmation/index.md +++ b/files/en-us/web/api/payment_request_api/using_secure_payment_confirmation/index.md @@ -94,7 +94,7 @@ navigator.credentials SPC allows a credential to be created in a cross-origin iframe (e.g., if `merchant.com` embeds an iframe from `bank.com`). In this flow, as part of a transaction, the Relying Party (e.g., a bank) authenticates the account holder through some mechanism other than SPC (e.g., by using a one-time passcode or some other mechanism). The Relying Party then offers the user the option of registering an SPC credential to streamline future transactions. The user registers an SPC credential with the Relying Party. -In order for these steps to happen in the merchant context (that is, without a redirect), the cross-origin iframe must have the [`payment`](/en-US/docs/Web/HTTP/Headers/Permissions-Policy/payment) permission policy set. +In order for these steps to happen in the merchant context (that is, without a redirect), the cross-origin iframe must have the [`payment`](/en-US/docs/Web/HTTP/Reference/Headers/Permissions-Policy/payment) permission policy set. For example: diff --git a/files/en-us/web/api/payment_request_api/using_the_payment_request_api/index.md b/files/en-us/web/api/payment_request_api/using_the_payment_request_api/index.md index 504c1a6e3022aa3..57137b3ef7fcd79 100644 --- a/files/en-us/web/api/payment_request_api/using_the_payment_request_api/index.md +++ b/files/en-us/web/api/payment_request_api/using_the_payment_request_api/index.md @@ -108,7 +108,7 @@ new PaymentRequest(buildSupportedPaymentMethodData(), { ## Detecting availability of the Payment Request API -You can effectively detect support for the Payment Request API by checking if the user's browser supports {{domxref("PaymentRequest")}}, i.e. `if (window.PaymentRequest)`. +You can effectively detect support for the Payment Request API by checking if the user's browser supports {{domxref("PaymentRequest")}}, i.e., `if (window.PaymentRequest)`. In the following snippet, a merchant page performs this check, and if it returns `true` updates the checkout button to use `PaymentRequest` instead of legacy web forms. @@ -290,14 +290,16 @@ If the merchant desires to collect additional information not part of the API (e ```js request .show() - .then((paymentResponse) => { + .then((paymentResponse) => paymentResponse.complete("success")) + .then(() => { // Process payment here. // Close the UI: - paymentResponse.complete('success').then(() => { - // Request additional shipping address details. - const additionalDetailsContainer = document.getElementById('additional-details-container'); - additionalDetailsContainer.style.display = 'block'; - window.scrollTo(additionalDetailsContainer.getBoundingClientRect().x, 0); + // Request additional shipping address details. + const additionalDetailsContainer = document.getElementById( + "additional-details-container", + ); + additionalDetailsContainer.style.display = "block"; + window.scrollTo(additionalDetailsContainer.getBoundingClientRect().x, 0); }) .catch((error) => { // Handle error. diff --git a/files/en-us/web/api/paymentmanager/enabledelegations/index.md b/files/en-us/web/api/paymentmanager/enabledelegations/index.md index c2264794b3aee54..63064e1bf1b2d13 100644 --- a/files/en-us/web/api/paymentmanager/enabledelegations/index.md +++ b/files/en-us/web/api/paymentmanager/enabledelegations/index.md @@ -49,10 +49,10 @@ navigator.serviceWorker.register("serviceworker.js").then((registration) => { registration.paymentManager .enableDelegations(["shippingAddress", "payerName"]) .then(() => { - // ... + // … }); - // ... + // … }); ``` diff --git a/files/en-us/web/api/paymentmanager/index.md b/files/en-us/web/api/paymentmanager/index.md index c8da519e207de6f..2c2092ca27b8d37 100644 --- a/files/en-us/web/api/paymentmanager/index.md +++ b/files/en-us/web/api/paymentmanager/index.md @@ -34,10 +34,10 @@ navigator.serviceWorker.register("serviceworker.js").then((registration) => { registration.paymentManager .enableDelegations(["shippingAddress", "payerName"]) .then(() => { - // ... + // … }); - // ... + // … }); ``` diff --git a/files/en-us/web/api/paymentmanager/userhint/index.md b/files/en-us/web/api/paymentmanager/userhint/index.md index a56cd6814f1353d..b1a45d661f32885 100644 --- a/files/en-us/web/api/paymentmanager/userhint/index.md +++ b/files/en-us/web/api/paymentmanager/userhint/index.md @@ -25,10 +25,10 @@ navigator.serviceWorker.register("serviceworker.js").then((registration) => { registration.paymentManager .enableDelegations(["shippingAddress", "payerName"]) .then(() => { - // ... + // … }); - // ... + // … }); ``` diff --git a/files/en-us/web/api/paymentrequest/merchantvalidation_event/index.md b/files/en-us/web/api/paymentrequest/merchantvalidation_event/index.md index 9f6694ec7c0c30f..1f080cfd1446747 100644 --- a/files/en-us/web/api/paymentrequest/merchantvalidation_event/index.md +++ b/files/en-us/web/api/paymentrequest/merchantvalidation_event/index.md @@ -20,10 +20,10 @@ This event is not cancelable and does not bubble. Use the event name in methods like {{domxref("EventTarget.addEventListener", "addEventListener()")}}, or set an event handler property. -```js -addEventListener("merchantvalidation", (event) => {}); +```js-nolint +addEventListener("merchantvalidation", (event) => { }) -onmerchantvalidation = (event) => {}; +onmerchantvalidation = (event) => { } ``` ## Event type diff --git a/files/en-us/web/api/paymentrequest/paymentmethodchange_event/index.md b/files/en-us/web/api/paymentrequest/paymentmethodchange_event/index.md index d7f2cbdccda6608..92be5c079362215 100644 --- a/files/en-us/web/api/paymentrequest/paymentmethodchange_event/index.md +++ b/files/en-us/web/api/paymentrequest/paymentmethodchange_event/index.md @@ -18,10 +18,10 @@ This event is not cancelable and does not bubble. Use the event name in methods like {{domxref("EventTarget.addEventListener", "addEventListener()")}}, or set an event handler property. -```js -addEventListener("paymentmethodchange", (event) => {}); +```js-nolint +addEventListener("paymentmethodchange", (event) => { }) -onpaymentmethodchange = (event) => {}; +onpaymentmethodchange = (event) => { } ``` ## Event type diff --git a/files/en-us/web/api/paymentrequest/paymentrequest/index.md b/files/en-us/web/api/paymentrequest/paymentrequest/index.md index f2c067c00767533..a2af15090eddb31 100644 --- a/files/en-us/web/api/paymentrequest/paymentrequest/index.md +++ b/files/en-us/web/api/paymentrequest/paymentrequest/index.md @@ -106,7 +106,7 @@ input parameters. ### Exceptions - `SecurityError` {{domxref("DOMException")}} - - : Use of this feature was blocked by a [Permissions Policy](/en-US/docs/Web/HTTP/Permissions_Policy). + - : Use of this feature was blocked by a [Permissions Policy](/en-US/docs/Web/HTTP/Guides/Permissions_Policy). ## Examples diff --git a/files/en-us/web/api/paymentrequest/shippingaddress/index.md b/files/en-us/web/api/paymentrequest/shippingaddress/index.md index dce140dd6bbb762..92a3f0983128e2d 100644 --- a/files/en-us/web/api/paymentrequest/shippingaddress/index.md +++ b/files/en-us/web/api/paymentrequest/shippingaddress/index.md @@ -17,6 +17,8 @@ user. It is `null` by default. ## Value +A {{domxref('PaymentAddress')}} object or `null`. + ## Examples Generally, the user agent will fill the `shippingAddress` property value. diff --git a/files/en-us/web/api/paymentrequest/shippingaddresschange_event/index.md b/files/en-us/web/api/paymentrequest/shippingaddresschange_event/index.md index 876f8ef5b649457..3656eeef74433b9 100644 --- a/files/en-us/web/api/paymentrequest/shippingaddresschange_event/index.md +++ b/files/en-us/web/api/paymentrequest/shippingaddresschange_event/index.md @@ -19,10 +19,10 @@ This event is not cancelable and does not bubble. Use the event name in methods like {{domxref("EventTarget.addEventListener", "addEventListener()")}}, or set an event handler property. -```js -addEventListener("shippingaddresschange", (event) => {}); +```js-nolint +addEventListener("shippingaddresschange", (event) => { }) -onshippingaddresschange = (event) => {}; +onshippingaddresschange = (event) => { } ``` ## Event type diff --git a/files/en-us/web/api/paymentrequest/shippingoption/index.md b/files/en-us/web/api/paymentrequest/shippingoption/index.md index d72d580a91caede..2545765d3e4a559 100644 --- a/files/en-us/web/api/paymentrequest/shippingoption/index.md +++ b/files/en-us/web/api/paymentrequest/shippingoption/index.md @@ -11,27 +11,21 @@ browser-compat: api.PaymentRequest.shippingOption {{APIRef("Payment Request API")}}{{SecureContext_Header}}{{Deprecated_Header}}{{Non-standard_Header}} -The **`shippingOption`** read-only attribute of -the {{domxref('PaymentRequest')}} interface returns either the id of a selected shipping -option, null (if no shipping option was set to be selected) or a shipping option -selected by the user. It is initially `null` by when no "selected" shipping -options are provided. +The **`shippingOption`** read-only attribute of the {{domxref('PaymentRequest')}} interface returns either the id of a selected shipping option, null (if no shipping option was set to be selected) or a shipping option selected by the user. +It is initially `null` by when no "selected" shipping options are provided. -This attribute is only populated if the constructor is called with the -`requestShipping` flag set to `true`. If -`requestShipping` was `false` (or missing), -`shippingOption` returns `null`, even the developer provides -a selected a shipping option. +This attribute is only populated if the constructor is called with the `requestShipping` flag set to `true`. +If `requestShipping` was `false` (or missing), `shippingOption` returns `null`, even the developer provides a selected a shipping option. ## Value +An object or `null`. + ## Examples -In the example below, the {{domxref('PaymentRequest.shippingaddresschange_event', 'shippingaddresschange')}} and -the {{domxref('PaymentRequest.shippingoptionchange_event', 'shippingoptionchange')}} events are dispatched. In -each calls to `updateDetails()` are made, one using a promise, and the other -with a plain JS object. This demonstrates synchronous and asynchronous updates to a -payment sheet. +In the example below, the {{domxref('PaymentRequest.shippingaddresschange_event', 'shippingaddresschange')}} and the {{domxref('PaymentRequest.shippingoptionchange_event', 'shippingoptionchange')}} events are dispatched. +In each calls to `updateDetails()` are made, one using a promise, and the other with a plain JS object. +This demonstrates synchronous and asynchronous updates to a payment sheet. ```js const request = new PaymentRequest(methodData, details, options); diff --git a/files/en-us/web/api/paymentrequest/shippingoptionchange_event/index.md b/files/en-us/web/api/paymentrequest/shippingoptionchange_event/index.md index 3520af1d2f2d036..d37e782e45596fd 100644 --- a/files/en-us/web/api/paymentrequest/shippingoptionchange_event/index.md +++ b/files/en-us/web/api/paymentrequest/shippingoptionchange_event/index.md @@ -21,10 +21,10 @@ This event is not cancelable and does not bubble. Use the event name in methods like {{domxref("EventTarget.addEventListener", "addEventListener()")}}, or set an event handler property. -```js -addEventListener("shippingoptionchange", (event) => {}); +```js-nolint +addEventListener("shippingoptionchange", (event) => { }) -onshippingoptionchange = (event) => {}; +onshippingoptionchange = (event) => { } ``` ## Event type diff --git a/files/en-us/web/api/paymentrequest/show/index.md b/files/en-us/web/api/paymentrequest/show/index.md index c38237354a720bc..de7862b724da448 100644 --- a/files/en-us/web/api/paymentrequest/show/index.md +++ b/files/en-us/web/api/paymentrequest/show/index.md @@ -270,7 +270,7 @@ call to {{domxref("paymentResponse.complete()")}} can indicate the success or fa the payment. ```js -button.onclick = async function handlePurchase() { +button.onclick = async () => { // Initialization of PaymentRequest arguments are excerpted for the sake of // brevity. const payment = new PaymentRequest(methods, details, options); diff --git a/files/en-us/web/api/paymentrequestevent/index.md b/files/en-us/web/api/paymentrequestevent/index.md index bf7f1c6478cbef9..ee038a2be66a0c4 100644 --- a/files/en-us/web/api/paymentrequestevent/index.md +++ b/files/en-us/web/api/paymentrequestevent/index.md @@ -62,7 +62,7 @@ self.addEventListener("paymentrequest", async (e) => { // Preserve the event for future use payment_request_event = e; - // ... + // … }); ``` diff --git a/files/en-us/web/api/paymentrequestevent/openwindow/index.md b/files/en-us/web/api/paymentrequestevent/openwindow/index.md index aa7398fc411f377..fb942fde9c5d811 100644 --- a/files/en-us/web/api/paymentrequestevent/openwindow/index.md +++ b/files/en-us/web/api/paymentrequestevent/openwindow/index.md @@ -32,9 +32,8 @@ A {{jsxref("Promise")}} that resolves with a reference to a ## Examples ```js -… -self.addEventListener('paymentrequest', async e => { -… +self.addEventListener("paymentrequest", async (e) => { + // … // Retain a promise for future resolution // Polyfill for PromiseResolver at link below. resolver = new PromiseResolver(); @@ -47,14 +46,13 @@ self.addEventListener('paymentrequest', async e => { client = await e.openWindow(checkoutURL); if (!client) { // Reject if the window fails to open - throw 'Failed to open window'; + throw new Error("Failed to open window"); } } catch (err) { // Reject the promise on failure resolver.reject(err); - }; + } }); -… ``` See [Open the payment handler window to display the web-based payment app frontend](https://web.dev/articles/orchestrating-payment-transactions#open-payment-handler-window) for more details about how this would be used. diff --git a/files/en-us/web/api/paymentrequestevent/paymentrequestevent/index.md b/files/en-us/web/api/paymentrequestevent/paymentrequestevent/index.md index cafaddceb45e673..d975725ccc78097 100644 --- a/files/en-us/web/api/paymentrequestevent/paymentrequestevent/index.md +++ b/files/en-us/web/api/paymentrequestevent/paymentrequestevent/index.md @@ -50,7 +50,7 @@ A developer would not use this constructor manually. A new `PaymentRequestEvent` ```js self.addEventListener("paymentrequest", (e) => { - // ... + // … }); ``` diff --git a/files/en-us/web/api/paymentrequestevent/respondwith/index.md b/files/en-us/web/api/paymentrequestevent/respondwith/index.md index 567a336aaeca5aa..9effff027bf8f9d 100644 --- a/files/en-us/web/api/paymentrequestevent/respondwith/index.md +++ b/files/en-us/web/api/paymentrequestevent/respondwith/index.md @@ -48,7 +48,7 @@ self.addEventListener("paymentrequest", async (e) => { client = await e.openWindow(checkoutURL); if (!client) { // Reject if the window fails to open - throw "Failed to open window"; + throw new Error("Failed to open window"); } } catch (err) { // Reject the promise on failure diff --git a/files/en-us/web/api/paymentrequestevent/total/index.md b/files/en-us/web/api/paymentrequestevent/total/index.md index a2732fb0240b5d0..64ffb66f96d5643 100644 --- a/files/en-us/web/api/paymentrequestevent/total/index.md +++ b/files/en-us/web/api/paymentrequestevent/total/index.md @@ -20,7 +20,7 @@ A `PaymentCurrencyAmount` object. This object contains the following properties: - `currency` - : A string containing a three-letter [ISO 4217](https://www.iso.org/iso-4217-currency-codes.html) standard currency code representing the currency of the payment. Examples include `USD`, `CAN`, and `GBP`. - `value` - - : A string containing a decimal monetary value, e.g. `2.55`. + - : A string containing a decimal monetary value, e.g., `2.55`. ## Examples diff --git a/files/en-us/web/api/paymentresponse/details/index.md b/files/en-us/web/api/paymentresponse/details/index.md index 0329ae6e2fa4076..37f2c72cdd9604a 100644 --- a/files/en-us/web/api/paymentresponse/details/index.md +++ b/files/en-us/web/api/paymentresponse/details/index.md @@ -13,10 +13,10 @@ The **`details`** read-only property of the provides a payment method specific message used by the merchant to process the transaction and determine a successful funds transfer. -This data is returned by the payment app that satisfies the payment request. Developers need to consult whomever controls the URL for the expected shape of the details object. - ## Value +An object. This data is returned by the payment app that satisfies the payment request. Developers need to consult whomever controls the URL for the expected shape of the details object. + ## Examples The following example extracts the details from the {{domxref('PaymentResponse')}} diff --git a/files/en-us/web/api/paymentresponse/payerdetailchange_event/index.md b/files/en-us/web/api/paymentresponse/payerdetailchange_event/index.md index 5b8605b90bebccb..c806f0c250af06d 100644 --- a/files/en-us/web/api/paymentresponse/payerdetailchange_event/index.md +++ b/files/en-us/web/api/paymentresponse/payerdetailchange_event/index.md @@ -18,10 +18,10 @@ This event is not cancelable and does not bubble. Use the event name in methods like {{domxref("EventTarget.addEventListener", "addEventListener()")}}, or set an event handler property. -```js -addEventListener("payerdetailchange", async (event) => {}); +```js-nolint +addEventListener("payerdetailchange", (event) => { }) -onpayerdetailchange = async (event) => {}; +onpayerdetailchange = (event) => { } ``` ## Event type @@ -87,7 +87,7 @@ response.onpayerdetailchange = async (ev) => { // validation to the errors list const errors = await Promise.all(promisesToValidate).then((results) => - results.reduce((errors, result), Object.assign(errors, result)), + results.reduce((errors, result) => Object.assign(errors, result)), ); // If we found any errors, wait for them to be corrected diff --git a/files/en-us/web/api/paymentresponse/retry/index.md b/files/en-us/web/api/paymentresponse/retry/index.md index 86adcf9d67aac3a..487668770238c61 100644 --- a/files/en-us/web/api/paymentresponse/retry/index.md +++ b/files/en-us/web/api/paymentresponse/retry/index.md @@ -29,7 +29,7 @@ retry(errorFields) - : An object, with the following properties: - `error` {{optional_inline}} - : A general description of a payment error from which the user may attempt to recover by retrying the payment, possibly after correcting mistakes in the payment information. `error` can be provided all by itself to provide only a generic error message, or in concert with the other properties to serve as an overview while other properties' values guide the user to errors in specific fields in the payment form. - - `paymentMethod {{optional_inline}} + - `paymentMethod` {{optional_inline}} - : Any payment-method-specific errors which may have occurred. This object's contents will vary depending on the payment method used. ### Return value diff --git a/files/en-us/web/api/paymentresponse/tojson/index.md b/files/en-us/web/api/paymentresponse/tojson/index.md index 64787a288b31cde..148926ebfee1ab2 100644 --- a/files/en-us/web/api/paymentresponse/tojson/index.md +++ b/files/en-us/web/api/paymentresponse/tojson/index.md @@ -32,8 +32,7 @@ In this example, calling `paymentResponse.toJSON()` returns a JSON representatio ```js payment.show().then((paymentResponse) => { - console.log(paymentResponse.toJSON()) - }; + console.log(paymentResponse.toJSON()); }); ``` diff --git a/files/en-us/web/api/performance/measureuseragentspecificmemory/index.md b/files/en-us/web/api/performance/measureuseragentspecificmemory/index.md index 5e804d638c8442e..60511c0b203d28d 100644 --- a/files/en-us/web/api/performance/measureuseragentspecificmemory/index.md +++ b/files/en-us/web/api/performance/measureuseragentspecificmemory/index.md @@ -49,38 +49,38 @@ A {{jsxref("Promise")}} that resolves to an object containing the following prop An example return value looks like this: -```js +```json { - bytes: 1500000, - breakdown: [ + "bytes": 1500000, + "breakdown": [ { - bytes: 1000000, - attribution: [ + "bytes": 1000000, + "attribution": [ { - url: "https://example.com", - scope: "Window", + "url": "https://example.com", + "scope": "Window", }, ], - types: ["DOM", "JS"], + "types": ["DOM", "JS"], }, { - bytes: 0, - attribution: [], - types: [], + "bytes": 0, + "attribution": [], + "types": [], }, { - bytes: 500000, - attribution: [ + "bytes": 500000, + "attribution": [ { - url: "https://example.com/iframe.html" - container: { - id: "example-id", - src: "redirect.html?target=iframe.html", + "url": "https://example.com/iframe.html" + "container": { + "id": "example-id", + "src": "redirect.html?target=iframe.html", }, - scope: "Window", + "scope": "Window", } ], - types: ["JS", "DOM"], + "types": ["JS", "DOM"], }, ], } @@ -93,7 +93,7 @@ An example return value looks like this: ## Description -The browser automatically allocates memory when objects are created and frees it when they are not reachable anymore (garbage collection). This garbage collection (GC) is an approximation since the general problem of determining whether or not a specific piece of memory is still needed is impossible (see also [JavaScript Memory Management](/en-US/docs/Web/JavaScript/Memory_management)). Developers need to make sure that objects are garbage collected, memory isn't leaked, and memory usage doesn't grow unnecessarily over time leading to slow and unresponsive web applications. Memory leaks are typically introduced by forgetting to unregister an event listener, not closing a worker, accumulating objects in arrays, and more. +The browser automatically allocates memory when objects are created and frees it when they are not reachable anymore (garbage collection). This garbage collection (GC) is an approximation since the general problem of determining whether or not a specific piece of memory is still needed is impossible (see also [JavaScript Memory Management](/en-US/docs/Web/JavaScript/Guide/Memory_management)). Developers need to make sure that objects are garbage collected, memory isn't leaked, and memory usage doesn't grow unnecessarily over time leading to slow and unresponsive web applications. Memory leaks are typically introduced by forgetting to unregister an event listener, not closing a worker, accumulating objects in arrays, and more. The `measureUserAgentSpecificMemory()` API aggregates memory usage data to help you find memory leaks. It can be used for memory regression detection or for A/B testing features to evaluate their memory impact. Rather than make single calls to this method, it's better to make periodic calls to track how memory usage changes over the duration of a session. diff --git a/files/en-us/web/api/performance/memory/index.md b/files/en-us/web/api/performance/memory/index.md index f07d438970cd9ff..5b01be7c5f9289d 100644 --- a/files/en-us/web/api/performance/memory/index.md +++ b/files/en-us/web/api/performance/memory/index.md @@ -34,11 +34,11 @@ Returns an object with the following properties: Calling `performance.memory` returns an object like this: -```js +```json { - totalJSHeapSize: 39973671, - usedJSHeapSize: 39127515, - jsHeapSizeLimit: 4294705152 + "totalJSHeapSize": 39973671, + "usedJSHeapSize": 39127515, + "jsHeapSizeLimit": 4294705152 } ``` diff --git a/files/en-us/web/api/performance/resourcetimingbufferfull_event/index.md b/files/en-us/web/api/performance/resourcetimingbufferfull_event/index.md index 93dae593620d006..e683486aeb2cac5 100644 --- a/files/en-us/web/api/performance/resourcetimingbufferfull_event/index.md +++ b/files/en-us/web/api/performance/resourcetimingbufferfull_event/index.md @@ -14,10 +14,10 @@ The `resourcetimingbufferfull` event is fired when the browser's [resource timin Use the event name in methods like {{domxref("EventTarget.addEventListener", "addEventListener()")}}, or set an event handler property. -```js -addEventListener("resourcetimingbufferfull", (event) => {}); +```js-nolint +addEventListener("resourcetimingbufferfull", (event) => { }) -onresourcetimingbufferfull = (event) => {}; +onresourcetimingbufferfull = (event) => { } ``` ## Event type diff --git a/files/en-us/web/api/performance/timeorigin/index.md b/files/en-us/web/api/performance/timeorigin/index.md index 16901a3732fce4d..0eface7f1320f89 100644 --- a/files/en-us/web/api/performance/timeorigin/index.md +++ b/files/en-us/web/api/performance/timeorigin/index.md @@ -40,7 +40,7 @@ In worker.js self.addEventListener("connect", (event) => { const port = event.ports[0]; - port.onmessage = function (event) { + port.onmessage = (event) => { const workerTaskStart = performance.now(); // doSomeWork() const workerTaskEnd = performance.now(); diff --git a/files/en-us/web/api/performance_api/long_animation_frame_timing/index.md b/files/en-us/web/api/performance_api/long_animation_frame_timing/index.md index fa54bf79880b7ac..d6efa9f23f9dd82 100644 --- a/files/en-us/web/api/performance_api/long_animation_frame_timing/index.md +++ b/files/en-us/web/api/performance_api/long_animation_frame_timing/index.md @@ -78,7 +78,7 @@ Beyond the standard data returned by a {{domxref("PerformanceEntry")}} entry, th - {{domxref("PerformanceLongAnimationFrameTiming.blockingDuration", "blockingDuration")}} - : A {{domxref("DOMHighResTimeStamp")}} indicating the total time in milliseconds for which the main thread was blocked from responding to high priority tasks, such as user input. This is calculated by taking all the [long tasks](/en-US/docs/Web/API/PerformanceLongTaskTiming#description) within the LoAF that have a `duration` of more than `50ms`, subtracting `50ms` from each, adding the rendering time to the longest task time, and summing the results. - {{domxref("PerformanceLongAnimationFrameTiming.firstUIEventTimestamp", "firstUIEventTimestamp")}} - - : A {{domxref("DOMHighResTimeStamp")}} indicating the time of the first UI event — such as a mouse or keyboard event — to be queued during the current animation frame. + - : A {{domxref("DOMHighResTimeStamp")}} indicating the time of the first UI event — such as a mouse or keyboard event — to be processed during the current animation frame. Note this timestamp can be before the start of this animation frame if there was a delay between the event happening and it being processed. - {{domxref("PerformanceLongAnimationFrameTiming.renderStart", "renderStart")}} - : A {{domxref("DOMHighResTimeStamp")}} indicating the start time of the rendering cycle, which includes {{domxref("Window.requestAnimationFrame()")}} callbacks, style and layout calculation, {{domxref("ResizeObserver")}} callbacks, and {{domxref("IntersectionObserver")}} callbacks. - {{domxref("PerformanceLongAnimationFrameTiming.styleAndLayoutStart", "styleAndLayoutStart")}} @@ -97,12 +97,12 @@ Beyond the standard data returned by a {{domxref("PerformanceEntry")}} entry, th - : A {{domxref("DOMHighResTimeStamp")}} indicating the total time, in milliseconds, spent by the script on "pausing" synchronous operations (for example, {{domxref("Window.alert()")}} calls or synchronous {{domxref("XMLHttpRequest")}}s). - {{domxref("PerformanceScriptTiming.sourceCharPosition", "script.sourceCharPosition")}}, {{domxref("PerformanceScriptTiming.sourceFunctionName", "script.sourceFunctionName")}}, and {{domxref("PerformanceScriptTiming.sourceURL", "script.sourceURL")}} - - : Values representing the script character position, function name, and script URL, respectively. It is important to note that the reported function name will be the "entry point" of the script (i.e. the top level of the stack), and not any specific slow sub-function. + - : Values representing the script character position, function name, and script URL, respectively. It is important to note that the reported function name will be the "entry point" of the script (i.e., the top level of the stack), and not any specific slow sub-function. For example, if an event handler calls a top-level function, which in turn calls a slow sub-function, the `source*` fields will report the top-level function's name and location, not the slow sub-function. This is because of performance reasons — a full stack trace is costly. - {{domxref("PerformanceScriptTiming.windowAttribution", "script.windowAttribution")}} an {{domxref("PerformanceScriptTiming.window", "script.window")}} - - : An enumerated value describing the relationship of the container (i.e. either the top-level document or and {{htmlelement("iframe")}}) this script was executed in to the top-level document, and a reference to its {{domxref("Window")}} object. + - : An enumerated value describing the relationship of the container (i.e., either the top-level document or and {{htmlelement("iframe")}}) this script was executed in to the top-level document, and a reference to its {{domxref("Window")}} object. > [!NOTE] > Script attribution is provided only for scripts running in the main thread of a page, including same-origin `<iframe>`s. However, cross-origin `<iframe>`s, [web workers](/en-US/docs/Web/API/Web_Workers_API), [service workers](/en-US/docs/Web/API/Service_Worker_API), and [extension](/en-US/docs/Mozilla/Add-ons/WebExtensions) code will not have script attribution in long animation frames, even if they impact the duration of one. diff --git a/files/en-us/web/api/performance_api/monitoring_bfcache_blocking_reasons/index.md b/files/en-us/web/api/performance_api/monitoring_bfcache_blocking_reasons/index.md index a33e00667ea7ae0..4eb2e4e1c90924c 100644 --- a/files/en-us/web/api/performance_api/monitoring_bfcache_blocking_reasons/index.md +++ b/files/en-us/web/api/performance_api/monitoring_bfcache_blocking_reasons/index.md @@ -53,16 +53,14 @@ function returnNRR() { The code snippets shown above will log {{domxref("NotRestoredReasons")}} objects to the console. These objects have the following structure, which represents the blocked state of the top-level frame: -```js +```json { - children: [], - id: null, - name: null, - reasons: [ - { reason: "unload-listener" } - ], - src: "", - url: "example.com", + "children": [], + "id": null, + "name": null, + "reasons": [{ "reason": "unload-listener" }], + "src": "", + "url": "example.com" } ``` @@ -87,33 +85,31 @@ When a page has same-origin `<iframe>`s embedded, the returned `notRestoredReaso For example: -```js +```json { - children: [ + "children": [ { - children: [], - id: "iframe-id", - name: "iframe-name", - reasons: [], - src: "./index.html", - url: "https://www.example.com/iframe-examples.html" + "children": [], + "id": "iframe-id", + "name": "iframe-name", + "reasons": [], + "src": "./index.html", + "url": "https://www.example.com/iframe-examples.html" }, { - children: [], - id: "iframe-id2", - name: "iframe-name2", - reasons: [ - { "reason": "unload-listener" } - ], - src: "./unload-examples.html", - url: "https://www.example.com/unload-examples.html" - }, + "children": [], + "id": "iframe-id2", + "name": "iframe-name2", + "reasons": [{ "reason": "unload-listener" }], + "src": "./unload-examples.html", + "url": "https://www.example.com/unload-examples.html" + } ], - id: null, - name: null, - reasons: [], - src: null, - url:"https://www.example.com" + "id": null, + "name": null, + "reasons": [], + "src": null, + "url": "https://www.example.com" } ``` @@ -123,39 +119,36 @@ When a page has cross-origin frames embedded, the amount of information shared a For example: -```js +```json { - children: [ + "children": [ { - children: [], - id: "iframe-id", - name: "iframe-name", - reasons: [], - src: "https://www.example2.com/", - url: null + "children": [], + "id": "iframe-id", + "name": "iframe-name", + "reasons": [], + "src": "https://www.example2.com/", + "url": null } ], - id: null, - name: null, - reasons: [ - { "reason": "masked" } - ], - src: null, - url:"https://www.example.com" + "id": null, + "name": null, + "reasons": [{ "reason": "masked" }], + "src": null, + "url": "https://www.example.com" } - ``` For all the cross-origin `<iframe>`s, no blocking reasons are reported; for the top-level frame a reason of `"masked"` is reported, to indicate that the reasons are being kept hidden for privacy purposes. Note that `"masked"` may also be used for hiding user agent-specific reasons; it doesn't always indicate an issue in an `<iframe>`. ## Blocking reasons -There are many different reasons why blocking could occur, and browsers can choose to implement their own specific reasons for blocking, based on how they operate. Developers should avoid depending on specific wording for reasons and be prepared to handle new reasons being added and deleted. +There are many different reasons why blocking could occur. Although the reasons are standardized, developers should avoid depending on specific wording for reasons and be prepared to handle new reasons being added and deleted. -The initial values listed in the specification are: +The values listed in [the specification](https://html.spec.whatwg.org/multipage/nav-history-apis.html#the-notrestoredreasons-interface) are: - `"fetch"` - - : While unloading, a fetch initiated by the current document (e.g. via {{domxref("Window/fetch", "fetch()")}}) was canceled while ongoing. As a result, the page was not in a stable state that could be stored in the bfcache. + - : While unloading, a fetch initiated by the current document (e.g., via {{domxref("Window/fetch", "fetch()")}}) was canceled while ongoing. As a result, the page was not in a stable state that could be stored in the bfcache. - `"lock"` - : While unloading, held locks and lock requests were terminated, so the page was not in a stable state that could be stored in the bfcache. - `"masked"` @@ -169,14 +162,92 @@ The initial values listed in the specification are: - `"websocket"` - : While unloading, an open [WebSocket](/en-US/docs/Web/API/WebSockets_API) connect was shut down, so the page was not in a stable state that could be stored in the bfcache. -Additional blocking reasons may be used by some browsers, for example: - -- `"unload-listener"` - - : The page registers an [`unload`](/en-US/docs/Web/API/Window/unload_event) handler, which prevents bfcache usage. This serves as a useful warning, as `unload` is deprecated. See [usage notes](/en-US/docs/Web/API/Window/unload_event#usage_notes) for more information. +### User-agent specific blocking reasons + +Additional blocking reasons that may be used by some browsers are also specified: + +- `"audio-capture"` + - : The Document requested audio capture permission by using Media Capture and Streams's [`getUserMedia()`](/en-US/docs/Web/API/MediaDevices/getUserMedia) with audio. +- `"background-work"` + - : The Document requested background work by calling [`SyncManager`](/en-US/docs/Web/API/SyncManager)'s [`register()`](/en-US/docs/Web/API/SyncManager/register) method, [`PeriodicSyncManager`](/en-US/docs/Web/API/PeriodicSyncManager)'s [`register()`](/en-US/docs/Web/API/PeriodicSyncManager/register) method, or [`BackgroundFetchManager`](/en-US/docs/Web/API/BackgroundFetchManager)'s [`fetch()`](/en-US/docs/Web/API/BackgroundFetchManager/fetch) method. +- `"broadcastchannel-message"` + - : While the page was stored in back/forward cache, a [`BroadcastChannel`](/en-US/docs/Web/API/BroadcastChannel) connection on the page received a message and message event was fired. +- `"idbversionchangeevent"` + - : The Document had a pending [`IDBVersionChangeEvent`](/en-US/docs/Web/API/IDBVersionChangeEvent) while unloading. +- `"idledetector"` + - : The Document had an active [`IdleDetector`](/en-US/docs/Web/API/IdleDetector) while unloading. +- `"keyboardlock"` + - : While unloading, keyboard lock was still active because [`Keyboard`](/en-US/docs/Web/API/Keyboard)'s [`lock()`](/en-US/docs/Web/API/Keyboard/lock) method was called. +- `"mediastream"` + - : A [MediaStreamTrack](/en-US/docs/Web/API/MediaStreamTrack) was in the live state upon unloading. +- `"midi"` + - : The Document requested a MIDI permission by calling [`navigator.requestMIDIAccess()`](/en-US/docs/Web/API/Navigator/requestMIDIAccess). +- `"modals"` + - : User prompts were shown while unloading. +- `"navigating"` + - : While unloading, loading was still ongoing, and so the Document was not in a state that could be stored in back/forward cache. +- `"navigation-canceled"` + - : The navigation request was canceled by calling [`window.stop()`](/en-US/docs/Web/API/Window/stop) and the page was not in a state to be stored in back/forward cache. +- `"non-trivial-browsing-context-group"` + - : The browsing context group of this Document had more than one top-level browsing context. +- `"otpcredential"` + - : The Document created an [`OTPCredential`](/en-US/docs/Web/API/OTPCredential). +- `"outstanding-network-request"` + - : While unloading, the Document had outstanding network requests and was not in a state that could be stored in back/forward cache. +- `"paymentrequest"` + - : The Document had an active [`PaymentRequest`](/en-US/docs/Web/API/PaymentRequest) while unloading. +- `"pictureinpicturewindow"` + - : The Document had an active [`PictureInPictureWindow`](/en-US/docs/Web/API/PictureInPictureWindow) while unloading. +- `"plugins"` + - : The Document contained plugins. +- `"request-method-not-get"` + - : The Document was created from an HTTP request whose method was not {{httpmethod("GET")}}. +- `"response-auth-required"` + - : The Document was created from an HTTP response that required HTTP authentication. - `"response-cache-control-no-store"` - - : The page uses `no-store` as a {{httpheader("Cache-Control")}} header value. -- `"related-active-contents"` - - : The page was opened from another page that still has a reference to this page, for example using "duplicate tab" functionality. + - : The Document was created from an HTTP response whose {{httpheader("Cache-Control")}} header included the "no-store" token. +- `"response-cache-control-no-cache"` + - : The Document was created from an HTTP response whose {{httpheader("Cache-Control")}} header included the "no-cache" token. +- `"response-keep-alive"` + - : The Document was created from an HTTP response that contained a {{httpheader("Keep-Alive")}} header. +- `"response-scheme-not-http-or-https"` + - : The Document was created from a response whose URL's scheme was not an HTTP(S) scheme. +- `"response-status-not-ok"` + - : The Document was created from an HTTP response whose status was not an ok status. +- `"rtc"` + - : While unloading, a [`RTCPeerConnection`](/en-US/docs/Web/API/RTCPeerConnection) or [`RTCDataChannel`](/en-US/docs/Web/API/RTCDataChannel) was shut down, so the page was not in a state that could be stored in the back/forward cache. +- `"sensors"` + - : The Document requested sensor access. +- `"serviceworker-added"` + - : The Document's service worker client started to be controlled by a [service worker](/en-US/docs/Web/API/Service_Worker_API) while the page was in back/forward cache. +- `"serviceworker-claimed"` + - : The Document's service worker client's active [service worker](/en-US/docs/Web/API/Service_Worker_API) was claimed while the page was in back/forward cache. +- `"serviceworker-postmessage"` + - : The Document's service worker client's active [service worker](/en-US/docs/Web/API/Service_Worker_API) received a message while the page was in back/forward cache. +- `"serviceworker-version-activated"` + - : The Document's service worker client's active [service worker](/en-US/docs/Web/API/Service_Worker_API)'s version was activated while the page was in back/forward cache. +- `"serviceworker-unregistered"` + - : The Document's service worker client's active [service worker](/en-US/docs/Web/API/Service_Worker_API)'s service worker registration was unregistered while the page was in back/forward cache. +- `"sharedworker"` + - : This Document was in the owner set of a [`SharedWorkerGlobalScope`](/en-US/docs/Web/API/SharedWorkerGlobalScope). +- `"smartcardconnection"` + - : The Document had an active `SmartCardConnection` while unloading. +- `"speechrecognition"` + - : The Document had an active [`SpeechRecognition`](/en-US/docs/Web/API/SpeechRecognition) while unloading. +- `"storageaccess"` + - : The Document requested storage access permission by using the [Storage Access API](/en-US/docs/Web/API/Storage_Access_API). +- `"unload-listener"` + - : The Document registered an event listener for the [`unload` event](/en-US/docs/Web/API/Window/unload_event). +- `"video-capture"` + - : The Document requested video capture permission by using Media Capture and Streams's [`getUserMedia()`](/en-US/docs/Web/API/MediaDevices/getUserMedia) with video. +- `"webhid"` + - : The Document called the [WebHID API](/en-US/docs/Web/API/WebHID_API)'s [`requestDevice()`](/en-US/docs/Web/API/HID/requestDevice) method. +- `"webshare"` + - : The Document used the [Web Share API](/en-US/docs/Web/API/Web_Share_API)'s [`navigator.share()`](/en-US/docs/Web/API/Navigator/share) method. +- `"webtransport"` + - : While unloading, an open [`WebTransport`](/en-US/docs/Web/API/WebTransport) connection was shut down, so the page was not in a state that could be stored in the back/forward cache. +- `"webxrdevice"` + - : The Document created a [XRSystem](/en-US/docs/Web/API/XRSystem). ## Browser compatibility diff --git a/files/en-us/web/api/performance_api/performance_data/index.md b/files/en-us/web/api/performance_api/performance_data/index.md index 5bd3f16ce31c69c..1cd685d264e1f7f 100644 --- a/files/en-us/web/api/performance_api/performance_data/index.md +++ b/files/en-us/web/api/performance_api/performance_data/index.md @@ -108,7 +108,7 @@ The `PerformanceObserver` option is preferred because: ## Managing buffer sizes -There is a buffer limit for performance entries for each global object. It ensures that the browser doesn't consume indefinite memory when holding performance data. Especially when your website or application fetches a lot of resources (e.g. when using polling), you might need to look into the limits for the buffers: +There is a buffer limit for performance entries for each global object. It ensures that the browser doesn't consume indefinite memory when holding performance data. Especially when your website or application fetches a lot of resources (e.g., when using polling), you might need to look into the limits for the buffers: | {{domxref("PerformanceEntry.entryType", "entryType")}} identifier | Interface | Maximum number of buffer entries | | ----------------------------------------------------------------- | ------------------------------------------ | -------------------------------- | diff --git a/files/en-us/web/api/performanceelementtiming/element/index.md b/files/en-us/web/api/performanceelementtiming/element/index.md index a836205755a7ab6..2df759302d2b826 100644 --- a/files/en-us/web/api/performanceelementtiming/element/index.md +++ b/files/en-us/web/api/performanceelementtiming/element/index.md @@ -20,7 +20,7 @@ An {{domxref("Element")}}, or [`null`](/en-US/docs/Web/JavaScript/Reference/Oper ### Logging the observed element -In this example an {{HTMLElement("img")}} element is being observed by adding the [`elementtiming`](/en-US/docs/Web/HTML/Attributes/elementtiming) attribute. A {{domxref("PerformanceObserver")}} is registered to get all performance entries of type `"element"` and the `buffered` flag is used to access data from before observer creation. The DOM element that is observed is logged to the console. +In this example an {{HTMLElement("img")}} element is being observed by adding the [`elementtiming`](/en-US/docs/Web/HTML/Reference/Attributes/elementtiming) attribute. A {{domxref("PerformanceObserver")}} is registered to get all performance entries of type `"element"` and the `buffered` flag is used to access data from before observer creation. The DOM element that is observed is logged to the console. ```html <img src="image.jpg" alt="a nice image" elementtiming="big-image" /> diff --git a/files/en-us/web/api/performanceelementtiming/id/index.md b/files/en-us/web/api/performanceelementtiming/id/index.md index b5db29dffb03906..286244663764a15 100644 --- a/files/en-us/web/api/performanceelementtiming/id/index.md +++ b/files/en-us/web/api/performanceelementtiming/id/index.md @@ -10,7 +10,7 @@ browser-compat: api.PerformanceElementTiming.id {{APIRef("Performance API")}}{{SeeCompatTable}} -The **`id`** read-only property of the {{domxref("PerformanceElementTiming")}} interface returns the [`id`](/en-US/docs/Web/HTML/Global_attributes/id) of the associated element. +The **`id`** read-only property of the {{domxref("PerformanceElementTiming")}} interface returns the [`id`](/en-US/docs/Web/HTML/Reference/Global_attributes/id) of the associated element. ## Value @@ -20,7 +20,7 @@ A string. ### Using `id` -In this example an {{HTMLElement("img")}} element is being observed by adding the [`elementtiming`](/en-US/docs/Web/HTML/Attributes/elementtiming) attribute. A {{domxref("PerformanceObserver")}} is registered to get all performance entries of type `"element"` and the `buffered` flag is used to access data from before observer creation. It will log `myImage` to the console, this being the [`id`](/en-US/docs/Web/HTML/Global_attributes/id) of the image element. +In this example an {{HTMLElement("img")}} element is being observed by adding the [`elementtiming`](/en-US/docs/Web/HTML/Reference/Attributes/elementtiming) attribute. A {{domxref("PerformanceObserver")}} is registered to get all performance entries of type `"element"` and the `buffered` flag is used to access data from before observer creation. It will log `myImage` to the console, this being the [`id`](/en-US/docs/Web/HTML/Reference/Global_attributes/id) of the image element. ```html <img diff --git a/files/en-us/web/api/performanceelementtiming/identifier/index.md b/files/en-us/web/api/performanceelementtiming/identifier/index.md index 4ab06deb8481bf3..b8a7c2109716363 100644 --- a/files/en-us/web/api/performanceelementtiming/identifier/index.md +++ b/files/en-us/web/api/performanceelementtiming/identifier/index.md @@ -10,7 +10,7 @@ browser-compat: api.PerformanceElementTiming.identifier {{APIRef("Performance API")}}{{SeeCompatTable}} -The **`identifier`** read-only property of the {{domxref("PerformanceElementTiming")}} interface returns the value of the [`elementtiming`](/en-US/docs/Web/HTML/Attributes/elementtiming) attribute on the element. +The **`identifier`** read-only property of the {{domxref("PerformanceElementTiming")}} interface returns the value of the [`elementtiming`](/en-US/docs/Web/HTML/Reference/Attributes/elementtiming) attribute on the element. ## Value @@ -20,7 +20,7 @@ A string. ### Using `identifier` -In this example an {{HTMLElement("img")}} element is being observed by adding the [`elementtiming`](/en-US/docs/Web/HTML/Attributes/elementtiming) attribute. A {{domxref("PerformanceObserver")}} is registered to get all performance entries of type `"element"` and the `buffered` flag is used to access data from before observer creation. The value of [`elementtiming`](/en-US/docs/Web/HTML/Attributes/elementtiming) is `big-image`. Calling `entry.identifier` therefore returns the string `big-image`. +In this example an {{HTMLElement("img")}} element is being observed by adding the [`elementtiming`](/en-US/docs/Web/HTML/Reference/Attributes/elementtiming) attribute. A {{domxref("PerformanceObserver")}} is registered to get all performance entries of type `"element"` and the `buffered` flag is used to access data from before observer creation. The value of [`elementtiming`](/en-US/docs/Web/HTML/Reference/Attributes/elementtiming) is `big-image`. Calling `entry.identifier` therefore returns the string `big-image`. ```html <img diff --git a/files/en-us/web/api/performanceelementtiming/index.md b/files/en-us/web/api/performanceelementtiming/index.md index 965160136cf51c2..25905e55168ec92 100644 --- a/files/en-us/web/api/performanceelementtiming/index.md +++ b/files/en-us/web/api/performanceelementtiming/index.md @@ -9,7 +9,7 @@ browser-compat: api.PerformanceElementTiming {{APIRef("Performance API")}}{{SeeCompatTable}} -The **`PerformanceElementTiming`** interface contains render timing information for image and text node elements the developer annotated with an [`elementtiming`](/en-US/docs/Web/HTML/Attributes/elementtiming) attribute for observation. +The **`PerformanceElementTiming`** interface contains render timing information for image and text node elements the developer annotated with an [`elementtiming`](/en-US/docs/Web/HTML/Reference/Attributes/elementtiming) attribute for observation. ## Description @@ -19,11 +19,11 @@ The API supports timing information on the following elements: - {{htmlelement("img")}} elements, - {{SVGElement("image")}} elements inside an {{SVGElement("svg")}}, -- [poster](/en-US/docs/Web/HTML/Element/video#poster) images of {{htmlelement("video")}} elements, +- [poster](/en-US/docs/Web/HTML/Reference/Elements/video#poster) images of {{htmlelement("video")}} elements, - elements which have a contentful {{cssxref("background-image")}} property with a URL value for a resource that is actually available, and - groups of text nodes, such as a {{htmlelement("p")}}. -The author flags an element for observation by adding the [`elementtiming`](/en-US/docs/Web/HTML/Attributes/elementtiming) attribute on the element. +The author flags an element for observation by adding the [`elementtiming`](/en-US/docs/Web/HTML/Reference/Attributes/elementtiming) attribute on the element. `PerformanceElementTiming` inherits from {{domxref("PerformanceEntry")}}. @@ -47,9 +47,9 @@ This interface also supports the following properties: - {{domxref("PerformanceElementTiming.element")}} {{ReadOnlyInline}} {{Experimental_Inline}} - : An {{domxref("Element")}} representing the element we are returning information about. - {{domxref("PerformanceElementTiming.id")}} {{ReadOnlyInline}} {{Experimental_Inline}} - - : A string which is the [`id`](/en-US/docs/Web/HTML/Global_attributes/id) of the element. + - : A string which is the [`id`](/en-US/docs/Web/HTML/Reference/Global_attributes/id) of the element. - {{domxref("PerformanceElementTiming.identifier")}} {{ReadOnlyInline}} {{Experimental_Inline}} - - : A string which is the value of the [`elementtiming`](/en-US/docs/Web/HTML/Attributes/for) attribute on the element. + - : A string which is the value of the [`elementtiming`](/en-US/docs/Web/HTML/Reference/Attributes/for) attribute on the element. - {{domxref("PerformanceElementTiming.intersectionRect")}} {{ReadOnlyInline}} {{Experimental_Inline}} - : A {{domxref("DOMRectReadOnly")}} which is the rectangle of the element within the viewport. - {{domxref("PerformanceElementTiming.loadTime")}} {{ReadOnlyInline}} {{Experimental_Inline}} @@ -72,7 +72,7 @@ This interface also supports the following properties: ### Observing render time of specific elements -In this example two elements are being observed by adding the [`elementtiming`](/en-US/docs/Web/HTML/Attributes/elementtiming) attribute. A {{domxref("PerformanceObserver")}} is registered to get all performance entries of type `"element"` and the `buffered` flag is used to access data from before observer creation. +In this example two elements are being observed by adding the [`elementtiming`](/en-US/docs/Web/HTML/Reference/Attributes/elementtiming) attribute. A {{domxref("PerformanceObserver")}} is registered to get all performance entries of type `"element"` and the `buffered` flag is used to access data from before observer creation. ```html <img src="image.jpg" elementtiming="big-image" /> @@ -100,4 +100,4 @@ Two entries will be output to the console. The first containing details of the i ## See also -- [`elementtiming`](/en-US/docs/Web/HTML/Attributes/elementtiming) HTML attribute +- [`elementtiming`](/en-US/docs/Web/HTML/Reference/Attributes/elementtiming) HTML attribute diff --git a/files/en-us/web/api/performanceelementtiming/intersectionrect/index.md b/files/en-us/web/api/performanceelementtiming/intersectionrect/index.md index 14d44b6a8658a7e..3650715b085e137 100644 --- a/files/en-us/web/api/performanceelementtiming/intersectionrect/index.md +++ b/files/en-us/web/api/performanceelementtiming/intersectionrect/index.md @@ -22,7 +22,7 @@ For display images this is the display rectangle of the image within the viewpor ### Logging `intersectionRect` -In this example an {{HTMLElement("img")}} element is being observed by adding the [`elementtiming`](/en-US/docs/Web/HTML/Attributes/elementtiming) attribute. A {{domxref("PerformanceObserver")}} is registered to get all performance entries of type `"element"` and the `buffered` flag is used to access data from before observer creation. Calling `entry.intersectionRect` returns a {{domxref("DOMRectReadOnly")}} object with the display rectangle of the image. +In this example an {{HTMLElement("img")}} element is being observed by adding the [`elementtiming`](/en-US/docs/Web/HTML/Reference/Attributes/elementtiming) attribute. A {{domxref("PerformanceObserver")}} is registered to get all performance entries of type `"element"` and the `buffered` flag is used to access data from before observer creation. Calling `entry.intersectionRect` returns a {{domxref("DOMRectReadOnly")}} object with the display rectangle of the image. ```html <img diff --git a/files/en-us/web/api/performanceelementtiming/loadtime/index.md b/files/en-us/web/api/performanceelementtiming/loadtime/index.md index f2bee7e463dea1f..3a571dfe3cf1a75 100644 --- a/files/en-us/web/api/performanceelementtiming/loadtime/index.md +++ b/files/en-us/web/api/performanceelementtiming/loadtime/index.md @@ -20,7 +20,7 @@ A {{domxref("DOMHighResTimeStamp")}} with the `loadTime` of the element. Always ### Logging `loadTime` -In this example an {{HTMLElement("img")}} element is being observed by adding the [`elementtiming`](/en-US/docs/Web/HTML/Attributes/elementtiming) attribute. A {{domxref("PerformanceObserver")}} is registered to get all performance entries of type `"element"`. The `buffered` flag is used to access data from before the observer was created. Calling `entry.loadTime` returns the loadTime of the image element. +In this example an {{HTMLElement("img")}} element is being observed by adding the [`elementtiming`](/en-US/docs/Web/HTML/Reference/Attributes/elementtiming) attribute. A {{domxref("PerformanceObserver")}} is registered to get all performance entries of type `"element"`. The `buffered` flag is used to access data from before the observer was created. Calling `entry.loadTime` returns the loadTime of the image element. ```html <img diff --git a/files/en-us/web/api/performanceelementtiming/naturalheight/index.md b/files/en-us/web/api/performanceelementtiming/naturalheight/index.md index 5774fc21c7e1de8..7369bc072be44c4 100644 --- a/files/en-us/web/api/performanceelementtiming/naturalheight/index.md +++ b/files/en-us/web/api/performanceelementtiming/naturalheight/index.md @@ -20,7 +20,7 @@ An unsigned 32-bit integer (unsigned long) which is the intrinsic height of the ### Logging `naturalHeight` -In this example an {{HTMLElement("img")}} element is being observed by adding the [`elementtiming`](/en-US/docs/Web/HTML/Attributes/elementtiming) attribute. A {{domxref("PerformanceObserver")}} is registered to get all performance entries of type `"element"` and the `buffered` flag is used to access data from before observer creation. The image file has a width of 1000px and a height of 750px. Calling `entry.naturalHeight` returns `750`, that being the intrinsic height in pixels. +In this example an {{HTMLElement("img")}} element is being observed by adding the [`elementtiming`](/en-US/docs/Web/HTML/Reference/Attributes/elementtiming) attribute. A {{domxref("PerformanceObserver")}} is registered to get all performance entries of type `"element"` and the `buffered` flag is used to access data from before observer creation. The image file has a width of 1000px and a height of 750px. Calling `entry.naturalHeight` returns `750`, that being the intrinsic height in pixels. ```html <img diff --git a/files/en-us/web/api/performanceelementtiming/naturalwidth/index.md b/files/en-us/web/api/performanceelementtiming/naturalwidth/index.md index 78dee4e9047a9b6..0877a549fdb4b8a 100644 --- a/files/en-us/web/api/performanceelementtiming/naturalwidth/index.md +++ b/files/en-us/web/api/performanceelementtiming/naturalwidth/index.md @@ -20,7 +20,7 @@ An unsigned 32-bit integer (unsigned long) which is the intrinsic width of the i ### Logging `naturalWidth` -In this example an {{HTMLElement("img")}} element is being observed by adding the [`elementtiming`](/en-US/docs/Web/HTML/Attributes/elementtiming) attribute. A {{domxref("PerformanceObserver")}} is registered to get all performance entries of type `"element"` and the `buffered` flag is used to access data from before observer creation. The image file has a width of 1000px and a height of 750px. Calling `entry.naturalWidth` returns `1000`, that being the intrinsic width in pixels. +In this example an {{HTMLElement("img")}} element is being observed by adding the [`elementtiming`](/en-US/docs/Web/HTML/Reference/Attributes/elementtiming) attribute. A {{domxref("PerformanceObserver")}} is registered to get all performance entries of type `"element"` and the `buffered` flag is used to access data from before observer creation. The image file has a width of 1000px and a height of 750px. Calling `entry.naturalWidth` returns `1000`, that being the intrinsic width in pixels. ```html <img diff --git a/files/en-us/web/api/performanceelementtiming/rendertime/index.md b/files/en-us/web/api/performanceelementtiming/rendertime/index.md index fa7326bc4681d68..264f057308dcaa7 100644 --- a/files/en-us/web/api/performanceelementtiming/rendertime/index.md +++ b/files/en-us/web/api/performanceelementtiming/rendertime/index.md @@ -16,7 +16,7 @@ The **`renderTime`** read-only property of the {{domxref("PerformanceElementTimi A {{domxref("DOMHighResTimeStamp")}} with the render time of the element. -For images this will be the **image rendering timestamp**. This is defined as the next paint that occurs after the image becomes fully loaded. If the timing allow check fails (as defined by the [Timing-allow-origin](/en-US/docs/Web/HTTP/Headers/Timing-Allow-Origin) header) this will return `0`. +For images this will be the **image rendering timestamp**. This is defined as the next paint that occurs after the image becomes fully loaded. If the timing allow check fails (as defined by the [Timing-allow-origin](/en-US/docs/Web/HTTP/Reference/Headers/Timing-Allow-Origin) header) this will return `0`. For text nodes this will be the **text rendering timestamp**. This is defined as when the element becomes text painted. @@ -24,7 +24,7 @@ For text nodes this will be the **text rendering timestamp**. This is defined as ### Logging `renderTime` -In this example an {{HTMLElement("img")}} element is being observed by adding the [`elementtiming`](/en-US/docs/Web/HTML/Attributes/elementtiming) attribute. A {{domxref("PerformanceObserver")}} is registered to get all performance entries of type `"element"` and the `buffered` flag is used to access data from before observer creation. Calling `entry.renderTime` returns the render time of the image element. +In this example an {{HTMLElement("img")}} element is being observed by adding the [`elementtiming`](/en-US/docs/Web/HTML/Reference/Attributes/elementtiming) attribute. A {{domxref("PerformanceObserver")}} is registered to get all performance entries of type `"element"` and the `buffered` flag is used to access data from before observer creation. Calling `entry.renderTime` returns the render time of the image element. ```html <img @@ -64,7 +64,7 @@ Alternatively, you can use {{domxref("PerformanceEntry.startTime", "startTime")} If you use `startTime`, you can flag any inaccuracies by checking if `renderTime` was used: ```js -const isRenderTime = entry.renderTime ? true : false; +const isRenderTime = Boolean(entry.renderTime); ``` ## Specifications diff --git a/files/en-us/web/api/performanceelementtiming/url/index.md b/files/en-us/web/api/performanceelementtiming/url/index.md index ec06f56779967ef..606428f9108b55a 100644 --- a/files/en-us/web/api/performanceelementtiming/url/index.md +++ b/files/en-us/web/api/performanceelementtiming/url/index.md @@ -20,7 +20,7 @@ A string which is the initial URL of the resources request for images or `0` for ### Logging `url` -In this example an {{HTMLElement("img")}} element is being observed by adding the [`elementtiming`](/en-US/docs/Web/HTML/Attributes/elementtiming) attribute. A {{domxref("PerformanceObserver")}} is registered to get all performance entries of type `"element"` and the `buffered` flag is used to access data from before observer creation. Calling `entry.url` returns `https://example.com/image.jpg`. +In this example an {{HTMLElement("img")}} element is being observed by adding the [`elementtiming`](/en-US/docs/Web/HTML/Reference/Attributes/elementtiming) attribute. A {{domxref("PerformanceObserver")}} is registered to get all performance entries of type `"element"` and the `buffered` flag is used to access data from before observer creation. Calling `entry.url` returns `https://example.com/image.jpg`. ```html <img diff --git a/files/en-us/web/api/performanceentry/starttime/index.md b/files/en-us/web/api/performanceentry/starttime/index.md index 4a484808a86615f..8d0b2086b0836fe 100644 --- a/files/en-us/web/api/performanceentry/starttime/index.md +++ b/files/en-us/web/api/performanceentry/starttime/index.md @@ -20,9 +20,9 @@ The meaning of this property depends on the value of this performance entry's {{ - `element` - : Either the value of this entry's {{domxref("PerformanceElementTiming.renderTime", "renderTime")}} if it is not `0`, otherwise the value of this entry's {{domxref("PerformanceElementTiming.loadTime", "loadTime")}}. - `event` - - : The time the event was created, i.e. the event's [`timeStamp`](/en-US/docs/Web/API/Event/timeStamp) property. + - : The time the event was created, i.e., the event's [`timeStamp`](/en-US/docs/Web/API/Event/timeStamp) property. - `first-input` - - : The time the first input event was created, i.e. that event's [`timeStamp`](/en-US/docs/Web/API/Event/timeStamp). + - : The time the first input event was created, i.e., that event's [`timeStamp`](/en-US/docs/Web/API/Event/timeStamp). - `largest-contentful-paint` - : The value of this entry's {{domxref("LargestContentfulPaint.renderTime", "renderTime")}} if it is not `0`, otherwise the value of this entry's {{domxref("LargestContentfulPaint.loadTime", "loadTime")}}. - `layout-shift` diff --git a/files/en-us/web/api/performancelonganimationframetiming/firstuieventtimestamp/index.md b/files/en-us/web/api/performancelonganimationframetiming/firstuieventtimestamp/index.md index 19fdadaee932387..ea03843a9d3e73d 100644 --- a/files/en-us/web/api/performancelonganimationframetiming/firstuieventtimestamp/index.md +++ b/files/en-us/web/api/performancelonganimationframetiming/firstuieventtimestamp/index.md @@ -10,7 +10,7 @@ browser-compat: api.PerformanceLongAnimationFrameTiming.firstUIEventTimestamp {{SeeCompatTable}}{{APIRef("Performance API")}} -The **`firstUIEventTimestamp`** read-only property of the {{domxref("PerformanceLongAnimationFrameTiming")}} interface returns a {{domxref("DOMHighResTimeStamp")}} indicating the time of the first UI event — such as a mouse or keyboard event — to be queued during the current animation frame. +The **`firstUIEventTimestamp`** read-only property of the {{domxref("PerformanceLongAnimationFrameTiming")}} interface returns a {{domxref("DOMHighResTimeStamp")}} indicating the time of the first UI event — such as a mouse or keyboard event — to be processed during the current animation frame. Note this timestamp can be before the start of this animation frame if there was a delay between the event happening and it being processed. ## Value diff --git a/files/en-us/web/api/performancenavigationtiming/activationstart/index.md b/files/en-us/web/api/performancenavigationtiming/activationstart/index.md index 9e05844d99dafb4..74afebf1bb960f0 100644 --- a/files/en-us/web/api/performancenavigationtiming/activationstart/index.md +++ b/files/en-us/web/api/performancenavigationtiming/activationstart/index.md @@ -50,9 +50,9 @@ let firstContentfulPaint = performance.getEntriesByName( "first-contentful-paint", )[0].startTime; -console.log("time to first paint: " + (firstPaint - activationStart)); +console.log(`time to first paint: ${firstPaint - activationStart}`); console.log( - "time to first-contentful-paint: " + (firstContentfulPaint - activationStart), + `time to first-contentful-paint: ${firstContentfulPaint - activationStart}`, ); ``` diff --git a/files/en-us/web/api/performancenavigationtiming/criticalchrestart/index.md b/files/en-us/web/api/performancenavigationtiming/criticalchrestart/index.md index 6d6df3b28bf3511..97b58a6fae02f83 100644 --- a/files/en-us/web/api/performancenavigationtiming/criticalchrestart/index.md +++ b/files/en-us/web/api/performancenavigationtiming/criticalchrestart/index.md @@ -10,7 +10,7 @@ browser-compat: api.PerformanceNavigationTiming.criticalCHRestart {{APIRef("Performance API")}}{{SeeCompatTable}} -A website can indicate that a particular [Client Hint](/en-US/docs/Web/HTTP/Client_hints) is critical to the page by including it in a {{HTTPHeader("Critical-CH")}} HTTP response header (as well as the {{HTTPHeader("Accept-CH")}} HTTP request header which is needed for all client hints whether critical or not). Doing so will trigger a connection restart if the hint listed in the `Critical-CH` HTTP response header could have been, but wasn't, included in the HTTP request initially sent. If the browser does not support that client hint, it is ignored and no connection restart occurs. +A website can indicate that a particular [Client Hint](/en-US/docs/Web/HTTP/Guides/Client_hints) is critical to the page by including it in a {{HTTPHeader("Critical-CH")}} HTTP response header (as well as the {{HTTPHeader("Accept-CH")}} HTTP request header which is needed for all client hints whether critical or not). Doing so will trigger a connection restart if the hint listed in the `Critical-CH` HTTP response header could have been, but wasn't, included in the HTTP request initially sent. If the browser does not support that client hint, it is ignored and no connection restart occurs. The **`criticalCHRestart`** read-only property represents the time at which the connection restart occurred. @@ -44,7 +44,7 @@ if (restartTime > 0) { ## See also -- [Client hints](/en-US/docs/Web/HTTP/Client_hints) +- [Client hints](/en-US/docs/Web/HTTP/Guides/Client_hints) - [User-Agent Client Hints API](/en-US/docs/Web/API/User-Agent_Client_Hints_API) - [Improving user privacy and developer experience with User-Agent Client Hints](https://developer.chrome.com/docs/privacy-security/user-agent-client-hints) (developer.chrome.com) - {{HTTPHeader("Accept-CH")}} diff --git a/files/en-us/web/api/performancenavigationtiming/notrestoredreasons/index.md b/files/en-us/web/api/performancenavigationtiming/notrestoredreasons/index.md index 4f7bea406ee63d8..17b41bb854f6479 100644 --- a/files/en-us/web/api/performancenavigationtiming/notrestoredreasons/index.md +++ b/files/en-us/web/api/performancenavigationtiming/notrestoredreasons/index.md @@ -39,16 +39,14 @@ function returnNRR() { The `PerformanceNavigationTiming.notRestoredReasons` property returns an object with the following structure, which provides reasons why the current document was blocked from using the bfcache. In this example the top-level frame has no embedded child `<iframe>`s: -```js +```json { - children: [], - id: null, - name: null, - reasons: [ - { reason: "unload-listener" } - ], - src: "", - url: "example.com", + "children": [], + "id": null, + "name": null, + "reasons": [{ "reason": "unload-listener" }], + "src": "", + "url": "example.com" } ``` diff --git a/files/en-us/web/api/performancenavigationtiming/type/index.md b/files/en-us/web/api/performancenavigationtiming/type/index.md index 1eb1b737d99294c..88d575a98de202f 100644 --- a/files/en-us/web/api/performancenavigationtiming/type/index.md +++ b/files/en-us/web/api/performancenavigationtiming/type/index.md @@ -25,7 +25,7 @@ The `type` property can have the following values: - `"back_forward"` - : Navigation is through the browser's history traversal operation. - `"prerender"` - - : Navigation is initiated by a [prerender hint](/en-US/docs/Web/HTML/Attributes/rel/prerender). + - : Navigation is initiated by a [prerender hint](/en-US/docs/Web/HTML/Reference/Attributes/rel/prerender). ## Examples diff --git a/files/en-us/web/api/performanceresourcetiming/contenttype/index.md b/files/en-us/web/api/performanceresourcetiming/contenttype/index.md index 8ca0ccb1d96b071..8622c7da1c9b61c 100644 --- a/files/en-us/web/api/performanceresourcetiming/contenttype/index.md +++ b/files/en-us/web/api/performanceresourcetiming/contenttype/index.md @@ -32,7 +32,7 @@ This may be one of the following values: - MIME type/subtype - : Any other MIME type/subtype supported by the user agent. - `""` (empty string) - - : Returned for MIME types that are not supported by the browser, or if the resource fetch failed due to [CORS](/en-US/docs/Web/HTTP/CORS) checks. + - : Returned for MIME types that are not supported by the browser, or if the resource fetch failed due to [CORS](/en-US/docs/Web/HTTP/Guides/CORS) checks. ## Examples @@ -45,9 +45,9 @@ The `buffered` option is used for accessing entries from before the observer cre ```js const observer = new PerformanceObserver((list) => { - const javascriptResources = list.getEntries().filter((entry) => { - return entry.contentType === "text/javascript"; - }); + const javascriptResources = list + .getEntries() + .filter((entry) => entry.contentType === "text/javascript"); console.log(javascriptResources); }); @@ -57,9 +57,9 @@ observer.observe({ type: "resource", buffered: true }); The following example uses {{domxref("Performance.getEntriesByType()")}}, which only shows `resource` performance entries present in the browser's performance timeline at the time you call the method. ```js -const scripts = performance.getEntriesByType("resource").filter((entry) => { - return entry.contentType === "text/javascript"; -}); +const scripts = performance + .getEntriesByType("resource") + .filter((entry) => entry.contentType === "text/javascript"); console.log(scripts); ``` diff --git a/files/en-us/web/api/performanceresourcetiming/deliverytype/index.md b/files/en-us/web/api/performanceresourcetiming/deliverytype/index.md index 3ec46d42623dd81..683bb7e7995452a 100644 --- a/files/en-us/web/api/performanceresourcetiming/deliverytype/index.md +++ b/files/en-us/web/api/performanceresourcetiming/deliverytype/index.md @@ -33,9 +33,9 @@ The following example uses a {{domxref("PerformanceObserver")}} to notify of new ```js const observer = new PerformanceObserver((list) => { - const cachedResources = list.getEntries().filter((entry) => { - return entry.deliveryType === "cache"; - }); + const cachedResources = list + .getEntries() + .filter((entry) => entry.deliveryType === "cache"); console.log(cachedResources); }); @@ -45,9 +45,9 @@ observer.observe({ type: "resource", buffered: true }); The following example uses {{domxref("Performance.getEntriesByType()")}}, which only shows `resource` performance entries present in the browser's performance timeline at the time you call the method. ```js -const scripts = performance.getEntriesByType("resource").filter((entry) => { - return entry.deliveryType === "cache"; -}); +const scripts = performance + .getEntriesByType("resource") + .filter((entry) => entry.deliveryType === "cache"); console.log(scripts); ``` diff --git a/files/en-us/web/api/performanceresourcetiming/finalresponseheadersstart/index.md b/files/en-us/web/api/performanceresourcetiming/finalresponseheadersstart/index.md index e2b50bc672699c1..5d4925ccab049bf 100644 --- a/files/en-us/web/api/performanceresourcetiming/finalresponseheadersstart/index.md +++ b/files/en-us/web/api/performanceresourcetiming/finalresponseheadersstart/index.md @@ -12,7 +12,7 @@ browser-compat: api.PerformanceResourceTiming.finalResponseHeadersStart The **`finalResponseHeadersStart`** read-only property returns a {{domxref("DOMHighResTimeStamp","timestamp")}} immediately after the browser receives the first byte of the final document response (for example, 200 OK) from the server. -This differs from **`{{domxref("PerformanceResourceTiming.requestStart", "requestStart")}}`** (which may also be represented as **`{{domxref("PerformanceResourceTiming.firstInterimResponseStart", "firstInterimResponseStart")}}`**), as this starts from the first bytes of any response including interim responses (for example, 103 Early Hints) with the final response coming potentially much later. +This differs from **{{domxref("PerformanceResourceTiming.requestStart", "requestStart")}}** (which may also be represented as **{{domxref("PerformanceResourceTiming.firstInterimResponseStart", "firstInterimResponseStart")}}**), as this starts from the first bytes of any response including interim responses (for example, 103 Early Hints) with the final response coming potentially much later. When there are no interim responses, `requestStart` is the same as `finalResponseHeadersStart` and `firstInterimResponseStart` is 0. diff --git a/files/en-us/web/api/performanceresourcetiming/initiatortype/index.md b/files/en-us/web/api/performanceresourcetiming/initiatortype/index.md index 3cb8477274f68ab..ba58da2e8902f4d 100644 --- a/files/en-us/web/api/performanceresourcetiming/initiatortype/index.md +++ b/files/en-us/web/api/performanceresourcetiming/initiatortype/index.md @@ -70,9 +70,9 @@ Example using a {{domxref("PerformanceObserver")}}, which notifies of new `resou ```js const observer = new PerformanceObserver((list) => { - const scripts = list.getEntries().filter((entry) => { - return entry.initiatorType === "script"; - }); + const scripts = list + .getEntries() + .filter((entry) => entry.initiatorType === "script"); console.log(scripts); }); @@ -82,9 +82,9 @@ observer.observe({ type: "resource", buffered: true }); Example using {{domxref("Performance.getEntriesByType()")}}, which only shows `resource` performance entries present in the browser's performance timeline at the time you call this method: ```js -const scripts = performance.getEntriesByType("resource").filter((entry) => { - return entry.initiatorType === "script"; -}); +const scripts = performance + .getEntriesByType("resource") + .filter((entry) => entry.initiatorType === "script"); console.log(scripts); ``` diff --git a/files/en-us/web/api/performanceresourcetiming/requeststart/index.md b/files/en-us/web/api/performanceresourcetiming/requeststart/index.md index ca973324432f798..ea4e0d8bc44202c 100644 --- a/files/en-us/web/api/performanceresourcetiming/requeststart/index.md +++ b/files/en-us/web/api/performanceresourcetiming/requeststart/index.md @@ -20,7 +20,7 @@ The `requestStart` property can have the following values: - `0` if the resource was instantaneously retrieved from a cache. - `0` if the resource is a cross-origin request and no {{HTTPHeader("Timing-Allow-Origin")}} HTTP response header is used. -When the `firstInterimResponseStart` is non-zero, that indicates it should be the same value as {{domxref("PerformanceResourceTiming.requestStart", "requestStart")}} for [supporting browsers](#browser_compatibility). +When the {{domxref("PerformanceResourceTiming.firstInterimResponseStart", "firstInterimResponseStart")}} is non-zero, that indicates it should be the same value as `requestStart` for [supporting browsers](#browser_compatibility). When there are no interim responses, `requestStart` is the same as `finalResponseHeadersStart` and `firstInterimResponseStart` is 0. diff --git a/files/en-us/web/api/performanceresourcetiming/responsestatus/index.md b/files/en-us/web/api/performanceresourcetiming/responsestatus/index.md index de72e675ee176b6..27ee873cb6c5dd4 100644 --- a/files/en-us/web/api/performanceresourcetiming/responsestatus/index.md +++ b/files/en-us/web/api/performanceresourcetiming/responsestatus/index.md @@ -16,8 +16,8 @@ This property maps to {{domxref("Response.status")}} from the [Fetch API](/en-US The `responseStatus` property can have the following values: -- A number indicating the [HTTP response status code](/en-US/docs/Web/HTTP/Status) returned when fetching the resource. -- `0` if the [CORS](/en-US/docs/Web/HTTP/CORS) check fails. +- A number indicating the [HTTP response status code](/en-US/docs/Web/HTTP/Reference/Status) returned when fetching the resource. +- `0` if the [CORS](/en-US/docs/Web/HTTP/Guides/CORS) check fails. - `0` for cross-origin {{HTMLElement("iframe")}} objects. ## Examples @@ -55,7 +55,7 @@ Alternatively, if `responseStatus` is not available, you can check if the {{domx ### Cross-origin response status codes -If the value of the `responseStatus` property is `0`, the resource might be a cross-origin request. To allow seeing cross-origin response status codes, the [CORS](/en-US/docs/Web/HTTP/CORS) {{HTTPHeader("Access-Control-Allow-Origin")}} HTTP response header needs to be set. +If the value of the `responseStatus` property is `0`, the resource might be a cross-origin request. To allow seeing cross-origin response status codes, the [CORS](/en-US/docs/Web/HTTP/Guides/CORS) {{HTTPHeader("Access-Control-Allow-Origin")}} HTTP response header needs to be set. For example, to allow `https://developer.mozilla.org` to see response status codes, the cross-origin resource should send: @@ -73,6 +73,6 @@ Access-Control-Allow-Origin: https://developer.mozilla.org ## See also -- [HTTP response status code](/en-US/docs/Web/HTTP/Status) +- [HTTP response status code](/en-US/docs/Web/HTTP/Reference/Status) - {{domxref("Response.status")}} -- [CORS](/en-US/docs/Web/HTTP/CORS) +- [CORS](/en-US/docs/Web/HTTP/Guides/CORS) diff --git a/files/en-us/web/api/performancescripttiming/index.md b/files/en-us/web/api/performancescripttiming/index.md index 4cea114e41aa599..ede1b98e5f4e42b 100644 --- a/files/en-us/web/api/performancescripttiming/index.md +++ b/files/en-us/web/api/performancescripttiming/index.md @@ -18,7 +18,7 @@ Long animation frames (LoAFs) are rendering updates that are delayed beyond 50ms The `PerformanceScriptTiming` interface (instances of which are accessed via the {{domxref("PerformanceLongAnimationFrameTiming.scripts")}} property) provides the following granular set of information on individual scripts that contribute to LoAFs, allowing developers to narrow down their root causes: - A detailed set of timestamps for each script. -- The identity and type of the invoker, i.e. the feature that, when invoked, ran the script. +- The identity and type of the invoker, i.e., the feature that, when invoked, ran the script. - Detailed information on each script source file, including the URL, and the function name and character position that contributed to the LoAF. `PerformanceScriptTiming` inherits from {{domxref("PerformanceEntry")}}. diff --git a/files/en-us/web/api/performancescripttiming/sourcefunctionname/index.md b/files/en-us/web/api/performancescripttiming/sourcefunctionname/index.md index e07593c1907f8ae..8178f1564e50615 100644 --- a/files/en-us/web/api/performancescripttiming/sourcefunctionname/index.md +++ b/files/en-us/web/api/performancescripttiming/sourcefunctionname/index.md @@ -19,12 +19,12 @@ For example, if an event handler calls a top-level function, which then calls a In the following snippet: ```js -setTimeout(function lib_func() { - slow_function(); +setTimeout(function libFunc() { + slowFunction(); }); ``` -`sourceFunctionName` would report `lib_func`, not `slow_function`. +`sourceFunctionName` would report `libFunc`, not `slowFunction`. ## Value diff --git a/files/en-us/web/api/performancetiming/index.md b/files/en-us/web/api/performancetiming/index.md index da9a1f95b477ad9..6a804e8adc57901 100644 --- a/files/en-us/web/api/performancetiming/index.md +++ b/files/en-us/web/api/performancetiming/index.md @@ -63,9 +63,9 @@ These properties are listed in the order in which they occur during the navigati - {{domxref("PerformanceTiming.domComplete")}} {{ReadOnlyInline}} {{Deprecated_Inline}} - : When the parser finished its work on the main document, that is when its {{domxref("Document.readyState")}} changes to `'complete'` and the corresponding {{domxref("Document/readystatechange_event", "readystatechange")}} event is thrown. - {{domxref("PerformanceTiming.loadEventStart")}} {{ReadOnlyInline}} {{Deprecated_Inline}} - - : When the {{domxref("Window/load_event", "load")}} event was sent for the current document. If this event has not yet been sent, it returns `0.` + - : When the {{domxref("Window/load_event", "load")}} event was sent for the current document. If this event has not yet been sent, it returns `0`. - {{domxref("PerformanceTiming.loadEventEnd")}} {{ReadOnlyInline}} {{Deprecated_Inline}} - - : When the {{domxref("Window/load_event", "load")}} event handler terminated, that is when the load event is completed. If this event has not yet been sent, or is not yet completed, it returns `0.` + - : When the {{domxref("Window/load_event", "load")}} event handler terminated, that is when the load event is completed. If this event has not yet been sent, or is not yet completed, it returns `0`. ## Instance methods diff --git a/files/en-us/web/api/performancetiming/loadeventend/index.md b/files/en-us/web/api/performancetiming/loadeventend/index.md index e9d5a22d1d9609a..3898eeba8e3d87a 100644 --- a/files/en-us/web/api/performancetiming/loadeventend/index.md +++ b/files/en-us/web/api/performancetiming/loadeventend/index.md @@ -19,7 +19,7 @@ The legacy read-only property returns an `unsigned long long` representing the moment, in milliseconds since the UNIX epoch, when the {{domxref("Window/load_event", "load")}} event handler terminated, that is when the load event is completed. If this event has not yet been -sent, or is not yet completed, it returns `0.` +sent, or is not yet completed, it returns `0`. ## Value diff --git a/files/en-us/web/api/performancetiming/loadeventstart/index.md b/files/en-us/web/api/performancetiming/loadeventstart/index.md index 1b4462210e26efd..87d9259f3c29ec5 100644 --- a/files/en-us/web/api/performancetiming/loadeventstart/index.md +++ b/files/en-us/web/api/performancetiming/loadeventstart/index.md @@ -18,7 +18,7 @@ The legacy **`PerformanceTiming.loadEventStart`** read-only property returns an `unsigned long long` representing the moment, in milliseconds since the UNIX epoch, when the {{domxref("Window/load_event", "load")}} event was sent for the -current document. If this event has not yet been sent, it returns `0.` +current document. If this event has not yet been sent, it returns `0`. ## Value diff --git a/files/en-us/web/api/permissions/revoke/index.md b/files/en-us/web/api/permissions/revoke/index.md index a1456b950efcd0f..99f03857acc82f3 100644 --- a/files/en-us/web/api/permissions/revoke/index.md +++ b/files/en-us/web/api/permissions/revoke/index.md @@ -55,7 +55,7 @@ A {{jsxref("Promise")}} that calls its fulfillment handler with a {{domxref("Per ### Exceptions - {{jsxref("TypeError")}} - - : Retrieving the `PermissionDescriptor` information failed in some way, or the permission doesn't exist or is currently unsupported (e.g. `midi`, or `push` with `userVisibleOnly`). + - : Retrieving the `PermissionDescriptor` information failed in some way, or the permission doesn't exist or is currently unsupported (e.g., `midi`, or `push` with `userVisibleOnly`). ## Examples diff --git a/files/en-us/web/api/permissions_api/index.md b/files/en-us/web/api/permissions_api/index.md index e6b6a7b3f42d0e0..f941586aa347329 100644 --- a/files/en-us/web/api/permissions_api/index.md +++ b/files/en-us/web/api/permissions_api/index.md @@ -19,7 +19,7 @@ For example, it can be used to determine if permission to access a particular fe Historically different APIs handle their own permissions inconsistently — for example the [Notifications API](/en-US/docs/Web/API/Notifications_API) provided its own methods for requesting permissions and checking permission status, whereas the [Geolocation API](/en-US/docs/Web/API/Geolocation) did not. The Permissions API provides the tools to allow developers to implement a consistent user experience for working with permissions. -The permissions from this API effectively aggregate all security restrictions for the context, including any requirement for an API to be used in a secure context, [Permissions-Policy](/en-US/docs/Web/HTTP/Headers/Permissions-Policy) restrictions applied to the document, requirements for user interaction, and user prompts. +The permissions from this API effectively aggregate all security restrictions for the context, including any requirement for an API to be used in a secure context, [Permissions-Policy](/en-US/docs/Web/HTTP/Reference/Headers/Permissions-Policy) restrictions applied to the document, requirements for user interaction, and user prompts. So, for example, if an API is restricted by permissions policy, the returned permission would be `denied` and the user would not be prompted for access. The `permissions` property has been made available on the {{domxref("Navigator")}} object, both in the standard browsing context and the worker context ({{domxref("WorkerNavigator")}} — so permission checks are available inside workers), and returns a {{domxref("Permissions")}} object that provides access to the Permissions API functionality. diff --git a/files/en-us/web/api/permissionstatus/change_event/index.md b/files/en-us/web/api/permissionstatus/change_event/index.md index 35ea2262870dbba..11fddf903390fd9 100644 --- a/files/en-us/web/api/permissionstatus/change_event/index.md +++ b/files/en-us/web/api/permissionstatus/change_event/index.md @@ -14,10 +14,10 @@ The **`change`** event of the {{domxref("PermissionStatus")}} interface fires wh Use the event name in methods like {{domxref("EventTarget.addEventListener", "addEventListener()")}}, or set an event handler property. -```js -addEventListener("change", (event) => {}); +```js-nolint +addEventListener("change", (event) => { }) -onchange = (event) => {}; +onchange = (event) => { } ``` ## Event type diff --git a/files/en-us/web/api/picture-in-picture_api/index.md b/files/en-us/web/api/picture-in-picture_api/index.md index b3699ac5b54c2d9..a6fec4730f6acaa 100644 --- a/files/en-us/web/api/picture-in-picture_api/index.md +++ b/files/en-us/web/api/picture-in-picture_api/index.md @@ -45,7 +45,7 @@ The Picture-in-Picture API augments the {{DOMxRef("HTMLVideoElement")}}, {{DOMxR ### Instance properties on the Document interface - {{DOMxRef("Document.pictureInPictureEnabled")}} - - : The `pictureInPictureEnabled` property tells you whether or not it is possible to engage picture-in-picture mode. This is `false` if picture-in-picture mode is not available for any reason (e.g. the [`"picture-in-picture"` feature](/en-US/docs/Web/HTTP/Headers/Permissions-Policy/picture-in-picture) has been disallowed, or picture-in-picture mode is not supported). + - : The `pictureInPictureEnabled` property tells you whether or not it is possible to engage picture-in-picture mode. This is `false` if picture-in-picture mode is not available for any reason (e.g., the [`"picture-in-picture"` feature](/en-US/docs/Web/HTTP/Reference/Headers/Permissions-Policy/picture-in-picture) has been disallowed, or picture-in-picture mode is not supported). ### Instance properties on the Document or ShadowRoot interfaces @@ -73,7 +73,7 @@ The [`:picture-in-picture`](/en-US/docs/Web/CSS/:picture-in-picture) [CSS](/en-U ## Controlling access -The availability of picture-in-picture mode can be controlled using [Permissions Policy](/en-US/docs/Web/HTTP/Permissions_Policy). The picture-in-picture mode feature is identified by the string `"picture-in-picture"`, with a default allowlist value of `*`, meaning that picture-in-picture mode is permitted in top-level document contexts, as well as to nested browsing contexts loaded from the same origin as the top-most document. +The availability of picture-in-picture mode can be controlled using [Permissions Policy](/en-US/docs/Web/HTTP/Guides/Permissions_Policy). The picture-in-picture mode feature is identified by the string `"picture-in-picture"`, with a default allowlist value of `*`, meaning that picture-in-picture mode is permitted in top-level document contexts, as well as to nested browsing contexts loaded from the same origin as the top-most document. ## Examples diff --git a/files/en-us/web/api/pictureinpicturewindow/resize_event/index.md b/files/en-us/web/api/pictureinpicturewindow/resize_event/index.md index b4354abe7775b87..37c5f6a5f47fbc3 100644 --- a/files/en-us/web/api/pictureinpicturewindow/resize_event/index.md +++ b/files/en-us/web/api/pictureinpicturewindow/resize_event/index.md @@ -16,10 +16,10 @@ This event is not cancelable and does not bubble. Use the event name in methods like {{domxref("EventTarget.addEventListener", "addEventListener()")}}, or set an event handler property. -```js -addEventListener("resize", (event) => {}); +```js-nolint +addEventListener("resize", (event) => { }) -onresize = (event) => {}; +onresize = (event) => { } ``` ## Event type diff --git a/files/en-us/web/api/pointer_events/index.md b/files/en-us/web/api/pointer_events/index.md index b85c450f885869c..6794f004e2cf8b0 100644 --- a/files/en-us/web/api/pointer_events/index.md +++ b/files/en-us/web/api/pointer_events/index.md @@ -79,11 +79,11 @@ The {{domxref("PointerEvent")}} interface extends the {{domxref("MouseEvent")}} - {{ domxref('PointerEvent.tangentialPressure','tangentialPressure')}} {{ReadOnlyInline}} - : The normalized tangential pressure of the pointer input (also known as barrel pressure or cylinder stress) in the range `-1` to `1`, where `0` is the neutral position of the control. - {{ domxref('PointerEvent.tiltX','tiltX')}} {{ReadOnlyInline}} - - : The plane angle (in degrees, in the range of `-90` to `90`) between the Y–Z plane and the plane containing both the pointer (e.g. pen stylus) axis and the Y axis. + - : The plane angle (in degrees, in the range of `-90` to `90`) between the Y–Z plane and the plane containing both the pointer (e.g., pen stylus) axis and the Y axis. - {{ domxref('PointerEvent.tiltY','tiltY')}} {{ReadOnlyInline}} - - : the plane angle (in degrees, in the range of `-90` to `90`) between the X–Z plane and the plane containing both the pointer (e.g. pen stylus) axis and the X axis. + - : the plane angle (in degrees, in the range of `-90` to `90`) between the X–Z plane and the plane containing both the pointer (e.g., pen stylus) axis and the X axis. - {{ domxref('PointerEvent.twist','twist')}} {{ReadOnlyInline}} - - : The clockwise rotation of the pointer (e.g. pen stylus) around its major axis in degrees, with a value in the range `0` to `359`. + - : The clockwise rotation of the pointer (e.g., pen stylus) around its major axis in degrees, with a value in the range `0` to `359`. - {{ domxref('PointerEvent.pointerType','pointerType')}} {{ReadOnlyInline}} - : Indicates the device type that caused the event (mouse, pen, touch, etc.). - {{ domxref('PointerEvent.isPrimary','isPrimary')}} {{ReadOnlyInline}} @@ -250,7 +250,7 @@ A mouse has only one pointer, so it will always be the primary pointer. For touc ## Determining button states -Some pointer devices (such as mouse and pen) support multiple buttons, and the button presses can be _chorded_ (i.e. pressing an additional button while another button on the pointer device is already pressed). +Some pointer devices (such as mouse and pen) support multiple buttons, and the button presses can be _chorded_ (i.e., pressing an additional button while another button on the pointer device is already pressed). To determine the state of button presses, pointer events uses the {{domxref("MouseEvent.button","button")}} and {{domxref("MouseEvent.buttons","buttons")}} properties of the {{domxref("MouseEvent")}} interface (that {{domxref("PointerEvent")}} inherits from). @@ -369,7 +369,7 @@ Although the pointer event interfaces enable applications to create enhanced use The browser _may map generic pointer input to mouse events for compatibility with mouse-based content_. This mapping of events is called _compatibility mouse events_. Authors can prevent the production of certain compatibility mouse events by canceling the pointerdown event but note that: - Mouse events can only be prevented when the pointer is down. -- Hovering pointers (e.g. a mouse with no buttons pressed) cannot have their mouse events prevented. +- Hovering pointers (e.g., a mouse with no buttons pressed) cannot have their mouse events prevented. - The `mouseover`, `mouseout`, `mouseenter`, and `mouseleave` events are never prevented (even if the pointer is down). ## Best practices @@ -392,16 +392,8 @@ Some additional values have been defined for the CSS {{cssxref("touch-action")}} ## See also -### Demos and examples - -- [Touch/pointer tests and demos (by Patrick H. Lauke)](https://patrickhlauke.github.io/touch/) - -### Community - +- [Touch Events](/en-US/docs/Web/API/Touch_events) - [Pointer Events Working Group](https://github.com/w3c/pointerevents) - [Mail list](https://lists.w3.org/Archives/Public/public-pointer-events/) - [W3C #pointerevents IRC channel](irc://irc.w3.org:6667/) - -### Related topics and resources - -- [Touch Events Standard](https://www.w3.org/TR/touch-events/) +- [Touch/pointer tests and demos](https://patrickhlauke.github.io/touch/) by Patrick H. Lauke diff --git a/files/en-us/web/api/pointer_lock_api/index.md b/files/en-us/web/api/pointer_lock_api/index.md index 1bedd104417cdbc..bb4a66c0003fbd1 100644 --- a/files/en-us/web/api/pointer_lock_api/index.md +++ b/files/en-us/web/api/pointer_lock_api/index.md @@ -154,7 +154,7 @@ When the mouse is unlocked, the system cursor can exit and re-enter the browser ## Simple example walkthrough -We've written a [pointer lock demo](https://mdn.github.io/dom-examples/pointer-lock/) ([see source code](https://github.com/mdn/dom-examples/tree/main/pointer-lock)) to show you how to use it to set up a simple control system. This demo uses JavaScript to draw a ball on top of an {{ htmlelement("canvas") }} element. When you click the canvas, pointer lock is then used to remove the mouse pointer and allow you to move the ball directly using the mouse. Let's see how this works. +We've written a [pointer lock demo](https://mdn.github.io/dom-examples/pointer-lock/) ([see source code](https://github.com/mdn/dom-examples/tree/main/pointer-lock)) to show you how to use it to set up a simple control system. This demo uses JavaScript to draw a ball on top of a {{ htmlelement("canvas") }} element. When you click the canvas, pointer lock is then used to remove the mouse pointer and allow you to move the ball directly using the mouse. Let's see how this works. We set initial x and y positions on the canvas: @@ -221,12 +221,10 @@ function updatePosition(e) { } tracker.textContent = `X position: ${x}, Y position: ${y}`; - if (!animation) { - animation = requestAnimationFrame(() => { - animation = null; - canvasDraw(); - }); - } + animation ??= requestAnimationFrame(() => { + animation = null; + canvasDraw(); + }); } ``` diff --git a/files/en-us/web/api/pointerevent/index.md b/files/en-us/web/api/pointerevent/index.md index 3faa46bc93fc5ab..ccba1fe34e029bb 100644 --- a/files/en-us/web/api/pointerevent/index.md +++ b/files/en-us/web/api/pointerevent/index.md @@ -41,11 +41,11 @@ _This interface inherits properties from {{domxref("MouseEvent")}} and {{domxref - {{domxref('PointerEvent.tangentialPressure')}} {{ReadOnlyInline}} - : The normalized tangential pressure of the pointer input (also known as barrel pressure or [cylinder stress](https://en.wikipedia.org/wiki/Cylinder_stress)) in the range `-1` to `1`, where `0` is the neutral position of the control. - {{domxref('PointerEvent.tiltX')}} {{ReadOnlyInline}} - - : The plane angle (in degrees, in the range of `-90` to `90`) between the Y–Z plane and the plane containing both the pointer (e.g. pen stylus) axis and the Y axis. + - : The plane angle (in degrees, in the range of `-90` to `90`) between the Y–Z plane and the plane containing both the pointer (e.g., pen stylus) axis and the Y axis. - {{domxref('PointerEvent.tiltY')}} {{ReadOnlyInline}} - - : The plane angle (in degrees, in the range of `-90` to `90`) between the X–Z plane and the plane containing both the pointer (e.g. pen stylus) axis and the X axis. + - : The plane angle (in degrees, in the range of `-90` to `90`) between the X–Z plane and the plane containing both the pointer (e.g., pen stylus) axis and the X axis. - {{domxref('PointerEvent.twist')}} {{ReadOnlyInline}} - - : The clockwise rotation of the pointer (e.g. pen stylus) around its major axis in degrees, with a value in the range `0` to `359`. + - : The clockwise rotation of the pointer (e.g., pen stylus) around its major axis in degrees, with a value in the range `0` to `359`. - {{domxref('PointerEvent.pointerType')}} {{ReadOnlyInline}} - : Indicates the device type that caused the event (mouse, pen, touch, etc.). - {{domxref('PointerEvent.isPrimary')}} {{ReadOnlyInline}} diff --git a/files/en-us/web/api/pointerevent/persistentdeviceid/index.md b/files/en-us/web/api/pointerevent/persistentdeviceid/index.md index e5cdf6aadf26291..5e1a1d6311fbc79 100644 --- a/files/en-us/web/api/pointerevent/persistentdeviceid/index.md +++ b/files/en-us/web/api/pointerevent/persistentdeviceid/index.md @@ -41,7 +41,7 @@ const colorYellow = 2; const colors = [colorBlue, colorGreen, colorYellow]; const pointerToColorMap = new Map(); -const colorAssignmentIndex = 0; +let colorAssignmentIndex = 0; const canvas = document.querySelector("#inking-surface"); diff --git a/files/en-us/web/api/popover_api/index.md b/files/en-us/web/api/popover_api/index.md index 5f417fe0583a9bd..6c230d0c4131d28 100644 --- a/files/en-us/web/api/popover_api/index.md +++ b/files/en-us/web/api/popover_api/index.md @@ -40,11 +40,11 @@ See [Using the popover API](/en-US/docs/Web/API/Popover_API/Using) for a detaile ## HTML attributes -- [`popover`](/en-US/docs/Web/HTML/Global_attributes/popover) +- [`popover`](/en-US/docs/Web/HTML/Reference/Global_attributes/popover) - : A global attribute that turns an element into a popover element; takes a popover state (`"auto"`, `"hint"`, or `"manual"`) as its value. -- [`popovertarget`](/en-US/docs/Web/HTML/Element/button#popovertarget) +- [`popovertarget`](/en-US/docs/Web/HTML/Reference/Elements/button#popovertarget) - : Turns a {{htmlelement("button")}} or {{htmlelement("input")}} element into a popover control button; takes the ID of the popover element to control as its value. -- [`popovertargetaction`](/en-US/docs/Web/HTML/Element/button#popovertargetaction) +- [`popovertargetaction`](/en-US/docs/Web/HTML/Reference/Elements/button#popovertargetaction) - : Specifies the action to be performed (`"hide"`, `"show"`, or `"toggle"`) on the popover element being controlled by a control {{htmlelement("button")}} or {{htmlelement("input")}}. ## CSS features @@ -64,11 +64,11 @@ See [Using the popover API](/en-US/docs/Web/API/Popover_API/Using) for a detaile ### Instance properties - {{domxref("HTMLElement.popover")}} - - : Gets and sets an element's popover state via JavaScript (`"auto"`, `"hint"`, or `"manual"`), and can be used for feature detection. Reflects the value of the [`popover`](/en-US/docs/Web/HTML/Global_attributes/popover) global HTML attribute. + - : Gets and sets an element's popover state via JavaScript (`"auto"`, `"hint"`, or `"manual"`), and can be used for feature detection. Reflects the value of the [`popover`](/en-US/docs/Web/HTML/Reference/Global_attributes/popover) global HTML attribute. - {{domxref("HTMLButtonElement.popoverTargetElement")}} and {{domxref("HTMLInputElement.popoverTargetElement")}} - - : Gets and sets the popover element being controlled by the control button. The JavaScript equivalent of the [`popovertarget`](/en-US/docs/Web/HTML/Element/button#popovertarget) HTML attribute. + - : Gets and sets the popover element being controlled by the control button. The JavaScript equivalent of the [`popovertarget`](/en-US/docs/Web/HTML/Reference/Elements/button#popovertarget) HTML attribute. - {{domxref("HTMLButtonElement.popoverTargetAction")}} and {{domxref("HTMLInputElement.popoverTargetAction")}} - - : Gets and sets the action to be performed (`"hide"`, `"show"`, or `"toggle"`) on the popover element being controlled by the control button. Reflects the value of the [`popovertargetaction`](/en-US/docs/Web/HTML/Element/button#popovertargetaction) HTML attribute. + - : Gets and sets the action to be performed (`"hide"`, `"show"`, or `"toggle"`) on the popover element being controlled by the control button. Reflects the value of the [`popovertargetaction`](/en-US/docs/Web/HTML/Reference/Elements/button#popovertargetaction) HTML attribute. ### Instance methods @@ -101,8 +101,8 @@ See our [Popover API examples landing page](https://mdn.github.io/dom-examples/p ## See also -- [`popover`](/en-US/docs/Web/HTML/Global_attributes/popover) HTML global attribute -- [`popovertarget`](/en-US/docs/Web/HTML/Element/button#popovertarget) HTML attribute -- [`popovertargetaction`](/en-US/docs/Web/HTML/Element/button#popovertargetaction) HTML attribute +- [`popover`](/en-US/docs/Web/HTML/Reference/Global_attributes/popover) HTML global attribute +- [`popovertarget`](/en-US/docs/Web/HTML/Reference/Elements/button#popovertarget) HTML attribute +- [`popovertargetaction`](/en-US/docs/Web/HTML/Reference/Elements/button#popovertargetaction) HTML attribute - [`::backdrop`](/en-US/docs/Web/CSS/::backdrop) CSS pseudo-element - [`:popover-open`](/en-US/docs/Web/CSS/:popover-open) CSS pseudo-class diff --git a/files/en-us/web/api/popover_api/using/index.md b/files/en-us/web/api/popover_api/using/index.md index 94d9926873fd940..f223e70b0edca55 100644 --- a/files/en-us/web/api/popover_api/using/index.md +++ b/files/en-us/web/api/popover_api/using/index.md @@ -12,7 +12,7 @@ The **Popover API** provides developers with a standard, consistent, flexible me ## Creating declarative popovers -In its simplest form, a popover is created by adding the [`popover`](/en-US/docs/Web/HTML/Global_attributes/popover) attribute to the element that you want to contain your popover content. An `id` is also needed to associate the popover with its controls. +In its simplest form, a popover is created by adding the [`popover`](/en-US/docs/Web/HTML/Reference/Global_attributes/popover) attribute to the element that you want to contain your popover content. An `id` is also needed to associate the popover with its controls. ```html <div id="mypopover" popover>Popover content</div> @@ -21,7 +21,7 @@ In its simplest form, a popover is created by adding the [`popover`](/en-US/docs > [!NOTE] > Setting the `popover` attribute with no value is equivalent to setting `popover="auto"`. -Adding this attribute causes the element to be hidden on page load by having {{cssxref("display", "display: none")}} set on it. To show/hide the popover, you need to add at least one control button (also know as the popover **invoker**). You can set a {{htmlelement("button")}} (or {{htmlelement("input")}} of `type="button"`) as a popover control button by giving it a [`popovertarget`](/en-US/docs/Web/HTML/Element/button#popovertarget) attribute, the value of which should be the ID of the popover to control: +Adding this attribute causes the element to be hidden on page load by having {{cssxref("display", "display: none")}} set on it. To show/hide the popover, you need to add at least one control button (also know as the popover **invoker**). You can set a {{htmlelement("button")}} (or {{htmlelement("input")}} of `type="button"`) as a popover control button by giving it a [`popovertarget`](/en-US/docs/Web/HTML/Reference/Elements/button#popovertarget) attribute, the value of which should be the ID of the popover to control: ```html <button popovertarget="mypopover">Toggle the popover</button> @@ -30,7 +30,7 @@ Adding this attribute causes the element to be hidden on page load by having {{c The default behavior is for the button to be a toggle button — pressing it repeatedly will toggle the popover between showing and hidden. -If you want to change that behavior, you can use the [`popovertargetaction`](/en-US/docs/Web/HTML/Element/button#popovertargetaction) attribute — this takes a value of `"hide"`, `"show"`, or `"toggle"`. For example, to create separate show and hide buttons, you could do this: +If you want to change that behavior, you can use the [`popovertargetaction`](/en-US/docs/Web/HTML/Reference/Elements/button#popovertargetaction) attribute — this takes a value of `"hide"`, `"show"`, or `"toggle"`. For example, to create separate show and hide buttons, you could do this: ```html <button popovertarget="mypopover" popovertargetaction="show"> @@ -67,13 +67,17 @@ You can see the behavior described above in action in our [Multiple auto popover When a relationship is established between a popover and its control (invoker) via the `popovertarget` attribute, the API automatically makes two other changes to the environment to allow keyboard and assistive technology (AT) users to more easily interact with the popover: -- When the popover is shown, the keyboard focus navigation order is updated so that the popover is next in the sequence: for example, when a button is pressed to show a popover, any buttons inside the popover will be next in the tabbing order (will be focused by pressing the <kbd>Tab</kbd> key). Conversely, when closing the popover via the keyboard (usually via via the <kbd>Esc</kbd> key), focus is shifted back to the invoker. -- To allow AT such as screen readers to make sense of the relationship between the invoker and the popover, an implicit [`aria-details`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-details) and [`aria-expanded`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-expanded) relationship is set up between them. +- When the popover is shown, the keyboard focus navigation order is updated so that the popover is next in the sequence: for example, when a button is pressed to show a popover, any buttons inside the popover will be next in the tabbing order (will be focused by pressing the <kbd>Tab</kbd> key). Conversely, when closing the popover via the keyboard (usually via the <kbd>Esc</kbd> key), focus is shifted back to the invoker. +- To allow AT such as screen readers to make sense of the relationship between the invoker and the popover, an implicit [`aria-details`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-details) and [`aria-expanded`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-expanded) relationship is set up between them. Setting up a relationship between a popover and its control in this manner also creates an implicit anchor reference between the two — see [Popover anchor positioning](#popover_anchor_positioning) for more details. -> [!NOTE] -> You can also set up a popover-invoker relationship using the `source` option of the {{domxref("HTMLElement.showPopover()")}} and {{domxref("HTMLElement.togglePopover()")}} methods, but bear in mind that in this case, only the focus navigation order changes are made, not the implicit ARIA relationship. This because the `source` option can be set to any kind of element, not just `<button>` elements, and it cannot be guaranteed that the relationship would make sense. +## Other ways to set up a popover-invoker relationship + +You can set up a popover-invoker relationship in other ways, in addition to using the `popovertarget` attribute: + +- Using the `source` option of the {{domxref("HTMLElement.showPopover()")}} or {{domxref("HTMLElement.togglePopover()")}} methods. Bear in mind that in this case, only the focus navigation order changes are made, not the implicit ARIA relationship. This because the `source` option can be set to any kind of element, not just `<button>` elements, and it cannot be guaranteed that the relationship would make sense. +- Between a {{htmlelement("select")}} element and its dropdown picker, when opting it into [customizable select element](/en-US/docs/Learn_web_development/Extensions/Forms/Customizable_select) functionality via the {{cssxref("appearance")}} property `base-select` value. In this case, an implicit popover-invoker relationship is created between the two. ## Using manual popover state @@ -94,18 +98,18 @@ You can see this behavior in action in our [Multiple manual popovers example](ht You can also control popovers using a JavaScript API. -The {{domxref("HTMLElement.popover")}} property can be used to get or set the [`popover`](/en-US/docs/Web/HTML/Global_attributes/popover) attribute. This can be used to create a popover via JavaScript, and is also useful for feature detection. For example: +The {{domxref("HTMLElement.popover")}} property can be used to get or set the [`popover`](/en-US/docs/Web/HTML/Reference/Global_attributes/popover) attribute. This can be used to create a popover via JavaScript, and is also useful for feature detection. For example: ```js function supportsPopover() { - return HTMLElement.prototype.hasOwnProperty("popover"); + return Object.hasOwn(HTMLElement.prototype, "popover"); } ``` Similarly: -- {{domxref("HTMLButtonElement.popoverTargetElement")}} and {{domxref("HTMLInputElement.popoverTargetElement")}} provide an equivalent to the [`popovertarget`](/en-US/docs/Web/HTML/Element/button#popovertarget) attribute, allowing you to set up the control button(s) for a popover, although the property value taken is a reference to the popover DOM element to control. -- {{domxref("HTMLButtonElement.popoverTargetAction")}} and {{domxref("HTMLInputElement.popoverTargetAction")}} provide an equivalent to the [`popovertargetaction`](/en-US/docs/Web/HTML/Element/button#popovertargetaction) global HTML attribute, allowing you to specify the action taken by a control button. +- {{domxref("HTMLButtonElement.popoverTargetElement")}} and {{domxref("HTMLInputElement.popoverTargetElement")}} provide an equivalent to the [`popovertarget`](/en-US/docs/Web/HTML/Reference/Elements/button#popovertarget) attribute, allowing you to set up the control button(s) for a popover, although the property value taken is a reference to the popover DOM element to control. +- {{domxref("HTMLButtonElement.popoverTargetAction")}} and {{domxref("HTMLInputElement.popoverTargetAction")}} provide an equivalent to the [`popovertargetaction`](/en-US/docs/Web/HTML/Reference/Elements/button#popovertargetaction) global HTML attribute, allowing you to specify the action taken by a control button. Putting these three together, you can programmatically set up a popover and its control button, like so: @@ -385,7 +389,7 @@ You can see an isolated example of this in our [Popover positioning example](htt There is another useful positioning option that the Popover API provides. If you want to position a popover relative to its invoker rather than the viewport or a positioned ancestor, you can take advantage of the fact that popovers and their invokers have an **implicit anchor reference**. -Associating any kind of popover with its invoker using the [`popovertarget`](/en-US/docs/Web/HTML/Element/button#popovertarget) attribute or the `source` option of the {{domxref("HTMLElement.showPopover()")}} or {{domxref("HTMLElement.togglePopover()")}} methods creates an implicit anchor reference between the two. This causes the invoker to become the popover's **anchor element**, meaning that you can position the popover relative to it via [CSS anchor positioning](/en-US/docs/Web/CSS/CSS_anchor_positioning). +[Associating any kind of popover with its invoker](#other_ways_to_set_up_a_popover-invoker_relationship) creates an implicit anchor reference between the two. This causes the invoker to become the popover's **anchor element**, meaning that you can position the popover relative to it using [CSS anchor positioning](/en-US/docs/Web/CSS/CSS_anchor_positioning). Because the association between the popover and the invoker is implicit, an explicit association does not need to be made using the {{cssxref("anchor-name")}} and {{cssxref("position-anchor")}} properties. However, you still need to specify the positioning CSS. @@ -438,7 +442,7 @@ Let's have a look at an example so you can see what this looks like: #### HTML -The HTML contains a {{htmlelement("div")}} element declared to be a popover via the global [`popover`](/en-US/docs/Web/HTML/Global_attributes/popover) HTML attribute, and a {{htmlelement("button")}} element designated as the popover's display control: +The HTML contains a {{htmlelement("div")}} element declared to be a popover via the global [`popover`](/en-US/docs/Web/HTML/Reference/Global_attributes/popover) HTML attribute, and a {{htmlelement("button")}} element designated as the popover's display control: ```html <button popovertarget="mypopover">Show the popover</button> diff --git a/files/en-us/web/api/positionsensorvrdevice/getstate/index.md b/files/en-us/web/api/positionsensorvrdevice/getstate/index.md index d45e0b985f79551..565315b86c3b9ec 100644 --- a/files/en-us/web/api/positionsensorvrdevice/getstate/index.md +++ b/files/en-us/web/api/positionsensorvrdevice/getstate/index.md @@ -11,7 +11,7 @@ browser-compat: api.PositionSensorVRDevice.getState {{deprecated_header}}{{APIRef("WebVR API")}}{{Non-standard_header}} -The **`getState()`** method of the {{domxref("PositionSensorVRDevice")}} interface returns the current state of the position sensor for the current frame (e.g. within the current {{domxref("window.requestAnimationFrame")}} callback) or for the previous frame, contained with a {{domxref("VRPose")}} object. This is the method you'd normally want to use, vs. {{domxref("PositionSensorVRDevice.getImmediateState")}}. +The **`getState()`** method of the {{domxref("PositionSensorVRDevice")}} interface returns the current state of the position sensor for the current frame (e.g., within the current {{domxref("window.requestAnimationFrame")}} callback) or for the previous frame, contained with a {{domxref("VRPose")}} object. This is the method you'd normally want to use, vs. {{domxref("PositionSensorVRDevice.getImmediateState")}}. ## Syntax diff --git a/files/en-us/web/api/positionsensorvrdevice/index.md b/files/en-us/web/api/positionsensorvrdevice/index.md index fe1dd8e47a9e886..0cbcf0008e1435f 100644 --- a/files/en-us/web/api/positionsensorvrdevice/index.md +++ b/files/en-us/web/api/positionsensorvrdevice/index.md @@ -15,7 +15,7 @@ The **`PositionSensorVRDevice`** interface of the [WebVR API](/en-US/docs/Web/AP ## Instance methods - {{domxref("PositionSensorVRDevice.getState()")}} {{Deprecated_Inline}} {{Non-standard_Inline}} - - : Returns the current state of the position sensor for the current frame (e.g. within the current {{domxref("window.requestAnimationFrame")}} callback) or for the previous frame, contained with a {{domxref("VRPose")}} object. This is the method you'd normally want to use, versus `getImmediateState()`. + - : Returns the current state of the position sensor for the current frame (e.g., within the current {{domxref("window.requestAnimationFrame")}} callback) or for the previous frame, contained with a {{domxref("VRPose")}} object. This is the method you'd normally want to use, versus `getImmediateState()`. - {{domxref("PositionSensorVRDevice.getImmediateState()")}} {{Deprecated_Inline}} {{Non-standard_Inline}} - : Returns the current instantaneous position sensor state. This is intended to only be used rarely, for certain special uses, for example sampling the immediate position of a hand orientation sensor — or at least it will be, in the future. - {{domxref("PositionSensorVRDevice.resetSensor()")}} {{Deprecated_Inline}} {{Non-standard_Inline}} diff --git a/files/en-us/web/api/presentation/receiver/index.md b/files/en-us/web/api/presentation/receiver/index.md index 9ebb7b81afc3172..cbe913234e39d7b 100644 --- a/files/en-us/web/api/presentation/receiver/index.md +++ b/files/en-us/web/api/presentation/receiver/index.md @@ -32,12 +32,14 @@ If the current context is not receiving a presentation, `receiver` is ### Determining whether or not the context is receiving a presentation You can easily determine whether or not the context is the receiver for a presentation -by checking the value of `navigator.receiver`. If it's a non-null value, then +by checking the value of `navigator.presentation.receiver`. If it's a non-null value, then the context is indeed receiving a presentation. If it's `null`, there's no incoming presentation. ```js -footer.textContent = navigator.receiver ? "Receiving presentation" : "(idle)"; +footer.textContent = navigator.presentation.receiver + ? "Receiving presentation" + : "(idle)"; ``` ### Accessing the connection list @@ -57,7 +59,7 @@ navigator.presentation.receiver.connectionList.then((connections) => { ``` After getting access to the output list element in the variable -`connectionView`, {{domxref("navigator.receiver")}} is used to get a +`connectionView`, `navigator.presentation.receiver` is used to get a reference to the {{domxref("PresentationReceiver")}} object for this context, and its {{domxref("PresentationReceiver.connectionList", "connectionList")}} is used to get a {{jsxref("Promise")}} which will be called when the list is available. diff --git a/files/en-us/web/api/presentation_api/index.md b/files/en-us/web/api/presentation_api/index.md index 761b37a0ce13e12..eea1e8b0b73e92f 100644 --- a/files/en-us/web/api/presentation_api/index.md +++ b/files/en-us/web/api/presentation_api/index.md @@ -9,7 +9,7 @@ browser-compat: api.Presentation {{securecontext_header}}{{SeeCompatTable}}{{DefaultAPISidebar("Presentation API")}} -The Presentation API lets a {{Glossary("user agent")}} (such as a Web browser) effectively display web content through large presentation devices such as projectors and network-connected televisions. Supported types of multimedia devices include both displays which are wired using HDMI, DVI, or the like, or wireless, using [DLNA](https://www.dlna.org/), [Chromecast](https://developers.google.com/cast/), [AirPlay](https://developer.apple.com/airplay/), or [Miracast](https://www.wi-fi.org/discover-wi-fi/miracast). +The Presentation API lets a {{Glossary("user agent")}} (such as a Web browser) effectively display web content through large presentation devices such as projectors and network-connected televisions. Supported types of multimedia devices include both displays which are wired using HDMI, DVI, or the like, or wireless, using [DLNA](https://www.dlna.org/), [Chromecast](https://developers.google.com/cast/), [AirPlay](https://developer.apple.com/airplay/), or [Miracast](https://www.wi-fi.org/applications). ![1-UA mode loaded the Controlling and Presenting pages together before outputting to displays. 2-UA mode loaded them separately using the Presentation Control Protocol.](presentation_mode_illustration.png) diff --git a/files/en-us/web/api/pressureobserver/observe/index.md b/files/en-us/web/api/pressureobserver/observe/index.md index 1bc90cce2b310ee..b5ab728d0baf7b9 100644 --- a/files/en-us/web/api/pressureobserver/observe/index.md +++ b/files/en-us/web/api/pressureobserver/observe/index.md @@ -37,7 +37,7 @@ A {{jsxref("Promise")}} that fulfils with {{jsxref("undefined")}}. ### Exceptions - `NotAllowedError` {{domxref("DOMException")}} - - : Thrown if the [Compute Pressure API](/en-US/docs/Web/API/Compute_Pressure_API) is disallowed by a {{httpheader('Permissions-Policy/compute-pressure','compute-pressure')}} [Permissions Policy](/en-US/docs/Web/HTTP/Permissions_Policy). + - : Thrown if the [Compute Pressure API](/en-US/docs/Web/API/Compute_Pressure_API) is disallowed by a {{httpheader('Permissions-Policy/compute-pressure','compute-pressure')}} [Permissions Policy](/en-US/docs/Web/HTTP/Guides/Permissions_Policy). - `NotSupportedError` {{domxref("DOMException")}} - : Thrown if the `source` parameter is not one of the supported sources for this user agent. diff --git a/files/en-us/web/api/pressureobserver/pressureobserver/index.md b/files/en-us/web/api/pressureobserver/pressureobserver/index.md index 913973144ed6af2..4449358ae8b1539 100644 --- a/files/en-us/web/api/pressureobserver/pressureobserver/index.md +++ b/files/en-us/web/api/pressureobserver/pressureobserver/index.md @@ -34,7 +34,7 @@ A new {{domxref("PressureObserver")}} object with the specified `callback` funct ### Exceptions - `NotAllowedError` {{domxref("DOMException")}} - - : Thrown if the [Compute Pressure API](/en-US/docs/Web/API/Compute_Pressure_API) is disallowed by a {{httpheader('Permissions-Policy/compute-pressure','compute-pressure')}} [Permissions Policy](/en-US/docs/Web/HTTP/Permissions_Policy). + - : Thrown if the [Compute Pressure API](/en-US/docs/Web/API/Compute_Pressure_API) is disallowed by a {{httpheader('Permissions-Policy/compute-pressure','compute-pressure')}} [Permissions Policy](/en-US/docs/Web/HTTP/Guides/Permissions_Policy). ## Examples diff --git a/files/en-us/web/api/pressureobserver/takerecords/index.md b/files/en-us/web/api/pressureobserver/takerecords/index.md index 17a025e90df0550..4420babb638f95f 100644 --- a/files/en-us/web/api/pressureobserver/takerecords/index.md +++ b/files/en-us/web/api/pressureobserver/takerecords/index.md @@ -35,7 +35,7 @@ An {{jsxref("Array")}} of {{domxref("PressureRecord")}} objects. The following example stores the current list of pressure records into `records` and empties the pressure observer. ```js -const observer = new PressureObserver(callback): +const observer = new PressureObserver(callback); observer.observe("cpu"); const records = observer.takeRecords(); diff --git a/files/en-us/web/api/prioritized_task_scheduling_api/index.md b/files/en-us/web/api/prioritized_task_scheduling_api/index.md index 1391072b34c5777..d9544be4383ca9d 100644 --- a/files/en-us/web/api/prioritized_task_scheduling_api/index.md +++ b/files/en-us/web/api/prioritized_task_scheduling_api/index.md @@ -242,7 +242,7 @@ The code below prints "Feature: Supported" if the API is supported on this brows ``` ```js hidden -//hidden logger code - simplifies example +// hidden logger code - simplifies example let log = document.getElementById("log"); function myLog(text) { log.textContent += `${text}\n`; diff --git a/files/en-us/web/api/profiler/index.md b/files/en-us/web/api/profiler/index.md new file mode 100644 index 000000000000000..eb514519d502981 --- /dev/null +++ b/files/en-us/web/api/profiler/index.md @@ -0,0 +1,63 @@ +--- +title: Profiler +slug: Web/API/Profiler +page-type: web-api-interface +status: + - experimental +browser-compat: api.Profiler +--- + +{{APIRef("JS Self-Profiling API")}}{{SeeCompatTable}} + +The **`Profiler`** interface of the [JS Self-Profiling API](/en-US/docs/Web/API/JS_Self-Profiling_API) enables you to create a [profile](/en-US/docs/Web/API/JS_Self-Profiling_API/Profile_content_and_format) of some part of your web application's execution. + +## Constructor + +- {{domxref("Profiler.Profiler","Profiler()")}} {{experimental_inline}} + - : Creates a new `Profiler` object, and starts collecting samples. + +## Instance methods + +- {{domxref("Profiler.stop()")}} {{experimental_inline}} + - : Stops the profiler, returning a {{jsxref("Promise")}} that resolves to the [profile](/en-US/docs/Web/API/JS_Self-Profiling_API/Profile_content_and_format). + +## Events + +- {{domxref("Profiler.samplebufferfull_event", "samplebufferfull")}} + - : Fired when the profile has recorded enough samples to fill its internal buffer. + +## Examples + +### Recording a profile + +The following code profiles the `doWork()` operation, and logs the result. + +```js +const profiler = new Profiler({ sampleInterval: 10, maxBufferSize: 10000 }); + +doWork(); + +const profile = await profiler.stop(); +console.log(JSON.stringify(profile)); +``` + +### Profiling page load + +The following code profiles the time between the script first running and the window's {{domxref("Window.load_event", "load")}} event firing. + +```js +const profiler = new Profiler({ sampleInterval: 10, maxBufferSize: 10000 }); + +window.addEventListener("load", async () => { + const profile = await profiler.stop(); + console.log(JSON.stringify(profile)); +}); +``` + +## Specifications + +{{Specifications}} + +## Browser compatibility + +{{Compat}} diff --git a/files/en-us/web/api/profiler/profiler/index.md b/files/en-us/web/api/profiler/profiler/index.md new file mode 100644 index 000000000000000..e2078ea3e4d1189 --- /dev/null +++ b/files/en-us/web/api/profiler/profiler/index.md @@ -0,0 +1,55 @@ +--- +title: "Profiler: Profiler() constructor" +short-title: Profiler() +slug: Web/API/Profiler/Profiler +page-type: web-api-constructor +status: + - experimental +browser-compat: api.Profiler.Profiler +--- + +{{APIRef("JS Self-Profiling API")}}{{SeeCompatTable}} + +The **`Profiler()`** constructor creates a new {{domxref("Profiler")}} object. + +Once created, the new profiler will start collecting samples. + +## Syntax + +```js-nolint +new Profiler(options) +``` + +### Parameters + +- `options` + + - : Options for this profiler. This is an object containing the following properties: + + - `maxBufferSize` + - : A number indicating the maximum number of samples to take. Once this number is reached, the browser will fire the {{domxref("Profiler.samplebufferfull_event", "samplebufferfull")}} event at the profiler, and no more samples will be recorded. + - `sampleInterval` + - : The time interval between samples, in milliseconds. + +### Exceptions + +- `RangeError` {{domxref("DOMException")}} + - : Thrown if the `sampleInterval` option is less than zero. +- `NotAllowedError` {{domxref("DOMException")}} + - : Thrown if the document was not served with a [document policy](https://wicg.github.io/document-policy/) that included the `"js-profiling"` configuration point. + +## Examples + +This example creates a profiler which will take up to 1000 samples, sampling every 10 milliseconds. + +```js +const profiler = new Profiler({ sampleInterval: 10, maxBufferSize: 1000 }); +``` + +## Specifications + +{{Specifications}} + +## Browser compatibility + +{{Compat}} diff --git a/files/en-us/web/api/profiler/samplebufferfull_event/index.md b/files/en-us/web/api/profiler/samplebufferfull_event/index.md new file mode 100644 index 000000000000000..92511a067eb61dc --- /dev/null +++ b/files/en-us/web/api/profiler/samplebufferfull_event/index.md @@ -0,0 +1,49 @@ +--- +title: "Profiler: samplebufferfull event" +short-title: samplebufferfull +slug: Web/API/Profiler/samplebufferfull_event +page-type: web-api-event +browser-compat: api.Profiler.samplebufferfull_event +--- + +{{APIRef("JS Self-Profiling API")}} + +The **`samplebufferfull`** event of the {{domxref("Profiler")}} interface is fired when the number of samples the profiler has recorded matches the [`maxBufferSize`](/en-US/docs/Web/API/Profiler/Profiler#maxbuffersize) value passed to the profiler's constructor. + +After this event fires, the profiler will not record any more samples. + +This event is not cancelable and does not bubble. + +## Syntax + +Use the event name in methods like {{domxref("EventTarget.addEventListener", "addEventListener()")}}, or set an event handler property. + +```js-nolint +addEventListener("samplebufferfull", (event) => { }) + +onsamplebufferfull = (event) => { } +``` + +## Event type + +An {{domxref("Event")}}. + +## Examples + +```js +const profiler = new Profiler({ sampleInterval: 10, maxBufferSize: 100 }); + +profiler.addEventListener("samplebufferfull", async () => { + console.log("Sample buffer full!"); + const trace = await profiler.stop(); + console.log(JSON.stringify(trace)); +}); +``` + +## Specifications + +{{Specifications}} + +## Browser compatibility + +{{Compat}} diff --git a/files/en-us/web/api/profiler/stop/index.md b/files/en-us/web/api/profiler/stop/index.md new file mode 100644 index 000000000000000..394f2c197720325 --- /dev/null +++ b/files/en-us/web/api/profiler/stop/index.md @@ -0,0 +1,50 @@ +--- +title: "Profiler: stop() method" +short-title: stop() +slug: Web/API/Profiler/stop +page-type: web-api-instance-method +status: + - experimental +browser-compat: api.Profiler.stop +--- + +{{APIRef("JS Self-Profiling API")}}{{SeeCompatTable}} + +The **`stop()`** method of the {{domxref("Profiler")}} interface stops the profiler and returns a {{jsxref("Promise")}} which resolves to the profile itself. + +## Syntax + +```js-nolint +stop() +``` + +### Parameters + +None. + +### Return value + +A {{jsxref("Promise")}} that resolves to an object containing the profile data. The format and interpretation of this object is described in [Profile anatomy and format](/en-US/docs/Web/API/JS_Self-Profiling_API/Profile_content_and_format). + +## Examples + +### Recording a profile + +The following code profiles the `doWork()` operation, and logs the result. + +```js +const profiler = new Profiler({ sampleInterval: 10, maxBufferSize: 10000 }); + +doWork(); + +const profile = await profiler.stop(); +console.log(JSON.stringify(profile)); +``` + +## Specifications + +{{Specifications}} + +## Browser compatibility + +{{Compat}} diff --git a/files/en-us/web/api/progressevent/index.md b/files/en-us/web/api/progressevent/index.md index 2922bb7d4ab5838..5ac43749221bd6b 100644 --- a/files/en-us/web/api/progressevent/index.md +++ b/files/en-us/web/api/progressevent/index.md @@ -7,7 +7,7 @@ browser-compat: api.ProgressEvent {{APIRef("XMLHttpRequest API")}}{{AvailableInWorkers}} -The **`ProgressEvent`** interface represents events measuring progress of an underlying process, like an HTTP request (for an `XMLHttpRequest`, or the loading of the underlying resource of an {{HTMLElement("img")}}, {{HTMLElement("audio")}}, {{HTMLElement("video")}}, {{HTMLElement("style")}} or {{HTMLElement("link")}}). +The **`ProgressEvent`** interface represents events that measure the progress of an underlying process, like an HTTP request (e.g., an `XMLHttpRequest`, or the loading of the underlying resource of an {{HTMLElement("img")}}, {{HTMLElement("audio")}}, {{HTMLElement("video")}}, {{HTMLElement("style")}} or {{HTMLElement("link")}}). {{InheritanceDiagram}} @@ -21,11 +21,19 @@ The **`ProgressEvent`** interface represents events measuring progress of an und _Also inherits properties from its parent {{domxref("Event")}}_. - {{domxref("ProgressEvent.lengthComputable")}} {{ReadOnlyInline}} - - : A boolean flag indicating if the ratio between the size of the data already transmitted or processed (`loaded`), and the total size of the data (`total`), is calculable. In other words, it tells if the progress is measurable or not. + - : A boolean flag indicating if the ratio between the size of the data already transmitted or processed (`loaded`), and the total size of the data (`total`), is calculable. + In other words, it tells if the progress is measurable or not. - {{domxref("ProgressEvent.loaded")}} {{ReadOnlyInline}} - - : A 64-bit unsigned integer indicating the size, in bytes, of the data already transmitted or processed. The ratio can be calculated by dividing `ProgressEvent.total` by the value of this property. When downloading a resource using HTTP, this only counts the body of the HTTP message, and doesn't include headers and other overhead. Note that for compressed requests of unknown total size, `loaded` might contain the size of the compressed, or decompressed, data, depending on the browser. As of 2024, it contains the size of the compressed data in Firefox, and the size of the uncompressed data in Chrome. + - : A number indicating the size of the data already transmitted or processed. + For a `ProgressEvent` dispatched by the browser in HTTP messages, the value refers to the size, in bytes, of the message body, excluding headers and other overhead. + In compressed messages of unknown total size, `loaded` might refer to the size of the compressed or uncompressed data, depending on the browser. + As of 2024, it contains the size of the compressed data in Firefox, and the uncompressed data in Chrome. + In a `ProgressEvent` you create yourself, you can assign any numeric value to `loaded` that represents the amount of work completed relative to the `total` value. - {{domxref("ProgressEvent.total")}} {{ReadOnlyInline}} - - : A 64-bit unsigned integer indicating the total size, in bytes, of the data being transmitted or processed. When downloading a resource using HTTP, this value is taken from the `Content-Length` response header. It only counts the body of the HTTP message, and doesn't include headers and other overhead. + - : A number indicating the total size of the data being transmitted or processed. + For `ProgressEvent`s dispatched by the browser in HTTP messages, the value refers to the size, in bytes, of a resource and is derived from the `Content-Length` header. + In a `ProgressEvent` you create yourself, you may wish to normalize `total` to a value such as `100` or `1` if revealing the precise amount of bytes of a resource is a concern. + If using `1` as a total, for example, then `loaded` would be a decimal value between `0` and `1`. ## Instance methods @@ -33,7 +41,9 @@ _Inherits methods from its parent, {{domxref("Event")}}._ ## Examples -The following example adds a `ProgressEvent` to a new {{domxref("XMLHTTPRequest")}} and uses it to display the status of the request. +### Showing the status of a request + +The following example adds a `ProgressEvent` to a new {{domxref("XMLHttpRequest")}} and uses it to display the status of the request. ```js const progressBar = document.getElementById("p"), @@ -51,6 +61,28 @@ client.onloadend = (pe) => { client.send(); ``` +### Using fractions in a ProgressEvent + +The total number of bytes of a resource may reveal too much information about a resource, so a number between 0 and 1 may be used in a {{domxref("ProgressEvent.ProgressEvent", "ProgressEvent()")}} instead: + +```js +function updateProgress(loaded, total) { + const progressEvent = new ProgressEvent("progress", { + lengthComputable: true, + loaded, + total, + }); + + document.dispatchEvent(progressEvent); +} + +document.addEventListener("progress", (event) => { + console.log(`Progress: ${event.loaded}/${event.total}`); +}); + +updateProgress(0.123456, 1); +``` + ## Specifications {{Specifications}} diff --git a/files/en-us/web/api/progressevent/loaded/index.md b/files/en-us/web/api/progressevent/loaded/index.md index 14b3cb763466a6c..960aa6dbdece527 100644 --- a/files/en-us/web/api/progressevent/loaded/index.md +++ b/files/en-us/web/api/progressevent/loaded/index.md @@ -8,11 +8,14 @@ browser-compat: api.ProgressEvent.loaded {{APIRef("XMLHttpRequest API")}}{{AvailableInWorkers}} -The **`ProgressEvent.loaded`** read-only property is a 64-bit unsigned integer -indicating the size, in bytes, of the data already transmitted or processed. The ratio can be calculated by dividing the value of this property by `ProgressEvent.total`. -When downloading a resource using HTTP, this only counts the body of the HTTP message, and doesn't include headers and other overhead. +The **`ProgressEvent.loaded`** read-only property is a number indicating the size of the data already transmitted or processed. +The progress ratio can be calculated by dividing the value of this property by {{domxref("ProgressEvent.total")}}. -Note that for compressed requests of unknown total size, `loaded` might contain the size of the compressed, or decompressed, data, depending on the browser. As of 2024, it contains the size of the compressed data in Firefox, and the size of the uncompressed data in Chrome. +For `ProgressEvent`s dispatched by the browser in HTTP messages, the value refers to the amount of bytes of a resource that are completed, and is derived from the `Content-Length` header. +For compressed requests of unknown total size, `loaded` might contain the size of the compressed or decompressed data, depending on the browser. +As of 2024, it contains the size of the compressed data in Firefox, and the size of the uncompressed data in Chrome. + +In a `ProgressEvent` you create yourself, you can assign any numeric value to `loaded` that represents the amount of work completed relative to the `total` value. ## Value diff --git a/files/en-us/web/api/progressevent/progressevent/index.md b/files/en-us/web/api/progressevent/progressevent/index.md index b40ebff859fd83c..5dac6f085614f02 100644 --- a/files/en-us/web/api/progressevent/progressevent/index.md +++ b/files/en-us/web/api/progressevent/progressevent/index.md @@ -25,20 +25,20 @@ new ProgressEvent(type, options) - `options` {{optional_inline}} - : An object that, _in addition of the properties defined in {{domxref("Event/Event", "Event()")}}_, can have the following properties: - `lengthComputable` {{optional_inline}} - - : A boolean value indicating if the total work to be done, and the - amount of work already done, by the underlying process is calculable. In other words, - it tells if the progress is measurable or not. It defaults to `false`. + - : A boolean value indicating if the total work to be done, and the amount of work already done, by the underlying process is calculable. + In other words, it tells if the progress is measurable or not. + It defaults to `false`. - `loaded` {{optional_inline}} - - : A number representing the amount of work already - performed by the underlying process. The ratio of work done can be calculated with the - property and `ProgressEvent.total`. When downloading a resource using HTTP, - this only represent the part of the content itself, not headers and other overhead. It - defaults to `0`. + - : A number representing the amount of work already performed by the underlying process. + For a `ProgressEvent` dispatched by the browser in HTTP messages, the value refers to the size, in bytes, of the message body, excluding headers and other overhead. + In a `ProgressEvent` you create yourself, you can assign any numeric value to `loaded` that represents the amount of work completed relative to the `total` value. + It defaults to `0`. - `total` {{optional_inline}} - - : A number representing the total amount of work that the - underlying process is in the progress of performing. When downloading a resource using - HTTP, this only represent the content itself, not headers and other overhead. It - defaults to `0`. + - : A number indicating the total size of the data being transmitted or processed. + For `ProgressEvent`s dispatched by the browser in HTTP messages, the value refers to the size, in bytes, of a resource and is derived from the `Content-Length` response header. + In a `ProgressEvent` you create yourself, you may wish to normalize `total` to a value such as `100` or `1` if revealing the precise amount of bytes of a resource is a concern. + If using `1` as a total, for example, then `loaded` should be a decimal value between `0` and `1`. + It defaults to `0`. ### Return value @@ -46,14 +46,16 @@ A new {{domxref("ProgressEvent")}} object. ## Example +### File upload + The example demonstrates how a `ProgressEvent` is built using a constructor. This is particularly useful for tracking the progress of processes like file uploads, downloads, or any long-running tasks. ```js function updateProgress(loaded, total) { const progressEvent = new ProgressEvent("progress", { lengthComputable: true, - loaded: loaded, - total: total, + loaded, + total, }); document.dispatchEvent(progressEvent); @@ -66,6 +68,28 @@ document.addEventListener("progress", (event) => { updateProgress(50, 100); ``` +### Using fractions in a ProgressEvent + +The total number of bytes of a resource may reveal too much information about a download, so a number between 0 and 1 may be used instead: + +```js +function updateProgress(loaded, total) { + const progressEvent = new ProgressEvent("progress", { + lengthComputable: true, + loaded, + total, + }); + + document.dispatchEvent(progressEvent); +} + +document.addEventListener("progress", (event) => { + console.log(`Progress: ${event.loaded}/${event.total}`); +}); + +updateProgress(0.123456, 1); +``` + ## Specifications {{Specifications}} diff --git a/files/en-us/web/api/progressevent/total/index.md b/files/en-us/web/api/progressevent/total/index.md index f0673f9afbf850f..ea612b075de9a43 100644 --- a/files/en-us/web/api/progressevent/total/index.md +++ b/files/en-us/web/api/progressevent/total/index.md @@ -8,17 +8,19 @@ browser-compat: api.ProgressEvent.total {{APIRef("XMLHttpRequest API")}}{{AvailableInWorkers}} -The **`ProgressEvent.total`** read-only property is a 64-bit unsigned integer -indicating the total size, in bytes, of the data being transmitted or processed. +The **`ProgressEvent.total`** read-only property is a number indicating the total size of the data being transmitted or processed. -When downloading a resource using HTTP, this value is taken from the `Content-Length` response header. It only counts the body of the HTTP message, and doesn't include headers and other overhead. +For `ProgressEvent`s dispatched by the browser, the value refers to the size, in bytes, of a resource and is derived from the `Content-Length` response header. -If the event's {{domxref("ProgressEvent.lengthComputable", "lengthComputable")}} -property is `false`, this value is meaningless and should be ignored. +In a `ProgressEvent` you create yourself, this may also be the total bytes of a resource, although this can be any number. +For example, you may wish to normalize `total` to a value such as `100` or `1` if revealing the precise amount of bytes of a resource is a concern. +If using `1` as a total, then {{domxref("ProgressEvent.loaded")}} would be a decimal value between `0` and `1`. + +If the event's {{domxref("ProgressEvent.lengthComputable", "lengthComputable")}} property is `false`, this value is meaningless and should be ignored. ## Value -An integer. +A number. ## Specifications diff --git a/files/en-us/web/api/publickeycredential/getclientcapabilities_static/index.md b/files/en-us/web/api/publickeycredential/getclientcapabilities_static/index.md index 0af97b7a0759b55..ad9304eae103c16 100644 --- a/files/en-us/web/api/publickeycredential/getclientcapabilities_static/index.md +++ b/files/en-us/web/api/publickeycredential/getclientcapabilities_static/index.md @@ -64,9 +64,8 @@ For example, the key `extension:appid` can be used to check if the [`appid` exte The returned {{jsxref("Promise")}} may be rejected with the following values: -- `NotAllowedError` {{domxref("DOMException")}} - - : The Web Authentication API is not allowed in the current browsing context. - For example, it might be blocked by a permission policy. +- `SecurityError` {{domxref("DOMException")}} + - : The RP domain is not valid. ## Description diff --git a/files/en-us/web/api/publickeycredential/getclientextensionresults/index.md b/files/en-us/web/api/publickeycredential/getclientextensionresults/index.md index b1c784b0066782f..09d46c8564a9c0c 100644 --- a/files/en-us/web/api/publickeycredential/getclientextensionresults/index.md +++ b/files/en-us/web/api/publickeycredential/getclientextensionresults/index.md @@ -8,13 +8,9 @@ browser-compat: api.PublicKeyCredential.getClientExtensionResults {{APIRef("Web Authentication API")}}{{securecontext_header}} -The **`getClientExtensionResults()`** method of the -{{domxref("PublicKeyCredential")}} interface returns a map between the identifiers of extensions requested during credential creation or authentication, and their results after processing by the user agent. +The **`getClientExtensionResults()`** method of the {{domxref("PublicKeyCredential")}} interface returns a map between the identifiers of extensions requested during credential creation or authentication, and their results after processing by the user agent. -During the creation or fetching of a `PublicKeyCredential` (via -{{domxref("CredentialsContainer.create()","navigator.credentials.create()")}} and -{{domxref("CredentialsContainer.get()","navigator.credentials.get()")}} respectively), it is possible -to request "custom" processing by the client for different extensions, specified in the `publicKey` option's `extensions` property. You can find more information about requesting the different extensions in [Web Authentication extensions](/en-US/docs/Web/API/Web_Authentication_API/WebAuthn_extensions). +During the creation or fetching of a `PublicKeyCredential` (via {{domxref("CredentialsContainer.create()","navigator.credentials.create()")}} and {{domxref("CredentialsContainer.get()","navigator.credentials.get()")}} respectively), it is possible to request "custom" processing by the client for different extensions, specified in the `publicKey` option's `extensions` property. You can find more information about requesting the different extensions in [Web Authentication extensions](/en-US/docs/Web/API/Web_Authentication_API/WebAuthn_extensions). > **Note:** `getClientExtensionResults()` only returns the results from extensions processed by the user agent (client). The results from extensions processed by the authenticator can be found in the [authenticator data](/en-US/docs/Web/API/Web_Authentication_API/Authenticator_data) available in {{domxref("AuthenticatorAssertionResponse.authenticatorData")}}. @@ -32,6 +28,11 @@ None. A {{jsxref("Map", "map")}}, with each entry being an extensions' identifier string as the key, and the output from the processing of the extension by the client as the value. +### Exceptions + +- `SecurityError` {{domxref("DOMException")}} + - : The RP domain is not valid. + ## Examples ```js @@ -72,6 +73,6 @@ navigator.credentials ## See also -- [The list of the currently defined extensions](https://www.w3.org/TR/webauthn/#sctn-defined-extensions) +- [The list of the currently defined extensions](https://w3c.github.io/webauthn/#sctn-defined-extensions) - {{domxref("AuthenticatorAssertionResponse.authenticatorData")}} which contains the result of the authenticator's extensions processing diff --git a/files/en-us/web/api/publickeycredential/isconditionalmediationavailable_static/index.md b/files/en-us/web/api/publickeycredential/isconditionalmediationavailable_static/index.md index e07dfed8a05600c..0eb5223304b2161 100644 --- a/files/en-us/web/api/publickeycredential/isconditionalmediationavailable_static/index.md +++ b/files/en-us/web/api/publickeycredential/isconditionalmediationavailable_static/index.md @@ -24,6 +24,13 @@ None. A {{jsxref("Promise")}} which resolves to a boolean value indicating whether or not conditional mediation is available. +### Exceptions + +The returned {{jsxref("Promise")}} may be rejected with the following values: + +- `SecurityError` {{domxref("DOMException")}} + - : The RP domain is not valid. + ## Examples Before invoking a conditional WebAuthn API call, check if: @@ -43,7 +50,7 @@ if ( // Call WebAuthn authentication const publicKeyCredentialRequestOptions = { // Server generated challenge - challenge: ****, + challenge: challengeFromServer, // The same RP ID as used during registration rpId: "example.com", }; diff --git a/files/en-us/web/api/publickeycredential/isuserverifyingplatformauthenticatoravailable_static/index.md b/files/en-us/web/api/publickeycredential/isuserverifyingplatformauthenticatoravailable_static/index.md index a5109a2ae398187..8cec34df9cbb6e0 100644 --- a/files/en-us/web/api/publickeycredential/isuserverifyingplatformauthenticatoravailable_static/index.md +++ b/files/en-us/web/api/publickeycredential/isuserverifyingplatformauthenticatoravailable_static/index.md @@ -31,12 +31,17 @@ None. ### Return value -A {{jsxref("Promise")}} which resolves to a boolean value indicating whether or -a not a user-verifying platform authenticator is available. +A {{jsxref("Promise")}} which resolves to a boolean value indicating whether or a not a user-verifying platform authenticator is available. > [!NOTE] -> In earlier versions of the specification, the boolean also -> conveyed the consent of the user to disclose such an authenticator existed. +> In earlier versions of the specification, the boolean also conveyed the consent of the user to disclose such an authenticator existed. + +### Exceptions + +The returned {{jsxref("Promise")}} may be rejected with the following values: + +- `SecurityError` {{domxref("DOMException")}} + - : The RP domain is not valid. ## Examples diff --git a/files/en-us/web/api/publickeycredential/parsecreationoptionsfromjson_static/index.md b/files/en-us/web/api/publickeycredential/parsecreationoptionsfromjson_static/index.md index b5cce4bbbfcbd54..d16e2639e8157cf 100644 --- a/files/en-us/web/api/publickeycredential/parsecreationoptionsfromjson_static/index.md +++ b/files/en-us/web/api/publickeycredential/parsecreationoptionsfromjson_static/index.md @@ -32,6 +32,8 @@ A {{domxref("PublicKeyCredentialCreationOptions")}} object. - `EncodingError` {{domxref("DOMException")}} - : Thrown the `options` object cannot be converted into a {{domxref("PublicKeyCredentialCreationOptions")}} object. +- `SecurityError` {{domxref("DOMException")}} + - : The RP domain is not valid. ## Description diff --git a/files/en-us/web/api/publickeycredential/parserequestoptionsfromjson_static/index.md b/files/en-us/web/api/publickeycredential/parserequestoptionsfromjson_static/index.md index 1e0d5d2d94753d8..4debec1dd2dae44 100644 --- a/files/en-us/web/api/publickeycredential/parserequestoptionsfromjson_static/index.md +++ b/files/en-us/web/api/publickeycredential/parserequestoptionsfromjson_static/index.md @@ -32,6 +32,8 @@ A {{domxref("PublicKeyCredentialRequestOptions")}} instance. - `EncodingError` {{domxref("DOMException")}} - : Thrown if any part of the `options` object cannot be converted into a {{domxref("PublicKeyCredentialRequestOptions")}} instance. +- `SecurityError` {{domxref("DOMException")}} + - : The RP domain is not valid. ## Description @@ -48,15 +50,17 @@ When authorizing an already registered user, a relying party server will supply The code below defines this information in the form described in the [`options` parameter](#options) above: ```js -const requestCredentialOptionsJSON = { - challenge: new Uint8Array([139, 66, 181, 87, 7, 203, ...]), - rpId: "acme.com", - allowCredentials: [{ +const requestCredentialOptionsJSON = { + challenge: new Uint8Array([139, 66, 181, 87, 7, 203 /* … */]), + rpId: "acme.com", + allowCredentials: [ + { type: "public-key", - id: new Uint8Array([64, 66, 25, 78, 168, 226, 174, ...]) - }], - userVerification: "required", - } + id: new Uint8Array([64, 66, 25, 78, 168, 226, 174 /* … */]), + }, + ], + userVerification: "required", +}; ``` Because this object only uses JSON data types, it can be serialized to JSON using [`JSON.stringify()`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/JSON/stringify) and sent to the web app. diff --git a/files/en-us/web/api/publickeycredential/signalallacceptedcredentials_static/index.md b/files/en-us/web/api/publickeycredential/signalallacceptedcredentials_static/index.md index 687cdd7adae56c0..cbe0b26a3189622 100644 --- a/files/en-us/web/api/publickeycredential/signalallacceptedcredentials_static/index.md +++ b/files/en-us/web/api/publickeycredential/signalallacceptedcredentials_static/index.md @@ -73,7 +73,7 @@ if (PublicKeyCredential.signalAllAcceptedCredentials) { allAcceptedCredentialIds: [ // A list of base64url-encoded credential IDs "vI0qOggiE3OT01ZRWBYz5l4MEgU0c7PmAA", - // ... + // … ], }); } diff --git a/files/en-us/web/api/publickeycredential/signalunknowncredential_static/index.md b/files/en-us/web/api/publickeycredential/signalunknowncredential_static/index.md index e882d0ec9cb2280..e3e5c8d494f012a 100644 --- a/files/en-us/web/api/publickeycredential/signalunknowncredential_static/index.md +++ b/files/en-us/web/api/publickeycredential/signalunknowncredential_static/index.md @@ -68,9 +68,9 @@ As a result of this, we invoke the `signalUnknownCredential()` method, passing i ```js const credential = await navigator.credentials.get({ - challenge: new Uint8Array([139, 66, 181, 87, 7, 203, ...]), + challenge: new Uint8Array([139, 66, 181, 87, 7, 203 /* … */]), rpId: "example.com", - allowCredentials: [] + allowCredentials: [], // Empty allowCredentials list means only discoverable // credentials are presented to the user }); @@ -90,7 +90,7 @@ if (result.status === 404) { if (PublicKeyCredential.signalUnknownCredential) { await PublicKeyCredential.signalUnknownCredential({ rpId: "example.com", - credentialId: credID + credentialId: credID, }); } else { // Encourage the user to delete the credential from the authenticator diff --git a/files/en-us/web/api/publickeycredential/tojson/index.md b/files/en-us/web/api/publickeycredential/tojson/index.md index e68a3bde0e3c554..54e3b957ac92fa6 100644 --- a/files/en-us/web/api/publickeycredential/tojson/index.md +++ b/files/en-us/web/api/publickeycredential/tojson/index.md @@ -52,6 +52,11 @@ The object properties are: - When authenticating a user the returned value will be a JSON-type representation version of {{domxref("AuthenticatorAssertionResponse")}} where buffer values have been [base64url](/en-US/docs/Glossary/Base64) encoded. +### Exceptions + +- `SecurityError` {{domxref("DOMException")}} + - : The RP domain is not valid. + ## Examples When registering a new user, a relying party server will supply information about the expected credentials to the web app. @@ -70,7 +75,7 @@ const registration_url = "https://example.com/registration"; const apiRegOptsResp = await fetch(registration_url, { method: "POST", headers: { "Content-Type": "application/json" }, - body: JSON.stringify(newCredentialInfo), //Calls newCredentialInfo.toJSON + body: JSON.stringify(newCredentialInfo), // Calls newCredentialInfo.toJSON }); ``` diff --git a/files/en-us/web/api/publickeycredentialcreationoptions/index.md b/files/en-us/web/api/publickeycredentialcreationoptions/index.md index b67e504d76a236a..c2fc04f91e1b104 100644 --- a/files/en-us/web/api/publickeycredentialcreationoptions/index.md +++ b/files/en-us/web/api/publickeycredentialcreationoptions/index.md @@ -155,7 +155,7 @@ The **`PublicKeyCredentialCreationOptions`** dictionary represents the object pa If omitted, `id` defaults to the document origin — which would be `login.example.com` in the above example. - `name` - - : A string representing the name of the relying party (e.g. `"Facebook"`). This is the name the user will be presented with when creating or validating a WebAuthn operation. + - : A string representing the name of the relying party (e.g., `"Facebook"`). This is the name the user will be presented with when creating or validating a WebAuthn operation. - `timeout` {{optional_inline}} @@ -174,7 +174,7 @@ The **`PublicKeyCredentialCreationOptions`** dictionary represents the object pa - : An {{jsxref("ArrayBuffer")}}, {{jsxref("TypedArray")}}, or {{jsxref("DataView")}} representing a unique ID for the user account. This value has a maximum length of 64 bytes, and is not intended to be displayed to the user. - `name` - - : A string providing a human-friendly identifier for the user's account, to help distinguish between different accounts with similar `displayName`s. This could be an email address (such as `"john.doe@example.com"`), phone number (for example `"+12345678901"`), or some other kind of user account identifier (for example `"johndoe667"`). + - : A string providing a human-friendly identifier for the user's account, to help distinguish between different accounts with similar `displayName`s. This could be an email address (such as `"john.doe@example.com"`), phone number (for example `"+12345678901"`), or some other kind of user account identifier (for example `"JohnDoe667"`). - `hints` {{optional_inline}} diff --git a/files/en-us/web/api/push_api/index.md b/files/en-us/web/api/push_api/index.md index 6a1ae567a758f8a..d614a727f54970b 100644 --- a/files/en-us/web/api/push_api/index.md +++ b/files/en-us/web/api/push_api/index.md @@ -25,7 +25,7 @@ The resulting {{domxref("PushSubscription")}} includes all the information that The service worker will be started as necessary to handle incoming push messages, which are delivered to the {{domxref("ServiceWorkerGlobalScope.push_event", "onpush")}} event handler. This allows apps to react to push messages being received, for example, by displaying a notification (using {{domxref("ServiceWorkerRegistration.showNotification()")}}.) -Each subscription is unique to a service worker. The endpoint for the subscription is a unique [capability URL](https://www.w3.org/TR/capability-urls/): knowledge of the endpoint is all that is necessary to send a message to your application. The endpoint URL therefore needs to be kept secret, or other applications might be able to send push messages to your application. +Each subscription is unique to a service worker. The endpoint for the subscription is a unique [capability URL](https://w3ctag.github.io/capability-urls/): knowledge of the endpoint is all that is necessary to send a message to your application. The endpoint URL therefore needs to be kept secret, or other applications might be able to send push messages to your application. Activating a service worker to deliver a push message can result in increased resource usage, particularly of the battery. Different browsers have different schemes for handling this, there is currently no standard mechanism. Firefox allows a limited number (quota) of push messages to be sent to an application, although Push messages that generate notifications are exempt from this limit. The limit is refreshed each time the site is visited. In Chrome there are no limits. @@ -51,7 +51,7 @@ The following additions to the [Service Worker API](/en-US/docs/Web/API/Service_ - {{domxref("ServiceWorkerGlobalScope.push_event", "onpush")}} - : An event handler fired whenever a {{domxref("ServiceWorkerGlobalScope/push_event", "push")}} event occurs; that is, whenever a server push message is received. - {{domxref("ServiceWorkerGlobalScope.pushsubscriptionchange_event", "onpushsubscriptionchange")}} - - : An event handler fired whenever a {{domxref("ServiceWorkerGlobalScope/pushsubscriptionchange_event", "pushsubscriptionchange")}} event occurs; for example, when a push subscription has been invalidated, or is about to be invalidated (e.g. when a push service sets an expiration time.) + - : An event handler fired whenever a {{domxref("ServiceWorkerGlobalScope/pushsubscriptionchange_event", "pushsubscriptionchange")}} event occurs; for example, when a push subscription has been invalidated, or is about to be invalidated (e.g., when a push service sets an expiration time.) ## Examples diff --git a/files/en-us/web/api/pushmanager/supportedcontentencodings_static/index.md b/files/en-us/web/api/pushmanager/supportedcontentencodings_static/index.md index d9e7acaa86be818..e2bece048590948 100644 --- a/files/en-us/web/api/pushmanager/supportedcontentencodings_static/index.md +++ b/files/en-us/web/api/pushmanager/supportedcontentencodings_static/index.md @@ -45,23 +45,24 @@ One approach is to put the needed information from {{domxref("PushSubscription") ```js // Get a PushSubscription object -const pushSubscription = await serviceWorkerRegistration.pushManager.subscribe(); +const pushSubscription = + await serviceWorkerRegistration.pushManager.subscribe(); // Create an object containing the information needed by the app server const subscriptionObject = { endpoint: pushSubscription.endpoint, keys: { - p256dh: pushSubscription.getKeys('p256dh'), - auth: pushSubscription.getKeys('auth'), + p256dh: pushSubscription.getKeys("p256dh"), + auth: pushSubscription.getKeys("auth"), }, encoding: PushManager.supportedContentEncodings, /* other app-specific data, such as user identity */ }; // Stringify the object an post to the app server -fetch(`https://example.com/push/`, { - method: "post", - body: JSON.stringify(pushSubscription); +fetch("https://example.com/push/", { + method: "POST", + body: JSON.stringify(pushSubscription), }); ``` diff --git a/files/en-us/web/api/pushsubscription/getkey/index.md b/files/en-us/web/api/pushsubscription/getkey/index.md index e823f2fc7688d76..34a640d20db72a8 100644 --- a/files/en-us/web/api/pushsubscription/getkey/index.md +++ b/files/en-us/web/api/pushsubscription/getkey/index.md @@ -63,7 +63,7 @@ reg.pushManager.getSubscription().then((subscription) => { const key = subscription.getKey("p256dh"); const auth = subscription.getKey("auth"); - // ... + // … }); ``` diff --git a/files/en-us/web/api/range/clonecontents/index.md b/files/en-us/web/api/range/clonecontents/index.md index 8dc87e0841758aa..e247713a2e20621 100644 --- a/files/en-us/web/api/range/clonecontents/index.md +++ b/files/en-us/web/api/range/clonecontents/index.md @@ -8,16 +8,20 @@ browser-compat: api.Range.cloneContents {{ APIRef("DOM") }} -The **`Range.cloneContents()`** returns a {{domxref("DocumentFragment")}} copying the objects of type {{ domxref("Node") }} -included in the {{ domxref("Range") }}. +The **`cloneContents()`** method of the {{domxref("Range")}} interface copies the selected {{ domxref("Node") }} children of the range's {{domxref("Range/commonAncestorContainer", "commonAncestorContainer")}} and puts them in a new {{domxref("DocumentFragment")}} object. -Event listeners added using {{domxref("EventTarget.addEventListener()", "addEventListener()")}} -are not copied during cloning. HTML attribute events are duplicated as they are -for the {{ domxref("Node.cloneNode()") }} method. HTML `id` attributes -are also cloned, which can lead to an invalid document through cloning. +Nodes are cloned using the same algorithm as {{ domxref("Node.cloneNode()") }}, which means event listeners attached with scripts are not cloned. HTML `id` attributes are cloned, which can lead to an invalid document through cloning. -Partially selected nodes include the parent tags necessary to make the document -fragment valid. +The first and last selected children of `commonAncestorContainer` may be partially selected. In this case, the child node itself is cloned, but its content is only the part that is selected, by recursively cloning the range between the original range's start/end boundary and that child node's end/start boundary. + +```plain +<p>paragraph 1</p><p>paragraph 2</p><p>paragraph 3</p> + ^----------- selection ------------^ + +cloneContents() returns: + +<p>graph 1</p><p>paragraph 2</p><p>para</p> +``` ## Syntax diff --git a/files/en-us/web/api/range/collapse/index.md b/files/en-us/web/api/range/collapse/index.md index ae4c57739e79b64..0823030e5709c25 100644 --- a/files/en-us/web/api/range/collapse/index.md +++ b/files/en-us/web/api/range/collapse/index.md @@ -8,7 +8,7 @@ browser-compat: api.Range.collapse {{APIRef("DOM")}} -The **`Range.collapse()`** method collapses the +The **`collapse()`** method of the {{domxref("Range")}} interface collapses the {{domxref("Range")}} to one of its boundary points. A collapsed {{domxref("Range")}} is empty, containing no content, specifying a @@ -27,7 +27,7 @@ collapse(toStart) - `toStart` {{optional_inline}} - : A boolean value: `true` collapses the {{domxref("Range")}} to its start, `false` to its end. If omitted, it defaults to - `false` {{experimental_inline}}. + `false`. ### Return value diff --git a/files/en-us/web/api/range/compareboundarypoints/index.md b/files/en-us/web/api/range/compareboundarypoints/index.md index 8cf71434df5a432..404fb0717038c3b 100644 --- a/files/en-us/web/api/range/compareboundarypoints/index.md +++ b/files/en-us/web/api/range/compareboundarypoints/index.md @@ -8,39 +8,34 @@ browser-compat: api.Range.compareBoundaryPoints {{ApiRef("DOM")}} -The -**`Range.compareBoundaryPoints()`** method compares the -boundary points of the {{domxref("Range")}} with those of another range. +The **`compareBoundaryPoints()`** method of the {{domxref("Range")}} interface compares the boundary points of the {{domxref("Range")}} with those of another range. ## Syntax ```js-nolint -compareBoundaryPoints(how, sourceRange) +compareBoundaryPoints(how, otherRange) ``` ### Parameters - `how` - - : A constant describing the comparison method: - - - `Range.END_TO_END` compares the end boundary-point of - _sourceRange_ to the end boundary-point of `Range`. - - `Range.END_TO_START` compares the end boundary-point of - _sourceRange_ to the start boundary-point of `Range`. - - `Range.START_TO_END` compares the start boundary-point of - _sourceRange_ to the end boundary-point of `Range`. - - `Range.START_TO_START` compares the start boundary-point of - _sourceRange_ to the start boundary-point of `Range`. - -- `sourceRange` + - `Range.END_TO_END` compares the end boundary-point of this `Range` to the end boundary-point of `otherRange`. + - `Range.END_TO_START` compares the start boundary-point of this `Range` to the end boundary-point of `otherRange`. + - `Range.START_TO_END` compares the end boundary-point of this `Range` to the start boundary-point of `otherRange`. + - `Range.START_TO_START` compares the start boundary-point of this `Range` to the start boundary-point of `otherRange`. +- `otherRange` - : A {{domxref("Range")}} to compare boundary points with the range. ### Return value -A number, `-1`, `0`, or `1`, indicating whether the -corresponding boundary-point of the {{domxref("Range")}} is respectively before, equal -to, or after the corresponding boundary-point of _sourceRange_. +A number. + +- `-1` if the specified boundary-point of this `Range` is before the specified boundary-point of `otherRange`. +- `0` if the specified boundary-point of this `Range` is the same as the specified boundary-point of `otherRange`. +- `1` if the specified boundary-point of this `Range` is after the specified boundary-point of `otherRange`. + +This API is consistent with the general convention that, when comparing A to B, a negative number means A comes before B and vice versa (see for example {{jsxref("Array.prototype.sort()")}}). The ranges are compared in the direction of `this` to `other`, the same as {{jsxref("String.prototype.localeCompare()")}}. However, the boundary points are specified in the reverse order for the `how` parameter: `END_TO_START` compares the _start_ of `this` to the _end_ of `other`. ### Exceptions @@ -49,12 +44,35 @@ to, or after the corresponding boundary-point of _sourceRange_. ## Examples +Below, we create two ranges on the same text node and compare their different boundary points. + ```js -const range = document.createRange(); -range.selectNode(document.querySelector("div")); -const sourceRange = document.createRange(); -sourceRange.selectNode(document.getElementsByTagName("div")[1]); -const compare = range.compareBoundaryPoints(Range.START_TO_END, sourceRange); +const text = new Text("0123456789"); + +const thisRange = new Range(); +thisRange.setStart(text, 1); +thisRange.setEnd(text, 6); + +const otherRange = new Range(); +otherRange.setStart(text, 1); +otherRange.setEnd(text, 4); + +// The ranges look like this: +// thisRange start v---------v thisRange end +// 0 1 2 3 4 5 6 7 8 9 +// otherRange start ^-----^ otherRange end + +// this start is *same as* other start +thisRange.compareBoundaryPoints(Range.START_TO_START, otherRange); // 0 + +// this end is *after* other start +thisRange.compareBoundaryPoints(Range.START_TO_END, otherRange); // 1 + +// this start is *after* other end +thisRange.compareBoundaryPoints(Range.END_TO_START, otherRange); // -1 + +// this end is *after* other end +thisRange.compareBoundaryPoints(Range.END_TO_END, otherRange); // 1 ``` ## Specifications diff --git a/files/en-us/web/api/range/comparenode/index.md b/files/en-us/web/api/range/comparenode/index.md index 1262736be810f17..f19bc366d2c5e2f 100644 --- a/files/en-us/web/api/range/comparenode/index.md +++ b/files/en-us/web/api/range/comparenode/index.md @@ -11,10 +11,23 @@ browser-compat: api.Range.compareNode {{APIRef("DOM")}}{{deprecated_header}}{{Non-standard_Header}} -The **`Range.compareNode()`** returns a constant indicating the +The **`compareNode()`** method of the {{domxref("Range")}} interface returns a constant indicating the position of the {{DOMxRef("Node")}}. -The possible values are: +## Syntax + +```js-nolint +compareNode(referenceNode) +``` + +### Parameters + +- `referenceNode` + - : The {{DOMxRef("Node")}} to compare with the `Range`. + +### Return value + +A constant indicating the position of the {{DOMxRef("Node")}}. The possible values are: - `NODE_BEFORE` (`0`) - : Node starts before the Range @@ -23,16 +36,20 @@ The possible values are: - `NODE_BEFORE_AND_AFTER` (`2`) - : Node starts before and ends after the Range - `NODE_INSIDE` (`3`) - - : Node starts after and ends before the Range, i.e. the Node is completely selected by + - : Node starts after and ends before the Range, i.e., the Node is completely selected by the Range. -> [!WARNING] -> This method [has been removed](/en-US/docs/Mozilla/Firefox/Releases/3/Site_compatibility) from [Gecko 1.9](/en-US/docs/Mozilla/Firefox/Releases/3) and -> will not exist in future versions of Firefox, which was the only browser implementing -> it; you should switch to {{DOMxRef("Range.compareBoundaryPoints()")}} as soon as -> possible. +## Examples + +```js +range = document.createRange(); +range.selectNode(document.getElementsByTagName("div").item(0)); +returnValue = range.compareNode(document.getElementsByTagName("p").item(0)); +``` + +## Notes -The following function can be used as replacement: +This method is non-standard. The following function can be used as replacement: ```js function rangeCompareNode(range, node) { @@ -55,34 +72,6 @@ function rangeCompareNode(range, node) { } ``` -## Syntax - -```js-nolint -compareNode(referenceNode) -``` - -### Parameters - -- `referenceNode` - - : The {{DOMxRef("Node")}} to compare with the `Range`. - -### Return value - -A constant indicating the position of the {{DOMxRef("Node")}}. - -## Examples - -```js -range = document.createRange(); -range.selectNode(document.getElementsByTagName("div").item(0)); -returnValue = range.compareNode(document.getElementsByTagName("p").item(0)); -``` - -## Notes - -This method is obsolete; you should use the W3C DOM -{{DOMxRef("Range.compareBoundaryPoints()")}} method. - ## Specifications This method is not standard and therefore not part of any specification. diff --git a/files/en-us/web/api/range/comparepoint/index.md b/files/en-us/web/api/range/comparepoint/index.md index e53b7ac5f839c39..d557205fc0cca8b 100644 --- a/files/en-us/web/api/range/comparepoint/index.md +++ b/files/en-us/web/api/range/comparepoint/index.md @@ -8,15 +8,7 @@ browser-compat: api.Range.comparePoint {{ApiRef("DOM")}} -The **`Range.comparePoint()`** method returns `-1`, -`0`, or `1` depending on whether the `referenceNode` is -before, the same as, or after the {{domxref("Range")}}. - -If the _reference node_ is a {{domxref("Node")}} of type {{domxref("Text")}}, -{{domxref("Comment")}}, or {{domxref("CDATASection")}}, then offset is the number of -characters from the start of _reference node_. For other {{domxref("Node")}} -types, offset is the number of child nodes between the start of the _reference -node_. +The **`comparePoint()`** method of the {{domxref("Range")}} interface determines whether a specified point is before, within, or after the {{domxref("Range")}}. The point is specified by a reference node and an offset within that node. ## Syntax @@ -27,21 +19,31 @@ comparePoint(referenceNode, offset) ### Parameters - `referenceNode` - - : The {{domxref("Node")}} to compare with the {{domxref("Range")}}. + - : The {{domxref("Node")}} that the `offset` is relative to. - `offset` - - : An integer greater than or equal to zero representing the offset inside the - _referenceNode_. + - : An integer greater than or equal to zero describing the position inside `referenceNode` of the point to be checked. If `referenceNode` is a {{domxref("Node")}} of type {{domxref("Text")}}, {{domxref("Comment")}}, or {{domxref("CDATASection")}}, then `offset` is the number of characters from the start of `referenceNode`. For other {{domxref("Node")}} types, `offset` is the number of child nodes from the start of the `referenceNode`. ### Return value -Returns `-1`, `0`, or `1`. +A number. + +- `-1` if the point specified by the `referenceNode` and `offset` is before the start of this `Range`. +- `0` if the point specified by the `referenceNode` and `offset` is within this `Range` (including the start and end points of the range). +- `1` if the point specified by the `referenceNode` and `offset` is after the end of this `Range`. ## Examples ```js -range = document.createRange(); -range.selectNode(document.getElementsByTagName("div").item(0)); -returnValue = range.comparePoint(document.getElementsByTagName("p").item(0), 1); +const text = new Text("0123456789"); + +const thisRange = new Range(); +thisRange.setStart(text, 1); +thisRange.setEnd(text, 6); + +thisRange.comparePoint(text, 3); // 0 +thisRange.comparePoint(text, 0); // -1 +thisRange.comparePoint(text, 6); // 0 +thisRange.comparePoint(text, 7); // 1 ``` ## Specifications diff --git a/files/en-us/web/api/range/deletecontents/index.md b/files/en-us/web/api/range/deletecontents/index.md index 7ff52ab896332b8..3120d1e9f00b40c 100644 --- a/files/en-us/web/api/range/deletecontents/index.md +++ b/files/en-us/web/api/range/deletecontents/index.md @@ -8,13 +8,18 @@ browser-compat: api.Range.deleteContents {{ApiRef("DOM")}} -The **`Range.deleteContents()`** method removes the contents of -the {{ domxref("Range") }} from the {{ domxref("Document") }}. +The **`Range.deleteContents()`** method removes all completely-selected {{ domxref("Node", "nodes", "", "nocode") }} within this range from the document. For the partially selected nodes at the start or end of the range, only the selected portion of the text is deleted, while the node itself remains intact. Afterwards, the range is collapsed to the end of the last selected node. -In the context of a {{ domxref("Range") }}, when a node is partially selected—meaning it overlaps with the start or end of the selection—only the selected portion of the text is deleted, while the node itself remains intact. However, if a node is fully selected, the entire node and its contents are removed. +```plain +<p>paragraph 1</p><p>paragraph 2</p><p>paragraph 3</p> + ^----------- selection ------------^ -Unlike {{ domxref("Range.extractContents()") }}, this method does not return a -{{domxref("DocumentFragment")}} containing the deleted content. +deleteContents() returns: + +<p>para</p><p>graph 3</p> +``` + +Unlike {{ domxref("Range.extractContents()") }}, this method does not return a {{domxref("DocumentFragment")}} containing the deleted content. ## Syntax @@ -32,12 +37,35 @@ None ({{jsxref("undefined")}}). ## Examples +### Using deleteContents() + +Select some text, possibly spanning multiple paragraphs, and then click the button to delete the selected text. Open your DOM inspector to check the updated DOM structure. + +```html +<p>paragraph 1</p> +<p>paragraph 2</p> +<p>paragraph 3</p> +<button id="delete">Delete selected text</button> +<button id="reset">Reset</button> +``` + ```js -range = document.createRange(); -range.selectNode(document.getElementsByTagName("div").item(0)); -range.deleteContents(); +const button = document.getElementById("delete"); +const reset = document.getElementById("reset"); +const output = document.getElementById("output"); + +button.addEventListener("click", () => { + const range = document.getSelection().getRangeAt(0); + range.deleteContents(); +}); + +reset.addEventListener("click", () => { + window.location.reload(); +}); ``` +{{EmbedLiveSample("using_deletecontents", "", "150")}} + ## Specifications {{Specifications}} diff --git a/files/en-us/web/api/range/extractcontents/index.md b/files/en-us/web/api/range/extractcontents/index.md index e2614603da657dc..e1a70df619d0def 100644 --- a/files/en-us/web/api/range/extractcontents/index.md +++ b/files/en-us/web/api/range/extractcontents/index.md @@ -8,17 +8,7 @@ browser-compat: api.Range.extractContents {{ApiRef("DOM")}} -The **`Range.extractContents()`** method moves contents of the -{{ domxref("Range") }} from the document tree into a {{ domxref("DocumentFragment") }}. - -Event listeners added using DOM Events are not retained during extraction. HTML -attribute events are retained or duplicated as they are for the -{{domxref("Node.cloneNode()")}} method. HTML `id` attributes are also cloned, -which can lead to an invalid document if a partially-selected node is extracted and -appended to the document. - -Partially selected nodes are cloned to include the parent tags necessary to make the -document fragment valid. +The **`extractContents()`** method of the {{domxref("Range")}} interface is similar to a combination of {{domxref("Range.cloneContents()")}} and {{domxref("Range.deleteContents()")}}. It removes the child {{domxref("Node")}}s of the range from the document, clones them, and returns them as a new {{domxref("DocumentFragment")}} object. For partially selected nodes, only the selected text is deleted, but all containing parent nodes up to the common ancestor are cloned as well, resulting in two copies of these nodes, one in the original document and one in the extracted fragment. ## Syntax diff --git a/files/en-us/web/api/range/ispointinrange/index.md b/files/en-us/web/api/range/ispointinrange/index.md index 657951c787f1a6d..23ce4e9e479e046 100644 --- a/files/en-us/web/api/range/ispointinrange/index.md +++ b/files/en-us/web/api/range/ispointinrange/index.md @@ -8,10 +8,7 @@ browser-compat: api.Range.isPointInRange {{ApiRef("DOM")}} -The **`Range.isPointInRange()`** method returns a boolean -indicating whether the given point is in the {{domxref("Range")}}. It returns -`true` if the point (cursor position) at `offset` within -`ReferenceNode` is within this range. +The **`isPointInRange()`** method of the {{domxref("Range")}} interface determines whether a specified point is within the {{domxref("Range")}}. The point is specified by a reference node and an offset within that node. It is equivalent to calling {{domxref("Range.comparePoint()")}} and checking if the result is `0`. ## Syntax @@ -22,10 +19,9 @@ isPointInRange(referenceNode, offset) ### Parameters - `referenceNode` - - : The {{domxref("Node")}} to compare with the {{domxref("Range")}}. + - : The {{domxref("Node")}} that the `offset` is relative to. - `offset` - - : The offset into {{domxref("Node")}} of the point to compare with the - {{domxref("Range")}}. + - : An integer greater than or equal to zero describing the position inside `referenceNode` of the point to be checked. If `referenceNode` is a {{domxref("Node")}} of type {{domxref("Text")}}, {{domxref("Comment")}}, or {{domxref("CDATASection")}}, then `offset` is the number of characters from the start of `referenceNode`. For other {{domxref("Node")}} types, `offset` is the number of child nodes from the start of the `referenceNode`. ### Return value @@ -34,9 +30,16 @@ A boolean. ## Examples ```js -range = document.createRange(); -range.selectNode(document.getElementsByTagName("div").item(0)); -bool = range.isPointInRange(document.getElementsByTagName("p").item(0), 1); +const text = new Text("0123456789"); + +const thisRange = new Range(); +thisRange.setStart(text, 1); +thisRange.setEnd(text, 6); + +thisRange.isPointInRange(text, 3); // true +thisRange.isPointInRange(text, 0); // false +thisRange.isPointInRange(text, 6); // true +thisRange.isPointInRange(text, 7); // false ``` ## Specifications diff --git a/files/en-us/web/api/range/setend/index.md b/files/en-us/web/api/range/setend/index.md index 9c4ffde958df0ff..5f7de6daebfdbb0 100644 --- a/files/en-us/web/api/range/setend/index.md +++ b/files/en-us/web/api/range/setend/index.md @@ -8,7 +8,7 @@ browser-compat: api.Range.setEnd {{ApiRef("DOM")}} -The **`Range.setEnd()`** method sets the end position of a {{domxref("Range")}} to be located at the given offset into the specified node x.Setting +The **`Range.setEnd()`** method sets the end position of a {{domxref("Range")}} to be located at the given offset into the specified node. Setting the end point above (higher in the document) than the start point will result in a collapsed range with the start and end points both set to the specified end position. diff --git a/files/en-us/web/api/range/surroundcontents/index.md b/files/en-us/web/api/range/surroundcontents/index.md index b88823817668dbc..e784b7c03361cd4 100644 --- a/files/en-us/web/api/range/surroundcontents/index.md +++ b/files/en-us/web/api/range/surroundcontents/index.md @@ -8,19 +8,9 @@ browser-compat: api.Range.surroundContents {{ApiRef("DOM")}} -The **`Range.surroundContents()`** method moves content of the -{{ domxref("Range") }} into a new node, placing the new node at the start of the -specified range. - -This method is nearly equivalent to -`newNode.appendChild(range.extractContents()); range.insertNode(newNode)`. -After surrounding, the boundary points of the `range` include -`newNode`. - -An exception will be thrown, however, if the {{ domxref("Range") }} splits a non-{{domxref("Text") }} -node with only one of its boundary points. That is, unlike the -alternative above, if there are partially selected nodes, they will not be cloned and -instead the operation will fail. +The **`surroundContents()`** method of the {{domxref("Range")}} interface surrounds the selected content by a provided node. It [extracts](/en-US/docs/Web/API/Range/extractContents) the contents of the range, replaces the children of `newParent` with the extracted contents, [inserts](/en-US/docs/Web/API/Range/insertNode) `newParent` at the location of the extracted contents, and makes the range select `newParent`. + +An exception is thrown if the range partially contains any non-{{domxref("Text")}} node. The range must only contain text nodes and completely selected nodes. ## Syntax diff --git a/files/en-us/web/api/readablebytestreamcontroller/index.md b/files/en-us/web/api/readablebytestreamcontroller/index.md index 2dc1ad63eeb4b2a..72a2eeca8bfe3c8 100644 --- a/files/en-us/web/api/readablebytestreamcontroller/index.md +++ b/files/en-us/web/api/readablebytestreamcontroller/index.md @@ -14,17 +14,17 @@ An instance of this controller type is created if an `underlyingSource` object w The `underlyingSource` object may also define [`start()`](/en-US/docs/Web/API/ReadableStream/ReadableStream#start) and [`pull()`](/en-US/docs/Web/API/ReadableStream/ReadableStream#pull) callback functions. These are called with the controller as a parameter, in order to set up the underlying source, and request data when needed. -The underlying source uses the controller to supply data to the stream via its [`byobRequest`](#readablebytestreamcontroller.byobrequest) property or [`enqueue()`](#readablebytestreamcontroller.enqueue) method. -[`byobRequest`](#readablebytestreamcontroller.byobrequest) is a {{domxref("ReadableStreamBYOBRequest")}} object that represents a pending request from a consumer to make a zero-copy transfer of data direct to a consumer. +The underlying source uses the controller to supply data to the stream via its [`byobRequest`](/en-US/docs/Web/API/ReadableByteStreamController/byobRequest) property or [`enqueue()`](/en-US/docs/Web/API/ReadableByteStreamController/enqueue) method. +`byobRequest` is a {{domxref("ReadableStreamBYOBRequest")}} object that represents a pending request from a consumer to make a zero-copy transfer of data direct to a consumer. `byobRequest` must be used to copy data if it exists (do not use `enqueue()` in this case)! -If the underlying source needs to pass data to the stream and `byobRequest` is `null` then the source can call [`enqueue()`](#readablebytestreamcontroller.enqueue) to add the data to the stream's internal queues. +If the underlying source needs to pass data to the stream and `byobRequest` is `null` then the source can call `enqueue()` to add the data to the stream's internal queues. -Note that the [`byobRequest`](#readablebytestreamcontroller.byobrequest) is only created in "BYOB mode" when there is a request from a reader and the stream's internal queue is empty. +Note that the `byobRequest` is only created in "BYOB mode" when there is a request from a reader and the stream's internal queue is empty. "BYOB mode" is enabled when using a {{domxref("ReadableStreamBYOBReader")}} (typically constructed by calling {{domxref("ReadableStream.getReader()")}} with the argument `{ mode: 'byob' }`). -It is also enabled when using a default reader and [`autoAllocateChunkSize`](/en-US/docs/Web/API/ReadableStream/ReadableStream#autoallocatechunksize) is specified in the [`ReadableController()` constructor](/en-US/docs/Web/API/ReadableStream/ReadableStream#autoallocatechunksize). +It is also enabled when using a default reader and [`autoAllocateChunkSize`](/en-US/docs/Web/API/ReadableStream/ReadableStream#autoallocatechunksize) is specified in the [`ReadableStream()` constructor](/en-US/docs/Web/API/ReadableStream/ReadableStream). -An underlying byte source can also use the controller to [`close()`](#readablebytestreamcontroller.close) the stream when all the data has been sent and report errors from the underlying source using [`error()`](#readablebytestreamcontroller.error). -The controller's [`desiredSize`](#readablebytestreamcontroller.desiredsize) property is used to apply "backpressure", informing the underlying source of the size of the internal queue (small values indicate that the queue is filling up, hinting to the underlying source that it is be desirable to pause or throttle the inflow). +An underlying byte source can also use the controller to [`close()`](/en-US/docs/Web/API/ReadableByteStreamController/close) the stream when all the data has been sent and report errors from the underlying source using [`error()`](/en-US/docs/Web/API/ReadableByteStreamController/error). +The controller's [`desiredSize`](/en-US/docs/Web/API/ReadableByteStreamController/desiredSize) property is used to apply "backpressure", informing the underlying source of the size of the internal queue (small values indicate that the queue is filling up, hinting to the underlying source that it is be desirable to pause or throttle the inflow). Note that even though the controller is primarily used by the underlying byte source, there is no reason it cannot be stored used by other parts of the system to signal the stream. diff --git a/files/en-us/web/api/readablestream/locked/index.md b/files/en-us/web/api/readablestream/locked/index.md index 55acd4364b68596..71fa358d566f07e 100644 --- a/files/en-us/web/api/readablestream/locked/index.md +++ b/files/en-us/web/api/readablestream/locked/index.md @@ -21,7 +21,7 @@ A {{Glossary("boolean")}} value indicating whether or not the readable stream is ```js const stream = new ReadableStream({ - // ... + // … }); const reader = stream.getReader(); diff --git a/files/en-us/web/api/readablestream/readablestream/index.md b/files/en-us/web/api/readablestream/readablestream/index.md index e88f095728fa095..ad35001ae435aa1 100644 --- a/files/en-us/web/api/readablestream/readablestream/index.md +++ b/files/en-us/web/api/readablestream/readablestream/index.md @@ -52,7 +52,7 @@ new ReadableStream(underlyingSource, queuingStrategy) implementation will not be continually called. - `cancel` (reason) {{optional_inline}} - : This method, also defined by the developer, will be called if the app signals - that the stream is to be cancelled (e.g. if {{domxref("ReadableStream.cancel()")}} + that the stream is to be cancelled (e.g., if {{domxref("ReadableStream.cancel()")}} is called). The contents should do whatever is necessary to release access to the stream source. If this process is asynchronous, it can return a promise to signal success or failure. The `reason` parameter contains a diff --git a/files/en-us/web/api/readablestreambyobreader/index.md b/files/en-us/web/api/readablestreambyobreader/index.md index 5e93a8bcb965455..6232712b93bdad5 100644 --- a/files/en-us/web/api/readablestreambyobreader/index.md +++ b/files/en-us/web/api/readablestreambyobreader/index.md @@ -13,7 +13,7 @@ It is used for efficient copying from underlying sources where the data is deliv An instance of this reader type should usually be obtained by calling {{domxref("ReadableStream.getReader()")}} on the stream, specifying `mode: "byob"` in the options parameter. The readable stream must have an _underlying byte source_. In other words, it must have been [constructed](/en-US/docs/Web/API/ReadableStream/ReadableStream) specifying an underlying source with [`type: "bytes"`](/en-US/docs/Web/API/ReadableStream/ReadableStream#type)). -Using this kind of reader, a [`read()`](#readablestreambyobreader.read) request when the readable stream's internal queues are empty will result in a zero copy transfer from the underlying source (bypassing the stream's internal queues). +Using this kind of reader, a [`read()`](/en-US/docs/Web/API/ReadableStreamBYOBReader/read) request when the readable stream's internal queues are empty will result in a zero copy transfer from the underlying source (bypassing the stream's internal queues). If the internal queues are not empty, a `read()` will satisfy the request from the buffered data. Note that the methods and properties are similar to those for the default reader ({{domxref("ReadableStreamDefaultReader")}}). diff --git a/files/en-us/web/api/readablestreambyobreader/read/index.md b/files/en-us/web/api/readablestreambyobreader/read/index.md index 26896edda7a6a50..06d01784d4ba313 100644 --- a/files/en-us/web/api/readablestreambyobreader/read/index.md +++ b/files/en-us/web/api/readablestreambyobreader/read/index.md @@ -50,32 +50,17 @@ read(view, options) ### Return value -A {{jsxref("Promise")}}, which fulfills/rejects with a result depending on the state of the stream. +A {{jsxref("Promise")}}, which fulfills/rejects with a result depending on the state of the stream. The result object contains two properties, `value` and `done`. The following are possible: -- If a chunk is available and the stream is still active, the promise fulfills with an object of the form: - - ```js - { value: theChunk, done: false } - ``` - - `theChunk` is a view containing the new data. +- If a chunk is available and the stream is still active, the result's `done` is `false`, and `value` is a view containing the new data. This is a view of the same type and over the same backing memory as the `view` passed to the `read()` method. The original `view` will be detached and no longer usable. -- If the stream is closed, the promise fulfills with an object of the form (where `theChunk` has the same properties as above): - - ```js - { value: theChunk, done: true } - ``` - -- If the stream is cancelled, the promise fulfills with an object of the form: - - ```js - { value: undefined, done: true } - ``` +- If the stream is closed, the result's `done` is `true`, and `value` has the same properties as above. +- If the stream is cancelled, the result's `done` is `true`, and `value` is `undefined`. In this case the backing memory is discarded. - If the stream throws an error, the promise rejects with the relevant error. @@ -169,9 +154,9 @@ class MockHypotheticalSocket { const resultObj = {}; resultObj["bytesRead"] = 0; - return new Promise((resolve /*, reject*/) => { + return new Promise((resolve /*, reject */) => { if (this.data_read >= this.max_data) { - //out of data + // Out of data resolve(resultObj); return; } @@ -204,9 +189,7 @@ class MockHypotheticalSocket { } // Dummy close function - close() { - return; - } + close() {} // Return random number bytes in this call of socket getNumberRandomBytesSocket() { @@ -389,7 +372,7 @@ function readStream(reader) { offset += value.byteLength; bytesReceived += value.byteLength; - //logConsumer(`Read ${bytesReceived} bytes: ${value}`); + // logConsumer(`Read ${bytesReceived} bytes: ${value}`); logConsumer(`Read ${value.byteLength} bytes (total: ${bytesReceived})`); result += value; diff --git a/files/en-us/web/api/readablestreambyobrequest/index.md b/files/en-us/web/api/readablestreambyobrequest/index.md index fdae413601d5522..d591019aeb0418a 100644 --- a/files/en-us/web/api/readablestreambyobrequest/index.md +++ b/files/en-us/web/api/readablestreambyobrequest/index.md @@ -17,7 +17,7 @@ An underlying source that supports "BYOB mode" should check for {{domxref("Reada If data arrives from the underlying source when {{domxref("ReadableByteStreamController.byobRequest")}} is `null`, it can be queued using {{domxref("ReadableByteStreamController.enqueue()")}}. This might happen when an underlying push source receives new data when the stream's internal buffers are not empty. -An underlying source uses the request by writing data to the BYOB request's [`view`](#readablestreambyobrequest.view) and then calling [`respond()`](#readablestreambyobrequest.respond), or by calling [`respondWithNewView()`](#readablestreambyobrequest.respondwithnewview) and passing a new view as an argument. +An underlying source uses the request by writing data to the BYOB request's [`view`](/en-US/docs/Web/API/ReadableStreamBYOBRequest/view) and then calling [`respond()`](/en-US/docs/Web/API/ReadableStreamBYOBRequest/respond), or by calling [`respondWithNewView()`](/en-US/docs/Web/API/ReadableStreamBYOBRequest/respondWithNewView) and passing a new view as an argument. Note that the "new view" must actually be a view over the _same_ buffer as the original `view`, starting at the same offset. This might be used to return a shorter buffer if the underlying source is unable to fill the entire original view. @@ -37,11 +37,11 @@ None. `ReadableStreamBYOBRequest` instance is created automatically by `Readable ## Instance methods - {{domxref("ReadableStreamBYOBRequest.respond()")}} - - : Signals the associated readable byte stream that the specified number of bytes were written into the current [`view`](#readablestreambyobrequest.view), which then causes the pending request from the consumer to be resolved. + - : Signals the associated readable byte stream that the specified number of bytes were written into the current [`view`](/en-US/docs/Web/API/ReadableStreamBYOBRequest/view), which then causes the pending request from the consumer to be resolved. Note that after this method is called the `view` is transferred and no longer modifiable. - {{domxref("ReadableStreamBYOBRequest.respondWithNewView()")}} - : Signals to the associated readable byte stream view passed as an argument should be transferred to the consumer of the readable byte stream. - This new view must use the same buffer as the original [`view`](#readablestreambyobrequest.view), start at the same offset, and be the same length or shorter. + This new view must use the same buffer as the original [`view`](/en-US/docs/Web/API/ReadableStreamBYOBRequest/view), start at the same offset, and be the same length or shorter. Note that after this method is called the `view` is transferred and no longer modifiable. ## Examples diff --git a/files/en-us/web/api/readablestreamdefaultreader/read/index.md b/files/en-us/web/api/readablestreamdefaultreader/read/index.md index 82188fcfae11fa7..2a0b90ab5022c5a 100644 --- a/files/en-us/web/api/readablestreamdefaultreader/read/index.md +++ b/files/en-us/web/api/readablestreamdefaultreader/read/index.md @@ -90,7 +90,7 @@ async function* makeTextFileLineIterator(fileURL) { let { value: chunk, done: readerDone } = await reader.read(); chunk = chunk ? utf8Decoder.decode(chunk, { stream: true }) : ""; - let re = /\r\n|\n|\r/gm; + let re = /\r?\n/g; let startIndex = 0; for (;;) { diff --git a/files/en-us/web/api/readablestreamdefaultreader/releaselock/index.md b/files/en-us/web/api/readablestreamdefaultreader/releaselock/index.md index 7c886a24f93196e..4462e3278209ad9 100644 --- a/files/en-us/web/api/readablestreamdefaultreader/releaselock/index.md +++ b/files/en-us/web/api/readablestreamdefaultreader/releaselock/index.md @@ -40,11 +40,11 @@ None ({{jsxref("undefined")}}). function fetchStream() { const reader = stream.getReader(); - // ... + // … reader.releaseLock(); - // ... + // … } ``` diff --git a/files/en-us/web/api/relativeorientationsensor/index.md b/files/en-us/web/api/relativeorientationsensor/index.md index de4c8e523beeb2e..a5c10a6a8fd862a 100644 --- a/files/en-us/web/api/relativeorientationsensor/index.md +++ b/files/en-us/web/api/relativeorientationsensor/index.md @@ -9,7 +9,7 @@ browser-compat: api.RelativeOrientationSensor The **`RelativeOrientationSensor`** interface of the [Sensor APIs](/en-US/docs/Web/API/Sensor_APIs) describes the device's physical orientation without regard to the Earth's reference coordinate system. -To use this sensor, the user must grant permission to the `'accelerometer'`, and `'gyroscope'` device sensors through the [Permissions API](/en-US/docs/Web/API/Permissions_API). In addition, this feature may be blocked by a [Permissions Policy](/en-US/docs/Web/HTTP/Permissions_Policy) set on your server. +To use this sensor, the user must grant permission to the `'accelerometer'`, and `'gyroscope'` device sensors through the [Permissions API](/en-US/docs/Web/API/Permissions_API). In addition, this feature may be blocked by a [Permissions Policy](/en-US/docs/Web/HTTP/Guides/Permissions_Policy) set on your server. {{InheritanceDiagram}} @@ -67,7 +67,7 @@ Promise.all([ ]).then((results) => { if (results.every((result) => result.state === "granted")) { sensor.start(); - // ... + // … } else { console.log("No permissions to use RelativeOrientationSensor."); } diff --git a/files/en-us/web/api/relativeorientationsensor/relativeorientationsensor/index.md b/files/en-us/web/api/relativeorientationsensor/relativeorientationsensor/index.md index 1e0bfe08c5b010e..4636e119bd14468 100644 --- a/files/en-us/web/api/relativeorientationsensor/relativeorientationsensor/index.md +++ b/files/en-us/web/api/relativeorientationsensor/relativeorientationsensor/index.md @@ -39,7 +39,7 @@ new RelativeOrientationSensor(options) ### Exceptions - `SecurityError` {{domxref("DOMException")}} - - : Use of this feature was blocked by a [Permissions Policy](/en-US/docs/Web/HTTP/Permissions_Policy). + - : Use of this feature was blocked by a [Permissions Policy](/en-US/docs/Web/HTTP/Guides/Permissions_Policy). ## Specifications diff --git a/files/en-us/web/api/remote_playback_api/index.md b/files/en-us/web/api/remote_playback_api/index.md index 6b1d4a8c49733d4..e58095286312bfc 100644 --- a/files/en-us/web/api/remote_playback_api/index.md +++ b/files/en-us/web/api/remote_playback_api/index.md @@ -55,8 +55,8 @@ function availabilityCallback(available) { } videoElem.remote.watchAvailability(availabilityCallback).catch(() => { - /* If the device cannot continuously watch available, - show the button to allow the user to try to prompt for a connection.*/ + // If the device cannot continuously watch available, + // show the button to allow the user to try to prompt for a connection. deviceBtn.style.display = "inline"; }); ``` diff --git a/files/en-us/web/api/remoteplayback/cancelwatchavailability/index.md b/files/en-us/web/api/remoteplayback/cancelwatchavailability/index.md index 9586ec9d810ec5d..001e6b690a8e0a1 100644 --- a/files/en-us/web/api/remoteplayback/cancelwatchavailability/index.md +++ b/files/en-us/web/api/remoteplayback/cancelwatchavailability/index.md @@ -38,7 +38,7 @@ A {{jsxref("Promise")}} that resolves with `undefined`. ## Examples -Once a remote playback device has been identified and is connected, the monitoring of available devices can be stopped using `cancelWatchAvailability().` +Once a remote playback device has been identified and is connected, the monitoring of available devices can be stopped using `cancelWatchAvailability()`. ```js function switchToRemoteUI() { diff --git a/files/en-us/web/api/remoteplayback/connect_event/index.md b/files/en-us/web/api/remoteplayback/connect_event/index.md index bfb28baa130cf95..3e598c89a5af706 100644 --- a/files/en-us/web/api/remoteplayback/connect_event/index.md +++ b/files/en-us/web/api/remoteplayback/connect_event/index.md @@ -14,10 +14,10 @@ The **`connect`** event of the {{domxref("RemotePlayback")}} interface fires whe Use the event name in methods like {{domxref("EventTarget.addEventListener", "addEventListener()")}}, or set an event handler property. -```js -addEventListener("connect", (event) => {}); +```js-nolint +addEventListener("connect", (event) => { }) -onconnect = (event) => {}; +onconnect = (event) => { } ``` ## Event type diff --git a/files/en-us/web/api/remoteplayback/connecting_event/index.md b/files/en-us/web/api/remoteplayback/connecting_event/index.md index 29c07918f28d9b7..87e54ca42dece34 100644 --- a/files/en-us/web/api/remoteplayback/connecting_event/index.md +++ b/files/en-us/web/api/remoteplayback/connecting_event/index.md @@ -14,10 +14,10 @@ The **`connecting`** event of the {{domxref("RemotePlayback")}} interface fires Use the event name in methods like {{domxref("EventTarget.addEventListener", "addEventListener()")}}, or set an event handler property. -```js -addEventListener("connecting", (event) => {}); +```js-nolint +addEventListener("connecting", (event) => { }) -onconnecting = (event) => {}; +onconnecting = (event) => { } ``` ## Event type diff --git a/files/en-us/web/api/remoteplayback/disconnect_event/index.md b/files/en-us/web/api/remoteplayback/disconnect_event/index.md index 35670a871a9089c..7bd5404f87f7676 100644 --- a/files/en-us/web/api/remoteplayback/disconnect_event/index.md +++ b/files/en-us/web/api/remoteplayback/disconnect_event/index.md @@ -14,10 +14,10 @@ The **`disconnect`** event of the {{domxref("RemotePlayback")}} interface fires Use the event name in methods like {{domxref("EventTarget.addEventListener", "addEventListener()")}}, or set an event handler property. -```js -addEventListener("disconnect", (event) => {}); +```js-nolint +addEventListener("disconnect", (event) => { }) -ondisconnect = (event) => {}; +ondisconnect = (event) => { } ``` ## Event type diff --git a/files/en-us/web/api/remoteplayback/index.md b/files/en-us/web/api/remoteplayback/index.md index a63a7977040fb9e..2935aecafaaf853 100644 --- a/files/en-us/web/api/remoteplayback/index.md +++ b/files/en-us/web/api/remoteplayback/index.md @@ -70,8 +70,8 @@ function availabilityCallback(available) { } videoElem.remote.watchAvailability(availabilityCallback).catch(() => { - /* If the device cannot continuously watch available, - show the button to allow the user to try to prompt for a connection.*/ + // If the device cannot continuously watch available, + // show the button to allow the user to try to prompt for a connection. deviceBtn.style.display = "inline"; }); ``` diff --git a/files/en-us/web/api/report/index.md b/files/en-us/web/api/report/index.md index b280c07ca3a551e..5b6d37c1cf300d3 100644 --- a/files/en-us/web/api/report/index.md +++ b/files/en-us/web/api/report/index.md @@ -20,7 +20,7 @@ Reports can be accessed in a number of ways: - {{domxref("Report.body")}} {{ReadOnlyInline}} - : The body of the report, which is a `ReportBody` object containing the detailed report information. - {{domxref("Report.type")}} {{ReadOnlyInline}} - - : The type of report generated, e.g. `deprecation` or `intervention`. + - : The type of report generated, e.g., `deprecation` or `intervention`. - {{domxref("Report.url")}} {{ReadOnlyInline}} - : The URL of the document that generated the report. diff --git a/files/en-us/web/api/report/type/index.md b/files/en-us/web/api/report/type/index.md index ba884af9d6852e9..e24651d5e35fbfd 100644 --- a/files/en-us/web/api/report/type/index.md +++ b/files/en-us/web/api/report/type/index.md @@ -9,7 +9,7 @@ browser-compat: api.Report.type {{APIRef("Reporting API")}}{{AvailableInWorkers}} The **`type`** read-only property of the {{domxref("Report")}} -interface returns the type of report generated, e.g. `deprecation` or +interface returns the type of report generated, e.g., `deprecation` or `intervention`. ## Value diff --git a/files/en-us/web/api/reporting_api/index.md b/files/en-us/web/api/reporting_api/index.md index cd0272f9fd01d17..34137ca1cbdcd82 100644 --- a/files/en-us/web/api/reporting_api/index.md +++ b/files/en-us/web/api/reporting_api/index.md @@ -2,8 +2,7 @@ title: Reporting API slug: Web/API/Reporting_API page-type: web-api-overview -status: - - experimental +browser-compat: http.headers.Reporting-Endpoints spec-urls: - https://w3c.github.io/reporting/#intro - https://w3c.github.io/webappsec-csp/#cspviolationreportbody @@ -11,16 +10,16 @@ spec-urls: - https://wicg.github.io/intervention-reporting/#intervention-report --- -{{SeeCompatTable}}{{DefaultAPISidebar("Reporting API")}}{{AvailableInWorkers}} +{{DefaultAPISidebar("Reporting API")}}{{AvailableInWorkers}} -The Reporting API provides a generic reporting mechanism for web applications to use to make reports available based on various platform features (for example [Content Security Policy](/en-US/docs/Web/HTTP/CSP), [Permissions-Policy](/en-US/docs/Web/HTTP/Headers/Permissions-Policy), or feature deprecation reports) in a consistent manner. +The Reporting API provides a generic reporting mechanism for web applications to use to make reports available based on various platform features (for example [Content Security Policy](/en-US/docs/Web/HTTP/Guides/CSP), [Permissions-Policy](/en-US/docs/Web/HTTP/Reference/Headers/Permissions-Policy), or feature deprecation reports) in a consistent manner. ## Concepts and usage There are several different features and problems on the web platform that generate information useful to web developers when they are trying to fix bugs or improve their websites in other ways. Such information can include: -- [Content Security Policy](/en-US/docs/Web/HTTP/CSP) violations. -- [Permissions-Policy](/en-US/docs/Web/HTTP/Headers/Permissions-Policy) violations. +- [Content Security Policy](/en-US/docs/Web/HTTP/Guides/CSP) violations. +- [Permissions-Policy](/en-US/docs/Web/HTTP/Reference/Headers/Permissions-Policy) violations. - Deprecated feature usage (when you are using something that will stop working soon in browsers). - Occurrence of crashes. - Occurrence of user-agent interventions (when the browser blocks something your code is trying to do because it is deemed a security risk for example, or just plain annoying, like auto-playing audio). @@ -79,7 +78,7 @@ The Reporting API spec also defines a Generate Test Report [WebDriver](/en-US/do - {{domxref("DeprecationReportBody")}} - : Contains details of deprecated web platform features that a website is using. - {{domxref("InterventionReportBody")}} - - : Contains details of an intervention report, which is generated when a request made by the website has been denied by the browser; e.g. for security reasons. + - : Contains details of an intervention report, which is generated when a request made by the website has been denied by the browser; e.g., for security reasons. - {{domxref("Report")}} - : An object representing a single report. - {{domxref("ReportingObserver")}} @@ -87,7 +86,7 @@ The Reporting API spec also defines a Generate Test Report [WebDriver](/en-US/do ### Related interfaces -These interfaces are defined as part of the HTTP [Content Security Policy (CSP)](/en-US/docs/Web/HTTP/CSP) specifications: +These interfaces are defined as part of the HTTP [Content Security Policy (CSP)](/en-US/docs/Web/HTTP/Guides/CSP) specifications: - {{domxref("CSPViolationReportBody")}} - : Contains details of a CSP violation. @@ -102,7 +101,7 @@ These HTTP response headers define the endpoints where reports are sent. - : Sets the name and URL of reporting endpoints. These endpoints can be used in the `report-to` directive, which may be used with a number of HTTP headers including {{httpheader("Content-Security-Policy")}} and or {{HTTPHeader("Content-Security-Policy-Report-Only")}}. - {{HTTPHeader("Report-To")}} {{deprecated_inline}} - - : Sets the name and URL of reporting endpoint groups, which may be used with a number of HTTP headers including `Content-Security-Policy`. + - : No longer part of the Reporting API but still supported by some browsers. This sets the name and URL of reporting endpoint groups, which may be used with a number of HTTP headers especially for [Network Error Logging](/en-US/docs/Web/HTTP/Guides/Network_Error_Logging) that has not yet been updated to support `Reporting-Endpoints`. Other Reporting API reports should use `Reporting-Endpoints` instead for better future support. Report endpoints can be set for the following reports using the `report-to` directive on the corresponding headers: @@ -156,11 +155,9 @@ This causes a deprecation report to be generated; because of the event handler w ## Browser compatibility -The API is supported by Chromium browsers, and by Firefox behind a preference (`dom.reporting.enabled`). - -See the specific interfaces for more detailed support information. +{{Compat}} ## See also -- [Content Security Policy](/en-US/docs/Web/HTTP/CSP) -- [`Permissions-Policy`](/en-US/docs/Web/HTTP/Headers/Permissions-Policy) +- [Content Security Policy](/en-US/docs/Web/HTTP/Guides/CSP) +- [`Permissions-Policy`](/en-US/docs/Web/HTTP/Reference/Headers/Permissions-Policy) diff --git a/files/en-us/web/api/reportingobserver/disconnect/index.md b/files/en-us/web/api/reportingobserver/disconnect/index.md index 56c4c0cdfa4f8c4..caa5d2dc01ddca2 100644 --- a/files/en-us/web/api/reportingobserver/disconnect/index.md +++ b/files/en-us/web/api/reportingobserver/disconnect/index.md @@ -46,7 +46,7 @@ const observer = new ReportingObserver((reports, observer) => { observer.observe(); -// ... +// … observer.disconnect(); ``` diff --git a/files/en-us/web/api/reportingobserver/reportingobserver/index.md b/files/en-us/web/api/reportingobserver/reportingobserver/index.md index 7616adfeb0df98e..4a58c16f356e06a 100644 --- a/files/en-us/web/api/reportingobserver/reportingobserver/index.md +++ b/files/en-us/web/api/reportingobserver/reportingobserver/index.md @@ -23,7 +23,7 @@ new ReportingObserver(callback, options) - `callback` - - : A callback function that runs when the observer starts to collect reports (i.e. via + - : A callback function that runs when the observer starts to collect reports (i.e., via {{domxref("ReportingObserver.observe()")}}). The callback function is given two parameters: diff --git a/files/en-us/web/api/request/cache/index.md b/files/en-us/web/api/request/cache/index.md index 6bd52ae418d9a47..f0953b6799deb96 100644 --- a/files/en-us/web/api/request/cache/index.md +++ b/files/en-us/web/api/request/cache/index.md @@ -8,7 +8,7 @@ browser-compat: api.Request.cache {{APIRef("Fetch API")}}{{AvailableInWorkers}} -The **`cache`** read-only property of the {{domxref("Request")}} interface contains the cache mode of the request. It controls how the request will interact with the browser's [HTTP cache](/en-US/docs/Web/HTTP/Caching). +The **`cache`** read-only property of the {{domxref("Request")}} interface contains the cache mode of the request. It controls how the request will interact with the browser's [HTTP cache](/en-US/docs/Web/HTTP/Guides/Caching). ## Value @@ -16,15 +16,15 @@ A `RequestCache` value. The available values are: - `default` — The browser looks for a matching request in its HTTP cache. - - If there is a match and it is [fresh](/en-US/docs/Web/HTTP/Caching#fresh_and_stale_based_on_age), it will be returned from the cache. - - If there is a match but it is [stale](/en-US/docs/Web/HTTP/Caching#fresh_and_stale_based_on_age), the browser will make a [conditional request](/en-US/docs/Web/HTTP/Conditional_requests) to the remote server. If the server indicates that the resource has not changed, it will be returned from the cache. Otherwise the resource will be downloaded from the server and the cache will be updated. + - If there is a match and it is [fresh](/en-US/docs/Web/HTTP/Guides/Caching#fresh_and_stale_based_on_age), it will be returned from the cache. + - If there is a match but it is [stale](/en-US/docs/Web/HTTP/Guides/Caching#fresh_and_stale_based_on_age), the browser will make a [conditional request](/en-US/docs/Web/HTTP/Guides/Conditional_requests) to the remote server. If the server indicates that the resource has not changed, it will be returned from the cache. Otherwise the resource will be downloaded from the server and the cache will be updated. - If there is no match, the browser will make a normal request, and will update the cache with the downloaded resource. - `no-store` — The browser fetches the resource from the remote server without first looking in the cache, _and will not_ update the cache with the downloaded resource. - `reload` — The browser fetches the resource from the remote server without first looking in the cache, _but then will_ update the cache with the downloaded resource. - `no-cache` — The browser looks for a matching request in its HTTP cache. - - If there is a match, _fresh or stale,_ the browser will make a [conditional request](/en-US/docs/Web/HTTP/Conditional_requests) to the remote server. If the server indicates that the resource has not changed, it will be returned from the cache. Otherwise the resource will be downloaded from the server and the cache will be updated. + - If there is a match, _fresh or stale,_ the browser will make a [conditional request](/en-US/docs/Web/HTTP/Guides/Conditional_requests) to the remote server. If the server indicates that the resource has not changed, it will be returned from the cache. Otherwise the resource will be downloaded from the server and the cache will be updated. - If there is no match, the browser will make a normal request, and will update the cache with the downloaded resource. - `force-cache` — The browser looks for a matching request in its HTTP cache. @@ -35,7 +35,7 @@ A `RequestCache` value. The available values are: - `only-if-cached` — The browser looks for a matching request in its HTTP cache. {{experimental_inline}} - If there is a match, _fresh or stale_, it will be returned from the cache. - - If there is no match, the browser will respond with a [504 Gateway timeout](/en-US/docs/Web/HTTP/Status/504) status. + - If there is no match, the browser will respond with a [504 Gateway timeout](/en-US/docs/Web/HTTP/Reference/Status/504) status. The `"only-if-cached"` mode can only be used if the request's [`mode`](/en-US/docs/Web/API/Request/mode) is `"same-origin"`. Cached redirects will be followed if the request's `redirect` property is `"follow"` and the redirects do not violate the `"same-origin"` mode. @@ -133,5 +133,5 @@ fetch("some.json", { ## See also - [ServiceWorker API](/en-US/docs/Web/API/Service_Worker_API) -- [HTTP access control (CORS)](/en-US/docs/Web/HTTP/CORS) +- [HTTP access control (CORS)](/en-US/docs/Web/HTTP/Guides/CORS) - [HTTP](/en-US/docs/Web/HTTP) diff --git a/files/en-us/web/api/request/clone/index.md b/files/en-us/web/api/request/clone/index.md index 91d2c2f789dade1..eac8edbe787a8e4 100644 --- a/files/en-us/web/api/request/clone/index.md +++ b/files/en-us/web/api/request/clone/index.md @@ -55,5 +55,5 @@ const newRequest = myRequest.clone(); // a copy of the request is now stored in ## See also - [Service Worker API](/en-US/docs/Web/API/Service_Worker_API) -- [HTTP access control (CORS)](/en-US/docs/Web/HTTP/CORS) +- [HTTP access control (CORS)](/en-US/docs/Web/HTTP/Guides/CORS) - [HTTP](/en-US/docs/Web/HTTP) diff --git a/files/en-us/web/api/request/credentials/index.md b/files/en-us/web/api/request/credentials/index.md index 170685b1f8e4dbe..84ec7e1a08d2037 100644 --- a/files/en-us/web/api/request/credentials/index.md +++ b/files/en-us/web/api/request/credentials/index.md @@ -22,6 +22,7 @@ A string with one of the following values: - : Never send credentials in the request or include credentials in the response. - `same-origin` - : Only send and include credentials for same-origin requests. + This is the default. - `include` - : Always include credentials, even for cross-origin requests. @@ -45,5 +46,5 @@ const credentials = request.credentials; // returns "same-origin" by default ## See also - [ServiceWorker API](/en-US/docs/Web/API/Service_Worker_API) -- [HTTP access control (CORS)](/en-US/docs/Web/HTTP/CORS) +- [HTTP access control (CORS)](/en-US/docs/Web/HTTP/Guides/CORS) - [HTTP](/en-US/docs/Web/HTTP) diff --git a/files/en-us/web/api/request/destination/index.md b/files/en-us/web/api/request/destination/index.md index 4493e87f734af83..118d78ece6d0ae1 100644 --- a/files/en-us/web/api/request/destination/index.md +++ b/files/en-us/web/api/request/destination/index.md @@ -41,8 +41,8 @@ Possible values are: - `""` - : The empty string is the default value, and is used for destinations that do not have their own value. This is the value when requests are made using the following APIs (among others): - - [`<a ping>`](/en-US/docs/Web/HTML/Element/a#ping) - - [`<area ping>`](/en-US/docs/Web/HTML/Element/area#ping) + - [`<a ping>`](/en-US/docs/Web/HTML/Reference/Elements/a#ping) + - [`<area ping>`](/en-US/docs/Web/HTML/Reference/Elements/area#ping) - {{domxref("Cache")}} - {{domxref("EventSource")}} - {{domxref("Window/fetch", "fetch()")}} @@ -113,5 +113,5 @@ const myDestination = myRequest.destination; // returns the empty string by defa ## See also - [ServiceWorker API](/en-US/docs/Web/API/Service_Worker_API) -- [HTTP access control (CORS)](/en-US/docs/Web/HTTP/CORS) +- [HTTP access control (CORS)](/en-US/docs/Web/HTTP/Guides/CORS) - [HTTP](/en-US/docs/Web/HTTP) diff --git a/files/en-us/web/api/request/headers/index.md b/files/en-us/web/api/request/headers/index.md index 70b8707ee233ea3..040bceacbfc703e 100644 --- a/files/en-us/web/api/request/headers/index.md +++ b/files/en-us/web/api/request/headers/index.md @@ -58,5 +58,5 @@ const myContentType = myRequest.headers.get("Content-Type"); // returns 'image/j ## See also - [ServiceWorker API](/en-US/docs/Web/API/Service_Worker_API) -- [HTTP access control (CORS)](/en-US/docs/Web/HTTP/CORS) +- [HTTP access control (CORS)](/en-US/docs/Web/HTTP/Guides/CORS) - [HTTP](/en-US/docs/Web/HTTP) diff --git a/files/en-us/web/api/request/index.md b/files/en-us/web/api/request/index.md index 00b0046686c8a64..1c3fbcb67e72792 100644 --- a/files/en-us/web/api/request/index.md +++ b/files/en-us/web/api/request/index.md @@ -25,7 +25,7 @@ You can create a new `Request` object using the {{domxref("Request.Request","Req - {{domxref("Request.cache")}} {{ReadOnlyInline}} - : Contains the cache mode of the request (e.g., `default`, `reload`, `no-cache`). - {{domxref("Request.credentials")}} {{ReadOnlyInline}} - - : Contains the credentials of the request (e.g., `omit`, `same-origin`, `include`). The default is `same-origin`. + - : Contains a value controlling whether credentials should be included with the request (e.g., `omit`, `same-origin`, `include`). The default is `same-origin`. - {{domxref("Request.destination")}} {{ReadOnlyInline}} - : A string describing the type of content being requested. - {{domxref("Request.headers")}} {{ReadOnlyInline}} @@ -93,7 +93,7 @@ fetch(request) }); ``` -In the following snippet, we create a new request using the `Request()` constructor with some initial data and body content for an API request which need a body payload: +In the following snippet, we create a new request using the `Request()` constructor with some initial data and body content for an API request which needs a body payload: ```js const request = new Request("https://example.com", { @@ -115,11 +115,10 @@ You could then fetch this API request by passing the `Request` object in as a pa ```js fetch(request) .then((response) => { - if (response.status === 200) { - return response.json(); - } else { + if (response.status !== 200) { throw new Error("Something went wrong on API server!"); } + return response.json(); }) .then((response) => { console.debug(response); @@ -141,5 +140,5 @@ fetch(request) ## See also - [ServiceWorker API](/en-US/docs/Web/API/Service_Worker_API) -- [HTTP access control (CORS)](/en-US/docs/Web/HTTP/CORS) +- [HTTP access control (CORS)](/en-US/docs/Web/HTTP/Guides/CORS) - [HTTP](/en-US/docs/Web/HTTP) diff --git a/files/en-us/web/api/request/integrity/index.md b/files/en-us/web/api/request/integrity/index.md index f7853bb1db068f0..ce0ae6fec680b05 100644 --- a/files/en-us/web/api/request/integrity/index.md +++ b/files/en-us/web/api/request/integrity/index.md @@ -45,5 +45,5 @@ console.log(myRequest.integrity); // "sha256-abc123" ## See also - [ServiceWorker API](/en-US/docs/Web/API/Service_Worker_API) -- [HTTP access control (CORS)](/en-US/docs/Web/HTTP/CORS) +- [HTTP access control (CORS)](/en-US/docs/Web/HTTP/Guides/CORS) - [HTTP](/en-US/docs/Web/HTTP) diff --git a/files/en-us/web/api/request/ishistorynavigation/index.md b/files/en-us/web/api/request/ishistorynavigation/index.md index 2a45ece9bc55418..80a70b2e97d3e0f 100644 --- a/files/en-us/web/api/request/ishistorynavigation/index.md +++ b/files/en-us/web/api/request/ishistorynavigation/index.md @@ -22,29 +22,28 @@ This example executes in a service worker. It listens for the {{domxref("Service ```js self.addEventListener("request", (event) => { - // ... + // … if (event.request.isHistoryNavigation) { event.respondWith( caches.match(event.request).then((response) => { if (response !== undefined) { return response; - } else { - return fetch(event.request).then((response) => { - let responseClone = response.clone(); + } + return fetch(event.request).then((response) => { + const responseClone = response.clone(); - caches.open("v1").then((cache) => { - cache.put(event.request, responseClone); - }); + caches + .open("v1") + .then((cache) => cache.put(event.request, responseClone)); - return response; - }); - } + return response; + }); }), ); } - // ... + // … }); ``` diff --git a/files/en-us/web/api/request/keepalive/index.md b/files/en-us/web/api/request/keepalive/index.md index da6041784b6a125..4410bc93a2c16fc 100644 --- a/files/en-us/web/api/request/keepalive/index.md +++ b/files/en-us/web/api/request/keepalive/index.md @@ -11,7 +11,7 @@ browser-compat: api.Request.keepalive The **`keepalive`** read-only property of the {{domxref("Request")}} interface contains the request's `keepalive` setting (`true` or `false`), which indicates whether the browser will keep the associated request alive if the page that initiated it is unloaded before the request is complete. This enables a {{domxref('Window.fetch','fetch()')}} request to, for example, send analytics at the end of a session even if the user navigates away from or closes the page. -This has some advantages over using {{domxref("Navigator.sendBeacon()")}} for the same purpose, including allowing you to use HTTP methods other than [`POST`](/en-US/docs/Web/HTTP/Methods/POST), customize request properties, and access the server response via the fetch {{jsxref("Promise")}} fulfillment. +This has some advantages over using {{domxref("Navigator.sendBeacon()")}} for the same purpose, including allowing you to use HTTP methods other than [`POST`](/en-US/docs/Web/HTTP/Reference/Methods/POST), customize request properties, and access the server response via the fetch {{jsxref("Promise")}} fulfillment. It is also available in [service workers](/en-US/docs/Web/API/Service_Worker_API). ## Value @@ -44,5 +44,5 @@ let myKeepAlive = myRequest.keepalive; // true ## See also - [ServiceWorker API](/en-US/docs/Web/API/Service_Worker_API) -- [HTTP access control (CORS)](/en-US/docs/Web/HTTP/CORS) +- [HTTP access control (CORS)](/en-US/docs/Web/HTTP/Guides/CORS) - [HTTP](/en-US/docs/Web/HTTP) diff --git a/files/en-us/web/api/request/method/index.md b/files/en-us/web/api/request/method/index.md index d02afd9b654bce2..ba46cfad6640f0c 100644 --- a/files/en-us/web/api/request/method/index.md +++ b/files/en-us/web/api/request/method/index.md @@ -38,5 +38,5 @@ const myMethod = myRequest.method; // GET ## See also - [ServiceWorker API](/en-US/docs/Web/API/Service_Worker_API) -- [HTTP access control (CORS)](/en-US/docs/Web/HTTP/CORS) +- [HTTP access control (CORS)](/en-US/docs/Web/HTTP/Guides/CORS) - [HTTP](/en-US/docs/Web/HTTP) diff --git a/files/en-us/web/api/request/mode/index.md b/files/en-us/web/api/request/mode/index.md index 090fb142ae38bc0..c3d26fedbf0466a 100644 --- a/files/en-us/web/api/request/mode/index.md +++ b/files/en-us/web/api/request/mode/index.md @@ -31,7 +31,7 @@ One of the following values: - `cors` - - : If the request is cross-origin then it will use the [Cross-Origin Resource Sharing (CORS)](/en-US/docs/Web/HTTP/CORS) mechanism. + - : If the request is cross-origin then it will use the [Cross-Origin Resource Sharing (CORS)](/en-US/docs/Web/HTTP/Guides/CORS) mechanism. - `navigate` @@ -49,7 +49,7 @@ for that `Request` is set to `cors`. However, for requests created other than by the {{domxref("Request.Request", "Request()")}} constructor, `no-cors` is typically used as the mode; for example, for embedded resources where the request is initiated from markup, unless the -[`crossorigin`](/en-US/docs/Web/HTML/Attributes/crossorigin) +[`crossorigin`](/en-US/docs/Web/HTML/Reference/Attributes/crossorigin) attribute is present, the request is in most cases made using the `no-cors` mode — that is, for the {{HTMLElement("link")}} or {{HTMLElement("script")}} elements (except when used with modules), or {{HTMLElement("img")}}, {{HTMLElement("audio")}}, @@ -78,5 +78,5 @@ const myMode = myRequest.mode; // returns "cors" by default ## See also - [ServiceWorker API](/en-US/docs/Web/API/Service_Worker_API) -- [HTTP access control (CORS)](/en-US/docs/Web/HTTP/CORS) +- [HTTP access control (CORS)](/en-US/docs/Web/HTTP/Guides/CORS) - [HTTP](/en-US/docs/Web/HTTP) diff --git a/files/en-us/web/api/request/redirect/index.md b/files/en-us/web/api/request/redirect/index.md index b6940276decf491..bf902927948c811 100644 --- a/files/en-us/web/api/request/redirect/index.md +++ b/files/en-us/web/api/request/redirect/index.md @@ -40,5 +40,5 @@ const myCred = myRequest.redirect; ## See also - [ServiceWorker API](/en-US/docs/Web/API/Service_Worker_API) -- [HTTP access control (CORS)](/en-US/docs/Web/HTTP/CORS) +- [HTTP access control (CORS)](/en-US/docs/Web/HTTP/Guides/CORS) - [HTTP](/en-US/docs/Web/HTTP) diff --git a/files/en-us/web/api/request/referrer/index.md b/files/en-us/web/api/request/referrer/index.md index 2706e1062d6c607..4720ca37079c4f2 100644 --- a/files/en-us/web/api/request/referrer/index.md +++ b/files/en-us/web/api/request/referrer/index.md @@ -42,5 +42,5 @@ const myReferrer = myRequest.referrer; // returns "about:client" by default ## See also - [ServiceWorker API](/en-US/docs/Web/API/Service_Worker_API) -- [HTTP access control (CORS)](/en-US/docs/Web/HTTP/CORS) +- [HTTP access control (CORS)](/en-US/docs/Web/HTTP/Guides/CORS) - [HTTP](/en-US/docs/Web/HTTP) diff --git a/files/en-us/web/api/request/referrerpolicy/index.md b/files/en-us/web/api/request/referrerpolicy/index.md index 6db339e99b76ba7..956d3787bebdc23 100644 --- a/files/en-us/web/api/request/referrerpolicy/index.md +++ b/files/en-us/web/api/request/referrerpolicy/index.md @@ -41,5 +41,5 @@ const myReferrer = myRequest.referrerPolicy; // returns "" by default ## See also - [ServiceWorker API](/en-US/docs/Web/API/Service_Worker_API) -- [HTTP access control (CORS)](/en-US/docs/Web/HTTP/CORS) +- [HTTP access control (CORS)](/en-US/docs/Web/HTTP/Guides/CORS) - [HTTP](/en-US/docs/Web/HTTP) diff --git a/files/en-us/web/api/request/request/index.md b/files/en-us/web/api/request/request/index.md index b7a8db18b71e9bc..699659a8bf5bfbe 100644 --- a/files/en-us/web/api/request/request/index.md +++ b/files/en-us/web/api/request/request/index.md @@ -92,7 +92,7 @@ const options = { const req = new Request("flowers.jpg", options); fetch(req).then((response) => { - // ... + // … }); ``` @@ -100,7 +100,7 @@ Note that you could also pass `options` into the `fetch` call to get the same ef ```js fetch(req, options).then((response) => { - // ... + // … }); ``` @@ -138,5 +138,5 @@ const copy = new Request(req); ## See also - [ServiceWorker API](/en-US/docs/Web/API/Service_Worker_API) -- [HTTP access control (CORS)](/en-US/docs/Web/HTTP/CORS) +- [HTTP access control (CORS)](/en-US/docs/Web/HTTP/Guides/CORS) - [HTTP](/en-US/docs/Web/HTTP) diff --git a/files/en-us/web/api/request/url/index.md b/files/en-us/web/api/request/url/index.md index 8f44a6492d9f43a..7d58eddf48f3c66 100644 --- a/files/en-us/web/api/request/url/index.md +++ b/files/en-us/web/api/request/url/index.md @@ -37,5 +37,5 @@ const myURL = myRequest.url; // "https://github.com/mdn/dom-examples/tree/main/f ## See also - [ServiceWorker API](/en-US/docs/Web/API/Service_Worker_API) -- [HTTP access control (CORS)](/en-US/docs/Web/HTTP/CORS) +- [HTTP access control (CORS)](/en-US/docs/Web/HTTP/Guides/CORS) - [HTTP](/en-US/docs/Web/HTTP) diff --git a/files/en-us/web/api/requestinit/index.md b/files/en-us/web/api/requestinit/index.md index e8c90ef855fd42e..73267ad8c0a9060 100644 --- a/files/en-us/web/api/requestinit/index.md +++ b/files/en-us/web/api/requestinit/index.md @@ -56,8 +56,8 @@ You can also construct a `Request` with a `RequestInit`, and pass the `Request` - : The browser looks in its HTTP cache for a response matching the request. - - If there is a match and it is [fresh](/en-US/docs/Web/HTTP/Caching#fresh_and_stale_based_on_age), it will be returned from the cache. - - If there is a match but it is [stale](/en-US/docs/Web/HTTP/Caching#fresh_and_stale_based_on_age), the browser will make a [conditional request](/en-US/docs/Web/HTTP/Conditional_requests) to the remote server. If the server indicates that the resource has not changed, it will be returned from the cache. Otherwise the resource will be downloaded from the server and the cache will be updated. + - If there is a match and it is [fresh](/en-US/docs/Web/HTTP/Guides/Caching#fresh_and_stale_based_on_age), it will be returned from the cache. + - If there is a match but it is [stale](/en-US/docs/Web/HTTP/Guides/Caching#fresh_and_stale_based_on_age), the browser will make a [conditional request](/en-US/docs/Web/HTTP/Guides/Conditional_requests) to the remote server. If the server indicates that the resource has not changed, it will be returned from the cache. Otherwise the resource will be downloaded from the server and the cache will be updated. - If there is no match, the browser will make a normal request, and will update the cache with the downloaded resource. - `no-store` @@ -68,7 +68,7 @@ You can also construct a `Request` with a `RequestInit`, and pass the `Request` - : The browser looks in its HTTP cache for a response matching the request. - - If there is a match, _fresh or stale,_ the browser will make a [conditional request](/en-US/docs/Web/HTTP/Conditional_requests) to the remote server. If the server indicates that the resource has not changed, it will be returned from the cache. Otherwise the resource will be downloaded from the server and the cache will be updated. + - If there is a match, _fresh or stale,_ the browser will make a [conditional request](/en-US/docs/Web/HTTP/Guides/Conditional_requests) to the remote server. If the server indicates that the resource has not changed, it will be returned from the cache. Otherwise the resource will be downloaded from the server and the cache will be updated. - If there is no match, the browser will make a normal request, and will update the cache with the downloaded resource. - `force-cache` @@ -109,7 +109,7 @@ You can also construct a `Request` with a `RequestInit`, and pass the `Request` - : Any headers you want to add to your request, contained within a {{domxref("Headers")}} object or an object literal whose keys are the names of headers and whose values are the header values. - Many headers are set automatically by the browser and can't be set by a script: these are called {{glossary("Forbidden request headers", "Forbidden request headers")}}. + Many headers are set automatically by the browser and can't be set by a script: these are called {{glossary("Forbidden request header", "Forbidden request headers")}}. If the `mode` option is set to `no-cors`, you can only set {{glossary("CORS-safelisted request header", "CORS-safelisted request headers")}}. @@ -120,7 +120,7 @@ You can also construct a `Request` with a `RequestInit`, and pass the `Request` - : Contains the [subresource integrity](/en-US/docs/Web/Security/Subresource_Integrity) value of the request. - This will be checked when the resource is fetched, just as it would be when the [`integrity`](/en-US/docs/Web/HTML/Element/script#integrity) attribute is set on a {{htmlelement("script")}} element. The browser will compute the {{glossary("Cryptographic_hash_function", "hash")}} of the fetched resource using the specified algorithm, and if the result does not match the value specified, the browser will reject the fetch request with a network error. + This will be checked when the resource is fetched, just as it would be when the [`integrity`](/en-US/docs/Web/HTML/Reference/Elements/script#integrity) attribute is set on a {{htmlelement("script")}} element. The browser will compute the {{glossary("hash function", "hash")}} of the fetched resource using the specified algorithm, and if the result does not match the value specified, the browser will reject the fetch request with a network error. The format of this option is `<hash-algo>-<hash-source>` where: @@ -136,7 +136,7 @@ You can also construct a `Request` with a `RequestInit`, and pass the `Request` This enables a {{domxref('Window.fetch','fetch()')}} request to send analytics at the end of a session even if the user navigates away from or closes the page. This has some advantages over using {{domxref("Navigator.sendBeacon()")}} for the same purpose. - For example, you can use HTTP methods other than [`POST`](/en-US/docs/Web/HTTP/Methods/POST), customize request properties, and access the server response via the fetch {{jsxref("Promise")}} fulfillment. + For example, you can use HTTP methods other than [`POST`](/en-US/docs/Web/HTTP/Reference/Methods/POST), customize request properties, and access the server response via the fetch {{jsxref("Promise")}} fulfillment. It is also available in [service workers](/en-US/docs/Web/API/Service_Worker_API). The body size for `keepalive` requests is limited to 64 kibibytes. @@ -145,7 +145,7 @@ You can also construct a `Request` with a `RequestInit`, and pass the `Request` - `method` {{optional_inline}} - - : The [request method](/en-US/docs/Web/HTTP/Methods). + - : The [request method](/en-US/docs/Web/HTTP/Reference/Methods). Defaults to {{httpmethod("GET")}}. @@ -159,7 +159,7 @@ You can also construct a `Request` with a `RequestInit`, and pass the `Request` - `cors` - - : If the request is cross-origin then it will use the [Cross-Origin Resource Sharing (CORS)](/en-US/docs/Web/HTTP/CORS) mechanism. Only {{glossary("CORS-safelisted response header", "CORS-safelisted response headers")}} are exposed in the response. + - : If the request is cross-origin then it will use the [Cross-Origin Resource Sharing (CORS)](/en-US/docs/Web/HTTP/Guides/CORS) mechanism. Only {{glossary("CORS-safelisted response header", "CORS-safelisted response headers")}} are exposed in the response. - `no-cors` @@ -194,7 +194,7 @@ You can also construct a `Request` with a `RequestInit`, and pass the `Request` - `redirect` {{optional_inline}} - - : Determines the browser's behavior in case the server replies with a [redirect status](/en-US/docs/Web/HTTP/Status#redirection_messages). One of the following values: + - : Determines the browser's behavior in case the server replies with a [redirect status](/en-US/docs/Web/HTTP/Reference/Status#redirection_messages). One of the following values: - `follow` - : Automatically follow redirects. @@ -301,5 +301,5 @@ In this case the request will be sent with the following options: - [Using Fetch](/en-US/docs/Web/API/Fetch_API/Using_Fetch) - [ServiceWorker API](/en-US/docs/Web/API/Service_Worker_API) -- [HTTP access control (CORS)](/en-US/docs/Web/HTTP/CORS) +- [HTTP access control (CORS)](/en-US/docs/Web/HTTP/Guides/CORS) - [HTTP](/en-US/docs/Web/HTTP) diff --git a/files/en-us/web/api/resize_observer_api/index.md b/files/en-us/web/api/resize_observer_api/index.md index 54c62963076b4ba..9afe894d22ae264 100644 --- a/files/en-us/web/api/resize_observer_api/index.md +++ b/files/en-us/web/api/resize_observer_api/index.md @@ -15,7 +15,7 @@ There are a whole raft of use cases for responsive design techniques (and others For example, [media queries](/en-US/docs/Web/CSS/CSS_media_queries) / {{domxref("window.matchMedia")}} are great for updating layouts at specific points when the viewport changes sizes, but what if you want to change layout in response to a specific element's size changing, which isn't the outer container? -To achieve this, a limited solution would be to listen to changes to a suitable event that hints at the element you are interested in changing size (e.g. the window [resize event](/en-US/docs/Web/API/Window/resize_event)), then figure out what the new dimensions or other features of the element after a resize using {{domxref("Element.getBoundingClientRect")}} or {{domxref("Window.getComputedStyle")}}, for example. +To achieve this, a limited solution would be to listen to changes to a suitable event that hints at the element you are interested in changing size (e.g., the window [resize event](/en-US/docs/Web/API/Window/resize_event)), then figure out what the new dimensions or other features of the element after a resize using {{domxref("Element.getBoundingClientRect")}} or {{domxref("Window.getComputedStyle")}}, for example. Such a solution tends to only work for limited use cases, be bad for performance (continually calling the above methods would result in a big performance hit), and often won't work when the browser window size is not changed. diff --git a/files/en-us/web/api/resizeobserver/index.md b/files/en-us/web/api/resizeobserver/index.md index bab822ffaef0a4c..176cbdb8456a393 100644 --- a/files/en-us/web/api/resizeobserver/index.md +++ b/files/en-us/web/api/resizeobserver/index.md @@ -99,7 +99,7 @@ const divElem = document.querySelector("body > div"); const resizeObserver = new ResizeObserver((entries) => { for (const entry of entries) { - entry.target.style.width = entry.contentBoxSize[0].inlineSize + 10 + "px"; + entry.target.style.width = `${entry.contentBoxSize[0].inlineSize + 10}px`; } }); @@ -120,7 +120,7 @@ const divElem = document.querySelector("body > div"); const resizeObserver = new ResizeObserver((entries) => { requestAnimationFrame(() => { for (const entry of entries) { - entry.target.style.width = entry.contentBoxSize[0].inlineSize + 10 + "px"; + entry.target.style.width = `${entry.contentBoxSize[0].inlineSize + 10}px`; } }); }); diff --git a/files/en-us/web/api/resizeobserverentry/contentboxsize/index.md b/files/en-us/web/api/resizeobserverentry/contentboxsize/index.md index 0aa033bbc4d964f..f53fd4d976208b3 100644 --- a/files/en-us/web/api/resizeobserverentry/contentboxsize/index.md +++ b/files/en-us/web/api/resizeobserverentry/contentboxsize/index.md @@ -42,31 +42,28 @@ size. ```js const resizeObserver = new ResizeObserver((entries) => { - for (let entry of entries) { + for (const entry of entries) { if (entry.contentBoxSize) { // The standard makes contentBoxSize an array... if (entry.contentBoxSize[0]) { - entry.target.style.borderRadius = - Math.min( - 100, - entry.contentBoxSize[0].inlineSize / 10 + - entry.contentBoxSize[0].blockSize / 10, - ) + "px"; + entry.target.style.borderRadius = `${Math.min( + 100, + entry.contentBoxSize[0].inlineSize / 10 + + entry.contentBoxSize[0].blockSize / 10, + )}px`; } else { - // ...but old versions of Firefox treat it as a single item - entry.target.style.borderRadius = - Math.min( - 100, - entry.contentBoxSize.inlineSize / 10 + - entry.contentBoxSize.blockSize / 10, - ) + "px"; + // … but old versions of Firefox treat it as a single item + entry.target.style.borderRadius = `${Math.min( + 100, + entry.contentBoxSize.inlineSize / 10 + + entry.contentBoxSize.blockSize / 10, + )}px`; } } else { - entry.target.style.borderRadius = - Math.min( - 100, - entry.contentRect.width / 10 + entry.contentRect.height / 10, - ) + "px"; + entry.target.style.borderRadius = `${Math.min( + 100, + entry.contentRect.width / 10 + entry.contentRect.height / 10, + )}px`; } } }); diff --git a/files/en-us/web/api/resizeobserverentry/index.md b/files/en-us/web/api/resizeobserverentry/index.md index b2dac65379d9fed..31eeb845abe299c 100644 --- a/files/en-us/web/api/resizeobserverentry/index.md +++ b/files/en-us/web/api/resizeobserverentry/index.md @@ -41,25 +41,20 @@ Note that the code covers three different compatibility cases: ```js const resizeObserver = new ResizeObserver((entries) => { - for (let entry of entries) { + for (const entry of entries) { if (entry.contentBoxSize) { // The standard makes contentBoxSize an array... if (entry.contentBoxSize[0]) { - h1Elem.style.fontSize = - Math.max(1.5, entry.contentBoxSize[0].inlineSize / 200) + "rem"; - pElem.style.fontSize = - Math.max(1, entry.contentBoxSize[0].inlineSize / 600) + "rem"; + h1Elem.style.fontSize = `${Math.max(1.5, entry.contentBoxSize[0].inlineSize / 200)}rem`; + pElem.style.fontSize = `${Math.max(1, entry.contentBoxSize[0].inlineSize / 600)}rem`; } else { - // ...but old versions of Firefox treat it as a single item - h1Elem.style.fontSize = - Math.max(1.5, entry.contentBoxSize.inlineSize / 200) + "rem"; - pElem.style.fontSize = - Math.max(1, entry.contentBoxSize.inlineSize / 600) + "rem"; + // … but old versions of Firefox treat it as a single item + h1Elem.style.fontSize = `${Math.max(1.5, entry.contentBoxSize.inlineSize / 200)}rem`; + pElem.style.fontSize = `${Math.max(1, entry.contentBoxSize.inlineSize / 600)}rem`; } } else { - h1Elem.style.fontSize = - Math.max(1.5, entry.contentRect.width / 200) + "rem"; - pElem.style.fontSize = Math.max(1, entry.contentRect.width / 600) + "rem"; + h1Elem.style.fontSize = `${Math.max(1.5, entry.contentRect.width / 200)}rem`; + pElem.style.fontSize = `${Math.max(1, entry.contentRect.width / 600)}rem`; } } console.log("Size changed"); diff --git a/files/en-us/web/api/response/arraybuffer/index.md b/files/en-us/web/api/response/arraybuffer/index.md index 72d208b4b448153..d1bff7c637fcdd7 100644 --- a/files/en-us/web/api/response/arraybuffer/index.md +++ b/files/en-us/web/api/response/arraybuffer/index.md @@ -121,5 +121,5 @@ function readFile(file) { ## See also - [ServiceWorker API](/en-US/docs/Web/API/Service_Worker_API) -- [HTTP access control (CORS)](/en-US/docs/Web/HTTP/CORS) +- [HTTP access control (CORS)](/en-US/docs/Web/HTTP/Guides/CORS) - [HTTP](/en-US/docs/Web/HTTP) diff --git a/files/en-us/web/api/response/blob/index.md b/files/en-us/web/api/response/blob/index.md index 71a930f20532093..7a4529833459252 100644 --- a/files/en-us/web/api/response/blob/index.md +++ b/files/en-us/web/api/response/blob/index.md @@ -75,5 +75,5 @@ fetch(myRequest) ## See also - [ServiceWorker API](/en-US/docs/Web/API/Service_Worker_API) -- [HTTP access control (CORS)](/en-US/docs/Web/HTTP/CORS) +- [HTTP access control (CORS)](/en-US/docs/Web/HTTP/Guides/CORS) - [HTTP](/en-US/docs/Web/HTTP) diff --git a/files/en-us/web/api/response/body/index.md b/files/en-us/web/api/response/body/index.md index 365fb2895605103..3504abc36341810 100644 --- a/files/en-us/web/api/response/body/index.md +++ b/files/en-us/web/api/response/body/index.md @@ -12,12 +12,12 @@ The **`body`** read-only property of the {{domxref("Response")}} interface is a ## Value -A {{domxref("ReadableStream")}}, or else [`null`](/en-US/docs/Web/JavaScript/Reference/Operators/null) for any `Response` object [constructed](/en-US/docs/Web/API/Response/Response) with a null [`body`](/en-US/docs/Web/API/Response/Response#body) property, or for any actual [HTTP response](/en-US/docs/Web/HTTP/Messages#http_responses) that has no [body](/en-US/docs/Web/HTTP/Messages#response_body). +A {{domxref("ReadableStream")}}, or else [`null`](/en-US/docs/Web/JavaScript/Reference/Operators/null) for any `Response` object [constructed](/en-US/docs/Web/API/Response/Response) with a null [`body`](/en-US/docs/Web/API/Response/Response#body) property, or for any actual [HTTP response](/en-US/docs/Web/HTTP/Guides/Messages#http_responses) that has no [body](/en-US/docs/Web/HTTP/Guides/Messages#response_body). The stream is a [readable byte stream](/en-US/docs/Web/API/Streams_API/Using_readable_byte_streams), which supports zero-copy reading using a {{domxref("ReadableStreamBYOBReader")}}. > [!NOTE] -> Current browsers don't actually conform to the spec requirement to set the `body` property to `null` for responses with no body (for example, responses to [`HEAD`](/en-US/docs/Web/HTTP/Methods/HEAD) requests, or [`204 No Content`](/en-US/docs/Web/HTTP/Status/204) responses). +> Current browsers don't actually conform to the spec requirement to set the `body` property to `null` for responses with no body (for example, responses to [`HEAD`](/en-US/docs/Web/HTTP/Reference/Methods/HEAD) requests, or [`204 No Content`](/en-US/docs/Web/HTTP/Reference/Status/204) responses). ## Examples diff --git a/files/en-us/web/api/response/bodyused/index.md b/files/en-us/web/api/response/bodyused/index.md index bdba07490e533c8..9b13ce9e532d044 100644 --- a/files/en-us/web/api/response/bodyused/index.md +++ b/files/en-us/web/api/response/bodyused/index.md @@ -83,5 +83,5 @@ Click "Reset" to reload the example, so you can try again. ## See also - [ServiceWorker API](/en-US/docs/Web/API/Service_Worker_API) -- [HTTP access control (CORS)](/en-US/docs/Web/HTTP/CORS) +- [HTTP access control (CORS)](/en-US/docs/Web/HTTP/Guides/CORS) - [HTTP](/en-US/docs/Web/HTTP) diff --git a/files/en-us/web/api/response/bytes/index.md b/files/en-us/web/api/response/bytes/index.md index d14e5faa377d878..6910db6bf95bfd2 100644 --- a/files/en-us/web/api/response/bytes/index.md +++ b/files/en-us/web/api/response/bytes/index.md @@ -102,7 +102,7 @@ function log(text) { ``` The code first checks if the `bytes()` method is supported. -If the method is supported it adds an event handler for the [`change` event](/en-US/docs/Web/API/HTMLElement/change_event) event on the `<select>` element. +If the method is supported it adds an event handler for the [`change` event](/en-US/docs/Web/API/HTMLElement/change_event) on the `<select>` element. When the value changes, it passes the value of the selection (a URL for an image file) to the `checkSignature()` method defined below. If the method is not supported it logs this information. @@ -128,7 +128,7 @@ The file name and the file type are then logged. ```js async function checkSignature(url) { - if (url == "") return; + if (url === "") return; log(`File: ${url}`); const response = await fetch(url); const image = await response.bytes(); @@ -180,5 +180,5 @@ The log should then display the file name, along with the file type that was det ## See also - [ServiceWorker API](/en-US/docs/Web/API/Service_Worker_API) -- [HTTP access control (CORS)](/en-US/docs/Web/HTTP/CORS) +- [HTTP access control (CORS)](/en-US/docs/Web/HTTP/Guides/CORS) - [HTTP](/en-US/docs/Web/HTTP) diff --git a/files/en-us/web/api/response/clone/index.md b/files/en-us/web/api/response/clone/index.md index 95c5cdafe057ed5..584d418789f444f 100644 --- a/files/en-us/web/api/response/clone/index.md +++ b/files/en-us/web/api/response/clone/index.md @@ -81,5 +81,5 @@ fetch(myRequest).then((response) => { ## See also - [ServiceWorker API](/en-US/docs/Web/API/Service_Worker_API) -- [HTTP access control (CORS)](/en-US/docs/Web/HTTP/CORS) +- [HTTP access control (CORS)](/en-US/docs/Web/HTTP/Guides/CORS) - [HTTP](/en-US/docs/Web/HTTP) diff --git a/files/en-us/web/api/response/error_static/index.md b/files/en-us/web/api/response/error_static/index.md index 520c0e8e2ad9e95..30bb1d246196074 100644 --- a/files/en-us/web/api/response/error_static/index.md +++ b/files/en-us/web/api/response/error_static/index.md @@ -73,5 +73,5 @@ try { ## See also - [ServiceWorker API](/en-US/docs/Web/API/Service_Worker_API) -- [HTTP access control (CORS)](/en-US/docs/Web/HTTP/CORS) +- [HTTP access control (CORS)](/en-US/docs/Web/HTTP/Guides/CORS) - [HTTP](/en-US/docs/Web/HTTP) diff --git a/files/en-us/web/api/response/formdata/index.md b/files/en-us/web/api/response/formdata/index.md index 67c0b997cbcc69d..86db62659c99d20 100644 --- a/files/en-us/web/api/response/formdata/index.md +++ b/files/en-us/web/api/response/formdata/index.md @@ -58,5 +58,5 @@ TBD. ## See also - [ServiceWorker API](/en-US/docs/Web/API/Service_Worker_API) -- [HTTP access control (CORS)](/en-US/docs/Web/HTTP/CORS) +- [HTTP access control (CORS)](/en-US/docs/Web/HTTP/Guides/CORS) - [HTTP](/en-US/docs/Web/HTTP) diff --git a/files/en-us/web/api/response/headers/index.md b/files/en-us/web/api/response/headers/index.md index 10ebac24726431a..ad6c989d4d79ca1 100644 --- a/files/en-us/web/api/response/headers/index.md +++ b/files/en-us/web/api/response/headers/index.md @@ -52,5 +52,5 @@ fetch(myRequest) ## See also - [ServiceWorker API](/en-US/docs/Web/API/Service_Worker_API) -- [HTTP access control (CORS)](/en-US/docs/Web/HTTP/CORS) +- [HTTP access control (CORS)](/en-US/docs/Web/HTTP/Guides/CORS) - [HTTP](/en-US/docs/Web/HTTP) diff --git a/files/en-us/web/api/response/index.md b/files/en-us/web/api/response/index.md index 06bcfb4b6769aa2..16030dc1dd3cf29 100644 --- a/files/en-us/web/api/response/index.md +++ b/files/en-us/web/api/response/index.md @@ -121,5 +121,5 @@ getJSON() ## See also - [ServiceWorker API](/en-US/docs/Web/API/Service_Worker_API) -- [HTTP access control (CORS)](/en-US/docs/Web/HTTP/CORS) +- [HTTP access control (CORS)](/en-US/docs/Web/HTTP/Guides/CORS) - [HTTP](/en-US/docs/Web/HTTP) diff --git a/files/en-us/web/api/response/json/index.md b/files/en-us/web/api/response/json/index.md index a910801dc6cc925..b435dfd159c47b3 100644 --- a/files/en-us/web/api/response/json/index.md +++ b/files/en-us/web/api/response/json/index.md @@ -79,5 +79,5 @@ fetch(myRequest) ## See also - [ServiceWorker API](/en-US/docs/Web/API/Service_Worker_API) -- [Cross-Origin Resource Sharing (CORS)](/en-US/docs/Web/HTTP/CORS) +- [Cross-Origin Resource Sharing (CORS)](/en-US/docs/Web/HTTP/Guides/CORS) - [HTTP](/en-US/docs/Web/HTTP) diff --git a/files/en-us/web/api/response/json_static/index.md b/files/en-us/web/api/response/json_static/index.md index eab1c929d5fa7c5..944385b4918990c 100644 --- a/files/en-us/web/api/response/json_static/index.md +++ b/files/en-us/web/api/response/json_static/index.md @@ -37,7 +37,7 @@ Response.json(data, options) - : The status message associated with the status code. For a status of `200` this might be `OK`. - `headers` - - : Any headers you want to add to your response, contained within a {{domxref("Headers")}} object or object literal of {{jsxref("String")}} key/value pairs (see [HTTP headers](/en-US/docs/Web/HTTP/Headers) for a reference). + - : Any headers you want to add to your response, contained within a {{domxref("Headers")}} object or object literal of {{jsxref("String")}} key/value pairs (see [HTTP headers](/en-US/docs/Web/HTTP/Reference/Headers) for a reference). ### Return value diff --git a/files/en-us/web/api/response/ok/index.md b/files/en-us/web/api/response/ok/index.md index 5dea0dbcc8f98bd..6d49e46491160f7 100644 --- a/files/en-us/web/api/response/ok/index.md +++ b/files/en-us/web/api/response/ok/index.md @@ -48,5 +48,5 @@ fetch(myRequest).then((response) => { ## See also - [ServiceWorker API](/en-US/docs/Web/API/Service_Worker_API) -- [HTTP access control (CORS)](/en-US/docs/Web/HTTP/CORS) +- [HTTP access control (CORS)](/en-US/docs/Web/HTTP/Guides/CORS) - [HTTP](/en-US/docs/Web/HTTP) diff --git a/files/en-us/web/api/response/redirect_static/index.md b/files/en-us/web/api/response/redirect_static/index.md index a5f5813fb0a16b2..22216a6b5630280 100644 --- a/files/en-us/web/api/response/redirect_static/index.md +++ b/files/en-us/web/api/response/redirect_static/index.md @@ -57,5 +57,5 @@ Response.redirect("https://www.example.com", 302); ## See also - [ServiceWorker API](/en-US/docs/Web/API/Service_Worker_API) -- [HTTP access control (CORS)](/en-US/docs/Web/HTTP/CORS) +- [HTTP access control (CORS)](/en-US/docs/Web/HTTP/Guides/CORS) - [HTTP](/en-US/docs/Web/HTTP) diff --git a/files/en-us/web/api/response/redirected/index.md b/files/en-us/web/api/response/redirected/index.md index ac760a24fc8cbcd..cf0199ac1daccf5 100644 --- a/files/en-us/web/api/response/redirected/index.md +++ b/files/en-us/web/api/response/redirected/index.md @@ -11,7 +11,7 @@ browser-compat: api.Response.redirected The **`redirected`** read-only property of the {{domxref("Response")}} interface indicates whether or not the response is the result of a request you made which was redirected. > [!NOTE] -> Relying on redirected to filter out redirects makes it easy for a forged redirect to prevent your content from working as expected. +> Checking `redirected` to prevent redirects is not recommended, because by the time a response is received, the redirect has already happened, and you may have sent the request to an unintended destination, potentially sending sensitive information. > Instead, you should do the filtering when you call {{domxref("Window/fetch", "fetch()")}}. > See the example [Disallowing redirects](#disallowing_redirects), which shows this being done. @@ -46,7 +46,7 @@ fetch("awesome-picture.jpg") ### Disallowing redirects -Because using redirected to manually filter out redirects can allow forgery of redirects, you should instead set the redirect mode to `"error"` in the `init` parameter when calling {{domxref("Window/fetch", "fetch()")}}, like this: +Checking `redirected` is a bad way to prevent redirects, because the redirect has already happened. Instead, you should set the redirect mode to `"error"` in the `options` parameter when calling {{domxref("Window/fetch", "fetch()")}}, like this: ```js fetch("awesome-picture.jpg", { redirect: "error" }) @@ -69,5 +69,5 @@ fetch("awesome-picture.jpg", { redirect: "error" }) - [Fetch API](/en-US/docs/Web/API/Fetch_API) - [ServiceWorker API](/en-US/docs/Web/API/Service_Worker_API) -- [HTTP access control (CORS)](/en-US/docs/Web/HTTP/CORS) +- [HTTP access control (CORS)](/en-US/docs/Web/HTTP/Guides/CORS) - [HTTP](/en-US/docs/Web/HTTP) diff --git a/files/en-us/web/api/response/response/index.md b/files/en-us/web/api/response/response/index.md index 9240d905e953a4b..f0cd820831ac052 100644 --- a/files/en-us/web/api/response/response/index.md +++ b/files/en-us/web/api/response/response/index.md @@ -46,7 +46,7 @@ new Response(body, options) - : The status message associated with the status code, such as `"OK"`. The default value is `""`. - `headers` - - : Any headers you want to add to your response, contained within a {{domxref("Headers")}} object or object literal of {{jsxref("String")}} key/value pairs (see [HTTP headers](/en-US/docs/Web/HTTP/Headers) for a reference). + - : Any headers you want to add to your response, contained within a {{domxref("Headers")}} object or object literal of {{jsxref("String")}} key/value pairs (see [HTTP headers](/en-US/docs/Web/HTTP/Reference/Headers) for a reference). By default this is empty. ## Examples @@ -71,5 +71,5 @@ const myResponse = new Response(myBlob, myOptions); ## See also - [ServiceWorker API](/en-US/docs/Web/API/Service_Worker_API) -- [HTTP access control (CORS)](/en-US/docs/Web/HTTP/CORS) +- [HTTP access control (CORS)](/en-US/docs/Web/HTTP/Guides/CORS) - [HTTP](/en-US/docs/Web/HTTP) diff --git a/files/en-us/web/api/response/status/index.md b/files/en-us/web/api/response/status/index.md index e9e689bc951e356..073fcf82f507784 100644 --- a/files/en-us/web/api/response/status/index.md +++ b/files/en-us/web/api/response/status/index.md @@ -8,14 +8,14 @@ browser-compat: api.Response.status {{APIRef("Fetch API")}}{{AvailableInWorkers}} -The **`status`** read-only property of the {{domxref("Response")}} interface contains the [HTTP status codes](/en-US/docs/Web/HTTP/Status) of the response. +The **`status`** read-only property of the {{domxref("Response")}} interface contains the [HTTP status codes](/en-US/docs/Web/HTTP/Reference/Status) of the response. For example, `200` for success, `404` if the resource could not be found. ## Value An unsigned short number. -This is one of the [HTTP response status codes](/en-US/docs/Web/HTTP/Status). +This is one of the [HTTP response status codes](/en-US/docs/Web/HTTP/Reference/Status). ## Examples @@ -52,5 +52,5 @@ fetch(myRequest) ## See also - [ServiceWorker API](/en-US/docs/Web/API/Service_Worker_API) -- [HTTP access control (CORS)](/en-US/docs/Web/HTTP/CORS) +- [HTTP access control (CORS)](/en-US/docs/Web/HTTP/Guides/CORS) - [HTTP](/en-US/docs/Web/HTTP) diff --git a/files/en-us/web/api/response/statustext/index.md b/files/en-us/web/api/response/statustext/index.md index 1572ccdd3baabfd..41d950dfc162e61 100644 --- a/files/en-us/web/api/response/statustext/index.md +++ b/files/en-us/web/api/response/statustext/index.md @@ -17,7 +17,7 @@ For example, this would be `OK` for a status code `200`, `Continue` for `100`, ` A {{jsxref("String")}} containing the HTTP status message associated with the response. The default value is "". -See [HTTP response status codes](/en-US/docs/Web/HTTP/Status) for a list of codes and their associated status messages. +See [HTTP response status codes](/en-US/docs/Web/HTTP/Reference/Status) for a list of codes and their associated status messages. Note that HTTP/2 [does not support](https://fetch.spec.whatwg.org/#concept-response-status-message) status messages. ## Examples @@ -54,5 +54,5 @@ fetch(myRequest) ## See also - [ServiceWorker API](/en-US/docs/Web/API/Service_Worker_API) -- [HTTP access control (CORS)](/en-US/docs/Web/HTTP/CORS) +- [HTTP access control (CORS)](/en-US/docs/Web/HTTP/Guides/CORS) - [HTTP](/en-US/docs/Web/HTTP) diff --git a/files/en-us/web/api/response/text/index.md b/files/en-us/web/api/response/text/index.md index bcd31d2c7c7f360..01de864ec8d6571 100644 --- a/files/en-us/web/api/response/text/index.md +++ b/files/en-us/web/api/response/text/index.md @@ -77,5 +77,5 @@ function getData(pageId) { ## See also - [ServiceWorker API](/en-US/docs/Web/API/Service_Worker_API) -- [HTTP access control (CORS)](/en-US/docs/Web/HTTP/CORS) +- [HTTP access control (CORS)](/en-US/docs/Web/HTTP/Guides/CORS) - [HTTP](/en-US/docs/Web/HTTP) diff --git a/files/en-us/web/api/response/type/index.md b/files/en-us/web/api/response/type/index.md index e0345e26b5f2b77..af208fadc60403c 100644 --- a/files/en-us/web/api/response/type/index.md +++ b/files/en-us/web/api/response/type/index.md @@ -8,48 +8,81 @@ browser-compat: api.Response.type {{APIRef("Fetch API")}}{{AvailableInWorkers}} -The **`type`** read-only property of the {{domxref("Response")}} interface contains the type of the response. -It can be one of the following: - -- `basic`: Normal, same origin response, with all headers exposed except "Set-Cookie". -- `cors`: Response was received from a valid cross-origin request. [Certain headers and the body](https://fetch.spec.whatwg.org/#concept-filtered-response-cors) may be accessed. -- `error`: Network error. - No useful information describing the error is available. - The Response's status is 0, headers are empty and immutable. - This is the type for a Response obtained from `Response.error()`. -- `opaque`: Response for "no-cors" request to cross-origin resource. - [Severely restricted](https://fetch.spec.whatwg.org/#concept-filtered-response-opaque). -- `opaqueredirect`: The fetch request was made with `redirect: "manual"`. - The Response's status is 0, headers are empty, body is null and trailer is empty. - -> [!NOTE] -> An "error" Response never really gets exposed to script: such a response to a {{domxref("Window/fetch", "fetch()")}} would reject the promise. +The **`type`** read-only property of the {{domxref("Response")}} interface contains the type of the response. The type determines whether scripts are able to access the response body and headers. ## Value -A `ResponseType` string indicating the type of the response. +A string, which may be any of the following values: + +- `basic` + + - : This applies in any of the following cases: + + - The request is same-origin. + - The requested URL's scheme is [`data:`](/en-US/docs/Web/URI/Reference/Schemes/data). + - The request's {{domxref("Request.mode", "mode")}} is `navigate` or `websocket`. + + With this type, all response headers are exposed except {{httpheader("Set-Cookie")}}. + +- `cors` + - : The request was cross-origin and was successfully processed using [CORS](/en-US/docs/Web/HTTP/Guides/CORS). With this type, only {{glossary("CORS-safelisted response header", "CORS-safelisted response headers")}} are exposed. +- `error` + + - : A network error occurred. The {{domxref("Response.status", "status")}} property is set to `0`, {{domxref("Response.body", "body")}} is `null`, headers are empty and immutable. + + This is the type of response returned by {{domxref("Response.error_static", "Response.error()")}}. A response of this type is not returned by a call to {{domxref("Window.fetch", "fetch()")}}, because if a network error occurs, the promise is rejected. + +- `opaque` + - : A response to a cross-origin request whose {{domxref("Request.mode", "mode")}} was set to `no-cors`. The {{domxref("Response.status", "status")}} property is set to `0`, {{domxref("Response.body", "body")}} is `null`, headers are empty and immutable. +- `opaqueredirect` + - : A response to a request whose {{domxref("Request.redirect", "redirect")}} option was set to `manual`, and which was redirected by the server. The {{domxref("Response.status", "status")}} property is set to `0`, {{domxref("Response.body", "body")}} is `null`, headers are empty and immutable. ## Examples -In our [Fetch Response example](https://github.com/mdn/dom-examples/tree/main/fetch/fetch-response) (see [Fetch Response live](https://mdn.github.io/dom-examples/fetch/fetch-response/)) we create a new {{domxref("Request")}} object using the {{domxref("Request.Request","Request()")}} constructor, passing it a JPG path. -We then fetch this request using {{domxref("Window/fetch", "fetch()")}}, extract a blob from the response using {{domxref("Response.blob")}}, create an object URL out of it using {{domxref("URL.createObjectURL_static", "URL.createObjectURL()")}}, and display this in an {{htmlelement("img")}}. +### A basic response + +The following same-origin request will return a `basic` response: + +```js +const response = await fetch("flowers.jpg"); + +console.log(response.type); // "basic" +``` + +### A CORS response -Note that at the top of the `fetch()` block we log the response `type` to the console. +Assuming `https://example.org` is not the requester's origin, and that the server responds with the appropriate CORS headers, this request will return a `cors` response: ```js -const myImage = document.querySelector("img"); - -const myRequest = new Request("flowers.jpg"); - -fetch(myRequest) - .then((response) => { - console.log("response.type =", response.type); // response.type = 'basic' - return response.blob(); - }) - .then((myBlob) => { - const objectURL = URL.createObjectURL(myBlob); - myImage.src = objectURL; - }); +const response = await fetch("https://example.org/flowers.jpg"); + +console.log(response.type); // "cors" +``` + +### An opaque response + +The following request is made with the [`no-cors`](/en-US/docs/Web/API/Request/mode#no-cors) option, so it returns an `opaque` response: + +```js +const response = await fetch("https://example.org/flowers.jpg", { + mode: "no-cors", +}); + +console.log(response.type); // "opaque" +console.log(response.body); // null +console.log(response.status); // 0 +``` + +### An error response + +The following code uses {{domxref("Response.error_static", "Response.error()")}} to create an `error` response: + +```js +const response = Response.error(); + +console.log(response.type); // "error" +console.log(response.body); // null +console.log(response.status); // 0 ``` ## Specifications @@ -63,5 +96,5 @@ fetch(myRequest) ## See also - [ServiceWorker API](/en-US/docs/Web/API/Service_Worker_API) -- [HTTP access control (CORS)](/en-US/docs/Web/HTTP/CORS) +- [HTTP access control (CORS)](/en-US/docs/Web/HTTP/Guides/CORS) - [HTTP](/en-US/docs/Web/HTTP) diff --git a/files/en-us/web/api/response/url/index.md b/files/en-us/web/api/response/url/index.md index a36f28afea395b0..664c5201b4309e6 100644 --- a/files/en-us/web/api/response/url/index.md +++ b/files/en-us/web/api/response/url/index.md @@ -49,5 +49,5 @@ fetch(myRequest) ## See also - [ServiceWorker API](/en-US/docs/Web/API/Service_Worker_API) -- [HTTP access control (CORS)](/en-US/docs/Web/HTTP/CORS) +- [HTTP access control (CORS)](/en-US/docs/Web/HTTP/Guides/CORS) - [HTTP](/en-US/docs/Web/HTTP) diff --git a/files/en-us/web/api/restrictiontarget/fromelement_static/index.md b/files/en-us/web/api/restrictiontarget/fromelement_static/index.md index 9d574d12b3f1ea7..53d2bae2760f78e 100644 --- a/files/en-us/web/api/restrictiontarget/fromelement_static/index.md +++ b/files/en-us/web/api/restrictiontarget/fromelement_static/index.md @@ -24,7 +24,7 @@ RestrictionTarget.fromElement(element) - : A reference to an {{domxref("Element")}} that you want to use as a restriction target. For an element to be used as a restriction target, it must: - - Form a [stacking context](/en-US/docs/Web/CSS/CSS_positioned_layout/Understanding_z-index/Stacking_context). + - Form a [stacking context](/en-US/docs/Web/CSS/CSS_positioned_layout/Stacking_context). - Be flattened in 3D space (for example, it is not subjected to any 3D [transforms](/en-US/docs/Web/CSS/CSS_transforms)). - Be rendered (for example, not be off-screen or hidden via `display: none`). - Contain only one box fragment (for example, not be broken across multiple lines). diff --git a/files/en-us/web/api/rtcaudiosourcestats/index.md b/files/en-us/web/api/rtcaudiosourcestats/index.md index 49bf8f148896f10..1c25b22c0afdd73 100644 --- a/files/en-us/web/api/rtcaudiosourcestats/index.md +++ b/files/en-us/web/api/rtcaudiosourcestats/index.md @@ -10,7 +10,7 @@ spec-urls: https://w3c.github.io/webrtc-stats/#dom-rtcaudiosourcestats The **`RTCAudioSourceStats`** dictionary of the [WebRTC API](/en-US/docs/Web/API/WebRTC_API) provides statistics information about an audio track ({{domxref("MediaStreamTrack")}}) that is attached to one or more senders ({{domxref("RTCRtpSender")}}). -These statistics can be obtained by iterating the {{domxref("RTCStatsReport")}} returned by {{domxref("RTCRtpSender.getStats()")}} or {{domxref("RTCPeerConnection.getStats()")}} until you find a report with the [`type`](#type) of `media-source` and a [`kind`](#kind) of `audio`. +These statistics can be obtained by iterating the {{domxref("RTCStatsReport")}} returned by {{domxref("RTCRtpSender.getStats()")}} or {{domxref("RTCPeerConnection.getStats()")}} until you find a report with the [`type`](/en-US/docs/Web/API/RTCAudioSourceStats/type) of `media-source` and a [`kind`](/en-US/docs/Web/API/RTCAudioSourceStats/kind) of `audio`. > [!NOTE] > For audio information about remotely sourced tracks (that are being received), see {{domxref("RTCInboundRtpStreamStats")}}. diff --git a/files/en-us/web/api/rtccertificate/getfingerprints/index.md b/files/en-us/web/api/rtccertificate/getfingerprints/index.md index 0bd53d1a5e5b311..caaa70c74704edd 100644 --- a/files/en-us/web/api/rtccertificate/getfingerprints/index.md +++ b/files/en-us/web/api/rtccertificate/getfingerprints/index.md @@ -10,8 +10,7 @@ browser-compat: api.RTCCertificate.getFingerprints The **`getFingerprints()`** method of the **{{domxref("RTCCertificate")}}** interface is used to get an array of certificate fingerprints. -An application can use this method to compare the client certificate fingerprints with the certificate fingerprints from the server. -The server and client may support different sets of algorithms: all fingerprint values for the set of algorithms supported by both client and server should match. +This can be used in application-level code to get certificate fingerprints, which are {{glossary("hash function","hashes")}} of the certificate created using the various algorithms supported by the browser. ## Syntax @@ -35,26 +34,56 @@ Each fingerprint is represented by an object with the following properties: - : A string containing the certificate fingerprint in lowercase hex string, as calculated with the `algorithm` hash function. The format is more precisely defined in [RFC4572, Section 5](https://www.rfc-editor.org/rfc/rfc4572#section-5). +## Description + +The {{domxref("RTCCertificate")}} instances used for a particular {{DOMxRef("RTCPeerConnection")}} can created using the {{DOMxRef("RTCPeerConnection.generateCertificate_static", "RTCPeerConnection.generateCertificate()")}} static method or fetched from storage in an [IndexedDB](/en-US/docs/Web/API/IndexedDB_API), and set in the constructor. +If no certificates are passed in the constructor they will be created automatically, in which case the certificates used can be fetched with {{DOMxRef("RTCPeerConnection.getConfiguration()")}}. + +Browsers will automatically exchange certificates and fingerprints associated with each {{DOMxRef("RTCPeerConnection")}} during the SDP offer phase, and these will be used as part of the DTLS handshake to verify that the remote party matches the certificate/endpoint send in the SDP. +This provides a low level validation that the WebRTC communication is being set up with the remote party that initiated the offer, but does not, for example, provide any validation of the identity of the communicating users. + +In some cases it can be useful for the application layer to share certificate fingerprints out-of-band: + +- If a trust relationship has been established between two web-browsers it can be persisted by storing the certificates and reusing them in a later session (up to a year later). + The trusted certificates are identified by their fingerprints. +- Peers than want to identify a particular user can send fingerprints and validate the associated user "out of band" (i.e., outside of the browser-mediated WebRTC communications flow). + The application can use the fingerprint to identify later sessions with the specific user. +- In some conferencing server ("middlebox") implementations, the server may need to known the fingerprints before doing any offer/answer. + +Peers may support different sets of algorithms. +When comparing certificates, all fingerprint values for the set of algorithms supported by peers should match. + ## Examples ### Getting certificate fingerprints -This example shows how you might get certificate fingerprints and compare them to fingerprints from a server. +This example shows how you might get certificate fingerprints from the local peer and compare them to fingerprints from the remote peer. -First we create a connection and get the fingerprints. -We also get the fingerprints from the server using "some mechanism". +First we create a connection and get certificates and their fingerprints. +We get the fingerprints from the remote peer using "some out of band mechanism". ```js +// Get the certificate fingerprints from the local peer. const rtcPeerConnection = new RTCPeerConnection(); +const configuration = rtcPeerConnection.getConfiguration(); +const certificates = configuration.certificates; +let fingerprintsFromClient; + +if (certificates && certificates.length > 0) { + certificates.forEach((cert) => { + // For purpose of demonstration, just get first certificate + fingerprintsFromClient = cert.getFingerprints(); + break; + }); +} -// Get the certificate fingerprints from the client. -const fingerprintsFromClient = rtcPeerConnection.certificate.getFingerprints(); - -// Get the certificate fingerprints from the server (pseudo code) -const fingerprintsFromServer = ...; +// Get the certificate fingerprints from the remote peer for particular certificate (pseudo code) +const fingerprintsFromServer = [ + /* … */ +]; ``` -There are numerous ways to compare the fingerprint arrays. +There are numerous ways to compare the fingerprint arrays for a particular certificate. Here we convert the arrays to dictionary objects where the algorithm name is the property and then compare them. This works because only one fingerprint value can exist for each algorithm. (There are many other ways to sort and compare the two arrays). @@ -71,7 +100,7 @@ let serverFingerprintDict = Object.fromEntries( // and all common properties match. function compareObjects(obj1, obj2) { const commonProperties = Object.keys(obj1).filter((prop) => - obj2.hasOwnProperty(prop), + Object.hasOwn(obj2, prop), ); // Return false if there are no common properties if (Object.keys(commonProperties).length === 0) return false; diff --git a/files/en-us/web/api/rtccertificatestats/index.md b/files/en-us/web/api/rtccertificatestats/index.md index 76b5712aed4e862..7fe09a346eb60a9 100644 --- a/files/en-us/web/api/rtccertificatestats/index.md +++ b/files/en-us/web/api/rtccertificatestats/index.md @@ -9,14 +9,14 @@ browser-compat: api.RTCStatsReport.type_certificate The **`RTCCertificateStats`** dictionary of the [WebRTC API](/en-US/docs/Web/API/WebRTC_API) is used to report information about a certificate used by an {{domxref("RTCDtlsTransport")}} and its underlying {{domxref("RTCIceTransport")}}. -The report can be obtained by iterating the {{domxref("RTCStatsReport")}} returned by {{domxref("RTCPeerConnection.getStats()")}} until you find an entry with the [`type`](#type) of `certificate`. +The report can be obtained by iterating the {{domxref("RTCStatsReport")}} returned by {{domxref("RTCPeerConnection.getStats()")}} until you find an entry with the [`type`](/en-US/docs/Web/API/RTCCertificateStats/type) of `certificate`. ## Instance properties - {{domxref("RTCCertificateStats.fingerprint", "fingerprint")}} - - : A string containing the certificate fingerprint, which is calculated using the hash function specified in [`fingerprintAlgorithm`](#fingerprintalgorithm). + - : A string containing the certificate fingerprint, which is calculated using the hash function specified in [`fingerprintAlgorithm`](/en-US/docs/Web/API/RTCCertificateStats/fingerprintAlgorithm). - {{domxref("RTCCertificateStats.fingerprintAlgorithm", "fingerprintAlgorithm")}} - - : A string containing the hash function used to compute the certificate [`fingerprint`](#fingerprint), such as "sha-256". + - : A string containing the hash function used to compute the certificate [`fingerprint`](/en-US/docs/Web/API/RTCCertificateStats/fingerprint), such as "sha-256". - {{domxref("RTCCertificateStats.base64Certificate", "base64Certificate")}} - : A string containing the base-64 representation of the DER-encoded certificate. diff --git a/files/en-us/web/api/rtccodecstats/index.md b/files/en-us/web/api/rtccodecstats/index.md index db59ae33795e950..fbf6657465a4615 100644 --- a/files/en-us/web/api/rtccodecstats/index.md +++ b/files/en-us/web/api/rtccodecstats/index.md @@ -9,14 +9,14 @@ browser-compat: api.RTCStatsReport.type_codec The **`RTCCodecStats`** dictionary of the [WebRTC API](/en-US/docs/Web/API/WebRTC_API) provides statistics about a codec used by {{Glossary("RTP")}} streams that are being sent or received by the associated {{domxref("RTCPeerConnection")}} object. -These statistics can be obtained by iterating the {{domxref("RTCStatsReport")}} object returned by {{domxref("RTCPeerConnection.getStats()")}} until you find an entry with the [`type`](#type) of `codec`. +These statistics can be obtained by iterating the {{domxref("RTCStatsReport")}} object returned by {{domxref("RTCPeerConnection.getStats()")}} until you find an entry with the [`type`](/en-US/docs/Web/API/RTCCodecStats/type) of `codec`. The codec statistics can be correlated with the inbound or outbound stream statistics (both local and remote) by matching their `codecId` property to the codec's `id`. -For example, if [`RTCInboundRtpStreamStats.codecId`](/en-US/docs/Web/API/RTCInboundRtpStreamStats#codecid) matches an [`RTCCodecStats.id`](#id) in the same report, then we know that the codec is being used on this peer connection's inbound stream. +For example, if [`RTCInboundRtpStreamStats.codecId`](/en-US/docs/Web/API/RTCInboundRtpStreamStats/codecId) matches an [`RTCCodecStats.id`](/en-US/docs/Web/API/RTCCodecStats/id) in the same report, then we know that the codec is being used on this peer connection's inbound stream. If no stream `codecId` references a codec statistic, then that codec statistic object is deleted — if the codec is used again, the statistics object will be recreated with the same `id`. Codec objects may be referenced by multiple RTP streams in media sections using the same transport. -In fact, user agents are expected to consolidate information into a single "codec" entry per payload type per transport (unless [sdpFmtpLine](#sdpfmtpline) is different when sending or receiving, in which case, different codecs will be needed for encoding and decoding). +In fact, user agents are expected to consolidate information into a single "codec" entry per payload type per transport (unless [sdpFmtpLine](/en-US/docs/Web/API/RTCCodecStats/sdpFmtpLine) is different when sending or receiving, in which case, different codecs will be needed for encoding and decoding). Note that other transports will use their own distinct `RTCCodecStats` objects. ## Instance properties diff --git a/files/en-us/web/api/rtcdatachannel/bufferedamountlow_event/index.md b/files/en-us/web/api/rtcdatachannel/bufferedamountlow_event/index.md index 083d0bd8132f07d..5f832b1dd988b30 100644 --- a/files/en-us/web/api/rtcdatachannel/bufferedamountlow_event/index.md +++ b/files/en-us/web/api/rtcdatachannel/bufferedamountlow_event/index.md @@ -16,10 +16,10 @@ This event is not cancelable and does not bubble. Use the event name in methods like {{domxref("EventTarget.addEventListener", "addEventListener()")}}, or set an event handler property. -```js -addEventListener("bufferedamountlow", (event) => {}); +```js-nolint +addEventListener("bufferedamountlow", (event) => { }) -onbufferedamountlow = (event) => {}; +onbufferedamountlow = (event) => { } ``` ## Event type diff --git a/files/en-us/web/api/rtcdatachannel/close_event/index.md b/files/en-us/web/api/rtcdatachannel/close_event/index.md index dcf41fafc16c09c..9e485380757c646 100644 --- a/files/en-us/web/api/rtcdatachannel/close_event/index.md +++ b/files/en-us/web/api/rtcdatachannel/close_event/index.md @@ -16,10 +16,10 @@ This event is not cancelable and does not bubble. Use the event name in methods like {{domxref("EventTarget.addEventListener", "addEventListener()")}}, or set an event handler property. -```js -addEventListener("close", (event) => {}); +```js-nolint +addEventListener("close", (event) => { }) -onclose = (event) => {}; +onclose = (event) => { } ``` ## Event type diff --git a/files/en-us/web/api/rtcdatachannel/closing_event/index.md b/files/en-us/web/api/rtcdatachannel/closing_event/index.md index ad5ed4eed24c549..16b9205c5c59486 100644 --- a/files/en-us/web/api/rtcdatachannel/closing_event/index.md +++ b/files/en-us/web/api/rtcdatachannel/closing_event/index.md @@ -16,10 +16,10 @@ This event is not cancelable and does not bubble. Use the event name in methods like {{domxref("EventTarget.addEventListener", "addEventListener()")}}, or set an event handler property. -```js -addEventListener("closing", (event) => {}); +```js-nolint +addEventListener("closing", (event) => { }) -onclosing = (event) => {}; +onclosing = (event) => { } ``` ## Event type diff --git a/files/en-us/web/api/rtcdatachannel/error_event/index.md b/files/en-us/web/api/rtcdatachannel/error_event/index.md index 6aa7373a17f1da1..03c120ea719d13e 100644 --- a/files/en-us/web/api/rtcdatachannel/error_event/index.md +++ b/files/en-us/web/api/rtcdatachannel/error_event/index.md @@ -18,10 +18,10 @@ This event is not cancelable and does not bubble. Use the event name in methods like {{domxref("EventTarget.addEventListener", "addEventListener()")}}, or set an event handler property. -```js -addEventListener("error", (event) => {}); +```js-nolint +addEventListener("error", (event) => { }) -onerror = (event) => {}; +onerror = (event) => { } ``` ## Event type diff --git a/files/en-us/web/api/rtcdatachannel/message_event/index.md b/files/en-us/web/api/rtcdatachannel/message_event/index.md index 24091c31e19b289..aa7f3427fb9ae83 100644 --- a/files/en-us/web/api/rtcdatachannel/message_event/index.md +++ b/files/en-us/web/api/rtcdatachannel/message_event/index.md @@ -19,10 +19,10 @@ This event is not cancelable and does not bubble. Use the event name in methods like {{domxref("EventTarget.addEventListener", "addEventListener()")}}, or set an event handler property. -```js -addEventListener("message", (event) => {}); +```js-nolint +addEventListener("message", (event) => { }) -onmessage = (event) => {}; +onmessage = (event) => { } ``` ## Event type @@ -44,7 +44,7 @@ _Also inherits properties from its parent interface, {{domxref("Event")}}._ - {{domxref("MessageEvent.source")}} {{ReadOnlyInline}} - : A reference to the message emitter, one of {{glossary("WindowProxy")}}, {{domxref("MessagePort")}}, or {{domxref("ServiceWorker")}}. - {{domxref("MessageEvent.ports")}} {{ReadOnlyInline}} - - : An array of {{domxref("MessagePort")}} objects representing the ports associated with the channel the message is being sent through (where appropriate, e.g. in channel messaging or when sending a message to a shared worker). + - : An array of {{domxref("MessagePort")}} objects representing the ports associated with the channel the message is being sent through (where appropriate, e.g., in channel messaging or when sending a message to a shared worker). ## Examples diff --git a/files/en-us/web/api/rtcdatachannel/open_event/index.md b/files/en-us/web/api/rtcdatachannel/open_event/index.md index c752c51a0efc00d..e9c1ec0e4a7bf64 100644 --- a/files/en-us/web/api/rtcdatachannel/open_event/index.md +++ b/files/en-us/web/api/rtcdatachannel/open_event/index.md @@ -16,10 +16,10 @@ This event is not cancelable and does not bubble. Use the event name in methods like {{domxref("EventTarget.addEventListener", "addEventListener()")}}, or set an event handler property. -```js -addEventListener("open", (event) => {}); +```js-nolint +addEventListener("open", (event) => { }) -onopen = (event) => {}; +onopen = (event) => { } ``` ## Event type diff --git a/files/en-us/web/api/rtcdatachannelstats/index.md b/files/en-us/web/api/rtcdatachannelstats/index.md index 282776e4ac57316..8377a34763c27c6 100644 --- a/files/en-us/web/api/rtcdatachannelstats/index.md +++ b/files/en-us/web/api/rtcdatachannelstats/index.md @@ -9,9 +9,9 @@ browser-compat: api.RTCStatsReport.type_data-channel The **`RTCDataChannelStats`** dictionary of the [WebRTC API](/en-US/docs/Web/API/WebRTC_API) provides statistics related to one {{domxref("RTCDataChannel")}} object on the connection. -The report can be obtained by iterating the {{domxref("RTCStatsReport")}} returned by {{domxref("RTCPeerConnection.getStats()")}} until you find an entry with the [`type`](#type) of `data-channel`. +The report can be obtained by iterating the {{domxref("RTCStatsReport")}} returned by {{domxref("RTCPeerConnection.getStats()")}} until you find an entry with the [`type`](/en-US/docs/Web/API/RTCDataChannelStats/type) of `data-channel`. -The data channels statistics may be correlated to a particular channel by comparing the [`dataChannelIdentifier`](#datachannelidentifier) property to a matching {{domxref("RTCDataChannel.id")}}. +The data channels statistics may be correlated to a particular channel by comparing the [`dataChannelIdentifier`](/en-US/docs/Web/API/RTCDataChannelStats/dataChannelIdentifier) property to a matching {{domxref("RTCDataChannel.id")}}. ## Instance properties diff --git a/files/en-us/web/api/rtcdtlstransport/error_event/index.md b/files/en-us/web/api/rtcdtlstransport/error_event/index.md index 2f115a91285d15e..cc0dd743aa88db9 100644 --- a/files/en-us/web/api/rtcdtlstransport/error_event/index.md +++ b/files/en-us/web/api/rtcdtlstransport/error_event/index.md @@ -16,10 +16,10 @@ This event is not cancelable and does not bubble. Use the event name in methods like {{domxref("EventTarget.addEventListener", "addEventListener()")}}, or set an event handler property. -```js -addEventListener("error", (event) => {}); +```js-nolint +addEventListener("error", (event) => { }) -onerror = (event) => {}; +onerror = (event) => { } ``` ## Event type diff --git a/files/en-us/web/api/rtcdtlstransport/index.md b/files/en-us/web/api/rtcdtlstransport/index.md index 1afbccd7a6480be..b144d0089dcfb5c 100644 --- a/files/en-us/web/api/rtcdtlstransport/index.md +++ b/files/en-us/web/api/rtcdtlstransport/index.md @@ -63,7 +63,7 @@ const rtcConfig = { const pc = new RTCPeerConnection(rtcConfig); ``` -[Bundling](https://webrtcstandards.info/sdp-bundle/) lets you use one `RTCDtlsTransport` to carry the data for multiple higher-level transports, such as multiple {{domxref("RTCRtpTransceiver")}}s. +[Bundling](https://datatracker.ietf.org/doc/rfc8843/) lets you use one `RTCDtlsTransport` to carry the data for multiple higher-level transports, such as multiple {{domxref("RTCRtpTransceiver")}}s. #### When not using BUNDLE diff --git a/files/en-us/web/api/rtcdtmfsender/tonechange_event/index.md b/files/en-us/web/api/rtcdtmfsender/tonechange_event/index.md index c874197f7ab8cf7..ec24f0deb6eaaee 100644 --- a/files/en-us/web/api/rtcdtmfsender/tonechange_event/index.md +++ b/files/en-us/web/api/rtcdtmfsender/tonechange_event/index.md @@ -18,10 +18,10 @@ This event is not cancelable and does not bubble. Use the event name in methods like {{domxref("EventTarget.addEventListener", "addEventListener()")}}, or set an event handler property. -```js -addEventListener("tonechange", (event) => {}); +```js-nolint +addEventListener("tonechange", (event) => { }) -ontonechange = (event) => {}; +ontonechange = (event) => { } ``` ## Event type diff --git a/files/en-us/web/api/rtcencodedaudioframe/getmetadata/index.md b/files/en-us/web/api/rtcencodedaudioframe/getmetadata/index.md index be11eaaed48c2e7..e2411236b2baef8 100644 --- a/files/en-us/web/api/rtcencodedaudioframe/getmetadata/index.md +++ b/files/en-us/web/api/rtcencodedaudioframe/getmetadata/index.md @@ -50,12 +50,11 @@ This example [WebRTC encoded transform](/en-US/docs/Web/API/WebRTC_API/Using_Enc ```js addEventListener("rtctransform", (event) => { - const async transform = new TransformStream({ + const transform = new TransformStream({ async transform(encodedFrame, controller) { - // Get the metadata and log const frameMetaData = encodedFrame.getMetadata(); - console.log(frameMetaData) + console.log(frameMetaData); // Enqueue the frame without modifying controller.enqueue(encodedFrame); @@ -70,7 +69,7 @@ addEventListener("rtctransform", (event) => { The resulting object from a local microphone might look like the one shown below. Note that there are no contributing sources because there is just one source, and no `sequenceNumber` because this is an outgoing frame. -```js +```json { "payloadType": 109, "synchronizationSource": 1876443470 diff --git a/files/en-us/web/api/rtcencodedaudioframe/index.md b/files/en-us/web/api/rtcencodedaudioframe/index.md index a325e56b3ccf44e..bee9b78bc844e15 100644 --- a/files/en-us/web/api/rtcencodedaudioframe/index.md +++ b/files/en-us/web/api/rtcencodedaudioframe/index.md @@ -33,7 +33,7 @@ The `transform()` method shows how this might be read, modified using a fictiona ```js addEventListener("rtctransform", (event) => { - const async transform = new TransformStream({ + const transform = new TransformStream({ async transform(encodedFrame, controller) { // Reconstruct the original frame. const view = new DataView(encodedFrame.data); @@ -42,7 +42,7 @@ addEventListener("rtctransform", (event) => { const newData = new ArrayBuffer(encodedFrame.data.byteLength); const newView = new DataView(newData); - //Encrypt frame bytes using the encryptFunction() method (not shown) + // Encrypt frame bytes using the encryptFunction() method (not shown) for (let i = 0; i < encodedFrame.data.byteLength; ++i) { const encryptedByte = encryptFunction(~view.getInt8(i)); newView.setInt8(i, encryptedByte); diff --git a/files/en-us/web/api/rtcencodedvideoframe/getmetadata/index.md b/files/en-us/web/api/rtcencodedvideoframe/getmetadata/index.md index 92b686c6bfe97a3..e2cdf74191354d0 100644 --- a/files/en-us/web/api/rtcencodedvideoframe/getmetadata/index.md +++ b/files/en-us/web/api/rtcencodedvideoframe/getmetadata/index.md @@ -51,7 +51,7 @@ An object with the following properties: - : A positive integer value indicating synchronization source ("ssrc") of the stream of RTP packets that are described by this encoded video frame. A source might be something like a camera or microphone, or some kind of mixer app that combines multiple sources. All packets from the same source share the same time source and sequence space, and so can be ordered relative to each other. - Note two frames with the same value refer to the same source (for more information see [`RTCInboundRtpStreamStats.ssrc`](/en-US/docs/Web/API/RTCInboundRtpStreamStats#ssrc)). + Note two frames with the same value refer to the same source (for more information see [`RTCInboundRtpStreamStats.ssrc`](/en-US/docs/Web/API/RTCInboundRtpStreamStats/ssrc)). - `payloadType` - : A positive integer value in the range from 0 to 127 that describes the format of the RTP payload. The mappings of values to formats is defined in RFC3550. @@ -69,12 +69,11 @@ This example [WebRTC encoded transform](/en-US/docs/Web/API/WebRTC_API/Using_Enc ```js addEventListener("rtctransform", (event) => { - const async transform = new TransformStream({ + const transform = new TransformStream({ async transform(encodedFrame, controller) { - // Get the metadata and log const frameMetaData = encodedFrame.getMetadata(); - console.log(frameMetaData) + console.log(frameMetaData); // Enqueue the frame without modifying controller.enqueue(encodedFrame); @@ -89,12 +88,10 @@ addEventListener("rtctransform", (event) => { The resulting object from a local webcam might look like the one shown below. Note that there are no contributing sources because there is just one source. -```js +```json { "contributingSources": [], - "dependencies": [ - 405 - ], + "dependencies": [405], "frameId": 406, "height": 480, "payloadType": 120, diff --git a/files/en-us/web/api/rtcencodedvideoframe/index.md b/files/en-us/web/api/rtcencodedvideoframe/index.md index 12b0ff6de1d4070..64e01c193f4d599 100644 --- a/files/en-us/web/api/rtcencodedvideoframe/index.md +++ b/files/en-us/web/api/rtcencodedvideoframe/index.md @@ -44,7 +44,7 @@ The `transform()` method shows how this might be read, modified by inverting the ```js addEventListener("rtctransform", (event) => { - const async transform = new TransformStream({ + const transform = new TransformStream({ async transform(encodedFrame, controller) { // Reconstruct the original frame. const view = new DataView(encodedFrame.data); diff --git a/files/en-us/web/api/rtcencodedvideoframe/type/index.md b/files/en-us/web/api/rtcencodedvideoframe/type/index.md index 680916e2321b0de..d6bbe1f3f86d568 100644 --- a/files/en-us/web/api/rtcencodedvideoframe/type/index.md +++ b/files/en-us/web/api/rtcencodedvideoframe/type/index.md @@ -30,7 +30,7 @@ The implementation of a `transform()` function in a [WebRTC Encoded Transform](/ ```js const transformer = new TransformStream({ - transform: async (encodedFrame, controller) => { + async transform(encodedFrame, controller) { if (encodedFrame.type === "key") { // Apply key frame transformation } else if (encodedFrame.type === "delta") { diff --git a/files/en-us/web/api/rtcerror/sdplinenumber/index.md b/files/en-us/web/api/rtcerror/sdplinenumber/index.md index f305a3a8e7ac159..7f2732e46e26114 100644 --- a/files/en-us/web/api/rtcerror/sdplinenumber/index.md +++ b/files/en-us/web/api/rtcerror/sdplinenumber/index.md @@ -15,7 +15,7 @@ The {{domxref("RTCError")}} interface's read-only property ## Value An unsigned integer value indicating the line within the SDP at which the syntax error -described by the `RTCError` object occurred. The lines are numbed starting +described by the `RTCError` object occurred. The lines are numbered starting with line 1. This property is `null` unless the value of diff --git a/files/en-us/web/api/rtcicecandidate/foundation/index.md b/files/en-us/web/api/rtcicecandidate/foundation/index.md index 2d85533293dc232..a6bc19d77c6fcb0 100644 --- a/files/en-us/web/api/rtcicecandidate/foundation/index.md +++ b/files/en-us/web/api/rtcicecandidate/foundation/index.md @@ -8,28 +8,27 @@ browser-compat: api.RTCIceCandidate.foundation {{APIRef("WebRTC")}} -The **{{domxref("RTCIceCandidate")}}** -interface's read-only **`foundation`** property is a string -which uniquely identifies the candidate across multiple transports. +The **`foundation`** read-only property of the {{domxref("RTCIceCandidate")}} interface is a string that allows correlation of candidates from a common network path on multiple {{domxref("RTCIceTransport")}} objects. -The `foundation` can therefore be used to correlate candidates that are present on -multiple {{domxref("RTCIceTransport")}} objects +Candidates share the same `foundation` if they: + +- have the same type: "host", "relayed", "server reflexive", or "peer reflexive". +- have "bases" that share the same IP address and transport, but not necessarily the same port. + Note that the IP address is that of the network interface from which the ICE agent sent the candidate. +- They come from a {{Glossary("STUN")}} or TURN server that has the same IP address. + +This is used to help optimize ICE performance while prioritizing and correlating candidates that appear on multiple {{domxref("RTCIceTransport")}} objects. ## Value -A string which uniquely identifies the candidate across all -`RTCIceTransport`s on which it is available. +A string which uniquely identifies the candidate across all `RTCIceTransport`s on which it is available. > [!NOTE] -> If `port` is `null` — and -> `port` is supported by the {{Glossary("user agent")}} — passing the -> candidate to {{domxref("RTCPeerConnection.addIceCandidate", "addIceCandidate()")}} -> will fail, throwing an `OperationError` exception. +> If `port` is `null` — and `port` is supported by the {{Glossary("user agent")}} — passing the candidate to {{domxref("RTCPeerConnection.addIceCandidate", "addIceCandidate()")}} will fail, throwing an `OperationError` exception. ## Usage notes -Consider this {{Glossary("SDP")}} attribute line (a-line) which describes an ICE -candidate: +Consider this {{Glossary("SDP")}} attribute line (a-line) which describes an ICE candidate: ```plain a=candidate:4234997325 1 udp 2043278322 192.0.2.172 44323 typ host @@ -39,8 +38,7 @@ The field `"4234997325"` is the foundation. ## Examples -This code snippet uses the `foundation` of two candidates to determine if -they're actually the same candidate. +This code snippet uses the `foundation` of two candidates to determine if they're actually the same candidate. ```js if (candidate1.foundation === candidate2.foundation) { diff --git a/files/en-us/web/api/rtcicecandidate/usernamefragment/index.md b/files/en-us/web/api/rtcicecandidate/usernamefragment/index.md index 36cdd81e8ff53a1..f8deefa04941f6d 100644 --- a/files/en-us/web/api/rtcicecandidate/usernamefragment/index.md +++ b/files/en-us/web/api/rtcicecandidate/usernamefragment/index.md @@ -71,11 +71,11 @@ restart, we can use code like this: ```js const ssNewCandidate = (signalMsg) => { - let candidate = new RTCIceCandidate(signalMsg.candidate); - let receivers = pc.getReceivers(); + const candidate = new RTCIceCandidate(signalMsg.candidate); + const receivers = pc.getReceivers(); for (const receiver of receivers) { - let parameters = receiver.transport.getParameters(); + const parameters = receiver.transport.iceTransport.getRemoteParameters(); if (parameters.usernameFragment === candidate.usernameFragment) { return; diff --git a/files/en-us/web/api/rtcicecandidatepairstats/availableincomingbitrate/index.md b/files/en-us/web/api/rtcicecandidatepairstats/availableincomingbitrate/index.md index 17aab5424355742..94f58f27ff7086b 100644 --- a/files/en-us/web/api/rtcicecandidatepairstats/availableincomingbitrate/index.md +++ b/files/en-us/web/api/rtcicecandidatepairstats/availableincomingbitrate/index.md @@ -3,7 +3,7 @@ title: "RTCIceCandidatePairStats: availableIncomingBitrate property" short-title: availableIncomingBitrate slug: Web/API/RTCIceCandidatePairStats/availableIncomingBitrate page-type: web-api-instance-property -browser-compat: api.RTCIceCandidatePairStats.availableIncomingBitrate +browser-compat: api.RTCStatsReport.type_candidate-pair.availableIncomingBitrate --- {{APIRef("WebRTC")}} diff --git a/files/en-us/web/api/rtcicecandidatepairstats/index.md b/files/en-us/web/api/rtcicecandidatepairstats/index.md index 4bbf531436d5978..9f7ff019009cfc1 100644 --- a/files/en-us/web/api/rtcicecandidatepairstats/index.md +++ b/files/en-us/web/api/rtcicecandidatepairstats/index.md @@ -9,7 +9,7 @@ browser-compat: api.RTCStatsReport.type_candidate-pair The **`RTCIceCandidatePairStats`** dictionary of the [WebRTC API](/en-US/docs/Web/API/WebRTC_API) is used to report statistics that provide insight into the quality and performance of an {{domxref("RTCPeerConnection")}} while connected and configured as described by the specified pair of {{Glossary("ICE")}} candidates. -The statistics can be obtained by iterating the {{domxref("RTCStatsReport")}} returned by {{domxref("RTCPeerConnection.getStats()")}} until you find an entry with the [`type`](#type) of `"candidate-pair"`. +The statistics can be obtained by iterating the {{domxref("RTCStatsReport")}} returned by {{domxref("RTCPeerConnection.getStats()")}} until you find an entry with the [`type`](/en-US/docs/Web/API/RTCIceCandidatePairStats/type) of `"candidate-pair"`. ## Instance properties diff --git a/files/en-us/web/api/rtcicecandidatepairstats/readable/index.md b/files/en-us/web/api/rtcicecandidatepairstats/readable/index.md index b3b9661303ec4ca..02f1ee0b85b6551 100644 --- a/files/en-us/web/api/rtcicecandidatepairstats/readable/index.md +++ b/files/en-us/web/api/rtcicecandidatepairstats/readable/index.md @@ -6,7 +6,7 @@ page-type: web-api-instance-property status: - deprecated - non-standard -browser-compat: api.RTCIceCandidatePairStats.readable +browser-compat: api.RTCStatsReport.type_candidate-pair.readable --- {{APIRef("WebRTC")}}{{Deprecated_Header}}{{Non-standard_Header}} diff --git a/files/en-us/web/api/rtcicecandidatepairstats/selected/index.md b/files/en-us/web/api/rtcicecandidatepairstats/selected/index.md index 1fed5d11747c080..9e43d5e67292d2f 100644 --- a/files/en-us/web/api/rtcicecandidatepairstats/selected/index.md +++ b/files/en-us/web/api/rtcicecandidatepairstats/selected/index.md @@ -3,7 +3,7 @@ title: "RTCIceCandidatePairStats: selected property" short-title: selected slug: Web/API/RTCIceCandidatePairStats/selected page-type: web-api-instance-property -browser-compat: api.RTCIceCandidatePairStats.selected +browser-compat: api.RTCStatsReport.type_candidate-pair.selected --- {{APIRef("WebRTC")}}{{non-standard_header}} diff --git a/files/en-us/web/api/rtcicecandidatepairstats/writable/index.md b/files/en-us/web/api/rtcicecandidatepairstats/writable/index.md index d0f300455e09212..9c20019db3d20a8 100644 --- a/files/en-us/web/api/rtcicecandidatepairstats/writable/index.md +++ b/files/en-us/web/api/rtcicecandidatepairstats/writable/index.md @@ -6,7 +6,7 @@ page-type: web-api-instance-property status: - deprecated - non-standard -browser-compat: api.RTCIceCandidatePairStats.writable +browser-compat: api.RTCStatsReport.type_candidate-pair.writable --- {{APIRef("WebRTC")}}{{Deprecated_Header}}{{Non-standard_Header}} diff --git a/files/en-us/web/api/rtcicecandidatestats/address/index.md b/files/en-us/web/api/rtcicecandidatestats/address/index.md index 2447598bbb43f2c..427e22af4500684 100644 --- a/files/en-us/web/api/rtcicecandidatestats/address/index.md +++ b/files/en-us/web/api/rtcicecandidatestats/address/index.md @@ -8,36 +8,23 @@ browser-compat: api.RTCStatsReport.type_local-candidate.address {{APIRef("WebRTC")}} -The **`address`** property of the -{{domxref("RTCIceCandidateStats")}} dictionary indicates the address of the -{{Glossary("ICE")}} candidate. While it's preferred that the address be specified as -an IPv4 or IPv6 numeric address, a fully-qualified domain name can be used as -well. +The **`address`** property of the {{domxref("RTCIceCandidateStats")}} dictionary indicates the address of the {{Glossary("ICE")}} candidate. +While it's preferred that the address be specified as an IPv4 or IPv6 numeric address, a fully-qualified domain name can be used as well. -When a domain name is specified, the first IP address selected for that -address is used, even if the domain name maps to multiple IP addresses. +When a domain name is specified, the first IP address selected for that address is used, even if the domain name maps to multiple IP addresses. ## Value -Either an IPv4 or IPv6 address or a fully-qualified domain name, which corresponds to -the candidate. +Either an IPv4 or IPv6 address or a fully-qualified domain name, which corresponds to the candidate. -- If the value of `address` is comprised entirely of digits from 0-9 with - periods as separators, the value is interpreted as an IPv4 address. -- If the value is entirely comprised of hexadecimal digits and colon (":") - characters, it is interpreted as an IPv6 address. -- Otherwise, the `address` is presumed to be a fully-qualified domain name, - which is resolved first using an AAAA record (assuming IPv6 is available), then using - an A record (if no result is found or the device only supports IPv4). If multiple IP - addresses are returned in response to the query, the {{Glossary("user agent")}} - selects one, which is then used for the duration of ICE processing. +- If the value of `address` is comprised entirely of digits from 0-9 with periods as separators, the value is interpreted as an IPv4 address. +- If the value is entirely comprised of hexadecimal digits and colon (":") characters, it is interpreted as an IPv6 address. +- Otherwise, the `address` is presumed to be a fully-qualified domain name, which is resolved first using an AAAA record (assuming IPv6 is available), then using an A record (if no result is found or the device only supports IPv4). + If multiple IP addresses are returned in response to the query, the {{Glossary("user agent")}} selects one, which is then used for the duration of ICE processing. ## Usage notes -The `address` property was previously known as `ip`, and only -permitted IPv4 and IPv6 addresses to be used. The addition of support for -fully-qualified domain names to be used for the address brought about the renaming of -the property. +The `address` property was previously known as `ip`, and only permitted IPv4 and IPv6 addresses to be used. The addition of support for fully-qualified domain names to be used for the address brought about the renaming of the property. ## Specifications diff --git a/files/en-us/web/api/rtcicecandidatestats/candidatetype/index.md b/files/en-us/web/api/rtcicecandidatestats/candidatetype/index.md index d64e7be26b1adf5..263efee08baf4df 100644 --- a/files/en-us/web/api/rtcicecandidatestats/candidatetype/index.md +++ b/files/en-us/web/api/rtcicecandidatestats/candidatetype/index.md @@ -8,11 +8,9 @@ browser-compat: api.RTCStatsReport.type_local-candidate.candidateType {{APIRef("WebRTC")}} -The {{domxref("RTCIceCandidateStats")}} interface's -**`candidateType`** property is a string that indicates the -type of {{Glossary("ICE")}} candidate the object represents. +The **`candidateType`** property of the {{domxref("RTCIceCandidateStats")}} dictionary is a string that indicates the type of {{Glossary("ICE")}} candidate the object represents. -## Value +### Value A string whose value is one of the strings found in [`RTCIceCandidate.type`](/en-US/docs/Web/API/RTCIceCandidate/type#value). diff --git a/files/en-us/web/api/rtcicecandidatestats/deleted/index.md b/files/en-us/web/api/rtcicecandidatestats/deleted/index.md index 17ae33caa156f19..b1a0e103866fe3e 100644 --- a/files/en-us/web/api/rtcicecandidatestats/deleted/index.md +++ b/files/en-us/web/api/rtcicecandidatestats/deleted/index.md @@ -3,7 +3,7 @@ title: "RTCIceCandidateStats: deleted property" short-title: deleted slug: Web/API/RTCIceCandidateStats/deleted page-type: web-api-instance-property -browser-compat: api.RTCIceCandidateStats.deleted +browser-compat: api.RTCStatsReport.type_local-candidate.deleted --- {{APIRef("WebRTC")}} diff --git a/files/en-us/web/api/rtcicecandidatestats/foundation/index.md b/files/en-us/web/api/rtcicecandidatestats/foundation/index.md new file mode 100644 index 000000000000000..05171ac2d28bc55 --- /dev/null +++ b/files/en-us/web/api/rtcicecandidatestats/foundation/index.md @@ -0,0 +1,29 @@ +--- +title: "RTCIceCandidateStats: foundation property" +short-title: foundation +slug: Web/API/RTCIceCandidateStats/foundation +page-type: web-api-instance-property +status: + - experimental +browser-compat: api.RTCStatsReport.type_local-candidate.foundation +--- + +{{APIRef("WebRTC")}}{{SeeCompatTable}} + +The **`foundation`** property of the {{domxref("RTCIceCandidateStats")}} interface is a string that allows correlation of candidates from a common network path on multiple {{domxref("RTCIceTransport")}} objects. + +It is the same for two candidates that are of the same type, are using the same transport protocol, originate from the same IP address, use ports that fall within the same range, and come from the same STUN server. + +For more information see {{domxref("RTCIceCandidate.foundation")}}. + +### Value + +A string representing the {{domxref("RTCIceCandidate.foundation", "foundation")}} of the corresponding {{domxref("RTCIceCandidate")}}. + +## Specifications + +{{Specifications}} + +## Browser compatibility + +{{Compat}} diff --git a/files/en-us/web/api/rtcicecandidatestats/index.md b/files/en-us/web/api/rtcicecandidatestats/index.md index 5c7d10a89c235cd..950522f8a3fd3b1 100644 --- a/files/en-us/web/api/rtcicecandidatestats/index.md +++ b/files/en-us/web/api/rtcicecandidatestats/index.md @@ -9,30 +9,38 @@ browser-compat: api.RTCStatsReport.type_local-candidate The **`RTCIceCandidateStats`** dictionary of the [WebRTC API](/en-US/docs/Web/API/WebRTC_API) is used to report statistics related to an {{domxref("RTCIceCandidate")}}. -The statistics can be obtained by iterating the {{domxref("RTCStatsReport")}} returned by {{domxref("RTCPeerConnection.getStats()")}} until you find a report with the [`type`](#type) of `local-candidate`. +The statistics can be obtained by iterating the {{domxref("RTCStatsReport")}} returned by {{domxref("RTCPeerConnection.getStats()")}} until you find a report with the [`type`](/en-US/docs/Web/API/RTCIceCandidateStats/type) of `local-candidate`. ## Instance properties - {{domxref("RTCIceCandidateStats.address", "address")}} {{optional_inline}} - : A string containing the address of the candidate. This value may be an IPv4 address, an IPv6 address, or a fully-qualified domain name. This property was previously named `ip` and only accepted IP addresses. + Corresponds to {{domxref("RTCIceCandidate.address")}}. - {{domxref("RTCIceCandidateStats.candidateType", "candidateType")}} - : A string matching one of the values in [`RTCIceCandidate.type`](/en-US/docs/Web/API/RTCIceCandidate/type#value), indicating what kind of candidate the object provides statistics for. -- {{domxref("RTCIceCandidateStats.deleted", "deleted")}} {{optional_inline}} - - : A Boolean value indicating whether or not the candidate has been released or deleted; the default value is `false`. For local candidates, its value is `true` if the candidate has been deleted or released. For host candidates, `true` means that any network resources (usually a network socket) associated with the candidate have already been released. For {{Glossary("TURN")}} candidates, the TURN allocation is no longer active for deleted candidates. This property is not present for remote candidates. +- {{domxref("RTCIceCandidateStats.deleted", "deleted")}} + - : A boolean indicating whether or not the candidate has been deleted or released. +- {{domxref("RTCIceCandidateStats.foundation", "foundation")}} {{optional_inline}} {{experimental_inline}} + - : A string that uniquely identifies the candidate across multiple transports. + Corresponds to {{domxref("RTCIceCandidate.foundation")}}. - {{domxref("RTCIceCandidateStats.port", "port")}} {{optional_inline}} - : The network port number used by the candidate. + Corresponds to {{domxref("RTCIceCandidate.port")}}. - {{domxref("RTCIceCandidateStats.priority", "priority")}} {{optional_inline}} - - : The candidate's priority, corresponding to {{domxref("RTCIceCandidate.priority")}}. + - : The candidate's priority. + Corresponds to {{domxref("RTCIceCandidate.priority")}}. - {{domxref("RTCIceCandidateStats.protocol", "protocol")}} {{optional_inline}} - : A string specifying the protocol (`tcp` or `udp`) used to transmit data on the `port`. -- {{domxref("RTCIceCandidateStats.relayProtocol", "relayProtocol")}} {{optional_inline}} - - : A string identifying the protocol used by the endpoint for communicating with the {{Glossary("TURN")}} server; valid values are `tcp`, `udp`, and `tls`. - Only present for local candidates. + Corresponds to {{domxref("RTCIceCandidate.protocol")}}. +- {{domxref("RTCIceCandidateStats.relayProtocol", "relayProtocol")}} + - : A string specifying the protocol being used by a local {{Glossary("ICE")}} candidate to communicate with the {{Glossary("TURN")}} server. - {{domxref("RTCIceCandidateStats.transportId", "transportId")}} - : A string uniquely identifying the transport object that was inspected in order to obtain the {{domxref("RTCTransportStats")}} associated with the candidate corresponding to these statistics. - {{domxref("RTCIceCandidateStats.url", "url")}} {{optional_inline}} - - : For local candidates, the `url` property is the {{Glossary("URL")}} of the {{Glossary("ICE")}} server from which the candidate was received. - This URL matches the one included in the {{domxref("RTCPeerConnectionIceEvent")}} object representing the {{domxref("RTCPeerConnection.icecandidate_event", "icecandidate")}} event that delivered the candidate to the local peer. + - : A string specifying the URL of the {{Glossary("ICE")}} server from which the described candidate was obtained. This property is _only_ available for local candidates. +- {{domxref("RTCIceCandidateStats.usernameFragment", "usernameFragment")}} {{optional_inline}} {{experimental_inline}} + - : A string containing the ICE username fragment ("ice-ufrag"). + Corresponds to {{domxref("RTCIceCandidate.usernameFragment")}}. ### Common instance properties @@ -49,7 +57,19 @@ The following properties are common to all WebRTC statistics objects. ## Examples -TBD +Given a variable `myPeerConnection`, which is an instance of {{domxref("RTCPeerConnection")}}, the code below uses `await` to wait for the statistics report, and then iterates it using `RTCStatsReport.forEach()`. +It then filters the dictionaries for just those reports that have the type of `local-candidate` and logs the result. + +```js +const stats = await myPeerConnection.getStats(); + +stats.forEach((report) => { + if (report.type === "local-candidate") { + // Log the ICE candidate information + console.log(report); + } +}); +``` ## Specifications diff --git a/files/en-us/web/api/rtcicecandidatestats/port/index.md b/files/en-us/web/api/rtcicecandidatestats/port/index.md index 4c5a07a56c0b8a0..dc874de81bfca99 100644 --- a/files/en-us/web/api/rtcicecandidatestats/port/index.md +++ b/files/en-us/web/api/rtcicecandidatestats/port/index.md @@ -8,13 +8,12 @@ browser-compat: api.RTCStatsReport.type_local-candidate.port {{APIRef("WebRTC")}} -The {{domxref("RTCIceCandidateStats")}} dictionary's **`port`** -property specifies the network port used by the candidate. +The **`port`** property of the {{domxref("RTCIceCandidateStats")}} dictionary specifies the network port used by the candidate. ## Value -An integer value indicating the network port used by the {{domxref("RTCIceCandidate")}} -described by the `RTCIceCandidateStats` object. +An integer value indicating the network port used by the {{domxref("RTCIceCandidate")}} described by this `RTCIceCandidateStats` object. +Corresponds to {{domxref("RTCIceCandidate.port")}}. ## Specifications diff --git a/files/en-us/web/api/rtcicecandidatestats/priority/index.md b/files/en-us/web/api/rtcicecandidatestats/priority/index.md index bb814c8a236c975..c948d00e06f31d4 100644 --- a/files/en-us/web/api/rtcicecandidatestats/priority/index.md +++ b/files/en-us/web/api/rtcicecandidatestats/priority/index.md @@ -8,35 +8,28 @@ browser-compat: api.RTCStatsReport.type_local-candidate.priority {{APIRef("WebRTC")}} -The {{domxref("RTCIceCandidateStats")}} dictionary's -**`priority`** property is a positive integer value -indicating the priority (or desirability) of the described candidate. +The **`priority`** property of the {{domxref("RTCIceCandidateStats")}} dictionary is a positive integer value indicating the priority (or desirability) of the described candidate. -During {{Glossary("ICE")}} negotiation while setting up a WebRTC peer connection, the -priority values reported to the remote peer by a {{Glossary("user agent")}} are used -to determine which candidates are considered "more desirable". The higher the value, -the more desirable the candidate is. +### Value -## Value +A positive integer indicating the priority of the {{domxref("RTCIceCandidate")}} described by the `RTCIceCandidateStats` object. +The value may be anywhere from 1 to 2,147,483,647. -A positive integer indicating the priority of the {{domxref("RTCIceCandidate")}} -described by the `RTCIceCandidateStats` object. The value may be anywhere -from 1 to 2,147,483,647. +## Description -## Determining priority +During {{Glossary("ICE")}} negotiation while setting up a WebRTC peer connection, the priority values reported to the remote peer by a {{Glossary("user agent")}} are used to determine which candidates are considered "more desirable". +The higher the value, the more desirable the candidate is. -The ICE specification describes how user agents and other software using WebRTC should -calculate the priority. The priority of a candidate is calculated using the following -variables as inputs: +### Determining priority -- The preferability of the candidate type (local, server reflexive, peer reflexive, - or relayed) +The ICE specification describes how user agents and other software using WebRTC should calculate the priority. +The priority of a candidate is calculated using the following variables as inputs: + +- The preferability of the candidate type (local, server reflexive, peer reflexive, or relayed) - The preferability of the candidate's specific IP address (for multihomed agents) - The candidate's component ID (1 for RTP, 2 for RTCP) -The candidate's priority is computed using the formula (_p<sub>type</sub>_ is -the priority of the candidate's type and _p<sub>local</sub>_ is the priority of -the IP address): +The candidate's priority is computed using the formula (_p<sub>type</sub>_ is the priority of the candidate's type and _p<sub>local</sub>_ is the priority of the IP address): <!-- prettier-ignore-start --> <math display="block"> @@ -44,9 +37,7 @@ the IP address): </math> <!-- prettier-ignore-end --> -This is equivalent to mapping the priorities of the candidate type, the local IP, and -the component ID into various bit ranges within the 32-bit `priority` -value. +This is equivalent to mapping the priorities of the candidate type, the local IP, and the component ID into various bit ranges within the 32-bit `priority` value. ## Specifications diff --git a/files/en-us/web/api/rtcicecandidatestats/protocol/index.md b/files/en-us/web/api/rtcicecandidatestats/protocol/index.md index eedd23346141600..111d0f1fe229506 100644 --- a/files/en-us/web/api/rtcicecandidatestats/protocol/index.md +++ b/files/en-us/web/api/rtcicecandidatestats/protocol/index.md @@ -8,18 +8,18 @@ browser-compat: api.RTCStatsReport.type_local-candidate.protocol {{APIRef("WebRTC")}} -The {{domxref("RTCIceCandidateStats")}} dictionary's -**`protocol`** property specifies the protocol the specified -candidate would use for communication with the remote peer. +The **`protocol`** property of the {{domxref("RTCIceCandidateStats")}} dictionary indicates the protocol the specified candidate would use for communication with the remote peer. ## Value -The value is one of the following string: +The value is one of the following strings: - `tcp` - - : The candidate, if selected, would use {{Glossary("TCP")}} as the transport protocol for its data. The {{domxref("RTCIceCandidate.tcpType", "tcpType")}} property provides additional information about the kind of TCP candidate represented by the object. + - : The candidate, if selected, would use {{Glossary("TCP")}} as the transport protocol for its data. + The {{domxref("RTCIceCandidate.tcpType", "tcpType")}} property provides additional information about the kind of TCP candidate represented by the object. - `udp` - - : The candidate will use the {{Glossary("UDP")}} transport protocol for its data. This is the preferred protocol for media interactions because of its better performance profile. + - : The candidate will use the {{Glossary("UDP")}} transport protocol for its data. + This is the preferred protocol for media interactions because of its better performance profile. ## Specifications diff --git a/files/en-us/web/api/rtcicecandidatestats/relayprotocol/index.md b/files/en-us/web/api/rtcicecandidatestats/relayprotocol/index.md index 5b58e34626c4a96..a003451587224db 100644 --- a/files/en-us/web/api/rtcicecandidatestats/relayprotocol/index.md +++ b/files/en-us/web/api/rtcicecandidatestats/relayprotocol/index.md @@ -3,7 +3,7 @@ title: "RTCIceCandidateStats: relayProtocol property" short-title: relayProtocol slug: Web/API/RTCIceCandidateStats/relayProtocol page-type: web-api-instance-property -browser-compat: api.RTCIceCandidateStats.relayProtocol +browser-compat: api.RTCStatsReport.type_local-candidate.relayProtocol --- {{APIRef("WebRTC")}} diff --git a/files/en-us/web/api/rtcicecandidatestats/transportid/index.md b/files/en-us/web/api/rtcicecandidatestats/transportid/index.md index 513edf1830e2d0a..f4e317e383d20d2 100644 --- a/files/en-us/web/api/rtcicecandidatestats/transportid/index.md +++ b/files/en-us/web/api/rtcicecandidatestats/transportid/index.md @@ -8,17 +8,13 @@ browser-compat: api.RTCStatsReport.type_local-candidate.transportId {{APIRef("WebRTC")}} -The {{domxref("RTCIceCandidateStats")}} dictionary's -**`transportId`** property is a string that uniquely -identifies the transport that produced the {{domxref("RTCTransportStats")}} from which -information about this candidate was taken. +The **`transportId`** property of the {{domxref("RTCIceCandidateStats")}} dictionary is a string that uniquely identifies the transport that produced the {{domxref("RTCTransportStats")}} from which information about this candidate was taken. + +This can be used, for example, to compare candidates that use the same transport. ## Value -A string whose value uniquely identifies the transport from which any -transport-related information accumulated in the {{domxref("RTCIceCandidateStats")}} was -taken. This can be used to compare candidates that would use the same transport, for -example. +A string whose value uniquely identifies the transport from which any transport-related information accumulated in the {{domxref("RTCIceCandidateStats")}} was taken. ## Specifications diff --git a/files/en-us/web/api/rtcicecandidatestats/url/index.md b/files/en-us/web/api/rtcicecandidatestats/url/index.md index e4ad6c7b070f6b8..22767ab858b834a 100644 --- a/files/en-us/web/api/rtcicecandidatestats/url/index.md +++ b/files/en-us/web/api/rtcicecandidatestats/url/index.md @@ -3,7 +3,7 @@ title: "RTCIceCandidateStats: url property" short-title: url slug: Web/API/RTCIceCandidateStats/url page-type: web-api-instance-property -browser-compat: api.RTCIceCandidateStats.url +browser-compat: api.RTCStatsReport.type_local-candidate.url --- {{APIRef("WebRTC")}} diff --git a/files/en-us/web/api/rtcicecandidatestats/usernamefragment/index.md b/files/en-us/web/api/rtcicecandidatestats/usernamefragment/index.md new file mode 100644 index 000000000000000..079174382cd7391 --- /dev/null +++ b/files/en-us/web/api/rtcicecandidatestats/usernamefragment/index.md @@ -0,0 +1,29 @@ +--- +title: "RTCIceCandidateStats: usernameFragment property" +short-title: usernameFragment +slug: Web/API/RTCIceCandidateStats/usernameFragment +page-type: web-api-instance-property +status: + - experimental +browser-compat: api.RTCStatsReport.type_local-candidate.usernameFragment +--- + +{{APIRef("WebRTC")}}{{SeeCompatTable}} + +The **`usernameFragment`** property of the {{domxref("RTCIceCandidateStats")}} interface is a string that represents the {{Glossary("ICE")}} username fragment ("ice-ufrag"). + +The fragment uniquely identifies a single ICE interaction session, and can be used to identify communications that are part of the same session even across ICE restarts. + +For more information see {{domxref("RTCIceCandidate.usernameFragment")}}. + +### Value + +A string representing the {{domxref("RTCIceCandidate.usernameFragment", "usernameFragment")}} of the corresponding {{domxref("RTCIceCandidate")}}. + +## Specifications + +{{Specifications}} + +## Browser compatibility + +{{Compat}} diff --git a/files/en-us/web/api/rtciceparameters/index.md b/files/en-us/web/api/rtciceparameters/index.md index d6b47070f89b7bf..f840a8dcab2b9e2 100644 --- a/files/en-us/web/api/rtciceparameters/index.md +++ b/files/en-us/web/api/rtciceparameters/index.md @@ -2,7 +2,7 @@ title: RTCIceParameters slug: Web/API/RTCIceParameters page-type: web-api-interface -browser-compat: api.RTCIceParameters +spec-urls: https://w3c.github.io/webrtc-pc/#rtciceparameters --- {{APIRef("WebRTC")}} @@ -25,7 +25,3 @@ The username fragment and password uniquely identify the remote peer for the dur ## Specifications {{Specifications}} - -## Browser compatibility - -{{Compat}} diff --git a/files/en-us/web/api/rtciceparameters/password/index.md b/files/en-us/web/api/rtciceparameters/password/index.md index ee06b4335346669..32fc5ecca232452 100644 --- a/files/en-us/web/api/rtciceparameters/password/index.md +++ b/files/en-us/web/api/rtciceparameters/password/index.md @@ -3,7 +3,7 @@ title: "RTCIceParameters: password property" short-title: password slug: Web/API/RTCIceParameters/password page-type: web-api-instance-property -browser-compat: api.RTCIceParameters.password +spec-urls: https://w3c.github.io/webrtc-pc/#dom-rtciceparameters-password --- {{APIRef("WebRTC")}} @@ -21,7 +21,3 @@ A string containing the password that corresponds to the transport's ## Specifications {{Specifications}} - -## Browser compatibility - -{{Compat}} diff --git a/files/en-us/web/api/rtciceparameters/usernamefragment/index.md b/files/en-us/web/api/rtciceparameters/usernamefragment/index.md index 3afbc2e6190778b..a5fac33a440962b 100644 --- a/files/en-us/web/api/rtciceparameters/usernamefragment/index.md +++ b/files/en-us/web/api/rtciceparameters/usernamefragment/index.md @@ -3,7 +3,7 @@ title: "RTCIceParameters: usernameFragment property" short-title: usernameFragment slug: Web/API/RTCIceParameters/usernameFragment page-type: web-api-instance-property -browser-compat: api.RTCIceParameters.usernameFragment +spec-urls: https://w3c.github.io/webrtc-pc/#dom-rtciceparameters-usernamefragment --- {{APIRef("WebRTC")}} @@ -25,7 +25,3 @@ fragments and their role in a connection. ## Specifications {{Specifications}} - -## Browser compatibility - -{{Compat}} diff --git a/files/en-us/web/api/rtcicetransport/gatheringstatechange_event/index.md b/files/en-us/web/api/rtcicetransport/gatheringstatechange_event/index.md index bafc000be8b7422..2707995db7c424b 100644 --- a/files/en-us/web/api/rtcicetransport/gatheringstatechange_event/index.md +++ b/files/en-us/web/api/rtcicetransport/gatheringstatechange_event/index.md @@ -18,10 +18,10 @@ This event is not cancelable and does not bubble. Use the event name in methods like {{domxref("EventTarget.addEventListener", "addEventListener()")}}, or set an event handler property. -```js -addEventListener("gatheringstatechange", (event) => {}); +```js-nolint +addEventListener("gatheringstatechange", (event) => { }) -ongatheringstatechange = (event) => {}; +ongatheringstatechange = (event) => { } ``` ## Event type diff --git a/files/en-us/web/api/rtcicetransport/selectedcandidatepairchange_event/index.md b/files/en-us/web/api/rtcicetransport/selectedcandidatepairchange_event/index.md index 53543631e70646b..2a07ed09e37df37 100644 --- a/files/en-us/web/api/rtcicetransport/selectedcandidatepairchange_event/index.md +++ b/files/en-us/web/api/rtcicetransport/selectedcandidatepairchange_event/index.md @@ -20,10 +20,10 @@ This event is not cancelable and does not bubble. Use the event name in methods like {{domxref("EventTarget.addEventListener", "addEventListener()")}}, or set an event handler property. -```js -addEventListener("selectedcandidatepairchange", (event) => {}); +```js-nolint +addEventListener("selectedcandidatepairchange", (event) => { }) -onselectedcandidatepairchange = (event) => {}; +onselectedcandidatepairchange = (event) => { } ``` ## Event type diff --git a/files/en-us/web/api/rtcicetransport/statechange_event/index.md b/files/en-us/web/api/rtcicetransport/statechange_event/index.md index d0d8332021dc38d..c4effae94ec41a0 100644 --- a/files/en-us/web/api/rtcicetransport/statechange_event/index.md +++ b/files/en-us/web/api/rtcicetransport/statechange_event/index.md @@ -16,10 +16,10 @@ This event is not cancelable and does not bubble. Use the event name in methods like {{domxref("EventTarget.addEventListener", "addEventListener()")}}, or set an event handler property. -```js -addEventListener("statechange", (event) => {}); +```js-nolint +addEventListener("statechange", (event) => { }) -onstatechange = (event) => {}; +onstatechange = (event) => { } ``` ## Event type diff --git a/files/en-us/web/api/rtcinboundrtpstreamstats/averagertcpinterval/index.md b/files/en-us/web/api/rtcinboundrtpstreamstats/averagertcpinterval/index.md index dd9a0c6ae84296b..397998aa7c3c525 100644 --- a/files/en-us/web/api/rtcinboundrtpstreamstats/averagertcpinterval/index.md +++ b/files/en-us/web/api/rtcinboundrtpstreamstats/averagertcpinterval/index.md @@ -3,7 +3,7 @@ title: "RTCInboundRtpStreamStats: averageRtcpInterval property" short-title: averageRtcpInterval slug: Web/API/RTCInboundRtpStreamStats/averageRtcpInterval page-type: web-api-instance-property -browser-compat: api.RTCInboundRtpStreamStats.averageRtcpInterval +browser-compat: api.RTCStatsReport.type_inbound-rtp.averageRtcpInterval --- {{APIRef("WebRTC")}} diff --git a/files/en-us/web/api/rtcinboundrtpstreamstats/index.md b/files/en-us/web/api/rtcinboundrtpstreamstats/index.md index 4a07e77a072cd9c..adfc64d3d1730ef 100644 --- a/files/en-us/web/api/rtcinboundrtpstreamstats/index.md +++ b/files/en-us/web/api/rtcinboundrtpstreamstats/index.md @@ -9,7 +9,7 @@ browser-compat: api.RTCStatsReport.type_inbound-rtp The **`RTCInboundRtpStreamStats`** dictionary of the [WebRTC API](/en-US/docs/Web/API/WebRTC_API) is used to report statistics related to the receiving end of an RTP stream on the local end of the {{domxref("RTCPeerConnection")}}. -The statistics can be obtained by iterating the {{domxref("RTCStatsReport")}} returned by {{domxref("RTCPeerConnection.getStats()")}} or {{domxref("RTCRtpReceiver.getStats()")}} until you find a report with the [`type`](#type) of `inbound-rtp`. +The statistics can be obtained by iterating the {{domxref("RTCStatsReport")}} returned by {{domxref("RTCPeerConnection.getStats()")}} or {{domxref("RTCRtpReceiver.getStats()")}} until you find a report with the [`type`](/en-US/docs/Web/API/RTCInboundRtpStreamStats/type) of `inbound-rtp`. ## Instance properties @@ -25,7 +25,7 @@ The statistics can be obtained by iterating the {{domxref("RTCStatsReport")}} re - : A long integer value indicating the total number of frames of video which have been correctly decoded so far for this media source. This is the number of frames that would have been rendered if none were dropped. _Only valid for video streams._ - {{domxref("RTCInboundRtpStreamStats.lastPacketReceivedTimestamp", "lastPacketReceivedTimestamp")}} - : A {{domxref("DOMHighResTimeStamp")}} indicating the time at which the last packet was received for this source. - The [`timestamp`](#timestamp) property, on the other hand, indicates the time at which the statistics object was generated. + The [`timestamp`](/en-US/docs/Web/API/RTCInboundRtpStreamStats/timestamp) property, on the other hand, indicates the time at which the statistics object was generated. - {{domxref("RTCInboundRtpStreamStats.mid", "mid")}} - : A string that uniquely identifies the pairing of source and destination of the transceiver's stream. This is the value of the corresponding {{domxref("RTCRtpTransceiver.mid")}} unless that is null, in which case the statistic property is not present. @@ -45,7 +45,7 @@ The statistics can be obtained by iterating the {{domxref("RTCStatsReport")}} re - : An integer indicating the number of times the receiver sent a Slice Loss Indication (SLI) frame to the sender to tell it that one or more consecutive (in terms of scan order) video macroblocks have been lost or corrupted. Available only for video streams. - `trackIdentifier` - : A string that contains the {{domxref("MediaStreamTrack.id", "id")}} value of the `MediaStreamTrack` associated with the inbound stream. -- {{domxref("RTCInboundRtpStreamStats.trackId", "trackId")}} {{deprecated_inline}} +- `trackId` {{deprecated_inline}} - : A string which identifies the statistics object representing the receiving track; this object is one of two types: {{domxref("RTCReceiverAudioTrackAttachmentStats")}} or {{domxref("RTCReceiverVideoTrackAttachmentStats")}}. This ID is stable across multiple calls to `getStats()`. ### Statistics measured at the receiver of an RTP stream @@ -102,8 +102,6 @@ The following properties are common to all WebRTC statistics objects. - {{domxref("RTCInboundRtpStreamStats.type", "type")}} - : A string with the value `"inbound-rtp"`, indicating the type of statistics that the object contains. -## Examples - ## Specifications {{Specifications}} diff --git a/files/en-us/web/api/rtcinboundrtpstreamstats/kind/index.md b/files/en-us/web/api/rtcinboundrtpstreamstats/kind/index.md index e4436a09e45554e..d9302630377da47 100644 --- a/files/en-us/web/api/rtcinboundrtpstreamstats/kind/index.md +++ b/files/en-us/web/api/rtcinboundrtpstreamstats/kind/index.md @@ -11,7 +11,7 @@ browser-compat: api.RTCStatsReport.type_inbound-rtp.kind The **`kind`** property of the {{domxref("RTCInboundRtpStreamStats")}} dictionary is a string indicating whether the described {{Glossary("RTP")}} stream contains audio or video media. This string will always be the same as the {{domxref("MediaStreamTrack.kind", "kind")}} of the {{domxref("MediaStreamTrack")}} object carried by the stream. -It will also match the media type of the codec associated with this statistics objects (i.e. the MIME type of the associated codec's {{domxref("RTCCodecStats.mimeType")}} property). +It will also match the media type of the codec associated with this statistics objects (i.e., the MIME type of the associated codec's {{domxref("RTCCodecStats.mimeType")}} property). ## Value diff --git a/files/en-us/web/api/rtcinboundrtpstreamstats/packetsduplicated/index.md b/files/en-us/web/api/rtcinboundrtpstreamstats/packetsduplicated/index.md index ef87c0e7b1663ac..b3dcefe14a9a62e 100644 --- a/files/en-us/web/api/rtcinboundrtpstreamstats/packetsduplicated/index.md +++ b/files/en-us/web/api/rtcinboundrtpstreamstats/packetsduplicated/index.md @@ -3,7 +3,7 @@ title: "RTCInboundRtpStreamStats: packetsDuplicated property" short-title: packetsDuplicated slug: Web/API/RTCInboundRtpStreamStats/packetsDuplicated page-type: web-api-instance-property -browser-compat: api.RTCInboundRtpStreamStats.packetsDuplicated +browser-compat: api.RTCStatsReport.type_inbound-rtp.packetsDuplicated --- {{APIRef("WebRTC")}} diff --git a/files/en-us/web/api/rtcinboundrtpstreamstats/packetsfaileddecryption/index.md b/files/en-us/web/api/rtcinboundrtpstreamstats/packetsfaileddecryption/index.md index 155c31e397de875..9ed0f5bc5cae0b3 100644 --- a/files/en-us/web/api/rtcinboundrtpstreamstats/packetsfaileddecryption/index.md +++ b/files/en-us/web/api/rtcinboundrtpstreamstats/packetsfaileddecryption/index.md @@ -3,7 +3,7 @@ title: "RTCInboundRtpStreamStats: packetsFailedDecryption property" short-title: packetsFailedDecryption slug: Web/API/RTCInboundRtpStreamStats/packetsFailedDecryption page-type: web-api-instance-property -browser-compat: api.RTCInboundRtpStreamStats.packetsFailedDecryption +browser-compat: api.RTCStatsReport.type_inbound-rtp.packetsFailedDecryption --- {{APIRef("WebRTC")}} diff --git a/files/en-us/web/api/rtcinboundrtpstreamstats/perdscppacketsreceived/index.md b/files/en-us/web/api/rtcinboundrtpstreamstats/perdscppacketsreceived/index.md index 01871c2f14f57e7..0d55c68cffdba2f 100644 --- a/files/en-us/web/api/rtcinboundrtpstreamstats/perdscppacketsreceived/index.md +++ b/files/en-us/web/api/rtcinboundrtpstreamstats/perdscppacketsreceived/index.md @@ -3,7 +3,7 @@ title: "RTCInboundRtpStreamStats: perDscpPacketsReceived property" short-title: perDscpPacketsReceived slug: Web/API/RTCInboundRtpStreamStats/perDscpPacketsReceived page-type: web-api-instance-property -browser-compat: api.RTCInboundRtpStreamStats.perDscpPacketsReceived +browser-compat: api.RTCStatsReport.type_inbound-rtp.perDscpPacketsReceived --- {{APIRef("WebRTC")}} diff --git a/files/en-us/web/api/rtcinboundrtpstreamstats/receiverid/index.md b/files/en-us/web/api/rtcinboundrtpstreamstats/receiverid/index.md index 1a7072f6c323c5c..7473e29f892b7a2 100644 --- a/files/en-us/web/api/rtcinboundrtpstreamstats/receiverid/index.md +++ b/files/en-us/web/api/rtcinboundrtpstreamstats/receiverid/index.md @@ -3,7 +3,7 @@ title: "RTCInboundRtpStreamStats: receiverId property" short-title: receiverId slug: Web/API/RTCInboundRtpStreamStats/receiverId page-type: web-api-instance-property -browser-compat: api.RTCInboundRtpStreamStats.receiverId +browser-compat: api.RTCStatsReport.type_inbound-rtp.receiverId --- {{APIRef("WebRTC")}} diff --git a/files/en-us/web/api/rtcinboundrtpstreamstats/slicount/index.md b/files/en-us/web/api/rtcinboundrtpstreamstats/slicount/index.md index f440300b0a8e30b..4c996160cf3385e 100644 --- a/files/en-us/web/api/rtcinboundrtpstreamstats/slicount/index.md +++ b/files/en-us/web/api/rtcinboundrtpstreamstats/slicount/index.md @@ -3,7 +3,7 @@ title: "RTCInboundRtpStreamStats: sliCount property" short-title: sliCount slug: Web/API/RTCInboundRtpStreamStats/sliCount page-type: web-api-instance-property -browser-compat: api.RTCInboundRtpStreamStats.sliCount +browser-compat: api.RTCStatsReport.type_inbound-rtp.sliCount --- {{APIRef("WebRTC")}} diff --git a/files/en-us/web/api/rtcoutboundrtpstreamstats/active/index.md b/files/en-us/web/api/rtcoutboundrtpstreamstats/active/index.md index db30381336e36f4..973b59b44c08688 100644 --- a/files/en-us/web/api/rtcoutboundrtpstreamstats/active/index.md +++ b/files/en-us/web/api/rtcoutboundrtpstreamstats/active/index.md @@ -12,7 +12,7 @@ browser-compat: api.RTCStatsReport.type_outbound-rtp.active The **`active`** property of the {{domxref("RTCOutboundRtpStreamStats")}} dictionary is a boolean that indicates whether this RTP stream is configured to be sent, or is disabled. -For example, this would be be `false` if the track corresponding to the the stream had its {{domxref("MediaStreamTrack.enabled")}} property set to `false`. +For example, this would be `false` if the track corresponding to the stream had its {{domxref("MediaStreamTrack.enabled")}} property set to `false`. Note that an active stream may still not be sending if, for example, the stream is limited by network conditions. ## Value diff --git a/files/en-us/web/api/rtcoutboundrtpstreamstats/index.md b/files/en-us/web/api/rtcoutboundrtpstreamstats/index.md index 004887facc8d271..3ad8040bb56967c 100644 --- a/files/en-us/web/api/rtcoutboundrtpstreamstats/index.md +++ b/files/en-us/web/api/rtcoutboundrtpstreamstats/index.md @@ -9,7 +9,7 @@ browser-compat: api.RTCStatsReport.type_outbound-rtp The **`RTCOutboundRtpStreamStats`** dictionary of the [WebRTC API](/en-US/docs/Web/API/WebRTC_API) is used to report metrics and statistics related to an outbound {{Glossary("RTP")}} stream being sent by an {{domxref("RTCRtpSender")}}. -The statistics can be obtained by iterating the {{domxref("RTCStatsReport")}} returned by {{domxref("RTCPeerConnection.getStats()")}} or {{domxref("RTCRtpSender.getStats()")}} until you find a report with the [`type`](#type) of `outbound-rtp`. +The statistics can be obtained by iterating the {{domxref("RTCStatsReport")}} returned by {{domxref("RTCPeerConnection.getStats()")}} or {{domxref("RTCRtpSender.getStats()")}} until you find a report with the [`type`](/en-US/docs/Web/API/RTCOutboundRtpStreamStats/type) of `outbound-rtp`. ## Instance properties @@ -112,8 +112,6 @@ The following properties are common to all WebRTC statistics objects. - {{domxref("RTCOutboundRtpStreamStats.type", "type")}} - : A string with the value `"outbound-rtp"`, indicating the type of statistics that the object contains. -## Examples - ## Specifications {{Specifications}} diff --git a/files/en-us/web/api/rtcoutboundrtpstreamstats/kind/index.md b/files/en-us/web/api/rtcoutboundrtpstreamstats/kind/index.md index 1969d2264793e3d..da391e0f6de9353 100644 --- a/files/en-us/web/api/rtcoutboundrtpstreamstats/kind/index.md +++ b/files/en-us/web/api/rtcoutboundrtpstreamstats/kind/index.md @@ -11,7 +11,7 @@ browser-compat: api.RTCStatsReport.type_outbound-rtp.kind The **`kind`** property of the {{domxref("RTCOutboundRtpStreamStats")}} dictionary is a string indicating whether the described {{Glossary("RTP")}} stream contains audio or video media. This string will always be the same as the {{domxref("MediaStreamTrack.kind", "kind")}} of the {{domxref("MediaStreamTrack")}} object carried by the stream. -It will also match the media type of the codec associated with this statistics objects (i.e. the MIME type of the associated codec's {{domxref("RTCCodecStats.mimeType")}} property). +It will also match the media type of the codec associated with this statistics objects (i.e., the MIME type of the associated codec's {{domxref("RTCCodecStats.mimeType")}} property). ## Value diff --git a/files/en-us/web/api/rtcoutboundrtpstreamstats/qualitylimitationdurations/index.md b/files/en-us/web/api/rtcoutboundrtpstreamstats/qualitylimitationdurations/index.md index 1bb631d391a4332..4f187a11b3cad02 100644 --- a/files/en-us/web/api/rtcoutboundrtpstreamstats/qualitylimitationdurations/index.md +++ b/files/en-us/web/api/rtcoutboundrtpstreamstats/qualitylimitationdurations/index.md @@ -69,7 +69,3 @@ pc.getStats().then((stats) => { ## Browser compatibility {{Compat}} - -## See also - -- {{domxref("RTCOutboundRtpStreamStats.qualityLimitationDurations")}} diff --git a/files/en-us/web/api/rtcoutboundrtpstreamstats/qualitylimitationreason/index.md b/files/en-us/web/api/rtcoutboundrtpstreamstats/qualitylimitationreason/index.md index 3c818f7eee12a0e..36edef4fc4f88fd 100644 --- a/files/en-us/web/api/rtcoutboundrtpstreamstats/qualitylimitationreason/index.md +++ b/files/en-us/web/api/rtcoutboundrtpstreamstats/qualitylimitationreason/index.md @@ -34,8 +34,6 @@ A string with one of the following values: - `other` - : The quality is primarily limited for a reason other than the above. -## Examples - ## Specifications {{Specifications}} diff --git a/files/en-us/web/api/rtcoutboundrtpstreamstats/retransmittedbytessent/index.md b/files/en-us/web/api/rtcoutboundrtpstreamstats/retransmittedbytessent/index.md index ad5b6c83bfd7b29..f2641b2bdbabd2f 100644 --- a/files/en-us/web/api/rtcoutboundrtpstreamstats/retransmittedbytessent/index.md +++ b/files/en-us/web/api/rtcoutboundrtpstreamstats/retransmittedbytessent/index.md @@ -14,7 +14,7 @@ RTX (Retransmission) is one of several mechanisms that WebRTC uses for retransmi RTX has to be negotiated between the sender and receiver during initial handshake. If RTX has not been negotiated the retransmitted bytes will be sent over the same SSRC; otherwise the bytes are sent on a separate SSRC but are still accounted for in this property. -The retransmitted bytes sent are included in the count reported by {{domxref("RTCOutboundRtpStreamStats .bytesSent", "bytesSent")}}. +The retransmitted bytes sent are included in the count reported by {{domxref("RTCOutboundRtpStreamStats.bytesSent", "bytesSent")}}. ## Value diff --git a/files/en-us/web/api/rtcoutboundrtpstreamstats/scalabilitymode/index.md b/files/en-us/web/api/rtcoutboundrtpstreamstats/scalabilitymode/index.md index 8b63b05d513f316..3828c89bc14d543 100644 --- a/files/en-us/web/api/rtcoutboundrtpstreamstats/scalabilitymode/index.md +++ b/files/en-us/web/api/rtcoutboundrtpstreamstats/scalabilitymode/index.md @@ -13,7 +13,7 @@ browser-compat: api.RTCStatsReport.type_outbound-rtp.scalabilityMode The **`scalabilityMode`** property of the {{domxref("RTCOutboundRtpStreamStats")}} dictionary represents the scalability mode for the RTP stream, if one has been configured. If not configured, the property is undefined. -The mode is used in [Scalable Video Coding (SVC)](https://www.w3.org/TR/webrtc-svc/) to define how define how a video stream may be encoded to allow for adaptation to different network conditions and receiver capabilities. +The mode is used in [Scalable Video Coding (SVC)](https://w3c.github.io/webrtc-svc/) to define how define how a video stream may be encoded to allow for adaptation to different network conditions and receiver capabilities. Different codecs allow for various kinds of scalability, such as providing different resolution, different frame rates, or different quality levels for a particular video. The mode may be configured, for example, by specifying the scalability mode as a parameter option in {{domxref("VideoEncoder.configure()")}}, {{domxref("RTCRtpSender.setParameters()")}}, or {{domxref("RTCPeerConnection.addTransceiver()")}}. diff --git a/files/en-us/web/api/rtcpeerconnection/addstream_event/index.md b/files/en-us/web/api/rtcpeerconnection/addstream_event/index.md index f193f700c90a080..98cc02ca4eb1aee 100644 --- a/files/en-us/web/api/rtcpeerconnection/addstream_event/index.md +++ b/files/en-us/web/api/rtcpeerconnection/addstream_event/index.md @@ -24,10 +24,10 @@ This event is not cancelable and does not bubble. Use the event name in methods like {{domxref("EventTarget.addEventListener", "addEventListener()")}}, or set an event handler property. -```js -addEventListener("addstream", (event) => {}); +```js-nolint +addEventListener("addstream", (event) => { }) -onaddstream = (event) => {}; +onaddstream = (event) => { } ``` ## Event type diff --git a/files/en-us/web/api/rtcpeerconnection/addtrack/index.md b/files/en-us/web/api/rtcpeerconnection/addtrack/index.md index db573e8449db335..f33b2c1ecae5c6a 100644 --- a/files/en-us/web/api/rtcpeerconnection/addtrack/index.md +++ b/files/en-us/web/api/rtcpeerconnection/addtrack/index.md @@ -157,7 +157,7 @@ An `RTCRtpSender` instance is only compatible for reuse if it meets the followin If all of those criteria are met, the sender gets reused, which results in these changes occurring to the existing `RTCRtpSender` and its `RTCRtpTransceiver`: - The `RTCRtpSender`'s {{domxref("RTCRtpSender.track", "track")}} is set to the specified track. -- The sender's set of associated streams is set to the list of streams passed into this method, `stream...`. +- The sender's set of associated streams is set to the list of streams passed into this method, `stream1`, …, `streamN`. - The associated {{domxref("RTCRtpTransceiver")}} has its `currentDirection` updated to indicate that it is sending; if its current value is `"recvonly"`, it becomes `"sendrecv"`, and if its current value is `"inactive"`, it becomes `"sendonly"`. diff --git a/files/en-us/web/api/rtcpeerconnection/cantrickleicecandidates/index.md b/files/en-us/web/api/rtcpeerconnection/cantrickleicecandidates/index.md index 413d6ceb40a6ca1..d134815b22c0dc5 100644 --- a/files/en-us/web/api/rtcpeerconnection/cantrickleicecandidates/index.md +++ b/files/en-us/web/api/rtcpeerconnection/cantrickleicecandidates/index.md @@ -49,7 +49,7 @@ async function newPeer(remoteOffer) { await pc.setLocalDescription(offer); if (pc.canTrickleIceCandidates) return pc.localDescription; const answer = await waitToCompleteIceGathering(pc); - sendAnswerToPeer(answer); //To peer via signaling channel + sendAnswerToPeer(answer); // To peer via signaling channel } // Handle error with try/catch diff --git a/files/en-us/web/api/rtcpeerconnection/connectionstatechange_event/index.md b/files/en-us/web/api/rtcpeerconnection/connectionstatechange_event/index.md index 7150e5504c89149..bbecca72631cc22 100644 --- a/files/en-us/web/api/rtcpeerconnection/connectionstatechange_event/index.md +++ b/files/en-us/web/api/rtcpeerconnection/connectionstatechange_event/index.md @@ -17,10 +17,10 @@ This event is not cancelable and does not bubble. Use the event name in methods like {{domxref("EventTarget.addEventListener", "addEventListener()")}}, or set an event handler property. -```js -addEventListener("connectionstatechange", (event) => {}); +```js-nolint +addEventListener("connectionstatechange", (event) => { }) -onconnectionstatechange = (event) => {}; +onconnectionstatechange = (event) => { } ``` ## Event type diff --git a/files/en-us/web/api/rtcpeerconnection/createoffer/index.md b/files/en-us/web/api/rtcpeerconnection/createoffer/index.md index 7ab3b6dcba66d76..fcfa7bfd61cee4b 100644 --- a/files/en-us/web/api/rtcpeerconnection/createoffer/index.md +++ b/files/en-us/web/api/rtcpeerconnection/createoffer/index.md @@ -33,7 +33,7 @@ createOffer(successCallback, failureCallback, options) // deprecated This will cause the returned offer to have different credentials than those already in place. If you then apply the returned offer, ICE will restart. Specify `false` to keep the same credentials and therefore not restart ICE. - **The default is `false`**. + **The default is `false`**. Instead of using this option, consider calling {{domxref("RTCPeerConnection.restartIce()")}}, which will automatically set this flag the next time `createOffer()` is called. - `offerToReceiveAudio` {{optional_inline}} {{deprecated_inline}} - : Provides additional control over the directionality of audio. For example, it can be used to ensure that audio can be received, regardless if audio is sent or not. - `offerToReceiveVideo` {{optional_inline}} {{deprecated_inline}} diff --git a/files/en-us/web/api/rtcpeerconnection/currentlocaldescription/index.md b/files/en-us/web/api/rtcpeerconnection/currentlocaldescription/index.md index e8e272a87033754..31ec07bb95cae94 100644 --- a/files/en-us/web/api/rtcpeerconnection/currentlocaldescription/index.md +++ b/files/en-us/web/api/rtcpeerconnection/currentlocaldescription/index.md @@ -30,7 +30,7 @@ This example looks at the `currentLocalDescription` and displays an alert contai ```js const pc = new RTCPeerConnection(); -// ... +// … const sd = pc.currentLocalDescription; if (sd) { alert(`Local session: type='${sd.type}'; sdp description='${sd.sdp}'`); diff --git a/files/en-us/web/api/rtcpeerconnection/currentremotedescription/index.md b/files/en-us/web/api/rtcpeerconnection/currentremotedescription/index.md index dff616d3cfca7a7..79cf9aabc2ee131 100644 --- a/files/en-us/web/api/rtcpeerconnection/currentremotedescription/index.md +++ b/files/en-us/web/api/rtcpeerconnection/currentremotedescription/index.md @@ -30,7 +30,7 @@ This example looks at the `currentRemoteDescription` and displays an alert conta ```js const pc = new RTCPeerConnection(); -// ... +// … const sd = pc.currentRemoteDescription; if (sd) { alert(`Local session: type='${sd.type}'; sdp description='${sd.sdp}'`); diff --git a/files/en-us/web/api/rtcpeerconnection/datachannel_event/index.md b/files/en-us/web/api/rtcpeerconnection/datachannel_event/index.md index ba49467b4c464e2..6a888d1b5e87541 100644 --- a/files/en-us/web/api/rtcpeerconnection/datachannel_event/index.md +++ b/files/en-us/web/api/rtcpeerconnection/datachannel_event/index.md @@ -19,10 +19,10 @@ This event is not cancelable and does not bubble. Use the event name in methods like {{domxref("EventTarget.addEventListener", "addEventListener()")}}, or set an event handler property. -```js -addEventListener("datachannel", (event) => {}); +```js-nolint +addEventListener("datachannel", (event) => { }) -ondatachannel = (event) => {}; +ondatachannel = (event) => { } ``` ## Event type diff --git a/files/en-us/web/api/rtcpeerconnection/generatecertificate_static/index.md b/files/en-us/web/api/rtcpeerconnection/generatecertificate_static/index.md index 84c0f4c562e0743..2cb7e6eeb991581 100644 --- a/files/en-us/web/api/rtcpeerconnection/generatecertificate_static/index.md +++ b/files/en-us/web/api/rtcpeerconnection/generatecertificate_static/index.md @@ -19,7 +19,7 @@ RTCPeerConnection.generateCertificate(keygenAlgorithm) ### Parameters - `keygenAlgorithm` - - : A [Web Crypto API](/en-US/docs/Web/API/Web_Crypto_API) {{domxref("AlgorithmIdentifier")}} string or an {{domxref("CryptoKey/algorithm","Algorithm")}} -subclassed object specifying an algorithm to use when creating the certificate's key. + - : A [Web Crypto API](/en-US/docs/Web/API/Web_Crypto_API) algorithm identifier string or object. See {{domxref("SubtleCrypto.generateKey()")}} for details on the format of the object. > **Note:** `generateCertificate()` is a static method, so it is always called on the `RTCPeerConnection` interface itself, not an instance thereof. diff --git a/files/en-us/web/api/rtcpeerconnection/getconfiguration/index.md b/files/en-us/web/api/rtcpeerconnection/getconfiguration/index.md index 8eaaf7deb671528..0f6a8910d563a4e 100644 --- a/files/en-us/web/api/rtcpeerconnection/getconfiguration/index.md +++ b/files/en-us/web/api/rtcpeerconnection/getconfiguration/index.md @@ -52,7 +52,7 @@ if (configuration.certificates?.length === 0) { This example fetches the current configuration of the {{domxref("RTCPeerConnection")}}, then looks to see if it has any certificates set by examining whether or not (a) the configuration has a value for `certificates`, and (b) whether its length is zero. -If it's determined that there are no certificates in place, {{domxref("RTCPeerConnection.generateCertificate_static", "RTCPeerConnection.generateCertificate()")}} is called to create a new certificate; we provide a fulfillment handler which adds a new array containing the one newly-created certificate to the current configuration and passes it to {{domxref("RTCPeerConnect.setConfiguration", "setConfiguration()")}} to add the certificate to the connection. +If it's determined that there are no certificates in place, {{domxref("RTCPeerConnection.generateCertificate_static", "RTCPeerConnection.generateCertificate()")}} is called to create a new certificate; we provide a fulfillment handler which adds a new array containing the one newly-created certificate to the current configuration and passes it to {{domxref("RTCPeerConnection.setConfiguration", "setConfiguration()")}} to add the certificate to the connection. ## Specifications diff --git a/files/en-us/web/api/rtcpeerconnection/icecandidate_event/index.md b/files/en-us/web/api/rtcpeerconnection/icecandidate_event/index.md index b9ea8073b4d4fb3..d49b6ae5ab33335 100644 --- a/files/en-us/web/api/rtcpeerconnection/icecandidate_event/index.md +++ b/files/en-us/web/api/rtcpeerconnection/icecandidate_event/index.md @@ -22,10 +22,10 @@ This event is not cancelable and does not bubble. Use the event name in methods like {{domxref("EventTarget.addEventListener", "addEventListener()")}}, or set an event handler property. -```js -addEventListener("icecandidate", (event) => {}); +```js-nolint +addEventListener("icecandidate", (event) => { }) -onicecandidate = (event) => {}; +onicecandidate = (event) => { } ``` ## Event type diff --git a/files/en-us/web/api/rtcpeerconnection/icecandidateerror_event/index.md b/files/en-us/web/api/rtcpeerconnection/icecandidateerror_event/index.md index d0c4e349574e991..7aa7bf1112f896b 100644 --- a/files/en-us/web/api/rtcpeerconnection/icecandidateerror_event/index.md +++ b/files/en-us/web/api/rtcpeerconnection/icecandidateerror_event/index.md @@ -16,10 +16,10 @@ This event is not cancelable and does not bubble. Use the event name in methods like {{domxref("EventTarget.addEventListener", "addEventListener()")}}, or set an event handler property. -```js -addEventListener("icecandidateerror", (event) => {}); +```js-nolint +addEventListener("icecandidateerror", (event) => { }) -onicecandidateerror = (event) => {}; +onicecandidateerror = (event) => { } ``` ## Event type diff --git a/files/en-us/web/api/rtcpeerconnection/iceconnectionstatechange_event/index.md b/files/en-us/web/api/rtcpeerconnection/iceconnectionstatechange_event/index.md index dce43315989def7..976f15bec2626e1 100644 --- a/files/en-us/web/api/rtcpeerconnection/iceconnectionstatechange_event/index.md +++ b/files/en-us/web/api/rtcpeerconnection/iceconnectionstatechange_event/index.md @@ -19,10 +19,10 @@ This event is not cancelable and does not bubble. Use the event name in methods like {{domxref("EventTarget.addEventListener", "addEventListener()")}}, or set an event handler property. -```js -addEventListener("iceconnectionstatechange", (event) => {}); +```js-nolint +addEventListener("iceconnectionstatechange", (event) => { }) -oniceconnectionstatechange = (event) => {}; +oniceconnectionstatechange = (event) => { } ``` ## Event type diff --git a/files/en-us/web/api/rtcpeerconnection/icegatheringstatechange_event/index.md b/files/en-us/web/api/rtcpeerconnection/icegatheringstatechange_event/index.md index 8f5c3d33ba88b0b..a7b2116710016bc 100644 --- a/files/en-us/web/api/rtcpeerconnection/icegatheringstatechange_event/index.md +++ b/files/en-us/web/api/rtcpeerconnection/icegatheringstatechange_event/index.md @@ -22,10 +22,10 @@ This event is not cancelable and does not bubble. Use the event name in methods like {{domxref("EventTarget.addEventListener", "addEventListener()")}}, or set an event handler property. -```js -addEventListener("icegatheringstatechange", (event) => {}); +```js-nolint +addEventListener("icegatheringstatechange", (event) => { }) -onicegatheringstatechange = (event) => {}; +onicegatheringstatechange = (event) => { } ``` ## Event type diff --git a/files/en-us/web/api/rtcpeerconnection/localdescription/index.md b/files/en-us/web/api/rtcpeerconnection/localdescription/index.md index 0c8bb15a80f5822..7e4f0cca0c4b62a 100644 --- a/files/en-us/web/api/rtcpeerconnection/localdescription/index.md +++ b/files/en-us/web/api/rtcpeerconnection/localdescription/index.md @@ -23,7 +23,7 @@ This example looks at the `localDescription` and displays an alert containing th ```js const pc = new RTCPeerConnection(); -// ... +// … const sd = pc.localDescription; if (sd) { alert(`Local session: type='${sd.type}'; sdp description='${sd.sdp}'`); diff --git a/files/en-us/web/api/rtcpeerconnection/negotiationneeded_event/index.md b/files/en-us/web/api/rtcpeerconnection/negotiationneeded_event/index.md index 142e24cc54e1432..a5f18811235aaf9 100644 --- a/files/en-us/web/api/rtcpeerconnection/negotiationneeded_event/index.md +++ b/files/en-us/web/api/rtcpeerconnection/negotiationneeded_event/index.md @@ -19,10 +19,10 @@ This event is not cancelable and does not bubble. Use the event name in methods like {{domxref("EventTarget.addEventListener", "addEventListener()")}}, or set an event handler property. -```js -addEventListener("negotiationneeded", (event) => {}); +```js-nolint +addEventListener("negotiationneeded", (event) => { }) -onnegotiationneeded = (event) => {}; +onnegotiationneeded = (event) => { } ``` ## Event type diff --git a/files/en-us/web/api/rtcpeerconnection/pendinglocaldescription/index.md b/files/en-us/web/api/rtcpeerconnection/pendinglocaldescription/index.md index 0d445f4e47a515c..8c47165183ee3ec 100644 --- a/files/en-us/web/api/rtcpeerconnection/pendinglocaldescription/index.md +++ b/files/en-us/web/api/rtcpeerconnection/pendinglocaldescription/index.md @@ -25,7 +25,7 @@ This example looks at the `pendingLocalDescription` to determine whether or not ```js const pc = new RTCPeerConnection(); -// ... +// … const sd = pc.pendingLocalDescription; if (sd) { // There's a description change underway! diff --git a/files/en-us/web/api/rtcpeerconnection/pendingremotedescription/index.md b/files/en-us/web/api/rtcpeerconnection/pendingremotedescription/index.md index 2caaafc17ef4bd6..b275740bce6006b 100644 --- a/files/en-us/web/api/rtcpeerconnection/pendingremotedescription/index.md +++ b/files/en-us/web/api/rtcpeerconnection/pendingremotedescription/index.md @@ -26,7 +26,7 @@ This example looks at the `pendingRemoteDescription` to determine whether or not ```js const pc = new RTCPeerConnection(); -// ... +// … const sd = pc.pendingRemoteDescription; if (sd) { // There's a description change underway! diff --git a/files/en-us/web/api/rtcpeerconnection/remotedescription/index.md b/files/en-us/web/api/rtcpeerconnection/remotedescription/index.md index 405fdb61cf8d8ee..65add5fc43b317a 100644 --- a/files/en-us/web/api/rtcpeerconnection/remotedescription/index.md +++ b/files/en-us/web/api/rtcpeerconnection/remotedescription/index.md @@ -26,7 +26,7 @@ This example looks at the `remoteDescription` and displays an alert containing t ```js const pc = new RTCPeerConnection(); -// ... +// … const sd = pc.remoteDescription; if (sd) { alert(`Remote session: type='${sd.type}'; sdp description='${sd.sdp}'`); diff --git a/files/en-us/web/api/rtcpeerconnection/removestream_event/index.md b/files/en-us/web/api/rtcpeerconnection/removestream_event/index.md index 92d3876d9416dfe..b5b57b3a1f89c3b 100644 --- a/files/en-us/web/api/rtcpeerconnection/removestream_event/index.md +++ b/files/en-us/web/api/rtcpeerconnection/removestream_event/index.md @@ -25,10 +25,10 @@ This event is not cancelable and does not bubble. Use the event name in methods like {{domxref("EventTarget.addEventListener", "addEventListener()")}}, or set an event handler property. -```js -addEventListener("removestream", (event) => {}); +```js-nolint +addEventListener("removestream", (event) => { }) -onremovestream = (event) => {}; +onremovestream = (event) => { } ``` ## Event type diff --git a/files/en-us/web/api/rtcpeerconnection/rtcpeerconnection/index.md b/files/en-us/web/api/rtcpeerconnection/rtcpeerconnection/index.md index 82489739f16bbbd..66ce97788365ee6 100644 --- a/files/en-us/web/api/rtcpeerconnection/rtcpeerconnection/index.md +++ b/files/en-us/web/api/rtcpeerconnection/rtcpeerconnection/index.md @@ -25,7 +25,7 @@ new RTCPeerConnection(configuration) - `bundlePolicy` {{optional_inline}} - - : Specifies how to handle negotiation of candidates when the remote peer is not compatible with the [SDP BUNDLE standard](https://webrtcstandards.info/sdp-bundle/). If the remote endpoint is BUNDLE-aware, all media tracks and data channels are bundled onto a single transport at the completion of negotiation, regardless of policy used, and any superfluous transports that were created initially are closed at that point. + - : Specifies how to handle negotiation of candidates when the remote peer is not compatible with the [SDP BUNDLE standard](https://datatracker.ietf.org/doc/rfc8843/). If the remote endpoint is BUNDLE-aware, all media tracks and data channels are bundled onto a single transport at the completion of negotiation, regardless of policy used, and any superfluous transports that were created initially are closed at that point. In technical terms, a BUNDLE lets all media flow between two peers flow across a single **5-tuple**; that is, from a single IP and port on one peer to a single IP and port on the other peer, using the same transport protocol. diff --git a/files/en-us/web/api/rtcpeerconnection/setconfiguration/index.md b/files/en-us/web/api/rtcpeerconnection/setconfiguration/index.md index 3ca3523e1d82874..831ede2f95b4bee 100644 --- a/files/en-us/web/api/rtcpeerconnection/setconfiguration/index.md +++ b/files/en-us/web/api/rtcpeerconnection/setconfiguration/index.md @@ -68,8 +68,10 @@ const restartConfig = { myPeerConnection.setConfiguration(restartConfig); +myPeerConnection.restartIce(); + myPeerConnection - .createOffer({ iceRestart: true }) + .createOffer() // restartIce() causes iceRestart to be set true .then((offer) => myPeerConnection.setLocalDescription(offer)) .then(() => { // send the offer to the other peer using the signaling server @@ -79,7 +81,7 @@ myPeerConnection First, a new object is created, `restartConfig`, specifying the new ICE server and its credentials. This is then passed into `setConfiguration()`. -ICE negotiation is restarted by calling {{domxref("RTCPeerConnection.createOffer()", "createOffer()")}}, specifying `true` as the value of the `iceRestart` option. +ICE negotiation is restarted by calling {{domxref("RTCPeerConnection.restartIce()", "restartIce()")}}, which causes the next offer created to include the new ICE server information. From there, we handle the process as usual, by setting the local description to the returned offer and then sending that offer to the other peer. ## Specifications diff --git a/files/en-us/web/api/rtcpeerconnection/signalingstatechange_event/index.md b/files/en-us/web/api/rtcpeerconnection/signalingstatechange_event/index.md index 0ea609d5d5a95cf..b9c21fb256b1d9b 100644 --- a/files/en-us/web/api/rtcpeerconnection/signalingstatechange_event/index.md +++ b/files/en-us/web/api/rtcpeerconnection/signalingstatechange_event/index.md @@ -16,10 +16,10 @@ This event is not cancelable and does not bubble. Use the event name in methods like {{domxref("EventTarget.addEventListener", "addEventListener()")}}, or set an event handler property. -```js -addEventListener("signalingstatechange", (event) => {}); +```js-nolint +addEventListener("signalingstatechange", (event) => { }) -onsignalingstatechange = (event) => {}; +onsignalingstatechange = (event) => { } ``` ## Event type diff --git a/files/en-us/web/api/rtcpeerconnection/track_event/index.md b/files/en-us/web/api/rtcpeerconnection/track_event/index.md index 0eb90de59ffe1e2..da86e7916242bb0 100644 --- a/files/en-us/web/api/rtcpeerconnection/track_event/index.md +++ b/files/en-us/web/api/rtcpeerconnection/track_event/index.md @@ -18,10 +18,10 @@ This event is not cancellable and does not bubble. Use the event name in methods like {{domxref("EventTarget.addEventListener", "addEventListener()")}}, or set an event handler property. -```js -addEventListener("track", (event) => {}); +```js-nolint +addEventListener("track", (event) => { }) -ontrack = (event) => {}; +ontrack = (event) => { } ``` ## Event type diff --git a/files/en-us/web/api/rtcpeerconnectionstats/index.md b/files/en-us/web/api/rtcpeerconnectionstats/index.md index a6195510eb426de..569313021168d1f 100644 --- a/files/en-us/web/api/rtcpeerconnectionstats/index.md +++ b/files/en-us/web/api/rtcpeerconnectionstats/index.md @@ -12,7 +12,7 @@ The **`RTCPeerConnectionStats`** dictionary of the [WebRTC API](/en-US/docs/Web/ In particular, it provides the number of unique data channels that have been opened, and the number of opened channels that have been closed. This allows the current number of open channels to be calculated. -These statistics can be obtained by iterating the {{domxref("RTCStatsReport")}} returned by {{domxref("RTCPeerConnection.getStats()")}} until you find a report with the [`type`](#type) of `peer-connection`. +These statistics can be obtained by iterating the {{domxref("RTCStatsReport")}} returned by {{domxref("RTCPeerConnection.getStats()")}} until you find a report with the [`type`](/en-US/docs/Web/API/RTCPeerConnectionStats/type) of `peer-connection`. ## Instance properties diff --git a/files/en-us/web/api/rtcremoteinboundrtpstreamstats/index.md b/files/en-us/web/api/rtcremoteinboundrtpstreamstats/index.md index 5e5a6b631c408f2..834c0e240836929 100644 --- a/files/en-us/web/api/rtcremoteinboundrtpstreamstats/index.md +++ b/files/en-us/web/api/rtcremoteinboundrtpstreamstats/index.md @@ -10,7 +10,7 @@ browser-compat: api.RTCStatsReport.type_remote-inbound-rtp The **`RTCRemoteInboundRtpStreamStats`** dictionary of the [WebRTC API](/en-US/docs/Web/API/WebRTC_API) is used to report statistics from the remote endpoint about a particular incoming RTP stream. These will correspond to an outgoing RTP stream at the local end of the {{domxref("RTCPeerConnection")}}. -The statistics can be obtained by iterating the {{domxref("RTCStatsReport")}} returned by {{domxref("RTCPeerConnection.getStats()")}} or {{domxref("RTCRtpReceiver.getStats()")}} until you find a report with the [`type`](#type) of `remote-inbound-rtp`. +The statistics can be obtained by iterating the {{domxref("RTCStatsReport")}} returned by {{domxref("RTCPeerConnection.getStats()")}} or {{domxref("RTCRtpReceiver.getStats()")}} until you find a report with the [`type`](/en-US/docs/Web/API/RTCRemoteInboundRtpStreamStats/type) of `remote-inbound-rtp`. ## Instance properties @@ -26,10 +26,10 @@ The statistics can be obtained by iterating the {{domxref("RTCStatsReport")}} re - : A number that indicates the estimated round trip time (RTT) for this SSRC, in seconds. This property will not exist until valid RTT data has been received. - {{domxref("RTCRemoteInboundRtpStreamStats.roundTripTimeMeasurements", "roundTripTimeMeasurements")}} {{optional_inline}} - - : A positive integer indicating the total number of valid round trip time measurements received for this [synchronization source (SSRC)](#ssrc). + - : A positive integer indicating the total number of valid round trip time measurements received for this [synchronization source (SSRC)](/en-US/docs/Web/API/RTCRemoteInboundRtpStreamStats/ssrc). - {{domxref("RTCRemoteInboundRtpStreamStats.totalRoundTripTime", "totalRoundTripTime")}} {{optional_inline}} - : A number indicating the cumulative sum of all round trip time measurements since the beginning of the session, in seconds. - The average round trip time can be computed by dividing `totalRoundTripTime` by [`roundTripTimeMeasurements`](#roundtriptimemeasurements). + The average round trip time can be computed by dividing `totalRoundTripTime` by [`roundTripTimeMeasurements`](/en-US/docs/Web/API/RTCRemoteInboundRtpStreamStats/roundTripTimeMeasurements). ### Received RTP stream statistics diff --git a/files/en-us/web/api/rtcremoteinboundrtpstreamstats/kind/index.md b/files/en-us/web/api/rtcremoteinboundrtpstreamstats/kind/index.md index 0e302e8faee8010..82c14c3bcee3ba0 100644 --- a/files/en-us/web/api/rtcremoteinboundrtpstreamstats/kind/index.md +++ b/files/en-us/web/api/rtcremoteinboundrtpstreamstats/kind/index.md @@ -11,7 +11,7 @@ browser-compat: api.RTCStatsReport.type_remote-inbound-rtp.kind The **`kind`** property of the {{domxref("RTCRemoteInboundRtpStreamStats")}} dictionary is a string indicating whether the described {{Glossary("RTP")}} stream contains audio or video media. This string will always be the same as the {{domxref("MediaStreamTrack.kind", "kind")}} of the {{domxref("MediaStreamTrack")}} object carried by the stream. -It will also match the media type of the codec associated with this statistics objects (i.e. the MIME type of the associated codec's {{domxref("RTCCodecStats.mimeType")}} property). +It will also match the media type of the codec associated with this statistics objects (i.e., the MIME type of the associated codec's {{domxref("RTCCodecStats.mimeType")}} property). ## Value diff --git a/files/en-us/web/api/rtcremoteinboundrtpstreamstats/roundtriptimemeasurements/index.md b/files/en-us/web/api/rtcremoteinboundrtpstreamstats/roundtriptimemeasurements/index.md index abea23054c0b5cc..0b23f521eb76932 100644 --- a/files/en-us/web/api/rtcremoteinboundrtpstreamstats/roundtriptimemeasurements/index.md +++ b/files/en-us/web/api/rtcremoteinboundrtpstreamstats/roundtriptimemeasurements/index.md @@ -8,7 +8,7 @@ browser-compat: api.RTCStatsReport.type_remote-inbound-rtp.roundTripTimeMeasurem {{APIRef("WebRTC")}} -The **`roundTripTimeMeasurements`** property of the {{domxref("RTCRemoteInboundRtpStreamStats")}} dictionary contains a positive integer value that represents the total number valid round trip time measurements received for this [synchronizing source](#ssrc). +The **`roundTripTimeMeasurements`** property of the {{domxref("RTCRemoteInboundRtpStreamStats")}} dictionary contains a positive integer value that represents the total number valid round trip time measurements received for this [synchronizing source](/en-US/docs/Web/API/RTCRemoteInboundRtpStreamStats/ssrc). The count can be used as a measure of the availability and reliability of round-trip-time measurement data. @@ -16,7 +16,7 @@ The count can be used as a measure of the availability and reliability of round- A positive number indicating the number of valid round trip time measurements. -This is the count of _RTCP Receiver Reports (RR)_ received for this [synchronizing source](#ssrc) that contain a non-zero value for the "delay since last SR (DLSR)" field. +This is the count of _RTCP Receiver Reports (RR)_ received for this [synchronizing source](/en-US/docs/Web/API/RTCRemoteInboundRtpStreamStats/ssrc) that contain a non-zero value for the "delay since last SR (DLSR)" field. ## Specifications diff --git a/files/en-us/web/api/rtcremoteoutboundrtpstreamstats/index.md b/files/en-us/web/api/rtcremoteoutboundrtpstreamstats/index.md index 8ee76caf6251566..bac9b1a1c61fc4e 100644 --- a/files/en-us/web/api/rtcremoteoutboundrtpstreamstats/index.md +++ b/files/en-us/web/api/rtcremoteoutboundrtpstreamstats/index.md @@ -10,7 +10,7 @@ browser-compat: api.RTCStatsReport.type_remote-outbound-rtp The **`RTCRemoteOutboundRtpStreamStats`** dictionary of the [WebRTC API](/en-US/docs/Web/API/WebRTC_API) is used to report statistics from a remote endpoint about its outbound RTP stream. This will correspond to an inbound stream that is currently being received by the local {{domxref("RTCPeerConnection")}} object. -The statistics can be obtained by iterating the {{domxref("RTCStatsReport")}} returned by {{domxref("RTCPeerConnection.getStats()")}} until you find a report with the [`type`](#type) of `remote-outbound-rtp`. +The statistics can be obtained by iterating the {{domxref("RTCStatsReport")}} returned by {{domxref("RTCPeerConnection.getStats()")}} until you find a report with the [`type`](/en-US/docs/Web/API/RTCRemoteOutboundRtpStreamStats/type) of `remote-outbound-rtp`. ## Instance properties @@ -21,12 +21,12 @@ The statistics can be obtained by iterating the {{domxref("RTCStatsReport")}} re - {{domxref("RTCRemoteOutboundRtpStreamStats.remoteTimestamp", "remoteTimestamp")}} {{optional_inline}} - : A {{domxref("DOMHighResTimeStamp")}} specifying the timestamp (on the remote device) at which the statistics in the `RTCRemoteOutboundRtpStreamStats` object were sent by the remote endpoint. This is different from the {{domxref("RTCRemoteOutboundRtpStreamStats.timestamp", "timestamp")}}; it represents the time at which the object's statistics were received or generated by the local endpoint. - `reportsSent` {{optional_inline}} {{experimental_inline}} - - : A positive integer indicating the total number of {{glossary("RTCP")}} Sender Report (SR) blocks sent for this [synchronization source (SSRC)](#ssrc). + - : A positive integer indicating the total number of {{glossary("RTCP")}} Sender Report (SR) blocks sent for this [synchronization source (SSRC)](/en-US/docs/Web/API/RTCRemoteOutboundRtpStreamStats/ssrc). - {{domxref("RTCRemoteOutboundRtpStreamStats.roundTripTimeMeasurements", "roundTripTimeMeasurements")}} {{optional_inline}} {{experimental_inline}} - - : A positive number that represents the total number of valid round trip time measurements received for this [synchronization source (SSRC)](#ssrc). + - : A positive number that represents the total number of valid round trip time measurements received for this [synchronization source (SSRC)](/en-US/docs/Web/API/RTCRemoteOutboundRtpStreamStats/ssrc). - {{domxref("RTCRemoteOutboundRtpStreamStats.totalRoundTripTime", "totalRoundTripTime")}} {{optional_inline}} {{experimental_inline}} - : A number indicating the cumulative sum of all round trip time measurements since the beginning of the session, in seconds. - The average round trip time can be computed by dividing `totalRoundTripTime` by [`roundTripTimeMeasurements`](#roundtriptimemeasurements). + The average round trip time can be computed by dividing `totalRoundTripTime` by [`roundTripTimeMeasurements`](/en-US/docs/Web/API/RTCRemoteOutboundRtpStreamStats/roundTripTimeMeasurements). ### Sent RTP stream statistics diff --git a/files/en-us/web/api/rtcrtpreceiver/getcapabilities_static/index.md b/files/en-us/web/api/rtcrtpreceiver/getcapabilities_static/index.md index 2860a38c219b384..b1a51e9f4e928d5 100644 --- a/files/en-us/web/api/rtcrtpreceiver/getcapabilities_static/index.md +++ b/files/en-us/web/api/rtcrtpreceiver/getcapabilities_static/index.md @@ -188,7 +188,7 @@ function logMediaCapabilities(kind) { log.textContent += "\nCodecs\n"; capabilities.codecs.forEach((codec) => { log.textContent += ` mime type: ${codec.mimeType}\n`; - log.textContent += ` channels: ${codec.channels}\n`; //max channels - e.g. 2 is stereo + log.textContent += ` channels: ${codec.channels}\n`; // max channels - e.g. 2 is stereo log.textContent += ` clockRate: ${codec.clockRate}\n`; // clock rate in Hz log.textContent += ` sdpFmtpLine: ${codec.sdpFmtpLine}\n`; // mime media type and subtype }); diff --git a/files/en-us/web/api/rtcrtpscripttransformer/generatekeyframe/index.md b/files/en-us/web/api/rtcrtpscripttransformer/generatekeyframe/index.md index 6561cdc6a363b8f..8fe5a00efc0d383 100644 --- a/files/en-us/web/api/rtcrtpscripttransformer/generatekeyframe/index.md +++ b/files/en-us/web/api/rtcrtpscripttransformer/generatekeyframe/index.md @@ -58,7 +58,7 @@ The promise returned by the method will resolve just before enqueuing the corres > [!NOTE] > Sending multiple streams (RID) at a time is called "simulcast". -> This feature provides a [middlebox](https://en.wikipedia.org/wiki/Middlebox) with the same stream in multiple levels of video quality, allowing it to manage bandwidth by selectively transmitting appropriate levels to participants and switch resolution rapidly on the fly (i.e. switching to forward low-quality video for everyone except the active speaker). +> This feature provides a [middlebox](https://en.wikipedia.org/wiki/Middlebox) with the same stream in multiple levels of video quality, allowing it to manage bandwidth by selectively transmitting appropriate levels to participants and switch resolution rapidly on the fly (i.e., switching to forward low-quality video for everyone except the active speaker). > The recipient only ever gets one stream, which is why the comparable receiver method {{domxref("RTCRtpScriptTransformer.sendKeyFrameRequest()")}} does not require that an RID is specified. ## Examples diff --git a/files/en-us/web/api/rtcrtpscripttransformer/index.md b/files/en-us/web/api/rtcrtpscripttransformer/index.md index fadc7680fe44a33..c207e497e0de1cb 100644 --- a/files/en-us/web/api/rtcrtpscripttransformer/index.md +++ b/files/en-us/web/api/rtcrtpscripttransformer/index.md @@ -99,10 +99,10 @@ Note that the properties of the object are arbitrary (provided the values can be // Code to instantiate transform and attach them to sender/receiver pipelines. onrtctransform = (event) => { let transform; - if (event.transformer.options.name == "senderTransform") + if (event.transformer.options.name === "senderTransform") transform = createSenderTransform(); // returns a TransformStream (not shown) - else if (event.transformer.options.name == "receiverTransform") + else if (event.transformer.options.name === "receiverTransform") transform = createReceiverTransform(); // returns a TransformStream (not shown) else return; diff --git a/files/en-us/web/api/rtcrtpscripttransformer/options/index.md b/files/en-us/web/api/rtcrtpscripttransformer/options/index.md index eafe8f208a75d9f..bcc3584b7e9ce58 100644 --- a/files/en-us/web/api/rtcrtpscripttransformer/options/index.md +++ b/files/en-us/web/api/rtcrtpscripttransformer/options/index.md @@ -59,9 +59,9 @@ First we implement a handler for the {{domxref("DedicatedWorkerGlobalScope.rtctr addEventListener("rtctransform", (event) => { let transform; // Select a transform based on passed options - if (event.transformer.options.name == "senderTransform") + if (event.transformer.options.name === "senderTransform") transform = createSenderTransform(); // A TransformStream - else if (event.transformer.options.name == "receiverTransform") + else if (event.transformer.options.name === "receiverTransform") transform = createReceiverTransform(); // A TransformStream else return; @@ -97,7 +97,7 @@ The worker can then get the port from the `rtctransform` event fired at the glob let messagePort; addEventListener("rtctransform", (event) => { messagePort = event.transformer.options.port; - // ... other transformer code + // … other transformer code }); ``` @@ -113,10 +113,10 @@ channel.port1.postMessage(encryptionKeyBuffer, [encryptionKeyBuffer]); The worker would listen for the `message` event to get the key: ```js - messagePort.addEventListener("message", (event) => { - const encryptionKeyBuffer = event.data; - // ... Use the encryptionKeyBuffer for encryption or any other purpose - }; +messagePort.addEventListener("message", (event) => { + const encryptionKeyBuffer = event.data; + // … Use the encryptionKeyBuffer for encryption or any other purpose +}); ``` See [message channel](/en-US/docs/Web/API/Channel_Messaging_API) for more information and examples. diff --git a/files/en-us/web/api/rtcrtpscripttransformer/readable/index.md b/files/en-us/web/api/rtcrtpscripttransformer/readable/index.md index dcbf001f97a33f0..d55cdff498d6dc8 100644 --- a/files/en-us/web/api/rtcrtpscripttransformer/readable/index.md +++ b/files/en-us/web/api/rtcrtpscripttransformer/readable/index.md @@ -26,9 +26,9 @@ The following example shows how `readable` is piped through a {{domxref("Transfo addEventListener("rtctransform", (event) => { let transform; // Select a transform based on passed options - if (event.transformer.options.name == "senderTransform") + if (event.transformer.options.name === "senderTransform") transform = createSenderTransform(); // A TransformStream - else if (event.transformer.options.name == "receiverTransform") + else if (event.transformer.options.name === "receiverTransform") transform = createReceiverTransform(); // A TransformStream else return; diff --git a/files/en-us/web/api/rtcrtpscripttransformer/writable/index.md b/files/en-us/web/api/rtcrtpscripttransformer/writable/index.md index b9dc0703bc06a92..3787eb5425ddb30 100644 --- a/files/en-us/web/api/rtcrtpscripttransformer/writable/index.md +++ b/files/en-us/web/api/rtcrtpscripttransformer/writable/index.md @@ -26,9 +26,9 @@ The following example shows how {{domxref("RTCRtpScriptTransformer.readable")}} addEventListener("rtctransform", (event) => { let transform; // Select a transform based on passed options - if (event.transformer.options.name == "senderTransform") + if (event.transformer.options.name === "senderTransform") transform = createSenderTransform(); // A TransformStream - else if (event.transformer.options.name == "receiverTransform") + else if (event.transformer.options.name === "receiverTransform") transform = createReceiverTransform(); // A TransformStream else return; diff --git a/files/en-us/web/api/rtcrtpsender/setparameters/index.md b/files/en-us/web/api/rtcrtpsender/setparameters/index.md index 9968d53603dab04..52d60c2cf30ec2c 100644 --- a/files/en-us/web/api/rtcrtpsender/setparameters/index.md +++ b/files/en-us/web/api/rtcrtpsender/setparameters/index.md @@ -190,11 +190,7 @@ async function setVideoParams(sender, height, bitrate) { const params = sender.getParameters(); // If encodings is null, create it - - if (!params.encodings) { - params.encodings = [{}]; - } - + params.encodings ??= [{}]; params.encodings[0].scaleResolutionDownBy = Math.max(scaleRatio, 1); params.encodings[0].maxBitrate = bitrate; await sender.setParameters(params); diff --git a/files/en-us/web/api/rtcrtptransceiver/setcodecpreferences/index.md b/files/en-us/web/api/rtcrtptransceiver/setcodecpreferences/index.md index 8e3e1c08785763c..52e3f3dd4c8b41c 100644 --- a/files/en-us/web/api/rtcrtptransceiver/setcodecpreferences/index.md +++ b/files/en-us/web/api/rtcrtptransceiver/setcodecpreferences/index.md @@ -19,11 +19,11 @@ This ensures that the array is ordered as required, does not contain any unsuppo The specified set of codecs will be used for all future connections that include this transceiver until this method is called again. -When preparing to open an {{domxref("RTCPeerConnection")}} the codecs should be set using `setCodecParameters()` _before_ calling either {{domxref("RTCPeerConnection.createOffer()")}} or {{domxref("RTCPeerConnection.createAnswer", "createAnswer()")}}, as these initiate the negotiation (and will use codec parameters from the {{Glossary("user agent", "user agent's")}} default configuration by default). +When preparing to open an {{domxref("RTCPeerConnection")}} the codecs should be set using `setCodecPreferences()` _before_ calling either {{domxref("RTCPeerConnection.createOffer()")}} or {{domxref("RTCPeerConnection.createAnswer", "createAnswer()")}}, as these initiate the negotiation (and will use codec parameters from the {{Glossary("user agent", "user agent's")}} default configuration by default). -The codecs can be changed when you have an ongoing communication, but you need to first call `setCodecParameters()` and then kick off a new negotiation. +The codecs can be changed when you have an ongoing communication, but you need to first call `setCodecPreferences()` and then kick off a new negotiation. A WebRTC application will already have code for this in the [`negotiationneeded` event handler](/en-US/docs/Web/API/RTCPeerConnection/negotiationneeded_event). -Note however that at time of writing the event is not automatically fired when you call `setCodecParameters()`, so you will have to call `onnegotiationneeded` yourself. +Note however that at time of writing the event is not automatically fired when you call `setCodecPreferences()`, so you will have to call `onnegotiationneeded` yourself. A guide to codecs supported by WebRTC—and each codec's positive and negative characteristics—can be found in [Codecs used by WebRTC](/en-US/docs/Web/Media/Guides/Formats/WebRTC_codecs). diff --git a/files/en-us/web/api/rtcrtptransceiver/stopped/index.md b/files/en-us/web/api/rtcrtptransceiver/stopped/index.md index 3811782c3063875..43fd0a091d9bcda 100644 --- a/files/en-us/web/api/rtcrtptransceiver/stopped/index.md +++ b/files/en-us/web/api/rtcrtptransceiver/stopped/index.md @@ -24,8 +24,6 @@ A Boolean value which is `true` if the transceiver's {{domxref("RTCRtpTransceiver.receiver", "receiver")}} will no longer receive data. If either or both are still at work, the result is `false`. -## Usage notes - ## Specifications This feature is not part of any current specification. It is no longer on track to become a standard. diff --git a/files/en-us/web/api/rtcsctptransport/index.md b/files/en-us/web/api/rtcsctptransport/index.md index 710ff280beca6f7..6f93c5068666634 100644 --- a/files/en-us/web/api/rtcsctptransport/index.md +++ b/files/en-us/web/api/rtcsctptransport/index.md @@ -11,7 +11,7 @@ The **`RTCSctpTransport`** interface provides information which describes a Stre You don't create `RTCSctpTransport` objects yourself; instead, you get access to the `RTCSctpTransport` for a given `RTCPeerConnection` through its **{{DOMxRef("RTCPeerConnection.sctp", "sctp")}}** property. -Possibly the most useful property on this interface is its [`maxMessageSize`](#rtcsctptransport.maxmessagesize) property, which you can use to determine the upper limit on the size of messages you can send over a data channel on the peer connection. +Possibly the most useful property on this interface is its [`maxMessageSize`](/en-US/docs/Web/API/RTCSctpTransport/maxMessageSize) property, which you can use to determine the upper limit on the size of messages you can send over a data channel on the peer connection. {{InheritanceDiagram}} diff --git a/files/en-us/web/api/rtcsctptransport/statechange_event/index.md b/files/en-us/web/api/rtcsctptransport/statechange_event/index.md index 0d9b4ff226fdb9f..13a6f21d63e1f08 100644 --- a/files/en-us/web/api/rtcsctptransport/statechange_event/index.md +++ b/files/en-us/web/api/rtcsctptransport/statechange_event/index.md @@ -16,10 +16,10 @@ A **`statechange`** event is sent to an {{domxref("RTCSctpTransport")}} to provi Use the event name in methods like {{domxref("EventTarget.addEventListener", "addEventListener()")}}, or set an event handler property. -```js -addEventListener("statechange", (event) => {}); +```js-nolint +addEventListener("statechange", (event) => { }) -onstatechange = (event) => {}; +onstatechange = (event) => { } ``` ## Event type diff --git a/files/en-us/web/api/rtcstatsreport/entries/index.md b/files/en-us/web/api/rtcstatsreport/entries/index.md index 3cec1153d83b291..b66ea184eccb3bb 100644 --- a/files/en-us/web/api/rtcstatsreport/entries/index.md +++ b/files/en-us/web/api/rtcstatsreport/entries/index.md @@ -40,7 +40,7 @@ The properties of statistics objects with the `type` of `outbound-rtp` are logge const stats = await myPeerConnection.getStats(); for (const stat of stats.entries()) { - if (stat.type != "outbound-rtp") continue; + if (stat.type !== "outbound-rtp") continue; Object.keys(stat).forEach((statName) => { console.log(`${statName}: ${report[statName]}`); }); diff --git a/files/en-us/web/api/rtcstatsreport/index.md b/files/en-us/web/api/rtcstatsreport/index.md index 61ffaff40c7885d..9bc5391253c8061 100644 --- a/files/en-us/web/api/rtcstatsreport/index.md +++ b/files/en-us/web/api/rtcstatsreport/index.md @@ -117,7 +117,7 @@ It assumes you already have an `RTCRtpSender` object named "sender". const stats = await sender.getStats(); for (const stat of stats.values()) { - if (stat.type != "outbound-rtp") continue; + if (stat.type !== "outbound-rtp") continue; Object.keys(stat).forEach((statName) => { console.log(`${statName}: ${report[statName]}`); }); diff --git a/files/en-us/web/api/rtcstatsreport/keys/index.md b/files/en-us/web/api/rtcstatsreport/keys/index.md index 3e68d4e06eb5921..b852442139d50fb 100644 --- a/files/en-us/web/api/rtcstatsreport/keys/index.md +++ b/files/en-us/web/api/rtcstatsreport/keys/index.md @@ -39,7 +39,7 @@ const stats = await myPeerConnection.getStats(); for (const id of stats.keys()) { // Get dictionary associated with key (id) const stat = stats.get(id); - if (stat.type != "outbound-rtp") continue; + if (stat.type !== "outbound-rtp") continue; Object.keys(stat).forEach((statName) => { console.log(`${statName}: ${report[statName]}`); }); diff --git a/files/en-us/web/api/rtcstatsreport/values/index.md b/files/en-us/web/api/rtcstatsreport/values/index.md index 9a5c3d9be0eaf56..cf8e2562cad5daa 100644 --- a/files/en-us/web/api/rtcstatsreport/values/index.md +++ b/files/en-us/web/api/rtcstatsreport/values/index.md @@ -36,7 +36,7 @@ The properties of statistics objects with the `type` of `outbound-rtp` are logge const stats = await myPeerConnection.getStats(); for (const stat of stats.values()) { - if (stat.type != "outbound-rtp") continue; + if (stat.type !== "outbound-rtp") continue; Object.keys(stat).forEach((statName) => { console.log(`${statName}: ${report[statName]}`); }); diff --git a/files/en-us/web/api/rtctrackevent/rtctrackevent/index.md b/files/en-us/web/api/rtctrackevent/rtctrackevent/index.md index ab6e1ab59173fa0..d75f19b8cf7960e 100644 --- a/files/en-us/web/api/rtctrackevent/rtctrackevent/index.md +++ b/files/en-us/web/api/rtctrackevent/rtctrackevent/index.md @@ -12,7 +12,7 @@ The **`RTCTrackEvent()`** constructor creates and returns a new {{domxref("RTCTr configured to describe the track which has been added to the {{domxref("RTCPeerConnection")}}. In general, you won't need to use this constructor, as `RTCTrackEvent` -objects are created by WebRTC and delivered to your `RTCPeerConnector`'s +objects are created by WebRTC and delivered to your `RTCPeerConnection`'s {{domxref("RTCPeerConnection.track_event", "ontrack")}} event handler as appropriate. ## Syntax diff --git a/files/en-us/web/api/rtctransformevent/index.md b/files/en-us/web/api/rtctransformevent/index.md index 1ea33a4967b6942..d9b958a364f012b 100644 --- a/files/en-us/web/api/rtctransformevent/index.md +++ b/files/en-us/web/api/rtctransformevent/index.md @@ -44,9 +44,9 @@ The code at the end shows how the stream is piped through the transform stream f addEventListener("rtctransform", (event) => { let transform; // Select a transform based on passed options - if (event.transformer.options.name == "senderTransform") { + if (event.transformer.options.name === "senderTransform") { transform = createSenderTransform(); // A TransformStream (not shown) - } else if (event.transformer.options.name == "receiverTransform") { + } else if (event.transformer.options.name === "receiverTransform") { transform = createReceiverTransform(); // A TransformStream (not shown) } // Pipe frames from the readable to writeable through TransformStream diff --git a/files/en-us/web/api/rtctransportstats/index.md b/files/en-us/web/api/rtctransportstats/index.md index 3b36f88c9a4ca57..e9a9f6208d29303 100644 --- a/files/en-us/web/api/rtctransportstats/index.md +++ b/files/en-us/web/api/rtctransportstats/index.md @@ -14,7 +14,7 @@ If the remote endpoint is aware of this feature, all {{domxref("MediaStreamTrack This is true for current browsers, but if connecting to an older endpoint that is not BUNDLE-aware, then separate transports might be used for different media. The policy to use in the negotiation is configured in the [`RTCPeerConnection` constructor](/en-US/docs/Web/API/RTCPeerConnection/RTCPeerConnection). -These statistics can be obtained by iterating the {{domxref("RTCStatsReport")}} returned by {{domxref("RTCPeerConnection.getStats()")}} until you find a report with the [`type`](#type) of `transport`. +These statistics can be obtained by iterating the {{domxref("RTCStatsReport")}} returned by {{domxref("RTCPeerConnection.getStats()")}} until you find a report with the [`type`](/en-US/docs/Web/API/RTCTransportStats/type) of `transport`. ## Instance properties diff --git a/files/en-us/web/api/rtcvideosourcestats/index.md b/files/en-us/web/api/rtcvideosourcestats/index.md index 2f6317190fe0f91..64fc94bdb651113 100644 --- a/files/en-us/web/api/rtcvideosourcestats/index.md +++ b/files/en-us/web/api/rtcvideosourcestats/index.md @@ -10,7 +10,7 @@ spec-urls: https://w3c.github.io/webrtc-stats/#dom-rtcvideosourcestats The **`RTCVideoSourceStats`** dictionary of the [WebRTC API](/en-US/docs/Web/API/WebRTC_API) provides statistics information about a video track ({{domxref("MediaStreamTrack")}}) that is attached to one or more senders ({{domxref("RTCRtpSender")}}). -These statistics can be obtained by iterating the {{domxref("RTCStatsReport")}} returned by {{domxref("RTCRtpSender.getStats()")}} or {{domxref("RTCPeerConnection.getStats()")}} until you find a report with the [`type`](#type) of `media-source` and a [`kind`](#kind) of `video`. +These statistics can be obtained by iterating the {{domxref("RTCStatsReport")}} returned by {{domxref("RTCRtpSender.getStats()")}} or {{domxref("RTCPeerConnection.getStats()")}} until you find a report with the [`type`](/en-US/docs/Web/API/RTCVideoSourceStats/type) of `media-source` and a [`kind`](/en-US/docs/Web/API/RTCVideoSourceStats/kind) of `video`. > [!NOTE] > For video information about remotely sourced tracks (that are being received), see {{domxref("RTCInboundRtpStreamStats")}}. diff --git a/files/en-us/web/api/scheduler/posttask/index.md b/files/en-us/web/api/scheduler/posttask/index.md index 2e1e0d10881b008..2e5970e612fc300 100644 --- a/files/en-us/web/api/scheduler/posttask/index.md +++ b/files/en-us/web/api/scheduler/posttask/index.md @@ -235,7 +235,7 @@ scheduler .postTask(() => console.log("Task executing"), { signal: abortTaskController.signal, }) - .then((taskResult) => console.log(`${taskResult}`)) //This won't run! + .then((taskResult) => console.log(`${taskResult}`)) // This won't run! .catch((error) => console.error("Error:", error)); // Log the error // Abort the task diff --git a/files/en-us/web/api/screen/change_event/index.md b/files/en-us/web/api/screen/change_event/index.md index eb36815cc25d6ba..6e7592bfc73d298 100644 --- a/files/en-us/web/api/screen/change_event/index.md +++ b/files/en-us/web/api/screen/change_event/index.md @@ -23,10 +23,10 @@ The **`change`** event of the {{domxref("Screen")}} interface is fired on a spec Use the event name in methods like {{domxref("EventTarget.addEventListener", "addEventListener()")}}, or set an event handler property. -```js -addEventListener("change", (event) => {}); +```js-nolint +addEventListener("change", (event) => { }) -onchange = (event) => {}; +onchange = (event) => { } ``` ## Event type diff --git a/files/en-us/web/api/screen/isextended/index.md b/files/en-us/web/api/screen/isextended/index.md index 2944cff0a3df771..c826ed4cfe24122 100644 --- a/files/en-us/web/api/screen/isextended/index.md +++ b/files/en-us/web/api/screen/isextended/index.md @@ -20,7 +20,7 @@ This property is typically accessed via `window.screen.isExtended`, and can be u A boolean value — `true` if the device has multiple screens, and `false` if not. > [!NOTE] -> If a {{httpheader("Permissions-Policy/window-management", "window-management")}} [Permissions-Policy](/en-US/docs/Web/HTTP/Permissions_Policy) is set that blocks use the Window Management API, `isExtended` will always return `false`. +> If a {{httpheader("Permissions-Policy/window-management", "window-management")}} [Permissions-Policy](/en-US/docs/Web/HTTP/Guides/Permissions_Policy) is set that blocks use the Window Management API, `isExtended` will always return `false`. ## Examples diff --git a/files/en-us/web/api/screen/orientationchange_event/index.md b/files/en-us/web/api/screen/orientationchange_event/index.md index 4cc33b955b8706b..a433e0e4627a40a 100644 --- a/files/en-us/web/api/screen/orientationchange_event/index.md +++ b/files/en-us/web/api/screen/orientationchange_event/index.md @@ -17,10 +17,10 @@ The `orientationchange` event fires when the device's orientation has changed. Use the event name in methods like {{domxref("EventTarget.addEventListener", "addEventListener()")}}, or set an event handler property. -```js -addEventListener("orientationchange", (event) => {}); +```js-nolint +addEventListener("orientationchange", (event) => { }) -onorientationchange = (event) => {}; +onorientationchange = (event) => { } ``` ## Event type diff --git a/files/en-us/web/api/screen_capture_api/element_region_capture/index.md b/files/en-us/web/api/screen_capture_api/element_region_capture/index.md index 33bf50db6f524fd..867141d0b4b1be2 100644 --- a/files/en-us/web/api/screen_capture_api/element_region_capture/index.md +++ b/files/en-us/web/api/screen_capture_api/element_region_capture/index.md @@ -29,7 +29,7 @@ In the next section we'll start with a basic Screen Capture API demo to illustra ## Screen Capture API demo -This demo uses the Screen Capture API to capture a window, screen, or tab, and broadcast the stream via a {{htmlelement("video")}} element on the same page. You can see it running live at [Screen Capture API example](https://mdn.github.io/dom-examples/screen-capture-api/basic-screen-capture) (also see the [source code](https://github.com/mdn/dom-examples/tree/main/screen-capture-api/basic-screen-capture)). +This demo uses the Screen Capture API to capture a window, screen, or tab, and broadcast the stream via a {{htmlelement("video")}} element on the same page. You can see it running live at [Screen Capture API example](https://mdn.github.io/dom-examples/screen-capture-api/basic-screen-capture/) (also see the [source code](https://github.com/mdn/dom-examples/tree/main/screen-capture-api/basic-screen-capture)). ### HTML @@ -111,7 +111,7 @@ video, } ``` -Finally, we give the `<video>` element a {{cssxref("max-width")}} of `50%` and a fixed {{cssxref("aspect-ratio")}} of `4/3`. This is to keep the video at a consistent size and avoid too much layout upheaval when the screen capture starts to be broadcast. If we didn't do this, the `<video>` element would grow to the same width as the entire captured area (window or screen), which would affect the layout. It is a [replaced element](/en-US/docs/Web/CSS/Replaced_element), after all, so its [intrinsic size](/en-US/docs/Glossary/Intrinsic_Size) depends on that of its content. +Finally, we give the `<video>` element a {{cssxref("max-width")}} of `50%` and a fixed {{cssxref("aspect-ratio")}} of `4/3`. This is to keep the video at a consistent size and avoid too much layout upheaval when the screen capture starts to be broadcast. If we didn't do this, the `<video>` element would grow to the same width as the entire captured area (window or screen), which would affect the layout. It is a {{ glossary("replaced elements", "replaced element")}}, after all, so its [intrinsic size](/en-US/docs/Glossary/Intrinsic_Size) depends on that of its content. ```css video { @@ -162,9 +162,9 @@ This obviously isn't ideal, and would cause issues in any kind of conferencing a ## The Element Capture API -The Element Capture API restricts the captured region to a specified rendered DOM tree (a selected element and its descendants). In this section we will explore a second demo that is identical to the one presented above, except that it uses Element Capture on top of basic Screen Capture. See this demo running live at [Element Capture API example](https://mdn.github.io/dom-examples/screen-capture-api/element-capture) (also see the [source code](https://github.com/mdn/dom-examples/tree/main/screen-capture-api/element-capture)). +The Element Capture API restricts the captured region to a specified rendered DOM tree (a selected element and its descendants). In this section we will explore a second demo that is identical to the one presented above, except that it uses Element Capture on top of basic Screen Capture. See this demo running live at [Element Capture API example](https://mdn.github.io/dom-examples/screen-capture-api/element-capture/) (also see the [source code](https://github.com/mdn/dom-examples/tree/main/screen-capture-api/element-capture)). -The HTML is identical to the previous example, and the CSS is _nearly_ identical. We'll explain the differences in the JavaScript now, then look at the CSS differences later on, in the [Issues with the Element Capture API](#issues-with-the-element-capture-api) section. +The HTML is identical to the previous example, and the CSS is _nearly_ identical. We'll explain the differences in the JavaScript now, then look at the CSS differences later on, in the [Restrictions on the Element Capture API](#restrictions_on_the_element_capture_api) section. To use the Element Capture API, we additionally grab a reference to a DOM element that we will later use as a **restriction target** — the screen area shown in the stream will be restricted to just that rendered element and its descendants: @@ -195,7 +195,7 @@ async function startCapture() { 4. We apply the restriction target to the track by calling {{domxref("BrowserCaptureMediaStreamTrack.restrictTo()")}} on it, passing it the `restrictionTarget` object. 5. Once all the above is done, we then set the `<video>` element's `srcObject` property value to the stream, to start broadcasting it. -Try running the [Element Capture API example](https://mdn.github.io/dom-examples/screen-capture-api/element-capture) in a [supporting browser](/en-US/docs/Web/API/RestrictionTarget#browser_compatibility) now. You should see that only the demo placeholder is included in the stream, thereby fixing the "hall of mirrors" problem. +Try running the [Element Capture API example](https://mdn.github.io/dom-examples/screen-capture-api/element-capture/) in a [supporting browser](/en-US/docs/Web/API/RestrictionTarget#browser_compatibility) now. You should see that only the demo placeholder is included in the stream, thereby fixing the "hall of mirrors" problem. > [!NOTE] > You can stop the restriction by calling `restrictTo()` again on the same track, passing an argument of `null` to it: @@ -206,7 +206,7 @@ Try running the [Element Capture API example](https://mdn.github.io/dom-examples ### Restrictions on the Element Capture API -To ensure that the element is **eligible for restriction**, that is, it will be captured when chosen as the restriction target element, it must form a [stacking context](/en-US/docs/Web/CSS/CSS_positioned_layout/Understanding_z-index/Stacking_context) and be flattened in 3D space. +To ensure that the element is **eligible for restriction**, that is, it will be captured when chosen as the restriction target element, it must form a [stacking context](/en-US/docs/Web/CSS/CSS_positioned_layout/Stacking_context) and be flattened in 3D space. To handle these restrictions, we've set the following additional CSS rule that targets the demo container element: @@ -229,7 +229,7 @@ For the full list of restrictions on the elements that can be used as restrictio The Region Capture API has a very similar effect to the Element Capture API, except that rather than restricting the captured region to a specific rendered DOM tree, it crops the stream to the area of the current browser tab defined by the bounding box of the target element. Let's look at a demo and then explore the differences between the two in more detail later on. -In this section we will explore a third demo that is identical to the others, except that it uses Region Capture on top of basic Screen Capture. See this demo running live at [Region Capture API example](https://mdn.github.io/dom-examples/screen-capture-api/region-capture) (also see the [source code](https://github.com/mdn/dom-examples/tree/main/screen-capture-api/region-capture)). +In this section we will explore a third demo that is identical to the others, except that it uses Region Capture on top of basic Screen Capture. See this demo running live at [Region Capture API example](https://mdn.github.io/dom-examples/screen-capture-api/region-capture/) (also see the [source code](https://github.com/mdn/dom-examples/tree/main/screen-capture-api/region-capture)). The HTML and CSS are identical to the previous examples. The JavaScript is nearly the same as the Element Capture JavaScript, with a few notable differences that we'll now explain. @@ -261,7 +261,7 @@ async function startCapture() { 3. We apply the crop target to the track by calling {{domxref("BrowserCaptureMediaStreamTrack.cropTo()")}} on it, passing it the `cropTarget` object. 4. Once all the above is done, we then set the `<video>` element's `srcObject` property value to the stream, to start broadcasting it. -Try running the [Region Capture API example](https://mdn.github.io/dom-examples/screen-capture-api/region-capture) in a [supporting browser](/en-US/docs/Web/API/CropTarget#browser_compatibility) now. You should see that only the demo placeholder is included in the stream, which also fixes the "hall of mirrors" problem. +Try running the [Region Capture API example](https://mdn.github.io/dom-examples/screen-capture-api/region-capture/) in a [supporting browser](/en-US/docs/Web/API/CropTarget#browser_compatibility) now. You should see that only the demo placeholder is included in the stream, which also fixes the "hall of mirrors" problem. > [!NOTE] > You can stop the cropping by calling `cropTo()` again on the same track, passing an argument of `null` to it: diff --git a/files/en-us/web/api/screen_capture_api/index.md b/files/en-us/web/api/screen_capture_api/index.md index b2d75dfc7f91f27..e83c5e3d39cd772 100644 --- a/files/en-us/web/api/screen_capture_api/index.md +++ b/files/en-us/web/api/screen_capture_api/index.md @@ -89,7 +89,7 @@ The Screen Capture API adds properties to the following dictionaries defined by ## Permissions Policy validation -{{Glossary("User agent", "User agents")}} that support [Permissions Policy](/en-US/docs/Web/HTTP/Permissions_Policy) (either using the HTTP {{HTTPHeader("Permissions-Policy")}} header or the {{HTMLElement("iframe")}} attribute [`allow`](/en-US/docs/Web/HTML/Element/iframe#allow)) can specify a desire to use the Screen Capture API using the directive `display-capture`: +{{Glossary("User agent", "User agents")}} that support [Permissions Policy](/en-US/docs/Web/HTTP/Guides/Permissions_Policy) (either using the HTTP {{HTTPHeader("Permissions-Policy")}} header or the {{HTMLElement("iframe")}} attribute [`allow`](/en-US/docs/Web/HTML/Reference/Elements/iframe#allow)) can specify a desire to use the Screen Capture API using the directive `display-capture`: ```html <iframe allow="display-capture" src="/some-other-document.html">…</iframe> diff --git a/files/en-us/web/api/screen_capture_api/using_screen_capture/index.md b/files/en-us/web/api/screen_capture_api/using_screen_capture/index.md index 08511c6174177f1..5a1e5a943c69bd1 100644 --- a/files/en-us/web/api/screen_capture_api/using_screen_capture/index.md +++ b/files/en-us/web/api/screen_capture_api/using_screen_capture/index.md @@ -337,7 +337,7 @@ The final product looks like this. If your browser supports Screen Capture API, ## Security -In order to function when [Permissions Policy](/en-US/docs/Web/HTTP/Permissions_Policy) is enabled, you will need the `display-capture` permission. This can be done using the {{HTTPHeader("Permissions-Policy")}} {{Glossary("HTTP")}} header or—if you're using the Screen Capture API in an {{HTMLElement("iframe")}}, the `<iframe>` element's [`allow`](/en-US/docs/Web/HTML/Element/iframe#allow) attribute. +In order to function when [Permissions Policy](/en-US/docs/Web/HTTP/Guides/Permissions_Policy) is enabled, you will need the `display-capture` permission. This can be done using the {{HTTPHeader("Permissions-Policy")}} {{Glossary("HTTP")}} header or—if you're using the Screen Capture API in an {{HTMLElement("iframe")}}, the `<iframe>` element's [`allow`](/en-US/docs/Web/HTML/Reference/Elements/iframe#allow) attribute. For example, this line in the HTTP headers will enable Screen Capture API for the document and any embedded {{HTMLElement("iframe")}} elements that are loaded from the same origin: diff --git a/files/en-us/web/api/screen_wake_lock_api/index.md b/files/en-us/web/api/screen_wake_lock_api/index.md index 9869809393d77bc..3cc4c0d21616a0c 100644 --- a/files/en-us/web/api/screen_wake_lock_api/index.md +++ b/files/en-us/web/api/screen_wake_lock_api/index.md @@ -41,8 +41,8 @@ The Screen Wake Lock API should be used to keep the screen on to benefit usabili - : Returns a {{domxref("WakeLock")}} object instance, from which all other functionality can be accessed. -- [`Permissions-Policy: screen-wake-lock`](/en-US/docs/Web/HTTP/Headers/Permissions-Policy/screen-wake-lock) - - : Access to the API is gated by the [`Permissions-Policy`](/en-US/docs/Web/HTTP/Headers/Permissions-Policy) directive `screen-wake-lock`. +- [`Permissions-Policy: screen-wake-lock`](/en-US/docs/Web/HTTP/Reference/Headers/Permissions-Policy/screen-wake-lock) + - : Access to the API is gated by the [`Permissions-Policy`](/en-US/docs/Web/HTTP/Reference/Headers/Permissions-Policy) directive `screen-wake-lock`. See [Security considerations](#security_considerations) below. ## Examples @@ -125,9 +125,9 @@ You can find the [complete code on GitHub here](https://github.com/mdn/dom-examp ## Security considerations -Access to the Screen Wake Lock API is controlled by the [Permissions Policy](/en-US/docs/Web/HTTP/Permissions_Policy) directive {{HTTPHeader("Permissions-Policy/screen-wake-lock","screen-wake-lock")}}. +Access to the Screen Wake Lock API is controlled by the [Permissions Policy](/en-US/docs/Web/HTTP/Guides/Permissions_Policy) directive {{HTTPHeader("Permissions-Policy/screen-wake-lock","screen-wake-lock")}}. -When using the [Permissions Policy](/en-US/docs/Web/HTTP/Permissions_Policy), the default allowlist for `screen-wake-lock` is `self`. +When using the [Permissions Policy](/en-US/docs/Web/HTTP/Guides/Permissions_Policy), the default allowlist for `screen-wake-lock` is `self`. This allows lock wake usage in same-origin nested frames but prevents third-party content from using locks. Third party usage can be enabled by the server first setting the `Permissions-Policy` header to grant permission a particular third party origin. @@ -138,7 +138,7 @@ Permissions-Policy: screen-wake-lock=(self b.example.com) Then the `allow="screen-wake-lock"` attribute must be added the frame container element for sources from that origin: ```html -<iframe src="https://b.example.com" allow="screen-wake-lock"/></iframe> +<iframe src="https://b.example.com" allow="screen-wake-lock"></iframe> ``` Browsers may also block the screen lock in a particular document for an implementation specific reason, such as a user or platform setting. diff --git a/files/en-us/web/api/screendetailed/devicepixelratio/index.md b/files/en-us/web/api/screendetailed/devicepixelratio/index.md index d8ecbea9b9205ed..6f142831c3e0c1d 100644 --- a/files/en-us/web/api/screendetailed/devicepixelratio/index.md +++ b/files/en-us/web/api/screendetailed/devicepixelratio/index.md @@ -16,7 +16,7 @@ The **`devicePixelRatio`** read-only property of the This is the same as the value returned by {{domxref("Window.devicePixelRatio")}}, except that `Window.devicePixelRatio`: - always returns the device pixel ratio for the {{domxref("ScreenDetails.currentScreen", "current screen", "", "nocode")}}. -- also includes scaling of the window itself, i.e. page zoom (at least on some browser implementations). +- also includes scaling of the window itself, i.e., page zoom (at least on some browser implementations). ## Value diff --git a/files/en-us/web/api/screendetails/currentscreenchange_event/index.md b/files/en-us/web/api/screendetails/currentscreenchange_event/index.md index b85b3ce04ebde36..49ed01c972c6677 100644 --- a/files/en-us/web/api/screendetails/currentscreenchange_event/index.md +++ b/files/en-us/web/api/screendetails/currentscreenchange_event/index.md @@ -32,10 +32,10 @@ The **`currentscreenchange`** event of the {{domxref("ScreenDetails")}} interfac Use the event name in methods like {{domxref("EventTarget.addEventListener", "addEventListener()")}}, or set an event handler property. -```js -addEventListener("currentscreenchange", (event) => {}); +```js-nolint +addEventListener("currentscreenchange", (event) => { }) -oncurrentscreenchange = (event) => {}; +oncurrentscreenchange = (event) => { } ``` ## Event type diff --git a/files/en-us/web/api/screendetails/screenschange_event/index.md b/files/en-us/web/api/screendetails/screenschange_event/index.md index 43157dccf5ab68e..eb5baa97933772a 100644 --- a/files/en-us/web/api/screendetails/screenschange_event/index.md +++ b/files/en-us/web/api/screendetails/screenschange_event/index.md @@ -16,10 +16,10 @@ The **`screenschange`** event of the {{domxref("ScreenDetails")}} interface is f Use the event name in methods like {{domxref("EventTarget.addEventListener", "addEventListener()")}}, or set an event handler property. -```js -addEventListener("screenschange", (event) => {}); +```js-nolint +addEventListener("screenschange", (event) => { }) -onscreenschange = (event) => {}; +onscreenschange = (event) => { } ``` ## Event type diff --git a/files/en-us/web/api/screenorientation/change_event/index.md b/files/en-us/web/api/screenorientation/change_event/index.md index a07e3fa85d37482..b9e0bdaa0666115 100644 --- a/files/en-us/web/api/screenorientation/change_event/index.md +++ b/files/en-us/web/api/screenorientation/change_event/index.md @@ -14,10 +14,10 @@ The **`change`** event of the {{domxref("ScreenOrientation")}} interface fires w Use the event name in methods like {{domxref("EventTarget.addEventListener", "addEventListener()")}}, or set an event handler property. -```js -addEventListener("change", (event) => {}); +```js-nolint +addEventListener("change", (event) => { }) -onchange = (event) => {}; +onchange = (event) => { } ``` ## Event type diff --git a/files/en-us/web/api/scriptprocessornode/audioprocess_event/index.md b/files/en-us/web/api/scriptprocessornode/audioprocess_event/index.md index 9c885da96705ad3..22ee9ffeaa09808 100644 --- a/files/en-us/web/api/scriptprocessornode/audioprocess_event/index.md +++ b/files/en-us/web/api/scriptprocessornode/audioprocess_event/index.md @@ -10,13 +10,23 @@ browser-compat: api.ScriptProcessorNode.audioprocess_event {{APIRef("Web Audio API")}}{{Deprecated_Header}} -The `audioprocess` event of the {{domxref("ScriptProcessorNode")}} interface is fired when an input buffer of a script processor is ready to be processed. +The **`audioprocess`** event of the {{domxref("ScriptProcessorNode")}} interface is fired when an input buffer of a script processor is ready to be processed. > [!NOTE] > This feature was replaced by [AudioWorklets](/en-US/docs/Web/API/AudioWorklet) and the {{domxref("AudioWorkletNode")}} interface. This event is not cancelable and does not bubble. +## Syntax + +Use the event name in methods like {{domxref("EventTarget.addEventListener", "addEventListener()")}}, or set an event handler property. + +```js-nolint +addEventListener("audioprocess", (event) => { }) + +onaudioprocess = (event) => { } +``` + ## Event type An {{domxref("AudioProcessingEvent")}}. Inherits from {{domxref("Event")}}. @@ -72,15 +82,13 @@ You could also set up the event handler using the `onaudioprocess` property: ```js scriptNode.onaudioprocess = (audioProcessingEvent) => { - // ... + // … }; ``` ## Specifications -Since the August 29, 2014, [Web Audio API specification](https://www.w3.org/TR/webaudio/#ScriptProcessorNode) publication, this feature has been deprecated. It is no longer on track to become a standard. - -It was replaced by [AudioWorklets](/en-US/docs/Web/API/AudioWorklet) and the {{domxref("AudioWorkletNode")}} interface. +{{Specifications}} ## Browser compatibility diff --git a/files/en-us/web/api/scriptprocessornode/index.md b/files/en-us/web/api/scriptprocessornode/index.md index b102b1fa450cc46..06bac6a31e5838b 100644 --- a/files/en-us/web/api/scriptprocessornode/index.md +++ b/files/en-us/web/api/scriptprocessornode/index.md @@ -74,9 +74,7 @@ See [`BaseAudioContext.createScriptProcessor()`](/en-US/docs/Web/API/BaseAudioCo ## Specifications -Since the August 29, 2014 [Web Audio API specification](https://www.w3.org/TR/webaudio/#ScriptProcessorNode) publication, this feature has been deprecated. It is no longer on track to become a standard. - -It was replaced by [AudioWorklets](/en-US/docs/Web/API/AudioWorklet) and the {{domxref("AudioWorkletNode")}} interface. +{{Specifications}} ## Browser compatibility diff --git a/files/en-us/web/api/securepaymentconfirmationrequest/index.md b/files/en-us/web/api/securepaymentconfirmationrequest/index.md index 9ff8fb73f6ddc6f..40098a9cc5e6919 100644 --- a/files/en-us/web/api/securepaymentconfirmationrequest/index.md +++ b/files/en-us/web/api/securepaymentconfirmationrequest/index.md @@ -16,7 +16,7 @@ An instance of this dictionary must be passed into the {{domxref("PaymentRequest - `challenge` - : An {{jsxref("ArrayBuffer")}}, {{jsxref("TypedArray")}}, or {{jsxref("DataView")}} provided by the relying party's server and used as a [cryptographic challenge](https://en.wikipedia.org/wiki/Challenge%E2%80%93response_authentication). This value will be signed by the authenticator and the signature will be sent back as part of {{domxref("AuthenticatorAttestationResponse.attestationObject")}}. This helps prevent replay attacks. - `credentialIds` - - : A list of {{jsxref("ArrayBuffer")}}, {{jsxref("TypedArray")}}, or {{jsxref("DataView")}}. These [Credential IDs](https://www.w3.org/TR/webauthn-2/#credential-id) represent Web Authentication credentials that have been registered with the relying party for authenticating during a payment with the associated `instrument`. + - : A list of {{jsxref("ArrayBuffer")}}, {{jsxref("TypedArray")}}, or {{jsxref("DataView")}}. These [Credential IDs](https://w3c.github.io/webauthn/#credential-id) represent Web Authentication credentials that have been registered with the relying party for authenticating during a payment with the associated `instrument`. - `extensions` {{optional_inline}} - : Any [WebAuthn extensions](/en-US/docs/Web/API/Web_Authentication_API/WebAuthn_extensions) that should be used for the passed credential(s). The caller does not need to specify the [`payment` extension](/en-US/docs/Web/API/Web_Authentication_API/WebAuthn_extensions#payment); this is added automatically. - `instrument` @@ -28,7 +28,7 @@ An instance of this dictionary must be passed into the {{domxref("PaymentRequest - `iconMustBeShown` {{optional_inline}} - : A boolean value indicating whether the icon must be successfully fetched and shown for the request to succeed. Defaults to `true`. - `locale` {{optional_inline}} - - : An optional list of well-formed {{RFC(5646, "Tags for Identifying Languages (also known as BCP 47)")}} language tags, in descending order of priority, that identify the local preferences of the website. That is, this represents a language priority list {{RFC(4647, "Matching of Language Tags")}}, which the user agent can use to perform [language negotiation](/en-US/docs/Web/HTTP/Content_negotiation) and locale-affected formatting with the caller. + - : An optional list of well-formed {{RFC(5646, "Tags for Identifying Languages (also known as BCP 47)")}} language tags, in descending order of priority, that identify the local preferences of the website. That is, this represents a language priority list {{RFC(4647, "Matching of Language Tags")}}, which the user agent can use to perform [language negotiation](/en-US/docs/Web/HTTP/Guides/Content_negotiation) and locale-affected formatting with the caller. > [!NOTE] > The locale is distinct from language or direction metadata associated with specific input members, in that it represents the caller's requested localized experience rather than assertion about a specific string value. See [SPC internationalization Considerations](https://w3c.github.io/secure-payment-confirmation/#sctn-i18n-considerations) for more discussion. - `payeeName` {{optional_inline}} diff --git a/files/en-us/web/api/securitypolicyviolationevent/blockeduri/index.md b/files/en-us/web/api/securitypolicyviolationevent/blockeduri/index.md index ba79788f3fb776a..ec383b71214c679 100644 --- a/files/en-us/web/api/securitypolicyviolationevent/blockeduri/index.md +++ b/files/en-us/web/api/securitypolicyviolationevent/blockeduri/index.md @@ -8,7 +8,7 @@ browser-compat: api.SecurityPolicyViolationEvent.blockedURI {{APIRef("Reporting API")}}{{AvailableInWorkers}} -The **`blockedURI`** read-only property of the {{domxref("SecurityPolicyViolationEvent")}} interface is a string representing the URI of the resource that was blocked because it violates a [Content Security Policy (CSP)](/en-US/docs/Web/HTTP/CSP). +The **`blockedURI`** read-only property of the {{domxref("SecurityPolicyViolationEvent")}} interface is a string representing the URI of the resource that was blocked because it violates a [Content Security Policy (CSP)](/en-US/docs/Web/HTTP/Guides/CSP). ## Value diff --git a/files/en-us/web/api/securitypolicyviolationevent/columnnumber/index.md b/files/en-us/web/api/securitypolicyviolationevent/columnnumber/index.md index 284123415b30a75..f6911ca9ab12d68 100644 --- a/files/en-us/web/api/securitypolicyviolationevent/columnnumber/index.md +++ b/files/en-us/web/api/securitypolicyviolationevent/columnnumber/index.md @@ -8,7 +8,7 @@ browser-compat: api.SecurityPolicyViolationEvent.columnNumber {{APIRef("Reporting API")}}{{AvailableInWorkers}} -The **`columnNumber`** read-only property of the {{domxref("SecurityPolicyViolationEvent")}} interface is the column number in the document or worker script at which the [Content Security Policy (CSP)](/en-US/docs/Web/HTTP/CSP) violation occurred. +The **`columnNumber`** read-only property of the {{domxref("SecurityPolicyViolationEvent")}} interface is the column number in the document or worker script at which the [Content Security Policy (CSP)](/en-US/docs/Web/HTTP/Guides/CSP) violation occurred. ## Value diff --git a/files/en-us/web/api/securitypolicyviolationevent/disposition/index.md b/files/en-us/web/api/securitypolicyviolationevent/disposition/index.md index e2b5bd80f38c484..b29e38e9c717431 100644 --- a/files/en-us/web/api/securitypolicyviolationevent/disposition/index.md +++ b/files/en-us/web/api/securitypolicyviolationevent/disposition/index.md @@ -8,7 +8,7 @@ browser-compat: api.SecurityPolicyViolationEvent.disposition {{APIRef("Reporting API")}}{{AvailableInWorkers}} -The **`disposition`** read-only property of the {{domxref("SecurityPolicyViolationEvent")}} interface indicates how the violated [Content Security Policy (CSP)](/en-US/docs/Web/HTTP/CSP) is configured to be treated by the user agent. +The **`disposition`** read-only property of the {{domxref("SecurityPolicyViolationEvent")}} interface indicates how the violated [Content Security Policy (CSP)](/en-US/docs/Web/HTTP/Guides/CSP) is configured to be treated by the user agent. ## Value diff --git a/files/en-us/web/api/securitypolicyviolationevent/documenturi/index.md b/files/en-us/web/api/securitypolicyviolationevent/documenturi/index.md index 6030baee8540eaa..7e9dfe1b5c0a558 100644 --- a/files/en-us/web/api/securitypolicyviolationevent/documenturi/index.md +++ b/files/en-us/web/api/securitypolicyviolationevent/documenturi/index.md @@ -8,7 +8,7 @@ browser-compat: api.SecurityPolicyViolationEvent.documentURI {{APIRef("Reporting API")}}{{AvailableInWorkers}} -The **`documentURI`** read-only property of the {{domxref("SecurityPolicyViolationEvent")}} interface is a string representing the URI of the document or worker in which the [Content Security Policy (CSP)](/en-US/docs/Web/HTTP/CSP) violation occurred. +The **`documentURI`** read-only property of the {{domxref("SecurityPolicyViolationEvent")}} interface is a string representing the URI of the document or worker in which the [Content Security Policy (CSP)](/en-US/docs/Web/HTTP/Guides/CSP) violation occurred. ## Value diff --git a/files/en-us/web/api/securitypolicyviolationevent/effectivedirective/index.md b/files/en-us/web/api/securitypolicyviolationevent/effectivedirective/index.md index 9a3c246ee6379fe..e1d53e3be7ec068 100644 --- a/files/en-us/web/api/securitypolicyviolationevent/effectivedirective/index.md +++ b/files/en-us/web/api/securitypolicyviolationevent/effectivedirective/index.md @@ -8,13 +8,13 @@ browser-compat: api.SecurityPolicyViolationEvent.effectiveDirective {{APIRef("Reporting API")}}{{AvailableInWorkers}} -The **`effectiveDirective`** read-only property of the {{domxref("SecurityPolicyViolationEvent")}} interface is a string representing the [Content Security Policy (CSP)](/en-US/docs/Web/HTTP/CSP) directive that was violated. +The **`effectiveDirective`** read-only property of the {{domxref("SecurityPolicyViolationEvent")}} interface is a string representing the [Content Security Policy (CSP)](/en-US/docs/Web/HTTP/Guides/CSP) directive that was violated. This supersedes {{domxref("SecurityPolicyViolationEvent.violatedDirective")}}, its historical alias. ## Value -A string representing the particular [`Content-Security-Policy` directive](/en-US/docs/Web/HTTP/Headers/Content-Security-Policy#directives) that was violated. +A string representing the particular [`Content-Security-Policy` directive](/en-US/docs/Web/HTTP/Reference/Headers/Content-Security-Policy#directives) that was violated. ## Examples diff --git a/files/en-us/web/api/securitypolicyviolationevent/index.md b/files/en-us/web/api/securitypolicyviolationevent/index.md index e3de26178e769ba..fc2e74812d3df05 100644 --- a/files/en-us/web/api/securitypolicyviolationevent/index.md +++ b/files/en-us/web/api/securitypolicyviolationevent/index.md @@ -7,7 +7,7 @@ browser-compat: api.SecurityPolicyViolationEvent {{APIRef("Reporting API")}}{{AvailableInWorkers}} -The **`SecurityPolicyViolationEvent`** interface inherits from {{domxref("Event")}}, and represents the event object of a `securitypolicyviolation` event sent on an {{domxref("Element/securitypolicyviolation_event", "Element")}}, {{domxref("Document/securitypolicyviolation_event", "Document")}}, or {{domxref("WorkerGlobalScope/securitypolicyviolation_event", "worker","","nocode")}} when its [Content Security Policy (CSP)](/en-US/docs/Web/HTTP/CSP) is violated. +The **`SecurityPolicyViolationEvent`** interface inherits from {{domxref("Event")}}, and represents the event object of a `securitypolicyviolation` event sent on an {{domxref("Element/securitypolicyviolation_event", "Element")}}, {{domxref("Document/securitypolicyviolation_event", "Document")}}, or {{domxref("WorkerGlobalScope/securitypolicyviolation_event", "worker","","nocode")}} when its [Content Security Policy (CSP)](/en-US/docs/Web/HTTP/Guides/CSP) is violated. {{InheritanceDiagram}} @@ -43,7 +43,7 @@ The **`SecurityPolicyViolationEvent`** interface inherits from {{domxref("Event" - : A number representing the HTTP status code of the document or worker in which the violation occurred. - {{domxref("SecurityPolicyViolationEvent.violatedDirective")}} {{ReadOnlyInline}} - : A string representing the directive that was violated. - This is a historical alias of [`effectiveDirective`](#effectivedirective). + This is a historical alias of [`effectiveDirective`](/en-US/docs/Web/API/SecurityPolicyViolationEvent/effectiveDirective). ## Examples @@ -65,7 +65,7 @@ document.addEventListener("securitypolicyviolation", (e) => { ## See also -- HTTP [Content Security Policy (CSP)](/en-US/docs/Web/HTTP/CSP) +- HTTP [Content Security Policy (CSP)](/en-US/docs/Web/HTTP/Guides/CSP) - {{domxref("CSPViolationReportBody")}} - The {{domxref("Element/securitypolicyviolation_event", "securitypolicyviolation")}} event of the {{domxref("Element")}} interface - The {{domxref("Document/securitypolicyviolation_event", "securitypolicyviolation")}} event of the {{domxref("Document")}} interface diff --git a/files/en-us/web/api/securitypolicyviolationevent/linenumber/index.md b/files/en-us/web/api/securitypolicyviolationevent/linenumber/index.md index b9f41198d60f59c..d4b7f9f84ade18f 100644 --- a/files/en-us/web/api/securitypolicyviolationevent/linenumber/index.md +++ b/files/en-us/web/api/securitypolicyviolationevent/linenumber/index.md @@ -8,7 +8,7 @@ browser-compat: api.SecurityPolicyViolationEvent.lineNumber {{APIRef("Reporting API")}}{{AvailableInWorkers}} -The **`lineNumber`** read-only property of the {{domxref("SecurityPolicyViolationEvent")}} interface is the line number in the document or worker script at which the [Content Security Policy (CSP)](/en-US/docs/Web/HTTP/CSP) violation occurred. +The **`lineNumber`** read-only property of the {{domxref("SecurityPolicyViolationEvent")}} interface is the line number in the document or worker script at which the [Content Security Policy (CSP)](/en-US/docs/Web/HTTP/Guides/CSP) violation occurred. ## Value diff --git a/files/en-us/web/api/securitypolicyviolationevent/originalpolicy/index.md b/files/en-us/web/api/securitypolicyviolationevent/originalpolicy/index.md index 21addd6be3f1947..8c8be2f92d51ba3 100644 --- a/files/en-us/web/api/securitypolicyviolationevent/originalpolicy/index.md +++ b/files/en-us/web/api/securitypolicyviolationevent/originalpolicy/index.md @@ -8,13 +8,13 @@ browser-compat: api.SecurityPolicyViolationEvent.originalPolicy {{APIRef("Reporting API")}}{{AvailableInWorkers}} -The **`originalPolicy`** read-only property of the {{domxref("SecurityPolicyViolationEvent")}} interface is a string containing the [Content Security Policy (CSP)](/en-US/docs/Web/HTTP/CSP) whose enforcement uncovered the violation. +The **`originalPolicy`** read-only property of the {{domxref("SecurityPolicyViolationEvent")}} interface is a string containing the [Content Security Policy (CSP)](/en-US/docs/Web/HTTP/Guides/CSP) whose enforcement uncovered the violation. ## Value A string representing the policy whose enforcement uncovered the violation. -This is the string in the {{HTTPHeader("Content-Security-Policy")}} HTTP header that contains the list of [directives](/en-US/docs/Web/HTTP/Headers/Content-Security-Policy#directives) and their values that make the CSP policy. +This is the string in the {{HTTPHeader("Content-Security-Policy")}} HTTP header that contains the list of [directives](/en-US/docs/Web/HTTP/Reference/Headers/Content-Security-Policy#directives) and their values that make the CSP policy. ## Examples diff --git a/files/en-us/web/api/securitypolicyviolationevent/referrer/index.md b/files/en-us/web/api/securitypolicyviolationevent/referrer/index.md index 81c13872c96b083..15cbaa7e0ef4d2a 100644 --- a/files/en-us/web/api/securitypolicyviolationevent/referrer/index.md +++ b/files/en-us/web/api/securitypolicyviolationevent/referrer/index.md @@ -8,7 +8,7 @@ browser-compat: api.SecurityPolicyViolationEvent.referrer {{APIRef("Reporting API")}}{{AvailableInWorkers}} -The **`referrer`** read-only property of the {{domxref("SecurityPolicyViolationEvent")}} interface is a string representing the referrer for the resources whose [Content Security Policy (CSP)](/en-US/docs/Web/HTTP/CSP) was violated. +The **`referrer`** read-only property of the {{domxref("SecurityPolicyViolationEvent")}} interface is a string representing the referrer for the resources whose [Content Security Policy (CSP)](/en-US/docs/Web/HTTP/Guides/CSP) was violated. This will be a URL or `null`. ## Value diff --git a/files/en-us/web/api/securitypolicyviolationevent/sample/index.md b/files/en-us/web/api/securitypolicyviolationevent/sample/index.md index 5a314cefa55b440..9aa0ee418789444 100644 --- a/files/en-us/web/api/securitypolicyviolationevent/sample/index.md +++ b/files/en-us/web/api/securitypolicyviolationevent/sample/index.md @@ -8,12 +8,13 @@ browser-compat: api.SecurityPolicyViolationEvent.sample {{APIRef("Reporting API")}}{{AvailableInWorkers}} -The **`sample`** read-only property of the {{domxref("SecurityPolicyViolationEvent")}} interface is a string representing a sample of the resource that caused the [Content Security Policy (CSP)](/en-US/docs/Web/HTTP/CSP) violation. +The **`sample`** read-only property of the {{domxref("SecurityPolicyViolationEvent")}} interface is a string representing a sample of the resource that caused the [Content Security Policy (CSP)](/en-US/docs/Web/HTTP/Guides/CSP) violation. -This is only [`script-src*`](/en-US/docs/Web/HTTP/Headers/Content-Security-Policy#script-src) and [`style-src*`](/en-US/docs/Web/HTTP/Headers/Content-Security-Policy#style-src) violations, when the corresponding `Content-Security-Policy` directive contains the [`'report-sample'`](/en-US/docs/Web/HTTP/Headers/Content-Security-Policy#report-sample) keyword. +This is only [`script-src*`](/en-US/docs/Web/HTTP/Reference/Headers/Content-Security-Policy/script-src) and [`style-src*`](/en-US/docs/Web/HTTP/Reference/Headers/Content-Security-Policy/style-src) violations, when the corresponding `Content-Security-Policy` directive contains the [`'report-sample'`](/en-US/docs/Web/HTTP/Reference/Headers/Content-Security-Policy#report-sample) keyword. In addition, this will only be populated if the resource is an inline script, event handler, or style — external resources causing a violation will not generate a sample. -> [!NOTE] Violation reports should be considered attacker-controlled data. +> [!NOTE] +> Violation reports should be considered attacker-controlled data. > The content of this field should be sanitized before storing or rendering. ## Value diff --git a/files/en-us/web/api/securitypolicyviolationevent/securitypolicyviolationevent/index.md b/files/en-us/web/api/securitypolicyviolationevent/securitypolicyviolationevent/index.md index 3ccfe36357445ac..4edc6e2f869f5eb 100644 --- a/files/en-us/web/api/securitypolicyviolationevent/securitypolicyviolationevent/index.md +++ b/files/en-us/web/api/securitypolicyviolationevent/securitypolicyviolationevent/index.md @@ -77,4 +77,4 @@ let SPVEvt = new SecurityPolicyViolationEvent("foo", { ## See also -- [Content Security Policy (CSP)](/en-US/docs/Web/HTTP/CSP) +- [Content Security Policy (CSP)](/en-US/docs/Web/HTTP/Guides/CSP) diff --git a/files/en-us/web/api/securitypolicyviolationevent/sourcefile/index.md b/files/en-us/web/api/securitypolicyviolationevent/sourcefile/index.md index a6fbec6c53f85c5..95b7ccd281dd199 100644 --- a/files/en-us/web/api/securitypolicyviolationevent/sourcefile/index.md +++ b/files/en-us/web/api/securitypolicyviolationevent/sourcefile/index.md @@ -8,7 +8,7 @@ browser-compat: api.SecurityPolicyViolationEvent.sourceFile {{APIRef("Reporting API")}}{{AvailableInWorkers}} -The **`sourceFile`** read-only property of the {{domxref("SecurityPolicyViolationEvent")}} interface is a string representing the URL of the script in which the [Content Security Policy (CSP)](/en-US/docs/Web/HTTP/CSP) violation occurred. +The **`sourceFile`** read-only property of the {{domxref("SecurityPolicyViolationEvent")}} interface is a string representing the URL of the script in which the [Content Security Policy (CSP)](/en-US/docs/Web/HTTP/Guides/CSP) violation occurred. ## Value diff --git a/files/en-us/web/api/securitypolicyviolationevent/statuscode/index.md b/files/en-us/web/api/securitypolicyviolationevent/statuscode/index.md index bc581a2ec829d5c..128593f2e41c220 100644 --- a/files/en-us/web/api/securitypolicyviolationevent/statuscode/index.md +++ b/files/en-us/web/api/securitypolicyviolationevent/statuscode/index.md @@ -8,7 +8,7 @@ browser-compat: api.SecurityPolicyViolationEvent.statusCode {{APIRef("Reporting API")}}{{AvailableInWorkers}} -The **`statusCode`** read-only property of the {{domxref("SecurityPolicyViolationEvent")}} interface is a number representing the HTTP status code of the window or worker in which the [Content Security Policy (CSP)](/en-US/docs/Web/HTTP/CSP) violation occurred. +The **`statusCode`** read-only property of the {{domxref("SecurityPolicyViolationEvent")}} interface is a number representing the HTTP status code of the window or worker in which the [Content Security Policy (CSP)](/en-US/docs/Web/HTTP/Guides/CSP) violation occurred. ## Value diff --git a/files/en-us/web/api/securitypolicyviolationevent/violateddirective/index.md b/files/en-us/web/api/securitypolicyviolationevent/violateddirective/index.md index 4e5be268ee805c6..74cc6ae3e2b1c38 100644 --- a/files/en-us/web/api/securitypolicyviolationevent/violateddirective/index.md +++ b/files/en-us/web/api/securitypolicyviolationevent/violateddirective/index.md @@ -8,13 +8,13 @@ browser-compat: api.SecurityPolicyViolationEvent.violatedDirective {{APIRef("Reporting API")}}{{AvailableInWorkers}} -The **`violatedDirective`** read-only property of the {{domxref("SecurityPolicyViolationEvent")}} interface is a string representing the [Content Security Policy (CSP)](/en-US/docs/Web/HTTP/CSP) directive that was violated. +The **`violatedDirective`** read-only property of the {{domxref("SecurityPolicyViolationEvent")}} interface is a string representing the [Content Security Policy (CSP)](/en-US/docs/Web/HTTP/Guides/CSP) directive that was violated. This is a historical alias of {{domxref("SecurityPolicyViolationEvent.effectiveDirective")}}, and has the same value. ## Value -A string representing the [`Content-Security-Policy` directive](/en-US/docs/Web/HTTP/Headers/Content-Security-Policy#directives) that was violated. +A string representing the [`Content-Security-Policy` directive](/en-US/docs/Web/HTTP/Reference/Headers/Content-Security-Policy#directives) that was violated. ## Examples diff --git a/files/en-us/web/api/selection/anchornode/index.md b/files/en-us/web/api/selection/anchornode/index.md index 8694bbb4cde7878..406b758efd417bc 100644 --- a/files/en-us/web/api/selection/anchornode/index.md +++ b/files/en-us/web/api/selection/anchornode/index.md @@ -8,18 +8,13 @@ browser-compat: api.Selection.anchorNode {{ ApiRef("DOM") }} -The **`Selection.anchorNode`** read-only property returns the -{{domxref("Node")}} in which the selection begins. +The **`Selection.anchorNode`** read-only property returns the {{domxref("Node")}} in which the selection begins. It can return `null` if selection never existed in the document (e.g., an iframe that was never clicked on, or the node belongs to another document tree). -A user may make a selection from left to right (in document order) or right to left -(reverse of document order). The anchor is where the user began the selection. This can -be visualized by holding the Shift key and pressing the arrow keys on your keyboard. The -selection's anchor does not move, but the selection's focus, the other end of the -selection, does move. +A user may make a selection from left to right (in document order) or right to left (reverse of document order). The anchor is where the user began the selection. This can be visualized by holding the <kbd>Shift</kbd> key and pressing the arrow keys on your keyboard. The selection's anchor does not move, but the selection's focus, the other end of the selection, does move. ## Value -A {{domxref("Node")}} object. +A {{domxref("Node")}} object or `null`. ## Specifications @@ -31,4 +26,5 @@ A {{domxref("Node")}} object. ## See also -- {{domxref("Selection")}}, the interface it belongs to. +- {{domxref("Selection")}} +- {{domxref("Selection.focusNode")}} diff --git a/files/en-us/web/api/selection/collapse/index.md b/files/en-us/web/api/selection/collapse/index.md index 53d498eccd77442..52cfda28aae73e2 100644 --- a/files/en-us/web/api/selection/collapse/index.md +++ b/files/en-us/web/api/selection/collapse/index.md @@ -25,7 +25,7 @@ collapse(node, offset) - `node` - : The caret location will be within this node. This value can also be set to `null` — if `null` is specified, the method will behave like - {{domxref("Selection.removeAllRanges()")}}, i.e. all ranges will be removed from the + {{domxref("Selection.removeAllRanges()")}}, i.e., all ranges will be removed from the selection. - `offset` {{optional_inline}} - : The offset in `node` to which the selection will be collapsed. If not diff --git a/files/en-us/web/api/selection/focusnode/index.md b/files/en-us/web/api/selection/focusnode/index.md index 2e957277ae9dceb..b032d7cd2482e57 100644 --- a/files/en-us/web/api/selection/focusnode/index.md +++ b/files/en-us/web/api/selection/focusnode/index.md @@ -8,18 +8,13 @@ browser-compat: api.Selection.focusNode {{ ApiRef("DOM") }} -The **`Selection.focusNode`** read-only property returns the -{{domxref("Node")}} in which the selection ends. +The **`Selection.focusNode`** read-only property returns the {{domxref("Node")}} in which the selection ends. It can return `null` if selection never existed in the document (e.g., an iframe that was never clicked on, or the node belongs to another document tree). -A user may make a selection from left to right (in document order) or right to left -(reverse of document order). The focus is where the user ended the selection. This can -be visualized by holding the <kbd>Shift</kbd> key and pressing the arrow keys on your -keyboard to modify the current selection. The selection's focus moves, but the -selection's anchor, the other end of the selection, does not move. +A user may make a selection from left to right (in document order) or right to left (reverse of document order). The focus is where the user ended the selection. This can be visualized by holding the <kbd>Shift</kbd> key and pressing the arrow keys on your keyboard. The selection's focus moves, but the selection's anchor, the other end of the selection, does not move. ## Value -A {{domxref("Node")}} object. +A {{domxref("Node")}} object or `null`. ## Specifications @@ -31,4 +26,5 @@ A {{domxref("Node")}} object. ## See also -- {{domxref("Selection")}}, the interface it belongs to. +- {{domxref("Selection")}} +- {{domxref("Selection.anchorNode")}} diff --git a/files/en-us/web/api/selection/getcomposedranges/index.md b/files/en-us/web/api/selection/getcomposedranges/index.md index 9f54149f5a03efa..a936febbdb299a2 100644 --- a/files/en-us/web/api/selection/getcomposedranges/index.md +++ b/files/en-us/web/api/selection/getcomposedranges/index.md @@ -3,12 +3,10 @@ title: "Selection: getComposedRanges() method" short-title: getComposedRanges() slug: Web/API/Selection/getComposedRanges page-type: web-api-instance-method -status: - - experimental browser-compat: api.Selection.getComposedRanges --- -{{ ApiRef("DOM") }}{{SeeCompatTable}} +{{ ApiRef("DOM") }} The **`Selection.getComposedRanges()`** method returns an array of {{domxref("StaticRange")}} objects representing the current selection ranges, and can return ranges that potentially cross shadow boundaries. @@ -29,17 +27,22 @@ Application code might use a {{domxref("MutationObserver")}} to monitor for DOM ```js-nolint getComposedRanges() -getComposedRanges(shadowRoot1) -getComposedRanges(shadowRoot1, shadowRoot2) -getComposedRanges(shadowRoot1, shadowRoot2, /* …, */ shadowRootN) +getComposedRanges(options) ``` ### Parameters -- `shadowRoot1`, …, `shadowRootN` - - : Zero or more {{domxref("ShadowRoot")}} arguments. - If a selection endpoint is within one of the provided shadow roots, the range will be able to return nodes within its corresponding Shadow DOM tree. - Otherwise, if the selection crosses a shadow boundary and the corresponding `ShadowRoot` is not provided, the returned range will be adjusted to include the entire host element for the shadow root. +- `options` {{optional_inline}} + + - : An object with the following properties, all optional: + + - `shadowRoots` {{optional_inline}} + - : An array of {{domxref("ShadowRoot")}} objects. + If a selection endpoint is within one of the provided shadow roots, the range will be able to return nodes within its corresponding Shadow DOM tree. + Otherwise, if the selection crosses a shadow boundary and the corresponding `ShadowRoot` is not provided, the returned range will be adjusted to include the entire host element for the shadow root. + +> [!NOTE] +> In the original specification, shadow roots were specified as a set of [rest parameters](/en-US/docs/Web/JavaScript/Reference/Functions/rest_parameters). Some browsers may still support this legacy syntax. ### Return value @@ -56,7 +59,7 @@ It allows you to select text that is defined in different nodes in the DOM, and #### HTML -The HTML defines some text nodes with some `<span>` elements to which we'll attach a shadow root using JavScript. +The HTML defines some text nodes with some `<span>` elements to which we'll attach a shadow root using JavaScript. We also add some buttons for copying and applying the selection using a number of different methods. ```html @@ -144,7 +147,7 @@ const copySelectionWithShadowRootsButton = document.querySelector( copySelectionWithShadowRootsButton.addEventListener("click", () => { composedRangeSelection = window .getSelection() - .getComposedRanges(openRoot, closedRoot)[0]; + .getComposedRanges({ shadowRoots: [openRoot, closedRoot] })[0]; log(`Selection has been copied (shadow roots passed)`); }); ``` diff --git a/files/en-us/web/api/selection/index.md b/files/en-us/web/api/selection/index.md index c3752d975dbc0fe..70716ec51e68a3b 100644 --- a/files/en-us/web/api/selection/index.md +++ b/files/en-us/web/api/selection/index.md @@ -22,7 +22,7 @@ A user may make a selection from left to right (in document order) or right to l - {{DOMxRef("Selection.direction")}} {{ReadOnlyInline}} - : A string describing the direction of the current selection. - {{DOMxRef("Selection.focusNode")}} {{ReadOnlyInline}} - - : Returns the {{DOMxRef("Node")}} in which the selection ends. Can return `null` if selection never existed in the document (for example, in an `iframe` that was never clicked on). + - : Returns the {{DOMxRef("Node")}} in which the selection ends. Can return `null` if selection never existed in the document (e.g., an iframe that was never clicked on). - {{DOMxRef("Selection.focusOffset")}} {{ReadOnlyInline}} - : Returns a number representing the offset of the selection's focus within the `focusNode`. If `focusNode` is a text node, this is the number of characters within `focusNode` preceding the focus. If `focusNode` is an element, this is the number of child nodes of the `focusNode` preceding the focus. - {{DOMxRef("Selection.isCollapsed")}} {{ReadOnlyInline}} @@ -50,7 +50,7 @@ A user may make a selection from left to right (in document order) or right to l - : Removes all ranges from the selection, leaving the {{domxref("Selection.anchorNode", "anchorNode")}} and {{domxref("Selection.focusNode","focusNode")}} properties equal to `null` and nothing selected. - {{DOMxRef("Selection.extend()")}} - : Moves the focus of the selection to a specified point. -- {{DOMxRef("Selection.getComposedRanges()")}} {{experimental_inline}} +- {{DOMxRef("Selection.getComposedRanges()")}} - : Returns an array of {{DOMxRef("StaticRange")}} objects, each that represents a selection that might cross shadow DOM boundaries. - {{DOMxRef("Selection.getRangeAt()")}} - : Returns a {{DOMxRef("Range")}} object representing one of the ranges currently selected. @@ -67,7 +67,7 @@ A user may make a selection from left to right (in document order) or right to l - {{DOMxRef("Selection.setPosition()")}} - : Collapses the current selection to a single point. - {{DOMxRef("Selection.toString()")}} - - : Returns a string currently being represented by the selection object, i.e. the currently selected text. + - : Returns a string currently being represented by the selection object, i.e., the currently selected text. ## Notes @@ -94,7 +94,7 @@ const range = selObj.getRangeAt(0); - `selObj` is a Selection object - `range` is a {{DOMxRef("Range")}} object -As the [Selection API specification notes](https://www.w3.org/TR/selection-api/#h_note_15), the Selection API was initially created by Netscape and allowed multiple ranges (for instance, to allow the user to select a column from a {{HTMLElement("table")}}). However, browsers other than Gecko did not implement multiple ranges, and the specification also requires the selection to always have a single range. +As the [Selection API specification notes](https://w3c.github.io/selection-api/#h-note-13), the Selection API was initially created by Netscape and allowed multiple ranges (for instance, to allow the user to select a column from a {{HTMLElement("table")}}). However, browsers other than Gecko did not implement multiple ranges, and the specification also requires the selection to always have a single range. ### Selection and input focus @@ -144,7 +144,7 @@ Other key terms used in this section. - anchor - : The anchor of a selection is the beginning point of the selection. When making a selection with a mouse, the anchor is where in the document the mouse button is initially pressed. As the user changes the selection using the mouse or the keyboard, the anchor does not move. - editing host - - : An editable element (e.g., an HTML element with [`contenteditable`](/en-US/docs/Web/HTML/Global_attributes/contenteditable) set, or the HTML child of a document that has {{DOMxRef("Document.designMode", "designMode")}} enabled). + - : An editable element (e.g., an HTML element with [`contenteditable`](/en-US/docs/Web/HTML/Reference/Global_attributes/contenteditable) set, or the HTML child of a document that has {{DOMxRef("Document.designMode", "designMode")}} enabled). - focus of a selection - : The _focus_ of a selection is the end point of the selection. When making a selection with a mouse, the focus is where in the document the mouse button is released. As the user changes the selection using the mouse or the keyboard, the focus is the end of the selection that moves. diff --git a/files/en-us/web/api/selection/setposition/index.md b/files/en-us/web/api/selection/setposition/index.md index 48b12d559704868..2f67a16789f42b0 100644 --- a/files/en-us/web/api/selection/setposition/index.md +++ b/files/en-us/web/api/selection/setposition/index.md @@ -25,7 +25,7 @@ setPosition(node, offset) - `node` - : The caret location will be within this node. This value can also be set to `null` — if `null` is specified, the method will behave like - {{domxref("Selection.removeAllRanges()")}}, i.e. all ranges will be removed from the + {{domxref("Selection.removeAllRanges()")}}, i.e., all ranges will be removed from the selection. - `offset` {{optional_inline}} - : The offset in `node` to which the selection will be collapsed. If not diff --git a/files/en-us/web/api/selection/tostring/index.md b/files/en-us/web/api/selection/tostring/index.md index 41be16e45752f18..f1b5fe1b39b053e 100644 --- a/files/en-us/web/api/selection/tostring/index.md +++ b/files/en-us/web/api/selection/tostring/index.md @@ -9,7 +9,7 @@ browser-compat: api.Selection.toString {{ ApiRef("DOM") }} The **`Selection.toString()`** method returns a string -currently being represented by the selection object, i.e. the currently selected text. +currently being represented by the selection object, i.e., the currently selected text. ## Syntax diff --git a/files/en-us/web/api/selection/type/index.md b/files/en-us/web/api/selection/type/index.md index 4c2168f3a0e7a32..2719e4aadcd00f9 100644 --- a/files/en-us/web/api/selection/type/index.md +++ b/files/en-us/web/api/selection/type/index.md @@ -20,7 +20,7 @@ values are: - `None` - : No selection has currently been made. - `Caret` - - : The selection is collapsed (i.e. the caret is placed on some + - : The selection is collapsed (i.e., the caret is placed on some text, but no range has been selected). - `Range` - : A range has been selected. diff --git a/files/en-us/web/api/sensor/activate_event/index.md b/files/en-us/web/api/sensor/activate_event/index.md index f17eadbe9976539..9caa8c14ec4e9be 100644 --- a/files/en-us/web/api/sensor/activate_event/index.md +++ b/files/en-us/web/api/sensor/activate_event/index.md @@ -17,10 +17,10 @@ on one of the [derived classes](/en-US/docs/Web/API/Sensor#interfaces_based_on_s Use the event name in methods like {{domxref("EventTarget.addEventListener", "addEventListener()")}}, or set an event handler property. -```js -addEventListener("activate", (event) => {}); +```js-nolint +addEventListener("activate", (event) => { }) -onactivate = (event) => {}; +onactivate = (event) => { } ``` ## Event type diff --git a/files/en-us/web/api/sensor/error_event/index.md b/files/en-us/web/api/sensor/error_event/index.md index f0cf700c52a6b0c..246fea17d1f3846 100644 --- a/files/en-us/web/api/sensor/error_event/index.md +++ b/files/en-us/web/api/sensor/error_event/index.md @@ -19,10 +19,10 @@ After this event has occurred, the {{domxref('Sensor')}} object becomes idle. If Use the event name in methods like {{domxref("EventTarget.addEventListener", "addEventListener()")}}, or set an event handler property. -```js -addEventListener("error", (event) => {}); +```js-nolint +addEventListener("error", (event) => { }) -onerror = (event) => {}; +onerror = (event) => { } ``` ## Event type diff --git a/files/en-us/web/api/sensor/index.md b/files/en-us/web/api/sensor/index.md index 12e25b104215db4..13471617673e717 100644 --- a/files/en-us/web/api/sensor/index.md +++ b/files/en-us/web/api/sensor/index.md @@ -9,7 +9,7 @@ browser-compat: api.Sensor The **`Sensor`** interface of the [Sensor APIs](/en-US/docs/Web/API/Sensor_APIs) is the base class for all the other sensor interfaces. This interface cannot be used directly. Instead it provides properties, event handlers, and methods accessed by interfaces that inherit from it. -This feature may be blocked by a [Permissions Policy](/en-US/docs/Web/HTTP/Permissions_Policy) set on your server. +This feature may be blocked by a [Permissions Policy](/en-US/docs/Web/HTTP/Guides/Permissions_Policy) set on your server. {{InheritanceDiagram}} diff --git a/files/en-us/web/api/sensor/reading_event/index.md b/files/en-us/web/api/sensor/reading_event/index.md index 1a44aa3fb57bf07..298d62610acc758 100644 --- a/files/en-us/web/api/sensor/reading_event/index.md +++ b/files/en-us/web/api/sensor/reading_event/index.md @@ -17,10 +17,10 @@ on one of the [derived classes](/en-US/docs/Web/API/Sensor#interfaces_based_on_s Use the event name in methods like {{domxref("EventTarget.addEventListener", "addEventListener()")}}, or set an event handler property. -```js -addEventListener("reading", (event) => {}); +```js-nolint +addEventListener("reading", (event) => { }) -onreading = (event) => {}; +onreading = (event) => { } ``` ## Event type diff --git a/files/en-us/web/api/sensor_apis/index.md b/files/en-us/web/api/sensor_apis/index.md index a7b8a741e624397..e93399ef241e286 100644 --- a/files/en-us/web/api/sensor_apis/index.md +++ b/files/en-us/web/api/sensor_apis/index.md @@ -60,7 +60,7 @@ As stated in Feature Detection, checking for a particular sensor API is insuffic The code example below illustrates these principles. The {{jsxref('statements/try...catch', 'try...catch')}} block catches errors thrown during sensor instantiation. It listens for {{domxref('Sensor.error_event', 'error')}} events to catch errors thrown during use. The only time anything is shown to the user is when [permissions](/en-US/docs/Web/API/Permissions_API) need to be requested and when the sensor type isn't supported by the device. -In addition, this feature may be blocked by a [Permissions Policy](/en-US/docs/Web/HTTP/Permissions_Policy) set on your server. +In addition, this feature may be blocked by a [Permissions Policy](/en-US/docs/Web/HTTP/Guides/Permissions_Policy) set on your server. ```js let accelerometer = null; diff --git a/files/en-us/web/api/serial/getports/index.md b/files/en-us/web/api/serial/getports/index.md index 3cd0d2f4a3f3b25..0d04facbaa18d54 100644 --- a/files/en-us/web/api/serial/getports/index.md +++ b/files/en-us/web/api/serial/getports/index.md @@ -30,7 +30,7 @@ A {{jsxref("Promise")}} that resolves with an array of {{domxref("SerialPort")}} - `SecurityError` {{domxref("DOMException")}} - : The returned `Promise` rejects with this error in either of the following situations: - - A {{httpheader('Permissions-Policy/serial','serial')}} [Permissions Policy](/en-US/docs/Web/HTTP/Permissions_Policy) blocks the use of this feature. + - A {{httpheader('Permissions-Policy/serial','serial')}} [Permissions Policy](/en-US/docs/Web/HTTP/Guides/Permissions_Policy) blocks the use of this feature. - A user permission prompt was denied. ## Examples diff --git a/files/en-us/web/api/serial/requestport/index.md b/files/en-us/web/api/serial/requestport/index.md index e6117e77ef2d429..cfa107ea27c2f56 100644 --- a/files/en-us/web/api/serial/requestport/index.md +++ b/files/en-us/web/api/serial/requestport/index.md @@ -50,7 +50,7 @@ A {{jsxref("Promise")}} that resolves with an instance of {{domxref("SerialPort" - `SecurityError` {{domxref("DOMException")}} - : The returned `Promise` rejects with this error in either of the following situations: - - A {{httpheader('Permissions-Policy/serial','serial')}} [Permissions Policy](/en-US/docs/Web/HTTP/Permissions_Policy) blocks the use of this feature. + - A {{httpheader('Permissions-Policy/serial','serial')}} [Permissions Policy](/en-US/docs/Web/HTTP/Guides/Permissions_Policy) blocks the use of this feature. - A user permission prompt was denied. - `NotFoundError` {{domxref("DOMException")}} - : The returned `Promise` rejects with this exception if the user does not select a port when prompted. diff --git a/files/en-us/web/api/serialport/close/index.md b/files/en-us/web/api/serialport/close/index.md index 97fe9d24c6668a2..ca4625032425722 100644 --- a/files/en-us/web/api/serialport/close/index.md +++ b/files/en-us/web/api/serialport/close/index.md @@ -12,6 +12,20 @@ browser-compat: api.SerialPort.close The **`SerialPort.close()`** method of the {{domxref("SerialPort")}} interface returns a {{jsxref("Promise")}} that resolves when the port closes. +## Syntax + +```js-nolint +close() +``` + +### Parameters + +None. + +### Return value + +A {{jsxref("Promise")}}. + ## Description `close()` closes the serial port if previously-locked {{domxref("SerialPort.readable")}} and {{domxref("SerialPort.writable")}} members are unlocked, meaning the `releaseLock()` methods have been called for their respective reader and writer. @@ -62,20 +76,6 @@ document.querySelector("button").addEventListener("click", async () => { Closing a serial port is more complicated when using [transform streams](/en-US/docs/Web/API/TransformStream). See [Close a serial port](https://developer.chrome.com/docs/capabilities/serial#close-port) for guidance. -## Syntax - -```js-nolint -close() -``` - -### Parameters - -None. - -### Return value - -A {{jsxref("Promise")}}. - ## Specifications {{Specifications}} diff --git a/files/en-us/web/api/serialport/connect_event/index.md b/files/en-us/web/api/serialport/connect_event/index.md index 795824c24aee906..20f49b233619f1c 100644 --- a/files/en-us/web/api/serialport/connect_event/index.md +++ b/files/en-us/web/api/serialport/connect_event/index.md @@ -29,10 +29,10 @@ For more information, see [Event bubbling](/en-US/docs/Learn_web_development/Cor Use the event name in methods like {{domxref("EventTarget.addEventListener", "addEventListener()")}}, or set an event handler property. -```js -addEventListener("connect", (event) => {}); +```js-nolint +addEventListener("connect", (event) => { }) -onconnect = (event) => {}; +onconnect = (event) => { } ``` ## Event type diff --git a/files/en-us/web/api/serialport/disconnect_event/index.md b/files/en-us/web/api/serialport/disconnect_event/index.md index 1029f813fa48ceb..bd552ee3c8e11b9 100644 --- a/files/en-us/web/api/serialport/disconnect_event/index.md +++ b/files/en-us/web/api/serialport/disconnect_event/index.md @@ -26,10 +26,10 @@ For more information, see [Event bubbling](/en-US/docs/Learn_web_development/Cor Use the event name in methods like {{domxref("EventTarget.addEventListener", "addEventListener()")}}, or set an event handler property. -```js -addEventListener("disconnect", (event) => {}); +```js-nolint +addEventListener("disconnect", (event) => { }) -ondisconnect = (event) => {}; +ondisconnect = (event) => { } ``` ## Event type diff --git a/files/en-us/web/api/server-sent_events/index.md b/files/en-us/web/api/server-sent_events/index.md index 5bd24215f99ccde..3554d6a56f8461a 100644 --- a/files/en-us/web/api/server-sent_events/index.md +++ b/files/en-us/web/api/server-sent_events/index.md @@ -9,9 +9,6 @@ spec-urls: https://html.spec.whatwg.org/multipage/server-sent-events.html#server Traditionally, a web page has to send a request to the server to receive new data; that is, the page requests data from the server. With server-sent events, it's possible for a server to send new data to a web page at any time, by pushing messages to the web page. These incoming messages can be treated as _[Events](/en-US/docs/Web/API/Event) + data_ inside the web page. -> [!NOTE] -> Firefox does not currently support the use of server-sent events in service workers (it does support them in dedicated and shared workers). See [Firefox bug 1681218](https://bugzil.la/1681218). - ## Concepts and usage To learn how to use server-sent events, see our article [Using server-sent events](/en-US/docs/Web/API/Server-sent_events/Using_server-sent_events). diff --git a/files/en-us/web/api/server-sent_events/using_server-sent_events/index.md b/files/en-us/web/api/server-sent_events/using_server-sent_events/index.md index 1efa27344f7ffcd..e7e2e28d1dcc19c 100644 --- a/files/en-us/web/api/server-sent_events/using_server-sent_events/index.md +++ b/files/en-us/web/api/server-sent_events/using_server-sent_events/index.md @@ -109,14 +109,14 @@ while (true) { The code above generates an event every second, with the event type "ping". Each event's data is a JSON object containing the ISO 8601 timestamp corresponding to the time at which the event was generated. At random intervals, a simple message (with no event type) is sent. The loop will keep running independent of the connection status, so a check is included -to break the loop if the connection has been closed (e.g. client closes the page). +to break the loop if the connection has been closed (e.g., client closes the page). > [!NOTE] > You can find a full example that uses the code shown in this article on GitHub — see [Simple SSE demo using PHP](https://github.com/mdn/dom-examples/tree/main/server-sent-events). ## Error handling -When problems occur (such as a network timeout or issues pertaining to [access control](/en-US/docs/Web/HTTP/CORS)), an error event is generated. You can take action on this programmatically by implementing the `onerror` callback on the `EventSource` object: +If the server responds with an `error` key (e.g., `JSON.parse(event.data.error)` or another problem occurs (such as a network timeout or issues pertaining to [access control](/en-US/docs/Web/HTTP/Guides/CORS)), an error event is generated. You can take action on this programmatically by implementing the `onerror` callback on the `EventSource` object: ```js evtSource.onerror = (err) => { diff --git a/files/en-us/web/api/service_worker_api/index.md b/files/en-us/web/api/service_worker_api/index.md index d891e49832fb38a..7c72a81fa27d9d2 100644 --- a/files/en-us/web/api/service_worker_api/index.md +++ b/files/en-us/web/api/service_worker_api/index.md @@ -15,7 +15,7 @@ A service worker is an event-driven [worker](/en-US/docs/Web/API/Worker) registe Service workers run in a worker context: they therefore have no DOM access and run on a different thread to the main JavaScript that powers your app. They are non-blocking and designed to be fully asynchronous. As a consequence, APIs such as synchronous [XHR](/en-US/docs/Web/API/XMLHttpRequest) and [Web Storage](/en-US/docs/Web/API/Web_Storage_API) can't be used inside a service worker. -Service workers can't import JavaScript modules dynamically, and [`import()`](/en-US/docs/Web/JavaScript/Reference/Operators/import#browser_compatibility) will throw if it is called in a service worker global scope. Static imports using the [`import`](/en-US/docs/Web/JavaScript/Reference/Statements/import) statement are allowed. +Service workers can't import JavaScript modules dynamically, and [`import()`](/en-US/docs/Web/JavaScript/Reference/Operators/import#browser_compatibility) will throw an error if it is called in a service worker global scope. Static imports using the [`import`](/en-US/docs/Web/JavaScript/Reference/Statements/import) statement are allowed. Service workers only run over HTTPS, for security reasons. Most significantly, HTTP connections are susceptible to malicious code injection by {{Glossary("MitM", "man in the middle")}} attacks, and such attacks could be worse if allowed access to these powerful APIs. In Firefox, service worker APIs are also hidden and cannot be used when the user is in [private browsing mode](https://support.mozilla.org/en-US/kb/private-browsing-use-firefox-without-history). @@ -111,7 +111,7 @@ In the future, service workers will be able to do several other useful things fo - {{DOMxRef("NavigationPreloadManager")}} - : Provides methods for managing the preloading of resources with a service worker. - {{DOMxRef("ServiceWorker")}} - - : Represents a service worker. Multiple browsing contexts (e.g. pages, workers, etc.) can be associated with the same `ServiceWorker` object. + - : Represents a service worker. Multiple browsing contexts (e.g., pages, workers, etc.) can be associated with the same `ServiceWorker` object. - {{DOMxRef("ServiceWorkerContainer")}} - : Provides an object representing the service worker as an overall unit in the network ecosystem, including facilities to register, unregister, and update service workers, and access the state of service workers and their registrations. - {{DOMxRef("ServiceWorkerGlobalScope")}} diff --git a/files/en-us/web/api/serviceworker/error_event/index.md b/files/en-us/web/api/serviceworker/error_event/index.md index 21d98e72755cf5a..c5321475144c306 100644 --- a/files/en-us/web/api/serviceworker/error_event/index.md +++ b/files/en-us/web/api/serviceworker/error_event/index.md @@ -14,10 +14,10 @@ The `error` event fires whenever an error occurs in the service worker. Use the event name in methods like {{domxref("EventTarget.addEventListener", "addEventListener()")}}, or set an event handler property. -```js -addEventListener("error", (event) => {}); +```js-nolint +addEventListener("error", (event) => { }) -onerror = (event) => {}; +onerror = (event) => { } ``` ## Event type diff --git a/files/en-us/web/api/serviceworker/index.md b/files/en-us/web/api/serviceworker/index.md index 0cecef9ad92ad86..25a6382288fa40c 100644 --- a/files/en-us/web/api/serviceworker/index.md +++ b/files/en-us/web/api/serviceworker/index.md @@ -7,7 +7,7 @@ browser-compat: api.ServiceWorker {{securecontext_header}}{{APIRef("Service Workers API")}}{{AvailableInWorkers}} -The **`ServiceWorker`** interface of the [Service Worker API](/en-US/docs/Web/API/Service_Worker_API) provides a reference to a service worker. Multiple {{glossary("browsing context", "browsing contexts")}} (e.g. pages, workers, etc.) can be associated with the same service worker, each through a unique `ServiceWorker` object. +The **`ServiceWorker`** interface of the [Service Worker API](/en-US/docs/Web/API/Service_Worker_API) provides a reference to a service worker. Multiple {{glossary("browsing context", "browsing contexts")}} (e.g., pages, workers, etc.) can be associated with the same service worker, each through a unique `ServiceWorker` object. A `ServiceWorker` object is available via a number of properties: @@ -17,7 +17,7 @@ A `ServiceWorker` object is available via a number of properties: - {{domxref("ServiceWorkerRegistration.installing")}} — when the service worker is in `installing` state - {{domxref("ServiceWorkerRegistration.waiting")}} — when the service worker is in `installed` state -The {{domxref("ServiceWorker.state")}} property and [`statechanged` event](/en-US/docs/Web/API/ServiceWorker/statechange_event) can be used to check and observe changes in the lifecycle-state of the object's associated service worker. +The {{domxref("ServiceWorker.state")}} property and [`statechange` event](/en-US/docs/Web/API/ServiceWorker/statechange_event) can be used to check and observe changes in the lifecycle-state of the object's associated service worker. Related lifecycle events, such as [`install`](/en-US/docs/Web/API/ServiceWorkerGlobalScope/install_event) and [`activate`](/en-US/docs/Web/API/ServiceWorkerGlobalScope/activate_event) are fired at the service worker itself. Service workers allow static import of [ECMAScript modules](/en-US/docs/Web/JavaScript/Guide/Modules), if supported, using [`import`](/en-US/docs/Web/JavaScript/Reference/Statements/import). diff --git a/files/en-us/web/api/serviceworker/statechange_event/index.md b/files/en-us/web/api/serviceworker/statechange_event/index.md index 34e1865610156d9..bdef46219b56009 100644 --- a/files/en-us/web/api/serviceworker/statechange_event/index.md +++ b/files/en-us/web/api/serviceworker/statechange_event/index.md @@ -14,10 +14,10 @@ The `statechange` event fires anytime the {{domxref("ServiceWorker.state")}} cha Use the event name in methods like {{domxref("EventTarget.addEventListener", "addEventListener()")}}, or set an event handler property. -```js -addEventListener("statechange", (event) => {}); +```js-nolint +addEventListener("statechange", (event) => { }) -onstatechange = (event) => {}; +onstatechange = (event) => { } ``` ## Event type diff --git a/files/en-us/web/api/serviceworkercontainer/controllerchange_event/index.md b/files/en-us/web/api/serviceworkercontainer/controllerchange_event/index.md index 3190c96e4e1e896..8e6d0ce51602c30 100644 --- a/files/en-us/web/api/serviceworkercontainer/controllerchange_event/index.md +++ b/files/en-us/web/api/serviceworkercontainer/controllerchange_event/index.md @@ -14,10 +14,10 @@ The **`controllerchange`** event of the {{domxref("ServiceWorkerContainer")}} in Use the event name in methods like {{domxref("EventTarget.addEventListener", "addEventListener()")}}, or set an event handler property. -```js -addEventListener("controllerchange", (event) => {}); +```js-nolint +addEventListener("controllerchange", (event) => { }) -oncontrollerchange = (event) => {}; +oncontrollerchange = (event) => { } ``` ## Event type diff --git a/files/en-us/web/api/serviceworkercontainer/error_event/index.md b/files/en-us/web/api/serviceworkercontainer/error_event/index.md deleted file mode 100644 index 6c8e7f0eaf4c86b..000000000000000 --- a/files/en-us/web/api/serviceworkercontainer/error_event/index.md +++ /dev/null @@ -1,40 +0,0 @@ ---- -title: "ServiceWorkerContainer: error event" -short-title: error -slug: Web/API/ServiceWorkerContainer/error_event -page-type: web-api-event -status: - - deprecated - - non-standard -browser-compat: api.ServiceWorkerContainer.error_event ---- - -{{APIRef("Service Workers API")}}{{Deprecated_header}}{{Non-standard_header}}{{SecureContext_Header}}{{AvailableInWorkers}} - -The `error` event fires when an error occurs in the service worker. - -## Syntax - -Use the event name in methods like {{domxref("EventTarget.addEventListener", "addEventListener()")}}, or set an event handler property. - -```js -addEventListener("error", (event) => {}); - -onerror = (event) => {}; -``` - -## Event type - -A generic {{domxref("Event")}}. - -## Example - -```js -navigator.serviceWorker.onerror = (event) => { - console.error(`received error message: ${event.message}`); -}; -``` - -## Browser compatibility - -{{Compat}} diff --git a/files/en-us/web/api/serviceworkercontainer/index.md b/files/en-us/web/api/serviceworkercontainer/index.md index 38ae2b40267e35f..cf820ca73c7e850 100644 --- a/files/en-us/web/api/serviceworkercontainer/index.md +++ b/files/en-us/web/api/serviceworkercontainer/index.md @@ -31,18 +31,16 @@ Most importantly, it exposes the {{domxref("ServiceWorkerContainer.register()")} - {{domxref("ServiceWorkerContainer.register()")}} - : Creates or updates a {{domxref("ServiceWorkerRegistration")}} for the given `scriptURL`. - {{domxref("ServiceWorkerContainer.startMessages()")}} - - : Explicitly starts the flow of messages being dispatched from a service worker to pages under its control (e.g. sent via {{domxref("Client.postMessage()")}}). This can be used to react to sent messages earlier, even before that page's content has finished loading. + - : Explicitly starts the flow of messages being dispatched from a service worker to pages under its control (e.g., sent via {{domxref("Client.postMessage()")}}). This can be used to react to sent messages earlier, even before that page's content has finished loading. ## Events - {{domxref("ServiceWorkerContainer/controllerchange_event", "controllerchange")}} - : Fired when the document's associated {{domxref("ServiceWorkerRegistration")}} acquires a new {{domxref("ServiceWorkerRegistration.active","active")}} worker. -- {{domxref("ServiceWorkerContainer/error_event", "error")}} {{Deprecated_Inline}} {{Non-standard_Inline}} - - : Fired whenever an error occurs in the associated service workers. - {{domxref("ServiceWorkerContainer/message_event", "message")}} - - : Fired when incoming messages are received by the `ServiceWorkerContainer` object (e.g. via a {{domxref("MessagePort.postMessage()")}} call). + - : Fired when incoming messages are received by the `ServiceWorkerContainer` object (e.g., via a {{domxref("MessagePort.postMessage()")}} call). - {{domxref("ServiceWorkerContainer/messageerror_event", "messageerror")}} - - : Fired when incoming messages can not deserialized by the `ServiceWorkerContainer` object (e.g. via a {{domxref("MessagePort.postMessage()")}} call). + - : Fired when incoming messages can not deserialized by the `ServiceWorkerContainer` object (e.g., via a {{domxref("MessagePort.postMessage()")}} call). ## Examples diff --git a/files/en-us/web/api/serviceworkercontainer/message_event/index.md b/files/en-us/web/api/serviceworkercontainer/message_event/index.md index 9f3d53ce1509505..928deceb54592f1 100644 --- a/files/en-us/web/api/serviceworkercontainer/message_event/index.md +++ b/files/en-us/web/api/serviceworkercontainer/message_event/index.md @@ -16,10 +16,10 @@ This event is not cancelable and does not bubble. Use the event name in methods like {{domxref("EventTarget.addEventListener", "addEventListener()")}}, or set an event handler property. -```js -addEventListener("message", (event) => {}); +```js-nolint +addEventListener("message", (event) => { }) -onmessage = (event) => {}; +onmessage = (event) => { } ``` ## Event type @@ -41,7 +41,7 @@ _This interface also inherits properties from its parent, {{domxref("Event")}}._ - {{domxref("MessageEvent.source")}} {{ReadOnlyInline}} - : A `MessageEventSource` (which can be a {{glossary("WindowProxy")}}, {{domxref("MessagePort")}}, or {{domxref("ServiceWorker")}} object) representing the message emitter. - {{domxref("MessageEvent.ports")}} {{ReadOnlyInline}} - - : An array of {{domxref("MessagePort")}} objects representing the ports associated with the channel the message is being sent through (where appropriate, e.g. in channel messaging or when sending a message to a shared worker). + - : An array of {{domxref("MessagePort")}} objects representing the ports associated with the channel the message is being sent through (where appropriate, e.g., in channel messaging or when sending a message to a shared worker). ## Examples diff --git a/files/en-us/web/api/serviceworkercontainer/messageerror_event/index.md b/files/en-us/web/api/serviceworkercontainer/messageerror_event/index.md index 16d0c3949e855c1..59849f491a932c1 100644 --- a/files/en-us/web/api/serviceworkercontainer/messageerror_event/index.md +++ b/files/en-us/web/api/serviceworkercontainer/messageerror_event/index.md @@ -14,12 +14,12 @@ This event is not cancelable and does not bubble. ## Syntax -Use the event name in methods like {{domxref("EventTarget.addEventListener()", "addEventListener()")}}, or set an event handler property. +Use the event name in methods like {{domxref("EventTarget.addEventListener", "addEventListener()")}}, or set an event handler property. -```js -addEventListener("messageerror", (event) => {}); +```js-nolint +addEventListener("messageerror", (event) => { }) -onmessageerror = (event) => {}; +onmessageerror = (event) => { } ``` ## Event type @@ -41,7 +41,7 @@ _This interface also inherits properties from its parent, {{domxref("Event")}}._ - {{domxref("MessageEvent.source")}} {{ReadOnlyInline}} - : A `MessageEventSource` (which can be a {{glossary("WindowProxy")}}, {{domxref("MessagePort")}}, or {{domxref("ServiceWorker")}} object) representing the message emitter. - {{domxref("MessageEvent.ports")}} {{ReadOnlyInline}} - - : An array of {{domxref("MessagePort")}} objects representing the ports associated with the channel the message is being sent through (where appropriate, e.g. in channel messaging or when sending a message to a shared worker). + - : An array of {{domxref("MessagePort")}} objects representing the ports associated with the channel the message is being sent through (where appropriate, e.g., in channel messaging or when sending a message to a shared worker). ## Examples diff --git a/files/en-us/web/api/serviceworkercontainer/register/index.md b/files/en-us/web/api/serviceworkercontainer/register/index.md index 0ef949a2c14d9b7..fcbecdd6257c801 100644 --- a/files/en-us/web/api/serviceworkercontainer/register/index.md +++ b/files/en-us/web/api/serviceworkercontainer/register/index.md @@ -35,7 +35,7 @@ register(scriptURL, options) - `scriptURL` - : The URL of the service worker script. - The registered service worker file needs to have a valid [JavaScript MIME type](/en-US/docs/Web/HTTP/MIME_types#textjavascript). + The registered service worker file needs to have a valid [JavaScript MIME type](/en-US/docs/Web/HTTP/Guides/MIME_types#textjavascript). - `options` {{optional_inline}} - : An object containing registration options. Currently available options are: @@ -44,7 +44,7 @@ register(scriptURL, options) - : A string representing a URL that defines a service worker's registration scope; that is, what range of URLs a service worker can control. - This is usually specified as a URL that is relative to the base URL of the site (e.g. `/some/path/`), so that the resolved scope is the same irrespective of what page the registration code is called from. + This is usually specified as a URL that is relative to the base URL of the site (e.g., `/some/path/`), so that the resolved scope is the same irrespective of what page the registration code is called from. The default `scope` for a service worker registration is the directory where the service worker script is located (resolving `./` against `scriptURL`). The scope should be used to specify documents that are in the same directory or more deeply nested than the service worker. diff --git a/files/en-us/web/api/serviceworkercontainer/startmessages/index.md b/files/en-us/web/api/serviceworkercontainer/startmessages/index.md index c63ec21b6607d99..a55792b5c6bcabf 100644 --- a/files/en-us/web/api/serviceworkercontainer/startmessages/index.md +++ b/files/en-us/web/api/serviceworkercontainer/startmessages/index.md @@ -10,7 +10,7 @@ browser-compat: api.ServiceWorkerContainer.startMessages The **`startMessages()`** method of the {{domxref("ServiceWorkerContainer")}} interface explicitly starts the flow of -messages being dispatched from a service worker to pages under its control (e.g. sent +messages being dispatched from a service worker to pages under its control (e.g., sent via {{domxref("Client.postMessage()")}}). This can be used to react to sent messages earlier, even before that page's content has finished loading. @@ -18,7 +18,7 @@ earlier, even before that page's content has finished loading. By default, all messages sent from a page's controlling service worker to the page (using {{domxref("Client.postMessage()")}}) are queued while the page is loading, and -get dispatched once the page's HTML document has been loaded and parsed (i.e. after the +get dispatched once the page's HTML document has been loaded and parsed (i.e., after the {{domxref("Document/DOMContentLoaded_event", "DOMContentLoaded")}} event fires). It's possible to start dispatching these messages earlier by calling `ServiceWorkerContainer.startMessages()`, for example if you've invoked a message handler using diff --git a/files/en-us/web/api/serviceworkerglobalscope/activate_event/index.md b/files/en-us/web/api/serviceworkerglobalscope/activate_event/index.md index 643c4d674bb009b..21171c924066bd6 100644 --- a/files/en-us/web/api/serviceworkerglobalscope/activate_event/index.md +++ b/files/en-us/web/api/serviceworkerglobalscope/activate_event/index.md @@ -16,10 +16,10 @@ This event is not cancelable and does not bubble. Use the event name in methods like {{domxref("EventTarget.addEventListener", "addEventListener()")}}, or set an event handler property. -```js -addEventListener("activate", (event) => {}); +```js-nolint +addEventListener("activate", (event) => { }) -onactivate = (event) => {}; +onactivate = (event) => { } ``` ## Event type @@ -41,15 +41,16 @@ self.addEventListener("activate", (event) => { const cacheAllowlist = ["v2"]; event.waitUntil( - caches.keys().then((cacheNames) => { - return Promise.all( + caches.keys().then((cacheNames) => + Promise.all( cacheNames.map((cacheName) => { if (!cacheAllowlist.includes(cacheName)) { return caches.delete(cacheName); } + return undefined; }), - ); - }), + ), + ), ); }); ``` @@ -58,7 +59,7 @@ You can also set up the event handler using the `onactivate` property: ```js self.onactivate = (event) => { - // ... + // … }; ``` diff --git a/files/en-us/web/api/serviceworkerglobalscope/backgroundfetchabort_event/index.md b/files/en-us/web/api/serviceworkerglobalscope/backgroundfetchabort_event/index.md index 2f735c846262189..3bb7af8e929369b 100644 --- a/files/en-us/web/api/serviceworkerglobalscope/backgroundfetchabort_event/index.md +++ b/files/en-us/web/api/serviceworkerglobalscope/backgroundfetchabort_event/index.md @@ -18,10 +18,10 @@ This event is not cancelable and does not bubble. Use the event name in methods like {{domxref("EventTarget.addEventListener", "addEventListener()")}}, or set an event handler property. -```js -addEventListener("backgroundfetchabort", (event) => {}); +```js-nolint +addEventListener("backgroundfetchabort", (event) => { }) -onbackgroundfetchabort = (event) => {}; +onbackgroundfetchabort = (event) => { } ``` ## Event type diff --git a/files/en-us/web/api/serviceworkerglobalscope/backgroundfetchclick_event/index.md b/files/en-us/web/api/serviceworkerglobalscope/backgroundfetchclick_event/index.md index 90a6169e4644f00..0be529f5a2a9e24 100644 --- a/files/en-us/web/api/serviceworkerglobalscope/backgroundfetchclick_event/index.md +++ b/files/en-us/web/api/serviceworkerglobalscope/backgroundfetchclick_event/index.md @@ -18,10 +18,10 @@ This event is not cancelable and does not bubble. Use the event name in methods like {{domxref("EventTarget.addEventListener", "addEventListener()")}}, or set an event handler property. -```js -addEventListener("backgroundfetchclick", (event) => {}); +```js-nolint +addEventListener("backgroundfetchclick", (event) => { }) -onbackgroundfetchclick = (event) => {}; +onbackgroundfetchclick = (event) => { } ``` ## Event type diff --git a/files/en-us/web/api/serviceworkerglobalscope/backgroundfetchfail_event/index.md b/files/en-us/web/api/serviceworkerglobalscope/backgroundfetchfail_event/index.md index 3222834fe7f8a5f..5a02c20b0f532ac 100644 --- a/files/en-us/web/api/serviceworkerglobalscope/backgroundfetchfail_event/index.md +++ b/files/en-us/web/api/serviceworkerglobalscope/backgroundfetchfail_event/index.md @@ -18,10 +18,10 @@ This event is not cancelable and does not bubble. Use the event name in methods like {{domxref("EventTarget.addEventListener", "addEventListener()")}}, or set an event handler property. -```js -addEventListener("backgroundfetchfail", (event) => {}); +```js-nolint +addEventListener("backgroundfetchfail", (event) => { }) -onbackgroundfetchfail = (event) => {}; +onbackgroundfetchfail = (event) => { } ``` ## Event type diff --git a/files/en-us/web/api/serviceworkerglobalscope/backgroundfetchsuccess_event/index.md b/files/en-us/web/api/serviceworkerglobalscope/backgroundfetchsuccess_event/index.md index 797923287171721..b8c034c1b935b73 100644 --- a/files/en-us/web/api/serviceworkerglobalscope/backgroundfetchsuccess_event/index.md +++ b/files/en-us/web/api/serviceworkerglobalscope/backgroundfetchsuccess_event/index.md @@ -18,10 +18,10 @@ This event is not cancelable and does not bubble. Use the event name in methods like {{domxref("EventTarget.addEventListener", "addEventListener()")}}, or set an event handler property. -```js -addEventListener("backgroundfetchsuccess", (event) => {}); +```js-nolint +addEventListener("backgroundfetchsuccess", (event) => { }) -onbackgroundfetchsuccess = (event) => {}; +onbackgroundfetchsuccess = (event) => { } ``` ## Event type diff --git a/files/en-us/web/api/serviceworkerglobalscope/canmakepayment_event/index.md b/files/en-us/web/api/serviceworkerglobalscope/canmakepayment_event/index.md index e85c98d1ca3cfa8..137dedce0c06719 100644 --- a/files/en-us/web/api/serviceworkerglobalscope/canmakepayment_event/index.md +++ b/files/en-us/web/api/serviceworkerglobalscope/canmakepayment_event/index.md @@ -16,10 +16,10 @@ The **`canmakepayment`** event of the {{domxref("ServiceWorkerGlobalScope")}} in Use the event name in methods like {{domxref("EventTarget.addEventListener", "addEventListener()")}}, or set an event handler property. -```js -addEventListener("canmakepayment", (event) => {}); +```js-nolint +addEventListener("canmakepayment", (event) => { }) -oncanmakepayment = (event) => {}; +oncanmakepayment = (event) => { } ``` ## Event type diff --git a/files/en-us/web/api/serviceworkerglobalscope/contentdelete_event/index.md b/files/en-us/web/api/serviceworkerglobalscope/contentdelete_event/index.md index a5f02e95328fa01..fec75e7094f9cce 100644 --- a/files/en-us/web/api/serviceworkerglobalscope/contentdelete_event/index.md +++ b/files/en-us/web/api/serviceworkerglobalscope/contentdelete_event/index.md @@ -18,10 +18,10 @@ This event is not cancelable and does not bubble. Use the event name in methods like {{domxref("EventTarget.addEventListener", "addEventListener()")}}, or set an event handler property. -```js -addEventListener("contentdelete", (event) => {}); +```js-nolint +addEventListener("contentdelete", (event) => { }) -oncontentdelete = (event) => {}; +oncontentdelete = (event) => { } ``` ## Event type @@ -59,7 +59,7 @@ You can also set up the event handler using the `oncontentdelete` property: ```js self.oncontentdelete = (event) => { - // ... + // … }; ``` diff --git a/files/en-us/web/api/serviceworkerglobalscope/cookiechange_event/index.md b/files/en-us/web/api/serviceworkerglobalscope/cookiechange_event/index.md index 1b1bd4a17fb5d93..c7d048303dc975f 100644 --- a/files/en-us/web/api/serviceworkerglobalscope/cookiechange_event/index.md +++ b/files/en-us/web/api/serviceworkerglobalscope/cookiechange_event/index.md @@ -3,12 +3,10 @@ title: "ServiceWorkerGlobalScope: cookiechange event" short-title: cookiechange slug: Web/API/ServiceWorkerGlobalScope/cookiechange_event page-type: web-api-event -status: - - experimental browser-compat: api.ServiceWorkerGlobalScope.cookiechange_event --- -{{APIRef("Cookie Store API")}}{{SeeCompatTable}}{{SecureContext_Header}}{{AvailableInWorkers("service")}} +{{APIRef("Cookie Store API")}}{{SecureContext_Header}}{{AvailableInWorkers("service")}} The **`cookiechange`** event of the {{domxref("ServiceWorkerGlobalScope")}} interface is fired when a cookie change occurs that matches the service worker's cookie change subscription list. @@ -18,10 +16,10 @@ This event is not cancelable and does not bubble. Use the event name in methods like {{domxref("EventTarget.addEventListener", "addEventListener()")}}, or set an event handler property. -```js -addEventListener("cookiechange", (event) => {}); +```js-nolint +addEventListener("cookiechange", (event) => { }) -oncookiechange = (event) => {}; +oncookiechange = (event) => { } ``` ## Event type diff --git a/files/en-us/web/api/serviceworkerglobalscope/fetch_event/index.md b/files/en-us/web/api/serviceworkerglobalscope/fetch_event/index.md index e23032768e0ad22..420b7914643ab3e 100644 --- a/files/en-us/web/api/serviceworkerglobalscope/fetch_event/index.md +++ b/files/en-us/web/api/serviceworkerglobalscope/fetch_event/index.md @@ -16,10 +16,10 @@ This event is not cancelable and does not bubble. Use the event name in methods like {{domxref("EventTarget.addEventListener", "addEventListener()")}}, or set an event handler property. -```js -addEventListener("fetch", (event) => {}); +```js-nolint +addEventListener("fetch", (event) => { }) -onfetch = (event) => {}; +onfetch = (event) => { } ``` ## Description diff --git a/files/en-us/web/api/serviceworkerglobalscope/index.md b/files/en-us/web/api/serviceworkerglobalscope/index.md index 2c461d09baab602..c3d0a555d5d6c2e 100644 --- a/files/en-us/web/api/serviceworkerglobalscope/index.md +++ b/files/en-us/web/api/serviceworkerglobalscope/index.md @@ -57,7 +57,7 @@ Listen to this event using {{domxref("EventTarget/addEventListener()", "addEvent - : Fired on a payment app's service worker to check whether it is ready to handle a payment. Specifically, it is fired when the merchant website calls the {{domxref("PaymentRequest.PaymentRequest", "PaymentRequest()")}} constructor. - {{domxref("ServiceWorkerGlobalScope/contentdelete_event", "contentdelete")}} {{Experimental_Inline}} - : Occurs when an item is removed from the {{domxref("ContentIndex")}}. -- {{domxref("ServiceWorkerGlobalScope/cookiechange_event", "cookiechange")}} {{Experimental_Inline}} +- {{domxref("ServiceWorkerGlobalScope/cookiechange_event", "cookiechange")}} - : Fired when a cookie change has occurred that matches the service worker's cookie change subscription list. - {{domxref("ServiceWorkerGlobalScope/fetch_event", "fetch")}} - : Occurs when a {{domxref("WorkerGlobalScope/fetch", "fetch()")}} is called. @@ -80,7 +80,7 @@ Listen to this event using {{domxref("EventTarget/addEventListener()", "addEvent - {{domxref("ServiceWorkerGlobalScope/push_event", "push")}} - : Occurs when a server push notification is received. - {{domxref("ServiceWorkerGlobalScope/pushsubscriptionchange_event", "pushsubscriptionchange")}} - - : Occurs when a push subscription has been invalidated, or is about to be invalidated (e.g. when a push service sets an expiration time). + - : Occurs when a push subscription has been invalidated, or is about to be invalidated (e.g., when a push service sets an expiration time). ## Examples diff --git a/files/en-us/web/api/serviceworkerglobalscope/install_event/index.md b/files/en-us/web/api/serviceworkerglobalscope/install_event/index.md index 4638bd790dfb58b..c23c1213ac0b7ee 100644 --- a/files/en-us/web/api/serviceworkerglobalscope/install_event/index.md +++ b/files/en-us/web/api/serviceworkerglobalscope/install_event/index.md @@ -16,10 +16,10 @@ This event is not cancelable and does not bubble. Use the event name in methods like {{domxref("EventTarget.addEventListener", "addEventListener()")}}, or set an event handler property. -```js -addEventListener("install", (event) => {}); +```js-nolint +addEventListener("install", (event) => { }) -oninstall = (event) => {}; +oninstall = (event) => { } ``` ## Event type @@ -63,7 +63,7 @@ You can also set up the event handler using the `oninstall` property: ```js self.oninstall = (event) => { - // ... + // … }; ``` diff --git a/files/en-us/web/api/serviceworkerglobalscope/message_event/index.md b/files/en-us/web/api/serviceworkerglobalscope/message_event/index.md index b7ac84576d334d8..a11debd23af1028 100644 --- a/files/en-us/web/api/serviceworkerglobalscope/message_event/index.md +++ b/files/en-us/web/api/serviceworkerglobalscope/message_event/index.md @@ -17,10 +17,10 @@ This event is not cancelable and does not bubble. Use the event name in methods like {{domxref("EventTarget.addEventListener", "addEventListener()")}}, or set an event handler property. -```js -addEventListener("message", (event) => {}); +```js-nolint +addEventListener("message", (event) => { }) -onmessage = (event) => {}; +onmessage = (event) => { } ``` ## Event type diff --git a/files/en-us/web/api/serviceworkerglobalscope/messageerror_event/index.md b/files/en-us/web/api/serviceworkerglobalscope/messageerror_event/index.md index 35960f3257f89f7..66af4a5ac842ce1 100644 --- a/files/en-us/web/api/serviceworkerglobalscope/messageerror_event/index.md +++ b/files/en-us/web/api/serviceworkerglobalscope/messageerror_event/index.md @@ -16,10 +16,10 @@ This event is not cancelable and does not bubble. Use the event name in methods like {{domxref("EventTarget.addEventListener", "addEventListener()")}}, or set an event handler property. -```js -addEventListener("messageerror", (event) => {}); +```js-nolint +addEventListener("messageerror", (event) => { }) -onmessageerror = (event) => {}; +onmessageerror = (event) => { } ``` ## Event type diff --git a/files/en-us/web/api/serviceworkerglobalscope/notificationclick_event/index.md b/files/en-us/web/api/serviceworkerglobalscope/notificationclick_event/index.md index ce45e44f5b9e9a1..437a8608d93f330 100644 --- a/files/en-us/web/api/serviceworkerglobalscope/notificationclick_event/index.md +++ b/files/en-us/web/api/serviceworkerglobalscope/notificationclick_event/index.md @@ -21,10 +21,10 @@ This event is not cancelable and does not bubble. Use the event name in methods like {{domxref("EventTarget.addEventListener", "addEventListener()")}}, or set an event handler property. -```js -addEventListener("notificationclick", (event) => {}); +```js-nolint +addEventListener("notificationclick", (event) => { }) -onnotificationclick = (event) => {}; +onnotificationclick = (event) => { } ``` ## Event type diff --git a/files/en-us/web/api/serviceworkerglobalscope/notificationclose_event/index.md b/files/en-us/web/api/serviceworkerglobalscope/notificationclose_event/index.md index 3bad1f5bfea2f0d..17725965ad0d16a 100644 --- a/files/en-us/web/api/serviceworkerglobalscope/notificationclose_event/index.md +++ b/files/en-us/web/api/serviceworkerglobalscope/notificationclose_event/index.md @@ -21,10 +21,10 @@ This event is not cancelable and does not bubble. Use the event name in methods like {{domxref("EventTarget.addEventListener", "addEventListener()")}}, or set an event handler property. -```js -addEventListener("notificationclose", (event) => {}); +```js-nolint +addEventListener("notificationclose", (event) => { }) -onnotificationclose = (event) => {}; +onnotificationclose = (event) => { } ``` ## Event type diff --git a/files/en-us/web/api/serviceworkerglobalscope/paymentrequest_event/index.md b/files/en-us/web/api/serviceworkerglobalscope/paymentrequest_event/index.md index fe8adb5c8f0aa7c..577401ffb74aded 100644 --- a/files/en-us/web/api/serviceworkerglobalscope/paymentrequest_event/index.md +++ b/files/en-us/web/api/serviceworkerglobalscope/paymentrequest_event/index.md @@ -16,10 +16,10 @@ The **`paymentrequest`** event of the {{domxref("ServiceWorkerGlobalScope")}} in Use the event name in methods like {{domxref("EventTarget.addEventListener", "addEventListener()")}}, or set an event handler property. -```js -addEventListener("paymentrequest", (event) => {}); +```js-nolint +addEventListener("paymentrequest", (event) => { }) -onpaymentrequest = (event) => {}; +onpaymentrequest = (event) => { } ``` ## Event type @@ -46,7 +46,7 @@ self.addEventListener("paymentrequest", async (e) => { // Preserve the event for future use payment_request_event = e; - // ... + // … }); ``` diff --git a/files/en-us/web/api/serviceworkerglobalscope/periodicsync_event/index.md b/files/en-us/web/api/serviceworkerglobalscope/periodicsync_event/index.md index 28d79e61d650dbf..c06b0b4c45c0d0b 100644 --- a/files/en-us/web/api/serviceworkerglobalscope/periodicsync_event/index.md +++ b/files/en-us/web/api/serviceworkerglobalscope/periodicsync_event/index.md @@ -18,10 +18,10 @@ This event is not cancelable and does not bubble. Use the event name in methods like {{domxref("EventTarget.addEventListener", "addEventListener()")}}, or set an event handler property. -```js -addEventListener("periodicsync", (event) => {}); +```js-nolint +addEventListener("periodicsync", (event) => { }) -onperiodicsync = (event) => {}; +onperiodicsync = (event) => { } ``` ## Event type @@ -53,7 +53,7 @@ You can also set up the event handler using the `onperiodicsync` property: ```js self.onperiodicsync = (event) => { - // ... + // … }; ``` diff --git a/files/en-us/web/api/serviceworkerglobalscope/push_event/index.md b/files/en-us/web/api/serviceworkerglobalscope/push_event/index.md index ea48917f9ffe6df..b42bd13220d4e48 100644 --- a/files/en-us/web/api/serviceworkerglobalscope/push_event/index.md +++ b/files/en-us/web/api/serviceworkerglobalscope/push_event/index.md @@ -16,10 +16,10 @@ This event is not cancelable and does not bubble. Use the event name in methods like {{domxref("EventTarget.addEventListener", "addEventListener()")}}, or set an event handler property. -```js -addEventListener("push", (event) => {}); +```js-nolint +addEventListener("push", (event) => { }) -onpush = (event) => {}; +onpush = (event) => { } ``` ## Event type diff --git a/files/en-us/web/api/serviceworkerglobalscope/pushsubscriptionchange_event/index.md b/files/en-us/web/api/serviceworkerglobalscope/pushsubscriptionchange_event/index.md index 86d3293b8d68812..7848722f4477d5f 100644 --- a/files/en-us/web/api/serviceworkerglobalscope/pushsubscriptionchange_event/index.md +++ b/files/en-us/web/api/serviceworkerglobalscope/pushsubscriptionchange_event/index.md @@ -18,10 +18,10 @@ This event is not cancelable and does not bubble. Use the event name in methods like {{domxref("EventTarget.addEventListener", "addEventListener()")}}, or set an event handler property. -```js -addEventListener("pushsubscriptionchange", (event) => {}); +```js-nolint +addEventListener("pushsubscriptionchange", (event) => { }) -onpushsubscriptionchange = (event) => {}; +onpushsubscriptionchange = (event) => { } ``` ## Event type diff --git a/files/en-us/web/api/serviceworkerglobalscope/sync_event/index.md b/files/en-us/web/api/serviceworkerglobalscope/sync_event/index.md index 33c1d432d43cf0b..8fcbf8532a4bd50 100644 --- a/files/en-us/web/api/serviceworkerglobalscope/sync_event/index.md +++ b/files/en-us/web/api/serviceworkerglobalscope/sync_event/index.md @@ -16,10 +16,10 @@ This event is not cancelable and does not bubble. Use the event name in methods like {{domxref("EventTarget.addEventListener", "addEventListener()")}}, or set an event handler property. -```js -addEventListener("sync", (event) => {}); +```js-nolint +addEventListener("sync", (event) => { }) -onsync = (event) => {}; +onsync = (event) => { } ``` ## Event type @@ -53,7 +53,7 @@ You can also set up the event handler using the `onsync` property: ```js self.onsync = (event) => { - // ... + // … }; ``` diff --git a/files/en-us/web/api/serviceworkerregistration/backgroundfetch/index.md b/files/en-us/web/api/serviceworkerregistration/backgroundfetch/index.md index 75d765d6474e165..fca4813637e86b0 100644 --- a/files/en-us/web/api/serviceworkerregistration/backgroundfetch/index.md +++ b/files/en-us/web/api/serviceworkerregistration/backgroundfetch/index.md @@ -38,7 +38,7 @@ async function requestBackgroundFetch(movieData) { label: "Downloading a show", }, ); - //... + // … } ``` diff --git a/files/en-us/web/api/serviceworkerregistration/cookies/index.md b/files/en-us/web/api/serviceworkerregistration/cookies/index.md index f05d23e36cec839..e7c966d862ee6e2 100644 --- a/files/en-us/web/api/serviceworkerregistration/cookies/index.md +++ b/files/en-us/web/api/serviceworkerregistration/cookies/index.md @@ -3,12 +3,10 @@ title: "ServiceWorkerRegistration: cookies property" short-title: cookies slug: Web/API/ServiceWorkerRegistration/cookies page-type: web-api-instance-property -status: - - experimental browser-compat: api.ServiceWorkerRegistration.cookies --- -{{APIRef("Cookie Store API")}}{{SeeCompatTable}}{{SecureContext_Header}}{{AvailableInWorkers("window_and_service")}} +{{APIRef("Cookie Store API")}}{{SecureContext_Header}}{{AvailableInWorkers("window_and_service")}} The **`cookies`** read-only property of the {{domxref("ServiceWorkerRegistration")}} interface returns a reference to the {{domxref("CookieStoreManager")}} interface, which enables a web app to subscribe to and unsubscribe from cookie change events in a [service worker](/en-US/docs/Web/API/Service_Worker_API). This is an entry point for the [Cookie Store API](/en-US/docs/Web/API/Cookie_Store_API). diff --git a/files/en-us/web/api/serviceworkerregistration/index.md b/files/en-us/web/api/serviceworkerregistration/index.md index 816d7a1c553491b..314db54fccaa3ae 100644 --- a/files/en-us/web/api/serviceworkerregistration/index.md +++ b/files/en-us/web/api/serviceworkerregistration/index.md @@ -21,7 +21,7 @@ _Also inherits properties from its parent interface,_ {{domxref("EventTarget")}} - : Returns a service worker whose state is `activating` or `activated`. This is initially set to `null`. An active worker will control a {{domxref("Client")}} if the client's URL falls within the scope of the registration (the `scope` option set when {{domxref("ServiceWorkerContainer.register")}} is first called.) - {{domxref("ServiceWorkerRegistration.backgroundFetch")}} {{ReadOnlyInline}} {{Experimental_Inline}} - : Returns a reference to a {{domxref("BackgroundFetchManager")}} object, which manages background fetch operations. -- {{domxref("ServiceWorkerRegistration.cookies")}} {{ReadOnlyInline}} {{Experimental_Inline}} +- {{domxref("ServiceWorkerRegistration.cookies")}} {{ReadOnlyInline}} - : Returns a reference to the {{domxref("CookieStoreManager")}} interface, which allows subscribe and unsubscribe to cookie change events. - {{domxref("ServiceWorkerRegistration.index")}} {{ReadOnlyInline}} {{Experimental_Inline}} - : Returns a reference to the {{domxref("ContentIndex")}} interface, for managing indexed content for offline viewing. diff --git a/files/en-us/web/api/serviceworkerregistration/paymentmanager/index.md b/files/en-us/web/api/serviceworkerregistration/paymentmanager/index.md index 1e3bcd69124a101..de855bde990250c 100644 --- a/files/en-us/web/api/serviceworkerregistration/paymentmanager/index.md +++ b/files/en-us/web/api/serviceworkerregistration/paymentmanager/index.md @@ -26,10 +26,10 @@ navigator.serviceWorker.register("serviceworker.js").then((registration) => { registration.paymentManager .enableDelegations(["shippingAddress", "payerName"]) .then(() => { - // ... + // … }); - // ... + // … }); ``` diff --git a/files/en-us/web/api/serviceworkerregistration/updatefound_event/index.md b/files/en-us/web/api/serviceworkerregistration/updatefound_event/index.md index 41e06490ed9a7a9..27b53082b58ec26 100644 --- a/files/en-us/web/api/serviceworkerregistration/updatefound_event/index.md +++ b/files/en-us/web/api/serviceworkerregistration/updatefound_event/index.md @@ -15,10 +15,10 @@ The **`updatefound`** event of the Use the event name in methods like {{domxref("EventTarget.addEventListener", "addEventListener()")}}, or set an event handler property. -```js -addEventListener("updatefound", (event) => {}); +```js-nolint +addEventListener("updatefound", (event) => { }) -onupdatefound = (event) => {}; +onupdatefound = (event) => { } ``` ## Event type diff --git a/files/en-us/web/api/shadowroot/clonable/index.md b/files/en-us/web/api/shadowroot/clonable/index.md index 26228ca588794a8..c7781afeb5b4ba7 100644 --- a/files/en-us/web/api/shadowroot/clonable/index.md +++ b/files/en-us/web/api/shadowroot/clonable/index.md @@ -13,7 +13,7 @@ The **`clonable`** read-only property of the {{domxref("ShadowRoot")}} interface When the value is `true`, a shadow host cloned with {{domxref("Node.cloneNode()")}} or {{domxref("Document.importNode()")}} will include a copy of the shadow root. By default the value is `false`. -It can be set to `true` using the `clonable` option of the {{domxref("Element.attachShadow()")}} method or by setting the [`shadowrootclonable`](/en-US/docs/Web/HTML/Element/template#shadowrootclonable) attribute of the `<template>` element that is being used to declaratively attach a shadow root. +It can be set to `true` using the `clonable` option of the {{domxref("Element.attachShadow()")}} method or by setting the [`shadowrootclonable`](/en-US/docs/Web/HTML/Reference/Elements/template#shadowrootclonable) attribute of the `<template>` element that is being used to declaratively attach a shadow root. ## Value diff --git a/files/en-us/web/api/shadowroot/delegatesfocus/index.md b/files/en-us/web/api/shadowroot/delegatesfocus/index.md index db917dc99abb6b6..02fb83b5989d9ee 100644 --- a/files/en-us/web/api/shadowroot/delegatesfocus/index.md +++ b/files/en-us/web/api/shadowroot/delegatesfocus/index.md @@ -14,7 +14,7 @@ If `true`, when a non-focusable part of the shadow DOM is clicked, or `.focus()` Focus is of particular importance for keyboard users (including those using screen readers). `delegatesFocus` default behavior is to focus the first focusable element — which may be undesirable if that element is not meant to be part of the tabbing order (for example, an element with `tabindex="-1"`), or if a more 'important' focusable element should receive initial focus (for instance, the first text field rather than the 'close' button which precedes it). In such cases, the `autofocus` attribute can be specified on the element which should receive initial focus. Use the `autofocus` attribute with caution as it can introduce accessibility issues, such as bypassing important content which may go unnoticed due to focus being set to an element later in the DOM order. -The property value is originally set using the `delegatesFocus` property of the object passed to {{domxref("Element.attachShadow()")}}, or using the [`shadowrootdelegatesfocus`](/en-US/docs/Web/HTML/Element/template#shadowrootclonable) attribute of the [`<template>`](/en-US/docs/Web/HTML/Element/template) element when a shadow root is created declaratively. +The property value is originally set using the `delegatesFocus` property of the object passed to {{domxref("Element.attachShadow()")}}, or using the [`shadowrootdelegatesfocus`](/en-US/docs/Web/HTML/Reference/Elements/template#shadowrootclonable) attribute of the [`<template>`](/en-US/docs/Web/HTML/Reference/Elements/template) element when a shadow root is created declaratively. ## Value @@ -23,16 +23,16 @@ The property value is originally set using the `delegatesFocus` property of the ## Examples ```js -let customElem = document.querySelector("my-shadow-dom-element"); -let shadow = customElem.shadowRoot; +const customElem = document.querySelector("my-shadow-dom-element"); +const shadow = customElem.shadowRoot; -// ... +// … // Does it delegate focus? -let hostElem = shadow.delegatesFocus; +const hostElem = shadow.delegatesFocus; ``` -The [Declarative Shadow DOM with delegated focus](/en-US/docs/Web/HTML/Element/template#declarative_shadow_dom_with_delegated_focus) example in the `<template>` documentation demonstrates the effects of delegating focus. +The [Declarative Shadow DOM with delegated focus](/en-US/docs/Web/HTML/Reference/Elements/template#declarative_shadow_dom_with_delegated_focus) example in the `<template>` documentation demonstrates the effects of delegating focus. ## Specifications diff --git a/files/en-us/web/api/shadowroot/gethtml/index.md b/files/en-us/web/api/shadowroot/gethtml/index.md index 3c16090f561c58a..850f1ab3187dadb 100644 --- a/files/en-us/web/api/shadowroot/gethtml/index.md +++ b/files/en-us/web/api/shadowroot/gethtml/index.md @@ -15,6 +15,9 @@ The options can be used to include nested shadow roots that have been set as {{d Without arguments, child nodes that are shadow roots are not serialized, and this method behaves in the same way as reading the value of {{domxref("Element.innerHTML")}}. +Note that some browsers serialize `<` and `>` in attributes as `&lt;` and `&gt;` in the returned HTML (see [Browser compatibility](#browser_compatibility)). +This prevents certain exploits where code becomes executable when serialized and then deserialized into HTML. + ## Syntax ```js-nolint diff --git a/files/en-us/web/api/shadowroot/host/index.md b/files/en-us/web/api/shadowroot/host/index.md index 8ae55bbdca2ba90..5f6796bd5310f1b 100644 --- a/files/en-us/web/api/shadowroot/host/index.md +++ b/files/en-us/web/api/shadowroot/host/index.md @@ -19,13 +19,13 @@ A DOM {{domxref('Element')}}. ## Examples ```js -let customElem = document.querySelector("my-shadow-dom-element"); -let shadow = customElem.shadowRoot; +const customElem = document.querySelector("my-shadow-dom-element"); +const shadow = customElem.shadowRoot; -// ... +// … // return the original host element some time later -let hostElem = shadow.host; +const hostElem = shadow.host; ``` ## Specifications @@ -38,7 +38,7 @@ let hostElem = shadow.host; ## See also -- [`part`](/en-US/docs/Web/HTML/Global_attributes/part) and [`exportparts`](/en-US/docs/Web/HTML/Global_attributes/exportparts) HTML attributes +- [`part`](/en-US/docs/Web/HTML/Reference/Global_attributes/part) and [`exportparts`](/en-US/docs/Web/HTML/Reference/Global_attributes/exportparts) HTML attributes - {{HTMLelement("template")}} and {{HTMLElement("slot")}} HTML elements - {{CSSXref(":host")}}, {{CSSXref(":host_function", ":host()")}}, and {{CSSXref(":host-context", ":host-context()")}} CSS pseudo-classes - {{CSSXref("::part")}} and {{CSSXref("::slotted")}} CSS pseudo-elements diff --git a/files/en-us/web/api/shadowroot/index.md b/files/en-us/web/api/shadowroot/index.md index c17f8ad430d2192..127744d855ae034 100644 --- a/files/en-us/web/api/shadowroot/index.md +++ b/files/en-us/web/api/shadowroot/index.md @@ -58,7 +58,7 @@ You can retrieve a reference to an element's shadow root using its {{domxref("El - {{domxref("ShadowRoot.elementsFromPoint()")}} {{Non-standard_Inline}} - : Returns an array of all elements at the specified coordinates. - {{DOMxRef("ShadowRoot.setHTMLUnsafe()")}} - - : Parses a string of HTML into a document fragment, without sanitization, which then replaces the shadowroot's original subtree. The HTML string may include declarative shadow roots, which would be parsed as template elements the HTML was set using [`ShadowRoot.innerHTML`](#shadowroot.innerhtml). + - : Parses a string of HTML into a document fragment, without sanitization, which then replaces the shadowroot's original subtree. The HTML string may include declarative shadow roots, which would be parsed as template elements the HTML was set using [`ShadowRoot.innerHTML`](/en-US/docs/Web/API/ShadowRoot/innerHTML). ## Events @@ -74,14 +74,18 @@ The following snippets are taken from our [life-cycle-callbacks](https://github. Inside the `<custom-square>` element's class definition we include some life cycle callbacks that make a call to an external function, `updateStyle()`, which actually applies the size and color to the element. You'll see that we are passing it `this` (the custom element itself) as a parameter. ```js -connectedCallback() { - console.log('Custom square element added to page.'); - updateStyle(this); -} +class Square extends HTMLElement { + // … + connectedCallback() { + console.log("Custom square element added to page."); + updateStyle(this); + } -attributeChangedCallback(name, oldValue, newValue) { - console.log('Custom square element attributes changed.'); - updateStyle(this); + attributeChangedCallback(name, oldValue, newValue) { + console.log("Custom square element attributes changed."); + updateStyle(this); + } + // … } ``` diff --git a/files/en-us/web/api/shadowroot/innerhtml/index.md b/files/en-us/web/api/shadowroot/innerhtml/index.md index ea55fd8ec58d7d4..d015a7d30605b3f 100644 --- a/files/en-us/web/api/shadowroot/innerhtml/index.md +++ b/files/en-us/web/api/shadowroot/innerhtml/index.md @@ -8,9 +8,10 @@ browser-compat: api.ShadowRoot.innerHTML {{APIRef("Shadow DOM")}} -The **`innerHTML`** property of the {{domxref("ShadowRoot")}} -interface sets or returns a reference to the DOM tree inside the -`ShadowRoot`. +The **`innerHTML`** property of the {{domxref("ShadowRoot")}} interface sets gets or sets the HTML markup to the DOM tree inside the `ShadowRoot`. + +Note that some browsers serialize `<` and `>` in attributes as `&lt;` and `&gt;` when reading the HTML (see [Browser compatibility](#browser_compatibility)). +This prevents certain exploits where code becomes executable when serialized and then deserialized into HTML. ## Value @@ -20,6 +21,8 @@ When set to the `null` value, that `null` value is converted to the empty string ## Examples +### Setting the innerHTML of a Shadow root + ```js let customElem = document.querySelector("my-shadow-dom-element"); let shadow = customElem.shadowRoot; diff --git a/files/en-us/web/api/shadowroot/mode/index.md b/files/en-us/web/api/shadowroot/mode/index.md index 27882053cb8e5d7..85bcba789252dd2 100644 --- a/files/en-us/web/api/shadowroot/mode/index.md +++ b/files/en-us/web/api/shadowroot/mode/index.md @@ -13,7 +13,7 @@ This defines whether or not the shadow root's internal features are accessible f When the `mode` of a shadow root is `"closed"`, the shadow root's implementation internals are inaccessible and unchangeable from JavaScript—in the same way the implementation internals of, for example, the {{HTMLElement("video")}} element are inaccessible and unchangeable from JavaScript. -The property value is set using the `options.mode` property of the object passed to {{domxref("Element.attachShadow()")}}, or using the [`shadowrootmode`](/en-US/docs/Web/HTML/Element/template#shadowrootmode) attribute of the [`<template>`](/en-US/docs/Web/HTML/Element/template) element when a shadow root is created declaratively. +The property value is set using the `options.mode` property of the object passed to {{domxref("Element.attachShadow()")}}, or using the [`shadowrootmode`](/en-US/docs/Web/HTML/Reference/Elements/template#shadowrootmode) attribute of the [`<template>`](/en-US/docs/Web/HTML/Reference/Elements/template) element when a shadow root is created declaratively. ## Value diff --git a/files/en-us/web/api/shadowroot/serializable/index.md b/files/en-us/web/api/shadowroot/serializable/index.md index 189793fbfacd1e1..7c40ab4daacd250 100644 --- a/files/en-us/web/api/shadowroot/serializable/index.md +++ b/files/en-us/web/api/shadowroot/serializable/index.md @@ -12,7 +12,7 @@ The **`serializable`** read-only property of the {{domxref("ShadowRoot")}} inter If set, the shadow root may be serialized by calling the {{DOMxRef('Element.getHTML()')}} or {{DOMxRef('ShadowRoot.getHTML()')}} methods with the `options.serializableShadowRoots` parameter set `true`. -The serializable property of a shadow root is specified when the shadow root is created, either declaratively by adding the [`shadowrootserializable`](/en-US/docs/Web/HTML/Element/template#shadowrootserializable) attribute on a `<template>` element (along with an allowed [`shadowrootmode`](/en-US/docs/Web/HTML/Element/template#shadowrootmode) value), or by setting the [`options.serializable`](/en-US/docs/Web/API/Element/attachShadow#serializable) parameter to `true` when using [`Element.attachShadow()`](/en-US/docs/Web/API/Element/attachShadow). +The serializable property of a shadow root is specified when the shadow root is created, either declaratively by adding the [`shadowrootserializable`](/en-US/docs/Web/HTML/Reference/Elements/template#shadowrootserializable) attribute on a `<template>` element (along with an allowed [`shadowrootmode`](/en-US/docs/Web/HTML/Reference/Elements/template#shadowrootmode) value), or by setting the [`options.serializable`](/en-US/docs/Web/API/Element/attachShadow#serializable) parameter to `true` when using [`Element.attachShadow()`](/en-US/docs/Web/API/Element/attachShadow). ## Value @@ -21,13 +21,13 @@ The serializable property of a shadow root is specified when the shadow root is ## Examples ```js -let customElem = document.querySelector("my-shadow-dom-element"); -let shadow = customElem.shadowRoot; +const customElem = document.querySelector("my-shadow-dom-element"); +const shadow = customElem.shadowRoot; -// ... +// … // Is it serializable? -let hostElem = shadow.serializable; +const hostElem = shadow.serializable; ``` ## Specifications diff --git a/files/en-us/web/api/shadowroot/sethtmlunsafe/index.md b/files/en-us/web/api/shadowroot/sethtmlunsafe/index.md index bd065d83dbfd801..c8c01df962c9975 100644 --- a/files/en-us/web/api/shadowroot/sethtmlunsafe/index.md +++ b/files/en-us/web/api/shadowroot/sethtmlunsafe/index.md @@ -9,11 +9,11 @@ browser-compat: api.ShadowRoot.setHTMLUnsafe {{APIRef("Shadow DOM")}} The **`setHTMLUnsafe()`** method of the {{domxref("ShadowRoot")}} interface is used to parse a string of HTML into a {{domxref("DocumentFragment")}}, which then replaces the element's subtree in the DOM. -The input HTML may include [declarative shadow roots](/en-US/docs/Web/HTML/Element/template#declarative_shadow_dom). +The input HTML may include [declarative shadow roots](/en-US/docs/Web/HTML/Reference/Elements/template#declarative_shadow_dom). The suffix "Unsafe" in the method name indicates that the method does not sanitize or remove potentially unsafe XSS-relevant input, such as `<script>` elements, and script or event handler content attributes. -If the string of HTML defines more than one [declarative shadow root](/en-US/docs/Web/HTML/Element/template#declarative_shadow_dom) in a particular shadow host then only the first {{domxref("ShadowRoot")}} is created — subsequent declarations are parsed as `<template>` elements within that shadow root. +If the string of HTML defines more than one [declarative shadow root](/en-US/docs/Web/HTML/Reference/Elements/template#declarative_shadow_dom) in a particular shadow host then only the first {{domxref("ShadowRoot")}} is created — subsequent declarations are parsed as `<template>` elements within that shadow root. > [!NOTE] > This method should be used instead of {{domxref("ShadowRoot.innerHTML")}} when a string of HTML may contain declarative shadow roots. diff --git a/files/en-us/web/api/shared_storage_api/index.md b/files/en-us/web/api/shared_storage_api/index.md index 53f6b2f831d983a..ce11edc30aa7f59 100644 --- a/files/en-us/web/api/shared_storage_api/index.md +++ b/files/en-us/web/api/shared_storage_api/index.md @@ -9,13 +9,17 @@ browser-compat: api.SharedStorage {{SeeCompatTable}}{{DefaultAPISidebar("Shared Storage API")}} -The **Shared Storage API** is a client-side storage mechanism that enables unpartitioned, cross-site data access while preserving privacy (i.e. without relying on tracking cookies). +> [!WARNING] +> This feature is currently opposed by one browser vendor. +> See the [Standards positions](#standards_positions) section below for details. + +The **Shared Storage API** is a client-side storage mechanism that enables unpartitioned, cross-site data access while preserving privacy (i.e., without relying on tracking cookies). ## Concepts and usage One major source of [privacy](/en-US/docs/Web/Privacy) and [security](/en-US/docs/Web/Security) problems on the web is the use of cookies set on third-party content embedded in sites (for example via {{htmlelement("iframe")}} elements). These cookies can be used to track and profile users, and share information across sites. -To prevent cross-site tracking, browsers are working towards partitioning all storage types, including [Cookies](/en-US/docs/Web/HTTP/Cookies), [Web Storage](/en-US/docs/Web/API/Web_Storage_API), [IndexedDB](/en-US/docs/Web/API/IndexedDB_API), and the [Cache API](/en-US/docs/Web/API/Cache). However, a major barrier to achieving this is the need for several legitimate use cases that rely on cross-site information sharing. Examples of such use cases include advertisers wanting to measure the reach of their ads across sites and generate reports, and site owners wanting to customize user experiences based on the group they are in or their previous site interactions. +To prevent cross-site tracking, browsers are working towards partitioning all storage types, including [Cookies](/en-US/docs/Web/HTTP/Guides/Cookies), [Web Storage](/en-US/docs/Web/API/Web_Storage_API), [IndexedDB](/en-US/docs/Web/API/IndexedDB_API), and the [Cache API](/en-US/docs/Web/API/Cache). However, a major barrier to achieving this is the need for several legitimate use cases that rely on cross-site information sharing. Examples of such use cases include advertisers wanting to measure the reach of their ads across sites and generate reports, and site owners wanting to customize user experiences based on the group they are in or their previous site interactions. The Shared Storage API provides a flexible solution for such use cases. It aims to provide the required data storage, processing, and sharing capabilities without the ability to track and profile users. @@ -34,23 +38,23 @@ The currently available output gates for the Shared Storage API are discussed in The **URL Selection** output gate, accessed via the {{domxref("WindowSharedStorage.selectURL", "selectURL()")}} method, is used to select a URL from a provided list to display to the user, based on shared storage data. This gate be used for the following purposes: -- [**Creative rotation**](https://developers.google.com/privacy-sandbox/private-advertising/shared-storage/creative-rotation): Use stored data such as creative IDs, view counts, and user interaction to determine which creative content users see across different sites. This approach helps in balancing views and prevents overexposure of certain content, which in turn can help avoid a negative user experience. -- [**A/B testing**](https://developers.google.com/privacy-sandbox/private-advertising/shared-storage/ab-testing): Assign a user to an experiment group, then store group details in shared storage for cross-site access. -- [**Custom user experiences**](https://developers.google.com/privacy-sandbox/private-advertising/shared-storage/known-customer): Share custom content and calls-to-action based on a user's registration status or other user states. +- [**Creative rotation**](https://privacysandbox.google.com/private-advertising/select-url/creative-rotation): Use stored data such as creative IDs, view counts, and user interaction to determine which creative content users see across different sites. This approach helps in balancing views and prevents overexposure of certain content, which in turn can help avoid a negative user experience. +- [**A/B testing**](https://privacysandbox.google.com/private-advertising/select-url/ab-testing): Assign a user to an experiment group, then store group details in shared storage for cross-site access. +- [**Custom user experiences**](https://privacysandbox.google.com/private-advertising/select-url/known-customer): Share custom content and calls-to-action based on a user's registration status or other user states. ### Run The **Run** output gate, accessed via the {{domxref("WindowSharedStorage.run", "run()")}} method, is intended to be used in a generic way to process some shared storage data. -The [Private Aggregation API](https://developers.google.com/privacy-sandbox/private-advertising/private-aggregation) can use the Run output gate to process shared storage data and generate aggregated reports. These reports can be used in the following use cases: +The [Private Aggregation API](https://privacysandbox.google.com/private-advertising/private-aggregation) can use the Run output gate to process shared storage data and generate aggregated reports. These reports can be used in the following use cases: -- [**Unique reach reporting**](https://developers.google.com/privacy-sandbox/private-advertising/private-aggregation/unique-reach): Content producers and advertisers often want to know the number of unique viewers for their content. You can use shared storage to report the first time a user sees your ad or embedded publication and prevent duplicate counting for the same user on a different site, giving you an aggregated noisy report of approximate unique reach. -- [**User demographic reporting**](https://developers.google.com/privacy-sandbox/private-advertising/private-aggregation/user-demographics): Content producers often want to understand the demographics of their audience. You can use shared storage to record user demographic data on your main site, and use aggregated reporting to report on it across other sites in embedded contexts. -- [**K+ frequency measurement**](https://developers.google.com/privacy-sandbox/private-advertising/private-aggregation/k-freq-reach): Sometimes described as "effective frequency", K+ frequency refers to the minimum number of views needed before a user will recognize or recall certain content (often used in the context of ad views). You can use shared storage to build reports of unique users who have seen a piece of content at least K times. +- [**Unique reach reporting**](https://privacysandbox.google.com/private-advertising/private-aggregation/unique-reach): Content producers and advertisers often want to know the number of unique viewers for their content. You can use shared storage to report the first time a user sees your ad or embedded publication and prevent duplicate counting for the same user on a different site, giving you an aggregated noisy report of approximate unique reach. +- [**User demographic reporting**](https://privacysandbox.google.com/private-advertising/private-aggregation/user-demographics): Content producers often want to understand the demographics of their audience. You can use shared storage to record user demographic data on your main site, and use aggregated reporting to report on it across other sites in embedded contexts. +- [**K+ frequency measurement**](https://privacysandbox.google.com/private-advertising/private-aggregation/k-freq-reach): Sometimes described as "effective frequency", K+ frequency refers to the minimum number of views needed before a user will recognize or recall certain content (often used in the context of ad views). You can use shared storage to build reports of unique users who have seen a piece of content at least K times. ## Understanding how shared storage works -There are two parts to using the Shared Storage API — writing data to storage and reading/processing it. To give you an idea of how these parts are handled, we'll walk you through the basic [A/B testing](https://developers.google.com/privacy-sandbox/private-advertising/shared-storage/ab-testing) example from developer.chrome.com. In this example, a user is assigned to an experiment group, and the group details are stored in shared storage. Other sites are able to use this data when choosing a URL to display in a [fenced frame](/en-US/docs/Web/API/Fenced_frame_API). +There are two parts to using the Shared Storage API — writing data to storage and reading/processing it. To give you an idea of how these parts are handled, we'll walk you through the basic [A/B testing](https://privacysandbox.google.com/private-advertising/select-url/ab-testing) example from developer.chrome.com. In this example, a user is assigned to an experiment group, and the group details are stored in shared storage. Other sites are able to use this data when choosing a URL to display in a [fenced frame](/en-US/docs/Web/API/Fenced_frame_API). ### Writing to shared storage @@ -261,11 +265,18 @@ For extensive demos, see the [Shared Storage API demo site](https://shared-stora {{Specifications}} +### Standards positions + +One browser vendor [opposes](/en-US/docs/Glossary/Web_standards#opposing_standards) this specification. +Known standards positions are as follows: + +- Mozilla (Firefox): [Negative](https://github.com/mozilla/standards-positions/issues/646) + ## Browser compatibility {{Compat}} ## See also -- [Shared Storage](https://developers.google.com/privacy-sandbox/private-advertising/shared-storage) on developers.google.com -- [The Privacy Sandbox](https://developers.google.com/privacy-sandbox) on developers.google.com +- [Shared Storage](https://privacysandbox.google.com/private-advertising/shared-storage) on privacysandbox.google.com +- [The Privacy Sandbox](https://privacysandbox.google.com/) on privacysandbox.google.com diff --git a/files/en-us/web/api/sharedstorageoperation/index.md b/files/en-us/web/api/sharedstorageoperation/index.md index afed700d7c18ed4..51ef8245d1b0047 100644 --- a/files/en-us/web/api/sharedstorageoperation/index.md +++ b/files/en-us/web/api/sharedstorageoperation/index.md @@ -31,7 +31,7 @@ The output gate types are detailed below: </tr> <tr> <td>Run</td> - <td>A generic way to process some shared storage data. Used, for example, by the <a href="https://developers.google.com/privacy-sandbox/private-advertising/private-aggregation">Private Aggregation API</a> to process shared storage data and generate aggregated reports. </td> + <td>A generic way to process some shared storage data. Used, for example, by the <a href="https://privacysandbox.google.com/private-advertising/private-aggregation">Private Aggregation API</a> to process shared storage data and generate aggregated reports. </td> <td>{{domxref("SharedStorageRunOperation")}}</td> <td>{{domxref("WindowSharedStorage.run()", "run()")}}</td> </tr> diff --git a/files/en-us/web/api/sharedstoragerunoperation/index.md b/files/en-us/web/api/sharedstoragerunoperation/index.md index ab3996af4ae2676..78518188a0645ce 100644 --- a/files/en-us/web/api/sharedstoragerunoperation/index.md +++ b/files/en-us/web/api/sharedstoragerunoperation/index.md @@ -78,7 +78,7 @@ async function measureUniqueReach() { measureUniqueReach(); ``` -For more details about this example, see [Unique reach measurement](https://developers.google.com/privacy-sandbox/private-advertising/private-aggregation/unique-reach). See [Shared Storage API](/en-US/docs/Web/API/Shared_Storage_API) for more examples. +For more details about this example, see [Unique reach measurement](https://privacysandbox.google.com/private-advertising/private-aggregation/unique-reach). See [Shared Storage API](/en-US/docs/Web/API/Shared_Storage_API) for more examples. ## Specifications diff --git a/files/en-us/web/api/sharedworker/error_event/index.md b/files/en-us/web/api/sharedworker/error_event/index.md index 07a7c7dea1eaad5..8d644ebee5946a3 100644 --- a/files/en-us/web/api/sharedworker/error_event/index.md +++ b/files/en-us/web/api/sharedworker/error_event/index.md @@ -14,10 +14,10 @@ The **`error`** event of the {{domxref("SharedWorker")}} interface fires when an Use the event name in methods like {{domxref("EventTarget.addEventListener", "addEventListener()")}}, or set an event handler property. -```js -addEventListener("error", (event) => {}); +```js-nolint +addEventListener("error", (event) => { }) -onerror = (event) => {}; +onerror = (event) => { } ``` ## Event type diff --git a/files/en-us/web/api/sharedworker/sharedworker/index.md b/files/en-us/web/api/sharedworker/sharedworker/index.md index 1e121a4abdcd41b..a8ce8637920bad4 100644 --- a/files/en-us/web/api/sharedworker/sharedworker/index.md +++ b/files/en-us/web/api/sharedworker/sharedworker/index.md @@ -54,7 +54,7 @@ new SharedWorker(aURL, options) identifying name for the {{domxref("SharedWorkerGlobalScope")}} representing the scope of the worker, which is mainly useful for debugging purposes. - `sameSiteCookies` - - : A string indicating which [`SameSite` cookies](/en-US/docs/Web/HTTP/Headers/Set-Cookie#samesitesamesite-value) + - : A string indicating which [`SameSite` cookies](/en-US/docs/Web/HTTP/Reference/Headers/Set-Cookie#samesitesamesite-value) should be available to the worker. Can have one of the following two values: - 'all' - : `SameSite=Strict`, `SameSite=Lax`, and `SameSite=None` cookies will all be available to the worker. @@ -68,7 +68,7 @@ new SharedWorker(aURL, options) - `SecurityError` {{domxref("DOMException")}} - : Thrown if the document is not allowed to start workers, for example if the URL has an invalid syntax or if the same-origin policy is violated, or if the `sameSiteCookies` value is not supported in the given context. - `NetworkError` {{domxref("DOMException")}} - - : Thrown if the MIME type of the worker script is incorrect. It should _always_ be `text/javascript` (for historical reasons [other JavaScript MIME types](/en-US/docs/Web/HTTP/MIME_types#textjavascript) may be accepted). + - : Thrown if the MIME type of the worker script is incorrect. It should _always_ be `text/javascript` (for historical reasons [other JavaScript MIME types](/en-US/docs/Web/HTTP/Guides/MIME_types#textjavascript) may be accepted). - `SyntaxError` {{domxref("DOMException")}} - : Thrown if `aURL` cannot be parsed. diff --git a/files/en-us/web/api/sharedworkerglobalscope/connect_event/index.md b/files/en-us/web/api/sharedworkerglobalscope/connect_event/index.md index c2a024896b81aa7..1899e24cdb3ab39 100644 --- a/files/en-us/web/api/sharedworkerglobalscope/connect_event/index.md +++ b/files/en-us/web/api/sharedworkerglobalscope/connect_event/index.md @@ -16,10 +16,10 @@ This event is not cancelable and does not bubble. Use the event name in methods like {{domxref("EventTarget.addEventListener", "addEventListener()")}}, or set an event handler property. -```js -addEventListener("connect", (event) => {}); +```js-nolint +addEventListener("connect", (event) => { }) -onconnect = (event) => {}; +onconnect = (event) => { } ``` ## Event type @@ -41,7 +41,7 @@ _This interface also inherits properties from its parent, {{domxref("Event")}}._ - {{domxref("MessageEvent.source")}} {{ReadOnlyInline}} - : A `MessageEventSource` (which can be a {{glossary("WindowProxy")}}, {{domxref("MessagePort")}}, or {{domxref("ServiceWorker")}} object) representing the message emitter. - {{domxref("MessageEvent.ports")}} {{ReadOnlyInline}} - - : An array of {{domxref("MessagePort")}} objects representing the ports associated with the channel the message is being sent through (where appropriate, e.g. in channel messaging or when sending a message to a shared worker). + - : An array of {{domxref("MessagePort")}} objects representing the ports associated with the channel the message is being sent through (where appropriate, e.g., in channel messaging or when sending a message to a shared worker). ## Examples diff --git a/files/en-us/web/api/snapevent/index.md b/files/en-us/web/api/snapevent/index.md index b48e2c8509cf5b0..75fcd175df1c1c9 100644 --- a/files/en-us/web/api/snapevent/index.md +++ b/files/en-us/web/api/snapevent/index.md @@ -9,7 +9,7 @@ browser-compat: api.SnapEvent {{APIRef("Snap Events")}}{{SeeCompatTable}} -The **`SnapEvent`** interface defines the event object for the {{domxref("Element/scrollsnapchanging_event", "scrollsnapchanging")}} and {{domxref("Element/scrollsnapchange_event", "scrollsnapchange")}} events. Respectively, these fire on on a [scroll container](/en-US/docs/Glossary/Scroll_container) when the browser determines that a new scroll snap target is pending (will be selected when the current scroll gesture ends), and when a new snap target is selected. +The **`SnapEvent`** interface defines the event object for the {{domxref("Element/scrollsnapchanging_event", "scrollsnapchanging")}} and {{domxref("Element/scrollsnapchange_event", "scrollsnapchange")}} events. Respectively, these fire on a [scroll container](/en-US/docs/Glossary/Scroll_container) when the browser determines that a new scroll snap target is pending (will be selected when the current scroll gesture ends), and when a new snap target is selected. These events can be used to run code in response to new elements being snapped to; `SnapEvent` exposes references to the element snapped to in the inline and/or block direction. The property values available on `SnapEvent` correspond directly to the value of the {{cssxref("scroll-snap-type")}} CSS property set on the scroll container: diff --git a/files/en-us/web/api/snapevent/snapevent/index.md b/files/en-us/web/api/snapevent/snapevent/index.md index 6d2ec9c581bcbf1..8e961760df2420e 100644 --- a/files/en-us/web/api/snapevent/snapevent/index.md +++ b/files/en-us/web/api/snapevent/snapevent/index.md @@ -38,7 +38,7 @@ For example: ```js mainElem.addEventListener("scrollsnapchange", (event) => { - // ... + // … // Log a SnapEvent object instance to the console console.log(event); diff --git a/files/en-us/web/api/snapevent/snaptargetblock/index.md b/files/en-us/web/api/snapevent/snaptargetblock/index.md index 0cb33761a44e0a1..7a9e103838d208c 100644 --- a/files/en-us/web/api/snapevent/snaptargetblock/index.md +++ b/files/en-us/web/api/snapevent/snaptargetblock/index.md @@ -15,7 +15,7 @@ The **`snapTargetBlock`** read-only property of the Specifically: -- In the case of the {{domxref("Element/scrollsnapchanging_event", "scrollsnapchanging")}} event, this refers to a pending block-direction snap target (i.e. it will be selected when the current scroll gesture ends). +- In the case of the {{domxref("Element/scrollsnapchanging_event", "scrollsnapchanging")}} event, this refers to a pending block-direction snap target (i.e., it will be selected when the current scroll gesture ends). - In the case of the {{domxref("Element/scrollsnapchange_event", "scrollsnapchange")}} event, this refers to a newly-selected block-direction snap target. The property values available on `SnapEvent` correspond directly to the value of the {{cssxref("scroll-snap-type")}} CSS property set on the scroll container. `snapTargetBlock` only returns an element reference if the snap axis is specified as `block` (or a physical axis value that equates to `block` in the current writing mode) or `both`. diff --git a/files/en-us/web/api/snapevent/snaptargetinline/index.md b/files/en-us/web/api/snapevent/snaptargetinline/index.md index 719671989227100..ab9b1a805c9b11c 100644 --- a/files/en-us/web/api/snapevent/snaptargetinline/index.md +++ b/files/en-us/web/api/snapevent/snaptargetinline/index.md @@ -15,7 +15,7 @@ The **`snapTargetInline`** read-only property of the Specifically: -- In the case of the {{domxref("Element/scrollsnapchanging_event", "scrollsnapchanging")}} event, this refers to a pending inline-direction snap target (i.e. it will be selected when the current scroll gesture ends). +- In the case of the {{domxref("Element/scrollsnapchanging_event", "scrollsnapchanging")}} event, this refers to a pending inline-direction snap target (i.e., it will be selected when the current scroll gesture ends). - In the case of the {{domxref("Element/scrollsnapchange_event", "scrollsnapchange")}} event, this refers to a newly-selected inline-direction snap target. The property values available on `SnapEvent` correspond directly to the value of the {{cssxref("scroll-snap-type")}} CSS property set on the scroll container. `snapTargetInline` only returns an element reference if the snap axis is specified as `inline` (or a physical axis value that equates to `inline` in the current writing mode) or `both`. diff --git a/files/en-us/web/api/sourcebuffer/abort/index.md b/files/en-us/web/api/sourcebuffer/abort/index.md index 6603c9886326484..a22839ddf6fab35 100644 --- a/files/en-us/web/api/sourcebuffer/abort/index.md +++ b/files/en-us/web/api/sourcebuffer/abort/index.md @@ -45,14 +45,14 @@ immediately start performing operations on it again. For example, consider this ```js sourceBuffer.addEventListener("updateend", (ev) => { - // ... + // … }); sourceBuffer.appendBuffer(buf); ``` Let's say that after the call to `appendBuffer` BUT before the -`updateend` event fires (i.e. a buffer is being appended but the operation +`updateend` event fires (i.e., a buffer is being appended but the operation has not yet completed) a user "scrubs" the video seeking to a new point in time. In this case you would want to manually call `abort()` on the source buffer to stop the decoding of the current buffer, then fetch and append the newly requested diff --git a/files/en-us/web/api/sourcebuffer/appendwindowend/index.md b/files/en-us/web/api/sourcebuffer/appendwindowend/index.md index 3a4d433925ba1b9..00c3e8f8cb8eb54 100644 --- a/files/en-us/web/api/sourcebuffer/appendwindowend/index.md +++ b/files/en-us/web/api/sourcebuffer/appendwindowend/index.md @@ -28,7 +28,7 @@ The following exceptions may be thrown when setting a new value for this propert - : Thrown if an attempt was made to set the value to less than or equal to {{domxref("SourceBuffer.appendWindowStart")}} or `NaN`. - `InvalidStateError` {{domxref("DOMException")}} - - : Thrown if this {{domxref("SourceBuffer")}} object is being updated (i.e. + - : Thrown if this {{domxref("SourceBuffer")}} object is being updated (i.e., its {{domxref("SourceBuffer.updating")}} property is currently `true`), or this `SourceBuffer` has been removed from the {{domxref("MediaSource")}}. diff --git a/files/en-us/web/api/sourcebuffer/appendwindowstart/index.md b/files/en-us/web/api/sourcebuffer/appendwindowstart/index.md index a8c0680c87d1cba..d66e30df329ad4d 100644 --- a/files/en-us/web/api/sourcebuffer/appendwindowstart/index.md +++ b/files/en-us/web/api/sourcebuffer/appendwindowstart/index.md @@ -30,7 +30,7 @@ The following exceptions may be thrown when setting a new value for this propert than or equal to {{domxref("SourceBuffer.appendWindowEnd")}}. - `InvalidStateError` {{domxref("DOMException")}} - - : Thrown if this {{domxref("SourceBuffer")}} object is being updated (i.e. + - : Thrown if this {{domxref("SourceBuffer")}} object is being updated (i.e., its {{domxref("SourceBuffer.updating")}} property is currently `true`), or this `SourceBuffer` has been removed from the {{domxref("MediaSource")}}. diff --git a/files/en-us/web/api/sourcebuffer/index.md b/files/en-us/web/api/sourcebuffer/index.md index d1d444cb7459d5a..98352e4148621dc 100644 --- a/files/en-us/web/api/sourcebuffer/index.md +++ b/files/en-us/web/api/sourcebuffer/index.md @@ -28,7 +28,7 @@ The **`SourceBuffer`** interface represents a chunk of media to be passed into a - {{domxref("SourceBuffer.timestampOffset")}} - : Controls the offset applied to timestamps inside media segments that are subsequently appended to the `SourceBuffer`. - {{domxref("SourceBuffer.updating")}} {{ReadOnlyInline}} - - : A boolean indicating whether the `SourceBuffer` is currently being updated — i.e. whether an {{domxref("SourceBuffer.appendBuffer()")}} or {{domxref("SourceBuffer.remove()")}} operation is currently in progress. + - : A boolean indicating whether the `SourceBuffer` is currently being updated — i.e., whether an {{domxref("SourceBuffer.appendBuffer()")}} or {{domxref("SourceBuffer.remove()")}} operation is currently in progress. - {{domxref("SourceBuffer.videoTracks")}} {{ReadOnlyInline}} - : A list of the video tracks currently contained inside the `SourceBuffer`. @@ -90,14 +90,13 @@ function loadVideo() { async function sourceOpen() { console.log(this.readyState); // open - const mediaSource = this; - const sourceBuffer = mediaSource.addSourceBuffer(mimeCodec); + const sourceBuffer = this.addSourceBuffer(mimeCodec); const response = await fetch(assetURL); const buffer = await response.arrayBuffer(); sourceBuffer.addEventListener("updateend", () => { - mediaSource.endOfStream(); + this.endOfStream(); video.play(); - console.log(mediaSource.readyState); // ended + console.log(this.readyState); // ended }); sourceBuffer.appendBuffer(buffer); } diff --git a/files/en-us/web/api/sourcebuffer/mode/index.md b/files/en-us/web/api/sourcebuffer/mode/index.md index 7b077b5af6e3ca5..c4e9db58c924def 100644 --- a/files/en-us/web/api/sourcebuffer/mode/index.md +++ b/files/en-us/web/api/sourcebuffer/mode/index.md @@ -48,7 +48,7 @@ The following exceptions may be thrown when setting a new value for this propert - : Thrown if an attempt was made to set the value to `segments` when the initial value is `sequence`. - `InvalidStateError` {{domxref("DOMException")}} - - : Thrown if the {{domxref("SourceBuffer")}} object is being updated (i.e. + - : Thrown if the {{domxref("SourceBuffer")}} object is being updated (i.e., its {{domxref("SourceBuffer.updating")}} property is currently `true`), the last media segment appended to this `SourceBuffer` is incomplete, or this diff --git a/files/en-us/web/api/sourcebuffer/timestampoffset/index.md b/files/en-us/web/api/sourcebuffer/timestampoffset/index.md index dc008338adce7c1..bbd2a0bbfd2df88 100644 --- a/files/en-us/web/api/sourcebuffer/timestampoffset/index.md +++ b/files/en-us/web/api/sourcebuffer/timestampoffset/index.md @@ -25,7 +25,7 @@ The following exception may be thrown when setting a new value for this property - `InvalidStateError` {{domxref("DOMException")}} - : Thrown if one or more of the {{domxref("SourceBuffer")}} objects in {{domxref("MediaSource.sourceBuffers")}} are being updated - (i.e. their {{domxref("SourceBuffer.updating")}} property is + (i.e., their {{domxref("SourceBuffer.updating")}} property is currently `true`), a media segment inside the `SourceBuffer` is currently being parsed, or this `SourceBuffer` has been removed from the diff --git a/files/en-us/web/api/sourcebuffer/updating/index.md b/files/en-us/web/api/sourcebuffer/updating/index.md index 0186e8b14fb63f8..62d162a467485b2 100644 --- a/files/en-us/web/api/sourcebuffer/updating/index.md +++ b/files/en-us/web/api/sourcebuffer/updating/index.md @@ -10,7 +10,7 @@ browser-compat: api.SourceBuffer.updating The **`updating`** read-only property of the {{domxref("SourceBuffer")}} interface indicates whether the `SourceBuffer` is -currently being updated — i.e. whether an {{domxref("SourceBuffer.appendBuffer()")}} or {{domxref("SourceBuffer.remove()")}} +currently being updated — i.e., whether an {{domxref("SourceBuffer.appendBuffer()")}} or {{domxref("SourceBuffer.remove()")}} operation is currently in progress. ## Value diff --git a/files/en-us/web/api/speculation_rules_api/index.md b/files/en-us/web/api/speculation_rules_api/index.md index 0247d8467aa9b99..67335e007ba188f 100644 --- a/files/en-us/web/api/speculation_rules_api/index.md +++ b/files/en-us/web/api/speculation_rules_api/index.md @@ -17,14 +17,14 @@ spec-urls: The **Speculation Rules API** is designed to improve performance for future navigations. It targets document URLs rather than specific resource files, and so makes sense for multi-page applications (MPAs) rather than single-page applications (SPAs). -The Speculation Rules API provides an alternative to the widely-available [`<link rel="prefetch">`](/en-US/docs/Web/HTML/Attributes/rel/prefetch) feature and is designed to supersede the Chrome-only deprecated [`<link rel="prerender">`](/en-US/docs/Web/HTML/Attributes/rel/prerender) feature. It provides many improvements over these technologies, along with a more expressive, configurable syntax for specifying which documents should be prefetched or prerendered. +The Speculation Rules API provides an alternative to the widely-available [`<link rel="prefetch">`](/en-US/docs/Web/HTML/Reference/Attributes/rel/prefetch) feature and is designed to supersede the Chrome-only deprecated [`<link rel="prerender">`](/en-US/docs/Web/HTML/Reference/Attributes/rel/prerender) feature. It provides many improvements over these technologies, along with a more expressive, configurable syntax for specifying which documents should be prefetched or prerendered. > [!NOTE] > The Speculation Rules API doesn't handle subresource prefetches; for that you'll need to use `<link rel="prefetch">`. ## Concepts and usage -Speculation rules can be specified inside inline [`<script type="speculationrules">`](/en-US/docs/Web/HTML/Element/script/type/speculationrules) elements and external text files referenced by the {{httpheader("Speculation-Rules")}} response header. The rules are specified as a JSON structure. +Speculation rules can be specified inside inline [`<script type="speculationrules">`](/en-US/docs/Web/HTML/Reference/Elements/script/type/speculationrules) elements and external text files referenced by the {{httpheader("Speculation-Rules")}} response header. The rules are specified as a JSON structure. A script example: @@ -55,7 +55,7 @@ A script example: </script> ``` -Speculation rules using a `<script>` element need to be explicitly allowed in the {{httpheader("Content-Security-Policy")}} [`script-src`](/en-US/docs/Web/HTTP/Headers/Content-Security-Policy/script-src) directive if the site includes it. This is done by adding one of the `'inline-speculation-rules'` source, a hash-source, or nonce-source. +Speculation rules using a `<script>` element need to be explicitly allowed in the {{httpheader("Content-Security-Policy")}} [`script-src`](/en-US/docs/Web/HTTP/Reference/Headers/Content-Security-Policy/script-src) directive if the site includes it. This is done by adding one of the `'inline-speculation-rules'` source, a hash-source, or nonce-source. An HTTP header example: @@ -70,7 +70,7 @@ The text resource containing the speculation rules JSON can have any valid name You specify a different array to contain the rules for each speculative loading type (for example `"prerender"` or `"prefetch"`). Each rule is contained in an object that specifies for example a list of resources to be fetched, plus options such as an explicit {{httpheader("Referrer-Policy")}} setting for each rule. Note that prerendered URLs are also prefetched. -See [`<script type="speculationrules">`](/en-US/docs/Web/HTML/Element/script/type/speculationrules) for a full explanation of the available syntax. +See [`<script type="speculationrules">`](/en-US/docs/Web/HTML/Reference/Elements/script/type/speculationrules) for a full explanation of the available syntax. ### Using prefetching @@ -85,7 +85,7 @@ Same-site and cross-site prefetches will work, but cross-site prefetches are lim > [!NOTE] > In the future an opt-in for cross-site prefetches will be provided via the {{httpheader("Supports-Loading-Mode")}} header, but this was not implemented at the time of writing (only cross-origin, same-site [prerendering](#using_prerendering) opt-in was available). -For browsers that support it, speculation rules prefetch should be preferred over older prefetch mechanisms, namely [`<link rel="prefetch">`](/en-US/docs/Web/HTML/Attributes/rel/prefetch) and {{domxref("Window/fetch", "fetch()")}} with a `priority: "low"` option set on it. Because we know that speculation rules prefetch is for navigations, not general resource prefetching: +For browsers that support it, speculation rules prefetch should be preferred over older prefetch mechanisms, namely [`<link rel="prefetch">`](/en-US/docs/Web/HTML/Reference/Attributes/rel/prefetch) and {{domxref("Window/fetch", "fetch()")}} with a `priority: "low"` option set on it. Because we know that speculation rules prefetch is for navigations, not general resource prefetching: - It can be used for cross-site navigations, whereas `<link rel="prefetch">` cannot. - It doesn't get blocked by {{httpheader("Cache-Control")}} headers, whereas `<link rel="prefetch">` often does. @@ -112,7 +112,7 @@ Prerendering uses memory and network bandwidth. If you prerender something the u Prerendering is restricted to same-origin documents by default. Cross-origin, same-site prerendering is possible — it requires the navigation target to opt-in using the {{httpheader("Supports-Loading-Mode")}} header with a value of `credentialed-prerender`. Cross-site prerendering is not possible at this time. -For browsers that support it, speculation rules prerender should be preferred over older prerender mechanisms, namely [`<link rel="prerender">`](/en-US/docs/Web/HTML/Attributes/rel/prerender): +For browsers that support it, speculation rules prerender should be preferred over older prerender mechanisms, namely [`<link rel="prerender">`](/en-US/docs/Web/HTML/Reference/Attributes/rel/prerender): - `<link rel="prerender">` is Chrome-specific and was never standardized, and the Chrome engineering team are in the process of sunsetting it. - It loads subresources loaded via JavaScript, whereas `<link rel="prerender">` doesn't. @@ -260,9 +260,12 @@ It is also potentially risky to prefetch a document whose server-rendered conten > [!NOTE] > Browsers will cache prefetched pages for a short time (Chrome for example caches them for 5 minutes) before discarding them, so in any case, your users might see content that is up to 5 minutes out of date. +Stale prefetches can be cleared using the {{httpheader("Clear-Site-Data#prefetchCache", "prefetchCache")}} value of the {{httpheader("Clear-Site-Data")}} response header. +This might be used, for example, when for state changing requests mean that the cached data is no longer valid, such as when logging out of a site. + Prefetching is safe if all side effects of fetching the page result from JavaScript execution, since the JavaScript will not run until activation. -One final tip is to audit the URLs listed as disallowed in your {{glossary("robots.txt")}} file — normally these URLs point to pages that can only be accessed by authenticated users, and therefore should not be included in search engine results. Many of these will be fine, but it can be a good place to find URLs unsafe for prefetching (i.e. they exhibit the conditions described above). +One final tip is to audit the URLs listed as disallowed in your {{glossary("robots.txt")}} file — normally these URLs point to pages that can only be accessed by authenticated users, and therefore should not be included in search engine results. Many of these will be fine, but it can be a good place to find URLs unsafe for prefetching (i.e., they exhibit the conditions described above). ### Unsafe prerendering @@ -306,6 +309,10 @@ User-specific state problems can occur for other user settings, for example lang The best mitigation for these cases, and indeed any time when content can get out of sync with the server, is for pages to refresh themselves as needed. For example, a server might use the [Broadcast Channel API](/en-US/docs/Web/API/Broadcast_Channel_API), or another mechanism such as {{domxref("Window/fetch", "fetch()")}} or a {{domxref("WebSocket")}}. Pages can then update themselves appropriately, including speculatively loaded pages that have not yet been activated. +Where refreshes are not possible, speculations can be cleared using the {{httpheader("Clear-Site-Data")}} response header with the {{httpheader("Clear-Site-Data#prefetchCache", `prefetchCache`)}} or {{httpheader("Clear-Site-Data#prerenderCache", `prerenderCache`)}} values (or both) as appropriate. + +The header can be returned on any same-site HTTP request (such as an `/api/add-to-cart` API call). + ## Session history behavior for prerendered documents Activating a prerendering/prerendered document behaves like any conventional navigation, from the end-user perspective. The activated document is displayed in the tab and appended to session history, and any existing forward history entries are pruned. Any navigations taking place within the prerendering browsing context _before_ activation do not affect the session history. @@ -314,7 +321,7 @@ From the developer's perspective, a prerendering document can be thought of as h While API features that operate on session history (for example {{domxref("History")}} and {{domxref("Navigation")}}) can be called within prerendering documents, they only operate on the context's trivial session history. Consequently, prerendering documents do not take part in their referring page's joint session history. For example, they cannot navigate their referrer via {{domxref("History.back()")}}. -This design ensures that users get the expected experience when using the back button — i.e. that they are taken back to the last thing they saw. Once a prerendering document is activated, only a single session history entry gets appended to the joint session history, ignoring any previous navigations that happened within the prerendering browsing context. Going back one step in the joint session history — for example, by pressing the back button — takes the user back to the referrer page. +This design ensures that users get the expected experience when using the back button — i.e., that they are taken back to the last thing they saw. Once a prerendering document is activated, only a single session history entry gets appended to the joint session history, ignoring any previous navigations that happened within the prerendering browsing context. Going back one step in the joint session history — for example, by pressing the back button — takes the user back to the referrer page. ## Platform features deferred or restricted during prerender @@ -381,12 +388,12 @@ APIs that require the containing document to be focused: APIs that require the containing document's {{domxref("Document.visibilityState")}} to be `"visible"`: -- [Picture-in-Picture API](/en-US/docs/Web/API/Picture-in-Picture_API): {{domxref("HTMLVideoElement.requestPictureInPicture()")}} (requires the containing document's visibility state to be `"visible", _or_ {{glossary("transient activation")}}) +- [Picture-in-Picture API](/en-US/docs/Web/API/Picture-in-Picture_API): {{domxref("HTMLVideoElement.requestPictureInPicture()")}} (requires the containing document's visibility state to be `"visible"`, _or_ {{glossary("transient activation")}}) - [Screen Wake Lock API](/en-US/docs/Web/API/Screen_Wake_Lock_API): {{domxref("WakeLock.request()")}} ### Other restricted features -- Download links, i.e. {{htmlelement("a")}} and {{htmlelement("area")}} elements with the `download` attribute, will have their downloads delayed until prerendering has finished. +- Download links, i.e., {{htmlelement("a")}} and {{htmlelement("area")}} elements with the `download` attribute, will have their downloads delayed until prerendering has finished. - No cross-site navigations: Any prerendering document that navigates to a different site will be immediately discarded before a request to that other site is sent. - Restricted URLs: Prerendering documents cannot host non-HTTP(S) top-level URLs. Including the following URL types will cause the prerender to be immediately discarded: - [`javascript:` URLs](/en-US/docs/Web/URI/Reference/Schemes/javascript) @@ -411,7 +418,7 @@ The Speculation Rules API does not define any interfaces of its own. - {{domxref("Document.prerendering")}} {{experimental_inline}} - : A boolean property that returns `true` if the document is currently in the process of prerendering. - {{domxref("Document.prerenderingchange_event", "prerenderingchange")}} event {{experimental_inline}} - - : Fired on a prerendered document when it is activated (i.e. the user views the page). + - : Fired on a prerendered document when it is activated (i.e., the user views the page). - {{domxref("PerformanceNavigationTiming.activationStart")}} {{experimental_inline}} - : A number representing the time between when a document starts prerendering and when it is activated. - {{domxref("PerformanceResourceTiming.deliveryType")}} `"navigational-prefetch"` value {{experimental_inline}} @@ -421,6 +428,8 @@ The Speculation Rules API does not define any interfaces of its own. - {{httpheader("Content-Security-Policy")}} `'inline-speculation-rules'` value {{experimental_inline}} - : Used to opt-in to allowing usage of `<script type="speculationrules">` to define speculation rules on the document being fetched. +- {{httpheader("Clear-Site-Data")}} `'prefetchCache'` and `'prerenderCache'` values {{experimental_inline}} + - : Use to clear speculations. For example, when state changes that renders the speculations stale. - {{httpheader("Speculation-Rules")}} {{experimental_inline}} - : Provides a list of URLs pointing to text resources containing speculation rule JSON definitions. When the response is an HTML document, these rules will be added to the document's speculation rule set. - {{httpheader("Supports-Loading-Mode")}} {{experimental_inline}} @@ -428,7 +437,7 @@ The Speculation Rules API does not define any interfaces of its own. ## HTML features -- [`<script type="speculationrules">`](/en-US/docs/Web/HTML/Element/script/type/speculationrules) {{experimental_inline}} +- [`<script type="speculationrules">`](/en-US/docs/Web/HTML/Reference/Elements/script/type/speculationrules) {{experimental_inline}} - : Used to define a set of prefetch and/or prerender speculation rules inside the current document, which are added to the document's speculation rule set. ## Examples diff --git a/files/en-us/web/api/speechgrammar/index.md b/files/en-us/web/api/speechgrammar/index.md index 9c22cbc62a1c5c0..7253cfd03a6638f 100644 --- a/files/en-us/web/api/speechgrammar/index.md +++ b/files/en-us/web/api/speechgrammar/index.md @@ -3,11 +3,12 @@ title: SpeechGrammar slug: Web/API/SpeechGrammar page-type: web-api-interface status: - - experimental + - deprecated + - non-standard browser-compat: api.SpeechGrammar --- -{{APIRef("Web Speech API")}}{{SeeCompatTable}} +{{APIRef("Web Speech API")}}{{deprecated_header}}{{non-standard_header}} The **`SpeechGrammar`** interface of the [Web Speech API](/en-US/docs/Web/API/Web_Speech_API) represents a set of words or patterns of words that we want the recognition service to recognize. @@ -15,14 +16,14 @@ Grammar is defined using [JSpeech Grammar Format](https://www.w3.org/TR/jsgf/) ( ## Constructor -- {{domxref("SpeechGrammar.SpeechGrammar()", "SpeechGrammar()")}} {{Non-standard_Inline}} {{Experimental_Inline}} +- {{domxref("SpeechGrammar.SpeechGrammar()", "SpeechGrammar()")}} {{Non-standard_Inline}} {{deprecated_inline}} - : Creates a new `SpeechGrammar` object. ## Instance properties -- {{domxref("SpeechGrammar.src")}} {{Experimental_Inline}} +- {{domxref("SpeechGrammar.src")}} {{deprecated_inline}} {{non-standard_inline}} - : Sets and returns a string containing the grammar from within in the `SpeechGrammar` object instance. -- {{domxref("SpeechGrammar.weight")}} {{Optional_Inline}} {{Experimental_Inline}} +- {{domxref("SpeechGrammar.weight")}} {{Optional_Inline}} {{deprecated_inline}} {{non-standard_inline}} - : Sets and returns the weight of the `SpeechGrammar` object. ## Examples diff --git a/files/en-us/web/api/speechgrammar/speechgrammar/index.md b/files/en-us/web/api/speechgrammar/speechgrammar/index.md index 8c010baa00c66f4..170817b20153d46 100644 --- a/files/en-us/web/api/speechgrammar/speechgrammar/index.md +++ b/files/en-us/web/api/speechgrammar/speechgrammar/index.md @@ -4,12 +4,12 @@ short-title: SpeechGrammar() slug: Web/API/SpeechGrammar/SpeechGrammar page-type: web-api-constructor status: - - experimental + - deprecated - non-standard browser-compat: api.SpeechGrammar.SpeechGrammar --- -{{APIRef("Web Speech API")}}{{Non-standard_Header}}{{SeeCompatTable}} +{{APIRef("Web Speech API")}}{{Non-standard_Header}}{{deprecated_header}} The **`SpeechGrammar()`** constructor of the {{domxref("SpeechGrammar")}} interface creates a new `SpeechGrammar` object diff --git a/files/en-us/web/api/speechgrammar/src/index.md b/files/en-us/web/api/speechgrammar/src/index.md index c9b4c097ae73dec..89b2266cdf89380 100644 --- a/files/en-us/web/api/speechgrammar/src/index.md +++ b/files/en-us/web/api/speechgrammar/src/index.md @@ -4,11 +4,12 @@ short-title: src slug: Web/API/SpeechGrammar/src page-type: web-api-instance-property status: - - experimental + - deprecated + - non-standard browser-compat: api.SpeechGrammar.src --- -{{APIRef("Web Speech API")}}{{SeeCompatTable}} +{{APIRef("Web Speech API")}}{{deprecated_header}}{{non-standard_header}} The **`src`** property of the {{domxref("SpeechGrammar")}} interface is used to get or set a string that contains the grammar within the `SpeechGrammar` object. diff --git a/files/en-us/web/api/speechgrammar/weight/index.md b/files/en-us/web/api/speechgrammar/weight/index.md index 7966b14f3957379..efcebdfdd92337e 100644 --- a/files/en-us/web/api/speechgrammar/weight/index.md +++ b/files/en-us/web/api/speechgrammar/weight/index.md @@ -4,11 +4,12 @@ short-title: weight slug: Web/API/SpeechGrammar/weight page-type: web-api-instance-property status: - - experimental + - deprecated + - non-standard browser-compat: api.SpeechGrammar.weight --- -{{APIRef("Web Speech API")}}{{SeeCompatTable}} +{{APIRef("Web Speech API")}}{{deprecated_header}}{{non-standard_header}} The optional **`weight`** property of the {{domxref("SpeechGrammar")}} interface sets and returns the weight of the diff --git a/files/en-us/web/api/speechgrammarlist/addfromstring/index.md b/files/en-us/web/api/speechgrammarlist/addfromstring/index.md index 7178c1dd9a72959..1e2418ec83c2c8f 100644 --- a/files/en-us/web/api/speechgrammarlist/addfromstring/index.md +++ b/files/en-us/web/api/speechgrammarlist/addfromstring/index.md @@ -12,7 +12,7 @@ browser-compat: api.SpeechGrammarList.addFromString The **`addFromString()`** method of the {{domxref("SpeechGrammarList")}} interface takes a grammar present in a specific -string within the code base (e.g. stored in a variable) and adds it to +string within the code base (e.g., stored in a variable) and adds it to the `SpeechGrammarList` as a new {{domxref("SpeechGrammar")}} object. ## Syntax diff --git a/files/en-us/web/api/speechrecognition/audioend_event/index.md b/files/en-us/web/api/speechrecognition/audioend_event/index.md index 55e18aea711fa23..70e4eacaf2e11d4 100644 --- a/files/en-us/web/api/speechrecognition/audioend_event/index.md +++ b/files/en-us/web/api/speechrecognition/audioend_event/index.md @@ -14,10 +14,10 @@ The **`audioend`** event of the [Web Speech API](/en-US/docs/Web/API/Web_Speech_ Use the event name in methods like {{domxref("EventTarget.addEventListener", "addEventListener()")}}, or set an event handler property. -```js -addEventListener("audioend", (event) => {}); +```js-nolint +addEventListener("audioend", (event) => { }) -onaudioend = (event) => {}; +onaudioend = (event) => { } ``` ## Event type @@ -29,7 +29,7 @@ A generic {{DOMxRef("Event")}} with no added properties. You can use the `audioend` event in an [`addEventListener`](/en-US/docs/Web/API/EventTarget/addEventListener) method: ```js -const recognition = new webkitSpeechRecognition() || new SpeechRecognition(); +const recognition = new (SpeechRecognition || webkitSpeechRecognition)(); recognition.addEventListener("audioend", () => { console.log("Audio capturing ended"); diff --git a/files/en-us/web/api/speechrecognition/audiostart_event/index.md b/files/en-us/web/api/speechrecognition/audiostart_event/index.md index 8cfef333e813ea2..172ba9318323bd9 100644 --- a/files/en-us/web/api/speechrecognition/audiostart_event/index.md +++ b/files/en-us/web/api/speechrecognition/audiostart_event/index.md @@ -14,10 +14,10 @@ The **`audiostart`** event of the [Web Speech API](/en-US/docs/Web/API/Web_Speec Use the event name in methods like {{domxref("EventTarget.addEventListener", "addEventListener()")}}, or set an event handler property. -```js -addEventListener("audiostart", (event) => {}); +```js-nolint +addEventListener("audiostart", (event) => { }) -onaudiostart = (event) => {}; +onaudiostart = (event) => { } ``` ## Event type @@ -29,7 +29,7 @@ A generic {{DOMxRef("Event")}} with no added properties. You can use the `audiostart` event in an [`addEventListener`](/en-US/docs/Web/API/EventTarget/addEventListener) method: ```js -const recognition = new webkitSpeechRecognition() || new SpeechRecognition(); +const recognition = new (SpeechRecognition || webkitSpeechRecognition)(); recognition.addEventListener("audiostart", () => { console.log("Audio capturing started"); diff --git a/files/en-us/web/api/speechrecognition/continuous/index.md b/files/en-us/web/api/speechrecognition/continuous/index.md index 894cf0a62434eaf..d50e8f6bac38e36 100644 --- a/files/en-us/web/api/speechrecognition/continuous/index.md +++ b/files/en-us/web/api/speechrecognition/continuous/index.md @@ -36,7 +36,7 @@ recognition.lang = "en-US"; recognition.interimResults = false; recognition.maxAlternatives = 1; -// ... +// … ``` ## Specifications diff --git a/files/en-us/web/api/speechrecognition/end_event/index.md b/files/en-us/web/api/speechrecognition/end_event/index.md index fe1e4368e0858b6..32ed757aef355ba 100644 --- a/files/en-us/web/api/speechrecognition/end_event/index.md +++ b/files/en-us/web/api/speechrecognition/end_event/index.md @@ -14,10 +14,10 @@ The **`end`** event of the [Web Speech API](/en-US/docs/Web/API/Web_Speech_API) Use the event name in methods like {{domxref("EventTarget.addEventListener", "addEventListener()")}}, or set an event handler property. -```js -addEventListener("end", (event) => {}); +```js-nolint +addEventListener("end", (event) => { }) -onend = (event) => {}; +onend = (event) => { } ``` ## Event type @@ -29,7 +29,7 @@ A generic {{DOMxRef("Event")}} with no added properties. You can use the `end` event in an [`addEventListener`](/en-US/docs/Web/API/EventTarget/addEventListener) method: ```js -const recognition = new webkitSpeechRecognition() || new SpeechRecognition(); +const recognition = new (SpeechRecognition || webkitSpeechRecognition)(); recognition.addEventListener("end", () => { console.log("Speech recognition service disconnected"); diff --git a/files/en-us/web/api/speechrecognition/error_event/index.md b/files/en-us/web/api/speechrecognition/error_event/index.md index e93f9a8d83f4baf..0b4ba83b31b2fbf 100644 --- a/files/en-us/web/api/speechrecognition/error_event/index.md +++ b/files/en-us/web/api/speechrecognition/error_event/index.md @@ -14,10 +14,10 @@ The **`error`** event of the [Web Speech API](/en-US/docs/Web/API/Web_Speech_API Use the event name in methods like {{domxref("EventTarget.addEventListener", "addEventListener()")}}, or set an event handler property. -```js -addEventListener("error", (event) => {}); +```js-nolint +addEventListener("error", (event) => { }) -onerror = (event) => {}; +onerror = (event) => { } ``` ## Event type @@ -40,7 +40,7 @@ _In addition to the properties listed below, properties from the parent interfac You can use the `error` event in an [`addEventListener`](/en-US/docs/Web/API/EventTarget/addEventListener) method: ```js -const recognition = new webkitSpeechRecognition() || new SpeechRecognition(); +const recognition = new (SpeechRecognition || webkitSpeechRecognition)(); recognition.addEventListener("error", (event) => { console.error(`Speech recognition error detected: ${event.error}`); diff --git a/files/en-us/web/api/speechrecognition/grammars/index.md b/files/en-us/web/api/speechrecognition/grammars/index.md index 961bfd6209c4e64..c3d7cbf8c11adc9 100644 --- a/files/en-us/web/api/speechrecognition/grammars/index.md +++ b/files/en-us/web/api/speechrecognition/grammars/index.md @@ -30,12 +30,12 @@ const recognition = new SpeechRecognition(); const speechRecognitionList = new SpeechGrammarList(); speechRecognitionList.addFromString(grammar, 1); recognition.grammars = speechRecognitionList; -//recognition.continuous = false; +// recognition.continuous = false; recognition.lang = "en-US"; recognition.interimResults = false; recognition.maxAlternatives = 1; -// ... +// … ``` ## Specifications diff --git a/files/en-us/web/api/speechrecognition/index.md b/files/en-us/web/api/speechrecognition/index.md index 78ac2194c29bb78..e0a1c1856b37f29 100644 --- a/files/en-us/web/api/speechrecognition/index.md +++ b/files/en-us/web/api/speechrecognition/index.md @@ -26,11 +26,11 @@ _`SpeechRecognition` also inherits properties from its parent interface, {{domxr - {{domxref("SpeechRecognition.grammars")}} - : Returns and sets a collection of {{domxref("SpeechGrammar")}} objects that represent the grammars that will be understood by the current `SpeechRecognition`. - {{domxref("SpeechRecognition.lang")}} - - : Returns and sets the language of the current `SpeechRecognition`. If not specified, this defaults to the HTML [`lang`](/en-US/docs/Web/HTML/Global_attributes/lang) attribute value, or the user agent's language setting if that isn't set either. + - : Returns and sets the language of the current `SpeechRecognition`. If not specified, this defaults to the HTML [`lang`](/en-US/docs/Web/HTML/Reference/Global_attributes/lang) attribute value, or the user agent's language setting if that isn't set either. - {{domxref("SpeechRecognition.continuous")}} - : Controls whether continuous results are returned for each recognition, or only a single result. Defaults to single (`false`.) - {{domxref("SpeechRecognition.interimResults")}} - - : Controls whether interim results should be returned (`true`) or not (`false`.) Interim results are results that are not yet final (e.g. the {{domxref("SpeechRecognitionResult.isFinal")}} property is `false`.) + - : Controls whether interim results should be returned (`true`) or not (`false`.) Interim results are results that are not yet final (e.g., the {{domxref("SpeechRecognitionResult.isFinal")}} property is `false`.) - {{domxref("SpeechRecognition.maxAlternatives")}} - : Sets the maximum number of {{domxref("SpeechRecognitionAlternative")}}s provided per result. The default value is 1. diff --git a/files/en-us/web/api/speechrecognition/interimresults/index.md b/files/en-us/web/api/speechrecognition/interimresults/index.md index 952ead082e38bf1..c9488e2ca88a711 100644 --- a/files/en-us/web/api/speechrecognition/interimresults/index.md +++ b/files/en-us/web/api/speechrecognition/interimresults/index.md @@ -11,7 +11,7 @@ browser-compat: api.SpeechRecognition.interimResults The **`interimResults`** property of the {{domxref("SpeechRecognition")}} interface controls whether interim results should be returned (`true`) or not (`false`). Interim results are results -that are not yet final (e.g. the {{domxref("SpeechRecognitionResult.isFinal")}} property +that are not yet final (e.g., the {{domxref("SpeechRecognitionResult.isFinal")}} property is `false`). The default value for **`interimResults`** is `false`. @@ -33,12 +33,12 @@ const recognition = new SpeechRecognition(); const speechRecognitionList = new SpeechGrammarList(); speechRecognitionList.addFromString(grammar, 1); recognition.grammars = speechRecognitionList; -//recognition.continuous = false; +// recognition.continuous = false; recognition.lang = "en-US"; recognition.interimResults = false; recognition.maxAlternatives = 1; -// ... +// … ``` ## Specifications diff --git a/files/en-us/web/api/speechrecognition/lang/index.md b/files/en-us/web/api/speechrecognition/lang/index.md index 434ea305a2f3e8d..a8963c8ee294765 100644 --- a/files/en-us/web/api/speechrecognition/lang/index.md +++ b/files/en-us/web/api/speechrecognition/lang/index.md @@ -10,7 +10,7 @@ browser-compat: api.SpeechRecognition.lang The **`lang`** property of the {{domxref("SpeechRecognition")}} interface returns and sets the language of the current `SpeechRecognition`. -If not specified, this defaults to the HTML [`lang`](/en-US/docs/Web/HTML/Global_attributes/lang) attribute +If not specified, this defaults to the HTML [`lang`](/en-US/docs/Web/HTML/Reference/Global_attributes/lang) attribute value, or the user agent's language setting if that isn't set either. ## Value @@ -28,12 +28,12 @@ const recognition = new SpeechRecognition(); const speechRecognitionList = new SpeechGrammarList(); speechRecognitionList.addFromString(grammar, 1); recognition.grammars = speechRecognitionList; -//recognition.continuous = false; +// recognition.continuous = false; recognition.lang = "en-US"; recognition.interimResults = false; recognition.maxAlternatives = 1; -// ... +// … ``` ## Specifications diff --git a/files/en-us/web/api/speechrecognition/maxalternatives/index.md b/files/en-us/web/api/speechrecognition/maxalternatives/index.md index fad9cb94b28d293..d1b9ab7012393af 100644 --- a/files/en-us/web/api/speechrecognition/maxalternatives/index.md +++ b/files/en-us/web/api/speechrecognition/maxalternatives/index.md @@ -30,12 +30,12 @@ const recognition = new SpeechRecognition(); const speechRecognitionList = new SpeechGrammarList(); speechRecognitionList.addFromString(grammar, 1); recognition.grammars = speechRecognitionList; -//recognition.continuous = false; +// recognition.continuous = false; recognition.lang = "en-US"; recognition.interimResults = false; recognition.maxAlternatives = 1; -// ... +// … ``` ## Specifications diff --git a/files/en-us/web/api/speechrecognition/nomatch_event/index.md b/files/en-us/web/api/speechrecognition/nomatch_event/index.md index aa9dee823e85a22..0d78f8334277717 100644 --- a/files/en-us/web/api/speechrecognition/nomatch_event/index.md +++ b/files/en-us/web/api/speechrecognition/nomatch_event/index.md @@ -16,10 +16,10 @@ This may involve some degree of recognition, which doesn't meet or exceed the {{ Use the event name in methods like {{domxref("EventTarget.addEventListener", "addEventListener()")}}, or set an event handler property. -```js -addEventListener("nomatch", (event) => {}); +```js-nolint +addEventListener("nomatch", (event) => { }) -onnomatch = (event) => {}; +onnomatch = (event) => { } ``` ## Event type @@ -46,7 +46,7 @@ _In addition to the properties listed below, properties from the parent interfac You can use the `nomatch` event in an [`addEventListener`](/en-US/docs/Web/API/EventTarget/addEventListener) method: ```js -const recognition = new webkitSpeechRecognition() || new SpeechRecognition(); +const recognition = new (SpeechRecognition || webkitSpeechRecognition)(); recognition.addEventListener("nomatch", () => { console.error("Speech not recognized"); diff --git a/files/en-us/web/api/speechrecognition/result_event/index.md b/files/en-us/web/api/speechrecognition/result_event/index.md index f45d7681c006e98..3c0b7b62211bc07 100644 --- a/files/en-us/web/api/speechrecognition/result_event/index.md +++ b/files/en-us/web/api/speechrecognition/result_event/index.md @@ -14,10 +14,10 @@ The **`result`** event of the [Web Speech API](/en-US/docs/Web/API/Web_Speech_AP Use the event name in methods like {{domxref("EventTarget.addEventListener", "addEventListener()")}}, or set an event handler property. -```js -addEventListener("result", (event) => {}); +```js-nolint +addEventListener("result", (event) => { }) -onresult = (event) => {}; +onresult = (event) => { } ``` ## Event type diff --git a/files/en-us/web/api/speechrecognition/soundend_event/index.md b/files/en-us/web/api/speechrecognition/soundend_event/index.md index 205f2fec164d938..62117fa2a6baaf1 100644 --- a/files/en-us/web/api/speechrecognition/soundend_event/index.md +++ b/files/en-us/web/api/speechrecognition/soundend_event/index.md @@ -14,10 +14,10 @@ The **`soundend`** event of the [Web Speech API](/en-US/docs/Web/API/Web_Speech_ Use the event name in methods like {{domxref("EventTarget.addEventListener", "addEventListener()")}}, or set an event handler property. -```js -addEventListener("soundend", (event) => {}); +```js-nolint +addEventListener("soundend", (event) => { }) -onsoundend = (event) => {}; +onsoundend = (event) => { } ``` ## Event type @@ -29,7 +29,7 @@ A generic {{DOMxRef("Event")}} with no added properties. You can use the `soundend` event in an [`addEventListener`](/en-US/docs/Web/API/EventTarget/addEventListener) method: ```js -const recognition = new webkitSpeechRecognition() || new SpeechRecognition(); +const recognition = new (SpeechRecognition || webkitSpeechRecognition)(); recognition.addEventListener("soundend", (event) => { console.log("Sound has stopped being received"); diff --git a/files/en-us/web/api/speechrecognition/soundstart_event/index.md b/files/en-us/web/api/speechrecognition/soundstart_event/index.md index 00a27d876c02f5f..7aebec8b55d0718 100644 --- a/files/en-us/web/api/speechrecognition/soundstart_event/index.md +++ b/files/en-us/web/api/speechrecognition/soundstart_event/index.md @@ -14,10 +14,10 @@ The **`soundstart`** event of the [Web Speech API](/en-US/docs/Web/API/Web_Speec Use the event name in methods like {{domxref("EventTarget.addEventListener", "addEventListener()")}}, or set an event handler property. -```js -addEventListener("soundstart", (event) => {}); +```js-nolint +addEventListener("soundstart", (event) => { }) -onsoundstart = (event) => {}; +onsoundstart = (event) => { } ``` ## Event type @@ -29,7 +29,7 @@ A generic {{DOMxRef("Event")}} with no added properties. You can use the `soundstart` event in an [`addEventListener`](/en-US/docs/Web/API/EventTarget/addEventListener) method: ```js -const recognition = new webkitSpeechRecognition() || new SpeechRecognition(); +const recognition = new (SpeechRecognition || webkitSpeechRecognition)(); recognition.addEventListener("soundstart", () => { console.log("Some sound is being received"); diff --git a/files/en-us/web/api/speechrecognition/speechend_event/index.md b/files/en-us/web/api/speechrecognition/speechend_event/index.md index ac0581c98dce5c9..d92aae7a45f0a82 100644 --- a/files/en-us/web/api/speechrecognition/speechend_event/index.md +++ b/files/en-us/web/api/speechrecognition/speechend_event/index.md @@ -14,10 +14,10 @@ The **`speechend`** event of the [Web Speech API](/en-US/docs/Web/API/Web_Speech Use the event name in methods like {{domxref("EventTarget.addEventListener", "addEventListener()")}}, or set an event handler property. -```js -addEventListener("speechend", (event) => {}); +```js-nolint +addEventListener("speechend", (event) => { }) -onspeechend = (event) => {}; +onspeechend = (event) => { } ``` ## Event type @@ -29,7 +29,7 @@ A generic {{DOMxRef("Event")}} with no added properties. You can use the `speechend` event in an [`addEventListener`](/en-US/docs/Web/API/EventTarget/addEventListener) method: ```js -const recognition = new webkitSpeechRecognition() || new SpeechRecognition(); +const recognition = new (SpeechRecognition || webkitSpeechRecognition)(); recognition.addEventListener("speechend", () => { console.log("Speech has stopped being detected"); diff --git a/files/en-us/web/api/speechrecognition/speechrecognition/index.md b/files/en-us/web/api/speechrecognition/speechrecognition/index.md index 333170ef2e573ed..08d7aa09dd1ee1b 100644 --- a/files/en-us/web/api/speechrecognition/speechrecognition/index.md +++ b/files/en-us/web/api/speechrecognition/speechrecognition/index.md @@ -32,12 +32,12 @@ const recognition = new SpeechRecognition(); const speechRecognitionList = new SpeechGrammarList(); speechRecognitionList.addFromString(grammar, 1); recognition.grammars = speechRecognitionList; -//recognition.continuous = false; +// recognition.continuous = false; recognition.lang = "en-US"; recognition.interimResults = false; recognition.maxAlternatives = 1; -// ... +// … ``` ## Specifications diff --git a/files/en-us/web/api/speechrecognition/speechstart_event/index.md b/files/en-us/web/api/speechrecognition/speechstart_event/index.md index 55e0326306a5955..fb5b7f1da6d2ba7 100644 --- a/files/en-us/web/api/speechrecognition/speechstart_event/index.md +++ b/files/en-us/web/api/speechrecognition/speechstart_event/index.md @@ -14,10 +14,10 @@ The **`speechstart`** event of the [Web Speech API](/en-US/docs/Web/API/Web_Spee Use the event name in methods like {{domxref("EventTarget.addEventListener", "addEventListener()")}}, or set an event handler property. -```js -addEventListener("speechstart", (event) => {}); +```js-nolint +addEventListener("speechstart", (event) => { }) -onspeechstart = (event) => {}; +onspeechstart = (event) => { } ``` ## Event type @@ -29,7 +29,7 @@ A generic {{DOMxRef("Event")}} with no added properties. You can use the `speechstart` event in an [`addEventListener`](/en-US/docs/Web/API/EventTarget/addEventListener) method: ```js -const recognition = new webkitSpeechRecognition() || new SpeechRecognition(); +const recognition = new (SpeechRecognition || webkitSpeechRecognition)(); recognition.addEventListener("speechstart", () => { console.log("Speech has been detected"); diff --git a/files/en-us/web/api/speechrecognition/start_event/index.md b/files/en-us/web/api/speechrecognition/start_event/index.md index a81d5731fdc41e6..a704b14a61acb9d 100644 --- a/files/en-us/web/api/speechrecognition/start_event/index.md +++ b/files/en-us/web/api/speechrecognition/start_event/index.md @@ -14,10 +14,10 @@ The **`start`** event of the [Web Speech API](/en-US/docs/Web/API/Web_Speech_API Use the event name in methods like {{domxref("EventTarget.addEventListener", "addEventListener()")}}, or set an event handler property. -```js -addEventListener("start", (event) => {}); +```js-nolint +addEventListener("start", (event) => { }) -onstart = (event) => {}; +onstart = (event) => { } ``` ## Event type @@ -29,7 +29,7 @@ A generic {{DOMxRef("Event")}} with no added properties. You can use the `start` event in an [`addEventListener`](/en-US/docs/Web/API/EventTarget/addEventListener) method: ```js -const recognition = new webkitSpeechRecognition() || new SpeechRecognition(); +const recognition = new (SpeechRecognition || webkitSpeechRecognition)(); recognition.addEventListener("start", () => { console.log("Speech recognition service has started"); diff --git a/files/en-us/web/api/speechsynthesis/getvoices/index.md b/files/en-us/web/api/speechsynthesis/getvoices/index.md index e14f41d2a52b2c1..f7201784b7b9581 100644 --- a/files/en-us/web/api/speechsynthesis/getvoices/index.md +++ b/files/en-us/web/api/speechsynthesis/getvoices/index.md @@ -39,16 +39,16 @@ function populateVoiceList() { const voices = speechSynthesis.getVoices(); - for (let i = 0; i < voices.length; i++) { + for (const voice of voices) { const option = document.createElement("option"); - option.textContent = `${voices[i].name} (${voices[i].lang})`; + option.textContent = `${voice.name} (${voice.lang})`; - if (voices[i].default) { + if (voice.default) { option.textContent += " — DEFAULT"; } - option.setAttribute("data-lang", voices[i].lang); - option.setAttribute("data-name", voices[i].name); + option.setAttribute("data-lang", voice.lang); + option.setAttribute("data-name", voice.name); document.getElementById("voiceSelect").appendChild(option); } } diff --git a/files/en-us/web/api/speechsynthesis/index.md b/files/en-us/web/api/speechsynthesis/index.md index 333a7b70d8575d3..e3be7e18bc6a921 100644 --- a/files/en-us/web/api/speechsynthesis/index.md +++ b/files/en-us/web/api/speechsynthesis/index.md @@ -74,16 +74,16 @@ let voices = []; function populateVoiceList() { voices = synth.getVoices(); - for (let i = 0; i < voices.length; i++) { + for (const voice of voices) { const option = document.createElement("option"); - option.textContent = `${voices[i].name} (${voices[i].lang})`; + option.textContent = `${voice.name} (${voice.lang})`; - if (voices[i].default) { + if (voice.default) { option.textContent += " — DEFAULT"; } - option.setAttribute("data-lang", voices[i].lang); - option.setAttribute("data-name", voices[i].name); + option.setAttribute("data-lang", voice.lang); + option.setAttribute("data-name", voice.name); voiceSelect.appendChild(option); } } @@ -99,9 +99,9 @@ inputForm.onsubmit = (event) => { const utterThis = new SpeechSynthesisUtterance(inputTxt.value); const selectedOption = voiceSelect.selectedOptions[0].getAttribute("data-name"); - for (let i = 0; i < voices.length; i++) { - if (voices[i].name === selectedOption) { - utterThis.voice = voices[i]; + for (const voice of voices) { + if (voice.name === selectedOption) { + utterThis.voice = voice; } } utterThis.pitch = pitch.value; diff --git a/files/en-us/web/api/speechsynthesis/speak/index.md b/files/en-us/web/api/speechsynthesis/speak/index.md index 9a502b8f5e9359a..9bdfdc3efa661b5 100644 --- a/files/en-us/web/api/speechsynthesis/speak/index.md +++ b/files/en-us/web/api/speechsynthesis/speak/index.md @@ -36,7 +36,7 @@ passing it into `speak()` as a parameter. ```js const synth = window.speechSynthesis; -// ... +// … inputForm.onsubmit = (event) => { event.preventDefault(); @@ -44,9 +44,9 @@ inputForm.onsubmit = (event) => { const utterThis = new SpeechSynthesisUtterance(inputTxt.value); const selectedOption = voiceSelect.selectedOptions[0].getAttribute("data-name"); - for (let i = 0; i < voices.length; i++) { - if (voices[i].name === selectedOption) { - utterThis.voice = voices[i]; + for (const voice of voices) { + if (voice.name === selectedOption) { + utterThis.voice = voice; } } synth.speak(utterThis); diff --git a/files/en-us/web/api/speechsynthesis/voiceschanged_event/index.md b/files/en-us/web/api/speechsynthesis/voiceschanged_event/index.md index a14701873d02c59..650a0d97bad36e5 100644 --- a/files/en-us/web/api/speechsynthesis/voiceschanged_event/index.md +++ b/files/en-us/web/api/speechsynthesis/voiceschanged_event/index.md @@ -14,10 +14,10 @@ The **`voiceschanged`** event of the [Web Speech API](/en-US/docs/Web/API/Web_Sp Use the event name in methods like {{domxref("EventTarget.addEventListener", "addEventListener()")}}, or set an event handler property. -```js -addEventListener("voiceschanged", (event) => {}); +```js-nolint +addEventListener("voiceschanged", (event) => { }) -onvoiceschanged = (event) => {}; +onvoiceschanged = (event) => { } ``` ## Event type @@ -33,11 +33,11 @@ const synth = window.speechSynthesis; synth.addEventListener("voiceschanged", () => { const voices = synth.getVoices(); - for (let i = 0; i < voices.length; i++) { + for (const voice of voices) { const option = document.createElement("option"); - option.textContent = `${voices[i].name} (${voices[i].lang})`; - option.setAttribute("data-lang", voices[i].lang); - option.setAttribute("data-name", voices[i].name); + option.textContent = `${voice.name} (${voice.lang})`; + option.setAttribute("data-lang", voice.lang); + option.setAttribute("data-name", voice.name); voiceSelect.appendChild(option); } }); @@ -49,11 +49,11 @@ Or use the `onvoiceschanged` event handler property: const synth = window.speechSynthesis; synth.onvoiceschanged = () => { const voices = synth.getVoices(); - for (let i = 0; i < voices.length; i++) { + for (const voice of voices) { const option = document.createElement("option"); - option.textContent = `${voices[i].name} (${voices[i].lang})`; - option.setAttribute("data-lang", voices[i].lang); - option.setAttribute("data-name", voices[i].name); + option.textContent = `${voice.name} (${voice.lang})`; + option.setAttribute("data-lang", voice.lang); + option.setAttribute("data-name", voice.name); voiceSelect.appendChild(option); } }; diff --git a/files/en-us/web/api/speechsynthesiserrorevent/error/index.md b/files/en-us/web/api/speechsynthesiserrorevent/error/index.md index 65d8a9a9d9d037e..0214eceeb50f671 100644 --- a/files/en-us/web/api/speechsynthesiserrorevent/error/index.md +++ b/files/en-us/web/api/speechsynthesiserrorevent/error/index.md @@ -65,7 +65,7 @@ const voiceSelect = document.querySelector("select"); const voices = synth.getVoices(); -// ... +// … inputForm.onsubmit = (event) => { event.preventDefault(); @@ -73,9 +73,9 @@ inputForm.onsubmit = (event) => { const utterThis = new SpeechSynthesisUtterance(inputTxt.value); const selectedOption = voiceSelect.selectedOptions[0].getAttribute("data-name"); - for (let i = 0; i < voices.length; i++) { - if (voices[i].name === selectedOption) { - utterThis.voice = voices[i]; + for (const voice of voices) { + if (voice.name === selectedOption) { + utterThis.voice = voice; } } diff --git a/files/en-us/web/api/speechsynthesiserrorevent/index.md b/files/en-us/web/api/speechsynthesiserrorevent/index.md index 76254b16643b7eb..e556c1a9a96a284 100644 --- a/files/en-us/web/api/speechsynthesiserrorevent/index.md +++ b/files/en-us/web/api/speechsynthesiserrorevent/index.md @@ -38,7 +38,7 @@ const voiceSelect = document.querySelector("select"); const voices = synth.getVoices(); -// ... +// … inputForm.onsubmit = (event) => { event.preventDefault(); @@ -46,9 +46,9 @@ inputForm.onsubmit = (event) => { const utterThis = new SpeechSynthesisUtterance(inputTxt.value); const selectedOption = voiceSelect.selectedOptions[0].getAttribute("data-name"); - for (let i = 0; i < voices.length; i++) { - if (voices[i].name === selectedOption) { - utterThis.voice = voices[i]; + for (const voice of voices) { + if (voice.name === selectedOption) { + utterThis.voice = voice; } } diff --git a/files/en-us/web/api/speechsynthesisutterance/boundary_event/index.md b/files/en-us/web/api/speechsynthesisutterance/boundary_event/index.md index 5802a4831ebfbb8..a2ee0c4c4d72d87 100644 --- a/files/en-us/web/api/speechsynthesisutterance/boundary_event/index.md +++ b/files/en-us/web/api/speechsynthesisutterance/boundary_event/index.md @@ -14,10 +14,10 @@ The **`boundary`** event of the [Web Speech API](/en-US/docs/Web/API/Web_Speech_ Use the event name in methods like {{domxref("EventTarget.addEventListener", "addEventListener()")}}, or set an event handler property. -```js -addEventListener("boundary", (event) => {}); +```js-nolint +addEventListener("boundary", (event) => { }) -onboundary = (event) => {}; +onboundary = (event) => { } ``` ## Event type diff --git a/files/en-us/web/api/speechsynthesisutterance/end_event/index.md b/files/en-us/web/api/speechsynthesisutterance/end_event/index.md index ce61b68c08a8209..d240a9fae1c0a8a 100644 --- a/files/en-us/web/api/speechsynthesisutterance/end_event/index.md +++ b/files/en-us/web/api/speechsynthesisutterance/end_event/index.md @@ -14,10 +14,10 @@ The **`end`** event of the [Web Speech API](/en-US/docs/Web/API/Web_Speech_API) Use the event name in methods like {{domxref("EventTarget.addEventListener", "addEventListener()")}}, or set an event handler property. -```js -addEventListener("end", (event) => {}); +```js-nolint +addEventListener("end", (event) => { }) -onend = (event) => {}; +onend = (event) => { } ``` ## Event type diff --git a/files/en-us/web/api/speechsynthesisutterance/error_event/index.md b/files/en-us/web/api/speechsynthesisutterance/error_event/index.md index 26c5afde9a6f02a..61092c30627e836 100644 --- a/files/en-us/web/api/speechsynthesisutterance/error_event/index.md +++ b/files/en-us/web/api/speechsynthesisutterance/error_event/index.md @@ -14,10 +14,10 @@ The **`error`** event of the [Web Speech API](/en-US/docs/Web/API/Web_Speech_API Use the event name in methods like {{domxref("EventTarget.addEventListener", "addEventListener()")}}, or set an event handler property. -```js -addEventListener("error", (event) => {}); +```js-nolint +addEventListener("error", (event) => { }) -onerror = (event) => {}; +onerror = (event) => { } ``` ## Event type diff --git a/files/en-us/web/api/speechsynthesisutterance/index.md b/files/en-us/web/api/speechsynthesisutterance/index.md index a4c0090f3df971e..55d3d586993dc5d 100644 --- a/files/en-us/web/api/speechsynthesisutterance/index.md +++ b/files/en-us/web/api/speechsynthesisutterance/index.md @@ -8,7 +8,7 @@ browser-compat: api.SpeechSynthesisUtterance {{APIRef("Web Speech API")}} The **`SpeechSynthesisUtterance`** interface of the [Web Speech API](/en-US/docs/Web/API/Web_Speech_API) represents a speech request. -It contains the content the speech service should read and information about how to read it (e.g. language, pitch and volume.) +It contains the content the speech service should read and information about how to read it (e.g., language, pitch and volume.) {{InheritanceDiagram}} @@ -78,9 +78,9 @@ let voices; function loadVoices() { voices = synth.getVoices(); - for (let i = 0; i < voices.length; i++) { + for (const [i, voice] of voices.entries()) { const option = document.createElement("option"); - option.textContent = `${voices[i].name} (${voices[i].lang})`; + option.textContent = `${voice.name} (${voice.lang})`; option.value = i; voiceSelect.appendChild(option); } diff --git a/files/en-us/web/api/speechsynthesisutterance/lang/index.md b/files/en-us/web/api/speechsynthesisutterance/lang/index.md index 51dce9bff307e15..f2ec173d58a89f7 100644 --- a/files/en-us/web/api/speechsynthesisutterance/lang/index.md +++ b/files/en-us/web/api/speechsynthesisutterance/lang/index.md @@ -10,7 +10,7 @@ browser-compat: api.SpeechSynthesisUtterance.lang The **`lang`** property of the {{domxref("SpeechSynthesisUtterance")}} interface gets and sets the language of the utterance. -If unset, the app's (i.e. the {{htmlelement("html")}} [`lang`](/en-US/docs/Web/HTML/Global_attributes/lang) value) lang will be used, or the user-agent default if that is unset too. +If unset, the app's (i.e., the {{htmlelement("html")}} [`lang`](/en-US/docs/Web/HTML/Reference/Global_attributes/lang) value) lang will be used, or the user-agent default if that is unset too. ## Value @@ -27,7 +27,7 @@ const voiceSelect = document.querySelector("select"); const voices = synth.getVoices(); -// ... +// … inputForm.onsubmit = (event) => { event.preventDefault(); @@ -35,9 +35,9 @@ inputForm.onsubmit = (event) => { const utterThis = new SpeechSynthesisUtterance(inputTxt.value); const selectedOption = voiceSelect.selectedOptions[0].getAttribute("data-name"); - for (let i = 0; i < voices.length; i++) { - if (voices[i].name === selectedOption) { - utterThis.voice = voices[i]; + for (const voice of voices) { + if (voice.name === selectedOption) { + utterThis.voice = voice; } } utterThis.lang = "en-US"; diff --git a/files/en-us/web/api/speechsynthesisutterance/mark_event/index.md b/files/en-us/web/api/speechsynthesisutterance/mark_event/index.md index 6a9229390337a84..dbc9cc283c23d5b 100644 --- a/files/en-us/web/api/speechsynthesisutterance/mark_event/index.md +++ b/files/en-us/web/api/speechsynthesisutterance/mark_event/index.md @@ -14,10 +14,10 @@ The **`mark`** event of the [Web Speech API](/en-US/docs/Web/API/Web_Speech_API) Use the event name in methods like {{domxref("EventTarget.addEventListener", "addEventListener()")}}, or set an event handler property. -```js -addEventListener("mark", (event) => {}); +```js-nolint +addEventListener("mark", (event) => { }) -onmark = (event) => {}; +onmark = (event) => { } ``` ## Event type diff --git a/files/en-us/web/api/speechsynthesisutterance/pause_event/index.md b/files/en-us/web/api/speechsynthesisutterance/pause_event/index.md index 687a184b4fe90e7..c9892667068b985 100644 --- a/files/en-us/web/api/speechsynthesisutterance/pause_event/index.md +++ b/files/en-us/web/api/speechsynthesisutterance/pause_event/index.md @@ -14,10 +14,10 @@ The **`pause`** event of the [Web Speech API](/en-US/docs/Web/API/Web_Speech_API Use the event name in methods like {{domxref("EventTarget.addEventListener", "addEventListener()")}}, or set an event handler property. -```js -addEventListener("pause", (event) => {}); +```js-nolint +addEventListener("pause", (event) => { }) -onpause = (event) => {}; +onpause = (event) => { } ``` ## Event type diff --git a/files/en-us/web/api/speechsynthesisutterance/pitch/index.md b/files/en-us/web/api/speechsynthesisutterance/pitch/index.md index 1e4bf2d7f26a7ee..e1c0f806b20df9c 100644 --- a/files/en-us/web/api/speechsynthesisutterance/pitch/index.md +++ b/files/en-us/web/api/speechsynthesisutterance/pitch/index.md @@ -29,7 +29,7 @@ const voiceSelect = document.querySelector("select"); const voices = synth.getVoices(); -// ... +// … inputForm.onsubmit = (event) => { event.preventDefault(); @@ -37,9 +37,9 @@ inputForm.onsubmit = (event) => { const utterThis = new SpeechSynthesisUtterance(inputTxt.value); const selectedOption = voiceSelect.selectedOptions[0].getAttribute("data-name"); - for (let i = 0; i < voices.length; i++) { - if (voices[i].name === selectedOption) { - utterThis.voice = voices[i]; + for (const voice of voices) { + if (voice.name === selectedOption) { + utterThis.voice = voice; } } utterThis.pitch = 1.5; diff --git a/files/en-us/web/api/speechsynthesisutterance/resume_event/index.md b/files/en-us/web/api/speechsynthesisutterance/resume_event/index.md index 0d6c9861c2cbffc..f0ababa271e4bda 100644 --- a/files/en-us/web/api/speechsynthesisutterance/resume_event/index.md +++ b/files/en-us/web/api/speechsynthesisutterance/resume_event/index.md @@ -14,10 +14,10 @@ The **`resume`** event of the [Web Speech API](/en-US/docs/Web/API/Web_Speech_AP Use the event name in methods like {{domxref("EventTarget.addEventListener", "addEventListener()")}}, or set an event handler property. -```js -addEventListener("resume", (event) => {}); +```js-nolint +addEventListener("resume", (event) => { }) -onresume = (event) => {}; +onresume = (event) => { } ``` ## Event type diff --git a/files/en-us/web/api/speechsynthesisutterance/speechsynthesisutterance/index.md b/files/en-us/web/api/speechsynthesisutterance/speechsynthesisutterance/index.md index 4ace863989f8784..c64249f6a4d5bd2 100644 --- a/files/en-us/web/api/speechsynthesisutterance/speechsynthesisutterance/index.md +++ b/files/en-us/web/api/speechsynthesisutterance/speechsynthesisutterance/index.md @@ -34,7 +34,7 @@ const voiceSelect = document.querySelector("select"); const voices = synth.getVoices(); -// ... +// … inputForm.onsubmit = (event) => { event.preventDefault(); @@ -42,9 +42,9 @@ inputForm.onsubmit = (event) => { const utterThis = new SpeechSynthesisUtterance(inputTxt.value); const selectedOption = voiceSelect.selectedOptions[0].getAttribute("data-name"); - for (let i = 0; i < voices.length; i++) { - if (voices[i].name === selectedOption) { - utterThis.voice = voices[i]; + for (const voice of voices) { + if (voice.name === selectedOption) { + utterThis.voice = voice; } } synth.speak(utterThis); diff --git a/files/en-us/web/api/speechsynthesisutterance/start_event/index.md b/files/en-us/web/api/speechsynthesisutterance/start_event/index.md index 12a72f5b6610302..c4643b927b60691 100644 --- a/files/en-us/web/api/speechsynthesisutterance/start_event/index.md +++ b/files/en-us/web/api/speechsynthesisutterance/start_event/index.md @@ -14,10 +14,10 @@ The **`start`** event of the [Web Speech API](/en-US/docs/Web/API/Web_Speech_API Use the event name in methods like {{domxref("EventTarget.addEventListener", "addEventListener()")}}, or set an event handler property. -```js -addEventListener("start", (event) => {}); +```js-nolint +addEventListener("start", (event) => { }) -onstart = (event) => {}; +onstart = (event) => { } ``` ## Event type diff --git a/files/en-us/web/api/speechsynthesisutterance/text/index.md b/files/en-us/web/api/speechsynthesisutterance/text/index.md index c8ac10a57985868..32ecddba074acba 100644 --- a/files/en-us/web/api/speechsynthesisutterance/text/index.md +++ b/files/en-us/web/api/speechsynthesisutterance/text/index.md @@ -30,7 +30,7 @@ const voiceSelect = document.querySelector("select"); const voices = synth.getVoices(); -// ... +// … inputForm.onsubmit = (event) => { event.preventDefault(); @@ -38,9 +38,9 @@ inputForm.onsubmit = (event) => { const utterThis = new SpeechSynthesisUtterance(inputTxt.value); const selectedOption = voiceSelect.selectedOptions[0].getAttribute("data-name"); - for (let i = 0; i < voices.length; i++) { - if (voices[i].name === selectedOption) { - utterThis.voice = voices[i]; + for (const voice of voices) { + if (voice.name === selectedOption) { + utterThis.voice = voice; } } console.log(utterThis.text); diff --git a/files/en-us/web/api/speechsynthesisutterance/voice/index.md b/files/en-us/web/api/speechsynthesisutterance/voice/index.md index 1a73010ee6c11f6..fdcce28a19589ea 100644 --- a/files/en-us/web/api/speechsynthesisutterance/voice/index.md +++ b/files/en-us/web/api/speechsynthesisutterance/voice/index.md @@ -28,7 +28,7 @@ const voiceSelect = document.querySelector("select"); const voices = synth.getVoices(); -// ... +// … inputForm.onsubmit = (event) => { event.preventDefault(); @@ -36,9 +36,9 @@ inputForm.onsubmit = (event) => { const utterThis = new SpeechSynthesisUtterance(inputTxt.value); const selectedOption = voiceSelect.selectedOptions[0].getAttribute("data-name"); - for (let i = 0; i < voices.length; i++) { - if (voices[i].name === selectedOption) { - utterThis.voice = voices[i]; + for (const voice of voices) { + if (voice.name === selectedOption) { + utterThis.voice = voice; } } synth.speak(utterThis); diff --git a/files/en-us/web/api/speechsynthesisutterance/volume/index.md b/files/en-us/web/api/speechsynthesisutterance/volume/index.md index 5bcef1f9b27a577..9a34a020429544c 100644 --- a/files/en-us/web/api/speechsynthesisutterance/volume/index.md +++ b/files/en-us/web/api/speechsynthesisutterance/volume/index.md @@ -29,7 +29,7 @@ const voiceSelect = document.querySelector("select"); const voices = synth.getVoices(); -// ... +// … inputForm.onsubmit = (event) => { event.preventDefault(); @@ -37,9 +37,9 @@ inputForm.onsubmit = (event) => { const utterThis = new SpeechSynthesisUtterance(inputTxt.value); const selectedOption = voiceSelect.selectedOptions[0].getAttribute("data-name"); - for (let i = 0; i < voices.length; i++) { - if (voices[i].name === selectedOption) { - utterThis.voice = voices[i]; + for (const voice of voices) { + if (voice.name === selectedOption) { + utterThis.voice = voice; } } utterThis.volume = 0.5; diff --git a/files/en-us/web/api/speechsynthesisvoice/default/index.md b/files/en-us/web/api/speechsynthesisvoice/default/index.md index 1b424770f5ae36f..05ae0a20b6e00f2 100644 --- a/files/en-us/web/api/speechsynthesisvoice/default/index.md +++ b/files/en-us/web/api/speechsynthesisvoice/default/index.md @@ -25,16 +25,16 @@ A boolean value. ## Examples ```js -for (let i = 0; i < voices.length; i++) { +for (const voice of voices) { const option = document.createElement("option"); - option.textContent = `${voices[i].name} (${voices[i].lang})`; + option.textContent = `${voice.name} (${voice.lang})`; - if (voices[i].default) { + if (voice.default) { option.textContent += " — DEFAULT"; } - option.setAttribute("data-lang", voices[i].lang); - option.setAttribute("data-name", voices[i].name); + option.setAttribute("data-lang", voice.lang); + option.setAttribute("data-name", voice.name); voiceSelect.appendChild(option); } ``` diff --git a/files/en-us/web/api/speechsynthesisvoice/index.md b/files/en-us/web/api/speechsynthesisvoice/index.md index 7f561a964cc65ac..29277ce79ba20ca 100644 --- a/files/en-us/web/api/speechsynthesisvoice/index.md +++ b/files/en-us/web/api/speechsynthesisvoice/index.md @@ -32,16 +32,16 @@ const synth = window.speechSynthesis; function populateVoiceList() { voices = synth.getVoices(); - for (let i = 0; i < voices.length; i++) { + for (const voice of voices) { const option = document.createElement("option"); - option.textContent = `${voices[i].name} (${voices[i].lang})`; + option.textContent = `${voice.name} (${voice.lang})`; - if (voices[i].default) { + if (voice.default) { option.textContent += " — DEFAULT"; } - option.setAttribute("data-lang", voices[i].lang); - option.setAttribute("data-name", voices[i].name); + option.setAttribute("data-lang", voice.lang); + option.setAttribute("data-name", voice.name); voiceSelect.appendChild(option); } } @@ -57,9 +57,9 @@ inputForm.onsubmit = (event) => { const utterThis = new SpeechSynthesisUtterance(inputTxt.value); const selectedOption = voiceSelect.selectedOptions[0].getAttribute("data-name"); - for (let i = 0; i < voices.length; i++) { - if (voices[i].name === selectedOption) { - utterThis.voice = voices[i]; + for (const voice of voices) { + if (voice.name === selectedOption) { + utterThis.voice = voice; } } utterThis.pitch = pitch.value; diff --git a/files/en-us/web/api/speechsynthesisvoice/lang/index.md b/files/en-us/web/api/speechsynthesisvoice/lang/index.md index e753020519d6e81..6966dd3c7413599 100644 --- a/files/en-us/web/api/speechsynthesisvoice/lang/index.md +++ b/files/en-us/web/api/speechsynthesisvoice/lang/index.md @@ -17,16 +17,16 @@ A string representing the language of the device. ## Examples ```js -for (let i = 0; i < voices.length; i++) { +for (const voice of voices) { const option = document.createElement("option"); - option.textContent = `${voices[i].name} (${voices[i].lang})`; + option.textContent = `${voice.name} (${voice.lang})`; - if (voices[i].default) { + if (voice.default) { option.textContent += " — DEFAULT"; } - option.setAttribute("data-lang", voices[i].lang); - option.setAttribute("data-name", voices[i].name); + option.setAttribute("data-lang", voice.lang); + option.setAttribute("data-name", voice.name); voiceSelect.appendChild(option); } ``` diff --git a/files/en-us/web/api/speechsynthesisvoice/localservice/index.md b/files/en-us/web/api/speechsynthesisvoice/localservice/index.md index adef4b4a8ad4c1e..1c2244d5ea6f08a 100644 --- a/files/en-us/web/api/speechsynthesisvoice/localservice/index.md +++ b/files/en-us/web/api/speechsynthesisvoice/localservice/index.md @@ -24,18 +24,18 @@ A boolean value. ## Examples ```js -for (let i = 0; i < voices.length; i++) { +for (const voice of voices) { const option = document.createElement("option"); - option.textContent = `${voices[i].name} (${voices[i].lang})`; + option.textContent = `${voice.name} (${voice.lang})`; - if (voices[i].default) { + if (voice.default) { option.textContent += " — DEFAULT"; } - console.log(voices[i].localService); + console.log(voice.localService); - option.setAttribute("data-lang", voices[i].lang); - option.setAttribute("data-name", voices[i].name); + option.setAttribute("data-lang", voice.lang); + option.setAttribute("data-name", voice.name); voiceSelect.appendChild(option); } ``` diff --git a/files/en-us/web/api/speechsynthesisvoice/voiceuri/index.md b/files/en-us/web/api/speechsynthesisvoice/voiceuri/index.md index fec97aa965d0033..a0d7ec7d1619dce 100644 --- a/files/en-us/web/api/speechsynthesisvoice/voiceuri/index.md +++ b/files/en-us/web/api/speechsynthesisvoice/voiceuri/index.md @@ -15,24 +15,24 @@ the speech synthesis service for this voice. ## Value A string representing the URI of the voice. This is a generic URI and -can point to local or remote services, e.g. it could be a proprietary system URN or a URL to a remote service. +can point to local or remote services, e.g., it could be a proprietary system URN or a URL to a remote service. ## Examples ```js -for (let i = 0; i < voices.length; i++) { +for (const voice of voices) { const option = document.createElement("option"); - option.textContent = `${voices[i].name} (${voices[i].lang})`; + option.textContent = `${voice.name} (${voice.lang})`; - if (voices[i].default) { + if (voice.default) { option.textContent += " — DEFAULT"; } - console.log(voices[i].voiceURI); + console.log(voice.voiceURI); // On Mac, this returns URNs, for example 'urn:moz-tts:osx:com.apple.speech.synthesis.voice.daniel' - option.setAttribute("data-lang", voices[i].lang); - option.setAttribute("data-name", voices[i].name); + option.setAttribute("data-lang", voice.lang); + option.setAttribute("data-name", voice.name); voiceSelect.appendChild(option); } ``` diff --git a/files/en-us/web/api/storage_access_api/index.md b/files/en-us/web/api/storage_access_api/index.md index e3dadaad46e6d55..67d607a8b18fa6a 100644 --- a/files/en-us/web/api/storage_access_api/index.md +++ b/files/en-us/web/api/storage_access_api/index.md @@ -41,7 +41,7 @@ The Storage Access API is intended to solve this problem; embedded cross-site co It is important to note that the Storage Access API is only needed to provide access to _unpartitioned_ third-party cookies. This means cookies stored in the traditional way since the early web — all cookies set on the same site are stored in the same cookie jar. This is in contrast to _partitioned_ cookies, where embedded resources under each top-level site are given a unique cookie storage space, thereby making tracking users across sites via these cookies impossible. -Browsers have various mechanisms to partition third-party cookie access, for example [Firefox Total Cookie Protection](https://blog.mozilla.org/en/products/firefox/firefox-rolls-out-total-cookie-protection-by-default-to-all-users-worldwide/) and [Cookies Having Independent Partitioned State (CHIPS)](/en-US/docs/Web/Privacy/Guides/Privacy_sandbox/Partitioned_cookies). +Browsers have various mechanisms to partition third-party cookie access, for example [Firefox Total Cookie Protection](https://blog.mozilla.org/en/mozilla/firefox-rolls-out-total-cookie-protection-by-default-to-all-users-worldwide/) and [Cookies Having Independent Partitioned State (CHIPS)](/en-US/docs/Web/Privacy/Guides/Privacy_sandbox/Partitioned_cookies). When we talk about third-party cookies in the context of the Storage Access API, we implicitly mean _unpartitioned_ third-party cookies. @@ -75,7 +75,7 @@ Several different security measures could cause a {{domxref("Document.requestSto 2. The document and top-level document must not have a `null` origin. 3. Origins that have never been interacted with as a first party do not have a notion of first-party storage. From the user's perspective, they only have a third-party relationship with that origin. Access requests are automatically denied if the browser detects that the user hasn't interacted with the embedded content in a first-party context recently (in Firefox, "recently" means within 30 days). 4. The document's window must be a [secure context](/en-US/docs/Web/Security/Secure_Contexts). -5. Sandboxed {{htmlelement("iframe")}}s cannot be granted storage access by default for security reasons. The API therefore also adds the `allow-storage-access-by-user-activation` [sandbox token](/en-US/docs/Web/HTML/Element/iframe#sandbox). The embedding website needs to add this to allow storage access requests to be successful, along with `allow-scripts` and `allow-same-origin` to allow it to execute a script to call the API and execute it in an origin that can have cookies/state: +5. Sandboxed {{htmlelement("iframe")}}s cannot be granted storage access by default for security reasons. The API therefore also adds the `allow-storage-access-by-user-activation` [sandbox token](/en-US/docs/Web/HTML/Reference/Elements/iframe#sandbox). The embedding website needs to add this to allow storage access requests to be successful, along with `allow-scripts` and `allow-same-origin` to allow it to execute a script to call the API and execute it in an origin that can have cookies/state: ```html <iframe @@ -86,7 +86,7 @@ Several different security measures could cause a {{domxref("Document.requestSto </iframe> ``` -6. Usage of this feature may be blocked by a {{httpheader("Permissions-Policy/storage-access", "storage-access")}} [Permissions Policy](/en-US/docs/Web/HTTP/Permissions_Policy) set on your server. +6. Usage of this feature may be blocked by a {{httpheader("Permissions-Policy/storage-access", "storage-access")}} [Permissions Policy](/en-US/docs/Web/HTTP/Guides/Permissions_Policy) set on your server. > [!NOTE] > The document may also be required to pass additional browser-specific checks. Examples: allowlists, blocklists, on-device classification, user settings, anti-[clickjacking](/en-US/docs/Web/Security/Attacks/Clickjacking) heuristics, or prompting the user for explicit permission. @@ -97,8 +97,8 @@ Although the API surface is the same, websites using the Storage Access API shou ### Chrome -- Cookies must have [`SameSite=None`](/en-US/docs/Web/HTTP/Headers/Set-Cookie#samesitesamesite-value) explicitly set on them, because the default value for Chrome is `SameSite=Lax` (`SameSite=None` is the default in Firefox and Safari). -- Cookies must have the [`Secure`](/en-US/docs/Web/HTTP/Headers/Set-Cookie#secure) attribute set on them. +- Cookies must have [`SameSite=None`](/en-US/docs/Web/HTTP/Reference/Headers/Set-Cookie#samesitesamesite-value) explicitly set on them, because the default value for Chrome is `SameSite=Lax` (`SameSite=None` is the default in Firefox and Safari). +- Cookies must have the [`Secure`](/en-US/docs/Web/HTTP/Reference/Headers/Set-Cookie#secure) attribute set on them. - The storage access grants are phased out after 30 days of browser usage passed without user interaction. Interaction with the embedded content extends this limit by another 30 days. This doesn't occur when {{domxref("Document.requestStorageAccessFor()")}} is called because the user is already on the page. ### Firefox diff --git a/files/en-us/web/api/storage_access_api/related_website_sets/index.md b/files/en-us/web/api/storage_access_api/related_website_sets/index.md index a8d0c4ae8f5c03b..8fe2c769591a7af 100644 --- a/files/en-us/web/api/storage_access_api/related_website_sets/index.md +++ b/files/en-us/web/api/storage_access_api/related_website_sets/index.md @@ -112,7 +112,7 @@ The primary site's `.well-known` file must explicitly list out the full set stru } ``` -Each associate and service site needs to specify its primary site in a `.well-known` file. Each non-primary site in the above example (e.g. `https://associateA.com`) would need a `/.well-known/related-website-set.json` file like this: +Each associate and service site needs to specify its primary site in a `.well-known` file. Each non-primary site in the above example (e.g., `https://associateA.com`) would need a `/.well-known/related-website-set.json` file like this: ```json { @@ -135,11 +135,11 @@ Once a set is active: RWS has been designed with security in mind. It would be disastrous if a bad actor site were able to claim to be part of a set and gain the privileges that entails. Lets consider a theoretical bad actor site, `evilsite.example.com`, and look at some examples of attacks it could try to make, all of which would fail: -- **`evilsite.example.com` claims to be an associated site in another set**: If a site claiming to be in a set (`i.e.` by listing a primary in a `.well-known` file) is not included in the set submission and/or primary's `.well-known` file, it won't get the benefits of being in the set. -- **`evilsite.example.com` claims to be a primary site, and submits a set that includes some would-be victim sites**: The submission process requires that `.well-known` files hosted by non-primary sites explicitly list out their primary. If this primary doesn't match the set submission (i.e. if the associated/service sites expect to have a different primary, or don't expect to be in a set at all), the submission will be rejected. +- **`evilsite.example.com` claims to be an associated site in another set**: If a site claiming to be in a set (i.e., by listing a primary in a `.well-known` file) is not included in the set submission and/or primary's `.well-known` file, it won't get the benefits of being in the set. +- **`evilsite.example.com` claims to be a primary site, and submits a set that includes some would-be victim sites**: The submission process requires that `.well-known` files hosted by non-primary sites explicitly list out their primary. If this primary doesn't match the set submission (i.e., if the associated/service sites expect to have a different primary, or don't expect to be in a set at all), the submission will be rejected. - **`site1.example.com` and `site2.example.com` are intentionally in the same set, but `site1.example.com` gets hijacked by `evilsite.example.com`**: The impact of a site hijacking attack within a set isn't any worse than it would usually be, once the other sites are updated accordingly: - The regular [Storage Access API](/en-US/docs/Web/API/Storage_Access_API) requires an active opt-in by the embedded site, so `site2.example.com` can stop calling `document.requestStorageAccess()` when it's embedded in `site1.example.com`, avoiding a {{glossary("CSRF")}} attack. - - Use of `requestStorageAccessFor()` requires [CORS](/en-US/docs/Web/HTTP/CORS), so `site2.example.com` could choose not to respond with the appropriate CORS headers when network requests are coming from `site1.example.com`, thereby avoiding a CSRF attack. + - Use of `requestStorageAccessFor()` requires [CORS](/en-US/docs/Web/HTTP/Guides/CORS), so `site2.example.com` could choose not to respond with the appropriate CORS headers when network requests are coming from `site1.example.com`, thereby avoiding a CSRF attack. ## Examples @@ -160,5 +160,5 @@ Two browser vendors [oppose](/en-US/docs/Glossary/Web_standards#opposing_standar ## See also - [Storage Access API](/en-US/docs/Web/API/Storage_Access_API) -- [Related Website Sets](https://developers.google.com/privacy-sandbox/cookies/related-website-sets) on developers.google.com (2023) -- [Related Website Sets: developer guide](https://developers.google.com/privacy-sandbox/cookies/related-website-sets-integration) on developers.google.com (2023) +- [Related Website Sets](https://privacysandbox.google.com/cookies/related-website-sets) on privacysandbox.google.com (2023) +- [Related Website Sets: developer guide](https://privacysandbox.google.com/cookies/related-website-sets-integration) on privacysandbox.google.com (2023) diff --git a/files/en-us/web/api/storage_access_api/using/index.md b/files/en-us/web/api/storage_access_api/using/index.md index 9fce2770c0d9b26..a4ca76a094650b7 100644 --- a/files/en-us/web/api/storage_access_api/using/index.md +++ b/files/en-us/web/api/storage_access_api/using/index.md @@ -19,7 +19,7 @@ In the example below, we show how an embedded cross-site {{htmlelement("iframe") ## Allowing a sandboxed \<iframe> to use the API -First of all, if the `<iframe>` is sandboxed, the embedding website needs to add the `allow-storage-access-by-user-activation` [sandbox token](/en-US/docs/Web/HTML/Element/iframe#sandbox) to allow Storage Access API requests to be successful, along with `allow-scripts` and `allow-same-origin` to allow it to execute a script to call the API and execute it in an origin that can have cookies and state: +First of all, if the `<iframe>` is sandboxed, the embedding website needs to add the `allow-storage-access-by-user-activation` [sandbox token](/en-US/docs/Web/HTML/Reference/Elements/iframe#sandbox) to allow Storage Access API requests to be successful, along with `allow-scripts` and `allow-same-origin` to allow it to execute a script to call the API and execute it in an origin that can have cookies and state: ```html <iframe @@ -182,7 +182,7 @@ to discover if the origin has previously been granted permission or if cookie ac - If the permission status is `"granted"` we can start using cookies; `requestStorageAccessFor()` was already called, so there is no need to call it again. - If the permission status is `"prompt"` we need to call `document.requestStorageAccessFor("https://example.com")` from within a user gesture, such as a button click. -After the `"top-level-storage-access"` permission is granted, cross-site requests will include cookies if they include [CORS](/en-US/docs/Web/HTTP/CORS) / [`crossorigin`](/en-US/docs/Web/HTML/Attributes/crossorigin), so sites may want to wait before triggering a request. Such requests must use the [`credentials: "include"`](/en-US/docs/Web/API/RequestInit#credentials) option and resources must include the `crossorigin="use-credentials"` attribute. +After the `"top-level-storage-access"` permission is granted, cross-site requests will include cookies if they include [CORS](/en-US/docs/Web/HTTP/Guides/CORS) / [`crossorigin`](/en-US/docs/Web/HTML/Reference/Attributes/crossorigin), so sites may want to wait before triggering a request. Such requests must use the [`credentials: "include"`](/en-US/docs/Web/API/RequestInit#credentials) option and resources must include the `crossorigin="use-credentials"` attribute. For example: diff --git a/files/en-us/web/api/storage_api/storage_quotas_and_eviction_criteria/index.md b/files/en-us/web/api/storage_api/storage_quotas_and_eviction_criteria/index.md index 441030a83df4840..14534622fb3ff07 100644 --- a/files/en-us/web/api/storage_api/storage_quotas_and_eviction_criteria/index.md +++ b/files/en-us/web/api/storage_api/storage_quotas_and_eviction_criteria/index.md @@ -28,7 +28,7 @@ Web developers can use the following web technologies to store data in the brows | Technology | Description | | --------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| [Cookies](/en-US/docs/Web/HTTP/Cookies) | An HTTP cookie is a small piece of data that the web server and browser send each other to remember stateful information across page navigation. | +| [Cookies](/en-US/docs/Web/HTTP/Guides/Cookies) | An HTTP cookie is a small piece of data that the web server and browser send each other to remember stateful information across page navigation. | | [Web Storage](/en-US/docs/Web/API/Web_Storage_API) | The Web Storage API provides mechanisms for webpages to store string-only key/value pairs, including [`localStorage`](/en-US/docs/Web/API/Window/localStorage) and [`sessionStorage`](/en-US/docs/Web/API/Window/sessionStorage). | | [IndexedDB](/en-US/docs/Web/API/IndexedDB_API) | IndexedDB is a Web API for storing large data structures in the browser and indexing them for high-performance searching. | | [Cache API](/en-US/docs/Web/API/Cache) | The Cache API provides a persistent storage mechanism for HTTP request and response object pairs that's used to make webpages load faster. | diff --git a/files/en-us/web/api/storageaccesshandle/locks/index.md b/files/en-us/web/api/storageaccesshandle/locks/index.md index 01de3ac56ff04c3..30711ac82d3f26d 100644 --- a/files/en-us/web/api/storageaccesshandle/locks/index.md +++ b/files/en-us/web/api/storageaccesshandle/locks/index.md @@ -20,9 +20,7 @@ A {{domxref("LockManager")}} object. document.requestStorageAccess({ locks: true }).then( (handle) => { console.log("locks access granted"); - await handle.locks.request('foo', async lock => { - return "ok"; - }); + handle.locks.request("foo", (lock) => "ok"); }, () => { console.log("locks access denied"); diff --git a/files/en-us/web/api/storagemanager/estimate/index.md b/files/en-us/web/api/storagemanager/estimate/index.md index 3b5c3bf1ed55dda..b8c1eec8c0b8652 100644 --- a/files/en-us/web/api/storagemanager/estimate/index.md +++ b/files/en-us/web/api/storagemanager/estimate/index.md @@ -69,7 +69,7 @@ navigator.storage.estimate().then((estimate) => { 100 ).toFixed(2); document.getElementById("quota").value = - (estimate.quota / 1024 / 1024).toFixed(2) + "MB"; + `${(estimate.quota / 1024 / 1024).toFixed(2)}MB`; }); ``` diff --git a/files/en-us/web/api/streams_api/index.md b/files/en-us/web/api/streams_api/index.md index ef13023c46a50c5..dbb49d71bcd3a5c 100644 --- a/files/en-us/web/api/streams_api/index.md +++ b/files/en-us/web/api/streams_api/index.md @@ -37,9 +37,9 @@ You can also write data to streams using {{domxref("WritableStream")}}. ### Readable streams - {{domxref("ReadableStream")}} - - : Represents a readable stream of data. It can be used to handle response streams of the [Fetch API](/en-US/docs/Web/API/Fetch_API), or developer-defined streams (e.g. a custom {{domxref("ReadableStream.ReadableStream", "ReadableStream()")}} constructor). + - : Represents a readable stream of data. It can be used to handle response streams of the [Fetch API](/en-US/docs/Web/API/Fetch_API), or developer-defined streams (e.g., a custom {{domxref("ReadableStream.ReadableStream", "ReadableStream()")}} constructor). - {{domxref("ReadableStreamDefaultReader")}} - - : Represents a default reader that can be used to read stream data supplied from a network (e.g. a fetch request). + - : Represents a default reader that can be used to read stream data supplied from a network (e.g., a fetch request). - {{domxref("ReadableStreamDefaultController")}} - : Represents a controller allowing control of a {{domxref("ReadableStream")}}'s state and internal queue. Default controllers are for streams that are not byte streams. @@ -76,7 +76,7 @@ You can also write data to streams using {{domxref("WritableStream")}}. ### ByteStream-related interfaces - {{domxref("ReadableStreamBYOBReader")}} - - : Represents a BYOB ("bring your own buffer") reader that can be used to read stream data supplied by the developer (e.g. a custom {{domxref("ReadableStream.ReadableStream", "ReadableStream()")}} constructor). + - : Represents a BYOB ("bring your own buffer") reader that can be used to read stream data supplied by the developer (e.g., a custom {{domxref("ReadableStream.ReadableStream", "ReadableStream()")}} constructor). - {{domxref("ReadableByteStreamController")}} - : Represents a controller allowing control of a {{domxref("ReadableStream")}}'s state and internal queue. Byte stream controllers are for byte streams. - {{domxref("ReadableStreamBYOBRequest")}} diff --git a/files/en-us/web/api/streams_api/using_readable_byte_streams/index.md b/files/en-us/web/api/streams_api/using_readable_byte_streams/index.md index 47081be1cdadfd8..0c5fd7332ab672a 100644 --- a/files/en-us/web/api/streams_api/using_readable_byte_streams/index.md +++ b/files/en-us/web/api/streams_api/using_readable_byte_streams/index.md @@ -102,9 +102,9 @@ class MockHypotheticalSocket { const resultObj = {}; resultObj["bytesRead"] = 0; - return new Promise((resolve /*, reject*/) => { + return new Promise((resolve /*, reject */) => { if (this.data_read >= this.max_data) { - //out of data + // Out of data resolve(resultObj); return; } @@ -137,9 +137,7 @@ class MockHypotheticalSocket { } // Dummy close function - close() { - return; - } + close() {} // Return random number bytes in this call of socket getNumberRandomBytesSocket() { @@ -347,7 +345,7 @@ function readStream(reader) { offset += value.byteLength; bytesReceived += value.byteLength; - //logConsumer(`Read ${bytesReceived} bytes: ${value}`); + // logConsumer(`Read ${bytesReceived} bytes: ${value}`); logConsumer(`Read ${bytesReceived} bytes`); result += value; @@ -355,7 +353,9 @@ function readStream(reader) { if (bytesReceived > 300 && bytesReceived < 600) { logConsumer(`Delaying read to emulate slow stream reading`); const delay = (ms) => - new Promise((resolve) => setTimeout(resolve, ms)); + new Promise((resolve) => { + setTimeout(resolve, ms); + }); await delay(1000); } @@ -440,9 +440,9 @@ class MockUnderlyingFileHandle { resultObj["buffer"] = buffer; resultObj["bytesRead"] = 0; - return new Promise((resolve /*, reject*/) => { + return new Promise((resolve /*, reject */) => { if (position >= this.maxdata) { - //out of data + // Out of data resolve(resultObj); return; } @@ -473,9 +473,7 @@ class MockUnderlyingFileHandle { } // Dummy close function - close() { - return; - } + close() {} // Return random character string randomChars(length = 8) { @@ -574,7 +572,7 @@ function makeReadableByteFileStream(filename) { return new ReadableStream({ type: "bytes", // An underlying byte stream! start(controller) { - // Called to initialise the underlying source. + // Called to initialize the underlying source. // For a file source open a file handle (here we just create the mocked object). fileHandle = new MockUnderlyingFileHandle(); logSource( @@ -701,9 +699,9 @@ class MockUnderlyingFileHandle { resultObj["buffer"] = buffer; resultObj["bytesRead"] = 0; - return new Promise((resolve /*, reject*/) => { + return new Promise((resolve /*, reject */) => { if (position >= this.maxdata) { - //out of data + // Out of data resolve(resultObj); return; } @@ -734,9 +732,7 @@ class MockUnderlyingFileHandle { } // Dummy close function - close() { - return; - } + close() {} // Return random character string randomChars(length = 8) { @@ -825,7 +821,7 @@ function makeReadableByteFileStream(filename) { return new ReadableStream({ type: "bytes", // An underlying byte stream! start(controller) { - // Called to initialise the underlying source. + // Called to initialize the underlying source. // For a file source open a file handle (here we just create the mocked object). fileHandle = new MockUnderlyingFileHandle(); logSource( @@ -941,9 +937,9 @@ class MockUnderlyingFileHandle { resultObj["buffer"] = buffer; resultObj["bytesRead"] = 0; - return new Promise((resolve /*, reject*/) => { + return new Promise((resolve /*, reject */) => { if (position >= this.maxdata) { - //out of data + // Out of data resolve(resultObj); return; } @@ -974,9 +970,7 @@ class MockUnderlyingFileHandle { } // Dummy close function - close() { - return; - } + close() {} // Return random character string randomChars(length = 8) { @@ -1065,7 +1059,7 @@ function makeReadableByteFileStream(filename) { return new ReadableStream({ type: "bytes", // An underlying byte stream! start(controller) { - // Called to initialise the underlying source. + // Called to initialize the underlying source. // For a file source open a file handle (here we just create the mocked object). fileHandle = new MockUnderlyingFileHandle(); logSource( diff --git a/files/en-us/web/api/streams_api/using_readable_streams/index.md b/files/en-us/web/api/streams_api/using_readable_streams/index.md index dd3be5cbd3c8824..c31ff982b067d62 100644 --- a/files/en-us/web/api/streams_api/using_readable_streams/index.md +++ b/files/en-us/web/api/streams_api/using_readable_streams/index.md @@ -50,7 +50,7 @@ fetch("./tortoise.png") }); ``` -Invoking this method creates a reader and locks it to the stream — no other reader may read this stream until this reader is released, e.g. by invoking {{domxref("ReadableStreamDefaultReader.releaseLock()")}}. +Invoking this method creates a reader and locks it to the stream — no other reader may read this stream until this reader is released, e.g., by invoking {{domxref("ReadableStreamDefaultReader.releaseLock()")}}. Also note that the previous example can be reduced by one step, as `response.body` is synchronous and so doesn't need the promise: @@ -274,9 +274,7 @@ class MockPushSource { } // Dummy close function - close() { - return; - } + close() {} // Return random character string static #randomChars(length = 8) { @@ -356,7 +354,7 @@ function makePushSourceStream() { readRepeatedly().catch((e) => controller.error(e)); function readRepeatedly() { return pushSource.dataRequest().then((result) => { - if (result.data.length == 0) { + if (result.data.length === 0) { logSource(`No data from source: closing`); controller.close(); return; @@ -379,9 +377,7 @@ function makePushSourceStream() { ```js hidden // Monkey patch fetch() so it returns a response that is a mocked stream -window.fetch = async (...args) => { - return { body: stream }; -}; +window.fetch = async (...args) => ({ body: stream }); ``` The code below shows a more complete example. @@ -456,9 +452,9 @@ The constructor takes two objects as parameters. The first object is required, a The first object can contain up to five members, only the first of which is required: -1. `start(controller)` — A method that is called once, immediately after the `ReadableStream` is constructed. Inside this method, you should include code that sets up the stream functionality, e.g. beginning generation of data or otherwise getting access to the source. +1. `start(controller)` — A method that is called once, immediately after the `ReadableStream` is constructed. Inside this method, you should include code that sets up the stream functionality, e.g., beginning generation of data or otherwise getting access to the source. 2. `pull(controller)` — A method that, when included, is called repeatedly until the stream's internal queue is full. This can be used to control the stream as more chunks are enqueued. -3. `cancel()` — A method that, when included, will be called if the app signals that the stream is to be cancelled (e.g. if {{domxref("ReadableStream.cancel()")}} is called). The contents should do whatever is necessary to release access to the stream source. +3. `cancel()` — A method that, when included, will be called if the app signals that the stream is to be cancelled (e.g., if {{domxref("ReadableStream.cancel()")}} is called). The contents should do whatever is necessary to release access to the stream source. 4. `type` and `autoAllocateChunkSize` — These are used — when included — to signify that the stream is to be a bytestream. Bytestreams are covered separately in [Using readable byte streams](/en-US/docs/Web/API/Streams_API/Using_readable_byte_streams), as they are somewhat different in purpose and use case to regular (default) streams. diff --git a/files/en-us/web/api/streams_api/using_writable_streams/index.md b/files/en-us/web/api/streams_api/using_writable_streams/index.md index ba5b94d57a076d9..b75b9828d0c940a 100644 --- a/files/en-us/web/api/streams_api/using_writable_streams/index.md +++ b/files/en-us/web/api/streams_api/using_writable_streams/index.md @@ -48,7 +48,7 @@ The constructor takes two objects as parameters. The first object is required, a The first object can contain up to four members, all of which are optional: -1. `start(controller)` — A method that is called once, immediately after the {{domxref("WritableStream")}} is constructed. Inside this method, you should include code that sets up the stream functionality, e.g. getting access to the underlying sink. +1. `start(controller)` — A method that is called once, immediately after the {{domxref("WritableStream")}} is constructed. Inside this method, you should include code that sets up the stream functionality, e.g., getting access to the underlying sink. 2. `write(chunk,controller)` — A method that is called repeatedly every time a new chunk is ready to be written to the underlying sink (specified in the `chunk` parameter). 3. `close(controller)` — A method that is called if the app signals that it has finished writing chunks to the stream. It should do whatever is necessary to finalize writes to the underlying sink, and release access to it. 4. `abort(reason)` — A method that will be called if the app signals that it wishes to abruptly close the stream and put it in an errored state. @@ -107,7 +107,7 @@ function sendMessage(message, writableStream) { // defaultWriter is of type WritableStreamDefaultWriter const defaultWriter = writableStream.getWriter(); const encoder = new TextEncoder(); - const encoded = encoder.encode(message, { stream: true }); + const encoded = encoder.encode(message); encoded.forEach((chunk) => { defaultWriter.ready .then(() => defaultWriter.write(chunk)) @@ -127,7 +127,7 @@ So here we create a writer to write the chunks to the stream using {{domxref("Wr We also create a new {{domxref("TextEncoder")}} instance using the relevant constructor to encode the message into chunks to be put into the stream. -With the chunks encoded, we then call [`forEach()`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/forEach) on the resulting array. Inside this block we use {{domxref("WritableStreamDefaultWriter.ready")}} to check whether the writer is ready to have another chunk written to it. `ready` returns a promise that fulfills when this is the case, inside of which we call {{domxref("WritableStreamDefaultWriter.write()")}} to actually write the chunk to the stream. This also triggers the `write()` method specified inside the `WritableStream()` constructor, as discussed above. +With the chunks encoded, we then call [`forEach()`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/TypedArray/forEach) on the resulting array. Inside this block we use {{domxref("WritableStreamDefaultWriter.ready")}} to check whether the writer is ready to have another chunk written to it. `ready` returns a promise that fulfills when this is the case, inside of which we call {{domxref("WritableStreamDefaultWriter.write()")}} to actually write the chunk to the stream. This also triggers the `write()` method specified inside the `WritableStream()` constructor, as discussed above. After the chunks have all been written, we then perform the `ready` check once more, to check that the last chunk has finished being written and all the work is done. When this `ready` check fulfills, we invoke {{domxref("WritableStreamDefaultWriter.close()")}} to close the stream. This also triggers the `close()` method specified inside the `WritableStream()` constructor, as discussed above. diff --git a/files/en-us/web/api/stylepropertymap/append/index.md b/files/en-us/web/api/stylepropertymap/append/index.md index b46934477190d9f..accaeb0a7127e10 100644 --- a/files/en-us/web/api/stylepropertymap/append/index.md +++ b/files/en-us/web/api/stylepropertymap/append/index.md @@ -21,7 +21,7 @@ append(property, value) ### Parameters - `property` - - : An identifier indicating the stylistic feature (e.g. font, width, background + - : An identifier indicating the stylistic feature (e.g., font, width, background color) to add. - `value` - : The value the given property should have. diff --git a/files/en-us/web/api/stylepropertymap/clear/index.md b/files/en-us/web/api/stylepropertymap/clear/index.md index 0de61a1a088192c..9f51bc9b9566fb1 100644 --- a/files/en-us/web/api/stylepropertymap/clear/index.md +++ b/files/en-us/web/api/stylepropertymap/clear/index.md @@ -27,7 +27,7 @@ None ({{jsxref("undefined")}}). ## Examples -The following example removes all styles within the elements [style attribute](/en-US/docs/Web/HTML/Global_attributes/style). +The following example removes all styles within the elements [style attribute](/en-US/docs/Web/HTML/Reference/Global_attributes/style). ```js // get the button element diff --git a/files/en-us/web/api/stylepropertymap/delete/index.md b/files/en-us/web/api/stylepropertymap/delete/index.md index 18897acbde149da..e5b5e466c5a5bc4 100644 --- a/files/en-us/web/api/stylepropertymap/delete/index.md +++ b/files/en-us/web/api/stylepropertymap/delete/index.md @@ -21,7 +21,7 @@ delete(property) ### Parameters - `property` - - : An identifier indicating the stylistic feature (e.g. font, width, background + - : An identifier indicating the stylistic feature (e.g., font, width, background color) to remove. ### Return value @@ -31,7 +31,7 @@ None ({{jsxref("undefined")}}). ## Examples The following example removes the {{cssxref('background-image')}} property from the -element's [style attribute](/en-US/docs/Web/HTML/Global_attributes/style). +element's [style attribute](/en-US/docs/Web/HTML/Reference/Global_attributes/style). ```js // get the button element diff --git a/files/en-us/web/api/stylepropertymap/set/index.md b/files/en-us/web/api/stylepropertymap/set/index.md index cba5c69b60fa88d..580049728936be6 100644 --- a/files/en-us/web/api/stylepropertymap/set/index.md +++ b/files/en-us/web/api/stylepropertymap/set/index.md @@ -20,7 +20,7 @@ set(property, value) ### Parameters - `property` - - : An identifier indicating the stylistic feature (e.g. font, width, background + - : An identifier indicating the stylistic feature (e.g., font, width, background color) to change. - `value` - : The value the given property should have. @@ -32,7 +32,7 @@ None ({{jsxref("undefined")}}). ## Examples This example sets the {{cssxref('padding-top')}} property, with the given value, within -the element's [style attribute](/en-US/docs/Web/HTML/Global_attributes/style). +the element's [style attribute](/en-US/docs/Web/HTML/Reference/Global_attributes/style). ```js // get the button element diff --git a/files/en-us/web/api/stylesheet/disabled/index.md b/files/en-us/web/api/stylesheet/disabled/index.md index 73eacbda630bb24..f0c656da1f2ad9d 100644 --- a/files/en-us/web/api/stylesheet/disabled/index.md +++ b/files/en-us/web/api/stylesheet/disabled/index.md @@ -13,7 +13,7 @@ The **`disabled`** property of the applying to the document. A style sheet may be disabled by manually setting this property to `true` or -if it's an inactive [alternative style sheet](/en-US/docs/Web/HTML/Attributes/rel/alternate_stylesheet). Note that `disabled === false` does not guarantee the style +if it's an inactive [alternative style sheet](/en-US/docs/Web/HTML/Reference/Attributes/rel/alternate_stylesheet). Note that `disabled === false` does not guarantee the style sheet is applied (it could be removed from the document, for instance). ## Value diff --git a/files/en-us/web/api/stylesheet/media/index.md b/files/en-us/web/api/stylesheet/media/index.md index cd0a9af1f379685..c54ee73d81b6dad 100644 --- a/files/en-us/web/api/stylesheet/media/index.md +++ b/files/en-us/web/api/stylesheet/media/index.md @@ -38,10 +38,8 @@ A read-only array-like `MediaList` object. document.styleSheets[i].media, )}`, ); - if (iSheetIndex === 0) - document.styleSheets[i].media.appendMedium("handheld"); - if (iSheetIndex === 1) - document.styleSheets[i].media.deleteMedium("print"); + if (i === 0) document.styleSheets[i].media.appendMedium("handheld"); + if (i === 1) document.styleSheets[i].media.deleteMedium("print"); console.log( `document.styleSheets[${i}].media: ${JSON.stringify( document.styleSheets[i].media, diff --git a/files/en-us/web/api/stylesheet/ownernode/index.md b/files/en-us/web/api/stylesheet/ownernode/index.md index 8f5ec4a709356ef..7965ade1ca965dc 100644 --- a/files/en-us/web/api/stylesheet/ownernode/index.md +++ b/files/en-us/web/api/stylesheet/ownernode/index.md @@ -13,8 +13,8 @@ The **`ownerNode`** property of the with the document. This is usually an HTML -[`<link>`](/en-US/docs/Web/HTML/Element/link) or -[`<style>`](/en-US/docs/Web/HTML/Element/style) element, but +[`<link>`](/en-US/docs/Web/HTML/Reference/Elements/link) or +[`<style>`](/en-US/docs/Web/HTML/Reference/Elements/style) element, but can also return a [processing instruction node](/en-US/docs/Web/API/ProcessingInstruction) in the case of `<?xml-stylesheet ?>`. ## Value diff --git a/files/en-us/web/api/stylesheetlist/index.md b/files/en-us/web/api/stylesheetlist/index.md index da0bbf4aa3015f4..490ac3dc9f23632 100644 --- a/files/en-us/web/api/stylesheetlist/index.md +++ b/files/en-us/web/api/stylesheetlist/index.md @@ -31,11 +31,8 @@ It is an array-like object but can't be iterated over using {{jsxref("Array")}} ### Get CSSStyleSheet objects with for loop ```js -const styleSheet = []; -const styleSheets = document.styleSheets; - -for (let i = 0; i < styleSheets.length; i++) { - styleSheet.push(styleSheets[i]); +for (const styleSheet of document.styleSheets) { + console.log(styleSheet); // A CSSStyleSheet object } ``` @@ -51,6 +48,7 @@ const allCSS = [...document.styleSheets] "Access to stylesheet %s is denied. Ignoring…", styleSheet.href, ); + return undefined; } }) .filter(Boolean) diff --git a/files/en-us/web/api/submitevent/submitter/index.md b/files/en-us/web/api/submitevent/submitter/index.md index 605cb0fb46f1c35..a675c5883f9c0ec 100644 --- a/files/en-us/web/api/submitevent/submitter/index.md +++ b/files/en-us/web/api/submitevent/submitter/index.md @@ -16,7 +16,7 @@ that was invoked to cause the form to be submitted. An element, indicating the element that sent the {{domxref("HTMLFormElement.submit_event", "submit")}} event to the form. While this -is often an {{HTMLElement("input")}} element whose [`type`](/en-US/docs/Web/HTML/Element/input#type) is `submit` or a {{HTMLElement("button")}} element whose [`type`](/en-US/docs/Web/HTML/Element/input#type) is `submit`, it could be some other element which has initiated a +is often an {{HTMLElement("input")}} element whose [`type`](/en-US/docs/Web/HTML/Reference/Elements/input#type) is `submit` or a {{HTMLElement("button")}} element whose [`type`](/en-US/docs/Web/HTML/Reference/Elements/input#type) is `submit`, it could be some other element which has initiated a submission process. If the submission was not triggered by a button of some kind, the value of `submitter` is `null`. diff --git a/files/en-us/web/api/subtlecrypto/decrypt/index.md b/files/en-us/web/api/subtlecrypto/decrypt/index.md index b9d675fb7166b11..3f6715c9d746f58 100644 --- a/files/en-us/web/api/subtlecrypto/decrypt/index.md +++ b/files/en-us/web/api/subtlecrypto/decrypt/index.md @@ -44,9 +44,9 @@ A {{jsxref("Promise")}} that fulfills with an {{jsxref("ArrayBuffer")}} containi The promise is rejected when the following exceptions are encountered: - `InvalidAccessError` {{domxref("DOMException")}} - - : Raised when the requested operation is not valid for the provided key (e.g. invalid encryption algorithm, or invalid key for the specified encryption algorithm). + - : Raised when the requested operation is not valid for the provided key (e.g., invalid encryption algorithm, or invalid key for the specified encryption algorithm). - `OperationError` {{domxref("DOMException")}} - - : Raised when the operation failed for an operation-specific reason (e.g. algorithm parameters of invalid sizes, or there was an error decrypting the ciphertext). + - : Raised when the operation failed for an operation-specific reason (e.g., algorithm parameters of invalid sizes, or there was an error decrypting the ciphertext). ## Supported algorithms diff --git a/files/en-us/web/api/subtlecrypto/derivekey/index.md b/files/en-us/web/api/subtlecrypto/derivekey/index.md index 6218bf16182aa20..6e16336b9882dc2 100644 --- a/files/en-us/web/api/subtlecrypto/derivekey/index.md +++ b/files/en-us/web/api/subtlecrypto/derivekey/index.md @@ -99,7 +99,7 @@ PBKDF2 is specified in [RFC 2898](https://datatracker.ietf.org/doc/html/rfc2898) #### ECDH -ECDH (Elliptic Curve Diffie-Hellman) is a _key-agreement algorithm_. +ECDH (Elliptic Curve Diffie–Hellman) is a _key-agreement algorithm_. It enables two people who each have an ECDH public/private key pair to generate a shared secret: that is, a secret that they — and no one else — share. They can then use this shared secret as a symmetric key to secure their communication, or can use the secret as an input to derive such a key (for example, using the HKDF algorithm). @@ -519,7 +519,7 @@ function getKey(keyMaterial, salt) { return window.crypto.subtle.deriveKey( { name: "HKDF", - salt: salt, + salt, info: new TextEncoder().encode("Encryption example"), hash: "SHA-256", }, diff --git a/files/en-us/web/api/subtlecrypto/digest/index.md b/files/en-us/web/api/subtlecrypto/digest/index.md index 25f4ca2500f363f..e025f27cbd446e5 100644 --- a/files/en-us/web/api/subtlecrypto/digest/index.md +++ b/files/en-us/web/api/subtlecrypto/digest/index.md @@ -8,14 +8,12 @@ browser-compat: api.SubtleCrypto.digest {{APIRef("Web Crypto API")}}{{SecureContext_header}}{{AvailableInWorkers}} -The **`digest()`** method of the {{domxref("SubtleCrypto")}} -interface generates a {{Glossary("digest")}} of the given data. A digest is a short -fixed-length value derived from some variable-length input. Cryptographic digests should -exhibit collision-resistance, meaning that it's hard to come up with two different -inputs that have the same digest value. +The **`digest()`** method of the {{domxref("SubtleCrypto")}} interface generates a _digest_ of the given data, using the specified {{glossary("hash function")}}. +A digest is a short fixed-length value derived from some variable-length input. +Cryptographic digests should exhibit collision-resistance, meaning that it's hard to come up with two different inputs that have the same digest value. -It takes as its arguments an identifier for the digest algorithm to use and the data to -digest. It returns a {{jsxref("Promise")}} which will be fulfilled with the digest. +It takes as its arguments an identifier for the digest algorithm to use and the data to digest. +It returns a {{jsxref("Promise")}} which will be fulfilled with the digest. Note that this API does not support streaming input: you must read the entire input into memory before passing it into the digest function. @@ -42,10 +40,8 @@ A {{jsxref("Promise")}} that fulfills with an {{jsxref("ArrayBuffer")}} containi ## Supported algorithms -Digest algorithms, also known as [cryptographic hash functions](/en-US/docs/Glossary/Cryptographic_hash_function), -transform an arbitrarily large block of data into a fixed-size output, -usually much shorter than the input. They have a variety of applications in -cryptography. +Digest algorithms, also known as {{glossary("Hash function", "hash functions")}}, transform an arbitrarily large block of data into a fixed-size output, usually much shorter than the input. +They have a variety of applications in cryptography. <table class="standard-table"> <tbody> @@ -99,12 +95,10 @@ cryptography. </table> > [!WARNING] -> SHA-1 is now considered vulnerable and should not -> be used for cryptographic applications. +> SHA-1 is now considered vulnerable and should not be used for cryptographic applications. > [!NOTE] -> If you are looking here for how to create a keyed-hash message authentication -> code ([HMAC](/en-US/docs/Glossary/HMAC)), you need to use the [SubtleCrypto.sign()](/en-US/docs/Web/API/SubtleCrypto/sign#hmac) instead. +> If you are looking here for how to create a keyed-hash message authentication code ([HMAC](/en-US/docs/Glossary/HMAC)), you need to use the [SubtleCrypto.sign()](/en-US/docs/Web/API/SubtleCrypto/sign#hmac) instead. ## Examples @@ -133,9 +127,8 @@ digestMessage(text).then((digestBuffer) => ### Converting a digest to a hex string -The digest is returned as an `ArrayBuffer`, but for comparison and display -digests are often represented as hex strings. This example calculates a digest, then -converts the `ArrayBuffer` to a hex string: +The digest is returned as an `ArrayBuffer`, but for comparison and display digests are often represented as hex strings. +This example calculates a digest, then converts the `ArrayBuffer` to a hex string: ```js const text = diff --git a/files/en-us/web/api/subtlecrypto/encrypt/index.md b/files/en-us/web/api/subtlecrypto/encrypt/index.md index 47aa2eb49f48ff5..4bfd24247af1e40 100644 --- a/files/en-us/web/api/subtlecrypto/encrypt/index.md +++ b/files/en-us/web/api/subtlecrypto/encrypt/index.md @@ -44,9 +44,9 @@ A {{jsxref("Promise")}} that fulfills with an {{jsxref("ArrayBuffer")}} containi The promise is rejected when the following exceptions are encountered: - `InvalidAccessError` {{domxref("DOMException")}} - - : Raised when the requested operation is not valid for the provided key (e.g. invalid encryption algorithm, or invalid key for the specified encryption algorithm). + - : Raised when the requested operation is not valid for the provided key (e.g., invalid encryption algorithm, or invalid key for the specified encryption algorithm). - `OperationError` {{domxref("DOMException")}} - - : Raised when the operation failed for an operation-specific reason (e.g. algorithm parameters of invalid sizes, or AES-GCM plaintext longer than 2<sup>39</sup>−256 bytes). + - : Raised when the operation failed for an operation-specific reason (e.g., algorithm parameters of invalid sizes, or AES-GCM plaintext longer than 2<sup>39</sup>−256 bytes). ## Supported algorithms @@ -208,14 +208,7 @@ function encryptMessage(key) { let encoded = getMessageEncoding(); // iv will be needed for decryption iv = window.crypto.getRandomValues(new Uint8Array(16)); - return window.crypto.subtle.encrypt( - { - name: "AES-CBC", - iv: iv, - }, - key, - encoded, - ); + return window.crypto.subtle.encrypt({ name: "AES-CBC", iv }, key, encoded); } ``` @@ -236,11 +229,7 @@ function encryptMessage(key) { const encoded = getMessageEncoding(); // iv will be needed for decryption const iv = window.crypto.getRandomValues(new Uint8Array(12)); - return window.crypto.subtle.encrypt( - { name: "AES-GCM", iv: iv }, - key, - encoded, - ); + return window.crypto.subtle.encrypt({ name: "AES-GCM", iv }, key, encoded); } ``` diff --git a/files/en-us/web/api/subtlecrypto/sign/index.md b/files/en-us/web/api/subtlecrypto/sign/index.md index 83489f4c6756dcf..03df74f2fa9b245 100644 --- a/files/en-us/web/api/subtlecrypto/sign/index.md +++ b/files/en-us/web/api/subtlecrypto/sign/index.md @@ -203,7 +203,7 @@ let signature = await window.crypto.subtle.sign("HMAC", key, encoded); ### Ed25519 (key generation, signing, and verification) -This code generates an Ed25519 signing key pair, uses the private key to sign the (encoded) contents of a text [`<input>`](/en-US/docs/Web/HTML/Element/input/text), and then verifies the signature using the public key. +This code generates an Ed25519 signing key pair, uses the private key to sign the (encoded) contents of a text [`<input>`](/en-US/docs/Web/HTML/Reference/Elements/input/text), and then verifies the signature using the public key. It is derived from [this source code on GitHub.](https://github.com/mdn/dom-examples/blob/main/web-crypto/sign-verify/ed25519.js), which you can [run live here](https://mdn.github.io/dom-examples/web-crypto/sign-verify/). #### HTML @@ -291,7 +291,7 @@ async function test(data) { log( `encodedData: ${shorterEncodedBuffer}...[${encodedData.byteLength} bytes total]`, ); - //log(`encodedData: ${encodedData}`); + // log(`encodedData: ${encodedData}`); // Sign the data using the private key. const signature = await crypto.subtle.sign( diff --git a/files/en-us/web/api/summarizer/availability_static/index.md b/files/en-us/web/api/summarizer/availability_static/index.md new file mode 100644 index 000000000000000..f74a0fa383b6fc8 --- /dev/null +++ b/files/en-us/web/api/summarizer/availability_static/index.md @@ -0,0 +1,121 @@ +--- +title: "Summarizer: availability() static method" +short-title: availability() +slug: Web/API/Summarizer/availability_static +page-type: web-api-static-method +status: + - experimental +browser-compat: api.Summarizer.availability_static +--- + +{{APIRef("Summarizer API")}}{{securecontext_header}}{{SeeCompatTable}} + +The **`availability()`** static method of the {{domxref("Summarizer")}} interface returns an enumerated value that indicates whether the browser AI model supports (or will support) a given `Summarizer` configuration. + +## Syntax + +```js-nolint +Summarizer.availability() +Summarizer.availability(options) +``` + +### Parameters + +- `options` {{optional_inline}} + + - : An options object specifying a possible configuration for a `Summarizer`. Possible values include: + + - `expectedInputLanguages` + - : An array of strings equal to [BCP 47 language tags](https://en.wikipedia.org/wiki/IETF_language_tag#List_of_common_primary_language_subtags) (as specified in [RFC 5646](https://datatracker.ietf.org/doc/html/rfc5646)) specifying the expected languages of the input text. Defaults to `["en"]`. + - `expectedContextLanguages` + - : An array of strings equal to BCP 47 language tags specifying the expected languages of any provided context strings (either the [`sharedContext`](/en-US/docs/Web/API/Summarizer/create_static#sharedcontext) passed to the `Summarizer`, or a `context` specified during a {{domxref("Summarizer.summarize", "summarize()")}} or {{domxref("Summarizer.summarizeStreaming", "summarizeStreaming()")}} call). Defaults to `["en"]`. + - `format` + - : An enumerated value specifying the text {{domxref("Summarizer.format", "format")}} you want summaries returned in. Defaults to `markdown`. + - `length` + - : An enumerated value specifying the relative {{domxref("Summarizer.length", "length")}} for the generated summaries. Defaults to `short`. + - `outputLanguage` + - : A string equal to a BCP 47 language tag specifying the expected language of summaries generated by the `Summarizer`. Defaults to `en`. + - `type` + - : An enumerated value specifying the {{domxref("Summarizer.type", "type")}} of summary you want this `Summarizer` to generate. Defaults to `key-points`. + +### Return value + +A {{jsxref("Promise")}} that fulfills with an enumerated value indicating whether support is available (or will be available) for a given `Summarizer` configuration, or `null` if support could not be determined. + +Possible values include: + +- `available` + - : The browser supports the given configuration and can be used immediately. +- `downloadable` + - : The browser supports the given configuration, but it first needs to download an AI model, or some fine-tuning data for the model. +- `downloading` + - : The browser supports the given configuration, but it needs to finish an ongoing download before it can proceed. +- `unavailable` + - : The browser does not support the given configuration. + +### Exceptions + +- `NotAllowedError` {{domxref("DOMException")}} + - : Thrown if usage of the Summarizer API is blocked by a {{httpheader('Permissions-Policy/summarizer','summarizer')}} {{httpheader("Permissions-Policy")}}. +- `NotSupportedError` {{domxref("DOMException")}} + - : Thrown if the provided `context` is not in language the `Summarizer` supports. +- `UnknownError` {{domxref("DOMException")}} + - : Thrown if the `measureInputUsage()` call failed for any other reason, or a reason the user agent did not wish to disclose. + +## Examples + +### Basic `availability()` usage + +```js +async function getSummarizer() { + const options = { + sharedContext: "This is a scientific article", + type: "key-points", + format: "markdown", + length: "medium", + }; + + const availability = await Summarizer.availability(options); + if (availability === "unavailable") { + // The Summarizer API isn't usable + return undefined; + } else if (availability === "available") { + // The Summarizer API can be used immediately + return Summarizer.create(options); + } + // The Summarizer API can be used after the model is downloaded + const summarizer = await Summarizer.create(options); + summarizer.addEventListener("downloadprogress", (e) => { + console.log(`Downloaded ${e.loaded * 100}%`); + }); + return summarizer; +} +``` + +### Detecting language support + +```js +async function langSupport(lang) { + const availability = await Summarizer.availability({ + expectedInputLanguages: [lang], + }); + return availability; +} + +langSupport("en-US"); +langSupport("fr"); +langSupport("zh-CN"); +``` + +## Specifications + +{{Specifications}} + +## Browser compatibility + +{{Compat}} + +## See also + +- [Using the Summarizer API](/en-US/docs/Web/API/Summarizer_API/Using) +- [Web AI demos](https://chrome.dev/web-ai-demos/) on chrome.dev diff --git a/files/en-us/web/api/summarizer/create_static/index.md b/files/en-us/web/api/summarizer/create_static/index.md new file mode 100644 index 000000000000000..d3dbd8520ccb5a5 --- /dev/null +++ b/files/en-us/web/api/summarizer/create_static/index.md @@ -0,0 +1,90 @@ +--- +title: "Summarizer: create() static method" +short-title: create() +slug: Web/API/Summarizer/create_static +page-type: web-api-static-method +status: + - experimental +browser-compat: api.Summarizer.create_static +--- + +{{APIRef("Summarizer API")}}{{securecontext_header}}{{SeeCompatTable}} + +The **`create()`** static method of the {{domxref("Summarizer")}} interface creates a new `Summarizer` instance from which to generate summaries. + +> [!NOTE] +> The `create()` method requires [transient activation](/en-US/docs/Glossary/Transient_activation), that is, it must be invoked in response to a user action such as a mouse click or button press. + +## Syntax + +```js-nolint +Summarizer.create() +Summarizer.create(options) +``` + +### Parameters + +- `options` {{optional_inline}} + + - : An object specifying configuration options for the `Summarizer`. Possible values include: + + - `expectedInputLanguages` + - : An array of strings specifying the expected languages of the input text, which should be valid [BCP 47 language tags](https://en.wikipedia.org/wiki/IETF_language_tag#List_of_common_primary_language_subtags) (as specified in [RFC 5646](https://datatracker.ietf.org/doc/html/rfc5646)). Defaults to `["en"]`. + - `expectedContextLanguages` + - : An array of strings specifying the expected languages of any provided context strings (either the [`sharedContext`](#sharedcontext) passed to the `Summarizer`, or a `context` specified during a {{domxref("Summarizer.summarize", "summarize()")}} or {{domxref("Summarizer.summarizeStreaming", "summarizeStreaming()")}} call), which should be valid BCP 47 language tags. Defaults to `["en"]`. + - `format` + - : An enumerated value specifying the text {{domxref("Summarizer.format", "format")}} you want summaries returned in. Defaults to `markdown`. + - `length` + - : An enumerated value specifying the relative {{domxref("Summarizer.length", "length")}} for the generated summaries. Defaults to `short`. + - `monitor` + - : A callback function with a {{domxref("CreateMonitor")}} argument that enables monitoring download progress of the AI model. + - `outputLanguage` + - : A string specifying the expected language of summaries generated by the `Summarizer`, which should be a valid BCP 47 language tag. Defaults to `en`. + - `sharedContext` + - : A {{domxref("Summarizer.sharedContext", "sharedContext")}} string describing the context the pieces of text to summarize are being used in, which helps the `Summarizer` generate more suitable summaries. + - `signal` + - : An {{domxref("AbortSignal")}} object instance, which allows the `create()` operation to be aborted via the associated {{domxref("AbortController")}}. + - `type` + - : An enumerated value specifying the {{domxref("Summarizer.type", "type")}} of summary you want this `Summarizer` to generate. Defaults to `key-points`. + +### Return value + +A {{jsxref("Promise")}} that fulfills with a `Summarizer` object instance. + +### Exceptions + +- `NotAllowedError` {{domxref("DOMException")}} + - : Thrown if usage of the Summarizer API is blocked by a {{httpheader('Permissions-Policy/summarizer','summarizer')}} {{httpheader("Permissions-Policy")}}. +- `NotSupportedError` {{domxref("DOMException")}} + - : Thrown if any of the language tags specified in `expectedContextLanguages`, `expectedInputLanguages`, or `outputLanguage` are invalid, or not supported. +- `OperationError` {{domxref("DOMException")}} + - : General-purpose exception thrown if `Summarizer` creation failed for any other reason. + +## Examples + +### Basic `Summarizer` creation + +```js +const summarizer = await Summarizer.create({ + sharedContext: + "A general summary to help a user decide if the text is worth reading", + type: "tldr", + length: "short", + format: "markdown", + expectedInputLanguages: ["en-US"], + outputLanguage: "en-US", +}); +``` + +## Specifications + +{{Specifications}} + +## Browser compatibility + +{{Compat}} + +## See also + +- [Using the Summarizer API](/en-US/docs/Web/API/Summarizer_API/Using) +- [Web AI demos](https://chrome.dev/web-ai-demos/) on chrome.dev diff --git a/files/en-us/web/api/summarizer/destroy/index.md b/files/en-us/web/api/summarizer/destroy/index.md new file mode 100644 index 000000000000000..19a3047463bae34 --- /dev/null +++ b/files/en-us/web/api/summarizer/destroy/index.md @@ -0,0 +1,57 @@ +--- +title: "Summarizer: destroy() method" +short-title: destroy() +slug: Web/API/Summarizer/destroy +page-type: web-api-instance-method +status: + - experimental +browser-compat: api.Summarizer.destroy +--- + +{{APIRef("Summarizer API")}}{{SeeCompatTable}} + +The **`destroy()`** method of the {{domxref("Summarizer")}} interface destroys the `Summarizer` instance it is called on. It makes sense to destroy `Summarizer` objects if they are no longer going to be used, as they tie up significant resources in their handling. + +## Syntax + +```js-nolint +destroy() +``` + +### Parameters + +None. + +### Return value + +None ({{jsxref("undefined")}}). + +## Examples + +### Basic `destroy()` usage + +```js +const summarizer = await Summarizer.create({ + sharedContext: + "A general summary to help a user decide if the text is worth reading", + type: "tldr", + length: "short", +}); + +// ... + +summarizer.destroy(); +``` + +## Specifications + +{{Specifications}} + +## Browser compatibility + +{{Compat}} + +## See also + +- [Using the Summarizer API](/en-US/docs/Web/API/Summarizer_API/Using) +- [Web AI demos](https://chrome.dev/web-ai-demos/) on chrome.dev diff --git a/files/en-us/web/api/summarizer/expectedcontextlanguages/index.md b/files/en-us/web/api/summarizer/expectedcontextlanguages/index.md new file mode 100644 index 000000000000000..f06dcf6747a0b35 --- /dev/null +++ b/files/en-us/web/api/summarizer/expectedcontextlanguages/index.md @@ -0,0 +1,44 @@ +--- +title: "Summarizer: expectedContextLanguages property" +short-title: expectedContextLanguages +slug: Web/API/Summarizer/expectedContextLanguages +page-type: web-api-instance-property +status: + - experimental +browser-compat: api.Summarizer.expectedContextLanguages +--- + +{{APIRef("Summarizer API")}}{{SeeCompatTable}} + +The **`expectedContextLanguages`** read-only property of the {{domxref("Summarizer")}} interface returns the languages the context strings should be written in. + +## Value + +An array of strings specifying the expected languages of any provided context strings (either the {{domxref("Summarizer.sharedContext")}}, or a `context` specified during a {{domxref("Summarizer.summarize", "summarize()")}} or {{domxref("Summarizer.summarizeStreaming", "summarizeStreaming()")}} call). + +The strings should be valid [BCP 47 language tags](https://en.wikipedia.org/wiki/IETF_language_tag#List_of_common_primary_language_subtags) (as specified in [RFC 5646](https://datatracker.ietf.org/doc/html/rfc5646)). + +## Examples + +```js +const summarizer = await Summarizer.create({ + expectedContextLanguages: ["en-US", "fr"], + // ... +}); + +// Logs "en-US" +console.log(summarizer.expectedContextLanguages[0]); +``` + +## Specifications + +{{Specifications}} + +## Browser compatibility + +{{Compat}} + +## See also + +- [Using the Summarizer API](/en-US/docs/Web/API/Summarizer_API/Using) +- [Web AI demos](https://chrome.dev/web-ai-demos/) on chrome.dev diff --git a/files/en-us/web/api/summarizer/expectedinputlanguages/index.md b/files/en-us/web/api/summarizer/expectedinputlanguages/index.md new file mode 100644 index 000000000000000..c5e323ad050ecb4 --- /dev/null +++ b/files/en-us/web/api/summarizer/expectedinputlanguages/index.md @@ -0,0 +1,44 @@ +--- +title: "Summarizer: expectedInputLanguages property" +short-title: expectedInputLanguages +slug: Web/API/Summarizer/expectedInputLanguages +page-type: web-api-instance-property +status: + - experimental +browser-compat: api.Summarizer.expectedInputLanguages +--- + +{{APIRef("Summarizer API")}}{{SeeCompatTable}} + +The **`expectedInputLanguages`** read-only property of the {{domxref("Summarizer")}} interface returns the languages the `Summarizer` should support. + +## Value + +An array of strings specifying the languages the `Summarizer` should support. + +The strings should be valid [BCP 47 language tags](https://en.wikipedia.org/wiki/IETF_language_tag#List_of_common_primary_language_subtags) (as specified in [RFC 5646](https://datatracker.ietf.org/doc/html/rfc5646)). + +## Examples + +```js +const summarizer = await Summarizer.create({ + expectedInputLanguages: ["en-US", "fr"], + // ... +}); + +// Logs "en-US" +console.log(summarizer.expectedInputLanguages[0]); +``` + +## Specifications + +{{Specifications}} + +## Browser compatibility + +{{Compat}} + +## See also + +- [Using the Summarizer API](/en-US/docs/Web/API/Summarizer_API/Using) +- [Web AI demos](https://chrome.dev/web-ai-demos/) on chrome.dev diff --git a/files/en-us/web/api/summarizer/format/index.md b/files/en-us/web/api/summarizer/format/index.md new file mode 100644 index 000000000000000..d3ea78836538957 --- /dev/null +++ b/files/en-us/web/api/summarizer/format/index.md @@ -0,0 +1,47 @@ +--- +title: "Summarizer: format property" +short-title: format +slug: Web/API/Summarizer/format +page-type: web-api-instance-property +status: + - experimental +browser-compat: api.Summarizer.format +--- + +{{APIRef("Summarizer API")}}{{SeeCompatTable}} + +The **`format`** read-only property of the {{domxref("Summarizer")}} interface returns the text format summaries will be returned in. + +## Value + +An enumerated value specifying the format of returned summaries. Possible values are: + +- `markdown` + - : Summaries contain no formatting. +- `plain-text` + - : Summaries contain markdown formatting (conforming to the [CommonMark](https://spec.commonmark.org/) spec). + +## Examples + +```js +const summarizer = await Summarizer.create({ + format: "plain-text", + // ... +}); + +// Logs "plain-text" +console.log(summarizer.format); +``` + +## Specifications + +{{Specifications}} + +## Browser compatibility + +{{Compat}} + +## See also + +- [Using the Summarizer API](/en-US/docs/Web/API/Summarizer_API/Using) +- [Web AI demos](https://chrome.dev/web-ai-demos/) on chrome.dev diff --git a/files/en-us/web/api/summarizer/index.md b/files/en-us/web/api/summarizer/index.md new file mode 100644 index 000000000000000..a6fbe4477ed3d03 --- /dev/null +++ b/files/en-us/web/api/summarizer/index.md @@ -0,0 +1,103 @@ +--- +title: Summarizer +slug: Web/API/Summarizer +page-type: web-api-interface +status: + - experimental +browser-compat: api.Summarizer +--- + +{{APIRef("Summarizer API")}}{{SeeCompatTable}} + +The **`Summarizer`** interface of the {{domxref("Summarizer API", "Summarizer API", "", "nocode")}} contains all the functionality for this API, including checking AI model availability, creating a new `Summarizer` instance, using it to generate a new summary, and more. + +{{InheritanceDiagram}} + +## Instance properties + +- {{domxref("Summarizer.expectedContextLanguages", "expectedContextLanguages")}} {{ReadOnlyInline}} {{Experimental_Inline}} + - : The languages the context strings should be written in. +- {{domxref("Summarizer.expectedInputLanguages", "expectedInputLanguages")}} {{ReadOnlyInline}} {{Experimental_Inline}} + - : The languages the `Summarizer` should support. +- {{domxref("Summarizer.format", "format")}} {{ReadOnlyInline}} {{Experimental_Inline}} + - : The text format summaries will be returned in. +- {{domxref("Summarizer.inputQuota", "inputQuota")}} {{ReadOnlyInline}} {{Experimental_Inline}} + - : The input quota available to the browser for generating summaries. +- {{domxref("Summarizer.length", "length")}} {{ReadOnlyInline}} {{Experimental_Inline}} + - : The relative length of the generated summaries. +- {{domxref("Summarizer.outputLanguage", "outputLanguage")}} {{ReadOnlyInline}} {{Experimental_Inline}} + - : The language the summary should be generated in. +- {{domxref("Summarizer.sharedContext", "sharedContext")}} {{ReadOnlyInline}} {{Experimental_Inline}} + - : A text string describing the context the pieces of text to summarize are being used in, which helps the `Summarizer` generate more suitable summaries. +- {{domxref("Summarizer.type", "type")}} {{ReadOnlyInline}} {{Experimental_Inline}} + - : The type of summary that will generated by the `Summarizer`. + +## Static methods + +- {{domxref("Summarizer.availability_static", "availability()")}} {{Experimental_Inline}} + - : Returns an enumerated value that indicates whether the browser AI model supports a given `Summarizer` configuration. +- {{domxref("Summarizer.create_static", "create()")}} {{Experimental_Inline}} + - : Creates a new `Summarizer` instance from which to generate summaries. + +## Instance methods + +- {{domxref("Summarizer.destroy", "destroy()")}} {{Experimental_Inline}} + - : Destroys the `Summarizer` instance it is called on. +- {{domxref("Summarizer.measureInputUsage", "measureInputUsage()")}} {{Experimental_Inline}} + - : Reports how much input quota would be used by a summarize operation for a given text input. +- {{domxref("Summarizer.summarize", "summarize()")}} {{Experimental_Inline}} + - : Generates a new summary string. +- {{domxref("Summarizer.summarizeStreaming", "summarizeStreaming()")}} {{Experimental_Inline}} + - : Generates a new summary as a {{domxref("ReadableStream")}}. + +## Examples + +See [Using the Summarizer API](/en-US/docs/Web/API/Summarizer_API/Using) for a complete example. + +### Creating a `Summarizer` instance + +```js +const summarizer = await Summarizer.create({ + sharedContext: + "A general summary to help a user decide if the text is worth reading", + type: "tldr", + length: "short", + format: "markdown", + expectedInputLanguages: ["en-US"], + outputLanguage: "en-US", +}); +``` + +### Generating a summary + +```js +const summary = await summarizer.summarize(myTextString); +console.log(summary); +``` + +### Generating a summary stream + +```js +const stream = summarizer.summarizeStreaming(myTextString); +let summary = ""; + +for await (const chunk of stream) { + summary += chunk; +} + +console.log("Stream complete"); +summaryOutput.textContent = summary; +``` + +## Specifications + +{{Specifications}} + +## Browser compatibility + +{{Compat}} + +## See also + +- [Using the Summarizer API](/en-US/docs/Web/API/Summarizer_API/Using) +- [Web AI demos](https://chrome.dev/web-ai-demos/) on chrome.dev diff --git a/files/en-us/web/api/summarizer/inputquota/index.md b/files/en-us/web/api/summarizer/inputquota/index.md new file mode 100644 index 000000000000000..7960e85b96a747f --- /dev/null +++ b/files/en-us/web/api/summarizer/inputquota/index.md @@ -0,0 +1,58 @@ +--- +title: "Summarizer: inputQuota property" +short-title: inputQuota +slug: Web/API/Summarizer/inputQuota +page-type: web-api-instance-property +status: + - experimental +browser-compat: api.Summarizer.inputQuota +--- + +{{APIRef("Summarizer API")}}{{SeeCompatTable}} + +The **`inputQuota`** read-only property of the {{domxref("Summarizer")}} interface returns the input quota available to the browser for generating summaries. + +## Value + +A number specifying the available input quota. This number is implementation-dependent. For example, it might be {{jsxref("infinity")}} if there are no limits beyond the user's memory and the maximum length of JavaScript strings, or it might be a number of tokens in the case of AI models that use a token/credits scheme. + +## Examples + +### Checking if you have sufficient quota + +In the below snippet, we create a new `Summarizer` instance using {{domxref("Summarizer.create_static", "create()")}}, then return the total input quota via `inputQuota` and the input quota usage for a summarizing a particular text string via {{domxref("Summarizer.measureInputUsage", "measureInputUsage()")}}. + +We then test to see if the individual input usage for that string is great than the total available quota. If so, we throw an appropriate error; it not, we commence summarizing the string using {{domxref("Summarizer.summarize", "summarize()")}}. + +```js +const summarizer = await Summarizer.create({ + sharedContext: + "A general summary to help a user decide if the text is worth reading", + type: "tldr", + length: "short", +}); + +const totalInputQuota = summarizer.inputQuota; +const inputUsage = await summarizer.measureInputUsage(myTextString); + +if (inputUsage > totalInputQuota) { + throw new Error("Boo, insufficient quota to generate a summary."); +} else { + console.log("Yay, quota available to generate a summary."); + const summary = await summarizer.summarize(myTextString); + // ... +} +``` + +## Specifications + +{{Specifications}} + +## Browser compatibility + +{{Compat}} + +## See also + +- [Using the Summarizer API](/en-US/docs/Web/API/Summarizer_API/Using) +- [Web AI demos](https://chrome.dev/web-ai-demos/) on chrome.dev diff --git a/files/en-us/web/api/summarizer/length/index.md b/files/en-us/web/api/summarizer/length/index.md new file mode 100644 index 000000000000000..c9d8b291885f425 --- /dev/null +++ b/files/en-us/web/api/summarizer/length/index.md @@ -0,0 +1,60 @@ +--- +title: "Summarizer: length property" +short-title: length +slug: Web/API/Summarizer/length +page-type: web-api-instance-property +status: + - experimental +browser-compat: api.Summarizer.length +--- + +{{APIRef("Summarizer API")}}{{SeeCompatTable}} + +The **`length`** read-only property of the {{domxref("Summarizer")}} interface returns the relative length of the generated summaries. + +## Value + +An enumerated value specifying the relative length of the generated summaries, the exact nature of which depends on the `Summarizer` {{domxref("Summarizer.type", "type")}} value. + +Possible values are: + +- `short` + - : A "short" summary + - For `type` `tldr` and `teaser`, the summary should fit into one sentence. + - For `type` `key-points`, the summary should be no more than three bullet points. + - For `type` `headline`, the summary should be no more than 12 words. +- `medium` + - : A "medium" summary + - For `type` `tldr` and `teaser`, the summary should fit into one short paragraph. + - For `type` `key-points`, the summary should be no more than five bullet points. + - For `type` `headline`, the summary should be no more than 17 words. +- `long` + - : A "long" summary + - For `type` `tldr` and `teaser`, the summary should fit into one paragraph. + - For `type` `key-points`, the summary should be no more than seven bullet points. + - For `type` `headline`, the summary should be no more than 22 words. + +## Examples + +```js +const summarizer = await Summarizer.create({ + length: "medium", + // ... +}); + +// Logs "medium" +console.log(summarizer.length); +``` + +## Specifications + +{{Specifications}} + +## Browser compatibility + +{{Compat}} + +## See also + +- [Using the Summarizer API](/en-US/docs/Web/API/Summarizer_API/Using) +- [Web AI demos](https://chrome.dev/web-ai-demos/) on chrome.dev. diff --git a/files/en-us/web/api/summarizer/measureinputusage/index.md b/files/en-us/web/api/summarizer/measureinputusage/index.md new file mode 100644 index 000000000000000..08dd5f49d8b0d53 --- /dev/null +++ b/files/en-us/web/api/summarizer/measureinputusage/index.md @@ -0,0 +1,87 @@ +--- +title: "Summarizer: measureInputUsage() method" +short-title: measureInputUsage() +slug: Web/API/Summarizer/measureInputUsage +page-type: web-api-instance-method +status: + - experimental +browser-compat: api.Summarizer.measureInputUsage +--- + +{{APIRef("Summarizer API")}}{{SeeCompatTable}} + +The **`measureInputUsage()`** method of the {{domxref("Summarizer")}} interface reports how much {{domxref("Summarizer.inputQuota", "inputQuota")}} would be used by a summarize operation for a given text input. + +## Syntax + +```js-nolint +measureInputUsage(input) +measureInputUsage(input, options) +``` + +### Parameters + +- `input` + - : A string representing the input text you want an input usage measurement for. +- `options` {{optional_inline}} + - : An object specifying configuration options for the `measureInputUsage()` operation. Possible values include: + - `context` + - : A string describing the context the input text would be used in, to help generate a more suitable summary. + - `signal` + - : An {{domxref("AbortSignal")}} object instance, which allows the `measureInputUsage()` operation to be aborted via the associated {{domxref("AbortController")}}. + +### Return value + +A {{jsxref("Promise")}} that fulfills with a number specifying the {{domxref("Summarizer.inputQuota", "inputQuota")}} usage of the given input text. + +### Exceptions + +- `NotAllowedError` {{domxref("DOMException")}} + - : Thrown if usage of the Summarizer API is blocked by a {{httpheader('Permissions-Policy/summarizer','summarizer')}} {{httpheader("Permissions-Policy")}}. +- `NotReadableError` {{domxref("DOMException")}} + - : Thrown if the output summary was filtered by the user agent, for example because it was detected to be harmful, inaccurate, or nonsensical. +- `NotSupportedError` {{domxref("DOMException")}} + - : Thrown if the provided `context` is not in language the `Summarizer` supports. +- `UnknownError` {{domxref("DOMException")}} + - : Thrown if the `measureInputUsage()` call failed for any other reason, or a reason the user agent did not wish to disclose. + +## Examples + +### Checking if you have sufficient quota + +In the below snippet, we create a new `Summarizer` instance using {{domxref("Summarizer.create_static", "create()")}}, then return the total input quota via {{domxref("Summarizer.inputQuota", "inputQuota")}} and the input quota usage for a summarizing a particular text string via `measureInputUsage()`. + +We then test to see if the individual input usage for that string is great than the total available quota. If so, we throw an appropriate error; it not, we commence summarizing the string using {{domxref("Summarizer.summarize", "summarize()")}}. + +```js +const summarizer = await Summarizer.create({ + sharedContext: + "A general summary to help a user decide if the text is worth reading", + type: "tldr", + length: "short", +}); + +const totalInputQuota = summarizer.inputQuota; +const inputUsage = await summarizer.measureInputUsage(myTextString); + +if (inputUsage > totalInputQuota) { + throw new Error("Boo, insufficient quota to generate a summary."); +} else { + console.log("Yay, quota available to generate a summary."); + const summary = await summarizer.summarize(myTextString); + // ... +} +``` + +## Specifications + +{{Specifications}} + +## Browser compatibility + +{{Compat}} + +## See also + +- [Using the Summarizer API](/en-US/docs/Web/API/Summarizer_API/Using) +- [Web AI demos](https://chrome.dev/web-ai-demos/) on chrome.dev diff --git a/files/en-us/web/api/summarizer/outputlanguage/index.md b/files/en-us/web/api/summarizer/outputlanguage/index.md new file mode 100644 index 000000000000000..66cdb4dc0eb757c --- /dev/null +++ b/files/en-us/web/api/summarizer/outputlanguage/index.md @@ -0,0 +1,44 @@ +--- +title: "Summarizer: outputLanguage property" +short-title: outputLanguage +slug: Web/API/Summarizer/outputLanguage +page-type: web-api-instance-property +status: + - experimental +browser-compat: api.Summarizer.outputLanguage +--- + +{{APIRef("Summarizer API")}}{{SeeCompatTable}} + +The **`outputLanguage`** read-only property of the {{domxref("Summarizer")}} interface returns the language the summary should be generated in. + +## Value + +A string specifying the language the summary should be generated in. + +The string should be a valid [BCP 47 language tag](https://en.wikipedia.org/wiki/IETF_language_tag#List_of_common_primary_language_subtags) (as specified in [RFC 5646](https://datatracker.ietf.org/doc/html/rfc5646)). + +## Examples + +```js +const summarizer = await Summarizer.create({ + outputLanguage: "en-US", + // ... +}); + +// Logs "en-US" +console.log(summarizer.outputLanguage); +``` + +## Specifications + +{{Specifications}} + +## Browser compatibility + +{{Compat}} + +## See also + +- [Using the Summarizer API](/en-US/docs/Web/API/Summarizer_API/Using) +- [Web AI demos](https://chrome.dev/web-ai-demos/) on chrome.dev diff --git a/files/en-us/web/api/summarizer/sharedcontext/index.md b/files/en-us/web/api/summarizer/sharedcontext/index.md new file mode 100644 index 000000000000000..911f92ce1b5bc60 --- /dev/null +++ b/files/en-us/web/api/summarizer/sharedcontext/index.md @@ -0,0 +1,43 @@ +--- +title: "Summarizer: sharedContext property" +short-title: sharedContext +slug: Web/API/Summarizer/sharedContext +page-type: web-api-instance-property +status: + - experimental +browser-compat: api.Summarizer.sharedContext +--- + +{{APIRef("Summarizer API")}}{{SeeCompatTable}} + +The **`sharedContext`** read-only property of the {{domxref("Summarizer")}} interface returns a string describing the context the pieces of text to summarize are being used in. This helps the `Summarizer` to generate more suitable summaries. + +## Value + +A string. + +## Examples + +```js +const summarizer = await Summarizer.create({ + sharedContext: + "A general summary to help a user decide if the text is worth reading", + // ... +}); + +// Logs "A general summary to help a user ..." +console.log(summarizer.sharedContext); +``` + +## Specifications + +{{Specifications}} + +## Browser compatibility + +{{Compat}} + +## See also + +- [Using the Summarizer API](/en-US/docs/Web/API/Summarizer_API/Using) +- [Web AI demos](https://chrome.dev/web-ai-demos/) on chrome.dev diff --git a/files/en-us/web/api/summarizer/summarize/index.md b/files/en-us/web/api/summarizer/summarize/index.md new file mode 100644 index 000000000000000..7eb5e77807273f1 --- /dev/null +++ b/files/en-us/web/api/summarizer/summarize/index.md @@ -0,0 +1,79 @@ +--- +title: "Summarizer: summarize() method" +short-title: summarize() +slug: Web/API/Summarizer/summarize +page-type: web-api-instance-method +status: + - experimental +browser-compat: api.Summarizer.summarize +--- + +{{APIRef("Summarizer API")}}{{SeeCompatTable}} + +The **`summarize()`** method of the {{domxref("Summarizer")}} interface generates a new summary string. + +## Syntax + +```js-nolint +summarize(input) +summarize(input, options) +``` + +### Parameters + +- `input` + - : A string representing the text to be summarized. +- `options` {{optional_inline}} + - : An object specifying configuration options for the `summarize()` operation. Possible values include: + - `context` + - : A string describing the context the input text is being used in, which helps the `Summarizer` generate a more suitable summary. + - `signal` + - : An {{domxref("AbortSignal")}} object instance, which allows the `summarize()` operation to be aborted via the associated {{domxref("AbortController")}}. + +### Return value + +A {{jsxref("Promise")}} that fulfills with a string containing the generated summary. + +### Exceptions + +- `InvalidStateError` {{domxref("DOMException")}} + - : Thrown if the current {{domxref("Document")}} is not active. +- `NotAllowedError` {{domxref("DOMException")}} + - : Thrown if usage of the Summarizer API is blocked by a {{httpheader('Permissions-Policy/summarizer','summarizer')}} {{httpheader("Permissions-Policy")}}. +- `NotReadableError` {{domxref("DOMException")}} + - : Thrown if the output summary was filtered by the user agent, for example because it was detected to be harmful, inaccurate, or nonsensical. +- `NotSupportedError` {{domxref("DOMException")}} + - : Thrown if the provided `context` is not in language the `Summarizer` supports. +- `QuotaExceededError` {{domxref("DOMException")}} + - : Thrown if the summarize operation exceeds the available {{domxref("Summarizer.inputQuota", "inputQuota")}}. +- `UnknownError` {{domxref("DOMException")}} + - : Thrown if the `summarize()` call failed for any other reason, or a reason the user agent did not wish to disclose. + +## Examples + +### Basic `summarize()` usage + +```js +const summarizer = await Summarizer.create({ + sharedContext: + "A general summary to help a user decide if the text is worth reading", + type: "tldr", + length: "short", +}); + +const summary = await summarizer.summarize(myTextString); +console.log(summary); +``` + +## Specifications + +{{Specifications}} + +## Browser compatibility + +{{Compat}} + +## See also + +- [Using the Summarizer API](/en-US/docs/Web/API/Summarizer_API/Using) +- [Web AI demos](https://chrome.dev/web-ai-demos/) on chrome.dev diff --git a/files/en-us/web/api/summarizer/summarizestreaming/index.md b/files/en-us/web/api/summarizer/summarizestreaming/index.md new file mode 100644 index 000000000000000..3986639f02fa65c --- /dev/null +++ b/files/en-us/web/api/summarizer/summarizestreaming/index.md @@ -0,0 +1,86 @@ +--- +title: "Summarizer: summarizeStreaming() method" +short-title: summarizeStreaming() +slug: Web/API/Summarizer/summarizeStreaming +page-type: web-api-instance-method +status: + - experimental +browser-compat: api.Summarizer.summarizeStreaming +--- + +{{APIRef("Summarizer API")}}{{SeeCompatTable}} + +The **`summarizeStreaming()`** method of the {{domxref("Summarizer")}} interface generates a new summary as a {{domxref("ReadableStream")}}. + +## Syntax + +```js-nolint +summarizeStreaming(input) +summarizeStreaming(input, options) +``` + +### Parameters + +- `input` + - : A string representing the text to be summarized. +- `options` {{optional_inline}} + - : An object specifying configuration options for the `summarizeStreaming()` operation. Possible values include: + - `context` + - : A string describing the context the input text is being used in, which helps the `Summarizer` generate a more suitable summary. + - `signal` + - : An {{domxref("AbortSignal")}} object instance, which allows the `summarizeStreaming()` operation to be aborted via the associated {{domxref("AbortController")}}. + +### Return value + +A {{domxref("ReadableStream")}} containing the generated summary. + +### Exceptions + +- `InvalidStateError` {{domxref("DOMException")}} + - : Thrown if the current {{domxref("Document")}} is not active. +- `NotAllowedError` {{domxref("DOMException")}} + - : Thrown if usage of the Summarizer API is blocked by a {{httpheader('Permissions-Policy/summarizer','summarizer')}} {{httpheader("Permissions-Policy")}}. +- `NotReadableError` {{domxref("DOMException")}} + - : Thrown if the output summary was filtered by the user agent, for example because it was detected to be harmful, inaccurate, or nonsensical. +- `NotSupportedError` {{domxref("DOMException")}} + - : Thrown if the provided `context` is not in language the `Summarizer` supports. +- `QuotaExceededError` {{domxref("DOMException")}} + - : Thrown if the summarize operation exceeds the available {{domxref("Summarizer.inputQuota", "inputQuota")}}. +- `UnknownError` {{domxref("DOMException")}} + - : Thrown if the `summarizeStreaming()` call failed for any other reason, or a reason the user agent did not wish to disclose. + +## Examples + +### Basic `summarizeStreaming()` usage + +```js +const summarizer = await Summarizer.create({ + sharedContext: + "A general summary to help a user decide if the text is worth reading", + type: "tldr", + length: "short", +}); + +const stream = summarizer.summarizeStreaming(myTextString); +let summary = ""; + +for await (const chunk of stream) { + summary += chunk; +} + +console.log("Stream complete"); +summaryOutput.textContent = summary; +``` + +## Specifications + +{{Specifications}} + +## Browser compatibility + +{{Compat}} + +## See also + +- [Using the Summarizer API](/en-US/docs/Web/API/Summarizer_API/Using) +- [Web AI demos](https://chrome.dev/web-ai-demos/) on chrome.dev diff --git a/files/en-us/web/api/summarizer/type/index.md b/files/en-us/web/api/summarizer/type/index.md new file mode 100644 index 000000000000000..c91cb54ed4f2253 --- /dev/null +++ b/files/en-us/web/api/summarizer/type/index.md @@ -0,0 +1,51 @@ +--- +title: "Summarizer: type property" +short-title: type +slug: Web/API/Summarizer/type +page-type: web-api-instance-property +status: + - experimental +browser-compat: api.Summarizer.type +--- + +{{APIRef("Summarizer API")}}{{SeeCompatTable}} + +The **`type`** read-only property of the {{domxref("Summarizer")}} interface returns the type of summary that will generated by the `Summarizer`. + +## Value + +An enumerated value specifying the form the summary will be generated in; possible values are: + +- `headline` + - : A single sentence article headline, capturing the main point of the input text. +- `key-points` + - : A bulleted list specifying the most important points presented in the input text. +- `teaser` + - : A "teaser" paragraph summarizing the most interesting or intriguing points of the input text, designed to draw the reader in to read more. +- `tldr` + - : A short, concise overview, designed as a summary for a busy reader. + +## Examples + +```js +const summarizer = await Summarizer.create({ + type: "tldr", + // ... +}); + +// Logs "tldr" +console.log(summarizer.type); +``` + +## Specifications + +{{Specifications}} + +## Browser compatibility + +{{Compat}} + +## See also + +- [Using the Summarizer API](/en-US/docs/Web/API/Summarizer_API/Using) +- [Web AI demos](https://chrome.dev/web-ai-demos/) on chrome.dev diff --git a/files/en-us/web/api/summarizer_api/index.md b/files/en-us/web/api/summarizer_api/index.md new file mode 100644 index 000000000000000..9c1150ce14aa3f3 --- /dev/null +++ b/files/en-us/web/api/summarizer_api/index.md @@ -0,0 +1,67 @@ +--- +title: Summarizer API +slug: Web/API/Summarizer_API +page-type: web-api-overview +status: + - experimental +browser-compat: api.Summarizer +spec-urls: https://webmachinelearning.github.io/writing-assistance-apis/#summarizer-api +--- + +{{SeeCompatTable}}{{DefaultAPISidebar("Summarizer API")}} + +The **Summarizer API** summarizes a given body of text via a browser's internal AI model (which may differ between browsers). + +## Concepts and usage + +Writing a summary of a larger body of text is a common writing task, and one that AI is well-suited to. Typical use cases include: + +- Providing a summary of a full article so the reader can judge whether to read the whole thing. +- Summarizing a meeting transcript so those joining the meeting late can get up to speed with what they've missed. +- Summarizing a set of product reviews to quickly communicate overall sentiment. + +The Summarizer API provides an asynchronous ({{jsxref("Promise")}}-based) mechanism for a website to feed a body of text into the browser's own internal AI model and request that it returns a summary of the text based on specified options. + +This is done using the functionality made available by the {{domxref("Summarizer")}} interface, in a two-step process: + +1. Create a `Summarizer` object instance using the {{domxref("Summarizer.create_static", "Summarizer.create()")}} static method, specifying options for what kind of summary you want written. Options include length, type (for example, "tldr" or key points), format (plain text or markdown), and input and output languages. + > [!NOTE] + > If you want to check whether the browser AI model is able to support your preferences, you can do so with the {{domxref("Summarizer.availability_static", "Summarizer.availability()")}} static method. +2. Run the {{domxref("Summarizer.summarize()")}} instance method to request the summary. + +After a `Summarizer` instance has been created, you can remove it again using the {{domxref("Summarizer.destroy()")}} instance method. You can also cancel a pending `create()` or `summarize()` operation using an {{domxref("AbortController")}}. + +See [Using the Summarizer API](/en-US/docs/Web/API/Summarizer_API/Using) for a walkthrough of how the API works. + +## Interfaces + +- {{domxref("Summarizer")}} {{Experimental_Inline}} + - : Contains all the functionality for the Summarizer API, including checking AI model availability, creating a new `Summarizer` instance, using it to generate a new summary, and more. + +## HTTP headers + +- {{httpheader("Permissions-Policy")}}; the {{httpheader('Permissions-Policy/summarizer','summarizer')}} directive + - : Controls access to the Summarizer API. Where a policy specifically disallows the use of the Summarizer API, any attempts to call the API's methods will fail with a `NotAllowedError` {{domxref("DOMException")}}. + +## Security considerations + +The specification requires that a user has recently interacted with the page when creating `Summarizer` objects ([transient user activation](/en-US/docs/Web/Security/User_activation) is required). + +In addition, the specification controls access to the API via {{httpheader('Permissions-Policy/summarizer','summarizer')}} {{httpheader("Permissions-Policy")}} directives. + +## Examples + +For a full example, see [Using the Summarizer API](/en-US/docs/Web/API/Summarizer_API/Using). + +## Specifications + +{{Specifications}} + +## Browser compatibility + +{{Compat}} + +## See also + +- [Summarize with built-in AI](https://developer.chrome.com/docs/ai/summarizer-api) on developer.chrome.com (2025) +- [Web AI demos](https://chrome.dev/web-ai-demos/) on chrome.dev diff --git a/files/en-us/web/api/summarizer_api/using/index.md b/files/en-us/web/api/summarizer_api/using/index.md new file mode 100644 index 000000000000000..d608521ebe87b5c --- /dev/null +++ b/files/en-us/web/api/summarizer_api/using/index.md @@ -0,0 +1,337 @@ +--- +title: Using the Summarizer API +slug: Web/API/Summarizer_API/Using +page-type: guide +--- + +{{DefaultAPISidebar("Summarizer API")}} + +The [Summarizer API](/en-US/docs/Web/API/Summarizer_API) provides an asynchronous ({{jsxref("Promise")}}-based) mechanism for a website to feed a body of text into the browser's own internal AI model and request that it returns a summary of the text based on specified options. This article explains how to use the fundamentals of the Summarizer API. + +## Creating a summarizer + +All of the Summarizer API's functionality is accessed through a single interface — {{domxref("Summarizer")}}. + +The first step in getting the browser AI model to output a summary is to create a `Summarizer` object instance. This is done using the {{domxref("Summarizer.create_static", "Summarizer.create()")}} static method, which takes an options object as an argument specifying options for what kind of summary you want written: + +```js +const summarizer = await Summarizer.create({ + sharedContext: + "A general summary to help a user decide if the text is worth reading", + type: "tldr", + length: "short", + format: "markdown", + expectedInputLanguages: ["en-US"], + outputLanguage: "en-US", +}); +``` + +The {{domxref("Summarizer.sharedContext", "sharedContext")}} option provides a string that helps the AI model write a more suitable summary for the context the text is being used in, while the {{domxref("Summarizer.type", "type")}} specifies what kind of summary you want to provide, like key bullet points or a "tldr" summary. + +We also specify the desired {{domxref("Summarizer.length", "length")}}, output {{domxref("Summarizer.format", "format")}}, {{domxref("Summarizer.expectedInputLanguages", "expectedInputLanguages")}}, and desired {{domxref("Summarizer.outputLanguage", "outputLanguage")}}. If the input and output languages are not specified, the language of the input text is auto-detected, and the output language will match the input language. + +If the browser's AI model does not support the specified input or output languages, an error is thrown. + +> [!NOTE] +> See the {{domxref("Summarizer.create_static", "create()")}} reference page for the full list of available options. + +## Checking configuration support + +Before creating a `Summarizer`, you can check whether your desired configuration is supported by the current browser using the {{domxref("Summarizer.availability_static", "Summarizer.availability()")}} static method. For example: + +```js +const availability = await Summarizer.availability({ + type: "tldr", + length: "short", + format: "markdown", + expectedInputLanguages: ["en-US"], + outputLanguage: "en-US", +}); +``` + +This method returns an enumerated value indicating whether support is, or will be available for the specified set of options: + +- `downloadable` means that the browser supports the requested options, but it first needs to download an AI model, or some fine-tuning data for the model. +- `downloading` means that the browser supports the requested options, but needs to finish an ongoing download before it can proceed. +- `available` means that the browser supports the given configuration without requiring any new downloads. +- `unavailable` means that the browser does not support the given configuration. + +If a download is required, it will be started automatically by the browser once a `Summarizer` instance is created using the `create()` method. You can track download progress automatically using a [monitor](#monitoring_download_progress). + +## Generating a summary + +When you've determined that your desired configuration works and you've created a `Summarizer` instance, you can use it to generate a summary by calling the {{domxref("Summarizer.summarize()")}} instance method on it, passing it the text to summarize as an argument. + +```js +const summary = await summarizer.summarize(myTextString); +console.log(summary); +``` + +It also optionally accepts an options object as a second argument that can accept a `context` string specific to this summary, and an abort {{domxref("AbortSignal", "signal")}} allowing the summary request to be aborted (see next section). + +There is a streaming version of the `summarize()` method available — {{domxref("Summarizer.summarizeStreaming()")}} — that allows you to return the summary as a {{domxref("ReadableStream")}}: + +```js +const stream = summarizer.summarizeStreaming(myTextString); +let summary = ""; + +for await (const chunk of stream) { + summary += chunk; +} + +console.log("Stream complete"); +summaryOutput.textContent = summary; +``` + +After a `Summarizer` instance has been created, you can remove it again using the {{domxref("Summarizer.destroy()")}} instance method. It makes sense to destroy `Summarizer` objects if they are no longer going to be used, as they tie up significant resources in their handling. + +## Cancelling summarize operations + +You can cancel a pending `create()`, `summarize()`, or `summarizeStreaming()` operation using an {{domxref("AbortController")}}: + +```js +const controller = new AbortController(); +const summary = await summarizer.summarize(myTextString, { + signal: controller.signal, +}); + +// ... + +controller.abort(); +``` + +## Monitoring download progress + +If the AI model for a particular summarizer is downloading (`availability()` returns `downloadable` and `downloading`), it is helpful to provide the user with feedback to tell them how long they need to wait before the operation completes. + +The `Summarizer.create()` method can accept a `monitor` property, the value of which is a callback function that takes a {{domxref("CreateMonitor")}} instance as an argument. `CreateMonitor` has a {{domxref("CreateMonitor/downloadprogress_event", "downloadprogress")}} event available, which fires when progress is made on downloading the AI model. +You can use this event to expose loading progress data: + +```js +const summarizer = await Summarizer.create({ + sharedContext: + "A general summary to help a user decide if the text is worth reading", + type: "tldr", + length: "short", + monitor(monitor) { + monitor.addEventListener("downloadprogress", (e) => { + console.log(`Downloaded ${Math.floor(e.loaded * 100)}%`); + }); + }, +}); +``` + +## Usage quotas + +Some implementations have an input quota that governs how many operations a website can request in a given period. The total quota can be accessed via the {{domxref("Summarizer.inputQuota")}} property, while the quota usage for a particular summary operation can be returned using the {{domxref("Summarizer.measureInputUsage()")}} method: + +For example, in the below snippet, we create a new `Summarizer` instance using {{domxref("Summarizer.create_static", "create()")}}, then return the total input quota via `inputQuota` and the input quota usage for a summarizing a particular text string via `measureInputUsage()`. + +We then test to see if the individual input usage for that string is great than the total available quota. If so, we throw an appropriate error; it not, we commence summarizing the string using {{domxref("Summarizer.summarize", "summarize()")}}. + +```js +const summarizer = await Summarizer.create({ + sharedContext: + "A general summary to help a user decide if the text is worth reading", + type: "tldr", + length: "short", +}); + +const totalInputQuota = summarizer.inputQuota; +const inputUsage = await summarizer.measureInputUsage(myTextString); + +if (inputUsage > totalInputQuota) { + throw new Error("Boo, insufficient quota to generate a summary."); +} else { + console.log("Yay, quota available to generate a summary."); + const summary = await summarizer.summarize(myTextString); + // ... +} +``` + +If you try to run a summarize operation that exceeds the available quota, a `QuotaExceededError` {{domxref("DOMException")}} will be thrown. + +## Complete example + +Let's look at a complete example that demonstrates the Summarizer API in action. + +### HTML + +In our markup, we first define an input {{htmlelement("form")}} that allows the user to set the text to summarize, and configuration options. This includes a {{htmlelement("textarea")}} for entering the text to be summarized, an {{htmlelement("output")}} element to display the character count of the text set by the user, and two {{htmlelement("select")}} elements for choosing a summarizer {{domxref("Summarizer.type", "type")}} and {{domxref("Summarizer.length", "length")}}. + +```html live-sample___summarizer-example +<h2>Input</h2> + +<form> + <div> + <label for="summary-text">Enter text to summarize:</label> + <textarea id="summary-text" name="summaryText" rows="6"></textarea> + <output class="input-count">Input character count: </output> + </div> + <div> + <label for="summary-type">Summary type:</label> + <select id="summary-type" name="summaryType"> + <option value="headline">Headline</option> + <option value="key-points">Key points</option> + <option value="teaser">Teaser</option> + <option value="tldr" selected>tldr</option> + </select> + </div> + <div> + <label for="summary-length">Summary length:</label> + <select id="summary-length" name="summaryLength"> + <option value="short" selected>Short</option> + <option value="medium">Medium</option> + <option value="long">Long</option> + </select> + </div> + <button type="submit">Submit</button> +</form> +``` + +The second half of our markup includes a {{htmlelement("p")}} element to display the generated summary, and a second {{htmlelement("output")}} element to display the summary character count. + +```html live-sample___summarizer-example +<h2>Summary output</h2> + +<p class="summary-output"></p> +<output class="output-count">Output summary character count: 0</output> +``` + +```css hidden live-sample___summarizer-example +* { + box-sizing: border-box; +} + +html { + font-family: Arial, Helvetica, sans-serif; +} + +body { + max-width: 600px; + margin: 0 auto; +} + +form div { + display: flex; + flex-direction: column; + gap: 10px; + margin-bottom: 20px; +} + +select, +textarea, +.summary-output { + padding: 5px; +} + +.summary-output { + min-height: 150px; + border: 1px solid black; + width: 100%; + display: block; +} + +.error { + color: red; +} +``` + +Note that we won't show the CSS for this example, as none of it is relevant to understanding the Summarizer API. + +### JavaScript + +In our script, we start off by grabbing references to the `<form>`, `<textarea>`, submit `<button>`, summary output `<p>`, and two `<output>` elements. + +```js live-sample___summarizer-example +const form = document.querySelector("form"); +const textarea = document.querySelector("textarea"); +const submitBtn = document.querySelector("button"); + +const summaryOutput = document.querySelector(".summary-output"); +const inputCount = document.querySelector(".input-count"); +const outputCount = document.querySelector(".output-count"); +``` + +Next, we use the {{domxref("EventTarget.addEventListener()")}} method to listen to two sets of events: + +- `submit` events on the `<form>` element; when the submit button is clicked, the `handleSubmission()` function is called. +- `input` events on the `<textarea>` element; when the current `<textarea>` value is changed, the `updateInputCount()` function is called. + +```js live-sample___summarizer-example +form.addEventListener("submit", handleSubmission); +textarea.addEventListener("input", updateInputCount); +``` + +The `updateInputCount()` function, defined next, sets the first `<output>` element's {{domxref("Node.textContent", "textContent")}} to a string containing the length of the `<textarea>` value. We also define a counterpart `displayOutputCount()` function that does the same thing for the second `<output>` element. This isn't called until near the end of the `handleSubmission()` function, after the summary has been returned. + +```js live-sample___summarizer-example +function updateInputCount() { + inputCount.textContent = `Input character count: ${textarea.value.length}`; +} + +function displayOutputCount() { + outputCount.textContent = `Output summary character count: ${summaryOutput.textContent.length}`; +} +``` + +Now we define the `handleSubmission()` function itself. After preventing the default form submission, we create a new {{domxref("FormData")}} object instance containing all our `<form>` data name/value pairs. We then run some data validation tests, checking whether the `<textarea>` content (`summaryText`) is empty or too short to waste cycles on, and printing an error message inside the summary output `<p>` if so. + +Provided the text passed the tests, we create a `Summarizer` object using the `create()` method, passing it a `sharedContext` string and the `type` (`summaryType`) and `length` (`summaryLength`) values selected in the form. We then set the output summary `<p>` and `<output>` to "pending" messages and disable the `<submit>` button while we run the `summarize()` operation. + +After the `summary` value is successfully returned, we set it as the output summary `<p>` element's `textContent`, call `displayOutputCount()` to display the output character count in the second `<output>` element, and reenable the submit `<button>`. + +```js live-sample___summarizer-example +async function handleSubmission(e) { + e.preventDefault(); + const formData = new FormData(form); + + if (formData.get("summaryText") === "") { + summaryOutput.innerHTML = `<span class="error">No text entered to summarize!</span>`; + return; + } else if (formData.get("summaryText").length < 100) { + summaryOutput.innerHTML = `<span class="error">I'm not trying to summarize something that short!</span>`; + return; + } + summaryOutput.innerHTML = ""; + + try { + const summarizer = await Summarizer.create({ + sharedContext: + "A general summary to help a user decide if the text is worth reading", + type: formData.get("summaryType"), + length: formData.get("summaryLength"), + }); + + summaryOutput.textContent = "...generating summary..."; + outputCount.textContent = "Output summary character count: -"; + submitBtn.disabled = true; + + const summary = await summarizer.summarize(formData.get("summaryText")); + + summaryOutput.textContent = summary; + displayOutputCount(); + submitBtn.disabled = false; + } catch (e) { + summaryOutput.innerHTML = `<span class="error">${e}</span>`; + } +} +``` + +The final step is to call the `updateInputCount()` function at the top level of the script, to ensure that the first `<output>` element containing the input count always displays the correct value on page load. + +```js live-sample___summarizer-example +updateInputCount(); +``` + +### Result + +The rendered example looks like this: + +{{EmbedLiveSample("summarizer-example", , "750px", , , , "summarizer", "allow-forms")}} + +Try entering a body of text into the "Input" `<textarea>` then pressing the submit button to generate an AI-generated summary. The text from your favorite Wikipedia page would be ideal. Try generating multiple summaries with different option combinations, to see how they affect the output. + +## See also + +- [Web AI demos](https://chrome.dev/web-ai-demos/) on chrome.dev diff --git a/files/en-us/web/api/svg_api/index.md b/files/en-us/web/api/svg_api/index.md index 230171cb2e36f85..2d9e7f26bcf49e8 100644 --- a/files/en-us/web/api/svg_api/index.md +++ b/files/en-us/web/api/svg_api/index.md @@ -29,7 +29,6 @@ The SVG API is a set of interfaces that have been categorized into the following - {{DOMxRef("SVGCircleElement")}} - {{DOMxRef("SVGClipPathElement")}} - {{DOMxRef("SVGComponentTransferFunctionElement")}} -- {{DOMxRef("SVGCursorElement")}} - {{DOMxRef("SVGDefsElement")}} - {{DOMxRef("SVGDescElement")}} - {{DOMxRef("SVGDiscardElement")}} @@ -128,7 +127,6 @@ Here are the DOM APIs for data types used in the definitions of SVG properties a ### SMIL-related interfaces -- {{DOMxRef("ElementTimeControl")}} - {{DOMxRef("TimeEvent")}} ### Other SVG interfaces diff --git a/files/en-us/web/api/svgaelement/target/index.md b/files/en-us/web/api/svgaelement/target/index.md index 9c8c770393995f0..07cb3dd7c881633 100644 --- a/files/en-us/web/api/svgaelement/target/index.md +++ b/files/en-us/web/api/svgaelement/target/index.md @@ -21,10 +21,10 @@ An {{domxref("SVGAnimatedString")}} indicating the ending resource target that o The code is taken from the ["SVGAElement example code"](/en-US/docs/Web/API/SVGAElement#example) ```js -// ... +// … const linkRef = document.querySelector("a"); linkRef.target = "_blank"; -// ... +// … ``` ## Specifications diff --git a/files/en-us/web/api/svgangle/index.md b/files/en-us/web/api/svgangle/index.md index 590445b955034ae..589de1dd1bb6a14 100644 --- a/files/en-us/web/api/svgangle/index.md +++ b/files/en-us/web/api/svgangle/index.md @@ -18,61 +18,36 @@ Every `SVGAngle` object operates in one of two modes: 1. **_Reflect the base value_** of a reflected animatable attribute (being exposed through the {{domxref("SVGAnimatedAngle.baseVal", "baseVal")}} member of an {{domxref("SVGAnimatedAngle")}}), 2. **_Be detached_,** which is the case for `SVGAngle` objects created with {{domxref("SVGSVGElement.createSVGAngle()")}}. -## Constants - -- `SVG_ANGLETYPE_UNKNOWN` - - : Some unknown type of value. Represented as the numeric value `0`. -- `SVG_ANGLETYPE_UNSPECIFIED` - - : A unitless {{cssxref("&lt;number&gt;")}} interpreted as a value in degrees. Represented as the numeric value `1`. -- `SVG_ANGLETYPE_DEG` - - : An {{cssxref("&lt;angle&gt;")}} with a `deg` unit. Represented as the numeric value `2`. -- `SVG_ANGLETYPE_RAD` - - : An {{cssxref("&lt;angle&gt;")}} with a `rad` unit. Represented as the numeric value `3`. -- `SVG_ANGLETYPE_GRAD` - - : An {{cssxref("&lt;angle&gt;")}} with a `grad` unit. Represented as the numeric value `4`. - ## Instance properties - {{domxref("SVGAngle.unitType")}} - - : The type of the value as specified by one of the `SVG_ANGLETYPE_*` constants defined on this interface. - - {{domxref("SVGAngle.value")}} - - : The value as a floating point value, in user units. Setting this attribute will cause `valueInSpecifiedUnits` and `valueAsString` to be updated automatically to reflect this setting. - - **Exceptions on setting:** A {{domxref("DOMException")}} with code `NO_MODIFICATION_ALLOWED_ERR` is raised when the length corresponds to a read-only attribute, or when the object itself is read-only. - - {{domxref("SVGAngle.valueInSpecifiedUnits")}} - - : The value as a floating point value, in the units expressed by `unitType`. Setting this attribute will cause `value` and `valueAsString` to be updated automatically to reflect this setting. - - **Exceptions on setting:** A {{domxref("DOMException")}} with code `NO_MODIFICATION_ALLOWED_ERR` is raised when the length corresponds to a read-only attribute, or when the object itself is read-only. - - {{domxref("SVGAngle.valueAsString")}} - - : The value as a string value, in the units expressed by `unitType`. Setting this attribute will cause `value`, `valueInSpecifiedUnits`, and `unitType` to be updated automatically to reflect this setting. - **Exceptions on setting:** - - A {{domxref("DOMException")}} with code `SYNTAX_ERR` is raised if the assigned string cannot be parsed as a valid {{cssxref("&lt;angle&gt;")}}. - - A {{domxref("DOMException")}} with code `NO_MODIFICATION_ALLOWED_ERR` is raised when the length corresponds to a read-only attribute, or when the object itself is read-only. - ## Instance methods -- {{domxref("SVGAngle.newValueSpecifiedUnits")}} - +- {{domxref("SVGAngle.convertToSpecifiedUnits()")}} + - : Preserve the same underlying stored value, but reset the stored unit identifier to the given `unitType`. Object attributes `unitType`, `valueInSpecifiedUnits`, and `valueAsString` might be modified as a result of this method. +- {{domxref("SVGAngle.newValueSpecifiedUnits()")}} - : Reset the value as a number with an associated unitType, thereby replacing the values for all of the attributes on the object. - **Exceptions:** - - - A {{domxref("DOMException")}} with code `NOT_SUPPORTED_ERR` is raised if `unitType` is `SVG_ANGLETYPE_UNKNOWN` or not a valid unit type constant (one of the other `SVG_ANGLETYPE_*` constants defined on this interface). - - A {{domxref("DOMException")}} with code `NO_MODIFICATION_ALLOWED_ERR` is raised when the length corresponds to a read only attribute or when the object itself is read only. - -- {{domxref("SVGAngle.convertToSpecifiedUnits")}} - - - : Preserve the same underlying stored value, but reset the stored unit identifier to the given `unitType`. Object attributes `unitType`, `valueInSpecifiedUnits`, and `valueAsString` might be modified as a result of this method. +## Static properties + +- `SVG_ANGLETYPE_UNKNOWN` (0) + - : Some unknown type of value. +- `SVG_ANGLETYPE_UNSPECIFIED` (1) + - : A unitless {{cssxref("&lt;number&gt;")}} interpreted as a value in degrees. +- `SVG_ANGLETYPE_DEG` (2) + - : An {{cssxref("&lt;angle&gt;")}} with a `deg` unit. +- `SVG_ANGLETYPE_RAD` (3) + - : An {{cssxref("&lt;angle&gt;")}} with a `rad` unit. +- `SVG_ANGLETYPE_GRAD` (4) + - : An {{cssxref("&lt;angle&gt;")}} with a `grad` unit. ## Specifications diff --git a/files/en-us/web/api/svgangle/unittype/index.md b/files/en-us/web/api/svgangle/unittype/index.md index 358056fc4209cbc..8eec946ca324051 100644 --- a/files/en-us/web/api/svgangle/unittype/index.md +++ b/files/en-us/web/api/svgangle/unittype/index.md @@ -8,7 +8,7 @@ browser-compat: api.SVGAngle.unitType {{APIRef("SVG")}} -The **`unitType`** property of the {{domxref("SVGAngle")}} interface is one of the [unit type constants](/en-US/docs/Web/API/SVGAngle#constants) and represents the units in which this angle's value is expressed. +The **`unitType`** property of the {{domxref("SVGAngle")}} interface is one of the [unit type constants](/en-US/docs/Web/API/SVGAngle#static_properties) and represents the units in which this angle's value is expressed. ## Value diff --git a/files/en-us/web/api/svgangle/value/index.md b/files/en-us/web/api/svgangle/value/index.md index 399d85feef03ac5..f5262831dd3c7eb 100644 --- a/files/en-us/web/api/svgangle/value/index.md +++ b/files/en-us/web/api/svgangle/value/index.md @@ -8,7 +8,7 @@ browser-compat: api.SVGAngle.value {{APIRef("SVG")}} -The `value` property of the {{domxref("SVGAngle")}} interface represents the floating point value of the [`<angle>`](/en-US/docs/Web/SVG/Content_type#angle) in degrees. +The `value` property of the {{domxref("SVGAngle")}} interface represents the floating point value of the [`<angle>`](/en-US/docs/Web/SVG/Guides/Content_type#angle) in degrees. Setting this attribute will cause {{domxref("SVGAngle.valueInSpecifiedUnits", "valueInSpecifiedUnits")}} and {{domxref("SVGAngle.valueAsString", "valueAsString")}} to be updated automatically to reflect this setting. diff --git a/files/en-us/web/api/svgangle/valueasstring/index.md b/files/en-us/web/api/svgangle/valueasstring/index.md index fb68e0405e95836..b9e4b126c0be131 100644 --- a/files/en-us/web/api/svgangle/valueasstring/index.md +++ b/files/en-us/web/api/svgangle/valueasstring/index.md @@ -46,5 +46,5 @@ console.log(Math.round(angle.value)); // Output: 90 (since 1.57 radians is appro ## See also -- [`<angle>`](/en-US/docs/Web/SVG/Content_type#angle) +- [`<angle>`](/en-US/docs/Web/SVG/Guides/Content_type#angle) - {{domxref("SVGAnimatedAngle")}} diff --git a/files/en-us/web/api/svganimatedangle/animval/index.md b/files/en-us/web/api/svganimatedangle/animval/index.md index 400f79ea4ecb608..72ec9cb1bcff949 100644 --- a/files/en-us/web/api/svganimatedangle/animval/index.md +++ b/files/en-us/web/api/svganimatedangle/animval/index.md @@ -8,13 +8,13 @@ browser-compat: api.SVGAnimatedAngle.animVal {{APIRef("SVG")}} -The **`animVal`** read-only property of the {{domxref("SVGAnimatedAngle")}} interface represents the current animated value of the associated [`<angle>`](/en-US/docs/Web/SVG/Content_type#angle) on an SVG element. If the attribute is not currently being animated, `animVal` will be the same as the `baseVal`. +The **`animVal`** read-only property of the {{domxref("SVGAnimatedAngle")}} interface represents the current animated value of the associated [`<angle>`](/en-US/docs/Web/SVG/Guides/Content_type#angle) on an SVG element. If the attribute is not currently being animated, `animVal` will be the same as the `baseVal`. This property reflects the animated state of the angle of the animating {{SVGattr("orient")}} attribute of the SVG {{SVGElement("marker")}} element, providing access to the value of the angle during animations. ## Value -An {{domxref("SVGAngle")}} object representing the animated value of the [`<angle>`](/en-US/docs/Web/SVG/Content_type#angle) content type. +An {{domxref("SVGAngle")}} object representing the animated value of the [`<angle>`](/en-US/docs/Web/SVG/Guides/Content_type#angle) content type. - If the angle is being animated, `animVal` will reflect the current animation state. - If the angle is not animated, `animVal` will be identical to {{domxref("SVGAnimatedAngle.baseVal")}}. @@ -45,4 +45,4 @@ console.log(animAngle.unitType); // Output: 2 (constant for SVG_ANGLETYPE_DEG) ## See also - {{domxref("SVGAnimatedAngle.baseVal")}} -- {{domxref("SVGAngle")}} and [angle `value` constants](/en-US/docs/Web/API/SVGAngle#constants) +- {{domxref("SVGAngle")}} and [angle `value` constants](/en-US/docs/Web/API/SVGAngle#static_properties) diff --git a/files/en-us/web/api/svganimatedangle/baseval/index.md b/files/en-us/web/api/svganimatedangle/baseval/index.md index 1c4134ddb43983a..88d16ec83b955a0 100644 --- a/files/en-us/web/api/svganimatedangle/baseval/index.md +++ b/files/en-us/web/api/svganimatedangle/baseval/index.md @@ -8,13 +8,13 @@ browser-compat: api.SVGAnimatedAngle.baseVal {{APIRef("SVG")}} -The **`baseVal`** read-only property of the {{domxref("SVGAnimatedAngle")}} interface represents the base (non-animated) value of the associated [`<angle>`](/en-US/docs/Web/SVG/Content_type#angle) on an SVG element. This property is used to retrieve the static value of the `<angle>`, unaffected by any ongoing animations. +The **`baseVal`** read-only property of the {{domxref("SVGAnimatedAngle")}} interface represents the base (non-animated) value of the associated [`<angle>`](/en-US/docs/Web/SVG/Guides/Content_type#angle) on an SVG element. This property is used to retrieve the static value of the `<angle>`, unaffected by any ongoing animations. This property reflects the `<angle>` value of the {{SVGattr("orient")}} attribute of the SVG {{SVGElement("marker")}} element, which is the same as the {{domxref("SVGMarkerElement.orientAngle")}} property. ## Value -An {{domxref("SVGAngle")}} object representing the base value of the [`<angle>`](/en-US/docs/Web/SVG/Content_type#angle) content type. +An {{domxref("SVGAngle")}} object representing the base value of the [`<angle>`](/en-US/docs/Web/SVG/Guides/Content_type#angle) content type. - The value is unaffected by animations, representing the initial state of the angle. - The unit type of the angle can be retrieved from {{domxref("SVGAngle.unitType")}}. @@ -43,4 +43,4 @@ console.log(baseAngle.unitType); // Output: 1 (constant for SVG_ANGLETYPE_UNSPEC ## See also - {{domxref("SVGAnimatedAngle.animVal")}} -- {{domxref("SVGAngle")}} and [angle `value` constants](/en-US/docs/Web/API/SVGAngle#constants) +- {{domxref("SVGAngle")}} and [angle `value` constants](/en-US/docs/Web/API/SVGAngle#static_properties) diff --git a/files/en-us/web/api/svganimatedangle/index.md b/files/en-us/web/api/svganimatedangle/index.md index 993def27c8c9777..2131272cf3a556e 100644 --- a/files/en-us/web/api/svganimatedangle/index.md +++ b/files/en-us/web/api/svganimatedangle/index.md @@ -7,83 +7,18 @@ browser-compat: api.SVGAnimatedAngle {{APIRef("SVG")}} -## SVG animated angle interface - -The `SVGAnimatedAngle` interface is used for attributes of basic type [\<angle>](/en-US/docs/Web/SVG/Content_type#angle) which can be animated. - -### Interface overview - -<table class="no-markdown"> - <tbody> - <tr> - <th scope="row">Also implement</th> - <td><em>None</em></td> - </tr> - <tr> - <th scope="row">Methods</th> - <td><em>None</em></td> - </tr> - <tr> - <th scope="row">Properties</th> - <td> - <ul> - <li> - readonly {{ domxref("SVGAngle") }} <code>baseVal</code> - </li> - <li> - readonly {{ domxref("SVGAngle") }} <code>animVal</code> - </li> - </ul> - </td> - </tr> - <tr> - <th scope="row">Normative document</th> - <td> - <a - href="https://www.w3.org/TR/SVG11/types.html#InterfaceSVGAnimatedAngle" - >SVG 1.1 (2nd Edition)</a - > - </td> - </tr> - </tbody> -</table> +The **`SVGAnimatedAngle`** interface is used for attributes of basic type [\<angle>](/en-US/docs/Web/SVG/Guides/Content_type#angle) which can be animated. ## Instance properties -<table class="no-markdown"> - <thead> - <tr> - <th>Name</th> - <th>Type</th> - <th>Description</th> - </tr> - </thead> - <tbody> - <tr> - <td><code>{{domxref("SVGAnimatedAngle.baseVal")}}</code></td> - <td>{{ domxref("SVGAngle") }}</td> - <td> - The base value of the given attribute before applying any animations. - </td> - </tr> - <tr> - <td><code>{{domxref("SVGAnimatedAngle.animVal")}}</code></td> - <td>{{ domxref("SVGAngle") }}</td> - <td> - A read only {{ domxref("SVGAngle") }} representing the current - animated value of the given attribute. If the given attribute is not - currently being animated, then the {{ domxref("SVGAngle") }} will - have the same contents as <code>baseVal</code>. The object referenced by - <code>animVal</code> will always be distinct from the one referenced by - <code>baseVal</code>, even when the attribute is not animated. - </td> - </tr> - </tbody> -</table> +- {{domxref("SVGAnimatedAngle.baseVal")}} {{ReadOnlyInline}} + - : An {{domxref("SVGAngle")}} representing the base value of the given attribute before applying any animations. +- {{domxref("SVGAnimatedAngle.animVal")}} {{ReadOnlyInline}} + - : A read only {{domxref("SVGAngle")}} representing the current animated value of the given attribute. If the given attribute is not currently being animated, then the {{domxref("SVGAngle")}} will have the same contents as `baseVal`. The object referenced by `animVal` will always be distinct from the one referenced by `baseVal`, even when the attribute is not animated. ## Instance methods -The `SVGAnimatedAngle` interface do not provide any specific methods. +_The `SVGAnimatedAngle` interface does not provide any specific methods._ ## Specifications diff --git a/files/en-us/web/api/svganimatedboolean/animval/index.md b/files/en-us/web/api/svganimatedboolean/animval/index.md index b965d2a9ee31a85..37100e64fbbce7f 100644 --- a/files/en-us/web/api/svganimatedboolean/animval/index.md +++ b/files/en-us/web/api/svganimatedboolean/animval/index.md @@ -10,7 +10,7 @@ browser-compat: api.SVGAnimatedBoolean.animVal The **`animVal`** read-only property of the {{domxref("SVGAnimatedBoolean")}} interface represents the current animated value of the associated animatable boolean SVG attribute. If the attribute is not animated, `animVal` is the same as {{domxref("SVGAnimatedBoolean.baseVal")}}. -Some boolean SVG attributes, such as [`preserveAlpha`](/en-US/docs/Web/SVG/Attribute/preserveAlpha), are animatable. In such cases, `SVGAnimatedBoolean.animVal` property is `true` when the attribute value resolves to true. Otherwise, the value is `false`. +Some boolean SVG attributes, such as [`preserveAlpha`](/en-US/docs/Web/SVG/Reference/Attribute/preserveAlpha), are animatable. In such cases, `SVGAnimatedBoolean.animVal` property is `true` when the attribute value resolves to true. Otherwise, the value is `false`. ## Value diff --git a/files/en-us/web/api/svganimatedboolean/baseval/index.md b/files/en-us/web/api/svganimatedboolean/baseval/index.md index 62311a29b6ba598..307ba3cb6c8731b 100644 --- a/files/en-us/web/api/svganimatedboolean/baseval/index.md +++ b/files/en-us/web/api/svganimatedboolean/baseval/index.md @@ -10,7 +10,7 @@ browser-compat: api.SVGAnimatedBoolean.baseVal The **`baseVal`** property of the {{domxref("SVGAnimatedBoolean")}} interface is the value of the associated animatable boolean SVG attribute in its base (none-animated) state. It reflects the value of the associated animatable boolean attribute when no animations are applied. -Some boolean SVG attributes, such as [`preserveAlpha`](/en-US/docs/Web/SVG/Attribute/preserveAlpha), are animatable. In such cases, `SVGAnimatedBoolean.baseVal` property is `false` when the attribute is set to `false`, is omitted and defaults to `false`, or is inheritable and inherits `false`. Otherwise, the value is `true`. +Some boolean SVG attributes, such as [`preserveAlpha`](/en-US/docs/Web/SVG/Reference/Attribute/preserveAlpha), are animatable. In such cases, `SVGAnimatedBoolean.baseVal` property is `false` when the attribute is set to `false`, is omitted and defaults to `false`, or is inheritable and inherits `false`. Otherwise, the value is `true`. ## Value diff --git a/files/en-us/web/api/svganimatedboolean/index.md b/files/en-us/web/api/svganimatedboolean/index.md index f14829c0546a673..11d5aab14c68ba7 100644 --- a/files/en-us/web/api/svganimatedboolean/index.md +++ b/files/en-us/web/api/svganimatedboolean/index.md @@ -7,77 +7,18 @@ browser-compat: api.SVGAnimatedBoolean {{APIRef("SVG")}} -## SVG animated boolean interface - -The `SVGAnimatedBoolean` interface is used for attributes of type boolean which can be animated. - -### Interface overview - -<table class="no-markdown"> - <tbody> - <tr> - <th scope="row">Also implement</th> - <td><em>None</em></td> - </tr> - <tr> - <th scope="row">Methods</th> - <td><em>None</em></td> - </tr> - <tr> - <th scope="row">Properties</th> - <td> - <ul> - <li>boolean <code>baseVal</code></li> - <li>readonly boolean <code>animVal</code></li> - </ul> - </td> - </tr> - <tr> - <th scope="row">Normative document</th> - <td> - <a - href="https://www.w3.org/TR/SVG11/types.html#InterfaceSVGAnimatedBoolean" - >SVG 1.1 (2nd Edition)</a - > - </td> - </tr> - </tbody> -</table> +The **`SVGAnimatedBoolean`** interface is used for attributes of type boolean which can be animated. ## Instance properties -<table class="no-markdown"> - <thead> - <tr> - <th>Name</th> - <th>Type</th> - <th>Description</th> - </tr> - </thead> - <tbody> - <tr> - <td><code>{{domxref("SVGAnimatedBoolean.baseVal")}}</code></td> - <td>boolean</td> - <td> - The base value of the given attribute before applying any animations. - </td> - </tr> - <tr> - <td><code>{{domxref("SVGAnimatedBoolean.animVal")}}</code></td> - <td>boolean</td> - <td> - If the given attribute or property is being animated, contains the - current animated value of the attribute or property. If the given - attribute or property is not currently being animated, contains the same - value as <code>baseVal</code>. - </td> - </tr> - </tbody> -</table> +- {{domxref("SVGAnimatedBoolean.baseVal")}} + - : A boolean representing the base value of the given attribute before applying any animations. +- {{domxref("SVGAnimatedBoolean.animVal")}} {{ReadOnlyInline}} + - : A boolean representing the current animated value of the given attribute. If the given attribute is not currently being animated, then it contains the same value as `baseVal`. ## Instance methods -The `SVGAnimatedBoolean` interface do not provide any specific methods. +_The `SVGAnimatedBoolean` interface does not provide any specific methods._ ## Specifications diff --git a/files/en-us/web/api/svganimatedinteger/animval/index.md b/files/en-us/web/api/svganimatedinteger/animval/index.md index ebfd184037d8b9a..e74111efc8ea5bd 100644 --- a/files/en-us/web/api/svganimatedinteger/animval/index.md +++ b/files/en-us/web/api/svganimatedinteger/animval/index.md @@ -8,7 +8,7 @@ browser-compat: api.SVGAnimatedInteger.animVal {{APIRef("SVG")}} -The **`animVal`** property of the {{domxref("SVGAnimatedInteger")}} interface represents the animated value of an [`<integer>`](/en-US/docs/Web/SVG/Content_type#integer). If no animation is applied, `animVal` equals `baseVal`. +The **`animVal`** property of the {{domxref("SVGAnimatedInteger")}} interface represents the animated value of an [`<integer>`](/en-US/docs/Web/SVG/Guides/Content_type#integer). If no animation is applied, `animVal` equals `baseVal`. Some attributes, like the {{SVGAttr("numOctaves")}} attribute of the {{SVGElement("feTurbulence")}} element or the {{SVGAttr("order")}} attribute of the {{SVGElement("feConvolveMatrix")}} accept a `long` integer as a value. This property provides access to the current animated state of the attribute as a number. @@ -41,6 +41,6 @@ console.log(animatedInteger.animVal); // Output: 4 (the current animated value) ## See also -- [`<integer>`](/en-US/docs/Web/SVG/Content_type#integer) +- [`<integer>`](/en-US/docs/Web/SVG/Guides/Content_type#integer) - {{SVGAttr("numOctaves")}} - {{SVGAttr("order")}} diff --git a/files/en-us/web/api/svganimatedinteger/baseval/index.md b/files/en-us/web/api/svganimatedinteger/baseval/index.md index c345cee24a00e0f..a698a3b8793d56e 100644 --- a/files/en-us/web/api/svganimatedinteger/baseval/index.md +++ b/files/en-us/web/api/svganimatedinteger/baseval/index.md @@ -8,7 +8,7 @@ browser-compat: api.SVGAnimatedInteger.baseVal {{APIRef("SVG")}} -The **`baseVal`** property of the {{domxref("SVGAnimatedInteger")}} interface represents the base (non-animated) value of an animatable [`<integer>`](/en-US/docs/Web/SVG/Content_type#integer). +The **`baseVal`** property of the {{domxref("SVGAnimatedInteger")}} interface represents the base (non-animated) value of an animatable [`<integer>`](/en-US/docs/Web/SVG/Guides/Content_type#integer). Some attributes, like the {{SVGAttr("numOctaves")}} attribute of the {{SVGElement("feTurbulence")}} element or the {{SVGAttr("order")}} attribute of the {{SVGElement("feConvolveMatrix")}} accept a `long` integer as a value. This property provides access to the static non-animated state of the attribute as a number. @@ -47,6 +47,6 @@ console.log(feTurbulence.getAttribute("numOctaves")); // Output: "6" ## See also -- [`<integer>`](/en-US/docs/Web/SVG/Content_type#integer) +- [`<integer>`](/en-US/docs/Web/SVG/Guides/Content_type#integer) - {{SVGAttr("numOctaves")}} - {{SVGAttr("order")}} diff --git a/files/en-us/web/api/svganimatedinteger/index.md b/files/en-us/web/api/svganimatedinteger/index.md index 4c8d7e99ad200cf..3906c89c44c0698 100644 --- a/files/en-us/web/api/svganimatedinteger/index.md +++ b/files/en-us/web/api/svganimatedinteger/index.md @@ -7,77 +7,18 @@ browser-compat: api.SVGAnimatedInteger {{APIRef("SVG")}} -## SVG animated integer interface - -The `SVGAnimatedInteger` interface is used for attributes of basic type [\<integer>](/en-US/docs/Web/SVG/Content_type#integer) which can be animated. - -### Interface overview - -<table class="no-markdown"> - <tbody> - <tr> - <th scope="row">Also implement</th> - <td><em>None</em></td> - </tr> - <tr> - <th scope="row">Methods</th> - <td><em>None</em></td> - </tr> - <tr> - <th scope="row">Properties</th> - <td> - <ul> - <li>long <code>baseVal</code></li> - <li>readonly long <code>animVal</code></li> - </ul> - </td> - </tr> - <tr> - <th scope="row">Normative document</th> - <td> - <a - href="https://www.w3.org/TR/SVG11/types.html#InterfaceSVGAnimatedInteger" - >SVG 1.1 (2nd Edition)</a - > - </td> - </tr> - </tbody> -</table> +The **`SVGAnimatedInteger`** interface is used for attributes of basic type [\<integer>](/en-US/docs/Web/SVG/Guides/Content_type#integer) which can be animated. ## Instance properties -<table class="no-markdown"> - <thead> - <tr> - <th>Name</th> - <th>Type</th> - <th>Description</th> - </tr> - </thead> - <tbody> - <tr> - <td><code>{{domxref("SVGAnimatedInteger.baseVal", "baseVal")}}</code></td> - <td>long</td> - <td> - The base value of the given attribute before applying any animations. - </td> - </tr> - <tr> - <td><code>{{domxref("SVGAnimatedInteger.animVal", "animVal")}}</code></td> - <td>long</td> - <td> - If the given attribute or property is being animated, contains the - current animated value of the attribute or property. If the given - attribute or property is not currently being animated, contains the same - value as <code>baseVal</code>. - </td> - </tr> - </tbody> -</table> +- {{domxref("SVGAnimatedInteger.baseVal", "baseVal")}} + - : An integer representing the base value of the given attribute before applying any animations. +- {{domxref("SVGAnimatedInteger.animVal", "animVal")}} {{ReadOnlyInline}} + - : An integer representing the current animated value of the given attribute. If the given attribute is not currently being animated, then it contains the same value as `baseVal`. ## Instance methods -The `SVGAnimatedInteger` interface do not provide any specific methods. +_The `SVGAnimatedInteger` interface does not provide any specific methods._ ## Specifications diff --git a/files/en-us/web/api/svganimatedlength/index.md b/files/en-us/web/api/svganimatedlength/index.md index 36ff0b73f7b0a61..971fe401f509870 100644 --- a/files/en-us/web/api/svganimatedlength/index.md +++ b/files/en-us/web/api/svganimatedlength/index.md @@ -7,7 +7,7 @@ browser-compat: api.SVGAnimatedLength {{APIRef("SVG")}} -The **`SVGAnimatedLength`** interface represents attributes of type [\<length>](/en-US/docs/Web/SVG/Content_type#length) which can be animated. +The **`SVGAnimatedLength`** interface represents attributes of type [\<length>](/en-US/docs/Web/SVG/Guides/Content_type#length) which can be animated. ## Instance properties diff --git a/files/en-us/web/api/svganimatedlengthlist/animval/index.md b/files/en-us/web/api/svganimatedlengthlist/animval/index.md index c830eec523a87e7..72ec5b321e9b7e7 100644 --- a/files/en-us/web/api/svganimatedlengthlist/animval/index.md +++ b/files/en-us/web/api/svganimatedlengthlist/animval/index.md @@ -8,9 +8,9 @@ browser-compat: api.SVGAnimatedLengthList.animVal {{APIRef("SVG")}} -The **`animVal`** read-only property of the {{domxref("SVGAnimatedLengthList")}} interface represents the animated value of an attribute that accepts a list of [`<length>`](/en-US/docs/Web/SVG/Content_type#length), [`<percentage>`](/en-US/docs/Web/SVG/Content_type#percentage), or [`<number>`](/en-US/docs/Web/SVG/Content_type#number) values. +The **`animVal`** read-only property of the {{domxref("SVGAnimatedLengthList")}} interface represents the animated value of an attribute that accepts a list of [`<length>`](/en-US/docs/Web/SVG/Guides/Content_type#length), [`<percentage>`](/en-US/docs/Web/SVG/Guides/Content_type#percentage), or [`<number>`](/en-US/docs/Web/SVG/Guides/Content_type#number) values. -Some SVG attributes, like the `x`, `y`, `dx`, and `dy` attributes of the [`<tspan>`](/en-US/docs/Web/SVG/Element/tspan) and [`<text>`](/en-US/docs/Web/SVG/Element/text) elements, accept a list of length, percentages, or numbers as a value. This property provides access to the current animated state of the attribute as a live {{domxref("SVGLengthList")}} object. +Some SVG attributes, like the `x`, `y`, `dx`, and `dy` attributes of the [`<tspan>`](/en-US/docs/Web/SVG/Reference/Element/tspan) and [`<text>`](/en-US/docs/Web/SVG/Reference/Element/text) elements, accept a list of length, percentages, or numbers as a value. This property provides access to the current animated state of the attribute as a live {{domxref("SVGLengthList")}} object. ## Value @@ -26,7 +26,7 @@ An {{domxref("SVGLengthList")}} object representing the animated value of the at ## See also -- [`<length>`](/en-US/docs/Web/SVG/Content_type#length) -- [`<percentage>`](/en-US/docs/Web/SVG/Content_type#percentage) -- [`<number>`](/en-US/docs/Web/SVG/Content_type#number) +- [`<length>`](/en-US/docs/Web/SVG/Guides/Content_type#length) +- [`<percentage>`](/en-US/docs/Web/SVG/Guides/Content_type#percentage) +- [`<number>`](/en-US/docs/Web/SVG/Guides/Content_type#number) - {{domxref("SVGLengthList")}} diff --git a/files/en-us/web/api/svganimatedlengthlist/baseval/index.md b/files/en-us/web/api/svganimatedlengthlist/baseval/index.md index 77deb67013436e3..a3e4a8d51be8294 100644 --- a/files/en-us/web/api/svganimatedlengthlist/baseval/index.md +++ b/files/en-us/web/api/svganimatedlengthlist/baseval/index.md @@ -8,9 +8,9 @@ browser-compat: api.SVGAnimatedLengthList.baseVal {{APIRef("SVG")}} -The **`baseVal`** read-only property of the {{domxref("SVGAnimatedLengthList")}} interface represents the base (non-animated) value of an animatable attribute that accepts a list of [`<length>`](/en-US/docs/Web/SVG/Content_type#length), [`<percentage>`](/en-US/docs/Web/SVG/Content_type#percentage), or [`<number>`](/en-US/docs/Web/SVG/Content_type#number) values. +The **`baseVal`** read-only property of the {{domxref("SVGAnimatedLengthList")}} interface represents the base (non-animated) value of an animatable attribute that accepts a list of [`<length>`](/en-US/docs/Web/SVG/Guides/Content_type#length), [`<percentage>`](/en-US/docs/Web/SVG/Guides/Content_type#percentage), or [`<number>`](/en-US/docs/Web/SVG/Guides/Content_type#number) values. -Some SVG attributes, like the `x`, `y`, `dx`, and `dy` attributes of the [`<tspan>`](/en-US/docs/Web/SVG/Element/tspan) and [`<text>`](/en-US/docs/Web/SVG/Element/text) elements, accept a list of length, percentages, or numbers as a value. This property reflects the attribute value, in its non-animated state, as a live {{domxref("SVGLengthList")}} object. +Some SVG attributes, like the `x`, `y`, `dx`, and `dy` attributes of the [`<tspan>`](/en-US/docs/Web/SVG/Reference/Element/tspan) and [`<text>`](/en-US/docs/Web/SVG/Reference/Element/text) elements, accept a list of length, percentages, or numbers as a value. This property reflects the attribute value, in its non-animated state, as a live {{domxref("SVGLengthList")}} object. ## Value @@ -26,7 +26,7 @@ An {{domxref("SVGLengthList")}} object representing the base value of the attrib ## See also -- [`<length>`](/en-US/docs/Web/SVG/Content_type#length) -- [`<percentage>`](/en-US/docs/Web/SVG/Content_type#percentage) -- [`<number>`](/en-US/docs/Web/SVG/Content_type#number) +- [`<length>`](/en-US/docs/Web/SVG/Guides/Content_type#length) +- [`<percentage>`](/en-US/docs/Web/SVG/Guides/Content_type#percentage) +- [`<number>`](/en-US/docs/Web/SVG/Guides/Content_type#number) - {{domxref("SVGLengthList")}} diff --git a/files/en-us/web/api/svganimatedlengthlist/index.md b/files/en-us/web/api/svganimatedlengthlist/index.md index 95554d4f9a7088d..d3ccd84c0ab7b5c 100644 --- a/files/en-us/web/api/svganimatedlengthlist/index.md +++ b/files/en-us/web/api/svganimatedlengthlist/index.md @@ -7,86 +7,18 @@ browser-compat: api.SVGAnimatedLengthList {{APIRef("SVG")}} -## SVG animated length list interface - -The `SVGAnimatedLengthList` interface is used for attributes of type {{ domxref("SVGLengthList") }} which can be animated. - -### Interface overview - -<table class="no-markdown"> - <tbody> - <tr> - <th scope="row">Also implement</th> - <td><em>None</em></td> - </tr> - <tr> - <th scope="row">Methods</th> - <td><em>None</em></td> - </tr> - <tr> - <th scope="row">Properties</th> - <td> - <ul> - <li> - readonly {{ domxref("SVGLengthList") }} - <code>baseVal</code> - </li> - <li> - readonly {{ domxref("SVGLengthList") }} - <code>animVal</code> - </li> - </ul> - </td> - </tr> - <tr> - <th scope="row">Normative document</th> - <td> - <a - href="https://www.w3.org/TR/SVG11/types.html#InterfaceSVGAnimatedLengthList" - >SVG 1.1 (2nd Edition)</a - > - </td> - </tr> - </tbody> -</table> +The **`SVGAnimatedLengthList`** interface is used for attributes of type {{domxref("SVGLengthList")}} which can be animated. ## Instance properties -<table class="no-markdown"> - <thead> - <tr> - <th>Name</th> - <th>Type</th> - <th>Description</th> - </tr> - </thead> - <tbody> - <tr> - <td><code>{{domxref("SVGAnimatedLengthList.baseVal", "baseVal")}}</code></td> - <td>{{ domxref("SVGLengthList") }}</td> - <td> - The base value of the given attribute before applying any animations. - </td> - </tr> - <tr> - <td><code>{{domxref("SVGAnimatedLengthList.animVal", "animVal")}}</code></td> - <td>{{ domxref("SVGLengthList") }}</td> - <td> - A read only {{ domxref("SVGLengthList") }} representing the - current animated value of the given attribute. If the given attribute is - not currently being animated, then the - {{ domxref("SVGLengthList") }} will have the same contents as - <code>baseVal</code>. The object referenced by <code>animVal</code> will - always be distinct from the one referenced by <code>baseVal</code>, even - when the attribute is not animated. - </td> - </tr> - </tbody> -</table> +- {{domxref("SVGAnimatedLengthList.baseVal")}} {{ReadOnlyInline}} + - : An {{domxref("SVGLengthList")}} that represents the base value of the given attribute before applying any animations. +- {{domxref("SVGAnimatedLengthList.animVal")}} {{ReadOnlyInline}} + - : A read only {{domxref("SVGLengthList")}} that represents the current animated value of the given attribute. If the given attribute is not currently being animated, then the {{domxref("SVGLengthList")}} will have the same contents as `baseVal`. The object referenced by `animVal` will always be distinct from the one referenced by `baseVal`, even when the attribute is not animated. ## Instance methods -The `SVGAnimatedLengthList` interface do not provide any specific methods. +_The `SVGAnimatedLengthList` interface does not provide any specific methods._ ## Specifications diff --git a/files/en-us/web/api/svganimatednumber/animval/index.md b/files/en-us/web/api/svganimatednumber/animval/index.md index 127b8297f1e40f7..5704a5e0f9be27b 100644 --- a/files/en-us/web/api/svganimatednumber/animval/index.md +++ b/files/en-us/web/api/svganimatednumber/animval/index.md @@ -18,7 +18,7 @@ A `number`; the current value of the animated attribute as a float. ## Examples -This example includes a {{SVGElement("path")}} element with a nested {{SVGElement("animate")}} element that animates the value of the path's {{SVGElement("pathLength")}} attribute: +This example includes a {{SVGElement("path")}} element with a nested {{SVGElement("animate")}} element that animates the value of the path's {{SVGAttr("pathLength")}} attribute: ```html <path d="M 0,40 h100" pathLength="90" id="path"> diff --git a/files/en-us/web/api/svganimatednumber/baseval/index.md b/files/en-us/web/api/svganimatednumber/baseval/index.md index a9dc08d928ef5ea..0c0860053726bf0 100644 --- a/files/en-us/web/api/svganimatednumber/baseval/index.md +++ b/files/en-us/web/api/svganimatednumber/baseval/index.md @@ -18,7 +18,7 @@ A `number`; the base value of the attribute as a float. ## Examples -This example includes a {{SVGElement("path")}} element with a nested {{SVGElement("animate")}} element that animates the value of the path's {{SVGElement("pathLength")}} attribute: +This example includes a {{SVGElement("path")}} element with a nested {{SVGElement("animate")}} element that animates the value of the path's {{SVGAttr("pathLength")}} attribute: ```html <path d="M 0,40 h100" pathLength="90" id="path"> diff --git a/files/en-us/web/api/svganimatednumber/index.md b/files/en-us/web/api/svganimatednumber/index.md index 19dc62ec93ac1ae..aacfff98c8694db 100644 --- a/files/en-us/web/api/svganimatednumber/index.md +++ b/files/en-us/web/api/svganimatednumber/index.md @@ -7,73 +7,14 @@ browser-compat: api.SVGAnimatedNumber {{APIRef("SVG")}} -## SVG animated number interface - -The `SVGAnimatedNumber` interface is used for attributes of basic type [\<Number>](/en-US/docs/Web/SVG/Content_type#number) which can be animated. - -### Interface overview - -<table class="no-markdown"> - <tbody> - <tr> - <th scope="row">Also implement</th> - <td><em>None</em></td> - </tr> - <tr> - <th scope="row">Methods</th> - <td><em>None</em></td> - </tr> - <tr> - <th scope="row">Properties</th> - <td> - <ul> - <li>float <code>baseVal</code></li> - <li>readonly float <code>animVal</code></li> - </ul> - </td> - </tr> - <tr> - <th scope="row">Normative document</th> - <td> - <a - href="https://www.w3.org/TR/SVG11/types.html#InterfaceSVGAnimatedNumber" - >SVG 1.1 (2nd Edition)</a - > - </td> - </tr> - </tbody> -</table> +The **`SVGAnimatedNumber`** interface represents attributes of type [\<number>](/en-US/docs/Web/SVG/Guides/Content_type#number) which can be animated. ## Instance properties -<table class="no-markdown"> - <thead> - <tr> - <th>Name</th> - <th>Type</th> - <th>Description</th> - </tr> - </thead> - <tbody> - <tr> - <td><code>{{domxref("SVGAnimatedNumber.baseVal")}}</code></td> - <td>float</td> - <td> - The base value of the given attribute before applying any animations. - </td> - </tr> - <tr> - <td><code>{{domxref("SVGAnimatedNumber.animVal")}}</code></td> - <td>float</td> - <td> - If the given attribute or property is being animated, contains the - current animated value of the attribute or property. If the given - attribute or property is not currently being animated, contains the same - value as <code>baseVal</code>. - </td> - </tr> - </tbody> -</table> +- {{domxref("SVGAnimatedNumber.baseVal", "baseVal")}} + - : An `SVGAnimatedNumber` representing the base value as a floating point value of the given attribute before applying any animations. +- {{domxref("SVGAnimatedNumber.animVal", "animVal")}} {{ReadOnlyInline}} + - : If the given attribute or property is being animated, an `SVGAnimatedNumber` containing the current animated value of the attribute or property. If the given attribute or property is not currently being animated, an `SVGAnimatedNumber` containing the same value as `baseVal`. ## Instance methods diff --git a/files/en-us/web/api/svganimatednumberlist/animval/index.md b/files/en-us/web/api/svganimatednumberlist/animval/index.md index 560d436d6e27caf..f3d7ba267c9b00d 100644 --- a/files/en-us/web/api/svganimatednumberlist/animval/index.md +++ b/files/en-us/web/api/svganimatednumberlist/animval/index.md @@ -8,9 +8,9 @@ browser-compat: api.SVGAnimatedNumberList.animVal {{APIRef("SVG")}} -The **`animVal`** read-only property of the {{domxref("SVGAnimatedNumberList")}} interface represents the current animated value of an animatable attribute that accepts a list of [`<number>`](/en-US/docs/Web/SVG/Content_type#number) values. +The **`animVal`** read-only property of the {{domxref("SVGAnimatedNumberList")}} interface represents the current animated value of an animatable attribute that accepts a list of [`<number>`](/en-US/docs/Web/SVG/Guides/Content_type#number) values. -This property reflects the [`viewBox`](/en-US/docs/Web/SVG/Attribute/viewBox) attribute of the [`<svg>`](/en-US/docs/Web/SVG/Element/svg) element, the [`values`](/en-US/docs/Web/SVG/Attribute/values#fecolormatrix) attribute of the [`feColorMatrix`](/en-US/docs/Web/SVG/Element/feColorMatrix) element and the {{SVGAttr("points")}} attribute of the {{SVGElement("rect")}}, {{SVGElement("polygon")}}, or {{SVGElement("polyline")}} element as a readonly {{domxref("SVGNumberList")}}, providing access to a dynamically updated list of points defined by the {{SVGAttr("points")}} attribute. +This property reflects the [`viewBox`](/en-US/docs/Web/SVG/Reference/Attribute/viewBox) attribute of the [`<svg>`](/en-US/docs/Web/SVG/Reference/Element/svg) element, the [`values`](/en-US/docs/Web/SVG/Reference/Attribute/values#fecolormatrix) attribute of the [`feColorMatrix`](/en-US/docs/Web/SVG/Reference/Element/feColorMatrix) element and the {{SVGAttr("points")}} attribute of the {{SVGElement("rect")}}, {{SVGElement("polygon")}}, or {{SVGElement("polyline")}} element as a readonly {{domxref("SVGNumberList")}}, providing access to a dynamically updated list of points defined by the {{SVGAttr("points")}} attribute. ## Value diff --git a/files/en-us/web/api/svganimatednumberlist/baseval/index.md b/files/en-us/web/api/svganimatednumberlist/baseval/index.md index c9eea8843b7fa25..4ce793f2c369cf3 100644 --- a/files/en-us/web/api/svganimatednumberlist/baseval/index.md +++ b/files/en-us/web/api/svganimatednumberlist/baseval/index.md @@ -8,9 +8,9 @@ browser-compat: api.SVGAnimatedNumberList.baseVal {{APIRef("SVG")}} -The **`baseVal`** read-only property of the {{domxref("SVGAnimatedNumberList")}} interface represents the base (non-animated) value of an animatable attribute that accepts a list of [`<number>`](/en-US/docs/Web/SVG/Content_type#number) values. +The **`baseVal`** read-only property of the {{domxref("SVGAnimatedNumberList")}} interface represents the base (non-animated) value of an animatable attribute that accepts a list of [`<number>`](/en-US/docs/Web/SVG/Guides/Content_type#number) values. -This property reflects the [`viewBox`](/en-US/docs/Web/SVG/Attribute/viewBox) attribute of the [`<svg>`](/en-US/docs/Web/SVG/Element/svg) element, the [`values`](/en-US/docs/Web/SVG/Attribute/values#fecolormatrix) attribute of the [`feColorMatrix`](/en-US/docs/Web/SVG/Element/feColorMatrix) element and the {{SVGAttr("points")}} attribute of the {{SVGElement("rect")}}, {{SVGElement("polygon")}}, or {{SVGElement("polyline")}} element as a readonly {{domxref("SVGNumberList")}}, providing access to a static list of points defined by the {{SVGAttr("points")}} attribute. +This property reflects the [`viewBox`](/en-US/docs/Web/SVG/Reference/Attribute/viewBox) attribute of the [`<svg>`](/en-US/docs/Web/SVG/Reference/Element/svg) element, the [`values`](/en-US/docs/Web/SVG/Reference/Attribute/values#fecolormatrix) attribute of the [`feColorMatrix`](/en-US/docs/Web/SVG/Reference/Element/feColorMatrix) element and the {{SVGAttr("points")}} attribute of the {{SVGElement("rect")}}, {{SVGElement("polygon")}}, or {{SVGElement("polyline")}} element as a readonly {{domxref("SVGNumberList")}}, providing access to a static list of points defined by the {{SVGAttr("points")}} attribute. ## Value diff --git a/files/en-us/web/api/svganimatednumberlist/index.md b/files/en-us/web/api/svganimatednumberlist/index.md index b57808f61309cab..21b96593d8b1629 100644 --- a/files/en-us/web/api/svganimatednumberlist/index.md +++ b/files/en-us/web/api/svganimatednumberlist/index.md @@ -7,48 +7,7 @@ browser-compat: api.SVGAnimatedNumberList {{APIRef("SVG")}} -## SVG animated number list interface - -The `SVGAnimatedNumber` interface is used for attributes which take a list of numbers and which can be animated. - -### Interface overview - -<table class="standard-table"> - <tbody> - <tr> - <th scope="row">Also implement</th> - <td><em>None</em></td> - </tr> - <tr> - <th scope="row">Methods</th> - <td><em>None</em></td> - </tr> - <tr> - <th scope="row">Properties</th> - <td> - <ul> - <li> - readonly {{ domxref("SVGNumberList") }} - <code>baseVal</code> - </li> - <li> - readonly {{ domxref("SVGNumberList") }} - <code>animVal</code> - </li> - </ul> - </td> - </tr> - <tr> - <th scope="row">Normative document</th> - <td> - <a - href="https://www.w3.org/TR/SVG11/types.html#InterfaceSVGAnimatedAngle" - >SVG 1.1 (2nd Edition)</a - > - </td> - </tr> - </tbody> -</table> +The **`SVGAnimatedNumberList`** interface represents a list of attributes of type [\<number>](/en-US/docs/Web/SVG/Guides/Content_type#number) which can be animated. ## Instance properties diff --git a/files/en-us/web/api/svganimatedpreserveaspectratio/index.md b/files/en-us/web/api/svganimatedpreserveaspectratio/index.md index fde2e1cf3868098..2f2771f97725db9 100644 --- a/files/en-us/web/api/svganimatedpreserveaspectratio/index.md +++ b/files/en-us/web/api/svganimatedpreserveaspectratio/index.md @@ -7,42 +7,7 @@ browser-compat: api.SVGAnimatedPreserveAspectRatio {{APIRef("SVG")}} -## SVG animated preserveAspectRatio interface - -The `SVGAnimatedPreserveAspectRatio` interface is used for attributes of type {{ domxref("SVGPreserveAspectRatio") }} which can be animated. - -### Interface overview - -<table class="standard-table"> - <tbody> - <tr> - <th scope="row">Also implement</th> - <td><em>None</em></td> - </tr> - <tr> - <th scope="row">Methods</th> - <td><em>None</em></td> - </tr> - <tr> - <th scope="row">Properties</th> - <td> - <ul> - <li>readonly float <code>baseVal</code></li> - <li>readonly float <code>animVal</code></li> - </ul> - </td> - </tr> - <tr> - <th scope="row">Normative document</th> - <td> - <a - href="https://www.w3.org/TR/SVG11/coords.html#InterfaceSVGAnimatedPreserveAspectRatio" - >SVG 1.1 (2nd Edition)</a - > - </td> - </tr> - </tbody> -</table> +The **`SVGAnimatedPreserveAspectRatio`** interface represents attributes of type {{ domxref("SVGPreserveAspectRatio") }} which can be animated. ## Instance properties diff --git a/files/en-us/web/api/svganimatedrect/animval/index.md b/files/en-us/web/api/svganimatedrect/animval/index.md index 3d437969d2cf0b3..2affe7c624c0397 100644 --- a/files/en-us/web/api/svganimatedrect/animval/index.md +++ b/files/en-us/web/api/svganimatedrect/animval/index.md @@ -25,15 +25,14 @@ A {{domxref("DOMRectReadOnly")}} object representing the animated value of the ` ``` ```js - const svgElement = document.getElementById("mySvg"); - const animatedRect = svgElement.viewBox.animVal; - - // Log the animated value (assuming an animation is applied) - console.log(animatedRect.x); - console.log(animatedRect.y); - console.log(animatedRect.width); - console.log(animatedRect.height); -</script> +const svgElement = document.getElementById("mySvg"); +const animatedRect = svgElement.viewBox.animVal; + +// Log the animated value (assuming an animation is applied) +console.log(animatedRect.x); +console.log(animatedRect.y); +console.log(animatedRect.width); +console.log(animatedRect.height); ``` ## Specifications diff --git a/files/en-us/web/api/svganimatedrect/index.md b/files/en-us/web/api/svganimatedrect/index.md index 82e62ff27455177..8ba4721054819f5 100644 --- a/files/en-us/web/api/svganimatedrect/index.md +++ b/files/en-us/web/api/svganimatedrect/index.md @@ -7,81 +7,18 @@ browser-compat: api.SVGAnimatedRect {{APIRef("SVG")}} -The `SVGAnimatedRect` interface is used for attributes of basic {{ domxref("SVGRect") }} which can be animated. - -### Interface overview - -<table class="no-markdown"> - <tbody> - <tr> - <th scope="row">Also implement</th> - <td><em>None</em></td> - </tr> - <tr> - <th scope="row">Methods</th> - <td><em>None</em></td> - </tr> - <tr> - <th scope="row">Properties</th> - <td> - <ul> - <li> - readonly {{ domxref("SVGRect") }} <code>baseVal</code> - </li> - <li> - readonly {{ domxref("SVGRect") }} <code>animVal</code> - </li> - </ul> - </td> - </tr> - <tr> - <th scope="row">Normative document</th> - <td> - <a - href="https://www.w3.org/TR/SVG11/types.html#InterfaceSVGAnimatedRect" - >SVG 1.1 (2nd Edition)</a - > - </td> - </tr> - </tbody> -</table> +The **`SVGAnimatedRect`** interface represents an {{domxref("SVGRect")}} attribute that can be animated. ## Instance properties -<table class="no-markdown"> - <thead> - <tr> - <th>Name</th> - <th>Type</th> - <th>Description</th> - </tr> - </thead> - <tbody> - <tr> - <td><code>{{domxref("SVGAnimatedRect.baseVal")}}</code></td> - <td>{{ domxref("SVGRect") }}</td> - <td> - The base value of the given attribute before applying any animations. - </td> - </tr> - <tr> - <td><code>{{domxref("SVGAnimatedRect.animVal")}}</code></td> - <td>{{ domxref("SVGRect") }}</td> - <td> - A read only {{ domxref("SVGRect") }} representing the current - animated value of the given attribute. If the given attribute is not - currently being animated, then the {{ domxref("SVGRect") }} will - have the same contents as <code>baseVal</code>. The object referenced by - <code>animVal</code> will always be distinct from the one referenced by - <code>baseVal</code>, even when the attribute is not animated. - </td> - </tr> - </tbody> -</table> +- {{domxref("SVGAnimatedRect.baseVal", "baseVal")}} + - : The base value of the given attribute before applying any animations. +- {{domxref("SVGAnimatedRect.animVal", "animVal")}} {{ReadOnlyInline}} + - : The current animated value of the given attribute as a read-only {{domxref("SVGRect")}}. If the given attribute is not currently being animated, then the {{domxref("SVGRect")}} will have the same contents as `baseVal`. The object referenced by `animVal` will always be distinct from the one referenced by `baseVal`, even when the attribute is not animated. ## Instance methods -_The `SVGAnimatedRect` interface do not provide any specific methods._ +_The `SVGAnimatedRect` interface does not provide any specific methods._ ## Specifications diff --git a/files/en-us/web/api/svganimatedtransformlist/index.md b/files/en-us/web/api/svganimatedtransformlist/index.md index 3013ea71da7c348..ce133cafd726d01 100644 --- a/files/en-us/web/api/svganimatedtransformlist/index.md +++ b/files/en-us/web/api/svganimatedtransformlist/index.md @@ -7,86 +7,18 @@ browser-compat: api.SVGAnimatedTransformList {{APIRef("SVG")}} -## SVG animated transform list interface - -The `SVGAnimatedTransformList` interface is used for attributes which take a list of numbers and which can be animated. - -### Interface overview - -<table class="no-markdown"> - <tbody> - <tr> - <th scope="row">Also implement</th> - <td><em>None</em></td> - </tr> - <tr> - <th scope="row">Methods</th> - <td><em>None</em></td> - </tr> - <tr> - <th scope="row">Properties</th> - <td> - <ul> - <li> - readonly {{ domxref("SVGTransformList") }} - <code>baseVal</code> - </li> - <li> - readonly {{ domxref("SVGTransformList") }} - <code>animVal</code> - </li> - </ul> - </td> - </tr> - <tr> - <th scope="row">Normative document</th> - <td> - <a - href="https://www.w3.org/TR/SVG/coords.html#InterfaceSVGAnimatedTransformList" - >SVG 1.1 (2nd Edition)</a - > - </td> - </tr> - </tbody> -</table> +The **`SVGAnimatedTransformList`** interface represents attributes which take a list of numbers and which can be animated. ## Instance properties -<table class="no-markdown"> - <thead> - <tr> - <th>Name</th> - <th>Type</th> - <th>Description</th> - </tr> - </thead> - <tbody> - <tr> - <td><code>{{domxref("SVGAnimatedTransformList.baseVal", "baseVal")}}</code></td> - <td>{{ domxref("SVGTransformList") }}</td> - <td> - The base value of the given attribute before applying any animations. - </td> - </tr> - <tr> - <td><code>{{domxref("SVGAnimatedTransformList.animVal", "animVal")}}</code></td> - <td>{{ domxref("SVGTransformList") }}</td> - <td> - A read only {{ domxref("SVGTransformList") }} representing - the current animated value of the given attribute. If the given - attribute is not currently being animated, then the - {{ domxref("SVGTransformList") }} will have the same contents - as <code>baseVal</code>. The object referenced by - <code>animVal</code> will always be distinct from the one referenced by - <code>baseVal</code>, even when the attribute is not animated. - </td> - </tr> - </tbody> -</table> +- {{domxref("SVGAnimatedTransformList.baseVal", "baseVal")}} {{ReadOnlyInline}} + - : The base value of the given attribute before applying any animations. +- {{domxref("SVGAnimatedTransformList.animVal", "animVal")}} {{ReadOnlyInline}} + - : The current animated value of the given attribute as read only {{domxref("SVGTransformList")}}. If the given attribute is not currently being animated, then the {{domxref("SVGTransformList")}} will have the same contents as `baseVal`. The object referenced by `animVal` will always be distinct from the one referenced by `baseVal`, even when the attribute is not animated. ## Instance methods -The `SVGAnimatedTransformList` interface doesn't provide any specific methods. +_The `SVGAnimatedTransformList` interface doesn't provide any specific methods._ ## Specifications diff --git a/files/en-us/web/api/svganimationelement/beginevent_event/index.md b/files/en-us/web/api/svganimationelement/beginevent_event/index.md index 8876a9942ead1fa..c6742f378d87672 100644 --- a/files/en-us/web/api/svganimationelement/beginevent_event/index.md +++ b/files/en-us/web/api/svganimationelement/beginevent_event/index.md @@ -10,7 +10,7 @@ browser-compat: api.SVGAnimationElement.beginEvent_event The **`beginEvent`** event of the {{domxref("SVGAnimationElement")}} interface is fired when the element local timeline begins to play. It will be raised each time the element begins the active duration (i.e., when it restarts, but not when it repeats). -It may be raised both in the course of normal (i.e. scheduled or interactive) timeline play, as well as in the case that the element was begun with a DOM method. +It may be raised both in the course of normal (i.e., scheduled or interactive) timeline play, as well as in the case that the element was begun with a DOM method. This event is not cancelable and does not bubble. @@ -18,10 +18,10 @@ This event is not cancelable and does not bubble. Use the event name in methods like {{domxref("EventTarget.addEventListener", "addEventListener()")}}, or set an event handler property. -```js -addEventListener("beginEvent", (event) => {}); +```js-nolint +addEventListener("beginEvent", (event) => { }) -onbegin = (event) => {}; +onbegin = (event) => { } ``` ## Event type @@ -107,6 +107,6 @@ animateElem.onbegin = () => { ## See also -- [SVG animation with SMIL](/en-US/docs/Web/SVG/SVG_animation_with_SMIL) +- [SVG animation with SMIL](/en-US/docs/Web/SVG/Guides/SVG_animation_with_SMIL) - {{domxref("SVGAnimationElement.endEvent_event", "endEvent")}} event - {{domxref("SVGAnimationElement.repeatEvent_event", "repeatEvent")}} event diff --git a/files/en-us/web/api/svganimationelement/endevent_event/index.md b/files/en-us/web/api/svganimationelement/endevent_event/index.md index ea9edfc8661df64..2c03f93baf1a815 100644 --- a/files/en-us/web/api/svganimationelement/endevent_event/index.md +++ b/files/en-us/web/api/svganimationelement/endevent_event/index.md @@ -11,7 +11,7 @@ browser-compat: api.SVGAnimationElement.endEvent_event The **`endEvent`** event of the {{domxref("SVGAnimationElement")}} interface is fired when at the active end of the animation is reached. > [!NOTE] -> This event is not raised at the simple end of each animation repeat. This event may be raised both in the course of normal (i.e. scheduled or interactive) timeline play, as well as in the case that the element was ended with a DOM method. +> This event is not raised at the simple end of each animation repeat. This event may be raised both in the course of normal (i.e., scheduled or interactive) timeline play, as well as in the case that the element was ended with a DOM method. This event is not cancelable and does not bubble. @@ -19,10 +19,10 @@ This event is not cancelable and does not bubble. Use the event name in methods like {{domxref("EventTarget.addEventListener", "addEventListener()")}}, or set an event handler property. -```js -addEventListener("endEvent", (event) => {}); +```js-nolint +addEventListener("endEvent", (event) => { }) -onend = (event) => {}; +onend = (event) => { } ``` ## Event type @@ -122,6 +122,6 @@ animateElem.onend = () => { ## See also -- [SVG animation with SMIL](/en-US/docs/Web/SVG/SVG_animation_with_SMIL) +- [SVG animation with SMIL](/en-US/docs/Web/SVG/Guides/SVG_animation_with_SMIL) - {{domxref("SVGAnimationElement.beginEvent_event", "beginEvent")}} event - {{domxref("SVGAnimationElement.repeatEvent_event", "repeatEvent")}} event diff --git a/files/en-us/web/api/svganimationelement/repeatevent_event/index.md b/files/en-us/web/api/svganimationelement/repeatevent_event/index.md index 00322eee0c4af4d..0dd35046a546a2e 100644 --- a/files/en-us/web/api/svganimationelement/repeatevent_event/index.md +++ b/files/en-us/web/api/svganimationelement/repeatevent_event/index.md @@ -19,10 +19,10 @@ This event is not cancelable and does not bubble. Use the event name in methods like {{domxref("EventTarget.addEventListener", "addEventListener()")}}, or set an event handler property. -```js -addEventListener("repeatEvent", (event) => {}); +```js-nolint +addEventListener("repeatEvent", (event) => { }) -onrepeat = (event) => {}; +onrepeat = (event) => { } ``` ## Event type @@ -108,6 +108,6 @@ animateElem.onrepeat = () => { ## See also -- [SVG animation with SMIL](/en-US/docs/Web/SVG/SVG_animation_with_SMIL) +- [SVG animation with SMIL](/en-US/docs/Web/SVG/Guides/SVG_animation_with_SMIL) - {{domxref("SVGAnimationElement.beginEvent_event", "beginEvent")}} event - {{domxref("SVGAnimationElement.endEvent_event", "endEvent")}} event diff --git a/files/en-us/web/api/svgclippathelement/index.md b/files/en-us/web/api/svgclippathelement/index.md index 430c763cc307f45..626647321a90ea5 100644 --- a/files/en-us/web/api/svgclippathelement/index.md +++ b/files/en-us/web/api/svgclippathelement/index.md @@ -35,3 +35,4 @@ _This interface doesn't implement any specific methods, but inherits methods fro ## See also - {{SVGElement("clipPath")}} +- [Introduction to CSS clipping](/en-US/docs/Web/CSS/CSS_masking/Clipping) diff --git a/files/en-us/web/api/svgcomponenttransferfunctionelement/index.md b/files/en-us/web/api/svgcomponenttransferfunctionelement/index.md index cac8e1eff42bfc8..ef2a7f75ed047e4 100644 --- a/files/en-us/web/api/svgcomponenttransferfunctionelement/index.md +++ b/files/en-us/web/api/svgcomponenttransferfunctionelement/index.md @@ -7,56 +7,10 @@ browser-compat: api.SVGComponentTransferFunctionElement {{APIRef("SVG")}} -The **`SVGComponentTransferFunctionElement`** interface defines a base interface used by the component transfer function interfaces. +The **`SVGComponentTransferFunctionElement`** interface represents a base interface used by the component transfer function interfaces. {{InheritanceDiagram}} -## Constants - -<table class="no-markdown"> - <tbody> - <tr> - <th>Name</th> - <th>Value</th> - <th>Description</th> - </tr> - <tr> - <td><code>SVG_FECOMPONENTTRANSFER_TYPE_UNKNOWN</code></td> - <td>0</td> - <td> - The type is not one of predefined types. It is invalid to attempt to - define a new value of this type or to attempt to switch an existing - value to this type. - </td> - </tr> - <tr> - <td><code>SVG_FECOMPONENTTRANSFER_TYPE_IDENTITY</code></td> - <td>1</td> - <td>Corresponds to the value <code>identity</code>.</td> - </tr> - <tr> - <td><code>SVG_FECOMPONENTTRANSFER_TYPE_TABLE</code></td> - <td>2</td> - <td>Corresponds to the value <code>table</code>.</td> - </tr> - <tr> - <td><code>SVG_FECOMPONENTTRANSFER_TYPE_DISCRETE</code></td> - <td>3</td> - <td>Corresponds to the value <code>discrete</code>.</td> - </tr> - <tr> - <td><code>SVG_FECOMPONENTTRANSFER_TYPE_LINEAR</code></td> - <td>4</td> - <td>Corresponds to the value <code>linear</code>.</td> - </tr> - <tr> - <td><code>SVG_FECOMPONENTTRANSFER_TYPE_GAMMA</code></td> - <td>5</td> - <td>Corresponds to the value <code>gamma</code>.</td> - </tr> - </tbody> -</table> - ## Instance properties _This interface also inherits properties from its parent interface, {{domxref("SVGElement")}}._ @@ -80,6 +34,21 @@ _This interface also inherits properties from its parent interface, {{domxref("S _This interface does not provide any specific methods, but implements those of its parent, {{domxref("SVGElement")}}._ +## Static properties + +- `SVG_FECOMPONENTTRANSFER_TYPE_UNKNOWN` (0) + - : The type is not one of predefined types. It is invalid to attempt to define a new value of this type or to attempt to switch an existing value to this type. +- `SVG_FECOMPONENTTRANSFER_TYPE_IDENTITY` (1) + - : Corresponds to the value `identity`. +- `SVG_FECOMPONENTTRANSFER_TYPE_TABLE` (2) + - : Corresponds to the value `table`. +- `SVG_FECOMPONENTTRANSFER_TYPE_DISCRETE` (3) + - : Corresponds to the value `discrete`. +- `SVG_FECOMPONENTTRANSFER_TYPE_LINEAR` (4) + - : Corresponds to the value `linear`. +- `SVG_FECOMPONENTTRANSFER_TYPE_GAMMA` (5) + - : Corresponds to the value `gamma`. + ## Specifications {{Specifications}} diff --git a/files/en-us/web/api/svgcomponenttransferfunctionelement/type/index.md b/files/en-us/web/api/svgcomponenttransferfunctionelement/type/index.md index 1b948de6afad577..4438d8ab49be8da 100644 --- a/files/en-us/web/api/svgcomponenttransferfunctionelement/type/index.md +++ b/files/en-us/web/api/svgcomponenttransferfunctionelement/type/index.md @@ -8,7 +8,7 @@ browser-compat: api.SVGComponentTransferFunctionElement.type {{APIRef("SVG")}} -The **`type`** read-only property of the {{domxref("SVGComponentTransferFunctionElement")}} interface reflects the {{SVGAttr("type")}} attribute of the given element. It takes one of the [`SVG_FECOMPONENTTRANSFER_TYPE_*`](/en-US/docs/Web/API/SVGComponentTransferFunctionElement#constants) constants defined on this interface. +The **`type`** read-only property of the {{domxref("SVGComponentTransferFunctionElement")}} interface reflects the {{SVGAttr("type")}} attribute of the given element. It takes one of the [`SVG_FECOMPONENTTRANSFER_TYPE_*`](/en-US/docs/Web/API/SVGComponentTransferFunctionElement#static_properties) constants defined on this interface. ## Value diff --git a/files/en-us/web/api/svgcursorelement/index.md b/files/en-us/web/api/svgcursorelement/index.md deleted file mode 100644 index f6789feaf40bb29..000000000000000 --- a/files/en-us/web/api/svgcursorelement/index.md +++ /dev/null @@ -1,39 +0,0 @@ ---- -title: SVGCursorElement -slug: Web/API/SVGCursorElement -page-type: web-api-interface -status: - - deprecated -browser-compat: api.SVGCursorElement ---- - -{{APIRef("SVG")}}{{Deprecated_Header}} - -The **`SVGCursorElement`** interface provides access to the properties of {{ SVGElement("cursor") }} elements, as well as methods to manipulate them. - -{{InheritanceDiagram}} - -## Instance properties - -_This interface also inherits properties from its parent, {{domxref("SVGElement")}}._ - -- {{domxref("SVGCursorElement.x")}} {{ReadOnlyInline}} - - : An {{domxref("SVGAnimatedLength")}} corresponding to the {{SVGAttr("x")}} attribute of the given {{SVGElement("cursor")}} element. -- {{domxref("SVGCursorElement.y")}} {{ReadOnlyInline}} - - : An {{domxref("SVGAnimatedLength")}} corresponding to the {{SVGAttr("y")}} attribute of the given {{SVGElement("cursor")}} element. - -## Instance methods - -_This interface doesn't implement any specific methods, but inherits methods from its parent, {{domxref("SVGElement")}}._ - -## Specifications - -{{Specifications}} - -## Browser compatibility - -{{Compat}} - -## See also - -- {{SVGElement("cursor")}} diff --git a/files/en-us/web/api/svgdiscardelement/index.md b/files/en-us/web/api/svgdiscardelement/index.md index 55e9f8557e1eb54..2c41c8e969134e3 100644 --- a/files/en-us/web/api/svgdiscardelement/index.md +++ b/files/en-us/web/api/svgdiscardelement/index.md @@ -3,15 +3,16 @@ title: SVGDiscardElement slug: Web/API/SVGDiscardElement page-type: web-api-interface status: + - deprecated - experimental browser-compat: api.SVGDiscardElement --- -{{APIRef("SVG")}}{{SeeCompatTable}} +{{APIRef("SVG")}}{{deprecated_header}}{{SeeCompatTable}} -The **`SVGDiscardElement`** interface is an interface for the {{SVGElement("discard")}} element. +The **`SVGDiscardElement`** interface is an interface for the deprecated `<discard>` element. -Note that it does not provide access to the specific attributes of the {{SVGElement("discard")}} element (`begin` and `href`). +Note that it does not provide access to the specific attributes of the `<discard>` element (`begin` and `href`). {{InheritanceDiagram}} @@ -30,7 +31,3 @@ _Inherits methods from its parent interface, {{domxref("SVGAnimationElement")}}. ## Browser compatibility {{Compat}} - -## See also - -- {{SVGElement("discard")}} SVG element diff --git a/files/en-us/web/api/svgelement/autofocus/index.md b/files/en-us/web/api/svgelement/autofocus/index.md new file mode 100644 index 000000000000000..999d895d30ba1ec --- /dev/null +++ b/files/en-us/web/api/svgelement/autofocus/index.md @@ -0,0 +1,29 @@ +--- +title: "SVGElement: autofocus property" +short-title: autofocus +slug: Web/API/SVGElement/autofocus +page-type: web-api-instance-property +browser-compat: api.SVGElement.autofocus +--- + +{{APIRef("SVG")}} + +The **`autofocus`** property of the {{domxref("SVGElement")}} interface contains a boolean value reflecting the [`autofocus`](/en-US/docs/Web/HTML/Reference/Global_attributes/autofocus) HTML global attribute. It indicates whether the SVG element should be focused when the page loads or when the element becomes shown if the SVG element is inside a {{htmlelement("dialog")}} or a [popover](/en-US/docs/Web/HTML/Reference/Global_attributes/popover). + +## Value + +A boolean value. + +## Specifications + +{{Specifications}} + +## Browser compatibility + +{{Compat}} + +## See also + +- {{domxref("SVGElement.focus")}} +- {{domxref("HTMLElement.autofocus")}} +- [Popover API](/en-US/docs/Web/API/Popover_API) diff --git a/files/en-us/web/api/svgelement/dataset/index.md b/files/en-us/web/api/svgelement/dataset/index.md index 5234f32a7003f3a..df022ada0b40033 100644 --- a/files/en-us/web/api/svgelement/dataset/index.md +++ b/files/en-us/web/api/svgelement/dataset/index.md @@ -8,7 +8,7 @@ browser-compat: api.SVGElement.dataset {{APIRef("SVG")}} -The **`dataset`** read-only property of the {{DOMxRef("SVGElement")}} interface provides read/write access to [custom data attributes](/en-US/docs/Web/SVG/Attribute/data-*) (`data-*`) on elements. It exposes a map of strings ({{domxref("DOMStringMap")}}) with an entry for each `data-*` attribute. +The **`dataset`** read-only property of the {{DOMxRef("SVGElement")}} interface provides read/write access to [custom data attributes](/en-US/docs/Web/SVG/Reference/Attribute/data-*) (`data-*`) on elements. It exposes a map of strings ({{domxref("DOMStringMap")}}) with an entry for each `data-*` attribute. For more information on the behavior of `dataset`, see {{domxref("HTMLElement.dataset")}}. @@ -44,5 +44,5 @@ console.log(el.dataset.id); // "1234567890" ## See also -- [`data-*`](/en-US/docs/Web/SVG/Attribute/data-*) SVG attributes -- [Using data attributes](/en-US/docs/Learn_web_development/Howto/Solve_HTML_problems/Use_data_attributes) +- [`data-*`](/en-US/docs/Web/SVG/Reference/Attribute/data-*) SVG attributes +- [Using data attributes](/en-US/docs/Web/HTML/How_to/Use_data_attributes) diff --git a/files/en-us/web/api/svgelement/error_event/index.md b/files/en-us/web/api/svgelement/error_event/index.md index e1d9345d3f40f95..6a4ba76b5e7a620 100644 --- a/files/en-us/web/api/svgelement/error_event/index.md +++ b/files/en-us/web/api/svgelement/error_event/index.md @@ -18,10 +18,10 @@ This event is not cancelable. Use the event name in methods like {{domxref("EventTarget.addEventListener", "addEventListener()")}}, or set an event handler property. -```js -addEventListener("error", (event) => {}); +```js-nolint +addEventListener("error", (event) => { }) -onerror = (event) => {}; +onerror = (event) => { } ``` ## Event type diff --git a/files/en-us/web/api/svgelement/index.md b/files/en-us/web/api/svgelement/index.md index 245371a9d80c80c..2da06bcf4b36453 100644 --- a/files/en-us/web/api/svgelement/index.md +++ b/files/en-us/web/api/svgelement/index.md @@ -17,14 +17,12 @@ _Also inherits properties from the {{DOMxRef("Element")}} interface._ - {{DOMxRef("SVGElement.attributeStyleMap")}} {{ReadOnlyInline}} - : A {{DOMxRef("StylePropertyMap")}} representing the declarations of the element's {{SVGAttr("style")}} attribute. -- {{DOMxRef("SVGElement.dataset")}} {{ReadOnlyInline}} - - : A {{DOMxRef("DOMStringMap")}} object which provides a list of key/value pairs of named data attributes which correspond to [custom data attributes](/en-US/docs/Learn_web_development/Howto/Solve_HTML_problems/Use_data_attributes) attached to the element. These can also be defined in SVG using attributes of the form {{SVGAttr("data-*")}}, where `*` is the key name for the pair. This works just like HTML's {{DOMxRef("HTMLElement.dataset")}} property and HTML's [`data-*`](/en-US/docs/Web/HTML/Global_attributes/data-*) global attribute. +- {{DOMxRef("SVGElement.autofocus")}} + - : Whether the control should be focused when the page loads, or when a {{htmlelement("dialog")}} or [popover](/en-US/docs/Web/HTML/Reference/Global_attributes/popover) become shown. - {{DOMxRef("SVGElement.className")}} {{Deprecated_Inline}} {{ReadOnlyInline}} - : An {{DOMxRef("SVGAnimatedString")}} that reflects the value of the {{SVGAttr("class")}} attribute on the given element, or the empty string if `class` is not present. This attribute is deprecated and may be removed in a future version of this specification. Authors are advised to use {{DOMxRef("Element.classList")}} instead. -- {{DOMxRef("SVGElement.blur")}} - - : Removes keyboard focus from the currently focused element. -- {{DOMxRef("SVGElement.focus")}} - - : Makes the element the current keyboard focus. +- {{DOMxRef("SVGElement.dataset")}} {{ReadOnlyInline}} + - : A {{DOMxRef("DOMStringMap")}} object which provides a list of key/value pairs of named data attributes which correspond to [custom data attributes](/en-US/docs/Web/HTML/How_to/Use_data_attributes) attached to the element. These can also be defined in SVG using attributes of the form {{SVGAttr("data-*")}}, where `*` is the key name for the pair. This works just like HTML's {{DOMxRef("HTMLElement.dataset")}} property and HTML's [`data-*`](/en-US/docs/Web/HTML/Reference/Global_attributes/data-*) global attribute. - {{DOMxRef("SVGElement.nonce")}} - : Returns the cryptographic number used once that is used by Content Security Policy to determine whether a given fetch will be allowed to proceed. - {{DOMxRef("SVGElement.ownerSVGElement")}} {{ReadOnlyInline}} @@ -38,7 +36,12 @@ _Also inherits properties from the {{DOMxRef("Element")}} interface._ ## Instance methods -_This interface has no methods, but inherits methods from {{DOMxRef("Element")}}._ +_This interface also inherits methods from {{DOMxRef("Element")}}._ + +- {{DOMxRef("SVGElement.blur()")}} + - : Removes keyboard focus from the currently focused element. +- {{DOMxRef("SVGElement.focus()")}} + - : Makes the element the current keyboard focus. ## Events @@ -67,6 +70,6 @@ Listen to these events using [`addEventListener()`](/en-US/docs/Web/API/EventTar ## See also -- HTML [`data-*`](/en-US/docs/Web/HTML/Global_attributes/data-*) attribute +- HTML [`data-*`](/en-US/docs/Web/HTML/Reference/Global_attributes/data-*) attribute - SVG {{SVGAttr("data-*")}} attribute -- [Using custom data attributes in HTML](/en-US/docs/Learn_web_development/Howto/Solve_HTML_problems/Use_data_attributes) +- [Using custom data attributes in HTML](/en-US/docs/Web/HTML/How_to/Use_data_attributes) diff --git a/files/en-us/web/api/svgelement/load_event/index.md b/files/en-us/web/api/svgelement/load_event/index.md index bf7318810043dad..47682187b905bb3 100644 --- a/files/en-us/web/api/svgelement/load_event/index.md +++ b/files/en-us/web/api/svgelement/load_event/index.md @@ -8,7 +8,7 @@ browser-compat: api.SVGElement.load_event {{APIRef("SVG")}} -The `load` event fires on an `SVGElement` when it is loaded in the browser, e.g. in the DOM in the case of an embedded `<svg>`. It is basically the same as the standard `load` DOM event. +The `load` event fires on an `SVGElement` when it is loaded in the browser, e.g., in the DOM in the case of an embedded `<svg>`. It is basically the same as the standard `load` DOM event. This event is not cancelable and does not bubble. @@ -16,10 +16,10 @@ This event is not cancelable and does not bubble. Use the event name in methods like {{domxref("EventTarget.addEventListener", "addEventListener()")}}, or set an event handler property. -```js -addEventListener("load", (event) => {}); +```js-nolint +addEventListener("load", (event) => { }) -onload = (event) => {}; +onload = (event) => { } ``` ## Event type diff --git a/files/en-us/web/api/svgelement/nonce/index.md b/files/en-us/web/api/svgelement/nonce/index.md index 40f7764caef4411..91fd71630da7b54 100644 --- a/files/en-us/web/api/svgelement/nonce/index.md +++ b/files/en-us/web/api/svgelement/nonce/index.md @@ -8,7 +8,7 @@ browser-compat: api.SVGElement.nonce {{APIRef("SVG")}} -The **`nonce`** property of the {{DOMxRef("SVGElement")}} interface returns the nonce that is used by [Content Security Policy](/en-US/docs/Web/HTTP/CSP) to determine whether a given fetch will be allowed to proceed. +The **`nonce`** property of the {{DOMxRef("SVGElement")}} interface returns the nonce that is used by [Content Security Policy](/en-US/docs/Web/HTTP/Guides/CSP) to determine whether a given fetch will be allowed to proceed. ## Value @@ -49,6 +49,6 @@ svg[nonce~="whatever"] { ## See also - {{domxref("HTMLElement.nonce")}} a similar method for HTML elements. -- [`nonce` global attribute](/en-US/docs/Web/HTML/Global_attributes/nonce) -- [Content Security Policy](/en-US/docs/Web/HTTP/CSP) +- [`nonce` global attribute](/en-US/docs/Web/HTML/Reference/Global_attributes/nonce) +- [Content Security Policy](/en-US/docs/Web/HTTP/Guides/CSP) - CSP: {{CSP("script-src")}} diff --git a/files/en-us/web/api/svgelement/style/index.md b/files/en-us/web/api/svgelement/style/index.md index 6b44bf756c169a0..290c4ad25783d38 100644 --- a/files/en-us/web/api/svgelement/style/index.md +++ b/files/en-us/web/api/svgelement/style/index.md @@ -8,7 +8,7 @@ browser-compat: api.SVGElement.style {{APIRef("CSSOM")}} -The read-only **`style`** property of the {{domxref("SVGElement")}} returns the _inline_ style of an element in the form of a live {{domxref("CSSStyleDeclaration")}} object that contains a list of all styles properties for that element with values assigned only for the attributes that are defined in the element's inline [`style`](/en-US/docs/Web/HTML/Global_attributes/style) attribute. +The read-only **`style`** property of the {{domxref("SVGElement")}} returns the _inline_ style of an element in the form of a live {{domxref("CSSStyleDeclaration")}} object that contains a list of all styles properties for that element with values assigned only for the attributes that are defined in the element's inline [`style`](/en-US/docs/Web/HTML/Reference/Global_attributes/style) attribute. Shorthand properties are expanded. If you set `style="border-top: 1px solid black"`, the longhand properties ({{cssxref("border-top-color")}}, {{cssxref("border-top-style")}}, and {{cssxref("border-top-width")}}) are set instead. @@ -66,7 +66,7 @@ for (const prop in elementStyle) { // We also ensure that the property is a numeric index (indicating an inline style) if ( Object.hasOwn(elementStyle, prop) && - !Number.isNaN(Number.parseInt(prop)) + !Number.isNaN(Number.parseInt(prop, 10)) ) { out.textContent += `${ elementStyle[prop] diff --git a/files/en-us/web/api/svgelement/tabindex/index.md b/files/en-us/web/api/svgelement/tabindex/index.md index 302e734bdad8539..1a61953ec6d4fd1 100644 --- a/files/en-us/web/api/svgelement/tabindex/index.md +++ b/files/en-us/web/api/svgelement/tabindex/index.md @@ -64,7 +64,7 @@ svg1.focus(); // Works, even though it is not in the tabbing order ## See also - {{domxref("HTMLElement.tabIndex")}} a similar method for HTML elements. -- [Accessibility of keyboard-navigable JavaScript widgets](/en-US/docs/Web/Accessibility/Keyboard-navigable_JavaScript_widgets) +- [Accessibility of keyboard-navigable JavaScript widgets](/en-US/docs/Web/Accessibility/Guides/Keyboard-navigable_JavaScript_widgets) - The HTML - [`tabindex`](/en-US/docs/Web/HTML/Global_attributes/tabindex) + [`tabindex`](/en-US/docs/Web/HTML/Reference/Global_attributes/tabindex) global attribute. diff --git a/files/en-us/web/api/svgellipseelement/cx/index.md b/files/en-us/web/api/svgellipseelement/cx/index.md index 20990a68ad1f1f6..9bffe9cf3f979aa 100644 --- a/files/en-us/web/api/svgellipseelement/cx/index.md +++ b/files/en-us/web/api/svgellipseelement/cx/index.md @@ -10,7 +10,7 @@ browser-compat: api.SVGEllipseElement.cx The **`cx`** read-only property of the {{domxref("SVGEllipseElement")}} interface describes the x-axis coordinate of the center of the ellipse as an {{domxref("SVGAnimatedLength")}}. It reflects the computed value of the {{SVGAttr("cx")}} attribute on the {{SVGElement("ellipse")}} element. -The attribute value is a [`<length>`](/en-US/docs/Web/SVG/Content_type#length), [`<percentage>`](/en-US/docs/Web/SVG/Content_type#percentage), or [`<number>`](/en-US/docs/Web/SVG/Content_type#number). The numeric value of the {{domxref("SVGAnimatedLength.baseVal")}} is the x-coordinate of the ellipse's center in the user coordinate system. +The attribute value is a [`<length>`](/en-US/docs/Web/SVG/Guides/Content_type#length), [`<percentage>`](/en-US/docs/Web/SVG/Guides/Content_type#percentage), or [`<number>`](/en-US/docs/Web/SVG/Guides/Content_type#number). The numeric value of the {{domxref("SVGAnimatedLength.baseVal")}} is the x-coordinate of the ellipse's center in the user coordinate system. ## Value diff --git a/files/en-us/web/api/svgellipseelement/cy/index.md b/files/en-us/web/api/svgellipseelement/cy/index.md index 4cbb8feae44829f..b59f12b263739c8 100644 --- a/files/en-us/web/api/svgellipseelement/cy/index.md +++ b/files/en-us/web/api/svgellipseelement/cy/index.md @@ -10,7 +10,7 @@ browser-compat: api.SVGEllipseElement.cy The **`cy`** read-only property of the {{domxref("SVGEllipseElement")}} interface describes the y-axis coordinate of the center of the ellipse as an {{domxref("SVGAnimatedLength")}}. It reflects the computed value of the {{SVGAttr("cy")}} attribute on the {{SVGElement("ellipse")}} element. -The attribute value is a [`<length>`](/en-US/docs/Web/SVG/Content_type#length), [`<percentage>`](/en-US/docs/Web/SVG/Content_type#percentage), or [`<number>`](/en-US/docs/Web/SVG/Content_type#number). The numeric value of the {{domxref("SVGAnimatedLength.baseVal")}} is the y-coordinate of the ellipse's center in the user coordinate system. +The attribute value is a [`<length>`](/en-US/docs/Web/SVG/Guides/Content_type#length), [`<percentage>`](/en-US/docs/Web/SVG/Guides/Content_type#percentage), or [`<number>`](/en-US/docs/Web/SVG/Guides/Content_type#number). The numeric value of the {{domxref("SVGAnimatedLength.baseVal")}} is the y-coordinate of the ellipse's center in the user coordinate system. ## Value diff --git a/files/en-us/web/api/svgellipseelement/rx/index.md b/files/en-us/web/api/svgellipseelement/rx/index.md index 4e3a3cdf3b6747a..7fce56e83695e3b 100644 --- a/files/en-us/web/api/svgellipseelement/rx/index.md +++ b/files/en-us/web/api/svgellipseelement/rx/index.md @@ -10,7 +10,7 @@ browser-compat: api.SVGEllipseElement.rx The **`rx`** read-only property of the {{domxref("SVGEllipseElement")}} interface describes the x-axis radius of the ellipse as an {{domxref("SVGAnimatedLength")}}. It reflects the computed value of the {{SVGAttr("rx")}} attribute on the {{SVGElement("ellipse")}} element. -The attribute value is a [`<length>`](/en-US/docs/Web/SVG/Content_type#length), [`<percentage>`](/en-US/docs/Web/SVG/Content_type#percentage), or [`<number>`](/en-US/docs/Web/SVG/Content_type#number). The numeric value of the {{domxref("SVGAnimatedLength.baseVal")}} is the radius of the ellipse along the x-axis in the user coordinate system. +The attribute value is a [`<length>`](/en-US/docs/Web/SVG/Guides/Content_type#length), [`<percentage>`](/en-US/docs/Web/SVG/Guides/Content_type#percentage), or [`<number>`](/en-US/docs/Web/SVG/Guides/Content_type#number). The numeric value of the {{domxref("SVGAnimatedLength.baseVal")}} is the radius of the ellipse along the x-axis in the user coordinate system. ## Value diff --git a/files/en-us/web/api/svgellipseelement/ry/index.md b/files/en-us/web/api/svgellipseelement/ry/index.md index a6e24e692594615..d768ebfee2420a8 100644 --- a/files/en-us/web/api/svgellipseelement/ry/index.md +++ b/files/en-us/web/api/svgellipseelement/ry/index.md @@ -10,7 +10,7 @@ browser-compat: api.SVGEllipseElement.ry The **`ry`** read-only property of the {{domxref("SVGEllipseElement")}} interface describes the y-axis radius of the ellipse as an {{domxref("SVGAnimatedLength")}}. It reflects the computed value of the {{SVGAttr("ry")}} attribute on the {{SVGElement("ellipse")}} element. -The attribute value is a [`<length>`](/en-US/docs/Web/SVG/Content_type#length), [`<percentage>`](/en-US/docs/Web/SVG/Content_type#percentage), or [`<number>`](/en-US/docs/Web/SVG/Content_type#number). The numeric value of the {{domxref("SVGAnimatedLength.baseVal")}} is the radius of the ellipse along the y-axis in the user coordinate system. +The attribute value is a [`<length>`](/en-US/docs/Web/SVG/Guides/Content_type#length), [`<percentage>`](/en-US/docs/Web/SVG/Guides/Content_type#percentage), or [`<number>`](/en-US/docs/Web/SVG/Guides/Content_type#number). The numeric value of the {{domxref("SVGAnimatedLength.baseVal")}} is the radius of the ellipse along the y-axis in the user coordinate system. ## Value diff --git a/files/en-us/web/api/svgevent/index.md b/files/en-us/web/api/svgevent/index.md deleted file mode 100644 index 0b134187f77bac0..000000000000000 --- a/files/en-us/web/api/svgevent/index.md +++ /dev/null @@ -1,18 +0,0 @@ ---- -title: SVGEvent -slug: Web/API/SVGEvent -page-type: web-api-interface ---- - -{{deprecated_header}}{{APIRef("SVG")}} - -The **`SVGEvent`** interface represents the event object for most SVG-related events. - -## Instance properties - -| Property | Type | Description | -| ------------------------------- | -------------------------- | ------------------------------------------------------ | -| `target` {{ReadOnlyInline}} | {{domxref("EventTarget")}} | The event target (the topmost target in the DOM tree). | -| `type` {{ReadOnlyInline}} | string | The type of event. | -| `bubbles` {{ReadOnlyInline}} | A boolean value | Whether the event normally bubbles or not. | -| `cancelable` {{ReadOnlyInline}} | A boolean value | Whether the event is cancellable or not. | diff --git a/files/en-us/web/api/svgfeblendelement/height/index.md b/files/en-us/web/api/svgfeblendelement/height/index.md index cf7e1ec2c2b4157..badfa93db8ec841 100644 --- a/files/en-us/web/api/svgfeblendelement/height/index.md +++ b/files/en-us/web/api/svgfeblendelement/height/index.md @@ -10,9 +10,9 @@ browser-compat: api.SVGFEBlendElement.height The **`height`** read-only property of the {{domxref("SVGFEBlendElement")}} interface describes the vertical size of an SVG filter primitive as a {{domxref("SVGAnimatedLength")}}. -It reflects the {{SVGElement("feBlend")}} element's {{SVGAttr("height")}} filter primitive attribute. The attribute is a [`<length>`](/en-US/docs/Web/SVG/Content_type#length) or a [`<percentage>`](/en-US/docs/Web/SVG/Content_type#percentage) relative to the height of the filter region. The default value is `100%`. The property value is a length in user coordinate system units. +It reflects the {{SVGElement("feBlend")}} element's {{SVGAttr("height")}} filter primitive attribute. The attribute is a [`<length>`](/en-US/docs/Web/SVG/Guides/Content_type#length) or a [`<percentage>`](/en-US/docs/Web/SVG/Guides/Content_type#percentage) relative to the height of the filter region. The default value is `100%`. The property value is a length in user coordinate system units. -The `<feBlend>` SVG filter blends two input images together using commonly used imaging software {{cssxref("blend-mode", "blending modes")}}. +The `<feBlend>` SVG filter blends two input images together using commonly used imaging software [blending modes](/en-US/docs/Web/CSS/blend-mode). ## Value diff --git a/files/en-us/web/api/svgfeblendelement/index.md b/files/en-us/web/api/svgfeblendelement/index.md index 51496fbe174ef79..a6260fe75ccc53d 100644 --- a/files/en-us/web/api/svgfeblendelement/index.md +++ b/files/en-us/web/api/svgfeblendelement/index.md @@ -11,52 +11,6 @@ The **`SVGFEBlendElement`** interface corresponds to the {{SVGElement("feBlend") {{InheritanceDiagram}} -## Constants - -<table class="no-markdown"> - <tbody> - <tr> - <th>Name</th> - <th>Value</th> - <th>Description</th> - </tr> - <tr> - <td><code>SVG_FEBLEND_MODE_UNKNOWN</code></td> - <td>0</td> - <td> - The type is not one of predefined types. It is invalid to attempt to - define a new value of this type or to attempt to switch an existing - value to this type. - </td> - </tr> - <tr> - <td><code>SVG_FEBLEND_MODE_NORMAL</code></td> - <td>1</td> - <td>Corresponds to the value <code>normal</code>.</td> - </tr> - <tr> - <td><code>SVG_FEBLEND_MODE_MULTIPLY</code></td> - <td>2</td> - <td>Corresponds to the value <code>multiply</code>.</td> - </tr> - <tr> - <td><code>SVG_FEBLEND_MODE_SCREEN</code></td> - <td>3</td> - <td>Corresponds to the value <code>screen</code>.</td> - </tr> - <tr> - <td><code>SVG_FEBLEND_MODE_DARKEN</code></td> - <td>4</td> - <td>Corresponds to the value <code>darken</code>.</td> - </tr> - <tr> - <td><code>SVG_FEBLEND_MODE_LIGHTEN</code></td> - <td>5</td> - <td>Corresponds to the value <code>lighten</code>.</td> - </tr> - </tbody> -</table> - ## Instance properties _This interface also inherits properties from its parent interface, {{domxref("SVGElement")}}._ @@ -82,6 +36,21 @@ _This interface also inherits properties from its parent interface, {{domxref("S _This interface does not provide any specific methods, but implements those of its parent, {{domxref("SVGElement")}}._ +## Static properties + +- `SVG_FEBLEND_MODE_UNKNOWN` (0) + - : The type is not one of predefined types. It is invalid to attempt to define a new value of this type or to attempt to switch an existing value to this type. +- `SVG_FEBLEND_MODE_NORMAL` (1) + - : Corresponds to the value `normal`. +- `SVG_FEBLEND_MODE_MULTIPLY` (2) + - : Corresponds to the value `multiply`. +- `SVG_FEBLEND_MODE_SCREEN` (3) + - : Corresponds to the value `screen`. +- `SVG_FEBLEND_MODE_DARKEN` (4) + - : Corresponds to the value `darken`. +- `SVG_FEBLEND_MODE_LIGHTEN` (5) + - : Corresponds to the value `lighten`. + ## Specifications {{Specifications}} diff --git a/files/en-us/web/api/svgfeblendelement/result/index.md b/files/en-us/web/api/svgfeblendelement/result/index.md index 31c88c94fb35ab3..09694b7b2a6ab32 100644 --- a/files/en-us/web/api/svgfeblendelement/result/index.md +++ b/files/en-us/web/api/svgfeblendelement/result/index.md @@ -11,7 +11,7 @@ browser-compat: api.SVGFEBlendElement.result The **`result`** read-only property of the {{domxref("SVGFEBlendElement")}} interface describes the assigned name of an SVG filter primitive as a {{domxref("SVGAnimatedString")}}. It reflects the {{SVGElement("feBlend")}} element's {{SVGAttr("result")}} attribute. -The `<feBlend>` SVG filter blends two input images together using commonly used imaging software {{cssxref("blend-mode", "blending modes")}}. +The `<feBlend>` SVG filter blends two input images together using commonly used imaging software [blending modes](/en-US/docs/Web/CSS/blend-mode). The attribute value is a {{cssxref("custom-ident")}}. If supplied, then graphics that result from processing this filter primitive can be referenced by an {{SVGAttr("in")}} attribute on a subsequent filter primitive within the same {{SVGElement("filter")}} element. diff --git a/files/en-us/web/api/svgfeblendelement/width/index.md b/files/en-us/web/api/svgfeblendelement/width/index.md index 89c02261f66756a..d7975de02d47fd2 100644 --- a/files/en-us/web/api/svgfeblendelement/width/index.md +++ b/files/en-us/web/api/svgfeblendelement/width/index.md @@ -10,9 +10,9 @@ browser-compat: api.SVGFEBlendElement.width The **`width`** read-only property of the {{domxref("SVGFEBlendElement")}} interface describes the horizontal size of an SVG filter primitive as a {{domxref("SVGAnimatedLength")}}. -It reflects the {{SVGElement("feBlend")}} element's {{SVGAttr("width")}} filter primitive attribute. The attribute is a [`<length>`](/en-US/docs/Web/SVG/Content_type#length) or a [`<percentage>`](/en-US/docs/Web/SVG/Content_type#percentage) relative to the width of the filter region. The default value is `100%`. The property value is a length in user coordinate system units. +It reflects the {{SVGElement("feBlend")}} element's {{SVGAttr("width")}} filter primitive attribute. The attribute is a [`<length>`](/en-US/docs/Web/SVG/Guides/Content_type#length) or a [`<percentage>`](/en-US/docs/Web/SVG/Guides/Content_type#percentage) relative to the width of the filter region. The default value is `100%`. The property value is a length in user coordinate system units. -The `<feBlend>` SVG filter blends two input images together using commonly used imaging software {{cssxref("blend-mode", "blending modes")}}. +The `<feBlend>` SVG filter blends two input images together using commonly used imaging software [blending modes](/en-US/docs/Web/CSS/blend-mode). ## Value diff --git a/files/en-us/web/api/svgfeblendelement/x/index.md b/files/en-us/web/api/svgfeblendelement/x/index.md index af515bbb9482c4e..ed1d3144b066be4 100644 --- a/files/en-us/web/api/svgfeblendelement/x/index.md +++ b/files/en-us/web/api/svgfeblendelement/x/index.md @@ -10,9 +10,9 @@ browser-compat: api.SVGFEBlendElement.x The **`x`** read-only property of the {{domxref("SVGFEBlendElement")}} interface describes the horizontal coordinate of the position of an SVG filter primitive as a {{domxref("SVGAnimatedLength")}}. -It reflects the {{SVGElement("feBlend")}} element's {{SVGAttr("x")}} filter primitive attribute value. The `<feBlend>` SVG filter blends two input images together using commonly used imaging software {{cssxref("blend-mode", "blending modes")}}. +It reflects the {{SVGElement("feBlend")}} element's {{SVGAttr("x")}} filter primitive attribute value. The `<feBlend>` SVG filter blends two input images together using commonly used imaging software [blending modes](/en-US/docs/Web/CSS/blend-mode). -The attribute is a [`<length>`](/en-US/docs/Web/SVG/Content_type#length) or [`<percentage>`](/en-US/docs/Web/SVG/Content_type#percentage). The `<coordinate>` is a length in the user coordinate system that is the given distance from the origin of the user coordinate system along the x-axis. If the `x` attribute is a percent value, the property value is relative to the width of the filter region in user coordinate system units. The default value is `0`. +The attribute is a [`<length>`](/en-US/docs/Web/SVG/Guides/Content_type#length) or [`<percentage>`](/en-US/docs/Web/SVG/Guides/Content_type#percentage). The `<coordinate>` is a length in the user coordinate system that is the given distance from the origin of the user coordinate system along the x-axis. If the `x` attribute is a percent value, the property value is relative to the width of the filter region in user coordinate system units. The default value is `0`. ## Value diff --git a/files/en-us/web/api/svgfeblendelement/y/index.md b/files/en-us/web/api/svgfeblendelement/y/index.md index 76aa2cc0c9288ec..bef5c7fea84154d 100644 --- a/files/en-us/web/api/svgfeblendelement/y/index.md +++ b/files/en-us/web/api/svgfeblendelement/y/index.md @@ -11,9 +11,9 @@ browser-compat: api.SVGFEBlendElement.y The **`y`** read-only property of the {{domxref("SVGFEBlendElement")}} interface describes the vertical coordinate of the position of an SVG filter primitive as a {{domxref("SVGAnimatedLength")}}. It reflects the {{SVGElement("feBlend")}} element's {{SVGAttr("y")}} filter primitive attribute value. -The `<feBlend>` SVG filter blends two input images together using commonly used imaging software {{cssxref("blend-mode", "blending modes")}}. +The `<feBlend>` SVG filter blends two input images together using commonly used imaging software [blending modes](/en-US/docs/Web/CSS/blend-mode). -The attribute is a [`<length>`](/en-US/docs/Web/SVG/Content_type#length) or [`<percentage>`](/en-US/docs/Web/SVG/Content_type#percentage). The `<coordinate>` is a length in the user coordinate system that is the given distance from the origin of the user coordinate system along the y-axis. If the `y` attribute is a percent value, the property value is a relative to the height of the filter region in user coordinate system units. The default value is `0`. +The attribute is a [`<length>`](/en-US/docs/Web/SVG/Guides/Content_type#length) or [`<percentage>`](/en-US/docs/Web/SVG/Guides/Content_type#percentage). The `<coordinate>` is a length in the user coordinate system that is the given distance from the origin of the user coordinate system along the y-axis. If the `y` attribute is a percent value, the property value is a relative to the height of the filter region in user coordinate system units. The default value is `0`. ## Value diff --git a/files/en-us/web/api/svgfecolormatrixelement/height/index.md b/files/en-us/web/api/svgfecolormatrixelement/height/index.md index b3a51a6d06d3ddd..70160ce8bf818b0 100644 --- a/files/en-us/web/api/svgfecolormatrixelement/height/index.md +++ b/files/en-us/web/api/svgfecolormatrixelement/height/index.md @@ -12,7 +12,7 @@ The **`height`** read-only property of the {{domxref("SVGFEColorMatrixElement")} It reflects the {{SVGElement("feColorMatrix")}} element's {{SVGAttr("height")}} filter primitive attribute. The `<feColorMatrix>` filter applies a matrix transformation on the {{glossary("RGB")}} color and {{glossary("alpha")}} values. -The attribute is a [`<length>`](/en-US/docs/Web/SVG/Content_type#length) or a [`<percentage>`](/en-US/docs/Web/SVG/Content_type#percentage) relative to the height of the filter region. The default value is `100%`. The property value is a length in user coordinate system units. +The attribute is a [`<length>`](/en-US/docs/Web/SVG/Guides/Content_type#length) or a [`<percentage>`](/en-US/docs/Web/SVG/Guides/Content_type#percentage) relative to the height of the filter region. The default value is `100%`. The property value is a length in user coordinate system units. ## Value @@ -41,4 +41,4 @@ console.log(verticalSize.baseVal.value); // the `height` value - CSS {{cssxref("mix-blend-mode")}} property - [CSS filter effects](/en-US/docs/Web/CSS/CSS_filter_effects) - SVG {{SVGElement("filter")}} element, SVG {{SVGAttr("filter")}} attribute in [SVG](/en-US/docs/Web/SVG) -- [Applying SVG effects to HTML content](/en-US/docs/Web/SVG/Applying_SVG_effects_to_HTML_content) +- [Applying SVG effects to HTML content](/en-US/docs/Web/SVG/Guides/Applying_SVG_effects_to_HTML_content) diff --git a/files/en-us/web/api/svgfecolormatrixelement/index.md b/files/en-us/web/api/svgfecolormatrixelement/index.md index 2d83c358e7c5b9d..107e14d54dd5047 100644 --- a/files/en-us/web/api/svgfecolormatrixelement/index.md +++ b/files/en-us/web/api/svgfecolormatrixelement/index.md @@ -11,47 +11,6 @@ The **`SVGFEColorMatrixElement`** interface corresponds to the {{SVGElement("feC {{InheritanceDiagram}} -## Constants - -<table class="no-markdown"> - <tbody> - <tr> - <th>Name</th> - <th>Value</th> - <th>Description</th> - </tr> - <tr> - <td><code>SVG_FECOLORMATRIX_TYPE_UNKNOWN</code></td> - <td>0</td> - <td> - The type is not one of predefined types. It is invalid to attempt to - define a new value of this type or to attempt to switch an existing - value to this type. - </td> - </tr> - <tr> - <td><code>SVG_FECOLORMATRIX_TYPE_MATRIX</code></td> - <td>1</td> - <td>Corresponds to the <code>matrix</code> value.</td> - </tr> - <tr> - <td><code>SVG_FECOLORMATRIX_TYPE_SATURATE</code></td> - <td>2</td> - <td>Corresponds to the <code>saturate</code> value.</td> - </tr> - <tr> - <td><code>SVG_FECOLORMATRIX_TYPE_HUEROTATE</code></td> - <td>3</td> - <td>Corresponds to <code>hueRotate</code> value.</td> - </tr> - <tr> - <td><code>SVG_FECOLORMATRIX_TYPE_LUMINANCETOALPHA</code></td> - <td>4</td> - <td>Corresponds to <code>luminanceToAlpha</code> value.</td> - </tr> - </tbody> -</table> - ## Instance properties _This interface also inherits properties from its parent interface, {{domxref("SVGElement")}}._ @@ -77,6 +36,19 @@ _This interface also inherits properties from its parent interface, {{domxref("S _This interface does not provide any specific methods, but implements those of its parent, {{domxref("SVGElement")}}_. +## Static properties + +- `SVG_FECOLORMATRIX_TYPE_UNKNOWN` (0) + - : The type is not one of predefined types. It is invalid to attempt to define a new value of this type or to attempt to switch an existing value to this type. +- `SVG_FECOLORMATRIX_TYPE_MATRIX` (1) + - : Corresponds to the value `matrix`. +- `SVG_FECOLORMATRIX_TYPE_SATURATE` (2) + - : Corresponds to the value `saturate`. +- `SVG_FECOLORMATRIX_TYPE_HUEROTATE` (3) + - : Corresponds to the value `hueRotate`. +- `SVG_FECOLORMATRIX_TYPE_LUMINANCETOALPHA` (4) + - : Corresponds to the value `luminanceToAlpha`. + ## Specifications {{Specifications}} diff --git a/files/en-us/web/api/svgfecolormatrixelement/result/index.md b/files/en-us/web/api/svgfecolormatrixelement/result/index.md index 5fa2d360ffacf81..a12ca9a0179af27 100644 --- a/files/en-us/web/api/svgfecolormatrixelement/result/index.md +++ b/files/en-us/web/api/svgfecolormatrixelement/result/index.md @@ -42,4 +42,4 @@ console.log(filterName.baseVal); // the filter's assigned name - CSS {{cssxref("mix-blend-mode")}} property - [CSS filter effects](/en-US/docs/Web/CSS/CSS_filter_effects) - SVG {{SVGElement("filter")}} element, SVG {{SVGAttr("filter")}} attribute in [SVG](/en-US/docs/Web/SVG) -- [Applying SVG effects to HTML content](/en-US/docs/Web/SVG/Applying_SVG_effects_to_HTML_content) +- [Applying SVG effects to HTML content](/en-US/docs/Web/SVG/Guides/Applying_SVG_effects_to_HTML_content) diff --git a/files/en-us/web/api/svgfecolormatrixelement/width/index.md b/files/en-us/web/api/svgfecolormatrixelement/width/index.md index d5a3c5e0edabe86..29ad6bc909610ee 100644 --- a/files/en-us/web/api/svgfecolormatrixelement/width/index.md +++ b/files/en-us/web/api/svgfecolormatrixelement/width/index.md @@ -10,7 +10,7 @@ browser-compat: api.SVGFEColorMatrixElement.width The **`width`** read-only property of the {{domxref("SVGFEColorMatrixElement")}} interface describes the horizontal size of an SVG filter primitive as a {{domxref("SVGAnimatedLength")}}. -It reflects the {{SVGElement("feColorMatrix")}} element's {{SVGAttr("width")}} filter primitive attribute. The `<feColorMatrix>` filter applies a matrix transformation on the {{glossary("RGB")}} color and {{glossary("alpha")}} values. The attribute is a [`<length>`](/en-US/docs/Web/SVG/Content_type#length) or a [`<percentage>`](/en-US/docs/Web/SVG/Content_type#percentage) relative to the width of the filter region. The default value is `100%`. The property value is a length in user coordinate system units. +It reflects the {{SVGElement("feColorMatrix")}} element's {{SVGAttr("width")}} filter primitive attribute. The `<feColorMatrix>` filter applies a matrix transformation on the {{glossary("RGB")}} color and {{glossary("alpha")}} values. The attribute is a [`<length>`](/en-US/docs/Web/SVG/Guides/Content_type#length) or a [`<percentage>`](/en-US/docs/Web/SVG/Guides/Content_type#percentage) relative to the width of the filter region. The default value is `100%`. The property value is a length in user coordinate system units. ## Value @@ -39,4 +39,4 @@ console.log(horizontalSize.baseVal.value); // the `width` value - CSS {{cssxref("mix-blend-mode")}} property - [CSS filter effects](/en-US/docs/Web/CSS/CSS_filter_effects) - SVG {{SVGElement("filter")}} element, SVG {{SVGAttr("filter")}} attribute in [SVG](/en-US/docs/Web/SVG) -- [Applying SVG effects to HTML content](/en-US/docs/Web/SVG/Applying_SVG_effects_to_HTML_content) +- [Applying SVG effects to HTML content](/en-US/docs/Web/SVG/Guides/Applying_SVG_effects_to_HTML_content) diff --git a/files/en-us/web/api/svgfecolormatrixelement/x/index.md b/files/en-us/web/api/svgfecolormatrixelement/x/index.md index 9256b2e0d8509b3..9f46718a55ccaf1 100644 --- a/files/en-us/web/api/svgfecolormatrixelement/x/index.md +++ b/files/en-us/web/api/svgfecolormatrixelement/x/index.md @@ -10,7 +10,7 @@ browser-compat: api.SVGFEColorMatrixElement.x The **`x`** read-only property of the {{domxref("SVGFEColorMatrixElement")}} interface describes the horizontal coordinate of the position of an SVG filter primitive as a {{domxref("SVGAnimatedLength")}}. -It reflects the {{SVGElement("feColorMatrix")}} element's {{SVGAttr("x")}} filter primitive attribute value. The `<feColorMatrix>` filter applies a matrix transformation on the {{glossary("RGB")}} color and {{glossary("alpha")}} values. The attribute is a [`<length>`](/en-US/docs/Web/SVG/Content_type#length) or [`<percentage>`](/en-US/docs/Web/SVG/Content_type#percentage). The `<coordinate>` is a length in the user coordinate system that is the given distance from the origin of the user coordinate system along the x-axis. If the `x` attribute is a percent value, the property value is relative to the width of the filter region in user coordinate system units. The default value is `0`. +It reflects the {{SVGElement("feColorMatrix")}} element's {{SVGAttr("x")}} filter primitive attribute value. The `<feColorMatrix>` filter applies a matrix transformation on the {{glossary("RGB")}} color and {{glossary("alpha")}} values. The attribute is a [`<length>`](/en-US/docs/Web/SVG/Guides/Content_type#length) or [`<percentage>`](/en-US/docs/Web/SVG/Guides/Content_type#percentage). The `<coordinate>` is a length in the user coordinate system that is the given distance from the origin of the user coordinate system along the x-axis. If the `x` attribute is a percent value, the property value is relative to the width of the filter region in user coordinate system units. The default value is `0`. ## Value @@ -39,4 +39,4 @@ console.log(leftPosition.baseVal.value); // the `x` value - CSS {{cssxref("mix-blend-mode")}} property - [CSS filter effects](/en-US/docs/Web/CSS/CSS_filter_effects) - SVG {{SVGElement("filter")}} element, SVG {{SVGAttr("filter")}} attribute in [SVG](/en-US/docs/Web/SVG) -- [Applying SVG effects to HTML content](/en-US/docs/Web/SVG/Applying_SVG_effects_to_HTML_content) +- [Applying SVG effects to HTML content](/en-US/docs/Web/SVG/Guides/Applying_SVG_effects_to_HTML_content) diff --git a/files/en-us/web/api/svgfecolormatrixelement/y/index.md b/files/en-us/web/api/svgfecolormatrixelement/y/index.md index e6713281ea87860..b3910c545dc5cc4 100644 --- a/files/en-us/web/api/svgfecolormatrixelement/y/index.md +++ b/files/en-us/web/api/svgfecolormatrixelement/y/index.md @@ -10,7 +10,7 @@ browser-compat: api.SVGFEColorMatrixElement.y The **`y`** read-only property of the {{domxref("SVGFEColorMatrixElement")}} interface describes the vertical coordinate of the position of an SVG filter primitive as a {{domxref("SVGAnimatedLength")}}. -It reflects the {{SVGElement("feColorMatrix")}} element's {{SVGAttr("y")}} filter primitive attribute value. The `<feColorMatrix>` filter applies a matrix transformation on the {{glossary("RGB")}} color and {{glossary("alpha")}} values. The attribute is a [`<length>`](/en-US/docs/Web/SVG/Content_type#length) or [`<percentage>`](/en-US/docs/Web/SVG/Content_type#percentage). The `<coordinate>` is a length in the user coordinate system that is the given distance from the origin of the filter along the y-axis. If the `y` attribute is a percent value, the property value is a relative to the height of the filter region in user coordinate system units. The default value is `0`. +It reflects the {{SVGElement("feColorMatrix")}} element's {{SVGAttr("y")}} filter primitive attribute value. The `<feColorMatrix>` filter applies a matrix transformation on the {{glossary("RGB")}} color and {{glossary("alpha")}} values. The attribute is a [`<length>`](/en-US/docs/Web/SVG/Guides/Content_type#length) or [`<percentage>`](/en-US/docs/Web/SVG/Guides/Content_type#percentage). The `<coordinate>` is a length in the user coordinate system that is the given distance from the origin of the filter along the y-axis. If the `y` attribute is a percent value, the property value is a relative to the height of the filter region in user coordinate system units. The default value is `0`. ## Value @@ -39,4 +39,4 @@ console.log(topPosition.baseVal.value); // the `y` value - CSS {{cssxref("mix-blend-mode")}} property - [CSS filter effects](/en-US/docs/Web/CSS/CSS_filter_effects) - SVG {{SVGElement("filter")}} element, SVG {{SVGAttr("filter")}} attribute in [SVG](/en-US/docs/Web/SVG) -- [Applying SVG effects to HTML content](/en-US/docs/Web/SVG/Applying_SVG_effects_to_HTML_content) +- [Applying SVG effects to HTML content](/en-US/docs/Web/SVG/Guides/Applying_SVG_effects_to_HTML_content) diff --git a/files/en-us/web/api/svgfecomponenttransferelement/height/index.md b/files/en-us/web/api/svgfecomponenttransferelement/height/index.md index 50e06ed39e83b84..70eb30ec4468ccc 100644 --- a/files/en-us/web/api/svgfecomponenttransferelement/height/index.md +++ b/files/en-us/web/api/svgfecomponenttransferelement/height/index.md @@ -12,7 +12,7 @@ The **`height`** read-only property of the {{domxref("SVGFEComponentTransferElem It reflects the {{SVGElement("feComponentTransfer")}} element's {{SVGAttr("height")}} filter primitive attribute. The `<feComponentTransfer>` filter performs component-wise color and alpha transparency remapping, allowing for brightness, contrast, color balance and threshold adjustments. -The attribute is a [`<length>`](/en-US/docs/Web/SVG/Content_type#length) or a [`<percentage>`](/en-US/docs/Web/SVG/Content_type#percentage) relative to the height of the filter region. The default value is `100%`. The property value is a length in user coordinate system units. +The attribute is a [`<length>`](/en-US/docs/Web/SVG/Guides/Content_type#length) or a [`<percentage>`](/en-US/docs/Web/SVG/Guides/Content_type#percentage) relative to the height of the filter region. The default value is `100%`. The property value is a length in user coordinate system units. ## Value diff --git a/files/en-us/web/api/svgfecomponenttransferelement/width/index.md b/files/en-us/web/api/svgfecomponenttransferelement/width/index.md index 5616b2412c5c84d..186fd77489de61a 100644 --- a/files/en-us/web/api/svgfecomponenttransferelement/width/index.md +++ b/files/en-us/web/api/svgfecomponenttransferelement/width/index.md @@ -10,7 +10,7 @@ browser-compat: api.SVGFEComponentTransferElement.width The **`width`** read-only property of the {{domxref("SVGFEComponentTransferElement")}} interface describes the horizontal size of an SVG filter primitive as a {{domxref("SVGAnimatedLength")}}. -It reflects the {{SVGElement("feComponentTransfer")}} element's {{SVGAttr("width")}} filter primitive attribute. The attribute is a [`<length>`](/en-US/docs/Web/SVG/Content_type#length) or a [`<percentage>`](/en-US/docs/Web/SVG/Content_type#percentage) relative to the width of the filter region. The default value is `100%`. The property value is a length in user coordinate system units. +It reflects the {{SVGElement("feComponentTransfer")}} element's {{SVGAttr("width")}} filter primitive attribute. The attribute is a [`<length>`](/en-US/docs/Web/SVG/Guides/Content_type#length) or a [`<percentage>`](/en-US/docs/Web/SVG/Guides/Content_type#percentage) relative to the width of the filter region. The default value is `100%`. The property value is a length in user coordinate system units. ## Value diff --git a/files/en-us/web/api/svgfecomponenttransferelement/x/index.md b/files/en-us/web/api/svgfecomponenttransferelement/x/index.md index c8fffba12102472..3ffb34bf138a366 100644 --- a/files/en-us/web/api/svgfecomponenttransferelement/x/index.md +++ b/files/en-us/web/api/svgfecomponenttransferelement/x/index.md @@ -10,7 +10,7 @@ browser-compat: api.SVGFEComponentTransferElement.x The **`x`** read-only property of the {{domxref("SVGFEComponentTransferElement")}} interface describes the horizontal coordinate of the position of an SVG filter primitive as a {{domxref("SVGAnimatedLength")}}. -It reflects the {{SVGElement("feComponentTransfer")}} element's {{SVGAttr("x")}} filter primitive attribute value. The attribute is a [`<length>`](/en-US/docs/Web/SVG/Content_type#length) or [`<percentage>`](/en-US/docs/Web/SVG/Content_type#percentage). The `<coordinate>` is a length in the user coordinate system that is the given distance from the origin of the user coordinate system along the x-axis. If the `x` attribute is a percent value, the property value is relative to the width of the filter region in user coordinate system units. The default value is `0`. +It reflects the {{SVGElement("feComponentTransfer")}} element's {{SVGAttr("x")}} filter primitive attribute value. The attribute is a [`<length>`](/en-US/docs/Web/SVG/Guides/Content_type#length) or [`<percentage>`](/en-US/docs/Web/SVG/Guides/Content_type#percentage). The `<coordinate>` is a length in the user coordinate system that is the given distance from the origin of the user coordinate system along the x-axis. If the `x` attribute is a percent value, the property value is relative to the width of the filter region in user coordinate system units. The default value is `0`. ## Value diff --git a/files/en-us/web/api/svgfecomponenttransferelement/y/index.md b/files/en-us/web/api/svgfecomponenttransferelement/y/index.md index 2ccaba64074b827..e520060612c7975 100644 --- a/files/en-us/web/api/svgfecomponenttransferelement/y/index.md +++ b/files/en-us/web/api/svgfecomponenttransferelement/y/index.md @@ -10,7 +10,7 @@ browser-compat: api.SVGFEComponentTransferElement.y The **`y`** read-only property of the {{domxref("SVGFEComponentTransferElement")}} interface describes the vertical coordinate of the position of an SVG filter primitive as a {{domxref("SVGAnimatedLength")}}. -It reflects the {{SVGElement("feComponentTransfer")}} element's {{SVGAttr("y")}} filter primitive attribute value. The attribute is a [`<length>`](/en-US/docs/Web/SVG/Content_type#length) or [`<percentage>`](/en-US/docs/Web/SVG/Content_type#percentage). The `<coordinate>` is a length in the user coordinate system that is the given distance from the origin of the filter along the y-axis. If the `y` attribute is a percent value, the property value is a relative to the height of the filter region in user coordinate system units. The default value is `0`. +It reflects the {{SVGElement("feComponentTransfer")}} element's {{SVGAttr("y")}} filter primitive attribute value. The attribute is a [`<length>`](/en-US/docs/Web/SVG/Guides/Content_type#length) or [`<percentage>`](/en-US/docs/Web/SVG/Guides/Content_type#percentage). The `<coordinate>` is a length in the user coordinate system that is the given distance from the origin of the filter along the y-axis. If the `y` attribute is a percent value, the property value is a relative to the height of the filter region in user coordinate system units. The default value is `0`. ## Value diff --git a/files/en-us/web/api/svgfecompositeelement/height/index.md b/files/en-us/web/api/svgfecompositeelement/height/index.md index 3523319b970ad07..23d675245338aab 100644 --- a/files/en-us/web/api/svgfecompositeelement/height/index.md +++ b/files/en-us/web/api/svgfecompositeelement/height/index.md @@ -10,7 +10,7 @@ browser-compat: api.SVGFECompositeElement.height The **`height`** read-only property of the {{domxref("SVGFECompositeElement")}} interface describes the vertical size of an SVG filter primitive as a {{domxref("SVGAnimatedLength")}}. -It reflects the {{SVGElement("feComposite")}} element's {{SVGAttr("height")}} filter primitive attribute. The `<feComposite>` SVG filter primitive combines two input images using a Porter-Duff compositing operation. The attribute is a [`<length>`](/en-US/docs/Web/SVG/Content_type#length) or a [`<percentage>`](/en-US/docs/Web/SVG/Content_type#percentage) relative to the height of the filter region. The default value is `100%`. The property value is a length in user coordinate system units. +It reflects the {{SVGElement("feComposite")}} element's {{SVGAttr("height")}} filter primitive attribute. The `<feComposite>` SVG filter primitive combines two input images using a Porter-Duff compositing operation. The attribute is a [`<length>`](/en-US/docs/Web/SVG/Guides/Content_type#length) or a [`<percentage>`](/en-US/docs/Web/SVG/Guides/Content_type#percentage) relative to the height of the filter region. The default value is `100%`. The property value is a length in user coordinate system units. ## Value diff --git a/files/en-us/web/api/svgfecompositeelement/index.md b/files/en-us/web/api/svgfecompositeelement/index.md index d5bb28683af54be..38557dfaf44fb8d 100644 --- a/files/en-us/web/api/svgfecompositeelement/index.md +++ b/files/en-us/web/api/svgfecompositeelement/index.md @@ -11,57 +11,6 @@ The **`SVGFECompositeElement`** interface corresponds to the {{SVGElement("feCom {{InheritanceDiagram}} -## Constants - -<table class="no-markdown"> - <tbody> - <tr> - <th>Name</th> - <th>Value</th> - <th>Description</th> - </tr> - <tr> - <td><code>SVG_FECOMPOSITE_OPERATOR_UNKNOWN</code></td> - <td>0</td> - <td> - The type is not one of predefined types. It is invalid to attempt to - define a new value of this type or to attempt to switch an existing - value to this type. - </td> - </tr> - <tr> - <td><code>SVG_FECOMPOSITE_OPERATOR_OVER</code></td> - <td>1</td> - <td>Corresponds to the <code>over</code> value.</td> - </tr> - <tr> - <td><code>SVG_FECOMPOSITE_OPERATOR_IN</code></td> - <td>2</td> - <td>Corresponds to the <code>in</code> value.</td> - </tr> - <tr> - <td><code>SVG_FECOMPOSITE_OPERATOR_OUT</code></td> - <td>3</td> - <td>Corresponds to <code>out</code> value.</td> - </tr> - <tr> - <td><code>SVG_FECOMPOSITE_OPERATOR_ATOP</code></td> - <td>4</td> - <td>Corresponds to <code>atop</code> value.</td> - </tr> - <tr> - <td><code>SVG_FECOMPOSITE_OPERATOR_XOR</code></td> - <td>5</td> - <td>Corresponds to <code>xor</code> value.</td> - </tr> - <tr> - <td><code>SVG_FECOMPOSITE_OPERATOR_ARITHMETIC</code></td> - <td>6</td> - <td>Corresponds to <code>arithmetic</code> value.</td> - </tr> - </tbody> -</table> - ## Instance properties _This interface also inherits properties from its parent interface, {{domxref("SVGElement")}}._ @@ -99,6 +48,23 @@ _This interface also inherits properties from its parent interface, {{domxref("S _This interface does not provide any specific methods, but implements those of its parent, {{domxref("SVGElement")}}._ +## Static properties + +- `SVG_FECOMPOSITE_OPERATOR_UNKNOWN` (0) + - : The type is not one of predefined types. It is invalid to attempt to define a new value of this type or to attempt to switch an existing value to this type. +- `SVG_FECOMPOSITE_OPERATOR_OVER` (1) + - : Corresponds to the value `over`. +- `SVG_FECOMPOSITE_OPERATOR_IN` (2) + - : Corresponds to the value `in`. +- `SVG_FECOMPOSITE_OPERATOR_OUT` (3) + - : Corresponds to the value `out`. +- `SVG_FECOMPOSITE_OPERATOR_ATOP` (4) + - : Corresponds to the value `atop`. +- `SVG_FECOMPOSITE_OPERATOR_XOR` (5) + - : Corresponds to the value `xor`. +- `SVG_FECOMPOSITE_OPERATOR_ARITHMETIC` (6) + - : Corresponds to the value `arithmetic`. + ## Specifications {{Specifications}} diff --git a/files/en-us/web/api/svgfecompositeelement/width/index.md b/files/en-us/web/api/svgfecompositeelement/width/index.md index 88fbddb715dcdd6..c294b9bd9c9013e 100644 --- a/files/en-us/web/api/svgfecompositeelement/width/index.md +++ b/files/en-us/web/api/svgfecompositeelement/width/index.md @@ -10,7 +10,7 @@ browser-compat: api.SVGFECompositeElement.width The **`width`** read-only property of the {{domxref("SVGFECompositeElement")}} interface describes the horizontal size of an SVG filter primitive as a {{domxref("SVGAnimatedLength")}}. -It reflects the {{SVGElement("feComposite")}} element's {{SVGAttr("width")}} filter primitive attribute. The `<feComposite>` SVG filter primitive combines two input images using a Porter-Duff compositing operation. The attribute is a [`<length>`](/en-US/docs/Web/SVG/Content_type#length) or a [`<percentage>`](/en-US/docs/Web/SVG/Content_type#percentage) relative to the width of the filter region. The default value is `100%`. The property value is a length in user coordinate system units. +It reflects the {{SVGElement("feComposite")}} element's {{SVGAttr("width")}} filter primitive attribute. The `<feComposite>` SVG filter primitive combines two input images using a Porter-Duff compositing operation. The attribute is a [`<length>`](/en-US/docs/Web/SVG/Guides/Content_type#length) or a [`<percentage>`](/en-US/docs/Web/SVG/Guides/Content_type#percentage) relative to the width of the filter region. The default value is `100%`. The property value is a length in user coordinate system units. ## Value diff --git a/files/en-us/web/api/svgfecompositeelement/x/index.md b/files/en-us/web/api/svgfecompositeelement/x/index.md index 97f5f91a7d22d06..d00b0d524ade65c 100644 --- a/files/en-us/web/api/svgfecompositeelement/x/index.md +++ b/files/en-us/web/api/svgfecompositeelement/x/index.md @@ -10,7 +10,7 @@ browser-compat: api.SVGFECompositeElement.x The **`x`** read-only property of the {{domxref("SVGFECompositeElement")}} interface describes the horizontal coordinate of the position of an SVG filter primitive as a {{domxref("SVGAnimatedLength")}}. -It reflects the {{SVGElement("feComposite")}} element's {{SVGAttr("x")}} filter primitive attribute value. The `<feComposite>` SVG filter primitive combines two input images using a Porter-Duff compositing operation. The attribute is a [`<length>`](/en-US/docs/Web/SVG/Content_type#length) or [`<percentage>`](/en-US/docs/Web/SVG/Content_type#percentage). The `<coordinate>` is a length in the user coordinate system that is the given distance from the origin of the user coordinate system along the x-axis. If the `x` attribute is a percent value, the property value is relative to the width of the filter region in user coordinate system units. The default value is `0`. +It reflects the {{SVGElement("feComposite")}} element's {{SVGAttr("x")}} filter primitive attribute value. The `<feComposite>` SVG filter primitive combines two input images using a Porter-Duff compositing operation. The attribute is a [`<length>`](/en-US/docs/Web/SVG/Guides/Content_type#length) or [`<percentage>`](/en-US/docs/Web/SVG/Guides/Content_type#percentage). The `<coordinate>` is a length in the user coordinate system that is the given distance from the origin of the user coordinate system along the x-axis. If the `x` attribute is a percent value, the property value is relative to the width of the filter region in user coordinate system units. The default value is `0`. ## Value diff --git a/files/en-us/web/api/svgfecompositeelement/y/index.md b/files/en-us/web/api/svgfecompositeelement/y/index.md index acd0e865bf14807..65d82219b69fe22 100644 --- a/files/en-us/web/api/svgfecompositeelement/y/index.md +++ b/files/en-us/web/api/svgfecompositeelement/y/index.md @@ -10,7 +10,7 @@ browser-compat: api.SVGFECompositeElement.y The **`y`** read-only property of the {{domxref("SVGFECompositeElement")}} interface describes the vertical coordinate of the position of an SVG filter primitive as a {{domxref("SVGAnimatedLength")}}. -It reflects the {{SVGElement("feComposite")}} element's {{SVGAttr("y")}} filter primitive attribute value. The `<feComposite>` SVG filter primitive combines two input images using a Porter-Duff compositing operation. The attribute is a [`<length>`](/en-US/docs/Web/SVG/Content_type#length) or [`<percentage>`](/en-US/docs/Web/SVG/Content_type#percentage). The `<coordinate>` is a length in the user coordinate system that is the given distance from the origin of the filter along the y-axis. If the `y` attribute is a percent value, the property value is a relative to the height of the filter region in user coordinate system units. The default value is `0`. +It reflects the {{SVGElement("feComposite")}} element's {{SVGAttr("y")}} filter primitive attribute value. The `<feComposite>` SVG filter primitive combines two input images using a Porter-Duff compositing operation. The attribute is a [`<length>`](/en-US/docs/Web/SVG/Guides/Content_type#length) or [`<percentage>`](/en-US/docs/Web/SVG/Guides/Content_type#percentage). The `<coordinate>` is a length in the user coordinate system that is the given distance from the origin of the filter along the y-axis. If the `y` attribute is a percent value, the property value is a relative to the height of the filter region in user coordinate system units. The default value is `0`. ## Value diff --git a/files/en-us/web/api/svgfeconvolvematrixelement/height/index.md b/files/en-us/web/api/svgfeconvolvematrixelement/height/index.md index 3b9e1d051c9ab33..45588dd21ea76bf 100644 --- a/files/en-us/web/api/svgfeconvolvematrixelement/height/index.md +++ b/files/en-us/web/api/svgfeconvolvematrixelement/height/index.md @@ -10,7 +10,7 @@ browser-compat: api.SVGFEConvolveMatrixElement.height The **`height`** read-only property of the {{domxref("SVGFEConvolveMatrixElement")}} interface describes the vertical size of an SVG filter primitive as a {{domxref("SVGAnimatedLength")}}. -It reflects the {{SVGElement("feConvolveMatrix")}} element's {{SVGAttr("height")}} filter primitive attribute. The `<feConvolveMatrix>` filter applies a matrix convolution effect, combining pixels in the input image with neighboring pixels to produce a convolution effect such as blurring, edge detection, sharpening, embossing or beveling. The attribute is a [`<length>`](/en-US/docs/Web/SVG/Content_type#length) or a [`<percentage>`](/en-US/docs/Web/SVG/Content_type#percentage) relative to the height of the filter region. The default value is `100%`. The property value is a length in user coordinate system units. +It reflects the {{SVGElement("feConvolveMatrix")}} element's {{SVGAttr("height")}} filter primitive attribute. The `<feConvolveMatrix>` filter applies a matrix convolution effect, combining pixels in the input image with neighboring pixels to produce a convolution effect such as blurring, edge detection, sharpening, embossing or beveling. The attribute is a [`<length>`](/en-US/docs/Web/SVG/Guides/Content_type#length) or a [`<percentage>`](/en-US/docs/Web/SVG/Guides/Content_type#percentage) relative to the height of the filter region. The default value is `100%`. The property value is a length in user coordinate system units. ## Value @@ -37,4 +37,4 @@ console.log(verticalSize.baseVal.value); // the `height` value - {{domxref("SVGFEConvolveMatrixElement.width")}} - [CSS filter effects](/en-US/docs/Web/CSS/CSS_filter_effects) module - SVG {{SVGElement("filter")}} element, SVG {{SVGAttr("filter")}} attribute in [SVG](/en-US/docs/Web/SVG) -- [Applying SVG effects to HTML content](/en-US/docs/Web/SVG/Applying_SVG_effects_to_HTML_content) +- [Applying SVG effects to HTML content](/en-US/docs/Web/SVG/Guides/Applying_SVG_effects_to_HTML_content) diff --git a/files/en-us/web/api/svgfeconvolvematrixelement/index.md b/files/en-us/web/api/svgfeconvolvematrixelement/index.md index da8d8a271e8373b..6f36ce01a18fa78 100644 --- a/files/en-us/web/api/svgfeconvolvematrixelement/index.md +++ b/files/en-us/web/api/svgfeconvolvematrixelement/index.md @@ -11,42 +11,6 @@ The **`SVGFEConvolveMatrixElement`** interface corresponds to the {{SVGElement(" {{InheritanceDiagram}} -## Constants - -<table class="no-markdown"> - <tbody> - <tr> - <th>Name</th> - <th>Value</th> - <th>Description</th> - </tr> - <tr> - <td><code>SVG_EDGEMODE_UNKNOWN</code></td> - <td>0</td> - <td> - The type is not one of predefined types. It is invalid to attempt to - define a new value of this type or to attempt to switch an existing - value to this type. - </td> - </tr> - <tr> - <td><code>SVG_EDGEMODE_DUPLICATE</code></td> - <td>1</td> - <td>Corresponds to the <code>duplicate</code> value.</td> - </tr> - <tr> - <td><code>SVG_EDGEMODE_WRAP</code></td> - <td>2</td> - <td>Corresponds to the <code>wrap</code> value.</td> - </tr> - <tr> - <td><code>SVG_EDGEMODE_NONE</code></td> - <td>3</td> - <td>Corresponds to <code>none</code> value.</td> - </tr> - </tbody> -</table> - ## Instance properties _This interface also inherits properties from its parent interface, {{domxref("SVGElement")}}._ @@ -90,6 +54,17 @@ _This interface also inherits properties from its parent interface, {{domxref("S _This interface does not provide any specific methods, but implements those of its parent, {{domxref("SVGElement")}}._ +## Static properties + +- `SVG_EDGEMODE_UNKNOWN` (0) + - : The type is not one of predefined types. It is invalid to attempt to define a new value of this type or to attempt to switch an existing value to this type. +- `SVG_EDGEMODE_DUPLICATE` (1) + - : Corresponds to the value `duplicate`. +- `SVG_EDGEMODE_WRAP` (2) + - : Corresponds to the value `wrap`. +- `SVG_EDGEMODE_NONE` (3) + - : Corresponds to the value `none`. + ## Specifications {{Specifications}} diff --git a/files/en-us/web/api/svgfeconvolvematrixelement/result/index.md b/files/en-us/web/api/svgfeconvolvematrixelement/result/index.md index 2a4f4a86f86d44b..d150c0576a1f518 100644 --- a/files/en-us/web/api/svgfeconvolvematrixelement/result/index.md +++ b/files/en-us/web/api/svgfeconvolvematrixelement/result/index.md @@ -42,4 +42,4 @@ console.log(filterName.baseVal); // the filter's assigned name - {{cssxref("custom-ident")}} data type - [CSS filter effects](/en-US/docs/Web/CSS/CSS_filter_effects) module - SVG {{SVGElement("filter")}} element, SVG {{SVGAttr("filter")}} attribute in [SVG](/en-US/docs/Web/SVG) -- [Applying SVG effects to HTML content](/en-US/docs/Web/SVG/Applying_SVG_effects_to_HTML_content) +- [Applying SVG effects to HTML content](/en-US/docs/Web/SVG/Guides/Applying_SVG_effects_to_HTML_content) diff --git a/files/en-us/web/api/svgfeconvolvematrixelement/width/index.md b/files/en-us/web/api/svgfeconvolvematrixelement/width/index.md index e8536ee3b5f5a65..5214fd79890c86a 100644 --- a/files/en-us/web/api/svgfeconvolvematrixelement/width/index.md +++ b/files/en-us/web/api/svgfeconvolvematrixelement/width/index.md @@ -10,7 +10,7 @@ browser-compat: api.SVGFEConvolveMatrixElement.width The **`width`** read-only property of the {{domxref("SVGFEConvolveMatrixElement")}} interface describes the horizontal size of an SVG filter primitive as a {{domxref("SVGAnimatedLength")}}. -It reflects the {{SVGElement("feConvolveMatrix")}} element's {{SVGAttr("width")}} filter primitive attribute. The `<feConvolveMatrix>` filter applies a matrix convolution effect, combining pixels in the input image with neighboring pixels to produce a convolution effect such as blurring, edge detection, sharpening, embossing or beveling. The attribute is a [`<length>`](/en-US/docs/Web/SVG/Content_type#length) or a [`<percentage>`](/en-US/docs/Web/SVG/Content_type#percentage) relative to the width of the filter region. The default value is `100%`. The property value is a length in user coordinate system units. +It reflects the {{SVGElement("feConvolveMatrix")}} element's {{SVGAttr("width")}} filter primitive attribute. The `<feConvolveMatrix>` filter applies a matrix convolution effect, combining pixels in the input image with neighboring pixels to produce a convolution effect such as blurring, edge detection, sharpening, embossing or beveling. The attribute is a [`<length>`](/en-US/docs/Web/SVG/Guides/Content_type#length) or a [`<percentage>`](/en-US/docs/Web/SVG/Guides/Content_type#percentage) relative to the width of the filter region. The default value is `100%`. The property value is a length in user coordinate system units. ## Value @@ -37,4 +37,4 @@ console.log(horizontalSize.baseVal.value); // the `width` value - {{domxref("SVGFEConvolveMatrixElement.height")}} - [CSS filter effects](/en-US/docs/Web/CSS/CSS_filter_effects) module - SVG {{SVGElement("filter")}} element, SVG {{SVGAttr("filter")}} attribute in [SVG](/en-US/docs/Web/SVG) -- [Applying SVG effects to HTML content](/en-US/docs/Web/SVG/Applying_SVG_effects_to_HTML_content) +- [Applying SVG effects to HTML content](/en-US/docs/Web/SVG/Guides/Applying_SVG_effects_to_HTML_content) diff --git a/files/en-us/web/api/svgfeconvolvematrixelement/x/index.md b/files/en-us/web/api/svgfeconvolvematrixelement/x/index.md index 5406b606c5ca00e..39e15b5820eff0f 100644 --- a/files/en-us/web/api/svgfeconvolvematrixelement/x/index.md +++ b/files/en-us/web/api/svgfeconvolvematrixelement/x/index.md @@ -10,7 +10,7 @@ browser-compat: api.SVGFEConvolveMatrixElement.x The **`x`** read-only property of the {{domxref("SVGFEConvolveMatrixElement")}} interface describes the horizontal coordinate of the position of an SVG filter primitive as a {{domxref("SVGAnimatedLength")}}. -It reflects the {{SVGElement("feConvolveMatrix")}} element's {{SVGAttr("x")}} filter primitive attribute value. The `<feConvolveMatrix>` filter applies a matrix convolution effect, combining pixels in the input image with neighboring pixels to produce a convolution effect such as blurring, edge detection, sharpening, embossing or beveling. The attribute is a [`<length>`](/en-US/docs/Web/SVG/Content_type#length) or [`<percentage>`](/en-US/docs/Web/SVG/Content_type#percentage). The `<coordinate>` is a length in the user coordinate system that is the given distance from the origin of the user coordinate system along the x-axis. If the `x` attribute is a percent value, the property value is relative to the width of the filter region in user coordinate system units. The default value is `0`. +It reflects the {{SVGElement("feConvolveMatrix")}} element's {{SVGAttr("x")}} filter primitive attribute value. The `<feConvolveMatrix>` filter applies a matrix convolution effect, combining pixels in the input image with neighboring pixels to produce a convolution effect such as blurring, edge detection, sharpening, embossing or beveling. The attribute is a [`<length>`](/en-US/docs/Web/SVG/Guides/Content_type#length) or [`<percentage>`](/en-US/docs/Web/SVG/Guides/Content_type#percentage). The `<coordinate>` is a length in the user coordinate system that is the given distance from the origin of the user coordinate system along the x-axis. If the `x` attribute is a percent value, the property value is relative to the width of the filter region in user coordinate system units. The default value is `0`. ## Value @@ -37,4 +37,4 @@ console.log(leftPosition.baseVal.value); // the `x` value - {{domxref("SVGFEConvolveMatrixElement.y")}} - [CSS filter effects](/en-US/docs/Web/CSS/CSS_filter_effects) module - SVG {{SVGElement("filter")}} element, SVG {{SVGAttr("filter")}} attribute in [SVG](/en-US/docs/Web/SVG) -- [Applying SVG effects to HTML content](/en-US/docs/Web/SVG/Applying_SVG_effects_to_HTML_content) +- [Applying SVG effects to HTML content](/en-US/docs/Web/SVG/Guides/Applying_SVG_effects_to_HTML_content) diff --git a/files/en-us/web/api/svgfeconvolvematrixelement/y/index.md b/files/en-us/web/api/svgfeconvolvematrixelement/y/index.md index 5bfb2af928847e2..03fd4baadc14216 100644 --- a/files/en-us/web/api/svgfeconvolvematrixelement/y/index.md +++ b/files/en-us/web/api/svgfeconvolvematrixelement/y/index.md @@ -12,7 +12,7 @@ The **`y`** read-only property of the {{domxref("SVGFEConvolveMatrixElement")}} It reflects the {{SVGElement("feConvolveMatrix")}} element's {{SVGAttr("y")}} filter primitive attribute value. The `<feConvolveMatrix>` filter applies a matrix convolution effect, combining pixels in the input image with neighboring pixels to produce a convolution effect such as blurring, edge detection, sharpening, embossing or beveling. -The attribute is a [`<length>`](/en-US/docs/Web/SVG/Content_type#length) or [`<percentage>`](/en-US/docs/Web/SVG/Content_type#percentage). The `<coordinate>` is a length in the user coordinate system that is the given distance from the origin of the filter along the y-axis. If the `y` attribute is a percent value, the property value is a relative to the height of the filter region in user coordinate system units. The default value is `0`. +The attribute is a [`<length>`](/en-US/docs/Web/SVG/Guides/Content_type#length) or [`<percentage>`](/en-US/docs/Web/SVG/Guides/Content_type#percentage). The `<coordinate>` is a length in the user coordinate system that is the given distance from the origin of the filter along the y-axis. If the `y` attribute is a percent value, the property value is a relative to the height of the filter region in user coordinate system units. The default value is `0`. ## Value @@ -39,4 +39,4 @@ console.log(topPosition.baseVal.value); // the `y` value - {{domxref("SVGFEConvolveMatrixElement.x")}} - [CSS filter effects](/en-US/docs/Web/CSS/CSS_filter_effects) module - SVG {{SVGElement("filter")}} element, SVG {{SVGAttr("filter")}} attribute in [SVG](/en-US/docs/Web/SVG) -- [Applying SVG effects to HTML content](/en-US/docs/Web/SVG/Applying_SVG_effects_to_HTML_content) +- [Applying SVG effects to HTML content](/en-US/docs/Web/SVG/Guides/Applying_SVG_effects_to_HTML_content) diff --git a/files/en-us/web/api/svgfediffuselightingelement/height/index.md b/files/en-us/web/api/svgfediffuselightingelement/height/index.md index 16d2cdcfe38261f..541bf350ca0248b 100644 --- a/files/en-us/web/api/svgfediffuselightingelement/height/index.md +++ b/files/en-us/web/api/svgfediffuselightingelement/height/index.md @@ -10,7 +10,7 @@ browser-compat: api.SVGFEDiffuseLightingElement.height The **`height`** read-only property of the {{domxref("SVGFEDiffuseLightingElement")}} interface describes the vertical size of an SVG filter primitive as a {{domxref("SVGAnimatedLength")}}. -It reflects the {{SVGElement("feDiffuseLighting")}} element's {{SVGAttr("height")}} filter primitive attribute. The filter lights an image using the alpha channel as a bump map. The attribute is a [`<length>`](/en-US/docs/Web/SVG/Content_type#length) or a [`<percentage>`](/en-US/docs/Web/SVG/Content_type#percentage) relative to the height of the filter region. The default value is `100%`. The property value is a length in user coordinate system units. +It reflects the {{SVGElement("feDiffuseLighting")}} element's {{SVGAttr("height")}} filter primitive attribute. The filter lights an image using the alpha channel as a bump map. The attribute is a [`<length>`](/en-US/docs/Web/SVG/Guides/Content_type#length) or a [`<percentage>`](/en-US/docs/Web/SVG/Guides/Content_type#percentage) relative to the height of the filter region. The default value is `100%`. The property value is a length in user coordinate system units. ## Value diff --git a/files/en-us/web/api/svgfediffuselightingelement/width/index.md b/files/en-us/web/api/svgfediffuselightingelement/width/index.md index 931670b8b6f512b..7de6f4963f603e2 100644 --- a/files/en-us/web/api/svgfediffuselightingelement/width/index.md +++ b/files/en-us/web/api/svgfediffuselightingelement/width/index.md @@ -10,7 +10,7 @@ browser-compat: api.SVGFEDiffuseLightingElement.width The **`width`** read-only property of the {{domxref("SVGFEDiffuseLightingElement")}} interface describes the horizontal size of an SVG filter primitive as a {{domxref("SVGAnimatedLength")}}. -It reflects the {{SVGElement("feDiffuseLighting")}} element's {{SVGAttr("width")}} filter primitive attribute. The filter lights an image using the alpha channel as a bump map. The attribute is a [`<length>`](/en-US/docs/Web/SVG/Content_type#length) or a [`<percentage>`](/en-US/docs/Web/SVG/Content_type#percentage) relative to the width of the filter region. The default value is `100%`. The property value is a length in user coordinate system units. +It reflects the {{SVGElement("feDiffuseLighting")}} element's {{SVGAttr("width")}} filter primitive attribute. The filter lights an image using the alpha channel as a bump map. The attribute is a [`<length>`](/en-US/docs/Web/SVG/Guides/Content_type#length) or a [`<percentage>`](/en-US/docs/Web/SVG/Guides/Content_type#percentage) relative to the width of the filter region. The default value is `100%`. The property value is a length in user coordinate system units. ## Value diff --git a/files/en-us/web/api/svgfediffuselightingelement/x/index.md b/files/en-us/web/api/svgfediffuselightingelement/x/index.md index b7f6f4e9a3e9e11..43c438dd515b8c7 100644 --- a/files/en-us/web/api/svgfediffuselightingelement/x/index.md +++ b/files/en-us/web/api/svgfediffuselightingelement/x/index.md @@ -10,7 +10,7 @@ browser-compat: api.SVGFEDiffuseLightingElement.x The **`x`** read-only property of the {{domxref("SVGFEDiffuseLightingElement")}} interface describes the horizontal coordinate of the position of an SVG filter primitive as a {{domxref("SVGAnimatedLength")}}. -It reflects the {{SVGElement("feDiffuseLighting")}} element's {{SVGAttr("x")}} filter primitive attribute value. The filter lights an image using the alpha channel as a bump map. The attribute is a [`<length>`](/en-US/docs/Web/SVG/Content_type#length) or [`<percentage>`](/en-US/docs/Web/SVG/Content_type#percentage). The `<coordinate>` is a length in the user coordinate system that is the given distance from the origin of the user coordinate system along the x-axis. If the `x` attribute is a percent value, the property value is relative to the width of the filter region in user coordinate system units. The default value is `0`. +It reflects the {{SVGElement("feDiffuseLighting")}} element's {{SVGAttr("x")}} filter primitive attribute value. The filter lights an image using the alpha channel as a bump map. The attribute is a [`<length>`](/en-US/docs/Web/SVG/Guides/Content_type#length) or [`<percentage>`](/en-US/docs/Web/SVG/Guides/Content_type#percentage). The `<coordinate>` is a length in the user coordinate system that is the given distance from the origin of the user coordinate system along the x-axis. If the `x` attribute is a percent value, the property value is relative to the width of the filter region in user coordinate system units. The default value is `0`. ## Value diff --git a/files/en-us/web/api/svgfediffuselightingelement/y/index.md b/files/en-us/web/api/svgfediffuselightingelement/y/index.md index a0ed7f21d3c3df1..37d2de1fdc5689b 100644 --- a/files/en-us/web/api/svgfediffuselightingelement/y/index.md +++ b/files/en-us/web/api/svgfediffuselightingelement/y/index.md @@ -10,7 +10,7 @@ browser-compat: api.SVGFEDiffuseLightingElement.y The **`y`** read-only property of the {{domxref("SVGFEDiffuseLightingElement")}} interface describes the vertical coordinate of the position of an SVG filter primitive as a {{domxref("SVGAnimatedLength")}}. -It reflects the {{SVGElement("feDiffuseLighting")}} element's {{SVGAttr("y")}} filter primitive attribute value. The filter lights an image using the alpha channel as a bump map. The attribute is a [`<length>`](/en-US/docs/Web/SVG/Content_type#length) or [`<percentage>`](/en-US/docs/Web/SVG/Content_type#percentage). The `<coordinate>` is a length in the user coordinate system that is the given distance from the origin of the filter along the y-axis. If the `y` attribute is a percent value, the property value is a relative to the height of the filter region in user coordinate system units. The default value is `0`. +It reflects the {{SVGElement("feDiffuseLighting")}} element's {{SVGAttr("y")}} filter primitive attribute value. The filter lights an image using the alpha channel as a bump map. The attribute is a [`<length>`](/en-US/docs/Web/SVG/Guides/Content_type#length) or [`<percentage>`](/en-US/docs/Web/SVG/Guides/Content_type#percentage). The `<coordinate>` is a length in the user coordinate system that is the given distance from the origin of the filter along the y-axis. If the `y` attribute is a percent value, the property value is a relative to the height of the filter region in user coordinate system units. The default value is `0`. ## Value diff --git a/files/en-us/web/api/svgfedisplacementmapelement/height/index.md b/files/en-us/web/api/svgfedisplacementmapelement/height/index.md index 3fc5ae24321b7ba..6acf823b2503061 100644 --- a/files/en-us/web/api/svgfedisplacementmapelement/height/index.md +++ b/files/en-us/web/api/svgfedisplacementmapelement/height/index.md @@ -10,7 +10,7 @@ browser-compat: api.SVGFEDisplacementMapElement.height The **`height`** read-only property of the {{domxref("SVGFEDisplacementMapElement")}} interface describes the vertical size of an SVG filter primitive as a {{domxref("SVGAnimatedLength")}}. -It reflects the {{SVGElement("feDisplacementMap")}} element's {{SVGAttr("height")}} filter primitive attribute. The attribute is a [`<length>`](/en-US/docs/Web/SVG/Content_type#length) or a [`<percentage>`](/en-US/docs/Web/SVG/Content_type#percentage) relative to the height of the filter region. The default value is `100%`. The property value is a length in user coordinate system units. +It reflects the {{SVGElement("feDisplacementMap")}} element's {{SVGAttr("height")}} filter primitive attribute. The attribute is a [`<length>`](/en-US/docs/Web/SVG/Guides/Content_type#length) or a [`<percentage>`](/en-US/docs/Web/SVG/Guides/Content_type#percentage) relative to the height of the filter region. The default value is `100%`. The property value is a length in user coordinate system units. ## Value diff --git a/files/en-us/web/api/svgfedisplacementmapelement/index.md b/files/en-us/web/api/svgfedisplacementmapelement/index.md index a6381c5d4b9966d..34113788e9169a0 100644 --- a/files/en-us/web/api/svgfedisplacementmapelement/index.md +++ b/files/en-us/web/api/svgfedisplacementmapelement/index.md @@ -11,47 +11,6 @@ The **`SVGFEDisplacementMapElement`** interface corresponds to the {{SVGElement( {{InheritanceDiagram}} -## Constants - -<table class="no-markdown"> - <tbody> - <tr> - <th>Name</th> - <th>Value</th> - <th>Description</th> - </tr> - <tr> - <td><code>SVG_CHANNEL_UNKNOWN</code></td> - <td>0</td> - <td> - The type is not one of predefined types. It is invalid to attempt to - define a new value of this type or to attempt to switch an existing - value to this type. - </td> - </tr> - <tr> - <td><code>SVG_CHANNEL_R</code></td> - <td>1</td> - <td>Corresponds to the <code>R</code> value.</td> - </tr> - <tr> - <td><code>SVG_CHANNEL_G</code></td> - <td>2</td> - <td>Corresponds to the <code>G</code> value.</td> - </tr> - <tr> - <td><code>SVG_CHANNEL_B</code></td> - <td>3</td> - <td>Corresponds to the <code>B</code> value.</td> - </tr> - <tr> - <td><code>SVG_CHANNEL_A</code></td> - <td>4</td> - <td>Corresponds to the <code>A</code> value.</td> - </tr> - </tbody> -</table> - ## Instance properties _This interface also inherits properties from its parent interface, {{domxref("SVGElement")}}._ @@ -81,6 +40,19 @@ _This interface also inherits properties from its parent interface, {{domxref("S _This interface does not provide any specific methods, but implements those of its parent, {{domxref("SVGElement")}}._ +## Static properties + +- `SVG_CHANNEL_UNKNOWN` (0) + - : The type is not one of predefined types. It is invalid to attempt to define a new value of this type or to attempt to switch an existing value to this type. +- `SVG_CHANNEL_R` (1) + - : Corresponds to the value `R`. +- `SVG_CHANNEL_G` (2) + - : Corresponds to the value `G`. +- `SVG_CHANNEL_B` (3) + - : Corresponds to the value `B`. +- `SVG_CHANNEL_A` (4) + - : Corresponds to the value `A`. + ## Specifications {{Specifications}} diff --git a/files/en-us/web/api/svgfedisplacementmapelement/width/index.md b/files/en-us/web/api/svgfedisplacementmapelement/width/index.md index 285b502960bee81..0a6e6e94b124bb5 100644 --- a/files/en-us/web/api/svgfedisplacementmapelement/width/index.md +++ b/files/en-us/web/api/svgfedisplacementmapelement/width/index.md @@ -10,7 +10,7 @@ browser-compat: api.SVGFEDisplacementMapElement.width The **`width`** read-only property of the {{domxref("SVGFEDisplacementMapElement")}} interface describes the horizontal size of an SVG filter primitive as a {{domxref("SVGAnimatedLength")}}. -It reflects the {{SVGElement("feDisplacementMap")}} element's {{SVGAttr("width")}} filter primitive attribute. The attribute is a [`<length>`](/en-US/docs/Web/SVG/Content_type#length) or a [`<percentage>`](/en-US/docs/Web/SVG/Content_type#percentage) relative to the width of the filter region. The default value is `100%`. The property value is a length in user coordinate system units. +It reflects the {{SVGElement("feDisplacementMap")}} element's {{SVGAttr("width")}} filter primitive attribute. The attribute is a [`<length>`](/en-US/docs/Web/SVG/Guides/Content_type#length) or a [`<percentage>`](/en-US/docs/Web/SVG/Guides/Content_type#percentage) relative to the width of the filter region. The default value is `100%`. The property value is a length in user coordinate system units. ## Value diff --git a/files/en-us/web/api/svgfedisplacementmapelement/x/index.md b/files/en-us/web/api/svgfedisplacementmapelement/x/index.md index fc85f9b010a7500..ac8f3b5a54e126a 100644 --- a/files/en-us/web/api/svgfedisplacementmapelement/x/index.md +++ b/files/en-us/web/api/svgfedisplacementmapelement/x/index.md @@ -10,7 +10,7 @@ browser-compat: api.SVGFEDisplacementMapElement.x The **`x`** read-only property of the {{domxref("SVGFEDisplacementMapElement")}} interface describes the horizontal coordinate of the position of an SVG filter primitive as a {{domxref("SVGAnimatedLength")}}. -It reflects the {{SVGElement("feDisplacementMap")}} element's {{SVGAttr("x")}} filter primitive attribute value. The attribute is a [`<length>`](/en-US/docs/Web/SVG/Content_type#length) or [`<percentage>`](/en-US/docs/Web/SVG/Content_type#percentage). The `<coordinate>` is a length in the user coordinate system that is the given distance from the origin of the user coordinate system along the x-axis. If the `x` attribute is a percent value, the property value is relative to the width of the filter region in user coordinate system units. The default value is `0`. +It reflects the {{SVGElement("feDisplacementMap")}} element's {{SVGAttr("x")}} filter primitive attribute value. The attribute is a [`<length>`](/en-US/docs/Web/SVG/Guides/Content_type#length) or [`<percentage>`](/en-US/docs/Web/SVG/Guides/Content_type#percentage). The `<coordinate>` is a length in the user coordinate system that is the given distance from the origin of the user coordinate system along the x-axis. If the `x` attribute is a percent value, the property value is relative to the width of the filter region in user coordinate system units. The default value is `0`. ## Value diff --git a/files/en-us/web/api/svgfedisplacementmapelement/y/index.md b/files/en-us/web/api/svgfedisplacementmapelement/y/index.md index 6b08d6ac16b8030..6f11c4aac6fead6 100644 --- a/files/en-us/web/api/svgfedisplacementmapelement/y/index.md +++ b/files/en-us/web/api/svgfedisplacementmapelement/y/index.md @@ -10,7 +10,7 @@ browser-compat: api.SVGFEDisplacementMapElement.y The **`y`** read-only property of the {{domxref("SVGFEDisplacementMapElement")}} interface describes the vertical coordinate of the position of an SVG filter primitive as a {{domxref("SVGAnimatedLength")}}. -It reflects the {{SVGElement("feDisplacementMap")}} element's {{SVGAttr("y")}} filter primitive attribute value. The attribute is a [`<length>`](/en-US/docs/Web/SVG/Content_type#length) or [`<percentage>`](/en-US/docs/Web/SVG/Content_type#percentage). The `<coordinate>` is a length in the user coordinate system that is the given distance from the origin of the filter along the y-axis. If the `y` attribute is a percent value, the property value is a relative to the height of the filter region in user coordinate system units. The default value is `0`. +It reflects the {{SVGElement("feDisplacementMap")}} element's {{SVGAttr("y")}} filter primitive attribute value. The attribute is a [`<length>`](/en-US/docs/Web/SVG/Guides/Content_type#length) or [`<percentage>`](/en-US/docs/Web/SVG/Guides/Content_type#percentage). The `<coordinate>` is a length in the user coordinate system that is the given distance from the origin of the filter along the y-axis. If the `y` attribute is a percent value, the property value is a relative to the height of the filter region in user coordinate system units. The default value is `0`. ## Value diff --git a/files/en-us/web/api/svgfedropshadowelement/height/index.md b/files/en-us/web/api/svgfedropshadowelement/height/index.md index d5f087cd8a336f4..9684daafb300201 100644 --- a/files/en-us/web/api/svgfedropshadowelement/height/index.md +++ b/files/en-us/web/api/svgfedropshadowelement/height/index.md @@ -10,7 +10,7 @@ browser-compat: api.SVGFEDropShadowElement.height The **`height`** read-only property of the {{domxref("SVGFEDropShadowElement")}} interface describes the vertical size of an SVG filter primitive as a {{domxref("SVGAnimatedLength")}}. -It reflects the {{SVGAttr("height")}} filter primitive attribute. The attribute is a [`<length>`](/en-US/docs/Web/SVG/Content_type#length) or a [`<percentage>`](/en-US/docs/Web/SVG/Content_type#percentage) relative to the height of the filter region. The default value is `100%`. The property value is a length in user coordinate system units. +It reflects the {{SVGAttr("height")}} filter primitive attribute. The attribute is a [`<length>`](/en-US/docs/Web/SVG/Guides/Content_type#length) or a [`<percentage>`](/en-US/docs/Web/SVG/Guides/Content_type#percentage) relative to the height of the filter region. The default value is `100%`. The property value is a length in user coordinate system units. ## Value diff --git a/files/en-us/web/api/svgfedropshadowelement/width/index.md b/files/en-us/web/api/svgfedropshadowelement/width/index.md index d698a58b79e7281..c358624da5d910d 100644 --- a/files/en-us/web/api/svgfedropshadowelement/width/index.md +++ b/files/en-us/web/api/svgfedropshadowelement/width/index.md @@ -10,7 +10,7 @@ browser-compat: api.SVGFEDropShadowElement.width The **`width`** read-only property of the {{domxref("SVGFEDropShadowElement")}} interface describes the horizontal size of an SVG filter primitive as a {{domxref("SVGAnimatedLength")}}. -It reflects the {{SVGAttr("width")}} filter primitive attribute. The attribute is a [`<length>`](/en-US/docs/Web/SVG/Content_type#length) or a [`<percentage>`](/en-US/docs/Web/SVG/Content_type#percentage) relative to the width of the filter region. The default value is `100%`. The property value is a length in user coordinate system units. +It reflects the {{SVGAttr("width")}} filter primitive attribute. The attribute is a [`<length>`](/en-US/docs/Web/SVG/Guides/Content_type#length) or a [`<percentage>`](/en-US/docs/Web/SVG/Guides/Content_type#percentage) relative to the width of the filter region. The default value is `100%`. The property value is a length in user coordinate system units. ## Value diff --git a/files/en-us/web/api/svgfedropshadowelement/x/index.md b/files/en-us/web/api/svgfedropshadowelement/x/index.md index 0f90d3d2a9b177a..9a6d4ceb2c9dc64 100644 --- a/files/en-us/web/api/svgfedropshadowelement/x/index.md +++ b/files/en-us/web/api/svgfedropshadowelement/x/index.md @@ -10,7 +10,7 @@ browser-compat: api.SVGFEDropShadowElement.x The **`x`** read-only property of the {{domxref("SVGFEDropShadowElement")}} interface describes the horizontal coordinate of the position of an SVG filter primitive as a {{domxref("SVGAnimatedLength")}}. -It reflects the {{SVGAttr("x")}} attribute of the {{SVGElement("feDropShadow")}} element, which creates a drop shadow of an input image. The attribute is a [`<length>`](/en-US/docs/Web/SVG/Content_type#length) or [`<percentage>`](/en-US/docs/Web/SVG/Content_type#percentage). The `<coordinate>` is a length in the user coordinate system that is the given distance from the origin of the user coordinate system along the x-axis. If the `x` attribute is a percent value, the property value is relative to the width of the filter region in user coordinate system units. +It reflects the {{SVGAttr("x")}} attribute of the {{SVGElement("feDropShadow")}} element, which creates a drop shadow of an input image. The attribute is a [`<length>`](/en-US/docs/Web/SVG/Guides/Content_type#length) or [`<percentage>`](/en-US/docs/Web/SVG/Guides/Content_type#percentage). The `<coordinate>` is a length in the user coordinate system that is the given distance from the origin of the user coordinate system along the x-axis. If the `x` attribute is a percent value, the property value is relative to the width of the filter region in user coordinate system units. ## Value diff --git a/files/en-us/web/api/svgfedropshadowelement/y/index.md b/files/en-us/web/api/svgfedropshadowelement/y/index.md index 10bfd64d6c65192..088047af573dcff 100644 --- a/files/en-us/web/api/svgfedropshadowelement/y/index.md +++ b/files/en-us/web/api/svgfedropshadowelement/y/index.md @@ -10,7 +10,7 @@ browser-compat: api.SVGFEDropShadowElement.y The **`y`** read-only property of the {{domxref("SVGFEDropShadowElement")}} interface describes the vertical coordinate of the position of an SVG filter primitive as a {{domxref("SVGAnimatedLength")}}. -It reflects the {{SVGAttr("y")}} attribute of the {{SVGElement("feDropShadow")}} element, which creates a drop shadow of an input image. The attribute is a [`<length>`](/en-US/docs/Web/SVG/Content_type#length) or [`<percentage>`](/en-US/docs/Web/SVG/Content_type#percentage). The `<coordinate>` is a length in the user coordinate system that is the given distance from the origin of the filter along the y-axis. If the `y` attribute is a percent value, the property value is a relative to the height of the filter region in user coordinate system units. The default value is `0`. +It reflects the {{SVGAttr("y")}} attribute of the {{SVGElement("feDropShadow")}} element, which creates a drop shadow of an input image. The attribute is a [`<length>`](/en-US/docs/Web/SVG/Guides/Content_type#length) or [`<percentage>`](/en-US/docs/Web/SVG/Guides/Content_type#percentage). The `<coordinate>` is a length in the user coordinate system that is the given distance from the origin of the filter along the y-axis. If the `y` attribute is a percent value, the property value is a relative to the height of the filter region in user coordinate system units. The default value is `0`. ## Value diff --git a/files/en-us/web/api/svgfefloodelement/height/index.md b/files/en-us/web/api/svgfefloodelement/height/index.md index f935e4e67b6829b..c0c0a5fe41e80c7 100644 --- a/files/en-us/web/api/svgfefloodelement/height/index.md +++ b/files/en-us/web/api/svgfefloodelement/height/index.md @@ -10,7 +10,7 @@ browser-compat: api.SVGFEFloodElement.height The **`height`** read-only property of the {{domxref("SVGFEFloodElement")}} interface describes the vertical size of an SVG filter primitive as a {{domxref("SVGAnimatedLength")}}. -It reflects the {{SVGAttr("height")}} attribute of the {{SVGElement("feFlood")}} element, which fills an SVG filter subregion with the color and opacity defined by {{SVGAttr("flood-color")}} and {{SVGAttr("flood-opacity")}}. The attribute is a [`<length>`](/en-US/docs/Web/SVG/Content_type#length) or a [`<percentage>`](/en-US/docs/Web/SVG/Content_type#percentage) relative to the height of the filter region. The default value is `100%`. The property value is a length in user coordinate system units. +It reflects the {{SVGAttr("height")}} attribute of the {{SVGElement("feFlood")}} element, which fills an SVG filter subregion with the color and opacity defined by {{SVGAttr("flood-color")}} and {{SVGAttr("flood-opacity")}}. The attribute is a [`<length>`](/en-US/docs/Web/SVG/Guides/Content_type#length) or a [`<percentage>`](/en-US/docs/Web/SVG/Guides/Content_type#percentage) relative to the height of the filter region. The default value is `100%`. The property value is a length in user coordinate system units. ## Value @@ -34,6 +34,7 @@ console.log(verticalSize.baseVal.value); // the `height` value ## See also -- {{domxref("SVGFEFloodElement.width")}}- [SVG filter tutorial](/en-US/docs/Web/SVG/Tutorial/SVG_Filters_Tutorial) +- {{domxref("SVGFEFloodElement.width")}} +- [SVG filter tutorial](/en-US/docs/Web/SVG/Guides/SVG_filters) - CSS {{cssxref("blend-mode")}} data type - CSS {{cssxref("mix-blend-mode")}} property diff --git a/files/en-us/web/api/svgfefloodelement/result/index.md b/files/en-us/web/api/svgfefloodelement/result/index.md index 804bbd5873981d8..612f2a6da47a0bb 100644 --- a/files/en-us/web/api/svgfefloodelement/result/index.md +++ b/files/en-us/web/api/svgfefloodelement/result/index.md @@ -36,7 +36,7 @@ console.log(filterName.baseVa); // the filter's assigned name ## See also -- {{domxref("SVGFEFloodElement.in1")}} -- {{cssxref("custom-ident")}} data type- [SVG filter tutorial](/en-US/docs/Web/SVG/Tutorial/SVG_Filters_Tutorial) +- {{cssxref("custom-ident")}} data type +- [SVG filter tutorial](/en-US/docs/Web/SVG/Guides/SVG_filters) - CSS {{cssxref("blend-mode")}} data type - CSS {{cssxref("mix-blend-mode")}} property diff --git a/files/en-us/web/api/svgfefloodelement/width/index.md b/files/en-us/web/api/svgfefloodelement/width/index.md index d5a079a6e13c514..6c8f392f714b830 100644 --- a/files/en-us/web/api/svgfefloodelement/width/index.md +++ b/files/en-us/web/api/svgfefloodelement/width/index.md @@ -10,7 +10,7 @@ browser-compat: api.SVGFEFloodElement.width The **`width`** read-only property of the {{domxref("SVGFEFloodElement")}} interface describes the horizontal size of an SVG filter primitive as a {{domxref("SVGAnimatedLength")}}. -It reflects the {{SVGAttr("width")}} attribute of the {{SVGElement("feFlood")}} element, which fills an SVG filter subregion with the color and opacity defined by {{SVGAttr("flood-color")}} and {{SVGAttr("flood-opacity")}}. The attribute is a [`<length>`](/en-US/docs/Web/SVG/Content_type#length) or a [`<percentage>`](/en-US/docs/Web/SVG/Content_type#percentage) relative to the width of the filter region. The default value is `100%`. The property value is a length in user coordinate system units. +It reflects the {{SVGAttr("width")}} attribute of the {{SVGElement("feFlood")}} element, which fills an SVG filter subregion with the color and opacity defined by {{SVGAttr("flood-color")}} and {{SVGAttr("flood-opacity")}}. The attribute is a [`<length>`](/en-US/docs/Web/SVG/Guides/Content_type#length) or a [`<percentage>`](/en-US/docs/Web/SVG/Guides/Content_type#percentage) relative to the width of the filter region. The default value is `100%`. The property value is a length in user coordinate system units. ## Value @@ -34,6 +34,7 @@ console.log(horizontalSize.baseVal.value); // the `width` value ## See also -- {{domxref("SVGFEFloodElement.height")}}- [SVG filter tutorial](/en-US/docs/Web/SVG/Tutorial/SVG_Filters_Tutorial) +- {{domxref("SVGFEFloodElement.height")}} +- [SVG filter tutorial](/en-US/docs/Web/SVG/Guides/SVG_filters) - CSS {{cssxref("blend-mode")}} data type - CSS {{cssxref("mix-blend-mode")}} property diff --git a/files/en-us/web/api/svgfefloodelement/x/index.md b/files/en-us/web/api/svgfefloodelement/x/index.md index c673bb66201ef62..17fe8032c1b4e1e 100644 --- a/files/en-us/web/api/svgfefloodelement/x/index.md +++ b/files/en-us/web/api/svgfefloodelement/x/index.md @@ -10,7 +10,7 @@ browser-compat: api.SVGFEFloodElement.x The **`x`** read-only property of the {{domxref("SVGFEFloodElement")}} interface describes the horizontal coordinate of the position of an SVG filter primitive as a {{domxref("SVGAnimatedLength")}}. -It reflects the {{SVGAttr("x")}} attribute of the {{SVGElement("feFlood")}} element, which fills an SVG filter subregion with the color and opacity defined by {{SVGAttr("flood-color")}} and {{SVGAttr("flood-opacity")}}. The attribute is a [`<length>`](/en-US/docs/Web/SVG/Content_type#length) or [`<percentage>`](/en-US/docs/Web/SVG/Content_type#percentage). The `<coordinate>` is a length in the user coordinate system that is the given distance from the origin of the user coordinate system along the x-axis. If the `x` attribute is a percent value, the property value is relative to the width of the filter region in user coordinate system units. The default value is `0`. +It reflects the {{SVGAttr("x")}} attribute of the {{SVGElement("feFlood")}} element, which fills an SVG filter subregion with the color and opacity defined by {{SVGAttr("flood-color")}} and {{SVGAttr("flood-opacity")}}. The attribute is a [`<length>`](/en-US/docs/Web/SVG/Guides/Content_type#length) or [`<percentage>`](/en-US/docs/Web/SVG/Guides/Content_type#percentage). The `<coordinate>` is a length in the user coordinate system that is the given distance from the origin of the user coordinate system along the x-axis. If the `x` attribute is a percent value, the property value is relative to the width of the filter region in user coordinate system units. The default value is `0`. ## Value @@ -34,6 +34,7 @@ console.log(leftPosition.baseVal.value); // the `x` value ## See also -- {{domxref("SVGFEFloodElement.y")}}- [SVG filter tutorial](/en-US/docs/Web/SVG/Tutorial/SVG_Filters_Tutorial) +- {{domxref("SVGFEFloodElement.y")}} +- [SVG filter tutorial](/en-US/docs/Web/SVG/Guides/SVG_filters) - CSS {{cssxref("blend-mode")}} data type - CSS {{cssxref("mix-blend-mode")}} property diff --git a/files/en-us/web/api/svgfefloodelement/y/index.md b/files/en-us/web/api/svgfefloodelement/y/index.md index 84a2bb5812d6350..86ccc68ccb2da66 100644 --- a/files/en-us/web/api/svgfefloodelement/y/index.md +++ b/files/en-us/web/api/svgfefloodelement/y/index.md @@ -10,7 +10,7 @@ browser-compat: api.SVGFEFloodElement.y The **`y`** read-only property of the {{domxref("SVGFEFloodElement")}} interface describes the vertical coordinate of the position of an SVG filter primitive as a {{domxref("SVGAnimatedLength")}}. -It reflects the {{SVGAttr("y")}} attribute of the {{SVGElement("feFlood")}} element, which fills an SVG filter subregion with the color and opacity defined by {{SVGAttr("flood-color")}} and {{SVGAttr("flood-opacity")}}. The attribute is a [`<length>`](/en-US/docs/Web/SVG/Content_type#length) or [`<percentage>`](/en-US/docs/Web/SVG/Content_type#percentage). The `<coordinate>` is a length in the user coordinate system that is the given distance from the origin of the filter along the y-axis. If the `y` attribute is a percent value, the property value is relative to the height of the filter region in user coordinate system units. The default value is `0`. +It reflects the {{SVGAttr("y")}} attribute of the {{SVGElement("feFlood")}} element, which fills an SVG filter subregion with the color and opacity defined by {{SVGAttr("flood-color")}} and {{SVGAttr("flood-opacity")}}. The attribute is a [`<length>`](/en-US/docs/Web/SVG/Guides/Content_type#length) or [`<percentage>`](/en-US/docs/Web/SVG/Guides/Content_type#percentage). The `<coordinate>` is a length in the user coordinate system that is the given distance from the origin of the filter along the y-axis. If the `y` attribute is a percent value, the property value is relative to the height of the filter region in user coordinate system units. The default value is `0`. ## Value @@ -34,6 +34,7 @@ console.log(topPosition.baseVal.value); // the `y` value ## See also -- {{domxref("SVGFEFloodElement.x")}}- [SVG filter tutorial](/en-US/docs/Web/SVG/Tutorial/SVG_Filters_Tutorial) +- {{domxref("SVGFEFloodElement.x")}} +- [SVG filter tutorial](/en-US/docs/Web/SVG/Guides/SVG_filters) - CSS {{cssxref("blend-mode")}} data type - CSS {{cssxref("mix-blend-mode")}} property diff --git a/files/en-us/web/api/svgfegaussianblurelement/height/index.md b/files/en-us/web/api/svgfegaussianblurelement/height/index.md index dc2abaeb028750b..07b5258ca184824 100644 --- a/files/en-us/web/api/svgfegaussianblurelement/height/index.md +++ b/files/en-us/web/api/svgfegaussianblurelement/height/index.md @@ -10,7 +10,7 @@ browser-compat: api.SVGFEGaussianBlurElement.height The **`height`** read-only property of the {{domxref("SVGFEGaussianBlurElement")}} interface describes the vertical size of an SVG filter primitive as a {{domxref("SVGAnimatedLength")}}. -It reflects the {{SVGAttr("height")}} attribute of the {{SVGElement("feGaussianBlur")}} element, which blurs an input image. The attribute is a [`<length>`](/en-US/docs/Web/SVG/Content_type#length) or a [`<percentage>`](/en-US/docs/Web/SVG/Content_type#percentage) relative to the height of the filter region. The default value is `100%`. The property value is a length in user coordinate system units. +It reflects the {{SVGAttr("height")}} attribute of the {{SVGElement("feGaussianBlur")}} element, which blurs an input image. The attribute is a [`<length>`](/en-US/docs/Web/SVG/Guides/Content_type#length) or a [`<percentage>`](/en-US/docs/Web/SVG/Guides/Content_type#percentage) relative to the height of the filter region. The default value is `100%`. The property value is a length in user coordinate system units. ## Value @@ -35,7 +35,7 @@ console.log(verticalSize.baseVal.value); // the `height` value ## See also - {{domxref("SVGFEGaussianBlurElement.width")}} -- [SVG filter tutorial](/en-US/docs/Web/SVG/Tutorial/SVG_Filters_Tutorial) +- [SVG filter tutorial](/en-US/docs/Web/SVG/Guides/SVG_filters) - CSS {{cssxref("blend-mode")}} data type - CSS {{cssxref("filter-function/blur", "blur()")}} function - [CSS filter effects](/en-US/docs/Web/CSS/CSS_filter_effects) module- CSS {{cssxref("mix-blend-mode")}} property diff --git a/files/en-us/web/api/svgfegaussianblurelement/result/index.md b/files/en-us/web/api/svgfegaussianblurelement/result/index.md index 3d01fcf8e81b44b..9d4fedf9b052e19 100644 --- a/files/en-us/web/api/svgfegaussianblurelement/result/index.md +++ b/files/en-us/web/api/svgfegaussianblurelement/result/index.md @@ -38,7 +38,7 @@ console.log(filterName.baseVal); // the filter's assigned name - {{domxref("SVGFEGaussianBlurElement.in1")}} - {{cssxref("custom-ident")}} data type -- [SVG filter tutorial](/en-US/docs/Web/SVG/Tutorial/SVG_Filters_Tutorial) +- [SVG filter tutorial](/en-US/docs/Web/SVG/Guides/SVG_filters) - CSS {{cssxref("blend-mode")}} data type - CSS {{cssxref("filter-function/blur", "blur()")}} function - [CSS filter effects](/en-US/docs/Web/CSS/CSS_filter_effects) module- CSS {{cssxref("mix-blend-mode")}} property diff --git a/files/en-us/web/api/svgfegaussianblurelement/width/index.md b/files/en-us/web/api/svgfegaussianblurelement/width/index.md index 0fac3976f3fc340..7f5313d8c8e05d9 100644 --- a/files/en-us/web/api/svgfegaussianblurelement/width/index.md +++ b/files/en-us/web/api/svgfegaussianblurelement/width/index.md @@ -10,7 +10,7 @@ browser-compat: api.SVGFEGaussianBlurElement.width The **`width`** read-only property of the {{domxref("SVGFEGaussianBlurElement")}} interface describes the horizontal size of an SVG filter primitive as a {{domxref("SVGAnimatedLength")}}. -It reflects the {{SVGAttr("width")}} attribute of the {{SVGElement("feGaussianBlur")}} element, which blurs an input image. The attribute is a [`<length>`](/en-US/docs/Web/SVG/Content_type#length) or a [`<percentage>`](/en-US/docs/Web/SVG/Content_type#percentage) relative to the width of the filter region. The default value is `100%`. The property value is a length in user coordinate system units. +It reflects the {{SVGAttr("width")}} attribute of the {{SVGElement("feGaussianBlur")}} element, which blurs an input image. The attribute is a [`<length>`](/en-US/docs/Web/SVG/Guides/Content_type#length) or a [`<percentage>`](/en-US/docs/Web/SVG/Guides/Content_type#percentage) relative to the width of the filter region. The default value is `100%`. The property value is a length in user coordinate system units. ## Value @@ -35,7 +35,7 @@ console.log(horizontalSize.baseVal.value); // the `width` value ## See also - {{domxref("SVGFEGaussianBlurElement.height")}} -- [SVG filter tutorial](/en-US/docs/Web/SVG/Tutorial/SVG_Filters_Tutorial) +- [SVG filter tutorial](/en-US/docs/Web/SVG/Guides/SVG_filters) - CSS {{cssxref("blend-mode")}} data type - CSS {{cssxref("filter-function/blur", "blur()")}} function - [CSS filter effects](/en-US/docs/Web/CSS/CSS_filter_effects) module- CSS {{cssxref("mix-blend-mode")}} property diff --git a/files/en-us/web/api/svgfegaussianblurelement/x/index.md b/files/en-us/web/api/svgfegaussianblurelement/x/index.md index dc482de3e9ecfdf..d0093e9be32cd75 100644 --- a/files/en-us/web/api/svgfegaussianblurelement/x/index.md +++ b/files/en-us/web/api/svgfegaussianblurelement/x/index.md @@ -10,7 +10,7 @@ browser-compat: api.SVGFEGaussianBlurElement.x The **`x`** read-only property of the {{domxref("SVGFEGaussianBlurElement")}} interface describes the horizontal coordinate of the position of an SVG filter primitive as a {{domxref("SVGAnimatedLength")}}. -It reflects the {{SVGAttr("x")}} attribute of the {{SVGElement("feGaussianBlur")}} element, which blurs an input image. The attribute is a [`<length>`](/en-US/docs/Web/SVG/Content_type#length) or [`<percentage>`](/en-US/docs/Web/SVG/Content_type#percentage). The `<coordinate>` is a length in the user coordinate system that is the given distance from the origin of the user coordinate system along the x-axis. If the `x` attribute is a percent value, the property value is relative to the width of the filter region in user coordinate system units. The default value is `0`. +It reflects the {{SVGAttr("x")}} attribute of the {{SVGElement("feGaussianBlur")}} element, which blurs an input image. The attribute is a [`<length>`](/en-US/docs/Web/SVG/Guides/Content_type#length) or [`<percentage>`](/en-US/docs/Web/SVG/Guides/Content_type#percentage). The `<coordinate>` is a length in the user coordinate system that is the given distance from the origin of the user coordinate system along the x-axis. If the `x` attribute is a percent value, the property value is relative to the width of the filter region in user coordinate system units. The default value is `0`. ## Value @@ -35,7 +35,7 @@ console.log(leftPosition.baseVal.value); // the `x` value ## See also - {{domxref("SVGFEGaussianBlurElement.y")}} -- [SVG filter tutorial](/en-US/docs/Web/SVG/Tutorial/SVG_Filters_Tutorial) +- [SVG filter tutorial](/en-US/docs/Web/SVG/Guides/SVG_filters) - CSS {{cssxref("blend-mode")}} data type - CSS {{cssxref("filter-function/blur", "blur()")}} function - [CSS filter effects](/en-US/docs/Web/CSS/CSS_filter_effects) module- CSS {{cssxref("mix-blend-mode")}} property diff --git a/files/en-us/web/api/svgfegaussianblurelement/y/index.md b/files/en-us/web/api/svgfegaussianblurelement/y/index.md index c76a9a2219688fb..213c8aa98dfe4b8 100644 --- a/files/en-us/web/api/svgfegaussianblurelement/y/index.md +++ b/files/en-us/web/api/svgfegaussianblurelement/y/index.md @@ -10,7 +10,7 @@ browser-compat: api.SVGFEGaussianBlurElement.y The **`y`** read-only property of the {{domxref("SVGFEGaussianBlurElement")}} interface describes the vertical coordinate of the position of an SVG filter primitive as a {{domxref("SVGAnimatedLength")}}. -It reflects the {{SVGAttr("y")}} attribute of the {{SVGElement("feGaussianBlur")}} element, which blurs an input image. The attribute is a [`<length>`](/en-US/docs/Web/SVG/Content_type#length) or [`<percentage>`](/en-US/docs/Web/SVG/Content_type#percentage). The `<coordinate>` is a length in the user coordinate system that is the given distance from the origin of the filter along the y-axis. If the `y` attribute is a percent value, the property value is relative to the height of the filter region in user coordinate system units. The default value is `0`. +It reflects the {{SVGAttr("y")}} attribute of the {{SVGElement("feGaussianBlur")}} element, which blurs an input image. The attribute is a [`<length>`](/en-US/docs/Web/SVG/Guides/Content_type#length) or [`<percentage>`](/en-US/docs/Web/SVG/Guides/Content_type#percentage). The `<coordinate>` is a length in the user coordinate system that is the given distance from the origin of the filter along the y-axis. If the `y` attribute is a percent value, the property value is relative to the height of the filter region in user coordinate system units. The default value is `0`. ## Value @@ -35,7 +35,7 @@ console.log(topPosition.baseVal.value); // the `y` value ## See also - {{domxref("SVGFEGaussianBlurElement.x")}} -- [SVG filter tutorial](/en-US/docs/Web/SVG/Tutorial/SVG_Filters_Tutorial) +- [SVG filter tutorial](/en-US/docs/Web/SVG/Guides/SVG_filters) - CSS {{cssxref("blend-mode")}} data type - CSS {{cssxref("filter-function/blur", "blur()")}} function - [CSS filter effects](/en-US/docs/Web/CSS/CSS_filter_effects) module- CSS {{cssxref("mix-blend-mode")}} property diff --git a/files/en-us/web/api/svgfeimageelement/height/index.md b/files/en-us/web/api/svgfeimageelement/height/index.md index 2c47ea0376016dd..579e2819e5f5483 100644 --- a/files/en-us/web/api/svgfeimageelement/height/index.md +++ b/files/en-us/web/api/svgfeimageelement/height/index.md @@ -10,7 +10,7 @@ browser-compat: api.SVGFEImageElement.height The **`height`** read-only property of the {{domxref("SVGFEImageElement")}} interface describes the vertical size of an SVG filter primitive as a {{domxref("SVGAnimatedLength")}}. -It reflects the {{SVGAttr("height")}} attribute of the {{SVGElement("feImage")}} element, which fetches image data from an external source and provides the pixel data as output. The attribute is a [`<length>`](/en-US/docs/Web/SVG/Content_type#length) or a [`<percentage>`](/en-US/docs/Web/SVG/Content_type#percentage) relative to the height of the filter region. The default value is `100%`. The property value is a length in user coordinate system units. +It reflects the {{SVGAttr("height")}} attribute of the {{SVGElement("feImage")}} element, which fetches image data from an external source and provides the pixel data as output. The attribute is a [`<length>`](/en-US/docs/Web/SVG/Guides/Content_type#length) or a [`<percentage>`](/en-US/docs/Web/SVG/Guides/Content_type#percentage) relative to the height of the filter region. The default value is `100%`. The property value is a length in user coordinate system units. ## Value @@ -35,7 +35,7 @@ console.log(verticalSize.baseVal.value); // the `height` value ## See also - {{domxref("SVGFEImageElement.width")}} -- [SVG tutorial: Filter effects](/en-US/docs/Web/SVG/Tutorial/Filter_effects) -- [SVG Filter primitive attributes](/en-US/docs/Web/SVG/Attribute#filters_attributes) +- [SVG tutorial: Filter effects](/en-US/docs/Web/SVG/Tutorials/SVG_from_scratch/Filter_effects) +- [SVG Filter primitive attributes](/en-US/docs/Web/SVG/Reference/Attribute#filters_attributes) - CSS {{cssxref("blend-mode")}} data type - CSS {{cssxref("mix-blend-mode")}} property diff --git a/files/en-us/web/api/svgfeimageelement/result/index.md b/files/en-us/web/api/svgfeimageelement/result/index.md index a9ad51092eae563..0427b1788663b40 100644 --- a/files/en-us/web/api/svgfeimageelement/result/index.md +++ b/files/en-us/web/api/svgfeimageelement/result/index.md @@ -36,9 +36,8 @@ console.log(filterName.baseVa); // the filter's assigned name ## See also -- {{domxref("SVGFEImageElement.in1")}} - {{cssxref("custom-ident")}} data type -- [SVG tutorial: Filter effects](/en-US/docs/Web/SVG/Tutorial/Filter_effects) -- [SVG Filter primitive attributes](/en-US/docs/Web/SVG/Attribute#filters_attributes) +- [SVG tutorial: Filter effects](/en-US/docs/Web/SVG/Tutorials/SVG_from_scratch/Filter_effects) +- [SVG Filter primitive attributes](/en-US/docs/Web/SVG/Reference/Attribute#filters_attributes) - CSS {{cssxref("blend-mode")}} data type - CSS {{cssxref("mix-blend-mode")}} property diff --git a/files/en-us/web/api/svgfeimageelement/width/index.md b/files/en-us/web/api/svgfeimageelement/width/index.md index f667080121025a5..3b03598c685d88e 100644 --- a/files/en-us/web/api/svgfeimageelement/width/index.md +++ b/files/en-us/web/api/svgfeimageelement/width/index.md @@ -10,7 +10,7 @@ browser-compat: api.SVGFEImageElement.width The **`width`** read-only property of the {{domxref("SVGFEImageElement")}} interface describes the horizontal size of an SVG filter primitive as a {{domxref("SVGAnimatedLength")}}. -It reflects the {{SVGAttr("width")}} attribute of the {{SVGElement("feImage")}} element, which fetches image data from an external source and provides the pixel data as output. The attribute is a [`<length>`](/en-US/docs/Web/SVG/Content_type#length) or a [`<percentage>`](/en-US/docs/Web/SVG/Content_type#percentage) relative to the width of the filter region. The default value is `100%`. The property value is a length in user coordinate system units. +It reflects the {{SVGAttr("width")}} attribute of the {{SVGElement("feImage")}} element, which fetches image data from an external source and provides the pixel data as output. The attribute is a [`<length>`](/en-US/docs/Web/SVG/Guides/Content_type#length) or a [`<percentage>`](/en-US/docs/Web/SVG/Guides/Content_type#percentage) relative to the width of the filter region. The default value is `100%`. The property value is a length in user coordinate system units. ## Value @@ -35,7 +35,7 @@ console.log(horizontalSize.baseVal.value); // the `width` value ## See also - {{domxref("SVGFEImageElement.height")}} -- [SVG tutorial: Filter effects](/en-US/docs/Web/SVG/Tutorial/Filter_effects) -- [SVG Filter primitive attributes](/en-US/docs/Web/SVG/Attribute#filters_attributes) +- [SVG tutorial: Filter effects](/en-US/docs/Web/SVG/Tutorials/SVG_from_scratch/Filter_effects) +- [SVG Filter primitive attributes](/en-US/docs/Web/SVG/Reference/Attribute#filters_attributes) - CSS {{cssxref("blend-mode")}} data type - CSS {{cssxref("mix-blend-mode")}} property diff --git a/files/en-us/web/api/svgfeimageelement/x/index.md b/files/en-us/web/api/svgfeimageelement/x/index.md index 321363c515ddacc..977e6fed7ad757f 100644 --- a/files/en-us/web/api/svgfeimageelement/x/index.md +++ b/files/en-us/web/api/svgfeimageelement/x/index.md @@ -10,7 +10,7 @@ browser-compat: api.SVGFEImageElement.x The **`x`** read-only property of the {{domxref("SVGFEImageElement")}} interface describes the horizontal coordinate of the position of an SVG filter primitive as a {{domxref("SVGAnimatedLength")}}. -It reflects the {{SVGAttr("x")}} attribute of the {{SVGElement("feImage")}} element, which fetches image data from an external source and provides the pixel data as output. The attribute is a [`<length>`](/en-US/docs/Web/SVG/Content_type#length) or [`<percentage>`](/en-US/docs/Web/SVG/Content_type#percentage). The `<coordinate>` is a length in the user coordinate system that is the given distance from the origin of the user coordinate system along the x-axis. If the `x` attribute is a percent value, the property value is relative to the width of the filter region in user coordinate system units. The default value is `0`. +It reflects the {{SVGAttr("x")}} attribute of the {{SVGElement("feImage")}} element, which fetches image data from an external source and provides the pixel data as output. The attribute is a [`<length>`](/en-US/docs/Web/SVG/Guides/Content_type#length) or [`<percentage>`](/en-US/docs/Web/SVG/Guides/Content_type#percentage). The `<coordinate>` is a length in the user coordinate system that is the given distance from the origin of the user coordinate system along the x-axis. If the `x` attribute is a percent value, the property value is relative to the width of the filter region in user coordinate system units. The default value is `0`. ## Value @@ -35,7 +35,7 @@ console.log(leftPosition.baseVal.value); // the `x` value ## See also - {{domxref("SVGFEImageElement.y")}} -- [SVG tutorial: Filter effects](/en-US/docs/Web/SVG/Tutorial/Filter_effects) -- [SVG Filter primitive attributes](/en-US/docs/Web/SVG/Attribute#filters_attributes) +- [SVG tutorial: Filter effects](/en-US/docs/Web/SVG/Tutorials/SVG_from_scratch/Filter_effects) +- [SVG Filter primitive attributes](/en-US/docs/Web/SVG/Reference/Attribute#filters_attributes) - CSS {{cssxref("blend-mode")}} data type - CSS {{cssxref("mix-blend-mode")}} property diff --git a/files/en-us/web/api/svgfeimageelement/y/index.md b/files/en-us/web/api/svgfeimageelement/y/index.md index 1b7c8d732b64345..0e9ef79754f7f80 100644 --- a/files/en-us/web/api/svgfeimageelement/y/index.md +++ b/files/en-us/web/api/svgfeimageelement/y/index.md @@ -10,7 +10,7 @@ browser-compat: api.SVGFEImageElement.y The **`y`** read-only property of the {{domxref("SVGFEImageElement")}} interface describes the vertical coordinate of the position of an SVG filter primitive as a {{domxref("SVGAnimatedLength")}}. -It reflects the {{SVGAttr("y")}} attribute of the {{SVGElement("feImage")}} element, which fetches image data from an external source and provides the pixel data as output. The attribute is a [`<length>`](/en-US/docs/Web/SVG/Content_type#length) or [`<percentage>`](/en-US/docs/Web/SVG/Content_type#percentage). The `<coordinate>` is a length in the user coordinate system that is the given distance from the origin of the filter along the y-axis. If the `y` attribute is a percent value, the property value is a relative to the height of the filter region in user coordinate system units. The default value is `0`. +It reflects the {{SVGAttr("y")}} attribute of the {{SVGElement("feImage")}} element, which fetches image data from an external source and provides the pixel data as output. The attribute is a [`<length>`](/en-US/docs/Web/SVG/Guides/Content_type#length) or [`<percentage>`](/en-US/docs/Web/SVG/Guides/Content_type#percentage). The `<coordinate>` is a length in the user coordinate system that is the given distance from the origin of the filter along the y-axis. If the `y` attribute is a percent value, the property value is a relative to the height of the filter region in user coordinate system units. The default value is `0`. ## Value @@ -35,7 +35,7 @@ console.log(topPosition.baseVal.value); // the `y` value ## See also - {{domxref("SVGFEImageElement.x")}} -- [SVG tutorial: Filter effects](/en-US/docs/Web/SVG/Tutorial/Filter_effects) -- [SVG Filter primitive attributes](/en-US/docs/Web/SVG/Attribute#filters_attributes) +- [SVG tutorial: Filter effects](/en-US/docs/Web/SVG/Tutorials/SVG_from_scratch/Filter_effects) +- [SVG Filter primitive attributes](/en-US/docs/Web/SVG/Reference/Attribute#filters_attributes) - CSS {{cssxref("blend-mode")}} data type - CSS {{cssxref("mix-blend-mode")}} property diff --git a/files/en-us/web/api/svgfemergeelement/height/index.md b/files/en-us/web/api/svgfemergeelement/height/index.md index 37550aa607ed393..b3f4afc5dc7df46 100644 --- a/files/en-us/web/api/svgfemergeelement/height/index.md +++ b/files/en-us/web/api/svgfemergeelement/height/index.md @@ -10,7 +10,7 @@ browser-compat: api.SVGFEMergeElement.height The **`height`** read-only property of the {{domxref("SVGFEMergeElement")}} interface describes the vertical size of an SVG filter primitive as a {{domxref("SVGAnimatedLength")}}. -It reflects the {{SVGAttr("height")}} attribute of the {{SVGElement("feMerge")}} element. The attribute is a [`<length>`](/en-US/docs/Web/SVG/Content_type#length) or a [`<percentage>`](/en-US/docs/Web/SVG/Content_type#percentage) relative to the height of the filter region. The default value is `100%`. The property value is a length in user coordinate system units. +It reflects the {{SVGAttr("height")}} attribute of the {{SVGElement("feMerge")}} element. The attribute is a [`<length>`](/en-US/docs/Web/SVG/Guides/Content_type#length) or a [`<percentage>`](/en-US/docs/Web/SVG/Guides/Content_type#percentage) relative to the height of the filter region. The default value is `100%`. The property value is a length in user coordinate system units. ## Value diff --git a/files/en-us/web/api/svgfemergeelement/width/index.md b/files/en-us/web/api/svgfemergeelement/width/index.md index 576b60896fc5807..b0f02656ec78511 100644 --- a/files/en-us/web/api/svgfemergeelement/width/index.md +++ b/files/en-us/web/api/svgfemergeelement/width/index.md @@ -10,7 +10,7 @@ browser-compat: api.SVGFEMergeElement.width The **`width`** read-only property of the {{domxref("SVGFEMergeElement")}} interface describes the horizontal size of an SVG filter primitive as a {{domxref("SVGAnimatedLength")}}. -It reflects the {{SVGAttr("width")}} attribute of the {{SVGElement("feMerge")}} element. The attribute is a [`<length>`](/en-US/docs/Web/SVG/Content_type#length) or a [`<percentage>`](/en-US/docs/Web/SVG/Content_type#percentage) relative to the width of the filter region. The default value is `100%`. The property value is a length in user coordinate system units. +It reflects the {{SVGAttr("width")}} attribute of the {{SVGElement("feMerge")}} element. The attribute is a [`<length>`](/en-US/docs/Web/SVG/Guides/Content_type#length) or a [`<percentage>`](/en-US/docs/Web/SVG/Guides/Content_type#percentage) relative to the width of the filter region. The default value is `100%`. The property value is a length in user coordinate system units. ## Value diff --git a/files/en-us/web/api/svgfemergeelement/x/index.md b/files/en-us/web/api/svgfemergeelement/x/index.md index 3e6ab2a710ee096..5d05e21ab93e685 100644 --- a/files/en-us/web/api/svgfemergeelement/x/index.md +++ b/files/en-us/web/api/svgfemergeelement/x/index.md @@ -10,7 +10,7 @@ browser-compat: api.SVGFEMergeElement.x The **`x`** read-only property of the {{domxref("SVGFEMergeElement")}} interface describes the horizontal coordinate of the position of an SVG filter primitive as a {{domxref("SVGAnimatedLength")}}. -It reflects the {{SVGAttr("x")}} attribute of the {{SVGElement("feMerge")}} element. The attribute is a [`<length>`](/en-US/docs/Web/SVG/Content_type#length) or [`<percentage>`](/en-US/docs/Web/SVG/Content_type#percentage). The `<coordinate>` is a length in the user coordinate system that is the given distance from the origin of the user coordinate system along the x-axis. If the `x` attribute is a percent value, the property value is relative to the width of the filter region in user coordinate system units. The default value is `0`. +It reflects the {{SVGAttr("x")}} attribute of the {{SVGElement("feMerge")}} element. The attribute is a [`<length>`](/en-US/docs/Web/SVG/Guides/Content_type#length) or [`<percentage>`](/en-US/docs/Web/SVG/Guides/Content_type#percentage). The `<coordinate>` is a length in the user coordinate system that is the given distance from the origin of the user coordinate system along the x-axis. If the `x` attribute is a percent value, the property value is relative to the width of the filter region in user coordinate system units. The default value is `0`. ## Value diff --git a/files/en-us/web/api/svgfemergeelement/y/index.md b/files/en-us/web/api/svgfemergeelement/y/index.md index 7f1d26487283dfa..4b59987b571ce6e 100644 --- a/files/en-us/web/api/svgfemergeelement/y/index.md +++ b/files/en-us/web/api/svgfemergeelement/y/index.md @@ -10,7 +10,7 @@ browser-compat: api.SVGFEMergeElement.y The **`y`** read-only property of the {{domxref("SVGFEMergeElement")}} interface describes the vertical coordinate of the position of an SVG filter primitive as a {{domxref("SVGAnimatedLength")}}. -It reflects the {{SVGAttr("y")}} attribute of the {{SVGElement("feMerge")}} element. The attribute is a [`<length>`](/en-US/docs/Web/SVG/Content_type#length) or [`<percentage>`](/en-US/docs/Web/SVG/Content_type#percentage). The `<coordinate>` is a length in the user coordinate system that is the given distance from the origin of the filter along the y-axis. If the `y` attribute is a percent value, the property value is a relative to the height of the filter region in user coordinate system units. The default value is `0`. +It reflects the {{SVGAttr("y")}} attribute of the {{SVGElement("feMerge")}} element. The attribute is a [`<length>`](/en-US/docs/Web/SVG/Guides/Content_type#length) or [`<percentage>`](/en-US/docs/Web/SVG/Guides/Content_type#percentage). The `<coordinate>` is a length in the user coordinate system that is the given distance from the origin of the filter along the y-axis. If the `y` attribute is a percent value, the property value is a relative to the height of the filter region in user coordinate system units. The default value is `0`. ## Value diff --git a/files/en-us/web/api/svgfemorphologyelement/height/index.md b/files/en-us/web/api/svgfemorphologyelement/height/index.md index f9c60fe95ae9d94..2cd9977fbaace6e 100644 --- a/files/en-us/web/api/svgfemorphologyelement/height/index.md +++ b/files/en-us/web/api/svgfemorphologyelement/height/index.md @@ -10,7 +10,7 @@ browser-compat: api.SVGFEMorphologyElement.height The **`height`** read-only property of the {{domxref("SVGFEMorphologyElement")}} interface describes the vertical size of an SVG filter primitive as a {{domxref("SVGAnimatedLength")}}. -It reflects the {{SVGAttr("height")}} attribute of the {{SVGElement("feMorphology")}} element. The attribute is a [`<length>`](/en-US/docs/Web/SVG/Content_type#length) or a [`<percentage>`](/en-US/docs/Web/SVG/Content_type#percentage) relative to the height of the filter region. The default value is `100%`. The property value is a length in user coordinate system units. +It reflects the {{SVGAttr("height")}} attribute of the {{SVGElement("feMorphology")}} element. The attribute is a [`<length>`](/en-US/docs/Web/SVG/Guides/Content_type#length) or a [`<percentage>`](/en-US/docs/Web/SVG/Guides/Content_type#percentage) relative to the height of the filter region. The default value is `100%`. The property value is a length in user coordinate system units. ## Value diff --git a/files/en-us/web/api/svgfemorphologyelement/index.md b/files/en-us/web/api/svgfemorphologyelement/index.md index 052986d5a53bfb4..1899039ff9f3583 100644 --- a/files/en-us/web/api/svgfemorphologyelement/index.md +++ b/files/en-us/web/api/svgfemorphologyelement/index.md @@ -11,37 +11,6 @@ The **`SVGFEMorphologyElement`** interface corresponds to the {{SVGElement("feMo {{InheritanceDiagram}} -## Constants - -<table class="no-markdown"> - <tbody> - <tr> - <th>Name</th> - <th>Value</th> - <th>Description</th> - </tr> - <tr> - <td><code>SVG_MORPHOLOGY_OPERATOR_UNKNOWN</code></td> - <td>0</td> - <td> - The type is not one of predefined types. It is invalid to attempt to - define a new value of this type or to attempt to switch an existing - value to this type. - </td> - </tr> - <tr> - <td><code>SVG_MORPHOLOGY_OPERATOR_ERODE</code></td> - <td>1</td> - <td>Corresponds to the <code>erode</code> value.</td> - </tr> - <tr> - <td><code>SVG_MORPHOLOGY_OPERATOR_DILATE</code></td> - <td>2</td> - <td>Corresponds to <code>dilate</code> value.</td> - </tr> - </tbody> -</table> - ## Instance properties _This interface also inherits properties from its parent interface, {{domxref("SVGElement")}}._ @@ -69,6 +38,15 @@ _This interface also inherits properties from its parent interface, {{domxref("S _This interface does not provide any specific methods, but implements those of its parent, {{domxref("SVGElement")}}._ +## Static properties + +- `SVG_MORPHOLOGY_OPERATOR_UNKNOWN` (0) + - : The type is not one of predefined types. It is invalid to attempt to define a new value of this type or to attempt to switch an existing value to this type. +- `SVG_MORPHOLOGY_OPERATOR_ERODE` (1) + - : Corresponds to the value `erode`. +- `SVG_MORPHOLOGY_OPERATOR_DILATE` (2) + - : Corresponds to the value `dilate`. + ## Specifications {{Specifications}} diff --git a/files/en-us/web/api/svgfemorphologyelement/width/index.md b/files/en-us/web/api/svgfemorphologyelement/width/index.md index 3adf39c966fe1e8..11d2b5c286ae018 100644 --- a/files/en-us/web/api/svgfemorphologyelement/width/index.md +++ b/files/en-us/web/api/svgfemorphologyelement/width/index.md @@ -10,7 +10,7 @@ browser-compat: api.SVGFEMorphologyElement.width The **`width`** read-only property of the {{domxref("SVGFEMorphologyElement")}} interface describes the horizontal size of an SVG filter primitive as a {{domxref("SVGAnimatedLength")}}. -It reflects the {{SVGAttr("width")}} attribute of the {{SVGElement("feMorphology")}} element. The attribute is a [`<length>`](/en-US/docs/Web/SVG/Content_type#length) or a [`<percentage>`](/en-US/docs/Web/SVG/Content_type#percentage) relative to the width of the filter region. The default value is `100%`. The property value is a length in user coordinate system units. +It reflects the {{SVGAttr("width")}} attribute of the {{SVGElement("feMorphology")}} element. The attribute is a [`<length>`](/en-US/docs/Web/SVG/Guides/Content_type#length) or a [`<percentage>`](/en-US/docs/Web/SVG/Guides/Content_type#percentage) relative to the width of the filter region. The default value is `100%`. The property value is a length in user coordinate system units. ## Value diff --git a/files/en-us/web/api/svgfemorphologyelement/x/index.md b/files/en-us/web/api/svgfemorphologyelement/x/index.md index 5104d36f93f8e1e..ecadad5c915d109 100644 --- a/files/en-us/web/api/svgfemorphologyelement/x/index.md +++ b/files/en-us/web/api/svgfemorphologyelement/x/index.md @@ -10,7 +10,7 @@ browser-compat: api.SVGFEMorphologyElement.x The **`x`** read-only property of the {{domxref("SVGFEMorphologyElement")}} interface describes the horizontal coordinate of the position of an SVG filter primitive as a {{domxref("SVGAnimatedLength")}}. -It reflects the {{SVGAttr("x")}} attribute of the {{SVGElement("feMorphology")}} element. The attribute is a [`<length>`](/en-US/docs/Web/SVG/Content_type#length) or [`<percentage>`](/en-US/docs/Web/SVG/Content_type#percentage). The `<coordinate>` is a length in the user coordinate system that is the given distance from the origin of the user coordinate system along the x-axis. If the `x` attribute is a percent value, the property value is relative to the width of the filter region in user coordinate system units. The default value is `0`. +It reflects the {{SVGAttr("x")}} attribute of the {{SVGElement("feMorphology")}} element. The attribute is a [`<length>`](/en-US/docs/Web/SVG/Guides/Content_type#length) or [`<percentage>`](/en-US/docs/Web/SVG/Guides/Content_type#percentage). The `<coordinate>` is a length in the user coordinate system that is the given distance from the origin of the user coordinate system along the x-axis. If the `x` attribute is a percent value, the property value is relative to the width of the filter region in user coordinate system units. The default value is `0`. ## Value diff --git a/files/en-us/web/api/svgfemorphologyelement/y/index.md b/files/en-us/web/api/svgfemorphologyelement/y/index.md index 980032d157c816a..235ac020f21123d 100644 --- a/files/en-us/web/api/svgfemorphologyelement/y/index.md +++ b/files/en-us/web/api/svgfemorphologyelement/y/index.md @@ -10,7 +10,7 @@ browser-compat: api.SVGFEMorphologyElement.y The **`y`** read-only property of the {{domxref("SVGFEMorphologyElement")}} interface describes the vertical coordinate of the position of an SVG filter primitive as a {{domxref("SVGAnimatedLength")}}. -It reflects the {{SVGAttr("y")}} attribute of the {{SVGElement("feMorphology")}} element. The attribute is a [`<length>`](/en-US/docs/Web/SVG/Content_type#length) or [`<percentage>`](/en-US/docs/Web/SVG/Content_type#percentage). The `<coordinate>` is a length in the user coordinate system that is the given distance from the origin of the filter along the y-axis. If the `y` attribute is a percent value, the property value is a relative to the height of the filter region in user coordinate system units. The default value is `0`. +It reflects the {{SVGAttr("y")}} attribute of the {{SVGElement("feMorphology")}} element. The attribute is a [`<length>`](/en-US/docs/Web/SVG/Guides/Content_type#length) or [`<percentage>`](/en-US/docs/Web/SVG/Guides/Content_type#percentage). The `<coordinate>` is a length in the user coordinate system that is the given distance from the origin of the filter along the y-axis. If the `y` attribute is a percent value, the property value is a relative to the height of the filter region in user coordinate system units. The default value is `0`. ## Value diff --git a/files/en-us/web/api/svgfeoffsetelement/height/index.md b/files/en-us/web/api/svgfeoffsetelement/height/index.md index 9bf63cab3d93aee..f3aa603f2a5ba4a 100644 --- a/files/en-us/web/api/svgfeoffsetelement/height/index.md +++ b/files/en-us/web/api/svgfeoffsetelement/height/index.md @@ -10,7 +10,7 @@ browser-compat: api.SVGFEOffsetElement.height The **`height`** read-only property of the {{domxref("SVGFEOffsetElement")}} interface describes the vertical size of an SVG filter primitive as an {{domxref("SVGAnimatedLength")}}. -It reflects the {{SVGAttr("height")}} attribute of the {{SVGElement("feOffset")}} element, which offsets the input image relative to its current position. The attribute is a [`<length>`](/en-US/docs/Web/SVG/Content_type#length) or a [`<percentage>`](/en-US/docs/Web/SVG/Content_type#percentage) relative to the height of the filter region. The default value is `100%`. The property value is a length in user coordinate system units. +It reflects the {{SVGAttr("height")}} attribute of the {{SVGElement("feOffset")}} element, which offsets the input image relative to its current position. The attribute is a [`<length>`](/en-US/docs/Web/SVG/Guides/Content_type#length) or a [`<percentage>`](/en-US/docs/Web/SVG/Guides/Content_type#percentage) relative to the height of the filter region. The default value is `100%`. The property value is a length in user coordinate system units. ## Value diff --git a/files/en-us/web/api/svgfeoffsetelement/width/index.md b/files/en-us/web/api/svgfeoffsetelement/width/index.md index eb18ee25fe00e22..233eb51e537e3c9 100644 --- a/files/en-us/web/api/svgfeoffsetelement/width/index.md +++ b/files/en-us/web/api/svgfeoffsetelement/width/index.md @@ -10,7 +10,7 @@ browser-compat: api.SVGFEOffsetElement.width The **`width`** read-only property of the {{domxref("SVGFEOffsetElement")}} interface describes the horizontal size of an SVG filter primitive as a {{domxref("SVGAnimatedLength")}}. -It reflects the {{SVGAttr("width")}} attribute of the {{SVGElement("feOffset")}} element, which offsets the input image relative to its current position. The attribute is a [`<length>`](/en-US/docs/Web/SVG/Content_type#length) or a [`<percentage>`](/en-US/docs/Web/SVG/Content_type#percentage) relative to the width of the filter region. The default value is `100%`. The property value is a length in user coordinate system units. +It reflects the {{SVGAttr("width")}} attribute of the {{SVGElement("feOffset")}} element, which offsets the input image relative to its current position. The attribute is a [`<length>`](/en-US/docs/Web/SVG/Guides/Content_type#length) or a [`<percentage>`](/en-US/docs/Web/SVG/Guides/Content_type#percentage) relative to the width of the filter region. The default value is `100%`. The property value is a length in user coordinate system units. ## Value diff --git a/files/en-us/web/api/svgfeoffsetelement/x/index.md b/files/en-us/web/api/svgfeoffsetelement/x/index.md index 09a487a3e4333ea..668f4738160a662 100644 --- a/files/en-us/web/api/svgfeoffsetelement/x/index.md +++ b/files/en-us/web/api/svgfeoffsetelement/x/index.md @@ -10,7 +10,7 @@ browser-compat: api.SVGFEOffsetElement.x The **`x`** read-only property of the {{domxref("SVGFEOffsetElement")}} interface describes the horizontal coordinate of the position of an SVG filter primitive as a {{domxref("SVGAnimatedLength")}}. -It reflects the {{SVGAttr("x")}} attribute of the {{SVGElement("feOffset")}} element, which offsets the input image relative to its current position. The attribute is a [`<length>`](/en-US/docs/Web/SVG/Content_type#length) or [`<percentage>`](/en-US/docs/Web/SVG/Content_type#percentage). The `<coordinate>` is a length in the user coordinate system that is the given distance from the origin of the user coordinate system along the x-axis. If the `x` attribute is a percent value, the property value is relative to the width of the filter region in user coordinate system units. The default value is `0`. +It reflects the {{SVGAttr("x")}} attribute of the {{SVGElement("feOffset")}} element, which offsets the input image relative to its current position. The attribute is a [`<length>`](/en-US/docs/Web/SVG/Guides/Content_type#length) or [`<percentage>`](/en-US/docs/Web/SVG/Guides/Content_type#percentage). The `<coordinate>` is a length in the user coordinate system that is the given distance from the origin of the user coordinate system along the x-axis. If the `x` attribute is a percent value, the property value is relative to the width of the filter region in user coordinate system units. The default value is `0`. ## Value diff --git a/files/en-us/web/api/svgfeoffsetelement/y/index.md b/files/en-us/web/api/svgfeoffsetelement/y/index.md index c7dccb67fe4f9ca..9561b11d2760a49 100644 --- a/files/en-us/web/api/svgfeoffsetelement/y/index.md +++ b/files/en-us/web/api/svgfeoffsetelement/y/index.md @@ -10,7 +10,7 @@ browser-compat: api.SVGFEOffsetElement.y The **`y`** read-only property of the {{domxref("SVGFEOffsetElement")}} interface describes the vertical coordinate of the position of an SVG filter primitive as a {{domxref("SVGAnimatedLength")}}. -It reflects the {{SVGAttr("y")}} attribute of the {{SVGElement("feOffset")}} element, which offsets the input image relative to its current position. The attribute is a [`<length>`](/en-US/docs/Web/SVG/Content_type#length) or [`<percentage>`](/en-US/docs/Web/SVG/Content_type#percentage). The `<coordinate>` is a length in the user coordinate system that is the given distance from the origin of the filter along the y-axis. If the `y` attribute is a percent value, the property value is a relative to the height of the filter region in user coordinate system units. The default value is `0`. +It reflects the {{SVGAttr("y")}} attribute of the {{SVGElement("feOffset")}} element, which offsets the input image relative to its current position. The attribute is a [`<length>`](/en-US/docs/Web/SVG/Guides/Content_type#length) or [`<percentage>`](/en-US/docs/Web/SVG/Guides/Content_type#percentage). The `<coordinate>` is a length in the user coordinate system that is the given distance from the origin of the filter along the y-axis. If the `y` attribute is a percent value, the property value is a relative to the height of the filter region in user coordinate system units. The default value is `0`. ## Value diff --git a/files/en-us/web/api/svgfepointlightelement/x/index.md b/files/en-us/web/api/svgfepointlightelement/x/index.md index 34c71943e856892..4582a9670905c05 100644 --- a/files/en-us/web/api/svgfepointlightelement/x/index.md +++ b/files/en-us/web/api/svgfepointlightelement/x/index.md @@ -10,7 +10,7 @@ browser-compat: api.SVGFEPointLightElement.x The **`x`** read-only property of the {{domxref("SVGFEPointLightElement")}} interface describes the horizontal coordinate of the position of an SVG filter primitive as a {{domxref("SVGAnimatedNumber")}}. -It reflects the {{SVGAttr("x")}} attribute of the {{SVGElement("fePointLight")}} element, which can be used to define the light source in a point light effect. The attribute is a [`<number>`](/en-US/docs/Web/SVG/Content_type#number). The default value is `0`. +It reflects the {{SVGAttr("x")}} attribute of the {{SVGElement("fePointLight")}} element, which can be used to define the light source in a point light effect. The attribute is a [`<number>`](/en-US/docs/Web/SVG/Guides/Content_type#number). The default value is `0`. ## Value diff --git a/files/en-us/web/api/svgfepointlightelement/y/index.md b/files/en-us/web/api/svgfepointlightelement/y/index.md index 5b3f8a488fde6dd..e033da6a2ee763b 100644 --- a/files/en-us/web/api/svgfepointlightelement/y/index.md +++ b/files/en-us/web/api/svgfepointlightelement/y/index.md @@ -10,7 +10,7 @@ browser-compat: api.SVGFEPointLightElement.y The **`y`** read-only property of the {{domxref("SVGFEPointLightElement")}} interface describes the vertical coordinate of the position of an SVG filter primitive as a {{domxref("SVGAnimatedNumber")}}. -It reflects the {{SVGAttr("y")}} attribute of the {{SVGElement("fePointLight")}} element, which can be used to define the light source in a point light effect. The attribute is a [`<number>`](/en-US/docs/Web/SVG/Content_type#number). The default value is `0`. +It reflects the {{SVGAttr("y")}} attribute of the {{SVGElement("fePointLight")}} element, which can be used to define the light source in a point light effect. The attribute is a [`<number>`](/en-US/docs/Web/SVG/Guides/Content_type#number). The default value is `0`. ## Value diff --git a/files/en-us/web/api/svgfepointlightelement/z/index.md b/files/en-us/web/api/svgfepointlightelement/z/index.md index 4c3700613e2ba9c..7c4ec1de823189f 100644 --- a/files/en-us/web/api/svgfepointlightelement/z/index.md +++ b/files/en-us/web/api/svgfepointlightelement/z/index.md @@ -10,7 +10,7 @@ browser-compat: api.SVGFEPointLightElement.z The **`z`** read-only property of the {{domxref("SVGFEPointLightElement")}} interface describes the z-axis value of the position of an SVG filter primitive as a {{domxref("SVGAnimatedNumber")}}. A positive Z-axis comes out towards the person viewing the content. -It reflects the {{SVGAttr("z")}} attribute of the {{SVGElement("fePointLight")}} element, which can be used to define the light source in a point light effect. The attribute is a [`<number>`](/en-US/docs/Web/SVG/Content_type#number). The default value is `0`. +It reflects the {{SVGAttr("z")}} attribute of the {{SVGElement("fePointLight")}} element, which can be used to define the light source in a point light effect. The attribute is a [`<number>`](/en-US/docs/Web/SVG/Guides/Content_type#number). The default value is `0`. ## Value diff --git a/files/en-us/web/api/svgfespecularlightingelement/height/index.md b/files/en-us/web/api/svgfespecularlightingelement/height/index.md index 89087ac9690d639..7c4675b12ef402a 100644 --- a/files/en-us/web/api/svgfespecularlightingelement/height/index.md +++ b/files/en-us/web/api/svgfespecularlightingelement/height/index.md @@ -10,7 +10,7 @@ browser-compat: api.SVGFESpecularLightingElement.height The **`height`** read-only property of the {{domxref("SVGFESpecularLightingElement")}} interface describes the vertical size of an SVG filter primitive as a {{domxref("SVGAnimatedLength")}}. -It reflects the {{SVGAttr("height")}} attribute of the {{SVGElement("feSpecularLighting")}} element, which lights a source graphic using the alpha channel as a bump map. The attribute is a [`<length>`](/en-US/docs/Web/SVG/Content_type#length) or a [`<percentage>`](/en-US/docs/Web/SVG/Content_type#percentage) relative to the height of the filter region. The default value is `100%`. The property value is a length in user coordinate system units. +It reflects the {{SVGAttr("height")}} attribute of the {{SVGElement("feSpecularLighting")}} element, which lights a source graphic using the alpha channel as a bump map. The attribute is a [`<length>`](/en-US/docs/Web/SVG/Guides/Content_type#length) or a [`<percentage>`](/en-US/docs/Web/SVG/Guides/Content_type#percentage) relative to the height of the filter region. The default value is `100%`. The property value is a length in user coordinate system units. ## Value diff --git a/files/en-us/web/api/svgfespecularlightingelement/kernelunitlengthx/index.md b/files/en-us/web/api/svgfespecularlightingelement/kernelunitlengthx/index.md new file mode 100644 index 000000000000000..6f8128b23882357 --- /dev/null +++ b/files/en-us/web/api/svgfespecularlightingelement/kernelunitlengthx/index.md @@ -0,0 +1,30 @@ +--- +title: "SVGFESpecularLightingElement: kernelUnitLengthX property" +short-title: kernelUnitLengthX +slug: Web/API/SVGFESpecularLightingElement/kernelUnitLengthX +page-type: web-api-instance-property +browser-compat: api.SVGFESpecularLightingElement.kernelUnitLengthX +--- + +{{APIRef("SVG")}} + +The **`kernelUnitLengthX`** read-only property of the {{domxref("SVGFESpecularLightingElement")}} interface reflects the x value of the {{SVGAttr("kernelUnitLength")}} attribute of the given {{SVGElement("feSpecularLighting")}} element. + +The `kernelUnitLength` attribute indicates the intended distance in current filter units, specified by the `primitiveUnits` attribute, for the x and y coordinates. It contains one or two values, with the y value defaulting to x if not present, and the `kernelUnitLengthX` property gets and sets the first value. + +## Value + +An {{domxref("SVGAnimatedNumber")}} object that corresponds to the X-component of the {{SVGAttr("kernelUnitLength")}} attribute of the given element. + +## Specifications + +{{Specifications}} + +## Browser compatibility + +{{Compat}} + +## See also + +- {{domxref("SVGFeSpecularLightingElement.kernelUnitLengthY")}} +- {{domxref("SVGAnimatedNumber")}} diff --git a/files/en-us/web/api/svgfespecularlightingelement/kernelunitlengthy/index.md b/files/en-us/web/api/svgfespecularlightingelement/kernelunitlengthy/index.md new file mode 100644 index 000000000000000..a04266f1650eb2d --- /dev/null +++ b/files/en-us/web/api/svgfespecularlightingelement/kernelunitlengthy/index.md @@ -0,0 +1,30 @@ +--- +title: "SVGFESpecularLightingElement: kernelUnitLengthY property" +short-title: kernelUnitLengthY +slug: Web/API/SVGFESpecularLightingElement/kernelUnitLengthY +page-type: web-api-instance-property +browser-compat: api.SVGFESpecularLightingElement.kernelUnitLengthY +--- + +{{APIRef("SVG")}} + +The **`kernelUnitLengthY`** read-only property of the {{domxref("SVGFESpecularLightingElement")}} interface reflects the y value of the {{SVGAttr("kernelUnitLength")}} attribute of the given {{SVGElement("feSpecularLighting")}} element. + +The `kernelUnitLength` attribute indicates the intended distance in current filter units, specified by the `primitiveUnits` attribute, for the x and y coordinates. It contains one or two values, with the y value defaulting to x if not present, and the `kernelUnitLengthY` property gets and sets the last value. + +## Value + +An {{domxref("SVGAnimatedNumber")}} object that corresponds to the Y-component of the {{SVGAttr("kernelUnitLength")}} attribute of the given element. + +## Specifications + +{{Specifications}} + +## Browser compatibility + +{{Compat}} + +## See also + +- {{domxref("SVGFeSpecularLightingElement.kernelUnitLengthX")}} +- {{domxref("SVGAnimatedNumber")}} diff --git a/files/en-us/web/api/svgfespecularlightingelement/width/index.md b/files/en-us/web/api/svgfespecularlightingelement/width/index.md index 8427ce4f8f798bc..aa360847877532b 100644 --- a/files/en-us/web/api/svgfespecularlightingelement/width/index.md +++ b/files/en-us/web/api/svgfespecularlightingelement/width/index.md @@ -10,7 +10,7 @@ browser-compat: api.SVGFESpecularLightingElement.width The **`width`** read-only property of the {{domxref("SVGFESpecularLightingElement")}} interface describes the horizontal size of an SVG filter primitive as a {{domxref("SVGAnimatedLength")}}. -It reflects the {{SVGAttr("width")}} attribute of the {{SVGElement("feSpecularLighting")}} element, which lights a source graphic using the alpha channel as a bump map. The attribute is a [`<length>`](/en-US/docs/Web/SVG/Content_type#length) or a [`<percentage>`](/en-US/docs/Web/SVG/Content_type#percentage) relative to the width of the filter region. The default value is `100%`. The property value is a length in user coordinate system units. +It reflects the {{SVGAttr("width")}} attribute of the {{SVGElement("feSpecularLighting")}} element, which lights a source graphic using the alpha channel as a bump map. The attribute is a [`<length>`](/en-US/docs/Web/SVG/Guides/Content_type#length) or a [`<percentage>`](/en-US/docs/Web/SVG/Guides/Content_type#percentage) relative to the width of the filter region. The default value is `100%`. The property value is a length in user coordinate system units. ## Value diff --git a/files/en-us/web/api/svgfespecularlightingelement/x/index.md b/files/en-us/web/api/svgfespecularlightingelement/x/index.md index 621b2ab9820b5d5..4b2daed1be70de3 100644 --- a/files/en-us/web/api/svgfespecularlightingelement/x/index.md +++ b/files/en-us/web/api/svgfespecularlightingelement/x/index.md @@ -10,7 +10,7 @@ browser-compat: api.SVGFESpecularLightingElement.x The **`x`** read-only property of the {{domxref("SVGFESpecularLightingElement")}} interface describes the horizontal coordinate of the position of an SVG filter primitive as a {{domxref("SVGAnimatedLength")}}. -It reflects the {{SVGAttr("x")}} attribute of the {{SVGElement("feSpecularLighting")}} element, which lights a source graphic using the alpha channel as a bump map. The attribute is a [`<length>`](/en-US/docs/Web/SVG/Content_type#length) or [`<percentage>`](/en-US/docs/Web/SVG/Content_type#percentage). The `<coordinate>` is a length in the user coordinate system that is the given distance from the origin of the user coordinate system along the x-axis. If the `x` attribute is a percent value, the property value is relative to the width of the filter region in user coordinate system units. The default value is `0`. +It reflects the {{SVGAttr("x")}} attribute of the {{SVGElement("feSpecularLighting")}} element, which lights a source graphic using the alpha channel as a bump map. The attribute is a [`<length>`](/en-US/docs/Web/SVG/Guides/Content_type#length) or [`<percentage>`](/en-US/docs/Web/SVG/Guides/Content_type#percentage). The `<coordinate>` is a length in the user coordinate system that is the given distance from the origin of the user coordinate system along the x-axis. If the `x` attribute is a percent value, the property value is relative to the width of the filter region in user coordinate system units. The default value is `0`. ## Value diff --git a/files/en-us/web/api/svgfespecularlightingelement/y/index.md b/files/en-us/web/api/svgfespecularlightingelement/y/index.md index b34c8334de42f40..68fea195631dc77 100644 --- a/files/en-us/web/api/svgfespecularlightingelement/y/index.md +++ b/files/en-us/web/api/svgfespecularlightingelement/y/index.md @@ -10,7 +10,7 @@ browser-compat: api.SVGFESpecularLightingElement.y The **`y`** read-only property of the {{domxref("SVGFESpecularLightingElement")}} interface describes the vertical coordinate of the position of an SVG filter primitive as a {{domxref("SVGAnimatedLength")}}. -It reflects the {{SVGAttr("y")}} attribute of the {{SVGElement("feSpecularLighting")}} element, which lights a source graphic using the alpha channel as a bump map. The attribute is a [`<length>`](/en-US/docs/Web/SVG/Content_type#length) or [`<percentage>`](/en-US/docs/Web/SVG/Content_type#percentage). The `<coordinate>` is a length in the user coordinate system that is the given distance from the origin of the filter along the y-axis. If the `y` attribute is a percent value, the property value is a relative to the height of the filter region in user coordinate system units. The default value is `0`. +It reflects the {{SVGAttr("y")}} attribute of the {{SVGElement("feSpecularLighting")}} element, which lights a source graphic using the alpha channel as a bump map. The attribute is a [`<length>`](/en-US/docs/Web/SVG/Guides/Content_type#length) or [`<percentage>`](/en-US/docs/Web/SVG/Guides/Content_type#percentage). The `<coordinate>` is a length in the user coordinate system that is the given distance from the origin of the filter along the y-axis. If the `y` attribute is a percent value, the property value is a relative to the height of the filter region in user coordinate system units. The default value is `0`. ## Value diff --git a/files/en-us/web/api/svgfespotlightelement/limitingconeangle/index.md b/files/en-us/web/api/svgfespotlightelement/limitingconeangle/index.md index b25d78bf3bd7bd0..1a02e020e5d6c35 100644 --- a/files/en-us/web/api/svgfespotlightelement/limitingconeangle/index.md +++ b/files/en-us/web/api/svgfespotlightelement/limitingconeangle/index.md @@ -18,7 +18,7 @@ An {{domxref("SVGAnimatedNumber")}} object. ### Accessing the `limitingConeAngle` attribute of the `<feSpotLight>` element -In this example, we access the angle in degrees between the spot light axis (i.e. the axis between the light source and the point to which it is pointing at) and the spot light cone, by using the `limitingConeAngle` read-only property of the `SVGFESpotLightElement` interface. +In this example, we access the angle in degrees between the spot light axis (i.e., the axis between the light source and the point to which it is pointing at) and the spot light cone, by using the `limitingConeAngle` read-only property of the `SVGFESpotLightElement` interface. ```html <svg viewBox="0 0 200 200" xmlns="http://www.w3.org/2000/svg"> diff --git a/files/en-us/web/api/svgfespotlightelement/x/index.md b/files/en-us/web/api/svgfespotlightelement/x/index.md index ed1f3f0e2d892ec..29a8c2a24cb111f 100644 --- a/files/en-us/web/api/svgfespotlightelement/x/index.md +++ b/files/en-us/web/api/svgfespotlightelement/x/index.md @@ -10,7 +10,7 @@ browser-compat: api.SVGFESpotLightElement.x The **`x`** read-only property of the {{domxref("SVGFESpotLightElement")}} interface describes the horizontal coordinate of the position of an SVG filter primitive as a {{domxref("SVGAnimatedNumber")}}. -It reflects the {{SVGAttr("x")}} attribute of the {{SVGElement("feSpotLight")}} element., which can be used to define the light source in a spotlight effect. The attribute is a [`<number>`](/en-US/docs/Web/SVG/Content_type#number). The default value is `0`. +It reflects the {{SVGAttr("x")}} attribute of the {{SVGElement("feSpotLight")}} element., which can be used to define the light source in a spotlight effect. The attribute is a [`<number>`](/en-US/docs/Web/SVG/Guides/Content_type#number). The default value is `0`. ## Value diff --git a/files/en-us/web/api/svgfespotlightelement/y/index.md b/files/en-us/web/api/svgfespotlightelement/y/index.md index a740081c9fc0d9e..5be8a60e19304cb 100644 --- a/files/en-us/web/api/svgfespotlightelement/y/index.md +++ b/files/en-us/web/api/svgfespotlightelement/y/index.md @@ -10,7 +10,7 @@ browser-compat: api.SVGFESpotLightElement.y The **`y`** read-only property of the {{domxref("SVGFESpotLightElement")}} interface describes the vertical coordinate of the position of an SVG filter primitive as a {{domxref("SVGAnimatedNumber")}}. -It reflects the {{SVGAttr("y")}} attribute of the {{SVGElement("feSpotLight")}} element., which can be used to define the light source in a spotlight effect. The attribute is a [`<number>`](/en-US/docs/Web/SVG/Content_type#number). The default value is `0`. +It reflects the {{SVGAttr("y")}} attribute of the {{SVGElement("feSpotLight")}} element., which can be used to define the light source in a spotlight effect. The attribute is a [`<number>`](/en-US/docs/Web/SVG/Guides/Content_type#number). The default value is `0`. ## Value diff --git a/files/en-us/web/api/svgfespotlightelement/z/index.md b/files/en-us/web/api/svgfespotlightelement/z/index.md index e9bce8fdade293f..1315a158b27edd5 100644 --- a/files/en-us/web/api/svgfespotlightelement/z/index.md +++ b/files/en-us/web/api/svgfespotlightelement/z/index.md @@ -10,7 +10,7 @@ browser-compat: api.SVGFESpotLightElement.z The **`z`** read-only property of the {{domxref("SVGFESpotLightElement")}} interface describes the z-axis value of the position of an SVG filter primitive as a {{domxref("SVGAnimatedNumber")}}. A positive Z-axis comes out towards the person viewing the content. -It reflects the {{SVGAttr("z")}} attribute of the {{SVGElement("feSpotLight")}} element, which can be used to define the light source in a spotlight effect. The attribute is a [`<number>`](/en-US/docs/Web/SVG/Content_type#number). The default value is `0`. +It reflects the {{SVGAttr("z")}} attribute of the {{SVGElement("feSpotLight")}} element, which can be used to define the light source in a spotlight effect. The attribute is a [`<number>`](/en-US/docs/Web/SVG/Guides/Content_type#number). The default value is `0`. ## Value diff --git a/files/en-us/web/api/svgfetileelement/height/index.md b/files/en-us/web/api/svgfetileelement/height/index.md index cbcdbbcbdca4945..483bda3f74e255c 100644 --- a/files/en-us/web/api/svgfetileelement/height/index.md +++ b/files/en-us/web/api/svgfetileelement/height/index.md @@ -10,7 +10,7 @@ browser-compat: api.SVGFETileElement.height The **`height`** read-only property of the {{domxref("SVGFETileElement")}} interface describes the vertical size of an SVG filter primitive as an {{domxref("SVGAnimatedLength")}}. -It reflects the {{SVGAttr("height")}} attribute of the {{SVGElement("feTitle")}} element, which fills a target rectangle with a repeated, tiled pattern of an input image. The attribute is a [`<length>`](/en-US/docs/Web/SVG/Content_type#length) or a [`<percentage>`](/en-US/docs/Web/SVG/Content_type#percentage) relative to the height of the filter region. The default value is `100%`. The property value is a length in user coordinate system units. +It reflects the {{SVGAttr("height")}} attribute of the {{SVGElement("feTile")}} element, which fills a target rectangle with a repeated, tiled pattern of an input image. The attribute is a [`<length>`](/en-US/docs/Web/SVG/Guides/Content_type#length) or a [`<percentage>`](/en-US/docs/Web/SVG/Guides/Content_type#percentage) relative to the height of the filter region. The default value is `100%`. The property value is a length in user coordinate system units. ## Value diff --git a/files/en-us/web/api/svgfetileelement/result/index.md b/files/en-us/web/api/svgfetileelement/result/index.md index 5d65d3133b94b08..1a125cc2c355dff 100644 --- a/files/en-us/web/api/svgfetileelement/result/index.md +++ b/files/en-us/web/api/svgfetileelement/result/index.md @@ -10,7 +10,7 @@ browser-compat: api.SVGFETileElement.result The **`result`** read-only property of the {{domxref("SVGFETileElement")}} interface describes the assigned name of an SVG filter primitive as an {{domxref("SVGAnimatedString")}}. -It reflects the {{SVGAttr("result")}} attribute of the {{SVGElement("feTitle")}} element, which fills a target rectangle with a repeated, tiled pattern of an input image. The attribute value is a {{cssxref("custom-ident")}}. If supplied, then graphics that result from processing this filter primitive can be referenced by an {{SVGAttr("in")}} attribute on a subsequent filter primitive within the same {{SVGElement("filter")}} element. +It reflects the {{SVGAttr("result")}} attribute of the {{SVGElement("feTile")}} element, which fills a target rectangle with a repeated, tiled pattern of an input image. The attribute value is a {{cssxref("custom-ident")}}. If supplied, then graphics that result from processing this filter primitive can be referenced by an {{SVGAttr("in")}} attribute on a subsequent filter primitive within the same {{SVGElement("filter")}} element. If no `result` attribute is defined, the filter's `result.baseVal` and `result.animVal` are empty strings, and the output of the `<feTile>` filter will only be available for re-use as the implicit input into the next filter primitive if that filter primitive provides no value for its `in` attribute. diff --git a/files/en-us/web/api/svgfetileelement/width/index.md b/files/en-us/web/api/svgfetileelement/width/index.md index e024dbe9497ff29..3b59e0e601b30a5 100644 --- a/files/en-us/web/api/svgfetileelement/width/index.md +++ b/files/en-us/web/api/svgfetileelement/width/index.md @@ -10,7 +10,7 @@ browser-compat: api.SVGFETileElement.width The **`width`** read-only property of the {{domxref("SVGFETileElement")}} interface describes the horizontal size of an SVG filter primitive as an {{domxref("SVGAnimatedLength")}}. -It reflects the {{SVGAttr("width")}} attribute of the {{SVGElement("feTitle")}} element, which fills a target rectangle with a repeated, tiled pattern of an input image. The attribute is a [`<length>`](/en-US/docs/Web/SVG/Content_type#length) or a [`<percentage>`](/en-US/docs/Web/SVG/Content_type#percentage) relative to the width of the filter region. The default value is `100%`. The property value is a length in user coordinate system units. +It reflects the {{SVGAttr("width")}} attribute of the {{SVGElement("feTile")}} element, which fills a target rectangle with a repeated, tiled pattern of an input image. The attribute is a [`<length>`](/en-US/docs/Web/SVG/Guides/Content_type#length) or a [`<percentage>`](/en-US/docs/Web/SVG/Guides/Content_type#percentage) relative to the width of the filter region. The default value is `100%`. The property value is a length in user coordinate system units. ## Value diff --git a/files/en-us/web/api/svgfetileelement/x/index.md b/files/en-us/web/api/svgfetileelement/x/index.md index e187964d7156429..69d29c3383de261 100644 --- a/files/en-us/web/api/svgfetileelement/x/index.md +++ b/files/en-us/web/api/svgfetileelement/x/index.md @@ -10,7 +10,7 @@ browser-compat: api.SVGFETileElement.x The **`x`** read-only property of the {{domxref("SVGFETileElement")}} interface describes the horizontal coordinate of the position of an SVG filter primitive as an {{domxref("SVGAnimatedLength")}}. -It reflects the {{SVGAttr("x")}} attribute of the {{SVGElement("feTitle")}} element, which fills a target rectangle with a repeated, tiled pattern of an input image. The attribute is a [`<length>`](/en-US/docs/Web/SVG/Content_type#length) or [`<percentage>`](/en-US/docs/Web/SVG/Content_type#percentage). The `<coordinate>` is a length in the user coordinate system that is the given distance from the origin of the user coordinate system along the x-axis. If the `x` attribute is a percent value, the property value is relative to the width of the filter region in user coordinate system units. The default value is `0`. +It reflects the {{SVGAttr("x")}} attribute of the {{SVGElement("feTile")}} element, which fills a target rectangle with a repeated, tiled pattern of an input image. The attribute is a [`<length>`](/en-US/docs/Web/SVG/Guides/Content_type#length) or [`<percentage>`](/en-US/docs/Web/SVG/Guides/Content_type#percentage). The `<coordinate>` is a length in the user coordinate system that is the given distance from the origin of the user coordinate system along the x-axis. If the `x` attribute is a percent value, the property value is relative to the width of the filter region in user coordinate system units. The default value is `0`. ## Value diff --git a/files/en-us/web/api/svgfetileelement/y/index.md b/files/en-us/web/api/svgfetileelement/y/index.md index e5aaef4b4dd6cf9..a30c95d0bf0e81a 100644 --- a/files/en-us/web/api/svgfetileelement/y/index.md +++ b/files/en-us/web/api/svgfetileelement/y/index.md @@ -10,7 +10,7 @@ browser-compat: api.SVGFETileElement.y The **`y`** read-only property of the {{domxref("SVGFETileElement")}} interface describes the vertical coordinate of the position of an SVG filter primitive as an {{domxref("SVGAnimatedLength")}}. -It reflects the {{SVGAttr("y")}} attribute of the {{SVGElement("feTitle")}} element, which fills a target rectangle with a repeated, tiled pattern of an input image. The attribute is a [`<length>`](/en-US/docs/Web/SVG/Content_type#length) or [`<percentage>`](/en-US/docs/Web/SVG/Content_type#percentage). The `<coordinate>` is a length in the user coordinate system that is the given distance from the origin of the filter along the y-axis. If the `y` attribute is a percent value, the property value is a relative to the height of the filter region in user coordinate system units. The default value is `0`. +It reflects the {{SVGAttr("y")}} attribute of the {{SVGElement("feTile")}} element, which fills a target rectangle with a repeated, tiled pattern of an input image. The attribute is a [`<length>`](/en-US/docs/Web/SVG/Guides/Content_type#length) or [`<percentage>`](/en-US/docs/Web/SVG/Guides/Content_type#percentage). The `<coordinate>` is a length in the user coordinate system that is the given distance from the origin of the filter along the y-axis. If the `y` attribute is a percent value, the property value is a relative to the height of the filter region in user coordinate system units. The default value is `0`. ## Value diff --git a/files/en-us/web/api/svgfeturbulenceelement/height/index.md b/files/en-us/web/api/svgfeturbulenceelement/height/index.md index 95f459a7c403cde..e68ff7c7b87a4db 100644 --- a/files/en-us/web/api/svgfeturbulenceelement/height/index.md +++ b/files/en-us/web/api/svgfeturbulenceelement/height/index.md @@ -10,7 +10,7 @@ browser-compat: api.SVGFETurbulenceElement.height The **`height`** read-only property of the {{domxref("SVGFETurbulenceElement")}} interface describes the vertical size of an SVG filter primitive as a {{domxref("SVGAnimatedLength")}}. -It reflects the {{SVGAttr("height")}} attribute of the {{SVGElement("feTurbulence")}} element, which allows the synthesis of artificial textures. The attribute is a [`<length>`](/en-US/docs/Web/SVG/Content_type#length) or a [`<percentage>`](/en-US/docs/Web/SVG/Content_type#percentage) relative to the height of the filter region. The default value is `100%`. The property value is a length in user coordinate system units. +It reflects the {{SVGAttr("height")}} attribute of the {{SVGElement("feTurbulence")}} element, which allows the synthesis of artificial textures. The attribute is a [`<length>`](/en-US/docs/Web/SVG/Guides/Content_type#length) or a [`<percentage>`](/en-US/docs/Web/SVG/Guides/Content_type#percentage) relative to the height of the filter region. The default value is `100%`. The property value is a length in user coordinate system units. ## Value diff --git a/files/en-us/web/api/svgfeturbulenceelement/index.md b/files/en-us/web/api/svgfeturbulenceelement/index.md index 13222102155bebf..3ec7bef52a1dba5 100644 --- a/files/en-us/web/api/svgfeturbulenceelement/index.md +++ b/files/en-us/web/api/svgfeturbulenceelement/index.md @@ -11,70 +11,6 @@ The **`SVGFETurbulenceElement`** interface corresponds to the {{SVGElement("feTu {{InheritanceDiagram}} -## Constants - -### Turbulence types - -<table class="no-markdown"> - <tbody> - <tr> - <th>Name</th> - <th>Value</th> - <th>Description</th> - </tr> - <tr> - <td><code>SVG_TURBULENCE_TYPE_UNKNOWN</code></td> - <td>0</td> - <td> - The type is not one of predefined types. It is invalid to attempt to - define a new value of this type or to attempt to switch an existing - value to this type. - </td> - </tr> - <tr> - <td><code>SVG_TURBULENCE_TYPE_FRACTALNOISE</code></td> - <td>1</td> - <td>Corresponds to the <code>fractalNoise</code> value.</td> - </tr> - <tr> - <td><code>SVG_TURBULENCE_TYPE_TURBULENCE</code></td> - <td>2</td> - <td>Corresponds to <code>turbulence</code> value.</td> - </tr> - </tbody> -</table> - -### Stitch options - -<table class="no-markdown"> - <tbody> - <tr> - <th>Name</th> - <th>Value</th> - <th>Description</th> - </tr> - <tr> - <td><code>SVG_STITCHTYPE_UNKNOWN</code></td> - <td>0</td> - <td> - The type is not one of predefined types. It is invalid to attempt to - define a new value of this type or to attempt to switch an existing - value to this type. - </td> - </tr> - <tr> - <td><code>SVG_STITCHTYPE_STITCH</code></td> - <td>1</td> - <td>Corresponds to the <code>stitch</code> value.</td> - </tr> - <tr> - <td><code>SVG_STITCHTYPE_NOSTITCH</code></td> - <td>2</td> - <td>Corresponds to <code>noStitch</code> value.</td> - </tr> - </tbody> -</table> - ## Instance properties _This interface also inherits properties from its parent interface, {{domxref("SVGElement")}}._ @@ -106,6 +42,21 @@ _This interface also inherits properties from its parent interface, {{domxref("S _This interface does not provide any specific methods, but implements those of its parent, {{domxref("SVGElement")}}._ +## Static properties + +- `SVG_TURBULENCE_TYPE_UNKNOWN` (0) + - : The type is not one of predefined types. It is invalid to attempt to define a new value of this type or to attempt to switch an existing value to this type. +- `SVG_TURBULENCE_TYPE_FRACTALNOISE` (1) + - : Corresponds to the value `fractalNoise`. +- `SVG_TURBULENCE_TYPE_TURBULENCE` (2) + - : Corresponds to the value `turbulence`. +- `SVG_STITCHTYPE_UNKNOWN` (0) + - : The type is not one of predefined types. It is invalid to attempt to define a new value of this type or to attempt to switch an existing value to this type. +- `SVG_STITCHTYPE_STITCH` (1) + - : Corresponds to the value `stitch`. +- `SVG_STITCHTYPE_NOSTITCH` (2) + - : Corresponds to the value `noStitch`. + ## Specifications {{Specifications}} diff --git a/files/en-us/web/api/svgfeturbulenceelement/result/index.md b/files/en-us/web/api/svgfeturbulenceelement/result/index.md index 29757840cc4512d..7dd39f261e69b5a 100644 --- a/files/en-us/web/api/svgfeturbulenceelement/result/index.md +++ b/files/en-us/web/api/svgfeturbulenceelement/result/index.md @@ -36,5 +36,4 @@ console.log(filterName.baseVal); // the filter's assigned name ## See also -- {{domxref("SVGFETurbulenceElement.in1")}} - {{cssxref("custom-ident")}} data type diff --git a/files/en-us/web/api/svgfeturbulenceelement/width/index.md b/files/en-us/web/api/svgfeturbulenceelement/width/index.md index 87a1e47929eee8a..c861bf963a759ba 100644 --- a/files/en-us/web/api/svgfeturbulenceelement/width/index.md +++ b/files/en-us/web/api/svgfeturbulenceelement/width/index.md @@ -10,7 +10,7 @@ browser-compat: api.SVGFETurbulenceElement.width The **`width`** read-only property of the {{domxref("SVGFETurbulenceElement")}} interface describes the horizontal size of an SVG filter primitive as a {{domxref("SVGAnimatedLength")}}. -It reflects the {{SVGAttr("width")}} attribute of the {{SVGElement("feTurbulence")}} element, which allows the synthesis of artificial textures. The attribute is a [`<length>`](/en-US/docs/Web/SVG/Content_type#length) or a [`<percentage>`](/en-US/docs/Web/SVG/Content_type#percentage) relative to the width of the filter region. The default value is `100%`. The property value is a length in user coordinate system units. +It reflects the {{SVGAttr("width")}} attribute of the {{SVGElement("feTurbulence")}} element, which allows the synthesis of artificial textures. The attribute is a [`<length>`](/en-US/docs/Web/SVG/Guides/Content_type#length) or a [`<percentage>`](/en-US/docs/Web/SVG/Guides/Content_type#percentage) relative to the width of the filter region. The default value is `100%`. The property value is a length in user coordinate system units. ## Value diff --git a/files/en-us/web/api/svgfeturbulenceelement/x/index.md b/files/en-us/web/api/svgfeturbulenceelement/x/index.md index 91f6af5f21e94c0..9da95adc31740bc 100644 --- a/files/en-us/web/api/svgfeturbulenceelement/x/index.md +++ b/files/en-us/web/api/svgfeturbulenceelement/x/index.md @@ -10,7 +10,7 @@ browser-compat: api.SVGFETurbulenceElement.x The **`x`** read-only property of the {{domxref("SVGFETurbulenceElement")}} interface describes the horizontal coordinate of the position of an SVG filter primitive as a {{domxref("SVGAnimatedLength")}}. -It reflects the {{SVGAttr("x")}} attribute of the {{SVGElement("feTurbulence")}} element, which allows the synthesis of artificial textures. The attribute is a [`<length>`](/en-US/docs/Web/SVG/Content_type#length) or [`<percentage>`](/en-US/docs/Web/SVG/Content_type#percentage). The `<coordinate>` is a length in the user coordinate system that is the given distance from the origin of the user coordinate system along the x-axis. If the `x` attribute is a percent value, the property value is relative to the width of the filter region in user coordinate system units. The default value is `0`. +It reflects the {{SVGAttr("x")}} attribute of the {{SVGElement("feTurbulence")}} element, which allows the synthesis of artificial textures. The attribute is a [`<length>`](/en-US/docs/Web/SVG/Guides/Content_type#length) or [`<percentage>`](/en-US/docs/Web/SVG/Guides/Content_type#percentage). The `<coordinate>` is a length in the user coordinate system that is the given distance from the origin of the user coordinate system along the x-axis. If the `x` attribute is a percent value, the property value is relative to the width of the filter region in user coordinate system units. The default value is `0`. ## Value diff --git a/files/en-us/web/api/svgfeturbulenceelement/y/index.md b/files/en-us/web/api/svgfeturbulenceelement/y/index.md index 770cbe75e025166..e1d74546312cb43 100644 --- a/files/en-us/web/api/svgfeturbulenceelement/y/index.md +++ b/files/en-us/web/api/svgfeturbulenceelement/y/index.md @@ -10,7 +10,7 @@ browser-compat: api.SVGFETurbulenceElement.y The **`y`** read-only property of the {{domxref("SVGFETurbulenceElement")}} interface describes the vertical coordinate of the position of an SVG filter primitive as a {{domxref("SVGAnimatedLength")}}. -It reflects the {{SVGAttr("y")}} attribute of the {{SVGElement("feTurbulence")}} element, which allows the synthesis of artificial textures. The attribute is a [`<length>`](/en-US/docs/Web/SVG/Content_type#length) or [`<percentage>`](/en-US/docs/Web/SVG/Content_type#percentage). The `<coordinate>` is a length in the user coordinate system that is the given distance from the origin of the filter along the y-axis. If the `y` attribute is a percent value, the property value is a relative to the height of the filter region in user coordinate system units. The default value is `0`. +It reflects the {{SVGAttr("y")}} attribute of the {{SVGElement("feTurbulence")}} element, which allows the synthesis of artificial textures. The attribute is a [`<length>`](/en-US/docs/Web/SVG/Guides/Content_type#length) or [`<percentage>`](/en-US/docs/Web/SVG/Guides/Content_type#percentage). The `<coordinate>` is a length in the user coordinate system that is the given distance from the origin of the filter along the y-axis. If the `y` attribute is a percent value, the property value is a relative to the height of the filter region in user coordinate system units. The default value is `0`. ## Value diff --git a/files/en-us/web/api/svgfilterelement/filterunits/index.md b/files/en-us/web/api/svgfilterelement/filterunits/index.md index d514a418e3d4d45..e5a550ee4122cc5 100644 --- a/files/en-us/web/api/svgfilterelement/filterunits/index.md +++ b/files/en-us/web/api/svgfilterelement/filterunits/index.md @@ -60,4 +60,4 @@ console.log(filterElement.filterUnits.baseVal); // Output: 1 (SVG_UNIT_TYPE_USER - {{domxref("SVGFilterElement.primitiveUnits")}} - {{domxref("SVGUnitTypes")}} -- [SVG filter primitive attributes](/en-US/docs/Web/SVG/Attribute#filters_attributes) +- [SVG filter primitive attributes](/en-US/docs/Web/SVG/Reference/Attribute#filters_attributes) diff --git a/files/en-us/web/api/svgfilterelement/height/index.md b/files/en-us/web/api/svgfilterelement/height/index.md index 05665449cb9fab1..a28d39f36b93192 100644 --- a/files/en-us/web/api/svgfilterelement/height/index.md +++ b/files/en-us/web/api/svgfilterelement/height/index.md @@ -10,7 +10,7 @@ browser-compat: api.SVGFilterElement.height The **`height`** read-only property of the {{domxref("SVGFilterElement")}} interface describes the vertical size of an SVG filter primitive as a {{domxref("SVGAnimatedLength")}}. -It reflects the {{SVGAttr("height")}} attribute of the {{SVGElement("filter")}} element. The attribute is a [`<length>`](/en-US/docs/Web/SVG/Content_type#length) or a [`<percentage>`](/en-US/docs/Web/SVG/Content_type#percentage) relative to the height of the filter region. The default value is `100%`. The property value is a length in user coordinate system units. +It reflects the {{SVGAttr("height")}} attribute of the {{SVGElement("filter")}} element. The attribute is a [`<length>`](/en-US/docs/Web/SVG/Guides/Content_type#length) or a [`<percentage>`](/en-US/docs/Web/SVG/Guides/Content_type#percentage) relative to the height of the filter region. The default value is `100%`. The property value is a length in user coordinate system units. ## Value @@ -34,7 +34,7 @@ console.log(verticalSize.baseVal.value); // the `height` value ## See also -- [SVG tutorial: Filter effects](/en-US/docs/Web/SVG/Tutorial/Filter_effects) -- [SVG filter primitive attributes](/en-US/docs/Web/SVG/Attribute#filters_attributes) +- [SVG tutorial: Filter effects](/en-US/docs/Web/SVG/Tutorials/SVG_from_scratch/Filter_effects) +- [SVG filter primitive attributes](/en-US/docs/Web/SVG/Reference/Attribute#filters_attributes) - CSS {{cssxref("blend-mode")}} data type - CSS {{cssxref("mix-blend-mode")}} property diff --git a/files/en-us/web/api/svgfilterelement/width/index.md b/files/en-us/web/api/svgfilterelement/width/index.md index 64c99da8be4e1af..ca4b67fff3613ee 100644 --- a/files/en-us/web/api/svgfilterelement/width/index.md +++ b/files/en-us/web/api/svgfilterelement/width/index.md @@ -10,7 +10,7 @@ browser-compat: api.SVGFilterElement.width The **`width`** read-only property of the {{domxref("SVGFilterElement")}} interface describes the horizontal size of an SVG filter primitive as a {{domxref("SVGAnimatedLength")}}. -It reflects the {{SVGAttr("width")}} attribute of the {{SVGElement("filter")}} element. The attribute is a [`<length>`](/en-US/docs/Web/SVG/Content_type#length) or a [`<percentage>`](/en-US/docs/Web/SVG/Content_type#percentage) relative to the width of the filter region. The default value is `100%`. The property value is a length in user coordinate system units. +It reflects the {{SVGAttr("width")}} attribute of the {{SVGElement("filter")}} element. The attribute is a [`<length>`](/en-US/docs/Web/SVG/Guides/Content_type#length) or a [`<percentage>`](/en-US/docs/Web/SVG/Guides/Content_type#percentage) relative to the width of the filter region. The default value is `100%`. The property value is a length in user coordinate system units. ## Value @@ -34,7 +34,7 @@ console.log(horizontalSize.baseVal.value); // the `width` value ## See also -- [SVG tutorial: Filter effects](/en-US/docs/Web/SVG/Tutorial/Filter_effects) -- [SVG Filter primitive attributes](/en-US/docs/Web/SVG/Attribute#filters_attributes) +- [SVG tutorial: Filter effects](/en-US/docs/Web/SVG/Tutorials/SVG_from_scratch/Filter_effects) +- [SVG Filter primitive attributes](/en-US/docs/Web/SVG/Reference/Attribute#filters_attributes) - CSS {{cssxref("blend-mode")}} data type - CSS {{cssxref("mix-blend-mode")}} property diff --git a/files/en-us/web/api/svgfilterelement/x/index.md b/files/en-us/web/api/svgfilterelement/x/index.md index 1b4a420a5e7cde3..067aa69fee1a649 100644 --- a/files/en-us/web/api/svgfilterelement/x/index.md +++ b/files/en-us/web/api/svgfilterelement/x/index.md @@ -10,7 +10,7 @@ browser-compat: api.SVGFilterElement.x The **`x`** read-only property of the {{domxref("SVGFilterElement")}} interface describes the horizontal coordinate of the position of an SVG filter primitive as a {{domxref("SVGAnimatedLength")}}. -It reflects the {{SVGAttr("x")}} attribute of the {{SVGElement("filter")}} element. The attribute is a [`<length>`](/en-US/docs/Web/SVG/Content_type#length) or [`<percentage>`](/en-US/docs/Web/SVG/Content_type#percentage). The `<coordinate>` is a length in the user coordinate system that is the given distance from the origin of the user coordinate system along the x-axis. If the `x` attribute is a percent value, the property value is relative to the width of the filter region in user coordinate system units. The default value is `0`. +It reflects the {{SVGAttr("x")}} attribute of the {{SVGElement("filter")}} element. The attribute is a [`<length>`](/en-US/docs/Web/SVG/Guides/Content_type#length) or [`<percentage>`](/en-US/docs/Web/SVG/Guides/Content_type#percentage). The `<coordinate>` is a length in the user coordinate system that is the given distance from the origin of the user coordinate system along the x-axis. If the `x` attribute is a percent value, the property value is relative to the width of the filter region in user coordinate system units. The default value is `0`. ## Value @@ -34,7 +34,7 @@ console.log(leftPosition.baseVal.value); // the `x` value ## See also -- [SVG tutorial: Filter effects](/en-US/docs/Web/SVG/Tutorial/Filter_effects) -- [SVG Filter primitive attributes](/en-US/docs/Web/SVG/Attribute#filters_attributes) +- [SVG tutorial: Filter effects](/en-US/docs/Web/SVG/Tutorials/SVG_from_scratch/Filter_effects) +- [SVG Filter primitive attributes](/en-US/docs/Web/SVG/Reference/Attribute#filters_attributes) - CSS {{cssxref("blend-mode")}} data type - CSS {{cssxref("mix-blend-mode")}} property diff --git a/files/en-us/web/api/svgfilterelement/y/index.md b/files/en-us/web/api/svgfilterelement/y/index.md index f06b440bab0a2a9..131f09360019a04 100644 --- a/files/en-us/web/api/svgfilterelement/y/index.md +++ b/files/en-us/web/api/svgfilterelement/y/index.md @@ -10,7 +10,7 @@ browser-compat: api.SVGFilterElement.y The **`y`** read-only property of the {{domxref("SVGFilterElement")}} interface describes the vertical coordinate of the position of an SVG filter primitive as a {{domxref("SVGAnimatedLength")}}. -It reflects the {{SVGAttr("y")}} attribute of the {{SVGElement("filter")}} element. The attribute is a [`<length>`](/en-US/docs/Web/SVG/Content_type#length) or [`<percentage>`](/en-US/docs/Web/SVG/Content_type#percentage). The `<coordinate>` is a length in the user coordinate system that is the given distance from the origin of the filter along the y-axis. If the `y` attribute is a percent value, the property value is a relative to the height of the filter region in user coordinate system units. The default value is `0`. +It reflects the {{SVGAttr("y")}} attribute of the {{SVGElement("filter")}} element. The attribute is a [`<length>`](/en-US/docs/Web/SVG/Guides/Content_type#length) or [`<percentage>`](/en-US/docs/Web/SVG/Guides/Content_type#percentage). The `<coordinate>` is a length in the user coordinate system that is the given distance from the origin of the filter along the y-axis. If the `y` attribute is a percent value, the property value is a relative to the height of the filter region in user coordinate system units. The default value is `0`. ## Value @@ -34,7 +34,7 @@ console.log(topPosition.baseVal.value); // the `y` value ## See also -- [SVG tutorial: Filter effects](/en-US/docs/Web/SVG/Tutorial/Filter_effects) -- [SVG Filter primitive attributes](/en-US/docs/Web/SVG/Attribute#filters_attributes) +- [SVG tutorial: Filter effects](/en-US/docs/Web/SVG/Tutorials/SVG_from_scratch/Filter_effects) +- [SVG Filter primitive attributes](/en-US/docs/Web/SVG/Reference/Attribute#filters_attributes) - CSS {{cssxref("blend-mode")}} data type - CSS {{cssxref("mix-blend-mode")}} property diff --git a/files/en-us/web/api/svgfontelement/index.md b/files/en-us/web/api/svgfontelement/index.md deleted file mode 100644 index 99e08d4fc4bdcce..000000000000000 --- a/files/en-us/web/api/svgfontelement/index.md +++ /dev/null @@ -1,36 +0,0 @@ ---- -title: SVGFontElement -slug: Web/API/SVGFontElement -page-type: web-api-interface -status: - - deprecated -browser-compat: api.SVGFontElement ---- - -{{APIRef("SVG")}}{{deprecated_header}} - -The **`SVGFontElement`** interface corresponds to the {{SVGElement("font")}} elements. - -Object-oriented access to the attributes of the {{SVGElement("font")}} element via the SVG DOM is not possible. - -{{InheritanceDiagram}} - -## Instance properties - -_This interface has no properties but inherits properties from its parent, {{domxref("SVGElement")}}._ - -## Instance methods - -_This interface has no methods but inherits methods from its parent, {{domxref("SVGElement")}}._ - -## Specifications - -{{Specifications}} - -## Browser compatibility - -{{Compat}} - -## See also - -- {{SVGElement("font")}} SVG Element diff --git a/files/en-us/web/api/svgfontfaceelement/index.md b/files/en-us/web/api/svgfontfaceelement/index.md deleted file mode 100644 index 2299bd111ea0c1f..000000000000000 --- a/files/en-us/web/api/svgfontfaceelement/index.md +++ /dev/null @@ -1,36 +0,0 @@ ---- -title: SVGFontFaceElement -slug: Web/API/SVGFontFaceElement -page-type: web-api-interface -status: - - deprecated -browser-compat: api.SVGFontFaceElement ---- - -{{APIRef("SVG")}}{{deprecated_header}} - -The **`SVGFontFaceElement`** interface corresponds to the {{SVGElement("font-face")}} elements. - -Object-oriented access to the attributes of the {{SVGElement("font-face")}} element via the SVG DOM is not possible. - -{{InheritanceDiagram}} - -## Instance properties - -_This interface has no properties but inherits properties from its parent, {{domxref("SVGElement")}}._ - -## Instance methods - -_This interface has no methods but inherits methods from its parent, {{domxref("SVGElement")}}._ - -## Specifications - -{{Specifications}} - -## Browser compatibility - -{{Compat}} - -## See also - -- {{SVGElement("font-face")}} diff --git a/files/en-us/web/api/svgfontfaceformatelement/index.md b/files/en-us/web/api/svgfontfaceformatelement/index.md deleted file mode 100644 index e1b2b0da6436357..000000000000000 --- a/files/en-us/web/api/svgfontfaceformatelement/index.md +++ /dev/null @@ -1,36 +0,0 @@ ---- -title: SVGFontFaceFormatElement -slug: Web/API/SVGFontFaceFormatElement -page-type: web-api-interface -status: - - deprecated -browser-compat: api.SVGFontFaceFormatElement ---- - -{{APIRef("SVG")}}{{deprecated_header}} - -The **`SVGFontFaceFormatElement`** interface corresponds to the {{SVGElement("font-face-format")}} elements. - -Object-oriented access to the attributes of the {{SVGElement("font-face-format")}} element via the SVG DOM is not possible. - -{{InheritanceDiagram}} - -## Instance properties - -_This interface has no properties but inherits properties from its parent, {{domxref("SVGElement")}}._ - -## Instance methods - -_This interface has no methods but inherits methods from its parent, {{domxref("SVGElement")}}._ - -## Specifications - -{{Specifications}} - -## Browser compatibility - -{{Compat}} - -## See also - -- {{SVGElement("font-face-format")}} diff --git a/files/en-us/web/api/svgfontfacenameelement/index.md b/files/en-us/web/api/svgfontfacenameelement/index.md deleted file mode 100644 index f38abb9c1bc136c..000000000000000 --- a/files/en-us/web/api/svgfontfacenameelement/index.md +++ /dev/null @@ -1,36 +0,0 @@ ---- -title: SVGFontFaceNameElement -slug: Web/API/SVGFontFaceNameElement -page-type: web-api-interface -status: - - deprecated -browser-compat: api.SVGFontFaceNameElement ---- - -{{APIRef("SVG")}}{{deprecated_header}} - -The **`SVGFontFaceNameElement`** interface corresponds to the {{SVGElement("font-face-name")}} elements. - -Object-oriented access to the attributes of the {{SVGElement("font-face-name")}} element via the SVG DOM is not possible. - -{{InheritanceDiagram}} - -## Instance properties - -_This interface has no properties but inherits properties from its parent, {{domxref("SVGElement")}}._ - -## Instance methods - -_This interface has no methods but inherits methods from its parent, {{domxref("SVGElement")}}._ - -## Specifications - -{{Specifications}} - -## Browser compatibility - -{{Compat}} - -## See also - -- {{SVGElement("font-face-name")}} diff --git a/files/en-us/web/api/svgfontfacesrcelement/index.md b/files/en-us/web/api/svgfontfacesrcelement/index.md deleted file mode 100644 index 6de45576067709f..000000000000000 --- a/files/en-us/web/api/svgfontfacesrcelement/index.md +++ /dev/null @@ -1,36 +0,0 @@ ---- -title: SVGFontFaceSrcElement -slug: Web/API/SVGFontFaceSrcElement -page-type: web-api-interface -status: - - deprecated -browser-compat: api.SVGFontFaceSrcElement ---- - -{{APIRef("SVG")}}{{deprecated_header}} - -The **`SVGFontFaceSrcElement`** interface corresponds to the {{SVGElement("font-face-src")}} elements. - -Object-oriented access to the attributes of the {{SVGElement("font-face-src")}} element via the SVG DOM is not possible. - -{{InheritanceDiagram}} - -## Instance properties - -_This interface has no properties but inherits properties from its parent, {{domxref("SVGElement")}}._ - -## Instance methods - -_This interface has no methods but inherits methods from its parent, {{domxref("SVGElement")}}._ - -## Specifications - -{{Specifications}} - -## Browser compatibility - -{{Compat}} - -## See also - -- {{SVGElement("font-face-src")}} diff --git a/files/en-us/web/api/svgfontfaceurielement/index.md b/files/en-us/web/api/svgfontfaceurielement/index.md deleted file mode 100644 index e60779ae80ec0c2..000000000000000 --- a/files/en-us/web/api/svgfontfaceurielement/index.md +++ /dev/null @@ -1,36 +0,0 @@ ---- -title: SVGFontFaceUriElement -slug: Web/API/SVGFontFaceUriElement -page-type: web-api-interface -status: - - deprecated -browser-compat: api.SVGFontFaceUriElement ---- - -{{APIRef("SVG")}}{{deprecated_header}} - -The **`SVGFontFaceUriElement`** interface corresponds to the {{SVGElement("font-face-uri")}} elements. - -Object-oriented access to the attributes of the {{SVGElement("font-face-uri")}} element via the SVG DOM is not possible. - -{{InheritanceDiagram}} - -## Instance properties - -_This interface has no properties but inherits properties from its parent, {{domxref("SVGElement")}}._ - -## Instance methods - -_This interface has no methods but inherits methods from its parent, {{domxref("SVGElement")}}._ - -## Specifications - -{{Specifications}} - -## Browser compatibility - -{{Compat}} - -## See also - -- {{SVGElement("font-face-uri")}} diff --git a/files/en-us/web/api/svgforeignobjectelement/height/index.md b/files/en-us/web/api/svgforeignobjectelement/height/index.md index 0c64f6436761482..0cf839c7394f73a 100644 --- a/files/en-us/web/api/svgforeignobjectelement/height/index.md +++ b/files/en-us/web/api/svgforeignobjectelement/height/index.md @@ -10,7 +10,7 @@ browser-compat: api.SVGForeignObjectElement.height The **`height`** read-only property of the {{domxref("SVGForeignObjectElement")}} interface describes the height of the `<foreignObject>` element. It reflects the computed value of the {{SVGAttr("height")}} attribute on the {{SVGElement("foreignObject")}} element. -The attribute value is a [`<length>`](/en-US/docs/Web/SVG/Content_type#length), [`<percentage>`](/en-US/docs/Web/SVG/Content_type#percentage), or [`<number>`](/en-US/docs/Web/SVG/Content_type#number). The numeric value of the {{domxref("SVGAnimatedLength.baseVal")}} is the y-coordinate of the `<foreignObject>` element in the user coordinate system. +The attribute value is a [`<length>`](/en-US/docs/Web/SVG/Guides/Content_type#length), [`<percentage>`](/en-US/docs/Web/SVG/Guides/Content_type#percentage), or [`<number>`](/en-US/docs/Web/SVG/Guides/Content_type#number). The numeric value of the {{domxref("SVGAnimatedLength.baseVal")}} is the y-coordinate of the `<foreignObject>` element in the user coordinate system. ## Value diff --git a/files/en-us/web/api/svgforeignobjectelement/width/index.md b/files/en-us/web/api/svgforeignobjectelement/width/index.md index 4ff4f94ef4f2141..2fa46e14b2a46d7 100644 --- a/files/en-us/web/api/svgforeignobjectelement/width/index.md +++ b/files/en-us/web/api/svgforeignobjectelement/width/index.md @@ -10,7 +10,7 @@ browser-compat: api.SVGForeignObjectElement.width The **`width`** read-only property of the {{domxref("SVGForeignObjectElement")}} interface describes the width of the `<foreignObject>` element. It reflects the computed value of the {{SVGAttr("width")}} attribute on the {{SVGElement("foreignObject")}} element. -The attribute value is a [`<length>`](/en-US/docs/Web/SVG/Content_type#length), [`<percentage>`](/en-US/docs/Web/SVG/Content_type#percentage), or [`<number>`](/en-US/docs/Web/SVG/Content_type#number). The numeric value of the {{domxref("SVGAnimatedLength.baseVal")}} is the y-coordinate of the `<foreignObject>` element in the user coordinate system. +The attribute value is a [`<length>`](/en-US/docs/Web/SVG/Guides/Content_type#length), [`<percentage>`](/en-US/docs/Web/SVG/Guides/Content_type#percentage), or [`<number>`](/en-US/docs/Web/SVG/Guides/Content_type#number). The numeric value of the {{domxref("SVGAnimatedLength.baseVal")}} is the y-coordinate of the `<foreignObject>` element in the user coordinate system. ## Value diff --git a/files/en-us/web/api/svgforeignobjectelement/x/index.md b/files/en-us/web/api/svgforeignobjectelement/x/index.md index 8608b0d360afe0c..00cb8bfcae451f5 100644 --- a/files/en-us/web/api/svgforeignobjectelement/x/index.md +++ b/files/en-us/web/api/svgforeignobjectelement/x/index.md @@ -10,7 +10,7 @@ browser-compat: api.SVGForeignObjectElement.x The **`x`** read-only property of the {{domxref("SVGForeignObjectElement")}} interface describes the x-axis coordinate of the `<foreignObject>` element. It reflects the computed value of the {{SVGAttr("x")}} attribute on the {{SVGElement("foreignObject")}} element. -The attribute value is a [`<length>`](/en-US/docs/Web/SVG/Content_type#length), [`<percentage>`](/en-US/docs/Web/SVG/Content_type#percentage), or [`<number>`](/en-US/docs/Web/SVG/Content_type#number). The numeric value of the {{domxref("SVGAnimatedLength.baseVal")}} is the x-coordinate of the `<foreignObject>` element in the user coordinate system. +The attribute value is a [`<length>`](/en-US/docs/Web/SVG/Guides/Content_type#length), [`<percentage>`](/en-US/docs/Web/SVG/Guides/Content_type#percentage), or [`<number>`](/en-US/docs/Web/SVG/Guides/Content_type#number). The numeric value of the {{domxref("SVGAnimatedLength.baseVal")}} is the x-coordinate of the `<foreignObject>` element in the user coordinate system. ## Value diff --git a/files/en-us/web/api/svgforeignobjectelement/y/index.md b/files/en-us/web/api/svgforeignobjectelement/y/index.md index 1bebf34a7fa529d..f373e6e8657e424 100644 --- a/files/en-us/web/api/svgforeignobjectelement/y/index.md +++ b/files/en-us/web/api/svgforeignobjectelement/y/index.md @@ -10,7 +10,7 @@ browser-compat: api.SVGForeignObjectElement.y The **`y`** read-only property of the {{domxref("SVGForeignObjectElement")}} interface describes the y-axis coordinate of the `<foreignObject>` element. It reflects the computed value of the {{SVGAttr("y")}} attribute on the {{SVGElement("foreignObject")}} element. -The attribute value is a [`<length>`](/en-US/docs/Web/SVG/Content_type#length), [`<percentage>`](/en-US/docs/Web/SVG/Content_type#percentage), or [`<number>`](/en-US/docs/Web/SVG/Content_type#number). The numeric value of the {{domxref("SVGAnimatedLength.baseVal")}} is the y-coordinate of the `<foreignObject>` element in the user coordinate system. +The attribute value is a [`<length>`](/en-US/docs/Web/SVG/Guides/Content_type#length), [`<percentage>`](/en-US/docs/Web/SVG/Guides/Content_type#percentage), or [`<number>`](/en-US/docs/Web/SVG/Guides/Content_type#number). The numeric value of the {{domxref("SVGAnimatedLength.baseVal")}} is the y-coordinate of the `<foreignObject>` element in the user coordinate system. ## Value diff --git a/files/en-us/web/api/svgglyphelement/index.md b/files/en-us/web/api/svgglyphelement/index.md deleted file mode 100644 index d60f83a6ee347ae..000000000000000 --- a/files/en-us/web/api/svgglyphelement/index.md +++ /dev/null @@ -1,39 +0,0 @@ ---- -title: SVGGlyphElement -slug: Web/API/SVGGlyphElement -page-type: web-api-interface -status: - - deprecated -browser-compat: api.SVGGlyphElement ---- - -{{APIRef("SVG")}}{{deprecated_header}} - -The **`SVGGlyphElement`** interface corresponds to the {{SVGElement("glyph")}} element. - -Object-oriented access to the attributes of the `<glyph>` element via the SVG DOM is not possible. - -{{InheritanceDiagram}} - -> [!WARNING] -> This interface was removed in the SVG 2 specification. - -## Instance properties - -_This interface doesn't implement any specific properties, but inherits properties from its parent interface, {{domxref("SVGElement")}}._ - -## Instance methods - -_This interface doesn't implement any specific methods, but inherits methods from its parent interface, {{domxref("SVGElement")}}._ - -## Specifications - -{{Specifications}} - -## Browser compatibility - -{{Compat}} - -## See also - -- {{SVGElement("glyph")}} diff --git a/files/en-us/web/api/svgglyphrefelement/index.md b/files/en-us/web/api/svgglyphrefelement/index.md deleted file mode 100644 index 714dbc96e3e36a2..000000000000000 --- a/files/en-us/web/api/svgglyphrefelement/index.md +++ /dev/null @@ -1,47 +0,0 @@ ---- -title: SVGGlyphRefElement -slug: Web/API/SVGGlyphRefElement -page-type: web-api-interface -status: - - deprecated -browser-compat: api.SVGGlyphRefElement ---- - -{{APIRef("SVG")}}{{Deprecated_Header}} - -The **`SVGGlyphRefElement`** interface corresponds to the {{SVGElement("glyphRef")}} elements. - -{{InheritanceDiagram}} - -## Instance properties - -_This interface also inherits properties from its parent, {{domxref("SVGElement")}}._ - -- {{domxref("SVGGlyphRefElement.glyphRef")}} {{Deprecated_Inline}} - - : A string corresponding to the {{SVGAttr("glyphRef")}} attribute of the given element. -- {{domxref("SVGGlyphRefElement.format")}} {{Deprecated_Inline}} - - : A string corresponding to the {{SVGAttr("format")}} attribute of the given element. -- {{domxref("SVGGlyphRefElement.x")}} {{Deprecated_Inline}} - - : A float corresponding to the {{SVGAttr("x")}} attribute of the given element. -- {{domxref("SVGGlyphRefElement.y")}} {{Deprecated_Inline}} - - : A float corresponding to the {{SVGAttr("y")}} attribute of the given element. -- {{domxref("SVGGlyphRefElement.dx")}} {{Deprecated_Inline}} - - : A float corresponding to the {{SVGAttr("dx")}} attribute of the given element. -- {{domxref("SVGGlyphRefElement.dy")}} {{Deprecated_Inline}} - - : A float corresponding to the {{SVGAttr("dy")}} attribute of the given element. - -## Instance methods - -_This interface has no methods but inherits methods from its parent, {{domxref("SVGElement")}}._ - -## Specifications - -{{Specifications}} - -## Browser compatibility - -{{Compat}} - -## See also - -- {{SVGElement("glyphRef")}} diff --git a/files/en-us/web/api/svggradientelement/index.md b/files/en-us/web/api/svggradientelement/index.md index 9c06fd750e1eda9..a1432bb9c4700fd 100644 --- a/files/en-us/web/api/svggradientelement/index.md +++ b/files/en-us/web/api/svggradientelement/index.md @@ -11,48 +11,12 @@ The **`SVGGradient`** interface is a base interface used by {{domxref("SVGLinear {{InheritanceDiagram}} -## Constants - -<table class="no-markdown"> - <tbody> - <tr> - <th>Name</th> - <th>Value</th> - <th>Description</th> - </tr> - <tr> - <td><code>SVG_SPREADMETHOD_UNKNOWN</code></td> - <td>0</td> - <td> - The type is not one of predefined types. It is invalid to attempt to - define a new value of this type or to attempt to switch an existing - value to this type. - </td> - </tr> - <tr> - <td><code>SVG_SPREADMETHOD_PAD</code></td> - <td>1</td> - <td>Corresponds to value <em>pad</em>.</td> - </tr> - <tr> - <td><code>SVG_SPREADMETHOD_REFLECT</code></td> - <td>2</td> - <td>Corresponds to value <em>reflect</em>.</td> - </tr> - <tr> - <td><code>SVG_SPREADMETHOD_REPEAT</code></td> - <td>3</td> - <td>Corresponds to value <em>repeat</em>.</td> - </tr> - </tbody> -</table> - ## Instance properties _This interface also inherits properties from its parent, {{domxref("SVGElement")}}._ - {{domxref("SVGGradientElement.href")}} {{ReadOnlyInline}} - - : An {{domxref("SVGAnimatedString")}} corresponding to the {{SVGAttr("href")}} or {{SVGAttr("xlink:href")}} {{deprecated_inline}} attribute of the given element. + - : An {{domxref("SVGAnimatedString")}} corresponding to the {{SVGAttr("href")}} or {{SVGAttr("xlink:href")}} attribute of the given element. - {{domxref("SVGGradientElement.gradientUnits")}} {{ReadOnlyInline}} - : An {{domxref("SVGAnimatedEnumeration")}} corresponding to the {{SVGAttr("gradientUnits")}} attribute on the given element. This property takes one of the constants defined in {{domxref("SVGUnitTypes")}}. - {{domxref("SVGGradientElement.gradientTransform")}} {{ReadOnlyInline}} @@ -64,6 +28,17 @@ _This interface also inherits properties from its parent, {{domxref("SVGElement" _This interface does not provide any specific methods, but implements those of its parent, {{domxref("SVGElement")}}._ +## Static properties + +- `SVG_SPREADMETHOD_UNKNOWN` (0) + - : The type is not one of predefined types. It is invalid to attempt to define a new value of this type or to attempt to switch an existing value to this type. +- `SVG_SPREADMETHOD_PAD` (1) + - : Corresponds to value `pad`. +- `SVG_SPREADMETHOD_REFLECT` (2) + - : Corresponds to value `reflect`. +- `SVG_SPREADMETHOD_REPEAT` (3) + - : Corresponds to value `repeat`. + ## Specifications {{Specifications}} diff --git a/files/en-us/web/api/svggraphicselement/copy_event/index.md b/files/en-us/web/api/svggraphicselement/copy_event/index.md deleted file mode 100644 index 89b00676b6396aa..000000000000000 --- a/files/en-us/web/api/svggraphicselement/copy_event/index.md +++ /dev/null @@ -1,96 +0,0 @@ ---- -title: "SVGGraphicsElement: copy event" -short-title: copy -slug: Web/API/SVGGraphicsElement/copy_event -page-type: web-api-event -browser-compat: api.Element.copy_event ---- - -{{APIRef("SVG")}} - -The **`copy`** event fires on {{domxref("SVGGraphicsElement", "SVGGraphicsElements")}} when the user initiates a copy action through the browser's user interface. - -The event's default action is to copy the selection (if any) to the clipboard. - -A handler for this event can _modify_ the clipboard contents by calling {{domxref("DataTransfer.setData", "setData(format, data)")}} on the event's {{domxref("ClipboardEvent.clipboardData")}} property, and cancelling the event's default action using [`event.preventDefault()`](/en-US/docs/Web/API/Event/preventDefault). - -However, the handler cannot _read_ the clipboard data. - -It's possible to construct and dispatch a [synthetic](/en-US/docs/Web/Events/Creating_and_triggering_events) `copy` event, but this will not affect the system clipboard. - -## Syntax - -Use the event name in methods like {{domxref("EventTarget.addEventListener", "addEventListener()")}}, or set an event handler property. - -```js -addEventListener("copy", (event) => {}); - -oncopy = (event) => {}; -``` - -## Event type - -A {{domxref("ClipboardEvent")}}. Inherits from {{domxref("Event")}}. - -{{InheritanceDiagram("ClipboardEvent")}} - -## Example - -### HTML - -```html -<?xml version="1.0" encoding="UTF-8"?> -<svg - viewBox="0 0 100 30" - width="600" - height="320" - xmlns="http://www.w3.org/2000/svg"> - <text x="5" y="10" id="text-to-copy">Copy this text</text> - <foreignObject x="5" y="20" width="90" height="20"> - <input xmlns="http://www.w3.org/1999/xhtml" placeholder="Paste it here" /> - </foreignObject> -</svg> -``` - -### CSS - -```css -input { - font-size: 10px; - width: 100%; - height: 90%; - box-sizing: border-box; - border: 1px solid black; -} -``` - -### JavaScript - -```js -document.querySelector("text").addEventListener("copy", (evt) => { - evt.clipboardData.setData( - "text/plain", - document.getSelection().toString().toUpperCase(), - ); - evt.preventDefault(); -}); -``` - -### Result - -{{EmbedLiveSample("Example", "620", "340")}} - -## Specifications - -{{Specifications}} - -## Browser compatibility - -{{Compat}} - -## See also - -- Related events: [`cut`](/en-US/docs/Web/API/SVGGraphicsElement/cut_event), [`paste`](/en-US/docs/Web/API/SVGGraphicsElement/paste_event) -- This event on HTML {{domxref("Element")}} targets: [`copy`](/en-US/docs/Web/API/Element/copy_event) -- This event on {{domxref("Document")}} targets: [`copy`](/en-US/docs/Web/API/Document/copy_event) -- This event on {{domxref("Window")}} targets: [`copy`](/en-US/docs/Web/API/Window/copy_event) diff --git a/files/en-us/web/api/svggraphicselement/cut_event/index.md b/files/en-us/web/api/svggraphicselement/cut_event/index.md deleted file mode 100644 index 16d0155ccc8d798..000000000000000 --- a/files/en-us/web/api/svggraphicselement/cut_event/index.md +++ /dev/null @@ -1,54 +0,0 @@ ---- -title: "SVGGraphicsElement: cut event" -short-title: cut -slug: Web/API/SVGGraphicsElement/cut_event -page-type: web-api-event -browser-compat: api.Element.cut_event ---- - -{{APIRef("SVG")}} - -The **`cut`** event is fired on an {{domxref("SVGGraphicsElement")}} when the user has initiated a "cut" action through the browser's user interface. - -If the user attempts a cut action on uneditable content, the `cut` event still fires but the event object contains no data. - -The event's default action is to copy the current selection (if any) to the system clipboard and remove it from the document. - -A handler for this event can _modify_ the clipboard contents by calling [`setData(format, data)`](/en-US/docs/Web/API/DataTransfer/setData) on the event's [`ClipboardEvent.clipboardData`](/en-US/docs/Web/API/ClipboardEvent/clipboardData) property, and cancelling the default action using [`event.preventDefault()`](/en-US/docs/Web/API/Event/preventDefault). - -Note though that cancelling the default action will also prevent the document from being updated. So an event handler which wants to emulate the default action for "cut" while modifying the clipboard must also manually remove the selection from the document. - -The handler cannot _read_ the clipboard data. - -It's possible to construct and dispatch a [synthetic](/en-US/docs/Web/Events/Creating_and_triggering_events) `cut` event, but this will not affect the system clipboard or the document's contents. - -## Syntax - -Use the event name in methods like {{domxref("EventTarget.addEventListener", "addEventListener()")}}, or set an event handler property. - -```js -addEventListener("cut", (event) => {}); - -oncut = (event) => {}; -``` - -## Event type - -A {{domxref("ClipboardEvent")}}. Inherits from {{domxref("Event")}}. - -{{InheritanceDiagram("ClipboardEvent")}} - -## Specifications - -{{Specifications}} - -## Browser compatibility - -{{Compat}} - -## See also - -- Related events: [`copy`](/en-US/docs/Web/API/SVGGraphicsElement/copy_event), [`paste`](/en-US/docs/Web/API/SVGGraphicsElement/paste_event) -- This event on HTML {{domxref("Element")}} targets: [`cut`](/en-US/docs/Web/API/Element/cut_event) -- This event on {{domxref("Document")}} targets: [`cut`](/en-US/docs/Web/API/Document/cut_event) -- This event on {{domxref("Window")}} targets: [`cut`](/en-US/docs/Web/API/Window/cut_event) diff --git a/files/en-us/web/api/svggraphicselement/index.md b/files/en-us/web/api/svggraphicselement/index.md index bff880b8479b25e..a6d9f5de96efa1e 100644 --- a/files/en-us/web/api/svggraphicselement/index.md +++ b/files/en-us/web/api/svggraphicselement/index.md @@ -33,17 +33,6 @@ _This interface also inherits methods from its parent, {{domxref("SVGElement")}} - {{domxref("SVGGraphicsElement.getScreenCTM()")}} - : Returns a {{domxref("DOMMatrix")}} representing the matrix that transforms the current element's coordinate system to the coordinate system of the SVG viewport for the SVG document fragment. -## Events - -Listen to these events using [`addEventListener()`](/en-US/docs/Web/API/EventTarget/addEventListener) or by assigning an event listener to the equivalent `on...` handler property. - -- [`copy`](/en-US/docs/Web/API/SVGGraphicsElement/copy_event) - - : Fired when the user initiates a copy action through the browser's user interface. -- [`cut`](/en-US/docs/Web/API/SVGGraphicsElement/cut_event) - - : Fired when the user has initiated a "cut" action through the browser's user interface. -- [`paste`](/en-US/docs/Web/API/SVGGraphicsElement/paste_event) - - : Fires when the user has initiated a "paste" action through the browser's user interface. - ## Specifications {{Specifications}} diff --git a/files/en-us/web/api/svggraphicselement/paste_event/index.md b/files/en-us/web/api/svggraphicselement/paste_event/index.md deleted file mode 100644 index 086ddd90a4c1540..000000000000000 --- a/files/en-us/web/api/svggraphicselement/paste_event/index.md +++ /dev/null @@ -1,99 +0,0 @@ ---- -title: "SVGGraphicsElement: paste event" -short-title: paste -slug: Web/API/SVGGraphicsElement/paste_event -page-type: web-api-event -browser-compat: api.Element.paste_event ---- - -{{APIRef("SVG")}} - -The **`paste`** event is fired on an {{domxref("SVGGraphicsElement")}} when the user has initiated a "paste" action through the browser's user interface. - -If the cursor is in an editable context (for example, in a {{HTMLElement("textarea")}} or an element with [`contenteditable`](/en-US/docs/Web/HTML/Global_attributes/contenteditable) attribute set to `true`) then the default action is to insert the contents of the clipboard into the document at the cursor position. - -A handler for this event can access the clipboard contents by calling {{domxref("DataTransfer/getData", "getData()")}} on the event's `clipboardData` property. - -To override the default behavior (for example to insert some different data or a transformation of the clipboard contents) an event handler must cancel the default action using {{domxref("Event/preventDefault", "event.preventDefault()")}}, and then insert its desired data manually. - -It's possible to construct and dispatch a [synthetic](/en-US/docs/Web/Events/Creating_and_triggering_events) `paste` event, but this will not affect the document's contents. - -## Syntax - -Use the event name in methods like {{domxref("EventTarget.addEventListener", "addEventListener()")}}, or set an event handler property. - -```js -addEventListener("paste", (event) => {}); - -onpaste = (event) => {}; -``` - -## Event type - -A {{domxref("ClipboardEvent")}}. Inherits from {{domxref("Event")}}. - -{{InheritanceDiagram("ClipboardEvent")}} - -## Example - -### HTML - -```html -<?xml version="1.0" encoding="UTF-8"?> -<svg - viewBox="0 0 140 30" - width="600" - height="320" - xmlns="http://www.w3.org/2000/svg"> - <foreignObject x="5" y="-10" width="90" height="20"> - <input xmlns="http://www.w3.org/1999/xhtml" value="Copy this text" /> - </foreignObject> - <text x="5" y="30" id="element-to-paste-text" tabindex="1"> - Paste it here - </text> -</svg> -``` - -### CSS - -```css -input { - font-size: 10px; - width: 100%; - height: 90%; - box-sizing: border-box; - border: 1px solid black; -} -``` - -### JavaScript - -```js -document - .getElementById("element-to-paste-text") - .addEventListener("paste", (evt) => { - evt.target.textContent = evt.clipboardData - .getData("text/plain") - .toUpperCase(); - evt.preventDefault(); - }); -``` - -### Result - -{{EmbedLiveSample("Example", "620", "340")}} - -## Specifications - -{{Specifications}} - -## Browser compatibility - -{{Compat}} - -## See also - -- Related events: [`cut`](/en-US/docs/Web/API/SVGGraphicsElement/cut_event), [`copy`](/en-US/docs/Web/API/SVGGraphicsElement/copy_event) -- This event on HTML {{domxref("Element")}} targets: [`paste`](/en-US/docs/Web/API/Element/paste_event) -- This event on {{domxref("Document")}} targets: [`paste`](/en-US/docs/Web/API/Document/paste_event) -- This event on {{domxref("Window")}} targets: [`paste`](/en-US/docs/Web/API/Window/paste_event) diff --git a/files/en-us/web/api/svghkernelement/index.md b/files/en-us/web/api/svghkernelement/index.md deleted file mode 100644 index d60c74eea9e215c..000000000000000 --- a/files/en-us/web/api/svghkernelement/index.md +++ /dev/null @@ -1,36 +0,0 @@ ---- -title: SVGHKernElement -slug: Web/API/SVGHKernElement -page-type: web-api-interface -status: - - deprecated -browser-compat: api.SVGHKernElement ---- - -{{APIRef("SVG")}}{{deprecated_header}} - -The **`SVGHKernElement`** interface corresponds to the {{SVGElement("hkern")}} elements. - -Object-oriented access to the attributes of the {{SVGElement("hkern")}} element via the SVG DOM is not possible. - -{{InheritanceDiagram}} - -## Instance properties - -_This interface has no properties but inherits properties from its parent, {{domxref("SVGElement")}}._ - -## Instance methods - -_This interface has no methods but inherits methods from its parent, {{domxref("SVGElement")}}._ - -## Specifications - -{{Specifications}} - -## Browser compatibility - -{{Compat}} - -## See also - -- {{SVGElement("hkern")}} diff --git a/files/en-us/web/api/svgimageelement/crossorigin/index.md b/files/en-us/web/api/svgimageelement/crossorigin/index.md new file mode 100644 index 000000000000000..f1ce33dd13c16d9 --- /dev/null +++ b/files/en-us/web/api/svgimageelement/crossorigin/index.md @@ -0,0 +1,28 @@ +--- +title: "SVGImageElement: crossOrigin property" +short-title: crossOrigin +slug: Web/API/SVGImageElement/crossOrigin +page-type: web-api-instance-property +browser-compat: api.SVGImageElement.crossOrigin +--- + +{{APIRef("SVG")}} + +The **`crossOrigin`** property of the {{domxref("SVGImageElement")}} interface is a string which specifies the Cross-Origin Resource Sharing ({{Glossary("CORS")}}) setting to use when retrieving the image. It reflects the {{SVGAttr("crossorigin")}} content attribute of the given {{SVGElement("image")}} element. + +## Value + +A string which specifies the CORS mode used when fetching the image resource. Valid values are `"anonymous"` or `"use-credentials"`. If the `crossOrigin` property is set to any other value, it is the same as specifying `"anonymous"`. + +## Specifications + +{{Specifications}} + +## Browser compatibility + +{{Compat}} + +## See also + +- {{domxref("HTMLImageElement.crossOrigin")}} +- {{domxref("HTMLMediaElement.crossOrigin")}} diff --git a/files/en-us/web/api/svgimageelement/index.md b/files/en-us/web/api/svgimageelement/index.md index 430bddf2f044875..171ee249167b4fb 100644 --- a/files/en-us/web/api/svgimageelement/index.md +++ b/files/en-us/web/api/svgimageelement/index.md @@ -15,12 +15,14 @@ The **`SVGImageElement`** interface corresponds to the {{SVGElement("image")}} e _This interface also inherits properties from its parent, {{domxref("SVGGraphicsElement")}}._ -- {{domxref("SVGImageElement.href")}} {{ReadOnlyInline}} - - : An {{domxref("SVGAnimatedString")}} corresponding to the {{SVGAttr("href")}} or {{SVGAttr("xlink:href")}} {{deprecated_inline}} attribute of the given {{SVGElement("image")}} element. +- {{domxref("SVGImageElement.crossOrigin")}} + - : A string reflecting the {{SVGAttr("crossorigin")}} content attribute, which represents the CORS setting of the given {{SVGElement("image")}} element. - {{domxref("SVGImageElement.decoding")}} - - : Represents a hint given to the browser on how it should decode the image. If this value is provided, it must be one of the possible permitted values: `"sync"` to decode the image synchronously, `"async"` to decode it asynchronously, or `"auto"` to indicate no preference (which is the default). + - : Represents a hint given to the browser on how it should decode the image. - {{domxref("SVGImageElement.height")}} {{ReadOnlyInline}} - : An {{domxref("SVGAnimatedLength")}} corresponding to the {{SVGAttr("height")}} attribute of the given {{SVGElement("image")}} element. +- {{domxref("SVGImageElement.href")}} {{ReadOnlyInline}} + - : An {{domxref("SVGAnimatedString")}} corresponding to the {{SVGAttr("href")}} or {{SVGAttr("xlink:href")}} {{deprecated_inline}} attribute of the given {{SVGElement("image")}} element. - {{domxref("SVGImageElement.preserveAspectRatio")}} {{ReadOnlyInline}} - : An {{domxref("SVGAnimatedPreserveAspectRatio")}} corresponding to the {{SVGAttr("preserveAspectRatio")}} attribute of the given {{SVGElement("image")}} element. - {{domxref("SVGImageElement.width")}} {{ReadOnlyInline}} diff --git a/files/en-us/web/api/svglength/index.md b/files/en-us/web/api/svglength/index.md index b0c2a9de4bbf9fb..0b7a4624535d167 100644 --- a/files/en-us/web/api/svglength/index.md +++ b/files/en-us/web/api/svglength/index.md @@ -7,7 +7,7 @@ browser-compat: api.SVGLength {{APIRef("SVG")}} -The **`SVGLength`** interface correspond to the [\<length>](/en-US/docs/Web/SVG/Content_type#length) basic data type. +The **`SVGLength`** interface correspond to the [\<length>](/en-US/docs/Web/SVG/Guides/Content_type#length) basic data type. An `SVGLength` object can be designated as read only, which means that attempts to modify the object will result in an exception being thrown. @@ -22,80 +22,6 @@ An `SVGLength` object can be designated as read only, which means that attempts - {{domxref("SVGLength.valueInSpecifiedUnits", "valueInSpecifiedUnits")}} - : The value as a floating point value, in the units expressed by `unitType`. -<table class="no-markdown"> - <thead> - <tr> - <th scope="col">Name</th> - <th scope="col">Value</th> - <th scope="col">Description</th> - </tr> - </thead> - <tbody> - <tr> - <td><code>SVG_LENGTHTYPE_UNKNOWN</code></td> - <td><code>0</code></td> - <td> - The unit type is not one of predefined unit types. It is invalid to - attempt to define a new value of this type or to attempt to switch an - existing value to this type. - </td> - </tr> - <tr> - <td><code>SVG_LENGTHTYPE_NUMBER</code></td> - <td><code>1</code></td> - <td> - No unit type was provided (i.e., a unitless value was specified), which - indicates a value in user units. - </td> - </tr> - <tr> - <td><code>SVG_LENGTHTYPE_PERCENTAGE</code></td> - <td><code>2</code></td> - <td>A percentage value was specified.</td> - </tr> - <tr> - <td><code>SVG_LENGTHTYPE_EMS</code></td> - <td><code>3</code></td> - <td>A value was specified using the em units defined in CSS2.</td> - </tr> - <tr> - <td><code>SVG_LENGTHTYPE_EXS</code></td> - <td><code>4</code></td> - <td>A value was specified using the ex units defined in CSS2.</td> - </tr> - <tr> - <td><code>SVG_LENGTHTYPE_PX</code></td> - <td><code>5</code></td> - <td>A value was specified using the px units defined in CSS2.</td> - </tr> - <tr> - <td><code>SVG_LENGTHTYPE_CM</code></td> - <td><code>6</code></td> - <td>A value was specified using the cm units defined in CSS2.</td> - </tr> - <tr> - <td><code>SVG_LENGTHTYPE_MM</code></td> - <td><code>7</code></td> - <td>A value was specified using the mm units defined in CSS2.</td> - </tr> - <tr> - <td><code>SVG_LENGTHTYPE_IN</code></td> - <td><code>8</code></td> - <td>A value was specified using the in units defined in CSS2.</td> - </tr> - <tr> - <td><code>SVG_LENGTHTYPE_PT</code></td> - <td><code>9</code></td> - <td>A value was specified using the pt units defined in CSS2.</td> - </tr> - <tr> - <td><code>SVG_LENGTHTYPE_PC</code></td> - <td><code>10</code></td> - <td>A value was specified using the pc units defined in CSS2.</td> - </tr> - </tbody> -</table> - ## Instance methods - {{domxref("SVGLength.convertToSpecifiedUnits", "convertToSpecifiedUnits()")}} @@ -103,6 +29,31 @@ An `SVGLength` object can be designated as read only, which means that attempts - {{domxref("SVGLength.newValueSpecifiedUnits", "newValueSpecifiedUnits()")}} - : Reset the value as a number with an associated `unitType`, thereby replacing the values for all of the attributes on the object. +## Static properties + +- `SVG_LENGTHTYPE_UNKNOWN` (0) + - : The unit type is not one of predefined unit types. It is invalid to attempt to define a new value of this type or to attempt to switch an existing value to this type. +- `SVG_LENGTHTYPE_NUMBER` (1) + - : No unit type was provided (i.e., a unitless value was specified), which indicates a value in user units. +- `SVG_LENGTHTYPE_PERCENTAGE` (2) + - : A percentage value was specified. +- `SVG_LENGTHTYPE_EMS` (3) + - : A value was specified using the `em` units. +- `SVG_LENGTHTYPE_EXS` (4) + - : A value was specified using the `ex` units. +- `SVG_LENGTHTYPE_PX` (5) + - : A value was specified using the `px` units. +- `SVG_LENGTHTYPE_CM` (6) + - : A value was specified using the `cm` units. +- `SVG_LENGTHTYPE_MM` (7) + - : A value was specified using the `mm` units. +- `SVG_LENGTHTYPE_IN` (8) + - : A value was specified using the `in` units. +- `SVG_LENGTHTYPE_PT` (9) + - : A value was specified using the `pt` units. +- `SVG_LENGTHTYPE_PC` (10) + - : A value was specified using the `pc` units. + ## Example ```xml @@ -110,24 +61,24 @@ An `SVGLength` object can be designated as read only, which means that attempts <script><![CDATA[ function start() { const rect = document.getElementById("myRect"); - const val = rect.x.baseVal; + const val = rect.x.baseVal; // read x in pixel and cm units - console.log("value: " + val.value + - ", valueInSpecifiedUnits: " + val.unitType + ": " + val.valueInSpecifiedUnits + - ", valueAsString: " + val.valueAsString); + console.log( + `value: ${val.value}, valueInSpecifiedUnits: ${val.valueInSpecifiedUnits} (${val.unitType}), valueAsString: ${val.valueAsString}`, + ); // set x = 20pt and read it out in pixel and pt units val.newValueSpecifiedUnits(SVGLength.SVG_LENGTHTYPE_PT, 20); - console.log("value: " + val.value + - ", valueInSpecifiedUnits " + val.unitType + ": " + val.valueInSpecifiedUnits + - ", valueAsString: " + val.valueAsString); + console.log( + `value: ${val.value}, valueInSpecifiedUnits: ${val.valueInSpecifiedUnits} (${val.unitType}), valueAsString: ${val.valueAsString}`, + ); // convert x = 20pt to inches and read out in pixel and inch units val.convertToSpecifiedUnits(SVGLength.SVG_LENGTHTYPE_IN); - console.log("value: " + val.value + - ", valueInSpecifiedUnits " + val.unitType + ": " + val.valueInSpecifiedUnits + - ", valueAsString: " + val.valueAsString); + console.log( + `value: ${val.value}, valueInSpecifiedUnits: ${val.valueInSpecifiedUnits} (${val.unitType}), valueAsString: ${val.valueAsString}`, + ); } ]]></script> <rect id="myRect" diff --git a/files/en-us/web/api/svglength/value/index.md b/files/en-us/web/api/svglength/value/index.md index 80d665133257016..9e34d14ec1b5b60 100644 --- a/files/en-us/web/api/svglength/value/index.md +++ b/files/en-us/web/api/svglength/value/index.md @@ -8,7 +8,7 @@ browser-compat: api.SVGLength.value {{APIRef("SVG")}} -The `value` property of the {{domxref("SVGLength")}} interface represents the floating point value of the [\<length>](/en-US/docs/Web/SVG/Content_type#length) in user units. +The `value` property of the {{domxref("SVGLength")}} interface represents the floating point value of the [\<length>](/en-US/docs/Web/SVG/Guides/Content_type#length) in user units. Setting this attribute will cause {{domxref("SVGLength.valueInSpecifiedUnits")}} and {{domxref("SVGLength.valueAsString")}} to be updated automatically to reflect this setting. diff --git a/files/en-us/web/api/svglength/valueasstring/index.md b/files/en-us/web/api/svglength/valueasstring/index.md index e1fa69fc706554f..979188499de57dd 100644 --- a/files/en-us/web/api/svglength/valueasstring/index.md +++ b/files/en-us/web/api/svglength/valueasstring/index.md @@ -8,7 +8,7 @@ browser-compat: api.SVGLength.valueAsString {{APIRef("SVG")}} -The `valueAsString` property of the {{domxref("SVGLength")}} interface represents the [\<length>](/en-US/docs/Web/SVG/Content_type#length)'s value as a strin\*, in the units expressed by {{domxref("SVGLength.unitType", "unitType")}}. +The `valueAsString` property of the {{domxref("SVGLength")}} interface represents the [\<length>](/en-US/docs/Web/SVG/Guides/Content_type#length)'s value as a string, in the units expressed by {{domxref("SVGLength.unitType", "unitType")}}. Setting this attribute will cause {{domxref("SVGLength.value", "value")}}, {{domxref("SVGLength.valueInSpecifiedUnits", "valueInSpecifiedUnits")}}, and {{domxref("SVGLength.unitType", "unitType")}} to be updated automatically to reflect this setting. @@ -48,6 +48,6 @@ console.log(length.value); // Output: 100 ## See also -- [`<number>`](/en-US/docs/Web/SVG/Content_type#number) -- [`<length>`](/en-US/docs/Web/SVG/Content_type#length) +- [`<number>`](/en-US/docs/Web/SVG/Guides/Content_type#number) +- [`<length>`](/en-US/docs/Web/SVG/Guides/Content_type#length) - {{domxref("SVGAnimatedLength")}} diff --git a/files/en-us/web/api/svglengthlist/index.md b/files/en-us/web/api/svglengthlist/index.md index 43ae4ffd7cb9c06..cd489bae0ed9bc5 100644 --- a/files/en-us/web/api/svglengthlist/index.md +++ b/files/en-us/web/api/svglengthlist/index.md @@ -85,7 +85,7 @@ function resetSpacing() { function printList() { output.textContent = ""; for (let i = 0; i < list.length; i++) { - output.innerText += list.getItem(i).value + "\n"; + output.innerText += `${list.getItem(i).value}\n`; } } printList(); diff --git a/files/en-us/web/api/svglengthlist/numberofitems/index.md b/files/en-us/web/api/svglengthlist/numberofitems/index.md index 1c06cae20d4f8de..f88903678c0269b 100644 --- a/files/en-us/web/api/svglengthlist/numberofitems/index.md +++ b/files/en-us/web/api/svglengthlist/numberofitems/index.md @@ -8,7 +8,7 @@ browser-compat: api.SVGLengthList.numberOfItems {{APIRef("SVG")}} -The **`numberOfItems`** property of the {{domxref("SVGLengthList")}} interface returns the number of items in the list. {{domxref("SVGLengthList.length", "length")}} is an alias of of it. +The **`numberOfItems`** property of the {{domxref("SVGLengthList")}} interface returns the number of items in the list. {{domxref("SVGLengthList.length", "length")}} is an alias of it. ## Value diff --git a/files/en-us/web/api/svglineargradientelement/x1/index.md b/files/en-us/web/api/svglineargradientelement/x1/index.md index abd9eb101c60b79..040b1f4787fe0ee 100644 --- a/files/en-us/web/api/svglineargradientelement/x1/index.md +++ b/files/en-us/web/api/svglineargradientelement/x1/index.md @@ -10,7 +10,7 @@ browser-compat: api.SVGLinearGradientElement.x1 The **`x1`** read-only property of the {{domxref("SVGLinearGradientElement")}} interface describes the x-axis coordinate of the start point of the gradient as an {{domxref("SVGAnimatedLength")}}. It reflects the computed value of the {{SVGAttr("x1")}} attribute on the {{SVGElement("linearGradient")}} element. -The attribute value is a [`<length>`](/en-US/docs/Web/SVG/Content_type#length), [`<percentage>`](/en-US/docs/Web/SVG/Content_type#percentage), or [`<number>`](/en-US/docs/Web/SVG/Content_type#number). The numeric value of the {{domxref("SVGAnimatedLength.baseVal")}} is the x-coordinate of the gradient's starting point in the user coordinate system. +The attribute value is a [`<length>`](/en-US/docs/Web/SVG/Guides/Content_type#length), [`<percentage>`](/en-US/docs/Web/SVG/Guides/Content_type#percentage), or [`<number>`](/en-US/docs/Web/SVG/Guides/Content_type#number). The numeric value of the {{domxref("SVGAnimatedLength.baseVal")}} is the x-coordinate of the gradient's starting point in the user coordinate system. ## Value diff --git a/files/en-us/web/api/svglineargradientelement/x2/index.md b/files/en-us/web/api/svglineargradientelement/x2/index.md index 125c0e754358dd5..7bb00048385639a 100644 --- a/files/en-us/web/api/svglineargradientelement/x2/index.md +++ b/files/en-us/web/api/svglineargradientelement/x2/index.md @@ -10,7 +10,7 @@ browser-compat: api.SVGLinearGradientElement.x2 The **`x2`** read-only property of the {{domxref("SVGLinearGradientElement")}} interface describes the x-axis coordinate of the start point of the gradient as an {{domxref("SVGAnimatedLength")}}. It reflects the computed value of the {{SVGAttr("x2")}} attribute on the {{SVGElement("linearGradient")}} element. -The attribute value is a [`<length>`](/en-US/docs/Web/SVG/Content_type#length), [`<percentage>`](/en-US/docs/Web/SVG/Content_type#percentage), or [`<number>`](/en-US/docs/Web/SVG/Content_type#number). The numeric value of the {{domxref("SVGAnimatedLength.baseVal")}} is the x-coordinate of the gradient's end point in the user coordinate system. +The attribute value is a [`<length>`](/en-US/docs/Web/SVG/Guides/Content_type#length), [`<percentage>`](/en-US/docs/Web/SVG/Guides/Content_type#percentage), or [`<number>`](/en-US/docs/Web/SVG/Guides/Content_type#number). The numeric value of the {{domxref("SVGAnimatedLength.baseVal")}} is the x-coordinate of the gradient's end point in the user coordinate system. ## Value diff --git a/files/en-us/web/api/svglineargradientelement/y1/index.md b/files/en-us/web/api/svglineargradientelement/y1/index.md index 0c10de7f07b6ab8..1432fc625718158 100644 --- a/files/en-us/web/api/svglineargradientelement/y1/index.md +++ b/files/en-us/web/api/svglineargradientelement/y1/index.md @@ -10,7 +10,7 @@ browser-compat: api.SVGLinearGradientElement.y1 The **`y1`** read-only property of the {{domxref("SVGLinearGradientElement")}} interface describes the y-axis coordinate of the start point of the gradient as an {{domxref("SVGAnimatedLength")}}. It reflects the computed value of the {{SVGAttr("y1")}} attribute on the {{SVGElement("linearGradient")}} element. -The attribute value is a [`<length>`](/en-US/docs/Web/SVG/Content_type#length), [`<percentage>`](/en-US/docs/Web/SVG/Content_type#percentage), or [`<number>`](/en-US/docs/Web/SVG/Content_type#number). The numeric value of the {{domxref("SVGAnimatedLength.baseVal")}} is the y-coordinate of the gradient's starting point in the user coordinate system. +The attribute value is a [`<length>`](/en-US/docs/Web/SVG/Guides/Content_type#length), [`<percentage>`](/en-US/docs/Web/SVG/Guides/Content_type#percentage), or [`<number>`](/en-US/docs/Web/SVG/Guides/Content_type#number). The numeric value of the {{domxref("SVGAnimatedLength.baseVal")}} is the y-coordinate of the gradient's starting point in the user coordinate system. ## Value diff --git a/files/en-us/web/api/svglineargradientelement/y2/index.md b/files/en-us/web/api/svglineargradientelement/y2/index.md index 51b7b7ff9f32978..27d376a1c0f7caa 100644 --- a/files/en-us/web/api/svglineargradientelement/y2/index.md +++ b/files/en-us/web/api/svglineargradientelement/y2/index.md @@ -10,7 +10,7 @@ browser-compat: api.SVGLinearGradientElement.y2 The **`y2`** read-only property of the {{domxref("SVGLinearGradientElement")}} interface describes the y-axis coordinate of the start point of the gradient as an {{domxref("SVGAnimatedLength")}}. It reflects the computed value of the {{SVGAttr("y2")}} attribute on the {{SVGElement("linearGradient")}} element. -The attribute value is a [`<length>`](/en-US/docs/Web/SVG/Content_type#length), [`<percentage>`](/en-US/docs/Web/SVG/Content_type#percentage), or [`<number>`](/en-US/docs/Web/SVG/Content_type#number). The numeric value of the {{domxref("SVGAnimatedLength.baseVal")}} is the y-coordinate of the gradient's end point in the user coordinate system. +The attribute value is a [`<length>`](/en-US/docs/Web/SVG/Guides/Content_type#length), [`<percentage>`](/en-US/docs/Web/SVG/Guides/Content_type#percentage), or [`<number>`](/en-US/docs/Web/SVG/Guides/Content_type#number). The numeric value of the {{domxref("SVGAnimatedLength.baseVal")}} is the y-coordinate of the gradient's end point in the user coordinate system. ## Value diff --git a/files/en-us/web/api/svglineelement/x1/index.md b/files/en-us/web/api/svglineelement/x1/index.md index 7c949f84723f2ad..9b961b0d3ad2fcc 100644 --- a/files/en-us/web/api/svglineelement/x1/index.md +++ b/files/en-us/web/api/svglineelement/x1/index.md @@ -10,7 +10,7 @@ browser-compat: api.SVGLineElement.x1 The **`x1`** read-only property of the {{domxref("SVGLineElement")}} interface describes the start of the SVG line along the x-axis as an {{domxref("SVGAnimatedLength")}}. It reflects the {{SVGElement("line")}} element's {{SVGAttr("x1")}} geometric attribute. -The attribute value is a [`<length>`](/en-US/docs/Web/SVG/Content_type#length), [`<percentage>`](/en-US/docs/Web/SVG/Content_type#percentage), or [`<number>`](/en-US/docs/Web/SVG/Content_type#number). The numeric value of the {{domxref("SVGAnimatedLength.baseVal")}} is that start position as a length along the x-axis in user coordinate system units. +The attribute value is a [`<length>`](/en-US/docs/Web/SVG/Guides/Content_type#length), [`<percentage>`](/en-US/docs/Web/SVG/Guides/Content_type#percentage), or [`<number>`](/en-US/docs/Web/SVG/Guides/Content_type#number). The numeric value of the {{domxref("SVGAnimatedLength.baseVal")}} is that start position as a length along the x-axis in user coordinate system units. ## Value diff --git a/files/en-us/web/api/svglineelement/x2/index.md b/files/en-us/web/api/svglineelement/x2/index.md index c9c9d8214501baa..1a7793291ccd67c 100644 --- a/files/en-us/web/api/svglineelement/x2/index.md +++ b/files/en-us/web/api/svglineelement/x2/index.md @@ -10,7 +10,7 @@ browser-compat: api.SVGLineElement.x2 The **`x2`** read-only property of the {{domxref("SVGLineElement")}} interface describes the x-axis coordinate value of the end of a line as an {{domxref("SVGAnimatedLength")}}. It reflects the {{SVGElement("line")}} element's {{SVGAttr("x2")}} geometric attribute. -The attribute value is a [`<length>`](/en-US/docs/Web/SVG/Content_type#length), [`<percentage>`](/en-US/docs/Web/SVG/Content_type#percentage), or [`<number>`](/en-US/docs/Web/SVG/Content_type#number). The numeric value of the {{domxref("SVGAnimatedLength.baseVal")}} is that end position along the x-axis in user coordinate system units. +The attribute value is a [`<length>`](/en-US/docs/Web/SVG/Guides/Content_type#length), [`<percentage>`](/en-US/docs/Web/SVG/Guides/Content_type#percentage), or [`<number>`](/en-US/docs/Web/SVG/Guides/Content_type#number). The numeric value of the {{domxref("SVGAnimatedLength.baseVal")}} is that end position along the x-axis in user coordinate system units. ## Value diff --git a/files/en-us/web/api/svglineelement/y1/index.md b/files/en-us/web/api/svglineelement/y1/index.md index 7919bfd75f795e4..d2d8a8937da4c43 100644 --- a/files/en-us/web/api/svglineelement/y1/index.md +++ b/files/en-us/web/api/svglineelement/y1/index.md @@ -10,7 +10,7 @@ browser-compat: api.SVGLineElement.y1 The **`y1`** read-only property of the {{domxref("SVGLineElement")}} interface describes the start of the SVG line along the y-axis as an {{domxref("SVGAnimatedLength")}}. It reflects the {{SVGElement("line")}} element's {{SVGAttr("y1")}} geometric attribute. -The attribute value is a [`<length>`](/en-US/docs/Web/SVG/Content_type#length), [`<percentage>`](/en-US/docs/Web/SVG/Content_type#percentage), or [`<number>`](/en-US/docs/Web/SVG/Content_type#number). The numeric value of the {{domxref("SVGAnimatedLength.baseVal")}} is that start position as a length along the y-axis in user coordinate system units. +The attribute value is a [`<length>`](/en-US/docs/Web/SVG/Guides/Content_type#length), [`<percentage>`](/en-US/docs/Web/SVG/Guides/Content_type#percentage), or [`<number>`](/en-US/docs/Web/SVG/Guides/Content_type#number). The numeric value of the {{domxref("SVGAnimatedLength.baseVal")}} is that start position as a length along the y-axis in user coordinate system units. ## Value diff --git a/files/en-us/web/api/svglineelement/y2/index.md b/files/en-us/web/api/svglineelement/y2/index.md index e20cc64e71435a4..607d460cc9453ec 100644 --- a/files/en-us/web/api/svglineelement/y2/index.md +++ b/files/en-us/web/api/svglineelement/y2/index.md @@ -10,7 +10,7 @@ browser-compat: api.SVGLineElement.y2 The **`y2`** read-only property of the {{domxref("SVGLineElement")}} interface describes the v-axis coordinate value of the end of a line as an {{domxref("SVGAnimatedLength")}}. It reflects the {{SVGElement("line")}} element's {{SVGAttr("y2")}} geometric attribute. -The attribute value is a [`<length>`](/en-US/docs/Web/SVG/Content_type#length), [`<percentage>`](/en-US/docs/Web/SVG/Content_type#percentage), or [`<number>`](/en-US/docs/Web/SVG/Content_type#number). The numeric value of the {{domxref("SVGAnimatedLength.baseVal")}} is that end position along the y-axis in user coordinate system units. +The attribute value is a [`<length>`](/en-US/docs/Web/SVG/Guides/Content_type#length), [`<percentage>`](/en-US/docs/Web/SVG/Guides/Content_type#percentage), or [`<number>`](/en-US/docs/Web/SVG/Guides/Content_type#number). The numeric value of the {{domxref("SVGAnimatedLength.baseVal")}} is that end position along the y-axis in user coordinate system units. ## Value diff --git a/files/en-us/web/api/svgmarkerelement/viewbox/index.md b/files/en-us/web/api/svgmarkerelement/viewbox/index.md index 4f509f17bf9876d..980cd0c93663967 100644 --- a/files/en-us/web/api/svgmarkerelement/viewbox/index.md +++ b/files/en-us/web/api/svgmarkerelement/viewbox/index.md @@ -37,8 +37,8 @@ This example demonstrates how to return the value of the `width` set for the {{S ``` ```js -let marker = document.getElementById("arrow"); -console.log(marker.viewBox.baseVal.width); //10 +const marker = document.getElementById("arrow"); +console.log(marker.viewBox.baseVal.width); // 10 ``` ## Specifications diff --git a/files/en-us/web/api/svgmissingglyphelement/index.md b/files/en-us/web/api/svgmissingglyphelement/index.md deleted file mode 100644 index d2f872123c4e316..000000000000000 --- a/files/en-us/web/api/svgmissingglyphelement/index.md +++ /dev/null @@ -1,36 +0,0 @@ ---- -title: SVGMissingGlyphElement -slug: Web/API/SVGMissingGlyphElement -page-type: web-api-interface -status: - - deprecated -browser-compat: api.SVGMissingGlyphElement ---- - -{{APIRef("SVG")}}{{deprecated_header}} - -The **`SVGMissingGlyphElement`** interface corresponds to the {{SVGElement("missing-glyph")}} elements. - -Object-oriented access to the attributes of the {{SVGElement("missing-glyph")}} element via the SVG DOM is not possible. - -{{InheritanceDiagram}} - -## Instance properties - -_This interface has no properties but inherits properties from its parent, {{domxref("SVGElement")}}._ - -## Instance methods - -_This interface has no methods but inherits methods from its parent, {{domxref("SVGElement")}}._ - -## Specifications - -{{Specifications}} - -## Browser compatibility - -{{Compat}} - -## See also - -- {{SVGElement("missing-glyph")}} diff --git a/files/en-us/web/api/svgnumberlist/numberofitems/index.md b/files/en-us/web/api/svgnumberlist/numberofitems/index.md index a57f7230cbe143a..db2ca78a94c5015 100644 --- a/files/en-us/web/api/svgnumberlist/numberofitems/index.md +++ b/files/en-us/web/api/svgnumberlist/numberofitems/index.md @@ -8,7 +8,7 @@ browser-compat: api.SVGNumberList.numberOfItems {{APIRef("SVG")}} -The **`numberOfItems`** property of the {{domxref("SVGNumberList")}} interface returns the number of items in the list. {{domxref("SVGNumberList.length", "length")}} is an alias of of it. +The **`numberOfItems`** property of the {{domxref("SVGNumberList")}} interface returns the number of items in the list. {{domxref("SVGNumberList.length", "length")}} is an alias of it. ## Value diff --git a/files/en-us/web/api/svgpathelement/getpathdata/index.md b/files/en-us/web/api/svgpathelement/getpathdata/index.md new file mode 100644 index 000000000000000..6f97c45ae084b11 --- /dev/null +++ b/files/en-us/web/api/svgpathelement/getpathdata/index.md @@ -0,0 +1,89 @@ +--- +title: "SVGPathElement: getPathData() method" +short-title: getPathData() +slug: Web/API/SVGPathElement/getPathData +page-type: web-api-instance-method +status: + - experimental +browser-compat: api.SVGPathElement.getPathData +--- + +{{APIRef("SVG")}}{{SeeCompatTable}} + +The **`SVGPathElement.getPathData()`** method returns the sequence of path segments that corresponds to the path data, optionally normalizing the values and segment types. + +## Syntax + +```js-nolint +getPathData() +getPathData(options) +``` + +### Parameters + +- `options` {{optional_inline}} + + - : An optional object for controlling aspects of the path data retrieval process. This object may contain the following properties: + + - `normalize` {{optional_inline}} + - : A boolean value indicating whether the returned sequence of path segments is converted to the base set of [absolute commands](/en-US/docs/Web/SVG/Reference/Attribute/d#path_commands) (`'M'`, `'L'`, `'C'` and `'Z'`), with the values adjusted accordingly. + +### Return value + +An array of path segments corresponding to the path data. If no valid path data exists, returns an empty sequence. + +Each path segment is an object with the following properties: + +- `type` + - : A [path commands](/en-US/docs/Web/SVG/Reference/Attribute/d#path_commands). + If [`options.normalize`](#normalize) is true this will be one of the absolute commands: `'M'`, `'L'`, `'C'` and `'Z'`. +- `values` + - : An array or value containing the parameters for the corresponding command. + +## Examples + +### Get path data + +Consider the following `<path>` element, drawing a square: + +```xml +<svg xmlns="http://www.w3.org/2000/svg" width="64" height="64"> + <path d="M0,0 h64 v64 h-64 z" /> +</svg> +``` + +The `getPathData()` method will return an array with the raw path data, the same as it's set in the `d` attribute. With the `normalize: true` option set, it will return path data normalized to the base set of path commands: + +```js +const path = document.querySelector("path"); + +console.log(path.getPathData()); + +// Output: raw path data: +// [ +// { type: "M", values: [0, 0] }, +// { type: "h", values: [64] }, +// { type: "v", values: [64] }, +// { type: "h", values: [-64] }, +// { type: "Z", values: [] } +// ] + +console.log(path.getPathData({ normalize: true })); + +// Output: normalized path data: +// [ +// { type: "M", values: [0, 0] }, +// { type: "L", values: [64, 0] }, +// { type: "L", values: [64, 64] }, +// { type: "L", values: [0, 64] }, +// { type: "Z", values: [] } +// ] +``` + +## Specifications + +{{Specifications}} + +## Browser compatibility + +{{Compat}} diff --git a/files/en-us/web/api/svgpathelement/getpathsegmentatlength/index.md b/files/en-us/web/api/svgpathelement/getpathsegmentatlength/index.md new file mode 100644 index 000000000000000..451ce01d208ccd9 --- /dev/null +++ b/files/en-us/web/api/svgpathelement/getpathsegmentatlength/index.md @@ -0,0 +1,70 @@ +--- +title: "SVGPathElement: getPathSegmentAtLength() method" +short-title: getPathSegmentAtLength() +slug: Web/API/SVGPathElement/getPathSegmentAtLength +page-type: web-api-instance-method +status: + - experimental +browser-compat: api.SVGPathElement.getPathSegmentAtLength +--- + +{{APIRef("SVG")}}{{SeeCompatTable}} + +The **`getPathSegmentAtLength()`** method of the {{domxref("SVGPathElement")}} interface returns the path segment at a given distance along the path. + +## Syntax + +```js-nolint +getPathSegmentAtLength(distance) +``` + +### Parameters + +- `distance` + + - : A number indicating the distance along the path. + +### Return value + +A path segment object. If no valid segment exists, returns null. + +Segment object has the following properties: + +- `type` + - : A [path commands](/en-US/docs/Web/SVG/Reference/Attribute/d#path_commands). +- `values` + - : An array or value containing the parameters for the corresponding command. + +## Examples + +### Get path segment + +Consider the following `<path>` element, drawing a square: + +```xml +<svg xmlns="http://www.w3.org/2000/svg" width="64" height="64"> + <path d="M0,0 h64 v64 h-64 z" /> +</svg> +``` + +The `getPathSegmentAtLength()` method will return an object that represents the `v64` segment that lays 65px along the path: + +```js +const path = document.querySelector("path"); + +console.log(path.getPathSegmentAtLength(65)); + +// Output: path segment +// { +// type: "v", +// values: [64] +// } +``` + +## Specifications + +{{Specifications}} + +## Browser compatibility + +{{Compat}} diff --git a/files/en-us/web/api/svgpathelement/getpointatlength/index.md b/files/en-us/web/api/svgpathelement/getpointatlength/index.md new file mode 100644 index 000000000000000..de6d67b59643330 --- /dev/null +++ b/files/en-us/web/api/svgpathelement/getpointatlength/index.md @@ -0,0 +1,112 @@ +--- +title: "SVGPathElement: getPointAtLength() method" +short-title: getPointAtLength() +slug: Web/API/SVGPathElement/getPointAtLength +page-type: web-api-instance-method +browser-compat: api.SVGPathElement.getPointAtLength +--- + +{{APIRef("SVG")}} + +The **`getPointAtLength()`** method of the {{domxref("SVGPathElement")}} interface returns the point at a given distance along the path. + +## Syntax + +```js-nolint +getPointAtLength(distance) +``` + +### Parameters + +- `distance` + + - : A number indicating the distance along the path + +### Return value + +A {{domxref("DOMPoint")}} indicating the point at a given distance along the path. + +### Examples + +#### Getting the midpoint of a `<path>` + +In this example, we determine the midpoint of a path by getting the point that is half way along the length of the path. + +We define an SVG that includes two paths: a basic line and a complex heart shape. + +The path that creates the heart is approximately 275 units long. + +```html +<svg width="200" height="100"> + <path + id="heart" + fill="red" + d="M 10,30 + A 20,20 0,0,1 50,30 + A 20,20 0,0,1 90,30 + Q 90,60 50,90 + Q 10,60 10,30 z" /> + <path id="line" d="M 0,30 h100" stroke="black" /> +</svg> +``` + +The line is horizontal, starting at `0, 30` and is 100 units long. +The path of the heart starts at `10, 30` and is approximately 275 units long. + +```html hidden +<pre id="log"></pre> +``` + +```css hidden +#log { + height: 70px; + overflow: scroll; + padding: 0.5rem; + border: 1px solid black; +} +``` + +```js hidden +const logElement = document.querySelector("#log"); +function log(text) { + logElement.innerText = `${logElement.innerText}${text}\n`; + logElement.scrollTop = logElement.scrollHeight; +} +``` + +We know the length of the line is 100 units, and hence that `50` is the mid point. +We use the {{domxref("SVGPathElement.getTotalLength()")}} method to get the length of the heart's path, dividing it by `2` to get the mid-point distance. +We then use the `getPointAtLength()` method to return the mid point as a `DOMPoint`. +We display the `x` and `y` coordinates for each mid point. + +```js +const basicPath = document.getElementById("line"); +const complexPath = document.getElementById("heart"); + +// Get the length of the heart and divide by 2 +const halfLength = complexPath.getTotalLength() / 2; + +// Access the getPointAtLength property +const basicMidPoint = basicPath.getPointAtLength(50); +const complexMidPoint = complexPath.getPointAtLength(halfLength); + +// The base value of the pathLength attribute +log(`Line mid point: ${basicMidPoint.x}, ${basicMidPoint.y}`); +log(`Heart mid point: ${complexMidPoint.x}, ${complexMidPoint.y}`); +``` + +{{EmbedLiveSample('Getting the total length of a `<path>`',"100%","220px")}} + +## Specifications + +{{Specifications}} + +## Browser compatibility + +{{Compat}} + +## See also + +- {{domxref("SVGPathElement.getTotalLength()")}} +- {{domxref("DOMPoint.x")}} +- {{domxref("DOMPoint.y")}} diff --git a/files/en-us/web/api/svgpathelement/gettotallength/index.md b/files/en-us/web/api/svgpathelement/gettotallength/index.md new file mode 100644 index 000000000000000..8fc2af49c148176 --- /dev/null +++ b/files/en-us/web/api/svgpathelement/gettotallength/index.md @@ -0,0 +1,89 @@ +--- +title: "SVGPathElement: getTotalLength() method" +short-title: getTotalLength() +slug: Web/API/SVGPathElement/getTotalLength +page-type: web-api-instance-method +browser-compat: api.SVGPathElement.getTotalLength +--- + +{{APIRef("SVG")}} + +The **`getTotalLength()`** method of the {{domxref("SVGPathElement")}} interface returns the user agent's computed value for the total length of the path in user units. + +## Syntax + +```js-nolint +getTotalLength() +``` + +### Parameters + +None. + +### Return value + +A number indicating the total length of the path in user units. + +### Examples + +### Getting the total length of a `<path>` + +In this example, we get the total length of two paths: a basic line and a heart shape. + +```html +<svg width="200" height="100"> + <path + id="heart" + fill="red" + d="M 10,30 + A 20,20 0,0,1 50,30 + A 20,20 0,0,1 90,30 + Q 90,60 50,90 + Q 10,60 10,30 z" /> + <path id="line" d="M 0,30 h100" stroke="black" /> +</svg> +``` + +```html hidden +<pre id="log"></pre> +``` + +```css hidden +#log { + height: 70px; + overflow: scroll; + padding: 0.5rem; + border: 1px solid black; +} +``` + +```js hidden +const logElement = document.querySelector("#log"); +function log(text) { + logElement.innerText = `${logElement.innerText}${text}\n`; + logElement.scrollTop = logElement.scrollHeight; +} +``` + +```js +const complexPath = document.getElementById("heart"); +const basicPath = document.getElementById("line"); + +// Access the pathLength property +const complexPathLength = complexPath.getTotalLength(); +const basicPathLength = basicPath.getTotalLength(); + +// The base value of the pathLength attribute +log(`complexPathLength: ${complexPathLength}`); +log(`basicPathLength: ${basicPathLength}`); +``` + +{{EmbedLiveSample('Getting the total length of a `<path>`',"100%","220px")}} + +## Specifications + +{{Specifications}} + +## Browser compatibility + +{{Compat}} diff --git a/files/en-us/web/api/svgpathelement/index.md b/files/en-us/web/api/svgpathelement/index.md index 56c873204ae3923..80490f193abdf95 100644 --- a/files/en-us/web/api/svgpathelement/index.md +++ b/files/en-us/web/api/svgpathelement/index.md @@ -18,10 +18,26 @@ The **`SVGPathElement`** interface corresponds to the {{SVGElement("path")}} ele _This interface inherits properties from its parent, {{domxref("SVGGeometryElement")}}._ +- {{domxref("SVGPathElement.pathLength")}} {{ReadOnlyInline}} + - : This property reflects the {{SVGAttr("pathLength")}} attribute. + ## Instance methods _This interface also inherits methods from its parent, {{domxref("SVGGeometryElement")}}._ +- {{domxref("SVGPathElement.getPathData()")}} {{experimental_inline}} + - : Returns the sequence of path segments that corresponds to the path data, optionally normalizing the values and segment types. +- {{domxref("SVGPathElement.getPointAtLength()")}} + - : Returns the point at a given distance along the path. +- {{domxref("SVGPathElement.getTotalLength()")}} + - : Returns the user agent's computed value for the total length of the path in user units. +- {{domxref("SVGPathElement.setPathData()")}} {{experimental_inline}} + - : Sets the sequence of path segments as the new path data. +- {{domxref("SVGPathElement.getPathSegmentAtLength()")}} {{experimental_inline}} + - : Returns the segment at a given distance along the path. + +### Deprecated methods + - {{domxref("SVGPathElement.getPathSegAtLength()")}} {{deprecated_inline}} - : Returns an unsigned long representing the index within the {{domxref("SVGAnimatedPathData.pathSegList", "pathSegList")}} utilizing the user agent's distance-along-a-path algorithm. - {{domxref("SVGPathElement.createSVGPathSegClosePath()")}} {{deprecated_inline}} diff --git a/files/en-us/web/api/svgpathelement/pathlength/index.md b/files/en-us/web/api/svgpathelement/pathlength/index.md new file mode 100644 index 000000000000000..d5a7a154477feb3 --- /dev/null +++ b/files/en-us/web/api/svgpathelement/pathlength/index.md @@ -0,0 +1,49 @@ +--- +title: "SVGPathElement: pathLength property" +short-title: pathLength +slug: Web/API/SVGPathElement/pathLength +page-type: web-api-instance-property +browser-compat: api.SVGPathElement.pathLength +--- + +{{APIRef("SVG")}} + +The **`pathLength`** read-only property of the {{domxref("SVGPathElement")}} interface reflects the {{SVGAttr("pathLength")}} attribute of the given {{SVGelement("path")}} element. + +## Value + +An {{domxref("SVGAnimatedNumber")}}. + +## Examples + +### Accessing the `pathLength` Property + +```html +<svg width="200" height="100"> + <path id="myPath" d="M 0,30 h100" pathLength="50" /> +</svg> +``` + +```js +const pathElement = document.getElementById("myPath"); + +// Access the pathLength property +const animatedNumber = pathElement.pathLength; + +// The base value of the pathLength attribute +console.log(animatedNumber.baseVal); // Output: 100 +``` + +## Specifications + +{{Specifications}} + +## Browser compatibility + +{{Compat}} + +## See also + +- {{domxref("SVGGeometryElement.pathLength")}} +- {{SVGAttr("pathLength")}} +- {{domxref("SVGAnimatedLength")}} diff --git a/files/en-us/web/api/svgpathelement/setpathdata/index.md b/files/en-us/web/api/svgpathelement/setpathdata/index.md new file mode 100644 index 000000000000000..d422e157711a0af --- /dev/null +++ b/files/en-us/web/api/svgpathelement/setpathdata/index.md @@ -0,0 +1,68 @@ +--- +title: "SVGPathElement: setPathData() method" +short-title: setPathData() +slug: Web/API/SVGPathElement/setPathData +page-type: web-api-instance-method +status: + - experimental +browser-compat: api.SVGPathElement.setPathData +--- + +{{APIRef("SVG")}}{{SeeCompatTable}} + +The **`SVGPathElement.setPathData()`** method sets the sequence of path segments as the new path data. + +## Syntax + +```js-nolint +setPathData(pathData) +``` + +### Parameters + +- `pathData` + + - : An array of path segments. + Each path segment is an object with the following properties: + + - `type` + - : A [path commands](/en-US/docs/Web/SVG/Reference/Attribute/d#path_commands). + If [`options.normalize`](/en-US/docs/Web/API/SVGPathElement/getPathData#normalize) is true this will be one of the absolute commands: `'M'`, `'L'`, `'C'` and `'Z'`. + - `values` + - : An array or value containing the parameters for the corresponding command. + +### Return value + +None ({{jsxref('undefined')}}). + +## Example + +### Set path data + +Consider the following `<path>` element, drawing a square: + +```xml +<svg xmlns="http://www.w3.org/2000/svg" width="64" height="64"> + <path d="M0,0 h64 v64 h-64 z" /> +</svg> +``` + +The code below uses {{domxref("SVGPathElement/getPathData", "getPathData()")}} method to return the normalized path data as [absolute commands](/en-US/docs/Web/SVG/Reference/Attribute/d#path_commands). +Setting the returned data back to the `<path>` element using the `setPathData()` method will result in the different set of path commands in the DOM: + +```js +const svgPath = document.querySelector("path"); +const pathData = path.getPathData({ normalize: true }); + +svgPath.setPathData(pathData); + +// <path d="M 0 0 L 64 0 L 64 64 L 0 64 Z" /> +``` + +## Specifications + +{{Specifications}} + +## Browser compatibility + +{{Compat}} diff --git a/files/en-us/web/api/svgpatternelement/height/index.md b/files/en-us/web/api/svgpatternelement/height/index.md index 7337de84662c163..3f11dee1f12049e 100644 --- a/files/en-us/web/api/svgpatternelement/height/index.md +++ b/files/en-us/web/api/svgpatternelement/height/index.md @@ -10,7 +10,7 @@ browser-compat: api.SVGPatternElement.height The **`height`** read-only property of the {{domxref("SVGPatternElement")}} interface describes the height of the pattern as an {{domxref("SVGAnimatedLength")}}. It reflects the computed value of the {{SVGAttr("height")}} attribute on the {{SVGElement("pattern")}} element. -The attribute value can be a [`<length>`](/en-US/docs/Web/SVG/Content_type#length), [`<percentage>`](/en-US/docs/Web/SVG/Content_type#percentage), or [`<number>`](/en-US/docs/Web/SVG/Content_type#number). The numeric value of the {{domxref("SVGAnimatedLength.baseVal")}} represents the height of the pattern in the user coordinate system. +The attribute value can be a [`<length>`](/en-US/docs/Web/SVG/Guides/Content_type#length), [`<percentage>`](/en-US/docs/Web/SVG/Guides/Content_type#percentage), or [`<number>`](/en-US/docs/Web/SVG/Guides/Content_type#number). The numeric value of the {{domxref("SVGAnimatedLength.baseVal")}} represents the height of the pattern in the user coordinate system. ## Value diff --git a/files/en-us/web/api/svgpatternelement/width/index.md b/files/en-us/web/api/svgpatternelement/width/index.md index 6b2b410c67eaf5d..f95370f5041b3ff 100644 --- a/files/en-us/web/api/svgpatternelement/width/index.md +++ b/files/en-us/web/api/svgpatternelement/width/index.md @@ -10,7 +10,7 @@ browser-compat: api.SVGPatternElement.width The **`width`** read-only property of the {{domxref("SVGPatternElement")}} interface describes the width of the pattern as an {{domxref("SVGAnimatedLength")}}. It reflects the computed value of the {{SVGAttr("width")}} attribute on the {{SVGElement("pattern")}} element. -The attribute value can be a [`<length>`](/en-US/docs/Web/SVG/Content_type#length), [`<percentage>`](/en-US/docs/Web/SVG/Content_type#percentage), or [`<number>`](/en-US/docs/Web/SVG/Content_type#number). The numeric value of the {{domxref("SVGAnimatedLength.baseVal")}} represents the width of the pattern in the user coordinate system. +The attribute value can be a [`<length>`](/en-US/docs/Web/SVG/Guides/Content_type#length), [`<percentage>`](/en-US/docs/Web/SVG/Guides/Content_type#percentage), or [`<number>`](/en-US/docs/Web/SVG/Guides/Content_type#number). The numeric value of the {{domxref("SVGAnimatedLength.baseVal")}} represents the width of the pattern in the user coordinate system. ## Value diff --git a/files/en-us/web/api/svgpatternelement/x/index.md b/files/en-us/web/api/svgpatternelement/x/index.md index 8bb175ef0d11378..4aa4b030f9ab7c6 100644 --- a/files/en-us/web/api/svgpatternelement/x/index.md +++ b/files/en-us/web/api/svgpatternelement/x/index.md @@ -10,7 +10,7 @@ browser-compat: api.SVGPatternElement.x The **`x`** read-only property of the {{domxref("SVGPatternElement")}} interface describes the x-axis coordinate of the start point of the pattern as an {{domxref("SVGAnimatedLength")}}. It reflects the computed value of the {{SVGAttr("x")}} attribute on the {{SVGElement("pattern")}} element. -The attribute value can be a [`<length>`](/en-US/docs/Web/SVG/Content_type#length), [`<percentage>`](/en-US/docs/Web/SVG/Content_type#percentage), or [`<number>`](/en-US/docs/Web/SVG/Content_type#number). The numeric value of the {{domxref("SVGAnimatedLength.baseVal")}} is the x-coordinate of the pattern's starting point in the user coordinate system. +The attribute value can be a [`<length>`](/en-US/docs/Web/SVG/Guides/Content_type#length), [`<percentage>`](/en-US/docs/Web/SVG/Guides/Content_type#percentage), or [`<number>`](/en-US/docs/Web/SVG/Guides/Content_type#number). The numeric value of the {{domxref("SVGAnimatedLength.baseVal")}} is the x-coordinate of the pattern's starting point in the user coordinate system. ## Value diff --git a/files/en-us/web/api/svgpatternelement/y/index.md b/files/en-us/web/api/svgpatternelement/y/index.md index 9edb3f866aea020..d8d2a3104a5f525 100644 --- a/files/en-us/web/api/svgpatternelement/y/index.md +++ b/files/en-us/web/api/svgpatternelement/y/index.md @@ -10,7 +10,7 @@ browser-compat: api.SVGPatternElement.y The **`y`** read-only property of the {{domxref("SVGPatternElement")}} interface describes the y-axis coordinate of the start point of the pattern as an {{domxref("SVGAnimatedLength")}}. It reflects the computed value of the {{SVGAttr("y")}} attribute on the {{SVGElement("pattern")}} element. -The attribute value can be a [`<length>`](/en-US/docs/Web/SVG/Content_type#length), [`<percentage>`](/en-US/docs/Web/SVG/Content_type#percentage), or [`<number>`](/en-US/docs/Web/SVG/Content_type#number). The numeric value of the {{domxref("SVGAnimatedLength.baseVal")}} is the y-coordinate of the pattern's starting point in the user coordinate system. +The attribute value can be a [`<length>`](/en-US/docs/Web/SVG/Guides/Content_type#length), [`<percentage>`](/en-US/docs/Web/SVG/Guides/Content_type#percentage), or [`<number>`](/en-US/docs/Web/SVG/Guides/Content_type#number). The numeric value of the {{domxref("SVGAnimatedLength.baseVal")}} is the y-coordinate of the pattern's starting point in the user coordinate system. ## Value diff --git a/files/en-us/web/api/svgpointlist/index.md b/files/en-us/web/api/svgpointlist/index.md index b3d8dd68e7ea125..af58169d23bc708 100644 --- a/files/en-us/web/api/svgpointlist/index.md +++ b/files/en-us/web/api/svgpointlist/index.md @@ -50,8 +50,8 @@ The following example shows an SVG which contains a {{SVGElement("polyline")}} w ``` ```js -let example = document.getElementById("example"); -console.log(example.points); //an SVGPointList +const example = document.getElementById("example"); +console.log(example.points); // An SVGPointList ``` ## Specifications diff --git a/files/en-us/web/api/svgpointlist/initialize/index.md b/files/en-us/web/api/svgpointlist/initialize/index.md index b96c4d804a5b6a8..11b234b904582e1 100644 --- a/files/en-us/web/api/svgpointlist/initialize/index.md +++ b/files/en-us/web/api/svgpointlist/initialize/index.md @@ -45,11 +45,11 @@ The following example shows an SVG which contains a {{SVGElement("polyline")}} w ``` ```js -let example = document.getElementById("example"); -console.log(example.points.length); //5; -let svgPoint = document.getElementById("svg").createSVGPoint(); +const example = document.getElementById("example"); +console.log(example.points.length); // 5; +const svgPoint = document.getElementById("svg").createSVGPoint(); example.points.initialize(svgPoint); -console.log(example.points.length); //1 +console.log(example.points.length); // 1 ``` ## Specifications diff --git a/files/en-us/web/api/svgpreserveaspectratio/index.md b/files/en-us/web/api/svgpreserveaspectratio/index.md index 94d7754df6d116d..6c45ae83d3f4e2a 100644 --- a/files/en-us/web/api/svgpreserveaspectratio/index.md +++ b/files/en-us/web/api/svgpreserveaspectratio/index.md @@ -7,253 +7,51 @@ browser-compat: api.SVGPreserveAspectRatio {{APIRef("SVG")}} -## SVG preserveAspectRatio interface - -The `SVGPreserveAspectRatio` interface corresponds to the {{ SVGAttr("preserveAspectRatio") }} attribute, which is available for some of SVG's elements. +The **`SVGPreserveAspectRatio`** interface corresponds to the {{SVGAttr("preserveAspectRatio")}} attribute. An `SVGPreserveAspectRatio` object can be designated as read only, which means that attempts to modify the object will result in an exception being thrown. -### Interface overview - -<table class="no-markdown"> - <tbody> - <tr> - <th scope="row">Also implement</th> - <td><em>None</em></td> - </tr> - <tr> - <th scope="row">Methods</th> - <td><em>None</em></td> - </tr> - <tr> - <th scope="row">Properties</th> - <td> - <ul> - <li>unsigned short <code>align</code></li> - <li>unsigned short <code>meetOrSlice</code></li> - </ul> - </td> - </tr> - <tr> - <th scope="row">Constants</th> - <td> - <ul> - <li><code>SVG_PRESERVEASPECTRATIO_UNKNOWN</code> = 0</li> - <li><code>SVG_PRESERVEASPECTRATIO_NONE</code> = 1</li> - <li><code>SVG_PRESERVEASPECTRATIO_XMINYMIN</code> = 2</li> - <li><code>SVG_PRESERVEASPECTRATIO_XMIDYMIN</code> = 3</li> - <li><code>SVG_PRESERVEASPECTRATIO_XMAXYMIN</code> = 4</li> - <li><code>SVG_PRESERVEASPECTRATIO_XMINYMID</code> = 5</li> - <li><code>SVG_PRESERVEASPECTRATIO_XMIDYMID</code> = 6</li> - <li><code>SVG_PRESERVEASPECTRATIO_XMAXYMID</code> = 7</li> - <li><code>SVG_PRESERVEASPECTRATIO_XMINYMAX</code> = 8</li> - <li><code>SVG_PRESERVEASPECTRATIO_XMIDYMAX</code> = 9</li> - <li><code>SVG_PRESERVEASPECTRATIO_XMAXYMAX</code> = 10</li> - </ul> - <ul> - <li><code>SVG_MEETORSLICE_UNKNOWN</code> = 0</li> - <li><code>SVG_MEETORSLICE_MEET</code> = 1</li> - <li><code>SVG_MEETORSLICE_SLICE</code> = 2</li> - </ul> - </td> - </tr> - <tr> - <th scope="row">Normative document</th> - <td> - <a - href="https://www.w3.org/TR/SVG/coords.html#InterfaceSVGPreserveAspectRatio" - >SVG 1.1 (2nd Edition)</a - > - </td> - </tr> - </tbody> -</table> - -## Constants - -<table class="no-markdown"> - <thead> - <tr> - <th>Name</th> - <th>Value</th> - <th>Description</th> - </tr> - </thead> - <tbody> - <tr> - <td> - <code>SVG_PRESERVEASPECTRATIO_UNKNOWN</code> - </td> - <td>0</td> - <td> - The enumeration was set to a value that is not one of predefined types. - It is invalid to attempt to define a new value of this type or to - attempt to switch an existing value to this type. - </td> - </tr> - <tr> - <td> - <code>SVG_PRESERVEASPECTRATIO_NONE</code> - </td> - <td>1</td> - <td> - Corresponds to value <code>none</code> for attribute - {{ SVGAttr("preserveAspectRatio") }}. - </td> - </tr> - <tr> - <td> - <code>SVG_PRESERVEASPECTRATIO_XMINYMIN</code> - </td> - <td>2</td> - <td> - Corresponds to value <code>xMinYMin</code> for attribute - {{ SVGAttr("preserveAspectRatio") }}. - </td> - </tr> - <tr> - <td> - <code>SVG_PRESERVEASPECTRATIO_XMIDYMIN</code> - </td> - <td>3</td> - <td> - Corresponds to value <code>xMidYMin</code> for attribute - {{ SVGAttr("preserveAspectRatio") }}. - </td> - </tr> - <tr> - <td> - <code>SVG_PRESERVEASPECTRATIO_XMAXYMIN</code> - </td> - <td>4</td> - <td> - Corresponds to value <code>xMaxYMin</code> for attribute - {{ SVGAttr("preserveAspectRatio") }}. - </td> - </tr> - <tr> - <td> - <code>SVG_PRESERVEASPECTRATIO_XMINYMID</code> - </td> - <td>5</td> - <td> - Corresponds to value <code>xMinYMid</code> for attribute - {{ SVGAttr("preserveAspectRatio") }}. - </td> - </tr> - <tr> - <td> - <code>SVG_PRESERVEASPECTRATIO_XMIDYMID</code> - </td> - <td>6</td> - <td> - Corresponds to value <code>xMidYMid</code> for attribute - {{ SVGAttr("preserveAspectRatio") }}. - </td> - </tr> - <tr> - <td> - <code>SVG_PRESERVEASPECTRATIO_XMAXYMID</code> - </td> - <td>7</td> - <td> - Corresponds to value <code>xMaxYMid</code> for attribute - {{ SVGAttr("preserveAspectRatio") }}. - </td> - </tr> - <tr> - <td> - <code>SVG_PRESERVEASPECTRATIO_XMINYMAX</code> - </td> - <td>8</td> - <td> - Corresponds to value <code>xMinYMax</code> for attribute - {{ SVGAttr("preserveAspectRatio") }}. - </td> - </tr> - <tr> - <td> - <code>SVG_PRESERVEASPECTRATIO_XMIDYMAX</code> - </td> - <td>9</td> - <td> - Corresponds to value <code>xMidYMax</code> for attribute - {{ SVGAttr("preserveAspectRatio") }}. - </td> - </tr> - <tr> - <td> - <code>SVG_PRESERVEASPECTRATIO_XMAXYMAX</code> - </td> - <td>10</td> - <td> - Corresponds to value <code>xMaxYMax</code> for attribute - {{ SVGAttr("preserveAspectRatio") }}. - </td> - </tr> - <tr> - <td><code>SVG_MEETORSLICE_UNKNOWN</code></td> - <td>0</td> - <td> - The enumeration was set to a value that is not one of predefined types. - It is invalid to attempt to define a new value of this type or to - attempt to switch an existing value to this type. - </td> - </tr> - <tr> - <td><code>SVG_MEETORSLICE_MEET</code></td> - <td>1</td> - <td> - Corresponds to value <code>meet</code> for attribute - {{ SVGAttr("preserveAspectRatio") }}. - </td> - </tr> - <tr> - <td><code>SVG_MEETORSLICE_SLICE</code></td> - <td>2</td> - <td> - Corresponds to value <code>slice</code> for attribute - {{ SVGAttr("preserveAspectRatio") }}. - </td> - </tr> - </tbody> -</table> - ## Instance properties -<table class="no-markdown"> - <thead> - <tr> - <th>Name</th> - <th>Type</th> - <th>Description</th> - </tr> - </thead> - <tbody> - <tr> - <td>{{domxref("SVGPreserveAspectRatio.align", "align")}}</td> - <td>unsigned short</td> - <td> - The type of the alignment value as specified by one of the - <code>SVG_PRESERVEASPECTRATIO_*</code> constants defined on this interface. - </td> - </tr> - <tr> - <td>{{domxref("SVGPreserveAspectRatio.meetOrSlice", "meetOrSlice")}}</td> - <td>unsigned short</td> - <td> - The type of the meet-or-slice value as specified by one of the - <code>SVG_MEETORSLICE_*</code> constants defined on this interface. - </td> - </tr> - </tbody> -</table> - -**Exceptions on setting:** a [`DOMException`](/en-US/docs/Web/API/DOMException) with code `NO_MODIFICATION_ALLOWED_ERR` is raised on an attempt to change the value of an attribute on a read only object. +- {{domxref("SVGPreserveAspectRatio.align", "align")}} + - : The type of the alignment value as specified by one of the `SVG_PRESERVEASPECTRATIO_*` constants defined on this interface. +- {{domxref("SVGPreserveAspectRatio.meetOrSlice", "meetOrSlice")}} + - : The type of the meet-or-slice value as specified by one of the `SVG_MEETORSLICE_*` constants defined on this interface. ## Instance methods -The `SVGPreserveAspectRatio` interface do not provide any specific methods. +_The `SVGPreserveAspectRatio` interface do not provide any specific methods._ + +## Static properties + +- `SVG_PRESERVEASPECTRATIO_UNKNOWN` (0) + - : The enumeration was set to a value that is not one of predefined types. It is invalid to attempt to define a new value of this type or to attempt to switch an existing value to this type. +- `SVG_PRESERVEASPECTRATIO_NONE` (1) + - : Corresponds to value `none` for attribute {{SVGAttr("preserveAspectRatio")}}. +- `SVG_PRESERVEASPECTRATIO_XMINYMIN` (2) + - : Corresponds to value `xMinYMin` for attribute {{SVGAttr("preserveAspectRatio")}}. +- `SVG_PRESERVEASPECTRATIO_XMIDYMIN` (3) + - : Corresponds to value `xMidYMin` for attribute {{SVGAttr("preserveAspectRatio")}}. +- `SVG_PRESERVEASPECTRATIO_XMAXYMIN` (4) + - : Corresponds to value `xMaxYMin` for attribute {{SVGAttr("preserveAspectRatio")}}. +- `SVG_PRESERVEASPECTRATIO_XMINYMID` (5) + - : Corresponds to value `xMinYMid` for attribute {{SVGAttr("preserveAspectRatio")}}. +- `SVG_PRESERVEASPECTRATIO_XMIDYMID` (6) + - : Corresponds to value `xMidYMid` for attribute {{SVGAttr("preserveAspectRatio")}}. +- `SVG_PRESERVEASPECTRATIO_XMAXYMID` (7) + - : Corresponds to value `xMaxYMid` for attribute {{SVGAttr("preserveAspectRatio")}}. +- `SVG_PRESERVEASPECTRATIO_XMINYMAX` (8) + - : Corresponds to value `xMinYMax` for attribute {{SVGAttr("preserveAspectRatio")}}. +- `SVG_PRESERVEASPECTRATIO_XMIDYMAX` (9) + - : Corresponds to value `xMidYMax` for attribute {{SVGAttr("preserveAspectRatio")}}. +- `SVG_PRESERVEASPECTRATIO_XMAXYMAX` (10) + - : Corresponds to value `xMaxYMax` for attribute {{SVGAttr("preserveAspectRatio")}}. +- `SVG_MEETORSLICE_UNKNOWN` (0) + - : The enumeration was set to a value that is not one of predefined types. It is invalid to attempt to define a new value of this type or to attempt to switch an existing value to this type. +- `SVG_MEETORSLICE_MEET` (1) + - : Corresponds to value `meet` for attribute {{SVGAttr("preserveAspectRatio")}}. +- `SVG_MEETORSLICE_SLICE` (2) + - : Corresponds to value `slice` for attribute {{SVGAttr("preserveAspectRatio")}}. ## Specifications diff --git a/files/en-us/web/api/svgradialgradientelement/cx/index.md b/files/en-us/web/api/svgradialgradientelement/cx/index.md index b60e3f0c18502e3..d27f48394c78f6c 100644 --- a/files/en-us/web/api/svgradialgradientelement/cx/index.md +++ b/files/en-us/web/api/svgradialgradientelement/cx/index.md @@ -10,7 +10,7 @@ browser-compat: api.SVGRadialGradientElement.cx The **`cx`** read-only property of the {{domxref("SVGRadialGradientElement")}} interface describes the x-axis coordinate of the center of the radial gradient as an {{domxref("SVGAnimatedLength")}}. It reflects the computed value of the {{SVGAttr("cx")}} attribute on the {{SVGElement("radialGradient")}} element. -The attribute value is a [`<length>`](/en-US/docs/Web/SVG/Content_type#length), [`<percentage>`](/en-US/docs/Web/SVG/Content_type#percentage), or [`<number>`](/en-US/docs/Web/SVG/Content_type#number). The numeric value of the {{domxref("SVGAnimatedLength.baseVal")}} is the x-coordinate of the radial gradient's center in the user coordinate system. +The attribute value is a [`<length>`](/en-US/docs/Web/SVG/Guides/Content_type#length), [`<percentage>`](/en-US/docs/Web/SVG/Guides/Content_type#percentage), or [`<number>`](/en-US/docs/Web/SVG/Guides/Content_type#number). The numeric value of the {{domxref("SVGAnimatedLength.baseVal")}} is the x-coordinate of the radial gradient's center in the user coordinate system. ## Value diff --git a/files/en-us/web/api/svgradialgradientelement/cy/index.md b/files/en-us/web/api/svgradialgradientelement/cy/index.md index 6b31ea643b02aec..213f6d8cdb408b2 100644 --- a/files/en-us/web/api/svgradialgradientelement/cy/index.md +++ b/files/en-us/web/api/svgradialgradientelement/cy/index.md @@ -10,7 +10,7 @@ browser-compat: api.SVGRadialGradientElement.cy The **`cy`** read-only property of the {{domxref("SVGRadialGradientElement")}} interface describes the y-axis coordinate of the center of the radial gradient as an {{domxref("SVGAnimatedLength")}}. It reflects the computed value of the {{SVGAttr("cy")}} attribute on the {{SVGElement("radialGradient")}} element. -The attribute value is a [`<length>`](/en-US/docs/Web/SVG/Content_type#length), [`<percentage>`](/en-US/docs/Web/SVG/Content_type#percentage), or [`<number>`](/en-US/docs/Web/SVG/Content_type#number). The numeric value of the {{domxref("SVGAnimatedLength.baseVal")}} is the y-coordinate of the radial gradient's center in the user coordinate system. +The attribute value is a [`<length>`](/en-US/docs/Web/SVG/Guides/Content_type#length), [`<percentage>`](/en-US/docs/Web/SVG/Guides/Content_type#percentage), or [`<number>`](/en-US/docs/Web/SVG/Guides/Content_type#number). The numeric value of the {{domxref("SVGAnimatedLength.baseVal")}} is the y-coordinate of the radial gradient's center in the user coordinate system. ## Value diff --git a/files/en-us/web/api/svgradialgradientelement/fr/index.md b/files/en-us/web/api/svgradialgradientelement/fr/index.md new file mode 100644 index 000000000000000..5e8c49b61835881 --- /dev/null +++ b/files/en-us/web/api/svgradialgradientelement/fr/index.md @@ -0,0 +1,68 @@ +--- +title: "SVGRadialGradientElement: fr property" +short-title: fr +slug: Web/API/SVGRadialGradientElement/fr +page-type: web-api-instance-property +browser-compat: api.SVGRadialGradientElement.fr +--- + +{{APIRef("SVG")}} + +The **`fr`** read-only property of the {{domxref("SVGRadialGradientElement")}} interface describes the radius of the focal circle of the radial gradient as an {{domxref("SVGAnimatedLength")}}. It reflects the computed value of the {{SVGAttr("fr")}} attribute on the {{SVGElement("radialGradient")}} element. + +The attribute value is a [`<length>`](/en-US/docs/Web/SVG/Guides/Content_type#length), [`<percentage>`](/en-US/docs/Web/SVG/Guides/Content_type#percentage), or [`<number>`](/en-US/docs/Web/SVG/Guides/Content_type#number). The numeric value of the {{domxref("SVGAnimatedLength.baseVal")}} is the radius of the focal point of the radial gradient in the user coordinate system. + +## Value + +An {{domxref("SVGAnimatedLength")}}. + +## Example + +Given the following SVG, with two identical gradients declared with different unit types: + +```html +<svg viewBox="0 0 200 100" width="200" xmlns="http://www.w3.org/2000/svg"> + <defs> + <radialGradient id="gradient1" r="20%" fr="0.5"> + <stop offset="0%" stop-color="red" /> + <stop offset="100%" stop-color="yellow" /> + </radialGradient> + <radialGradient id="gradient2" r="20%" fr="50%"> + <stop offset="0%" stop-color="red" /> + <stop offset="100%" stop-color="yellow" /> + </radialGradient> + </defs> + <rect x="0" y="0" width="100" height="100" fill="url(#gradient1)" /> + <rect x="100" y="0" width="100" height="100" fill="url(#gradient2)" /> +</svg> +``` + +We can access the `fr` attributes' unit type, value, and value as specified without the unit type: + +```js +const radialGradients = document.querySelectorAll("radialGradient"); +const frGradient1 = radialGradients[0].fr; +const frGradient2 = radialGradients[1].fr; + +console.log(frGradient1.baseVal.unitType); // 1 (SVGLength.SVG_LENGTHTYPE_NUMBER) +console.log(frGradient1.baseVal.value); // 0.5 +console.log(frGradient1.baseVal.valueInSpecifiedUnits); // 0.5 + +console.log(frGradient2.baseVal.unitType); // 2 (SVGLength.SVG_LENGTHTYPE_PERCENTAGE) +console.log(frGradient2.baseVal.value); // 79.05693817138672 +console.log(frGradient2.baseVal.valueInSpecifiedUnits); // 50 +``` + +## Specifications + +{{Specifications}} + +## Browser compatibility + +{{Compat}} + +## See also + +- {{domxref("SVGRadialGradientElement.fx")}} +- {{domxref("SVGLength.unitType")}} +- {{domxref("SVGAnimatedLength.baseVal")}} diff --git a/files/en-us/web/api/svgradialgradientelement/fx/index.md b/files/en-us/web/api/svgradialgradientelement/fx/index.md index 4e0690a54781c38..639b3a9238fa5f2 100644 --- a/files/en-us/web/api/svgradialgradientelement/fx/index.md +++ b/files/en-us/web/api/svgradialgradientelement/fx/index.md @@ -10,7 +10,7 @@ browser-compat: api.SVGRadialGradientElement.fx The **`fx`** read-only property of the {{domxref("SVGRadialGradientElement")}} interface describes the x-axis coordinate of the focal point of the radial gradient as an {{domxref("SVGAnimatedLength")}}. It reflects the computed value of the {{SVGAttr("fx")}} attribute on the {{SVGElement("radialGradient")}} element. -The attribute value is a [`<length>`](/en-US/docs/Web/SVG/Content_type#length), [`<percentage>`](/en-US/docs/Web/SVG/Content_type#percentage), or [`<number>`](/en-US/docs/Web/SVG/Content_type#number). The numeric value of the {{domxref("SVGAnimatedLength.baseVal")}} is the x-coordinate of the focal point of the radial gradient in the user coordinate system. +The attribute value is a [`<length>`](/en-US/docs/Web/SVG/Guides/Content_type#length), [`<percentage>`](/en-US/docs/Web/SVG/Guides/Content_type#percentage), or [`<number>`](/en-US/docs/Web/SVG/Guides/Content_type#number). The numeric value of the {{domxref("SVGAnimatedLength.baseVal")}} is the x-coordinate of the focal point of the radial gradient in the user coordinate system. ## Value diff --git a/files/en-us/web/api/svgradialgradientelement/fy/index.md b/files/en-us/web/api/svgradialgradientelement/fy/index.md index 96e39a0c9cce1e0..5d999df915b8c16 100644 --- a/files/en-us/web/api/svgradialgradientelement/fy/index.md +++ b/files/en-us/web/api/svgradialgradientelement/fy/index.md @@ -10,7 +10,7 @@ browser-compat: api.SVGRadialGradientElement.fy The **`fy`** read-only property of the {{domxref("SVGRadialGradientElement")}} interface describes the y-axis coordinate of the focal point of the radial gradient as an {{domxref("SVGAnimatedLength")}}. It reflects the computed value of the {{SVGAttr("fy")}} attribute on the {{SVGElement("radialGradient")}} element. -The attribute value is a [`<length>`](/en-US/docs/Web/SVG/Content_type#length), [`<percentage>`](/en-US/docs/Web/SVG/Content_type#percentage), or [`<number>`](/en-US/docs/Web/SVG/Content_type#number). The numeric value of the {{domxref("SVGAnimatedLength.baseVal")}} is the y-coordinate of the focal point of the radial gradient in the user coordinate system. +The attribute value is a [`<length>`](/en-US/docs/Web/SVG/Guides/Content_type#length), [`<percentage>`](/en-US/docs/Web/SVG/Guides/Content_type#percentage), or [`<number>`](/en-US/docs/Web/SVG/Guides/Content_type#number). The numeric value of the {{domxref("SVGAnimatedLength.baseVal")}} is the y-coordinate of the focal point of the radial gradient in the user coordinate system. ## Value diff --git a/files/en-us/web/api/svgradialgradientelement/index.md b/files/en-us/web/api/svgradialgradientelement/index.md index 0b96d5a8ded9adf..fad1663d6520baa 100644 --- a/files/en-us/web/api/svgradialgradientelement/index.md +++ b/files/en-us/web/api/svgradialgradientelement/index.md @@ -21,6 +21,8 @@ _This interface also inherits properties from its parent, {{domxref("SVGGradient - : An {{domxref("SVGAnimatedLength")}} corresponding to the {{SVGAttr("cy")}} attribute of the given {{SVGElement("RadialGradient")}} element. - {{domxref("SVGRadialGradientElement.r")}} {{ReadOnlyInline}} - : An {{domxref("SVGAnimatedLength")}} corresponding to the {{SVGAttr("r")}} attribute of the given {{SVGElement("RadialGradient")}} element. +- {{domxref("SVGRadialGradientElement.fr")}} {{ReadOnlyInline}} + - : An {{domxref("SVGAnimatedLength")}} corresponding to the {{SVGAttr("fr")}} attribute. - {{domxref("SVGRadialGradientElement.fx")}} {{ReadOnlyInline}} - : An {{domxref("SVGAnimatedLength")}} corresponding to the {{SVGAttr("fx")}} attribute of the given {{SVGElement("RadialGradient")}} element. - {{domxref("SVGRadialGradientElement.fy")}} {{ReadOnlyInline}} diff --git a/files/en-us/web/api/svgradialgradientelement/r/index.md b/files/en-us/web/api/svgradialgradientelement/r/index.md index 44eac95bc98a152..f7a2f51c30a343a 100644 --- a/files/en-us/web/api/svgradialgradientelement/r/index.md +++ b/files/en-us/web/api/svgradialgradientelement/r/index.md @@ -10,7 +10,7 @@ browser-compat: api.SVGRadialGradientElement.r The **`r`** read-only property of the {{domxref("SVGRadialGradientElement")}} interface describes the radius of the radial gradient as an {{domxref("SVGAnimatedLength")}}. It reflects the computed value of the {{SVGAttr("r")}} attribute on the {{SVGElement("radialGradient")}} element. -The attribute value is a [`<length>`](/en-US/docs/Web/SVG/Content_type#length), [`<percentage>`](/en-US/docs/Web/SVG/Content_type#percentage), or [`<number>`](/en-US/docs/Web/SVG/Content_type#number). The numeric value of the {{domxref("SVGAnimatedLength.baseVal")}} is the radius of the radial gradient in the user coordinate system. +The attribute value is a [`<length>`](/en-US/docs/Web/SVG/Guides/Content_type#length), [`<percentage>`](/en-US/docs/Web/SVG/Guides/Content_type#percentage), or [`<number>`](/en-US/docs/Web/SVG/Guides/Content_type#number). The numeric value of the {{domxref("SVGAnimatedLength.baseVal")}} is the radius of the radial gradient in the user coordinate system. ## Value diff --git a/files/en-us/web/api/svgrect/height/index.md b/files/en-us/web/api/svgrect/height/index.md index 2e6658e301234d6..6dd8f112c5f6618 100644 --- a/files/en-us/web/api/svgrect/height/index.md +++ b/files/en-us/web/api/svgrect/height/index.md @@ -10,7 +10,7 @@ browser-compat: api.SVGRect.height The **`height`** property of the {{domxref("SVGRect")}} interface is an alias for the {{DOMXref("DOMRect.height")}} property. It describes the vertical size of the element. It reflects the SVG element's {{SVGattr("height")}} attribute and the CSS {{cssxref("height")}} property. -The height is a length; it is the distance from the top of element to the bottom of the element in the user coordinate system. Its syntax is the same as that for [`<length>`](/en-US/docs/Web/SVG/Content_type#length). +The height is a length; it is the distance from the top of element to the bottom of the element in the user coordinate system. Its syntax is the same as that for [`<length>`](/en-US/docs/Web/SVG/Guides/Content_type#length). ## Usage context @@ -26,8 +26,8 @@ The height is a length; it is the distance from the top of element to the bottom <td>Value</td> <td> <code> - <a href="/en-US/docs/Web/SVG/Content_type#length">&#x3C;length></a - > | <a href="/en-US/docs/Web/SVG/Content_type#percentage" + <a href="/en-US/docs/Web/SVG/Guides/Content_type#length">&#x3C;length></a + > | <a href="/en-US/docs/Web/SVG/Guides/Content_type#percentage" >&#x3C;percentage></a > </code> diff --git a/files/en-us/web/api/svgrect/width/index.md b/files/en-us/web/api/svgrect/width/index.md index 5d28d55f408cec5..7246722841eb53f 100644 --- a/files/en-us/web/api/svgrect/width/index.md +++ b/files/en-us/web/api/svgrect/width/index.md @@ -10,7 +10,7 @@ browser-compat: api.SVGRect.width The **`width`** property of the {{domxref("SVGRect")}} interface is an alias for the {{DOMXref("DOMRect.width")}} property. It describes the horizontal size of the element. It reflects the SVG element's {{SVGattr("width")}} attribute and the CSS {{cssxref("width")}} property. -The width is a length; it is the distance from the left of element to the right of the element in the user coordinate system. Its syntax is the same as that for [`<length>`](/en-US/docs/Web/SVG/Content_type#length). +The width is a length; it is the distance from the left of element to the right of the element in the user coordinate system. Its syntax is the same as that for [`<length>`](/en-US/docs/Web/SVG/Guides/Content_type#length). ## Usage context @@ -26,8 +26,8 @@ The width is a length; it is the distance from the left of element to the right <td>Value</td> <td> <code> - <a href="/en-US/docs/Web/SVG/Content_type#length">&#x3C;length></a - > | <a href="/en-US/docs/Web/SVG/Content_type#percentage" + <a href="/en-US/docs/Web/SVG/Guides/Content_type#length">&#x3C;length></a + > | <a href="/en-US/docs/Web/SVG/Guides/Content_type#percentage" >&#x3C;percentage></a > </code> diff --git a/files/en-us/web/api/svgrect/y/index.md b/files/en-us/web/api/svgrect/y/index.md index 9348deee360e5a1..926b3d891c98585 100644 --- a/files/en-us/web/api/svgrect/y/index.md +++ b/files/en-us/web/api/svgrect/y/index.md @@ -10,7 +10,7 @@ browser-compat: api.SVGRect.y The **`y`** property of the {{domxref("SVGRect")}} interface is an alias for the {{DOMXref("DOMRect.y")}} property. It describes the vertical coordinate of the position of the element. It reflects the SVG element's {{SVGattr("y")}} attribute and the CSS {{cssxref("y")}} property. -A `<coordinate>` is a length in the user coordinate system that is the given distance from the origin of the user coordinate system along the relevant axis (the y-axis for Y coordinates, the x-axis for X coordinates). Its syntax is the same as that for [`<length>`](/en-US/docs/Web/SVG/Content_type#length). +A `<coordinate>` is a length in the user coordinate system that is the given distance from the origin of the user coordinate system along the relevant axis (the y-axis for Y coordinates, the x-axis for X coordinates). Its syntax is the same as that for [`<length>`](/en-US/docs/Web/SVG/Guides/Content_type#length). ## Usage context @@ -26,8 +26,8 @@ A `<coordinate>` is a length in the user coordinate system that is the given dis <td>Value</td> <td> <code> - <a href="/en-US/docs/Web/SVG/Content_type#length">&#x3C;length></a - > | <a href="/en-US/docs/Web/SVG/Content_type#percentage" + <a href="/en-US/docs/Web/SVG/Guides/Content_type#length">&#x3C;length></a + > | <a href="/en-US/docs/Web/SVG/Guides/Content_type#percentage" >&#x3C;percentage></a > </code> diff --git a/files/en-us/web/api/svgrectelement/height/index.md b/files/en-us/web/api/svgrectelement/height/index.md index 232742d56ae3137..9afc50e4708dfac 100644 --- a/files/en-us/web/api/svgrectelement/height/index.md +++ b/files/en-us/web/api/svgrectelement/height/index.md @@ -8,7 +8,7 @@ browser-compat: api.SVGRectElement.height {{APIRef("SVG")}} -The **`height`** read-only property of the {{domxref("SVGRectElement")}} interface describes the vertical size of an SVG rectangle as a {{domxref("SVGAnimatedLength")}}. The length is in user coordinate system units along the y-axis. Its syntax is the same as that for [`<length>`](/en-US/docs/Web/SVG/Content_type#length). +The **`height`** read-only property of the {{domxref("SVGRectElement")}} interface describes the vertical size of an SVG rectangle as a {{domxref("SVGAnimatedLength")}}. The length is in user coordinate system units along the y-axis. Its syntax is the same as that for [`<length>`](/en-US/docs/Web/SVG/Guides/Content_type#length). It reflects the {{SVGElement("rect")}} element's {{SVGAttr("height")}} presentational attribute. The CSS {{cssxref("height")}} property takes precedence over the SVG `height` presentational attribute, so the value may not reflect the elements actual size. The default value is `0`. diff --git a/files/en-us/web/api/svgrectelement/rx/index.md b/files/en-us/web/api/svgrectelement/rx/index.md index 49bc9b3497717dc..b5121a54d751e8c 100644 --- a/files/en-us/web/api/svgrectelement/rx/index.md +++ b/files/en-us/web/api/svgrectelement/rx/index.md @@ -8,7 +8,7 @@ browser-compat: api.SVGRectElement.rx {{APIRef("SVG")}} -The **`rx`** read-only property of the {{domxref("SVGRectElement")}} interface describes the horizontal curve of the corners of an SVG rectangle as a {{domxref("SVGAnimatedLength")}}. The length is in user coordinate system units along the x-axis. Its syntax is the same as that for [`<length>`](/en-US/docs/Web/SVG/Content_type#length). +The **`rx`** read-only property of the {{domxref("SVGRectElement")}} interface describes the horizontal curve of the corners of an SVG rectangle as a {{domxref("SVGAnimatedLength")}}. The length is in user coordinate system units along the x-axis. Its syntax is the same as that for [`<length>`](/en-US/docs/Web/SVG/Guides/Content_type#length). It reflects the {{SVGElement("rect")}} element's {{SVGAttr("rx")}} presentational attribute. The CSS {{cssxref("rx")}} property takes precedence over the SVG `rx` presentational attribute, so the value may not reflect the actual size of the rounded corners. The default value is `0`, which draws a rectangle with square corners. diff --git a/files/en-us/web/api/svgrectelement/ry/index.md b/files/en-us/web/api/svgrectelement/ry/index.md index f39b4a6c3070d23..402cd32df660563 100644 --- a/files/en-us/web/api/svgrectelement/ry/index.md +++ b/files/en-us/web/api/svgrectelement/ry/index.md @@ -8,7 +8,7 @@ browser-compat: api.SVGRectElement.ry {{APIRef("SVG")}} -The **`ry`** read-only property of the {{domxref("SVGRectElement")}} interface describes the vertical curve of the corners of an SVG rectangle as a {{domxref("SVGAnimatedLength")}}. The length is in user coordinate system units along the y-axis. Its syntax is the same as that for [`<length>`](/en-US/docs/Web/SVG/Content_type#length). +The **`ry`** read-only property of the {{domxref("SVGRectElement")}} interface describes the vertical curve of the corners of an SVG rectangle as a {{domxref("SVGAnimatedLength")}}. The length is in user coordinate system units along the y-axis. Its syntax is the same as that for [`<length>`](/en-US/docs/Web/SVG/Guides/Content_type#length). It reflects the {{SVGElement("rect")}} element's {{SVGAttr("ry")}} presentational attribute. The CSS {{cssxref("ry")}} property takes precedence over the SVG `ry` presentational attribute, so the value may not reflect the actual size of the rounded corners. The default value is `0`, which draws a rectangle with square corners. diff --git a/files/en-us/web/api/svgrectelement/width/index.md b/files/en-us/web/api/svgrectelement/width/index.md index 2d37e76a07c9308..be2157a9eb5cbf8 100644 --- a/files/en-us/web/api/svgrectelement/width/index.md +++ b/files/en-us/web/api/svgrectelement/width/index.md @@ -8,7 +8,7 @@ browser-compat: api.SVGRectElement.width {{APIRef("SVG")}} -The **`width`** read-only property of the {{domxref("SVGRectElement")}} interface describes the horizontal size of an SVG rectangle as a {{domxref("SVGAnimatedLength")}}. The length is in user coordinate system units along the x-axis. Its syntax is the same as that for [`<length>`](/en-US/docs/Web/SVG/Content_type#length). +The **`width`** read-only property of the {{domxref("SVGRectElement")}} interface describes the horizontal size of an SVG rectangle as a {{domxref("SVGAnimatedLength")}}. The length is in user coordinate system units along the x-axis. Its syntax is the same as that for [`<length>`](/en-US/docs/Web/SVG/Guides/Content_type#length). It reflects the {{SVGElement("rect")}} element's {{SVGAttr("width")}} presentational attribute. The CSS {{cssxref("width")}} property takes precedence over the SVG `width` presentational attribute, so the value may not reflect the elements actual size. The default value is `0`. diff --git a/files/en-us/web/api/svgrectelement/x/index.md b/files/en-us/web/api/svgrectelement/x/index.md index 31a563ec42b5e41..5e50ed10a7eac0f 100644 --- a/files/en-us/web/api/svgrectelement/x/index.md +++ b/files/en-us/web/api/svgrectelement/x/index.md @@ -8,7 +8,7 @@ browser-compat: api.SVGRectElement.x {{APIRef("SVG")}} -The **`x`** read-only property of the {{domxref("SVGRectElement")}} interface describes the horizontal coordinate of the position of an SVG rectangle as a {{domxref("SVGAnimatedLength")}}. The `<coordinate>` is a length in the user coordinate system that is the given distance from the origin of the user coordinate system along the x-axis. Its syntax is the same as that for [`<length>`](/en-US/docs/Web/SVG/Content_type#length). +The **`x`** read-only property of the {{domxref("SVGRectElement")}} interface describes the horizontal coordinate of the position of an SVG rectangle as a {{domxref("SVGAnimatedLength")}}. The `<coordinate>` is a length in the user coordinate system that is the given distance from the origin of the user coordinate system along the x-axis. Its syntax is the same as that for [`<length>`](/en-US/docs/Web/SVG/Guides/Content_type#length). It reflects the {{SVGElement("rect")}} element's {{SVGAttr("x")}} geometric attribute value. The CSS {{cssxref("x")}} property takes precedence over the SVG `x` geometric attribute, so the value may not reflect the element's appearance. The default value is `0`. diff --git a/files/en-us/web/api/svgrectelement/y/index.md b/files/en-us/web/api/svgrectelement/y/index.md index 188767c0faa424f..d394f984215ef5b 100644 --- a/files/en-us/web/api/svgrectelement/y/index.md +++ b/files/en-us/web/api/svgrectelement/y/index.md @@ -8,7 +8,7 @@ browser-compat: api.SVGRectElement.y {{APIRef("SVG")}} -The **`y`** read-only property of the {{domxref("SVGRectElement")}} interface describes the vertical coordinate of the position of an SVG rectangle as a {{domxref("SVGAnimatedLength")}}. The `<coordinate>` is a length in the user coordinate system that is the given distance from the origin of the user coordinate system along the y-axis. Its syntax is the same as that for [`<length>`](/en-US/docs/Web/SVG/Content_type#length). +The **`y`** read-only property of the {{domxref("SVGRectElement")}} interface describes the vertical coordinate of the position of an SVG rectangle as a {{domxref("SVGAnimatedLength")}}. The `<coordinate>` is a length in the user coordinate system that is the given distance from the origin of the user coordinate system along the y-axis. Its syntax is the same as that for [`<length>`](/en-US/docs/Web/SVG/Guides/Content_type#length). It reflects the {{SVGElement("rect")}} element's {{SVGAttr("y")}} geometric attribute value. The CSS {{cssxref("y")}} property takes precedence over the SVG `y` attribute, so the value may not reflect the element's appearance. The default value is `0`. diff --git a/files/en-us/web/api/svgrenderingintent/index.md b/files/en-us/web/api/svgrenderingintent/index.md index 1554f8cde840bb8..7ce7e2b8a0dccd4 100644 --- a/files/en-us/web/api/svgrenderingintent/index.md +++ b/files/en-us/web/api/svgrenderingintent/index.md @@ -16,52 +16,6 @@ The **`SVGRenderingIntent`** interface defines the enumerated list of possible v > [!WARNING] > This interface was removed in the SVG 2 specification. -## Constants - -<table class="no-markdown"> - <tbody> - <tr> - <th>Name</th> - <th>Value</th> - <th>Description</th> - </tr> - <tr> - <td><code>RENDERING_INTENT_UNKNOWN</code></td> - <td>0</td> - <td> - The type is not one of predefined types. It is invalid to attempt to - define a new value of this type or to attempt to switch an existing - value to this type. - </td> - </tr> - <tr> - <td><code>RENDERING_INTENT_AUTO</code></td> - <td>1</td> - <td>Corresponds to the value <code>auto</code>.</td> - </tr> - <tr> - <td><code>RENDERING_INTENT_PERCEPTUAL</code></td> - <td>2</td> - <td>Corresponds to the value <code>perceptual</code>.</td> - </tr> - <tr> - <td><code>RENDERING_INTENT_RELATIVE_COLORIMETRIC</code></td> - <td>3</td> - <td>Corresponds to the value <code>relative-colorimetric</code>.</td> - </tr> - <tr> - <td><code>RENDERING_INTENT_SATURATION</code></td> - <td>4</td> - <td>Corresponds to the value <code>saturation</code>.</td> - </tr> - <tr> - <td><code>RENDERING_INTENT_ABSOLUTE_COLORIMETRIC</code></td> - <td>5</td> - <td>Corresponds to the value <code>absolute-colorimetric</code>.</td> - </tr> - </tbody> -</table> - ## Instance properties _This interface doesn't implement any specific properties._ @@ -70,6 +24,21 @@ _This interface doesn't implement any specific properties._ _This interface doesn't implement any specific methods._ +## Static properties + +- `RENDERING_INTENT_UNKNOWN` (0) + - : The type is not one of predefined types. It is invalid to attempt to define a new value of this type or to attempt to switch an existing value to this type. +- `RENDERING_INTENT_AUTO` (1) + - : Corresponds to the value `auto`. +- `RENDERING_INTENT_PERCEPTUAL` (2) + - : Corresponds to the value `perceptual`. +- `RENDERING_INTENT_RELATIVE_COLORIMETRIC` (3) + - : Corresponds to the value `relative-colorimetric`. +- `RENDERING_INTENT_SATURATION` (4) + - : Corresponds to the value `saturation`. +- `RENDERING_INTENT_ABSOLUTE_COLORIMETRIC` (5) + - : Corresponds to the value `absolute-colorimetric`. + ## Specifications {{Specifications}} diff --git a/files/en-us/web/api/svgscriptelement/type/index.md b/files/en-us/web/api/svgscriptelement/type/index.md index edddc20aeb2ee85..4fdb687aa04fe90 100644 --- a/files/en-us/web/api/svgscriptelement/type/index.md +++ b/files/en-us/web/api/svgscriptelement/type/index.md @@ -20,7 +20,7 @@ An string. ```html <svg xmlns="http://www.w3.org/2000/svg" width="400" height="200"> - <script id="myScript" href="script.js" type="application/javascript"></script> + <script id="myScript" href="script.js" type="text/javascript"></script> </svg> ``` @@ -28,7 +28,7 @@ An string. const scriptElement = document.getElementById("myScript"); // Access the type property -console.log(scriptElement.type); // Output: "application/javascript" +console.log(scriptElement.type); // Output: "text/javascript" ``` ## Specifications diff --git a/files/en-us/web/api/svgstringlist/numberofitems/index.md b/files/en-us/web/api/svgstringlist/numberofitems/index.md index 9f00e03a49bc9e3..7051019eeb77c92 100644 --- a/files/en-us/web/api/svgstringlist/numberofitems/index.md +++ b/files/en-us/web/api/svgstringlist/numberofitems/index.md @@ -8,7 +8,7 @@ browser-compat: api.SVGStringList.numberOfItems {{APIRef("SVG")}} -The **`numberOfItems`** property of the {{domxref("SVGStringList")}} interface returns the number of items in the list. {{domxref("SVGStringList.length", "length")}} is an alias of of it. +The **`numberOfItems`** property of the {{domxref("SVGStringList")}} interface returns the number of items in the list. {{domxref("SVGStringList.length", "length")}} is an alias of it. ## Value diff --git a/files/en-us/web/api/svgstyleelement/disabled/index.md b/files/en-us/web/api/svgstyleelement/disabled/index.md index 001d9d592d4bfa7..2e0299dceb9e037 100644 --- a/files/en-us/web/api/svgstyleelement/disabled/index.md +++ b/files/en-us/web/api/svgstyleelement/disabled/index.md @@ -10,7 +10,7 @@ browser-compat: api.SVGStyleElement.disabled The **`SVGStyleElement.disabled`** property can be used to get and set whether the stylesheet is disabled (`true`) or not (`false`). -Note that there is no corresponding `disabled` attribute on the [SVG `<style>` element](/en-US/docs/Web/SVG/Element/style). +Note that there is no corresponding `disabled` attribute on the [SVG `<style>` element](/en-US/docs/Web/SVG/Reference/Element/style). ## Value @@ -28,7 +28,7 @@ This example demonstrates programmatically setting the disabled property on a st #### HTML -The HTML contains an SVG definition for a [`<circle>`](/en-US/docs/Web/SVG/Element/circle) with a [`<style>`](/en-US/docs/Web/SVG/Element/style) element, along with a button that will be used to disable the style. +The HTML contains an SVG definition for a [`<circle>`](/en-US/docs/Web/SVG/Reference/Element/circle) with a [`<style>`](/en-US/docs/Web/SVG/Reference/Element/style) element, along with a button that will be used to disable the style. ```html <button>Enable</button> @@ -118,7 +118,7 @@ Note that this is the earliest point at which setting the property to `true` wil Before this point the SVG did not have a style associated, and so the value defaults to `false`. ```js -//Disable the style +// Disable the style style.disabled = true; ``` diff --git a/files/en-us/web/api/svgstyleelement/index.md b/files/en-us/web/api/svgstyleelement/index.md index ad07bae32c1ad93..af3f7b4102f17dd 100644 --- a/files/en-us/web/api/svgstyleelement/index.md +++ b/files/en-us/web/api/svgstyleelement/index.md @@ -25,7 +25,7 @@ _This interface also inherits properties from its parent interface, {{domxref("S - {{domxref("SVGStyleElement.title")}} - - : A string corresponding to the [`title`](/en-US/docs/Web/SVG/Element/style#title) attribute of the given element. + - : A string corresponding to the [`title`](/en-US/docs/Web/SVG/Reference/Element/style#title) attribute of the given element. - {{domxref("SVGStyleElement.sheet")}} {{ReadOnlyInline}} @@ -119,7 +119,7 @@ This example demonstrates how to get and set the properties of a style element, ### HTML -The HTML contains an SVG definition for a [`<circle>`](/en-US/docs/Web/SVG/Element/circle) with a [`<style>`](/en-US/docs/Web/SVG/Element/style) element, along with an HTML [`<button>`](/en-US/docs/Web/HTML/Element/button) element that will be used to enable and disable the style, and an HTML [`<textarea>`](/en-US/docs/Web/HTML/Element/button) element for logging the property values. +The HTML contains an SVG definition for a [`<circle>`](/en-US/docs/Web/SVG/Reference/Element/circle) with a [`<style>`](/en-US/docs/Web/SVG/Reference/Element/style) element, along with an HTML [`<button>`](/en-US/docs/Web/HTML/Reference/Elements/button) element that will be used to enable and disable the style, and an HTML [`<textarea>`](/en-US/docs/Web/HTML/Reference/Elements/button) element for logging the property values. ```html <button>Disable</button> @@ -158,7 +158,7 @@ This is called after initialization, whenever the frame resizes, and if the butt const log = document.getElementById("log"); function setLogText() { - //Log current values of properties + // Log current values of properties log.value = `style.media: ${style.media} (frame width: ${window.innerWidth})\n`; // 'all' by default log.value += `style.title: ${style.title}\n`; // no default value log.value += `style.disabled: ${style.disabled}\n`; // 'false' by default diff --git a/files/en-us/web/api/svgstyleelement/media/index.md b/files/en-us/web/api/svgstyleelement/media/index.md index 3d963752014725f..f19b74421ca5a55 100644 --- a/files/en-us/web/api/svgstyleelement/media/index.md +++ b/files/en-us/web/api/svgstyleelement/media/index.md @@ -8,7 +8,7 @@ browser-compat: api.SVGStyleElement.media {{APIRef("SVG")}} -The **`SVGStyleElement.media`** property is a media query string corresponding to the [`media`](/en-US/docs/Web/SVG/Element/style#media) attribute of the given SVG style element. +The **`SVGStyleElement.media`** property is a media query string corresponding to the [`media`](/en-US/docs/Web/SVG/Reference/Element/style#media) attribute of the given SVG style element. The query must be matched for the style to apply. @@ -17,7 +17,7 @@ The query must be matched for the style to apply. A string defining a valid media query list with one or more comma separated values. For example `"screen, print"`, or `"all"` (the default). -The value is initialized with the string specified in the corresponding style's [`media`](/en-US/docs/Web/SVG/Element/style#media) attribute. +The value is initialized with the string specified in the corresponding style's [`media`](/en-US/docs/Web/SVG/Reference/Element/style#media) attribute. ## Examples @@ -25,7 +25,7 @@ This example demonstrates programmatically getting and setting the media propert ### HTML -The HTML contains an SVG definition for a [`<circle>`](/en-US/docs/Web/SVG/Element/circle) with a [`<style>`](/en-US/docs/Web/SVG/Element/style) element that is conditional on the media query `"all and (min-width: 600px)"`. +The HTML contains an SVG definition for a [`<circle>`](/en-US/docs/Web/SVG/Reference/Element/circle) with a [`<style>`](/en-US/docs/Web/SVG/Reference/Element/style) element that is conditional on the media query `"all and (min-width: 600px)"`. We also define a `button` that will be used to display the current style and change the style. ```html diff --git a/files/en-us/web/api/svgstyleelement/sheet/index.md b/files/en-us/web/api/svgstyleelement/sheet/index.md index ee6ed0254451d80..6a4b56b36283c38 100644 --- a/files/en-us/web/api/svgstyleelement/sheet/index.md +++ b/files/en-us/web/api/svgstyleelement/sheet/index.md @@ -20,7 +20,7 @@ This example demonstrates how to get the CSS sheet associated with an element. ### HTML -The HTML contains an SVG definition for a [`<circle>`](/en-US/docs/Web/SVG/Element/circle). +The HTML contains an SVG definition for a [`<circle>`](/en-US/docs/Web/SVG/Reference/Element/circle). ```html <textarea id="log" rows="3" cols="50"></textarea> diff --git a/files/en-us/web/api/svgstyleelement/title/index.md b/files/en-us/web/api/svgstyleelement/title/index.md index 014a879e2174693..471aae8a046669e 100644 --- a/files/en-us/web/api/svgstyleelement/title/index.md +++ b/files/en-us/web/api/svgstyleelement/title/index.md @@ -8,14 +8,14 @@ browser-compat: api.SVGStyleElement.title {{APIRef("SVG")}} -The **`SVGStyleElement.title`** property is a string corresponding to the [`title`](/en-US/docs/Web/SVG/Element/style#title) attribute of the given SVG style element. -It may be used to select between [alternate style sheets](/en-US/docs/Web/HTML/Attributes/rel/alternate_stylesheet). +The **`SVGStyleElement.title`** property is a string corresponding to the [`title`](/en-US/docs/Web/SVG/Reference/Element/style#title) attribute of the given SVG style element. +It may be used to select between [alternate style sheets](/en-US/docs/Web/HTML/Reference/Attributes/rel/alternate_stylesheet). ## Value A string with any value. -The value is initialized with the string specified in the corresponding style's [`title`](/en-US/docs/Web/SVG/Element/style#title) attribute. +The value is initialized with the string specified in the corresponding style's [`title`](/en-US/docs/Web/SVG/Reference/Element/style#title) attribute. ## Examples @@ -23,7 +23,7 @@ This example demonstrates programmatically getting and setting the `title` prope ### HTML -The HTML contains an SVG definition for a [`<circle>`](/en-US/docs/Web/SVG/Element/circle) with a [`<style>`](/en-US/docs/Web/SVG/Element/style) element that has a `title`. +The HTML contains an SVG definition for a [`<circle>`](/en-US/docs/Web/SVG/Reference/Element/circle) with a [`<style>`](/en-US/docs/Web/SVG/Reference/Element/style) element that has a `title`. We also define a text area for logging the current title. ```html diff --git a/files/en-us/web/api/svgstyleelement/type/index.md b/files/en-us/web/api/svgstyleelement/type/index.md index c670f753551c266..318cac980fc63e1 100644 --- a/files/en-us/web/api/svgstyleelement/type/index.md +++ b/files/en-us/web/api/svgstyleelement/type/index.md @@ -11,7 +11,7 @@ browser-compat: api.SVGStyleElement.type {{APIRef("SVG")}} {{Deprecated_Header}} The **`SVGStyleElement.type`** property returns the type of the current style. -The value reflects the associated SVG `<style>` element's [`type`](/en-US/docs/Web/SVG/Element/style#type) attribute. +The value reflects the associated SVG `<style>` element's [`type`](/en-US/docs/Web/SVG/Reference/Element/style#type) attribute. Authors should not use this property or rely on the value. diff --git a/files/en-us/web/api/svgsvgelement/getelementbyid/index.md b/files/en-us/web/api/svgsvgelement/getelementbyid/index.md index 3afcb5b2276cda7..6628a08f79b29ad 100644 --- a/files/en-us/web/api/svgsvgelement/getelementbyid/index.md +++ b/files/en-us/web/api/svgsvgelement/getelementbyid/index.md @@ -49,7 +49,7 @@ const elementDisplay = document.getElementById("elementDisplay"); getElementButton.addEventListener("click", () => { const circleElement = svgElement.getElementById("circle1"); if (circleElement) { - elementDisplay.textContent = "Element found: " + circleElement.tagName; + elementDisplay.textContent = `Element found: ${circleElement.tagName}`; } else { elementDisplay.textContent = "Element not found."; } diff --git a/files/en-us/web/api/svgsvgelement/viewbox/index.md b/files/en-us/web/api/svgsvgelement/viewbox/index.md index 7cd50b69ba8d1e5..2b87e320271922a 100644 --- a/files/en-us/web/api/svgsvgelement/viewbox/index.md +++ b/files/en-us/web/api/svgsvgelement/viewbox/index.md @@ -23,7 +23,7 @@ An {{domxref("SVGAnimatedRect")}}. Give the following SVG opening tag: ```html -<svg viewbox="-12 -18 200 300" x="5" y="5" height="400" width="600"></svg> +<svg viewBox="-12 -18 200 300" x="5" y="5" height="400" width="600"></svg> ``` We can retrieve the viewBox values, but they differ from the {{domxref("SVGSVGElement.x", "x")}}, {{domxref("SVGSVGElement.y", "y")}}, {{domxref("SVGSVGElement.width", "width")}}, and {{domxref("SVGSVGElement.height", "height")}} properties: @@ -34,16 +34,16 @@ const vBox = svg.viewBox; // The SVGSVGElement viewBox property console.dir(vBox); // SVGAnimatedRect { baseVal: SVGRect, animVal: SVGRect } -​console.log(vBox.baseVal.x); // -12 -​console.log(vBox.baseVal.y); // -18 -​console.log(vBox.baseVal.width); // 200 -​console.log(vBox.baseVal.height); // 300 +console.log(vBox.baseVal.x); // -12 +console.log(vBox.baseVal.y); // -18 +console.log(vBox.baseVal.width); // 200 +console.log(vBox.baseVal.height); // 300 // Other SVGSVGElement properties -​console.log(svg.x); // 5 -​console.log(svg.y); // 5 -​console.log(svg.width); // 400 -​console.log(svg.height); // 600 +console.log(svg.x); // 5 +console.log(svg.y); // 5 +console.log(svg.width); // 400 +console.log(svg.height); // 600 ``` ## Specifications diff --git a/files/en-us/web/api/svgsvgelement/x/index.md b/files/en-us/web/api/svgsvgelement/x/index.md index 9a4d0f3f19528e4..e6d13fa71dd4936 100644 --- a/files/en-us/web/api/svgsvgelement/x/index.md +++ b/files/en-us/web/api/svgsvgelement/x/index.md @@ -8,7 +8,7 @@ browser-compat: api.SVGSVGElement.x {{APIRef("SVG")}} -The **`x`** read-only property of the {{domxref("SVGSVGElement")}} interface describes the horizontal coordinate of the position of that SVG as an {{domxref("SVGAnimatedLength")}}. When an {{SVGElement("svg")}} is nested within another `<svg>`, the horizontal coordinate is a length in the user coordinate system that is the given distance from the origin of the user coordinate system along the x-axis. Its syntax is the same as that for [`<length>`](/en-US/docs/Web/SVG/Content_type#length). +The **`x`** read-only property of the {{domxref("SVGSVGElement")}} interface describes the horizontal coordinate of the position of that SVG as an {{domxref("SVGAnimatedLength")}}. When an {{SVGElement("svg")}} is nested within another `<svg>`, the horizontal coordinate is a length in the user coordinate system that is the given distance from the origin of the user coordinate system along the x-axis. Its syntax is the same as that for [`<length>`](/en-US/docs/Web/SVG/Guides/Content_type#length). It reflects the {{SVGElement("svg")}} element's {{SVGAttr("x")}} geometric attribute. The default value is `0`. The `x` attribute has no effect on outermost `<svg>` elements; only one nested ones. The CSS {{cssxref("x")}} property takes precedence over the `<svg>` element's `x` attribute, so the value may not reflect the element's appearance. diff --git a/files/en-us/web/api/svgsvgelement/y/index.md b/files/en-us/web/api/svgsvgelement/y/index.md index e623c01d275d5f3..4f27ccdb55a446f 100644 --- a/files/en-us/web/api/svgsvgelement/y/index.md +++ b/files/en-us/web/api/svgsvgelement/y/index.md @@ -8,7 +8,7 @@ browser-compat: api.SVGSVGElement.y {{APIRef("SVG")}} -The **`y`** read-only property of the {{domxref("SVGSVGElement")}} interface describes the vertical coordinate of the position of that SVG as an {{domxref("SVGAnimatedLength")}}. When an {{SVGElement("svg")}} is nested within another `<svg>`, the vertical coordinate is a length in the user coordinate system that is the given distance from the origin of the user coordinate system along the y-axis. Its syntax is the same as that for [`<length>`](/en-US/docs/Web/SVG/Content_type#length). +The **`y`** read-only property of the {{domxref("SVGSVGElement")}} interface describes the vertical coordinate of the position of that SVG as an {{domxref("SVGAnimatedLength")}}. When an {{SVGElement("svg")}} is nested within another `<svg>`, the vertical coordinate is a length in the user coordinate system that is the given distance from the origin of the user coordinate system along the y-axis. Its syntax is the same as that for [`<length>`](/en-US/docs/Web/SVG/Guides/Content_type#length). It reflects the {{SVGElement("svg")}} element's {{SVGAttr("y")}} geometric attribute. The default value is `0`. The `y` attribute has no effect on outermost `<svg>` elements; only on nested ones. The CSS {{cssxref("y")}} property takes precedence over the `<svg>` element's `y` attribute, so the value may not reflect the element's appearance. diff --git a/files/en-us/web/api/svgtextcontentelement/index.md b/files/en-us/web/api/svgtextcontentelement/index.md index 68fe1f93690b209..51e15063629937b 100644 --- a/files/en-us/web/api/svgtextcontentelement/index.md +++ b/files/en-us/web/api/svgtextcontentelement/index.md @@ -7,37 +7,10 @@ browser-compat: api.SVGTextContentElement {{APIRef("SVG")}} -The **`SVGTextContentElement`** interface is implemented by elements that support rendering child text content. It is inherited by various text-related interfaces, such as {{domxref("SVGTextElement")}}, {{domxref("SVGTSpanElement")}}, {{domxref("SVGTRefElement")}}, and {{domxref("SVGTextPathElement")}}. +The **`SVGTextContentElement`** interface is implemented by elements that support rendering child text content. It is inherited by various text-related interfaces, such as {{domxref("SVGTextElement")}}, {{domxref("SVGTSpanElement")}}, and {{domxref("SVGTextPathElement")}}. {{InheritanceDiagram}} -## Constants - -<table class="standard-table"> - <tbody> - <tr> - <td>Constant</td> - <td>Value</td> - <td>Description</td> - </tr> - <tr> - <td>LENGTHADJUST_UNKNOWN</td> - <td>0</td> - <td>Some other value.</td> - </tr> - <tr> - <td>LENGTHADJUST_SPACING</td> - <td>1</td> - <td>The <code>spacing</code> keyword.</td> - </tr> - <tr> - <td>LENGTHADJUST_SPACINGANDGLYPHS</td> - <td>2</td> - <td>The <code>spacingAndGlyphs</code> keyword.</td> - </tr> - </tbody> -</table> - ## Instance properties _This interface also inherits properties from its parent, {{domxref("SVGGraphicsElement")}}._ @@ -45,7 +18,7 @@ _This interface also inherits properties from its parent, {{domxref("SVGGraphics - {{domxref("SVGTextContentElement.textLength")}} {{ReadOnlyInline}} - : An {{domxref("SVGAnimatedLength")}} reflecting the {{SVGAttr("textLength")}} attribute of the given element. - {{domxref("SVGTextContentElement.lengthAdjust")}} {{ReadOnlyInline}} - - : An {{domxref("SVGAnimatedEnumeration")}} reflecting the {{SVGAttr("lengthAdjust")}} attribute of the given element. The numeric type values represent one of the constant values above. + - : An {{domxref("SVGAnimatedEnumeration")}} reflecting the {{SVGAttr("lengthAdjust")}} attribute of the given element. The numeric type values represent one of the `LENGTHADJUST_*` constant values. ## Instance methods @@ -80,6 +53,15 @@ _This interface also inherits methods from its parent, {{domxref("SVGGraphicsEle - {{domxref("SVGTextContentElement.selectSubString()")}} {{deprecated_inline}} - : Selects text within the element. +## Static properties + +- `LENGTHADJUST_UNKNOWN` (0) + - : The type is not one of predefined types. It is invalid to attempt to define a new value of this type or to attempt to switch an existing value to this type. +- `LENGTHADJUST_SPACING` (1) + - : Corresponds to the value `spacing`. +- `LENGTHADJUST_SPACINGANDGLYPHS` (2) + - : Corresponds to the value `spacingAndGlyphs`. + ## Specifications {{Specifications}} diff --git a/files/en-us/web/api/svgtextpathelement/index.md b/files/en-us/web/api/svgtextpathelement/index.md index 930dd92eed3709c..a65f0b5a9a28924 100644 --- a/files/en-us/web/api/svgtextpathelement/index.md +++ b/files/en-us/web/api/svgtextpathelement/index.md @@ -11,76 +11,12 @@ The **`SVGTextPathElement`** interface corresponds to the {{SVGElement("textPath {{InheritanceDiagram}} -## Constants - -### Method types - -<table class="no-markdown"> - <tbody> - <tr> - <th>Name</th> - <th>Value</th> - <th>Description</th> - </tr> - <tr> - <td><code>TEXTPATH_METHODTYPE_UNKNOWN</code></td> - <td>0</td> - <td> - The type is not one of predefined types. It is invalid to attempt to - define a new value of this type or to attempt to switch an existing - value to this type. - </td> - </tr> - <tr> - <td><code>TEXTPATH_METHODTYPE_ALIGN</code></td> - <td>1</td> - <td>Corresponds to the value <code>align</code>.</td> - </tr> - <tr> - <td><code>TEXTPATH_METHODTYPE_STRETCH</code></td> - <td>2</td> - <td>Corresponds to the value <code>stretch</code>.</td> - </tr> - </tbody> -</table> - -### Spacing types - -<table class="no-markdown"> - <tbody> - <tr> - <th>Name</th> - <th>Value</th> - <th>Description</th> - </tr> - <tr> - <td><code>TEXTPATH_SPACINGTYPE_UNKNOWN</code></td> - <td>0</td> - <td> - The type is not one of predefined types. It is invalid to attempt to - define a new value of this type or to attempt to switch an existing - value to this type. - </td> - </tr> - <tr> - <td><code>TEXTPATH_SPACINGTYPE_AUTO</code></td> - <td>1</td> - <td>Corresponds to the value <code>auto</code>.</td> - </tr> - <tr> - <td><code>TEXTPATH_SPACINGTYPE_EXACT</code></td> - <td>2</td> - <td>Corresponds to the value <code>exact</code>.</td> - </tr> - </tbody> -</table> - ## Instance properties _This interface also inherits properties from its parent interface, {{domxref("SVGTextContentElement")}}._ - {{domxref("SVGTextPathElement.href")}} {{ReadOnlyInline}} - - : An {{domxref("SVGAnimatedString")}} corresponding to the {{SVGAttr("href")}} or {{SVGAttr("xlink:href")}} {{deprecated_inline}} attribute of the given element. + - : An {{domxref("SVGAnimatedString")}} corresponding to the {{SVGAttr("href")}} or {{SVGAttr("xlink:href")}} attribute of the given element. - {{domxref("SVGTextPathElement.startOffset")}} {{ReadOnlyInline}} - : An {{domxref("SVGAnimatedLength")}} corresponding to the X component of the {{SVGAttr("startOffset")}} attribute of the given element. - {{domxref("SVGTextPathElement.method")}} {{ReadOnlyInline}} @@ -92,6 +28,21 @@ _This interface also inherits properties from its parent interface, {{domxref("S _This interface does not provide any specific methods, but implements those of its parent, {{domxref("SVGTextContentElement")}}._ +## Static properties + +- `TEXTPATH_METHODTYPE_UNKNOWN` (0) + - : The type is not one of predefined types. It is invalid to attempt to define a new value of this type or to attempt to switch an existing value to this type. +- `TEXTPATH_METHODTYPE_ALIGN` (1) + - : Corresponds to the value `align`. +- `TEXTPATH_METHODTYPE_STRETCH` (2) + - : Corresponds to the value `stretch`. +- `TEXTPATH_SPACINGTYPE_UNKNOWN` (0) + - : The type is not one of predefined types. It is invalid to attempt to define a new value of this type or to attempt to switch an existing value to this type. +- `TEXTPATH_SPACINGTYPE_AUTO` (1) + - : Corresponds to the value `auto`. +- `TEXTPATH_SPACINGTYPE_EXACT` (2) + - : Corresponds to the value `exact`. + ## Specifications {{Specifications}} diff --git a/files/en-us/web/api/svgtextpathelement/method/index.md b/files/en-us/web/api/svgtextpathelement/method/index.md index 53072a3a2439935..c23afadb3c234e0 100644 --- a/files/en-us/web/api/svgtextpathelement/method/index.md +++ b/files/en-us/web/api/svgtextpathelement/method/index.md @@ -8,7 +8,7 @@ browser-compat: api.SVGTextPathElement.method {{APIRef("SVG")}} -The **`method`** read-only property of the {{domxref("SVGTextPathElement")}} interface reflects the {{SVGAttr("method")}} attribute of the given {{SVGElement("textPath")}} element. It takes one of the [`TEXTPATH_METHODTYPE_*` constants](/en-US/docs/Web/API/SVGTextPathElement#method_types) defined on this interface. +The **`method`** read-only property of the {{domxref("SVGTextPathElement")}} interface reflects the {{SVGAttr("method")}} attribute of the given {{SVGElement("textPath")}} element. It takes one of the [`TEXTPATH_METHODTYPE_*` constants](/en-US/docs/Web/API/SVGTextPathElement#static_properties) defined on this interface. ## Value @@ -49,4 +49,4 @@ console.log(textPath.method.baseVal); // Output: 1 (TEXTPATH_METHODTYPE_ALIGN) ## See also - {{domxref("SVGTextPathElement.spacing")}} -- [`SVGTextPathElement` method types](/en-US/docs/Web/API/SVGTextPathElement#method_types) +- [`SVGTextPathElement` method types](/en-US/docs/Web/API/SVGTextPathElement#static_properties) diff --git a/files/en-us/web/api/svgtextpathelement/spacing/index.md b/files/en-us/web/api/svgtextpathelement/spacing/index.md index bfef01984afceef..a0f22534c6883a1 100644 --- a/files/en-us/web/api/svgtextpathelement/spacing/index.md +++ b/files/en-us/web/api/svgtextpathelement/spacing/index.md @@ -8,7 +8,7 @@ browser-compat: api.SVGTextPathElement.spacing {{APIRef("SVG")}} -The **`spacing`** read-only property of the {{domxref("SVGTextPathElement")}} interface reflects the {{SVGAttr("spacing")}} attribute of the given {{SVGElement("textPath")}} element. It takes one of the [`TEXTPATH_SPACINGTYPE_*` constants](/en-US/docs/Web/API/SVGTextPathElement#spacing_types) defined on this interface. +The **`spacing`** read-only property of the {{domxref("SVGTextPathElement")}} interface reflects the {{SVGAttr("spacing")}} attribute of the given {{SVGElement("textPath")}} element. It takes one of the [`TEXTPATH_SPACINGTYPE_*` constants](/en-US/docs/Web/API/SVGTextPathElement#static_properties) defined on this interface. ## Value @@ -49,4 +49,4 @@ console.log(textPath.spacing.baseVal); // Output: 1 (TEXTPATH_SPACINGTYPE_AUTO) ## See also - {{domxref("SVGTextPathElement.method")}} -- [`SVGTextPathElement` spacing types](/en-US/docs/Web/API/SVGTextPathElement#spacing_types) +- [`SVGTextPathElement` spacing types](/en-US/docs/Web/API/SVGTextPathElement#static_properties) diff --git a/files/en-us/web/api/svgtextpositioningelement/dx/index.md b/files/en-us/web/api/svgtextpositioningelement/dx/index.md index 8f6ba4ff91b96ca..e3ad3a9ad008948 100644 --- a/files/en-us/web/api/svgtextpositioningelement/dx/index.md +++ b/files/en-us/web/api/svgtextpositioningelement/dx/index.md @@ -8,9 +8,9 @@ browser-compat: api.SVGTextPositioningElement.dx {{APIRef("SVG")}} -The **`dx`** read-only property of the {{domxref("SVGTextPositioningElement")}} interface describes the x-axis coordinate of the {{domxref("SVGTextElement")}}, {{domxref("SVGTSpanElement")}}, or {{domxref("SVGTRefElement")}} as an {{domxref("SVGAnimatedLengthList")}}. It reflects the {{SVGAttr("dx")}} attribute's horizontal displacement of the individual text glyphs in the user coordinate system. +The **`dx`** read-only property of the {{domxref("SVGTextPositioningElement")}} interface describes the x-axis coordinate of the {{domxref("SVGTextElement")}} or {{domxref("SVGTSpanElement")}} as an {{domxref("SVGAnimatedLengthList")}}. It reflects the {{SVGAttr("dx")}} attribute's horizontal displacement of the individual text glyphs in the user coordinate system. -The attribute value is a list of [`<length>`](/en-US/docs/Web/SVG/Content_type#length), [`<percentage>`](/en-US/docs/Web/SVG/Content_type#percentage), or [`<number>`](/en-US/docs/Web/SVG/Content_type#number). The numeric values in the {{domxref("SVGAnimatedLengthList.baseVal")}} reflect the horizontal displacements in the user coordinate system. +The attribute value is a list of [`<length>`](/en-US/docs/Web/SVG/Guides/Content_type#length), [`<percentage>`](/en-US/docs/Web/SVG/Guides/Content_type#percentage), or [`<number>`](/en-US/docs/Web/SVG/Guides/Content_type#number). The numeric values in the {{domxref("SVGAnimatedLengthList.baseVal")}} reflect the horizontal displacements in the user coordinate system. ## Value diff --git a/files/en-us/web/api/svgtextpositioningelement/dy/index.md b/files/en-us/web/api/svgtextpositioningelement/dy/index.md index 114311ca76f2efe..3b9d121b95c34d7 100644 --- a/files/en-us/web/api/svgtextpositioningelement/dy/index.md +++ b/files/en-us/web/api/svgtextpositioningelement/dy/index.md @@ -8,9 +8,9 @@ browser-compat: api.SVGTextPositioningElement.dy {{APIRef("SVG")}} -The **`dy`** read-only property of the {{domxref("SVGTextPositioningElement")}} interface describes the y-axis coordinate of the {{domxref("SVGTextElement")}}, {{domxref("SVGTSpanElement")}}, or {{domxref("SVGTRefElement")}} as an {{domxref("SVGAnimatedLengthList")}}. It reflects the {{SVGAttr("dy")}} attribute's vertical displacement of the individual text glyphs in the user coordinate system. +The **`dy`** read-only property of the {{domxref("SVGTextPositioningElement")}} interface describes the y-axis coordinate of the {{domxref("SVGTextElement")}} or {{domxref("SVGTSpanElement")}} as an {{domxref("SVGAnimatedLengthList")}}. It reflects the {{SVGAttr("dy")}} attribute's vertical displacement of the individual text glyphs in the user coordinate system. -The attribute value is a list of [`<length>`](/en-US/docs/Web/SVG/Content_type#length), [`<percentage>`](/en-US/docs/Web/SVG/Content_type#percentage), or [`<number>`](/en-US/docs/Web/SVG/Content_type#number). The numeric values in the {{domxref("SVGAnimatedLengthList.baseVal")}} reflect the vertical displacements in the user coordinate system. +The attribute value is a list of [`<length>`](/en-US/docs/Web/SVG/Guides/Content_type#length), [`<percentage>`](/en-US/docs/Web/SVG/Guides/Content_type#percentage), or [`<number>`](/en-US/docs/Web/SVG/Guides/Content_type#number). The numeric values in the {{domxref("SVGAnimatedLengthList.baseVal")}} reflect the vertical displacements in the user coordinate system. ## Value diff --git a/files/en-us/web/api/svgtextpositioningelement/index.md b/files/en-us/web/api/svgtextpositioningelement/index.md index 6e38b361a4e473e..c35e570090deb52 100644 --- a/files/en-us/web/api/svgtextpositioningelement/index.md +++ b/files/en-us/web/api/svgtextpositioningelement/index.md @@ -7,7 +7,7 @@ browser-compat: api.SVGTextPositioningElement {{APIRef("SVG")}} -The **`SVGTextPositioningElement`** interface is implemented by elements that support attributes that position individual text glyphs. It is inherited by {{domxref("SVGTextElement")}}, {{domxref("SVGTSpanElement")}}, and {{domxref("SVGTRefElement")}}. +The **`SVGTextPositioningElement`** interface is implemented by elements that support attributes that position individual text glyphs. It is inherited by {{domxref("SVGTextElement")}} and {{domxref("SVGTSpanElement")}}. {{InheritanceDiagram}} diff --git a/files/en-us/web/api/svgtextpositioningelement/rotate/index.md b/files/en-us/web/api/svgtextpositioningelement/rotate/index.md index e9d60f3a4c094b9..8774d116e076850 100644 --- a/files/en-us/web/api/svgtextpositioningelement/rotate/index.md +++ b/files/en-us/web/api/svgtextpositioningelement/rotate/index.md @@ -3,7 +3,7 @@ title: "SVGTextPositioningElement: rotate property" short-title: rotate slug: Web/API/SVGTextPositioningElement/rotate page-type: web-api-instance-property -browser-compat: api.SVGAnimationElement.rotate +browser-compat: api.SVGTextPositioningElement.rotate --- {{APIRef("SVG")}} diff --git a/files/en-us/web/api/svgtextpositioningelement/x/index.md b/files/en-us/web/api/svgtextpositioningelement/x/index.md index 0e432ee7844bd23..ab5638e3581b624 100644 --- a/files/en-us/web/api/svgtextpositioningelement/x/index.md +++ b/files/en-us/web/api/svgtextpositioningelement/x/index.md @@ -8,9 +8,9 @@ browser-compat: api.SVGTextPositioningElement.x {{APIRef("SVG")}} -The **`x`** read-only property of the {{domxref("SVGTextPositioningElement")}} interface describes the x-axis coordinate of the {{domxref("SVGTextElement")}}, {{domxref("SVGTSpanElement")}}, or {{domxref("SVGTRefElement")}} as an {{domxref("SVGAnimatedLengthList")}}. It reflects the {{SVGAttr("x")}} attribute's horizontal position of the individual text glyphs in the user coordinate system. +The **`x`** read-only property of the {{domxref("SVGTextPositioningElement")}} interface describes the x-axis coordinate of the {{domxref("SVGTextElement")}} or {{domxref("SVGTSpanElement")}} as an {{domxref("SVGAnimatedLengthList")}}. It reflects the {{SVGAttr("x")}} attribute's horizontal position of the individual text glyphs in the user coordinate system. -The attribute value is a list of [`<length>`](/en-US/docs/Web/SVG/Content_type#length), [`<percentage>`](/en-US/docs/Web/SVG/Content_type#percentage), or [`<number>`](/en-US/docs/Web/SVG/Content_type#number). The numeric values in the {{domxref("SVGAnimatedLengthList.baseVal")}} reflect the x-coordinates in the user coordinate system. +The attribute value is a list of [`<length>`](/en-US/docs/Web/SVG/Guides/Content_type#length), [`<percentage>`](/en-US/docs/Web/SVG/Guides/Content_type#percentage), or [`<number>`](/en-US/docs/Web/SVG/Guides/Content_type#number). The numeric values in the {{domxref("SVGAnimatedLengthList.baseVal")}} reflect the x-coordinates in the user coordinate system. ## Value diff --git a/files/en-us/web/api/svgtextpositioningelement/y/index.md b/files/en-us/web/api/svgtextpositioningelement/y/index.md index 6bd03f4ca502239..bf2c9f74b447402 100644 --- a/files/en-us/web/api/svgtextpositioningelement/y/index.md +++ b/files/en-us/web/api/svgtextpositioningelement/y/index.md @@ -8,9 +8,9 @@ browser-compat: api.SVGTextPositioningElement.y {{APIRef("SVG")}} -The **`y`** read-only property of the {{domxref("SVGTextPositioningElement")}} interface describes the y-axis coordinate of the {{domxref("SVGTextElement")}}, {{domxref("SVGTSpanElement")}}, or {{domxref("SVGTRefElement")}} as an {{domxref("SVGAnimatedLengthList")}}. It reflects the {{SVGAttr("y")}} attribute's vertical position of the individual text glyphs in the user coordinate system. +The **`y`** read-only property of the {{domxref("SVGTextPositioningElement")}} interface describes the y-axis coordinate of the {{domxref("SVGTextElement")}} or {{domxref("SVGTSpanElement")}} as an {{domxref("SVGAnimatedLengthList")}}. It reflects the {{SVGAttr("y")}} attribute's vertical position of the individual text glyphs in the user coordinate system. -The attribute value is a list of [`<length>`](/en-US/docs/Web/SVG/Content_type#length), [`<percentage>`](/en-US/docs/Web/SVG/Content_type#percentage), or [`<number>`](/en-US/docs/Web/SVG/Content_type#number). The numeric values in the {{domxref("SVGAnimatedLengthList.baseVal")}} reflect the y-coordinates in the user coordinate system. +The attribute value is a list of [`<length>`](/en-US/docs/Web/SVG/Guides/Content_type#length), [`<percentage>`](/en-US/docs/Web/SVG/Guides/Content_type#percentage), or [`<number>`](/en-US/docs/Web/SVG/Guides/Content_type#number). The numeric values in the {{domxref("SVGAnimatedLengthList.baseVal")}} reflect the y-coordinates in the user coordinate system. ## Value diff --git a/files/en-us/web/api/svgtransform/index.md b/files/en-us/web/api/svgtransform/index.md index e002dee8c8b06ba..77e521bee60b519 100644 --- a/files/en-us/web/api/svgtransform/index.md +++ b/files/en-us/web/api/svgtransform/index.md @@ -7,361 +7,50 @@ browser-compat: api.SVGTransform {{APIRef("SVG")}} -## SVG transform interface - -`SVGTransform` is the interface for one of the component transformations within an {{ domxref("SVGTransformList") }}; thus, an `SVGTransform` object corresponds to a single component (e.g., `scale(…)` or `matrix(…)`) within a {{ SVGAttr("transform") }} attribute. +The **`SVGTransform`** interface reflects one of the component transformations within an {{ domxref("SVGTransformList") }}; thus, an `SVGTransform` object corresponds to a single component (e.g., `scale(…)` or `matrix(…)`) within a {{ SVGAttr("transform") }} attribute. An `SVGTransform` object can be designated as read only, which means that attempts to modify the object will result in an exception being thrown. -### Interface overview - -<table class="no-markdown"> - <tbody> - <tr> - <th scope="row">Also implement</th> - <td><em>None</em></td> - </tr> - <tr> - <th scope="row">Methods</th> - <td> - <ul> - <li> - <code - >void setMatrix(in {{ domxref("DOMMatrix") }} - matrix)</code - > - </li> - <li><code>void setTranslate(in float tx, in float ty)</code></li> - <li><code>void setScale(in float sx, in float sy)</code></li> - <li> - <code - >void setRotate(in float angle, in float cx, in float cy)</code - > - </li> - <li><code>void setSkewX(in float angle)</code></li> - <li><code>void setSkewY(in float angle)</code></li> - </ul> - </td> - </tr> - <tr> - <th scope="row">Properties</th> - <td> - <ul> - <li>readonly unsigned short <code>type</code></li> - <li>readonly float <code>angle</code></li> - <li> - readonly {{ domxref("DOMMatrix") }} <code>matrix</code> - </li> - </ul> - </td> - </tr> - <tr> - <th scope="row">Constants</th> - <td> - <ul> - <li><code>SVG_TRANSFORM_UNKNOWN</code> = 0</li> - <li><code>SVG_TRANSFORM_MATRIX</code> = 1</li> - <li><code>SVG_TRANSFORM_TRANSLATE</code> = 2</li> - <li><code>SVG_TRANSFORM_SCALE</code> = 3</li> - <li><code>SVG_TRANSFORM_ROTATE</code> = 4</li> - <li><code>SVG_TRANSFORM_SKEWX</code> = 5</li> - <li><code>SVG_TRANSFORM_SKEWY</code> = 6</li> - </ul> - </td> - </tr> - <tr> - <th scope="row">Normative document</th> - <td> - <a href="https://www.w3.org/TR/SVG11/coords.html#InterfaceSVGTransform" - >SVG 1.1 (2nd Edition)</a - > - </td> - </tr> - </tbody> -</table> - -## Constants - -<table class="no-markdown"> - <tbody> - <tr> - <th>Name</th> - <th>Value</th> - <th>Description</th> - </tr> - <tr> - <td><code>SVG_TRANSFORM_UNKNOWN</code></td> - <td>0</td> - <td> - The unit type is not one of predefined unit types. It is invalid to - attempt to define a new value of this type or to attempt to switch an - existing value to this type. - </td> - </tr> - <tr> - <td><code>SVG_TRANSFORM_MATRIX</code></td> - <td>1</td> - <td>A <code>matrix(…)</code> transformation</td> - </tr> - <tr> - <td><code>SVG_TRANSFORM_TRANSLATE</code></td> - <td>2</td> - <td>A <code>translate(…)</code> transformation</td> - </tr> - <tr> - <td><code>SVG_TRANSFORM_SCALE</code></td> - <td>3</td> - <td>A <code>scale(…)</code> transformation</td> - </tr> - <tr> - <td><code>SVG_TRANSFORM_ROTATE</code></td> - <td>4</td> - <td>A <code>rotate(…)</code> transformation</td> - </tr> - <tr> - <td><code>SVG_TRANSFORM_SKEWX</code></td> - <td>5</td> - <td>A <code>skewx(…)</code> transformation</td> - </tr> - <tr> - <td><code>SVG_TRANSFORM_SKEWY</code></td> - <td>6</td> - <td>A <code>skewy(…)</code> transformation</td> - </tr> - </tbody> -</table> - ## Instance properties -<table class="no-markdown"> - <thead> - <tr> - <th>Name</th> - <th>Type</th> - <th>Description</th> - </tr> - </thead> - <tbody> - <tr> - <td><code>{{domxref("SVGTransform.type", "type")}}</code></td> - <td>unsigned short</td> - <td> - The type of the value as specified by one of the SVG_TRANSFORM_* - constants defined on this interface. - </td> - </tr> - <tr> - <td><code>{{domxref("SVGTransform.angle", "angle")}}</code></td> - <td>float</td> - <td> - A convenience attribute for <code>SVG_TRANSFORM_ROTATE</code>, - <code>SVG_TRANSFORM_SKEWX</code> and <code>SVG_TRANSFORM_SKEWY</code>. - It holds the angle that was specified.<br /><br />For - <code>SVG_TRANSFORM_MATRIX</code>, - <code>SVG_TRANSFORM_TRANSLATE</code> and - <code>SVG_TRANSFORM_SCALE</code>, <code>angle</code> will be zero. - </td> - </tr> - <tr> - <td><code>{{domxref("SVGTransform.matrix", "matrix")}}</code></td> - <td>{{ domxref("DOMMatrix") }}</td> - <td> - <p> - The matrix that represents this transformation. The matrix object is - live, meaning that any changes made to the - <code>SVGTransform</code> object are immediately reflected in the - matrix object and vice versa. In case the matrix object is changed - directly (i.e., without using the methods on the - <code>SVGTransform</code> interface itself) then the type of the - <code>SVGTransform</code> changes to - <code>SVG_TRANSFORM_MATRIX</code>. - </p> - <ul> - <li> - For <code>SVG_TRANSFORM_MATRIX</code>, the matrix contains the a, b, - c, d, e, f values supplied by the user. - </li> - <li> - For <code>SVG_TRANSFORM_TRANSLATE</code>, e and f represent the - translation amounts (a=1, b=0, c=0 and d=1). - </li> - <li> - For <code>SVG_TRANSFORM_SCALE</code>, a and d represent the scale - amounts (b=0, c=0, e=0 and f=0). - </li> - <li> - For <code>SVG_TRANSFORM_SKEWX</code> and - <code>SVG_TRANSFORM_SKEWY</code>, a, b, c and d represent the matrix - which will result in the given skew (e=0 and f=0). - </li> - <li> - For <code>SVG_TRANSFORM_ROTATE</code>, a, b, c, d, e and f together - represent the matrix which will result in the given rotation. When - the rotation is around the center point (0, 0), e and f will be - zero. - </li> - </ul> - </td> - </tr> - </tbody> -</table> +- {{domxref("SVGTransform.type", "type")}} + - : The type of the value as specified by one of the `SVG_TRANSFORM_*` constants defined on this interface. +- {{domxref("SVGTransform.angle", "angle")}} + - : The angle as a floating point value. A convenience attribute for `SVG_TRANSFORM_ROTATE`, `SVG_TRANSFORM_SKEWX` and `SVG_TRANSFORM_SKEWY`. For `SVG_TRANSFORM_MATRIX`, `SVG_TRANSFORM_TRANSLATE` and `SVG_TRANSFORM_SCALE`, `angle` will be zero. +- {{domxref("SVGTransform.matrix", "matrix")}} + - : The matrix as a {{ domxref("DOMMatrix") }} that represents this transformation. The matrix object is live, meaning that any changes made to the `SVGTransform` object are immediately reflected in the matrix object and vice versa. In case the matrix object is changed directly (i.e., without using the methods on the `SVGTransform` interface itself) then the type of the `SVGTransform` changes to `SVG_TRANSFORM_MATRIX`. ## Instance methods -<table class="no-markdown"> - <thead> - <tr> - <th>Name &#x26; Arguments</th> - <th>Return</th> - <th>Description</th> - </tr> - </thead> - <tbody> - <tr> - <td> - <code - ><strong>{{domxref("SVGTransform.setMatrix", "setMatrix")}}</strong>(in {{ domxref("DOMMatrix") }} - <em>matrix</em>)</code - > - </td> - <td><em>void</em></td> - <td> - <p> - Sets the transform type to <code>SVG_TRANSFORM_MATRIX</code>, with - parameter matrix defining the new transformation. Note that the values - from the parameter <code>matrix</code> are copied. - </p> - <p><strong>Exceptions:</strong></p> - <ul> - <li> - a {{ domxref("DOMException") }} with code - <code>NO_MODIFICATION_ALLOWED_ERR</code> is raised when attempting - to modify a read only attribute or when the object itself is read - only. - </li> - </ul> - </td> - </tr> - <tr> - <td> - <code - ><strong>{{domxref("SVGTransform.setTranslate", "setTranslate")}}</strong>(in float <em>tx</em>, in float - <em>ty</em>)</code - > - </td> - <td><em>void</em></td> - <td> - <p> - Sets the transform type to <code>SVG_TRANSFORM_TRANSLATE</code>, with - parameters <code>tx</code> and <code>ty</code> defining the - translation amounts. - </p> - <p><strong>Exceptions:</strong></p> - <ul> - <li> - a {{ domxref("DOMException") }} with code - <code>NO_MODIFICATION_ALLOWED_ERR</code> is raised when attempting - to modify a read only attribute or when the object itself is read - only. - </li> - </ul> - </td> - </tr> - <tr> - <td> - <code - ><strong>{{domxref("SVGTransform.setScale", "setScale")}}</strong>(in float <em>sx</em>, in float - <em>sy</em>)</code - > - </td> - <td><em>void</em></td> - <td> - <p> - Sets the transform type to <code>SVG_TRANSFORM_SCALE</code>, with - parameters <code>sx</code> and <code>sy</code> defining the scale - amounts. - </p> - <p><strong>Exceptions:</strong></p> - <ul> - <li> - a {{ domxref("DOMException") }} with code - <code>NO_MODIFICATION_ALLOWED_ERR</code> is raised when attempting - to modify a read only attribute or when the object itself is read - only. - </li> - </ul> - </td> - </tr> - <tr> - <td> - <code - ><strong>{{domxref("SVGTransform.setRotate", "setRotate")}}</strong>(in float <em>angle</em>, in float - <em>cx</em>, in float <em>cy</em>)</code - > - </td> - <td><em>void</em></td> - <td> - <p> - Sets the transform type to <code>SVG_TRANSFORM_ROTATE</code>, with - parameter <code>angle</code> defining the rotation angle and - parameters <code>cx</code> and <code>cy</code> defining the optional - center of rotation. - </p> - <p><strong>Exceptions:</strong></p> - <ul> - <li> - a {{ domxref("DOMException") }} with code - <code>NO_MODIFICATION_ALLOWED_ERR</code> is raised when attempting - to modify a read only attribute or when the object itself is read - only. - </li> - </ul> - </td> - </tr> - <tr> - <td> - <code><strong>{{domxref("SVGTransform.setSkewX", "setSkewX")}}</strong>(in float <em>angle</em>)</code> - </td> - <td><em>void</em></td> - <td> - <p> - Sets the transform type to <code>SVG_TRANSFORM_SKEWX</code>, with - parameter <code>angle</code> defining the amount of skew. - </p> - <p><strong>Exceptions:</strong></p> - <ul> - <li> - a {{ domxref("DOMException") }} with code - <code>NO_MODIFICATION_ALLOWED_ERR</code> is raised when attempting - to modify a read only attribute or when the object itself is read - only. - </li> - </ul> - </td> - </tr> - <tr> - <td> - <code><strong>{{domxref("SVGTransform.setSkewY", "setSkewY")}}</strong>(in float <em>angle</em>)</code> - </td> - <td><em>void</em></td> - <td> - <p> - Sets the transform type to <code>SVG_TRANSFORM_SKEWY</code>, with - parameter <code>angle</code> defining the amount of skew. - </p> - <p><strong>Exceptions:</strong></p> - <ul> - <li> - a {{ domxref("DOMException") }} with code - <code>NO_MODIFICATION_ALLOWED_ERR</code> is raised when attempting - to modify a read only attribute or when the object itself is read - only. - </li> - </ul> - </td> - </tr> - </tbody> -</table> +- {{domxref("SVGTransform.setMatrix", "setMatrix()")}} + - : Sets the transform type to `SVG_TRANSFORM_MATRIX`, with parameter matrix defining the new transformation. Note that the values from the parameter `matrix` are copied. +- {{domxref("SVGTransform.setTranslate", "setTranslate()")}} + - : Sets the transform type to `SVG_TRANSFORM_TRANSLATE`, with parameters `tx` and `ty` defining the translation amounts. +- {{domxref("SVGTransform.setScale", "setScale()")}} + - : Sets the transform type to `SVG_TRANSFORM_SCALE`, with parameters `sx` and `sy` defining the scale amounts. +- {{domxref("SVGTransform.setRotate", "setRotate()")}} + - : Sets the transform type to `SVG_TRANSFORM_ROTATE`, with parameter `angle` defining the rotation angle and parameters `cx` and `cy` defining the optional center of rotation. +- {{domxref("SVGTransform.setSkewX", "setSkewX()")}} + - : Sets the transform type to `SVG_TRANSFORM_SKEWX`, with parameter `angle` defining the amount of skew. +- {{domxref("SVGTransform.setSkewY", "setSkewY()")}} + - : Sets the transform type to `SVG_TRANSFORM_SKEWY`, with parameter `angle` defining the amount of skew. + +## Static properties + +- `SVG_TRANSFORM_UNKNOWN` (0) + - : The unit type is not one of predefined unit types. It is invalid to attempt to define a new value of this type or to attempt to switch an existing value to this type. +- `SVG_TRANSFORM_MATRIX` (1) + - : A `matrix(…)` transformation. +- `SVG_TRANSFORM_TRANSLATE` (2) + - : A `translate(…)` transformation. +- `SVG_TRANSFORM_SCALE` (3) + - : A `scale(…)` transformation. +- `SVG_TRANSFORM_ROTATE` (4) + - : A `rotate(…)` transformation. +- `SVG_TRANSFORM_SKEWX` (5) + - : A `skewx(…)` transformation. +- `SVG_TRANSFORM_SKEWY` (6) + - : A `skewy(…)` transformation. ## Specifications diff --git a/files/en-us/web/api/svgtransformlist/index.md b/files/en-us/web/api/svgtransformlist/index.md index f3e721fa3e84b7d..3b4c3e393e4fc6d 100644 --- a/files/en-us/web/api/svgtransformlist/index.md +++ b/files/en-us/web/api/svgtransformlist/index.md @@ -7,349 +7,39 @@ browser-compat: api.SVGTransformList {{APIRef("SVG")}} -## SVG transform list interface - -The `SVGTransformList` defines a list of {{ domxref("SVGTransform") }} objects. +The **`SVGTransformList`** interface defines a list of {{ domxref("SVGTransform") }} objects. An `SVGTransformList` object can be designated as read only, which means that attempts to modify the object will result in an exception being thrown. An `SVGTransformList` is indexable and can be accessed like an array. -### Interface overview - -<table class="standard-table"> - <tbody> - <tr> - <th scope="row">Also implement</th> - <td><em>None</em></td> - </tr> - <tr> - <th scope="row">Methods</th> - <td> - <ul> - <li><code>void clear()</code></li> - <li> - {{ domxref("SVGTransform") }} - <code - >initialize(in {{ domxref("SVGTransform") }} - <em>newItem</em>)</code - > - </li> - <li> - {{ domxref("SVGTransform") }} - <code>getItem(in unsigned long <em>index</em>)</code> - </li> - <li> - {{ domxref("SVGTransform") }} - <code - >insertItemBefore(in {{ domxref("SVGTransform") }} - <em>newItem</em>, in unsigned long <em>index</em>)</code - > - </li> - <li> - {{ domxref("SVGTransform") }} - <code - >replaceItem(in {{ domxref("SVGTransform") }} - <em>newItem</em>, in unsigned long <em>index</em>)</code - > - </li> - <li> - {{ domxref("SVGTransform") }} - <code>removeItem(in unsigned long <em>index</em>)</code> - </li> - <li> - {{ domxref("SVGTransform") }} - <code - >appendItem(in {{ domxref("SVGTransform") }} - <em>newItem</em>)</code - > - </li> - <li> - {{ domxref("SVGTransform") }} - <code - >createSVGTransformFromMatrix(in - {{ domxref("DOMMatrix") }})</code - > - </li> - <li> - {{ domxref("SVGTransform") }} <code>consolidate()</code> - </li> - </ul> - </td> - </tr> - <tr> - <th scope="row">Properties</th> - <td> - <ul> - <li>readonly unsigned long <code>numberOfItems</code></li> - <li> - readonly unsigned long - <code>length</code> - </li> - </ul> - </td> - </tr> - <tr> - <th scope="row">Normative document</th> - <td> - <a - href="https://www.w3.org/TR/SVG/coords.html#InterfaceSVGTransformList" - >SVG 1.1 (2nd Edition)</a - > - </td> - </tr> - </tbody> -</table> - ## Instance properties -| Name | Type | Description | -| -------------------------------------------------------------- | ------------- | -------------------------------- | -| {{domxref("SVGTransformList.numberOfItems", "numberOfItems")}} | unsigned long | The number of items in the list. | -| {{domxref("SVGTransformList.length", "length")}} | unsigned long | The number of items in the list. | +- {{domxref("SVGTransformList.numberOfItems", "numberOfItems")}} + - : The number of items in the list. +- {{domxref("SVGTransformList.length", "length")}} + - : The number of items in the list. ## Instance methods -<table class="standard-table"> - <thead> - <tr> - <th>Name &#x26; Arguments</th> - <th>Return</th> - <th>Description</th> - </tr> - </thead> - <tbody> - <tr> - <td> - <code><strong>{{domxref("SVGTransformList.clear", "clear")}}</strong>()</code> - </td> - <td><code>void</code></td> - <td> - <p> - Clears all existing current items from the list, with the result being - an empty list. - </p> - <p><strong>Exceptions:</strong></p> - <ul> - <li> - a {{ domxref("DOMException") }} with code - <code>NO_MODIFICATION_ALLOWED_ERR</code> is raised when the list - corresponds to a read only attribute or when the object itself is - read only. - </li> - </ul> - </td> - </tr> - <tr> - <td> - <code - ><strong>{{domxref("SVGTransformList.initialize", "initialize")}}</strong>(in - {{ domxref("SVGTransform") }} <em>newItem</em>)</code - > - </td> - <td>{{ domxref("SVGTransform") }}</td> - <td> - <p> - Clears all existing current items from the list and re-initializes the - list to hold the single item specified by the parameter. If the - inserted item is already in a list, it is removed from its previous - list before it is inserted into this list. The inserted item is the - item itself and not a copy. The return value is the item inserted into - the list. - </p> - <p><strong>Exceptions:</strong></p> - <ul> - <li> - a {{ domxref("DOMException") }} with code - <code>NO_MODIFICATION_ALLOWED_ERR</code> is raised when the list - corresponds to a read only attribute or when the object itself is - read only. - </li> - </ul> - </td> - </tr> - <tr> - <td> - <code><strong>{{domxref("SVGTransformList.getItem", "getItem")}}</strong>(in unsigned long <em>index</em>)</code> - </td> - <td>{{ domxref("SVGTransform") }}</td> - <td> - <p> - Returns the specified item from the list. The returned item is the - item itself and not a copy. Any changes made to the item are - immediately reflected in the list. The first item is number 0. - </p> - <p><strong>Exceptions:</strong></p> - <ul> - <li> - a {{ domxref("DOMException") }} with code - <code>NO_MODIFICATION_ALLOWED_ERR</code> is raised when the list - corresponds to a read only attribute or when the object itself is - read only. - </li> - </ul> - </td> - </tr> - <tr> - <td> - <code - ><strong>{{domxref("SVGTransformList.insertItemBefore", "insertItemBefore")}}</strong>(in - {{ domxref("SVGTransform") }} <em>newItem</em>, in unsigned - long <em>index</em>)</code - > - </td> - <td>{{ domxref("SVGTransform") }}</td> - <td> - <p> - Inserts a new item into the list at the specified position. The first - item is number 0. If <code>newItem</code> is already in a list, it is - removed from its previous list before it is inserted into this list. - The inserted item is the item itself and not a copy. If the item is - already in this list, note that the index of the item to insert before - is before the removal of the item. If the <code>index</code> is equal - to 0, then the new item is inserted at the front of the list. If the - index is greater than or equal to <code>numberOfItems</code>, then the - new item is appended to the end of the list. - </p> - <p><strong>Exceptions:</strong></p> - <ul> - <li> - a {{ domxref("DOMException") }} with code - <code>NO_MODIFICATION_ALLOWED_ERR</code> is raised when the list - corresponds to a read only attribute or when the object itself is - read only. - </li> - </ul> - </td> - </tr> - <tr> - <td> - <code - ><strong>{{domxref("SVGTransformList.replaceItem", "replaceItem")}}</strong>(in - {{ domxref("SVGTransform") }} <em>newItem</em>, in unsigned - long <em>index</em>)</code - > - </td> - <td>{{ domxref("SVGTransform") }}</td> - <td> - <p> - Replaces an existing item in the list with a new item. If - <code>newItem</code> is already in a list, it is removed from its - previous list before it is inserted into this list. The inserted item - is the item itself and not a copy. If the item is already in this - list, note that the index of the item to replace is before the removal - of the item. - </p> - <p><strong>Exceptions:</strong></p> - <ul> - <li> - a {{ domxref("DOMException") }} with code - <code>NO_MODIFICATION_ALLOWED_ERR</code> is raised when the list - corresponds to a read only attribute or when the object itself is - read only. - </li> - <li> - a {{ domxref("DOMException") }} with code - <code>INDEX_SIZE_ERR</code> is raised if the index number is greater - than or equal to <code>numberOfItems</code>. - </li> - </ul> - </td> - </tr> - <tr> - <td> - <code - ><strong>{{domxref("SVGTransformList.removeItem", "removeItem")}}</strong>(in unsigned long <em>index</em>)</code - > - </td> - <td>{{ domxref("SVGTransform") }}</td> - <td> - <p>Removes an existing item from the list.</p> - <p><strong>Exceptions:</strong></p> - <ul> - <li> - a {{ domxref("DOMException") }} with code - <code>NO_MODIFICATION_ALLOWED_ERR</code> is raised when the list - corresponds to a read only attribute or when the object itself is - read only. - </li> - <li> - a {{ domxref("DOMException") }} with code - <code>INDEX_SIZE_ERR</code> is raised if the index number is greater - than or equal to <code>numberOfItems</code>. - </li> - </ul> - </td> - </tr> - <tr> - <td> - <code - ><strong>{{domxref("SVGTransformList.appendItem", "appendItem")}}</strong>(in - {{ domxref("SVGTransform") }} <em>newItem</em>)</code - > - </td> - <td>{{ domxref("SVGTransform") }}</td> - <td> - <p> - Inserts a new item at the end of the list. If <code>newItem</code> is - already in a list, it is removed from its previous list before it is - inserted into this list. The inserted item is the item itself and not - a copy. - </p> - <p><strong>Exceptions:</strong></p> - <ul> - <li> - a {{ domxref("DOMException") }} with code - <code>NO_MODIFICATION_ALLOWED_ERR</code> is raised when the list - corresponds to a read only attribute or when the object itself is - read only. - </li> - </ul> - </td> - </tr> - <tr> - <td> - <code - ><strong>{{domxref("SVGTransformList.createSVGTransformFromMatrix", "createSVGTransformFromMatrix")}}</strong>(in - {{ domxref("DOMMatrix") }})</code - > - </td> - <td>{{ domxref("SVGTransform") }}</td> - <td> - Creates an <code>SVGTransform</code> object which is initialized to - transform of type <code>SVG_TRANSFORM_MATRIX</code> and whose values are - the given matrix. The values from the parameter matrix are copied, the - matrix parameter is not adopted as <code>SVGTransform::matrix</code>. - </td> - </tr> - <tr> - <td> - <code><strong>{{domxref("SVGTransformList.consolidate", "consolidate")}}</strong>()</code> - </td> - <td>{{ domxref("SVGTransform") }}</td> - <td> - <p> - Consolidates the list of separate <code>SVGTransform</code> objects by - multiplying the equivalent transformation matrices together to result - in a list consisting of a single <code>SVGTransform</code> object of - type <code>SVG_TRANSFORM_MATRIX</code>. The consolidation operation - creates new <code>SVGTransform</code> object as the first and only - item in the list. The returned item is the item itself and not a copy. - Any changes made to the item are immediately reflected in the list. - </p> - <p><strong>Exceptions:</strong></p> - <ul> - <li> - a {{ domxref("DOMException") }} with code - <code>NO_MODIFICATION_ALLOWED_ERR</code> is raised when the list - corresponds to a read only attribute or when the object itself is - read only. - </li> - </ul> - </td> - </tr> - </tbody> -</table> +- {{domxref("SVGTransformList.clear", "clear()")}} + - : Clears all existing current items from the list, with the result being an empty list. +- {{domxref("SVGTransformList.initialize", "initialize()")}} + - : Clears all existing current items from the list and re-initializes the list to hold the single item specified by the parameter. If the inserted item is already in a list, it is removed from its previous list before it is inserted into this list. The inserted item is the item itself and not a copy. The return value is the item inserted into the list. +- {{domxref("SVGTransformList.getItem", "getItem()")}} + - : Returns the specified item from the list. The returned item is the item itself and not a copy. Any changes made to the item are immediately reflected in the list. The first item is number `0`. +- {{domxref("SVGTransformList.insertItemBefore", "insertItemBefore()")}} + - : Inserts a new item into the list at the specified position. The first item is number `0`. If `newItem` is already in a list, it is removed from its previous list before it is inserted into this list. The inserted item is the item itself and not a copy. If the item is already in this list, note that the index of the item to insert before is before the removal of the item. If the `index` is equal to 0, then the new item is inserted at the front of the list. If the index is greater than or equal to `numberOfItems`, then the new item is appended to the end of the list. +- {{domxref("SVGTransformList.replaceItem", "replaceItem()")}} + - : Replaces an existing item in the list with a new item. If `newItem` is already in a list, it is removed from its previous list before it is inserted into this list. The inserted item is the item itself and not a copy. If the item is already in this list, note that the index of the item to replace is before the removal of the item. +- {{domxref("SVGTransformList.removeItem", "removeItem()")}} + - : Removes an existing item from the list. +- {{domxref("SVGTransformList.appendItem", "appendItem()")}} + - : Inserts a new item at the end of the list. If `newItem` is already in a list it is removed from its previous list before it is inserted into this list. The inserted item is the item itself and not a copy. +- {{domxref("SVGTransformList.createSVGTransformFromMatrix", "createSVGTransformFromMatrix()")}} + - : Creates an `SVGTransform` object which is initialized to transform of type `SVG_TRANSFORM_MATRIX` and whose values are the given matrix. The values from the parameter matrix are copied, the matrix parameter is not adopted as `SVGTransform::matrix`. +- {{domxref("SVGTransformList.consolidate", "consolidate()")}} + - : Consolidates the list of separate `SVGTransform` objects by multiplying the equivalent transformation matrices together to result in a list consisting of a single `SVGTransform` object of type `SVG_TRANSFORM_MATRIX`. The consolidation operation creates new `SVGTransform` object as the first and only item in the list. The returned item is the item itself and not a copy. Any changes made to the item are immediately reflected in the list. ## Examples @@ -367,7 +57,7 @@ In this example we create a function that will apply three different transformat Example showing how to transform svg elements that using SVGTransform objects </desc> - <script type="application/ecmascript"> + <script> <![CDATA[ function transformMe(evt) { // svg root element to access the createSVGTransform() function diff --git a/files/en-us/web/api/svgtrefelement/index.md b/files/en-us/web/api/svgtrefelement/index.md deleted file mode 100644 index 17e6976ba314c07..000000000000000 --- a/files/en-us/web/api/svgtrefelement/index.md +++ /dev/null @@ -1,36 +0,0 @@ ---- -title: SVGTRefElement -slug: Web/API/SVGTRefElement -page-type: web-api-interface -status: - - deprecated -browser-compat: api.SVGTRefElement ---- - -{{APIRef("SVG")}}{{deprecated_header}} - -The **`SVGTRefElement`** interface corresponds to the {{SVGElement("tref")}} elements. - -Object-oriented access to the attributes of the {{SVGElement("tref")}} element via the SVG DOM is not possible. - -{{InheritanceDiagram}} - -## Instance properties - -_This interface has no properties but inherits properties from its parent, {{domxref("SVGTextPositioningElement")}}._ - -## Instance methods - -_This interface has no methods but inherits methods from its parent, {{domxref("SVGTextPositioningElement")}}._ - -## Specifications - -{{Specifications}} - -## Browser compatibility - -{{Compat}} - -## See also - -- {{SVGElement("tref")}} diff --git a/files/en-us/web/api/svgunittypes/index.md b/files/en-us/web/api/svgunittypes/index.md index 24984e63040415a..52dbaa15176673b 100644 --- a/files/en-us/web/api/svgunittypes/index.md +++ b/files/en-us/web/api/svgunittypes/index.md @@ -11,15 +11,6 @@ The **`SVGUnitTypes`** interface defines a commonly used set of constants used f {{InheritanceDiagram}} -## Constants - -- `SVG_UNIT_TYPE_UNKNOWN` (0) - - : The type is not one of predefined types. It is invalid to attempt to define a new value of this type or to attempt to switch an existing value to this type. -- `SVG_UNIT_TYPE_USERSPACEONUSE` (1) - - : Corresponds to the value `userSpaceOnUse`. -- `SVG_UNIT_TYPE_OBJECTBOUNDINGBOX` (2) - - : Corresponds to the value `objectBoundingBox`. - ## Instance properties _This interface doesn't implement any specific properties._ @@ -28,6 +19,15 @@ _This interface doesn't implement any specific properties._ _This interface doesn't implement any specific methods._ +## Static properties + +- `SVG_UNIT_TYPE_UNKNOWN` (0) + - : The type is not one of predefined types. It is invalid to attempt to define a new value of this type or to attempt to switch an existing value to this type. +- `SVG_UNIT_TYPE_USERSPACEONUSE` (1) + - : Corresponds to the value `userSpaceOnUse`. +- `SVG_UNIT_TYPE_OBJECTBOUNDINGBOX` (2) + - : Corresponds to the value `objectBoundingBox`. + ## Specifications {{Specifications}} diff --git a/files/en-us/web/api/svguseelement/height/index.md b/files/en-us/web/api/svguseelement/height/index.md index d12a489e659442c..4d63b442c742eea 100644 --- a/files/en-us/web/api/svguseelement/height/index.md +++ b/files/en-us/web/api/svguseelement/height/index.md @@ -10,7 +10,7 @@ browser-compat: api.SVGUseElement.height The **`height`** read-only property of the {{domxref("SVGUseElement")}} interface describes the height of the referenced element as an {{domxref("SVGAnimatedLength")}}. It reflects the computed value of the {{SVGAttr("height")}} attribute on the {{SVGElement("use")}} element. -The attribute value is a [`<length>`](/en-US/docs/Web/SVG/Content_type#length), [`<percentage>`](/en-US/docs/Web/SVG/Content_type#percentage), or [`<number>`](/en-US/docs/Web/SVG/Content_type#number). The numeric value of the {{domxref("SVGAnimatedLength.baseVal")}} is the height of the referenced element in the user coordinate system. +The attribute value is a [`<length>`](/en-US/docs/Web/SVG/Guides/Content_type#length), [`<percentage>`](/en-US/docs/Web/SVG/Guides/Content_type#percentage), or [`<number>`](/en-US/docs/Web/SVG/Guides/Content_type#number). The numeric value of the {{domxref("SVGAnimatedLength.baseVal")}} is the height of the referenced element in the user coordinate system. ## Value diff --git a/files/en-us/web/api/svguseelement/width/index.md b/files/en-us/web/api/svguseelement/width/index.md index 2d8d0c9b04c679b..2d4afc32ff24b4d 100644 --- a/files/en-us/web/api/svguseelement/width/index.md +++ b/files/en-us/web/api/svguseelement/width/index.md @@ -10,7 +10,7 @@ browser-compat: api.SVGUseElement.width The **`width`** read-only property of the {{domxref("SVGUseElement")}} interface describes the width of the referenced element as an {{domxref("SVGAnimatedLength")}}. It reflects the computed value of the {{SVGAttr("width")}} attribute on the {{SVGElement("use")}} element. -The attribute value is a [`<length>`](/en-US/docs/Web/SVG/Content_type#length), [`<percentage>`](/en-US/docs/Web/SVG/Content_type#percentage), or [`<number>`](/en-US/docs/Web/SVG/Content_type#number). The numeric value of the {{domxref("SVGAnimatedLength.baseVal")}} is the width of the referenced element in the user coordinate system. +The attribute value is a [`<length>`](/en-US/docs/Web/SVG/Guides/Content_type#length), [`<percentage>`](/en-US/docs/Web/SVG/Guides/Content_type#percentage), or [`<number>`](/en-US/docs/Web/SVG/Guides/Content_type#number). The numeric value of the {{domxref("SVGAnimatedLength.baseVal")}} is the width of the referenced element in the user coordinate system. ## Value diff --git a/files/en-us/web/api/svguseelement/x/index.md b/files/en-us/web/api/svguseelement/x/index.md index a26f6defa149720..810fd3fe3c8f64b 100644 --- a/files/en-us/web/api/svguseelement/x/index.md +++ b/files/en-us/web/api/svguseelement/x/index.md @@ -10,7 +10,7 @@ browser-compat: api.SVGUseElement.x The **`x`** read-only property of the {{domxref("SVGUseElement")}} interface describes the x-axis coordinate of the start point of the referenced element as an {{domxref("SVGAnimatedLength")}}. It reflects the computed value of the {{SVGAttr("x")}} attribute on the {{SVGElement("use")}} element. -The attribute value is a [`<length>`](/en-US/docs/Web/SVG/Content_type#length), [`<percentage>`](/en-US/docs/Web/SVG/Content_type#percentage), or [`<number>`](/en-US/docs/Web/SVG/Content_type#number). The numeric value of the {{domxref("SVGAnimatedLength.baseVal")}} is the x-coordinate of the top-left corner of the referenced element in the user coordinate system. +The attribute value is a [`<length>`](/en-US/docs/Web/SVG/Guides/Content_type#length), [`<percentage>`](/en-US/docs/Web/SVG/Guides/Content_type#percentage), or [`<number>`](/en-US/docs/Web/SVG/Guides/Content_type#number). The numeric value of the {{domxref("SVGAnimatedLength.baseVal")}} is the x-coordinate of the top-left corner of the referenced element in the user coordinate system. ## Value diff --git a/files/en-us/web/api/svguseelement/y/index.md b/files/en-us/web/api/svguseelement/y/index.md index 30053ec9e91b66c..c7f73aaece2803c 100644 --- a/files/en-us/web/api/svguseelement/y/index.md +++ b/files/en-us/web/api/svguseelement/y/index.md @@ -10,7 +10,7 @@ browser-compat: api.SVGUseElement.y The **`y`** read-only property of the {{domxref("SVGUseElement")}} interface describes the y-axis coordinate of the start point of the referenced element as an {{domxref("SVGAnimatedLength")}}. It reflects the computed value of the {{SVGAttr("y")}} attribute on the {{SVGElement("use")}} element. -The attribute value is a [`<length>`](/en-US/docs/Web/SVG/Content_type#length), [`<percentage>`](/en-US/docs/Web/SVG/Content_type#percentage), or [`<number>`](/en-US/docs/Web/SVG/Content_type#number). The numeric value of the {{domxref("SVGAnimatedLength.baseVal")}} is the y-coordinate of the top-left corner of the referenced element in the user coordinate system. +The attribute value is a [`<length>`](/en-US/docs/Web/SVG/Guides/Content_type#length), [`<percentage>`](/en-US/docs/Web/SVG/Guides/Content_type#percentage), or [`<number>`](/en-US/docs/Web/SVG/Guides/Content_type#number). The numeric value of the {{domxref("SVGAnimatedLength.baseVal")}} is the y-coordinate of the top-left corner of the referenced element in the user coordinate system. ## Value diff --git a/files/en-us/web/api/svgvkernelement/index.md b/files/en-us/web/api/svgvkernelement/index.md deleted file mode 100644 index fe02233992d7bbd..000000000000000 --- a/files/en-us/web/api/svgvkernelement/index.md +++ /dev/null @@ -1,36 +0,0 @@ ---- -title: SVGVKernElement -slug: Web/API/SVGVKernElement -page-type: web-api-interface -status: - - deprecated -browser-compat: api.SVGVKernElement ---- - -{{APIRef("SVG")}}{{deprecated_header}} - -The **`SVGVKernElement`** interface corresponds to the {{SVGElement("vkern")}} elements. - -Object-oriented access to the attributes of the {{SVGElement("vkern")}} element via the SVG DOM is not possible. - -{{InheritanceDiagram}} - -## Instance properties - -_This interface has no properties but inherits properties from its parent, {{domxref("SVGElement")}}._ - -## Instance methods - -_This interface has no methods but inherits methods from its parent, {{domxref("SVGElement")}}._ - -## Specifications - -{{Specifications}} - -## Browser compatibility - -{{Compat}} - -## See also - -- {{SVGElement("vkern")}} diff --git a/files/en-us/web/api/taskattributiontiming/containerid/index.md b/files/en-us/web/api/taskattributiontiming/containerid/index.md index ef1d60611a85d15..447c58bc8e54d93 100644 --- a/files/en-us/web/api/taskattributiontiming/containerid/index.md +++ b/files/en-us/web/api/taskattributiontiming/containerid/index.md @@ -15,7 +15,7 @@ attribute. A container is the iframe, embed or object etc. that is being implica ## Value -A string containing the container's [`id`](/en-US/docs/Web/HTML/Global_attributes/id) HTML content attribute. +A string containing the container's [`id`](/en-US/docs/Web/HTML/Reference/Global_attributes/id) HTML content attribute. ## Specifications diff --git a/files/en-us/web/api/taskattributiontiming/containername/index.md b/files/en-us/web/api/taskattributiontiming/containername/index.md index 4ec21c1382ca030..6d2dff39f37ad6b 100644 --- a/files/en-us/web/api/taskattributiontiming/containername/index.md +++ b/files/en-us/web/api/taskattributiontiming/containername/index.md @@ -15,7 +15,7 @@ attribute. A container is the iframe, embed or object etc. that is being implica ## Value -A string containing the container's `name` HTML content attribute (e.g. [`<iframe name="myIframe">`](/en-US/docs/Web/HTML/Element/iframe#name) or [`<object name="myObject">`](/en-US/docs/Web/HTML/Element/object#name)). +A string containing the container's `name` HTML content attribute (e.g., [`<iframe name="myIframe">`](/en-US/docs/Web/HTML/Reference/Elements/iframe#name) or [`<object name="myObject">`](/en-US/docs/Web/HTML/Reference/Elements/object#name)). ## Specifications diff --git a/files/en-us/web/api/taskattributiontiming/containersrc/index.md b/files/en-us/web/api/taskattributiontiming/containersrc/index.md index d56f9acc4709b9e..2463de2e18a833c 100644 --- a/files/en-us/web/api/taskattributiontiming/containersrc/index.md +++ b/files/en-us/web/api/taskattributiontiming/containersrc/index.md @@ -15,7 +15,7 @@ attribute. A container is the iframe, embed or object etc. that is being implica ## Value -A string containing the container's `src` attribute (e.g. [`<iframe src="url.html">`](/en-US/docs/Web/HTML/Element/iframe#src)). +A string containing the container's `src` attribute (e.g., [`<iframe src="url.html">`](/en-US/docs/Web/HTML/Reference/Elements/iframe#src)). ## Specifications diff --git a/files/en-us/web/api/taskcontroller/index.md b/files/en-us/web/api/taskcontroller/index.md index 24e1974ed434b4d..bdd3a6be4ddf97c 100644 --- a/files/en-us/web/api/taskcontroller/index.md +++ b/files/en-us/web/api/taskcontroller/index.md @@ -41,7 +41,7 @@ _This interface also inherits the properties of its parent, {{domxref("AbortCont - `TaskController.signal` {{ReadOnlyInline}} - : Returns a {{domxref("TaskSignal")}} object instance. The signal is passed to tasks so that they can be aborted or re-prioritized by the controller. - The property is inherited from [`AbortController`](/en-US/docs/Web/API/AbortController#abortcontroller.signal). + The property is inherited from [`AbortController`](/en-US/docs/Web/API/AbortController/signal). ## Examples diff --git a/files/en-us/web/api/tasksignal/any_static/index.md b/files/en-us/web/api/tasksignal/any_static/index.md index 973649c7dc04ba2..dafcfcd223e16e4 100644 --- a/files/en-us/web/api/tasksignal/any_static/index.md +++ b/files/en-us/web/api/tasksignal/any_static/index.md @@ -29,7 +29,7 @@ TaskSignal.any(signals, init) - : Contains optional configuration parameters. Currently only one property is defined: - `priority` {{optional_inline}} - : One of the following: - - A string which is one of `user-blocking`, `user-visible` and `background`. + - A [priority](/en-US/docs/Web/API/Prioritized_Task_Scheduling_API#task_priorities) string which is one of `user-blocking`, `user-visible` and `background`. - A {{domxref("TaskSignal")}}. ### Return value @@ -41,7 +41,7 @@ A `TaskSignal` instance. It will be aborted when the first signal passed into `s - Its {{domxref("TaskSignal.priority", "priority")}} property will be determined by the `priority` parameter: - If the `priority` parameter was a string, it will be the value of the string. - - If the `priority` parameter was a `TaskSignal`, it will be the value of that signal's `priority`. + - If the `priority` parameter was a `TaskSignal`, it will be the value of that signal's {{domxref("TaskSignal/priority","priority")}}. ## Examples @@ -76,7 +76,7 @@ try { }); const body = await res.blob(); // Do something with downloaded content - // ... + // … } catch (e) { if (e.name === "AbortError") { // Cancelled by the user diff --git a/files/en-us/web/api/tasksignal/prioritychange_event/index.md b/files/en-us/web/api/tasksignal/prioritychange_event/index.md index 09f9c0f857fddb7..63c0ba2c354869f 100644 --- a/files/en-us/web/api/tasksignal/prioritychange_event/index.md +++ b/files/en-us/web/api/tasksignal/prioritychange_event/index.md @@ -14,10 +14,10 @@ The **`prioritychange`** event is sent to a {{domxref('TaskSignal')}} if its [pr Use the event name in methods like {{domxref("EventTarget.addEventListener", "addEventListener()")}}, or set an event handler property. -```js -addEventListener("prioritychange", (event) => {}); +```js-nolint +addEventListener("prioritychange", (event) => { }) -onprioritychange = (event) => {}; +onprioritychange = (event) => { } ``` ## Event type diff --git a/files/en-us/web/api/textdecoder/encoding/index.md b/files/en-us/web/api/textdecoder/encoding/index.md index 172d4a0cc3102de..e86fa089aac923b 100644 --- a/files/en-us/web/api/textdecoder/encoding/index.md +++ b/files/en-us/web/api/textdecoder/encoding/index.md @@ -25,7 +25,7 @@ A lower-cased ASCII string, which can be one of the following values: ['iso-8859-5'](https://en.wikipedia.org/wiki/ISO/IEC_8859-5), ['iso-8859-6'](https://en.wikipedia.org/wiki/ISO/IEC_8859-6), ['iso-8859-7'](https://en.wikipedia.org/wiki/ISO/IEC_8859-7), - ['iso-8859-8'](https://en.wikipedia.org/wiki/ISO/IEC_8859-8)'`, + ['iso-8859-8'](https://en.wikipedia.org/wiki/ISO/IEC_8859-8), ['iso-8859-8i'](https://en.wikipedia.org/wiki/ISO-8859-8-I), ['iso-8859-10'](https://en.wikipedia.org/wiki/ISO/IEC_8859-10), ['iso-8859-13'](https://en.wikipedia.org/wiki/ISO/IEC_8859-13), diff --git a/files/en-us/web/api/textdecoderstream/readable/index.md b/files/en-us/web/api/textdecoderstream/readable/index.md index eeacacb4b6179c5..1895f4fb0537acc 100644 --- a/files/en-us/web/api/textdecoderstream/readable/index.md +++ b/files/en-us/web/api/textdecoderstream/readable/index.md @@ -19,8 +19,8 @@ A {{domxref("ReadableStream")}}. This example shows how to return a {{domxref("ReadableStream")}} from a `TextDecoderStream`. ```js -stream = new TextDecoderStream(); -console.log(stream.readable); //a ReadableStream +const stream = new TextDecoderStream(); +console.log(stream.readable); // A ReadableStream ``` ## Specifications diff --git a/files/en-us/web/api/textencoderstream/encoding/index.md b/files/en-us/web/api/textencoderstream/encoding/index.md index 616031fa81787fe..cb1f401c7108867 100644 --- a/files/en-us/web/api/textencoderstream/encoding/index.md +++ b/files/en-us/web/api/textencoderstream/encoding/index.md @@ -20,7 +20,7 @@ A string containing `utf-8` encoded data. The following example demonstrates how to return `encoding` from a `TextEncoderStream` object. ```js -stream = new TextEncoderStream(); +const stream = new TextEncoderStream(); console.log(stream.encoding); ``` diff --git a/files/en-us/web/api/textencoderstream/readable/index.md b/files/en-us/web/api/textencoderstream/readable/index.md index 6111a9014bfa851..9c291971f70a111 100644 --- a/files/en-us/web/api/textencoderstream/readable/index.md +++ b/files/en-us/web/api/textencoderstream/readable/index.md @@ -19,8 +19,8 @@ A {{domxref("ReadableStream")}}. The following example demonstrates how to return a `ReadableStream` from a `TextEncoderStream` object. ```js -stream = new TextEncoderStream(); -console.log(stream.readable); //a ReadableStream +const stream = new TextEncoderStream(); +console.log(stream.readable); // A ReadableStream ``` ## Specifications diff --git a/files/en-us/web/api/textencoderstream/writable/index.md b/files/en-us/web/api/textencoderstream/writable/index.md index 14e28b3e1def1e3..fa3882444288935 100644 --- a/files/en-us/web/api/textencoderstream/writable/index.md +++ b/files/en-us/web/api/textencoderstream/writable/index.md @@ -19,7 +19,7 @@ A {{domxref("WritableStream")}}. The following example demonstrates how to return a `WritableStream` from a `TextEncoderStream` object. ```js -stream = new TextEncoderStream(); +const stream = new TextEncoderStream(); console.log(stream.writable); // A WritableStream ``` diff --git a/files/en-us/web/api/textformat/index.md b/files/en-us/web/api/textformat/index.md index 602b0cdaed78aa2..4b30be555e92912 100644 --- a/files/en-us/web/api/textformat/index.md +++ b/files/en-us/web/api/textformat/index.md @@ -11,7 +11,7 @@ browser-compat: api.TextFormat The **`TextFormat`** interface represents specific formatting that should be applied to a range of text in an editable text region that's attached to an {{domxref("EditContext")}} instance. The text formatting is requested by the {{glossary("Input Method Editor")}} (IME) window that the user is composing text with. -When using one of the default editable regions of the web, such as a [`<textarea>`](/en-US/docs/Web/HTML/Element/textarea) element, IME composition is handled by the browser and operating system for you. For example, when using Japanese IME in a textarea, on Windows, the following text formats can be applied: +When using one of the default editable regions of the web, such as a [`<textarea>`](/en-US/docs/Web/HTML/Reference/Elements/textarea) element, IME composition is handled by the browser and operating system for you. For example, when using Japanese IME in a textarea, on Windows, the following text formats can be applied: - When text is being composed with the keyboard, the typed characters have a thin wavy underline: diff --git a/files/en-us/web/api/texttrack/cuechange_event/index.md b/files/en-us/web/api/texttrack/cuechange_event/index.md index 1ef03132e500443..d517fcc2bddd725 100644 --- a/files/en-us/web/api/texttrack/cuechange_event/index.md +++ b/files/en-us/web/api/texttrack/cuechange_event/index.md @@ -14,10 +14,10 @@ The **`cuechange`** event fires when a {{domxref("TextTrack")}} has changed the Use the event name in methods like {{domxref("EventTarget.addEventListener", "addEventListener()")}}, or set an event handler property. -```js -addEventListener("cuechange", (event) => {}); +```js-nolint +addEventListener("cuechange", (event) => { }) -oncuechange = (event) => {}; +oncuechange = (event) => { } ``` ## Event type diff --git a/files/en-us/web/api/texttrack/index.md b/files/en-us/web/api/texttrack/index.md index 0cdca6e18c09209..d460c96f5064ef5 100644 --- a/files/en-us/web/api/texttrack/index.md +++ b/files/en-us/web/api/texttrack/index.md @@ -33,9 +33,9 @@ _This interface also inherits properties from {{domxref("EventTarget")}}._ - {{domxref("TextTrack.label")}} {{ReadOnlyInline}} - : A human-readable string which contains the text track's label, if one is present; otherwise, this is an empty string (`""`), in which case a custom label may need to be generated by your code using other attributes of the track, if the track's label needs to be exposed to the user. - {{domxref("TextTrack.language")}} {{ReadOnlyInline}} - - : A string which specifies the text language in which the text track's contents is written. The value must adhere to the format specified in {{RFC(5646, "Tags for Identifying Languages (also known as BCP 47)")}}, just like the HTML [`lang`](/en-US/docs/Web/HTML/Global_attributes/lang) attribute. For example, this can be `"en-US"` for United States English or `"pt-BR"` for Brazilian Portuguese. + - : A string which specifies the text language in which the text track's contents is written. The value must adhere to the format specified in {{RFC(5646, "Tags for Identifying Languages (also known as BCP 47)")}}, just like the HTML [`lang`](/en-US/docs/Web/HTML/Reference/Global_attributes/lang) attribute. For example, this can be `"en-US"` for United States English or `"pt-BR"` for Brazilian Portuguese. - {{domxref("TextTrack.mode")}} - - : A string specifying the track's current mode, which must be one of the permitted values. Changing this property's value changes the track's current mode to match. The default is `disabled`, unless the {{HTMLElement("track")}} element's [`default`](/en-US/docs/Web/HTML/Element/track#default) boolean attribute is set to `true` — in which case the default mode is `showing`. + - : A string specifying the track's current mode, which must be one of the permitted values. Changing this property's value changes the track's current mode to match. The default is `disabled`, unless the {{HTMLElement("track")}} element's [`default`](/en-US/docs/Web/HTML/Reference/Elements/track#default) boolean attribute is set to `true` — in which case the default mode is `showing`. - {{domxref("TextTrack.sourceBuffer", "sourceBuffer")}} {{ReadOnlyInline}} - : The {{domxref("SourceBuffer")}} that created the track. Returns null if the track was not created by a {{domxref("SourceBuffer")}} or the {{domxref("SourceBuffer")}} has been removed from the {{domxref("MediaSource.sourceBuffers")}} attribute of its parent media source. diff --git a/files/en-us/web/api/texttrack/language/index.md b/files/en-us/web/api/texttrack/language/index.md index b70c76b739171c5..e89b6d3e302b5a0 100644 --- a/files/en-us/web/api/texttrack/language/index.md +++ b/files/en-us/web/api/texttrack/language/index.md @@ -10,7 +10,7 @@ browser-compat: api.TextTrack.language The **`language`** read-only property of the {{domxref("TextTrack")}} interface returns the language of the text track. -This uses the same values as the HTML [`lang`](/en-US/docs/Web/HTML/Global_attributes/lang) attribute. These values are documented in {{RFC(5646, "Tags for Identifying Languages (also known as BCP 47)")}}. +This uses the same values as the HTML [`lang`](/en-US/docs/Web/HTML/Reference/Global_attributes/lang) attribute. These values are documented in {{RFC(5646, "Tags for Identifying Languages (also known as BCP 47)")}}. ## Value diff --git a/files/en-us/web/api/texttrack/mode/index.md b/files/en-us/web/api/texttrack/mode/index.md index 9ef4332aba394d3..d7727bef75ec059 100644 --- a/files/en-us/web/api/texttrack/mode/index.md +++ b/files/en-us/web/api/texttrack/mode/index.md @@ -26,7 +26,7 @@ A string which indicates the track's current mode. One of: - : The text track is currently disabled. While the track's presence is exposed in the DOM, the user agent is otherwise ignoring it. No cues are active, no events are being fired, and the user agent won't attempt to obtain the track's cues. This is the - default value, unless the text track has the [`default`](/en-US/docs/Web/HTML/Element/track#default) + default value, unless the text track has the [`default`](/en-US/docs/Web/HTML/Reference/Elements/track#default) Boolean attribute is specified, in which case the default is `showing`. - `hidden` - : The text track is currently active but the cues aren't being displayed. If the user @@ -41,12 +41,12 @@ A string which indicates the track's current mode. One of: list is being maintained and events are firing at the appropriate times; the track's text is also being drawn appropriately based on the styling and the track's {{domxref("TextTrack.kind", "kind")}}. This is the default value if the text - track's [`default`](/en-US/docs/Web/HTML/Element/track#default) Boolean attribute is specified. + track's [`default`](/en-US/docs/Web/HTML/Reference/Elements/track#default) Boolean attribute is specified. ## Usage notes The default `mode` is `disabled`, unless the -[`default`](/en-US/docs/Web/HTML/Element/track#default) Boolean attribute is specified, in which case the +[`default`](/en-US/docs/Web/HTML/Reference/Elements/track#default) Boolean attribute is specified, in which case the default `mode` is `showing`. When a text track is loaded in the `disabled` state, the corresponding WebVTT file is not loaded until the state changes to either `showing` or `hidden`. This way, the resource diff --git a/files/en-us/web/api/texttrackcue/enter_event/index.md b/files/en-us/web/api/texttrackcue/enter_event/index.md index 1f8d526b6e31c95..b756629acebac1e 100644 --- a/files/en-us/web/api/texttrackcue/enter_event/index.md +++ b/files/en-us/web/api/texttrackcue/enter_event/index.md @@ -14,10 +14,10 @@ The **`enter`** event fires when a cue becomes active. In the case of subtitles Use the event name in methods like {{domxref("EventTarget.addEventListener", "addEventListener()")}}, or set an event handler property. -```js -addEventListener("enter", (event) => {}); +```js-nolint +addEventListener("enter", (event) => { }) -onenter = (event) => {}; +onenter = (event) => { } ``` ## Event type diff --git a/files/en-us/web/api/texttrackcue/exit_event/index.md b/files/en-us/web/api/texttrackcue/exit_event/index.md index 4309e3830f6f386..34ad295eb5249cc 100644 --- a/files/en-us/web/api/texttrackcue/exit_event/index.md +++ b/files/en-us/web/api/texttrackcue/exit_event/index.md @@ -14,10 +14,10 @@ The **`exit`** event fires when a cue stops being active. Use the event name in methods like {{domxref("EventTarget.addEventListener", "addEventListener()")}}, or set an event handler property. -```js -addEventListener("exit", (event) => {}); +```js-nolint +addEventListener("exit", (event) => { }) -onexit = (event) => {}; +onexit = (event) => { } ``` ## Event type diff --git a/files/en-us/web/api/texttrackcue/pauseonexit/index.md b/files/en-us/web/api/texttrackcue/pauseonexit/index.md index 4c00da1f45e5496..b5eaa6329816336 100644 --- a/files/en-us/web/api/texttrackcue/pauseonexit/index.md +++ b/files/en-us/web/api/texttrackcue/pauseonexit/index.md @@ -14,8 +14,6 @@ The **`pauseOnExit`** property of the {{domxref("TextTrackCue")}} interface retu A {{jsxref("Boolean")}}, true if the media will pause. -## Examples - ## Specifications {{Specifications}} diff --git a/files/en-us/web/api/texttracklist/addtrack_event/index.md b/files/en-us/web/api/texttracklist/addtrack_event/index.md index d81c44080aa3812..baa3ff71d9a2e6f 100644 --- a/files/en-us/web/api/texttracklist/addtrack_event/index.md +++ b/files/en-us/web/api/texttracklist/addtrack_event/index.md @@ -14,10 +14,10 @@ The **`addtrack`** event is fired when a track is added to a [`TextTrackList`](/ Use the event name in methods like {{domxref("EventTarget.addEventListener", "addEventListener()")}}, or set an event handler property. -```js -addEventListener("addtrack", (event) => {}); +```js-nolint +addEventListener("addtrack", (event) => { }) -onaddtrack = (event) => {}; +onaddtrack = (event) => { } ``` ## Event type diff --git a/files/en-us/web/api/texttracklist/change_event/index.md b/files/en-us/web/api/texttracklist/change_event/index.md index a98ae44be2b6d2b..fc4a87b037eae30 100644 --- a/files/en-us/web/api/texttracklist/change_event/index.md +++ b/files/en-us/web/api/texttracklist/change_event/index.md @@ -14,10 +14,10 @@ The **`change`** event is fired when a text track is made active or inactive, or Use the event name in methods like {{domxref("EventTarget.addEventListener", "addEventListener()")}}, or set an event handler property. -```js -addEventListener("change", (event) => {}); +```js-nolint +addEventListener("change", (event) => { }) -onchange = (event) => {}; +onchange = (event) => { } ``` ## Event type diff --git a/files/en-us/web/api/texttracklist/gettrackbyid/index.md b/files/en-us/web/api/texttracklist/gettrackbyid/index.md index 693ec9cde6a5c59..35bb48f99154c26 100644 --- a/files/en-us/web/api/texttracklist/gettrackbyid/index.md +++ b/files/en-us/web/api/texttracklist/gettrackbyid/index.md @@ -11,7 +11,7 @@ browser-compat: api.TextTrackList.getTrackById The **{{domxref("TextTrackList")}}** method **`getTrackById()`** returns the first {{domxref("TextTrack")}} object from the track list whose -[`id`](/en-US/docs/Web/HTML/Global_attributes/id) matches the +[`id`](/en-US/docs/Web/HTML/Reference/Global_attributes/id) matches the specified string. This lets you find a specified track if you know its ID string. diff --git a/files/en-us/web/api/texttracklist/removetrack_event/index.md b/files/en-us/web/api/texttracklist/removetrack_event/index.md index f9636fd58a4c03e..c433139a6bb9e31 100644 --- a/files/en-us/web/api/texttracklist/removetrack_event/index.md +++ b/files/en-us/web/api/texttracklist/removetrack_event/index.md @@ -14,10 +14,10 @@ The **`removetrack`** event is fired when a track is removed from a [`TextTrackL Use the event name in methods like {{domxref("EventTarget.addEventListener", "addEventListener()")}}, or set an event handler property. -```js -addEventListener("removetrack", (event) => {}); +```js-nolint +addEventListener("removetrack", (event) => { }) -onremovetrack = (event) => {}; +onremovetrack = (event) => { } ``` ## Event type diff --git a/files/en-us/web/api/timeevent/index.md b/files/en-us/web/api/timeevent/index.md index 92fba01ccf26290..cf5065adab0c9d9 100644 --- a/files/en-us/web/api/timeevent/index.md +++ b/files/en-us/web/api/timeevent/index.md @@ -2,11 +2,12 @@ title: TimeEvent slug: Web/API/TimeEvent page-type: web-api-interface +browser-compat: api.TimeEvent --- {{APIRef("SVG")}} -The **`TimeEvent`** interface, a part of [SVG SMIL](/en-US/docs/Web/SVG/SVG_animation_with_SMIL) animation, provides specific contextual information associated with Time events. +The **`TimeEvent`** interface, a part of [SVG SMIL](/en-US/docs/Web/SVG/Guides/SVG_animation_with_SMIL) animation, provides specific contextual information associated with Time events. {{InheritanceDiagram}} @@ -21,3 +22,11 @@ The **`TimeEvent`** interface, a part of [SVG SMIL](/en-US/docs/Web/SVG/SVG_anim - {{domxref("TimeEvent.initTimeEvent()")}} - : Used to initialize the value of a TimeEvent created through the DocumentEvent interface. This method may only be called before the TimeEvent has been dispatched via the dispatchEvent method, though it may be called multiple times during that phase if necessary. + +## Specifications + +{{Specifications}} + +## Browser compatibility + +{{Compat}} diff --git a/files/en-us/web/api/toggleevent/index.md b/files/en-us/web/api/toggleevent/index.md index 62a009386e6c54e..429fcab3cae3707 100644 --- a/files/en-us/web/api/toggleevent/index.md +++ b/files/en-us/web/api/toggleevent/index.md @@ -37,7 +37,7 @@ _This interface inherits properties from its parent, {{DOMxRef("Event")}}._ ```js const popover = document.getElementById("mypopover"); -// ... +// … popover.addEventListener("beforetoggle", (event) => { if (event.newState === "open") { diff --git a/files/en-us/web/api/toggleevent/newstate/index.md b/files/en-us/web/api/toggleevent/newstate/index.md index b376be05362caee..cfbbdfe85a0fa73 100644 --- a/files/en-us/web/api/toggleevent/newstate/index.md +++ b/files/en-us/web/api/toggleevent/newstate/index.md @@ -19,7 +19,7 @@ A string. Possible values are `"open"` (the popover is being shown) or `"closed" ```js const popover = document.getElementById("mypopover"); -// ... +// … popover.addEventListener("beforetoggle", (event) => { if (event.newState === "open") { diff --git a/files/en-us/web/api/toggleevent/oldstate/index.md b/files/en-us/web/api/toggleevent/oldstate/index.md index 421278f9c4cf5d1..a6c6d162e5cc1f6 100644 --- a/files/en-us/web/api/toggleevent/oldstate/index.md +++ b/files/en-us/web/api/toggleevent/oldstate/index.md @@ -19,7 +19,7 @@ A string. Possible values are `"open"` (the popover is going from showing to hid ```js const popover = document.getElementById("mypopover"); -// ... +// … popover.addEventListener("beforetoggle", (event) => { if (event.oldState === "open") { diff --git a/files/en-us/web/api/toggleevent/toggleevent/index.md b/files/en-us/web/api/toggleevent/toggleevent/index.md index c1c4ebb9f5299a4..198bd02eccaa354 100644 --- a/files/en-us/web/api/toggleevent/toggleevent/index.md +++ b/files/en-us/web/api/toggleevent/toggleevent/index.md @@ -36,7 +36,7 @@ For example: ```js const popover = document.getElementById("mypopover"); -// ... +// … popover.addEventListener("beforetoggle", (event) => { if (event.newState === "open") { diff --git a/files/en-us/web/api/topics_api/index.md b/files/en-us/web/api/topics_api/index.md index f35152bdd259a4f..2d5fd064b7fcea1 100644 --- a/files/en-us/web/api/topics_api/index.md +++ b/files/en-us/web/api/topics_api/index.md @@ -11,7 +11,8 @@ browser-compat: api.Document.browsingTopics {{DefaultAPISidebar("Topics API")}}{{SeeCompatTable}}{{non-standard_header}} > [!WARNING] -> This feature is currently opposed by two browser vendors. See the [Standards positions](#standards_positions) section below for details of opposition. +> This feature is currently opposed by two browser vendors. +> See the [Standards positions](#standards_positions) section below for details. > [!NOTE] > An [Enrollment process](/en-US/docs/Web/Privacy/Guides/Privacy_sandbox/Enrollment) is required to use the Topics API in your applications. See the [Enrollment](#enrollment) section for details of what sub-features are gated by enrollment. @@ -24,7 +25,7 @@ A typical mechanism for advertising on the web involves a user visiting **publis The above process can be made more effective using interest-based advertising (IBA). The idea is that when users visit the publisher sites, they are served a **personalized** selection of ads based on their interests. Their interests are inferred from sites they have previously visited. In the past, third-party tracking cookies have been used to collect information on user interests, but browsers are phasing out the availability of third-party cookies for an increasing proportion of users. The Topics API provides part of the path towards this goal — a mechanism to implement IBA that does not depend on user tracking. -First of all, the browser infers a user's interests from the URLs of sites they visit that have ad tech `<iframe>`s embedded. These interests are mapped to specific **topics of interest**, and the browser calculates and records the users' top topic (i.e. the topic that their interests mapped to most often) at the end of each **epoch**. An epoch is a week by default. The top topic is updated each week so that interests are kept current and users don't start to see ads for topics that they are no longer interested in. +First of all, the browser infers a user's interests from the URLs of sites they visit that have ad tech `<iframe>`s embedded. These interests are mapped to specific **topics of interest**, and the browser calculates and records the users' top topic (i.e., the topic that their interests mapped to most often) at the end of each **epoch**. An epoch is a week by default. The top topic is updated each week so that interests are kept current and users don't start to see ads for topics that they are no longer interested in. > [!NOTE] > This process only happens on sites where a Topics API feature is used (see [What API features enable the Topics API?](/en-US/docs/Web/API/Topics_API/Using#what_api_features_enable_the_topics_api)). @@ -60,7 +61,7 @@ The Topics API has no distinct interfaces of its own. - {{httpheader("Sec-Browsing-Topics")}} - : Sends the selected topics for the current user along with a request, which are used by an ad tech platform to choose a personalized ad to display. - {{httpheader("Observe-Browsing-Topics")}} - - : Used to mark topics of interest inferred from a calling site's URL (i.e. the site where the ad tech `<iframe>` is embedded) as observed in the response to a request generated by a [feature that enables the Topics API](/en-US/docs/Web/API/Topics_API/Using#what_api_features_enable_the_topics_api). The browser will subsequently use those topics to calculate top topics for the current user for future epochs. + - : Used to mark topics of interest inferred from a calling site's URL (i.e., the site where the ad tech `<iframe>` is embedded) as observed in the response to a request generated by a [feature that enables the Topics API](/en-US/docs/Web/API/Topics_API/Using#what_api_features_enable_the_topics_api). The browser will subsequently use those topics to calculate top topics for the current user for future epochs. - {{httpheader("Permissions-Policy")}}; the {{httpheader('Permissions-Policy/browsing-topics','browsing-topics')}} directive - : Controls access to the Topics API. Where a policy specifically disallows the use of the Topics API, any attempts to call the `Document.browsingTopics()` method or send a request with a `Sec-Browsing-Topics` header will fail with a `NotAllowedError` {{domxref("DOMException")}}. @@ -84,7 +85,8 @@ This feature is not part of an official standard, although it is specified in th ### Standards positions -Two browser vendors [oppose](/en-US/docs/Glossary/Web_standards#opposing_standards) this specification. Known positions are as follows: +Two browser vendors [oppose](/en-US/docs/Glossary/Web_standards#opposing_standards) this specification. +Known standards positions are as follows: - Mozilla (Firefox): [Negative](https://mozilla.github.io/standards-positions/#topics) - Apple (Safari): [Negative](https://webkit.org/standards-positions/#position-111) @@ -95,5 +97,5 @@ Two browser vendors [oppose](/en-US/docs/Glossary/Web_standards#opposing_standar ## See also -- [Topics API](https://developers.google.com/privacy-sandbox/private-advertising/topics) on developers.google.com (2023) -- [The Privacy Sandbox](https://developers.google.com/privacy-sandbox) on developers.google.com (2023) +- [Topics API](https://privacysandbox.google.com/private-advertising/topics) on privacysandbox.google.com (2023) +- [The Privacy Sandbox](https://privacysandbox.google.com/) on privacysandbox.google.com (2023) diff --git a/files/en-us/web/api/topics_api/using/index.md b/files/en-us/web/api/topics_api/using/index.md index 38cd93804f96c02..22b356583a54f55 100644 --- a/files/en-us/web/api/topics_api/using/index.md +++ b/files/en-us/web/api/topics_api/using/index.md @@ -28,8 +28,8 @@ If the `<iframe>` content from `ad-tech1.example` implements a [feature that ena 1. Infer **topics of interest** from the site URL. The topics are taken from a [standard taxonomy](/en-US/docs/Web/API/Topics_API#what_topics_are_there); for the above URL examples, they would be "Fitness", "Fibre & textile arts", and "Soccer". 2. **Mark the topics as observed**, which involves recording a **topics history entry** for each one in a private topics history storage. Each topics history entry includes the following information: - - A document id (i.e. an identifier for the current page). - - Topics calculation input data (i.e. the page hostname). + - A document id (i.e., an identifier for the current page). + - Topics calculation input data (i.e., the page hostname). - The time (since the Unix epoch) when the page was first observed. - The domain(s) where the topic was observed (known as **topic caller domains**). @@ -85,7 +85,7 @@ When the request associated with one of the above features is sent: 3. An {{httpheader("Observe-Browsing-Topics")}} header should be set on the response to the request — this has the effect of causing the browser to record the current page visit as observed by the calling ad tech provider, so the associated topic(s) will be recorded in a topics history entry, and subsequently be used in [topic selection](#selecting_topics_of_interest_to_influence_ad_choice). > [!NOTE] - > It is important to clarify that this doesn't record the top topics sent in the `Sec-Browsing-Topics` header as observed. It records the topics inferred from the calling site's URL (i.e. the site where the ad tech `<iframe>` is embedded) as observed. + > It is important to clarify that this doesn't record the top topics sent in the `Sec-Browsing-Topics` header as observed. It records the topics inferred from the calling site's URL (i.e., the site where the ad tech `<iframe>` is embedded) as observed. ### The `browsingTopics()` method @@ -171,4 +171,4 @@ You can also test your Topics API code locally without [enrollment](/en-US/docs/ ## See also -- [Topics API](https://developers.google.com/privacy-sandbox/private-advertising/topics) on developers.google.com (2023) +- [Topics API](https://privacysandbox.google.com/private-advertising/topics) on privacysandbox.google.com (2023) diff --git a/files/en-us/web/api/touch/radiusx/index.md b/files/en-us/web/api/touch/radiusx/index.md index c0bf189ae87beab..bfcfed38141bfb4 100644 --- a/files/en-us/web/api/touch/radiusx/index.md +++ b/files/en-us/web/api/touch/radiusx/index.md @@ -18,7 +18,7 @@ A number. ## Examples -This example illustrates using the {{domxref("Touch")}} interface's `Touch.radiusX`, `Touch.radiusX` and {{domxref("Touch.rotationAngle")}} properties. The `Touch.radiusX` property is the radius of the ellipse which most closely circumscribes the touching area (e.g. finger, stylus) along the axis **indicated** by the touch point's {{domxref("Touch.rotationAngle")}}. Likewise, the {{domxref("Touch.radiusY")}} property is the radius of the ellipse which most closely circumscribes the touching area (e.g. finger, stylus) along the axis **perpendicular** to that indicated by {{domxref("Touch.rotationAngle")}}. The {{domxref("Touch.rotationAngle")}} is the angle (in degrees) that the ellipse described by `radiusX` and `radiusY` is rotated clockwise about its center. +This example illustrates using the {{domxref("Touch")}} interface's `Touch.radiusX`, `Touch.radiusX` and {{domxref("Touch.rotationAngle")}} properties. The `Touch.radiusX` property is the radius of the ellipse which most closely circumscribes the touching area (e.g., finger, stylus) along the axis **indicated** by the touch point's {{domxref("Touch.rotationAngle")}}. Likewise, the {{domxref("Touch.radiusY")}} property is the radius of the ellipse which most closely circumscribes the touching area (e.g., finger, stylus) along the axis **perpendicular** to that indicated by {{domxref("Touch.rotationAngle")}}. The {{domxref("Touch.rotationAngle")}} is the angle (in degrees) that the ellipse described by `radiusX` and `radiusY` is rotated clockwise about its center. The following simple code snippet, registers a single handler for the {{domxref("Element/touchstart_event", "touchstart")}}, {{domxref("Element/touchmove_event", "touchmove")}} and {{domxref("Element/touchend_event", "touchend")}} events. When the `src` element is touched, the element's width and height will be calculate based on the touch point's `radiusX` and `radiusY` values and the element will then be rotated using the touch point's `rotationAngle`. diff --git a/files/en-us/web/api/touch/touch/index.md b/files/en-us/web/api/touch/touch/index.md index 79794a882705671..00ffa2dd37ce254 100644 --- a/files/en-us/web/api/touch/touch/index.md +++ b/files/en-us/web/api/touch/touch/index.md @@ -39,9 +39,9 @@ new Touch(options) - `pageY` {{optional_inline}} - : Defaults to `0`, of type `double`, that is the vertical position of the touch on the client window of the user's screen, including any scroll offset. - `radiusX` {{optional_inline}} - - : Defaults to `0`, of type `float`, that is the radius of the ellipse which most closely circumscribes the touching area (e.g. finger, stylus) along the axis indicated by rotationAngle, in CSS pixels of the same scale as screenX; `0` if no value is known. The value must not be negative. + - : Defaults to `0`, of type `float`, that is the radius of the ellipse which most closely circumscribes the touching area (e.g., finger, stylus) along the axis indicated by rotationAngle, in CSS pixels of the same scale as screenX; `0` if no value is known. The value must not be negative. - `radiusY` {{optional_inline}} - - : Defaults to `0`, of type `float`, that is the radius of the ellipse which most closely circumscribes the touching area (e.g. finger, stylus) along the axis perpendicular to that indicated by rotationAngle, in CSS pixels of the same scale as screenY; `0` if no value is known. The value must not be negative. + - : Defaults to `0`, of type `float`, that is the radius of the ellipse which most closely circumscribes the touching area (e.g., finger, stylus) along the axis perpendicular to that indicated by rotationAngle, in CSS pixels of the same scale as screenY; `0` if no value is known. The value must not be negative. - `rotationAngle` {{optional_inline}} - : Defaults to `0`, of type `float`, that is the angle (in degrees) that the ellipse described by radiusX and radiusY is rotated clockwise about its center; `0` if no value is known. The value must be greater than or equal to `0` and less than `90`. If the ellipse described by radiusX and radiusY is circular, then rotationAngle has no effect. The user agent may use `0` as the value in this case, or it may use any other value in the allowed range. (For example, the user agent may use the rotationAngle value from the previous touch event, to avoid sudden changes.). - `force` {{optional_inline}} diff --git a/files/en-us/web/api/touch_events/index.md b/files/en-us/web/api/touch_events/index.md index 7b80fe19738ce60..0f7c91fa0981057 100644 --- a/files/en-us/web/api/touch_events/index.md +++ b/files/en-us/web/api/touch_events/index.md @@ -95,13 +95,13 @@ function handleStart(evt) { const ctx = el.getContext("2d"); const touches = evt.changedTouches; - for (let i = 0; i < touches.length; i++) { + for (const [i, touch] of touches.entries()) { log(`touchstart: ${i}.`); - ongoingTouches.push(copyTouch(touches[i])); - const color = colorForTouch(touches[i]); - log(`color of touch with id ${touches[i].identifier} = ${color}`); + ongoingTouches.push(copyTouch(touch)); + const color = colorForTouch(touch); + log(`color of touch with id ${touch.identifier} = ${color}`); ctx.beginPath(); - ctx.arc(touches[i].pageX, touches[i].pageY, 4, 0, 2 * Math.PI, false); // a circle at the start + ctx.arc(touch.pageX, touch.pageY, 4, 0, 2 * Math.PI, false); // a circle at the start ctx.fillStyle = color; ctx.fill(); } @@ -123,9 +123,9 @@ function handleMove(evt) { const ctx = el.getContext("2d"); const touches = evt.changedTouches; - for (let i = 0; i < touches.length; i++) { - const color = colorForTouch(touches[i]); - const idx = ongoingTouchIndexById(touches[i].identifier); + for (const touch of touches) { + const color = colorForTouch(touch); + const idx = ongoingTouchIndexById(touch.identifier); if (idx >= 0) { log(`continuing touch ${idx}`); @@ -134,13 +134,13 @@ function handleMove(evt) { `ctx.moveTo( ${ongoingTouches[idx].pageX}, ${ongoingTouches[idx].pageY} );`, ); ctx.moveTo(ongoingTouches[idx].pageX, ongoingTouches[idx].pageY); - log(`ctx.lineTo( ${touches[i].pageX}, ${touches[i].pageY} );`); - ctx.lineTo(touches[i].pageX, touches[i].pageY); + log(`ctx.lineTo( ${touch.pageX}, ${touch.pageY} );`); + ctx.lineTo(touch.pageX, touch.pageY); ctx.lineWidth = 4; ctx.strokeStyle = color; ctx.stroke(); - ongoingTouches.splice(idx, 1, copyTouch(touches[i])); // swap in the new touch record + ongoingTouches.splice(idx, 1, copyTouch(touch)); // swap in the new touch record } else { log("can't figure out which touch to continue"); } @@ -166,17 +166,17 @@ function handleEnd(evt) { const ctx = el.getContext("2d"); const touches = evt.changedTouches; - for (let i = 0; i < touches.length; i++) { - const color = colorForTouch(touches[i]); - let idx = ongoingTouchIndexById(touches[i].identifier); + for (const touch of touches) { + const color = colorForTouch(touch); + let idx = ongoingTouchIndexById(touch.identifier); if (idx >= 0) { ctx.lineWidth = 4; ctx.fillStyle = color; ctx.beginPath(); ctx.moveTo(ongoingTouches[idx].pageX, ongoingTouches[idx].pageY); - ctx.lineTo(touches[i].pageX, touches[i].pageY); - ctx.fillRect(touches[i].pageX - 4, touches[i].pageY - 4, 8, 8); // and a square at the end + ctx.lineTo(touch.pageX, touch.pageY); + ctx.fillRect(touch.pageX - 4, touch.pageY - 4, 8, 8); // and a square at the end ongoingTouches.splice(idx, 1); // remove it; we're done } else { log("can't figure out which touch to end"); @@ -197,7 +197,7 @@ function handleCancel(evt) { log("touchcancel."); const touches = evt.changedTouches; - for (let i = 0; i < touches.length; i++) { + for (const touch of touches) { let idx = ongoingTouchIndexById(touches[i].identifier); ongoingTouches.splice(idx, 1); // remove it; we're done } diff --git a/files/en-us/web/api/touch_events/multi-touch_interaction/index.md b/files/en-us/web/api/touch_events/multi-touch_interaction/index.md index 4a2e37c2c37a1ee..1b76ea0632b3941 100644 --- a/files/en-us/web/api/touch_events/multi-touch_interaction/index.md +++ b/files/en-us/web/api/touch_events/multi-touch_interaction/index.md @@ -131,8 +131,8 @@ function start_handler(ev) { ev.preventDefault(); // Cache the touch points for later processing of 2-touch pinch/zoom if (ev.targetTouches.length === 2) { - for (let i = 0; i < ev.targetTouches.length; i++) { - tpCache.push(ev.targetTouches[i]); + for (const touch of ev.targetTouches) { + tpCache.push(touch); } } if (logEvents) log("touchStart", ev, true); @@ -252,8 +252,8 @@ function log(name, ev, printTargetIds) { if (printTargetIds) { s = ""; - for (let i = 0; i < ev.targetTouches.length; i++) { - s += `... id = ${ev.targetTouches[i].identifier}\n`; + for (const touch of ev.targetTouches) { + s += `... id = ${touch.identifier}\n`; } o.innerText += s; } diff --git a/files/en-us/web/api/touch_events/using_touch_events/index.md b/files/en-us/web/api/touch_events/using_touch_events/index.md index 7ecdb43cd003901..66994ea02f81c7d 100644 --- a/files/en-us/web/api/touch_events/using_touch_events/index.md +++ b/files/en-us/web/api/touch_events/using_touch_events/index.md @@ -89,8 +89,8 @@ someElement.addEventListener( (ev) => { // Iterate through the touch points that were activated // for this element and process each event 'target' - for (let i = 0; i < ev.targetTouches.length; i++) { - process_target(ev.targetTouches[i].target); + for (const touch of ev.targetTouches) { + process_target(touch.target); } }, false, @@ -124,31 +124,20 @@ Some new features regarding a touch point's [touch area](/en-US/docs/Web/API/Tou ## What about Pointer Events? -The introduction of new input mechanisms results in increased application complexity to handle various input events, such as key events, mouse events, pen/stylus events, and touch events. To help address this problem, the [Pointer Events standard](https://www.w3.org/TR/pointerevents/) _defines events and related interfaces for handling hardware agnostic pointer input from devices including a mouse, pen, touchscreen, etc._. That is, the abstract _pointer_ creates a unified input model that can represent a contact point for a finger, pen/stylus or mouse. See the [Pointer Events MDN article](/en-US/docs/Web/API/Pointer_events). +The introduction of new input mechanisms results in increased application complexity to handle various input events, such as key events, mouse events, pen/stylus events, and touch events. To help address this problem, the [Pointer Events](/en-US/docs/Web/API/Pointer_events) API defines events and related interfaces for handling hardware agnostic pointer input from devices including a mouse, pen, touchscreen, etc. That is, the abstract _pointer_ creates a unified input model that can represent a contact point for a finger, pen/stylus or mouse. The pointer event model can simplify an application's input processing since a pointer represents input from any input device. Additionally, the pointer event types are very similar to mouse event types (for example, `pointerdown` and `pointerup`) thus code to handle pointer events closely matches mouse handling code. The implementation status of pointer events in browsers is [relatively high](https://caniuse.com/#search=pointer) with Chrome, Firefox, IE11 and Edge having complete implementations. -## Examples and demos - -The following documents describe how to use touch events and include example code: - -- [Touch events overview](/en-US/docs/Web/API/Touch_events) -- [Implement Custom Gestures](https://web.dev/articles/add-touch-to-your-site) -- [Add touch screen support to your website (The easy way)](https://www.codicode.com/art/easy_way_to_add_touch_support_to_your_website.aspx) - -Touch event demonstrations: - -- [Paint Program (by Rick Byers)](https://rbyers.github.io/paint.html) -- [Touch/pointer tests and demos (by Patrick H. Lauke)](https://patrickhlauke.github.io/touch/) - -## Community +## See also +- [Touch events](/en-US/docs/Web/API/Touch_events) +- [Pointer events](/en-US/docs/Web/API/Pointer_events) +- [Add touch to your site](https://web.dev/articles/add-touch-to-your-site) on web.dev +- [Add touch screen support to your website (The easy way)](https://codicode.com/art/easy_way_to_add_touch_support_to_your_website.aspx) +- [Paint Program](https://rbyers.github.io/paint.html) by Rick Byers +- [Touch/pointer tests and demos](https://patrickhlauke.github.io/touch/) by Patrick H. Lauke - [Touch Events Community Group](https://github.com/w3c/touch-events) - [Mail list](https://lists.w3.org/Archives/Public/public-touchevents/) - [W3C #touchevents IRC channel](irc://irc.w3.org:6667/) - -## Related topics and resources - -- [Pointer Events Standard](https://www.w3.org/TR/pointerevents/) diff --git a/files/en-us/web/api/transitionevent/pseudoelement/index.md b/files/en-us/web/api/transitionevent/pseudoelement/index.md index 847ac86b8a9de7a..1a57474179b98fd 100644 --- a/files/en-us/web/api/transitionevent/pseudoelement/index.md +++ b/files/en-us/web/api/transitionevent/pseudoelement/index.md @@ -11,7 +11,7 @@ browser-compat: api.TransitionEvent.pseudoElement The **`TransitionEvent.pseudoElement`** read-only property is a string, starting with `'::'`, containing the name of the [pseudo-element](/en-US/docs/Web/CSS/Pseudo-elements) the animation runs on. If the transition doesn't run on a pseudo-element but on the element, an empty string: -`''``.` +`""`. ## Value diff --git a/files/en-us/web/api/translator/availability_static/index.md b/files/en-us/web/api/translator/availability_static/index.md new file mode 100644 index 000000000000000..4030ec00512bc25 --- /dev/null +++ b/files/en-us/web/api/translator/availability_static/index.md @@ -0,0 +1,122 @@ +--- +title: "Translator: availability() static method" +short-title: availability() +slug: Web/API/Translator/availability_static +page-type: web-api-static-method +status: + - experimental +browser-compat: api.Translator.availability_static +--- + +{{APIRef("Translator and Language Detector APIs")}}{{securecontext_header}}{{SeeCompatTable}} + +The **`availability()`** static method of the {{domxref("Translator")}} interface returns an enumerated value that indicates the availability of the AI model for the given `Translator` configuration. + +## Syntax + +```js-nolint +Translator.availability(options) +``` + +### Parameters + +- `options` + + - : An object specifying configuration options for the `Translator`. Possible values include: + + - `sourceLanguage` + - : A string specifying the language of the input text to be translated, which should be a valid [BCP 47 language tag](https://en.wikipedia.org/wiki/IETF_language_tag#List_of_common_primary_language_subtags) (as specified in [RFC 5646](https://datatracker.ietf.org/doc/html/rfc5646)). + - `targetLanguage` + - : A string specifying the language that the input text will be translated into, which should be valid BCP 47 language tag. + +### Return value + +A {{jsxref("Promise")}} that fulfills with an enumerated value indicating whether support is available (or will be available) for a given `Translator` configuration, or `null` if support could not be determined. + +Possible values include: + +- `available` + - : The browser supports the given configuration and it can be used immediately. +- `downloadable` + - : The browser supports the given configuration, but it first needs to download an AI model, or some fine-tuning data for the model. +- `downloading` + - : The browser supports the given configuration, but it has to finish an ongoing download before it can proceed. +- `unavailable` + - : The browser does not support the given configuration. This value is also returned if the specified `sourceLanguage` and `targetLanguage` are the same. + +### Exceptions + +- `InvalidStateError` {{domxref("DOMException")}} + - : Thrown if the page's {{domxref("Document")}} is not yet active. +- `OperationError` {{domxref("DOMException")}} + - : Thrown if initialization of the AI model failed for any reason. +- `UnknownError` {{domxref("DOMException")}} + - : Thrown if the `availability()` call failed for any other reason, or a reason the user agent did not wish to disclose. + +If usage of the method is blocked by a {{httpheader('Permissions-Policy/translator','translator')}} {{httpheader("Permissions-Policy")}}, the promise rejects with a value of `unavailable`. + +## Examples + +### Basic `availability()` usage + +In the following snippet, we start by checking the availability of the model for translating between two languages using the `availability()` method: + +- If it returns `unavailable`, we print an appropriate error message to the console. +- If it returns `available`, we create a translator using the {{domxref("Translator.create_static", "create()")}} method, passing it the source and target languages. The required AI model is available, so we can use it immediately. +- If it returns a different value (that is, `downloadable` or `downloading`), we run the same `create()` method call, but this time we include a `monitor` that logs the percentage of the model downloaded each time the {{domxref("CreateMonitor/downloadprogress_event", "downloadprogress")}} event fires. + +```js +async function getTranslator(languages) { + const availability = await Translator.availability(languages); + + if (availability === "unavailable") { + console.log( + `Translation not supported; try a different language combination.`, + ); + return undefined; + } else if (availability === "available") { + return await Translator.create(languages); + } + return await Translator.create({ + ...languages, + monitor(monitor) { + monitor.addEventListener("downloadprogress", (e) => { + console.log(`Downloaded ${Math.floor(e.loaded * 100)}%`); + }); + }, + }); +} + +const translator = await getTranslator({ + sourceLanguage: "en", + targetLanguage: "ja", +}); +``` + +### Detecting language support + +```js +async function langSupport(source, target) { + const availability = await Translator.availability({ + sourceLanguage: source, + targetLanguage: target, + }); + return availability; +} + +await langSupport("en", "fr"); +await langSupport("en", "pt"); +await langSupport("en", "zh"); +``` + +## Specifications + +{{Specifications}} + +## Browser compatibility + +{{Compat}} + +## See also + +- [Using the Translator and Language Detector APIs](/en-US/docs/Web/API/Translator_and_Language_Detector_APIs/Using) diff --git a/files/en-us/web/api/translator/create_static/index.md b/files/en-us/web/api/translator/create_static/index.md new file mode 100644 index 000000000000000..297bc427be93e49 --- /dev/null +++ b/files/en-us/web/api/translator/create_static/index.md @@ -0,0 +1,84 @@ +--- +title: "Translator: create() static method" +short-title: create() +slug: Web/API/Translator/create_static +page-type: web-api-static-method +status: + - experimental +browser-compat: api.Translator.create_static +--- + +{{APIRef("Translator and Language Detector APIs")}}{{securecontext_header}}{{SeeCompatTable}} + +The **`create()`** static method of the {{domxref("Translator")}} interface creates a new `Translator` instance that can be used to translate text. + +> [!NOTE] +> The `create()` method requires [transient activation](/en-US/docs/Glossary/Transient_activation), that is, it must be invoked in response to a user action such as a mouse click or button press. + +## Syntax + +```js-nolint +Translator.create(options) +``` + +### Parameters + +- `options` + + - : An object specifying configuration options for the `Translator`. Possible values include: + + - `sourceLanguage` + - : A string specifying the expected language of the input text to be translated, which should be a valid [BCP 47 language tag](https://en.wikipedia.org/wiki/IETF_language_tag#List_of_common_primary_language_subtags) (as specified in [RFC 5646](https://datatracker.ietf.org/doc/html/rfc5646)). + - `targetLanguage` + - : A string specifying the language that the input text will be translated into, which should be valid BCP 47 language tag. + - `monitor` {{optional_inline}} + - : A callback function with a {{domxref("CreateMonitor")}} argument that enables monitoring download progress of the AI model. + - `signal` {{optional_inline}} + - : An {{domxref("AbortSignal")}} object instance, which allows the `create()` operation to be aborted via the associated {{domxref("AbortController")}}. + +### Return value + +A {{jsxref("Promise")}} that fulfills with a `Translator` object instance. + +### Exceptions + +- `InvalidStateError` {{domxref("DOMException")}} + - : Thrown if the page's {{domxref("Document")}} is not yet active. +- `NetworkError` {{domxref("DOMException")}} + - : Thrown if: + - The network was not available to download the AI model. + - The user has cancelled the AI model download. +- `NotAllowedError` {{domxref("DOMException")}} + - : Thrown if: + - Usage of the method is blocked by a {{httpheader('Permissions-Policy/translator','translator')}} {{httpheader("Permissions-Policy")}}. + - The user has blocked the AI model download in some way. + - The `create()` method wasn't called via {{glossary("transient activation")}}. +- `NotSupportedError` {{domxref("DOMException")}} + - : Thrown if: + - The language tags specified in `sourceLanguage` or `targetLanguage` are invalid, or not supported. This is the case if the specified `sourceLanguage` and `targetLanguage` are the same. + - An AI model to support the specified combination of `sourceLanguage` and `targetLanguage` is not available. +- `OperationError` {{domxref("DOMException")}} + - : General-purpose exception thrown if `Translator` creation failed for any other reason. + +## Examples + +### Basic `Translator` creation + +```js +const translator = await Translator.create({ + sourceLanguage: "en", + targetLanguage: "ja", +}); +``` + +## Specifications + +{{Specifications}} + +## Browser compatibility + +{{Compat}} + +## See also + +- [Using the Translator and Language Detector APIs](/en-US/docs/Web/API/Translator_and_Language_Detector_APIs/Using) diff --git a/files/en-us/web/api/translator/destroy/index.md b/files/en-us/web/api/translator/destroy/index.md new file mode 100644 index 000000000000000..2c2747097ad65ee --- /dev/null +++ b/files/en-us/web/api/translator/destroy/index.md @@ -0,0 +1,54 @@ +--- +title: "Translator: destroy() method" +short-title: destroy() +slug: Web/API/Translator/destroy +page-type: web-api-instance-method +status: + - experimental +browser-compat: api.Translator.destroy +--- + +{{APIRef("Translator and Language Detector APIs")}}{{SeeCompatTable}} + +The **`destroy()`** method of the {{domxref("Translator")}} interface destroys the `Translator` instance it is called on. It makes sense to destroy these objects if they are no longer going to be used, as they tie up significant resources in their handling. + +## Syntax + +```js-nolint +destroy() +``` + +### Parameters + +None. + +### Return value + +None ({{jsxref("undefined")}}). + +## Examples + +### Basic `destroy()` usage + +```js +const translator = await Translator.create({ + sourceLanguage: "en", + targetLanguage: "ja", +}); + +// ... + +translator.destroy(); +``` + +## Specifications + +{{Specifications}} + +## Browser compatibility + +{{Compat}} + +## See also + +- [Using the Translator and Language Detector APIs](/en-US/docs/Web/API/Translator_and_Language_Detector_APIs/Using) diff --git a/files/en-us/web/api/translator/index.md b/files/en-us/web/api/translator/index.md new file mode 100644 index 000000000000000..856277b106d39f2 --- /dev/null +++ b/files/en-us/web/api/translator/index.md @@ -0,0 +1,87 @@ +--- +title: Translator +slug: Web/API/Translator +page-type: web-api-interface +status: + - experimental +browser-compat: api.Translator +--- + +{{APIRef("Translator and Language Detector APIs")}}{{SeeCompatTable}} + +The **`Translator`** interface of the {{domxref("Translator and Language Detector APIs", "Translator and Language Detector APIs", "", "nocode")}} contains all the associated translation functionality, including checking AI model availability, creating a new `Translator` instance, using it to create a translation, and more. + +{{InheritanceDiagram}} + +## Instance properties + +- {{domxref("Translator.inputQuota", "inputQuota")}} {{ReadOnlyInline}} {{Experimental_Inline}} + - : The input quota available to the browser for generating translations. +- {{domxref("Translator.sourceLanguage", "sourceLanguage")}} {{ReadOnlyInline}} {{Experimental_Inline}} + - : The expected language of the input text to be translated. +- {{domxref("Translator.targetLanguage", "targetLanguage")}} {{ReadOnlyInline}} {{Experimental_Inline}} + - : The language that the input text will be translated into. + +## Static methods + +- {{domxref("Translator.availability_static", "availability()")}} {{Experimental_Inline}} + - : Returns an enumerated value that indicates the availability of the AI model for the given `Translator` configuration. +- {{domxref("Translator.create_static", "create()")}} {{Experimental_Inline}} + - : Creates a new `Translator` instance from which to generate translations. + +## Instance methods + +- {{domxref("Translator.destroy", "destroy()")}} {{Experimental_Inline}} + - : Destroys the `Translator` instance it is called on. +- {{domxref("Translator.measureInputUsage", "measureInputUsage()")}} {{Experimental_Inline}} + - : Reports how much input quota would be used by a translation operation for a given text input. +- {{domxref("Translator.translate", "translate()")}} {{Experimental_Inline}} + - : Returns a string containing a translation of the input string. +- {{domxref("Translator.translateStreaming", "translateStreaming()")}} {{Experimental_Inline}} + - : Generates a translation of the input string as a {{domxref("ReadableStream")}}. + +## Examples + +See [Using the Translator and Language Detector APIs](/en-US/docs/Web/API/Translator_and_Language_Detector_APIs/Using) for a complete example. + +### Creating a `Translator` instance + +```js +const translator = await Translator.create({ + sourceLanguage: "en", + targetLanguage: "ja", +}); +``` + +### Generating a translation + +```js +const translation = await translator.translate(myTextString); +console.log(translation); +``` + +### Generating a translation stream + +```js +const stream = translator.translateStreaming(myTextString); +let translation = ""; + +for await (const chunk of stream) { + translation += chunk; +} + +console.log("Stream complete"); +console.log(translation); +``` + +## Specifications + +{{Specifications}} + +## Browser compatibility + +{{Compat}} + +## See also + +- [Using the Translator and Language Detector APIs](/en-US/docs/Web/API/Translator_and_Language_Detector_APIs/Using) diff --git a/files/en-us/web/api/translator/inputquota/index.md b/files/en-us/web/api/translator/inputquota/index.md new file mode 100644 index 000000000000000..324359d0e2928a3 --- /dev/null +++ b/files/en-us/web/api/translator/inputquota/index.md @@ -0,0 +1,59 @@ +--- +title: "Translator: inputQuota property" +short-title: inputQuota +slug: Web/API/Translator/inputQuota +page-type: web-api-instance-property +status: + - experimental +browser-compat: api.Translator.inputQuota +--- + +{{APIRef("Translator and Language Detector APIs")}}{{SeeCompatTable}} + +The **`inputQuota`** read-only property of the {{domxref("Translator")}} interface returns the input quota available to the browser for generating translations. + +## Value + +A number specifying the available input quota. + +This number is implementation-dependant. For example, it might be {{jsxref("Infinity")}} if there are no limits beyond the user's memory and the maximum length of JavaScript strings, or it might be a number of tokens in the case of AI models that use a token/credits scheme. + +The only guarantee is that `inputQuota` - {{domxref("Translator.measureInputUsage", "measureInputUsage()")}} will be non-negative if there is sufficient quota to translate the text. + +## Examples + +### Checking if you have enough quota + +In the below snippet, we create a new `Translator` instance using {{domxref("Translator.create_static", "create()")}}, then return the total input quota via `inputQuota` and the input quota usage for a translating a particular text string via {{domxref("Translator.measureInputUsage", "measureInputUsage()")}}. + +We then test to see if the individual input usage for that string is greater than the total available quota. If so, we throw an appropriate error; it not, we commence translating the string using {{domxref("Translator.translate", "translate()")}}. + +```js +const translator = await Translator.create({ + sourceLanguage: "en", + targetLanguage: "ja", +}); + +const totalInputQuota = translator.inputQuota; +const inputUsage = await translator.measureInputUsage(myTextString); + +if (inputUsage > totalInputQuota) { + throw new Error("Insufficient quota to translate."); +} else { + console.log("Quota available to translate."); + const translation = await translator.translate(myTextString); + // ... +} +``` + +## Specifications + +{{Specifications}} + +## Browser compatibility + +{{Compat}} + +## See also + +- [Using the Translator and Language Detector APIs](/en-US/docs/Web/API/Translator_and_Language_Detector_APIs/Using) diff --git a/files/en-us/web/api/translator/measureinputusage/index.md b/files/en-us/web/api/translator/measureinputusage/index.md new file mode 100644 index 000000000000000..31d1a6a351c28d7 --- /dev/null +++ b/files/en-us/web/api/translator/measureinputusage/index.md @@ -0,0 +1,82 @@ +--- +title: "Translator: measureInputUsage() method" +short-title: measureInputUsage() +slug: Web/API/Translator/measureInputUsage +page-type: web-api-instance-method +status: + - experimental +browser-compat: api.Translator.measureInputUsage +--- + +{{APIRef("Translator and Language Detector APIs")}}{{SeeCompatTable}} + +The **`measureInputUsage()`** method of the {{domxref("Translator")}} interface reports how much input quota would be used by a translation operation for a given text input. + +## Syntax + +```js-nolint +measureInputUsage(input) +measureInputUsage(input, options) +``` + +### Parameters + +- `input` + - : A string representing the input text you want an input usage measurement for. +- `options` {{optional_inline}} + - : An object specifying configuration options for the `measureInputUsage()` operation. Possible values include: + - `signal` + - : An {{domxref("AbortSignal")}} object instance, which allows the `measureInputUsage()` operation to be aborted via the associated {{domxref("AbortController")}}. + +### Return value + +A {{jsxref("Promise")}} that fulfills with a number specifying the {{domxref("Translator.inputQuota", "inputQuota")}} usage of the given input text. + +This number is implementation-dependant; if it is less than the {{domxref("Translator.inputQuota", "inputQuota")}}, the string can be translated. + +### Exceptions + +- `NotAllowedError` {{domxref("DOMException")}} + - : Thrown if usage of the `Translator` API is blocked by a {{httpheader('Permissions-Policy/translator','translator')}} {{httpheader("Permissions-Policy")}}. +- `NotReadableError` {{domxref("DOMException")}} + - : Thrown if the output translation was filtered by the user agent, for example because it was detected to be harmful, inaccurate, or nonsensical. +- `UnknownError` {{domxref("DOMException")}} + - : Thrown if the `measureInputUsage()` call failed for any other reason, or a reason the user agent did not wish to disclose. + +## Examples + +### Checking if you have enough quota + +In the below snippet, we create a new `Translator` instance using {{domxref("Translator.create_static", "create()")}}, then return the total input quota via {{domxref("Translator.inputQuota", "inputQuota")}} and the input quota usage for a translating a particular text string via `measureInputUsage()`. + +We then test to see if the individual input usage for that string is greater than the total available quota. If so, we throw an appropriate error; it not, we commence translating the string using {{domxref("Translator.translate", "translate()")}}. + +```js +const translator = await Translator.create({ + sourceLanguage: "en", + targetLanguage: "ja", +}); + +const totalInputQuota = translator.inputQuota; +const inputUsage = await translator.measureInputUsage(myTextString); + +if (inputUsage > totalInputQuota) { + throw new Error("Insufficient quota to translate."); +} else { + console.log("Quota available to translate."); + const translation = await translator.translate(myTextString); + // ... +} +``` + +## Specifications + +{{Specifications}} + +## Browser compatibility + +{{Compat}} + +## See also + +- [Using the Translator and Language Detector APIs](/en-US/docs/Web/API/Translator_and_Language_Detector_APIs/Using) diff --git a/files/en-us/web/api/translator/sourcelanguage/index.md b/files/en-us/web/api/translator/sourcelanguage/index.md new file mode 100644 index 000000000000000..7031a439632ee56 --- /dev/null +++ b/files/en-us/web/api/translator/sourcelanguage/index.md @@ -0,0 +1,43 @@ +--- +title: "Translator: sourceLanguage property" +short-title: sourceLanguage +slug: Web/API/Translator/sourceLanguage +page-type: web-api-instance-property +status: + - experimental +browser-compat: api.Translator.sourceLanguage +--- + +{{APIRef("Translator and Language Detector APIs")}}{{SeeCompatTable}} + +The **`sourceLanguage`** read-only property of the {{domxref("Translator")}} interface returns the expected language of the input text to be translated. + +A `Translator` instance's `sourceLanguage` is set when creating it via a {{domxref("Translator.create_static", "create()")}} call. + +## Value + +A string specifying the source language. This will be a valid [BCP 47 language tag](https://en.wikipedia.org/wiki/IETF_language_tag#List_of_common_primary_language_subtags) (as specified in [RFC 5646](https://datatracker.ietf.org/doc/html/rfc5646)). + +## Examples + +```js +const translator = await Translator.create({ + sourceLanguage: "en", + targetLanguage: "ja", +}); + +// Logs "en" +console.log(translator.sourceLanguage); +``` + +## Specifications + +{{Specifications}} + +## Browser compatibility + +{{Compat}} + +## See also + +- [Using the Translator and Language Detector APIs](/en-US/docs/Web/API/Translator_and_Language_Detector_APIs/Using) diff --git a/files/en-us/web/api/translator/targetlanguage/index.md b/files/en-us/web/api/translator/targetlanguage/index.md new file mode 100644 index 000000000000000..9b21d30c3134c1b --- /dev/null +++ b/files/en-us/web/api/translator/targetlanguage/index.md @@ -0,0 +1,43 @@ +--- +title: "Translator: targetLanguage property" +short-title: targetLanguage +slug: Web/API/Translator/targetLanguage +page-type: web-api-instance-property +status: + - experimental +browser-compat: api.Translator.targetLanguage +--- + +{{APIRef("Translator and Language Detector APIs")}}{{SeeCompatTable}} + +The **`targetLanguage`** read-only property of the {{domxref("Translator")}} interface returns the language that the input text will be translated into. + +A `Translator` instance's `targetLanguage` is set when creating it via a {{domxref("Translator.create_static", "create()")}} call. + +## Value + +A string specifying the source language. This will be a valid [BCP 47 language tag](https://en.wikipedia.org/wiki/IETF_language_tag#List_of_common_primary_language_subtags) (as specified in [RFC 5646](https://datatracker.ietf.org/doc/html/rfc5646)). + +## Examples + +```js +const translator = await Translator.create({ + sourceLanguage: "en", + targetLanguage: "ja", +}); + +// Logs "ja" +console.log(translator.targetLanguage); +``` + +## Specifications + +{{Specifications}} + +## Browser compatibility + +{{Compat}} + +## See also + +- [Using the Translator and Language Detector APIs](/en-US/docs/Web/API/Translator_and_Language_Detector_APIs/Using) diff --git a/files/en-us/web/api/translator/translate/index.md b/files/en-us/web/api/translator/translate/index.md new file mode 100644 index 000000000000000..83665cbf82eace8 --- /dev/null +++ b/files/en-us/web/api/translator/translate/index.md @@ -0,0 +1,66 @@ +--- +title: "Translator: translate() method" +short-title: translate() +slug: Web/API/Translator/translate +page-type: web-api-instance-method +status: + - experimental +browser-compat: api.Translator.translate +--- + +{{APIRef("Translator and Language Detector APIs")}}{{SeeCompatTable}} + +The **`translate()`** method of the {{domxref("Translator")}} interface returns a translation of an input string. + +## Syntax + +```js-nolint +translate(input) +translate(input, options) +``` + +### Parameters + +- `input` + - : A string representing the text to be translated. +- `options` {{optional_inline}} + - : An object specifying configuration options for the `translate()` operation. Possible values include: + - `signal` + - : An {{domxref("AbortSignal")}} object instance, which allows the `translate()` operation to be aborted via the associated {{domxref("AbortController")}}. + +### Return value + +A {{jsxref("Promise")}} that fulfills with a string containing the generated translation. + +### Exceptions + +- `InvalidStateError` {{domxref("DOMException")}} + - : Thrown if the current {{domxref("Document")}} is not active. +- `QuotaExceededError` {{domxref("DOMException")}} + - : Thrown if the translation operation exceeds the available {{domxref("Translator.inputQuota", "inputQuota")}}. + +## Examples + +### Basic `translate()` usage + +```js +const translator = await Translator.create({ + sourceLanguage: "en", + targetLanguage: "ja", +}); + +const translation = await translator.translate(myTextString); +console.log(translation); +``` + +## Specifications + +{{Specifications}} + +## Browser compatibility + +{{Compat}} + +## See also + +- [Using the Translator and Language Detector APIs](/en-US/docs/Web/API/Translator_and_Language_Detector_APIs/Using) diff --git a/files/en-us/web/api/translator/translatestreaming/index.md b/files/en-us/web/api/translator/translatestreaming/index.md new file mode 100644 index 000000000000000..84b69c3f8d61a18 --- /dev/null +++ b/files/en-us/web/api/translator/translatestreaming/index.md @@ -0,0 +1,73 @@ +--- +title: "Translator: translateStreaming() method" +short-title: translateStreaming() +slug: Web/API/Translator/translateStreaming +page-type: web-api-instance-method +status: + - experimental +browser-compat: api.Translator.translateStreaming +--- + +{{APIRef("Translator and Language Detector APIs")}}{{SeeCompatTable}} + +The **`translateStreaming()`** method of the {{domxref("Translator")}} interface generates a translation as a {{domxref("ReadableStream")}}. + +## Syntax + +```js-nolint +translateStreaming(input) +translateStreaming(input, options) +``` + +### Parameters + +- `input` + - : A string representing the text to be translated. +- `options` {{optional_inline}} + - : An object specifying configuration options for the `translateStreaming()` operation. Possible values include: + - `signal` + - : An {{domxref("AbortSignal")}} object instance, which allows the `translateStreaming()` operation to be aborted via the associated {{domxref("AbortController")}}. + +### Return value + +A {{domxref("ReadableStream")}} containing the generated translation. + +### Exceptions + +- `InvalidStateError` {{domxref("DOMException")}} + - : Thrown if the current {{domxref("Document")}} is not active. +- `QuotaExceededError` {{domxref("DOMException")}} + - : Thrown if the translation operation exceeds the available {{domxref("Translator.inputQuota", "inputQuota")}}. + +## Examples + +### Basic `translate()` usage + +```js +const translator = await Translator.create({ + sourceLanguage: "en", + targetLanguage: "ja", +}); + +const stream = translator.translateStreaming(myTextString); +let translation = ""; + +for await (const chunk of stream) { + console.log(chunk); + translation += chunk; +} + +console.log("Complete translation:", translation); +``` + +## Specifications + +{{Specifications}} + +## Browser compatibility + +{{Compat}} + +## See also + +- [Using the Translator and Language Detector APIs](/en-US/docs/Web/API/Translator_and_Language_Detector_APIs/Using) diff --git a/files/en-us/web/api/translator_and_language_detector_apis/index.md b/files/en-us/web/api/translator_and_language_detector_apis/index.md new file mode 100644 index 000000000000000..8ce3d0c0f475261 --- /dev/null +++ b/files/en-us/web/api/translator_and_language_detector_apis/index.md @@ -0,0 +1,71 @@ +--- +title: Translator and Language Detector APIs +slug: Web/API/Translator_and_Language_Detector_APIs +page-type: web-api-overview +status: + - experimental +browser-compat: api.Translator +spec-urls: https://webmachinelearning.github.io/translation-api +--- + +{{SeeCompatTable}}{{DefaultAPISidebar("Translator and Language Detector APIs")}} + +The **Translator and Language Detector APIs** provide functionality to detect the language that text is written in, and to translate text into different languages, via a browser's own internal AI model (which may differ between browsers). + +## Concepts and usage + +Translating a body of text is a common task on today's web. Typical use cases include: + +- On-the-fly translation of an article that isn't available in your language. +- Translating a user's support requests into a language the support agent understands. +- Facilitating chats between users that don't speak each other's languages. + +Detecting the language of a body of test is an important precursor for successful automated translation, but has other uses beyond direct translation. For example, it allows automatic UI configuration based on user text entry, ranging from updating UI and error strings, to automatically loading appropriate dictionaries for spell checking or curse word detection. + +AI is well-suited to facilitating language detection and translation. The Translator and Language Detector APIs provide asynchronous ({{jsxref("Promise")}}-based) mechanisms for a website to detect languages and translate text via the browser's own internal AI model. This is useful and efficient because the browser handles the service, rather than the developer having to rely on the user downloading AI models, or host or pay for a cloud-based translation service. + +- Language detection is done via the {{domxref("LanguageDetector")}} interface. A `LanguageDetector` object instance is created using the {{domxref("LanguageDetector.create_static", "LanguageDetector.create()")}} static method, then the {{domxref("LanguageDetector.detect", "detect()")}} instance method is passed the text string to detect the language for. +- Translation is done via the {{domxref("Translator")}} interface. A `Translator` object instance is created using the {{domxref("Translator.create_static", "Translator.create()")}} static method, then the {{domxref("Translator.translate", "translate()")}} instance method is passed the text string to translate. + +You can also cancel pending operations using an {{domxref("AbortController")}}. + +The `Translator` and `LanguageDetector` instances consume a lot of resources, so once you're finished with them, you are encouraged to remove them using a `destroy()` instance method (for example, {{domxref("Translator.destroy()")}}). + +See [Using the Translator and Language Detector APIs](/en-US/docs/Web/API/Translator_and_Language_Detector_APIs/Using) for a walkthrough of how to use the APIs. + +## Interfaces + +- {{domxref("LanguageDetector")}} {{Experimental_Inline}} + - : Contains all the language detection functionality, including checking AI model availability, creating a new `LanguageDetector` instance, using it to detect a language, and more. +- {{domxref("Translator")}} {{Experimental_Inline}} + - : Contains all the translation functionality, including checking AI model availability, creating a new `Translator` instance, using it to create a translation, and more. + +## HTTP headers + +- {{httpheader("Permissions-Policy")}}; the {{httpheader("Permissions-Policy/language-detector", "language-detector")}} directive + - : Controls access to the language detection functionality. Where a policy specifically disallows its use, any attempts to call the `LanguageDetector` methods will fail with a `NotAllowedError` {{domxref("DOMException")}}. +- {{httpheader("Permissions-Policy")}}; the {{httpheader("Permissions-Policy/translator", "translator")}} directive + - : Controls access to the translation functionality. Where a policy specifically disallows its use, any attempts to call the `Translator` methods will fail with a `NotAllowedError` {{domxref("DOMException")}}. + +## Security considerations + +Creation of `LanguageDetector` and `Translator` objects requires that the user has recently interacted with the page ([transient user activation](/en-US/docs/Web/Security/User_activation) is required). + +Access to the API is also controlled via {{httpheader("Permissions-Policy/language-detector", "language-detector")}} and {{httpheader("Permissions-Policy/translator", "translator")}} {{httpheader("Permissions-Policy")}} directives. + +## Examples + +For a full example, see [Using the Translator and Language Detector APIs](/en-US/docs/Web/API/Translator_and_Language_Detector_APIs/Using). + +## Specifications + +{{Specifications}} + +## Browser compatibility + +{{Compat}} + +## See also + +- [Language detection with built-in AI](https://developer.chrome.com/docs/ai/language-detection) on developer.chrome.com (2025) +- [Translation with built-in AI](https://developer.chrome.com/docs/ai/translator-api) on developer.chrome.com (2025) diff --git a/files/en-us/web/api/translator_and_language_detector_apis/using/index.md b/files/en-us/web/api/translator_and_language_detector_apis/using/index.md new file mode 100644 index 000000000000000..cc3606078ca1c0d --- /dev/null +++ b/files/en-us/web/api/translator_and_language_detector_apis/using/index.md @@ -0,0 +1,514 @@ +--- +title: Using the Translator and Language Detector APIs +slug: Web/API/Translator_and_Language_Detector_APIs/Using +page-type: guide +--- + +{{DefaultAPISidebar("Translator and Language Detector APIs")}} + +The [Translator and Language Detector APIs](/en-US/docs/Web/API/Translator_and_Language_Detector_APIs) provide asynchronous ({{jsxref("Promise")}}-based) mechanisms for a website to detect languages and translate text via the browser's own internal AI model. This is useful and efficient because the browser handles the service, rather than the developer having to rely on the user downloading AI models, or host or pay for a cloud-based translation service. +This article explains how to use these APIs. + +## Detecting a language + +All of the language detection functionality is accessed through the {{domxref("LanguageDetector")}} interface. + +The first step in getting the AI model to detect a language is to create a `LanguageDetector` object instance. This is done using the {{domxref("LanguageDetector.create_static", "LanguageDetector.create()")}} static method, which takes an options object as an argument: + +```js +const detector = await LanguageDetector.create({ + expectedInputLanguages: ["en-US", "zh"], +}); +``` + +The {{domxref("LanguageDetector.expectedInputLanguages", "expectedInputLanguages")}} property specifies the languages you are expecting to feed into the detector, to help improve the accuracy of the language detection. + +> [!NOTE] +> Different implementations will likely support different languages. + +When you've created a `LanguageDetector` instance, you can use it to detect a language by calling the {{domxref("LanguageDetector.detect()")}} instance method on it, passing it the text to check as an argument. + +```js +const results = await detector.detect(myTextString); +``` + +This method returns an array of objects representing the detected potential language matches. +Each one contains: + +- A string containing the [BCP 47 language tag](https://en.wikipedia.org/wiki/IETF_language_tag#List_of_common_primary_language_subtags) representing the detected language. +- A number between 0 and 1 representing a confidence score for that match. + +So for example: + +```js +results.forEach((result) => { + console.log(`${result.detectedLanguage}: ${result.confidence}`); +}); + +// Results in logs like this: +// la: 0.8359838724136353 +// es: 0.017705978825688362 +// sv: 0.012977192178368568 +// en: 0.011148443445563316 +// und: 0.0003214875760022551 +``` + +> [!NOTE] +> The last array element always represents a confidence score for the `und` language — this is an abbreviation of "undetermined", and represents the probability that the text is not written in a language the model knows. + +## Creating a translation + +Translation follows a very similar pattern to language detection. A {{domxref("Translator")}} object instance is created using the {{domxref("Translator.create_static", "Translator.create()")}} static method, which takes an options object that must contain at least a {{domxref("Translator.sourceLanguage", "sourceLanguage")}} and {{domxref("Translator.targetLanguage", "targetLanguage")}}: + +```js +const translator = await Translator.create({ + sourceLanguage: "en", + targetLanguage: "ja", +}); +``` + +The translation is then created by calling the {{domxref("Translator.translate()")}} instance method, which is passed the text string to translate as an argument: + +```js +const translation = await translator.translate(myTextString); +``` + +This returns a string containing the translation. + +There is also a streaming version of the `translate()` method available — {{domxref("Translator.translateStreaming()")}} — that allows you to return the translation as a {{domxref("ReadableStream")}}. This can be useful when translating very large bodies of text: + +```js +const stream = translator.translateStreaming(myTextString); +let translation = ""; + +for await (const chunk of stream) { + translation += chunk; +} + +console.log("Stream complete"); +console.log(translation); +``` + +## Checking configuration support + +Before creating a `LanguageDetector` or `Translator` object, you can check whether your desired language configuration is supported by the current browser using the {{domxref("LanguageDetector.availability_static", "LanguageDetector.availability()")}} and {{domxref("Translator.availability_static", "Translator.availability()")}} static methods. For example: + +```js +const detectorAvailability = await LanguageDetector.availability({ + expectedInputLanguages: ["en-US", "ja"], +}); + +const translatorAvailability = await Translator.availability({ + sourceLanguage: "en", + targetLanguage: "ja", +}); +``` + +These methods return an enumerated value indicating whether support is, or will be available for the specified set of options: + +- `downloadable` means that the implementation supports the requested options, but needs to download a model or some fine-tuning data. +- `downloading` means that the implementation supports the requested options, but needs to finish an ongoing download. +- `available` means that the implementation supports the requested options without requiring any new downloads. +- `unavailable` means that the implementation doesn't support the requested options. + +If a download is required, it will be started automatically by the browser once a `LanguageDetector` or `Translator` instance is created using the relevant `create()` method. You can track download progress automatically using a [monitor](#monitoring_download_progress). + +## Cancelling operations and destroying instances + +You can cancel a pending detection or translation operation using an {{domxref("AbortController")}}, with the associated {{domxref("AbortSignal")}} being included inside the method options object as a `signal` property value. For example, aborting a `Translator.create()` operation would look like this: + +```js +const controller = new AbortController(); + +const translator = await Translator.create({ + sourceLanguage: detectedLanguage, + targetLanguage: formData.get("translateLanguage"), + signal: controller.signal, +}); + +// ... + +controller.abort(); +``` + +Once a `Translator` or `LanguageDetector` instance has been created, you can destroy it when it is finished with using the {{domxref("Translator.destroy()")}}/{{domxref("LanguageDetector.destroy()")}} methods: + +```js +translator.destroy(); +detector.destroy(); +``` + +It makes sense to destroy these objects if they are no longer going to be used, as they tie up significant resources in their handling. + +## Monitoring download progress + +If the AI model for a particular detection or translation is downloading (`availability()` returns `downloadable` and `downloading`), it is helpful to provide the user with feedback to tell them how long they need to wait before the operation completes. + +The `Translator` and `LanguageDetector` `create()` methods can accept a `monitor` property, the value of which is a callback function that takes a {{domxref("CreateMonitor")}} instance as an argument. `CreateMonitor` has a {{domxref("CreateMonitor/downloadprogress_event", "downloadprogress")}} event available, which fires when progress is made on downloading the AI model. + +You can use this event to expose loading progress data: + +```js +translator = await Translator.create({ + sourceLanguage: "en", + targetLanguage: "ja", + monitor(monitor) { + monitor.addEventListener("downloadprogress", (e) => { + console.log(`Downloaded ${Math.floor(e.loaded * 100)}%`); + }); + }, +}); +``` + +If the specified languages are not supported, a download will not be initiated, and a `NotSupportedError` {{domxref("DOMException")}} will be thrown. + +## Usage quotas + +Some implementations have an input quota that governs how many operations a website can request in a given period. The total quota can be accessed via the {{domxref("Translator.inputQuota")}}/{{domxref("LanguageDetector.inputQuota")}} properties, while the quota usage for a particular translation or language detection can be returned using the {{domxref("Translator.measureInputUsage()")}}/{{domxref("LanguageDetector.measureInputUsage()")}} methods: + +For example, the below snippet returns the total input quota via `Translator.inputQuota` and the input quota usage for a translating a particular text string via `Translator.measureInputUsage()`. + +We then test to see if the individual input usage for that string is greater than the total available quota. If so, we throw an appropriate error; it not, we commence translating the string using {{domxref("Translator.translate", "translate()")}}. + +```js +const translator = await Translator.create({ + sourceLanguage: "en", + targetLanguage: "ja", +}); + +const totalInputQuota = translator.inputQuota; +const inputUsage = await translator.measureInputUsage(myTextString); + +if (inputUsage > totalInputQuota) { + throw new Error("Insufficient quota to translate."); +} else { + console.log("Quota available to translate."); + const translation = await translator.translate(myTextString); + // ... +} +``` + +If you try to run a language detection or translation operation that exceeds the available quota, a `QuotaExceededError` {{domxref("DOMException")}} will be thrown. + +## Complete example + +Let's look at a complete example that demonstrates the Translator and Language Detector APIs in action. + +### HTML + +In our markup, we first define an input {{htmlelement("form")}} that allows the user to set the text to translate, and language to translate into. This includes a {{htmlelement("textarea")}} for entering the text itself, an {{htmlelement("output")}} element to display the detected language, and a {{htmlelement("select")}} element for choosing a translation language. + +```html live-sample___translator-example +<h2>Input</h2> + +<form> + <div> + <label for="translate-text">Enter text to translate:</label> + <textarea id="translate-text" name="translateText" rows="6"></textarea> + <output class="detected-language">Detected language: </output> + </div> + <div> + <label for="translate-language">Choose translation language:</label> + <select id="translate-language" name="translateLanguage"> + <option value="en" selected>English (en)</option> + <option value="fr">French (fr)</option> + <option value="de">German (de)</option> + <option value="it">Italian (it)</option> + <option value="zh">Mandarin Chinese (zh)</option> + <option value="zh-Hant">Taiwanese Mandarin (zh-Hant)</option> + <option value="ja">Japanese (ja)</option> + <option value="pt">Portuguese (pt)</option> + <option value="ru">Russian (ru)</option> + <option value="es">Spanish (es)</option> + <option value="tr">Turkish (tr)</option> + <option value="hi">Hindi (hi)</option> + <option value="vi">Vietnamese (vi)</option> + <option value="bn">Bengali (bn)</option> + </select> + </div> + <button type="submit">Translate</button> +</form> +``` + +The second half of our markup includes a {{htmlelement("p")}} element to display the generated translation. + +```html live-sample___translator-example +<h2>Translation output</h2> + +<p class="translate-output"></p> +``` + +```css hidden live-sample___translator-example +* { + box-sizing: border-box; +} + +html { + font-family: Arial, Helvetica, sans-serif; +} + +body { + max-width: 600px; + margin: 0 auto; +} + +form div { + display: flex; + flex-direction: column; + gap: 10px; + margin-bottom: 20px; +} + +select, +textarea, +.translate-output { + padding: 5px; +} + +.translate-output { + min-height: 150px; + border: 1px solid black; + width: 100%; + display: block; +} + +.error { + color: red; +} +``` + +Note that we won't show the CSS for this example, as none of it is relevant to understanding the Translator and Language Detector APIs. + +### JavaScript + +In our script, we start off by grabbing references to the `<form>`, `<textarea>`, submit `<button>`, translation output `<p>`, and language detection `<output>` elements. We also declare a variable called `detectedLanguage` to contain results of language detection operations. + +```js +const form = document.querySelector("form"); +const textarea = document.querySelector("textarea"); +const submitBtn = document.querySelector("button"); + +const translateOutput = document.querySelector(".translate-output"); +const detectedLanguageOutput = document.querySelector(".detected-language"); +let detectedLanguage = ""; +``` + +Next, we use the {{domxref("EventTarget.addEventListener()")}} method to listen to two events: + +- `submit` events on the `<form>` element; when the form is submitted, the `handleTranslation()` function is called. +- `input` events on the `<textarea>` element; when the current `<textarea>` value is changed, the `detectLanguage()` function is called. + +```js +form.addEventListener("submit", handleTranslation); +textarea.addEventListener("input", detectLanguage); +``` + +The `detectLanguage()` function, defined next, first checks whether the `<textarea>` element's value is greater than 20 characters. If so, we carry on with the language detection. If not, we disable the submit button and display a message in the `<output>` element's {{domxref("Node.textContent", "textContent")}} saying that the text is too short to detect the language. We do this because language detection generally doesn't work well on single words and very short phrases. If you commonly work with short text, test carefully with your priority languages and return the result as unknown when the confidence is too low. + +When detecting the language of the entered text, we create a `LanguageDetector` instance using the {{domxref("LanguageDetector.create_static", "create()")}} method, which includes a `monitor` to log download progress if the model takes a while to download. We then detect the language using the {{domxref("LanguageDetector.detect", "detect()")}} method, passing it the `<textarea>` value. When the results are returned, we write the language and confidence of the top result into the `<output>` element. In more complex apps, you might want to report multiple results and possibly let the user choose what language it is, but this will do for the demo. + +Finally, we set the submit button to not be disabled, so the form can be submitted to start the translation. + +```js +async function detectLanguage() { + if (textarea.value.length > 20) { + const detector = await LanguageDetector.create({ + monitor(monitor) { + monitor.addEventListener("downloadprogress", (e) => { + console.log(`Downloaded ${e.loaded * 100}%`); + }); + }, + }); + + const results = await detector.detect(textarea.value); + detectedLanguageOutput.textContent = `Detected language: ${ + results[0].detectedLanguage + }. Confidence: ${results[0].confidence.toFixed(4)}`; + detectedLanguage = results[0].detectedLanguage; + + submitBtn.disabled = false; + } else { + detectedLanguageOutput.textContent = `Text too short to accurately detect language.`; + detectedLanguage = ""; + + submitBtn.disabled = true; + } +} +``` + +Now we define the `handleTranslation()` function. After preventing the form's default submission, we create a new {{domxref("FormData")}} object instance containing our `<form>` data name/value pairs. We then run a data validation test, checking whether the detected `<textarea>` content language is the same as the language chosen to translate into (`translateLanguage`). If it is, we print an error message inside the `<p>` with class `translate-output`. + +```js +async function handleTranslation(e) { + e.preventDefault(); + + const formData = new FormData(form); + + if (formData.get("translateLanguage") === detectedLanguage) { + translateOutput.innerHTML = `<span class="error">Input language and translation language are the same.</span>`; + return; + } else { + translateOutput.innerHTML = ""; + } +``` + +If the test passes, we open a [`try { ... }`](/en-US/docs/Web/JavaScript/Reference/Statements/try...catch) block. We start by checking the availability of the model for translating between the detected input and chosen output languages using the {{domxref("Translator.availability_static", "availability()")}} method: + +- If it returns `unavailable`, we print an appropriate error message inside the `<p>` with class `translate-output`. +- If it returns `available`, we create a translator using the {{domxref("Translator.create_static", "create()")}} method, passing it the detected input and chosen output languages. The required AI model is available, so we can use it immediately. +- If it returns a different value (that is, `downloadable` or `downloading`), we run the same `create()` method call, but this time we include a `monitor` that prints out the percentage of the model downloaded to the `translate-output` `<p>` each time the {{domxref("CreateMonitor/downloadprogress_event", "downloadprogress")}} event fires. + +```js + try { + const availability = await Translator.availability({ + sourceLanguage: detectedLanguage, + targetLanguage: formData.get("translateLanguage"), + }); + let translator; + + if (availability === "unavailable") { + translateOutput.innerHTML = `<span class="error">Translation not available; try a different language combination.</span>`; + return; + } else if (availability === "available") { + translator = await Translator.create({ + sourceLanguage: detectedLanguage, + targetLanguage: formData.get("translateLanguage"), + }); + } else { + translator = await Translator.create({ + sourceLanguage: detectedLanguage, + targetLanguage: formData.get("translateLanguage"), + monitor(monitor) { + monitor.addEventListener("downloadprogress", (e) => { + translateOutput.textContent = `Downloaded ${Math.floor( + e.loaded * 100 + )}%`; + }); + }, + }); + } +``` + +Next, we set the output `<p>` content to a pending message and disable the submit button before calling {{domxref("Translator.translate()")}} to perform the actual translation, passing it the `<textarea>` value. Once the translation is done, we display it inside the output `<p>` before making the submit button not disabled again. + +```js +translateOutput.textContent = "...generating translation..."; +submitBtn.disabled = true; + +const translation = await translator.translate(formData.get("translateText")); + +translateOutput.textContent = translation; +submitBtn.disabled = false; +``` + +Finally, we include the `try` block's counterpart `catch() { ... }` block. If the `try` content throws any kind of exception, we display it inside the output `<p>`. + +```js + } catch (e) { + translateOutput.innerHTML = `<span class="error">${e}</span>`; + } +} +``` + +```js hidden live-sample___translator-example +const form = document.querySelector("form"); +const textarea = document.querySelector("textarea"); +const submitBtn = document.querySelector("button"); + +const translateOutput = document.querySelector(".translate-output"); +const detectedLanguageOutput = document.querySelector(".detected-language"); +let detectedLanguage = ""; + +form.addEventListener("submit", handleTranslation); +textarea.addEventListener("input", detectLanguage); + +async function detectLanguage() { + if (textarea.value.length > 20) { + const detector = await LanguageDetector.create({ + monitor(monitor) { + monitor.addEventListener("downloadprogress", (e) => { + console.log(`Downloaded ${e.loaded * 100}%`); + }); + }, + }); + + const results = await detector.detect(textarea.value); + detectedLanguageOutput.textContent = `Detected language: ${ + results[0].detectedLanguage + }. Confidence: ${results[0].confidence.toFixed(4)}`; + detectedLanguage = results[0].detectedLanguage; + + submitBtn.disabled = false; + } else { + detectedLanguageOutput.textContent = `Text too short to accurately detect language.`; + detectedLanguage = ""; + + submitBtn.disabled = true; + } +} + +async function handleTranslation(e) { + e.preventDefault(); + + const formData = new FormData(form); + + if (formData.get("translateLanguage") === detectedLanguage) { + translateOutput.innerHTML = `<span class="error">Input language and translation language are the same.</span>`; + return; + } + translateOutput.innerHTML = ""; + + try { + const availability = await Translator.availability({ + sourceLanguage: detectedLanguage, + targetLanguage: formData.get("translateLanguage"), + }); + let translator; + + if (availability === "unavailable") { + translateOutput.innerHTML = `<span class="error">Translation not available; try a different language combination.</span>`; + return; + } + if (availability === "available") { + translator = await Translator.create({ + sourceLanguage: detectedLanguage, + targetLanguage: formData.get("translateLanguage"), + }); + } else { + translator = await Translator.create({ + sourceLanguage: detectedLanguage, + targetLanguage: formData.get("translateLanguage"), + monitor(monitor) { + monitor.addEventListener("downloadprogress", (e) => { + translateOutput.textContent = `Downloaded ${Math.floor( + e.loaded * 100, + )}%`; + }); + }, + }); + } + + translateOutput.textContent = "...generating translation..."; + submitBtn.disabled = true; + + const translation = await translator.translate( + formData.get("translateText"), + ); + + translateOutput.textContent = translation; + submitBtn.disabled = false; + } catch (e) { + translateOutput.innerHTML = `<span class="error">${e}</span>`; + } +} +``` + +### Result + +The rendered example looks like this: + +{{EmbedLiveSample("translator-example", , "750px", , , , "translator; language-detector", "allow-forms")}} + +Try typing a body of text into the `<textarea>`, and note how the detected language and confidence are only reported when the number of characters becomes greater than 20. Choose a translation language different to your input text, then press the submit button to generate an AI-generated translation. + +Some of the translation language choices may not be available in your browser, even if it does support the APIs. diff --git a/files/en-us/web/api/treewalker/index.md b/files/en-us/web/api/treewalker/index.md index 70f7c85def87838..c14010356ace23f 100644 --- a/files/en-us/web/api/treewalker/index.md +++ b/files/en-us/web/api/treewalker/index.md @@ -58,7 +58,9 @@ _This interface doesn't inherit any method._ ```html <!doctype html> <html lang="en"> - <head><title>Demo</title> + <head> + <title>Demo</title> + </head> <body> <div id="container"></div> </body> diff --git a/files/en-us/web/api/trusted_types_api/index.md b/files/en-us/web/api/trusted_types_api/index.md index b81cb4594d74338..3e1d59146291f9b 100644 --- a/files/en-us/web/api/trusted_types_api/index.md +++ b/files/en-us/web/api/trusted_types_api/index.md @@ -8,30 +8,185 @@ spec-urls: https://w3c.github.io/trusted-types/dist/spec/ {{DefaultAPISidebar("Trusted Types API")}}{{AvailableInWorkers}} -The **Trusted Types API** gives web developers a way to lock down the insecure parts of the {{domxref("Document Object Model","DOM API", "", "nocode")}} to prevent client-side {{Glossary("Cross-site scripting")}} (XSS) attacks. +The **Trusted Types API** gives web developers a way to ensure that input has been passed through a user-specified transformation function before being passed to an API that might execute that input. This can help to protect against client-side [cross-site scripting (XSS)](/en-US/docs/Web/Security/Attacks/XSS) attacks. Most commonly the transformation function [sanitizes](/en-US/docs/Web/Security/Attacks/XSS#sanitization) the input. -## Concepts and Usage +## Concepts and usage -Client-side, or DOM-based, XSS attacks happen when data controlled by a user (such as that input into a form field) reaches a function that can execute that data. These functions are known as _injection sinks_. DOM-based XSS attacks happen when a user is able to write arbitrary JavaScript code and have it executed by one of these functions. +Client-side, or DOM-based, XSS attacks happen when data crafted by an attacker is passed to a browser API that executes that data as code. These APIs are known as _injection sinks_. -The Trusted Types API locks down risky injection sinks, requiring you to process the data before passing it to one of these functions. If you use a string, then the browser will throw a {{jsxref("TypeError")}} and prevent the use of the function. +The Trusted Types API distinguishes three sorts of injection sinks: -Trusted Types works alongside [Content-Security Policy](/en-US/docs/Web/HTTP/CSP) with the {{CSP("trusted-types")}} and {{CSP("require-trusted-types-for")}} directives. +- **HTML sinks**: APIs that interpret their input as HTML, such as {{domxref("Element.innerHTML")}} or {{domxref("Document.write()", "document.write()")}}. These APIs could execute JavaScript if it is embedded in the HTML, for example in {{htmlelement("script")}} tags or event handler attributes. +- **JavaScript sinks**: APIs that interpret their input as JavaScript, such as {{jsxref("Global_Objects/eval", "eval()")}} or {{domxref("HTMLScriptElement.text")}}. +- **JavaScript URL sinks**: APIs that interpret their input as the URL of a script, such as {{domxref("HTMLScriptElement.src")}}. -### Injection Sinks +One of the main defenses against DOM-based XSS attacks is to ensure that input is made safe before being passed to an injection sink. -The Trusted Types API locks down injection sinks that can act as a vector for DOM-XSS attacks. An injection sink is any Web API function that should only be called with trusted, validated or sanitized input. Examples of injection sinks include: +In the Trusted Types API, a developer defines a _policy object_, which contains methods that transform input bound for an injection sink so as to make it safe. The policy can define different methods for the different types of sink: -- Functions that insert HTML into the document such as {{domxref("Element.innerHTML")}}, {{domxref("Element.outerHTML")}}, or {{domxref("Document.write()")}}. -- Functions that create a new same-origin {{domxref("Document")}} with caller-controlled markup such as {{domxref("DOMParser.parseFromString()")}}. -- Functions that execute code such as {{jsxref("Global_Objects/eval", "eval()")}}. -- Setters for {{domxref("Element")}} attributes that accept a URL of code to load or execute. +- For HTML sinks, the transformation function typically [sanitizes](/en-US/docs/Web/Security/Attacks/XSS#sanitization) the input, for example by using a library like [DOMPurify](https://github.com/cure53/DOMPurify). +- For JavaScript and JavaScript URL sinks, the policy may turn off the sinks entirely or allow certain predefined inputs (for example, specific URLs). -Trusted Types will force you to process the data before passing it to any injection sink rather than use a string. This ensures that the data is trustworthy. +The Trusted Types API will then ensure that input is passed through the appropriate transformation function before being passed into the sink. -### Trusted Type Policies +That is, the API enables you to define your policy in one place and then be assured that any data passed to an injection sink has been passed through the policy. -A policy is a factory for Trusted Types. Web developers can specify a set of policies used for the creation of typed objects which form the trusted codebase for valid Trusted Type objects. +> [!NOTE] +> +> The Trusted Types API does _not_ itself supply a policy or any transformation functions: the developer defines their own policy, which contains the transformations that they wish to apply. + +The API has two main parts: + +- A JavaScript API enables a developer to sanitize data before passing it to an injection sink. +- Two [CSP](/en-US/docs/Web/HTTP/Guides/CSP) directives enforce and control the usage of the JavaScript API. + +### The Trusted Types JavaScript API + +In the Trusted Types API: + +- The `trustedTypes` global property, available in both {{domxref("Window.trustedTypes", "Window")}} and {{domxref("WorkerGlobalScope.trustedTypes", "Worker")}} contexts, is used to create {{domxref("TrustedTypePolicy")}} objects. +- A {{domxref("TrustedTypePolicy")}} object is used to create trusted type objects: it will do this by passing the data through a transformation function. +- Trusted type objects represent data that has been through the policy, and can therefore be safely passed to an injection sink. There are three sorts of trusted type, corresponding to the different sort of injection sink: + - {{domxref("TrustedHTML")}} is for passing to a sink that will render the data as HTML. + - {{domxref("TrustedScript")}} is for passing to a sink that will execute the data as JavaScript. + - {{domxref("TrustedScriptURL")}} is for passing to a sink that will parse the data as a URL to a script. + +With this API, instead of passing a string to an injection sink like `innerHTML`, you use a `TrustedTypePolicy` to create a `TrustedHTML` object from the string, then pass that into the sink, and can be sure that the string has been passed through a transformation function. + +For example, this code creates a `TrustedTypePolicy` that can create `TrustedHTML` objects by sanitizing the input strings with the [DOMPurify](https://github.com/cure53/DOMPurify) library: + +```js +const policy = trustedTypes.createPolicy("my-policy", { + createHTML: (input) => DOMPurify.sanitize(input), +}); +``` + +Next, you can use this `policy` object to create a `TrustedHTML` object, and pass that object into the injection sink: + +```js +const userInput = "<p>I might be XSS</p>"; +const element = document.querySelector("#container"); + +const trustedHTML = policy.createHTML(userInput); +element.innerHTML = trustedHTML; +``` + +### Using a CSP to enforce trusted types + +The API described above enables you to sanitize data, but it doesn't ensure that your code never passes input directly to an injection sink: that is, it doesn't stop you passing a string into `innerHTML`. + +In order to enforce that a trusted type must always be passed, you include the {{CSP("require-trusted-types-for")}} directive in your [CSP](/en-US/docs/Web/HTTP/Guides/CSP). +With this directive set, passing strings into injection sinks will result in a `TypeError` exception: + +```js example-bad +const userInput = "<p>I might be XSS</p>"; +const element = document.querySelector("#container"); + +element.innerHTML = userInput; // Throws a TypeError +``` + +Additionally, the {{CSP("trusted-types")}} CSP directive can be used to control which policies your code is allowed to create. When you create a policy using {{domxref("TrustedTypePolicyFactory/createPolicy", "trustedTypes.createPolicy()")}}, you pass a name for the policy. The `trusted-types` CSP directive lists acceptable policy names, so `createPolicy()` will throw an exception if it is passed a name which was not listed in `trusted-types`. This prevents some code in your web application from creating a policy that you were not expecting. + +### The default policy + +In the Trusted Types API, you can define a _default policy_. This helps you find any places in your code where you're still passing strings into injection sinks, so you can rewrite the code to create and pass trusted types instead. + +If you create a policy named `"default"`, and your CSP enforces the use of trusted types, then any string argument passed into injection sinks will be automatically passed to this policy. For example, suppose we create a policy like this: + +```js +trustedTypes.createPolicy("default", { + createHTML(value) { + console.log("Please refactor this code"); + return sanitize(value); + }, +}); +``` + +With this policy, if your code assigns a string to `innerHTML`, the browser will call the policy's `createHTML()` method and assign its result to the sink: + +```js +const userInput = "<p>I might be XSS</p>"; +const element = document.querySelector("#container"); + +element.innerHTML = userInput; +// Logs "Please refactor this code" +// Assigns the result of sanitize(userInput) +``` + +If the default policy returned `null` or `undefined`, then the browser will throw a `TypeError` when assigning the result to the sink: + +```js +trustedTypes.createPolicy("default", { + createHTML(value) { + console.log("Please refactor this code"); + return null; + }, +}); + +const userInput = "<p>I might be XSS</p>"; +const element = document.querySelector("#container"); + +element.innerHTML = userInput; +// Logs "Please refactor this code" +// Throws a TypeError +``` + +> [!NOTE] +> It's recommended that you use the default policy only while you are transitioning from legacy code that passes input directly to injection sinks, to code that uses trusted types explicitly. + +### Cross-browser support for trusted types + +The Trusted Types API is not yet available in all modern browsers, but it is usable everywhere today thanks to [compatibility aids created by the W3C](https://github.com/w3c/trusted-types/tree/main?tab=readme-ov-file#polyfill). + +- The [_full_ polyfill](https://github.com/w3c/trusted-types/blob/main/src/polyfill/full.js) defines the JavaScript API, attempts to infer the CSP from the current document, and enforces the use of trusted types based on the inferred CSP. +- The [_API only_ polyfill](https://github.com/w3c/trusted-types/blob/main/src/polyfill/api_only.js) defines only the JavaScript API, and does not include the ability to enforce the use of trusted types using a CSP. + +As well as these two polyfills, the W3C provides what it calls a _tinyfill_, which we'll explain in more detail below. + +Note that as long as you have tested your code on a supporting browser with CSP enforcement enabled, then you don't need to use the _full polyfill_ above on other browsers — you can get the same benefits using the _API only polyfill_ or the _tinyfill_. + +This is because the enforcement forces you to refactor your code to ensure that all data is passed through the Trusted Types API (and therefore has been through a sanitization function) before being passed to an injection sink. +If you then run the refactored code in a different browser without enforcement, it will still go through the same code paths, and give you the same protection. + +#### Trusted Types tinyfill + +In this section we'll look at how the trusted types tinyfill can protect a website, even though it doesn't add support for trusted types at all. + +The trusted types tinyfill is just this: + +```js +if (typeof trustedTypes === "undefined") + trustedTypes = { createPolicy: (n, rules) => rules }; +``` + +It provides an implementation of `trustedTypes.createPolicy()` which just returns the [`policyOptions`](/en-US/docs/Web/API/TrustedTypePolicyFactory/createPolicy#policyoptions) object it was passed. The `policyOptions` object defines sanitization functions for data, and these functions are expected to return strings. + +With this tinyfill in place, suppose we create a policy: + +```js +const policy = trustedTypes.createPolicy("my-policy", { + createHTML: (input) => DOMPurify.sanitize(input), +}); +``` + +In browsers that support trusted types, this will return a `TrustedTypePolicy` which will create a `TrustedHTML` object when we call `policy.createHTML()`. The `TrustedHTML` object can then be passed to an injection sink, and we can enforce that the sink received a trusted type, rather than a string. + +In browsers that don't support trusted types, this code will return an object with a `createHTML()` function that sanitizes its input and returns it as a string. The sanitized string can then be passed to an injection sink. + +```js +const userInput = "I might be XSS"; +const element = document.querySelector("#container"); + +const trustedHTML = policy.createHTML(userInput); +// In supporting browsers, trustedHTML is a TrustedHTML object. +// In non-supporting browsers, trustedHTML is a string. + +element.innerHTML = trustedHTML; +// In supporting browsers, this will throw if trustedHTML +// is not a TrustedHTML object. +``` + +Either way, the injection sink gets sanitized data, and because we could enforce the use of the policy in the supporting browser, we know that this code path goes through the sanitization function in the non-supporting browser, too. ## Interfaces diff --git a/files/en-us/web/api/trustedhtml/index.md b/files/en-us/web/api/trustedhtml/index.md index cd6cf14f6aa32ce..57915c3ba12f0e3 100644 --- a/files/en-us/web/api/trustedhtml/index.md +++ b/files/en-us/web/api/trustedhtml/index.md @@ -7,7 +7,7 @@ browser-compat: api.TrustedHTML {{APIRef("Trusted Types API")}}{{AvailableInWorkers}} -The **`TrustedHTML`** interface of the {{domxref("Trusted Types API", "", "", "nocode")}} represents a string that a developer can insert into an [injection sink](/en-US/docs/Web/API/Trusted_Types_API#injection_sinks) that will render it as HTML. These objects are created via {{domxref("TrustedTypePolicy.createHTML()")}} and therefore have no constructor. +The **`TrustedHTML`** interface of the {{domxref("Trusted Types API", "", "", "nocode")}} represents a string that a developer can insert into an [injection sink](/en-US/docs/Web/API/Trusted_Types_API#concepts_and_usage) that will render it as HTML. These objects are created via {{domxref("TrustedTypePolicy.createHTML()")}} and therefore have no constructor. The value of a `TrustedHTML` object is set when the object is created and cannot be changed by JavaScript as there is no setter exposed. diff --git a/files/en-us/web/api/trustedscript/index.md b/files/en-us/web/api/trustedscript/index.md index aa347c85fcc5506..019a1b6199bb96c 100644 --- a/files/en-us/web/api/trustedscript/index.md +++ b/files/en-us/web/api/trustedscript/index.md @@ -7,7 +7,7 @@ browser-compat: api.TrustedScript {{APIRef("Trusted Types API")}}{{AvailableInWorkers}} -The **`TrustedScript`** interface of the {{domxref("Trusted Types API", "", "", "nocode")}} represents a string with an uncompiled script body that a developer can insert into an [injection sink](/en-US/docs/Web/API/Trusted_Types_API#injection_sinks) that might execute the script. These objects are created via {{domxref("TrustedTypePolicy.createScript","TrustedTypePolicy.createScript()")}} and therefore have no constructor. +The **`TrustedScript`** interface of the {{domxref("Trusted Types API", "", "", "nocode")}} represents a string with an uncompiled script body that a developer can insert into an [injection sink](/en-US/docs/Web/API/Trusted_Types_API#concepts_and_usage) that might execute the script. These objects are created via {{domxref("TrustedTypePolicy.createScript","TrustedTypePolicy.createScript()")}} and therefore have no constructor. The value of a **TrustedScript** object is set when the object is created and cannot be changed by JavaScript as there is no setter exposed. diff --git a/files/en-us/web/api/trustedscript/tostring/index.md b/files/en-us/web/api/trustedscript/tostring/index.md index 1da6cd48b420679..6362aceb73f451f 100644 --- a/files/en-us/web/api/trustedscript/tostring/index.md +++ b/files/en-us/web/api/trustedscript/tostring/index.md @@ -8,7 +8,7 @@ browser-compat: api.TrustedScript.toString {{APIRef("Trusted Types API")}}{{AvailableInWorkers}} -The **`toString()`** method of the {{domxref("TrustedScript")}} interface returns a string which may safely inserted into an [injection sink](/en-US/docs/Web/API/Trusted_Types_API#injection_sinks). +The **`toString()`** method of the {{domxref("TrustedScript")}} interface returns a string which may be safely inserted into an [injection sink](/en-US/docs/Web/API/Trusted_Types_API#concepts_and_usage). ## Syntax diff --git a/files/en-us/web/api/trustedscripturl/index.md b/files/en-us/web/api/trustedscripturl/index.md index d22ec4629e05c97..6d321edda8c7f16 100644 --- a/files/en-us/web/api/trustedscripturl/index.md +++ b/files/en-us/web/api/trustedscripturl/index.md @@ -7,7 +7,7 @@ browser-compat: api.TrustedScriptURL {{APIRef("Trusted Types API")}}{{AvailableInWorkers}} -The **`TrustedScriptURL`** interface of the {{domxref("Trusted Types API", "", "", "nocode")}} represents a string that a developer can insert into an [injection sink](/en-US/docs/Web/API/Trusted_Types_API#injection_sinks) that will parse it as a URL of an external script. These objects are created via {{domxref("TrustedTypePolicy.createScriptURL","TrustedTypePolicy.createScriptURL()")}} and therefore have no constructor. +The **`TrustedScriptURL`** interface of the {{domxref("Trusted Types API", "", "", "nocode")}} represents a string that a developer can insert into an [injection sink](/en-US/docs/Web/API/Trusted_Types_API#concepts_and_usage) that will parse it as a URL of an external script. These objects are created via {{domxref("TrustedTypePolicy.createScriptURL","TrustedTypePolicy.createScriptURL()")}} and therefore have no constructor. The value of a `TrustedScriptURL` object is set when the object is created and cannot be changed by JavaScript as there is no setter exposed. diff --git a/files/en-us/web/api/trustedscripturl/tostring/index.md b/files/en-us/web/api/trustedscripturl/tostring/index.md index c8ba90514d9cf9d..c6b2ecd1b02c49a 100644 --- a/files/en-us/web/api/trustedscripturl/tostring/index.md +++ b/files/en-us/web/api/trustedscripturl/tostring/index.md @@ -8,7 +8,7 @@ browser-compat: api.TrustedScriptURL.toString {{APIRef("Trusted Types API")}}{{AvailableInWorkers}} -The **`toString()`** method of the {{domxref("TrustedScriptURL")}} interface returns a string which may safely inserted into an [injection sink](/en-US/docs/Web/API/Trusted_Types_API#injection_sinks). +The **`toString()`** method of the {{domxref("TrustedScriptURL")}} interface returns a string which may safely inserted into an [injection sink](/en-US/docs/Web/API/Trusted_Types_API#concepts_and_usage). ## Syntax diff --git a/files/en-us/web/api/trustedtypepolicyfactory/createpolicy/index.md b/files/en-us/web/api/trustedtypepolicyfactory/createpolicy/index.md index dbd72ec80cb4272..3285a2693cfabaf 100644 --- a/files/en-us/web/api/trustedtypepolicyfactory/createpolicy/index.md +++ b/files/en-us/web/api/trustedtypepolicyfactory/createpolicy/index.md @@ -10,16 +10,6 @@ browser-compat: api.TrustedTypePolicyFactory.createPolicy The **`createPolicy()`** method of the {{domxref("TrustedTypePolicyFactory")}} interface creates a {{domxref("TrustedTypePolicy")}} object that implements the rules passed as `policyOptions`. -### The default policy - -In Chrome a policy with a name of "default" creates a special policy that will be used if a string (rather than a Trusted Type object) is passed to an injection sink. This can be used in a transitional phase while moving from an application that inserted strings into injection sinks. - -> [!NOTE] -> The above behavior is not yet settled in the specification and may change in future. - -> [!WARNING] -> A lax default policy could defeat the purpose of using Trusted Types, and therefore should be defined with strict rules to ensure it cannot be used to run dangerous code. - ## Syntax ```js-nolint @@ -48,12 +38,14 @@ A {{domxref("TrustedTypePolicy")}} object. ### Exceptions - {{jsxref("TypeError")}} - - : Thrown if policy names are restricted by the [Content Security Policy `trusted-types` directive](/en-US/docs/Web/HTTP/Headers/Content-Security-Policy/trusted-types) and this name is not on the allowlist. + - : Thrown if policy names are restricted by the [Content Security Policy `trusted-types` directive](/en-US/docs/Web/HTTP/Reference/Headers/Content-Security-Policy/trusted-types) and this name is not on the allowlist. - {{jsxref("TypeError")}} - - : Thrown if the name is a duplicate and the [Content Security Policy trusted-types directive](/en-US/docs/Web/HTTP/Headers/Content-Security-Policy/trusted-types) is not using `allow-duplicates`. + - : Thrown if the name is a duplicate and the [Content Security Policy trusted-types directive](/en-US/docs/Web/HTTP/Reference/Headers/Content-Security-Policy/trusted-types) is not using `allow-duplicates`. ## Examples +### Creating a policy for HTML sinks + The below code creates a policy with the name `"myEscapePolicy"` with a function defined for `createHTML()` which sanitizes HTML. ```js @@ -64,13 +56,13 @@ const escapeHTMLPolicy = trustedTypes.createPolicy("myEscapePolicy", { ### Creating a default policy -On a site where Trusted Types are enforced via a Content Security Policy with the [`require-trusted-types-for`](/en-US/docs/Web/HTTP/Headers/Content-Security-Policy/require-trusted-types-for) directive set to `script`, any injection script that accepts a script expects a Trusted Type object. In the case that a string is inserted instead, the following default policy will be used. +On a site where Trusted Types are enforced via a Content Security Policy with the [`require-trusted-types-for`](/en-US/docs/Web/HTTP/Reference/Headers/Content-Security-Policy/require-trusted-types-for) directive set to `script`, any injection script that accepts a script expects a Trusted Type object. In the case that a string is inserted instead, a [default policy](/en-US/docs/Web/API/Trusted_Types_API#the_default_policy) will be used. -The policy logs a message to the console to remind the developer to refactor this part of the application to use a Trusted Type object. It also appends details of the use of the default policy, type, and injection sink to the returned value. +The default policy logs a message to the console to remind the developer to refactor this part of the application to use a Trusted Type object. It also appends details of the use of the default policy, type, and injection sink to the returned value. ```js trustedTypes.createPolicy("default", { - createScriptURL: (s, type, sink) => { + createScriptURL(s, type, sink) { console.log("Please refactor."); return `${s}?default-policy-used&type=${encodeURIComponent( type, diff --git a/files/en-us/web/api/trustedtypepolicyfactory/defaultpolicy/index.md b/files/en-us/web/api/trustedtypepolicyfactory/defaultpolicy/index.md index 85a4c1d09da9dcc..5d2a08217d7b8fa 100644 --- a/files/en-us/web/api/trustedtypepolicyfactory/defaultpolicy/index.md +++ b/files/en-us/web/api/trustedtypepolicyfactory/defaultpolicy/index.md @@ -10,8 +10,7 @@ browser-compat: api.TrustedTypePolicyFactory.defaultPolicy The **`defaultPolicy`** read-only property of the {{domxref("TrustedTypePolicyFactory")}} interface returns the default {{domxref("TrustedTypePolicy")}} or null if this is empty. -> [!NOTE] -> Information about the creation and use of default policies can be found in the [`createPolicy()`](/en-US/docs/Web/API/TrustedTypePolicyFactory/createPolicy#the_default_policy) documentation. +See [The default policy](/en-US/docs/Web/API/Trusted_Types_API#the_default_policy) for more details. ## Value diff --git a/files/en-us/web/api/ui_events/index.md b/files/en-us/web/api/ui_events/index.md index 3d1f932eb20a998..1f07445e6878203 100644 --- a/files/en-us/web/api/ui_events/index.md +++ b/files/en-us/web/api/ui_events/index.md @@ -11,7 +11,7 @@ spec-urls: https://w3c.github.io/uievents/ The UI Events API defines a system for handling user interactions such as mouse and keyboard input. This includes: -- events that are fired on specific user actions such keypresses or mouse clicks. Most of these events fire on the {{domxref("Element")}} interface, but the events relating to loading and unloading resources fire on the {{domxref("Window")}} interface. +- events that are fired on specific user actions such key presses or mouse clicks. Most of these events fire on the {{domxref("Element")}} interface, but the events relating to loading and unloading resources fire on the {{domxref("Window")}} interface. - event interfaces, which are passed into handlers for these events. These interfaces inherit from {{domxref("Event")}} and provide extra information specific to the type of user interaction: for example, the {{domxref("KeyboardEvent")}} is passed into a {{domxref("Element.keydown_event", "keydown")}} event handler and provides information about the key that was pressed. ## Interfaces diff --git a/files/en-us/web/api/ui_events/keyboard_event_key_values/index.md b/files/en-us/web/api/ui_events/keyboard_event_key_values/index.md index 48857e9bebbca86..fbca3e6c1e4263d 100644 --- a/files/en-us/web/api/ui_events/keyboard_event_key_values/index.md +++ b/files/en-us/web/api/ui_events/keyboard_event_key_values/index.md @@ -1089,7 +1089,7 @@ _Modifiers_ are special keys which are used to generate special characters or ca ## IME and composition keys -Keys used when using an {{glossary("Input Method Editor")}} (IME) to input text which can't readily be entered by simple keypresses, such as text in languages such as those which have more graphemes than there are character entry keys on the keyboard. Common examples include Chinese, Japanese, Korean, and Hindi. +Keys used when using an {{glossary("Input Method Editor")}} (IME) to input text which can't readily be entered by simple key presses, such as text in languages such as those which have more graphemes than there are character entry keys on the keyboard. Common examples include Chinese, Japanese, Korean, and Hindi. Some keys are common across multiple languages, while others exist only on keyboards targeting specific languages. In addition, not all keyboards have all of these keys. @@ -1225,7 +1225,7 @@ Some keys are common across multiple languages, while others exist only on keybo <a href="https://en.wikipedia.org/wiki/ISO/IEC_9995" >ISO/IEC 9995 keyboard</a >. Each key may have multiple groups of characters, each in its own - column. Pressing this key instructs the device to interpret keypresses + column. Pressing this key instructs the device to interpret key presses as coming from the first column on subsequent keystrokes. </td> <td></td> @@ -3057,7 +3057,7 @@ The values below are derived in part from a number of consumer electronics techn - [DTV Application Software Environment](https://www.atsc.org/atsc-documents/a100-dtv-application-software-environment-level-1-dase-1/) (part of the [ATSC](https://en.wikipedia.org/wiki/ATSC) specification) - [Open Cable Application Platform](https://en.wikipedia.org/wiki/OpenCable_Application_Platform) -- [ANSI/CEA-2014-B](https://shop.cta.tech/products/web-based-protocol-and-framework-for-remote-user-interface-on-upnp-networks-and-the-internet): Web-based Protocol and Framework for Remote User Interface on UPnP™ Networks and the Internet +- [ANSI/CEA-2014-B](https://shop.cta.tech/products/cta-2014): Web-based Protocol and Framework for Remote User Interface on UPnP™ Networks and the Internet - [Android KeyEvent key code values](https://developer.android.com/reference/android/view/KeyEvent.html) > [!NOTE] diff --git a/files/en-us/web/api/url/index.md b/files/en-us/web/api/url/index.md index 5d490b409bbcff8..c99f603ed2ffee0 100644 --- a/files/en-us/web/api/url/index.md +++ b/files/en-us/web/api/url/index.md @@ -81,7 +81,7 @@ if (URL.canParse("../cats", "http://www.example.com/dogs")) { console.log(url.hostname); // "www.example.com" console.log(url.pathname); // "/cats" } else { - console.log("Invalid URL"); //Invalid URL + console.log("Invalid URL"); } ``` diff --git a/files/en-us/web/api/url/protocol/index.md b/files/en-us/web/api/url/protocol/index.md index b46d2a3dc9e95d2..f275bba391ba5ef 100644 --- a/files/en-us/web/api/url/protocol/index.md +++ b/files/en-us/web/api/url/protocol/index.md @@ -8,7 +8,7 @@ browser-compat: api.URL.protocol {{ApiRef("URL API")}} {{AvailableInWorkers}} -The **`protocol`** property of the {{domxref("URL")}} interface is a string containing the protocol or scheme of the URL, including the final `":"`. If the port is the default for the protocol (`80` for `ws:` and `http:`, `443` for `wss:` and `https:`, and `21` for `ftp:`), this property contains an empty string, `""`. +The **`protocol`** property of the {{domxref("URL")}} interface is a string containing the protocol or scheme of the URL, including the final `":"`. This property can be set to change the protocol of the URL. A `":"` is appended to the provided string if not provided. The provided scheme has to be compatible with the rest of the URL to be considered valid. diff --git a/files/en-us/web/api/url/searchparams/index.md b/files/en-us/web/api/url/searchparams/index.md index 2ca4fbe66927ab1..b61a8ffcfa86467 100644 --- a/files/en-us/web/api/url/searchparams/index.md +++ b/files/en-us/web/api/url/searchparams/index.md @@ -24,7 +24,7 @@ A {{domxref("URLSearchParams")}} object. const params = new URL("https://example.com/?name=Jonathan%20Smith&age=18") .searchParams; const name = params.get("name"); -const age = parseInt(params.get("age")); +const age = parseInt(params.get("age"), 10); console.log(`name: ${name}`); // name: Jonathan Smith console.log(`age: ${age}`); // age: 18 diff --git a/files/en-us/web/api/url_api/index.md b/files/en-us/web/api/url_api/index.md index 0aafa3b6ffe6db5..14a97942a1cabe9 100644 --- a/files/en-us/web/api/url_api/index.md +++ b/files/en-us/web/api/url_api/index.md @@ -93,7 +93,7 @@ function fillTableWithParameters(tbl) { } ``` -A working version of this example can be [found on Glitch](https://url-api.glitch.me/). Just add parameters to the URL when loading the page to see them in the table. For instance, try [`https://url-api.glitch.me?from=mdn&excitement=high&likelihood=inconceivable`](https://url-api.glitch.me?from=mdn&excitement=high&likelihood=inconceivable). +A working version of this example can be [found on Glitch](https://url-api.glitch.me/). Just add parameters to the URL when loading the page to see them in the table. For instance, try [`https://url-api.glitch.me/?from=mdn&excitement=high&likelihood=inconceivable`](https://url-api.glitch.me/?from=mdn&excitement=high&likelihood=inconceivable). ## Specifications diff --git a/files/en-us/web/api/urlsearchparams/getall/index.md b/files/en-us/web/api/urlsearchparams/getall/index.md index 8ebcad12beee13d..92d17a13fa86faa 100644 --- a/files/en-us/web/api/urlsearchparams/getall/index.md +++ b/files/en-us/web/api/urlsearchparams/getall/index.md @@ -29,13 +29,13 @@ An array of strings, which may be empty if no values for the given parameter are ## Examples ```js -let url = new URL("https://example.com?foo=1&bar=2"); -let params = new URLSearchParams(url.search); +const url = new URL("https://example.com?foo=1&bar=2"); +const params = new URLSearchParams(url.search); -//Add a second foo parameter. +// Add a second foo parameter. params.append("foo", 4); -console.log(params.getAll("foo")); //Prints ["1","4"]. +console.log(params.getAll("foo")); // ["1", "4"] ``` ## Specifications diff --git a/files/en-us/web/api/urlsearchparams/sort/index.md b/files/en-us/web/api/urlsearchparams/sort/index.md index c10b727072645b9..5b2f01bf1a90a00 100644 --- a/files/en-us/web/api/urlsearchparams/sort/index.md +++ b/files/en-us/web/api/urlsearchparams/sort/index.md @@ -11,7 +11,7 @@ browser-compat: api.URLSearchParams.sort The **`URLSearchParams.sort()`** method sorts all key/value pairs contained in this object in place and returns `undefined`. The sort order is according to unicode code points of the keys. This method uses a stable sorting -algorithm (i.e. the relative order between key/value pairs with equal keys will be +algorithm (i.e., the relative order between key/value pairs with equal keys will be preserved). ## Syntax diff --git a/files/en-us/web/api/urlsearchparams/urlsearchparams/index.md b/files/en-us/web/api/urlsearchparams/urlsearchparams/index.md index 00582f64581aab7..7a281b5cda445d8 100644 --- a/files/en-us/web/api/urlsearchparams/urlsearchparams/index.md +++ b/files/en-us/web/api/urlsearchparams/urlsearchparams/index.md @@ -70,13 +70,13 @@ console.log(url.origin); const add_params = { c: "a", - d: new String(2), - e: false.toString(), + d: 2, + e: false, }; const new_params = new URLSearchParams([ ...Array.from(url.searchParams.entries()), // [["a","hello"],["b","world"]] - ...Object.entries(add_params), // [["c","a"],["d","2"],["e","false"]] + ...Object.entries(add_params), // [["c","a"],["d",2],["e",false]] ]).toString(); console.log(new_params); // a=hello&b=world&c=a&d=2&e=false diff --git a/files/en-us/web/api/usb/connect_event/index.md b/files/en-us/web/api/usb/connect_event/index.md index 53382b640e2ffef..a6fc73079cbcbc0 100644 --- a/files/en-us/web/api/usb/connect_event/index.md +++ b/files/en-us/web/api/usb/connect_event/index.md @@ -16,10 +16,10 @@ The **`connect`** event of the {{DOMxRef("USB")}} interface is fired whenever a Use the event name in methods like {{domxref("EventTarget.addEventListener", "addEventListener()")}}, or set an event handler property. -```js -addEventListener("connect", (event) => {}); +```js-nolint +addEventListener("connect", (event) => { }) -onconnect = (event) => {}; +onconnect = (event) => { } ``` ## Event type diff --git a/files/en-us/web/api/usb/disconnect_event/index.md b/files/en-us/web/api/usb/disconnect_event/index.md index 0cd6c6de3fac2c6..8eb28b7256f6a46 100644 --- a/files/en-us/web/api/usb/disconnect_event/index.md +++ b/files/en-us/web/api/usb/disconnect_event/index.md @@ -16,10 +16,10 @@ The **`disconnect`** event of the {{DOMxRef("USB")}} interface is fired whenever Use the event name in methods like {{domxref("EventTarget.addEventListener", "addEventListener()")}}, or set an event handler property. -```js -addEventListener("disconnect", (event) => {}); +```js-nolint +addEventListener("disconnect", (event) => { }) -ondisconnect = (event) => {}; +ondisconnect = (event) => { } ``` ## Event type diff --git a/files/en-us/web/api/user-agent_client_hints_api/index.md b/files/en-us/web/api/user-agent_client_hints_api/index.md index 7acb797e9a652a9..a69ee6e7d0b67b8 100644 --- a/files/en-us/web/api/user-agent_client_hints_api/index.md +++ b/files/en-us/web/api/user-agent_client_hints_api/index.md @@ -13,7 +13,7 @@ spec-urls: https://wicg.github.io/ua-client-hints/ {{DefaultAPISidebar("User-Agent Client Hints API")}}{{SeeCompatTable}} -The **User-Agent Client Hints API** extends [Client Hints](/en-US/docs/Web/HTTP/Client_hints) to provide a way of exposing browser and platform information via User-Agent response and request headers, and a JavaScript API. +The **User-Agent Client Hints API** extends [Client Hints](/en-US/docs/Web/HTTP/Guides/Client_hints) to provide a way of exposing browser and platform information via User-Agent response and request headers, and a JavaScript API. ## Concepts and Usage diff --git a/files/en-us/web/api/validitystate/badinput/index.md b/files/en-us/web/api/validitystate/badinput/index.md index 41b94d43d34362a..e2a548f8ab47b1a 100644 --- a/files/en-us/web/api/validitystate/badinput/index.md +++ b/files/en-us/web/api/validitystate/badinput/index.md @@ -18,9 +18,9 @@ A boolean that is `true` if the `ValidityState` object does not conform to the e ### Detecting bad input -The following example checks the validity of a [numeric input element](/en-US/docs/Web/HTML/Element/input/number). +The following example checks the validity of a [numeric input element](/en-US/docs/Web/HTML/Reference/Elements/input/number). If the user enters text instead of a number, the element fails constraint validation, and the styles matching [`input:invalid`](/en-US/docs/Web/CSS/:invalid) are applied. -The [`<pre>`](/en-US/docs/Web/HTML/Element/pre) element above the input shows the validation message when the element `badInput` evaluates to `true`: +The [`<pre>`](/en-US/docs/Web/HTML/Reference/Elements/pre) element above the input shows the validation message when the element `badInput` evaluates to `true`: ```css input:invalid { @@ -56,7 +56,7 @@ function log(text) { userInput.addEventListener("input", () => { userInput.reportValidity(); if (userInput.validity.badInput) { - log("Bad input detected: " + userInput.validationMessage); + log(`Bad input detected: ${userInput.validationMessage}`); } }); ``` @@ -74,5 +74,5 @@ userInput.addEventListener("input", () => { ## See also - ValidityState [valid](/en-US/docs/Web/API/ValidityState/valid), [customError](/en-US/docs/Web/API/ValidityState/customError) properties. -- [Guide: Constraint validation](/en-US/docs/Web/HTML/Constraint_validation) +- [Guide: Constraint validation](/en-US/docs/Web/HTML/Guides/Constraint_validation) - [Tutorial: Form data validation](/en-US/docs/Learn_web_development/Extensions/Forms/Form_validation) diff --git a/files/en-us/web/api/validitystate/customerror/index.md b/files/en-us/web/api/validitystate/customerror/index.md index 09dde5c0aeb5ee9..1959a1f1b589bf5 100644 --- a/files/en-us/web/api/validitystate/customerror/index.md +++ b/files/en-us/web/api/validitystate/customerror/index.md @@ -19,10 +19,10 @@ A boolean that is `true` if a custom error message has been set to a non-empty s ### Detecting a custom error In this example, {{domxref("HTMLInputElement.setCustomValidity", "setCustomValidity()")}} sets a custom error message when a form submission contains user input that's considered invalid. -The "Validate input" button calls {{domxref("HTMLInputElement.reportValidity", "reportValidity()")}}, which displays a validation message under the element if a user enters values that do not match the [form's constraints](/en-US/docs/Web/HTML/Constraint_validation#constraint_validation_process). +The "Validate input" button calls {{domxref("HTMLInputElement.reportValidity", "reportValidity()")}}, which displays a validation message under the element if a user enters values that do not match the [form's constraints](/en-US/docs/Web/HTML/Guides/Constraint_validation#constraint_validation_process). If you enter the text "good" or "fine" and try to validate the input, the field is marked invalid until the custom error message is cleared (set to an empty string). -For comparison, there is a [`minlength`](/en-US/docs/Web/HTML/Attributes/minlength) attribute on the input element that allows us to demonstrate the [`tooShort` validity state](/en-US/docs/Web/API/ValidityState/tooShort) when the user enters less than two characters. +For comparison, there is a [`minlength`](/en-US/docs/Web/HTML/Reference/Attributes/minlength) attribute on the input element that allows us to demonstrate the [`tooShort` validity state](/en-US/docs/Web/API/ValidityState/tooShort) when the user enters less than two characters. When the value in the form control is invalid, even if there is no custom error, the input will have a red outline. #### HTML @@ -70,7 +70,7 @@ function log(text) { const check = (input) => { // Handle cases where input is too vague - if (input.value == "good" || input.value == "fine") { + if (input.value === "good" || input.value === "fine") { input.setCustomValidity(`"${input.value}" is not a feeling.`); } else { // An empty string resets the custom validity state @@ -86,7 +86,7 @@ const validateInput = () => { userInput.reportValidity(); if (userInput.validity.customError) { // We can handle custom validity states here - log("Custom validity error: " + userInput.validationMessage); + log(`Custom validity error: ${userInput.validationMessage}`); } else { log(userInput.validationMessage); } @@ -110,5 +110,5 @@ checkButton.addEventListener("click", validateInput); ## See also - ValidityState [badInput](/en-US/docs/Web/API/ValidityState/badInput), [valid](/en-US/docs/Web/API/ValidityState/valid) properties. -- [Constraint validation](/en-US/docs/Web/HTML/Constraint_validation) +- [Constraint validation](/en-US/docs/Web/HTML/Guides/Constraint_validation) - [Forms: Data form validation](/en-US/docs/Learn_web_development/Extensions/Forms/Form_validation) diff --git a/files/en-us/web/api/validitystate/index.md b/files/en-us/web/api/validitystate/index.md index 286bb05023fe4ea..fb50da902a4dfd4 100644 --- a/files/en-us/web/api/validitystate/index.md +++ b/files/en-us/web/api/validitystate/index.md @@ -18,23 +18,23 @@ For each of these Boolean properties, a value of `true` indicates that the speci - {{domxref("ValidityState.customError", "customError")}} {{ReadOnlyInline}} - : A boolean value indicating whether the element's custom validity message has been set to a non-empty string by calling the element's {{domxref('HTMLInputElement.setCustomValidity', 'setCustomValidity()')}} method. - {{domxref("ValidityState.patternMismatch", "patternMismatch")}} {{ReadOnlyInline}} - - : A boolean value that is `true` if the value does not match the specified [`pattern`](/en-US/docs/Web/HTML/Element/input#pattern), and `false` if it does match. If `true`, the element matches the {{cssxref(":invalid")}} CSS pseudo-class. + - : A boolean value that is `true` if the value does not match the specified [`pattern`](/en-US/docs/Web/HTML/Reference/Elements/input#pattern), and `false` if it does match. If `true`, the element matches the {{cssxref(":invalid")}} CSS pseudo-class. - {{domxref("ValidityState.rangeOverflow", "rangeOverflow")}} {{ReadOnlyInline}} - - : A boolean value that is `true` if the value is greater than the maximum specified by the [`max`](/en-US/docs/Web/HTML/Element/input#max) attribute, or `false` if it is less than or equal to the maximum. If `true`, the element matches the {{cssxref(":invalid")}} and {{cssxref(":out-of-range")}} and CSS pseudo-classes. + - : A boolean value that is `true` if the value is greater than the maximum specified by the [`max`](/en-US/docs/Web/HTML/Reference/Elements/input#max) attribute, or `false` if it is less than or equal to the maximum. If `true`, the element matches the {{cssxref(":invalid")}} and {{cssxref(":out-of-range")}} and CSS pseudo-classes. - {{domxref("ValidityState.rangeUnderflow", "rangeUnderflow")}} {{ReadOnlyInline}} - - : A boolean value that is `true` if the value is less than the minimum specified by the [`min`](/en-US/docs/Web/HTML/Element/input#min) attribute, or `false` if it is greater than or equal to the minimum. If `true`, the element matches the {{cssxref(":invalid")}} and {{cssxref(":out-of-range")}} CSS pseudo-classes. + - : A boolean value that is `true` if the value is less than the minimum specified by the [`min`](/en-US/docs/Web/HTML/Reference/Elements/input#min) attribute, or `false` if it is greater than or equal to the minimum. If `true`, the element matches the {{cssxref(":invalid")}} and {{cssxref(":out-of-range")}} CSS pseudo-classes. - {{domxref("ValidityState.stepMismatch", "stepMismatch")}} {{ReadOnlyInline}} - - : A boolean value that is `true` if the value does not fit the rules determined by the [`step`](/en-US/docs/Web/HTML/Element/input#step) attribute (that is, it's not evenly divisible by the step value), or `false` if it does fit the step rule. If `true`, the element matches the {{cssxref(":invalid")}} CSS pseudo-class. + - : A boolean value that is `true` if the value does not fit the rules determined by the [`step`](/en-US/docs/Web/HTML/Reference/Elements/input#step) attribute (that is, it's not evenly divisible by the step value), or `false` if it does fit the step rule. If `true`, the element matches the {{cssxref(":invalid")}} CSS pseudo-class. - {{domxref("ValidityState.tooLong", "tooLong")}} {{ReadOnlyInline}} - : A boolean value that is `true` if the value exceeds the specified `maxlength` for {{domxref("HTMLInputElement")}} or {{domxref("HTMLTextAreaElement")}} objects, or `false` if its length is less than or equal to the maximum length. _Note: This property is never `true` in Gecko, because elements' values are prevented from being longer than `maxlength`._ If `true`, the element matches the {{cssxref(":invalid")}} and {{cssxref(":out-of-range")}} CSS pseudo-classes. - {{domxref("ValidityState.tooShort", "tooShort")}} {{ReadOnlyInline}} - : A boolean value that is `true` if the value fails to meet the specified `minlength` for {{domxref("HTMLInputElement")}} or {{domxref("HTMLTextAreaElement")}} objects, or `false` if its length is greater than or equal to the minimum length. If `true`, the element matches the {{cssxref(":invalid")}} and {{cssxref(":out-of-range")}} CSS pseudo-classes. - {{domxref("ValidityState.typeMismatch", "typeMismatch")}} {{ReadOnlyInline}} - - : A boolean value that is `true` if the value is not in the required syntax (when [`type`](/en-US/docs/Web/HTML/Element/input#type) is `email` or `url`), or `false` if the syntax is correct. If `true`, the element matches the {{cssxref(":invalid")}} CSS pseudo-class. + - : A boolean value that is `true` if the value is not in the required syntax (when [`type`](/en-US/docs/Web/HTML/Reference/Elements/input#type) is `email` or `url`), or `false` if the syntax is correct. If `true`, the element matches the {{cssxref(":invalid")}} CSS pseudo-class. - {{domxref("ValidityState.valid", "valid")}} {{ReadOnlyInline}} - : A boolean value that is `true` if the element meets all its validation constraints, and is therefore considered to be valid, or `false` if it fails any constraint. If `true`, the element matches the {{cssxref(":valid")}} CSS pseudo-class; the {{cssxref(":invalid")}} CSS pseudo-class otherwise. - {{domxref("ValidityState.valueMissing", "valueMissing")}} {{ReadOnlyInline}} - - : A boolean value that is `true` if the element has a [`required`](/en-US/docs/Web/HTML/Element/input#required) attribute, but no value, or `false` otherwise. If `true`, the element matches the {{cssxref(":invalid")}} CSS pseudo-class. + - : A boolean value that is `true` if the element has a [`required`](/en-US/docs/Web/HTML/Reference/Elements/input#required) attribute, but no value, or `false` otherwise. If `true`, the element matches the {{cssxref(":invalid")}} CSS pseudo-class. ## Specifications @@ -46,5 +46,5 @@ For each of these Boolean properties, a value of `true` indicates that the speci ## See also -- [Guide: Constraint validation](/en-US/docs/Web/HTML/Constraint_validation) +- [Guide: Constraint validation](/en-US/docs/Web/HTML/Guides/Constraint_validation) - [Tutorial: Form data validation](/en-US/docs/Learn_web_development/Extensions/Forms/Form_validation) diff --git a/files/en-us/web/api/validitystate/patternmismatch/index.md b/files/en-us/web/api/validitystate/patternmismatch/index.md index 3620df6193879c4..2fb6335664d0257 100644 --- a/files/en-us/web/api/validitystate/patternmismatch/index.md +++ b/files/en-us/web/api/validitystate/patternmismatch/index.md @@ -8,13 +8,13 @@ browser-compat: api.ValidityState.patternMismatch {{APIRef("HTML DOM")}} -The read-only **`patternMismatch`** property of the [`ValidityState`](/en-US/docs/Web/API/ValidityState) interface indicates if the value of an {{HTMLElement("input")}}, after having been edited by the user, does not conform to the constraints set by the element's [`pattern`](/en-US/docs/Web/HTML/Attributes/pattern) attribute. +The read-only **`patternMismatch`** property of the [`ValidityState`](/en-US/docs/Web/API/ValidityState) interface indicates if the value of an {{HTMLElement("input")}}, after having been edited by the user, does not conform to the constraints set by the element's [`pattern`](/en-US/docs/Web/HTML/Reference/Attributes/pattern) attribute. The `patternMismatch` property will be true if and only if the following conditions are all true: -- the field supports the [`pattern`](/en-US/docs/Web/HTML/Attributes/pattern) attribute — which means the {{HTMLElement("input")}} is of `type` {{HTMLElement("input/text", "text")}}, {{HTMLElement("input/tel", "tel")}}, {{HTMLElement("input/email", "email")}}, {{HTMLElement("input/url", "url")}}, {{HTMLElement("input/password", "password")}}, or {{HTMLElement("input/search", "search")}} -- the [`pattern`](/en-US/docs/Web/HTML/Attributes/pattern) attribute contains a valid regular expression -- the {{HTMLElement("input")}} value doesn't conform to the constraints set by the [`pattern`](/en-US/docs/Web/HTML/Attributes/pattern) value. +- the field supports the [`pattern`](/en-US/docs/Web/HTML/Reference/Attributes/pattern) attribute — which means the {{HTMLElement("input")}} is of `type` {{HTMLElement("input/text", "text")}}, {{HTMLElement("input/tel", "tel")}}, {{HTMLElement("input/email", "email")}}, {{HTMLElement("input/url", "url")}}, {{HTMLElement("input/password", "password")}}, or {{HTMLElement("input/search", "search")}} +- the [`pattern`](/en-US/docs/Web/HTML/Reference/Attributes/pattern) attribute contains a valid regular expression +- the {{HTMLElement("input")}} value doesn't conform to the constraints set by the [`pattern`](/en-US/docs/Web/HTML/Reference/Attributes/pattern) value. ## Value @@ -53,7 +53,7 @@ Given the following: </p> ``` -Here we have 3 sections for a North American phone number with an implicit label encompassing all three components of the phone number, expecting 3-digits, 3-digits and 4-digits respectively, as defined by the [`pattern`](/en-US/docs/Web/HTML/Attributes/pattern) attribute set on each. +Here we have 3 sections for a North American phone number with an implicit label encompassing all three components of the phone number, expecting 3-digits, 3-digits and 4-digits respectively, as defined by the [`pattern`](/en-US/docs/Web/HTML/Reference/Attributes/pattern) attribute set on each. If the values are too long or too short, or contain characters that aren't digits, `patternMismatch` will be true. When `true`, the element matches the {{cssxref(":invalid")}} CSS pseudo-classes. @@ -65,7 +65,7 @@ input:invalid { {{EmbedLiveSample("Examples", 300, 87)}} -Note, in this case, we get a `patternMismatch` not a {{domxref('validityState.tooLong')}} or {{domxref('validityState.tooShort')}} if the values are too long or too short because it is the pattern that is dictating the length of the value. Had we used [`minlength`](/en-US/docs/Web/HTML/Attributes/minlength) and [`maxlength`](/en-US/docs/Web/HTML/Attributes/maxlength) attributes instead, we may have seen {{domxref('validityState.tooLong')}} or {{domxref('validityState.tooShort')}} being true. +Note, in this case, we get a `patternMismatch` not a {{domxref('validityState.tooLong')}} or {{domxref('validityState.tooShort')}} if the values are too long or too short because it is the pattern that is dictating the length of the value. Had we used [`minlength`](/en-US/docs/Web/HTML/Reference/Attributes/minlength) and [`maxlength`](/en-US/docs/Web/HTML/Reference/Attributes/maxlength) attributes instead, we may have seen {{domxref('validityState.tooLong')}} or {{domxref('validityState.tooShort')}} being true. > [!NOTE] > The `{{HTMLElement("input/email", "email")}}` input type requires, at minimum, a match of `x@y` and the `{{HTMLElement("input/url", "url")}}` type requires, at minimum, a match to x:, with no pattern attribute present. When invalid, the {{domxref('validityState.typeMismatch')}} will be true, if there is no pattern attribute (or if the pattern attribute is not valid for that input type). @@ -80,6 +80,6 @@ Note, in this case, we get a `patternMismatch` not a {{domxref('validityState.to ## See also -- [Constraint validation](/en-US/docs/Web/HTML/Constraint_validation) +- [Constraint validation](/en-US/docs/Web/HTML/Guides/Constraint_validation) - [Forms: Data form validation](/en-US/docs/Learn_web_development/Extensions/Forms/Form_validation) - [Regular Expressions](/en-US/docs/Web/JavaScript/Guide/Regular_expressions) diff --git a/files/en-us/web/api/validitystate/rangeoverflow/index.md b/files/en-us/web/api/validitystate/rangeoverflow/index.md index 35cabe2fe28c34b..6bf9451e45d7bb2 100644 --- a/files/en-us/web/api/validitystate/rangeoverflow/index.md +++ b/files/en-us/web/api/validitystate/rangeoverflow/index.md @@ -8,9 +8,9 @@ browser-compat: api.ValidityState.rangeOverflow {{APIRef("HTML DOM")}} -The read-only **`rangeOverflow`** property of the [`ValidityState`](/en-US/docs/Web/API/ValidityState) interface indicates if the value of an {{HTMLElement("input")}}, after having been edited by the user, does not conform to the constraints set by the element's [`max`](/en-US/docs/Web/HTML/Attributes/max) attribute. +The read-only **`rangeOverflow`** property of the [`ValidityState`](/en-US/docs/Web/API/ValidityState) interface indicates if the value of an {{HTMLElement("input")}}, after having been edited by the user, does not conform to the constraints set by the element's [`max`](/en-US/docs/Web/HTML/Reference/Attributes/max) attribute. -If the field is numeric in nature, including the {{HTMLElement("input/date", "date")}}, {{HTMLElement("input/month", "month")}}, {{HTMLElement("input/week", "week")}}, {{HTMLElement("input/time", "time")}}, {{HTMLElement("input/datetime-local", "datetime-local")}}, {{HTMLElement("input/number", "number")}} and {{HTMLElement("input/range", "range")}} types and a `max` value is set, if the value doesn't conform to the constraints set by the [`max`](/en-US/docs/Web/HTML/Attributes/step) value, the `rangeOverflow` property will be true. +If the field is numeric in nature, including the {{HTMLElement("input/date", "date")}}, {{HTMLElement("input/month", "month")}}, {{HTMLElement("input/week", "week")}}, {{HTMLElement("input/time", "time")}}, {{HTMLElement("input/datetime-local", "datetime-local")}}, {{HTMLElement("input/number", "number")}} and {{HTMLElement("input/range", "range")}} types and a `max` value is set, if the value doesn't conform to the constraints set by the [`max`](/en-US/docs/Web/HTML/Reference/Attributes/step) value, the `rangeOverflow` property will be true. ## Value @@ -20,8 +20,8 @@ A boolean that is `true` if the `ValidityState` does not conform to the constrai ### Input with numeric overflow -The following example checks the validity of a [numeric input element](/en-US/docs/Web/HTML/Element/input/number). -A constraint has been added using the [`max` attribute](/en-US/docs/Web/HTML/Element/input/number#max) which sets a maximum value of `18` for the input. +The following example checks the validity of a [numeric input element](/en-US/docs/Web/HTML/Reference/Elements/input/number). +A constraint has been added using the [`max` attribute](/en-US/docs/Web/HTML/Reference/Elements/input/number#max) which sets a maximum value of `18` for the input. If the user enters a number higher than 18, the element fails constraint validation, and the styles matching {{cssxref(":invalid")}} and {{cssxref(":out-of-range")}} CSS pseudo-classes ```css @@ -79,7 +79,7 @@ userInput.addEventListener("input", () => { ## See also - {{domxref("ValidityState.rangeUnderflow")}} -- [Constraint validation](/en-US/docs/Web/HTML/Constraint_validation) +- [Constraint validation](/en-US/docs/Web/HTML/Guides/Constraint_validation) - [Forms: Data form validation](/en-US/docs/Learn_web_development/Extensions/Forms/Form_validation) -- [`step` attribute](/en-US/docs/Web/HTML/Attributes/step) -- [`min` attribute](/en-US/docs/Web/HTML/Attributes/min) +- [`step` attribute](/en-US/docs/Web/HTML/Reference/Attributes/step) +- [`min` attribute](/en-US/docs/Web/HTML/Reference/Attributes/min) diff --git a/files/en-us/web/api/validitystate/rangeunderflow/index.md b/files/en-us/web/api/validitystate/rangeunderflow/index.md index fb5134b0ad43733..5783b91d01c6645 100644 --- a/files/en-us/web/api/validitystate/rangeunderflow/index.md +++ b/files/en-us/web/api/validitystate/rangeunderflow/index.md @@ -8,9 +8,9 @@ browser-compat: api.ValidityState.rangeUnderflow {{APIRef("HTML DOM")}} -The read-only **`rangeUnderflow`** property of the [`ValidityState`](/en-US/docs/Web/API/ValidityState) interface indicates if the value of an {{HTMLElement("input")}}, after having been edited by the user, does not conform to the constraints set by the element's [`min`](/en-US/docs/Web/HTML/Attributes/min) attribute. +The read-only **`rangeUnderflow`** property of the [`ValidityState`](/en-US/docs/Web/API/ValidityState) interface indicates if the value of an {{HTMLElement("input")}}, after having been edited by the user, does not conform to the constraints set by the element's [`min`](/en-US/docs/Web/HTML/Reference/Attributes/min) attribute. -If the field is numeric in nature, including the {{HTMLElement("input/date", "date")}}, {{HTMLElement("input/month", "month")}}, {{HTMLElement("input/week", "week")}}, {{HTMLElement("input/time", "time")}}, {{HTMLElement("input/datetime-local", "datetime-local")}}, {{HTMLElement("input/number", "number")}} and {{HTMLElement("input/range", "range")}} types and a `min` value is set, if the value doesn't conform to the constraints set by the [`min`](/en-US/docs/Web/HTML/Attributes/step) value, the `rangeUnderflow` property will be true. +If the field is numeric in nature, including the {{HTMLElement("input/date", "date")}}, {{HTMLElement("input/month", "month")}}, {{HTMLElement("input/week", "week")}}, {{HTMLElement("input/time", "time")}}, {{HTMLElement("input/datetime-local", "datetime-local")}}, {{HTMLElement("input/number", "number")}} and {{HTMLElement("input/range", "range")}} types and a `min` value is set, if the value doesn't conform to the constraints set by the [`min`](/en-US/docs/Web/HTML/Reference/Attributes/step) value, the `rangeUnderflow` property will be true. ## Value @@ -20,8 +20,8 @@ A boolean that is `true` if the `ValidityState` does not conform to the constrai ### Input with numeric underflow -The following example checks the validity of a [numeric input element](/en-US/docs/Web/HTML/Element/input/number). -A constraint has been added using the [`min` attribute](/en-US/docs/Web/HTML/Element/input/number#min) which sets a minimum value of `18` for the input. +The following example checks the validity of a [numeric input element](/en-US/docs/Web/HTML/Reference/Elements/input/number). +A constraint has been added using the [`min` attribute](/en-US/docs/Web/HTML/Reference/Elements/input/number#min) which sets a minimum value of `18` for the input. If the user enters a number lower than 18, the element fails constraint validation, and the styles matching {{cssxref(":invalid")}} and {{cssxref(":out-of-range")}} CSS pseudo-classes ```css @@ -79,7 +79,7 @@ userInput.addEventListener("input", () => { ## See also - {{domxref("ValidityState.rangeOverflow")}} -- [Constraint validation](/en-US/docs/Web/HTML/Constraint_validation) +- [Constraint validation](/en-US/docs/Web/HTML/Guides/Constraint_validation) - [Forms: Data form validation](/en-US/docs/Learn_web_development/Extensions/Forms/Form_validation) -- [`step` attribute](/en-US/docs/Web/HTML/Attributes/step) -- [`max` attribute](/en-US/docs/Web/HTML/Attributes/max) +- [`step` attribute](/en-US/docs/Web/HTML/Reference/Attributes/step) +- [`max` attribute](/en-US/docs/Web/HTML/Reference/Attributes/max) diff --git a/files/en-us/web/api/validitystate/stepmismatch/index.md b/files/en-us/web/api/validitystate/stepmismatch/index.md index 8d1c756d9456b36..51ed7a92d9bf5fb 100644 --- a/files/en-us/web/api/validitystate/stepmismatch/index.md +++ b/files/en-us/web/api/validitystate/stepmismatch/index.md @@ -10,7 +10,7 @@ browser-compat: api.ValidityState.stepMismatch The read-only **`stepMismatch`** property of the [`ValidityState`](/en-US/docs/Web/API/ValidityState) interface indicates if the value of an {{HTMLElement("input")}}, after having been edited by the user, does not conform to the constraints set by the element's `step` attribute. -If the field is numeric in nature, including the {{HTMLElement("input/date", "date")}}, {{HTMLElement("input/month", "month")}}, {{HTMLElement("input/week", "week")}}, {{HTMLElement("input/time", "time")}}, {{HTMLElement("input/datetime-local", "datetime-local")}}, {{HTMLElement("input/number", "number")}} and {{HTMLElement("input/range", "range")}} types and the step value is not `any`, if the value don't doesn't conform to the constraints set by the [`step`](/en-US/docs/Web/HTML/Attributes/step) and [`min`](/en-US/docs/Web/HTML/Attributes/min) values, then `stepMismatch` will be true. If the remainder of the form control's value less the [`min`](/en-US/docs/Web/HTML/Attributes/min) value, divided by the [`step`](/en-US/docs/Web/HTML/Attributes/step) value (which defaults to 1 if omitted) is not zero, there is a mismatch. +If the field is numeric in nature, including the {{HTMLElement("input/date", "date")}}, {{HTMLElement("input/month", "month")}}, {{HTMLElement("input/week", "week")}}, {{HTMLElement("input/time", "time")}}, {{HTMLElement("input/datetime-local", "datetime-local")}}, {{HTMLElement("input/number", "number")}} and {{HTMLElement("input/range", "range")}} types and the step value is not `any`, if the value don't doesn't conform to the constraints set by the [`step`](/en-US/docs/Web/HTML/Reference/Attributes/step) and [`min`](/en-US/docs/Web/HTML/Reference/Attributes/min) values, then `stepMismatch` will be true. If the remainder of the form control's value less the [`min`](/en-US/docs/Web/HTML/Reference/Attributes/min) value, divided by the [`step`](/en-US/docs/Web/HTML/Reference/Attributes/step) value (which defaults to 1 if omitted) is not zero, there is a mismatch. ## Value @@ -20,8 +20,8 @@ A boolean that is `true` if the `ValidityState` does not conform to the constrai ### Input with step mismatch -The following example checks the validity of a [numeric input element](/en-US/docs/Web/HTML/Element/input/number). -A constraint has been added using the [`step` attribute](/en-US/docs/Web/HTML/Element/input/number#step) which means the input expects increments of 5 as values. +The following example checks the validity of a [numeric input element](/en-US/docs/Web/HTML/Reference/Elements/input/number). +A constraint has been added using the [`step` attribute](/en-US/docs/Web/HTML/Reference/Elements/input/number#step) which means the input expects increments of 5 as values. If the user enters a number that's not divisible by 5, the element fails constraint validation, and the styles matching {{cssxref(":invalid")}} CSS pseudo-class are applied. ```css @@ -77,6 +77,6 @@ userInput.addEventListener("input", () => { ## See also -- [Constraint validation](/en-US/docs/Web/HTML/Constraint_validation) +- [Constraint validation](/en-US/docs/Web/HTML/Guides/Constraint_validation) - [Forms: Data form validation](/en-US/docs/Learn_web_development/Extensions/Forms/Form_validation) -- [`step` attribute](/en-US/docs/Web/HTML/Attributes/step) +- [`step` attribute](/en-US/docs/Web/HTML/Reference/Attributes/step) diff --git a/files/en-us/web/api/validitystate/toolong/index.md b/files/en-us/web/api/validitystate/toolong/index.md index c7e78bd8931f283..3b3bc8f4d328dd3 100644 --- a/files/en-us/web/api/validitystate/toolong/index.md +++ b/files/en-us/web/api/validitystate/toolong/index.md @@ -8,7 +8,7 @@ browser-compat: api.ValidityState.tooLong {{APIRef("HTML DOM")}} -The read-only **`tooLong`** property of the [`ValidityState`](/en-US/docs/Web/API/ValidityState) interface indicates if the value of an {{HTMLElement("input")}} or {{HTMLElement("textarea")}}, after having been edited by the user, exceeds the maximum code-unit length established by the element's [`maxlength`](/en-US/docs/Web/HTML/Attributes/maxlength) attribute. +The read-only **`tooLong`** property of the [`ValidityState`](/en-US/docs/Web/API/ValidityState) interface indicates if the value of an {{HTMLElement("input")}} or {{HTMLElement("textarea")}}, after having been edited by the user, exceeds the maximum code-unit length established by the element's [`maxlength`](/en-US/docs/Web/HTML/Reference/Attributes/maxlength) attribute. ## Value @@ -18,8 +18,8 @@ A boolean that is `true` if the `ValidityState` does not conform to the constrai ### Textarea with too long character count -The following example checks the validity of a [textarea element](/en-US/docs/Web/HTML/Element/textarea). -A constraint has been added using the [`maxlength` attribute](/en-US/docs/Web/HTML/Element/input/text#maxlength) so the textarea expects a maximum of 10 characters. +The following example checks the validity of a [textarea element](/en-US/docs/Web/HTML/Reference/Elements/textarea). +A constraint has been added using the [`maxlength` attribute](/en-US/docs/Web/HTML/Reference/Elements/input/text#maxlength) so the textarea expects a maximum of 10 characters. If there are too many characters in the textarea (which is true below), the element fails constraint validation, and the styles matching {{cssxref(":invalid")}} CSS pseudo-class are applied. When editing the textarea, the browser will not allow the user to add characters that would fail constraint validation of maximum character count, so at first, only deleting characters is allowed. @@ -86,5 +86,5 @@ userInput.addEventListener("input", () => { ## See also -- [Constraint validation](/en-US/docs/Web/HTML/Constraint_validation) +- [Constraint validation](/en-US/docs/Web/HTML/Guides/Constraint_validation) - [Forms: Data form validation](/en-US/docs/Learn_web_development/Extensions/Forms/Form_validation) diff --git a/files/en-us/web/api/validitystate/tooshort/index.md b/files/en-us/web/api/validitystate/tooshort/index.md index c435fe1112e2d5e..8a8bc076fb1e2e8 100644 --- a/files/en-us/web/api/validitystate/tooshort/index.md +++ b/files/en-us/web/api/validitystate/tooshort/index.md @@ -18,8 +18,8 @@ A boolean that is `true` if the `ValidityState` does not conform to the constrai ### Input with too short string value -The following example checks the validity of a [text input element](/en-US/docs/Web/HTML/Element/input/text). -A constraint has been added using the [`minlength` attribute](/en-US/docs/Web/HTML/Element/input/text#minlength) so the input expects a string with a minimum of 4 characters. +The following example checks the validity of a [text input element](/en-US/docs/Web/HTML/Reference/Elements/input/text). +A constraint has been added using the [`minlength` attribute](/en-US/docs/Web/HTML/Reference/Elements/input/text#minlength) so the input expects a string with a minimum of 4 characters. If the user enters a string that's too short, the element fails constraint validation, and the styles matching {{cssxref(":invalid")}} CSS pseudo-class are applied. ```css @@ -75,5 +75,5 @@ userInput.addEventListener("input", () => { ## See also -- [Guide: Constraint validation](/en-US/docs/Web/HTML/Constraint_validation) +- [Guide: Constraint validation](/en-US/docs/Web/HTML/Guides/Constraint_validation) - [Tutorial: Form data validation](/en-US/docs/Learn_web_development/Extensions/Forms/Form_validation) diff --git a/files/en-us/web/api/validitystate/typemismatch/index.md b/files/en-us/web/api/validitystate/typemismatch/index.md index aeed512d72bb04b..70d2160ac3b9f7e 100644 --- a/files/en-us/web/api/validitystate/typemismatch/index.md +++ b/files/en-us/web/api/validitystate/typemismatch/index.md @@ -8,13 +8,13 @@ browser-compat: api.ValidityState.typeMismatch {{APIRef("HTML DOM")}} -The read-only **`typeMismatch`** property of the [`ValidityState`](/en-US/docs/Web/API/ValidityState) interface indicates if the value of an {{HTMLElement("input")}}, after having been edited by the user, does not conform to the constraints set by the element's [`type`](/en-US/docs/Web/HTML/Element/input#input_types) attribute. +The read-only **`typeMismatch`** property of the [`ValidityState`](/en-US/docs/Web/API/ValidityState) interface indicates if the value of an {{HTMLElement("input")}}, after having been edited by the user, does not conform to the constraints set by the element's [`type`](/en-US/docs/Web/HTML/Reference/Elements/input#input_types) attribute. If the `type` attribute expects specific strings, such as the {{HTMLElement("input/email", "email")}} and {{HTMLElement("input/url", "url")}} types and the value doesn't conform to the constraints set by the type, the `typeMismatch` property will be true. -The {{HTMLElement("input/email", "email")}} input type expects one or more valid email addresses, depending on whether the [`multiple`](/en-US/docs/Web/HTML/Attributes/multiple) attribute is present. A valid email address includes an email prefix and a domain, with or without a top level domain. If the value of the email input is not an empty string, a single valid email address, or one or more comma separated email address if the [`multiple`](/en-US/docs/Web/HTML/Attributes/multiple) attribute is present, there is a `typeMismatch`. +The {{HTMLElement("input/email", "email")}} input type expects one or more valid email addresses, depending on whether the [`multiple`](/en-US/docs/Web/HTML/Reference/Attributes/multiple) attribute is present. A valid email address includes an email prefix and a domain, with or without a top level domain. If the value of the email input is not an empty string, a single valid email address, or one or more comma separated email address if the [`multiple`](/en-US/docs/Web/HTML/Reference/Attributes/multiple) attribute is present, there is a `typeMismatch`. -The {{HTMLElement("input/url", "url")}} input type expects one or more valid URLs, depending on whether the [`multiple`](/en-US/docs/Web/HTML/Attributes/multiple) attribute is present. A valid URL includes a protocol, optionally with an IP address, or an optional subdomain, domain, and top level domain combination. If the value of the URL input is not an empty string, a single valid URL, or one or more comma separated URLS if the [`multiple`](/en-US/docs/Web/HTML/Attributes/multiple) attribute is present, there is a `typeMismatch`. +The {{HTMLElement("input/url", "url")}} input type expects one or more valid URLs, depending on whether the [`multiple`](/en-US/docs/Web/HTML/Reference/Attributes/multiple) attribute is present. A valid URL includes a protocol, optionally with an IP address, or an optional subdomain, domain, and top level domain combination. If the value of the URL input is not an empty string, a single valid URL, or one or more comma separated URLS if the [`multiple`](/en-US/docs/Web/HTML/Reference/Attributes/multiple) attribute is present, there is a `typeMismatch`. | Input type | Value | Expected value | | --------------------------------------- | ----------------- | -------------------------------------------------------------- | @@ -29,11 +29,11 @@ A boolean that is `true` if the `ValidityState` does not conform to the constrai ### Type mismatch on input element -The `typeMismatch` occurs when there is a disconnect between the [`value`](/en-US/docs/Web/HTML/Element/input#value) expected via the [`type`](/en-US/docs/Web/HTML/Element/input#input_types) attribute and the data that is actually present. +The `typeMismatch` occurs when there is a disconnect between the [`value`](/en-US/docs/Web/HTML/Reference/Elements/input#value) expected via the [`type`](/en-US/docs/Web/HTML/Reference/Elements/input#input_types) attribute and the data that is actually present. The `typeMismatch` is only one of the many possible errors and is only relevant for the {{HTMLElement("input/email", "email")}} and {{HTMLElement("input/url", "url")}} types. When the value provided doesn't match the expected value based on the type for other input types, you get different errors. For example, if the {{HTMLElement("input/number", "number")}} input value is not a floating point number, the `badInput` is `true`. -If the email is [`required`](/en-US/docs/Web/HTML/Attributes/required) but is empty, the {{domxref('ValidityState.valueMissing','valueMissing')}} will be `true`. +If the email is [`required`](/en-US/docs/Web/HTML/Reference/Attributes/required) but is empty, the {{domxref('ValidityState.valueMissing','valueMissing')}} will be `true`. ```html <pre id="log">Validation logged here...</pre> @@ -78,7 +78,7 @@ emailInput.addEventListener("input", () => { } else if (emailInput.validity.typeMismatch) { log("Input is not an email."); } else { - log("Validation failed: " + emailInput.validationMessage); + log(`Validation failed: ${emailInput.validationMessage}`); } }); ``` @@ -96,6 +96,6 @@ emailInput.addEventListener("input", () => { ## See also - ValidityState [badInput](/en-US/docs/Web/API/ValidityState/badInput), [valid](/en-US/docs/Web/API/ValidityState/valid), [customError](/en-US/docs/Web/API/ValidityState/customError) properties. -- [Constraint validation](/en-US/docs/Web/HTML/Constraint_validation) +- [Constraint validation](/en-US/docs/Web/HTML/Guides/Constraint_validation) - [Forms: Data form validation](/en-US/docs/Learn_web_development/Extensions/Forms/Form_validation) - [Regular Expressions](/en-US/docs/Web/JavaScript/Guide/Regular_expressions) diff --git a/files/en-us/web/api/validitystate/valid/index.md b/files/en-us/web/api/validitystate/valid/index.md index e7bf4cfafcc9088..7667cee0ed60276 100644 --- a/files/en-us/web/api/validitystate/valid/index.md +++ b/files/en-us/web/api/validitystate/valid/index.md @@ -20,8 +20,8 @@ A boolean that is `true` if the `ValidityState` does conform to all the constrai ### Displaying validity state -The following example checks the validity of a [numeric input element](/en-US/docs/Web/HTML/Element/input/number). -A constraint has been added using the [`min` attribute](/en-US/docs/Web/HTML/Element/input/number#min) which sets a minimum value of `18` for the input. +The following example checks the validity of a [numeric input element](/en-US/docs/Web/HTML/Reference/Elements/input/number). +A constraint has been added using the [`min` attribute](/en-US/docs/Web/HTML/Reference/Elements/input/number#min) which sets a minimum value of `18` for the input. If the user enters any value that's not a number greater than 17, the element fails constraint validation, and the styles matching `input:invalid` are applied. ```css @@ -81,5 +81,5 @@ userInput.addEventListener("input", () => { ## See also - ValidityState [badInput](/en-US/docs/Web/API/ValidityState/badInput), [customError](/en-US/docs/Web/API/ValidityState/customError) properties. -- [Constraint validation](/en-US/docs/Web/HTML/Constraint_validation) +- [Constraint validation](/en-US/docs/Web/HTML/Guides/Constraint_validation) - [Forms: Data form validation](/en-US/docs/Learn_web_development/Extensions/Forms/Form_validation) diff --git a/files/en-us/web/api/validitystate/valuemissing/index.md b/files/en-us/web/api/validitystate/valuemissing/index.md index edf358e2896d30c..98b01149961a554 100644 --- a/files/en-us/web/api/validitystate/valuemissing/index.md +++ b/files/en-us/web/api/validitystate/valuemissing/index.md @@ -8,7 +8,7 @@ browser-compat: api.ValidityState.valueMissing {{APIRef("HTML DOM")}} -The read-only **`valueMissing`** property of the [`ValidityState`](/en-US/docs/Web/API/ValidityState) interface indicates if a [`required`](/en-US/docs/Web/HTML/Attributes/required) control, such as an {{HTMLElement("input")}}, {{HTMLElement("select")}}, or {{HTMLElement("textarea")}}, has an empty value. +The read-only **`valueMissing`** property of the [`ValidityState`](/en-US/docs/Web/API/ValidityState) interface indicates if a [`required`](/en-US/docs/Web/HTML/Reference/Attributes/required) control, such as an {{HTMLElement("input")}}, {{HTMLElement("select")}}, or {{HTMLElement("textarea")}}, has an empty value. If the `required` attribute is set, and no {{HTMLElement("option")}} is selected or a `<textarea>` or user-editable `<input>` is empty, the `valueMissing` property will be `true`. The property is only `true` if the field is required and has no value; if the field is not required, or if the field is required and has a value, the value is `false`. @@ -18,8 +18,8 @@ A boolean that is `true` if the `ValidityState` is not set and the `required` at ### Missing required input value -The following example checks the validity of a [numeric input element](/en-US/docs/Web/HTML/Element/input/number). -Constraints have been added using the [`min` attribute](/en-US/docs/Web/HTML/Element/input/number#min) which sets a minimum value of `18` for the input, and the [`required` attribute](/en-US/docs/Web/HTML/Attributes/required) which disallows empty values. +The following example checks the validity of a [numeric input element](/en-US/docs/Web/HTML/Reference/Elements/input/number). +Constraints have been added using the [`min` attribute](/en-US/docs/Web/HTML/Reference/Elements/input/number#min) which sets a minimum value of `18` for the input, and the [`required` attribute](/en-US/docs/Web/HTML/Reference/Attributes/required) which disallows empty values. If the user enters any value that's not a number greater than 17, the element fails constraint validation, and the styles matching {{cssxref(":invalid")}} are applied. ```css @@ -60,7 +60,7 @@ userInput.addEventListener("input", () => { } else if (userInput.validity.valueMissing) { log("Required field cannot be empty."); } else { - log("Bad input detected: " + userInput.validationMessage); + log(`Bad input detected: ${userInput.validationMessage}`); } }); ``` @@ -78,6 +78,6 @@ userInput.addEventListener("input", () => { ## See also - ValidityState [badInput](/en-US/docs/Web/API/ValidityState/badInput), [valid](/en-US/docs/Web/API/ValidityState/valid) properties. -- [Constraint validation](/en-US/docs/Web/HTML/Constraint_validation) +- [Constraint validation](/en-US/docs/Web/HTML/Guides/Constraint_validation) - [Forms: Data form validation](/en-US/docs/Learn_web_development/Extensions/Forms/Form_validation) - [Regular Expressions](/en-US/docs/Web/JavaScript/Guide/Regular_expressions) diff --git a/files/en-us/web/api/videodecoder/configure/index.md b/files/en-us/web/api/videodecoder/configure/index.md index be6eb8100eddf22..dba4719b1c79e0a 100644 --- a/files/en-us/web/api/videodecoder/configure/index.md +++ b/files/en-us/web/api/videodecoder/configure/index.md @@ -21,7 +21,7 @@ configure(config) - `config` - : An object containing the following members: - `codec` - - : A string containing a [valid codec string](https://www.w3.org/TR/webcodecs-codec-registry/#video-codec-registry). See ["codecs" parameter](/en-US/docs/Web/Media/Guides/Formats/codecs_parameter#codec_options_by_container) for details on codec string construction. + - : A string containing a [valid codec string](https://w3c.github.io/webcodecs/codec_registry.html#video-codec-registry). See ["codecs" parameter](/en-US/docs/Web/Media/Guides/Formats/codecs_parameter#codec_options_by_container) for details on codec string construction. - `description` {{optional_inline}} - : An {{jsxref("ArrayBuffer")}}, a {{jsxref("TypedArray")}}, or a {{jsxref("DataView")}} containing a sequence of codec specific bytes, commonly known as extradata. - `codedWidth` {{optional_inline}} @@ -59,7 +59,7 @@ configure(config) - : A boolean. If `true` this is a hint that the selected decoder should be optimized to minimize the number of {{domxref("EncodedVideoChunk")}} objects that have to be decoded before a {{domxref("VideoFrame")}} is output. > [!NOTE] -> The registrations in the [WebCodecs Codec Registry](https://www.w3.org/TR/webcodecs-codec-registry/#audio-codec-registry) link to a specification detailing whether and how to populate the optional `description` member. +> The registrations in the [WebCodecs Codec Registry](https://w3c.github.io/webcodecs/codec_registry.html#video-codec-registry) link to a specification detailing whether and how to populate the optional `description` member. ### Return value @@ -81,7 +81,7 @@ The following example creates a new {{domxref("VideoDecoder")}} and configures i ```js const init = { output: handleFrame, - error: (e) => { + error(e) { console.log(e.message); }, }; diff --git a/files/en-us/web/api/videodecoder/dequeue_event/index.md b/files/en-us/web/api/videodecoder/dequeue_event/index.md index f42e73bd79928f3..13baeaa0871aa79 100644 --- a/files/en-us/web/api/videodecoder/dequeue_event/index.md +++ b/files/en-us/web/api/videodecoder/dequeue_event/index.md @@ -16,10 +16,10 @@ This eliminates the need for developers to use a {{domxref("Window.setTimeout", Use the event name in methods like {{domxref("EventTarget.addEventListener", "addEventListener()")}}, or set an event handler property. -```js -addEventListener("dequeue", (event) => {}); +```js-nolint +addEventListener("dequeue", (event) => { }) -ondequeue = (event) => {}; +ondequeue = (event) => { } ``` ## Example diff --git a/files/en-us/web/api/videoencoder/configure/index.md b/files/en-us/web/api/videoencoder/configure/index.md index 914c44fbc6845b9..ac7d8d2bf2439be 100644 --- a/files/en-us/web/api/videoencoder/configure/index.md +++ b/files/en-us/web/api/videoencoder/configure/index.md @@ -23,7 +23,7 @@ configure(config) - `config` - : A dictionary object containing the following members: - `codec` - - : A string containing a [valid codec string](https://www.w3.org/TR/webcodecs-codec-registry/#audio-codec-registry). See ["codecs" parameter](/en-US/docs/Web/Media/Guides/Formats/codecs_parameter#codec_options_by_container) for details on codec string construction. + - : A string containing a [valid codec string](https://w3c.github.io/webcodecs/codec_registry.html#video-codec-registry). See ["codecs" parameter](/en-US/docs/Web/Media/Guides/Formats/codecs_parameter#codec_options_by_container) for details on codec string construction. - `width` {{optional_inline}} - : An integer representing the width of each output {{domxref("EncodedVideoChunk")}} in pixels, before any ratio adjustments. - `height` {{optional_inline}} @@ -82,7 +82,7 @@ The following example creates a new {{domxref("VideoEncoder")}} and configures i ```js const init = { output: handleChunk, - error: (e) => { + error(e) { console.log(e.message); }, }; diff --git a/files/en-us/web/api/videoencoder/dequeue_event/index.md b/files/en-us/web/api/videoencoder/dequeue_event/index.md index 71f556b9d949a9d..13afcf5ea8c28b5 100644 --- a/files/en-us/web/api/videoencoder/dequeue_event/index.md +++ b/files/en-us/web/api/videoencoder/dequeue_event/index.md @@ -16,10 +16,10 @@ This eliminates the need for developers to use a {{domxref("Window.setTimeout", Use the event name in methods like {{domxref("EventTarget.addEventListener", "addEventListener()")}}, or set an event handler property. -```js -addEventListener("dequeue", (event) => {}); +```js-nolint +addEventListener("dequeue", (event) => { }) -ondequeue = (event) => {}; +ondequeue = (event) => { } ``` ## Example diff --git a/files/en-us/web/api/videoencoder/encode/index.md b/files/en-us/web/api/videoencoder/encode/index.md index bed97bd8ae2e189..f7ea277fdc77672 100644 --- a/files/en-us/web/api/videoencoder/encode/index.md +++ b/files/en-us/web/api/videoencoder/encode/index.md @@ -85,7 +85,7 @@ if (codec.includes("vp09")) { encodeOptions.av1 = { quantizer: qp }; } else if (codec.includes("avc")) { encodeOptions.avc = { quantizer: qp }; -} else if (codec.includes("hvc1" || codec.includes("hev1"))) { +} else if (codec.includes("hvc1") || codec.includes("hev1")) { encodeOptions.hevc = { quantizer: qp }; } diff --git a/files/en-us/web/api/videoencoder/videoencoder/index.md b/files/en-us/web/api/videoencoder/videoencoder/index.md index e0dc7f691a32bc0..fe4900d8c2a66e4 100644 --- a/files/en-us/web/api/videoencoder/videoencoder/index.md +++ b/files/en-us/web/api/videoencoder/videoencoder/index.md @@ -25,7 +25,7 @@ new VideoEncoder(options) - `decoderConfig` {{Optional_Inline}} - : An object containing: - `codec` - - : A string containing a [valid codec string](https://www.w3.org/TR/webcodecs-codec-registry/#video-codec-registry). + - : A string containing a [valid codec string](https://w3c.github.io/webcodecs/codec_registry.html#video-codec-registry). - `description` {{Optional_Inline}} - : An {{jsxref("ArrayBuffer")}}, a {{jsxref("TypedArray")}}, or a {{jsxref("DataView")}} containing a sequence of codec-specific bytes, commonly known as "extradata". - `codedWidth` {{Optional_Inline}} diff --git a/files/en-us/web/api/videoframe/colorspace/index.md b/files/en-us/web/api/videoframe/colorspace/index.md index 2a84d39504fa1e1..0ef369314c165b0 100644 --- a/files/en-us/web/api/videoframe/colorspace/index.md +++ b/files/en-us/web/api/videoframe/colorspace/index.md @@ -21,7 +21,7 @@ The following example prints the `colorSpace` to the console. ```js const cnv = document.createElement("canvas"); // draw something on the canvas -// ... +// … const videoFrame = new VideoFrame(cnv, { timestamp: 0 }); console.log(videoFrame.colorSpace); ``` diff --git a/files/en-us/web/api/videoframe/videoframe/index.md b/files/en-us/web/api/videoframe/videoframe/index.md index 774cca4de0c22e7..e287423dae7ad78 100644 --- a/files/en-us/web/api/videoframe/videoframe/index.md +++ b/files/en-us/web/api/videoframe/videoframe/index.md @@ -121,24 +121,24 @@ The following examples are from the article [Video processing with WebCodecs](ht ```js const cnv = document.createElement("canvas"); // draw something on the canvas -// ... -let frame_from_canvas = new VideoFrame(cnv, { timestamp: 0 }); +// … +const frame_from_canvas = new VideoFrame(cnv, { timestamp: 0 }); ``` In the following example a `VideoFrame` is created from a {{jsxref("TypedArray")}}. ```js const pixelSize = 4; -let init = { +const init = { timestamp: 0, codedWidth: 320, codedHeight: 200, format: "RGBA", }; -let data = new Uint8Array(init.codedWidth * init.codedHeight * pixelSize); +const data = new Uint8Array(init.codedWidth * init.codedHeight * pixelSize); for (let x = 0; x < init.codedWidth; x++) { for (let y = 0; y < init.codedHeight; y++) { - let offset = (y * init.codedWidth + x) * pixelSize; + const offset = (y * init.codedWidth + x) * pixelSize; data[offset] = 0x7f; // Red data[offset + 1] = 0xff; // Green data[offset + 2] = 0xd4; // Blue @@ -146,7 +146,7 @@ for (let x = 0; x < init.codedWidth; x++) { } } init.transfer = [data.buffer]; -let frame = new VideoFrame(data, init); +const frame = new VideoFrame(data, init); ``` ## Specifications diff --git a/files/en-us/web/api/videotrackgenerator/index.md b/files/en-us/web/api/videotrackgenerator/index.md new file mode 100644 index 000000000000000..ee97df126b6681a --- /dev/null +++ b/files/en-us/web/api/videotrackgenerator/index.md @@ -0,0 +1,66 @@ +--- +title: VideoTrackGenerator +slug: Web/API/VideoTrackGenerator +page-type: web-api-interface +status: + - experimental +browser-compat: api.VideoTrackGenerator +--- + +{{APIRef("Insertable Streams for MediaStreamTrack API")}}{{SeeCompatTable}}{{AvailableInWorkers("dedicated")}} + +The **`VideoTrackGenerator`** interface of the [Insertable Streams for MediaStreamTrack API](/en-US/docs/Web/API/Insertable_Streams_for_MediaStreamTrack_API) has a {{domxref("WritableStream")}} property that acts as a {{domxref("MediaStreamTrack")}} source, by consuming a stream of {{domxref("VideoFrame")}}s as input. + +## Constructor + +- {{domxref("VideoTrackGenerator.VideoTrackGenerator", "VideoTrackGenerator()")}} {{Experimental_Inline}} + - : Creates a new `VideoTrackGenerator` object which accepts {{domxref("VideoFrame")}} objects. + +## Instance properties + +- {{domxref("VideoTrackGenerator.muted")}} {{Experimental_Inline}} + - : A Boolean property to temporarily halt or resume the generation of video frames in the output track. +- {{domxref("VideoTrackGenerator.track")}} {{Experimental_Inline}} + - : The output {{domxref("MediaStreamTrack")}}. +- {{domxref("VideoTrackGenerator.writable")}} {{Experimental_Inline}} + - : The input {{domxref("WritableStream")}}. + +## Examples + +The following example is from the article [Unbundling MediaStreamTrackProcessor and VideoTrackGenerator](https://blog.mozilla.org/webrtc/unbundling-mediastreamtrackprocessor-and-videotrackgenerator/). It [transfers](/en-US/docs/Web/API/Web_Workers_API/Transferable_objects) a camera {{domxref("MediaStreamTrack")}} to a worker for processing. The worker creates a pipeline that applies a sepia tone filter to the video frames and mirrors them. The pipeline culminates in a `VideoTrackGenerator` whose {{domxref("MediaStreamTrack")}} is transferred back and played. The media now flows in real time through the transform off the {{Glossary("main thread")}}. + +```js +const stream = await navigator.mediaDevices.getUserMedia({ video: true }); +const [track] = stream.getVideoTracks(); +const worker = new Worker("worker.js"); +worker.postMessage({ track }, [track]); +const { data } = await new Promise((r) => { + worker.onmessage = r; +}); +video.srcObject = new MediaStream([data.track]); +``` + +worker.js: + +```js +onmessage = async ({ data: { track } }) => { + const vtg = new VideoTrackGenerator(); + self.postMessage({ track: vtg.track }, [vtg.track]); + const { readable } = new MediaStreamTrackProcessor({ track }); + await readable + .pipeThrough(new TransformStream({ transform })) + .pipeTo(vtg.writable); +}; +``` + +## Specifications + +{{Specifications}} + +## Browser compatibility + +{{Compat}} + +## See also + +- {{domxref("MediaStreamTrackProcessor")}} diff --git a/files/en-us/web/api/videotrackgenerator/muted/index.md b/files/en-us/web/api/videotrackgenerator/muted/index.md new file mode 100644 index 000000000000000..f2b3f0be3025123 --- /dev/null +++ b/files/en-us/web/api/videotrackgenerator/muted/index.md @@ -0,0 +1,39 @@ +--- +title: "VideoTrackGenerator: muted property" +short-title: muted +slug: Web/API/VideoTrackGenerator/muted +page-type: web-api-instance-property +status: + - experimental +browser-compat: api.VideoTrackGenerator.muted +--- + +{{APIRef("Insertable Streams for MediaStreamTrack API")}}{{SeeCompatTable}} + +The **`muted`** Boolean property of the {{domxref("VideoTrackGenerator")}} interface can be used to temporarily halt or resume the generation of video frames in the output track. + +## Value + +A boolean. + +## Examples + +To pause production of video frames: + +```js +videoTrackGenerator.muted = true; +``` + +To resume production of video frames: + +```js +videoTrackGenerator.muted = false; +``` + +## Specifications + +{{Specifications}} + +## Browser compatibility + +{{Compat}} diff --git a/files/en-us/web/api/videotrackgenerator/track/index.md b/files/en-us/web/api/videotrackgenerator/track/index.md new file mode 100644 index 000000000000000..ddab1b88ff68576 --- /dev/null +++ b/files/en-us/web/api/videotrackgenerator/track/index.md @@ -0,0 +1,29 @@ +--- +title: "VideoTrackGenerator: track property" +short-title: track +slug: Web/API/VideoTrackGenerator/track +page-type: web-api-instance-property +status: + - experimental +browser-compat: api.VideoTrackGenerator.track +--- + +{{APIRef("Insertable Streams for MediaStreamTrack API")}}{{SeeCompatTable}} + +The **`track`** property of the {{domxref("VideoTrackGenerator")}} interface returns a {{domxref("MediaStreamTrack")}}. {{domxref("VideoFrame")}}s written to {{domxref("VideoTrackGenerator.writable")}} will be generated in this track. + +## Value + +A video {{domxref("MediaStreamTrack")}}. + +## Examples + +See the [Insertable Streams for MediaStreamTrack API](/en-US/docs/Web/API/Insertable_Streams_for_MediaStreamTrack_API#examples) for an example. + +## Specifications + +{{Specifications}} + +## Browser compatibility + +{{Compat}} diff --git a/files/en-us/web/api/videotrackgenerator/videotrackgenerator/index.md b/files/en-us/web/api/videotrackgenerator/videotrackgenerator/index.md new file mode 100644 index 000000000000000..8f56830e2457876 --- /dev/null +++ b/files/en-us/web/api/videotrackgenerator/videotrackgenerator/index.md @@ -0,0 +1,39 @@ +--- +title: "VideoTrackGenerator: VideoTrackGenerator() constructor" +short-title: VideoTrackGenerator() +slug: Web/API/VideoTrackGenerator/VideoTrackGenerator +page-type: web-api-constructor +status: + - experimental +browser-compat: api.VideoTrackGenerator.VideoTrackGenerator +--- + +{{APIRef("Insertable Streams for MediaStreamTrack API")}}{{SeeCompatTable}} + +The **`VideoTrackGenerator()`** constructor creates a new {{domxref("VideoTrackGenerator")}} object which consumes a stream of media frames and exposes a {{domxref("MediaStreamTrack")}}. + +## Syntax + +```js-nolint +new VideoTrackGenerator() +``` + +## Examples + +In the following example a new video `VideoTrackGenerator` is created. + +```js +const trackGenerator = new VideoTrackGenerator(); +``` + +## Specifications + +{{Specifications}} + +## Browser compatibility + +{{Compat}} + +## See also + +- [Insertable streams for MediaStreamTrack](https://developer.chrome.com/docs/capabilities/web-apis/mediastreamtrack-insertable-media-processing) diff --git a/files/en-us/web/api/videotrackgenerator/writable/index.md b/files/en-us/web/api/videotrackgenerator/writable/index.md new file mode 100644 index 000000000000000..59f22eb78402edb --- /dev/null +++ b/files/en-us/web/api/videotrackgenerator/writable/index.md @@ -0,0 +1,29 @@ +--- +title: "VideoTrackGenerator: writable property" +short-title: writable +slug: Web/API/VideoTrackGenerator/writable +page-type: web-api-instance-property +status: + - experimental +browser-compat: api.VideoTrackGenerator.writable +--- + +{{APIRef("Insertable Streams for MediaStreamTrack API")}}{{SeeCompatTable}} + +The **`writable`** property of the {{domxref("VideoTrackGenerator")}} interface returns a {{domxref("WritableStream")}}. This allows the writing of {{domxref("VideoFrame")}}s to the {{domxref("VideoTrackGenerator.track")}}. + +## Value + +A {{domxref("WritableStream")}} of {{domxref("VideoFrame")}}s. + +## Examples + +See the [Insertable Streams for MediaStreamTrack API](/en-US/docs/Web/API/Insertable_Streams_for_MediaStreamTrack_API#examples) for an example. + +## Specifications + +{{Specifications}} + +## Browser compatibility + +{{Compat}} diff --git a/files/en-us/web/api/videotracklist/addtrack_event/index.md b/files/en-us/web/api/videotracklist/addtrack_event/index.md index 3a08ad8598afbca..597227b082f3379 100644 --- a/files/en-us/web/api/videotracklist/addtrack_event/index.md +++ b/files/en-us/web/api/videotracklist/addtrack_event/index.md @@ -14,10 +14,10 @@ The `addtrack` event is fired when a video track is added to a [`VideoTrackList` Use the event name in methods like {{domxref("EventTarget.addEventListener", "addEventListener()")}}, or set an event handler property. -```js -addEventListener("addtrack", (event) => {}); +```js-nolint +addEventListener("addtrack", (event) => { }) -onaddtrack = (event) => {}; +onaddtrack = (event) => { } ``` ## Event type diff --git a/files/en-us/web/api/videotracklist/change_event/index.md b/files/en-us/web/api/videotracklist/change_event/index.md index a629f92d974e706..e209c786f998711 100644 --- a/files/en-us/web/api/videotracklist/change_event/index.md +++ b/files/en-us/web/api/videotracklist/change_event/index.md @@ -14,10 +14,10 @@ The `change` event is fired when a video track is made active or inactive, for e Use the event name in methods like {{domxref("EventTarget.addEventListener", "addEventListener()")}}, or set an event handler property. -```js -addEventListener("change", (event) => {}); +```js-nolint +addEventListener("change", (event) => { }) -onchange = (event) => {}; +onchange = (event) => { } ``` ## Event type diff --git a/files/en-us/web/api/videotracklist/removetrack_event/index.md b/files/en-us/web/api/videotracklist/removetrack_event/index.md index e7c7d2e172ed2d8..a5fea6b244780ee 100644 --- a/files/en-us/web/api/videotracklist/removetrack_event/index.md +++ b/files/en-us/web/api/videotracklist/removetrack_event/index.md @@ -14,10 +14,10 @@ The `removetrack` event is fired when a video track is removed from a [`VideoTra Use the event name in methods like {{domxref("EventTarget.addEventListener", "addEventListener()")}}, or set an event handler property. -```js -addEventListener("removetrack", (event) => {}); +```js-nolint +addEventListener("removetrack", (event) => { }) -onremovetrack = (event) => {}; +onremovetrack = (event) => { } ``` ## Event type diff --git a/files/en-us/web/api/view_transition_api/index.md b/files/en-us/web/api/view_transition_api/index.md index e3a3b2d3c848f01..6d10f6f00dc414f 100644 --- a/files/en-us/web/api/view_transition_api/index.md +++ b/files/en-us/web/api/view_transition_api/index.md @@ -24,7 +24,7 @@ However, creating view transitions on the web has historically been difficult: - Stop accidental user interactions with the old content from causing problems. - Remove the old content once the transition is complete. Accessibility issues like loss of reading position, focus confusion, and strange live region announcement behavior can also result from having the new and old content both present in the DOM at once. -- Cross-document view transitions (i.e. across navigations between different pages in MPAs) have historically been impossible. +- Cross-document view transitions (i.e., across navigations between different pages in MPAs) have historically been impossible. The View Transition API provides an easy way of handling the required view changes and transition animations for both the above use cases. @@ -35,7 +35,7 @@ See [Using the View Transition API](/en-US/docs/Web/API/View_Transition_API/Usin ## Interfaces - {{domxref("ViewTransition")}} - - : Represents a view transition, and provides functionality to react to the transition reaching different states (e.g. ready to run the animation, or animation finished) or skip the transition altogether. + - : Represents a view transition, and provides functionality to react to the transition reaching different states (e.g., ready to run the animation, or animation finished) or skip the transition altogether. ## Extensions to other interfaces @@ -52,7 +52,7 @@ See [Using the View Transition API](/en-US/docs/Web/API/View_Transition_API/Usin ## HTML additions -- [`<link rel="expect">`](/en-US/docs/Web/HTML/Attributes/rel#expect) +- [`<link rel="expect">`](/en-US/docs/Web/HTML/Reference/Attributes/rel#expect) - : Identifies the most critical content in the associated document for the user's initial view of the page. Document rendering will be blocked until the critical content has been parsed, ensuring a consistent first paint — and therefore, view transition — across all supporting browsers. ## CSS additions @@ -66,18 +66,20 @@ See [Using the View Transition API](/en-US/docs/Web/API/View_Transition_API/Usin - {{cssxref("view-transition-name")}} - : Provides the selected element with a separate identifying name and causes it to participate in a separate view transition from the root view transition — or no view transition if the `none` value is specified. +- {{cssxref("view-transition-class")}} + - : Provides an additional method of styling to selected elements that have a `view-transition-name`. ### Pseudo-elements - {{cssxref("::view-transition")}} - : The root of the view transitions overlay, which contains all view transitions and sits over the top of all other page content. -- {{cssxref("::view-transition-group", "::view-transition-group()")}} +- {{cssxref("::view-transition-group()")}} - : The root of a single view transition. -- {{cssxref("::view-transition-image-pair", "::view-transition-image-pair()")}} +- {{cssxref("::view-transition-image-pair()")}} - : The container for a view transition's old and new views — before and after the transition. -- {{cssxref("::view-transition-old", "::view-transition-old()")}} +- {{cssxref("::view-transition-old()")}} - : A static snapshot of the old view, before the transition. -- {{cssxref("::view-transition-new", "::view-transition-new()")}} +- {{cssxref("::view-transition-new()")}} - : A live representation of the new view, after the transition. ## Examples @@ -99,4 +101,4 @@ See [Using the View Transition API](/en-US/docs/Web/API/View_Transition_API/Usin - [Smooth transitions with the View Transition API](https://developer.chrome.com/docs/web-platform/view-transitions/) on developer.chrome.com (2024) - [View Transition API: Creating Smooth Page Transitions](https://stackdiary.com/view-transitions-api/) on stackdiary.com (2023) -- [View Transitions API: Single Page Apps Without a Framework](https://www.debugbear.com/blog/view-transitions-spa-without-framework) on www.debugbear.com (2024) +- [View Transitions API: Single Page Apps Without a Framework](https://www.debugbear.com/blog/view-transitions-spa-without-framework) on DebugBear (2024) diff --git a/files/en-us/web/api/view_transition_api/using/index.md b/files/en-us/web/api/view_transition_api/using/index.md index 9c40816c5b71fa9..efc06ec8e4d3cc1 100644 --- a/files/en-us/web/api/view_transition_api/using/index.md +++ b/files/en-us/web/api/view_transition_api/using/index.md @@ -49,14 +49,14 @@ To handle creating the outbound and inbound transition animations, the API const ``` > [!NOTE] -> A {{cssxref("::view-transition-group")}} subtree is created for every captured `view-transition-name`. +> A {{cssxref("::view-transition-group()")}} subtree is created for every captured `view-transition-name`. In the case of same-document transitions (SPAs), the pseudo-element tree is made available in the document. In the case of cross-document transitions (MPAs), the pseudo-element tree is made available in the destination document only. The most interesting parts of the tree structure are as follows: - {{cssxref("::view-transition")}} is the root of view transitions overlay, which contains all view transition snapshot groups and sits over the top of all other page content. -- A {{cssxref("::view-transition-group")}} acts as a container for each view transition snapshot group. The `root` argument specifies the default snapshot group — the view transition animation will apply to the snapshot whose `view-transition-name` is `root`. By default, this is the {{cssxref(":root")}} element, because the default browser styles define this: +- A {{cssxref("::view-transition-group()")}} acts as a container for each view transition snapshot group. The `root` argument specifies the default snapshot group — the view transition animation will apply to the snapshot whose `view-transition-name` is `root`. By default, this is the {{cssxref(":root")}} element, because the default browser styles define this: ```css :root { @@ -66,13 +66,13 @@ The most interesting parts of the tree structure are as follows: Be aware however that page authors can change this by unsetting the above, and setting `view-transition-name: root` on a different element. -- {{cssxref("::view-transition-old")}} targets the static snapshot of the old page element, and {{cssxref("::view-transition-new")}} targets the live snapshot of the new page element. Both of these render as replaced content, in the same manner as an {{htmlelement("img")}} or {{htmlelement("video")}}, meaning that they can be styled with handy properties like {{cssxref("object-fit")}} and {{cssxref("object-position")}}. +- {{cssxref("::view-transition-old()")}} targets the static snapshot of the old page element, and {{cssxref("::view-transition-new()")}} targets the live snapshot of the new page element. Both of these render as replaced content, in the same manner as an {{htmlelement("img")}} or {{htmlelement("video")}}, meaning that they can be styled with handy properties like {{cssxref("object-fit")}} and {{cssxref("object-position")}}. > [!NOTE] -> It is possible to target different DOM elements with different custom view transition animations by setting a different {{cssxref("view-transition-name")}} on each one. In such cases, a `::view-transition-group` is created for each one. See [Different animations for different elements](#different_animations_for_different_elements) for an example. +> It is possible to target different DOM elements with different custom view transition animations by setting a different {{cssxref("view-transition-name")}} on each one. In such cases, a `::view-transition-group()` is created for each one. See [Different animations for different elements](#different_animations_for_different_elements) for an example. > [!NOTE] -> As you'll see later, to customize the outbound and inbound animations you need to target the {{cssxref("::view-transition-old")}} and {{cssxref("::view-transition-new")}} pseudo-elements with your animations, respectively. +> As you'll see later, to customize the outbound and inbound animations you need to target the {{cssxref("::view-transition-old()")}} and {{cssxref("::view-transition-new()")}} pseudo-elements with your animations, respectively. ## Creating a basic view transition @@ -130,7 +130,7 @@ Most appearance transitions are given a default smooth cross-fade animation, as - `height` and `width` transitions have a smooth scaling animation applied. - `position` and `transform` transitions have a smooth movement animation applied. -You can modify the default animations in any way you want using regular CSS — target the "from" animation with {{cssxref("::view-transition-old")}}, and the "to" animation with {{cssxref("::view-transition-new")}}. +You can modify the default animations in any way you want using regular CSS — target the "from" animation with {{cssxref("::view-transition-old()")}}, and the "to" animation with {{cssxref("::view-transition-new()")}}. For example, to change the speed of both: @@ -217,7 +217,7 @@ With this CSS applied, the generated pseudo-element tree will now look like this The existence of the second set of pseudo-elements allows separate view transition styling to be applied just to the `<figcaption>`. The different old and new view captures are handled separately from one another. > [!NOTE] -> The value of `view-transition-name` can be anything you want except for `none` — the `none` value specifically means that the element will not participate in a view transition. +> The value of `view-transition-name` is a unique {{cssxref("custom-ident")}}; it can be any identifier that wouldn't be misinterpreted as a keyword. The keyword `none` is not a valid name, as that value means the element will not participate in any view transitions. Also avoid `auto`, as it's being discussed as a way to [determine `view-transition-name` automatically](https://drafts.csswg.org/css-view-transitions-2/#auto-vt-name). > > `view-transition-name` values must also be unique. If two rendered elements have the same `view-transition-name` at the same time, {{domxref("ViewTransition.ready")}} will reject and the transition will be skipped. @@ -283,7 +283,7 @@ figcaption { } ``` -This works because, by default, `::view-transition-group` transitions `width` and `height` between the old and new views with a smooth scale. We just needed to set a fixed `height` on both states to make it work. +This works because, by default, `::view-transition-group()` transitions `width` and `height` between the old and new views with a smooth scale. We just needed to set a fixed `height` on both states to make it work. > **Note:** [Smooth transitions with the View Transition API](https://developer.chrome.com/docs/web-platform/view-transitions/) contains several other customization examples. @@ -489,9 +489,9 @@ Before running a cross-document transition, you ideally want to wait until the s 2. Critical scripts are loaded and run. 3. The HTML visible for the user's initial view of the page has been parsed, so it renders consistently. -Styles are render blocked by default, and scripts can be render blocked using the [`blocking="render"`](/en-US/docs/Web/HTML/Element/script#blocking) attribute. +Styles are render blocked by default, and scripts can be render blocked using the [`blocking="render"`](/en-US/docs/Web/HTML/Reference/Elements/script#blocking) attribute. -To ensure that your initial HTML has been parsed and will always render consistently before the transition animation runs, you can use [`<link rel="expect">`](/en-US/docs/Web/HTML/Attributes/rel#expect). In this element, you include the following attributes: +To ensure that your initial HTML has been parsed and will always render consistently before the transition animation runs, you can use [`<link rel="expect">`](/en-US/docs/Web/HTML/Reference/Attributes/rel#expect). In this element, you include the following attributes: - `rel="expect"` to indicate that you want to use this `<link>` element to render block some HTML on the page. - `href="#element-id"` to indicate the ID of the element you want to render block. @@ -528,7 +528,7 @@ Let's explore what this looks like with an example HTML document: The result is that document rendering is blocked until the lead content `<div>` has been parsed, ensuring a consistent view transition. -You can also specify a [`media`](/en-US/docs/Web/HTML/Element/link#media) attribute on `<link rel="expect">` elements. For example, you might want to block rendering on a smaller amount of content when loading the page on a narrow-screen device, than on a wide-screen device. This makes sense — on a mobile, less content will be visible when the page first loads than in the case of a desktop. +You can also specify a [`media`](/en-US/docs/Web/HTML/Reference/Elements/link#media) attribute on `<link rel="expect">` elements. For example, you might want to block rendering on a smaller amount of content when loading the page on a narrow-screen device, than on a wide-screen device. This makes sense — on a mobile, less content will be visible when the page first loads than in the case of a desktop. This could be achieved with the following HTML: diff --git a/files/en-us/web/api/viewtransition/index.md b/files/en-us/web/api/viewtransition/index.md index 60af4ea4848a24c..294c3b42f7090ed 100644 --- a/files/en-us/web/api/viewtransition/index.md +++ b/files/en-us/web/api/viewtransition/index.md @@ -7,7 +7,7 @@ browser-compat: api.ViewTransition {{APIRef("View Transition API")}} -The **`ViewTransition`** interface of the {{domxref("View Transition API", "View Transition API", "", "nocode")}} represents an active view transition, and provides functionality to react to the transition reaching different states (e.g. ready to run the animation, or animation finished) or skip the transition altogether. +The **`ViewTransition`** interface of the {{domxref("View Transition API", "View Transition API", "", "nocode")}} represents an active view transition, and provides functionality to react to the transition reaching different states (e.g., ready to run the animation, or animation finished) or skip the transition altogether. This object type is made available in the following ways: diff --git a/files/en-us/web/api/virtualkeyboard/geometrychange_event/index.md b/files/en-us/web/api/virtualkeyboard/geometrychange_event/index.md index 49521dd3e19e9cf..e631eec51c92dcd 100644 --- a/files/en-us/web/api/virtualkeyboard/geometrychange_event/index.md +++ b/files/en-us/web/api/virtualkeyboard/geometrychange_event/index.md @@ -19,10 +19,10 @@ The `geometrychange` event is useful to detect when the virtual keyboard appears Use the event name in methods like {{domxref("EventTarget.addEventListener", "addEventListener()")}}, or set an event handler property. -```js -navigator.virtualKeyboard.addEventListener("geometrychange", (event) => {}); +```js-nolint +addEventListener("geometrychange", (event) => { }) -navigator.virtualKeyboard.ongeometrychange = (event) => {}; +ongeometrychange = (event) => { } ``` ## Event type diff --git a/files/en-us/web/api/virtualkeyboard/hide/index.md b/files/en-us/web/api/virtualkeyboard/hide/index.md index 68d1cca0e017d2c..8241a1fccbd78a4 100644 --- a/files/en-us/web/api/virtualkeyboard/hide/index.md +++ b/files/en-us/web/api/virtualkeyboard/hide/index.md @@ -12,7 +12,7 @@ browser-compat: api.VirtualKeyboard.hide The **`hide()`** method of the {{domxref("VirtualKeyboard")}} interface programmatically hides the on-screen virtual keyboard. This is useful when the page needs to implement its own virtual keyboard logic by using the {{domxref("VirtualKeyboard_API", "VirtualKeyboard API", "", "nocode")}}. -This method only works if the currently-focused element's [`virtualKeyboardPolicy`](/en-US/docs/Web/HTML/Global_attributes/virtualkeyboardpolicy) attribute is set to `manual` and [`inputmode`](/en-US/docs/Web/HTML/Global_attributes/inputmode) isn't set to `none`. +This method only works if the currently-focused element's [`virtualKeyboardPolicy`](/en-US/docs/Web/HTML/Reference/Global_attributes/virtualkeyboardpolicy) attribute is set to `manual` and [`inputmode`](/en-US/docs/Web/HTML/Reference/Global_attributes/inputmode) isn't set to `none`. The `hide()` method always returns `undefined` and triggers a {{domxref("VirtualKeyboard.geometrychange_event", "geometrychange")}} event. @@ -37,26 +37,27 @@ The code snippet below shows how to use the `virtualkeyboardpolicy` attribute to ```html <div contenteditable virtualkeyboardpolicy="manual" id="editor"></div> <button id="edit-button">Edit</button> -<script> - if ("virtualKeyboard" in navigator) { - const editor = document.getElementById("editor"); - const editButton = document.getElementById("edit-button"); - let isEditing = false; - - editButton.addEventListener("click", () => { - if (isEditing) { - navigator.virtualKeyboard.hide(); - editButton.textContent = "Edit"; - } else { - editor.focus(); - navigator.virtualKeyboard.show(); - editButton.textContent = "Save changes"; - } - - isEditing = !isEditing; - }); - } -</script> +``` + +```js +if ("virtualKeyboard" in navigator) { + const editor = document.getElementById("editor"); + const editButton = document.getElementById("edit-button"); + let isEditing = false; + + editButton.addEventListener("click", () => { + if (isEditing) { + navigator.virtualKeyboard.hide(); + editButton.textContent = "Edit"; + } else { + editor.focus(); + navigator.virtualKeyboard.show(); + editButton.textContent = "Save changes"; + } + + isEditing = !isEditing; + }); +} ``` ## Specifications diff --git a/files/en-us/web/api/virtualkeyboard/show/index.md b/files/en-us/web/api/virtualkeyboard/show/index.md index edf87254466d861..ab5b4bbac53d9dd 100644 --- a/files/en-us/web/api/virtualkeyboard/show/index.md +++ b/files/en-us/web/api/virtualkeyboard/show/index.md @@ -12,7 +12,7 @@ browser-compat: api.VirtualKeyboard.show The **`show()`** method of the {{domxref("VirtualKeyboard")}} interface programmatically shows the on-screen virtual keyboard. This is useful when the page needs to implement its own virtual keyboard logic, especially when using the `virtualkeyboardpolicy` attribute on `contenteditable` elements as explained in [Control the virtual keyboard on `contenteditable` elements](/en-US/docs/Web/API/VirtualKeyboard_API#control_the_virtual_keyboard_on_contenteditable_elements). -This method only works if the currently-focused element is a form control — such as an {{htmlelement("input")}} or {{htmlelement("textarea")}} element — or if the focused element is [`contenteditable`](/en-US/docs/Web/HTML/Global_attributes/contenteditable), and the currently-focused element's [`virtualKeyboardPolicy`](/en-US/docs/Web/HTML/Global_attributes/virtualkeyboardpolicy) attribute is set to `manual` and [`inputmode`](/en-US/docs/Web/HTML/Global_attributes/inputmode) isn't set to `none`. +This method only works if the currently-focused element is a form control — such as an {{htmlelement("input")}} or {{htmlelement("textarea")}} element — or if the focused element is [`contenteditable`](/en-US/docs/Web/HTML/Reference/Global_attributes/contenteditable), and the currently-focused element's [`virtualKeyboardPolicy`](/en-US/docs/Web/HTML/Reference/Global_attributes/virtualkeyboardpolicy) attribute is set to `manual` and [`inputmode`](/en-US/docs/Web/HTML/Reference/Global_attributes/inputmode) isn't set to `none`. The `show()` method always returns `undefined` and triggers a {{domxref("VirtualKeyboard.geometrychange_event", "geometrychange")}} event. @@ -34,29 +34,30 @@ Undefined. The code snippet below shows how to use the `virtualkeyboardpolicy` attribute to prevent the browser from showing the virtual keyboard on click or tap. The code also uses the `navigator.virtualKeyboard.show()` and `navigator.virtualKeyboard.hide()` methods to show and hide the virtual keyboard when a button is clicked: -```js +```html <div contenteditable virtualkeyboardpolicy="manual" id="editor"></div> <button id="edit-button">Edit</button> -<script> - if ("virtualKeyboard" in navigator) { - const editor = document.getElementById("editor"); - const editButton = document.getElementById("edit-button"); - let isEditing = false; - - editButton.addEventListener("click", () => { - if (isEditing) { - navigator.virtualKeyboard.hide(); - editButton.textContent = "Edit"; - } else { - editor.focus(); - navigator.virtualKeyboard.show(); - editButton.textContent = "Save changes"; - } - - isEditing = !isEditing; - }); - } -</script> +``` + +```js +if ("virtualKeyboard" in navigator) { + const editor = document.getElementById("editor"); + const editButton = document.getElementById("edit-button"); + let isEditing = false; + + editButton.addEventListener("click", () => { + if (isEditing) { + navigator.virtualKeyboard.hide(); + editButton.textContent = "Edit"; + } else { + editor.focus(); + navigator.virtualKeyboard.show(); + editButton.textContent = "Save changes"; + } + + isEditing = !isEditing; + }); +} ``` ## Specifications diff --git a/files/en-us/web/api/virtualkeyboard_api/index.md b/files/en-us/web/api/virtualkeyboard_api/index.md index be7ebf5a586fd0c..d59f93cc78588b4 100644 --- a/files/en-us/web/api/virtualkeyboard_api/index.md +++ b/files/en-us/web/api/virtualkeyboard_api/index.md @@ -31,7 +31,7 @@ The VirtualKeyboard API consists of three parts: - The {{domxref("VirtualKeyboard")}} interface, accessed through {{domxref('navigator.virtualKeyboard')}}, is used to opt out of the automatic virtual keyboard behavior, show or hide the virtual keyboard programmatically, as well as get the current position and size of the virtual keyboard. - The `keyboard-inset-*` CSS environment variables provide information about the virtual keyboard's position and size. -- The [`virtualkeyboardpolicy`](/en-US/docs/Web/HTML/Global_attributes/virtualkeyboardpolicy) attribute specifies whether the virtual keyboard should appear on `contenteditable` elements. +- The [`virtualkeyboardpolicy`](/en-US/docs/Web/HTML/Reference/Global_attributes/virtualkeyboardpolicy) attribute specifies whether the virtual keyboard should appear on `contenteditable` elements. ### Opt out of the automatic virtual keyboard behavior @@ -86,24 +86,25 @@ The code snippet below uses the `keyboard-inset-height` CSS variable to reserve ### Control the virtual keyboard on `contenteditable` elements -By default, elements using the [`contenteditable`](/en-US/docs/Web/HTML/Global_attributes/contenteditable) attribute also trigger the virtual keyboard when tapped or clicked. In certain situations, it may be desirable to prevent this behavior and instead show the virtual keyboard after a different event. +By default, elements using the [`contenteditable`](/en-US/docs/Web/HTML/Reference/Global_attributes/contenteditable) attribute also trigger the virtual keyboard when tapped or clicked. In certain situations, it may be desirable to prevent this behavior and instead show the virtual keyboard after a different event. -Set the [`virtualkeyboardpolicy`](/en-US/docs/Web/HTML/Global_attributes/virtualkeyboardpolicy) attribute to `manual` to prevent the default handling of the virtual keyboard in the browser, and instead handle it yourself by using the {{domxref("VirtualKeyboard")}} interface's `show()` and `hide()` methods. +Set the [`virtualkeyboardpolicy`](/en-US/docs/Web/HTML/Reference/Global_attributes/virtualkeyboardpolicy) attribute to `manual` to prevent the default handling of the virtual keyboard in the browser, and instead handle it yourself by using the {{domxref("VirtualKeyboard")}} interface's `show()` and `hide()` methods. The code snippet below shows how to use the `virtualkeyboardpolicy` attribute and the `navigator.virtualKeyboard.show()` method to show the virtual keyboard on double-click instead: ```html <div contenteditable virtualkeyboardpolicy="manual" id="editor"></div> -<script> - if ("virtualKeyboard" in navigator) { - navigator.virtualKeyboard.overlaysContent = true; +``` - const editor = document.getElementById("editor"); - editor.addEventListener("dblclick", () => { - navigator.virtualKeyboard.show(); - }); - } -</script> +```js +if ("virtualKeyboard" in navigator) { + navigator.virtualKeyboard.overlaysContent = true; + + const editor = document.getElementById("editor"); + editor.addEventListener("dblclick", () => { + navigator.virtualKeyboard.show(); + }); +} ``` ## Interfaces diff --git a/files/en-us/web/api/visibilitystateentry/index.md b/files/en-us/web/api/visibilitystateentry/index.md index 0a15e61aaad458f..eebe1fe89091348 100644 --- a/files/en-us/web/api/visibilitystateentry/index.md +++ b/files/en-us/web/api/visibilitystateentry/index.md @@ -15,8 +15,8 @@ This can be used to pinpoint visibility changes on the performance timeline, and There are two key visibility state change times that this API reports on: -- `visible`: The time when the page becomes visible (i.e. when its tab moves into the foreground). -- `hidden`: The time when the pages become hidden (i.e. when its tab moves into the background). +- `visible`: The time when the page becomes visible (i.e., when its tab moves into the foreground). +- `hidden`: The time when the pages become hidden (i.e., when its tab moves into the background). The performance timeline will always have a `"visibility-state"` entry with a `startTime` of `0` and a `name` representing the initial page visibility state. diff --git a/files/en-us/web/api/visualviewport/resize_event/index.md b/files/en-us/web/api/visualviewport/resize_event/index.md index c791c1091325863..a54a3f17cf27d3e 100644 --- a/files/en-us/web/api/visualviewport/resize_event/index.md +++ b/files/en-us/web/api/visualviewport/resize_event/index.md @@ -14,10 +14,10 @@ The **`resize`** event of the {{domxref("VisualViewport")}} interface is fired w Use the event name in methods like {{domxref("EventTarget.addEventListener", "addEventListener()")}}, or set an event handler property. -```js -addEventListener("resize", (event) => {}); +```js-nolint +addEventListener("resize", (event) => { }) -onresize = (event) => {}; +onresize = (event) => { } ``` ## Event type diff --git a/files/en-us/web/api/visualviewport/scroll_event/index.md b/files/en-us/web/api/visualviewport/scroll_event/index.md index 08ad0204e0e91a9..dcaf4c2444c18b0 100644 --- a/files/en-us/web/api/visualviewport/scroll_event/index.md +++ b/files/en-us/web/api/visualviewport/scroll_event/index.md @@ -14,10 +14,10 @@ The **`scroll`** event of the {{domxref("VisualViewport")}} interface is fired w Use the event name in methods like {{domxref("EventTarget.addEventListener", "addEventListener()")}}, or set an event handler property. -```js -addEventListener("scroll", (event) => {}); +```js-nolint +addEventListener("scroll", (event) => { }) -onscroll = (event) => {}; +onscroll = (event) => { } ``` ## Event type diff --git a/files/en-us/web/api/visualviewport/scrollend_event/index.md b/files/en-us/web/api/visualviewport/scrollend_event/index.md index d70e89503642cfd..432f660ebdb34da 100644 --- a/files/en-us/web/api/visualviewport/scrollend_event/index.md +++ b/files/en-us/web/api/visualviewport/scrollend_event/index.md @@ -14,10 +14,10 @@ The **`scrollend`** event of the {{domxref("VisualViewport")}} interface is fire Use the event name in methods like {{domxref("EventTarget.addEventListener", "addEventListener()")}}, or set an event handler property. -```js -addEventListener("scrollend", (event) => {}); +```js-nolint +addEventListener("scrollend", (event) => { }) -onscrollend = (event) => {}; +onscrollend = (event) => { } ``` ## Event type diff --git a/files/en-us/web/api/vrdisplay/depthfar/index.md b/files/en-us/web/api/vrdisplay/depthfar/index.md index e67e80b0827022c..2ea25114aac8655 100644 --- a/files/en-us/web/api/vrdisplay/depthfar/index.md +++ b/files/en-us/web/api/vrdisplay/depthfar/index.md @@ -11,7 +11,7 @@ browser-compat: api.VRDisplay.depthFar {{APIRef("WebVR API")}}{{Deprecated_Header}}{{Non-standard_Header}} -The **`depthFar`** property of the {{domxref("VRDisplay")}} interface gets and sets the z-depth defining the far plane of the [eye view frustum](https://en.wikipedia.org/wiki/Viewing_frustum), i.e. the furthest viewable boundary of the scene. +The **`depthFar`** property of the {{domxref("VRDisplay")}} interface gets and sets the z-depth defining the far plane of the [eye view frustum](https://en.wikipedia.org/wiki/Viewing_frustum), i.e., the furthest viewable boundary of the scene. > [!NOTE] > This property was part of the old [WebVR API](https://immersive-web.github.io/webvr/spec/1.1/). It has been superseded by the [WebXR Device API](https://immersive-web.github.io/webxr/). diff --git a/files/en-us/web/api/vrdisplay/depthnear/index.md b/files/en-us/web/api/vrdisplay/depthnear/index.md index b489695302c46fa..b944cb41b8e4429 100644 --- a/files/en-us/web/api/vrdisplay/depthnear/index.md +++ b/files/en-us/web/api/vrdisplay/depthnear/index.md @@ -11,7 +11,7 @@ browser-compat: api.VRDisplay.depthNear {{APIRef("WebVR API")}}{{Deprecated_Header}}{{Non-standard_Header}} -The **`depthNear`** property of the {{domxref("VRDisplay")}} interface gets and sets the z-depth defining the near plane of the [eye view frustum](https://en.wikipedia.org/wiki/Viewing_frustum), i.e. the nearest viewable boundary of the scene. +The **`depthNear`** property of the {{domxref("VRDisplay")}} interface gets and sets the z-depth defining the near plane of the [eye view frustum](https://en.wikipedia.org/wiki/Viewing_frustum), i.e., the nearest viewable boundary of the scene. > [!NOTE] > This property was part of the old [WebVR API](https://immersive-web.github.io/webvr/spec/1.1/). It has been superseded by the [WebXR Device API](https://immersive-web.github.io/webxr/). diff --git a/files/en-us/web/api/vrdisplay/geteyeparameters/index.md b/files/en-us/web/api/vrdisplay/geteyeparameters/index.md index 67d989edae86ad1..5023e603e074adf 100644 --- a/files/en-us/web/api/vrdisplay/geteyeparameters/index.md +++ b/files/en-us/web/api/vrdisplay/geteyeparameters/index.md @@ -29,7 +29,7 @@ getEyeParameters(whichEye) ### Return value -A {{domxref("VREyeParameters")}} object, or null if the VR is not able to present content (e.g. {{domxref("VRDisplayCapabilities.canPresent")}} returns `false`). +A {{domxref("VREyeParameters")}} object, or null if the VR is not able to present content (e.g., {{domxref("VRDisplayCapabilities.canPresent")}} returns `false`). ## Examples diff --git a/files/en-us/web/api/vrdisplay/index.md b/files/en-us/web/api/vrdisplay/index.md index bd252ad4d186177..a4ee166dac08ddb 100644 --- a/files/en-us/web/api/vrdisplay/index.md +++ b/files/en-us/web/api/vrdisplay/index.md @@ -22,9 +22,9 @@ An array of all connected VR Devices can be returned by invoking the {{domxref(" - {{domxref("VRDisplay.capabilities")}} {{ReadOnlyInline}} {{Deprecated_Inline}} {{Non-standard_Inline}} - : Returns a {{domxref("VRDisplayCapabilities")}} object that indicates the various capabilities of the `VRDisplay`. - {{domxref("VRDisplay.depthFar")}} {{Deprecated_Inline}} {{Non-standard_Inline}} - - : Gets and sets the z-depth defining the far plane of the [eye view frustum](https://en.wikipedia.org/wiki/Viewing_frustum), i.e. the furthest viewable boundary of the scene. + - : Gets and sets the z-depth defining the far plane of the [eye view frustum](https://en.wikipedia.org/wiki/Viewing_frustum), i.e., the furthest viewable boundary of the scene. - {{domxref("VRDisplay.depthNear")}} {{Deprecated_Inline}} {{Non-standard_Inline}} - - : Gets and sets the z-depth defining the near plane of the [eye view frustum](https://en.wikipedia.org/wiki/Viewing_frustum), i.e. the nearest viewable boundary of the scene. + - : Gets and sets the z-depth defining the near plane of the [eye view frustum](https://en.wikipedia.org/wiki/Viewing_frustum), i.e., the nearest viewable boundary of the scene. - {{domxref("VRDisplay.displayId")}} {{ReadOnlyInline}} {{Deprecated_Inline}} {{Non-standard_Inline}} - : Returns an identifier for this particular VRDisplay, which is also used as an association point in the [Gamepad API](/en-US/docs/Web/API/Gamepad_API) (see {{domxref("Gamepad.displayId")}}). - {{domxref("VRDisplay.displayName")}} {{ReadOnlyInline}} {{Deprecated_Inline}} {{Non-standard_Inline}} diff --git a/files/en-us/web/api/vrdisplaycapabilities/canpresent/index.md b/files/en-us/web/api/vrdisplaycapabilities/canpresent/index.md index cb7b22a4f488bc5..aea5c55d48b0c71 100644 --- a/files/en-us/web/api/vrdisplaycapabilities/canpresent/index.md +++ b/files/en-us/web/api/vrdisplaycapabilities/canpresent/index.md @@ -11,7 +11,7 @@ browser-compat: api.VRDisplayCapabilities.canPresent {{APIRef("WebVR API")}}{{Deprecated_Header}}{{Non-standard_Header}} -The **`canPresent`** read-only property of the {{domxref("VRDisplayCapabilities")}} interface returns a boolean value stating whether the VR display is capable of presenting content (e.g. through an HMD). +The **`canPresent`** read-only property of the {{domxref("VRDisplayCapabilities")}} interface returns a boolean value stating whether the VR display is capable of presenting content (e.g., through an HMD). > [!NOTE] > This property was part of the old [WebVR API](https://immersive-web.github.io/webvr/spec/1.1/). It has been superseded by the [WebXR Device API](https://immersive-web.github.io/webxr/). diff --git a/files/en-us/web/api/vrdisplaycapabilities/index.md b/files/en-us/web/api/vrdisplaycapabilities/index.md index 38b0e22a33f8769..5843ceb6c28f7f7 100644 --- a/files/en-us/web/api/vrdisplaycapabilities/index.md +++ b/files/en-us/web/api/vrdisplaycapabilities/index.md @@ -20,7 +20,7 @@ This interface is accessible through the {{domxref("VRDisplay.capabilities")}} p ## Instance properties - {{domxref("VRDisplayCapabilities.canPresent")}} {{Deprecated_Inline}} {{ReadOnlyInline}} {{Non-standard_Inline}} - - : Returns a boolean value stating whether the VR display is capable of presenting content (e.g. through an HMD). + - : Returns a boolean value stating whether the VR display is capable of presenting content (e.g., through an HMD). - {{domxref("VRDisplayCapabilities.hasExternalDisplay")}} {{Deprecated_Inline}} {{ReadOnlyInline}} {{Non-standard_Inline}} - : Returns a boolean value stating whether the VR display is separate from the device's primary display. - {{domxref("VRDisplayCapabilities.hasOrientation")}} {{Deprecated_Inline}} {{ReadOnlyInline}} {{Non-standard_Inline}} @@ -28,7 +28,7 @@ This interface is accessible through the {{domxref("VRDisplay.capabilities")}} p - {{domxref("VRDisplayCapabilities.hasPosition")}} {{Deprecated_Inline}} {{ReadOnlyInline}} {{Non-standard_Inline}} - : Returns a boolean value stating whether the VR display can track and return position information. - {{domxref("VRDisplayCapabilities.maxLayers")}} {{Deprecated_Inline}} {{ReadOnlyInline}} {{Non-standard_Inline}} - - : Returns a number indicating the maximum number of {{domxref("VRLayerInit")}}s that the VR display can present at once (e.g. the maximum length of the array that {{domxref("VRDisplay.requestPresent()")}} can accept.) + - : Returns a number indicating the maximum number of {{domxref("VRLayerInit")}}s that the VR display can present at once (e.g., the maximum length of the array that {{domxref("VRDisplay.requestPresent()")}} can accept.) ## Examples diff --git a/files/en-us/web/api/vrdisplaycapabilities/maxlayers/index.md b/files/en-us/web/api/vrdisplaycapabilities/maxlayers/index.md index bd04f1dc70fd7c9..4d7e810480323e9 100644 --- a/files/en-us/web/api/vrdisplaycapabilities/maxlayers/index.md +++ b/files/en-us/web/api/vrdisplaycapabilities/maxlayers/index.md @@ -11,7 +11,7 @@ browser-compat: api.VRDisplayCapabilities.maxLayers {{APIRef("WebVR API")}}{{Deprecated_Header}}{{Non-standard_Header}} -The **`maxLayers`** read-only property of the {{domxref("VRDisplayCapabilities")}} interface returns a number indicating the maximum number of {{domxref("VRLayerInit")}}s that the VR display can present at once (e.g. the maximum length of the array that {{domxref("VRDisplay.requestPresent()")}} can accept.) +The **`maxLayers`** read-only property of the {{domxref("VRDisplayCapabilities")}} interface returns a number indicating the maximum number of {{domxref("VRLayerInit")}}s that the VR display can present at once (e.g., the maximum length of the array that {{domxref("VRDisplay.requestPresent()")}} can accept.) > [!NOTE] > This property was part of the old [WebVR API](https://immersive-web.github.io/webvr/spec/1.1/). It has been superseded by the [WebXR Device API](https://immersive-web.github.io/webxr/). diff --git a/files/en-us/web/api/vrlayerinit/index.md b/files/en-us/web/api/vrlayerinit/index.md index be3de1b4c863498..3009a01a3ac4ec3 100644 --- a/files/en-us/web/api/vrlayerinit/index.md +++ b/files/en-us/web/api/vrlayerinit/index.md @@ -57,11 +57,15 @@ if (navigator.getVRDisplays) { `VRLayerInit` objects look something like this: ```js -{ - leftBounds : [/* … */], - rightBounds: [/* … */], - source: canvasReference -} +const init = { + leftBounds: [ + /* … */ + ], + rightBounds: [ + /* … */ + ], + source: canvasReference, +}; ``` > [!NOTE] diff --git a/files/en-us/web/api/vttcue/index.md b/files/en-us/web/api/vttcue/index.md index bd4265e8c07e9e9..1e43c5c8a46312f 100644 --- a/files/en-us/web/api/vttcue/index.md +++ b/files/en-us/web/api/vttcue/index.md @@ -59,9 +59,7 @@ _This interface also inherits properties from {{domxref("TextTrackCue")}}._ The following example adds a new {{domxref("TextTrack")}} to the video, then adds cues using the {{domxref("TextTrack.addCue()")}} method, with a `VTTCue` object as the value. ```html -<video - controls - src="https://interactive-examples.mdn.mozilla.net/media/cc0-videos/friday.mp4"></video> +<video controls src="/shared-assets/videos/friday.mp4"></video> ``` ### CSS diff --git a/files/en-us/web/api/wakelock/request/index.md b/files/en-us/web/api/wakelock/request/index.md index f0ddc679cadb23e..91a44ac499df261 100644 --- a/files/en-us/web/api/wakelock/request/index.md +++ b/files/en-us/web/api/wakelock/request/index.md @@ -40,7 +40,7 @@ A {{jsxref("Promise")}} that resolves with a {{domxref("WakeLockSentinel")}} obj - : Thrown when wake lock is not available, which can happen because: - - Use of this feature is blocked by a [Permissions Policy](/en-US/docs/Web/HTTP/Permissions_Policy). + - Use of this feature is blocked by a [Permissions Policy](/en-US/docs/Web/HTTP/Guides/Permissions_Policy). - The document is not fully active. - The document's visibility state is `hidden`. - The {{Glossary("User Agent")}} could not acquire platform's wake lock. diff --git a/files/en-us/web/api/wakelocksentinel/release_event/index.md b/files/en-us/web/api/wakelocksentinel/release_event/index.md index 41f3161e8ad4000..d042b0a4342e3cb 100644 --- a/files/en-us/web/api/wakelocksentinel/release_event/index.md +++ b/files/en-us/web/api/wakelocksentinel/release_event/index.md @@ -17,10 +17,10 @@ This can happen if the document becomes inactive or looses visibility, if the de Use the event name in methods like {{domxref("EventTarget.addEventListener", "addEventListener()")}}, or set an event handler property. -```js -addEventListener("release", (event) => {}); +```js-nolint +addEventListener("release", (event) => { }) -onrelease = (event) => {}; +onrelease = (event) => { } ``` ## Event type diff --git a/files/en-us/web/api/web_animations_api/index.md b/files/en-us/web/api/web_animations_api/index.md index 01243cbb7a0eeb3..16d8dbda92dd93e 100644 --- a/files/en-us/web/api/web_animations_api/index.md +++ b/files/en-us/web/api/web_animations_api/index.md @@ -7,7 +7,7 @@ spec-urls: https://drafts.csswg.org/web-animations/ {{DefaultAPISidebar("Web Animations")}} -The **Web Animations API** allows for synchronizing and timing changes to the presentation of a Web page, i.e. animation of DOM elements. It does so by combining two models: the Timing Model and the Animation Model. +The **Web Animations API** allows for synchronizing and timing changes to the presentation of a Web page, i.e., animation of DOM elements. It does so by combining two models: the Timing Model and the Animation Model. ## Concepts and usage diff --git a/files/en-us/web/api/web_animations_api/keyframe_formats/index.md b/files/en-us/web/api/web_animations_api/keyframe_formats/index.md index 9218c5ec522ee8a..09fcbf2e84bb840 100644 --- a/files/en-us/web/api/web_animations_api/keyframe_formats/index.md +++ b/files/en-us/web/api/web_animations_api/keyframe_formats/index.md @@ -103,7 +103,7 @@ There are two different ways to format keyframes: ### Implicit to/from keyframes -In newer browser versions, you are able to set a beginning or end state for an animation only (i.e. a single keyframe), and the browser will infer the other end of the animation if it is able to. For example, consider [this animation](https://mdn.github.io/dom-examples/web-animations-api/implicit-keyframes.html) — the Keyframe object looks like so: +In newer browser versions, you are able to set a beginning or end state for an animation only (i.e., a single keyframe), and the browser will infer the other end of the animation if it is able to. For example, consider [this animation](https://mdn.github.io/dom-examples/web-animations-api/implicit-keyframes.html) — the Keyframe object looks like so: ```js let rotate360 = [{ transform: "rotate(360deg)" }]; diff --git a/files/en-us/web/api/web_animations_api/tips/index.md b/files/en-us/web/api/web_animations_api/tips/index.md index adf82103ffbcf50..a6036f1b652dd6f 100644 --- a/files/en-us/web/api/web_animations_api/tips/index.md +++ b/files/en-us/web/api/web_animations_api/tips/index.md @@ -4,7 +4,7 @@ slug: Web/API/Web_Animations_API/Tips page-type: guide --- -{{CSSRef}} +{{DefaultAPISidebar("Web Animations")}} CSS animations make it possible to do incredible things with the elements that make up your documents and apps. There are things you might want to do that aren't obvious and many clever ways to do things that may not be immediately apparent. This article is a collection of tips and tricks we've found that will hopefully make your work easier, including how to re-run a completed animation. diff --git a/files/en-us/web/api/web_animations_api/using_the_web_animations_api/index.md b/files/en-us/web/api/web_animations_api/using_the_web_animations_api/index.md index 80bdc2c3025e139..20a29c4920a0c60 100644 --- a/files/en-us/web/api/web_animations_api/using_the_web_animations_api/index.md +++ b/files/en-us/web/api/web_animations_api/using_the_web_animations_api/index.md @@ -241,7 +241,7 @@ When animating elements, a common use case is to persist the final state of the - The browser has to maintain the state of the animation while it is still active, so the animation continues to consume resources even though it is no longer animating. Note that this is somewhat alleviated by the browser [automatically removing filling animations](#automatically_removing_filling_animations). - Styles applied by animations have a [higher precedence in the cascade](/en-US/docs/Web/CSS/CSS_cascade/Cascade#cascading_order) than specified styles, so it can be difficult to override them when needed. -A better approach is to use the {{domxref("Animation.commitStyles()")}} method. This writes the computed values of the animation's current styles into its target element's [`style`](/en-US/docs/Web/HTML/Global_attributes/style) attribute, after which the element can be restyled normally. +A better approach is to use the {{domxref("Animation.commitStyles()")}} method. This writes the computed values of the animation's current styles into its target element's [`style`](/en-US/docs/Web/HTML/Reference/Global_attributes/style) attribute, after which the element can be restyled normally. ## Automatically removing filling animations diff --git a/files/en-us/web/api/web_animations_api/web_animations_api_concepts/index.md b/files/en-us/web/api/web_animations_api/web_animations_api_concepts/index.md index 1d5d79599541266..61f952aefc83d8e 100644 --- a/files/en-us/web/api/web_animations_api/web_animations_api_concepts/index.md +++ b/files/en-us/web/api/web_animations_api/web_animations_api_concepts/index.md @@ -12,7 +12,7 @@ The Web Animations API fills the gap between declarative CSS animations and tran ## History -Over a decade ago, [Synchronized Multimedia Integration Language, or SMIL](/en-US/docs/Web/SVG/SVG_animation_with_SMIL) (pronounced "smile"), brought animation to SVG. Back then it was the only animation engine browsers had to worry about. While four out of five browsers supported SMIL, it only animated SVG elements, could not be used from CSS, and was very complex — often leading to inconsistent implementations. Ten years later, the Safari team introduced the [CSS Animations](https://drafts.csswg.org/css-animations/) and [CSS Transitions](https://drafts.csswg.org/css-transitions/) specs. +Over a decade ago, [Synchronized Multimedia Integration Language, or SMIL](/en-US/docs/Web/SVG/Guides/SVG_animation_with_SMIL) (pronounced "smile"), brought animation to SVG. Back then it was the only animation engine browsers had to worry about. While four out of five browsers supported SMIL, it only animated SVG elements, could not be used from CSS, and was very complex — often leading to inconsistent implementations. Ten years later, the Safari team introduced the [CSS Animations](https://drafts.csswg.org/css-animations/) and [CSS Transitions](https://drafts.csswg.org/css-transitions/) specs. The Internet Explorer team requested an animations API to consolidate and normalize animation functionality across all browsers, and thus efforts began in earnest among Mozilla Firefox and Google Chrome developers to create the one animation spec to rule them all: the Web Animations API. Now we've got the WAAPI for future animation specifications to piggyback on, allowing them to remain consistent and play well together. It also provides a point of reference all browsers can adhere to with the currently available specs. @@ -52,7 +52,7 @@ Timeline objects provide the useful property [`currentTime`](/en-US/docs/Web/API If Animation objects are DVD players, we can think of Animation Effects, or Keyframe Effects, as DVDs. Keyframe Effects are a bundle of information including at the bare minimum a set of keys and the duration they need to be animated over. The Animation Object takes this information and, using the Timeline Object, assembles a playable animation we can view and reference. -We currently have only one animation effect type available: [`KeyframeEffect`](/en-US/docs/Web/API/KeyframeEffect). Potentially we could have all kinds of Animation Effects in the future—e.g. effects for grouping and sequencing, not unlike features we had in Flash. In fact, Group Effects and Sequence Effects have already been outlined in the currently-in-progress level 2 spec of the Web Animations API. +We currently have only one animation effect type available: [`KeyframeEffect`](/en-US/docs/Web/API/KeyframeEffect). Potentially we could have all kinds of Animation Effects in the future—e.g., effects for grouping and sequencing, not unlike features we had in Flash. In fact, Group Effects and Sequence Effects have already been outlined in the currently-in-progress level 2 spec of the Web Animations API. ### Assembling the Animation from disparate pieces diff --git a/files/en-us/web/api/web_audio_api/advanced_techniques/index.md b/files/en-us/web/api/web_audio_api/advanced_techniques/index.md index 37f3b1badc0d74d..1d7ee101e32f6eb 100644 --- a/files/en-us/web/api/web_audio_api/advanced_techniques/index.md +++ b/files/en-us/web/api/web_audio_api/advanced_techniques/index.md @@ -121,7 +121,7 @@ We pass a time parameter to the function here, which we'll use later to schedule This is great, but wouldn't it be nice if we had an amplitude envelope to go with it? Let's create one so we get used to the methods we need to create an envelope with the Web Audio API. -Let's say our envelope has attack and release. We can allow the user to control these using [range inputs](/en-US/docs/Web/HTML/Element/input/range) on the interface: +Let's say our envelope has attack and release. We can allow the user to control these using [range inputs](/en-US/docs/Web/HTML/Reference/Elements/input/range) on the interface: ```html <label for="attack">Attack</label> diff --git a/files/en-us/web/api/web_audio_api/best_practices/index.md b/files/en-us/web/api/web_audio_api/best_practices/index.md index 138ac6b896848b3..89554d41596d86e 100644 --- a/files/en-us/web/api/web_audio_api/best_practices/index.md +++ b/files/en-us/web/api/web_audio_api/best_practices/index.md @@ -12,7 +12,7 @@ There's no strict right or wrong way when writing creative code. As long as you There are four main ways to load sound with the Web Audio API and it can be a little confusing as to which one you should use. -When working with files, you are looking at either grabbing the file from an {{domxref("HTMLMediaElement")}} (i.e. an {{htmlelement("audio")}} or {{htmlelement("video")}} element), or you're looking to fetch the file and decode it into a buffer. Both are legitimate ways of working, however, it's more common to use the former when you are working with full-length tracks, and the latter when working with shorter, more sample-like tracks. +When working with files, you are looking at either grabbing the file from an {{domxref("HTMLMediaElement")}} (i.e., an {{htmlelement("audio")}} or {{htmlelement("video")}} element), or you're looking to fetch the file and decode it into a buffer. Both are legitimate ways of working, however, it's more common to use the former when you are working with full-length tracks, and the latter when working with shorter, more sample-like tracks. Media elements have streaming support out of the box. The audio will start playing when the browser determines it can load the rest of the file before playing finishes. You can see an example of how to use this with the Web Audio API in the [Using the Web Audio API tutorial](/en-US/docs/Web/API/Web_Audio_API/Using_Web_Audio_API). @@ -28,7 +28,7 @@ The Web Audio API specification is constantly evolving and like most things on t There's the [`standardized-audio-context`](https://github.com/chrisguttandin/standardized-audio-context) npm package, which creates API functionality consistently across browsers, filling holes as they are found. It's constantly in development and endeavors to keep up with the current specification. -There is also the option of libraries, of which there are a few depending on your use case. For a good all-rounder, [howler.js](https://howlerjs.com/) is a good choice. It has cross-browser support and, provides a useful subset of functionality. Although it doesn't harness the full gamut of filters and other effects the Web Audio API comes with, you can do most of what you'd want to do. +There is also the option of libraries, of which there are a few depending on your use case. For a good all-rounder, [howler.js](https://howlerjs.com/) is a good choice. It has cross-browser support and provides a useful subset of functionality. Although it doesn't harness the full gamut of filters and other effects the Web Audio API comes with, you can do most of what you'd want to do. If you are looking for sound creation or a more instrument-based option, [tone.js](https://tonejs.github.io/) is a great library. It provides advanced scheduling capabilities, synths, and effects, and intuitive musical abstractions built on top of the Web Audio API. @@ -82,9 +82,9 @@ You might instead be working with an {{domxref("OfflineAudioContext")}}, in whic If your website or application contains sound, you should allow the user control over it, otherwise again, it will become annoying. This can be achieved by play/stop and volume/mute controls. The [Using the Web Audio API](/en-US/docs/Web/API/Web_Audio_API/Using_Web_Audio_API) tutorial goes over how to do this. -If you have buttons that switch audio on and off, using the ARIA [`role="switch"`](/en-US/docs/Web/Accessibility/ARIA/Roles/switch_role) attribute on them is a good option for signalling to assistive technology what the button's exact purpose is, and therefore making the app more accessible. There's a [demo of how to use it here](https://codepen.io/Wilto/pen/ZoGoQm?editors=1100). +If you have buttons that switch audio on and off, using the ARIA [`role="switch"`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/switch_role) attribute on them is a good option for signalling to assistive technology what the button's exact purpose is, and therefore making the app more accessible. There's a [demo of how to use it here](https://codepen.io/Wilto/pen/ZoGoQm?editors=1100). -As you work with a lot of changing values within the Web Audio API and will want to provide users with control over these, the [`<input type="range">`](/en-US/docs/Web/HTML/Element/input/range) is often a good choice of control to use. It's a good option as you can set minimum and maximum values, as well as increments with the [`step`](/en-US/docs/Web/HTML/Element/input#step) attribute. +As you work with a lot of changing values within the Web Audio API and will want to provide users with control over these, the [`<input type="range">`](/en-US/docs/Web/HTML/Reference/Elements/input/range) is often a good choice of control to use. It's a good option as you can set minimum and maximum values, as well as increments with the [`step`](/en-US/docs/Web/HTML/Reference/Elements/input#step) attribute. ## Setting AudioParam values diff --git a/files/en-us/web/api/web_audio_api/controlling_multiple_parameters_with_constantsourcenode/index.md b/files/en-us/web/api/web_audio_api/controlling_multiple_parameters_with_constantsourcenode/index.md index e7ae460332fe8dd..2644367a45c6455 100644 --- a/files/en-us/web/api/web_audio_api/controlling_multiple_parameters_with_constantsourcenode/index.md +++ b/files/en-us/web/api/web_audio_api/controlling_multiple_parameters_with_constantsourcenode/index.md @@ -32,16 +32,23 @@ The HTML content for this example is primarily a checkbox, shaped as an actual b ```html <div class="controls"> - <input type="checkbox" id="playButton"> - <label for="playButton">Activate: </label> - <label for="volumeControl">Volume: </label> - <input type="range" min="0.0" max="1.0" step="0.01" - value="0.8" name="volume" id="volumeControl"> - </div> + <input type="checkbox" id="playButton" /> + <label for="playButton">Activate: </label> + <label for="volumeControl">Volume: </label> + <input + type="range" + min="0.0" + max="1.0" + step="0.01" + value="0.8" + name="volume" + id="volumeControl" /> </div> -<p>Toggle the checkbox above to start and stop the tones, and use the volume control to -change the volume of the notes E and G in the chord.</p> +<p> + Toggle the checkbox above to start and stop the tones, and use the volume + control to change the volume of the notes E and G in the chord. +</p> ``` ```css hidden @@ -56,7 +63,7 @@ change the volume of the notes E and G in the chord.</p> content: "⏸"; } -#playButton:not(checked) + label::after { +#playButton:not(:checked) + label::after { content: "▶️"; } @@ -209,19 +216,19 @@ When the user clicks the play/pause toggle button while the oscillators aren't p function startOscillators() { oscNode1 = new OscillatorNode(context, { type: "sine", - frequency: 261.625565300598634, // middle C$ + frequency: 261.6255653005986, // middle C$ }); oscNode1.connect(gainNode1); oscNode2 = new OscillatorNode(context, { type: "sine", - frequency: 329.627556912869929, // E + frequency: 329.6275569128699, // E }); oscNode2.connect(gainNode2); oscNode3 = new OscillatorNode(context, { type: "sine", - frequency: 391.995435981749294, // G + frequency: 391.99543598174927, // G }); oscNode3.connect(gainNode3); diff --git a/files/en-us/web/api/web_audio_api/index.md b/files/en-us/web/api/web_audio_api/index.md index cba71fbdf3c4013..05ba1a21ea05bd0 100644 --- a/files/en-us/web/api/web_audio_api/index.md +++ b/files/en-us/web/api/web_audio_api/index.md @@ -63,7 +63,7 @@ General containers and definitions that shape audio graphs in Web Audio API usag - {{domxref("AudioContext")}} - : The **`AudioContext`** interface represents an audio-processing graph built from audio modules linked together, each represented by an {{domxref("AudioNode")}}. An audio context controls the creation of the nodes it contains and the execution of the audio processing, or decoding. You need to create an `AudioContext` before you do anything else, as everything happens inside a context. - {{domxref("AudioNode")}} - - : The **`AudioNode`** interface represents an audio-processing module like an _audio source_ (e.g. an HTML {{HTMLElement("audio")}} or {{HTMLElement("video")}} element), _audio destination_, _intermediate processing module_ (e.g. a filter like {{domxref("BiquadFilterNode")}}, or _volume control_ like {{domxref("GainNode")}}). + - : The **`AudioNode`** interface represents an audio-processing module like an _audio source_ (e.g., an HTML {{HTMLElement("audio")}} or {{HTMLElement("video")}} element), _audio destination_, _intermediate processing module_ (e.g., a filter like {{domxref("BiquadFilterNode")}}, or _volume control_ like {{domxref("GainNode")}}). - {{domxref("AudioParam")}} - : The **`AudioParam`** interface represents an audio-related parameter, like one of an {{domxref("AudioNode")}}. It can be set to a specific value or a change in value, and can be scheduled to happen at a specific time and following a specific pattern. - {{domxref("AudioParamMap")}} diff --git a/files/en-us/web/api/web_audio_api/simple_synth/index.md b/files/en-us/web/api/web_audio_api/simple_synth/index.md index ae5e3cefce847c7..c060ba174c2fb13 100644 --- a/files/en-us/web/api/web_audio_api/simple_synth/index.md +++ b/files/en-us/web/api/web_audio_api/simple_synth/index.md @@ -36,7 +36,7 @@ Beneath the keyboard, we'll put some controls for configuring the layer. For now First we create the `<div>` to contain the settings bar, so it can be styled as needed. Then we establish a box that will be presented on the left side of the bar and place a label and an {{HTMLElement("input")}} element of type `"range"`. The range element will typically be presented as a slider control; we configure it to allow any value between 0.0 and 1.0, stepping by 0.01 each position. -```html +```html-nolint <div class="settingsBar"> <div class="left"> <span>Volume: </span> @@ -53,16 +53,15 @@ First we create the `<div>` to contain the settings bar, so it can be styled as <option value="1.0" label="100%"></option> </datalist> </div> -</div> ``` -We specify a default value of 0.5, and we provide a {{HTMLElement("datalist")}} element which is connected to the range using the [`list`](/en-US/docs/Web/HTML/Element/input#list) attribute to find an option list whose ID matches; in this case, the data set is named `"volumes"`. This lets us provide a set of common values and special strings which the browser may optionally choose to display in some fashion; we provide names for the values 0.0 ("Mute") and 1.0 ("100%"). +We specify a default value of 0.5, and we provide a {{HTMLElement("datalist")}} element which is connected to the range using the [`list`](/en-US/docs/Web/HTML/Reference/Elements/input#list) attribute to find an option list whose ID matches; in this case, the data set is named `"volumes"`. This lets us provide a set of common values and special strings which the browser may optionally choose to display in some fashion; we provide names for the values 0.0 ("Mute") and 1.0 ("100%"). ##### The waveform picker On the right side of the settings bar, we place a label and a {{HTMLElement("select")}} element named `"waveform"` whose options correspond to the available waveforms. -```html +```html-nolint <div class="right"> <span>Current waveform: </span> <select name="waveform"> @@ -214,7 +213,6 @@ References to elements we'll need access to are obtained: - `volumeControl` is the {{HTMLElement("input")}} element (of type `"range"`) used to control the main audio volume. ```js -let noteFreq = null; let customWaveform = null; let sineTerms = null; let cosineTerms = null; @@ -222,129 +220,48 @@ let cosineTerms = null; Finally, global variables that will be used when constructing waveforms are created: -- `noteFreq` will be an array of arrays; each array represents one octave, each of which contains one entry for each note in that octave. The value for each is the frequency, in Hertz, of the note's tone. - `customWaveform` will be set up as a {{domxref("PeriodicWave")}} describing the waveform to use when the user selects "Custom" from the waveform picker. - `sineTerms` and `cosineTerms` will be used to store the data for generating the waveform; each will contain an array that's generated when the user chooses "Custom". ### Creating the note table -The `createNoteTable()` function builds the array `noteFreq` to contain an array of objects representing each octave. Each octave, in turn, has one named property for each note in that octave; the property's name is the note's name (such as "C#" to represent C-sharp), and the value is the frequency, in Hertz, of that note. +The `createNoteTable()` function builds the array `noteFreq` to contain an array of objects representing each octave. Each octave, in turn, has one named property for each note in that octave; the property's name is the note's name (such as "C#" to represent C-sharp), and the value is the frequency, in Hertz, of that note. We only hardcode one octave; each subsequent octave can be derived from the previous octave by doubling each note. ```js function createNoteTable() { - const noteFreq = []; - for (let i=0; i< 9; i++) { - noteFreq[i] = []; + const noteFreq = [ + { A: 27.5, "A#": 29.13523509488062, B: 30.867706328507754 }, + { + C: 32.70319566257483, + "C#": 34.64782887210901, + D: 36.70809598967595, + "D#": 38.89087296526011, + E: 41.20344461410874, + F: 43.65352892912549, + "F#": 46.2493028389543, + G: 48.99942949771866, + "G#": 51.91308719749314, + A: 55, + "A#": 58.27047018976124, + B: 61.73541265701551, + }, + ]; + for (let octave = 2; octave <= 7; octave++) { + noteFreq.push( + Object.fromEntries( + Object.entries(noteFreq[octave - 1]).map(([key, freq]) => [ + key, + freq * 2, + ]), + ), + ); } - - noteFreq[0]["A"] = 27.500000000000000; - noteFreq[0]["A#"] = 29.135235094880619; - noteFreq[0]["B"] = 30.867706328507756; - - noteFreq[1]["C"] = 32.703195662574829; - noteFreq[1]["C#"] = 34.647828872109012; - noteFreq[1]["D"] = 36.708095989675945; - noteFreq[1]["D#"] = 38.890872965260113; - noteFreq[1]["E"] = 41.203444614108741; - noteFreq[1]["F"] = 43.653528929125485; - noteFreq[1]["F#"] = 46.249302838954299; - noteFreq[1]["G"] = 48.999429497718661; - noteFreq[1]["G#"] = 51.913087197493142; - noteFreq[1]["A"] = 55.000000000000000; - noteFreq[1]["A#"] = 58.270470189761239; - noteFreq[1]["B"] = 61.735412657015513; - // … -``` - -Several octaves not shown for brevity. - -```js hidden -noteFreq[2]["C"] = 65.406391325149658; -noteFreq[2]["C#"] = 69.295657744218024; -noteFreq[2]["D"] = 73.41619197935189; -noteFreq[2]["D#"] = 77.781745930520227; -noteFreq[2]["E"] = 82.406889228217482; -noteFreq[2]["F"] = 87.307057858250971; -noteFreq[2]["F#"] = 92.498605677908599; -noteFreq[2]["G"] = 97.998858995437323; -noteFreq[2]["G#"] = 103.826174394986284; -noteFreq[2]["A"] = 110.0; -noteFreq[2]["A#"] = 116.540940379522479; -noteFreq[2]["B"] = 123.470825314031027; - -noteFreq[3]["C"] = 130.812782650299317; -noteFreq[3]["C#"] = 138.591315488436048; -noteFreq[3]["D"] = 146.83238395870378; -noteFreq[3]["D#"] = 155.563491861040455; -noteFreq[3]["E"] = 164.813778456434964; -noteFreq[3]["F"] = 174.614115716501942; -noteFreq[3]["F#"] = 184.997211355817199; -noteFreq[3]["G"] = 195.997717990874647; -noteFreq[3]["G#"] = 207.652348789972569; -noteFreq[3]["A"] = 220.0; -noteFreq[3]["A#"] = 233.081880759044958; -noteFreq[3]["B"] = 246.941650628062055; - -noteFreq[4]["C"] = 261.625565300598634; -noteFreq[4]["C#"] = 277.182630976872096; -noteFreq[4]["D"] = 293.66476791740756; -noteFreq[4]["D#"] = 311.12698372208091; -noteFreq[4]["E"] = 329.627556912869929; -noteFreq[4]["F"] = 349.228231433003884; -noteFreq[4]["F#"] = 369.994422711634398; -noteFreq[4]["G"] = 391.995435981749294; -noteFreq[4]["G#"] = 415.304697579945138; -noteFreq[4]["A"] = 440.0; -noteFreq[4]["A#"] = 466.163761518089916; -noteFreq[4]["B"] = 493.883301256124111; - -noteFreq[5]["C"] = 523.251130601197269; -noteFreq[5]["C#"] = 554.365261953744192; -noteFreq[5]["D"] = 587.32953583481512; -noteFreq[5]["D#"] = 622.253967444161821; -noteFreq[5]["E"] = 659.255113825739859; -noteFreq[5]["F"] = 698.456462866007768; -noteFreq[5]["F#"] = 739.988845423268797; -noteFreq[5]["G"] = 783.990871963498588; -noteFreq[5]["G#"] = 830.609395159890277; -noteFreq[5]["A"] = 880.0; -noteFreq[5]["A#"] = 932.327523036179832; -noteFreq[5]["B"] = 987.766602512248223; - -noteFreq[6]["C"] = 1046.502261202394538; -noteFreq[6]["C#"] = 1108.730523907488384; -noteFreq[6]["D"] = 1174.659071669630241; -noteFreq[6]["D#"] = 1244.507934888323642; -noteFreq[6]["E"] = 1318.510227651479718; -noteFreq[6]["F"] = 1396.912925732015537; -noteFreq[6]["F#"] = 1479.977690846537595; -noteFreq[6]["G"] = 1567.981743926997176; -noteFreq[6]["G#"] = 1661.218790319780554; -noteFreq[6]["A"] = 1760.0; -noteFreq[6]["A#"] = 1864.655046072359665; -noteFreq[6]["B"] = 1975.533205024496447; -``` - -```js - noteFreq[7]["C"] = 2093.004522404789077; - noteFreq[7]["C#"] = 2217.461047814976769; - noteFreq[7]["D"] = 2349.318143339260482; - noteFreq[7]["D#"] = 2489.015869776647285; - noteFreq[7]["E"] = 2637.020455302959437; - noteFreq[7]["F"] = 2793.825851464031075; - noteFreq[7]["F#"] = 2959.955381693075191; - noteFreq[7]["G"] = 3135.963487853994352; - noteFreq[7]["G#"] = 3322.437580639561108; - noteFreq[7]["A"] = 3520.000000000000000; - noteFreq[7]["A#"] = 3729.310092144719331; - noteFreq[7]["B"] = 3951.066410048992894; - - noteFreq[8]["C"] = 4186.009044809578154; + noteFreq.push({ C: 4186.009044809578 }); return noteFreq; } ``` -The result is an array, `noteFreq`, with an object for each octave. Each octave object has named properties in it where the property name is the name of the note (such as "C#" to represent C-sharp) and the property's value is the note's frequency in Hertz. In part, the resulting object looks like this: +In part, the resulting object looks like this: <table class="standard-table"> <tbody> @@ -398,29 +315,13 @@ With this table in place, we can find out the frequency for a given note in a pa > [!NOTE] > The values in the example table above have been rounded to two decimal places. -```js hidden -if (!Object.entries) { - Object.entries = function entries(O) { - return reduce( - keys(O), - (e, k) => - concat( - e, - typeof k === "string" && isEnumerable(O, k) ? [[k, O[k]]] : [], - ), - [], - ); - }; -} -``` - ### Building the keyboard The `setup()` function is responsible for building the keyboard and preparing the app to play music. ```js function setup() { - noteFreq = createNoteTable(); + const noteFreq = createNoteTable(); volumeControl.addEventListener("change", changeVolume, false); @@ -498,7 +399,7 @@ function createKey(note, octave, freq) { } ``` -After creating the elements that will represent the key and its label, we configure the key's element by setting its class to "key" (which establishes its appearance). Then we add [`data-*`](/en-US/docs/Web/HTML/Global_attributes/data-*) attributes which contain the key's octave (attribute `data-octave`), string representing the note to play (attribute `data-note`), and frequency (attribute `data-frequency`) in Hertz. This will let us easily fetch that information as needed when handling events. +After creating the elements that will represent the key and its label, we configure the key's element by setting its class to "key" (which establishes its appearance). Then we add [`data-*`](/en-US/docs/Web/HTML/Reference/Global_attributes/data-*) attributes which contain the key's octave (attribute `data-octave`), string representing the note to play (attribute `data-note`), and frequency (attribute `data-frequency`) in Hertz. This will let us easily fetch that information as needed when handling events. ### Making music @@ -592,8 +493,9 @@ This sets the value of the main gain node's `gain` {{domxref("AudioParam")}} to The code below adds [`keydown`](/en-US/docs/Web/API/Element/keydown_event) and [`keyup`](/en-US/docs/Web/API/Element/keyup_event) event listeners to handle keyboard input. The `keydown` event handler calls `notePressed()` to start playing the note corresponding to the key that was pressed, and the `keyup` event handler calls `noteReleased()` to stop playing the note corresponding to the key that was released. -```js-nolint +```js const synthKeys = document.querySelectorAll(".key"); +// prettier-ignore const keyCodes = [ "Space", "ShiftLeft", "KeyZ", "KeyX", "KeyC", "KeyV", "KeyB", "KeyN", "KeyM", "Comma", "Period", "Slash", "ShiftRight", diff --git a/files/en-us/web/api/web_audio_api/using_audioworklet/index.md b/files/en-us/web/api/web_audio_api/using_audioworklet/index.md index 69271ea9adc1bf9..c34dfa1ceb92867 100644 --- a/files/en-us/web/api/web_audio_api/using_audioworklet/index.md +++ b/files/en-us/web/api/web_audio_api/using_audioworklet/index.md @@ -105,23 +105,26 @@ It's entirely up to you. This is a very powerful tool in your audio programming Let's take a look at an implementation of `process()` that can process multiple inputs, with each input being used to generate the corresponding output. Any excess inputs are ignored. ```js -process(inputList, outputList, parameters) { - const sourceLimit = Math.min(inputList.length, outputList.length); - - for (let inputNum = 0; inputNum < sourceLimit; inputNum++) { - const input = inputList[inputNum]; - const output = outputList[inputNum]; - const channelCount = Math.min(input.length, output.length); - - for (let channelNum = 0; channelNum < channelCount; channelNum++) { - input[channelNum].forEach((sample, i) => { - // Manipulate the sample - output[channelNum][i] = sample; - }); +class MyAudioProcessor extends AudioWorkletProcessor { + // … + process(inputList, outputList, parameters) { + const sourceLimit = Math.min(inputList.length, outputList.length); + + for (let inputNum = 0; inputNum < sourceLimit; inputNum++) { + const input = inputList[inputNum]; + const output = outputList[inputNum]; + const channelCount = Math.min(input.length, output.length); + + for (let channelNum = 0; channelNum < channelCount; channelNum++) { + input[channelNum].forEach((sample, i) => { + // Manipulate the sample + output[channelNum][i] = sample; + }); + } } - }; - return true; + return true; + } } ``` @@ -132,29 +135,32 @@ Note that when determining the number of sources to process and send through to Many nodes perform **mixing** operations, where the inputs are combined in some way into a single output. This is demonstrated in the following example. ```js -process(inputList, outputList, parameters) { - const sourceLimit = Math.min(inputList.length, outputList.length); - for (let inputNum = 0; inputNum < sourceLimit; inputNum++) { - let input = inputList[inputNum]; - let output = outputList[0]; - let channelCount = Math.min(input.length, output.length); - - for (let channelNum = 0; channelNum < channelCount; channelNum++) { - for (let i = 0; i < input[channelNum].length; i++) { - let sample = output[channelNum][i] + input[channelNum][i]; - - if (sample > 1.0) { - sample = 1.0; - } else if (sample < -1.0) { - sample = -1.0; +class MyAudioProcessor extends AudioWorkletProcessor { + // … + process(inputList, outputList, parameters) { + const sourceLimit = Math.min(inputList.length, outputList.length); + for (let inputNum = 0; inputNum < sourceLimit; inputNum++) { + let input = inputList[inputNum]; + let output = outputList[0]; + let channelCount = Math.min(input.length, output.length); + + for (let channelNum = 0; channelNum < channelCount; channelNum++) { + for (let i = 0; i < input[channelNum].length; i++) { + let sample = output[channelNum][i] + input[channelNum][i]; + + if (sample > 1.0) { + sample = 1.0; + } else if (sample < -1.0) { + sample = -1.0; + } + + output[channelNum][i] = sample; } - - output[channelNum][i] = sample; } } - }; - return true; + return true; + } } ``` @@ -224,21 +230,24 @@ To add parameters to an {{domxref("AudioWorkletNode")}}, you need to define them In the following implementation of `parameterDescriptors()`, the returned array has two `AudioParam` objects. The first defines `gain` as a value between 0 and 1, with a default value of 0.5. The second parameter is named `frequency` and defaults to 440.0, with a range from 27.5 to 4186.009, inclusively. ```js -static get parameterDescriptors() { - return [ - { - name: "gain", - defaultValue: 0.5, - minValue: 0, - maxValue: 1 - }, - { - name: "frequency", - defaultValue: 440.0, - minValue: 27.5, - maxValue: 4186.009 - } - ]; +class MyAudioProcessor extends AudioWorkletProcessor { + // … + static get parameterDescriptors() { + return [ + { + name: "gain", + defaultValue: 0.5, + minValue: 0, + maxValue: 1, + }, + { + name: "frequency", + defaultValue: 440.0, + minValue: 27.5, + maxValue: 4186.009, + }, + ]; + } } ``` @@ -252,31 +261,34 @@ Accessing your processor node's parameters is as simple as looking them up in th In the code below, we see a `process()` function that handles a `gain` parameter which can be used as either an a-rate or k-rate parameter. Our node only supports one input, so it just takes the first input in the list, applies the gain to it, and writes the resulting data to the first output's buffer. ```js -process(inputList, outputList, parameters) { - const input = inputList[0]; - const output = outputList[0]; - const gain = parameters.gain; - - for (let channelNum = 0; channelNum < input.length; channelNum++) { - const inputChannel = input[channelNum]; - const outputChannel = output[channelNum]; - - // If gain.length is 1, it's a k-rate parameter, so apply - // the first entry to every frame. Otherwise, apply each - // entry to the corresponding frame. - - if (gain.length === 1) { - for (let i = 0; i < inputChannel.length; i++) { - outputChannel[i] = inputChannel[i] * gain[0]; - } - } else { - for (let i = 0; i < inputChannel.length; i++) { - outputChannel[i] = inputChannel[i] * gain[i]; +class MyAudioProcessor extends AudioWorkletProcessor { + // … + process(inputList, outputList, parameters) { + const input = inputList[0]; + const output = outputList[0]; + const gain = parameters.gain; + + for (let channelNum = 0; channelNum < input.length; channelNum++) { + const inputChannel = input[channelNum]; + const outputChannel = output[channelNum]; + + // If gain.length is 1, it's a k-rate parameter, so apply + // the first entry to every frame. Otherwise, apply each + // entry to the corresponding frame. + + if (gain.length === 1) { + for (let i = 0; i < inputChannel.length; i++) { + outputChannel[i] = inputChannel[i] * gain[0]; + } + } else { + for (let i = 0; i < inputChannel.length; i++) { + outputChannel[i] = inputChannel[i] * gain[i]; + } } } - } - return true; + return true; + } } ``` diff --git a/files/en-us/web/api/web_audio_api/using_iir_filters/index.md b/files/en-us/web/api/web_audio_api/using_iir_filters/index.md index ad45efa0fe18575..5b664c5b69ed09e 100644 --- a/files/en-us/web/api/web_audio_api/using_iir_filters/index.md +++ b/files/en-us/web/api/web_audio_api/using_iir_filters/index.md @@ -32,7 +32,7 @@ When you are using an {{domxref("IIRFilterNode")}} instead of a {{domxref("Biqua With the IIR filter node it's up to you to set what `feedforward` and `feedback` values the filter needs — this determines the characteristics of the filter. The downside is that this involves some complex maths. -If you are looking to learn more there's some [information about the maths behind IIR filters here](https://ece.uccs.edu/~mwickert/ece2610/lecture_notes/ece2610_chap8.pdf). This enters the realms of signal processing theory — don't worry if you look at it and feel like it's not for you. +If you are looking to learn more there's some [information about the maths behind IIR filters here](https://www.staff.ncl.ac.uk/oliver.hinton/eee305/Chapter5.pdf). This enters the realms of signal processing theory — don't worry if you look at it and feel like it's not for you. If you want to play with the IIR filter node and need some values to help along the way, there's [a table of already calculated values here](https://www.dspguide.com/CH20.PDF); on pages 4 & 5 of the linked PDF the `an` values refer to the `feedForward` values and the `bn` values refer to the `feedback`. [musicdsp.org](https://www.musicdsp.org/en/latest/) is also a great resource if you want to read more about different filters and how they are implemented digitally. diff --git a/files/en-us/web/api/web_audio_api/using_web_audio_api/index.md b/files/en-us/web/api/web_audio_api/using_web_audio_api/index.md index 0b89b2af299bffc..ae33284e6a3be19 100644 --- a/files/en-us/web/api/web_audio_api/using_web_audio_api/index.md +++ b/files/en-us/web/api/web_audio_api/using_web_audio_api/index.md @@ -52,7 +52,7 @@ Now, the audio context we've created needs some sound to play through it. There ``` > [!NOTE] -> If the sound file you're loading is held on a different domain you will need to use the `crossorigin` attribute; see [Cross Origin Resource Sharing (CORS)](/en-US/docs/Web/HTTP/CORS) for more information. +> If the sound file you're loading is held on a different domain you will need to use the `crossorigin` attribute; see [Cross Origin Resource Sharing (CORS)](/en-US/docs/Web/HTTP/Guides/CORS) for more information. To use all the nice things we get with the Web Audio API, we need to grab the source from this element and _pipe_ it into the context we have created. Lucky for us there's a method that allows us to do just that — {{domxref("AudioContext.createMediaElementSource")}}: @@ -138,7 +138,7 @@ audioElement.addEventListener( Let's delve into some basic modification nodes, to change the sound that we have. This is where the Web Audio API really starts to come in handy. First of all, let's change the volume. This can be done using a {{domxref("GainNode")}}, which represents how big our sound wave is. -There are two ways you can create nodes with the Web Audio API. You can use the factory method on the context itself (e.g. `audioContext.createGain()`) or via a constructor of the node (e.g. `new GainNode()`). We'll use the factory method in our code: +There are two ways you can create nodes with the Web Audio API. You can use the factory method on the context itself (e.g., `audioContext.createGain()`) or via a constructor of the node (e.g., `new GainNode()`). We'll use the factory method in our code: ```js const gainNode = audioContext.createGain(); @@ -156,7 +156,7 @@ This will make our audio graph look like this: The default value for gain is 1; this keeps the current volume the same. Gain can be set to a minimum of about -3.4028235E38 and a max of about 3.4028235E38 (float number range in JavaScript). Here we'll allow the boombox to move the gain up to 2 (double the original volume) and down to 0 (this will effectively mute our sound). -Let's give the user control to do this — we'll use a [range input](/en-US/docs/Web/HTML/Element/input/range): +Let's give the user control to do this — we'll use a [range input](/en-US/docs/Web/HTML/Reference/Elements/input/range): ```html <input type="range" id="volume" min="0" max="2" value="1" step="0.01" /> @@ -180,7 +180,7 @@ volumeControl.addEventListener( ``` > [!NOTE] -> The values of node objects (e.g. `GainNode.gain`) are not simple values; they are actually objects of type {{domxref("AudioParam")}} — these called parameters. This is why we have to set `GainNode.gain`'s `value` property, rather than just setting the value on `gain` directly. This enables them to be much more flexible, allowing for passing the parameter a specific set of values to change between over a set period of time, for example. +> The values of node objects (e.g., `GainNode.gain`) are not simple values; they are actually objects of type {{domxref("AudioParam")}} — these called parameters. This is why we have to set `GainNode.gain`'s `value` property, rather than just setting the value on `gain` directly. This enables them to be much more flexible, allowing for passing the parameter a specific set of values to change between over a set period of time, for example. Great, now the user can update the track's volume! The gain node is the perfect node to use if you want to add mute functionality. diff --git a/files/en-us/web/api/web_audio_api/web_audio_spatialization_basics/index.md b/files/en-us/web/api/web_audio_api/web_audio_spatialization_basics/index.md index 1fb9fed4eb6f6b8..284ea5bc6c0d2dd 100644 --- a/files/en-us/web/api/web_audio_api/web_audio_spatialization_basics/index.md +++ b/files/en-us/web/api/web_audio_api/web_audio_spatialization_basics/index.md @@ -71,7 +71,7 @@ listener.upY.value = 1; listener.upZ.value = 0; ``` -The forward properties represent the 3D coordinate position of the listener's forward direction (e.g. the direction they are facing in), while the up properties represent the 3D coordinate position of the top of the listener's head. +The forward properties represent the 3D coordinate position of the listener's forward direction (e.g., the direction they are facing in), while the up properties represent the 3D coordinate position of the top of the listener's head. These two together can nicely set the direction. ## Creating a panner node @@ -174,7 +174,7 @@ const panner = new PannerNode(audioCtx, { Now we're going to move our boombox around our 'room'. We've got some controls set up to do this. We can move it left and right, up and down, and back and forth; we can also rotate it. -The sound direction is coming from the boombox speaker at the front, so when we rotate it, we can alter the sound's direction — i.e. make it project to the back when the boombox is rotated 180 degrees and facing away from us. +The sound direction is coming from the boombox speaker at the front, so when we rotate it, we can alter the sound's direction — i.e., make it project to the back when the boombox is rotated 180 degrees and facing away from us. We need to set up a few things for the interface. First, we'll get references to the elements we want to move, then we'll store references to the values we'll change when we set up [CSS transforms](/en-US/docs/Web/CSS/CSS_transforms) to actually do the movement. @@ -207,7 +207,7 @@ const outerBound = 1.5; Let's create a function that takes the direction we want to move as a parameter, and both modifies the CSS transform and updates the position and orientation values of our panner node properties to change the sound as appropriate. To start with let's take a look at our left, right, up and down values as these are pretty straightforward. -We'll move the boombox along these axis and update the appropriate position. +We'll move the boombox along these axes and update the appropriate position. ```js function moveBoombox(direction) { @@ -243,37 +243,40 @@ function moveBoombox(direction) { It's a similar story for our move in and out values too: ```js -case 'back': - if (transform.zAxis > innerBound) { - transform.zAxis -= 0.01; - panner.positionZ.value += 40; - } - break; -case 'forward': - if (transform.zAxis < outerBound) { - transform.zAxis += 0.01; - panner.positionZ.value -= 40; - } - break; +switch (direction) { + // … + case "back": + if (transform.zAxis > innerBound) { + transform.zAxis -= 0.01; + panner.positionZ.value += 40; + } + break; + case "forward": + if (transform.zAxis < outerBound) { + transform.zAxis += 0.01; + panner.positionZ.value -= 40; + } + break; +} ``` Our rotation values are a little more involved, however, as we need to move the sound _around_. -Not only do we have to update two axis values (e.g. if you rotate an object around the x-axis, you update the y and z coordinates for that object), but we also need to do some more maths for this. +Not only do we have to update two axis values (e.g., if you rotate an object around the x-axis, you update the y and z coordinates for that object), but we also need to do some more maths for this. The rotation is a circle and we need [`Math.sin`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Math/sin) and [`Math.cos`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Math/cos) to help us draw that circle. Let's set up a rotation rate, which we'll convert into a radian range value for use in `Math.sin` and `Math.cos` later, when we want to figure out the new coordinates when we're rotating our boombox: ```js -// set up rotation constants -const rotationRate = 60; // bigger number equals slower sound rotation +// Set up rotation constants +const rotationRate = 60; // Bigger number equals slower sound rotation -const q = Math.PI / rotationRate; //rotation increment in radians +const q = Math.PI / rotationRate; // Rotation increment in radians ``` We can also use this to work out degrees rotated, which will help with the CSS transforms we will have to create (note we need both an x and y-axis for the CSS transforms): ```js -// get degrees for CSS +// Get degrees for CSS const degreesX = (q * 180) / Math.PI; const degreesY = (q * 180) / Math.PI; ``` @@ -281,18 +284,25 @@ const degreesY = (q * 180) / Math.PI; Let's take a look at our left rotation as an example. We need to change the x orientation and the z orientation of the panner coordinates, to move around the y-axis for our left rotation: ```js -case 'rotate-left': - transform.rotateY -= degreesY; - - // 'left' is rotation about y-axis with negative angle increment - z = panner.orientationZ.value*Math.cos(q) - panner.orientationX.value*Math.sin(q); - x = panner.orientationZ.value*Math.sin(q) + panner.orientationX.value*Math.cos(q); - y = panner.orientationY.value; - - panner.orientationX.value = x; - panner.orientationY.value = y; - panner.orientationZ.value = z; - break; +switch (direction) { + // … + case "rotate-left": + transform.rotateY -= degreesY; + + // 'left' is rotation about y-axis with negative angle increment + z = + panner.orientationZ.value * Math.cos(q) - + panner.orientationX.value * Math.sin(q); + x = + panner.orientationZ.value * Math.sin(q) + + panner.orientationX.value * Math.cos(q); + y = panner.orientationY.value; + + panner.orientationX.value = x; + panner.orientationY.value = y; + panner.orientationZ.value = z; + break; +} ``` This _is_ a little confusing, but what we're doing is using sin and cos to help us work out the circular motion the coordinates need for the rotation of the boombox. @@ -300,36 +310,51 @@ This _is_ a little confusing, but what we're doing is using sin and cos to help We can do this for all the axes. We just need to choose the right orientations to update and whether we want a positive or negative increment. ```js -case 'rotate-right': - transform.rotateY += degreesY; - // 'right' is rotation about y-axis with positive angle increment - z = panner.orientationZ.value*Math.cos(-q) - panner.orientationX.value*Math.sin(-q); - x = panner.orientationZ.value*Math.sin(-q) + panner.orientationX.value*Math.cos(-q); - y = panner.orientationY.value; - panner.orientationX.value = x; - panner.orientationY.value = y; - panner.orientationZ.value = z; - break; -case 'rotate-up': - transform.rotateX += degreesX; - // 'up' is rotation about x-axis with negative angle increment - z = panner.orientationZ.value*Math.cos(-q) - panner.orientationY.value*Math.sin(-q); - y = panner.orientationZ.value*Math.sin(-q) + panner.orientationY.value*Math.cos(-q); - x = panner.orientationX.value; - panner.orientationX.value = x; - panner.orientationY.value = y; - panner.orientationZ.value = z; - break; -case 'rotate-down': - transform.rotateX -= degreesX; - // 'down' is rotation about x-axis with positive angle increment - z = panner.orientationZ.value*Math.cos(q) - panner.orientationY.value*Math.sin(q); - y = panner.orientationZ.value*Math.sin(q) + panner.orientationY.value*Math.cos(q); - x = panner.orientationX.value; - panner.orientationX.value = x; - panner.orientationY.value = y; - panner.orientationZ.value = z; - break; +switch (direction) { + // … + case "rotate-right": + transform.rotateY += degreesY; + // 'right' is rotation about y-axis with positive angle increment + z = + panner.orientationZ.value * Math.cos(-q) - + panner.orientationX.value * Math.sin(-q); + x = + panner.orientationZ.value * Math.sin(-q) + + panner.orientationX.value * Math.cos(-q); + y = panner.orientationY.value; + panner.orientationX.value = x; + panner.orientationY.value = y; + panner.orientationZ.value = z; + break; + case "rotate-up": + transform.rotateX += degreesX; + // 'up' is rotation about x-axis with negative angle increment + z = + panner.orientationZ.value * Math.cos(-q) - + panner.orientationY.value * Math.sin(-q); + y = + panner.orientationZ.value * Math.sin(-q) + + panner.orientationY.value * Math.cos(-q); + x = panner.orientationX.value; + panner.orientationX.value = x; + panner.orientationY.value = y; + panner.orientationZ.value = z; + break; + case "rotate-down": + transform.rotateX -= degreesX; + // 'down' is rotation about x-axis with positive angle increment + z = + panner.orientationZ.value * Math.cos(q) - + panner.orientationY.value * Math.sin(q); + y = + panner.orientationZ.value * Math.sin(q) + + panner.orientationY.value * Math.cos(q); + x = panner.orientationX.value; + panner.orientationX.value = x; + panner.orientationY.value = y; + panner.orientationZ.value = z; + break; +} ``` One last thing — we need to update the CSS and keep a reference of the last move for the mouse event. @@ -449,7 +474,7 @@ function moveBoombox(direction, prevMove) { ## Wiring up our controls -Wiring up out control buttons is comparatively simple — now we can listen for a mouse event on our controls and run this function, as well as stop it when the mouse is released: +Wiring up our control buttons is comparatively simple — now we can listen for a mouse event on our controls and run this function, as well as stop it when the mouse is released: ```js // for each of our controls, move the boombox and change the position values diff --git a/files/en-us/web/api/web_authentication_api/attestation_and_assertion/index.md b/files/en-us/web/api/web_authentication_api/attestation_and_assertion/index.md index 7de68c37ac4463c..dc32c12374a9170 100644 --- a/files/en-us/web/api/web_authentication_api/attestation_and_assertion/index.md +++ b/files/en-us/web/api/web_authentication_api/attestation_and_assertion/index.md @@ -19,7 +19,7 @@ The attestation is returned through the WebAuthn API as the [AuthenticatorAttest - [Authenticator data](/en-US/docs/Web/API/Web_Authentication_API/Authenticator_data) containing an `attestedCredentialData` field, which in turn contains the `credentialId` and `credentialPublicKey`. The `attestedCredentialData` is an optional field used in attestation. It is not included when used in the AuthenticatorAssertionResponse. - An attestation statement, which is optionally present depending on whether the relying party requests attestation. In general, relying parties aren't encouraged to request attestation, so it's more likely that this statement won't be present. -Different devices have different attestation formats. The [pre-defined attestation formats in WebAuthn](https://www.w3.org/TR/webauthn/#defined-attestation-formats) are: +Different devices have different attestation formats. The [pre-defined attestation formats in WebAuthn](https://w3c.github.io/webauthn/#sctn-defined-attestation-formats) are: - **Packed** - a generic attestation format that is commonly used by devices whose sole function is as a WebAuthn authenticator, such as security keys. - **TPM** - the Trusted Platform Module (TPM) is a set of specifications from the Trusted Platform Group (TPG). This attestation format is commonly found in desktop computers and is used by Windows Hello as its preferred attestation format. diff --git a/files/en-us/web/api/web_authentication_api/index.md b/files/en-us/web/api/web_authentication_api/index.md index 8cdde8032ca2333..750ffe74f9dd189 100644 --- a/files/en-us/web/api/web_authentication_api/index.md +++ b/files/en-us/web/api/web_authentication_api/index.md @@ -15,7 +15,7 @@ WebAuthn uses [asymmetric (public-key) cryptography](https://en.wikipedia.org/wi - **Protection against phishing:** An attacker who creates a fake login website can't login as the user because the signature changes with the [origin](/en-US/docs/Glossary/Origin) of the website. - **Reduced impact of data breaches:** Developers don't need to hash the public key, and if an attacker gets access to the public key used to verify the authentication, it can't authenticate because it needs the private key. -- **Invulnerable to password attacks:** Some users might reuse passwords, and an attacker may obtain the user's password for another website (e.g. via a data breach). Also, text passwords are much easier to brute-force than a digital signature. +- **Invulnerable to password attacks:** Some users might reuse passwords, and an attacker may obtain the user's password for another website (e.g., via a data breach). Also, text passwords are much easier to brute-force than a digital signature. Many websites already have pages that allow users to register new accounts or log into an existing account, and WebAuthn acts as a replacement or enhancement for the authentication part of the system. It extends the [Credential Management API](/en-US/docs/Web/API/Credential_Management_API), abstracting communication between the user agent and an authenticator and providing the following new functionality: @@ -47,15 +47,15 @@ To illustrate how the credential creation process works, let's describe the typi ```js let credential = await navigator.credentials.create({ publicKey: { - challenge: new Uint8Array([117, 61, 252, 231, 191, 241, ...]), + challenge: new Uint8Array([117, 61, 252, 231, 191, 241 /* … */]), rp: { id: "acme.com", name: "ACME Corporation" }, user: { id: new Uint8Array([79, 252, 83, 72, 214, 7, 89, 26]), name: "jamiedoe", - displayName: "Jamie Doe" + displayName: "Jamie Doe", }, - pubKeyCredParams: [ {type: "public-key", alg: -7} ] - } + pubKeyCredParams: [{ type: "public-key", alg: -7 }], + }, }); ``` @@ -92,14 +92,16 @@ A typical authentication flow is as follows: ```js let credential = await navigator.credentials.get({ publicKey: { - challenge: new Uint8Array([139, 66, 181, 87, 7, 203, ...]), + challenge: new Uint8Array([139, 66, 181, 87, 7, 203 /* … */]), rpId: "acme.com", - allowCredentials: [{ - type: "public-key", - id: new Uint8Array([64, 66, 25, 78, 168, 226, 174, ...]) - }], + allowCredentials: [ + { + type: "public-key", + id: new Uint8Array([64, 66, 25, 78, 168, 226, 174 /* … */]), + }, + ], userVerification: "required", - } + }, }); ``` @@ -125,7 +127,7 @@ A discoverable credential is created via a [`create()`](/en-US/docs/Web/API/Cred In order to authenticate, the RP server calls [`get()`](/en-US/docs/Web/API/CredentialsContainer/get) with **conditional mediation** specified, that is [`mediation`](/en-US/docs/Web/API/CredentialsContainer/get#mediation) set to `conditional`, an empty [`allowCredentials`](/en-US/docs/Web/API/PublicKeyCredentialRequestOptions#allowcredentials) list (meaning only discoverable credentials can be shown), and a challenge. -Conditional mediation results in discoverable credentials found in the authenticator being presented to the user in a non-modal UI along with an indication of the origin requesting credentials, rather than a modal dialog. In practice, this means autofilling available credentials in your login forms. The metadata stored in discoverable credentials can be displayed to help users choose a credential when logging in. To display discoverable credentials in your login forms, you also need to include [`autocomplete="webauthn"`](/en-US/docs/Web/HTML/Attributes/autocomplete#webauthn) on your form fields. +Conditional mediation results in discoverable credentials found in the authenticator being presented to the user in a non-modal UI along with an indication of the origin requesting credentials, rather than a modal dialog. In practice, this means autofilling available credentials in your login forms. The metadata stored in discoverable credentials can be displayed to help users choose a credential when logging in. To display discoverable credentials in your login forms, you also need to include [`autocomplete="webauthn"`](/en-US/docs/Web/HTML/Reference/Attributes/autocomplete#webauthn) on your form fields. To reiterate, the relying party doesn't tell the authenticator what credentials to offer to the user — instead, the authenticator supplies the list it has available. Once the user selects a credential, the authenticator uses it to sign the challenge with the associated private key, and the browser returns the signed challenge and its `credentialId` to the RP server. @@ -163,7 +165,7 @@ The signup and login workflows can be customized based on the capabilities of th This can be used, for example, to check: - Client support for various authenticators such as passkeys or biometric user verification. -- Whether the client [supports methods to keep relying party and authenticator credentials in sync](/en-US/docs/Web/API/Web_Authentication_API#discoverable_credential_synchronization_methods). +- Whether the client [supports methods to keep relying party and authenticator credentials in sync](#discoverable_credential_synchronization_methods). - Whether the client allows a single passkey to be used on different websites with the same origin. The code below shows how you might use `getClientCapabilities()` to check if the client supports authenticators that offer biometric user verification. @@ -184,15 +186,15 @@ async function checkIsUserVerifyingPlatformAuthenticatorAvailable() { ## Controlling access to the API -The availability of WebAuthn can be controlled using a [Permissions Policy](/en-US/docs/Web/HTTP/Permissions_Policy), specifying two directives in particular: +The availability of WebAuthn can be controlled using a [Permissions Policy](/en-US/docs/Web/HTTP/Guides/Permissions_Policy), specifying two directives in particular: - {{httpheader("Permissions-Policy/publickey-credentials-create", "publickey-credentials-create")}}: Controls the availability of {{domxref("CredentialsContainer.create", "navigator.credentials.create()")}} with the `publicKey` option. - {{httpheader("Permissions-Policy/publickey-credentials-get", "publickey-credentials-get")}}: Controls the availability of {{domxref("CredentialsContainer.get", "navigator.credentials.get()")}} with the `publicKey` option. Both directives have a default allowlist value of `"self"`, meaning that by default these methods can be used in top-level document contexts. In addition, `get()` can be used in nested browsing contexts loaded from the same origin as the top-most document. -`get()` and `create()` can be used in nested browsing contexts loaded from the different origins to the top-most document (i.e. in cross-origin `<iframes>`), if allowed by the [`publickey-credentials-get`](/en-US/docs/Web/HTTP/Headers/Permissions-Policy/publickey-credentials-get) and [`publickey-credentials-create`](/en-US/docs/Web/HTTP/Headers/Permissions-Policy/publickey-credentials-create) `Permission-Policy` directives, respectively. -For cross-origin `create()` calls, where the permission was granted by [`allow=` on an iframe](/en-US/docs/Web/HTTP/Headers/Permissions-Policy#iframes), the frame must also have {{glossary("Transient activation")}}. +`get()` and `create()` can be used in nested browsing contexts loaded from the different origins to the top-most document (i.e., in cross-origin `<iframes>`), if allowed by the [`publickey-credentials-get`](/en-US/docs/Web/HTTP/Reference/Headers/Permissions-Policy/publickey-credentials-get) and [`publickey-credentials-create`](/en-US/docs/Web/HTTP/Reference/Headers/Permissions-Policy/publickey-credentials-create) `Permission-Policy` directives, respectively. +For cross-origin `create()` calls, where the permission was granted by [`allow=` on an iframe](/en-US/docs/Web/HTTP/Reference/Headers/Permissions-Policy#iframes), the frame must also have {{glossary("Transient activation")}}. > [!NOTE] > Where a policy forbids use of these methods, the {{jsxref("Promise", "promises", "", 1)}} returned by them will reject with a `NotAllowedError` {{domxref("DOMException")}}. diff --git a/files/en-us/web/api/web_authentication_api/webauthn_extensions/index.md b/files/en-us/web/api/web_authentication_api/webauthn_extensions/index.md index 183dbb6c2580cb7..06934f1fa274465 100644 --- a/files/en-us/web/api/web_authentication_api/webauthn_extensions/index.md +++ b/files/en-us/web/api/web_authentication_api/webauthn_extensions/index.md @@ -5,6 +5,9 @@ page-type: guide browser-compat: - api.CredentialsContainer.create.publicKey_option.extensions - api.CredentialsContainer.get.publicKey_option.extensions +spec-urls: + - https://w3c.github.io/webauthn/#sctn-defined-extensions + - https://fidoalliance.org/specs/fido-v2.1-ps-20210615/fido-client-to-authenticator-protocol-v2.1-ps-20210615.html#sctn-defined-extensions --- {{DefaultAPISidebar("Web Authentication API")}} @@ -24,22 +27,22 @@ For example, in a `publicKey` object for a `create()` call, we might want to req ```js const publicKey = { - challenge: new Uint8Array([117, 61, 252, 231, 191, 241, ...]), + challenge: new Uint8Array([117, 61, 252, 231, 191, 241 /* … */]), rp: { id: "acme.com", name: "ACME Corporation" }, user: { id: new Uint8Array([79, 252, 83, 72, 214, 7, 89, 26]), name: "jamiedoe", - displayName: "Jamie Doe" + displayName: "Jamie Doe", }, - pubKeyCredParams: [ {type: "public-key", alg: -7} ], + pubKeyCredParams: [{ type: "public-key", alg: -7 }], authenticatorSelection: { - residentKey: "preferred" + residentKey: "preferred", }, extensions: { credProps: true, - minPinLength: true - } -} + minPinLength: true, + }, +}; ``` We can then pass the `publicKey` object into a `create()` call to initiate the credential creation flow: @@ -99,21 +102,25 @@ Allows a relying party to request an assertion for a credential previously regis The `publicKey`'s `extensions` property must contain an `appid` property, the value of which is the application identifier used in the legacy API. For example: ```js -extensions: { - appid: "https://accounts.example.com"; -} +({ + extensions: { + appid: "https://accounts.example.com", + }, +}); ``` You must also list the FIDO U2F credential IDs in the `publicKey`'s `allowCredentials` property, for example: ```js -allowCredentials: { - [ - id: arrayBuffer, // needs to contain decoded binary form of id - transports: ["nfc", "usb"] - type: "public-key" - ] -} +({ + allowCredentials: [ + { + id: arrayBuffer, // needs to contain decoded binary form of id + transports: ["nfc", "usb"], + type: "public-key", + }, + ], +}); ``` #### Output @@ -133,21 +140,25 @@ Allows a relying party to exclude authenticators containing specified credential The `publicKey`'s `extensions` property must contain an `appidExclude` property, the value of which is the identifier of the relying party requesting to exclude authenticators by legacy FIDO U2F credentials. For example: ```js -extensions: { - appidExclude: "https://accounts.example.com"; -} +({ + extensions: { + appidExclude: "https://accounts.example.com", + }, +}); ``` You can then list FIDO U2F credentials in the `publicKey`'s `excludeCredentials` property, for example: ```js -excludeCredentials: { - [ - id: arrayBuffer, // needs to contain decoded binary form of id - transports: ["nfc", "usb"] - type: "public-key" - ] -} +({ + excludeCredentials: [ + { + id: arrayBuffer, // needs to contain decoded binary form of id + transports: ["nfc", "usb"], + type: "public-key", + }, + ], +}); ``` #### Output @@ -167,17 +178,21 @@ Allows a relying party to request additional information/properties about the cr The `publicKey`'s `extensions` property must contain a `credProps` property with a value of `true`: ```js -extensions: { - credProps: true; -} +({ + extensions: { + credProps: true, + }, +}); ``` You must also set `authenticatorSelection.requireResidentKey` to `true`, which indicates that a resident key is required. ```js -authenticatorSelection: { - requireResidentKey: true; -} +({ + authenticatorSelection: { + requireResidentKey: true, + }, +}); ``` #### Output @@ -185,9 +200,11 @@ authenticatorSelection: { Outputs the following if the registered {{domxref("PublicKeyCredential")}} is a client-side discoverable credential: ```js -credProps: { - rk: true; -} +({ + credProps: { + rk: true, + }, +}); ``` If `rk` is set to `false` in the output, the credential is a server-side credential. If `rk` is not present in the output, then it is not known whether the credential is client-side discoverable or server-side. @@ -205,10 +222,12 @@ Allows a relying party to specify a minimum credential protection policy when cr The `publicKey`'s `extensions` property must contain a `credentialProtectionPolicy` property specifying the protection level of the credential to be created, and a boolean `enforceCredentialProtectionPolicy` property specifying whether the `create()` call should fail rather than creating a credential that does not conform to the specified policy: ```js -extensions: { - credentialProtectionPolicy: "userVerificationOptional", - enforceCredentialProtectionPolicy: true -} +({ + extensions: { + credentialProtectionPolicy: "userVerificationOptional", + enforceCredentialProtectionPolicy: true, + }, +}); ``` The available `credentialProtectionPolicy` values are as follows: @@ -234,7 +253,7 @@ The available `credentialProtectionPolicy` values are as follows: If the `create()` call is successful, the authenticator data will contain a representation of the `credProtect` value representing the set policy in the following form: ```js -{ "credProtect": 0x01 } +({ credProtect: 0x01 }); ``` ### `largeBlob` @@ -250,11 +269,13 @@ Allows a relying party to store blobs associated with a credential on the authen During a `create()` call, the `publicKey`'s `extensions` property must contain a `largeBlob` property with the following object structure: ```js -extensions: { - largeBlob: { - support: "required"; - } -} +({ + extensions: { + largeBlob: { + support: "required", + }, + }, +}); ``` The `support` property's value is a string, which can be one of the following: @@ -267,21 +288,25 @@ During a `get()` call, the `publicKey`'s `extensions` property must contain a `l The `read` property is a boolean. A value of `true` indicates that the relying party would like to fetch a previously-written blob associated with the asserted credential: ```js -extensions: { - largeBlob: { - read: true; - } -} +({ + extensions: { + largeBlob: { + read: true, + }, + }, +}); ``` The `write` property takes as a value an {{jsxref("ArrayBuffer")}}, {{jsxref("TypedArray")}}, or {{jsxref("DataView")}} representing a blob that the relying party wants to store alongside an existing credential: ```js -extensions: { - largeBlob: { - write: arrayBuffer; - } -} +({ + extensions: { + largeBlob: { + write: arrayBuffer, + }, + }, +}); ``` > [!NOTE] @@ -292,17 +317,21 @@ extensions: { A successful `create()` call provides the following extension output if the registered credential is capable of storing blobs: ```js -largeBlob: { - supported: true; // false if it cannot store blobs -} +({ + largeBlob: { + supported: true, // false if it cannot store blobs + }, +}); ``` A `get()` read call makes the blob available as an {{jsxref("ArrayBuffer")}} in the extension output if successful: ```js -largeBlob: { - blob: arrayBuffer; -} +({ + largeBlob: { + blob: arrayBuffer, + }, +}); ``` > [!NOTE] @@ -311,9 +340,11 @@ largeBlob: { A `get()` write call indicates whether the write operation was successful with a `written` boolean value in the extension output. A `true` value means it was written successfully to the associated authenticator, and `false` means it was unsuccessful. ```js -largeBlob: { - written: true; -} +({ + largeBlob: { + written: true, + }, +}); ``` ### `minPinLength` @@ -329,9 +360,11 @@ Allows relying parties to request the authenticator's minimum PIN length. The `publicKey`'s `extensions` property must contain a `minPinLength` property with a value of `true`: ```js -extensions: { - minPinLength: true; -} +({ + extensions: { + minPinLength: true, + }, +}); ``` #### Output @@ -339,7 +372,7 @@ extensions: { If the relying party is authorized to receive the `minPinLength` value (if its `rpId` is present on the authenticator's authorized relying party list), the authenticator data will contain a representation of it in the following form: ```js -{"minPinLength": uint} +({ minPinLength: uint }); ``` If the relying party is not authorized, the extension is ignored, and no `"minPinLength"` output value is provided. @@ -379,10 +412,7 @@ None There are a number of places that WebAuthn extensions are specified. IANA's [WebAuthn Extension Identifiers](https://www.iana.org/assignments/webauthn/webauthn.xhtml#webauthn-extension-ids) provides a registry of all extensions, but bear in mind that some may be deprecated. -Places where extensions are specified: - -- [Web Authentication Level 3, Section 10: Defined extensions](https://w3c.github.io/webauthn/#sctn-defined-extensions) -- [Client to Authenticator Protocol (CTAP) 2, Section 12: Defined Extensions](https://fidoalliance.org/specs/fido-v2.1-ps-20210615/fido-client-to-authenticator-protocol-v2.1-ps-20210615.html#sctn-defined-extensions) +{{Specifications}} ## Browser compatibility diff --git a/files/en-us/web/api/web_bluetooth_api/index.md b/files/en-us/web/api/web_bluetooth_api/index.md index 18f8e7152ee944a..0e37c92e7fafe9a 100644 --- a/files/en-us/web/api/web_bluetooth_api/index.md +++ b/files/en-us/web/api/web_bluetooth_api/index.md @@ -44,7 +44,7 @@ The Bluetooth API extends the following APIs, adding the listed features. The Web Bluetooth API can only be used in a secure context. -Access to the API is controlled by the [Permissions Policy](/en-US/docs/Web/HTTP/Permissions_Policy) directive {{HTTPHeader("Permissions-Policy/bluetooth","bluetooth")}}. +Access to the API is controlled by the [Permissions Policy](/en-US/docs/Web/HTTP/Guides/Permissions_Policy) directive {{HTTPHeader("Permissions-Policy/bluetooth","bluetooth")}}. The default allowlist for the `bluetooth` policy is `self`, which enables Bluetooth usage in same-origin nested frames but prevents access by third-party content by default. Cross-origin access is enabled by specifying the allowed origins in both the `Permissions-Policy: bluetooth` HTTP header and the desired `<iframe>`. @@ -73,7 +73,7 @@ const btPermission = await navigator.permissions.query({ name: "bluetooth", deviceId: sessionStorage.lastDevice, }); -if (result.devices.length == 1) { +if (result.devices.length === 1) { return result.devices[0]; } else { throw new DOMException("Lost permission", "NotFoundError"); diff --git a/files/en-us/web/api/web_components/index.md b/files/en-us/web/api/web_components/index.md index 8ec91d7037e7dc0..acaf5e749651034 100644 --- a/files/en-us/web/api/web_components/index.md +++ b/files/en-us/web/api/web_components/index.md @@ -66,7 +66,7 @@ The basic approach for implementing a web component generally looks something li - : The following extensions are defined: - - The [`is`](/en-US/docs/Web/HTML/Global_attributes/is) global HTML attribute + - The [`is`](/en-US/docs/Web/HTML/Reference/Global_attributes/is) global HTML attribute - : Allows you to specify that a standard HTML element should behave like a registered custom built-in element. - The "is" option of the {{domxref("Document.createElement()")}} method - : Allows you to create an instance of a standard HTML element that behaves like a given registered custom built-in element. @@ -92,7 +92,7 @@ The basic approach for implementing a web component generally looks something li - : Pseudo-elements relating specifically to custom elements: - {{cssxref("::part")}} - - : Represents any element within a [shadow tree](/en-US/docs/Web/API/Web_components/Using_shadow_DOM) that has a matching [`part`](/en-US/docs/Web/HTML/Global_attributes/part) attribute. + - : Represents any element within a [shadow tree](/en-US/docs/Web/API/Web_components/Using_shadow_DOM) that has a matching [`part`](/en-US/docs/Web/HTML/Reference/Global_attributes/part) attribute. ### Shadow DOM @@ -110,7 +110,7 @@ The basic approach for implementing a web component generally looks something li - : Additions to the `Node` interface relevant to shadow DOM: - The {{domxref("Node.getRootNode()")}} method returns the context object's root, which optionally includes the shadow root if it is available. - - The {{domxref("Node.isConnected")}} property returns a boolean indicating whether or not the Node is connected (directly or indirectly) to the context object, e.g. the {{domxref("Document")}} object in the case of the normal DOM, or the {{domxref("ShadowRoot")}} in the case of a shadow DOM. + - The {{domxref("Node.isConnected")}} property returns a boolean indicating whether or not the Node is connected (directly or indirectly) to the context object, e.g., the {{domxref("Document")}} object in the case of the normal DOM, or the {{domxref("ShadowRoot")}} in the case of a shadow DOM. - {{domxref("Event")}} extensions @@ -127,7 +127,7 @@ The basic approach for implementing a web component generally looks something li - : Contains an HTML fragment that is not rendered when a containing document is initially loaded, but can be displayed at runtime using JavaScript, mainly used as the basis of custom element structures. The associated DOM interface is {{domxref("HTMLTemplateElement")}}. - {{htmlelement("slot")}} - : A placeholder inside a web component that you can fill with your own markup, which lets you create separate DOM trees and present them together. The associated DOM interface is {{domxref("HTMLSlotElement")}}. -- The [`slot`](/en-US/docs/Web/HTML/Global_attributes/slot) global HTML attribute +- The [`slot`](/en-US/docs/Web/HTML/Reference/Global_attributes/slot) global HTML attribute - : Assigns a slot in a shadow DOM shadow tree to an element. - {{domxref("Element.assignedSlot")}} - : A read-only attribute which returns a reference to the {{htmlelement("slot")}} in which this element is inserted. diff --git a/files/en-us/web/api/web_components/using_custom_elements/index.md b/files/en-us/web/api/web_components/using_custom_elements/index.md index ebfaa9b5cb8ebd6..12779e20cb98b52 100644 --- a/files/en-us/web/api/web_components/using_custom_elements/index.md +++ b/files/en-us/web/api/web_components/using_custom_elements/index.md @@ -14,12 +14,12 @@ This article introduces custom elements, and walks through some examples. There are two types of custom element: +- **Autonomous custom elements** inherit from the HTML element base class {{domxref("HTMLElement")}}. You have to implement their behavior from scratch. + - **Customized built-in elements** inherit from standard HTML elements such as {{domxref("HTMLImageElement")}} or {{domxref("HTMLParagraphElement")}}. Their implementation extends the behavior of select instances of the standard element. > [!NOTE] - > Safari does not plan to support custom built-in elements. See the [`is` attribute](/en-US/docs/Web/HTML/Global_attributes/is) for more information. - -- **Autonomous custom elements** inherit from the HTML element base class {{domxref("HTMLElement")}}. You have to implement their behavior from scratch. + > Safari does not plan to support custom built-in elements. See the [`is` attribute](/en-US/docs/Web/HTML/Reference/Global_attributes/is) for more information. ## Implementing a custom element @@ -55,10 +55,11 @@ Once your custom element is registered, the browser will call certain methods of Custom element lifecycle callbacks include: -- `connectedCallback()`: called each time the element is added to the document. The specification recommends that, as far as possible, developers should implement custom element setup in this callback rather than the constructor. -- `disconnectedCallback()`: called each time the element is removed from the document. -- `adoptedCallback()`: called each time the element is moved to a new document. -- `attributeChangedCallback()`: called when attributes are changed, added, removed, or replaced. See [Responding to attribute changes](#responding_to_attribute_changes) for more details about this callback. +- `connectedCallback()`: Called each time the element is added to the document. The specification recommends that, as far as possible, developers should implement custom element setup in this callback rather than the constructor. +- `disconnectedCallback()`: Called each time the element is removed from the document. +- `connectedMoveCallback()`: When defined, this is called _instead of_ `connectedCallback()` and `disconnectedCallback()` each time the element is moved to a different place in the DOM via {{domxref("Element.moveBefore()")}}. Use this to avoid running initialization/cleanup code in the `connectedCallback()` and `disconnectedCallback()` callbacks when the element is not actually being added to or removed from the DOM. See [Lifecycle callbacks and state-preserving moves](#lifecycle_callbacks_and_state-preserving_moves) for more details. +- `adoptedCallback()`: Called each time the element is moved to a new document. +- `attributeChangedCallback()`: Called when attributes are changed, added, removed, or replaced. See [Responding to attribute changes](#responding_to_attribute_changes) for more details about this callback. Here's a minimal custom element that logs these lifecycle events: @@ -80,6 +81,10 @@ class MyCustomElement extends HTMLElement { console.log("Custom element removed from page."); } + connectedMoveCallback() { + console.log("Custom element moved with moveBefore()"); + } + adoptedCallback() { console.log("Custom element moved to new page."); } @@ -92,6 +97,24 @@ class MyCustomElement extends HTMLElement { customElements.define("my-custom-element", MyCustomElement); ``` +#### Lifecycle callbacks and state-preserving moves + +The position of a custom element in the DOM can be manipulated just like any regular HTML element, but there are lifecycle side-effects to consider. + +Each time a custom element is moved (via methods such as {{domxref("Element.moveBefore()")}} or {{domxref("Node.insertBefore()")}}), the `disconnectedCallback()` and `connectedCallback()` lifecycle callbacks are fired, because the element is disconnected from and reconnected to the DOM. + +This might be your intended behavior. However, since these callbacks are typically used to implement any required initialization or cleanup code to run at the start or end of the element's lifecycle, running them when the element is moved (rather than removed or inserted) may cause problems with its state. You might for example remove some stored data that the element still needs. + +If you want to preserve the element's state, you can do so by defining a `connectedMoveCallback()` lifecycle callback inside the element class, and then using the {{domxref("Element.moveBefore()")}} method to move the element (instead of similar methods such as {{domxref("Node.insertBefore()")}}). This causes the `connectedMoveCallback()` to run instead of `connectedCallback()` and `disconnectedCallback()`. + +You could add an empty `connectedMoveCallback()` to stop the other two callbacks running, or include some custom logic to handle the move: + +```js +connectedMoveCallback() { + console.log("Custom move-handling logic here."); +} +``` + ## Registering a custom element To make a custom element available in a page, call the {{domxref("CustomElementRegistry.define()", "define()")}} method of {{domxref("Window.customElements")}}. @@ -121,7 +144,7 @@ customElements.define("popup-info", PopupInfo); Once you've defined and registered a custom element, you can use it in your code. -To use a customized built-in element, use the built-in element but with the custom name as the value of the [`is`](/en-US/docs/Web/HTML/Global_attributes/is) attribute: +To use a customized built-in element, use the built-in element but with the custom name as the value of the [`is`](/en-US/docs/Web/HTML/Reference/Global_attributes/is) attribute: ```html <p is="word-count"></p> @@ -428,7 +451,7 @@ Now let's have a look at a customized built in element example. This example ext - [See the source code](https://github.com/mdn/web-components-examples/tree/main/expanding-list-web-component) > [!NOTE] -> Please see the [`is`](/en-US/docs/Web/HTML/Global_attributes/is) attribute reference for caveats on implementation reality of custom built-in elements. +> Please see the [`is`](/en-US/docs/Web/HTML/Reference/Global_attributes/is) attribute reference for caveats on implementation reality of custom built-in elements. First of all, we define our element's class: @@ -475,7 +498,7 @@ class ExpandingList extends HTMLUListElement { const nextUl = e.target.nextElementSibling; // Toggle visible state and update class attribute on ul - if (nextUl.style.display == "block") { + if (nextUl.style.display === "block") { nextUl.style.display = "none"; nextUl.parentNode.setAttribute("class", "closed"); } else { @@ -512,7 +535,7 @@ Using the built-in element in a web document also looks somewhat different: You use a `<ul>` element as normal, but specify the name of the custom element inside the `is` attribute. -Note that in this case we must ensure that the script defining our custom element is executed after the DOM has been fully parsed, because `connectedCallback()` is called as soon as the expanding list is added to the DOM, and at that point its children have not been added yet, so the `querySelectorAll()` calls will not find any items. One way to ensure this is to add the [defer](/en-US/docs/Web/HTML/Element/script#defer) attribute to the line that includes the script: +Note that in this case we must ensure that the script defining our custom element is executed after the DOM has been fully parsed, because `connectedCallback()` is called as soon as the expanding list is added to the DOM, and at that point its children have not been added yet, so the `querySelectorAll()` calls will not find any items. One way to ensure this is to add the [defer](/en-US/docs/Web/HTML/Reference/Elements/script#defer) attribute to the line that includes the script: ```html <script src="main.js" defer></script> @@ -528,16 +551,20 @@ So far we've seen only one lifecycle callback in action: `connectedCallback()`. In the class constructor, we attach a shadow DOM to the element, then attach empty {{htmlelement("div")}} and {{htmlelement("style")}} elements to the shadow root: ```js -constructor() { - // Always call super first in constructor - super(); +class Square extends HTMLElement { + // … + constructor() { + // Always call super first in constructor + super(); - const shadow = this.attachShadow({ mode: "open" }); + const shadow = this.attachShadow({ mode: "open" }); - const div = document.createElement("div"); - const style = document.createElement("style"); - shadow.appendChild(style); - shadow.appendChild(div); + const div = document.createElement("div"); + const style = document.createElement("style"); + shadow.appendChild(style); + shadow.appendChild(div); + } + // … } ``` @@ -559,37 +586,53 @@ function updateStyle(elem) { The actual updates are all handled by the lifecycle callbacks. The `connectedCallback()` runs each time the element is added to the DOM — here we run the `updateStyle()` function to make sure the square is styled as defined in its attributes: ```js -connectedCallback() { - console.log("Custom square element added to page."); - updateStyle(this); +class Square extends HTMLElement { + // … + connectedCallback() { + console.log("Custom square element added to page."); + updateStyle(this); + } + // … } ``` The `disconnectedCallback()` and `adoptedCallback()` callbacks log messages to the console to inform us when the element is either removed from the DOM, or moved to a different page: ```js -disconnectedCallback() { - console.log("Custom square element removed from page."); -} +class Square extends HTMLElement { + // … + disconnectedCallback() { + console.log("Custom square element removed from page."); + } -adoptedCallback() { - console.log("Custom square element moved to new page."); + adoptedCallback() { + console.log("Custom square element moved to new page."); + } + // … } ``` The `attributeChangedCallback()` callback is run whenever one of the element's attributes is changed in some way. As you can see from its parameters, it is possible to act on attributes individually, looking at their name, and old and new attribute values. In this case however, we are just running the `updateStyle()` function again to make sure that the square's style is updated as per the new values: ```js -attributeChangedCallback(name, oldValue, newValue) { - console.log("Custom square element attributes changed."); - updateStyle(this); +class Square extends HTMLElement { + // … + attributeChangedCallback(name, oldValue, newValue) { + console.log("Custom square element attributes changed."); + updateStyle(this); + } + // … } ``` Note that to get the `attributeChangedCallback()` callback to fire when an attribute changes, you have to observe the attributes. This is done by specifying a `static get observedAttributes()` method inside the custom element class - this should return an array containing the names of the attributes you want to observe: ```js -static get observedAttributes() { - return ["color", "size"]; +class Square extends HTMLElement { + // … + static get observedAttributes() { + return ["color", "size"]; + } + // … } ``` diff --git a/files/en-us/web/api/web_components/using_shadow_dom/index.md b/files/en-us/web/api/web_components/using_shadow_dom/index.md index 4b24a32f5e8217a..f03c3b61b808838 100644 --- a/files/en-us/web/api/web_components/using_shadow_dom/index.md +++ b/files/en-us/web/api/web_components/using_shadow_dom/index.md @@ -66,13 +66,13 @@ Before shadow DOM was made available to web developers, browsers were already us ### Attribute inheritance -The shadow tree and {{ HTMLElement("slot") }} elements inherit the [`dir`](/en-US/docs/Web/HTML/Global_attributes/dir) and [`lang`](/en-US/docs/Web/HTML/Global_attributes/lang) attributes from their shadow host. +The shadow tree and {{ HTMLElement("slot") }} elements inherit the [`dir`](/en-US/docs/Web/HTML/Reference/Global_attributes/dir) and [`lang`](/en-US/docs/Web/HTML/Reference/Global_attributes/lang) attributes from their shadow host. ## Creating a shadow DOM ### Imperatively with JavaScript -The following page contains two elements, a {{htmlelement("div")}} element with an [`id`](/en-US/docs/Web/HTML/Global_attributes/id) of `"host"`, and a {{htmlelement("span")}} element containing some text: +The following page contains two elements, a {{htmlelement("div")}} element with an [`id`](/en-US/docs/Web/HTML/Reference/Global_attributes/id) of `"host"`, and a {{htmlelement("span")}} element containing some text: ```html <div id="host"></div> diff --git a/files/en-us/web/api/web_components/using_templates_and_slots/index.md b/files/en-us/web/api/web_components/using_templates_and_slots/index.md index 3d463ffafe0372c..a9cb03200901e90 100644 --- a/files/en-us/web/api/web_components/using_templates_and_slots/index.md +++ b/files/en-us/web/api/web_components/using_templates_and_slots/index.md @@ -95,7 +95,7 @@ So, if we want to add a slot into our trivial example, we could update our templ If the slot's content isn't defined when the element is included in the markup, or if the browser doesn't support slots, `<my-paragraph>` just contains the fallback content "My default text". -To define the slot's content, we include an HTML structure inside the `<my-paragraph>` element with a [`slot`](/en-US/docs/Web/HTML/Global_attributes/slot) attribute whose value is equal to the name of the slot we want it to fill. As before, this can be anything you like, for example: +To define the slot's content, we include an HTML structure inside the `<my-paragraph>` element with a [`slot`](/en-US/docs/Web/HTML/Reference/Global_attributes/slot) attribute whose value is equal to the name of the slot we want it to fill. As before, this can be anything you like, for example: ```html <my-paragraph> @@ -161,8 +161,8 @@ To finish off the article, let's look at something a little less trivial. The following set of code snippets show how to use {{HTMLElement("slot")}} together with {{HTMLElement("template")}} and some JavaScript to: -- create a **`<element-details>`** element with [named slots](/en-US/docs/Web/HTML/Element/slot#name) in its [shadow root](/en-US/docs/Web/API/ShadowRoot) -- design the **`<element-details>`** element in such a way that, when used in documents, it is rendered from composing the element's content together with content from its [shadow root](/en-US/docs/Web/API/ShadowRoot)—that is, pieces of the element's content are used to fill in [named slots](/en-US/docs/Web/HTML/Element/slot#name) in its [shadow root](/en-US/docs/Web/API/ShadowRoot) +- create a **`<element-details>`** element with [named slots](/en-US/docs/Web/HTML/Reference/Elements/slot#name) in its [shadow root](/en-US/docs/Web/API/ShadowRoot) +- design the **`<element-details>`** element in such a way that, when used in documents, it is rendered from composing the element's content together with content from its [shadow root](/en-US/docs/Web/API/ShadowRoot)—that is, pieces of the element's content are used to fill in [named slots](/en-US/docs/Web/HTML/Reference/Elements/slot#name) in its [shadow root](/en-US/docs/Web/API/ShadowRoot) Note that it is technically possible to use {{HTMLElement("slot")}} element without a {{HTMLElement("template")}} element, e.g., within say a regular {{HTMLElement("div")}} element, and still take advantage of the place-holder features of {{HTMLElement("slot")}} for Shadow DOM content, and doing so may indeed avoid the small trouble of needing to first access the template element's `content` property (and clone it). However, it is generally more practical to add slots within a {{HTMLElement("template")}} element, since you are unlikely to need to define a pattern based on an already-rendered element. @@ -174,7 +174,7 @@ In addition, even if it is not already rendered, the purpose of the container as ### Creating a template with some slots -First of all, we use the {{HTMLElement("slot")}} element within a {{HTMLElement("template")}} element to create a new "element-details-template" [document fragment](/en-US/docs/Web/API/DocumentFragment) containing some [named slots](/en-US/docs/Web/HTML/Element/slot#name): +First of all, we use the {{HTMLElement("slot")}} element within a {{HTMLElement("template")}} element to create a new "element-details-template" [document fragment](/en-US/docs/Web/API/DocumentFragment) containing some [named slots](/en-US/docs/Web/HTML/Reference/Elements/slot#name): ```html <template id="element-details-template"> @@ -233,13 +233,13 @@ First of all, we use the {{HTMLElement("slot")}} element within a {{HTMLElement( That {{HTMLElement("template")}} element has several features: - The {{HTMLElement("template")}} has a {{HTMLElement("style")}} element with a set of CSS styles that are scoped just to the document fragment the {{HTMLElement("template")}} creates. -- The {{HTMLElement("template")}} uses {{HTMLElement("slot")}} and its [`name`](/en-US/docs/Web/HTML/Element/slot#name) attribute to make three [named slots](/en-US/docs/Web/HTML/Element/slot#name): +- The {{HTMLElement("template")}} uses {{HTMLElement("slot")}} and its [`name`](/en-US/docs/Web/HTML/Reference/Elements/slot#name) attribute to make three [named slots](/en-US/docs/Web/HTML/Reference/Elements/slot#name): - `<slot name="element-name">` - `<slot name="description">` - `<slot name="attributes">` -- The {{HTMLElement("template")}} wraps the [named slots](/en-US/docs/Web/HTML/Element/slot#name) in a {{HTMLElement("details")}} element. +- The {{HTMLElement("template")}} wraps the [named slots](/en-US/docs/Web/HTML/Reference/Elements/slot#name) in a {{HTMLElement("details")}} element. ### Creating a new \<element-details> element from the \<template> @@ -291,9 +291,9 @@ Now let's take that **`<element-details>`** element and actually use it in our d About that snippet, notice these points: -- The snippet has two instances of **`<element-details>`** elements which both use the [`slot`](/en-US/docs/Web/HTML/Global_attributes/slot) attribute to reference the [named slots](/en-US/docs/Web/HTML/Element/slot#name) `"element-name"` and `"description"` we put in the `<element-details>` [shadow root](/en-US/docs/Web/API/ShadowRoot). -- Only the first of those two **`<element-details>`** elements references the `"attributes"` [named slot](/en-US/docs/Web/HTML/Element/slot#name). The second `<element-details>` element lacks any reference to the `"attributes"` [named slot](/en-US/docs/Web/HTML/Element/slot#name). -- The first `<element-details>` element references the `"attributes"` [named slot](/en-US/docs/Web/HTML/Element/slot#name) using a {{HTMLElement("dl")}} element with {{HTMLElement("dt")}} and {{HTMLElement("dd")}} children. +- The snippet has two instances of **`<element-details>`** elements which both use the [`slot`](/en-US/docs/Web/HTML/Reference/Global_attributes/slot) attribute to reference the [named slots](/en-US/docs/Web/HTML/Reference/Elements/slot#name) `"element-name"` and `"description"` we put in the `<element-details>` [shadow root](/en-US/docs/Web/API/ShadowRoot). +- Only the first of those two **`<element-details>`** elements references the `"attributes"` [named slot](/en-US/docs/Web/HTML/Reference/Elements/slot#name). The second `<element-details>` element lacks any reference to the `"attributes"` [named slot](/en-US/docs/Web/HTML/Reference/Elements/slot#name). +- The first `<element-details>` element references the `"attributes"` [named slot](/en-US/docs/Web/HTML/Reference/Elements/slot#name) using a {{HTMLElement("dl")}} element with {{HTMLElement("dt")}} and {{HTMLElement("dd")}} children. ### Adding a final bit of style @@ -329,7 +329,7 @@ Finally let's put all the snippets together and see what the rendered result loo Notice the following points about this rendered result: - Even though the instances of the **`<element-details>`** element in the document do not directly use the {{HTMLElement("details")}} element, they get rendered using {{HTMLElement("details")}} because the [shadow root](/en-US/docs/Web/API/ShadowRoot) causes them to get populated with that. -- Within the rendered {{HTMLElement("details")}} output, the content in the **`<element-details>`** elements fills the [named slots](/en-US/docs/Web/HTML/Element/slot#name) from the [shadow root](/en-US/docs/Web/API/ShadowRoot). In other words, the DOM tree from the **`<element-details>`** elements get _composed_ together with the content of the [shadow root](/en-US/docs/Web/API/ShadowRoot). -- For both **`<element-details>`** elements, an **Attributes** heading gets automatically added from the [shadow root](/en-US/docs/Web/API/ShadowRoot) before the position of the `"attributes"` [named slot](/en-US/docs/Web/HTML/Element/slot#name). -- Because the first **`<element-details>`** has a {{HTMLElement("dl")}} element which explicitly references the `"attributes"` [named slot](/en-US/docs/Web/HTML/Element/slot#name) from its [shadow root](/en-US/docs/Web/API/ShadowRoot), the contents of that {{HTMLElement("dl")}} replace the `"attributes"` [named slot](/en-US/docs/Web/HTML/Element/slot#name) from the [shadow root](/en-US/docs/Web/API/ShadowRoot). -- Because the second **`<element-details>`** doesn't explicitly reference the `"attributes"` [named slot](/en-US/docs/Web/HTML/Element/slot#name) from its [shadow root](/en-US/docs/Web/API/ShadowRoot), its content for that [named slot](/en-US/docs/Web/HTML/Element/slot#name) gets filled with the default content for it from the [shadow root](/en-US/docs/Web/API/ShadowRoot). +- Within the rendered {{HTMLElement("details")}} output, the content in the **`<element-details>`** elements fills the [named slots](/en-US/docs/Web/HTML/Reference/Elements/slot#name) from the [shadow root](/en-US/docs/Web/API/ShadowRoot). In other words, the DOM tree from the **`<element-details>`** elements get _composed_ together with the content of the [shadow root](/en-US/docs/Web/API/ShadowRoot). +- For both **`<element-details>`** elements, an **Attributes** heading gets automatically added from the [shadow root](/en-US/docs/Web/API/ShadowRoot) before the position of the `"attributes"` [named slot](/en-US/docs/Web/HTML/Reference/Elements/slot#name). +- Because the first **`<element-details>`** has a {{HTMLElement("dl")}} element which explicitly references the `"attributes"` [named slot](/en-US/docs/Web/HTML/Reference/Elements/slot#name) from its [shadow root](/en-US/docs/Web/API/ShadowRoot), the contents of that {{HTMLElement("dl")}} replace the `"attributes"` [named slot](/en-US/docs/Web/HTML/Reference/Elements/slot#name) from the [shadow root](/en-US/docs/Web/API/ShadowRoot). +- Because the second **`<element-details>`** doesn't explicitly reference the `"attributes"` [named slot](/en-US/docs/Web/HTML/Reference/Elements/slot#name) from its [shadow root](/en-US/docs/Web/API/ShadowRoot), its content for that [named slot](/en-US/docs/Web/HTML/Reference/Elements/slot#name) gets filled with the default content for it from the [shadow root](/en-US/docs/Web/API/ShadowRoot). diff --git a/files/en-us/web/api/web_crypto_api/non-cryptographic_uses_of_subtle_crypto/index.md b/files/en-us/web/api/web_crypto_api/non-cryptographic_uses_of_subtle_crypto/index.md index 7e7dcd017b68f5e..33e6348c16b29c5 100755 --- a/files/en-us/web/api/web_crypto_api/non-cryptographic_uses_of_subtle_crypto/index.md +++ b/files/en-us/web/api/web_crypto_api/non-cryptographic_uses_of_subtle_crypto/index.md @@ -20,7 +20,7 @@ If in doubt don't try doing it yourself, hire someone with experience and ensure This is the simplest useful thing you can do with the [Web Crypto API](/en-US/docs/Web/API/Web_Crypto_API). It doesn't involve generating keys or certificates and has one single step. -[Hashing](/en-US/docs/Glossary/Hash) is a technique where you convert a large string of bytes into a smaller string, where small changes to the long string result in large changes in the smaller string. This technique is useful for identifying two identical files without checking every byte of both files. This is very useful as you have a simple string to compare. To be clear hashing is a **one way** operation. You cannot generate the original string of bytes from the hash. +{{glossary("Hash function", "Hashing")}} is a technique where you convert a large string of bytes into a smaller string, where small changes to the long string result in large changes in the smaller string. This technique is useful for identifying two identical files without checking every byte of both files. This is very useful as you have a simple string to compare. To be clear hashing is a **one way** operation. You cannot generate the original string of bytes from the hash. If two generated hashes are the same, but the files that used to generate them are different, that is known as a _hash collision_ which is an extremely improbable thing to occur by accident and, for a secure hash function like SHA256, almost impossible to manufacture. So if the two strings are the same you can be reasonably sure the two original files are identical. @@ -102,7 +102,7 @@ async function hashTheseFiles(e) { At this point you may be thinking to yourself "_I can use this on my own website, so when users go to download a file we can ensure the hashes match to reassure the user their download is secure_". Unfortunately, this has two issues that immediately spring to mind: - Executable downloads should **always** be done over HTTPS. This prevents intermediate parties from performing attacks like this so it would be redundant. -- If the attacker is able to replace the download file on the original server, then they can also simply replace the code which invokes the SubtleCrypto interface to bypass it and just state that everything is fine. Probably something sneaky like replacing [strict equality](/en-US/docs/Web/JavaScript/Equality_comparisons_and_sameness#strict_equality_using), which can be a pain to spot in your own code: +- If the attacker is able to replace the download file on the original server, then they can also simply replace the code which invokes the SubtleCrypto interface to bypass it and just state that everything is fine. Probably something sneaky like replacing [strict equality](/en-US/docs/Web/JavaScript/Guide/Equality_comparisons_and_sameness#strict_equality_using), which can be a pain to spot in your own code: ```diff --- if (checksum === correctCheckSum) return true; diff --git a/files/en-us/web/api/web_locks_api/index.md b/files/en-us/web/api/web_locks_api/index.md index c7d52dafca0cfe3..c2180b7718db090 100644 --- a/files/en-us/web/api/web_locks_api/index.md +++ b/files/en-us/web/api/web_locks_api/index.md @@ -75,7 +75,7 @@ Several options can be passed when requesting a lock: ### Monitoring -The {{domxref("LockManager.query", "navigator.locks.query()")}} method can be used by scripts to introspect the state of the lock manager for the origin. This can be useful when debugging, for example, identifying why a lock could not be acquired. The results are a snapshot of the lock manager state, which identifies held and requested locks and some additional data (e.g. mode) about each, at the time the snapshot was taken. +The {{domxref("LockManager.query", "navigator.locks.query()")}} method can be used by scripts to introspect the state of the lock manager for the origin. This can be useful when debugging, for example, identifying why a lock could not be acquired. The results are a snapshot of the lock manager state, which identifies held and requested locks and some additional data (e.g., mode) about each, at the time the snapshot was taken. ### Advanced use diff --git a/files/en-us/web/api/web_midi_api/index.md b/files/en-us/web/api/web_midi_api/index.md index 72aefb5f9f1581c..72a308d519b4be8 100644 --- a/files/en-us/web/api/web_midi_api/index.md +++ b/files/en-us/web/api/web_midi_api/index.md @@ -40,7 +40,7 @@ Therefore, the API can be used for musical and non-musical uses, with any MIDI d Access to the API is requested using the {{domxref("navigator.requestMIDIAccess()")}} method. - The method must be called in a [secure context](/en-US/docs/Web/Security/Secure_Contexts). -- Access may be gated by the [`midi`](/en-US/docs/Web/HTTP/Headers/Permissions-Policy/midi) HTTP [Permission Policy](/en-US/docs/Web/HTTP/Permissions_Policy). +- Access may be gated by the [`midi`](/en-US/docs/Web/HTTP/Reference/Headers/Permissions-Policy/midi) HTTP [Permission Policy](/en-US/docs/Web/HTTP/Guides/Permissions_Policy). - The user must explicitly grant permission to use the API through a user-agent specific mechanism, or have previously granted permission. Note that if access is denied by a permission policy it cannot be granted by a user permission. diff --git a/files/en-us/web/api/web_share_api/index.md b/files/en-us/web/api/web_share_api/index.md index 3778f8af7e397ae..6e774f70ef2b913 100644 --- a/files/en-us/web/api/web_share_api/index.md +++ b/files/en-us/web/api/web_share_api/index.md @@ -30,7 +30,7 @@ The {{domxref("navigator.share()")}} method invokes the native sharing mechanism It requires {{Glossary("transient activation")}}, and hence must be triggered off a UI event like a button click. Further, the method must specify valid data that is supported for sharing by the native implementation. -The Web Share API is gated by the [web-share](/en-US/docs/Web/HTTP/Headers/Permissions-Policy/web-share) Permissions Policy. +The Web Share API is gated by the [web-share](/en-US/docs/Web/HTTP/Reference/Headers/Permissions-Policy/web-share) Permissions Policy. If the policy is supported but has not been granted, both methods will indicate that the data is not shareable. ## Interfaces diff --git a/files/en-us/web/api/web_speech_api/index.md b/files/en-us/web/api/web_speech_api/index.md index 47365c92c9b3e62..b01aaf3f2256f29 100644 --- a/files/en-us/web/api/web_speech_api/index.md +++ b/files/en-us/web/api/web_speech_api/index.md @@ -56,7 +56,7 @@ For more details on using these features, see [Using the Web Speech API](/en-US/ - : Contains information about the current state of {{domxref("SpeechSynthesisUtterance")}} objects that have been processed in the speech service. - {{domxref("SpeechSynthesisUtterance")}} - : Represents a speech request. - It contains the content the speech service should read and information about how to read it (e.g. language, pitch and volume.) + It contains the content the speech service should read and information about how to read it (e.g., language, pitch and volume.) - {{domxref("SpeechSynthesisVoice")}} - : Represents a voice that the system supports. Every `SpeechSynthesisVoice` has its own relative speech service including information about language, name and URI. @@ -85,5 +85,3 @@ The [Web Speech API examples](https://github.com/mdn/dom-examples/tree/main/web- ## See also - [Using the Web Speech API](/en-US/docs/Web/API/Web_Speech_API/Using_the_Web_Speech_API) -- [SitePoint article](https://www.sitepoint.com/talking-web-pages-and-the-speech-synthesis-api/) -- [HTML5Rocks article](https://developer.chrome.com/blog/web-apps-that-talk-introduction-to-the-speech-synthesis-api/) diff --git a/files/en-us/web/api/web_speech_api/using_the_web_speech_api/index.md b/files/en-us/web/api/web_speech_api/using_the_web_speech_api/index.md index 7c35c3a9bc2e665..51ff87714d458a5 100644 --- a/files/en-us/web/api/web_speech_api/using_the_web_speech_api/index.md +++ b/files/en-us/web/api/web_speech_api/using_the_web_speech_api/index.md @@ -70,7 +70,8 @@ const colors = [ "blue", "brown", "chocolate", - "coral" /* … */, + "coral", + // … ]; const grammar = `#JSGF V1.0; grammar colors; public <color> = ${colors.join( " | ", @@ -293,7 +294,8 @@ inputForm.onsubmit = (event) => { event.preventDefault(); const utterThis = new SpeechSynthesisUtterance(inputTxt.value); - const selectedOption = voiceSelect.selectedOptions[0].getAttribute('data-name'); + const selectedOption = + voiceSelect.selectedOptions[0].getAttribute("data-name"); for (const voice of voices) { if (voice.name === selectedOption) { utterThis.voice = voice; @@ -302,25 +304,19 @@ inputForm.onsubmit = (event) => { utterThis.pitch = pitch.value; utterThis.rate = rate.value; synth.speak(utterThis); -``` - -In the final part of the handler, we include a {{domxref("SpeechSynthesisUtterance.pause_event", "pause")}} event to demonstrate how {{domxref("SpeechSynthesisEvent")}} can be put to good use. When {{domxref("SpeechSynthesis.pause()")}} is invoked, this returns a message reporting the character number and name that the speech was paused at. - -```js -utterThis.onpause = (event) => { - const char = event.utterance.text.charAt(event.charIndex); - console.log( - `Speech paused at character ${event.charIndex} of "${event.utterance.text}", which is "${char}".`, - ); + utterThis.onpause = (event) => { + const char = event.utterance.text.charAt(event.charIndex); + console.log( + `Speech paused at character ${event.charIndex} of "${event.utterance.text}", which is "${char}".`, + ); + }; + inputTxt.blur(); }; ``` -Finally, we call [blur()](/en-US/docs/Web/API/HTMLElement/blur) on the text input. This is mainly to hide the keyboard on Firefox OS. +In the final part of the handler, we include a {{domxref("SpeechSynthesisUtterance.pause_event", "pause")}} event to demonstrate how {{domxref("SpeechSynthesisEvent")}} can be put to good use. When {{domxref("SpeechSynthesis.pause()")}} is invoked, this returns a message reporting the character number and name that the speech was paused at. -```js - inputTxt.blur(); -} -``` +Finally, we call [`blur()`](/en-US/docs/Web/API/HTMLElement/blur) on the text input. This is mainly to hide the keyboard on Firefox OS. #### Updating the displayed pitch and rate values diff --git a/files/en-us/web/api/web_workers_api/index.md b/files/en-us/web/api/web_workers_api/index.md index 9da2d41560ce6e5..6f067769669b3dc 100644 --- a/files/en-us/web/api/web_workers_api/index.md +++ b/files/en-us/web/api/web_workers_api/index.md @@ -11,7 +11,7 @@ spec-urls: https://html.spec.whatwg.org/multipage/workers.html#workers ## Concepts and usage -A worker is an object created using a constructor (e.g. {{DOMxRef("Worker.Worker", "Worker()")}}) that runs a named JavaScript file — this file contains the code that will run in the worker thread. +A worker is an object created using a constructor (e.g., {{DOMxRef("Worker.Worker", "Worker()")}}) that runs a named JavaScript file — this file contains the code that will run in the worker thread. In addition to the standard [JavaScript](/en-US/docs/Web/JavaScript) set of functions (such as {{jsxref("String")}}, {{jsxref("Array")}}, {{jsxref("Object")}}, {{jsxref("JSON")}}, etc.), you can run almost any code you like inside a worker thread. There are some exceptions: for example, you can't directly manipulate the DOM from inside a worker, or use some default methods and properties of the {{domxref("Window")}} object. For information about the code that you _can_ run see [supported functions](/en-US/docs/Web/API/Web_Workers_API/Functions_and_classes_available_to_workers#functions_available_in_workers), and [supported Web APIs](/en-US/docs/Web/API/Web_Workers_API/Functions_and_classes_available_to_workers#web_apis_available_in_workers). @@ -44,7 +44,7 @@ While {{domxref("Window")}} is not directly available to workers, many of the sa - {{DOMxRef("WorkerLocation")}} - : Defines the absolute location of the script executed by the {{domxref("Worker")}}. - {{DOMxRef("SharedWorker")}} - - : Represents a specific kind of worker that can be accessed from several {{glossary("browsing context", "browsing contexts")}} (i.e. windows, tabs, or iframes) or even other workers. + - : Represents a specific kind of worker that can be accessed from several {{glossary("browsing context", "browsing contexts")}} (i.e., windows, tabs, or iframes) or even other workers. - {{DOMxRef("WorkerGlobalScope")}} - : Represents the generic scope of any worker (doing the same job as {{DOMxRef("Window")}} does for normal web content). Different types of worker have scope objects that inherit from this interface and add more specific features. - {{DOMxRef("DedicatedWorkerGlobalScope")}} diff --git a/files/en-us/web/api/web_workers_api/structured_clone_algorithm/index.md b/files/en-us/web/api/web_workers_api/structured_clone_algorithm/index.md index 22da38820ee993b..7f8f1d41584d58a 100644 --- a/files/en-us/web/api/web_workers_api/structured_clone_algorithm/index.md +++ b/files/en-us/web/api/web_workers_api/structured_clone_algorithm/index.md @@ -35,8 +35,8 @@ It clones by recursing through the input object while maintaining a map of previ - {{jsxref("Error")}} types (but see [Error types](#error_types) below). - {{jsxref("Map")}} - {{jsxref("Number")}} -- {{jsxref("Object")}} objects: but only plain objects (e.g. from object literals). -- [Primitive types](/en-US/docs/Web/JavaScript/Data_structures#primitive_values), except `symbol`. +- {{jsxref("Object")}} objects: but only plain objects (e.g., from object literals). +- [Primitive types](/en-US/docs/Web/JavaScript/Guide/Data_structures#primitive_values), except `symbol`. - {{jsxref("RegExp")}}: but note that `lastIndex` is not preserved. - {{jsxref("Set")}} - {{jsxref("String")}} diff --git a/files/en-us/web/api/web_workers_api/transferable_objects/index.md b/files/en-us/web/api/web_workers_api/transferable_objects/index.md index 197ffa9b89cf911..46e6051c4dd9746 100644 --- a/files/en-us/web/api/web_workers_api/transferable_objects/index.md +++ b/files/en-us/web/api/web_workers_api/transferable_objects/index.md @@ -91,6 +91,7 @@ Some of the items that various specifications indicate can be _transferred_ are - {{domxref("RTCDataChannel")}} - {{domxref("MediaSourceHandle")}} - {{domxref("MIDIAccess")}} +- {{domxref("MediaStreamTrack")}} > [!NOTE] > Transferable objects are marked up in [Web IDL files](https://github.com/w3c/webref/tree/main/ed/idl) with the attribute `[Transferable]`. diff --git a/files/en-us/web/api/web_workers_api/using_web_workers/index.md b/files/en-us/web/api/web_workers_api/using_web_workers/index.md index 65f1f3521ed32f9..00b5bf595fcf040 100644 --- a/files/en-us/web/api/web_workers_api/using_web_workers/index.md +++ b/files/en-us/web/api/web_workers_api/using_web_workers/index.md @@ -13,7 +13,7 @@ This article provides a detailed introduction to using web workers. ## Web Workers API -A worker is an object created using a constructor (e.g. {{domxref("Worker.Worker", "Worker()")}}) that runs a named JavaScript file — this file contains the code that will run in the worker thread; workers run in another global context that is different from the current {{domxref("window")}}. Thus, using the {{domxref("window")}} shortcut to get the current global scope (instead of {{domxref("window.self","self")}}) within a {{domxref("Worker")}} will return an error. +A worker is an object created using a constructor (e.g., {{domxref("Worker.Worker", "Worker()")}}) that runs a named JavaScript file — this file contains the code that will run in the worker thread; workers run in another global context that is different from the current {{domxref("window")}}. Thus, using the {{domxref("window")}} shortcut to get the current global scope (instead of {{domxref("window.self","self")}}) within a {{domxref("Worker")}} will return an error. The worker context is represented by a {{domxref("DedicatedWorkerGlobalScope")}} object in the case of dedicated workers (standard workers that are utilized by a single script; shared workers use {{domxref("SharedWorkerGlobalScope")}}). A dedicated worker is only accessible from the script that first spawned it, whereas shared workers can be accessed from multiple scripts. @@ -68,7 +68,7 @@ The magic of workers happens via the {{domxref("Worker.postMessage", "postMessag ```js [first, second].forEach((input) => { input.onchange = () => { - myWorker.port.postMessage([first.value, second.value]); + myWorker.postMessage([first.value, second.value]); console.log("Message posted to worker"); }; }); @@ -204,7 +204,7 @@ onconnect = (e) => { }; ``` -First, we use an `onconnect` handler to fire code when a connection to the port happens (i.e. when the `onmessage` event handler in the parent thread is set up, or when the `start()` method is explicitly called in the parent thread). +First, we use an `onconnect` handler to fire code when a connection to the port happens (i.e., when the `onmessage` event handler in the parent thread is set up, or when the `start()` method is explicitly called in the parent thread). We use the `ports` attribute of this event object to grab the port and store it in a variable. @@ -225,7 +225,7 @@ When a message comes back through the port from the worker, we insert the calcul The {{domxref("Worker")}} interface spawns real OS-level threads, and mindful programmers may be concerned that concurrency can cause "interesting" effects in your code if you aren't careful. -However, since web workers have carefully controlled communication points with other threads, it's actually very hard to cause concurrency problems. There's no access to non-threadsafe components or the DOM. And you have to pass specific data in and out of a thread through serialized objects. So you have to work really hard to cause problems in your code. +However, since web workers have carefully controlled communication points with other threads, it's actually very hard to cause concurrency problems. There's no access to non-thread-safe components or the DOM. And you have to pass specific data in and out of a thread through serialized objects. So you have to work really hard to cause problems in your code. ## Content security policy @@ -237,7 +237,7 @@ Content-Security-Policy: script-src 'self' Among other things, this will prevent any scripts it includes from using [`eval()`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/eval). However, if the script constructs a worker, code running in the worker's context _will_ be allowed to use `eval()`. -To specify a content security policy for the worker, set a [Content-Security-Policy](/en-US/docs/Web/HTTP/Headers/Content-Security-Policy) response header for the request which delivered the worker script itself. +To specify a content security policy for the worker, set a [Content-Security-Policy](/en-US/docs/Web/HTTP/Reference/Headers/Content-Security-Policy) response header for the request which delivered the worker script itself. The exception to this is if the worker script's origin is a globally unique identifier (for example, if its URL has a scheme of data or blob). In this case, the worker does inherit the CSP of the document or worker that created it. @@ -323,7 +323,6 @@ First, we create a `QueryableWorker` class that takes the URL of the worker, a d ```js function QueryableWorker(url, defaultListener, onError) { - const instance = this; const worker = new Worker(url); const listeners = {}; @@ -416,7 +415,8 @@ function reply(queryMethodListener, ...queryMethodArguments) { }); } -/* This method is called when main page calls QueryWorker's postMessage method directly*/ +// This method is called when main page calls QueryWorker's postMessage +// method directly function defaultReply(message) { // do something } @@ -452,7 +452,7 @@ Here are the full implementation: <meta charset="UTF-8" /> <meta name="viewport" content="width=device-width" /> <title>MDN Example - Queryable worker</title> - <script type="text/javascript"> + <script> // QueryableWorker instances methods: // * sendQuery(queryable function name, argument to pass 1, argument to pass 2, etc. etc.): calls a Worker's queryable function // * postMessage(string or JSON Data): see Worker.prototype.postMessage() @@ -660,7 +660,7 @@ There is not an "official" way to embed the code of a worker within a web page, // In the past blob builder existed, but now we use Blob const blob = new Blob( Array.prototype.map.call( - document.querySelectorAll("script[type='text\/js-worker']"), + document.querySelectorAll("script[type='text/js-worker']"), (script) => script.textContent, ), { type: "text/javascript" }, @@ -817,6 +817,14 @@ To learn how to debug web workers, see the documentation for each browser's Java - [Chrome Sources panel](https://developer.chrome.com/docs/devtools/sources) - [Firefox JavaScript Debugger](https://firefox-source-docs.mozilla.org/devtools-user/debugger/) +To open devtools for web workers, you can use the following URLs: + +- Edge: `edge://inspect/` +- Chrome: `chrome://inspect/` +- Firefox: `about:debugging#/runtime/this-firefox` + +These pages show an overview over all service workers. You need to find the relevant one by the URL and then click _inspect_ to access devtools such as the console and debugger for that worker. + ## Functions and interfaces available in workers You can use most standard JavaScript features inside a web worker, including: diff --git a/files/en-us/web/api/webgl2renderingcontext/bufferdata/index.md b/files/en-us/web/api/webgl2renderingcontext/bufferdata/index.md index f56dd6a1f79ab82..61f90053d55aef1 100644 --- a/files/en-us/web/api/webgl2renderingcontext/bufferdata/index.md +++ b/files/en-us/web/api/webgl2renderingcontext/bufferdata/index.md @@ -48,7 +48,7 @@ bufferData(target, srcData, usage, srcOffset, length) store. One of `size` and `srcData` must be provided. - `srcData` {{optional_inline}} - - : An {{jsxref("ArrayBuffer")}}, {{jsxref("SharedArrayBuffer")}}, a {{jsxref("TypedArray")}} or a {{jsxref("DataView")}} + - : A {{jsxref("TypedArray")}} or a {{jsxref("DataView")}} that views an {{jsxref("ArrayBuffer")}} or {{jsxref("SharedArrayBuffer")}} that will be copied into the data store. If `null`, a data store is still created, but the content is uninitialized and undefined. One of `size` and `srcData` must be provided. diff --git a/files/en-us/web/api/webgl2renderingcontext/buffersubdata/index.md b/files/en-us/web/api/webgl2renderingcontext/buffersubdata/index.md index ec1993c02f15e6b..e3f65b797009a52 100644 --- a/files/en-us/web/api/webgl2renderingcontext/buffersubdata/index.md +++ b/files/en-us/web/api/webgl2renderingcontext/buffersubdata/index.md @@ -48,7 +48,7 @@ bufferSubData(target, dstByteOffset, srcData, srcOffset, length) - : A {{domxref("WebGL_API/Types", "GLintptr")}} specifying an offset in bytes where the data replacement will start. - `srcData` {{optional_inline}} - - : An {{jsxref("ArrayBuffer")}}, {{jsxref("SharedArrayBuffer")}}, a {{jsxref("DataView")}}, or a {{jsxref("TypedArray")}} + - : A {{jsxref("TypedArray")}} or a {{jsxref("DataView")}} that views an {{jsxref("ArrayBuffer")}} or {{jsxref("SharedArrayBuffer")}} that will be copied into the data store. - `srcOffset` {{optional_inline}} - : A {{domxref("WebGL_API/Types", "GLuint")}} specifying the element index offset where to start reading diff --git a/files/en-us/web/api/webgl2renderingcontext/resumetransformfeedback/index.md b/files/en-us/web/api/webgl2renderingcontext/resumetransformfeedback/index.md index 9094a7d3f7f77ee..83691e3f1942cb3 100644 --- a/files/en-us/web/api/webgl2renderingcontext/resumetransformfeedback/index.md +++ b/files/en-us/web/api/webgl2renderingcontext/resumetransformfeedback/index.md @@ -33,7 +33,7 @@ const transformFeedback = gl.createTransformFeedback(); gl.bindTransformFeedback(gl.TRANSFORM_FEEDBACK, transformFeedback); gl.beginTransformFeedback(gl.TRIANGLES); gl.pauseTransformFeedback(); -//… +// … gl.resumeTransformFeedback(); gl.drawArrays(gl.TRIANGLES, 0, 3); gl.endTransformFeedback(); diff --git a/files/en-us/web/api/webgl2renderingcontext/uniform/index.md b/files/en-us/web/api/webgl2renderingcontext/uniform/index.md index dfb11cef2e0e378..68f6553593a894a 100644 --- a/files/en-us/web/api/webgl2renderingcontext/uniform/index.md +++ b/files/en-us/web/api/webgl2renderingcontext/uniform/index.md @@ -12,9 +12,15 @@ The **`WebGL2RenderingContext.uniform[1234][uif][v]()`** methods of the [WebGL API](/en-US/docs/Web/API/WebGL_API) specify values of uniform variables. -> **Note:** `ui` stands for _unsigned integer_, `i` for _integer_, `f` for _float_, and `v` for _vector_. -> Not all combinations are valid: `u` cannot be combined with `f`. -> See the syntax table below. Equivalent Regex: `uniform[1234](u?i|f)v?` +The names of these methods are formed by: + +- The number of components in the uniform variable (1, 2, 3, or 4). +- The type of the uniform variable (`i` for integer, `f` for float, `ui` for unsigned integer). +- The presence of a vector (`v`) suffix for vector types. + +They can be matched by the regex `uniform[1234](u?i|f)v?`. + +Most of these signatures are inherited from the [WebGL 1 API](/en-US/docs/Web/API/WebGLRenderingContext/uniform). WebGL 2 adds the unsigned integer versions, and the additional `srcOffset` and `srcLength` parameters to the vector methods. ## Syntax @@ -79,14 +85,15 @@ uniform4uiv(location, data, srcOffset, srcLength) - : A {{domxref("WebGLUniformLocation")}} object containing the location of the uniform attribute to modify. - `data`, `v0`, `v1`, `v2`, `v3` - - : A new value to be used for the uniform variable. Possible types: - - - A {{jsxref("Number")}} for unsigned integer values (methods with - `ui`), for integer values (methods with `i`), or for floats - (methods with `f`). - - A {{jsxref("Uint32Array")}} for unsigned integer vector methods (methods with - `uiv`). + - A {{jsxref("Number")}} for unsigned integer values (methods with `ui`), for integer values (methods with `i`), or for floats (methods with `f`). + - A {{jsxref("Uint32Array")}} (or an {{jsxref("Array")}} of unsigned integer numbers) for unsigned integer vector methods (methods with `uiv`). + - A {{jsxref("Int32Array")}} (or an {{jsxref("Array")}} of integer numbers) for integer vector methods (methods with `iv`). + - A {{jsxref("Float32Array")}} (or an {{jsxref("Array")}} of numbers) for floating point vector methods (methods with `fv`). +- `srcOffset` {{optional_inline}} + - : A non-negative integer specifying the index of the first element in the `data` array to be used. Defaults to `0`. +- `srcLength` {{optional_inline}} + - : A non-negative integer specifying the number of elements in the `data` array to be used. Defaults to `0`, which gets treated as `data.length - srcOffset`. `srcOffset + srcLength` must be less than or equal to `data.length`. ### Return value @@ -102,4 +109,4 @@ None ({{jsxref("undefined")}}). ## See also -- {{domxref("WebGLRenderingContext.uniform()")}} +- [`WebGLRenderingContext.uniform[1234][fi][v]()`](/en-US/docs/Web/API/WebGLRenderingContext/uniform) diff --git a/files/en-us/web/api/webgl2renderingcontext/vertexattribipointer/index.md b/files/en-us/web/api/webgl2renderingcontext/vertexattribipointer/index.md index 98ec394c927c0c3..457e19133148173 100644 --- a/files/en-us/web/api/webgl2renderingcontext/vertexattribipointer/index.md +++ b/files/en-us/web/api/webgl2renderingcontext/vertexattribipointer/index.md @@ -55,18 +55,18 @@ interpreted as integers in the shader. ### Linear Blend Skinning ```js -//Describe the layout of the buffer: -//1. position +// Describe the layout of the buffer: +// 1. position gl.vertexAttribPointer(0, 3, gl.FLOAT, false, 20, 0); gl.enableVertexAttribArray(0); -//2. bone weights, normalized to [0, 1] +// 2. bone weights, normalized to [0, 1] gl.vertexAttribPointer(1, 4, gl.UNSIGNED_BYTE, true, 20, 12); gl.enableVertexAttribArray(1); -//3. bone indices, interpreted as integer +// 3. bone indices, interpreted as integer gl.vertexAttribIPointer(2, 4, gl.UNSIGNED_BYTE, 20, 16); gl.enableVertexAttribArray(2); -//Connect to attributes from the vertex shader +// Connect to attributes from the vertex shader gl.bindAttribLocation(shaderProgram, 0, "position"); gl.bindAttribLocation(shaderProgram, 1, "boneWeights"); gl.bindAttribLocation(shaderProgram, 2, "boneIndices"); diff --git a/files/en-us/web/api/webgl_api/by_example/hello_glsl/index.md b/files/en-us/web/api/webgl_api/by_example/hello_glsl/index.md index eef6e7980793248..6039d770f45b04f 100644 --- a/files/en-us/web/api/webgl_api/by_example/hello_glsl/index.md +++ b/files/en-us/web/api/webgl_api/by_example/hello_glsl/index.md @@ -64,11 +64,6 @@ button { </script> ``` -```js hidden -;(() => { - "use strict"; -``` - ```js window.addEventListener("load", setupWebGL, false); let gl; @@ -150,10 +145,6 @@ function getRenderingContext() { } ``` -```js hidden -})(); -``` - The source code of this example is also available on [GitHub](https://github.com/idofilin/webgl-by-example/tree/master/hello-glsl). {{PreviousNext("Web/API/WebGL_API/By_example/Raining_rectangles","Web/API/WebGL_API/By_example/Hello_vertex_attributes")}} diff --git a/files/en-us/web/api/webgl_api/by_example/hello_vertex_attributes/index.md b/files/en-us/web/api/webgl_api/by_example/hello_vertex_attributes/index.md index acfa44056cf786d..d8d2e4372d04e25 100644 --- a/files/en-us/web/api/webgl_api/by_example/hello_vertex_attributes/index.md +++ b/files/en-us/web/api/webgl_api/by_example/hello_vertex_attributes/index.md @@ -69,11 +69,6 @@ button { </script> ``` -```js hidden -;(() => { - "use strict"; -``` - ```js window.addEventListener("load", setupWebGL, false); let gl; @@ -170,10 +165,6 @@ function getRenderingContext() { } ``` -```js hidden -})(); -``` - The source code of this example is also available on [GitHub](https://github.com/idofilin/webgl-by-example/tree/master/hello-vertex-attributes). {{PreviousNext("Web/API/WebGL_API/By_example/Hello_GLSL","Web/API/WebGL_API/By_example/Textures_from_code")}} diff --git a/files/en-us/web/api/webgl_api/by_example/raining_rectangles/index.md b/files/en-us/web/api/webgl_api/by_example/raining_rectangles/index.md index d21c393b8bc9c54..5f1fa9e9043a522 100644 --- a/files/en-us/web/api/webgl_api/by_example/raining_rectangles/index.md +++ b/files/en-us/web/api/webgl_api/by_example/raining_rectangles/index.md @@ -47,11 +47,6 @@ button { } ``` -```js hidden -;(() => { - "use strict"; -``` - ```js window.addEventListener("load", setupAnimation, false); let gl; @@ -123,27 +118,27 @@ function playerClick(evt) { } } -function Rectangle() { - // Keeping a reference to the new Rectangle object, rather - // than using the confusing this keyword. - const rect = this; - // We get three random numbers and use them for new rectangle - // size and position. For each we use a different number, - // because we want horizontal size, vertical size and - // position to be determined independently. - const randNums = getRandomVector(); - rect.size = [5 + 120 * randNums[0], 5 + 120 * randNums[1]]; - rect.position = [ - randNums[2] * (gl.drawingBufferWidth - rect.size[0]), - gl.drawingBufferHeight, - ]; - rect.velocity = 1.0 + 6.0 * Math.random(); - rect.color = getRandomVector(); - gl.clearColor(rect.color[0], rect.color[1], rect.color[2], 1.0); - function getRandomVector() { - return [Math.random(), Math.random(), Math.random()]; +class Rectangle { + constructor() { + // We get three random numbers and use them for new rectangle + // size and position. For each we use a different number, + // because we want horizontal size, vertical size and + // position to be determined independently. + const randVec = getRandomVector(); + this.size = [5 + 120 * randVec[0], 5 + 120 * randVec[1]]; + this.position = [ + randVec[2] * (gl.drawingBufferWidth - this.size[0]), + gl.drawingBufferHeight, + ]; + this.velocity = 1.0 + 6.0 * Math.random(); + this.color = getRandomVector(); + gl.clearColor(this.color[0], this.color[1], this.color[2], 1.0); } } + +function getRandomVector() { + return [Math.random(), Math.random(), Math.random()]; +} ``` ```js hidden @@ -166,10 +161,6 @@ function getRenderingContext() { } ``` -```js hidden -})(); -``` - The source code of this example is also available on [GitHub](https://github.com/idofilin/webgl-by-example/tree/master/raining-rectangles). {{PreviousNext("Web/API/WebGL_API/By_example/Scissor_animation","Web/API/WebGL_API/By_example/Hello_GLSL")}} diff --git a/files/en-us/web/api/webgl_api/by_example/scissor_animation/index.md b/files/en-us/web/api/webgl_api/by_example/scissor_animation/index.md index fa4f77782668338..7b072a28bfed7fc 100644 --- a/files/en-us/web/api/webgl_api/by_example/scissor_animation/index.md +++ b/files/en-us/web/api/webgl_api/by_example/scissor_animation/index.md @@ -51,11 +51,6 @@ button { } ``` -```js hidden -;(() => { - "use strict"; -``` - ```js window.addEventListener("load", setupAnimation, false); // Variables to hold the WebGL context, and the color and @@ -148,10 +143,6 @@ function getRenderingContext() { } ``` -```js hidden -})(); -``` - The source code of this example is also available on [GitHub](https://github.com/idofilin/webgl-by-example/tree/master/scissor-animation). {{PreviousNext("Web/API/WebGL_API/By_example/Boilerplate_1","Web/API/WebGL_API/By_example/Raining_rectangles")}} diff --git a/files/en-us/web/api/webgl_api/by_example/textures_from_code/index.md b/files/en-us/web/api/webgl_api/by_example/textures_from_code/index.md index 8a5ebb47a32f47c..69189a9a2b23b16 100644 --- a/files/en-us/web/api/webgl_api/by_example/textures_from_code/index.md +++ b/files/en-us/web/api/webgl_api/by_example/textures_from_code/index.md @@ -72,11 +72,6 @@ button { </script> ``` -```js hidden -;(() => { - "use strict"; -``` - ```js window.addEventListener("load", setupWebGL, false); @@ -158,10 +153,6 @@ function getRenderingContext() { } ``` -```js hidden -})(); -``` - The source code of this example is also available on [GitHub](https://github.com/idofilin/webgl-by-example/tree/master/textures-from-code). {{PreviousNext("Web/API/WebGL_API/By_example/Hello_vertex_attributes","Web/API/WebGL_API/By_example/Video_textures")}} diff --git a/files/en-us/web/api/webgl_api/compressed_texture_formats/index.md b/files/en-us/web/api/webgl_api/compressed_texture_formats/index.md index 4c64b3d33b8e384..5fcbbe2a9aa9a87 100644 --- a/files/en-us/web/api/webgl_api/compressed_texture_formats/index.md +++ b/files/en-us/web/api/webgl_api/compressed_texture_formats/index.md @@ -14,7 +14,7 @@ Unless otherwise specified, this article applies to both WebGL 1 and 2 contexts. If supported, textures can be stored in a compressed format in video memory. This allows for additional detail while limiting the added video memory necessary. Textures are uncompressed on the fly when being accessed by a shader. Note that this advantage doesn't translate to network bandwidth: while the formats are better than uncompressed data, they are in general far worse than standard image formats such as PNG and JPG. -As compressed textures require hardware support, therefore no specific formats are required by WebGL; instead, a context can make different formats available, depending on hardware support. [This site](https://toji.github.io/texture-tester/) shows which formats are supported in the used browser. +As compressed textures require hardware support, therefore no specific formats are required by WebGL; instead, a context can make different formats available, depending on hardware support. The [WebGL Texture Tester](https://toji.github.io/texture-tester/) site shows which formats are supported in the used browser. Usage of compressed formats first requires activating the respective extension with {{domxref("WebGLRenderingContext.getExtension()")}}. If supported, it will return an extension object with constants for the added formats and the formats will also be returned by calls to `gl.getParameter(gl.COMPRESSED_TEXTURE_FORMATS)`. (E.g. `ext.COMPRESSED_RGBA_S3TC_DXT1_EXT` for the {{domxref("WEBGL_compressed_texture_s3tc")}} extension.) These can then be used with {{domxref("WebGLRenderingContext.compressedTexImage2D()", "compressedTexImage[23]D")}} or {{domxref("WebGLRenderingContext.compressedTexSubImage2D()", "compressedTexSubImage[23]D")}} instead of `texImage2D` calls. diff --git a/files/en-us/web/api/webgl_api/data/index.md b/files/en-us/web/api/webgl_api/data/index.md index 01e9dcc7ba03aae..8f31455bee805e0 100644 --- a/files/en-us/web/api/webgl_api/data/index.md +++ b/files/en-us/web/api/webgl_api/data/index.md @@ -46,8 +46,7 @@ gl.vertexAttribPointer(vColor, 4, gl.FLOAT, false, 0, 0); gl.enableVertexAttribArray(vColor); ``` -```cpp -//glsl +```glsl attribute vec4 vColor; void main() diff --git a/files/en-us/web/api/webgl_api/matrix_math_for_the_web/index.md b/files/en-us/web/api/webgl_api/matrix_math_for_the_web/index.md index 5eccccda0b7cec0..4de64116632da26 100644 --- a/files/en-us/web/api/webgl_api/matrix_math_for_the_web/index.md +++ b/files/en-us/web/api/webgl_api/matrix_math_for_the_web/index.md @@ -18,8 +18,13 @@ Let's begin by considering the **identity matrix**. This is a special transforma The identity matrix looks like this in JavaScript: -```js -let identityMatrix = [1, 0, 0, 0, 0, 1, 0, 0, 0, 0, 1, 0, 0, 0, 0, 1]; +```js-nolint +const identityMatrix = [ + 1, 0, 0, 0, + 0, 1, 0, 0, + 0, 0, 1, 0, + 0, 0, 0, 1, +]; ``` What does multiplying by the identity matrix look like? The easiest example is to multiply a single point by the identity matrix. Since a 3D point only needs three values (`x`, `y`, and `z`), and the transformation matrix is a 4×4 value matrix, we need to add a fourth dimension to the point. By convention, this dimension is called the **perspective**, and is represented by the letter `w`. For a typical position, setting `w` to 1 will make the math work out. @@ -30,9 +35,9 @@ After adding the `w` component to the point, notice how neatly the matrix and th [1, 0, 0, 0, 0, 1, 0, 0, 0, 0, 1, 0, - 0, 0, 0, 1] + 0, 0, 0, 1]; -[4, 3, 2, 1] // Point at [x, y, z, w] +[4, 3, 2, 1]; // Point at [x, y, z, w] ``` The `w` component has some additional uses that are out of scope for this article. Check out the [WebGL model view projection](/en-US/docs/Web/API/WebGL_API/WebGL_model_view_projection) article for a look into how it comes in handy. @@ -45,40 +50,40 @@ In our example code we have defined a function to multiply a matrix and a point // point • matrix function multiplyMatrixAndPoint(matrix, point) { // Give a simple variable name to each part of the matrix, a column and row number - let c0r0 = matrix[0], + const c0r0 = matrix[0], c1r0 = matrix[1], c2r0 = matrix[2], c3r0 = matrix[3]; - let c0r1 = matrix[4], + const c0r1 = matrix[4], c1r1 = matrix[5], c2r1 = matrix[6], c3r1 = matrix[7]; - let c0r2 = matrix[8], + const c0r2 = matrix[8], c1r2 = matrix[9], c2r2 = matrix[10], c3r2 = matrix[11]; - let c0r3 = matrix[12], + const c0r3 = matrix[12], c1r3 = matrix[13], c2r3 = matrix[14], c3r3 = matrix[15]; // Now set some simple names for the point - let x = point[0]; - let y = point[1]; - let z = point[2]; - let w = point[3]; + const x = point[0]; + const y = point[1]; + const z = point[2]; + const w = point[3]; // Multiply the point against each part of the 1st column, then add together - let resultX = x * c0r0 + y * c0r1 + z * c0r2 + w * c0r3; + const resultX = x * c0r0 + y * c0r1 + z * c0r2 + w * c0r3; // Multiply the point against each part of the 2nd column, then add together - let resultY = x * c1r0 + y * c1r1 + z * c1r2 + w * c1r3; + const resultY = x * c1r0 + y * c1r1 + z * c1r2 + w * c1r3; // Multiply the point against each part of the 3rd column, then add together - let resultZ = x * c2r0 + y * c2r1 + z * c2r2 + w * c2r3; + const resultZ = x * c2r0 + y * c2r1 + z * c2r2 + w * c2r3; // Multiply the point against each part of the 4th column, then add together - let resultW = x * c3r0 + y * c3r1 + z * c3r2 + w * c3r3; + const resultW = x * c3r0 + y * c3r1 + z * c3r2 + w * c3r3; return [resultX, resultY, resultZ, resultW]; } @@ -109,7 +114,7 @@ Now using the function above we can multiply a point by the matrix. Using the id ```js // sets identityResult to [4,3,2,1] -let identityResult = multiplyMatrixAndPoint(identityMatrix, [4, 3, 2, 1]); +const identityResult = multiplyMatrixAndPoint(identityMatrix, [4, 3, 2, 1]); ``` Returning the same point is not very useful, but there are other types of matrices that can perform helpful operations on points. The next sections will demonstrate some of these matrices. @@ -119,38 +124,27 @@ Returning the same point is not very useful, but there are other types of matric In addition to multiplying a matrix and a point together, you can also multiply two matrices together. The function from above can be re-used to help out in this process: ```js -//matrixB • matrixA +// matrixB • matrixA function multiplyMatrices(matrixA, matrixB) { // Slice the second matrix up into rows - let row0 = [matrixB[0], matrixB[1], matrixB[2], matrixB[3]]; - let row1 = [matrixB[4], matrixB[5], matrixB[6], matrixB[7]]; - let row2 = [matrixB[8], matrixB[9], matrixB[10], matrixB[11]]; - let row3 = [matrixB[12], matrixB[13], matrixB[14], matrixB[15]]; + const row0 = [matrixB[0], matrixB[1], matrixB[2], matrixB[3]]; + const row1 = [matrixB[4], matrixB[5], matrixB[6], matrixB[7]]; + const row2 = [matrixB[8], matrixB[9], matrixB[10], matrixB[11]]; + const row3 = [matrixB[12], matrixB[13], matrixB[14], matrixB[15]]; // Multiply each row by matrixA - let result0 = multiplyMatrixAndPoint(matrixA, row0); - let result1 = multiplyMatrixAndPoint(matrixA, row1); - let result2 = multiplyMatrixAndPoint(matrixA, row2); - let result3 = multiplyMatrixAndPoint(matrixA, row3); + const result0 = multiplyMatrixAndPoint(matrixA, row0); + const result1 = multiplyMatrixAndPoint(matrixA, row1); + const result2 = multiplyMatrixAndPoint(matrixA, row2); + const result3 = multiplyMatrixAndPoint(matrixA, row3); // Turn the result rows back into a single matrix + // prettier-ignore return [ - result0[0], - result0[1], - result0[2], - result0[3], - result1[0], - result1[1], - result1[2], - result1[3], - result2[0], - result2[1], - result2[2], - result2[3], - result3[0], - result3[1], - result3[2], - result3[3], + result0[0], result0[1], result0[2], result0[3], + result1[0], result1[1], result1[2], result1[3], + result2[0], result2[1], result2[2], result2[3], + result3[0], result3[1], result3[2], result3[3], ]; } ``` @@ -158,12 +152,12 @@ function multiplyMatrices(matrixA, matrixB) { Let's look at this function in action: ```js -let someMatrix = [4, 0, 0, 0, 0, 3, 0, 0, 0, 0, 5, 0, 4, 8, 4, 1]; +const someMatrix = [4, 0, 0, 0, 0, 3, 0, 0, 0, 0, 5, 0, 4, 8, 4, 1]; -let identityMatrix = [1, 0, 0, 0, 0, 1, 0, 0, 0, 0, 1, 0, 0, 0, 0, 1]; +const identityMatrix = [1, 0, 0, 0, 0, 1, 0, 0, 0, 0, 1, 0, 0, 0, 0, 1]; // Returns a new array equivalent to someMatrix -let someMatrixResult = multiplyMatrices(identityMatrix, someMatrix); +const someMatrixResult = multiplyMatrices(identityMatrix, someMatrix); ``` > [!WARNING] @@ -176,11 +170,11 @@ A **translation matrix** is based upon the identity matrix, and is used in 3D gr You can't actually drink the coffee using only a translation matrix, because to drink it, you have to be able to tilt or rotate the cup to pour the coffee into your mouth. We'll look at the type of matrix (cleverly called a **[rotation matrix](#rotation_matrix)**) you use to do this later. ```js -let x = 50; -let y = 100; -let z = 0; +const x = 50; +const y = 100; +const z = 0; -let translationMatrix = [1, 0, 0, 0, 0, 1, 0, 0, 0, 0, 1, 0, x, y, z, 1]; +const translationMatrix = [1, 0, 0, 0, 0, 1, 0, 0, 0, 0, 1, 0, x, y, z, 1]; ``` Place the distances along the three axes in the corresponding positions in the translation matrix, then multiply it by the point or matrix you need to move through 3D space. @@ -205,10 +199,10 @@ function matrixArrayToCssMatrix(array) { } // Grab the DOM element -let moveMe = document.getElementById("move-me"); +const moveMe = document.getElementById("move-me"); // Returns a result like: "matrix3d(1, 0, 0, 0, 0, 1, 0, 0, 0, 0, 1, 0, 50, 100, 0, 1);" -let matrix3dRule = matrixArrayToCssMatrix(translationMatrix); +const matrix3dRule = matrixArrayToCssMatrix(translationMatrix); // Set the transform moveMe.style.transform = matrix3dRule; @@ -225,11 +219,11 @@ A **scale matrix** makes something larger or smaller in one or more of the three The amount of change to apply to each of the width, height, and depth is placed diagonally starting at the top-left corner and making their way down toward the bottom-right. ```js -let w = 1.5; // width (x) -let h = 0.7; // height (y) -let d = 1; // depth (z) +const w = 1.5; // width (x) +const h = 0.7; // height (y) +const d = 1; // depth (z) -let scaleMatrix = [w, 0, 0, 0, 0, h, 0, 0, 0, 0, d, 0, 0, 0, 0, 1]; +const scaleMatrix = [w, 0, 0, 0, 0, h, 0, 0, 0, 0, d, 0, 0, 0, 0, 1]; ``` [View on JSFiddle](https://jsfiddle.net/tatumcreative/fndd6e1b/) @@ -244,15 +238,15 @@ First, here's code that rotates a point around the origin without using matrices ```js // Manually rotating a point about the origin without matrices -let point = [10, 2]; +const point = [10, 2]; // Calculate the distance from the origin -let distance = Math.sqrt(point[0] * point[0] + point[1] * point[1]); +const distance = Math.sqrt(point[0] * point[0] + point[1] * point[1]); // The equivalent of 60 degrees, in radians -let rotationInRadians = Math.PI / 3; +const rotationInRadians = Math.PI / 3; -let transformedPoint = [ +const transformedPoint = [ Math.cos(rotationInRadians) * distance, Math.sin(rotationInRadians) * distance, ]; @@ -261,32 +255,21 @@ let transformedPoint = [ It is possible to encode these type of steps into a matrix, and do it for each of the `x`, `y`, and `z` dimensions. Below is the representation of a counterclockwise rotation about the Z axis in a left-handed coordinate system: ```js -let sin = Math.sin; -let cos = Math.cos; +const sin = Math.sin; +const cos = Math.cos; // NOTE: There is no perspective in these transformations, so a rotation // at this point will only appear to only shrink the div -let a = Math.PI * 0.3; //Rotation amount in radians +const a = Math.PI * 0.3; // Rotation amount in radians // Rotate around Z axis -let rotateZMatrix = [ - cos(a), - -sin(a), - 0, - 0, - sin(a), - cos(a), - 0, - 0, - 0, - 0, - 1, - 0, - 0, - 0, - 0, - 1, +// prettier-ignore +const rotateZMatrix = [ + cos(a), -sin(a), 0, 0, + sin(a), cos(a), 0, 0, + 0, 0, 1, 0, + 0, 0, 0, 1, ]; ``` @@ -298,15 +281,33 @@ Here are a set of functions that return rotation matrices for rotating around ea ```js function rotateAroundXAxis(a) { - return [1, 0, 0, 0, 0, cos(a), -sin(a), 0, 0, sin(a), cos(a), 0, 0, 0, 0, 1]; + // prettier-ignore + return [ + 1, 0, 0, 0, + 0, cos(a), -sin(a), 0, + 0, sin(a), cos(a), 0, + 0, 0, 0, 1, + ]; } function rotateAroundYAxis(a) { - return [cos(a), 0, sin(a), 0, 0, 1, 0, 0, -sin(a), 0, cos(a), 0, 0, 0, 0, 1]; + // prettier-ignore + return [ + cos(a), 0, sin(a), 0, + 0, 1, 0, 0, + -sin(a), 0, cos(a), 0, + 0, 0, 0, 1, + ]; } function rotateAroundZAxis(a) { - return [cos(a), -sin(a), 0, 0, sin(a), cos(a), 0, 0, 0, 0, 1, 0, 0, 0, 0, 1]; + // prettier-ignore + return [ + cos(a), -sin(a), 0, 0, + sin(a), cos(a), 0, 0, + 0, 0, 1, 0, + 0, 0, 0, 1, + ]; } ``` @@ -329,7 +330,7 @@ transformation = rotate * translate * scale The function that we will be using to compose our matrices is `multiplyArrayOfMatrices()`, which is part of the set of [utility functions](https://github.com/gregtatum/mdn-webgl) introduced near the top of this article. It takes an array of matrices and multiplies them together, returning the result. In WebGL shader code, this is built into the language and the `*` operator can be used. Additionally this example uses `scale()` and `translate()` functions, which return matrices as defined above. ```js -let transformMatrix = MDN.multiplyArrayOfMatrices([ +const transformMatrix = MDN.multiplyArrayOfMatrices([ rotateAroundZAxis(Math.PI * 0.5), // Step 3: rotate around 90 degrees translate(0, 200, 0), // Step 2: move down 200 pixels scale(0.8, 0.8, 0.8), // Step 1: scale down @@ -343,7 +344,7 @@ let transformMatrix = MDN.multiplyArrayOfMatrices([ Finally, a fun step to show how matrices work is to reverse the steps to bring the matrix back to the original identity matrix. ```js -let transformMatrix = MDN.multiplyArrayOfMatrices([ +const transformMatrix = MDN.multiplyArrayOfMatrices([ scale(1.25, 1.25, 1.25), // Step 6: scale back up translate(0, -200, 0), // Step 5: move back up rotateAroundZAxis(-Math.PI * 0.5), // Step 4: rotate back diff --git a/files/en-us/web/api/webgl_api/tutorial/animating_objects_with_webgl/index.md b/files/en-us/web/api/webgl_api/tutorial/animating_objects_with_webgl/index.md index 254eb5124abd6e1..225901f1a6e9637 100644 --- a/files/en-us/web/api/webgl_api/tutorial/animating_objects_with_webgl/index.md +++ b/files/en-us/web/api/webgl_api/tutorial/animating_objects_with_webgl/index.md @@ -20,15 +20,15 @@ let deltaTime = 0; Now we need to update the `drawScene()` function to apply the current rotation to the camera when drawing it. After translating the camera to the initial drawing position for the square, we apply the rotation. -> [!NOTE] -> In your "draw-scene.js" module, update the declaration of your `drawScene()` function so it can be passed the rotation to use: +In your "draw-scene.js" module, update the declaration of your `drawScene()` function so it can be passed the rotation to use: -```js-nolint +```js function drawScene(gl, programInfo, buffers, squareRotation) { + // … +} ``` -> [!NOTE] -> In your `drawScene()` function, right after the line `mat4.translate()` call, add this code: +In your `drawScene()` function, right after the line `mat4.translate()` call, add this code: ```js mat4.rotate( @@ -43,8 +43,7 @@ This rotates the modelViewMatrix by the current value of `squareRotation`, aroun To actually animate, we need to add code that changes the value of `squareRotation` over time. -> [!NOTE] -> Add this code at the end of your `main()` function, replacing the existing `drawScene()` call: +Add this code at the end of your `main()` function, replacing the existing `drawScene()` call: ```js let then = 0; diff --git a/files/en-us/web/api/webgl_api/tutorial/creating_3d_objects_using_webgl/index.md b/files/en-us/web/api/webgl_api/tutorial/creating_3d_objects_using_webgl/index.md index da43a67fba0d96a..0540a25a68b1c1c 100644 --- a/files/en-us/web/api/webgl_api/tutorial/creating_3d_objects_using_webgl/index.md +++ b/files/en-us/web/api/webgl_api/tutorial/creating_3d_objects_using_webgl/index.md @@ -14,8 +14,7 @@ Consider: each face requires four vertices to define it, but each vertex is shar First, let's build the cube's vertex position buffer by updating the code in `initBuffers()`. This is pretty much the same as it was for the square plane, but somewhat longer since there are 24 vertices (4 per side). -> [!NOTE] -> In the `initPositionBuffer()` function of your "init-buffers.js" module, replace the `positions` declaration with this code: +In the `initPositionBuffer()` function of your "init-buffers.js" module, replace the `positions` declaration with this code: ```js const positions = [ @@ -41,8 +40,7 @@ const positions = [ Since we've added a z-component to our vertices, we need to update the `numComponents` of our `vertexPosition` attribute to 3. -> [!NOTE] -> In the `setPositionAttribute()` function of your "draw-scene.js" module, change the `numComponents` constant from `2` to `3`: +In the `setPositionAttribute()` function of your "draw-scene.js" module, change the `numComponents` constant from `2` to `3`: ```js const numComponents = 3; @@ -52,8 +50,7 @@ const numComponents = 3; We also need to build an array of colors for each of the 24 vertices. This code starts by defining a color for each face, then uses a loop to assemble an array of all the colors for each of the vertices. -> [!NOTE] -> In the `initColorBuffer()` function of your "init-buffers.js" module, replace the `colors` declaration with this code: +In the `initColorBuffer()` function of your "init-buffers.js" module, replace the `colors` declaration with this code: ```js const faceColors = [ @@ -67,10 +64,9 @@ const faceColors = [ // Convert the array of colors into a table for all the vertices. -var colors = []; +let colors = []; -for (var j = 0; j < faceColors.length; ++j) { - const c = faceColors[j]; +for (const c of faceColors) { // Repeat each color four times for the four vertices of the face colors = colors.concat(c, c, c, c); } @@ -80,8 +76,7 @@ for (var j = 0; j < faceColors.length; ++j) { Once the vertex arrays are generated, we need to build the element array. -> [!NOTE] -> In your "init-buffer.js" module, add the following function: +In your "init-buffer.js" module, add the following function: ```js function initIndexBuffer(gl) { @@ -92,43 +87,14 @@ function initIndexBuffer(gl) { // indices into the vertex array to specify each triangle's // position. + // prettier-ignore const indices = [ - 0, - 1, - 2, - 0, - 2, - 3, // front - 4, - 5, - 6, - 4, - 6, - 7, // back - 8, - 9, - 10, - 8, - 10, - 11, // top - 12, - 13, - 14, - 12, - 14, - 15, // bottom - 16, - 17, - 18, - 16, - 18, - 19, // right - 20, - 21, - 22, - 20, - 22, - 23, // left + 0, 1, 2, 0, 2, 3, // front + 4, 5, 6, 4, 6, 7, // back + 8, 9, 10, 8, 10, 11, // top + 12, 13, 14, 12, 14, 15, // bottom + 16, 17, 18, 16, 18, 19, // right + 20, 21, 22, 20, 22, 23, // left ]; // Now send the element array to GL @@ -147,33 +113,34 @@ The `indices` array defines each face like a pair of triangles, specifying each Next, you need to call this new function from `initBuffers()`, and return the buffer it creates. -> [!NOTE] -> At the end of the `initBuffers()` function of your "init-buffers.js" module, add the following code, replacing the existing `return` statement: +At the end of the `initBuffers()` function of your "init-buffers.js" module, add the following code, replacing the existing `return` statement: ```js -const indexBuffer = initIndexBuffer(gl); +function initBuffers(gl) { + // … -return { - position: positionBuffer, - color: colorBuffer, - indices: indexBuffer, -}; + const indexBuffer = initIndexBuffer(gl); + + return { + position: positionBuffer, + color: colorBuffer, + indices: indexBuffer, + }; +} ``` ## Drawing the cube Next we need to add code to our `drawScene()` function to draw using the cube's index buffer, adding new {{domxref("WebGLRenderingContext.bindBuffer()", "gl.bindBuffer()")}} and {{domxref("WebGLRenderingContext.drawElements()", "gl.drawElements()")}} calls. -> [!NOTE] -> In your `drawScene()` function, add the following code just before the `gl.useProgram` line: +In your `drawScene()` function, add the following code just before the `gl.useProgram` line: ```js // Tell WebGL which indices to use to index the vertices gl.bindBuffer(gl.ELEMENT_ARRAY_BUFFER, buffers.indices); ``` -> [!NOTE] -> In the `drawScene()` function of your "draw-scene.js" module, replace the block just after the two `gl.uniformMatrix4fv` calls, that contains the `gl.drawArrays()` line, with the following block: +In the `drawScene()` function of your "draw-scene.js" module, replace the block just after the two `gl.uniformMatrix4fv` calls, that contains the `gl.drawArrays()` line, with the following block: ```js { @@ -188,22 +155,21 @@ Since each face of our cube is comprised of two triangles, there are 6 vertices Finally, let's replace our variable `squareRotation` by `cubeRotation` and add a second rotation around the x axis. -> [!NOTE] -> At the start of your "webgl-demo.js" file, replace the `squareRotation` declaration with this line: +At the start of your "webgl-demo.js" file, replace the `squareRotation` declaration with this line: ```js let cubeRotation = 0.0; ``` -> [!NOTE] -> In your `drawScene()` function declaration, replace the `squareRotation` with `cubeRotation`: +In your `drawScene()` function declaration, replace the `squareRotation` with `cubeRotation`: -```js-nolint +```js function drawScene(gl, programInfo, buffers, cubeRotation) { + // … +} ``` -> [!NOTE] -> In your `drawScene()` function, replace the `mat4.rotate` call with the following code: +In your `drawScene()` function, replace the `mat4.rotate` call with the following code: ```js mat4.rotate( @@ -226,8 +192,7 @@ mat4.rotate( ); // axis to rotate around (X) ``` -> [!NOTE] -> In your `main()` function, replace the code that calls `drawScene()` and updates `squareRotation` to pass in and update `cubeRotation` instead: +In your `main()` function, replace the code that calls `drawScene()` and updates `squareRotation` to pass in and update `cubeRotation` instead: ```js drawScene(gl, programInfo, buffers, cubeRotation); diff --git a/files/en-us/web/api/webgl_api/tutorial/lighting_in_webgl/index.md b/files/en-us/web/api/webgl_api/tutorial/lighting_in_webgl/index.md index 0a335425fec30ce..ccfccc8ee82833a 100644 --- a/files/en-us/web/api/webgl_api/tutorial/lighting_in_webgl/index.md +++ b/files/en-us/web/api/webgl_api/tutorial/lighting_in_webgl/index.md @@ -10,7 +10,7 @@ As should be clear by now, WebGL doesn't have much built-in knowledge. It just r ## Simulating lighting and shading in 3D -Although going into detail about the theory behind simulated lighting in 3D graphics is far beyond the scope of this article, it's helpful to know a bit about how it works. Instead of discussing it in depth here, take a look at the article on [Phong shading](https://en.wikipedia.org/wiki/Phong_shading) at Wikipedia, which provides a good overview of the most commonly used lighting model or if you'd like to see a WebGL based explanation [see this article](https://webglfundamentals.org/webgl/lessons/webgl-3d-lighting-point.html). +Although going into detail about the theory behind simulated lighting in 3D graphics is far beyond the scope of this article, it's helpful to know a bit about how it works. Instead of discussing it in depth here, take a look at the article on [Phong shading](https://en.wikipedia.org/wiki/Phong_shading) at Wikipedia, which provides a good overview of the most commonly used lighting model. Or if you'd like to see a WebGL based explanation, read [WebGL 3D - Point Lighting](https://webglfundamentals.org/webgl/lessons/webgl-3d-lighting-point.html). There are three basic types of lighting: diff --git a/files/en-us/web/api/webgl_api/tutorial/using_textures_in_webgl/index.md b/files/en-us/web/api/webgl_api/tutorial/using_textures_in_webgl/index.md index 914bf866eb2a4ad..03fb9147be56b8a 100644 --- a/files/en-us/web/api/webgl_api/tutorial/using_textures_in_webgl/index.md +++ b/files/en-us/web/api/webgl_api/tutorial/using_textures_in_webgl/index.md @@ -13,7 +13,7 @@ Now that our sample program has a rotating 3D cube, let's map a texture onto it The first thing to do is add code to load the textures. In our case, we'll be using a single texture, mapped onto all six sides of our rotating cube, but the same technique can be used for any number of textures. > [!NOTE] -> It's important to note that the loading of textures follows [cross-domain rules](/en-US/docs/Web/HTTP/CORS); that is, you can only load textures from sites for which your content has CORS approval. See [Cross-domain textures below](#cross-domain_textures) for details. +> It's important to note that the loading of textures follows [cross-domain rules](/en-US/docs/Web/HTTP/Guides/CORS); that is, you can only load textures from sites for which your content has CORS approval. See [Cross-domain textures below](#cross-domain_textures) for details. > [!NOTE] > Add these two functions to your "webgl-demo.js" script: @@ -321,15 +321,15 @@ WebGL provides a minimum of 8 texture units; the first of these is `gl.TEXTURE0` Lastly, add `texture` as a parameter to the `drawScene()` function, both where it is defined and where it is called. -> [!NOTE] -> Update the declaration of your `drawScene()` function to add the new parameter: +Update the declaration of your `drawScene()` function to add the new parameter: -```js-nolint +```js function drawScene(gl, programInfo, buffers, texture, cubeRotation) { + // … +} ``` -> [!NOTE] -> Update the place in your `main()` function where you call `drawScene()`: +Update the place in your `main()` function where you call `drawScene()`: ```js drawScene(gl, programInfo, buffers, texture, cubeRotation); @@ -343,7 +343,7 @@ At this point, the rotating cube should be good to go. ## Cross-domain textures -Loading of WebGL textures is subject to cross-domain access controls. In order for your content to load a texture from another domain, CORS approval needs to be obtained. See [HTTP access control](/en-US/docs/Web/HTTP/CORS) for details on CORS. +Loading of WebGL textures is subject to cross-domain access controls. In order for your content to load a texture from another domain, CORS approval needs to be obtained. See [HTTP access control](/en-US/docs/Web/HTTP/Guides/CORS) for details on CORS. Because WebGL now requires textures to be loaded from secure contexts, you can't use textures loaded from `file:///` URLs in WebGL. That means that you'll need a secure web server to test and deploy your code. For local testing, see our guide [How do you set up a local testing server?](/en-US/docs/Learn_web_development/Howto/Tools_and_setup/set_up_a_local_testing_server) for help. diff --git a/files/en-us/web/api/webgl_api/types/index.md b/files/en-us/web/api/webgl_api/types/index.md index 0880d916be899a4..45de76cdd14791e 100644 --- a/files/en-us/web/api/webgl_api/types/index.md +++ b/files/en-us/web/api/webgl_api/types/index.md @@ -64,7 +64,7 @@ These types are used within a {{domxref("WebGLRenderingContext")}}. <tr> <td><code>GLsizei</code></td> <td><code>long</code></td> - <td>Used for sizes (e.g. width and height of the drawing buffer).</td> + <td>Used for sizes (e.g., width and height of the drawing buffer).</td> </tr> <tr> <td><code>GLintptr</code></td> diff --git a/files/en-us/web/api/webgl_api/webgl_best_practices/index.md b/files/en-us/web/api/webgl_api/webgl_best_practices/index.md index 8d3b53a42ae4a7a..b73bf1fe7962494 100644 --- a/files/en-us/web/api/webgl_api/webgl_best_practices/index.md +++ b/files/en-us/web/api/webgl_api/webgl_best_practices/index.md @@ -108,7 +108,7 @@ In production code, avoid such entry points, especially on the browser main thre - `get*Parameter()` in general: possible flush + round-trip. In some cases, these will be cached to avoid the round-trip, but try to avoid relying on this. - `checkFramebufferStatus()`: possible flush + round-trip. - `getBufferSubData()`: usual finish + round-trip. (This is okay for READ buffers in conjunction with fences - see [async data readback](#use_non-blocking_async_data_readback) below.) -- `readPixels()` to the CPU (i.e. without an UNPACK buffer bound): finish + round-trip. Instead, use GPU-GPU `readPixels` in conjunction with async data readback. +- `readPixels()` to the CPU (i.e., without an UNPACK buffer bound): finish + round-trip. Instead, use GPU-GPU `readPixels` in conjunction with async data readback. ## Always enable vertex attrib 0 as an array @@ -120,7 +120,7 @@ WebGL doesn't offer APIs to query the maximum amount of video memory on the syst One technique pioneered by the Google Maps team is the notion of a _per-pixel VRAM budget_: -1\) For one system (e.g. a particular desktop / laptop), decide the maximum amount of VRAM your application should use. 2) Compute the number of pixels covered by a maximized browser window. E.g. `(window.innerWidth * devicePixelRatio) * (window.innerHeight * window.devicePixelRatio)` 3) The per-pixel VRAM budget is (1) divided by (2), and is a constant. +1\) For one system (e.g., a particular desktop / laptop), decide the maximum amount of VRAM your application should use. 2) Compute the number of pixels covered by a maximized browser window. E.g. `(window.innerWidth * devicePixelRatio) * (window.innerHeight * window.devicePixelRatio)` 3) The per-pixel VRAM budget is (1) divided by (2), and is a constant. This constant should _generally_ be portable among systems. Mobile devices typically have smaller screens than powerful desktop machines with large monitors. Re-compute this constant on a few target systems to get a reliable estimate. @@ -389,7 +389,7 @@ It may work on your system, but on many others it won't. Avoid it if you can. Ch Float16-blending is always supported. -## Some formats (e.g. RGB) may be emulated +## Some formats (e.g., RGB) may be emulated A number of formats (particularly three-channel formats) are emulated. For example, RGB32F is often actually RGBA32F, and Luminance8 may actually be RGBA8. RGB8 in particular is often surprisingly slow, as masking out the alpha channel and/or patching blend functions has fairly high overhead. Prefer to use RGBA8 and ignore the alpha yourself for better performance. @@ -401,7 +401,7 @@ Most applications, even those requiring alpha blending, can be structured to pro ## Consider compressed texture formats -While JPG and PNG are generally smaller over-the-wire, GPU compressed texture formats are smaller on in GPU memory, and are faster to sample from. (This reduces texture memory bandwidth, which is precious on mobile) However, compressed texture formats have worse quality than JPG, and are generally only acceptable for colors (not e.g. normals or coordinates). +While JPG and PNG are generally smaller over-the-wire, GPU compressed texture formats are smaller on in GPU memory, and are faster to sample from. (This reduces texture memory bandwidth, which is precious on mobile) However, compressed texture formats have worse quality than JPG, and are generally only acceptable for colors (not e.g., normals or coordinates). Unfortunately, there's no single universally supported format. Every system has at least one of the following though: @@ -428,7 +428,7 @@ Depth and stencil attachments and formats are actually inseparable on many devic ## texImage/texSubImage uploads (esp. videos) can cause pipeline flushes -Most texture uploads from DOM elements will incur a processing pass that will temporarily switch GL Programs internally, causing a pipeline flush. (Pipelines are formalized explicitly in [Vulkan](https://registry.khronos.org/vulkan/specs/1.2/html/chap9.html#VkGraphicsPipelineCreateInfo) et al, but are implicit behind-the-scenes in OpenGL and WebGL. Pipelines are more or less the tuple of shader program, depth/stencil/multisample/blend/rasterization state) +Most texture uploads from DOM elements will incur a processing pass that will temporarily switch GL Programs internally, causing a pipeline flush. (Pipelines are formalized explicitly in [Vulkan](https://docs.vulkan.org/spec/latest/chapters/pipelines.html) et al, but are implicit behind-the-scenes in OpenGL and WebGL. Pipelines are more or less the tuple of shader program, depth/stencil/multisample/blend/rasterization state) In WebGL: @@ -528,7 +528,7 @@ function clientWaitAsync(gl, sync, flags, interval_ms) { function test() { const res = gl.clientWaitSync(sync, flags, 0); if (res === gl.WAIT_FAILED) { - reject(); + reject(new Error("clientWaitSync failed")); return; } if (res === gl.TIMEOUT_EXPIRED) { @@ -587,29 +587,28 @@ Demo: [Device pixel presnap](https://kdashg.github.io/misc/webgl/device-pixel-pr ## ResizeObserver and 'device-pixel-content-box' -On supporting browsers (Chromium?), `ResizeObserver` can be used with `'device-pixel-content-box'` to request a callback that includes the true {{glossary("device pixel")}} size of an element. This can be used to build an async-but-accurate function: +On [supporting browsers](/en-US/docs/Web/API/ResizeObserverEntry/devicePixelContentBoxSize#browser_compatibility), `ResizeObserver` can be used with `'device-pixel-content-box'` to request a callback that includes the true {{glossary("device pixel")}} size of an element. This can be used to build an async-but-accurate function: ```js -window.getDevicePixelSize = - window.getDevicePixelSize || - (async (elem) => { - await new Promise((fn_resolve) => { - const observer = new ResizeObserver((entries) => { - for (const cur of entries) { - const dev_size = cur.devicePixelContentBoxSize; - const ret = { - width: dev_size[0].inlineSize, - height: dev_size[0].blockSize, - }; - fn_resolve(ret); - observer.disconnect(); - return; - } - throw `device-pixel-content-box not observed for elem ${elem}`; - }); - observer.observe(elem, { box: "device-pixel-content-box" }); +function getDevicePixelSize(elem) { + return new Promise((resolve) => { + const observer = new ResizeObserver(([cur]) => { + if (!cur) { + throw new Error( + `device-pixel-content-box not observed for elem ${elem}`, + ); + } + const devSize = cur.devicePixelContentBoxSize; + const ret = { + width: devSize[0].inlineSize, + height: devSize[0].blockSize, + }; + resolve(ret); + observer.disconnect(); }); + observer.observe(elem, { box: "device-pixel-content-box" }); }); +} ``` Please refer to [the specification](https://www.w3.org/TR/resize-observer/#resize-observer-interface) for more details. diff --git a/files/en-us/web/api/webgl_api/webgl_model_view_projection/index.md b/files/en-us/web/api/webgl_api/webgl_model_view_projection/index.md index 9e15e471824ec65..466164913f495ea 100644 --- a/files/en-us/web/api/webgl_api/webgl_model_view_projection/index.md +++ b/files/en-us/web/api/webgl_api/webgl_model_view_projection/index.md @@ -78,7 +78,7 @@ WebGLBox.prototype.draw = function (settings) { // drawn to the screen. There are two that form a square. const data = new Float32Array([ - //Triangle 1 + // Triangle 1 settings.left, settings.bottom, settings.depth, @@ -89,7 +89,7 @@ WebGLBox.prototype.draw = function (settings) { settings.top, settings.depth, - //Triangle 2 + // Triangle 2 settings.left, settings.top, settings.depth, @@ -260,9 +260,9 @@ The clipping of points and polygons from clip space happens before the homogeneo To start playing with this idea the previous example can be modified to allow for the use of the `w` component. ```js -//Redefine the triangles to use the W component +// Redefine the triangles to use the W component const data = new Float32Array([ - //Triangle 1 + // Triangle 1 settings.left, settings.bottom, settings.depth, @@ -276,7 +276,7 @@ const data = new Float32Array([ settings.depth, settings.w, - //Triangle 2 + // Triangle 2 settings.left, settings.top, settings.depth, @@ -368,7 +368,7 @@ The following code sample defines a method on the `CubeDemo` object that will cr ```js CubeDemo.prototype.computeModelMatrix = function (now) { - //Scale down by 50% + // Scale down by 50% const scale = MDN.scaleMatrix(0.5, 0.5, 0.5); // Rotate around X according to time @@ -473,7 +473,7 @@ The last step of filling in the w component can actually be accomplished with a const identity = [1, 0, 0, 0, 0, 1, 0, 0, 0, 0, 1, 0, 0, 0, 0, 1]; MDN.multiplyPoint(identity, [2, 3, 4, 1]); -//> [2, 3, 4, 1] +// [2, 3, 4, 1] ``` Then move the last column's 1 up one space. @@ -482,7 +482,7 @@ Then move the last column's 1 up one space. const copyZ = [1, 0, 0, 0, 0, 1, 0, 0, 0, 0, 1, 1, 0, 0, 0, 0]; MDN.multiplyPoint(copyZ, [2, 3, 4, 1]); -//> [2, 3, 4, 4] +// [2, 3, 4, 4] ``` However in the last example we performed `(z + 1) * scaleFactor`: @@ -490,48 +490,37 @@ However in the last example we performed `(z + 1) * scaleFactor`: ```js const scaleFactor = 0.5; +// prettier-ignore const simpleProjection = [ - 1, - 0, - 0, - 0, - 0, - 1, - 0, - 0, - 0, - 0, - 1, - scaleFactor, - 0, - 0, - 0, - scaleFactor, + 1, 0, 0, 0, + 0, 1, 0, 0, + 0, 0, 1, scaleFactor, + 0, 0, 0, scaleFactor, ]; MDN.multiplyPoint(simpleProjection, [2, 3, 4, 1]); -//> [2, 3, 4, 2.5] +// [2, 3, 4, 2.5] ``` Breaking it out a little further we can see how this works: ```js -let x = 2 * 1 + 3 * 0 + 4 * 0 + 1 * 0; -let y = 2 * 0 + 3 * 1 + 4 * 0 + 1 * 0; -let z = 2 * 0 + 3 * 0 + 4 * 1 + 1 * 0; -let w = 2 * 0 + 3 * 0 + 4 * scaleFactor + 1 * scaleFactor; +const x = 2 * 1 + 3 * 0 + 4 * 0 + 1 * 0; +const y = 2 * 0 + 3 * 1 + 4 * 0 + 1 * 0; +const z = 2 * 0 + 3 * 0 + 4 * 1 + 1 * 0; +const w = 2 * 0 + 3 * 0 + 4 * scaleFactor + 1 * scaleFactor; ``` The last line could be simplified to: ```js -w = 4 * scaleFactor + 1 * scaleFactor; +const w = 4 * scaleFactor + 1 * scaleFactor; ``` Then factoring out the scaleFactor, we get this: ```js -w = (4 + 1) * scaleFactor; +const w = (4 + 1) * scaleFactor; ``` Which is exactly the same as the `(z + 1) * scaleFactor` that we used in the previous example. @@ -540,23 +529,12 @@ In the box demo, an additional `computeSimpleProjectionMatrix()` method is added ```js CubeDemo.prototype.computeSimpleProjectionMatrix = function (scaleFactor) { + // prettier-ignore this.transforms.projection = [ - 1, - 0, - 0, - 0, - 0, - 1, - 0, - 0, - 0, - 0, - 1, - scaleFactor, - 0, - 0, - 0, - scaleFactor, + 1, 0, 0, 0, + 0, 1, 0, 0, + 0, 0, 1, scaleFactor, + 0, 0, 0, scaleFactor, ]; }; ``` @@ -622,23 +600,12 @@ MDN.perspectiveMatrix = function ( const f = 1.0 / Math.tan(fieldOfViewInRadians / 2); const rangeInv = 1 / (near - far); + // prettier-ignore return [ - f / aspectRatio, - 0, - 0, - 0, - 0, - f, - 0, - 0, - 0, - 0, - (near + far) * rangeInv, - -1, - 0, - 0, - near * far * rangeInv * 2, - 0, + f / aspectRatio, 0, 0, 0, + 0, f, 0, 0, + 0, 0, (near + far) * rangeInv, -1, + 0, 0, near * far * rangeInv * 2, 0, ]; }; ``` diff --git a/files/en-us/web/api/webglprogram/index.md b/files/en-us/web/api/webglprogram/index.md index 70111e8645fa135..d794ca1980f8b75 100644 --- a/files/en-us/web/api/webglprogram/index.md +++ b/files/en-us/web/api/webglprogram/index.md @@ -24,7 +24,7 @@ gl.linkProgram(program); if (!gl.getProgramParameter(program, gl.LINK_STATUS)) { const info = gl.getProgramInfoLog(program); - throw `Could not compile WebGL program. \n\n${info}`; + throw new Error(`Could not compile WebGL program. \n\n${info}`); } ``` diff --git a/files/en-us/web/api/webglrenderingcontext/attachshader/index.md b/files/en-us/web/api/webglrenderingcontext/attachshader/index.md index 07fa4a3ce513cea..11f802d19536317 100644 --- a/files/en-us/web/api/webglrenderingcontext/attachshader/index.md +++ b/files/en-us/web/api/webglrenderingcontext/attachshader/index.md @@ -39,7 +39,7 @@ gl.linkProgram(program); if (!gl.getProgramParameter(program, gl.LINK_STATUS)) { const info = gl.getProgramInfoLog(program); - throw `Could not compile WebGL program. \n\n${info}`; + throw new Error(`Could not compile WebGL program. \n\n${info}`); } ``` diff --git a/files/en-us/web/api/webglrenderingcontext/bindtexture/index.md b/files/en-us/web/api/webglrenderingcontext/bindtexture/index.md index cc633d1299d37d2..fc4182d3f5c8761 100644 --- a/files/en-us/web/api/webglrenderingcontext/bindtexture/index.md +++ b/files/en-us/web/api/webglrenderingcontext/bindtexture/index.md @@ -23,16 +23,21 @@ bindTexture(target, texture) - : A {{domxref("WebGL_API/Types", "GLenum")}} specifying the binding point (target). Possible values: - - `gl.TEXTURE_2D`: A two-dimensional texture. - - `gl.TEXTURE_CUBE_MAP`: A cube-mapped texture. - When using a {{domxref("WebGL2RenderingContext", "WebGL 2 context", "", 1)}}, - the following values are available additionally: + - `gl.TEXTURE_2D` + - : A two-dimensional texture. + - `gl.TEXTURE_CUBE_MAP` + - : A cube-mapped texture. - - `gl.TEXTURE_3D`: A three-dimensional texture. - - `gl.TEXTURE_2D_ARRAY`: A two-dimensional array texture. + When using a {{domxref("WebGL2RenderingContext", "WebGL 2 context", "", 1)}}, the following values are available additionally: + + - `gl.TEXTURE_3D` + - : A three-dimensional texture. + - `gl.TEXTURE_2D_ARRAY` + - : A two-dimensional array texture. - `texture` - : A {{domxref("WebGLTexture")}} object to bind. + If `null` is passed, the currently bound texture for the specified target is unbound. ### Return value @@ -56,6 +61,13 @@ const texture = gl.createTexture(); gl.bindTexture(gl.TEXTURE_2D, texture); ``` +### Unbinding a texture + +```js +// Unbind any texture currently bound to TEXTURE_2D +gl.bindTexture(gl.TEXTURE_2D, null); +``` + ### Getting current bindings To check the current texture binding, query the `gl.TEXTURE_BINDING_2D` or diff --git a/files/en-us/web/api/webglrenderingcontext/bufferdata/index.md b/files/en-us/web/api/webglrenderingcontext/bufferdata/index.md index 5d7f29a208139ac..927515b46b98fe0 100644 --- a/files/en-us/web/api/webglrenderingcontext/bufferdata/index.md +++ b/files/en-us/web/api/webglrenderingcontext/bufferdata/index.md @@ -49,7 +49,8 @@ bufferData(target, srcData, usage) - : A {{domxref("WebGL_API/Types", "GLsizeiptr")}} setting the size in bytes of the buffer object's data store. - `srcData` {{optional_inline}} - - : An {{jsxref("ArrayBuffer")}}, {{jsxref("SharedArrayBuffer")}}, a {{jsxref("TypedArray")}} or a {{jsxref("DataView")}} + - : A {{jsxref("TypedArray")}} or a {{jsxref("DataView")}} that views an {{jsxref("ArrayBuffer")}} or + {{jsxref("SharedArrayBuffer")}} that will be copied into the data store. If `null`, a data store is still created, but the content is uninitialized and undefined. - `usage` diff --git a/files/en-us/web/api/webglrenderingcontext/buffersubdata/index.md b/files/en-us/web/api/webglrenderingcontext/buffersubdata/index.md index ecf2b451395f396..5e677d7d31ee8a2 100644 --- a/files/en-us/web/api/webglrenderingcontext/buffersubdata/index.md +++ b/files/en-us/web/api/webglrenderingcontext/buffersubdata/index.md @@ -52,7 +52,7 @@ bufferSubData(target, offset, srcData) - : A {{domxref("WebGL_API/Types", "GLintptr")}} specifying an offset in bytes where the data replacement will start. - `srcData` {{optional_inline}} - - : An {{jsxref("ArrayBuffer")}}, {{jsxref("SharedArrayBuffer")}}, a {{jsxref("DataView")}}, or a {{jsxref("TypedArray")}} + - : A {{jsxref("TypedArray")}} or a {{jsxref("DataView")}} that views an {{jsxref("ArrayBuffer")}} or {{jsxref("SharedArrayBuffer")}} that will be copied into the data store. - `srcOffset` - : A {{domxref("WebGL_API/Types", "GLuint")}} specifying the element index offset where to start reading diff --git a/files/en-us/web/api/webglrenderingcontext/createprogram/index.md b/files/en-us/web/api/webglrenderingcontext/createprogram/index.md index d7ecbc35b3a30c5..afd04b2ae5a12eb 100644 --- a/files/en-us/web/api/webglrenderingcontext/createprogram/index.md +++ b/files/en-us/web/api/webglrenderingcontext/createprogram/index.md @@ -43,7 +43,7 @@ gl.linkProgram(program); if (!gl.getProgramParameter(program, gl.LINK_STATUS)) { const info = gl.getProgramInfoLog(program); - throw `Could not compile WebGL program. \n\n${info}`; + throw new Error(`Could not compile WebGL program. \n\n${info}`); } ``` diff --git a/files/en-us/web/api/webglrenderingcontext/getcontextattributes/index.md b/files/en-us/web/api/webglrenderingcontext/getcontextattributes/index.md index 1746ab91fab24c4..2d2ec785a71e932 100644 --- a/files/en-us/web/api/webglrenderingcontext/getcontextattributes/index.md +++ b/files/en-us/web/api/webglrenderingcontext/getcontextattributes/index.md @@ -46,17 +46,17 @@ gl.getContextAttributes(); the `getContextAttributes` method returns an object that describes the attributes set on this context, for example: -```js +```json { - alpha: true, - antialias: true, - depth: true, - failIfMajorPerformanceCaveat: false, - powerPreference: "default", - premultipliedAlpha: true, - preserveDrawingBuffer: false, - stencil: false, - desynchronized: false + "alpha": true, + "antialias": true, + "depth": true, + "failIfMajorPerformanceCaveat": false, + "powerPreference": "default", + "premultipliedAlpha": true, + "preserveDrawingBuffer": false, + "stencil": false, + "desynchronized": false } ``` diff --git a/files/en-us/web/api/webglrenderingcontext/getextension/index.md b/files/en-us/web/api/webglrenderingcontext/getextension/index.md index d3fa97e39517458..8d1b77abda13c65 100644 --- a/files/en-us/web/api/webglrenderingcontext/getextension/index.md +++ b/files/en-us/web/api/webglrenderingcontext/getextension/index.md @@ -42,8 +42,7 @@ gl.getExtension("WEBGL_lose_context").loseContext(); ## WebGL extensions -Extensions for the WebGL API are registered in the [WebGL Extension Registry](https://registry.khronos.org/webgl/extensions/). They are also -listed [here](/en-US/docs/Web/API/WebGL_API#extensions). +Extensions for the WebGL API are registered in the [WebGL Extension Registry](https://registry.khronos.org/webgl/extensions/). They are also listed in our [WebGL API reference](/en-US/docs/Web/API/WebGL_API#extensions). ## Specifications diff --git a/files/en-us/web/api/webglrenderingcontext/getparameter/index.md b/files/en-us/web/api/webglrenderingcontext/getparameter/index.md index b826458f2b11e86..12c868df7c0ae31 100644 --- a/files/en-us/web/api/webglrenderingcontext/getparameter/index.md +++ b/files/en-us/web/api/webglrenderingcontext/getparameter/index.md @@ -126,7 +126,7 @@ You can query the following `pname` parameters when using a <tr> <td><code>gl.COLOR_WRITEMASK</code></td> <td> - sequence&#x3C;{{domxref("WebGL_API/Types", "GLboolean")}}> + <code>sequence&#x3C;{{domxref("WebGL_API/Types", "GLboolean", "", "nocode")}}></code> (with 4 values) </td> <td></td> diff --git a/files/en-us/web/api/webglrenderingcontext/getsupportedextensions/index.md b/files/en-us/web/api/webglrenderingcontext/getsupportedextensions/index.md index d629c37347c38cb..c5bf145426b3f55 100644 --- a/files/en-us/web/api/webglrenderingcontext/getsupportedextensions/index.md +++ b/files/en-us/web/api/webglrenderingcontext/getsupportedextensions/index.md @@ -41,7 +41,7 @@ specific extension object. ## WebGL extensions -Extensions for the WebGL API are registered in the [WebGL Extension Registry](https://registry.khronos.org/webgl/extensions/). They are also listed [here](/en-US/docs/Web/API/WebGL_API#extensions). +Extensions for the WebGL API are registered in the [WebGL Extension Registry](https://registry.khronos.org/webgl/extensions/). They are also listed in our [WebGL API reference](/en-US/docs/Web/API/WebGL_API#extensions). ## Specifications diff --git a/files/en-us/web/api/webglrenderingcontext/validateprogram/index.md b/files/en-us/web/api/webglrenderingcontext/validateprogram/index.md index df12233f1de55e4..3adf84da6a0c261 100644 --- a/files/en-us/web/api/webglrenderingcontext/validateprogram/index.md +++ b/files/en-us/web/api/webglrenderingcontext/validateprogram/index.md @@ -42,7 +42,7 @@ gl.validateProgram(program); if (!gl.getProgramParameter(program, gl.LINK_STATUS)) { const info = gl.getProgramInfoLog(program); - throw `Could not compile WebGL program. \n\n${info}`; + throw new Error(`Could not compile WebGL program. \n\n${info}`); } gl.useProgram(program); diff --git a/files/en-us/web/api/webglrenderingcontext/vertexattrib/index.md b/files/en-us/web/api/webglrenderingcontext/vertexattrib/index.md index ba788c0dbc0271d..40842ebcb4d61e0 100644 --- a/files/en-us/web/api/webglrenderingcontext/vertexattrib/index.md +++ b/files/en-us/web/api/webglrenderingcontext/vertexattrib/index.md @@ -61,15 +61,15 @@ change the values is by calling this function again. ```js const a_foobar = gl.getAttribLocation(shaderProgram, "foobar"); -//either set each component individually: +// Either set each component individually: gl.vertexAttrib3f(a_foobar, 10.0, 5.0, 2.0); -//or provide a Float32Array: +// Or provide a Float32Array: const floatArray = new Float32Array([10.0, 5.0, 2.0]); gl.vertexAttrib3fv(a_foobar, floatArray); ``` ```js -// we want to load the following 3x3 matrix into attribute named "matrix3x3" +// We want to load the following 3x3 matrix into attribute named "matrix3x3" // 0 1 2 // 3 4 5 // 6 7 8 diff --git a/files/en-us/web/api/webglrenderingcontext/vertexattribpointer/index.md b/files/en-us/web/api/webglrenderingcontext/vertexattribpointer/index.md index 55e69f6668d3764..215326f08e8f939 100644 --- a/files/en-us/web/api/webglrenderingcontext/vertexattribpointer/index.md +++ b/files/en-us/web/api/webglrenderingcontext/vertexattribpointer/index.md @@ -84,7 +84,7 @@ None ({{jsxref("undefined")}}). the ARRAY_BUFFER target. - When using a {{domxref("WebGL2RenderingContext", "WebGL 2 context", "", 1)}}, a `gl.INVALID_OPERATION` error is thrown if this vertex attribute is defined - as an integer in the vertex shader (e.g. `uvec4` or `ivec4`, + as an integer in the vertex shader (e.g., `uvec4` or `ivec4`, instead of `vec4`). ## Description @@ -136,7 +136,7 @@ they are stored in the array buffer. You have two options: While the `ArrayBuffer` can be filled with both integers and floats, the attributes will always be converted to a float when they are sent to the vertex shader. If you need to use integers in your vertex shader code, you can either cast the float -back to an integer in the vertex shader (e.g. `(int) floatNumber`), or use +back to an integer in the vertex shader (e.g., `(int) floatNumber`), or use {{domxref("WebGL2RenderingContext.vertexAttribIPointer()", "gl.vertexAttribIPointer()")}} from WebGL2. ### Default attribute values @@ -149,7 +149,7 @@ to tell WebGL to use the default value, while calling {{domxref("WebGLRenderingContext.enableVertexAttribArray()", "gl.enableVertexAttribArray()")}} will read the values from the array buffer as specified with `gl.vertexAttribPointer()`. -Similarly, if our vertex shader expects e.g. a 4-component attribute with +Similarly, if our vertex shader expects e.g., a 4-component attribute with `vec4` but in our `gl.vertexAttribPointer()` call we set the `size` to `2`, then WebGL will set the first two components based on the array buffer, while the third and fourth components are taken from the default @@ -169,7 +169,7 @@ color. You can call {{domxref("WebGLRenderingContext.getVertexAttrib()", "gl.getVertexAttrib()")}} and {{domxref("WebGLRenderingContext.getVertexAttribOffset()", "gl.getVertexAttribOffset()")}} to -get the current parameters for an attribute, e.g. the +get the current parameters for an attribute, e.g., the data type or whether the attribute should be normalized. Keep in mind that these WebGL functions have a slow performance and it is better to store the state inside your JavaScript application. However, these functions are great for debugging a WebGL context @@ -235,7 +235,7 @@ vertices.forEach((vertex, i) => { ``` For higher performance, we could also do the previous JSON to ArrayBuffer conversion on -the server-side, e.g. with Node.js. Then we could load the binary file and interpret it +the server-side, e.g., with Node.js. Then we could load the binary file and interpret it as an array buffer: ```js @@ -248,7 +248,7 @@ const buffer = await response.arrayBuffer(); First, we create a new Vertex Buffer Object (VBO) and supply it with our array buffer: ```js -//Bind array buffer to a Vertex Buffer Object +// Bind array buffer to a Vertex Buffer Object const vbo = gl.createBuffer(); gl.bindBuffer(gl.ARRAY_BUFFER, vbo); gl.bufferData(gl.ARRAY_BUFFER, buffer, gl.STATIC_DRAW); @@ -258,23 +258,23 @@ Then, we specify the memory layout of the array buffer, either by setting the in ourselves: ```js -//Describe the layout of the buffer: -//1. position, not normalized +// Describe the layout of the buffer: +// 1. position, not normalized gl.vertexAttribPointer(0, 3, gl.FLOAT, false, 20, 0); gl.enableVertexAttribArray(0); -//2. normal vector, normalized to [-1, 1] +// 2. normal vector, normalized to [-1, 1] gl.vertexAttribPointer(1, 4, gl.BYTE, true, 20, 12); gl.enableVertexAttribArray(1); -//3. texture coordinates, normalized to [0, 1] +// 3. texture coordinates, normalized to [0, 1] gl.vertexAttribPointer(2, 2, gl.UNSIGNED_SHORT, true, 20, 16); gl.enableVertexAttribArray(2); -//Set the attributes in the vertex shader to the same indices +// Set the attributes in the vertex shader to the same indices gl.bindAttribLocation(shaderProgram, 0, "position"); gl.bindAttribLocation(shaderProgram, 1, "normal"); gl.bindAttribLocation(shaderProgram, 2, "texUV"); -//Since the attribute indices have changed, we must re-link the shader -//Note that this will reset all uniforms that were previously set. +// Since the attribute indices have changed, we must re-link the shader +// Note that this will reset all uniforms that were previously set. gl.linkProgram(shaderProgram); ``` diff --git a/files/en-us/web/api/webglshader/index.md b/files/en-us/web/api/webglshader/index.md index c880fc291fa9561..9c75df744a66b4f 100644 --- a/files/en-us/web/api/webglshader/index.md +++ b/files/en-us/web/api/webglshader/index.md @@ -24,7 +24,7 @@ function createShader(gl, sourceCode, type) { if (!gl.getShaderParameter(shader, gl.COMPILE_STATUS)) { const info = gl.getShaderInfoLog(shader); - throw `Could not compile WebGL program. \n\n${info}`; + throw new Error(`Could not compile WebGL program. \n\n${info}`); } return shader; } @@ -45,17 +45,19 @@ const vertexShaderSource = " gl_Position = position;\n" + "}\n"; -//Use the createShader function from the example above +// Use the createShader function from the example above const vertexShader = createShader(gl, vertexShaderSource, gl.VERTEX_SHADER); ``` ### Creating a fragment shader ```js -const fragmentShaderSource = - "void main() {\n" + " gl_FragColor = vec4(1.0, 1.0, 1.0, 1.0);\n" + "}\n"; +const fragmentShaderSource = `void main() { + gl_FragColor = vec4(1.0, 1.0, 1.0, 1.0); +} +`; -//Use the createShader function from the example above +// Use the createShader function from the example above const fragmentShader = createShader( gl, fragmentShaderSource, diff --git a/files/en-us/web/api/webgpu_api/index.md b/files/en-us/web/api/webgpu_api/index.md index bc1ac53d9fba14e..1e89995f9d73bff 100644 --- a/files/en-us/web/api/webgpu_api/index.md +++ b/files/en-us/web/api/webgpu_api/index.md @@ -42,7 +42,7 @@ There are several layers of abstraction between a device GPU and a web browser r > [!NOTE] > The above diagram assumes a device with only one GPU. -- A native GPU API, which is part of the OS (e.g. Metal on macOS), is a programming interface allowing native applications to use the capabilities of the GPU. API instructions are sent to the GPU (and responses received) via a driver. It is possible for a system to have multiple native OS APIs and drivers available to communicate with the GPU, although the above diagram assumes a device with only one native API/driver. +- A native GPU API, which is part of the OS (e.g., Metal on macOS), is a programming interface allowing native applications to use the capabilities of the GPU. API instructions are sent to the GPU (and responses received) via a driver. It is possible for a system to have multiple native OS APIs and drivers available to communicate with the GPU, although the above diagram assumes a device with only one native API/driver. - A browser's WebGPU implementation handles communicating with the GPU via a native GPU API driver. A WebGPU adapter effectively represents a physical GPU and driver available on the underlying system, in your code. - A logical device is an abstraction via which a single web app can access GPU capabilities in a compartmentalized way. Logical devices are required to provide multiplexing capabilities. A physical device's GPU is used by many applications and processes concurrently, including potentially many web apps. Each web app needs to be able to access WebGPU in isolation for security and logic reasons. @@ -69,7 +69,7 @@ async function init() { const device = await adapter.requestDevice(); - //... + // … } ``` @@ -157,7 +157,7 @@ const canvas = document.querySelector("#gpuCanvas"); const context = canvas.getContext("webgpu"); context.configure({ - device: device, + device, format: navigator.gpu.getPreferredCanvasFormat(), alphaMode: "premultiplied", }); @@ -225,7 +225,7 @@ Next, we create a descriptor object that specifies the configuration of our rend In addition, in the case of the vertex shader stage we provide our `vertexBuffers` object to provide the expected state of our vertex data. And in the case of our fragment shader stage, we provide an array of color target states that indicate the specified rendering format (this matches the format specified in our canvas context config earlier). -We also specify a `primitive` state, which in this case just states the type of primitive we will be drawing, and a `layout` of `auto`. The `layout` property defines the layout (structure, purpose, and type) of all the GPU resources (buffers, textures, etc.) used during the execution of the pipeline. In more complex apps, this would take the form of a {{domxref("GPUPipelineLayout")}} object, created using {{domxref("GPUDevice.createPipelineLayout()")}} (you can see an example in our [Basic compute pipeline](#basic_compute_pipeline)), which allows the GPU to figure out how to run the pipeline most efficiently ahead of time. Here however we are specifying the `auto` value, which will cause the pipeline to generate an implicit bind group layout based on any bindings defined in the shader code. +We also specify a `primitive` object, which in this case just states the type of primitive we will be drawing, and a `layout` of `auto`. The `layout` property defines the layout (structure, purpose, and type) of all the GPU resources (buffers, textures, etc.) used during the execution of the pipeline. In more complex apps, this would take the form of a {{domxref("GPUPipelineLayout")}} object, created using {{domxref("GPUDevice.createPipelineLayout()")}} (you can see an example in our [Basic compute pipeline](#basic_compute_pipeline)), which allows the GPU to figure out how to run the pipeline most efficiently ahead of time. However, we are specifying the `auto` value, which will cause the pipeline to generate an implicit bind group layout based on any bindings defined in the shader code. ```js const pipelineDescriptor = { @@ -516,7 +516,7 @@ You can find more information about WebGPU error handling in the explainer — s - {{domxref("HTMLCanvasElement.getContext()")}} — the `"webgpu"` `contextType` - : Invoking `getContext()` with the `"webgpu"` `contextType` returns a {{domxref("GPUCanvasContext")}} object instance, which can then be configured with {{domxref("GPUCanvasContext.configure()")}}. - {{domxref("GPUCanvasContext")}} - - : Represents the WebGPU rendering context of an {{htmlelement("canvas")}} element. + - : Represents the WebGPU rendering context of a {{htmlelement("canvas")}} element. ### Representing pipeline resources diff --git a/files/en-us/web/api/webotp_api/index.md b/files/en-us/web/api/webotp_api/index.md index 7c3f56fe8d28b1f..407a2713ecc4389 100644 --- a/files/en-us/web/api/webotp_api/index.md +++ b/files/en-us/web/api/webotp_api/index.md @@ -20,7 +20,7 @@ Phone numbers are often used as a way to identify the user of an app. An SMS is OTP use cases include: -- Improving sign-in security by using a phone number as an extra factor (i.e. for two-factor authentication (2FA) or multifactor authentication (MFA)). +- Improving sign-in security by using a phone number as an extra factor (i.e., for two-factor authentication (2FA) or multifactor authentication (MFA)). - Verifying sensitive actions such as payments. The WebOTP API allows web apps to expedite this validation process by copying the OTP from the SMS and passing it to the app automatically after the user has provided consent (most native platforms have an equivalent API). @@ -83,7 +83,7 @@ In this case, the last line must consist of: ## Controlling access to the API -The availability of WebOTP can be controlled using a [Permissions Policy](/en-US/docs/Web/HTTP/Permissions_Policy) specifying a {{httpheader("Permissions-Policy/otp-credentials", "otp-credentials")}} directive. This directive has a default allowlist value of `"self"`, meaning that by default, these methods can be used in top-level document contexts. +The availability of WebOTP can be controlled using a [Permissions Policy](/en-US/docs/Web/HTTP/Guides/Permissions_Policy) specifying a {{httpheader("Permissions-Policy/otp-credentials", "otp-credentials")}} directive. This directive has a default allowlist value of `"self"`, meaning that by default, these methods can be used in top-level document contexts. You could specify a directive allowing the use of WebOTP in a specific cross-origin domain (i.e., inside an {{htmlelement("iframe")}}) like this: @@ -116,7 +116,7 @@ In this example, when an SMS message arrives and the user grants permission, an [Try this demo using a phone](https://web-otp.glitch.me/). -The form field includes an [`autocomplete`](/en-US/docs/Web/HTML/Attributes/autocomplete) attribute with the value of `one-time-code`. This is not needed for the WebOTP API to work, but it is worth including. As a result, Safari will prompt the user to autofill this field with the OTP when a correctly-formatted SMS is received, even though the WebOTP API isn't fully supported in Safari. +The form field includes an [`autocomplete`](/en-US/docs/Web/HTML/Reference/Attributes/autocomplete) attribute with the value of `one-time-code`. This is not needed for the WebOTP API to work, but it is worth including. As a result, Safari will prompt the user to autofill this field with the OTP when a correctly-formatted SMS is received, even though the WebOTP API isn't fully supported in Safari. ```html <input type="text" autocomplete="one-time-code" inputmode="numeric" /> diff --git a/files/en-us/web/api/webrtc_api/build_a_phone_with_peerjs/build_the_server/index.md b/files/en-us/web/api/webrtc_api/build_a_phone_with_peerjs/build_the_server/index.md index b11780a276477d1..8bab2d394394247 100644 --- a/files/en-us/web/api/webrtc_api/build_a_phone_with_peerjs/build_the_server/index.md +++ b/files/en-us/web/api/webrtc_api/build_a_phone_with_peerjs/build_the_server/index.md @@ -38,9 +38,10 @@ In this article we'll set up the server for our phone app. The server file will const express = require("express"); const http = require("http"); const path = require("path"); + const { ExpressPeerServer } = require("peer"); + const app = express(); const server = http.createServer(app); - const { ExpressPeerServer } = require("peer"); const port = process.env.PORT || "8000"; const peerServer = ExpressPeerServer(server, { diff --git a/files/en-us/web/api/webrtc_api/build_a_phone_with_peerjs/connect_peers/creating_a_call/index.md b/files/en-us/web/api/webrtc_api/build_a_phone_with_peerjs/connect_peers/creating_a_call/index.md index faceefe5b7072c7..37f831575721da5 100644 --- a/files/en-us/web/api/webrtc_api/build_a_phone_with_peerjs/connect_peers/creating_a_call/index.md +++ b/files/en-us/web/api/webrtc_api/build_a_phone_with_peerjs/connect_peers/creating_a_call/index.md @@ -26,10 +26,10 @@ Exciting times — now you're going to give your users the ability to create cal call.on("stream", (stream) => { // B - window.remoteAudio.srcObject = stream; // C - window.remoteAudio.autoplay = true; // D - window.peerStream = stream; //E - showConnectedContent(); //F }); + window.remoteAudio.srcObject = stream; + window.remoteAudio.autoplay = true; + window.peerStream = stream; + showConnectedContent(); }); }); ``` diff --git a/files/en-us/web/api/webrtc_api/build_a_phone_with_peerjs/connect_peers/get_microphone_permission/index.md b/files/en-us/web/api/webrtc_api/build_a_phone_with_peerjs/connect_peers/get_microphone_permission/index.md index 536809da0b1f86d..f3720c79f8ed369 100644 --- a/files/en-us/web/api/webrtc_api/build_a_phone_with_peerjs/connect_peers/get_microphone_permission/index.md +++ b/files/en-us/web/api/webrtc_api/build_a_phone_with_peerjs/connect_peers/get_microphone_permission/index.md @@ -31,7 +31,7 @@ The `getUserMedia()` endpoint takes a `constraints` object that specifies which Let's explain the most important lines: - `window.localStream = stream` attaches the `MediaStream` object (which we have assigned to `stream` on the previous line) to the window as the `localStream`. - - `window.localAudio.srcObject = stream` sets the [`<audio>` element](/en-US/docs/Web/HTML/Element/audio) with the ID of `localAudio`'s `src` attribute to be the `MediaStream` returned by the promise so that it will play our stream. + - `window.localAudio.srcObject = stream` sets the [`<audio>` element](/en-US/docs/Web/HTML/Reference/Elements/audio) with the ID of `localAudio`'s `src` attribute to be the `MediaStream` returned by the promise so that it will play our stream. - `window.localAudio.autoplay = true` sets the `autoplay` attribute of the `<audio>` element to true, so that the audio plays automatically. > [!WARNING] diff --git a/files/en-us/web/api/webrtc_api/build_a_phone_with_peerjs/index.md b/files/en-us/web/api/webrtc_api/build_a_phone_with_peerjs/index.md index 79c0503baa3c9f7..a0120245e3d20c5 100644 --- a/files/en-us/web/api/webrtc_api/build_a_phone_with_peerjs/index.md +++ b/files/en-us/web/api/webrtc_api/build_a_phone_with_peerjs/index.md @@ -21,7 +21,7 @@ This is an intermediate level tutorial; before attempting it you should already - [Express](/en-US/docs/Learn_web_development/Extensions/Server-side/Express_Nodejs) - [HTML](/en-US/docs/Web/HTML) -Before you get started, you'll want to make sure you've [installed node](https://nodejs.org/en/download/package-manager) and [Yarn](https://classic.yarnpkg.com/en/docs/install) (the instructions in later articles assume Yarn, but you can feel free to use [npm](https://docs.npmjs.com/getting-started/) or another manager if you'd prefer). +Before you get started, you'll want to make sure you've [installed node](https://nodejs.org/en/download) and [Yarn](https://classic.yarnpkg.com/en/docs/install) (the instructions in later articles assume Yarn, but you can feel free to use [npm](https://docs.npmjs.com/getting-started/) or another manager if you'd prefer). > [!NOTE] > If you learn better by following step-by-step code, we've also provided this [tutorial in code](https://github.com/SamsungInternet/WebPhone/tree/master/tutorial), which you can use instead. diff --git a/files/en-us/web/api/webrtc_api/build_a_phone_with_peerjs/setup/index.md b/files/en-us/web/api/webrtc_api/build_a_phone_with_peerjs/setup/index.md index 07dd717ad728fe0..a3738e7d2e4c19a 100644 --- a/files/en-us/web/api/webrtc_api/build_a_phone_with_peerjs/setup/index.md +++ b/files/en-us/web/api/webrtc_api/build_a_phone_with_peerjs/setup/index.md @@ -130,7 +130,7 @@ p { } button { - background-color: -internal-light-dark(white, black); + background-color: light-dark(white, black); padding: 1rem 10rem; border-radius: 3rem; border: none; diff --git a/files/en-us/web/api/webrtc_api/perfect_negotiation/index.md b/files/en-us/web/api/webrtc_api/perfect_negotiation/index.md index ded8afc8241f1f2..c840fe6802d953b 100644 --- a/files/en-us/web/api/webrtc_api/perfect_negotiation/index.md +++ b/files/en-us/web/api/webrtc_api/perfect_negotiation/index.md @@ -29,13 +29,11 @@ How you determine which peer is polite and which is impolite is generally up to An important thing to keep in mind is this: the roles of caller and callee can switch during perfect negotiation. If the polite peer is the caller and it sends an offer but there's a collision with the impolite peer, the polite peer drops its offer and instead replies to the offer it has received from the impolite peer. By doing so, the polite peer has switched from being the caller to the callee! -## Implementing perfect negotiation - Let's take a look at an example that implements the perfect negotiation pattern. The code assumes that there's a `SignalingChannel` class defined that is used to communicate with the signaling server. Your own code, of course, can use any signaling technique you like. Note that this code is identical for both peers involved in the connection. -### Create the signaling and peer connections +## Create the signaling and peer connections First, the signaling channel needs to be opened and the {{domxref("RTCPeerConnection")}} needs to be created. The {{Glossary("STUN")}} server listed here is obviously not a real one; you'll need to replace `stun.my-server.tld` with the address of a real STUN server. @@ -50,7 +48,7 @@ const pc = new RTCPeerConnection(config); This code also gets the {{HTMLElement("video")}} elements using the classes "self-view" and "remote-view"; these will contain, respectively, the local user's self-view and the view of the incoming stream from the remote peer. -### Connecting to a remote peer +## Connecting to a remote peer ```js const constraints = { audio: true, video: true }; @@ -75,7 +73,7 @@ The `start()` function shown above can be called by either of the two end-points This isn't appreciably different from older WebRTC connection establishment code. The user's camera and microphone are obtained by calling {{domxref("MediaDevices.getUserMedia", "getUserMedia()")}}. The resulting media tracks are then added to the {{domxref("RTCPeerConnection")}} by passing them into {{domxref("RTCPeerConnection.addTrack", "addTrack()")}}. Then, finally, the media source for the self-view {{HTMLElement("video")}} element indicated by the `selfVideo` constant is set to the camera and microphone stream, allowing the local user to see what the other peer sees. -### Handling incoming tracks +## Handling incoming tracks We next need to set up a handler for {{domxref("RTCPeerConnection.track_event", "track")}} events to handle inbound video and audio tracks that have been negotiated to be received by this peer connection. To do this, we implement the {{domxref("RTCPeerConnection")}}'s {{domxref("RTCPeerConnection.track_event", "ontrack")}} event handler. @@ -90,17 +88,17 @@ pc.ontrack = ({ track, streams }) => { }; ``` -When the `track` event occurs, this handler executes. Using [destructuring](/en-US/docs/Web/JavaScript/Reference/Operators/Destructuring_assignment), the {{domxref("RTCTrackEvent")}}'s {{domxref("RTCTrackEvent.track", "track")}} and {{domxref("RTCTrackEvent.streams", "streams")}} properties are extracted. The former is either the video track or the audio track being received. The latter is an array of {{domxref("MediaStream")}} objects, each representing a stream containing this track (a track may in rare cases belong to multiple streams at once). In our case, this will always contain one stream, at index 0, because we passed one stream into `addTrack()` earlier. +When the `track` event occurs, this handler executes. Using [destructuring](/en-US/docs/Web/JavaScript/Reference/Operators/Destructuring), the {{domxref("RTCTrackEvent")}}'s {{domxref("RTCTrackEvent.track", "track")}} and {{domxref("RTCTrackEvent.streams", "streams")}} properties are extracted. The former is either the video track or the audio track being received. The latter is an array of {{domxref("MediaStream")}} objects, each representing a stream containing this track (a track may in rare cases belong to multiple streams at once). In our case, this will always contain one stream, at index 0, because we passed one stream into `addTrack()` earlier. We add an unmute event handler to the track, because the track will become unmuted once it starts receiving packets. We put the remainder of our reception code in there. If we already have video coming in from the remote peer (which we can see if the remote view's `<video>` element's {{domxref("HTMLMediaElement.srcObject", "srcObject")}} property already has a value), we do nothing. Otherwise, we set `srcObject` to the stream at index 0 in the `streams` array. -### The perfect negotiation logic +## The perfect negotiation logic Now we get into the true perfect negotiation logic, which functions entirely independently from the rest of the application. -#### Handling the negotiationneeded event +### Handling the negotiationneeded event First, we implement the {{domxref("RTCPeerConnection")}} event handler {{domxref("RTCPeerConnection.negotiationneeded_event", "onnegotiationneeded")}} to get a local description and send it using the signaling channel to the remote peer. @@ -122,11 +120,9 @@ pc.onnegotiationneeded = async () => { Note that `setLocalDescription()` without arguments automatically creates and sets the appropriate description based on the current {{domxref("RTCPeerConnection.signalingState", "signalingState")}}. The set description is either an answer to the most recent offer from the remote peer _or_ a freshly-created offer if there's no negotiation underway. Here, it will always be an `offer`, because the negotiationneeded event is only fired in `stable` state. -We set a Boolean variable, `makingOffer` to `true` to mark that we're preparing an offer. To avoid races, we'll use this value later instead of the signaling state to determine whether or not an offer is being processed because the value of {{domxref("RTCPeerConnection.signalingState", "signalingState")}} changes asynchronously, introducing a glare opportunity. - -Once the offer has been created, set and sent (or an error occurs), `makingOffer` gets set back to `false`. +We set a Boolean variable, `makingOffer` to `true` to mark that we're preparing an offer. We set `makingOffer` immediately before calling `setLocalDescription()` in order to lock against interfering with sending this offer, and we don't clear it back to `false` until the offer has been sent to the signaling server (or an error has occurred, preventing the offer from being made). To avoid races, we'll use this value later instead of the signaling state to determine whether or not an offer is being processed because the value of {{domxref("RTCPeerConnection.signalingState", "signalingState")}} changes asynchronously, introducing a potential collision of an outgoing and an incoming call ("glare"). -#### Handling incoming ICE candidates +### Handling incoming ICE candidates Next, we need to handle the `RTCPeerConnection` event {{domxref("RTCPeerConnection.icecandidate_event", "icecandidate")}}, which is how the local ICE layer passes candidates to us for delivery to the remote peer over the signaling channel. @@ -136,26 +132,29 @@ pc.onicecandidate = ({ candidate }) => signaler.send({ candidate }); This takes the `candidate` member of this ICE event and passes it through to the signaling channel's `send()` method to be sent over the signaling server to the remote peer. -#### Handling incoming messages on the signaling channel +### Handling incoming messages on the signaling channel The last piece of the puzzle is code to handle incoming messages from the signaling server. That's implemented here as an `onmessage` event handler on the signaling channel object. This method is invoked each time a message arrives from the signaling server. ```js let ignoreOffer = false; +let isSettingRemoteAnswerPending = false; signaler.onmessage = async ({ data: { description, candidate } }) => { try { if (description) { - const offerCollision = - description.type === "offer" && - (makingOffer || pc.signalingState !== "stable"); + const readyForOffer = + !makingOffer && + (pc.signalingState === "stable" || isSettingRemoteAnswerPending); + const offerCollision = description.type === "offer" && !readyForOffer; ignoreOffer = !polite && offerCollision; if (ignoreOffer) { return; } - + isSettingRemoteAnswerPending = description.type === "answer"; await pc.setRemoteDescription(description); + isSettingRemoteAnswerPending = false; if (description.type === "offer") { await pc.setLocalDescription(); signaler.send({ description: pc.localDescription }); @@ -179,7 +178,7 @@ Upon receiving an incoming message from the `SignalingChannel` through its `onme If, on the other hand, the message has a `candidate`, it's an ICE candidate received from the remote peer as part of [trickle ICE](/en-US/docs/Web/API/RTCPeerConnection/canTrickleIceCandidates). The candidate is destined to be delivered to the local ICE layer by passing it into {{domxref("RTCPeerConnection.addIceCandidate", "addIceCandidate()")}}. -##### On receiving a description +#### On receiving a description If we received a `description`, we prepare to respond to the incoming offer or answer. First, we check to make sure we're in a state in which we can accept an offer. If the connection's signaling state isn't `stable` or if our end of the connection has started the process of making its own offer, then we need to look out for offer collision. @@ -191,227 +190,10 @@ Having ensured that we want to accept the offer, we set the remote description t If the newly-set remote description is an offer, we ask WebRTC to select an appropriate local configuration by calling the {{domxref("RTCPeerConnection")}} method {{domxref("RTCPeerConnection.setLocalDescription", "setLocalDescription()")}} without parameters. This causes `setLocalDescription()` to automatically generate an appropriate answer in response to the received offer. Then we send the answer through the signaling channel back to the first peer. -##### On receiving an ICE candidate +#### On receiving an ICE candidate On the other hand, if the received message contains an ICE candidate, we deliver it to the local {{Glossary("ICE")}} layer by calling the {{domxref("RTCPeerConnection")}} method {{domxref("RTCPeerConnection.addIceCandidate", "addIceCandidate()")}}. If an error occurs and we've ignored the most recent offer, we also ignore any error that may occur when trying to add the candidate. -## Making negotiation perfect - -If you're curious what makes perfect negotiation _so perfect_, this section is for you. Here, we'll look at each change made to the WebRTC API and to best practice recommendations to make perfect negotiation possible. - -### Glare-free setLocalDescription() - -In the past, the {{domxref("RTCPeerConnection.negotiationneeded_event", "negotiationneeded")}} event was easily handled in a way that was susceptible to glare—that is, it was prone to collisions, where both peers could wind up attempting to make an offer at the same time, leading to one or the other peers getting an error and aborting the connection attempt. - -#### The old way - -Consider this {{domxref("RTCPeerConnection.negotiationneeded_event", "onnegotiationneeded")}} event handler: - -```js example-bad -pc.onnegotiationneeded = async () => { - try { - await pc.setLocalDescription(await pc.createOffer()); - signaler.send({ description: pc.localDescription }); - } catch (err) { - console.error(err); - } -}; -``` - -Because the {{domxref("RTCPeerConnection.createOffer", "createOffer()")}} method is asynchronous and takes some time to complete, there's time in which the remote peer might attempt to send an offer of its own, causing us to leave the `stable` state and enter the `have-remote-offer` state, which means we are now waiting for a response to the offer. But once it receives the offer we just sent, so is the remote peer. This leaves both peers in a state in which the connection attempt cannot be completed. - -#### Perfect negotiation with the updated API - -As shown in the section [Implementing perfect negotiation](#implementing_perfect_negotiation), we can eliminate this problem by introducing a variable (here called `makingOffer`) which we use to indicate that we are in the process of sending an offer, and making use of the updated `setLocalDescription()` method: - -```js example-good -let makingOffer = false; - -pc.onnegotiationneeded = async () => { - try { - makingOffer = true; - await pc.setLocalDescription(); - signaler.send({ description: pc.localDescription }); - } catch (err) { - console.error(err); - } finally { - makingOffer = false; - } -}; -``` - -We set `makingOffer` immediately before calling `setLocalDescription()` in order to lock against interfering with sending this offer, and we don't clear it back to `false` until the offer has been sent to the signaling server (or an error has occurred, preventing the offer from being made). This way, we avoid the risk of offers colliding. - -### Automatic rollback in setRemoteDescription() - -A key component to perfect negotiation is the concept of the polite peer, which always rolls itself back if it receives an offer while itself waiting for an answer to an offer. Previously, triggering rollback involved manually checking for rollback conditions and triggering the rollback manually, by setting the local description to one with the type `rollback`, like this: - -```js -await pc.setLocalDescription({ type: "rollback" }); -``` - -Doing so returns the local peer to the `stable` {{domxref("RTCPeerConnection.signalingState", "signalingState")}} from whichever state it had previously been in. Since a peer can only accept offers when in the `stable` state, the peer has thus rescinded its offer and is ready to receive the offer from the remote (impolite) peer. As we'll see in a moment, there are problems with this approach, however. - -#### Perfect negotiation with the old API - -Using the previous API to implement incoming negotiation messages during perfect negotiation would look something like this: - -```js example-bad -signaler.onmessage = async ({ data: { description, candidate } }) => { - try { - if (description) { - if (description.type === "offer" && pc.signalingState !== "stable") { - if (!polite) { - return; - } - - await Promise.all([ - pc.setLocalDescription({ type: "rollback" }), - pc.setRemoteDescription(description), - ]); - } else { - await pc.setRemoteDescription(description); - } - - if (description.type === "offer") { - await pc.setLocalDescription(await pc.createAnswer()); - signaler.send({ description: pc.localDescription }); - } - } else if (candidate) { - try { - await pc.addIceCandidate(candidate); - } catch (err) { - if (!ignoreOffer) { - throw err; - } - } - } - } catch (err) { - console.error(err); - } -}; -``` - -Since rollback works by postponing changes until the next negotiation (which will begin immediately after the current one is finished), the polite peer needs to know when it needs to throw away a received offer if it's currently waiting for a reply to an offer it's already sent. - -The code checks to see if the message is an offer, and if so, if the local signaling state isn't `stable`. If it's not stable, _and_ the local peer is the polite one, we need to trigger rollback so we can replace the outgoing offer with the new incoming one. And these must both be completed before we can proceed with handling the received offer. - -Since there isn't a single "roll back and use this offer instead", performing this change on the polite peer requires two steps, executed in the context of [`Promise.all()`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise/all), which is used to ensure that both statements execute completely before continuing to handle the received offer. The first statement triggers rollback and the second sets the remote description to the received one, thus completing the process of replacing the previously _sent_ offer with the newly _received_ offer. The polite peer has now become the callee instead of the caller. - -All other descriptions received from the impolite peer are processed as normal, by passing them into {{domxref("RTCPeerConnection.setRemoteDescription", "setRemoteDescription()")}}. - -Finally, we process a received offer by calling `setLocalDescription()` to set our local description to the one returned by {{domxref("RTCPeerConnection.createAnswer", "createAnswer()")}}. Then that gets sent to the polite peer using the signaling channel. - -If the incoming message is an ICE candidate rather than an SDP description, it's delivered to the ICE layer by passing it into the {{domxref("RTCPeerConnection")}} method {{domxref("RTCPeerConnection.addIceCandidate", "addIceCandidate()")}}. If an error occurs here and we didn't just discard an offer due to being the impolite peer during a collision, we [`throw`](/en-US/docs/Web/JavaScript/Reference/Statements/throw) the error so the caller can handle it. Otherwise, we drop the error, ignoring it, since it doesn't matter in this context. - -#### Perfect negotiation with the updated API - -The updated code takes advantage of the fact that you can now call {{domxref("RTCPeerConnection.setLocalDescription", "setLocalDescription()")}} with no parameters so it just does the right thing for you, as well as the fact that `setRemoteDescription()` automatically rolls back if necessary. This lets us get rid of the need to use a [`Promise`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise) to keep the timing in order, since the rollback becomes an essentially atomic part of the `setRemoteDescription()` call. - -```js example-good -let ignoreOffer = false; - -signaler.onmessage = async ({ data: { description, candidate } }) => { - try { - if (description) { - const offerCollision = - description.type === "offer" && - (makingOffer || pc.signalingState !== "stable"); - - ignoreOffer = !polite && offerCollision; - if (ignoreOffer) { - return; - } - - await pc.setRemoteDescription(description); - if (description.type === "offer") { - await pc.setLocalDescription(); - signaler.send({ description: pc.localDescription }); - } - } else if (candidate) { - try { - await pc.addIceCandidate(candidate); - } catch (err) { - if (!ignoreOffer) { - throw err; - } - } - } - } catch (err) { - console.error(err); - } -}; -``` - -While the difference in code size is minor, and the complexity isn't reduced much either, the code is much, much more reliable. Let's take a dive into the code to see how it works now. - -##### On receiving a description - -In the revised code, if the received message is an SDP `description`, we check to see if it arrived while we're attempting to transmit an offer. If the received message is an `offer` _and_ the local peer is the impolite peer, _and_ a collision is occurring, we ignore the offer because we want to continue to try to use the offer that's already in the process of being sent. That's the impolite peer in action. - -In any other case, we'll try instead to handle the incoming message. This begins by setting the remote description to the received `description` by passing it into {{domxref("RTCPeerConnection.setRemoteDescription", "setRemoteDescription()")}}. This works regardless of whether we're handling an offer or an answer since rollback will be performed automatically as needed. - -At that point, if the received message is an `offer`, we use `setLocalDescription()` to create and set an appropriate local description, then we send it to the remote peer over the signaling server. - -##### On receiving an ICE candidate - -On the other hand, if the received message is an ICE candidate—indicated by the JSON object containing a `candidate` member—we deliver it to the local ICE layer by calling the {{domxref("RTCPeerConnection")}} method {{domxref("RTCPeerConnection.addIceCandidate", "addIceCandidate()")}}. Errors are, as before, ignored if we have just discarded an offer. - -### Explicit restartIce() method added - -The techniques previously used to trigger an [ICE restart](/en-US/docs/Web/API/WebRTC_API/Session_lifetime#ice_restart) while handling the event {{domxref("RTCPeerConnection.negotiationneeded_event", "negotiationneeded")}} have significant flaws. These flaws have made it difficult to safely and reliably trigger a restart during negotiation. The perfect negotiation improvements have fixed this by adding a new {{domxref("RTCPeerConnection.restartIce", "restartIce()")}} method to `RTCPeerConnection`. - -#### The old way - -In the past, if you encountered an ICE error and needed to restart negotiation, you might have done something like this: - -```js example-bad -pc.onnegotiationneeded = async (options) => { - await pc.setLocalDescription(await pc.createOffer(options)); - signaler.send({ description: pc.localDescription }); -}; -pc.oniceconnectionstatechange = () => { - if (pc.iceConnectionState === "failed") { - pc.onnegotiationneeded({ iceRestart: true }); - } -}; -``` - -This has a number of reliability issues and outright bugs (such as failing if the {{domxref("RTCPeerConnection.iceconnectionstatechange_event", "iceconnectionstatechange")}} event fires when the signaling state isn't `stable`), but there was no way you could actually request an ICE restart other than by creating and sending an offer with the `iceRestart` option set to `true`. Sending the restart request thus required directly invoking the `negotiationneeded` event's handler. Getting it right was tricky at best, and was so easy to get wrong that bugs are common. - -#### Using restartIce() - -Now, you can use `restartIce()` to do this much more cleanly: - -```js example-good -let makingOffer = false; - -pc.onnegotiationneeded = async () => { - try { - makingOffer = true; - await pc.setLocalDescription(); - signaler.send({ description: pc.localDescription }); - } catch (err) { - console.error(err); - } finally { - makingOffer = false; - } -}; -pc.oniceconnectionstatechange = () => { - if (pc.iceConnectionState === "failed") { - pc.restartIce(); - } -}; -``` - -With this improved technique, instead of directly calling `onnegotiationneeded` with options to trigger ICE restart, the `failed` [ICE connection state](/en-US/docs/Web/API/RTCPeerConnection/iceConnectionState) calls {{domxref("RTCPeerConnection.restartIce", "restartIce()")}}. `restartIce()` tells the ICE layer to automatically add the `iceRestart` flag to the next ICE message sent. Problem solved! - -### Rollback no longer supported in the pranswer state - -The last of the API changes that stand out is that you can no longer roll back when in either of the `have-remote-pranswer` or the `have-local-pranswer` states. Fortunately, when using perfect negotiation there's no need to do this anyway, since the situations that cause this are caught and prevented before rolling these back ever becomes necessary. - -Thus, attempting to trigger rollback while in one of the two `pranswer` states will now throw an `InvalidStateError`. - ## See also - [WebRTC API](/en-US/docs/Web/API/WebRTC_API) diff --git a/files/en-us/web/api/webrtc_api/protocols/index.md b/files/en-us/web/api/webrtc_api/protocols/index.md index ca5f65abb33cb9a..259e79ac8640f2e 100644 --- a/files/en-us/web/api/webrtc_api/protocols/index.md +++ b/files/en-us/web/api/webrtc_api/protocols/index.md @@ -79,10 +79,10 @@ In addition, because it is a part of the RTP header rather than the payload, it ### Scalable video coding -[Scalable Video Coding (SVC)](https://www.w3.org/TR/webrtc-svc/) encodes a video source in a single stream, with multiple layers that can be selectively decoded to obtain video with particular resolutions, bitrate, or quality. +[Scalable Video Coding (SVC)](https://w3c.github.io/webrtc-svc/) encodes a video source in a single stream, with multiple layers that can be selectively decoded to obtain video with particular resolutions, bitrate, or quality. An SFM can forward a subset of the layers in order to send a stream that is appropriate for each recipient's network and device. -Note that the dependencies are much more complicated than needed to for selecting streams to forward when using simulcast (see the [dependency diagrams](https://www.w3.org/TR/webrtc-svc/#dependencydiagrams*) in the SVC specification for a "flavor" of the complexity). +Note that the dependencies are much more complicated than needed to for selecting streams to forward when using simulcast (see the [dependency diagrams](https://w3c.github.io/webrtc-svc/#dependencydiagrams*) in the SVC specification for a "flavor" of the complexity). The SVC stream consists of a base layer that provides a minimum level of quality, and may include a number of enhancement layers that allow varying frame rates ("temporal scalability"), increased resolution ("spatial scalability"), and the same resolution at different bitrates. The VP8 codec only supports temporal layers, while VP9 supports both temporal and spatial layers. diff --git a/files/en-us/web/api/webrtc_api/session_lifetime/index.md b/files/en-us/web/api/webrtc_api/session_lifetime/index.md index 6e4c0e2f4135a5c..865790c69426f88 100644 --- a/files/en-us/web/api/webrtc_api/session_lifetime/index.md +++ b/files/en-us/web/api/webrtc_api/session_lifetime/index.md @@ -66,12 +66,19 @@ Sometimes, during the lifetime of a WebRTC session, network conditions change. O > [!NOTE] > Different browsers support ICE restart under different sets of conditions. Not all browsers will perform ICE restart due to network congestion, for example. -If you need to change the configuration of the connection in some way (such as changing to a different set of ICE servers), you can do so before restarting ICE by calling {{domxref("RTCPeerConnection.setConfiguration()")}} with an updated configuration object before restarting ICE. +The handling of the `failed` [ICE connection state](/en-US/docs/Web/API/RTCPeerConnection/iceConnectionState) below shows how you might restart the connection. -To explicitly trigger ICE restart, start the renegotiation process by calling {{domxref("RTCPeerConnection.createOffer()")}}, specifying the `iceRestart` option with a value of `true`. Then handle the connection process from then on just like you normally would. This generates new values for the ICE username fragment (ufrag) and password, which will be used by the renegotiation process and the resulting connection. +```js +pc.oniceconnectionstatechange = () => { + if (pc.iceConnectionState === "failed") { + pc.setConfiguration(restartConfig); + pc.restartIce(); + } +}; +``` -The answerer side of the connection will automatically begin ICE restart when new values are detected for the ICE ufrag and ICE password. +The code first calls {{domxref("RTCPeerConnection.setConfiguration()")}} with an updated configuration object. This should be done before restarting ICE if you need to change the connection configuration in some way (such as changing to a different set of ICE servers). -## Transmission +The handler then calls {{domxref("RTCPeerConnection.restartIce()")}}. This tells the ICE layer to automatically add the `iceRestart` flag to the next `createOffer()` call, which triggers an ICE restart. It also creates new values for the ICE username fragment (ufrag) and password, which will be used by the renegotiation process and the resulting connection. -## Reception +The answerer side of the connection will automatically begin ICE restart when new values are detected for the ICE ufrag and ICE password. diff --git a/files/en-us/web/api/webrtc_api/simple_rtcdatachannel_sample/index.md b/files/en-us/web/api/webrtc_api/simple_rtcdatachannel_sample/index.md index 2e0da345a6c398c..53dcc5e4fb3d796 100644 --- a/files/en-us/web/api/webrtc_api/simple_rtcdatachannel_sample/index.md +++ b/files/en-us/web/api/webrtc_api/simple_rtcdatachannel_sample/index.md @@ -274,7 +274,7 @@ function sendMessage() { } ``` -First, the text of the message is fetched from the input box's [`value`](/en-US/docs/Web/HTML/Element/input#value) attribute. This is then sent to the remote peer by calling {{domxref("RTCDataChannel.send", "sendChannel.send()")}}. That's all there is to it! The rest of this method is just some user experience sugar — the input box is emptied and re-focused so the user can immediately begin typing another message. +First, the text of the message is fetched from the input box's [`value`](/en-US/docs/Web/HTML/Reference/Elements/input#value) attribute. This is then sent to the remote peer by calling {{domxref("RTCDataChannel.send", "sendChannel.send()")}}. That's all there is to it! The rest of this method is just some user experience sugar — the input box is emptied and re-focused so the user can immediately begin typing another message. ### Receiving messages diff --git a/files/en-us/web/api/webrtc_api/using_data_channels/index.md b/files/en-us/web/api/webrtc_api/using_data_channels/index.md index bf72cc8b0f712b9..ee06645ebf3566d 100644 --- a/files/en-us/web/api/webrtc_api/using_data_channels/index.md +++ b/files/en-us/web/api/webrtc_api/using_data_channels/index.md @@ -78,12 +78,12 @@ This eventually became a problem. Over time, various applications (including tho This will become an issue when browsers properly support the current standard for supporting larger messages—the end-of-record (EOR) flag that indicates when a message is the last one in a series that should be treated as a single payload. This is implemented in Firefox 57, but is not yet implemented in Chrome (see [Chromium Bug 7774](https://crbug.com/webrtc/7774)). With EOR support in place, `RTCDataChannel` payloads can be much larger (officially up to 256 KiB, but Firefox's implementation caps them at a whopping 1 GiB). Even at 256 KiB, that's large enough to cause noticeable delays in handling urgent traffic. If you go even larger, the delays can become untenable unless you are certain of your operational conditions. -In order to resolve this issue, a new system of **stream schedulers** (usually referred to as the "SCTP ndata specification") has been designed to make it possible to interleave messages sent on different streams, including streams used to implement WebRTC data channels. This [proposal](https://datatracker.ietf.org/doc/html/draft-ietf-tsvwg-sctp-ndata) is still in IETF draft form, but once implemented, it will make it possible to send messages with essentially no size limitations, since the SCTP layer will automatically interleave the underlying sub-messages to ensure that every channel's data has the opportunity to get through. +In order to resolve this issue, a new system of **stream schedulers** has been designed to make it possible to interleave messages sent on different streams, including streams used to implement WebRTC data channels. This [proposal](https://datatracker.ietf.org/doc/html/draft-ietf-tsvwg-sctp-ndata) is still in IETF draft form, but once implemented, it will make it possible to send messages with essentially no size limitations, since the SCTP layer will automatically interleave the underlying sub-messages to ensure that every channel's data has the opportunity to get through. -Firefox support for ndata is in the process of being implemented; see [Firefox bug 1381145](https://bugzil.la/1381145) to track it becoming available for general use. The Chrome team is tracking their implementation of ndata support in [Chrome Bug 5696](https://crbug.com/webrtc/5696). +Firefox support for stream schedulers is in the process of being implemented; see [Firefox bug 1381145](https://bugzil.la/1381145) to track it becoming available for general use. The Chrome team is tracking their implementation of stream schedulers support in [Chrome Bug 5696](https://crbug.com/webrtc/5696). > [!NOTE] -> Much of the information in this section is based in part on the blog post [Demystifying WebRTC's Data Channel Message Size Limitations](https://lgrahl.de/articles/demystifying-webrtc-dc-size-limit.html), written by Lennart Grahl. He goes into a bit more detail there, but as browsers have been updated since then some of it may be out-of-date. In addition, as time goes by, it will become more so, especially once EOR and ndata support are fully integrated in the major browsers. +> Much of the information in this section is based in part on the blog post [Demystifying WebRTC's Data Channel Message Size Limitations](https://lgrahl.de/articles/demystifying-webrtc-dc-size-limit.html), written by Lennart Grahl. He goes into a bit more detail there, but as browsers have been updated since then some of it may be out-of-date. In addition, as time goes by, it will become more so, especially once EOR and stream schedulers support are fully integrated in the major browsers. ## Security diff --git a/files/en-us/web/api/webrtc_api/using_dtmf/index.md b/files/en-us/web/api/webrtc_api/using_dtmf/index.md index 5abd44439f96d8e..9b696968d80ebc2 100644 --- a/files/en-us/web/api/webrtc_api/using_dtmf/index.md +++ b/files/en-us/web/api/webrtc_api/using_dtmf/index.md @@ -79,11 +79,6 @@ let mediaConstraints = { video: false, }; -let offerOptions = { - offerToReceiveAudio: 1, - offerToReceiveVideo: 0, -}; - let dialButton = null; let logElement = null; ``` @@ -100,8 +95,6 @@ These are, in order: - : Because some browsers have not yet implemented {{domxref("RTCPeerConnection.addTrack()")}}, therefore requiring the use of the obsolete {{domxref("RTCPeerConnection.addStream", "addStream()")}} method, we use this Boolean to determine whether or not the user agent supports `addTrack()`; if it doesn't, we'll fall back to `addStream()`. This gets figured out in `connectAndDial()`, as shown in [Starting the connection process](#starting_the_connection_process). - `mediaConstraints` - : An object specifying the constraints to use when starting the connection. We want an audio-only connection, so `video` is `false`, while `audio` is `true`. -- `offerOptions` - - : An object providing options to specify when calling {{domxref("RTCPeerConnection.createOffer()")}}. In this case, we state that we want to receive audio but not video. - `dialButton` and `logElement` - : These variables will be used to store references to the dial button and the {{HTMLElement("div")}} into which logging information will be written. They'll get set up when the page is first loaded. See [Initialization](#initialization) below. @@ -288,36 +281,33 @@ Our call to `insertDTMF()` specifies not only the DTMF to send (`dialString`), b #### Negotiating the connection -When the calling {{domxref("RTCPeerConnection")}} begins to receive media (after the microphone's stream is added to it), a {{domxref("RTCPeerConnection.negotiationneeded_event", "negotiationneeded")}} event is delivered to the caller, letting it know that it's time to start negotiating the connection with the receiver. As previously mentioned, our example is simplified somewhat because we control both the caller and the receiver, so `handleCallerNegotiationNeeded()` is able to quickly construct the connection by chaining the required calls together for both the caller and receiver, as shown below. +When the calling {{domxref("RTCPeerConnection")}} begins to receive media (after the microphone's stream is added to it), a {{domxref("RTCPeerConnection.negotiationneeded_event", "negotiationneeded")}} event is delivered to the caller, letting it know that it's time to start negotiating the connection with the receiver. As previously mentioned, our example is simplified somewhat because we control both the caller and the receiver, so `handleCallerNegotiationNeeded()` is able to quickly construct the connection by calling methods for both the caller and receiver, as shown below. ```js -function handleCallerNegotiationNeeded() { +// Offer to receive audio but not video +const constraints = { audio: true, video: false }; + +async function handleCallerNegotiationNeeded() { log("Negotiating…"); - callerPC - .createOffer(offerOptions) - .then((offer) => { - log(`Setting caller's local description: ${offer.sdp}`); - return callerPC.setLocalDescription(offer); - }) - .then(() => { - log( - "Setting receiver's remote description to the same as caller's local", - ); - return receiverPC.setRemoteDescription(callerPC.localDescription); - }) - .then(() => { - log("Creating answer"); - return receiverPC.createAnswer(); - }) - .then((answer) => { - log(`Setting receiver's local description to ${answer.sdp}`); - return receiverPC.setLocalDescription(answer); - }) - .then(() => { - log("Setting caller's remote description to match"); - return callerPC.setRemoteDescription(receiverPC.localDescription); - }) - .catch((err) => log(`Error during negotiation: ${err.message}`)); + try { + const stream = await navigator.mediaDevices.getUserMedia(constraints); + for (const track of stream.getTracks()) { + pc.addTrack(track, stream); + } + const offer = await callerPC.createOffer(); + log(`Setting caller's local description: ${offer.sdp}`); + await callerPC.setLocalDescription(offer); + log("Setting receiver's remote description to the same as caller's local"); + await receiverPC.setRemoteDescription(callerPC.localDescription); + log("Creating answer"); + const answer = await receiverPC.createAnswer(); + log(`Setting receiver's local description to ${answer.sdp}`); + await receiverPC.setLocalDescription(answer); + log("Setting caller's remote description to match"); + await callerPC.setRemoteDescription(receiverPC.localDescription); + } catch (err) { + log(`Error during negotiation: ${err.message}`); + } } ``` diff --git a/files/en-us/web/api/webrtc_api/using_encoded_transforms/index.md b/files/en-us/web/api/webrtc_api/using_encoded_transforms/index.md index 85f44bef139f7d0..a8686081da29f1a 100644 --- a/files/en-us/web/api/webrtc_api/using_encoded_transforms/index.md +++ b/files/en-us/web/api/webrtc_api/using_encoded_transforms/index.md @@ -161,9 +161,9 @@ The value of the `name` property is used to determine which `TransformStream` to // Code to instantiate transform and attach them to sender/receiver pipelines. onrtctransform = (event) => { let transform; - if (event.transformer.options.name == "senderTransform") + if (event.transformer.options.name === "senderTransform") transform = createSenderTransform(); // returns a TransformStream - else if (event.transformer.options.name == "receiverTransform") + else if (event.transformer.options.name === "receiverTransform") transform = createReceiverTransform(); // returns a TransformStream else return; event.transformer.readable diff --git a/files/en-us/web/api/websocket/close_event/index.md b/files/en-us/web/api/websocket/close_event/index.md index 63b49a6a5f7aba7..65889f235618537 100644 --- a/files/en-us/web/api/websocket/close_event/index.md +++ b/files/en-us/web/api/websocket/close_event/index.md @@ -14,10 +14,10 @@ The `close` event is fired when a connection with a `WebSocket` is closed. Use the event name in methods like {{domxref("EventTarget.addEventListener", "addEventListener()")}}, or set an event handler property. -```js -addEventListener("close", (event) => {}); +```js-nolint +addEventListener("close", (event) => { }) -onclose = (event) => {}; +onclose = (event) => { } ``` ## Event type diff --git a/files/en-us/web/api/websocket/error_event/index.md b/files/en-us/web/api/websocket/error_event/index.md index 032aeb7d1e002bc..57fb29c69b7167f 100644 --- a/files/en-us/web/api/websocket/error_event/index.md +++ b/files/en-us/web/api/websocket/error_event/index.md @@ -14,10 +14,10 @@ The `error` event is fired when a connection with a `WebSocket` has been closed Use the event name in methods like {{domxref("EventTarget.addEventListener", "addEventListener()")}}, or set an event handler property. -```js -addEventListener("error", (event) => {}); +```js-nolint +addEventListener("error", (event) => { }) -onerror = (event) => {}; +onerror = (event) => { } ``` ## Event type diff --git a/files/en-us/web/api/websocket/message_event/index.md b/files/en-us/web/api/websocket/message_event/index.md index e82192854e4f2b1..8b477572d01f457 100644 --- a/files/en-us/web/api/websocket/message_event/index.md +++ b/files/en-us/web/api/websocket/message_event/index.md @@ -14,10 +14,10 @@ The `message` event is fired when data is received through a `WebSocket`. Use the event name in methods like {{domxref("EventTarget.addEventListener", "addEventListener()")}}, or set an event handler property. -```js -addEventListener("message", (event) => {}); +```js-nolint +addEventListener("message", (event) => { }) -onmessage = (event) => {}; +onmessage = (event) => { } ``` ## Event type diff --git a/files/en-us/web/api/websocket/open_event/index.md b/files/en-us/web/api/websocket/open_event/index.md index 4daaf338f284005..a0bc6cc4180e539 100644 --- a/files/en-us/web/api/websocket/open_event/index.md +++ b/files/en-us/web/api/websocket/open_event/index.md @@ -14,10 +14,10 @@ The `open` event is fired when a connection with a `WebSocket` is opened. Use the event name in methods like {{domxref("EventTarget.addEventListener", "addEventListener()")}}, or set an event handler property. -```js -addEventListener("open", (event) => {}); +```js-nolint +addEventListener("open", (event) => { }) -onopen = (event) => {}; +onopen = (event) => { } ``` ## Event type diff --git a/files/en-us/web/api/websocket/websocket/index.md b/files/en-us/web/api/websocket/websocket/index.md index 5b47da8d0ce65bd..d3b87b583a7d616 100644 --- a/files/en-us/web/api/websocket/websocket/index.md +++ b/files/en-us/web/api/websocket/websocket/index.md @@ -28,7 +28,7 @@ new WebSocket(url, protocols) - `protocols` {{optional_inline}} - : A single string or an array of strings representing the [sub-protocol(s)](/en-US/docs/Web/API/WebSockets_API/Writing_WebSocket_servers#subprotocols) that the client would like to use, in order of preference. - If it is omitted, an empty array is used by default, i.e. `[]`. + If it is omitted, an empty array is used by default, i.e., `[]`. A single server can implement multiple WebSocket sub-protocols, and handle different types of interactions depending on the specified value. Note however that only one sub-protocol can be selected per connection. @@ -49,7 +49,7 @@ new WebSocket(url, protocols) - parsing of [`url`](#url) fails - [`url`](#url) has a scheme other than `ws`, `wss`, `http`, or `https` - [`url`](#url) has a [fragment](/en-US/docs/Web/URI/Reference/Fragment) - - any of the values in [`protocols`](#protocols) occur more than once, or otherwise fail to match the requirements for elements that comprise the value of [`Sec-WebSocket-Protocol`](/en-US/docs/Web/HTTP/Protocol_upgrade_mechanism#sec-websocket-protocol) fields as defined by the WebSocket Protocol specification + - any of the values in [`protocols`](#protocols) occur more than once, or otherwise fail to match the requirements for elements that comprise the value of [`Sec-WebSocket-Protocol`](/en-US/docs/Web/HTTP/Guides/Protocol_upgrade_mechanism#sec-websocket-protocol) fields as defined by the WebSocket Protocol specification ## Examples @@ -58,9 +58,11 @@ The examples below show how you might connect to a `WebSocket`. The code below shows how we can connect to a socket using an URL with the `wss` schema: ```js -const wssWebSocket = new WebSocket('wss://websocket.example.org'); +const wssWebSocket = new WebSocket("wss://websocket.example.org"); console.log(wssWebSocket.url); // 'wss://websocket.example.org' -... // Do something with socket + +// Do something with socket + wssWebSocket.close(); ``` @@ -68,9 +70,11 @@ The code for connecting to an HTTPS URL is nearly the same. Under the hood the browser resolves this to a "WSS" connection, so the {{domxref("WebSocket.url")}} will have the schema "wss:". ```js -const httpsWebSocket = new WebSocket('https://websocket.example.org'); +const httpsWebSocket = new WebSocket("https://websocket.example.org"); console.log(httpsWebSocket.url); // 'wss://websocket.example.org' -... // Do something with socket + +// Do something with socket + httpsWebSocket.close(); ``` @@ -78,8 +82,10 @@ We can also resolve relative URLs. The absolute URL will depend on the base URL of the context in which it is called. ```js -relativeWebSocket = new WebSocket('/local/url'); -... // Do something with socket +relativeWebSocket = new WebSocket("/local/url"); + +// Do something with socket + relativeWebSocket.close(); ``` diff --git a/files/en-us/web/api/websockets_api/using_websocketstream/index.md b/files/en-us/web/api/websockets_api/using_websocketstream/index.md index 230ffd0624ef501..034324468f5e63a 100644 --- a/files/en-us/web/api/websockets_api/using_websocketstream/index.md +++ b/files/en-us/web/api/websockets_api/using_websocketstream/index.md @@ -117,7 +117,7 @@ To demonstrate basic usage of `WebSocketStream`, we've created a sample client. > [!NOTE] > To get the example working, you'll also need a server component. We wrote our client to work along with the Deno server explained in [Writing a WebSocket server in JavaScript (Deno)](/en-US/docs/Web/API/WebSockets_API/Writing_a_WebSocket_server_in_JavaScript_Deno), but any compatible server will do. -The HTML for the demo is as follows. It includes informational [`<h2>`](/en-US/docs/Web/HTML/Element/Heading_Elements) and {{htmlelement("p")}} elements, a {{htmlelement("button")}} to close the WebSocket connection that is initially disabled, and a {{htmlelement("div")}} for us to write output messages into. +The HTML for the demo is as follows. It includes informational [`<h2>`](/en-US/docs/Web/HTML/Reference/Elements/Heading_Elements) and {{htmlelement("p")}} elements, a {{htmlelement("button")}} to close the WebSocket connection that is initially disabled, and a {{htmlelement("div")}} for us to write output messages into. ```html <h2>WebSocketStream Test</h2> diff --git a/files/en-us/web/api/websockets_api/writing_a_websocket_server_in_javascript_deno/index.md b/files/en-us/web/api/websockets_api/writing_a_websocket_server_in_javascript_deno/index.md index dc5aa70dc43dbfe..385143c5b8df790 100644 --- a/files/en-us/web/api/websockets_api/writing_a_websocket_server_in_javascript_deno/index.md +++ b/files/en-us/web/api/websockets_api/writing_a_websocket_server_in_javascript_deno/index.md @@ -25,34 +25,33 @@ Create a `main.js` file. This file will contain the code for a simple HTTP serve ```js Deno.serve({ port: 80, - handler: async (request) => { - // If the request is a websocket upgrade, - // we need to use the Deno.upgradeWebSocket helper - if (request.headers.get("upgrade") === "websocket") { - const { socket, response } = Deno.upgradeWebSocket(request); - - socket.onopen = () => { - console.log("CONNECTED"); - }; - socket.onmessage = (event) => { - console.log(`RECEIVED: ${event.data}`); - socket.send("pong"); - }; - socket.onclose = () => console.log("DISCONNECTED"); - socket.onerror = (error) => console.error("ERROR:", error); - - return response; - } else { + async handler(request) { + if (request.headers.get("upgrade") !== "websocket") { // If the request is a normal HTTP request, // we serve the client HTML file. const file = await Deno.open("./index.html", { read: true }); return new Response(file.readable); } + // If the request is a websocket upgrade, + // we need to use the Deno.upgradeWebSocket helper + const { socket, response } = Deno.upgradeWebSocket(request); + + socket.onopen = () => { + console.log("CONNECTED"); + }; + socket.onmessage = (event) => { + console.log(`RECEIVED: ${event.data}`); + socket.send("pong"); + }; + socket.onclose = () => console.log("DISCONNECTED"); + socket.onerror = (error) => console.error("ERROR:", error); + + return response; }, }); ``` -`Deno.upgradeWebSocket()` upgrades the connection to a WebSocket connection, which is explained further in [Protocol upgrade mechanism](/en-US/docs/Web/HTTP/Protocol_upgrade_mechanism). +`Deno.upgradeWebSocket()` upgrades the connection to a WebSocket connection, which is explained further in [Protocol upgrade mechanism](/en-US/docs/Web/HTTP/Guides/Protocol_upgrade_mechanism). [`Deno.serve()`](https://docs.deno.com/api/deno/~/Deno.serve) uses `Deno.listen()` and `Deno.serveHttp()` under the hood, and is a higher-level interface to easily set up a HTTP server. Without it, the code would look something like this. diff --git a/files/en-us/web/api/websockets_api/writing_websocket_client_applications/index.md b/files/en-us/web/api/websockets_api/writing_websocket_client_applications/index.md index 83d3cbd8c655ca7..eb54851425c0bcc 100644 --- a/files/en-us/web/api/websockets_api/writing_websocket_client_applications/index.md +++ b/files/en-us/web/api/websockets_api/writing_websocket_client_applications/index.md @@ -66,7 +66,7 @@ const exampleSocket = new WebSocket("wss://www.example.com/socketserver", [ Once the connection is established (that is, `readyState` is `OPEN`), {{domxref("WebSocket.protocol", "exampleSocket.protocol")}} will tell you which protocol the server selected. -Establishing a WebSocket relies on the [HTTP Upgrade mechanism](/en-US/docs/Web/HTTP/Protocol_upgrade_mechanism), so the request for the protocol upgrade is implicit when we address the web server as `ws://www.example.com` or `wss://www.example.com`. +Establishing a WebSocket relies on the [HTTP Upgrade mechanism](/en-US/docs/Web/HTTP/Guides/Protocol_upgrade_mechanism), so the request for the protocol upgrade is implicit when we address the web server as `ws://www.example.com` or `wss://www.example.com`. ## Sending data to the server diff --git a/files/en-us/web/api/websockets_api/writing_websocket_server/index.md b/files/en-us/web/api/websockets_api/writing_websocket_server/index.md index 5dfbe38f23bb567..b26ba0172c3cf47 100644 --- a/files/en-us/web/api/websockets_api/writing_websocket_server/index.md +++ b/files/en-us/web/api/websockets_api/writing_websocket_server/index.md @@ -94,7 +94,7 @@ Console.WriteLine("A client connected."); NetworkStream stream = client.GetStream(); -//enter to an infinite cycle to be able to handle every change in stream +// Enter to an infinite cycle to be able to handle every change in stream while (true) { while (!stream.DataAvailable); @@ -123,7 +123,7 @@ byte[] bytes = new byte[client.Available]; stream.Read(bytes, 0, bytes.Length); -//translate bytes of request to string +// Translate bytes of request to string String data = Encoding.UTF8.GetString(bytes); if (Regex.IsMatch(data, "^GET")) { @@ -282,29 +282,29 @@ class Server { mask = (bytes[1] & 0b10000000) != 0; // must be true, "All messages from the client to the server have this bit set" int opcode = bytes[0] & 0b00001111; // expecting 1 - text message ulong offset = 2, - msglen = bytes[1] & (ulong)0b01111111; + msgLen = bytes[1] & (ulong)0b01111111; - if (msglen == 126) { + if (msgLen == 126) { // bytes are reversed because websocket will print them in Big-Endian, whereas // BitConverter will want them arranged in little-endian on windows - msglen = BitConverter.ToUInt16(new byte[] { bytes[3], bytes[2] }, 0); + msgLen = BitConverter.ToUInt16(new byte[] { bytes[3], bytes[2] }, 0); offset = 4; - } else if (msglen == 127) { + } else if (msgLen == 127) { // To test the below code, we need to manually buffer larger messages — since the NIC's autobuffering // may be too latency-friendly for this code to run (that is, we may have only some of the bytes in this // websocket frame available through client.Available). - msglen = BitConverter.ToUInt64(new byte[] { bytes[9], bytes[8], bytes[7], bytes[6], bytes[5], bytes[4], bytes[3], bytes[2] },0); + msgLen = BitConverter.ToUInt64(new byte[] { bytes[9], bytes[8], bytes[7], bytes[6], bytes[5], bytes[4], bytes[3], bytes[2] },0); offset = 10; } - if (msglen == 0) { - Console.WriteLine("msglen == 0"); + if (msgLen == 0) { + Console.WriteLine("msgLen == 0"); } else if (mask) { - byte[] decoded = new byte[msglen]; + byte[] decoded = new byte[msgLen]; byte[] masks = new byte[4] { bytes[offset], bytes[offset + 1], bytes[offset + 2], bytes[offset + 3] }; offset += 4; - for (ulong i = 0; i < msglen; ++i) + for (ulong i = 0; i < msgLen; ++i) decoded[i] = (byte)(bytes[offset + i] ^ masks[i % 4]); string text = Encoding.UTF8.GetString(decoded); diff --git a/files/en-us/web/api/websockets_api/writing_websocket_servers/index.md b/files/en-us/web/api/websockets_api/writing_websocket_servers/index.md index cb351011d1a1f1e..7202dc311bbc37b 100644 --- a/files/en-us/web/api/websockets_api/writing_websocket_servers/index.md +++ b/files/en-us/web/api/websockets_api/writing_websocket_servers/index.md @@ -45,13 +45,13 @@ Sec-WebSocket-Version: 13 The client can solicit extensions and/or subprotocols here; see [Miscellaneous](#miscellaneous) for details. Also, common headers like {{HTTPHeader("User-Agent")}}, {{HTTPHeader("Referer")}}, {{HTTPHeader("Cookie")}}, or authentication headers might be there as well. Do whatever you want with those; they don't directly pertain to the WebSocket. It's also safe to ignore them. In many common setups, a reverse proxy has already dealt with them. > [!NOTE] -> All **browsers** send an [`Origin` header](/en-US/docs/Web/HTTP/CORS#origin). You can use this header for security (checking for same origin, automatically allowing or denying, etc.) and send a [403 Forbidden](/en-US/docs/Web/HTTP/Status/403) if you don't like what you see. This is effective against [Cross Site WebSocket Hijacking (CSWH)](https://cwe.mitre.org/data/definitions/1385.html). However, be warned that non-browser agents can send a faked `Origin`. Most applications reject requests without this header. +> All **browsers** send an [`Origin` header](/en-US/docs/Web/HTTP/Guides/CORS#origin). You can use this header for security (checking for same origin, automatically allowing or denying, etc.) and send a [403 Forbidden](/en-US/docs/Web/HTTP/Reference/Status/403) if you don't like what you see. This is effective against [Cross Site WebSocket Hijacking (CSWH)](https://cwe.mitre.org/data/definitions/1385.html). However, be warned that non-browser agents can send a faked `Origin`. Most applications reject requests without this header. If any header is not understood or has an incorrect value, the server should send a {{HTTPStatus("400")}} ("Bad Request") response and immediately close the socket. As usual, it may also give the reason why the handshake failed in the HTTP response body, but the message may never be displayed (browsers do not display it). If the server doesn't understand that version of WebSockets, it should send a {{HTTPHeader("Sec-WebSocket-Version")}} header back that contains the version(s) it does understand. In the example above, it indicates version 13 of the WebSocket protocol. The most interesting header here is {{HTTPHeader("Sec-WebSocket-Key")}}. Let's look at that next. -> **Note:** [Regular HTTP status codes](/en-US/docs/Web/HTTP/Status) can be used only before the handshake. After the handshake succeeds, you have to use a different set of codes (defined in section 7.4 of the spec). +> **Note:** [Regular HTTP status codes](/en-US/docs/Web/HTTP/Reference/Status) can be used only before the handshake. After the handshake succeeds, you have to use a different set of codes (defined in section 7.4 of the spec). ### Server handshake response diff --git a/files/en-us/web/api/websocketstream/opened/index.md b/files/en-us/web/api/websocketstream/opened/index.md index 0ec2bf184c9cb86..bce53ae9786abef 100644 --- a/files/en-us/web/api/websocketstream/opened/index.md +++ b/files/en-us/web/api/websocketstream/opened/index.md @@ -20,7 +20,7 @@ A promise, which fulfills with an object containing the following properties: - `extensions` - : A string representing any extensions applied to the `WebSocketStream`. Such extensions are not currently defined, but may be in the future. Currently returns an empty string. - `protocol` - - : A string representing the sub-protocol used to open the current WebSocket connection (chosen from the options specified in the [`protocols`](/en-US/docs/Web/API/WebSocketStream/WebSocketStream#protocols) option of the `WebSocketStream()` constructor). Returns an empty string if no sub-protocol has been used to open the connection (i.e. no sub-protocol options were included in the constructor call). + - : A string representing the sub-protocol used to open the current WebSocket connection (chosen from the options specified in the [`protocols`](/en-US/docs/Web/API/WebSocketStream/WebSocketStream#protocols) option of the `WebSocketStream()` constructor). Returns an empty string if no sub-protocol has been used to open the connection (i.e., no sub-protocol options were included in the constructor call). - `readable` - : A {{domxref("ReadableStream")}} instance. Call {{domxref("ReadableStream.getReader()")}} on it to obtain a {{domxref("ReadableStreamDefaultReader")}} instance that can be used to read incoming WebSocket data. - `writable` diff --git a/files/en-us/web/api/webtransport/close/index.md b/files/en-us/web/api/webtransport/close/index.md index 1005c88d43042a8..30cbca5e25422ae 100644 --- a/files/en-us/web/api/webtransport/close/index.md +++ b/files/en-us/web/api/webtransport/close/index.md @@ -41,10 +41,10 @@ const url = "https://example.com:4999/wt"; // Initialize transport connection const transport = new WebTransport(url); -// ... +// … transport.close({ - closeCode: 017, + closeCode: 17, reason: "CloseButtonPressed", }); ``` diff --git a/files/en-us/web/api/webtransport/closed/index.md b/files/en-us/web/api/webtransport/closed/index.md index 39d846080da00fe..aebd97c56ef5c4d 100644 --- a/files/en-us/web/api/webtransport/closed/index.md +++ b/files/en-us/web/api/webtransport/closed/index.md @@ -10,6 +10,8 @@ browser-compat: api.WebTransport.closed The **`closed`** read-only property of the {{domxref("WebTransport")}} interface returns a promise that resolves when the transport is closed. +This promise is created when the `WebTransport` object is created and is resolved when the transport is closed in any way, such as by calling the {{domxref("WebTransport.close", "close()")}} method, when the connection failed, or when the connection is closed by the server. Accessing or awaiting this promise does not trigger any action; it only allows actions to be taken when the transport is closed, similar to listening to an event. + ## Value A {{jsxref("Promise")}} that resolves to an object containing the following properties: @@ -19,6 +21,8 @@ A {{jsxref("Promise")}} that resolves to an object containing the following prop - `reason` - : A string representing the reason for closing the `WebTransport`. +Or, in the case of an unexpected closure, such as network failure, the promise rejects with an error. + ## Examples ```js @@ -31,10 +35,10 @@ async function initTransport(url) { // The connection can be used once ready fulfills await transport.ready; - // ... + // … } -// ... +// … async function closeTransport(transport) { // Respond to connection closing diff --git a/files/en-us/web/api/webtransport/createbidirectionalstream/index.md b/files/en-us/web/api/webtransport/createbidirectionalstream/index.md index ec1ec75e7617b0d..757cf7fbed2f710 100644 --- a/files/en-us/web/api/webtransport/createbidirectionalstream/index.md +++ b/files/en-us/web/api/webtransport/createbidirectionalstream/index.md @@ -61,7 +61,7 @@ async function setUpBidirectional() { // stream.writable is a WritableStream const writable = stream.writable; - // ... + // … } ``` diff --git a/files/en-us/web/api/webtransport/createunidirectionalstream/index.md b/files/en-us/web/api/webtransport/createunidirectionalstream/index.md index 0d35caf10dab15e..d14de378ca34e48 100644 --- a/files/en-us/web/api/webtransport/createunidirectionalstream/index.md +++ b/files/en-us/web/api/webtransport/createunidirectionalstream/index.md @@ -77,15 +77,15 @@ async function writeData() { You can also use {{domxref("WritableStreamDefaultWriter.abort()")}} to abruptly terminate the stream. When using `abort()`, the browser may discard any pending data that hasn't yet been sent. ```js -// ... +// … const stream = await transport.createUnidirectionalStream(); const writer = stream.getWriter(); -// ... +// … -writer.write(...); -writer.write(...); +writer.write(data1); +writer.write(data2); await writer.abort(); // Not all the data may have been written. ``` diff --git a/files/en-us/web/api/webtransport/index.md b/files/en-us/web/api/webtransport/index.md index 5392b9bcc53cccd..b6b45150e2edb45 100644 --- a/files/en-us/web/api/webtransport/index.md +++ b/files/en-us/web/api/webtransport/index.md @@ -87,7 +87,7 @@ async function useTransport(url) { const transport = await initTransport(url); // Use the transport object to send and receive data - // ... + // … // When done, close the transport await closeTransport(transport); diff --git a/files/en-us/web/api/webtransport/ready/index.md b/files/en-us/web/api/webtransport/ready/index.md index 3e2ac03c18912dd..268e053dc422b68 100644 --- a/files/en-us/web/api/webtransport/ready/index.md +++ b/files/en-us/web/api/webtransport/ready/index.md @@ -10,6 +10,8 @@ browser-compat: api.WebTransport.ready The **`ready`** read-only property of the {{domxref("WebTransport")}} interface returns a promise that resolves when the transport is ready to use. +This promise is created when the `WebTransport` object is created and is resolved when a connection is established. Accessing or awaiting this promise does not trigger any action; it only allows actions to be taken when the transport is ready, similar to listening to an event. + ## Value A {{jsxref("Promise")}} that resolves to `undefined`. @@ -26,10 +28,10 @@ async function initTransport(url) { // The connection can be used once ready fulfills await transport.ready; - // ... + // … } -// ... +// … async function closeTransport(transport) { // Respond to connection closing diff --git a/files/en-us/web/api/webtransport/reliability/index.md b/files/en-us/web/api/webtransport/reliability/index.md index 4074054130010fc..b06b90011534454 100644 --- a/files/en-us/web/api/webtransport/reliability/index.md +++ b/files/en-us/web/api/webtransport/reliability/index.md @@ -37,12 +37,12 @@ async function initTransport(url) { // Prior to this the reliability is "pending" await transport.ready; - if (transport.reliability == "reliable-only") { + if (transport.reliability === "reliable-only") { // Use connection only with reliable transports } else { // Use connection with either reliable or unreliable transports. } - // ... + // … } ``` diff --git a/files/en-us/web/api/webtransport/webtransport/index.md b/files/en-us/web/api/webtransport/webtransport/index.md index 072a132c7082b39..c378197d4e43708 100644 --- a/files/en-us/web/api/webtransport/webtransport/index.md +++ b/files/en-us/web/api/webtransport/webtransport/index.md @@ -129,7 +129,7 @@ async function useTransport(url) { const transport = await initTransport(url); // Use the transport object to send and receive data - // ... + // … // When done, close the transport await closeTransport(transport); diff --git a/files/en-us/web/api/webtransport_api/index.md b/files/en-us/web/api/webtransport_api/index.md index 7c1f7cb5456c824..66491594419d6cb 100644 --- a/files/en-us/web/api/webtransport_api/index.md +++ b/files/en-us/web/api/webtransport_api/index.md @@ -42,10 +42,10 @@ async function initTransport(url) { // The connection can be used once ready fulfills await transport.ready; - // ... + // … } -// ... +// … async function closeTransport(transport) { // Respond to connection closing @@ -171,7 +171,7 @@ async function setUpBidirectional() { // stream.writable is a WebTransportSendStream const writable = stream.writable; - ... + // … } ``` diff --git a/files/en-us/web/api/webtransportbidirectionalstream/index.md b/files/en-us/web/api/webtransportbidirectionalstream/index.md index c981ca46f9bb6f7..10b526a7fd55167 100644 --- a/files/en-us/web/api/webtransportbidirectionalstream/index.md +++ b/files/en-us/web/api/webtransportbidirectionalstream/index.md @@ -34,7 +34,7 @@ async function setUpBidirectional() { // stream.writable is a WebTransportSendStream const writable = stream.writable; - ... + // … } ``` diff --git a/files/en-us/web/api/webtransporterror/index.md b/files/en-us/web/api/webtransporterror/index.md index dae6eea9a653800..019dca7917757f6 100644 --- a/files/en-us/web/api/webtransporterror/index.md +++ b/files/en-us/web/api/webtransporterror/index.md @@ -38,7 +38,7 @@ async function initTransport(url) { // The connection can be used once ready fulfills await transport.ready; - // ... + // … } catch (error) { const msg = `Transport initialization failed. Reason: ${error.message}. diff --git a/files/en-us/web/api/webtransporterror/source/index.md b/files/en-us/web/api/webtransporterror/source/index.md index d1232c0748deb35..cdab52501df50c0 100644 --- a/files/en-us/web/api/webtransporterror/source/index.md +++ b/files/en-us/web/api/webtransporterror/source/index.md @@ -27,7 +27,7 @@ async function initTransport(url) { // The connection can be used once ready fulfills await transport.ready; - // ... + // … } catch (error) { const msg = `Transport initialization failed. Reason: ${error.message}. diff --git a/files/en-us/web/api/webtransporterror/streamerrorcode/index.md b/files/en-us/web/api/webtransporterror/streamerrorcode/index.md index 5dbe1eea58fd29f..a567210cb76945d 100644 --- a/files/en-us/web/api/webtransporterror/streamerrorcode/index.md +++ b/files/en-us/web/api/webtransporterror/streamerrorcode/index.md @@ -27,7 +27,7 @@ async function initTransport(url) { // The connection can be used once ready fulfills await transport.ready; - // ... + // … } catch (error) { const msg = `Transport initialization failed. Reason: ${error.message}. diff --git a/files/en-us/web/api/webtransporterror/webtransporterror/index.md b/files/en-us/web/api/webtransporterror/webtransporterror/index.md index e560e2e23e64f5d..6c1a4eb09c787c6 100644 --- a/files/en-us/web/api/webtransporterror/webtransporterror/index.md +++ b/files/en-us/web/api/webtransporterror/webtransporterror/index.md @@ -40,7 +40,7 @@ async function initTransport(url) { // The connection can be used once ready fulfills await transport.ready; - // ... + // … } catch (error) { const msg = `Transport initialization failed. Reason: ${error.message}. diff --git a/files/en-us/web/api/webvr_api/concepts/index.md b/files/en-us/web/api/webvr_api/concepts/index.md index 45fe6f7957bf4ec..ab9ff868160cb53 100644 --- a/files/en-us/web/api/webvr_api/concepts/index.md +++ b/files/en-us/web/api/webvr_api/concepts/index.md @@ -112,8 +112,8 @@ A term commonly used in VR because it is a major handicap of using an HMD — we To minimize this unwanted effect, we need to: -- Avoid focusing on different depths (e.g. avoid using a lot of particles with different depths.) -- Avoid eye convergence (e.g. if you have an object that comes towards the camera your eyes will follow and converge on it.) +- Avoid focusing on different depths (e.g., avoid using a lot of particles with different depths.) +- Avoid eye convergence (e.g., if you have an object that comes towards the camera your eyes will follow and converge on it.) - Use darker backgrounds with more subdued colors where possible; a bright screen will make the eyes more tired. - Avoid rapid brightness changes. - Avoid presenting the user with large amounts of text to read. You should also be careful with the distance between the eyes/camera and the text to read. 0.5m is uncomfortable, whereas at more than 2m the stereo effect starts to break down, so somewhere in between is advisable. diff --git a/files/en-us/web/api/webvr_api/index.md b/files/en-us/web/api/webvr_api/index.md index 60dab549b8cf0b2..42e717b5cd06f4c 100644 --- a/files/en-us/web/api/webvr_api/index.md +++ b/files/en-us/web/api/webvr_api/index.md @@ -100,7 +100,7 @@ The WebVR API extends the following APIs, adding the listed features. #### Window events - {{DOMxRef("Window.vrdisplaypresentchange_event", "vrdisplaypresentchange")}} - - : Fired when the presenting state of a VR display changes — i.e. goes from presenting to not presenting or vice versa. + - : Fired when the presenting state of a VR display changes — i.e., goes from presenting to not presenting or vice versa. - {{DOMxRef("Window.vrdisplayconnect_event", "vrdisplayconnect")}} - : Fired when a compatible VR display has been connected to the computer. - {{DOMxRef("Window.vrdisplaydisconnect_event", "vrdisplaydisconnect")}} diff --git a/files/en-us/web/api/webvr_api/using_the_webvr_api/index.md b/files/en-us/web/api/webvr_api/using_the_webvr_api/index.md index a7e488ce4abd295..2709dde6d4080d8 100644 --- a/files/en-us/web/api/webvr_api/using_the_webvr_api/index.md +++ b/files/en-us/web/api/webvr_api/using_the_webvr_api/index.md @@ -17,10 +17,10 @@ To get started, you need: - Supporting VR hardware. - - The cheapest option is to use a mobile device, supporting browser, and device mount (e.g. Google Cardboard). This won't be quite as good an experience as dedicated hardware, but you won't need to purchase a powerful computer or dedicated VR display. + - The cheapest option is to use a mobile device, supporting browser, and device mount (e.g., Google Cardboard). This won't be quite as good an experience as dedicated hardware, but you won't need to purchase a powerful computer or dedicated VR display. - Dedicated hardware can be costly, but it does provide a better experience. The most WebVR-compatible hardware at the moment is the HTC VIVE, and The Oculus Rift. The front page of [webvr.info](https://webvr.info/) has some further useful information about available hardware, and what browser support them. -- A computer powerful enough to handle rendering/displaying of VR scenes using your dedicated VR Hardware, if required. To give you an idea of what you need, look at the relevant guide for the VR you are purchasing (e.g. [VIVE READY Computers](https://www.vive.com/us/vive-ready/)). +- A computer powerful enough to handle rendering/displaying of VR scenes using your dedicated VR Hardware, if required. To give you an idea of what you need, look at the relevant guide for the VR you are purchasing (e.g., [VIVE READY Computers](https://www.vive.com/us/vive-ready/)). - A supporting browser installed — the latest [Firefox Nightly](https://www.mozilla.org/en-US/firefox/channel/desktop/) or [Chrome](https://www.google.com/chrome/index.html) are your best options right now, on desktop or mobile. Once you have everything assembled, you can test to see whether your setup works with WebVR by going to our [simple A-Frame demo](https://mdn.github.io/webvr-tests/webvr/aframe-demo/), and seeing whether the scene renders and whether you can enter VR display mode by pressing the button at the bottom right. @@ -44,7 +44,7 @@ Our demo features the holy grail of WebGL demos — a rotating 3D cube. We've im Our demo also features: - A button to start (and stop) our scene from being presented in the VR display. -- A button to show (and hide) VR pose data, i.e. the position and orientation of the headset, updated in real time. +- A button to show (and hide) VR pose data, i.e., the position and orientation of the headset, updated in real time. When you look through the source code of [our demo's main JavaScript file](https://github.com/mdn/webvr-tests/blob/main/webvr/raw-webgl-example/webgl-demo.js), you can easily find the WebVR-specific parts by searching for the string "WebVR" in preceding comments. @@ -116,7 +116,7 @@ To begin with, `start()` retrieves a WebGL context to use to render 3D graphics function start() { canvas = document.getElementById("gl-canvas"); - initWebGL(canvas); // Initialize the GL context + initWebGL(canvas); // Initialize the GL context // WebGL setup code here ``` @@ -136,7 +136,7 @@ Now onto our first WebVR-specific code. First of all, we check to see if {{domxr ```js // WebVR: Check to see if WebVR is supported if (navigator.getVRDisplays) { - console.log('WebVR 1.1 supported'); + console.log("WebVR 1.1 supported"); ``` Inside our `if () { }` block, we run the {{domxref("Navigator.getVRDisplays()")}} function. This returns a promise, which is fulfilled with an array containing all the VR display devices connected to the computer. If none are connected, the array will be empty. @@ -152,7 +152,7 @@ Inside the promise `then()` block, we check whether the array length is more tha // If a display is available, use it to present the scene if (displays.length > 0) { vrDisplay = displays[0]; - console.log('Display found'); + console.log("Display found"); ``` > [!NOTE] @@ -172,10 +172,10 @@ Since the maximum number of layers you can display is currently 1, and the only ```js // Starting the presentation when the button is clicked: It can only be called in response to a user gesture - btn.addEventListener('click', () => { - if (btn.textContent === 'Start VR display') { + btn.addEventListener("click", () => { + if (btn.textContent === "Start VR display") { vrDisplay.requestPresent([{ source: canvas }]).then(() => { - console.log('Presenting to WebVR display'); + console.log("Presenting to WebVR display"); ``` With our presentation request successful, we now want to start setting up to render content to present to the VRDisplay. First of all we set the canvas to the same size as the VR display area. We do this by getting the {{domxref("VREyeParameters")}} for both eyes using {{domxref("VRDisplay.getEyeParameters()")}}. @@ -203,7 +203,7 @@ drawVRScene(); Finally, we update the button text so that the next time it is pressed, it will stop presentation to the VR display. ```js - btn.textContent = 'Exit VR display'; + btn.textContent = "Exit VR display"; }); ``` @@ -212,9 +212,9 @@ To stop the VR presentation when the button is subsequently pressed, we call {{d ```js } else { vrDisplay.exitPresent(); - console.log('Stopped presenting to WebVR display'); + console.log("Stopped presenting to WebVR display"); - btn.textContent = 'Start VR display'; + btn.textContent = "Start VR display"; // Stop the VR presentation, and start the normal presentation vrDisplay.cancelAnimationFrame(vrSceneFrame); @@ -224,7 +224,7 @@ To stop the VR presentation when the button is subsequently pressed, we call {{d } }); } else { - console.log('WebVR API not supported by this browser.'); + console.log("WebVR API not supported by this browser."); } } ``` @@ -465,7 +465,7 @@ You should note that we've used a conditional expression to detect whether the l The WebVR spec features a number of events that are fired, allowing our app code to react to changes in the state of the VR display (see [Window events](/en-US/docs/Web/API/WebVR_API#window_events)). For example: -- {{domxref("Window/vrdisplaypresentchange_event", "vrdisplaypresentchange")}} — Fires when the presenting state of a VR display changes — i.e. goes from presenting to not presenting, or vice versa. +- {{domxref("Window/vrdisplaypresentchange_event", "vrdisplaypresentchange")}} — Fires when the presenting state of a VR display changes — i.e., goes from presenting to not presenting, or vice versa. - {{domxref("Window.vrdisplayconnect_event", "vrdisplayconnect")}} — Fires when a compatible VR display has been connected to the computer. - {{domxref("Window.vrdisplaydisconnect_event", "vrdisplaydisconnect")}} — Fires when a compatible VR display has been disconnected from the computer. diff --git a/files/en-us/web/api/webvr_api/using_vr_controllers_with_webvr/index.md b/files/en-us/web/api/webvr_api/using_vr_controllers_with_webvr/index.md index 70c03419faddb25..73d8637887d613d 100644 --- a/files/en-us/web/api/webvr_api/using_vr_controllers_with_webvr/index.md +++ b/files/en-us/web/api/webvr_api/using_vr_controllers_with_webvr/index.md @@ -15,7 +15,7 @@ Many WebVR hardware setups feature controllers that go along with the headset. T ## The WebVR API -The [WebVR API](/en-US/docs/Web/API/WebVR_API) is a nascent, but very interesting new feature of the web platform that allows developers to create web-based virtual reality experiences. It does this by providing access to VR headsets connected to your computer as {{domxref("VRDisplay")}} objects, which can be manipulated to start and stop presentation to the display, queried for movement data (e.g. orientation and position) that can be used to update the display on each frame of the animation loop, and more. +The [WebVR API](/en-US/docs/Web/API/WebVR_API) is a nascent, but very interesting new feature of the web platform that allows developers to create web-based virtual reality experiences. It does this by providing access to VR headsets connected to your computer as {{domxref("VRDisplay")}} objects, which can be manipulated to start and stop presentation to the display, queried for movement data (e.g., orientation and position) that can be used to update the display on each frame of the animation loop, and more. Before you read this article, you should really be familiar with the basics of the WebVR API already — go and read [Using the WebVR API](/en-US/docs/Web/API/WebVR_API/Using_the_WebVR_API) first, if you haven't already done so, which also details browser support and required hardware setup. @@ -25,7 +25,7 @@ The [Gamepad API](/en-US/docs/Web/API/Gamepad_API) is a fairly well-supported AP You can find more about basic Gamepad API usage in [Using the Gamepad API](/en-US/docs/Web/API/Gamepad_API/Using_the_Gamepad_API), and [Implementing controls using the Gamepad API](/en-US/docs/Games/Techniques/Controls_Gamepad_API). -However, in this article we will mainly be concentrating on some of the new features provided by the [Gamepad Extensions](https://w3c.github.io/gamepad/extensions.html) API, which allows access to advanced controller information such as position and orientation data, control over haptic actuators (e.g. vibration hardware), and more. This API is very new, and currently is only supported and enabled by default in Firefox 55+ Beta/Nightly channels. +However, in this article we will mainly be concentrating on some of the new features provided by the [Gamepad Extensions](https://w3c.github.io/gamepad/extensions.html) API, which allows access to advanced controller information such as position and orientation data, control over haptic actuators (e.g., vibration hardware), and more. This API is very new, and currently is only supported and enabled by default in Firefox 55+ Beta/Nightly channels. ## Types of controller @@ -110,7 +110,6 @@ Gamepad can return position info: ${gp.pose.hasPosition} Gamepad can return orientation info: ${gp.pose.hasOrientation}`; listItem.insertBefore( document.createElement("strong"), - }), listItem.firstChild, ).textContent = `Gamepad ${gp.index}`; list.appendChild(listItem); @@ -140,8 +139,8 @@ At the end of our example we first include the `removeGamepads()` function: ```js function removeGamepads() { const gpLi = document.querySelectorAll(".gamepad"); - for (let i = 0; i < gpLi.length; i++) { - list.removeChild(gpLi[i]); + for (const li of gpLi) { + list.removeChild(li); } reportGamepads(); } diff --git a/files/en-us/web/api/webvtt_api/index.md b/files/en-us/web/api/webvtt_api/index.md index d3d53251b9a4e60..3f32ad70e69ccdd 100644 --- a/files/en-us/web/api/webvtt_api/index.md +++ b/files/en-us/web/api/webvtt_api/index.md @@ -82,9 +82,7 @@ These [CSS](/en-US/docs/Web/CSS) [pseudo-element](/en-US/docs/Web/CSS/Pseudo-ele The following example adds a new {{domxref("TextTrack")}} to the video, then adds cues using {{domxref("TextTrack.addCue()")}} method calls, with constructed `VTTCue` objects as arguments. ```html -<video - controls - src="https://interactive-examples.mdn.mozilla.net/media/cc0-videos/friday.mp4"></video> +<video controls src="/shared-assets/videos/friday.mp4"></video> ``` #### CSS @@ -181,9 +179,7 @@ video { ``` ```html -<video - controls - src="https://interactive-examples.mdn.mozilla.net/media/cc0-videos/friday.mp4"></video> +<video controls src="/shared-assets/videos/friday.mp4"></video> ``` #### CSS @@ -250,9 +246,7 @@ video { ``` ```html hidden -<video - controls - src="https://interactive-examples.mdn.mozilla.net/media/cc0-videos/friday.mp4"></video> +<video controls src="/shared-assets/videos/friday.mp4"></video> ``` #### Styling by tag type @@ -371,7 +365,7 @@ video::cue(v[voice="Bob"]) { #### Result -The example should the cues with colour coding that matches the styling above (if the text is not colored, then `::cue` is not supported on your browser). +The example should the cues with color coding that matches the styling above (if the text is not colored, then `::cue` is not supported on your browser). {{EmbedLiveSample('More cue styling examples','400','330')}} diff --git a/files/en-us/web/api/webvtt_api/web_video_text_tracks_format/index.md b/files/en-us/web/api/webvtt_api/web_video_text_tracks_format/index.md index 503b4a327eb981f..926ac655bd61231 100644 --- a/files/en-us/web/api/webvtt_api/web_video_text_tracks_format/index.md +++ b/files/en-us/web/api/webvtt_api/web_video_text_tracks_format/index.md @@ -142,7 +142,7 @@ This is the third A cue timing indicates the time interval when the cue is shown. It has a start and end time, represented by timestamps. The end time must be greater than the start time, and the start time must be greater than or equal to all previous start times. -Cues may have overlapping timings, unless the WebVTT file is being used for chapters ({{HTMLElement("track")}} [`kind`](/en-US/docs/Web/HTML/Element/track#kind) is `chapters`). +Cues may have overlapping timings, unless the WebVTT file is being used for chapters ({{HTMLElement("track")}} [`kind`](/en-US/docs/Web/HTML/Reference/Elements/track#kind) is `chapters`). Each cue timing contains five components: @@ -290,7 +290,7 @@ Older browser versions may support only the following subset of named character ### Cue payload text tags A number of tags, such as `<b>`, can be used for marking up and styling text within a cue. -However, if the WebVTT file is used in a {{HTMLElement("track")}} element where the attribute [`kind`](/en-US/docs/Web/HTML/Element/track#kind) is `chapters` then you cannot use tags. +However, if the WebVTT file is used in a {{HTMLElement("track")}} element where the attribute [`kind`](/en-US/docs/Web/HTML/Reference/Elements/track#kind) is `chapters` then you cannot use tags. - Timestamp tag diff --git a/files/en-us/web/api/webxr_device_api/cameras/index.md b/files/en-us/web/api/webxr_device_api/cameras/index.md index fd47e7ecc357786..15a23dd569f6a5d 100644 --- a/files/en-us/web/api/webxr_device_api/cameras/index.md +++ b/files/en-us/web/api/webxr_device_api/cameras/index.md @@ -194,7 +194,7 @@ const translateVec = vec3.fromValues( mat4.translate(transform, transform, translateVec); ``` -This starts with the perspective matrix representing a 130° vertical field of view, then applies a translation that moves the camera in a manner that includes [track](#track), [crane](#crane), and [push](#push) movements. +This starts with the perspective matrix representing a 130° vertical field of view, then applies a translation that moves the camera in a manner that includes [track](#trucking_moving_left_or_right), [crane](#pedestaling_moving_up_or_down), and [push](#dollying_moving_in_or_out) movements. #### Scaling transforms diff --git a/files/en-us/web/api/webxr_device_api/index.md b/files/en-us/web/api/webxr_device_api/index.md index 586ecabc72daab5..95fb71d9716e92a 100644 --- a/files/en-us/web/api/webxr_device_api/index.md +++ b/files/en-us/web/api/webxr_device_api/index.md @@ -5,6 +5,17 @@ page-type: web-api-overview status: - experimental browser-compat: api.Navigator.xr +spec-urls: + - https://immersive-web.github.io/webxr/ + - https://immersive-web.github.io/anchors/ + - https://immersive-web.github.io/webxr-ar-module/ + - https://immersive-web.github.io/depth-sensing/ + - https://immersive-web.github.io/dom-overlays/ + - https://immersive-web.github.io/webxr-gamepads-module/ + - https://immersive-web.github.io/webxr-hand-input/ + - https://immersive-web.github.io/hit-test/ + - https://immersive-web.github.io/layers/ + - https://immersive-web.github.io/lighting-estimation/ --- {{DefaultAPISidebar("WebXR Device API")}}{{SecureContext_Header}}{{SeeCompatTable}} @@ -37,7 +48,7 @@ The equipment may also include an accelerometer, barometer, or other sensors whi - {{domxref("navigator.xr")}} - {{domxref("XRSystem")}} - {{domxref("XRPermissionStatus")}} -- `Permissions-Policy`: [`xr-spatial-tracking`](/en-US/docs/Web/HTTP/Headers/Permissions-Policy/xr-spatial-tracking) +- `Permissions-Policy`: [`xr-spatial-tracking`](/en-US/docs/Web/HTTP/Reference/Headers/Permissions-Policy/xr-spatial-tracking) ### Session @@ -164,75 +175,7 @@ The following guides and tutorials are a great resource to learn how to comprehe ## Specifications -<table> - <thead> - <tr> - <th>Specification</th> - </tr> - </thead> - <tbody> - <tr> - <td><a href="https://immersive-web.github.io/webxr/"><strong>WebXR Device API</strong></a> - (<a href="https://github.com/immersive-web/webxr">Source</a>, - <a href="https://github.com/immersive-web/webxr/issues">Issues</a>, - <a href="https://github.com/immersive-web/webxr/blob/master/explainer.md">Explainer</a>)</td> - </tr> - <tr> - <td><a href="https://immersive-web.github.io/anchors/"><strong>WebXR Anchors Module</strong></a> - (<a href="https://github.com/immersive-web/anchors">Source</a>, - <a href="https://github.com/immersive-web/anchors/issues">Issues</a>, - <a href="https://github.com/immersive-web/anchors/blob/master/explainer.md">Explainer</a>)</td> - </tr> - <tr> - <td><a href="https://immersive-web.github.io/webxr-ar-module/"><strong>WebXR Augmented Reality Module</strong></a> - (<a href="https://github.com/immersive-web/webxr-ar-module">Source</a>, - <a href="https://github.com/immersive-web/webxr-ar-module/issues">Issues</a>, - <a href="https://github.com/immersive-web/webxr-ar-module/blob/master/ar-module-explainer.md">Explainer</a>)</td> - </tr> - <tr> - <td><a href="https://immersive-web.github.io/depth-sensing/"><strong>WebXR Depth Sensing Module</strong></a> - (<a href="https://github.com/immersive-web/depth-sensing">Source</a>, - <a href="https://github.com/immersive-web/depth-sensing/issues">Issues</a>, - <a href="https://github.com/immersive-web/depth-sensing/blob/main/explainer.md">Explainer</a>)</td> - </tr> - <tr> - <td><a href="https://immersive-web.github.io/dom-overlays/"><strong>WebXR DOM Overlays Module</strong></a> - (<a href="https://github.com/immersive-web/dom-overlays">Source</a>, - <a href="https://github.com/immersive-web/dom-overlays/issues">Issues</a>, - <a href="https://github.com/immersive-web/dom-overlays/blob/master/explainer.md">Explainer</a>)</td> - </tr> - <tr> - <td><a href="https://immersive-web.github.io/webxr-gamepads-module/"><strong>WebXR Gamepads Module</strong></a> - (<a href="https://github.com/immersive-web/webxr-gamepads-module">Source</a>, - <a href="https://github.com/immersive-web/webxr-gamepads-module/issues">Issues</a>, - <a href="https://github.com/immersive-web/webxr-gamepads-module/blob/master/gamepads-module-explainer.md">Explainer</a>)</td> - </tr> - <tr> - <td><a href="https://immersive-web.github.io/webxr-hand-input/"><strong>WebXR Hand Input Module</strong></a> - (<a href="https://github.com/immersive-web/webxr-hand-input">Source</a>, - <a href="https://github.com/immersive-web/webxr-hand-input/issues">Issues</a>, - <a href="https://github.com/immersive-web/webxr-hand-input/blob/master/explainer.md">Explainer</a>)</td> - </tr> - <tr> - <td><a href="https://immersive-web.github.io/hit-test/"><strong>WebXR Hit Test Module</strong></a> - (<a href="https://github.com/immersive-web/hit-test">Source</a>, - <a href="https://github.com/immersive-web/hit-test/issues">Issues</a>, - <a href="https://github.com/immersive-web/hit-test/blob/master/hit-testing-explainer.md">Explainer</a>)</td> - </tr> - <tr> - <td><a href="https://immersive-web.github.io/layers/"><strong>WebXR Layers API</strong></a> - (<a href="https://github.com/immersive-web/layers">Source</a>, - <a href="https://github.com/immersive-web/layers/issues">Issues</a>, - <a href="https://github.com/immersive-web/layers/blob/master/explainer.md">Explainer</a>)</td> - </tr> - <tr> - <td><a href="https://immersive-web.github.io/lighting-estimation/"><strong>WebXR Lighting Estimation API</strong></a> - (<a href="https://github.com/immersive-web/lighting-estimation">Source</a>, - <a href="https://github.com/immersive-web/lighting-estimation/issues">Issues</a>, - <a href="https://github.com/immersive-web/lighting-estimation/blob/main/lighting-estimation-explainer.md">Explainer</a>)</td> - </tr> - </tbody> -</table> +{{Specifications}} ## Browser compatibility diff --git a/files/en-us/web/api/webxr_device_api/inputs/index.md b/files/en-us/web/api/webxr_device_api/inputs/index.md index cbe7d38b7646bca..8bdbee428cdbd30 100644 --- a/files/en-us/web/api/webxr_device_api/inputs/index.md +++ b/files/en-us/web/api/webxr_device_api/inputs/index.md @@ -172,7 +172,7 @@ The `inputsourceschange` event is also fired once when the session's creation ca Each input source has a {{domxref("XRInputSource.profiles", "profiles")}} property, which contains a live list of the WebXR input profiles which apply to the input source, in order of specificity from most-specific to least. -In order to do anything meaningful involving scanning of profiles beyond basic identification of features, you may need to import the JSON profile database from the [WebXR Input Profiles Registry](https://github.com/immersive-web/webxr-input-profiles/tree/master/packages/registry). +In order to do anything meaningful involving scanning of profiles beyond basic identification of features, you may need to import the JSON profile database from the [WebXR Input Profiles Registry](https://github.com/immersive-web/webxr-input-profiles/tree/main/packages/registry). See [Input profiles](#input_profiles) for more specific details on working with input profiles. diff --git a/files/en-us/web/api/webxr_device_api/movement_and_motion/index.md b/files/en-us/web/api/webxr_device_api/movement_and_motion/index.md index f518f34f860c6bf..739a016416e1f6f 100644 --- a/files/en-us/web/api/webxr_device_api/movement_and_motion/index.md +++ b/files/en-us/web/api/webxr_device_api/movement_and_motion/index.md @@ -35,7 +35,6 @@ const enableRotation = true; const allowMouseRotation = true; const allowKeyboardMotion = true; const enableForcePolyfill = false; -//const SESSION_TYPE = "immersive-vr"; const SESSION_TYPE = "inline"; const MOUSE_SPEED = 0.003; ``` diff --git a/files/en-us/web/api/webxr_device_api/permissions_and_security/index.md b/files/en-us/web/api/webxr_device_api/permissions_and_security/index.md index e20e1d7789c4934..1b22b47149118bf 100644 --- a/files/en-us/web/api/webxr_device_api/permissions_and_security/index.md +++ b/files/en-us/web/api/webxr_device_api/permissions_and_security/index.md @@ -6,13 +6,13 @@ page-type: guide {{DefaultAPISidebar("WebXR Device API")}} -The [WebXR Device API](/en-US/docs/Web/API/WebXR_Device_API) has several areas of security to contend with, from establishing [Permissions Policy](/en-US/docs/Web/HTTP/Permissions_Policy) to ensuring the user intends to use the mixed reality presentation before activating it. Among other things, you need to confirm access to device features such as the microphone and/or camera, get permission to use immersive VR mode (if applicable), and so forth. The variety of hardware and software involved in XR brings multiple APIs and technologies into play. In this guide, we'll cover how to ensure your app has the permissions it needs to provide a secure and private XR experience. +The [WebXR Device API](/en-US/docs/Web/API/WebXR_Device_API) has several areas of security to contend with, from establishing [Permissions Policy](/en-US/docs/Web/HTTP/Guides/Permissions_Policy) to ensuring the user intends to use the mixed reality presentation before activating it. Among other things, you need to confirm access to device features such as the microphone and/or camera, get permission to use immersive VR mode (if applicable), and so forth. The variety of hardware and software involved in XR brings multiple APIs and technologies into play. In this guide, we'll cover how to ensure your app has the permissions it needs to provide a secure and private XR experience. The WebXR Device API is subject to a number of permission and security controls. While not onerous, they are worth being aware of. These mostly revolve around the fully-immersive `immersive-vr` session mode, but there are things to be aware of when setting up an AR session, as well. ## Immersive presentation of VR -First, any requests to activate the `immersive-vr` mode are rejected if the domain issuing the request does not have permission to enable an immersive session. This permission comes from the `xr-spatial-tracking` [Permissions Policy](/en-US/docs/Web/HTTP/Permissions_Policy). +First, any requests to activate the `immersive-vr` mode are rejected if the domain issuing the request does not have permission to enable an immersive session. This permission comes from the `xr-spatial-tracking` [Permissions Policy](/en-US/docs/Web/HTTP/Guides/Permissions_Policy). Once that check is passed, the request to enter `immersive-vr` mode is allowed if all of the following are true: diff --git a/files/en-us/web/api/webxr_device_api/spatial_tracking/index.md b/files/en-us/web/api/webxr_device_api/spatial_tracking/index.md index 731e9a6db6a2148..799ca0071f4b8d6 100644 --- a/files/en-us/web/api/webxr_device_api/spatial_tracking/index.md +++ b/files/en-us/web/api/webxr_device_api/spatial_tracking/index.md @@ -136,10 +136,7 @@ function myDrawFrame(currentFrameTime, frame) { animationFrameRequestID = session.requestAnimationFrame(myDrawFrame); if (viewerPose) { - if (!previousViewerPose) { - previousViewerPose = viewerPose; - } - + previousViewerPose ??= viewerPose; let offsetMatrix = mat4.create(); mat4.sub( offsetMatrix, diff --git a/files/en-us/web/api/webxr_device_api/startup_and_shutdown/index.md b/files/en-us/web/api/webxr_device_api/startup_and_shutdown/index.md index 07b73e0c979c526..6fedf738052c3cf 100644 --- a/files/en-us/web/api/webxr_device_api/startup_and_shutdown/index.md +++ b/files/en-us/web/api/webxr_device_api/startup_and_shutdown/index.md @@ -105,7 +105,7 @@ Of course, you can simplify this depending on your needs; since your app is prob ### Permissions and security -There are a number of security measures in place revolving around WebXR. First among these is that use of `immersive-vr` mode—which entirely replaces the user's view of the world—requires that the `xr-spatial-tracking` [permission policy](/en-US/docs/Web/HTTP/Permissions_Policy) be in place. On top of that, the document needs to be secure and currently focused. Finally, you must call {{domxref("XRSystem.requestSession", "requestSession()")}} from a user event handler, such as the handler for the {{domxref("Element.click_event", "click")}} event. +There are a number of security measures in place revolving around WebXR. First among these is that use of `immersive-vr` mode—which entirely replaces the user's view of the world—requires that the `xr-spatial-tracking` [permission policy](/en-US/docs/Web/HTTP/Guides/Permissions_Policy) be in place. On top of that, the document needs to be secure and currently focused. Finally, you must call {{domxref("XRSystem.requestSession", "requestSession()")}} from a user event handler, such as the handler for the {{domxref("Element.click_event", "click")}} event. For more specifics about securing WebXR activities and usage, see the article [Permissions and security for WebXR](/en-US/docs/Web/API/WebXR_Device_API/Permissions_and_security). diff --git a/files/en-us/web/api/wgsllanguagefeatures/index.md b/files/en-us/web/api/wgsllanguagefeatures/index.md index f14b26a84c136fb..dfb72ba287e1632 100644 --- a/files/en-us/web/api/wgsllanguagefeatures/index.md +++ b/files/en-us/web/api/wgsllanguagefeatures/index.md @@ -94,7 +94,7 @@ for (const value of valueIterator) { console.log(value); } -// ... +// … ``` ## Specifications diff --git a/files/en-us/web/api/wheelevent/deltamode/index.md b/files/en-us/web/api/wheelevent/deltamode/index.md index 85fc226409d8e04..b45681aa62b81bb 100644 --- a/files/en-us/web/api/wheelevent/deltamode/index.md +++ b/files/en-us/web/api/wheelevent/deltamode/index.md @@ -18,6 +18,8 @@ Permitted values are: | `DOM_DELTA_LINE` | `0x01` | The delta values are specified in lines. | | `DOM_DELTA_PAGE` | `0x02` | The delta values are specified in pages. | +You must check the `deltaMode` property to determine the unit of the `deltaX`, `deltaY`, and `deltaZ` values. Do not assume that those values are specified in pixels. Some browsers, for compatibility reasons, may return different units for the `delta*` values depending on whether `deltaMode` has been accessed, to accommodate for websites not explicitly checking the `deltaMode` property. + ## Value An `unsigned long`. diff --git a/files/en-us/web/api/wheelevent/deltax/index.md b/files/en-us/web/api/wheelevent/deltax/index.md index d9dfd3911421a4c..0b7cac0b6140fcf 100644 --- a/files/en-us/web/api/wheelevent/deltax/index.md +++ b/files/en-us/web/api/wheelevent/deltax/index.md @@ -12,6 +12,8 @@ The **`WheelEvent.deltaX`** read-only property is a `double` representing the horizontal scroll amount in the {{domxref("WheelEvent.deltaMode")}} unit. +You must check the `deltaMode` property to determine the unit of the `deltaX` value. Do not assume that the `deltaX` value is specified in pixels. Some browsers, for compatibility reasons, may return different units for the `deltaX` value depending on whether `deltaMode` has been accessed, to accommodate for websites not explicitly checking the `deltaMode` property. + ## Value A number. diff --git a/files/en-us/web/api/wheelevent/deltay/index.md b/files/en-us/web/api/wheelevent/deltay/index.md index 1b1ec51ef934b3c..6769615d1100744 100644 --- a/files/en-us/web/api/wheelevent/deltay/index.md +++ b/files/en-us/web/api/wheelevent/deltay/index.md @@ -12,6 +12,8 @@ The **`WheelEvent.deltaY`** read-only property is a `double` representing the vertical scroll amount in the {{domxref("WheelEvent.deltaMode")}} unit. +You must check the `deltaMode` property to determine the unit of the `deltaY` value. Do not assume that the `deltaY` value is specified in pixels. Some browsers, for compatibility reasons, may return different units for the `deltaY` value depending on whether `deltaMode` has been accessed, to accommodate for websites not explicitly checking the `deltaMode` property. + ## Value A number. diff --git a/files/en-us/web/api/wheelevent/deltaz/index.md b/files/en-us/web/api/wheelevent/deltaz/index.md index 45e8600b00bd0d5..c9a5b3f2f057384 100644 --- a/files/en-us/web/api/wheelevent/deltaz/index.md +++ b/files/en-us/web/api/wheelevent/deltaz/index.md @@ -12,6 +12,8 @@ The **`WheelEvent.deltaZ`** read-only property is a `double` representing the scroll amount along the z-axis, in the {{domxref("WheelEvent.deltaMode")}} unit. +You must check the `deltaMode` property to determine the unit of the `deltaZ` value. Do not assume that the `deltaZ` value is specified in pixels. Some browsers, for compatibility reasons, may return different units for the `deltaZ` value depending on whether `deltaMode` has been accessed, to accommodate for websites not explicitly checking the `deltaMode` property. + ## Value A number. diff --git a/files/en-us/web/api/wheelevent/index.md b/files/en-us/web/api/wheelevent/index.md index 6be59dd742109e3..161db52652cab28 100644 --- a/files/en-us/web/api/wheelevent/index.md +++ b/files/en-us/web/api/wheelevent/index.md @@ -36,15 +36,7 @@ _This interface inherits properties from its ancestors, {{DOMxRef("MouseEvent")} - {{DOMxRef("WheelEvent.deltaZ")}} {{ReadOnlyInline}} - : Returns a `double` representing the scroll amount for the z-axis. - {{DOMxRef("WheelEvent.deltaMode")}} {{ReadOnlyInline}} - - - : Returns an `unsigned long` representing the unit of the `delta*` values' scroll amount. Permitted values are: - - | Constant | Value | Description | - | ---------------------------- | ------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------ | - | `WheelEvent.DOM_DELTA_PIXEL` | `0x00` | The `delta*` values are specified in pixels. | - | `WheelEvent.DOM_DELTA_LINE` | `0x01` | The `delta*` values are specified in lines. Each mouse click scrolls a line of content, where the method used to calculate line height is browser dependent. | - | `WheelEvent.DOM_DELTA_PAGE` | `0x02` | The `delta*` values are specified in pages. Each mouse click scrolls a page of content. | - + - : Returns an `unsigned long` representing the unit of the `delta*` values' scroll amount. - {{DOMxRef("WheelEvent.wheelDelta")}} {{ReadOnlyInline}} {{Deprecated_Inline}} {{Non-standard_Inline}} - : Returns an integer (32-bit) representing the distance in pixels. - {{DOMxRef("WheelEvent.wheelDeltaX")}} {{ReadOnlyInline}} {{Deprecated_Inline}} {{Non-standard_Inline}} diff --git a/files/en-us/web/api/window/afterprint_event/index.md b/files/en-us/web/api/window/afterprint_event/index.md index 3bac4864d8ec923..ea9bf42c242a410 100644 --- a/files/en-us/web/api/window/afterprint_event/index.md +++ b/files/en-us/web/api/window/afterprint_event/index.md @@ -16,9 +16,10 @@ The {{domxref("Window.beforeprint_event", "beforeprint")}} and `afterprint` even Use the event name in methods like {{domxref("EventTarget.addEventListener", "addEventListener()")}}, or set an event handler property. -```js -addEventListener("afterprint", (event) => {}); -onafterprint = (event) => {}; +```js-nolint +addEventListener("afterprint", (event) => { }) + +onafterprint = (event) => { } ``` ## Event type diff --git a/files/en-us/web/api/window/appinstalled_event/index.md b/files/en-us/web/api/window/appinstalled_event/index.md index b78659f1de7fd05..7d3c6f99e07e9ef 100644 --- a/files/en-us/web/api/window/appinstalled_event/index.md +++ b/files/en-us/web/api/window/appinstalled_event/index.md @@ -16,10 +16,10 @@ This event is not cancelable and does not bubble. Use the event name in methods like {{domxref("EventTarget.addEventListener", "addEventListener()")}}, or set an event handler property. -```js -addEventListener("appinstalled", (event) => {}); +```js-nolint +addEventListener("appinstalled", (event) => { }) -onappinstalled = (event) => {}; +onappinstalled = (event) => { } ``` ## Event type diff --git a/files/en-us/web/api/window/atob/index.md b/files/en-us/web/api/window/atob/index.md index c1bd6e1c6be4553..c677a34a628efb2 100644 --- a/files/en-us/web/api/window/atob/index.md +++ b/files/en-us/web/api/window/atob/index.md @@ -26,11 +26,11 @@ atob(encodedData) ### Parameters - `encodedData` - - : A binary string (i.e., a string in which each character in the string is treated as a byte of binary data) containing base64-encoded data. + - : A base64-encoded string, using the alphabet produced by {{domxref("Window.btoa()")}}. ### Return value -An ASCII string containing decoded data from `encodedData`. +A binary string containing raw bytes decoded from `encodedData`. Strings in JavaScript are encoded as UTF-16, so this means each character must have a code point less than 256, representing one byte of data. ### Exceptions diff --git a/files/en-us/web/api/window/back/index.md b/files/en-us/web/api/window/back/index.md deleted file mode 100644 index 6fbdf501088f111..000000000000000 --- a/files/en-us/web/api/window/back/index.md +++ /dev/null @@ -1,58 +0,0 @@ ---- -title: "Window: back() method" -short-title: back() -slug: Web/API/Window/back -page-type: web-api-instance-method -status: - - deprecated - - non-standard ---- - -{{APIRef}}{{ Non-standard_header() }}{{deprecated_header}} - -The obsolete and non-standard method `back()` on the {{domxref("window")}} -interface returns the window to the previous item in the history. This was a -Firefox-specific method and was removed in Firefox 31. - -> [!NOTE] -> Use the standard {{domxref("history.back")}} method instead. - -## Syntax - -```js-nolint -back() -``` - -### Parameters - -None. - -### Return value - -None ({{jsxref("undefined")}}). - -## Examples - -This simple example handles a click on a "Back" button by calling `back()`. - -```js -function handleMyBackButton() { - if (canGoBack) { - window.back(); - } -} -``` - -## Specifications - -This is not part of any specification. - -## Browser compatibility - -This non-standard method was only implemented in Firefox, and was removed in Firefox -31\. - -## See also - -- {{domxref("History.back()")}} -- {{domxref("History.forward()")}} diff --git a/files/en-us/web/api/window/beforeinstallprompt_event/index.md b/files/en-us/web/api/window/beforeinstallprompt_event/index.md index d9a56bcad3531c2..4e6a1e7ab48f7f7 100644 --- a/files/en-us/web/api/window/beforeinstallprompt_event/index.md +++ b/files/en-us/web/api/window/beforeinstallprompt_event/index.md @@ -25,10 +25,10 @@ When the user uses the in-app installation UI to install the app, the in-app ins Use the event name in methods like {{domxref("EventTarget.addEventListener", "addEventListener()")}}, or set an event handler property. -```js -addEventListener("beforeinstallprompt", (event) => {}); +```js-nolint +addEventListener("beforeinstallprompt", (event) => { }) -onbeforeinstallprompt = (event) => {}; +onbeforeinstallprompt = (event) => { } ``` ## Event type diff --git a/files/en-us/web/api/window/beforeprint_event/index.md b/files/en-us/web/api/window/beforeprint_event/index.md index e5408aea0eec236..80e265e653648ba 100644 --- a/files/en-us/web/api/window/beforeprint_event/index.md +++ b/files/en-us/web/api/window/beforeprint_event/index.md @@ -16,9 +16,10 @@ The {{domxref("Window.afterprint_event", "afterprint")}} and `beforeprint` event Use the event name in methods like {{domxref("EventTarget.addEventListener", "addEventListener()")}}, or set an event handler property. -```js -addEventListener("beforeprint", (event) => {}); -onbeforeprint = (event) => {}; +```js-nolint +addEventListener("beforeprint", (event) => { }) + +onbeforeprint = (event) => { } ``` ## Event type diff --git a/files/en-us/web/api/window/beforeunload_event/index.md b/files/en-us/web/api/window/beforeunload_event/index.md index aa5ca701a94320b..e7d3893f919cecd 100644 --- a/files/en-us/web/api/window/beforeunload_event/index.md +++ b/files/en-us/web/api/window/beforeunload_event/index.md @@ -16,7 +16,7 @@ The dialog can be triggered in the following ways: - Calling the event object's {{domxref("Event.preventDefault()", "preventDefault()")}} method. - Setting the event object's {{domxref("BeforeUnloadEvent.returnValue", "returnValue")}} property to a non-empty string value or any other [truthy](/en-US/docs/Glossary/Truthy) value. -- Returning any truthy value from the event handler function, e.g. `return "string"`. Note that this only works when the function is attached via the `onbeforeunload` property, not the {{domxref("EventTarget.addEventListener", "addEventListener()")}} method. This behavior is consistent across modern versions of Firefox, Safari, and Chrome. +- Returning any truthy value from the event handler function, e.g., `return "string"`. Note that this only works when the function is attached via the `onbeforeunload` property, not the {{domxref("EventTarget.addEventListener", "addEventListener()")}} method. This behavior is consistent across modern versions of Firefox, Safari, and Chrome. The last two mechanisms are legacy features; best practice is to trigger the dialog by invoking `preventDefault()` on the event object, while also setting `returnValue` to support legacy cases. @@ -24,9 +24,10 @@ The last two mechanisms are legacy features; best practice is to trigger the dia Use the event name in methods like {{domxref("EventTarget.addEventListener", "addEventListener()")}}, or set an event handler property. -```js -addEventListener("beforeunload", (event) => {}); -onbeforeunload = (event) => {}; +```js-nolint +addEventListener("beforeunload", (event) => { }) + +onbeforeunload = (event) => { } ``` ## Event type @@ -75,7 +76,7 @@ In the following example we have an HTML text {{htmlelement("input")}} to repres Our JavaScript attaches an {{domxref("Element/input_event", "input")}} event listener to the `<input>` element that listens for changes in the inputted value. When the value is updated to a non-empty value, a `beforeunload` event listener is attached to the {{domxref("Window")}} object. -If the value becomes an empty string again (i.e. the value is deleted), the `beforeunload` event listener is removed again — as mentioned above in the [Usage notes](#usage_notes), the listener should be removed when there is no unsaved data to warn about. +If the value becomes an empty string again (i.e., the value is deleted), the `beforeunload` event listener is removed again — as mentioned above in the [Usage notes](#usage_notes), the listener should be removed when there is no unsaved data to warn about. The `beforeunload` event handler function invokes `event.preventDefault()` to trigger the warning dialog when the user closes or navigates the tab. We have also included `event.returnValue = true` in the handler function so that any browsers that don't support the `event.preventDefault()` mechanism will still run the demo correctly. diff --git a/files/en-us/web/api/window/blur_event/index.md b/files/en-us/web/api/window/blur_event/index.md index 7abb7e31aeb7457..c7698e72fcdd796 100644 --- a/files/en-us/web/api/window/blur_event/index.md +++ b/files/en-us/web/api/window/blur_event/index.md @@ -18,10 +18,10 @@ This event is not cancelable and does not bubble. Use the event name in methods like {{domxref("EventTarget.addEventListener", "addEventListener()")}}, or set an event handler property. -```js -addEventListener("blur", (event) => {}); +```js-nolint +addEventListener("blur", (event) => { }) -onblur = (event) => {}; +onblur = (event) => { } ``` ## Event type diff --git a/files/en-us/web/api/window/btoa/index.md b/files/en-us/web/api/window/btoa/index.md index a62463087773433..35ef184c04dd200 100644 --- a/files/en-us/web/api/window/btoa/index.md +++ b/files/en-us/web/api/window/btoa/index.md @@ -28,7 +28,7 @@ btoa(stringToEncode) ### Parameters - `stringToEncode` - - : The _binary string_ to encode. + - : The _binary string_ to encode. Strings in JavaScript are encoded as UTF-16, so this means each character must have a code point less than 256, representing one byte of data. ### Return value diff --git a/files/en-us/web/api/window/caches/index.md b/files/en-us/web/api/window/caches/index.md index 12d6db8959dcd5c..757544e1f80aeed 100644 --- a/files/en-us/web/api/window/caches/index.md +++ b/files/en-us/web/api/window/caches/index.md @@ -20,9 +20,7 @@ A {{domxref("CacheStorage")}} object. The following example shows how a window can retrieve cached data. ```js -window.caches.open("v1").then((cache) => { - return cache.match("/list"); -}); +caches.open("v1").then((cache) => cache.match("/list")); ``` ## Specifications diff --git a/files/en-us/web/api/window/close/index.md b/files/en-us/web/api/window/close/index.md index 05f643641ec8c52..0ce81d69806c727 100644 --- a/files/en-us/web/api/window/close/index.md +++ b/files/en-us/web/api/window/close/index.md @@ -43,7 +43,7 @@ window; this demonstrates how to use `Window.close()` to close a window opened by calling {{domxref("window.open()")}}. ```js -//Global variable to store a reference to the opened window +// Global variable to store a reference to the opened window let openedWindow; function openWindow() { diff --git a/files/en-us/web/api/window/confirm/firefox_confirm_dialog.png b/files/en-us/web/api/window/confirm/firefox_confirm_dialog.png deleted file mode 100644 index 297565a2f47ed46..000000000000000 Binary files a/files/en-us/web/api/window/confirm/firefox_confirm_dialog.png and /dev/null differ diff --git a/files/en-us/web/api/window/copy_event/index.md b/files/en-us/web/api/window/copy_event/index.md deleted file mode 100644 index 31c07452988129c..000000000000000 --- a/files/en-us/web/api/window/copy_event/index.md +++ /dev/null @@ -1,51 +0,0 @@ ---- -title: "Window: copy event" -short-title: copy -slug: Web/API/Window/copy_event -page-type: web-api-event -browser-compat: api.Element.copy_event ---- - -{{APIRef}} - -The **`copy`** event fires when the user initiates a copy action through the browser's user interface. - -The original target for this event is the {{domxref("Element")}} that was the intended target of the copy action. You can listen for this event on the {{domxref("Window")}} interface to handle it in the capture or bubbling phases. For full details on this event please see the page on the [Element: copy event](/en-US/docs/Web/API/Element/copy_event). - -## Syntax - -Use the event name in methods like {{domxref("EventTarget.addEventListener", "addEventListener()")}}, or set an event handler property. - -```js -addEventListener("copy", (event) => {}); - -oncopy = (event) => {}; -``` - -## Event type - -A {{domxref("ClipboardEvent")}}. Inherits from {{domxref("Event")}}. - -{{InheritanceDiagram("ClipboardEvent")}} - -## Examples - -```js -window.addEventListener("copy", (event) => { - console.log("copy action initiated"); -}); -``` - -## Specifications - -{{Specifications}} - -## Browser compatibility - -{{Compat}} - -## See also - -- Related events: {{domxref("Window/cut_event", "cut")}}, {{domxref("Window/paste_event", "paste")}} -- This event on {{domxref("Element")}} targets: {{domxref("Element/copy_event", "copy")}} -- This event on {{domxref("Document")}} targets: {{domxref("Document/copy_event", "copy")}} diff --git a/files/en-us/web/api/window/crossoriginisolated/index.md b/files/en-us/web/api/window/crossoriginisolated/index.md index f0a84a351dcaa88..67b142805ba7869 100644 --- a/files/en-us/web/api/window/crossoriginisolated/index.md +++ b/files/en-us/web/api/window/crossoriginisolated/index.md @@ -10,7 +10,7 @@ browser-compat: api.crossOriginIsolated The **`crossOriginIsolated`** read-only property of the {{domxref("Window")}} interface returns a boolean value that indicates whether the document is cross-origin isolated. -A cross-origin isolated document only shares its {{glossary("Browsing context", "browsing context group")}} with same-origin documents in popups and navigations, and resources (both same-origin and cross-origin) that the document has opted into using via [CORS](/en-US/docs/Web/HTTP/CORS) (and [COEP](/en-US/docs/Web/HTTP/Headers/Cross-Origin-Embedder-Policy) for `<iframe>`). +A cross-origin isolated document only shares its {{glossary("Browsing context", "browsing context group")}} with same-origin documents in popups and navigations, and resources (both same-origin and cross-origin) that the document has opted into using via [CORS](/en-US/docs/Web/HTTP/Guides/CORS) (and [COEP](/en-US/docs/Web/HTTP/Reference/Headers/Cross-Origin-Embedder-Policy) for `<iframe>`). The relationship between a cross-origin opener of the document or any cross-origin popups that it opens are severed. The document may also be hosted in a separate OS process alongside other documents with which it can communicate by operating on shared memory. This mitigates the risk of side-channel attacks and cross-origin attacks referred to as [XS-Leaks](https://xsleaks.dev/). diff --git a/files/en-us/web/api/window/cut_event/index.md b/files/en-us/web/api/window/cut_event/index.md deleted file mode 100644 index dead6a31782a133..000000000000000 --- a/files/en-us/web/api/window/cut_event/index.md +++ /dev/null @@ -1,51 +0,0 @@ ---- -title: "Window: cut event" -short-title: cut -slug: Web/API/Window/cut_event -page-type: web-api-event -browser-compat: api.Element.cut_event ---- - -{{APIRef}} - -The **`cut`** event is fired when the user has initiated a "cut" action through the browser's user interface. - -The original target for this event is the {{domxref("Element")}} that was the intended target of the cut action. You can listen for this event on the {{domxref("Window")}} interface to handle it in the capture or bubbling phases. For full details on this event please see the page on the [Element: cut event](/en-US/docs/Web/API/Element/cut_event). - -## Syntax - -Use the event name in methods like {{domxref("EventTarget.addEventListener", "addEventListener()")}}, or set an event handler property. - -```js -addEventListener("cut", (event) => {}); - -oncut = (event) => {}; -``` - -## Event type - -A {{domxref("ClipboardEvent")}}. Inherits from {{domxref("Event")}}. - -{{InheritanceDiagram("ClipboardEvent")}} - -## Examples - -```js -window.addEventListener("cut", (event) => { - console.log("cut action initiated"); -}); -``` - -## Specifications - -{{Specifications}} - -## Browser compatibility - -{{Compat}} - -## See also - -- Related events: {{domxref("Window/copy_event", "copy")}}, {{domxref("Window/paste_event", "paste")}} -- This event on {{domxref("Element")}} targets: {{domxref("Element/cut_event", "cut")}} -- This event on {{domxref("Document")}} targets: {{domxref("Document/cut_event", "cut")}} diff --git a/files/en-us/web/api/window/devicemotion_event/index.md b/files/en-us/web/api/window/devicemotion_event/index.md index efbf47e7250f01a..bcce6aee26db31e 100644 --- a/files/en-us/web/api/window/devicemotion_event/index.md +++ b/files/en-us/web/api/window/devicemotion_event/index.md @@ -16,10 +16,10 @@ This event is not cancelable and does not bubble. Use the event name in methods like {{domxref("EventTarget.addEventListener", "addEventListener()")}}, or set an event handler property. -```js -addEventListener("devicemotion", (event) => {}); +```js-nolint +addEventListener("devicemotion", (event) => { }) -ondevicemotion = (event) => {}; +ondevicemotion = (event) => { } ``` ## Event type @@ -64,4 +64,3 @@ window.addEventListener("devicemotion", handleMotionEvent, true); ## See also - {{domxref("Window.deviceorientation_event", "deviceorientation")}} -- [DeviceOrientation Event](https://www.w3.org/TR/orientation-event/#devicemotion) diff --git a/files/en-us/web/api/window/deviceorientation_event/index.md b/files/en-us/web/api/window/deviceorientation_event/index.md index 54481c60ceafb80..8ac23a2bf74102d 100644 --- a/files/en-us/web/api/window/deviceorientation_event/index.md +++ b/files/en-us/web/api/window/deviceorientation_event/index.md @@ -18,10 +18,10 @@ This event is not cancelable and does not bubble. Use the event name in methods like {{domxref("EventTarget.addEventListener", "addEventListener()")}}, or set an event handler property. -```js -addEventListener("deviceorientation", (event) => {}); +```js-nolint +addEventListener("deviceorientation", (event) => { }) -ondeviceorientation = (event) => {}; +ondeviceorientation = (event) => { } ``` ## Event type diff --git a/files/en-us/web/api/window/deviceorientationabsolute_event/index.md b/files/en-us/web/api/window/deviceorientationabsolute_event/index.md index 8c3cf7409cf65ef..8de42044ce06eb4 100644 --- a/files/en-us/web/api/window/deviceorientationabsolute_event/index.md +++ b/files/en-us/web/api/window/deviceorientationabsolute_event/index.md @@ -16,10 +16,10 @@ This event is not cancelable and does not bubble. Use the event name in methods like {{domxref("EventTarget.addEventListener", "addEventListener()")}}, or set an event handler property. -```js -addEventListener("deviceorientationabsolute", (event) => {}); +```js-nolint +addEventListener("deviceorientationabsolute", (event) => { }) -ondeviceorientationabsolute = (event) => {}; +ondeviceorientationabsolute = (event) => { } ``` ## Event type diff --git a/files/en-us/web/api/window/devicepixelratio/index.md b/files/en-us/web/api/window/devicepixelratio/index.md index 4d77bb5b2bd98ef..61855a83dabf2aa 100644 --- a/files/en-us/web/api/window/devicepixelratio/index.md +++ b/files/en-us/web/api/window/devicepixelratio/index.md @@ -85,11 +85,11 @@ In this example, we'll set up a media query and watch it to see when the device ```html <div id="container"> <p> - This example demonstrates the effect of zooming the page in and out - (or moving it to a screen with a different scaling factor) on the - value of the <code>devicePixelRatio</code> property.</p> - <p>Try it and watch what happens!</p> + This example demonstrates the effect of zooming the page in and out (or + moving it to a screen with a different scaling factor) on the value of the + <code>devicePixelRatio</code> property. </p> + <p>Try it and watch what happens!</p> </div> <div id="output"></div> ``` @@ -124,9 +124,7 @@ let remove = null; const output = document.querySelector("#output"); const updatePixelRatio = () => { - if (remove != null) { - remove(); - } + remove?.(); const mqString = `(resolution: ${window.devicePixelRatio}dppx)`; const media = matchMedia(mqString); media.addEventListener("change", updatePixelRatio); diff --git a/files/en-us/web/api/window/documentpictureinpicture/index.md b/files/en-us/web/api/window/documentpictureinpicture/index.md index 760040d76f0c487..0d7571a648a7eaf 100644 --- a/files/en-us/web/api/window/documentpictureinpicture/index.md +++ b/files/en-us/web/api/window/documentpictureinpicture/index.md @@ -22,7 +22,7 @@ A {{domxref("DocumentPictureInPicture")}} object instance. ```js const videoPlayer = document.getElementById("player"); -// ... +// … // Open a Picture-in-Picture window. await window.documentPictureInPicture.requestWindow({ @@ -30,7 +30,7 @@ await window.documentPictureInPicture.requestWindow({ height: videoPlayer.clientHeight, }); -// ... +// … ``` ## Specifications diff --git a/files/en-us/web/api/window/error_event/index.md b/files/en-us/web/api/window/error_event/index.md index 25c1390c0bb2c97..e4a6bacc9304edb 100644 --- a/files/en-us/web/api/window/error_event/index.md +++ b/files/en-us/web/api/window/error_event/index.md @@ -16,10 +16,10 @@ This event is only generated for script errors thrown synchronously, such as dur Use the event name in methods like {{domxref("EventTarget.addEventListener", "addEventListener()")}}, or set an event handler property. -```js -addEventListener("error", (event) => {}); +```js-nolint +addEventListener("error", (event) => { }) -onerror = (message, source, lineno, colno, error) => {}; +onerror = (message, source, lineno, colno, error) => { } ``` > [!NOTE] @@ -64,7 +64,7 @@ The event handler's signature is asymmetric between `addEventListener()` and `on - : A string containing a human-readable error message describing the problem. Same as {{domxref("ErrorEvent.message")}}. > [!NOTE] - > In HTML, the [content event handler attribute](/en-US/docs/Web/HTML/Attributes#event_handler_attributes) `onerror` on the {{HTMLElement("body")}} element attaches `error` event listeners to `window` (_not_ the `<body>` element). For this event handler, the first parameter is called `event`, not `message`, although it still contains a string; that is, you would use `<body onerror="console.error(event)">` to log the error message. + > In HTML, the [content event handler attribute](/en-US/docs/Web/HTML/Reference/Attributes#event_handler_attributes) `onerror` on the {{HTMLElement("body")}} element attaches `error` event listeners to `window` (_not_ the `<body>` element). For this event handler, the first parameter is called `event`, not `message`, although it still contains a string; that is, you would use `<body onerror="console.error(event)">` to log the error message. - `source` - : A string containing the URL of the script that generated the error. @@ -88,7 +88,7 @@ window.onerror = (a, b, c, d, e) => { ``` > [!NOTE] -> These parameter names are observable with an [HTML event handler attribute](/en-US/docs/Web/HTML/Attributes#event_handler_attributes), where the first parameter is called `event` instead of `message`. +> These parameter names are observable with an [HTML event handler attribute](/en-US/docs/Web/HTML/Reference/Attributes#event_handler_attributes), where the first parameter is called `event` instead of `message`. This special behavior only happens for the `onerror` event handler on `window`. The [`Element.onerror`](/en-US/docs/Web/API/HTMLElement/error_event) handler still receives a single {{domxref("ErrorEvent")}} object. diff --git a/files/en-us/web/api/window/external/index.md b/files/en-us/web/api/window/external/index.md index 77d5b596fc1a169..5f86ca58e815302 100644 --- a/files/en-us/web/api/window/external/index.md +++ b/files/en-us/web/api/window/external/index.md @@ -27,10 +27,7 @@ The `External` object has the following methods: <code>AddSearchProvider(descriptionURL)</code> </td> <td> - Dummy function; does nothing. See - <a href="/en-US/docs/Web/XML/Guides/OpenSearch#autodiscovery_of_search_plugins" - >Autodiscovery of search plugins</a - >. + Dummy function; does nothing. Used to <a href="/en-US/docs/Web/XML/Guides/OpenSearch">register search descriptions</a>. </td> </tr> <tr> diff --git a/files/en-us/web/api/window/fence/index.md b/files/en-us/web/api/window/fence/index.md index 47300032f5063e1..bffa18b43cd816e 100644 --- a/files/en-us/web/api/window/fence/index.md +++ b/files/en-us/web/api/window/fence/index.md @@ -41,5 +41,5 @@ window.fence.reportEvent({ ## See also -- [Fenced frames](https://developers.google.com/privacy-sandbox/private-advertising/fenced-frame) on developers.google.com -- [The Privacy Sandbox](https://developers.google.com/privacy-sandbox) on developers.google.com +- [Fenced frames](https://privacysandbox.google.com/private-advertising/fenced-frame) on privacysandbox.google.com +- [The Privacy Sandbox](https://privacysandbox.google.com/) on privacysandbox.google.com diff --git a/files/en-us/web/api/window/fetch/index.md b/files/en-us/web/api/window/fetch/index.md index a5e9d8ed6852320..1f8611dce7158ed 100644 --- a/files/en-us/web/api/window/fetch/index.md +++ b/files/en-us/web/api/window/fetch/index.md @@ -16,7 +16,7 @@ A `fetch()` promise only rejects when the request fails, for example, because of A `fetch()` promise _does not_ reject if the server responds with HTTP status codes that indicate errors (`404`, `504`, etc.). Instead, a `then()` handler must check the {{domxref("Response.ok")}} and/or {{domxref("Response.status")}} properties. -The `fetch()` method is controlled by the `connect-src` directive of [Content Security Policy](/en-US/docs/Web/HTTP/Headers/Content-Security-Policy) rather than the directive of the resources it's retrieving. +The `fetch()` method is controlled by the `connect-src` directive of [Content Security Policy](/en-US/docs/Web/HTTP/Reference/Headers/Content-Security-Policy) rather than the directive of the resources it's retrieving. > [!NOTE] > The `fetch()` method's parameters are identical to those of the {{domxref("Request.Request","Request()")}} constructor. @@ -51,7 +51,7 @@ A {{jsxref("Promise")}} that resolves to a {{domxref("Response")}} object. - : The request was aborted due to a call to the {{domxref("AbortController")}} {{domxref("AbortController.abort", "abort()")}} method. - `NotAllowedError` {{domxref("DOMException")}} - - : Thrown if use of the [Topics API](/en-US/docs/Web/API/Topics_API) is specifically disallowed by a {{httpheader('Permissions-Policy/browsing-topics','browsing-topics')}} [Permissions Policy](/en-US/docs/Web/HTTP/Permissions_Policy), and a `fetch()` request was made with `browsingTopics: true`. + - : Thrown if use of the [Topics API](/en-US/docs/Web/API/Topics_API) is specifically disallowed by a {{httpheader('Permissions-Policy/browsing-topics','browsing-topics')}} [Permissions Policy](/en-US/docs/Web/HTTP/Guides/Permissions_Policy), and a `fetch()` request was made with `browsingTopics: true`. - {{jsxref("TypeError")}} - : Can occur for the following reasons: @@ -65,19 +65,19 @@ A {{jsxref("Promise")}} that resolves to a {{domxref("Response")}} object. <tbody> <tr> <td>Blocked by a permissions policy</td> - <td>Use of the <a href="/en-US/docs/Web/API/Attribution_Reporting_API">Attribution Reporting API</a> is blocked by a <a href="/en-US/docs/Web/HTTP/Headers/Permissions-Policy/attribution-reporting"><code>attribution-reporting</code></a> {{httpheader("Permissions-Policy")}}, and a <code>fetch()</code> request was made with <code>attributionReporting</code> specified.</td> + <td>Use of the <a href="/en-US/docs/Web/API/Attribution_Reporting_API">Attribution Reporting API</a> is blocked by a <a href="/en-US/docs/Web/HTTP/Reference/Headers/Permissions-Policy/attribution-reporting"><code>attribution-reporting</code></a> {{httpheader("Permissions-Policy")}}, and a <code>fetch()</code> request was made with <code>attributionReporting</code> specified.</td> </tr> <tr> <td>Invalid header name.</td> <td> <!-- cSpell:ignore ontent --> - <pre> + <pre class="brush: js"> // space in "C ontent-Type" const headers = { - 'C ontent-Type': 'text/xml', - 'Breaking-Bad': '<3', + "C ontent-Type": "text/xml", + "Breaking-Bad": "<3", }; -fetch('https://example.com/', { headers }); +fetch("https://example.com/", { headers }); </pre> </td> </tr> @@ -86,12 +86,12 @@ fetch('https://example.com/', { headers }); Invalid header value. The header object must contain exactly two elements. </td> <td> - <pre> + <pre class="brush: js"> const headers = [ - ['Content-Type', 'text/html', 'extra'], - ['Accept'], + ["Content-Type", "text/html", "extra"], + ["Accept"], ]; -fetch('https://example.com/', { headers }); +fetch("https://example.com/", { headers }); </pre> </td> </tr> @@ -100,30 +100,30 @@ fetch('https://example.com/', { headers }); Invalid URL or scheme, or using a scheme that fetch does not support, or using a scheme that is not supported for a particular request mode. </td> <td> - <pre> -fetch('blob://example.com/', { mode: 'cors' }); + <pre class="brush: js"> +fetch("blob://example.com/", { mode: "cors" }); </pre> </td> </tr> <td>URL includes credentials.</td> <td> - <pre> -fetch('https://user:password@example.com/'); + <pre class="brush: js"> +fetch("https://user:password@example.com/"); </pre> </td> <tr> <td>Invalid referrer URL.</td> <td> - <pre> -fetch('https://example.com/', { referrer: './abc\u0000df' }); + <pre class="brush: js"> +fetch("https://example.com/", { referrer: "./abc\u0000df" }); </pre> </td> </tr> <tr> <td>Invalid modes (<code>navigate</code> and <code>websocket</code>).</td> <td> - <pre> -fetch('https://example.com/', { mode: 'navigate' }); + <pre class="brush: js"> +fetch("https://example.com/", { mode: "navigate" }); </pre> </td> </tr> @@ -132,10 +132,10 @@ fetch('https://example.com/', { mode: 'navigate' }); If the request cache mode is "only-if-cached" and the request mode is other than "same-origin". </td> <td> - <pre> -fetch('https://example.com/', { - cache: 'only-if-cached', - mode: 'no-cors', + <pre class="brush: js"> +fetch("https://example.com/", { + cache: "only-if-cached", + mode: "no-cors", }); </pre> </td> @@ -143,36 +143,36 @@ fetch('https://example.com/', { <tr> <td> If the request method is an invalid name token or one of the forbidden headers - (<code>'CONNECT'</code>, <code>'TRACE'</code> or <code>'TRACK'</code>). + (<code>CONNECT</code>, <code>TRACE</code> or <code>TRACK</code>). </td> <td> - <pre> -fetch('https://example.com/', { method: 'CONNECT' }); + <pre class="brush: js"> +fetch("https://example.com/", { method: "CONNECT" }); </pre> </td> </tr> <tr> <td> If the request mode is "no-cors" and the request method is not a CORS-safe-listed method - (<code>'GET'</code>, <code>'HEAD'</code>, or <code>'POST'</code>). + (<code>GET</code>, <code>HEAD</code>, or <code>POST</code>). </td> <td> - <pre> -fetch('https://example.com/', { - method: 'CONNECT', - mode: 'no-cors', + <pre class="brush: js"> +fetch("https://example.com/", { + method: "CONNECT", + mode: "no-cors", }); </pre> </td> </tr> <tr> <td> - If the request method is <code>'GET'</code> or <code>'HEAD'</code> and the body is non-null or not undefined. + If the request method is <code>GET</code> or <code>HEAD</code> and the body is non-null or not undefined. </td> <td> - <pre> -fetch('https://example.com/', { - method: 'GET', + <pre class="brush: js"> +fetch("https://example.com/", { + method: "GET", body: new FormData(), }); </pre> @@ -231,7 +231,7 @@ const options = { const req = new Request("flowers.jpg", options); fetch(req).then((response) => { - // ... + // … }); ``` @@ -268,5 +268,5 @@ The [Using fetch](/en-US/docs/Web/API/Fetch_API/Using_Fetch) article provides mo - {{domxref("WorkerGlobalScope.fetch()")}} - [Fetch API](/en-US/docs/Web/API/Fetch_API) - [ServiceWorker API](/en-US/docs/Web/API/Service_Worker_API) -- [HTTP access control (CORS)](/en-US/docs/Web/HTTP/CORS) +- [HTTP access control (CORS)](/en-US/docs/Web/HTTP/Guides/CORS) - [HTTP](/en-US/docs/Web/HTTP) diff --git a/files/en-us/web/api/window/fetchlater/index.md b/files/en-us/web/api/window/fetchlater/index.md new file mode 100644 index 000000000000000..140b364e8fe8eb6 --- /dev/null +++ b/files/en-us/web/api/window/fetchlater/index.md @@ -0,0 +1,187 @@ +--- +title: "Window: fetchLater() method" +short-title: fetchLater() +slug: Web/API/Window/fetchLater +page-type: web-api-instance-method +status: + - experimental +browser-compat: api.Window.fetchLater +--- + +{{APIRef("fetchLater API")}}{{SeeCompatTable}} + +The **`fetchLater()`** method of the {{domxref("Window")}} interface creates a deferred fetch. + +A `fetchLater()` request is sent once the page is navigated away from (it is destroyed or enters the [bfcache](/en-US/docs/Glossary/bfcache)), or after a provided `activateAfter` timeout — whichever comes first. + +The `fetchLater()` methods returns a {{domxref("FetchLaterResult")}} object containing a single `activated` value stating whether the request has been sent yet. Note the method does not return the result of the actual fetch when that happens (since it is often sent after the document has been destroyed) and the whole response of the fetch, including body and headers, is ignored. + +Requests whose body is a {{domxref("ReadableStream")}} cannot be deferred. + +The `fetchLater()` method is controlled by the `connect-src` [Content Security Policy](/en-US/docs/Web/HTTP/Reference/Headers/Content-Security-Policy) directive rather than the directive of the retrieved resources. + +## Syntax + +```js-nolint +fetchLater(resource) +fetchLater(resource, options) +``` + +### Parameters + +The `fetchLater()` method takes all the same parameters as {{domxref("Window.fetch", "fetch()")}}, but with one additional `activateAfter` option. + +- `resource` + + - : This defines the resource that you wish to fetch. Identical to {{domxref("Window.fetch", "fetch()")}}, this can either be: + + - A string or any other object with a {{Glossary("stringifier")}} — including a {{domxref("URL")}} object — that provides the URL of the resource you want to fetch. The URL may be relative to the base URL, which is the document's {{domxref("Node.baseURI", "baseURI")}} in a window context. + - A {{domxref("Request")}} object. + +- `options` {{optional_inline}} + + - : A {{domxref("DeferredRequestInit")}} object containing any custom settings that you want to apply to the request, including an `activateAfter` timeout value that defines how long the result should be deferred for before sending. + +### Exceptions + +The [same exceptions for `fetch()`](/en-US/docs/Web/API/Window/fetch#exceptions) can be raised for `fetchLater()`, along with the following additional exceptions: + +- `QuotaExceededError` {{domxref("DOMException")}} + + - : Use of this feature was blocked due to exceeding the available quota. See [`fetchLater()` quotas](/en-US/docs/Web/API/fetchLater_API/fetchLater_quotas) for more details. Callers of `fetchLater()` should be defensive and catch `QuotaExceededError` errors in almost all cases, especially if they are embedding third-party JavaScript. + +- `RangeError` {{domxref("DOMException")}} + + - : Thrown when a negative `activateAfter` value is specified. + +- `TypeError` {{domxref("DOMException")}} + - : In addition to the reasons for `fetch()`, this exception will also be thrown for a {{domxref("ReadableStream")}} request (which cannot be deferred) or for use of untrustworthy URLs (such as `http://`). + +### Return value + +A {{domxref("FetchLaterResult")}} containing an `activated` boolean property indicating if the request has been sent yet. + +> [!NOTE] +> Once the fetch request is sent, its response — including the body and headers — is not made available and will be ignored. + +## Examples + +The [`fetchLater()` quotas](/en-US/docs/Web/API/fetchLater_API/fetchLater_quotas) article provides examples of how the quotas are applied. + +### Defer a `GET` request until the page is navigated away from or closed + +```js +fetchLater("/send_beacon"); +``` + +### Defer a `POST` request for around one minute + +In this example we create a {{domxref("Request")}}, and provide an `activateAfter` value to delay sending the request for 60,000 milliseconds (or one minute): + +```js +fetchLater("/send_beacon", { + method: "POST", + body: getBeaconData(), + activateAfter: 60000, // 1 minute +}); +``` + +> [!NOTE] +> The actual sending time is unknown, as the browser may wait for a longer or shorter period of time, for example to optimize batching of deferred fetches. + +### Defer a `POST` request for around one minute with a try/catch + +The same example as above, but the best practice is to enclose this in a try/catch: + +```js +try { + fetchLater("/send_beacon", { + method: "POST", + body: getBeaconData(), + activateAfter: 60000, // 1 minute + }); +} catch (e) { + if (e instanceof QuotaExceededError) { + // Handle the quota error + } else { + // Handle other errors + } +} +``` + +### Defer a `POST` request for around one minute and create a function to check if sent + +```js +const result = fetchLater("https://report.example.com", { + method: "POST", + body: JSON.stringify(myReport), + activateAfter: 60000 /* 1 minute */, +}); + +function checkIfFetched() { + return result.activated; +} +``` + +### Update a pending request + +In this example we use an {{domxref("AbortController")}} to cancel and recreate the request: + +```js +let beaconResult = null; +let beaconAbort = null; + +function updateBeacon(data) { + const pending = !beaconResult || !beaconResult.activated; + if (pending && beaconAbort) { + beaconAbort.abort(); + } + + createBeacon(data); +} + +function createBeacon(data) { + if (beaconResult && !beaconResult.activated) { + // Avoid creating duplicated beacon if the previous one is still pending. + return; + } + + beaconAbort = new AbortController(); + beaconResult = fetchLater({ + url: data, + signal: beaconAbort.signal, + }); +} +``` + +### Invalid examples + +Any of the following calls to `fetchLater()` would throw: + +```js +// Only potentially trustworthy URLs are supported +fetchLater("http://untrusted.example.com"); + +// The length of the deferred request has to be known +fetchLater("https://origin.example.com", { body: someDynamicStream }); + +// Deferred fetching only works on active windows +const detachedWindow = iframe.contentWindow; +iframe.remove(); +detachedWindow.fetchLater("https://origin.example.com"); +``` + +## Specifications + +{{Specifications}} + +## Browser compatibility + +{{Compat}} + +## See also + +- [`fetchLater()` API](/en-US/docs/Web/API/fetchLater_API) +- [`fetchLater()` quotas](/en-US/docs/Web/API/fetchLater_API/fetchLater_quotas) +- {{domxref("FetchLaterResult")}} +- [Fetch API](/en-US/docs/Web/API/Fetch_API) diff --git a/files/en-us/web/api/window/focus_event/index.md b/files/en-us/web/api/window/focus_event/index.md index 2e52fab0624979f..fd16ef50a34cde8 100644 --- a/files/en-us/web/api/window/focus_event/index.md +++ b/files/en-us/web/api/window/focus_event/index.md @@ -18,10 +18,10 @@ This event is not cancelable and does not bubble. Use the event name in methods like {{domxref("EventTarget.addEventListener", "addEventListener()")}}, or set an event handler property. -```js -addEventListener("focus", (event) => {}); +```js-nolint +addEventListener("focus", (event) => { }) -onfocus = (event) => {}; +onfocus = (event) => { } ``` ## Event type diff --git a/files/en-us/web/api/window/forward/index.md b/files/en-us/web/api/window/forward/index.md deleted file mode 100644 index 59b4814def82ea0..000000000000000 --- a/files/en-us/web/api/window/forward/index.md +++ /dev/null @@ -1,53 +0,0 @@ ---- -title: "Window: forward() method" -short-title: forward() -slug: Web/API/Window/forward -page-type: web-api-instance-method -status: - - deprecated - - non-standard ---- - -{{APIRef}}{{Non-standard_header}} {{deprecated_header}} - -Moves the window one document forward in history. This was a Firefox-specific method and was removed in Firefox 31. - -> [!NOTE] -> Use the standard {{domxref("History.forward", "history.forward()")}} method instead. - -## Syntax - -```js-nolint -forward() -``` - -### Parameters - -None. - -### Return value - -None ({{jsxref("undefined")}}). - -## Examples - -```js -function goForward() { - if (canGoForward) { - window.forward(); - } -} -``` - -## Specifications - -This is not part of any specification. - -## Browser compatibility - -This non-standard method was only implemented in Firefox, and was removed in Firefox 31. - -## See also - -- {{domxref("History.back()")}} -- {{domxref("History.forward()")}} diff --git a/files/en-us/web/api/window/gamepadconnected_event/index.md b/files/en-us/web/api/window/gamepadconnected_event/index.md index dc15b1425c401a3..0272d6d3a6a3e54 100644 --- a/files/en-us/web/api/window/gamepadconnected_event/index.md +++ b/files/en-us/web/api/window/gamepadconnected_event/index.md @@ -10,10 +10,20 @@ browser-compat: api.Window.gamepadconnected_event The `gamepadconnected` event is fired when the browser detects that a gamepad has been connected or the first time a button/axis of the gamepad is used. -The event will not fire if disallowed by the document's {{httpheader('Permissions-Policy/gamepad','gamepad')}} [Permissions Policy](/en-US/docs/Web/HTTP/Permissions_Policy). +The event will not fire if disallowed by the document's {{httpheader('Permissions-Policy/gamepad','gamepad')}} [Permissions Policy](/en-US/docs/Web/HTTP/Guides/Permissions_Policy). This event is not cancelable and does not bubble. +## Syntax + +Use the event name in methods like {{domxref("EventTarget.addEventListener", "addEventListener()")}}, or set an event handler property. + +```js-nolint +addEventListener("gamepadconnected", (event) => { }) + +ongamepadconnected = (event) => { } +``` + ## Examples To be informed when a gamepad is connected, you can add a handler to the window using {{domxref("EventTarget.addEventListener", "addEventListener()")}}, like this: diff --git a/files/en-us/web/api/window/gamepaddisconnected_event/index.md b/files/en-us/web/api/window/gamepaddisconnected_event/index.md index 59152d9cec691b8..3901bc764539744 100644 --- a/files/en-us/web/api/window/gamepaddisconnected_event/index.md +++ b/files/en-us/web/api/window/gamepaddisconnected_event/index.md @@ -10,10 +10,20 @@ browser-compat: api.Window.gamepaddisconnected_event The `gamepaddisconnected` event is fired when the browser detects that a gamepad has been disconnected. -The event will not fire if disallowed by the document's {{httpheader('Permissions-Policy/gamepad','gamepad')}} [Permissions Policy](/en-US/docs/Web/HTTP/Permissions_Policy). +The event will not fire if disallowed by the document's {{httpheader('Permissions-Policy/gamepad','gamepad')}} [Permissions Policy](/en-US/docs/Web/HTTP/Guides/Permissions_Policy). This event is not cancelable and does not bubble. +## Syntax + +Use the event name in methods like {{domxref("EventTarget.addEventListener", "addEventListener()")}}, or set an event handler property. + +```js-nolint +addEventListener("gamepaddisconnected", (event) => { }) + +ongamepaddisconnected = (event) => { } +``` + ## Examples To be informed when a gamepad is disconnected, you can add a handler to the window using {{domxref("EventTarget.addEventListener", "addEventListener()")}}, like this: diff --git a/files/en-us/web/api/window/getcomputedstyle/index.md b/files/en-us/web/api/window/getcomputedstyle/index.md index 0532130522f6bd1..c216f6cc5e908f3 100644 --- a/files/en-us/web/api/window/getcomputedstyle/index.md +++ b/files/en-us/web/api/window/getcomputedstyle/index.md @@ -13,8 +13,7 @@ The containing the values of all CSS properties of an element, after applying active stylesheets and resolving any basic computation those values may contain. -Individual CSS property values are accessed through APIs provided by the object, or by -indexing with CSS property names. +Individual CSS property values are accessed through APIs provided by the returned {{DOMxRef("CSSStyleDeclaration")}} object, or by indexing with CSS property names. The values returned by `getComputedStyle` are [resolved values](/en-US/docs/Web/CSS/CSS_cascade/Value_processing#resolved_value). ## Syntax @@ -33,8 +32,20 @@ getComputedStyle(element, pseudoElt) ### Return value -A _live_ {{DOMxRef("CSSStyleDeclaration")}} -object, which updates automatically when the element's styles are changed. +A _live_ {{DOMxRef("CSSStyleDeclaration")}} object, which updates automatically when the element's styles are changed. + +Note that: + +- The returned {{DOMxRef("CSSStyleDeclaration")}} object contains active values for CSS property _longhand_ names as well as shorthand names. For example, the returned object contains entries for {{cssxref("border-bottom-width")}} in addition to the {{cssxref("border-width")}} and {{cssxref("border")}} [shorthand property names](/en-US/docs/Web/CSS/CSS_cascade/Shorthand_properties). +- Returned values are sometimes deliberately inaccurate. To avoid the "CSS History Leak" security issue, browsers may lie about the computed styles for a visited link, returning values as if the user never visited the linked URL. See [Plugging the CSS history leak](https://blog.mozilla.org/security/2010/03/31/plugging-the-css-history-leak/) and [Privacy-related changes coming to CSS `:visited`](https://hacks.mozilla.org/2010/03/privacy-related-changes-coming-to-css-vistited/) for examples of how this is implemented. +- During [CSS transitions](/en-US/docs/Web/CSS/CSS_transitions), `getComputedStyle` returns the original property value in Firefox, but the final property value in WebKit. +- In Firefox, properties with the value `auto` return the used value, not the value `auto`. So if you apply `top:auto` and `bottom:0` on an element with `height:30px` and a containing block of `height:100px`, Firefox's computed style for `top` returns `70px`, as 100 − 30 = 70. +- For compatibility reasons, serialized color values are expressed as [`rgb()`](/en-US/docs/Web/CSS/color_value/rgb) colors if the alpha channel value is exactly `1`, and `rgba()` colors otherwise. In both cases, legacy syntax is used, with commas as separators (for example `rgb(255, 0, 0)`). + +The returned object is the same {{DOMxRef("CSSStyleDeclaration")}} type as the object returned from the element's {{DOMxRef("HTMLElement/style", "style")}} property. However, the two objects have different purposes: + +- The object from `getComputedStyle` is read-only, and should be used to inspect the element's style — including those set by a `<style>` element or an external stylesheet. +- The `element.style` object should be used to **set** styles on that element, or inspect styles directly added to it from JavaScript manipulation or the global `style` attribute. ### Exceptions @@ -46,23 +57,25 @@ object, which updates automatically when the element's styles are changed. > [!NOTE] > Valid pseudo-element selector refers to syntactic - > validity, e.g. `::unsupported` is considered valid, even though the + > validity, e.g., `::unsupported` is considered valid, even though the > pseudo-element itself is not supported. Additionally, the latest W3 standard [explicitly supports](https://www.w3.org/TR/cssom-1/#dom-window-getcomputedstyle) only `::before` and `::after`, while the CSS > WG draft [does not restrict this value](https://drafts.csswg.org/cssom/#dom-window-getcomputedstyle). Browser compatibility may vary. ## Examples +### Retrieving computed styles + In this example we style a {{HTMLElement("p")}} element, then retrieve those styles using `getComputedStyle()`, and print them into the text content of the `<p>`. -### HTML +#### HTML ```html <p>Hello</p> ``` -### CSS +#### CSS ```css p { @@ -76,7 +89,7 @@ p { } ``` -### JavaScript +#### JavaScript ```js const para = document.querySelector("p"); @@ -88,36 +101,11 @@ para.textContent = )}.`; ``` -### Result - -{{EmbedLiveSample('Examples', '100%', '240px')}} +#### Result -## Description +{{EmbedLiveSample('retrieving_computed_styles', '100%', '240px')}} -The returned object is the same {{DOMxRef("CSSStyleDeclaration")}} type as the object -returned from the element's {{DOMxRef("HTMLElement/style", "style")}} property. However, -the two objects have different purposes: - -- The object from `getComputedStyle` is read-only, and should be used to - inspect the element's style — including those set by a `<style>` - element or an external stylesheet. -- The `element.style` object should be used to - **set** styles on that element, or inspect styles directly added to it - from JavaScript manipulation or the global `style` attribute. - -The first argument must be an {{domxref("Element")}}. Non-elements, like a -{{DOMxRef("Text")}} node, will throw an error. - -## defaultView - -In many code samples, `getComputedStyle` is used from the -{{DOMxRef("document.defaultView")}} object. In nearly all cases, this is needless, as -`getComputedStyle` exists on the `window` object as well. It's -likely the `defaultView` pattern was a combination of folks not wanting to -write a testing spec for `window` and making an API that was also usable in -Java. - -## Use with pseudo-elements +### Use with pseudo-elements `getComputedStyle` can pull style info from pseudo-elements (such as `::after`, `::before`, `::marker`, @@ -140,42 +128,6 @@ Java. </script> ``` -## Notes - -- The returned {{DOMxRef("CSSStyleDeclaration")}} object contains active values for - CSS property **_longhand_** names as well as shorthand names. For example, the returned object contains entries for - {{cssxref("border-bottom-width")}} in addition to the {{cssxref("border-width")}} and - {{cssxref("border")}} [shorthand property names](/en-US/docs/Web/CSS/CSS_cascade/Shorthand_properties). You can query values with longhand names like - {{cssxref("font-size")}} as well as shorthand names like {{cssxref("font")}}. -- CSS property values may be accessed using the - {{DOMxRef("CSSStyleDeclaration.getPropertyValue", "getPropertyValue(propName)")}} method or by indexing directly into the object - using array or [dot notation](/en-US/docs/Learn_web_development/Core/Scripting/Object_basics#dot_notation) such as `obj['z-index']` or `obj.zIndex`. -- The values returned by `getComputedStyle` are [resolved values](/en-US/docs/Web/CSS/resolved_value). - These are usually the same as CSS 2.1's - [computed values](/en-US/docs/Web/CSS/CSS_cascade/computed_value), but for some older properties - like `width`, `height`, or `padding`, they are - instead the same as [used values](/en-US/docs/Web/CSS/CSS_cascade/used_value). Originally, CSS - 2.0 defined the _computed values_ as the "ready to be used" final values of - properties after cascading and inheritance, but CSS 2.1 redefined them as pre-layout, - and _used values_ as post-layout. For CSS 2.0 properties, - `getComputedStyle` returns the old meaning of computed values, now called - **used values**. An example difference between pre- and post-layout - values includes the resolution of percentages for `width` or - `height`, as those will be replaced by their pixel equivalent only for - _used values_. -- Returned values are sometimes deliberately inaccurate. To avoid the "CSS History - Leak" security issue, browsers may lie about the computed styles for a visited link, - returning values as if the user never visited the linked URL. See [Plugging the CSS history leak](https://blog.mozilla.org/security/2010/03/31/plugging-the-css-history-leak/) and [Privacy-related changes coming to CSS `:visited`](https://hacks.mozilla.org/2010/03/privacy-related-changes-coming-to-css-vistited/) for examples of how this is implemented. -- During [CSS transitions](/en-US/docs/Web/CSS/CSS_transitions), - `getComputedStyle` returns the original property value in Firefox, but the - final property value in WebKit. -- In Firefox, properties with the value `auto` return the used value, not - the value `auto`. So if you apply `top:auto` and - `bottom:0` on an element with `height:30px` and a containing - block of `height:100px`, Firefox's computed style for `top` - returns `70px`, as 100 − 30 = 70. -- For compatibility reasons, serialized color values are expressed as [`rgb()`](/en-US/docs/Web/CSS/color_value/rgb) colors if the alpha channel value is exactly `1`, and `rgba()` colors otherwise. In both cases, legacy syntax is used, with commas as separators (for example `rgb(255, 0, 0)`). - ## Specifications {{Specifications}} @@ -188,4 +140,5 @@ Java. - {{DOMxRef("window.getDefaultComputedStyle()")}} - {{DOMxRef("CSSStyleDeclaration.getPropertyValue", "getPropertyValue()")}} -- [Resolved value](/en-US/docs/Web/CSS/resolved_value) +- {{domxref("Element.computedStyleMap()")}} +- [Resolved value](/en-US/docs/Web/CSS/CSS_cascade/Value_processing#resolved_value) diff --git a/files/en-us/web/api/window/getdefaultcomputedstyle/index.md b/files/en-us/web/api/window/getdefaultcomputedstyle/index.md index ee58e7ca9fa4dec..7693679edd52091 100644 --- a/files/en-us/web/api/window/getdefaultcomputedstyle/index.md +++ b/files/en-us/web/api/window/getdefaultcomputedstyle/index.md @@ -10,7 +10,7 @@ browser-compat: api.Window.getDefaultComputedStyle {{APIRef("CSSOM")}}{{Non-standard_Header}} -The **`getDefaultComputedStyle()`** method gives the default [computed values](/en-US/docs/Web/CSS/CSS_cascade/computed_value) of all the CSS +The **`getDefaultComputedStyle()`** method gives the default [computed values](/en-US/docs/Web/CSS/CSS_cascade/Value_processing#computed_value) of all the CSS properties of an element, ignoring author styling. That is, only user-agent and user styles are taken into account. diff --git a/files/en-us/web/api/window/getscreendetails/index.md b/files/en-us/web/api/window/getscreendetails/index.md index b492949f3b20d4e..da0011687da6f9f 100644 --- a/files/en-us/web/api/window/getscreendetails/index.md +++ b/files/en-us/web/api/window/getscreendetails/index.md @@ -30,7 +30,7 @@ A {{jsxref("Promise")}} that fulfills with a {{domxref("ScreenDetails")}} object ### Exceptions - `NotAllowedError` {{domxref("DOMException")}} - - : Thrown if a {{httpheader("Permissions-Policy/window-management", "window-management")}} [Permissions-Policy](/en-US/docs/Web/HTTP/Permissions_Policy) is set that blocks use of the [Window Management API](/en-US/docs/Web/API/Window_Management_API), or if the user has explicitly denied the browser's permission request to use the API. + - : Thrown if a {{httpheader("Permissions-Policy/window-management", "window-management")}} [Permissions-Policy](/en-US/docs/Web/HTTP/Guides/Permissions_Policy) is set that blocks use of the [Window Management API](/en-US/docs/Web/API/Window_Management_API), or if the user has explicitly denied the browser's permission request to use the API. ## Examples diff --git a/files/en-us/web/api/window/hashchange_event/index.md b/files/en-us/web/api/window/hashchange_event/index.md index 76650c5abd1d579..4575ded1ede6607 100644 --- a/files/en-us/web/api/window/hashchange_event/index.md +++ b/files/en-us/web/api/window/hashchange_event/index.md @@ -10,13 +10,16 @@ browser-compat: api.Window.hashchange_event The **`hashchange`** event is fired when the fragment identifier of the URL has changed (the part of the URL beginning with and following the `#` symbol). +This event does not fire when the hash is modified using {{domxref("history.pushState()")}} or {{domxref("history.replaceState()")}}. + ## Syntax Use the event name in methods like {{domxref("EventTarget.addEventListener", "addEventListener()")}}, or set an event handler property. -```js -addEventListener("hashchange", (event) => {}); -onhashchange = (event) => {}; +```js-nolint +addEventListener("hashchange", (event) => { }) + +onhashchange = (event) => { } ``` ## Event type diff --git a/files/en-us/web/api/window/index.md b/files/en-us/web/api/window/index.md index 4b4c1c14d5cc723..a39619b31e473c6 100644 --- a/files/en-us/web/api/window/index.md +++ b/files/en-us/web/api/window/index.md @@ -91,7 +91,7 @@ Note that properties which are objects (e.g., for overriding the prototype of bu - : Returns a reference to the window that opened this current window. - {{domxref("Window.origin")}} {{ReadOnlyInline}} - : Returns the global object's origin, serialized as a string. -- {{domxref("Window.originAgentCluster")}} {{ReadOnlyInline}} {{Experimental_Inline}} +- {{domxref("Window.originAgentCluster")}} {{ReadOnlyInline}} - : Returns `true` if this window belongs to an origin-keyed agent cluster. - {{domxref("Window.outerHeight")}} {{ReadOnlyInline}} - : Gets the height of the outside of the browser window. @@ -189,6 +189,8 @@ _This interface inherits methods from the {{domxref("EventTarget")}} interface._ - : Writes a message to the console. - {{domxref("Window.fetch()")}} - : Starts the process of fetching a resource from the network. +- {{domxref("Window.fetchLater()")}} {{experimental_inline}} + - : Creates a deferred fetch, which is sent once the page is navigated away from (it is destroyed or enters the [bfcache](/en-US/docs/Glossary/bfcache)), or after a provided `activateAfter` timeout — whichever comes first. - {{domxref("Window.find()")}} {{Non-standard_Inline}} - : Searches for a given string in a window. - {{domxref("Window.focus()")}} @@ -258,14 +260,10 @@ _This interface inherits methods from the {{domxref("EventTarget")}} interface._ ### Deprecated methods -- {{domxref("Window.back()")}} {{Non-standard_Inline}} {{Deprecated_Inline}} - - : Moves back one in the window history. This method is deprecated; you should instead use {{domxref("History.back", "history.back()")}}. - {{domxref("Window.captureEvents()")}} {{Deprecated_Inline}} - : Registers the window to capture all events of the specified type. - {{domxref("Window.clearImmediate()")}} {{Non-standard_Inline}} {{Deprecated_Inline}} - : Cancels the repeated execution set using `setImmediate()`. -- {{domxref("Window.forward()")}} {{Non-standard_Inline}} {{Deprecated_Inline}} - - : Moves the window one document forward in the history. This method is deprecated; you should instead use {{domxref("History.forward", "history.forward()")}}. - {{domxref("Window.releaseEvents()")}} {{Deprecated_Inline}} - : Releases the window from trapping events of a specific type. - {{domxref("Window.requestFileSystem()")}} {{Non-standard_Inline}} {{Deprecated_Inline}} @@ -274,8 +272,6 @@ _This interface inherits methods from the {{domxref("EventTarget")}} interface._ - : Executes a function after the browser has finished other heavy tasks. - {{domxref("Window.setResizable()")}} {{Non-standard_Inline}} {{deprecated_inline}} - : Does nothing (no-op). Kept for backward compatibility with Netscape 4.x. -- {{domxref("Window.showModalDialog()")}} {{Non-standard_Inline}} {{Deprecated_Inline}} - - : Displays a modal dialog. - {{domxref("Window.webkitConvertPointFromNodeToPage()")}} {{Non-standard_Inline}} {{Deprecated_Inline}} - : Transforms a {{domxref("WebKitPoint")}} from the node's coordinate system to the page's coordinate system. - {{domxref("Window.webkitConvertPointFromPageToNode()")}} {{Non-standard_Inline}} {{Deprecated_Inline}} @@ -294,18 +290,6 @@ Listen to these events using [`addEventListener()`](/en-US/docs/Web/API/EventTar - {{domxref("Window/storage_event", "storage")}} - : Fired when a storage area (`localStorage` or `sessionStorage`) has been modified in the context of another document. -### Clipboard events - -- {{domxref("Window/copy_event", "copy")}} - - : Fired when the user initiates a copy action through the browser's user interface. - Also available via the {{domxref("HTMLElement/copy_event", "oncopy")}} property. -- {{domxref("Window/cut_event", "cut")}} - - : Fired when the user initiates a cut action through the browser's user interface. - Also available via the {{domxref("HTMLElement/cut_event", "oncut")}} property. -- {{domxref("Window/paste_event", "paste")}} - - : Fired when the user initiates a paste action through the browser's user interface. - Also available via the {{domxref("HTMLElement/paste_event", "onpaste")}} property. - ### Connection events - {{domxref("Window/offline_event", "offline")}} @@ -393,7 +377,7 @@ Listen to these events using [`addEventListener()`](/en-US/docs/Web/API/EventTar - {{domxref("Window/scrollsnapchange_event", "scrollsnapchange")}} {{experimental_inline}} - : Fired on the scroll container at the end of a scrolling operation when a new scroll snap target has been selected. - {{domxref("Window/scrollsnapchanging_event", "scrollsnapchanging")}} {{experimental_inline}} - - : Fired on the scroll container when the browser determines a new scroll snap target is pending, i.e. it will be selected when the current scroll gesture ends. + - : Fired on the scroll container when the browser determines a new scroll snap target is pending, i.e., it will be selected when the current scroll gesture ends. ### Deprecated events @@ -408,7 +392,7 @@ Listen to these events using [`addEventListener()`](/en-US/docs/Web/API/EventTar - {{domxref("Window/vrdisplaydeactivate_event", "vrdisplaydeactivate")}} {{Deprecated_Inline}} {{Non-standard_Inline}} - : Fired when a display can no longer be presented to. - {{domxref("Window/vrdisplaypresentchange_event", "vrdisplaypresentchange")}} {{Deprecated_Inline}} {{Non-standard_Inline}} - - : Fired when the presenting state of a VR device changes — i.e. goes from presenting to not presenting, or vice versa. + - : Fired when the presenting state of a VR device changes — i.e., goes from presenting to not presenting, or vice versa. ### Bubbled events diff --git a/files/en-us/web/api/window/innerheight/index.md b/files/en-us/web/api/window/innerheight/index.md index b9c24ec5afa45d2..f43d53b30dade80 100644 --- a/files/en-us/web/api/window/innerheight/index.md +++ b/files/en-us/web/api/window/innerheight/index.md @@ -52,7 +52,7 @@ console.log(top.innerHeight); To change the size of a window, see {{domxref("window.resizeBy()")}} and {{domxref("window.resizeTo()")}}. -To get the outer height of a window, i.e. the height of the whole browser window, see +To get the outer height of a window, i.e., the height of the whole browser window, see {{domxref("window.outerHeight")}}. ### Graphical example diff --git a/files/en-us/web/api/window/languagechange_event/index.md b/files/en-us/web/api/window/languagechange_event/index.md index f905d5c51e8c235..9e7243df6ae3a2f 100644 --- a/files/en-us/web/api/window/languagechange_event/index.md +++ b/files/en-us/web/api/window/languagechange_event/index.md @@ -14,9 +14,10 @@ The **`languagechange`** event is fired at the global scope object when the user Use the event name in methods like {{domxref("EventTarget.addEventListener", "addEventListener()")}}, or set an event handler property. -```js -addEventListener("languagechange", (event) => {}); -onlanguagechange = (event) => {}; +```js-nolint +addEventListener("languagechange", (event) => { }) + +onlanguagechange = (event) => { } ``` ## Event type diff --git a/files/en-us/web/api/window/load_event/index.md b/files/en-us/web/api/window/load_event/index.md index 3ee898fec35725d..6299497251b145d 100644 --- a/files/en-us/web/api/window/load_event/index.md +++ b/files/en-us/web/api/window/load_event/index.md @@ -22,10 +22,10 @@ This event is not cancelable and does not bubble. Use the event name in methods like {{domxref("EventTarget.addEventListener", "addEventListener()")}}, or set an event handler property. -```js -addEventListener("load", (event) => {}); +```js-nolint +addEventListener("load", (event) => { }) -onload = (event) => {}; +onload = (event) => { } ``` ## Event type diff --git a/files/en-us/web/api/window/message_event/index.md b/files/en-us/web/api/window/message_event/index.md index 6531fb0ecff8e8d..e62d415f7bcb208 100644 --- a/files/en-us/web/api/window/message_event/index.md +++ b/files/en-us/web/api/window/message_event/index.md @@ -16,10 +16,10 @@ This event is not cancellable and does not bubble. Use the event name in methods like {{domxref("EventTarget.addEventListener", "addEventListener()")}}, or set an event handler property. -```js -addEventListener("message", (event) => {}); +```js-nolint +addEventListener("message", (event) => { }) -onmessage = (event) => {}; +onmessage = (event) => { } ``` ## Event type @@ -41,11 +41,11 @@ _This interface also inherits properties from its parent, {{domxref("Event")}}._ - {{domxref("MessageEvent.source")}} {{ReadOnlyInline}} - : A `MessageEventSource` (which can be a {{glossary("WindowProxy")}}, {{domxref("MessagePort")}}, or {{domxref("ServiceWorker")}} object) representing the message emitter. - {{domxref("MessageEvent.ports")}} {{ReadOnlyInline}} - - : An array of {{domxref("MessagePort")}} objects representing the ports associated with the channel the message is being sent through (where appropriate, e.g. in channel messaging or when sending a message to a shared worker). + - : An array of {{domxref("MessagePort")}} objects representing the ports associated with the channel the message is being sent through (where appropriate, e.g., in channel messaging or when sending a message to a shared worker). ## Examples -Suppose a script sends a message to a different browsing context, such as another [`<iframe>`](/en-US/docs/Web/HTML/Element/iframe), using code like this: +Suppose a script sends a message to a different browsing context, such as another [`<iframe>`](/en-US/docs/Web/HTML/Reference/Elements/iframe), using code like this: ```js const targetFrame = window.top.frames[1]; diff --git a/files/en-us/web/api/window/messageerror_event/index.md b/files/en-us/web/api/window/messageerror_event/index.md index c74af674b2fbeda..26ed44686796f61 100644 --- a/files/en-us/web/api/window/messageerror_event/index.md +++ b/files/en-us/web/api/window/messageerror_event/index.md @@ -16,10 +16,10 @@ This event is not cancellable and does not bubble. Use the event name in methods like {{domxref("EventTarget.addEventListener", "addEventListener()")}}, or set an event handler property. -```js -addEventListener("messageerror", (event) => {}); +```js-nolint +addEventListener("messageerror", (event) => { }) -onmessageerror = (event) => {}; +onmessageerror = (event) => { } ``` ## Event type @@ -41,7 +41,7 @@ _This interface also inherits properties from its parent, {{domxref("Event")}}._ - {{domxref("MessageEvent.source")}} {{ReadOnlyInline}} - : A `MessageEventSource` (which can be a {{glossary("WindowProxy")}}, {{domxref("MessagePort")}}, or {{domxref("ServiceWorker")}} object) representing the message emitter. - {{domxref("MessageEvent.ports")}} {{ReadOnlyInline}} - - : An array of {{domxref("MessagePort")}} objects representing the ports associated with the channel the message is being sent through (where appropriate, e.g. in channel messaging or when sending a message to a shared worker). + - : An array of {{domxref("MessagePort")}} objects representing the ports associated with the channel the message is being sent through (where appropriate, e.g., in channel messaging or when sending a message to a shared worker). ## Examples diff --git a/files/en-us/web/api/window/name/index.md b/files/en-us/web/api/window/name/index.md index 847696d0b04be73..0bfc473ece57d29 100644 --- a/files/en-us/web/api/window/name/index.md +++ b/files/en-us/web/api/window/name/index.md @@ -22,7 +22,7 @@ Browsing contexts do not need to have names. Modern browsers will reset `Window.name` to an empty string if a tab loads a page from a different domain, and restore the name if the original page is reloaded -(e.g. by selecting the "back" button). This prevents an untrusted page from accessing +(e.g., by selecting the "back" button). This prevents an untrusted page from accessing any information that the previous page might have stored in the property (potentially the new page might also modify such data, which might then be read by the original page if it was reloaded). diff --git a/files/en-us/web/api/window/navigator/index.md b/files/en-us/web/api/window/navigator/index.md index 6589fd88f00c2ad..9274071f53eb9e1 100644 --- a/files/en-us/web/api/window/navigator/index.md +++ b/files/en-us/web/api/window/navigator/index.md @@ -45,9 +45,8 @@ function getBrowserName(userAgent) { } else if (userAgent.includes("Safari")) { // "Mozilla/5.0 (iPhone; CPU iPhone OS 15_6_1 like Mac OS X) AppleWebKit/605.1.15 (KHTML, like Gecko) Version/15.6 Mobile/15E148 Safari/604.1" return "Apple Safari"; - } else { - return "unknown"; } + return "unknown"; } const browserName = getBrowserName(navigator.userAgent); diff --git a/files/en-us/web/api/window/offline_event/index.md b/files/en-us/web/api/window/offline_event/index.md index 30833ff7b20f371..e21e6a2d6bf1442 100644 --- a/files/en-us/web/api/window/offline_event/index.md +++ b/files/en-us/web/api/window/offline_event/index.md @@ -14,9 +14,10 @@ The **`offline`** event of the {{domxref("Window")}} interface is fired when the Use the event name in methods like {{domxref("EventTarget.addEventListener", "addEventListener()")}}, or set an event handler property. -```js -addEventListener("offline", (event) => {}); -onoffline = (event) => {}; +```js-nolint +addEventListener("offline", (event) => { }) + +onoffline = (event) => { } ``` ## Event type diff --git a/files/en-us/web/api/window/online_event/index.md b/files/en-us/web/api/window/online_event/index.md index 8c836e84e8f7008..7216a701b600be0 100644 --- a/files/en-us/web/api/window/online_event/index.md +++ b/files/en-us/web/api/window/online_event/index.md @@ -17,9 +17,10 @@ The **`online`** event of the {{domxref("Window")}} interface is fired when the Use the event name in methods like {{domxref("EventTarget.addEventListener", "addEventListener()")}}, or set an event handler property. -```js -addEventListener("online", (event) => {}); -ononline = (event) => {}; +```js-nolint +addEventListener("online", (event) => { }) + +ononline = (event) => { } ``` ## Event type diff --git a/files/en-us/web/api/window/open/index.md b/files/en-us/web/api/window/open/index.md index 5ca940b66be9e50..e13cd0d6b4ed1aa 100644 --- a/files/en-us/web/api/window/open/index.md +++ b/files/en-us/web/api/window/open/index.md @@ -8,7 +8,7 @@ browser-compat: api.Window.open {{APIRef}} -The **`open()`** method of the [`Window`](/en-US/docs/Web/API/Window) interface loads a specified resource into a new or existing browsing context (that is, a tab, a window, or an [iframe](/en-US/docs/Web/HTML/Element/iframe)) under a specified name. +The **`open()`** method of the [`Window`](/en-US/docs/Web/API/Window) interface loads a specified resource into a new or existing browsing context (that is, a tab, a window, or an [iframe](/en-US/docs/Web/HTML/Reference/Elements/iframe)) under a specified name. ## Syntax @@ -27,9 +27,9 @@ open(url, target, windowFeatures) - `target` {{optional_inline}} - - : A string, without whitespace, specifying the [name](/en-US/docs/Web/API/Window/name) of the browsing context the resource is being loaded into. If the name doesn't identify an existing context, a new context is created and given the specified name. The special [`target` keywords](/en-US/docs/Web/HTML/Element/a#target), `_self`, `_blank` (default), `_parent`, `_top`, and `_unfencedTop` can also be used. `_unfencedTop` is only relevant to [fenced frames](/en-US/docs/Web/API/Fenced_frame_API). + - : A string, without whitespace, specifying the [name](/en-US/docs/Web/API/Window/name) of the browsing context the resource is being loaded into. If the name doesn't identify an existing context, a new context is created and given the specified name. The special [`target` keywords](/en-US/docs/Web/HTML/Reference/Elements/a#target), `_self`, `_blank` (default), `_parent`, `_top`, and `_unfencedTop` can also be used. `_unfencedTop` is only relevant to [fenced frames](/en-US/docs/Web/API/Fenced_frame_API). - This name can be used as the `target` attribute of [`<a>`](/en-US/docs/Web/HTML/Element/a#target) or [`<form>`](/en-US/docs/Web/HTML/Element/form#target) elements. + This name can be used as the `target` attribute of [`<a>`](/en-US/docs/Web/HTML/Reference/Elements/a#target) or [`<form>`](/en-US/docs/Web/HTML/Reference/Elements/form#target) elements. - `windowFeatures` {{optional_inline}} @@ -37,7 +37,7 @@ open(url, target, windowFeatures) - `attributionsrc` {{experimental_inline}} - - : Indicates that you want the browser to send an {{httpheader("Attribution-Reporting-Eligible")}} header along with the `open()` call. This call must be made with [transient activation](/en-US/docs/Glossary/Transient_activation) (i.e. inside a user interaction event handle such as `click`), within five seconds of user interaction. On the server-side this is used to trigger sending an {{httpheader("Attribution-Reporting-Register-Source")}} header in the response to complete registration of an attribution source. + - : Indicates that you want the browser to send an {{httpheader("Attribution-Reporting-Eligible")}} header along with the `open()` call. This call must be made with [transient activation](/en-US/docs/Glossary/Transient_activation) (i.e., inside a user interaction event handle such as `click`), within five seconds of user interaction. On the server-side this is used to trigger sending an {{httpheader("Attribution-Reporting-Register-Source")}} header in the response to complete registration of an attribution source. In addition, the browser is also triggered to store the associated source data (as provided in the {{httpheader("Attribution-Reporting-Register-Source")}} response header) when the `open()` method completes. @@ -82,7 +82,7 @@ open(url, target, windowFeatures) When `noopener` is used, non-empty target names, other than `_top`, `_self`, and `_parent`, are treated like `_blank` in terms of deciding whether to open a new browsing context. - `noreferrer` - - : If this feature is set, the browser will omit the [`Referer`](/en-US/docs/Web/HTTP/Headers/Referer) header, as well as set `noopener` to true. See [`rel="noreferrer"`](/en-US/docs/Web/HTML/Attributes/rel/noreferrer) for more information. + - : If this feature is set, the browser will omit the [`Referer`](/en-US/docs/Web/HTTP/Reference/Headers/Referer) header, as well as set `noopener` to true. See [`rel="noreferrer"`](/en-US/docs/Web/HTML/Reference/Attributes/rel/noreferrer) for more information. A [`null`](/en-US/docs/Web/JavaScript/Reference/Operators/null) value is treated the same as the empty string (`""`). @@ -185,7 +185,7 @@ link.addEventListener( The above code solves a few usability problems related to links opening popups. The purpose of the `event.preventDefault()` in the code is to cancel the default action of the link: if the event listener for `click` is executed, then there is no need to execute the default action of the link. But if JavaScript support is disabled or non-existent on the user's browser, then the event listener for `click` is ignored, and the browser loads the referenced resource in the target frame or window that has the name `"WikipediaWindowName"`. If no frame nor window has the name `"WikipediaWindowName"`, then the browser will create a new window and name it `"WikipediaWindowName"`. > [!NOTE] -> For more details about the `target` attribute, see [`<a>`](/en-US/docs/Web/HTML/Element/a#target) or [`<form>`](/en-US/docs/Web/HTML/Element/form#target). +> For more details about the `target` attribute, see [`<a>`](/en-US/docs/Web/HTML/Reference/Elements/a#target) or [`<form>`](/en-US/docs/Web/HTML/Reference/Elements/form#target). ### Reuse existing windows and avoid `target="_blank"` @@ -290,7 +290,7 @@ Avoid `<a href="#" onclick="window.open(…);">` or `<a href="javascript:window\ These bogus `href` values cause unexpected behavior when copying/dragging links, opening links in a new tab/window, bookmarking, or when JavaScript is loading, errors, or is disabled. They also convey incorrect semantics to assistive technologies, like screen readers. -If necessary, use a [`<button>`](/en-US/docs/Web/HTML/Element/button) element instead. In general, _you should only use a link for navigation to a real URL_. +If necessary, use a [`<button>`](/en-US/docs/Web/HTML/Reference/Elements/button) element instead. In general, _you should only use a link for navigation to a real URL_. ### Always identify links leading to a secondary window @@ -307,7 +307,7 @@ The purpose is to warn users of context changes to minimize confusion on the use When extreme changes in context are explicitly identified before they occur, then the users can determine if they wish to proceed or so they can be prepared for the change: not only they will not be confused or feel disoriented, but more experienced users can better decide how to open such links (in a new window or not, in the same window, in a new tab or not, in "background" or not). - [WebAIM: Links and Hypertext - Hypertext Links](https://webaim.org/techniques/hypertext/hypertext_links) -- [MDN / Understanding WCAG, Guideline 3.2](/en-US/docs/Web/Accessibility/Understanding_WCAG/Understandable#guideline_3.2_—_predictable_make_web_pages_appear_and_operate_in_predictable_ways) +- [MDN / Understanding WCAG, Guideline 3.2](/en-US/docs/Web/Accessibility/Guides/Understanding_WCAG/Understandable#guideline_3.2_—_predictable_make_web_pages_appear_and_operate_in_predictable_ways) - [G200: Opening new windows and tabs from a link only when necessary](https://www.w3.org/TR/WCAG20-TECHS/G200.html) - [G201: Giving users advanced warning when opening a new window](https://www.w3.org/TR/WCAG20-TECHS/G201.html) @@ -322,11 +322,11 @@ When extreme changes in context are explicitly identified before they occur, the ## See also - `target` attribute documentation: - - [`<a>`](/en-US/docs/Web/HTML/Element/a#target) - - [`<form>`](/en-US/docs/Web/HTML/Element/form#target) + - [`<a>`](/en-US/docs/Web/HTML/Reference/Elements/a#target) + - [`<form>`](/en-US/docs/Web/HTML/Reference/Elements/form#target) - [`window.close()`](/en-US/docs/Web/API/Window/close) - [`window.closed`](/en-US/docs/Web/API/Window/closed) - [`window.focus()`](/en-US/docs/Web/API/Window/focus) - [`window.opener`](/en-US/docs/Web/API/Window/opener) -- [`rel="opener"`](/en-US/docs/Web/HTML/Attributes/rel#opener) and [`rel="noopener"`](/en-US/docs/Web/HTML/Attributes/rel#noopener) +- [`rel="opener"`](/en-US/docs/Web/HTML/Reference/Attributes/rel#opener) and [`rel="noopener"`](/en-US/docs/Web/HTML/Reference/Attributes/rel#noopener) - [Same-origin policy](/en-US/docs/Web/Security/Same-origin_policy) diff --git a/files/en-us/web/api/window/opener/index.md b/files/en-us/web/api/window/opener/index.md index 8052f299d2d5b20..ac8e6896184f96a 100644 --- a/files/en-us/web/api/window/opener/index.md +++ b/files/en-us/web/api/window/opener/index.md @@ -11,7 +11,7 @@ browser-compat: api.Window.opener The {{domxref("Window")}} interface's **`opener`** property returns a reference to the window that opened the window, either with {{domxref("Window.open", "open()")}}, or by navigating -a link with a [`target`](/en-US/docs/Web/HTML/Element/a#target) attribute. +a link with a [`target`](/en-US/docs/Web/HTML/Reference/Elements/a#target) attribute. In other words, if window `A` opens window `B`, `B.opener` returns `A`. @@ -19,7 +19,7 @@ In other words, if window `A` opens window `B`, ## Value A {{domxref("Window")}}-like object referring to the window that opened the current -window (using {{domxref("window.open()")}}, or by a link with [`target`](/en-US/docs/Web/HTML/Element/a#target) attribute set). If this window was not opened by being linked to or created by +window (using {{domxref("window.open()")}}, or by a link with [`target`](/en-US/docs/Web/HTML/Reference/Elements/a#target) attribute set). If this window was not opened by being linked to or created by another, returns [`null`](/en-US/docs/Web/JavaScript/Reference/Operators/null). If the opener is not on the same origin as the current page, functionality of the @@ -52,10 +52,10 @@ In the following cases, the browser does not populate `window.opener`, but leaves it [`null`](/en-US/docs/Web/JavaScript/Reference/Operators/null): - The opener can be omitted by specifying - [`rel=noopener`](/en-US/docs/Web/HTML/Attributes/rel#noopener) on a link, or passing + [`rel=noopener`](/en-US/docs/Web/HTML/Reference/Attributes/rel#noopener) on a link, or passing `noopener` in the {{domxref("Window.open", "windowFeatures")}} parameter. -- Windows opened because of links with a [`target`](/en-US/docs/Web/HTML/Element/a#target) of `_blank` don't get an `opener`, unless explicitly - requested with [`rel=opener`](/en-US/docs/Web/HTML/Attributes/rel#opener). +- Windows opened because of links with a [`target`](/en-US/docs/Web/HTML/Reference/Elements/a#target) of `_blank` don't get an `opener`, unless explicitly + requested with [`rel=opener`](/en-US/docs/Web/HTML/Reference/Attributes/rel#opener). - Having a {{HTTPHeader("Cross-Origin-Opener-Policy")}} header with a value of `same-origin` prevents setting `opener`. Since the new window is loaded in a different browsing context, it won't have a reference to the opening diff --git a/files/en-us/web/api/window/orientationchange_event/index.md b/files/en-us/web/api/window/orientationchange_event/index.md index aef642cbec15548..cf7fc312d8c40eb 100644 --- a/files/en-us/web/api/window/orientationchange_event/index.md +++ b/files/en-us/web/api/window/orientationchange_event/index.md @@ -20,10 +20,10 @@ This event is deprecated. Listen for the {{domxref("ScreenOrientation.change_eve Use the event name in methods like {{domxref("EventTarget.addEventListener", "addEventListener()")}}, or set an event handler property. -```js -addEventListener("orientationchange", (event) => {}); +```js-nolint +addEventListener("orientationchange", (event) => { }) -onorientationchange = (event) => {}; +onorientationchange = (event) => { } ``` ## Event type diff --git a/files/en-us/web/api/window/origin/index.md b/files/en-us/web/api/window/origin/index.md index 329f8ae65be83dc..b2b41ed2df67ebe 100644 --- a/files/en-us/web/api/window/origin/index.md +++ b/files/en-us/web/api/window/origin/index.md @@ -22,7 +22,7 @@ Executed from inside window scope, the following snippet will log the document's console.log(window.origin); // On this page returns 'https://developer.mozilla.org' ``` -If the origin is not a scheme/host/port tuple (say you are trying to run it locally, i.e. via `file://` URL), `origin` will return the string `"null"`. +If the origin is not a scheme/host/port tuple (say you are trying to run it locally, i.e., via `file://` URL), `origin` will return the string `"null"`. ## Specifications diff --git a/files/en-us/web/api/window/originagentcluster/index.md b/files/en-us/web/api/window/originagentcluster/index.md index 9881e0312e14c4f..17601492554a4fd 100644 --- a/files/en-us/web/api/window/originagentcluster/index.md +++ b/files/en-us/web/api/window/originagentcluster/index.md @@ -3,12 +3,10 @@ title: "Window: originAgentCluster property" short-title: originAgentCluster slug: Web/API/Window/originAgentCluster page-type: web-api-instance-property -status: - - experimental browser-compat: api.Window.originAgentCluster --- -{{APIRef}}{{SeeCompatTable}} +{{APIRef}} The **`originAgentCluster`** read-only property of the {{domxref("Window")}} interface returns `true` if this window belongs to an _origin-keyed [agent cluster](https://tc39.es/ecma262/#sec-agent-clusters)_: this means that the operating system has provided dedicated resources (for example an operating system process) to this window's origin that are not shared with windows from other origins. diff --git a/files/en-us/web/api/window/outerheight/index.md b/files/en-us/web/api/window/outerheight/index.md index 2d043f744a9aa1a..0f859ff088c44aa 100644 --- a/files/en-us/web/api/window/outerheight/index.md +++ b/files/en-us/web/api/window/outerheight/index.md @@ -14,7 +14,7 @@ The **`Window.outerHeight`** read-only property returns the height in pixels of To change the size of a window, see {{domxref("window.resizeBy()")}} and {{domxref("window.resizeTo()")}}. -To get the inner height of a window, i.e. the height of the page being displayed, see {{domxref("window.innerHeight")}}. +To get the inner height of a window, i.e., the height of the page being displayed, see {{domxref("window.innerHeight")}}. ### Graphical example diff --git a/files/en-us/web/api/window/outerwidth/index.md b/files/en-us/web/api/window/outerwidth/index.md index 7d4cf1f5d0ab511..e089a03b956edb5 100644 --- a/files/en-us/web/api/window/outerwidth/index.md +++ b/files/en-us/web/api/window/outerwidth/index.md @@ -14,7 +14,7 @@ browser-compat: api.Window.outerWidth To change the size of a window, see {{domxref("window.resizeBy()")}} and {{domxref("window.resizeTo()")}}. -To get the inner width of a window, i.e. the width of the page being displayed, see {{domxref("window.innerWidth")}}. +To get the inner width of a window, i.e., the width of the page being displayed, see {{domxref("window.innerWidth")}}. ## Specifications diff --git a/files/en-us/web/api/window/pagehide_event/index.md b/files/en-us/web/api/window/pagehide_event/index.md index 8b27057f35fe230..19e64d4f0806ec9 100644 --- a/files/en-us/web/api/window/pagehide_event/index.md +++ b/files/en-us/web/api/window/pagehide_event/index.md @@ -16,9 +16,10 @@ For example, when the user clicks the browser's Back button, the current page re Use the event name in methods like {{domxref("EventTarget.addEventListener", "addEventListener()")}}, or set an event handler property. -```js -addEventListener("pagehide", (event) => {}); -onpagehide = (event) => {}; +```js-nolint +addEventListener("pagehide", (event) => { }) + +onpagehide = (event) => { } ``` ## Event type diff --git a/files/en-us/web/api/window/pagereveal_event/index.md b/files/en-us/web/api/window/pagereveal_event/index.md index 575aeeedb1e535e..1be5f1f3e782734 100644 --- a/files/en-us/web/api/window/pagereveal_event/index.md +++ b/files/en-us/web/api/window/pagereveal_event/index.md @@ -16,9 +16,10 @@ This is useful in the case of cross-document (MPA) [view transitions](/en-US/doc Use the event name in methods like {{domxref("EventTarget.addEventListener", "addEventListener()")}}, or set an event handler property. -```js -addEventListener("pagereveal", (event) => {}); -onpagereveal = (event) => {}; +```js-nolint +addEventListener("pagereveal", (event) => { }) + +onpagereveal = (event) => { } ``` ## Event type diff --git a/files/en-us/web/api/window/pageshow_event/index.md b/files/en-us/web/api/window/pageshow_event/index.md index 887f1f6275ff07e..aeb365015d29dc3 100644 --- a/files/en-us/web/api/window/pageshow_event/index.md +++ b/files/en-us/web/api/window/pageshow_event/index.md @@ -24,9 +24,10 @@ This includes: Use the event name in methods like {{domxref("EventTarget.addEventListener", "addEventListener()")}}, or set an event handler property. -```js -addEventListener("pageshow", (event) => {}); -onpageshow = (event) => {}; +```js-nolint +addEventListener("pageshow", (event) => { }) + +onpageshow = (event) => { } ``` ## Event type diff --git a/files/en-us/web/api/window/pageswap_event/index.md b/files/en-us/web/api/window/pageswap_event/index.md index fc61ba8a2c2b6d1..2059f389aa54f38 100644 --- a/files/en-us/web/api/window/pageswap_event/index.md +++ b/files/en-us/web/api/window/pageswap_event/index.md @@ -18,9 +18,10 @@ It also provides access to the navigation type and current and destination docum Use the event name in methods like {{domxref("EventTarget.addEventListener", "addEventListener()")}}, or set an event handler property. -```js -addEventListener("pageswap", (event) => {}); -onpageswap = (event) => {}; +```js-nolint +addEventListener("pageswap", (event) => { }) + +onpageswap = (event) => { } ``` ## Event type diff --git a/files/en-us/web/api/window/paste_event/index.md b/files/en-us/web/api/window/paste_event/index.md deleted file mode 100644 index b430b5400fd73b3..000000000000000 --- a/files/en-us/web/api/window/paste_event/index.md +++ /dev/null @@ -1,51 +0,0 @@ ---- -title: "Window: paste event" -short-title: paste -slug: Web/API/Window/paste_event -page-type: web-api-event -browser-compat: api.Element.paste_event ---- - -{{APIRef}} - -The **`paste`** event is fired when the user has initiated a "paste" action through the browser's user interface. - -The original target for this event is the {{domxref("Element")}} that was the intended target of the paste action. You can listen for this event on the {{domxref("Window")}} interface to handle it in the capture or bubbling phases. For full details on this event please see the page on the [Element: paste event](/en-US/docs/Web/API/Element/paste_event). - -## Syntax - -Use the event name in methods like {{domxref("EventTarget.addEventListener", "addEventListener()")}}, or set an event handler property. - -```js -addEventListener("paste", (event) => {}); - -onpaste = (event) => {}; -``` - -## Event type - -A {{domxref("ClipboardEvent")}}. Inherits from {{domxref("Event")}}. - -{{InheritanceDiagram("ClipboardEvent")}} - -## Examples - -```js -window.addEventListener("paste", (event) => { - console.log("paste action initiated"); -}); -``` - -## Specifications - -{{Specifications}} - -## Browser compatibility - -{{Compat}} - -## See also - -- Related events: {{domxref("Window/cut_event", "cut")}}, {{domxref("Window/copy_event", "copy")}} -- This event on {{domxref("Element")}} targets: {{domxref("Element/paste_event", "paste")}} -- This event on {{domxref("Document")}} targets: {{domxref("Document/paste_event", "paste")}} diff --git a/files/en-us/web/api/window/popstate_event/index.md b/files/en-us/web/api/window/popstate_event/index.md index d918551791b9897..78dc867274a6b28 100644 --- a/files/en-us/web/api/window/popstate_event/index.md +++ b/files/en-us/web/api/window/popstate_event/index.md @@ -14,9 +14,10 @@ The **`popstate`** event of the {{domxref("Window")}} interface is fired when th Use the event name in methods like {{domxref("EventTarget.addEventListener", "addEventListener()")}}, or set an event handler property. -```js -addEventListener("popstate", (event) => {}); -onpopstate = (event) => {}; +```js-nolint +addEventListener("popstate", (event) => { }) + +onpopstate = (event) => { } ``` ## Event type @@ -65,7 +66,7 @@ To better understand when the `popstate` event is fired, consider this simplifie 2. If **current-entry**'s title wasn't set using one of the History API methods ({{domxref("History.pushState", "pushState()")}} or {{domxref("History.replaceState", "replaceState()")}}), set the entry's title to the string returned by its {{domxref("document.title")}} attribute. 3. If the browser has state information it wishes to store with the **current-entry** before navigating away from it, it then does so. The entry is now said to have "persisted user state." This information the browser might add to the history session entry may include, for instance, the document's scroll position, the values of form inputs, and other such data. 4. If **new-entry** has a different `Document` object than **current-entry**, the browsing context is updated so that its {{domxref("Window.document", "document")}} property refers to the document referred to by **new-entry**, and the context's name is updated to match the context name of the now-current document. -5. Each form control within **new-entry**'s {{domxref("Document")}} that has [`autocomplete`](/en-US/docs/Web/HTML/Element/input#autocomplete) configured with its autofill field name set to `off` is reset. See [The HTML autocomplete attribute](/en-US/docs/Web/HTML/Attributes/autocomplete) for more about the autocomplete field names and how autocomplete works. +5. Each form control within **new-entry**'s {{domxref("Document")}} that has [`autocomplete`](/en-US/docs/Web/HTML/Reference/Elements/input#autocomplete) configured with its autofill field name set to `off` is reset. See [The HTML autocomplete attribute](/en-US/docs/Web/HTML/Reference/Attributes/autocomplete) for more about the autocomplete field names and how autocomplete works. 6. If **new-entry**'s document is already fully loaded and ready—that is, its {{domxref("Document.readyState", "readyState")}} is `complete`—and the document is not already visible, it's made visible and the {{domxref("Window/pageshow_event", "pageshow")}} event is fired at the document with the {{domxref("PageTransitionEvent")}}'s {{domxref("PageTransitionEvent.persisted", "persisted")}} attribute set to `true`. 7. The document's {{domxref("Document.URL", "URL")}} is set to that of **new-entry**. 8. If the history traversal is being performed with replacement enabled, the entry immediately prior to the destination entry (taking into account the `delta` parameter on methods such as {{domxref("History.go", "go()")}}) is removed from the history stack. diff --git a/files/en-us/web/api/window/postmessage/index.md b/files/en-us/web/api/window/postmessage/index.md index 161021e567a58e1..97040df8af597fe 100644 --- a/files/en-us/web/api/window/postmessage/index.md +++ b/files/en-us/web/api/window/postmessage/index.md @@ -159,7 +159,7 @@ window.addEventListener("message", (event) => { // message is to call postMessage on event.source and provide // event.origin as the targetOrigin. event.source.postMessage( - "hi there yourself! the secret response " + "is: rheeeeet!", + "hi there yourself! the secret response is: rheeeeet!", event.origin, ); }); diff --git a/files/en-us/web/api/window/querylocalfonts/index.md b/files/en-us/web/api/window/querylocalfonts/index.md index 11ac89c3d60fba7..ddca8a0f5a5453d 100644 --- a/files/en-us/web/api/window/querylocalfonts/index.md +++ b/files/en-us/web/api/window/querylocalfonts/index.md @@ -12,7 +12,7 @@ browser-compat: api.Window.queryLocalFonts The **`window.queryLocalFonts()`** method returns a {{jsxref("Promise")}} that fulfills with an array of {{domxref("FontData")}} objects representing the font faces available locally. -To use this method, the user must grant permission to access `local-fonts` (permission status can be queried via the {{domxref("Permissions API", "", "", "nocode")}}). In addition, this feature may be blocked by a [Permissions Policy](/en-US/docs/Web/HTTP/Permissions_Policy) set on your server. +To use this method, the user must grant permission to access `local-fonts` (permission status can be queried via the {{domxref("Permissions API", "", "", "nocode")}}). In addition, this feature may be blocked by a [Permissions Policy](/en-US/docs/Web/HTTP/Guides/Permissions_Policy) set on your server. ## Syntax @@ -36,7 +36,7 @@ A {{jsxref("Promise")}} that fulfills with an array of {{domxref("FontData")}} o - `NotAllowedError` {{domxref("DOMException")}} - : The user chose to deny permission to use this feature when presented with the browser's permission prompt after the method was first invoked. - `SecurityError` {{domxref("DOMException")}} - - : Use of this feature was blocked by a [Permissions Policy](/en-US/docs/Web/HTTP/Permissions_Policy), or it was not called via a user interaction such as a button press, or current {{glossary("origin")}} is an opaque origin. + - : Use of this feature was blocked by a [Permissions Policy](/en-US/docs/Web/HTTP/Guides/Permissions_Policy), or it was not called via a user interaction such as a button press, or current {{glossary("origin")}} is an opaque origin. ## Examples diff --git a/files/en-us/web/api/window/rejectionhandled_event/index.md b/files/en-us/web/api/window/rejectionhandled_event/index.md index 3ca12c8dc289328..879ec956b5964f1 100644 --- a/files/en-us/web/api/window/rejectionhandled_event/index.md +++ b/files/en-us/web/api/window/rejectionhandled_event/index.md @@ -8,7 +8,7 @@ browser-compat: api.Window.rejectionhandled_event {{APIRef("HTML DOM")}} -The **`rejectionhandled`** event is sent to the script's global scope (usually {{domxref("window")}} but also {{domxref("Worker")}}) whenever a rejected JavaScript {{jsxref("Promise")}} is handled late, i.e. when a handler is attached to the promise after its rejection had caused an {{domxref("Window.unhandledrejection_event", "unhandledrejection")}} event. +The **`rejectionhandled`** event is sent to the script's global scope (usually {{domxref("window")}} but also {{domxref("Worker")}}) whenever a rejected JavaScript {{jsxref("Promise")}} is handled late, i.e., when a handler is attached to the promise after its rejection had caused an {{domxref("Window.unhandledrejection_event", "unhandledrejection")}} event. This can be used in debugging and for general application resiliency, in tandem with the `unhandledrejection` event, which is sent when a promise is rejected but there is no handler for the rejection at the time. @@ -16,9 +16,10 @@ This can be used in debugging and for general application resiliency, in tandem Use the event name in methods like {{domxref("EventTarget.addEventListener", "addEventListener()")}}, or set an event handler property. -```js -addEventListener("rejectionhandled", (event) => {}); -onrejectionhandled = (event) => {}; +```js-nolint +addEventListener("rejectionhandled", (event) => { }) + +onrejectionhandled = (event) => { } ``` ## Event type diff --git a/files/en-us/web/api/window/requestfilesystem/index.md b/files/en-us/web/api/window/requestfilesystem/index.md index 8f946e22efa9e59..f74092f6ed56988 100644 --- a/files/en-us/web/api/window/requestfilesystem/index.md +++ b/files/en-us/web/api/window/requestfilesystem/index.md @@ -44,7 +44,7 @@ requestFileSystem(type, size, successCallback, errorCallback) - : An optional parameter specifying a function which is called if an error occurs while attempting to obtain the file system, or if the user denies permission to create or access the file system. The callback receives as input a single parameter: a - `FileError` object describing the error. + `DOMException` object describing the error. ### Return value diff --git a/files/en-us/web/api/window/resize_event/index.md b/files/en-us/web/api/window/resize_event/index.md index 61ac8889eccb577..dc7b02be3113dab 100644 --- a/files/en-us/web/api/window/resize_event/index.md +++ b/files/en-us/web/api/window/resize_event/index.md @@ -12,7 +12,7 @@ The **`resize`** event fires when the document view (window) has been resized. This event is not cancelable and does not bubble. -In some earlier browsers it was possible to register `resize` event handlers on any HTML element. It is still possible to set `onresize` attributes or use {{domxref("EventTarget.addEventListener", "addEventListener()")}} to set a handler on any element. However, `resize` events are only fired on the {{domxref("Window", "window")}} object (i.e. returned by {{domxref("document.defaultView")}}). Only handlers registered on the `window` object will receive `resize` events. +In some earlier browsers it was possible to register `resize` event handlers on any HTML element. It is still possible to set `onresize` attributes or use {{domxref("EventTarget.addEventListener", "addEventListener()")}} to set a handler on any element. However, `resize` events are only fired on the {{domxref("Window", "window")}} object (i.e., returned by {{domxref("document.defaultView")}}). Only handlers registered on the `window` object will receive `resize` events. While the `resize` event fires only for the window nowadays, you can get resize notifications for other elements using the [ResizeObserver](/en-US/docs/Web/API/ResizeObserver) API. @@ -22,10 +22,10 @@ If the resize event is triggered too many times for your application, see [Optim Use the event name in methods like {{domxref("EventTarget.addEventListener", "addEventListener()")}}, or set an event handler property. -```js -addEventListener("resize", (event) => {}); +```js-nolint +addEventListener("resize", (event) => { }) -onresize = (event) => {}; +onresize = (event) => { } ``` ## Event type diff --git a/files/en-us/web/api/window/scrollsnapchange_event/index.md b/files/en-us/web/api/window/scrollsnapchange_event/index.md index 0dd3561582023a6..7ec393b3cf96940 100644 --- a/files/en-us/web/api/window/scrollsnapchange_event/index.md +++ b/files/en-us/web/api/window/scrollsnapchange_event/index.md @@ -18,10 +18,10 @@ This event works in much the same way as the {{domxref("Element")}} interface's Use the event name in methods like {{domxref("EventTarget.addEventListener", "addEventListener()")}}, or set an event handler property. -```js -addEventListener("scrollsnapchange", (event) => {}); +```js-nolint +addEventListener("scrollsnapchange", (event) => { }) -onscrollsnapchange = (event) => {}; +onscrollsnapchange = (event) => { } ``` ## Event type diff --git a/files/en-us/web/api/window/scrollsnapchanging_event/index.md b/files/en-us/web/api/window/scrollsnapchanging_event/index.md index 69941cad9cc6848..b85b2c9787204ca 100644 --- a/files/en-us/web/api/window/scrollsnapchanging_event/index.md +++ b/files/en-us/web/api/window/scrollsnapchanging_event/index.md @@ -10,7 +10,7 @@ browser-compat: api.Window.scrollsnapchanging_event {{APIRef}}{{SeeCompatTable}} -The **`scrollsnapchanging`** event of the {{domxref("Window")}} interface is fired on the `window` when the browser determines a new scroll snap target is pending, i.e. it will be selected when the current scroll gesture ends. +The **`scrollsnapchanging`** event of the {{domxref("Window")}} interface is fired on the `window` when the browser determines a new scroll snap target is pending, i.e., it will be selected when the current scroll gesture ends. This event works in much the same way as the {{domxref("Element")}} interface's [`scrollsnapchanging`](/en-US/docs/Web/API/Element/scrollsnapchanging_event) event, except that the overall HTML document has to be set as the scroll snap container (i.e., {{cssxref("scroll-snap-type")}} is set on the {{htmlelement("html")}} element). @@ -18,10 +18,10 @@ This event works in much the same way as the {{domxref("Element")}} interface's Use the event name in methods like {{domxref("EventTarget.addEventListener", "addEventListener()")}}, or set an event handler property. -```js -addEventListener("scrollsnapchanging", (event) => {}); +```js-nolint +addEventListener("scrollsnapchanging", (event) => { }) -onscrollsnapchanging = (event) => {}; +onscrollsnapchanging = (event) => { } ``` ## Event type diff --git a/files/en-us/web/api/window/setinterval/index.md b/files/en-us/web/api/window/setinterval/index.md index 190a14b22f039f7..515cfea095a5c97 100644 --- a/files/en-us/web/api/window/setinterval/index.md +++ b/files/en-us/web/api/window/setinterval/index.md @@ -10,8 +10,6 @@ browser-compat: api.setInterval The **`setInterval()`** method of the {{domxref("Window")}} interface repeatedly calls a function or executes a code snippet, with a fixed time delay between each call. -This method returns an interval ID which uniquely identifies the interval, so you can remove it later by calling {{domxref("Window.clearInterval", "clearInterval()")}}. - ## Syntax ```js-nolint @@ -40,9 +38,11 @@ setInterval(func, delay, arg1, arg2, /* …, */ argN) ### Return value -The returned `intervalID` is a numeric, non-zero value which identifies the timer created by the call to `setInterval()`; this value can be passed to {{domxref("Window.clearInterval", "clearInterval()")}} to cancel the interval. +The `setInterval()` method returns a positive integer (typically within the range of 1 to 2,147,483,647) that uniquely identifies the interval timer created by the call. This identifier, often referred to as an "interval ID", can be passed to {{domxref("Window.clearInterval", "clearInterval()")}} to stop the repeated execution of the specified function. + +Within the same global environment (e.g., a particular window or worker), the interval ID is ensured to remain unique and is not reused for any new interval timer as long as the original timer is still active. However, different global environments maintain their own independent pools of interval IDs. -It may be helpful to be aware that `setInterval()` and {{domxref("Window.setTimeout", "setTimeout()")}} share the same pool of IDs, and that `clearInterval()` and {{domxref("Window.clearTimeout", "clearTimeout()")}} can technically be used interchangeably. +Be aware that `setInterval()` and {{domxref("Window.setTimeout", "setTimeout()")}} share the same pool of IDs, and that `clearInterval()` and {{domxref("Window.clearTimeout", "clearTimeout()")}} can technically be used interchangeably. For clarity, however, you should try to always match them to avoid confusion when maintaining your code. > [!NOTE] @@ -100,9 +100,7 @@ let intervalId; function changeColor() { // check if an interval has already been set up - if (!intervalId) { - intervalId = setInterval(flashText, 1000); - } + intervalId ??= setInterval(flashText, 1000); } function flashText() { diff --git a/files/en-us/web/api/window/settimeout/index.md b/files/en-us/web/api/window/settimeout/index.md index be6383bde9144c2..66a60e678617b42 100644 --- a/files/en-us/web/api/window/settimeout/index.md +++ b/files/en-us/web/api/window/settimeout/index.md @@ -48,12 +48,9 @@ setTimeout(functionRef, delay, param1, param2, /* …, */ paramN) ### Return value -The returned `timeoutID` is a positive integer value which -identifies the timer created by the call to `setTimeout()`. This value can be -passed to {{domxref("Window.clearTimeout","clearTimeout()")}} to -cancel the timeout. +The `setTimeout()` method returns a positive integer (typically within the range of 1 to 2,147,483,647) that uniquely identifies the timer created by the call. This identifier, often referred to as a "timeout ID", can be passed to {{domxref("Window.clearTimeout","clearTimeout()")}} to cancel the timer. -It is guaranteed that a `timeoutID` value will never be reused by a subsequent call to `setTimeout()` or `setInterval()` on the same window while the timer is still active. However, different objects use separate pools of IDs. +Within the same global environment (e.g., a specific window or worker) the timeout ID is guaranteed not to be reused for any new timer as long as the original timer remains active. However, separate global environments maintain their own independent pools of timer IDs. ## Description @@ -322,9 +319,27 @@ using a Web Audio API {{domxref("AudioContext")}}. The specifics of this are browser-dependent: -- Firefox Desktop and Chrome both have a minimum timeout of 1 second for inactive tabs. +- Firefox Desktop has a minimum timeout of 1 second for inactive tabs. - Firefox for Android has a minimum timeout of 15 minutes for inactive tabs and may unload them entirely. - Firefox does not throttle inactive tabs if the tab contains an {{domxref("AudioContext")}}. +- Chrome uses different levels of throttling depending on the tab activity: + + - **Minimal throttling**: Applies to timers when the page is visible, has made sound recently, or is otherwise considered active by Chrome. Timers run close to the requested interval. + + - **Throttling**: Applies to timers when minimal throttle conditions are not met and any of these conditions are true: + - Nesting count (i.e., number of chained timer calls) is lower than 5. + - Page has been invisible for less than 5 minutes. + - WebRTC is active. + + Timers in this state are checked once per second, which may be batched together with other timers that have similar timeouts. + + - **Intensive throttling**: Introduced in Chrome 88 (January 2021). Applies to timers when neither minimal throttling nor throttling conditions are met, and all of the following conditions are met: + - Nesting count is 5 or higher. + - Page has been invisible for more than 5 minutes. + - Page has been silent for more than 30 seconds. + - WebRTC is inactive. + + Timers in this state are checked once per minute, which may be batched together with other timers that have similar timeouts. #### Throttling of tracking scripts diff --git a/files/en-us/web/api/window/showdirectorypicker/index.md b/files/en-us/web/api/window/showdirectorypicker/index.md index 52f4667c1bf39e3..39e09c9af6a546f 100644 --- a/files/en-us/web/api/window/showdirectorypicker/index.md +++ b/files/en-us/web/api/window/showdirectorypicker/index.md @@ -18,6 +18,7 @@ select a directory. ```js-nolint showDirectoryPicker() +showDirectoryPicker(options) ``` ### Parameters diff --git a/files/en-us/web/api/window/showmodaldialog/index.md b/files/en-us/web/api/window/showmodaldialog/index.md deleted file mode 100644 index 917e231415c1b84..000000000000000 --- a/files/en-us/web/api/window/showmodaldialog/index.md +++ /dev/null @@ -1,116 +0,0 @@ ---- -title: "Window: showModalDialog() method" -short-title: showModalDialog() -slug: Web/API/Window/showModalDialog -page-type: web-api-instance-method -status: - - deprecated - - non-standard -browser-compat: api.Window.showModalDialog ---- - -{{APIRef}}{{Deprecated_Header}}{{Non-standard_Header}} - -> [!WARNING] -> This feature has been removed. Please fix your websites and applications. -> -> This method was removed in Chrome 43 and Firefox 56. - -The **`Window.showModalDialog()`** -created and displayed a modal dialog box containing a specified HTML document. - -## Syntax - -```js-nolint -showModalDialog(uri) -showModalDialog(uri, arguments) -showModalDialog(uri, arguments, options) -``` - -### Parameters - -- `uri` - - : Is the URL of the document to display in the dialog. -- `arguments` {{optional_inline}} - - : Values passed to the dialog. - property. -- `options` {{optional_inline}} - - : A string specifying window ornamentation for the - dialog, using one or more semicolon delimited values: - -<table class="no-markdown"> - <tbody> - <tr> - <th>Syntax</th> - <th>Description</th> - </tr> - <tr> - <td><code>center: {on | off | yes | no | 1 | 0 }</code></td> - <td> - If <code>on</code>, <code>yes</code>, or <code>1</code>, the dialog - window is centered on the desktop; otherwise it's hidden. Default is - <code>yes</code>. - </td> - </tr> - <tr> - <td> - <code>dialogheight: <em>height</em></code> - </td> - <td>The height of the dialog box in pixels.</td> - </tr> - <tr> - <td> - <code>dialogleft: <em>left</em></code> - </td> - <td>Distance of the dialog box from the left edge of the desktop.</td> - </tr> - <tr> - <td> - <code>dialogwidth: <em>width</em></code> - </td> - <td>The width of the dialog box in pixels.</td> - </tr> - <tr> - <td> - <code>dialogtop: <em>top</em></code> - </td> - <td>Distance of the dialog box from the top edge of the desktop.</td> - </tr> - <tr> - <td><code>resizable: {on | off | yes | no | 1 | 0 }</code></td> - <td> - If this argument's value is <code>on</code>, <code>yes</code>, or 1, the - dialog window can be resized by the user; otherwise its size is fixed. - The default value is <code>no</code>. - </td> - </tr> - <tr> - <td><code>scroll: {on | off | yes | no | 1 | 0 }</code></td> - <td> - If <code>on</code>, <code>yes</code>, or 1, the dialog window has scroll - bars; otherwise its size is fixed. Default is <code>no</code>. - </td> - </tr> - </tbody> -</table> - -> [!NOTE] -> Firefox does not implement the `dialogHide`, `edge`, `status`, or `unadorned` arguments. - -### Return value - -Holds the `returnValue` property as set by the document specified by `uri`. - -## Specifications - -- [MSDN page for `showModalDialog`](<https://learn.microsoft.com/en-us/previous-versions/ms536759(v=vs.85)>) - -## Browser compatibility - -{{Compat}} - -## See also - -- {{HTMLElement("dialog")}}, a replacement for `window.showModalDialog()`. -- [showModalDialog Polyfill](https://github.com/niutech/showModalDialog) - using a {{HTMLElement("dialog")}} and [generators](/en-US/docs/Web/JavaScript/Reference/Statements/function*) diff --git a/files/en-us/web/api/window/showopenfilepicker/index.md b/files/en-us/web/api/window/showopenfilepicker/index.md index 2ee1fb0ca6f753e..647cb7c6e4aa381 100644 --- a/files/en-us/web/api/window/showopenfilepicker/index.md +++ b/files/en-us/web/api/window/showopenfilepicker/index.md @@ -18,6 +18,7 @@ or multiple files and returns a handle for the file(s). ```js-nolint showOpenFilePicker() +showOpenFilePicker(options) ``` ### Parameters @@ -49,7 +50,7 @@ showOpenFilePicker() - `description` {{Optional_Inline}} - : An optional description of the category of files types allowed. Defaults to an empty string. - `accept` - - : An {{jsxref('Object')}} with the keys set to the [MIME type](/en-US/docs/Web/HTTP/MIME_types/Common_types) and the values an {{jsxref('Array')}} of file extensions (see below + - : An {{jsxref('Object')}} with the keys set to the [MIME type](/en-US/docs/Web/HTTP/Guides/MIME_types/Common_types) and the values an {{jsxref('Array')}} of file extensions (see below for an example). ### Return value diff --git a/files/en-us/web/api/window/showsavefilepicker/index.md b/files/en-us/web/api/window/showsavefilepicker/index.md index 6e63ba20bb2d234..0a9f3c356b93dca 100644 --- a/files/en-us/web/api/window/showsavefilepicker/index.md +++ b/files/en-us/web/api/window/showsavefilepicker/index.md @@ -18,6 +18,7 @@ Either by selecting an existing file, or entering a name for a new file. ```js-nolint showSaveFilePicker() +showSaveFilePicker(options) ``` ### Parameters @@ -49,7 +50,7 @@ showSaveFilePicker() - : An optional description of the category of files types allowed. Default to be an empty string. - `accept` - - : An {{jsxref('Object')}} with the keys set to the [MIME type](/en-US/docs/Web/HTTP/MIME_types/Common_types) and the values an {{jsxref('Array')}} of file extensions (see below + - : An {{jsxref('Object')}} with the keys set to the [MIME type](/en-US/docs/Web/HTTP/Guides/MIME_types/Common_types) and the values an {{jsxref('Array')}} of file extensions (see below for an example). ### Return value diff --git a/files/en-us/web/api/window/storage_event/index.md b/files/en-us/web/api/window/storage_event/index.md index 49e0fde0b84ea2c..a3f1b5f565fb9e3 100644 --- a/files/en-us/web/api/window/storage_event/index.md +++ b/files/en-us/web/api/window/storage_event/index.md @@ -19,9 +19,10 @@ This event is not cancelable and does not bubble. Use the event name in methods like {{domxref("EventTarget.addEventListener", "addEventListener()")}}, or set an event handler property. -```js -addEventListener("storage", (event) => {}); -onstorage = (event) => {}; +```js-nolint +addEventListener("storage", (event) => { }) + +onstorage = (event) => { } ``` ## Event type diff --git a/files/en-us/web/api/window/unhandledrejection_event/index.md b/files/en-us/web/api/window/unhandledrejection_event/index.md index 23d59e97a925ba6..58cbb514eef6288 100644 --- a/files/en-us/web/api/window/unhandledrejection_event/index.md +++ b/files/en-us/web/api/window/unhandledrejection_event/index.md @@ -16,9 +16,10 @@ This is useful for debugging and for providing fallback error handling for unexp Use the event name in methods like {{domxref("EventTarget.addEventListener", "addEventListener()")}}, or set an event handler property. -```js -addEventListener("unhandledrejection", (event) => {}); -onunhandledrejection = (event) => {}; +```js-nolint +addEventListener("unhandledrejection", (event) => { }) + +onunhandledrejection = (event) => { } ``` ## Event type diff --git a/files/en-us/web/api/window/unload_event/index.md b/files/en-us/web/api/window/unload_event/index.md index ae1bd61fd4c14f6..8eb61014160a901 100644 --- a/files/en-us/web/api/window/unload_event/index.md +++ b/files/en-us/web/api/window/unload_event/index.md @@ -33,9 +33,10 @@ Please note that the unload event also follows the document tree: parent frame u Use the event name in methods like {{domxref("EventTarget.addEventListener", "addEventListener()")}}, or set an event handler property. -```js -addEventListener("unload", (event) => {}); -onunload = (event) => {}; +```js-nolint +addEventListener("unload", (event) => { }) + +onunload = (event) => { } ``` ## Event type diff --git a/files/en-us/web/api/window/vrdisplayactivate_event/index.md b/files/en-us/web/api/window/vrdisplayactivate_event/index.md index a00d6f7e7d929bc..bc2f5998dcabdbe 100644 --- a/files/en-us/web/api/window/vrdisplayactivate_event/index.md +++ b/files/en-us/web/api/window/vrdisplayactivate_event/index.md @@ -22,10 +22,10 @@ This event is not cancelable and does not bubble. Use the event name in methods like {{domxref("EventTarget.addEventListener", "addEventListener()")}}, or set an event handler property. -```js -addEventListener("vrdisplayactivate", (event) => {}); +```js-nolint +addEventListener("vrdisplayactivate", (event) => { }) -onvrdisplayactivate = (event) => {}; +onvrdisplayactivate = (event) => { } ``` ## Event type diff --git a/files/en-us/web/api/window/vrdisplayconnect_event/index.md b/files/en-us/web/api/window/vrdisplayconnect_event/index.md index e37d8ddcbb1b9aa..75461e10743087c 100644 --- a/files/en-us/web/api/window/vrdisplayconnect_event/index.md +++ b/files/en-us/web/api/window/vrdisplayconnect_event/index.md @@ -22,10 +22,10 @@ This event is not cancelable and does not bubble. Use the event name in methods like {{domxref("EventTarget.addEventListener", "addEventListener()")}}, or set an event handler property. -```js -addEventListener("vrdisplayconnect", (event) => {}); +```js-nolint +addEventListener("vrdisplayconnect", (event) => { }) -onvrdisplayconnect = (event) => {}; +onvrdisplayconnect = (event) => { } ``` ## Event type diff --git a/files/en-us/web/api/window/vrdisplaydeactivate_event/index.md b/files/en-us/web/api/window/vrdisplaydeactivate_event/index.md index b5055cd02fdcbfc..ab7014f4be8c2bc 100644 --- a/files/en-us/web/api/window/vrdisplaydeactivate_event/index.md +++ b/files/en-us/web/api/window/vrdisplaydeactivate_event/index.md @@ -22,10 +22,10 @@ This event is not cancelable and does not bubble. Use the event name in methods like {{domxref("EventTarget.addEventListener", "addEventListener()")}}, or set an event handler property. -```js -addEventListener("vrdisplaydeactivate", (event) => {}); +```js-nolint +addEventListener("vrdisplaydeactivate", (event) => { }) -onvrdisplaydeactivate = (event) => {}; +onvrdisplaydeactivate = (event) => { } ``` ## Event type diff --git a/files/en-us/web/api/window/vrdisplaydisconnect_event/index.md b/files/en-us/web/api/window/vrdisplaydisconnect_event/index.md index eee68dc3bcd2ae1..45a3120930053d1 100644 --- a/files/en-us/web/api/window/vrdisplaydisconnect_event/index.md +++ b/files/en-us/web/api/window/vrdisplaydisconnect_event/index.md @@ -19,10 +19,10 @@ This event is not cancelable and does not bubble. Use the event name in methods like {{domxref("EventTarget.addEventListener", "addEventListener()")}}, or set an event handler property. -```js -addEventListener("vrdisplaydisconnect", (event) => {}); +```js-nolint +addEventListener("vrdisplaydisconnect", (event) => { }) -onvrdisplaydisconnect = (event) => {}; +onvrdisplaydisconnect = (event) => { } ``` ## Event type diff --git a/files/en-us/web/api/window/vrdisplaypresentchange_event/index.md b/files/en-us/web/api/window/vrdisplaypresentchange_event/index.md index f5b75d568748cd7..4b87babdd6c64e2 100644 --- a/files/en-us/web/api/window/vrdisplaypresentchange_event/index.md +++ b/files/en-us/web/api/window/vrdisplaypresentchange_event/index.md @@ -11,7 +11,7 @@ browser-compat: api.Window.vrdisplaypresentchange_event {{APIRef("Window")}}{{Deprecated_Header}}{{Non-standard_Header}} -The **`vrdisplaypresentchange`** event of the [WebVR API](/en-US/docs/Web/API/WebVR_API) is fired when the presenting state of a VR display changes — i.e. goes from presenting to not presenting, or vice versa. +The **`vrdisplaypresentchange`** event of the [WebVR API](/en-US/docs/Web/API/WebVR_API) is fired when the presenting state of a VR display changes — i.e., goes from presenting to not presenting, or vice versa. > [!NOTE] > This event was part of the old [WebVR API](https://immersive-web.github.io/webvr/spec/1.1/). It has been superseded by the [WebXR Device API](https://immersive-web.github.io/webxr/). @@ -22,10 +22,10 @@ This event is not cancelable and does not bubble. Use the event name in methods like {{domxref("EventTarget.addEventListener", "addEventListener()")}}, or set an event handler property. -```js -addEventListener("vrdisplaypresentchange", (event) => {}); +```js-nolint +addEventListener("vrdisplaypresentchange", (event) => { }) -onvrdisplaypresentchange = (event) => {}; +onvrdisplaypresentchange = (event) => { } ``` ## Event type diff --git a/files/en-us/web/api/window/window/index.md b/files/en-us/web/api/window/window/index.md index 149027238a434b6..9789a61439c532c 100644 --- a/files/en-us/web/api/window/window/index.md +++ b/files/en-us/web/api/window/window/index.md @@ -31,7 +31,7 @@ In web pages, the window object is also a _global object_. This means: 2. You can access the built-in properties of the window object without having to prefix them with `window.`: ```js - setTimeout("alert('Hi!')", 50); // equivalent to using window.setTimeout(). + setTimeout(() => alert("Hi!"), 50); // equivalent to using window.setTimeout() and window.alert(). alert(window === window.window); // displays "true" ``` diff --git a/files/en-us/web/api/window_management_api/index.md b/files/en-us/web/api/window_management_api/index.md index d583e1a42aeb686..6c668a42c84ac01 100644 --- a/files/en-us/web/api/window_management_api/index.md +++ b/files/en-us/web/api/window_management_api/index.md @@ -45,7 +45,7 @@ The Window Management API is useful in cases such as: ## Permissions policy integration -The {{httpheader("Permissions-Policy/window-management", "window-management")}} [Permissions-Policy](/en-US/docs/Web/HTTP/Permissions_Policy) can be used to control permission to use the Window Management API. Specifically: +The {{httpheader("Permissions-Policy/window-management", "window-management")}} [Permissions-Policy](/en-US/docs/Web/HTTP/Guides/Permissions_Policy) can be used to control permission to use the Window Management API. Specifically: - Usage of the {{domxref("Window.getScreenDetails()")}} method. If blocked, its {{jsxref("Promise")}} will reject with a `NotAllowedError` exception. - Querying the {{domxref("Screen.isExtended", "Window.screen.isExtended")}} property. If blocked, it will always return `false`. diff --git a/files/en-us/web/api/window_management_api/using/index.md b/files/en-us/web/api/window_management_api/using/index.md index 3a84ad84646d207..c93b67ecfaa2c10 100644 --- a/files/en-us/web/api/window_management_api/using/index.md +++ b/files/en-us/web/api/window_management_api/using/index.md @@ -49,9 +49,9 @@ You'll still need to use {{domxref("Window.open()")}} to open and manage windows ```js // Array to hold references to the currently open windows -let windowRefs = []; +const windowRefs = []; -// ... +// … function openWindow(left, top, width, height, url) { const windowFeatures = `left=${left},top=${top},width=${width},height=${height}`; @@ -94,7 +94,7 @@ openWindow( sites[1].url, ); -// ... +// … ``` ### Closing all windows @@ -140,7 +140,7 @@ In modern browsers, a separate user gesture event is required for each `Window.o In our demo application, we have gone for the third option. Our `openWindow()` function contains the following section: ```js -// ... +// … if (windowRef === null) { // If the browser is blocking new windows, close any windows that were @@ -152,7 +152,7 @@ if (windowRef === null) { windowRefs.push(windowRef); } -// ... +// … ``` If the browser blocks a new window, the resulting `windowRef` will be `null`. In this case we run our `closeAllWindows()` function to close any windows that _did_ manage to open before the blocking started, and show a [popover element](/en-US/docs/Web/API/Popover_API) that explains how to disable the popup blocker. diff --git a/files/en-us/web/api/windowcontrolsoverlay/geometrychange_event/index.md b/files/en-us/web/api/windowcontrolsoverlay/geometrychange_event/index.md index 7ba10aa14fc0c25..cc002ccab6428a0 100644 --- a/files/en-us/web/api/windowcontrolsoverlay/geometrychange_event/index.md +++ b/files/en-us/web/api/windowcontrolsoverlay/geometrychange_event/index.md @@ -18,10 +18,10 @@ This only applies to Progressive Web Apps installed on desktop operating systems Use the event name in methods like {{domxref("EventTarget.addEventListener", "addEventListener()")}}, or set an event handler property. -```js -addEventListener("geometrychange", (event) => {}); +```js-nolint +addEventListener("geometrychange", (event) => { }) -ongeometrychange = (event) => {}; +ongeometrychange = (event) => { } ``` ## Event type diff --git a/files/en-us/web/api/windowsharedstorage/run/index.md b/files/en-us/web/api/windowsharedstorage/run/index.md index 4f96292e44016f1..35bc8069d0815be 100644 --- a/files/en-us/web/api/windowsharedstorage/run/index.md +++ b/files/en-us/web/api/windowsharedstorage/run/index.md @@ -62,7 +62,7 @@ async function measureUniqueReach() { measureUniqueReach(); ``` -See [Unique reach measurement](https://developers.google.com/privacy-sandbox/private-advertising/private-aggregation/unique-reach) for a full explanation of this example. See [Shared Storage API](/en-US/docs/Web/API/Shared_Storage_API) for more examples. +See [Unique reach measurement](https://privacysandbox.google.com/private-advertising/private-aggregation/unique-reach) for a full explanation of this example. See [Shared Storage API](/en-US/docs/Web/API/Shared_Storage_API) for more examples. ## Specifications diff --git a/files/en-us/web/api/worker/error_event/index.md b/files/en-us/web/api/worker/error_event/index.md index 99e58c23451412c..b8a951e80668c0b 100644 --- a/files/en-us/web/api/worker/error_event/index.md +++ b/files/en-us/web/api/worker/error_event/index.md @@ -14,10 +14,10 @@ The **`error`** event of the {{domxref("Worker")}} interface fires when an error Use the event name in methods like {{domxref("EventTarget.addEventListener", "addEventListener()")}}, or set an event handler property. -```js -addEventListener("error", (event) => {}); +```js-nolint +addEventListener("error", (event) => { }) -onerror = (event) => {}; +onerror = (event) => { } ``` ## Event type diff --git a/files/en-us/web/api/worker/message_event/index.md b/files/en-us/web/api/worker/message_event/index.md index 17bbf23c9ee8139..e9b9ea6fccf2bd6 100644 --- a/files/en-us/web/api/worker/message_event/index.md +++ b/files/en-us/web/api/worker/message_event/index.md @@ -8,7 +8,7 @@ browser-compat: api.Worker.message_event {{APIRef("Web Workers API")}}{{AvailableInWorkers("window_and_worker_except_service")}} -The `message` event is fired on a {{domxref('Worker')}} object when the worker's parent receives a message from its worker (i.e. when the worker sends a message using [`DedicatedWorkerGlobalScope.postMessage()`](/en-US/docs/Web/API/DedicatedWorkerGlobalScope/postMessage)). +The `message` event is fired on a {{domxref('Worker')}} object when the worker's parent receives a message from its worker (i.e., when the worker sends a message using [`DedicatedWorkerGlobalScope.postMessage()`](/en-US/docs/Web/API/DedicatedWorkerGlobalScope/postMessage)). This event is not cancellable and does not bubble. @@ -16,10 +16,10 @@ This event is not cancellable and does not bubble. Use the event name in methods like {{domxref("EventTarget.addEventListener", "addEventListener()")}}, or set an event handler property. -```js -addEventListener("message", (event) => {}); +```js-nolint +addEventListener("message", (event) => { }) -onmessage = (event) => {}; +onmessage = (event) => { } ``` ## Event type @@ -41,7 +41,7 @@ _This interface also inherits properties from its parent, {{domxref("Event")}}._ - {{domxref("MessageEvent.source")}} {{ReadOnlyInline}} - : A `MessageEventSource` (which can be a {{glossary("WindowProxy")}}, {{domxref("MessagePort")}}, or {{domxref("ServiceWorker")}} object) representing the message emitter. - {{domxref("MessageEvent.ports")}} {{ReadOnlyInline}} - - : An array of {{domxref("MessagePort")}} objects representing the ports associated with the channel the message is being sent through (where appropriate, e.g. in channel messaging or when sending a message to a shared worker). + - : An array of {{domxref("MessagePort")}} objects representing the ports associated with the channel the message is being sent through (where appropriate, e.g., in channel messaging or when sending a message to a shared worker). ## Examples diff --git a/files/en-us/web/api/worker/messageerror_event/index.md b/files/en-us/web/api/worker/messageerror_event/index.md index ed46ca129419913..964ad600df545b3 100644 --- a/files/en-us/web/api/worker/messageerror_event/index.md +++ b/files/en-us/web/api/worker/messageerror_event/index.md @@ -16,10 +16,10 @@ This event is not cancellable and does not bubble. Use the event name in methods like {{domxref("EventTarget.addEventListener", "addEventListener()")}}, or set an event handler property. -```js -addEventListener("messageerror", (event) => {}); +```js-nolint +addEventListener("messageerror", (event) => { }) -onmessageerror = (event) => {}; +onmessageerror = (event) => { } ``` ## Event type @@ -41,7 +41,7 @@ _This interface also inherits properties from its parent, {{domxref("Event")}}._ - {{domxref("MessageEvent.source")}} {{ReadOnlyInline}} - : A `MessageEventSource` (which can be a {{glossary("WindowProxy")}}, {{domxref("MessagePort")}}, or {{domxref("ServiceWorker")}} object) representing the message emitter. - {{domxref("MessageEvent.ports")}} {{ReadOnlyInline}} - - : An array of {{domxref("MessagePort")}} objects representing the ports associated with the channel the message is being sent through (where appropriate, e.g. in channel messaging or when sending a message to a shared worker). + - : An array of {{domxref("MessagePort")}} objects representing the ports associated with the channel the message is being sent through (where appropriate, e.g., in channel messaging or when sending a message to a shared worker). ## Examples diff --git a/files/en-us/web/api/worker/postmessage/index.md b/files/en-us/web/api/worker/postmessage/index.md index fb464e60447b495..842a8a88082f62e 100644 --- a/files/en-us/web/api/worker/postmessage/index.md +++ b/files/en-us/web/api/worker/postmessage/index.md @@ -50,7 +50,7 @@ const myWorker = new Worker("worker.js"); [first, second].forEach((input) => { input.onchange = () => { - myWorker.port.postMessage([first.value, second.value]); + myWorker.postMessage([first.value, second.value]); console.log("Message posted to worker"); }; }); @@ -71,7 +71,7 @@ This minimum example has `main` create an `ArrayBuffer` and transfer it to `myWo const myWorker = new Worker("myWorker.js"); // listen for myWorker to transfer the buffer back to main -myWorker.addEventListener("message", function handleMessageFromWorker(msg) { +myWorker.addEventListener("message", (msg) => { console.log("message from worker received in main:", msg); const bufTransferredBackFromWorker = msg.data; @@ -103,7 +103,7 @@ console.log( ```js // listen for main to transfer the buffer to myWorker -self.onmessage = function handleMessageFromMain(msg) { +self.onmessage = (msg) => { console.log("message from main received in worker:", msg); const bufTransferredFromMain = msg.data; diff --git a/files/en-us/web/api/worker/worker/index.md b/files/en-us/web/api/worker/worker/index.md index ea769d8ae3bd370..99599ab8dc5e7a8 100644 --- a/files/en-us/web/api/worker/worker/index.md +++ b/files/en-us/web/api/worker/worker/index.md @@ -49,10 +49,10 @@ new Worker(url, options) ### Exceptions - `SecurityError` {{domxref("DOMException")}} - - : Thrown if the document is not allowed to start workers, e.g. if the URL has an invalid syntax or if the same-origin policy is violated. + - : Thrown if the document is not allowed to start workers, e.g., if the URL has an invalid syntax or if the same-origin policy is violated. - `NetworkError` {{domxref("DOMException")}} - : Thrown if the MIME type of the worker script is incorrect. It _should_ always be `text/javascript` - (for historical reasons [other JavaScript MIME types](/en-US/docs/Web/HTTP/MIME_types#legacy_javascript_mime_types) may be accepted). + (for historical reasons [other JavaScript MIME types](/en-US/docs/Web/HTTP/Guides/MIME_types#legacy_javascript_mime_types) may be accepted). - `SyntaxError` {{domxref("DOMException")}} - : Thrown if _aURL_ cannot be parsed. diff --git a/files/en-us/web/api/workerglobalscope/crossoriginisolated/index.md b/files/en-us/web/api/workerglobalscope/crossoriginisolated/index.md index beaf45dc9a256a1..bfbdac47fb23911 100644 --- a/files/en-us/web/api/workerglobalscope/crossoriginisolated/index.md +++ b/files/en-us/web/api/workerglobalscope/crossoriginisolated/index.md @@ -10,7 +10,7 @@ browser-compat: api.crossOriginIsolated The **`crossOriginIsolated`** read-only property of the {{domxref("WorkerGlobalScope")}} interface returns a boolean value that indicates whether the document is cross-origin isolated. -A cross-origin isolated document only shares its {{glossary("Browsing context", "browsing context group")}} with same-origin documents in popups and navigations, and resources (both same-origin and cross-origin) that the document has opted into using via [CORS](/en-US/docs/Web/HTTP/CORS) (and [COEP](/en-US/docs/Web/HTTP/Headers/Cross-Origin-Embedder-Policy) for `<iframe>`). +A cross-origin isolated document only shares its {{glossary("Browsing context", "browsing context group")}} with same-origin documents in popups and navigations, and resources (both same-origin and cross-origin) that the document has opted into using via [CORS](/en-US/docs/Web/HTTP/Guides/CORS) (and [COEP](/en-US/docs/Web/HTTP/Reference/Headers/Cross-Origin-Embedder-Policy) for `<iframe>`). The relationship between a cross-origin opener of the document or any cross-origin popups that it opens are severed. The document may also be hosted in a separate OS process alongside other documents with which it can communicate by operating on shared memory. This mitigates the risk of side-channel attacks and cross-origin attacks referred to as [XS-Leaks](https://xsleaks.dev/). diff --git a/files/en-us/web/api/workerglobalscope/error_event/index.md b/files/en-us/web/api/workerglobalscope/error_event/index.md index dccdadda00d58e8..426fb665f38e6e9 100644 --- a/files/en-us/web/api/workerglobalscope/error_event/index.md +++ b/files/en-us/web/api/workerglobalscope/error_event/index.md @@ -14,10 +14,10 @@ The **`error`** event of the {{domxref("WorkerGlobalScope")}} interface fires wh Use the event name in methods like {{domxref("EventTarget.addEventListener", "addEventListener()")}}, or set an event handler property. -```js -addEventListener("error", (event) => {}); +```js-nolint +addEventListener("error", (event) => { }) -onerror = (message, filename, lineno, colno, error) => {}; +onerror = (message, filename, lineno, colno, error) => { } ``` > [!NOTE] diff --git a/files/en-us/web/api/workerglobalscope/fetch/index.md b/files/en-us/web/api/workerglobalscope/fetch/index.md index 6cbc36969bbcd04..fa174d1326f73c8 100644 --- a/files/en-us/web/api/workerglobalscope/fetch/index.md +++ b/files/en-us/web/api/workerglobalscope/fetch/index.md @@ -16,7 +16,7 @@ A `fetch()` promise only rejects when the request fails, for example, because of A `fetch()` promise _does not_ reject if the server responds with HTTP status codes that indicate errors (`404`, `504`, etc.). Instead, a `then()` handler must check the {{domxref("Response.ok")}} and/or {{domxref("Response.status")}} properties. -The `fetch()` method is controlled by the `connect-src` directive of [Content Security Policy](/en-US/docs/Web/HTTP/Headers/Content-Security-Policy) rather than the directive of the resources it's retrieving. +The `fetch()` method is controlled by the `connect-src` directive of [Content Security Policy](/en-US/docs/Web/HTTP/Reference/Headers/Content-Security-Policy) rather than the directive of the resources it's retrieving. > [!NOTE] > The `fetch()` method's parameters are identical to those of the {{domxref("Request.Request","Request()")}} constructor. @@ -50,7 +50,7 @@ A {{jsxref("Promise")}} that resolves to a {{domxref("Response")}} object. - `AbortError` {{domxref("DOMException")}} - : The request was aborted due to a call to the {{domxref("AbortController")}} {{domxref("AbortController.abort", "abort()")}} method. - `NotAllowedError` {{domxref("DOMException")}} - - : Thrown if use of the [Topics API](/en-US/docs/Web/API/Topics_API) is specifically disallowed by a {{httpheader('Permissions-Policy/browsing-topics','browsing-topics')}} [Permissions Policy](/en-US/docs/Web/HTTP/Permissions_Policy), and a `fetch()` request was made with `browsingTopics: true`. + - : Thrown if use of the [Topics API](/en-US/docs/Web/API/Topics_API) is specifically disallowed by a {{httpheader('Permissions-Policy/browsing-topics','browsing-topics')}} [Permissions Policy](/en-US/docs/Web/HTTP/Guides/Permissions_Policy), and a `fetch()` request was made with `browsingTopics: true`. - {{jsxref("TypeError")}} - : An error when the fetch operation could not be performed. See {{domxref("Window.fetch()")}} exceptions for a list of reasons why this error can occur. @@ -72,5 +72,5 @@ See {{domxref("Window.fetch", "fetch()")}} for examples. - {{domxref("Window.fetch()")}} - [Fetch API](/en-US/docs/Web/API/Fetch_API) - [ServiceWorker API](/en-US/docs/Web/API/Service_Worker_API) -- [HTTP access control (CORS)](/en-US/docs/Web/HTTP/CORS) +- [HTTP access control (CORS)](/en-US/docs/Web/HTTP/Guides/CORS) - [HTTP](/en-US/docs/Web/HTTP) diff --git a/files/en-us/web/api/workerglobalscope/importscripts/index.md b/files/en-us/web/api/workerglobalscope/importscripts/index.md index 46b1d04275f8055..109544ca33100db 100644 --- a/files/en-us/web/api/workerglobalscope/importscripts/index.md +++ b/files/en-us/web/api/workerglobalscope/importscripts/index.md @@ -30,7 +30,7 @@ None ({{jsxref("undefined")}}). ### Exceptions - `NetworkError` - - : Imported scripts were served without a `text/javascript` MIME type or without one of the permitted [legacy JavaScript MIME types](/en-US/docs/Web/HTTP/MIME_types#legacy_javascript_mime_types). + - : Imported scripts were served without a `text/javascript` MIME type or without one of the permitted [legacy JavaScript MIME types](/en-US/docs/Web/HTTP/Guides/MIME_types#legacy_javascript_mime_types). - {{jsxref("TypeError")}} - : Thrown if the current {{domxref("WorkerGlobalScope")}} is a module. Use [`import`](/en-US/docs/Web/JavaScript/Reference/Statements/import) instead. diff --git a/files/en-us/web/api/workerglobalscope/index.md b/files/en-us/web/api/workerglobalscope/index.md index 33a6f619eba72e4..a51ab6546b33e29 100644 --- a/files/en-us/web/api/workerglobalscope/index.md +++ b/files/en-us/web/api/workerglobalscope/index.md @@ -59,7 +59,7 @@ _This interface inherits methods from the {{domxref("EventTarget")}} interface._ - {{domxref("WorkerGlobalScope.createImageBitmap()")}} - : Accepts a variety of different image sources, and returns a {{jsxref("Promise")}} which resolves to an {{domxref("ImageBitmap")}}. Optionally the source is cropped to the rectangle of pixels originating at _(sx, sy)_ with width sw, and height sh. - {{domxref("WorkerGlobalScope.dump()")}} {{deprecated_inline}} {{non-standard_inline}} - - : Allows you to write a message to stdout — i.e. in your terminal. This is the same as Firefox's {{domxref("window.dump")}}, but for workers. + - : Allows you to write a message to stdout — i.e., in your terminal. This is the same as Firefox's {{domxref("window.dump")}}, but for workers. - {{domxref("WorkerGlobalScope.fetch()")}} - : Starts the process of fetching a resource from the network. - {{domxref("WorkerGlobalScope.importScripts()")}} @@ -88,7 +88,7 @@ _This interface inherits methods from the {{domxref("EventTarget")}} interface._ - {{domxref("WorkerGlobalScope/rejectionhandled_event", "rejectionhandled")}} - : Fired on handled {{jsxref("Promise")}} rejection events. - {{domxref("WorkerGlobalScope/securitypolicyviolation_event", "securitypolicyviolation")}} - - : Fired when a [Content Security Policy](/en-US/docs/Web/HTTP/CSP) is violated. + - : Fired when a [Content Security Policy](/en-US/docs/Web/HTTP/Guides/CSP) is violated. - {{domxref("WorkerGlobalScope/unhandledrejection_event", "unhandledrejection")}} - : Fired on unhandled {{jsxref("Promise")}} rejection events. diff --git a/files/en-us/web/api/workerglobalscope/languagechange_event/index.md b/files/en-us/web/api/workerglobalscope/languagechange_event/index.md index 6e33ad5f4b2f63b..41eb420f52b13a3 100644 --- a/files/en-us/web/api/workerglobalscope/languagechange_event/index.md +++ b/files/en-us/web/api/workerglobalscope/languagechange_event/index.md @@ -16,10 +16,10 @@ This event is not cancelable and does not bubble. Use the event name in methods like {{domxref("EventTarget.addEventListener", "addEventListener()")}}, or set an event handler property. -```js -addEventListener("languagechange", (event) => {}); +```js-nolint +addEventListener("languagechange", (event) => { }) -onlanguagechange = (event) => {}; +onlanguagechange = (event) => { } ``` ## Event type diff --git a/files/en-us/web/api/workerglobalscope/offline_event/index.md b/files/en-us/web/api/workerglobalscope/offline_event/index.md index 29b01f423d3824f..2fa12ab28154f81 100644 --- a/files/en-us/web/api/workerglobalscope/offline_event/index.md +++ b/files/en-us/web/api/workerglobalscope/offline_event/index.md @@ -14,10 +14,10 @@ The **`offline`** event of the {{domxref("WorkerGlobalScope")}} fires when the d Use the event name in methods like {{domxref("EventTarget.addEventListener", "addEventListener()")}}, or set an event handler property. -```js -addEventListener("offline", (event) => {}); +```js-nolint +addEventListener("offline", (event) => { }) -onoffline = (event) => {}; +onoffline = (event) => { } ``` ## Event type diff --git a/files/en-us/web/api/workerglobalscope/online_event/index.md b/files/en-us/web/api/workerglobalscope/online_event/index.md index aab51c1bf63d72b..2b2e8a54827822d 100644 --- a/files/en-us/web/api/workerglobalscope/online_event/index.md +++ b/files/en-us/web/api/workerglobalscope/online_event/index.md @@ -14,10 +14,10 @@ The **`online`** event of the {{domxref("WorkerGlobalScope")}} fires when the de Use the event name in methods like {{domxref("EventTarget.addEventListener", "addEventListener()")}}, or set an event handler property. -```js -addEventListener("online", (event) => {}); +```js-nolint +addEventListener("online", (event) => { }) -ononline = (event) => {}; +ononline = (event) => { } ``` ## Event type diff --git a/files/en-us/web/api/workerglobalscope/origin/index.md b/files/en-us/web/api/workerglobalscope/origin/index.md index ce3f99b77126d14..de01930f5a1ea40 100644 --- a/files/en-us/web/api/workerglobalscope/origin/index.md +++ b/files/en-us/web/api/workerglobalscope/origin/index.md @@ -24,7 +24,7 @@ self.onmessage = () => { }; ``` -If the origin is not a scheme/host/port tuple (say you are trying to run it locally, i.e. via `file://` URL), `origin` will return the string `"null"`. +If the origin is not a scheme/host/port tuple (say you are trying to run it locally, i.e., via `file://` URL), `origin` will return the string `"null"`. ## Specifications diff --git a/files/en-us/web/api/workerglobalscope/rejectionhandled_event/index.md b/files/en-us/web/api/workerglobalscope/rejectionhandled_event/index.md index 7938b8a63f9d496..f268c2652869fcc 100644 --- a/files/en-us/web/api/workerglobalscope/rejectionhandled_event/index.md +++ b/files/en-us/web/api/workerglobalscope/rejectionhandled_event/index.md @@ -16,9 +16,10 @@ This can be used in debugging and for general application resiliency, in tandem Use the event name in methods like {{domxref("EventTarget.addEventListener", "addEventListener()")}}, or set an event handler property. -```js -self.addEventListener("rejectionhandled", (event) => {}); -self.onrejectionhandled = (event) => {}; +```js-nolint +addEventListener("rejectionhandled", (event) => { }) + +onrejectionhandled = (event) => { } ``` ## Event type diff --git a/files/en-us/web/api/workerglobalscope/securitypolicyviolation_event/index.md b/files/en-us/web/api/workerglobalscope/securitypolicyviolation_event/index.md index 9614ce07d7be169..10fcc455c26a45c 100644 --- a/files/en-us/web/api/workerglobalscope/securitypolicyviolation_event/index.md +++ b/files/en-us/web/api/workerglobalscope/securitypolicyviolation_event/index.md @@ -8,7 +8,7 @@ browser-compat: api.WorkerGlobalScope.securitypolicyviolation_event {{APIRef}}{{AvailableInWorkers("worker")}} -The **`securitypolicyviolation`** event is fired when a [Content Security Policy](/en-US/docs/Web/HTTP/CSP) is violated in a worker. +The **`securitypolicyviolation`** event is fired when a [Content Security Policy](/en-US/docs/Web/HTTP/Guides/CSP) is violated in a worker. The handler can be assigned using the `onsecuritypolicyviolation` event handler property or using {{domxref("EventTarget.addEventListener()")}}. @@ -16,10 +16,10 @@ The handler can be assigned using the `onsecuritypolicyviolation` event handler Use the event name in methods like {{domxref("EventTarget.addEventListener", "addEventListener()")}}, or set an event handler property. -```js -addEventListener("securitypolicyviolation", (event) => {}); +```js-nolint +addEventListener("securitypolicyviolation", (event) => { }) -onsecuritypolicyviolation = (event) => {}; +onsecuritypolicyviolation = (event) => { } ``` ## Event type @@ -54,4 +54,4 @@ self.addEventListener("securitypolicyviolation", (e) => { - The {{domxref("Document/securitypolicyviolation_event", "securitypolicyviolation")}} event of the {{domxref("Document")}} interface - The {{domxref("Element/securitypolicyviolation_event", "securitypolicyviolation")}} event of the {{domxref("Element")}} interface -- [HTTP > Content Security Policy](/en-US/docs/Web/HTTP/CSP) +- [HTTP > Content Security Policy](/en-US/docs/Web/HTTP/Guides/CSP) diff --git a/files/en-us/web/api/workerglobalscope/setinterval/index.md b/files/en-us/web/api/workerglobalscope/setinterval/index.md index 6ca7111820a2097..75a3e9276ca8f2c 100644 --- a/files/en-us/web/api/workerglobalscope/setinterval/index.md +++ b/files/en-us/web/api/workerglobalscope/setinterval/index.md @@ -10,8 +10,6 @@ browser-compat: api.setInterval The **`setInterval()`** method of the {{domxref("WorkerGlobalScope")}} interface repeatedly calls a function or executes a code snippet, with a fixed time delay between each call. -This method returns an interval ID which uniquely identifies the interval, so you can remove it later by calling {{domxref("WorkerGlobalScope.clearInterval", "clearInterval()")}}. - This method is also available in window contexts: for a detailed description of `setInterval()`, see the {{domxref("Window.setInterval()")}} page. ## Syntax @@ -42,9 +40,11 @@ setInterval(func, delay, arg1, arg2, /* …, */ argN) ### Return value -The returned `intervalID` is a numeric, non-zero value which identifies the timer created by the call to `setInterval()`; this value can be passed to {{domxref("WorkerGlobalScope.clearInterval", "clearInterval()")}} to cancel the interval. +The `setInterval()` method returns a positive integer (typically within the range of 1 to 2,147,483,647) that uniquely identifies the interval timer created by the call. This identifier, often referred to as an "interval ID", can be passed to {{domxref("Window.clearInterval", "clearInterval()")}} to stop the repeated execution of the specified function. + +Within the same global environment (e.g., a particular window or worker), the interval ID is ensured to remain unique and is not reused for any new interval timer as long as the original timer is still active. However, different global environments maintain their own independent pools of interval IDs. -It may be helpful to be aware that `setInterval()` and {{domxref("WorkerGlobalScope.setTimeout", "setTimeout()")}} share the same pool of IDs, and that `clearInterval()` and {{domxref("WorkerGlobalScope.clearTimeout", "clearTimeout()")}} can technically be used interchangeably. +Be aware that `setInterval()` and {{domxref("Window.setTimeout", "setTimeout()")}} share the same pool of IDs, and that `clearInterval()` and {{domxref("Window.clearTimeout", "clearTimeout()")}} can technically be used interchangeably. For clarity, however, you should try to always match them to avoid confusion when maintaining your code. > [!NOTE] diff --git a/files/en-us/web/api/workerglobalscope/settimeout/index.md b/files/en-us/web/api/workerglobalscope/settimeout/index.md index 74f33d44cca565a..719f530fa0e3b44 100644 --- a/files/en-us/web/api/workerglobalscope/settimeout/index.md +++ b/files/en-us/web/api/workerglobalscope/settimeout/index.md @@ -48,12 +48,9 @@ setTimeout(functionRef, delay, param1, param2, /* …, */ paramN) ### Return value -The returned `timeoutID` is a positive integer value which -identifies the timer created by the call to `setTimeout()`. This value can be -passed to {{domxref("WorkerGlobalScope.clearTimeout","clearTimeout()")}} to -cancel the timeout. +The `setTimeout()` method returns a positive integer (typically within the range of 1 to 2,147,483,647) that uniquely identifies the timer created by the call. This identifier, often referred to as a "timeout ID", can be passed to {{domxref("Window.clearTimeout","clearTimeout()")}} to cancel the timer. -It is guaranteed that a `timeoutID` value will never be reused by a subsequent call to `setTimeout()` or `setInterval()` on the same worker while the timer is still active. However, different objects use separate pools of IDs. +Within the same global environment (e.g., a specific window or worker) the timeout ID is guaranteed not to be reused for any new timer as long as the original timer remains active. However, separate global environments maintain their own independent pools of timer IDs. ## Description diff --git a/files/en-us/web/api/workerglobalscope/unhandledrejection_event/index.md b/files/en-us/web/api/workerglobalscope/unhandledrejection_event/index.md index 7ba4f53378addc7..f00a9be7047ee35 100644 --- a/files/en-us/web/api/workerglobalscope/unhandledrejection_event/index.md +++ b/files/en-us/web/api/workerglobalscope/unhandledrejection_event/index.md @@ -16,9 +16,10 @@ This is useful for debugging and for providing fallback error handling for unexp Use the event name in methods like {{domxref("EventTarget.addEventListener", "addEventListener()")}}, or set an event handler property. -```js -self.addEventListener("unhandledrejection", (event) => {}); -self.onunhandledrejection = (event) => {}; +```js-nolint +addEventListener("unhandledrejection", (event) => { }) + +onunhandledrejection = (event) => { } ``` ## Event type diff --git a/files/en-us/web/api/workernavigator/gpu/index.md b/files/en-us/web/api/workernavigator/gpu/index.md index 588baaff3b5c88c..123a84298f508b6 100644 --- a/files/en-us/web/api/workernavigator/gpu/index.md +++ b/files/en-us/web/api/workernavigator/gpu/index.md @@ -32,7 +32,7 @@ async function init() { const device = await adapter.requestDevice(); - //... + // … } ``` diff --git a/files/en-us/web/api/workernavigator/hid/index.md b/files/en-us/web/api/workernavigator/hid/index.md index 7ddc683fbb3565f..689a2af2cd15327 100644 --- a/files/en-us/web/api/workernavigator/hid/index.md +++ b/files/en-us/web/api/workernavigator/hid/index.md @@ -13,7 +13,7 @@ browser-compat: api.WorkerNavigator.hid The **`WorkerNavigator.hid`** read-only property returns an {{domxref("HID")}} object providing methods for accessing HID device connections and events that fire when the user agent connects to or disconnects from a device. -Where a defined [Permissions Policy](/en-US/docs/Web/HTTP/Permissions_Policy) blocks WebHID usage, the `WorkerNavigator.hid` property will not be available. +Where a defined [Permissions Policy](/en-US/docs/Web/HTTP/Guides/Permissions_Policy) blocks WebHID usage, the `WorkerNavigator.hid` property will not be available. ## Value diff --git a/files/en-us/web/api/workernavigator/languages/index.md b/files/en-us/web/api/workernavigator/languages/index.md index d49ca41aaedb777..3368a9e119aeb65 100644 --- a/files/en-us/web/api/workernavigator/languages/index.md +++ b/files/en-us/web/api/workernavigator/languages/index.md @@ -22,7 +22,7 @@ When its value changes, as the user's preferred languages are changed a The `Accept-Language` HTTP header in every HTTP request from the user's browser uses the same value for the `navigator.languages` property except for -the extra `qvalues` (quality values) field (e.g. `en-US;q=0.8`). +the extra `qvalues` (quality values) field (e.g., `en-US;q=0.8`). ## Value @@ -33,8 +33,8 @@ An array or strings. You can run this insert a web worker: ```js -navigator.language; //"en-US" -navigator.languages; //["en-US", "zh-CN", "ja-JP"] +navigator.language; // "en-US" +navigator.languages; // ["en-US", "zh-CN", "ja-JP"] ``` ## Specifications diff --git a/files/en-us/web/api/worklet/addmodule/index.md b/files/en-us/web/api/worklet/addmodule/index.md index 7b50966c2fad2b0..f42778e3b04e82c 100644 --- a/files/en-us/web/api/worklet/addmodule/index.md +++ b/files/en-us/web/api/worklet/addmodule/index.md @@ -30,7 +30,7 @@ addModule(moduleURL, options) - `credentials` - : A {{domxref("Request.credentials")}} value that - indicates whether to send credentials (e.g. cookies and HTTP authentication) + indicates whether to send credentials (e.g., cookies and HTTP authentication) when loading the module. Can be one of `"omit"`, `"same-origin"`, or `"include"`. Defaults to `"same-origin"`. See also {{domxref("Request.credentials")}}. diff --git a/files/en-us/web/api/workletsharedstorage/get/index.md b/files/en-us/web/api/workletsharedstorage/get/index.md index f73ddf088c6b2fb..a665998143e5c21 100644 --- a/files/en-us/web/api/workletsharedstorage/get/index.md +++ b/files/en-us/web/api/workletsharedstorage/get/index.md @@ -49,10 +49,12 @@ The main page script: async function injectContent() { // Load the Shared Storage worklet - await window.sharedStorage.worklet.addModule('k-freq-measurement-worklet.js'); + await window.sharedStorage.worklet.addModule("k-freq-measurement-worklet.js"); // Run the K-frequency measurement operation - await window.sharedStorage.run('k-freq-measurement', { data: { kFreq: 3, contentId: 123 }); + await window.sharedStorage.run("k-freq-measurement", { + data: { kFreq: 3, contentId: 123 }, + }); } injectContent(); @@ -86,6 +88,7 @@ class KFreqMeasurementOperation { (await this.sharedStorage.get(hasReportedContentKey)) === "true"; const impressionCount = parseInt( (await this.sharedStorage.get(impressionCountKey)) || 0, + 10, ); // Do not report if a report has been sent already @@ -115,7 +118,7 @@ class KFreqMeasurementOperation { register("k-freq-measurement", KFreqMeasurementOperation); ``` -For more details about this example, see [K+ frequency measurement](https://developers.google.com/privacy-sandbox/private-advertising/private-aggregation/k-freq-reach). See the [Shared Storage API](/en-US/docs/Web/API/Shared_Storage_API) landing page for links to other examples. +For more details about this example, see [K+ frequency measurement](https://privacysandbox.google.com/private-advertising/private-aggregation/k-freq-reach). See the [Shared Storage API](/en-US/docs/Web/API/Shared_Storage_API) landing page for links to other examples. ## Specifications @@ -128,4 +131,4 @@ For more details about this example, see [K+ frequency measurement](https://deve ## See also - [Shared Storage API](/en-US/docs/Web/API/Shared_Storage_API) -- [Noise and scaling](https://developers.google.com/privacy-sandbox/private-advertising/private-aggregation/fundamentals#noise_and_scaling) on developers.google.com (2023) +- [Noise and scaling](https://privacysandbox.google.com/private-advertising/private-aggregation/fundamentals#noise_and_scaling) on privacysandbox.google.com (2023) diff --git a/files/en-us/web/api/workletsharedstorage/index.md b/files/en-us/web/api/workletsharedstorage/index.md index 955a6e3f9f2c7bf..e42448fc512ce1b 100644 --- a/files/en-us/web/api/workletsharedstorage/index.md +++ b/files/en-us/web/api/workletsharedstorage/index.md @@ -44,9 +44,9 @@ _`WorkletSharedStorage` inherits properties from its parent interface, {{domxref ### Passing contextual data via `setSharedStorageContext()` -You can use the [Private Aggregation API](https://developers.google.com/privacy-sandbox/private-advertising/private-aggregation) to create reports that combine event-level data inside fenced frames with contextual data from the embedding document. `setSharedStorageContext()` can be used to pass contextual data from the embedder to shared storage worklets initiated by the [Protected Audience API](https://developers.google.com/privacy-sandbox/private-advertising/protected-audience). +You can use the [Private Aggregation API](https://privacysandbox.google.com/private-advertising/private-aggregation) to create reports that combine event-level data inside fenced frames with contextual data from the embedding document. `setSharedStorageContext()` can be used to pass contextual data from the embedder to shared storage worklets initiated by the [Protected Audience API](https://privacysandbox.google.com/private-advertising/protected-audience). -In this example, we store data from both the embedding page and the fenced frame using [shared storage](https://developers.google.com/privacy-sandbox/private-advertising/shared-storage). +In this example, we store data from both the embedding page and the fenced frame using [shared storage](https://privacysandbox.google.com/private-advertising/shared-storage). On the embedding page, we set a mock event ID as the shared storage context using `setSharedStorageContext()`: @@ -80,8 +80,12 @@ In the `reporting-worklet.js` worklet, we read the embedding document's event ID ```js class ReportingOperation { - convertEventIdToBucket(eventId) { ... } - convertEventPayloadToValue(info) { ... } + convertEventIdToBucket(eventId) { + // … + } + convertEventPayloadToValue(info) { + // … + } async run(data) { // Data from the embedder @@ -92,12 +96,12 @@ class ReportingOperation { privateAggregation.sendHistogramReport({ bucket: convertEventIdToBucket(eventId), - value: convertEventPayloadToValue(eventPayload) + value: convertEventPayloadToValue(eventPayload), }); } } -register('send-report', ReportingOperation); +register("send-report", ReportingOperation); ``` ## Specifications diff --git a/files/en-us/web/api/writablestream/abort/index.md b/files/en-us/web/api/writablestream/abort/index.md index 7bbbc7877441f20..18eba18903eff4c 100644 --- a/files/en-us/web/api/writablestream/abort/index.md +++ b/files/en-us/web/api/writablestream/abort/index.md @@ -36,19 +36,19 @@ A {{jsxref("Promise")}}, which fulfills with the value given in the `reason` par const writableStream = new WritableStream( { write(chunk) { - // ... + // … }, close() { - // ... + // … }, abort(err) { - // ... + // … }, }, queuingStrategy, ); -// ... +// … // abort the stream later on, when required writableStream.abort(); diff --git a/files/en-us/web/api/writablestream/close/index.md b/files/en-us/web/api/writablestream/close/index.md index 4b8d8633806b5b6..ed91b3e4b0c9c0b 100644 --- a/files/en-us/web/api/writablestream/close/index.md +++ b/files/en-us/web/api/writablestream/close/index.md @@ -64,7 +64,7 @@ function sendMessage(message, writableStream) { // defaultWriter is of type WritableStreamDefaultWriter const defaultWriter = writableStream.getWriter(); const encoder = new TextEncoder(); - const encoded = encoder.encode(message, { stream: true }); + const encoded = encoder.encode(message); encoded.forEach((chunk) => { defaultWriter.ready .then(() => { diff --git a/files/en-us/web/api/writablestream/getwriter/index.md b/files/en-us/web/api/writablestream/getwriter/index.md index 77736dab76fe31d..d6b2613aa03639b 100644 --- a/files/en-us/web/api/writablestream/getwriter/index.md +++ b/files/en-us/web/api/writablestream/getwriter/index.md @@ -44,7 +44,7 @@ function sendMessage(message, writableStream) { // defaultWriter is of type WritableStreamDefaultWriter const defaultWriter = writableStream.getWriter(); const encoder = new TextEncoder(); - const encoded = encoder.encode(message, { stream: true }); + const encoded = encoder.encode(message); encoded.forEach((chunk) => { defaultWriter.ready .then(() => defaultWriter.write(chunk)) diff --git a/files/en-us/web/api/writablestream/index.md b/files/en-us/web/api/writablestream/index.md index 258e226c4d8c63c..a1f8a9da6ad3192 100644 --- a/files/en-us/web/api/writablestream/index.md +++ b/files/en-us/web/api/writablestream/index.md @@ -33,88 +33,34 @@ This object comes with built-in backpressure and queuing. ## Examples -The following example illustrates several features of this interface. It shows the creation of the `WritableStream` with a custom sink and an API-supplied queueing strategy. It then calls a function called `sendMessage()`, passing the newly created stream and a string. Inside this function it calls the stream's `getWriter()` method, which returns an instance of {{domxref("WritableStreamDefaultWriter")}}. A `forEach()` call is used to write each chunk of the string to the stream. Finally, `write()` and `close()` return promises that are processed to deal with success or failure of chunks and streams. +The following example illustrates several features of this interface. It creates the `WritableStream` with a custom sink. It then calls the stream's `getWriter()` method, which returns an instance of {{domxref("WritableStreamDefaultWriter")}}. Next, several strings are written to the stream. Finally, `close()` returns a promise that resolves when all the writes have successfully completed. ```js -const list = document.querySelector("ul"); - -function sendMessage(message, writableStream) { - // defaultWriter is of type WritableStreamDefaultWriter - const defaultWriter = writableStream.getWriter(); - const encoder = new TextEncoder(); - const encoded = encoder.encode(message); - encoded.forEach((chunk) => { - defaultWriter.ready - .then(() => defaultWriter.write(chunk)) - .then(() => { - console.log("Chunk written to sink."); - }) - .catch((err) => { - console.log("Chunk error:", err); - }); - }); - // Call ready again to ensure that all chunks are written - // before closing the writer. - defaultWriter.ready - .then(() => { - defaultWriter.close(); - }) - .then(() => { - console.log("All chunks written"); - }) - .catch((err) => { - console.log("Stream error:", err); - }); -} - -const decoder = new TextDecoder("utf-8"); -const queuingStrategy = new CountQueuingStrategy({ highWaterMark: 1 }); -let result = ""; const writableStream = new WritableStream( + // Implement the sink { - // Implement the sink write(chunk) { - return new Promise((resolve, reject) => { - const buffer = new ArrayBuffer(1); - const view = new Uint8Array(buffer); - view[0] = chunk; - const decoded = decoder.decode(view, { stream: true }); - const listItem = document.createElement("li"); - listItem.textContent = `Chunk decoded: ${decoded}`; - list.appendChild(listItem); - result += decoded; - resolve(); - }); - }, - close() { - const listItem = document.createElement("li"); - listItem.textContent = `[MESSAGE RECEIVED] ${result}`; - list.appendChild(listItem); - }, - abort(err) { - console.log("Sink error:", err); + const textElement = document.getElementById("text-output"); + textElement.textContent += chunk; }, }, - queuingStrategy, ); -sendMessage("Hello, world.", writableStream); -``` - -You can find the full code in our [Simple writer example](https://mdn.github.io/dom-examples/streams/simple-writer/). +const writer = writableStream.getWriter(); -### Backpressure +try { + writer.write("Hello, "); + writer.write("world!\n"); + writer.write("This has been a demo!\n"); -Because of how [backpressure](/en-US/docs/Web/API/Streams_API/Concepts#backpressure) is supported in the API, its implementation in code may be less than obvious. -To see how backpressure is implemented look for three things: + await writer.close(); // wait for all chunks to be written + console.log("All chunks written"); +} catch (error) { + console.error("Stream error: ", error); +} +``` -- The `highWaterMark` property, which is set when creating the counting strategy using `new CountQueuingStrategy`, sets the maximum amount of data that the `WritableStream` instance will handle in a single `write()` operation. - In this example, it's the maximum amount of data that can be sent to `defaultWriter.write()`, in the `sendMessage` function. -- The `defaultWriter.ready` property returns a promise that resolves when the sink (the first property of the `WritableStream` constructor) is done writing data. - The data source can either write more data using `defaultWriter.write()` or call `defaultWriter.close()`, as demonstrated in the example above. - Calling `close()` too early can prevent data from being written. - This is why the example calls `defaultWriter.ready` twice. -- The {{jsxref("Promise")}} returned by the sink's `write()` method tells the `WritableStream` and its writer when to resolve `defaultWriter.ready`. +This example does not support the [backpressure](/en-US/docs/Web/API/Streams_API/Concepts#backpressure) feature of Streams. ## Specifications diff --git a/files/en-us/web/api/writablestream/locked/index.md b/files/en-us/web/api/writablestream/locked/index.md index c7709348d11ad25..8a923e3ceca5be4 100644 --- a/files/en-us/web/api/writablestream/locked/index.md +++ b/files/en-us/web/api/writablestream/locked/index.md @@ -20,19 +20,19 @@ A boolean value indicating whether or not the writable stream is locked. const writableStream = new WritableStream( { write(chunk) { - // ... + // … }, close() { - // ... + // … }, abort(err) { - // ... + // … }, }, queuingStrategy, ); -// ... +// … const writer = writableStream.getWriter(); diff --git a/files/en-us/web/api/writablestreamdefaultcontroller/error/index.md b/files/en-us/web/api/writablestreamdefaultcontroller/error/index.md index 38c5997c9d6e7a0..e0cd7c5d01d82db 100644 --- a/files/en-us/web/api/writablestreamdefaultcontroller/error/index.md +++ b/files/en-us/web/api/writablestreamdefaultcontroller/error/index.md @@ -49,13 +49,13 @@ const writableStream = new WritableStream({ controller.error("My error is broken"); }, write(chunk, controller) { - // ... + // … }, close(controller) { - // ... + // … }, abort(err) { - // ... + // … }, }); ``` diff --git a/files/en-us/web/api/writablestreamdefaultcontroller/index.md b/files/en-us/web/api/writablestreamdefaultcontroller/index.md index 0c9b65aa050132c..9fca799a3e824ec 100644 --- a/files/en-us/web/api/writablestreamdefaultcontroller/index.md +++ b/files/en-us/web/api/writablestreamdefaultcontroller/index.md @@ -34,13 +34,13 @@ const writableStream = new WritableStream({ controller.error("My stream is broken"); }, write(chunk, controller) { - // ... + // … }, close(controller) { - // ... + // … }, abort(err) { - // ... + // … }, }); ``` diff --git a/files/en-us/web/api/writablestreamdefaultwriter/abort/index.md b/files/en-us/web/api/writablestreamdefaultwriter/abort/index.md index db645f9cd714806..a3bbd1f1acce142 100644 --- a/files/en-us/web/api/writablestreamdefaultwriter/abort/index.md +++ b/files/en-us/web/api/writablestreamdefaultwriter/abort/index.md @@ -46,23 +46,23 @@ rejects with an error if the writer was inactive or the receiver stream is inval const writableStream = new WritableStream( { write(chunk) { - // ... + // … }, close() { - // ... + // … }, abort(err) { - // ... + // … }, }, queuingStrategy, ); -// ... +// … const writer = writableStream.getWriter(); -// ... +// … // abort the stream when desired await writer.abort("WritableStream aborted. Reason: ..."); diff --git a/files/en-us/web/api/writablestreamdefaultwriter/closed/index.md b/files/en-us/web/api/writablestreamdefaultwriter/closed/index.md index a66bdb3f00c3e50..47aab69baa9e7da 100644 --- a/files/en-us/web/api/writablestreamdefaultwriter/closed/index.md +++ b/files/en-us/web/api/writablestreamdefaultwriter/closed/index.md @@ -24,19 +24,19 @@ const writableStream = new WritableStream( { start(controller) {}, write(chunk, controller) { - // ... + // … }, close(controller) { - // ... + // … }, abort(err) { - // ... + // … }, }, queuingStrategy, ); -// ... +// … const writer = writableStream.getWriter(); diff --git a/files/en-us/web/api/writablestreamdefaultwriter/desiredsize/index.md b/files/en-us/web/api/writablestreamdefaultwriter/desiredsize/index.md index 9d0a13c60d9227c..e7bcf75f268d533 100644 --- a/files/en-us/web/api/writablestreamdefaultwriter/desiredsize/index.md +++ b/files/en-us/web/api/writablestreamdefaultwriter/desiredsize/index.md @@ -31,26 +31,26 @@ closed. const writableStream = new WritableStream( { write(chunk) { - // ... + // … }, close() { - // ... + // … }, abort(err) { - // ... + // … }, }, queuingStrategy, ); -// ... +// … const writer = writableStream.getWriter(); -// ... +// … // return stream's desired size -let size = writer.desiredSize; +const size = writer.desiredSize; ``` ## Specifications diff --git a/files/en-us/web/api/writablestreamdefaultwriter/releaselock/index.md b/files/en-us/web/api/writablestreamdefaultwriter/releaselock/index.md index a236b6e8a5e0a9b..12bc96226f9ed0a 100644 --- a/files/en-us/web/api/writablestreamdefaultwriter/releaselock/index.md +++ b/files/en-us/web/api/writablestreamdefaultwriter/releaselock/index.md @@ -34,23 +34,23 @@ None ({{jsxref("undefined")}}). const writableStream = new WritableStream( { write(chunk) { - // ... + // … }, close() { - // ... + // … }, abort(err) { - // ... + // … }, }, queuingStrategy, ); -// ... +// … const writer = writableStream.getWriter(); -// ... +// … // release writer's lock on the stream when desired writer.releaseLock(); diff --git a/files/en-us/web/api/writablestreamdefaultwriter/writablestreamdefaultwriter/index.md b/files/en-us/web/api/writablestreamdefaultwriter/writablestreamdefaultwriter/index.md index fc2e8ff59b33785..1b10ddefd6d940e 100644 --- a/files/en-us/web/api/writablestreamdefaultwriter/writablestreamdefaultwriter/index.md +++ b/files/en-us/web/api/writablestreamdefaultwriter/writablestreamdefaultwriter/index.md @@ -54,7 +54,7 @@ function sendMessage(message, writableStream) { // defaultWriter is of type WritableStreamDefaultWriter const defaultWriter = writableStream.getWriter(); const encoder = new TextEncoder(); - const encoded = encoder.encode(message, { stream: true }); + const encoded = encoder.encode(message); encoded.forEach((chunk) => { defaultWriter.ready .then(() => defaultWriter.write(chunk)) diff --git a/files/en-us/web/api/xmldocument/index.md b/files/en-us/web/api/xmldocument/index.md index d14e262cb5b0f23..749d80da3909a47 100644 --- a/files/en-us/web/api/xmldocument/index.md +++ b/files/en-us/web/api/xmldocument/index.md @@ -11,7 +11,7 @@ The **XMLDocument** interface represents an XML document. It inherits from the g {{InheritanceDiagram}} -## Property +## Instance properties _Also inherits properties from: {{DOMxRef("Document")}}_. diff --git a/files/en-us/web/api/xmlhttprequest/abort_event/index.md b/files/en-us/web/api/xmlhttprequest/abort_event/index.md index d7c1fa70bccc5bc..237dae4574338e7 100644 --- a/files/en-us/web/api/xmlhttprequest/abort_event/index.md +++ b/files/en-us/web/api/xmlhttprequest/abort_event/index.md @@ -14,10 +14,10 @@ The `abort` event is fired when a request has been aborted, for example because Use the event name in methods like {{domxref("EventTarget.addEventListener", "addEventListener()")}}, or set an event handler property. -```js -addEventListener("abort", (event) => {}); +```js-nolint +addEventListener("abort", (event) => { }) -onabort = (event) => {}; +onabort = (event) => { } ``` ## Event type @@ -112,7 +112,7 @@ function runXHR(url) { } xhrButtonSuccess.addEventListener("click", () => { - runXHR("my-picture.jpg"); + runXHR("/shared-assets/images/examples/balloon.jpg"); }); xhrButtonError.addEventListener("click", () => { @@ -120,7 +120,7 @@ xhrButtonError.addEventListener("click", () => { }); xhrButtonAbort.addEventListener("click", () => { - runXHR("my-picture.jpg").abort(); + runXHR("/shared-assets/images/examples/balloon.jpg").abort(); }); ``` diff --git a/files/en-us/web/api/xmlhttprequest/channel/index.md b/files/en-us/web/api/xmlhttprequest/channel/index.md deleted file mode 100644 index b5c8c6a281220cc..000000000000000 --- a/files/en-us/web/api/xmlhttprequest/channel/index.md +++ /dev/null @@ -1,12 +0,0 @@ ---- -title: "XMLHttpRequest: channel property" -short-title: channel -slug: Web/API/XMLHttpRequest/channel -page-type: web-api-instance-property -status: - - non-standard ---- - -{{APIRef("XMLHttpRequest API")}} {{AvailableInWorkers("window_and_worker_except_service")}} - -XMLHttpRequest.channel is an `nsIChannel` that used by the object when performing the request. This is `null` if the channel hasn't been created yet. In the case of a multi-part request, this is the initial channel, not the different parts in the multi-part request. **Requires elevated privileges to access.** diff --git a/files/en-us/web/api/xmlhttprequest/error_event/index.md b/files/en-us/web/api/xmlhttprequest/error_event/index.md index 474b5bcec0251de..e0a5be8ab18dfe2 100644 --- a/files/en-us/web/api/xmlhttprequest/error_event/index.md +++ b/files/en-us/web/api/xmlhttprequest/error_event/index.md @@ -14,10 +14,10 @@ The `error` event is fired when the request encountered an error. Use the event name in methods like {{domxref("EventTarget.addEventListener", "addEventListener()")}}, or set an event handler property. -```js -addEventListener("error", (event) => {}); +```js-nolint +addEventListener("error", (event) => { }) -onerror = (event) => {}; +onerror = (event) => { } ``` ## Event type diff --git a/files/en-us/web/api/xmlhttprequest/getallresponseheaders/index.md b/files/en-us/web/api/xmlhttprequest/getallresponseheaders/index.md index b9c0738fe526be6..158f4d097a2550d 100644 --- a/files/en-us/web/api/xmlhttprequest/getallresponseheaders/index.md +++ b/files/en-us/web/api/xmlhttprequest/getallresponseheaders/index.md @@ -72,7 +72,7 @@ request.open("GET", "foo.txt", true); request.send(); request.onreadystatechange = () => { - if (request.readyState === this.HEADERS_RECEIVED) { + if (request.readyState === request.HEADERS_RECEIVED) { // Get the raw header string const headers = request.getAllResponseHeaders(); diff --git a/files/en-us/web/api/xmlhttprequest/getresponseheader/index.md b/files/en-us/web/api/xmlhttprequest/getresponseheader/index.md index 3f1f1d9b8c63d85..fdb8c2672daf8aa 100644 --- a/files/en-us/web/api/xmlhttprequest/getresponseheader/index.md +++ b/files/en-us/web/api/xmlhttprequest/getresponseheader/index.md @@ -77,7 +77,7 @@ client.onreadystatechange = () => { ## See also - [Using XMLHttpRequest](/en-US/docs/Web/API/XMLHttpRequest_API/Using_XMLHttpRequest) -- [HTTP headers](/en-US/docs/Web/HTTP/Headers) +- [HTTP headers](/en-US/docs/Web/HTTP/Reference/Headers) - {{DOMxRef("XMLHttpRequest.getAllResponseHeaders", "getAllResponseHeaders()")}} - {{DOMxRef("XMLHttpRequest.response", "response")}} - Setting request headers: {{DOMxRef("XMLHttpRequest.setRequestHeader", "setRequestHeader()")}} diff --git a/files/en-us/web/api/xmlhttprequest/index.md b/files/en-us/web/api/xmlhttprequest/index.md index 1646194b13fd2d9..42dd486dcb5936d 100644 --- a/files/en-us/web/api/xmlhttprequest/index.md +++ b/files/en-us/web/api/xmlhttprequest/index.md @@ -37,7 +37,7 @@ _This interface also inherits properties of {{domxref("XMLHttpRequestEventTarget - {{domxref("XMLHttpRequest.responseXML")}} {{ReadOnlyInline}} - : Returns a {{domxref("Document")}} containing the response to the request, or `null` if the request was unsuccessful, has not yet been sent, or cannot be parsed as XML or HTML. Not available in [Web Workers](/en-US/docs/Web/API/Web_Workers_API). - {{domxref("XMLHttpRequest.status")}} {{ReadOnlyInline}} - - : Returns the [HTTP response status code](/en-US/docs/Web/HTTP/Status) of the request. + - : Returns the [HTTP response status code](/en-US/docs/Web/HTTP/Reference/Status) of the request. - {{domxref("XMLHttpRequest.statusText")}} {{ReadOnlyInline}} - : Returns a string containing the response string returned by the HTTP server. Unlike {{domxref("XMLHttpRequest.status")}}, this includes the entire text of the response message (`"OK"`, for example). @@ -54,14 +54,10 @@ _This interface also inherits properties of {{domxref("XMLHttpRequestEventTarget ### Non-standard properties -- {{domxref("XMLHttpRequest.channel")}} {{ReadOnlyInline}} - - : The channel used by the object when performing the request. -- {{domxref("XMLHttpRequest.mozAnon")}} {{ReadOnlyInline}} +- `XMLHttpRequest.mozAnon` {{ReadOnlyInline}} {{Non-standard_Inline}} - : A boolean. If true, the request will be sent without cookie and authentication headers. -- {{domxref("XMLHttpRequest.mozSystem")}} {{ReadOnlyInline}} +- `XMLHttpRequest.mozSystem` {{ReadOnlyInline}} {{Non-standard_Inline}} - : A boolean. If true, the same origin policy will not be enforced on the request. -- {{domxref("XMLHttpRequest.mozBackgroundRequest")}} - - : A boolean. It indicates whether or not the object represents a background service request. ## Instance methods diff --git a/files/en-us/web/api/xmlhttprequest/load_event/index.md b/files/en-us/web/api/xmlhttprequest/load_event/index.md index 9a40ba2cd4ed2b0..be6cef7177a1dad 100644 --- a/files/en-us/web/api/xmlhttprequest/load_event/index.md +++ b/files/en-us/web/api/xmlhttprequest/load_event/index.md @@ -14,10 +14,10 @@ The `load` event is fired when an {{domxref("XMLHttpRequest")}} transaction comp Use the event name in methods like {{domxref("EventTarget.addEventListener", "addEventListener()")}}, or set an event handler property. -```js -addEventListener("load", (event) => {}); +```js-nolint +addEventListener("load", (event) => { }) -onload = (event) => {}; +onload = (event) => { } ``` ## Event type diff --git a/files/en-us/web/api/xmlhttprequest/loadend_event/index.md b/files/en-us/web/api/xmlhttprequest/loadend_event/index.md index 25314ec9cbc4804..b5c640dfcd21a52 100644 --- a/files/en-us/web/api/xmlhttprequest/loadend_event/index.md +++ b/files/en-us/web/api/xmlhttprequest/loadend_event/index.md @@ -14,10 +14,10 @@ The **`loadend`** event is fired when a request has completed, whether successfu Use the event name in methods like {{domxref("EventTarget.addEventListener", "addEventListener()")}}, or set an event handler property. -```js -addEventListener("loadend", (event) => {}); +```js-nolint +addEventListener("loadend", (event) => { }) -onloadend = (event) => {}; +onloadend = (event) => { } ``` ## Event type diff --git a/files/en-us/web/api/xmlhttprequest/loadstart_event/index.md b/files/en-us/web/api/xmlhttprequest/loadstart_event/index.md index 7ee49b91a2886d9..1f31589897cc51d 100644 --- a/files/en-us/web/api/xmlhttprequest/loadstart_event/index.md +++ b/files/en-us/web/api/xmlhttprequest/loadstart_event/index.md @@ -14,10 +14,10 @@ The **`loadstart`** event is fired when a request has started to load data. Use the event name in methods like {{domxref("EventTarget.addEventListener", "addEventListener()")}}, or set an event handler property. -```js -addEventListener("loadstart", (event) => {}); +```js-nolint +addEventListener("loadstart", (event) => { }) -onloadstart = (event) => {}; +onloadstart = (event) => { } ``` ## Event type diff --git a/files/en-us/web/api/xmlhttprequest/mozanon/index.md b/files/en-us/web/api/xmlhttprequest/mozanon/index.md deleted file mode 100644 index ce8bee0e9c92ac5..000000000000000 --- a/files/en-us/web/api/xmlhttprequest/mozanon/index.md +++ /dev/null @@ -1,12 +0,0 @@ ---- -title: "XMLHttpRequest: mozAnon property" -short-title: mozAnon -slug: Web/API/XMLHttpRequest/mozAnon -page-type: web-api-instance-property -status: - - non-standard ---- - -{{APIRef("XMLHttpRequest API")}} {{AvailableInWorkers("window_and_worker_except_service")}} - -**`XMLHttpRequest.mozAnon`** is a boolean. If true, the request will be sent without cookies or authentication headers. diff --git a/files/en-us/web/api/xmlhttprequest/mozbackgroundrequest/index.md b/files/en-us/web/api/xmlhttprequest/mozbackgroundrequest/index.md deleted file mode 100644 index f02916b4fa8598b..000000000000000 --- a/files/en-us/web/api/xmlhttprequest/mozbackgroundrequest/index.md +++ /dev/null @@ -1,20 +0,0 @@ ---- -title: "XMLHttpRequest: mozBackgroundRequest property" -short-title: mozBackgroundRequest -slug: Web/API/XMLHttpRequest/mozBackgroundRequest -page-type: web-api-instance-property -status: - - non-standard ---- - -{{APIRef("XMLHttpRequest API")}} {{AvailableInWorkers("window_and_worker_except_service")}} - -> [!NOTE] -> This method is not available from Web content. It requires elevated privileges to access. - -**`XMLHttpRequest.mozBackgroundRequest`** is a Boolean, indicating if the object represents a background service request. If `true`, no load group is associated with the request, with security dialogs prevented from being shown to the user. - -In cases in where a security dialog (such as authentication or a bad certificate notification) would normally be shown, this request fails instead. - -> [!NOTE] -> This property must be set before calling `open()`. diff --git a/files/en-us/web/api/xmlhttprequest/mozsystem/index.md b/files/en-us/web/api/xmlhttprequest/mozsystem/index.md deleted file mode 100644 index c9caf410c4cdb85..000000000000000 --- a/files/en-us/web/api/xmlhttprequest/mozsystem/index.md +++ /dev/null @@ -1,12 +0,0 @@ ---- -title: "XMLHttpRequest: mozSystem property" -short-title: mozSystem -slug: Web/API/XMLHttpRequest/mozSystem -page-type: web-api-instance-property -status: - - non-standard ---- - -{{APIRef("XMLHttpRequest API")}} {{AvailableInWorkers("window_and_worker_except_service")}} - -**`mozSystem`** is a boolean. If true, the same origin policy is not enforced on the request. diff --git a/files/en-us/web/api/xmlhttprequest/open/index.md b/files/en-us/web/api/xmlhttprequest/open/index.md index 1a6a5c37fe3dd29..0215e34e07c2d4f 100644 --- a/files/en-us/web/api/xmlhttprequest/open/index.md +++ b/files/en-us/web/api/xmlhttprequest/open/index.md @@ -28,7 +28,7 @@ open(method, url, async, user, password) ### Parameters - `method` - - : The [HTTP request method](/en-US/docs/Web/HTTP/Methods) to use, such as + - : The [HTTP request method](/en-US/docs/Web/HTTP/Reference/Methods) to use, such as `"GET"`, `"POST"`, `"PUT"`, `"DELETE"`, etc. Ignored for non-HTTP(S) URLs. - `url` diff --git a/files/en-us/web/api/xmlhttprequest/overridemimetype/index.md b/files/en-us/web/api/xmlhttprequest/overridemimetype/index.md index 2117f9d6ac767a1..023f9e92ba5585c 100644 --- a/files/en-us/web/api/xmlhttprequest/overridemimetype/index.md +++ b/files/en-us/web/api/xmlhttprequest/overridemimetype/index.md @@ -41,7 +41,7 @@ server's stated type for the data being received. > [!NOTE] > If the server doesn't provide a -> [`Content-Type`](/en-US/docs/Web/HTTP/Headers/Content-Type) +> [`Content-Type`](/en-US/docs/Web/HTTP/Reference/Headers/Content-Type) > header, {{domxref("XMLHttpRequest")}} assumes that the MIME type is > `"text/xml"`. If the content isn't valid XML, an "XML Parsing Error: not > well-formed" error occurs. You can avoid this by calling diff --git a/files/en-us/web/api/xmlhttprequest/progress_event/index.md b/files/en-us/web/api/xmlhttprequest/progress_event/index.md index 98d43679949b1bd..2f446bcfd2a7f29 100644 --- a/files/en-us/web/api/xmlhttprequest/progress_event/index.md +++ b/files/en-us/web/api/xmlhttprequest/progress_event/index.md @@ -14,10 +14,10 @@ The **`progress`** event is fired periodically when a request receives more data Use the event name in methods like {{domxref("EventTarget.addEventListener", "addEventListener()")}}, or set an event handler property. -```js -addEventListener("progress", (event) => {}); +```js-nolint +addEventListener("progress", (event) => { }) -onprogress = (event) => {}; +onprogress = (event) => { } ``` ## Event type diff --git a/files/en-us/web/api/xmlhttprequest/readystatechange_event/index.md b/files/en-us/web/api/xmlhttprequest/readystatechange_event/index.md index 04f0ced8957dbca..6688588cec90c04 100644 --- a/files/en-us/web/api/xmlhttprequest/readystatechange_event/index.md +++ b/files/en-us/web/api/xmlhttprequest/readystatechange_event/index.md @@ -18,10 +18,10 @@ The `readystatechange` event is fired whenever the {{domxref("XMLHttpRequest.rea Use the event name in methods like {{domxref("EventTarget.addEventListener", "addEventListener()")}}, or set an event handler property. -```js -addEventListener("readystatechange", (event) => {}); +```js-nolint +addEventListener("readystatechange", (event) => { }) -onreadystatechange = (event) => {}; +onreadystatechange = (event) => { } ``` ## Event type diff --git a/files/en-us/web/api/xmlhttprequest/response/index.md b/files/en-us/web/api/xmlhttprequest/response/index.md index 0b7427ccb0ee223..ca8132e5fef8849 100644 --- a/files/en-us/web/api/xmlhttprequest/response/index.md +++ b/files/en-us/web/api/xmlhttprequest/response/index.md @@ -41,7 +41,7 @@ The content is handled as raw text data (since nothing here is overriding the de {{domxref("XMLHttpRequest.responseType", "responseType")}}). ```js -const url = "somePage.html"; //A local page +const url = "somePage.html"; // A local page function load(url, callback) { const xhr = new XMLHttpRequest(); diff --git a/files/en-us/web/api/xmlhttprequest/send/index.md b/files/en-us/web/api/xmlhttprequest/send/index.md index f2f35073d2f83ef..fd2b4aa87e9f4e4 100644 --- a/files/en-us/web/api/xmlhttprequest/send/index.md +++ b/files/en-us/web/api/xmlhttprequest/send/index.md @@ -44,7 +44,7 @@ send(body) If no value is specified for the body, a default value of `null` is used. -The best way to send binary content (e.g. in file uploads) is by using +The best way to send binary content (e.g., in file uploads) is by using a {{jsxref("TypedArray")}}, a {{jsxref("DataView")}} or a {{domxref("Blob")}} object in conjunction with the `send()` method. diff --git a/files/en-us/web/api/xmlhttprequest/setattributionreporting/index.md b/files/en-us/web/api/xmlhttprequest/setattributionreporting/index.md index 46947da966b0523..cc921faa75fb685 100644 --- a/files/en-us/web/api/xmlhttprequest/setattributionreporting/index.md +++ b/files/en-us/web/api/xmlhttprequest/setattributionreporting/index.md @@ -39,7 +39,7 @@ None (`undefined`). - `InvalidStateError` {{domxref("DOMException")}} - : Thrown if the associated {{domxref("XMLHttpRequest")}} has not yet been {{domxref("XMLHttpRequest.open", "opened", "", "nocode")}}, or has already been {{domxref("XMLHttpRequest.send", "sent", "", "nocode")}}. - `TypeError` {{domxref("DOMException")}} - - : Thrown if use of the [Attribution Reporting API](/en-US/docs/Web/API/Attribution_Reporting_API) is blocked by a [`attribution-reporting`](/en-US/docs/Web/HTTP/Headers/Permissions-Policy/attribution-reporting) {{httpheader("Permissions-Policy")}}. + - : Thrown if use of the [Attribution Reporting API](/en-US/docs/Web/API/Attribution_Reporting_API) is blocked by a [`attribution-reporting`](/en-US/docs/Web/HTTP/Reference/Headers/Permissions-Policy/attribution-reporting) {{httpheader("Permissions-Policy")}}. ## Examples diff --git a/files/en-us/web/api/xmlhttprequest/setrequestheader/index.md b/files/en-us/web/api/xmlhttprequest/setrequestheader/index.md index 8fff528b4980f38..05687d9a31aff89 100644 --- a/files/en-us/web/api/xmlhttprequest/setrequestheader/index.md +++ b/files/en-us/web/api/xmlhttprequest/setrequestheader/index.md @@ -18,7 +18,7 @@ If no {{HTTPHeader("Accept")}} header has been set using this, an `Accept` heade For security reasons, there are several {{Glossary("Forbidden_request_header", "forbidden request headers")}} whose values are controlled by the user agent. Any attempt to set a value for one of those headers from frontend JavaScript code will be ignored without warning or error. -In addition, the [`Authorization`](/en-US/docs/Web/HTTP/Headers/Authorization) HTTP header may be added to a request, but will be removed if the request is redirected cross-origin. +In addition, the [`Authorization`](/en-US/docs/Web/HTTP/Reference/Headers/Authorization) HTTP header may be added to a request, but will be removed if the request is redirected cross-origin. > [!NOTE] > For your custom fields, you may encounter a "**not allowed by Access-Control-Allow-Headers in preflight response**" exception when you send requests across domains. diff --git a/files/en-us/web/api/xmlhttprequest/status/index.md b/files/en-us/web/api/xmlhttprequest/status/index.md index c8fc2259a57312a..1ad07ded854af23 100644 --- a/files/en-us/web/api/xmlhttprequest/status/index.md +++ b/files/en-us/web/api/xmlhttprequest/status/index.md @@ -8,7 +8,7 @@ browser-compat: api.XMLHttpRequest.status {{APIRef("XMLHttpRequest API")}} {{AvailableInWorkers("window_and_worker_except_service")}} -The read-only **`XMLHttpRequest.status`** property returns the numerical HTTP [status code](/en-US/docs/Web/HTTP/Status) of the `XMLHttpRequest`'s response. +The read-only **`XMLHttpRequest.status`** property returns the numerical HTTP [status code](/en-US/docs/Web/HTTP/Reference/Status) of the `XMLHttpRequest`'s response. Before the request completes, the value of `status` is 0. Browsers also report a status of 0 in case of `XMLHttpRequest` errors. @@ -55,5 +55,5 @@ xhr.send(); ## See also -- List of [HTTP status](/en-US/docs/Web/HTTP/Status) +- List of [HTTP status](/en-US/docs/Web/HTTP/Reference/Status) - [HTTP](/en-US/docs/Web/HTTP) diff --git a/files/en-us/web/api/xmlhttprequest/statustext/index.md b/files/en-us/web/api/xmlhttprequest/statustext/index.md index d5860ee6cee665b..cb23739080fc63d 100644 --- a/files/en-us/web/api/xmlhttprequest/statustext/index.md +++ b/files/en-us/web/api/xmlhttprequest/statustext/index.md @@ -8,7 +8,7 @@ browser-compat: api.XMLHttpRequest.statusText {{APIRef("XMLHttpRequest API")}} {{AvailableInWorkers("window_and_worker_except_service")}} -The read-only **`XMLHttpRequest.statusText`** property returns a string containing the response's status message as returned by the HTTP server. Unlike [`XMLHTTPRequest.status`](/en-US/docs/Web/API/XMLHttpRequest/status) which indicates a numerical status code, this property contains the _text_ of the response status, such as "OK" or "Not Found". If the request's [`readyState`](/en-US/docs/Web/API/XMLHttpRequest/readyState) is in `UNSENT` or `OPENED` state, the value of `statusText` will be an empty string. +The read-only **`XMLHttpRequest.statusText`** property returns a string containing the response's status message as returned by the HTTP server. Unlike [`XMLHttpRequest.status`](/en-US/docs/Web/API/XMLHttpRequest/status) which indicates a numerical status code, this property contains the _text_ of the response status, such as "OK" or "Not Found". If the request's [`readyState`](/en-US/docs/Web/API/XMLHttpRequest/readyState) is in `UNSENT` or `OPENED` state, the value of `statusText` will be an empty string. If the server response doesn't explicitly specify a status text, `statusText` will assume the default value "OK". @@ -58,6 +58,6 @@ xhr.send(null); ## See also -- List of [HTTP status](/en-US/docs/Web/HTTP/Status) +- List of [HTTP status](/en-US/docs/Web/HTTP/Reference/Status) - [HTTP](/en-US/docs/Web/HTTP) - [WHATWG Fetch Living Standard](https://fetch.spec.whatwg.org/#concept-response-status-message) diff --git a/files/en-us/web/api/xmlhttprequest/timeout_event/index.md b/files/en-us/web/api/xmlhttprequest/timeout_event/index.md index 6f630cb42496831..b18a13ea78f0a82 100644 --- a/files/en-us/web/api/xmlhttprequest/timeout_event/index.md +++ b/files/en-us/web/api/xmlhttprequest/timeout_event/index.md @@ -14,10 +14,10 @@ The **`timeout`** event is fired when progression is terminated due to preset ti Use the event name in methods like {{domxref("EventTarget.addEventListener", "addEventListener()")}}, or set an event handler property. -```js -addEventListener("timeout", (event) => {}); +```js-nolint +addEventListener("timeout", (event) => { }) -ontimeout = (event) => {}; +ontimeout = (event) => { } ``` ## Event type diff --git a/files/en-us/web/api/xmlhttprequest/upload/index.md b/files/en-us/web/api/xmlhttprequest/upload/index.md index 8f091246ee1eb70..02e3b40f7883c0f 100644 --- a/files/en-us/web/api/xmlhttprequest/upload/index.md +++ b/files/en-us/web/api/xmlhttprequest/upload/index.md @@ -13,7 +13,7 @@ The {{domxref("XMLHttpRequest")}} `upload` property returns an {{domxref("XMLHtt It is an opaque object, but because it's also an {{domxref("XMLHttpRequestEventTarget")}}, event listeners can be attached to track its process. > [!NOTE] -> Attaching event listeners to this object prevents the request from being a "simple request" and will cause a preflight request to be issued if cross-origin; see [CORS](/en-US/docs/Web/HTTP/CORS). Because of this, event listeners need to be registered before calling {{domxref("XMLHttpRequest.send", "send()")}} or upload events won't be dispatched. +> Attaching event listeners to this object prevents the request from being a "simple request" and will cause a preflight request to be issued if cross-origin; see [CORS](/en-US/docs/Web/HTTP/Guides/CORS). Because of this, event listeners need to be registered before calling {{domxref("XMLHttpRequest.send", "send()")}} or upload events won't be dispatched. > [!NOTE] > The spec also seems to indicate that event listeners should be attached after {{domxref("XMLHttpRequest.open", "open()")}}. However, browsers are buggy on this matter, and often need the listeners to be registered _before_ {{domxref("XMLHttpRequest.open", "open()")}} to work. diff --git a/files/en-us/web/api/xmlhttprequest/xmlhttprequest/index.md b/files/en-us/web/api/xmlhttprequest/xmlhttprequest/index.md index 8329a7054c36189..5f4530d17fc7f58 100644 --- a/files/en-us/web/api/xmlhttprequest/xmlhttprequest/index.md +++ b/files/en-us/web/api/xmlhttprequest/xmlhttprequest/index.md @@ -24,9 +24,11 @@ new XMLHttpRequest(options) There are no standard parameters. However, Firefox allows a non-standard parameter: - `options` {{non-standard_inline}} - - : An object that can contain the following flag: + - : An object that can contain the following flags: - `mozAnon` - : A boolean. When setting this flag to `true` will cause the browser not to expose the {{Glossary("origin")}} and user credentials when fetching resources. Most important, this means that {{Glossary("Cookie", "cookies")}} will not be sent unless explicitly added using `setRequestHeader`. + - `mozSystem` + - : A boolean. When setting this flag to `true`, the same origin policy will not be enforced on the request. ### Return value diff --git a/files/en-us/web/api/xmlhttprequest_api/html_in_xmlhttprequest/index.md b/files/en-us/web/api/xmlhttprequest_api/html_in_xmlhttprequest/index.md index 152c6a4abef8a60..fc967999a3d92ae 100644 --- a/files/en-us/web/api/xmlhttprequest_api/html_in_xmlhttprequest/index.md +++ b/files/en-us/web/api/xmlhttprequest_api/html_in_xmlhttprequest/index.md @@ -70,7 +70,7 @@ If the file is named `detect.html`, the following function can be used for detec ```js function detectHtmlInXhr(callback) { if (!window.XMLHttpRequest) { - setTimeout(function () { + setTimeout(() => { callback(false); }, 0); @@ -101,7 +101,7 @@ function detectHtmlInXhr(callback) { xhr.responseType = "document"; xhr.send(); } catch (e) { - setTimeout(function () { + setTimeout(() => { if (!done) { done = true; callback(false); diff --git a/files/en-us/web/api/xmlhttprequest_api/index.md b/files/en-us/web/api/xmlhttprequest_api/index.md index 22132c41edeff21..7bbcafdaf810f09 100644 --- a/files/en-us/web/api/xmlhttprequest_api/index.md +++ b/files/en-us/web/api/xmlhttprequest_api/index.md @@ -10,14 +10,14 @@ spec-urls: https://xhr.spec.whatwg.org/ The **XMLHttpRequest API** enables web apps to make HTTP requests to web servers and receive the responses programmatically using JavaScript. This in turn enables a website to update just part of a page with data from the server, rather than having to navigate to a whole new page. This practice is also sometimes known as {{glossary("AJAX")}}. -The [Fetch API](/en-US/docs/Web/API/Fetch_API) is the more flexible and powerful replacement for the XMLHttpRequest API. The Fetch API uses {{jsxref("Promise", "promises", "", 1)}} instead of events to handle asynchronous responses, integrates well with [service workers](/en-US/docs/Web/API/Service_Worker_API), and supports advanced aspects of HTTP such as [CORS](/en-US/docs/Web/HTTP/CORS). For these reasons, the Fetch API is usually used in modern web apps instead of {{domxref("XMLHttpRequest")}}. +The [Fetch API](/en-US/docs/Web/API/Fetch_API) is the more flexible and powerful replacement for the XMLHttpRequest API. The Fetch API uses {{jsxref("Promise", "promises", "", 1)}} instead of events to handle asynchronous responses, integrates well with [service workers](/en-US/docs/Web/API/Service_Worker_API), and supports advanced aspects of HTTP such as [CORS](/en-US/docs/Web/HTTP/Guides/CORS). For these reasons, the Fetch API is usually used in modern web apps instead of {{domxref("XMLHttpRequest")}}. ## Concepts and usage The central interface in the XMLHttpRequest API is {{domxref("XMLHttpRequest")}}. To make an HTTP request: 1. Create a new `XMLHttpRequest` instance by calling its {{domxref("XMLHttpRequest.XMLHttpRequest", "constructor", "", "nocode")}}. -2. Initialize it by calling {{domxref("XMLHttpRequest.open()")}}. At this point you provide the URL for the request, the [HTTP method](/en-US/docs/Web/HTTP/Methods) to use, and optionally, a username and password. +2. Initialize it by calling {{domxref("XMLHttpRequest.open()")}}. At this point you provide the URL for the request, the [HTTP method](/en-US/docs/Web/HTTP/Reference/Methods) to use, and optionally, a username and password. 3. Attach event handlers to get the result of the request. For example, the {{domxref("XMLHttpRequest.load_event", "load")}} event is fired when the request has successfully completed, and the {{domxref("XMLHttpRequest.error_event", "error")}} event is fired in various error conditions. 4. Send the request by calling {{domxref("XMLHttpRequest.send()")}}. diff --git a/files/en-us/web/api/xmlhttprequest_api/sending_and_receiving_binary_data/index.md b/files/en-us/web/api/xmlhttprequest_api/sending_and_receiving_binary_data/index.md index 6d4e41f7bf898d1..2b7cde7e50d00a7 100644 --- a/files/en-us/web/api/xmlhttprequest_api/sending_and_receiving_binary_data/index.md +++ b/files/en-us/web/api/xmlhttprequest_api/sending_and_receiving_binary_data/index.md @@ -39,7 +39,7 @@ req.responseType = "blob"; req.onload = (event) => { const blob = req.response; - // ... + // … }; req.send(); diff --git a/files/en-us/web/api/xmlhttprequest_api/synchronous_and_asynchronous_requests/index.md b/files/en-us/web/api/xmlhttprequest_api/synchronous_and_asynchronous_requests/index.md index c49f9a9f03b11a1..ecdf3ab03b75e02 100644 --- a/files/en-us/web/api/xmlhttprequest_api/synchronous_and_asynchronous_requests/index.md +++ b/files/en-us/web/api/xmlhttprequest_api/synchronous_and_asynchronous_requests/index.md @@ -48,7 +48,7 @@ In some cases, you must read many external files. This is a standard function wh ```js function xhrSuccess() { - this.callback.apply(this, this.arguments); + this.callback(...this.arguments); } function xhrError() { diff --git a/files/en-us/web/api/xmlhttprequest_api/using_formdata_objects/index.md b/files/en-us/web/api/xmlhttprequest_api/using_formdata_objects/index.md index d099ddb4bde09b5..042d4d89d305f84 100644 --- a/files/en-us/web/api/xmlhttprequest_api/using_formdata_objects/index.md +++ b/files/en-us/web/api/xmlhttprequest_api/using_formdata_objects/index.md @@ -146,10 +146,10 @@ form.addEventListener("submit", async (event) => { ``` > [!NOTE] -> If you pass in a reference to the form, the [request HTTP method](/en-US/docs/Web/HTTP/Methods) specified in the form will be used over the method specified in the `open()` call. +> If you pass in a reference to the form, the [request HTTP method](/en-US/docs/Web/HTTP/Reference/Methods) specified in the form will be used over the method specified in the `open()` call. > [!WARNING] -> When using `FormData` to submit POST requests using {{ domxref("XMLHttpRequest") }} or the [Fetch API](/en-US/docs/Web/API/Fetch_API) with the `multipart/form-data` content type (e.g. when uploading files and blobs to the server), _do not_ explicitly set the [`Content-Type`](/en-US/docs/Web/HTTP/Headers/Content-Type) header on the request. Doing so will prevent the browser from being able to set the `Content-Type` header with the boundary expression it will use to delimit form fields in the request body. +> When using `FormData` to submit POST requests using {{ domxref("XMLHttpRequest") }} or the [Fetch API](/en-US/docs/Web/API/Fetch_API) with the `multipart/form-data` content type (e.g., when uploading files and blobs to the server), _do not_ explicitly set the [`Content-Type`](/en-US/docs/Web/HTTP/Reference/Headers/Content-Type) header on the request. Doing so will prevent the browser from being able to set the `Content-Type` header with the boundary expression it will use to delimit form fields in the request body. You can also append a {{ domxref("File") }} or {{ domxref("Blob") }} directly to the {{ domxref("FormData") }} object, like this: diff --git a/files/en-us/web/api/xmlhttprequest_api/using_xmlhttprequest/index.md b/files/en-us/web/api/xmlhttprequest_api/using_xmlhttprequest/index.md index 88f279b305c0e7e..721fadae1230d86 100644 --- a/files/en-us/web/api/xmlhttprequest_api/using_xmlhttprequest/index.md +++ b/files/en-us/web/api/xmlhttprequest_api/using_xmlhttprequest/index.md @@ -17,7 +17,7 @@ To send an HTTP request: 2. Open a URL 3. Send the request. -After the transaction completes, the `XMLHttpRequest` object will contain useful information such as the response body and the [HTTP status](/en-US/docs/Web/HTTP/Status) of the result. +After the transaction completes, the `XMLHttpRequest` object will contain useful information such as the response body and the [HTTP status](/en-US/docs/Web/HTTP/Reference/Status) of the result. ```js function reqListener() { @@ -237,7 +237,7 @@ If you want to know if the current page has changed, refer to the article about ## Cross-site XMLHttpRequest -Modern browsers support cross-site requests by implementing the [Cross-Origin Resource Sharing](/en-US/docs/Web/HTTP/CORS) (CORS) standard. As long as the server is configured to allow requests from your web application's origin, `XMLHttpRequest` will work. Otherwise, an `INVALID_ACCESS_ERR` exception is thrown. +Modern browsers support cross-site requests by implementing the [Cross-Origin Resource Sharing](/en-US/docs/Web/HTTP/Guides/CORS) (CORS) standard. As long as the server is configured to allow requests from your web application's origin, `XMLHttpRequest` will work. Otherwise, an `INVALID_ACCESS_ERR` exception is thrown. ## Bypassing the cache @@ -279,6 +279,6 @@ If you conclude with an XMLHttpRequest receiving `status=0` and `statusText=null - [Using the Fetch API](/en-US/docs/Web/API/Fetch_API/Using_Fetch) - [HTML in XMLHttpRequest](/en-US/docs/Web/API/XMLHttpRequest_API/HTML_in_XMLHttpRequest) -- [HTTP access control](/en-US/docs/Web/HTTP/CORS) +- [HTTP access control](/en-US/docs/Web/HTTP/Guides/CORS) - [XMLHttpRequest - REST and the Rich User Experience](https://www.peej.co.uk/articles/rich-user-experience.html) - [The `XMLHttpRequest` object: WHATWG specification](https://xhr.spec.whatwg.org/) diff --git a/files/en-us/web/api/xmlhttprequestupload/abort_event/index.md b/files/en-us/web/api/xmlhttprequestupload/abort_event/index.md index 0a36195ead1f224..b294a2b6be2497c 100644 --- a/files/en-us/web/api/xmlhttprequestupload/abort_event/index.md +++ b/files/en-us/web/api/xmlhttprequestupload/abort_event/index.md @@ -14,10 +14,10 @@ The `abort` event is fired at {{domxref("XMLHttpRequestUpload")}} when a request Use the event name in methods like {{domxref("EventTarget.addEventListener", "addEventListener()")}}, or set an event handler property. -```js -addEventListener("abort", (event) => {}); +```js-nolint +addEventListener("abort", (event) => { }) -onabort = (event) => {}; +onabort = (event) => { } ``` ## Event type diff --git a/files/en-us/web/api/xmlhttprequestupload/error_event/index.md b/files/en-us/web/api/xmlhttprequestupload/error_event/index.md index a43f73ca635de40..4d084f310e20f2d 100644 --- a/files/en-us/web/api/xmlhttprequestupload/error_event/index.md +++ b/files/en-us/web/api/xmlhttprequestupload/error_event/index.md @@ -14,10 +14,10 @@ The `error` event is fired when the request encountered an error. Use the event name in methods like {{domxref("EventTarget.addEventListener", "addEventListener()")}}, or set an event handler property. -```js -addEventListener("error", (event) => {}); +```js-nolint +addEventListener("error", (event) => { }) -onerror = (event) => {}; +onerror = (event) => { } ``` ## Event type diff --git a/files/en-us/web/api/xmlhttprequestupload/index.md b/files/en-us/web/api/xmlhttprequestupload/index.md index 810bf180d3b32b2..0045fac74707aa4 100644 --- a/files/en-us/web/api/xmlhttprequestupload/index.md +++ b/files/en-us/web/api/xmlhttprequestupload/index.md @@ -68,7 +68,7 @@ This allows you to upload a file to a server; it displays a progress bar while t <label for="file">File to upload</label><input type="file" id="file" /> </p> <p> - <progress /> + <progress></progress> </p> <p> <output></output> diff --git a/files/en-us/web/api/xmlhttprequestupload/load_event/index.md b/files/en-us/web/api/xmlhttprequestupload/load_event/index.md index d599314c7d6a3dd..ad47c6f628d873c 100644 --- a/files/en-us/web/api/xmlhttprequestupload/load_event/index.md +++ b/files/en-us/web/api/xmlhttprequestupload/load_event/index.md @@ -14,10 +14,10 @@ The `load` event is fired when an {{domxref("XMLHttpRequestUpload")}} transactio Use the event name in methods like {{domxref("EventTarget.addEventListener", "addEventListener()")}}, or set an event handler property. -```js -addEventListener("load", (event) => {}); +```js-nolint +addEventListener("load", (event) => { }) -onload = (event) => {}; +onload = (event) => { } ``` ## Event type diff --git a/files/en-us/web/api/xmlhttprequestupload/loadend_event/index.md b/files/en-us/web/api/xmlhttprequestupload/loadend_event/index.md index 1d508fd90a85d37..80e00511f1f5004 100644 --- a/files/en-us/web/api/xmlhttprequestupload/loadend_event/index.md +++ b/files/en-us/web/api/xmlhttprequestupload/loadend_event/index.md @@ -16,10 +16,10 @@ The `loadend` event is also sent when the request has been interrupted (by a {{d Use the event name in methods like {{domxref("EventTarget.addEventListener", "addEventListener()")}}, or set an event handler property. -```js -addEventListener("loadend", (event) => {}); +```js-nolint +addEventListener("loadend", (event) => { }) -onloadend = (event) => {}; +onloadend = (event) => { } ``` ## Event type @@ -41,7 +41,7 @@ _In addition to the properties listed below, properties from the parent interfac ## Examples -## Using the `loadend` event +### Using the `loadend` event You can use the `loadend` event to detect the (successful or not) termination of an upload. For a complete code example that uploads a file and displays a progress bar, see the main {{domxref("XMLHttpRequestUpload")}} page. diff --git a/files/en-us/web/api/xmlhttprequestupload/loadstart_event/index.md b/files/en-us/web/api/xmlhttprequestupload/loadstart_event/index.md index 5cb131fdee0f97a..84f96f94adc89ff 100644 --- a/files/en-us/web/api/xmlhttprequestupload/loadstart_event/index.md +++ b/files/en-us/web/api/xmlhttprequestupload/loadstart_event/index.md @@ -14,10 +14,10 @@ The **`loadstart`** event is fired when a request has started to load data. Use the event name in methods like {{domxref("EventTarget.addEventListener", "addEventListener()")}}, or set an event handler property. -```js -addEventListener("loadstart", (event) => {}); +```js-nolint +addEventListener("loadstart", (event) => { }) -onloadstart = (event) => {}; +onloadstart = (event) => { } ``` ## Event type @@ -39,7 +39,7 @@ _In addition to the properties listed below, properties from the parent interfac ## Examples -## Using the `loadstart` event +### Using the `loadstart` event You can use the `loadstart` event to detect the beginning of an upload. For a complete code example that uploads a file and displays a progress bar, see the main {{domxref("XMLHttpRequestUpload")}} page. diff --git a/files/en-us/web/api/xmlhttprequestupload/progress_event/index.md b/files/en-us/web/api/xmlhttprequestupload/progress_event/index.md index 0c360f66f07a801..01b8d18690bd534 100644 --- a/files/en-us/web/api/xmlhttprequestupload/progress_event/index.md +++ b/files/en-us/web/api/xmlhttprequestupload/progress_event/index.md @@ -14,10 +14,10 @@ The **`progress`** event is fired periodically when a request receives more data Use the event name in methods like {{domxref("EventTarget.addEventListener", "addEventListener()")}}, or set an event handler property. -```js -addEventListener("progress", (event) => {}); +```js-nolint +addEventListener("progress", (event) => { }) -onprogress = (event) => {}; +onprogress = (event) => { } ``` ## Event type @@ -39,7 +39,7 @@ _In addition to the properties listed below, properties from the parent interfac ## Examples -## Using the `progress` event +### Using the `progress` event You can use the `progress` event to get info about the progress of a lengthy upload. For a complete code example that uploads a file and displays a progress bar, see the main {{domxref("XMLHttpRequestUpload")}} page. diff --git a/files/en-us/web/api/xmlhttprequestupload/timeout_event/index.md b/files/en-us/web/api/xmlhttprequestupload/timeout_event/index.md index 03489ced3a7bee9..6d3807503770e8e 100644 --- a/files/en-us/web/api/xmlhttprequestupload/timeout_event/index.md +++ b/files/en-us/web/api/xmlhttprequestupload/timeout_event/index.md @@ -14,10 +14,10 @@ The **`timeout`** event is fired when progression is terminated due to preset ti Use the event name in methods like {{domxref("EventTarget.addEventListener", "addEventListener()")}}, or set an event handler property. -```js -addEventListener("timeout", (event) => {}); +```js-nolint +addEventListener("timeout", (event) => { }) -ontimeout = (event) => {}; +ontimeout = (event) => { } ``` ## Event type diff --git a/files/en-us/web/api/xpathevaluator/createexpression/index.md b/files/en-us/web/api/xpathevaluator/createexpression/index.md index e26a743d13d0a9a..02e9a2dec51290d 100644 --- a/files/en-us/web/api/xpathevaluator/createexpression/index.md +++ b/files/en-us/web/api/xpathevaluator/createexpression/index.md @@ -35,7 +35,7 @@ expression. #### INVALID_EXPRESSION_ERR If the expression is not legal according to the rules of the -`XPathEvaluator`, an {{domxref("XPathException")}} of type +`XPathEvaluator`, a {{domxref("DOMException")}} of type `INVALID_EXPRESSION_ERR` is raised. #### NAMESPACE_ERR diff --git a/files/en-us/web/api/xpathevaluator/evaluate/index.md b/files/en-us/web/api/xpathevaluator/evaluate/index.md index b4970f09759f9b9..0783f5b14a4f3f9 100644 --- a/files/en-us/web/api/xpathevaluator/evaluate/index.md +++ b/files/en-us/web/api/xpathevaluator/evaluate/index.md @@ -49,13 +49,13 @@ expression. #### INVALID_EXPRESSION_ERR If the expression is not legal according to the rules of the -{{domxref("XPathEvaluator")}}, an {{domxref("XPathException")}} of type +{{domxref("XPathEvaluator")}}, a {{domxref("DOMException")}} of type `INVALID_EXPRESSION_ERR` is raised. #### TYPE_ERR -In case result cannot be converted to the specified type, an -{{domxref("XPathException")}} of type `TYPE_ERR` is raised. +In case result cannot be converted to the specified type, a +{{domxref("DOMException")}} of type `TYPE_ERR` is raised. #### NAMESPACE_ERR diff --git a/files/en-us/web/api/xpathexception/code/index.md b/files/en-us/web/api/xpathexception/code/index.md deleted file mode 100644 index 61cb7f3d5505794..000000000000000 --- a/files/en-us/web/api/xpathexception/code/index.md +++ /dev/null @@ -1,25 +0,0 @@ ---- -title: "XPathException: code property" -short-title: code -slug: Web/API/XPathException/code -page-type: web-api-instance-property -browser-compat: api.XPathException.code ---- - -{{APIRef("DOM XPath")}}{{Deprecated_Header}} - -The **`code`** read-only property of the -{{domxref("XPathException")}} interface returns a `short` that contains one -of the [error code constants](/en-US/docs/Web/API/XPathException#constants). - -## Value - -A `short` number representing the error code. - -## Specifications - -{{Specifications}} - -## Browser compatibility - -{{Compat}} diff --git a/files/en-us/web/api/xpathexception/index.md b/files/en-us/web/api/xpathexception/index.md deleted file mode 100644 index 1b5a8f43e2a9503..000000000000000 --- a/files/en-us/web/api/xpathexception/index.md +++ /dev/null @@ -1,59 +0,0 @@ ---- -title: XPathException -slug: Web/API/XPathException -page-type: web-api-interface -browser-compat: api.XPathException ---- - -{{APIRef("DOM XPath")}}{{Deprecated_Header}} - -In the [DOM XPath API](/en-US/docs/Web/XML/XPath) the **`XPathException`** interface represents exception conditions that can be encountered while performing XPath operations. - -## Instance properties - -- {{domxref("XPathException.code")}} {{ReadOnlyInline}} - - : Returns a `short` that contains one of the [error code constants](#constants). - -## Constants - -<table class="no-markdown"> - <thead> - <tr> - <th scope="col">Constant</th> - <th scope="col">Value</th> - <th scope="col">Description</th> - </tr> - </thead> - <tbody> - <tr> - <td><code>INVALID_EXPRESSION_ERR</code></td> - <td><code>51</code></td> - <td> - If the expression has a syntax error or otherwise is not a legal - expression according to the rules of the specific - {{domxref("XPathEvaluator")}} or contains specialized - extension functions or variables not supported by this implementation. - </td> - </tr> - <tr> - <td><code>TYPE_ERR</code></td> - <td><code>52</code></td> - <td> - If the expression cannot be converted to return the specified type. - </td> - </tr> - </tbody> -</table> - -## Specifications - -{{Specifications}} - -## Browser compatibility - -{{Compat}} - -## See also - -- {{DOMxRef("Document.createExpression()")}} -- {{DOMxRef("XPathExpression")}} diff --git a/files/en-us/web/api/xpathexpression/evaluate/index.md b/files/en-us/web/api/xpathexpression/evaluate/index.md index 0a1117ee61a8513..e17fc80d5f06599 100644 --- a/files/en-us/web/api/xpathexpression/evaluate/index.md +++ b/files/en-us/web/api/xpathexpression/evaluate/index.md @@ -42,13 +42,13 @@ expression. #### INVALID_EXPRESSION_ERR If the expression is not legal according to the rules of the -{{domxref("XPathEvaluator")}}, an {{domxref("XPathException")}} of type +{{domxref("XPathEvaluator")}}, a {{domxref("DOMException")}} of type `INVALID_EXPRESSION_ERR` is raised. #### TYPE_ERR -In case result cannot be converted to the specified type, an -{{domxref("XPathException")}} of type `TYPE_ERR` is raised. +In case result cannot be converted to the specified type, a +{{domxref("DOMException")}} of type `TYPE_ERR` is raised. #### NAMESPACE_ERR diff --git a/files/en-us/web/api/xpathresult/booleanvalue/index.md b/files/en-us/web/api/xpathresult/booleanvalue/index.md index 0846f3b4800f393..12bb2e31d93d30c 100644 --- a/files/en-us/web/api/xpathresult/booleanvalue/index.md +++ b/files/en-us/web/api/xpathresult/booleanvalue/index.md @@ -21,8 +21,8 @@ The return value is the boolean value of the `XPathResult` returned by #### TYPE_ERR -In case {{domxref("XPathResult.resultType")}} is not `BOOLEAN_TYPE`, an -{{domxref("XPathException")}} of type `TYPE_ERR` is thrown. +In case {{domxref("XPathResult.resultType")}} is not `BOOLEAN_TYPE`, a +{{domxref("DOMException")}} of type `TYPE_ERR` is thrown. ## Examples diff --git a/files/en-us/web/api/xpathresult/iteratenext/index.md b/files/en-us/web/api/xpathresult/iteratenext/index.md index e439513f601099b..987cca2349b834d 100644 --- a/files/en-us/web/api/xpathresult/iteratenext/index.md +++ b/files/en-us/web/api/xpathresult/iteratenext/index.md @@ -31,13 +31,13 @@ The next {{domxref("Node")}} within the node set of the `XPathResult`. #### TYPE_ERR In case {{domxref("XPathResult.resultType")}} is not -`UNORDERED_NODE_ITERATOR_TYPE` or `ORDERED_NODE_ITERATOR_TYPE`, an -{{domxref("XPathException")}} of type `TYPE_ERR` is thrown. +`UNORDERED_NODE_ITERATOR_TYPE` or `ORDERED_NODE_ITERATOR_TYPE`, a +{{domxref("DOMException")}} of type `TYPE_ERR` is thrown. #### INVALID_STATE_ERR -If the document is mutated since the result was returned, an -{{domxref("XPathException")}} of type `INVALID_STATE_ERR` is thrown. +If the document is mutated since the result was returned, a +{{domxref("DOMException")}} of type `INVALID_STATE_ERR` is thrown. ## Examples diff --git a/files/en-us/web/api/xpathresult/numbervalue/index.md b/files/en-us/web/api/xpathresult/numbervalue/index.md index 094d57ba8998b5b..555e3e20c8d093f 100644 --- a/files/en-us/web/api/xpathresult/numbervalue/index.md +++ b/files/en-us/web/api/xpathresult/numbervalue/index.md @@ -21,8 +21,8 @@ The return value is the numeric value of the `XPathResult` returned by #### TYPE_ERR -In case {{domxref("XPathResult.resultType")}} is not `NUMBER_TYPE`, an -{{domxref("XPathException")}} of type `TYPE_ERR` is thrown. +In case {{domxref("XPathResult.resultType")}} is not `NUMBER_TYPE`, a +{{domxref("DOMException")}} of type `TYPE_ERR` is thrown. ## Examples diff --git a/files/en-us/web/api/xpathresult/singlenodevalue/index.md b/files/en-us/web/api/xpathresult/singlenodevalue/index.md index af1185d6b485e04..4b1d2bae68869f7 100644 --- a/files/en-us/web/api/xpathresult/singlenodevalue/index.md +++ b/files/en-us/web/api/xpathresult/singlenodevalue/index.md @@ -24,8 +24,8 @@ returned by {{domxref("Document.evaluate()")}}. #### TYPE_ERR In case {{domxref("XPathResult.resultType")}} is not -`ANY_UNORDERED_NODE_TYPE` or `FIRST_ORDERED_NODE_TYPE`, an -{{domxref("XPathException")}} of type `TYPE_ERR` is thrown. +`ANY_UNORDERED_NODE_TYPE` or `FIRST_ORDERED_NODE_TYPE`, a +{{domxref("DOMException")}} of type `TYPE_ERR` is thrown. ## Examples diff --git a/files/en-us/web/api/xpathresult/snapshotitem/index.md b/files/en-us/web/api/xpathresult/snapshotitem/index.md index 57eb76ba6e4c630..5f2b30cc9f19dcd 100644 --- a/files/en-us/web/api/xpathresult/snapshotitem/index.md +++ b/files/en-us/web/api/xpathresult/snapshotitem/index.md @@ -35,8 +35,8 @@ The {{domxref("Node")}} at the given index within the node set of the #### TYPE_ERR In case {{domxref("XPathResult.resultType")}} is not -`UNORDERED_NODE_SNAPSHOT_TYPE` or `ORDERED_NODE_SNAPSHOT_TYPE`, an -{{domxref("XPathException")}} of type `TYPE_ERR` is thrown. +`UNORDERED_NODE_SNAPSHOT_TYPE` or `ORDERED_NODE_SNAPSHOT_TYPE`, a +{{domxref("DOMException")}} of type `TYPE_ERR` is thrown. ## Examples diff --git a/files/en-us/web/api/xpathresult/snapshotlength/index.md b/files/en-us/web/api/xpathresult/snapshotlength/index.md index f75fd8411272ed8..168e926b3b4d547 100644 --- a/files/en-us/web/api/xpathresult/snapshotlength/index.md +++ b/files/en-us/web/api/xpathresult/snapshotlength/index.md @@ -21,8 +21,8 @@ An integer value representing the number of nodes in the result snapshot. #### TYPE_ERR In case {{domxref("XPathResult.resultType")}} is not -`UNORDERED_NODE_SNAPSHOT_TYPE` or `ORDERED_NODE_SNAPSHOT_TYPE`, an -{{domxref("XPathException")}} of type `TYPE_ERR` is thrown. +`UNORDERED_NODE_SNAPSHOT_TYPE` or `ORDERED_NODE_SNAPSHOT_TYPE`, a +{{domxref("DOMException")}} of type `TYPE_ERR` is thrown. ## Examples diff --git a/files/en-us/web/api/xpathresult/stringvalue/index.md b/files/en-us/web/api/xpathresult/stringvalue/index.md index 05283ad7ae0ad0d..c39bad36d0280ff 100644 --- a/files/en-us/web/api/xpathresult/stringvalue/index.md +++ b/files/en-us/web/api/xpathresult/stringvalue/index.md @@ -21,8 +21,8 @@ The return value is the string value of the `XPathResult` returned by #### TYPE_ERR -In case {{domxref("XPathResult.resultType")}} is not `STRING_TYPE`, an -{{domxref("XPathException")}} of type `TYPE_ERR` is thrown. +In case {{domxref("XPathResult.resultType")}} is not `STRING_TYPE`, a +{{domxref("DOMException")}} of type `TYPE_ERR` is thrown. ## Examples diff --git a/files/en-us/web/api/xrcpudepthinformation/index.md b/files/en-us/web/api/xrcpudepthinformation/index.md index e919a2177636e2e..0f2e057e991dcf3 100644 --- a/files/en-us/web/api/xrcpudepthinformation/index.md +++ b/files/en-us/web/api/xrcpudepthinformation/index.md @@ -33,8 +33,6 @@ This interface inherits properties from its parent, {{domxref("XRDepthInformatio - {{domxref("XRCPUDepthInformation.getDepthInMeters()")}} {{Experimental_Inline}} - : Returns the depth in meters at (x, y) in normalized view coordinates. -## Examples - ## Specifications {{Specifications}} diff --git a/files/en-us/web/api/xrcubelayer/redraw_event/index.md b/files/en-us/web/api/xrcubelayer/redraw_event/index.md index 14b86f38eef7fe6..20227d2660aefb2 100644 --- a/files/en-us/web/api/xrcubelayer/redraw_event/index.md +++ b/files/en-us/web/api/xrcubelayer/redraw_event/index.md @@ -18,10 +18,10 @@ See also the {{domxref("XRCompositionLayer.needsRedraw")}} property which is als Use the event name in methods like {{domxref("EventTarget.addEventListener", "addEventListener()")}}, or set an event handler property. -```js -addEventListener("redraw", (event) => {}); +```js-nolint +addEventListener("redraw", (event) => { }) -onredraw = (event) => {}; +onredraw = (event) => { } ``` ## Event type diff --git a/files/en-us/web/api/xrcylinderlayer/redraw_event/index.md b/files/en-us/web/api/xrcylinderlayer/redraw_event/index.md index 0d6842f94bab6cb..3f6c42d6f2734a5 100644 --- a/files/en-us/web/api/xrcylinderlayer/redraw_event/index.md +++ b/files/en-us/web/api/xrcylinderlayer/redraw_event/index.md @@ -18,10 +18,10 @@ See also the {{domxref("XRCompositionLayer.needsRedraw")}} property which is als Use the event name in methods like {{domxref("EventTarget.addEventListener", "addEventListener()")}}, or set an event handler property. -```js -addEventListener("redraw", (event) => {}); +```js-nolint +addEventListener("redraw", (event) => { }) -onredraw = (event) => {}; +onredraw = (event) => { } ``` ## Event type diff --git a/files/en-us/web/api/xrequirectlayer/redraw_event/index.md b/files/en-us/web/api/xrequirectlayer/redraw_event/index.md index 540dea9e0aca6e1..6b8b28c7bb0798c 100644 --- a/files/en-us/web/api/xrequirectlayer/redraw_event/index.md +++ b/files/en-us/web/api/xrequirectlayer/redraw_event/index.md @@ -18,10 +18,10 @@ See also the {{domxref("XRCompositionLayer.needsRedraw")}} property which is als Use the event name in methods like {{domxref("EventTarget.addEventListener", "addEventListener()")}}, or set an event handler property. -```js -addEventListener("redraw", (event) => {}); +```js-nolint +addEventListener("redraw", (event) => { }) -onredraw = (event) => {}; +onredraw = (event) => { } ``` ## Event type diff --git a/files/en-us/web/api/xrhand/index.md b/files/en-us/web/api/xrhand/index.md index 28c8d9f53b2af92..42af7d70cc68c8b 100644 --- a/files/en-us/web/api/xrhand/index.md +++ b/files/en-us/web/api/xrhand/index.md @@ -18,7 +18,7 @@ The **`XRHand`** interface is pair iterator (an ordered map) with the key being ## Instance methods -The `XRhand` object is a pair iterator. It can directly be used in a {{jsxref("Statements/for...of", "for...of")}} structure. `for (const joint of myHand)` is equivalent to `for (const joint of myHand.entries())`. +The `XRHand` object is a pair iterator. It can directly be used in a {{jsxref("Statements/for...of", "for...of")}} structure. `for (const joint of myHand)` is equivalent to `for (const joint of myHand.entries())`. However, it's not a map-like object, so you don't have the `clear()`, `delete()`, `has()`, and `set()` methods. - `entries()` {{Experimental_Inline}} diff --git a/files/en-us/web/api/xrinputsourcearray/index.md b/files/en-us/web/api/xrinputsourcearray/index.md index 3a99620ee1a2aed..cb76424627e8fca 100644 --- a/files/en-us/web/api/xrinputsourcearray/index.md +++ b/files/en-us/web/api/xrinputsourcearray/index.md @@ -42,8 +42,6 @@ if (sources.length > 0) { } ``` -## Examples - ## Specifications {{Specifications}} diff --git a/files/en-us/web/api/xrlayerevent/layer/index.md b/files/en-us/web/api/xrlayerevent/layer/index.md index 9f16866c485e22d..6cccb93c26fbcc4 100644 --- a/files/en-us/web/api/xrlayerevent/layer/index.md +++ b/files/en-us/web/api/xrlayerevent/layer/index.md @@ -24,7 +24,7 @@ In this example, the `layer` property is used to obtain the {{domxref("XRLayer") ```js myLayer.addEventListener("redraw", (e) => { - if (typeof e.layer === "XRQuadLayer") { + if (e.layer instanceof XRQuadLayer) { // redraw quad layer } }); diff --git a/files/en-us/web/api/xrlightprobe/reflectionchange_event/index.md b/files/en-us/web/api/xrlightprobe/reflectionchange_event/index.md index 390b63796c49cf0..bfa7b91a87f3b57 100644 --- a/files/en-us/web/api/xrlightprobe/reflectionchange_event/index.md +++ b/files/en-us/web/api/xrlightprobe/reflectionchange_event/index.md @@ -16,10 +16,10 @@ The WebXR **`reflectionchange`** event fires each time the estimated reflection Use the event name in methods like {{domxref("EventTarget.addEventListener", "addEventListener()")}}, or set an event handler property. -```js -addEventListener("reflectionchange", (event) => {}); +```js-nolint +addEventListener("reflectionchange", (event) => { }) -onreflectionchange = (event) => {}; +onreflectionchange = (event) => { } ``` ## Event type diff --git a/files/en-us/web/api/xrquadlayer/redraw_event/index.md b/files/en-us/web/api/xrquadlayer/redraw_event/index.md index 691948d5a90044e..f034255d45f9316 100644 --- a/files/en-us/web/api/xrquadlayer/redraw_event/index.md +++ b/files/en-us/web/api/xrquadlayer/redraw_event/index.md @@ -18,10 +18,10 @@ See also the {{domxref("XRCompositionLayer.needsRedraw")}} property which is als Use the event name in methods like {{domxref("EventTarget.addEventListener", "addEventListener()")}}, or set an event handler property. -```js -addEventListener("redraw", (event) => {}); +```js-nolint +addEventListener("redraw", (event) => { }) -onredraw = (event) => {}; +onredraw = (event) => { } ``` ## Event type diff --git a/files/en-us/web/api/xrreferencespace/reset_event/index.md b/files/en-us/web/api/xrreferencespace/reset_event/index.md index ff3e83c0e9eef5a..1f32fc202d223d7 100644 --- a/files/en-us/web/api/xrreferencespace/reset_event/index.md +++ b/files/en-us/web/api/xrreferencespace/reset_event/index.md @@ -20,10 +20,10 @@ This event is not cancelable. Use the event name in methods like {{domxref("EventTarget.addEventListener", "addEventListener()")}}, or set an event handler property. -```js -addEventListener("reset", (event) => {}); +```js-nolint +addEventListener("reset", (event) => { }) -onreset = (event) => {}; +onreset = (event) => { } ``` ## Event type diff --git a/files/en-us/web/api/xrreferencespaceevent/referencespace/index.md b/files/en-us/web/api/xrreferencespaceevent/referencespace/index.md index b16967bb1fc0509..1fe34a031d015a7 100644 --- a/files/en-us/web/api/xrreferencespaceevent/referencespace/index.md +++ b/files/en-us/web/api/xrreferencespaceevent/referencespace/index.md @@ -16,8 +16,6 @@ originator of the event. An {{domxref("XRReferenceSpace")}} indicating the source of the event. -## Examples - ## Specifications {{Specifications}} diff --git a/files/en-us/web/api/xrsession/end/index.md b/files/en-us/web/api/xrsession/end/index.md index 9972a888d366f66..0bb303ebe13b1d9 100644 --- a/files/en-us/web/api/xrsession/end/index.md +++ b/files/en-us/web/api/xrsession/end/index.md @@ -31,8 +31,6 @@ related to shutting down the session have completed. You can use the promise to things like update UI elements to reflect the shut down connection, trigger application shut down, or whatever else you might need to do. -## Examples - ## Specifications {{Specifications}} diff --git a/files/en-us/web/api/xrsession/end_event/index.md b/files/en-us/web/api/xrsession/end_event/index.md index e3cf3e392b2b383..bf09cb699ef5dd9 100644 --- a/files/en-us/web/api/xrsession/end_event/index.md +++ b/files/en-us/web/api/xrsession/end_event/index.md @@ -16,10 +16,10 @@ An `end` event is fired at an {{DOMxRef("XRSession")}} object when the WebXR ses Use the event name in methods like {{domxref("EventTarget.addEventListener", "addEventListener()")}}, or set an event handler property. -```js -addEventListener("end", (event) => {}); +```js-nolint +addEventListener("end", (event) => { }) -onend = (event) => {}; +onend = (event) => { } ``` ## Event type diff --git a/files/en-us/web/api/xrsession/inputsourceschange_event/index.md b/files/en-us/web/api/xrsession/inputsourceschange_event/index.md index 7b59661306dc9a7..7283c84ec13619d 100644 --- a/files/en-us/web/api/xrsession/inputsourceschange_event/index.md +++ b/files/en-us/web/api/xrsession/inputsourceschange_event/index.md @@ -16,10 +16,10 @@ The **`inputsourceschange`** event is sent to an {{domxref("XRSession")}} when t Use the event name in methods like {{domxref("EventTarget.addEventListener", "addEventListener()")}}, or set an event handler property. -```js -addEventListener("inputsourceschange", (event) => {}); +```js-nolint +addEventListener("inputsourceschange", (event) => { }) -oninputsourceschange = (event) => {}; +oninputsourceschange = (event) => { } ``` ## Event type diff --git a/files/en-us/web/api/xrsession/select_event/index.md b/files/en-us/web/api/xrsession/select_event/index.md index 5c4d58b7fb8b380..c81b925698a9d80 100644 --- a/files/en-us/web/api/xrsession/select_event/index.md +++ b/files/en-us/web/api/xrsession/select_event/index.md @@ -18,10 +18,10 @@ The {{domxref("Element.beforexrselect_event", "beforexrselect")}} is fired befor Use the event name in methods like {{domxref("EventTarget.addEventListener", "addEventListener()")}}, or set an event handler property. -```js -addEventListener("select", (event) => {}); +```js-nolint +addEventListener("select", (event) => { }) -onselect = (event) => {}; +onselect = (event) => { } ``` ## Event type diff --git a/files/en-us/web/api/xrsession/selectend_event/index.md b/files/en-us/web/api/xrsession/selectend_event/index.md index 866d5fc8c89c823..699e239b9b65fb2 100644 --- a/files/en-us/web/api/xrsession/selectend_event/index.md +++ b/files/en-us/web/api/xrsession/selectend_event/index.md @@ -18,10 +18,10 @@ The {{domxref("Element.beforexrselect_event", "beforexrselect")}} is fired befor Use the event name in methods like {{domxref("EventTarget.addEventListener", "addEventListener()")}}, or set an event handler property. -```js -addEventListener("selectend", (event) => {}); +```js-nolint +addEventListener("selectend", (event) => { }) -onselectend = (event) => {}; +onselectend = (event) => { } ``` ## Event type diff --git a/files/en-us/web/api/xrsession/selectstart_event/index.md b/files/en-us/web/api/xrsession/selectstart_event/index.md index 574b31c077be3c4..fda325fba49fd8e 100644 --- a/files/en-us/web/api/xrsession/selectstart_event/index.md +++ b/files/en-us/web/api/xrsession/selectstart_event/index.md @@ -18,10 +18,10 @@ The {{domxref("Element.beforexrselect_event", "beforexrselect")}} is fired befor Use the event name in methods like {{domxref("EventTarget.addEventListener", "addEventListener()")}}, or set an event handler property. -```js -addEventListener("selectstart", (event) => {}); +```js-nolint +addEventListener("selectstart", (event) => { }) -onselectstart = (event) => {}; +onselectstart = (event) => { } ``` ## Event type diff --git a/files/en-us/web/api/xrsession/squeeze_event/index.md b/files/en-us/web/api/xrsession/squeeze_event/index.md index 279ac533bb912b7..ba149a3bc2dabde 100644 --- a/files/en-us/web/api/xrsession/squeeze_event/index.md +++ b/files/en-us/web/api/xrsession/squeeze_event/index.md @@ -18,10 +18,10 @@ For details on how the {{domxref("XRSession.squeezestart_event", "squeezestart") Use the event name in methods like {{domxref("EventTarget.addEventListener", "addEventListener()")}}, or set an event handler property. -```js -addEventListener("squeeze", (event) => {}); +```js-nolint +addEventListener("squeeze", (event) => { }) -onsqueeze = (event) => {}; +onsqueeze = (event) => { } ``` ## Event type diff --git a/files/en-us/web/api/xrsession/squeezeend_event/index.md b/files/en-us/web/api/xrsession/squeezeend_event/index.md index a55833a65c8ace4..12459279dc9a4fc 100644 --- a/files/en-us/web/api/xrsession/squeezeend_event/index.md +++ b/files/en-us/web/api/xrsession/squeezeend_event/index.md @@ -18,10 +18,10 @@ Primary squeeze actions include things like users pressing triggers or buttons, Use the event name in methods like {{domxref("EventTarget.addEventListener", "addEventListener()")}}, or set an event handler property. -```js -addEventListener("squeezeend", (event) => {}); +```js-nolint +addEventListener("squeezeend", (event) => { }) -onsqueezeend = (event) => {}; +onsqueezeend = (event) => { } ``` ## Event type diff --git a/files/en-us/web/api/xrsession/squeezestart_event/index.md b/files/en-us/web/api/xrsession/squeezestart_event/index.md index f584f214fdb9c1c..1acf70f5b2ac2e6 100644 --- a/files/en-us/web/api/xrsession/squeezestart_event/index.md +++ b/files/en-us/web/api/xrsession/squeezestart_event/index.md @@ -18,10 +18,10 @@ Primary squeeze actions are actions which are meant to represent gripping or squ Use the event name in methods like {{domxref("EventTarget.addEventListener", "addEventListener()")}}, or set an event handler property. -```js -addEventListener("squeezestart", (event) => {}); +```js-nolint +addEventListener("squeezestart", (event) => { }) -onsqueezestart = (event) => {}; +onsqueezestart = (event) => { } ``` ## Event type diff --git a/files/en-us/web/api/xrsession/visibilitychange_event/index.md b/files/en-us/web/api/xrsession/visibilitychange_event/index.md index 00ee39a03cb1a34..7b8c1660f5f4f5d 100644 --- a/files/en-us/web/api/xrsession/visibilitychange_event/index.md +++ b/files/en-us/web/api/xrsession/visibilitychange_event/index.md @@ -16,10 +16,10 @@ The **`visibilitychange`** event is sent to an {{domxref("XRSession")}} to infor Use the event name in methods like {{domxref("EventTarget.addEventListener", "addEventListener()")}}, or set an event handler property. -```js -addEventListener("visibilitychange", (event) => {}); +```js-nolint +addEventListener("visibilitychange", (event) => { }) -onvisibilitychange = (event) => {}; +onvisibilitychange = (event) => { } ``` ## Event type diff --git a/files/en-us/web/api/xrsystem/devicechange_event/index.md b/files/en-us/web/api/xrsystem/devicechange_event/index.md index 72a86e8e7ed92d4..510fc9396cf8460 100644 --- a/files/en-us/web/api/xrsystem/devicechange_event/index.md +++ b/files/en-us/web/api/xrsystem/devicechange_event/index.md @@ -19,13 +19,13 @@ A **`devicechange`** event is fired on an {{DOMxRef("XRSystem")}} object wheneve Use the event name in methods like {{domxref("EventTarget.addEventListener", "addEventListener()")}}, or set an event handler property. -```js -addEventListener("devicechange", (event) => {}); +```js-nolint +addEventListener("devicechange", (event) => { }) -ondevicechange = (event) => {}; +ondevicechange = (event) => { } ``` -If the use of WebXR has been blocked by an `xr-spatial-tracking` [Permissions Policy](/en-US/docs/Web/HTTP/Permissions_Policy), `devicechange` events will not fire. +If the use of WebXR has been blocked by an `xr-spatial-tracking` [Permissions Policy](/en-US/docs/Web/HTTP/Guides/Permissions_Policy), `devicechange` events will not fire. ## Event type diff --git a/files/en-us/web/api/xrsystem/issessionsupported/index.md b/files/en-us/web/api/xrsystem/issessionsupported/index.md index 7d29a8b3ca23608..2c75ae846561c3a 100644 --- a/files/en-us/web/api/xrsystem/issessionsupported/index.md +++ b/files/en-us/web/api/xrsystem/issessionsupported/index.md @@ -48,7 +48,7 @@ returned promise, passing to the rejection handler a {{domxref("DOMException")}} `name` is one of the following strings. - `SecurityError` - - : Use of this feature is blocked by an `xr-spatial-tracking` [Permissions Policy](/en-US/docs/Web/HTTP/Permissions_Policy). + - : Use of this feature is blocked by an `xr-spatial-tracking` [Permissions Policy](/en-US/docs/Web/HTTP/Guides/Permissions_Policy). ## Examples diff --git a/files/en-us/web/api/xrsystem/requestsession/index.md b/files/en-us/web/api/xrsystem/requestsession/index.md index 7bd3cb79fb99f5d..73ea23c0920108b 100644 --- a/files/en-us/web/api/xrsystem/requestsession/index.md +++ b/files/en-us/web/api/xrsystem/requestsession/index.md @@ -109,7 +109,7 @@ The following session features and reference spaces can be requested, either as ## Security -Several session features and the various reference spaces have minimum security and privacy requirements, like asking for user consent and/or requiring the {{HTTPHeader("Permissions-Policy")}}: [`xr-spatial-tracking`](/en-US/docs/Web/HTTP/Headers/Permissions-Policy/xr-spatial-tracking) directive to be set. See also [Permissions and security](/en-US/docs/Web/API/WebXR_Device_API/Permissions_and_security) for more details. +Several session features and the various reference spaces have minimum security and privacy requirements, like asking for user consent and/or requiring the {{HTTPHeader("Permissions-Policy")}}: [`xr-spatial-tracking`](/en-US/docs/Web/HTTP/Reference/Headers/Permissions-Policy/xr-spatial-tracking) directive to be set. See also [Permissions and security](/en-US/docs/Web/API/WebXR_Device_API/Permissions_and_security) for more details. | Session feature | User consent requirement | Permissions policy requirement | | --------------- | ----------------------------------- | ------------------------------ | diff --git a/files/en-us/web/api/xrview/projectionmatrix/index.md b/files/en-us/web/api/xrview/projectionmatrix/index.md index 311ec31e33206ab..4e46f25c5aad52f 100644 --- a/files/en-us/web/api/xrview/projectionmatrix/index.md +++ b/files/en-us/web/api/xrview/projectionmatrix/index.md @@ -27,8 +27,6 @@ The projection matrix for each eye's view is used to ensure that the correct are scene is presented to each eye in order to create a believable 3D scene without introducing discomfort for the user. -## Examples - ## Specifications {{Specifications}} diff --git a/files/en-us/web/api/xrwebgldepthinformation/index.md b/files/en-us/web/api/xrwebgldepthinformation/index.md index 84b8728521ec753..7ee207b12ce252a 100644 --- a/files/en-us/web/api/xrwebgldepthinformation/index.md +++ b/files/en-us/web/api/xrwebgldepthinformation/index.md @@ -28,8 +28,6 @@ This interface inherits properties from its parent, {{domxref("XRDepthInformatio - {{domxref("XRDepthInformation.width")}} {{ReadOnlyInline}} - : Contains the width of the depth buffer (number of columns). -## Examples - ## Specifications {{Specifications}} diff --git a/files/en-us/web/api/xsltprocessor/index.md b/files/en-us/web/api/xsltprocessor/index.md index 828bc1f8dfdee8b..17e69ef78fb87ea 100644 --- a/files/en-us/web/api/xsltprocessor/index.md +++ b/files/en-us/web/api/xsltprocessor/index.md @@ -61,7 +61,7 @@ async function init() { xsltProcessor.importStylesheet(xslStylesheet); // process the file - // ... + // … } ``` diff --git a/files/en-us/web/css/-moz-float-edge/index.md b/files/en-us/web/css/-moz-float-edge/index.md index 5d64a05a5ab99c2..dc079caa4918b63 100644 --- a/files/en-us/web/css/-moz-float-edge/index.md +++ b/files/en-us/web/css/-moz-float-edge/index.md @@ -38,10 +38,7 @@ The non-standard **`-moz-float-edge`** [CSS](/en-US/docs/Web/CSS) property speci ## Formal syntax -```plain --moz-float-edge = - content-box | margin-box -``` +{{CSSSyntaxRaw(`-moz-float-edge = content-box | margin-box`)}} ## Examples diff --git a/files/en-us/web/css/-moz-force-broken-image-icon/index.md b/files/en-us/web/css/-moz-force-broken-image-icon/index.md index b0e1bd0424d83b5..78f518fb5d43b4b 100644 --- a/files/en-us/web/css/-moz-force-broken-image-icon/index.md +++ b/files/en-us/web/css/-moz-force-broken-image-icon/index.md @@ -17,7 +17,7 @@ The **`-moz-force-broken-image-icon`** extended CSS property can be used to forc ### Values - {{cssxref("&lt;integer&gt;")}} - - : A value of `1` means that the broken image icon is shown even if the image has an [`alt`](/en-US/docs/Web/HTML/Element/img#alt) attribute. When the value `0` is used, the image will act as usual and only display the `alt` attribute. + - : A value of `1` means that the broken image icon is shown even if the image has an [`alt`](/en-US/docs/Web/HTML/Reference/Elements/img#alt) attribute. When the value `0` is used, the image will act as usual and only display the `alt` attribute. > [!NOTE] > Even if the value is set to `1` the `alt` attribute will still be displayed, alongside the broken image icon. @@ -28,9 +28,7 @@ The **`-moz-force-broken-image-icon`** extended CSS property can be used to forc ## Formal syntax -```plain --moz-force-broken-image-icon = {{cssxref("&lt;integer&gt;")}} -``` +{{CSSSyntaxRaw(`-moz-force-broken-image-icon = <integer>`)}} ## Examples diff --git a/files/en-us/web/css/-moz-image-rect/index.md b/files/en-us/web/css/-moz-image-rect/index.md index 6e6a770131c2aa5..467ba5852dc901f 100644 --- a/files/en-us/web/css/-moz-image-rect/index.md +++ b/files/en-us/web/css/-moz-image-rect/index.md @@ -69,6 +69,8 @@ Then the four boxes defining the segments of the image are defined. Let's look a background-image: -moz-image-rect(url(firefox.png), 0%, 50%, 50%, 0%); width: 133px; height: 136px; + left: 0px; + top: 0px; position: absolute; } ``` @@ -80,6 +82,8 @@ This is the top-left corner of the image. It defines a rectangle containing the background-image: -moz-image-rect(url(firefox.png), 0%, 100%, 50%, 50%); width: 133px; height: 136px; + left: 133px; + top: 0px; position: absolute; } ``` @@ -93,12 +97,16 @@ The other corners follow a similar pattern: background-image: -moz-image-rect(url(firefox.png), 50%, 50%, 100%, 0%); width: 133px; height: 136px; + left: 0px; + top: 136px; position: absolute; } #box4 { background-image: -moz-image-rect(url(firefox.png), 50%, 100%, 100%, 50%); width: 133px; height: 136px; + left: 133px; + top: 136px; position: absolute; } ``` @@ -108,17 +116,17 @@ The other corners follow a similar pattern: We include a container with four boxes: ```html -<div id="container" onclick="rotate()"> - <div id="box1" style="left:0px;top:0px;">Top left</div> - <div id="box2" style="left:133px;top:0px;">Top right</div> - <div id="box3" style="left:0px;top:136px;">Bottom left</div> - <div id="box4" style="left:133px;top:136px;">Bottom right</div> +<div id="container"> + <div id="box1">Top left</div> + <div id="box2">Top right</div> + <div id="box3">Bottom left</div> + <div id="box4">Bottom right</div> </div> ``` This places the four segments of our image in a two-by-two box grid. These four segments are all contained within a larger {{HTMLElement("div")}} block whose primary purpose is to receive click events and dispatch them to our JavaScript code. -### The JavaScript code +### JavaScript This code handles the click event when the container receives a mouse click. @@ -140,6 +148,8 @@ function rotate() { prevStyle = curStyle; } } + +document.getElementById("container").addEventListener("click", rotate); ``` This uses {{DOMxRef("window.getComputedStyle()")}} to fetch the style of each element, shifting it to the following element. Notice that before it begins doing so it saves a copy of the last box's style since it will be overwritten by the third element's style. By copying the values of the {{CSSxRef("background-image")}} property from one element to the next with each mouse click, we achieve the desired effect. diff --git a/files/en-us/web/css/-moz-image-region/index.md b/files/en-us/web/css/-moz-image-region/index.md index e45c2442b4c6f8d..e9184ad43d7a01a 100644 --- a/files/en-us/web/css/-moz-image-region/index.md +++ b/files/en-us/web/css/-moz-image-region/index.md @@ -41,10 +41,7 @@ The syntax is similar to the {{CSSxRef("clip")}} property. All four values are r ## Formal syntax -```plain - -moz-image-region = - <shape> | auto -``` +{{CSSSyntaxRaw(`-moz-image-region = <shape> | auto`)}} ## Examples diff --git a/files/en-us/web/css/-moz-orient/index.md b/files/en-us/web/css/-moz-orient/index.md index 2c9022558570bcc..c275e70b5cd0ba6 100644 --- a/files/en-us/web/css/-moz-orient/index.md +++ b/files/en-us/web/css/-moz-orient/index.md @@ -32,10 +32,7 @@ The `-moz-orient` property is specified as one of the keyword values chosen from ## Formal syntax -```plain --moz-orient = - inline | block | horizontal | vertical -``` +{{CSSSyntaxRaw(`-moz-orient = inline | block | horizontal | vertical`)}} ## Examples diff --git a/files/en-us/web/css/-moz-user-focus/index.md b/files/en-us/web/css/-moz-user-focus/index.md index 5e6ab4cde71a39c..96a7b6fc8694b79 100644 --- a/files/en-us/web/css/-moz-user-focus/index.md +++ b/files/en-us/web/css/-moz-user-focus/index.md @@ -45,10 +45,7 @@ The default is `none`, which disables focussing on the element and removes focus ## Formal syntax -```plain --moz-user-focus = - ignore | normal | none -``` +{{CSSSyntaxRaw(`-moz-user-focus = ignore | normal | none`)}} ## Examples diff --git a/files/en-us/web/css/-moz-user-input/index.md b/files/en-us/web/css/-moz-user-input/index.md index 3fbadb6a3766736..f671c49d6fc356e 100644 --- a/files/en-us/web/css/-moz-user-input/index.md +++ b/files/en-us/web/css/-moz-user-input/index.md @@ -42,10 +42,7 @@ The `user-input` property is currently not on a standards track. ## Formal syntax -```plain --moz-user-input = - auto | none -``` +{{CSSSyntaxRaw(`-moz-user-input = auto | none`)}} ## Examples diff --git a/files/en-us/web/css/-webkit-border-before/index.md b/files/en-us/web/css/-webkit-border-before/index.md index 43c9becefd3591a..88beff9f167d5fd 100644 --- a/files/en-us/web/css/-webkit-border-before/index.md +++ b/files/en-us/web/css/-webkit-border-before/index.md @@ -60,10 +60,7 @@ The standard-track equivalent of this property is {{cssxref("border-block-start" ## Formal syntax -```plain --webkit-border-before = - <'border-width'> || <'border-style'> || <color> -``` +{{CSSSyntaxRaw(`-webkit-border-before = <'border-width'> || <'border-style'> || <color>`)}} ## Examples diff --git a/files/en-us/web/css/-webkit-box-reflect/index.md b/files/en-us/web/css/-webkit-box-reflect/index.md index d7624382efa8f10..fa9d8df4de3f48b 100644 --- a/files/en-us/web/css/-webkit-box-reflect/index.md +++ b/files/en-us/web/css/-webkit-box-reflect/index.md @@ -49,10 +49,7 @@ The **`-webkit-box-reflect`** [CSS](/en-US/docs/Web/CSS) property lets you refle ## Formal syntax -```plain --webkit-box-reflect = - [ above | below | right | left ]? <length>? <image>? -``` +{{CSSSyntaxRaw(`-webkit-box-reflect = [ above | below | right | left ]? <length>? <image>?`)}} ## Specifications diff --git a/files/en-us/web/css/-webkit-mask-box-image/index.md b/files/en-us/web/css/-webkit-mask-box-image/index.md index b348b31b95807f3..a3b6453a7ed0876 100644 --- a/files/en-us/web/css/-webkit-mask-box-image/index.md +++ b/files/en-us/web/css/-webkit-mask-box-image/index.md @@ -78,24 +78,14 @@ Border repeat styles, when included, are interpreted in the order of `<repeat-x> ## Formal definition -- [Initial value](/en-US/docs/Web/CSS/CSS_cascade/initial_value): `none` +- [Initial value](/en-US/docs/Web/CSS/CSS_cascade/Value_processing#initial_value): `none` - Applies to: all elements - [Inherited](/en-US/docs/Web/CSS/CSS_cascade/Inheritance): no -- [Computed value](/en-US/docs/Web/CSS/CSS_cascade/computed_value): as specified +- [Computed value](/en-US/docs/Web/CSS/CSS_cascade/Value_processing#computed_value): as specified ## Formal syntax -```plain --webkit-mask-box-image: <mask-image-source> [<mask-image-offset>{4} <mask-border-repeat>{1,2} ] - -Where: - -<mask-image-source> = {{cssxref("url_value", "&lt;url&gt;")}} | <gradient> | none - -<mask-image-offset> = <length> | <percentage> | <number> - -<repeat-style> = repeat | stretch | round | space -``` +{{CSSSyntaxRaw(`-webkit-mask-box-image = <mask-image-source> [ <mask-image-offset>{4} <mask-border-repeat>{1,2} ]`)}} ## Examples @@ -111,7 +101,7 @@ Where: ```css .example-two { - -webkit-mask-box-image: url("logo.png") 100 100 0 0 round round; + -webkit-mask-box-image: url("logo.png") 100px 100px 0px 0px round round; } ``` diff --git a/files/en-us/web/css/-webkit-mask-composite/index.md b/files/en-us/web/css/-webkit-mask-composite/index.md index c8160cc491e9e46..5646fa106de08ab 100644 --- a/files/en-us/web/css/-webkit-mask-composite/index.md +++ b/files/en-us/web/css/-webkit-mask-composite/index.md @@ -69,10 +69,7 @@ The **`-webkit-mask-composite`** property specifies the manner in which multiple ## Formal syntax -```plain --webkit-mask-composite = - <composite-style># -``` +{{CSSSyntaxRaw(`-webkit-mask-composite = <composite-style>#`)}} ## Examples diff --git a/files/en-us/web/css/-webkit-mask-position-x/index.md b/files/en-us/web/css/-webkit-mask-position-x/index.md index 5e6db4510dd7acc..795a41d231a522e 100644 --- a/files/en-us/web/css/-webkit-mask-position-x/index.md +++ b/files/en-us/web/css/-webkit-mask-position-x/index.md @@ -58,10 +58,7 @@ The `-webkit-mask-position-x` CSS property sets the initial horizontal position ## Formal syntax -```plain --webkit-mask-position-x = - [ <length-percentage> | left | center | right ]# -``` +{{CSSSyntaxRaw(`-webkit-mask-position-x = [ <length-percentage> | left | center | right ]#`)}} ## Examples diff --git a/files/en-us/web/css/-webkit-mask-position-y/index.md b/files/en-us/web/css/-webkit-mask-position-y/index.md index be6fe5c732ca04a..5755dd335726ce9 100644 --- a/files/en-us/web/css/-webkit-mask-position-y/index.md +++ b/files/en-us/web/css/-webkit-mask-position-y/index.md @@ -58,10 +58,7 @@ The `-webkit-mask-position-y` CSS property sets the initial vertical position of ## Formal syntax -```plain --webkit-mask-position-y = - [ <length-percentage> | top | center | bottom ]# -``` +{{CSSSyntaxRaw(`-webkit-mask-position-y = [ <length-percentage> | top | center | bottom ]#`)}} ## Examples diff --git a/files/en-us/web/css/-webkit-mask-repeat-x/index.md b/files/en-us/web/css/-webkit-mask-repeat-x/index.md index cb8cffee664070f..0a4b7e87f405fc8 100644 --- a/files/en-us/web/css/-webkit-mask-repeat-x/index.md +++ b/files/en-us/web/css/-webkit-mask-repeat-x/index.md @@ -50,10 +50,7 @@ The `-webkit-mask-repeat-x` property specifies whether and how a mask image is r ## Formal syntax -```plain --webkit-mask-repeat-x = - repeat | no-repeat | space | round -``` +{{CSSSyntaxRaw(`-webkit-mask-repeat-x = [ repeat | no-repeat | space | round ]#`)}} ## Examples diff --git a/files/en-us/web/css/-webkit-mask-repeat-y/index.md b/files/en-us/web/css/-webkit-mask-repeat-y/index.md index f948d6331181961..f935457d7bdaa80 100644 --- a/files/en-us/web/css/-webkit-mask-repeat-y/index.md +++ b/files/en-us/web/css/-webkit-mask-repeat-y/index.md @@ -50,10 +50,7 @@ The `-webkit-mask-repeat-y` property sets whether and how a mask image is repeat ## Formal syntax -```plain --webkit-mask-repeat-y = - repeat | no-repeat | space | round -``` +{{CSSSyntaxRaw(`-webkit-mask-repeat-y = [ repeat | no-repeat | space | round ]#`)}} ## Examples diff --git a/files/en-us/web/css/-webkit-tap-highlight-color/index.md b/files/en-us/web/css/-webkit-tap-highlight-color/index.md index 1a1f444d1895fae..0ff50652ec17243 100644 --- a/files/en-us/web/css/-webkit-tap-highlight-color/index.md +++ b/files/en-us/web/css/-webkit-tap-highlight-color/index.md @@ -35,10 +35,7 @@ A {{Cssxref("&lt;color&gt;")}}. ## Formal syntax -```plain --webkit-tap-highlight-color = - <color> -``` +{{CSSSyntaxRaw(`-webkit-tap-highlight-color = <color>`)}} ## Specifications diff --git a/files/en-us/web/css/-webkit-text-security/index.md b/files/en-us/web/css/-webkit-text-security/index.md index bb100e90cdfe1f3..04e6429aaf51258 100644 --- a/files/en-us/web/css/-webkit-text-security/index.md +++ b/files/en-us/web/css/-webkit-text-security/index.md @@ -29,9 +29,7 @@ browser-compat: css.properties.-webkit-text-security ## Formal syntax -```plain --webkit-text-security = circle | disc | square | none -``` +{{CSSSyntaxRaw(`-webkit-text-security = circle | disc | square | none`)}} ## Examples diff --git a/files/en-us/web/css/-webkit-text-stroke/index.md b/files/en-us/web/css/-webkit-text-stroke/index.md index 7cc775149ba738b..cacec470a97ee87 100644 --- a/files/en-us/web/css/-webkit-text-stroke/index.md +++ b/files/en-us/web/css/-webkit-text-stroke/index.md @@ -12,7 +12,6 @@ The **`-webkit-text-stroke`** [CSS](/en-US/docs/Web/CSS) property specifies the ```css /* Width and color values */ -webkit-text-stroke: 4px navy; -text-stroke: 4px navy; /* Global values */ -webkit-text-stroke: inherit; diff --git a/files/en-us/web/css/-webkit-touch-callout/index.md b/files/en-us/web/css/-webkit-touch-callout/index.md index 68065479213c4b0..072bc5fa2f7f5e6 100644 --- a/files/en-us/web/css/-webkit-touch-callout/index.md +++ b/files/en-us/web/css/-webkit-touch-callout/index.md @@ -41,10 +41,7 @@ When a target is touched and held on iOS, Safari displays a callout information ## Formal syntax -```plain --webkit-touch-callout = - default | none -``` +{{CSSSyntaxRaw(`-webkit-touch-callout = default | none`)}} ## Examples diff --git a/files/en-us/web/css/@container/index.md b/files/en-us/web/css/@container/index.md index 048c532f019d6fd..7d73debc5f51692 100644 --- a/files/en-us/web/css/@container/index.md +++ b/files/en-us/web/css/@container/index.md @@ -9,7 +9,7 @@ browser-compat: css.at-rules.container The **`@container`** [CSS](/en-US/docs/Web/CSS) [at-rule](/en-US/docs/Web/CSS/CSS_syntax/At-rule) is a conditional group rule that applies styles to a [containment context](/en-US/docs/Web/CSS/CSS_containment/Container_queries#naming_containment_contexts). Style declarations are filtered by a condition and applied to the container if the condition is true. -The condition is evaluated when the container size or [`<style-feature>`](#container_style_queries) value changes. +The condition is evaluated when the queried container size, [`<style-feature>`](#container_style_queries), or scroll-state changes. The {{cssxref("container-name")}} property specifies a list of query container names. These names can be used by `@container` rules to filter which query containers are targeted. The optional, case-sensitive `<container-name>` filters the query containers that are targeted by the query. @@ -28,28 +28,44 @@ The `@container` at-rule has the following syntax: For example: ```css +/* With a <size-query> */ @container (width > 400px) { h2 { font-size: 1.5em; } } -/* with an optional <container-name> */ +/* With an optional <container-name> */ @container tall (height > 30rem) { - h2 { + p { line-height: 1.6; } } -/* multiple queries in a single condition */ +/* With a <scroll-state> */ +@container scroll-state(scrollable: top) { + .back-to-top-link { + visibility: visible; + } +} + +/* With a <container-name> and a <scroll-state> */ +@container sticky-heading scroll-state(stuck: top) { + h2 { + background: purple; + color: white; + } +} + +/* Multiple queries in a single condition */ @container (width > 400px) and style(--responsive: true) { h2 { font-size: 1.5em; } } -/* condition list */ -@container card (width > 400px), style(--responsive: true) { +/* Condition list */ +@container card (width > 400px), style(--responsive: true), scroll-state(stuck: top) { h2 { font-size: 1.5em; } @@ -65,10 +81,10 @@ For example: - `<container-name>` - : Optional. The name of the container that the styles will be applied to when the query evaluates to true, specified as an {{cssxref("ident")}}. - `<container-query>` - - : A set of features that are evaluated against the query container when the size of the container changes. + - : A set of features that are evaluated against the query container when the size, [`<style-feature>`](#container_style_queries), or scroll-state of the container changes. - `<stylesheet>` - - : A set of CSS declarations. + - : A set of CSS rules or declarations. ### Logical keywords in container queries @@ -123,7 +139,23 @@ Details about usage and naming restrictions are described in the {{cssxref("cont ### Descriptors -The following descriptors can be used within the container condition: +The `<container-condition>` queries include [size](#size_container_descriptors) and [scroll-state](#scroll-state_container_descriptors) container descriptors. + +#### Size container descriptors + +The `<container-condition>` can include one or more boolean size queries, each within a set of parentheses. A size query includes a size descriptor, a value, and — depending on the descriptor — a comparison operator. The syntax for including multiple conditions is the same as for [`@media`](/en-US/docs/Web/CSS/@media) size feature queries. + +```css +@container (min-width: 400px) { + /* … */ +} +@container (orientation: landscape) and (width > 400px) { + /* … */ +} +@container (15em <= block-size <= 30em) { + /* … */ +} +``` - `aspect-ratio` @@ -148,6 +180,143 @@ The following descriptors can be used within the container condition: - `width` - : The width of the container expressed as a {{cssxref("length")}} value. +#### Scroll-state container descriptors + +Scroll-state container descriptors are specified inside the `<container-condition>` within a set of parentheses following the `scroll-state` keyword, for example: + +```css +@container scroll-state(scrollable: top) { + /* … */ +} +@container scroll-state(stuck: inline-end) { + /* … */ +} +@container scroll-state(snapped: both) { + /* … */ +} +``` + +Supported keywords for scroll-state container descriptors include physical and {{glossary("flow relative values")}} + +- `scrollable` + + - : Queries whether the container can be scrolled in the given direction via user-initiated scrolling, such as by dragging the scrollbar or using a trackpad gesture. In other words, is there overflowing content in the given direction that can be scrolled to? Valid `scrollable` values include the following keywords: + + - `none` + - : The container is not a {{glossary("scroll container")}} or otherwise cannot be scrolled in any direction. + - `top` + - : The container can be scrolled towards its top edge. + - `right` + - : The container can be scrolled towards its right-hand edge. + - `bottom` + - : The container can be scrolled towards its bottom edge. + - `left` + - : The container can be scrolled towards its left-hand edge. + - `x` + - : The container can be scrolled horizontally towards either or both of its left-hand or right-hand edges. + - `y` + - : The container can be scrolled vertically towards either or both of its top or bottom edges. + - `block-start` + - : The container can be scrolled towards its block-start edge. + - `block-end` + - : The container can be scrolled towards its block-end edge. + - `inline-start` + - : The container can be scrolled towards its inline-start edge. + - `inline-end` + - : The container can be scrolled towards its inline-end edge. + - `block` + - : The container can be scrolled in its block direction towards either or both of its block-start or block-end edges. + - `inline` + - : The container can be scrolled in its inline direction towards either or both of its inline-start and inline-end edges. + + If the test passes, the rules inside the `@container` block are applied to descendants of the scroll container. + + To evaluate whether a container is scrollable, without being concerned about the direction, use the `none` value with the `not` operator: + + ```css + @container not scroll-state(scrollable: none) { + /* … */ + } + ``` + +- `snapped` + + - : Queries whether the container is, or will be, snapped to a [scroll snap](/en-US/docs/Web/CSS/CSS_scroll_snap) container ancestor along the given axis. Valid `snapped` values include the following keywords: + + - `none` + - : The container is not a scroll [snap target](/en-US/docs/Glossary/Scroll_snap#snap_target) for its ancestor scroll container. When implementing a `snapped: none` query, containers that _are_ snap targets for the scroll container will _not_ have the `@container` styles applied, whereas non-snap targets _will_ have the styles applied. + - `x` + - : The container is a horizontal scroll snap target for its ancestor scroll container, that is, it is snapping horizontally to its ancestor. + - `y` + - : The container is a vertical scroll snap target for its ancestor scroll container, that is, it is snapping vertically to its ancestor. + - `block` + - : The container is a block-axis scroll snap target for its ancestor scroll container, that is, it is snapping to its ancestor in the block direction. + - `inline` + - : The container is an inline-axis scroll snap target for its ancestor scroll container, that is, it is snapping to its ancestor in the inline direction. + - `both` + - : The container is both a horizontal and vertical scroll snap target for its ancestor scroll container and is snapping to its ancestor in both directions. The container won't match if it is only snapping to its ancestor along the horizontal _or_ vertical axis. It needs to be both. + + To evaluate a container with a non-`none` `snapped` scroll-state query, it must be a container with a scroll container ancestor having a {{cssxref("scroll-snap-type")}} value other than `none`. A `snapped: none` query will match even when there is no scroll container ancestor. + + Evaluations occur when [`scrollsnapchanging`](/en-US/docs/Web/API/Element/scrollsnapchanging_event) events fire on the scroll snap container. If the test passes, the rules inside the `@container` block are applied to descendants of the container. + + To evaluate whether a container is a snap target, without being concerned about the direction, use the `none` value with the `not` operator: + + ```css + @container not scroll-state(snapped: none) { + /* … */ + } + ``` + +- `stuck` + + - : Queries whether a container with a {{cssxref("position")}} value of [`sticky`](/en-US/docs/Learn_web_development/Core/CSS_layout/Positioning#sticky_positioning) is stuck to an edge of its scrolling container ancestor. Valid `stuck` values include the following keywords: + + - `none` + - : The container is not stuck to any edges of its container. Note that `none` queries will match even if the container does not have `position: sticky` set on it. + - `top` + - : The container is stuck to the top edge of its container. + - `right` + - : The container is stuck to the right-hand edge of its container. + - `bottom` + - : The container is stuck to the bottom edge of its container. + - `left` + - : The container is stuck to the left-hand edge of its container. + - `block-start` + - : The container is stuck to the block-start edge of its container. + - `block-end` + - : The container is stuck to the block-end edge of its container. + - `inline-start` + - : The container is stuck to the inline-start edge of its container. + - `inline-end` + - : The container is stuck to the inline-end edge of its container. + + To evaluate a container with a non-`none` `stuck` scroll-state query, it must have `position: sticky` set on it, and be inside a scroll container. If the test passes, the rules inside the `@container` block are applied to descendants of the `position: sticky` container. + + It is possible for two values from opposite axes to match at the same time: + + ```css + @container scroll-state((stuck: top) and (stuck: left)) { + /* … */ + } + ``` + + However, two values from opposite edges will never match at the same time: + + ```css + @container scroll-state((stuck: left) and (stuck: right)) { + /* … */ + } + ``` + + To evaluate whether a container is stuck, without being concerned about the direction, use the `none` value with the `not` operator: + + ```css + @container not scroll-state(stuck: none) { + /* … */ + } + ``` + ## Formal syntax {{csssyntax}} @@ -173,11 +342,11 @@ You can then use the `@container` at-rule to apply styles to the element with th ```js hidden const post = document.querySelector(".post"); const span = document.createElement("span"); -span.textContent = ".post width: " + post.clientWidth + "px"; +span.textContent = `.post width: ${post.clientWidth}px`; post.parentNode.insertBefore(span, post.nextSibling); // update on resize window.addEventListener("resize", () => { - span.textContent = ".post width: " + post.clientWidth + "px"; + span.textContent = `.post width: ${post.clientWidth}px`; }); ``` @@ -206,7 +375,7 @@ span { @container (width < 650px) { .card { width: 50%; - background-color: gray; + background-color: lightgray; font-size: 1em; } } @@ -290,7 +459,7 @@ A style feature without a value evaluates to true if the computed value is diffe If the `<style-feature>` passed as the `style()` function's argument is a declaration, the style query evaluates to true if the declaration's value is the same as the computed value of that property for the container being queried. Otherwise, it resolves to false. -The following container query checks if the {{cssxref("computed_value")}} of the container element's `--accent-color` is `blue`: +The following container query checks if the [computed value](/en-US/docs/Web/CSS/CSS_cascade/Value_processing#computed_value) of the container element's `--accent-color` is `blue`: ```css @container style(--accent-color: blue) { @@ -305,6 +474,10 @@ Style features that query a shorthand property are true if the computed values m The global `revert` and `revert-layer` are invalid as values in a `<style-feature>` and cause the container style query to be false. +### Scroll-state queries + +See [Using container scroll-state queries](/en-US/docs/Web/CSS/CSS_conditional_rules/Container_scroll-state_queries) for full walkthroughs of scroll-state query examples. + ## Specifications {{Specifications}} @@ -317,6 +490,7 @@ The global `revert` and `revert-layer` are invalid as values in a `<style-featur - [Using container queries](/en-US/docs/Web/CSS/CSS_containment/Container_queries) - [Using container size and style queries](/en-US/docs/Web/CSS/CSS_containment/Container_size_and_style_queries) +- [Using container scroll-state queries](/en-US/docs/Web/CSS/CSS_conditional_rules/Container_scroll-state_queries) - {{Cssxref("container-name")}} - {{Cssxref("container-type")}} - {{Cssxref("contain")}} diff --git a/files/en-us/web/css/@counter-style/index.md b/files/en-us/web/css/@counter-style/index.md index 7866325e9fe4781..1f63798be1ee4bb 100644 --- a/files/en-us/web/css/@counter-style/index.md +++ b/files/en-us/web/css/@counter-style/index.md @@ -126,7 +126,7 @@ See more examples on the [demo page](https://mdn.github.io/css-examples/counter- ### Ready-made counter styles -Find a collection of over 100 `counter-style` code snippets in the [Ready-made Counter Styles](https://www.w3.org/TR/predefined-counter-styles/) document. This document provides counters that meet the needs of languages and cultures around the world. +Find a collection of over 100 `counter-style` code snippets in the [Ready-made Counter Styles](https://w3c.github.io/predefined-counter-styles/) document. This document provides counters that meet the needs of languages and cultures around the world. The [Counter styles converter](https://r12a.github.io/app-counters/) pulls from this list to test and create copy and paste code for counter styles. diff --git a/files/en-us/web/css/@counter-style/system/index.md b/files/en-us/web/css/@counter-style/system/index.md index c92f5a936119d61..e479910bdf3b297 100644 --- a/files/en-us/web/css/@counter-style/system/index.md +++ b/files/en-us/web/css/@counter-style/system/index.md @@ -299,7 +299,7 @@ This example renders a list using Roman numerals. Notice that a `range` is speci #### HTML -We use the [`start`](/en-US/docs/Web/HTML/Element/ol#start) attribute on the {{HTMLElement("ol")}} element to demonstrate that counting doesn't need to start at `1`. Additionally, we use the [`value`](/en-US/docs/Web/HTML/Element/li#value) attribute on the fifth {{HTMLElement("li")}} element to demonstrate that the counters you define using `@counter-style` behave just like native counters. +We use the [`start`](/en-US/docs/Web/HTML/Reference/Elements/ol#start) attribute on the {{HTMLElement("ol")}} element to demonstrate that counting doesn't need to start at `1`. Additionally, we use the [`value`](/en-US/docs/Web/HTML/Reference/Elements/li#value) attribute on the fifth {{HTMLElement("li")}} element to demonstrate that the counters you define using `@counter-style` behave just like native counters. ```html <ol start="48"> diff --git a/files/en-us/web/css/@document/index.md b/files/en-us/web/css/@document/index.md index 9f154b5d6fc177e..f561871d0d13e1e 100644 --- a/files/en-us/web/css/@document/index.md +++ b/files/en-us/web/css/@document/index.md @@ -40,7 +40,7 @@ The values provided to the `url()`, `url-prefix()`, `domain()`, and `media-docum Escaped values provided to the `regexp()` function must additionally be escaped from the CSS. For example, a `.` (period) matches any character in regular expressions. To match a literal period, you would first need to escape it using regular expression rules (to `\.`), then escape that string using CSS rules (to `\\.`). -`@document` is currently only supported in Firefox; if you wanted to replicate using such functionality in your own non-Firefox browser, you could try using [this polyfill](https://github.com/An-Error94/Handy-Scripts/tree/master/%40document-polyfill) by @An-Error94, which uses a combination of a user script, [data-\* attributes](/en-US/docs/Web/HTML/Global_attributes/data-*), and [attribute selectors](/en-US/docs/Web/CSS/Attribute_selectors). +`@document` is currently only supported in Firefox; if you wanted to replicate using such functionality in your own non-Firefox browser, you could try using [this polyfill](https://github.com/An-Error94/Handy-Scripts/tree/master/%40document-polyfill) by @An-Error94, which uses a combination of a user script, [data-\* attributes](/en-US/docs/Web/HTML/Reference/Global_attributes/data-*), and [attribute selectors](/en-US/docs/Web/CSS/Attribute_selectors). > [!NOTE] > There is a -moz-prefixed version of this property — `@-moz-document`. This has been limited to use only in user and UA sheets in Firefox 59 in Nightly and Beta — an experiment designed to mitigate potential CSS injection attacks (See [Firefox bug 1035091](https://bugzil.la/1035091)). diff --git a/files/en-us/web/css/@font-face/font-stretch/index.md b/files/en-us/web/css/@font-face/font-stretch/index.md index ce8ff2ecdaf9357..36508cba2d4a5ab 100644 --- a/files/en-us/web/css/@font-face/font-stretch/index.md +++ b/files/en-us/web/css/@font-face/font-stretch/index.md @@ -113,7 +113,7 @@ For TrueType or OpenType variable fonts, the "wdth" variation is used to impleme People with dyslexia and other cognitive conditions may have difficulty reading fonts that are too condensed, especially if the font has a [low contrast color ratio](/en-US/docs/Web/CSS/color#accessibility). -- [MDN Understanding WCAG, Guideline 1.4 explanations](/en-US/docs/Web/Accessibility/Understanding_WCAG/Perceivable#guideline_1.4_make_it_easier_for_users_to_see_and_hear_content_including_separating_foreground_from_background) +- [MDN Understanding WCAG, Guideline 1.4 explanations](/en-US/docs/Web/Accessibility/Guides/Understanding_WCAG/Perceivable#guideline_1.4_make_it_easier_for_users_to_see_and_hear_content_including_separating_foreground_from_background) - [Understanding Success Criterion 1.4.8 | W3C Understanding WCAG 2.0](https://www.w3.org/TR/UNDERSTANDING-WCAG20/visual-audio-contrast-visual-presentation.html) ## Formal definition @@ -122,7 +122,7 @@ People with dyslexia and other cognitive conditions may have difficulty reading ## Formal syntax -{{csssyntax}} +{{CSSSyntax("font-width")}} ## Examples diff --git a/files/en-us/web/css/@font-face/font-weight/index.md b/files/en-us/web/css/@font-face/font-weight/index.md index 20f5defe9ca15a5..d5067b7eaf65d48 100644 --- a/files/en-us/web/css/@font-face/font-weight/index.md +++ b/files/en-us/web/css/@font-face/font-weight/index.md @@ -7,7 +7,7 @@ browser-compat: css.at-rules.font-face.font-weight {{CSSRef}} -The **`font-weight`** CSS {{cssxref("@font-face")}} descriptor enables authors to specify a single font weight, or a range of font weights, for the font specified in a {{cssxref("@font-face")}} at-rule. This is then used by the browser to select the appropriate font when a CSS rule sets a desired {{cssxref("font-weight", "font weight")}}. +The **`font-weight`** CSS {{cssxref("@font-face")}} descriptor enables authors to specify a single font weight, or a range of font weights, for the font specified in a {{cssxref("@font-face")}} at-rule. This is then used by the browser to select the appropriate font when a CSS rule sets a desired [font weight](/en-US/docs/Web/CSS/font-weight). Typically, a developer will want to use fonts from a single font family in a range of different weights. With traditional, or _static_ fonts, a single font file contains characters from a font family in a specific weight and style: for example, "Helvetica bold italic". To enable displaying light, regular, bold, or extra-bold fonts when the `font-weight` property calls a specific weight, you can define multiple {{cssxref("@font-face")}} at-rules for the same family (all with the same {{cssxref("@font-face/font-family", "font-family")}} descriptor value), one for each weight or range of weights. @@ -74,7 +74,7 @@ For TrueType or OpenType variable fonts, the "wght" variation is used to impleme People experiencing low vision conditions may have difficulty reading text set with a `font-weight` value of `100` (Thin/Hairline) or `200` (Extra Light), especially if the font has a [low contrast color ratio](/en-US/docs/Web/CSS/color#accessibility). -- [MDN Understanding WCAG, Guideline 1.4 explanations](/en-US/docs/Web/Accessibility/Understanding_WCAG/Perceivable#guideline_1.4_make_it_easier_for_users_to_see_and_hear_content_including_separating_foreground_from_background) +- [MDN Understanding WCAG, Guideline 1.4 explanations](/en-US/docs/Web/Accessibility/Guides/Understanding_WCAG/Perceivable#guideline_1.4_make_it_easier_for_users_to_see_and_hear_content_including_separating_foreground_from_background) - [Understanding Success Criterion 1.4.8 | W3C Understanding WCAG 2.0](https://www.w3.org/TR/UNDERSTANDING-WCAG20/visual-audio-contrast-visual-presentation.html) ## Formal definition diff --git a/files/en-us/web/css/@font-face/index.md b/files/en-us/web/css/@font-face/index.md index 56c4d2e6c404556..8d041958e0de89e 100644 --- a/files/en-us/web/css/@font-face/index.md +++ b/files/en-us/web/css/@font-face/index.md @@ -78,7 +78,7 @@ The `@font-face` at-rule may be used not only at the top level of a CSS, but als ### Notes -- Web fonts are subject to the same domain restriction (font files must be on the same domain as the page using them), unless [HTTP access controls](/en-US/docs/Web/HTTP/CORS) are used to relax this restriction. +- Web fonts are subject to the same domain restriction (font files must be on the same domain as the page using them), unless [HTTP access controls](/en-US/docs/Web/HTTP/Guides/CORS) are used to relax this restriction. - `@font-face` cannot be declared within a CSS selector. For example, the following will not work: ```css example-bad diff --git a/files/en-us/web/css/@font-face/src/index.md b/files/en-us/web/css/@font-face/src/index.md index 07322149672e447..0a407cb3a9345a4 100644 --- a/files/en-us/web/css/@font-face/src/index.md +++ b/files/en-us/web/css/@font-face/src/index.md @@ -123,7 +123,7 @@ To check if a font format is supported by a browser within CSS, use the {{cssxre > [!NOTE] > -> - `format(svg)` stands for [SVG fonts](/en-US/docs/Web/SVG/Tutorial/SVG_fonts), and `tech(color-SVG)` stands for [OpenType fonts with SVG table](https://learn.microsoft.com/en-us/typography/opentype/spec/svg) (also called OpenType-SVG color fonts), which are completely different. +> - `format(svg)` stands for [SVG fonts](/en-US/docs/Web/SVG/Tutorials/SVG_from_scratch/Using_fonts), and `tech(color-SVG)` stands for [OpenType fonts with SVG table](https://learn.microsoft.com/en-us/typography/opentype/spec/svg) (also called OpenType-SVG color fonts), which are completely different. > - The `opentype` and `truetype` values are equivalent whether the font file uses cubic bezier curves (within CFF/CFF2 table) or quadratic bezier curves (within glyph table). Older non-normalized `format()` values have the following equivalent syntax; provided as a string enclosed in quotes for backward-compatibility reasons: @@ -160,18 +160,9 @@ To check if a font technology is supported by a browser within CSS, use the {{cs ## Formal syntax -```plain -<url> [ format( <font-format> ) ]? [ tech( <font-tech># ) ]? | -local( <family-name> ) +{{CSSSyntax}} -<font-format> = [ <string> | collection | embedded-opentype | opentype | svg | truetype | woff | woff2 ] - -<font-tech> = [ <font-features-tech> | <color-font-tech> | variations | palettes | incremental-patch | incremental-range | incremental-auto ] - -<font-features-tech> = [ features-opentype | features-aat | features-graphite ] - -<color-font-tech> = [ color-COLRv0 | color-COLRv1 | color-SVG | color-sbix | color-CBDT ] -``` +{{CSSSyntaxRaw(`<font-src>`)}} ## Examples diff --git a/files/en-us/web/css/@font-palette-values/override-colors/index.md b/files/en-us/web/css/@font-palette-values/override-colors/index.md index 1fdb49070f50c36..e3d7f1cc1dd81f3 100644 --- a/files/en-us/web/css/@font-palette-values/override-colors/index.md +++ b/files/en-us/web/css/@font-palette-values/override-colors/index.md @@ -158,7 +158,7 @@ h2 { #### Result -This example shows the that in `base-palette` `3`, the color at index 0 is overridden with `rebeccapurple`. +This example shows that in `base-palette` `3`, the color at index 0 is overridden with `rebeccapurple`. ![Example showing base-palette and base-palette with 1 color overridden](override-base-palette-color.jpg) diff --git a/files/en-us/web/css/@import/index.md b/files/en-us/web/css/@import/index.md index ee74ea7c2d25fbd..b63f5f8443b8fb9 100644 --- a/files/en-us/web/css/@import/index.md +++ b/files/en-us/web/css/@import/index.md @@ -31,7 +31,7 @@ where: - _list-of-media-queries_ - : Is a comma-separated list of [media queries](/en-US/docs/Web/CSS/CSS_media_queries/Using_media_queries), which specify the media-dependent conditions for applying the CSS rules defined in the linked URL. If the browser does not support any of these queries, it does not load the linked resource. - _layer-name_ - - : Is the name of a [cascade layer](/en-US/docs/Web/CSS/@layer) into which the contents of the linked resource are imported. + - : Is the name of a [cascade layer](/en-US/docs/Web/CSS/@layer) into which the contents of the linked resource are imported. See [`layer()`](/en-US/docs/Web/CSS/@import/layer_function) for more information. - _supports-condition_ - : Indicates the feature(s) that the browser must support in order for the stylesheet to be imported. If the browser does not conform to the conditions specified in the _supports-condition_, it may not fetch the linked stylesheet, and even if downloaded through some other path, will not load it. @@ -102,13 +102,13 @@ The `@import` rules in the above examples show media-dependent conditions that w ### Importing CSS rules conditional on feature support ```css -@import url("gridy.css") supports(display: grid) screen and (max-width: 400px); -@import url("flexy.css") supports((not (display: grid)) and (display: flex)) +@import url("grid.css") supports(display: grid) screen and (max-width: 400px); +@import url("flex.css") supports((not (display: grid)) and (display: flex)) screen and (max-width: 400px); ``` The `@import` rules above illustrate how you might import a layout that uses a grid if `display: grid` is supported, and otherwise imports CSS that uses `display: flex`. -While you can only have one `supports()` statement, you can combine any number of feature checks with `not`, `and`, and `or`. However, you must use parenthesis to define precedence when you mix them, e.g. `supports((..) or (..) and not (..))` is invalid, but `supports((..) or ((..) and (not (..))))` is valid. +While you can only have one `supports()` statement, you can combine any number of feature checks with `not`, `and`, and `or`. However, you must use parenthesis to define precedence when you mix them, e.g., `supports((..) or (..) and not (..))` is invalid, but `supports((..) or ((..) and (not (..))))` is valid. Note that if you just have a single declaration then you don't need to wrap it in additional parentheses: this is shown in the first example above. The examples above show support conditions using basic declaration syntax. diff --git a/files/en-us/web/css/@import/layer_function/index.md b/files/en-us/web/css/@import/layer_function/index.md index aa1bdd964946ac8..cf580a03e309c2f 100644 --- a/files/en-us/web/css/@import/layer_function/index.md +++ b/files/en-us/web/css/@import/layer_function/index.md @@ -20,7 +20,7 @@ The `framework.themes.dark` is the layer into which the CSS file would be import ## Formal syntax -{{CSSSyntax}} +{{CSSSyntaxRaw(`layer() = layer( <layer-name> )`)}} ## Specifications diff --git a/files/en-us/web/css/@media/forced-colors/index.md b/files/en-us/web/css/@media/forced-colors/index.md index 812311f51a704a1..d358325229e3e2c 100644 --- a/files/en-us/web/css/@media/forced-colors/index.md +++ b/files/en-us/web/css/@media/forced-colors/index.md @@ -36,8 +36,8 @@ These browser-specified values are selected from the set of system colors — th - {{cssxref("outline-color")}} - {{cssxref("column-rule-color")}} - {{cssxref("-webkit-tap-highlight-color")}} -- [SVG fill attribute](/en-US/docs/Web/SVG/Attribute/fill) -- [SVG stroke attribute](/en-US/docs/Web/SVG/Attribute/stroke) +- [SVG fill attribute](/en-US/docs/Web/SVG/Reference/Attribute/fill) +- [SVG stroke attribute](/en-US/docs/Web/SVG/Reference/Attribute/stroke) Additionally the following properties have special behavior in forced colors mode: diff --git a/files/en-us/web/css/@media/index.md b/files/en-us/web/css/@media/index.md index cdbfab3b3c23a4b..b495fa3680dcc96 100644 --- a/files/en-us/web/css/@media/index.md +++ b/files/en-us/web/css/@media/index.md @@ -16,13 +16,15 @@ The **`@media`** [CSS](/en-US/docs/Web/CSS) [at-rule](/en-US/docs/Web/CSS/CSS_sy ```css interactive-example abbr { - color: chocolate; + color: #860304; + font-weight: bold; + transition: color 0.5s ease; } @media (hover: hover) { abbr:hover { - color: limegreen; - transition-duration: 1s; + color: #001ca8; + transition-duration: 0.5s; } } @@ -154,7 +156,7 @@ Media feature expressions test for their presence, value, or range of values, an - {{cssxref("@media/scan", "scan")}} - : Whether display output is progressive or interlaced. - {{cssxref("@media/scripting", "scripting")}} - - : Detects whether scripting (i.e. JavaScript) is available. + - : Detects whether scripting (i.e., JavaScript) is available. Added in Media Queries Level 5. - {{cssxref("@media/shape", "shape")}} - : Detects the shape of the device to distinguish rectangular and round displays. @@ -164,6 +166,18 @@ Media feature expressions test for their presence, value, or range of values, an - : Combination of brightness, contrast ratio, and color depth that are supported by the video plane of user agent and the output device. Added in Media Queries Level 5. - {{cssxref("@media/width", "width")}} - : Width of the viewport including width of scrollbar. +- {{cssxref("@media/-moz-device-pixel-ratio", "-moz-device-pixel-ratio")}} + - : The number of device pixels per CSS pixel. Use the [`resolution`](/en-US/docs/Web/CSS/@media/resolution) feature with the `dppx` unit instead. +- {{cssxref("@media/-webkit-animation", "-webkit-animation")}} + - : The browser supports `-webkit` prefixed CSS {{cssxref("animation")}}. Use the [`@supports (animation)`](/en-US/docs/Web/CSS/@supports) feature query instead. +- {{cssxref("@media/-webkit-device-pixel-ratio", "-webkit-device-pixel-ratio")}} + - : The number of device pixels per CSS pixel. Use the [`resolution`](/en-US/docs/Web/CSS/@media/resolution) feature with the `dppx` unit instead. +- {{cssxref("@media/-webkit-transform-2d", "-webkit-transform-2d")}} + - : The browser supports `-webkit` prefixed 2D CSS {{cssxref("transform")}}. Use the [`@supports (transform)`](/en-US/docs/Web/CSS/@supports) feature query instead. +- {{cssxref("@media/-webkit-transform-3d", "-webkit-transform-3d")}} + - : The browser supports `-webkit` prefixed 3D CSS {{cssxref("transform")}}. Use the [`@supports (transform)`](/en-US/docs/Web/CSS/@supports) feature query instead. +- {{cssxref("@media/-webkit-transition", "-webkit-transition")}} + - : The browser supports `-webkit` prefixed CSS {{cssxref("transition")}}. Use the [`@supports (transition)`](/en-US/docs/Web/CSS/@supports) feature query instead. ### Logical operators @@ -196,7 +210,7 @@ You can also combine multiple media queries into a single rule by separating the ### User agent client hints -Some media queries have corresponding [user agent client hints](/en-US/docs/Web/HTTP/Client_hints). +Some media queries have corresponding [user agent client hints](/en-US/docs/Web/HTTP/Guides/Client_hints). These are HTTP headers that request content that is pre-optimized for the particular media requirement. They include {{HTTPHeader("Sec-CH-Prefers-Color-Scheme")}} and {{HTTPHeader("Sec-CH-Prefers-Reduced-Motion")}}. @@ -210,7 +224,7 @@ To best accommodate people who adjust a site's text size, use [`em`](/en-US/docs Both [`em`](/en-US/docs/Web/CSS/CSS_Values_and_Units/Numeric_data_types) and [`px`](/en-US/docs/Web/CSS/CSS_Values_and_Units/Numeric_data_types) are valid units, but [`em`](/en-US/docs/Web/CSS/CSS_Values_and_Units/Numeric_data_types) works better if the user changes the browser text size. -Also consider media queries or [HTTP user agent client hints](/en-US/docs/Web/HTTP/Client_hints#user-agent_client_hints) to improve the user's experience. +Also consider media queries or [HTTP user agent client hints](/en-US/docs/Web/HTTP/Guides/Client_hints#user_agent_client_hints) to improve the user's experience. For example, the media query [`prefers-reduced-motion`](/en-US/docs/Web/CSS/@media/prefers-reduced-motion) or the equivalent HTTP header {{HTTPHeader("Sec-CH-Prefers-Reduced-Motion")}}) can be used to minimize the amount of animation or motion used based on user preferences. ## Security diff --git a/files/en-us/web/css/@media/prefers-color-scheme/index.md b/files/en-us/web/css/@media/prefers-color-scheme/index.md index 145d6380ee21e3a..4821fab21ad9e17 100644 --- a/files/en-us/web/css/@media/prefers-color-scheme/index.md +++ b/files/en-us/web/css/@media/prefers-color-scheme/index.md @@ -8,16 +8,16 @@ browser-compat: css.at-rules.media.prefers-color-scheme {{CSSRef}} The **`prefers-color-scheme`** [CSS](/en-US/docs/Web/CSS) [media feature](/en-US/docs/Web/CSS/CSS_media_queries/Using_media_queries#targeting_media_features) is used to detect if a user has requested light or dark color themes. -A user indicates their preference through an operating system setting (e.g. light or dark mode) or a user agent setting. +A user indicates their preference through an operating system setting (e.g., light or dark mode) or a user agent setting. ## Embedded elements For SVG and iframes, `prefers-color-scheme` lets you set a CSS style for the SVG or iframe based on the [`color-scheme`](/en-US/docs/Web/CSS/color-scheme) of the parent element in the web page. -SVGs must be used embedded (i.e., `<img src="circle.svg" alt="circle" />`) as opposed to [inlined in HTML](/en-US/docs/Web/SVG/Tutorial/SVG_In_HTML_Introduction#basic_example). +SVGs must be used embedded (i.e., `<img src="circle.svg" alt="circle" />`) as opposed to [inlined in HTML](/en-US/docs/Web/SVG/Guides/SVG_in_HTML#basic_example). An example of using `prefers-color-scheme` in SVGs can be found in the ["Inherited color scheme in embedded elements"](#inherited_color_scheme_in_embedded_elements) section. Using `prefers-color-scheme` is allowed in [cross-origin](/en-US/docs/Web/Security/Same-origin_policy#cross-origin_network_access) `<svg>` and `<iframe>` elements. Cross-origin elements are elements retrieved from a different host than the page that is referencing them. -To learn more about SVGs, see the [SVG documentation](/en-US/docs/Web/SVG) and for more information about iframes, see the [iframe documentation](/en-US/docs/Web/HTML/Element/iframe). +To learn more about SVGs, see the [SVG documentation](/en-US/docs/Web/SVG) and for more information about iframes, see the [iframe documentation](/en-US/docs/Web/HTML/Reference/Elements/iframe). ## Syntax @@ -112,33 +112,40 @@ In this case, the parent element with a `color-scheme` CSS property is a `<div>` <div> <img /> </div> - -<div style="color-scheme: light"> +<div class="light"> <img /> </div> -<div style="color-scheme: dark"> +<div class="dark"> <img /> </div> +``` -<!-- Embed an SVG for all <img> elements --> -<script> - for (let img of document.querySelectorAll("img")) { - img.alt = "circle"; - img.src = - "data:image/svg+xml;base64," + - window.btoa(` - <svg width="32" height="32" viewBox="0 0 32 32" xmlns="http://www.w3.org/2000/svg"> - <style> - :root { color: blue } - @media (prefers-color-scheme: dark) { - :root { color: purple } - } - </style> - <circle fill="currentColor" cx="16" cy="16" r="16"/> - </svg> - `); - } -</script> +```css +.light { + color-scheme: light; +} + +.dark { + color-scheme: dark; +} +``` + +```js +// Embed an SVG for all <img> elements +for (let img of document.querySelectorAll("img")) { + img.alt = "circle"; + img.src = `data:image/svg+xml;base64,${window.btoa(` + <svg width="32" height="32" viewBox="0 0 32 32" xmlns="http://www.w3.org/2000/svg"> + <style> + :root { color: blue } + @media (prefers-color-scheme: dark) { + :root { color: purple } + } + </style> + <circle fill="currentColor" cx="16" cy="16" r="16"/> + </svg> + `)}`; +} ``` {{EmbedLiveSample("Color_scheme_inheritance")}} @@ -154,8 +161,8 @@ In this case, the parent element with a `color-scheme` CSS property is a `<div>` ## See also - {{cssxref("color-scheme")}} property -- [`<meta name="color-scheme">`](/en-US/docs/Web/HTML/Element/meta/name#color-scheme) -- {{HTTPHeader("Sec-CH-Prefers-Color-Scheme")}} HTTP Header [User Agent Client Hint](/en-US/docs/Web/HTTP/Client_hints#user-agent_client_hints) +- [`<meta name="color-scheme">`](/en-US/docs/Web/HTML/Reference/Elements/meta/name#color-scheme) +- {{HTTPHeader("Sec-CH-Prefers-Color-Scheme")}} HTTP Header [User Agent Client Hint](/en-US/docs/Web/HTTP/Guides/Client_hints#user_agent_client_hints) - [Simulate prefers-color-scheme in Firefox](https://firefox-source-docs.mozilla.org/devtools-user/page_inspector/how_to/examine_and_edit_css/index.html#view-media-rules-for-prefers-color-scheme) - [Video: Coding a Dark Mode for your Website](https://www.youtube.com/watch?v=jmepqJ5UbuM) - [Redesigning your product and website for dark mode](https://stuffandnonsense.co.uk/blog/redesigning-your-product-and-website-for-dark-mode) diff --git a/files/en-us/web/css/@media/prefers-reduced-motion/index.md b/files/en-us/web/css/@media/prefers-reduced-motion/index.md index e7231232dd0eeed..aa4fe57b334403c 100644 --- a/files/en-us/web/css/@media/prefers-reduced-motion/index.md +++ b/files/en-us/web/css/@media/prefers-reduced-motion/index.md @@ -15,7 +15,7 @@ The **`prefers-reduced-motion`** [CSS](/en-US/docs/Web/CSS) [media feature](/en- Such animations can trigger discomfort for those with [vestibular motion disorders](https://www.a11yproject.com/posts/understanding-vestibular-disorders/). Animations such as scaling or panning large objects can be vestibular motion triggers. ```css -@media (prefers-reduced-motion) { +@media (prefers-reduced-motion: reduce) { /* styles to apply if a user's device settings are set to reduced motion */ } ``` @@ -25,7 +25,7 @@ Such animations can trigger discomfort for those with [vestibular motion disorde - `no-preference` - : Indicates that a user has made no preference known on the device. This keyword value evaluates as false. - `reduce` - - : Indicates that a user has enabled the setting on their device for reduced motion. This keyword value evaluates as true. + - : Indicates that a user has enabled the setting on their device for reduced motion. The `reduce` keyword value evaluates as true; therefore, `@media (prefers-reduced-motion)` is equivalent to `@media (prefers-reduced-motion: reduce)`. ## User preferences @@ -65,7 +65,7 @@ This example uses a scaling animation for the purpose of demonstrating `prefers- } /* Tone down the animation to avoid vestibular motion triggers. */ -@media (prefers-reduced-motion) { +@media (prefers-reduced-motion: reduce) { .animation { animation: dissolve 4s linear infinite both; background-color: green; @@ -131,6 +131,6 @@ You can enable the setting for reducing motion on [your device](#user_preference ## See also -- {{HTTPHeader("Sec-CH-Prefers-Reduced-Motion")}} HTTP Header [User Agent Client Hint](/en-US/docs/Web/HTTP/Client_hints#user-agent_client_hints) +- {{HTTPHeader("Sec-CH-Prefers-Reduced-Motion")}} HTTP Header [User Agent Client Hint](/en-US/docs/Web/HTTP/Guides/Client_hints#user_agent_client_hints) - [An introduction to the reduced motion media query](https://css-tricks.com/introduction-reduced-motion-media-query/) on CSS-Tricks (2019) - [Responsive design for motion](https://webkit.org/blog/7551/responsive-design-for-motion/) on WebKit Blog (2017) diff --git a/files/en-us/web/css/@namespace/index.md b/files/en-us/web/css/@namespace/index.md index fab60845a220e68..7e3b6630880a2f0 100644 --- a/files/en-us/web/css/@namespace/index.md +++ b/files/en-us/web/css/@namespace/index.md @@ -61,7 +61,7 @@ Any `@namespace` rules must follow all {{cssxref("@charset")}} and {{cssxref("@i The `@namespace` rule can also be used to define a **namespace prefix**. When a universal, type, or attribute selector is prefixed with a namespace prefix, then that selector only matches if the namespace _and_ name of the element or attribute matches. -In HTML, known [foreign elements](https://html.spec.whatwg.org/multipage/syntax.html#foreign-elements) will automatically be assigned namespaces. This means that HTML elements will act as though they are in the XHTML namespace (`http://www.w3.org/1999/xhtml`), even if there is no `xmlns` attribute anywhere in the document, and the [`<svg>`](/en-US/docs/Web/SVG/Element/svg) and [`<math>`](/en-US/docs/Web/MathML/Element/math) elements will be assigned their proper namespaces (`http://www.w3.org/2000/svg` and `http://www.w3.org/1998/Math/MathML`, respectively). +In HTML, known [foreign elements](https://html.spec.whatwg.org/multipage/syntax.html#foreign-elements) will automatically be assigned namespaces. This means that HTML elements will act as though they are in the XHTML namespace (`http://www.w3.org/1999/xhtml`), even if there is no `xmlns` attribute anywhere in the document, and the [`<svg>`](/en-US/docs/Web/SVG/Reference/Element/svg) and [`<math>`](/en-US/docs/Web/MathML/Reference/Element/math) elements will be assigned their proper namespaces (`http://www.w3.org/2000/svg` and `http://www.w3.org/1998/Math/MathML`, respectively). > [!NOTE] > In XML, unless a prefix is defined directly on an attribute (_e.g._, `xlink:href`), that attribute has no namespace. In other words, attributes do not inherit the namespace of the element they're on. To match this behavior, the default namespace in CSS does not apply to attribute selectors. @@ -101,5 +101,5 @@ svg|a { ## See also -- [Namespaces crash course](/en-US/docs/Web/SVG/Namespaces_Crash_Course) +- [Namespaces crash course](/en-US/docs/Web/SVG/Guides/Namespaces_crash_course) - [CSS at-rule functions](/en-US/docs/Web/CSS/CSS_syntax/At-rule_functions) diff --git a/files/en-us/web/css/@page/size/index.md b/files/en-us/web/css/@page/size/index.md index 0c5e3b1df85e112..04358ad0637f61f 100644 --- a/files/en-us/web/css/@page/size/index.md +++ b/files/en-us/web/css/@page/size/index.md @@ -41,9 +41,9 @@ size: A4 portrait; - `auto` - : The user agent decides the size of the page. In most cases, the dimensions and orientation of the target sheet are used. - `landscape` - - : The content of the page is displayed in landscape mode (i.e. the longest side of the box is horizontal). + - : The content of the page is displayed in landscape mode (i.e., the longest side of the box is horizontal). - `portrait` - - : The content of the page is displayed in portrait mode (i.e. the longest side of the box is vertical). This is the default orientation. + - : The content of the page is displayed in portrait mode (i.e., the longest side of the box is vertical). This is the default orientation. - `<length>` - : Any length value (see {{cssxref("&lt;length&gt;")}}). The first value corresponds to the width of the page box and the second one corresponds to its height. If only one value is provided, it is used for both width and height. - `<page-size>` @@ -65,11 +65,11 @@ size: A4 portrait; - JIS-B4 - : This correspond to the JIS standard dimensions: 257mm x 364mm. - letter - - : This keyword is an equivalent to the dimensions of letter paper in North America i.e. 8.5in x 11in. + - : This keyword is an equivalent to the dimensions of letter paper in North America i.e., 8.5in x 11in. - legal - - : This keyword is an equivalent to the dimensions of legal papers in North America i.e. 8.5in x 14in. + - : This keyword is an equivalent to the dimensions of legal papers in North America i.e., 8.5in x 14in. - ledger - - : This keyword is an equivalent to the dimensions of ledger pages in North America i.e. 11in x 17in. + - : This keyword is an equivalent to the dimensions of ledger pages in North America i.e., 11in x 17in. ## Formal definition diff --git a/files/en-us/web/css/@property/index.md b/files/en-us/web/css/@property/index.md index 669690ac2d80ad9..257bc3ae673fd48 100644 --- a/files/en-us/web/css/@property/index.md +++ b/files/en-us/web/css/@property/index.md @@ -42,6 +42,9 @@ The following conditions must be met for the `@property` rule to be valid: If either is missing, the entire `@property` rule is invalid and ignored. - The {{cssxref("@property/initial-value","initial-value")}} descriptor is optional if the value of the `syntax` descriptor is the universal syntax definition (that is, `syntax: "*"`). If the `initial-value` descriptor is required but omitted, the entire `@property` rule is invalid and ignored. +- If the value of the `syntax` descriptor is not the universal syntax definition, the {{cssxref("@property/initial-value","initial-value")}} descriptor has to be a [computationally independent](https://drafts.css-houdini.org/css-properties-values-api-1/#computationally-independent) value. + This means the value can be converted into a computed value without depending on other values, except for "global" definitions independent of CSS. + For example, `10px` is computationally independent—it doesn't change when converted to a computed value. `2in` is also valid, because `1in` is always equivalent to `96px`. However, `3em` is not valid, because the value of an `em` is dependent on the parent's {{cssxref("font-size")}}. - Unknown descriptors are invalid and ignored, but do not invalidate the `@property` rule. ## Formal syntax diff --git a/files/en-us/web/css/@property/syntax/index.md b/files/en-us/web/css/@property/syntax/index.md index 0a69d84bb22a354..85663dd67b6f31e 100644 --- a/files/en-us/web/css/@property/syntax/index.md +++ b/files/en-us/web/css/@property/syntax/index.md @@ -8,7 +8,7 @@ browser-compat: css.at-rules.property.syntax {{CSSRef}} The **`syntax`** descriptor of the {{cssxref("@property")}} [at-rule](/en-US/docs/Web/CSS/CSS_syntax/At-rule) defines the allowed value types for the registered [CSS custom property](/en-US/docs/Web/CSS/--*). -It controls how the property's specified value is processed to derive the {{cssxref("computed_value","computed value")}}. +It controls how the property's specified value is processed to derive the [computed value](/en-US/docs/Web/CSS/CSS_cascade/Value_processing#computed_value). It is a required descriptor; if missing or invalid, the entire `@property` rule is invalid and ignored. ## Syntax diff --git a/files/en-us/web/css/@scope/index.md b/files/en-us/web/css/@scope/index.md index 2d4e1ba67b2119a..cf6c5518707eae4 100644 --- a/files/en-us/web/css/@scope/index.md +++ b/files/en-us/web/css/@scope/index.md @@ -19,7 +19,7 @@ The `@scope` at-rule contains one or more rulesets (termed **scoped style rules* ```css @scope (scope root) to (scope limit) { - rulesets + /* … */ } ``` @@ -41,7 +41,7 @@ The `@scope` at-rule contains one or more rulesets (termed **scoped style rules* A complex web document might include components such as headers, footers, news articles, maps, media players, ads, and others. As complexity increases, effectively managing the styling for these components becomes more of a concern, and effective scoping of styles helps us manage this complexity. Let's consider the following DOM tree: -```plain-nolint +```plain body └─ article.feature ├─ section.article-hero @@ -136,11 +136,17 @@ The three rules in the following block are all equivalent in what they select: ```css @scope (.feature) { - img { ... } + img { + /* … */ + } - :scope img { ... } + :scope img { + /* … */ + } - & img { ... } + & img { + /* … */ + } } ``` @@ -150,14 +156,18 @@ The three rules in the following block are all equivalent in what they select: ```css /* figure is only a limit when it is a direct child of the :scope */ - @scope (.article-body) to (:scope > figure) { ... } + @scope (.article-body) to (:scope > figure) { + /* … */ + } ``` - A scope limit can reference elements outside the scope root using `:scope`. For example: ```css /* figure is only a limit when the :scope is inside .feature */ - @scope (.article-body) to (.feature :scope figure) { ... } + @scope (.article-body) to (.feature :scope figure) { + /* … */ + } ``` - Scoped style rules can't escape the subtree. Selections like `:scope + p` are invalid because that selection would be outside the subtree. @@ -180,7 +190,9 @@ Including a ruleset inside a `@scope` block does not affect the specificity of i ```css @scope (.article-body) { /* img has a specificity of 0-0-1, as expected */ - img { ... } + img { + /* … */ + } } ``` @@ -189,7 +201,9 @@ However, if you decide to explicitly prepend the `:scope` pseudo-class to your s ```css @scope (.article-body) { /* :scope img has a specificity of 0-1-0 + 0-0-1 = 0-1-1 */ - :scope img { ... } + :scope img { + /* … */ + } } ``` @@ -197,7 +211,9 @@ When using the `&` selector inside a `@scope` block, `&` represents the scope ro ```css @scope (figure, #primary) { - & img { ... } + & img { + /* … */ + } } ``` @@ -210,10 +226,14 @@ When using the `&` selector inside a `@scope` block, `&` represents the scope ro ```css @scope (.feature) { /* Selects a .feature inside the matched root .feature */ - & & { ... } + & & { + /* … */ + } /* Doesn't work */ - :scope :scope { ... } + :scope :scope { + /* … */ + } } ``` diff --git a/files/en-us/web/css/@starting-style/index.md b/files/en-us/web/css/@starting-style/index.md index 30e3631fab899a0..5582f5a715e02c9 100644 --- a/files/en-us/web/css/@starting-style/index.md +++ b/files/en-us/web/css/@starting-style/index.md @@ -7,7 +7,7 @@ browser-compat: css.at-rules.starting-style {{CSSRef}} -The **`@starting-style`** [CSS](/en-US/docs/Web/CSS) [at-rule](/en-US/docs/Web/CSS/CSS_syntax/At-rule) is used to define starting values for properties set on an element that you want to transition from when the element receives its first style update, i.e. when an element is first displayed on a previously loaded page. +The **`@starting-style`** [CSS](/en-US/docs/Web/CSS) [at-rule](/en-US/docs/Web/CSS/CSS_syntax/At-rule) is used to define starting values for properties set on an element that you want to transition from when the element receives its first style update, i.e., when an element is first displayed on a previously loaded page. ## Syntax @@ -17,18 +17,19 @@ The `@starting-style` at rule can be used in two ways: ```css @starting-style { - rulesets + /* rulesets */ } ``` 2. Nested within an existing ruleset, in which case it contains one or more declarations defining starting property values for the elements already selected by that ruleset: ```css - selector { /* existing ruleset */ + selector { + /* existing ruleset */ /* ... */ @starting-style { - declarations + /* declarations */ } } ``` @@ -88,7 +89,7 @@ In effect, there are three style states to manage in these situations — starti ## Formal syntax -{{csssyntax}} +{{CSSSyntaxRaw(`@starting-style = @starting-style { <rule-list> }`)}} ## Examples @@ -213,7 +214,7 @@ In this example, a [popover](/en-US/docs/Web/API/Popover_API) is animated using #### HTML -The HTML contains a {{htmlelement("div")}} element declared as a popover using the [popover](/en-US/docs/Web/HTML/Global_attributes/popover) attribute and a {{htmlelement("button")}} element designated as the popover's display control using its [popovertarget](/en-US/docs/Web/HTML/Element/button#popovertarget) attribute. +The HTML contains a {{htmlelement("div")}} element declared as a popover using the [popover](/en-US/docs/Web/HTML/Reference/Global_attributes/popover) attribute and a {{htmlelement("button")}} element designated as the popover's display control using its [popovertarget](/en-US/docs/Web/HTML/Reference/Elements/button#popovertarget) attribute. ```html <button popovertarget="mypopover">Show the popover</button> @@ -305,7 +306,7 @@ The code renders as follows: > Because popovers change from `display: none` to `display: block` each time they are shown, the popover transitions from its `@starting-style` styles to its `[popover]:popover-open` styles every time the entry transition occurs. When the popover closes, it transitions from its `[popover]:popover-open` state to the default `[popover]` state. > [!NOTE] -> You can find an example that demonstrates transitioning a {{htmlelement("dialog")}} element and its backdrop as it is shown and hidden on the `<dialog>` reference page — see [Transitioning dialog elements](/en-US/docs/Web/HTML/Element/dialog#transitioning_dialog_elements). +> You can find an example that demonstrates transitioning a {{htmlelement("dialog")}} element and its backdrop as it is shown and hidden on the `<dialog>` reference page — see [Transitioning dialog elements](/en-US/docs/Web/HTML/Reference/Elements/dialog#transitioning_dialog_elements). ### Transitioning elements on DOM addition and removal diff --git a/files/en-us/web/css/@supports/index.md b/files/en-us/web/css/@supports/index.md index 9f45f326cc4f375..ea6adf25cabd066 100644 --- a/files/en-us/web/css/@supports/index.md +++ b/files/en-us/web/css/@supports/index.md @@ -200,9 +200,16 @@ The `or` operator creates a new expression from the disjunction of two shorter e Multiple disjunctions can be juxtaposed without the need of more parentheses. The following are both equivalent: ```css -@supports (transform-style: preserve) or (-moz-transform-style: preserve) or (-webkit-transform-style: preserve) {} +@supports (transform-style: preserve) or (-moz-transform-style: preserve) or + (-webkit-transform-style: preserve) { +} -@supports (transform-style: preserve-3d) or ((-moz-transform-style: preserve-3d) or (-webkit-transform-style: preserve-3d))) {} +@supports (transform-style: preserve-3d) or + ( + (-moz-transform-style: preserve-3d) or + (-webkit-transform-style: preserve-3d) + ) { +} ``` > [!NOTE] diff --git a/files/en-us/web/css/@view-transition/index.md b/files/en-us/web/css/@view-transition/index.md index 590fbf5fbd9d0bc..349db3a31d52d45 100644 --- a/files/en-us/web/css/@view-transition/index.md +++ b/files/en-us/web/css/@view-transition/index.md @@ -96,10 +96,10 @@ See this [transitions multi-page app](https://mdn.github.io/dom-examples/view-tr ## See also - {{cssxref("::view-transition", "::view-transition")}} -- {{cssxref("::view-transition-new", "::view-transition-new()")}} -- {{cssxref("::view-transition-old", "::view-transition-old()")}} -- {{cssxref("::view-transition-group", "::view-transition-group()")}} -- {{cssxref("::view-transition-image-pair", "::view-transition-image-pair()")}} +- {{cssxref("::view-transition-new()")}} +- {{cssxref("::view-transition-old()")}} +- {{cssxref("::view-transition-group()")}} +- {{cssxref("::view-transition-image-pair()")}} - [View Transition API](/en-US/docs/Web/API/View_Transition_API) - [CSS at-rules](/en-US/docs/Web/CSS/CSS_syntax/At-rule) - [CSS at-rule functions](/en-US/docs/Web/CSS/CSS_syntax/At-rule_functions) diff --git a/files/en-us/web/css/_colon_-moz-loading/index.md b/files/en-us/web/css/_colon_-moz-loading/index.md index 82ed0d1dff56bd8..fedb2bbd0a57496 100644 --- a/files/en-us/web/css/_colon_-moz-loading/index.md +++ b/files/en-us/web/css/_colon_-moz-loading/index.md @@ -27,8 +27,7 @@ The **`:-moz-loading`** [CSS](/en-US/docs/Web/CSS) [pseudo-class](/en-US/docs/We ```css :-moz-loading { - background-color: #aaa; - background-image: url(loading-animation.gif) center no-repeat; + background: url(loading-animation.gif) center no-repeat; } ``` diff --git a/files/en-us/web/css/_colon_-moz-submit-invalid/index.md b/files/en-us/web/css/_colon_-moz-submit-invalid/index.md index d4c646c7f89c884..8305c3096125e67 100644 --- a/files/en-us/web/css/_colon_-moz-submit-invalid/index.md +++ b/files/en-us/web/css/_colon_-moz-submit-invalid/index.md @@ -9,7 +9,7 @@ browser-compat: css.selectors.-moz-submit-invalid {{CSSRef}}{{Non-standard_Header}} -The **`:-moz-submit-invalid`** CSS [pseudo-class](/en-US/docs/Web/CSS/Pseudo-classes) is a [Mozilla extension](/en-US/docs/Web/CSS/Mozilla_Extensions) that represents any submit {{HTMLElement("button")}} on forms whose contents aren't valid based on their [validation constraints](/en-US/docs/Web/HTML/Constraint_validation). +The **`:-moz-submit-invalid`** CSS [pseudo-class](/en-US/docs/Web/CSS/Pseudo-classes) is a [Mozilla extension](/en-US/docs/Web/CSS/Mozilla_Extensions) that represents any submit {{HTMLElement("button")}} on forms whose contents aren't valid based on their [validation constraints](/en-US/docs/Web/HTML/Guides/Constraint_validation). By default, no style is applied. You can use this pseudo-class to customize the appearance of the submit button when there are invalid form fields. diff --git a/files/en-us/web/css/_colon_any-link/index.md b/files/en-us/web/css/_colon_any-link/index.md index 12f6b9af7107e95..42cf73b343a62f5 100644 --- a/files/en-us/web/css/_colon_any-link/index.md +++ b/files/en-us/web/css/_colon_any-link/index.md @@ -91,7 +91,7 @@ a:-webkit-any-link { ## See also - [Creating links](/en-US/docs/Learn_web_development/Core/Structuring_content/Creating_links) -- Matches HTML elements: [`<a>`](/en-US/docs/Web/HTML/Element/a) and [`<area>`](/en-US/docs/Web/HTML/Element/area) with an [`href`](/en-US/docs/Web/HTML/Element/a#href) attribute +- Matches HTML elements: [`<a>`](/en-US/docs/Web/HTML/Reference/Elements/a) and [`<area>`](/en-US/docs/Web/HTML/Reference/Elements/area) with an [`href`](/en-US/docs/Web/HTML/Reference/Elements/a#href) attribute - Related CSS selectors: - [`:visited`](/en-US/docs/Web/CSS/:visited) diff --git a/files/en-us/web/css/_colon_blank/index.md b/files/en-us/web/css/_colon_blank/index.md index 805ccfd419ce1a5..a4f1ad5b43ac2c5 100644 --- a/files/en-us/web/css/_colon_blank/index.md +++ b/files/en-us/web/css/_colon_blank/index.md @@ -14,7 +14,7 @@ spec-urls: https://drafts.csswg.org/selectors/#blank-pseudo > > See [CSSWG issue #1967](https://github.com/w3c/csswg-drafts/issues/1967). -The **`:blank`** [CSS](/en-US/docs/Web/CSS) [pseudo-class](/en-US/docs/Web/CSS/Pseudo-classes) selects empty user input elements (e.g. {{HTMLElement("input")}} or {{HTMLElement("textarea")}}). +The **`:blank`** [CSS](/en-US/docs/Web/CSS) [pseudo-class](/en-US/docs/Web/CSS/Pseudo-classes) selects empty user input elements (e.g., {{HTMLElement("input")}} or {{HTMLElement("textarea")}}). ## Syntax diff --git a/files/en-us/web/css/_colon_checked/index.md b/files/en-us/web/css/_colon_checked/index.md index 790613512822d40..4dbc7f7fd07299c 100644 --- a/files/en-us/web/css/_colon_checked/index.md +++ b/files/en-us/web/css/_colon_checked/index.md @@ -7,7 +7,7 @@ browser-compat: css.selectors.checked {{CSSRef}} -The **`:checked`** [CSS](/en-US/docs/Web/CSS) [pseudo-class](/en-US/docs/Web/CSS/Pseudo-classes) selector represents any **radio** ([`<input type="radio">`](/en-US/docs/Web/HTML/Element/input/radio)), **checkbox** ([`<input type="checkbox">`](/en-US/docs/Web/HTML/Element/input/checkbox)), or **option** ({{HTMLElement("option")}} in a {{HTMLElement("select")}}) element that is checked or toggled to an `on` state. +The **`:checked`** [CSS](/en-US/docs/Web/CSS) [pseudo-class](/en-US/docs/Web/CSS/Pseudo-classes) selector represents any **radio** ([`<input type="radio">`](/en-US/docs/Web/HTML/Reference/Elements/input/radio)), **checkbox** ([`<input type="checkbox">`](/en-US/docs/Web/HTML/Reference/Elements/input/checkbox)), or **option** ({{HTMLElement("option")}} in a {{HTMLElement("select")}} element) that is checked or toggled to an `on` state. {{InteractiveExample("CSS Demo: :checked", "tabbed-shorter")}} @@ -50,7 +50,7 @@ input:checked { The user can engage this state by checking/selecting an element, or disengage it by unchecking/deselecting the element. > [!NOTE] -> Because browsers often treat `<option>`s as [replaced elements](/en-US/docs/Web/CSS/Replaced_element), the extent to which they can be styled with the `:checked` pseudo-class varies from browser to browser. +> Because browsers often treat `<option>`s as {{ glossary("replaced elements")}}, the extent to which they can be styled with the `:checked` pseudo-class varies from browser to browser. [Customizable select element](/en-US/docs/Learn_web_development/Extensions/Forms/Customizable_select) functionality can be used to enable full customization of `<option>` elements just like any regular DOM element, in supporting browsers. ## Syntax @@ -221,5 +221,5 @@ This example utilizes the `:checked` pseudo-class to let the user toggle content - [Web forms — working with user data](/en-US/docs/Learn_web_development/Extensions/Forms) - [Styling web forms](/en-US/docs/Learn_web_development/Extensions/Forms/Styling_web_forms) -- Related HTML elements: [`<input type="checkbox">`](/en-US/docs/Web/HTML/Element/input/checkbox), [`<input type="radio">`](/en-US/docs/Web/HTML/Element/input/radio), {{HTMLElement("select")}}, and {{HTMLElement("option")}} -- [Replaced elements](/en-US/docs/Web/CSS/Replaced_element) +- Related HTML elements: [`<input type="checkbox">`](/en-US/docs/Web/HTML/Reference/Elements/input/checkbox), [`<input type="radio">`](/en-US/docs/Web/HTML/Reference/Elements/input/radio), {{HTMLElement("select")}}, and {{HTMLElement("option")}} +- {{glossary("Replaced elements")}} diff --git a/files/en-us/web/css/_colon_default/index.md b/files/en-us/web/css/_colon_default/index.md index 2cc48d107fab056..3b2d30c64ef59fc 100644 --- a/files/en-us/web/css/_colon_default/index.md +++ b/files/en-us/web/css/_colon_default/index.md @@ -47,7 +47,7 @@ input:default { </form> ``` -What this selector matches is defined in [HTML Standard §4.16.3 Pseudo-classes](https://html.spec.whatwg.org/multipage/semantics-other.html#selector-default) — it may match the {{htmlelement("button")}}, [`<input type="checkbox">`](/en-US/docs/Web/HTML/Element/input/checkbox), [`<input type="radio">`](/en-US/docs/Web/HTML/Element/input/radio), and {{htmlelement("option")}} elements: +What this selector matches is defined in [HTML Standard §4.16.3 Pseudo-classes](https://html.spec.whatwg.org/multipage/semantics-other.html#selector-default) — it may match the {{htmlelement("button")}}, [`<input type="checkbox">`](/en-US/docs/Web/HTML/Reference/Elements/input/checkbox), [`<input type="radio">`](/en-US/docs/Web/HTML/Reference/Elements/input/radio), and {{htmlelement("option")}} elements: - A default option element is the first one with the `selected` attribute, or the first enabled option in DOM order. `multiple` {{htmlelement("select")}}s can have more than one `selected` option, so all will match `:default`. - `<input type="checkbox">` and `<input type="radio">` match if they have the `checked` attribute. @@ -111,4 +111,4 @@ input:default + label { - [Web forms — Working with user data](/en-US/docs/Learn_web_development/Extensions/Forms) - [Styling web forms](/en-US/docs/Learn_web_development/Extensions/Forms/Styling_web_forms) -- Related HTML elements: {{htmlelement("button")}}, [`<input type="checkbox">`](/en-US/docs/Web/HTML/Element/input/checkbox), [`<input type="radio">`](/en-US/docs/Web/HTML/Element/input/radio), and {{htmlelement("option")}} +- Related HTML elements: {{htmlelement("button")}}, [`<input type="checkbox">`](/en-US/docs/Web/HTML/Reference/Elements/input/checkbox), [`<input type="radio">`](/en-US/docs/Web/HTML/Reference/Elements/input/radio), and {{htmlelement("option")}} diff --git a/files/en-us/web/css/_colon_defined/index.md b/files/en-us/web/css/_colon_defined/index.md index 514bbca6445f2c2..c838978f5bad860 100644 --- a/files/en-us/web/css/_colon_defined/index.md +++ b/files/en-us/web/css/_colon_defined/index.md @@ -7,7 +7,7 @@ browser-compat: css.selectors.defined {{CSSRef}} -The **`:defined`** [CSS](/en-US/docs/Web/CSS) [pseudo-class](/en-US/docs/Web/CSS/Pseudo-classes) represents any element that has been defined. This includes any standard element built into the browser and custom elements that have been successfully defined (i.e. with the {{domxref("CustomElementRegistry.define()")}} method). +The **`:defined`** [CSS](/en-US/docs/Web/CSS) [pseudo-class](/en-US/docs/Web/CSS/Pseudo-classes) represents any element that has been defined. This includes any standard element built into the browser and custom elements that have been successfully defined (i.e., with the {{domxref("CustomElementRegistry.define()")}} method). ```css /* Selects any defined element */ diff --git a/files/en-us/web/css/_colon_dir/index.md b/files/en-us/web/css/_colon_dir/index.md index 0c78c223d2e290a..f72500c7a67d014 100644 --- a/files/en-us/web/css/_colon_dir/index.md +++ b/files/en-us/web/css/_colon_dir/index.md @@ -19,10 +19,10 @@ The **`:dir()`** [CSS](/en-US/docs/Web/CSS) [pseudo-class](/en-US/docs/Web/CSS/P The `:dir()` pseudo-class uses only the _semantic_ value of the directionality, i.e., the one defined in the document itself. It doesn't account for _styling_ directionality, i.e., the directionality set by CSS properties such as {{cssxref("direction")}}. > [!NOTE] -> Be aware that the behavior of the `:dir()` pseudo-class is not equivalent to the `[dir=…]` [attribute selectors](/en-US/docs/Web/CSS/Attribute_selectors). The latter match the HTML [`dir`](/en-US/docs/Web/HTML/Global_attributes/dir) attribute, and ignore elements that lack it — even if they inherit a direction from their parent. (Similarly, `[dir=rtl]` and `[dir=ltr]` won't match the `auto` value.) In contrast, `:dir()` will match the value calculated by the {{glossary("user agent")}}, even if inherited. +> Be aware that the behavior of the `:dir()` pseudo-class is not equivalent to the `[dir=…]` [attribute selectors](/en-US/docs/Web/CSS/Attribute_selectors). The latter match the HTML [`dir`](/en-US/docs/Web/HTML/Reference/Global_attributes/dir) attribute, and ignore elements that lack it — even if they inherit a direction from their parent. (Similarly, `[dir=rtl]` and `[dir=ltr]` won't match the `auto` value.) In contrast, `:dir()` will match the value calculated by the {{glossary("user agent")}}, even if inherited. > [!NOTE] -> In HTML, the direction is determined by the [`dir`](/en-US/docs/Web/HTML/Global_attributes/dir) attribute. Other document types may have different methods. +> In HTML, the direction is determined by the [`dir`](/en-US/docs/Web/HTML/Reference/Global_attributes/dir) attribute. Other document types may have different methods. ## Syntax @@ -82,5 +82,5 @@ The `:dir()` pseudo-class requires one parameter, representing the text directio ## See also - Language-related pseudo-classes: {{cssxref(":lang")}} -- HTML [`lang`](/en-US/docs/Web/HTML/Global_attributes/lang) attribute -- HTML [`translate`](/en-US/docs/Web/HTML/Global_attributes/translate) attribute +- HTML [`lang`](/en-US/docs/Web/HTML/Reference/Global_attributes/lang) attribute +- HTML [`translate`](/en-US/docs/Web/HTML/Reference/Global_attributes/translate) attribute diff --git a/files/en-us/web/css/_colon_empty/index.md b/files/en-us/web/css/_colon_empty/index.md index c444617476dc096..20126ceb9bc55bc 100644 --- a/files/en-us/web/css/_colon_empty/index.md +++ b/files/en-us/web/css/_colon_empty/index.md @@ -23,7 +23,7 @@ div:empty { <div></div> <p>Element with comment:</p> -<div><!-- Simple Comment --></div> +<div><!-- A comment --></div> <p>Element with nested empty element:</p> <div><p></p></div> @@ -42,13 +42,13 @@ div:empty { ## Accessibility -Assistive technology such as screen readers cannot parse interactive content that is empty. All interactive content must have an accessible name, which is created by providing a text value for the interactive control's parent element ([anchors](/en-US/docs/Web/HTML/Element/a), [buttons](/en-US/docs/Web/HTML/Element/button), etc.). Accessible names expose the interactive control to the [accessibility tree](/en-US/docs/Learn_web_development/Core/Accessibility/What_is_accessibility#accessibility_apis), an API that communicates information useful for assistive technologies. +Assistive technology such as screen readers cannot parse interactive content that is empty. All interactive content must have an accessible name, which is created by providing a text value for the interactive control's parent element ([anchors](/en-US/docs/Web/HTML/Reference/Elements/a), [buttons](/en-US/docs/Web/HTML/Reference/Elements/button), etc.). Accessible names expose the interactive control to the [accessibility tree](/en-US/docs/Learn_web_development/Core/Accessibility/What_is_accessibility#accessibility_apis), an API that communicates information useful for assistive technologies. The text that provides the interactive control's accessible name can be hidden using [a combination of properties](https://gomakethings.com/hidden-content-for-better-a11y/#hiding-the-link) that remove it visually from the screen but keep it parsable by assistive technology. This is commonly used for buttons that rely solely on an icon to convey purpose. - [What is an accessible name? | The Paciello Group](https://www.tpgi.com/what-is-an-accessible-name/) - [Hidden content for better a11y | Go Make Things](https://gomakethings.com/hidden-content-for-better-a11y/) -- [MDN Understanding WCAG, Guideline 2.4 explanations](/en-US/docs/Web/Accessibility/Understanding_WCAG/Operable#guideline_2.4_%e2%80%94_navigable_provide_ways_to_help_users_navigate_find_content_and_determine_where_they_are) +- [MDN Understanding WCAG, Guideline 2.4 explanations](/en-US/docs/Web/Accessibility/Guides/Understanding_WCAG/Operable#guideline_2.4_%e2%80%94_navigable_provide_ways_to_help_users_navigate_find_content_and_determine_where_they_are) - [Understanding Success Criterion 2.4.4 | W3C Understanding WCAG 2.0](https://www.w3.org/TR/UNDERSTANDING-WCAG20/navigation-mechanisms-refs.html) ## Examples diff --git a/files/en-us/web/css/_colon_enabled/index.md b/files/en-us/web/css/_colon_enabled/index.md index 9631cba1799465c..f7b62ca45b7c562 100644 --- a/files/en-us/web/css/_colon_enabled/index.md +++ b/files/en-us/web/css/_colon_enabled/index.md @@ -43,8 +43,10 @@ label { ## Syntax -```plain -:enabled +```css +:enabled { + /* ... */ +} ``` ## Examples diff --git a/files/en-us/web/css/_colon_first-of-type/index.md b/files/en-us/web/css/_colon_first-of-type/index.md index b2c19aff3ad969d..200edb79b8a70fd 100644 --- a/files/en-us/web/css/_colon_first-of-type/index.md +++ b/files/en-us/web/css/_colon_first-of-type/index.md @@ -7,7 +7,7 @@ browser-compat: css.selectors.first-of-type {{CSSRef}} -The **`:first-of-type`** [CSS](/en-US/docs/Web/CSS) [pseudo-class](/en-US/docs/Web/CSS/Pseudo-classes) represents the first element of its type among a group of sibling elements. +The **`:first-of-type`** [CSS](/en-US/docs/Web/CSS) [pseudo-class](/en-US/docs/Web/CSS/Pseudo-classes) represents the first element of its type (tag name) among a group of sibling elements. {{InteractiveExample("CSS Demo: :first-of-type", "tabbed-shorter")}} diff --git a/files/en-us/web/css/_colon_focus-visible/index.md b/files/en-us/web/css/_colon_focus-visible/index.md index 9e24d9222be972e..6b3c3050f2cfc37 100644 --- a/files/en-us/web/css/_colon_focus-visible/index.md +++ b/files/en-us/web/css/_colon_focus-visible/index.md @@ -81,7 +81,7 @@ It may not be obvious as to why the focus indicator is appearing and disappearin ### Comparing :focus and :focus-visible -This example presents three pairs of controls. Each pair consists of a [`text`](/en-US/docs/Web/HTML/Element/input/text) input and a button. +This example presents three pairs of controls. Each pair consists of a [`text`](/en-US/docs/Web/HTML/Reference/Elements/input/text) input and a button. - The first pair does not add any custom styles for focus states, and shows the default case. - The second pair adds styles using the `:focus` pseudo-class. @@ -168,4 +168,3 @@ If your code has to work in old browser versions that do not support `:focus-vis - {{CSSxRef(":focus")}} - {{CSSxRef(":focus-within")}} -- [A polyfill for `:focus-visible`](https://github.com/WICG/focus-visible) diff --git a/files/en-us/web/css/_colon_fullscreen/index.md b/files/en-us/web/css/_colon_fullscreen/index.md index 5729086bc7b622a..2825f3f939814cb 100644 --- a/files/en-us/web/css/_colon_fullscreen/index.md +++ b/files/en-us/web/css/_colon_fullscreen/index.md @@ -23,13 +23,13 @@ The `:fullscreen` pseudo-class lets you configure your stylesheets to automatica ## Examples -### Styling a Fullscreen Element +### Styling a fullscreen element This example applies a different background color to a {{htmlelement("div")}} element, depending on whether or not it is in fullscreen mode. It includes a {{htmlelement("button")}} to toggle fullscreen on and off. ```html <div class="element"> - <h1>MDN :fullscreen pseudo-class demo</h1> + <h1><code>:fullscreen</code> pseudo-class demo</h1> <p> This demo uses the <code>:fullscreen</code> pseudo-class to automatically @@ -60,7 +60,7 @@ The `:fullscreen` pseudo-class is used to override the [`background-color`](/en- The following JavaScript provides an event handler function that toggles fullscreen when the `<button>` is clicked. ```js -document.querySelector(".toggle").addEventListener("click", function (event) { +document.querySelector(".toggle").addEventListener("click", (event) => { if (document.fullscreenElement) { // If there is a fullscreen element, exit full screen. document.exitFullscreen(); @@ -71,9 +71,18 @@ document.querySelector(".toggle").addEventListener("click", function (event) { }); ``` -#### Demo +```css hidden +.element { + display: flex; + flex-direction: column; + align-items: center; + justify-content: center; + font-family: sans-serif; + padding: 1.2em; +} +``` -[See the example live](https://jsfiddle.net/yookoala/oLc1uws0/). +{{EmbedLiveSample("Styling a fullscreen element", "", "300", "", "", "", "fullscreen")}} ## Specifications @@ -89,4 +98,4 @@ document.querySelector(".toggle").addEventListener("click", function (event) { - [Guide to the Fullscreen API](/en-US/docs/Web/API/Fullscreen_API/Guide) - {{cssxref("::backdrop")}} - DOM API: {{ domxref("Element.requestFullscreen()") }}, {{ domxref("Document.exitFullscreen()") }}, {{ domxref("Document.fullscreenElement") }} -- [`allowfullscreen`](/en-US/docs/Web/HTML/Element/iframe#allowfullscreen) attribute +- [`allowfullscreen`](/en-US/docs/Web/HTML/Reference/Elements/iframe#allowfullscreen) attribute diff --git a/files/en-us/web/css/_colon_has-slotted/index.md b/files/en-us/web/css/_colon_has-slotted/index.md index 1afa3c2aadcbb4c..73db52fa10c6312 100644 --- a/files/en-us/web/css/_colon_has-slotted/index.md +++ b/files/en-us/web/css/_colon_has-slotted/index.md @@ -9,7 +9,8 @@ browser-compat: css.selectors.has-slotted The **`:has-slotted`** [CSS](/en-US/docs/Web/CSS) [pseudo-class](/en-US/docs/Web/CSS/Pseudo-classes) matches when the content of a {{HTMLElement("slot")}} element is not empty or not using the default value (see [Using templates and slots](/en-US/docs/Web/API/Web_components/Using_templates_and_slots) for more information). -> [!NOTE] Even a single whitespace text node is sufficient to make `:has-slotted` apply. +> [!NOTE] +> Even a single whitespace text node is sufficient to make `:has-slotted` apply. This only works when used inside CSS placed within a [shadow DOM](/en-US/docs/Web/API/Web_components/Using_shadow_DOM). diff --git a/files/en-us/web/css/_colon_has/index.md b/files/en-us/web/css/_colon_has/index.md index 66308878e2cb0e4..8c3aa6f9e81b152 100644 --- a/files/en-us/web/css/_colon_has/index.md +++ b/files/en-us/web/css/_colon_has/index.md @@ -30,9 +30,9 @@ The `:has()` pseudo-class takes on the [specificity](/en-US/docs/Web/CSS/CSS_cas If the `:has()` pseudo-class itself is not supported in a browser, the entire selector block will fail unless `:has()` is in a forgiving selector list, such as in [`:is()`](/en-US/docs/Web/CSS/:is) and [`:where()`](/en-US/docs/Web/CSS/:where). -The `:has()` pseudo-class cannot be nested within another `:has()`. This is because many pseudo-elements exist conditionally based on the styling of their ancestors and allowing these to be queried by `:has()` can introduce cyclic querying. +The `:has()` pseudo-class cannot be nested within another `:has()`. -Pseudo-elements are also not valid selectors within `:has()` and pseudo-elements are not valid anchors for `:has()`. +Pseudo-elements are also not valid selectors within `:has()` and pseudo-elements are not valid anchors for `:has()`. This is because many pseudo-elements exist conditionally based on the styling of their ancestors and allowing these to be queried by `:has()` can introduce cyclic querying. ## Examples diff --git a/files/en-us/web/css/_colon_in-range/index.md b/files/en-us/web/css/_colon_in-range/index.md index 0bddf9affa17277..d6aadc28bcb3969 100644 --- a/files/en-us/web/css/_colon_in-range/index.md +++ b/files/en-us/web/css/_colon_in-range/index.md @@ -7,7 +7,7 @@ browser-compat: css.selectors.in-range {{CSSRef}} -The **`:in-range`** [CSS](/en-US/docs/Web/CSS) [pseudo-class](/en-US/docs/Web/CSS/Pseudo-classes) represents an {{htmlelement("input")}} element whose current value is within the range limits specified by the [`min`](/en-US/docs/Web/HTML/Element/input#min) and [`max`](/en-US/docs/Web/HTML/Element/input#max) attributes. +The **`:in-range`** [CSS](/en-US/docs/Web/CSS) [pseudo-class](/en-US/docs/Web/CSS/Pseudo-classes) represents an {{htmlelement("input")}} element whose current value is within the range limits specified by the [`min`](/en-US/docs/Web/HTML/Reference/Elements/input#min) and [`max`](/en-US/docs/Web/HTML/Reference/Elements/input#max) attributes. {{InteractiveExample("CSS Demo: :in-range", "tabbed-shorter")}} diff --git a/files/en-us/web/css/_colon_indeterminate/index.md b/files/en-us/web/css/_colon_indeterminate/index.md index c5bb51781004981..9b6bfab5e02ed77 100644 --- a/files/en-us/web/css/_colon_indeterminate/index.md +++ b/files/en-us/web/css/_colon_indeterminate/index.md @@ -18,14 +18,16 @@ input:indeterminate { Elements targeted by this selector are: -- [`<input type="checkbox">`](/en-US/docs/Web/HTML/Element/input/checkbox) elements whose [`indeterminate`](/en-US/docs/Web/API/HTMLInputElement/indeterminate) property is set to `true` -- [`<input type="radio">`](/en-US/docs/Web/HTML/Element/input/radio) elements, when all radio buttons with the same `name` value in the form are unchecked -- {{HTMLElement("progress")}} elements in an indeterminate state +- [`<input type="checkbox">`](/en-US/docs/Web/HTML/Reference/Elements/input/checkbox) elements with the [`indeterminate`](/en-US/docs/Web/API/HTMLInputElement/indeterminate) property set to `true`. +- [`<input type="radio">`](/en-US/docs/Web/HTML/Reference/Elements/input/radio) elements with the same `name` value and none of them `checked`. +- {{HTMLElement("progress")}} elements with no `value`, placing them in an indeterminate state. ## Syntax -```plain -:indeterminate +```css +:indeterminate { + /* ... */ +} ``` ## Examples @@ -85,8 +87,8 @@ fieldset:not(:first-of-type) > div:not(:last-child) { ```js const inputs = document.getElementsByTagName("input"); -for (let i = 0; i < inputs.length; i++) { - inputs[i].indeterminate = true; +for (const input of inputs) { + input.indeterminate = true; } ``` @@ -131,6 +133,6 @@ progress:indeterminate { - [Web forms — Working with user data](/en-US/docs/Learn_web_development/Extensions/Forms) - [Styling web forms](/en-US/docs/Learn_web_development/Extensions/Forms/Styling_web_forms) -- The [`<input type="checkbox">`](/en-US/docs/Web/HTML/Element/input/checkbox) element's [`indeterminate`](/en-US/docs/Web/API/HTMLInputElement/indeterminate) property +- The [`<input type="checkbox">`](/en-US/docs/Web/HTML/Reference/Elements/input/checkbox) element's [`indeterminate`](/en-US/docs/Web/API/HTMLInputElement/indeterminate) property - {{HTMLElement("input")}} and the {{domxref("HTMLInputElement")}} interface which implements it. - The {{cssxref(":checked")}} CSS selector lets you style checkboxes based on whether they're checked or not diff --git a/files/en-us/web/css/_colon_invalid/index.md b/files/en-us/web/css/_colon_invalid/index.md index b2717a4039a0705..43dd6d4e39dd316 100644 --- a/files/en-us/web/css/_colon_invalid/index.md +++ b/files/en-us/web/css/_colon_invalid/index.md @@ -7,7 +7,7 @@ browser-compat: css.selectors.invalid {{CSSRef}} -The **`:invalid`** [CSS](/en-US/docs/Web/CSS) [pseudo-class](/en-US/docs/Web/CSS/Pseudo-classes) represents any {{HTMLElement("form")}}, {{HTMLElement("fieldset")}}, {{HTMLElement("input")}} or other {{HTMLElement("form")}} element whose contents fail to [validate](/en-US/docs/Web/HTML/Constraint_validation). +The **`:invalid`** [CSS](/en-US/docs/Web/CSS) [pseudo-class](/en-US/docs/Web/CSS/Pseudo-classes) represents any {{HTMLElement("form")}}, {{HTMLElement("fieldset")}}, {{HTMLElement("input")}} or other {{HTMLElement("form")}} element whose contents fail to [validate](/en-US/docs/Web/HTML/Guides/Constraint_validation). {{InteractiveExample("CSS Demo: :invalid", "tabbed-shorter")}} @@ -57,7 +57,7 @@ This pseudo-class is useful for highlighting field errors for the user. The color red is commonly used to indicate invalid input. People who have certain types of color blindness will be unable to determine the input's state unless it is accompanied by an additional indicator that does not rely on color to convey meaning. Typically, descriptive text and/or an icon are used. -- [MDN Understanding WCAG, Guideline 1.4 explanations](/en-US/docs/Web/Accessibility/Understanding_WCAG/Perceivable#guideline_1.4_make_it_easier_for_users_to_see_and_hear_content_including_separating_foreground_from_background) +- [MDN Understanding WCAG, Guideline 1.4 explanations](/en-US/docs/Web/Accessibility/Guides/Understanding_WCAG/Perceivable#guideline_1.4_make_it_easier_for_users_to_see_and_hear_content_including_separating_foreground_from_background) - [Understanding Success Criterion 1.4.1 | W3C Understanding WCAG 2.0](https://www.w3.org/TR/UNDERSTANDING-WCAG20/visual-audio-contrast-without-color.html) ## Examples diff --git a/files/en-us/web/css/_colon_is/index.md b/files/en-us/web/css/_colon_is/index.md index 09d0da8f809aa06..26af04a2af2626f 100644 --- a/files/en-us/web/css/_colon_is/index.md +++ b/files/en-us/web/css/_colon_is/index.md @@ -20,7 +20,6 @@ ol { color: darkblue; } -/* stylelint-disable-next-line selector-pseudo-class-no-unknown */ :is(ol, ul, menu:unsupported) :is(ol, ul) { color: green; } @@ -165,7 +164,7 @@ You can replace it with: ### Simplifying section selectors -The `:is()` pseudo-class is particularly useful when dealing with HTML [sections and headings](/en-US/docs/Web/HTML/Element/Heading_Elements). Since {{HTMLElement("section")}}, {{HTMLElement("article")}}, {{HTMLElement("aside")}}, and {{HTMLElement("nav")}} are commonly nested together, without `:is()`, styling them to match one another can be tricky. +The `:is()` pseudo-class is particularly useful when dealing with HTML [sections and headings](/en-US/docs/Web/HTML/Reference/Elements/Heading_Elements). Since {{HTMLElement("section")}}, {{HTMLElement("article")}}, {{HTMLElement("aside")}}, and {{HTMLElement("nav")}} are commonly nested together, without `:is()`, styling them to match one another can be tricky. For example, without `:is()`, styling all the {{HTMLElement("Heading_Elements", "h1")}} elements at different depths could be very complicated: diff --git a/files/en-us/web/css/_colon_lang/index.md b/files/en-us/web/css/_colon_lang/index.md index 80dedc7a5d1fd88..62b66f10c0aba9d 100644 --- a/files/en-us/web/css/_colon_lang/index.md +++ b/files/en-us/web/css/_colon_lang/index.md @@ -30,7 +30,7 @@ The **`:lang()`** [CSS](/en-US/docs/Web/CSS) [pseudo-class](/en-US/docs/Web/CSS/ ``` > [!NOTE] -> In HTML, the language is determined by a combination of the [`lang`](/en-US/docs/Web/HTML/Global_attributes/lang) attribute, the {{HTMLElement("meta")}} element, and possibly by information from the protocol (such as HTTP headers). For other document types there may be other document methods for determining the language. +> In HTML, the language is determined by a combination of the [`lang`](/en-US/docs/Web/HTML/Reference/Global_attributes/lang) attribute, the {{HTMLElement("meta")}} element, and possibly by information from the protocol (such as HTTP headers). For other document types there may be other document methods for determining the language. ## Syntax @@ -147,6 +147,6 @@ p { ## See also - The {{cssxref(":dir")}} pseudo-class that matches by directionality of text -- HTML [`lang`](/en-US/docs/Web/HTML/Global_attributes/lang) attribute -- HTML [`translate`](/en-US/docs/Web/HTML/Global_attributes/translate) attribute +- HTML [`lang`](/en-US/docs/Web/HTML/Reference/Global_attributes/lang) attribute +- HTML [`translate`](/en-US/docs/Web/HTML/Reference/Global_attributes/translate) attribute - {{RFC(5646, "Tags for Identifying Languages (also known as BCP 47)")}} diff --git a/files/en-us/web/css/_colon_last-of-type/index.md b/files/en-us/web/css/_colon_last-of-type/index.md index fffefae7b6b83c9..23c28c56f085322 100644 --- a/files/en-us/web/css/_colon_last-of-type/index.md +++ b/files/en-us/web/css/_colon_last-of-type/index.md @@ -7,7 +7,7 @@ browser-compat: css.selectors.last-of-type {{CSSRef}} -The **`:last-of-type`** [CSS](/en-US/docs/Web/CSS) [pseudo-class](/en-US/docs/Web/CSS/Pseudo-classes) represents the last element of its type among a group of sibling elements. +The **`:last-of-type`** [CSS](/en-US/docs/Web/CSS) [pseudo-class](/en-US/docs/Web/CSS/Pseudo-classes) represents the last element of its type (tag name) among a group of sibling elements. {{InteractiveExample("CSS Demo: :last-of-type", "tabbed-shorter")}} diff --git a/files/en-us/web/css/_colon_modal/index.md b/files/en-us/web/css/_colon_modal/index.md index 3fc90d22596f5bd..f155a454198a99f 100644 --- a/files/en-us/web/css/_colon_modal/index.md +++ b/files/en-us/web/css/_colon_modal/index.md @@ -65,14 +65,14 @@ showNumber.addEventListener("click", () => { Examples of elements that will prevent user interaction with the rest of the page and will be selected by the `:modal` pseudo-class include: -- The [`dialog`](/en-US/docs/Web/HTML/Element/dialog) element opened with the `showModal()` API. +- The [`dialog`](/en-US/docs/Web/HTML/Reference/Elements/dialog) element opened with the `showModal()` API. - The element selected by the [`:fullscreen`](/en-US/docs/Web/CSS/:fullscreen) pseudo-class when opened with the `requestFullscreen()` API. ## Examples ### Styling a modal dialog -This example styles a modal dialog that opens when the "Update details" button is activated. This example has been built on top of the {{HTMLElement("dialog")}} element [example](/en-US/docs/Web/HTML/Element/dialog#handling_the_return_value_from_the_dialog). +This example styles a modal dialog that opens when the "Update details" button is activated. This example has been built on top of the {{HTMLElement("dialog")}} element [example](/en-US/docs/Web/HTML/Reference/Elements/dialog#handling_the_return_value_from_the_dialog). ```html hidden <!-- Basic modal dialog containing a form --> @@ -158,6 +158,6 @@ favDialog.addEventListener("close", () => { ## See also -- [`dialog`](/en-US/docs/Web/HTML/Element/dialog) element +- [`dialog`](/en-US/docs/Web/HTML/Reference/Elements/dialog) element - Other element display state pseudo-classes: {{CSSxRef(":fullscreen")}} and {{CSSxRef(":picture-in-picture")}} - Complete list of [pseudo-classes](/en-US/docs/Web/CSS/Pseudo-classes) diff --git a/files/en-us/web/css/_colon_nth-child/index.md b/files/en-us/web/css/_colon_nth-child/index.md index 3caf65783cf7323..0e0c6cbe35a7b88 100644 --- a/files/en-us/web/css/_colon_nth-child/index.md +++ b/files/en-us/web/css/_colon_nth-child/index.md @@ -383,10 +383,6 @@ A common practice for tables is to use _zebra-stripes_ which alternates between #### HTML -```html-nolint hidden -<div class="wrapper"> -``` - ```html-nolint <table class="broken"> <thead> @@ -416,14 +412,10 @@ A common practice for tables is to use _zebra-stripes_ which alternates between </table> ``` -```html hidden -</div> -``` - #### CSS ```css hidden -.wrapper { +body { display: flex; justify-content: space-around; } diff --git a/files/en-us/web/css/_colon_nth-last-child/index.md b/files/en-us/web/css/_colon_nth-last-child/index.md index 28a522317ed23db..f556f2320987baa 100644 --- a/files/en-us/web/css/_colon_nth-last-child/index.md +++ b/files/en-us/web/css/_colon_nth-last-child/index.md @@ -82,7 +82,8 @@ By passing a selector argument, we can select the **nth-last** element that matc > This is different from moving the selector outside of the function, like: ```css -li.important: nth-last-child(-n + 3); +li.important:nth-last-child(-n + 3) { +} ``` This selector applies a style to list items if they are also within the last three children. diff --git a/files/en-us/web/css/_colon_only-of-type/index.md b/files/en-us/web/css/_colon_only-of-type/index.md index d45655dc5d97f15..2d568ddec02a6ce 100644 --- a/files/en-us/web/css/_colon_only-of-type/index.md +++ b/files/en-us/web/css/_colon_only-of-type/index.md @@ -7,7 +7,7 @@ browser-compat: css.selectors.only-of-type {{CSSRef}} -The **`:only-of-type`** CSS [pseudo-class](/en-US/docs/Web/CSS/Pseudo-classes) represents an element that has no siblings of the same type. +The **`:only-of-type`** CSS [pseudo-class](/en-US/docs/Web/CSS/Pseudo-classes) represents an element that has no siblings of the same type (tag name). {{InteractiveExample("CSS Demo: :only-of-type", "tabbed-shorter")}} diff --git a/files/en-us/web/css/_colon_open/index.md b/files/en-us/web/css/_colon_open/index.md index c585cf2b8e93429..501c1545e032d9d 100644 --- a/files/en-us/web/css/_colon_open/index.md +++ b/files/en-us/web/css/_colon_open/index.md @@ -22,12 +22,12 @@ The **`:open`** [CSS](/en-US/docs/Web/CSS) [pseudo-class](/en-US/docs/Web/CSS/Ps The `:open` pseudo-class selects any element currently in the open state, which includes the following elements: - {{htmlelement("details")}} and {{htmlelement("dialog")}} elements that are in an open state, that is, they have the `open` attribute set. -- {{htmlelement("input")}} elements that display a picker interface for the user to choose a value from (for example [`<input type="color">`](/en-US/docs/Web/HTML/Element/input/color)), when the picker is displayed. -- {{htmlelement("select")}} elements that display a drop-down box for the user to choose a value from, when the drop-down is displayed. +- {{htmlelement("input")}} elements that display a picker interface for the user to choose a value from (for example [`<input type="color">`](/en-US/docs/Web/HTML/Reference/Elements/input/color)), when the picker is displayed. +- {{htmlelement("select")}} elements that display a drop-down picker for the user to choose a value from, when the picker is displayed. Note that when implementing [customizable select elements](/en-US/docs/Learn_web_development/Extensions/Forms/Customizable_select), the picker itself can be selected using the {{cssxref("::picker()", "::picker(select)")}} pseudo-element. Note that the open and closed states are semantic states, and don't necessary correlate with the visibility of the element in question. For example, a `<details>` element that is expanded to show its content is open, and will be selected by the `details:open` selector, even if it is hidden with a {{cssxref("visibility")}} value of `hidden`. -{{domxref("Popover API", "Popover", "", "nocode")}} elements (that is, elements with the [`popover`](/en-US/docs/Web/HTML/Global_attributes/popover) attribute set on them) have distinct semantic states representing popovers that are showing or hidden, which can coexist alongside open and closed states. To target a popover element in an showing state, use the {{cssxref(":popover-open")}} pseudo-class instead. +{{domxref("Popover API", "Popover", "", "nocode")}} elements (that is, elements with the [`popover`](/en-US/docs/Web/HTML/Reference/Global_attributes/popover) attribute set on them) have distinct semantic states representing popovers that are showing or hidden, which can coexist alongside open and closed states. To target a popover element in an showing state, use the {{cssxref(":popover-open")}} pseudo-class instead. ## Examples @@ -119,7 +119,7 @@ There is nothing special about our fruit selector. ``` > [!NOTE] -> We are not using a multi-line `<select>` (that is, one with the [`multiple`](/en-US/docs/Web/HTML/Attributes/multiple) attribute set) — those tend to render as a scrolling list box rather than a drop down menu, so don't have an open state. +> We are not using a multi-line `<select>` (that is, one with the [`multiple`](/en-US/docs/Web/HTML/Reference/Attributes/multiple) attribute set) — those tend to render as a scrolling list box rather than a drop down menu, so don't have an open state. #### CSS @@ -136,8 +136,7 @@ select { font-size: 100%; padding: 5px; border: 1px solid black; - background-color: white; - background: url("data:image/svg+xml,%3Csvg width='20' height='20' viewbox='0 0 20 20' xmlns='http://www.w3.org/2000/svg'%3E%3Cpolygon points='5,5 15,5 10,15'/%3E%3C/svg%3E") + background: url("data:image/svg+xml,%3Csvg width='20' height='20' viewBox='0 0 20 20' xmlns='http://www.w3.org/2000/svg'%3E%3Cpolygon points='5,5 15,5 10,15'/%3E%3C/svg%3E") no-repeat right 3px center / 1em 1em; } @@ -155,7 +154,7 @@ When the `<select>` is opened, we use the `:open` pseudo-class to set a differen ```css select:open { background-color: #f8f2dc; - background-image: url("data:image/svg+xml,%3Csvg width='20' height='20' viewbox='0 0 20 20' xmlns='http://www.w3.org/2000/svg'%3E%3Cpolygon points='5,15 10,5 15,15'/%3E%3C/svg%3E"); + background-image: url("data:image/svg+xml,%3Csvg width='20' height='20' viewBox='0 0 20 20' xmlns='http://www.w3.org/2000/svg'%3E%3Cpolygon points='5,15 10,5 15,15'/%3E%3C/svg%3E"); } label:has(select:open) { diff --git a/files/en-us/web/css/_colon_optional/index.md b/files/en-us/web/css/_colon_optional/index.md index cf7da24813e0e86..512c5033d7ca679 100644 --- a/files/en-us/web/css/_colon_optional/index.md +++ b/files/en-us/web/css/_colon_optional/index.md @@ -7,7 +7,7 @@ browser-compat: css.selectors.optional {{CSSRef}} -The **`:optional`** [CSS](/en-US/docs/Web/CSS) [pseudo-class](/en-US/docs/Web/CSS/Pseudo-classes) represents any {{HTMLElement("input")}}, {{HTMLElement("select")}}, or {{HTMLElement("textarea")}} element that does not have the [`required`](/en-US/docs/Web/HTML/Element/input#required) attribute set on it. +The **`:optional`** [CSS](/en-US/docs/Web/CSS) [pseudo-class](/en-US/docs/Web/CSS/Pseudo-classes) represents any {{HTMLElement("input")}}, {{HTMLElement("select")}}, or {{HTMLElement("textarea")}} element that does not have the [`required`](/en-US/docs/Web/HTML/Reference/Elements/input#required) attribute set on it. {{InteractiveExample("CSS Demo: :optional", "tabbed-standard")}} @@ -61,11 +61,11 @@ This pseudo-class is useful for styling fields that are not required to submit a ## Accessibility -If a [form](/en-US/docs/Web/HTML/Element/form) contains optional {{htmlelement("input")}}s, required inputs should be indicated using the [`required`](/en-US/docs/Web/HTML/Element/input#required) attribute. This will ensure that people navigating with the aid of assistive technology such as a screen reader will be able to understand which inputs need valid content to ensure a successful form submission. +If a [form](/en-US/docs/Web/HTML/Reference/Elements/form) contains optional {{htmlelement("input")}}s, required inputs should be indicated using the [`required`](/en-US/docs/Web/HTML/Reference/Elements/input#required) attribute. This will ensure that people navigating with the aid of assistive technology such as a screen reader will be able to understand which inputs need valid content to ensure a successful form submission. Required inputs should also be indicated visually, using a treatment that does not rely solely on color to convey meaning. Typically, descriptive text and/or an icon are used. -- [MDN Understanding WCAG, Guideline 3.3 explanations](/en-US/docs/Web/Accessibility/Understanding_WCAG/Understandable#guideline_3.3_%e2%80%94_input_assistance_help_users_avoid_and_correct_mistakes) +- [MDN Understanding WCAG, Guideline 3.3 explanations](/en-US/docs/Web/Accessibility/Guides/Understanding_WCAG/Understandable#guideline_3.3_%e2%80%94_input_assistance_help_users_avoid_and_correct_mistakes) - [Understanding Success Criterion 3.3.2 | W3C Understanding WCAG 2.0](https://www.w3.org/TR/UNDERSTANDING-WCAG20/minimize-error-cues.html) ## Examples diff --git a/files/en-us/web/css/_colon_out-of-range/index.md b/files/en-us/web/css/_colon_out-of-range/index.md index 18b29670f9b4088..8188f0d916d183f 100644 --- a/files/en-us/web/css/_colon_out-of-range/index.md +++ b/files/en-us/web/css/_colon_out-of-range/index.md @@ -7,7 +7,7 @@ browser-compat: css.selectors.out-of-range {{CSSRef}} -The **`:out-of-range`** [CSS](/en-US/docs/Web/CSS) [pseudo-class](/en-US/docs/Web/CSS/Pseudo-classes) represents an {{htmlelement("input")}} element whose current value is outside the range limits specified by the [`min`](/en-US/docs/Web/HTML/Element/input#min) and [`max`](/en-US/docs/Web/HTML/Element/input#max) attributes. +The **`:out-of-range`** [CSS](/en-US/docs/Web/CSS) [pseudo-class](/en-US/docs/Web/CSS/Pseudo-classes) represents an {{htmlelement("input")}} element whose current value is outside the range limits specified by the [`min`](/en-US/docs/Web/HTML/Reference/Elements/input#min) and [`max`](/en-US/docs/Web/HTML/Reference/Elements/input#max) attributes. {{InteractiveExample("CSS Demo: :out-of-range", "tabbed-shorter")}} diff --git a/files/en-us/web/css/_colon_paused/index.md b/files/en-us/web/css/_colon_paused/index.md index 031cdfcd08c6dfe..76efdaffbb653c7 100644 --- a/files/en-us/web/css/_colon_paused/index.md +++ b/files/en-us/web/css/_colon_paused/index.md @@ -7,7 +7,7 @@ browser-compat: css.selectors.paused {{CSSRef}} -The **`:paused`** [CSS](/en-US/docs/Web/CSS) [pseudo-class](/en-US/docs/Web/CSS/Pseudo-classes) selector represents an element that is playable, such as {{htmlelement("audio")}} or {{htmlelement("video")}}, when that element is "paused" (i.e. not "playing"). +The **`:paused`** [CSS](/en-US/docs/Web/CSS) [pseudo-class](/en-US/docs/Web/CSS/Pseudo-classes) selector represents an element that is playable, such as {{htmlelement("audio")}} or {{htmlelement("video")}}, when that element is "paused" (i.e., not "playing"). A resource is paused if the user explicitly paused it, or if it is in a non-activated or other non-playing state, like "loaded, hasn't been activated yet". This is different from `:buffering` or `:stalled`, which are states that occur while the resource is considered "playing". diff --git a/files/en-us/web/css/_colon_placeholder-shown/index.md b/files/en-us/web/css/_colon_placeholder-shown/index.md index eef0a1b9c0a7e80..5d98cd0ed6834a4 100644 --- a/files/en-us/web/css/_colon_placeholder-shown/index.md +++ b/files/en-us/web/css/_colon_placeholder-shown/index.md @@ -7,7 +7,7 @@ browser-compat: css.selectors.placeholder-shown {{CSSRef}} -The **`:placeholder-shown`** [CSS](/en-US/docs/Web/CSS) [pseudo-class](/en-US/docs/Web/CSS/Pseudo-classes) represents any {{HTMLElement("input")}} or {{HTMLElement("textarea")}} element that is currently displaying [placeholder text](/en-US/docs/Web/HTML/Element/input#placeholder). +The **`:placeholder-shown`** [CSS](/en-US/docs/Web/CSS) [pseudo-class](/en-US/docs/Web/CSS/Pseudo-classes) represents any {{HTMLElement("input")}} or {{HTMLElement("textarea")}} element that is currently displaying [placeholder text](/en-US/docs/Web/HTML/Reference/Elements/input#placeholder). {{InteractiveExample("CSS Demo: :placeholder-shown", "tabbed-shorter")}} diff --git a/files/en-us/web/css/_colon_popover-open/index.md b/files/en-us/web/css/_colon_popover-open/index.md index aa45f914aac1286..eabe9455270ad0d 100644 --- a/files/en-us/web/css/_colon_popover-open/index.md +++ b/files/en-us/web/css/_colon_popover-open/index.md @@ -7,7 +7,7 @@ browser-compat: css.selectors.popover-open {{CSSRef}} -The **`:popover-open`** [CSS](/en-US/docs/Web/CSS) [pseudo-class](/en-US/docs/Web/CSS/Pseudo-classes) represents a {{domxref("Popover API", "popover", "", "nocode")}} element (i.e. one with a [`popover` attribute](/en-US/docs/Web/HTML/Global_attributes/popover)) that is in the showing state. You can use this to apply style to popover elements only when they are shown. +The **`:popover-open`** [CSS](/en-US/docs/Web/CSS) [pseudo-class](/en-US/docs/Web/CSS/Pseudo-classes) represents a {{domxref("Popover API", "popover", "", "nocode")}} element (i.e., one with a [`popover` attribute](/en-US/docs/Web/HTML/Reference/Global_attributes/popover)) that is in the showing state. You can use this to apply style to popover elements only when they are shown. ## Syntax @@ -61,4 +61,4 @@ To override the default styles and get the popover to appear somewhere else on y ## See also - [Popover API](/en-US/docs/Web/API/Popover_API) -- [`popover`](/en-US/docs/Web/HTML/Global_attributes/popover) HTML global attribute +- [`popover`](/en-US/docs/Web/HTML/Reference/Global_attributes/popover) HTML global attribute diff --git a/files/en-us/web/css/_colon_read-only/index.md b/files/en-us/web/css/_colon_read-only/index.md index 88f6b71e459d2a1..617013a9d0f8db2 100644 --- a/files/en-us/web/css/_colon_read-only/index.md +++ b/files/en-us/web/css/_colon_read-only/index.md @@ -7,7 +7,7 @@ browser-compat: css.selectors.read-only {{CSSRef}} -The **`:read-only`** [CSS](/en-US/docs/Web/CSS) [pseudo-class](/en-US/docs/Web/CSS/Pseudo-classes) selects elements (such as certain {{htmlelement("input")}} types and {{htmlelement("textarea")}}) that are not editable by the user. Elements on which the HTML attribute [`readonly`](/en-US/docs/Web/HTML/Attributes/readonly) doesn't have an effect (such as [`<input type="radio">`](/en-US/docs/Web/HTML/Element/input/radio), [`<input type="checkbox">`](/en-US/docs/Web/HTML/Element/input/checkbox), and all other non-form elements) are also selected by the `:read-only` pseudo-class. In fact, `:read-only` matches anything that {{cssxref(":read-write")}} doesn't match, making it equivalent to `:not(:read-write)`. +The **`:read-only`** [CSS](/en-US/docs/Web/CSS) [pseudo-class](/en-US/docs/Web/CSS/Pseudo-classes) selects elements (such as certain {{htmlelement("input")}} types and {{htmlelement("textarea")}}) that are not editable by the user. Elements on which the HTML attribute [`readonly`](/en-US/docs/Web/HTML/Reference/Attributes/readonly) doesn't have an effect (such as [`<input type="radio">`](/en-US/docs/Web/HTML/Reference/Elements/input/radio), [`<input type="checkbox">`](/en-US/docs/Web/HTML/Reference/Elements/input/checkbox), and all other non-form elements) are also selected by the `:read-only` pseudo-class. In fact, `:read-only` matches anything that {{cssxref(":read-write")}} doesn't match, making it equivalent to `:not(:read-write)`. {{InteractiveExample("CSS Demo: :read-only", "tabbed-shorter")}} @@ -133,7 +133,6 @@ textarea { display: block; font-family: inherit; font-size: 100%; - padding: 0; margin: 0; box-sizing: border-box; padding: 5px; @@ -224,4 +223,4 @@ p:read-write { ## See also - {{cssxref(":read-write")}} -- HTML [`contenteditable`](/en-US/docs/Web/HTML/Global_attributes/contenteditable) attribute +- HTML [`contenteditable`](/en-US/docs/Web/HTML/Reference/Global_attributes/contenteditable) attribute diff --git a/files/en-us/web/css/_colon_read-write/index.md b/files/en-us/web/css/_colon_read-write/index.md index e5de819ea640a8b..0800342d644a097 100644 --- a/files/en-us/web/css/_colon_read-write/index.md +++ b/files/en-us/web/css/_colon_read-write/index.md @@ -81,7 +81,7 @@ You can find the full source code at [readonly-confirmation.html](https://github ### Styling read-write non-form controls -This selector doesn't just select {{htmlElement("input")}}/{{htmlElement("textarea")}} elements — it will select _any_ element that can be edited by the user, such as a {{htmlelement("p")}} element with [`contenteditable`](/en-US/docs/Web/HTML/Global_attributes/contenteditable) set on it. +This selector doesn't just select {{htmlElement("input")}}/{{htmlElement("textarea")}} elements — it will select _any_ element that can be edited by the user, such as a {{htmlelement("p")}} element with [`contenteditable`](/en-US/docs/Web/HTML/Reference/Global_attributes/contenteditable) set on it. ```html <p contenteditable>This paragraph is editable; it is read-write.</p> @@ -119,4 +119,4 @@ p:read-write { ## See also - {{cssxref(":read-only")}} -- HTML [`contenteditable`](/en-US/docs/Web/HTML/Global_attributes/contenteditable) attribute +- HTML [`contenteditable`](/en-US/docs/Web/HTML/Reference/Global_attributes/contenteditable) attribute diff --git a/files/en-us/web/css/_colon_required/index.md b/files/en-us/web/css/_colon_required/index.md index 4355e454e100442..adaca31f32ad516 100644 --- a/files/en-us/web/css/_colon_required/index.md +++ b/files/en-us/web/css/_colon_required/index.md @@ -7,7 +7,7 @@ browser-compat: css.selectors.required {{CSSRef}} -The **`:required`** [CSS](/en-US/docs/Web/CSS) [pseudo-class](/en-US/docs/Web/CSS/Pseudo-classes) represents any {{HTMLElement("input")}}, {{HTMLElement("select")}}, or {{HTMLElement("textarea")}} element that has the [`required`](/en-US/docs/Web/HTML/Element/input#required) attribute set on it. +The **`:required`** [CSS](/en-US/docs/Web/CSS) [pseudo-class](/en-US/docs/Web/CSS/Pseudo-classes) represents any {{HTMLElement("input")}}, {{HTMLElement("select")}}, or {{HTMLElement("textarea")}} element that has the [`required`](/en-US/docs/Web/HTML/Reference/Elements/input#required) attribute set on it. {{InteractiveExample("CSS Demo: :required", "tabbed-standard")}} @@ -61,11 +61,11 @@ This pseudo-class is useful for highlighting fields that must have valid data be ## Accessibility -Mandatory {{htmlelement("input")}}s should have the [`required`](/en-US/docs/Web/HTML/Element/input#required) attribute applied to them. This will ensure that people navigating with the aid of assistive technology such as a screen reader will be able to understand which inputs need valid content to ensure a successful submission. +Mandatory {{htmlelement("input")}}s should have the [`required`](/en-US/docs/Web/HTML/Reference/Elements/input#required) attribute applied to them. This will ensure that people navigating with the aid of assistive technology such as a screen reader will be able to understand which inputs need valid content to ensure a successful submission. If the form also contains [optional](/en-US/docs/Web/CSS/:optional) inputs, required inputs should be indicated visually using a treatment that does not rely solely on color to convey meaning. Typically, descriptive text and/or an icon are used. -- [MDN Understanding WCAG, Guideline 3.3 explanations](/en-US/docs/Web/Accessibility/Understanding_WCAG/Understandable#guideline_3.3_%e2%80%94_input_assistance_help_users_avoid_and_correct_mistakes) +- [MDN Understanding WCAG, Guideline 3.3 explanations](/en-US/docs/Web/Accessibility/Guides/Understanding_WCAG/Understandable#guideline_3.3_%e2%80%94_input_assistance_help_users_avoid_and_correct_mistakes) - [Understanding Success Criterion 3.3.2 | W3C Understanding WCAG 2.0](https://www.w3.org/TR/UNDERSTANDING-WCAG20/minimize-error-cues.html) ## Examples diff --git a/files/en-us/web/css/_colon_scope/index.md b/files/en-us/web/css/_colon_scope/index.md index fea22f3dec5cf93..4c58d9f72c2c3e2 100644 --- a/files/en-us/web/css/_colon_scope/index.md +++ b/files/en-us/web/css/_colon_scope/index.md @@ -150,7 +150,7 @@ document.getElementById("results").textContent = Array.prototype.map #### Result -The scope of `context` is the element with the [`id`](/en-US/docs/Web/HTML/Global_attributes/id) of `context`. The selected elements are the `<div>` elements that are direct children of that context — `element-1` and `element-2` — but not their descendants. +The scope of `context` is the element with the [`id`](/en-US/docs/Web/HTML/Reference/Global_attributes/id) of `context`. The selected elements are the `<div>` elements that are direct children of that context — `element-1` and `element-2` — but not their descendants. {{ EmbedLiveSample('Using :scope in JavaScript') }} diff --git a/files/en-us/web/css/_colon_stalled/index.md b/files/en-us/web/css/_colon_stalled/index.md index 3c976ce42eb689c..f59838b9049cfe2 100644 --- a/files/en-us/web/css/_colon_stalled/index.md +++ b/files/en-us/web/css/_colon_stalled/index.md @@ -9,7 +9,7 @@ browser-compat: css.selectors.stalled The **`:stalled`** [CSS](/en-US/docs/Web/CSS) [pseudo-class](/en-US/docs/Web/CSS/Pseudo-classes) selector represents an element that is playable, such as {{htmlelement("audio")}} or {{htmlelement("video")}}, when playback is stalled. A resource is considered to be stalled if the user has requested playback of a specific position in the media resource, but it has failed to receive any data for some amount of time. -This is different from {{cssxref(":buffering")}} in that the media element is unexpectedly not loading data when stalled (e.g. due to a network error) for around 3 seconds (the exact time is [user agent dependent](https://html.spec.whatwg.org/multipage/media.html#stall-timeout)). +This is different from {{cssxref(":buffering")}} in that the media element is unexpectedly not loading data when stalled (e.g., due to a network error) for around 3 seconds (the exact time is [user agent dependent](https://html.spec.whatwg.org/multipage/media.html#stall-timeout)). > [!NOTE] > Like with the {{cssxref(":buffering")}} pseudo-class, the element is still considered to be "playing" when it is "stalled". diff --git a/files/en-us/web/css/_colon_state/index.md b/files/en-us/web/css/_colon_state/index.md index f77073267595c76..77f788cfbcb2828 100644 --- a/files/en-us/web/css/_colon_state/index.md +++ b/files/en-us/web/css/_colon_state/index.md @@ -70,7 +70,7 @@ For a live example of this code in action, see the [Matching the custom state of This example shows how the `:state()` pseudo-class can be used to target the [shadow parts](/en-US/docs/Web/CSS/CSS_shadow_parts) of a custom element. -Shadow parts are defined and named using the [`part`](/en-US/docs/Web/HTML/Global_attributes/part) attribute. +Shadow parts are defined and named using the [`part`](/en-US/docs/Web/HTML/Reference/Global_attributes/part) attribute. For example, consider a custom element named `<question-box>` that uses a `<labeled-checkbox>` custom element as a shadow part named `checkbox`: ```js diff --git a/files/en-us/web/css/_colon_target-current/index.md b/files/en-us/web/css/_colon_target-current/index.md new file mode 100644 index 000000000000000..6ffe447e03393e4 --- /dev/null +++ b/files/en-us/web/css/_colon_target-current/index.md @@ -0,0 +1,56 @@ +--- +title: :target-current +slug: Web/CSS/:target-current +page-type: css-pseudo-class +status: + - experimental +browser-compat: css.selectors.target-current +--- + +{{CSSRef}}{{SeeCompatTable}} + +The **`:target-current`** [CSS](/en-US/docs/Web/CSS) [pseudo-class](/en-US/docs/Web/CSS/Pseudo-classes) selects the **active** scroll marker — the {{cssxref("::scroll-marker")}} pseudo-element of a {{cssxref("scroll-marker-group")}} that is currently scrolled to. This [selector](/en-US/docs/Web/CSS/CSS_selectors) can be used to style the active navigation position within a [scroll marker group](/en-US/docs/Web/CSS/::scroll-marker-group#description). + +> [!NOTE] +> The `:target-current` pseudo-class is only valid on `::scroll-marker` pseudo-elements. + +## Syntax + +```css-nolint +:target-current { + /* ... */ +} +``` + +## Examples + +See [Creating CSS carousels](/en-US/docs/Web/CSS/CSS_overflow/CSS_carousels) and {{cssxref("::scroll-marker")}} for complete examples that use the `:target-current` pseudo-class. + +### Basic usage + +```css +::scroll-marker { + background-color: white; +} + +::scroll-marker:target-current { + background-color: black; +} +``` + +## Specifications + +{{Specifications}} + +## Browser compatibility + +{{Compat}} + +## See also + +- {{cssxref("scroll-marker-group")}} +- {{cssxref("::scroll-marker")}} +- {{cssxref("::scroll-marker-group")}} +- [Creating CSS carousels](/en-US/docs/Web/CSS/CSS_overflow/CSS_carousels) +- [CSS overflow](/en-US/docs/Web/CSS/CSS_overflow) module +- [CSS Carousel Gallery](https://chrome.dev/carousel/) via chrome.dev (2025) diff --git a/files/en-us/web/css/_colon_target-within/index.md b/files/en-us/web/css/_colon_target-within/index.md index 9517530a89abb1e..c03418c30c0355d 100644 --- a/files/en-us/web/css/_colon_target-within/index.md +++ b/files/en-us/web/css/_colon_target-within/index.md @@ -9,7 +9,7 @@ spec-urls: https://drafts.csswg.org/selectors/#target-within-pseudo {{CSSRef}}{{SeeCompatTable}} -The **`:target-within`** [CSS](/en-US/docs/Web/CSS) [pseudo-class](/en-US/docs/Web/CSS/Pseudo-classes) represents an element that is a target element or _contains_ an element that is a target. A target element is a unique element with an [`id`](/en-US/docs/Web/HTML/Global_attributes/id) matching the URL's fragment. In other words, it represents an element that is itself matched by the {{CSSxRef(":target")}} pseudo-class or has a descendant that is matched by `:target`. (This includes descendants in [shadow trees](/en-US/docs/Web/API/Web_components/Using_shadow_DOM).) +The **`:target-within`** [CSS](/en-US/docs/Web/CSS) [pseudo-class](/en-US/docs/Web/CSS/Pseudo-classes) represents an element that is a target element or _contains_ an element that is a target. A target element is a unique element with an [`id`](/en-US/docs/Web/HTML/Reference/Global_attributes/id) matching the URL's fragment. In other words, it represents an element that is itself matched by the {{CSSxRef(":target")}} pseudo-class or has a descendant that is matched by `:target`. (This includes descendants in [shadow trees](/en-US/docs/Web/API/Web_components/Using_shadow_DOM).) ```css /* Selects a <div> when one of its descendants is a target */ diff --git a/files/en-us/web/css/_colon_target/index.md b/files/en-us/web/css/_colon_target/index.md index ec4f28d568c0771..d5bce30c7b4d34a 100644 --- a/files/en-us/web/css/_colon_target/index.md +++ b/files/en-us/web/css/_colon_target/index.md @@ -16,7 +16,7 @@ The **`:target`** [CSS](/en-US/docs/Web/CSS) [pseudo-class](/en-US/docs/Web/CSS/ } ``` -For example, the following URL has a fragment identifier (denoted by the _#_ sign) that marks the element with the [`id`](/en-US/docs/Web/HTML/Global_attributes/id) of `setup` as the document's target element: +For example, the following URL has a fragment identifier (denoted by the _#_ sign) that marks the element with the [`id`](/en-US/docs/Web/HTML/Reference/Global_attributes/id) of `setup` as the document's target element: ```url http://www.example.com/help/#setup diff --git a/files/en-us/web/css/_colon_user-invalid/index.md b/files/en-us/web/css/_colon_user-invalid/index.md index f246c2f356e99e6..e949cb10a64b6f5 100644 --- a/files/en-us/web/css/_colon_user-invalid/index.md +++ b/files/en-us/web/css/_colon_user-invalid/index.md @@ -7,7 +7,7 @@ browser-compat: css.selectors.user-invalid {{CSSRef}} -The **`:user-invalid`** CSS [pseudo-class](/en-US/docs/Web/CSS/Pseudo-classes) represents any validated form element whose value isn't valid based on their [validation constraints](/en-US/docs/Web/HTML/Constraint_validation), after the user has interacted with it. +The **`:user-invalid`** CSS [pseudo-class](/en-US/docs/Web/CSS/Pseudo-classes) represents any validated form element whose value isn't valid based on their [validation constraints](/en-US/docs/Web/HTML/Guides/Constraint_validation), after the user has interacted with it. The `:user-invalid` pseudo-class must match an {{CSSxRef(":invalid")}}, {{CSSxRef(":out-of-range")}}, or blank-but {{CSSxRef(":required")}} element between the time the user has attempted to submit the form and before the user has interacted again with the form element. diff --git a/files/en-us/web/css/_colon_user-valid/index.md b/files/en-us/web/css/_colon_user-valid/index.md index 36ccbc6ab5f1af1..b512613ab6748a6 100644 --- a/files/en-us/web/css/_colon_user-valid/index.md +++ b/files/en-us/web/css/_colon_user-valid/index.md @@ -7,7 +7,7 @@ browser-compat: css.selectors.user-valid {{CSSRef}} -The **`:user-valid`** CSS [pseudo-class](/en-US/docs/Web/CSS/Pseudo-classes) represents any validated form element whose value validates correctly based on its [validation constraints](/en-US/docs/Web/HTML/Constraint_validation). However, unlike {{cssxref(":valid")}} it only matches once the user has interacted with it. +The **`:user-valid`** CSS [pseudo-class](/en-US/docs/Web/CSS/Pseudo-classes) represents any validated form element whose value validates correctly based on its [validation constraints](/en-US/docs/Web/HTML/Guides/Constraint_validation). However, unlike {{cssxref(":valid")}} it only matches once the user has interacted with it. This pseudo-class is applied if the form control is valid and any of the following has occurred: diff --git a/files/en-us/web/css/_colon_valid/index.md b/files/en-us/web/css/_colon_valid/index.md index 6a7d4d9d5ee5204..62872d5002d17d5 100644 --- a/files/en-us/web/css/_colon_valid/index.md +++ b/files/en-us/web/css/_colon_valid/index.md @@ -7,7 +7,7 @@ browser-compat: css.selectors.valid {{CSSRef}} -The **`:valid`** [CSS](/en-US/docs/Web/CSS) [pseudo-class](/en-US/docs/Web/CSS/Pseudo-classes) represents any {{HTMLElement("input")}} or other {{HTMLElement("form")}} element whose contents [validate](/en-US/docs/Web/HTML/Constraint_validation) successfully. This allows to easily make valid fields adopt an appearance that helps the user confirm that their data is formatted properly. +The **`:valid`** [CSS](/en-US/docs/Web/CSS) [pseudo-class](/en-US/docs/Web/CSS/Pseudo-classes) represents any {{HTMLElement("input")}} or other {{HTMLElement("form")}} element whose contents [validate](/en-US/docs/Web/HTML/Guides/Constraint_validation) successfully. This allows to easily make valid fields adopt an appearance that helps the user confirm that their data is formatted properly. {{InteractiveExample("CSS Demo: :valid", "tabbed-shorter")}} @@ -58,7 +58,7 @@ This pseudo-class is useful for highlighting correct fields for the user. The color green is commonly used to indicate valid input. People who have certain types of color blindness will be unable to determine the input's state unless it is accompanied by an additional indicator that does not rely on color to convey meaning. Typically, descriptive text and/or an icon are used. -- [MDN Understanding WCAG, Guideline 1.4 explanations](/en-US/docs/Web/Accessibility/Understanding_WCAG/Perceivable#guideline_1.4_make_it_easier_for_users_to_see_and_hear_content_including_separating_foreground_from_background) +- [MDN Understanding WCAG, Guideline 1.4 explanations](/en-US/docs/Web/Accessibility/Guides/Understanding_WCAG/Perceivable#guideline_1.4_make_it_easier_for_users_to_see_and_hear_content_including_separating_foreground_from_background) - [Understanding Success Criterion 1.4.1 | W3C Understanding WCAG 2.0](https://www.w3.org/TR/UNDERSTANDING-WCAG20/visual-audio-contrast-without-color.html) ## Examples diff --git a/files/en-us/web/css/_colon_visited/index.md b/files/en-us/web/css/_colon_visited/index.md index 8cd161137e8d367..a5b20ece12e80b7 100644 --- a/files/en-us/web/css/_colon_visited/index.md +++ b/files/en-us/web/css/_colon_visited/index.md @@ -53,11 +53,11 @@ For privacy reasons, browsers strictly limit which styles you can apply using th - Allowable SVG attributes are {{SVGAttr("fill")}} and {{SVGAttr("stroke")}}. - The alpha component of the allowed styles will be ignored. The alpha component of the element's non-`:visited` state will be used instead. In Firefox when the alpha component is `0`, the style set in `:visited` will be ignored entirely. - Although these styles can change the appearance of colors to the end user, the {{domxref("window.getComputedStyle")}} method will lie and always return the value of the non-`:visited` color. -- The [`<link>`](/en-US/docs/Web/HTML/Element/link) element is never matched by `:visited`. +- The [`<link>`](/en-US/docs/Web/HTML/Reference/Elements/link) element is never matched by `:visited`. - DOM methods that match elements via CSS selectors — such as [`querySelector()`](/en-US/docs/Web/API/Document/querySelector) and [`querySelectorAll()`](/en-US/docs/Web/API/Document/querySelectorAll) — will always return an "empty" result even if there are visited links in a document. For the aforementioned methods, this will be `null` or an empty [`NodeList`](/en-US/docs/Web/API/NodeList), respectively. > [!NOTE] -> For more information on these limitations and the reasons behind them, see [Privacy and the :visited selector](/en-US/docs/Web/CSS/Privacy_and_the_:visited_selector). +> For more information on these limitations and the reasons behind them, see [Privacy and the :visited selector](/en-US/docs/Web/CSS/CSS_selectors/Privacy_and_the_visited_selector). ## Syntax @@ -109,5 +109,5 @@ a:visited { ## See also -- [Privacy and the :visited selector](/en-US/docs/Web/CSS/Privacy_and_the_:visited_selector) +- [Privacy and the :visited selector](/en-US/docs/Web/CSS/CSS_selectors/Privacy_and_the_visited_selector) - Link-related pseudo-classes: {{cssxref(":link")}}, {{cssxref(":active")}}, {{cssxref(":hover")}} diff --git a/files/en-us/web/css/_colon_where/index.md b/files/en-us/web/css/_colon_where/index.md index 9a1f2fba1e80473..8adac84d86b9a0b 100644 --- a/files/en-us/web/css/_colon_where/index.md +++ b/files/en-us/web/css/_colon_where/index.md @@ -20,7 +20,6 @@ ol { } /* Not applied to ol, because of lower specificity */ -/* stylelint-disable-next-line selector-pseudo-class-no-unknown */ :where(ol, ul, menu:unsupported) :where(ol, ul) { color: green; } diff --git a/files/en-us/web/css/_doublecolon_-webkit-search-results-button/index.md b/files/en-us/web/css/_doublecolon_-webkit-search-results-button/index.md index 41f334d8653ce69..fe392ba1af7d64a 100644 --- a/files/en-us/web/css/_doublecolon_-webkit-search-results-button/index.md +++ b/files/en-us/web/css/_doublecolon_-webkit-search-results-button/index.md @@ -9,7 +9,7 @@ browser-compat: css.selectors.-webkit-search-results-button {{CSSRef}}{{Non-standard_header}} -The **`::-webkit-search-results-button`** CSS [pseudo-element](/en-US/docs/Web/CSS/Pseudo-elements) represents a button (the "search results button") at the left edge of an {{HTMLElement("input")}} of `type="search"` which when clicked displays a menu which allows the user to choose from previous recent search queries. This button and pseudo-element are non-standard, supported only in WebKit and Blink, hence the vendor prefix. The search results button is only shown on search {{HTMLElement("input")}} elements that have a [`results`](/en-US/docs/Web/HTML/Element/input#results) attribute. +The **`::-webkit-search-results-button`** CSS [pseudo-element](/en-US/docs/Web/CSS/Pseudo-elements) represents a button (the "search results button") at the left edge of an {{HTMLElement("input")}} of `type="search"` which when clicked displays a menu which allows the user to choose from previous recent search queries. This button and pseudo-element are non-standard, supported only in WebKit and Blink, hence the vendor prefix. The search results button is only shown on search {{HTMLElement("input")}} elements that have a [`results`](/en-US/docs/Web/HTML/Reference/Elements/input#results) attribute. ## Syntax diff --git a/files/en-us/web/css/_doublecolon_after/index.md b/files/en-us/web/css/_doublecolon_after/index.md index 15716429a965cb3..f0e6332d8e03f46 100644 --- a/files/en-us/web/css/_doublecolon_after/index.md +++ b/files/en-us/web/css/_doublecolon_after/index.md @@ -44,9 +44,6 @@ a::after { </p> ``` -> [!NOTE] -> The pseudo-elements generated by `::before` and `::after` are inline boxes generated as if they were immediate children of the element on which they are applied, or the "originating element," and thus can not apply to _[replaced elements](/en-US/docs/Web/CSS/Replaced_element)_, such as {{htmlelement("img")}}, whose contents are replaced and not affected by the current document's styles. - ## Syntax ```css-nolint @@ -56,10 +53,18 @@ a::after { } ``` +## Description + +The `::after` pseudo-element is an inline box generated as an immediate child of the element it is associated with, or the "originating element". It is often used to add cosmetic content to an element via the {{CSSxRef("content")}} property, such as icons, quote marks, or other decoration. + +`::after` pseudo-elements can't be applied to _{{ glossary("replaced elements")}}_ such as {{htmlelement("img")}}, whose contents are determined by external resources and not affected by the current document's styles. + +An `::after` pseudo-element with a {{cssxref("display")}} value of `list-item` behaves like a list item, and can therefore generate a {{cssxref("::marker")}} pseudo-element just like an {{htmlelement("li")}} element. + If the [`content`](/en-US/docs/Web/CSS/content) property is not specified, has an invalid value, or has `normal` or `none` as a value, then the `::after` pseudo-element is not rendered. It behaves as if `display: none` is set. > [!NOTE] -> CSS introduced the `::after` notation (with two colons) to distinguish [pseudo-classes](/en-US/docs/Web/CSS/Pseudo-classes) from [pseudo-elements](/en-US/docs/Web/CSS/Pseudo-elements). For backward compatibility, browsers also accept `:after`, introduced earlier. +> The [Selectors Level 3](https://drafts.csswg.org/selectors-3/#gen-content) specification introduced the double-colon notation `::after` to distinguish [pseudo-classes](/en-US/docs/Web/CSS/Pseudo-classes) from [pseudo-elements](/en-US/docs/Web/CSS/Pseudo-elements). Browsers also accept single-colon notation `:after`, introduced in CSS2. ## Accessibility @@ -130,20 +135,20 @@ We can style text or images in the {{CSSxRef("content")}} property almost any wa ### Tooltips -This example uses `::after`, in conjunction with the [`attr()`](/en-US/docs/Web/CSS/attr) CSS expression and a `data-descr` [custom data attribute](/en-US/docs/Web/HTML/Global_attributes/data-*), to create tooltips. No JavaScript is required! +This example uses `::after`, in conjunction with the [`attr()`](/en-US/docs/Web/CSS/attr) CSS expression and a `data-description` [custom data attribute](/en-US/docs/Web/HTML/Reference/Global_attributes/data-*), to create tooltips. No JavaScript is required! -We can also support keyboard users with this technique, by adding a `tabindex` of `0` to make each `span` keyboard focusable, and using a CSS `:focus` selector. This shows how flexible `::before` and `::after` can be, though for the most accessible experience a semantic disclosure widget created in some other way (such as with [details and summary](/en-US/docs/Web/HTML/Element/details) elements) is likely to be more appropriate. +We can also support keyboard users with this technique, by adding a `tabindex` of `0` to make each `span` keyboard focusable, and using a CSS `:focus` selector. This shows how flexible `::before` and `::after` can be, though for the most accessible experience a semantic disclosure widget created in some other way (such as with [details and summary](/en-US/docs/Web/HTML/Reference/Elements/details) elements) is likely to be more appropriate. #### HTML ```html <p> Here we have some - <span tabindex="0" data-descr="collection of words and punctuation"> + <span tabindex="0" data-description="collection of words and punctuation"> text </span> with a few - <span tabindex="0" data-descr="small popups that appear when hovering"> + <span tabindex="0" data-description="small popups that appear when hovering"> tooltips</span >. </p> @@ -152,16 +157,16 @@ We can also support keyboard users with this technique, by adding a `tabindex` o #### CSS ```css -span[data-descr] { +span[data-description] { position: relative; text-decoration: underline; color: #00f; cursor: help; } -span[data-descr]:hover::after, -span[data-descr]:focus::after { - content: attr(data-descr); +span[data-description]:hover::after, +span[data-description]:focus::after { + content: attr(data-description); position: absolute; left: 0; top: 24px; @@ -180,6 +185,56 @@ span[data-descr]:focus::after { {{EmbedLiveSample('Tooltips', 450, 120)}} +### `::after::marker` nested pseudo-elements + +The `::after::marker` [nested pseudo-element](/en-US/docs/Web/CSS/Pseudo-elements#nesting_pseudo-elements) selects the list {{CSSxRef("::marker")}} of an `::after` pseudo-element that is itself a list item, that is, it has its {{CSSxRef("display")}} property set to `list-item`. + +In this demo, we generate extra list items before and after a list navigation menu using `::before` and `::after` (setting them to `display: list-item` so they behave like list items). We then use `ul::before::marker` and `ul::after::marker` to give their list markers a different color. + +#### HTML + +```html +<ul> + <li><a href="#">Introduction</a></li> + <li><a href="#">Getting started</a></li> + <li><a href="#">Understanding the basics</a></li> +</ul> +``` + +#### CSS + +```css +ul { + font-size: 1.5rem; + font-family: Arial, Helvetica, sans-serif; +} + +ul::before, +ul::after { + display: list-item; + color: orange; +} + +ul::before { + content: "Start"; +} + +ul::after { + content: "End"; +} + +ul::before::marker, +ul::after::marker { + color: red; +} +``` + +#### Result + +{{EmbedLiveSample('`::after::marker` nested pseudo-elements', 450, 200)}} + +While the list bullets of the three navigation items are generated because they are `<li>` elements, "Start" and "End" have been inserted via pseudo-elements and `::marker` is used to style their bullets. + ## Specifications {{Specifications}} diff --git a/files/en-us/web/css/_doublecolon_backdrop/index.md b/files/en-us/web/css/_doublecolon_backdrop/index.md index 2f7447d181b02b7..a42c5b4d902f13d 100644 --- a/files/en-us/web/css/_doublecolon_backdrop/index.md +++ b/files/en-us/web/css/_doublecolon_backdrop/index.md @@ -153,5 +153,5 @@ closeButton.addEventListener("click", () => { - {{cssxref(":fullscreen")}} pseudo-class - {{HTMLElement("dialog")}} HTML element - [Fullscreen API](/en-US/docs/Web/API/Fullscreen_API) -- [`popover`](/en-US/docs/Web/HTML/Global_attributes/popover) HTML global attribute +- [`popover`](/en-US/docs/Web/HTML/Reference/Global_attributes/popover) HTML global attribute - [Popover API](/en-US/docs/Web/API/Popover_API) diff --git a/files/en-us/web/css/_doublecolon_before/index.md b/files/en-us/web/css/_doublecolon_before/index.md index 53ecd076a2f3e5f..509c7dcd7dc71e7 100644 --- a/files/en-us/web/css/_doublecolon_before/index.md +++ b/files/en-us/web/css/_doublecolon_before/index.md @@ -40,9 +40,6 @@ a::before { </p> ``` -> [!NOTE] -> The pseudo-elements generated by `::before` and `::after` are boxes generated as if they were immediate children of the element on which they are applied, or the "originating element," and thus can not apply to _[replaced elements](/en-US/docs/Web/CSS/Replaced_element)_, such as {{htmlelement("img")}}, whose content is outside the scope of the CSS formatting model. - ## Syntax ```css-nolint @@ -52,9 +49,18 @@ a::before { } ``` +## Description + +The `::before` pseudo-element is an inline box generated as an immediate child of the element it is associated with, or the "originating element". It is often used to add cosmetic content to an element via the {{CSSxRef("content")}} property, such as icons, quote marks, or other decoration. + +`::before` pseudo-elements can't be applied to _{{ glossary("replaced elements")}}_ such as {{htmlelement("img")}}, whose contents are determined by external resources and not affected by the current document's styles. + +A `::before` pseudo-element with a {{cssxref("display")}} value of `list-item` behaves like a list item, and can therefore generate a {{cssxref("::marker")}} pseudo-element just like an {{htmlelement("li")}} element. + If the [`content`](/en-US/docs/Web/CSS/content) property is not specified, has an invalid value, or has `normal` or `none` as a value, then the `::before` pseudo-element is not rendered. It behaves as if `display: none` is set. -> **Note:** [Selectors Level 3](https://drafts.csswg.org/selectors-3/#gen-content) introduced the double-colon notation `::before` to distinguish [pseudo-classes](/en-US/docs/Web/CSS/Pseudo-classes) from [pseudo-elements](/en-US/docs/Web/CSS/Pseudo-elements). Browsers also accept single-colon notation `:before`, introduced in CSS2. +> [!NOTE] +> The [Selectors Level 3](https://drafts.csswg.org/selectors-3/#gen-content) specification introduced the double-colon notation `::before` to distinguish [pseudo-classes](/en-US/docs/Web/CSS/Pseudo-classes) from [pseudo-elements](/en-US/docs/Web/CSS/Pseudo-elements). Browsers also accept single-colon notation `:before`, introduced in CSS2. ## Accessibility @@ -62,7 +68,7 @@ Using a `::before` pseudo-element to add content is discouraged, as it is not re ## Examples -### Adding quotation marks +### Quotation marks One example of using `::before` pseudo-elements is to provide quotation marks. Here we use both `::before` and {{Cssxref("::after")}} to insert quotation characters. @@ -188,9 +194,9 @@ Here is the above code example running live. Note that there are no icons used, {{EmbedLiveSample('To-do_list', 400, 300)}} -### Special characters +### Unicode escape sequences -As this is CSS; not HTML, you can **not** use markup entities in content values. If you need to use a special character, and can not enter it literally into your CSS content string, use a unicode escape sequence, consisting of a backslash followed by the hexadecimal unicode value. +As generated content is CSS, not HTML, you **can't** use markup entities in content values. If you need to use a special character, and can't enter it literally into your CSS content string, use a unicode escape sequence. This consists of a backslash followed by the character's hexadecimal unicode value. #### HTML @@ -218,8 +224,8 @@ li[aria-current="step"] { font-weight: bold; } -li[aria-current="step"]::after { - content: " \21E6"; /* Hexadecimal for Unicode Leftwards white arrow*/ +li[aria-current="step"]::before { + content: "\21E8 "; /* Unicode escape sequence for "Rightwards White Arrow" */ display: inline; } ``` @@ -228,6 +234,56 @@ li[aria-current="step"]::after { {{EmbedLiveSample('Special_characters', 400, 200)}} +### `::before::marker` nested pseudo-elements + +The `::before::marker` [nested pseudo-element](/en-US/docs/Web/CSS/Pseudo-elements#nesting_pseudo-elements) selects the list {{CSSxRef("::marker")}} of an `::after` pseudo-element that is itself a list item, that is, it has its {{CSSxRef("display")}} property set to `list-item`. + +In this demo, we generate extra [list items](/en-US/docs/Web/HTML/Reference/Elements/li) before and after a list navigation menu using `::before` and `::after` (setting them to `display: list-item` so they behave like list items). We then use `ul::before::marker` and `ul::after::marker` to give their list markers a different color. + +#### HTML + +```html +<ul> + <li><a href="#">Introduction</a></li> + <li><a href="#">Getting started</a></li> + <li><a href="#">Understanding the basics</a></li> +</ul> +``` + +#### CSS + +```css +ul { + font-size: 1.5rem; + font-family: Arial, Helvetica, sans-serif; +} + +ul::before, +ul::after { + display: list-item; + color: orange; +} + +ul::before { + content: "Start"; +} + +ul::after { + content: "End"; +} + +ul::before::marker, +ul::after::marker { + color: red; +} +``` + +#### Result + +{{EmbedLiveSample('`::before::marker` nested pseudo-elements', 450, 200)}} + +While the list bullets of the three navigation items are generated because they are `<li>` elements, "Start" and "End" have been inserted via pseudo-elements and `::marker` is used to style their bullets. + ## Specifications {{Specifications}} diff --git a/files/en-us/web/css/_doublecolon_checkmark/index.md b/files/en-us/web/css/_doublecolon_checkmark/index.md new file mode 100644 index 000000000000000..30b76da18ec4138 --- /dev/null +++ b/files/en-us/web/css/_doublecolon_checkmark/index.md @@ -0,0 +1,135 @@ +--- +title: ::checkmark +slug: Web/CSS/::checkmark +page-type: css-pseudo-element +status: + - experimental +browser-compat: css.selectors.checkmark +--- + +{{CSSRef}}{{SeeCompatTable}} + +The **`::checkmark`** [CSS](/en-US/docs/Web/CSS) [pseudo-element](/en-US/docs/Web/CSS/Pseudo-elements) targets the checkmark placed inside the currently-selected {{htmlelement("option")}} element of a [customizable select element](/en-US/docs/Learn_web_development/Extensions/Forms/Customizable_select). It can be used to provide a visual indication of which option is selected. + +{{InteractiveExample("CSS Demo: ::checkmark")}} + +```html-nolint interactive-example +<label for="pet-select"> + Select pet: +</label> +<br /> +<select id="pet-select"> + <option value="cat">Cat</option> + <option value="dog">Dog</option> + <option value="chicken"> + Chicken + </option> +</select> +``` + +```css interactive-example +option::checkmark { + color: orange; + font-size: 1.5rem; +} + +select, +::picker(select) { + appearance: base-select; + width: 200px; +} + +select { + border: 2px solid #ddd; + background: #eee; + padding: 10px; +} + +::picker(select) { + border: none; +} + +option { + border: 2px solid #ddd; + background: #eee; + padding: 10px; +} + +option:first-of-type { + border-radius: 8px 8px 0 0; +} + +option:last-of-type { + border-radius: 0 0 8px 8px; +} + +option:nth-of-type(odd) { + background: #fff; +} + +option:not(option:last-of-type) { + border-bottom: none; +} +``` + +## Syntax + +```css-nolint +::checkmark { + /* ... */ +} +``` + +## Description + +The `::checkmark` pseudo-element targets the checkmark placed inside a [customizable select element's](/en-US/docs/Learn_web_development/Extensions/Forms/Customizable_select) currently-selected `<option>`. + +It is only available to target when the originating element has a picker and has base appearance set on it via the {{cssxref("appearance")}} property `base-select` value. Its generated box appears before any boxes generated by the {{cssxref("::before")}} pseudo-element. The icon can be customized using the {{cssxref("content")}} property. + +The `::checkmark` selector is useful for example if you want to hide the checkmark, use a custom icon, or adjust the checkmark's rendering position inside `<option>` elements. + +> [!NOTE] +> The `::checkmark` pseudo-element is not included in the accessibility tree, so any generated {{cssxref("content")}} set on it will not be announced by assistive technologies. You should still make sure that any new icon you set visually makes sense for its intended purpose. + +## Examples + +### Customizing the checkmark + +To opt-in to customizable select functionality, the `<select>` element and its picker both need to have an {{cssxref("appearance")}} value of `base-select` set on them: + +```css +select, +::picker(select) { + appearance: base-select; +} +``` + +Assuming [flexbox](/en-US/docs/Web/CSS/CSS_flexible_box_layout) is being used to lay out the `<option>` elements (which is true in **current implementations** of customizable selects), you could then move the checkmark from the start of the row to the end by setting an {{cssxref("order")}} value on it greater than `0`, and aligning it to the end of the row using an `auto` {{cssxref("margin-left")}} value (see [Alignment and auto margins](/en-US/docs/Web/CSS/CSS_box_alignment/Box_alignment_in_flexbox#alignment_and_auto_margins)). + +The value of the {{cssxref("content")}} property could also be set to a different emoji to change the displayed icon. + +```css +option::checkmark { + order: 1; + margin-left: auto; + content: "☑️"; +} +``` + +See [Styling the current selection checkmark](/en-US/docs/Learn_web_development/Extensions/Forms/Customizable_select#styling_the_current_selection_checkmark) for a full example that uses this code, along with a live example rendering. + +## Specifications + +{{Specifications}} + +## Browser compatibility + +{{Compat}} + +## See also + +- {{htmlelement("select")}}, {{htmlelement("option")}}, {{htmlelement("optgroup")}}, {{htmlelement("label")}}, {{htmlelement("button")}}, {{htmlelement("selectedcontent")}} +- {{cssxref("appearance")}} +- {{cssxref("::picker()", "::picker(select)")}}, {{cssxref("::picker-icon")}} +- {{cssxref(":open")}}, {{cssxref(":checked")}} +- [Customizable select elements](/en-US/docs/Learn_web_development/Extensions/Forms/Customizable_select) diff --git a/files/en-us/web/css/_doublecolon_column/index.md b/files/en-us/web/css/_doublecolon_column/index.md new file mode 100644 index 000000000000000..fad3a9208e775e8 --- /dev/null +++ b/files/en-us/web/css/_doublecolon_column/index.md @@ -0,0 +1,238 @@ +--- +title: ::column +slug: Web/CSS/::column +page-type: css-pseudo-element +status: + - experimental +browser-compat: css.selectors.column +--- + +{{CSSRef}}{{SeeCompatTable}} + +The **`::column`** [CSS](/en-US/docs/Web/CSS) [pseudo-element](/en-US/docs/Web/CSS/Pseudo-elements) represents the individual columns generated when a container is set to display its content in multiple columns via [CSS multi-column layout](/en-US/docs/Web/CSS/CSS_multicol_layout). The `::column` pseudo-element enables applying styles that do not affect the layout to these generated fragments. + +## Syntax + +```css-nolint +::column { + /* ... */ +} +``` + +## Description + +When CSS multi-column layout is used to lay out a container's content in multiple columns (for example, using the {{cssxref("column-count")}} property), `::column` pseudo-elements are generated to contain each individual column. + +The `::column` pseudo-element only accepts scroll snap properties that apply to elements inside a scroll container, including {{cssxref("scroll-margin")}}, {{cssxref("scroll-snap-align")}}, and {{cssxref("scroll-snap-stop")}}. + +The `::column` pseudo-element can have a {{cssxref("::scroll-marker")}} pseudo-element. Other pseudo-elements like {{cssxref("::before")}} and {{cssxref("::after")}} are not generated on `::column`. Applying `::column::scroll-marker` creates a marker for every column of the originating [scroll container](/en-US/docs/Glossary/Scroll_container), with the `::scroll-marker` pseudo-elements inheriting from the `::column` pseudo-element's originating element rather than the `::column` itself. + +This is useful for [CSS carousels](/en-US/docs/Web/CSS/CSS_overflow/CSS_carousels) — `::column` can be used to generate `::scroll-marker` pseudo-elements for each column, and set them as [snap targets](/en-US/docs/Glossary/Scroll_snap#snap_target) using [CSS scroll snap](/en-US/docs/Web/CSS/CSS_scroll_snap). + +While the styling that can be applied to `::column` is very limited, it may be expanded in the future. Any properties and values supported in the future will be limited to ones that do not affect layout. + +## Examples + +### Scrolling column layout + +This demo creates a responsive container that snaps each "page" of content into place. It uses the {{cssxref("columns")}} property and the `::columns` pseudo-element to create content columns that span the full width of their parent {{glossary("scroll container")}}, which can be scrolled horizontally. Each column contains one or more list items, which vary in number depending on the viewport width. + +#### HTML + +The HTML consists of an [unordered list](/en-US/docs/Web/HTML/Reference/Elements/ul), with each [list item](/en-US/docs/Web/HTML/Reference/Elements/li) containing some sample content: + +```html-nolint +<ul> +... + <li> + <h2>Item 1</h2> + </li> +... +</ul> +``` + +```html hidden live-sample___column-layout-example live-sample___carousel-example +<ul> + <li> + <h2>Item 1</h2> + </li> + <li> + <h2>Item 2</h2> + </li> + <li> + <h2>Item 3</h2> + </li> + <li> + <h2>Item 4</h2> + </li> + <li> + <h2>Item 5</h2> + </li> + <li> + <h2>Item 6</h2> + </li> + <li> + <h2>Item 7</h2> + </li> + <li> + <h2>Item 8</h2> + </li> + <li> + <h2>Item 9</h2> + </li> + <li> + <h2>Item 10</h2> + </li> + <li> + <h2>Item 11</h2> + </li> + <li> + <h2>Item 12</h2> + </li> + <li> + <h2>Item 13</h2> + </li> + <li> + <h2>Item 14</h2> + </li> + <li> + <h2>Item 15</h2> + </li> +</ul> +``` + +#### CSS + +The list is given a fixed {{cssxref("height")}} and a {{cssxref("width")}} of `100vw` to make it span the full width of the viewport. An {{cssxref("overflow-x")}} value of `scroll` is then set so that the content will scroll horizontally, and [CSS scroll snap](/en-US/docs/Web/CSS/CSS_scroll_snap) is used to snap to each item or "page" — a {{cssxref("scroll-snap-type")}} value of `x mandatory` is used to make the list into a [scroll snap container](/en-US/docs/Glossary/Scroll_snap#scroll_snap_container). Finally, a {{cssxref("columns")}} value of `1` is set to force the list contents to display as a single column. A {{cssxref("text-align")}} value of `center` is also applied, to align the content with the center of the list. + +```css hidden live-sample___column-layout-example live-sample___carousel-example +* { + box-sizing: border-box; +} + +body { + margin: 0; + font-family: Arial, Helvetica, sans-serif; +} +``` + +```css live-sample___column-layout-example live-sample___carousel-example +ul { + width: 100vw; + height: 300px; + padding: 10px; + + overflow-x: scroll; + scroll-snap-type: x mandatory; + + columns: 1; + text-align: center; +} +``` + +The list items are then styled: + +- A {{cssxref("display")}} value of `inline-block` is set to make the list items sit alongside one another and make the list scroll horizontally. +- A fixed {{cssxref("width")}} and {{cssxref("height")}} has been set on them. +- A `text-align` value of `left` is set on them to override the `text-align: center` set on the parent container, so the item content will be left-aligned. +- Every even-numbered list item is given a different background-color via {{cssxref(":nth-child()")}}, so that it is easier to see the scrolling effect. + +```css live-sample___column-layout-example live-sample___carousel-example +li { + list-style-type: none; + + display: inline-block; + height: 100%; + width: 200px; + text-align: left; + + background-color: #eee; + outline: 1px solid #ddd; + padding: 0 20px; + margin: 0 10px; +} + +li:nth-child(even) { + background-color: cyan; +} +``` + +The {{cssxref("scroll-snap-align")}} property is set on the `::column` pseudo-elements — which represent the content columns generated by the `columns` property — so that when scrolled, a column is snapped to be centered within the scroll container. + +```css live-sample___column-layout-example live-sample___carousel-example +ul::column { + scroll-snap-align: center; +} +``` + +#### Result + +{{EmbedLiveSample("column-layout-example", "100%", "400px")}} + +### Column-based carousel with scroll markers + +Expanding on the previous example, we will create scroll markers to enable direct navigation to different columns by applying a {{cssxref("scroll-marker-group")}} to the container and a {{cssxref("::scroll-marker")}} to each `::column` pseudo-element. The HTML remains unchanged. + +#### CSS + +We create a scroll marker group with the {{cssxref("scroll-marker-group")}} property, placing the group after all the content: + +```css live-sample___carousel-example +ul { + scroll-marker-group: after; +} +``` + +We then apply styles to the {{cssxref("::scroll-marker-group")}} pseudo-element to lay out the scroll markers in the center of the row with a `0.4em` gap between each one: + +```css live-sample___carousel-example +::scroll-marker-group { + display: flex; + gap: 0.4em; + place-content: center; +} +``` + +Finally, we use the {{cssxref("::scroll-marker")}} pseudo-element to create a round, transparent marker for each list item with a black border, then style the marker of the currently-scrolled element differently from the others, targeting the marker with the {{cssxref(":target-current")}} pseudo-class: + +```css live-sample___carousel-example +ul::column::scroll-marker { + content: ""; + width: 16px; + height: 16px; + background-color: transparent; + border: 2px solid black; + border-radius: 10px; +} + +ul::column::scroll-marker:target-current { + background-color: black; +} +``` + +#### Result + +{{EmbedLiveSample("carousel-example", "100%", "400px")}} + +Try pressing the scroll markers to jump straight to each page. Note how the current marker is highlighted so you can see where you are in the pagination. Also try tabbing to the scroll marker group, then use the cursor keys to cycle through each page. + +See [Creating CSS carousels](/en-US/docs/Web/CSS/CSS_overflow/CSS_carousels) for more carousel examples. + +## Specifications + +{{Specifications}} + +## Browser compatibility + +{{Compat}} + +## See also + +- {{cssxref("columns")}} +- {{cssxref("::scroll-marker")}} +- {{cssxref("::scroll-marker-group")}} +- {{cssxref(":target-current")}} +- [Creating CSS carousels](/en-US/docs/Web/CSS/CSS_overflow/CSS_carousels) +- [CSS multi-column layout](/en-US/docs/Web/CSS/CSS_multicol_layout) module +- [CSS overflow](/en-US/docs/Web/CSS/CSS_overflow) module +- [CSS Carousel Gallery](https://chrome.dev/carousel/) via chrome.dev (2025) diff --git a/files/en-us/web/css/_doublecolon_cue/index.md b/files/en-us/web/css/_doublecolon_cue/index.md index 776f83a12897ce8..122c59440026531 100644 --- a/files/en-us/web/css/_doublecolon_cue/index.md +++ b/files/en-us/web/css/_doublecolon_cue/index.md @@ -40,7 +40,7 @@ video::cue { The properties are applied to the entire set of cues as if they were a single unit. The only exception is that `background` and its longhand properties apply to each cue individually, to avoid creating boxes and obscuring unexpectedly large areas of the media. -In the example above, the `::cue(u)` selector selects all the [`<u>`](/en-US/docs/Web/HTML/Element/u) elements inside [the cue text](https://raw.githubusercontent.com/mdn/interactive-examples/main/live-examples/media/examples/friday.vtt). +In the example above, the `::cue(u)` selector selects all the [`<u>`](/en-US/docs/Web/HTML/Reference/Elements/u) elements inside [the cue text](https://raw.githubusercontent.com/mdn/interactive-examples/main/live-examples/media/examples/friday.vtt). ## Syntax diff --git a/files/en-us/web/css/_doublecolon_details-content/index.md b/files/en-us/web/css/_doublecolon_details-content/index.md index 49098d097f9fc7b..7b299aa0f2d1215 100644 --- a/files/en-us/web/css/_doublecolon_details-content/index.md +++ b/files/en-us/web/css/_doublecolon_details-content/index.md @@ -108,5 +108,5 @@ details[open]::details-content { ## See also -- [`<details>`](/en-US/docs/Web/HTML/Element/details) -- [`<summary>`](/en-US/docs/Web/HTML/Element/summary) +- [`<details>`](/en-US/docs/Web/HTML/Reference/Elements/details) +- [`<summary>`](/en-US/docs/Web/HTML/Reference/Elements/summary) diff --git a/files/en-us/web/css/_doublecolon_file-selector-button/index.md b/files/en-us/web/css/_doublecolon_file-selector-button/index.md index 6297d6dbf3229e8..48560ad53f7ba65 100644 --- a/files/en-us/web/css/_doublecolon_file-selector-button/index.md +++ b/files/en-us/web/css/_doublecolon_file-selector-button/index.md @@ -7,7 +7,7 @@ browser-compat: css.selectors.file-selector-button {{CSSRef}} -The **`::file-selector-button`** [CSS](/en-US/docs/Web/CSS) [pseudo-element](/en-US/docs/Web/CSS/Pseudo-elements) represents the button of an {{HTMLElement("input") }} of [`type="file"`](/en-US/docs/Web/HTML/Element/input/file). +The **`::file-selector-button`** [CSS](/en-US/docs/Web/CSS) [pseudo-element](/en-US/docs/Web/CSS/Pseudo-elements) represents the button of an {{HTMLElement("input") }} of [`type="file"`](/en-US/docs/Web/HTML/Reference/Elements/input/file). {{InteractiveExample("CSS Demo: ::file-selector-button", "tabbed-shorter")}} @@ -34,7 +34,9 @@ input::file-selector-button { ## Syntax ```css -selector::file-selector-button +::file-selector-button { + /* ... */ +} ``` ## Examples @@ -143,4 +145,4 @@ input[type="file"]::file-selector-button:hover { - [WebKit CSS extensions](/en-US/docs/Web/CSS/WebKit_Extensions) - [File and Directory Entries API](/en-US/docs/Web/API/File_and_Directory_Entries_API) -- [`<input type="file">`](/en-US/docs/Web/HTML/Element/input/file) +- [`<input type="file">`](/en-US/docs/Web/HTML/Reference/Elements/input/file) diff --git a/files/en-us/web/css/_doublecolon_first-letter/index.md b/files/en-us/web/css/_doublecolon_first-letter/index.md index 869e4c1cf18db1b..fce9109d1c8e7a8 100644 --- a/files/en-us/web/css/_doublecolon_first-letter/index.md +++ b/files/en-us/web/css/_doublecolon_first-letter/index.md @@ -7,7 +7,7 @@ browser-compat: css.selectors.first-letter {{CSSRef}} -The **`::first-letter`** [CSS](/en-US/docs/Web/CSS) [pseudo-element](/en-US/docs/Web/CSS/Pseudo-elements) applies styles to the first letter of the first line of a [block container](/en-US/docs/Web/CSS/Visual_formatting_model#block_containers), but only when not preceded by other content (such as images or inline tables). +The **`::first-letter`** [CSS](/en-US/docs/Web/CSS) [pseudo-element](/en-US/docs/Web/CSS/Pseudo-elements) applies styles to the first letter of the first line of a [block container](/en-US/docs/Web/CSS/CSS_display/Visual_formatting_model#block_containers), but only when not preceded by other content (such as images or inline tables). {{InteractiveExample("CSS Demo: ::first-letter", "tabbed-shorter")}} diff --git a/files/en-us/web/css/_doublecolon_first-line/index.md b/files/en-us/web/css/_doublecolon_first-line/index.md index a03b48c0082f79b..66c1e04c017b1eb 100644 --- a/files/en-us/web/css/_doublecolon_first-line/index.md +++ b/files/en-us/web/css/_doublecolon_first-line/index.md @@ -7,7 +7,7 @@ browser-compat: css.selectors.first-line {{CSSRef}} -The **`::first-line`** [CSS](/en-US/docs/Web/CSS) [pseudo-element](/en-US/docs/Web/CSS/Pseudo-elements) applies styles to the first line of a [block container](/en-US/docs/Web/CSS/Visual_formatting_model#block_containers). +The **`::first-line`** [CSS](/en-US/docs/Web/CSS) [pseudo-element](/en-US/docs/Web/CSS/Pseudo-elements) applies styles to the first line of a [block container](/en-US/docs/Web/CSS/CSS_display/Visual_formatting_model#block_containers). {{InteractiveExample("CSS Demo: ::first-line", "tabbed-shorter")}} diff --git a/files/en-us/web/css/_doublecolon_grammar-error/index.md b/files/en-us/web/css/_doublecolon_grammar-error/index.md index 0dabbba6f46f3a0..fdeabe7ddd70a31 100644 --- a/files/en-us/web/css/_doublecolon_grammar-error/index.md +++ b/files/en-us/web/css/_doublecolon_grammar-error/index.md @@ -68,3 +68,4 @@ In this example, eventual supporting browsers should highlight any flagged gramm ## See also - {{cssxref("::spelling-error")}} +- {{cssxref("text-decoration-line")}} diff --git a/files/en-us/web/css/_doublecolon_part/index.md b/files/en-us/web/css/_doublecolon_part/index.md index 31121966579d0f4..a66ad9d7af60c90 100644 --- a/files/en-us/web/css/_doublecolon_part/index.md +++ b/files/en-us/web/css/_doublecolon_part/index.md @@ -7,7 +7,7 @@ browser-compat: css.selectors.part {{CSSRef}} -The **`::part`** [CSS](/en-US/docs/Web/CSS) [pseudo-element](/en-US/docs/Web/CSS/Pseudo-elements) represents any element within a [shadow tree](/en-US/docs/Web/API/Web_components/Using_shadow_DOM) that has a matching [`part`](/en-US/docs/Web/HTML/Global_attributes/part) attribute. +The **`::part`** [CSS](/en-US/docs/Web/CSS) [pseudo-element](/en-US/docs/Web/CSS/Pseudo-elements) represents any element within a [shadow tree](/en-US/docs/Web/API/Web_components/Using_shadow_DOM) that has a matching [`part`](/en-US/docs/Web/HTML/Reference/Global_attributes/part) attribute. ```css custom-element::part(foo) { @@ -17,13 +17,13 @@ custom-element::part(foo) { ## Description -The global [`part`](/en-US/docs/Web/HTML/Global_attributes/part) attribute makes a shadow tree element visible to its parent DOM. The part names declared using the `part` attribute are used as the parameter of the `::part()` pseudo-element. In this way, you can apply CSS styles to elements in the shadow tree from outside of it. +The global [`part`](/en-US/docs/Web/HTML/Reference/Global_attributes/part) attribute makes a shadow tree element visible to its parent DOM. The part names declared using the `part` attribute are used as the parameter of the `::part()` pseudo-element. In this way, you can apply CSS styles to elements in the shadow tree from outside of it. Part names are similar to CSS classes: multiple elements can have the same part name, and a single element can have multiple part names. All part names used in `::part()` pseudo-element must be present in the `part` value declared on the shadow tree element but the order of the part names doesn't matter, i.e., the selectors `::part(tab active)` and `::part(active tab)` are the same. -The `::part()` pseudo-element is only visible to the parent DOM. This means that when a shadow tree is nested, the parts are not visible to any ancestors other than the direct parent. The [`exportparts`](/en-US/docs/Web/HTML/Global_attributes/exportparts) attribute solves this limitation by explicitly exporting already defined `part` names, making them globally stylable. +The `::part()` pseudo-element is only visible to the parent DOM. This means that when a shadow tree is nested, the parts are not visible to any ancestors other than the direct parent. The [`exportparts`](/en-US/docs/Web/HTML/Reference/Global_attributes/exportparts) attribute solves this limitation by explicitly exporting already defined `part` names, making them globally stylable. -[Pseudo-classes](/en-US/docs/Web/CSS/Pseudo-classes) (such as `::part(label):hover`) can be appended to the `::part()` selector, but [structural pseudo-classes](/en-US/docs/Web/CSS/Pseudo-classes#tree-structural_pseudo-classes) that match based on tree information (such as `:empty`), rather than local element information (such as `:last-child`), cannot be appended. +[Pseudo-classes](/en-US/docs/Web/CSS/Pseudo-classes) (such as `::part(label):hover`) can be appended to the `::part()` selector, but [structural pseudo-classes](/en-US/docs/Web/CSS/Pseudo-classes#tree-structural_pseudo-classes) that match based on tree information, such as `:empty` and `:last-child`, cannot be appended. Additional pseudo-elements, such as `::before`, can be appended to the `::part()` selector, but additional `::part()` element can't be appended. For example, `::part(confirm-button)::part(active)` never matches anything, i.e, it is not the same as `::part(confirm-button active)`. This is because doing so would expose more structural information than is intended. @@ -106,7 +106,7 @@ globalThis.customElements.define( ## See also -- [`part`](/en-US/docs/Web/HTML/Global_attributes/part) attribute +- [`part`](/en-US/docs/Web/HTML/Reference/Global_attributes/part) attribute - {{CSSxRef(":state",":state()")}} pseudo-class function -- [`exportparts`](/en-US/docs/Web/HTML/Global_attributes/exportparts) attribute +- [`exportparts`](/en-US/docs/Web/HTML/Reference/Global_attributes/exportparts) attribute - [CSS shadow parts](/en-US/docs/Web/CSS/CSS_shadow_parts) module diff --git a/files/en-us/web/css/_doublecolon_picker-icon/index.md b/files/en-us/web/css/_doublecolon_picker-icon/index.md new file mode 100644 index 000000000000000..b789f36ab70fd68 --- /dev/null +++ b/files/en-us/web/css/_doublecolon_picker-icon/index.md @@ -0,0 +1,79 @@ +--- +title: ::picker-icon +slug: Web/CSS/::picker-icon +page-type: css-pseudo-element +status: + - experimental +browser-compat: css.selectors.picker-icon +--- + +{{CSSRef}}{{SeeCompatTable}} + +The **`::picker-icon`** [CSS](/en-US/docs/Web/CSS) [pseudo-element](/en-US/docs/Web/CSS/Pseudo-elements) targets the picker icon inside form controls that have an icon associated with them. In the case of a [customizable select element](/en-US/docs/Learn_web_development/Extensions/Forms/Customizable_select), it selects the arrow icon shown on the `<select>` element that points down when it is closed. + +## Syntax + +```css-nolint +::picker-icon { + /* ... */ +} +``` + +## Description + +The `::picker-icon` pseudo-element targets the picker icon of form controls, that is, the icon shown on the control button. It is only available to target when the originating element has a picker and has base appearance set on it via the {{cssxref("appearance")}} property `base-select` value. Its generated box appears after any boxes generated by the {{cssxref("::after")}} pseudo-element, with the icon specified in default browser stylesheet; you can customize it using the {{cssxref("content")}} property. + +The `::picker-icon` selector can be used to select the down-facing arrow on the inline-end side of a [customizable select element](/en-US/docs/Learn_web_development/Extensions/Forms/Customizable_select). This is useful for example if you want to customize the color or size of the icon, use a different icon (using {{cssxref("content")}} or [SVG](/en-US/docs/Web/SVG)), or animate it when the picker is opened and closed. + +Selecting customizable `<select>` picker icons is the only current use case for `::picker-icon`, but more may be added in the future. + +> [!NOTE] +> The `::picker-icon` pseudo-element is not included in the accessibility tree, so any generated {{cssxref("content")}} set on it will not be announced by assistive technologies. You should still make sure that any new icon you set visually makes sense for its intended purpose. + +## Examples + +### Animating the picker icon + +To opt-in to customizable select functionality, the `<select>` element and its picker both need to have an {{cssxref("appearance")}} value of `base-select` set on them: + +```css +select, +::picker(select) { + appearance: base-select; +} +``` + +You could then, for example, target the `::picker-icon` and give it a custom {{cssxref("color")}} and a {{cssxref("transition")}} so that changes to its {{cssxref("rotate")}} property are smoothly animated: + +```css +select::picker-icon { + color: #999; + transition: 0.4s rotate; +} +``` + +In the next rule, `::picker-icon` is combined with the {{cssxref(":open")}} pseudo-class — which targets the icon only when the picker is open — transitioning it to a `rotate` value of `180deg` when the `<select>` is opened. + +```css +select:open::picker-icon { + rotate: 180deg; +} +``` + +See [Styling the picker icon](/en-US/docs/Learn_web_development/Extensions/Forms/Customizable_select#styling_the_picker_icon) for a full example that uses this code, along with a live example rendering. + +## Specifications + +{{Specifications}} + +## Browser compatibility + +{{Compat}} + +## See also + +- {{htmlelement("select")}}, {{htmlelement("option")}}, {{htmlelement("optgroup")}}, {{htmlelement("label")}}, {{htmlelement("button")}}, {{htmlelement("selectedcontent")}} +- {{cssxref("appearance")}} +- {{cssxref("::picker()", "::picker(select)")}}, {{cssxref("::checkmark")}} +- {{cssxref(":open")}}, {{cssxref(":checked")}} +- [Customizable select elements](/en-US/docs/Learn_web_development/Extensions/Forms/Customizable_select) diff --git a/files/en-us/web/css/_doublecolon_picker/index.md b/files/en-us/web/css/_doublecolon_picker/index.md new file mode 100644 index 000000000000000..56f84f07bb03f2e --- /dev/null +++ b/files/en-us/web/css/_doublecolon_picker/index.md @@ -0,0 +1,107 @@ +--- +title: ::picker() +slug: Web/CSS/::picker +page-type: css-pseudo-element +status: + - experimental +browser-compat: css.selectors.picker +--- + +{{CSSRef}}{{SeeCompatTable}} + +The **`::picker()`** [CSS](/en-US/docs/Web/CSS) [pseudo-element](/en-US/docs/Web/CSS/Pseudo-elements) targets the picker part of an element, for example the drop-down picker of a [customizable select element](/en-US/docs/Learn_web_development/Extensions/Forms/Customizable_select). + +## Syntax + +```css-nolint +::picker(<ident>) { + /* ... */ +} +``` + +### Parameters + +- {{cssxref("ident")}} + - : A string representing the element whose picker you want to target. The following values are available: + - `select` + - : The drop-down picker of customizable select elements. + +## Description + +The `::picker()` pseudo-element targets the picker part of a form control, that is, the pop-up part that appears to allow you to make a selection when you press the control button. It is only available to target when the originating element has a picker and has base appearance set on it via the {{cssxref("appearance")}} property `base-select` value. + +The `::picker(select)` selector targets all descendants of customizable `<select>` element except for the first `<button>` child; these descendants are grouped together by the browser and rendered as the picker. The first `<button>` child represents the control button that opens the picker when pressed. + +This allows you to target all of the picker contents as a single entity, for example if you want to customize its border, animate it when it appears and disappears, or position it somewhere different to the default position. Our [customizable select elements](/en-US/docs/Learn_web_development/Extensions/Forms/Customizable_select) guide shows many examples of `::picker(select)` usage. + +### Picker popover behavior + +The `<select>` element and the picker have an implicit invoker/popover relationship assigned to them automatically, as specified by the [Popover API](/en-US/docs/Web/API/Popover_API). See [Using the Popover API](/en-US/docs/Web/API/Popover_API/Using) for more details of popover behavior, and see [Animating the picker drop-down using popover states](/en-US/docs/Learn_web_development/Extensions/Forms/Customizable_select#animating_the_picker_using_popover_states) for a typical use case allowed by the implicit popover association. + +### Picker anchor positioning + +A further side-effect of the implicit invoker/popover relationship mentioned above is that the `<select>` element and the picker also have an implicit anchor reference, meaning that the picker is automatically associated with the select via [CSS anchor positioning](/en-US/docs/Web/CSS/CSS_anchor_positioning). This has several advantages, most notably: + +- The browser default styles position the picker relative to the button (the anchor) and you can customize this position as explained in [Positioning elements relative to their anchor](/en-US/docs/Web/CSS/CSS_anchor_positioning/Using#positioning_elements_relative_to_their_anchor). For reference, the related default styles are as follows: + + ```css + inset: auto; + margin: 0; + min-inline-size: anchor-size(self-inline); + min-block-size: 1lh; + /* Go to the edge of the viewport, and add scrollbars if needed. */ + max-block-size: stretch; + overflow: auto; + /* Below and span-right, by default. */ + position-area: block-end span-inline-end; + ``` + +- The browser default styles also define some position-try fallbacks that reposition the picker if it is in danger of overflowing the viewport. Position-try fallbacks are explained in [Handling overflow: try fallbacks and conditional hiding](/en-US/docs/Web/CSS/CSS_anchor_positioning/Try_options_hiding). For reference, the related default fallback styles are as follows: + + ```css + position-try-order: most-block-size; + position-try-fallbacks: + /* First try above and span-right, */ + /* then below but span-left, */ + /* then above and span-left. */ + block-start span-inline-end, + block-end span-inline-start, + block-start span-inline-start; + ``` + +## Examples + +### Basic custom select usage + +To opt-in to the custom select functionality and minimal browser base styles (and remove the OS-provided styling), the `<select>` element and its picker both need to have an {{cssxref("appearance")}} value of `base-select` set on them: + +```css +select, +::picker(select) { + appearance: base-select; +} +``` + +You could then, for example, remove the picker's default black {{cssxref("border")}}: + +```css +::picker(select) { + border: none; +} +``` + +## Specifications + +{{Specifications}} + +## Browser compatibility + +{{Compat}} + +## See also + +- {{htmlelement("select")}}, {{htmlelement("option")}}, {{htmlelement("optgroup")}}, {{htmlelement("label")}}, {{htmlelement("button")}}, {{htmlelement("selectedcontent")}} +- {{cssxref("appearance")}} +- {{cssxref("::picker-icon")}}, {{cssxref("::checkmark")}} +- {{cssxref(":open")}}, {{cssxref(":checked")}} +- [Customizable select elements](/en-US/docs/Learn_web_development/Extensions/Forms/Customizable_select) diff --git a/files/en-us/web/css/_doublecolon_placeholder/index.md b/files/en-us/web/css/_doublecolon_placeholder/index.md index c742a4279695ed2..c2443ccde926370 100644 --- a/files/en-us/web/css/_doublecolon_placeholder/index.md +++ b/files/en-us/web/css/_doublecolon_placeholder/index.md @@ -7,7 +7,7 @@ browser-compat: css.selectors.placeholder {{CSSRef}} -The **`::placeholder`** [CSS](/en-US/docs/Web/CSS) [pseudo-element](/en-US/docs/Web/CSS/Pseudo-elements) represents the [placeholder text](/en-US/docs/Web/HTML/Element/input#placeholder) in an {{HTMLElement("input")}} or {{HTMLElement("textarea")}} element. +The **`::placeholder`** [CSS](/en-US/docs/Web/CSS) [pseudo-element](/en-US/docs/Web/CSS/Pseudo-elements) represents the [placeholder text](/en-US/docs/Web/HTML/Reference/Elements/input#placeholder) in an {{HTMLElement("input")}} or {{HTMLElement("textarea")}} element. {{InteractiveExample("CSS Demo: ::placeholder", "tabbed-shorter")}} @@ -61,14 +61,14 @@ It is important to ensure that the contrast ratio between the color of the place Color contrast ratio is determined by comparing the luminosity of the placeholder text and the input background color values. In order to meet current [Web Content Accessibility Guidelines (WCAG)](https://www.w3.org/WAI/standards-guidelines/wcag/), a ratio of 4.5:1 is required for text content and 3:1 for larger text such as headings. Large text is defined as 18.66px and bold or larger, or 24px or larger. - [WebAIM: Color Contrast Checker](https://webaim.org/resources/contrastchecker/) -- [MDN Understanding WCAG, Guideline 1.4 explanations](/en-US/docs/Web/Accessibility/Understanding_WCAG/Perceivable#guideline_1.4_make_it_easier_for_users_to_see_and_hear_content_including_separating_foreground_from_background) +- [MDN Understanding WCAG, Guideline 1.4 explanations](/en-US/docs/Web/Accessibility/Guides/Understanding_WCAG/Perceivable#guideline_1.4_make_it_easier_for_users_to_see_and_hear_content_including_separating_foreground_from_background) - [Understanding Success Criterion 1.4.3 | W3C Understanding WCAG 2.0](https://www.w3.org/TR/UNDERSTANDING-WCAG20/visual-audio-contrast-contrast.html) #### Usability Placeholder text with sufficient color contrast may be interpreted as entered input. Placeholder text will also disappear when a person enters content into an {{htmlelement("input")}} element. Both of these circumstances can interfere with successful form completion, especially for people with cognitive concerns. -An alternate approach to providing placeholder information is to include it outside of the input in close visual proximity, then use [`aria-describedby`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-describedby) to programmatically associate the {{HTMLElement("input")}} with its hint. +An alternate approach to providing placeholder information is to include it outside of the input in close visual proximity, then use [`aria-describedby`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-describedby) to programmatically associate the {{HTMLElement("input")}} with its hint. With this implementation, the hint content is available even if information is entered into the input field, and the input appears free of preexisting input when the page is loaded. Most screen reading technology will use `aria-describedby` to read the hint after the input's label text is announced, and the person using the screen reader can mute it if they find the extra information unnecessary. @@ -90,7 +90,7 @@ Placeholder text will appear with the same styling as user-entered text content ### Labels -Placeholders are not a replacement for the {{htmlelement("label")}} element. Without a label that has been programmatically associated with an input using a combination of the [`for`](/en-US/docs/Web/HTML/Element/label#for) and [`id`](/en-US/docs/Web/HTML/Global_attributes/id) attributes, assistive technology such as screen readers cannot parse {{htmlelement("input")}} elements. +Placeholders are not a replacement for the {{htmlelement("label")}} element. Without a label that has been programmatically associated with an input using a combination of the [`for`](/en-US/docs/Web/HTML/Reference/Elements/label#for) and [`id`](/en-US/docs/Web/HTML/Reference/Global_attributes/id) attributes, assistive technology such as screen readers cannot parse {{htmlelement("input")}} elements. - [Placeholders in Form Fields Are Harmful — Nielsen Norman Group](https://www.nngroup.com/articles/form-design-placeholders/) diff --git a/files/en-us/web/css/_doublecolon_scroll-button/index.md b/files/en-us/web/css/_doublecolon_scroll-button/index.md new file mode 100644 index 000000000000000..f7a47931a35e2b4 --- /dev/null +++ b/files/en-us/web/css/_doublecolon_scroll-button/index.md @@ -0,0 +1,229 @@ +--- +title: ::scroll-button() +slug: Web/CSS/::scroll-button +page-type: css-pseudo-element +status: + - experimental +browser-compat: css.selectors.scroll-button +--- + +{{CSSRef}}{{SeeCompatTable}} + +The **`::scroll-button()`** [CSS](/en-US/docs/Web/CSS) [pseudo-element](/en-US/docs/Web/CSS/Pseudo-elements) represents a button for controlling the scrolling of a {{glossary("scroll container")}}. They are generated on scroll containers when their {{cssxref("content")}} value is not `none`. The direction of the scrolling is determined by the parameter value. + +## Syntax + +```css-nolint +::scroll-button(<scroll-button-direction>) { + /* ... */ +} +``` + +### Parameters + +- `<scroll-button-direction>` + + - : A value representing which direction of scroll button you want to select. The following values are available: + + - `*` + - : Selects all the originating element's scroll buttons, allowing styles to be applied to each of them in a single rule. + - `down` + - : Selects the button that will scroll the content downward. + - `left` + - : Selects the button that will scroll the content left. + - `right` + - : Selects the button that will scroll the content right. + - `up` + - : Selects the button that will scroll the content upward. + - `block-end` + - : Selects the button that will scroll the content in the block-end direction. + - `block-start` + - : Selects the button that will scroll the content in the block-start direction. + - `inline-end` + - : Selects the button that will scroll the content in the inline-end direction. + - `inline-start` + - : Selects the button that will scroll the content in the inline-start direction. + + The specification also defines two other values — `next` and `prev` — but these are not currently supported in any browser. + +## Description + +The `::scroll-button()` pseudo-elements are generated inside a {{glossary("scroll container")}} only when their {{cssxref("content")}} properties are set to a value other than `none`. They are generated as siblings of the scroll container's child DOM elements, immediately preceding them and any {{cssxref("::scroll-marker-group")}} generated on the container. + +You can generate up to four scroll buttons per scroll container, which will scroll the content towards the start and end of the block and inline axes. The selector's argument specifies which scrolling direction is selected. You can also specify a value of `*` to target all of the `::scroll-button()` pseudo-elements, providing styles to all the buttons in a single rule. + +The generated buttons behave just like regular {{htmlelement("button")}} elements, including sharing their default browser styles. They are focusable, accessible, and can be activated like regular buttons. When a scroll button is pressed, the scroll container's content is scrolled in the specified direction by one "page," or approximately the dimension of the scroll container, similar to pressing <kbd>PgUp</kbd> and <kbd>PgDn</kbd> keys. + +The recommendation is to set up [CSS scroll snapping](/en-US/docs/Web/CSS/CSS_scroll_snap) on the scroll container and set each separate item of content you want to scroll to as a [snap target](/en-US/docs/Glossary/Scroll_snap#snap_target). This being the case, activating a scroll button will scroll the content to the snap target that is one "page" away. While the scroll buttons will work without scroll snapping, you might not get the desired effect. + +When it is not possible to scroll any further in a particular scroll button's scrolling direction, the button is automatically disabled, otherwise it is enabled. You can style the scroll buttons in their enabled and disabled states using the {{cssxref(":enabled")}} and {{cssxref(":disabled")}} pseudo-classes. + +## Examples + +See [Creating CSS carousels](/en-US/docs/Web/CSS/CSS_overflow/CSS_carousels) for more carousel examples. + +### Creating scroll buttons + +In this example, we demonstrate how to create scroll buttons on a CSS carousel. + +#### HTML + +We have a basic HTML {{htmlelement("ul")}} list with several {{htmlelement("li")}} list items. + +```html live-sample___creating-scroll-buttons live-sample___positioning-scroll-buttons +<ul> + <li>Item 1</li> + <li>Item 2</li> + <li>Item 3</li> + <li>Item 4</li> + <li>Item 5</li> + <li>Item 6</li> + <li>Item 7</li> + <li>Item 8</li> +</ul> +``` + +#### CSS + +##### Styling the carousel + +We convert our `<ul>` into a carousel by setting the {{cssxref("display")}} to `flex`, creating a single, non-wrapping row of `<li>` elements. The {{cssxref("overflow-x")}} property is set to `auto`, meaning if the items overflow their container on the x-axis, the content will scroll horizontally. We then convert the `<ul>` into a [scroll-snap container](/en-US/docs/Glossary/Scroll_snap#scroll_snap_container), ensuring that items always snap into place when the container is scrolled with a {{cssxref("scroll-snap-type")}} value of `mandatory`. + +```css live-sample___creating-scroll-buttons live-sample___positioning-scroll-buttons +ul { + display: flex; + gap: 4vw; + padding-left: 0; + overflow-x: auto; + overscroll-behavior-x: contain; + scroll-snap-type: x mandatory; +} +``` + +Next, we style the `<li>` elements, using the {{cssxref("flex")}} property to make them 100% of the width of the container. The {{cssxref("scroll-snap-align")}} value of `start` causes the left-hand side of the left-most visible item to snap to the left edge of the container when the content is scrolled. + +```css live-sample___creating-scroll-buttons live-sample___positioning-scroll-buttons +li { + list-style-type: none; + background-color: #eee; + flex: 0 0 100%; + height: 100px; + padding-top: 20px; + scroll-snap-align: start; + text-align: center; +} +``` + +##### Creating the scroll buttons + +First, all scroll buttons are targeted with some rudimentary styles, as well as styling based on different states. It is important to set {{cssxref(":focus")}} styles for keyboard users. Also, as scroll buttons are automatically set to [`disabled`](/en-US/docs/Web/HTML/Reference/Attributes/disabled) when no more scrolling can occur in that direction, we use the {{cssxref(":disabled")}} pseudo-class to target this state. + +```css live-sample___creating-scroll-buttons live-sample___positioning-scroll-buttons +ul::scroll-button(*) { + border: 0; + font-size: 2rem; + background: none; + color: rgb(0 0 0 / 0.7); + cursor: pointer; +} + +ul::scroll-button(*):hover, +ul::scroll-button(*):focus { + color: rgb(0 0 0 / 1); +} + +ul::scroll-button(*):active { + translate: 1px 1px; +} + +ul::scroll-button(*):disabled { + color: rgb(0 0 0 / 0.2); + cursor: unset; +} +``` + +> [!NOTE] +> We also set a {{cssxref("cursor")}} value of `pointer` on the scroll buttons to make it more obvious that they can be interacted with (an improvement for both general [UX](/en-US/docs/Glossary/UX) and [cognitive accessibility](/en-US/docs/Web/Accessibility/Guides/Cognitive_accessibility)), unsetting it when the scroll buttons are `:disabled`. + +Next, an appropriate icon is set on the left and right scroll buttons via the `content` property, which is also what causes the scroll buttons to be generated: + +```css live-sample___creating-scroll-buttons live-sample___positioning-scroll-buttons +ul::scroll-button(left) { + content: "◄"; +} + +ul::scroll-button(right) { + content: "►"; +} +``` + +We don't need to set [alternative text](/en-US/docs/Web/CSS/content#alternative_text_string_counter) for the icons on the `content` as the browser takes care of providing appropriate {{glossary("accessible name", "accessible names")}} automatically. + +#### Result + +{{EmbedLiveSample("creating-scroll-buttons", '', '220')}} + +Note how the scroll buttons are created at the bottom left on the carousel. Try pressing them to see how they cause the content to be scrolled. + +### Positioning the scroll buttons + +The previous example works, but the buttons are not ideally placed. In this section, we will add some CSS to position them using [anchor positioning](/en-US/docs/Web/CSS/CSS_anchor_positioning). + +#### CSS + +First of all, a reference {{cssxref("anchor-name")}} is set on the `<ul>` to define it as a named anchor. Next, each scroll button has its {{cssxref("position")}} set to `absolute` and its {{cssxref("position-anchor")}} property set to the list's `anchor-name`, to [associate the two together](/en-US/docs/Web/CSS/CSS_anchor_positioning/Using#associating_anchor_and_positioned_elements). + +```css live-sample___positioning-scroll-buttons +ul { + anchor-name: --myCarousel; +} + +ul::scroll-button(*) { + position: absolute; + position-anchor: --myCarousel; +} +``` + +To actually position each scroll button, we first set an {{cssxref("align-self")}} value of `anchor-center` on both of them, to center them vertically on the carousel: + +```css live-sample___positioning-scroll-buttons +ul::scroll-button(*) { + align-self: anchor-center; +} +``` + +We then set values on their {{glossary("inset properties")}} to handle the horizontal positioning. We use {{cssxref("anchor()")}} functions to position the specified sides of the buttons relative to the sides of the carousel. In each case, the {{cssxref("calc()")}} function is used to add some space between the button edge and the carousel edge. For example, the right-hand edge of the left scroll button is positioned 45 pixels to the right of the carousel's left-hand edge. + +```css live-sample___positioning-scroll-buttons +ul::scroll-button(left) { + right: calc(anchor(left) - 45px); +} + +ul::scroll-button(right) { + left: calc(anchor(right) - 45px); +} +``` + +#### Result + +{{EmbedLiveSample("positioning-scroll-buttons", '', '220')}} + +## Specifications + +{{Specifications}} + +## Browser compatibility + +{{Compat}} + +## See also + +- {{cssxref("scroll-marker-group")}} +- {{cssxref("::scroll-marker-group")}} +- {{cssxref("::scroll-marker")}} +- {{cssxref("::column")}} +- {{cssxref(":target-current")}} +- [Creating CSS carousels](/en-US/docs/Web/CSS/CSS_overflow/CSS_carousels) +- [CSS overflow](/en-US/docs/Web/CSS/CSS_overflow) module +- [CSS anchor positioning](/en-US/docs/Web/CSS/CSS_anchor_positioning) module +- [CSS Carousel Gallery](https://chrome.dev/carousel/) via chrome.dev (2025) diff --git a/files/en-us/web/css/_doublecolon_scroll-marker-group/index.md b/files/en-us/web/css/_doublecolon_scroll-marker-group/index.md new file mode 100644 index 000000000000000..b0258061997d29a --- /dev/null +++ b/files/en-us/web/css/_doublecolon_scroll-marker-group/index.md @@ -0,0 +1,194 @@ +--- +title: ::scroll-marker-group +slug: Web/CSS/::scroll-marker-group +page-type: css-pseudo-element +status: + - experimental +browser-compat: css.selectors.scroll-marker-group +--- + +{{CSSRef}}{{SeeCompatTable}} + +The **`::scroll-marker-group`** [CSS](/en-US/docs/Web/CSS) [pseudo-element](/en-US/docs/Web/CSS/Pseudo-elements) is generated inside a {{glossary("scroll container")}} and contains any {{cssxref("::scroll-marker")}} pseudo-elements generated on descendants of the scroll container. + +## Syntax + +```css-nolint +::scroll-marker-group { + /* ... */ +} +``` + +## Description + +A scroll container's **`::scroll-marker-group`** pseudo-element represents a **scroll marker group**. This is a container that automatically contains any {{cssxref("::scroll-marker")}} pseudo-elements generated on itself or its descendants. This allows them to be positioned and laid out as a group, and is typically used when creating a CSS carousel to provide a scroll position indicator. The individual scroll markers can be used to navigate to their associated content items. + +The scroll container must have its {{cssxref("scroll-marker-group")}} property set to a non-`none` value for the `::scroll-marker-group` pseudo-element to be generated. The {{cssxref("scroll-marker-group")}} value determines where the scroll marker group appears in the carousel's tab order and layout box order (but not DOM structure) — `before` puts it at the start, while `after` puts it at the end. + +It is a best practice to match the visual rendering position of the scroll marker group with the tab order. When positioning the group at the start of the content, put it at the beginning of the tab order using `before`. When positioning the group at the end of the content, put it at the end of the tab order using `after`. + +Accessibility-wise, the scroll marker group and contained scroll markers are rendered with [`tablist`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/tablist_role)/[`tab`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/tab_role) semantics. When you <kbd>Tab</kbd> to the group, it behaves like a single item (that is, another press of the <kbd>Tab</kbd> key will move past the group to the next item), and you can move between the different scroll markers using the left and right (or up and down) cursor keys. + +## Examples + +See [Creating CSS carousels](/en-US/docs/Web/CSS/CSS_overflow/CSS_carousels) for other examples that use the `::scroll-marker` pseudo-element. + +### Creating carousel scroll markers + +This demo is a carousel of single pages, with each item taking up the full page. We have included scroll markers to enable the user to navigate to any page with the click of a marker. + +#### HTML + +The HTML consists of an [unordered list](/en-US/docs/Web/HTML/Reference/Elements/ul), with each [list item](/en-US/docs/Web/HTML/Reference/Elements/li) containing some sample content: + +```html live-sample___carousel-example live-sample___carousel-example_final +<ul> + <li> + <h2>Page 1</h2> + </li> + <li> + <h2>Page 2</h2> + </li> + <li> + <h2>Page 3</h2> + </li> + <li> + <h2>Page 4</h2> + </li> +</ul> +``` + +#### CSS + +We first convert our `<ul>` into a carousel by setting the {{cssxref("display")}} to `flex`, creating a single, non-wrapping row of `<li>` elements. The {{cssxref("overflow-x")}} property is set to `auto`, meaning if the items overflow their container on the x-axis, the content will scroll horizontally. We then convert the `<ul>` into a [scroll-snap container](/en-US/docs/Glossary/Scroll_snap#scroll_snap_container), ensuring that items always snap into place when the container is scrolled with a {{cssxref("scroll-snap-type")}} value of `mandatory`. + +```css hidden live-sample___carousel-example live-sample___carousel-example_final +* { + box-sizing: border-box; +} + +body { + margin: 0; + font-family: Arial, Helvetica, sans-serif; +} +``` + +```css live-sample___carousel-example live-sample___carousel-example_final +ul { + display: flex; + gap: 4vw; + padding-left: 0; + overflow-x: auto; + overscroll-behavior-x: contain; + scroll-snap-type: x mandatory; +} +``` + +Next, we style the `<li>` elements, using the {{cssxref("flex")}} property to make them `100%` of the width of the container. The {{cssxref("scroll-snap-align")}} value of `start` causes the left-hand side of the left-most visible item to snap to the left edge of the container when the content is scrolled. + +```css live-sample___carousel-example live-sample___carousel-example_final +li { + list-style-type: none; + background-color: #eee; + flex: 0 0 100%; + height: 200px; + padding-top: 20px; + scroll-snap-align: start; + text-align: center; +} +``` + +Next, the list's {{cssxref("scroll-marker-group")}} property is set to `after`, so the `::scroll-marker-group` pseudo-element is placed after the list's DOM content in the tabbing order and layout box order; this means it comes after the scroll buttons: + +```css live-sample___carousel-example live-sample___carousel-example_final +ul { + scroll-marker-group: after; +} +``` + +Next, the list's `::scroll-marker-group` pseudo-element is laid out using flexbox, with a {{cssxref("justify-content")}} value of of `center` and a {{cssxref("gap")}} of `20px` so that its children (the {{cssxref("::scroll-marker")}} pseudo-elements) are centered inside the `::scroll-marker-group` with a gap between each one. + +```css live-sample___carousel-example live-sample___carousel-example_final +ul::scroll-marker-group { + display: flex; + justify-content: center; + gap: 20px; +} +``` + +Next, the scroll markers themselves are styled. The look of each one is handled by setting {{cssxref("width")}}, {{cssxref("height")}}, {{cssxref("background-color")}}, {{cssxref("border")}}, and {{cssxref("border-radius")}}, but we also need to set a non-`none` value for the {{cssxref("content")}}, property so they are actually generated. + +```css live-sample___carousel-example live-sample___carousel-example_final +li::scroll-marker { + width: 16px; + height: 16px; + background-color: transparent; + border: 2px solid black; + border-radius: 50%; + content: ""; +} +``` + +> [!NOTE] +> Generated content is inline by default; we can apply `width` and `height` to our scroll markers because they are being laid out as flex items. + +Finally, the {{cssxref(":target-current")}} pseudo-class is used to select whichever scroll marker corresponds to the currently visible "page", highlighting how far the user has scrolled through the content. In this case, we set the `background-color` to `black` so it is styled as a filled-in circle. + +```css live-sample___carousel-example live-sample___carousel-example_final +li::scroll-marker:target-current { + background-color: black; +} +``` + +#### Result + +{{EmbedLiveSample("carousel-example", "100%", "280px")}} + +### Positioning the scroll marker group with anchor-positioning + +This example extends the previous one, demonstrating the use of [CSS anchor positioning](/en-US/docs/Web/CSS/CSS_anchor_positioning) to position the scroll marker group relative to the carousel. + +#### CSS + +The list's `::scroll-marker-group` pseudo-element is positioned relative to the carousel using CSS anchor positioning by giving the group a value for {{cssxref("position-anchor")}} that matches the {{cssxref("anchor-name")}} of the `<ul>`. We then position the group relative to the scroll container in the block direction by setting a {{cssxref("top")}} value that includes an {{cssxref("anchor()")}} function. We also add a {{cssxref("justify-self")}} value of `anchor-center`, which aligns the group to the center of the scroll container in the inline direction. + +```css live-sample___carousel-example_final +ul { + anchor-name: --myCarousel; +} + +ul::scroll-marker-group { + /* From the previous example */ + display: flex; + gap: 20px; + + position: absolute; + position-anchor: --myCarousel; + top: calc(anchor(bottom) - 70px); + justify-self: anchor-center; +} +``` + +#### Result + +{{EmbedLiveSample("carousel-example_final", "100%", "260px")}} + +## Specifications + +{{Specifications}} + +## Browser compatibility + +{{Compat}} + +## See also + +- {{cssxref("scroll-marker-group")}} +- {{cssxref("::scroll-button()")}} +- {{cssxref("::scroll-marker")}} +- {{cssxref("::column")}} +- {{cssxref(":target-current")}} +- [Creating CSS carousels](/en-US/docs/Web/CSS/CSS_overflow/CSS_carousels) +- [CSS anchor positioning](/en-US/docs/Web/CSS/CSS_anchor_positioning) module +- [CSS overflow](/en-US/docs/Web/CSS/CSS_overflow) module +- [CSS Carousel Gallery](https://chrome.dev/carousel/) via chrome.dev (2025) diff --git a/files/en-us/web/css/_doublecolon_scroll-marker/index.md b/files/en-us/web/css/_doublecolon_scroll-marker/index.md new file mode 100644 index 000000000000000..f2d66be479191aa --- /dev/null +++ b/files/en-us/web/css/_doublecolon_scroll-marker/index.md @@ -0,0 +1,197 @@ +--- +title: ::scroll-marker +slug: Web/CSS/::scroll-marker +page-type: css-pseudo-element +status: + - experimental +browser-compat: css.selectors.scroll-marker +--- + +{{CSSRef}}{{SeeCompatTable}} + +The **`::scroll-marker`** [CSS](/en-US/docs/Web/CSS) [pseudo-element](/en-US/docs/Web/CSS/Pseudo-elements) can be generated inside any element and represents its scroll marker. All elements can have a `::scroll-marker` pseudo-element, which is placed into the {{cssxref("::scroll-marker-group")}} of the nearest {{glossary("scroll container")}} ancestor. A scroll marker behaves like an anchor ({{htmlelement("a")}} element) whose scroll target is the marker's originating element — and scrolls the scroll container to that element when activated. + +## Syntax + +```css-nolint +::scroll-marker { + /* ... */ +} +``` + +## Description + +A `::scroll-marker` is generated on an element when the `::scroll-marker`'s {{cssxref("content")}} property is set to a non-`none` value, and its has an ancestor scroll container with a non-`none` {{cssxref("scroll-marker-group")}} property value (meaning that it will generate a {{cssxref("::scroll-marker-group")}} pseudo-element). + +The scroll container's `::scroll-marker-group` pseudo-element automatically contains any `::scroll-marker` pseudo-elements generated on the scroll container or its descendants. This allows them to be positioned and laid out as a group and is typically used when creating a CSS carousel to create a scroll position indicator. The individual scroll markers can be used to navigate to their associated content items. + +Accessibility-wise, the scroll marker group and contained scroll markers are rendered with [`tablist`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/tablist_role)/[`tab`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/tab_role) semantics. When you <kbd>Tab</kbd> to the group, it behaves like a single item (that is, another press of the <kbd>Tab</kbd> key will move past the group to the next item), and you can move between the different scroll markers using the left and right (or up and down) cursor keys. + +## Examples + +See [Creating CSS carousels](/en-US/docs/Web/CSS/CSS_overflow/CSS_carousels) for other examples that use the `::scroll-marker` pseudo-element. + +### Creating carousel scroll markers + +In this example, we demonstrate how to create scroll markers on a CSS carousel. + +#### HTML + +We have a basic HTML {{htmlelement("ul")}} list with several {{htmlelement("li")}} list items. + +```html live-sample___creating-scroll-markers live-sample___custom-numbering +<ul> + <li>Item 1</li> + <li>Item 2</li> + <li>Item 3</li> + <li>Item 4</li> + <li>Item 5</li> + <li>Item 6</li> + <li>Item 7</li> + <li>Item 8</li> +</ul> +``` + +#### CSS + +We convert our `<ul>` into a scroll snapping overflow container by setting the {{cssxref("display")}} to `flex`, creating a single, non-wrapping row of `<li>` elements. The {{cssxref("overflow-x")}} property is set to `auto`, meaning if the items overflow their container on the x-axis, the content will scroll horizontally. We then convert the `<ul>` into a [scroll-snap container](/en-US/docs/Glossary/Scroll_snap#scroll_snap_container), ensuring that items always snap into place when the container is scrolled with a {{cssxref("scroll-snap-type")}} value of `mandatory`. + +We create a scroll marker group with the `scroll-marker-group` property, placing the group after all the content. + +```css live-sample___creating-scroll-markers live-sample___custom-numbering +ul { + display: flex; + gap: 4vw; + padding-left: 0; + overflow-x: auto; + overscroll-behavior-x: contain; + scroll-snap-type: x mandatory; + scroll-marker-group: after; +} +``` + +Next, we style the `<li>` elements, using the {{cssxref("flex")}} property to make them `33%` of the width of the container. The {{cssxref("scroll-snap-align")}} value of `start` causes the left-hand side of the left-most visible item to snap to the left edge of the container when the content is scrolled. + +```css live-sample___creating-scroll-markers live-sample___custom-numbering +li { + list-style-type: none; + background-color: #eee; + flex: 0 0 33%; + height: 100px; + padding-top: 20px; + scroll-snap-align: start; + text-align: center; +} +``` + +We then use the `::scroll-marker` pseudo-element to create a square marker for each list item with a red border: + +```css live-sample___creating-scroll-markers +li::scroll-marker { + content: ""; + border: 1px solid red; + height: 1em; + width: 1em; +} +``` + +We also apply styles to the {{cssxref("::scroll-marker-group")}} pseudo-element to lay out the scroll markers in the center of the row with a `0.4em` gap between each one: + +```css live-sample___creating-scroll-markers live-sample___custom-numbering +::scroll-marker-group { + display: flex; + gap: 0.4em; + place-content: center; +} +``` + +Finally, we style the marker of the currently-scrolled element differently from the others, targeting the marker with the {{cssxref(":target-current")}} pseudo-class. + +```css live-sample___creating-scroll-markers +::scroll-marker:target-current { + background: red; +} +``` + +#### Result + +{{EmbedLiveSample("creating-scroll-markers", '', '200')}} + +### Custom scroll marker numbering and style + +This example is the same as the previous one, except that we have applied some different styling to the scroll markers, and used [CSS counters](/en-US/docs/Web/CSS/CSS_lists) to increment the number shown on each marker. The CSS differences are explained in the next section. + +### CSS + +In this example, we set a name of a counter we want to increment on each `<li>` — `markers` — using the {{cssxref("counter-increment")}} property: + +```css live-sample___custom-numbering +li { + counter-increment: markers; +} +``` + +We then set the `::scroll-marker` pseudo-element's {{cssxref("content")}} property to the {{cssxref("counter()")}} function, passing it the `markers` counter name as an argument. This has the effect of inserting a number into each marker, which increments automatically. The rest of the styling is rudimentary, but it illustrates how the markers can be fully-styled. + +```css live-sample___custom-numbering +li::scroll-marker { + content: counter(markers); + font-family: sans-serif; + width: fit-content; + height: 1em; + padding: 5px; + color: black; + text-decoration: none; + border: 2px solid rgb(0 0 0 / 0.15); + border-radius: 0.5em; + background-color: #eee; +} +``` + +For another interesting customization, we include two rules to select the marker of the first and last list items by inserting {{cssxref(":first-child")}} and {{cssxref(":last-child")}} into the selector chain, respectively. We give the first marker text content of "First", and the last marker text content of "Last". + +```css live-sample___custom-numbering +li:first-child::scroll-marker { + content: "First"; +} + +li:last-child::scroll-marker { + content: "Last"; +} +``` + +To improve user experience, we set a different color on the markers on {{cssxref(":hover")}} and use the `:target-current` pseudo-class to set a different {{cssxref("color")}} and {{cssxref("background-color")}} on the currently-scrolled element's marker so users know which item is currently in view: + +```css live-sample___custom-numbering +::scroll-marker:hover { + background-color: #dcc; +} + +::scroll-marker:target-current { + background-color: purple; + color: white; +} +``` + +#### Result + +{{EmbedLiveSample("custom-numbering", '', '220')}} + +## Specifications + +{{Specifications}} + +## Browser compatibility + +{{Compat}} + +## See also + +- {{cssxref("scroll-marker-group")}} +- {{cssxref("::scroll-button()")}} +- {{cssxref("::scroll-marker-group")}} +- {{cssxref(":target-current")}} +- [Creating CSS carousels](/en-US/docs/Web/CSS/CSS_overflow/CSS_carousels) +- [CSS lists and counters](/en-US/docs/Web/CSS/CSS_lists) module +- [CSS overflow](/en-US/docs/Web/CSS/CSS_overflow) module +- [CSS Carousel Gallery](https://chrome.dev/carousel/) via chrome.dev (2025) diff --git a/files/en-us/web/css/_doublecolon_selection/index.md b/files/en-us/web/css/_doublecolon_selection/index.md index 91b74a93d15902f..eb979d8dfd5413c 100644 --- a/files/en-us/web/css/_doublecolon_selection/index.md +++ b/files/en-us/web/css/_doublecolon_selection/index.md @@ -53,7 +53,7 @@ If overridden, it is important to ensure that the **contrast ratio** between the Color contrast ratio is found by comparing the luminosity of the selected text and the selected text background colors. To meet current [Web Content Accessibility Guidelines (WCAG)](https://www.w3.org/WAI/standards-guidelines/wcag/), text content must have a contrast ratio of **4.5:1**, or 3:1 for larger text such as headings. (WCAG defines large text as between `18.66px` and `24px` and [bold](/en-US/docs/Web/CSS/font-weight), or `24px` or larger.) - [WebAIM: Color Contrast Checker](https://webaim.org/resources/contrastchecker/) -- [MDN Understanding WCAG, Guideline 1.4 explanations](/en-US/docs/Web/Accessibility/Understanding_WCAG/Perceivable#guideline_1.4_make_it_easier_for_users_to_see_and_hear_content_including_separating_foreground_from_background) +- [MDN Understanding WCAG, Guideline 1.4 explanations](/en-US/docs/Web/Accessibility/Guides/Understanding_WCAG/Perceivable#guideline_1.4_make_it_easier_for_users_to_see_and_hear_content_including_separating_foreground_from_background) - [Understanding Success Criterion 1.4.3 | W3C Understanding WCAG 2.0](https://www.w3.org/TR/UNDERSTANDING-WCAG20/visual-audio-contrast-contrast.html) ## Examples diff --git a/files/en-us/web/css/_doublecolon_slotted/index.md b/files/en-us/web/css/_doublecolon_slotted/index.md index 558353fcc3c2fd8..9ddaa1a6a982e9c 100644 --- a/files/en-us/web/css/_doublecolon_slotted/index.md +++ b/files/en-us/web/css/_doublecolon_slotted/index.md @@ -182,7 +182,7 @@ Our markup includes three custom elements, including a custom element with an in - {{cssxref(":host-context", ":host-context()")}} - {{cssxref(":has-slotted")}} - [CSS scoping](/en-US/docs/Web/CSS/CSS_scoping) module -- HTML [`slot`](/en-US/docs/Web/HTML/Global_attributes/slot) attribute +- HTML [`slot`](/en-US/docs/Web/HTML/Reference/Global_attributes/slot) attribute - HTML {{HTMLElement("slot")}} element - HTML {{HTMLElement("template")}} element - [Web components](/en-US/docs/Web/API/Web_components) diff --git a/files/en-us/web/css/_doublecolon_spelling-error/index.md b/files/en-us/web/css/_doublecolon_spelling-error/index.md index 3615bf4f48e3b81..f028ea3ab760870 100644 --- a/files/en-us/web/css/_doublecolon_spelling-error/index.md +++ b/files/en-us/web/css/_doublecolon_spelling-error/index.md @@ -67,3 +67,4 @@ In this example, eventual supporting browsers should highlight any flagged spell ## See also - {{cssxref("::grammar-error")}} +- {{cssxref("text-decoration-line")}} diff --git a/files/en-us/web/css/_doublecolon_view-transition-group/index.md b/files/en-us/web/css/_doublecolon_view-transition-group/index.md index e1992686f35b5e4..ad6aec4a3efc385 100644 --- a/files/en-us/web/css/_doublecolon_view-transition-group/index.md +++ b/files/en-us/web/css/_doublecolon_view-transition-group/index.md @@ -1,5 +1,5 @@ --- -title: ::view-transition-group +title: ::view-transition-group() slug: Web/CSS/::view-transition-group page-type: css-pseudo-element browser-compat: css.selectors.view-transition-group @@ -7,14 +7,14 @@ browser-compat: css.selectors.view-transition-group {{CSSRef}} -The **`::view-transition-group`** [CSS](/en-US/docs/Web/CSS) [pseudo-element](/en-US/docs/Web/CSS/Pseudo-elements) represents a single view transition snapshot group. +The **`::view-transition-group()`** [CSS](/en-US/docs/Web/CSS) [pseudo-element](/en-US/docs/Web/CSS/Pseudo-elements) represents a single view transition snapshot group. -During a view transition, `::view-transition-group` is included in the associated pseudo-element tree as explained in [The view transition pseudo-element tree](/en-US/docs/Web/API/View_Transition_API/Using#the_view_transition_pseudo-element_tree). It is only ever a child of {{cssxref("::view-transition")}}, and has a {{cssxref("::view-transition-image-pair")}} as a child. +During a view transition, `::view-transition-group()` is included in the associated pseudo-element tree as explained in [The view transition pseudo-element tree](/en-US/docs/Web/API/View_Transition_API/Using#the_view_transition_pseudo-element_tree). It is only ever a child of {{cssxref("::view-transition")}}, and has a {{cssxref("::view-transition-image-pair()")}} as a child. -`::view-transition-group` is given the following default styling in the UA stylesheet: +`::view-transition-group()` is given the following default styling in the UA stylesheet: ```css -html::view-transition-group(*) { +:root::view-transition-group(*) { position: absolute; top: 0; left: 0; @@ -24,7 +24,7 @@ html::view-transition-group(*) { } ``` -By default, selected elements initially mirror the size and position of the {{cssxref("::view-transition-old")}} pseudo-element representing the "old" view state, or the {{cssxref("::view-transition-new")}} pseudo-element representing the "new" view state if there isn't an "old" view state. +By default, selected elements initially mirror the size and position of the {{cssxref("::view-transition-old()")}} pseudo-element representing the "old" view state, or the {{cssxref("::view-transition-new()")}} pseudo-element representing the "new" view state if there isn't an "old" view state. If there's both an "old" and "new" view state, styles in the view transition style sheet animate this pseudo-element's {{cssxref("width")}} and {{cssxref("height")}} from the size of the "old" view state's border box to that of the "new" view state's border box. @@ -36,19 +36,23 @@ In addition, the element's transform is animated from the "old" view state's scr ## Syntax ```css-nolint -::view-transition-group(<pt-name-selector>) { +::view-transition-group([ <pt-name-selector> <pt-class-selector>? ] | <pt-class-selector>) { /* ... */ } ``` -`<pt-name-selector>` can be one of the following values: +### Parameters - `*` - - : Causes the pseudo-element to match all view transition groups. + - : The [universal selector (`*`)](/en-US/docs/Web/CSS/Universal_selectors); selects all view transition groups on a page. - `root` - - : Causes the pseudo-element to match the default `root` view transition group created by the user agent to contain the view transition for the overall page. This group includes any element not assigned to its own specific view transition group via the {{cssxref("view-transition-name")}} property. -- {{cssxref("custom-ident")}} - - : Causes the pseudo-element to match a specific view transition group created by assigning the given {{cssxref("custom-ident")}} to an element via the {{cssxref("view-transition-name")}} property. + - : The {{cssxref("view-transition-name")}} applied to {{cssxref(":root")}} causes the pseudo-element to match the default `root` view transition group. This is the snapshot group created by the user agent to contain the view transition for the overall page. This group includes any element not assigned to its own specific view transition snapshot group via the `view-transition-name` property. +- `<pt-name-selector>` + - : The {{cssxref("custom-ident")}} set as the value of the {{cssxref("view-transition-name")}} property. +- `<pt-class-selector>` + - : The {{cssxref("custom-ident")}} set as the value of the {{cssxref("view-transition-class")}} property, preceded by a period (`.`). + +The {{cssxref("specificity")}} of the named view transition pseudo-element is equal to the [specificity of the type selector](/en-US/docs/Web/CSS/CSS_cascade/Specificity#type_column), unless the parameter used is the universal selector is used, in which case the specificity is zero. ## Examples @@ -58,6 +62,10 @@ In addition, the element's transform is animated from the "old" view state's scr animation-timing-function: ease; z-index: 1; } + +::view-transition-group(.card) { + animation-duration: 1s; +} ``` ## Specifications diff --git a/files/en-us/web/css/_doublecolon_view-transition-image-pair/index.md b/files/en-us/web/css/_doublecolon_view-transition-image-pair/index.md index 0904d6e15e96dd0..46a77f4e032875b 100644 --- a/files/en-us/web/css/_doublecolon_view-transition-image-pair/index.md +++ b/files/en-us/web/css/_doublecolon_view-transition-image-pair/index.md @@ -1,5 +1,5 @@ --- -title: ::view-transition-image-pair +title: ::view-transition-image-pair() slug: Web/CSS/::view-transition-image-pair page-type: css-pseudo-element browser-compat: css.selectors.view-transition-image-pair @@ -7,11 +7,11 @@ browser-compat: css.selectors.view-transition-image-pair {{CSSRef}} -The **`::view-transition-image-pair`** [CSS](/en-US/docs/Web/CSS) [pseudo-element](/en-US/docs/Web/CSS/Pseudo-elements) represents a container for a [view transition's](/en-US/docs/Web/API/View_Transition_API) "old" and "new" view states — before and after the transition. +The **`::view-transition-image-pair()`** [CSS](/en-US/docs/Web/CSS) [pseudo-element](/en-US/docs/Web/CSS/Pseudo-elements) represents a container for a [view transition's](/en-US/docs/Web/API/View_Transition_API) "old" and "new" view states — before and after the transition. -During a view transition, `::view-transition-image-pair` is included in the associated pseudo-element tree as explained in [The view transition pseudo-element tree](/en-US/docs/Web/API/View_Transition_API/Using#the_view_transition_pseudo-element_tree). It is only ever a child of a {{cssxref("::view-transition-group")}}. In terms of children, it can have a {{cssxref("::view-transition-new")}} or a {{cssxref("::view-transition-old")}}, or both. +During a view transition, `::view-transition-image-pair()` is included in the associated pseudo-element tree as explained in [The view transition pseudo-element tree](/en-US/docs/Web/API/View_Transition_API/Using#the_view_transition_pseudo-element_tree). It is only ever a child of a {{cssxref("::view-transition-group()")}}. In terms of children, it can have a {{cssxref("::view-transition-new()")}} or a {{cssxref("::view-transition-old()")}}, or both. -`::view-transition-image-pair` is given the following default styling in the UA stylesheet: +`::view-transition-image-pair()` is given the following default styling in the UA stylesheet: ```css :root::view-transition-image-pair(*) { @@ -24,24 +24,26 @@ During a view transition, `::view-transition-image-pair` is included in the asso } ``` -During a view transition, `::view-transition-image-pair` has {{cssxref("isolation", "isolation: isolate")}} set on it in the view transition style sheet so that its children can be blended with non-normal blend modes without affecting other visual outputs. +During a view transition, `::view-transition-image-pair()` has {{cssxref("isolation", "isolation: isolate")}} set on it in the view transition style sheet so that its children can be blended with non-normal blend modes without affecting other visual outputs. ## Syntax ```css-nolint -::view-transition-image-pair(<pt-name-selector>) { +::view-transition-image-pair([ <pt-name-selector> <pt-class-selector>? ] | <pt-class-selector>) { /* ... */ } ``` -`<pt-name-selector>` can be one of the following values: +### Parameters - `*` - - : Causes the pseudo-element to match all view transition groups. + - : The [universal selector (`*`)](/en-US/docs/Web/CSS/Universal_selectors); selects all view transition groups on a page. - `root` - - : Causes the pseudo-element to match the default `root` view transition group created by the user agent to contain the view transition for the overall page. This group includes any element not assigned to its own specific view transition group via the {{cssxref("view-transition-name")}} property. -- {{cssxref("custom-ident")}} - - : Causes the pseudo-element to match a specific view transition group created by assigning the given {{cssxref("custom-ident")}} to an element via the {{cssxref("view-transition-name")}} property. + - : Causes the pseudo-element to match the default `root` view transition snapshot group created by the user agent to contain the view transition for the overall page. This group includes any element not assigned to its own specific view transition snapshot group via the {{cssxref("view-transition-name")}} property. +- `<pt-name-selector>` + - : The {{cssxref("custom-ident")}} set as the value of the {{cssxref("view-transition-name")}} property. +- `<pt-class-selector>` + - : The {{cssxref("custom-ident")}} set as the value of the {{cssxref("view-transition-class")}} property preceded by a period (`.`). ## Examples @@ -49,6 +51,10 @@ During a view transition, `::view-transition-image-pair` has {{cssxref("isolatio ::view-transition-image-pair(root) { isolation: auto; } + +::view-transition-image-pair(.card) { + isolation: isolate; +} ``` ## Specifications diff --git a/files/en-us/web/css/_doublecolon_view-transition-new/index.md b/files/en-us/web/css/_doublecolon_view-transition-new/index.md index 43e79427782ef63..28b952b4c29f347 100644 --- a/files/en-us/web/css/_doublecolon_view-transition-new/index.md +++ b/files/en-us/web/css/_doublecolon_view-transition-new/index.md @@ -1,5 +1,5 @@ --- -title: ::view-transition-new +title: ::view-transition-new() slug: Web/CSS/::view-transition-new page-type: css-pseudo-element browser-compat: css.selectors.view-transition-new @@ -7,9 +7,9 @@ browser-compat: css.selectors.view-transition-new {{CSSRef}} -The **`::view-transition-new`** [CSS](/en-US/docs/Web/CSS) [pseudo-element](/en-US/docs/Web/CSS/Pseudo-elements) represents the "new" view state of a view transition — a snapshot live representation of the state after the transition. +The **`::view-transition-new()`** [CSS](/en-US/docs/Web/CSS) [pseudo-element](/en-US/docs/Web/CSS/Pseudo-elements) represents the "new" view state of a view transition — a snapshot live representation of the state after the transition. -During a view transition, `::view-transition-new` is included in the associated pseudo-element tree as explained in [The view transition pseudo-element tree](/en-US/docs/Web/API/View_Transition_API/Using#the_view_transition_pseudo-element_tree). It is only ever a child of a {{cssxref("::view-transition-image-pair")}}, and never has any children. +During a view transition, `::view-transition-new()` is included in the associated pseudo-element tree as explained in [The view transition pseudo-element tree](/en-US/docs/Web/API/View_Transition_API/Using#the_view_transition_pseudo-element_tree). It is only ever a child of a {{cssxref("::view-transition-image-pair()")}}, and never has any children. It is a replaced element and therefore can be manipulated with properties such as {{cssxref("object-fit")}} and {{cssxref("object-position")}}. It has natural dimensions equal to the content's size. @@ -46,24 +46,26 @@ The following default styling is included in the UA stylesheet: ``` > [!NOTE] -> Additional view transition styles are also setup to animate `::view-transition-new`. These are dynamically generated during the view transition; see the specification [setup transition pseudo-elements](https://drafts.csswg.org/css-view-transitions-1/#setup-transition-pseudo-elements) and [update pseudo-element styles](https://drafts.csswg.org/css-view-transitions-1/#update-pseudo-element-styles) sections for more details. +> Additional view transition styles are also setup to animate `::view-transition-new()`. These are dynamically generated during the view transition; see the specification [setup transition pseudo-elements](https://drafts.csswg.org/css-view-transitions-1/#setup-transition-pseudo-elements) and [update pseudo-element styles](https://drafts.csswg.org/css-view-transitions-1/#update-pseudo-element-styles) sections for more details. ## Syntax ```css-nolint -::view-transition-new(<pt-name-selector>) { +::view-transition-new([ <pt-name-selector> <pt-class-selector>? ] | <pt-class-selector>) { /* ... */ } ``` -`<pt-name-selector>` can be one of the following values: +### Parameters - `*` - - : Causes the pseudo-element to match all view transition groups. + - : The [universal selector (`*`)](/en-US/docs/Web/CSS/Universal_selectors); selects all view transition groups on a page. - `root` - : Causes the pseudo-element to match the default `root` view transition snapshot group created by the user agent to contain the view transition for the overall page. This group includes any element not assigned to its own specific view transition snapshot group via the {{cssxref("view-transition-name")}} property. -- {{cssxref("custom-ident")}} - - : Causes the pseudo-element to match a specific view transition snapshot group created by assigning the given {{cssxref("custom-ident")}} to an element via the {{cssxref("view-transition-name")}} property. +- `<pt-name-selector>` + - : The {{cssxref("custom-ident")}} set as the value of the {{cssxref("view-transition-name")}} property. +- `<pt-class-selector>` + - : The {{cssxref("custom-ident")}} set as the value of the {{cssxref("view-transition-class")}} property preceded by a period (`.`). ## Examples diff --git a/files/en-us/web/css/_doublecolon_view-transition-old/index.md b/files/en-us/web/css/_doublecolon_view-transition-old/index.md index 78ffc9f27b18de5..25f5051d8b40773 100644 --- a/files/en-us/web/css/_doublecolon_view-transition-old/index.md +++ b/files/en-us/web/css/_doublecolon_view-transition-old/index.md @@ -1,5 +1,5 @@ --- -title: ::view-transition-old +title: ::view-transition-old() slug: Web/CSS/::view-transition-old page-type: css-pseudo-element browser-compat: css.selectors.view-transition-old @@ -7,9 +7,9 @@ browser-compat: css.selectors.view-transition-old {{CSSRef}} -The **`::view-transition-old`** [CSS](/en-US/docs/Web/CSS) [pseudo-element](/en-US/docs/Web/CSS/Pseudo-elements) represents the "old" view state of a view transition — a static snapshot of the old view, before the transition. +The **`::view-transition-old()`** [CSS](/en-US/docs/Web/CSS) [pseudo-element](/en-US/docs/Web/CSS/Pseudo-elements) represents the "old" view state of a view transition — a static snapshot of the old view, before the transition. -During a view transition, `::view-transition-old` is included in the associated pseudo-element tree as explained in [The view transition pseudo-element tree](/en-US/docs/Web/API/View_Transition_API/Using#the_view_transition_pseudo-element_tree), provided there's an "old" view state to represent. It is only ever a child of a {{cssxref("::view-transition-image-pair")}}, and never has any children. +During a view transition, `::view-transition-old()` is included in the associated pseudo-element tree as explained in [The view transition pseudo-element tree](/en-US/docs/Web/API/View_Transition_API/Using#the_view_transition_pseudo-element_tree), provided there's an "old" view state to represent. It is only ever a child of a {{cssxref("::view-transition-image-pair()")}}, and never has any children. It is a replaced element and therefore can be manipulated with properties such as {{cssxref("object-fit")}} and {{cssxref("object-position")}}. It has natural dimensions equal to the content's size. @@ -46,24 +46,26 @@ The following default styling is included in the UA stylesheet: ``` > [!NOTE] -> Additional view transition styles are also setup to animate `::view-transition-old`. These are dynamically generated during the view transition; see the specification [setup transition pseudo-elements](https://drafts.csswg.org/css-view-transitions-1/#setup-transition-pseudo-elements) and [update pseudo-element styles](https://drafts.csswg.org/css-view-transitions-1/#update-pseudo-element-styles) sections for more details. +> Additional view transition styles are also setup to animate `::view-transition-old()`. These are dynamically generated during the view transition; see the specification [setup transition pseudo-elements](https://drafts.csswg.org/css-view-transitions-1/#setup-transition-pseudo-elements) and [update pseudo-element styles](https://drafts.csswg.org/css-view-transitions-1/#update-pseudo-element-styles) sections for more details. ## Syntax ```css-nolint -::view-transition-old(<pt-name-selector>) { +::view-transition-old([ <pt-name-selector> <pt-class-selector>? ] | <pt-class-selector>) { /* ... */ } ``` -`<pt-name-selector>` can be one of the following values: +### Parameters - `*` - - : Causes the pseudo-element to match all view transition groups. + - : The universal selector (`*`) selects all view transition groups on a page. - `root` - : Causes the pseudo-element to match the default `root` view transition snapshot group created by the user agent to contain the view transition for the overall page. This group includes any element not assigned to its own specific view transition snapshot group via the {{cssxref("view-transition-name")}} property. -- {{cssxref("custom-ident")}} - - : Causes the pseudo-element to match a specific view transition snapshot group created by assigning the given {{cssxref("custom-ident")}} to an element via the {{cssxref("view-transition-name")}} property. +- `<pt-name-selector>` + - : The {{cssxref("custom-ident")}} set as the value of the {{cssxref("view-transition-name")}} property. +- `<pt-class-selector>` + - : The {{cssxref("custom-ident")}} set as the value of the {{cssxref("view-transition-class")}} property preceded by a period (`.`). ## Examples diff --git a/files/en-us/web/css/_doublecolon_view-transition/index.md b/files/en-us/web/css/_doublecolon_view-transition/index.md index 17b1c3c1c0fded0..7de9c543c87b1f7 100644 --- a/files/en-us/web/css/_doublecolon_view-transition/index.md +++ b/files/en-us/web/css/_doublecolon_view-transition/index.md @@ -9,18 +9,18 @@ browser-compat: css.selectors.view-transition The **`::view-transition`** [CSS](/en-US/docs/Web/CSS) [pseudo-element](/en-US/docs/Web/CSS/Pseudo-elements) represents the root of the [view transitions](/en-US/docs/Web/API/View_Transition_API) overlay, which contains all view transition snapshot groups and sits over the top of all other page content. -During a view transition, `::view-transition` is included in the associated pseudo-element tree as explained in [The view transition pseudo-element tree](/en-US/docs/Web/API/View_Transition_API/Using#the_view_transition_pseudo-element_tree). It is the top-level node of this tree, and has one or more {{cssxref("::view-transition-group")}}s as children. +During a view transition, `::view-transition` is included in the associated pseudo-element tree as explained in [The view transition pseudo-element tree](/en-US/docs/Web/API/View_Transition_API/Using#the_view_transition_pseudo-element_tree). It is the top-level node of this tree, and has one or more {{cssxref("::view-transition-group()")}}s as children. `::view-transition` is given the following default styling in the UA stylesheet: ```css -html::view-transition { +:root::view-transition { position: fixed; inset: 0; } ``` -All {{cssxref("::view-transition-group")}} pseudo-elements are positioned relative to the view transition root. +All {{cssxref("::view-transition-group()")}} pseudo-elements are positioned relative to the view transition root. ## Syntax diff --git a/files/en-us/web/css/absolute-size/index.md b/files/en-us/web/css/absolute-size/index.md index c726849039e4a25..19bf8b1c476c742 100644 --- a/files/en-us/web/css/absolute-size/index.md +++ b/files/en-us/web/css/absolute-size/index.md @@ -58,7 +58,7 @@ Each `<absolute-size>` keyword value is sized relative to the `medium` size and In CSS1 (1996), the scaling factor between adjacent keyword value indexes was 1.5, which was too large. In CSS2 (1998), the scaling factor between adjacent keyword value indexes was 1.2, which created issues for the small values. As a single fixed ratio between adjacent absolute-size keywords was found to be problematic, there is no longer a fixed ratio recommendation. The only recommendation to preserve readability is that the smallest font size should not be less than `9px`. -For each `<absolute-size>` keyword value, the following table lists the scaling factor, mapping to [`<h1>` to `<h6>`](/en-US/docs/Web/HTML/Element/Heading_Elements) headings, and mapping to the deprecated [HTML `size` attribute](#html_size_attribute). +For each `<absolute-size>` keyword value, the following table lists the scaling factor, mapping to [`<h1>` to `<h6>`](/en-US/docs/Web/HTML/Reference/Elements/Heading_Elements) headings, and mapping to the deprecated [HTML `size` attribute](#html_size_attribute). | `<absolute-size>` | xx-small | x-small | small | medium | large | x-large | xx-large | xxx-large | | --------------------- | -------- | ------- | ----- | ------ | ----- | ------- | -------- | --------- | diff --git a/files/en-us/web/css/accent-color/index.md b/files/en-us/web/css/accent-color/index.md index b677556acf9464d..f4c44e67e8670d9 100644 --- a/files/en-us/web/css/accent-color/index.md +++ b/files/en-us/web/css/accent-color/index.md @@ -9,14 +9,56 @@ browser-compat: css.properties.accent-color The **`accent-color`** [CSS](/en-US/docs/Web/CSS) property sets the {{Glossary("accent")}} color for user-interface controls generated by some elements. -{{EmbedInteractiveExample("pages/css/accent-color.html")}} +{{InteractiveExample("CSS Demo: accent-color")}} + +```css interactive-example-choice +accent-color: red; +``` + +```css interactive-example-choice +accent-color: #74992e; +``` + +```css interactive-example-choice +accent-color: rgb(255, 255, 128); +``` + +```css interactive-example-choice +accent-color: hsl(250, 100%, 34%); +``` + +```html interactive-example +<section class="default-example container" id="default-example"> + <div> + <input checked="" id="example-element" type="checkbox" /> + <label for="example-element" id="example-label">Example Label</label> + </div> +</section> +``` + +```css interactive-example +.container > div { + display: flex; + align-items: center; +} + +#example-element { + width: 40px; + height: 40px; +} + +#example-label { + margin-left: 10px; + font-size: x-large; +} +``` Browsers that support `accent-color` currently apply it to the following HTML elements: -- [`<input type="checkbox">`](/en-US/docs/Web/HTML/Element/input/checkbox) -- [`<input type="radio">`](/en-US/docs/Web/HTML/Element/input/radio) -- [`<input type="range">`](/en-US/docs/Web/HTML/Element/input/range) -- [`<progress>`](/en-US/docs/Web/HTML/Element/progress) +- [`<input type="checkbox">`](/en-US/docs/Web/HTML/Reference/Elements/input/checkbox) +- [`<input type="radio">`](/en-US/docs/Web/HTML/Reference/Elements/input/radio) +- [`<input type="range">`](/en-US/docs/Web/HTML/Reference/Elements/input/range) +- [`<progress>`](/en-US/docs/Web/HTML/Reference/Elements/progress) Each user agent has an accent color, with variations to ensure legibility and contrast. That accent color is not used by every user-interface control nor in diff --git a/files/en-us/web/css/align-content/index.md b/files/en-us/web/css/align-content/index.md index 65cca726a7f5f69..940f9d845d3ceaa 100644 --- a/files/en-us/web/css/align-content/index.md +++ b/files/en-us/web/css/align-content/index.md @@ -11,9 +11,53 @@ The [CSS](/en-US/docs/Web/CSS) **`align-content`** property sets the distributio The interactive example below uses grid layout to demonstrate some of the values of this property. -{{EmbedInteractiveExample("pages/css/align-content.html")}} +{{InteractiveExample("CSS Demo: align-content")}} -This property has no effect on single line flex containers (i.e. ones with `flex-wrap: nowrap`). +```css interactive-example-choice +align-content: start; +``` + +```css interactive-example-choice +align-content: center; +``` + +```css interactive-example-choice +align-content: space-between; +``` + +```css interactive-example-choice +align-content: space-around; +``` + +```html interactive-example +<section class="default-example" id="default-example"> + <div class="example-container"> + <div class="transition-all" id="example-element"> + <div>One</div> + <div>Two</div> + <div>Three</div> + </div> + </div> +</section> +``` + +```css interactive-example +#example-element { + border: 1px solid #c5c5c5; + display: grid; + grid-template-columns: 60px 60px; + grid-auto-rows: 40px; + column-gap: 10px; + height: 180px; +} + +#example-element > div { + background-color: rgba(0, 0, 255, 0.2); + border: 3px solid blue; +} +``` + +This property has no effect on single line flex containers (i.e., ones with `flex-wrap: nowrap`). ## Syntax @@ -90,7 +134,7 @@ align-content: unset; - : Used alongside an alignment keyword. Regardless of the relative sizes of the item and alignment container and whether overflow which causes data loss might happen, the given alignment value is honored. > [!NOTE] -> The `<content-distribution>` values (`space-between`, `space-around`, `space-evenly`, and `stretch`) have no effect in [block layout](/en-US/docs/Web/CSS/CSS_box_alignment/Box_alignment_in_block_abspos_tables#align-content_and_justify-content) as all the content in that block is treated as a single [alignment-subject](/en-US/docs/Glossary/Alignment_Subject) +> The `<content-distribution>` values (`space-between`, `space-around`, `space-evenly`, and `stretch`) have no effect in [block layout](/en-US/docs/Web/CSS/CSS_box_alignment/Box_alignment_in_block_abspos_tables#align-content_and_justify-content) as all the content in that block is treated as a single [alignment-subject](/en-US/docs/Glossary/Alignment_Subject). ## Formal definition @@ -108,10 +152,6 @@ In this example, you can switch between three different {{cssxref("display")}} p #### HTML -```html-nolint hidden -<div class="wrapper"> -``` - ```html <section> <div class="olive">Olive</div> @@ -123,46 +163,45 @@ In this example, you can switch between three different {{cssxref("display")}} p </section> ``` -```html-nolint hidden +```html hidden <fieldset class="controls"> - <legend>Controls</legend> - <div class="row"> - <label for="display">display: </label> - <select id="display"> - <option value="block" selected>block</option> - <option value="flex">flex</option> - <option value="grid">grid</option> - </select> - </div> - <div class="row"> - <label for="alignContent">align-content: </label> - <select id="alignContent"> - <option value="normal" selected>normal</option> - <option value="start">start</option> - <option value="center">center</option> - <option value="end">end</option> - <option value="flex-start">flex-start</option> - <option value="flex-end">flex-end</option> - <option value="space-between">space-between</option> - <option value="space-around">space-around</option> - <option value="space-evenly">space-evenly</option> - </select> - </div> - <p>CSS applied</p> - <pre> + <legend>Controls</legend> + <div class="row"> + <label for="display">display: </label> + <select id="display"> + <option value="block" selected>block</option> + <option value="flex">flex</option> + <option value="grid">grid</option> + </select> + </div> + <div class="row"> + <label for="alignContent">align-content: </label> + <select id="alignContent"> + <option value="normal" selected>normal</option> + <option value="start">start</option> + <option value="center">center</option> + <option value="end">end</option> + <option value="flex-start">flex-start</option> + <option value="flex-end">flex-end</option> + <option value="space-between">space-between</option> + <option value="space-around">space-around</option> + <option value="space-evenly">space-evenly</option> + </select> + </div> + <p>CSS applied</p> + <pre> section { display: <span id="displayStyle">block</span>; align-content: <span id="align">normal</span> } - </pre> - </fieldset> -</div> + </pre> +</fieldset> ``` #### CSS ```css hidden -.wrapper { +body { font-size: 1.25rem; display: flex; gap: 1rem; @@ -251,5 +290,5 @@ In [block layout](/en-US/docs/Web/CSS/CSS_box_alignment/Box_alignment_in_block_a - [Box alignment in grid layout](/en-US/docs/Web/CSS/CSS_box_alignment/Box_alignment_in_grid_layout) - [CSS box alignment](/en-US/docs/Web/CSS/CSS_box_alignment) - [Block and inline layout in normal flow](/en-US/docs/Web/CSS/CSS_display/Block_and_inline_layout_in_normal_flow) -- [Block-level_content](/en-US/docs/Glossary/Block-level_content) +- [Block-level content](/en-US/docs/Glossary/Block-level_content) - {{CSSXRef("display")}} diff --git a/files/en-us/web/css/align-items/index.md b/files/en-us/web/css/align-items/index.md index d6fd0e74d10873f..3e0bc7301fd58e0 100644 --- a/files/en-us/web/css/align-items/index.md +++ b/files/en-us/web/css/align-items/index.md @@ -9,7 +9,51 @@ browser-compat: css.properties.align-items The [CSS](/en-US/docs/Web/CSS) **`align-items`** property sets the {{cssxref("align-self")}} value on all direct children as a group. In flexbox, it controls the alignment of items on the {{glossary("cross axis")}}. In grid layout, it controls the alignment of items on the block axis within their {{glossary("grid areas")}}. -{{EmbedInteractiveExample("pages/css/align-items.html")}} +{{InteractiveExample("CSS Demo: align-items")}} + +```css interactive-example-choice +align-items: stretch; +``` + +```css interactive-example-choice +align-items: center; +``` + +```css interactive-example-choice +align-items: start; +``` + +```css interactive-example-choice +align-items: end; +``` + +```html interactive-example +<section class="default-example" id="default-example"> + <div class="example-container"> + <div class="transition-all" id="example-element"> + <div>One</div> + <div>Two</div> + <div>Three</div> + </div> + </div> +</section> +``` + +```css interactive-example +#example-element { + border: 1px solid #c5c5c5; + display: grid; + width: 200px; + grid-template-columns: 1fr 1fr; + grid-auto-rows: 80px; + grid-gap: 10px; +} + +#example-element > div { + background-color: rgba(0, 0, 255, 0.2); + border: 3px solid blue; +} +``` The interactive example below demonstrates some of the values for `align-items` using grid and flex layout. @@ -34,7 +78,9 @@ align-items: anchor-center; /* Baseline alignment */ align-items: baseline; align-items: first baseline; -align-items: last baseline; /* Overflow alignment (for positional alignment only) */ +align-items: last baseline; + +/* Overflow alignment (for positional alignment only) */ align-items: safe center; align-items: unsafe center; diff --git a/files/en-us/web/css/align-self/index.md b/files/en-us/web/css/align-self/index.md index 2f82421fec33634..b05098bf6f7a0f8 100644 --- a/files/en-us/web/css/align-self/index.md +++ b/files/en-us/web/css/align-self/index.md @@ -9,7 +9,49 @@ browser-compat: css.properties.align-self The **`align-self`** [CSS](/en-US/docs/Web/CSS) property overrides a grid or flex item's {{cssxref("align-items")}} value. In grid, it aligns the item inside the {{glossary("Grid Areas", "grid area")}}. In flexbox, it aligns the item on the {{glossary("cross axis")}}. -{{EmbedInteractiveExample("pages/css/align-self.html")}} +{{InteractiveExample("CSS Demo: align-self")}} + +```css interactive-example-choice +align-self: stretch; +``` + +```css interactive-example-choice +align-self: center; +``` + +```css interactive-example-choice +align-self: start; +``` + +```css interactive-example-choice +align-self: end; +``` + +```html interactive-example +<section class="default-example" id="default-example"> + <div class="example-container"> + <div class="transition-all" id="example-element">One</div> + <div>Two</div> + <div>Three</div> + </div> +</section> +``` + +```css interactive-example +.example-container { + border: 1px solid #c5c5c5; + display: grid; + width: 200px; + grid-template-columns: 1fr 1fr; + grid-auto-rows: 80px; + grid-gap: 10px; +} + +.example-container > div { + background-color: rgba(0, 0, 255, 0.2); + border: 3px solid blue; +} +``` The property doesn't apply to block-level boxes, or to table cells. If a flexbox item's cross-axis margin is `auto`, then `align-self` is ignored. diff --git a/files/en-us/web/css/all/index.md b/files/en-us/web/css/all/index.md index 37ceae8834c63e1..242289f66d74c9e 100644 --- a/files/en-us/web/css/all/index.md +++ b/files/en-us/web/css/all/index.md @@ -9,7 +9,60 @@ browser-compat: css.properties.all The **`all`** [shorthand](/en-US/docs/Web/CSS/CSS_cascade/Shorthand_properties) [CSS](/en-US/docs/Web/CSS) property resets all of an element's properties except {{cssxref("unicode-bidi")}}, {{cssxref("direction")}}, and [CSS Custom Properties](/en-US/docs/Web/CSS/CSS_cascading_variables/Using_CSS_custom_properties). It can set properties to their initial or inherited values, or to the values specified in another cascade layer or stylesheet origin. -{{EmbedInteractiveExample("pages/css/all.html")}} +{{InteractiveExample("CSS Demo: all")}} + +```css interactive-example-choice +/*no all property*/ +``` + +```css interactive-example-choice +all: initial; +``` + +```css interactive-example-choice +all: inherit; +``` + +```css interactive-example-choice +all: unset; +``` + +```css interactive-example-choice +all: revert; +``` + +```html interactive-example +<section id="default-example"> + <div class="example-container-bg"> + <div class="example-container"> + <p id="example-element"> + This paragraph has a font size of 1.5rem and a color of gold. It also + has 1rem of vertical margin set by the user-agent. The parent of the + paragraph is a &lt;div&gt; with a dashed blue border. + </p> + </div> + </div> +</section> +``` + +```css interactive-example +#example-element { + color: gold; + padding: 10px; + font-size: 1.5rem; + text-align: left; + width: 100%; +} + +.example-container { + border: 2px dashed #2d5ae1; +} + +.example-container-bg { + background-color: #77767b; + padding: 20px; +} +``` ## Constituent properties @@ -31,15 +84,15 @@ The `all` property is specified as one of the CSS global keyword values. Note th ### Values - {{cssxref("initial")}} - - : Specifies that all the element's properties should be changed to their [initial values](/en-US/docs/Web/CSS/CSS_cascade/initial_value). + - : Specifies that all the element's properties should be changed to their [initial values](/en-US/docs/Web/CSS/CSS_cascade/Value_processing#initial_value). - {{cssxref("inherit")}} - : Specifies that all the element's properties should be changed to their [inherited values](/en-US/docs/Web/CSS/CSS_cascade/Inheritance). - {{cssxref("unset")}} - : Specifies that all the element's properties should be changed to their inherited values if they inherit by default, or to their initial values if not. - {{cssxref("revert")}} - : Specifies behavior that depends on the stylesheet origin to which the declaration belongs: - - If the rule belongs to the [author origin](/en-US/docs/Web/CSS/CSS_cascade/Cascade#author_stylesheets), the `revert` value rolls back the [cascade](/en-US/docs/Web/CSS/CSS_cascade/Cascade) to the user level, so that the [specified values](/en-US/docs/Web/CSS/CSS_cascade/specified_value) are calculated as if no author-level rules were specified for the element. For purposes of `revert`, the author origin includes the Override and Animation origins. - - If the rule belongs to the [user origin](/en-US/docs/Web/CSS/CSS_cascade/Cascade#user_stylesheets), the `revert` value rolls back the [cascade](/en-US/docs/Web/CSS/CSS_cascade/Cascade) to the user-agent level, so that the [specified values](/en-US/docs/Web/CSS/CSS_cascade/specified_value) are calculated as if no author-level or user-level rules were specified for the element. + - If the rule belongs to the [author origin](/en-US/docs/Web/CSS/CSS_cascade/Cascade#author_stylesheets), the `revert` value rolls back the [cascade](/en-US/docs/Web/CSS/CSS_cascade/Cascade) to the user level, so that the [specified values](/en-US/docs/Web/CSS/CSS_cascade/Value_processing#specified_value) are calculated as if no author-level rules were specified for the element. For purposes of `revert`, the author origin includes the Override and Animation origins. + - If the rule belongs to the [user origin](/en-US/docs/Web/CSS/CSS_cascade/Cascade#user_stylesheets), the `revert` value rolls back the [cascade](/en-US/docs/Web/CSS/CSS_cascade/Cascade) to the user-agent level, so that the [specified values](/en-US/docs/Web/CSS/CSS_cascade/Value_processing#specified_value) are calculated as if no author-level or user-level rules were specified for the element. - If the rule belongs to the [user-agent origin](/en-US/docs/Web/CSS/CSS_cascade/Cascade#user-agent_stylesheets), the `revert` value acts like `unset`. - {{cssxref("revert-layer")}} - : Specifies that all the element's properties should roll back the cascade to a previous [cascade layer](/en-US/docs/Web/CSS/@layer), if one exists. If no other cascade layer exists, the element's properties will roll back to the matching rule, if one exists, in the current layer or to a previous [style origin](/en-US/docs/Glossary/Style_origin). diff --git a/files/en-us/web/css/anchor-name/index.md b/files/en-us/web/css/anchor-name/index.md index 205e3937e096716..0adbc83347a0425 100644 --- a/files/en-us/web/css/anchor-name/index.md +++ b/files/en-us/web/css/anchor-name/index.md @@ -52,7 +52,7 @@ To tether and place a positioned element in a specific location relative to an a You cannot associate a positioned element with an anchor element if the anchor is hidden, such as with {{cssxref("display", "display: none")}} or {{cssxref("visibility", "visibility: hidden")}}, or if the anchor is part of the [skipped contents](/en-US/docs/Web/CSS/CSS_containment/Using_CSS_containment#skips_its_contents) of another element due to it having {{cssxref("content-visibility", "content-visibility: hidden")}} set on it. -The `anchor-name` property is supported on all elements that generate a principal box. This means that [pseudo-elements](/en-US/docs/Web/CSS/Pseudo-elements), including generated content created using {{cssxref("::before")}} and {{cssxref("::after")}}, and UI features like the [`range` input](/en-US/docs/Web/HTML/Element/input/range) thumb ({{cssxref("::-webkit-slider-thumb")}}) can be anchor elements. Pseudo elements are implicitly anchored to the same element as the pseudo-element's originating element, unless otherwise specified. +The `anchor-name` property is supported on all elements that generate a principal box. This means that [pseudo-elements](/en-US/docs/Web/CSS/Pseudo-elements), including generated content created using {{cssxref("::before")}} and {{cssxref("::after")}}, and UI features like the [`range` input](/en-US/docs/Web/HTML/Reference/Elements/input/range) thumb ({{cssxref("::-webkit-slider-thumb")}}) can be anchor elements. Pseudo elements are implicitly anchored to the same element as the pseudo-element's originating element, unless otherwise specified. For more information on anchor features and usage, see the [CSS anchor positioning](/en-US/docs/Web/CSS/CSS_anchor_positioning) module landing page and the [Using CSS anchor positioning](/en-US/docs/Web/CSS/CSS_anchor_positioning/Using) guide. @@ -172,7 +172,7 @@ This example demonstrates how you can associate multiple positioned elements wit #### HTML -The HTML is the same as for the previous example, except this time we have multiple positioned element `<div>`s with different [`id`](/en-US/docs/Web/HTML/Global_attributes/id)s to identify them. +The HTML is the same as for the previous example, except this time we have multiple positioned element `<div>`s with different [`id`](/en-US/docs/Web/HTML/Reference/Global_attributes/id)s to identify them. ```html <p> @@ -386,6 +386,6 @@ Scroll the page to see how both of the infoboxes are tethered to the anchor. ## See also - {{cssxref("position-anchor")}} -- HTML [`anchor`](/en-US/docs/Web/HTML/Global_attributes/anchor) attribute +- HTML [`anchor`](/en-US/docs/Web/HTML/Reference/Global_attributes/anchor) attribute - [CSS anchor positioning](/en-US/docs/Web/CSS/CSS_anchor_positioning) module - [Using CSS anchor positioning](/en-US/docs/Web/CSS/CSS_anchor_positioning/Using) guide diff --git a/files/en-us/web/css/anchor-size/index.md b/files/en-us/web/css/anchor-size/index.md index 75a31d2f01e1822..d43054a6cff2909 100644 --- a/files/en-us/web/css/anchor-size/index.md +++ b/files/en-us/web/css/anchor-size/index.md @@ -108,7 +108,7 @@ The length returned is the vertical or horizontal size of an anchor element or i The anchor element used as the basis for the dimension length is the element with the `anchor-name` specified in the `<anchor-name>` parameter. If more than one element has the same anchor name, the last element with that anchor name in the DOM order is used. -If no `<anchor-name>` parameter is included in the function call, the element's **default anchor**, referenced in its [`position-anchor`](/en-US/docs/Web/CSS/position-anchor) property, or associated with the element via the [`anchor`](/en-US/docs/Web/HTML/Global_attributes/anchor) HTML attribute, is used. +If no `<anchor-name>` parameter is included in the function call, the element's **default anchor**, referenced in its [`position-anchor`](/en-US/docs/Web/CSS/position-anchor) property, or associated with the element via the [`anchor`](/en-US/docs/Web/HTML/Reference/Global_attributes/anchor) HTML attribute, is used. If an `<anchor-name>` parameter is included and there are no elements matching that anchor name, the fallback value is used. If no fallback was included, the declaration is ignored. For example, if `width: anchor-size(--foo width, 50px); height: anchor-size(--foo width);` were specified on the positioned element but no anchor named `--foo` exists in the DOM, the `width` would be `50px` and the `height` declaration would have no effect. diff --git a/files/en-us/web/css/anchor/index.md b/files/en-us/web/css/anchor/index.md index 9527f058293aa4b..7c23760bec90467 100644 --- a/files/en-us/web/css/anchor/index.md +++ b/files/en-us/web/css/anchor/index.md @@ -42,10 +42,10 @@ The parameters are: - `<anchor-name>` {{optional_inline}} - - : The [`anchor-name`](/en-US/docs/Web/CSS/anchor-name) property value of an anchor element you want to position the element's side relative to. This is a `<dashed-ident>` value. If omitted, the element's **default anchor**, referenced in its [`position-anchor`](/en-US/docs/Web/CSS/position-anchor) property, or associated with the element via the [`anchor`](/en-US/docs/Web/HTML/Global_attributes/anchor) HTML attribute, is used. + - : The [`anchor-name`](/en-US/docs/Web/CSS/anchor-name) property value of an anchor element you want to position the element's side relative to. This is a `<dashed-ident>` value. If omitted, the element's **default anchor**, referenced in its [`position-anchor`](/en-US/docs/Web/CSS/position-anchor) property, or associated with the element via the [`anchor`](/en-US/docs/Web/HTML/Reference/Global_attributes/anchor) HTML attribute, is used. > [!NOTE] - > Specifying an `<anchor-name>` inside an `anchor()` function does not associate an element with an anchor; it only positions the element relative to that anchor. The [`position-anchor`](/en-US/docs/Web/CSS/position-anchor) CSS property or the [`anchor`](/en-US/docs/Web/HTML/Global_attributes/anchor) HTML attribute is still needed to create the association. + > Specifying an `<anchor-name>` inside an `anchor()` function does not associate an element with an anchor; it only positions the element relative to that anchor. The [`position-anchor`](/en-US/docs/Web/CSS/position-anchor) CSS property or the [`anchor`](/en-US/docs/Web/HTML/Reference/Global_attributes/anchor) HTML attribute is still needed to create the association. - `<anchor-side>` @@ -87,7 +87,7 @@ The `anchor()` function enables positioning an element relative to the edges of It returns a `<length>` value specifying the distance between the anchor-positioned element side specified by the inset value, and the side of the anchor element specified by the chosen `<anchor-side>` value. As it returns a `<length>`, it can be used within [other CSS functions](/en-US/docs/Web/CSS/CSS_Values_and_Units/CSS_Value_Functions) that accept length values, including {{cssxref("calc()")}}, {{cssxref("clamp()")}}, etc. -If no anchor with the name specified by the `<anchor-name>` exists, or if the positioned element does not have an anchor associated with it (i.e. via the {{cssxref("position-anchor")}} property), the first parameter is considered invalid and the fallback `<length-percentage>` value is used if one is available. For example, if `top: anchor(bottom, 50px)` were specified on the positioned element but no anchor was associated with it, the fallback value would be used, so `top` would get a computed value of `50px`. +If no anchor with the name specified by the `<anchor-name>` exists, or if the positioned element does not have an anchor associated with it (i.e., via the {{cssxref("position-anchor")}} property), the first parameter is considered invalid and the fallback `<length-percentage>` value is used if one is available. For example, if `top: anchor(bottom, 50px)` were specified on the positioned element but no anchor was associated with it, the fallback value would be used, so `top` would get a computed value of `50px`. For detailed information on anchor features and usage, see the [CSS anchor positioning](/en-US/docs/Web/CSS/CSS_anchor_positioning) module landing page and the [Using CSS anchor positioning](/en-US/docs/Web/CSS/CSS_anchor_positioning/Using) guide. @@ -160,7 +160,7 @@ This example positions the positioned element's logical block end edge `10px` fr You can position an element relative to multiple anchors by specifying different `<anchor-name>` values inside the `anchor()` function of different inset properties on the same element (see [Element positioned relative to multiple anchors](#element_positioned_relative_to_multiple_anchors) below). This can be used to create useful functionality such as drag handles at the corners of a positioned element that can be used to resize it. -While a positioned element can be positioned relative to more than one anchor element, it is only ever associated with the single anchor defined via its [`position-anchor`](/en-US/docs/Web/CSS/position-anchor) property (or the [`anchor`](/en-US/docs/Web/HTML/Global_attributes/anchor) HTML attribute). This is the anchor the element will scroll with when the page scrolls; it can also be used to control when the element is [conditionally hidden](/en-US/docs/Web/CSS/CSS_anchor_positioning/Try_options_hiding#conditionally_hiding_anchor-positioned_elements). +While a positioned element can be positioned relative to more than one anchor element, it is only ever associated with the single anchor defined via its [`position-anchor`](/en-US/docs/Web/CSS/position-anchor) property (or the [`anchor`](/en-US/docs/Web/HTML/Reference/Global_attributes/anchor) HTML attribute). This is the anchor the element will scroll with when the page scrolls; it can also be used to control when the element is [conditionally hidden](/en-US/docs/Web/CSS/CSS_anchor_positioning/Try_options_hiding#conditionally_hiding_anchor-positioned_elements). ## Formal syntax @@ -384,7 +384,7 @@ This example positions an element relative to two different anchors, which are u #### HTML -We specify three {{htmlelement("div")}} elements in total. The first two have a class of `anchor` and will be defined as anchors; each one has an individual `id` that will be used to provide them with different positioning information. The last `<div>` has a class of `infobox` and will be defined as the positioned element. We include the [`tabindex`](/en-US/docs/Web/HTML/Global_attributes/tabindex) attribute to enable them to receive keyboard focus. +We specify three {{htmlelement("div")}} elements in total. The first two have a class of `anchor` and will be defined as anchors; each one has an individual `id` that will be used to provide them with different positioning information. The last `<div>` has a class of `infobox` and will be defined as the positioned element. We include the [`tabindex`](/en-US/docs/Web/HTML/Reference/Global_attributes/tabindex) attribute to enable them to receive keyboard focus. ```html <div id="anchor1" class="anchor" tabindex="0">⚓︎1</div> @@ -473,16 +473,16 @@ function makeDraggable(elem) { elem.addEventListener("keyup", (e) => { switch (e.key) { case "d": - elem.style.left = elem.offsetLeft + 5 + "px"; + elem.style.left = `${elem.offsetLeft + 5}px`; break; case "a": - elem.style.left = elem.offsetLeft - 5 + "px"; + elem.style.left = `${elem.offsetLeft - 5}px`; break; case "w": - elem.style.top = elem.offsetTop - 5 + "px"; + elem.style.top = `${elem.offsetTop - 5}px`; break; case "s": - elem.style.top = elem.offsetTop + 5 + "px"; + elem.style.top = `${elem.offsetTop + 5}px`; break; } e.preventDefault(); @@ -496,8 +496,8 @@ function makeDraggable(elem) { pos3 = e.offsetLeft; pos4 = e.offsetTop; // set the element's new position: - elem.style.top = elem.offsetTop - pos2 + "px"; - elem.style.left = elem.offsetLeft - pos1 + "px"; + elem.style.top = `${elem.offsetTop - pos2}px`; + elem.style.left = `${elem.offsetLeft - pos1}px`; } function dragMouseDown(e) { @@ -516,8 +516,8 @@ function makeDraggable(elem) { pos3 = e.clientX; pos4 = e.clientY; // set the element's new position: - elem.style.top = elem.offsetTop - pos2 + "px"; - elem.style.left = elem.offsetLeft - pos1 + "px"; + elem.style.top = `${elem.offsetTop - pos2}px`; + elem.style.left = `${elem.offsetLeft - pos1}px`; } function closeDragElement() { diff --git a/files/en-us/web/css/angle/index.md b/files/en-us/web/css/angle/index.md index a50ccc1ded0f807..657ac0cd3d99830 100644 --- a/files/en-us/web/css/angle/index.md +++ b/files/en-us/web/css/angle/index.md @@ -9,7 +9,41 @@ browser-compat: css.types.angle The **`<angle>`** [CSS](/en-US/docs/Web/CSS) [data type](/en-US/docs/Web/CSS/CSS_Values_and_Units/CSS_data_types) represents an angle value expressed in degrees, gradians, radians, or turns. It is used, for example, in {{cssxref("&lt;gradient&gt;")}}s and in some {{cssxref("transform")}} functions. -{{EmbedInteractiveExample("pages/css/type-angle.html")}} +{{InteractiveExample("CSS Demo: &amp;lt;angle&amp;gt;")}} + +```css interactive-example-choice +transform: rotate(45deg); +``` + +```css interactive-example-choice +transform: rotate(3.1416rad); +``` + +```css interactive-example-choice +transform: rotate(-50grad); +``` + +```css interactive-example-choice +transform: rotate(1.75turn); +``` + +```html interactive-example +<section class="default-example" id="default-example"> + <div class="transition-all" id="example-element"> + This box can rotate to different angles. + </div> +</section> +``` + +```css interactive-example +#example-element { + background-color: #0118f3; + padding: 0.75em; + width: 180px; + height: 120px; + color: white; +} +``` ## Syntax diff --git a/files/en-us/web/css/animation-composition/index.md b/files/en-us/web/css/animation-composition/index.md index 1a0b02001cdd5a8..45d0cc93870c429 100644 --- a/files/en-us/web/css/animation-composition/index.md +++ b/files/en-us/web/css/animation-composition/index.md @@ -163,9 +163,9 @@ Here the underlying value is `translateX(50px) rotate(45deg)`. {{EmbedLiveSample("Reversing the animation direction","100%","250")}} -- With `replace`, the final effect value for the `transform` property in the `0%, 20%` keyframe is `translateX(100px)` (completely replacing the underlying value `translateX(30px) rotate(45deg)`). In this case, the element rotates from 45deg to 0deg as it animates from the default value set on the element itself to the non-rotated value set at the 0% mark. This is the default behavior. -- With `add`, the final effect value for the `transform` property in the `0%, 20%` keyframe is `translateX(30px) rotate(45deg)` followed by `translateX(100px)`. So the element is moved `30px` to the right, rotated `45deg`, then translated `100px` more along the redirected X axis. -- With `accumulate`, the final effect value in the `0%, 20%` keyframe is `translateX(130px) rotate(45deg)`. This means that the two X-axis translation values of `30px` and `100px` are combined or "accumulated". +- With `replace`, the final effect value for the `transform` property in the `20%, 40%` keyframe is `translateX(100px)` (completely replacing the underlying value `translateX(30px) rotate(45deg)`). In this case, the element rotates from 45deg to 0deg as it animates from the default value set on the element itself to the non-rotated value set at the 20% mark. This is the default behavior. +- With `add`, the final effect value for the `transform` property in the `20%, 40%` keyframe is `translateX(30px) rotate(45deg) translateX(100px)`. So the element is first moved 100px to the right, rotated 45deg around the origin, then moved to the right by 30px. +- With `accumulate`, the final effect value in the `20%, 40%` keyframe is `translateX(130px) rotate(45deg)`. This means that the two X-axis translation values of `30px` and `100px` are combined or "accumulated". ## Specifications diff --git a/files/en-us/web/css/animation-delay/index.md b/files/en-us/web/css/animation-delay/index.md index 26ca7d078036a13..ab2630671b4eebb 100644 --- a/files/en-us/web/css/animation-delay/index.md +++ b/files/en-us/web/css/animation-delay/index.md @@ -9,7 +9,106 @@ browser-compat: css.properties.animation-delay The **`animation-delay`** [CSS](/en-US/docs/Web/CSS) property specifies the amount of time to wait from applying the animation to an element before beginning to perform the animation. The animation can start later, immediately from its beginning, or immediately and partway through the animation. -{{EmbedInteractiveExample("pages/css/animation-delay.html")}} +{{InteractiveExample("CSS Demo: animation-delay")}} + +```css interactive-example-choice +animation-delay: 250ms; +``` + +```css interactive-example-choice +animation-delay: 2s; +``` + +```css interactive-example-choice +animation-delay: -2s; +``` + +```html interactive-example +<section class="flex-column" id="default-example"> + <div>Animation <span id="play-status"></span></div> + <div id="example-element">Select a delay to start!</div> +</section> +``` + +```css interactive-example +#example-element { + background-color: #1766aa; + color: white; + margin: auto; + margin-left: 0; + border: 5px solid #333; + width: 150px; + height: 150px; + border-radius: 50%; + display: flex; + justify-content: center; + align-items: center; + flex-direction: column; +} + +#play-status { + font-weight: bold; +} + +.animating { + animation-name: slide; + animation-duration: 3s; + animation-timing-function: ease-in; + animation-iteration-count: 2; + animation-direction: alternate; +} + +@keyframes slide { + from { + background-color: orange; + color: black; + margin-left: 0; + } + to { + background-color: orange; + color: black; + margin-left: 80%; + } +} +``` + +```js interactive-example +"use strict"; + +window.addEventListener("load", () => { + const el = document.getElementById("example-element"); + const status = document.getElementById("play-status"); + + function update() { + status.textContent = "delaying"; + el.className = ""; + window.requestAnimationFrame(() => { + window.requestAnimationFrame(() => { + el.className = "animating"; + }); + }); + } + + el.addEventListener("animationstart", () => { + status.textContent = "playing"; + }); + + el.addEventListener("animationend", () => { + status.textContent = "finished"; + }); + + const observer = new MutationObserver(() => { + update(); + }); + + observer.observe(el, { + attributes: true, + attributeFilter: ["style"], + }); + + update(); +}); +``` It is often convenient to use the shorthand property {{cssxref("animation")}} to set all animation properties at once. diff --git a/files/en-us/web/css/animation-direction/index.md b/files/en-us/web/css/animation-direction/index.md index 37ee070c80c0854..e1ae466b08e3494 100644 --- a/files/en-us/web/css/animation-direction/index.md +++ b/files/en-us/web/css/animation-direction/index.md @@ -9,7 +9,88 @@ browser-compat: css.properties.animation-direction The **`animation-direction`** [CSS](/en-US/docs/Web/CSS) property sets whether an animation should play forward, backward, or alternate back and forth between playing the sequence forward and backward. -{{EmbedInteractiveExample("pages/css/animation-direction.html")}} +{{InteractiveExample("CSS Demo: animation-direction")}} + +```css interactive-example-choice +animation-direction: normal; +``` + +```css interactive-example-choice +animation-direction: reverse; +``` + +```css interactive-example-choice +animation-direction: alternate; +``` + +```css interactive-example-choice +animation-direction: alternate-reverse; +``` + +```html interactive-example +<section class="flex-column" id="default-example"> + <div id="example-element"></div> + <button id="play-pause">Play</button> +</section> +``` + +```css interactive-example +#example-element { + animation-duration: 3s; + animation-iteration-count: infinite; + animation-name: slide; + animation-play-state: paused; + animation-timing-function: ease-in; + background-color: #1766aa; + border-radius: 50%; + border: 5px solid #333; + color: white; + height: 150px; + margin: auto; + margin-left: 0; + width: 150px; +} + +#example-element.running { + animation-play-state: running; +} + +#play-pause { + font-size: 2rem; +} + +@keyframes slide { + from { + background-color: orange; + color: black; + margin-left: 0; + } + to { + background-color: orange; + color: black; + margin-left: 80%; + } +} +``` + +```js interactive-example +"use strict"; + +window.addEventListener("load", () => { + const el = document.getElementById("example-element"); + const button = document.getElementById("play-pause"); + + button.addEventListener("click", () => { + if (el.classList.contains("running")) { + el.classList.remove("running"); + button.textContent = "Play"; + } else { + el.classList.add("running"); + button.textContent = "Pause"; + } + }); +}); +``` It is often convenient to use the shorthand property {{cssxref("animation")}} to set all animation properties at once. diff --git a/files/en-us/web/css/animation-duration/index.md b/files/en-us/web/css/animation-duration/index.md index efb2cdeb78dc040..74c26bceb3f9f03 100644 --- a/files/en-us/web/css/animation-duration/index.md +++ b/files/en-us/web/css/animation-duration/index.md @@ -9,7 +9,84 @@ browser-compat: css.properties.animation-duration The **`animation-duration`** [CSS](/en-US/docs/Web/CSS) property sets the length of time that an animation takes to complete one cycle. -{{EmbedInteractiveExample("pages/css/animation-duration.html")}} +{{InteractiveExample("CSS Demo: animation-duration")}} + +```css interactive-example-choice +animation-duration: 750ms; +``` + +```css interactive-example-choice +animation-duration: 3s; +``` + +```css interactive-example-choice +animation-duration: 0s; +``` + +```html interactive-example +<section class="flex-column" id="default-example"> + <div class="animating" id="example-element"></div> + <button id="play-pause">Play</button> +</section> +``` + +```css interactive-example +#example-element { + animation-direction: alternate; + animation-iteration-count: infinite; + animation-name: slide; + animation-play-state: paused; + animation-timing-function: ease-in; + background-color: #1766aa; + border-radius: 50%; + border: 5px solid #333; + color: white; + height: 150px; + margin: auto; + margin-left: 0; + width: 150px; +} + +#example-element.running { + animation-play-state: running; +} + +#play-pause { + font-size: 2rem; +} + +@keyframes slide { + from { + background-color: orange; + color: black; + margin-left: 0; + } + to { + background-color: orange; + color: black; + margin-left: 80%; + } +} +``` + +```js interactive-example +"use strict"; + +window.addEventListener("load", () => { + const el = document.getElementById("example-element"); + const button = document.getElementById("play-pause"); + + button.addEventListener("click", () => { + if (el.classList.contains("running")) { + el.classList.remove("running"); + button.textContent = "Play"; + } else { + el.classList.add("running"); + button.textContent = "Pause"; + } + }); +}); +``` It is often convenient to use the shorthand property {{ cssxref("animation") }} to set all animation properties at once. diff --git a/files/en-us/web/css/animation-fill-mode/index.md b/files/en-us/web/css/animation-fill-mode/index.md index 11d9fa58236d31f..ea938c3e8834e19 100644 --- a/files/en-us/web/css/animation-fill-mode/index.md +++ b/files/en-us/web/css/animation-fill-mode/index.md @@ -9,7 +9,111 @@ browser-compat: css.properties.animation-fill-mode The **`animation-fill-mode`** [CSS](/en-US/docs/Web/CSS) property sets how a CSS animation applies styles to its target before and after its execution. -{{EmbedInteractiveExample("pages/css/animation-fill-mode.html")}} +{{InteractiveExample("CSS Demo: animation-fill-mode")}} + +```css interactive-example-choice +animation-fill-mode: none; +animation-delay: 1s; +``` + +```css interactive-example-choice +animation-fill-mode: forwards; +animation-delay: 1s; +``` + +```css interactive-example-choice +animation-fill-mode: backwards; +animation-delay: 1s; +``` + +```css interactive-example-choice +animation-fill-mode: both; +animation-delay: 1s; +``` + +```html interactive-example +<section class="flex-column" id="default-example"> + <div>Animation <span id="play-status"></span></div> + <div id="example-element">Select a mode to start!</div> +</section> +``` + +```css interactive-example +#example-element { + background-color: #1766aa; + color: white; + margin: auto; + margin-left: 0; + border: 5px solid #333; + width: 150px; + height: 150px; + border-radius: 50%; + + display: flex; + justify-content: center; + align-items: center; + flex-direction: column; +} + +#play-status { + font-weight: bold; +} + +.animating { + animation: slide 1s ease-in 1; +} + +@keyframes slide { + from { + background-color: orange; + color: black; + margin-left: 0; + } + to { + background-color: orange; + color: black; + margin-left: 80%; + } +} +``` + +```js interactive-example +"use strict"; + +window.addEventListener("load", () => { + const el = document.getElementById("example-element"); + const status = document.getElementById("play-status"); + + function update() { + status.textContent = "delaying"; + el.className = ""; + window.requestAnimationFrame(() => { + window.requestAnimationFrame(() => { + el.className = "animating"; + }); + }); + } + + el.addEventListener("animationstart", () => { + status.textContent = "playing"; + }); + + el.addEventListener("animationend", () => { + status.textContent = "finished"; + }); + + const observer = new MutationObserver(() => { + update(); + }); + + observer.observe(el, { + attributes: true, + attributeFilter: ["style"], + }); + + update(); +}); +``` It is often convenient to use the shorthand property {{cssxref("animation")}} to set all animation properties at once. diff --git a/files/en-us/web/css/animation-iteration-count/index.md b/files/en-us/web/css/animation-iteration-count/index.md index 9b9c9f2025fa5c0..ed15f7f4034eb93 100644 --- a/files/en-us/web/css/animation-iteration-count/index.md +++ b/files/en-us/web/css/animation-iteration-count/index.md @@ -9,7 +9,104 @@ browser-compat: css.properties.animation-iteration-count The **`animation-iteration-count`** [CSS](/en-US/docs/Web/CSS) property sets the number of times an animation sequence should be played before stopping. -{{EmbedInteractiveExample("pages/css/animation-iteration-count.html")}} +{{InteractiveExample("CSS Demo: animation-iteration-count")}} + +```css interactive-example-choice +animation-iteration-count: 0; +``` + +```css interactive-example-choice +animation-iteration-count: 2; +``` + +```css interactive-example-choice +animation-iteration-count: 1.5; +``` + +```html interactive-example +<section class="flex-column" id="default-example"> + <div>Animation <span id="play-status"></span></div> + <div id="example-element">Select a count to start!</div> +</section> +``` + +```css interactive-example +#example-element { + align-items: center; + background-color: #1766aa; + border-radius: 50%; + border: 5px solid #333; + color: white; + display: flex; + flex-direction: column; + height: 150px; + justify-content: center; + margin: auto; + margin-left: 0; + width: 150px; +} + +#play-status { + font-weight: bold; +} + +.animating { + animation-name: slide; + animation-duration: 3s; + animation-timing-function: ease-in; +} + +@keyframes slide { + from { + background-color: orange; + color: black; + margin-left: 0; + } + to { + background-color: orange; + color: black; + margin-left: 80%; + } +} +``` + +```js interactive-example +"use strict"; + +window.addEventListener("load", () => { + const el = document.getElementById("example-element"); + const status = document.getElementById("play-status"); + + function update() { + status.textContent = "delaying"; + el.className = ""; + window.requestAnimationFrame(() => { + window.requestAnimationFrame(() => { + el.className = "animating"; + }); + }); + } + + el.addEventListener("animationstart", () => { + status.textContent = "playing"; + }); + + el.addEventListener("animationend", () => { + status.textContent = "finished"; + }); + + const observer = new MutationObserver(() => { + update(); + }); + + observer.observe(el, { + attributes: true, + attributeFilter: ["style"], + }); + + update(); +}); +``` It is often convenient to use the shorthand property {{cssxref("animation")}} to set all animation properties at once. diff --git a/files/en-us/web/css/animation-name/index.md b/files/en-us/web/css/animation-name/index.md index 832c5102f68e732..6e500fcacc30ce6 100644 --- a/files/en-us/web/css/animation-name/index.md +++ b/files/en-us/web/css/animation-name/index.md @@ -7,9 +7,70 @@ browser-compat: css.properties.animation-name {{CSSRef}} -The **`animation-name`** [CSS](/en-US/docs/Web/CSS) property specifies the names of one or more {{cssxref("@keyframes")}} at-rules that describe the animation to apply to an element. Multiple `@keyframe` at-rules are specified as a comma-separated list of names. If the specified name does not match any `@keyframe` at-rule, no properties are animated. +The **`animation-name`** [CSS](/en-US/docs/Web/CSS) property specifies the names of one or more {{cssxref("@keyframes")}} at-rules that describe the animation to apply to an element. Multiple `@keyframes` at-rules are specified as a comma-separated list of names. If the specified name does not match any `@keyframes` at-rule, no properties are animated. -{{EmbedInteractiveExample("pages/css/animation-name.html")}} +{{InteractiveExample("CSS Demo: animation-name")}} + +```css interactive-example-choice +animation-name: none; +``` + +```css interactive-example-choice +animation-name: slide; +``` + +```css interactive-example-choice +animation-name: bounce; +``` + +```html interactive-example +<section class="flex-column" id="default-example"> + <div class="animating" id="example-element"></div> +</section> +``` + +```css interactive-example +#example-element { + animation-direction: alternate; + animation-duration: 1s; + animation-iteration-count: infinite; + animation-timing-function: ease-in; + background-color: #1766aa; + border-radius: 50%; + border: 5px solid #333; + color: white; + height: 150px; + margin: auto; + margin-left: 0; + width: 150px; +} + +@keyframes slide { + from { + background-color: orange; + color: black; + margin-left: 0; + } + to { + background-color: orange; + color: black; + margin-left: 80%; + } +} + +@keyframes bounce { + from { + background-color: orange; + color: black; + margin-top: 0; + } + to { + background-color: orange; + color: black; + margin-top: 40%; + } +} +``` It is often convenient to use the shorthand property {{cssxref("animation")}} to set all animation properties at once. diff --git a/files/en-us/web/css/animation-play-state/index.md b/files/en-us/web/css/animation-play-state/index.md index b4900c254612b3c..1a38d8de844e91b 100644 --- a/files/en-us/web/css/animation-play-state/index.md +++ b/files/en-us/web/css/animation-play-state/index.md @@ -9,7 +9,55 @@ browser-compat: css.properties.animation-play-state The **`animation-play-state`** [CSS](/en-US/docs/Web/CSS) property sets whether an animation is running or paused. -{{EmbedInteractiveExample("pages/css/animation-play-state.html")}} +{{InteractiveExample("CSS Demo: animation-play-state")}} + +```css interactive-example-choice +animation-play-state: paused; +``` + +```css interactive-example-choice +animation-play-state: running; +``` + +```html interactive-example +<section class="flex-column" id="default-example"> + <div class="animating" id="example-element"></div> +</section> +``` + +```css interactive-example +#example-element { + background-color: #1766aa; + color: white; + margin: auto; + margin-left: 0; + border: 5px solid #333; + width: 150px; + height: 150px; + border-radius: 50%; +} + +.animating { + animation-name: slide; + animation-duration: 3s; + animation-timing-function: ease-in; + animation-iteration-count: infinite; + animation-direction: alternate; +} + +@keyframes slide { + from { + background-color: orange; + color: black; + margin-left: 0; + } + to { + background-color: orange; + color: black; + margin-left: 80%; + } +} +``` Resuming a paused animation will start the animation from where it left off at the time it was paused, rather than starting over from the beginning of the animation sequence. diff --git a/files/en-us/web/css/animation-range-end/index.md b/files/en-us/web/css/animation-range-end/index.md index 1e00deb24a6db23..3aae742c8eb7b54 100644 --- a/files/en-us/web/css/animation-range-end/index.md +++ b/files/en-us/web/css/animation-range-end/index.md @@ -9,7 +9,7 @@ browser-compat: css.properties.animation-range-end {{CSSRef}}{{SeeCompatTable}} -The **`animation-range-end`** [CSS](/en-US/docs/Web/CSS) property is used to set the end of an animation's attachment range along its timeline, i.e. where along the timeline an animation will end. +The **`animation-range-end`** [CSS](/en-US/docs/Web/CSS) property is used to set the end of an animation's attachment range along its timeline, i.e., where along the timeline an animation will end. The `animation-range-end` and {{cssxref("animation-range-start")}} properties can also be set using the [`animation-range`](/en-US/docs/Web/CSS/animation-range) shorthand property. diff --git a/files/en-us/web/css/animation-range-start/index.md b/files/en-us/web/css/animation-range-start/index.md index 1f1a69d339e5693..215d6b18441c61c 100644 --- a/files/en-us/web/css/animation-range-start/index.md +++ b/files/en-us/web/css/animation-range-start/index.md @@ -9,7 +9,7 @@ browser-compat: css.properties.animation-range-start {{CSSRef}}{{SeeCompatTable}} -The **`animation-range-start`** [CSS](/en-US/docs/Web/CSS) property is used to set the start of an animation's attachment range along its timeline, i.e. where along the timeline an animation will start. +The **`animation-range-start`** [CSS](/en-US/docs/Web/CSS) property is used to set the start of an animation's attachment range along its timeline, i.e., where along the timeline an animation will start. The `animation-range-start` and {{cssxref("animation-range-end")}} properties can also be set using the [`animation-range`](/en-US/docs/Web/CSS/animation-range) shorthand property. @@ -147,7 +147,7 @@ Last, an animation is specified on the element that animates its opacity and sca } to { - opacity: 1, + opacity: 1; transform: scaleX(1); } } diff --git a/files/en-us/web/css/animation-range/index.md b/files/en-us/web/css/animation-range/index.md index 6224f92b870d69a..5cfce5666cf5ed3 100644 --- a/files/en-us/web/css/animation-range/index.md +++ b/files/en-us/web/css/animation-range/index.md @@ -9,7 +9,7 @@ browser-compat: css.properties.animation-range {{CSSRef}}{{SeeCompatTable}} -The **`animation-range`** [CSS](/en-US/docs/Web/CSS) [shorthand property](/en-US/docs/Web/CSS/CSS_cascade/Shorthand_properties) is used to set the start and end of an animation's attachment range along its timeline, i.e. where along the timeline an animation will start and end. +The **`animation-range`** [CSS](/en-US/docs/Web/CSS) [shorthand property](/en-US/docs/Web/CSS/CSS_cascade/Shorthand_properties) is used to set the start and end of an animation's attachment range along its timeline, i.e., where along the timeline an animation will start and end. ## Constituent properties @@ -204,7 +204,7 @@ Last, an animation is specified on the element that animates its opacity and sca } to { - opacity: 1, + opacity: 1; transform: scaleX(1); } } diff --git a/files/en-us/web/css/animation-timing-function/index.md b/files/en-us/web/css/animation-timing-function/index.md index d6e50c11355bc31..94e1ea21cef6591 100644 --- a/files/en-us/web/css/animation-timing-function/index.md +++ b/files/en-us/web/css/animation-timing-function/index.md @@ -9,7 +9,87 @@ browser-compat: css.properties.animation-timing-function The **`animation-timing-function`** [CSS](/en-US/docs/Web/CSS) property sets how an animation progresses through the duration of each cycle. -{{EmbedInteractiveExample("pages/css/animation-timing-function.html")}} +{{InteractiveExample("CSS Demo: animation-timing-function")}} + +```css interactive-example-choice +animation-timing-function: linear; +``` + +```css interactive-example-choice +animation-timing-function: ease-in-out; +``` + +```css interactive-example-choice +animation-timing-function: steps(5, end); +``` + +```css interactive-example-choice +animation-timing-function: cubic-bezier(0.1, -0.6, 0.2, 0); +``` + +```html interactive-example +<section class="flex-column" id="default-example"> + <div class="animating" id="example-element"></div> + <button id="play-pause">Play</button> +</section> +``` + +```css interactive-example +#example-element { + animation-duration: 3s; + animation-iteration-count: infinite; + animation-name: slide; + animation-play-state: paused; + background-color: #1766aa; + border-radius: 50%; + border: 5px solid #333; + color: white; + height: 150px; + margin: auto; + margin-left: 0; + width: 150px; +} + +#example-element.running { + animation-play-state: running; +} + +#play-pause { + font-size: 2rem; +} + +@keyframes slide { + from { + background-color: orange; + color: black; + margin-left: 0; + } + to { + background-color: orange; + color: black; + margin-left: 80%; + } +} +``` + +```js interactive-example +"use strict"; + +window.addEventListener("load", () => { + const el = document.getElementById("example-element"); + const button = document.getElementById("play-pause"); + + button.addEventListener("click", () => { + if (el.classList.contains("running")) { + el.classList.remove("running"); + button.textContent = "Play"; + } else { + el.classList.add("running"); + button.textContent = "Pause"; + } + }); +}); +``` It is often convenient to use the shorthand property {{cssxref("animation")}} to set all animation properties at once. @@ -506,5 +586,5 @@ The following image shows graphs of all the `step()` function values used in thi - [Using CSS animations](/en-US/docs/Web/CSS/CSS_animations/Using_CSS_animations) - {{cssxref('easing-function')}} - JavaScript {{domxref("AnimationEvent")}} API -- [Cubic bézier generation tool](https://cubic-bezier.com) +- [Cubic bézier generation tool](https://cubic-bezier.com/) - Other related animation properties: {{cssxref("animation")}}, {{cssxref("animation-composition")}}, {{cssxref("animation-delay")}}, {{cssxref("animation-direction")}}, {{cssxref("animation-duration")}}, {{cssxref("animation-fill-mode")}}, {{cssxref("animation-iteration-count")}}, {{cssxref("animation-name")}}, {{cssxref("animation-play-state")}}, {{cssxref("animation-timeline")}} diff --git a/files/en-us/web/css/animation/index.md b/files/en-us/web/css/animation/index.md index 060df87de72ebbc..5c7d72c2530d8a2 100644 --- a/files/en-us/web/css/animation/index.md +++ b/files/en-us/web/css/animation/index.md @@ -9,7 +9,49 @@ browser-compat: css.properties.animation The **`animation`** [shorthand](/en-US/docs/Web/CSS/CSS_cascade/Shorthand_properties) [CSS](/en-US/docs/Web/CSS) property applies an animation between styles. It is a shorthand for {{cssxref("animation-name")}}, {{cssxref("animation-duration")}}, {{cssxref("animation-timing-function")}}, {{cssxref("animation-delay")}}, {{cssxref("animation-iteration-count")}}, {{cssxref("animation-direction")}}, {{cssxref("animation-fill-mode")}}, {{cssxref("animation-play-state")}}, and {{cssxref("animation-timeline")}}. -{{EmbedInteractiveExample("pages/css/animation.html")}} +{{InteractiveExample("CSS Demo: animation")}} + +```css interactive-example-choice +animation: 3s ease-in 1s infinite reverse both running slide-in; +``` + +```css interactive-example-choice +animation: 3s linear 1s infinite running slide-in; +``` + +```css interactive-example-choice +animation: 3s linear 1s infinite alternate slide-in; +``` + +```css interactive-example-choice +animation: 0.5s linear 1s infinite alternate slide-in; +``` + +```html interactive-example +<section class="flex-column" id="default-example"> + <div id="example-element"></div> +</section> +``` + +```css interactive-example +#example-element { + background-color: #1766aa; + margin: 20px; + border: 5px solid #333; + width: 150px; + height: 150px; + border-radius: 50%; +} + +@keyframes slide-in { + from { + margin-left: -20%; + } + to { + margin-left: 100%; + } +} +``` ## Constituent properties @@ -93,7 +135,7 @@ Consider providing a mechanism for pausing or disabling animation as well as usi - [Designing Safer Web Animation For Motion Sensitivity · An A List Apart Article](https://alistapart.com/article/designing-safer-web-animation-for-motion-sensitivity/) - [An Introduction to the Reduced Motion Media Query | CSS-Tricks](https://css-tricks.com/introduction-reduced-motion-media-query/) - [Responsive Design for Motion | WebKit](https://webkit.org/blog/7551/responsive-design-for-motion/) -- [MDN Understanding WCAG, Guideline 2.2 explanations](/en-US/docs/Web/Accessibility/Understanding_WCAG/Operable#guideline_2.2_%e2%80%94_enough_time_provide_users_enough_time_to_read_and_use_content) +- [MDN Understanding WCAG, Guideline 2.2 explanations](/en-US/docs/Web/Accessibility/Guides/Understanding_WCAG/Operable#guideline_2.2_%e2%80%94_enough_time_provide_users_enough_time_to_read_and_use_content) - [Understanding Success Criterion 2.2.2 | W3C Understanding WCAG 2.0](https://www.w3.org/TR/UNDERSTANDING-WCAG20/time-limits-pause.html) ## Formal definition diff --git a/files/en-us/web/css/appearance/index.md b/files/en-us/web/css/appearance/index.md index bd584509f5aa1df..9c650de73499ec9 100644 --- a/files/en-us/web/css/appearance/index.md +++ b/files/en-us/web/css/appearance/index.md @@ -9,7 +9,34 @@ browser-compat: css.properties.appearance The **`appearance`** [CSS](/en-US/docs/Web/CSS) property is used to display UI elements with platform-specific styling, based on the operating system's theme. -{{EmbedInteractiveExample("pages/css/appearance.html")}} +{{InteractiveExample("CSS Demo: appearance")}} + +```css interactive-example-choice +appearance: none; +``` + +```css interactive-example-choice +appearance: auto; +``` + +```html interactive-example +<section id="default-example"> + <div class="background"> + <button id="example-element">button</button> + </div> +</section> +``` + +```css interactive-example +.background { + display: flex; + place-content: center; + place-items: center; + width: 150px; + height: 150px; + background-color: white; +} +``` Before standardization, this property allowed elements to be shown as widgets, such as buttons or check boxes. It was considered a misfeature and authors are encouraged to use only standard keywords now. @@ -24,6 +51,7 @@ appearance: none; appearance: auto; appearance: menulist-button; appearance: textfield; +appearance: base-select; /* Global values */ appearance: inherit; @@ -50,6 +78,13 @@ Some examples are provided, but the list is not exhaustive. - : Acts as `none` on elements with no special styling. +- `base-select` + + - : Opts the {{htmlelement("select")}} element and the {{cssxref("::picker()", "::picker(select)")}} pseudo-element into the browser-defined default (base) styles and behavior for [customizable select elements](/en-US/docs/Learn_web_development/Extensions/Forms/Customizable_select). + + > [!NOTE] + > The specification currently defines the `base` value, which is intended to apply base browser styles more generally for UI elements they are available for. However, this is not currently supported in any browser. + - `<compat-special>` - : One of `menulist-button` or `textfield`. @@ -213,6 +248,25 @@ select.none { {{EmbedLiveSample("Apply_custom_styling", 1050, 100)}} +### Basic custom select usage + +To opt-in to custom select functionality, the `<select>` element and its picker both need to have an `appearance` value of `base-select` set on them: + +```css +select, +::picker(select) { + appearance: base-select; +} +``` + +You could then, for example, remove the picker's default black {{cssxref("border")}}: + +```css +::picker(select) { + border: none; +} +``` + ## Specifications {{Specifications}} diff --git a/files/en-us/web/css/aspect-ratio/index.md b/files/en-us/web/css/aspect-ratio/index.md index 9fcf3964d8a41a5..fc9afa212c66fd4 100644 --- a/files/en-us/web/css/aspect-ratio/index.md +++ b/files/en-us/web/css/aspect-ratio/index.md @@ -11,7 +11,41 @@ The **`aspect-ratio`** [CSS](/en-US/docs/Web/CSS) property allows you to define At least one of the box's sizes needs to be automatic in order for `aspect-ratio` to have any effect. If neither the width nor height is an automatic size, then the provided aspect ratio has no effect on the box's preferred sizes. -{{EmbedInteractiveExample("pages/css/aspect-ratio.html")}} +{{InteractiveExample("CSS Demo: aspect-ratio")}} + +```css interactive-example-choice +aspect-ratio: auto; +``` + +```css interactive-example-choice +aspect-ratio: 1 / 1; +``` + +```css interactive-example-choice +aspect-ratio: 16 / 9; +``` + +```css interactive-example-choice +aspect-ratio: 0.5; +``` + +```html interactive-example +<section id="default-example"> + <img + class="transition-all" + height="640" + id="example-element" + src="/shared-assets/images/examples/plumeria.jpg" + width="466" /> +</section> +``` + +```css interactive-example +#example-element { + height: 100%; + width: auto; +} +``` ## Syntax @@ -31,7 +65,7 @@ aspect-ratio: revert-layer; aspect-ratio: unset; ``` -This property is specified as one or both of the keyword auto or a `<ratio>`. If both are given, and the element is a [replaced element](/en-US/docs/Web/CSS/Replaced_element), such as [`<img>`](/en-US/docs/Web/HTML/Element/img), then the given ratio is used until the content is loaded. After the content is loaded, the `auto` value is applied, so the intrinsic aspect ratio of the loaded content is used. +This property is specified as one or both of the keyword auto or a `<ratio>`. If both are given, and the element is a {{ glossary("replaced elements", "replaced element")}}, such as [`<img>`](/en-US/docs/Web/HTML/Reference/Elements/img), then the given ratio is used until the content is loaded. After the content is loaded, the `auto` value is applied, so the intrinsic aspect ratio of the loaded content is used. If the element is not a replaced element, then the given `ratio` is used. @@ -39,7 +73,7 @@ If the element is not a replaced element, then the given `ratio` is used. - `auto` - - : [Replaced elements](/en-US/docs/Web/CSS/Replaced_element) with an intrinsic aspect ratio use _that_ aspect ratio, otherwise the box has no preferred aspect ratio. Size calculations involving intrinsic aspect ratio always work with the content box dimensions. + - : {{glossary("Replaced elements")}} with an intrinsic aspect ratio use _that_ aspect ratio, otherwise the box has no preferred aspect ratio. Size calculations involving intrinsic aspect ratio always work with the content box dimensions. - {{cssxref("&lt;ratio&gt;")}} diff --git a/files/en-us/web/css/attr/index.md b/files/en-us/web/css/attr/index.md index e434e37b02f43b7..bd3a2d171945710 100644 --- a/files/en-us/web/css/attr/index.md +++ b/files/en-us/web/css/attr/index.md @@ -46,7 +46,7 @@ attr(href) /* With type */ attr(data-width px) attr(data-size rem) -attr(data-name string) +attr(data-name raw-string) attr(id type(<custom-ident>)) attr(data-count type(<number>)) attr(data-size type(<length> | <percentage>)) @@ -71,14 +71,17 @@ The parameters are: - : The attribute name whose value should be retrieved from the selected HTML element(s). - `<attr-type>` - - : Specifies how the attribute value is parsed into a CSS value. This can be the `string` keyword, a `type()` function, or a CSS dimension unit. When omitted, it defaults to `string`. + - : Specifies how the attribute value is parsed into a CSS value. This can be the `raw-string` keyword, a `type()` function, or a CSS dimension unit (specified using an `<attr-unit>` identifier). When omitted, it defaults to `raw-string`. - - The `string` keyword parses the value into a CSS string. + - The `raw-string` keyword causes the attribute's literal value to be treated as the value of a CSS string, with no CSS parsing performed (including CSS escapes, whitespace removal, comments, etc). The `<fallback-value>` is only used if the attribute is omitted; specifying an empty value doesn't trigger the fallback. ```css - attr(data-name string, "stranger") + attr(data-name raw-string, "stranger") ``` + > [!NOTE] + > This keyword was originally named and supported in Chromium browsers as `string`. Both keywords will be supported briefly, for backwards compatibility purposes. + - The `type()` function takes a `<syntax>` as its argument that specifies what [data type](/en-US/docs/Web/CSS/CSS_Values_and_Units/CSS_data_types) to parse the value into. The `<syntax>` can be {{CSSxRef("&lt;angle&gt;")}}, {{CSSxRef("&lt;color&gt;")}}, {{CSSxRef("&lt;custom-ident&gt;")}}, {{CSSxRef("&lt;image&gt;")}}, {{CSSxRef("&lt;integer&gt;")}}, {{CSSxRef("&lt;length&gt;")}}, {{CSSxRef("&lt;length-percentage&gt;")}}, {{CSSxRef("&lt;number&gt;")}}, {{CSSxRef("&lt;percentage&gt;")}}, {{CSSxRef("&lt;resolution&gt;")}}, {{CSSxRef("&lt;string&gt;")}}, {{CSSxRef("&lt;time&gt;")}}, {{CSSxRef("&lt;transform-function&gt;")}}, or a combination thereof. ```css @@ -92,7 +95,14 @@ The parameters are: attr(data-size type(<length> | <percentage>), 0px) ``` - For [security reasons](#limitations_and_security) {{CSSxRef("url_value", "&lt;url&gt;")}} is not allowed as a `<syntax>`. + > [!NOTE] + > For [security reasons](#limitations_and_security) {{CSSxRef("url_value", "&lt;url&gt;")}} is not allowed as a `<syntax>`. + + To accept any data type, use `*` as the type. This still triggers CSS parsing but with no requirements placed on it beyond that it parses validly and substitutes the result of that parsing directly as tokens, rather than as a `<string>` value. + + ```css + attr(data-content type(*)) + ``` - The `<attr-unit>` identifier specifies the unit a numeric value should have (if any). It can be the `%` character (percentage) or a [CSS distance unit](/en-US/docs/Web/CSS/CSS_Values_and_Units/Numeric_data_types#distance_units) such as `px`, `rem`, `deg`, `s`, etc. @@ -117,23 +127,24 @@ If no `<fallback-value>` is set, the return value will default to an empty strin ### Limitations and security -The `attr()` function can reference attributes that were never intended by the page author to be used for styling, and might contain sensitive information (for example, a security token used by scripts on the page). In general, this is fine, but it can become a security threat when used in URLs. You therefore can't use `attr()` to dynamically construct URLs. +The `attr()` function can reference attributes that were never intended by the page author to be used for styling and might contain sensitive information (for example, a security token used by scripts on the page). In general, this is fine, but it can become a security threat when used in URLs. Therefore, you can't use `attr()` to dynamically construct URLs. ```html <!-- This won't work! --> <span data-icon="https://example.org/icons/question-mark.svg">help</span> -<style> - span[data-icon] { - background-image: url(attr(data-icon)); - } -</style> ``` -Values that use `attr()` get marked as _"`attr()`-tainted"_. Using an `attr()`-tainted value as or in a `<url>` makes a declaration become ["invalid at computed value time" or IACVT for short](https://brm.us/iacvt) +```css +span[data-icon] { + background-image: url(attr(data-icon)); +} +``` + +Values that use `attr()` get marked as _`attr()`-tainted_. Using an `attr()`-tainted value as or in a `<url>` makes a declaration become ["invalid at computed value time" or IACVT for short](https://www.bram.us/2024/02/26/css-what-is-iacvt/). ### Backwards compatibility -Generally speaking, the modern `attr()` syntax is backwards-compatible because the old way of using it — without specifying an `<attr-type>` — behaves the same as before. Having `attr(data-attr)` in your code is the same as writing `attr(data-attr type(<string>))` or the simpler `attr(data-attr string))`. +Generally speaking, the modern `attr()` syntax is backward-compatible because the old way of using it — without specifying an `<attr-type>` — behaves the same as before. Having `attr(data-attr)` in your code is the same as writing `attr(data-attr type(<string>))` or the simpler `attr(data-attr string))`. However, there are two edge cases where the modern `attr()` syntax behaves differently from the old syntax. @@ -152,7 +163,7 @@ div::before { } ``` -In browsers with support for the modern syntax, the output will be … nothing. Those browsers will successfully parse the second declaration but, because it is invalid content for the `content` property, the declaration becomes ["invalid at computed value time" or IACVT for short](https://brm.us/iacvt). +In browsers with support for the modern syntax, the output will be … nothing. Those browsers will successfully parse the second declaration, but because it is invalid content for the `content` property, the declaration becomes ["invalid at computed value time" or IACVT for short](https://www.bram.us/2024/02/26/css-what-is-iacvt/). To prevent this kind of situation, [feature detection](#feature_detection) is recommended. @@ -173,7 +184,7 @@ A second edge case is the following: Browsers without support for modern syntax display the text `"foo"`. In browsers with modern `attr()` support there is no output. -This is because `attr()` — similar to custom properties that use the `var()` function — get substituted at [computed value time](https://brm.us/iacvt/#custom-properties). With the modern behavior, `--x` first tries to read the `data-attr` attribute from the `#parent` element, which results in an empty string because there is no such attribute on `#parent`. That empty string then gets inherited by the `#child` element, resulting in a `content: ;` declaration being set. +This is because `attr()` — similar to custom properties that use the `var()` function — get substituted at [computed value time](https://www.bram.us/2024/02/26/css-what-is-iacvt/#custom-properties). With the modern behavior, `--x` first tries to read the `data-attr` attribute from the `#parent` element, which results in an empty string because there is no such attribute on `#parent`. That empty string then gets inherited by the `#child` element, resulting in a `content: ;` declaration being set. To prevent this sort of situation, don't pass inherited `attr()` values onto children unless you explicitly want to. @@ -213,7 +224,7 @@ if (!CSS.supports("x: attr(x type(*))")) { ### content property -In this example, we prepend the value of the `data-foo` [`data-*`](/en-US/docs/Web/HTML/Global_attributes/data-*) [global attribute](/en-US/docs/Web/HTML/Global_attributes) to the contents of the {{HTMLElement("p")}} element. +In this example, we prepend the value of the `data-foo` [`data-*`](/en-US/docs/Web/HTML/Reference/Global_attributes/data-*) [global attribute](/en-US/docs/Web/HTML/Reference/Global_attributes) to the contents of the {{HTMLElement("p")}} element. #### HTML @@ -237,7 +248,7 @@ In this example, we prepend the value of the `data-foo` [`data-*`](/en-US/docs/W {{SeeCompatTable}} -In this example, we append the value of `data-browser` [`data-*`](/en-US/docs/Web/HTML/Global_attributes/data-*) [global attribute](/en-US/docs/Web/HTML/Global_attributes) to the {{HTMLElement("p")}} element. If the `data-browser` attribute is missing from the {{HTMLElement("p")}} element, we append the _fallback_ value of "**Unknown**". +In this example, we append the value of `data-browser` [`data-*`](/en-US/docs/Web/HTML/Reference/Global_attributes/data-*) [global attribute](/en-US/docs/Web/HTML/Reference/Global_attributes) to the {{HTMLElement("p")}} element. If the `data-browser` attribute is missing from the {{HTMLElement("p")}} element, we append the _fallback_ value of "**Unknown**". #### HTML @@ -263,7 +274,7 @@ p::after { {{SeeCompatTable}} -In this example, we set the CSS value of {{CSSXRef("background-color")}} to the value of the `data-background` [`data-*`](/en-US/docs/Web/HTML/Global_attributes/data-*) [global attribute](/en-US/docs/Web/HTML/Global_attributes) assigned to the {{HTMLElement("div")}} element. +In this example, we set the CSS value of {{CSSXRef("background-color")}} to the value of the `data-background` [`data-*`](/en-US/docs/Web/HTML/Reference/Global_attributes/data-*) [global attribute](/en-US/docs/Web/HTML/Reference/Global_attributes) assigned to the {{HTMLElement("div")}} element. #### HTML @@ -493,5 +504,5 @@ document.querySelector("button").addEventListener("click", (e) => { ## See also - [Attribute selectors](/en-US/docs/Web/CSS/Attribute_selectors) -- [HTML `data-*` attributes](/en-US/docs/Web/HTML/Global_attributes/data-*) -- [SVG `data-*` attributes](/en-US/docs/Web/SVG/Attribute/data-*) +- [HTML `data-*` attributes](/en-US/docs/Web/HTML/Reference/Global_attributes/data-*) +- [SVG `data-*` attributes](/en-US/docs/Web/SVG/Reference/Attribute/data-*) diff --git a/files/en-us/web/css/attribute_selectors/index.md b/files/en-us/web/css/attribute_selectors/index.md index c3077e5a189816f..dc2fe35f962e764 100644 --- a/files/en-us/web/css/attribute_selectors/index.md +++ b/files/en-us/web/css/attribute_selectors/index.md @@ -61,7 +61,7 @@ a[class~="logo"] { ### Values - `<attr>` - - : An {{cssxref("ident")}}, that is, the unquoted name of the attribute. This can be any valid language-specific attribute (SVG, HTML, XML, etc), a [`data-*` attribute](/en-US/docs/Web/HTML/Global_attributes/data-*), or an author-created attribute. + - : An {{cssxref("ident")}}, that is, the unquoted name of the attribute. This can be any valid language-specific attribute (SVG, HTML, XML, etc), a [`data-*` attribute](/en-US/docs/Web/HTML/Reference/Global_attributes/data-*), or an author-created attribute. - `<value>` - : An {{cssxref("ident")}} or {{cssxref("string")}}, representing the attribute value. The value must be quoted if it contains spaces or special characters. - `s` or `i` @@ -71,7 +71,7 @@ a[class~="logo"] { The case sensitivity of attribute names and values depends on the document language. In HTML, attribute names are case-insensitive, as are spec-defined {{glossary("enumerated")}} values. The [case-insensitive HTML attribute values](https://html.spec.whatwg.org/multipage/semantics-other.html#case-sensitivity-of-selectors) are listed in the HTML spec. For these attributes, the attribute value in the selector is case-insensitive, regardless of whether the value is invalid or the attribute for the element on which it is set is invalid. -If the attribute value is case-sensitive, like [`class`](/en-US/docs/Web/HTML/Global_attributes/class), [`id`](/en-US/docs/Web/HTML/Global_attributes/id), and [`data-*`](/en-US/docs/Web/HTML/Global_attributes/data-*) attributes, the attribute selector value match is case-sensitive. Attributes defined outside of the HTML specification, like [`role`](/en-US/docs/Web/Accessibility/ARIA/Roles) and [`aria-*`](/en-US/docs/Web/Accessibility/ARIA/Attributes) attributes, are also case-sensitive. Case-sensitive attribute selectors can be made case-insensitive with the inclusion of the case-insensitive modifier (`i`). +If the attribute value is case-sensitive, like [`class`](/en-US/docs/Web/HTML/Reference/Global_attributes/class), [`id`](/en-US/docs/Web/HTML/Reference/Global_attributes/id), and [`data-*`](/en-US/docs/Web/HTML/Reference/Global_attributes/data-*) attributes, the attribute selector value match is case-sensitive. Attributes defined outside of the HTML specification, like [`role`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles) and [`aria-*`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes) attributes, are also case-sensitive. Case-sensitive attribute selectors can be made case-insensitive with the inclusion of the case-insensitive modifier (`i`). ## Examples @@ -190,7 +190,7 @@ div[data-lang="zh-Hant-TW"] { ### HTML ordered lists -The HTML specification requires the [`type`](/en-US/docs/Web/HTML/Element/input#type) attribute to be matched case-insensitively because it is primarily used in the {{HTMLElement("input")}} element. +The HTML specification requires the [`type`](/en-US/docs/Web/HTML/Reference/Elements/input#type) attribute to be matched case-insensitively because it is primarily used in the {{HTMLElement("input")}} element. Note that if a modifier is not supported by the user agent, then the selector will not match. #### CSS diff --git a/files/en-us/web/css/backdrop-filter/index.md b/files/en-us/web/css/backdrop-filter/index.md index 7b13c3f7fface61..5842e64c4c79920 100644 --- a/files/en-us/web/css/backdrop-filter/index.md +++ b/files/en-us/web/css/backdrop-filter/index.md @@ -9,7 +9,48 @@ browser-compat: css.properties.backdrop-filter The **`backdrop-filter`** [CSS](/en-US/docs/Web/CSS) property lets you apply graphical effects such as blurring or color shifting to the area behind an element. Because it applies to everything _behind_ the element, to see the effect the element or its background needs to be transparent or partially transparent. -{{EmbedInteractiveExample("pages/css/backdrop-filter.html")}} +{{InteractiveExample("CSS Demo: backdrop-filter()")}} + +```css interactive-example-choice +backdrop-filter: blur(10px); +``` + +```css interactive-example-choice +backdrop-filter: invert(80%); +``` + +```css interactive-example-choice +backdrop-filter: sepia(90%); +``` + +```html interactive-example +<section class="default-example" id="default-example"> + <div class="example-container"> + <div id="example-element">Example</div> + </div> +</section> +``` + +```css interactive-example +.example-container { + background-image: url("/shared-assets/images/examples/balloon.jpg"); + background-size: cover; + width: 200px; + height: 200px; + display: flex; + align-items: center; + justify-content: center; + color: black; +} + +#example-element { + font-weight: bold; + flex: 1; + text-align: center; + padding: 20px 10px; + background-color: rgba(255, 255, 255, 0.2); +} +``` ## Syntax @@ -48,7 +89,7 @@ backdrop-filter: unset; - `none` - : No filter is applied to the backdrop. - `<filter-value-list>` - - : A space-separated list of {{cssxref("&lt;filter-function&gt;")}}s or an [SVG filter](/en-US/docs/Web/SVG/Element/filter) that will be applied to the backdrop. CSS `<filter-function>`s include {{CSSxRef("filter-function/blur", "blur()")}}, {{CSSxRef("filter-function/brightness", "brightness()")}}, {{CSSxRef("filter-function/contrast", "contrast()")}}, {{CSSxRef("filter-function/drop-shadow", "drop-shadow()")}}, {{CSSxRef("filter-function/grayscale", "grayscale()")}}, {{CSSxRef("filter-function/hue-rotate", "hue-rotate()")}}, {{CSSxRef("filter-function/invert", "invert()")}}, {{CSSxRef("filter-function/opacity", "opacity()")}}, {{CSSxRef("filter-function/saturate", "saturate()")}}, and {{CSSxRef("filter-function/sepia", "sepia()")}}. + - : A space-separated list of {{cssxref("&lt;filter-function&gt;")}}s or an [SVG filter](/en-US/docs/Web/SVG/Reference/Element/filter) that will be applied to the backdrop. CSS `<filter-function>`s include {{CSSxRef("filter-function/blur", "blur()")}}, {{CSSxRef("filter-function/brightness", "brightness()")}}, {{CSSxRef("filter-function/contrast", "contrast()")}}, {{CSSxRef("filter-function/drop-shadow", "drop-shadow()")}}, {{CSSxRef("filter-function/grayscale", "grayscale()")}}, {{CSSxRef("filter-function/hue-rotate", "hue-rotate()")}}, {{CSSxRef("filter-function/invert", "invert()")}}, {{CSSxRef("filter-function/opacity", "opacity()")}}, {{CSSxRef("filter-function/saturate", "saturate()")}}, and {{CSSxRef("filter-function/sepia", "sepia()")}}. ## Formal definition diff --git a/files/en-us/web/css/backface-visibility/index.md b/files/en-us/web/css/backface-visibility/index.md index d35ea83eff3f3fe..ed8b6e41dc4214b 100644 --- a/files/en-us/web/css/backface-visibility/index.md +++ b/files/en-us/web/css/backface-visibility/index.md @@ -9,7 +9,73 @@ browser-compat: css.properties.backface-visibility The **`backface-visibility`** [CSS](/en-US/docs/Web/CSS) property sets whether the back face of an element is visible when turned towards the user. -{{EmbedInteractiveExample("pages/css/backface-visibility.html")}} +{{InteractiveExample("CSS Demo: backface-visibility")}} + +```css interactive-example-choice +backface-visibility: visible; +``` + +```css interactive-example-choice +backface-visibility: hidden; +``` + +```html interactive-example +<section class="default-example" id="default-example"> + <div id="example-element"> + <div class="face front">1</div> + <div class="face back">2</div> + <div class="face right">3</div> + <div class="face bottom">6</div> + </div> +</section> +``` + +```css interactive-example +#default-example { + background: linear-gradient(skyblue, khaki); +} + +#example-element { + width: 100px; + height: 100px; + perspective: 550px; + perspective-origin: 220% 220%; + transform-style: preserve-3d; +} + +.face { + display: flex; + align-items: center; + justify-content: center; + width: 100%; + height: 100%; + position: absolute; + backface-visibility: inherit; + background: rgba(0, 0, 0, 0.4); + font-size: 60px; + color: white; +} + +.front { + transform: translateZ(50px); +} + +.back { + background: rgb(230, 0, 0); + color: white; + transform: rotateY(180deg) translateZ(50px); +} + +.right { + background: rgba(0, 0, 0, 0.6); + transform: rotateY(90deg) translateZ(50px); +} + +.bottom { + background: rgba(0, 0, 0, 0.6); + transform: rotateX(-90deg) translateZ(50px); +} +``` An element's back face is a mirror image of its front face. Though invisible in 2D, the back face can become visible when a transformation causes the element to be rotated in 3D space. (This property has no effect on 2D transforms, which have no perspective.) diff --git a/files/en-us/web/css/background-attachment/index.md b/files/en-us/web/css/background-attachment/index.md index 850577207f8dbb8..848f201ec20a7c9 100644 --- a/files/en-us/web/css/background-attachment/index.md +++ b/files/en-us/web/css/background-attachment/index.md @@ -9,7 +9,71 @@ browser-compat: css.properties.background-attachment The **`background-attachment`** [CSS](/en-US/docs/Web/CSS) property sets whether a background image's position is fixed within the {{glossary("viewport")}}, or scrolls with its containing block. -{{EmbedInteractiveExample("pages/css/background-attachment.html")}} +{{InteractiveExample("CSS Demo: background-attachment")}} + +```css interactive-example-choice +background-attachment: scroll; +``` + +```css interactive-example-choice +background-attachment: fixed; +``` + +```css interactive-example-choice +background-attachment: local; +``` + +```css interactive-example-choice +background-attachment: local, scroll; +``` + +```css interactive-example-choice +background-attachment: scroll, local; +``` + +```html interactive-example +<section id="default-example"> + <div id="example-element"> + London. Michaelmas term lately over, and the Lord Chancellor sitting in + Lincoln's Inn Hall. Implacable November weather. As much mud in the streets + as if the waters had but newly retired from the face of the earth, and it + would not be wonderful to meet a Megalosaurus, forty feet long or so, + waddling like an elephantine lizard up Holborn Hill. London. Michaelmas term + lately over, and the Lord Chancellor sitting in Lincoln's Inn Hall. + Implacable November weather. As much mud in the streets as if the waters had + but newly retired from the face of the earth, and it would not be wonderful + to meet a Megalosaurus, forty feet long or so, waddling like an elephantine + lizard up Holborn Hill. + </div> +</section> +``` + +```css interactive-example +body { + overflow: scroll; +} + +#default-example { + height: 600px; +} + +#example-element { + max-width: 20rem; + height: 100%; + background: + url("/shared-assets/images/examples/lizard.png") right 3rem top 1rem / 15rem + no-repeat, + url("/shared-assets/images/examples/moon.jpg") center / 10rem; + color: #ff5454; + font-size: 1.5em; + font-weight: bold; + overflow: auto; + padding: 20px; + text-shadow: + 0 0 0.6rem #000, + 0 0 0.6rem #000; +} +``` ## Syntax @@ -48,7 +112,7 @@ The `background-attachment` property is specified as one of the keyword values f ## Examples -### Simple example +### Basic example #### HTML @@ -71,7 +135,7 @@ p { #### Result -{{EmbedLiveSample("Simple_example")}} +{{EmbedLiveSample("Basic_example")}} ### Multiple background images diff --git a/files/en-us/web/css/background-blend-mode/index.md b/files/en-us/web/css/background-blend-mode/index.md index f7123f5fc38238d..aab211d5982f812 100644 --- a/files/en-us/web/css/background-blend-mode/index.md +++ b/files/en-us/web/css/background-blend-mode/index.md @@ -9,7 +9,40 @@ browser-compat: css.properties.background-blend-mode The **`background-blend-mode`** [CSS](/en-US/docs/Web/CSS) property sets how an element's background images should blend with each other and with the element's background color. -{{EmbedInteractiveExample("pages/css/background-blend-mode.html")}} +{{InteractiveExample("CSS Demo: background-blend-mode")}} + +```css interactive-example-choice +background-blend-mode: normal; +``` + +```css interactive-example-choice +background-blend-mode: multiply; +``` + +```css interactive-example-choice +background-blend-mode: hard-light; +``` + +```css interactive-example-choice +background-blend-mode: difference; +``` + +```html interactive-example +<section class="default-example" id="default-example"> + <div class="example-container"> + <div class="transition-all" id="example-element"></div> + </div> +</section> +``` + +```css interactive-example +#example-element { + background-color: green; + background-image: url("/shared-assets/images/examples/balloon.jpg"); + width: 250px; + height: 305px; +} +``` Blending modes should be defined in the same order as the {{cssxref("background-image")}} property. If the blending modes' and background images' list lengths are not equal, it will be repeated and/or truncated until lengths match. @@ -97,7 +130,7 @@ document.getElementById("select").onchange = (event) => { console.log(document.getElementById("div")); ``` -{{ EmbedLiveSample('Examples', "330", "350") }} +{{ EmbedLiveSample('try_out_different_blend_modes', "330", "350") }} ## Specifications diff --git a/files/en-us/web/css/background-clip/index.md b/files/en-us/web/css/background-clip/index.md index 538d609db7af6d7..488b66a37a7f73e 100644 --- a/files/en-us/web/css/background-clip/index.md +++ b/files/en-us/web/css/background-clip/index.md @@ -9,15 +9,51 @@ browser-compat: css.properties.background-clip The **`background-clip`** [CSS](/en-US/docs/Web/CSS) property sets whether an element's background extends underneath its border box, padding box, or content box. -{{EmbedInteractiveExample("pages/css/background-clip.html")}} +{{InteractiveExample("CSS Demo: background-clip")}} + +```css interactive-example-choice +background-clip: border-box; +``` + +```css interactive-example-choice +background-clip: padding-box; +``` + +```css interactive-example-choice +background-clip: content-box; +``` + +```css interactive-example-choice +background-clip: text; +color: transparent; +text-shadow: none; +``` + +```html interactive-example +<section id="default-example"> + <div id="example-element">This is the content of the element.</div> +</section> +``` + +```css interactive-example +#example-element { + background-image: url("/shared-assets/images/examples/leopard.jpg"); + color: white; + text-shadow: 2px 2px black; + padding: 20px; + border: 10px dashed #333; + font-size: 2em; + font-weight: bold; +} +``` The background is always drawn behind the border, so `background-clip: border-box` has a visual effect only when the border is partially opaque or has transparent or partially opaque regions. Also, the `background-clip: text` property has little to no visual effect if the text is fully or partially opaque. > [!NOTE] -> Because the [root element](/en-US/docs/Web/HTML/Element/html) has a different background painting area, the `background-clip` property has no effect when specified on it. See "[The backgrounds of special elements.](https://drafts.csswg.org/css-backgrounds-3/#special-backgrounds)" +> Because the [root element](/en-US/docs/Web/HTML/Reference/Elements/html) has a different background painting area, the `background-clip` property has no effect when specified on it. See "[The backgrounds of special elements.](https://drafts.csswg.org/css-backgrounds-3/#special-backgrounds)" > [!NOTE] -> For documents whose [root element](/en-US/docs/Web/HTML/Element/html) is an HTML element: if the computed value of {{cssxref("background-image")}} on the root element is `none` and its {{cssxref("background-color")}} is `transparent`, user agents must instead propagate the computed values of the `background` properties from that element's first HTML {{HTMLElement("body")}} child element. The used values of that `<body>` element's `background` properties are their initial values, and the propagated values are treated as if they were specified on the root element. It is recommended that authors of HTML documents specify the canvas background for the `<body>` element rather than the HTML element. +> For documents whose [root element](/en-US/docs/Web/HTML/Reference/Elements/html) is an HTML element: if the computed value of {{cssxref("background-image")}} on the root element is `none` and its {{cssxref("background-color")}} is `transparent`, user agents must instead propagate the computed values of the `background` properties from that element's first HTML {{HTMLElement("body")}} child element. The used values of that `<body>` element's `background` properties are their initial values, and the propagated values are treated as if they were specified on the root element. It is recommended that authors of HTML documents specify the canvas background for the `<body>` element rather than the HTML element. ## Syntax diff --git a/files/en-us/web/css/background-color/index.md b/files/en-us/web/css/background-color/index.md index 875e5a3198f4f55..0890880a8fd73dd 100644 --- a/files/en-us/web/css/background-color/index.md +++ b/files/en-us/web/css/background-color/index.md @@ -9,7 +9,45 @@ browser-compat: css.properties.background-color The **`background-color`** [CSS](/en-US/docs/Web/CSS) property sets the background color of an element. -{{EmbedInteractiveExample("pages/css/background-color.html")}} +{{InteractiveExample("CSS Demo: background-color")}} + +```css interactive-example-choice +background-color: brown; +``` + +```css interactive-example-choice +background-color: #74992e; +``` + +```css interactive-example-choice +background-color: rgb(255, 255, 128); +``` + +```css interactive-example-choice +background-color: rgba(255, 255, 128, 0.5); +``` + +```css interactive-example-choice +background-color: hsl(50, 33%, 25%); +``` + +```css interactive-example-choice +background-color: hsla(50, 33%, 25%, 0.75); +``` + +```html interactive-example +<section id="default-example"> + <div class="transition-all" id="example-element"></div> +</section> +``` + +```css interactive-example +#example-element { + min-width: 100%; + min-height: 100%; + padding: 10%; +} +``` ## Syntax @@ -60,7 +98,7 @@ It is important to ensure that the contrast ratio between the background color a Color contrast ratio is determined by comparing the luminance of the text and background color values. In order to meet current [Web Content Accessibility Guidelines (WCAG)](https://www.w3.org/WAI/standards-guidelines/wcag/), a ratio of 4.5:1 is required for text content and 3:1 for larger text such as headings. Large text is defined as 18.66px and [bold](/en-US/docs/Web/CSS/font-weight) or larger, or 24px or larger. - [WebAIM: Color Contrast Checker](https://webaim.org/resources/contrastchecker/) -- [MDN Understanding WCAG, Guideline 1.4 explanations](/en-US/docs/Web/Accessibility/Understanding_WCAG/Perceivable#guideline_1.4_make_it_easier_for_users_to_see_and_hear_content_including_separating_foreground_from_background) +- [MDN Understanding WCAG, Guideline 1.4 explanations](/en-US/docs/Web/Accessibility/Guides/Understanding_WCAG/Perceivable#guideline_1.4_make_it_easier_for_users_to_see_and_hear_content_including_separating_foreground_from_background) - [Understanding Success Criterion 1.4.3 | W3C Understanding WCAG 2.0](https://www.w3.org/TR/UNDERSTANDING-WCAG20/visual-audio-contrast-contrast.html) ## Formal definition diff --git a/files/en-us/web/css/background-image/index.md b/files/en-us/web/css/background-image/index.md index b6574d65cc85f02..d7ec19cd430d907 100644 --- a/files/en-us/web/css/background-image/index.md +++ b/files/en-us/web/css/background-image/index.md @@ -9,7 +9,43 @@ browser-compat: css.properties.background-image The **`background-image`** [CSS](/en-US/docs/Web/CSS) property sets one or more background images on an element. -{{EmbedInteractiveExample("pages/css/background-image.html")}} +{{InteractiveExample("CSS Demo: background-image")}} + +```css interactive-example-choice +background-image: url("/shared-assets/images/examples/lizard.png"); +``` + +```css interactive-example-choice +background-image: + url("/shared-assets/images/examples/lizard.png"), + url("/shared-assets/images/examples/star.png"); +``` + +```css interactive-example-choice +background-image: + url("/shared-assets/images/examples/star.png"), + url("/shared-assets/images/examples/lizard.png"); +``` + +```css interactive-example-choice +background-image: + linear-gradient(rgba(0, 0, 255, 0.5), rgba(255, 255, 0, 0.5)), + url("/shared-assets/images/examples/lizard.png"); +``` + +```html interactive-example +<section id="default-example"> + <div id="example-element"></div> +</section> +``` + +```css interactive-example +#example-element { + min-width: 100%; + min-height: 100%; + padding: 10%; +} +``` The background images are drawn on stacking context layers on top of each other. The first layer specified is drawn as if it is closest to the user. @@ -55,7 +91,7 @@ To specify multiple background images, supply multiple values, separated by a co Browsers do not provide any special information on background images to assistive technology. This is important primarily for screen readers, as a screen reader will not announce its presence and therefore convey nothing to its users. If the image contains information critical to understanding the page's overall purpose, it is better to describe it semantically in the document. -- [MDN Understanding WCAG, Guideline 1.1 explanations](/en-US/docs/Web/Accessibility/Understanding_WCAG/Perceivable#guideline_1.1_—_providing_text_alternatives_for_non-text_content) +- [MDN Understanding WCAG, Guideline 1.1 explanations](/en-US/docs/Web/Accessibility/Guides/Understanding_WCAG/Perceivable#guideline_1.1_—_providing_text_alternatives_for_non-text_content) - [Understanding Success Criterion 1.1.1 | W3C Understanding WCAG 2.0](https://www.w3.org/TR/UNDERSTANDING-WCAG20/text-equiv-all.html) Additionally, it is important to ensure that the contrast ratio between the background image and the foreground text is high enough that people with low vision can read the page content. @@ -63,7 +99,7 @@ Additionally, it is important to ensure that the contrast ratio between the back Color contrast ratio is determined by comparing the luminance of the text and background color values. To meet [Web Content Accessibility Guidelines (WCAG)](https://www.w3.org/WAI/standards-guidelines/wcag/), a ratio of 4.5:1 is required for body text content and 3:1 for larger text such as headings. Large text is defined as 24px or larger, or [bolded](/en-US/docs/Web/CSS/font-weight) 18.66px or larger. - [WebAIM: Color Contrast Checker](https://webaim.org/resources/contrastchecker/) -- [Understanding WCAG, Guideline 1.4 explanation](/en-US/docs/Web/Accessibility/Understanding_WCAG/Perceivable#guideline_1.4_make_it_easier_for_users_to_see_and_hear_content_including_separating_foreground_from_background) +- [Understanding WCAG, Guideline 1.4 explanation](/en-US/docs/Web/Accessibility/Guides/Understanding_WCAG/Perceivable#guideline_1.4_make_it_easier_for_users_to_see_and_hear_content_including_separating_foreground_from_background) - [Understanding Success Criterion 1.4.3 | Understanding WCAG 2.0](https://www.w3.org/TR/UNDERSTANDING-WCAG20/visual-audio-contrast-contrast.html), W3C (2023) ## Formal definition diff --git a/files/en-us/web/css/background-origin/index.md b/files/en-us/web/css/background-origin/index.md index 504839f54e6b981..5a112ebdf11a614 100644 --- a/files/en-us/web/css/background-origin/index.md +++ b/files/en-us/web/css/background-origin/index.md @@ -9,7 +9,40 @@ browser-compat: css.properties.background-origin The **`background-origin`** [CSS](/en-US/docs/Web/CSS) property sets the background's origin: from the border start, inside the border, or inside the padding. -{{EmbedInteractiveExample("pages/css/background-origin.html")}} +{{InteractiveExample("CSS Demo: background-origin")}} + +```css interactive-example-choice +background-origin: border-box; +background-repeat: no-repeat; +``` + +```css interactive-example-choice +background-origin: padding-box; +background-repeat: no-repeat; +``` + +```css interactive-example-choice +background-origin: content-box; +background-repeat: no-repeat; +``` + +```html interactive-example +<section id="default-example"> + <div id="example-element">This is the content of the element.</div> +</section> +``` + +```css interactive-example +#example-element { + background-image: url("/shared-assets/images/examples/leopard.jpg"); + color: #d73611; + text-shadow: 2px 2px black; + padding: 20px; + border: 10px dashed #333; + font-size: 2em; + font-weight: bold; +} +``` Note that `background-origin` is ignored when {{cssxref("background-attachment")}} is `fixed`. @@ -36,7 +69,7 @@ The `background-origin` property is specified as one of the keyword values liste - `border-box` - : The background is positioned relative to the border box. - `padding-box` - - : The background is positioned relative to the padding box. + - : The background is positioned relative to the padding box. Default value. - `content-box` - : The background is positioned relative to the content box. diff --git a/files/en-us/web/css/background-position-x/index.md b/files/en-us/web/css/background-position-x/index.md index 63d0a26fd309a41..f60c4d77aedc259 100644 --- a/files/en-us/web/css/background-position-x/index.md +++ b/files/en-us/web/css/background-position-x/index.md @@ -9,7 +9,42 @@ browser-compat: css.properties.background-position-x The **`background-position-x`** [CSS](/en-US/docs/Web/CSS) property sets the initial horizontal position for each background image. The position is relative to the position layer set by {{cssxref("background-origin")}}. -{{EmbedInteractiveExample("pages/css/background-position-x.html")}} +{{InteractiveExample("CSS Demo: background-position-x")}} + +```css interactive-example-choice +background-position-x: left; +``` + +```css interactive-example-choice +background-position-x: center; +``` + +```css interactive-example-choice +background-position-x: 25%; +``` + +```css interactive-example-choice +background-position-x: 2rem; +``` + +```css interactive-example-choice +background-position-x: right 32px; +``` + +```html interactive-example +<section class="display-block" id="default-example"> + <div class="transition-all" id="example-element"></div> +</section> +``` + +```css interactive-example +#example-element { + background-color: navajowhite; + background-image: url("/shared-assets/images/examples/star.png"); + background-repeat: no-repeat; + height: 100%; +} +``` <!-- The source for this interactive example is stored in a GitHub repository. If you'd like to contribute to the interactive examples project, please clone https://github.com/mdn/interactive-examples and send us a pull request. --> @@ -73,7 +108,7 @@ The `background-position-x` property is specified as one or more values, separat ### Basic example -The following example shows a simple background image implementation, with background-position-x and background-position-y used to define the image's horizontal and vertical positions separately. +The following example shows a background image implementation, with background-position-x and background-position-y used to define the image's horizontal and vertical positions separately. #### HTML diff --git a/files/en-us/web/css/background-position-y/index.md b/files/en-us/web/css/background-position-y/index.md index 39f5834b796a28d..13015f31d3dd766 100644 --- a/files/en-us/web/css/background-position-y/index.md +++ b/files/en-us/web/css/background-position-y/index.md @@ -9,7 +9,42 @@ browser-compat: css.properties.background-position-y The **`background-position-y`** [CSS](/en-US/docs/Web/CSS) property sets the initial vertical position for each background image. The position is relative to the position layer set by {{cssxref("background-origin")}}. -{{EmbedInteractiveExample("pages/css/background-position-y.html")}} +{{InteractiveExample("CSS Demo: background-position-y")}} + +```css interactive-example-choice +background-position-y: top; +``` + +```css interactive-example-choice +background-position-y: center; +``` + +```css interactive-example-choice +background-position-y: 25%; +``` + +```css interactive-example-choice +background-position-y: 2rem; +``` + +```css interactive-example-choice +background-position-y: bottom 32px; +``` + +```html interactive-example +<section class="display-block" id="default-example"> + <div class="transition-all" id="example-element"></div> +</section> +``` + +```css interactive-example +#example-element { + background-color: navajowhite; + background-image: url("/shared-assets/images/examples/star.png"); + background-repeat: no-repeat; + height: 100%; +} +``` <!-- The source for this interactive example is stored in a GitHub repository. If you'd like to contribute to the interactive examples project, please clone https://github.com/mdn/interactive-examples and send us a pull request. --> @@ -73,7 +108,7 @@ The `background-position-y` property is specified as one or more values, separat ### Basic example -The following example shows a simple background image implementation, with background-position-x and background-position-y used to define the image's horizontal and vertical positions separately. +The following example shows a background image implementation, with background-position-x and background-position-y used to define the image's horizontal and vertical positions separately. #### HTML diff --git a/files/en-us/web/css/background-position/index.md b/files/en-us/web/css/background-position/index.md index c9635b851634383..d67b3a1307d5e04 100644 --- a/files/en-us/web/css/background-position/index.md +++ b/files/en-us/web/css/background-position/index.md @@ -9,7 +9,46 @@ browser-compat: css.properties.background-position The **`background-position`** [CSS](/en-US/docs/Web/CSS) property sets the initial position for each background image. The position is relative to the position layer set by {{cssxref("background-origin")}}. -{{EmbedInteractiveExample("pages/css/background-position.html")}} +{{InteractiveExample("CSS Demo: background-position")}} + +```css interactive-example-choice +background-position: top; +``` + +```css interactive-example-choice +background-position: left; +``` + +```css interactive-example-choice +background-position: center; +``` + +```css interactive-example-choice +background-position: 25% 75%; +``` + +```css interactive-example-choice +background-position: bottom 50px right 100px; +``` + +```css interactive-example-choice +background-position: right 35% bottom 45%; +``` + +```html interactive-example +<section class="display-block" id="default-example"> + <div class="transition-all" id="example-element"></div> +</section> +``` + +```css interactive-example +#example-element { + background-color: navajowhite; + background-image: url("/shared-assets/images/examples/star.png"); + background-repeat: no-repeat; + height: 100%; +} +``` ## Syntax diff --git a/files/en-us/web/css/background-repeat/favicon32.png b/files/en-us/web/css/background-repeat/favicon32.png deleted file mode 100644 index 04cf15ccc88b584..000000000000000 Binary files a/files/en-us/web/css/background-repeat/favicon32.png and /dev/null differ diff --git a/files/en-us/web/css/background-repeat/index.md b/files/en-us/web/css/background-repeat/index.md index e77f2cc19c09ef0..b3d51b80968086d 100644 --- a/files/en-us/web/css/background-repeat/index.md +++ b/files/en-us/web/css/background-repeat/index.md @@ -9,7 +9,45 @@ browser-compat: css.properties.background-repeat The **`background-repeat`** [CSS](/en-US/docs/Web/CSS) property sets how background images are repeated. A background image can be repeated along the horizontal and vertical axes, or not repeated at all. -{{EmbedInteractiveExample("pages/css/background-repeat.html")}} +{{InteractiveExample("CSS Demo: background-repeat")}} + +```css interactive-example-choice +background-repeat: repeat-x; +``` + +```css interactive-example-choice +background-repeat: repeat; +``` + +```css interactive-example-choice +background-repeat: space; +``` + +```css interactive-example-choice +background-repeat: round; +``` + +```css interactive-example-choice +background-repeat: no-repeat; +``` + +```css interactive-example-choice +background-repeat: space repeat; +``` + +```html interactive-example +<section id="default-example"> + <div id="example-element"></div> +</section> +``` + +```css interactive-example +#example-element { + background: #ccc url("/shared-assets/images/examples/moon.jpg") center / 120px; + min-width: 100%; + min-height: 100%; +} +``` ## Syntax @@ -38,18 +76,18 @@ background-repeat: unset; ## Description -The property accepts two [`<repeat-style>`](#values) keyterms, or one keyterm as a shorthand for the two values. When two values are provided, the first value defines the horizontal repetition behavior and the second value defines the vertical behavior. +The property accepts a comma-separated list of two [`<repeat-style>`](#values) keyterms, or one keyterm as a shorthand for the two values. When two values are provided, the first value defines the horizontal repetition behavior and the second value defines the vertical behavior. Property values can be used to repeat only horizontally, vertically, or not at all. -The default value is `repeat repeat`. With this value, the background image maintains its intrinsic {{glossary("aspect ratio")}}, repeating both horizontally and vertically to cover the entire background paint area, with edge images being clipped to the size of the element. Which edges clipped depends on the value of the {{cssxref("background-position")}}. How many times they are repeated and how much the images on the edges are clipped depends on the size of the background painting area and the {{cssxref("background-size")}}. +The default value is `repeat repeat`. With this value, the background image maintains its intrinsic {{glossary("aspect ratio")}}, repeating both horizontally and vertically to cover the entire background paint area, with edge images being clipped to the size of the element. Which edges clipped depends on the value of the corresponding {{cssxref("background-position")}} value. How many times they are repeated and how much the images on the edges are clipped depends on the size of the background painting area and the corresponding {{cssxref("background-size")}} value. -The repeating images can be evenly spaced apart, ensuring the repeated image maintains its aspect ratio without being clipped. With the `space` value, if the background paint area has a different aspect ratio than the image or does not otherwise have a size that a multiple of the background size in either direction, there will be areas not covered by the background image. +The repeating images can be evenly spaced apart, ensuring the repeated image maintains its aspect ratio without being clipped. With the `space` value, if the background paint area has a different aspect ratio than the image or does not otherwise have a size that is a multiple of the background size in either direction, there will be areas not covered by the background image. -Alternatively, the repeated background image can be stretched to cover the entire area without clipping. With `round`, the repeated image is stretched to fill all the available space until there is room to add an additional repeated image if the aspect ratio of the background image is not the same as the paint area's aspect ratio. For example, given a background image is 100px x 100px and a background paint area of 1099px x 750px, the image will be repeated 10 times in the horizontal direction and 7 times vertically, for a total of 70 repetitions, with each image stretched in both directions to be 109.9px x 105px. If the width of the paint area increases by 1px, becoming 1100px wide, an 11th image will fit horizontally for a total of 77 image repetitions, with each image being painted at 100px wide and 105px tall, stretched only in the vertical direction. +Alternatively, the repeated background image can be stretched to cover the entire area without clipping. With `round`, the repeated image is stretched to fill all the available space until there is room to add an additional repeated image if the aspect ratio of the background image is not the same as the paint area's aspect ratio. For example, given a background image that is 100px x 100px and a background paint area of 1099px x 750px, the image will be repeated 10 times in the horizontal direction and 7 times vertically, for a total of 70 repetitions, with each image stretched in both directions to be 109.9px x 105px, altering the image's aspect ratio and potentially distorting it. If the width of the paint area increases by 1px, becoming 1100px wide, an 11th image will fit horizontally for a total of 77 image repetitions, with each image being painted at 100px wide and 105px tall, stretched only in the vertical direction. ## Values -The property accepts up to two `<repeat-style>` keyterms. The first value is the horizontal repetition. The second value is the vertical behavior. If only a single value is set to a value other than `repeat-x` or `repeat-y`, that value is applied the both vertices. The values include: +The property accepts a comma-separated list of two `<repeat-style>` keyterms or one keyterm as a shorthand for the two values. The first value is the horizontal repetition. The second value is the vertical behavior. If only a single value is set to a value other than `repeat-x` or `repeat-y`, that value is applied the both vertices. The values include: - `repeat` @@ -173,7 +211,8 @@ div { /* Multiple images */ .seven { - background-image: url(star-solid.gif), url(favicon32.png); + background-image: + url(star-solid.gif), url(/shared-assets/images/examples/favicon32.png); background-repeat: repeat-x, repeat-y; height: 144px; } diff --git a/files/en-us/web/css/background-size/index.md b/files/en-us/web/css/background-size/index.md index 784f57388e09f81..d9fd412da74101b 100644 --- a/files/en-us/web/css/background-size/index.md +++ b/files/en-us/web/css/background-size/index.md @@ -10,7 +10,42 @@ browser-compat: css.properties.background-size The **`background-size`** [CSS](/en-US/docs/Web/CSS) property sets the size of the element's background image. The image can be left to its natural size, stretched, or constrained to fit the available space. -{{EmbedInteractiveExample("pages/css/background-size.html")}} +{{InteractiveExample("CSS Demo: background-size")}} + +```css interactive-example-choice +background-size: contain; +``` + +```css interactive-example-choice +background-size: contain; +background-repeat: no-repeat; +``` + +```css interactive-example-choice +background-size: cover; +``` + +```css interactive-example-choice +background-size: 30%; +``` + +```css interactive-example-choice +background-size: 200px 100px; +``` + +```html interactive-example +<section id="default-example"> + <div class="transition-all" id="example-element"></div> +</section> +``` + +```css interactive-example +#example-element { + background-image: url("/shared-assets/images/examples/hand.jpg"); + min-width: 100%; + min-height: 100%; +} +``` Spaces not covered by a background image are filled with the {{cssxref("background-color")}} property, and the background color will be visible behind background images that have transparency/translucency. @@ -105,7 +140,7 @@ Based on the intrinsic dimensions and proportions, the rendered size of the back - If the image has only one intrinsic dimension but has no intrinsic proportions, it's rendered using the specified dimension and the other dimension of the background positioning area. > [!NOTE] - > SVG images have a [`preserveAspectRatio`](/en-US/docs/Web/SVG/Attribute/preserveAspectRatio) attribute that defaults to the equivalent of `contain`; an explicit `background-size` causes `preserveAspectRatio` to be ignored. + > SVG images have a [`preserveAspectRatio`](/en-US/docs/Web/SVG/Reference/Attribute/preserveAspectRatio) attribute that defaults to the equivalent of `contain`; an explicit `background-size` causes `preserveAspectRatio` to be ignored. - **If the `background-size` has one `auto` component and one non-`auto` component:** diff --git a/files/en-us/web/css/background/index.md b/files/en-us/web/css/background/index.md index 351e6488366806d..ad10e0cb9e801ce 100644 --- a/files/en-us/web/css/background/index.md +++ b/files/en-us/web/css/background/index.md @@ -9,7 +9,45 @@ browser-compat: css.properties.background The **`background`** [shorthand](/en-US/docs/Web/CSS/CSS_cascade/Shorthand_properties) [CSS](/en-US/docs/Web/CSS) property sets all background style properties at once, such as color, image, origin and size, or repeat method. Component properties not set in the `background` shorthand property value declaration are set to their default values. -{{EmbedInteractiveExample("pages/css/background.html")}} +{{InteractiveExample("CSS Demo: background")}} + +```css interactive-example-choice +background: green; +``` + +```css interactive-example-choice +background: content-box radial-gradient(crimson, skyblue); +``` + +```css interactive-example-choice +background: no-repeat url("/shared-assets/images/examples/lizard.png"); +``` + +```css interactive-example-choice +background: left 5% / 15% 60% repeat-x + url("/shared-assets/images/examples/star.png"); +``` + +```css interactive-example-choice +background: + center / contain no-repeat + url("/shared-assets/images/examples/firefox-logo.svg"), + #eee 35% url("/shared-assets/images/examples/lizard.png"); +``` + +```html interactive-example +<section id="default-example"> + <div id="example-element"></div> +</section> +``` + +```css interactive-example +#example-element { + min-width: 100%; + min-height: 100%; + padding: 10%; +} +``` ## Constituent properties @@ -33,7 +71,7 @@ background: green; /* Using a <bg-image> and <repeat-style> */ background: url("test.jpg") repeat-y; -/* Using a <box> and <background-color> */ +/* Using a <visual-box> and <'background-color'> */ background: border-box red; /* A single image, centered and scaled */ @@ -55,25 +93,25 @@ The syntax of each layer is as follows: - `<attachment>` - `<bg-image>` - - `<position>` + - `<bg-position>` - `<bg-size>` - `<repeat-style>` -- The `<bg-size>` value may only be included immediately after `<position>`, separated with the '/' character, like this: `center/80%`. -- The `<box>` value may be included zero, one, or two times. If included once, it sets both {{cssxref("background-origin")}} and {{cssxref("background-clip")}}. If it is included twice, the first occurrence sets {{cssxref("background-origin")}}, and the second sets {{cssxref("background-clip")}}. -- The `<background-color>` value may only be included in the last layer specified. +- The `<bg-size>` value may only be included immediately after `<bg-position>`, separated with the '/' character, like this: `center/80%`. +- The `<visual-box>` value may be included zero, one, or two times. If included once, it sets both {{cssxref("background-origin")}} and {{cssxref("background-clip")}}. If it is included twice, the first occurrence sets {{cssxref("background-origin")}}, and the second sets {{cssxref("background-clip")}}. +- The `<'background-color'>` value may only be included in the last layer specified. ### Values - `<attachment>` - : See {{cssxref("background-attachment")}}. Default: `scroll`. -- `<box>` +- `<visual-box>` - : See {{cssxref("background-clip")}} and {{cssxref("background-origin")}}. Default: `border-box` and `padding-box` respectively. -- `<background-color>` +- `<'background-color'>` - : See {{cssxref("background-color")}}. Default: `transparent`. - `<bg-image>` - : See {{Cssxref("background-image")}}. Default: `none`. -- `<position>` +- `<bg-position>` - : See {{cssxref("background-position")}}. Default: 0% 0%. - `<repeat-style>` - : See {{cssxref("background-repeat")}}. Default: `repeat`. @@ -100,7 +138,7 @@ background: repeat scroll 0% 0% / auto padding-box border-box none transparent; Browsers do not provide any special information on background images to assistive technology. This is important primarily for screen readers, as a screen reader will not announce its presence and therefore convey nothing to its users. If the image contains information critical to understanding the page's overall purpose, it is better to describe it semantically in the document. -- [MDN Understanding WCAG, Guideline 1.1 explanations](/en-US/docs/Web/Accessibility/Understanding_WCAG/Perceivable#guideline_1.1_—_providing_text_alternatives_for_non-text_content) +- [MDN Understanding WCAG, Guideline 1.1 explanations](/en-US/docs/Web/Accessibility/Guides/Understanding_WCAG/Perceivable#guideline_1.1_—_providing_text_alternatives_for_non-text_content) - [Understanding Success Criterion 1.1.1 | W3C Understanding WCAG 2.0](https://www.w3.org/TR/UNDERSTANDING-WCAG20/text-equiv-all.html) ## Examples diff --git a/files/en-us/web/css/baseline-position/index.md b/files/en-us/web/css/baseline-position/index.md index a00159f949e2944..8f2e7552ec8766b 100644 --- a/files/en-us/web/css/baseline-position/index.md +++ b/files/en-us/web/css/baseline-position/index.md @@ -2,7 +2,7 @@ title: <baseline-position> slug: Web/CSS/baseline-position page-type: css-type -browser-compat: css.types.baseline-position +spec-urls: https://drafts.csswg.org/css-align/#typedef-baseline-position --- {{CSSRef}} @@ -36,10 +36,6 @@ The `<baseline-position>` enumerated value type is specified using an optional ` {{Specifications}} -## Browser compatibility - -{{Compat}} - ## See also - Properties that use this data type: {{cssxref("align-content")}}, {{cssxref("align-items")}}, {{cssxref("align-self")}}, {{cssxref("justify-items")}}, {{cssxref("justify-self")}}, {{cssxref("place-content")}}, {{cssxref("place-items")}}, and {{cssxref("place-self")}} diff --git a/files/en-us/web/css/basic-shape/circle/index.md b/files/en-us/web/css/basic-shape/circle/index.md index 942b7b502c5477c..a2934e7c4992c3b 100644 --- a/files/en-us/web/css/basic-shape/circle/index.md +++ b/files/en-us/web/css/basic-shape/circle/index.md @@ -9,7 +9,45 @@ browser-compat: css.types.basic-shape.circle The **`circle()`** CSS [function](/en-US/docs/Web/CSS/CSS_Values_and_Units/CSS_Value_Functions) defines a circle using a radius and a position. It is one of the {{cssxref("&lt;basic-shape&gt;")}} data types. -{{EmbedInteractiveExample("pages/css/function-circle.html")}} +{{InteractiveExample("CSS Demo: circle()")}} + +```css interactive-example-choice +clip-path: circle(50px); +``` + +```css interactive-example-choice +clip-path: circle(6rem at right center); +``` + +```css interactive-example-choice +clip-path: circle(10% at 2rem 90%); +``` + +```css interactive-example-choice +clip-path: circle(closest-side at 5rem 6rem); +``` + +```css interactive-example-choice +clip-path: circle(farthest-side); +``` + +```html interactive-example +<section class="default-example" id="default-example"> + <div class="transition-all" id="example-element"></div> +</section> +``` + +```css interactive-example +#default-example { + background: #fe9; +} + +#example-element { + background: linear-gradient(to bottom right, #f52, #05f); + width: 100%; + height: 100%; +} +``` ## Syntax diff --git a/files/en-us/web/css/basic-shape/ellipse/index.md b/files/en-us/web/css/basic-shape/ellipse/index.md index 58d79cb91f8f211..fd0de51041ef412 100644 --- a/files/en-us/web/css/basic-shape/ellipse/index.md +++ b/files/en-us/web/css/basic-shape/ellipse/index.md @@ -9,7 +9,41 @@ browser-compat: css.types.basic-shape.ellipse The **`ellipse()`** [CSS](/en-US/docs/Web/CSS) function is one of the {{cssxref("&lt;basic-shape&gt;")}} [data types](/en-US/docs/Web/CSS/CSS_Values_and_Units/CSS_data_types). -{{EmbedInteractiveExample("pages/css/function-ellipse.html")}} +{{InteractiveExample("CSS Demo: ellipse()")}} + +```css interactive-example-choice +clip-path: ellipse(20px 50px); +``` + +```css interactive-example-choice +clip-path: ellipse(4rem 50% at right center); +``` + +```css interactive-example-choice +clip-path: ellipse(closest-side closest-side at 5rem 6rem); +``` + +```css interactive-example-choice +clip-path: ellipse(closest-side farthest-side); +``` + +```html interactive-example +<section class="default-example" id="default-example"> + <div class="transition-all" id="example-element"></div> +</section> +``` + +```css interactive-example +#default-example { + background: #fe9; +} + +#example-element { + background: linear-gradient(to bottom right, #f52, #05f); + width: 100%; + height: 100%; +} +``` ## Syntax diff --git a/files/en-us/web/css/basic-shape/index.md b/files/en-us/web/css/basic-shape/index.md index bd3890485f28bce..5764a3724a7a84b 100644 --- a/files/en-us/web/css/basic-shape/index.md +++ b/files/en-us/web/css/basic-shape/index.md @@ -9,7 +9,56 @@ browser-compat: css.types.basic-shape The **`<basic-shape>`** [CSS](/en-US/docs/Web/CSS) [data type](/en-US/docs/Web/CSS/CSS_Values_and_Units/CSS_data_types) represents a shape used in the {{cssxref("clip-path")}}, {{cssxref("shape-outside")}}, and {{cssxref("offset-path")}} properties. -{{EmbedInteractiveExample("pages/css/type-basic-shape.html")}} +{{InteractiveExample("CSS Demo: &amp;lt;basic-shape&amp;gt;")}} + +```css interactive-example-choice +clip-path: inset(22% 12% 15px 35px); +``` + +```css interactive-example-choice +clip-path: circle(6rem at 12rem 8rem); +``` + +```css interactive-example-choice +clip-path: ellipse(115px 55px at 50% 40%); +``` + +```css interactive-example-choice +clip-path: polygon( + 50% 2.4%, + 34.5% 33.8%, + 0% 38.8%, + 25% 63.1%, + 19.1% 97.6%, + 50% 81.3%, + 80.9% 97.6%, + 75% 63.1%, + 100% 38.8%, + 65.5% 33.8% +); +``` + +```css interactive-example-choice +clip-path: path("M 50,245 A 160,160 0,0,1 360,120 z"); +``` + +```html interactive-example +<section class="default-example" id="default-example"> + <div class="transition-all" id="example-element"></div> +</section> +``` + +```css interactive-example +#default-example { + background: #fe9; +} + +#example-element { + background: linear-gradient(to bottom right, #f52, #05f); + width: 100%; + height: 100%; +} +``` ## Syntax @@ -101,13 +150,13 @@ The function takes a list of comma-separated coordinate pairs, each consisting o ### Syntax for paths -The {{cssxref("basic-shape/path","path()")}} function defines a shape using an SVG {{SVGAttr("fill-rule")}} and an SVG [path definition](/en-US/docs/Web/SVG/Attribute/d). +The {{cssxref("basic-shape/path","path()")}} function defines a shape using an SVG {{SVGAttr("fill-rule")}} and an SVG [path definition](/en-US/docs/Web/SVG/Reference/Attribute/d). ```plain path( <'fill-rule'>? , <string> ) ``` -The required `<string>` is an [SVG path](/en-US/docs/Web/SVG/Attribute/d) as a quoted string. The `path()` function is not a valid {{cssxref("shape-outside")}} property value. +The required `<string>` is an [SVG path](/en-US/docs/Web/SVG/Reference/Attribute/d) as a quoted string. The `path()` function is not a valid {{cssxref("shape-outside")}} property value. ### Syntax for shapes @@ -117,7 +166,7 @@ The {{cssxref("basic-shape/shape","shape()")}} function defines a shape using an shape( <'fill-rule'>? from <coordinate-pair> , <shape-command># ) ``` -The `from <coordinate-pair>` parameter represents the starting point for the first shape command, and `<shape-command>` defines one or more shape commands, which are similar to the [SVG path commands](/en-US/docs/Web/SVG/Attribute/d#path_commands). The `shape()` function is not a valid {{cssxref("shape-outside")}} property value. +The `from <coordinate-pair>` parameter represents the starting point for the first shape command, and `<shape-command>` defines one or more shape commands, which are similar to the [SVG path commands](/en-US/docs/Web/SVG/Reference/Attribute/d#path_commands). The `shape()` function is not a valid {{cssxref("shape-outside")}} property value. ## Description @@ -148,7 +197,7 @@ Each value in the lists of the two `<basic-shape>` functions is interpolated bas - **Both shapes are of type `polygon()`**: Interpolation is applied between each corresponding value if they use the same `<fill-rule>` and have the same number of comma-separated coordinate pairs. -- **Both shapes are of type `path()`**: Interpolation is applied to each parameter as a {{cssxref("&lt;number&gt;")}} if the path strings in both the shapes match the number, type, and sequence of [path data commands](/en-US/docs/Web/SVG/Attribute/d#path_commands). +- **Both shapes are of type `path()`**: Interpolation is applied to each parameter as a {{cssxref("&lt;number&gt;")}} if the path strings in both the shapes match the number, type, and sequence of [path data commands](/en-US/docs/Web/SVG/Reference/Attribute/d#path_commands). - **Both shapes are of type `shape()`**: Interpolation is applied between each corresponding value if they have the identical command keyword and use the same `<by-to>` keyword. If `shape()` is used in the {{cssxref("clip-path")}} property, the two shapes interpolate if they also have the same `<fill-rule>`. diff --git a/files/en-us/web/css/basic-shape/inset/index.md b/files/en-us/web/css/basic-shape/inset/index.md index 5610d99302aa97c..e03ea413f8a4143 100644 --- a/files/en-us/web/css/basic-shape/inset/index.md +++ b/files/en-us/web/css/basic-shape/inset/index.md @@ -9,7 +9,41 @@ browser-compat: css.types.basic-shape.inset The **`inset()`** [CSS](/en-US/docs/Web/CSS) function defines a rectangle at the specified inset distances from each side of the reference box. It is a basic shape function used to define one of the {{cssxref("&lt;basic-shape&gt;")}} [data types](/en-US/docs/Web/CSS/CSS_Values_and_Units/CSS_data_types). -{{EmbedInteractiveExample("pages/css/function-inset.html")}} +{{InteractiveExample("CSS Demo: inset()")}} + +```css interactive-example-choice +clip-path: inset(30px); +``` + +```css interactive-example-choice +clip-path: inset(1rem 2rem 3rem 4rem); +``` + +```css interactive-example-choice +clip-path: inset(20% 30% round 20px); +``` + +```css interactive-example-choice +clip-path: inset(4rem 20% round 1rem 2rem 3rem 4rem); +``` + +```html interactive-example +<section class="default-example" id="default-example"> + <div class="transition-all" id="example-element"></div> +</section> +``` + +```css interactive-example +#default-example { + background: #fe9; +} + +#example-element { + background: linear-gradient(to bottom right, #f52, #05f); + width: 100%; + height: 100%; +} +``` ## Syntax diff --git a/files/en-us/web/css/basic-shape/path/index.md b/files/en-us/web/css/basic-shape/path/index.md index 3221716f8871c12..f8e0f73a71c179f 100644 --- a/files/en-us/web/css/basic-shape/path/index.md +++ b/files/en-us/web/css/basic-shape/path/index.md @@ -7,11 +7,46 @@ browser-compat: css.types.basic-shape.path {{CSSRef}} -The **`path()`** [CSS](/en-US/docs/Web/CSS) [function](/en-US/docs/Web/CSS/CSS_Values_and_Units/CSS_Value_Functions) accepts an [SVG path](/en-US/docs/Web/SVG/Element/path) string, and is used in the [CSS shapes](/en-US/docs/Web/CSS/CSS_shapes) and [CSS motion path](/en-US/docs/Web/CSS/CSS_motion_path) modules to enable a shape to be drawn. The `path()` function is a {{cssxref("&lt;basic-shape&gt;")}} data type value. It can be used in the CSS [`offset-path`](/en-US/docs/Web/CSS/offset-path) and [`clip-path`](/en-US/docs/Web/CSS/clip-path) properties and in the SVG [`d`](/en-US/docs/Web/SVG/Attribute/d) attribute. +The **`path()`** [CSS](/en-US/docs/Web/CSS) [function](/en-US/docs/Web/CSS/CSS_Values_and_Units/CSS_Value_Functions) accepts an [SVG path](/en-US/docs/Web/SVG/Reference/Element/path) string, and is used in the [CSS shapes](/en-US/docs/Web/CSS/CSS_shapes) and [CSS motion path](/en-US/docs/Web/CSS/CSS_motion_path) modules to enable a shape to be drawn. The `path()` function is a {{cssxref("&lt;basic-shape&gt;")}} data type value. It can be used in the CSS [`offset-path`](/en-US/docs/Web/CSS/offset-path) and [`clip-path`](/en-US/docs/Web/CSS/clip-path) properties and in the SVG [`d`](/en-US/docs/Web/SVG/Reference/Attribute/d) attribute. There are some limitations to using the `path()` function. The path has to be defined as a single string, so a custom path can't be created using variables ([`var()`](/en-US/docs/Web/CSS/var) functions). Also, all the lengths in the path are implicitly defined in [pixel](/en-US/docs/Web/CSS/CSS_Values_and_Units/Numeric_data_types#absolute_length_units) (`px`) units; other units can't be used. The [`shape()`](/en-US/docs/Web/CSS/basic-shape/shape) function offers more flexibility than the `path()` function. -{{EmbedInteractiveExample("pages/css/function-path.html")}} +{{InteractiveExample("CSS Demo: path()")}} + +```css interactive-example-choice +clip-path: path( + "M 20 240 \ + L 20 80 L 160 80 \ + L 160 20 L 280 100 \ + L 160 180 L 160 120 \ + L 60 120 L 60 240 Z" +); +``` + +```css interactive-example-choice +clip-path: path( + "M 20 240 \ + C 20 0 300 0 300 240 Z" +); +``` + +```html interactive-example +<section class="default-example" id="default-example"> + <div class="transition-all" id="example-element"></div> +</section> +``` + +```css interactive-example +#default-example { + background: #fe9; +} + +#example-element { + background: linear-gradient(to bottom right, #f52, #05f); + width: 100%; + height: 100%; +} +``` ## Syntax @@ -29,7 +64,7 @@ path( [<fill-rule>,]? <string> ) ### Parameters -- [`<fill-rule>`](/en-US/docs/Web/SVG/Attribute/fill-rule) {{optional_inline}} +- [`<fill-rule>`](/en-US/docs/Web/SVG/Reference/Attribute/fill-rule) {{optional_inline}} - : Defines what parts of the path are inside the shape. The possible values include: @@ -40,7 +75,7 @@ path( [<fill-rule>,]? <string> ) > **Warning:** `<fill-rule>` is not supported in {{cssxref("offset-path")}} and using it invalidates the property. - {{cssxref("string")}} - - : A [data string](/en-US/docs/Web/SVG/Attribute/d), contained in quotes, which defines an [SVG path](/en-US/docs/Web/SVG/Element/path). The SVG path data string contains [path commands](/en-US/docs/Web/SVG/Attribute/d#path_commands) that implicitly use pixel units. An empty path is considered invalid. + - : A [data string](/en-US/docs/Web/SVG/Reference/Attribute/d), contained in quotes, which defines an [SVG path](/en-US/docs/Web/SVG/Reference/Element/path). The SVG path data string contains [path commands](/en-US/docs/Web/SVG/Reference/Attribute/d#path_commands) that implicitly use pixel units. An empty path is considered invalid. ### Return value @@ -116,7 +151,7 @@ btn.addEventListener("click", () => { ### Modify the value of the SVG path d attribute -The `path()` can be used to modify the value of the SVG [`d` attribute](/en-US/docs/Web/SVG/Attribute/d), which can also be set to `none` in your CSS. +The `path()` can be used to modify the value of the SVG [`d` attribute](/en-US/docs/Web/SVG/Reference/Attribute/d), which can also be set to `none` in your CSS. The "V" symbol will flip vertically when you hover over it, if `d` is supported as a CSS property. diff --git a/files/en-us/web/css/basic-shape/polygon/index.md b/files/en-us/web/css/basic-shape/polygon/index.md index 18c9be2e3641d38..7d0ce31fb0a3414 100644 --- a/files/en-us/web/css/basic-shape/polygon/index.md +++ b/files/en-us/web/css/basic-shape/polygon/index.md @@ -9,7 +9,41 @@ browser-compat: css.types.basic-shape.polygon The **`polygon()`** [CSS](/en-US/docs/Web/CSS) function is one of the {{cssxref("&lt;basic-shape&gt;")}} [data types](/en-US/docs/Web/CSS/CSS_Values_and_Units/CSS_data_types). It's used to draw a [polygon](https://en.wikipedia.org/wiki/Polygon) by providing one or more pairs of coordinates, each of which represents a vertex of the shape. -{{EmbedInteractiveExample("pages/css/function-polygon.html")}} +{{InteractiveExample("CSS Demo: polygon()")}} + +```css interactive-example-choice +clip-path: polygon( + 0% 20%, + 60% 20%, + 60% 0%, + 100% 50%, + 60% 100%, + 60% 80%, + 0% 80% +); +``` + +```css interactive-example-choice +clip-path: polygon(50% 0%, 100% 50%, 50% 100%, 0% 50%); +``` + +```html interactive-example +<section class="default-example" id="default-example"> + <div class="transition-all" id="example-element"></div> +</section> +``` + +```css interactive-example +#default-example { + background: #fe9; +} + +#example-element { + background: linear-gradient(to bottom right, #f52, #05f); + width: 100%; + height: 100%; +} +``` ## Syntax @@ -27,13 +61,13 @@ polygon(nonzero, 0% 0%, 50% 50%, 0% 100%) polygon(evenodd, 0% 0%, 50% 50%, 0% 100%) ``` -The `polygon()` parameters are separated by a comma and optional whitespace. The first parameter is an optional [`<fill-rule>`](/en-US/docs/Web/SVG/Attribute/fill-rule) value. Additional parameters are points that define the polygon. Each point is a pair of x/y coordinate {{cssxref("length-percentage")}} values separated by a space, e.g. "0 0" and "100% 100%" for the left/top and bottom right corners, respectively. +The `polygon()` parameters are separated by a comma and optional whitespace. The first parameter is an optional [`<fill-rule>`](/en-US/docs/Web/SVG/Reference/Attribute/fill-rule) value. Additional parameters are points that define the polygon. Each point is a pair of x/y coordinate {{cssxref("length-percentage")}} values separated by a space, e.g., "0 0" and "100% 100%" for the left/top and bottom right corners, respectively. -Note: The SVG [`<polygon>`](/en-US/docs/Web/SVG/Element/polygon) element has separate attributes for [`fill-rule`](/en-US/docs/Web/SVG/Attribute/fill-rule) and [`points`](/en-US/docs/Web/SVG/Attribute/points), and `points` is flexible about the use of space and comma separators. CSS `polygon()` rules for separators are strictly enforced. +Note: The SVG [`<polygon>`](/en-US/docs/Web/SVG/Reference/Element/polygon) element has separate attributes for [`fill-rule`](/en-US/docs/Web/SVG/Reference/Attribute/fill-rule) and [`points`](/en-US/docs/Web/SVG/Reference/Attribute/points), and `points` is flexible about the use of space and comma separators. CSS `polygon()` rules for separators are strictly enforced. ### Parameters -- [`<fill-rule>`](/en-US/docs/Web/SVG/Attribute/fill-rule) {{optional_inline}} +- [`<fill-rule>`](/en-US/docs/Web/SVG/Reference/Attribute/fill-rule) {{optional_inline}} - : An optional value of `nonzero` (the default when omitted) or `evenodd`, which specifies the filling rule. - {{cssxref("length-percentage")}} - : Each vertex of the polygon is represented by a pair of `<length-percentage>` values, which give the x/y coordinates of the vertex relative to the shape's [reference box](/en-US/docs/Web/CSS/CSS_shapes/Basic_shapes#the_reference_box). diff --git a/files/en-us/web/css/basic-shape/shape/index.md b/files/en-us/web/css/basic-shape/shape/index.md index ca7724776dfbb24..a57bc2544441fda 100644 --- a/files/en-us/web/css/basic-shape/shape/index.md +++ b/files/en-us/web/css/basic-shape/shape/index.md @@ -2,12 +2,10 @@ title: shape() slug: Web/CSS/basic-shape/shape page-type: css-function -status: - - experimental browser-compat: css.types.basic-shape.shape --- -{{CSSRef}}{{SeeCompatTable}} +{{CSSRef}} The **`shape()`** [CSS function](/en-US/docs/Web/CSS/CSS_Values_and_Units/CSS_Value_Functions) is used to define a shape for the {{cssxref("clip-path")}} and {{cssxref("offset-path")}} properties. It combines an initial starting point with a series of shape commands that define the path of the shape. The `shape()` function is a member of the {{cssxref("&lt;basic-shape&gt;")}} data type. @@ -24,7 +22,10 @@ offset-path: shape(from 10px 10px, move by 10px 5px, line by 20px 40%, close); offset-path: shape(from 10px 10px, hline by 50px, vline to 5rem); /* <curve-command> */ -offset-path: shape(from 10px 10px, curve to 80px 80px via 160px 1px 20% 16px); +offset-path: shape( + from 10px 10px, + curve to 80px 80px with 160px 1px / 20% 16px +); /* <smooth-command> */ offset-path: shape(from 10px 10px, smooth to 100px 50pt); @@ -47,16 +48,17 @@ offset-path: shape( clip-path: shape( evenodd from 10px 10px, - curve to 60px 20% via 40px 0, + curve to 60px 20% with 40px 0, smooth to 90px 0, - curve by -20px 60% via 10% 40px 20% 20px, - smooth by -40% -10px via -10px 70px + curve by -20px 60% with 10% 40px / 20% 20px, + smooth by -40% -10px with -10px 70px, + close ); ``` ### Parameters -- [`<fill-rule>`](/en-US/docs/Web/SVG/Attribute/fill-rule) {{optional_inline}} +- [`<fill-rule>`](/en-US/docs/Web/SVG/Reference/Attribute/fill-rule) {{optional_inline}} - : Specifies how overlapping regions of a shape should be filled. The possible values include: @@ -72,7 +74,7 @@ clip-path: shape( - `<shape-command>` - - : Specifies a list of one or more comma-separated commands that define the shape, using syntax similar to [SVG path commands](/en-US/docs/Web/SVG/Attribute/d#path_commands). Commands include `<move-command>`, `<line-command>`, `<hv-line-command>`, `<curve-command>`, `<smooth-command>`, `<arc-command>`, and `close`. Each command's starting point is the previous command's ending point, with the first point of the shape defined by the [`from <coordinate-pair>`](#from_coordinate-pair) parameter. + - : Specifies a list of one or more comma-separated commands that define the shape, using syntax similar to [SVG path commands](/en-US/docs/Web/SVG/Reference/Attribute/d#path_commands). Commands include `<move-command>`, `<line-command>`, `<hv-line-command>`, `<curve-command>`, `<smooth-command>`, `<arc-command>`, and `close`. Each command's starting point is the previous command's ending point, with the first point of the shape defined by the [`from <coordinate-pair>`](#from_coordinate-pair) parameter. The syntax of most shape commands is a keyword providing a directive, such as `move` or `line`, followed by the `by` or `to` keyword, and a set of coordinates. @@ -85,25 +87,25 @@ clip-path: shape( The following `<shape-command>`s can be specified: `<move-command>`, `<line-command>`, `<hv-line-command>`, `<curve-command>`, `<smooth-command>`, `<arc-command>`, and `close`. - `<move-command>`: Specified as `move [by | to] <coordinate-pair>`. This command adds a [MoveTo command](/en-US/docs/Web/SVG/Attribute/d#moveto_path_commands) to the list of shape commands. It draws nothing. Rather, it specifies the starting position for the next command. The `by` or `to` keyword specifies whether the `<coordinate-pair>` point is relative or absolute, respectively. If the `<move-command>` follows the `close` command, it identifies the starting point of the next shape or subpath. + `<move-command>`: Specified as `move [by | to] <coordinate-pair>`. This command adds a [MoveTo command](/en-US/docs/Web/SVG/Reference/Attribute/d#moveto_path_commands) to the list of shape commands. It draws nothing. Rather, it specifies the starting position for the next command. The `by` or `to` keyword specifies whether the `<coordinate-pair>` point is relative or absolute, respectively. If the `<move-command>` follows the `close` command, it identifies the starting point of the next shape or subpath. - `<line-command>`: Specified as `line [by | to] <coordinate-pair>`. This command adds a [LineTo command](/en-US/docs/Web/SVG/Attribute/d#lineto_path_commands) to the list of shape commands. It draws a straight line from the command's starting point to its ending point. The `by` or `to` keyword specifies whether the ending point specified by `<coordinate-pair>` is relative or absolute, respectively. + `<line-command>`: Specified as `line [by | to] <coordinate-pair>`. This command adds a [LineTo command](/en-US/docs/Web/SVG/Reference/Attribute/d#lineto_path_commands) to the list of shape commands. It draws a straight line from the command's starting point to its ending point. The `by` or `to` keyword specifies whether the ending point specified by `<coordinate-pair>` is relative or absolute, respectively. - `<hv-line-command>`: Specified as `[hline | vline] [by | to] <length-percentage>`. This command adds a horizontal (`hline`) or vertical (`vline`) [LineTo command](/en-US/docs/Web/SVG/Attribute/d#lineto_path_commands) to the list of shape commands. With `hline`, a horizontal line is drawn from the command's starting point `to` or `by` the `x` position defined by `<length-percentage>`. With `vline`, a vertical line is drawn from the command's starting point `to` or `by` the `y` position defined by `<length-percentage>`. The `by` or `to` keyword determines the relative or absolute ending point, respectively. This command is equivalent to `<line-command>` with one coordinate value set by the single `<length-percentage>` and the other coordinate value remaining unchanged from its starting command. + `<hv-line-command>`: Specified as `[hline | vline] [by | to] <length-percentage>`. This command adds a horizontal (`hline`) or vertical (`vline`) [LineTo command](/en-US/docs/Web/SVG/Reference/Attribute/d#lineto_path_commands) to the list of shape commands. With `hline`, a horizontal line is drawn from the command's starting point `to` or `by` the `x` position defined by `<length-percentage>`. With `vline`, a vertical line is drawn from the command's starting point `to` or `by` the `y` position defined by `<length-percentage>`. The `by` or `to` keyword determines the relative or absolute ending point, respectively. This command is equivalent to `<line-command>` with one coordinate value set by the single `<length-percentage>` and the other coordinate value remaining unchanged from its starting command. - `<curve-command>`: Specified as `curve [by | to] <coordinate-pair> via <coordinate-pair> [<coordinate-pair>]`. This command adds a [Bézier curve command](/en-US/docs/Web/SVG/Attribute/d#cubic_bézier_curve) to the list of shape commands. The `by` or `to` keyword determines whether the ending point of the curve, specified by the first `<coordinate-pair>`, is relative or absolute, respectively. The `via` keyword specifies the control points of the Bézier curve. + `<curve-command>`: Specified as `curve [by | to] <coordinate-pair> with <coordinate-pair> [/ <coordinate-pair>]`. This command adds a [Bézier curve command](/en-US/docs/Web/SVG/Reference/Attribute/d#cubic_bézier_curve) to the list of shape commands. The `by` or `to` keyword determines whether the ending point of the curve, specified by the first `<coordinate-pair>`, is relative or absolute, respectively. The `with` keyword specifies the control points of the Bézier curve. - - If only a single `<coordinate-pair>` is provided, the command draws a [quadratic Bézier curve](/en-US/docs/Web/SVG/Attribute/d#quadratic_bézier_curve), which is defined by three points (the start point, control point, and end point). + - If only a single `<coordinate-pair>` is provided, the command draws a [quadratic Bézier curve](/en-US/docs/Web/SVG/Reference/Attribute/d#quadratic_bézier_curve), which is defined by three points (the start point, control point, and end point). - If two `<coordinate-pair>` values are provided, the command draws a cubic Bézier curve, which is defined by four points (the start point, two control points, and the end point). - `<smooth-command>`: Specified as `smooth [by | to] <coordinate-pair> [via <coordinate-pair>]`. This command adds a smooth [Bézier curve command](/en-US/docs/Web/SVG/Attribute/d#cubic_bézier_curve) to the list of shape commands. The `by` or `to` keyword determines whether the ending point of the curve, specified by the first `<coordinate-pair>`, is relative or absolute, respectively. + `<smooth-command>`: Specified as `smooth [by | to] <coordinate-pair> [with <coordinate-pair>]`. This command adds a smooth [Bézier curve command](/en-US/docs/Web/SVG/Reference/Attribute/d#cubic_bézier_curve) to the list of shape commands. The `by` or `to` keyword determines whether the ending point of the curve, specified by the first `<coordinate-pair>`, is relative or absolute, respectively. - - If `via <coordinate-pair>` is omitted, the command draws a smooth quadratic Bézier curve, which uses the previous control point and the current endpoint to define the curve. - - If the optional `via` keyword is included, it specifies the control points of the curve through `<coordinate-pair>`, drawing a smooth cubic Bézier curve defined by the previous control point, the current control point, and the current endpoint. + - If `with <coordinate-pair>` is omitted, the command draws a smooth quadratic Bézier curve, which uses the previous control point and the current endpoint to define the curve. + - If the optional `with` keyword is included, it specifies the control points of the curve through `<coordinate-pair>`, drawing a smooth cubic Bézier curve defined by the previous control point, the current control point, and the current endpoint. Smooth curves ensure a continuous transition from the shape, while quadratic curves do not. Smooth quadratic curves maintain a seamless transition using a single control point, whereas smooth cubic curves provide a more refined transition using two control points. - `<arc-command>`: Specified as `arc [by | to] <coordinate-pair> of <length-percentage> [<length-percentage>] [<arc-sweep> | <arc-size> | rotate <angle>]`. This command adds an [elliptical arc curve command](/en-US/docs/Web/SVG/Attribute/d#elliptical_arc_curve) to the list of shape commands. It draws an elliptical arc between a starting point and an ending point. The `by` or `to` keyword determines whether the ending point of the curve, specified by the first `<coordinate-pair>`, is relative or absolute, respectively. + `<arc-command>`: Specified as `arc [by | to] <coordinate-pair> of <length-percentage> [<length-percentage>] [<arc-sweep> | <arc-size> | rotate <angle>]`. This command adds an [elliptical arc curve command](/en-US/docs/Web/SVG/Reference/Attribute/d#elliptical_arc_curve) to the list of shape commands. It draws an elliptical arc between a starting point and an ending point. The `by` or `to` keyword determines whether the ending point of the curve, specified by the first `<coordinate-pair>`, is relative or absolute, respectively. The elliptical arc curve command defines two possible ellipses, which intersect both the starting and ending points, and each can be traced clockwise or counterclockwise, resulting in four possible arcs depending on the arc size, direction, and angle. The `of` keyword specifies the size of the ellipse from which the arc is taken: the first `<length-percentage>` provides the horizontal radius of the ellipse, and the second `<length-percentage>` provides the vertical radius. @@ -121,18 +123,18 @@ clip-path: shape( - If the horizontal and vertical radii don't describe an ellipse large enough to intersect both the starting point and ending points (after rotation by the specified `<angle>`), the radii are scaled up uniformly until the ellipse is just large enough to intersect both points. - If the starting and ending points of the arc lie on exactly opposite sides of the ellipse, there is only one possible ellipse and two possible arcs. In this case, `<arc-sweep>` specifies the arc to choose, and `<arc-size>` has no effect. - `close`: Adds a [ClosePath command](/en-US/docs/Web/SVG/Attribute/d#closepath) to the list of shape commands, drawing a straight line from the current position (end of the last command) to the first point in the path defined in the `from <coordinate-pair>` parameter. To close the shape without drawing a line, include a `<move-command>` with the originating coordinates before the close command. If the `close` command is immediately followed by a `<move-command>`, it defines the starting point of the next shape or subpath. + `close`: Adds a [ClosePath command](/en-US/docs/Web/SVG/Reference/Attribute/d#closepath) to the list of shape commands, drawing a straight line from the current position (end of the last command) to the first point in the path defined in the `from <coordinate-pair>` parameter. To close the shape without drawing a line, include a `<move-command>` with the originating coordinates before the close command. If the `close` command is immediately followed by a `<move-command>`, it defines the starting point of the next shape or subpath. ## Description The `shape()` function allows you to define complex shapes. It is similar to the {{cssxref("basic-shape/path","path()")}} shape function in several ways: - The `<fill-rule>` parameter in the `shape()` function works exactly like the same parameter in the `path()` function. -- The `shape()` function requires specifying one or more `<shape-command>`s, where each command uses an underlying [path command](/en-US/docs/Web/SVG/Attribute/d#path_commands), such as [MoveTo](/en-US/docs/Web/SVG/Attribute/d#moveto_path_commands), [LineTo](/en-US/docs/Web/SVG/Attribute/d#lineto_path_commands), and [ClosePath](/en-US/docs/Web/SVG/Attribute/d#closepath). +- The `shape()` function requires specifying one or more `<shape-command>`s, where each command uses an underlying [path command](/en-US/docs/Web/SVG/Reference/Attribute/d#path_commands), such as [MoveTo](/en-US/docs/Web/SVG/Reference/Attribute/d#moveto_path_commands), [LineTo](/en-US/docs/Web/SVG/Reference/Attribute/d#lineto_path_commands), and [ClosePath](/en-US/docs/Web/SVG/Reference/Attribute/d#closepath). However, `shape()` offers several advantages over using `path()`: -- `shape()` uses standard CSS syntax, making it easier to create and modify shapes directly in your stylesheet. In comparison, `path()` uses the [SVG path](/en-US/docs/Web/SVG/Element/path) syntax, which is less intuitive for those not familiar with SVG. +- `shape()` uses standard CSS syntax, making it easier to create and modify shapes directly in your stylesheet. In comparison, `path()` uses the [SVG path](/en-US/docs/Web/SVG/Reference/Element/path) syntax, which is less intuitive for those not familiar with SVG. - `shape()` supports a variety of CSS units, including percentages, `rem`, and `em`. `path()`, on the other hand, defines shapes as a single string and limits units to `px`. - `shape()` also allows the use of CSS math functions, like {{cssxref("calc")}}, {{cssxref("max")}}, and {{cssxref("abs")}}, providing more versatility when defining shapes. @@ -205,7 +207,7 @@ body { .shape1 { offset-path: shape( from 30% 60px, - curve to 180px 180px via 90px 190px, + curve to 180px 180px with 90px 190px, close, move by 0px 150px, hline by 40% @@ -292,19 +294,20 @@ body { clip-path: shape(from 0% 0%, line to 100% 0%, line to 50% 100%, close); } -/* Clipping region with curves and smooth transitions and a box */ +/* A Heart clipping region using curve and arc transitions + and a box using hline and vline transitions */ .shape2 { clip-path: shape( - from 10px 10px, - curve to 60px 20% via 40px 0, - smooth to 90px 0, - curve by -20px 60% via 10% 40px 20% 20px, - smooth by -40% -10px via -10px 70px, + from 20px 70px, + arc to 100px 70px of 1% cw, + arc to 180px 70px of 1% cw, + curve to 100px 190px with 180px 130px, + curve to 20px 70px with 20px 130px, close, - move to 100px 100px, - hline by 50px, - vline by 50px, - hline by -50px, + move to 150px 150px, + hline by 40px, + vline by 40px, + hline by -40px, close ); } diff --git a/files/en-us/web/css/block-size/index.md b/files/en-us/web/css/block-size/index.md index 3e23586d3f3a878..3a7acc331080a9e 100644 --- a/files/en-us/web/css/block-size/index.md +++ b/files/en-us/web/css/block-size/index.md @@ -7,11 +7,47 @@ browser-compat: css.properties.block-size {{CSSRef}} -The **`block-size`** [CSS](/en-US/docs/Web/CSS) property defines the horizontal or vertical size of an element's block, depending on its writing mode. It corresponds to either the {{cssxref("width")}} or the {{cssxref("height")}} property, depending on the value of {{cssxref("writing-mode")}}. +The **`block-size`** [CSS](/en-US/docs/Web/CSS) property defines the size of an element's block along the [block axis](/en-US/docs/Glossary/Grid_Axis). If the {{cssxref("writing-mode")}} is horizontal, it corresponds to the {{cssxref("height")}}; if the writing mode is vertical, it corresponds to the {{cssxref("width")}}. A related property is {{cssxref("inline-size")}}, which defines the other dimension of the element. -If the writing mode is vertically oriented, the value of `block-size` relates to the width of the element; otherwise, it relates to the height of the element. A related property is {{cssxref("inline-size")}}, which defines the other dimension of the element. +{{InteractiveExample("CSS Demo: block-size")}} -{{EmbedInteractiveExample("pages/css/block-size.html")}} +```css interactive-example-choice +block-size: 150px; +writing-mode: horizontal-tb; +``` + +```css interactive-example-choice +block-size: 150px; +writing-mode: vertical-rl; +``` + +```css interactive-example-choice +block-size: auto; +writing-mode: horizontal-tb; +``` + +```css interactive-example-choice +block-size: auto; +writing-mode: vertical-lr; +``` + +```html interactive-example +<section class="default-example" id="default-example"> + <div class="transition-all" id="example-element"> + This is a box where you can change the block-size. + </div> +</section> +``` + +```css interactive-example +#example-element { + display: flex; + flex-direction: column; + background-color: #5b6dcd; + justify-content: center; + color: #ffffff; +} +``` ## Syntax diff --git a/files/en-us/web/css/border-block-color/index.md b/files/en-us/web/css/border-block-color/index.md index ef5d82a2016f9dc..1b806cdf081e231 100644 --- a/files/en-us/web/css/border-block-color/index.md +++ b/files/en-us/web/css/border-block-color/index.md @@ -9,7 +9,43 @@ browser-compat: css.properties.border-block-color The **`border-block-color`** [CSS](/en-US/docs/Web/CSS) property defines the color of the logical block borders of an element, which maps to a physical border color depending on the element's writing mode, directionality, and text orientation. It corresponds to the {{cssxref("border-top-color")}} and {{cssxref("border-bottom-color")}}, or {{cssxref("border-right-color")}} and {{cssxref("border-left-color")}} property depending on the values defined for {{cssxref("writing-mode")}}, {{cssxref("direction")}}, and {{cssxref("text-orientation")}}. -{{EmbedInteractiveExample("pages/css/border-block-color.html")}} +{{InteractiveExample("CSS Demo: border-block-color")}} + +```css interactive-example-choice +border-block-color: red; +writing-mode: horizontal-tb; +``` + +```css interactive-example-choice +border-block-color: #32a1ce; +writing-mode: vertical-rl; +``` + +```css interactive-example-choice +border-block-color: rgb(170, 50, 220, 0.6); +writing-mode: horizontal-tb; +direction: rtl; +``` + +```html interactive-example +<section class="default-example" id="default-example"> + <div class="transition-all" id="example-element"> + This is a box with a border around it. + </div> +</section> +``` + +```css interactive-example +#example-element { + background-color: #eee; + color: #000; + border: 0.75em solid; + padding: 0.75em; + width: 80%; + height: 100px; + unicode-bidi: bidi-override; +} +``` The border color in the other dimension can be set with {{cssxref("border-inline-color")}} which sets {{cssxref("border-inline-start-color")}}, and {{cssxref("border-inline-end-color")}}. diff --git a/files/en-us/web/css/border-block-end-color/index.md b/files/en-us/web/css/border-block-end-color/index.md index c6543bb753f4e88..ac86ce23a395c37 100644 --- a/files/en-us/web/css/border-block-end-color/index.md +++ b/files/en-us/web/css/border-block-end-color/index.md @@ -9,7 +9,47 @@ browser-compat: css.properties.border-block-end-color The **`border-block-end-color`** [CSS](/en-US/docs/Web/CSS) property defines the color of the logical block-end border of an element, which maps to a physical border color depending on the element's writing mode, directionality, and text orientation. It corresponds to the {{cssxref("border-top-color")}}, {{cssxref("border-right-color")}}, {{cssxref("border-bottom-color")}}, or {{cssxref("border-left-color")}} property depending on the values defined for {{cssxref("writing-mode")}}, {{cssxref("direction")}}, and {{cssxref("text-orientation")}}. -{{EmbedInteractiveExample("pages/css/border-block-end-color.html")}} +{{InteractiveExample("CSS Demo: border-block-end-color")}} + +```css interactive-example-choice +border-block-end-color: red; +writing-mode: horizontal-tb; +``` + +```css interactive-example-choice +border-block-end-color: #32a1ce; +writing-mode: vertical-rl; +``` + +```css interactive-example-choice +border-block-end-color: rgb(170, 50, 220, 0.6); +writing-mode: horizontal-tb; +``` + +```css interactive-example-choice +border-block-end-color: hsl(60, 90%, 50%, 0.8); +writing-mode: vertical-lr; +``` + +```html interactive-example +<section class="default-example" id="default-example"> + <div class="transition-all" id="example-element"> + This is a box with a border around it. + </div> +</section> +``` + +```css interactive-example +#example-element { + background-color: #eee; + color: #000; + border: 0.75em solid; + padding: 0.75em; + width: 80%; + height: 100px; + unicode-bidi: bidi-override; +} +``` ## Syntax diff --git a/files/en-us/web/css/border-block-end-style/index.md b/files/en-us/web/css/border-block-end-style/index.md index 1cfcb9f9f527f64..ec2ac2c381ec9d7 100644 --- a/files/en-us/web/css/border-block-end-style/index.md +++ b/files/en-us/web/css/border-block-end-style/index.md @@ -9,7 +9,47 @@ browser-compat: css.properties.border-block-end-style The **`border-block-end-style`** [CSS](/en-US/docs/Web/CSS) property defines the style of the logical block-end border of an element, which maps to a physical border style depending on the element's writing mode, directionality, and text orientation. It corresponds to the {{cssxref("border-top-style")}}, {{cssxref("border-right-style")}}, {{cssxref("border-bottom-style")}}, or {{cssxref("border-left-style")}} property depending on the values defined for {{cssxref("writing-mode")}}, {{cssxref("direction")}}, and {{cssxref("text-orientation")}}. -{{EmbedInteractiveExample("pages/css/border-block-end-style.html")}} +{{InteractiveExample("CSS Demo: border-block-end-style")}} + +```css interactive-example-choice +border-block-end-style: dotted; +writing-mode: horizontal-tb; +``` + +```css interactive-example-choice +border-block-end-style: dotted; +writing-mode: vertical-rl; +``` + +```css interactive-example-choice +border-block-end-style: groove; +writing-mode: horizontal-tb; +``` + +```css interactive-example-choice +border-block-end-style: dashed; +writing-mode: vertical-lr; +``` + +```html interactive-example +<section class="default-example" id="default-example"> + <div class="transition-all" id="example-element"> + This is a box with a border around it. + </div> +</section> +``` + +```css interactive-example +#example-element { + background-color: #eee; + color: #000; + border: 0.75em solid; + padding: 0.75em; + width: 80%; + height: 100px; + unicode-bidi: bidi-override; +} +``` ## Syntax diff --git a/files/en-us/web/css/border-block-end-width/index.md b/files/en-us/web/css/border-block-end-width/index.md index daaee1721ee1f22..440d550a8044578 100644 --- a/files/en-us/web/css/border-block-end-width/index.md +++ b/files/en-us/web/css/border-block-end-width/index.md @@ -9,7 +9,47 @@ browser-compat: css.properties.border-block-end-width The **`border-block-end-width`** [CSS](/en-US/docs/Web/CSS) property defines the width of the logical block-end border of an element, which maps to a physical border width depending on the element's writing mode, directionality, and text orientation. It corresponds to the {{cssxref("border-top-width")}}, {{cssxref("border-right-width")}}, {{cssxref("border-bottom-width")}}, or {{cssxref("border-left-width")}} property depending on the values defined for {{cssxref("writing-mode")}}, {{cssxref("direction")}}, and {{cssxref("text-orientation")}}. -{{EmbedInteractiveExample("pages/css/border-block-end-width.html")}} +{{InteractiveExample("CSS Demo: border-block-end-width")}} + +```css interactive-example-choice +border-block-end-width: thick; +writing-mode: horizontal-tb; +``` + +```css interactive-example-choice +border-block-end-width: thick; +writing-mode: vertical-rl; +``` + +```css interactive-example-choice +border-block-end-width: 4px; +writing-mode: horizontal-tb; +``` + +```css interactive-example-choice +border-block-end-width: 4px; +writing-mode: vertical-lr; +``` + +```html interactive-example +<section class="default-example" id="default-example"> + <div class="transition-all" id="example-element"> + This is a box with a border around it. + </div> +</section> +``` + +```css interactive-example +#example-element { + background-color: palegreen; + color: #000; + border: 0 solid crimson; + padding: 0.75em; + width: 80%; + height: 100px; + unicode-bidi: bidi-override; +} +``` ## Syntax diff --git a/files/en-us/web/css/border-block-end/index.md b/files/en-us/web/css/border-block-end/index.md index 05e0d2c22b97fa3..c1d7dea218dff7f 100644 --- a/files/en-us/web/css/border-block-end/index.md +++ b/files/en-us/web/css/border-block-end/index.md @@ -9,7 +9,46 @@ browser-compat: css.properties.border-block-end The **`border-block-end`** [CSS](/en-US/docs/Web/CSS) property is a [shorthand property](/en-US/docs/Web/CSS/CSS_cascade/Shorthand_properties) for setting the individual logical block-end border property values in a single place in the style sheet. -{{EmbedInteractiveExample("pages/css/border-block-end.html")}} +{{InteractiveExample("CSS Demo: border-block-end")}} + +```css interactive-example-choice +border-block-end: solid; +writing-mode: horizontal-tb; +``` + +```css interactive-example-choice +border-block-end: dashed red; +writing-mode: vertical-rl; +``` + +```css interactive-example-choice +border-block-end: 1rem solid; +writing-mode: horizontal-tb; +``` + +```css interactive-example-choice +border-block-end: thick double #32a1ce; +writing-mode: vertical-lr; +``` + +```html interactive-example +<section class="default-example" id="default-example"> + <div class="transition-all" id="example-element"> + This is a box with a border around it. + </div> +</section> +``` + +```css interactive-example +#example-element { + background-color: #eee; + color: #8b008b; + padding: 0.75em; + width: 80%; + height: 100px; + unicode-bidi: bidi-override; +} +``` ## Constituent properties diff --git a/files/en-us/web/css/border-block-start-color/index.md b/files/en-us/web/css/border-block-start-color/index.md index 941e4b930dd6ddf..9991d88a9cd4b88 100644 --- a/files/en-us/web/css/border-block-start-color/index.md +++ b/files/en-us/web/css/border-block-start-color/index.md @@ -9,7 +9,47 @@ browser-compat: css.properties.border-block-start-color The **`border-block-start-color`** [CSS](/en-US/docs/Web/CSS) property defines the color of the logical block-start border of an element, which maps to a physical border color depending on the element's writing mode, directionality, and text orientation. It corresponds to the {{cssxref("border-top-color")}}, {{cssxref("border-right-color")}}, {{cssxref("border-bottom-color")}}, or {{cssxref("border-left-color")}} property depending on the values defined for {{cssxref("writing-mode")}}, {{cssxref("direction")}}, and {{cssxref("text-orientation")}}. -{{EmbedInteractiveExample("pages/css/border-block-start-color.html")}} +{{InteractiveExample("CSS Demo: border-block-start-color")}} + +```css interactive-example-choice +border-block-start-color: red; +writing-mode: horizontal-tb; +``` + +```css interactive-example-choice +border-block-start-color: #32a1ce; +writing-mode: vertical-rl; +``` + +```css interactive-example-choice +border-block-start-color: rgb(170, 50, 220, 0.6); +writing-mode: horizontal-tb; +``` + +```css interactive-example-choice +border-block-start-color: hsl(60, 90%, 50%, 0.8); +writing-mode: vertical-lr; +``` + +```html interactive-example +<section class="default-example" id="default-example"> + <div class="transition-all" id="example-element"> + This is a box with a border around it. + </div> +</section> +``` + +```css interactive-example +#example-element { + background-color: #eee; + color: #000; + border: 0.75em solid; + padding: 0.75em; + width: 80%; + height: 100px; + unicode-bidi: bidi-override; +} +``` ## Syntax diff --git a/files/en-us/web/css/border-block-start-style/index.md b/files/en-us/web/css/border-block-start-style/index.md index 26007226b863664..4ecba8c5cfddabb 100644 --- a/files/en-us/web/css/border-block-start-style/index.md +++ b/files/en-us/web/css/border-block-start-style/index.md @@ -9,7 +9,47 @@ browser-compat: css.properties.border-block-start-style The **`border-block-start-style`** [CSS](/en-US/docs/Web/CSS) property defines the style of the logical block start border of an element, which maps to a physical border style depending on the element's writing mode, directionality, and text orientation. It corresponds to the {{cssxref("border-top-style")}}, {{cssxref("border-right-style")}}, {{cssxref("border-bottom-style")}}, or {{cssxref("border-left-style")}} property depending on the values defined for {{cssxref("writing-mode")}}, {{cssxref("direction")}}, and {{cssxref("text-orientation")}}. -{{EmbedInteractiveExample("pages/css/border-block-start-style.html")}} +{{InteractiveExample("CSS Demo: border-block-start-style")}} + +```css interactive-example-choice +border-block-start-style: dotted; +writing-mode: horizontal-tb; +``` + +```css interactive-example-choice +border-block-start-style: dotted; +writing-mode: vertical-rl; +``` + +```css interactive-example-choice +border-block-start-style: groove; +writing-mode: horizontal-tb; +``` + +```css interactive-example-choice +border-block-start-style: dashed; +writing-mode: vertical-lr; +``` + +```html interactive-example +<section class="default-example" id="default-example"> + <div class="transition-all" id="example-element"> + This is a box with a border around it. + </div> +</section> +``` + +```css interactive-example +#example-element { + background-color: #eee; + color: #000; + border: 0.75em solid; + padding: 0.75em; + width: 80%; + height: 100px; + unicode-bidi: bidi-override; +} +``` ## Syntax diff --git a/files/en-us/web/css/border-block-start-width/index.md b/files/en-us/web/css/border-block-start-width/index.md index 0cfb45a6b0c5c71..29fb78265a661f8 100644 --- a/files/en-us/web/css/border-block-start-width/index.md +++ b/files/en-us/web/css/border-block-start-width/index.md @@ -9,7 +9,47 @@ browser-compat: css.properties.border-block-start-width The **`border-block-start-width`** [CSS](/en-US/docs/Web/CSS) property defines the width of the logical block-start border of an element, which maps to a physical border width depending on the element's writing mode, directionality, and text orientation. It corresponds to the {{cssxref("border-top-width")}}, {{cssxref("border-right-width")}}, {{cssxref("border-bottom-width")}}, or {{cssxref("border-left-width")}} property depending on the values defined for {{cssxref("writing-mode")}}, {{cssxref("direction")}}, and {{cssxref("text-orientation")}}. -{{EmbedInteractiveExample("pages/css/border-block-start-width.html")}} +{{InteractiveExample("CSS Demo: border-block-start-width")}} + +```css interactive-example-choice +border-block-start-width: thick; +writing-mode: horizontal-tb; +``` + +```css interactive-example-choice +border-block-start-width: thick; +writing-mode: vertical-rl; +``` + +```css interactive-example-choice +border-block-start-width: 4px; +writing-mode: horizontal-tb; +``` + +```css interactive-example-choice +border-block-start-width: 4px; +writing-mode: vertical-lr; +``` + +```html interactive-example +<section class="default-example" id="default-example"> + <div class="transition-all" id="example-element"> + This is a box with a border around it. + </div> +</section> +``` + +```css interactive-example +#example-element { + background-color: palegreen; + color: #000; + border: 0 solid crimson; + padding: 0.75em; + width: 80%; + height: 100px; + unicode-bidi: bidi-override; +} +``` ## Syntax diff --git a/files/en-us/web/css/border-block-start/index.md b/files/en-us/web/css/border-block-start/index.md index 4adcf48ba7c019c..417694101d0c6c6 100644 --- a/files/en-us/web/css/border-block-start/index.md +++ b/files/en-us/web/css/border-block-start/index.md @@ -9,7 +9,46 @@ browser-compat: css.properties.border-block-start The **`border-block-start`** [CSS](/en-US/docs/Web/CSS) property is a [shorthand property](/en-US/docs/Web/CSS/CSS_cascade/Shorthand_properties) for setting the individual logical block-start border property values in a single place in the style sheet. -{{EmbedInteractiveExample("pages/css/border-block-start.html")}} +{{InteractiveExample("CSS Demo: border-block-start")}} + +```css interactive-example-choice +border-block-start: solid; +writing-mode: horizontal-tb; +``` + +```css interactive-example-choice +border-block-start: dashed red; +writing-mode: vertical-rl; +``` + +```css interactive-example-choice +border-block-start: 1rem solid; +writing-mode: horizontal-tb; +``` + +```css interactive-example-choice +border-block-start: thick double #32a1ce; +writing-mode: vertical-lr; +``` + +```html interactive-example +<section class="default-example" id="default-example"> + <div class="transition-all" id="example-element"> + This is a box with a border around it. + </div> +</section> +``` + +```css interactive-example +#example-element { + background-color: #eee; + color: #8b008b; + padding: 0.75em; + width: 80%; + height: 100px; + unicode-bidi: bidi-override; +} +``` ## Constituent properties diff --git a/files/en-us/web/css/border-block-style/index.md b/files/en-us/web/css/border-block-style/index.md index 5566d3122c54129..4db637fcc85e728 100644 --- a/files/en-us/web/css/border-block-style/index.md +++ b/files/en-us/web/css/border-block-style/index.md @@ -9,7 +9,43 @@ browser-compat: css.properties.border-block-style The **`border-block-style`** [CSS](/en-US/docs/Web/CSS) property defines the style of the logical block borders of an element, which maps to a physical border style depending on the element's writing mode, directionality, and text orientation. It corresponds to the {{cssxref("border-top-style")}} and {{cssxref("border-bottom-style")}}, or {{cssxref("border-left-style")}} and {{cssxref("border-right-style")}} properties depending on the values defined for {{cssxref("writing-mode")}}, {{cssxref("direction")}}, and {{cssxref("text-orientation")}}. -{{EmbedInteractiveExample("pages/css/border-block-style.html")}} +{{InteractiveExample("CSS Demo: border-block-style")}} + +```css interactive-example-choice +border-block-style: dotted; +writing-mode: horizontal-tb; +``` + +```css interactive-example-choice +border-block-style: dotted; +writing-mode: vertical-rl; +``` + +```css interactive-example-choice +border-block-style: groove; +writing-mode: horizontal-tb; +direction: rtl; +``` + +```html interactive-example +<section class="default-example" id="default-example"> + <div class="transition-all" id="example-element"> + This is a box with a border around it. + </div> +</section> +``` + +```css interactive-example +#example-element { + background-color: #eee; + color: #000; + border: 0.75em solid; + padding: 0.75em; + width: 80%; + height: 100px; + unicode-bidi: bidi-override; +} +``` The border style in the other dimension can be set with {{cssxref("border-inline-style")}}, which sets {{cssxref("border-inline-start-style")}}, and {{cssxref("border-inline-end-style")}}. diff --git a/files/en-us/web/css/border-block-width/index.md b/files/en-us/web/css/border-block-width/index.md index ba11fdc2407037c..b4c95c5ad4a0505 100644 --- a/files/en-us/web/css/border-block-width/index.md +++ b/files/en-us/web/css/border-block-width/index.md @@ -9,7 +9,43 @@ browser-compat: css.properties.border-block-width The **`border-block-width`** [CSS](/en-US/docs/Web/CSS) property defines the width of the logical block borders of an element, which maps to a physical border width depending on the element's writing mode, directionality, and text orientation. It corresponds to the {{cssxref("border-top-width")}} and {{cssxref("border-bottom-width")}}, or {{cssxref("border-left-width")}}, and {{cssxref("border-right-width")}} property depending on the values defined for {{cssxref("writing-mode")}}, {{cssxref("direction")}}, and {{cssxref("text-orientation")}}. -{{EmbedInteractiveExample("pages/css/border-block-width.html")}} +{{InteractiveExample("CSS Demo: border-block-width")}} + +```css interactive-example-choice +border-block-width: thick; +writing-mode: horizontal-tb; +``` + +```css interactive-example-choice +border-block-width: thick; +writing-mode: vertical-rl; +``` + +```css interactive-example-choice +border-block-width: 4px; +writing-mode: horizontal-tb; +direction: rtl; +``` + +```html interactive-example +<section class="default-example" id="default-example"> + <div class="transition-all" id="example-element"> + This is a box with a border around it. + </div> +</section> +``` + +```css interactive-example +#example-element { + background-color: palegreen; + color: #000; + border: 0 solid crimson; + padding: 0.75em; + width: 80%; + height: 100px; + unicode-bidi: bidi-override; +} +``` The border width in the other dimension can be set with {{cssxref("border-inline-width")}}, which sets {{cssxref("border-inline-start-width")}}, and {{cssxref("border-inline-end-width")}}. diff --git a/files/en-us/web/css/border-block/index.md b/files/en-us/web/css/border-block/index.md index c1f74ed84ea3469..ee9f03a869b0c14 100644 --- a/files/en-us/web/css/border-block/index.md +++ b/files/en-us/web/css/border-block/index.md @@ -9,7 +9,42 @@ browser-compat: css.properties.border-block The **`border-block`** [CSS](/en-US/docs/Web/CSS) property is a [shorthand property](/en-US/docs/Web/CSS/CSS_cascade/Shorthand_properties) for setting the individual logical block border property values in a single place in the style sheet. -{{EmbedInteractiveExample("pages/css/border-block.html")}} +{{InteractiveExample("CSS Demo: border-block")}} + +```css interactive-example-choice +border-block: solid; +writing-mode: horizontal-tb; +``` + +```css interactive-example-choice +border-block: dashed red; +writing-mode: vertical-rl; +``` + +```css interactive-example-choice +border-block: 1rem solid; +writing-mode: horizontal-tb; +direction: rtl; +``` + +```html interactive-example +<section class="default-example" id="default-example"> + <div class="transition-all" id="example-element"> + This is a box with a border around it. + </div> +</section> +``` + +```css interactive-example +#example-element { + background-color: #eee; + color: #8b008b; + padding: 0.75em; + width: 80%; + height: 100px; + unicode-bidi: bidi-override; +} +``` `border-block` can be used to set the values for one or more of {{cssxref("border-block-width")}}, {{cssxref("border-block-style")}}, and {{cssxref("border-block-color")}} setting both the start and end in the block dimension at once. The physical borders to which it maps depends on the element's writing mode, directionality, and text orientation. It corresponds to the {{cssxref("border-top")}} and {{cssxref("border-bottom")}} or {{cssxref("border-right")}}, and {{cssxref("border-left")}} properties depending on the values defined for {{cssxref("writing-mode")}}, {{cssxref("direction")}}, and {{cssxref("text-orientation")}}. diff --git a/files/en-us/web/css/border-bottom-color/index.md b/files/en-us/web/css/border-bottom-color/index.md index 455f9dfa171f26b..0823d5c8aae6f26 100644 --- a/files/en-us/web/css/border-bottom-color/index.md +++ b/files/en-us/web/css/border-bottom-color/index.md @@ -9,7 +9,46 @@ browser-compat: css.properties.border-bottom-color The **`border-bottom-color`** [CSS](/en-US/docs/Web/CSS) property sets the color of an element's bottom [border](/en-US/docs/Web/CSS/border). It can also be set with the shorthand CSS properties {{cssxref("border-color")}} or {{cssxref("border-bottom")}}. -{{EmbedInteractiveExample("pages/css/border-bottom-color.html")}} +{{InteractiveExample("CSS Demo: border-bottom-color")}} + +```css interactive-example-choice +border-bottom-color: red; +``` + +```css interactive-example-choice +border-bottom-color: #32a1ce; +``` + +```css interactive-example-choice +border-bottom-color: rgb(170, 50, 220, 0.6); +``` + +```css interactive-example-choice +border-bottom-color: hsl(60, 90%, 50%, 0.8); +``` + +```css interactive-example-choice +border-bottom-color: transparent; +``` + +```html interactive-example +<section class="default-example" id="default-example"> + <div class="transition-all" id="example-element"> + This is a box with a border around it. + </div> +</section> +``` + +```css interactive-example +#example-element { + background-color: #eee; + color: #000; + border: 0.75em solid; + padding: 0.75em; + width: 80%; + height: 100px; +} +``` ## Syntax @@ -47,7 +86,7 @@ The `border-bottom-color` property is specified as a single value. ## Examples -### A simple div with a border +### A div with a border #### HTML @@ -76,7 +115,7 @@ The `border-bottom-color` property is specified as a single value. #### Result -{{EmbedLiveSample('A_simple_div_with_a_border')}} +{{EmbedLiveSample('A_div_with_a_border')}} ## Specifications diff --git a/files/en-us/web/css/border-bottom-left-radius/index.md b/files/en-us/web/css/border-bottom-left-radius/index.md index 5d73efc32a2b7ef..f1ca0031db3dd28 100644 --- a/files/en-us/web/css/border-bottom-left-radius/index.md +++ b/files/en-us/web/css/border-bottom-left-radius/index.md @@ -9,7 +9,46 @@ browser-compat: css.properties.border-bottom-left-radius The **`border-bottom-left-radius`** [CSS](/en-US/docs/Web/CSS) property rounds the bottom-left corner of an element by specifying the radius (or the radius of the semi-major and semi-minor axes) of the ellipse defining the curvature of the corner. -{{EmbedInteractiveExample("pages/css/border-bottom-left-radius.html")}} +{{InteractiveExample("CSS Demo: border-bottom-left-radius")}} + +```css interactive-example-choice +border-bottom-left-radius: 80px 80px; +``` + +```css interactive-example-choice +border-bottom-left-radius: 250px 100px; +``` + +```css interactive-example-choice +border-bottom-left-radius: 50%; +``` + +```css interactive-example-choice +border-bottom-left-radius: 50%; +border: black 10px double; +background-clip: content-box; +``` + +```html interactive-example +<section class="default-example" id="default-example"> + <div class="transition-all" id="example-element"> + This is a box with a bottom left rounded corner. + </div> +</section> +``` + +```css interactive-example +#example-element { + width: 80%; + height: 80%; + display: flex; + justify-content: center; + flex-direction: column; + background-color: #5b6dcd; + color: white; + padding: 10px; +} +``` The rounding can be a circle or an ellipse, or if one of the value is `0` no rounding is done and the corner is square. diff --git a/files/en-us/web/css/border-bottom-right-radius/index.md b/files/en-us/web/css/border-bottom-right-radius/index.md index e9f05d197b52d85..d3d2216b0eda32a 100644 --- a/files/en-us/web/css/border-bottom-right-radius/index.md +++ b/files/en-us/web/css/border-bottom-right-radius/index.md @@ -9,7 +9,46 @@ browser-compat: css.properties.border-bottom-right-radius The **`border-bottom-right-radius`** [CSS](/en-US/docs/Web/CSS) property rounds the bottom-right corner of an element by specifying the radius (or the radius of the semi-major and semi-minor axes) of the ellipse defining the curvature of the corner. -{{EmbedInteractiveExample("pages/css/border-bottom-right-radius.html")}} +{{InteractiveExample("CSS Demo: border-bottom-right-radius")}} + +```css interactive-example-choice +border-bottom-right-radius: 80px 80px; +``` + +```css interactive-example-choice +border-bottom-right-radius: 250px 100px; +``` + +```css interactive-example-choice +border-bottom-right-radius: 50%; +``` + +```css interactive-example-choice +border-bottom-right-radius: 50%; +border: black 10px double; +background-clip: content-box; +``` + +```html interactive-example +<section class="default-example" id="default-example"> + <div class="transition-all" id="example-element"> + This is a box with a bottom right rounded corner. + </div> +</section> +``` + +```css interactive-example +#example-element { + width: 80%; + height: 80%; + display: flex; + justify-content: center; + flex-direction: column; + background-color: #5b6dcd; + color: white; + padding: 10px; +} +``` The rounding can be a circle or an ellipse, or if one of the value is `0` no rounding is done and the corner is square. diff --git a/files/en-us/web/css/border-bottom-style/index.md b/files/en-us/web/css/border-bottom-style/index.md index 296b065d737e2aa..92362f9a6854397 100644 --- a/files/en-us/web/css/border-bottom-style/index.md +++ b/files/en-us/web/css/border-bottom-style/index.md @@ -9,7 +9,54 @@ browser-compat: css.properties.border-bottom-style The **`border-bottom-style`** [CSS](/en-US/docs/Web/CSS) property sets the line style of an element's bottom {{cssxref("border")}}. -{{EmbedInteractiveExample("pages/css/border-bottom-style.html")}} +{{InteractiveExample("CSS Demo: border-bottom-style")}} + +```css interactive-example-choice +border-bottom-style: none; +``` + +```css interactive-example-choice +border-bottom-style: dotted; +``` + +```css interactive-example-choice +border-bottom-style: dashed; +``` + +```css interactive-example-choice +border-bottom-style: solid; +``` + +```css interactive-example-choice +border-bottom-style: groove; +``` + +```css interactive-example-choice +border-bottom-style: inset; +``` + +```html interactive-example +<section id="default-example"> + <div class="transition-all" id="example-element"> + This is a box with a border around it. + </div> +</section> +``` + +```css interactive-example +#example-element { + background-color: #eee; + color: #000; + border: 0.75em solid; + padding: 0.75em; + width: 80%; + height: 100px; +} + +body { + background-color: #fff; +} +``` > [!NOTE] > The specification doesn't define how borders of different styles connect in the corners. diff --git a/files/en-us/web/css/border-bottom-width/index.md b/files/en-us/web/css/border-bottom-width/index.md index 261e6f8b38928f8..2f5a9ab7688b8b5 100644 --- a/files/en-us/web/css/border-bottom-width/index.md +++ b/files/en-us/web/css/border-bottom-width/index.md @@ -9,7 +9,46 @@ browser-compat: css.properties.border-bottom-width The **`border-bottom-width`** [CSS](/en-US/docs/Web/CSS) property sets the width of the bottom border of an element. -{{EmbedInteractiveExample("pages/css/border-bottom-width.html")}} +{{InteractiveExample("CSS Demo: border-bottom-width")}} + +```css interactive-example-choice +border-bottom-width: thick; +``` + +```css interactive-example-choice +border-bottom-width: 2em; +``` + +```css interactive-example-choice +border-bottom-width: 4px; +``` + +```css interactive-example-choice +border-bottom-width: 2ex; +``` + +```css interactive-example-choice +border-bottom-width: 0; +``` + +```html interactive-example +<section class="default-example" id="default-example"> + <div class="transition-all" id="example-element"> + This is a box with a border around it. + </div> +</section> +``` + +```css interactive-example +#example-element { + background-color: palegreen; + color: #000; + border: 0 solid crimson; + padding: 0.75em; + width: 80%; + height: 100px; +} +``` ## Syntax diff --git a/files/en-us/web/css/border-bottom/index.md b/files/en-us/web/css/border-bottom/index.md index 84a38127c6ddad1..74e6ea199e42f5d 100644 --- a/files/en-us/web/css/border-bottom/index.md +++ b/files/en-us/web/css/border-bottom/index.md @@ -9,7 +9,45 @@ browser-compat: css.properties.border-bottom The **`border-bottom`** [shorthand](/en-US/docs/Web/CSS/CSS_cascade/Shorthand_properties) [CSS](/en-US/docs/Web/CSS) property sets an element's bottom [border](/en-US/docs/Web/CSS/border). It sets the values of {{cssxref("border-bottom-width")}}, {{cssxref("border-bottom-style")}} and {{cssxref("border-bottom-color")}}. -{{EmbedInteractiveExample("pages/css/border-bottom.html")}} +{{InteractiveExample("CSS Demo: border-bottom")}} + +```css interactive-example-choice +border-bottom: solid; +``` + +```css interactive-example-choice +border-bottom: dashed red; +``` + +```css interactive-example-choice +border-bottom: 1rem solid; +``` + +```css interactive-example-choice +border-bottom: thick double #32a1ce; +``` + +```css interactive-example-choice +border-bottom: 4mm ridge rgba(211, 220, 50, 0.6); +``` + +```html interactive-example +<section class="default-example" id="default-example"> + <div class="transition-all" id="example-element"> + This is a box with a border around it. + </div> +</section> +``` + +```css interactive-example +#example-element { + background-color: #eee; + color: #8b008b; + padding: 0.75em; + width: 80%; + height: 100px; +} +``` As with all shorthand properties, `border-bottom` always sets the values of all of the properties that it can set, even if they are not specified. It sets those that are not specified to their default values. Consider the following code: diff --git a/files/en-us/web/css/border-collapse/index.md b/files/en-us/web/css/border-collapse/index.md index 5880df2678fc068..13b17ae769b5851 100644 --- a/files/en-us/web/css/border-collapse/index.md +++ b/files/en-us/web/css/border-collapse/index.md @@ -9,7 +9,47 @@ browser-compat: css.properties.border-collapse The **`border-collapse`** [CSS](/en-US/docs/Web/CSS) property sets whether cells inside a {{htmlElement("table")}} have shared or separate borders. -{{EmbedInteractiveExample("pages/css/border-collapse.html")}} +{{InteractiveExample("CSS Demo: border-collapse")}} + +```css interactive-example-choice +border-collapse: collapse; +``` + +```css interactive-example-choice +border-collapse: separate; +``` + +```html interactive-example +<section class="default-example" id="default-example"> + <table class="transition-all" id="example-element"> + <tr> + <td>Cell 1.1</td> + <td>Cell 1.2</td> + </tr> + <tr> + <td>Cell 2.1</td> + <td>Cell 2.2</td> + </tr> + <tr> + <td>Cell 3.1</td> + <td>Cell 3.2</td> + </tr> + </table> +</section> +``` + +```css interactive-example +table { + width: 15rem; + table-layout: fixed; +} + +td { + border: 5px solid; + border-color: crimson dodgerblue orange limegreen; + padding: 0.75rem; +} +``` When cells are collapsed, the {{cssxref("border-style")}} value of `inset` behaves like `ridge`, and `outset` behaves like `groove`. diff --git a/files/en-us/web/css/border-color/index.md b/files/en-us/web/css/border-color/index.md index 307810081a2e4bb..c0c223eb10f941a 100644 --- a/files/en-us/web/css/border-color/index.md +++ b/files/en-us/web/css/border-color/index.md @@ -9,7 +9,46 @@ browser-compat: css.properties.border-color The **`border-color`** [shorthand](/en-US/docs/Web/CSS/CSS_cascade/Shorthand_properties) [CSS](/en-US/docs/Web/CSS) property sets the color of an element's border. -{{EmbedInteractiveExample("pages/css/border-color.html")}} +{{InteractiveExample("CSS Demo: border-color")}} + +```css interactive-example-choice +border-color: red; +``` + +```css interactive-example-choice +border-color: red #32a1ce; +``` + +```css interactive-example-choice +border-color: red rgba(170, 50, 220, 0.6) green; +``` + +```css interactive-example-choice +border-color: red yellow green hsla(60, 90%, 50%, 0.8); +``` + +```css interactive-example-choice +border-color: red yellow green transparent; +``` + +```html interactive-example +<section class="default-example" id="default-example"> + <div class="transition-all" id="example-element"> + This is a box with a border around it. + </div> +</section> +``` + +```css interactive-example +#example-element { + background-color: #eee; + color: #000; + border: 0.75em solid; + padding: 0.75em; + width: 80%; + height: 100px; +} +``` Each side can be set individually using {{CSSxRef("border-top-color")}}, {{CSSxRef("border-right-color")}}, {{CSSxRef("border-bottom-color")}}, and {{CSSxRef("border-left-color")}}; or using the writing mode-aware {{CSSxRef("border-block-start-color")}}, {{CSSxRef("border-block-end-color")}}, {{CSSxRef("border-inline-start-color")}}, and {{CSSxRef("border-inline-end-color")}}. diff --git a/files/en-us/web/css/border-end-end-radius/index.md b/files/en-us/web/css/border-end-end-radius/index.md index 8c8b2f39b9a90fe..9ea1a7c95982ea0 100644 --- a/files/en-us/web/css/border-end-end-radius/index.md +++ b/files/en-us/web/css/border-end-end-radius/index.md @@ -9,7 +9,47 @@ browser-compat: css.properties.border-end-end-radius The **`border-end-end-radius`** [CSS](/en-US/docs/Web/CSS) property defines a logical border radius on an element, which maps to a physical border radius that depends on the element's {{cssxref("writing-mode")}}, {{cssxref("direction")}}, and {{cssxref("text-orientation")}}. This is useful when building styles to work regardless of the [text orientation](/en-US/docs/Web/CSS/text-orientation) and [writing mode](/en-US/docs/Web/CSS/CSS_writing_modes). -{{EmbedInteractiveExample("pages/css/border-end-end-radius.html")}} +{{InteractiveExample("CSS Demo: border-end-end-radius")}} + +```css interactive-example-choice +border-end-end-radius: 80px 80px; +``` + +```css interactive-example-choice +border-end-end-radius: 250px 100px; +direction: rtl; +``` + +```css interactive-example-choice +border-end-end-radius: 50%; +writing-mode: vertical-lr; +``` + +```css interactive-example-choice +border-end-end-radius: 50%; +writing-mode: vertical-rl; +``` + +```html interactive-example +<section class="default-example" id="default-example"> + <div class="transition-all" id="example-element"> + This is a box with a bottom right rounded corner. + </div> +</section> +``` + +```css interactive-example +#example-element { + width: 80%; + height: 80%; + display: flex; + justify-content: center; + flex-direction: column; + background-color: #5b6dcd; + color: white; + padding: 10px; +} +``` This property affects the corner between the block-end and the inline-end sides of the element. For instance, in a `horizontal-tb` writing mode with `ltr` direction, it corresponds to the {{CSSxRef("border-bottom-right-radius")}} property. diff --git a/files/en-us/web/css/border-end-start-radius/index.md b/files/en-us/web/css/border-end-start-radius/index.md index 1aa711b023dbea6..3f638650a38b863 100644 --- a/files/en-us/web/css/border-end-start-radius/index.md +++ b/files/en-us/web/css/border-end-start-radius/index.md @@ -9,7 +9,47 @@ browser-compat: css.properties.border-end-start-radius The **`border-end-start-radius`** [CSS](/en-US/docs/Web/CSS) property defines a logical border radius on an element, which maps to a physical border radius depending on the element's {{cssxref("writing-mode")}}, {{cssxref("direction")}}, and {{cssxref("text-orientation")}}. This is useful when building styles to work regardless of the [text orientation](/en-US/docs/Web/CSS/text-orientation) and [writing mode](/en-US/docs/Web/CSS/CSS_writing_modes). -{{EmbedInteractiveExample("pages/css/border-end-start-radius.html")}} +{{InteractiveExample("CSS Demo: border-end-start-radius")}} + +```css interactive-example-choice +border-end-start-radius: 80px 80px; +``` + +```css interactive-example-choice +border-end-start-radius: 250px 100px; +direction: rtl; +``` + +```css interactive-example-choice +border-end-start-radius: 50%; +writing-mode: vertical-lr; +``` + +```css interactive-example-choice +border-end-start-radius: 50%; +writing-mode: vertical-rl; +``` + +```html interactive-example +<section class="default-example" id="default-example"> + <div class="transition-all" id="example-element"> + This is a box with a bottom left rounded corner. + </div> +</section> +``` + +```css interactive-example +#example-element { + width: 80%; + height: 80%; + display: flex; + justify-content: center; + flex-direction: column; + background-color: #5b6dcd; + color: white; + padding: 10px; +} +``` This property affects the corner between the block-end and the inline-start sides of the element. For instance, in a `horizontal-tb` writing mode with `ltr` direction, it corresponds to the {{CSSxRef("border-bottom-left-radius")}} property. diff --git a/files/en-us/web/css/border-image-outset/index.md b/files/en-us/web/css/border-image-outset/index.md index 209b2bb3f3debd5..ab7b0ac48369064 100644 --- a/files/en-us/web/css/border-image-outset/index.md +++ b/files/en-us/web/css/border-image-outset/index.md @@ -11,7 +11,46 @@ The **`border-image-outset`** [CSS](/en-US/docs/Web/CSS) property sets the dista The parts of the border image that are rendered outside the element's border box with `border-image-outset` do not trigger overflow scrollbars and don't capture mouse events. -{{EmbedInteractiveExample("pages/css/border-image-outset.html")}} +{{InteractiveExample("CSS Demo: border-image-outset")}} + +```css interactive-example-choice +border-image-outset: 0; +``` + +```css interactive-example-choice +border-image-outset: 15px; +``` + +```css interactive-example-choice +border-image-outset: 30px; +``` + +```css interactive-example-choice +border-image-outset: 40px; +``` + +```html interactive-example +<section id="default-example"> + <div id="example-element">This is a box with a border around it.</div> +</section> +``` + +```css interactive-example +#example-element { + width: 80%; + height: 80%; + display: flex; + align-items: center; + justify-content: center; + padding: 50px; + background: #fff3d4; + color: #000; + border: 30px solid; + border-image: url("/shared-assets/images/examples/border-diamonds.png") 30 + round; + font-size: 1.2em; +} +``` ## Syntax diff --git a/files/en-us/web/css/border-image-repeat/index.md b/files/en-us/web/css/border-image-repeat/index.md index d991c7385b52539..e7198907e0139c5 100644 --- a/files/en-us/web/css/border-image-repeat/index.md +++ b/files/en-us/web/css/border-image-repeat/index.md @@ -7,9 +7,52 @@ browser-compat: css.properties.border-image-repeat {{CSSRef}} -The **`border-image-repeat`** [CSS](/en-US/docs/Web/CSS) property defines how the [edge regions](/en-US/docs/Web/CSS/border-image-slice#edge-regions) and [middle region](/en-US/docs/Web/CSS/border-image-slice#middle-region) of a source image are adjusted to fit the dimensions of an element's [border image](/en-US/docs/Web/CSS/border-image). The middle region can be displayed by using the keyword "fill" in the {{cssxref("border-image-slice")}} property. +The **`border-image-repeat`** [CSS](/en-US/docs/Web/CSS) property defines how the images for the sides and the middle part of the [border image](/en-US/docs/Web/CSS/border-image) are scaled and tiled. The middle region can be displayed by using the keyword "fill" in the {{cssxref("border-image-slice")}} property. -{{EmbedInteractiveExample("pages/css/border-image-repeat.html")}} +{{InteractiveExample("CSS Demo: border-image-repeat")}} + +```css interactive-example-choice +border-image-repeat: stretch; +``` + +```css interactive-example-choice +border-image-repeat: repeat; +``` + +```css interactive-example-choice +border-image-repeat: round; +``` + +```css interactive-example-choice +border-image-repeat: space; +``` + +```css interactive-example-choice +border-image-repeat: round stretch; +``` + +```html interactive-example +<section id="default-example"> + <div id="example-element">This is a box with a border around it.</div> +</section> +``` + +```css interactive-example +#example-element { + width: 80%; + height: 80%; + display: flex; + align-items: center; + justify-content: center; + padding: 50px; + background: #fff3d4; + color: #000; + border: 30px solid; + border-image: url("/shared-assets/images/examples/border-diamonds.png") 30 + round; + font-size: 1.2em; +} +``` ## Syntax diff --git a/files/en-us/web/css/border-image-slice/index.md b/files/en-us/web/css/border-image-slice/index.md index 229ea7b2f194c16..259189a783976bd 100644 --- a/files/en-us/web/css/border-image-slice/index.md +++ b/files/en-us/web/css/border-image-slice/index.md @@ -9,7 +9,48 @@ browser-compat: css.properties.border-image-slice The **`border-image-slice`** [CSS](/en-US/docs/Web/CSS) property divides the image specified by {{cssxref("border-image-source")}} into regions. These regions form the components of an element's [border image](/en-US/docs/Web/CSS/border-image). -{{EmbedInteractiveExample("pages/css/border-image-slice.html")}} +{{InteractiveExample("CSS Demo: border-image-slice")}} + +```css interactive-example-choice +border-image-slice: 30; +``` + +```css interactive-example-choice +border-image-slice: 30 fill; +``` + +```css interactive-example-choice +border-image-slice: 44; +``` + +```css interactive-example-choice +border-image: url("/shared-assets/images/examples/border-florid.svg") round; +border-image-slice: calc(50 / 184 * 100%) calc(80 / 284 * 100%) fill; +border-image-width: 30px 48px; +``` + +```html interactive-example +<section id="default-example"> + <div id="example-element">This is a box with a border around it.</div> +</section> +``` + +```css interactive-example +#example-element { + width: 80%; + height: 80%; + display: flex; + align-items: center; + justify-content: center; + padding: 50px; + background: #fff3d4; + color: #000; + border: 30px solid; + border-image: url("/shared-assets/images/examples/border-diamonds.png") 30 + round; + font-size: 1.2em; +} +``` The slicing process creates nine regions in total: four corners, four edges, and a middle region. Four slice lines, set a given distance from their respective sides, control the size of the regions. @@ -80,7 +121,7 @@ The optional `fill` value, if used, can be placed anywhere in the declaration. ### Adjustable border width and slice -The following example shows a simple `<div>` with a border image set on it. The source image for the borders is as follows: +The following example shows a `<div>` with a border image set on it. The source image for the borders is as follows: ![nice multi-colored diamonds](border-diamonds.png) @@ -131,7 +172,7 @@ div > div { height: 200px; border-width: 30px; border-style: solid; - border-image: url(https://interactive-examples.mdn.mozilla.net/media/examples/border-diamonds.png); + border-image: url(/shared-assets/images/examples/border-diamonds.png); border-image-slice: 30; border-image-repeat: round; } diff --git a/files/en-us/web/css/border-image-source/index.md b/files/en-us/web/css/border-image-source/index.md index 1cd7400001062a5..92a345666243b59 100644 --- a/files/en-us/web/css/border-image-source/index.md +++ b/files/en-us/web/css/border-image-source/index.md @@ -9,7 +9,50 @@ browser-compat: css.properties.border-image-source The **`border-image-source`** [CSS](/en-US/docs/Web/CSS) property sets the source image used to create an element's [border image](/en-US/docs/Web/CSS/border-image). -{{EmbedInteractiveExample("pages/css/border-image-source.html")}} +{{InteractiveExample("CSS Demo: border-image-source")}} + +```css interactive-example-choice +border-image-source: url("/shared-assets/images/examples/border-diamonds.png"); +``` + +```css interactive-example-choice +border-image-source: url("/shared-assets/images/examples/border-stars.png"); +``` + +```css interactive-example-choice +border-image-source: repeating-linear-gradient( + 45deg, + transparent, + #4d9f0c 20px +); +``` + +```css interactive-example-choice +border-image-source: none; +``` + +```html interactive-example +<section id="default-example"> + <div id="example-element">This is a box with a border around it.</div> +</section> +``` + +```css interactive-example +#example-element { + width: 80%; + height: 80%; + display: flex; + align-items: center; + justify-content: center; + padding: 50px; + background: #fff3d4; + color: #000; + border: 30px solid; + border-image: url("/shared-assets/images/examples/border-diamonds.png") 30 + round; + font-size: 1.2em; +} +``` The {{cssxref("border-image-slice")}} property is used to divide the source image into regions, which are then dynamically applied to the final border image. diff --git a/files/en-us/web/css/border-image-width/index.md b/files/en-us/web/css/border-image-width/index.md index 9fc2fad49bc9aff..44aac950ae62693 100644 --- a/files/en-us/web/css/border-image-width/index.md +++ b/files/en-us/web/css/border-image-width/index.md @@ -9,7 +9,46 @@ browser-compat: css.properties.border-image-width The **`border-image-width`** [CSS](/en-US/docs/Web/CSS) property sets the width of an element's [border image](/en-US/docs/Web/CSS/border-image). -{{EmbedInteractiveExample("pages/css/border-image-width.html")}} +{{InteractiveExample("CSS Demo: border-image-width")}} + +```css interactive-example-choice +border-image-width: 30px; +``` + +```css interactive-example-choice +border-image-width: 15px 40px; +``` + +```css interactive-example-choice +border-image-width: 2.6rem; +``` + +```css interactive-example-choice +border-image-width: 20% 8%; +``` + +```html interactive-example +<section id="default-example"> + <div id="example-element">This is a box with a border around it.</div> +</section> +``` + +```css interactive-example +#example-element { + width: 80%; + height: 80%; + display: flex; + align-items: center; + justify-content: center; + padding: 50px; + background: #fff3d4; + color: #000; + border: 30px solid; + border-image: url("/shared-assets/images/examples/border-diamonds.png") 30 + round; + font-size: 1.2em; +} +``` If this property's value is greater than the element's {{cssxref("border-width")}}, the border image will extend beyond the padding (and/or content) edge. diff --git a/files/en-us/web/css/border-image/index.md b/files/en-us/web/css/border-image/index.md index 7aa30113c8d19f7..c7e0e1b9e9d5a65 100644 --- a/files/en-us/web/css/border-image/index.md +++ b/files/en-us/web/css/border-image/index.md @@ -9,7 +9,53 @@ browser-compat: css.properties.border-image The **`border-image`** [CSS](/en-US/docs/Web/CSS) property draws an image around a given element. It replaces the element's regular [border](/en-US/docs/Web/CSS/border). -{{EmbedInteractiveExample("pages/css/border-image.html")}} +{{InteractiveExample("CSS Demo: border-image")}} + +```css interactive-example-choice +border-image: url("/shared-assets/images/examples/border-diamonds.png") 30; +``` + +```css interactive-example-choice +border-image: url("/shared-assets/images/examples/border-diamonds.png") 30 / + 19px round; +``` + +```css interactive-example-choice +border-image: url("/shared-assets/images/examples/border-diamonds.png") 30 + fill / 30px / 30px space; +``` + +```css interactive-example-choice +border-image: linear-gradient(#f6b73c, #4d9f0c) 30; +``` + +```css interactive-example-choice +border-image: repeating-linear-gradient(30deg, #4d9f0c, #9198e5, #4d9f0c 20px) + 60; +``` + +```html interactive-example +<section id="default-example"> + <div id="example-element">This is a box with a border around it.</div> +</section> +``` + +```css interactive-example +#example-element { + width: 80%; + height: 80%; + display: flex; + align-items: center; + justify-content: center; + padding: 50px; + background: #fff3d4; + color: #000; + border: 30px solid; + border-image: url("/shared-assets/images/examples/border-diamonds.png") 30 + round; + font-size: 1.2em; +} +``` > [!NOTE] > You should specify a separate {{cssxref("border-style")}} in case the border image fails to load. Although the specification doesn't strictly require it, some browsers don't render the border image if {{cssxref("border-style")}} is `none` or {{cssxref("border-width")}} is `0`. @@ -50,7 +96,7 @@ border-image: unset; The `border-image` property may be specified with anywhere from one to five of the values listed below. > [!NOTE] -> If the [computed value](/en-US/docs/Web/CSS/CSS_cascade/computed_value) of {{cssxref("border-image-source")}} is `none`, or if the image cannot be displayed, the {{cssxref("border-style")}} will be displayed instead. +> If the [computed value](/en-US/docs/Web/CSS/CSS_cascade/Value_processing#computed_value) of {{cssxref("border-image-source")}} is `none`, or if the image cannot be displayed, the {{cssxref("border-style")}} will be displayed instead. ### Values @@ -69,7 +115,7 @@ The `border-image` property may be specified with anywhere from one to five of t Assistive technology cannot parse border images. If the image contains information critical to understanding the page's overall purpose, it is better to describe it semantically in the document. -- [MDN Understanding WCAG, Guideline 1.1 explanations](/en-US/docs/Web/Accessibility/Understanding_WCAG/Perceivable#guideline_1.1_—_providing_text_alternatives_for_non-text_content) +- [MDN Understanding WCAG, Guideline 1.1 explanations](/en-US/docs/Web/Accessibility/Guides/Understanding_WCAG/Perceivable#guideline_1.1_—_providing_text_alternatives_for_non-text_content) - [Understanding Success Criterion 1.1.1 | Understanding WCAG 2.0](https://www.w3.org/TR/UNDERSTANDING-WCAG20/text-equiv-all.html) ## Formal definition diff --git a/files/en-us/web/css/border-inline-color/index.md b/files/en-us/web/css/border-inline-color/index.md index c540c312f8ea683..004d32e3cd3db42 100644 --- a/files/en-us/web/css/border-inline-color/index.md +++ b/files/en-us/web/css/border-inline-color/index.md @@ -9,7 +9,43 @@ browser-compat: css.properties.border-inline-color The **`border-inline-color`** [CSS](/en-US/docs/Web/CSS) property defines the color of the logical inline borders of an element, which maps to a physical border color depending on the element's writing mode, directionality, and text orientation. It corresponds to the {{cssxref("border-top-color")}} and {{cssxref("border-bottom-color")}}, or {{cssxref("border-right-color")}} and {{cssxref("border-left-color")}} property depending on the values defined for {{cssxref("writing-mode")}}, {{cssxref("direction")}}, and {{cssxref("text-orientation")}}. -{{EmbedInteractiveExample("pages/css/border-inline-color.html")}} +{{InteractiveExample("CSS Demo: border-inline-color")}} + +```css interactive-example-choice +border-inline-color: red; +writing-mode: horizontal-tb; +``` + +```css interactive-example-choice +border-inline-color: #32a1ce; +writing-mode: vertical-rl; +``` + +```css interactive-example-choice +border-inline-color: rgb(170, 50, 220, 0.6); +writing-mode: horizontal-tb; +direction: rtl; +``` + +```html interactive-example +<section class="default-example" id="default-example"> + <div class="transition-all" id="example-element"> + This is a box with a border around it. + </div> +</section> +``` + +```css interactive-example +#example-element { + background-color: #eee; + color: #000; + border: 0.75em solid; + padding: 0.75em; + width: 80%; + height: 100px; + unicode-bidi: bidi-override; +} +``` The border color in the other dimension can be set with {{cssxref("border-block-color")}} which sets {{cssxref("border-block-start-color")}}, and {{cssxref("border-block-end-color")}}. diff --git a/files/en-us/web/css/border-inline-end-color/index.md b/files/en-us/web/css/border-inline-end-color/index.md index ae7db7b481ba823..9bc5095c6badb6d 100644 --- a/files/en-us/web/css/border-inline-end-color/index.md +++ b/files/en-us/web/css/border-inline-end-color/index.md @@ -9,7 +9,43 @@ browser-compat: css.properties.border-inline-end-color The **`border-inline-end-color`** [CSS](/en-US/docs/Web/CSS) property defines the color of the logical inline-end border of an element, which maps to a physical border color depending on the element's writing mode, directionality, and text orientation. It corresponds to the {{cssxref("border-top-color")}}, {{cssxref("border-right-color")}}, {{cssxref("border-bottom-color")}}, or {{cssxref("border-left-color")}} property depending on the values defined for {{cssxref("writing-mode")}}, {{cssxref("direction")}}, and {{cssxref("text-orientation")}}. -{{EmbedInteractiveExample("pages/css/border-inline-end-color.html")}} +{{InteractiveExample("CSS Demo: border-inline-end-color")}} + +```css interactive-example-choice +border-inline-end-color: red; +writing-mode: horizontal-tb; +``` + +```css interactive-example-choice +border-inline-end-color: #32a1ce; +writing-mode: vertical-rl; +``` + +```css interactive-example-choice +border-inline-end-color: rgb(170, 50, 220, 0.6); +writing-mode: horizontal-tb; +direction: rtl; +``` + +```html interactive-example +<section class="default-example" id="default-example"> + <div class="transition-all" id="example-element"> + This is a box with a border around it. + </div> +</section> +``` + +```css interactive-example +#example-element { + background-color: #eee; + color: #000; + border: 0.75em solid; + padding: 0.75em; + width: 80%; + height: 100px; + unicode-bidi: bidi-override; +} +``` ## Syntax diff --git a/files/en-us/web/css/border-inline-end-style/index.md b/files/en-us/web/css/border-inline-end-style/index.md index 87e3fe7e62b2497..63f67934579c760 100644 --- a/files/en-us/web/css/border-inline-end-style/index.md +++ b/files/en-us/web/css/border-inline-end-style/index.md @@ -9,7 +9,43 @@ browser-compat: css.properties.border-inline-end-style The **`border-inline-end-style`** [CSS](/en-US/docs/Web/CSS) property defines the style of the logical inline end border of an element, which maps to a physical border style depending on the element's writing mode, directionality, and text orientation. It corresponds to the {{cssxref("border-top-style")}}, {{cssxref("border-right-style")}}, {{cssxref("border-bottom-style")}}, or {{cssxref("border-left-style")}} property depending on the values defined for {{cssxref("writing-mode")}}, {{cssxref("direction")}}, and {{cssxref("text-orientation")}}. -{{EmbedInteractiveExample("pages/css/border-inline-end-style.html")}} +{{InteractiveExample("CSS Demo: border-inline-end-style")}} + +```css interactive-example-choice +border-inline-end-style: dotted; +writing-mode: horizontal-tb; +``` + +```css interactive-example-choice +border-inline-end-style: dotted; +writing-mode: vertical-rl; +``` + +```css interactive-example-choice +border-inline-end-style: groove; +writing-mode: horizontal-tb; +direction: rtl; +``` + +```html interactive-example +<section class="default-example" id="default-example"> + <div class="transition-all" id="example-element"> + This is a box with a border around it. + </div> +</section> +``` + +```css interactive-example +#example-element { + background-color: #eee; + color: #000; + border: 0.75em solid; + padding: 0.75em; + width: 80%; + height: 100px; + unicode-bidi: bidi-override; +} +``` ## Syntax diff --git a/files/en-us/web/css/border-inline-end-width/index.md b/files/en-us/web/css/border-inline-end-width/index.md index 9e1bee3319479ab..6c662b6564719bd 100644 --- a/files/en-us/web/css/border-inline-end-width/index.md +++ b/files/en-us/web/css/border-inline-end-width/index.md @@ -9,7 +9,43 @@ browser-compat: css.properties.border-inline-end-width The **`border-inline-end-width`** [CSS](/en-US/docs/Web/CSS) property defines the width of the logical inline-end border of an element, which maps to a physical border width depending on the element's writing mode, directionality, and text orientation. It corresponds to the {{cssxref("border-top-width")}}, {{cssxref("border-right-width")}}, {{cssxref("border-bottom-width")}}, or {{cssxref("border-left-width")}} property depending on the values defined for {{cssxref("writing-mode")}}, {{cssxref("direction")}}, and {{cssxref("text-orientation")}}. -{{EmbedInteractiveExample("pages/css/border-inline-end-width.html")}} +{{InteractiveExample("CSS Demo: border-inline-end-width")}} + +```css interactive-example-choice +border-inline-end-width: thick; +writing-mode: horizontal-tb; +``` + +```css interactive-example-choice +border-inline-end-width: thick; +writing-mode: vertical-rl; +``` + +```css interactive-example-choice +border-inline-end-width: 4px; +writing-mode: horizontal-tb; +direction: rtl; +``` + +```html interactive-example +<section class="default-example" id="default-example"> + <div class="transition-all" id="example-element"> + This is a box with a border around it. + </div> +</section> +``` + +```css interactive-example +#example-element { + background-color: palegreen; + color: #000; + border: 0 solid crimson; + padding: 0.75em; + width: 80%; + height: 100px; + unicode-bidi: bidi-override; +} +``` ## Syntax diff --git a/files/en-us/web/css/border-inline-end/index.md b/files/en-us/web/css/border-inline-end/index.md index 31a571c4e50d843..bdcbca7cfc89da0 100644 --- a/files/en-us/web/css/border-inline-end/index.md +++ b/files/en-us/web/css/border-inline-end/index.md @@ -9,7 +9,42 @@ browser-compat: css.properties.border-inline-end The **`border-inline-end`** [CSS](/en-US/docs/Web/CSS) property is a [shorthand property](/en-US/docs/Web/CSS/CSS_cascade/Shorthand_properties) for setting the individual logical inline-end border property values in a single place in the style sheet. -{{EmbedInteractiveExample("pages/css/border-inline-end.html")}} +{{InteractiveExample("CSS Demo: border-inline-end")}} + +```css interactive-example-choice +border-inline-end: solid; +writing-mode: horizontal-tb; +``` + +```css interactive-example-choice +border-inline-end: dashed red; +writing-mode: vertical-rl; +``` + +```css interactive-example-choice +border-inline-end: 1rem solid; +writing-mode: horizontal-tb; +direction: rtl; +``` + +```html interactive-example +<section class="default-example" id="default-example"> + <div class="transition-all" id="example-element"> + This is a box with a border around it. + </div> +</section> +``` + +```css interactive-example +#example-element { + background-color: #eee; + color: #8b008b; + padding: 0.75em; + width: 80%; + height: 100px; + unicode-bidi: bidi-override; +} +``` ## Constituent properties diff --git a/files/en-us/web/css/border-inline-start-color/index.md b/files/en-us/web/css/border-inline-start-color/index.md index a862d1113021fe0..2b69849d7d23aae 100644 --- a/files/en-us/web/css/border-inline-start-color/index.md +++ b/files/en-us/web/css/border-inline-start-color/index.md @@ -9,7 +9,43 @@ browser-compat: css.properties.border-inline-start-color The **`border-inline-start-color`** [CSS](/en-US/docs/Web/CSS) property defines the color of the logical inline start border of an element, which maps to a physical border color depending on the element's writing mode, directionality, and text orientation. It corresponds to the {{cssxref("border-top-color")}}, {{cssxref("border-right-color")}}, {{cssxref("border-bottom-color")}}, or {{cssxref("border-left-color")}} property depending on the values defined for {{cssxref("writing-mode")}}, {{cssxref("direction")}}, and {{cssxref("text-orientation")}}. -{{EmbedInteractiveExample("pages/css/border-inline-start-color.html")}} +{{InteractiveExample("CSS Demo: border-inline-start-color")}} + +```css interactive-example-choice +border-inline-start-color: red; +writing-mode: horizontal-tb; +``` + +```css interactive-example-choice +border-inline-start-color: #32a1ce; +writing-mode: vertical-rl; +``` + +```css interactive-example-choice +border-inline-start-color: rgb(170, 50, 220, 0.6); +writing-mode: horizontal-tb; +direction: rtl; +``` + +```html interactive-example +<section class="default-example" id="default-example"> + <div class="transition-all" id="example-element"> + This is a box with a border around it. + </div> +</section> +``` + +```css interactive-example +#example-element { + background-color: #eee; + color: #000; + border: 0.75em solid; + padding: 0.75em; + width: 80%; + height: 100px; + unicode-bidi: bidi-override; +} +``` ## Syntax diff --git a/files/en-us/web/css/border-inline-start-style/index.md b/files/en-us/web/css/border-inline-start-style/index.md index 700346e0645c74c..37897ecdb25cbed 100644 --- a/files/en-us/web/css/border-inline-start-style/index.md +++ b/files/en-us/web/css/border-inline-start-style/index.md @@ -9,7 +9,43 @@ browser-compat: css.properties.border-inline-start-style The **`border-inline-start-style`** [CSS](/en-US/docs/Web/CSS) property defines the style of the logical inline start border of an element, which maps to a physical border style depending on the element's writing mode, directionality, and text orientation. It corresponds to the {{cssxref("border-top-style")}}, {{cssxref("border-right-style")}}, {{cssxref("border-bottom-style")}}, or {{cssxref("border-left-style")}} property depending on the values defined for {{cssxref("writing-mode")}}, {{cssxref("direction")}}, and {{cssxref("text-orientation")}}. -{{EmbedInteractiveExample("pages/css/border-inline-start-style.html")}} +{{InteractiveExample("CSS Demo: border-inline-start-style")}} + +```css interactive-example-choice +border-inline-start-style: dotted; +writing-mode: horizontal-tb; +``` + +```css interactive-example-choice +border-inline-start-style: dotted; +writing-mode: vertical-rl; +``` + +```css interactive-example-choice +border-inline-start-style: groove; +writing-mode: horizontal-tb; +direction: rtl; +``` + +```html interactive-example +<section class="default-example" id="default-example"> + <div class="transition-all" id="example-element"> + This is a box with a border around it. + </div> +</section> +``` + +```css interactive-example +#example-element { + background-color: #eee; + color: #000; + border: 0.75em solid; + padding: 0.75em; + width: 80%; + height: 100px; + unicode-bidi: bidi-override; +} +``` ## Syntax diff --git a/files/en-us/web/css/border-inline-start-width/index.md b/files/en-us/web/css/border-inline-start-width/index.md index 3d3aae00acfe836..fb842d41656c57c 100644 --- a/files/en-us/web/css/border-inline-start-width/index.md +++ b/files/en-us/web/css/border-inline-start-width/index.md @@ -9,7 +9,43 @@ browser-compat: css.properties.border-inline-start-width The **`border-inline-start-width`** [CSS](/en-US/docs/Web/CSS) property defines the width of the logical inline-start border of an element, which maps to a physical border width depending on the element's writing mode, directionality, and text orientation. It corresponds to the {{cssxref("border-top-width")}}, {{cssxref("border-right-width")}}, {{cssxref("border-bottom-width")}}, or {{cssxref("border-left-width")}} property depending on the values defined for {{cssxref("writing-mode")}}, {{cssxref("direction")}}, and {{cssxref("text-orientation")}}. -{{EmbedInteractiveExample("pages/css/border-inline-start-width.html")}} +{{InteractiveExample("CSS Demo: border-inline-start-width")}} + +```css interactive-example-choice +border-inline-start-width: thick; +writing-mode: horizontal-tb; +``` + +```css interactive-example-choice +border-inline-start-width: thick; +writing-mode: vertical-rl; +``` + +```css interactive-example-choice +border-inline-start-width: 4px; +writing-mode: horizontal-tb; +direction: rtl; +``` + +```html interactive-example +<section class="default-example" id="default-example"> + <div class="transition-all" id="example-element"> + This is a box with a border around it. + </div> +</section> +``` + +```css interactive-example +#example-element { + background-color: palegreen; + color: #000; + border: 0 solid crimson; + padding: 0.75em; + width: 80%; + height: 100px; + unicode-bidi: bidi-override; +} +``` ## Syntax diff --git a/files/en-us/web/css/border-inline-start/index.md b/files/en-us/web/css/border-inline-start/index.md index b5367a95b61c396..c74d244b53ef491 100644 --- a/files/en-us/web/css/border-inline-start/index.md +++ b/files/en-us/web/css/border-inline-start/index.md @@ -9,7 +9,42 @@ browser-compat: css.properties.border-inline-start The **`border-inline-start`** [CSS](/en-US/docs/Web/CSS) property is a [shorthand property](/en-US/docs/Web/CSS/CSS_cascade/Shorthand_properties) for setting the individual logical inline-start border property values in a single place in the style sheet. -{{EmbedInteractiveExample("pages/css/border-inline-start.html")}} +{{InteractiveExample("CSS Demo: border-inline-start")}} + +```css interactive-example-choice +border-inline-start: solid; +writing-mode: horizontal-tb; +``` + +```css interactive-example-choice +border-inline-start: dashed red; +writing-mode: vertical-rl; +``` + +```css interactive-example-choice +border-inline-start: 1rem solid; +writing-mode: horizontal-tb; +direction: rtl; +``` + +```html interactive-example +<section class="default-example" id="default-example"> + <div class="transition-all" id="example-element"> + This is a box with a border around it. + </div> +</section> +``` + +```css interactive-example +#example-element { + background-color: #eee; + color: #8b008b; + padding: 0.75em; + width: 80%; + height: 100px; + unicode-bidi: bidi-override; +} +``` ## Constituent properties diff --git a/files/en-us/web/css/border-inline-style/index.md b/files/en-us/web/css/border-inline-style/index.md index 6834ec8e6317c1f..617e5db23c71e4d 100644 --- a/files/en-us/web/css/border-inline-style/index.md +++ b/files/en-us/web/css/border-inline-style/index.md @@ -9,7 +9,43 @@ browser-compat: css.properties.border-inline-style The **`border-inline-style`** [CSS](/en-US/docs/Web/CSS) property defines the style of the logical inline borders of an element, which maps to a physical border style depending on the element's writing mode, directionality, and text orientation. It corresponds to the {{cssxref("border-top-style")}} and {{cssxref("border-bottom-style")}}, or {{cssxref("border-left-style")}} and {{cssxref("border-right-style")}} properties depending on the values defined for {{cssxref("writing-mode")}}, {{cssxref("direction")}}, and {{cssxref("text-orientation")}}. -{{EmbedInteractiveExample("pages/css/border-inline-style.html")}} +{{InteractiveExample("CSS Demo: border-inline-style")}} + +```css interactive-example-choice +border-inline-style: dotted; +writing-mode: horizontal-tb; +``` + +```css interactive-example-choice +border-inline-style: dotted; +writing-mode: vertical-rl; +``` + +```css interactive-example-choice +border-inline-style: groove; +writing-mode: horizontal-tb; +direction: rtl; +``` + +```html interactive-example +<section class="default-example" id="default-example"> + <div class="transition-all" id="example-element"> + This is a box with a border around it. + </div> +</section> +``` + +```css interactive-example +#example-element { + background-color: #eee; + color: #000; + border: 0.75em solid; + padding: 0.75em; + width: 80%; + height: 100px; + unicode-bidi: bidi-override; +} +``` The border style in the other dimension can be set with {{cssxref("border-block-style")}}, which sets {{cssxref("border-block-start-style")}}, and {{cssxref("border-block-end-style")}}. diff --git a/files/en-us/web/css/border-inline-width/index.md b/files/en-us/web/css/border-inline-width/index.md index b3993ef15ad52bf..639483f24c80510 100644 --- a/files/en-us/web/css/border-inline-width/index.md +++ b/files/en-us/web/css/border-inline-width/index.md @@ -9,7 +9,43 @@ browser-compat: css.properties.border-inline-width The **`border-inline-width`** [CSS](/en-US/docs/Web/CSS) property defines the width of the logical inline borders of an element, which maps to a physical border width depending on the element's writing mode, directionality, and text orientation. It corresponds to the {{cssxref("border-top-width")}} and {{cssxref("border-bottom-width")}}, or {{cssxref("border-left-width")}}, and {{cssxref("border-right-width")}} property depending on the values defined for {{cssxref("writing-mode")}}, {{cssxref("direction")}}, and {{cssxref("text-orientation")}}. -{{EmbedInteractiveExample("pages/css/border-inline-width.html")}} +{{InteractiveExample("CSS Demo: border-inline-width")}} + +```css interactive-example-choice +border-inline-width: thick; +writing-mode: horizontal-tb; +``` + +```css interactive-example-choice +border-inline-width: thick; +writing-mode: vertical-rl; +``` + +```css interactive-example-choice +border-inline-width: 4px; +writing-mode: horizontal-tb; +direction: rtl; +``` + +```html interactive-example +<section class="default-example" id="default-example"> + <div class="transition-all" id="example-element"> + This is a box with a border around it. + </div> +</section> +``` + +```css interactive-example +#example-element { + background-color: palegreen; + color: #000; + border: 0 solid crimson; + padding: 0.75em; + width: 80%; + height: 100px; + unicode-bidi: bidi-override; +} +``` The border width in the other dimension can be set with {{cssxref("border-block-width")}}, which sets {{cssxref("border-block-start-width")}}, and {{cssxref("border-block-end-width")}}. diff --git a/files/en-us/web/css/border-inline/index.md b/files/en-us/web/css/border-inline/index.md index 672004ae37dec5e..999edc494f842df 100644 --- a/files/en-us/web/css/border-inline/index.md +++ b/files/en-us/web/css/border-inline/index.md @@ -9,7 +9,42 @@ browser-compat: css.properties.border-inline The **`border-inline`** [CSS](/en-US/docs/Web/CSS) property is a [shorthand property](/en-US/docs/Web/CSS/CSS_cascade/Shorthand_properties) for setting the individual logical inline border property values in a single place in the style sheet. -{{EmbedInteractiveExample("pages/css/border-inline.html")}} +{{InteractiveExample("CSS Demo: border-inline")}} + +```css interactive-example-choice +border-inline: solid; +writing-mode: horizontal-tb; +``` + +```css interactive-example-choice +border-inline: dashed red; +writing-mode: vertical-rl; +``` + +```css interactive-example-choice +border-inline: 1rem solid; +writing-mode: horizontal-tb; +direction: rtl; +``` + +```html interactive-example +<section class="default-example" id="default-example"> + <div class="transition-all" id="example-element"> + This is a box with a border around it. + </div> +</section> +``` + +```css interactive-example +#example-element { + background-color: #eee; + color: #8b008b; + padding: 0.75em; + width: 80%; + height: 100px; + unicode-bidi: bidi-override; +} +``` The physical borders to which `border-inline` maps depends on the element's writing mode, directionality, and text orientation. It corresponds to the {{cssxref("border-top")}} and {{cssxref("border-bottom")}} or {{cssxref("border-right")}}, and {{cssxref("border-left")}} properties, depending on the values defined for {{cssxref("writing-mode")}}, {{cssxref("direction")}}, and {{cssxref("text-orientation")}}. diff --git a/files/en-us/web/css/border-left-color/index.md b/files/en-us/web/css/border-left-color/index.md index e62bbd948a3522e..7a290b2555e41de 100644 --- a/files/en-us/web/css/border-left-color/index.md +++ b/files/en-us/web/css/border-left-color/index.md @@ -9,7 +9,46 @@ browser-compat: css.properties.border-left-color The **`border-left-color`** [CSS](/en-US/docs/Web/CSS) property sets the color of an element's left [border](/en-US/docs/Web/CSS/border). It can also be set with the shorthand CSS properties {{cssxref("border-color")}} or {{cssxref("border-left")}}. -{{EmbedInteractiveExample("pages/css/border-left-color.html")}} +{{InteractiveExample("CSS Demo: border-left-color")}} + +```css interactive-example-choice +border-left-color: red; +``` + +```css interactive-example-choice +border-left-color: #32a1ce; +``` + +```css interactive-example-choice +border-left-color: rgb(170, 50, 220, 0.6); +``` + +```css interactive-example-choice +border-left-color: hsl(60, 90%, 50%, 0.8); +``` + +```css interactive-example-choice +border-left-color: transparent; +``` + +```html interactive-example +<section class="default-example" id="default-example"> + <div class="transition-all" id="example-element"> + This is a box with a border around it. + </div> +</section> +``` + +```css interactive-example +#example-element { + background-color: #eee; + color: #000; + border: 0.75em solid; + padding: 0.75em; + width: 80%; + height: 100px; +} +``` ## Syntax @@ -47,7 +86,7 @@ The `border-left-color` property is specified as a single value. ## Examples -### A simple div with a border +### A div with a border #### HTML @@ -76,7 +115,7 @@ The `border-left-color` property is specified as a single value. #### Result -{{EmbedLiveSample('A_simple_div_with_a_border')}} +{{EmbedLiveSample('A_div_with_a_border')}} ## Specifications diff --git a/files/en-us/web/css/border-left-style/index.md b/files/en-us/web/css/border-left-style/index.md index 430ab6e5fb0ac46..824b169ffca9457 100644 --- a/files/en-us/web/css/border-left-style/index.md +++ b/files/en-us/web/css/border-left-style/index.md @@ -9,7 +9,54 @@ browser-compat: css.properties.border-left-style The **`border-left-style`** [CSS](/en-US/docs/Web/CSS) property sets the line style of an element's left {{cssxref("border")}}. -{{EmbedInteractiveExample("pages/css/border-left-style.html")}} +{{InteractiveExample("CSS Demo: border-left-style")}} + +```css interactive-example-choice +border-left-style: none; +``` + +```css interactive-example-choice +border-left-style: dotted; +``` + +```css interactive-example-choice +border-left-style: dashed; +``` + +```css interactive-example-choice +border-left-style: solid; +``` + +```css interactive-example-choice +border-left-style: groove; +``` + +```css interactive-example-choice +border-left-style: inset; +``` + +```html interactive-example +<section id="default-example"> + <div class="transition-all" id="example-element"> + This is a box with a border around it. + </div> +</section> +``` + +```css interactive-example +#example-element { + background-color: #eee; + color: #000; + border: 0.75em solid; + padding: 0.75em; + width: 80%; + height: 100px; +} + +body { + background-color: #fff; +} +``` > [!NOTE] > The specification doesn't define how borders of different styles connect in the corners. diff --git a/files/en-us/web/css/border-left-width/index.md b/files/en-us/web/css/border-left-width/index.md index 7f18b16937f2ee9..31e74719ee6b94d 100644 --- a/files/en-us/web/css/border-left-width/index.md +++ b/files/en-us/web/css/border-left-width/index.md @@ -9,7 +9,46 @@ browser-compat: css.properties.border-left-width The **`border-left-width`** [CSS](/en-US/docs/Web/CSS) property sets the width of the left border of an element. -{{EmbedInteractiveExample("pages/css/border-left-width.html")}} +{{InteractiveExample("CSS Demo: border-left-width")}} + +```css interactive-example-choice +border-left-width: thick; +``` + +```css interactive-example-choice +border-left-width: 2em; +``` + +```css interactive-example-choice +border-left-width: 4px; +``` + +```css interactive-example-choice +border-left-width: 2ex; +``` + +```css interactive-example-choice +border-left-width: 0; +``` + +```html interactive-example +<section class="default-example" id="default-example"> + <div class="transition-all" id="example-element"> + This is a box with a border around it. + </div> +</section> +``` + +```css interactive-example +#example-element { + background-color: palegreen; + color: #000; + border: 0 solid crimson; + padding: 0.75em; + width: 80%; + height: 100px; +} +``` ## Syntax diff --git a/files/en-us/web/css/border-left/index.md b/files/en-us/web/css/border-left/index.md index 60b4cab2095ed2a..0cbe0271fa0f9be 100644 --- a/files/en-us/web/css/border-left/index.md +++ b/files/en-us/web/css/border-left/index.md @@ -9,7 +9,45 @@ browser-compat: css.properties.border-left The **`border-left`** [shorthand](/en-US/docs/Web/CSS/CSS_cascade/Shorthand_properties) [CSS](/en-US/docs/Web/CSS) property sets all the properties of an element's left [border](/en-US/docs/Web/CSS/border). -{{EmbedInteractiveExample("pages/css/border-left.html")}} +{{InteractiveExample("CSS Demo: border-left")}} + +```css interactive-example-choice +border-left: solid; +``` + +```css interactive-example-choice +border-left: dashed red; +``` + +```css interactive-example-choice +border-left: 1rem solid; +``` + +```css interactive-example-choice +border-left: thick double #32a1ce; +``` + +```css interactive-example-choice +border-left: 4mm ridge rgba(211, 220, 50, 0.6); +``` + +```html interactive-example +<section class="default-example" id="default-example"> + <div class="transition-all" id="example-element"> + This is a box with a border around it. + </div> +</section> +``` + +```css interactive-example +#example-element { + background-color: #eee; + color: #8b008b; + padding: 0.75em; + width: 80%; + height: 100px; +} +``` As with all shorthand properties, `border-left` always sets the values of all of the properties that it can set, even if they are not specified. It sets those that are not specified to their default values. Consider the following code: diff --git a/files/en-us/web/css/border-radius/index.md b/files/en-us/web/css/border-radius/index.md index 9dc4e9249cbdd30..daca0ef887aab77 100644 --- a/files/en-us/web/css/border-radius/index.md +++ b/files/en-us/web/css/border-radius/index.md @@ -9,7 +9,52 @@ browser-compat: css.properties.border-radius The **`border-radius`** [CSS](/en-US/docs/Web/CSS) property rounds the corners of an element's outer border edge. You can set a single radius to make circular corners, or two radii to make elliptical corners. -{{EmbedInteractiveExample("pages/css/border-radius.html")}} +{{InteractiveExample("CSS Demo: border-radius")}} + +```css interactive-example-choice +border-radius: 30px; +``` + +```css interactive-example-choice +border-radius: 25% 10%; +``` + +```css interactive-example-choice +border-radius: 10% 30% 50% 70%; +``` + +```css interactive-example-choice +border-radius: 10% / 50%; +``` + +```css interactive-example-choice +border-radius: 10px 100px / 120px; +``` + +```css interactive-example-choice +border-radius: 50% 20% / 10% 40%; +``` + +```html interactive-example +<section class="default-example" id="default-example"> + <div class="transition-all" id="example-element"> + This is a box with rounded corners. + </div> +</section> +``` + +```css interactive-example +#example-element { + width: 80%; + height: 80%; + display: flex; + justify-content: center; + flex-direction: column; + background-color: #5b6dcd; + color: white; + padding: 10px; +} +``` The radius applies to the whole {{cssxref("background")}}, even if the element has no border; the exact position of the clipping is defined by the {{cssxref("background-clip")}} property. @@ -187,6 +232,11 @@ border-bottom-left-radius: 3px 4px; ## Examples +### Comparing border styles + +The following example has seven {{htmlelement("pre")}} elements, each of which demonstrates combinations of `border` and `border-radius` styles. +The styles applied to each `<pre>` element are included as the element's contents, so you can see the CSS declarations necessary to create the associated border style: + ```html hidden <pre id="example-1"> border: solid 10px; @@ -234,7 +284,7 @@ pre { margin: 20px; padding: 20px; width: 80%; - height: 80px; + height: 50px; } pre#example-1 { @@ -278,15 +328,7 @@ pre#example-7 { } ``` -{{EmbedLiveSample("Examples", "200", "1150")}} - -### Live Samples - -- Sample 1 : <https://jsfiddle.net/Tripad/qnGKj/2/> -- Sample 2 : <https://jsfiddle.net/Tripad/qnGKj/3/> -- Sample 3 : <https://jsfiddle.net/Tripad/qnGKj/4/> -- Sample 4 : <https://jsfiddle.net/Tripad/qnGKj/5/> -- Sample 5 : <https://jsfiddle.net/Tripad/qnGKj/6/> +{{EmbedLiveSample("Comparing border styles", "", "900")}} ## Specifications diff --git a/files/en-us/web/css/border-right-color/index.md b/files/en-us/web/css/border-right-color/index.md index 184cbf25834ad13..fb6d9a37dc8a956 100644 --- a/files/en-us/web/css/border-right-color/index.md +++ b/files/en-us/web/css/border-right-color/index.md @@ -9,7 +9,46 @@ browser-compat: css.properties.border-right-color The **`border-right-color`** [CSS](/en-US/docs/Web/CSS) property sets the color of an element's right [border](/en-US/docs/Web/CSS/border). It can also be set with the shorthand CSS properties {{cssxref("border-color")}} or {{cssxref("border-right")}}. -{{EmbedInteractiveExample("pages/css/border-right-color.html")}} +{{InteractiveExample("CSS Demo: border-right-color")}} + +```css interactive-example-choice +border-right-color: red; +``` + +```css interactive-example-choice +border-right-color: #32a1ce; +``` + +```css interactive-example-choice +border-right-color: rgb(170, 50, 220, 0.6); +``` + +```css interactive-example-choice +border-right-color: hsl(60, 90%, 50%, 0.8); +``` + +```css interactive-example-choice +border-right-color: transparent; +``` + +```html interactive-example +<section class="default-example" id="default-example"> + <div class="transition-all" id="example-element"> + This is a box with a border around it. + </div> +</section> +``` + +```css interactive-example +#example-element { + background-color: #eee; + color: #000; + border: 0.75em solid; + padding: 0.75em; + width: 80%; + height: 100px; +} +``` ## Syntax @@ -47,7 +86,7 @@ The `border-right-color` property is specified as a single value. ## Examples -### A simple div with a border +### A div with a border #### HTML @@ -76,7 +115,7 @@ The `border-right-color` property is specified as a single value. #### Result -{{EmbedLiveSample('A_simple_div_with_a_border')}} +{{EmbedLiveSample('A_div_with_a_border')}} ## Specifications diff --git a/files/en-us/web/css/border-right-style/index.md b/files/en-us/web/css/border-right-style/index.md index 068314aceb77bb4..c881ca75d95fe5c 100644 --- a/files/en-us/web/css/border-right-style/index.md +++ b/files/en-us/web/css/border-right-style/index.md @@ -9,7 +9,54 @@ browser-compat: css.properties.border-right-style The **`border-right-style`** [CSS](/en-US/docs/Web/CSS) property sets the line style of an element's right {{cssxref("border")}}. -{{EmbedInteractiveExample("pages/css/border-right-style.html")}} +{{InteractiveExample("CSS Demo: border-right-style")}} + +```css interactive-example-choice +border-right-style: none; +``` + +```css interactive-example-choice +border-right-style: dotted; +``` + +```css interactive-example-choice +border-right-style: dashed; +``` + +```css interactive-example-choice +border-right-style: solid; +``` + +```css interactive-example-choice +border-right-style: groove; +``` + +```css interactive-example-choice +border-right-style: inset; +``` + +```html interactive-example +<section id="default-example"> + <div class="transition-all" id="example-element"> + This is a box with a border around it. + </div> +</section> +``` + +```css interactive-example +#example-element { + background-color: #eee; + color: #000; + border: 0.75em solid; + padding: 0.75em; + width: 80%; + height: 100px; +} + +body { + background-color: #fff; +} +``` > [!NOTE] > The specification doesn't define how borders of different styles connect in the corners. diff --git a/files/en-us/web/css/border-right-width/index.md b/files/en-us/web/css/border-right-width/index.md index 3b2fa5003e4f888..91fd1588f434178 100644 --- a/files/en-us/web/css/border-right-width/index.md +++ b/files/en-us/web/css/border-right-width/index.md @@ -9,7 +9,46 @@ browser-compat: css.properties.border-right-width The **`border-right-width`** [CSS](/en-US/docs/Web/CSS) property sets the width of the right border of an element. -{{EmbedInteractiveExample("pages/css/border-right-width.html")}} +{{InteractiveExample("CSS Demo: border-right-width")}} + +```css interactive-example-choice +border-right-width: thick; +``` + +```css interactive-example-choice +border-right-width: 2em; +``` + +```css interactive-example-choice +border-right-width: 4px; +``` + +```css interactive-example-choice +border-right-width: 2ex; +``` + +```css interactive-example-choice +border-right-width: 0; +``` + +```html interactive-example +<section class="default-example" id="default-example"> + <div class="transition-all" id="example-element"> + This is a box with a border around it. + </div> +</section> +``` + +```css interactive-example +#example-element { + background-color: palegreen; + color: #000; + border: 0 solid crimson; + padding: 0.75em; + width: 80%; + height: 100px; +} +``` ## Syntax diff --git a/files/en-us/web/css/border-right/index.md b/files/en-us/web/css/border-right/index.md index d5a5e0055db1576..ca9fcea768d381b 100644 --- a/files/en-us/web/css/border-right/index.md +++ b/files/en-us/web/css/border-right/index.md @@ -9,7 +9,45 @@ browser-compat: css.properties.border-right The **`border-right`** [shorthand](/en-US/docs/Web/CSS/CSS_cascade/Shorthand_properties) [CSS](/en-US/docs/Web/CSS) property sets all the properties of an element's right [border](/en-US/docs/Web/CSS/border). -{{EmbedInteractiveExample("pages/css/border-right.html")}} +{{InteractiveExample("CSS Demo: border-right")}} + +```css interactive-example-choice +border-right: solid; +``` + +```css interactive-example-choice +border-right: dashed red; +``` + +```css interactive-example-choice +border-right: 1rem solid; +``` + +```css interactive-example-choice +border-right: thick double #32a1ce; +``` + +```css interactive-example-choice +border-right: 4mm ridge rgba(211, 220, 50, 0.6); +``` + +```html interactive-example +<section class="default-example" id="default-example"> + <div class="transition-all" id="example-element"> + This is a box with a border around it. + </div> +</section> +``` + +```css interactive-example +#example-element { + background-color: #eee; + color: #8b008b; + padding: 0.75em; + width: 80%; + height: 100px; +} +``` As with all shorthand properties, `border-right` always sets the values of all of the properties that it can set, even if they are not specified. It sets those that are not specified to their default values. Consider the following code: diff --git a/files/en-us/web/css/border-spacing/index.md b/files/en-us/web/css/border-spacing/index.md index c37f3100e336a94..033a040964583e1 100644 --- a/files/en-us/web/css/border-spacing/index.md +++ b/files/en-us/web/css/border-spacing/index.md @@ -9,7 +9,51 @@ browser-compat: css.properties.border-spacing The **`border-spacing`** [CSS](/en-US/docs/Web/CSS) property sets the distance between the borders of adjacent cells in a {{htmlelement("table")}}. This property applies only when {{cssxref("border-collapse")}} is `separate`. -{{EmbedInteractiveExample("pages/css/border-spacing.html")}} +{{InteractiveExample("CSS Demo: border-spacing")}} + +```css interactive-example-choice +border-spacing: 0; +``` + +```css interactive-example-choice +border-spacing: 5px; +``` + +```css interactive-example-choice +border-spacing: 5px 1rem; +``` + +```html interactive-example +<section class="default-example" id="default-example"> + <table class="transition-all" id="example-element"> + <tr> + <td>Cell 1.1</td> + <td>Cell 1.2</td> + </tr> + <tr> + <td>Cell 2.1</td> + <td>Cell 2.2</td> + </tr> + <tr> + <td>Cell 3.1</td> + <td>Cell 3.2</td> + </tr> + </table> +</section> +``` + +```css interactive-example +table { + width: 15rem; + table-layout: fixed; +} + +td { + border: 5px solid; + border-color: crimson dodgerblue; + padding: 0.75rem; +} +``` The `border-spacing` value is also used along the outside edge of the table, where the distance between the table's border and the cells in the first/last column or row is the sum of the relevant (horizontal or vertical) `border-spacing` and the relevant (top, right, bottom, or left) {{cssxref("padding")}} on the table. diff --git a/files/en-us/web/css/border-start-end-radius/index.md b/files/en-us/web/css/border-start-end-radius/index.md index 0e0f195ffe10eb1..0bfbbffa62e0897 100644 --- a/files/en-us/web/css/border-start-end-radius/index.md +++ b/files/en-us/web/css/border-start-end-radius/index.md @@ -9,7 +9,47 @@ browser-compat: css.properties.border-start-end-radius The **`border-start-end-radius`** [CSS](/en-US/docs/Web/CSS) property defines a logical border radius on an element, which maps to a physical border radius depending on the element's {{cssxref("writing-mode")}}, {{cssxref("direction")}}, and {{cssxref("text-orientation")}}. This is useful when building styles to work regardless of the [text orientation](/en-US/docs/Web/CSS/text-orientation) and [writing mode](/en-US/docs/Web/CSS/CSS_writing_modes). -{{EmbedInteractiveExample("pages/css/border-start-end-radius.html")}} +{{InteractiveExample("CSS Demo: border-start-end-radius")}} + +```css interactive-example-choice +border-start-end-radius: 80px 80px; +``` + +```css interactive-example-choice +border-start-end-radius: 250px 100px; +direction: rtl; +``` + +```css interactive-example-choice +border-start-end-radius: 50%; +writing-mode: vertical-lr; +``` + +```css interactive-example-choice +border-start-end-radius: 50%; +writing-mode: vertical-rl; +``` + +```html interactive-example +<section class="default-example" id="default-example"> + <div class="transition-all" id="example-element"> + This is a box with a top right rounded corner. + </div> +</section> +``` + +```css interactive-example +#example-element { + width: 80%; + height: 80%; + display: flex; + justify-content: center; + flex-direction: column; + background-color: #5b6dcd; + color: white; + padding: 10px; +} +``` This property affects the corner between the block-start and the inline-end sides of the element. For instance, in a `horizontal-tb` writing mode with `ltr` direction, it corresponds to the {{CSSxRef("border-top-right-radius")}} property. diff --git a/files/en-us/web/css/border-start-start-radius/index.md b/files/en-us/web/css/border-start-start-radius/index.md index b40104aab47b328..fd5746a3879e9b2 100644 --- a/files/en-us/web/css/border-start-start-radius/index.md +++ b/files/en-us/web/css/border-start-start-radius/index.md @@ -9,7 +9,47 @@ browser-compat: css.properties.border-start-start-radius The **`border-start-start-radius`** [CSS](/en-US/docs/Web/CSS) property defines a logical border radius on an element, which maps to a physical border radius that depends on the element's {{cssxref("writing-mode")}}, {{cssxref("direction")}}, and {{cssxref("text-orientation")}}. This is useful when building styles to work regardless of the [text orientation](/en-US/docs/Web/CSS/text-orientation) and [writing mode](/en-US/docs/Web/CSS/CSS_writing_modes). -{{EmbedInteractiveExample("pages/css/border-start-start-radius.html")}} +{{InteractiveExample("CSS Demo: border-start-start-radius")}} + +```css interactive-example-choice +border-start-start-radius: 80px 80px; +``` + +```css interactive-example-choice +border-start-start-radius: 250px 100px; +direction: rtl; +``` + +```css interactive-example-choice +border-start-start-radius: 50%; +writing-mode: vertical-lr; +``` + +```css interactive-example-choice +border-start-start-radius: 50%; +writing-mode: vertical-rl; +``` + +```html interactive-example +<section class="default-example" id="default-example"> + <div class="transition-all" id="example-element"> + This is a box with a top left rounded corner. + </div> +</section> +``` + +```css interactive-example +#example-element { + width: 80%; + height: 80%; + display: flex; + justify-content: center; + flex-direction: column; + background-color: #5b6dcd; + color: white; + padding: 10px; +} +``` This property affects the corner between the block-start and the inline-start sides of the element. For instance, in a `horizontal-tb` writing mode with `ltr` direction, it corresponds to the {{CSSxRef("border-top-left-radius")}} property. diff --git a/files/en-us/web/css/border-style/index.md b/files/en-us/web/css/border-style/index.md index d56bd69a2eb3625..1cb983efac38a32 100644 --- a/files/en-us/web/css/border-style/index.md +++ b/files/en-us/web/css/border-style/index.md @@ -9,7 +9,54 @@ browser-compat: css.properties.border-style The **`border-style`** [shorthand](/en-US/docs/Web/CSS/CSS_cascade/Shorthand_properties) [CSS](/en-US/docs/Web/CSS) property sets the line style for all four sides of an element's border. -{{EmbedInteractiveExample("pages/css/border-style.html")}} +{{InteractiveExample("CSS Demo: border-style")}} + +```css interactive-example-choice +border-style: none; +``` + +```css interactive-example-choice +border-style: dotted; +``` + +```css interactive-example-choice +border-style: inset; +``` + +```css interactive-example-choice +border-style: dashed solid; +``` + +```css interactive-example-choice +border-style: dashed double none; +``` + +```css interactive-example-choice +border-style: dashed groove none dotted; +``` + +```html interactive-example +<section id="default-example"> + <div class="transition-all" id="example-element"> + This is a box with a border around it. + </div> +</section> +``` + +```css interactive-example +#example-element { + background-color: #eee; + color: #000; + border: 0.75em solid; + padding: 0.75em; + width: 80%; + height: 100px; +} + +body { + background-color: #fff; +} +``` ## Constituent properties diff --git a/files/en-us/web/css/border-top-color/index.md b/files/en-us/web/css/border-top-color/index.md index 76f4355481a8fc8..86019dfb260358a 100644 --- a/files/en-us/web/css/border-top-color/index.md +++ b/files/en-us/web/css/border-top-color/index.md @@ -9,7 +9,46 @@ browser-compat: css.properties.border-top-color The **`border-top-color`** [CSS](/en-US/docs/Web/CSS) property sets the color of an element's top [border](/en-US/docs/Web/CSS/border). It can also be set with the shorthand CSS properties {{cssxref("border-color")}} or {{cssxref("border-top")}}. -{{EmbedInteractiveExample("pages/css/border-top-color.html")}} +{{InteractiveExample("CSS Demo: border-top-color")}} + +```css interactive-example-choice +border-top-color: red; +``` + +```css interactive-example-choice +border-top-color: #32a1ce; +``` + +```css interactive-example-choice +border-top-color: rgb(170, 50, 220, 0.6); +``` + +```css interactive-example-choice +border-top-color: hsl(60, 90%, 50%, 0.8); +``` + +```css interactive-example-choice +border-top-color: transparent; +``` + +```html interactive-example +<section class="default-example" id="default-example"> + <div class="transition-all" id="example-element"> + This is a box with a border around it. + </div> +</section> +``` + +```css interactive-example +#example-element { + background-color: #eee; + color: #000; + border: 0.75em solid; + padding: 0.75em; + width: 80%; + height: 100px; +} +``` ## Syntax @@ -47,7 +86,7 @@ The `border-top-color` property is specified as a single value. ## Examples -### A simple div with a border +### A div with a border #### HTML @@ -76,7 +115,7 @@ The `border-top-color` property is specified as a single value. #### Result -{{EmbedLiveSample('A_simple_div_with_a_border')}} +{{EmbedLiveSample('A_div_with_a_border')}} ## Specifications diff --git a/files/en-us/web/css/border-top-left-radius/index.md b/files/en-us/web/css/border-top-left-radius/index.md index 896a530cdfe319b..350ab6c5a7290cf 100644 --- a/files/en-us/web/css/border-top-left-radius/index.md +++ b/files/en-us/web/css/border-top-left-radius/index.md @@ -9,7 +9,46 @@ browser-compat: css.properties.border-top-left-radius The **`border-top-left-radius`** [CSS](/en-US/docs/Web/CSS) property rounds the top-left corner of an element by specifying the radius (or the radius of the semi-major and semi-minor axes) of the ellipse defining the curvature of the corner. -{{EmbedInteractiveExample("pages/css/border-top-left-radius.html")}} +{{InteractiveExample("CSS Demo: border-top-left-radius")}} + +```css interactive-example-choice +border-top-left-radius: 80px 80px; +``` + +```css interactive-example-choice +border-top-left-radius: 250px 100px; +``` + +```css interactive-example-choice +border-top-left-radius: 50%; +``` + +```css interactive-example-choice +border-top-left-radius: 50%; +border: black 10px double; +background-clip: content-box; +``` + +```html interactive-example +<section class="default-example" id="default-example"> + <div class="transition-all" id="example-element"> + This is a box with a top left rounded corner. + </div> +</section> +``` + +```css interactive-example +#example-element { + width: 80%; + height: 80%; + display: flex; + justify-content: center; + flex-direction: column; + background-color: #5b6dcd; + color: white; + padding: 10px; +} +``` The rounding can be a circle or an ellipse, or if one of the value is `0`, no rounding is done and the corner is square. diff --git a/files/en-us/web/css/border-top-right-radius/index.md b/files/en-us/web/css/border-top-right-radius/index.md index 32cbd202e9bc6c6..0eeeb7b172787f7 100644 --- a/files/en-us/web/css/border-top-right-radius/index.md +++ b/files/en-us/web/css/border-top-right-radius/index.md @@ -9,7 +9,46 @@ browser-compat: css.properties.border-top-right-radius The **`border-top-right-radius`** [CSS](/en-US/docs/Web/CSS) property rounds the top-right corner of an element by specifying the radius (or the radius of the semi-major and semi-minor axes) of the ellipse defining the curvature of the corner. -{{EmbedInteractiveExample("pages/css/border-top-right-radius.html")}} +{{InteractiveExample("CSS Demo: border-top-right-radius")}} + +```css interactive-example-choice +border-top-right-radius: 80px 80px; +``` + +```css interactive-example-choice +border-top-right-radius: 250px 100px; +``` + +```css interactive-example-choice +border-top-right-radius: 50%; +``` + +```css interactive-example-choice +border-top-right-radius: 50%; +border: black 10px double; +background-clip: content-box; +``` + +```html interactive-example +<section class="default-example" id="default-example"> + <div class="transition-all" id="example-element"> + This is a box with a top right rounded corner. + </div> +</section> +``` + +```css interactive-example +#example-element { + width: 80%; + height: 80%; + display: flex; + justify-content: center; + flex-direction: column; + background-color: #5b6dcd; + color: white; + padding: 10px; +} +``` The rounding can be a circle or an ellipse, or if one of the value is `0` no rounding is done and the corner is square. diff --git a/files/en-us/web/css/border-top-style/index.md b/files/en-us/web/css/border-top-style/index.md index 94053525d485cf3..3b830e565ec6764 100644 --- a/files/en-us/web/css/border-top-style/index.md +++ b/files/en-us/web/css/border-top-style/index.md @@ -9,7 +9,54 @@ browser-compat: css.properties.border-top-style The **`border-top-style`** [CSS](/en-US/docs/Web/CSS) property sets the line style of an element's top {{CSSxRef("border")}}. -{{EmbedInteractiveExample("pages/css/border-top-style.html")}} +{{InteractiveExample("CSS Demo: border-top-style")}} + +```css interactive-example-choice +border-top-style: none; +``` + +```css interactive-example-choice +border-top-style: dotted; +``` + +```css interactive-example-choice +border-top-style: dashed; +``` + +```css interactive-example-choice +border-top-style: solid; +``` + +```css interactive-example-choice +border-top-style: groove; +``` + +```css interactive-example-choice +border-top-style: inset; +``` + +```html interactive-example +<section id="default-example"> + <div class="transition-all" id="example-element"> + This is a box with a border around it. + </div> +</section> +``` + +```css interactive-example +#example-element { + background-color: #eee; + color: #000; + border: 0.75em solid; + padding: 0.75em; + width: 80%; + height: 100px; +} + +body { + background-color: #fff; +} +``` > [!NOTE] > The specification doesn't define how borders of different styles connect in the corners. diff --git a/files/en-us/web/css/border-top-width/index.md b/files/en-us/web/css/border-top-width/index.md index 3b5161681883165..d3720afb77c6f97 100644 --- a/files/en-us/web/css/border-top-width/index.md +++ b/files/en-us/web/css/border-top-width/index.md @@ -9,7 +9,46 @@ browser-compat: css.properties.border-top-width The **`border-top-width`** [CSS](/en-US/docs/Web/CSS) property sets the width of the top border of an element. -{{EmbedInteractiveExample("pages/css/border-top-width.html")}} +{{InteractiveExample("CSS Demo: border-top-width")}} + +```css interactive-example-choice +border-top-width: thick; +``` + +```css interactive-example-choice +border-top-width: 2em; +``` + +```css interactive-example-choice +border-top-width: 4px; +``` + +```css interactive-example-choice +border-top-width: 2ex; +``` + +```css interactive-example-choice +border-top-width: 0; +``` + +```html interactive-example +<section class="default-example" id="default-example"> + <div class="transition-all" id="example-element"> + This is a box with a border around it. + </div> +</section> +``` + +```css interactive-example +#example-element { + background-color: palegreen; + color: #000; + border: 0 solid crimson; + padding: 0.75em; + width: 80%; + height: 100px; +} +``` ## Syntax diff --git a/files/en-us/web/css/border-top/index.md b/files/en-us/web/css/border-top/index.md index 55a3dc1104f3eab..25a16d1f1f9649b 100644 --- a/files/en-us/web/css/border-top/index.md +++ b/files/en-us/web/css/border-top/index.md @@ -9,7 +9,45 @@ browser-compat: css.properties.border-top The **`border-top`** [shorthand](/en-US/docs/Web/CSS/CSS_cascade/Shorthand_properties) [CSS](/en-US/docs/Web/CSS) property sets all the properties of an element's top [border](/en-US/docs/Web/CSS/border). -{{EmbedInteractiveExample("pages/css/border-top.html")}} +{{InteractiveExample("CSS Demo: border-top")}} + +```css interactive-example-choice +border-top: solid; +``` + +```css interactive-example-choice +border-top: dashed red; +``` + +```css interactive-example-choice +border-top: 1rem solid; +``` + +```css interactive-example-choice +border-top: thick double #32a1ce; +``` + +```css interactive-example-choice +border-top: 4mm ridge rgba(211, 220, 50, 0.6); +``` + +```html interactive-example +<section class="default-example" id="default-example"> + <div class="transition-all" id="example-element"> + This is a box with a border around it. + </div> +</section> +``` + +```css interactive-example +#example-element { + background-color: #eee; + color: #8b008b; + padding: 0.75em; + width: 80%; + height: 100px; +} +``` As with all shorthand properties, `border-top` always sets the values of all of the properties that it can set, even if they are not specified. It sets those that are not specified to their default values. Consider the following code: diff --git a/files/en-us/web/css/border-width/index.md b/files/en-us/web/css/border-width/index.md index f3b747142a4e370..38d9e0cc26bae3a 100644 --- a/files/en-us/web/css/border-width/index.md +++ b/files/en-us/web/css/border-width/index.md @@ -9,7 +9,46 @@ browser-compat: css.properties.border-width The **`border-width`** [shorthand](/en-US/docs/Web/CSS/CSS_cascade/Shorthand_properties) [CSS](/en-US/docs/Web/CSS) property sets the width of an element's border. -{{EmbedInteractiveExample("pages/css/border-width.html")}} +{{InteractiveExample("CSS Demo: border-width")}} + +```css interactive-example-choice +border-width: thick; +``` + +```css interactive-example-choice +border-width: 1em; +``` + +```css interactive-example-choice +border-width: 4px 1.25em; +``` + +```css interactive-example-choice +border-width: 2ex 1.25ex 0.5ex; +``` + +```css interactive-example-choice +border-width: 0 4px 8px 12px; +``` + +```html interactive-example +<section class="default-example" id="default-example"> + <div class="transition-all" id="example-element"> + This is a box with a border around it. + </div> +</section> +``` + +```css interactive-example +#example-element { + background-color: palegreen; + color: #000; + border: 0 solid crimson; + padding: 0.75em; + width: 80%; + height: 100px; +} +``` ## Constituent properties diff --git a/files/en-us/web/css/border/index.md b/files/en-us/web/css/border/index.md index 4bfe8c03394ebb9..fbaecf73fc6c0dd 100644 --- a/files/en-us/web/css/border/index.md +++ b/files/en-us/web/css/border/index.md @@ -9,7 +9,45 @@ browser-compat: css.properties.border The **`border`** [shorthand](/en-US/docs/Web/CSS/CSS_cascade/Shorthand_properties) [CSS](/en-US/docs/Web/CSS) property sets an element's border. It sets the values of {{Cssxref("border-width")}}, {{Cssxref("border-style")}}, and {{Cssxref("border-color")}}. -{{EmbedInteractiveExample("pages/css/border.html")}} +{{InteractiveExample("CSS Demo: border")}} + +```css interactive-example-choice +border: solid; +``` + +```css interactive-example-choice +border: dashed red; +``` + +```css interactive-example-choice +border: 1rem solid; +``` + +```css interactive-example-choice +border: thick double #32a1ce; +``` + +```css interactive-example-choice +border: 4mm ridge rgba(211, 220, 50, 0.6); +``` + +```html interactive-example +<section class="default-example" id="default-example"> + <div class="transition-all" id="example-element"> + This is a box with a border around it. + </div> +</section> +``` + +```css interactive-example +#example-element { + background-color: #eee; + color: #8b008b; + padding: 0.75em; + width: 80%; + height: 100px; +} +``` ## Constituent properties @@ -58,7 +96,7 @@ The `border` property may be specified using one, two, or three of the values li ## Description -As with all shorthand properties, any omitted sub-values will be set to their [initial value](/en-US/docs/Web/CSS/CSS_cascade/initial_value). Importantly, `border` cannot be used to specify a custom value for {{cssxref("border-image")}}, but instead sets it to its initial value, i.e., `none`. +As with all shorthand properties, any omitted sub-values will be set to their [initial value](/en-US/docs/Web/CSS/CSS_cascade/Value_processing#initial_value). Importantly, `border` cannot be used to specify a custom value for {{cssxref("border-image")}}, but instead sets it to its initial value, i.e., `none`. The `border` shorthand is especially useful when you want all four borders to be the same. To make them different from each other, however, you can use the longhand {{Cssxref("border-width")}}, {{Cssxref("border-style")}}, and {{Cssxref("border-color")}} properties, which accept different values for each side. Alternatively, you can target one border at a time with the physical (e.g., {{Cssxref("border-top")}} ) and logical (e.g., {{Cssxref("border-block-start")}}) border properties. diff --git a/files/en-us/web/css/bottom/index.md b/files/en-us/web/css/bottom/index.md index 7ea40b0bfe24e77..fc32b1b9b909a42 100644 --- a/files/en-us/web/css/bottom/index.md +++ b/files/en-us/web/css/bottom/index.md @@ -9,7 +9,57 @@ browser-compat: css.properties.bottom The **`bottom`** [CSS](/en-US/docs/Web/CSS) property participates in setting the vertical position of a [positioned element](/en-US/docs/Web/CSS/position). This {{glossary("inset properties", "inset property")}} has no effect on non-positioned elements. -{{EmbedInteractiveExample("pages/css/bottom.html")}} +{{InteractiveExample("CSS Demo: bottom")}} + +```css interactive-example-choice +bottom: 0; +``` + +```css interactive-example-choice +bottom: 4em; +``` + +```css interactive-example-choice +bottom: 10%; +``` + +```css interactive-example-choice +bottom: 20px; +``` + +```html interactive-example +<section id="default-example"> + <div class="example-container"> + <div id="example-element">I am absolutely positioned.</div> + <p> + As much mud in the streets as if the waters had but newly retired from the + face of the earth, and it would not be wonderful to meet a Megalosaurus, + forty feet long or so, waddling like an elephantine lizard up Holborn + Hill. + </p> + </div> +</section> +``` + +```css interactive-example +.example-container { + border: 0.75em solid; + padding: 0.75em; + text-align: left; + position: relative; + width: 100%; + min-height: 200px; +} + +#example-element { + background-color: #264653; + border: 4px solid #ffb500; + color: white; + position: absolute; + width: 140px; + height: 60px; +} +``` The effect of `bottom` depends on how the element is positioned (i.e., the value of the {{cssxref("position")}} property): @@ -62,9 +112,6 @@ bottom: unset; - for _absolutely positioned elements_, the position of the element is based on the {{Cssxref("top")}} property, while `height: auto` is treated as a height based on the content; or if `top` is also `auto`, the element is positioned where it should vertically be positioned if it were a static element. - for _relatively positioned elements_, the distance of the element from its normal position is based on the {{Cssxref("top")}} property; or if `top` is also `auto`, the element is not moved vertically at all. -- `inherit` - - : Specifies that the value is the same as the computed value from its parent element (which might not be its containing block). This computed value is then handled as if it were a {{cssxref("&lt;length&gt;")}}, {{cssxref("&lt;percentage&gt;")}}, or the `auto` keyword. - ## Formal definition {{cssinfo}} diff --git a/files/en-us/web/css/box-align/index.md b/files/en-us/web/css/box-align/index.md index 9fc36e1dc101d79..403288228e48d2f 100644 --- a/files/en-us/web/css/box-align/index.md +++ b/files/en-us/web/css/box-align/index.md @@ -67,67 +67,54 @@ If the alignment is set using the element's `align` attribute, then the style is ## Formal syntax -```plain -box-align = - start | center | end | baseline | stretch -``` +{{CSSSyntaxRaw(`box-align = start | center | end | baseline | stretch`)}} ## Examples ### Setting box alignment ```html -<!doctype html> -<html lang="en-US"> - <head> - <meta charset="UTF-8" /> - <title>CSS box-align example</title> - <style> - div.example { - display: box; /* As specified */ - display: -moz-box; /* Mozilla */ - display: -webkit-box; /* WebKit */ - - /* Make this box taller than the children, +<div class="example"> + <p>I will be second from the bottom of div.example, centered horizontally.</p> + <p>I will be on the bottom of div.example, centered horizontally.</p> +</div> +``` + +```css +div.example { + display: box; /* As specified */ + display: -moz-box; /* Mozilla */ + display: -webkit-box; /* WebKit */ + + /* Make this box taller than the children, so there is room for the box-pack */ - height: 400px; + height: 400px; - /* Make this box wider than the children + /* Make this box wider than the children so there is room for the box-align */ - width: 300px; - - /* Children should be oriented vertically */ - box-orient: vertical; /* As specified */ - -moz-box-orient: vertical; /* Mozilla */ - -webkit-box-orient: vertical; /* WebKit */ - - /* Align children to the horizontal center of this box */ - box-align: center; /* As specified */ - -moz-box-align: center; /* Mozilla */ - -webkit-box-align: center; /* WebKit */ - - /* Pack children to the bottom of this box */ - box-pack: end; /* As specified */ - -moz-box-pack: end; /* Mozilla */ - -webkit-box-pack: end; /* WebKit */ - } - - div.example > p { - /* Make children narrower than their parent, + width: 300px; + + /* Children should be oriented vertically */ + box-orient: vertical; /* As specified */ + -moz-box-orient: vertical; /* Mozilla */ + -webkit-box-orient: vertical; /* WebKit */ + + /* Align children to the horizontal center of this box */ + box-align: center; /* As specified */ + -moz-box-align: center; /* Mozilla */ + -webkit-box-align: center; /* WebKit */ + + /* Pack children to the bottom of this box */ + box-pack: end; /* As specified */ + -moz-box-pack: end; /* Mozilla */ + -webkit-box-pack: end; /* WebKit */ +} + +div.example > p { + /* Make children narrower than their parent, so there is room for the box-align */ - width: 200px; - } - </style> - </head> - <body> - <div class="example"> - <p> - I will be second from the bottom of div.example, centered horizontally. - </p> - <p>I will be on the bottom of div.example, centered horizontally.</p> - </div> - </body> -</html> + width: 200px; +} ``` ## Specifications diff --git a/files/en-us/web/css/box-decoration-break/index.md b/files/en-us/web/css/box-decoration-break/index.md index c47460592e49d71..ed9711d0b74000d 100644 --- a/files/en-us/web/css/box-decoration-break/index.md +++ b/files/en-us/web/css/box-decoration-break/index.md @@ -9,7 +9,46 @@ browser-compat: css.properties.box-decoration-break The **`box-decoration-break`** [CSS](/en-US/docs/Web/CSS) property specifies how an element's [fragments](/en-US/docs/Web/CSS/CSS_fragmentation) should be rendered when broken across multiple lines, columns, or pages. -{{EmbedInteractiveExample("pages/css/box-decoration-break.html")}} +{{InteractiveExample("CSS Demo: box-decoration-break")}} + +```css interactive-example-choice +-webkit-box-decoration-break: slice; +box-decoration-break: slice; +``` + +```css interactive-example-choice +-webkit-box-decoration-break: clone; +box-decoration-break: clone; +``` + +```html interactive-example +<section id="default-example"> + <div id="example-container"> + <span id="example-element">This text breaks across multiple lines.</span> + </div> +</section> +``` + +```css interactive-example +#example-container { + width: 14rem; +} + +#example-element { + background: linear-gradient(to bottom right, #6f6f6f, #000); + color: white; + box-shadow: + 8px 8px 10px 0 #ff1492, + -5px -5px 5px 0 #00f, + 5px 5px 15px 0 #ff0; + padding: 0 1em; + border-radius: 16px; + border-style: solid; + margin-left: 10px; + font: 24px sans-serif; + line-height: 2; +} +``` The specified value will impact the appearance of the following properties: diff --git a/files/en-us/web/css/box-direction/index.md b/files/en-us/web/css/box-direction/index.md index a0848d99ea0471a..5e02bfc381ad800 100644 --- a/files/en-us/web/css/box-direction/index.md +++ b/files/en-us/web/css/box-direction/index.md @@ -56,10 +56,7 @@ If the direction is set using the element's `dir` attribute, then the style is i ## Formal syntax -```plain -box-direction = - normal | reverse | inherit -``` +{{CSSSyntaxRaw(`box-direction = normal | reverse`)}} ## Examples diff --git a/files/en-us/web/css/box-flex-group/index.md b/files/en-us/web/css/box-flex-group/index.md index c54dd0fe8fac5bc..225fc97c2cdd0c7 100644 --- a/files/en-us/web/css/box-flex-group/index.md +++ b/files/en-us/web/css/box-flex-group/index.md @@ -40,14 +40,11 @@ The `box-flex-group` property is specified as any positive {{CSSxRef("&lt;intege ## Formal syntax -```plain -box-flex-group = - <integer> -``` +{{CSSSyntaxRaw(`box-flex-group = <integer>`)}} ## Examples -### Simple usage example +### Basic usage example In the original flexbox spec, `box-flex-group` could be used to assign flex children to different groups to distribute flexible space between: diff --git a/files/en-us/web/css/box-flex/index.md b/files/en-us/web/css/box-flex/index.md index 41abb30b48d052a..f3415ff460dbf11 100644 --- a/files/en-us/web/css/box-flex/index.md +++ b/files/en-us/web/css/box-flex/index.md @@ -55,7 +55,7 @@ If the flex value is set using the element's `flex` attribute, then the style is To make XUL elements in a containing box the same size, set the containing box's `equalsize` attribute to the value `always`. This attribute does not have a corresponding CSS property. -A trick to make all content elements in a containing box the same size, is to give them all a fixed size (e.g. `height: 0`), and the same `box-flex` value greater than zero (e.g. `-moz-box-flex: 1`). +A trick to make all content elements in a containing box the same size, is to give them all a fixed size (e.g., `height: 0`), and the same `box-flex` value greater than zero (e.g., `-moz-box-flex: 1`). ## Formal definition @@ -63,47 +63,36 @@ A trick to make all content elements in a containing box the same size, is to gi ## Formal syntax -```plain -box-flex = - <number> -``` +{{CSSSyntaxRaw(`box-flex = <number>`)}} ## Examples ### Setting box-flex ```html -<!doctype html> -<html lang="en-US"> - <head> - <meta charset="UTF-8" /> - <title>-moz-box-flex example</title> - <style> - div.example { - display: -moz-box; - display: -webkit-box; - border: 1px solid black; - width: 100%; - } - div.example > p:nth-child(1) { - -moz-box-flex: 1; /* Mozilla */ - -webkit-box-flex: 1; /* WebKit */ - border: 1px solid black; - } - div.example > p:nth-child(2) { - -moz-box-flex: 0; /* Mozilla */ - -webkit-box-flex: 0; /* WebKit */ - border: 1px solid black; - } - </style> - </head> - <body> - <div class="example"> - <p>I will expand to fill extra space</p> - <p>I will not expand</p> - </div> - </body> -</html> +<div class="example"> + <p>I will expand to fill extra space</p> + <p>I will not expand</p> +</div> +``` + +```css +div.example { + display: -moz-box; + display: -webkit-box; + border: 1px solid black; + width: 100%; +} +div.example > p:nth-child(1) { + -moz-box-flex: 1; /* Mozilla */ + -webkit-box-flex: 1; /* WebKit */ + border: 1px solid black; +} +div.example > p:nth-child(2) { + -moz-box-flex: 0; /* Mozilla */ + -webkit-box-flex: 0; /* WebKit */ + border: 1px solid black; +} ``` ## Specifications diff --git a/files/en-us/web/css/box-lines/index.md b/files/en-us/web/css/box-lines/index.md index 3f1fff846f9124a..a84c15b5f0ce8a5 100644 --- a/files/en-us/web/css/box-lines/index.md +++ b/files/en-us/web/css/box-lines/index.md @@ -53,14 +53,11 @@ The `box-lines` property is specified as one of the keyword values listed below. ## Formal syntax -```plain -box-lines = - single | multiple -``` +{{CSSSyntaxRaw(`box-lines = single | multiple`)}} ## Examples -### Simple usage example +### Basic usage example In the original version of the spec, `box-lines` allowed you to specify that you wanted your flex container's children to wrap onto multiple lines. This was only supported in WebKit-based browsers, with a prefix. diff --git a/files/en-us/web/css/box-ordinal-group/index.md b/files/en-us/web/css/box-ordinal-group/index.md index 61a15da086534a7..80311524ff453ec 100644 --- a/files/en-us/web/css/box-ordinal-group/index.md +++ b/files/en-us/web/css/box-ordinal-group/index.md @@ -38,10 +38,7 @@ The `box-ordinal-group` property is specified as any positive {{CSSxRef("&lt;int ## Formal syntax -```plain -box-ordinal-group = - <integer> -``` +{{CSSSyntaxRaw(`box-ordinal-group = <integer>`)}} ## Examples diff --git a/files/en-us/web/css/box-orient/index.md b/files/en-us/web/css/box-orient/index.md index d08e4347611c5cf..5ee8d326c64a43c 100644 --- a/files/en-us/web/css/box-orient/index.md +++ b/files/en-us/web/css/box-orient/index.md @@ -55,10 +55,7 @@ HTML DOM elements lay out their contents along the inline-axis by default. This ## Formal syntax -```plain -box-orient = - horizontal | vertical | inline-axis | block-axis | inherit -``` +{{CSSSyntaxRaw(`box-orient = horizontal | vertical | inline-axis | block-axis`)}} ## Examples diff --git a/files/en-us/web/css/box-pack/index.md b/files/en-us/web/css/box-pack/index.md index 1089e282362dfe3..01622f355bc7efa 100644 --- a/files/en-us/web/css/box-pack/index.md +++ b/files/en-us/web/css/box-pack/index.md @@ -82,10 +82,7 @@ If the packing is set using the element's `pack` attribute, then the style is ig ## Formal syntax -```plain -box-pack = - start | center | end | justify -``` +{{CSSSyntaxRaw(`box-pack = start | center | end | justify`)}} ## Examples diff --git a/files/en-us/web/css/box-shadow/index.md b/files/en-us/web/css/box-shadow/index.md index bd11820ae75ce48..b40ac8f5ba7cf23 100644 --- a/files/en-us/web/css/box-shadow/index.md +++ b/files/en-us/web/css/box-shadow/index.md @@ -9,7 +9,47 @@ browser-compat: css.properties.box-shadow The **`box-shadow`** [CSS](/en-US/docs/Web/CSS) property adds shadow effects around an element's frame. You can set multiple effects separated by commas. A box shadow is described by X and Y offsets relative to the element, blur and spread radius, and color. -{{EmbedInteractiveExample("pages/css/box-shadow.html")}} +{{InteractiveExample("CSS Demo: box-shadow")}} + +```css interactive-example-choice +box-shadow: 10px 5px 5px red; +``` + +```css interactive-example-choice +box-shadow: 60px -16px teal; +``` + +```css interactive-example-choice +box-shadow: 12px 12px 2px 1px rgba(0, 0, 255, 0.2); +``` + +```css interactive-example-choice +box-shadow: inset 5em 1em gold; +``` + +```css interactive-example-choice +box-shadow: + 3px 3px red, + -1em 0 0.4em olive; +``` + +```html interactive-example +<section id="default-example"> + <div class="transition-all" id="example-element"> + <p>This is a box with a box-shadow around it.</p> + </div> +</section> +``` + +```css interactive-example +#example-element { + margin: 20px auto; + padding: 0; + border: 2px solid #333; + width: 80%; + text-align: center; +} +``` The `box-shadow` property enables you to cast a drop shadow from the frame of almost any element. If a {{cssxref("border-radius")}} is specified on the element with a box shadow, the box shadow takes on the same rounded corners. The z-ordering of multiple box shadows is the same as multiple [text shadows](/en-US/docs/Web/CSS/text-shadow) (the first specified shadow is on top). diff --git a/files/en-us/web/css/box-sizing/index.md b/files/en-us/web/css/box-sizing/index.md index a5ab6115b195a9e..10386347fac1f81 100644 --- a/files/en-us/web/css/box-sizing/index.md +++ b/files/en-us/web/css/box-sizing/index.md @@ -9,7 +9,56 @@ browser-compat: css.properties.box-sizing The **`box-sizing`** [CSS](/en-US/docs/Web/CSS) property sets how the total width and height of an element is calculated. -{{EmbedInteractiveExample("pages/css/box-sizing.html")}} +{{InteractiveExample("CSS Demo: box-sizing")}} + +```css interactive-example-choice +box-sizing: content-box; +width: 100%; +``` + +```css interactive-example-choice +box-sizing: content-box; +width: 100%; +border: solid #5b6dcd 10px; +padding: 5px; +``` + +```css interactive-example-choice +box-sizing: border-box; +width: 100%; +border: solid #5b6dcd 10px; +padding: 5px; +``` + +```html interactive-example +<section id="default-example"> + <div id="example-element-parent"> + <p>Parent container</p> + <div class="transition-all" id="example-element"> + <p>Child container</p> + </div> + </div> +</section> +``` + +```css interactive-example +#example-element-parent { + width: 220px; + height: 200px; + border: solid 10px #ffc129; + margin: 0.8em; +} + +#example-element { + height: 60px; + margin: 2em auto; + background-color: rgba(81, 81, 81, 0.6); +} + +#example-element > p { + margin: 0; +} +``` By default in the [CSS box model](/en-US/docs/Web/CSS/CSS_box_model/Introduction_to_the_CSS_box_model), the `width` and `height` you assign to an element is applied only to the element's content box. If the element has any border or padding, this is then added to the `width` and `height` to arrive at the size of the box that's rendered on the screen. This means that when you set `width` and `height`, you have to adjust the value you give to allow for any border or padding that may be added. For example, if you have four boxes with `width: 25%;`, if any has left or right padding or a left or right border, they will not by default fit on one line within the constraints of the parent container. diff --git a/files/en-us/web/css/break-after/index.md b/files/en-us/web/css/break-after/index.md index c2f9bad6aef9b1c..791b3647f40e01c 100644 --- a/files/en-us/web/css/break-after/index.md +++ b/files/en-us/web/css/break-after/index.md @@ -9,7 +9,78 @@ browser-compat: css.properties.break-after The **`break-after`** [CSS](/en-US/docs/Web/CSS) property sets how page, column, or region breaks should behave after a generated box. If there is no generated box, the property is ignored. -{{EmbedInteractiveExample("pages/css/break-after.html")}} +{{InteractiveExample("CSS Demo: break-after")}} + +```css interactive-example-choice +break-after: auto; +``` + +```css interactive-example-choice +break-after: page; +``` + +```html interactive-example +<section id="default-example"> + <div> + <p> + The effect of this property can be noticed when the document is being + printed or a preview of a print is displayed. + </p> + <button id="print-btn">Show Print Preview</button> + <div class="box-container"> + <div class="box">Content before the property</div> + <div class="box" id="example-element">Content with 'break-after'</div> + <div class="box">Content after the property</div> + </div> + </div> +</section> +``` + +```css interactive-example +.box { + border: solid #5b6dcd 5px; + background-color: #5b6dcd; + margin: 10px 0; + padding: 5px; +} + +#example-element { + border: solid 5px #ffc129; + background-color: #ffc129; + color: black; +} + +.hide-element { + display: none; +} +``` + +```js interactive-example +const btn = document.getElementById("print-btn"); +const editorContainer = document.getElementsByClassName( + "css-editor-container", +)[0]; +const exampleHTMLElement = document.getElementById("default-example"); + +const printableSection = document.createElement("div"); +printableSection.setAttribute("id", "printable-section"); +printableSection.classList.add("hide-element"); +document.body.appendChild(printableSection); + +btn.addEventListener("click", () => { + const exampleContent = exampleHTMLElement.innerHTML; + + editorContainer.classList.add("hide-element"); + printableSection.innerHTML = exampleContent; + printableSection.classList.remove("hide-element"); + + window.print(); + + printableSection.classList.add("hide-element"); + printableSection.innerHTML = ""; + editorContainer.classList.remove("hide-element"); +}); +``` ## Syntax diff --git a/files/en-us/web/css/break-before/index.md b/files/en-us/web/css/break-before/index.md index f163a9f42640291..3750eb40df0aa02 100644 --- a/files/en-us/web/css/break-before/index.md +++ b/files/en-us/web/css/break-before/index.md @@ -9,7 +9,78 @@ browser-compat: css.properties.break-before The **`break-before`** [CSS](/en-US/docs/Web/CSS) property sets how page, column, or region breaks should behave before a generated box. If there is no generated box, the property is ignored. -{{EmbedInteractiveExample("pages/css/break-before.html")}} +{{InteractiveExample("CSS Demo: break-before")}} + +```css interactive-example-choice +break-before: auto; +``` + +```css interactive-example-choice +break-before: page; +``` + +```html interactive-example +<section id="default-example"> + <div> + <p> + The effect of this property can be noticed when the document is being + printed or a preview of a print is displayed. + </p> + <button id="print-btn">Show Print Preview</button> + <div class="box-container"> + <div class="box">Content before the property</div> + <div class="box" id="example-element">Content with 'break-before'</div> + <div class="box">Content after the property</div> + </div> + </div> +</section> +``` + +```css interactive-example +.box { + border: solid #5b6dcd 5px; + background-color: #5b6dcd; + margin: 10px 0; + padding: 5px; +} + +#example-element { + border: solid 5px #ffc129; + background-color: #ffc129; + color: black; +} + +.hide-element { + display: none; +} +``` + +```js interactive-example +const btn = document.getElementById("print-btn"); +const editorContainer = document.getElementsByClassName( + "css-editor-container", +)[0]; +const exampleHTMLElement = document.getElementById("default-example"); + +const printableSection = document.createElement("div"); +printableSection.setAttribute("id", "printable-section"); +printableSection.classList.add("hide-element"); +document.body.appendChild(printableSection); + +btn.addEventListener("click", () => { + const exampleContent = exampleHTMLElement.innerHTML; + + editorContainer.classList.add("hide-element"); + printableSection.innerHTML = exampleContent; + printableSection.classList.remove("hide-element"); + + window.print(); + + printableSection.classList.add("hide-element"); + printableSection.innerHTML = ""; + editorContainer.classList.remove("hide-element"); +}); +``` ## Syntax diff --git a/files/en-us/web/css/break-inside/index.md b/files/en-us/web/css/break-inside/index.md index bbfe488d6376589..5876dc8a33f3bbf 100644 --- a/files/en-us/web/css/break-inside/index.md +++ b/files/en-us/web/css/break-inside/index.md @@ -9,7 +9,84 @@ browser-compat: css.properties.break-inside The **`break-inside`** [CSS](/en-US/docs/Web/CSS) property sets how page, column, or region breaks should behave inside a generated box. If there is no generated box, the property is ignored. -{{EmbedInteractiveExample("pages/css/break-inside.html")}} +{{InteractiveExample("CSS Demo: break-inside")}} + +```css interactive-example-choice +break-inside: auto; +``` + +```css interactive-example-choice +break-inside: avoid; +``` + +```html interactive-example +<section id="default-example"> + <div> + <p> + The effect of this property can be noticed when the document is being + printed or a preview of a print is displayed. + </p> + <button id="print-btn">Show Print Preview</button> + <div class="box-container"> + <div class="box">Content before the property</div> + <div class="box" id="example-element">Content with 'break-inside'</div> + <div class="box">Content after the property</div> + </div> + </div> +</section> +``` + +```css interactive-example +.box { + border: solid #5b6dcd 5px; + background-color: #5b6dcd; + margin: 10px 0; + padding: 5px; +} + +#example-element { + border: solid 5px #ffc129; + background-color: #ffc129; + color: black; +} + +.hide-element { + display: none; +} + +@media print { + #example-element { + height: 25cm; + } +} +``` + +```js interactive-example +const btn = document.getElementById("print-btn"); +const editorContainer = document.getElementsByClassName( + "css-editor-container", +)[0]; +const exampleHTMLElement = document.getElementById("default-example"); + +const printableSection = document.createElement("div"); +printableSection.setAttribute("id", "printable-section"); +printableSection.classList.add("hide-element"); +document.body.appendChild(printableSection); + +btn.addEventListener("click", () => { + const exampleContent = exampleHTMLElement.innerHTML; + + editorContainer.classList.add("hide-element"); + printableSection.innerHTML = exampleContent; + printableSection.classList.remove("hide-element"); + + window.print(); + + printableSection.classList.add("hide-element"); + printableSection.innerHTML = ""; + editorContainer.classList.remove("hide-element"); +}); +``` ## Syntax diff --git a/files/en-us/web/css/calc-keyword/index.md b/files/en-us/web/css/calc-keyword/index.md index 7fcab3c2f804c81..4b5e52c0ff681ac 100644 --- a/files/en-us/web/css/calc-keyword/index.md +++ b/files/en-us/web/css/calc-keyword/index.md @@ -114,7 +114,7 @@ The second box shows how to use `pi` inside a [`sin()`](/en-US/docs/Web/CSS/sin) .container { display: flex; flex-direction: column; - align-items: left; + align-items: start; width: 200px; } .container > div { @@ -163,12 +163,12 @@ const eValue = document.querySelector("#e-value"); const piValue = document.querySelector("#pi-value"); eInput.addEventListener("input", function () { - e.style.transform = "rotate(calc(1deg * pow(" + this.value + ", e)))"; + e.style.transform = `rotate(calc(1deg * pow(${this.value}, e)))`; eValue.textContent = e.style.transform; }); piInput.addEventListener("input", function () { - pi.style.rotate = "calc(sin(" + this.value + " * pi) * 100deg)"; + pi.style.rotate = `calc(sin(${this.value} * pi) * 100deg)`; piValue.textContent = pi.style.rotate; }); ``` diff --git a/files/en-us/web/css/calc-size/index.md b/files/en-us/web/css/calc-size/index.md index 8a40857db16fdc1..e32603745fcf641 100644 --- a/files/en-us/web/css/calc-size/index.md +++ b/files/en-us/web/css/calc-size/index.md @@ -221,7 +221,7 @@ p { } ``` -In the CSS, we use [flexbox](/en-US/docs/Web/CSS/CSS_flexible_box_layout) to center the child elements inside the `<section>`, and set the`width` and `height` of the `<section>` to `calc-size()` functions. The `width` is set equal to `fit-content` plus `6rem`. The `height` is set to `auto` multiplied by two. +In the CSS, we use [flexbox](/en-US/docs/Web/CSS/CSS_flexible_box_layout) to center the child elements inside the `<section>`, and set the `width` and `height` of the `<section>` to `calc-size()` functions. The `width` is set equal to `fit-content` plus `6rem`. The `height` is set to `auto` multiplied by two. ```css section { @@ -249,7 +249,7 @@ This example demonstrates how to use `calc-size()` to animate between a specific #### HTML -The HTML contains a single {{htmlelement("section")}} element with [`tabindex="0"`](/en-US/docs/Web/HTML/Global_attributes/tabindex) set on it so it can receive keyboard focus. The `<section>` contains {{htmlelement("header")}} and {{htmlelement("main")}} elements, each with their own child content. +The HTML contains a single {{htmlelement("section")}} element with [`tabindex="0"`](/en-US/docs/Web/HTML/Reference/Global_attributes/tabindex) set on it so it can receive keyboard focus. The `<section>` contains {{htmlelement("header")}} and {{htmlelement("main")}} elements, each with their own child content. ```html <section tabindex="0"> @@ -472,7 +472,7 @@ As mentioned earlier, it is possible to use another function inside `calc-size() #### HTML -The HTML contains a {{htmlelement("form")}} element containing three textual `<input>` types. Each `<input>` has a {{htmlelement("label")}} associated with it to make the form accessible, and a [`maxlength`](/en-US/docs/Web/HTML/Attributes/maxlength) applied to stop entered values getting long enough to break the form layout. +The HTML contains a {{htmlelement("form")}} element containing three textual `<input>` types. Each `<input>` has a {{htmlelement("label")}} associated with it to make the form accessible, and a [`maxlength`](/en-US/docs/Web/HTML/Reference/Attributes/maxlength) applied to stop entered values getting long enough to break the form layout. ```html <form> diff --git a/files/en-us/web/css/calc-sum/index.md b/files/en-us/web/css/calc-sum/index.md index b4a0c559c9d61fe..704fe6efa332103 100644 --- a/files/en-us/web/css/calc-sum/index.md +++ b/files/en-us/web/css/calc-sum/index.md @@ -2,7 +2,7 @@ title: <calc-sum> slug: Web/CSS/calc-sum page-type: css-type -browser-compat: css.types.calc-sum +spec-urls: https://drafts.csswg.org/css-values/#typedef-calc-sum --- {{CSSRef}} @@ -39,10 +39,6 @@ The `+` and `-` operators **must be surrounded by {{Glossary("whitespace")}}**. {{Specifications}} -## Browser compatibility - -{{Compat}} - ## See also - {{CSSxRef("&lt;calc-product&gt;")}} diff --git a/files/en-us/web/css/calc/index.md b/files/en-us/web/css/calc/index.md index 6b3a9a5a1508cc9..4ad9dad9e86bdbb 100644 --- a/files/en-us/web/css/calc/index.md +++ b/files/en-us/web/css/calc/index.md @@ -9,7 +9,40 @@ browser-compat: css.types.calc The **`calc()`** [CSS](/en-US/docs/Web/CSS) [function](/en-US/docs/Web/CSS/CSS_Values_and_Units/CSS_Value_Functions) lets you perform calculations when specifying CSS property values. It can be used with {{cssxref("&lt;length&gt;")}}, {{cssxref("&lt;frequency&gt;")}}, {{cssxref("&lt;angle&gt;")}}, {{cssxref("&lt;time&gt;")}}, {{cssxref("&lt;percentage&gt;")}}, {{cssxref("&lt;number&gt;")}}, {{cssxref("&lt;integer&gt;")}}, and {{cssxref("color_value", "&lt;color-function&gt;")}} values. -{{EmbedInteractiveExample("pages/css/function-calc.html")}} +{{InteractiveExample("CSS Demo: calc()")}} + +```css interactive-example-choice +width: calc(10px + 100px); +``` + +```css interactive-example-choice +width: calc(100% - 30px); +``` + +```css interactive-example-choice +width: calc(2em * 5); +``` + +```css interactive-example-choice +width: calc(var(--variable-width) + 20px); +``` + +```html interactive-example +<section class="default-example" id="default-example"> + <div class="transition-all" id="example-element">Change my width.</div> +</section> +``` + +```css interactive-example +:root { + --variable-width: 100px; +} + +#example-element { + border: 10px solid #000; + padding: 10px; +} +``` ## Syntax @@ -98,7 +131,7 @@ h1 { This ensures that text size will scale if the page is zoomed. -- [MDN Understanding WCAG, Guideline 1.4 explanations](/en-US/docs/Web/Accessibility/Understanding_WCAG/Perceivable#guideline_1.4_make_it_easier_for_users_to_see_and_hear_content_including_separating_foreground_from_background) +- [MDN Understanding WCAG, Guideline 1.4 explanations](/en-US/docs/Web/Accessibility/Guides/Understanding_WCAG/Perceivable#guideline_1.4_make_it_easier_for_users_to_see_and_hear_content_including_separating_foreground_from_background) - [Understanding Success Criterion 1.4.4 | W3C Understanding WCAG 2.0](https://www.w3.org/TR/UNDERSTANDING-WCAG20/visual-audio-contrast-scale.html) ## Examples diff --git a/files/en-us/web/css/caption-side/index.md b/files/en-us/web/css/caption-side/index.md index 372dda90062bcad..96f0c6ece2013f9 100644 --- a/files/en-us/web/css/caption-side/index.md +++ b/files/en-us/web/css/caption-side/index.md @@ -9,7 +9,71 @@ browser-compat: css.properties.caption-side The **`caption-side`** [CSS](/en-US/docs/Web/CSS) property puts the content of a table's {{HTMLElement("caption")}} on the specified side. The values are relative to the {{cssxref("writing-mode")}} of the table. -{{EmbedInteractiveExample("pages/css/caption-side.html")}} +{{InteractiveExample("CSS Demo: caption-side")}} + +```css interactive-example-choice +caption-side: top; +``` + +```css interactive-example-choice +caption-side: bottom; +``` + +```html interactive-example +<section class="default-example" id="default-example"> + <table class="transition-all" id="example-element"> + <caption> + Famous animals + </caption> + <tr> + <th>Name</th> + <th>Location</th> + </tr> + <tr> + <td>Giraffe</td> + <td>Africa</td> + </tr> + <tr> + <td>Penguin</td> + <td>Antarctica</td> + </tr> + <tr> + <td>Sloth</td> + <td>South America</td> + </tr> + <tr> + <td>Tiger</td> + <td>Asia</td> + </tr> + </table> +</section> +``` + +```css interactive-example +table { + font-size: 1.2rem; + text-align: left; + color: #000; +} + +th, +td { + padding: 0.2rem 1rem; +} + +caption { + background: #fc3; + padding: 0.5rem 1rem; +} + +tr { + background: #eee; +} + +tr:nth-child(even) { + background: #ccc; +} +``` ## Syntax diff --git a/files/en-us/web/css/caret-color/index.md b/files/en-us/web/css/caret-color/index.md index f20543a59d9b1bc..a708b251e5fadf1 100644 --- a/files/en-us/web/css/caret-color/index.md +++ b/files/en-us/web/css/caret-color/index.md @@ -7,9 +7,36 @@ browser-compat: css.properties.caret-color {{CSSRef}} -The **`caret-color`** [CSS](/en-US/docs/Web/CSS) property sets the color of the **insertion caret**, the visible marker where the next character typed will be inserted. This is sometimes referred to as the **text input cursor**. The caret appears in elements such as {{HTMLElement("input")}} or those with the [`contenteditable`](/en-US/docs/Web/HTML/Global_attributes/contenteditable) attribute. The caret is typically a thin vertical line that flashes to help make it more noticeable. By default, it is black, but its color can be altered with this property. +The **`caret-color`** [CSS](/en-US/docs/Web/CSS) property sets the color of the **insertion caret**, the visible marker where the next character typed will be inserted. This is sometimes referred to as the **text input cursor**. The caret appears in elements such as {{HTMLElement("input")}} or those with the [`contenteditable`](/en-US/docs/Web/HTML/Reference/Global_attributes/contenteditable) attribute. The caret is typically a thin vertical line that flashes to help make it more noticeable. By default, it is black, but its color can be altered with this property. -{{EmbedInteractiveExample("pages/css/caret-color.html")}} +{{InteractiveExample("CSS Demo: caret-color")}} + +```css interactive-example-choice +caret-color: red; +``` + +```css interactive-example-choice +caret-color: auto; +``` + +```css interactive-example-choice +caret-color: transparent; +``` + +```html interactive-example +<section class="default-example container" id="default-example"> + <div> + <p>Enter text in the field to see the caret:</p> + <p><input id="example-element" type="text" /></p> + </div> +</section> +``` + +```css interactive-example +#example-element { + font-size: 1.2rem; +} +``` Note that the insertion caret is only one type of caret. For example, many browsers have a "navigation caret," which acts similarly to an insertion caret but can be moved around in non-editable text. On the other hand, the mouse cursor image shown when hovering over text where the {{cssxref("cursor")}} property is `auto`, or when hovering over an element where the `cursor` property is `text` or `vertical-text`, though it sometimes looks like a caret, is not a caret (it's a cursor). @@ -102,6 +129,6 @@ p.custom { ## See also - The {{HTMLElement("input")}} element -- The HTML [`contenteditable`](/en-US/docs/Web/HTML/Global_attributes/contenteditable) attribute, which can be used to make any element's text editable +- The HTML [`contenteditable`](/en-US/docs/Web/HTML/Reference/Global_attributes/contenteditable) attribute, which can be used to make any element's text editable - The {{cssxref("&lt;color&gt;")}} data type - Other color-related properties: {{cssxref("color")}}, {{cssxref("background-color")}}, {{cssxref("border-color")}}, {{cssxref("outline-color")}}, {{cssxref("text-decoration-color")}}, {{cssxref("text-emphasis-color")}}, {{cssxref("text-shadow")}}, and {{cssxref("column-rule-color")}} diff --git a/files/en-us/web/css/clamp/index.md b/files/en-us/web/css/clamp/index.md index eb63fcfd73f1b84..c97a1868da5842f 100644 --- a/files/en-us/web/css/clamp/index.md +++ b/files/en-us/web/css/clamp/index.md @@ -9,7 +9,28 @@ browser-compat: css.types.clamp The **`clamp()`** [CSS](/en-US/docs/Web/CSS) [function](/en-US/docs/Web/CSS/CSS_Values_and_Units/CSS_Value_Functions) clamps a middle value within a range of values between a defined minimum bound and a maximum bound. The function takes three parameters: a minimum value, a preferred value, and a maximum allowed value. -{{EmbedInteractiveExample("pages/css/function-clamp.html")}} +{{InteractiveExample("CSS Demo: clamp()")}} + +```css interactive-example-choice +font-size: clamp(1rem, 2.5vw, 2rem); +``` + +```css interactive-example-choice +font-size: clamp(1.5rem, 2.5vw, 4rem); +``` + +```css interactive-example-choice +font-size: clamp(1rem, 10vw, 2rem); +``` + +```html interactive-example +<section class="default-example" id="default-example"> + <div class="transition-all" id="example-element"> + The font-size of this text varies depending on the base font of the page, + and the size of the viewport. + </div> +</section> +``` Note that using `clamp()` for font sizes, as in these examples, allows you to set a font-size that grows with the size of the viewport, but doesn't go below a minimum font-size or above a maximum font-size. It has the same effect as the code in [Fluid Typography](https://css-tricks.com/snippets/css/fluid-typography/) but in one line, and without the use of media queries. @@ -48,13 +69,13 @@ You can use different units for each value in your expressions and different uni Keep the following aspects in mind while working with the function: - Math expressions involving percentages for widths and heights on table columns, table column groups, table rows, table row groups, and table cells in both auto and fixed layout tables _may_ be treated as if `auto` had been specified. -- It is permitted to nest `max()` and `min()` functions as expression values, in which case the inner ones are treated as simple parentheses. The expressions are full math expressions, so you can use direct addition, subtraction, multiplication and division without using the calc() function itself. +- It is permitted to nest `max()` and `min()` functions as expression values, in which case the inner ones are treated as basic parentheses. The expressions are full math expressions, so you can use direct addition, subtraction, multiplication and division without using the calc() function itself. - The expression can be values combining the addition ( `+` ), subtraction ( `-` ), multiplication ( `*` ) and division ( `/` ) operators, using standard operator precedence rules. Make sure to put a space on each side of the `+` and `-` operands. The operands in the expression may be any {{CSSxRef("&lt;length&gt;")}} syntax value. You can use different units for each value in your expression. You may also use parentheses to establish computation order when needed. - Oftentimes you will want to use {{CSSxRef("min", "min()")}} and {{CSSxRef("max", "max()")}} within a `clamp()` function. ### Return value -`clamp(MIN, VAL, MAX)` is resolved as `{{CSSxRef("max", "max")}}(MIN, {{CSSxRef("min", "min")}}(VAL, MAX))`. +`clamp(MIN, VAL, MAX)` is resolved as `max(MIN, min(VAL, MAX))`. Based on the provided parameters, the function returns {{CSSxRef("&lt;length&gt;")}}, {{CSSxRef("&lt;frequency&gt;")}}, {{CSSxRef("&lt;angle&gt;")}}, {{CSSxRef("&lt;time&gt;")}}, {{CSSxRef("&lt;percentage&gt;")}}, {{CSSxRef("&lt;number&gt;")}}, or {{CSSxRef("&lt;integer&gt;")}}. @@ -78,11 +99,11 @@ In all three cases, the page uses a combination of a viewport-relative units ([` The example is at <https://mdn.github.io/css-examples/min-max-clamp/>. Open it in a new window and try adjusting the window width. -The **line length** (controlled by the [`width`](/en-US/docs/Web/CSS/width) of the [`<body>`](/en-US/docs/Web/HTML/Element/body) element) will increase as the window width increases, but only up to a certain point (`1000px`), and beyond that point, it won't increase anymore. We're using `min()` to set a **maximum line length**: it can go under `1000px`, but won't go over. This is helpful because long lines are harder to read, so we often want to limit how long a line can be. To achieve this we use `min(1000px, calc(70% + 100px))`: when the result of the percentage-based calculation goes above `1000px`, we switch to the fixed `1000px` value. +The **line length** (controlled by the [`width`](/en-US/docs/Web/CSS/width) of the [`<body>`](/en-US/docs/Web/HTML/Reference/Elements/body) element) will increase as the window width increases, but only up to a certain point (`1000px`), and beyond that point, it won't increase anymore. We're using `min()` to set a **maximum line length**: it can go under `1000px`, but won't go over. This is helpful because long lines are harder to read, so we often want to limit how long a line can be. To achieve this we use `min(1000px, calc(70% + 100px))`: when the result of the percentage-based calculation goes above `1000px`, we switch to the fixed `1000px` value. -The **size of the paragraph text**, controlled by the [`font-size`](/en-US/docs/Web/CSS/font-size) of the [`<p>`](/en-US/docs/Web/HTML/Element/p) element, decreases as the window gets narrower, but only up to a certain point, and beyond that point (the point where `1.2vw` is less than `1.2rem`) it doesn't get any smaller: it stays at `1.2rem`. We're using `max()` to set a **minimum font size**: the font can grow above `1.2rem` but will never go below it. This is helpful because really small text is hard to read. To achieve this we use `max(1.2rem, 1.2vw)`. This means that the `font-size` will be set at `1.2rem`, unless the computed value of `1.2vw` is greater than that of `1.2rem`, in which case it will be set to `1.2vw` instead. +The **size of the paragraph text**, controlled by the [`font-size`](/en-US/docs/Web/CSS/font-size) of the [`<p>`](/en-US/docs/Web/HTML/Reference/Elements/p) element, decreases as the window gets narrower, but only up to a certain point, and beyond that point (the point where `1.2vw` is less than `1.2rem`) it doesn't get any smaller: it stays at `1.2rem`. We're using `max()` to set a **minimum font size**: the font can grow above `1.2rem` but will never go below it. This is helpful because really small text is hard to read. To achieve this we use `max(1.2rem, 1.2vw)`. This means that the `font-size` will be set at `1.2rem`, unless the computed value of `1.2vw` is greater than that of `1.2rem`, in which case it will be set to `1.2vw` instead. -The **size of the heading text**, controlled by the [`font-size`](/en-US/docs/Web/CSS/font-size) of the [`<h1>`](/en-US/docs/Web/HTML/Element/Heading_Elements) element, has a viewport-relative value with both a maximum and a minimum threshold. To achieve this we use `clamp(1.8rem, 2.5vw, 2.8rem)`. The viewport-relative value is `2.5vw` but it is clamped between `1.8rem` and `2.8rem`, so: +The **size of the heading text**, controlled by the [`font-size`](/en-US/docs/Web/CSS/font-size) of the [`<h1>`](/en-US/docs/Web/HTML/Reference/Elements/Heading_Elements) element, has a viewport-relative value with both a maximum and a minimum threshold. To achieve this we use `clamp(1.8rem, 2.5vw, 2.8rem)`. The viewport-relative value is `2.5vw` but it is clamped between `1.8rem` and `2.8rem`, so: - if the calculated value of `2.5vw` is less than `1.8rem`, then `1.8rem` will be used - if the calculated value of `2.5vw` is greater than `2.8rem`, then `2.8rem` will be used. @@ -92,7 +113,7 @@ This prevents the heading text from getting too small in a very narrow window, o #### HTML ```html -<h1>Simple responsive test</h1> +<h1>Basic responsive test</h1> <p> Lorem ipsum dolor sit amet, consectetur adipiscing elit. In orci orci, eleifend id risus nec, mattis rutrum velit. Suspendisse fringilla egestas erat diff --git a/files/en-us/web/css/class_selectors/index.md b/files/en-us/web/css/class_selectors/index.md index 0d6e5132c022854..d1b2269048134ea 100644 --- a/files/en-us/web/css/class_selectors/index.md +++ b/files/en-us/web/css/class_selectors/index.md @@ -7,7 +7,7 @@ browser-compat: css.selectors.class {{CSSRef}} -The [CSS](/en-US/docs/Web/CSS) **class selector** matches elements based on the contents of their [`class`](/en-US/docs/Web/HTML/Global_attributes/class) attribute. +The [CSS](/en-US/docs/Web/CSS) **class selector** matches elements based on the contents of their [`class`](/en-US/docs/Web/HTML/Reference/Global_attributes/class) attribute. ```css /* All elements with class="spacious" */ @@ -30,13 +30,17 @@ li.spacious.elegant { ## Syntax ```css -.class_name { style properties } +.class_name { + /* … */ +} ``` Note that this is equivalent to the following [attribute selector](/en-US/docs/Web/CSS/Attribute_selectors): ```css -[class~=class_name] { style properties } +[class~="class_name"] { + /* … */ +} ``` The `class_name` value must be a valid [CSS identifier](/en-US/docs/Web/CSS/ident). HTML `class` attributes which are not valid CSS identifiers must be [escaped](/en-US/docs/Web/CSS/ident#escaping_characters) before they can be used in class selectors. diff --git a/files/en-us/web/css/clear/index.md b/files/en-us/web/css/clear/index.md index 5894e65209f6962..85bcd228dc8dd33 100644 --- a/files/en-us/web/css/clear/index.md +++ b/files/en-us/web/css/clear/index.md @@ -9,7 +9,62 @@ browser-compat: css.properties.clear The **`clear`** [CSS](/en-US/docs/Web/CSS) property sets whether an element must be moved below (cleared) [floating](/en-US/docs/Web/CSS/float) elements that precede it. The `clear` property applies to floating and non-floating elements. -{{EmbedInteractiveExample("pages/css/clear.html")}} +{{InteractiveExample("CSS Demo: clear")}} + +```css interactive-example-choice +clear: none; +``` + +```css interactive-example-choice +clear: left; +``` + +```css interactive-example-choice +clear: right; +``` + +```css interactive-example-choice +clear: both; +``` + +```html interactive-example +<section class="default-example" id="default-example"> + <div class="example-container"> + <div class="floated-left">Left</div> + <div class="floated-right">Right</div> + <div class="transition-all" id="example-element"> + As much mud in the streets as if the waters had but newly retired from the + face of the earth, and it would not be wonderful to meet a Megalosaurus, + forty feet long or so, waddling like an elephantine lizard up Holborn + Hill. + </div> + </div> +</section> +``` + +```css interactive-example +.example-container { + border: 1px solid #c5c5c5; + padding: 0.75em; + text-align: left; + line-height: normal; +} + +.floated-left { + border: solid 10px #ffc129; + background-color: rgba(81, 81, 81, 0.6); + padding: 1em; + float: left; +} + +.floated-right { + border: solid 10px #ffc129; + background-color: rgba(81, 81, 81, 0.6); + padding: 1em; + float: right; + height: 150px; +} +``` When applied to non-floating blocks, it moves the [border edge](/en-US/docs/Web/CSS/CSS_box_model/Introduction_to_the_CSS_box_model#border_area) of the element down until it is below the [margin edge](/en-US/docs/Web/CSS/CSS_box_model/Introduction_to_the_CSS_box_model#margin_area) of all relevant floats. The non-floated block's top margin collapses. diff --git a/files/en-us/web/css/clip-path/index.md b/files/en-us/web/css/clip-path/index.md index a143726f4692164..fa49ad061d80e8f 100644 --- a/files/en-us/web/css/clip-path/index.md +++ b/files/en-us/web/css/clip-path/index.md @@ -9,7 +9,68 @@ browser-compat: css.properties.clip-path The **`clip-path`** [CSS](/en-US/docs/Web/CSS) property creates a clipping region that sets what part of an element should be shown. Parts that are inside the region are shown, while those outside are hidden. -{{EmbedInteractiveExample("pages/css/clip-path.html")}} +{{InteractiveExample("CSS Demo: clip-path")}} + +```css interactive-example-choice +clip-path: circle(40%); +``` + +```css interactive-example-choice +clip-path: ellipse(130px 140px at 10% 20%); +``` + +```css interactive-example-choice +clip-path: polygon(50% 0, 100% 50%, 50% 100%, 0 50%); +``` + +```css interactive-example-choice +clip-path: path("M 0 200 L 0,75 A 5,5 0,0,1 150,75 L 200 200 z"); +``` + +```css interactive-example-choice +clip-path: rect(5px 145px 160px 5px round 20%); +``` + +```css interactive-example-choice +clip-path: xywh(0 5px 100% 75% round 15% 0); +``` + +```html interactive-example +<section class="default-example" id="default-example"> + <div class="example-container"> + <img + class="transition-all" + id="example-element" + src="/shared-assets/images/examples/balloon-small.jpg" + width="150" /> + We had agreed, my companion and I, that I should call for him at his house, + after dinner, not later than eleven o’clock. This athletic young Frenchman + belongs to a small set of Parisian sportsmen, who have taken up “ballooning” + as a pastime. After having exhausted all the sensations that are to be found + in ordinary sports, even those of “automobiling” at a breakneck speed, the + members of the “Aéro Club” now seek in the air, where they indulge in all + kinds of daring feats, the nerve-racking excitement that they have ceased to + find on earth. + </div> +</section> +``` + +```css interactive-example +section { + align-items: flex-start; +} + +.example-container { + text-align: left; + padding: 20px; +} + +#example-element { + float: left; + width: 150px; + margin: 20px; +} +``` ## Syntax @@ -38,6 +99,7 @@ clip-path: path( "M0.5,1 C0.5,1,0,0.7,0,0.3 A0.25,0.25,1,1,1,0.5,0.3 A0.25,0.25,1,1,1,1,0.3 C1,0.7,0.5,1,0.5,1 Z" ); clip-path: rect(5px 5px 160px 145px round 20%); +clip-path: shape(from 0% 0%, line to 100% 0%, line to 50% 100%, close); clip-path: xywh(0 5px 100% 75% round 15% 0); /* Box and shape values combined */ @@ -101,7 +163,7 @@ The `clip-path` property is specified as one or a combination of the values list - : No clipping path is created. > [!NOTE] -> A computed value other than **`none`** results in the creation of a new [stacking context](/en-US/docs/Web/CSS/CSS_positioned_layout/Understanding_z-index/Stacking_context) the same way that CSS {{cssxref("opacity")}} does for values other than `1`. +> A computed value other than **`none`** results in the creation of a new [stacking context](/en-US/docs/Web/CSS/CSS_positioned_layout/Stacking_context) the same way that CSS {{cssxref("opacity")}} does for values other than `1`. ## Formal definition @@ -113,481 +175,176 @@ The `clip-path` property is specified as one or a combination of the values list ## Examples -### Comparison of HTML and SVG +### Shapes and geometry boxes -```html hidden -<svg class="defs"> - <defs> - <clipPath id="myPath" clipPathUnits="objectBoundingBox"> - <path - d="M0.5,1 C0.5,1,0,0.7,0,0.3 A0.25,0.25,1,1,1,0.5,0.3 A0.25,0.25,1,1,1,1,0.3 C1,0.7,0.5,1,0.5,1 Z" /> - </clipPath> - </defs> -</svg> +In this example, two triangles are created by defining a `polygon()` as the clip path on {{htmlelement("div")}} elements. Each one has a solid colored background and a thick {{cssxref("border")}}. The second `<div>` element has its reference box set to `content-box`: -<div class="grid"> - <div class="col"> - <div class="note">clip-path: none</div> - <div class="row"> - <div class="cell"> - <span>HTML</span> - <div class="container"> - <p class="none">I LOVE<br /><em>clipping</em></p> - </div> - </div> - <div class="cell"> - <span>SVG</span> - <div class="container view-box"> - <svg viewBox="0 0 192 192"> - <g class="none"> - <rect x="24" y="24" width="144" height="144" /> - <text x="96" y="91">I LOVE</text> - <text x="96" y="109" class="em">clipping</text> - </g> - </svg> - </div> - </div> - </div> - - <div class="note"> - clip-path: url(#myPath)<br /><br /> - Assuming the following clipPath definition: - <pre> -&lt;svg&gt; - &lt;clipPath id="myPath" clipPathUnits="objectBoundingBox"&gt; - &lt;path d="M0.5,1 - C 0.5,1,0,0.7,0,0.3 - A 0.25,0.25,1,1,1,0.5,0.3 - A 0.25,0.25,1,1,1,1,0.3 - C 1,0.7,0.5,1,0.5,1 Z" /&gt; - &lt;/clipPath&gt; -&lt;/svg&gt;</pre - > - </div> - <div class="row"> - <div class="cell"> - <span>HTML</span> - <div class="container"> - <p class="svg">I LOVE<br /><em>clipping</em></p> - </div> - </div> - <div class="cell"> - <span>SVG</span> - <div class="container view-box"> - <svg viewBox="0 0 192 192"> - <g class="svg"> - <rect x="24" y="24" width="144" height="144" /> - <text x="96" y="91">I LOVE</text> - <text x="96" y="109" class="em">clipping</text> - </g> - </svg> - </div> - </div> - </div> - - <div class="note"> - clip-path: path('M15,45 A30,30,0,0,1,75,45 A30,30,0,0,1,135,45 - Q135,90,75,130 Q15,90,15,45 Z') - </div> - <div class="row"> - <div class="cell"> - <span>HTML</span> - <div class="container"> - <p class="svg2">I LOVE<br /><em>clipping</em></p> - </div> - </div> - <div class="cell"> - <span>SVG</span> - <div class="container view-box"> - <svg viewBox="0 0 192 192"> - <g class="svg2"> - <rect x="24" y="24" width="144" height="144" /> - <text x="96" y="91">I LOVE</text> - <text x="96" y="109" class="em">clipping</text> - </g> - </svg> - </div> - </div> - </div> - - <div class="note">clip-path: circle(25%)</div> - <div class="row"> - <div class="cell"> - <span>HTML</span> - <div class="container"> - <p class="shape1">I LOVE<br /><em>clipping</em></p> - </div> - </div> - <div class="cell"> - <span>SVG</span> - <div class="container view-box"> - <svg viewBox="0 0 192 192"> - <g class="shape1"> - <rect x="24" y="24" width="144" height="144" /> - <text x="96" y="91">I LOVE</text> - <text x="96" y="109" class="em">clipping</text> - </g> - </svg> - </div> - </div> - </div> - - <div class="note">clip-path: circle(25% at 25% 25%)</div> - <div class="row"> - <div class="cell"> - <span>HTML</span> - <div class="container"> - <p class="shape2">I LOVE<br /><em>clipping</em></p> - </div> - </div> - <div class="cell"> - <span>SVG</span> - <div class="container view-box"> - <svg viewBox="0 0 192 192"> - <g class="shape2"> - <rect x="24" y="24" width="144" height="144" /> - <text x="96" y="91">I LOVE</text> - <text x="96" y="109" class="em">clipping</text> - </g> - </svg> - </div> - </div> - </div> - - <div class="note">clip-path: fill-box circle(25% at 25% 25%)</div> - <div class="row"> - <div class="cell"> - <span>HTML</span> - <div class="container"> - <p class="shape3">I LOVE<br /><em>clipping</em></p> - </div> - </div> - <div class="cell"> - <span>SVG</span> - <div class="container view-box"> - <svg viewBox="0 0 192 192"> - <g class="shape3"> - <rect x="24" y="24" width="144" height="144" /> - <text x="96" y="91">I LOVE</text> - <text x="96" y="109" class="em">clipping</text> - </g> - </svg> - </div> - </div> - </div> - - <div class="note">clip-path: stroke-box circle(25% at 25% 25%)</div> - <div class="row"> - <div class="cell"> - <span>HTML</span> - <div class="container"> - <p class="shape4">I LOVE<br /><em>clipping</em></p> - </div> - </div> - <div class="cell"> - <span>SVG</span> - <div class="container view-box"> - <svg viewBox="0 0 192 192"> - <g class="shape4"> - <rect x="24" y="24" width="144" height="144" /> - <text x="96" y="91">I LOVE</text> - <text x="96" y="109" class="em">clipping</text> - </g> - </svg> - </div> - </div> - </div> - - <div class="note">clip-path: view-box circle(25% at 25% 25%)</div> - <div class="row"> - <div class="cell"> - <span>HTML</span> - <div class="container"> - <p class="shape5">I LOVE<br /><em>clipping</em></p> - </div> - </div> - <div class="cell"> - <span>SVG</span> - <div class="container view-box"> - <svg viewBox="0 0 192 192"> - <g class="shape5"> - <rect x="24" y="24" width="144" height="144" /> - <text x="96" y="91">I LOVE</text> - <text x="96" y="109" class="em">clipping</text> - </g> - </svg> - </div> - </div> - </div> - - <div class="note">clip-path: margin-box circle(25% at 25% 25%)</div> - <div class="row"> - <div class="cell"> - <span>HTML</span> - <div class="container"> - <p class="shape6">I LOVE<br /><em>clipping</em></p> - </div> - </div> - <div class="cell"> - <span>SVG</span> - <div class="container view-box"> - <svg viewBox="0 0 192 192"> - <g class="shape6"> - <rect x="24" y="24" width="144" height="144" /> - <text x="96" y="91">I LOVE</text> - <text x="96" y="109" class="em">clipping</text> - </g> - </svg> - </div> - </div> - </div> - - <div class="note">clip-path: border-box circle(25% at 25% 25%)</div> - <div class="row"> - <div class="cell"> - <span>HTML</span> - <div class="container"> - <p class="shape7">I LOVE<br /><em>clipping</em></p> - </div> - </div> - <div class="cell"> - <span>SVG</span> - <div class="container view-box"> - <svg viewBox="0 0 192 192"> - <g class="shape7"> - <rect x="24" y="24" width="144" height="144" /> - <text x="96" y="91">I LOVE</text> - <text x="96" y="109" class="em">clipping</text> - </g> - </svg> - </div> - </div> - </div> - - <div class="note">clip-path: padding-box circle(25% at 25% 25%)</div> - <div class="row"> - <div class="cell"> - <span>HTML</span> - <div class="container"> - <p class="shape8">I LOVE<br /><em>clipping</em></p> - </div> - </div> - <div class="cell"> - <span>SVG</span> - <div class="container view-box"> - <svg viewBox="0 0 192 192"> - <g class="shape8"> - <rect x="24" y="24" width="144" height="144" /> - <text x="96" y="91">I LOVE</text> - <text x="96" y="109" class="em">clipping</text> - </g> - </svg> - </div> - </div> - </div> - - <div class="note">clip-path: content-box circle(25% at 25% 25%)</div> - <div class="row"> - <div class="cell"> - <span>HTML</span> - <div class="container"> - <p class="shape9">I LOVE<br /><em>clipping</em></p> - </div> - </div> - <div class="cell"> - <span>SVG</span> - <div class="container view-box"> - <svg viewBox="0 0 192 192"> - <g class="shape9"> - <rect x="24" y="24" width="144" height="144" /> - <text x="96" y="91">I LOVE</text> - <text x="96" y="109" class="em">clipping</text> - </g> - </svg> - </div> - </div> - </div> - </div> -</div> +#### HTML + +```html live-sample___shapes1 live-sample___shapes2 live-sample___shapes3 +<div></div> +<div></div> ``` -```css -html, -body { - height: 100%; - box-sizing: border-box; - background: #eee; -} +#### CSS -.grid { - width: 100%; - height: 100%; +```css hidden live-sample___shapes1 live-sample___shapes2 live-sample___shapes3 +body { display: flex; - font: 1em monospace; + gap: 20px; + flex-flow: row wrap; } +``` -.row { - display: flex; - flex: 1 auto; - flex-direction: row; - flex-wrap: wrap; -} +```css live-sample___shapes1 live-sample___shapes2 live-sample___shapes3 +div { + height: 200px; + width: 200px; + box-sizing: border-box; + background-color: rebeccapurple; + border: 20px solid magenta; -.col { - flex: 1 auto; + clip-path: polygon(50% 0, 100% 100%, 0 100%); } -.cell { - margin: 0.5em; - padding: 0.5em; - background-color: #fff; - overflow: hidden; - text-align: center; - flex: 1; +div:last-of-type { + clip-path: content-box polygon(50% 0, 100% 100%, 0 100%); } +``` -.note { - background: #fff3d4; - padding: 1em; - margin: 0.5em 0.5em 0; - font: 0.8em sans-serif; - text-align: left; - white-space: nowrap; -} +#### Results -.note + .row .cell { - margin-top: 0; -} +{{EmbedLiveSample("shapes1", "", "230")}} -.container { - display: inline-block; - border: 1px dotted grey; - position: relative; -} +For the first triangle, we didn't specify a reference box; it therefore defaults to `border-box`, with the 0% and 100% positions located on the outside edge of the border. In the second example, we set the `<geometry-box>` to `content-box`, meaning the reference box for the basic shape is the outer edge of the content area, which is inside the padding box. Because our example has no `padding`, this is the inner edge of the border. -.container::before { - content: "margin"; - position: absolute; - top: 2px; - left: 2px; - font: italic 0.6em sans-serif; -} +### `shape()` versus `path()` functions -.view-box { - box-shadow: - 1rem 1rem 0 #efefef inset, - -1rem -1rem 0 #efefef inset; -} +Expanding on the previous example, we create the same triangle with different `<basic-shape>` values, demonstrating how the {{cssxref("basic-shape/shape", "shape()")}} and {{cssxref("basic-shape/path", "path()")}} functions can also be used to create clipping paths, with `shape()` being a more flexible solution. -.container.view-box::after { - content: "view-box"; - position: absolute; - left: 1.1rem; - top: 1.1rem; - font: italic 0.6em sans-serif; -} +We use `path()` to define the first element's clipping path, and `shape()` for the second, both using the default `border-box` as their reference box: -.cell span { - display: block; - margin-bottom: 0.5em; +```css live-sample___shapes2 live-sample___shapes3 +div { + clip-path: path("M100 0 L200 200 L0 200 Z"); } -p { - font-family: sans-serif; - background: #000; - color: pink; - margin: 2em; - padding: 3em 1em; - border: 1em solid pink; - width: 6em; +div:last-of-type { + clip-path: shape(from 50% 0, line to 100% 100%, line to 0 100%, close); } +``` -.none { - clip-path: none; -} -.svg { - clip-path: url(#myPath); -} -.svg2 { - clip-path: path( - "M15,45 A30,30,0,0,1,75,45 A30,30,0,0,1,135,45 Q135,90,75,130 Q15,90,15,45 Z" - ); -} -.shape1 { - clip-path: circle(25%); -} -.shape2 { - clip-path: circle(25% at 25% 25%); -} -.shape3 { - clip-path: fill-box circle(25% at 25% 25%); -} -.shape4 { - clip-path: stroke-box circle(25% at 25% 25%); -} -.shape5 { - clip-path: view-box circle(25% at 25% 25%); -} -.shape6 { - clip-path: margin-box circle(25% at 25% 25%); -} -.shape7 { - clip-path: border-box circle(25% at 25% 25%); -} -.shape8 { - clip-path: padding-box circle(25% at 25% 25%); -} -.shape9 { - clip-path: content-box circle(25% at 25% 25%); -} +As a result, the path defined with the shape() function grows with the element, whereas the path() version does not: -.defs { - width: 0; - height: 0; - margin: 0; -} +{{EmbedLiveSample("shapes2", "", "230")}} -pre { - margin-bottom: 0; -} +Because the `shape()` function allows using {{cssxref("percentage")}} values (and [custom properties](/en-US/docs/Web/CSS/--*) too), it is more robust. -svg { - margin: 1em; - font-family: sans-serif; - width: 192px; - height: 192px; +We'll demonstrate this by increasing the size of the underlying element: + +```css live-sample___shapes3 +div { + width: 250px; + height: 250px; } +``` + +{{EmbedLiveSample("shapes3", "", "280")}} + +The visibility, or at least partial visibility, of the four border sides in the clip path example defined by the `shape()` function is due to the percentage values allowing the path to grow with the element. In the `path()` version, the element grew, but not the shape. As a result, the top and left borders are partially visible while the right and bottom borders are clipped out. + +### SVG as clip source + +In this example, we define SVG {{svgElement("clipPath")}} elements to use as a `clip-path` source. + +#### HTML + +We include two {{htmlElement("div")}} elements and an `<svg>` element containing two `<clipPath>` elements. One `<clipPath>` contains four {{svgElement("rect")}} elements that together define window panes, leaving a cross of blank space in the middle, and the other contains two crossing `<rect>` elements. -svg rect { - stroke: pink; - stroke-width: 16px; +```html +<svg height="0" width="0"> + <defs> + <clipPath id="window"> + <rect y="0" x="0" width="80" height="80" /> + <rect y="0" x="120" width="80" height="80" /> + <rect y="120" x="0" width="80" height="80" /> + <rect y="120" x="120" width="80" height="80" /> + </clipPath> + <clipPath id="cross"> + <rect y="0" x="80" width="40" height="200" /> + <rect y="80" x="0" width="200" height="40" /> + </clipPath> + </defs> +</svg> + +<div class="window">Window</div> +<div class="cross">Cross</div> +``` + +#### CSS + +We use [flexbox](/en-US/docs/Web/CSS/CSS_flexible_box_layout) to allow our elements to sit side-by-side with a gap between them, if there is space available. We define a {{cssxref("gradient/conic-gradient", "conic-gradient()")}} background image on both `<div>` elements, providing an interesting visual to clip, along with a {{cssxref("border")}}. + +```css +body { + display: flex; + gap: 20px; + flex-flow: row wrap; + font: 2em sans-serif; +} + +div { + width: 200px; + height: 200px; + background-image: conic-gradient( + at center, + rebeccapurple, + green, + lightblue, + rebeccapurple + ); + + border: 5px solid; + box-sizing: border-box; } +``` -svg text { - fill: pink; - text-anchor: middle; +We then set the `id` of the `<clipPath>` as the `<clip-source>`. We center the text in the `cross` example vertically using {{cssxref("align-content")}}, as otherwise the text would be clipped, as is happening in the `window` example. + +```css +.window { + clip-path: url(#window); } -svg text.em { - font-style: italic; +.cross { + clip-path: url(#cross); + align-content: center; } ``` -{{EmbedLiveSample("Comparison_of_HTML_and_SVG", "100%", "800px")}} +#### Results + +{{EmbedLiveSample("SVG as clip source", "", "230")}} + +The elements, including their border and text, are clipped, with only the parts overlapping the `<clipPath>` elements being drawn to the page. + +### The various value types -### Complete example +This example demonstrates the various values of the `clip-path` property clipping an HTML {{htmlelement("img")}}. #### HTML +The HTML includes an `<img>` that will be clipped, a star-shaped `<clipPath>`, and a {{htmlelement("select")}} element to choose a `clip-path` property value from. + ```html -<img id="clipped" src="mdn.svg" alt="MDN logo" /> +<img + id="clipped" + src="https://mdn.github.io/shared-assets/images/examples/progress-pride-flag.jpg" + alt="Pride flag" /> <svg height="0" width="0"> <defs> - <clipPath id="cross"> - <rect y="110" x="137" width="90" height="90" /> - <rect x="0" y="110" width="90" height="90" /> - <rect x="137" y="0" width="90" height="90" /> - <rect x="0" y="0" width="90" height="90" /> + <clipPath id="star"> + <path d="M100,0 42,180 196,70 4,70 158,180z" /> </clipPath> </defs> </svg> @@ -595,9 +352,9 @@ svg text.em { <select id="clipPath"> <option value="none">none</option> <option value="circle(100px at 110px 100px)">circle</option> - <option value="url(#cross)" selected>cross</option> + <option value="url(#star)" selected>star</option> <option value="inset(20px round 20px)">inset</option> - <option value="rect(10px 10px 180px 220px round 20px)">rect</option> + <option value="rect(20px 150px 200px 20px round 10%)">rect</option> <option value="xywh(0 20% 90% 67% round 0 0 5% 5px)">xywh</option> <option value="path('M 0 200 L 0,110 A 110,90 0,0,1 240,100 L 200 340 z')"> path @@ -605,25 +362,50 @@ svg text.em { </select> ``` +```html hidden +<pre id="log"></pre> +``` + #### CSS +The initial rendering includes the star as the `clip-path` source. + ```css #clipped { margin-bottom: 20px; - clip-path: url(#cross); + clip-path: url(#star); } ``` -```js hidden +#### JavaScript + +When you select a new option from the `<select>` menu, an event handler updates the value of the `clip-path` set on the `<img>`. + +```js const clipPathSelect = document.getElementById("clipPath"); clipPathSelect.addEventListener("change", (evt) => { - document.getElementById("clipped").style.clipPath = evt.target.value; + const path = evt.target.value; + document.getElementById("clipped").style.clipPath = path; + log(`clip-path: ${path};`); }); ``` +```js hidden +function log(text) { + const logElement = document.querySelector("#log"); + logElement.innerText = `${text}`; + logElement.scrollTop = logElement.scrollHeight; +} +``` + #### Result -{{EmbedLiveSample("Complete_example", 230, 250)}} +{{EmbedLiveSample("Complete_example", 230, 300)}} + +Select different options to change the `clip-path` value. + +> [!NOTE] +> While it is possible to define a path of text, if you want to clip a background image to text rather than a shape, see the {{cssxref("background-clip")}} property. ## Specifications @@ -638,6 +420,8 @@ clipPathSelect.addEventListener("change", (evt) => { - {{CSSxRef("clip-rule")}} - {{CSSxRef("mask")}} - {{CSSxRef("filter")}} +- {{cssxref("background-clip")}} +- [Introduction to CSS clipping](/en-US/docs/Web/CSS/CSS_masking/Clipping) +- [CSS masking](/en-US/docs/Web/CSS/CSS_masking) module - SVG {{SVGAttr("clip-path")}} attribute -- [Shapes in clipping and masking – and how to use them](https://hacks.mozilla.org/2017/06/css-shapes-clipping-and-masking/) -- [Applying SVG effects to HTML content](/en-US/docs/Web/SVG/Applying_SVG_effects_to_HTML_content) +- [Applying SVG effects to HTML content](/en-US/docs/Web/SVG/Guides/Applying_SVG_effects_to_HTML_content) diff --git a/files/en-us/web/css/clip-rule/index.md b/files/en-us/web/css/clip-rule/index.md index 60ff3236f410c6e..3d6697635a04d53 100644 --- a/files/en-us/web/css/clip-rule/index.md +++ b/files/en-us/web/css/clip-rule/index.md @@ -7,7 +7,9 @@ browser-compat: css.properties.clip-rule {{CSSRef}} -The **`clip-rule`** [CSS](/en-US/docs/Web/CSS) property defines how to determine which pixels in a mask's box are inside the clipping shape defined by a [clip path](/en-US/docs/Web/CSS/clip-path), and which are outside, when parts of the path overlap other parts. Specifically, it chooses between the "non-zero" and "even-odd" methods of determining inclusion. `clip-rule` can be applied to all SVG elements, but only has an effect on those which are part of a clipping path. CSS values of the `clip-rule` property can override SVG values of the {{SVGAttr("clip-rule")}} attribute. +The **`clip-rule`** [CSS](/en-US/docs/Web/CSS) property determines, when parts of the path overlap other parts, which pixels in a mask's box are inside the clipping shape defined by a [clip path](/en-US/docs/Web/CSS/clip-path) and which are outside. + +The `clip-rule` property only applies to SVG elements that are contained within a {{SVGElement("clipPath")}} element, overriding the element's {{SVGAttr("clip-rule")}} attribute value if present. The `clip-rule` property basically works as the {{cssxref("fill-rule")}} property, except that it applies to `<clipPath>` definitions. It does not have any effect on CSS {{cssxref("basic-shape")}}s. ## Syntax @@ -40,6 +42,144 @@ clip-rule: unset; ## Examples +### Value comparison + +In this example, we will apply different CSS `clip-rule` values to similar SVG {{SVGElement("path")}} elements to demonstrate the difference between `evenodd` and `non-zero`. + +#### HTML + +The markup has multiple `<svg>` containers, each containing a `<clipPath>` element that defines a star shape, and a `<rect>` element to draw the star inside. The stars are created with overlapping lines. Other than the `id`, the markup of the first two SVG elements is identical. The third SVG includes just the `<path>` element, showing how the lines of the path that created the star overlap. + +```html +<svg> + <clipPath id="star1"> + <path d="M50,0 21,90 98,35 2,35 79,90z" /> + </clipPath> + <rect clip-path="url(#star1)" width="95" height="95" /> +</svg> + +<svg> + <clipPath id="star2"> + <path d="M50,0 21,90 98,35 2,35 79,90z" /> + </clipPath> + <rect clip-path="url(#star2)" width="95" height="95" /> +</svg> + +<svg id="star3"> + <path d="M50,0 21,90 98,35 2,35 79,90z" /> +</svg> +``` + +#### CSS + +The `clip-rule` for the `<path>` in the first SVG is set to `evenodd`; `nonzero` in the second SVG. For the path-only SVG, we removed the default {{cssxref("fill")}} and defined both a {{cssxref("stroke")}} color and {{cssxref("stroke-width")}} to make the overlapping path lines visible: + +```css hidden +body { + display: flex; + gap: 20px; +} +svg { + width: 110px; + height: 110px; +} +``` + +```css +#star1 path { + clip-rule: evenodd; +} + +#star2 path { + clip-rule: nonzero; +} + +#star3 path { + fill: none; + stroke: #000; + stroke-width: 1; +} +``` + +#### Results + +{{EmbedLiveSample("Value comparison", "", "130")}} + +### Within basic shape definitions + +This example demonstrates that, while the `clip-rule` does not have any effect on CSS {{cssxref("basic-shape")}}s, it can affect a `<clipPath>` used as the source of a shape. + +#### HTML + +We include an SVG with two `<clipPath>` elements that define star shapes, which are identical except for their `id` attribute values. We also include two `<div>` elements that will contain our star shapes. + +```html +<svg height="0" width="0"> + <defs> + <clipPath id="star1"> + <path d="M100,0 42,180 196,70 4,70 158,180z" /> + </clipPath> + <clipPath id="star2"> + <path d="M100,0 42,180 196,70 4,70 158,180z" /> + </clipPath> + </defs> +</svg> + +<div></div> +<div></div> +``` + +#### CSS + +We provide the `<div>` elements with a set {{cssxref("width")}} and {{cssxref("height")}}, adding a [`conic-gradient()`](/en-US/docs/Web/CSS/gradient/conic-gradient) for their {{cssxref("background-image")}} value: + +```css hidden +body { + display: flex; + gap: 20px; +} +``` + +```css +div { + height: 200px; + width: 200px; + background-image: conic-gradient( + at center, + rebeccapurple, + green, + lightblue, + rebeccapurple + ); +} +``` + +We use the {{cssxref("clip-path")}} property to set the different `<clipPath>` elements as the clipping path for each `<div>`: + +```css +div:first-of-type { + clip-path: url(#star1); +} +div:last-of-type { + clip-path: url(#star2); +} +``` + +Finally, we set the different `clip-rule` values for each of the `<clipPath>` element's `<path>`s: + +```css +#star1 path { + clip-rule: evenodd; +} +#star2 path { + clip-rule: nonzero; +} +``` + +#### Results + +{{EmbedLiveSample("Within basic shape definitions", "", "200")}} + ### Choosing between rules for a path with all clockwise paths In this SVG image, we have two rectangles that are clipped, once with each clipping rule. There are two {{SVGElement("clipPath")}} elements, so that one can be set to use the non-zero clipping rule and the other uses the even-odd rule. Both paths are drawn in a clockwise direction for both its inner and outer parts. @@ -140,6 +280,10 @@ In this case, because the outer part of the path moves in a clockwise (left-to-r ## See also +- {{cssxref("fill-rule")}} +- {{cssxref("clip-path")}} +- [Introduction to CSS clipping](/en-US/docs/Web/CSS/CSS_masking/Clipping) +- [CSS masking](/en-US/docs/Web/CSS/CSS_masking) module - SVG {{SVGAttr("clip-rule")}} attribute - SVG {{SVGElement("clipPath")}} element -- CSS {{CSSxRef('clip-path')}} property +- SVG {{SVGAttr("fill-rule")}} attribute diff --git a/files/en-us/web/css/clip/index.md b/files/en-us/web/css/clip/index.md index ca265d2f7c74e2c..9ff49427fa279e4 100644 --- a/files/en-us/web/css/clip/index.md +++ b/files/en-us/web/css/clip/index.md @@ -10,7 +10,7 @@ browser-compat: css.properties.clip {{CSSRef}}{{Deprecated_Header}} > [!WARNING] -> Where possible, authors are encouraged to use the newer {{cssxref("clip-path")}} property instead. +> Authors are encouraged to use the {{cssxref("clip-path")}} property instead. The **`clip`** [CSS](/en-US/docs/Web/CSS) property defines a visible portion of an element. The `clip` property applies only to absolutely positioned elements — that is, elements with {{cssxref("position","position:absolute")}} or {{cssxref("position","position:fixed")}}. @@ -33,12 +33,15 @@ clip: unset; ### Values -- {{cssxref("shape")}} +- `rect()` - - : A rectangular {{cssxref("shape")}} of the form `rect(<top>, <right>, <bottom>, <left>)`. The `<top>` and `<bottom>` values are offsets from the _inside top border edge_ of the box, while `<right>` and `<left>` are offsets from the _inside left border edge_ of the box — that is, the extent of the padding box. + - : A rectangle defined using a `rect()` function of the form `rect(<top>, <right>, <bottom>, <left>)`. The `<top>` and `<bottom>` values are offsets from the _inside top border edge_ of the box, while `<right>` and `<left>` are offsets from the _inside left border edge_ of the box — that is, the extent of the padding box. The `<top>`, `<right>`, `<bottom>`, and `<left>` values may be either a {{cssxref("&lt;length&gt;")}} or `auto`. If any side's value is `auto`, the element is clipped to that side's _inside border edge_. +> [!NOTE] +> The `rect()` {{cssxref("shape")}} function used in the deprecated `clip` property is different from the CSS {{cssxref("basic-shape/rect","rect()")}} function used to define a CSS {{cssxref("basic-shape")}}. + - `auto` - : The element does not clip (default). This is different from `rect(auto, auto, auto, auto)`, which clips to the element's inside border edges. @@ -109,12 +112,8 @@ clip: unset; ## See also -- This property is deprecated. Use {{cssxref("clip-path")}} instead. -- Related CSS properties: - - {{cssxref("text-overflow")}} - - {{cssxref("white-space")}} - - {{cssxref("overflow-x")}} - - {{cssxref("overflow-y")}} - - {{cssxref("overflow")}} - - {{cssxref("display")}} - - {{cssxref("position")}} +- {{cssxref("clip-path")}} +- {{cssxref("position")}} +- {{cssxref("mask")}} +- {{cssxref("shape-image-threshold")}} +- {{cssxref("shape-outside")}} diff --git a/files/en-us/web/css/color-scheme/index.md b/files/en-us/web/css/color-scheme/index.md index 3615fa0044012f4..824b0b38b1706b6 100644 --- a/files/en-us/web/css/color-scheme/index.md +++ b/files/en-us/web/css/color-scheme/index.md @@ -18,7 +18,32 @@ Component authors must use the [`prefers-color-scheme`](/en-US/docs/Web/CSS/@med Common choices for operating system color schemes are "light" and "dark", or "day mode" and "night mode". When a user selects one of these color schemes, the operating system makes adjustments to the user interface. This includes [form controls](/en-US/docs/Learn_web_development/Extensions/Forms), [scrollbars](/en-US/docs/Web/CSS/CSS_scrollbars_styling), and the used values of [CSS system colors](/en-US/docs/Web/CSS/system-color). -{{EmbedInteractiveExample("pages/css/color-scheme.html")}} +{{InteractiveExample("CSS Demo: color-scheme")}} + +```css interactive-example-choice +color-scheme: normal; +``` + +```css interactive-example-choice +color-scheme: dark; +``` + +```css interactive-example-choice +color-scheme: light; +``` + +```html interactive-example +<section class="default-example container" id="default-example"> + <textarea id="example-element">Text Area</textarea> +</section> +``` + +```css interactive-example +#example-element { + width: 80%; + height: 50%; +} +``` ## Syntax @@ -42,7 +67,7 @@ The `color-scheme` property's value must be one of the following keywords. ### Values - `normal` - - : Indicates that the element can be rendered using the page's [color scheme](/en-US/docs/Web/HTML/Element/meta/name#color-scheme) settings. If the page does not have a color scheme set, the element is rendered using the page's default color settings. + - : Indicates that the element can be rendered using the page's [color scheme](/en-US/docs/Web/HTML/Reference/Elements/meta/name#color-scheme) settings. If the page does not have a color scheme set, the element is rendered using the page's default color settings. - `light` - : Indicates that the element can be rendered using the operating system _light_ color scheme. - `dark` @@ -87,7 +112,7 @@ footer { } ``` -Along with the above CSS, also include the [`<meta name="color-scheme">`](/en-US/docs/Web/HTML/Element/meta/name#color-scheme) HTML {{HTMLElement("meta")}} tag in the {{htmlelement("head")}}, before any CSS style information, to inform user agents about the preferred color scheme, helping prevent unwanted screen flashes during the page load. +Along with the above CSS, also include the [`<meta name="color-scheme">`](/en-US/docs/Web/HTML/Reference/Elements/meta/name#color-scheme) HTML {{HTMLElement("meta")}} tag in the {{htmlelement("head")}}, before any CSS style information, to inform user agents about the preferred color scheme, helping prevent unwanted screen flashes during the page load. ### Styling based on color schemes diff --git a/files/en-us/web/css/color/index.md b/files/en-us/web/css/color/index.md index 2931d1afc4296d3..3d83dc86e6b7e1f 100644 --- a/files/en-us/web/css/color/index.md +++ b/files/en-us/web/css/color/index.md @@ -9,7 +9,53 @@ browser-compat: css.properties.color The **`color`** [CSS](/en-US/docs/Web/CSS) property sets the foreground [color value](/en-US/docs/Web/CSS/color_value) of an element's text and [text decorations](/en-US/docs/Web/CSS/text-decoration), and sets the [`currentcolor`](/en-US/docs/Web/CSS/color_value#currentcolor_keyword) value. `currentcolor` may be used as an indirect value on _other_ properties and is the default for other color properties, such as {{cssxref("border-color")}}. -{{EmbedInteractiveExample("pages/css/color.html")}} +{{InteractiveExample("CSS Demo: color")}} + +```css interactive-example-choice +color: rebeccapurple; +``` + +```css interactive-example-choice +color: #00a400; +``` + +```css interactive-example-choice +color: rgb(214, 122, 127); +``` + +```css interactive-example-choice +color: hsl(30deg 82% 43%); +``` + +```css interactive-example-choice +color: hsla(237deg 74% 33% / 61%); +``` + +```css interactive-example-choice +color: hwb(152deg 0% 58% / 70%); +``` + +```html interactive-example +<section id="default-example"> + <div class="example-container"> + <p id="example-element"> + London. Michaelmas term lately over, and the Lord Chancellor sitting in + Lincoln's Inn Hall. Implacable November weather. + </p> + </div> +</section> +``` + +```css interactive-example +#example-element { + font-size: 1.5em; +} + +.example-container { + background-color: white; + padding: 10px; +} +``` For an overview of using color in HTML, see [Applying color to HTML elements using CSS](/en-US/docs/Web/CSS/CSS_colors/Applying_color). @@ -82,7 +128,7 @@ It is important to ensure that the contrast ratio between the color of the text Color contrast ratio is determined by comparing the luminosity of the text and background color values. In order to meet current [Web Content Accessibility Guidelines (WCAG)](https://www.w3.org/WAI/standards-guidelines/wcag/), a ratio of 4.5:1 is required for text content and 3:1 for larger text such as headings. Large text is defined as 18.66px and [bold](/en-US/docs/Web/CSS/font-weight) or larger, or 24px or larger. - [WebAIM: Color Contrast Checker](https://webaim.org/resources/contrastchecker/) -- [MDN Understanding WCAG, Guideline 1.4 explanations](/en-US/docs/Web/Accessibility/Understanding_WCAG/Perceivable#guideline_1.4_make_it_easier_for_users_to_see_and_hear_content_including_separating_foreground_from_background) +- [MDN Understanding WCAG, Guideline 1.4 explanations](/en-US/docs/Web/Accessibility/Guides/Understanding_WCAG/Perceivable#guideline_1.4_make_it_easier_for_users_to_see_and_hear_content_including_separating_foreground_from_background) - [Understanding Success Criterion 1.4.3 | W3C Understanding WCAG 2.0](https://www.w3.org/TR/UNDERSTANDING-WCAG20/visual-audio-contrast-contrast.html) ## Formal definition @@ -145,4 +191,4 @@ p { - Other color-related properties: {{cssxref("background-color")}}, {{cssxref("border-color")}}, {{cssxref("outline-color")}}, {{cssxref("text-decoration-color")}}, {{cssxref("text-emphasis-color")}}, {{cssxref("text-shadow")}}, {{cssxref("caret-color")}}, {{cssxref("column-rule-color")}}, and {{cssxref("print-color-adjust")}} - SVG {{SVGAttr("color")}} attribute - [Applying color to HTML elements using CSS](/en-US/docs/Web/CSS/CSS_colors/Applying_color) -- [WCAG: color contrast](/en-US/docs/Web/Accessibility/Understanding_WCAG/Perceivable/Color_contrast) +- [WCAG: color contrast](/en-US/docs/Web/Accessibility/Guides/Understanding_WCAG/Perceivable/Color_contrast) diff --git a/files/en-us/web/css/color_value/color-mix/index.md b/files/en-us/web/css/color_value/color-mix/index.md index 9e8adfd9e4ad50d..ee241bc99c130e8 100644 --- a/files/en-us/web/css/color_value/color-mix/index.md +++ b/files/en-us/web/css/color_value/color-mix/index.md @@ -9,6 +9,13 @@ browser-compat: css.types.color.color-mix The **`color-mix()`** functional notation takes two {{cssxref("&lt;color&gt;")}} values and returns the result of mixing them in a given colorspace by a given amount. +Choosing the correct color space is important for producing desired results. Given the same colors to mix, different color spaces may be more appropriate depending on the interpolation use case. + +- If the result of physically mixing two colored lights is desired, the CIE XYZ or srgb-linear color space is appropriate, because they are linear in light intensity. +- If colors need to be evenly spaced perceptually (such as in a gradient), the Oklab color space (and the older Lab) are appropriate, because they are designed to be perceptually uniform. +- If avoiding graying out in color mixing is desired, i.e., maximizing chroma throughout the transition, Oklch (and the older LCH) work well. +- Only use sRGB if you need to match the behavior of a specific device or software that uses sRGB. The sRGB color space is neither linear-light nor perceptually uniform, and produces poorer results such as overly dark or grayish mixes. + ## Syntax ```css @@ -72,7 +79,7 @@ The following live demo mixes two colors, `color-one` and `color-two`, using the ### Mixing two colors -This example demonstrates mixing two colors, blue `#a71e14` at different percentages and white with no percentage given. The higher the percentage of `#a71e14` is mixed, the more blue and less white the output color is. +This example demonstrates mixing two colors, red `#a71e14` at different percentages and white with no percentage given. The higher the percentage of `#a71e14` is mixed, the more red and less white the output color is. #### HTML @@ -89,7 +96,7 @@ This example demonstrates mixing two colors, blue `#a71e14` at different percent #### CSS -The `color-mix()` function is used to add increasing percentages of blue, up to 100%. The 6th {{htmlelement("li")}} doesn't include a percentage for either color. +The `color-mix()` function is used to add increasing percentages of red, up to 100%. The 6th {{htmlelement("li")}} doesn't include a percentage for either color. ```css hidden ul { diff --git a/files/en-us/web/css/color_value/color/index.md b/files/en-us/web/css/color_value/color/index.md index 434bf518f865f4f..2244ffe1522daaa 100644 --- a/files/en-us/web/css/color_value/color/index.md +++ b/files/en-us/web/css/color_value/color/index.md @@ -122,7 +122,7 @@ color(from hsl(0 100% 50%) xyz x y 0.5) ``` > [!NOTE] -> As mentioned above, if the output color is using a different color model to the origin color, the origin color is converted to the same model as the output color in the background so that it can be represented in a way that is compatible (i.e. using the same channels). For example, the {{cssxref("color_value/hsl", "hsl()")}} color `hsl(0 100% 50%)` is converted to `color(srgb 1 0 0)` in the first case above and `color(xyz 0.412426 0.212648 0.5)` in the second case. +> As mentioned above, if the output color is using a different color model to the origin color, the origin color is converted to the same model as the output color in the background so that it can be represented in a way that is compatible (i.e., using the same channels). For example, the {{cssxref("color_value/hsl", "hsl()")}} color `hsl(0 100% 50%)` is converted to `color(srgb 1 0 0)` in the first case above and `color(xyz 0.412426 0.212648 0.5)` in the second case. In the examples we've seen so far in this section, the alpha channels have not been explicitly specified for either the origin or output colors. When the output color alpha channel is not specified, it defaults to the same value as the origin color alpha channel. When the origin color alpha channel is not specified (and it is not a relative color), it defaults to `1`. Therefore, the origin and output alpha channel values are `1` for the above examples. diff --git a/files/en-us/web/css/color_value/hsl/index.md b/files/en-us/web/css/color_value/hsl/index.md index 08df583bfc5bb88..bd513cb17ed485c 100644 --- a/files/en-us/web/css/color_value/hsl/index.md +++ b/files/en-us/web/css/color_value/hsl/index.md @@ -15,7 +15,37 @@ spec-urls: The **`hsl()`** functional notation expresses a color in the {{glossary("RGB", "sRGB")}} {{glossary("color space")}} according to its _hue_, _saturation_, and _lightness_ components. An optional _alpha_ component represents the color's transparency. -{{EmbedInteractiveExample("pages/css/function-hsl.html")}} +{{InteractiveExample("CSS Demo: hsl()")}} + +```css interactive-example-choice +background: hsl(50 80% 40%); +``` + +```css interactive-example-choice +background: hsl(150deg 30% 60%); +``` + +```css interactive-example-choice +background: hsl(0.3turn 60% 45% / 0.7); +``` + +```css interactive-example-choice +background: hsl(0 80% 50% / 25%); +``` + +```html interactive-example +<section id="default-example"> + <div class="transition-all" id="example-element"></div> +</section> +``` + +```css interactive-example +#example-element { + min-width: 100%; + min-height: 100%; + padding: 10%; +} +``` Defining _complementary colors_ with `hsl()` can be done by adding or subtracting 180 degrees from the hue value, as they are positioned on the same diameter of the {{glossary("color wheel")}}. For example, if the hue angle of a color is `10deg`, its complementary has `190deg` as its hue angle. @@ -140,7 +170,7 @@ This example: The final output color is the equivalent of `hsl(0 30% 60%)` in the sRGB color space — `color(srgb 0.72 0.48 0.48)`. > [!NOTE] -> As mentioned above, if the output color is using a different color model to the origin color, the origin color is converted to the same model as the output color in the background so that it can be represented in a way that is compatible (i.e. using the same channels). +> As mentioned above, if the output color is using a different color model to the origin color, the origin color is converted to the same model as the output color in the background so that it can be represented in a way that is compatible (i.e., using the same channels). In the examples we've seen so far in this section, the alpha channels have not been explicitly specified for either the origin or output colors. When the output color alpha channel is not specified, it defaults to the same value as the origin color alpha channel. When the origin color alpha channel is not specified (and it is not a relative color), it defaults to `1`. Therefore, the origin and output alpha channel values are `1` for the above examples. diff --git a/files/en-us/web/css/color_value/hwb/index.md b/files/en-us/web/css/color_value/hwb/index.md index d926306c16d1700..0ec535456881aac 100644 --- a/files/en-us/web/css/color_value/hwb/index.md +++ b/files/en-us/web/css/color_value/hwb/index.md @@ -12,7 +12,37 @@ spec-urls: The **`hwb()`** functional notation expresses a color in the {{glossary("RGB", "sRGB")}} {{glossary("color space")}} according to its hue, whiteness, and blackness. An optional alpha component represents the color's transparency. -{{EmbedInteractiveExample("pages/css/function-hwb.html")}} +{{InteractiveExample("CSS Demo: hwb()")}} + +```css interactive-example-choice +background: hwb(12 50% 0%); +``` + +```css interactive-example-choice +background: hwb(50deg 30% 40%); +``` + +```css interactive-example-choice +background: hwb(0.5turn 10% 0% / 0.5); +``` + +```css interactive-example-choice +background: hwb(0 100% 0% / 50%); +``` + +```html interactive-example +<section id="default-example"> + <div class="transition-all" id="example-element"></div> +</section> +``` + +```css interactive-example +#example-element { + min-width: 100%; + min-height: 100%; + padding: 10%; +} +``` ## Syntax @@ -144,7 +174,7 @@ This example: The final output color is the equivalent of `hwb(0 30% 0%)` in the sRGB color space — `color(srgb 1 0.3 0.3)`. > [!NOTE] -> As mentioned above, if the output color is using a different color model to the origin color, the origin color is converted to the same model or space as the output color in the background so that it can be represented in a way that is compatible (i.e. using the same channels). +> As mentioned above, if the output color is using a different color model to the origin color, the origin color is converted to the same model or space as the output color in the background so that it can be represented in a way that is compatible (i.e., using the same channels). In the examples we've seen so far in this section, the alpha channels have not been explicitly specified for either the origin or output colors. When the output color alpha channel is not specified, it defaults to the same value as the origin color alpha channel. When the origin color alpha channel is not specified (and it is not a relative color), it defaults to `1`. Therefore, the origin and output alpha channel values are `1` for the above examples. diff --git a/files/en-us/web/css/color_value/index.md b/files/en-us/web/css/color_value/index.md index 49dd8d8fa8117b6..573e748ffe22549 100644 --- a/files/en-us/web/css/color_value/index.md +++ b/files/en-us/web/css/color_value/index.md @@ -85,13 +85,24 @@ The `currentcolor` keyword represents the value of an element's {{Cssxref("color If `currentcolor` is used as the value of the `color` property, it instead takes its value from the inherited value of the `color` property. ```html -<div style="color: blue; border: 1px dashed currentcolor;"> +<div class="container"> The color of this text is blue. - <div style="background: currentcolor; height:9px;"></div> + <div class="child"></div> This block is surrounded by a blue border. </div> ``` +```css +.container { + color: blue; + border: 1px dashed currentcolor; +} +.child { + background: currentcolor; + height: 9px; +} +``` + {{EmbedLiveSample("currentcolor_keyword", "100%", 80)}} ### Missing color components @@ -114,7 +125,7 @@ background-color: hsl(0deg 100% 50%); Color interpolation happens with [gradients](/en-US/docs/Web/CSS/gradient), [transitions](/en-US/docs/Web/CSS/CSS_transitions/Using_CSS_transitions), and [animations](/en-US/docs/Web/CSS/CSS_animations/Using_CSS_animations). -When interpolating `<color>` values, they are first converted to a given color space, and then each component of the [computed values](/en-US/docs/Web/CSS/CSS_cascade/computed_value) are interpolated linearly, with interpolation's speed being determined by the [easing function](/en-US/docs/Web/CSS/easing-function) in transitions and animations. The interpolation color space defaults to Oklab, but can be overridden through {{CSSXref("&lt;color-interpolation-method&gt;")}} in some color-related functional notations. +When interpolating `<color>` values, they are first converted to a given color space, and then each component of the [computed values](/en-US/docs/Web/CSS/CSS_cascade/Value_processing#computed_value) are interpolated linearly, with interpolation's speed being determined by the [easing function](/en-US/docs/Web/CSS/easing-function) in transitions and animations. The interpolation color space defaults to Oklab, but can be overridden through {{CSSXref("&lt;color-interpolation-method&gt;")}} in some color-related functional notations. ### Interpolation with missing components @@ -190,7 +201,7 @@ The preprocessing procedure is: ## Accessibility -Some people have difficulty distinguishing colors. The [WCAG 2.2](/en-US/docs/Web/Accessibility/Understanding_WCAG/Perceivable/Use_of_color) recommendation strongly advises against using color as the only means of conveying a specific message, action, or result. See [color and color contrast](/en-US/docs/Web/Accessibility/Understanding_WCAG/Perceivable/Color_contrast) for more information. +Some people have difficulty distinguishing colors. The [WCAG 2.2](/en-US/docs/Web/Accessibility/Guides/Understanding_WCAG/Perceivable/Use_of_color) recommendation strongly advises against using color as the only means of conveying a specific message, action, or result. See [color and color contrast](/en-US/docs/Web/Accessibility/Guides/Understanding_WCAG/Perceivable/Color_contrast) for more information. ## Formal syntax diff --git a/files/en-us/web/css/color_value/lab/index.md b/files/en-us/web/css/color_value/lab/index.md index ef74deca2ba873e..cdee85d94b92e64 100644 --- a/files/en-us/web/css/color_value/lab/index.md +++ b/files/en-us/web/css/color_value/lab/index.md @@ -117,7 +117,7 @@ This example: The final output color is `lab(54.29 -100 69.8997)`. > [!NOTE] -> As mentioned above, if the output color is using a different color model to the origin color, the origin color is converted to the same model as the output color in the background so that it can be represented in a way that is compatible (i.e. using the same channels). +> As mentioned above, if the output color is using a different color model to the origin color, the origin color is converted to the same model as the output color in the background so that it can be represented in a way that is compatible (i.e., using the same channels). In the examples we've seen so far in this section, the alpha channels have not been explicitly specified for either the origin or output colors. When the output color alpha channel is not specified, it defaults to the same value as the origin color alpha channel. When the origin color alpha channel is not specified (and it is not a relative color), it defaults to `1`. Therefore, the origin and output alpha channel values are `1` for the above examples. diff --git a/files/en-us/web/css/color_value/lch/index.md b/files/en-us/web/css/color_value/lch/index.md index 59525cac25d7b2a..90d97e80744d15a 100644 --- a/files/en-us/web/css/color_value/lch/index.md +++ b/files/en-us/web/css/color_value/lch/index.md @@ -140,7 +140,7 @@ This example: The final output color is `lch(70 150 40.856)`. > [!NOTE] -> As mentioned above, if the output color is using a different color model to the origin color, the origin color is converted to the same model as the output color in the background so that it can be represented in a way that is compatible (i.e. using the same channels). +> As mentioned above, if the output color is using a different color model to the origin color, the origin color is converted to the same model as the output color in the background so that it can be represented in a way that is compatible (i.e., using the same channels). In the examples we've seen so far in this section, the alpha channels have not been explicitly specified for either the origin or output colors. When the output color alpha channel is not specified, it defaults to the same value as the origin color alpha channel. When the origin color alpha channel is not specified (and it is not a relative color), it defaults to `1`. Therefore, the origin and output alpha channel values are `1` for the above examples. diff --git a/files/en-us/web/css/color_value/light-dark/index.md b/files/en-us/web/css/color_value/light-dark/index.md index 167a1167ec6f870..fd3e9c6604991be 100644 --- a/files/en-us/web/css/color_value/light-dark/index.md +++ b/files/en-us/web/css/color_value/light-dark/index.md @@ -8,7 +8,7 @@ browser-compat: css.types.color.light-dark {{CSSRef}} The **`light-dark()`** [CSS](/en-US/docs/Web/CSS) [`<color>` function](/en-US/docs/Web/CSS/CSS_Values_and_Units/CSS_Value_Functions#color_functions) enables setting two colors for a property - returning one of the two colors options by detecting if the developer has set a light or dark color scheme or the user has requested light or dark color theme - without needing to encase the theme colors within a [`prefers-color-scheme`](/en-US/docs/Web/CSS/@media/prefers-color-scheme) [media feature](/en-US/docs/Web/CSS/CSS_media_queries/Using_media_queries#targeting_media_features) query. -Users are able to indicate their color-scheme preference through their operating system settings (e.g. light or dark mode) or their user agent settings. The `light-dark()` function enables providing two color values where any `<color>` value is accepted. The `light-dark()` CSS color function returns the first value if the user's preference is set to `light` or if no preference is set and the second value if the user's preference is set to `dark`. +Users are able to indicate their color-scheme preference through their operating system settings (e.g., light or dark mode) or their user agent settings. The `light-dark()` function enables providing two color values where any `<color>` value is accepted. The `light-dark()` CSS color function returns the first value if the user's preference is set to `light` or if no preference is set and the second value if the user's preference is set to `dark`. To enable support for the `light-dark()` color function, the {{CSSXref("color-scheme")}} must have a value of `light dark`, usually set on the {{CSSXref(":root")}} [pseudo-class](/en-US/docs/Web/CSS/Pseudo-classes). @@ -145,5 +145,5 @@ section { - [CSS colors](/en-US/docs/Web/CSS/CSS_colors) module - [`prefers-contrast`](/en-US/docs/Web/CSS/@media/prefers-contrast) {{cssxref("@media")}} feature - [`contrast()`](/en-US/docs/Web/CSS/filter-function/contrast) -- [WCAG: color contrast](/en-US/docs/Web/Accessibility/Understanding_WCAG/Perceivable/Color_contrast) +- [WCAG: color contrast](/en-US/docs/Web/Accessibility/Guides/Understanding_WCAG/Perceivable/Color_contrast) - [CSS custom properties](/en-US/docs/Web/CSS/--*) and {{cssxref("var")}} diff --git a/files/en-us/web/css/color_value/oklab/index.md b/files/en-us/web/css/color_value/oklab/index.md index af9415d98206df2..ed27c85db634d73 100644 --- a/files/en-us/web/css/color_value/oklab/index.md +++ b/files/en-us/web/css/color_value/oklab/index.md @@ -120,7 +120,7 @@ This example: The final output color is `oklab(0.627966 -0.3 0.125859)`. > [!NOTE] -> As mentioned above, if the output color is using a different color model to the origin color, the origin color is converted to the same model as the output color in the background so that it can be represented in a way that is compatible (i.e. using the same channels). +> As mentioned above, if the output color is using a different color model to the origin color, the origin color is converted to the same model as the output color in the background so that it can be represented in a way that is compatible (i.e., using the same channels). In the examples we've seen so far in this section, the alpha channels have not been explicitly specified for either the origin or output colors. When the output color alpha channel is not specified, it defaults to the same value as the origin color alpha channel. When the origin color alpha channel is not specified (and it is not a relative color), it defaults to `1`. Therefore, the origin and output alpha channel values are `1` for the above examples. diff --git a/files/en-us/web/css/color_value/oklch/index.md b/files/en-us/web/css/color_value/oklch/index.md index 9c065b9388523b4..562087623bd5838 100644 --- a/files/en-us/web/css/color_value/oklch/index.md +++ b/files/en-us/web/css/color_value/oklch/index.md @@ -140,7 +140,7 @@ This example: The final output color is `oklch(0.8 0.4 29.2346)`. > [!NOTE] -> As mentioned above, if the output color is using a different color model to the origin color, the origin color is converted to the same model as the output color in the background so that it can be represented in a way that is compatible (i.e. using the same channels). +> As mentioned above, if the output color is using a different color model to the origin color, the origin color is converted to the same model as the output color in the background so that it can be represented in a way that is compatible (i.e., using the same channels). In the examples we've seen so far in this section, the alpha channels have not been explicitly specified for either the origin or output colors. When the output color alpha channel is not specified, it defaults to the same value as the origin color alpha channel. When the origin color alpha channel is not specified (and it is not a relative color), it defaults to `1`. Therefore, the origin and output alpha channel values are `1` for the above examples. diff --git a/files/en-us/web/css/color_value/rgb/index.md b/files/en-us/web/css/color_value/rgb/index.md index f3bf0066533443b..ec3613db0048fa4 100644 --- a/files/en-us/web/css/color_value/rgb/index.md +++ b/files/en-us/web/css/color_value/rgb/index.md @@ -15,7 +15,37 @@ spec-urls: The **`rgb()`** functional notation expresses a color in the {{glossary("RGB", "sRGB")}} {{glossary("color space")}} according to its red, green, and blue components. An optional alpha component represents the color's transparency. -{{EmbedInteractiveExample("pages/css/function-rgb.html")}} +{{InteractiveExample("CSS Demo: rgb()")}} + +```css interactive-example-choice +background: rgb(31 120 50); +``` + +```css interactive-example-choice +background: rgb(30% 20% 50%); +``` + +```css interactive-example-choice +background: rgb(255 122 127 / 80%); +``` + +```css interactive-example-choice +background: rgb(255 122 127 / 0.2); +``` + +```html interactive-example +<section id="default-example"> + <div class="transition-all" id="example-element"></div> +</section> +``` + +```css interactive-example +#example-element { + min-width: 100%; + min-height: 100%; + padding: 10%; +} +``` ## Syntax @@ -120,7 +150,7 @@ This example: The final output color is the equivalent of `rgb(255 80 80)` in the sRGB color space — `color(srgb 1 0.313726 0.313726)`. > [!NOTE] -> As mentioned above, if the output color is using a different color model to the origin color, the origin color is converted to the same model or space as the output color in the background so that it can be represented in a way that is compatible (i.e. using the same channels). +> As mentioned above, if the output color is using a different color model to the origin color, the origin color is converted to the same model or space as the output color in the background so that it can be represented in a way that is compatible (i.e., using the same channels). In the examples we've seen so far in this section, the alpha channels have not been explicitly specified for either the origin or output colors. When the output color alpha channel is not specified, it defaults to the same value as the origin color alpha channel. When the origin color alpha channel is not specified (and it is not a relative color), it defaults to `1`. Therefore, the origin and output alpha channel values are `1` for the above examples. diff --git a/files/en-us/web/css/column-count/index.md b/files/en-us/web/css/column-count/index.md index 6671262e44bdb1b..7b372d1c6cb6df8 100644 --- a/files/en-us/web/css/column-count/index.md +++ b/files/en-us/web/css/column-count/index.md @@ -9,7 +9,43 @@ browser-compat: css.properties.column-count The **`column-count`** [CSS](/en-US/docs/Web/CSS) property breaks an element's content into the specified number of columns. -{{EmbedInteractiveExample("pages/css/column-count.html")}} +{{InteractiveExample("CSS Demo: column-count")}} + +```css interactive-example-choice +column-count: 2; +``` + +```css interactive-example-choice +column-count: 3; +``` + +```css interactive-example-choice +column-count: 4; +``` + +```css interactive-example-choice +column-count: auto; +column-width: 8rem; +``` + +```html interactive-example +<section id="default-example"> + <p id="example-element"> + London. Michaelmas term lately over, and the Lord Chancellor sitting in + Lincoln's Inn Hall. Implacable November weather. As much mud in the streets + as if the waters had but newly retired from the face of the earth, and it + would not be wonderful to meet a Megalosaurus, forty feet long or so, + waddling like an elephantine lizard up Holborn Hill. + </p> +</section> +``` + +```css interactive-example +#example-element { + width: 100%; + text-align: left; +} +``` ## Syntax diff --git a/files/en-us/web/css/column-fill/index.md b/files/en-us/web/css/column-fill/index.md index 9699fd279c5ce48..f51986bbe97b878 100644 --- a/files/en-us/web/css/column-fill/index.md +++ b/files/en-us/web/css/column-fill/index.md @@ -9,7 +9,33 @@ browser-compat: css.properties.column-fill The **`column-fill`** [CSS](/en-US/docs/Web/CSS) property controls how an element's contents are balanced when broken into columns. -{{EmbedInteractiveExample("pages/css/column-fill.html")}} +{{InteractiveExample("CSS Demo: column-fill")}} + +```css interactive-example-choice +column-fill: auto; +``` + +```css interactive-example-choice +column-fill: balance; +``` + +```html interactive-example +<section id="default-example"> + <p id="example-element"> + London. Michaelmas term lately over, and the Lord Chancellor sitting in + Lincoln's Inn Hall. Implacable November weather. + </p> +</section> +``` + +```css interactive-example +#example-element { + width: 100%; + height: 90%; + columns: 3; + text-align: left; +} +``` ## Syntax diff --git a/files/en-us/web/css/column-gap/index.md b/files/en-us/web/css/column-gap/index.md index 7b2975534d30185..eedec8faa3fd90a 100644 --- a/files/en-us/web/css/column-gap/index.md +++ b/files/en-us/web/css/column-gap/index.md @@ -13,7 +13,51 @@ Initially a part of [Multi-column Layout](/en-US/docs/Web/CSS/CSS_multicol_layou Early versions of the specification called this property `grid-column-gap`, and to maintain compatibility with legacy websites, browsers will still accept `grid-column-gap` as an alias for `column-gap`. -{{EmbedInteractiveExample("pages/css/column-gap.html")}} +{{InteractiveExample("CSS Demo: column-gap")}} + +```css interactive-example-choice +column-gap: 0; +``` + +```css interactive-example-choice +column-gap: 10%; +``` + +```css interactive-example-choice +column-gap: 1em; +``` + +```css interactive-example-choice +column-gap: 20px; +``` + +```html interactive-example +<section class="default-example" id="default-example"> + <div class="example-container"> + <div class="transition-all" id="example-element"> + <div>One</div> + <div>Two</div> + <div>Three</div> + <div>Four</div> + <div>Five</div> + </div> + </div> +</section> +``` + +```css interactive-example +#example-element { + border: 1px solid #c5c5c5; + display: grid; + grid-template-columns: 1fr 1fr; + width: 200px; +} + +#example-element > div { + background-color: rgba(0, 0, 255, 0.2); + border: 3px solid blue; +} +``` ## Syntax diff --git a/files/en-us/web/css/column-rule-color/index.md b/files/en-us/web/css/column-rule-color/index.md index d4d2ffdf30d4919..48174ae50634f0b 100644 --- a/files/en-us/web/css/column-rule-color/index.md +++ b/files/en-us/web/css/column-rule-color/index.md @@ -9,7 +9,43 @@ browser-compat: css.properties.column-rule-color The **`column-rule-color`** [CSS](/en-US/docs/Web/CSS) property sets the color of the line drawn between columns in a multi-column layout. -{{EmbedInteractiveExample("pages/css/column-rule-color.html")}} +{{InteractiveExample("CSS Demo: column-rule-color")}} + +```css interactive-example-choice +column-rule-color: red; +``` + +```css interactive-example-choice +column-rule-color: rgb(48, 125, 222); +``` + +```css interactive-example-choice +column-rule-color: hsla(120, 80%, 40%, 0.6); +``` + +```css interactive-example-choice +column-rule-color: currentcolor; +``` + +```html interactive-example +<section id="default-example"> + <p id="example-element"> + London. Michaelmas term lately over, and the Lord Chancellor sitting in + Lincoln's Inn Hall. Implacable November weather. As much mud in the streets + as if the waters had but newly retired from the face of the earth, and it + would not be wonderful to meet a Megalosaurus, forty feet long or so, + waddling like an elephantine lizard up Holborn Hill. + </p> +</section> +``` + +```css interactive-example +#example-element { + columns: 3; + column-rule: solid; + text-align: left; +} +``` ## Syntax diff --git a/files/en-us/web/css/column-rule-style/index.md b/files/en-us/web/css/column-rule-style/index.md index 8b5a42289b2f627..410f2cf5b9d1019 100644 --- a/files/en-us/web/css/column-rule-style/index.md +++ b/files/en-us/web/css/column-rule-style/index.md @@ -9,7 +9,48 @@ browser-compat: css.properties.column-rule-style The **`column-rule-style`** [CSS](/en-US/docs/Web/CSS) property sets the style of the line drawn between columns in a multi-column layout. -{{EmbedInteractiveExample("pages/css/column-rule-style.html")}} +{{InteractiveExample("CSS Demo: column-rule-style")}} + +```css interactive-example-choice +column-rule-style: none; +``` + +```css interactive-example-choice +column-rule-style: dotted; +``` + +```css interactive-example-choice +column-rule-style: solid; +``` + +```css interactive-example-choice +column-rule-style: double; +``` + +```css interactive-example-choice +column-rule-style: ridge; +column-rule-color: #88f; +``` + +```html interactive-example +<section id="default-example"> + <p id="example-element"> + London. Michaelmas term lately over, and the Lord Chancellor sitting in + Lincoln's Inn Hall. Implacable November weather. As much mud in the streets + as if the waters had but newly retired from the face of the earth, and it + would not be wonderful to meet a Megalosaurus, forty feet long or so, + waddling like an elephantine lizard up Holborn Hill. + </p> +</section> +``` + +```css interactive-example +#example-element { + columns: 3; + column-rule: solid; + text-align: left; +} +``` ## Syntax diff --git a/files/en-us/web/css/column-rule-width/index.md b/files/en-us/web/css/column-rule-width/index.md index a214d566096dfae..bce50b38e37560a 100644 --- a/files/en-us/web/css/column-rule-width/index.md +++ b/files/en-us/web/css/column-rule-width/index.md @@ -9,7 +9,43 @@ browser-compat: css.properties.column-rule-width The **`column-rule-width`** [CSS](/en-US/docs/Web/CSS) property sets the width of the line drawn between columns in a multi-column layout. -{{EmbedInteractiveExample("pages/css/column-rule-width.html")}} +{{InteractiveExample("CSS Demo: column-rule-width")}} + +```css interactive-example-choice +column-rule-width: thin; +``` + +```css interactive-example-choice +column-rule-width: medium; +``` + +```css interactive-example-choice +column-rule-width: thick; +``` + +```css interactive-example-choice +column-rule-width: 12px; +``` + +```html interactive-example +<section id="default-example"> + <p id="example-element"> + London. Michaelmas term lately over, and the Lord Chancellor sitting in + Lincoln's Inn Hall. Implacable November weather. As much mud in the streets + as if the waters had but newly retired from the face of the earth, and it + would not be wonderful to meet a Megalosaurus, forty feet long or so, + waddling like an elephantine lizard up Holborn Hill. + </p> +</section> +``` + +```css interactive-example +#example-element { + columns: 3; + column-rule: solid; + text-align: left; +} +``` ## Syntax diff --git a/files/en-us/web/css/column-rule/index.md b/files/en-us/web/css/column-rule/index.md index e3ca41b11b16fe0..4a9538fd8be2ac6 100644 --- a/files/en-us/web/css/column-rule/index.md +++ b/files/en-us/web/css/column-rule/index.md @@ -9,7 +9,43 @@ browser-compat: css.properties.column-rule The **`column-rule`** [shorthand](/en-US/docs/Web/CSS/CSS_cascade/Shorthand_properties) [CSS](/en-US/docs/Web/CSS) property sets the width, style, and color of the line drawn between columns in a multi-column layout. -{{EmbedInteractiveExample("pages/css/column-rule.html")}} +{{InteractiveExample("CSS Demo: column-rule")}} + +```css interactive-example-choice +column-rule: dotted; +``` + +```css interactive-example-choice +column-rule: solid 6px; +``` + +```css interactive-example-choice +column-rule: solid blue; +``` + +```css interactive-example-choice +column-rule: thick inset blue; +``` + +```html interactive-example +<section id="default-example"> + <p id="example-element"> + London. Michaelmas term lately over, and the Lord Chancellor sitting in + Lincoln's Inn Hall. Implacable November weather. As much mud in the streets + as if the waters had but newly retired from the face of the earth, and it + would not be wonderful to meet a Megalosaurus, forty feet long or so, + waddling like an elephantine lizard up Holborn Hill. + </p> +</section> +``` + +```css interactive-example +#example-element { + columns: 3; + column-rule: solid; + text-align: left; +} +``` ## Constituent properties diff --git a/files/en-us/web/css/column-span/index.md b/files/en-us/web/css/column-span/index.md index 194d74701e14b49..77245efe3256501 100644 --- a/files/en-us/web/css/column-span/index.md +++ b/files/en-us/web/css/column-span/index.md @@ -9,7 +9,51 @@ browser-compat: css.properties.column-span The **`column-span`** [CSS](/en-US/docs/Web/CSS) property makes it possible for an element to span across all columns when its value is set to `all`. -{{EmbedInteractiveExample("pages/css/column-span.html")}} +{{InteractiveExample("CSS Demo: column-span")}} + +```css interactive-example-choice +column-span: none; +``` + +```css interactive-example-choice +column-span: all; +``` + +```html interactive-example +<section id="default-example"> + <div class="multicol-element"> + <p> + London. Michaelmas term lately over, and the Lord Chancellor sitting in + Lincoln's Inn Hall. + </p> + <div id="example-element">Spanner?</div> + <p> + Implacable November weather. As much mud in the streets as if the waters + had but newly retired from the face of the earth, and it would not be + wonderful to meet a Megalosaurus, forty feet long or so, waddling like an + elephantine lizard up Holborn Hill. + </p> + </div> +</section> +``` + +```css interactive-example +.multicol-element { + width: 100%; + text-align: left; + column-count: 3; +} + +.multicol-element p { + margin: 0; +} + +#example-element { + background-color: rebeccapurple; + padding: 10px; + color: #fff; +} +``` An element that spans more than one column is called a **spanning element**. diff --git a/files/en-us/web/css/column-width/index.md b/files/en-us/web/css/column-width/index.md index cbdb1e76fdd7030..b6ae1a09740c917 100644 --- a/files/en-us/web/css/column-width/index.md +++ b/files/en-us/web/css/column-width/index.md @@ -9,7 +9,43 @@ browser-compat: css.properties.column-width The **`column-width`** [CSS](/en-US/docs/Web/CSS) property sets the ideal column width in a multi-column layout. The container will have as many columns as can fit without any of them having a width less than the `column-width` value. If the width of the container is narrower than the specified value, the single column's width will be smaller than the declared column width. -{{EmbedInteractiveExample("pages/css/column-width.html")}} +{{InteractiveExample("CSS Demo: column-width")}} + +```css interactive-example-choice +column-width: auto; +``` + +```css interactive-example-choice +column-width: 6rem; +``` + +```css interactive-example-choice +column-width: 120px; +``` + +```css interactive-example-choice +column-width: 18ch; +``` + +```html interactive-example +<section id="default-example"> + <p id="example-element"> + London. Michaelmas term lately over, and the Lord Chancellor sitting in + Lincoln's Inn Hall. Implacable November weather. As much mud in the streets + as if the waters had but newly retired from the face of the earth, and it + would not be wonderful to meet a Megalosaurus, forty feet long or so, + waddling like an elephantine lizard up Holborn Hill. + </p> +</section> +``` + +```css interactive-example +#example-element { + width: 100%; + columns: auto; + text-align: left; +} +``` This property can help you create responsive designs that fit different screen sizes. Especially in the presence of the {{cssxref("column-count")}} property (which has precedence), you must specify all related length values to achieve an exact column width. In horizontal text these are {{cssxref('width')}}, `column-width`, {{cssxref('column-gap')}}, and {{cssxref('column-rule-width')}}. diff --git a/files/en-us/web/css/columns/index.md b/files/en-us/web/css/columns/index.md index ef76373fa95ed87..e9aee81d93fc5a2 100644 --- a/files/en-us/web/css/columns/index.md +++ b/files/en-us/web/css/columns/index.md @@ -9,7 +9,42 @@ browser-compat: css.properties.columns The **`columns`** [CSS](/en-US/docs/Web/CSS) shorthand property sets the number of columns to use when drawing an element's contents, as well as those columns' widths. -{{EmbedInteractiveExample("pages/css/columns.html")}} +{{InteractiveExample("CSS Demo: columns")}} + +```css interactive-example-choice +columns: 2; +``` + +```css interactive-example-choice +columns: 6rem auto; +``` + +```css interactive-example-choice +columns: 12em; +``` + +```css interactive-example-choice +columns: 3; +``` + +```html interactive-example +<section id="default-example"> + <p id="example-element"> + London. Michaelmas term lately over, and the Lord Chancellor sitting in + Lincoln's Inn Hall. Implacable November weather. As much mud in the streets + as if the waters had but newly retired from the face of the earth, and it + would not be wonderful to meet a Megalosaurus, forty feet long or so, + waddling like an elephantine lizard up Holborn Hill. + </p> +</section> +``` + +```css interactive-example +#example-element { + min-width: 21rem; + text-align: left; +} +``` ## Constituent properties diff --git a/files/en-us/web/css/contain/index.md b/files/en-us/web/css/contain/index.md index 20ef6ede3609b7c..f5b30bd76933e0b 100644 --- a/files/en-us/web/css/contain/index.md +++ b/files/en-us/web/css/contain/index.md @@ -10,7 +10,69 @@ browser-compat: css.properties.contain The **`contain`** [CSS](/en-US/docs/Web/CSS) property indicates that an element and its contents are, as much as possible, independent from the rest of the document tree. Containment enables isolating a subsection of the DOM, providing performance benefits by limiting calculations of layout, style, paint, size, or any combination to a DOM subtree rather than the entire page. Containment can also be used to scope CSS counters and quotes. -{{EmbedInteractiveExample("pages/css/contain.html")}} +{{InteractiveExample("CSS Demo: contain")}} + +```css interactive-example-choice +contain: none; +``` + +```css interactive-example-choice +contain: size; +``` + +```css interactive-example-choice +contain: layout; +``` + +```css interactive-example-choice +contain: paint; +``` + +```css interactive-example-choice +contain: strict; +``` + +```html interactive-example +<section class="default-example" id="default-example"> + <div class="card" id="example-element"> + <h2>Element with '<code>contain</code>'</h2> + <p> + The Goldfish is a species of domestic fish best known for its bright + colors and patterns. + </p> + <div class="fixed"><p>Fixed right 4px</p></div> + </div> +</section> +``` + +```css interactive-example +h2 { + margin-top: 0; +} + +#default-example { + text-align: left; + padding: 4px; + font-size: 16px; +} + +.card { + text-align: left; + border: 3px dotted; + padding: 20px; + margin: 10px; + width: 85%; + min-height: 150px; +} + +.fixed { + position: fixed; + border: 3px dotted; + right: 4px; + padding: 4px; + margin: 4px; +} +``` There are four types of CSS containment: size, layout, style, and paint, which are set on the container. The property is a space-separated list of a subset of the five standard values or one of the two shorthand values. @@ -23,7 +85,7 @@ Using the `contain` property is useful on pages with groups of elements that are > Using `layout`, `paint`, `strict` or `content` values for this property creates: > > 1. A new [containing block](/en-US/docs/Web/CSS/CSS_display/Containing_block) (for the descendants whose {{cssxref("position")}} property is `absolute` or `fixed`). -> 2. A new [stacking context](/en-US/docs/Web/CSS/CSS_positioned_layout/Understanding_z-index/Stacking_context). +> 2. A new [stacking context](/en-US/docs/Web/CSS/CSS_positioned_layout/Stacking_context). > 3. A new [block formatting context](/en-US/docs/Web/CSS/CSS_display/Block_formatting_context). ## Syntax diff --git a/files/en-us/web/css/container-name/index.md b/files/en-us/web/css/container-name/index.md index ce41aee103f7dfd..39f9df3a974eb86 100644 --- a/files/en-us/web/css/container-name/index.md +++ b/files/en-us/web/css/container-name/index.md @@ -8,7 +8,7 @@ browser-compat: css.properties.container-name {{CSSRef}} The **container-name** [CSS](/en-US/docs/Web/CSS) property specifies a list of query container names used by the [@container](/en-US/docs/Web/CSS/@container) at-rule in a [container query](/en-US/docs/Web/CSS/CSS_containment/Container_queries). -A container query will apply styles to elements based on the size of the nearest ancestor with a containment context. +A container query will apply styles to elements based on the [size](/en-US/docs/Web/CSS/CSS_containment/Container_size_and_style_queries#container_size_queries) or [scroll-state](/en-US/docs/Web/CSS/CSS_conditional_rules/Container_scroll-state_queries) of the nearest ancestor with a containment context. When a containment context is given a name, it can be specifically targeted using the {{Cssxref("@container")}} at-rule instead of the nearest ancestor with containment. > [!NOTE] @@ -153,6 +153,7 @@ This is useful if you want to target the same container with multiple container - [CSS container queries](/en-US/docs/Web/CSS/CSS_containment/Container_queries) - [Using container size and style queries](/en-US/docs/Web/CSS/CSS_containment/Container_size_and_style_queries) +- [Using container scroll-state queries](/en-US/docs/Web/CSS/CSS_conditional_rules/Container_scroll-state_queries) - {{Cssxref("@container")}} at-rule - CSS {{Cssxref("container")}} shorthand property - CSS {{Cssxref("container-type")}} property diff --git a/files/en-us/web/css/container-type/index.md b/files/en-us/web/css/container-type/index.md index 338a18a82b2d9e4..1865e68409a260f 100644 --- a/files/en-us/web/css/container-type/index.md +++ b/files/en-us/web/css/container-type/index.md @@ -7,11 +7,10 @@ browser-compat: css.properties.container-type {{CSSRef}} -An element can be established as a query container for [container size queries](/en-US/docs/Web/CSS/CSS_containment/Container_queries) using the **`container-type`** [CSS](/en-US/docs/Web/CSS) property. `container-type` is used to define the type of size containment used in a container query. +An element can be established as a query container using the **`container-type`** [CSS](/en-US/docs/Web/CSS) property. `container-type` is used to define the type of container context used in a container query. The available container contexts are: -Size containment turns off the ability of an element to get size information from its contents, which is important for container queries to avoid infinite loops. If this were not the case, a CSS rule inside a container query could change the content size, which in turn could make the query evaluate to false and change the parent element's size, which in turn could change the content size and flip the query back to true, and so on. - -The container size has to be set explicitly or by context — for example, block elements, flex containers, and grid containers stretching to the full width of their parent. If an explicit or contextual size is not available, elements with size containment will collapse. +- [Size](/en-US/docs/Web/CSS/CSS_containment/Container_size_and_style_queries): Enable selectively applying CSS rules to a container's children based on a general size or inline size condition such as a maximum or minimum dimension, aspect ratio, or orientation. +- [Scroll-state](/en-US/docs/Web/CSS/CSS_conditional_rules/Container_scroll-state_queries): Enable selectively applying CSS rules to a container's children based on a scroll-state condition such as whether the container is a scroll container that is partially scrolled or whether the container is a [snap target](/en-US/docs/Glossary/Scroll_snap#snap_target) that is snapped to its scroll snap container. > [!NOTE] > When using the `container-type` and {{cssxref("container-name")}} properties, the `style` and `layout` values of the {{cssxref("contain")}} property are automatically applied. @@ -23,6 +22,10 @@ The container size has to be set explicitly or by context — for example, block container-type: normal; container-type: size; container-type: inline-size; +container-type: scroll-state; + +/* Two values */ +container-type: size scroll-state; /* Global Values */ container-type: inherit; @@ -34,23 +37,30 @@ container-type: unset; ### Values -- `size` - - - : Establishes a query container for container size queries in both the [inline and block](/en-US/docs/Web/CSS/CSS_logical_properties_and_values/Basic_concepts_of_logical_properties_and_values#block_and_inline_dimensions) dimensions. - Applies layout containment, style containment, and size containment to the container. - - Size containment is applied to the element in both the inline and block directions. The size of the element can be computed in isolation, ignoring the child elements. +The `container-type` property can take a single value from the list below, or two values — one of which must be `scroll-state` and the other can be `inline-size` or `size`. In other words, an element an be established as a size query container, a scroll-state query container, both, or neither. - `inline-size` - : Establishes a query container for dimensional queries on the [inline axis](/en-US/docs/Web/CSS/CSS_logical_properties_and_values/Basic_concepts_of_logical_properties_and_values#block_and_inline_dimensions) of the container. Applies layout, style, and inline-size containment to the element. - Inline size containment is applied to the element. The inline size of the element can be computed in isolation, ignoring the child elements. + Inline size containment is applied to the element. The inline size of the element can be [computed in isolation](/en-US/docs/Web/CSS/CSS_containment/Using_CSS_containment#size_containment), ignoring the child elements (see [Using CSS containment](/en-US/docs/Web/CSS/CSS_containment/Using_CSS_containment)). - `normal` + - : Default value. The element is not a query container for any container size queries, but remains a query container for [container style queries](/en-US/docs/Web/CSS/@container#container_style_queries). +- `scroll-state` + + - : Establishes a query container for scroll-state queries on the container. In this case, the size of the element is not computed in isolation; no containment is applied. + +- `size` + + - : Establishes a query container for container size queries in both the [inline and block](/en-US/docs/Web/CSS/CSS_logical_properties_and_values/Basic_concepts_of_logical_properties_and_values#block_and_inline_dimensions) dimensions. + Applies layout containment, style containment, and size containment to the container. + + Size containment is applied to the element in both the inline and block directions. The size of the element can be computed in isolation, ignoring the child elements. + ## Formal definition {{CSSInfo}} @@ -59,6 +69,30 @@ container-type: unset; {{CSSSyntax}} +## Description + +Container queries allow you to selectively apply styles inside a container based on conditional queries performed on the container. The {{cssxref("@container")}} at-rule is used to specify the tests performed on a container, and the rules that will apply to the container's contents if the query returns `true`. + +The container query tests are only performed on elements with a `container-type` property, which defines the elements as a size or scroll-state container, or both. + +### Container size queries + +[Container size queries](/en-US/docs/Web/CSS/CSS_containment/Container_size_and_style_queries#container_size_queries) allow you to selectively apply CSS rules to a container's descendants based on a size condition such as a maximum or minimum dimension, aspect ratio, or orientation. + +Size containers additionally have size containment applied to them — this turns off the ability of an element to get size information from its contents, which is important for container queries to avoid infinite loops. If this were not the case, a CSS rule inside a container query could change the content size, which in turn could make the query evaluate to false and change the parent element's size, which in turn could change the content size and flip the query back to true, and so on. This sequence would then repeat itself in an endless loop. + +The container size has to be set by context, such as block-level elements that stretch to the full width of their parent, or explicitly defined. If a contextual or explicit size is not available, elements with size containment will collapse. + +### Container scroll-state queries + +[Container scroll-state queries](/en-US/docs/Web/CSS/CSS_conditional_rules/Container_scroll-state_queries) allow you to selectively apply CSS rules to a container's children based on a scroll-state condition such as: + +- Whether the container's contents are partially scrolled. +- Whether the container is a snap target that is snapped to a scroll snap container. +- Whether the container is positioned via [`position: sticky`](/en-US/docs/Web/CSS/display) and stuck to a boundary of a {{glossary("scroll container", "scrolling container")}}. + +In the first case, the queried container is the scroll container itself. In the other two cases the queried container is an element that is affected by the scroll position of an ancestor scroll container. + ## Examples ### Establishing inline size containment @@ -149,6 +183,7 @@ Writing a container query via the {{Cssxref("@container")}} at-rule will apply s - [CSS container queries](/en-US/docs/Web/CSS/CSS_containment/Container_queries) - [Using container size and style queries](/en-US/docs/Web/CSS/CSS_containment/Container_size_and_style_queries) +- [Using container scroll-state queries](/en-US/docs/Web/CSS/CSS_conditional_rules/Container_scroll-state_queries) - {{Cssxref("@container")}} at-rule - CSS {{Cssxref("container")}} shorthand property - CSS {{Cssxref("container-name")}} property diff --git a/files/en-us/web/css/content-distribution/index.md b/files/en-us/web/css/content-distribution/index.md index 3eb5e49af4aa71e..2f0280e968e75f7 100644 --- a/files/en-us/web/css/content-distribution/index.md +++ b/files/en-us/web/css/content-distribution/index.md @@ -2,7 +2,7 @@ title: <content-distribution> slug: Web/CSS/content-distribution page-type: css-type -browser-compat: css.types.content-distribution +spec-urls: https://drafts.csswg.org/css-align/#typedef-content-distribution --- {{CSSRef}} @@ -39,10 +39,6 @@ The following keyword values are represented by the `<content-distribution>` gra {{Specifications}} -## Browser compatibility - -{{Compat}} - ## See also - Properties that use this data type: {{cssxref("align-content")}}, {{cssxref("justify-content")}}, {{cssxref("place-content")}} diff --git a/files/en-us/web/css/content-position/index.md b/files/en-us/web/css/content-position/index.md index 713036ab3b8936f..c67adb3808da49b 100644 --- a/files/en-us/web/css/content-position/index.md +++ b/files/en-us/web/css/content-position/index.md @@ -2,7 +2,7 @@ title: <content-position> slug: Web/CSS/content-position page-type: css-type -browser-compat: css.types.content-position +spec-urls: https://drafts.csswg.org/css-align/#typedef-content-position --- {{CSSRef}} @@ -37,14 +37,10 @@ The `<content-position>` enumerated value type is specified using one of the fol {{Specifications}} -## Browser compatibility - -{{Compat}} - ## See also - Properties that use this data type: {{cssxref("align-content")}}, {{cssxref("justify-content")}}, {{cssxref("place-content")}} -- Other box alignment data types: {{cssxref("baseline-position")}}, {{cssxref("content-distribution")}}, {{cssxref("content-position")}}, {{cssxref("overflow-position")}}, and {{cssxref("self-position")}} +- Other box alignment data types: {{cssxref("baseline-position")}}, {{cssxref("content-distribution")}}, `content-position`, {{cssxref("overflow-position")}}, and {{cssxref("self-position")}} - [CSS box alignment](/en-US/docs/Web/CSS/CSS_box_alignment) module - [CSS flexible box layout](/en-US/docs/Web/CSS/CSS_flexible_box_layout) module - [CSS grid layout](/en-US/docs/Web/CSS/CSS_grid_layout) module diff --git a/files/en-us/web/css/content-visibility/index.md b/files/en-us/web/css/content-visibility/index.md index 2af9a645b6b1621..4ab6bfb25f35085 100644 --- a/files/en-us/web/css/content-visibility/index.md +++ b/files/en-us/web/css/content-visibility/index.md @@ -10,9 +10,50 @@ browser-compat: css.properties.content-visibility The **`content-visibility`** [CSS](/en-US/docs/Web/CSS) property controls whether or not an element renders its contents at all, along with forcing a strong set of containments, allowing user agents to potentially omit large swathes of layout and rendering work until it becomes needed. It enables the user agent to skip an element's rendering work (including layout and painting) until it is needed — which makes the initial page load much faster. > [!NOTE] -> The {{domxref("element/contentvisibilityautostatechange_event", "contentvisibilityautostatechange")}} event fires on any element with `content-visibility: auto` set on it when its rendering work starts or stops being skipped. This provides a convenient way for an app's code to start or stop rendering processes (e.g. drawing on a {{htmlelement("canvas")}}) when they are not needed, thereby conserving processing power. +> The {{domxref("element/contentvisibilityautostatechange_event", "contentvisibilityautostatechange")}} event fires on any element with `content-visibility: auto` set on it when its rendering work starts or stops being skipped. This provides a convenient way for an app's code to start or stop rendering processes (e.g., drawing on a {{htmlelement("canvas")}}) when they are not needed, thereby conserving processing power. -{{EmbedInteractiveExample("pages/css/content-visibility.html")}} +{{InteractiveExample("CSS Demo: content-visibility")}} + +```css interactive-example-choice +content-visibility: visible; +``` + +```css interactive-example-choice +content-visibility: hidden; +``` + +```html interactive-example +<section class="default-example" id="default-example"> + <div class="container" id="example-element"> + <div class="child"> + <span>This is an inner div</span> + </div> + </div> +</section> +``` + +```css interactive-example +.container { + width: 140px; + height: 140px; + border: 3px solid rgb(64, 28, 163); + background-color: rgb(135, 136, 184); + display: flex; + align-items: center; + justify-content: center; +} + +.child { + border: 3px solid rgb(64, 28, 163); + background-color: wheat; + color: black; + width: 80%; + height: 80%; + display: flex; + align-items: center; + justify-content: center; +} +``` ## Syntax @@ -33,7 +74,7 @@ content-visibility: unset; ### Values - `visible` - - : No effect. The element's contents are laid out and rendered as normal. + - : No effect. The element's contents are laid out and rendered as normal. This is the default value. - `hidden` - : The element [skips its contents](/en-US/docs/Web/CSS/CSS_containment/Using_CSS_containment#skips_its_contents). The skipped contents must not be accessible to user-agent features, such as find-in-page, tab-order navigation, etc., nor be selectable or focusable. This is similar to giving the contents `display: none`. - `auto` @@ -190,7 +231,7 @@ In this example, we have a {{htmlelement("div")}} element, the content of which #### CSS -In the CSS we initially set `content-visibility: hidden;` on the `<div>` to hide its content. We then set up `@keyframe` animations and attach them to classes to show and hide the `<div>`, animating `content-visibility` and [`color`](/en-US/docs/Web/CSS/color) so that you get a smooth animation effect as the content is shown/hidden. +In the CSS we initially set `content-visibility: hidden;` on the `<div>` to hide its content. We then set up `@keyframes` animations and attach them to classes to show and hide the `<div>`, animating `content-visibility` and [`color`](/en-US/docs/Web/CSS/color) so that you get a smooth animation effect as the content is shown/hidden. ```css div { diff --git a/files/en-us/web/css/content/index.md b/files/en-us/web/css/content/index.md index f0eee86c8766651..d61870533b02612 100644 --- a/files/en-us/web/css/content/index.md +++ b/files/en-us/web/css/content/index.md @@ -9,21 +9,21 @@ browser-compat: css.properties.content The **`content`** [CSS](/en-US/docs/Web/CSS) property replaces content with a generated value. It can be used to define what is rendered inside an element or pseudo-element. For elements, the `content` property specifies whether the element renders normally (`normal` or `none`) or is replaced with an image (and associated "alt" text). For pseudo-elements and margin boxes, `content` defines the content as images, text, both, or none, which determines whether the element renders at all. -Objects inserted using the `content` property are **anonymous [replaced elements](/en-US/docs/Web/CSS/Replaced_element)**. +Objects inserted using the `content` property are **anonymous {{ glossary("replaced elements")}}**. {{InteractiveExample("CSS Demo: content", "tabbed-shorter")}} ```css interactive-example .topic-games::before { - content: "🎮 "; + content: "🎮 " / "games"; } .topic-weather::before { - content: "⛅ "; + content: "⛅ " / "cloudy"; } .topic-hot::before { - content: url("/shared-assets/images/examples/fire.png"); + content: url("/shared-assets/images/examples/fire.png") / "On fire"; margin-right: 6px; } ``` @@ -89,7 +89,7 @@ content: unset; The value can be: -- One of two keywords — `none` or `normal`. +- One of two keywords: `none` or `normal`. `normal` is the default property value. - `<content-replacement>` when replacing a DOM node. `<content-replacement>` is always an `<image>`. - A `<content-list>` when replacing pseudo-elements and margin boxes. A `<content-list>` is a list of one or more anonymous inline boxes appearing in the order specified. Each `<content-list>` item is of type [`<string>`](#string), [`<image>`](#image), [`<counter>`](#counter), [`<quote>`](#quote), [`<target>`](#target), or [`<leader()>`](#leader). - An optional alternative text value of a `<string>` or `<counter>`, preceded by a slash (`/`). @@ -103,7 +103,7 @@ The keywords and data types mentioned above are described in more detail below: - `normal` - - : The default value. Computes to `none` for the {{cssxref("::before")}} and {{cssxref("::after")}} pseudo-elements. For other pseudo-elements, the content will be the initial (or normal) content expected for that {{cssxref("::marker")}}, {{cssxref("::placeholder")}}, or {{cssxref("::file-selector-button")}}. For regular elements or page margin boxes, this computes to the element's descendants. + - : For the {{cssxref("::before")}} and {{cssxref("::after")}} pseudo-elements, this value computes to `none` . For other pseudo-elements such as {{cssxref("::marker")}}, {{cssxref("::placeholder")}}, or {{cssxref("::file-selector-button")}}, it produces the element's initial (or normal) content. For regular elements or page margin boxes, it computes to the element's descendants. This is the default value. - {{cssxref("&lt;string&gt;")}} @@ -142,7 +142,7 @@ The keywords and data types mentioned above are described in more detail below: - : The `attr(x)` CSS function retrieves the value of an attribute of the selected element, or the pseudo-element's originating element. The value of the element's attribute `x` is an unparsed string representing the attribute name. If there is no attribute `x`, an empty string is returned. The case sensitivity of the attribute name parameter depends on the document language. - alternative text: `/ <string> | <counter>` - - : Alternative text may be specified for an image or any `<content-list>` items, by appending a forward slash and then a string of text or a counter. The alternative text is intended for speech output by screen-readers, but may also be displayed in some browsers. Note that if the browser does not support alternative text, the `content` declaration will be considered invalid and will be ignored. The {{cssxref("string", "/ &lt;string>")}} or {{cssxref("counter", "/ &lt;counter>")}} data types specify the "alt text" for the element. + - : Alternative text may be specified for an image or any `<content-list>` items, by appending a forward slash and then a string of text or a counter. The alternative text is intended for speech output by screen-readers, but may also be displayed in some browsers. The {{cssxref("string", "/ &lt;string>")}} or {{cssxref("counter", "/ &lt;counter>")}} data types specify the "alt text" for the element. ## Formal definition @@ -159,7 +159,7 @@ CSS-generated content is not included in the [DOM](/en-US/docs/Web/API/Document_ If inserted content is not decorative, check that the information is provided to assistive technologies and is also available when CSS is turned off. - [Accessibility support for CSS generated content – Tink](https://tink.uk/accessibility-support-for-css-generated-content/) (2015) -- [WCAG, Guideline 1.3: Create content that can be presented in different ways](/en-US/docs/Web/Accessibility/Understanding_WCAG/Perceivable#guideline_1.3_—_create_content_that_can_be_presented_in_different_ways) +- [WCAG, Guideline 1.3: Create content that can be presented in different ways](/en-US/docs/Web/Accessibility/Guides/Understanding_WCAG/Perceivable#guideline_1.3_—_create_content_that_can_be_presented_in_different_ways) - [Understanding Success Criterion 1.3.1 | W3C Understanding WCAG 2.0](https://www.w3.org/TR/UNDERSTANDING-WCAG20/content-structure-separation-programmatic.html) - [Failure of Success Criterion 1.3.1: inserting non-decorative generated content](https://www.w3.org/TR/WCAG20-TECHS/F87) Techniques for WCAG 2.0 @@ -266,8 +266,8 @@ This example combines a counter sandwiched between two `<string>`s prepended to <li>Ducks</li> <li>Flightless</li> </ol> - <li>Marsupials</li> </li> + <li>Marsupials</li> </ol> ``` @@ -324,7 +324,7 @@ The generated content is the value of the `href` attribute, prepended by "URL: " ### Adding an image with alternative text -This example inserts an image before all links. Two `content` values are provided. The later `content` value includes an image with alternative text that a screen reader can output as speech. If a browser does not support alternative text, this declaration will be considered invalid, with the previous `content` value displaying. This fallback content list includes an image and the message " - alt text is not supported - ". +This example inserts an image before all links. Two `content` values are provided. The later `content` value includes an image with alternative text that a screen reader can output as speech. #### HTML @@ -336,20 +336,11 @@ This example inserts an image before all links. Two `content` values are provide The CSS to show the image and set the alternative text is shown below. This also sets the font and color for the content. -This will be used on browsers that _display_ the alternative text and in browsers that don't support alternative text and show the fallback `content` value. ```css a::before { - /* fallback content */ - content: url("https://mozorg.cdn.mozilla.net/media/img/favicon.ico") - " - alt text is not supported - "; - /* content with alternative text */ content: url("https://mozorg.cdn.mozilla.net/media/img/favicon.ico") / " MOZILLA: "; - font: - x-small Arial, - sans-serif; - color: gray; } ``` @@ -358,11 +349,9 @@ a::before { {{EmbedLiveSample('Adding_an_image_with_alternative_text', '100%', 60)}} > [!NOTE] -> If the alternative text syntax is supported, the value will be exposed in the browser's accessibility tree. Refer to the [See also](#see_also) section for browser-specific accessibility panels. - -If using a screen reader, it should speak the word "MOZILLA" when it reaches the image. If supported (if the "alt text is not supported" is not showing), you can select the `::before` pseudo-element with your developer tools selection tool, and view the {{glossary("accessible name")}} in the accessibility panel. +> The alternative text value is exposed in the browser's accessibility tree. Refer to the [See also](#see_also) section for browser-specific accessibility panels. -In browsers that don't support the alternative text syntax the whole declaration containing the alt text is invalid. In this case, the previous `content` value will be used, showing the image and "alt text is not supported" text. +If using a screen reader, it should speak the word "MOZILLA" when it reaches the image. You can select the `::before` pseudo-element with your developer tools selection tool, and view the {{glossary("accessible name")}} in the accessibility panel. ### Element replacement with URL @@ -397,7 +386,7 @@ When generating content on regular elements (rather than just on pseudo-elements ### Element replacement with `<gradient>` -This example demonstrates how an element's contents can be replaced by any type of `<image>`, in this case, a CSS gradient. The element's contents are replaced with a {{cssxref("gradient/linear-gradient", "linear-gradient()")}}. With {{cssxref("@supports")}}, we provide alt text support and a {{cssxref("gradient/repeating-linear-gradient", "repeating-linear-gradient()")}} for browsers that support alt text with element content replacement. +This example demonstrates how an element's contents can be replaced by any type of `<image>`, in this case, a CSS gradient. The element's contents are replaced with a {{cssxref("gradient/linear-gradient", "linear-gradient()")}}. We provide alt text because all images should be described for accessibility. #### HTML @@ -416,14 +405,8 @@ div { } #replaced { - content: linear-gradient(#639f, #c96a); -} - -@supports (content: linear-gradient(#000, #fff) / "alt text") { - #replaced { - content: repeating-linear-gradient(blue 0, orange 10%) / - "Gradients and alt text are supported"; - } + content: repeating-linear-gradient(blue 0, orange 10%) / + "Gradients and alt text are supported"; } ``` @@ -431,16 +414,16 @@ div { {{EmbedLiveSample('Element_replacement_with_gradient', '100%', 200)}} -Check the [browser compatibility chart](#browser_compatibility). All browsers support gradients and all browsers support replacing elements with images, but not all browsers support gradients as a `content` value and not all browsers support alt text on replacements. If the browser displays a box with no gradient, replacing elements is supported, but gradients are not supported as a content replacement value. If the element is replaced with a striped gradient, the browser supports both. +Check the [browser compatibility chart](#browser_compatibility). All browsers support gradients and all browsers support replacing elements with images, but not all browsers support gradients as a `content` value. ### Element replacement with `image-set()` -This example replaces an element's content with a {{cssxref("image/image-set", "image-set()")}}. If the users display has normal resolution the `1x.png` will be displayed screens with a higher resolution will display the `2x.png` image. +This example replaces an element's content with a {{cssxref("image/image-set", "image-set()")}}. If the users display has normal resolution the `1x.png` will be displayed. Screens with a higher resolution will display the `2x.png` image. #### HTML ```html -<div id="replaced">Mozilla</div> +<div id="replaced">I disappear!</div> ``` #### CSS @@ -457,7 +440,7 @@ div { content: image-set( "1x.png" 1x, "2x.png" 2x - ); + ) / "DPI"; } ``` @@ -478,13 +461,15 @@ div { - {{Cssxref("::after")}} - {{Cssxref("::before")}} - {{Cssxref("::marker")}} +- {{cssxref("::scroll-button()")}} +- {{cssxref("::scroll-marker")}} +- {{cssxref(":target-current")}} - {{Cssxref("contain")}} - {{Cssxref("quotes")}} - {{cssxref("gradient", "&lt;gradient&gt;")}} - {{cssxref("image/image-set", "image-set()")}} - {{cssxref("url_value", "&lt;url&gt;")}} -- [Replaced elements](/en-US/docs/Web/CSS/Replaced_element) +- {{glossary("Replaced elements")}} - [CSS generated content](/en-US/docs/Web/CSS/CSS_generated_content) module - [CSS lists and counters](/en-US/docs/Web/CSS/CSS_lists) module - - Browser accessibility panels: [Firefox Accessibility inspector](https://firefox-source-docs.mozilla.org/devtools-user/accessibility_inspector/), [Chrome Accessibility pane](https://developer.chrome.com/docs/devtools/accessibility/reference#pane), and [Safari Accessibility tree](https://webflow.com/glossary/accessibility-tree#:~:text=To%20view%20a%20website%E2%80%99s%20accessibility%20tree%20in%20Safari) diff --git a/files/en-us/web/css/counter-increment/index.md b/files/en-us/web/css/counter-increment/index.md index f80eec65550fd3e..d4c40ea082c008a 100644 --- a/files/en-us/web/css/counter-increment/index.md +++ b/files/en-us/web/css/counter-increment/index.md @@ -13,7 +13,40 @@ If a named counter in the list of space-separated counters and values doesn't ex The counter's value can be reset to any integer value with the {{cssxref("counter-reset")}} CSS property. -{{EmbedInteractiveExample("pages/css/counter-increment.html")}} +{{InteractiveExample("CSS Demo: counter-increment")}} + +```css interactive-example-choice +counter-increment: example-counter; +``` + +```css interactive-example-choice +counter-increment: example-counter 0; +``` + +```css interactive-example-choice +counter-increment: example-counter 5; +``` + +```css interactive-example-choice +counter-increment: example-counter -5; +``` + +```html interactive-example +<section class="default-example" id="default-example"> + <div class="transition-all" id="example-element">Counter value:</div> +</section> +``` + +```css interactive-example +#default-example { + text-align: left; + counter-reset: example-counter; +} + +#example-element::after { + content: counter(example-counter); +} +``` ## Syntax diff --git a/files/en-us/web/css/counter-reset/index.md b/files/en-us/web/css/counter-reset/index.md index f879a4c0d7f2615..127870b790bade3 100644 --- a/files/en-us/web/css/counter-reset/index.md +++ b/files/en-us/web/css/counter-reset/index.md @@ -9,7 +9,60 @@ browser-compat: css.properties.counter-reset The **`counter-reset`** [CSS](/en-US/docs/Web/CSS) property creates named [CSS counters](/en-US/docs/Web/CSS/CSS_counter_styles/Using_CSS_counters) and initializes them to a specific value. It supports creating counters that count up from one to the number of elements, as well as those that count down from the number of elements to one. -{{EmbedInteractiveExample("pages/css/counter-reset.html")}} +{{InteractiveExample("CSS Demo: counter-reset")}} + +```css interactive-example-choice +counter-reset: none; +``` + +```css interactive-example-choice +counter-reset: chapter-count 0; +``` + +```css interactive-example-choice +counter-reset: chapter-count; +``` + +```css interactive-example-choice +counter-reset: chapter-count 5; +``` + +```css interactive-example-choice +counter-reset: chapter-count -5; +``` + +```html interactive-example +<section class="default-example" id="default-example"> + <div class="transition-all" id="chapters"> + <h1>Alice's Adventures in Wonderland</h1> + <h2>Down the Rabbit-Hole</h2> + <h2 id="example-element">The Pool of Tears</h2> + <h2>A Caucus-Race and a Long Tale</h2> + <h2>The Rabbit Sends in a Little Bill</h2> + </div> +</section> +``` + +```css interactive-example +#default-example { + text-align: left; + counter-reset: chapter-count; +} + +#example-element { + background-color: lightblue; + color: black; +} + +h2 { + counter-increment: chapter-count; + font-size: 1em; +} + +h2::before { + content: "Chapter " counters(chapter-count, ".") ": "; +} +``` ## Syntax @@ -133,7 +186,7 @@ ol { {{EmbedLiveSample("Overriding the list-item counter", 140, 300)}} -Using `counter-reset`, we set the implicit `list-item` counter to start counting at `3` for every `ol`. Then, the first item would be numbered 4, second would be numbered 5, etc., similar to the effect of writing [`<ol start="4">`](/en-US/docs/Web/HTML/Element/ol#start) in HTML. +Using `counter-reset`, we set the implicit `list-item` counter to start counting at `3` for every `ol`. Then, the first item would be numbered 4, second would be numbered 5, etc., similar to the effect of writing [`<ol start="4">`](/en-US/docs/Web/HTML/Reference/Elements/ol#start) in HTML. ### Using a reverse counter diff --git a/files/en-us/web/css/counter-set/index.md b/files/en-us/web/css/counter-set/index.md index ce5fa5248a12340..98d3697e9b8a92a 100644 --- a/files/en-us/web/css/counter-set/index.md +++ b/files/en-us/web/css/counter-set/index.md @@ -13,7 +13,60 @@ If the counters don't exist the `counter-set` property creates a new counter for If a named counter in the list is missing a value, the value of the counter will be set to `0`. -{{EmbedInteractiveExample("pages/css/counter-set.html")}} +{{InteractiveExample("CSS Demo: counter-set")}} + +```css interactive-example-choice +counter-set: none; +``` + +```css interactive-example-choice +counter-set: chapter-count 0; +``` + +```css interactive-example-choice +counter-set: chapter-count; +``` + +```css interactive-example-choice +counter-set: chapter-count 5; +``` + +```css interactive-example-choice +counter-set: chapter-count -5; +``` + +```html interactive-example +<section class="default-example" id="default-example"> + <div class="transition-all" id="chapters"> + <h1>Alice's Adventures in Wonderland</h1> + <h2>Down the Rabbit-Hole</h2> + <h2 id="example-element">The Pool of Tears</h2> + <h2>A Caucus-Race and a Long Tale</h2> + <h2>The Rabbit Sends in a Little Bill</h2> + </div> +</section> +``` + +```css interactive-example +#default-example { + text-align: left; + counter-set: chapter-count; +} + +#example-element { + background-color: #37077c; + color: white; +} + +h2 { + counter-increment: chapter-count; + font-size: 1em; +} + +h2::before { + content: "Chapter " counter(chapter-count) ": "; +} +``` > [!NOTE] > The counter's value can be incremented or decremented using the {{cssxref("counter-increment")}} CSS property. diff --git a/files/en-us/web/css/counter/index.md b/files/en-us/web/css/counter/index.md index 4a166349c2bddb2..3fbd626bb091ee7 100644 --- a/files/en-us/web/css/counter/index.md +++ b/files/en-us/web/css/counter/index.md @@ -58,7 +58,7 @@ The `counter()` function accepts up to two parameters. The first parameter is th - `<counter-name>` - : A {{cssxref("&lt;custom-ident&gt;")}} identifying the counter, which is the same case-sensitive name used with the {{cssxref("counter-reset")}} and {{cssxref("counter-increment")}} property values. The counter name cannot start with two dashes and can't be `none`, `unset`, `initial`, or `inherit`. - `<counter-style>` - - : A {{cssxref("&lt;list-style-type&gt;")}} name, {{cssxref("&lt;@counter-style&gt;")}} name or {{cssxref("symbols", "symbols()")}} function, where a counter style name is a `numeric`, `alphabetic`, or `symbolic` simple predefined counter style, a complex longhand east Asian or Ethiopic predefined counter style, or other [predefined counter style](/en-US/docs/Web/CSS/CSS_counter_styles). If omitted, the counter-style defaults to `decimal`. + - : A {{cssxref("&lt;list-style-type&gt;")}} name, {{cssxref("&lt;@counter-style&gt;")}} name or {{cssxref("symbols", "symbols()")}} function, where a counter style name is a `numeric`, `alphabetic`, or `symbolic` predefined counter style, a complex longhand east Asian or Ethiopic predefined counter style, or other [predefined counter style](/en-US/docs/Web/CSS/CSS_counter_styles). If omitted, the counter-style defaults to `decimal`. > [!NOTE] > To join the counter values when nesting counters, use the {{cssxref("counters", "counters()")}} function, which provides an additional {{cssxref("string")}} parameter. diff --git a/files/en-us/web/css/counters/index.md b/files/en-us/web/css/counters/index.md index 85dfc7943c48671..3e15743247b2e3b 100644 --- a/files/en-us/web/css/counters/index.md +++ b/files/en-us/web/css/counters/index.md @@ -56,7 +56,7 @@ li::before { ## Syntax ```css -/* Simple usage - style defaults to decimal */ +/* Basic usage - style defaults to decimal */ counters(counter-name, '.'); /* changing the counter display */ @@ -74,7 +74,7 @@ The `counters()` function accepts two or three parameters. The first parameter i - {{cssxref("&lt;string&gt;")}} - : Any number of text characters. Non-Latin characters must be encoded using their Unicode escape sequences: for example, `\000A9` represents the copyright symbol. - `<counter-style>` - - : A counter style name or a [`symbols()`](/en-US/docs/Web/CSS/symbols) function. The counter style name can be a simple predefined style such as numeric, alphabetic, or symbolic, a complex longhand predefined style such as East Asian or Ethiopic, or another [predefined counter style](/en-US/docs/Web/CSS/CSS_counter_styles). If omitted, the counter-style defaults to decimal. + - : A counter style name or a [`symbols()`](/en-US/docs/Web/CSS/symbols) function. The counter style name can be a predefined style such as numeric, alphabetic, or symbolic, a complex longhand predefined style such as East Asian or Ethiopic, or another [predefined counter style](/en-US/docs/Web/CSS/CSS_counter_styles). If omitted, the counter-style defaults to decimal. The return value is a string containing all the values of all the counters in the element's CSS counters set named `<counter-name>` in the counter style defined by `<counter-style>` (or decimal, if omitted). The return string is sorted in outermost-first to innermost-last order, joined by the `<string>` specified. diff --git a/files/en-us/web/css/cross-fade/index.md b/files/en-us/web/css/cross-fade/index.md index 7c466a6cbdf9053..d68d3cd3aae10b6 100644 --- a/files/en-us/web/css/cross-fade/index.md +++ b/files/en-us/web/css/cross-fade/index.md @@ -8,7 +8,7 @@ browser-compat: css.types.image.cross-fade {{CSSRef}} The **`cross-fade()`** [CSS](/en-US/docs/Web/CSS) [function](/en-US/docs/Web/CSS/CSS_Values_and_Units/CSS_Value_Functions) can be used to blend two or more images at a defined transparency. -It can be used for many simple image manipulations, such as tinting an image with a solid color or highlighting a particular area of the page by combining an image with a radial gradient. +It can be used for many basic image manipulations, such as tinting an image with a solid color or highlighting a particular area of the page by combining an image with a radial gradient. ## Syntax @@ -96,7 +96,7 @@ Browsers do not provide any special information on background images to assistiv If the image contains information critical to understanding the page's overall purpose, it is better to describe it semantically in the document. When using background images, make sure the contrast in color is great enough that any text is legible over the image as well as if the images are missing. -- [MDN Understanding WCAG, Guideline 1.1 explanations](/en-US/docs/Web/Accessibility/Understanding_WCAG/Perceivable#guideline_1.1_—_providing_text_alternatives_for_non-text_content) +- [MDN Understanding WCAG, Guideline 1.1 explanations](/en-US/docs/Web/Accessibility/Guides/Understanding_WCAG/Perceivable#guideline_1.1_—_providing_text_alternatives_for_non-text_content) - [Understanding Success Criterion 1.1.1 | W3C Understanding WCAG 2.0](https://www.w3.org/TR/UNDERSTANDING-WCAG20/text-equiv-all.html) ## Formal syntax @@ -110,13 +110,13 @@ When using background images, make sure the contrast in color is great enough th #### HTML ```html -<div class="crossfade"></div> +<div class="cross-fade"></div> ``` #### CSS ```css -.crossfade { +.cross-fade { width: 300px; height: 300px; background-image: -webkit-cross-fade(url("br.png"), url("tr.png"), 75%); diff --git a/files/en-us/web/css/css_anchor_positioning/index.md b/files/en-us/web/css/css_anchor_positioning/index.md index 4d7758f8ceef2a6..fd9bbd48c2fcebf 100644 --- a/files/en-us/web/css/css_anchor_positioning/index.md +++ b/files/en-us/web/css/css_anchor_positioning/index.md @@ -49,7 +49,7 @@ In addition, the specification provides CSS-only mechanisms to: ### HTML attributes -- [`anchor`](/en-US/docs/Web/HTML/Global_attributes/anchor) {{non-standard_inline}} +- [`anchor`](/en-US/docs/Web/HTML/Reference/Global_attributes/anchor) {{non-standard_inline}} ### Interfaces @@ -121,6 +121,7 @@ In addition, the specification provides CSS-only mechanisms to: ## See also +- [CSS scroll anchoring](/en-US/docs/Web/CSS/CSS_scroll_anchoring) module - [Learn: CSS positioning](/en-US/docs/Learn_web_development/Core/CSS_layout/Positioning) - [CSS logical properties and values](/en-US/docs/Web/CSS/CSS_logical_properties_and_values) module - [Learn: Sizing items in CSS](/en-US/docs/Learn_web_development/Core/Styling_basics/Sizing) diff --git a/files/en-us/web/css/css_anchor_positioning/try_options_hiding/index.md b/files/en-us/web/css/css_anchor_positioning/try_options_hiding/index.md index 159f1a1a7f19eff..e275db083e05b78 100644 --- a/files/en-us/web/css/css_anchor_positioning/try_options_hiding/index.md +++ b/files/en-us/web/css/css_anchor_positioning/try_options_hiding/index.md @@ -265,7 +265,7 @@ The `descriptor-list` defines the property values for that individual custom try - {{cssxref("position-area")}} - [Inset properties](/en-US/docs/Glossary/Inset_properties) -- Margin properties (e.g. {{cssxref("margin-left")}}, {{cssxref("margin-block-start")}}) +- Margin properties (e.g., {{cssxref("margin-left")}}, {{cssxref("margin-block-start")}}) - [self-alignment](/en-US/docs/Web/CSS/CSS_anchor_positioning/Using#centering_on_the_anchor_using_anchor-center) properties - Sizing properties ({{cssxref("width")}}, {{cssxref("block-size")}}, etc.) - {{cssxref("position-anchor")}} diff --git a/files/en-us/web/css/css_anchor_positioning/using/index.md b/files/en-us/web/css/css_anchor_positioning/using/index.md index 9a79f9c5feb7f08..800796d8e678ed1 100644 --- a/files/en-us/web/css/css_anchor_positioning/using/index.md +++ b/files/en-us/web/css/css_anchor_positioning/using/index.md @@ -23,7 +23,7 @@ It's very common to want to tether, or bind, one element to another. For example Modern interfaces frequently call for some content — often reusable and dynamically-generated — to be situated relative to an anchor element. Creating such use cases would be fairly straightforward if the element to tether to (aka the **anchor element**) was always in the same place in the UI and the tethered element (aka the **anchor-positioned element**, or just **positioned element**) could always be placed immediately before or after it in the source order. However, things are rarely that simple. -The location of positioned elements relative to their anchor element needs to be maintained and adjusted as the anchor element moves or otherwise changes configuration (e.g. by scrolling, changing the viewport size, drag and drop, etc.). For example, if an element such as a form field gets close to the edge of the viewport, its tooltip may end up offscreen. Generally, you want to bind the tooltip to its form control and ensure the tooltip is kept fully visible on-screen as long as the form field is visible, automatically moving the tooltip if needed. You may have noticed this as the default behavior in your operating system when you right-click (<kbd>Ctrl</kbd> + click) context menus on your desktop or laptop. +The location of positioned elements relative to their anchor element needs to be maintained and adjusted as the anchor element moves or otherwise changes configuration (e.g., by scrolling, changing the viewport size, drag and drop, etc.). For example, if an element such as a form field gets close to the edge of the viewport, its tooltip may end up offscreen. Generally, you want to bind the tooltip to its form control and ensure the tooltip is kept fully visible on-screen as long as the form field is visible, automatically moving the tooltip if needed. You may have noticed this as the default behavior in your operating system when you right-click (<kbd>Ctrl</kbd> + click) context menus on your desktop or laptop. Historically, associating an element with another element and dynamically changing a positioned element's location and size based on an anchor's position required JavaScript, which added complexity and performance issues. It also wasn't guaranteed to work in all situations. The features defined in the [CSS anchor positioning](/en-US/docs/Web/CSS/CSS_anchor_positioning) module enable implementing such use cases performantly and declaratively with CSS (and HTML) instead of JavaScript. @@ -94,8 +94,9 @@ The anchor and infobox are now associated, but for the moment you'll have to tru In some cases, an implicit anchor reference will be made between two elements, due to the semantic nature of their relationship. For example, when using the [Popover API](/en-US/docs/Web/API/Popover_API) to associate a popover with a control, an implicit anchor reference is made between the two. This can occur when: -- Declaratively associating a popover with a control using the [`popovertarget`](/en-US/docs/Web/HTML/Element/button#popovertarget) and [`id`](/en-US/docs/Web/HTML/Global_attributes/id) attributes. +- Declaratively associating a popover with a control using the [`popovertarget`](/en-US/docs/Web/HTML/Reference/Elements/button#popovertarget) and [`id`](/en-US/docs/Web/HTML/Reference/Global_attributes/id) attributes. - Programmatically associating a popover action such as {{domxref("HTMLElement.showPopover", "showPopover()")}} with a control using the `source` option. +- A {{htmlelement("select")}} element and its dropdown picker are opted into [customizable select element](/en-US/docs/Learn_web_development/Extensions/Forms/Customizable_select) functionality via the {{cssxref("appearance")}} property `base-select` value. In this case, an implicit popover-invoker relationship is created between the two, which also means they'll have an implicit anchor reference. > [!NOTE] > The methods above associate an anchor with an element, but they are not yet tethered. To tether them together, the positioned element needs to be positioned relative to its anchor, which is done with CSS. @@ -121,7 +122,7 @@ anchor(<anchor-name> <anchor-side>, <fallback>) - `<anchor-name>` - - : The [`anchor-name`](/en-US/docs/Web/CSS/anchor-name) property value of the anchor element you want to position the element's side relative to. This is a `<dashed-ident>` value. If omitted, the element's **default anchor** is used. This is the anchor referenced in its [`position-anchor`](/en-US/docs/Web/CSS/position-anchor) property, or associated with the element via the non-standard [`anchor`](/en-US/docs/Web/HTML/Global_attributes/anchor) HTML attribute. + - : The [`anchor-name`](/en-US/docs/Web/CSS/anchor-name) property value of the anchor element you want to position the element's side relative to. This is a `<dashed-ident>` value. If omitted, the element's **default anchor** is used. This is the anchor referenced in its [`position-anchor`](/en-US/docs/Web/CSS/position-anchor) property, or associated with the element via the non-standard [`anchor`](/en-US/docs/Web/HTML/Reference/Global_attributes/anchor) HTML attribute. > [!NOTE] > Specifying an `<anchor-name>` positions the element relative to that anchor, but does not provide element association. While you can position an element's sides relative to multiple anchors by specifying [different `<anchor-name>` values](/en-US/docs/Web/CSS/anchor#positioning_an_element_relative_to_multiple_anchors) inside different `anchor()` functions on the same element, the positioned element is only associated with a single anchor. @@ -558,7 +559,7 @@ This rule sizes the positioned element's inline size to 4 times the anchor eleme } ``` -Let's look at an example. The HTML and base CSS are the same as in the previous examples, except that the anchor element is given a [`tabindex="0"`](/en-US/docs/Web/HTML/Global_attributes/tabindex) attribute to make it focusable. The infobox is given fixed positioning and associated with the anchor in the same way as before. However, this time around we tether it to the right of the anchor using a `position-area`, and give it a width five times the width of the anchor's width: +Let's look at an example. The HTML and base CSS are the same as in the previous examples, except that the anchor element is given a [`tabindex="0"`](/en-US/docs/Web/HTML/Reference/Global_attributes/tabindex) attribute to make it focusable. The infobox is given fixed positioning and associated with the anchor in the same way as before. However, this time around we tether it to the right of the anchor using a `position-area`, and give it a width five times the width of the anchor's width: ```html hidden <p> @@ -681,7 +682,7 @@ This can be useful in cases where you want to set an anchor-positioned element's Let's look at an example where we set an anchor-positioned element's margin and position relative to the anchor element's width. -In the HTML, we specify two {{htmlelement("div")}} elements, one `anchor` element and one `infobox` element that we'll position relative to the anchor. We give the anchor element a [`tabindex`](/en-US/docs/Web/HTML/Global_attributes/tabindex) attribute so that it can be focused via the keyboard. We also include filler text to make the {{htmlelement("body")}} tall enough to require scrolling, but this has been hidden for the sake of brevity. +In the HTML, we specify two {{htmlelement("div")}} elements, one `anchor` element and one `infobox` element that we'll position relative to the anchor. We give the anchor element a [`tabindex`](/en-US/docs/Web/HTML/Reference/Global_attributes/tabindex) attribute so that it can be focused via the keyboard. We also include filler text to make the {{htmlelement("body")}} tall enough to require scrolling, but this has been hidden for the sake of brevity. ```html hidden <p>Lorem ipsum dolor sit amet, consectetur adipiscing elit.</p> diff --git a/files/en-us/web/css/css_animations/index.md b/files/en-us/web/css/css_animations/index.md index 746081e4edd71ca..18999333c9c72f0 100644 --- a/files/en-us/web/css/css_animations/index.md +++ b/files/en-us/web/css/css_animations/index.md @@ -16,7 +16,7 @@ The **CSS animations** module lets you animate the values of CSS properties, suc To view the animation in the box below, click the checkbox 'Play the animation' or hover the cursor over the box. When the animating is active, the cloud at the top changes shape, snowflakes fall, and the snow level at the bottom rises. To pause the animation, uncheck the checkbox or move your cursor away from the box. ```html hidden live-sample___animation -<!-- See aria-label: https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-label --> +<!-- See aria-label: https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-label --> <input type="checkbox" id="animate" diff --git a/files/en-us/web/css/css_animations/using_css_animations/index.md b/files/en-us/web/css/css_animations/using_css_animations/index.md index c8a8ed9714d25c6..647d09fc095c215 100644 --- a/files/en-us/web/css/css_animations/using_css_animations/index.md +++ b/files/en-us/web/css/css_animations/using_css_animations/index.md @@ -10,7 +10,7 @@ page-type: guide There are three key advantages to CSS animations over traditional script-driven animation techniques: -1. They're easy to use for simple animations; you can create them without even having to know JavaScript. +1. They're easy to use for basic animations; you can create them without even having to know JavaScript. 2. The animations run well, even under moderate system load. Simple animations can often perform poorly in JavaScript. The rendering engine can use frame-skipping and other techniques to keep the performance as smooth as possible. 3. Letting the browser control the animation sequence lets the browser optimize performance and efficiency by, for example, reducing the update frequency of animations running in tabs that aren't currently visible. diff --git a/files/en-us/web/css/css_basic_user_interface/index.md b/files/en-us/web/css/css_basic_user_interface/index.md index 8b9dd2f35686f40..b4cd5a784fa59e9 100644 --- a/files/en-us/web/css/css_basic_user_interface/index.md +++ b/files/en-us/web/css/css_basic_user_interface/index.md @@ -111,7 +111,7 @@ Click "Play" in the example above to see or edit the code for the animation in t ## Related concepts - CSS [`cursor`](/en-US/docs/Web/CSS/cursor) property -- SVG [`cursor`](/en-US/docs/Web/SVG/Attribute/cursor) attribute +- SVG [`cursor`](/en-US/docs/Web/SVG/Reference/Attribute/cursor) attribute - CSS {{CSSxRef(":focus")}}, {{CSSxRef(":focus-within")}}, and {{CSSxRef(":focus-visible")}} pseudoclasses - {{DOMXref("CaretPosition")}} Interface diff --git a/files/en-us/web/css/css_box_alignment/box_alignment/index.md b/files/en-us/web/css/css_box_alignment/box_alignment/index.md index ca772622aac21b0..9f14da90bc81df6 100644 --- a/files/en-us/web/css/css_box_alignment/box_alignment/index.md +++ b/files/en-us/web/css/css_box_alignment/box_alignment/index.md @@ -54,9 +54,9 @@ The below image shows an alignment container with two alignment subjects inside. There are three different types of alignment that the specification details; these use keyword values. -- [Positional alignment](#positional-alignment) -- [Baseline alignment](#baseline-alignment) -- [Distributed alignment](#distributed-alignment) +- [Positional alignment](#positional_alignment) +- [Baseline alignment](#baseline_alignment) +- [Distributed alignment](#distributed_alignment) ### Positional alignment diff --git a/files/en-us/web/css/css_box_alignment/box_alignment_in_block_abspos_tables/index.md b/files/en-us/web/css/css_box_alignment/box_alignment_in_block_abspos_tables/index.md index f5f57d0bdb8f610..49858fdd08e91a9 100644 --- a/files/en-us/web/css/css_box_alignment/box_alignment_in_block_abspos_tables/index.md +++ b/files/en-us/web/css/css_box_alignment/box_alignment_in_block_abspos_tables/index.md @@ -4,6 +4,8 @@ slug: Web/CSS/CSS_box_alignment/Box_alignment_in_block_abspos_tables page-type: guide --- +{{CSSRef}} + The [CSS box alignment](/en-US/docs/Web/CSS/CSS_box_alignment) module details how alignment works in various layout methods. In this guide, we explore how box alignment works in the context of block layout, including floated, positioned, and table elements. As this guide aims to detail things which are specific to block layout and box alignment, it should be read in conjunction with the [box alignment](/en-US/docs/Web/CSS/CSS_box_alignment/Box_alignment) guide, which details the common features of box alignment across layout methods. ## align-content and justify-content diff --git a/files/en-us/web/css/css_box_alignment/box_alignment_in_flexbox/index.md b/files/en-us/web/css/css_box_alignment/box_alignment_in_flexbox/index.md index c44819db54f7924..559e95d243444fc 100644 --- a/files/en-us/web/css/css_box_alignment/box_alignment_in_flexbox/index.md +++ b/files/en-us/web/css/css_box_alignment/box_alignment_in_flexbox/index.md @@ -12,15 +12,10 @@ The [box alignment](/en-US/docs/Web/CSS/CSS_box_alignment) module details how al In this flexbox example, three flex items are aligned on the main axis using {{cssxref("justify-content")}} and on the cross axis using {{cssxref("align-items")}}. The first item overrides the `align-items` values set on the group by setting {{cssxref("align-self")}} to `center`. -```html live-sample___flex-align-items -<div class="box"> - <div>One</div> - <div>Two</div> - <div>Three <br />has <br />extra <br />text</div> -</div> -``` - -```css hidden live-sample___flex-align-items +```css hidden live-sample___gap live-sample___flex-align-items live-sample___auto-margins +body { + font-family: sans-serif; +} .box > * { padding: 20px; border: 2px solid rgb(96 139 168); @@ -29,6 +24,14 @@ In this flexbox example, three flex items are aligned on the main axis using {{c } ``` +```html live-sample___flex-align-items +<div class="box"> + <div>One</div> + <div>Two</div> + <div>Three <br />has <br />extra <br />text</div> +</div> +``` + ```css live-sample___flex-align-items .box { display: flex; @@ -87,15 +90,6 @@ By setting a {{cssxref("margin")}} of `auto` on one item in a set of flex items </div> ``` -```css hidden live-sample___auto-margins -.box > * { - padding: 20px; - border: 2px solid rgb(96 139 168); - border-radius: 5px; - background-color: rgb(96 139 168 / 0.2); -} -``` - ```css live-sample___auto-margins .box { display: flex; @@ -131,15 +125,6 @@ On the cross axis the `row-gap` property creates spacing between adjacent flex l </div> ``` -```css hidden live-sample___gap -.box > * { - padding: 20px; - border: 2px solid rgb(96 139 168); - border-radius: 5px; - background-color: rgb(96 139 168 / 0.2); -} -``` - ```css live-sample___gap .box { width: 450px; diff --git a/files/en-us/web/css/css_box_alignment/box_alignment_in_grid_layout/index.md b/files/en-us/web/css/css_box_alignment/box_alignment_in_grid_layout/index.md index a82492ee885bc78..246502d7078d06a 100644 --- a/files/en-us/web/css/css_box_alignment/box_alignment_in_grid_layout/index.md +++ b/files/en-us/web/css/css_box_alignment/box_alignment_in_grid_layout/index.md @@ -14,7 +14,44 @@ As this guide aims to detail things which are specific to CSS grid layout and Bo In this example using [grid layout](/en-US/docs/Web/CSS/CSS_grid_layout/Basic_concepts_of_grid_layout), there is extra space in the {{glossary("grid container")}} after laying out the fixed-width tracks on the inline {{glossary("main axis")}}. This space is distributed using {{cssxref("justify-content")}}. On the block {{glossary("cross axis")}} the alignment of the items inside their grid areas is controlled with {{cssxref("align-items")}}. The first item overrides the `align-items` value set on the group by setting {{cssxref("align-self")}} to `center`. -{{EmbedGHLiveSample("css-examples/box-alignment/overview/grid-align-items.html", '100%', 500)}} +```html live-sample___grid-align-items +<div class="box"> + <div>One</div> + <div>Two</div> + <div>Three <br />has <br />extra <br />text</div> + <div>Four</div> + <div>Five</div> + <div>Six</div> +</div> +``` + +```css hidden live-sample___grid-align-items +body { + font-family: sans-serif; +} +.box > * { + padding: 20px; + border: 2px solid rgb(96 139 168); + border-radius: 5px; + background-color: rgb(96 139 168 / 0.2); +} +``` + +```css live-sample___grid-align-items +.box { + display: grid; + grid-template-columns: 120px 120px 120px; + align-items: start; + justify-content: space-between; + border: 2px dotted rgb(96 139 168); +} + +.box :first-child { + align-self: center; +} +``` + +{{EmbedLiveSample("grid-align-items", , 200)}} ## Grid axes diff --git a/files/en-us/web/css/css_box_model/index.md b/files/en-us/web/css/css_box_model/index.md index 43b2fddf30fb15d..2e02cc028728701 100644 --- a/files/en-us/web/css/css_box_model/index.md +++ b/files/en-us/web/css/css_box_model/index.md @@ -9,7 +9,7 @@ spec-urls: https://drafts.csswg.org/css-box-4/ The **CSS box model** module defines the `margin` and `padding` properties, which along with the [height](/en-US/docs/Web/CSS/CSS_box_sizing), [width](/en-US/docs/Web/CSS/CSS_box_sizing) and [border properties](/en-US/docs/Web/CSS/CSS_backgrounds_and_borders), make up the CSS [box model](/en-US/docs/Web/CSS/CSS_box_model/Introduction_to_the_CSS_box_model). -Every visible element on a webpage is a box laid out according to the [visual formatting model](/en-US/docs/Web/CSS/Visual_formatting_model). CSS properties define their size, position, and stacking level, with the box model properties (and others) defining the extrinsic size of each box, and the space around them. +Every visible element on a webpage is a box laid out according to the [visual formatting model](/en-US/docs/Web/CSS/CSS_display/Visual_formatting_model). CSS properties define their size, position, and stacking level, with the box model properties (and others) defining the extrinsic size of each box, and the space around them. Each box has a rectangular content area, inside which any text, images, and other content is displayed. The content may be surrounded by padding, a border, and a margin, on one or more sides. The padding is around the content, the border is around the padding, and the margin sits outside the border. The box model describes how these features — the content, padding, border, and margin — work together to create a box as displayed by CSS. @@ -52,7 +52,7 @@ The CSS box model module defines physical (or "page relative") properties such a - : Sometimes, two adjacent margins are collapsed into one. This article describes the rules that govern when and why this happens, and how to control it. -- [Visual formatting model](/en-US/docs/Web/CSS/Visual_formatting_model) +- [Visual formatting model](/en-US/docs/Web/CSS/CSS_display/Visual_formatting_model) - : Explains the visual formatting model. diff --git a/files/en-us/web/css/css_box_model/introduction_to_the_css_box_model/index.md b/files/en-us/web/css/css_box_model/introduction_to_the_css_box_model/index.md index 6dc49a70d000eb7..dcd5302646c42fc 100644 --- a/files/en-us/web/css/css_box_model/introduction_to_the_css_box_model/index.md +++ b/files/en-us/web/css/css_box_model/introduction_to_the_css_box_model/index.md @@ -28,7 +28,7 @@ The thickness of the padding is determined by the {{cssxref("padding-top")}}, {{ The **border area**, bounded by the border edge, extends the padding area to include the element's borders. Its dimensions are the _border-box width_ and the _border-box height_. -The thickness of the borders are determined by the {{cssxref("border-width")}} and shorthand {{cssxref("border")}} properties. If the {{cssxref("box-sizing")}} property is set to `border-box`, the border area's size can be explicitly defined with the {{cssxref("width")}}, {{cssxref("min-width")}}, {{cssxref("max-width")}}, {{ cssxref("height") }}, {{cssxref("min-height")}}, and {{cssxref("max-height")}} properties. When there is a background ({{cssxref("background-color")}} or {{cssxref("background-image")}}) set on a box, it extends to the outer edge of the border (i.e. extends underneath the border in z-ordering). This default behavior can be altered with the {{cssxref("background-clip")}} CSS property. +The thickness of the borders are determined by the {{cssxref("border-width")}} and shorthand {{cssxref("border")}} properties. If the {{cssxref("box-sizing")}} property is set to `border-box`, the border area's size can be explicitly defined with the {{cssxref("width")}}, {{cssxref("min-width")}}, {{cssxref("max-width")}}, {{ cssxref("height") }}, {{cssxref("min-height")}}, and {{cssxref("max-height")}} properties. When there is a background ({{cssxref("background-color")}} or {{cssxref("background-image")}}) set on a box, it extends to the outer edge of the border (i.e., extends underneath the border in z-ordering). This default behavior can be altered with the {{cssxref("background-clip")}} CSS property. ## Margin area @@ -49,14 +49,14 @@ Finally, note that for non-replaced inline elements, the amount of space taken u - [Comments](/en-US/docs/Web/CSS/CSS_syntax/Comments) - [Specificity](/en-US/docs/Web/CSS/CSS_cascade/Specificity) - [Inheritance](/en-US/docs/Web/CSS/CSS_cascade/Inheritance) - - [Layout modes](/en-US/docs/Web/CSS/Layout_mode) - - [Visual formatting model](/en-US/docs/Web/CSS/Visual_formatting_model) + - [Layout modes](/en-US/docs/Glossary/Layout_mode) + - [Visual formatting model](/en-US/docs/Web/CSS/CSS_display/Visual_formatting_model) - [Margin collapsing](/en-US/docs/Web/CSS/CSS_box_model/Mastering_margin_collapsing) - Values - - [Initial values](/en-US/docs/Web/CSS/CSS_cascade/initial_value) - - [Computed values](/en-US/docs/Web/CSS/CSS_cascade/computed_value) - - [Used values](/en-US/docs/Web/CSS/CSS_cascade/used_value) - - [Actual values](/en-US/docs/Web/CSS/CSS_cascade/actual_value) + - [Initial values](/en-US/docs/Web/CSS/CSS_cascade/Value_processing#initial_value) + - [Computed values](/en-US/docs/Web/CSS/CSS_cascade/Value_processing#computed_value) + - [Used values](/en-US/docs/Web/CSS/CSS_cascade/Value_processing#used_value) + - [Actual values](/en-US/docs/Web/CSS/CSS_cascade/Value_processing#actual_value) - [Value definition syntax](/en-US/docs/Web/CSS/CSS_Values_and_Units/Value_definition_syntax) - [Shorthand properties](/en-US/docs/Web/CSS/CSS_cascade/Shorthand_properties) - - [Replaced elements](/en-US/docs/Web/CSS/Replaced_element) + - {{glossary("Replaced elements")}} diff --git a/files/en-us/web/css/css_box_model/mastering_margin_collapsing/index.md b/files/en-us/web/css/css_box_model/mastering_margin_collapsing/index.md index 36424e53b82d1e3..cc9e99b73c5c671 100644 --- a/files/en-us/web/css/css_box_model/mastering_margin_collapsing/index.md +++ b/files/en-us/web/css/css_box_model/mastering_margin_collapsing/index.md @@ -79,13 +79,13 @@ p { - [Specificity](/en-US/docs/Web/CSS/CSS_cascade/Specificity) - [Inheritance](/en-US/docs/Web/CSS/CSS_cascade/Inheritance) - [Box model](/en-US/docs/Web/CSS/CSS_box_model/Introduction_to_the_CSS_box_model) - - [Layout modes](/en-US/docs/Web/CSS/Layout_mode) - - [Visual formatting model](/en-US/docs/Web/CSS/Visual_formatting_model) + - [Layout modes](/en-US/docs/Glossary/Layout_mode) + - [Visual formatting model](/en-US/docs/Web/CSS/CSS_display/Visual_formatting_model) - Values - - [Initial values](/en-US/docs/Web/CSS/CSS_cascade/initial_value) - - [Computed values](/en-US/docs/Web/CSS/CSS_cascade/computed_value) - - [Used values](/en-US/docs/Web/CSS/CSS_cascade/used_value) - - [Actual values](/en-US/docs/Web/CSS/CSS_cascade/actual_value) + - [Initial values](/en-US/docs/Web/CSS/CSS_cascade/Value_processing#initial_value) + - [Computed values](/en-US/docs/Web/CSS/CSS_cascade/Value_processing#computed_value) + - [Used values](/en-US/docs/Web/CSS/CSS_cascade/Value_processing#used_value) + - [Actual values](/en-US/docs/Web/CSS/CSS_cascade/Value_processing#actual_value) - [Value definition syntax](/en-US/docs/Web/CSS/CSS_Values_and_Units/Value_definition_syntax) - [Shorthand properties](/en-US/docs/Web/CSS/CSS_cascade/Shorthand_properties) - - [Replaced elements](/en-US/docs/Web/CSS/Replaced_element) + - {{glossary("Replaced elements")}} diff --git a/files/en-us/web/css/css_box_sizing/index.md b/files/en-us/web/css/css_box_sizing/index.md index 4874882d26f836a..b13884e17afc272 100644 --- a/files/en-us/web/css/css_box_sizing/index.md +++ b/files/en-us/web/css/css_box_sizing/index.md @@ -73,7 +73,7 @@ The [logical properties and values module](/en-US/docs/Web/CSS/CSS_logical_prope - : Sometimes, two adjacent margins are collapsed into one. This article describes the rules that govern when and why this happens, and how to control it. -- [Visual formatting model](/en-US/docs/Web/CSS/Visual_formatting_model) +- [Visual formatting model](/en-US/docs/Web/CSS/CSS_display/Visual_formatting_model) - : Explains the visual formatting model. diff --git a/files/en-us/web/css/css_box_sizing/understanding_aspect-ratio/index.md b/files/en-us/web/css/css_box_sizing/understanding_aspect-ratio/index.md index e0c6a061899a841..dd40cdcd59de16a 100644 --- a/files/en-us/web/css/css_box_sizing/understanding_aspect-ratio/index.md +++ b/files/en-us/web/css/css_box_sizing/understanding_aspect-ratio/index.md @@ -528,7 +528,7 @@ In this example of square grid items, the grid tracks are auto-sized, taking the ```css hidden div { gap: 20px; - font-size: 1.1; + font-size: 1.1rem; } div div { @@ -590,6 +590,10 @@ For the content of a grid item to not grow beyond the preferred height set by th {{EmbedLiveSample("making_grid_cells_square", "100", "380")}} +## Specifications + +{{Specifications}} + ## See also - [CSS box sizing](/en-US/docs/Web/CSS/CSS_box_sizing) module diff --git a/files/en-us/web/css/css_cascade/actual_value/index.md b/files/en-us/web/css/css_cascade/actual_value/index.md deleted file mode 100644 index 468ce2cd74cd162..000000000000000 --- a/files/en-us/web/css/css_cascade/actual_value/index.md +++ /dev/null @@ -1,46 +0,0 @@ ---- -title: Actual value -slug: Web/CSS/CSS_cascade/actual_value -page-type: guide -spec-urls: - - https://www.w3.org/TR/CSS22/cascade.html#actual-value - - https://drafts.csswg.org/css-cascade-5/#actual-value ---- - -{{CSSRef}} - -The **actual value** of a [CSS](/en-US/docs/Web/CSS) property is the [used value](/en-US/docs/Web/CSS/CSS_cascade/used_value) of that property after any necessary approximations have been applied. For example, a {{glossary("user agent")}} that can only render borders with a whole-number pixel width may round the thickness of the border to the nearest integer. - -## Calculating a property's actual value - -The {{glossary("user agent")}} performs four steps to calculate a property's actual (final) value: - -1. First, the [specified value](/en-US/docs/Web/CSS/CSS_cascade/specified_value) is determined based on the result of [cascading](/en-US/docs/Web/CSS/CSS_cascade/Cascade), [inheritance](/en-US/docs/Web/CSS/CSS_cascade/Inheritance), or using the [initial value](/en-US/docs/Web/CSS/CSS_cascade/initial_value). -2. Next, the [computed value](/en-US/docs/Web/CSS/CSS_cascade/computed_value) is calculated according to the specification (for example, a `span` with `position: absolute` will have its computed `display` changed to `block`). -3. Then, layout is calculated, resulting in the [used value](/en-US/docs/Web/CSS/CSS_cascade/used_value). -4. Finally, the used value is transformed according to the limitations of the local environment, resulting in the actual value. - -## Specifications - -{{Specifications}} - -## See also - -- CSS key concepts: - - [CSS syntax](/en-US/docs/Web/CSS/CSS_syntax/Syntax) - - [At-rules](/en-US/docs/Web/CSS/CSS_syntax/At-rule) - - [Comments](/en-US/docs/Web/CSS/CSS_syntax/Comments) - - [Specificity](/en-US/docs/Web/CSS/CSS_cascade/Specificity) - - [Inheritance](/en-US/docs/Web/CSS/CSS_cascade/Inheritance) - - [Box model](/en-US/docs/Web/CSS/CSS_box_model/Introduction_to_the_CSS_box_model) - - [Layout modes](/en-US/docs/Web/CSS/Layout_mode) - - [Visual formatting model](/en-US/docs/Web/CSS/Visual_formatting_model) - - [Margin collapsing](/en-US/docs/Web/CSS/CSS_box_model/Mastering_margin_collapsing) - - Values - - [Initial values](/en-US/docs/Web/CSS/CSS_cascade/initial_value) - - [Computed values](/en-US/docs/Web/CSS/CSS_cascade/computed_value) - - [Used values](/en-US/docs/Web/CSS/CSS_cascade/used_value) - - [Resolved values](/en-US/docs/Web/CSS/resolved_value) - - [Value definition syntax](/en-US/docs/Web/CSS/CSS_Values_and_Units/Value_definition_syntax) - - [Shorthand properties](/en-US/docs/Web/CSS/CSS_cascade/Shorthand_properties) - - [Replaced elements](/en-US/docs/Web/CSS/Replaced_element) diff --git a/files/en-us/web/css/css_cascade/cascade/index.md b/files/en-us/web/css/css_cascade/cascade/index.md index ca2ac2ebaab8ef9..15dbce863deedd9 100644 --- a/files/en-us/web/css/css_cascade/cascade/index.md +++ b/files/en-us/web/css/css_cascade/cascade/index.md @@ -31,7 +31,7 @@ Unless the user-agent stylesheet includes an [`!important`](/en-US/docs/Web/CSS/ ### Author stylesheets -**Author stylesheets** are the most common type of stylesheet; these are the styles written by web developers. These styles can reset user-agent styles, as noted above, and define the styles for the design of a given web page or application. The author, or web developer, defines the styles for the document using one or more linked or imported stylesheets, {{HTMLElement('style')}} blocks, and inline styles defined with the [`style`](/en-US/docs/Web/HTML/Global_attributes/style) attribute. These author styles define the look and feel of the website — its theme. +**Author stylesheets** are the most common type of stylesheet; these are the styles written by web developers. These styles can reset user-agent styles, as noted above, and define the styles for the design of a given web page or application. The author, or web developer, defines the styles for the document using one or more linked or imported stylesheets, {{HTMLElement('style')}} blocks, and inline styles defined with the [`style`](/en-US/docs/Web/HTML/Reference/Global_attributes/style) attribute. These author styles define the look and feel of the website — its theme. ### User stylesheets @@ -50,16 +50,16 @@ The cascading algorithm determines how to find the value to apply for each prope 1. **Relevance**: It first filters all the rules from the different sources to keep only the rules that apply to a given element. That means rules whose selector matches the given element and which are part of an appropriate `media` at-rule. 2. **Origin and importance**: Then it sorts these rules according to their importance, that is, whether or not they are followed by `!important`, and by their origin. Ignoring layers for the moment, the cascade order is as follows: - | Precedence Order (low to high) | Origin | Importance | - | ------------------------------ | ------------------------ | ------------ | - | 1 | user-agent (browser) | normal | - | 2 | user | normal | - | 3 | author (developer) | normal | - | 4 | CSS @keyframe animations | | - | 5 | author (developer) | `!important` | - | 6 | user | `!important` | - | 7 | user-agent (browser) | `!important` | - | 8 | CSS transitions | | + | Precedence Order (low to high) | Origin | Importance | + | ------------------------------ | ----------------------- | ------------ | + | 1 | user-agent (browser) | normal | + | 2 | user | normal | + | 3 | author (developer) | normal | + | 4 | CSS keyframe animations | | + | 5 | author (developer) | `!important` | + | 6 | user | `!important` | + | 7 | user-agent (browser) | `!important` | + | 8 | CSS transitions | | 3. **Specificity**: In case of equality with an origin, the [specificity](/en-US/docs/Web/CSS/CSS_cascade/Specificity) of a rule is considered to choose one value or another. The specificity of the selectors are compared, and the declaration with the highest specificity wins. 4. **Scoping proximity**: When two selectors in the origin layer with precedence have the same specificity, the property value within scoped rules with the smallest number of hops up the DOM hierarchy to the scope root wins. See [How `@scope` conflicts are resolved](/en-US/docs/Web/CSS/@scope#how_scope_conflicts_are_resolved) for more details and an example. @@ -203,11 +203,11 @@ In this example, the author used CSS's {{CSSXref('@import')}} rule to import fiv ```html <style> - @import unlayeredStyles.css; - @import AStyles.css layer(A); - @import moreUnlayeredStyles.css; - @import BStyles.css layer(B); - @import CStyles.css layer(C); + @import "unlayeredStyles.css"; + @import "AStyles.css" layer(A); + @import "moreUnlayeredStyles.css"; + @import "BStyles.css" layer(B); + @import "CStyles.css" layer(C); p { color: red; padding: 1em !important; @@ -352,7 +352,7 @@ Finally, {{cssxref("@charset")}} obeys specific algorithms and isn't affected by Presentational attributes are attributes in the source document that can affect styling. For example, when included, the deprecated `align` attribute sets the alignment on several HTML elements and the `fill` attribute defines the color used to paint SVG shapes and text and defines the final state for SVG animations. While they are author styles, presentational attributes do not participate in the cascade. -If the HTML presentation attribute is supported by the user agent, valid presentational attributes included in HTML and SVG, such as the [`align`](/en-US/docs/Web/HTML/Element/img#align) or [`fill`](/en-US/docs/Web/SVG/Attribute/fill) attributes, are translated to the corresponding CSS rules (all SVG presentation attributes are supported as CSS properties) and inserted in the author stylesheet prior to any other styles with a specificity equal to `0`. +If the HTML presentation attribute is supported by the user agent, valid presentational attributes included in HTML and SVG, such as the [`align`](/en-US/docs/Web/HTML/Reference/Elements/img#align) or [`fill`](/en-US/docs/Web/SVG/Reference/Attribute/fill) attributes, are translated to the corresponding CSS rules (all SVG presentation attributes are supported as CSS properties) and inserted in the author stylesheet prior to any other styles with a specificity equal to `0`. Presentational attributes cannot be declared `!important`. @@ -421,4 +421,4 @@ After your content has finished altering styles, it may find itself in a situati - [Specificity](/en-US/docs/Web/CSS/CSS_cascade/Specificity) - [Inheritance](/en-US/docs/Web/CSS/CSS_cascade/Inheritance) - [At-rules](/en-US/docs/Web/CSS/CSS_syntax/At-rule) -- [Initial](/en-US/docs/Web/CSS/CSS_cascade/initial_value), [computed](/en-US/docs/Web/CSS/CSS_cascade/computed_value), [used](/en-US/docs/Web/CSS/CSS_cascade/used_value), and [actual](/en-US/docs/Web/CSS/CSS_cascade/actual_value) values +- [Initial](/en-US/docs/Web/CSS/CSS_cascade/Value_processing#initial_value), [computed](/en-US/docs/Web/CSS/CSS_cascade/Value_processing#computed_value), [used](/en-US/docs/Web/CSS/CSS_cascade/Value_processing#used_value), and [actual](/en-US/docs/Web/CSS/CSS_cascade/Value_processing#actual_value) values diff --git a/files/en-us/web/css/css_cascade/computed_value/index.md b/files/en-us/web/css/css_cascade/computed_value/index.md deleted file mode 100644 index 6d7cd13f67c2067..000000000000000 --- a/files/en-us/web/css/css_cascade/computed_value/index.md +++ /dev/null @@ -1,48 +0,0 @@ ---- -title: Computed value -slug: Web/CSS/CSS_cascade/computed_value -page-type: guide -spec-urls: - - https://www.w3.org/TR/CSS22/cascade.html#computed-value - - https://drafts.csswg.org/css-cascade-5/#computed-value ---- - -{{CSSRef}} - -The **computed value** of a [CSS](/en-US/docs/Web/CSS) property is the value that is transferred from parent to child during inheritance. It is calculated from the [specified value](/en-US/docs/Web/CSS/CSS_cascade/specified_value) by: - -1. Handling the special values {{cssxref("inherit")}}, {{cssxref("initial")}}, {{cssxref("revert")}}, {{cssxref("revert-layer")}}, and {{cssxref("unset")}}. -2. Doing the computation needed to reach the value described in the "Computed value" line in the property's definition table. - -The computation needed to reach a property's computed value typically involves converting relative values (such as those in `em` units or percentages) to absolute values. For example, if an element has specified values `font-size: 16px` and `padding-top: 2em`, then the computed value of `padding-top` is `32px` (double the font size). - -However, for some properties (those where percentages are relative to something that may require layout to determine, such as `width`, `margin-right`, `text-indent`, and `top`), percentage-specified values turn into percentage-computed values. Additionally, unitless numbers specified on the `line-height` property become the computed value, as specified. The relative values that remain in the computed value become absolute when the [used value](/en-US/docs/Web/CSS/CSS_cascade/used_value) is determined. - -> [!NOTE] -> The {{domxref("Window.getComputedStyle", "getComputedStyle()")}} DOM API returns the [resolved value](/en-US/docs/Web/CSS/resolved_value), which may either be the computed value or the [used value](/en-US/docs/Web/CSS/CSS_cascade/used_value), depending on the property. - -## Specifications - -{{Specifications}} - -## See also - -- {{domxref("window.getComputedStyle")}} -- CSS key concepts: - - [CSS syntax](/en-US/docs/Web/CSS/CSS_syntax/Syntax) - - [At-rules](/en-US/docs/Web/CSS/CSS_syntax/At-rule) - - [Comments](/en-US/docs/Web/CSS/CSS_syntax/Comments) - - [Specificity](/en-US/docs/Web/CSS/CSS_cascade/Specificity) - - [Inheritance](/en-US/docs/Web/CSS/CSS_cascade/Inheritance) - - [Box model](/en-US/docs/Web/CSS/CSS_box_model/Introduction_to_the_CSS_box_model) - - [Layout modes](/en-US/docs/Web/CSS/Layout_mode) - - [Visual formatting model](/en-US/docs/Web/CSS/Visual_formatting_model) - - [Margin collapsing](/en-US/docs/Web/CSS/CSS_box_model/Mastering_margin_collapsing) - - Values - - [Initial values](/en-US/docs/Web/CSS/CSS_cascade/initial_value) - - [Used values](/en-US/docs/Web/CSS/CSS_cascade/used_value) - - [Resolved values](/en-US/docs/Web/CSS/resolved_value) - - [Actual values](/en-US/docs/Web/CSS/CSS_cascade/actual_value) - - [Value definition syntax](/en-US/docs/Web/CSS/CSS_Values_and_Units/Value_definition_syntax) - - [Shorthand properties](/en-US/docs/Web/CSS/CSS_cascade/Shorthand_properties) - - [Replaced elements](/en-US/docs/Web/CSS/Replaced_element) diff --git a/files/en-us/web/css/css_cascade/index.md b/files/en-us/web/css/css_cascade/index.md index db149a50ef8ac7f..168b833f18c90d0 100644 --- a/files/en-us/web/css/css_cascade/index.md +++ b/files/en-us/web/css/css_cascade/index.md @@ -48,19 +48,19 @@ The opposite also occurs. Sometimes there are no declarations defining the value ### Glossary and definitions -- [Actual value](/en-US/docs/Web/CSS/CSS_cascade/actual_value) +- [Actual value](/en-US/docs/Web/CSS/CSS_cascade/Value_processing#actual_value) - [Anonymous layer](/en-US/docs/Learn_web_development/Core/Styling_basics/Cascade_layers#the_layer_block_at-rule_for_named_and_anonymous_layers) - [Author origin](/en-US/docs/Web/CSS/CSS_cascade/Cascade#author_stylesheets) - [Cascade](/en-US/docs/Web/CSS/CSS_cascade/Cascade) -- [Computed value](/en-US/docs/Web/CSS/CSS_cascade/computed_value) -- [Initial value](/en-US/docs/Web/CSS/CSS_cascade/initial_value) +- [Computed value](/en-US/docs/Web/CSS/CSS_cascade/Value_processing#computed_value) +- [Initial value](/en-US/docs/Web/CSS/CSS_cascade/Value_processing#initial_value) - [Named layer](/en-US/docs/Learn_web_development/Core/Styling_basics/Cascade_layers#the_layer_statement_at-rule_for_named_layers) -- [Resolved value](/en-US/docs/Web/CSS/resolved_value) +- [Resolved value](/en-US/docs/Web/CSS/CSS_cascade/Value_processing#resolved_value) - [Shorthand properties](/en-US/docs/Web/CSS/CSS_cascade/Shorthand_properties) - [Specificity](/en-US/docs/Web/CSS/CSS_cascade/Specificity) -- [Specified value](/en-US/docs/Web/CSS/CSS_cascade/specified_value) +- [Specified value](/en-US/docs/Web/CSS/CSS_cascade/Value_processing#specified_value) - {{glossary("style origin")}} -- [Used value](/en-US/docs/Web/CSS/CSS_cascade/used_value) +- [Used value](/en-US/docs/Web/CSS/CSS_cascade/Value_processing#used_value) - [User origin](/en-US/docs/Web/CSS/CSS_cascade/Cascade#user_stylesheets) - [User-agent origin](/en-US/docs/Web/CSS/CSS_cascade/Cascade#user-agent_stylesheets) @@ -84,7 +84,7 @@ The opposite also occurs. Sometimes there are no declarations defining the value ## Related concepts -- [Element-attached styles](/en-US/docs/Web/HTML/Global_attributes/style) +- [Element-attached styles](/en-US/docs/Web/HTML/Reference/Global_attributes/style) - [Inline styles and the cascade](/en-US/docs/Web/CSS/CSS_cascade/Cascade#inline_styles) - [Conditional rules for @imports](/en-US/docs/Web/CSS/@import#importing_css_rules_conditional_on_media_queries) - [Value definition syntax](/en-US/docs/Web/CSS/CSS_Values_and_Units/Value_definition_syntax) diff --git a/files/en-us/web/css/css_cascade/inheritance/index.md b/files/en-us/web/css/css_cascade/inheritance/index.md index 4d019feedc77b08..80fe36503620157 100644 --- a/files/en-us/web/css/css_cascade/inheritance/index.md +++ b/files/en-us/web/css/css_cascade/inheritance/index.md @@ -11,14 +11,14 @@ In CSS, **inheritance** controls what happens when no value is specified for a p CSS properties can be categorized in two types: -- **inherited properties**, which by default are set to the [computed value](/en-US/docs/Web/CSS/CSS_cascade/computed_value) of the parent element -- **non-inherited properties**, which by default are set to [initial value](/en-US/docs/Web/CSS/CSS_cascade/initial_value) of the property +- **inherited properties**, which by default are set to the [computed value](/en-US/docs/Web/CSS/CSS_cascade/Value_processing#computed_value) of the parent element +- **non-inherited properties**, which by default are set to [initial value](/en-US/docs/Web/CSS/CSS_cascade/Value_processing#initial_value) of the property Refer to [any CSS property](/en-US/docs/Web/CSS/Reference#index) definition to see whether a specific property inherits by default ("Inherited: yes") or not ("Inherited: no"). ## Inherited properties -When no value for an **inherited property** has been specified on an element, the element gets the [computed value](/en-US/docs/Web/CSS/CSS_cascade/computed_value) of that property on its parent element. Only the root element of the document gets the [initial value](/en-US/docs/Web/CSS/CSS_cascade/initial_value) given in the property's summary. +When no value for an **inherited property** has been specified on an element, the element gets the [computed value](/en-US/docs/Web/CSS/CSS_cascade/Value_processing#computed_value) of that property on its parent element. Only the root element of the document gets the [initial value](/en-US/docs/Web/CSS/CSS_cascade/Value_processing#initial_value) given in the property's summary. A typical example of an inherited property is the [`color`](/en-US/docs/Web/CSS/color) property. Consider the following style rules and the markup: @@ -38,7 +38,7 @@ The words "emphasized text" will appear green, since the `em` element has inheri ## Non-inherited properties -When no value for a **non-inherited property** has been specified on an element, the element gets the [initial value](/en-US/docs/Web/CSS/CSS_cascade/initial_value) of that property (as specified in the property's summary). +When no value for a **non-inherited property** has been specified on an element, the element gets the [initial value](/en-US/docs/Web/CSS/CSS_cascade/Value_processing#initial_value) of that property (as specified in the property's summary). A typical example of a non-inherited property is the {{ Cssxref("border") }} property. Consider the following style rules and the markup: @@ -94,6 +94,10 @@ em { We can see here another border around the word "emphasized text". +## Specifications + +{{Specifications}} + ## See also - CSS values for controlling inheritance: [`inherit`](/en-US/docs/Web/CSS/inherit), [`initial`](/en-US/docs/Web/CSS/initial), [`revert`](/en-US/docs/Web/CSS/revert), [`revert-layer`](/en-US/docs/Web/CSS/revert-layer), and [`unset`](/en-US/docs/Web/CSS/unset) @@ -105,6 +109,6 @@ We can see here another border around the word "emphasized text". - [CSS syntax](/en-US/docs/Web/CSS/CSS_syntax/Syntax) guide - [CSS syntax](/en-US/docs/Web/CSS/CSS_syntax) module - [At-rules](/en-US/docs/Web/CSS/CSS_syntax/At-rule) -- [Initial](/en-US/docs/Web/CSS/CSS_cascade/initial_value), [computed](/en-US/docs/Web/CSS/CSS_cascade/computed_value), [used](/en-US/docs/Web/CSS/CSS_cascade/used_value), and [actual](/en-US/docs/Web/CSS/CSS_cascade/actual_value) values +- [Initial](/en-US/docs/Web/CSS/CSS_cascade/Value_processing#initial_value), [computed](/en-US/docs/Web/CSS/CSS_cascade/Value_processing#computed_value), [used](/en-US/docs/Web/CSS/CSS_cascade/Value_processing#used_value), and [actual](/en-US/docs/Web/CSS/CSS_cascade/Value_processing#actual_value) values - [Value definition syntax](/en-US/docs/Web/CSS/CSS_Values_and_Units/Value_definition_syntax) - [CSS nesting module](/en-US/docs/Web/CSS/CSS_nesting) diff --git a/files/en-us/web/css/css_cascade/initial_value/index.md b/files/en-us/web/css/css_cascade/initial_value/index.md deleted file mode 100644 index 19df4db3f7d6493..000000000000000 --- a/files/en-us/web/css/css_cascade/initial_value/index.md +++ /dev/null @@ -1,46 +0,0 @@ ---- -title: Initial value -slug: Web/CSS/CSS_cascade/initial_value -page-type: guide -spec-urls: - - https://www.w3.org/TR/CSS22/cascade.html#specified-value - - https://drafts.csswg.org/css-cascade-5/#specified-value ---- - -{{CSSRef}} - -The **initial value** of a [CSS](/en-US/docs/Web/CSS) property is its default value, as listed in its definition table in the specification. The usage of the initial value depends on whether a property is inherited or not: - -- For [inherited properties](/en-US/docs/Web/CSS/CSS_cascade/Inheritance#inherited_properties), the initial value is used on the _root element only_, as long as no [specified value](/en-US/docs/Web/CSS/CSS_cascade/specified_value) is supplied. -- For [non-inherited properties](/en-US/docs/Web/CSS/CSS_cascade/Inheritance#non-inherited_properties), the initial value is used on _all elements_, as long as no [specified value](/en-US/docs/Web/CSS/CSS_cascade/specified_value) is supplied. - -You can explicitly specify the initial value by using the {{cssxref("initial")}} keyword. - -> [!NOTE] -> The initial value should not be confused with the value specified by the browser's style sheet. - -## Specifications - -{{Specifications}} - -## See also - -- {{cssxref("initial")}} -- CSS key concepts: - - [CSS syntax](/en-US/docs/Web/CSS/CSS_syntax/Syntax) - - [At-rules](/en-US/docs/Web/CSS/CSS_syntax/At-rule) - - [Comments](/en-US/docs/Web/CSS/CSS_syntax/Comments) - - [Specificity](/en-US/docs/Web/CSS/CSS_cascade/Specificity) - - [Inheritance](/en-US/docs/Web/CSS/CSS_cascade/Inheritance) - - [Box model](/en-US/docs/Web/CSS/CSS_box_model/Introduction_to_the_CSS_box_model) - - [Layout modes](/en-US/docs/Web/CSS/Layout_mode) - - [Visual formatting model](/en-US/docs/Web/CSS/Visual_formatting_model) - - [Margin collapsing](/en-US/docs/Web/CSS/CSS_box_model/Mastering_margin_collapsing) - - Values - - [Computed values](/en-US/docs/Web/CSS/CSS_cascade/computed_value) - - [Used values](/en-US/docs/Web/CSS/CSS_cascade/used_value) - - [Resolved values](/en-US/docs/Web/CSS/resolved_value) - - [Actual values](/en-US/docs/Web/CSS/CSS_cascade/actual_value) - - [Value definition syntax](/en-US/docs/Web/CSS/CSS_Values_and_Units/Value_definition_syntax) - - [Shorthand properties](/en-US/docs/Web/CSS/CSS_cascade/Shorthand_properties) - - [Replaced elements](/en-US/docs/Web/CSS/Replaced_element) diff --git a/files/en-us/web/css/css_cascade/shorthand_properties/index.md b/files/en-us/web/css/css_cascade/shorthand_properties/index.md index a52482ee32675b9..46477af3733e51d 100644 --- a/files/en-us/web/css/css_cascade/shorthand_properties/index.md +++ b/files/en-us/web/css/css_cascade/shorthand_properties/index.md @@ -234,6 +234,7 @@ See [Handling conflicts](/en-US/docs/Learn_web_development/Core/Styling_basics/H - {{cssxref("scroll-padding-block")}} - {{cssxref("scroll-padding-inline")}} - {{cssxref("scroll-timeline")}} +- {{cssxref("text-box")}} - {{cssxref("text-decoration")}} - {{cssxref("text-emphasis")}} - {{cssxref("text-wrap")}} @@ -253,6 +254,6 @@ See [Handling conflicts](/en-US/docs/Learn_web_development/Core/Styling_basics/H - [Learn: Handling conflicts](/en-US/docs/Learn_web_development/Core/Styling_basics/Handling_conflicts) - [Learn: Cascade layers](/en-US/docs/Learn_web_development/Core/Styling_basics/Cascade_layers) - [CSS cascading and inheritance](/en-US/docs/Web/CSS/CSS_cascade) module -- [Visual formatting models](/en-US/docs/Web/CSS/Visual_formatting_model) -- [Initial](/en-US/docs/Web/CSS/CSS_cascade/initial_value), [computed](/en-US/docs/Web/CSS/CSS_cascade/computed_value), [used](/en-US/docs/Web/CSS/CSS_cascade/used_value), and [actual](/en-US/docs/Web/CSS/CSS_cascade/actual_value) values +- [Visual formatting models](/en-US/docs/Web/CSS/CSS_display/Visual_formatting_model) +- [Initial](/en-US/docs/Web/CSS/CSS_cascade/Value_processing#initial_value), [computed](/en-US/docs/Web/CSS/CSS_cascade/Value_processing#computed_value), [used](/en-US/docs/Web/CSS/CSS_cascade/Value_processing#used_value), and [actual](/en-US/docs/Web/CSS/CSS_cascade/Value_processing#actual_value) values - [Value definition syntax](/en-US/docs/Web/CSS/CSS_Values_and_Units/Value_definition_syntax) diff --git a/files/en-us/web/css/css_cascade/specificity/index.md b/files/en-us/web/css/css_cascade/specificity/index.md index 4398655f4ba0734..2e11dae1dce3f24 100644 --- a/files/en-us/web/css/css_cascade/specificity/index.md +++ b/files/en-us/web/css/css_cascade/specificity/index.md @@ -60,9 +60,15 @@ The specificity for a required input nested in an element with attribute `id="my If the password input type with `required` is nested in an element with `id="myApp"` set, the specificity weight will be `1-2-1`, based on one ID, two pseudo-classes, and one element type, whether or not it has focus. Why is the specificity weight `1-2-1` rather than `0-1-1` or `0-1-0` in this case? Because the specificity weight comes from the matching selector with the greatest specificity weight. The weight is determined by comparing the values in the three columns, from left to right. ```css -[type="password"] /* 0-1-0 */ -input:focus /* 0-1-1 */ -:root #myApp input:required /* 1-2-1 */ +[type="password"] { + /* 0-1-0 */ +} +input:focus { + /* 0-1-1 */ +} +:root #myApp input:required { + /* 1-2-1 */ +} ``` ### Three-column comparison @@ -245,7 +251,8 @@ Including a ruleset inside a `@scope` block does not affect the specificity of i ```css @scope (.article-body) { /* img has a specificity of 0-0-1, as expected */ - img { ... } + img { + } } ``` @@ -254,7 +261,8 @@ However, if you decide to explicitly prepend the `:scope` pseudo-class to your s ```css @scope (.article-body) { /* :scope img has a specificity of 0-1-0 + 0-0-1 = 0-1-1 */ - :scope img { ... } + :scope img { + } } ``` @@ -262,7 +270,8 @@ When using the `&` selector inside a `@scope` block, `&` represents the scope ro ```css @scope (figure, #primary) { - & img { ... } + & img { + } } ``` @@ -340,7 +349,7 @@ When two selectors from different layers match the same element, origin and impo ```html <style> - @import TW.css layer(); + @import "TW.css" layer(); p, p * { font-size: 1rem; @@ -371,7 +380,7 @@ If you're unable to remove `!important` flags from an authors style sheet, the o ```html <style> - @import importantOverrides.css layer(); + @import "importantOverrides.css" layer(); </style> ``` @@ -500,7 +509,7 @@ A few things to remember about specificity: - [CSS error handling](/en-US/docs/Web/CSS/CSS_syntax/Error_handling) - [At-rules](/en-US/docs/Web/CSS/CSS_syntax/At-rule) - [Inheritance](/en-US/docs/Web/CSS/CSS_cascade/Inheritance) -- [Initial](/en-US/docs/Web/CSS/CSS_cascade/initial_value), [computed](/en-US/docs/Web/CSS/CSS_cascade/computed_value), [used](/en-US/docs/Web/CSS/CSS_cascade/used_value), and [actual](/en-US/docs/Web/CSS/CSS_cascade/actual_value) values +- [Initial](/en-US/docs/Web/CSS/CSS_cascade/Value_processing#initial_value), [computed](/en-US/docs/Web/CSS/CSS_cascade/Value_processing#computed_value), [used](/en-US/docs/Web/CSS/CSS_cascade/Value_processing#used_value), and [actual](/en-US/docs/Web/CSS/CSS_cascade/Value_processing#actual_value) values - [Value definition syntax](/en-US/docs/Web/CSS/CSS_Values_and_Units/Value_definition_syntax) - [Learn: Handling conflicts](/en-US/docs/Learn_web_development/Core/Styling_basics/Handling_conflicts) - [Learn: cascade layers](/en-US/docs/Learn_web_development/Core/Styling_basics/Cascade_layers) diff --git a/files/en-us/web/css/css_cascade/specified_value/index.md b/files/en-us/web/css/css_cascade/specified_value/index.md deleted file mode 100644 index 51d14a1cad418f2..000000000000000 --- a/files/en-us/web/css/css_cascade/specified_value/index.md +++ /dev/null @@ -1,73 +0,0 @@ ---- -title: Specified value -slug: Web/CSS/CSS_cascade/specified_value -page-type: guide -spec-urls: - - https://www.w3.org/TR/CSS22/cascade.html#specified-value - - https://drafts.csswg.org/css-cascade-5/#specified-value ---- - -{{CSSRef}} - -The **specified value** of a [CSS](/en-US/docs/Web/CSS) property is the value it receives from the document's style sheet. The specified value for a given property is determined according to the following rules: - -1. If the document's style sheet explicitly specifies a value for the property, the given value will be used. -2. If the document's style sheet doesn't specify a value but it is an inherited property, the value will be taken from the parent element. -3. If none of the above apply, the element's [initial value](/en-US/docs/Web/CSS/CSS_cascade/initial_value) will be used. - -## Examples - -### HTML - -```html -<p>My specified color is given explicitly in the CSS.</p> - -<div> - The specified values of all my properties default to their initial values, - because none of them are given in the CSS. -</div> - -<div class="fun"> - <p> - The specified value of my font family is not given explicitly in the CSS, so - it is inherited from my parent. However, the border is not an inheriting - property. - </p> -</div> -``` - -### CSS - -```css -.fun { - border: 1px dotted pink; - font-family: fantasy; -} - -p { - color: green; -} -``` - -### Result - -{{EmbedLiveSample("Examples", 500, 220)}} - -## Specifications - -{{Specifications}} - -## See also - -- [Specificity](/en-US/docs/Web/CSS/CSS_cascade/Specificity) -- [Inheritance](/en-US/docs/Web/CSS/CSS_cascade/Inheritance) -- [CSS syntax](/en-US/docs/Web/CSS/CSS_syntax/Syntax) -- [At-rules](/en-US/docs/Web/CSS/CSS_syntax/At-rule) -- [Box model](/en-US/docs/Web/CSS/CSS_box_model/Introduction_to_the_CSS_box_model) -- [Layout modes](/en-US/docs/Web/CSS/Layout_mode) -- [Visual formatting models](/en-US/docs/Web/CSS/Visual_formatting_model) -- [Margin collapsing](/en-US/docs/Web/CSS/CSS_box_model/Mastering_margin_collapsing) -- [Initial](/en-US/docs/Web/CSS/CSS_cascade/initial_value), [computed](/en-US/docs/Web/CSS/CSS_cascade/computed_value), [used](/en-US/docs/Web/CSS/CSS_cascade/used_value), and [actual](/en-US/docs/Web/CSS/CSS_cascade/actual_value) values -- [Value definition syntax](/en-US/docs/Web/CSS/CSS_Values_and_Units/Value_definition_syntax) -- [Shorthand properties](/en-US/docs/Web/CSS/CSS_cascade/Shorthand_properties) -- [Replaced elements](/en-US/docs/Web/CSS/Replaced_element) diff --git a/files/en-us/web/css/css_cascade/used_value/index.md b/files/en-us/web/css/css_cascade/used_value/index.md deleted file mode 100644 index 7a3cca00d3c37c9..000000000000000 --- a/files/en-us/web/css/css_cascade/used_value/index.md +++ /dev/null @@ -1,123 +0,0 @@ ---- -title: Used value -slug: Web/CSS/CSS_cascade/used_value -page-type: guide -spec-urls: - - https://www.w3.org/TR/CSS22/cascade.html#used-value - - https://drafts.csswg.org/css-cascade-5/#used-value ---- - -{{CSSRef}} - -The **used value** of a [CSS](/en-US/docs/Web/CSS) property is its value after all calculations have been performed on the [computed value](/en-US/docs/Web/CSS/CSS_cascade/computed_value). - -After the {{glossary("user agent")}} has finished its calculations, every CSS property has a used value. The used values of dimensions (e.g., {{cssxref("width")}}, {{cssxref("line-height")}}) are in pixels. The used values of shorthand properties (e.g., {{cssxref("background")}}) are consistent with those of their component properties (e.g., {{cssxref("background-color")}} or {{cssxref("background-size")}}) and with {{cssxref("position")}} and {{cssxref("float")}}. - -> [!NOTE] -> The {{domxref("Window.getComputedStyle", "getComputedStyle()")}} DOM API returns the [resolved value](/en-US/docs/Web/CSS/resolved_value), which may either be the [computed value](/en-US/docs/Web/CSS/CSS_cascade/computed_value) or the used value, depending on the property. - -## Example - -This example computes and displays the used `width` value of three elements (updates on resize): - -### HTML - -```html -<div id="no-width"> - <p>No explicit width.</p> - <p class="show-used-width">..</p> - - <div id="width-50"> - <p>Explicit width: 50%.</p> - <p class="show-used-width">..</p> - - <div id="width-inherit"> - <p>Explicit width: inherit.</p> - <p class="show-used-width">..</p> - </div> - </div> -</div> -``` - -### CSS - -```css -#no-width { - width: auto; -} - -#width-50 { - width: 50%; -} - -#width-inherit { - width: inherit; -} - -/* Make results easier to see */ -div { - border: 1px solid red; - padding: 8px; -} -``` - -### JavaScript - -```js -function updateUsedWidth(id) { - const div = document.getElementById(id); - const par = div.querySelector(".show-used-width"); - const wid = window.getComputedStyle(div)["width"]; - par.textContent = `Used width: ${wid}.`; -} - -function updateAllUsedWidths() { - updateUsedWidth("no-width"); - updateUsedWidth("width-50"); - updateUsedWidth("width-inherit"); -} - -updateAllUsedWidths(); -window.addEventListener("resize", updateAllUsedWidths); -``` - -### Result - -{{ EmbedLiveSample('Example', '80%', 372) }} - -## Difference from computed value - -CSS 2.0 defined only _computed value_ as the last step in a property's calculation. Then, CSS 2.1 introduced the distinct definition of used value. An element could then explicitly inherit a width/height of a parent, whose computed value is a percentage. For CSS properties that don't depend on layout (e.g., `display`, `font-size`, or `line-height`), the computed values and used values are the same. The following are the CSS 2.1 properties that do depend on layout, so they have a different computed value and used value: (taken from [CSS 2.1 Changes: Specified, computed, and actual values](https://www.w3.org/TR/CSS2/changes.html#q21.36)): - -- `background-position` -- `bottom`, `left`, `right`, `top` -- `height`, `width` -- `margin-bottom`, `margin-left`, `margin-right`, `margin-top` -- `min-height`, `min-width` -- `padding-bottom`, `padding-left`, `padding-right`, `padding-top` -- `text-indent` - -## Specifications - -{{Specifications}} - -## See also - -- {{domxref("window.getComputedStyle")}} -- CSS key concepts: - - [CSS syntax](/en-US/docs/Web/CSS/CSS_syntax/Syntax) - - [Comments](/en-US/docs/Web/CSS/CSS_syntax/Comments) - - [Specificity](/en-US/docs/Web/CSS/CSS_cascade/Specificity) - - [Inheritance](/en-US/docs/Web/CSS/CSS_cascade/Inheritance) - - [Box model](/en-US/docs/Web/CSS/CSS_box_model/Introduction_to_the_CSS_box_model) - - [Layout modes](/en-US/docs/Web/CSS/Layout_mode) - - [Visual formatting model](/en-US/docs/Web/CSS/Visual_formatting_model) - - [Margin collapsing](/en-US/docs/Web/CSS/CSS_box_model/Mastering_margin_collapsing) - - Values - - [Initial values](/en-US/docs/Web/CSS/CSS_cascade/initial_value) - - [Computed values](/en-US/docs/Web/CSS/CSS_cascade/computed_value) - - [Resolved values](/en-US/docs/Web/CSS/resolved_value) - - [Actual values](/en-US/docs/Web/CSS/CSS_cascade/actual_value) - - [Value definition syntax](/en-US/docs/Web/CSS/CSS_Values_and_Units/Value_definition_syntax) - - [Shorthand properties](/en-US/docs/Web/CSS/CSS_cascade/Shorthand_properties) - - [Replaced elements](/en-US/docs/Web/CSS/Replaced_element) diff --git a/files/en-us/web/css/css_cascade/value_processing/index.md b/files/en-us/web/css/css_cascade/value_processing/index.md new file mode 100644 index 000000000000000..98c435e4149f9c6 --- /dev/null +++ b/files/en-us/web/css/css_cascade/value_processing/index.md @@ -0,0 +1,182 @@ +--- +title: CSS property value processing +slug: Web/CSS/CSS_cascade/Value_processing +page-type: guide +--- + +{{CSSRef}} + +For every element in a document tree, the browser assigns a value to every CSS property that applies to that element. The rendered value of each CSS property for a given element or box is the result of a calculation based on stylesheet definitions, inheritance, the [cascade](/en-US/docs/Web/CSS/CSS_cascade/Cascade), dependencies, unit conversion, and the display environment. This guide provides an overview of the processing steps applied to define how each CSS value is ultimately rendered by exploring key concepts like specified, computed, used, and actual values. + +## Property values + +Every CSS property's value comes from the declaration with the greatest {{cssxref("specificity")}}. If two or more declarations with the same specificity provide different property values for the same element, the declaration value whose selector has the greatest algorithmic weight gets applied. + +Each property value comes from a single property-value pair; is single value is applied from each property. Even if the value is a comma separated list of values, that list of values came from a single declaration. + +To determine which specified value is applied, the user agent gathers and processes all the styles from different sources, such as inline styles, and internal and external stylesheets. + +Certain properties inherit values from their parent elements unless explicitly overridden. [Inheritance](/en-US/docs/Web/CSS/CSS_cascade/Inheritance) occurs when no style information exists for a specific property on an element. If the property is inherited, the value is set to the [computed value](#computed_value) of the parent element. If the property is not inherited, its value is set to the [initial value](#initial_value) for that element. + +The [cascade](/en-US/docs/Web/CSS/CSS_cascade/Cascade) determines which value should be applied when multiple conflicting styles target the same element. The cascade algorithm defines how user agents combine property values originating from different sources, scopes, and/or layers. When a selector matches an element, the property's [specified value](#specified_value) from the origin with the highest precedence gets applied, even if a selector from a lower precedence origin or layer has greater {{cssxref("specificity")}}. + +After applying the cascading rules and resolving values step by step, the browser ensures the visual presentation matches the processed CSS. + +## Processing stages + +All elements that are part of the document's flattened element tree have declared, cascaded, specified, computed, used, and actual values. For a specific property, these values may or may not be the same. For example, if your large code base includes the CSS `p { font-size: 1.25em; }` and your HTML includes `<p>CSS is fun!</p>`, what size will the paragraph be? The {{cssxref("font-size")}} value moves through a few stages to go from the `em` specified value to the rendered `px` value. + +- [Initial value](#initial_value) +- [Specified value](#specified_value) +- [Computed value](#computed_value) +- [Used Value](#used_value) + +These values are used to determine the final [rendered value](#rendered_values). + +### Initial value + +A property's **initial value** is the default value as listed in its definition table in the specification. The usage of the initial value depends on whether a property is inherited or not: + +For [inherited properties](/en-US/docs/Web/CSS/CSS_cascade/Inheritance#inherited_properties), the initial value is used on the _root element only_, as long as no [specified value](#specified_value) is supplied. + +- For [non-inherited properties](/en-US/docs/Web/CSS/CSS_cascade/Inheritance#non-inherited_properties), the initial value is used on _all elements_, as long as no specified value is supplied. + +You can explicitly set the initial value by using the {{cssxref("initial")}} keyword. + +> [!NOTE] +> The initial value for can be found in the formal syntax section of each CSS property reference page. For example, the [initial value of `font-size` is `medium`](/en-US/docs/Web/CSS/font-size#formal_definition). The initial value should not be confused with the value specified by the browser's style sheet. + +### Specified value + +The **specified value** is the value initially assigned in the CSS file or by the `style` attribute. The specified value for a given property is determined according to the following rules: + +1. If the document's style sheet explicitly specifies a value for the property, the given value will be used. +2. If the document's style sheet doesn't specify a value but it is an inherited property, the value will be taken from the parent element. +3. If none of the above apply, the element's [initial value](#initial_value) will be used. + +In the example, `p { font-size: 1.25em; }`, the specified value is `1.25em`, unless the codebase includes a `font-size` declaration with greater {{cssxref("specificity")}}. + +### Computed value + +The **computed value** of a property is the value transferred from parent to child during inheritance. It is the result after resolving things like relative units and custom properties into absolute values, but before considering layout-specific information. + +The computed value is calculated from the [specified value](#specified_value) by: + +1. Handling the special values {{cssxref("inherit")}}, {{cssxref("initial")}}, {{cssxref("revert")}}, {{cssxref("revert-layer")}}, and {{cssxref("unset")}}. +2. Doing the computation needed to reach the value described in the "Computed value" line in the property's definition table. + +The computation needed to reach a property's computed value typically involves converting relative values (such as those in `em` units or percentages) to absolute values. For example, if an element has specified values `font-size: 16px` and `padding-top: 2em`, then the computed value of `padding-top` is `32px` (double the font size). + +However, for some properties (those where percentages are relative to something that may require layout to determine, such as `width`, `margin-right`, `text-indent`, and `top`), percentage-specified values turn into percentage-computed values. Additionally, unitless numbers specified on the `line-height` property become the computed value, as specified. The relative values that remain in the computed value become absolute when the [used value](#used_value) is determined. + +Given `p { font-size: 1.25em; }`, if `em` is `16px`, the computed font size for a paragraph will be `20px`. + +### Used value + +The **used value** is the property's value after all calculations have been performed on the [computed value](#computed_value) and it has been refined with layout-specific details (e.g., percentages resolved to actual pixel values). + +Every CSS property has a used value. The used values of dimensions (e.g., {{cssxref("width")}} or {{cssxref("line-height")}}) are in pixels. The used values of shorthand properties (e.g., {{cssxref("background")}}) are consistent with those of their component properties (e.g., {{cssxref("background-color")}} or {{cssxref("background-size")}}) and with {{cssxref("position")}} and {{cssxref("float")}}. + +The used value for the {{cssxref("width")}} or {{cssxref("inline-size")}} of an element is a pixel value even if the specified value of the property was set with percentages or keyword values. + +If we have three container elements with their width set as `auto`, `50%`, and `inherit`: + +```html hidden +<div id="no-width"> + <p>No explicit width.</p> + <p class="show-used-width">..</p> + + <div id="width-50"> + <p>Explicit width: 50%.</p> + <p class="show-used-width">..</p> + + <div id="width-inherit"> + <p>Explicit width: inherit.</p> + <p class="show-used-width">..</p> + </div> + </div> +</div> +``` + +```css +#no-width { + width: auto; +} + +#width-50 { + width: 50%; +} + +#width-inherit { + width: inherit; +} + +/* Make results easier to see */ +div { + border: 1px solid red; + padding: 8px; +} +``` + +```js hidden +function updateUsedWidth(id) { + const div = document.getElementById(id); + const par = div.querySelector(".show-used-width"); + const wid = window.getComputedStyle(div)["width"]; + par.textContent = `Used width: ${wid}.`; +} + +function updateAllUsedWidths() { + updateUsedWidth("no-width"); + updateUsedWidth("width-50"); + updateUsedWidth("width-inherit"); +} + +updateAllUsedWidths(); +window.addEventListener("resize", updateAllUsedWidths); +``` + +While the three specified values, `auto`, `50%`, and `inherit`, are keyword and {{cssxref("percentage")}} values, retrieving the `width` using `window.getComputedStyle(el)["width"];` returns an [absolute length](/en-US/docs/Web/CSS/length#absolute_length_units) `px` value: + +{{ EmbedLiveSample('Example', '80%', 372) }} + +Change the window size or rotate your mobile device to change the size and the used values. + +## Rendered values + +The rendered value is called the [actual value](#actual_value), while the value retrieved via script is called the [resolved value](#resolved_value). + +### Actual Value + +The **actual value** of a property is the [used value](#used_value) of that property after any necessary approximations have been applied. It is the final rendered value as implemented by the browser, including adjustments for rendering quirks or limitations. For example, a {{glossary("user agent")}} that can only render borders with a whole-number pixel width may round the thickness of the border to the nearest integer. + +The calculation includes these steps: + +1. First, the [specified value](#specified_value) is determined based on the result of [cascading](/en-US/docs/Web/CSS/CSS_cascade/Cascade), [inheritance](/en-US/docs/Web/CSS/CSS_cascade/Inheritance), or using the [initial value](#initial_value). +2. Next, the [computed value](#computed_value) is calculated according to the specification (for example, a `span` with `position: absolute` will have its computed `display` changed to `block`). +3. Then, layout is calculated, resulting in the [used value](#used_value). +4. Finally, the used value is transformed according to the limitations of the local environment, resulting in the actual value. + +### Resolved value + +The **resolved value** of a property is the value after applying active stylesheets and resolving any basic computation those values may contain. The {{domxref("Window.getComputedStyle", "getComputedStyle()")}} method returns a live {{domxref("CSSStyleDeclaration")}} object containing the resolved values of all CSS properties applied to a specified element. Each resolved value is either the [computed value](#computed_value) or the [used value](#used_value), depending on the property. + +Historically, `getComputedStyle()` returned the computed value of an element or pseudo-element. As CSS evolved, so did the concept of "computed value", but the values returned by `getComputedStyle()` had to remain the same for backward compatibility with deployed scripts. These values are the "resolved values". + +For most properties, the resolved value is the computed value, but for a few legacy properties (including {{cssxref("width")}} and {{cssxref("height")}}), it is the used value. The [CSSOM specification](https://drafts.csswg.org/cssom/#resolved-values) provides per-property details. + +CSS 2.0 defined _computed value_ as the last step in a property's calculation. CSS 2.1 introduced the distinct definition of "used value". An element could then explicitly inherit the width/height of its parent, whose computed value is a percentage. For CSS properties that don't depend on layout (e.g., `display`, `font-size`, or `line-height`), the computed values and used values are the same. The following list contains the CSS 2.1 properties that _do_ depend on layout, and therefore have a different computed value and used value (taken from [CSS 2.1 Changes: Specified, computed, and actual values](https://www.w3.org/TR/CSS2/changes.html#q21.36)): + +- {{cssxref("background-position")}} +- {{cssxref("bottom")}}, {{cssxref("left")}}, {{cssxref("right")}}, {{cssxref("top")}} +- {{cssxref("height")}}, {{cssxref("width")}} +- {{cssxref("margin-bottom")}}, {{cssxref("margin-left")}}, {{cssxref("margin-right")}}, {{cssxref("margin-top")}} +- {{cssxref("min-height")}}, {{cssxref("min-width")}} +- {{cssxref("padding-bottom")}}, {{cssxref("padding-left")}}, {{cssxref("padding-right")}}, {{cssxref("padding-top")}} +- {{cssxref("text-indent")}} + +## See also + +- CSS values for controlling inheritance: [`inherit`](/en-US/docs/Web/CSS/inherit), [`initial`](/en-US/docs/Web/CSS/initial), [`revert`](/en-US/docs/Web/CSS/revert), [`revert-layer`](/en-US/docs/Web/CSS/revert-layer), and [`unset`](/en-US/docs/Web/CSS/unset) +- [CSS cascading and inheritance](/en-US/docs/Web/CSS/CSS_cascade) module +- [CSS syntax](/en-US/docs/Web/CSS/CSS_syntax) module diff --git a/files/en-us/web/css/css_cascading_variables/using_css_custom_properties/index.md b/files/en-us/web/css/css_cascading_variables/using_css_custom_properties/index.md index 3851ca341632f8e..5d51b5e786791fb 100644 --- a/files/en-us/web/css/css_cascading_variables/using_css_custom_properties/index.md +++ b/files/en-us/web/css/css_cascading_variables/using_css_custom_properties/index.md @@ -35,7 +35,7 @@ section { } ``` -The selector given to the ruleset ([`<section>`](/en-US/docs/Web/HTML/Element/section) elements in the example above) defines the scope in which the custom property can be used. +The selector given to the ruleset ([`<section>`](/en-US/docs/Web/HTML/Reference/Elements/section) elements in the example above) defines the scope in which the custom property can be used. For this reason, a common practice is to define custom properties on the {{cssxref(":root")}} pseudo-class, so that it can be referenced globally: ```css @@ -465,7 +465,7 @@ However, when the values of custom properties are parsed, the browser doesn't ye Unfortunately, these valid values can be used, via the `var()` functional notation, in a context where they might not make sense. Properties and custom variables can lead to invalid CSS statements, leading to the concept of _valid at computed time_. -When the browser encounters an invalid `var()` substitution, then the [initial](/en-US/docs/Web/CSS/CSS_cascade/initial_value) or [inherited](/en-US/docs/Web/CSS/CSS_cascade/Inheritance) value of the property is used. +When the browser encounters an invalid `var()` substitution, then the [initial](/en-US/docs/Web/CSS/CSS_cascade/Value_processing#initial_value) or [inherited](/en-US/docs/Web/CSS/CSS_cascade/Inheritance) value of the property is used. This example is just like the last one, except we use a custom property. The browser substitutes the value of `--text-color` in place of `var(--text-color)`, but `16px` is not a valid property value for {{cssxref("color")}}. diff --git a/files/en-us/web/css/css_colors/applying_color/index.md b/files/en-us/web/css/css_colors/applying_color/index.md index cef9dcb29fa50c6..2037658aa854afa 100644 --- a/files/en-us/web/css/css_colors/applying_color/index.md +++ b/files/en-us/web/css/css_colors/applying_color/index.md @@ -7,7 +7,7 @@ page-type: guide {{CSSRef}} -With [CSS](/en-US/docs/Web/CSS), there are lots of ways to add color to your [HTML](/en-US/docs/Web/HTML) [elements](/en-US/docs/Web/HTML/Element) to create the look you want. This guide is a primer introducing how CSS can be used to apply colors to HTML elements. This guide includes [lists of the CSS properties that set color in their values](#properties_that_can_have_color) and how to use colors both [in stylesheets](#specifying_colors_as_values_in_stylesheets) and [in other ways](#other_ways_to_use_color). +With [CSS](/en-US/docs/Web/CSS), there are lots of ways to add color to your [HTML](/en-US/docs/Web/HTML) [elements](/en-US/docs/Web/HTML/Reference/Elements) to create the look you want. This guide is a primer introducing how CSS can be used to apply colors to HTML elements. This guide includes [lists of the CSS properties that set color in their values](#properties_that_can_have_color) and how to use colors both [in stylesheets](#specifying_colors_as_values_in_stylesheets) and [in other ways](#other_ways_to_use_color). > [!NOTE] > It is important to [use colors wisely](/en-US/docs/Web/CSS/CSS_colors/Using_color_wisely). Always select appropriate colors, ensuring the contrast between text and the background is sufficient to ensure legibility, and always keep the needs of people with differing visual capabilities in mind. @@ -46,7 +46,7 @@ Whenever an element is rendered, these properties are used to determine the colo - {{cssxref("caret-color")}} - - : The color to use when drawing the {{Glossary("caret")}} (sometimes referred to as the text input cursor) within the element. This is only useful in elements that are editable, such as {{HTMLElement("input")}} and {{HTMLElement("textarea")}} or elements whose HTML [`contenteditable`](/en-US/docs/Web/HTML/Global_attributes/contenteditable) attribute is set to `true`. + - : The color to use when drawing the {{Glossary("caret")}} (sometimes referred to as the text input cursor) within the element. This is only useful in elements that are editable, such as {{HTMLElement("input")}} and {{HTMLElement("textarea")}} or elements whose HTML [`contenteditable`](/en-US/docs/Web/HTML/Reference/Global_attributes/contenteditable) attribute is set to `true`. ### Boxes @@ -169,7 +169,7 @@ The `.boxLeft` class, used to style the box on the left, sets up the color of th background-color: hwb(270deg 63% 13%); outline: 4px dashed #6e1478; color: hsl(0deg 100% 100%); - text-decoration: underline; + text-decoration-line: underline; text-decoration-style: wavy; text-decoration-color: #8f8; text-decoration: underline wavy #8f8; diff --git a/files/en-us/web/css/css_colors/color_picker_tool/index.md b/files/en-us/web/css/css_colors/color_picker_tool/index.md index 60d05d83d548b78..12a45c924d08aaf 100644 --- a/files/en-us/web/css/css_colors/color_picker_tool/index.md +++ b/files/en-us/web/css/css_colors/color_picker_tool/index.md @@ -26,7 +26,7 @@ The generated color values can be used anywhere the {{cssxref("color_value", "&l - [CSS color values](/en-US/docs/Web/CSS/CSS_colors/Color_values) - [Using color wisely](/en-US/docs/Web/CSS/CSS_colors/Using_color_wisely) - [Using relative colors](/en-US/docs/Web/CSS/CSS_colors/Relative_colors) -- [Understanding color and luminance](/en-US/docs/Web/Accessibility/Understanding_Colors_and_Luminance) -- [WCAG 1.4.1: Color contrast](/en-US/docs/Web/Accessibility/Understanding_WCAG/Perceivable/Color_contrast) +- [Understanding color and luminance](/en-US/docs/Web/Accessibility/Guides/Colors_and_Luminance) +- [WCAG 1.4.1: Color contrast](/en-US/docs/Web/Accessibility/Guides/Understanding_WCAG/Perceivable/Color_contrast) - [Learn: Styling backgrounds and borders using CSS](/en-US/docs/Learn_web_development/Core/Styling_basics/Backgrounds_and_borders) - [Learn accessibility: Color and color contrast](/en-US/docs/Learn_web_development/Core/Accessibility/CSS_and_JavaScript#color_and_color_contrast) diff --git a/files/en-us/web/css/css_colors/color_values/index.md b/files/en-us/web/css/css_colors/color_values/index.md index 5b007660a29282e..6522675487b75c2 100644 --- a/files/en-us/web/css/css_colors/color_values/index.md +++ b/files/en-us/web/css/css_colors/color_values/index.md @@ -76,7 +76,7 @@ See the {{cssxref("hex-color")}} data type for more information on hexadecimal s #### HTML color input type -There are many situations in which your website may need to let the user select a color. Perhaps you have a customizable user interface, or you're implementing a drawing app. Maybe you have editable text and need to let the user choose the text color. Or perhaps your app lets the user assign colors to folders or items. For such use cases, the {{HTMLElement("input")}} element has a `"color"` [`type`](/en-US/docs/Web/HTML/Element/input#type), which renders a color picker control. +There are many situations in which your website may need to let the user select a color. Perhaps you have a customizable user interface, or you're implementing a drawing app. Maybe you have editable text and need to let the user choose the text color. Or perhaps your app lets the user assign colors to folders or items. For such use cases, the {{HTMLElement("input")}} element has a `"color"` [`type`](/en-US/docs/Web/HTML/Reference/Elements/input#type), which renders a color picker control. This example allows you to choose a color. Once a choice is made, the {{cssxref("border-color")}} is set to that color, and the value is displayed. @@ -106,7 +106,7 @@ The HTML creates a box containing a color picker control (with a label created u } ``` -The following JavaScript updates the border's color to match the color picker's initial value, then adds two event handlers to the [`<input type="color">`](/en-US/docs/Web/HTML/Element/input/color) element to respond to changes made to its value. +The following JavaScript updates the border's color to match the color picker's initial value, then adds two event handlers to the [`<input type="color">`](/en-US/docs/Web/HTML/Reference/Elements/input/color) element to respond to changes made to its value. ```js const colorPicker = document.querySelector("#colorPicker"); @@ -691,6 +691,6 @@ The {{cssxref("color_value/light-dark", "light-dark()")}} function lets you spec - [Applying color to HTML elements using CSS](/en-US/docs/Web/CSS/CSS_colors/Applying_color) - [Using color wisely](/en-US/docs/Web/CSS/CSS_colors/Using_color_wisely) - [Using relative colors](/en-US/docs/Web/CSS/CSS_colors/Relative_colors) -- [Understanding color and luminance](/en-US/docs/Web/Accessibility/Understanding_Colors_and_Luminance) -- [WCAG 1.4.1: Color contrast](/en-US/docs/Web/Accessibility/Understanding_WCAG/Perceivable/Color_contrast) +- [Understanding color and luminance](/en-US/docs/Web/Accessibility/Guides/Colors_and_Luminance) +- [WCAG 1.4.1: Color contrast](/en-US/docs/Web/Accessibility/Guides/Understanding_WCAG/Perceivable/Color_contrast) - [CSS color module](/en-US/docs/Web/CSS/CSS_colors) diff --git a/files/en-us/web/css/css_colors/index.md b/files/en-us/web/css/css_colors/index.md index eb3f5b6b6fa2329..91ddced7bdd9e7c 100644 --- a/files/en-us/web/css/css_colors/index.md +++ b/files/en-us/web/css/css_colors/index.md @@ -19,7 +19,7 @@ The color syntax converter below shows the values of the currently selected colo {{EmbedGHLiveSample("css-examples/modules/colors.html", '100%', 450)}} -Selecting a color via the [color picker](/en-US/docs/Web/HTML/Element/input/color) and an opacity via the [slider](/en-US/docs/Web/HTML/Element/input/range) updates the RGB, HEX, HSL, and HWB values. When you choose a new color or opacity value, the color of the background and the slider update via the CSS properties {{cssxref("background-color")}} and {{cssxref("accent-color")}}, respectively. +Selecting a color via the [color picker](/en-US/docs/Web/HTML/Reference/Elements/input/color) and an opacity via the [slider](/en-US/docs/Web/HTML/Reference/Elements/input/range) updates the RGB, HEX, HSL, and HWB values. When you choose a new color or opacity value, the color of the background and the slider update via the CSS properties {{cssxref("background-color")}} and {{cssxref("accent-color")}}, respectively. To see the code for this color syntax converter, [view the source on GitHub](https://github.com/mdn/css-examples/blob/main/modules/colors.html). @@ -86,9 +86,9 @@ To see the code for this color syntax converter, [view the source on GitHub](htt - : Color theory and resources, including finding the right colors to create an accessible color palette, contrast, and printing in color. - [Using relative colors](/en-US/docs/Web/CSS/CSS_colors/Relative_colors) - : This article explains relative CSS color syntax, shows what the different options are, and looks at some illustrative examples. -- [Understanding color and luminance](/en-US/docs/Web/Accessibility/Understanding_Colors_and_Luminance) +- [Understanding color and luminance](/en-US/docs/Web/Accessibility/Guides/Colors_and_Luminance) - : Color perception and using colors with color insensitive (color blind) users, reduced vision users and users with vestibular disorders or other neurological disorders in mind. -- [WCAG 1.4.1: Color contrast](/en-US/docs/Web/Accessibility/Understanding_WCAG/Perceivable/Color_contrast) +- [WCAG 1.4.1: Color contrast](/en-US/docs/Web/Accessibility/Guides/Understanding_WCAG/Perceivable/Color_contrast) - : Explanation of contrast requirements between background and foreground content to ensure legibility. ## Related concepts @@ -110,12 +110,12 @@ To see the code for this color syntax converter, [view the source on GitHub](htt - {{cssxref("text-shadow")}} - {{cssxref("-webkit-tap-highlight-color")}} - SVG color properties that are part of other specifications: - - [`fill`](/en-US/docs/Web/SVG/Attribute/fill) - - [`flood-color`](/en-US/docs/Web/SVG/Attribute/flood-color) - - [`lighting-color`](/en-US/docs/Web/SVG/Attribute/lighting-color) - - [`stop-color`](/en-US/docs/Web/SVG/Attribute/stop-color) - - [`stroke`](/en-US/docs/Web/SVG/Attribute/stroke) -- SVG [`color`](/en-US/docs/Web/SVG/Attribute/color) attribute + - [`fill`](/en-US/docs/Web/SVG/Reference/Attribute/fill) + - [`flood-color`](/en-US/docs/Web/SVG/Reference/Attribute/flood-color) + - [`lighting-color`](/en-US/docs/Web/SVG/Reference/Attribute/lighting-color) + - [`stop-color`](/en-US/docs/Web/SVG/Reference/Attribute/stop-color) + - [`stroke`](/en-US/docs/Web/SVG/Reference/Attribute/stroke) +- SVG [`color`](/en-US/docs/Web/SVG/Reference/Attribute/color) attribute - {{glossary("Color wheel")}} glossary term - {{glossary("Interpolation")}} glossary term - The [`@font-palette-values`](/en-US/docs/Web/CSS/@font-palette-values) at-rule [`override-colors`](/en-US/docs/Web/CSS/@font-palette-values/override-colors) descriptor @@ -132,5 +132,5 @@ To see the code for this color syntax converter, [view the source on GitHub](htt - [CSS color adjustment](/en-US/docs/Web/CSS/CSS_color_adjustment) module and the {{cssxref("print-color-adjust")}} property. - [CSS images](/en-US/docs/Web/CSS/CSS_images) module, which is where CSS [`<gradient>`](/en-US/docs/Web/CSS/gradient) images are defined. - The [`VideoColorSpace`](/en-US/docs/Web/API/VideoColorSpace) interface -- The SVG [`<feColorMatrix>`](/en-US/docs/Web/SVG/Element/feColorMatrix) element +- The SVG [`<feColorMatrix>`](/en-US/docs/Web/SVG/Reference/Element/feColorMatrix) element - [Canvas API: applying styles and colors](/en-US/docs/Web/API/Canvas_API/Tutorial/Applying_styles_and_colors#colors) diff --git a/files/en-us/web/css/css_colors/relative_colors/index.md b/files/en-us/web/css/css_colors/relative_colors/index.md index 49958ede2d40d1b..43b911732d9e94b 100644 --- a/files/en-us/web/css/css_colors/relative_colors/index.md +++ b/files/en-us/web/css/css_colors/relative_colors/index.md @@ -100,7 +100,7 @@ To reiterate, when a relative color is defined, the channel values of the origin rgb(from red r g b) ``` -However, when specifying the output values, you don't need to use the origin color channel values at all. You need to provide the output channel values in the right order (e.g. red, then green, then blue in the case of `rgb()`), but they can be any values you wish provided they are valid values for those channels. This gives relative CSS colors a high degree of flexibility. +However, when specifying the output values, you don't need to use the origin color channel values at all. You need to provide the output channel values in the right order (e.g., red, then green, then blue in the case of `rgb()`), but they can be any values you wish provided they are valid values for those channels. This gives relative CSS colors a high degree of flexibility. For example, if you wanted to, you could specify absolute values like those shown below, transforming `red` into `blue`: @@ -318,9 +318,9 @@ This example allows you to choose a base color and a color palette type. The bro The full HTML is included below for reference. The most interesting parts are as follows: -- The `--base-color` custom property is stored as an inline [`style`](/en-US/docs/Web/HTML/Global_attributes/style) on the {{htmlelement("div")}} element with the ID of `container`. We've placed it there so it is easy to update the value using JavaScript. We've provided an initial value of `#ff0000` (`red`) to show a color palette based on that value when the example loads. Note that normally we'd probably set this on the {{htmlelement("html")}} element, but the MDN live sample was removing it when rendering. -- The base color picker is created using an [`<input type="color">`](/en-US/docs/Web/HTML/Element/input/color) control. When a new value is set in this control, the `--base-color` custom property is set to this value using JavaScript, which in turn generates a new color palette. All the displayed colors are relative colors based on `--base-color`. -- The set of [`<input type="radio">`](/en-US/docs/Web/HTML/Element/input/radio) controls enables choosing a color palette type to generate. When a new value is chosen here, JavaScript is used to set a new class on the `container` `<div>` to represent the chosen palette. In the CSS, descendant selectors are used to target the child `<div>`s (e.g. `.comp :nth-child(1)`) so they can have the correct colors applied to them and hide the unused `<div>` nodes. +- The `--base-color` custom property is stored as an inline [`style`](/en-US/docs/Web/HTML/Reference/Global_attributes/style) on the {{htmlelement("div")}} element with the ID of `container`. We've placed it there so it is easy to update the value using JavaScript. We've provided an initial value of `#ff0000` (`red`) to show a color palette based on that value when the example loads. Note that normally we'd probably set this on the {{htmlelement("html")}} element, but the MDN live sample was removing it when rendering. +- The base color picker is created using an [`<input type="color">`](/en-US/docs/Web/HTML/Reference/Elements/input/color) control. When a new value is set in this control, the `--base-color` custom property is set to this value using JavaScript, which in turn generates a new color palette. All the displayed colors are relative colors based on `--base-color`. +- The set of [`<input type="radio">`](/en-US/docs/Web/HTML/Reference/Elements/input/radio) controls enables choosing a color palette type to generate. When a new value is chosen here, JavaScript is used to set a new class on the `container` `<div>` to represent the chosen palette. In the CSS, descendant selectors are used to target the child `<div>`s (e.g., `.comp :nth-child(1)`) so they can have the correct colors applied to them and hide the unused `<div>` nodes. - The `container` `<div>` containing the child `<div>`s that display the colors of the generated palette. Note that an initial class of `comp` is set on it, so that the page will display a complementary color scheme when first loaded. ```html @@ -386,7 +386,7 @@ The full HTML is included below for reference. The most interesting parts are as #### CSS -Below we are only showing the CSS that sets the palette colors. Note how, in each case, descendent selectors are used to apply the correct {{cssxref("background-color")}} to each child `<div>` for the chosen palette. We care more about the position of the `<div>`s in the source order than the type of element, so we have used {{cssxref(":nth-child")}} to target them. +Below we are only showing the CSS that sets the palette colors. Note how, in each case, descendant selectors are used to apply the correct {{cssxref("background-color")}} to each child `<div>` for the chosen palette. We care more about the position of the `<div>`s in the source order than the type of element, so we have used {{cssxref(":nth-child")}} to target them. In the last rule we've used the [general sibling selector (`~`)](/en-US/docs/Web/CSS/Subsequent-sibling_combinator) to target the unused `<div>` elements in each palette type, setting [`display: none`](/en-US/docs/Web/CSS/Subsequent-sibling_combinator) to stop them being rendered. @@ -405,7 +405,7 @@ h1 { margin-left: 16px; } -/* Simple form styling */ +/* Basic form styling */ #color-picker { margin-left: 16px; @@ -562,7 +562,7 @@ fieldset { In the example CSS you'll notice {{cssxref("@supports")}} blocks being used to provide different {{cssxref("background-color")}} values to browsers that support a previous draft specification of the relative color syntax. These are required because Safari's initial implementation was based on an older version of the spec in which origin color channel values resolved to {{cssxref("&lt;number&gt;")}}s or other unit types depending on the context. This meant that values sometimes required units when performing additions and subtractions, which created confusion. In newer implementations, origin color channel values always resolve to an equivalent {{cssxref("&lt;number&gt;")}} value, which means calculations are always done with unitless values. -Note how the support test in each case is done using a simple declaration — `color: lch(from red l c calc(h + 90deg))` for example — rather than the actual value that we need to vary for other browsers. When testing complex values like these, you should use the simplest possible declaration that still contains the syntactic difference you want to test for. +Note how the support test in each case is done using any color declaration — `color: lch(from red l c calc(h + 90deg))` for example — not necessarily the actual value that we need to vary for other browsers. When testing complex values like these, you should use the simplest possible declaration that still contains the syntactic difference you want to test for. Including a custom property in the `@supports` test doesn't work — the test always comes back as positive regardless of what value the custom property is given. This is because a custom property value only becomes invalid when assigned to be an invalid value (or part of an invalid value) of a regular CSS property. To work around this, in each test we have replaced `var(--base-color)` with the `red` keyword. @@ -605,7 +605,7 @@ The output is as follows. This starts to show the power of relative CSS colors ### Live UI color scheme updater -This example shows a card containing a heading and text, but with a twist — below the card is a slider ([`<input type="range">`](/en-US/docs/Web/HTML/Element/input/range)) control. When its value is changed, JavaScript is used to set a `--hue` custom property value to the new slider value. +This example shows a card containing a heading and text, but with a twist — below the card is a slider ([`<input type="range">`](/en-US/docs/Web/HTML/Reference/Elements/input/range)) control. When its value is changed, JavaScript is used to set a `--hue` custom property value to the new slider value. This in turn adjusts the color scheme for the entire UI: @@ -617,8 +617,8 @@ This in turn adjusts the color scheme for the entire UI: The HTML for the example is shown below. - The {{htmlelement("main")}} element acts as an outer wrapper to contain the rest of the content, allowing the card and form to be centered vertically and horizontally inside `<main>` as one unit. -- The {{htmlelement("section")}} element contains the [`<h1>`](/en-US/docs/Web/HTML/Element/Heading_Elements) and {{htmlelement("p")}} elements that define the card's content. -- The {{htmlelement("form")}} element contains the ([`<input type="range">`](/en-US/docs/Web/HTML/Element/input/range)) control and its {{htmlelement("label")}}. +- The {{htmlelement("section")}} element contains the [`<h1>`](/en-US/docs/Web/HTML/Reference/Elements/Heading_Elements) and {{htmlelement("p")}} elements that define the card's content. +- The {{htmlelement("form")}} element contains the ([`<input type="range">`](/en-US/docs/Web/HTML/Reference/Elements/input/range)) control and its {{htmlelement("label")}}. ```html <main> diff --git a/files/en-us/web/css/css_colors/using_color_wisely/index.md b/files/en-us/web/css/css_colors/using_color_wisely/index.md index 1e53c28c13053df..89dc2182af3afb1 100644 --- a/files/en-us/web/css/css_colors/using_color_wisely/index.md +++ b/files/en-us/web/css/css_colors/using_color_wisely/index.md @@ -48,11 +48,11 @@ A full review of color theory is beyond the scope of this article, however, ther Make sure your content is [accessible](/en-US/docs/Web/Accessibility). There are several ways color can create an {{Glossary("accessibility")}} problem. Improper or careless use of color can result in a website or app that a percentage of your target audience may not be able to use adequately, resulting in lost traffic, lost business, and possibly even a public relations problem or a lawsuit. So it's important to consider your use of color carefully. -It's important to [understand color and luminance](/en-US/docs/Web/Accessibility/Understanding_Colors_and_Luminance) and to always consider [color blindness](https://medlineplus.gov/colorblindness.html) and [vestibular disorders](/en-US/docs/Web/Accessibility/Seizure_disorders). There are several kinds; the most common is red-green color blindness, which causes people to be unable to differentiate between the colors red and green. There are others, too, ranging from an inability to tell the difference between certain colors to the total inability to see color at all. There are even color and animation combinations that can lead your photosensitive users to experience [seizures](/en-US/docs/Web/Accessibility/Seizure_disorders#colors). +It's important to [understand color and luminance](/en-US/docs/Web/Accessibility/Guides/Colors_and_Luminance) and to always consider [color blindness](https://medlineplus.gov/colorblindness.html) and [vestibular disorders](/en-US/docs/Web/Accessibility/Guides/Seizure_disorders). There are several kinds; the most common is red-green color blindness, which causes people to be unable to differentiate between the colors red and green. There are others, too, ranging from an inability to tell the difference between certain colors to the total inability to see color at all. There are even color and animation combinations that can lead your photosensitive users to experience [seizures](/en-US/docs/Web/Accessibility/Guides/Seizure_disorders#colors). -While higher [color contrast](https://digital.gov/guides/accessibility-for-teams/visual-design/#color-and-contrast) is often a good thing when it comes to accessibility, when animating, especially rapidly, [reducing color contrast](/en-US/docs/Web/Accessibility/Seizure_disorders#reduce_contrast) on animating elements reduces seizure risk. If you include animations, use the [`prefers-reduced-motion`](/en-US/docs/Web/CSS/@media/prefers-reduced-motion) {{cssxref("@media")}} query feature to reduce animations for users who have selected that preference. +While higher [color contrast](https://digital.gov/guides/accessibility-for-teams/visual-design/#color-and-contrast) is often a good thing when it comes to accessibility, when animating, especially rapidly, [reducing color contrast](/en-US/docs/Web/Accessibility/Guides/Seizure_disorders#reduce_contrast) on animating elements reduces seizure risk. If you include animations, use the [`prefers-reduced-motion`](/en-US/docs/Web/CSS/@media/prefers-reduced-motion) {{cssxref("@media")}} query feature to reduce animations for users who have selected that preference. -That said, ensure you have enough [color contrast](/en-US/docs/Web/Accessibility/Understanding_WCAG/Perceivable/Color_contrast) between your background and foreground content to ensure legibility. Also, never use color as the only way to convey information. If, for example, you indicate the success of an operation with a green border around the associated UI element, and failure with a red border, users with red-green color blindness won't be able to use your site properly. Instead, use text and color indicators together to include those users. For example, a green check mark and a red cross mark would be better. +That said, ensure you have enough [color contrast](/en-US/docs/Web/Accessibility/Guides/Understanding_WCAG/Perceivable/Color_contrast) between your background and foreground content to ensure legibility. Also, never use color as the only way to convey information. If, for example, you indicate the success of an operation with a green border around the associated UI element, and failure with a red border, users with red-green color blindness won't be able to use your site properly. Instead, use text and color indicators together to include those users. For example, a green check mark and a red cross mark would be better. ## Palette design example @@ -104,6 +104,6 @@ With this set, the browser won't tamper with the appearance of the element on wh - [CSS color values](/en-US/docs/Web/CSS/CSS_colors/Color_values) - [Using relative colors](/en-US/docs/Web/CSS/CSS_colors/Relative_colors) - [CSS color module](/en-US/docs/Web/CSS/CSS_colors) -- [Understanding color and luminance](/en-US/docs/Web/Accessibility/Understanding_Colors_and_Luminance) -- [WCAG 1.4.1: Color contrast](/en-US/docs/Web/Accessibility/Understanding_WCAG/Perceivable/Color_contrast) +- [Understanding color and luminance](/en-US/docs/Web/Accessibility/Guides/Colors_and_Luminance) +- [WCAG 1.4.1: Color contrast](/en-US/docs/Web/Accessibility/Guides/Understanding_WCAG/Perceivable/Color_contrast) - [Paletton](https://paletton.com/) diff --git a/files/en-us/web/css/css_compositing_and_blending/index.md b/files/en-us/web/css/css_compositing_and_blending/index.md index 576e75eac2d16e7..8fec98dd16277f0 100644 --- a/files/en-us/web/css/css_compositing_and_blending/index.md +++ b/files/en-us/web/css/css_compositing_and_blending/index.md @@ -9,7 +9,7 @@ spec-urls: {{CSSRef}} -The **CSS compositing and blending** module defines how an element's background layers can be blended together, how an element can be blended with its container, and whether the element must create a new [stacking context](/en-US/docs/Web/CSS/CSS_positioned_layout/Understanding_z-index/Stacking_context). +The **CSS compositing and blending** module defines how an element's background layers can be blended together, how an element can be blended with its container, and whether the element must create a new [stacking context](/en-US/docs/Web/CSS/CSS_positioned_layout/Stacking_context). The properties in this CSS module can be used to define the blending mode that should be used, if any, to blend an element's background images and colors into a single background image. This module provides 16 blending modes. You can also define how an element's borders, background, and content, including text, emojis, and images, should be blended with the background of its container. diff --git a/files/en-us/web/css/css_conditional_rules/container_scroll-state_queries/index.md b/files/en-us/web/css/css_conditional_rules/container_scroll-state_queries/index.md new file mode 100644 index 000000000000000..842d9e0a4f4a9a2 --- /dev/null +++ b/files/en-us/web/css/css_conditional_rules/container_scroll-state_queries/index.md @@ -0,0 +1,847 @@ +--- +title: Using container scroll-state queries +slug: Web/CSS/CSS_conditional_rules/Container_scroll-state_queries +page-type: guide +--- + +{{CSSRef}} + +**Container scroll-state queries** are a type of [container query](/en-US/docs/Web/CSS/@container). Rather than selectively applying styles to descendant elements based on the container's size, scroll-state queries allow you to selectively apply styles to descendant elements based on the container's scroll state. This can include whether the container is partially scrolled, snapped to a [scroll snap container](/en-US/docs/Glossary/Scroll_snap#scroll_snap_container) ancestor, or positioned via [`position: sticky`](/en-US/docs/Web/CSS/position) and stuck to a boundary of a {{glossary("scroll container")}} ancestor. + +This article explains how to use container scroll-state queries, walking through an example of each type. It assumes that you know the basics of container queries. If you are new to container queries, read [CSS container queries](/en-US/docs/Web/CSS/CSS_containment/Container_queries) before continuing. + +## Types of container scroll-state query + +There are three `@container` descriptors you can use in a `scroll-state()` query: + +- `scrollable`: Queries whether a container can be scrolled in the given direction via user-initiated scrolling (for example by dragging the scrollbar or using a trackpad gesture). In other words, is there any overflowing content in the given direction that can be scrolled to? This is useful for applying styling related to the scroll position of a scroll container. For example, you could display a hint that encourages people to scroll down and see more content when the scrollbar is up at the top, and hide it when the user has actually started scrolling. +- `snapped`: Queries whether a container is, or will be, snapped to a [scroll snap](/en-US/docs/Web/CSS/CSS_scroll_snap) container ancestor along a given axis. This is useful for applying styles when an element is snapped to a scroll snap container. For example, you might want to highlight a snapped element in some way, or reveal some of its content that was previously hidden. +- `stuck`: Queries whether a container with a {{cssxref("position")}} value of `sticky` is stuck to an edge of its scroll container ancestor. This is useful for styling `position: sticky` elements differently when stuck — for example, you could give them a different color scheme or layout. + +## Syntax overview + +To establish a container element as a scroll-state query container, set the {{cssxref("container-type")}} property on it with a value of `scroll-state`. You can optionally also give it a {{cssxref("container-name")}}, so that you can target it with a specific container query: + +```css +.container { + container-type: scroll-state; + container-name: my-container; +} +``` + +You can then create a {{cssxref("@container")}} block that specifies the query, the rules that are applied to children of the container if the test passes, and optionally, the `container-name` of the container(s) you want to query. If you don't specify a `container-name`, the container query will be applied to all scroll-state query containers on the page. + +Here, we query only containers named `my-container` to determine whether the container can be scrolled towards its top edge: + +```css +@container my-container scroll-state(scrollable: top) { + /* CSS rules go here */ +} +``` + +> [!NOTE] +> To separate scroll-state queries from other container queries, the scroll-state descriptors and value are placed inside parentheses, preceded by `scroll-state` (`scroll-state( ... )`). These constructs look like functions, but they're not. + +## Using `scrollable` queries + +Scroll-state [`scrollable`](/en-US/docs/Web/CSS/@container#scrollable) queries, written as `scroll-state(scrollable: value)`, test whether a container's scrolling ancestor can be scrolled in the given direction via user-initiated scrolling. If not, the query returns false. + +The `value` indicates the direction you are testing for scrolling availability in, for example: + +- `top`: Tests whether the container can be scrolled towards its top edge. +- `inline-end`: Tests whether the container can be scrolled towards its inline-end edge. +- `y`: Tests whether the container can be scrolled in either or both directions along its y axis. + +If the test passes, the rules inside the `@container` block are applied to descendants of the matching scroll container. + +Let's look at an example in which we have a scrolling container full of content, and a handy little link to scroll back to the top if wished. We will use a `scrollable` query to only show the link when the user has started to scroll down through the content. + +### HTML + +In the HTML we have an {{htmlelement("article")}} element containing enough content to cause the document to scroll, preceded by a [back-to-top link](/en-US/docs/Web/HTML/Reference/Elements/a#result_8): + +```html +<a class="back-to-top" href="#" aria-label="Top of page">↑</a> +<article> + <h1>Reader with container query-controlled "back-to-top" link</h1> + <section> + <header> + <h2>This first section is interesting</h2> + + <p>Lorem ipsum dolor sit amet, consectetur adipiscing elit.</p> + </header> + + ... + </section> + + ... +</article> +``` + +We have hidden most of the HTML for brevity. + +```html hidden live-sample___scrollable +<a class="back-to-top" href="#" aria-label="Scroll back to top">↑</a> +<article> + <h1>Reader with container query-controlled "back-to-top" link</h1> + <section> + <header> + <h2>This first section is interesting</h2> + + <p>Lorem ipsum dolor sit amet, consectetur adipiscing elit.</p> + </header> + + <p> + Mauris non malesuada est, sed vestibulum nibh. Duis vestibulum iaculis + lectus, eu sagittis dolor dignissim iaculis. Nunc et orci sed sapien + eleifend placerat. Curabitur dapibus risus eget odio sollicitudin, sit + amet luctus justo pellentesque. + </p> + + <p> + <strong>Morbi non pharetra quam.</strong> Fusce vestibulum sem diam, ac + consequat augue consectetur ut. Donec at augue viverra, tempus urna sit + amet, porta augue. + <em>Phasellus fringilla tincidunt sem ullamcorper varius.</em> Aenean + gravida feugiat sem nec ultricies. + </p> + + <img src="#" alt="Placeholder" /> + + <p> + Sed pellentesque placerat mi sed maximus. Sed vitae dui vitae mi pulvinar + gravida sed et libero. + <a href="#">Duis nec venenatis dolor, sed tristique felis.</a> + Integer dapibus facilisis leo elementum vulputate. Curabitur a urna quis + nulla vulputate tincidunt quis ac enim. + </p> + + <p> + Cras non elit vel leo dignissim convallis. Duis eros urna, varius sit amet + lorem vel, feugiat euismod est. + <strong>Aliquam ornare eu elit ut iaculis.</strong> + Suspendisse vulputate tempor leo, non rhoncus risus aliquam vel. + </p> + </section> + <section> + <header> + <h2>This one, not so much</h2> + + <p>Suspendisse varius est ac turpis mollis cursus.</p> + </header> + + <p> + <strong + >Curabitur faucibus condimentum eros, ut auctor felis lacinia + sed.</strong + > + Praesent vitae scelerisque eros. + </p> + + <p> + <em>Ut vitae suscipit augue.</em> Cras et orci condimentum ante dignissim + iaculis. Sed consectetur quis est sed dignissim. Nulla egestas orci erat, + et commodo arcu feugiat ut. + </p> + + <img src="#" alt="Placeholder" /> + + <p> + Sed non tempor massa, at accumsan ante. Pellentesque habitant morbi + <a href="#">tristique senectus</a> et netus et malesuada fames ac turpis + egestas. + </p> + + <p> + Pellentesque placerat luctus tempor. Nunc congue dapibus eros, at + vulputate nulla. Sed rutrum eleifend magna vel porta. Integer cursus orci + faucibus turpis scelerisque, nec pharetra arcu molestie. + </p> + </section> + <section> + <header> + <h2>Hopefully this section provides some clarity?</h2> + + <p>Curabitur facilisis ornare lorem et eleifend.</p> + </header> + + <p> + <strong>Aenean mollis non neque sed finibus.</strong> Lorem ipsum dolor + sit amet, consectetur adipiscing elit. Suspendisse sagittis viverra urna. + In hac habitasse platea dictumst. Vestibulum neque orci, mollis sagittis + augue et, pharetra vehicula diam. + </p> + + <img src="#" alt="Placeholder" /> + + <p> + <a href="#">Pellentesque sollicitudin</a> nunc quis nisl condimentum, ac + iaculis libero feugiat. + <strong>Nullam ultrices purus a nulla dignissim hendrerit.</strong> In + molestie consectetur est quis pulvinar. + </p> + + <p> + Vivamus ac erat eu est lobortis commodo. Orci varius natoque penatibus et + magnis dis parturient montes, nascetur ridiculus mus. In nulla turpis, + <strong>mollis et est tempor</strong>, dignissim aliquam metus. Proin eu + arcu quis erat mollis pulvinar. Vivamus at facilisis neque. + </p> + + <p> + Integer bibendum laoreet erat, quis vulputate mauris bibendum nec. Class + aptent taciti sociosqu ad litora torquent per conubia nostra, per inceptos + himenaeos. Nam ut est in arcu interdum hendrerit. + </p> + </section> + <section> + <header> + <h2>A summary of sorts</h2> + + <p>Nunc facilisis augue quis ex porta aliquam.</p> + </header> + + <img src="#" alt="Placeholder" /> + + <p> + <strong + >Fusce nisi enim, venenatis a est vel, varius placerat lacus.</strong + > + Nunc tempus rutrum nisl bibendum aliquet. Pellentesque vitae nunc sed nisl + tincidunt elementum a sit amet nisi. Morbi pretium at dolor in pulvinar. + Curabitur dapibus eleifend accumsan. + </p> + + <p> + Donec rhoncus, leo vitae mollis maximus, tellus lorem interdum arcu, eu + <em>tempor lectus libero in risus</em>. Ut sit amet magna vitae mauris + tempor bibendum. <a href="#">Integer id mauris ut ex mattis finibus.</a> + </p> + + <p> + Curabitur dui felis, elementum et tellus id, blandit facilisis lorem. + Aliquam sed posuere ligula, at auctor ipsum. Morbi dignissim accumsan + tellus pretium iaculis. + </p> + </section> +</article> +``` + +### CSS + +The `.back-to-top` link is given a {{cssxref("position")}} value of `fixed`, placed at the bottom-right corner of the viewport, and moved off the viewport using a {{cssxref("translate")}} value of `80px 0`. A {{cssxref("transition")}} value will animate the `translate` and {{cssxref("background-color")}} when either value changes. + +```css hidden live-sample___scrollable +/* General styling */ + +* { + box-sizing: border-box; +} + +html { + font-family: Arial, Helvetica, sans-serif; + height: 100%; +} + +body { + height: inherit; + width: 100%; + max-width: 540px; + padding: 20px; + margin: 0 auto; +} + +p { + line-height: 1.5; +} + +img { + display: block; + width: 90%; + margin: 30px auto; + padding: 20px; + border: 2px solid gray; + aspect-ratio: 3/2; +} +``` + +```css live-sample___scrollable +.back-to-top { + width: 64px; + height: 64px; + color: white; + text-align: center; + position: fixed; + bottom: 10px; + right: 10px; + translate: 80px 0; + transition: + 0.4s translate, + 0.2s background-color; +} +``` + +```css hidden live-sample___scrollable +.back-to-top { + text-decoration: none; + border-radius: 50%; + border: 1px solid #0007; + background-color: #0007; + color: white; + font-size: 3rem; + text-shadow: 0 0 2px black; + padding-bottom: 10px; +} + +.back-to-top:hover, +.back-to-top:focus { + background: #0009; +} +``` + +The {{glossary("scroll container")}} in this example is the `<html>` element itself, denoted as a scroll-state query container with a {{cssxref("container-type")}} value of `scroll-state`. The {{cssxref("container-name")}} isn't strictly necessary but is useful in cases where the code is added to a codebase with multiple scroll-state query containers targeted with different queries. + +```css live-sample___scrollable +html { + container-type: scroll-state; + container-name: scroller; +} +``` + +Next, we define a {{cssxref("@container")}} block that sets the container name targeted by this query, and the query itself — `scrollable: top`. This query applies the rules contained inside the block only if the `<html>` element can be scrolled toward its top edge — in other words, if the container has previously been scrolled downwards. If that is the case, `translate: 0 0` is applied to the `.back-to-top` link, which transitions it back on-screen. + +```css live-sample___scrollable +@container scroller scroll-state(scrollable: top) { + .back-to-top { + translate: 0 0; + } +} +``` + +We've hidden the rest of the example CSS for brevity. + +### Result + +{{EmbedLiveSample("scrollable", "100%", "400px")}} + +Try scrolling the document down, and note how the "back-to-top" link appears as a result, animating smoothly from the right side of the viewport due to the `transition`. If you scroll back to the top by activating the link or manually scrolling, the "back-to-top" link transitions off-screen. + +## Using `snapped` queries + +Relevant only when [scroll snapping](/en-US/docs/Web/CSS/CSS_scroll_snap) is implemented, scroll-state [`snapped`](/en-US/docs/Web/CSS/@container#snapped) queries (written as `scroll-state(snapped: value)`) test whether a container is, or will be, snapped to a [scroll snap container](/en-US/docs/Glossary/Scroll_snap#scroll_snap_container) ancestor along the given axis. If not, the query returns false. + +The `value` in this case indicates the direction you are testing the element's ability to snap in, for example: + +- `x`: Tests whether the container is snapping horizontally to its scroll-snap container ancestor. +- `inline`: Tests whether the container is snapping to its scroll-snap container ancestor in the inline direction. +- `y`: Tests whether the container is snapping to its scroll-snap container ancestor in both directions. + +To evaluate a container with a non-`none` `snapped` scroll-state query, it must be a container with a scroll-snap container ancestor, that is, the ancestor has a {{cssxref("scroll-snap-type")}} value other than `none`. The container query `scroll-state(snapped: none)` matches scroll-state containers that do not have a scroll container ancestor. + +Evaluation will occur when the [`scrollsnapchanging`](/en-US/docs/Web/API/Element/scrollsnapchanging_event) event fires on the scroll snap container. + +If the test passes, the rules inside the `@container` block are applied to descendants of the matching scroll snap target container. + +In this example, we'll look at a scroll snap container with children that snap to it vertically and use a `snapped` query to style the children only when they are snapped or about to be snapped. + +### HTML + +The HTML consists of a {{htmlelement("main")}} element that will be a scroll snap container. Inside are several {{htmlelement("section")}} elements that will be snap targets. Each `<section>` contains a wrapper {{htmlelement("div")}} and an `<h2>` [heading](/en-US/docs/Web/HTML/Reference/Elements/Heading_Elements). The wrappers are included to create a style target as container queries enable styling a container's descendants, not the container itself. + +```html +<main> + <section> + <div class="wrapper"> + <h2>Section 1</h2> + </div> + </section> + + ... +</main> +``` + +We have hidden most of the HTML for brevity. + +```html hidden live-sample___snapped +<main> + <section> + <div class="wrapper"> + <h2>Section 1</h2> + </div> + </section> + <section> + <div class="wrapper"> + <h2>Section 2</h2> + </div> + </section> + <section> + <div class="wrapper"> + <h2>Section 3</h2> + </div> + </section> + <section> + <div class="wrapper"> + <h2>Section 4</h2> + </div> + </section> + <section> + <div class="wrapper"> + <h2>Section 5</h2> + </div> + </section> + <section> + <div class="wrapper"> + <h2>Section 6</h2> + </div> + </section> + <section> + <div class="wrapper"> + <h2>Section 7</h2> + </div> + </section> + <section> + <div class="wrapper"> + <h2>Section 8</h2> + </div> + </section> + <section> + <div class="wrapper"> + <h2>Section 9</h2> + </div> + </section> + <section> + <div class="wrapper"> + <h2>Section 10</h2> + </div> + </section> + <section> + <div class="wrapper"> + <h2>Section 11</h2> + </div> + </section> + <section> + <div class="wrapper"> + <h2>Section 12</h2> + </div> + </section> + <section> + <div class="wrapper"> + <h2>Section 13</h2> + </div> + </section> + <section> + <div class="wrapper"> + <h2>Section 14</h2> + </div> + </section> + <section> + <div class="wrapper"> + <h2>Section 15</h2> + </div> + </section> + <section> + <div class="wrapper"> + <h2>Section 16</h2> + </div> + </section> +</main> +``` + +### CSS + +```css hidden live-sample___snapped +* { + box-sizing: border-box; +} + +html { + height: 100%; +} + +/* body and main sizing */ + +body { + display: flex; + align-items: center; + justify-content: center; + height: inherit; +} + +main { + gap: 50px; +} +``` + +We set an {{cssxref("overflow")}} value of `scroll` and a fixed {{cssxref("height")}} on the `<main>` element to turn it into a vertical scroll container. We also set a {{cssxref("scroll-snap-type")}} value of `y mandatory` to turn `<main>` into a scroll snap container that snap targets will snap to along the y axis; `mandatory` means that a snap target will _always_ be snapped to. + +```css live-sample___snapped +main { + overflow: scroll; + scroll-snap-type: y mandatory; + height: 450px; + width: 250px; + border: 3px solid black; +} +``` + +The `<section>` elements are designated as snap targets by setting a non-`none` {{cssxref("scroll-snap-align")}} value. The `center` value means that they will snap to the container at their center points. + +```css live-sample___snapped +section { + font-family: Arial, Helvetica, sans-serif; + width: 150px; + height: 150px; + margin: 50px auto; + + scroll-snap-align: center; +} +``` + +```css hidden live-sample___snapped +.wrapper { + width: 100%; + height: 100%; + border-radius: 5px; + background: #eee; + box-shadow: + inset 1px 1px 4px rgb(255 255 255 / 0.5), + inset -1px -1px 4px rgb(0 0 0 / 0.5); + + display: flex; + align-items: center; + justify-content: center; + + transition: + 0.6s background, + 0.6s color; +} + +h2 { + font-size: 1rem; + letter-spacing: 1px; +} +``` + +We want to enable the `<section>` elements to be queried. Specifically, we want to test whether the `<section>` elements are snapping to their container, so we denote them as scroll-state query containers by setting a {{cssxref("container-type")}} value of `scroll-state` on them. We also give them a {{cssxref("container-name")}}, which isn't strictly necessary, but will be useful if our code gets more complex later and we have multiple scroll-state query containers that we want to target with different queries. + +```css live-sample___snapped +section { + container-type: scroll-state; + container-name: snap-container; +} +``` + +Next, we define a {{cssxref("@container")}} block that sets the container name we are targeting with this query, and the query itself — `snapped: y`. This query applies the rules contained inside the block only if a `<section>` element is being snapped vertically to its container. If that is the case, we apply a new {{cssxref("background")}} and {{cssxref("color")}} to the `<section>` element's child `.wrapper` `<div>` to highlight it. + +```css live-sample___snapped +@container snap-container scroll-state(snapped: y) { + .wrapper { + background: purple; + color: white; + } +} +``` + +### Result + +The rendered result is shown below. Try scrolling the container up and down, and note how the `<section>` style changes when it becomes snapped to its container. + +{{EmbedLiveSample("snapped", "100%", "500px")}} + +## Using `stuck` queries + +Scroll-state [`stuck`](/en-US/docs/Web/CSS/@container#scrollable) queries, written as `scroll-state(stuck: value)`, test whether a container with a {{cssxref("position")}} value of `sticky` is stuck to an edge of its scroll container ancestor. If not, the query returns false. + +The `value` in this case indicates the scroll container edge you are testing, for example: + +- `top`: Tests whether the container is stuck to the top edge of its scroll container ancestor. +- `block-end`: Tests whether the container is stuck to the block-end edge of its scroll container ancestor. +- `none`: Tests whether the container is not stuck to any edges of its scroll container ancestor. Note that `none` queries will match even if the container does not have `position: sticky` set on it. + +If the query returns true, the rules inside the `@container` block are applied to descendants of the matching `position: sticky` container. + +Let's look at an example where we have a scrolling container with overflowing content, in which the headings are set to `position: sticky` and stick to the top edge of the container when they scroll to that position. We will use a `stuck` scroll-state query to style the headings differently when they are stuck to the top edge. + +### HTML + +In the HTML, we have an {{htmlelement("article")}} element containing enough content to cause the document to scroll. It is structured using several {{htmlelement("section")}} elements, each containing a {{htmlelement("header")}} with nested content: + +```html +<article> + <h1>Sticky reader with scroll-state container query</h1> + <section> + <header> + <h2>This first section is interesting</h2> + + <p>Lorem ipsum dolor sit amet, consectetur adipiscing elit.</p> + </header> + + ... + </section> + + <section> + <header> + <h2>This one, not so much</h2> + + <p>Confecta res esset.</p> + </header> + + ... + </section> + + ... +</article> +``` + +We have hidden most of the HTML for brevity. + +```html hidden live-sample___stuck +<article> + <h1>Sticky reader with scroll-state container query</h1> + <section> + <header> + <h2>This first section is interesting</h2> + + <p>Lorem ipsum dolor sit amet, consectetur adipiscing elit.</p> + </header> + + <p> + Id deserunt exercitation in incididunt in dolor ipsum enim occaecat quis + officia et. In dolore Lorem anim enim. Dolor nulla deserunt laboris irure + incididunt labore tempor amet consectetur. Commodo eu tempor qui laboris + duis ipsum adipisicing sunt. Do anim laboris commodo aliquip consequat ut + eiusmod mollit sint nostrud sunt exercitation do. + </p> + + <p> + <strong>Est proident voluptate dolore.</strong> Aute irure ea culpa mollit + <em>anim aute proident consectetur.</em> Duis deserunt consequat elit non. + Cupidatat et amet anim labore est. Incididunt aute incididunt ex amet + sint. + </p> + + <img src="#" alt="Placeholder" /> + + <p> + Ullamco duis qui amet sunt eu nulla deserunt dolore officia irure nulla. + <a href="#">Qui enim dolore est virtus;</a> + Erat enim consectetur. + </p> + + <p> + Dolor aliquip officia id esse Lorem ullamco ea veniam. + <strong>Voluptate cillum commodo anim veniam;</strong> + Ad nulla amet anim eu incididunt reprehenderit proident in aliqua sit + commodo magna. + </p> + </section> + <section> + <header> + <h2>This one, not so much</h2> + + <p>Confecta res esset.</p> + </header> + + <p> + <strong>Nam quid possums facere delius?</strong> Tu quidem reddes; Omnis + peccant para dicts. + </p> + + <p> + <em>Pariatur ex cupidatat exercitation</em> reprehenderit quis culpa est + proident pariatur ut. + </p> + + <img src="#" alt="Placeholder" /> + + <p> + Non nulla pariatur cillum pariatur. + <a href="#">Ipsum magna proident fugiat qui duis et.</a> + Reprehenderit sit ipsum ut adipisicing aliqua eiusmod nulla consectetur + deserunt dolor dolor. + </p> + + <p> + Cupidatat deserunt adipisicing adipisicing occaecat voluptate duis laboris + excepteur labore et in aliquip aute. Quis aliquip reprehenderit dolor + nostrud cupidatat nostrud nisi occaecat elit. Magna dolor ullamco eiusmod + deserunt elit cillum qui amet. Dolor ad consequat anim commodo eu sunt do + tempor eu velit est. + </p> + </section> + <section> + <header> + <h2>Hopefully this section provides some clarity?</h2> + + <p>Dolor consectetur esse aute eiusmod ex reprehenderit cupidatat.</p> + </header> + + <p> + <strong>Ipsum quis sint incididunt aliquip</strong>. Duis tempor sunt enim + Lorem ut officia cillum magna. + </p> + + <img src="#" alt="Placeholder" /> + + <p> + <a href="#">Sint modo partes vitae beatae.</a> + Ipsum esse nostrud incididunt ipsum ipsum esse aliquip Lorem enim. + <strong>Sed hoc sane concedays.</strong> Voluptate qui consequat dolor + dolor dolore ex. Enim dolor enim sit proident. Ad laborum incididunt + dolore aliquip exercitation exercitation. Sunt cupidatat esse enim duis + proident. + </p> + + <p> + Labore dolor cupidatat ut velit in minim cupidatat enim nisi proident + eiusmod. + <strong + >Non nostrud consectetur est occaecat ut esse esse tempor eiusmod + non.</strong + > + Cupidatat aliqua dolore est sit ad exercitation nostrud nostrud eu. Qui + consequat et aliquip ea labore. + </p> + + <p> + Pariatur quis quis nostrud exercitation pariatur magna veniam Lorem + commodo cupidatat irure reprehenderit. Nostrud pariatur est pariatur elit + sit ea voluptate minim mollit. Aliqua pariatur cupidatat et cillum. Velit + exercitation adipisicing laboris ullamco. Incididunt id eiusmod id cillum + qui anim. Aliquip minim nostrud excepteur dolore deserunt pariatur eu + eiusmod reprehenderit ullamco magna. + </p> + </section> + <section> + <header> + <h2>A summary of sorts</h2> + + <p>Irure adipisicing occaecat dolore in ex voluptate.</p> + </header> + + <img src="#" alt="Placeholder" /> + + <p> + <strong>An quidem modi?</strong> + <strong + >Excepteur non Lorem ex aliqua est reprehenderit incididunt sunt in + ullamco in et;</strong + > + Aliqua veniam nulla magna anim labore amet proident nisi mollit non. + Consequat incididunt exercitation nisi consequat culpa officia aliqua + veniam. Anim aliqua consectetur pariatur mollit proident incididunt id. + </p> + + <p> + Non labore, inquit, de nomin. <em>Fall igniter possimus.</em> + <a href="#">Preterits, inquit, gaud.</a> + Est commodo adipisicing qui duis excepteur sit ea irure amet voluptate + deserunt anim deserunt. + </p> + + <p> + Ad mollit laboris reprehenderit magna tempor. Consequat pariatur esse + ipsum duis laboris. + </p> + </section> +</article> +``` + +### CSS + +Each `<header>` has a {{cssxref("position")}} value of `sticky` and a {{cssxref("top")}} value of `0`, which sticks them to the top edge of the scroll container. To test whether the `<header>` elements are stuck to the container top edge, they are denoted as scroll-state query containers with a {{cssxref("container-type")}} value of `scroll-state`. The {{cssxref("container-name")}} isn't strictly necessary but will be useful if this code gets added to a code base with multiple scroll-state query containers targeted with different queries. + +```css hidden live-sample___stuck +/* General styling */ + +* { + box-sizing: border-box; +} + +html { + font-family: Arial, Helvetica, sans-serif; + height: 100%; +} + +body { + height: inherit; + width: 100%; + max-width: 540px; + padding: 20px; + margin: 0 auto; +} + +p { + line-height: 1.5; +} + +img { + display: block; + width: 90%; + margin: 30px auto; + padding: 20px; + border: 2px solid gray; + aspect-ratio: 3/2; +} +``` + +```css live-sample___stuck +header { + background: white; + position: sticky; + top: 0; + container-type: scroll-state; + container-name: sticky-heading; +} +``` + +We also give the `<h2>` and `<p>` elements inside the `<header>` elements some basic styling, and a {{cssxref("transition")}} value so they will smoothly animate when their {{cssxref("background")}} values change. + +```css live-sample___stuck +h2, +header p { + margin: 0; + transition: 0.4s background; +} + +h2 { + padding: 20px 5px; + margin-bottom: 10px; +} + +header p { + font-style: italic; + padding: 10px 5px; +} +``` + +Next, we define a {{cssxref("@container")}} block that sets the container name we are targeting with this query, and the query itself — `stuck: top`. This query applies the rules contained inside the block only if a `<header>` element is stuck to the top of its scroll container. When that is the case, a different `background` and a {{cssxref("box-shadow")}} are applied to the contained `<h2>` and `<p>`. + +```css live-sample___stuck +@container sticky-heading scroll-state(stuck: top) { + h2, + p { + background: #ccc; + box-shadow: 0 5px 2px #0007; + } +} +``` + +We have hidden the rest of the CSS for brevity. + +### Result + +Try scrolling the document down and up, and note how the `<h2>` and `<p>` elements transition to a new color scheme when they become stuck to the top of their container's top edge. + +{{EmbedLiveSample("stuck", "100%", "400px")}} + +## See also + +- {{Cssxref("container-name")}} +- {{Cssxref("container-type")}} +- {{Cssxref("position")}} +- {{Cssxref("@container")}} +- [CSS container queries](/en-US/docs/Web/CSS/CSS_containment/Container_queries) +- [Using container size and style queries](/en-US/docs/Web/CSS/CSS_containment/Container_size_and_style_queries) +- [CSS conditional rules](/en-US/docs/Web/CSS/CSS_conditional_rules) module +- [CSS positioning](/en-US/docs/Web/CSS/CSS_positioned_layout) module diff --git a/files/en-us/web/css/css_conditional_rules/index.md b/files/en-us/web/css/css_conditional_rules/index.md index 8ff756dafaa3299..d4181180f602246 100644 --- a/files/en-us/web/css/css_conditional_rules/index.md +++ b/files/en-us/web/css/css_conditional_rules/index.md @@ -89,6 +89,10 @@ There are plans to further extend possible queries by adding the generalized con - : A look at JavaScript and CSS feature detection, including CSS `@supports`. +- [Using container scroll-state queries](/en-US/docs/Web/CSS/CSS_conditional_rules/Container_scroll-state_queries) + + - : Using container scroll-state queries, with an example of each type. + ## Related concepts - [CSS cascading and inheritance](/en-US/docs/Web/CSS/CSS_cascade) module @@ -100,7 +104,7 @@ There are plans to further extend possible queries by adding the generalized con - [`<media-feature>`](/en-US/docs/Web/CSS/@media#media_features) - [`<media-type>`](/en-US/docs/Web/CSS/@media#media_types) - [`<media-condition>`](/en-US/docs/Web/CSS/@media#logical_operators) - - [`<media-query-list>`](/en-US/docs/Web/SVG/Attribute/media) + - [`<media-query-list>`](/en-US/docs/Web/SVG/Reference/Attribute/media) - [CSS logical operators](/en-US/docs/Web/CSS/@media#logical_operators) (`not`, `or`, and `and`) - [CSSOM view](/en-US/docs/Web/CSS/CSSOM_view) module diff --git a/files/en-us/web/css/css_conditional_rules/using_feature_queries/index.md b/files/en-us/web/css/css_conditional_rules/using_feature_queries/index.md index d06c79f1e9d2719..b0e7cbde1fdfb43 100644 --- a/files/en-us/web/css/css_conditional_rules/using_feature_queries/index.md +++ b/files/en-us/web/css/css_conditional_rules/using_feature_queries/index.md @@ -19,7 +19,7 @@ A feature query consists of the `@supports` at-rule followed by the support cond ```css /* `@supports` at-rule */ @supports <support-condition> { - CSS rules to apply + /* CSS rules to apply */ } /* `supports()` function */ @@ -31,11 +31,11 @@ For example, we can apply a set of styles or import an entire stylesheet if the ```css /* `@supports` at-rule */ @supports (color: red) { - CSS rules to apply + /* CSS rules to apply */ } /* `supports()` function */ -@import `/css/styles.css` supports(color: red); +@import "/css/styles.css" supports(color: red); ``` As another example, if you want to check if a browser supports the `row-gap` property you would write the following feature query. It doesn't matter which value you use in a lot of cases: if all you want is to check that the browser supports this property, then any valid value will do. @@ -73,11 +73,11 @@ Expanding on the `color` property example above, here we check if the browser su ```css /* `@supports` at-rule */ @supports (color: AccentColor) { - CSS rules to apply + /* CSS rules to apply */ } /* `supports()` function */ -@import `/css/styles.css` supports(color: AccentColor); +@import "/css/styles.css" supports(color: AccentColor); ``` In these examples, we've used feature queries to check if the user-agent supports a specific value of a CSS property, listing the single declaration within parenthesis. You can test for multiple property values or the lack of support. @@ -89,7 +89,7 @@ In addition to asking the browser if it supports a feature, you can test for the ```css /* `@supports` at-rule with `not` */ @supports not (property: value) { - CSS rules to apply + /* CSS rules to apply */ } ``` @@ -128,7 +128,7 @@ You may need to test support for more than one property in your feature query. T ```css /* multiple feature `@supports` at-rule */ @supports (property1: value) and (property2: value) { - CSS rules to apply + /* CSS rules to apply */ } ``` @@ -168,7 +168,7 @@ You can also use `or` to apply CSS only if one or more declarations are supporte ```css /* any feature `@supports` at-rule */ @supports (property1: value) or (property2: value) { - CSS rules to apply + /* CSS rules to apply */ } ``` @@ -207,7 +207,7 @@ For example, the `selector()` function can be used to import a stylesheet for br ```css /* A `selector()` query within a `supports()` function */ -@import `/css/webkitShadowStyles.css` +@import "/css/webkitShadowStyles.css" supports(selector(::-webkit-inner-spin-button)); ``` diff --git a/files/en-us/web/css/css_containment/container_queries/index.md b/files/en-us/web/css/css_containment/container_queries/index.md index 3f5cf55f6c4d066..f0662bb729af189 100644 --- a/files/en-us/web/css/css_containment/container_queries/index.md +++ b/files/en-us/web/css/css_containment/container_queries/index.md @@ -6,15 +6,21 @@ page-type: guide {{CSSRef}} -Container queries enable you to apply styles to an element based on the size of the element's container. If, for example, a container has less space available in the surrounding context, you can hide certain elements or use smaller fonts. +Container queries enable you to apply styles to an element based on certain attributes of its container: + +- The container's size. +- Styles applied to the container. +- The container's scroll-state or that of its scrolling ancestor. Container queries are an alternative to [media queries](/en-US/docs/Web/CSS/CSS_media_queries), which apply styles to elements based on viewport size or other device characteristics. +This article provides an introduction to using container queries, specifically focusing on size container queries. Other guides discuss [style](/en-US/docs/Web/CSS/CSS_containment/Container_size_and_style_queries#container_style_queries) and [scroll-state](/en-US/docs/Web/CSS/CSS_conditional_rules/Container_scroll-state_queries) container queries in detail. + ![Two different query types. First, a media query based on the viewport's width, which is the full width of the browser. Second, a container query based on the width of a container element.](container-query.svg) -## Using container queries +## Using container size queries -To use container queries, you need to declare a **containment context** on an element so that the browser knows you might want to query the dimensions of this container later. +While container queries apply styles based on the container type, container size queries apply styles specifically based on the container's dimensions. To use container size queries, you need to declare a **containment context** on an element so that the browser knows you might want to query the dimensions of this container later. To do this, use the {{cssxref("container-type")}} property with a value of `size`, `inline-size`, or `normal`. These values have the following effects: @@ -113,6 +119,8 @@ When applying styles to a container using container queries, you can use contain These units specify a length relative to the dimensions of a query container. Components that use units of length relative to their container are more flexible to use in different containers without having to recalculate concrete length values. +If no eligible container is available for the query, the container query length unit defaults to the [small viewport unit](/en-US/docs/Web/CSS/length#small_viewport_units) for that axis (`sv*`). + The container query length units are: - `cqw`: 1% of a query container's width @@ -165,6 +173,7 @@ If you want to use a single-column layout for devices with a smaller viewport, y - CSS {{Cssxref("container-name")}} property - CSS {{cssxref("content-visibility")}} property - [Using container size and style queries](/en-US/docs/Web/CSS/CSS_containment/Container_size_and_style_queries) +- [Using container scroll-state queries](/en-US/docs/Web/CSS/CSS_conditional_rules/Container_scroll-state_queries) - [Say Hello to CSS Container Queries](https://ishadeed.com/article/say-hello-to-css-container-queries/) by Ahmad Shadeed - [Container Queries: a Quick Start Guide](https://www.oddbird.net/2021/04/05/containerqueries/) - [Collection of Container Queries articles](https://github.com/sturobson/Awesome-Container-Queries) diff --git a/files/en-us/web/css/css_containment/container_size_and_style_queries/index.md b/files/en-us/web/css/css_containment/container_size_and_style_queries/index.md index 3fbf44989fc3e23..ce4ea4c31abd94e 100644 --- a/files/en-us/web/css/css_containment/container_size_and_style_queries/index.md +++ b/files/en-us/web/css/css_containment/container_size_and_style_queries/index.md @@ -17,21 +17,28 @@ Container queries are similar to [media queries](/en-US/docs/Web/CSS/CSS_media_q } ``` -There are two types of container queries: _container size queries_ and _container style queries_: +There are three types of container queries: - **Container size queries** - : Size queries enable applying styles to elements based on the current [size](/en-US/docs/Web/CSS/@container#descriptors) of a containing element, including the orientation and {{glossary("aspect ratio")}}. The containing elements need to be explicitly declared as _size query containers_. - **Container style queries** + - : Style queries enable applying styles to elements based on a containing element's style features. Any non-empty element can be a style query container. Currently, the only style feature supported by style queries is CSS [custom properties](/en-US/docs/Web/CSS/CSS_cascading_variables/Using_CSS_custom_properties). In this case, the query returns true or false depending on the computed value of the containing element's custom properties. When container style queries are fully supported, they will enable you to apply styles to any element's descendants based on any property, declaration, or computed value — for example if the container is `display: inline flex` or has a non-transparent background color. +- **[Container scroll-state queries](/en-US/docs/Web/CSS/CSS_conditional_rules/Container_scroll-state_queries)** + + - : Scroll-state queries allow you to selectively apply CSS rules to a container's descendants based on scroll-state conditions, such as whether the queried element is partially scrolled or whether the container is snapped to a scroll snap container. The containing elements need to be explicitly declared as _scroll-state query containers_. + In this guide, we learn the basics of container queries by looking at: 1. [container size queries](#container_size_queries_2), 2. [naming containers](#naming_containers) to limit their scope, and 3. using the `style()` functional notation within the {{cssxref("@container")}} at rule's `<container-condition>` to create [style queries with custom properties](#style_queries_for_custom_properties). +Scroll-state queries are discussed in [Using container scroll-state queries](/en-US/docs/Web/CSS/CSS_conditional_rules/Container_scroll-state_queries). + ## Container size queries Container size queries are filtered by a size condition. The associated styles are applied to contained elements if the container element has been declared to be a container and the container condition is true for that element. An element's size container is the nearest ancestor with containment. @@ -172,7 +179,7 @@ The `<style-query>` parameter of the `style()` functional notation can include j ##### Unregistered custom properties -When CSS variables are introduced via a simple CSS custom property value assignment, valueless custom property queries always return true. +When CSS variables are introduced via a CSS custom property value assignment, valueless custom property queries always return true. ```css :root { @@ -193,7 +200,7 @@ The behavior of registered custom properties is different. When explicitly defin ```css @property --theme-color { initial-value: rebeccapurple; - inherited: true; + inherits: true; } :root { @@ -221,7 +228,7 @@ If a style query includes a value for the custom property, the element's compute } ``` -This container style query matches any element that has `blue` as the {{cssxref("computed_value")}} of the `--accent-color` custom property. +This container style query matches any element that has `blue` as the [computed value](/en-US/docs/Web/CSS/CSS_cascade/Value_processing#computed_value) of the `--accent-color` custom property. In this case, other color values equivalent to sRGB `blue` (such as the hexadecimal code `#0000ff`) will match only if the `--accent-color` property was defined as a color with `@property` or `CSS.registerProperty()`, for example: @@ -274,8 +281,8 @@ const body = document.querySelector("body"); const other = document.getElementById("other"); const color = document.getElementById("color"); -for (let i = 0; i < radios.length; i++) { - radios[i].addEventListener("change", (e) => { +for (const radio of radios) { + radio.addEventListener("change", (e) => { body.style.setProperty("--theme", e.target.value); }); } @@ -412,6 +419,7 @@ These features are not yet supported in any browser. - CSS {{Cssxref("contain")}} property - CSS {{Cssxref("container")}} shorthand property - CSS {{Cssxref("container-name")}} property +- [Using container scroll-state queries](/en-US/docs/Web/CSS/CSS_conditional_rules/Container_scroll-state_queries) - [Understanding `aspect-ratio`](/en-US/docs/Web/CSS/CSS_box_sizing/Understanding_aspect-ratio) - [Getting Started with Style Queries](https://developer.chrome.com/docs/css-ui/style-queries) (2022) - [Style queries](https://una.im/style-queries/) via una.im (2022) diff --git a/files/en-us/web/css/css_containment/index.md b/files/en-us/web/css/css_containment/index.md index 4288ceeecc9b9c6..17ff8c5467ff0ec 100644 --- a/files/en-us/web/css/css_containment/index.md +++ b/files/en-us/web/css/css_containment/index.md @@ -75,7 +75,7 @@ Container queries are similar to dimension [media queries](/en-US/docs/Web/CSS/C - {{CSSxRef("aspect-ratio")}} property - {{cssxref("contain-intrinsic-size")}} shorthand property - {{CSSxRef("contain-intrinsic-inline-size")}} property - - {{CSSxRef("contain-intrinsic-size")}} property + - {{CSSxRef("contain-intrinsic-block-size")}} property - {{CSSxRef("contain-intrinsic-width")}} property - {{CSSxRef("contain-intrinsic-height")}} property diff --git a/files/en-us/web/css/css_containment/using_css_containment/index.md b/files/en-us/web/css/css_containment/using_css_containment/index.md index 4c99ae90c557427..80cbcb7c690435a 100644 --- a/files/en-us/web/css/css_containment/using_css_containment/index.md +++ b/files/en-us/web/css/css_containment/using_css_containment/index.md @@ -46,7 +46,7 @@ It tells the browser that the internal layout of the element is completely separ By setting `contain: content` on each `<article>` we have indicated this; we have told the browser that each article is independent. The browser can then use this information to make decisions about how to render each `<article>` of content. For example, it might not render articles that are outside the viewable area. -When additional articles are appended at the end of the page, the browser does not need to recalculate layout or repaint the preceding content; it also doesn't need to touch any area outside of the containing element's subtree. If box model properties are dependent, however, the browser will need to recalculate layout and repaint. For example, if the `<article>` is styled such that its size depends on its contents (e.g. with `height: auto`), then the browser will need to account for its size changing. +When additional articles are appended at the end of the page, the browser does not need to recalculate layout or repaint the preceding content; it also doesn't need to touch any area outside of the containing element's subtree. If box model properties are dependent, however, the browser will need to recalculate layout and repaint. For example, if the `<article>` is styled such that its size depends on its contents (e.g., with `height: auto`), then the browser will need to account for its size changing. ## Key concepts and terminology @@ -69,7 +69,7 @@ In addition: - {{cssxref("float")}} layout will be performed independently inside the specified element. - Margins won't collapse across a layout containment boundary. - The layout container is a [containing block](/en-US/docs/Web/CSS/CSS_display/Containing_block) for `absolute`- and `fixed`-positioned descendants. -- The containing box creates a [stacking context](/en-US/docs/Web/CSS/CSS_positioned_layout/Understanding_z-index/Stacking_context), therefore {{cssxref("z-index")}} can be used. +- The containing box creates a [stacking context](/en-US/docs/Web/CSS/CSS_positioned_layout/Stacking_context), therefore {{cssxref("z-index")}} can be used. > [!NOTE] > The `style` and `layout` values of `contain` are automatically applied when using the {{cssxref("container-type")}} and {{cssxref("container-name")}} properties. @@ -82,7 +82,7 @@ article { } ``` -Paint containment essentially clips the box to the padding edge of the [principal box](/en-US/docs/Web/CSS/Visual_formatting_model#the_principal_box). There can be no visible overflow. The same additional notes are true for `paint` containment as `layout` containment (see above). +Paint containment essentially clips the box to the padding edge of the [principal box](/en-US/docs/Web/CSS/CSS_display/Visual_formatting_model#the_principal_box). There can be no visible overflow. The same additional notes are true for `paint` containment as `layout` containment (see above). Another advantage is that if the element with containment applied is offscreen, the browser does not need to paint its child elements — these are also offscreen as they are contained completely by that box. @@ -101,7 +101,7 @@ If you set `contain: size` on an element, you need to specify the size of the el ```css article { contain: size; - contain-intrinsic-size: 100vw auto; + contain-intrinsic-size: 100vw auto none; } ``` @@ -136,7 +136,7 @@ To remove this risk, always set a size when using `strict`: ```css article { contain: strict; - contain-intrinsic-size: 80vw auto; + contain-intrinsic-size: 80vw auto none; } ``` @@ -145,7 +145,7 @@ The above is the same as: ```css article { contain: size layout paint style; - contain-intrinsic-size: 80vw auto; + contain-intrinsic-size: 80vw auto none; } ``` diff --git a/files/en-us/web/css/css_counter_styles/using_css_counters/index.md b/files/en-us/web/css/css_counter_styles/using_css_counters/index.md index 958b102b118c1a7..5641d3732069d9d 100644 --- a/files/en-us/web/css/css_counter_styles/using_css_counters/index.md +++ b/files/en-us/web/css/css_counter_styles/using_css_counters/index.md @@ -76,6 +76,10 @@ The value of a counter can be displayed using either the {{cssxref("counter", "c For example, the following declaration uses `counter()` to prefix each `h3` heading with the text `Section <number>:`, where `<number>` is the value of the count in decimal (the default display style): ```css +body { + counter-reset: section; /* Set a counter named 'section', and its initial value is 0. */ +} + h3::before { counter-increment: section; /* Increment the value of section counter by 1 */ content: "Section " counter(section) ": "; /* Display counter value in default style (decimal) */ @@ -145,7 +149,7 @@ The counter value is decreased by specifying a negative value for {{cssxref("cou ### Counter inheritance and propagation -Each element or pseudo-element has a set of counters in the scope of that element. Initial counters in the set are received from the element's parent and the preceding sibling. The counter values are received from the last descendent of the previous sibling, the last sibling, or the parent. +Each element or pseudo-element has a set of counters in the scope of that element. Initial counters in the set are received from the element's parent and the preceding sibling. The counter values are received from the last descendant of the previous sibling, the last sibling, or the parent. When an element declares a counter, the counter is nested inside the counter with the same name received from the parent. If the parent doesn't have a counter with the same name then the counter is added to the element's counters set as it is. A counter with the same name received from the previous sibling is removed from the counters set. diff --git a/files/en-us/web/css/css_display/block_and_inline_layout_in_normal_flow/index.md b/files/en-us/web/css/css_display/block_and_inline_layout_in_normal_flow/index.md index 9e66d4aa12237e2..b0ff82ae650e48b 100644 --- a/files/en-us/web/css/css_display/block_and_inline_layout_in_normal_flow/index.md +++ b/files/en-us/web/css/css_display/block_and_inline_layout_in_normal_flow/index.md @@ -33,7 +33,7 @@ In a vertical writing mode then would lay out horizontally. In this guide, we will be working in English and therefore a horizontal writing mode. However, everything described should work in the same way if your document is in a vertical writing mode. -As defined in the specification, the margins between two block boxes are what creates separation between the elements. We see this with a very simple layout of two paragraphs, to which I have added a border. The default browser stylesheet adds spacing between the paragraphs by way of adding a margin to the top and bottom. +As defined in the specification, the margins between two block boxes are what creates separation between the elements. We can see this with the layout of two paragraphs, to which I have added a border. The default browser stylesheet adds spacing between the paragraphs by way of adding a margin to the top and bottom. ```html live-sample___normal-flow <div class="box"> @@ -195,7 +195,7 @@ strong { {{EmbedLiveSample("line-box")}} -Find out more about how block and inline boxes behave in our guide to the [visual formatting model](/en-US/docs/Web/CSS/Visual_formatting_model). +Find out more about how block and inline boxes behave in our guide to the [visual formatting model](/en-US/docs/Web/CSS/CSS_display/Visual_formatting_model). ## The display property and flow layout diff --git a/files/en-us/web/css/css_display/block_formatting_context/index.md b/files/en-us/web/css/css_display/block_formatting_context/index.md index 7ae6eca73772d73..56f11ca33a82801 100644 --- a/files/en-us/web/css/css_display/block_formatting_context/index.md +++ b/files/en-us/web/css/css_display/block_formatting_context/index.md @@ -231,9 +231,9 @@ In this example, we wrap the second `<div>` in an outer `<div>`, and create a ne - [Specificity](/en-US/docs/Web/CSS/CSS_cascade/Specificity) - [Inheritance](/en-US/docs/Web/CSS/CSS_cascade/Inheritance) - [Box model](/en-US/docs/Web/CSS/CSS_box_model/Introduction_to_the_CSS_box_model) -- [Layout modes](/en-US/docs/Web/CSS/Layout_mode) -- [Visual formatting models](/en-US/docs/Web/CSS/Visual_formatting_model) +- [Layout modes](/en-US/docs/Glossary/Layout_mode) +- [Visual formatting models](/en-US/docs/Web/CSS/CSS_display/Visual_formatting_model) - [Margin collapsing](/en-US/docs/Web/CSS/CSS_box_model/Mastering_margin_collapsing) -- [Initial](/en-US/docs/Web/CSS/CSS_cascade/initial_value), [computed](/en-US/docs/Web/CSS/CSS_cascade/computed_value), [used values](/en-US/docs/Web/CSS/CSS_cascade/used_value), and [actual](/en-US/docs/Web/CSS/CSS_cascade/actual_value) values +- [Initial](/en-US/docs/Web/CSS/CSS_cascade/Value_processing#initial_value), [computed](/en-US/docs/Web/CSS/CSS_cascade/Value_processing#computed_value), [used values](/en-US/docs/Web/CSS/CSS_cascade/Value_processing#used_value), and [actual](/en-US/docs/Web/CSS/CSS_cascade/Value_processing#actual_value) values - [Value definition syntax](/en-US/docs/Web/CSS/CSS_Values_and_Units/Value_definition_syntax) -- [Replaced elements](/en-US/docs/Web/CSS/Replaced_element) +- {{glossary("Replaced elements")}} diff --git a/files/en-us/web/css/css_display/containing_block/index.md b/files/en-us/web/css/css_display/containing_block/index.md index 5ac3346007e3a90..dbc837494c39c99 100644 --- a/files/en-us/web/css/css_display/containing_block/index.md +++ b/files/en-us/web/css/css_display/containing_block/index.md @@ -35,9 +35,9 @@ The process for identifying the containing block depends entirely on the value o 4. If the `position` property is **`absolute`** or **`fixed`**, the containing block may also be formed by the edge of the _padding box_ of the nearest ancestor element that has any of the following: - A {{cssxref("filter")}}, {{cssxref("backdrop-filter")}}, {{cssxref("transform")}}, or {{cssxref("perspective")}} value other than `none`. - - A {{cssxref("contain")}} value of `layout`, `paint`, `strict` or `content` (e.g. `contain: paint;`). + - A {{cssxref("contain")}} value of `layout`, `paint`, `strict` or `content` (e.g., `contain: paint;`). - A {{cssxref("container-type")}} value other than `normal`. - - A {{cssxref("will-change")}} value containing a property for which a non-initial value would form a containing block (e.g. `filter` or `transform`). + - A {{cssxref("will-change")}} value containing a property for which a non-initial value would form a containing block (e.g., `filter` or `transform`). - A {{cssxref("content-visibility")}} value of `auto`. > [!NOTE] @@ -260,11 +260,11 @@ p { - [Learn: sizing items in CSS](/en-US/docs/Learn_web_development/Core/Styling_basics/Sizing) - [Box model](/en-US/docs/Web/CSS/CSS_box_model/Introduction_to_the_CSS_box_model) - [CSS box model](/en-US/docs/Web/CSS/CSS_box_model) module -- [Layout modes](/en-US/docs/Web/CSS/Layout_mode) -- [Visual formatting models](/en-US/docs/Web/CSS/Visual_formatting_model) +- [Layout modes](/en-US/docs/Glossary/Layout_mode) +- [Visual formatting models](/en-US/docs/Web/CSS/CSS_display/Visual_formatting_model) - [Block formatting context](/en-US/docs/Web/CSS/CSS_display/Block_formatting_context) -- [Stacking context](/en-US/docs/Web/CSS/CSS_positioned_layout/Understanding_z-index/Stacking_context) +- [Stacking context](/en-US/docs/Web/CSS/CSS_positioned_layout/Stacking_context) - [Margin collapsing](/en-US/docs/Web/CSS/CSS_box_model/Mastering_margin_collapsing) -- [Initial](/en-US/docs/Web/CSS/CSS_cascade/initial_value), [computed](/en-US/docs/Web/CSS/CSS_cascade/computed_value), [used](/en-US/docs/Web/CSS/CSS_cascade/used_value), and [actual](/en-US/docs/Web/CSS/CSS_cascade/actual_value) values -- [Replaced elements](/en-US/docs/Web/CSS/Replaced_element) +- [Initial](/en-US/docs/Web/CSS/CSS_cascade/Value_processing#initial_value), [computed](/en-US/docs/Web/CSS/CSS_cascade/Value_processing#computed_value), [used](/en-US/docs/Web/CSS/CSS_cascade/Value_processing#used_value), and [actual](/en-US/docs/Web/CSS/CSS_cascade/Value_processing#actual_value) values +- {{glossary("Replaced elements")}} - {{glossary("Intrinsic size")}} diff --git a/files/en-us/web/css/css_display/flow_layout_and_writing_modes/index.md b/files/en-us/web/css/css_display/flow_layout_and_writing_modes/index.md index eafacffd0e88498..c788e8483e0a826 100644 --- a/files/en-us/web/css/css_display/flow_layout_and_writing_modes/index.md +++ b/files/en-us/web/css/css_display/flow_layout_and_writing_modes/index.md @@ -50,7 +50,7 @@ h1 { ## Block flow direction -The {{cssxref("writing-mode")}} property accepts the values `horizontal-tb`, `vertical-rl` and `vertical-lr`. These values control the direction that blocks flow on the page. The initial value is `horizontal-tb,` which is a top to bottom block flow direction with a horizontal inline direction. Left to right languages, such as English, and Right to left languages, such as Arabic, are all `horizontal-tb`. +The {{cssxref("writing-mode")}} property accepts the values `horizontal-tb`, `vertical-rl` and `vertical-lr`. These values control the direction that blocks flow on the page. The initial value is `horizontal-tb`, which is a top to bottom block flow direction with a horizontal inline direction. Left to right languages, such as English, and Right to left languages, such as Arabic, are all `horizontal-tb`. The following example shows blocks using the initial `horizontal-tb` value explicitly: diff --git a/files/en-us/web/css/css_display/index.md b/files/en-us/web/css/css_display/index.md index 4f9183d9158f9b6..e14fd781b93761b 100644 --- a/files/en-us/web/css/css_display/index.md +++ b/files/en-us/web/css/css_display/index.md @@ -2,7 +2,9 @@ title: CSS display slug: Web/CSS/CSS_display page-type: css-module -spec-urls: https://drafts.csswg.org/css-display/ +spec-urls: + - https://drafts.csswg.org/css-display/ + - https://drafts.csswg.org/css-display-4/ --- {{CSSRef}} @@ -16,6 +18,8 @@ The **CSS display** module defines how the CSS formatting box tree is generated - {{CSSxRef("display")}} - {{CSSxRef("order")}} - {{CSSxRef("visibility")}} +- {{cssxref("reading-flow")}} +- {{cssxref("reading-order")}} ### Data types @@ -32,12 +36,9 @@ The **CSS display** module defines how the CSS formatting box tree is generated - [Block formatting context (BFC)](/en-US/docs/Web/CSS/CSS_display/Block_formatting_context) - {{glossary("Block-level content")}} - [Containing block](/en-US/docs/Web/CSS/CSS_display/Containing_block) -- {{glossary("Flex")}} - [Flow layout](/en-US/docs/Web/CSS/CSS_display/Flow_layout) -- {{glossary("Grid")}} -- [Inline formatting context](/en-US/docs/Web/CSS/Inline_formatting_context) -- {{glossary("Inline-level content")}} -- [Replaced element](/en-US/docs/Web/CSS/Replaced_element) +- {{glossary("Reading order")}} +- {{glossary("Replaced elements")}} - {{glossary("Ruby")}} ## Guides @@ -59,8 +60,15 @@ The **CSS display** module defines how the CSS formatting box tree is generated ### Properties -- {{cssxref("transition-behavior")}} - {{cssxref("overflow")}} +- {{cssxref("transition-behavior")}} + +### Glossary and terms + +- {{glossary("Flex")}} +- {{glossary("Grid")}} +- [Inline formatting context](/en-US/docs/Web/CSS/CSS_inline_layout/Inline_formatting_context) +- {{glossary("Inline-level content")}} ### Guides @@ -95,4 +103,4 @@ The **CSS display** module defines how the CSS formatting box tree is generated - [CSS lists and counters](/en-US/docs/Web/CSS/CSS_lists) module - [CSS ruby layout](/en-US/docs/Web/CSS/CSS_ruby_layout) module - [CSS table](/en-US/docs/Web/CSS/CSS_table) module -- [Visual formatting model](/en-US/docs/Web/CSS/Visual_formatting_model) +- [Visual formatting model](/en-US/docs/Web/CSS/CSS_display/Visual_formatting_model) diff --git a/files/en-us/web/css/css_display/introduction_to_formatting_contexts/index.md b/files/en-us/web/css/css_display/introduction_to_formatting_contexts/index.md index 51e67bfd1844cb3..c58ef81ce4bd778 100644 --- a/files/en-us/web/css/css_display/introduction_to_formatting_contexts/index.md +++ b/files/en-us/web/css/css_display/introduction_to_formatting_contexts/index.md @@ -185,5 +185,5 @@ In this guide, we have looked in more detail at the block and Inline formatting ## See also - [Block formatting context](/en-US/docs/Web/CSS/CSS_display/Block_formatting_context) -- [Visual formatting model](/en-US/docs/Web/CSS/Visual_formatting_model) +- [Visual formatting model](/en-US/docs/Web/CSS/CSS_display/Visual_formatting_model) - [CSS Box Model](/en-US/docs/Web/CSS/CSS_box_model) diff --git a/files/en-us/web/css/css_display/multi-keyword_syntax_of_display/index.md b/files/en-us/web/css/css_display/multi-keyword_syntax_of_display/index.md index dfba0e22f2871d1..a7aa23c9796a371 100644 --- a/files/en-us/web/css/css_display/multi-keyword_syntax_of_display/index.md +++ b/files/en-us/web/css/css_display/multi-keyword_syntax_of_display/index.md @@ -159,9 +159,9 @@ Changing between `display: flow-root` and `display: block flow-root` will achiev ```js hidden function changeDisplayType() { - var parentDiv = document.getElementById("parent"); - var siblingDiv = document.getElementById("sibling"); - var displayType = document.getElementById("displayType").value; + const parentDiv = document.getElementById("parent"); + const siblingDiv = document.getElementById("sibling"); + const displayType = document.getElementById("displayType").value; parentDiv.style.display = displayType; siblingDiv.style.display = displayType; diff --git a/files/en-us/web/css/css_display/visual_formatting_model/index.md b/files/en-us/web/css/css_display/visual_formatting_model/index.md new file mode 100644 index 000000000000000..3400fb96eecdf9a --- /dev/null +++ b/files/en-us/web/css/css_display/visual_formatting_model/index.md @@ -0,0 +1,263 @@ +--- +title: Visual formatting model +slug: Web/CSS/CSS_display/Visual_formatting_model +page-type: guide +--- + +{{CSSRef}} + +In CSS, the **visual formatting model** describes how user agents take the document tree, and process and display it for visual media. This includes {{glossary("continuous media")}} such as a computer screen and [paged media](/en-US/docs/Web/CSS/CSS_paged_media) such as a book or document printed by browser print functions. Most of the information applies equally to continuous and paged media. + +In the visual formatting model, each element in the document tree generates zero or more boxes according to the box model. The layout of these boxes is governed by: + +- Box dimensions and type. +- Positioning scheme (normal flow, float, and absolute positioning). +- Relationships between elements in the document tree. +- External information (e.g., viewport size, intrinsic dimensions of images, etc.). + +Much of the information about the visual formatting model is defined in CSS2, however, various CSS layout modules have expanded upon this information. When reading specifications you will often find references to the model as defined in CSS2, so an understanding of the model and the terms used to describe it in CSS2 is valuable when reading other layout specifications. + +In this document we define the model and introduce some of the related terms and concepts, linking to more specific pages for further details. + +## The role of the viewport + +In continuous media, the {{glossary("viewport")}} is the viewing area of the browser window. User agents can change the layout of the page when the viewport size changes — for example, if you resize your window, or change the orientation of a mobile device. + +If the viewport is smaller than the size of the document then the user agent needs to offer a way to scroll to the parts of the document that are not displayed. We most often see this as scrolling in the **block dimension** — vertically in a horizontal, top-to-bottom language. However, you might design something that requires scrolling in the **inline dimension** too. + +## Box generation + +**Box generation** is the part of the CSS visual formatting model that creates boxes from the document's elements. Generated boxes are of different types, which affect their visual formatting. The type of the box generated depends on the value of the CSS {{cssxref("display")}} property. + +Initially defined in CSS2, the `display` property was extended in the [CSS display](/en-US/docs/Web/CSS/CSS_display), [CSS flexible box layout](/en-US/docs/Web/CSS/CSS_flexible_box_layout), [CSS grid layout](/en-US/docs/Web/CSS/CSS_grid_layout), and [CSS ruby layout](/en-US/docs/Web/CSS/CSS_ruby_layout) modules. In addition, some of the terminologies around the display have been updated and clarified in the years since CSS2. + +CSS takes your source document and renders it onto a canvas. To do this, it generates an intermediary structure, the **box tree**, which represents the formatting structure of the rendered document. Each box in the box tree represents its corresponding element (or pseudo-element) in space and/or time on the canvas, while each text run in the box tree likewise represents the contents of its corresponding text nodes. + +Then, for each element, CSS generates zero or more boxes as specified by that element's `display` property value. + +> [!NOTE] +> Boxes are often referred to by their display type — e.g., a box generated by an element with `display: block` is called a "block box" or just a "block". Note however that block boxes, block-level boxes, and block containers are all subtly different; see the [block boxes](#block_boxes) section below for more details. + +### The principal box + +When an element generates one or more boxes, one of them is the **principal box**, which contains its descendant boxes and generated content in the box tree, and is also the box involved in any positioning scheme. + +Some elements may generate additional boxes in addition to the principal box, for example `display: list-item` generates more than one box (e.g., a **principal block box** and a **child marker box**). And some values (such as `none` or `contents`) cause the element and/or its descendants to not generate any boxes at all. + +### Anonymous boxes + +An **anonymous box** is created when there is not an HTML element to use for the box. This situation happens when, for example, you declare `display: flex` on a parent element, and directly inside there is a run of text not contained in another element. In order to fix the box tree, an anonymous box is created around that run of text. It will then behave as a flex item, however, it cannot be targeted and styled like a regular box because there is no element to target. + +```html live-sample___anonymous-flex +<div class="flex"> + I am wrapped in an anonymous box + <p>I am in the paragraph</p> + I am wrapped in an anonymous box. +</div> +``` + +```css live-sample___anonymous-flex +body { + font: 1.2em sans-serif; + margin: 20px; +} + +.flex { + display: flex; +} + +.flex > * { + background-color: rebeccapurple; + color: white; +} +``` + +{{EmbedLiveSample("anonymous-flex")}} + +The same thing happens when you have text runs interspersed with block elements. In the next example I have a string inside a `<div>`; in the middle of my string is a `<p>` element containing part of the text. + +```html live-sample___anonymous-block +<div class="example"> + I am wrapped in an anonymous box + <p>I am in the paragraph</p> + I am wrapped in an anonymous box. +</div> +``` + +```css live-sample___anonymous-block +body { + font: 1.2em sans-serif; + margin: 20px; +} + +.example > * { + background-color: rebeccapurple; + color: white; +} +``` + +{{EmbedLiveSample("anonymous-block")}} + +The string is split into three boxes in the box tree. The part of the string before the paragraph element is wrapped in an anonymous box, then we have the `<p>`, which generates a box, and then another anonymous box. + +Something to consider about these anonymous boxes is that they inherit styles from their direct parent, but you cannot change how they look by targeting the anonymous box. In my examples, I am using a direct child selector to target the children of the container. This does not change the anonymous boxes, as they are not "elements" as such. + +**Inline anonymous boxes** are created when a string is split by an inline element, for example, a sentence that includes a section wrapped with `<em></em>`. This splits the sentence into three inline boxes — an anonymous inline box before the emphasized section, the section wrapped in the `<em>` element, then a final anonymous inline box. As with the anonymous block boxes, these anonymous inline boxes cannot be styled independently in the way the `<em>` can; they just inherit the styles of their container. + +Other formatting contexts also create anonymous boxes. [Grid layout](/en-US/docs/Web/CSS/CSS_grid_layout) behaves in the same way as the [flexbox](/en-US/docs/Web/CSS/CSS_flexible_box_layout) example above, turning strings of text into a grid item with an anonymous box. [Multiple-column](/en-US/docs/Web/CSS/CSS_multicol_layout) layout creates anonymous column boxes around the columns; these also cannot be styled or otherwise targeted. [Table layout](/en-US/docs/Web/CSS/CSS_table) will add anonymous boxes to create a proper table structure — for example adding an anonymous table row — if there was no box with `display: table-row`. + +### Line boxes + +**Line boxes** are the boxes that wrap each line of text. You can see the difference between line boxes and their containing block if you float an item and then follow it by a block that has a background color. + +In the following example, the line boxes following the floated `<div>` are shortened to wrap around the float. The background of the box runs behind the float, as the floated item has been taken out of flow. + +```html live-sample___line-boxes +<div class="float"></div> +<p class="following"> + This text is following the float, the line boxes are shortened to make room + for the float but the box of the element still takes position in normal flow. +</p> +``` + +```css live-sample___line-boxes +body { + font: 1.2em sans-serif; + margin: 20px; +} + +.float { + float: left; + width: 150px; + height: 150px; + background-color: rebeccapurple; + margin: 20px; +} + +.following { + background-color: #ccc; +} +``` + +{{EmbedLiveSample("line-boxes", "", "250px")}} + +## Positioning schemes and in-flow and out-of-flow elements + +In CSS, a box may be laid out according to three positioning schemes — **normal flow**, **floats**, or **absolute positioning**. + +### Normal flow + +In CSS, the normal flow includes block-level formatting of block boxes, inline-level formatting of inline boxes, and also includes relative and sticky positioning of block-level and inline-level boxes. + +Read more about [flow layout](/en-US/docs/Web/CSS/CSS_display/Flow_layout) in CSS. + +### Floats + +In the float model, a box is first laid out according to the normal flow, then taken out of the flow and positioned, typically to the left or right. Content may flow along the side of a float. + +Find out more about [floats](/en-US/docs/Learn_web_development/Core/CSS_layout/Floats). + +### Absolute positioning + +In the absolute positioning model (which also includes `fixed` positioning), a box is removed from the normal flow entirely and assigned a position relative to a containing block (which is the viewport in the case of fixed positioning) or to one or more anchor elements in [CSS anchor positioning](/en-US/docs/Web/CSS/CSS_anchor_positioning). + +An element is called **out of flow** if it is floated, absolutely positioned, or is the root element. An element is called **in-flow** if it is not out of the flow. + +Read about [CSS positioned layout](/en-US/docs/Web/CSS/CSS_positioned_layout). + +## Formatting contexts and the display property + +Boxes can be described as having an **outer display type**, which is `block` or `inline`. This outer display type refers to how the box behaves alongside other elements on the page. + +Boxes also have an inner display type, dictating how their children behave. For normal block and inline layout, or normal flow, this display type is `flow`. This means that the child elements will also be either `block` or `inline`. + +However, the inner display type might be something like `grid` or `flex`, in which case the direct children will display as a grid, or flex items. In such a case the element is described as creating a grid or flex [formatting context](/en-US/docs/Web/CSS/CSS_display/Introduction_to_formatting_contexts). In many ways, this is similar to a block formatting context, however, the children behave as flex or grid items rather than items in normal flow. + +The interactions between block-level and inline-level boxes are described in the {{cssxref("display")}} property reference. + +In addition, the references for specific values of display explain how these formatting contexts work in terms of box layout. + +- [CSS grid layout](/en-US/docs/Web/CSS/CSS_grid_layout) module +- [CSS flexible box layout](/en-US/docs/Web/CSS/CSS_flexible_box_layout) module +- [CSS multi-column layout](/en-US/docs/Web/CSS/CSS_multicol_layout) module +- [CSS table](/en-US/docs/Web/CSS/CSS_table) module +- [CSS lists and counters](/en-US/docs/Web/CSS/CSS_lists) module + +### Independent formatting contexts + +Elements either participate in the formatting context of their containing block or establish an independent formatting context. A grid container, for example, establishes a new **grid formatting context** for its children. + +**Independent formatting contexts** contain floats, and margins do not collapse across formatting context boundaries. Therefore, creating a new block formatting context can ensure that floats and margins remain inside a box. To do this, add `display: flow-root` to the box on which you wish to create a new [block formatting context](/en-US/docs/Web/CSS/CSS_display/Block_formatting_context). + +The following example shows the effect of `display: flow-root`. The box with the black background appears to wrap around the floated item and text. If you remove `display: flow-root`, the floated item will poke out of the bottom of the box as it is no longer contained. + +```html live-sample___block-flow-root +<div class="container"> + <div class="item">Floated</div> + <p>Text following the float.</p> +</div> +``` + +```css hidden live-sample___block-flow-root +body { + font: 1.2em sans-serif; + margin: 20px; +} +.container { + background-color: #333; + color: #fff; +} + +.item { + background-color: #fff; + border: 1px solid #999; + color: #333; + width: 100px; + height: 100px; + padding: 10px; +} +``` + +```css live-sample___block-flow-root +.container { + display: flow-root; +} + +.item { + margin: 10px; + float: left; +} +``` + +{{EmbedLiveSample("block-flow-root", "", "250px")}} + +### Block boxes + +In specifications, block boxes, block-level boxes, and block containers are all referred to as **block boxes** in certain places. These things are somewhat different and the term block box should only be used if there is no ambiguity. + +#### Block containers + +A **block container** either contains only inline-level boxes participating in an inline formatting context, or only block-level boxes participating in a block formatting context. For this reason, we see the behavior explained above, where anonymous boxes are introduced to ensure all of the items can participate in a block or inline formatting context. An element is a block container only if it contains block-level or inline-level boxes. + +#### Inline-level and block-level boxes + +These are the boxes contained inside the block container that are participating in inline or block layout, respectively. + +#### Block boxes + +A block box is a block-level box that is also a block container. As described in CSS `display`, a box can be a block-level box, but not also a block container (it might be a flex or grid container for example). + +## See also + +- [CSS syntax](/en-US/docs/Web/CSS/CSS_syntax/Syntax) guide +- [Comments](/en-US/docs/Web/CSS/CSS_syntax/Comments) +- [Specificity](/en-US/docs/Web/CSS/CSS_cascade/Specificity) +- [Inheritance](/en-US/docs/Web/CSS/CSS_cascade/Inheritance) +- [Stacking context](/en-US/docs/Web/CSS/CSS_positioned_layout/Stacking_context) +- [Block formatting context](/en-US/docs/Web/CSS/CSS_display/Block_formatting_context) +- [Box model](/en-US/docs/Web/CSS/CSS_box_model/Introduction_to_the_CSS_box_model) +- [Layout modes](/en-US/docs/Glossary/Layout_mode) +- [Margin collapsing](/en-US/docs/Web/CSS/CSS_box_model/Mastering_margin_collapsing) +- {{glossary("Replaced elements")}} +- {{DOMxRef("VisualViewport")}} interface +- {{glossary("Scroll container")}} diff --git a/files/en-us/web/css/css_filter_effects/index.md b/files/en-us/web/css/css_filter_effects/index.md index 26a1e77f6a50ef2..85f72c202259f90 100644 --- a/files/en-us/web/css/css_filter_effects/index.md +++ b/files/en-us/web/css/css_filter_effects/index.md @@ -172,7 +172,7 @@ for (control of controls) { document.querySelector("button").addEventListener( "click", () => { - setTimeout(function () { + setTimeout(() => { changeCSS(); }, 50); }, @@ -180,25 +180,28 @@ document.querySelector("button").addEventListener( ); function changeCSS() { - let currentFilter = - "filter: " + - blur() + - brightness() + - contrast() + - dropShadow() + - grayscale() + - hueRotate() + - invert() + - opacity() + - saturate() + - sepia() + - ";"; + let currentFilter = "filter: "; + for (const filter of [ + blur(), + brightness(), + contrast(), + dropShadow(), + grayscale(), + hueRotate(), + invert(), + opacity(), + saturate(), + sepia(), + ]) { + currentFilter += filter; + } + currentFilter += ";"; image.setAttribute("style", currentFilter); output.innerText = currentFilter; } function blur() { let blurValue = document.getElementsByName("blur")[0].value; - return blurValue == "0" ? "" : `blur(${blurValue}rem) `; + return blurValue === "0" ? "" : `blur(${blurValue}rem) `; } function brightness() { let brightnessValue = document.getElementsByName("brightness")[0].value; @@ -208,37 +211,37 @@ function brightness() { } function contrast() { let contrastValue = document.getElementsByName("contrast")[0].value; - return contrastValue == 1 ? "" : `contrast(${contrastValue}) `; + return contrastValue === 1 ? "" : `contrast(${contrastValue}) `; } function dropShadow() { let dropShadowValue = document.getElementsByName("dropShadow")[0].value; - return dropShadowValue == 0 + return dropShadowValue === 0 ? "" : `drop-shadow(${dropShadowValue}rem ${dropShadowValue}rem 0rem orange) `; } function grayscale() { let grayscaleValue = document.getElementsByName("grayscale")[0].value; - return grayscaleValue == 0 ? "" : `grayscale(${grayscaleValue}) `; + return grayscaleValue === 0 ? "" : `grayscale(${grayscaleValue}) `; } function hueRotate() { let hueRotateValue = document.getElementsByName("hueRotate")[0].value; - return hueRotateValue == 0 ? "" : `hue-rotate(${hueRotateValue}turn) `; + return hueRotateValue === 0 ? "" : `hue-rotate(${hueRotateValue}turn) `; } function invert() { let invertValue = document.getElementsByName("invert")[0].value; - return invertValue == 0 ? "" : `invert(${invertValue}) `; + return invertValue === 0 ? "" : `invert(${invertValue}) `; } function opacity() { let opacityValue = document.getElementsByName("opacity")[0].value; - return opacityValue == 1 ? "" : `opacity(${opacityValue}) `; + return opacityValue === 1 ? "" : `opacity(${opacityValue}) `; } function saturate() { let saturateValue = document.getElementsByName("saturate")[0].value; - return saturateValue == 1 ? "" : `saturate(${saturateValue}) `; + return saturateValue === 1 ? "" : `saturate(${saturateValue}) `; } function sepia() { let sepiaValue = document.getElementsByName("sepia")[0].value; - return sepiaValue == 0 ? "" : `sepia(${sepiaValue})`; + return sepiaValue === 0 ? "" : `sepia(${sepiaValue})`; } ``` @@ -278,7 +281,7 @@ function sepia() { - {{glossary("interpolation")}} glossary term -- [`color-interpolation-filters`](/en-US/docs/Web/SVG/Attribute/color-interpolation-filters) SVG property +- [`color-interpolation-filters`](/en-US/docs/Web/SVG/Reference/Attribute/color-interpolation-filters) SVG property ## Specifications diff --git a/files/en-us/web/css/css_filter_effects/using_filter_effects/index.md b/files/en-us/web/css/css_filter_effects/using_filter_effects/index.md index 37ab2ebd7837c72..7d2c77244116947 100644 --- a/files/en-us/web/css/css_filter_effects/using_filter_effects/index.md +++ b/files/en-us/web/css/css_filter_effects/using_filter_effects/index.md @@ -73,7 +73,7 @@ img:focus { } ``` -In the {{HTMLElement("img")}} element, [`tabindex`](/en-US/docs/Web/HTML/Global_attributes/tabindex) is set to `0` to enable focus without altering the tabbing order for keyboard users because `<img>` is not an interactive element. +In the {{HTMLElement("img")}} element, [`tabindex`](/en-US/docs/Web/HTML/Reference/Global_attributes/tabindex) is set to `0` to enable focus without altering the tabbing order for keyboard users because `<img>` is not an interactive element. ```css hidden img { @@ -118,7 +118,8 @@ This example applies two filters — [`hue-rotate()`](/en-US/docs/Web/CSS/filter ```css .container { - background: url(image.jpg) no-repeat left / contain goldenrod; + background: url("/shared-assets/images/examples/listen_to_black_women.jpg") + no-repeat left / contain goldenrod; } p { backdrop-filter: hue-rotate(240deg) blur(5px); @@ -141,9 +142,7 @@ p { ``` ```html hidden -<div - class="container" - style="background-image: url('https://mdn.github.io/shared-assets/images/examples/listen_to_black_women.jpg');"> +<div class="container"> <p> Text on images can be illegible and inaccessible even with a drop shadow. </p> @@ -225,7 +224,7 @@ No filter effect is applied to the third line to show the original effect as a c ## Using SVG filters -In addition to the 10 defined {{cssxref("filter-function")}}s, the CSS filter effects support `url()`, with the parameter being an [SVG filter](/en-US/docs/Web/SVG/Element/filter), which may be embedded in an internal or external SVG file. +In addition to the 10 defined {{cssxref("filter-function")}}s, the CSS filter effects support `url()`, with the parameter being an [SVG filter](/en-US/docs/Web/SVG/Reference/Element/filter), which may be embedded in an internal or external SVG file. A single SVG can be used to define several filters, each with an `id`: @@ -258,7 +257,7 @@ Just like the {{cssxref("filter-function/blur", "blur()")}} filter function appl In both the cases, the blur radius value, specified as a {{cssxref("&lt;length&gt;")}} in CSS and as a pixel equivalent {{cssxref("&lt;number&gt;")}} in SVG, defines the value of the standard deviation to the Gaussian function. In other words, it defines the number of pixels on the screen that blend into each other; a larger value creates more blur. -The [`<filter>`](/en-US/docs/Web/SVG/Element/filter)'s {{SVGAttr("stdDeviation")}} attribute accepts up to two values enabling creating more complex blur values. To create an equivalent blur, we include one value for `stdDeviation`: +The [`<filter>`](/en-US/docs/Web/SVG/Reference/Element/filter)'s {{SVGAttr("stdDeviation")}} attribute accepts up to two values enabling creating more complex blur values. To create an equivalent blur, we include one value for `stdDeviation`: ```html hidden <table cellpadding="5"> @@ -304,7 +303,7 @@ The [`<filter>`](/en-US/docs/Web/SVG/Element/filter)'s {{SVGAttr("stdDeviation") </svg> ``` -The SVG `url()` filter value can be included as the value of the SVG [`<image>`](/en-US/docs/Web/SVG/Element/image) element's [`filter`](/en-US/docs/Web/SVG/Attribute/filter) attribute or as part of the value of the CSS `filter` and `backdrop-filter` properties. +The SVG `url()` filter value can be included as the value of the SVG [`<image>`](/en-US/docs/Web/SVG/Reference/Element/image) element's [`filter`](/en-US/docs/Web/SVG/Reference/Attribute/filter) attribute or as part of the value of the CSS `filter` and `backdrop-filter` properties. ```css .filter { @@ -323,4 +322,4 @@ The SVG `url()` filter value can be included as the value of the SVG [`<image>`] - {{cssxref("background-blend-mode")}}, {{cssxref("mix-blend-mode")}} - [CSS filter effects](/en-US/docs/Web/CSS/CSS_filter_effects) - SVG {{SVGElement("filter")}} element, SVG {{SVGAttr("filter")}} attribute in [SVG](/en-US/docs/Web/SVG) -- [Applying SVG effects to HTML content](/en-US/docs/Web/SVG/Applying_SVG_effects_to_HTML_content) +- [Applying SVG effects to HTML content](/en-US/docs/Web/SVG/Guides/Applying_SVG_effects_to_HTML_content) diff --git a/files/en-us/web/css/css_flexible_box_layout/aligning_items_in_a_flex_container/index.md b/files/en-us/web/css/css_flexible_box_layout/aligning_items_in_a_flex_container/index.md index 83687c0cdee7a4f..17b10034a34737f 100644 --- a/files/en-us/web/css/css_flexible_box_layout/aligning_items_in_a_flex_container/index.md +++ b/files/en-us/web/css/css_flexible_box_layout/aligning_items_in_a_flex_container/index.md @@ -96,7 +96,6 @@ In the example below, the value of `align-items` is `stretch`. Try the other val .box div { width: 100px; - height: 100px; background-color: rgb(96 139 168 / 0.2); border: 2px solid rgb(96 139 168); border-radius: 5px; diff --git a/files/en-us/web/css/css_flexible_box_layout/basic_concepts_of_flexbox/index.md b/files/en-us/web/css/css_flexible_box_layout/basic_concepts_of_flexbox/index.md index a32e909e3ff48b1..43b868da7b50ba7 100644 --- a/files/en-us/web/css/css_flexible_box_layout/basic_concepts_of_flexbox/index.md +++ b/files/en-us/web/css/css_flexible_box_layout/basic_concepts_of_flexbox/index.md @@ -286,7 +286,7 @@ There are also some predefined shorthand values which cover most of the use case - `flex: none` - `flex: <positive-number>` -The `initial` value is a [CSS-wide value](/en-US/docs/Web/CSS/CSS_Values_and_Units/CSS_data_types#css-wide_values) that represents the initial value for a property. Setting `flex: initial` resets the item to the [initial values](#initial_values) of the three longhand properties, which is the same as `flex: 0 1 auto`. The initial value of `flex-grow` is `0`, so items will not grow larger than their `flex-basis` size. The initial value of `flex-shrink` is `1`, so items can shrink if they need to rather than overflowing. The initial value of `flex-basis` is `auto`. Items will either use any size set on the item in the main dimension, or they will get their size from the content size. +The `initial` value is a [CSS-wide keyword](/en-US/docs/Web/CSS/CSS_Values_and_Units/CSS_data_types#css-wide_keywords) that represents the initial value for a property. Setting `flex: initial` resets the item to the [initial values](#initial_values) of the three longhand properties, which is the same as `flex: 0 1 auto`. The initial value of `flex-grow` is `0`, so items will not grow larger than their `flex-basis` size. The initial value of `flex-shrink` is `1`, so items can shrink if they need to rather than overflowing. The initial value of `flex-basis` is `auto`. Items will either use any size set on the item in the main dimension, or they will get their size from the content size. Using `flex: auto` is the same as using `flex: 1 1 auto`; this is similar to `flex: initial`, except that the items can grow and fill the container as well as shrink if needed. diff --git a/files/en-us/web/css/css_flexible_box_layout/mastering_wrapping_of_flex_items/index.md b/files/en-us/web/css/css_flexible_box_layout/mastering_wrapping_of_flex_items/index.md index cb0c146f889be07..1f24bc08a25480f 100644 --- a/files/en-us/web/css/css_flexible_box_layout/mastering_wrapping_of_flex_items/index.md +++ b/files/en-us/web/css/css_flexible_box_layout/mastering_wrapping_of_flex_items/index.md @@ -309,7 +309,7 @@ p:has(:checked) + div .collapse { The above was a single-line, non-wrapping flex container with a set size of `600px` so whether the item is visible or collapsed, the width is the same. It is important to understand that while the container retains a strut of the collapsed item's cross-size, the main size is not preserved. Multi-line flex containers rewrap their items after removing collapsed items from rendering. The new space that a collapsed item leaves in the main direction may cause non-collapsed items to be placed in a different line than if the item were not collapsed. Because each line is laid out like an independent single-line flex container and its composition may change after collapsing, its cross-axis size may change too. -The following example shows this behavior. The third flex item is collapsed, so it occupies zero space along the main axis (the inline-size is `0`). When collapsed, its strut is on the first row after the fourth item, with the first row being tall enough to fit the three lines of text that the third item would have had. Then, if you uncollapse the item (e.g. by removing the `collapse` class), there is no longer enough horizontal space for the fifth item on the first row, and it moves to the second. This causes the second row to grow to fit the two lines of text of its new member, and the last flex item is pushed onto a new row. With a taller second line and a new third line, the flex container is much taller than it was before. +The following example shows this behavior. The third flex item is collapsed, so it occupies zero space along the main axis (the inline-size is `0`). When collapsed, its strut is on the first row after the fourth item, with the first row being tall enough to fit the three lines of text that the third item would have had. Then, if you uncollapse the item (e.g., by removing the `collapse` class), there is no longer enough horizontal space for the fifth item on the first row, and it moves to the second. This causes the second row to grow to fit the two lines of text of its new member, and the last flex item is pushed onto a new row. With a taller second line and a new third line, the flex container is much taller than it was before. > [!NOTE] > Use Firefox for the example below as other common browsers treat `collapse` as `hidden`. diff --git a/files/en-us/web/css/css_flexible_box_layout/relationship_of_flexbox_to_other_layout_methods/index.md b/files/en-us/web/css/css_flexible_box_layout/relationship_of_flexbox_to_other_layout_methods/index.md index 7fbded0d784181c..f8d7406e9d3bacc 100644 --- a/files/en-us/web/css/css_flexible_box_layout/relationship_of_flexbox_to_other_layout_methods/index.md +++ b/files/en-us/web/css/css_flexible_box_layout/relationship_of_flexbox_to_other_layout_methods/index.md @@ -57,7 +57,7 @@ The writing modes specification defines the following values of the {{cssxref("w The `sideways-rl` and `sideways-lr` have support only in Firefox currently. -Note that you would not normally use CSS and the `writing-mode` property to change an entire document to another writing mode. This would be done via HTML, by adding a [`dir`](/en-US/docs/Web/HTML/Global_attributes/dir) and [`lang`](/en-US/docs/Web/HTML/Global_attributes/lang) attribute to the {{htmlelement("html")}} element to indicate the document language and default text direction. This would mean that the document would display correctly even if CSS did not load. +Note that you would not normally use CSS and the `writing-mode` property to change an entire document to another writing mode. This would be done via HTML, by adding a [`dir`](/en-US/docs/Web/HTML/Reference/Global_attributes/dir) and [`lang`](/en-US/docs/Web/HTML/Reference/Global_attributes/lang) attribute to the {{htmlelement("html")}} element to indicate the document language and default text direction. This would mean that the document would display correctly even if CSS did not load. ## Flexbox and other layout methods diff --git a/files/en-us/web/css/css_fonts/variable_fonts_guide/index.md b/files/en-us/web/css/css_fonts/variable_fonts_guide/index.md index 1d9b6c9a7017064..04456416d58f7ab 100644 --- a/files/en-us/web/css/css_fonts/variable_fonts_guide/index.md +++ b/files/en-us/web/css/css_fonts/variable_fonts_guide/index.md @@ -9,7 +9,7 @@ page-type: guide **Variable fonts** are an evolution of the OpenType font specification that enables many different variations of a typeface to be incorporated into a single file, rather than having a separate font file for every width, weight, or style. They let you access all the variations contained in a given font file via CSS and a single {{cssxref("@font-face")}} reference. This article will give you all you need to know to get you started using variable fonts. > [!NOTE] -> To use variable fonts on your operating system, you need to make sure that it is up to date. For example, Linux OSes need the latest Linux Freetype version, and macOS prior to High Sierra (10.13) does not support variable fonts. If your operating system is not up to date, you will not be able to use variable fonts in web pages or the Firefox Developer Tools. +> To use variable fonts on your operating system, you need to make sure that it is up to date. For example, Linux OSes need the latest Linux FreeType version, and macOS prior to High Sierra (10.13) does not support variable fonts. If your operating system is not up to date, you will not be able to use variable fonts in web pages or the Firefox Developer Tools. ## Variable Fonts: what they are, and how they differ @@ -29,7 +29,7 @@ This allows for common typographic techniques such as setting different size hea #### A note about font families, weights, and variants -You might notice that we have been talking about having a specific font file for every weight and style (i.e. bold and italic and bold italic), rather than relying upon the browser to synthesize them. The reason for this is that most typefaces have very specific designs for bolder weights and italics that often include completely different characters (lower-case 'a' and 'g's are often quite different in italics, for example). To most accurately reflect the typeface design and avoid differences between browsers and how they may or may not synthesize the different styles, it's more accurate to load the specific font files where needed when using a non-variable font. +You might notice that we have been talking about having a specific font file for every weight and style (i.e., bold and italic and bold italic), rather than relying upon the browser to synthesize them. The reason for this is that most typefaces have very specific designs for bolder weights and italics that often include completely different characters (lower-case 'a' and 'g's are often quite different in italics, for example). To most accurately reflect the typeface design and avoid differences between browsers and how they may or may not synthesize the different styles, it's more accurate to load the specific font files where needed when using a non-variable font. You may also find that some variable fonts come split into two files: one for uprights and all their variations, and one containing the italic variations. This is sometimes done to reduce the overall file size in cases where the italics aren't needed or used. In all cases, it is still possible to link them with a common {{cssxref("font-family")}} name so you can call them using the same `font-family` and appropriate {{cssxref("font-style")}}. @@ -402,7 +402,7 @@ In the following live example, you can adjust the slant. ```css hidden live-sample___slant-example @font-face { font-family: "SlantFont"; - font-style: oblique -15 15; + font-style: oblique -15deg 15deg; src: url("https://mdn.github.io/shared-assets/fonts/font_with_slant_axis.woff2") format("woff2"); } @@ -701,10 +701,10 @@ In this case, the `font-style: italic` declaration indicates that this font file In this case, the `oblique 0deg 12deg` value indicates that this font file should be used when in a style rule the `font-family` property is `MyVariableFontName` and the [font-style](/en-US/docs/Web/CSS/font-style) property is oblique with an angle between zero and 12 degrees inclusive. > [!NOTE] -> Not all browsers have implemented the full syntax for font format, so test carefully. All browsers that support variable fonts will still render them if you set the format to just the file format, rather than format-variations (i.e. `woff2` instead of `woff2-variations`), but it's best to use the proper syntax if possible. +> Not all browsers have implemented the full syntax for font format, so test carefully. All browsers that support variable fonts will still render them if you set the format to just the file format, rather than format-variations (i.e., `woff2` instead of `woff2-variations`), but it's best to use the proper syntax if possible. > [!NOTE] -> Supplying value ranges for `font-weight`, `font-stretch`, and `font-style` will keep the browser from attempting to render an axis outside that range if you are using the appropriate attribute (i.e. `font-weight` or `font-stretch`), but will not block you from supplying an invalid value via `font-variation-settings`, so use with care. +> Supplying value ranges for `font-weight`, `font-stretch`, and `font-style` will keep the browser from attempting to render an axis outside that range if you are using the appropriate attribute (i.e., `font-weight` or `font-stretch`), but will not block you from supplying an invalid value via `font-variation-settings`, so use with care. ## Working with older browsers @@ -851,7 +851,7 @@ body { - [W3C GitHub issue queue](https://github.com/w3c/csswg-drafts/issues) - [Microsoft Open Type Variations introduction](https://learn.microsoft.com/en-us/typography/opentype/spec/otvaroverview) - [Microsoft OpenType Design-Variation Axis Tag Registry](https://learn.microsoft.com/en-us/typography/opentype/spec/dvaraxisreg) -- [Wakamai Fondue](https://wakamaifondue.com/) (a site that will tell you what your font can do via a simple drag-and-drop inspection interface) +- [Wakamai Fondue](https://wakamaifondue.com/) (a site that will tell you what your font can do via a drag-and-drop inspection interface) - [Axis Praxis](https://www.axis-praxis.org/) (the original variable fonts playground site) - [V-Fonts.com](https://v-fonts.com/) (a catalog of variable fonts and where to get them) - [Font Playground](https://play.typedetail.com/) (another playground for variable fonts with some very unique approaches to user interface) diff --git a/files/en-us/web/css/css_fonts/woff/index.md b/files/en-us/web/css/css_fonts/woff/index.md index 5d4b07434175fa9..a4420aee01f11ef 100644 --- a/files/en-us/web/css/css_fonts/woff/index.md +++ b/files/en-us/web/css/css_fonts/woff/index.md @@ -1,5 +1,6 @@ --- title: The Web Open Font Format (WOFF) +short-title: Web Open Font Format (WOFF) slug: Web/CSS/CSS_fonts/WOFF page-type: guide browser-compat: diff --git a/files/en-us/web/css/css_generated_content/index.md b/files/en-us/web/css/css_generated_content/index.md index d3ea4987e6bb479..91f40aca23ad3a0 100644 --- a/files/en-us/web/css/css_generated_content/index.md +++ b/files/en-us/web/css/css_generated_content/index.md @@ -152,6 +152,12 @@ The CSS generated content module introduces six yet-to-be implemented CSS functi - {{cssxref("counter-increment")}} property - {{cssxref("counter-reset")}} property +- [CSS overflow](/en-US/docs/Web/CSS/CSS_overflow) module + + - {{cssxref("::scroll-button()")}} pseudo-element + - {{cssxref("::scroll-marker")}} pseudo-element + - {{cssxref(":target-current")}} pseudo-class + - [CSS values and units](/en-US/docs/Web/CSS/CSS_Values_and_Units) module - {{cssxref("attr", "attr()")}} function @@ -166,4 +172,4 @@ The CSS generated content module introduces six yet-to-be implemented CSS functi - [CSS pseudo-elements](/en-US/docs/Web/CSS/CSS_pseudo-elements) module - [CSS lists and counters](/en-US/docs/Web/CSS/CSS_lists) module -- [Replaced elements](/en-US/docs/Web/CSS/Replaced_element) +- {{glossary("Replaced elements")}} diff --git a/files/en-us/web/css/css_grid_layout/auto-placement_in_grid_layout/index.md b/files/en-us/web/css/css_grid_layout/auto-placement_in_grid_layout/index.md index 89603a945b2bcd4..f3a7bd7137b9667 100644 --- a/files/en-us/web/css/css_grid_layout/auto-placement_in_grid_layout/index.md +++ b/files/en-us/web/css/css_grid_layout/auto-placement_in_grid_layout/index.md @@ -6,7 +6,7 @@ page-type: guide {{CSSRef}} -[CSS grid layout](/en-US/docs/Web/CSS/CSS_grid_layout/) contains rules that control what happens when you create a grid and do not explicitly place some or all of the child items within the grid. When you don't need explicit control over content placement, this "auto-placement" is the simplest way of creating a grid for a set of items. +[CSS grid layout](/en-US/docs/Web/CSS/CSS_grid_layout) contains rules that control what happens when you create a grid and do not explicitly place some or all of the child items within the grid. When you don't need explicit control over content placement, this "auto-placement" is the simplest way of creating a grid for a set of items. ## Default placement @@ -267,7 +267,7 @@ body { ## The order of auto placed items -A grid can contain a mixture of item placements. Some of the items may have a specifically defined position on the grid while others may be auto-placed. If you have a document order that reflects the order in which items sit on the grid you may not need to write CSS rules to place absolutely everything. The specification contains a long section detailing the [Grid item placement algorithm](https://drafts.csswg.org/css-grid/#auto-placement-algo), however for most of us we just need to remember a few simple rules for our items. +A grid can contain a mixture of item placements. Some of the items may have a specifically defined position on the grid, while others may be auto-placed. If you have a document order that reflects the order in which items sit on the grid, you may not need to write CSS rules to place absolutely everything. The specification contains a long section detailing the [Grid item placement algorithm](https://drafts.csswg.org/css-grid/#auto-placement-algo); however, for most of us, we just need to remember a few rules for our items. ### Order modified document order diff --git a/files/en-us/web/css/css_grid_layout/basic_concepts_of_grid_layout/index.md b/files/en-us/web/css/css_grid_layout/basic_concepts_of_grid_layout/index.md index ba9ae0feec6379b..fe9c27b4453de7a 100644 --- a/files/en-us/web/css/css_grid_layout/basic_concepts_of_grid_layout/index.md +++ b/files/en-us/web/css/css_grid_layout/basic_concepts_of_grid_layout/index.md @@ -98,7 +98,7 @@ Grid tracks are defined in the [explicit grid](#implicit_and_explicit_grids) by ### Basic example -We can add to our earlier example by adding the `grid-template-columns` property, then defining the size of the column tracks. +We can add column tracks to our earlier example by adding the `grid-template-columns` property, then defining the size of the column tracks. We have now created a grid with three 200-pixel-wide column tracks. The child items will be laid out on this grid one in each grid cell. diff --git a/files/en-us/web/css/css_grid_layout/box_alignment_in_grid_layout/index.md b/files/en-us/web/css/css_grid_layout/box_alignment_in_grid_layout/index.md index 7a9c2837fef5db5..da9fa4d2e76b930 100644 --- a/files/en-us/web/css/css_grid_layout/box_alignment_in_grid_layout/index.md +++ b/files/en-us/web/css/css_grid_layout/box_alignment_in_grid_layout/index.md @@ -316,7 +316,7 @@ By combining the align and justify properties we can easily center an item insid ## Aligning the grid tracks on the block axis -If you have a situation where your grid tracks use an area that is smaller than the grid container you can align the grid tracks themselves inside that container. The {{cssxref("align-content")}} aligns the tracks on the block axis and {{cssxref("justify-content")}} aligns on the inline axis. As with the `*-items` and `*-item` properties, the {{CSSxRef("place-content")}} property is shorthand for `align-content` and `justify-content. +If you have a situation where your grid tracks use an area that is smaller than the grid container you can align the grid tracks themselves inside that container. The {{cssxref("align-content")}} aligns the tracks on the block axis and {{cssxref("justify-content")}} aligns on the inline axis. As with the `*-items` and `*-item` properties, the {{CSSxRef("place-content")}} property is shorthand for `align-content` and `justify-content`. The values for `align-content`, `justify-content` and `place-content` all include the {{cssxref("content-distribution")}} and {{cssxref("content-position")}} values. The `align-content` property also accepts {{cssxref("baseline-position")}} values and, like the other `justify-*` properties, `justify-content` also accepts `left` and `right`. @@ -536,7 +536,7 @@ We can also apply the {{cssxref("content-distribution")}} space distribution val If an item spans more than one grid track, using a space distribution value will likely cause items on your grid to become larger because the space that's added between the tracks is added to the spanning item. Therefore, if you use these values, make sure the content of the tracks can cope with the extra space or that you have used alignment properties on the items, so they move to the start or end rather than stretch. -In the below image, we placed the grid with two different `align-content` values to compare `start` and `space-between`. You can see how the first two items, which span two row tracks, have taken on extra height in the `space-between` example as they gain the space that exists because of the of the free space that was distributed _between_ the three rows: +In the below image, we placed the grid with two different `align-content` values to compare `start` and `space-between`. You can see how the first two items, which span two row tracks, have taken on extra height in the `space-between` example as they gain the space that exists because of the free space that was distributed _between_ the three rows: ![Demonstrating how items become larger if we use space-between.](7_space-between.png) diff --git a/files/en-us/web/css/css_grid_layout/grid_layout_and_accessibility/index.md b/files/en-us/web/css/css_grid_layout/grid_layout_and_accessibility/index.md index 2d58fc9b3d03a05..64a325737e0e428 100644 --- a/files/en-us/web/css/css_grid_layout/grid_layout_and_accessibility/index.md +++ b/files/en-us/web/css/css_grid_layout/grid_layout_and_accessibility/index.md @@ -16,7 +16,7 @@ We've already seen in these guides that CSS grid layout gives us the power to re The CSS grid layout specification includes a [Reordering and Accessibility](https://drafts.csswg.org/css-grid/#order-accessibility) section. The introduction to that section details what browsers should do when content is visually reordered using grid layout: -> Grid layout gives authors great powers of rearrangement over the document. However, these are not a substitute for correct ordering of the document source. The `order` property and grid placement do not affect ordering in non-visual media (such as speech). Likewise, rearranging grid items visually does not affect the default traversal order of sequential navigation modes (such as cycling through links, see e.g. [`tabindex`](/en-US/docs/Web/HTML/Global_attributes/tabindex)). +> Grid layout gives authors great powers of rearrangement over the document. However, these are not a substitute for correct ordering of the document source. The `order` property and grid placement do not affect ordering in non-visual media (such as speech). Likewise, rearranging grid items visually does not affect the default traversal order of sequential navigation modes (such as cycling through links, see e.g., [`tabindex`](/en-US/docs/Web/HTML/Reference/Global_attributes/tabindex)). If you reorder things visually using grid layout, this will not change how the items are ordered if the content is being read out by a screen reader, or other text to speech user agent. In addition, the reordering will not change tab order. This means that someone navigating using the keyboard could be tabbing through links on your site and suddenly find themselves jumping from the top to the bottom of the document due to a reordered item being next in the tab order. diff --git a/files/en-us/web/css/css_grid_layout/grid_layout_and_progressive_enhancement/10-float-simple-override.png b/files/en-us/web/css/css_grid_layout/grid_layout_and_progressive_enhancement/10-float-simple-override.png deleted file mode 100644 index 4a3fd1bb946d9fc..000000000000000 Binary files a/files/en-us/web/css/css_grid_layout/grid_layout_and_progressive_enhancement/10-float-simple-override.png and /dev/null differ diff --git a/files/en-us/web/css/css_grid_layout/grid_layout_and_progressive_enhancement/10-float-width-problem.png b/files/en-us/web/css/css_grid_layout/grid_layout_and_progressive_enhancement/10-float-width-problem.png deleted file mode 100644 index ef2f6c1a1b5fc49..000000000000000 Binary files a/files/en-us/web/css/css_grid_layout/grid_layout_and_progressive_enhancement/10-float-width-problem.png and /dev/null differ diff --git a/files/en-us/web/css/css_grid_layout/grid_layout_and_progressive_enhancement/10-floated-cards.png b/files/en-us/web/css/css_grid_layout/grid_layout_and_progressive_enhancement/10-floated-cards.png deleted file mode 100644 index a8a687be42f5d86..000000000000000 Binary files a/files/en-us/web/css/css_grid_layout/grid_layout_and_progressive_enhancement/10-floated-cards.png and /dev/null differ diff --git a/files/en-us/web/css/css_grid_layout/grid_layout_using_line-based_placement/index.md b/files/en-us/web/css/css_grid_layout/grid_layout_using_line-based_placement/index.md index a10b00453d4c1fc..3afee712ee02660 100644 --- a/files/en-us/web/css/css_grid_layout/grid_layout_using_line-based_placement/index.md +++ b/files/en-us/web/css/css_grid_layout/grid_layout_using_line-based_placement/index.md @@ -8,7 +8,7 @@ page-type: guide In the [basic concepts of grid layout](/en-US/docs/Web/CSS/CSS_grid_layout/Basic_concepts_of_grid_layout) guide, we took a brief look at positioning items on a grid using line numbers. In this guide, we will fully explore how this fundamental feature of the specification works. -Starting your exploration of grid with numbered lines is the most logical place to begin because when you use grid layout, you always have numbered lines. The lines are numbered for columns and rows, and are indexed from `1`. Note that grid is indexed according to the writing mode of the document. In a left to right language, such as English, line 1 is on the left-hand side of the grid. If you are working in a right-to-left language, such as Arabic, then line 1 will on the right-hand of the grid. We will learn more about the interaction between writing modes and grids in the [grids, logical values, and writing modes](/en-US/docs/Web/CSS/CSS_grid_layout/Grids_logical_values_and_writing_modes) guide. +Starting your exploration of grid with numbered lines is the most logical place to begin because when you use grid layout, you always have numbered lines. The lines are numbered for columns and rows, and are indexed from `1`. Note that grid is indexed according to the writing mode of the document. In a left-to-right language, such as English, line 1 is on the left-hand side of the grid. If you are working in a right-to-left language, such as Arabic, then line 1 will be on the right-hand of the grid. We will learn more about the interaction between writing modes and grids in the [grids, logical values, and writing modes](/en-US/docs/Web/CSS/CSS_grid_layout/Grids_logical_values_and_writing_modes) guide. ## A basic example @@ -55,7 +55,7 @@ Inside our grid container, we include four child elements. {{ EmbedLiveSample('A_basic_example', '300', '330') }} -If we do not place these on to the grid in any way they will lay out according to the auto-placement rules, one item in each of the first four cells. You can inspect the grid with your browser developer tools to see how the grid defines columns and rows. +If we do not place these onto the grid in any way, they will lay out according to the auto-placement rules, one item in each of the first four cells. You can inspect the grid with your browser developer tools to see how the grid defines columns and rows. ![The example grid highlighted in DevTools](highlighted_grid.png) diff --git a/files/en-us/web/css/css_grid_layout/grid_template_areas/index.md b/files/en-us/web/css/css_grid_layout/grid_template_areas/index.md index 4bdf03a0a3404dd..875004274692b6b 100644 --- a/files/en-us/web/css/css_grid_layout/grid_template_areas/index.md +++ b/files/en-us/web/css/css_grid_layout/grid_template_areas/index.md @@ -29,7 +29,7 @@ We can also define an area by giving it a name and then specify the location of - a sidebar - the main content -![An image showing a simple two column layout with header and footer](4_layout.png) +![An image showing a two column layout with header and footer](4_layout.png) With the {{cssxref("grid-area")}} property we can assign each of these areas a name. By itself, this does not create any layout. Rather, it provides named areas to use in a layout. @@ -237,7 +237,7 @@ As our layout is now contained in one part of the CSS, this makes it very easy t When doing this, define the names for your areas outside of any media queries. That way the content area would always be called `main` no matter where on the grid it is placed. -For our layout above, we might like to have a very simple layout at narrow widths, defining a single column grid and stacking our four items into four rows. +For our layout above, we might like to have a very basic layout at narrow widths, defining a single column grid and stacking our four items into four rows. ```css hidden * { @@ -325,7 +325,7 @@ Many of the grid examples you will find online make the assumption that you will ### Media object example -As a very simple example we can create a "[media object](/en-US/docs/Web/CSS/Layout_cookbook/Media_objects)". This is a component with space for an image or other media on one side and content on the other. The image might be displayed on the right or left of the box. +As an example, we can create a "[media object](/en-US/docs/Web/CSS/Layout_cookbook/Media_objects)". This is a component with space for an image or other media on one side and content on the other. The image might be displayed on the right or left of the box. ![Images showing an example media object design](4_media_objects.png) @@ -468,7 +468,7 @@ The {{cssxref("grid")}} shorthand goes a step further and also sets properties u - {{cssxref("grid-auto-columns")}} - {{cssxref("grid-auto-flow")}} -You can use this syntax in the exact same way as the {{cssxref("grid-template")}} shorthand. Just be aware than when doing so you will reset the other values set by the property. +You can use this syntax in the exact same way as the {{cssxref("grid-template")}} shorthand. Just be aware that when doing so you will reset the other values set by the property. ```css .wrapper { diff --git a/files/en-us/web/css/css_grid_layout/masonry_layout/index.md b/files/en-us/web/css/css_grid_layout/masonry_layout/index.md index 863ac4ec8410ffc..fdfb38d99d611d9 100644 --- a/files/en-us/web/css/css_grid_layout/masonry_layout/index.md +++ b/files/en-us/web/css/css_grid_layout/masonry_layout/index.md @@ -231,6 +231,10 @@ body { In browsers [that do not support masonry](#browser_compatibility), regular grid auto-placement will be used instead. +## Specifications + +{{Specifications}} + ## Browser compatibility {{Compat}} diff --git a/files/en-us/web/css/css_grid_layout/relationship_of_grid_layout_with_other_layout_methods/index.md b/files/en-us/web/css/css_grid_layout/relationship_of_grid_layout_with_other_layout_methods/index.md index 810975726f652aa..a231cb10d2b1e88 100644 --- a/files/en-us/web/css/css_grid_layout/relationship_of_grid_layout_with_other_layout_methods/index.md +++ b/files/en-us/web/css/css_grid_layout/relationship_of_grid_layout_with_other_layout_methods/index.md @@ -127,7 +127,7 @@ If you are using flexbox and find yourself disabling some of the flexibility, yo Most grid alignment features were originally defined is the [CSS flexible box layout](/en-US/docs/Web/CSS/CSS_flexible_box_layout). These features provided proper alignment control for the first time and made it easy to center a box on the page. Flex items can stretch to the height of the flex container, meaning that equal height columns were possible. These properties are now defined in the [CSS box alignment](/en-US/docs/Web/CSS/CSS_box_alignment) module, and are used in multiple layout modes, including grid layout. -We will be taking a proper look at [Aligning items in CSS grid layout](/en-US/docs/Web/CSS/CSS_grid_layout/Box_alignment_in_grid_layout) later. For now, here is a comparison between simple examples of flexbox and grid. +We will be taking a proper look at [Aligning items in CSS grid layout](/en-US/docs/Web/CSS/CSS_grid_layout/Box_alignment_in_grid_layout) later. For now, here is a comparison between examples of flexbox and grid. In the first example, which uses flexbox, we have a container with three items inside. The container's {{cssxref("min-height")}} is set, so it defines the height of the flex container. We have set {{cssxref("align-items")}} on the flex container to `flex-end` so the items will line up at the end of the flex container. We have also set the {{cssxref("align-self")}} property on `box1` so it will override the default and stretch to the height of the container and on `box2` so it aligns to the start of the flex container. diff --git a/files/en-us/web/css/css_houdini/index.md b/files/en-us/web/css/css_houdini/index.md deleted file mode 100644 index a3e926f8f65a6bb..000000000000000 --- a/files/en-us/web/css/css_houdini/index.md +++ /dev/null @@ -1,73 +0,0 @@ ---- -title: CSS Houdini -slug: Web/CSS/CSS_Houdini -page-type: guide -status: - - experimental ---- - -{{CSSRef}} - -**CSS Houdini** is a set of APIs that expose parts of the CSS engine. This makes it easier for developers to create extensions for CSS. These extensions might be to polyfill features that are not yet available in a browser, experiment with new ways of doing layout, or add creative borders or other effects. - -While many Houdini examples showcase the creative possibilities of the APIs, there are many practical use cases. For example, you can use Houdini to create advanced custom properties with type checking and default values. - -## Basic example - -A regular [CSS custom property](/en-US/docs/Web/CSS/--*) consists of a property name and a value. Therefore I might create a custom property called `--background-color` and expect it to be given a color value. The value is then used in the CSS as if it were the color value. - -```css -:root { - --background-color: blue; -} - -.box { - background-color: var(--background-color); -} -``` - -In the above example however, there is nothing to stop someone using some other value for this property, perhaps setting it to a length. Having done so, anywhere that the property is used would have no background color as `background-color: 12px` is not valid. When browsers come across CSS they don't recognize as valid they throw that line away. - -Using {{cssxref("@property")}} however, we can declare the custom property with a {{CSSxRef("@property/syntax","syntax")}} of `<color>`. This shows that we need this property to have a value which is a valid color. - -```css -@property --background-color { - syntax: "<color>"; - inherits: false; - initial-value: blue; -} -``` - -## Houdini worklets - -A feature of Houdini is the {{domxref("Worklet")}}. A worklet is a module, written in JavaScript, that extends CSS using one of the Houdini APIs. You can see an example worklet on the {{domxref("PaintWorkletGlobalScope.registerPaint()")}} page. Once a worklet has been registered you can use it in CSS just like any other value. This means that even if you are not a JavaScript developer, you can access Houdini APIs by using worklets other people have created. - -## Reference - -### CSS at-rule and descriptors - -The {{CSSxRef("@property")}} at-rule allows you to register an advanced custom property. - -- {{CSSxRef("@property")}} -- {{CSSxRef("@property/inherits","inherits")}} -- {{CSSxRef("@property/initial-value","initial-value")}} -- {{CSSxRef("@property/syntax","syntax")}} - -### Houdini API references - -- [CSS Properties and Values API](/en-US/docs/Web/API/CSS_Properties_and_Values_API) -- [CSS Typed Object Model API](/en-US/docs/Web/API/CSS_Typed_OM_API) -- [CSS Painting API](/en-US/docs/Web/API/CSS_Painting_API) -- {{domxref("Worklet")}} reference - -### Houdini guides - -- [Properties and Values API Guide](/en-US/docs/Web/API/CSS_Properties_and_Values_API/guide) -- [Typed OM API Guide](/en-US/docs/Web/API/CSS_Typed_OM_API/Guide) -- [Using the CSS Painting API](/en-US/docs/Web/API/CSS_Painting_API/Guide) - -## External resources - -- [Interactive introduction to Houdini](https://houdini.glitch.me/) -- [A Practical Overview of CSS Houdini](https://www.smashingmagazine.com/2020/03/practical-overview-css-houdini/) -- [Smarter custom properties with Houdini's new API](https://web.dev/articles/css-props-and-vals) diff --git a/files/en-us/web/css/css_images/index.md b/files/en-us/web/css/css_images/index.md index 57d27bdadea603b..fdccd8b79ac9738 100644 --- a/files/en-us/web/css/css_images/index.md +++ b/files/en-us/web/css/css_images/index.md @@ -31,9 +31,10 @@ The **CSS images** module defines the types of images that can be used (the {{CS - {{CSSxRef("gradient/repeating-conic-gradient", "repeating-conic-gradient()")}} - {{CSSxRef("cross-fade", "cross-fade()")}} - {{CSSxRef("element", "element()")}} -- {{CSSxRef("image/image", "image()")}} - {{CSSxRef("image/image-set", "image-set()")}} +The specification also defines the {{CSSxRef("image/image", "image()")}} function, which is not yet supported by any browser. + ### Data types - {{CSSxRef("&lt;gradient&gt;")}} diff --git a/files/en-us/web/css/css_images/replaced_element_properties/index.md b/files/en-us/web/css/css_images/replaced_element_properties/index.md new file mode 100644 index 000000000000000..f168c69186a5f0a --- /dev/null +++ b/files/en-us/web/css/css_images/replaced_element_properties/index.md @@ -0,0 +1,149 @@ +--- +title: Styling replaced elements +slug: Web/CSS/CSS_images/Replaced_element_properties +page-type: guide +--- + +{{CSSRef}} + +Some [CSS](/en-US/docs/Web/CSS) properties apply to all elements, some only to grid and flex containers, others only to transformable elements. This guide introduces the properties that only apply to _replaced elements_. + +A **{{glossary("replaced elements", "replaced element")}}** is an element whose representation is outside the scope of CSS; they're external objects whose representation is independent of the CSS formatting model. Some replaced elements, such as {{HTMLElement("iframe")}} elements, may have stylesheets of their own, but they don't inherit the styles of the parent document. + +## Using CSS with replaced elements + +CSS handles replaced elements specifically in some cases, like when calculating margins and some `auto` values. Only replaced elements can ever have {{glossary("intrinsic size", "intrinsic dimensions")}}. Some replaced elements, but not all, have intrinsic dimensions or a defined baseline, which is used by some CSS properties, such as {{cssxref("vertical-align")}}. + +While document styles can set the size and position of replaced elements, document styles dont affect the replaced elements' content, with some exceptions: The [CSS images module](/en-US/docs/Web/CSS/CSS_images) includes properties which support controlling the positioning of the element's content within its box. + +## Controlling object position within the content box + +The CSS images module defines two properties which can be used to specify how the object contained within the replaced element should be positioned within the element's box area. The `object-fit` property is used to size objects, while the `object-position` property is used to position them. + +### The `object-fit` property + +The `object-fit` property specifies how the replaced element's content object should be fitted to the containing element's box. The property defines how images, videos and other embeddable media formats respond to the height and width of the replaced element's content box. If the height, width, or aspect-ratio of a element differ from the resource that will be occupying space reserved for the element, the `fill`, `contain`, `cover`, `scale-down`, and `none` values define whether the browser should scale the resource, cover the allocated space, contain the asset withing the space, or allow the resource to be distorted. + +When contained or scaled down, any areas of the box not covered by the replaced element will show the element's background. + +The `object-fit` property has no effect on {{HTMLElement("iframe")}}, {{HTMLElement("embed")}}, and {{HTMLElement("fencedframe")}} elements. + +![A square photo of the progressive pride flag flying near a chimney.](https://mdn.github.io/shared-assets/images/examples/progress-pride-flag.jpg) + +If we place the image, a square with a 1:1 aspect ratio, in a 100px x 300px box (1:3 aspect ratio), by default the image will fill the box, distorting itself. We can use the `object-fit` property to define how the image should be rendered when forced into a box with a different size and aspect ratio: + +```html hidden live-sample___example1 live-sample___example2 +<img + src="https://mdn.github.io/shared-assets/images/examples/progress-pride-flag.jpg" + alt="Pride flag" /> +<img + src="https://mdn.github.io/shared-assets/images/examples/progress-pride-flag.jpg" + alt="Pride flag" /> +<img + src="https://mdn.github.io/shared-assets/images/examples/progress-pride-flag.jpg" + alt="Pride flag" /> +<img + src="https://mdn.github.io/shared-assets/images/examples/progress-pride-flag.jpg" + alt="Pride flag" /> +<img + src="https://mdn.github.io/shared-assets/images/examples/progress-pride-flag.jpg" + alt="Pride flag" /> +<img + src="https://mdn.github.io/shared-assets/images/examples/progress-pride-flag.jpg" + alt="Pride flag" /> +<p> + <label><input type="checkbox" /> Change dimensions</label> +</p> +``` + +```css hidden live-sample___example1 live-sample___example2 +body { + display: flex; + gap: 20px; + flex-flow: row wrap; + grid-auto-flow: column; + max-width: 98%; + margin: 10px auto 0; +} +img { + width: 100px; + height: 300px; + outline: 2px solid purple; +} +body:has(:checked) img { + width: 300px; + height: 100px; +} +``` + +```css live-sample___example1 live-sample___example2 +img:nth-of-type(1) { + object-fit: fill; +} +img:nth-of-type(2) { + object-fit: cover; +} +img:nth-of-type(3) { + object-fit: contain; +} +img:nth-of-type(4) { + object-fit: scale-down; +} +img:nth-of-type(5) { + object-fit: none; +} +img:nth-of-type(6) { + /* no object-fit property */ + outline: 2px dashed red; +} +``` + +{{EmbedLiveSample('example1','100%','650')}} + +Check the box to set the height and width values. Note that only the `fill` value (the default) distorts the original image. With all other values, the intrinsic aspect ratio of the image is maintained. + +### The `object-position` property + +The `object-position` property specifies the alignment of the replaced element's content object within the element's box. + +Often used in conjunction with the {{cssxref("object-fit")}} property, it takes as it's value a {{cssxref("position_value", "&lt;position&gt;")}} value, the same value type at used in for {{cssxref("background-position")}}. + +```css live-sample___example2 +img { + object-position: bottom right; +} +``` + +{{EmbedLiveSample('example2','100%','650')}} + +```html hidden live-sample___example3 +<img + src="https://mdn.github.io/shared-assets/images/examples/progress-pride-flag.jpg" + alt="Pride flag" /> +``` + +It can be used without `object-fit`. In this case, the image is rendered at it's intrinsic size (218px x 218px), with the position of the contents of the image set by the `object-position` value. + +```css hidden live-sample___example3 +img { + margin: 10px 0 0 10px; +} +``` + +```css live-sample___example3 +img { + outline: 2px solid; + object-position: 114px 72px; +} +``` + +{{EmbedLiveSample('example3','100%','250')}} + +The `object-position` property works equally well with `<iframe>`, `<video>`, and `<embed>` elements as it does for `<img>`. + +## See also + +- [Understanding aspect ratios](/en-US/docs/Web/CSS/CSS_box_sizing/Understanding_aspect-ratio) +- [CSS images](/en-US/docs/Web/CSS/CSS_images) module +- [CSS display](/en-US/docs/Web/CSS/CSS_display) module +- [CSS backgrounds and borders](/en-US/docs/Web/CSS/CSS_backgrounds_and_borders) module diff --git a/files/en-us/web/css/css_inline_layout/index.md b/files/en-us/web/css/css_inline_layout/index.md index 0cbfaabec53f09b..7750dd881a80a9a 100644 --- a/files/en-us/web/css/css_inline_layout/index.md +++ b/files/en-us/web/css/css_inline_layout/index.md @@ -33,6 +33,11 @@ The specification also defines the `baseline-shift`, `baseline-source`, `initial - {{glossary("baseline/typography", "baseline")}} - {{glossary("leading")}} +## Guides + +- [Inline formatting context](/en-US/docs/Web/CSS/CSS_inline_layout/Inline_formatting_context) + - : Explains the inline formatting context. + ## Related concepts - {{cssxref("font-size")}} property diff --git a/files/en-us/web/css/css_inline_layout/inline_formatting_context/index.md b/files/en-us/web/css/css_inline_layout/inline_formatting_context/index.md new file mode 100644 index 000000000000000..3b47e15be60c6c2 --- /dev/null +++ b/files/en-us/web/css/css_inline_layout/inline_formatting_context/index.md @@ -0,0 +1,231 @@ +--- +title: Inline formatting context +slug: Web/CSS/CSS_inline_layout/Inline_formatting_context +page-type: guide +--- + +{{CSSRef}} + +This guide explains the inline formatting context. + +## Core concepts + +The inline formatting context is part of the visual rendering of a web page. Inline boxes are laid out one after the other, in the direction sentences run in the writing mode in use: + +- In a horizontal writing mode, boxes are laid out horizontally, starting on the left. +- In a vertical writing mode they would be laid out vertically starting at the top. + +In the example below, the two {{HTMLElement("div")}} elements with the black borders are part of a [block formatting context](/en-US/docs/Web/CSS/CSS_display/Block_formatting_context), while inside each box, the words participate in an inline formatting context. The words in the horizontal writing mode run horizontally, while words in the vertical writing mode run vertically. + +```html live-sample___inline +<div class="example horizontal">One Two Three</div> +<div class="example vertical">Four Five Six</div> +``` + +```css live-sample___inline +body { + font: 1.2em sans-serif; +} +.example { + border: 5px solid black; + margin: 20px; +} + +.horizontal { + writing-mode: horizontal-tb; +} +.vertical { + writing-mode: vertical-rl; +} +``` + +{{EmbedLiveSample("inline", "", "220px")}} + +Boxes forming a line are contained by a rectangular area called a line box. This box will be large enough to contain all of the inline boxes in that line; when there is no more room in the inline direction another line will be created. Therefore, a paragraph is a set of inline line boxes, stacked in the block direction. + +When an inline box is split, margins, borders, and padding have no visual effect where the split occurs. In the next example there is a {{HTMLElement("span")}} element wrapping a set of words wrapping onto two lines. The border on the `<span>` breaks at the wrapping point. + +```html live-sample___break +<div class="example"> + Before that night— + <span + >a memorable night, as it was to prove— hundreds of millions of people</span + > + had watched the rising smoke-wreaths of their fires without drawing any + special inspiration from the fact. +</div> +``` + +```css live-sample___break +body { + font: 1.2em sans-serif; +} +.example { + border: 5px solid black; + margin: 20px; +} + +span { + border: 5px solid rebeccapurple; +} +``` + +{{EmbedLiveSample("break")}} + +Margins, borders, and padding in the inline direction are respected. In the example below you can see how the margin, border, and padding on the inline `<span>` element are added. + +```html live-sample___mbp +<div class="example horizontal">One <span>Two</span> Three</div> +<div class="example vertical">Four <span>Five</span> Six</div> +``` + +```css live-sample___mbp +body { + font: 1.2em sans-serif; +} + +.example { + border: 5px solid black; + margin: 20px; +} + +span { + border: 5px solid rebeccapurple; + padding-inline-start: 20px; + padding-inline-end: 40px; + margin-inline-start: 30px; + margin-inline-end: 10px; +} +.horizontal { + writing-mode: horizontal-tb; +} + +.vertical { + writing-mode: vertical-rl; +} +``` + +{{EmbedLiveSample("mbp", "", "340px")}} + +> [!NOTE] +> I am using the logical, flow-relative properties — {{cssxref("padding-inline-start")}} rather than {{cssxref("padding-left")}} — so that they work in the inline dimension whether the text is horizontal or vertical. Read more about these properties in [Logical Properties and Values](/en-US/docs/Web/CSS/CSS_logical_properties_and_values). + +## Alignment in the block direction + +Inline boxes may be aligned in the block direction in different ways, using the {{cssxref("vertical-align")}} property, which will align on the block axis in vertical writing modes (therefore not vertically at all!). In the example below the large text is making the line box of the first sentence larger, therefore the `vertical-align` property can be used to align the inline boxes either side of it. I have used the value `top`, try changing it to `middle`, `bottom`, or `baseline`. + +```html live-sample___align +<div class="example horizontal"> + Before that night—<span>a memorable night</span>, as it was to prove—hundreds + of millions of people had watched the rising smoke-wreaths of their fires + without drawing any special inspiration from the fact. +</div> + +<div class="example vertical"> + Before that night—<span>a memorable night</span>, as it was to prove—hundreds + of millions of people had watched the rising smoke-wreaths of their fires + without drawing any special inspiration from the fact. +</div> +``` + +```css live-sample___align +body { + font: 1.2em sans-serif; +} + +span { + font-size: 200%; + vertical-align: top; +} + +.example { + border: 5px solid black; + margin: 20px; + inline-size: 400px; +} + +.horizontal { + writing-mode: horizontal-tb; +} + +.vertical { + writing-mode: vertical-rl; +} +``` + +{{EmbedLiveSample("align", "", "640px")}} + +## Alignment in the inline direction + +If there is additional space in the inline direction, the {{cssxref("text-align")}} property can be used to align the inline boxes within their line box. Try changing the value of `text-align` below to `end`. + +```html live-sample___text-align +<div class="example horizontal">One Two Three</div> +<div class="example vertical">Four Five Six</div> +``` + +```css hidden live-sample___text-align +body { + font: 1.2em sans-serif; +} + +.example { + border: 5px solid black; + margin: 20px; +} + +.horizontal { + writing-mode: horizontal-tb; +} + +.vertical { + writing-mode: vertical-rl; +} +``` + +```css live-sample___text-align +.example { + text-align: center; + inline-size: 250px; +} +``` + +{{EmbedLiveSample("text-align", "", "350px")}} + +## Effect of floats + +Line boxes usually have the same size in the inline direction, therefore the same width if working in a horizontal writing mode, or height if working in a vertical writing mode. If there is a {{cssxref("float")}} within the same block formatting context however, the float will cause the line boxes that wrap the float to become shorter. + +```html live-sample___float +<div class="box"> + <div class="float">I am a floated box!</div> + <p>I am content inside the container.</p> +</div> +``` + +```css live-sample___float +body { + font: 1.2em sans-serif; +} + +.box { + background-color: rgb(224 206 247); + border: 5px solid rebeccapurple; +} + +.float { + float: left; + width: 250px; + height: 150px; + background-color: white; + border: 1px solid black; + padding: 10px; +} +``` + +{{EmbedLiveSample("float", "", "200px")}} + +## See also + +- [Block formatting context](/en-US/docs/Web/CSS/CSS_display/Block_formatting_context) +- [Visual formatting model](/en-US/docs/Web/CSS/CSS_display/Visual_formatting_model) diff --git a/files/en-us/web/css/css_logical_properties_and_values/basic_concepts_of_logical_properties_and_values/index.md b/files/en-us/web/css/css_logical_properties_and_values/basic_concepts_of_logical_properties_and_values/index.md index ce7290d26ad8c31..d6180f9d12c545b 100644 --- a/files/en-us/web/css/css_logical_properties_and_values/basic_concepts_of_logical_properties_and_values/index.md +++ b/files/en-us/web/css/css_logical_properties_and_values/basic_concepts_of_logical_properties_and_values/index.md @@ -10,7 +10,7 @@ The [CSS logical properties and values module](/en-US/docs/Web/CSS/CSS_logical_p ## Why are logical properties useful -CSS 2.1 and earlier had sized things according to the physical dimensions of the screen. Therefore we describe boxes as having a {{CSSxRef("width")}} and {{CSSxRef("height")}}, position items from the `top` and `left`, assign borders, margin, and padding to the `top`, `right`, `bottom`, `left`, etc. The Logical properties and values module defines mappings for these {{glossary("physical properties")}} and values to their logical, or flow relative, counterparts — e.g. `start` and `end` as opposed to `left` and `right`/`top` and `bottom`. +CSS 2.1 and earlier had sized things according to the physical dimensions of the screen. Therefore we describe boxes as having a {{CSSxRef("width")}} and {{CSSxRef("height")}}, position items from the `top` and `left`, assign borders, margin, and padding to the `top`, `right`, `bottom`, `left`, etc. The Logical properties and values module defines mappings for these {{glossary("physical properties")}} and values to their logical, or flow relative, counterparts — e.g., `start` and `end` as opposed to `left` and `right`/`top` and `bottom`. These mappings are very useful for sites that get translated into languages with a different writing mode than the original layout. For example, with a CSS grid layout, if the grid container has a width applied with the {{CSSxRef("align-self")}} and {{CSSxRef("justify-self")}} properties used to align the grid items, as these properties are flow relative, the `justify-self: start` aligns the item to the start on the inline dimension, and `align-self: start` does the same on the block dimension. @@ -79,7 +79,7 @@ When working with a site in a writing mode other than a horizontal, top-to-botto A key concept of working with flow relative properties and values is the two dimensions of block and inline. CSS layout methods such as flexbox and grid layout use the concepts of `block` and `inline` rather than `right` and `left`/`top` and `bottom` when aligning items. -The `inline` dimension is the dimension along which a line of text runs in the writing mode in use. Therefore, in an English document with the text running horizontally left-to-right, or an Arabic document with the text running horizontally right-to-left, the inline dimension is _horizontal_. Switch to a vertical writing mode (e.g. a Japanese document) and the inline dimension is now _vertical_, as lines in that writing mode run vertically. +The `inline` dimension is the dimension along which a line of text runs in the writing mode in use. Therefore, in an English document with the text running horizontally left-to-right, or an Arabic document with the text running horizontally right-to-left, the inline dimension is _horizontal_. Switch to a vertical writing mode (e.g., a Japanese document) and the inline dimension is now _vertical_, as lines in that writing mode run vertically. The block dimension is the other dimension, and the direction in which blocks — such as paragraphs — display one after the other. In English and Arabic, these run vertically, whereas in any vertical writing mode these run horizontally. diff --git a/files/en-us/web/css/css_logical_properties_and_values/sizing/index.md b/files/en-us/web/css/css_logical_properties_and_values/sizing/index.md index 8a27186e053f210..b16721095919e8d 100644 --- a/files/en-us/web/css/css_logical_properties_and_values/sizing/index.md +++ b/files/en-us/web/css/css_logical_properties_and_values/sizing/index.md @@ -8,7 +8,7 @@ page-type: guide In this guide we will explain the flow-relative mappings between physical dimension properties and logical properties used for sizing elements on our pages. -When specifying the size of an item, the [CSS logical properties and values](/en-US/docs/Web/CSS/CSS_logical_properties_and_values) module gives you the ability to indicate sizing as it relates to the flow of text (inline and block) rather than physical sizing which relates to the physical dimensions of horizontal and vertical (e.g. left and right). While these flow relative mappings may well become the default for many of us, in a design you may well use both physical and logical sizing. You might want some features to always relate to the physical dimensions whatever the writing mode. +When specifying the size of an item, the [CSS logical properties and values](/en-US/docs/Web/CSS/CSS_logical_properties_and_values) module gives you the ability to indicate sizing as it relates to the flow of text (inline and block) rather than physical sizing which relates to the physical dimensions of horizontal and vertical (e.g., left and right). While these flow relative mappings may well become the default for many of us, in a design you may well use both physical and logical sizing. You might want some features to always relate to the physical dimensions whatever the writing mode. ## Mappings for dimensions diff --git a/files/en-us/web/css/css_masking/clipping/index.md b/files/en-us/web/css/css_masking/clipping/index.md new file mode 100644 index 000000000000000..d888526610d02ac --- /dev/null +++ b/files/en-us/web/css/css_masking/clipping/index.md @@ -0,0 +1,550 @@ +--- +title: Introduction to CSS clipping +slug: Web/CSS/CSS_masking/Clipping +page-type: guide +--- + +{{CSSRef}} + +CSS clipping enables you to define visible portions of an element while hiding other parts, effectively "clipping" its content within a specific shape or area. With clipping, elements aren't limited to being rendered as rectangles and can be designed in visually engaging ways. This guide explores the {{cssxref("clip-path")}} property along with some examples. + +## CSS clipping + +Clipping is a CSS technique used to clip (hide) sections of an element, displaying only the area of the element located within a developer-defined path. Clips areas are created by vector paths; anything in the path is visible while areas outside the path are hidden. + +### The `clip-path` property + +The `clip-path` property applies clipping. The value it accepts is a vector path defining the area of the element that should remain visible. The path can be defined using boxes, a reference to an [SVG `<clipPath>`](#svg_as_source), or CSS [shapes and paths](#shape_function). In the following example, we clip a blue square {{htmlelement("div")}}, creating a diamond, using the {{cssxref("basic-shape/polygon","polygon()")}} function as the clipping path: + +```html hidden live-sample__clip-path +<div class="diamond"></div> +``` + +```css live-sample__clip-path +.diamond { + height: 200px; + width: 200px; + background-color: blue; + + clip-path: polygon(0 50%, 50% 100%, 100% 50%, 50% 0); +} +``` + +{{ EmbedLiveSample('clip-path', 230, 230) }} + +With the `clip-path` property, you can make complex shapes by clipping an element to a `<basic-shape>` or to an [SVG source](#svg_as_source). You can [animate and transition `clip-path` shapes](#animation) if the declared states have the same number of vector points. + +### Values of the `clip-path` property + +To visually clip an element, the `clip-path` property is set to either a {{cssxref("geometry-box")}}, a {{cssxref("url_value", "url")}} to a {{svgElement("clipPath")}} clip source, or a {{cssxref("basic-shape")}} created with [shape function](/en-US/docs/Web/CSS/CSS_Values_and_Units/CSS_Value_Functions#shape_functions). + +### Geometry boxes + +The `clip-path` hides everything outside of the clipped region. The most basic clipping is done via a geometry box. You can clip an element based on it's margin, border, padding, or content. The effects of these visual box values can achieved via other CSS properties, such as setting the {{cssxref("border-color")}} to transparent and the {{cssxref("background-origin")}} to the desired visual box. We're looking at these values mostly because these values are using in conjunction with the shape functions, which we'll look at later, to define the origin of the shape clip path. + +[Understanding the reference box](/en-US/docs/Web/CSS/CSS_shapes/Basic_shapes#the_reference_box) used by CSS shapes is important when using `clip-path`, especially with [basic shapes](#clipping_to_basic_shapes), as the reference box defines a shape's coordinate system. + +#### Visual box values + +This live example demonstrates the `clip-path` property's different visual box values on a element, while comparing it to the CSS `background-origin` property. We've applied a {{cssxref("border")}}, a {{cssxref("background-color")}}, a {{cssxref("background-image")}}, and {{cssxref("padding")}} to the {{htmlelement("blockquote")}}. Select a radio button to update the `--value` to a different `<geometry-box>` value, which updates the {{cssxref("background-origin")}} and the {{cssxref("clip-path")}} resolved values. + +```css hidden +body { + display: flex; + flex-flow: row wrap; + place-content: center; +} +blockquote { + float: left; + font-size: 1.2rem; +} +q { + color: white; + font-family: sans-serif; + display: block; + margin-bottom: 0.5em; +} +p { + margin: 0; + line-height: 1.6; +} + +body { + --value: initial; +} +body:has([value="border-box"]:checked) { + --value: border-box; +} +body:has([value="padding-box"]:checked) { + --value: padding-box; +} +body:has([value="content-box"]:checked) { + --value: content-box; +} +body:has([type="checkbox"]:checked) blockquote { + border-radius: 70px; +} +``` + +```css +blockquote { + width: 210px; + padding: 20px; + margin: 20px; + border: 20px dashed #dedede; + background-color: #ededed; + background-image: linear-gradient(rebeccapurple, magenta); + background-repeat: no-repeat; +} + +.clippath { + background-origin: var(--value); + clip-path: var(--value); +} + +.box-model { + background-origin: var(--value); +} +``` + +```html hidden +<blockquote class="clippath"> + <q + >I've learned that people will forget what you said, people will forget what + you did, but people will never forget how you made them feel.</q + > + <cite>&mdash; Maya Angelou</cite> +</blockquote> +<blockquote class="box-model"> + <q + >I've learned that people will forget what you said, people will forget what + you did, but people will never forget how you made them feel.</q + > + <cite>&mdash; Maya Angelou</cite> +</blockquote> + +<fieldset> + <legend>Select the geometry box value:</legend> + <p> + <label + ><input type="radio" name="gb" value="border-box" /> border-box</label + > + </p> + <p> + <label + ><input type="radio" name="gb" value="padding-box" /> padding-box</label + > + </p> + <p> + <label + ><input type="radio" name="gb" value="content-box" /> content-box</label + > + </p> + <p> + <label + ><input type="radio" name="gb" value="initial" checked /> initial</label + > + </p> +</fieldset> +<p> + <label><input type="checkbox" /> Change the border radius</label> +</p> +``` + +{{ EmbedLiveSample('visual box values', 230, 430) }} + +When a `<geometry>` box is specified in combination with a `<basic-shape>`, the value defines the reference box for the basic shape. If specified by itself, it causes the edges of the specified box, including any corner shaping (such as a `border-radius`), to be the clipping path. + +#### Shape origin + +The previous example may make you think that the `<geometry-box>` values are useless, as you can use `background-origin` instead. And you can. But when clipping using basic shapes, the `<geometry-box>`, when included along with a `<basic-shape>` as the `clip-path` value, defines the reference box for, or origin of, that shape. We can combine the two previous examples to demonstrate this. + +```html hidden +<blockquote class="clippath"> + <q + >I've learned that people will forget what you said, people will forget what + you did, but people will never forget how you made them feel.</q + > + <cite>&mdash; Maya Angelou</cite> +</blockquote> +<fieldset> + <legend>Select the origin of the clip path shape:</legend> + <p> + <label + ><input type="radio" name="gb" value="border-box" checked /> + border-box</label + > + </p> + <p> + <label + ><input type="radio" name="gb" value="padding-box" /> padding-box</label + > + </p> + <p> + <label + ><input type="radio" name="gb" value="content-box" /> content-box</label + > + </p> +</fieldset> +``` + +```css +blockquote { + width: 210px; + padding: 20px; + margin: 20px; + border: 20px dashed #dedede; + background-color: #ededed; + background-image: linear-gradient(rebeccapurple, magenta); + background-repeat: no-repeat; + background-origin: border-box; + clip-path: var(--value) polygon(0 50%, 50% 100%, 100% 50%, 50% 0); +} +``` + +```css hidden +blockquote { + font-size: 1.2rem; +} +q { + color: white; + font-family: sans-serif; + display: block; + margin-bottom: 0.5em; +} +p { + margin: 0; + line-height: 1.6; +} + +body { + --value: ""; +} +body:has([value="border-box"]:checked) { + --value: border-box; +} +body:has([value="padding-box"]:checked) { + --value: padding-box; +} +body:has([value="content-box"]:checked) { + --value: content-box; +} +``` + +{{ EmbedLiveSample('shape origin', 230, 420) }} + +For another example, see [`clip-path` shapes and geometry boxes](/en-US/docs/Web/CSS/clip-path#shapes_and_geometry_boxes). + +Even values like `clip-path: margin-box` can be useful. In addition to creative visuals made by placing the clip-path's edge at the margin-box edge, any computed value for `clip-path`, other than `none`, results in the creation of a new [stacking context](/en-US/docs/Web/CSS/CSS_positioned_layout/Stacking_context) the same way that CSS {{cssxref("opacity")}} does for values other than `1`. + +## Clipping to basic shapes + +The `clip-path` property's support of {{cssxref("basic-shape")}} values provides a powerful way to shape elements. The various shape function enable defining precise clipping regions, effectively sculpting elements into unique forms. The basic shape functions, include: + +- {{cssxref("basic-shape/circle","circle()")}} +- {{cssxref("basic-shape/ellipse","ellipse()")}} +- {{cssxref("basic-shape/inset","inset()")}} +- {{cssxref("basic-shape/path","path()")}} +- {{cssxref("basic-shape/polygon","polygon()")}} +- {{cssxref("basic-shape/rect","rect()")}} +- {{cssxref("basic-shape/shape","shape()")}} +- {{cssxref("basic-shape/xywh","xywh()")}} + +The size and position of these shapes are defined by the `<geometry-box>` value, which defaults to border-box being used as the reference box if the `clip-path` value includes a shape without the `<geometry-box>` component value. + +Some of these functions appear to only provide basic predefined clipping options. They may appear to replicate effects you can created with {{cssxref("border-radius")}}, but if you [toggled the `border-radius`](#visual_box_values) property in the previous example, you may have noticed the power of CSS clipping. Shapes provide even more control. For example, `inset()` enables clipping a rectangle with precise margins. The real power and control comes with `path()`, `shape()`, and even `polygon()`, which allows for custom multi-point shapes. + +### Creating polygons + +With `polygon()`, by defining pairs of coordinates, each of which represents a vertex of the shape. you can create intricate forms like stars or abstract figures. The coordinates define vector points connected by straight lines. + +Here we use the `polygon()` function to create a star: + +```html hidden +<div class="star"></div> +``` + +```css +.star { + width: 200px; + height: 200px; + background: linear-gradient(rebeccapurple, magenta) blue; + clip-path: polygon( + 50% 0%, + 61% 35%, + 100% 35%, + 68% 57%, + 79% 91%, + 50% 70%, + 21% 91%, + 32% 57%, + 0% 35%, + 39% 35%, + 50% 0% + ); +} +``` + +{{ EmbedLiveSample('Creating polygons', 230, 230) }} + +### Animation + +Clipped shapes can be animated and transitioned by declaring the same number of vector points for the different states. + +```html hidden +<div class="star"></div> +``` + +```css hidden +.star { + width: 200px; + height: 200px; + background: linear-gradient(rebeccapurple, magenta) blue; + clip-path: polygon( + 50% 0%, + 61% 35%, + 100% 35%, + 68% 57%, + 79% 91%, + 50% 70%, + 21% 91%, + 32% 57%, + 0% 35%, + 39% 35%, + 50% 0% + ); +} +``` + +```css +@keyframes morphStar { + from { + clip-path: polygon( + 50% 0%, + 61% 35%, + 100% 35%, + 68% 57%, + 79% 91%, + 50% 70%, + 21% 91%, + 32% 57%, + 0% 35%, + 39% 35%, + 50% 0% + ); + } + to { + clip-path: polygon( + 50% 10%, + 65% 30%, + 90% 20%, + 75% 60%, + 85% 95%, + 50% 80%, + 15% 95%, + 25% 60%, + 10% 20%, + 35% 30%, + 50% 10% + ); + } +} + +.star { + animation: morphStar alternate 3s infinite ease-in-out; +} +``` + +{{ EmbedLiveSample('Animation', 230, 230) }} + +### The `path()` function + +The `path()` function enables drawing shapes using SVG commands. The function accepts the equivalent of the SVG {{svgattr("d")}} attribute as the function's parameter. + +The star from the previous example can be created using `path()`: + +```html hidden +<div class="star"></div> +``` + +```css +.star { + width: 200px; + height: 200px; + background: linear-gradient(rebeccapurple, magenta) blue; + clip-path: path( + "M100,0 L122,70 L200,70 L136,114 L158,182 L100,140 L42,182 L64,114 L0,70 L78,70 L100,0 Z" + ); +} +``` + +{{ EmbedLiveSample('The path function', 230, 230) }} + +### Curved lines + +With `path()`, we are not limited to straight lines. In this example, we use the `path()` function to create a heart: + +```html hidden +<div class="heart"></div> +``` + +```css +.heart { + width: 200px; + height: 200px; + background: linear-gradient(rebeccapurple, magenta) blue; + clip-path: path( + "M20,70 A40,40,0,0,1,100,70 A40,40,0,0,1,180,70 Q180,130,100,190 Q20,130,20,70 Z" + ); +} +``` + +{{ EmbedLiveSample('Curved lines', 230, 230) }} + +### SVG as source + +Instead of passing an SVG {{svgattr("d")}} attribute string as the `path()` function argument, the value of the `clip-path` property can reference the SVG {{svgElement("clipPath")}} element directly. + +```html +<div class="heart"></div> +<svg height="0" width="0"> + <clipPath id="heart"> + <path + d="M20,70 A40,40,0,0,1,100,70 A40,40,0,0,1,180,70 Q180,130,100,190 Q20,130,20,70 Z" /> + </clipPath> +</svg> +``` + +The `id` of the `<clipPath>` is the parameter of the {{cssxref("url_function", "url()")}} function. + +```css +.heart { + width: 200px; + height: 200px; + background: linear-gradient(rebeccapurple, magenta) blue; + clip-path: url(#heart); +} +``` + +{{ EmbedLiveSample('svg as source', 230, 230) }} + +### Shape function + +The SVG path syntax is not the most intuitive. For this reason, CSS also offers a `shape()` function. The `shape()` function also takes path drawing directive, but with a syntax that is more human readable. We can recreate the heart with more declarative CSS: + +```css +.heart { + clip-path: shape( + from 20px 70px, + arc to 100px 70px of 1% cw, + arc to 180px 70px of 1% cw, + curve to 100px 190px with 180px 130px, + curve to 20px 70px with 20px 130px + ); +} +``` + +The `shape()` function is more robust in that it accepts CSS values and units (`path()` is limited to coordinates), including using CSS math functions like `calc()`. By using variables, we can create shapes (and boxes) of many different sizes: + +```css +:root { + --m: 10; +} +.heart { + width: calc(20px * var(--m)); + height: calc(20px * var(--m)); + display: inline-block; + background: linear-gradient(rebeccapurple, magenta) blue; + clip-path: border-box + shape( + from calc(2px * var(--m)) calc(7px * var(--m)), + arc to calc(10px * var(--m)) calc(7px * var(--m)) of 1% cw, + arc to calc(18px * var(--m)) calc(7px * var(--m)) of 1% cw, + curve to calc(10px * var(--m)) calc(19px * var(--m)) with + calc(18px * var(--m)) calc(13px * var(--m)), + curve to calc(2px * var(--m)) calc(7px * var(--m)) with + calc(2px * var(--m)) calc(13px * var(--m)) + ); +} +.small { + --m: 4; +} + +.medium { + --m: 8; +} + +.large { + --m: 12; +} +``` + +```html +<div class="heart small"></div> +<div class="heart medium"></div> +<div class="heart large"></div> +``` + +{{ EmbedLiveSample('shape function', 230, 270) }} + +### Wrapping text around your clipped shapes + +Clipped elements are still rectangular boxed. Clipping means your element doesn't look like a box; but it is still a box. To wrap inline content around the non-rectangular (or rectangular) shapes you define, use the {{cssxref("shape-outside")}} property. By default, inline content wraps around its margin box; `shape-outside` provides a way to customize this wrapping, making it possible to wrap text around the elements you've clipped, following the clip path you replicated rather than the element's rectangular box. + +The content includes two elements to be clipped and the content that will be shaped around them. + +```html +<div class="leftTriangle"></div> +<div class="rightTriangle"></div> +<blockquote> + <q> + I've learned that people will forget what you said, people will forget what + you did, but people will never forget how you made them feel.</q + > + <cite>&mdash; Maya Angelou</cite> +</blockquote> +``` + +```css hidden +:root { + --m: 10; + font-size: calc(3px * var(--m)); +} +div { + width: calc(0.75em * var(--m)); + height: calc(0.75em * var(--m)); + display: inline-block; + background: linear-gradient(rebeccapurple, magenta) blue; +} +cite { + display: block; + text-align: right; +} +``` + +In addition to applying the same shape for both the `clip-shape` and `shape-outside` properties, the clipped element has to be floated so that the clipped element is on the same line as the content. + +```css +.leftTriangle { + clip-path: polygon(0 0, 0 100%, 100% 0); + shape-outside: polygon(0 0, 0 100%, 100% 0); + float: left; +} +.rightTriangle { + clip-path: polygon(100% 0, 100% 100%, 0 100%); + shape-outside: polygon(100% 0, 100% 100%, 0 100%); + float: right; +} +``` + +{{ EmbedLiveSample('Wrapping text around your clipped shapes', 230, 290) }} + +## See also + +- {{cssxref("basic-shape")}} +- {{cssxref("shape-image-threshold")}} +- {{cssxref("shape-margin")}} +- [Overview of shapes](/en-US/docs/Web/CSS/CSS_shapes/Overview_of_shapes) +- [Introduction to CSS masking](/en-US/docs/Web/CSS/CSS_masking/Masking) +- [CSS masking](/en-US/docs/Web/CSS/CSS_masking) module +- [CSS shapes](/en-US/docs/Web/CSS/CSS_shapes) module diff --git a/files/en-us/web/css/css_masking/index.md b/files/en-us/web/css/css_masking/index.md index 5f90a18836967f4..a5bfc8355afa032 100644 --- a/files/en-us/web/css/css_masking/index.md +++ b/files/en-us/web/css/css_masking/index.md @@ -7,23 +7,26 @@ spec-urls: https://drafts.fxtf.org/css-masking/ {{CSSRef}} -The **CSS masking** module that defines masking and clipping for partially or fully hiding portions of visual elements. +The **CSS masking** module defines masking and clipping, two different graphical operations that are used to partially or fully hide portions of visual elements. + +**Clipping** involves defining a closed vector path, shape, or polygon as a **clipping path**. Everything inside the clipping path region remains visible while everything outside is hidden, or "clipped out". The {{cssxref("clip-path")}} property specifies a {{cssxref("&lt;basic-shape&gt;")}} or references an SVG {{SVGElement("clipPath")}} element to be used as a clipping path. + +CSS **masking** properties are used to apply a mask to an element or its border. A graphical object is then painted onto the background or border, completely or partially masking out parts of the element or its border, depending on the opacity or luminance of the mask. + +The image used as the mask is specified by the {{cssxref("mask-image")}} or {{cssxref("mask-border-source")}} properties. The specified mask can be an {{cssxref("image")}}, a {{cssxref("gradient")}}, or an SVG {{SVGElement("mask")}} element. The mask can be sized and positioned similarly to [background and border images](/en-US/docs/Web/CSS/CSS_backgrounds_and_borders). + +Clipping and masking in CSS behaves the same way as it does with SVG: First, the element is styled without filter effects, masking, clipping, and opacity. Then, any effects are applied to the element in the following order: [filter effects](/en-US/docs/Web/CSS/CSS_filter_effects), clipping, masking, and opacity. + +While masking provides more control and options, clipping can perform better if a basic shape is all that's required — they are easier to interpolate. ## Reference ### Properties -- {{cssxref("clip")}} +- {{cssxref("clip")}} {{deprecated_inline}} - {{cssxref("clip-path")}} - {{cssxref("clip-rule")}} -- {{cssxref("mask")}} -- {{cssxref("mask-border")}} -- {{cssxref("mask-border-mode")}} -- {{cssxref("mask-border-outset")}} -- {{cssxref("mask-border-repeat")}} -- {{cssxref("mask-border-slice")}} -- {{cssxref("mask-border-source")}} -- {{cssxref("mask-border-width")}} +- {{cssxref("mask")}} shorthand - {{cssxref("mask-clip")}} - {{cssxref("mask-composite")}} - {{cssxref("mask-image")}} @@ -33,7 +36,74 @@ The **CSS masking** module that defines masking and clipping for partially or fu - {{cssxref("mask-repeat")}} - {{cssxref("mask-size")}} - {{cssxref("mask-type")}} +- {{cssxref("mask-border")}} shorthand +- {{cssxref("mask-border-mode")}} +- {{cssxref("mask-border-outset")}} +- {{cssxref("mask-border-repeat")}} +- {{cssxref("mask-border-slice")}} +- {{cssxref("mask-border-source")}} +- {{cssxref("mask-border-width")}} + +### Data types + +- [`<geometry-box>`](/en-US/docs/Web/CSS/clip-path#geometry-box) + +### Functions + +- {{cssxref("basic-shape/rect","rect()")}} function + +### Interfaces + +- {{domxref("SVGClipPathElement")}} +- {{domxref("SVGMaskElement")}} + - {{domxref("SVGMaskElement.maskContentUnits")}} + +## Guides + +- [Introduction to CSS clipping](/en-US/docs/Web/CSS/CSS_masking/Clipping) + + - : Introduction to clipping in CSS, including the `clip-path` property with examples. + +- [Introduction to CSS masking](/en-US/docs/Web/CSS/CSS_masking/Masking) + + - : Introduction to masking in CSS, the various mask image types, and the effects of luminance and alpha-transparency in masking. + +## Related concepts + +- [`<coord-box>`](/en-US/docs/Web/CSS/box-edge#values) +- {{cssxref("&lt;image&gt;")}} +- {{cssxref("&lt;position&gt;")}} +- {{cssxref("&lt;url&gt;")}} + +- [CSS backgrounds and borders](/en-US/docs/Web/CSS/CSS_backgrounds_and_borders) module + + - {{cssxref("background")}} shorthand + - {{cssxref("background-origin")}} + - {{cssxref("background-position")}} + - {{cssxref("background-repeat")}} + - {{cssxref("background-size")}} + - {{cssxref("border-image")}} shorthand + - {{cssxref("border-image-repeat")}} + - {{cssxref("border-image-slice")}} + - {{cssxref("border-image-source")}} + - {{cssxref("border-image-width")}} + - [`<repeat-style>`](/en-US/docs/Web/CSS/background-repeat#values) data type + +- [CSS shapes](/en-US/docs/Web/CSS/CSS_shapes) module + + - {{cssxref("&lt;basic-shape&gt;")}} data type + - {{cssxref("basic-shape/polygon","polygon()")}} function + - [`<shape-box>`](/en-US/docs/Web/CSS/shape-outside#shape-box) data type ## Specifications {{Specifications}} + +## See also + +- {{cssxref("background-clip")}} +- [CSS filter effects](/en-US/docs/Web/CSS/CSS_filter_effects) module +- [SVG tutorial: clipping and masking](/en-US/docs/Web/SVG/Tutorials/SVG_from_scratch/Clipping_and_masking) +- {{domxref("CanvasRenderingContext2D.clip()")}} +- {{domxref("WebGLRenderingContext.colorMask()")}} +- [PWA icon masking](/en-US/docs/Web/Progressive_web_apps/How_to/Define_app_icons#support_masking) diff --git a/files/en-us/web/css/css_masking/masking/index.md b/files/en-us/web/css/css_masking/masking/index.md new file mode 100644 index 000000000000000..a7d16d93d7087dd --- /dev/null +++ b/files/en-us/web/css/css_masking/masking/index.md @@ -0,0 +1,293 @@ +--- +title: Introduction to CSS masking +slug: Web/CSS/CSS_masking/Masking +page-type: guide +--- + +{{CSSRef}} + +CSS masking enables you to reveal or hide parts of an element selectively by applying one or more mask images to it. These mask images can be gradients, images, or SVG sources. Unlike [CSS clipping](/en-US/docs/Web/CSS/CSS_masking/Clipping), which either fully shows or hides areas of an element based on the shape of a single path, masking allows for nuanced transparency and blending effects based on the alpha transparency and, optionally, luminance of the mask images. + +This guide introduces the concept of masking, the various mask image types, and how the luminance and alpha-transparency of the mask impact the portions of the element that are masked (made visible), versus the portions that are clipped (or hidden). + +## What is masking in CSS? + +In CSS, masks can be used to define areas of an element that are visible and other areas that are hidden. Mask layers, defined by one or more {{cssxref("mask-image")}} sources, determine the areas of an element that should be visible and at what opacity. + +> [!NOTE] +> Multiple CSS masking property values can be set using the {{cssxref("mask")}} shorthand property. + +With `alpha` masks, the opacity of the masked element matches the opacity of the mask applied. In CSS, masking is the opposite of a masquerade mask, where the face is hidden wherever the mask is opaque. In CSS, the areas of the element where its mask is fully opaque will be fully opaque and visible. Wherever the mask is fully transparent, the element will be fully hidden. Areas of the element that are masked by partially opaque mask areas will be partially opaque, matching the mask's opacity. + +With alpha masks, the color of the mask is irrelevant. Only the opacity of the mask matters. With [luminance masks](#alpha_transparency_versus_luminance), the brightness of the mask colors is taken into account when determining the opacity of the masked element. The brighter and more opaque the color, the more opaque the element. The darker and more transparent the color, the less opaque the mask will be. + +Masks can be defined using CSS gradients, raster images (such as PNGs), and SVG {{svgelement("mask")}} elements. In this guide, we introduce the various mask image types as we discuss [opaqueness and transparency](#opaqueness_versus_transparency), [luminance](#alpha_transparency_versus_luminance), and [masking versus CSS clipping](#svg_mask_as_mask_source). + +Each mask layer consists of a {{cssxref("mask-image")}}, which is [positioned](/en-US/docs/Web/CSS/mask-position) relative to an origin box. The mask images can be [sized](/en-US/docs/Web/CSS/mask-size), [repeated](/en-US/docs/Web/CSS/mask-repeat), and [clipped](/en-US/docs/Web/CSS/mask-clip). In cases where multiple mask images are declared, the way the [mask layers are composited](/en-US/docs/Web/CSS/mask-composite), or combined, can be set. These are discussed in the [masking properties guide](/en-US/docs/Web/CSS/CSS_masking/CSS_mask_properties). + +> [!NOTE] +> All examples will be using the following image as the underlying element upon which masks will be applied: +> +> <img src="https://mdn.github.io/shared-assets/images/examples/progress-pride-flag.jpg" alt="Pride flag" /> + +## Opaqueness versus transparency + +```html hidden live-sample___gradient1 live-sample___gradient2 live-sample___image1 live-sample___luminance1 live-sample___luminance2 live-sample___luminance3 +<img + src="https://mdn.github.io/shared-assets/images/examples/progress-pride-flag.jpg" + alt="Pride flag" + class="applied-mask" /> +<div class="mask-source"></div> +``` + +```css hidden live-sample___gradient1 live-sample___gradient2 live-sample___image1 live-sample___luminance1 live-sample___luminance2 live-sample___luminance3 live-sample___svg1 +body { + display: flex; + gap: 20px; + padding: 15px; + background-image: + linear-gradient(to right, rgb(0 0 0 / 0) 50%, rgb(0 0 0 / 0.05) 50%), + linear-gradient(to bottom, rgb(0 0 0 / 0) 50%, rgb(0 0 0 / 0.05) 50%); + background-size: 20px 20px; +} +div, +svg, +img { + width: 220px; + aspect-ratio: 1; +} +``` + +With alpha masks, the visible areas of an element are defined by the alpha-transparency of the mask applied to it. Wherever the mask is fully opaque, the element will be visible. At every pixel where the mask is fully transparent, the element too will be fully hidden. Areas of the element that are masked by a partially opaque section of a mask will be partially opaque, matching the opacity of the mask applied to it. + +To demonstrate this, let's look at an example using a {{cssxref("conic-gradient")}} as the `mask-image`. CSS gradients, including conic gradients, can be used to create smooth transitions between visible and hidden areas. + +In this case, the top-right corner of the mask is fully opaque, the top-left quadrant is fully transparent, and the bottom half has a smooth transition between opaque and transparent. + +```css live-sample___gradient1 +.applied-mask { + mask-image: conic-gradient(rgb(0 0 0 / 1) 90deg, rgba(0 0 0 / 0) 270deg); +} +.mask-source { + background: conic-gradient(rgb(0 0 0 / 1) 90deg, rgba(0 0 0 / 0) 270deg); +} +``` + +Note how the element on which the mask is applied has a fully visible top-right corner, the top-left quarter is hidden, and the bottom half transitions smoothly from visible to transparent, reflecting the visibility of the applied mask image. + +{{EmbedLiveSample("gradient1", "", "250px")}} + +With alpha masks, the color of the mask doesn't matter, only the transparency. In this example, we have a striped gradient with fully opaque red, semi-opaque red, and fully transparent stripes. + +```css live-sample___gradient2 +.applied-mask { + mask-image: repeating-linear-gradient( + to bottom right, + #f00 0 20px, + #f005 20px 40px, + transparent 40px 60px + ); +} +.mask-source { + background: repeating-linear-gradient( + to bottom right, + #f00 0 20px, + #f005 20px 40px, + transparent 40px 60px + ); +} +``` + +Note how the fully opaque mask areas reveal fully opaque element pixels, semi-transparent mask areas create semi-transparent areas, and fully transparent mask areas hide the associated areas completely. + +{{EmbedLiveSample("gradient2", "", "250px")}} + +The previous two examples used gradients as masks and background images. The mask image doesn't have to be a CSS image. It can be an external image or an SVG. + +In this case we use an external PNG. The image contains a colorful heart with a transparent background. + +```css live-sample___image1 live-sample___luminance1 +.applied-mask { + mask-image: url(https://mdn.github.io/shared-assets/images/examples/colorful-heart.png); + mask-size: 220px 220px; +} +.mask-source { + background: url(https://mdn.github.io/shared-assets/images/examples/colorful-heart.png); + background-size: 220px 220px; +} +``` + +Note how the transparent mask areas crop the element; the only parts of the element that are visible are the areas where the mask is opaque. The color of the mask itself doesn't matter. + +{{EmbedLiveSample("image1", "", "250px")}} + +## Alpha transparency versus luminance + +The `mask-mode` property's default value — `match-source` — sets the mode to either `alpha` or `luminance`, depending on the value. The `match-source` value resolves to `alpha` for all mask sources other than SVG {{svgelement("mask")}} elements. If the mask source is a `<mask>` element, `match-source` resolves to the `<mask>`'s {{cssxref("mask-type")}} property value, if set. Otherwise, it resolves to the value of the SVG {{svgattr("mask-type")}} attribute set on the `<mask>` element. If that is not explicitly set either, `match-source` will resolve to `luminance`. + +If `mask-mode` resolves to `luminance`, or we explicitly set it to `luminance`, the colors of the mask will affect the mask opacity. In the previous demo, the `mask-mode` was not set, so the value defaulted to `match-source`. As the colorful heart image is a transparent PNG, `match-source` resolves to `alpha`. By explicitly setting this property, we can control the mode. In this demo, we change the `mask-mode` to `luminance`. + +```css live-sample___luminance1 +.applied-mask { + mask-mode: luminance; +} +``` + +When applying `mask-mode: luminance` to the same mask as in the previous example, the areas of the element where the mask is **lightest** are more opaque, while **darker** areas are less opaque. + +{{EmbedLiveSample("luminance1", "", "250px")}} + +The opacity of a luminance mask is determined by the `R`, `G`, `B`, and `A` values of an {{glossary("RGB")}} color using the formula: + +`((0.2125 * R) + (0.7154 * G) + (0.0721 * B)) * A` + +For example, the newest {{cssxref("named-color")}} is `rebeccapurple`, which is `#663399`. While one might assume the lightness might be equivalent to the L of the `hsl()` color function, it's not that simple. The value `#663399` is equivalent to `rgb(40% 20% 60% / 1)` and `hsl(270 50% 40% / 1)`, but the brightness value is `27.134%`, not `40%`. + +`((0.2125 * 0.4) + (0.7154 * 0.2) + (0.0721 * 0.6)) * 1 = 0.27134` + +White has a brightness value of `100%`. + +`((0.2125 * 1) + (0.7154 * 1) + (0.0721 * 1)) * 1 = 1` + +Black's brightness is `0%`. + +`((0.2125 * 0) + (0.7154 * 0) + (0.0721 * 0)) * 1 = 0` + +We'll demonstrate this by adding white (`rgb(100% 100% 100%)`) with a lightness of `100%` at `27.234%` opacity to a `rebeccapurple`, `white`, and `black` linear gradient, which we'll then use to mask our image. This white resolves to the same opacity value: + +`((0.2125 * 1) + (0.7154 * 1) + (0.0721 * 1)) * 0.27134 = 0.27134` + +```css live-sample___luminance2 +.applied-mask { + mask-image: repeating-linear-gradient( + to bottom left, + rebeccapurple 0 20px, + rgb(100% 100% 100% / 0.27134) 20px 40px, + black 40px 45px, + white 45px 50px + ); + mask-mode: luminance; +} +.mask-source { + background: repeating-linear-gradient( + to bottom left, + rebeccapurple 0 20px, + rgb(100% 100% 100% / 0.27134) 20px 40px, + black 40px 45px, + white 45px 50px + ); +} +``` + +```css hidden live-sample___luminance2 live-sample___luminance3 +:has(:checked) .applied-mask { + mask-mode: alpha; +} +``` + +```html hidden live-sample___luminance2 live-sample___luminance3 +<label><input type="checkbox" /><code>mask-mode: alpha;</code></label> +``` + +The areas with a `white` mask are fully opaque. The areas with a `black` mask are fully transparent. The areas with a `rebeccapurple` mask and the areas with a `27.1234%` opaque white mask are both `27.1234%` opaque. + +{{EmbedLiveSample("luminance2", "", "250px")}} + +If you toggle the `mask-mode` to `alpha`, the color of the gradient no longer matters. The entire element will be opaque except the areas covered by the semi-opaque white. + +The `mask-mode` property enables using raster images without alpha transparency, such as JPEGs, as mask images. A JPEG is made up of opaque pixels. Using a JPEG as a mask with its default `alpha` mask mode would hide the entire element. The `luminance` value of `mask-mode`, on the other hand, clips the element where the mask is black (has no lightness), is fully opaque where the mask is opaque white (100% lightness), with other areas being semi-transparent based on the lightness of the mask area masking it. + +In this example, we have a white moon against a black night sky. + +```css live-sample___luminance3 +.applied-mask { + mask-image: url(https://mdn.github.io/shared-assets/images/examples/moon.jpg); + mask-mode: luminance; + mask-size: 220px; +} +.mask-source { + background: url(https://mdn.github.io/shared-assets/images/examples/moon.jpg); + background-size: 220px; +} +``` + +The element is clipped and not visible where the sky is black. The image is most visible where the moon is at it's lightest. + +{{EmbedLiveSample("luminance3", "", "250px")}} + +In this case, if you toggle the `mask-mode` to `alpha`, the entire element will be visible as the entire mask is opaque. + +## SVG `<mask>` as mask source + +A mask can be any type of CSS {{cssxref("image")}} or a `<mask-source>`. A `<mask-source>` is a {{cssxref("url_value", "&lt;url&gt;")}} reference to an SVG {{SVGElement("mask")}} element. This is similar to clipping with the CSS {{cssxref("clip-path")}} property, in which case the "mask" is an SVG {{SVGElement("clipPath")}} element instead (with `clip-path`, the luminance of the path doesn't matter). + +In this example, we define an SVG with a `<mask>` element, an identical {{SVGElement("clipPath")}} element, and an identical {{SVGElement("path")}} element so you can view the mask and clip path source. + +```html live-sample___svg1 +<img + src="https://mdn.github.io/shared-assets/images/examples/progress-pride-flag.jpg" + alt="Pride flag" + class="applied-mask" /> +<svg class="mask-source"> + <mask id="mask-heart"> + <path + d="M20,70 A40,40,0,0,1,100,70 A40,40,0,0,1,180,70 Q180,130,100,190 Q20,130,20,70 Z" + fill="rgb(255 0 0 / 0.5)" + stroke="rgb(255 255 255 / 1)" + stroke-width="20" /> + </mask> + <clippath id="clip-heart"> + <path + d="M20,70 A40,40,0,0,1,100,70 A40,40,0,0,1,180,70 Q180,130,100,190 Q20,130,20,70 Z" + fill="rgb(255 0 0 / 0.5)" + stroke="rgb(255 255 255 / 1)" + stroke-width="20" /> + </clippath> + <path + d="M20,70 A40,40,0,0,1,100,70 A40,40,0,0,1,180,70 Q180,130,100,190 Q20,130,20,70 Z" + fill="rgb(255 0 0 / 0.5)" + stroke="rgb(255 255 255 / 1)" + stroke-width="20" /> +</svg> +<img + src="https://mdn.github.io/shared-assets/images/examples/progress-pride-flag.jpg" + alt="Pride flag" + class="applied-clip" /> +``` + +```css live-sample___svg1 +.applied-mask { + mask-image: url(#mask-heart); +} +.applied-clip { + clip-path: url(#clip-heart); +} +``` + +```css hidden live-sample___svg1 +:has(:checked) .applied-mask { + mask-mode: alpha; +} +body { + flex-flow: row wrap; +} +``` + +```html hidden live-sample___svg1 +<label><input type="checkbox" /><code>mask-mode: alpha;</code></label> +``` + +Because the image source is a `<mask>`, and the mask has neither the `mask-type` CSS property nor the `mask-type` SVG attribute set, the `mask-type` defaults to `alpha`, so the default of `mask-mode: match-source` resolves to `luminance`. This is because, for mask sources that are SVG {{svgelement("mask")}} elements, the `mask-type` defaults to `luminance` unless the {{svgattr("mask-type")}} attribute is explicitly set to `alpha`. + +{{EmbedLiveSample("svg1", "", "300px")}} + +As we haven't set the `mask-type` attribute or CSS property on our mask, the `mask-mode` property default of `match-source` resolves to `luminance`. Toggle the checkbox to set the `mask-mode` value to `alpha` or allow it to default to `match-source`. + +This example also demonstrated the difference between masking and clipping in CSS. You'll note that luminance and alpha-transparency are relevant to masking but not to clipping. Masking can be used to control the opacity of an element, while clipping shows everything inside the clipping path and fully hides the parts of the element outside the clip path. Clipped areas are completely invisible, whereas masked areas can be partially or fully visible. + +If all you need are shapes, clipping may suffice. But if you need fading, variable opacity, or even control of position and size (which we'll discuss in a separate guide), masking is more suitable. + +## See also + +- [Introduction to CSS clipping](/en-US/docs/Web/CSS/CSS_masking/Clipping) +- [CSS masking](/en-US/docs/Web/CSS/CSS_masking) module diff --git a/files/en-us/web/css/css_media_queries/index.md b/files/en-us/web/css/css_media_queries/index.md index b085c70a23ff34b..6ed48a4908feb37 100644 --- a/files/en-us/web/css/css_media_queries/index.md +++ b/files/en-us/web/css/css_media_queries/index.md @@ -102,7 +102,7 @@ When designing reusable HTML components, you may also use [container queries](/e - : Tips and techniques for helping improve web content printer output. -- [Responsive images](/en-US/docs/Web/HTML/Responsive_images) +- [Responsive images](/en-US/docs/Web/HTML/Guides/Responsive_images) - : Learn how to use media queries with `sizes` to implement responsive image solutions on websites. @@ -128,10 +128,10 @@ When designing reusable HTML components, you may also use [container queries](/e - [Device Posture API](/en-US/docs/Web/API/Device_Posture_API) - {{cssxref("@media/device-posture", "device-posture")}} descriptor - HTML - - `sizes` attribute for [`<img>`](/en-US/docs/Web/HTML/Element/img#sizes), [`<link>`](/en-US/docs/Web/HTML/Element/link#sizes), and [`<source>`](/en-US/docs/Web/HTML/Element/source#sizes) for {{HTMLElement("picture")}} - - `media` attribute for [`<link>`](/en-US/docs/Web/HTML/Element/link#media), [`<source>`](/en-US/docs/Web/HTML/Element/source#media), and [`<style>`](/en-US/docs/Web/HTML/Element/style#media) [HTML](/en-US/docs/Web/HTML) - - [Viewport `<meta>` tag](/en-US/docs/Web/HTML/Viewport_meta_tag) -- SVG [`media`](/en-US/docs/Web/SVG/Attribute/media) attribute + - `sizes` attribute for [`<img>`](/en-US/docs/Web/HTML/Reference/Elements/img#sizes), [`<link>`](/en-US/docs/Web/HTML/Reference/Elements/link#sizes), and [`<source>`](/en-US/docs/Web/HTML/Reference/Elements/source#sizes) for {{HTMLElement("picture")}} + - `media` attribute for [`<link>`](/en-US/docs/Web/HTML/Reference/Elements/link#media), [`<source>`](/en-US/docs/Web/HTML/Reference/Elements/source#media), and [`<style>`](/en-US/docs/Web/HTML/Reference/Elements/style#media) [HTML](/en-US/docs/Web/HTML) + - [Viewport `<meta>` tag](/en-US/docs/Web/HTML/Guides/Viewport_meta_element) +- SVG [`media`](/en-US/docs/Web/SVG/Reference/Attribute/media) attribute ## Specifications @@ -140,6 +140,6 @@ When designing reusable HTML components, you may also use [container queries](/e ## See also - [Container queries](/en-US/docs/Web/CSS/CSS_containment/Container_queries) -- [Using the `srcset` and `sizes` attributes](/en-US/docs/Web/HTML/Element/img#using_the_srcset_and_sizes_attributes) +- [Using the `srcset` and `sizes` attributes](/en-US/docs/Web/HTML/Reference/Elements/img#using_the_srcset_and_sizes_attributes) - [CSS paged media](/en-US/docs/Web/CSS/CSS_paged_media) - Use {{cssxref("@supports")}} to apply styles that depend on browser support for various CSS technologies. diff --git a/files/en-us/web/css/css_media_queries/testing_media_queries/index.md b/files/en-us/web/css/css_media_queries/testing_media_queries/index.md index b3544cc4b96e378..27cf3b87e9278e3 100644 --- a/files/en-us/web/css/css_media_queries/testing_media_queries/index.md +++ b/files/en-us/web/css/css_media_queries/testing_media_queries/index.md @@ -75,6 +75,10 @@ To stop receiving notifications about changes to the value of your media query, mediaQueryList.removeEventListener("change", handleOrientationChange); ``` +## Specifications + +{{Specifications}} + ## Browser compatibility {{Compat}} diff --git a/files/en-us/web/css/css_media_queries/using_media_queries/index.md b/files/en-us/web/css/css_media_queries/using_media_queries/index.md index 706ca6a350e58fd..9ba6c413edcea87 100644 --- a/files/en-us/web/css/css_media_queries/using_media_queries/index.md +++ b/files/en-us/web/css/css_media_queries/using_media_queries/index.md @@ -246,7 +246,7 @@ The `not` keyword inverts the meaning of a single media query. For example, the } ``` -The `not` negates only the media query it is applied to. The `not`, without parenthesis, negates all the features within the media query in which it is contained. This means, in a comma-separated list of media queries, each `not` applies to the single query it is contained within, applying to _all_ the features within that single query. In this example, the `not` applies to the first media query, which concludes at the first comma: +The `not` negates only the media query it is applied to. The `not`, without parenthesis, negates all the features within the media query in which it is contained. This means, in a comma-separated list of media queries, each `not` applies to the single query it is contained within, applying to _all_ the features within that single query. In this example, the `not` applies to the first media query `screen and (color)`, which concludes at the first comma: ```css @media not screen and (color), print and (color) { @@ -254,53 +254,31 @@ The `not` negates only the media query it is applied to. The `not`, without pare } ``` -The above query is evaluated like this: +Because the query starts with a media type `screen`, you _cannot_ wrap `screen and (color)` with parentheses. On the other hand, if your media query consists of features only, then you _must_ parenthesize the query: ```css -@media (not (screen and (color))), print and (color) { +@media not ((width > 1000px) and (color)), print and (color) { /* … */ } ``` -Both examples are valid. Media conditions can be grouped by wrapping them in parentheses (`()`). These groups can then be nested within a condition the same as a single media query. - -The `not` is evaluated last in a media query, meaning it applies to the entire media query, not to a single feature within a query, as if an open parenthesis was added immediately after the `not` and closed at the end of the media query. - -The following query: - -```css -@media not all and (monochrome) { - /* … */ -} -``` - -is evaluated like this: +Parentheses limit the components of the query that get negated. For example, to negate the `(width > 1000px)` query only: ```css -@media not (all and (monochrome)) { +@media (not (width > 1000px)) and (color), print and (color) { /* … */ } ``` -It is not evaluated like this: - -```css example-bad -@media (not all) and (monochrome) { - /* … */ -} -``` - -To negate a single feature within a media query, use parenthesis. Encompassing a `not` and a media feature in parentheses limits the components of the query that get negated. - -In this example, we negate the `hover` media feature but not the `all` media type: +`not` only negates the query to its right. In this example, we negate the `hover` media feature but not the `screen` media type: ```css -@media all and (not(hover)) { +@media screen and not (hover) { /* … */ } ``` -The `not(hover)` matches if the device has no hover capability. In this case, because of the parentheses, the `not` applies to `hover` but not to `all`. +The `not (hover)` matches if the device has no hover capability. In this case, because of its ordering, the `not` applies to `hover` but not to `screen`. ### Improving compatibility with older browsers diff --git a/files/en-us/web/css/css_media_queries/using_media_queries_for_accessibility/index.md b/files/en-us/web/css/css_media_queries/using_media_queries_for_accessibility/index.md index 417bea65356c9f3..1bd118b5b2590cc 100644 --- a/files/en-us/web/css/css_media_queries/using_media_queries_for_accessibility/index.md +++ b/files/en-us/web/css/css_media_queries/using_media_queries_for_accessibility/index.md @@ -21,7 +21,7 @@ The [`prefers-reduced-motion`](/en-US/docs/Web/CSS/@media/prefers-reduced-motion ### Example -This example has an annoying animation unless you turn on Reduce Motion in [your accessibility preferences](/en-US/docs/Web/Accessibility/Accessibility:_What_users_can_to_to_browse_safely). +This example has an annoying animation unless you turn on Reduce Motion in [your accessibility preferences](/en-US/docs/Web/Accessibility/Guides/Browsing_safely). #### HTML diff --git a/files/en-us/web/css/css_motion_path/index.md b/files/en-us/web/css/css_motion_path/index.md index bce235cbc984cf0..c6aa7dd41da4ea5 100644 --- a/files/en-us/web/css/css_motion_path/index.md +++ b/files/en-us/web/css/css_motion_path/index.md @@ -2,7 +2,7 @@ title: CSS motion path slug: Web/CSS/CSS_motion_path page-type: css-module -browser-compat: css.properties.offset-path +spec-urls: https://drafts.fxtf.org/motion/ --- {{CSSRef}} @@ -56,7 +56,3 @@ The idea is that when you want to animate an element moving along a path, you pr ## Specifications {{Specifications}} - -## Browser compatibility - -{{Compat}} diff --git a/files/en-us/web/css/css_multicol_layout/index.md b/files/en-us/web/css/css_multicol_layout/index.md index 3be2c0e90c2aa15..9dcd7641d5184f4 100644 --- a/files/en-us/web/css/css_multicol_layout/index.md +++ b/files/en-us/web/css/css_multicol_layout/index.md @@ -2,7 +2,9 @@ title: CSS multi-column layout slug: Web/CSS/CSS_multicol_layout page-type: css-module -spec-urls: https://drafts.csswg.org/css-multicol/ +spec-urls: + - https://drafts.csswg.org/css-multicol/ + - https://drafts.csswg.org/css-multicol-2/ --- {{CSSRef}} @@ -286,7 +288,11 @@ blockquote p::after { - {{cssxref("column-width")}} > [!NOTE] -> Bear in mind that setting container height and line length can pose challenges for people with visual or cognitive disabilities. [WCAG Success Criterion 1.4.8](/en-US/docs/Web/Accessibility/Understanding_WCAG/Perceivable#guideline_1.4_make_it_easier_for_users_to_see_and_hear_content_including_separating_foreground_from_background) states that even when the text size is doubled, content should not need to be scrolled. +> Bear in mind that setting container height and line length can pose challenges for people with visual or cognitive disabilities. [WCAG Success Criterion 1.4.8](/en-US/docs/Web/Accessibility/Guides/Understanding_WCAG/Perceivable#guideline_1.4_make_it_easier_for_users_to_see_and_hear_content_including_separating_foreground_from_background) states that even when the text size is doubled, content should not need to be scrolled. + +## Selectors and pseudo-elements + +- {{cssxref("::column")}} ## Guides diff --git a/files/en-us/web/css/css_namespaces/index.md b/files/en-us/web/css/css_namespaces/index.md index 695dac64ef76754..b65fad2d6c59c53 100644 --- a/files/en-us/web/css/css_namespaces/index.md +++ b/files/en-us/web/css/css_namespaces/index.md @@ -2,7 +2,7 @@ title: CSS namespaces slug: Web/CSS/CSS_namespaces page-type: css-module -browser-compat: css.at-rules.namespace +spec-urls: https://drafts.csswg.org/css-namespaces/ --- {{CSSRef}} @@ -23,7 +23,7 @@ The `@namespace` rule is used for declaring a default namespace and for binding ## Guides -- [Namespaces crash course](/en-US/docs/Web/SVG/Namespaces_Crash_Course) +- [Namespaces crash course](/en-US/docs/Web/SVG/Guides/Namespaces_crash_course) - : Deep dive into what a namespace is and how they are used in XML and XML-based markup languages. @@ -55,13 +55,9 @@ The `@namespace` rule is used for declaring a default namespace and for binding {{Specifications}} -## Browser compatibility - -{{Compat}} - ## See also -- [`<a>`](/en-US/docs/Web/SVG/Element/a#example) SVG element +- [`<a>`](/en-US/docs/Web/SVG/Reference/Element/a#example) SVG element - [CSS `<url>` type](/en-US/docs/Web/CSS/url_value) - [CSS at-rules](/en-US/docs/Web/CSS/CSS_syntax/At-rule) - [CSS at-rule functions](/en-US/docs/Web/CSS/CSS_syntax/At-rule_functions) diff --git a/files/en-us/web/css/css_nesting/nesting_and_specificity/index.md b/files/en-us/web/css/css_nesting/nesting_and_specificity/index.md index e3320253bc38836..cedd55dc53e3146 100644 --- a/files/en-us/web/css/css_nesting/nesting_and_specificity/index.md +++ b/files/en-us/web/css/css_nesting/nesting_and_specificity/index.md @@ -10,7 +10,7 @@ The [specificity](/en-US/docs/Web/CSS/CSS_cascade/Specificity) of the `&` nestin ```html <b class="foo"> - <c>Blue text</c> + <i>Blue text</i> </b> ``` @@ -18,12 +18,12 @@ The [specificity](/en-US/docs/Web/CSS/CSS_cascade/Specificity) of the `&` nestin ```css-nolint #a, b { - & c { + & i { color: blue; } } -.foo c { +.foo i { color: red; } ``` @@ -32,19 +32,19 @@ The [specificity](/en-US/docs/Web/CSS/CSS_cascade/Specificity) of the `&` nestin ```css :is(#a, b) { - & c { + & i { color: blue; } } -.foo c { +.foo i { color: red; } ``` In this example, the id selector (`#a`) has a specificity of [`1-0-0`](/en-US/docs/Web/CSS/CSS_cascade/Specificity#selector_weight_categories), while the type selector (`b`) has a specificity of `0-0-1`. The [`&` nesting selector](/en-US/docs/Web/CSS/Nesting_selector) and `:is()` pseudo-class both take a specificity of `1-0-0`, even though the `#a` id selector is never used. -The `.foo` class selector has a specificity of `0-1-0`. This makes the total specificity `1-0-1` for `& c` and `0-1-1` for `.foo c`, meaning that `color: blue;` wins out. +The `.foo` class selector has a specificity of `0-1-0`. This makes the total specificity `1-0-1` for `& i` and `0-1-1` for `.foo i`, meaning that `color: blue;` wins out. ## See also diff --git a/files/en-us/web/css/css_nesting/nesting_at-rules/index.md b/files/en-us/web/css/css_nesting/nesting_at-rules/index.md index edbad4f3de8628a..713715237a7bfe5 100644 --- a/files/en-us/web/css/css_nesting/nesting_at-rules/index.md +++ b/files/en-us/web/css/css_nesting/nesting_at-rules/index.md @@ -15,6 +15,7 @@ Any [at-rule](/en-US/docs/Web/CSS/CSS_syntax/At-rule) whose body contains style - {{cssxref('@layer')}} - {{cssxref('@scope')}} - {{cssxref('@container')}} +- {{cssxref('@starting-style')}} ## Examples diff --git a/files/en-us/web/css/css_nesting/using_css_nesting/index.md b/files/en-us/web/css/css_nesting/using_css_nesting/index.md index bd47a60e756a7f4..5f40a709195e834 100644 --- a/files/en-us/web/css/css_nesting/using_css_nesting/index.md +++ b/files/en-us/web/css/css_nesting/using_css_nesting/index.md @@ -392,7 +392,7 @@ With the following CSS: ```css .foo { background-color: silver; - @media (screen) { + @media screen { color: tomato; } color: black; @@ -403,7 +403,7 @@ The `background-color` is parsed first and set to silver, then the `@media` rule The CSSOM parses the CSS in the following way: -```txt +```plain ↳ CSSStyleRule .style - background-color: silver diff --git a/files/en-us/web/css/css_overflow/css_carousels/carousel.drawio b/files/en-us/web/css/css_overflow/css_carousels/carousel.drawio new file mode 100644 index 000000000000000..a7e122ca7814398 --- /dev/null +++ b/files/en-us/web/css/css_overflow/css_carousels/carousel.drawio @@ -0,0 +1,55 @@ +<mxfile host="app.diagrams.net" agent="Mozilla/5.0 (Macintosh; Intel Mac OS X 10.15; rv:137.0) Gecko/20100101 Firefox/137.0" version="24.7.7"> + <diagram name="Page-1" id="nMK7wGiNTNxS1q2FWcUp"> + <mxGraphModel dx="1314" dy="680" grid="1" gridSize="10" guides="1" tooltips="1" connect="1" arrows="1" fold="1" page="1" pageScale="1" pageWidth="3300" pageHeight="4681" math="0" shadow="0"> + <root> + <mxCell id="0" /> + <mxCell id="1" parent="0" /> + <mxCell id="sJuday59ZZZzxu0nJ7RU-22" value="" style="rounded=0;whiteSpace=wrap;html=1;strokeColor=none;" vertex="1" parent="1"> + <mxGeometry x="240" y="60" width="870" height="410" as="geometry" /> + </mxCell> + <mxCell id="sJuday59ZZZzxu0nJ7RU-1" value="" style="rounded=1;whiteSpace=wrap;html=1;" vertex="1" parent="1"> + <mxGeometry x="380" y="150" width="580" height="230" as="geometry" /> + </mxCell> + <mxCell id="sJuday59ZZZzxu0nJ7RU-2" value="" style="ellipse;whiteSpace=wrap;html=1;aspect=fixed;" vertex="1" parent="1"> + <mxGeometry x="350" y="237.5" width="55" height="55" as="geometry" /> + </mxCell> + <mxCell id="sJuday59ZZZzxu0nJ7RU-3" value="" style="html=1;shadow=0;dashed=0;align=center;verticalAlign=middle;shape=mxgraph.arrows2.arrow;dy=0.6;dx=40;flipH=1;notch=0;" vertex="1" parent="1"> + <mxGeometry x="361" y="252.5" width="25" height="25" as="geometry" /> + </mxCell> + <mxCell id="sJuday59ZZZzxu0nJ7RU-4" value="" style="ellipse;whiteSpace=wrap;html=1;aspect=fixed;movable=1;resizable=1;rotatable=1;deletable=1;editable=1;locked=0;connectable=1;" vertex="1" parent="1"> + <mxGeometry x="932" y="237.5" width="55" height="55" as="geometry" /> + </mxCell> + <mxCell id="sJuday59ZZZzxu0nJ7RU-5" value="" style="html=1;shadow=0;dashed=0;align=center;verticalAlign=middle;shape=mxgraph.arrows2.arrow;dy=0.6;dx=40;flipH=1;notch=0;movable=1;resizable=1;rotatable=1;deletable=1;editable=1;locked=0;connectable=1;direction=west;" vertex="1" parent="1"> + <mxGeometry x="950" y="252.5" width="25" height="25" as="geometry" /> + </mxCell> + <mxCell id="sJuday59ZZZzxu0nJ7RU-14" value="" style="group" vertex="1" connectable="0" parent="1"> + <mxGeometry x="600" y="390" width="140" height="20" as="geometry" /> + </mxCell> + <mxCell id="sJuday59ZZZzxu0nJ7RU-6" value="" style="ellipse;whiteSpace=wrap;html=1;aspect=fixed;fillColor=#000000;" vertex="1" parent="sJuday59ZZZzxu0nJ7RU-14"> + <mxGeometry width="20" height="20" as="geometry" /> + </mxCell> + <mxCell id="sJuday59ZZZzxu0nJ7RU-7" value="" style="ellipse;whiteSpace=wrap;html=1;aspect=fixed;" vertex="1" parent="sJuday59ZZZzxu0nJ7RU-14"> + <mxGeometry x="40" width="20" height="20" as="geometry" /> + </mxCell> + <mxCell id="sJuday59ZZZzxu0nJ7RU-8" value="" style="ellipse;whiteSpace=wrap;html=1;aspect=fixed;" vertex="1" parent="sJuday59ZZZzxu0nJ7RU-14"> + <mxGeometry x="80" width="20" height="20" as="geometry" /> + </mxCell> + <mxCell id="sJuday59ZZZzxu0nJ7RU-9" value="" style="ellipse;whiteSpace=wrap;html=1;aspect=fixed;" vertex="1" parent="sJuday59ZZZzxu0nJ7RU-14"> + <mxGeometry x="120" width="20" height="20" as="geometry" /> + </mxCell> + <mxCell id="sJuday59ZZZzxu0nJ7RU-17" value="&lt;font style=&quot;font-size: 20px;&quot;&gt;Content area&lt;/font&gt;" style="text;html=1;align=center;verticalAlign=middle;whiteSpace=wrap;rounded=0;" vertex="1" parent="1"> + <mxGeometry x="610" y="262.5" width="120" height="30" as="geometry" /> + </mxCell> + <mxCell id="sJuday59ZZZzxu0nJ7RU-18" value="&lt;font style=&quot;font-size: 20px;&quot;&gt;&quot;Prev&quot; button&lt;/font&gt;" style="text;html=1;align=center;verticalAlign=middle;whiteSpace=wrap;rounded=0;" vertex="1" parent="1"> + <mxGeometry x="260" y="250" width="100" height="30" as="geometry" /> + </mxCell> + <mxCell id="sJuday59ZZZzxu0nJ7RU-19" value="&lt;font style=&quot;font-size: 20px;&quot;&gt;&quot;Next&quot; button&lt;/font&gt;" style="text;html=1;align=center;verticalAlign=middle;whiteSpace=wrap;rounded=0;" vertex="1" parent="1"> + <mxGeometry x="975" y="250" width="100" height="30" as="geometry" /> + </mxCell> + <mxCell id="sJuday59ZZZzxu0nJ7RU-20" value="&lt;font style=&quot;font-size: 20px;&quot;&gt;Scroll markers&lt;/font&gt;" style="text;html=1;align=center;verticalAlign=middle;whiteSpace=wrap;rounded=0;" vertex="1" parent="1"> + <mxGeometry x="595" y="420" width="150" height="30" as="geometry" /> + </mxCell> + </root> + </mxGraphModel> + </diagram> +</mxfile> diff --git a/files/en-us/web/css/css_overflow/css_carousels/carousel.png b/files/en-us/web/css/css_overflow/css_carousels/carousel.png new file mode 100644 index 000000000000000..08d4db8756ccd06 Binary files /dev/null and b/files/en-us/web/css/css_overflow/css_carousels/carousel.png differ diff --git a/files/en-us/web/css/css_overflow/css_carousels/index.md b/files/en-us/web/css/css_overflow/css_carousels/index.md new file mode 100644 index 000000000000000..2f1dca99ae66fd1 --- /dev/null +++ b/files/en-us/web/css/css_overflow/css_carousels/index.md @@ -0,0 +1,552 @@ +--- +title: Creating CSS carousels +slug: Web/CSS/CSS_overflow/CSS_carousels +page-type: guide +--- + +{{CSSRef}} + +The [CSS overflow](/en-US/docs/Web/CSS/CSS_overflow) module defines features enabling the creation of flexible and accessible pure-CSS carousels with browser-generated and developer-styled scroll buttons and scroll markers. This guide explains how to create a carousel using these features. + +## Carousel concepts + +**Carousels** are a common feature on the web. They typically take the form of a scrolling content area containing several items, such as presentation slides, ads, headline news stories, or key product features. + +Users can move through the items by clicking or activating navigational buttons or by swiping. The navigation usually includes: + +- **scroll buttons** + - : Generally "previous" and "next" buttons or links. +- **scroll markers** + - : A series of button or link icons, each representing one or more items depending on how many items are shown at each scroll position within the carousel. + +![A carousel with a content area in the middle, previous and next buttons to the left and right, and scroll markers at the bottom](carousel.png) + +A key feature of carousels is **pagination** — the items feel like separate pieces of content that are moved between rather than forming one continuous section of content. You might show one item at a time or several items on each carousel "page". When several items are visible, you might show an entirely new group of items each time the "next" or "previous" button is pressed. Alternatively, you could add a single new item to one end of the list while moving the item at the other end out of view. + +Creating carousels with JavaScript can be quite brittle and challenging to implement. They require scripts to associate scroll markers with the items they represent while continuously updating the scroll buttons to keep them operating correctly. When carousels are created using JavaScript, the accessibility of the carousel and the associated controls has to be added in. + +Fortunately, we can create accessible carousels with associated controls without the use of JavaScript, using CSS carousel features. + +## CSS carousel features + +The CSS carousel features provide pseudo-elements and pseudo-classes that enable the creation of carousels using only CSS and HTML, with the browser handling most of the scrolling and link references in an accessible, flexible, and consistent manner. These features are as follows: + +- {{cssxref("::scroll-button()")}} + - : Generated inside a {{glossary("scroll container")}}, these pseudo-elements represent scroll buttons, which scroll the container in a specified direction. +- {{cssxref("::scroll-marker-group")}} + - : Generated inside a scroll container; used to collect together and lay out scroll markers. +- {{cssxref("::scroll-marker")}} + - : Generated inside the children of a scroll container ancestor or within a scroll container's columns, to represent their scroll markers. These can be selected to scroll the container to their associated child elements or column, and are collected inside the scroll container's {{cssxref("::scroll-marker-group")}} for layout purposes. +- {{cssxref(":target-current")}} + - : This pseudo-class can be used to select the currently-active scroll marker. It can be used to provide a highlight style to the currently active marker, which is important for usability and accessibility. +- {{cssxref("::column")}} + - : This pseudo-element represents the individual columns generated when a container is set to display its content in multiple columns via [CSS multi-column layout](/en-US/docs/Web/CSS/CSS_multicol_layout). It can be used in conjunction with {{cssxref("::scroll-marker")}} to generate a scroll marker for each column. + +## Carousel with single pages + +Our first demo is a carousel of single pages, with each item taking up the full page. We have [scroll markers](#creating_scroll_markers) as bottom navigation and [scroll buttons](#creating_scroll_buttons) on the sides of the page, enabling the user to move to the next and previous pages. + +We'll use [flexbox](#carousel_layout_with_flexbox) to lay out the carousel, [scroll snapping](#setting_up_scroll_snapping_on_the_list) to enforce clear pagination, and anchor positioning to [position the scroll buttons](#positioning_scroll_buttons) and scroll markers relative to the carousel. + +The HTML consists of a [heading element](/en-US/docs/Web/HTML/Reference/Elements/Heading_Elements) and an [unordered list](/en-US/docs/Web/HTML/Reference/Elements/ul), with each [list item](/en-US/docs/Web/HTML/Reference/Elements/li) containing some sample content: + +```html live-sample___first-example live-sample___first-example-step1 live-sample___first-example-step2 +<h1>CSS carousel single item per page</h1> +<ul> + <li> + <h2>Page 1</h2> + </li> + <li> + <h2>Page 2</h2> + </li> + <li> + <h2>Page 3</h2> + </li> + <li> + <h2>Page 4</h2> + </li> +</ul> +``` + +### Carousel layout with flexbox + +We use [flexbox](/en-US/docs/Web/CSS/CSS_flexible_box_layout) to create a single row of items; the `<ul>` is the flex container, and the `<li>` child list items are displayed horizontally with each item taking up the full width of the carousel. + +The unordered list is made to fill the full width of the viewport with a width {{cssxref("width")}} of `100vw`; it is also given a {{cssxref("height")}} of `300px`, and some {{cssxref("padding")}}. We then use flexbox to lay out the list — setting a {{cssxref("display")}} value of `flex` to cause the child list items to display in a row (due to the default {{cssxref("flex-direction")}} value of `row`), with a {{cssxref("gap")}} of `4vw` between each one. + +```css hidden live-sample___first-example live-sample___first-example-step1 live-sample___first-example-step2 +* { + box-sizing: border-box; +} + +body { + margin: 0; + font-family: Arial, Helvetica, sans-serif; +} + +h1 { + text-align: center; + font-size: 1.7rem; +} +``` + +```css live-sample___first-example live-sample___first-example-step1 live-sample___first-example-step2 +ul { + width: 100vw; + height: 300px; + padding: 20px; + display: flex; + gap: 4vw; +} +``` + +Now it's time to style the list items. The first declarations provide rudimentary styling. The important declaration is the {{cssxref("flex")}} value of `0 0 100%`, which forces each item to be as wide as the container (the `<ul>`). As a result, the content will overflow its container, and the viewport will scroll horizontally. + +```css live-sample___first-example live-sample___first-example-step1 live-sample___first-example-step2 +li { + list-style-type: none; + background-color: #eee; + border: 1px solid #ddd; + padding: 20px; + + flex: 0 0 100%; +} + +li:nth-child(even) { + background-color: cyan; +} +``` + +In addition, every even-numbered list item is given a different background-color via {{cssxref(":nth-child()")}}, so that it is easier to see the scrolling effect. + +### Setting up scroll snapping on the list + +In this section, we will set an overflow value on the `<ul>` to turn it into a {{glossary("scroll container")}}, then apply [CSS scroll snapping](/en-US/docs/Web/CSS/CSS_scroll_snap) to cause the list to snap to the center of each list item as the content is scrolled. + +An {{cssxref("overflow-x")}} value of `scroll` is set on the `<ul>` so that its content will scroll horizontally within the list, rather than the entire viewport scrolling. [CSS scroll snap](/en-US/docs/Web/CSS/CSS_scroll_snap) is then used to snap to each "page" — a {{cssxref("scroll-snap-type")}} value of `x mandatory` is set to make the list into a [scroll snap container](/en-US/docs/Glossary/Scroll_snap#scroll_snap_container). The `x` keyword causes the container's [snap targets](/en-US/docs/Glossary/Scroll_snap#snap_target) to be snapped to horizontally, while the `mandatory` keyword means that the container will always snap to a snap target at the end of a scrolling action. + +```css live-sample___first-example live-sample___first-example-step1 live-sample___first-example-step2 +ul { + overflow-x: scroll; + scroll-snap-type: x mandatory; +} +``` + +Next, a {{cssxref("scroll-snap-align")}} value of `center` is set on the list items so that, when the list is scrolled, it snaps to the center of each list item. + +```css live-sample___first-example live-sample___first-example-step1 live-sample___first-example-step2 +li { + scroll-snap-align: center; +} +``` + +The code shown so far renders as follows: + +{{EmbedLiveSample("first-example-step1", "100%", "400px")}} + +Try scrolling the list by swiping or using the scrollbar to see the scroll snapping effect. No matter where you end your scroll motion, an item will always "snap" into place. + +> [!NOTE] +> CSS scroll snapping is not mandatory to use the CSS carousel features. However, carousels work a lot better with scroll snapping included. Without scroll snapping, the scroll buttons and markers will be unlikely to navigate cleanly between pages, and the result will be substandard. + +### Creating scroll buttons + +In this section we add "previous" and "next" scroll buttons to the demo to provide a tool to navigate between carousel pages. This is achieved using the {{cssxref("::scroll-button()")}} pseudo-element. + +The `::scroll-button()` pseudo-elements generate buttons inside a scroll container only when their {{cssxref("content")}} properties are set to a value other than `none`. Each `::scroll-button()` represents a scroll button, the scrolling direction of which is specified by the selector's argument. You can generate up to four scroll buttons per scroll container, each scrolling the container's content towards the start or end of the block or inline axis. + +You can also specify an argument of `*` to target all of the `::scroll-button()` pseudo-elements with styles. + +First, all scroll buttons are targeted with some rudimentary styles, as well as styling based on different states. It is important to set {{cssxref(":focus")}} styles for keyboard users. Also, as scroll buttons are automatically set to [`disabled`](/en-US/docs/Web/HTML/Reference/Attributes/disabled) when no more scrolling can occur in that direction, we use the {{cssxref(":disabled")}} pseudo-class to target this state. + +```css live-sample___first-example live-sample___first-example-step2 +ul::scroll-button(*) { + border: 0; + font-size: 2rem; + background: none; + color: rgb(0 0 0 / 0.7); + cursor: pointer; +} + +ul::scroll-button(*):hover, +ul::scroll-button(*):focus { + color: rgb(0 0 0 / 1); +} + +ul::scroll-button(*):active { + translate: 1px 1px; +} + +ul::scroll-button(*):disabled { + color: rgb(0 0 0 / 0.2); + cursor: unset; +} +``` + +> [!NOTE] +> We also set a {{cssxref("cursor")}} value of `pointer` on the scroll buttons to make it more obvious that they can be interacted with (an improvement for both general [UX](/en-US/docs/Glossary/UX) and [cognitive accessibility](/en-US/docs/Web/Accessibility/Guides/Cognitive_accessibility)), unsetting it when the scroll buttons are `:disabled`. + +Next, an appropriate icon is set on the left and right scroll buttons via the `content` property, which is also what causes the scroll buttons to be generated: + +```css live-sample___first-example live-sample___first-example-step2 +ul::scroll-button(left) { + content: "◄"; +} + +ul::scroll-button(right) { + content: "►"; +} +``` + +> [!NOTE] +> The scroll buttons are automatically given an appropriate accessible name, so they are announced appropriately by assistive technologies. For example, the above buttons have an implicit [`role`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles) of `button` and their {{glossary("accessible name", "accessible names")}} are "scroll left" and "scroll right", respectively. + +### Positioning scroll buttons + +We've created the scroll buttons. Now we will position them relative to the carousel using [CSS anchor positioning](/en-US/docs/Web/CSS/CSS_anchor_positioning). + +First of all, a reference {{cssxref("anchor-name")}} is set on the list. Next, each scroll button has its {{cssxref("position")}} set to `absolute`, and its {{cssxref("position-anchor")}} property set to the same reference name defined on the list, to associate the two together. + +```css live-sample___first-example live-sample___first-example-step2 +ul { + anchor-name: --myCarousel; +} + +ul::scroll-button(*) { + position: absolute; + position-anchor: --myCarousel; +} +``` + +To actually position each scroll button, we set values on their {{glossary("inset properties")}}. We use {{cssxref("anchor()")}} functions to position the specified sides of the buttons relative to the sides of the carousel. In each case, the {{cssxref("calc()")}} function is used to add some space between the button edge and the carousel edge. For example, the right-hand edge of the left scroll button is positioned 70 pixels to the right of the carousel's left-hand edge. + +```css live-sample___first-example live-sample___first-example-step2 +ul::scroll-button(left) { + right: calc(anchor(left) - 70px); + bottom: calc(anchor(top) + 13px); +} + +ul::scroll-button(right) { + left: calc(anchor(right) - 70px); + bottom: calc(anchor(top) + 13px); +} +``` + +Adding in the scroll button code, we get the following result: + +{{EmbedLiveSample("first-example-step2", "100%", "400px")}} + +Try pressing the "previous" and "next" scroll buttons to see how the pages are scrolled, respecting the scroll-snapping behavior. Also note how the "previous" button is automatically disabled when the list is scrolled to the start of the content, while the "next" button is automatically disabled when the list is scrolled to the end of the content. + +### Creating scroll markers + +Scroll markers are a group of buttons, each one of which scrolls the carousel to a position related to one of the content pages. They provide an additional navigation tool that also indicates your progress through the carousel pages. + +In this section, we will add scroll markers to the carousel, which involves three main features: + +- The {{cssxref("scroll-marker-group")}} property is set on the scroll container element. It needs to be set to a non-`none` value for the {{cssxref("::scroll-marker-group")}} pseudo-element to be generated; its value specifies where the scroll marker group appears in the carousel's tab order and layout box order (but not DOM structure) — `before` puts it at the start, before the scroll buttons, while `after` puts it at the end. +- The {{cssxref("::scroll-marker-group")}} pseudo-element exists inside a scroll container, and is used to collect together and lay out scroll markers. +- {{cssxref("::scroll-marker")}} pseudo-elements exist inside the children and {{cssxref("::column")}} fragments of a scroll container ancestor, and represent their scroll markers. These are collected inside the ancestor's {{cssxref("::scroll-marker-group")}} for layout purposes. + +To begin with, the list's `scroll-marker-group` property is set to `after`, so the `::scroll-marker-group` pseudo-element is placed after the list's DOM content in the focus and layout box order; this means it comes after the scroll buttons: + +```css live-sample___first-example +ul { + scroll-marker-group: after; +} +``` + +Next, the list's `::scroll-marker-group` pseudo-element is positioned relative to the carousel using CSS anchor positioning, similar to the scroll button's, except that it is horizontally centered on the carousel using a {{cssxref("justify-self")}} value of `anchor-center`. The group is laid out using flexbox, with a {{cssxref("justify-content")}} value of of `center` and a {{cssxref("gap")}} of `20px` so that its children (the `::scroll-marker` pseudo-elements) are centered inside the `::scroll-marker-group` with a gap between each one. + +```css live-sample___first-example +ul::scroll-marker-group { + position: absolute; + position-anchor: --myCarousel; + top: calc(anchor(bottom) - 70px); + justify-self: anchor-center; + + display: flex; + justify-content: center; + gap: 20px; +} +``` + +Next, we handle the look and feel of the scroll markers themselves; they can be styled just like any other [generated content](/en-US/docs/Web/CSS/CSS_generated_content). It is important to note that we need to set a non-`none` value for the `content` property so the scroll markers are actually generated. We also set some rudimentary styles to make the markers appear as outlined circles: + +```css live-sample___first-example +li::scroll-marker { + content: ""; + width: 16px; + height: 16px; + background-color: transparent; + border: 2px solid black; + border-radius: 50%; +} +``` + +> [!NOTE] +> Generated content is inline by default; we can apply `width` and `height` to our scroll markers because they are being laid out as flex items. + +Finally for this section, the {{cssxref(":target-current")}} pseudo-class is used to select whichever scroll marker corresponds to the currently visible "page", highlighting how far the user has scrolled through the content. In this case, we set the `background-color` to `black` so it is styled as a filled-in circle. + +```css live-sample___first-example +li::scroll-marker:target-current { + background-color: black; +} +``` + +> [!NOTE] +> Accessibility-wise, the scroll marker group and contained scroll markers are rendered with [`tablist`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/tablist_role)/[`tab`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/tab_role) semantics. When you <kbd>Tab</kbd> to the group with the keyboard, it behaves like a single item (that is, another press of the <kbd>Tab</kbd> key will move past the group to the next item), and you can move between the different scroll markers using the left and right (or up and down) cursor keys. + +## Single page carousel final result + +All of the above code combines together to create the following result: + +{{EmbedLiveSample("first-example", "100%", "400px")}} + +Since the previous live example, the scroll markers have been added — try pressing them to jump straight to each page. Note how the current marker is highlighted so you can see where you are in the pagination. Also try tabbing to the scroll marker group, then use the cursor keys to cycle through each page. + +You can also navigate between pages by swiping left and right, dragging the scroll bar, or pressing the scroll buttons. + +## Responsive carousel: multiple items per page + +The second demo is a carousel with multiple items per page, which again includes [scroll buttons](#creating_scroll_buttons) and [scroll markers](#creating_scroll_markers) for navigating through the pages. This demo is also responsive — different numbers of items appear on each page depending on the viewport width. + +This demo is very similar to the [Carousel with single pages](#carousel_with_single_pages) demo, except that instead of using flexbox for layout, it uses [CSS multi-column layout](/en-US/docs/Web/CSS/CSS_multicol_layout) and the {{cssxref("::column")}} pseudo-element to create arbitrary columns that span the full width of the carousel and may contain multiple items. + +Using this approach, we can be sure that if the viewport grows or shrinks, while the item size remains constant, we'll never have a partial item displayed off the edge of the scrollport. In this case, the scroll markers are created on scroll container fragments, per-column, rather than on children, per-item. + +The HTML is very similar to that of the previous demo, except that there are significantly more list items and, as multiple items will be visible at a time, we are labeling them as items rather than pages: + +```html-nolint +... + <li> + <h2>Item 1</h2> + </li> +... +``` + +This demo also has very similar CSS, with the exception of the rules explained in the following sections. + +```html hidden live-sample___second-example +<h1>CSS carousel multiple items per page</h1> +<ul> + <li> + <h2>Item 1</h2> + </li> + <li> + <h2>Item 2</h2> + </li> + <li> + <h2>Item 3</h2> + </li> + <li> + <h2>Item 4</h2> + </li> + <li> + <h2>Item 5</h2> + </li> + <li> + <h2>Item 6</h2> + </li> + <li> + <h2>Item 7</h2> + </li> + <li> + <h2>Item 8</h2> + </li> + <li> + <h2>Item 9</h2> + </li> + <li> + <h2>Item 10</h2> + </li> + <li> + <h2>Item 11</h2> + </li> + <li> + <h2>Item 12</h2> + </li> + <li> + <h2>Item 13</h2> + </li> + <li> + <h2>Item 14</h2> + </li> + <li> + <h2>Item 15</h2> + </li> +</ul> +``` + +### Carousel layout using columns + +This example uses [CSS multi-column layout](/en-US/docs/Web/CSS/CSS_multicol_layout), rather than flexbox, to layout the carousel items. The {{cssxref("columns")}} value of `1` forces each column to be the full width of the container, with the contents displaying a single column at a time. A {{cssxref("text-align")}} value of `center` is also applied, forcing the contents to align with the center of the list. + +```css hidden live-sample___second-example +* { + box-sizing: border-box; +} + +body { + margin: 0; + font-family: Arial, Helvetica, sans-serif; +} + +h1 { + text-align: center; + font-size: 1.7rem; +} +``` + +```css live-sample___second-example +ul { + width: 100vw; + height: 300px; + padding: 10px; + + overflow-x: scroll; + scroll-snap-type: x mandatory; + + columns: 1; + text-align: center; +} +``` + +We provide rudimentary box styling for the list items, then apply layout styles to allow one or more items to fit into the single content column, depending on the viewport width. The number dynamically changes as the list gets wider or narrower. + +```css live-sample___second-example +li { + list-style-type: none; + + display: inline-block; + height: 100%; + width: 200px; + + background-color: #eee; + border: 1px solid #ddd; + padding: 20px; + margin: 0 10px; + + text-align: left; +} + +li:nth-child(even) { + background-color: cyan; +} +``` + +The key layout properties are as follows: + +- A {{cssxref("display")}} value of `inline-block` has been set to force the list items to sit alongside one another and make the list scroll horizontally. +- An absolute {{cssxref("width")}} of `200px` has been set on them to control their sizing, meaning one or more will fit in a column that grows and shrinks along with the width of the viewport. +- A `text-align` value of `left` is set on them to override the `text-align: center` set on the parent container, so the item content will be left-aligned. + +The {{cssxref("scroll-snap-align")}} property is now set on the {{cssxref("::column")}} pseudo-elements — which represent the content columns generated by the `columns` property — rather than the list items. We want to snap to each complete column rather than every individual list item, showing all new items with each scroll action. + +```css live-sample___second-example +ul::column { + scroll-snap-align: center; +} +``` + +```css hidden live-sample___second-example +ul::scroll-button(*) { + border: 0; + font-size: 2rem; + background: none; + color: rgb(0 0 0 / 0.7); + cursor: pointer; +} + +ul::scroll-button(*):hover, +ul::scroll-button(*):focus { + color: rgb(0 0 0 / 1); +} + +ul::scroll-button(*):active { + translate: 1px 1px; +} + +ul::scroll-button(*):disabled { + color: rgb(0 0 0 / 0.2); + cursor: unset; +} + +ul::scroll-button(left) { + content: "◄"; +} + +ul::scroll-button(right) { + content: "►"; +} + +ul { + anchor-name: --myCarousel; +} + +ul::scroll-button(*) { + position: absolute; + position-anchor: --myCarousel; +} + +ul::scroll-button(left) { + right: calc(anchor(left) - 70px); + bottom: calc(anchor(top) + 13px); +} + +ul::scroll-button(right) { + left: calc(anchor(right) - 70px); + bottom: calc(anchor(top) + 13px); +} + +ul { + scroll-marker-group: after; +} + +ul::scroll-marker-group { + position: absolute; + position-anchor: --myCarousel; + top: calc(anchor(bottom) - 70px); + justify-self: anchor-center; + display: flex; + justify-content: center; + gap: 20px; +} +``` + +### Column scroll markers + +The CSS for creating the scroll markers in this demo is nearly identical to the [previous demo](#creating_scroll_markers), except that the selectors are different — the scroll markers are created on the generated `::column` scroll markers rather than the list items (note how we are including two pseudo-elements here, to generate scroll markers on the generated columns). + +```css live-sample___second-example +ul::column::scroll-marker { + content: ""; + width: 16px; + height: 16px; + background-color: transparent; + border: 2px solid black; + border-radius: 10px; +} + +ul::column::scroll-marker:target-current { + background-color: black; +} +``` + +## Responsive carousel final result + +The Responsive carousel is rendered as follows: + +{{EmbedLiveSample("second-example", "100%", "400px")}} + +Try navigating between the different pages by swiping left and right, using the scroll bar, pressing the scroll buttons, and pressing the scroll markers. The functionality is similar to the single page flexbox example, except that now there are multiple list items in each navigated position; the scroll markers are set on column fragments, potentially containing multiple items, instead of on each item. + +Also, try resizing the screen width and you'll see that the number of list items that can fit inside the list changes — and therefore the number of generated columns changes too. As the number of columns changes, the number of scroll markers dynamically updates so that each column is represented in the scroll marker group. + +## See also + +- [CSS overflow](/en-US/docs/Web/CSS/CSS_overflow) module +- [CSS anchor positioning](/en-US/docs/Web/CSS/CSS_anchor_positioning) module +- [CSS scroll snap](/en-US/docs/Web/CSS/CSS_scroll_snap) module +- [CSS Carousel Gallery](https://chrome.dev/carousel/) via chrome.dev (2025) diff --git a/files/en-us/web/css/css_overflow/index.md b/files/en-us/web/css/css_overflow/index.md index a3037b884323731..1f7796ad9425a0a 100644 --- a/files/en-us/web/css/css_overflow/index.md +++ b/files/en-us/web/css/css_overflow/index.md @@ -5,13 +5,14 @@ page-type: css-module spec-urls: - https://drafts.csswg.org/css-overflow/ - https://drafts.csswg.org/css-overflow-4/ + - https://drafts.csswg.org/css-overflow-5/ --- {{CSSRef}} The **CSS overflow** module properties enable you to handle scrollable overflow in visual media. -Overflow happens when the content in an element box extends past one or more of the box's edges. **Scrollable overflow** is the content that appears outside the element box for which you might want to add a scrolling mechanism. CSS overflow properties let you control what happens when content overflows an element box. +Overflow happens when the content in an element box extends past one or more of the box's edges. **Scrollable overflow** is the content that appears outside the element box for which you might want to add a scrolling mechanism. CSS overflow properties let you control what happens when content overflows an element box, including creating carousels without JavaScript. Painting effects that overflow the content but do not participate in the CSS box model do not affect layout. This type of overflow is also known as {{Glossary("ink overflow")}}. Examples of ink overflows include box shadows, border images, text decoration, overhanging glyphs, and outlines. Ink overflows do not extend the scrollable overflow region. @@ -226,12 +227,20 @@ A link is included in the content box above to demonstrate the effects of keyboa - {{CSSxRef("overflow-x")}} - {{CSSxRef("overflow-y")}} - {{CSSxRef("scroll-behavior")}} +- {{cssxref("scroll-marker-group")}} - {{CSSxRef("scrollbar-gutter")}} - {{CSSxRef("text-overflow")}} > [!NOTE] > The CSS Overflow Module Level 4 introduces the `block-ellipsis`, `continue`, `max-lines`, `overflow-clip-margin-block`, `overflow-clip-margin-block-end`, `overflow-clip-margin-block-start`, `overflow-clip-margin-bottom`, `overflow-clip-margin-inline`, `overflow-clip-margin-inline-end`, `overflow-clip-margin-inline-start`, `overflow-clip-margin-left`, `overflow-clip-margin-right`, and `overflow-clip-margin-top` properties. These have not yet been implemented. +### Selectors and pseudo-elements + +- {{cssxref("::scroll-button()")}} +- {{cssxref("::scroll-marker")}} +- {{cssxref("::scroll-marker-group")}} +- {{cssxref(":target-current")}} + ### Data types - [`<overflow>`](/en-US/docs/Web/CSS/overflow_value) enumerated values @@ -240,11 +249,14 @@ A link is included in the content box above to demonstrate the effects of keyboa - [Learn: Overflowing content](/en-US/docs/Learn_web_development/Core/Styling_basics/Overflow) - : Learn what overflow is and how to manage it. +- [Creating CSS carousels](/en-US/docs/Web/CSS/CSS_overflow/CSS_carousels) + - : Create pure-CSS carousel UI features using scroll buttons, scroll markers, and generated columns. - [Creating a named scroll progress timeline animation](/en-US/docs/Web/CSS/scroll-timeline-name#creating_a_named_scroll_progress_timeline_animation) - : The CSS scroll timeline {{cssxref('scroll-timeline-name')}} and {{cssxref('scroll-timeline-axis')}} properties, along with the {{cssxref('scroll-timeline')}} shorthand, create animations tied to the scroll offset of a scroll container. ## Related concepts +- {{cssxref("::column")}} - {{CSSxRef("scrollbar-width")}} CSS property - {{CSSxRef("scrollbar-color")}} CSS property - {{CSSxRef("scrollbar-gutter")}} CSS property @@ -256,7 +268,7 @@ A link is included in the content box above to demonstrate the effects of keyboa - {{cssxref("scroll-snap-type")}} CSS property - {{cssxref("text-overflow")}} CSS property - {{CSSxRef("::-webkit-scrollbar")}} pseudo-element -- [`scrollbar`](/en-US/docs/Web/Accessibility/ARIA/Roles/scrollbar_role) ARIA role +- [`scrollbar`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/scrollbar_role) ARIA role - Element {{domxref("Element.scroll", "scroll()")}} method - Element {{domxref("Element.scrollBy", "scrollBy()")}} method - Element {{domxref("Element.scrollIntoView", "scrollIntoView()")}} method diff --git a/files/en-us/web/css/css_overscroll_behavior/index.md b/files/en-us/web/css/css_overscroll_behavior/index.md index 22297809fbd8306..2e1e17b0cb2963a 100644 --- a/files/en-us/web/css/css_overscroll_behavior/index.md +++ b/files/en-us/web/css/css_overscroll_behavior/index.md @@ -39,7 +39,7 @@ This module defines the overscroll behavior, enabling you to specify the actions ## Related concepts -- [`scrollbar`](/en-US/docs/Web/Accessibility/ARIA/Roles/scrollbar_role) ARIA role +- [`scrollbar`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/scrollbar_role) ARIA role - [Containing block](/en-US/docs/Web/CSS/CSS_display/Containing_block) concept - [CSS overflow](/en-US/docs/Web/CSS/CSS_overflow) module: - {{cssxref("overflow")}} shorthand property @@ -74,7 +74,7 @@ This module defines the overscroll behavior, enabling you to specify the actions ## See also +- [CSS scroll anchoring](/en-US/docs/Web/CSS/CSS_scroll_anchoring) module +- [CSS scroll snap](/en-US/docs/Web/CSS/CSS_scroll_snap) module - [CSS box model](/en-US/docs/Web/CSS/CSS_box_model) module - [CSS logical properties and values](/en-US/docs/Web/CSS/CSS_logical_properties_and_values) module -- [CSS scroll snap](/en-US/docs/Web/CSS/CSS_scroll_snap) module -- [Take control of your scroll - customizing pull-to-refresh and overflow effects](https://developer.chrome.com/blog/overscroll-behavior) on developer.chrome.com (2017) diff --git a/files/en-us/web/css/css_positioned_layout/index.md b/files/en-us/web/css/css_positioned_layout/index.md index 00cc58b6df205de..724fa3bdee41bbf 100644 --- a/files/en-us/web/css/css_positioned_layout/index.md +++ b/files/en-us/web/css/css_positioned_layout/index.md @@ -38,6 +38,14 @@ The **CSS positioned layout** module defines how to position elements on a web p - [Understanding z-index](/en-US/docs/Web/CSS/CSS_positioned_layout/Understanding_z-index) - : Presents the notion of stacking context and explains how z-ordering works, with several examples. +- [Stacking without the `z-index` property](/en-US/docs/Web/CSS/CSS_positioned_layout/Stacking_without_z-index) + - : The stacking rules that apply when `z-index` is not used. +- [Stacking floating elements](/en-US/docs/Web/CSS/CSS_positioned_layout/Stacking_floating_elements) + - : How floating elements are handled with stacking. +- [Using `z-index`](/en-US/docs/Web/CSS/CSS_positioned_layout/Using_z-index) + - : How to use `z-index` to change default stacking. +- [Stacking context](/en-US/docs/Web/CSS/CSS_positioned_layout/Stacking_context) + - : CSS stacking context, the CSS features that create new stacking contexts, and nested stacking contexts. ## Related concepts diff --git a/files/en-us/web/css/css_positioned_layout/stacking_context/index.md b/files/en-us/web/css/css_positioned_layout/stacking_context/index.md new file mode 100644 index 000000000000000..16be62ad74ab433 --- /dev/null +++ b/files/en-us/web/css/css_positioned_layout/stacking_context/index.md @@ -0,0 +1,245 @@ +--- +title: Stacking context +slug: Web/CSS/CSS_positioned_layout/Stacking_context +page-type: guide +--- + +{{CSSRef}} + +**Stacking context** is a three-dimensional conceptualization of HTML elements along an imaginary z-axis relative to the user, who is assumed to be facing the viewport or the webpage. The stacking context determines how elements are layered on top of one another along the z-axis (think of it as the "depth" dimension on your screen). Stacking context determines the visual order of how overlapping content is rendered. + +Elements within a stacking context are stacked independently from elements outside of that stacking context, ensuring elements in one stacking context don't interfere with the stacking order of elements in another. Each stacking context is completely independent of its siblings: only descendant elements are considered when stacking is processed. + +Each stacking context is self-contained. After an element's contents are stacked, the entire element is considered as a single unit in the stacking order of its parent stacking context. + +Within a stacking context, child elements are stacked according to the `z-index` values of all the siblings. The stacking contexts of these nested elements only have meaning in this parent. Stacking contexts are treated atomically as a single unit in the parent stacking context. Stacking contexts can be contained in other stacking contexts, and together create a hierarchy of stacking contexts. + +The hierarchy of stacking contexts is a subset of the hierarchy of HTML elements because only certain elements create stacking contexts. Elements that don't create their own stacking contexts are _assimilated_ by the parent stacking context. + +## Features creating stacking contexts + +A stacking context is formed, anywhere in the document, by any element in the following scenarios: + +- Root element of the document (`<html>`). +- Element with a {{cssxref("position")}} value `absolute` or `relative` and {{cssxref("z-index")}} value other than `auto`. +- Element with a {{cssxref("position")}} value `fixed` or `sticky`. +- Element with a {{cssxref("container-type")}} value `size` or `inline-size` set (See [container queries](/en-US/docs/Web/CSS/CSS_containment/Container_queries)). +- Element that is a [flex item](/en-US/docs/Web/CSS/CSS_flexible_box_layout/Basic_concepts_of_flexbox) with a {{cssxref("z-index")}} value other than `auto`. +- Element that is a [grid item]() with {{cssxref("z-index")}} value other than `auto`. +- Element with an {{cssxref("opacity")}} value less than `1`. +- Element with a {{cssxref("mix-blend-mode")}} value other than `normal`. +- Element with any of the following properties with a value other than `none`: + + - {{cssxref("transform")}} + - {{cssxref("scale")}} + - {{cssxref("rotate")}} + - {{cssxref("translate")}} + - {{cssxref("filter")}} + - {{cssxref("backdrop-filter")}} + - {{cssxref("perspective")}} + - {{cssxref("clip-path")}} + - {{cssxref("mask")}} / {{cssxref("mask-image")}} / {{cssxref("mask-border")}} + +- Element with the {{cssxref("isolation")}} value `isolate`. +- Element with a {{cssxref("will-change")}} value specifying any property that would create a stacking context on non-initial value. +- Element with a {{cssxref("contain")}} value of `layout` or `paint`, or a composite value that includes either of these values (i.e., `contain: strict`, `contain: content`). +- Element placed into the [top layer](/en-US/docs/Glossary/Top_layer) and its corresponding {{cssxref("::backdrop")}}. Examples include [fullscreen](/en-US/docs/Web/API/Fullscreen_API) and [popover](/en-US/docs/Web/API/Popover_API) elements. +- Element that has had stacking context-creating properties (such as `opacity`) animated using {{cssxref("@keyframes")}}, with [`animation-fill-mode`](/en-US/docs/Web/CSS/animation-fill-mode) set to [`forwards`](/en-US/docs/Web/CSS/animation-fill-mode#forwards). + +## Nested stacking contexts + +Stacking contexts can be contained in other stacking contexts, and they can together create a hierarchy of stacking contexts. + +The root element of a document is a stacking context which, in most cases, contains nested stacking contexts, many of which will contain additional stacking contexts. Within each stacking context, child elements are stacked according to the same rules explained in [Using `z-index`](/en-US/docs/Web/CSS/CSS_positioned_layout/Using_z-index). Importantly, the `z-index` values of its child stacking contexts only have meaning within its parent's stacking context. Stacking contexts are treated atomically as a single unit in the parent stacking context. + +To figure out the _rendering order_ of stacked elements along the z-axis, think of each index value as a "version number" of sorts, where child elements represent minor version numbers underneath their parent's major version number. + +To demonstrate how the stacking order of each element participates in the stacking order of their ancestor stacking contexts, let's look at an example page with six container elements. There are three sibling {{htmlelement("article")}} elements. The last `<article>` contains three sibling {{htmlelement("section")}} elements, with the {{htmlelement("heading_elements", "&lt;h1&gt;")}} and {{htmlelement("code")}} of that third article appearing between the first and second sibling `<section>` elements. + +```html +<article id="container1"> + <h1>Article element #1</h1> + <code> + position: relative;<br /> + z-index: 5; + </code> +</article> + +<article id="container2"> + <h1>Article Element #2</h1> + <code> + position: relative;<br /> + z-index: 2; + </code> +</article> + +<article id="container3"> + <section id="container4"> + <h1>Section Element #4</h1> + <code> + position: relative;<br /> + z-index: 6; + </code> + </section> + + <h1>Article Element #3</h1> + <code> + position: absolute;<br /> + z-index: 4; + </code> + + <section id="container5"> + <h1>Section Element #5</h1> + <code> + position: relative;<br /> + z-index: 1; + </code> + </section> + + <section id="container6"> + <h1>Section Element #6</h1> + <code> + position: absolute;<br /> + z-index: 3; + </code> + </section> +</article> +``` + +Every container element has an {{cssxref("opacity")}} of less than `1` and a {{cssxref("position")}} of either `relative` or `absolute` set. These property-value pairs create a stacking context when the element has `z-index` value other than `auto`. + +```css hidden +* { + margin: 0; +} +html { + padding: 20px; + font: + 12px/20px Arial, + sans-serif; +} +h1 { + font-size: 1.25em; +} +#container1, +#container2 { + border: 1px dashed #696; + padding: 10px; + background-color: #cfc; +} +#container1 { + margin-bottom: 190px; +} +#container3 { + border: 1px dashed #900; + background-color: #fdd; + padding: 40px 20px 20px; + width: 330px; +} +#container4 { + border: 1px dashed #996; + background-color: #ffc; + padding: 25px 10px 5px; + margin-bottom: 15px; +} +#container5 { + border: 1px dashed #996; + background-color: #ffc; + margin-top: 15px; + padding: 5px 10px; +} +#container6 { + background-color: #ddf; + border: 1px dashed #009; + padding-left: 20px; + padding-top: 125px; + width: 150px; + height: 125px; +} +``` + +```css +section, +article { + opacity: 0.85; + position: relative; +} +#container1 { + z-index: 5; +} +#container2 { + z-index: 2; +} +#container3 { + z-index: 4; + position: absolute; + top: 40px; + left: 180px; +} +#container4 { + z-index: 6; +} +#container5 { + z-index: 1; +} +#container6 { + z-index: 3; + position: absolute; + top: 20px; + left: 180px; +} +``` + +The CSS properties for colors, fonts, alignment, and [box-model](/en-US/docs/Web/CSS/CSS_box_model/Introduction_to_the_CSS_box_model) have been hidden for brevity. + +{{ EmbedLiveSample('Nested stacking contexts', '100%', '396') }} + +The hierarchy of stacking contexts in the above example is as follows: + +```plain no-lint +Root +│ +├── ARTICLE #1 +├── ARTICLE #2 +└── ARTICLE #3 + │ + ├── SECTION #4 + ├──── ARTICLE #3 content + ├── SECTION #5 + └── SECTION #6 +``` + +The three `<section>` elements are children of ARTICLE #3. Therefore, the stacking of the section elements is completely resolved within ARTICLE #3. Once stacking and rendering within ARTICLE #3 is completed, the whole ARTICLE #3 element is passed for stacking in the root element with respect to its sibling `<article>` elements. + +By comparing the `z-index` as "version numbers", we can see how an element with a `z-index` of `1` (SECTION #5) is stacked above an element with a `z-index` of `2` (ARTICLE #2), and how an element with a `z-index` of `6` (SECTION #4) is stacked below an element with a `z-index` of `5` (ARTICLE #1). +SECTION #4 is rendered under ARTICLE #1 because ARTICLE #1's z-index (`5`) is valid within the stacking context of the root element, while SECTION #4's z-index (`6`) is valid within the stacking context of ARTICLE #3 (`z-index: 4`). So SECTION #4 is under ARTICLE #1 because SECTION #4 belongs to ARTICLE #3, which has a lower z-index value (`4-6` is less than `5-0`). + +For the same reason, ARTICLE #2 (`z-index: 2`) is rendered under SECTION #5 (`z-index`: 1) because SECTION #5 belongs to ARTICLE #3 (`z-index: 4`), which has a higher z-index value (`2-0` is less than `4-1`). + +ARTICLE #3's z-index is `4`, but this value is independent of the `z-index` of three sections nested inside it because they belong to a different stacking context. + +In our example (sorted according to the final rendering order): + +- Root + + - ARTICLE #2: (`z-index`: 2), which results in a rendering order of `2-0` + - ARTICLE #3: (`z-index`: 4), which results in a rendering order of `4-0` + + - SECTION #5: (`z-index`: 1), stacked under an element (`z-index`: 4), which results in a rendering order of `4-1` + - SECTION #6: (`z-index`: 3), stacked under an element (`z-index`: 4), which results in a rendering order of `4-3` + - SECTION #4: (`z-index`: 6), stacked under an element (`z-index`: 4), which results in a rendering order of `4-6` + + - ARTICLE #1: (`z-index`: 5), which results in a rendering order of `5-0` + +## Additional examples + +Additional examples include a [2-level hierarchy with `z-index` on the last level](/en-US/docs/Web/CSS/CSS_positioned_layout/Stacking_context/Stacking_context_example_1), a [2-level HTML hierarchy, `z-index` on all levels](/en-US/docs/Web/CSS/CSS_positioned_layout/Stacking_context/Stacking_context_example_2), and a [3-level HTML hierarchy, `z-index` on the second level](/en-US/docs/Web/CSS/CSS_positioned_layout/Stacking_context/Stacking_context_example_3). + +## See also + +- [Understanding z-index](/en-US/docs/Web/CSS/CSS_positioned_layout/Understanding_z-index) +- [Stacking without the `z-index` property](/en-US/docs/Web/CSS/CSS_positioned_layout/Stacking_without_z-index) +- [Stacking floating elements](/en-US/docs/Web/CSS/CSS_positioned_layout/Stacking_floating_elements) +- [Using z-index](/en-US/docs/Web/CSS/CSS_positioned_layout/Using_z-index) +- {{glossary("Top layer")}} +- [CSS positioned layout](/en-US/docs/Web/CSS/CSS_positioned_layout) module diff --git a/files/en-us/web/css/css_positioned_layout/stacking_context/stacking_context_example_1/index.md b/files/en-us/web/css/css_positioned_layout/stacking_context/stacking_context_example_1/index.md new file mode 100644 index 000000000000000..fdbd508992aca38 --- /dev/null +++ b/files/en-us/web/css/css_positioned_layout/stacking_context/stacking_context_example_1/index.md @@ -0,0 +1,116 @@ +--- +title: Stacking context example 1 +slug: Web/CSS/CSS_positioned_layout/Stacking_context/Stacking_context_example_1 +page-type: guide +--- + +{{CSSRef}} + +## Description + +Let's start with a basic example. In the root stacking context, there are two relatively positioned `<div>` elements (DIV #1 and DIV #3) without `z-index` properties. Inside DIV #1, there is an absolutely positioned DIV #2, while in DIV #3, there is an absolutely positioned DIV #4, both without `z-index` properties. + +The only stacking context is the root context. Without `z-index` values, elements are stacked in order of occurrence. + +![Stacking context example 1](understanding_zindex_05a.png) + +If DIV #2 is assigned a positive (non-zero and non-auto) z-index value, it is rendered above all the other DIVs. + +![Stacking context example 1](understanding_zindex_05b.png) + +Then if DIV #4 is also assigned a positive z-index greater than DIV #2's z-index, it is rendered above all the other DIVs including DIV #2. + +![Stacking context example 1](understanding_zindex_05c.png) + +In this last example you can see that DIV #2 and DIV #4 are not siblings, because they belong to different parents in the HTML elements' hierarchy. Even so, stacking of DIV #4 with respect of DIV #2 can be controlled through `z-index`. It happens that, since DIV #1 and DIV #3 are not assigned any z-index value, they do not create a stacking context. This means that all their content, including DIV #2 and DIV #4, belongs to the same root stacking context. + +In terms of stacking contexts, DIV #1 and DIV #3 are assimilated into the root element, and the resulting hierarchy is the following: + +- Root stacking context + + - DIV #2 (`z-index`: 1) + - DIV #4 (`z-index`: 2) + +> [!NOTE] +> DIV #1 and DIV #3 are not translucent. It is important to remember that assigning an opacity less than 1 to a positioned element implicitly creates a stacking context, just like adding a `z-index` value. And this example shows what happens when a parent element does not create a stacking context. + +## Example + +### HTML + +```html +<div id="div1"> + <br /><span class="bold">DIV #1</span> <br />position: relative; + <div id="div2"> + <br /><span class="bold">DIV #2</span> <br />position: absolute; + <br />z-index: 1; + </div> +</div> + +<br /> + +<div id="div3"> + <br /><span class="bold">DIV #3</span> <br />position: relative; + <div id="div4"> + <br /><span class="bold">DIV #4</span> <br />position: absolute; + <br />z-index: 2; + </div> +</div> +``` + +### CSS + +```css +.bold { + font-family: Arial; + font-size: 12px; + font-weight: bold; +} + +#div1, +#div3 { + height: 80px; + position: relative; + border: 1px dashed #669966; + background-color: #ccffcc; + padding-left: 5px; +} + +#div2 { + opacity: 0.8; + z-index: 1; + position: absolute; + width: 150px; + height: 200px; + top: 20px; + left: 170px; + border: 1px dashed #990000; + background-color: #ffdddd; + text-align: center; +} + +#div4 { + opacity: 0.8; + z-index: 2; + position: absolute; + width: 200px; + height: 80px; + top: 65px; + left: 50px; + border: 1px dashed #000099; + background-color: #ddddff; + text-align: left; + padding-left: 10px; +} +``` + +## Result + +{{ EmbedLiveSample('Example', '', '300') }} + +## See also + +- [Example: 2-level HTML hierarchy, `z-index` on all levels](/en-US/docs/Web/CSS/CSS_positioned_layout/Stacking_context/Stacking_context_example_2) +- [Example: 3-level HTML hierarchy, `z-index` on the second level](/en-US/docs/Web/CSS/CSS_positioned_layout/Stacking_context/Stacking_context_example_3) +- [Stacking context](/en-US/docs/Web/CSS/CSS_positioned_layout/Stacking_context) +- [CSS positioned layout](/en-US/docs/Web/CSS/CSS_positioned_layout) module diff --git a/files/en-us/web/css/css_positioned_layout/understanding_z-index/stacking_context_example_1/understanding_zindex_05a.png b/files/en-us/web/css/css_positioned_layout/stacking_context/stacking_context_example_1/understanding_zindex_05a.png similarity index 100% rename from files/en-us/web/css/css_positioned_layout/understanding_z-index/stacking_context_example_1/understanding_zindex_05a.png rename to files/en-us/web/css/css_positioned_layout/stacking_context/stacking_context_example_1/understanding_zindex_05a.png diff --git a/files/en-us/web/css/css_positioned_layout/understanding_z-index/stacking_context_example_1/understanding_zindex_05b.png b/files/en-us/web/css/css_positioned_layout/stacking_context/stacking_context_example_1/understanding_zindex_05b.png similarity index 100% rename from files/en-us/web/css/css_positioned_layout/understanding_z-index/stacking_context_example_1/understanding_zindex_05b.png rename to files/en-us/web/css/css_positioned_layout/stacking_context/stacking_context_example_1/understanding_zindex_05b.png diff --git a/files/en-us/web/css/css_positioned_layout/understanding_z-index/stacking_context_example_1/understanding_zindex_05c.png b/files/en-us/web/css/css_positioned_layout/stacking_context/stacking_context_example_1/understanding_zindex_05c.png similarity index 100% rename from files/en-us/web/css/css_positioned_layout/understanding_z-index/stacking_context_example_1/understanding_zindex_05c.png rename to files/en-us/web/css/css_positioned_layout/stacking_context/stacking_context_example_1/understanding_zindex_05c.png diff --git a/files/en-us/web/css/css_positioned_layout/stacking_context/stacking_context_example_2/index.md b/files/en-us/web/css/css_positioned_layout/stacking_context/stacking_context_example_2/index.md new file mode 100644 index 000000000000000..c427b6602866cac --- /dev/null +++ b/files/en-us/web/css/css_positioned_layout/stacking_context/stacking_context_example_2/index.md @@ -0,0 +1,127 @@ +--- +title: Stacking context example 2 +slug: Web/CSS/CSS_positioned_layout/Stacking_context/Stacking_context_example_2 +page-type: guide +--- + +{{CSSRef}} + +## Description + +This is a basic example, but it is the key for understanding the concept of _stacking context_. There are the same four DIVs of the previous example, but now `z-index` properties are assigned on both levels of the hierarchy. + +You can see that DIV #2 (`z-index`: 2) is above DIV #3 (`z-index`: 1), because they both belong to the same stacking context (the root one), so z-index values rule how elements are stacked. + +What can be considered strange is that DIV #2 (`z-index`: 2) is above DIV #4 (`z-index`: 10), despite their z-index values. The reason is that they do not belong to the same stacking context. DIV #4 belongs to the stacking context created by DIV #3, and as explained previously DIV #3 (and all its content) is under DIV #2. + +To better understand the situation, this is the stacking context hierarchy: + +- Root stacking context + + - DIV #2 (`z-index`: 2) + - DIV #3 (`z-index`: 1) + + - DIV #4 (`z-index`: 10) + +> [!NOTE] +> It is worth remembering that the HTML hierarchy is different from the stacking context hierarchy. In the stacking context hierarchy, elements that do not create a stacking context are collapsed on their parent. + +## Example + +### HTML + +```html +<div id="div1"> + <br /> + <span class="bold">DIV #1</span><br /> + position: relative; + <div id="div2"> + <br /> + <span class="bold">DIV #2</span><br /> + position: absolute;<br /> + z-index: 2; + </div> +</div> + +<br /> + +<div id="div3"> + <br /> + <span class="bold">DIV #3</span><br /> + position: relative;<br /> + z-index: 1; + <div id="div4"> + <br /> + <span class="bold">DIV #4</span><br /> + position: absolute;<br /> + z-index: 10; + </div> +</div> +``` + +### CSS + +```css +div { + font: 12px Arial; +} + +span.bold { + font-weight: bold; +} + +#div2 { + z-index: 2; +} +#div3 { + z-index: 1; +} +#div4 { + z-index: 10; +} + +#div1, +#div3 { + height: 80px; + position: relative; + border: 1px dashed #669966; + background-color: #ccffcc; + padding-left: 5px; +} + +#div2 { + opacity: 0.8; + position: absolute; + width: 150px; + height: 200px; + top: 20px; + left: 170px; + border: 1px dashed #990000; + background-color: #ffdddd; + text-align: center; +} + +#div4 { + opacity: 0.8; + position: absolute; + width: 200px; + height: 70px; + top: 65px; + left: 50px; + border: 1px dashed #000099; + background-color: #ddddff; + text-align: left; + padding-left: 10px; +} +``` + +## Result + +{{ EmbedLiveSample('Example', '352', '270') }} + +## See also + +- [Example: 1-level HTML hierarchy, `z-index` on the last level](/en-US/docs/Web/CSS/CSS_positioned_layout/Stacking_context/Stacking_context_example_1) +- [Example: 3-level HTML hierarchy, `z-index` on the second level](/en-US/docs/Web/CSS/CSS_positioned_layout/Stacking_context/Stacking_context_example_3) +- [Stacking context](/en-US/docs/Web/CSS/CSS_positioned_layout/Stacking_context) +- [CSS positioned layout](/en-US/docs/Web/CSS/CSS_positioned_layout) module diff --git a/files/en-us/web/css/css_positioned_layout/stacking_context/stacking_context_example_3/index.md b/files/en-us/web/css/css_positioned_layout/stacking_context/stacking_context_example_3/index.md new file mode 100644 index 000000000000000..61c58497e9965c9 --- /dev/null +++ b/files/en-us/web/css/css_positioned_layout/stacking_context/stacking_context_example_3/index.md @@ -0,0 +1,156 @@ +--- +title: Stacking context example 3 +slug: Web/CSS/CSS_positioned_layout/Stacking_context/Stacking_context_example_3 +page-type: guide +--- + +{{CSSRef}} + +## Description + +This example shows problems that arise when mixing several positioned elements in a multi-level HTML hierarchy and when `z-index` values are assigned using class selectors. + +The example has a three-level hierarchical menu made from several positioned `div` elements. Second-level and third-level `div` elements appear when a user hovers or clicks on their parents. Usually this kind of menu is script-generated either client-side or server-side, so style rules are assigned with a class selector instead of the id selector. + +If the three menu levels partially overlap, then managing stacking could become a problem. + +The first-level menu is relatively positioned, creating a stacking context. + +The second-level menu is absolutely positioned inside the parent element. In order to put it above all first-level menus, the `z-index` property is used. The problem is that for each second-level menu, a stacking context is created and each third-level menu belongs to the context of its parent. + +So a third-level menu will be stacked under the following second-level menus, because all second-level menus share the same z-index value and the default stacking rules apply. + +To better understand the situation, here is the stacking context hierarchy (the three dots "..." represent multiple repetition of the previous line): + +- Root stacking context + + - LEVEL #1 + + - LEVEL #2 (`z-index`: 1) + + - LEVEL #3 + - … + - LEVEL #3 + + - LEVEL #2 (`z-index`: 1) + - … + - LEVEL #2 (`z-index`: 1) + + - LEVEL #1 + - … + - LEVEL #1 + +This problem can be avoided by removing overlapping between different level menus, or by using individual (and different) z-index values assigned through the id selector instead of class selector, or by flattening the HTML hierarchy. + +> [!NOTE] +> In the source code you will see that second-level and third level menus are made of several `div` elements contained in an absolutely positioned container. This is useful to group and position all of them at once. + +## Example + +### HTML + +```html +<div class="lev1"> + LEVEL #1 + + <div id="container1"> + <div class="lev2"> + LEVEL #2 <br />z-index: 1; + + <div id="container2"> + <div class="lev3">LEVEL #3</div> + <div class="lev3">LEVEL #3</div> + <div class="lev3">LEVEL #3</div> + <div class="lev3">LEVEL #3</div> + <div class="lev3">LEVEL #3</div> + <div class="lev3">LEVEL #3</div> + <div class="lev3">LEVEL #3</div> + <div class="lev3">LEVEL #3</div> + <div class="lev3">LEVEL #3</div> + <div class="lev3">LEVEL #3</div> + <div class="lev3">LEVEL #3</div> + </div> + </div> + + <div class="lev2">LEVEL #2 <br />z-index: 1;</div> + <div class="lev2">LEVEL #2 <br />z-index: 1;</div> + <div class="lev2">LEVEL #2 <br />z-index: 1;</div> + </div> +</div> + +<div class="lev1">LEVEL #1</div> +<div class="lev1">LEVEL #1</div> +<div class="lev1">LEVEL #1</div> +``` + +### CSS + +```css hidden +div { + font: 12px Arial; + font-weight: bold; + padding-left: 5px; +} +.lev1 { + border: 2px outset #669966; + background-color: #ccffcc; +} +.lev2 { + border: 2px outset #990000; + background-color: #ffdddd; +} +.lev3 { + border: 2px outset #000099; + background-color: #ddddff; +} +``` + +```css +div { + opacity: 0.9; +} +.lev1 { + width: 250px; + height: 70px; + position: relative; +} + +#container1 { + z-index: 1; + position: absolute; + top: 30px; + left: 75px; +} + +.lev2 { + width: 200px; + height: 60px; + position: relative; +} + +#container2 { + z-index: 1; + position: absolute; + top: 20px; + left: 110px; +} + +.lev3 { + z-index: 10; + width: 100px; + position: relative; +} +``` + +## Result + +{{ EmbedLiveSample('Example', '320', '330') }} + +## See also + +- [Stacking without the `z-index` property](/en-US/docs/Web/CSS/CSS_positioned_layout/Stacking_without_z-index): The stacking rules that apply when `z-index` is not used. +- [Stacking floating elements](/en-US/docs/Web/CSS/CSS_positioned_layout/Stacking_floating_elements): How floating elements are handled with stacking. +- [Using z-index](/en-US/docs/Web/CSS/CSS_positioned_layout/Using_z-index): How to use `z-index` to change default stacking. +- [Stacking context](/en-US/docs/Web/CSS/CSS_positioned_layout/Stacking_context): Notes on the stacking context. +- [Stacking context example 1](/en-US/docs/Web/CSS/CSS_positioned_layout/Stacking_context/Stacking_context_example_1): 2-level HTML hierarchy, `z-index` on the last level +- [Stacking context example 2](/en-US/docs/Web/CSS/CSS_positioned_layout/Stacking_context/Stacking_context_example_2): 2-level HTML hierarchy, `z-index` on all levels diff --git a/files/en-us/web/css/css_positioned_layout/stacking_floating_elements/index.md b/files/en-us/web/css/css_positioned_layout/stacking_floating_elements/index.md new file mode 100644 index 000000000000000..024693bcdca6534 --- /dev/null +++ b/files/en-us/web/css/css_positioned_layout/stacking_floating_elements/index.md @@ -0,0 +1,126 @@ +--- +title: Stacking floating elements +slug: Web/CSS/CSS_positioned_layout/Stacking_floating_elements +page-type: guide +--- + +{{CSSRef}} + +For floating elements, the stacking order is a bit different. Floating elements are placed between non-positioned elements and positioned elements: + +1. The background and borders of the root element. +2. Descendant non-positioned elements, in order of appearance in the HTML. +3. _Floating elements_. +4. Descendant positioned elements, in order of appearance in the HTML. + +See [types of positioning](/en-US/docs/Web/CSS/position#types_of_positioning) for an explanation of positioned and non-positioned elements. + +> [!NOTE] +> If an `opacity` value is applied to a non-positioned element (i.e., DIV #4 in the example below), something strange happens: the background and border of that block pop up above the floating blocks and the positioned blocks. This is due to a peculiar part of the specification: applying an `opacity` value creates a new stacking context (see [What No One Told You About Z-Index](https://philipwalton.com/articles/what-no-one-told-you-about-z-index/)). + +## Example + +You can see in this example that the background and border of the non-positioned element (DIV #4) is completely unaffected by floating elements, but the content is affected. This happens according to standard float behavior which can be shown with a rule added to the above list: + +1. The background and borders of the root element. +2. Descendant non-positioned elements, in order of appearance in the HTML. +3. Floating elements. +4. _Descendant non-positioned inline elements_. +5. Descendant positioned elements, in order of appearance in the HTML. + +### HTML + +```html +<div id="abs1"><strong>DIV #1</strong><br />position: absolute;</div> + +<div id="flo1"><strong>DIV #2</strong><br />float: left;</div> + +<div id="flo2"><strong>DIV #3</strong><br />float: right;</div> + +<br /> + +<div id="sta1"><strong>DIV #4</strong><br />no positioning</div> + +<div id="abs2"><strong>DIV #5</strong><br />position: absolute;</div> + +<div id="rel1"><strong>DIV #6</strong><br />position: relative;</div> +``` + +### CSS + +```css +div { + padding: 10px; + text-align: center; +} + +strong { + font-family: sans-serif; +} + +#abs1 { + position: absolute; + width: 150px; + height: 200px; + top: 10px; + right: 140px; + border: 1px dashed #900; + background-color: #fdd; +} + +#sta1 { + height: 100px; + border: 1px dashed #996; + background-color: #ffc; + margin: 0px 10px 0px 10px; + text-align: left; +} + +#flo1 { + margin: 0px 10px 0px 20px; + float: left; + width: 150px; + height: 200px; + border: 1px dashed #090; + background-color: #cfc; +} + +#flo2 { + margin: 0px 20px 0px 10px; + float: right; + width: 150px; + height: 200px; + border: 1px dashed #090; + background-color: #cfc; +} + +#abs2 { + position: absolute; + width: 150px; + height: 100px; + top: 80px; + left: 100px; + border: 1px dashed #990; + background-color: #fdd; +} + +#rel1 { + position: relative; + border: 1px dashed #996; + background-color: #cff; + margin: 0px 10px 0px 10px; + text-align: left; +} +``` + +## Result + +{{EmbedLiveSample("Example", 600, 250)}} + +## See also + +- [Understanding z-index](/en-US/docs/Web/CSS/CSS_positioned_layout/Understanding_z-index) +- [Stacking without the `z-index` property](/en-US/docs/Web/CSS/CSS_positioned_layout/Stacking_without_z-index) +- [Using z-index](/en-US/docs/Web/CSS/CSS_positioned_layout/Using_z-index) +- [Stacking context](/en-US/docs/Web/CSS/CSS_positioned_layout/Stacking_context) +- [CSS positioned layout](/en-US/docs/Web/CSS/CSS_positioned_layout) module diff --git a/files/en-us/web/css/css_positioned_layout/stacking_without_z-index/index.md b/files/en-us/web/css/css_positioned_layout/stacking_without_z-index/index.md new file mode 100644 index 000000000000000..b30cc1b35e3a374 --- /dev/null +++ b/files/en-us/web/css/css_positioned_layout/stacking_without_z-index/index.md @@ -0,0 +1,117 @@ +--- +title: Stacking without the z-index property +slug: Web/CSS/CSS_positioned_layout/Stacking_without_z-index +page-type: guide +--- + +{{CSSRef}} + +When the {{cssxref("z-index")}} property is not specified on any element, elements are stacked in the following order (from bottom to top): + +1. The background and borders of the root element. +2. Descendant non-positioned elements, in order of appearance in the HTML. +3. Descendant positioned elements, in order of appearance in the HTML. + +See [types of positioning](/en-US/docs/Web/CSS/position#types_of_positioning) for an explanation of positioned and non-positioned elements. + +Keep in mind, when the {{cssxref("order")}} property alters rendering from the _order of appearance in the HTML_ within {{cssxref("flex")}} containers, it similarly affects the order for stacking context. + +## Example + +In this example, DIV #1 through DIV #4 are positioned elements. DIV #5 is static, and so is drawn below the other four elements, even though it comes later in the HTML markup. + +### HTML + +```html +<div id="abs1" class="absolute"> + <strong>DIV #1</strong><br />position: absolute; +</div> +<div id="rel1" class="relative"> + <strong>DIV #2</strong><br />position: relative; +</div> +<div id="rel2" class="relative"> + <strong>DIV #3</strong><br />position: relative; +</div> +<div id="abs2" class="absolute"> + <strong>DIV #4</strong><br />position: absolute; +</div> +<div id="sta1" class="static"> + <strong>DIV #5</strong><br />position: static; +</div> +``` + +### CSS + +```css +strong { + font-family: sans-serif; +} + +div { + padding: 10px; + border: 1px dashed; + text-align: center; +} + +.static { + position: static; + height: 80px; + background-color: #ffc; + border-color: #996; +} + +.absolute { + position: absolute; + width: 150px; + height: 350px; + background-color: #fdd; + border-color: #900; + opacity: 0.7; +} + +.relative { + position: relative; + height: 80px; + background-color: #cfc; + border-color: #696; + opacity: 0.7; +} + +#abs1 { + top: 10px; + left: 10px; +} + +#rel1 { + top: 30px; + margin: 0px 50px 0px 50px; +} + +#rel2 { + top: 15px; + left: 20px; + margin: 0px 50px 0px 50px; +} + +#abs2 { + top: 10px; + right: 10px; +} + +#sta1 { + background-color: #ffc; + margin: 0px 50px 0px 50px; +} +``` + +## Result + +{{EmbedLiveSample("Example", 600, 400)}} + +## See also + +- [Understanding z-index](/en-US/docs/Web/CSS/CSS_positioned_layout/Understanding_z-index) +- [Using z-index](/en-US/docs/Web/CSS/CSS_positioned_layout/Using_z-index) +- [Stacking context](/en-US/docs/Web/CSS/CSS_positioned_layout/Stacking_context) +- [Stacking floating elements](/en-US/docs/Web/CSS/CSS_positioned_layout/Stacking_floating_elements) +- [CSS positioned layout](/en-US/docs/Web/CSS/CSS_positioned_layout) module diff --git a/files/en-us/web/css/css_positioned_layout/understanding_z-index/index.md b/files/en-us/web/css/css_positioned_layout/understanding_z-index/index.md index 36d7ce1046bd82a..b1ca018febd180c 100644 --- a/files/en-us/web/css/css_positioned_layout/understanding_z-index/index.md +++ b/files/en-us/web/css/css_positioned_layout/understanding_z-index/index.md @@ -6,27 +6,149 @@ page-type: guide {{CSSRef}} -In the most basic cases, [HTML](/en-US/docs/Web/HTML) pages can be considered two-dimensional, because text, images, and other elements are arranged on the page without overlapping. In this case, there is a single rendering flow, and all elements are aware of the space taken by others. The {{cssxref("z-index")}} attribute lets you adjust the order of the layering of objects when rendering content. +In the most basic cases, when text, images, and other elements are arranged on the page without overlapping, [HTML](/en-US/docs/Web/HTML) pages can be considered two-dimensional. In such cases, there is a single rendering flow, and all elements are aware of the space taken by others. CSS isn't that simple — CSS positioning, transformation, containment, and other features can cause elements to overlap. In this guide, we introduce the {{cssxref("z-index")}} property, which lets you place elements in front or behind other elements in the same [stacking context](/en-US/docs/Web/CSS/CSS_positioned_layout/Stacking_context). -> _In CSS 2.1, each box has a position in three dimensions. In addition to their horizontal and vertical positions, boxes lie along a "z-axis" and are formatted one on top of the other. Z-axis positions are particularly relevant when boxes overlap visually._ +## Layers on the z-axis -(from [CSS 2.1 Section 9.9.1 - Layered presentation](https://www.w3.org/TR/CSS21/visuren.html#z-index)) +The elements rendered on a page are comprised of a series of boxes. Each box has a position in three dimensions. In addition to their inline and block positions, boxes lie along a third dimension known as the _z-axis_. Controlling an element's z-axis position becomes especially relevant when element boxes overlap visually. Several property values can cause elements to overlap. The {{cssxref("z-index")}} property provides you a way to control how they overlap! -This means that CSS style rules allow you to position boxes on layers in addition to the default rendering layer (layer 0). The position on an imaginary z-axis of each layer is expressed as an integer representing the stacking order for rendering. Greater numbers mean closer to the observer. Control the position on this z-axis with the CSS `z-index` property. +By default, element boxes are rendered on Layer 0. The `z-index` property allows you to position elements on different layers along the z-axis, in addition to the default rendering layer. Each element's position along the imaginary z-axis (z-index value) is expressed as an integer (positive, negative, or zero) and controls the stacking order during rendering. Greater numbers mean elements are closer to the observer. -Using `z-index` appears extremely easy: a single property assigned a single integer number with an easy-to-understand behavior. When `z-index` is applied to complex hierarchies of HTML elements, its behavior can be hard to understand or predict. This is due to complex stacking rules. In fact, a dedicated section has been reserved in the CSS specification [CSS-2.1 Appendix E](https://www.w3.org/TR/CSS21/zindex.html) to explain these rules better. +If you are not familiar with the term 'z-axis', imagine the page as a stack of layers, each with an assigned number. Layers are rendered in numerical order, with larger numbers appearing on top of smaller numbers (_X_ in the table below represents an arbitrary positive integer): -This guide will try to explain those rules, with some simplification and several examples. +| Layer | Description | +| ------------ | ------------------------------------- | +| Bottom layer | Farthest from the observer | +| Layer -X | Layers with negative `z-index` values | +| Layer 0 | Default rendering layer | +| Layer X | Layers with positive `z-index` values | +| Top layer | Closest to the observer | -## Articles +## Elements in normal flow -1. [Stacking without the `z-index` property](/en-US/docs/Web/CSS/CSS_positioned_layout/Understanding_z-index/Stacking_without_z-index): The stacking rules that apply when `z-index` is not used. -2. [Stacking floating elements](/en-US/docs/Web/CSS/CSS_positioned_layout/Understanding_z-index/Stacking_floating_elements): How floating elements are handled with stacking. -3. [Using `z-index`](/en-US/docs/Web/CSS/CSS_positioned_layout/Understanding_z-index/Using_z-index): How to use `z-index` to change default stacking. -4. [Stacking context](/en-US/docs/Web/CSS/CSS_positioned_layout/Understanding_z-index/Stacking_context): Notes on the stacking context. +By default, when no `z-index` property is specified, elements are rendered on the default rendering layer (Layer 0). -## Examples +Consider the following three elements: -1. [Stacking context example 1](/en-US/docs/Web/CSS/CSS_positioned_layout/Understanding_z-index/Stacking_context_example_1): 2-level HTML hierarchy, `z-index` on the last level -2. [Stacking context example 2](/en-US/docs/Web/CSS/CSS_positioned_layout/Understanding_z-index/Stacking_context_example_2): 2-level HTML hierarchy, `z-index` on all levels -3. [Stacking context example 3](/en-US/docs/Web/CSS/CSS_positioned_layout/Understanding_z-index/Stacking_context_example_3): 3-level HTML hierarchy, `z-index` on the second level +```html live-sample___example1 live-sample___example2 live-sample___example3 +<div id="div1">#1</div> +<div id="div2">#2</div> +<div id="div3">#3</div> +``` + +Without any positioning properties applied, these elements flow normally in document order, one after another, without overlapping. + +```css live-sample___example1 live-sample___example2 live-sample___example3 live-sample___example4 +div { + height: 100px; + width: 100px; + outline: 1px dotted; + line-height: 100px; + font-size: 40px; + text-align: center; + font-family: arial, helvetica, sans-serif; +} + +#div1 { + background-color: lightpink; +} + +#div2 { + background-color: lightyellow; +} + +#div3 { + background-color: lightgreen; +} +``` + +{{EmbedLiveSample("Example1", 600, 340)}} + +## Default layering behavior + +To stack the elements, we can [position](/en-US/docs/Web/CSS/position#types_of_positioning) them. +If we use absolute positioning to place them in (almost) the same spot, the default stacking order follows the source order: the first element in the HTML appears at the bottom layer and the last element appears at the top layer. + +```css live-sample___example2 live-sample___example3 live-sample___example4 +div { + position: absolute; +} + +#div1 { + top: 0; + left: 0; +} + +#div2 { + top: 10px; + left: 10px; +} + +#div3 { + top: 20px; + left: 20px; +} +``` + +{{EmbedLiveSample("Example2", 600, 130)}} + +## Rearranging layers + +We can use the CSS {{cssxref("z-index")}} property to position each element along the z-axis, effectively rearranging the stacking order. + +By adding `z-index` values, we change the default layer order: + +```css live-sample___example3 live-sample___example4 +#div1 { + z-index: 5; +} + +#div2 { + z-index: -9; +} + +#div3 { + z-index: 0; +} +``` + +{{EmbedLiveSample("Example3", 600, 130)}} + +The element with the lowest `z-index` value appears on the bottom layer. The element with the highest `z-index` value appears on the top layer. In this example, `-9` is the lowest value, so `#div2` is behind all the others. The first element in the source order, `#div1`, has the greatest value, so it appears on top of all the others. + +## Impact of stacking contexts + +Using `z-index` may appear fairly straightforward at first: a single property assigned a single integer number with a seemingly understandable behavior. When `z-index` is applied to complex hierarchies of HTML elements, many find the resulting behavior hard to understand or predict. + +If the elements are not siblings, the stacking behavior can become more complicated because each element may belong to a different [stacking context](/en-US/docs/Web/CSS/CSS_positioned_layout/Stacking_context). This is shown in the example below. + +```html live-sample___example4 +<section> + <div id="div1">#1</div> + <div id="div2">#2</div> +</section> +<div id="div3">#3</div> +``` + +```css live-sample___example4 +section { + position: absolute; + z-index: 2; +} +``` + +{{EmbedLiveSample("Example4", 600, 130)}} + +Even though the `z-index` value of `#div3` (`0`) is greater than that of `#div2` (`-9`), `#div2` appears above `#div3` because `#div1` and `#div2` are nested in a separate stacking context created by `<section>`. The `<section>` element and `#div3` are siblings, and since the `<section>` element's z-index is greater than that of `#div3` (`2` versus `0`), `#div3` is placed behind `<section>` and all of `<section>`'s contents. For more in-depth details about the topic, see our [Stacking context](/en-US/docs/Web/CSS/CSS_positioned_layout/Stacking_context) guide. + +## Conclusion + +As we've seen in this guide, `z-index` provides a way to control how elements stack along z-axis. You learned how the integer values of the `z-index` property can be used to alter the stacking order. However, as demonstrated in the last example, stacking orders can be complicated. Stacking orders follow a series of complex stacking rules to ensure that all browsers stack the same content in the same manner providing consistency and predictability. It's important to understand the [features that create stacking contexts](/en-US/docs/Web/CSS/CSS_positioned_layout/Stacking_context#features_creating_stacking_contexts) and how [nested stacking contexts](/en-US/docs/Web/CSS/CSS_positioned_layout/Stacking_context#nested_stacking_contexts) affect layer order. + +## See also + +- [Stacking without the `z-index` property](/en-US/docs/Web/CSS/CSS_positioned_layout/Stacking_without_z-index) +- [Stacking floating elements](/en-US/docs/Web/CSS/CSS_positioned_layout/Stacking_floating_elements) +- [Using `z-index`](/en-US/docs/Web/CSS/CSS_positioned_layout/Using_z-index) +- [Stacking context](/en-US/docs/Web/CSS/CSS_positioned_layout/Stacking_context) +- [CSS positioned layout](/en-US/docs/Web/CSS/CSS_positioned_layout) module diff --git a/files/en-us/web/css/css_positioned_layout/understanding_z-index/stacking_context/index.md b/files/en-us/web/css/css_positioned_layout/understanding_z-index/stacking_context/index.md deleted file mode 100644 index 5235d62001c3fdd..000000000000000 --- a/files/en-us/web/css/css_positioned_layout/understanding_z-index/stacking_context/index.md +++ /dev/null @@ -1,230 +0,0 @@ ---- -title: Stacking context -slug: Web/CSS/CSS_positioned_layout/Understanding_z-index/Stacking_context -page-type: guide ---- - -{{CSSRef}} - -**Stacking context** is a three-dimensional conceptualization of HTML elements along an imaginary z-axis relative to the user, who is assumed to be facing the viewport or the webpage. HTML elements occupy this space in priority order based on element attributes. - -## Description - -In the previous article of this guide, [Using z-index](/en-US/docs/Web/CSS/CSS_positioned_layout/Understanding_z-index/Using_z-index), we showed that the rendering order of certain elements is influenced by their `z-index` value. This occurs because these elements have special properties which cause them to form a _stacking context_. - -A stacking context is formed, anywhere in the document, by any element in the following scenarios: - -- Root element of the document (`<html>`). -- Element with a {{cssxref("position")}} value `absolute` or `relative` and {{cssxref("z-index")}} value other than `auto`. -- Element with a {{cssxref("position")}} value `fixed` or `sticky` (sticky for all mobile browsers, but not older desktop browsers). -- Element with a {{cssxref("container-type")}} value `size` or `inline-size` set, intended for [container queries](/en-US/docs/Web/CSS/CSS_containment/Container_queries). -- Element that is a child of a [flex](/en-US/docs/Web/CSS/CSS_flexible_box_layout/Basic_concepts_of_flexbox) container, with {{cssxref("z-index")}} value other than `auto`. -- Element that is a child of a {{cssxref("grid")}} container, with {{cssxref("z-index")}} value other than `auto`. -- Element with an {{cssxref("opacity")}} value less than `1`. -- Element with a {{cssxref("mix-blend-mode")}} value other than `normal`. -- Element with any of the following properties with value other than `none`: - - - {{cssxref("transform")}} - - {{cssxref("scale")}} - - {{cssxref("rotate")}} - - {{cssxref("translate")}} - - {{cssxref("filter")}} - - {{cssxref("backdrop-filter")}} - - {{cssxref("perspective")}} - - {{cssxref("clip-path")}} - - {{cssxref("mask")}} / {{cssxref("mask-image")}} / {{cssxref("mask-border")}} - -- Element with an {{cssxref("isolation")}} value `isolate`. -- Element with a {{cssxref("will-change")}} value specifying any property that would create a stacking context on non-initial value. -- Element with a {{cssxref("contain")}} value of `layout`, or `paint`, or a composite value that includes either of them (i.e. `contain: strict`, `contain: content`). -- Element placed into the [top layer](/en-US/docs/Glossary/Top_layer) and its corresponding {{cssxref("::backdrop")}}. Examples include [fullscreen](/en-US/docs/Web/API/Fullscreen_API) and [popover](/en-US/docs/Web/API/Popover_API) elements. -- Element that has had stacking context-creating properties (such as `opacity`) animated using {{cssxref("@keyframes")}}, with [`animation-fill-mode`](/en-US/docs/Web/CSS/animation-fill-mode) set to [`forwards`](/en-US/docs/Web/CSS/animation-fill-mode#forwards). - -Within a stacking context, child elements are stacked according to the same rules explained just above. Importantly, the `z-index` values of its child stacking contexts only have meaning in this parent. Stacking contexts are treated atomically as a single unit in the parent stacking context. - -In summary: - -- Stacking contexts can be contained in other stacking contexts, and together create a hierarchy of stacking contexts. -- Each stacking context is completely independent of its siblings: only descendant elements are considered when stacking is processed. -- Each stacking context is self-contained: after the element's contents are stacked, the whole element is considered in the stacking order of the parent stacking context. - -> [!NOTE] -> The hierarchy of stacking contexts is a subset of the hierarchy of HTML elements because only certain elements create stacking contexts. We can say that elements that do not create their own stacking contexts are _assimilated_ by the parent stacking context. - -## Example - -![Example of stacking rules modified using z-index](understanding_zindex_04.png) - -In this example, every positioned element creates its own stacking context, because of their positioning and `z-index` values. The hierarchy of stacking contexts is organized as follows: - -- Root - - - DIV #1 - - DIV #2 - - DIV #3 - - - DIV #4 - - DIV #5 - - DIV #6 - -It is important to note that DIV #4, DIV #5 and DIV #6 are children of DIV #3, so stacking of those elements is completely resolved within DIV #3. Once stacking and rendering within DIV #3 is completed, the whole DIV #3 element is passed for stacking in the root element with respect to its sibling's DIV. - -DIV #4 is rendered under DIV #1 because DIV #1's z-index (5) is valid within the stacking context of the root element, while DIV #4's z-index (6) is valid within the stacking context of DIV #3. So, DIV #4 is under DIV #1, because DIV #4 belongs to DIV #3, which has a lower z-index value. - -For the same reason DIV #2 (`z-index`: 2) is rendered under DIV#5 (`z-index`: 1) because DIV #5 belongs to DIV #3, which has a higher z-index value. - -DIV #3's z-index is 4, but this value is independent from z-index of DIV #4, DIV #5 and DIV #6, because it belongs to a different stacking context. - -An easy way to figure out the _rendering order_ of stacked elements along the z-axis is to think of it as a "version number" of sorts, where child elements are minor version numbers underneath their parent's major version numbers. This way we can easily see how an element with a z-index of 1 (DIV #5) is stacked above an element with a z-index of 2 (DIV #2), and how an element with a z-index of 6 (DIV #4) is stacked below an element with a z-index of 5 (DIV #1). - -In our example (sorted according to the final rendering order): - -- Root - - - DIV #2: (`z-index`: 2) - - DIV #3: (`z-index`: 4) - - - DIV #5: (`z-index`: 1), stacked under an element (`z-index`: 4), which results in a rendering order of 4.1 - - DIV #6: (`z-index`: 3), stacked under an element (`z-index`: 4), which results in a rendering order of 4.3 - - DIV #4: (`z-index`: 6), stacked under an element (`z-index`: 4), which results in a rendering order of 4.6 - - - DIV #1: (`z-index`: 5) - -### HTML - -```html -<div id="div1"> - <h1>Division Element #1</h1> - <code> - position: relative;<br /> - z-index: 5; - </code> -</div> - -<div id="div2"> - <h1>Division Element #2</h1> - <code> - position: relative;<br /> - z-index: 2; - </code> -</div> - -<div id="div3"> - <div id="div4"> - <h1>Division Element #4</h1> - <code> - position: relative;<br /> - z-index: 6; - </code> - </div> - - <h1>Division Element #3</h1> - <code> - position: absolute;<br /> - z-index: 4; - </code> - - <div id="div5"> - <h1>Division Element #5</h1> - <code> - position: relative;<br /> - z-index: 1; - </code> - </div> - - <div id="div6"> - <h1>Division Element #6</h1> - <code> - position: absolute;<br /> - z-index: 3; - </code> - </div> -</div> -``` - -### CSS - -```css -* { - margin: 0; -} -html { - padding: 20px; - font: - 12px/20px Arial, - sans-serif; -} -div { - opacity: 0.7; - position: relative; -} -h1 { - font: inherit; - font-weight: bold; -} -#div1, -#div2 { - border: 1px dashed #696; - padding: 10px; - background-color: #cfc; -} -#div1 { - z-index: 5; - margin-bottom: 190px; -} -#div2 { - z-index: 2; -} -#div3 { - z-index: 4; - opacity: 1; - position: absolute; - top: 40px; - left: 180px; - width: 330px; - border: 1px dashed #900; - background-color: #fdd; - padding: 40px 20px 20px; -} -#div4, -#div5 { - border: 1px dashed #996; - background-color: #ffc; -} -#div4 { - z-index: 6; - margin-bottom: 15px; - padding: 25px 10px 5px; -} -#div5 { - z-index: 1; - margin-top: 15px; - padding: 5px 10px; -} -#div6 { - z-index: 3; - position: absolute; - top: 20px; - left: 180px; - width: 150px; - height: 125px; - border: 1px dashed #009; - padding-top: 125px; - background-color: #ddf; - text-align: center; -} -``` - -## Result - -{{ EmbedLiveSample('Example', '100%', '396') }} - -## See also - -- [Stacking without the `z-index` property](/en-US/docs/Web/CSS/CSS_positioned_layout/Understanding_z-index/Stacking_without_z-index): The stacking rules that apply when `z-index` is not used. -- [Stacking floating elements](/en-US/docs/Web/CSS/CSS_positioned_layout/Understanding_z-index/Stacking_floating_elements): How floating elements are handled with stacking. -- [Using z-index](/en-US/docs/Web/CSS/CSS_positioned_layout/Understanding_z-index/Using_z-index): How to use `z-index` to change default stacking. -- [Stacking context example 1](/en-US/docs/Web/CSS/CSS_positioned_layout/Understanding_z-index/Stacking_context_example_1): 2-level HTML hierarchy, `z-index` on the last level -- [Stacking context example 2](/en-US/docs/Web/CSS/CSS_positioned_layout/Understanding_z-index/Stacking_context_example_2): 2-level HTML hierarchy, `z-index` on all levels -- [Stacking context example 3](/en-US/docs/Web/CSS/CSS_positioned_layout/Understanding_z-index/Stacking_context_example_3): 3-level HTML hierarchy, `z-index` on the second level -- [Top layer](/en-US/docs/Glossary/Top_layer) diff --git a/files/en-us/web/css/css_positioned_layout/understanding_z-index/stacking_context/understanding_zindex_04.png b/files/en-us/web/css/css_positioned_layout/understanding_z-index/stacking_context/understanding_zindex_04.png deleted file mode 100644 index a57b36e7028671d..000000000000000 Binary files a/files/en-us/web/css/css_positioned_layout/understanding_z-index/stacking_context/understanding_zindex_04.png and /dev/null differ diff --git a/files/en-us/web/css/css_positioned_layout/understanding_z-index/stacking_context_example_1/index.md b/files/en-us/web/css/css_positioned_layout/understanding_z-index/stacking_context_example_1/index.md deleted file mode 100644 index f812db2d4aff9bb..000000000000000 --- a/files/en-us/web/css/css_positioned_layout/understanding_z-index/stacking_context_example_1/index.md +++ /dev/null @@ -1,118 +0,0 @@ ---- -title: Stacking context example 1 -slug: Web/CSS/CSS_positioned_layout/Understanding_z-index/Stacking_context_example_1 -page-type: guide ---- - -{{CSSRef}} - -## Description - -Let's start with a basic example. In the root stacking context, there are two relatively positioned `<div>` elements (DIV #1 and DIV #3) without `z-index` properties. Inside DIV #1, there is an absolutely positioned DIV #2, while in DIV #3, there is an absolutely positioned DIV #4, both without `z-index` properties. - -The only stacking context is the root context. Without `z-index` values, elements are stacked in order of occurrence. - -![Stacking context example 1](understanding_zindex_05a.png) - -If DIV #2 is assigned a positive (non-zero and non-auto) z-index value, it is rendered above all the other DIVs. - -![Stacking context example 1](understanding_zindex_05b.png) - -Then if DIV #4 is also assigned a positive z-index greater than DIV #2's z-index, it is rendered above all the other DIVs including DIV #2. - -![Stacking context example 1](understanding_zindex_05c.png) - -In this last example you can see that DIV #2 and DIV #4 are not siblings, because they belong to different parents in the HTML elements' hierarchy. Even so, stacking of DIV #4 with respect of DIV #2 can be controlled through `z-index`. It happens that, since DIV #1 and DIV #3 are not assigned any z-index value, they do not create a stacking context. This means that all their content, including DIV #2 and DIV #4, belongs to the same root stacking context. - -In terms of stacking contexts, DIV #1 and DIV #3 are assimilated into the root element, and the resulting hierarchy is the following: - -- Root stacking context - - - DIV #2 (`z-index`: 1) - - DIV #4 (`z-index`: 2) - -> [!NOTE] -> DIV #1 and DIV #3 are not translucent. It is important to remember that assigning an opacity less than 1 to a positioned element implicitly creates a stacking context, just like adding a `z-index` value. And this example shows what happens when a parent element does not create a stacking context. - -## Example - -### HTML - -```html -<div id="div1"> - <br /><span class="bold">DIV #1</span> <br />position: relative; - <div id="div2"> - <br /><span class="bold">DIV #2</span> <br />position: absolute; - <br />z-index: 1; - </div> -</div> - -<br /> - -<div id="div3"> - <br /><span class="bold">DIV #3</span> <br />position: relative; - <div id="div4"> - <br /><span class="bold">DIV #4</span> <br />position: absolute; - <br />z-index: 2; - </div> -</div> -``` - -### CSS - -```css -.bold { - font-family: Arial; - font-size: 12px; - font-weight: bold; -} - -#div1, -#div3 { - height: 80px; - position: relative; - border: 1px dashed #669966; - background-color: #ccffcc; - padding-left: 5px; -} - -#div2 { - opacity: 0.8; - z-index: 1; - position: absolute; - width: 150px; - height: 200px; - top: 20px; - left: 170px; - border: 1px dashed #990000; - background-color: #ffdddd; - text-align: center; -} - -#div4 { - opacity: 0.8; - z-index: 2; - position: absolute; - width: 200px; - height: 80px; - top: 65px; - left: 50px; - border: 1px dashed #000099; - background-color: #ddddff; - text-align: left; - padding-left: 10px; -} -``` - -## Result - -{{ EmbedLiveSample('Example', '', '300') }} - -## See also - -- [Stacking without the `z-index` property](/en-US/docs/Web/CSS/CSS_positioned_layout/Understanding_z-index/Stacking_without_z-index): The stacking rules that apply when `z-index` is not used. -- [Stacking floating elements](/en-US/docs/Web/CSS/CSS_positioned_layout/Understanding_z-index/Stacking_floating_elements): How floating elements are handled with stacking. -- [Using z-index](/en-US/docs/Web/CSS/CSS_positioned_layout/Understanding_z-index/Using_z-index): How to use `z-index` to change default stacking. -- [Stacking context](/en-US/docs/Web/CSS/CSS_positioned_layout/Understanding_z-index/Stacking_context): Notes on the stacking context. -- [Stacking context example 2](/en-US/docs/Web/CSS/CSS_positioned_layout/Understanding_z-index/Stacking_context_example_2): 2-level HTML hierarchy, `z-index` on all levels -- [Stacking context example 3](/en-US/docs/Web/CSS/CSS_positioned_layout/Understanding_z-index/Stacking_context_example_3): 3-level HTML hierarchy, `z-index` on the second level diff --git a/files/en-us/web/css/css_positioned_layout/understanding_z-index/stacking_context_example_2/index.md b/files/en-us/web/css/css_positioned_layout/understanding_z-index/stacking_context_example_2/index.md deleted file mode 100644 index 27da0371fe5fe77..000000000000000 --- a/files/en-us/web/css/css_positioned_layout/understanding_z-index/stacking_context_example_2/index.md +++ /dev/null @@ -1,129 +0,0 @@ ---- -title: Stacking context example 2 -slug: Web/CSS/CSS_positioned_layout/Understanding_z-index/Stacking_context_example_2 -page-type: guide ---- - -{{CSSRef}} - -## Description - -This is a very simple example, but it is the key for understanding the concept of _stacking context_. There are the same four DIVs of the previous example, but now `z-index` properties are assigned on both levels of the hierarchy. - -You can see that DIV #2 (`z-index`: 2) is above DIV #3 (`z-index`: 1), because they both belong to the same stacking context (the root one), so z-index values rule how elements are stacked. - -What can be considered strange is that DIV #2 (`z-index`: 2) is above DIV #4 (`z-index`: 10), despite their z-index values. The reason is that they do not belong to the same stacking context. DIV #4 belongs to the stacking context created by DIV #3, and as explained previously DIV #3 (and all its content) is under DIV #2. - -To better understand the situation, this is the stacking context hierarchy: - -- Root stacking context - - - DIV #2 (`z-index`: 2) - - DIV #3 (`z-index`: 1) - - - DIV #4 (`z-index`: 10) - -> [!NOTE] -> It is worth remembering that the HTML hierarchy is different from the stacking context hierarchy. In the stacking context hierarchy, elements that do not create a stacking context are collapsed on their parent. - -## Example - -### HTML - -```html -<div id="div1"> - <br /> - <span class="bold">DIV #1</span><br /> - position: relative; - <div id="div2"> - <br /> - <span class="bold">DIV #2</span><br /> - position: absolute;<br /> - z-index: 2; - </div> -</div> - -<br /> - -<div id="div3"> - <br /> - <span class="bold">DIV #3</span><br /> - position: relative;<br /> - z-index: 1; - <div id="div4"> - <br /> - <span class="bold">DIV #4</span><br /> - position: absolute;<br /> - z-index: 10; - </div> -</div> -``` - -### CSS - -```css -div { - font: 12px Arial; -} - -span.bold { - font-weight: bold; -} - -#div2 { - z-index: 2; -} -#div3 { - z-index: 1; -} -#div4 { - z-index: 10; -} - -#div1, -#div3 { - height: 80px; - position: relative; - border: 1px dashed #669966; - background-color: #ccffcc; - padding-left: 5px; -} - -#div2 { - opacity: 0.8; - position: absolute; - width: 150px; - height: 200px; - top: 20px; - left: 170px; - border: 1px dashed #990000; - background-color: #ffdddd; - text-align: center; -} - -#div4 { - opacity: 0.8; - position: absolute; - width: 200px; - height: 70px; - top: 65px; - left: 50px; - border: 1px dashed #000099; - background-color: #ddddff; - text-align: left; - padding-left: 10px; -} -``` - -## Result - -{{ EmbedLiveSample('Example', '352', '270') }} - -## See also - -- [Stacking without the `z-index` property](/en-US/docs/Web/CSS/CSS_positioned_layout/Understanding_z-index/Stacking_without_z-index): The stacking rules that apply when `z-index` is not used. -- [Stacking floating elements](/en-US/docs/Web/CSS/CSS_positioned_layout/Understanding_z-index/Stacking_floating_elements): How floating elements are handled with stacking. -- [Using z-index](/en-US/docs/Web/CSS/CSS_positioned_layout/Understanding_z-index/Using_z-index): How to use `z-index` to change default stacking. -- [Stacking context](/en-US/docs/Web/CSS/CSS_positioned_layout/Understanding_z-index/Stacking_context): Notes on the stacking context. -- [Stacking context example 1](/en-US/docs/Web/CSS/CSS_positioned_layout/Understanding_z-index/Stacking_context_example_1): 2-level HTML hierarchy, `z-index` on the last level -- [Stacking context example 3](/en-US/docs/Web/CSS/CSS_positioned_layout/Understanding_z-index/Stacking_context_example_3): 3-level HTML hierarchy, `z-index` on the second level diff --git a/files/en-us/web/css/css_positioned_layout/understanding_z-index/stacking_context_example_3/index.md b/files/en-us/web/css/css_positioned_layout/understanding_z-index/stacking_context_example_3/index.md deleted file mode 100644 index 155a36acc7225bb..000000000000000 --- a/files/en-us/web/css/css_positioned_layout/understanding_z-index/stacking_context_example_3/index.md +++ /dev/null @@ -1,169 +0,0 @@ ---- -title: Stacking context example 3 -slug: Web/CSS/CSS_positioned_layout/Understanding_z-index/Stacking_context_example_3 -page-type: guide ---- - -{{CSSRef}} - -## Description - -This last example shows problems that arise when mixing several positioned elements in a multi-level HTML hierarchy and when `z-index` values are assigned using class selectors. - -Let's take as an example a three-level hierarchical menu made from several positioned `div` elements. Second-level and third-level `div` elements appear when a user hovers or clicks on their parents. Usually this kind of menu is script-generated either client-side or server-side, so style rules are assigned with a class selector instead of the id selector. - -If the three menu levels partially overlap, then managing stacking could become a problem. - -The first-level menu is only relatively positioned, so no stacking context is created. - -The second-level menu is absolutely positioned inside the parent element. In order to put it above all first-level menus, the `z-index` property is used. The problem is that for each second-level menu, a stacking context is created and each third-level menu belongs to the context of its parent. - -So a third-level menu will be stacked under the following second-level menus, because all second-level menus share the same z-index value and the default stacking rules apply. - -To better understand the situation, here is the stacking context hierarchy (the three dots "..." represent multiple repetition of the previous line): - -- Root stacking context - - - LEVEL #1 - - - LEVEL #2 (`z-index`: 1) - - - LEVEL #3 - - … - - LEVEL #3 - - - LEVEL #2 (`z-index`: 1) - - … - - LEVEL #2 (`z-index`: 1) - - - LEVEL #1 - - … - - LEVEL #1 - -This problem can be avoided by removing overlapping between different level menus, or by using individual (and different) z-index values assigned through the id selector instead of class selector, or by flattening the HTML hierarchy. - -> [!NOTE] -> In the source code you will see that second-level and third level menus are made of several `div` elements contained in an absolutely positioned container. This is useful to group and position all of them at once. - -## Example - -### HTML - -```html -<div class="lev1"> - <span class="bold">LEVEL #1</span> - - <div id="container1"> - <div class="lev2"> - <br /><span class="bold">LEVEL #2</span> <br />z-index: 1; - - <div id="container2"> - <div class="lev3"><span class="bold">LEVEL #3</span></div> - <div class="lev3"><span class="bold">LEVEL #3</span></div> - <div class="lev3"><span class="bold">LEVEL #3</span></div> - <div class="lev3"><span class="bold">LEVEL #3</span></div> - <div class="lev3"><span class="bold">LEVEL #3</span></div> - <div class="lev3"><span class="bold">LEVEL #3</span></div> - <div class="lev3"><span class="bold">LEVEL #3</span></div> - <div class="lev3"><span class="bold">LEVEL #3</span></div> - <div class="lev3"><span class="bold">LEVEL #3</span></div> - <div class="lev3"><span class="bold">LEVEL #3</span></div> - <div class="lev3"><span class="bold">LEVEL #3</span></div> - </div> - </div> - - <div class="lev2"> - <br /><span class="bold">LEVEL #2</span> <br />z-index: 1; - </div> - <div class="lev2"> - <br /><span class="bold">LEVEL #2</span> <br />z-index: 1; - </div> - <div class="lev2"> - <br /><span class="bold">LEVEL #2</span> <br />z-index: 1; - </div> - </div> -</div> - -<div class="lev1"> - <span class="bold">LEVEL #1</span> -</div> - -<div class="lev1"> - <span class="bold">LEVEL #1</span> -</div> - -<div class="lev1"> - <span class="bold">LEVEL #1</span> -</div> -``` - -### CSS - -```css -div { - font: 12px Arial; -} - -span.bold { - font-weight: bold; -} - -div.lev1 { - width: 250px; - height: 70px; - position: relative; - border: 2px outset #669966; - background-color: #ccffcc; - padding-left: 5px; -} - -#container1 { - z-index: 1; - position: absolute; - top: 30px; - left: 75px; -} - -div.lev2 { - opacity: 0.9; - width: 200px; - height: 60px; - position: relative; - border: 2px outset #990000; - background-color: #ffdddd; - padding-left: 5px; -} - -#container2 { - z-index: 1; - position: absolute; - top: 20px; - left: 110px; -} - -div.lev3 { - z-index: 10; - width: 100px; - position: relative; - border: 2px outset #000099; - background-color: #ddddff; - padding-left: 5px; -} -``` - -## Result - -{{ EmbedLiveSample('Example', '320', '330') }} - -## See also - -- [Stacking without the `z-index` property](/en-US/docs/Web/CSS/CSS_positioned_layout/Understanding_z-index/Stacking_without_z-index): The stacking rules that apply when `z-index` is not used. -- [Stacking floating elements](/en-US/docs/Web/CSS/CSS_positioned_layout/Understanding_z-index/Stacking_floating_elements): How floating elements are handled with stacking. -- [Using z-index](/en-US/docs/Web/CSS/CSS_positioned_layout/Understanding_z-index/Using_z-index): How to use `z-index` to change default stacking. -- [Stacking context](/en-US/docs/Web/CSS/CSS_positioned_layout/Understanding_z-index/Stacking_context): Notes on the stacking context. -- [Stacking context example 1](/en-US/docs/Web/CSS/CSS_positioned_layout/Understanding_z-index/Stacking_context_example_1): 2-level HTML hierarchy, `z-index` on the last level -- [Stacking context example 2](/en-US/docs/Web/CSS/CSS_positioned_layout/Understanding_z-index/Stacking_context_example_2): 2-level HTML hierarchy, `z-index` on all levels - -> [!NOTE] -> The sample image looks wrong - with the second level 2 overlapping the level 3 menus - because level 2 has opacity, which creates a new stacking context. -> Basically, this whole sample page is incorrect and misleading. diff --git a/files/en-us/web/css/css_positioned_layout/understanding_z-index/stacking_floating_elements/index.md b/files/en-us/web/css/css_positioned_layout/understanding_z-index/stacking_floating_elements/index.md deleted file mode 100644 index cfc885c5de9d2f9..000000000000000 --- a/files/en-us/web/css/css_positioned_layout/understanding_z-index/stacking_floating_elements/index.md +++ /dev/null @@ -1,127 +0,0 @@ ---- -title: Stacking floating elements -slug: Web/CSS/CSS_positioned_layout/Understanding_z-index/Stacking_floating_elements -page-type: guide ---- - -{{CSSRef}} - -For floating elements, the stacking order is a bit different. Floating elements are placed between non-positioned elements and positioned elements: - -1. The background and borders of the root element. -2. Descendant non-positioned elements, in order of appearance in the HTML. -3. _Floating elements_. -4. Descendant positioned elements, in order of appearance in the HTML. - -See [types of positioning](/en-US/docs/Web/CSS/position#types_of_positioning) for an explanation of positioned and non-positioned elements. - -> [!NOTE] -> If an `opacity` value is applied to a non-positioned element (i.e., DIV #4 in the example below), something strange happens: the background and border of that block pop up above the floating blocks and the positioned blocks. This is due to a peculiar part of the specification: applying an `opacity` value creates a new stacking context (see [What No One Told You About Z-Index](https://philipwalton.com/articles/what-no-one-told-you-about-z-index/)). - -## Example - -You can see in this example that the background and border of the non-positioned element (DIV #4) is completely unaffected by floating elements, but the content is affected. This happens according to standard float behavior which can be shown with a rule added to the above list: - -1. The background and borders of the root element. -2. Descendant non-positioned elements, in order of appearance in the HTML. -3. Floating elements. -4. _Descendant non-positioned inline elements_. -5. Descendant positioned elements, in order of appearance in the HTML. - -### HTML - -```html -<div id="abs1"><strong>DIV #1</strong><br />position: absolute;</div> - -<div id="flo1"><strong>DIV #2</strong><br />float: left;</div> - -<div id="flo2"><strong>DIV #3</strong><br />float: right;</div> - -<br /> - -<div id="sta1"><strong>DIV #4</strong><br />no positioning</div> - -<div id="abs2"><strong>DIV #5</strong><br />position: absolute;</div> - -<div id="rel1"><strong>DIV #6</strong><br />position: relative;</div> -``` - -### CSS - -```css -div { - padding: 10px; - text-align: center; -} - -strong { - font-family: sans-serif; -} - -#abs1 { - position: absolute; - width: 150px; - height: 200px; - top: 10px; - right: 140px; - border: 1px dashed #900; - background-color: #fdd; -} - -#sta1 { - height: 100px; - border: 1px dashed #996; - background-color: #ffc; - margin: 0px 10px 0px 10px; - text-align: left; -} - -#flo1 { - margin: 0px 10px 0px 20px; - float: left; - width: 150px; - height: 200px; - border: 1px dashed #090; - background-color: #cfc; -} - -#flo2 { - margin: 0px 20px 0px 10px; - float: right; - width: 150px; - height: 200px; - border: 1px dashed #090; - background-color: #cfc; -} - -#abs2 { - position: absolute; - width: 150px; - height: 100px; - top: 80px; - left: 100px; - border: 1px dashed #990; - background-color: #fdd; -} - -#rel1 { - position: relative; - border: 1px dashed #996; - background-color: #cff; - margin: 0px 10px 0px 10px; - text-align: left; -} -``` - -## Result - -{{EmbedLiveSample("Example", 600, 250)}} - -## See also - -- [Stacking without the `z-index` property](/en-US/docs/Web/CSS/CSS_positioned_layout/Understanding_z-index/Stacking_without_z-index): The stacking rules that apply when `z-index` is not used. -- [Using z-index](/en-US/docs/Web/CSS/CSS_positioned_layout/Understanding_z-index/Using_z-index): How to use `z-index` to change default stacking. -- [Stacking context](/en-US/docs/Web/CSS/CSS_positioned_layout/Understanding_z-index/Stacking_context): Notes on the stacking context. -- [Stacking context example 1](/en-US/docs/Web/CSS/CSS_positioned_layout/Understanding_z-index/Stacking_context_example_1): 2-level HTML hierarchy, z-index on the last level -- [Stacking context example 2](/en-US/docs/Web/CSS/CSS_positioned_layout/Understanding_z-index/Stacking_context_example_2): 2-level HTML hierarchy, z-index on all levels -- [Stacking context example 3](/en-US/docs/Web/CSS/CSS_positioned_layout/Understanding_z-index/Stacking_context_example_3): 3-level HTML hierarchy, z-index on the second level diff --git a/files/en-us/web/css/css_positioned_layout/understanding_z-index/stacking_without_z-index/index.md b/files/en-us/web/css/css_positioned_layout/understanding_z-index/stacking_without_z-index/index.md deleted file mode 100644 index e8f49a6e130e1a7..000000000000000 --- a/files/en-us/web/css/css_positioned_layout/understanding_z-index/stacking_without_z-index/index.md +++ /dev/null @@ -1,118 +0,0 @@ ---- -title: Stacking without the z-index property -slug: Web/CSS/CSS_positioned_layout/Understanding_z-index/Stacking_without_z-index -page-type: guide ---- - -{{CSSRef}} - -When the {{cssxref("z-index")}} property is not specified on any element, elements are stacked in the following order (from bottom to top): - -1. The background and borders of the root element. -2. Descendant non-positioned elements, in order of appearance in the HTML. -3. Descendant positioned elements, in order of appearance in the HTML. - -See [types of positioning](/en-US/docs/Web/CSS/position#types_of_positioning) for an explanation of positioned and non-positioned elements. - -Keep in mind, when the {{cssxref("order")}} property alters rendering from the _order of appearance in the HTML_ within {{cssxref("flex")}} containers, it similarly affects the order for stacking context. - -## Example - -In this example, DIV #1 through DIV #4 are positioned elements. DIV #5 is static, and so is drawn below the other four elements, even though it comes later in the HTML markup. - -### HTML - -```html -<div id="abs1" class="absolute"> - <strong>DIV #1</strong><br />position: absolute; -</div> -<div id="rel1" class="relative"> - <strong>DIV #2</strong><br />position: relative; -</div> -<div id="rel2" class="relative"> - <strong>DIV #3</strong><br />position: relative; -</div> -<div id="abs2" class="absolute"> - <strong>DIV #4</strong><br />position: absolute; -</div> -<div id="sta1" class="static"> - <strong>DIV #5</strong><br />position: static; -</div> -``` - -### CSS - -```css -strong { - font-family: sans-serif; -} - -div { - padding: 10px; - border: 1px dashed; - text-align: center; -} - -.static { - position: static; - height: 80px; - background-color: #ffc; - border-color: #996; -} - -.absolute { - position: absolute; - width: 150px; - height: 350px; - background-color: #fdd; - border-color: #900; - opacity: 0.7; -} - -.relative { - position: relative; - height: 80px; - background-color: #cfc; - border-color: #696; - opacity: 0.7; -} - -#abs1 { - top: 10px; - left: 10px; -} - -#rel1 { - top: 30px; - margin: 0px 50px 0px 50px; -} - -#rel2 { - top: 15px; - left: 20px; - margin: 0px 50px 0px 50px; -} - -#abs2 { - top: 10px; - right: 10px; -} - -#sta1 { - background-color: #ffc; - margin: 0px 50px 0px 50px; -} -``` - -## Result - -{{EmbedLiveSample("Example", 600, 400)}} - -## See also - -- [Stacking floating elements](/en-US/docs/Web/CSS/CSS_positioned_layout/Understanding_z-index/Stacking_floating_elements): How floating elements are handled with stacking. -- [Using z-index](/en-US/docs/Web/CSS/CSS_positioned_layout/Understanding_z-index/Using_z-index): How to use `z-index` to change default stacking. -- [Stacking context](/en-US/docs/Web/CSS/CSS_positioned_layout/Understanding_z-index/Stacking_context): Notes on the stacking context. -- [Stacking context example 1](/en-US/docs/Web/CSS/CSS_positioned_layout/Understanding_z-index/Stacking_context_example_1): 2-level HTML hierarchy, z-index on the last level -- [Stacking context example 2](/en-US/docs/Web/CSS/CSS_positioned_layout/Understanding_z-index/Stacking_context_example_2): 2-level HTML hierarchy, z-index on all levels -- [Stacking context example 3](/en-US/docs/Web/CSS/CSS_positioned_layout/Understanding_z-index/Stacking_context_example_3): 3-level HTML hierarchy, z-index on the second level diff --git a/files/en-us/web/css/css_positioned_layout/understanding_z-index/using_z-index/index.md b/files/en-us/web/css/css_positioned_layout/understanding_z-index/using_z-index/index.md deleted file mode 100644 index 856a2f6a33922d8..000000000000000 --- a/files/en-us/web/css/css_positioned_layout/understanding_z-index/using_z-index/index.md +++ /dev/null @@ -1,135 +0,0 @@ ---- -title: Using z-index -slug: Web/CSS/CSS_positioned_layout/Understanding_z-index/Using_z-index -page-type: guide ---- - -{{CSSRef}} - -The first article of this guide, [Stacking without the `z-index` property](/en-US/docs/Web/CSS/CSS_positioned_layout/Understanding_z-index/Stacking_without_z-index), explains how stacking is arranged by default. If you want to create a custom stacking order, you can use the {{cssxref("z-index")}} property on a [positioned](/en-US/docs/Web/CSS/position#types_of_positioning) element. - -The `z-index` property can be specified with an integer value (positive, zero, or negative), which represents the position of the element along an imaginary z-axis. If you are not familiar with the term 'z-axis', imagine the page as a stack of layers, each one having a number. Layers are rendered in numerical order, with larger numbers above smaller numbers (_X_ represents an arbitrary positive integer): - -| Layer | Description | -| ------------ | ------------------------------------- | -| Bottom layer | Farthest from the observer | -| Layer -X | Layers with negative `z-index` values | -| Layer 0 | Default rendering layer | -| Layer X | Layers with positive `z-index` values | -| Top layer | Closest to the observer | - -> [!NOTE] -> -> - When no `z-index` property is specified, elements are rendered on the default rendering layer (Layer 0). -> - If several elements share the same `z-index` value (i.e., they are placed on the same layer), stacking rules explained in the section [Stacking without the `z-index` property](/en-US/docs/Web/CSS/CSS_positioned_layout/Understanding_z-index/Stacking_without_z-index) apply. - -## Example - -In this example, the layers' stacking order is rearranged using `z-index`. The `z-index` of DIV #5 has no effect since it is not a positioned element. - -### HTML - -```html -<div id="abs1"> - <strong>DIV #1</strong> - <br />position: absolute; <br />z-index: 5; -</div> - -<div id="rel1"> - <strong>DIV #2</strong> - <br />position: relative; <br />z-index: 3; -</div> - -<div id="rel2"> - <strong>DIV #3</strong> - <br />position: relative; <br />z-index: 2; -</div> - -<div id="abs2"> - <strong>DIV #4</strong> - <br />position: absolute; <br />z-index: 1; -</div> - -<div id="sta1"> - <strong>DIV #5</strong> - <br />no positioning <br />z-index: 8; -</div> -``` - -### CSS - -```css -div { - padding: 10px; - opacity: 0.7; - text-align: center; -} - -strong { - font-family: sans-serif; -} - -#abs1 { - z-index: 5; - position: absolute; - width: 150px; - height: 350px; - top: 10px; - left: 10px; - border: 1px dashed #900; - background-color: #fdd; -} - -#rel1 { - z-index: 3; - height: 100px; - position: relative; - top: 30px; - border: 1px dashed #696; - background-color: #cfc; - margin: 0px 50px 0px 50px; -} - -#rel2 { - z-index: 2; - height: 100px; - position: relative; - top: 15px; - left: 20px; - border: 1px dashed #696; - background-color: #cfc; - margin: 0px 50px 0px 50px; -} - -#abs2 { - z-index: 1; - position: absolute; - width: 150px; - height: 350px; - top: 10px; - right: 10px; - border: 1px dashed #900; - background-color: #fdd; -} - -#sta1 { - z-index: 8; - height: 70px; - border: 1px dashed #996; - background-color: #ffc; - margin: 0px 50px 0px 50px; -} -``` - -## Result - -{{EmbedLiveSample("Example", 600, 400)}} - -## See also - -- [Stacking without the `z-index` property](/en-US/docs/Web/CSS/CSS_positioned_layout/Understanding_z-index/Stacking_without_z-index): The stacking rules that apply when `z-index` is not used. -- [Stacking floating elements](/en-US/docs/Web/CSS/CSS_positioned_layout/Understanding_z-index/Stacking_floating_elements): How floating elements are handled with stacking. -- [Stacking context](/en-US/docs/Web/CSS/CSS_positioned_layout/Understanding_z-index/Stacking_context): Notes on the stacking context. -- [Stacking context example 1](/en-US/docs/Web/CSS/CSS_positioned_layout/Understanding_z-index/Stacking_context_example_1): 2-level HTML hierarchy, z-index on the last level -- [Stacking context example 2](/en-US/docs/Web/CSS/CSS_positioned_layout/Understanding_z-index/Stacking_context_example_2): 2-level HTML hierarchy, z-index on all levels -- [Stacking context example 3](/en-US/docs/Web/CSS/CSS_positioned_layout/Understanding_z-index/Stacking_context_example_3): 3-level HTML hierarchy, z-index on the second level diff --git a/files/en-us/web/css/css_positioned_layout/using_z-index/index.md b/files/en-us/web/css/css_positioned_layout/using_z-index/index.md new file mode 100644 index 000000000000000..8e247a72eb87ae4 --- /dev/null +++ b/files/en-us/web/css/css_positioned_layout/using_z-index/index.md @@ -0,0 +1,134 @@ +--- +title: Using z-index +slug: Web/CSS/CSS_positioned_layout/Using_z-index +page-type: guide +--- + +{{CSSRef}} + +The first article of this guide, [Stacking without the `z-index` property](/en-US/docs/Web/CSS/CSS_positioned_layout/Stacking_without_z-index), explains how stacking is arranged by default. If you want to create a custom stacking order, you can use the {{cssxref("z-index")}} property on a [positioned](/en-US/docs/Web/CSS/position#types_of_positioning) element. + +The `z-index` property can be specified with an integer value (positive, zero, or negative), which represents the position of the element along an imaginary z-axis. If you are not familiar with the term 'z-axis', imagine the page as a stack of layers, each one having a number. Layers are rendered in numerical order, with larger numbers above smaller numbers (_X_ represents an arbitrary positive integer): + +| Layer | Description | +| ------------ | ------------------------------------- | +| Bottom layer | Farthest from the observer | +| Layer -X | Layers with negative `z-index` values | +| Layer 0 | Default rendering layer | +| Layer X | Layers with positive `z-index` values | +| Top layer | Closest to the observer | + +> [!NOTE] +> +> - When no `z-index` property is specified, elements are rendered on the default rendering layer (Layer 0). +> - If several elements share the same `z-index` value (i.e., they are placed on the same layer), stacking rules explained in the section [Stacking without the `z-index` property](/en-US/docs/Web/CSS/CSS_positioned_layout/Stacking_without_z-index) apply. + +## Example + +In this example, the layers' stacking order is rearranged using `z-index`. The `z-index` of DIV #5 has no effect since it is not a positioned element. + +### HTML + +```html +<div id="abs1"> + <strong>DIV #1</strong> + <br />position: absolute; <br />z-index: 5; +</div> + +<div id="rel1"> + <strong>DIV #2</strong> + <br />position: relative; <br />z-index: 3; +</div> + +<div id="rel2"> + <strong>DIV #3</strong> + <br />position: relative; <br />z-index: 2; +</div> + +<div id="abs2"> + <strong>DIV #4</strong> + <br />position: absolute; <br />z-index: 1; +</div> + +<div id="sta1"> + <strong>DIV #5</strong> + <br />no positioning <br />z-index: 8; +</div> +``` + +### CSS + +```css +div { + padding: 10px; + opacity: 0.7; + text-align: center; +} + +strong { + font-family: sans-serif; +} + +#abs1 { + z-index: 5; + position: absolute; + width: 150px; + height: 350px; + top: 10px; + left: 10px; + border: 1px dashed #900; + background-color: #fdd; +} + +#rel1 { + z-index: 3; + height: 100px; + position: relative; + top: 30px; + border: 1px dashed #696; + background-color: #cfc; + margin: 0px 50px 0px 50px; +} + +#rel2 { + z-index: 2; + height: 100px; + position: relative; + top: 15px; + left: 20px; + border: 1px dashed #696; + background-color: #cfc; + margin: 0px 50px 0px 50px; +} + +#abs2 { + z-index: 1; + position: absolute; + width: 150px; + height: 350px; + top: 10px; + right: 10px; + border: 1px dashed #900; + background-color: #fdd; +} + +#sta1 { + z-index: 8; + height: 70px; + border: 1px dashed #996; + background-color: #ffc; + margin: 0px 50px 0px 50px; +} +``` + +## Result + +{{EmbedLiveSample("Example", 600, 400)}} + +## See also + +- [Understanding z-index](/en-US/docs/Web/CSS/CSS_positioned_layout/Understanding_z-index) +- [Stacking context](/en-US/docs/Web/CSS/CSS_positioned_layout/Stacking_context) +- [Stacking floating elements](/en-US/docs/Web/CSS/CSS_positioned_layout/Stacking_floating_elements) +- [Stacking without `z-index`](/en-US/docs/Web/CSS/CSS_positioned_layout/Stacking_without_z-index) +- [CSS positioned layout](/en-US/docs/Web/CSS/CSS_positioned_layout) module diff --git a/files/en-us/web/css/css_properties_and_values_api/houdini/index.md b/files/en-us/web/css/css_properties_and_values_api/houdini/index.md new file mode 100644 index 000000000000000..e7e71e97ad8d867 --- /dev/null +++ b/files/en-us/web/css/css_properties_and_values_api/houdini/index.md @@ -0,0 +1,73 @@ +--- +title: CSS Houdini +slug: Web/CSS/CSS_properties_and_values_API/Houdini +page-type: guide +status: + - experimental +--- + +{{CSSRef}} + +**CSS Houdini** is a set of APIs that expose parts of the CSS engine. This makes it easier for developers to create extensions for CSS. These extensions might be to polyfill features that are not yet available in a browser, experiment with new ways of doing layout, or add creative borders or other effects. + +While many Houdini examples showcase the creative possibilities of the APIs, there are many practical use cases. For example, you can use Houdini to create advanced custom properties with type checking and default values. + +## Basic example + +A regular [CSS custom property](/en-US/docs/Web/CSS/--*) consists of a property name and a value. Therefore I might create a custom property called `--background-color` and expect it to be given a color value. The value is then used in the CSS as if it were the color value. + +```css +:root { + --background-color: blue; +} + +.box { + background-color: var(--background-color); +} +``` + +In the above example however, there is nothing to stop someone using some other value for this property, perhaps setting it to a length. Having done so, anywhere that the property is used would have no background color as `background-color: 12px` is not valid. When browsers come across CSS they don't recognize as valid they throw that line away. + +Using {{cssxref("@property")}} however, we can declare the custom property with a {{CSSxRef("@property/syntax","syntax")}} of `<color>`. This shows that we need this property to have a value which is a valid color. + +```css +@property --background-color { + syntax: "<color>"; + inherits: false; + initial-value: blue; +} +``` + +## Houdini worklets + +A feature of Houdini is the {{domxref("Worklet")}}. A worklet is a module, written in JavaScript, that extends CSS using one of the Houdini APIs. You can see an example worklet on the {{domxref("PaintWorkletGlobalScope.registerPaint()")}} page. Once a worklet has been registered you can use it in CSS just like any other value. This means that even if you are not a JavaScript developer, you can access Houdini APIs by using worklets other people have created. + +## Reference + +### CSS at-rule and descriptors + +The {{CSSxRef("@property")}} at-rule allows you to register an advanced custom property. + +- {{CSSxRef("@property")}} +- {{CSSxRef("@property/inherits","inherits")}} +- {{CSSxRef("@property/initial-value","initial-value")}} +- {{CSSxRef("@property/syntax","syntax")}} + +### Houdini API references + +- [CSS Properties and Values API](/en-US/docs/Web/API/CSS_Properties_and_Values_API) +- [CSS Typed Object Model API](/en-US/docs/Web/API/CSS_Typed_OM_API) +- [CSS Painting API](/en-US/docs/Web/API/CSS_Painting_API) +- {{domxref("Worklet")}} reference + +### Houdini guides + +- [Properties and Values API Guide](/en-US/docs/Web/API/CSS_Properties_and_Values_API/guide) +- [Typed OM API Guide](/en-US/docs/Web/API/CSS_Typed_OM_API/Guide) +- [Using the CSS Painting API](/en-US/docs/Web/API/CSS_Painting_API/Guide) + +## External resources + +- [Interactive introduction to Houdini](https://houdini.glitch.me/) +- [A Practical Overview of CSS Houdini](https://www.smashingmagazine.com/2020/03/practical-overview-css-houdini/) +- [Smarter custom properties with Houdini's new API](https://web.dev/articles/css-props-and-vals) diff --git a/files/en-us/web/css/css_properties_and_values_api/index.md b/files/en-us/web/css/css_properties_and_values_api/index.md index e2b2b55123562d9..1dd120d88979bd7 100644 --- a/files/en-us/web/css/css_properties_and_values_api/index.md +++ b/files/en-us/web/css/css_properties_and_values_api/index.md @@ -9,7 +9,7 @@ spec-urls: https://www.w3.org/TR/css-properties-values-api-1/ The **CSS properties and values API** module defines a method for registering new CSS properties, defining the property's data type, inheritance behavior, and, optionally, an initial value. This API expands on [CSS custom properties for cascading variables](/en-US/docs/Web/CSS/CSS_cascading_variables) module, which allows authors to define custom properties in CSS using [two dash syntax (`--`)](/en-US/docs/Web/CSS/--*). -The CSS properties and values API is part of the [CSS Houdini](/en-US/docs/Web/CSS/CSS_Houdini) umbrella of APIs. +The CSS properties and values API is part of the [CSS Houdini](/en-US/docs/Web/API/Houdini_APIs) umbrella of APIs. Custom properties let you reuse values across a project to simplify complex or repetitive stylesheets. Basic custom properties are defined in the [CSS custom properties for cascading variables](/en-US/docs/Web/CSS/CSS_cascading_variables) module. @@ -81,9 +81,9 @@ The value of `--stop-color` is set to `cornflowerblue` at first, but when you ho ## Guides - [Using the CSS properties and values API](/en-US/docs/Web/API/CSS_Properties_and_Values_API/guide) - - : Explains how to register custom properties in CSS and JavaScript, with hints on handling undefined and invalid values, fallbacks, and inheritance. - +- [CSS Houdini](/en-US/docs/Web/CSS/CSS_properties_and_values_API/Houdini) + - : Reference guide to Houdini resources including the CSS modules, API guides, and external resources. - [Houdini APIs](/en-US/docs/Web/API/Houdini_APIs) - : Explains what CSS Houdini is and its advantages, along with a list of available APIs and their statuses. diff --git a/files/en-us/web/css/css_pseudo-elements/index.md b/files/en-us/web/css/css_pseudo-elements/index.md index 846dc93b327404b..a37327d0fc8b70f 100644 --- a/files/en-us/web/css/css_pseudo-elements/index.md +++ b/files/en-us/web/css/css_pseudo-elements/index.md @@ -65,6 +65,17 @@ The specification also defines the `::details-content` and `::search-text` pseud - {{cssxref("::cue")}} - {{cssxref("::cue", "::cue()")}} +- [CSS multi-column layout](/en-US/docs/Web/CSS/CSS_multicol_layout) module + + - {{cssxref("::column")}} + +- [CSS overflow](/en-US/docs/Web/CSS/CSS_overflow) module + + - {{cssxref("::scroll-button()")}} + - {{cssxref("::scroll-marker")}} + - {{cssxref("::scroll-marker-group")}} + - {{cssxref(":target-current")}} + - [CSS scoping](/en-US/docs/Web/CSS/CSS_scoping) module - {{CSSXref(":host")}} @@ -94,7 +105,7 @@ The specification also defines the `::details-content` and `::search-text` pseud - [Pseudo-classes](/en-US/docs/Web/CSS/Pseudo-classes) - [Universal selectors](/en-US/docs/Web/CSS/Universal_selectors) -- [`placeholder`](/en-US/docs/Web/HTML/Element/input#placeholder) attribute of the `<input>` element +- [`placeholder`](/en-US/docs/Web/HTML/Reference/Elements/input#placeholder) attribute of the `<input>` element - [`:placeholder-shown`](/en-US/docs/Web/CSS/:placeholder-shown) selector - [CSS generated content](/en-US/docs/Web/CSS/CSS_generated_content) diff --git a/files/en-us/web/css/css_ruby_layout/index.md b/files/en-us/web/css/css_ruby_layout/index.md index 56e0861d4d6c663..004cd58affcf162 100644 --- a/files/en-us/web/css/css_ruby_layout/index.md +++ b/files/en-us/web/css/css_ruby_layout/index.md @@ -35,15 +35,15 @@ The CSS ruby layout module adds the following values to the {{cssxref("display") ## Related concepts -- [CSS display](/en-US/docs/Web/CSS/CSS_Display) module +- [CSS display](/en-US/docs/Web/CSS/CSS_display) module - {{cssxref("display")}} - {{CSSxRef("&lt;display-internal&gt;")}} -- [CSS text decoration](/en-US/docs/Web/CSS/CSS_Text_Decoration) module +- [CSS text decoration](/en-US/docs/Web/CSS/CSS_text_decoration) module - {{cssxref("text-emphasis-color")}} - {{cssxref("text-emphasis-position")}} - {{cssxref("text-emphasis-style")}} - {{cssxref("text-emphasis")}} shorthand -- [HTML elements](/en-US/docs/Web/HTML/Element) +- [HTML elements](/en-US/docs/Web/HTML/Reference/Elements) - {{HTMLElement("rb")}} - {{HTMLElement("rp")}} - {{HTMLElement("rt")}} @@ -60,4 +60,4 @@ The CSS ruby layout module adds the following values to the {{cssxref("display") - {{cssxref("unicode-bidi")}} - {{cssxref("font-variant-east-asian")}} - {{cssxref(":lang()")}} -- HTML [`lang`](/en-US/docs/Web/HTML/Global_attributes/lang) attribute +- HTML [`lang`](/en-US/docs/Web/HTML/Reference/Global_attributes/lang) attribute diff --git a/files/en-us/web/css/css_scoping/index.md b/files/en-us/web/css/css_scoping/index.md index 4b01d0eb53bde5d..692357790abb769 100644 --- a/files/en-us/web/css/css_scoping/index.md +++ b/files/en-us/web/css/css_scoping/index.md @@ -52,7 +52,7 @@ Sometimes it's useful to be able to style a host from inside the shadow tree con - HTML {{HTMLElement("template")}} element - HTML {{HTMLElement("slot")}} element -- HTML [`slot`](/en-US/docs/Web/HTML/Global_attributes/slot) attribute +- HTML [`slot`](/en-US/docs/Web/HTML/Reference/Global_attributes/slot) attribute - {{Glossary("Shadow tree")}} glossary term - {{Glossary("DOM")}} glossary term diff --git a/files/en-us/web/css/css_scroll-driven_animations/index.md b/files/en-us/web/css/css_scroll-driven_animations/index.md index 7039eb9d80076e0..f2437a3e85e9e18 100644 --- a/files/en-us/web/css/css_scroll-driven_animations/index.md +++ b/files/en-us/web/css/css_scroll-driven_animations/index.md @@ -62,7 +62,7 @@ CSS scroll-driven animations adds the ability to include `<timeline-range-name>` ### Functions -Possible values of the {{cssxref("animation-timeline")}} property for defining _anonymous scroll progress timelines_ and _anonymous view progress timelines_ (i.e. implicitly defined by the browser rather than being explicitly named and defined using the `scroll-timeline-*` and `view-timeline-*` properties): +Possible values of the {{cssxref("animation-timeline")}} property for defining _anonymous scroll progress timelines_ and _anonymous view progress timelines_ (i.e., implicitly defined by the browser rather than being explicitly named and defined using the `scroll-timeline-*` and `view-timeline-*` properties): - [`scroll()`](/en-US/docs/Web/CSS/animation-timeline/scroll) - [`view()`](/en-US/docs/Web/CSS/animation-timeline/view) diff --git a/files/en-us/web/css/css_scroll_anchoring/index.md b/files/en-us/web/css/css_scroll_anchoring/index.md new file mode 100644 index 000000000000000..0609e1d6f10763c --- /dev/null +++ b/files/en-us/web/css/css_scroll_anchoring/index.md @@ -0,0 +1,44 @@ +--- +title: CSS scroll anchoring +slug: Web/CSS/CSS_scroll_anchoring +page-type: css-module +spec-urls: https://drafts.csswg.org/css-scroll-anchoring/ +--- + +{{CSSRef}} + +The **CSS scroll anchoring** module defines a mechanism to prevent page movement due to DOM changes above the visible region of a scrolling box while the user is consuming the visible content. + +Scroll anchoring attempts to keep the user's view of the document stable across layout changes. It works by selecting a DOM node (the anchor node) whose movement is used to determine adjustments to the scroll position. The anchor node is always a descendant of the scrolling box. + +For scroll containers that are [snapped](/en-US/docs/Glossary/Scroll_snap) to an element, scroll anchoring is limited to adjustments that would be allowed by re-snapping. + +## Reference + +### Properties + +- {{cssxref("overflow-anchor")}} + +## Glossary and definitions + +- {{glossary("Scroll container")}} +- {{glossary("Scroll snap")}} + +## Guides + +- [Understanding scroll anchoring](/en-US/docs/Web/CSS/CSS_scroll_anchoring/Scroll_anchoring) + - : What is scroll anchoring, suppression triggers, and when and how to enable and disable this browser feature. + +## Related concepts + +- {{CSSxRef("overscroll-behavior")}} + +## Specifications + +{{Specifications}} + +## See also + +- [CSS overflow](/en-US/docs/Web/CSS/CSS_overflow) module +- [CSS scroll snap](/en-US/docs/Web/CSS/CSS_scroll_snap) module +- [CSS overscroll behavior](/en-US/docs/Web/CSS/CSS_overscroll_behavior) module diff --git a/files/en-us/web/css/css_scroll_anchoring/scroll_anchoring/index.md b/files/en-us/web/css/css_scroll_anchoring/scroll_anchoring/index.md new file mode 100644 index 000000000000000..5806336b79887d7 --- /dev/null +++ b/files/en-us/web/css/css_scroll_anchoring/scroll_anchoring/index.md @@ -0,0 +1,83 @@ +--- +title: Understanding scroll anchoring +slug: Web/CSS/CSS_scroll_anchoring/Scroll_anchoring +page-type: guide +browser-compat: css.properties.overflow-anchor +--- + +{{CSSRef}} + +As a user of the web, you are probably familiar with the problem that scroll anchoring solves. You browse to a long page on a slow connection and begin to scroll to read the content; while you are busy reading, the part of the page you are looking at suddenly jumps. This has happened because large images or some other elements have just loaded further up in the content. + +Scroll anchoring is a browser feature that aims to solve this problem of content jumping, which happens if content loads in after the user has already scrolled to a new part of the document. + +## How does it work? + +Scroll anchoring adjusts the scroll position to compensate for the changes outside of the viewport. This means that the point in the document the user is looking at remains in the viewport, which may mean their scroll position actually changes in terms of how _far_ they have moved through the document. + +## How do I turn on scroll anchoring? + +You don't! The feature is enabled by default in supporting browsers. In most cases anchored scrolling is exactly what you want — content jumping is a poor experience for anyone. + +## What if I need to debug it? + +If your page is not behaving well with scroll anchoring enabled, it is probably because some `scroll` event listener is not handling the extra scrolling to compensate for the anchor node movement. + +You can check whether disabling scroll anchoring fixes the issue in Firefox by changing `layout.css.scroll-anchoring.enabled` to `false` in `about:config`. You can also check what node Firefox is using as the anchor using the `layout.css.scroll-anchoring.highlight` switch. That will show a purple overlay on top of the anchor node. + +If a node doesn't seem to be an appropriate anchor, you can exclude it using {{cssxref("overflow-anchor")}}, as described below. + +## What if I need to disable it? + +The [CSS scroll anchoring module](/en-US/docs/Web/CSS/CSS_scroll_anchoring) provides the {{cssxref("overflow-anchor")}} property, which can be used to disable scroll anchoring on all or part of the document. It's essentially a way to opt out of the behavior. + +The only possible values are `auto` or `none`: + +- `auto` is the initial value; as long as the user's browser supports scroll anchoring, the behavior will happen, and they should see fewer content jumps. +- `none` means that you have explicitly opted the document, or part of the document, out of scroll anchoring. + +To opt out the entire document, you can set it on the {{htmlelement("body")}} element: + +```css +body { + overflow-anchor: none; +} +``` + +To opt out of scroll anchoring for a section of the document, set `overflow-anchor: none` on the section's container element: + +```css +.container { + overflow-anchor: none; +} +``` + +If opting out of scroll anchoring on the document or a section thereof, a descendant of an opted-out area cannot be opted back in. For example, if you opt out the entire document, you can't set `overflow-anchor: auto` on a descendant node to turn scroll anchoring back on for a subsection. + +### Suppression triggers + +There are some _suppression triggers_, which disable scroll anchoring in places where it might be problematic. If any of the triggers happen on the anchor node, or an ancestor of it, anchoring is suppressed. + +These suppression triggers are changes to the computed value of any of the following properties: + +- {{cssxref("top")}}, {{cssxref("left")}}, {{cssxref("right")}}, or {{cssxref("bottom")}} +- {{cssxref("margin")}} or {{cssxref("padding")}} +- Any {{cssxref("width")}} or {{cssxref("height")}}-related properties +- {{cssxref("transform")}} and the individual transform properties {{cssxref("translate")}}, {{cssxref("scale")}}, and {{cssxref("rotate")}} + +Additionally, {{cssxref("position")}} changes anywhere inside the {{glossary("scroll container")}} also disable scroll anchoring. + +## Specifications + +{{Specifications}} + +## Browser compatibility + +{{Compat}} + +To conditionally apply styles based on whether scroll anchoring can be disabled, use [`@supports` feature queries](/en-US/docs/Web/CSS/@supports) to test support for the `overflow-anchor` property. + +## See also + +- [Original scroll anchoring explainer](https://github.com/WICG/ScrollAnchoring/blob/master/explainer.md) via WICG (2016) +- [Scroll anchoring for web developers](https://blog.chromium.org/2017/04/scroll-anchoring-for-web-developers.html) via Chromium (2017) diff --git a/files/en-us/web/css/css_scroll_snap/index.md b/files/en-us/web/css/css_scroll_snap/index.md index e8967fdeec91990..3a5266b47ada35a 100644 --- a/files/en-us/web/css/css_scroll_snap/index.md +++ b/files/en-us/web/css/css_scroll_snap/index.md @@ -308,7 +308,7 @@ To compare scroll snapping to regular scrolling, check the "disable snapping" ch - Element {{domxref("Element.scrollTo", "scrollTo()")}} method - Element {{domxref("Element.scroll_event", "scroll")}} event - Element {{domxref("Element.scrollend_event", "scrollend")}} event -- [`scrollbar`](/en-US/docs/Web/Accessibility/ARIA/Roles/scrollbar_role) ARIA role +- [`scrollbar`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/scrollbar_role) ARIA role - {{Glossary("Scroll container")}} glossary term ## Specifications @@ -319,6 +319,7 @@ To compare scroll snapping to regular scrolling, check the "disable snapping" ch - [CSS overflow](/en-US/docs/Web/CSS/CSS_overflow) module - [CSS scrollbars styling](/en-US/docs/Web/CSS/CSS_scrollbars_styling) module +- [CSS scroll anchoring](/en-US/docs/Web/CSS/CSS_scroll_anchoring) module - [Keyboard-only scrolling areas](https://adrianroselli.com/2022/06/keyboard-only-scrolling-areas.html) on adrianroselli.com (2022) - [Scroll snap examples](https://codepen.io/collection/KpqBGW) on CodePen (2022) - [Well-controlled scrolling with CSS scroll snap](https://web.dev/articles/css-scroll-snap) on web.dev (2021) diff --git a/files/en-us/web/css/css_scroll_snap/using_scroll_snap_events/index.md b/files/en-us/web/css/css_scroll_snap/using_scroll_snap_events/index.md index 343e9deac830fa1..f6dd544f118715a 100644 --- a/files/en-us/web/css/css_scroll_snap/using_scroll_snap_events/index.md +++ b/files/en-us/web/css/css_scroll_snap/using_scroll_snap_events/index.md @@ -197,7 +197,7 @@ The style changes mentioned above will be applied through classes applied to the ### JavaScript -In the JavaScript, we start by grabbing a reference to the `<main>` element and defining the number of `<section>` elements to generate (in this case, 21) and a variable to begin counting from. We then use a [`while`](/en-US/docs/Web/JavaScript/Reference/Statements/while) loop to generate the `<section>` elements, giving each one a child [`h2`](/en-US/docs/Web/HTML/Element/Heading_Elements) with text that reads `Section` plus the current value of `n`. +In the JavaScript, we start by grabbing a reference to the `<main>` element and defining the number of `<section>` elements to generate (in this case, 21) and a variable to begin counting from. We then use a [`while`](/en-US/docs/Web/JavaScript/Reference/Statements/while) loop to generate the `<section>` elements, giving each one a child [`h2`](/en-US/docs/Web/HTML/Reference/Elements/Heading_Elements) with text that reads `Section` plus the current value of `n`. ```js const mainElem = document.querySelector("main"); @@ -214,7 +214,7 @@ while (n <= sectionCount) { } ``` -Now on to the {{domxref("Element/scrollsnapchanging_event", "scrollsnapchanging")}} event handler function. When a child of the `<main>` element (i.e. any `<section>` element) becomes a pending snap target selection, we: +Now on to the {{domxref("Element/scrollsnapchanging_event", "scrollsnapchanging")}} event handler function. When a child of the `<main>` element (i.e., any `<section>` element) becomes a pending snap target selection, we: 1. Check to see if an element previously had the `pending` class applied and, if so, remove it. This is so that only the current pending target is given the `pending` class and colored darker gray. We don't want previously-pending targets that are no longer pending to keep the styling. 2. Give the element referenced by the {{domxref("SnapEvent.snapTargetBlock", "snapTargetBlock")}} property (which will be one of the `<section>` elements) the `pending` class so it turns a darker gray. @@ -235,7 +235,7 @@ mainElem.addEventListener("scrollsnapchanging", (event) => { When a scrolling gesture ends, and a `<section>` element is actually selected as a snap target, the {{domxref("Element/scrollsnapchange_event", "scrollsnapchange")}} event handler function fires. This: -1. Checks to see if a snap target was previously selected — i.e. if a `select-section` class was previously applied to an element. If so, we remove it. +1. Checks to see if a snap target was previously selected — i.e., if a `select-section` class was previously applied to an element. If so, we remove it. 2. Applies the `select-section` class to the `<section>` element referenced in the `snapTargetBlock` property so that the snap target that was just selected will have the selection animation applied to it. ```js diff --git a/files/en-us/web/css/css_scrollbars_styling/index.md b/files/en-us/web/css/css_scrollbars_styling/index.md index b521e3ac4b1ce69..2e2bd490bb6eb9b 100644 --- a/files/en-us/web/css/css_scrollbars_styling/index.md +++ b/files/en-us/web/css/css_scrollbars_styling/index.md @@ -85,7 +85,7 @@ for us to breathe. - {{cssxref("scroll-snap-type")}} CSS property - {{CSSxRef("::-webkit-scrollbar")}} pseudo-element - {{glossary("scroll container")}} glossary term -- [`scrollbar`](/en-US/docs/Web/Accessibility/ARIA/Roles/scrollbar_role) ARIA role +- [`scrollbar`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/scrollbar_role) ARIA role ## Specifications diff --git a/files/en-us/web/css/css_selectors/index.md b/files/en-us/web/css/css_selectors/index.md index 172ec40fa010a4f..08c7f1d0456760a 100644 --- a/files/en-us/web/css/css_selectors/index.md +++ b/files/en-us/web/css/css_selectors/index.md @@ -23,6 +23,7 @@ Selectors, whether used in CSS or JavaScript, enable targeting HTML elements bas - `~` ([Subsequent sibling combinator](/en-US/docs/Web/CSS/Subsequent-sibling_combinator)) - " " ([Descendant combinator](/en-US/docs/Web/CSS/Descendant_combinator)) - `|` ([Namespace separator](/en-US/docs/Web/CSS/Namespace_separator)) +- `,` ([Selector list](/en-US/docs/Web/CSS/Selector_list)) ### Selectors @@ -33,7 +34,6 @@ Selectors, whether used in CSS or JavaScript, enable targeting HTML elements bas - {{CSSXref(":buffering")}} - {{CSSXref(":checked")}} - {{CSSXref(":current")}} -- {{CSSXref(":current", ":current()")}} - {{CSSXref(":default")}} - {{CSSXref(":defined")}} - {{CSSXref(":dir", ":dir()")}} @@ -49,8 +49,8 @@ Selectors, whether used in CSS or JavaScript, enable targeting HTML elements bas - {{CSSXref(":future")}} - {{CSSXref(":has", ":has()")}} - {{CSSXref(":hover")}} -- {{CSSXref(":indeterminate")}} - {{CSSXref(":in-range")}} +- {{CSSXref(":indeterminate")}} - {{CSSXref(":invalid")}} - {{CSSXref(":is", ":is()")}} - {{CSSXref(":lang", ":lang()")}} @@ -68,6 +68,7 @@ Selectors, whether used in CSS or JavaScript, enable targeting HTML elements bas - {{CSSXref(":nth-last-of-type", ":nth-last-of-type()")}} - {{CSSXref(":only-child")}} - {{CSSXref(":only-of-type")}} +- {{CSSXref(":open")}} - {{CSSXref(":optional")}} - {{CSSXref(":out-of-range")}} - {{CSSXref(":past")}} @@ -75,6 +76,7 @@ Selectors, whether used in CSS or JavaScript, enable targeting HTML elements bas - {{CSSXref(":picture-in-picture")}} - {{CSSXref(":placeholder-shown")}} - {{CSSXref(":playing")}} +- {{CSSXref(":popover-open")}} - {{CSSXref(":read-only")}} - {{CSSXref(":read-write")}} - {{CSSXref(":required")}} @@ -106,7 +108,6 @@ Selectors, whether used in CSS or JavaScript, enable targeting HTML elements bas - [Compound selector](/en-US/docs/Web/CSS/CSS_selectors/Selector_structure#compound_selector) - [Complex selector](/en-US/docs/Web/CSS/CSS_selectors/Selector_structure#complex_selector) - [Relative selector](/en-US/docs/Web/CSS/CSS_selectors/Selector_structure#relative_selector) -- [Selector list](/en-US/docs/Web/CSS/Selector_list) - [Specificity](/en-US/docs/Web/CSS/CSS_cascade/Specificity) ## Guides @@ -123,14 +124,18 @@ Selectors, whether used in CSS or JavaScript, enable targeting HTML elements bas - : Lists the pseudo-classes, selectors that allow the selection of elements based on state information that is not contained in the document tree, defined in the various CSS modules and HTML. -- [Learn: CSS selectors](/en-US/docs/Learn_web_development/Core/Styling_basics/Basic_selectors) - - - : Part of CSS building blocks, includes tutorials on [Type, class, and ID selectors](/en-US/docs/Learn_web_development/Core/Styling_basics/Basic_selectors), [Attribute selectors](/en-US/docs/Learn_web_development/Core/Styling_basics/Attribute_selectors), [Pseudo-classes and pseudo-elements](/en-US/docs/Learn_web_development/Core/Styling_basics/Pseudo_classes_and_elements), [Combinators](/en-US/docs/Learn_web_development/Core/Styling_basics/Combinators), [Handling conflicts](/en-US/docs/Learn_web_development/Core/Styling_basics/Handling_conflicts), and [Cascade layers](/en-US/docs/Learn_web_development/Core/Styling_basics/Cascade_layers). - - [Using the `:target` pseudo-class in selectors](/en-US/docs/Web/CSS/CSS_selectors/Using_the_:target_pseudo-class_in_selectors) - : Learn how to use the {{CSSXref(":target")}} pseudo-class to style the target element a URL's fragment identifier. +- [Privacy and the `:visited` selector](/en-US/docs/Web/CSS/CSS_selectors/Privacy_and_the_visited_selector) + + - : Explores the style limitations set on the `:visited` class for user privacy. + +- [CSS building blocks: CSS selectors](/en-US/docs/Learn_web_development/Core/Styling_basics/Basic_selectors) + + - : Introduction to basic CSS selectors, including tutorials on [Type, class, and ID selectors](/en-US/docs/Learn_web_development/Core/Styling_basics/Basic_selectors), [Attribute selectors](/en-US/docs/Learn_web_development/Core/Styling_basics/Attribute_selectors), [Pseudo-classes and pseudo-elements](/en-US/docs/Learn_web_development/Core/Styling_basics/Pseudo_classes_and_elements), and [Combinators](/en-US/docs/Learn_web_development/Core/Styling_basics/Combinators). + - [Learn: UI pseudo-classes](/en-US/docs/Learn_web_development/Extensions/Forms/UI_pseudo-classes) - : Learn the different UI pseudo-classes available for styling forms in different states. @@ -141,7 +146,6 @@ Selectors, whether used in CSS or JavaScript, enable targeting HTML elements bas ## Related concepts -- {{CSSXref(":popover-open")}} pseudo-class - {{CSSXref(":state","state()")}} pseudo-class - [CSS nesting](/en-US/docs/Web/CSS/CSS_nesting) module - [`&` nesting selector](/en-US/docs/Web/CSS/Nesting_selector) @@ -149,9 +153,28 @@ Selectors, whether used in CSS or JavaScript, enable targeting HTML elements bas - {{CSSXref(":host")}} pseudo-class - {{CSSXref(":host_function", ":host()")}} pseudo-class - - {{cssxref(":host-context", ":host-context()")}} pseudo-class + - {{CSSXref(":host-context", ":host-context()")}} pseudo-class + - {{CSSXref(":has-slotted")}} pseudo-class - {{CSSXref("::slotted")}} pseudo-element +- [CSS overflow](/en-US/docs/Web/CSS/CSS_overflow) module + + - {{cssxref("::scroll-button()")}} + - {{cssxref("::scroll-marker")}} + - {{cssxref("::scroll-marker-group")}} + - {{cssxref(":target-current")}} + +- [CSS multi-column layout](/en-US/docs/Web/CSS/CSS_multicol_layout) module + + - {{cssxref("::column")}} + +- [CSS paged media](/en-US/docs/Web/CSS/CSS_paged_media) module + + - {{CSSXref(":left")}} pseudo-class + - {{CSSXref(":right")}} pseudo-class + - {{CSSXref(":first")}} pseudo-class + - `:blank` pseudo-class + - [CSS pseudo-element module](/en-US/docs/Web/CSS/CSS_pseudo-elements) (representing entities not included in HTML) - {{CSSXref("::after")}} diff --git a/files/en-us/web/css/css_selectors/privacy_and_the_visited_selector/index.md b/files/en-us/web/css/css_selectors/privacy_and_the_visited_selector/index.md new file mode 100644 index 000000000000000..6c8fd32829e72f9 --- /dev/null +++ b/files/en-us/web/css/css_selectors/privacy_and_the_visited_selector/index.md @@ -0,0 +1,62 @@ +--- +title: Privacy and the :visited selector +slug: Web/CSS/CSS_selectors/Privacy_and_the_visited_selector +page-type: guide +--- + +{{CSSRef}} + +Originally, the [CSS](/en-US/docs/Web/CSS) {{ cssxref(":visited") }} selector was a privacy and security risk. With a little bit of JavaScript, websites could uncover a user's browsing history and figure out what sites the user had visited. This was done using methods like {{domxref("window.getComputedStyle")}} and other techniques. This process was quick, enabling websites to not only determine where the user had been on the web, but also to guess a lot of information about the user's identity. + +To mitigate this privacy concern, browsers limit the amount of information that can be obtained from visited links. + +## Little white lies + +To preserve users' privacy, browsers lie to web applications under certain circumstances: + +- The `window.getComputedStyle` method and similar functions, such as {{ domxref("element.querySelector") }}, always return values indicating that a user has never visited any of the links on a page. +- When using a sibling selector, such as `:visited + span`, the adjacent element (`span` in this example) is styled as though the link were unvisited. +- In rare scenarios, if you're using nested link elements and the element being matched is different from the link whose presence in history is being tested, the element will be rendered as though the link were unvisited. + +## Limits to visited link styles + +You can style visited links, but there are limits to which styles you can use. Only the following styles can be applied to visited links: + +- {{ cssxref("color") }} +- {{ cssxref("background-color") }} +- {{ cssxref("border-color") }} (and its sub-properties) +- {{ cssxref("column-rule-color") }} +- {{ cssxref("outline-color") }} +- {{ cssxref("text-decoration-color") }} +- {{ cssxref("text-emphasis-color") }} +- Color parts of the {{SVGAttr("fill")}} and {{SVGAttr("stroke")}} attributes + +In addition, even for the styles mentioned above, transparency differences between unvisited and visited links are not applied. This restriction prevents the use of the `alpha` parameter in various {{cssxref("color_value", "&lt;color&gt;")}} functions or the [`transparent`](/en-US/docs/Web/CSS/named-color#transparent) keyword to distinguish between the two states. + +Here is an example of how to use styles with the aforementioned restrictions: + +```css +:link { + outline: 1px dotted blue; + background-color: white; + /* The default value of `background-color` is `transparent`. You need to + specify a different value, otherwise changes on `:visited` won't apply. */ +} + +:visited { + outline-color: orange; /* Visited links have an orange outline */ + background-color: green; /* Visited links have a green background */ + color: yellow; /* Visited links have yellow colored text */ +} +``` + +## Impact on web developers + +You may want to consider the following when developing sites: + +- Changing {{cssxref("background-image")}} values based on a link's visited state will not work since only colors can be used to style visited links. +- Colors that are otherwise transparent will not apply when styled via a `:visited` selector. + +## See also + +- [Preventing attacks on a user's history through CSS `:visited` selectors](https://dbaron.org/mozilla/visited-privacy) (2010) diff --git a/files/en-us/web/css/css_selectors/selectors_and_combinators/index.md b/files/en-us/web/css/css_selectors/selectors_and_combinators/index.md index 42d8eeffc04cfb5..5021072fbda33bc 100644 --- a/files/en-us/web/css/css_selectors/selectors_and_combinators/index.md +++ b/files/en-us/web/css/css_selectors/selectors_and_combinators/index.md @@ -19,7 +19,7 @@ There are over 80 selectors and combinators. CSS selectors can be grouped into t The [type selector](/en-US/docs/Web/CSS/Type_selectors) selects all elements that have the given node name. For example, `div` will select all {{HTMLElement("div")}} elements and `input` will match any {{HTMLElement("input")}} element. The [universal selector](/en-US/docs/Web/CSS/Universal_selectors), denoted with an asterisk (`*`), is a special type selector that selects all elements. -The [class selector](/en-US/docs/Web/CSS/Class_selectors) selects all elements that have the given `class` attribute denoted by the class name prefixed with a period (`.`). For example, `.index` will match any element that has `class="index"`. The [ID selector](/en-US/docs/Web/CSS/ID_selectors) selects an element based on the value of its `id` attribute. The selector is the `id` prefixed with a "number sign" (U+0023, `#`). For example, `#toc` will match the element that has `id="toc"`. Both [`class`](/en-US/docs/Web/HTML/Global_attributes/class) and [`id`](/en-US/docs/Web/HTML/Global_attributes/id) are global attributes. There should be only one element with a given `id` in a document; but if there is more than one, the ID selector will match all the elements with that `id`. +The [class selector](/en-US/docs/Web/CSS/Class_selectors) selects all elements that have the given `class` attribute denoted by the class name prefixed with a period (`.`). For example, `.index` will match any element that has `class="index"`. The [ID selector](/en-US/docs/Web/CSS/ID_selectors) selects an element based on the value of its `id` attribute. The selector is the `id` prefixed with a "number sign" (U+0023, `#`). For example, `#toc` will match the element that has `id="toc"`. Both [`class`](/en-US/docs/Web/HTML/Reference/Global_attributes/class) and [`id`](/en-US/docs/Web/HTML/Reference/Global_attributes/id) are global attributes. There should be only one element with a given `id` in a document; but if there is more than one, the ID selector will match all the elements with that `id`. When combining a type or universal selector with a class or id selector to create a [compound selector](/en-US/docs/Web/CSS/CSS_selectors/Selector_structure#compound_selector), the type or universal selector must precede the class or id. diff --git a/files/en-us/web/css/css_selectors/using_the__colon_target_pseudo-class_in_selectors/index.md b/files/en-us/web/css/css_selectors/using_the__colon_target_pseudo-class_in_selectors/index.md index 3cfdb6287613e10..8d087e649f66d38 100644 --- a/files/en-us/web/css/css_selectors/using_the__colon_target_pseudo-class_in_selectors/index.md +++ b/files/en-us/web/css/css_selectors/using_the__colon_target_pseudo-class_in_selectors/index.md @@ -12,7 +12,7 @@ When a URL points at a specific piece of a document using a [URL fragment identi The [pseudo-class](/en-US/docs/Web/CSS/Pseudo-classes) {{cssxref(":target")}} is used to style the target element of the document identified using the URL fragment identifier. For example, the URL `https://developer.mozilla.org/en-US/docs/Web/CSS#reference` contains the fragment identifier `#reference`. In HTML, identifiers are found as the values of either `id` or `name` attributes, since the two share the same namespace. Thus, the example URL would point to the element that has the id `reference` in that document. -Suppose you wish to style any `h2` element that is the target of a URL, but do not want any other kind of element to get a target style. This is simple enough: +To style any `h2` element that is the target of a URL, while not effecting any other kind of element to get a target style, use the `:target` pseudo-class with the [type selector](/en-US/docs/Web/CSS/Type_selectors): ```css h2:target { diff --git a/files/en-us/web/css/css_shadow_parts/index.md b/files/en-us/web/css/css_shadow_parts/index.md index b5474abaefb2d92..ca4d438c5f0136e 100644 --- a/files/en-us/web/css/css_shadow_parts/index.md +++ b/files/en-us/web/css/css_shadow_parts/index.md @@ -9,7 +9,7 @@ spec-urls: https://drafts.csswg.org/css-shadow-parts/ The **CSS shadow parts** module defines the {{CSSXref("::part", "::part()")}} pseudo-element that can be set on a [shadow host](/en-US/docs/Glossary/Shadow_tree). Using this pseudo-element, you can enable shadow hosts to expose the selected element in the shadow tree to the outside page for styling purposes. -By default, elements in a shadow tree can be styled only within their respective shadow roots. The CSS shadow parts module enables including a [`part`](/en-US/docs/Web/HTML/Global_attributes/part) attribute on {{HTMLElement("template")}} descendants that make up the custom element, exposing the shadow tree node to external styling via the `::part()` pseudo-element. +By default, elements in a shadow tree can be styled only within their respective shadow roots. The CSS shadow parts module enables including a [`part`](/en-US/docs/Web/HTML/Reference/Global_attributes/part) attribute on {{HTMLElement("template")}} descendants that make up the custom element, exposing the shadow tree node to external styling via the `::part()` pseudo-element. ## Reference @@ -19,8 +19,8 @@ By default, elements in a shadow tree can be styled only within their respective ### HTML attributes -- [`part`](/en-US/docs/Web/HTML/Global_attributes/part) -- [`exportparts`](/en-US/docs/Web/HTML/Global_attributes/exportparts) +- [`part`](/en-US/docs/Web/HTML/Reference/Global_attributes/part) +- [`exportparts`](/en-US/docs/Web/HTML/Reference/Global_attributes/exportparts) ### Definitions diff --git a/files/en-us/web/css/css_shapes/from_box_values/index.md b/files/en-us/web/css/css_shapes/from_box_values/index.md index c285b52019365c5..73a9a07a3e05d99 100644 --- a/files/en-us/web/css/css_shapes/from_box_values/index.md +++ b/files/en-us/web/css/css_shapes/from_box_values/index.md @@ -192,7 +192,7 @@ body { ## When to use box values -Using box values is a simple way to create shapes; however, this is by nature only going to work with very simple shapes that can be defined using the well-supported `border-radius` property. The examples shown above show one such use case. You can create a circular shape using `border-radius` and then curve text around it. +Using box values is a way to create shapes; however, this naturally works only with very basic shapes that can be defined using the `border-radius` property. The examples shown above show one such use case. You can create a circular shape using `border-radius` and then curve text around it. With just this basic technique, you can create some interesting effects. In my final example of this section, I have floated two elements left and right, giving each a border radius of 100% in the direction closest to the text. diff --git a/files/en-us/web/css/css_shapes/index.md b/files/en-us/web/css/css_shapes/index.md index 384844690e03d13..e189778489c7b6e 100644 --- a/files/en-us/web/css/css_shapes/index.md +++ b/files/en-us/web/css/css_shapes/index.md @@ -17,9 +17,9 @@ Shapes define geometries that can be used as CSS values. This module provides fu ## CSS shapes in action -The example below shows an image that has been floated left, and the `shape-outside` property applied with a value of `circle(50%)`. This creates a circle shape, and the content wrapping the float now wraps around that shape. This changes the length of the wrapping text's line boxes. +The example below shows an image that has been floated left, and the `shape-outside` property applied with a value of `circle(50%)`. This creates a circle shape, and the content wrapping the float now wraps around that shape. This changes the length of the wrapping text's line boxes. You can click "Play" to edit the code in the MDN Playground. -```html live-sample___circle +```html live-sample___circle hidden <div class="box"> <img alt="A hot air balloon" @@ -38,7 +38,7 @@ The example below shows an image that has been floated left, and the `shape-outs </div> ``` -```css live-sample___circle +```css live-sample___circle hidden body { font: 1.2em / 1.5 sans-serif; } @@ -138,5 +138,5 @@ img { - [CSS Shapes 101](https://alistapart.com/article/css-shapes-101/) via alistapart.com (2014) - [Creating non-rectangular layouts with CSS Shapes](https://www.sarasoueidan.com/blog/css-shapes/) via sarasoueidan.com (2013) - [How to use CSS Shapes in your web design](https://webdesign.tutsplus.com/how-to-use-css-shapes-in-your-web-design--cms-27498t) via tutsplus.com (2016) -- [How to get started with CSS Shapes](https://www.webdesignerdepot.com/2015/03/how-to-get-started-with-css-shapes/) via webdesignerdepot.com (2015) +- [How to get started with CSS Shapes](https://webdesignerdepot.com/how-to-get-started-with-css-shapes/) via webdesignerdepot.com (2015) - [Edit CSS shapes with the shape path editor](https://firefox-source-docs.mozilla.org/devtools-user/page_inspector/how_to/edit_css_shapes/index.html) via mozilla.org (2018) ([Video](https://www.youtube.com/watch?v=u9bDe3Bw0sA)) diff --git a/files/en-us/web/css/css_shapes/overview_of_shapes/index.md b/files/en-us/web/css/css_shapes/overview_of_shapes/index.md index 4e47e89f43d6366..adbc1db5264afac 100644 --- a/files/en-us/web/css/css_shapes/overview_of_shapes/index.md +++ b/files/en-us/web/css/css_shapes/overview_of_shapes/index.md @@ -75,7 +75,7 @@ The value `circle(50%)` is an example of a basic shape. The specification define Three of these functions only define rectangles. With the `inset()` function, you define four offset values, thus pulling the line boxes of any wrapping content closer to the object than they otherwise would. The `rect()` function defines a rectangle by specifying the distance from the top and left edges of the containing block. The `xywh()` function works by specifying distances from the top and left edges of the reference box and setting the width and height of the rectangle from that starting point. -We have already seen how `circle()` creates a circular shape. An `ellipse()` is essentially a squashed circle. If none of these simple shapes do the trick you can create more complex shapes using the `polygon()` function, which allows the definition of a series of lines. The `path()` and `shape()` functions can be used to create ANY shape via a series of line, curve, and move commands. +We have already seen how `circle()` creates a circular shape. An `ellipse()` is essentially a squashed circle. If none of these basic shapes do the trick you can create more complex shapes using the `polygon()` function, which allows the definition of a series of lines. The `path()` and `shape()` functions can be used to create ANY shape via a series of line, curve, and move commands. In our [Guide to Basic Shapes](/en-US/docs/Web/CSS/CSS_shapes/Basic_shapes) we explore each of the possible Basic Shapes and how to create them. @@ -132,7 +132,7 @@ To explore the box values in more detail, see our guide covering [Shapes from bo An interesting way to generate your path is to use an image with an alpha channel—the text will then wrap around the non-transparent parts of the image. This allows the overlay of wrapped content around an image or the use of an image that is never displayed on the page purely as a method of creating a complex shape without needing to carefully map a polygon. -Note that images used in this way must be [CORS compatible](/en-US/docs/Web/HTTP/CORS), otherwise `shape-outside` will act as if `none` had been given as the value, and you will get no shape. +Note that images used in this way must be [CORS compatible](/en-US/docs/Web/HTTP/Guides/CORS), otherwise `shape-outside` will act as if `none` had been given as the value, and you will get no shape. In this next example, we have an image with a fully transparent area, and we are using an image as the URL value for `shape-outside`. The shape is created around the opaque area — the image of the balloon. diff --git a/files/en-us/web/css/css_shapes/shapes_from_images/index.md b/files/en-us/web/css/css_shapes/shapes_from_images/index.md index 8a62652d585f4a4..c9cb40a58e07cbb 100644 --- a/files/en-us/web/css/css_shapes/shapes_from_images/index.md +++ b/files/en-us/web/css/css_shapes/shapes_from_images/index.md @@ -82,7 +82,7 @@ img { ## CORS compatibility -Something that you will run into when creating shapes from an image is that the image you use must be [CORS compatible](/en-US/docs/Web/HTTP/CORS). An image hosted on the same domain as your site should work, however, if your images are hosted on a different domain such as on a CDN you should ensure that they are sending the correct headers to enable them to be used for Shapes. Due to this requirement for CORS-compatible images, if you are previewing your file locally without using a local web server, your shape will not work. +Something that you will run into when creating shapes from an image is that the image you use must be [CORS compatible](/en-US/docs/Web/HTTP/Guides/CORS). An image hosted on the same domain as your site should work, however, if your images are hosted on a different domain such as on a CDN you should ensure that they are sending the correct headers to enable them to be used for Shapes. Due to this requirement for CORS-compatible images, if you are previewing your file locally without using a local web server, your shape will not work. ### Is it a CORS issue? diff --git a/files/en-us/web/css/css_syntax/at-rule_functions/index.md b/files/en-us/web/css/css_syntax/at-rule_functions/index.md index e5b64d408078b24..8776eb948ddb9a4 100644 --- a/files/en-us/web/css/css_syntax/at-rule_functions/index.md +++ b/files/en-us/web/css/css_syntax/at-rule_functions/index.md @@ -27,7 +27,7 @@ The {{CSSxRef("@import")}} at-rule is used to import styles from other styleshee - : Imports a stylesheet file from the specified URL. - {{CSSxRef("@import", "@import supports()")}} - : Imports a stylesheet file based on browser support. -- {{CSSxRef("@import", "@import layer()")}} +- [`@import layer()`](/en-US/docs/Web/CSS/@import/layer_function) - : Imports a stylesheet file into the specified cascade layer. ## @supports functions diff --git a/files/en-us/web/css/css_syntax/error_handling/index.md b/files/en-us/web/css/css_syntax/error_handling/index.md index 4dbf9f928a18422..4141cf25b3c9e6a 100644 --- a/files/en-us/web/css/css_syntax/error_handling/index.md +++ b/files/en-us/web/css/css_syntax/error_handling/index.md @@ -52,7 +52,7 @@ Different at-rules have different grammar rules, different (or no) descriptors, For example, the `@font-face` rule requires both a [`font-family`](/en-US/docs/Web/CSS/@font-face/font-family) and [`src`](/en-US/docs/Web/CSS/@font-face/src) descriptor. If either of these is omitted or invalid, the entire `@font-face` rule is invalid. Including an unrelated descriptor, any other valid font descriptor with an invalid value, or a property style declaration within the `@font-face` nested block will not invalidate the font declaration. As long as the font name and font source are included and valid, any invalid CSS within the at-rule is ignored, but the `@font-face` block is still parsed. -While the grammar of the `@keyframe` at-rule is very different from the `@font-face` rule grammar, the type of error still impacts what gets ignored. Important declarations (marked with the {{cssxref("important")}} flag) and properties that can't be animated are ignored in keyframe rules, but they don't impact other styles declared in the same keyframe selector block. Including an invalid keyframe selector (such as a percentage value less than `0%` or greater than `100%`, or a {{cssxref("number")}} omitting the `%`) invalidates the keyframe selector list and therefore the style block is ignored. An invalid keyframe selector only invalidates the invalid selector's style block; it does not invalidate the entire `@keyframe` declaration. Including styles between two keyframe selector blocks, on the other hand, will invalidate the entire `@keyframe` at-rule. +While the grammar of the `@keyframes` at-rule is very different from the `@font-face` rule grammar, the type of error still impacts what gets ignored. Important declarations (marked with the {{cssxref("important")}} flag) and properties that can't be animated are ignored in keyframe rules, but they don't impact other styles declared in the same keyframe selector block. Including an invalid keyframe selector (such as a percentage value less than `0%` or greater than `100%`, or a {{cssxref("number")}} omitting the `%`) invalidates the keyframe selector list and therefore the style block is ignored. An invalid keyframe selector only invalidates the invalid selector's style block; it does not invalidate the entire `@keyframes` declaration. Including styles between two keyframe selector blocks, on the other hand, will invalidate the entire `@keyframes` at-rule. Some at-rules are almost always valid. The {{cssxref("@layer")}} at-rule comes in both regular and nested forms. The `@layer` statement syntax contains just the prelude, ending with a semi-colon. Alternatively, the nested syntax has layer styles nested between curly braces coming after the prelude. Omitting a closing curly brace may be a logic error but is not a syntax error. In the case of a missing closing brace in `@layer`, any styles coming after where the closing brace should have been are parsed as being in the cascade layer defined in the at-rule's prelude. The CSS is valid as there are no syntax errors; nothing is discarded. A syntax error may cause the named or anonymous layer to be empty, but the layer is still created. @@ -78,13 +78,13 @@ When it comes to CSS properties and values within a declaration block, if either This example contains an error. The parser ignores the error (and the comments), seeks forward until it encounters a semi-colon, then restarts parsing: -```css-nolint bad +```css-nolint example-bad p { -/* Invalid syntax due to missing semi-colon */ + /* Invalid syntax due to missing semi-colon */ border-color: red background-color: green; -/* Valid syntax but likely a logic error */ + /* Valid syntax but likely a logic error */ border-width: 100vh; } ``` @@ -128,9 +128,9 @@ In this example, the last declaration in each block is valid in all browsers — If a stylesheet ends while a rule, declaration, function, string, or comment is still open, the parser will automatically close everything that was left unclosed. > [!NOTE] -> This is true of external style sheets, selector blocks within an HTML {{HTMLElement("style")}} element, and inline rules within a [`style`](/en-US/docs/Web/HTML/Global_attributes/style) attribute. +> This is true of external style sheets, selector blocks within an HTML {{HTMLElement("style")}} element, and inline rules within a [`style`](/en-US/docs/Web/HTML/Reference/Global_attributes/style) attribute. -If the content between the last semi-colon and the end of the stylesheet is valid, even if incomplete, the CSS will be parsed normally. For example, if you fail to close out a `@keyframe` declaration before closing your {{htmlelement("style")}}, the animation is still valid. +If the content between the last semi-colon and the end of the stylesheet is valid, even if incomplete, the CSS will be parsed normally. For example, if you fail to close out a `@keyframes` declaration before closing your {{htmlelement("style")}}, the animation is still valid. ```html-nolint example-bad <style> @@ -167,11 +167,11 @@ Each CSS property accepts specific data types. For example, the {{cssxref("backg ### Invalid custom properties -Custom properties are generally considered valid when declared, but may create invalid CSS when accessed, i.e. they may be used as a value (via the {{cssxref("var")}} function) for a property that does not accept that value type. The browser parses each custom property when encountered without regard to where the property is consumed. +Custom properties are generally considered valid when declared, but may create invalid CSS when accessed, i.e., they may be used as a value (via the {{cssxref("var")}} function) for a property that does not accept that value type. The browser parses each custom property when encountered without regard to where the property is consumed. Generally, when a property value is invalid, the declaration is ignored and the property falls back to the last valid value. Invalid computed custom property values, however, work slightly differently. -When a `var()` substitution is invalid, the declaration is not ignored and the [initial](/en-US/docs/Web/CSS/CSS_cascade/initial_value) or [inherited](/en-US/docs/Web/CSS/CSS_cascade/Inheritance) value of the property is used instead. The property is set to a new value, but possibly not the expected one. +When a `var()` substitution is invalid, the declaration is not ignored and the [initial](/en-US/docs/Web/CSS/CSS_cascade/Value_processing#initial_value) or [inherited](/en-US/docs/Web/CSS/CSS_cascade/Inheritance) value of the property is used instead. The property is set to a new value, but possibly not the expected one. Let's look at an example to illustrate this behavior: diff --git a/files/en-us/web/css/css_syntax/index.md b/files/en-us/web/css/css_syntax/index.md index a1d6b80981afa0c..cf9dcca6676213e 100644 --- a/files/en-us/web/css/css_syntax/index.md +++ b/files/en-us/web/css/css_syntax/index.md @@ -66,10 +66,10 @@ This module doesn't define any properties, [data types](/en-US/docs/Web/CSS/CSS_ - {{cssxref("@import")}} at-rule - {{cssxref("important")}} flag -- [Initial values](/en-US/docs/Web/CSS/CSS_cascade/initial_value) -- [Computed values](/en-US/docs/Web/CSS/CSS_cascade/computed_value) -- [Used values](/en-US/docs/Web/CSS/CSS_cascade/used_value) -- [Actual values](/en-US/docs/Web/CSS/CSS_cascade/actual_value) +- [Initial values](/en-US/docs/Web/CSS/CSS_cascade/Value_processing#initial_value) +- [Computed values](/en-US/docs/Web/CSS/CSS_cascade/Value_processing#computed_value) +- [Used values](/en-US/docs/Web/CSS/CSS_cascade/Value_processing#used_value) +- [Actual values](/en-US/docs/Web/CSS/CSS_cascade/Value_processing#actual_value) - [CSS inheritance](/en-US/docs/Web/CSS/CSS_cascade/Inheritance) - {{Glossary("Property/CSS", "CSS property")}} @@ -93,8 +93,8 @@ This module doesn't define any properties, [data types](/en-US/docs/Web/CSS/CSS_ - {{HTMLElement("style")}} element - {{HTMLElement("link")}} element -- [`class`](/en-US/docs/Web/HTML/Global_attributes/class) attribute -- [`rel`](/en-US/docs/Web/HTML/Attributes/rel#stylesheet) attribute +- [`class`](/en-US/docs/Web/HTML/Reference/Global_attributes/class) attribute +- [`rel`](/en-US/docs/Web/HTML/Reference/Attributes/rel#stylesheet) attribute ## Specifications diff --git a/files/en-us/web/css/css_syntax/syntax/index.md b/files/en-us/web/css/css_syntax/syntax/index.md index 9010a620f30cb03..daf9afa72f438a6 100644 --- a/files/en-us/web/css/css_syntax/syntax/index.md +++ b/files/en-us/web/css/css_syntax/syntax/index.md @@ -34,7 +34,7 @@ A CSS declaration block is visualized in the diagram below. ![Within a CSS block, encompassed in braces, semicolons separate declarations, with the final semicolon being optional but recommended as good practice.](declaration-block.png) > [!NOTE] -> The content of a CSS declaration block, that is a list of semicolon-separated declarations, without the initial and closing braces, can be put inside an HTML [`style`](/en-US/docs/Web/HTML/Global_attributes/style) attribute. +> The content of a CSS declaration block, that is a list of semicolon-separated declarations, without the initial and closing braces, can be put inside an HTML [`style`](/en-US/docs/Web/HTML/Reference/Global_attributes/style) attribute. ## CSS rulesets @@ -83,8 +83,8 @@ There is another group of statements – the **nested statements**. These are st - [Cascade](/en-US/docs/Web/CSS/CSS_cascade/Cascade) - [Value definition syntax](/en-US/docs/Web/CSS/CSS_Values_and_Units/Value_definition_syntax) - Values - - [Initial values](/en-US/docs/Web/CSS/CSS_cascade/initial_value) - - [Computed values](/en-US/docs/Web/CSS/CSS_cascade/computed_value) - - [Used values](/en-US/docs/Web/CSS/CSS_cascade/used_value) - - [Actual values](/en-US/docs/Web/CSS/CSS_cascade/actual_value) + - [Initial values](/en-US/docs/Web/CSS/CSS_cascade/Value_processing#initial_value) + - [Computed values](/en-US/docs/Web/CSS/CSS_cascade/Value_processing#computed_value) + - [Used values](/en-US/docs/Web/CSS/CSS_cascade/Value_processing#used_value) + - [Actual values](/en-US/docs/Web/CSS/CSS_cascade/Value_processing#actual_value) - [Shorthand properties](/en-US/docs/Web/CSS/CSS_cascade/Shorthand_properties) diff --git a/files/en-us/web/css/css_transforms/index.md b/files/en-us/web/css/css_transforms/index.md index 8bdb19be03eff4a..56a9e3f7b089b67 100644 --- a/files/en-us/web/css/css_transforms/index.md +++ b/files/en-us/web/css/css_transforms/index.md @@ -607,25 +607,25 @@ const resetInput = (inputEl) => { }; const updateOutputs = () => { - translateXOutput.value = `${parseInt(translateXRange.value)}px`; - translateYOutput.value = `${parseInt(translateYRange.value)}px`; - translateZOutput.value = `${parseInt(translateZRange.value)}px`; + translateXOutput.value = `${translateXRange.value}px`; + translateYOutput.value = `${translateYRange.value}px`; + translateZOutput.value = `${translateZRange.value}px`; - rotateXOutput.value = `${parseInt(rotateXRange.value)}°`; - rotateYOutput.value = `${parseInt(rotateYRange.value)}°`; - rotateZOutput.value = `${parseInt(rotateZRange.value)}°`; + rotateXOutput.value = `${rotateXRange.value}°`; + rotateYOutput.value = `${rotateYRange.value}°`; + rotateZOutput.value = `${rotateZRange.value}°`; - scaleXOutput.value = `${parseFloat(scaleXRange.value)}x`; - scaleYOutput.value = `${parseFloat(scaleYRange.value)}x`; - scaleZOutput.value = `${parseFloat(scaleZRange.value)}x`; + scaleXOutput.value = `${scaleXRange.value}x`; + scaleYOutput.value = `${scaleYRange.value}x`; + scaleZOutput.value = `${scaleZRange.value}x`; - skewXOutput.value = `${parseFloat(skewXRange.value)}°`; - skewYOutput.value = `${parseFloat(skewYRange.value)}°`; + skewXOutput.value = `${skewXRange.value}°`; + skewYOutput.value = `${skewYRange.value}°`; - perspectiveOutput.value = `${parseInt(perspectiveRange.value)}px`; + perspectiveOutput.value = `${perspectiveRange.value}px`; - perspectiveOriginXOutput.value = `${parseInt(perspectiveOriginXRange.value)}%`; - perspectiveOriginYOutput.value = `${parseInt(perspectiveOriginYRange.value)}%`; + perspectiveOriginXOutput.value = `${perspectiveOriginXRange.value}%`; + perspectiveOriginYOutput.value = `${perspectiveOriginYRange.value}%`; }; const updateTransform = () => { @@ -749,10 +749,10 @@ The cube in the above example is comprised of six `<div>` elements, all of which - [Interpolation](/en-US/docs/Glossary/Interpolation) - [Stacking context](/en-US/docs/Glossary/Stacking_context) - [SVG](/en-US/docs/Web/SVG) concepts: - - [`<animate>`](/en-US/docs/Web/SVG/Element/animate) element - - [`<animateTransform>`](/en-US/docs/Web/SVG/Element/animateTransform) element - - [`<set>`](/en-US/docs/Web/SVG/Element/set) element - - [`transform`](/en-US/docs/Web/SVG/Attribute/transform) element + - [`<animate>`](/en-US/docs/Web/SVG/Reference/Element/animate) element + - [`<animateTransform>`](/en-US/docs/Web/SVG/Reference/Element/animateTransform) element + - [`<set>`](/en-US/docs/Web/SVG/Reference/Element/set) element + - [`transform`](/en-US/docs/Web/SVG/Reference/Attribute/transform) element ## Specifications @@ -760,6 +760,6 @@ The cube in the above example is comprised of six `<div>` elements, all of which ## See also -- [Basic SVG transformations](/en-US/docs/Web/SVG/Tutorial/Basic_Transformations) tutorial +- [Basic SVG transformations](/en-US/docs/Web/SVG/Tutorials/SVG_from_scratch/Basic_transformations) tutorial - [CSS animations](/en-US/docs/Web/CSS/CSS_animations) module - [CSS transitions](/en-US/docs/Web/CSS/CSS_transitions) module diff --git a/files/en-us/web/css/css_transforms/using_css_transforms/index.md b/files/en-us/web/css/css_transforms/using_css_transforms/index.md index 09c09e50c060fd9..9f6c58acc6cb890 100644 --- a/files/en-us/web/css/css_transforms/using_css_transforms/index.md +++ b/files/en-us/web/css/css_transforms/using_css_transforms/index.md @@ -11,7 +11,7 @@ By modifying the coordinate space, **CSS transforms** change the shape and posit CSS transforms are implemented using a set of CSS properties that let you apply affine linear transformations to HTML elements. These transformations include rotation, skewing, scaling, and translation both in the plane and in the 3D space. > [!WARNING] -> Only transformable elements can be `transform`ed; that is, all elements whose layout is governed by the CSS [box model](/en-US/docs/Web/CSS/CSS_box_model) except for: [non-replaced inline boxes](/en-US/docs/Web/CSS/Visual_formatting_model#inline-level_and_block-level_boxes), [table-column boxes](/en-US/docs/Web/HTML/Element/col), and [table-column-group boxes](/en-US/docs/Web/HTML/Element/colgroup). +> Only transformable elements can be `transform`ed; that is, all elements whose layout is governed by the CSS [box model](/en-US/docs/Web/CSS/CSS_box_model) except for: [non-replaced inline boxes](/en-US/docs/Web/CSS/CSS_display/Visual_formatting_model#inline-level_and_block-level_boxes), [table-column boxes](/en-US/docs/Web/HTML/Reference/Elements/col), and [table-column-group boxes](/en-US/docs/Web/HTML/Reference/Elements/colgroup). ## CSS transforms properties @@ -82,7 +82,7 @@ The HTML below creates four copies of the same box, with the perspective set at <tr> <td> <div class="container"> - <div class="cube pers250"> + <div class="cube perspective-250"> <div class="face front">1</div> <div class="face back">2</div> <div class="face right">3</div> @@ -94,7 +94,7 @@ The HTML below creates four copies of the same box, with the perspective set at </td> <td> <div class="container"> - <div class="cube pers350"> + <div class="cube perspective-350"> <div class="face front">1</div> <div class="face back">2</div> <div class="face right">3</div> @@ -112,7 +112,7 @@ The HTML below creates four copies of the same box, with the perspective set at <tr> <td> <div class="container"> - <div class="cube pers500"> + <div class="cube perspective-500"> <div class="face front">1</div> <div class="face back">2</div> <div class="face right">3</div> @@ -124,7 +124,7 @@ The HTML below creates four copies of the same box, with the perspective set at </td> <td> <div class="container"> - <div class="cube pers650"> + <div class="cube perspective-650"> <div class="face front">1</div> <div class="face back">2</div> <div class="face right">3</div> @@ -145,19 +145,19 @@ The CSS establishes classes that can be used to set the perspective to different ```css /* Shorthand classes for different perspective values */ -.pers250 { +.perspective-250 { perspective: 250px; } -.pers350 { +.perspective-350 { perspective: 350px; } -.pers500 { +.perspective-500 { perspective: 500px; } -.pers650 { +.perspective-650 { perspective: 650px; } diff --git a/files/en-us/web/css/css_values_and_units/css_data_types/index.md b/files/en-us/web/css/css_values_and_units/css_data_types/index.md index 257ef44ab594652..88d78828a6ff839 100644 --- a/files/en-us/web/css/css_values_and_units/css_data_types/index.md +++ b/files/en-us/web/css/css_values_and_units/css_data_types/index.md @@ -112,15 +112,15 @@ Some CSS properties can take a dimension or a percentage value. In this case the - {{cssxref("&lt;image&gt;")}} - : A URL reference to an image or a color gradient. -- {{cssxref("&lt;color-stop-list&gt;")}} +- `<color-stop-list>` - : A list of two or more color stops with optional transition information using a color hint. -- {{cssxref("&lt;linear-color-stop&gt;")}} +- `<linear-color-stop>` - : A `<color>` and a `<length-percentage>` to indicate the color stop for this part of the gradient. -- {{cssxref("&lt;linear-color-hint&gt;")}} +- `<linear-color-hint>` - : A `<length-percentage>` to indicate how the color interpolates. -- {{cssxref("&lt;ending-shape&gt;")}} +- `<ending-shape>` - : Used for radial gradients; can have a keyword value of `circle` or `ellipse`. -- {{cssxref("&lt;size&gt;")}} +- `<size>` - : Determines the size of the radial gradient's ending shape. This accepts a value of a keyword or a `<length>` but not a percentage. ## 2D positioning diff --git a/files/en-us/web/css/css_values_and_units/index.md b/files/en-us/web/css/css_values_and_units/index.md index a1de1fa30acac62..62a27e4962b9e6c 100644 --- a/files/en-us/web/css/css_values_and_units/index.md +++ b/files/en-us/web/css/css_values_and_units/index.md @@ -56,7 +56,6 @@ Additional functions, including `calc-mix()`, `crossorigin()`, `first-valid()`, - [`<animation-timeline>`](/en-US/docs/Web/CSS/animation-timeline) - [`<attr-name>`](/en-US/docs/Web/CSS/attr#attr-name) - [`<attr-type>`](/en-US/docs/Web/CSS/attr#attr-type) -- [`<attr-unit>`](/en-US/docs/Web/CSS/attr#attr-unit) - {{CSSxRef("&lt;calc-keyword&gt;")}} (`e`, `pi`, `infinity`, {{glossary("NaN")}}) - [`<calc-size-basis>`](/en-US/docs/Web/CSS/calc-size#calc-size-basis) - [`<calc-sum>`](/en-US/docs/Web/CSS/calc-sum) @@ -64,7 +63,7 @@ Additional functions, including `calc-mix()`, `crossorigin()`, `first-valid()`, - [`<dashed-ident>`](/en-US/docs/Web/CSS/dashed-ident) - [`<dimension>`](/en-US/docs/Web/CSS/dimension) - [`<easing-function>`](/en-US/docs/Web/CSS/easing-function) -- [`<first-valid()>`](/en-US/docs/Web/CSS/) +- [`<first-valid()>`](/en-US/docs/Web/CSS) - [`<frequency>`](/en-US/docs/Web/CSS/frequency) - [`<frequency-percentage>`](/en-US/docs/Web/CSS/frequency-percentage) - [`<ident>`](/en-US/docs/Web/CSS/ident) @@ -81,7 +80,7 @@ Additional functions, including `calc-mix()`, `crossorigin()`, `first-valid()`, - [`<syntax>`](/en-US/docs/Web/CSS/CSS_syntax/Syntax) - [`<time-percentage>`](/en-US/docs/Web/CSS/time-percentage) - [`<time>`](/en-US/docs/Web/CSS/time) -- [`<url>`](/en-US/docs/Web/CSS/url) +- [`<url>`](/en-US/docs/Web/CSS/url_value) - [`<url-modifier>`](/en-US/docs/Web/CSS/url_function#url-modifier) - [`<view-timeline-name>`](/en-US/docs/Web/CSS/view-timeline-name) @@ -91,64 +90,60 @@ Additional functions, including `calc-mix()`, `crossorigin()`, `first-valid()`, - [`cap`](/en-US/docs/Web/CSS/length#cap) - [`ch`](/en-US/docs/Web/CSS/length#ch) - [`cm`](/en-US/docs/Web/CSS/length#cm) -- [`deg`](/en-US/docs/Web/CSS/length#deg) -- [`dpcm`](/en-US/docs/Web/CSS/length#dpcm) -- [`dpi`](/en-US/docs/Web/CSS/length#dpi) -- [`dppx`](/en-US/docs/Web/CSS/length#dppx) -- [`dvb`](/en-US/docs/Web/CSS/length#dvb) -- [`dvh`](/en-US/docs/Web/CSS/length#dvh) -- [`dvi`](/en-US/docs/Web/CSS/length#dvi) -- [`dvmax`](/en-US/docs/Web/CSS/length#dvmax) -- [`dvmin`](/en-US/docs/Web/CSS/length#dvmin) -- [`dvw`](/en-US/docs/Web/CSS/length#dvw) +- [`deg`](/en-US/docs/Web/CSS/angle#deg) +- [`dpcm`](/en-US/docs/Web/CSS/resolution#dpcm) +- [`dpi`](/en-US/docs/Web/CSS/resolution#dpi) +- [`dppx`](/en-US/docs/Web/CSS/resolution#dppx) +- [`dvb`](/en-US/docs/Web/CSS/length#vb) +- [`dvh`](/en-US/docs/Web/CSS/length#vh) +- [`dvi`](/en-US/docs/Web/CSS/length#vi) +- [`dvmax`](/en-US/docs/Web/CSS/length#vmax) +- [`dvmin`](/en-US/docs/Web/CSS/length#vmin) +- [`dvw`](/en-US/docs/Web/CSS/length#vw) - [`em`](/en-US/docs/Web/CSS/length#em) - [`ex`](/en-US/docs/Web/CSS/length#ex) -- [`grad`](/en-US/docs/Web/CSS/length#grad) -- [`Hz`](/en-US/docs/Web/CSS/length#Hz) +- [`grad`](/en-US/docs/Web/CSS/angle#grad) +- [`Hz`](/en-US/docs/Web/CSS/frequency#hz) - [`ic`](/en-US/docs/Web/CSS/length#ic) - [`in`](/en-US/docs/Web/CSS/length#in) -- [`kHz`](/en-US/docs/Web/CSS/length#kHz) -- [`left`](/en-US/docs/Web/CSS/length#left) +- [`kHz`](/en-US/docs/Web/CSS/frequency#khz) - [`lh`](/en-US/docs/Web/CSS/length#lh) -- [`lvb`](/en-US/docs/Web/CSS/length#lvb) -- [`lvh`](/en-US/docs/Web/CSS/length#lvh) -- [`lvi`](/en-US/docs/Web/CSS/length#lvi) -- [`lvmax`](/en-US/docs/Web/CSS/length#lvmax) -- [`lvmin`](/en-US/docs/Web/CSS/length#lvmin) -- [`lvw`](/en-US/docs/Web/CSS/length#lvw) +- [`lvb`](/en-US/docs/Web/CSS/length#vb) +- [`lvh`](/en-US/docs/Web/CSS/length#vh) +- [`lvi`](/en-US/docs/Web/CSS/length#vi) +- [`lvmax`](/en-US/docs/Web/CSS/length#vmax) +- [`lvmin`](/en-US/docs/Web/CSS/length#vmin) +- [`lvw`](/en-US/docs/Web/CSS/length#vw) - [`mm`](/en-US/docs/Web/CSS/length#mm) -- [`ms`](/en-US/docs/Web/CSS/length#ms) +- [`ms`](/en-US/docs/Web/CSS/time#ms) - [`pc`](/en-US/docs/Web/CSS/length#pc) -- [`pi`](/en-US/docs/Web/CSS/length#pi) - [`pt`](/en-US/docs/Web/CSS/length#pt) - [`px`](/en-US/docs/Web/CSS/length#px) -- [`Q`](/en-US/docs/Web/CSS/length#Q) -- [`rad`](/en-US/docs/Web/CSS/length#rad) +- [`Q`](/en-US/docs/Web/CSS/length#q) +- [`rad`](/en-US/docs/Web/CSS/angle#rad) - [`rcap`](/en-US/docs/Web/CSS/length#rcap) - [`rch`](/en-US/docs/Web/CSS/length#rch) - [`rem`](/en-US/docs/Web/CSS/length#rem) - [`rex`](/en-US/docs/Web/CSS/length#rex) - [`ric`](/en-US/docs/Web/CSS/length#ric) - [`rlh`](/en-US/docs/Web/CSS/length#rlh) -- [`s`](/en-US/docs/Web/CSS/length#s) -- [`size`](/en-US/docs/Web/CSS/length#size) -- [`svb`](/en-US/docs/Web/CSS/length#svb) -- [`svh`](/en-US/docs/Web/CSS/length#svh) -- [`svi`](/en-US/docs/Web/CSS/length#svi) -- [`svmax`](/en-US/docs/Web/CSS/length#svmax) -- [`svmin`](/en-US/docs/Web/CSS/length#svmin) -- [`svw`](/en-US/docs/Web/CSS/length#svw) -- [`turn`](/en-US/docs/Web/CSS/length#turn) -- [`up`](/en-US/docs/Web/CSS/length#up) +- [`s`](/en-US/docs/Web/CSS/time#s) +- [`svb`](/en-US/docs/Web/CSS/length#vb) +- [`svh`](/en-US/docs/Web/CSS/length#vh) +- [`svi`](/en-US/docs/Web/CSS/length#vi) +- [`svmax`](/en-US/docs/Web/CSS/length#vmax) +- [`svmin`](/en-US/docs/Web/CSS/length#vmin) +- [`svw`](/en-US/docs/Web/CSS/length#vw) +- [`turn`](/en-US/docs/Web/CSS/angle#turn) - [`vb`](/en-US/docs/Web/CSS/length#vb) - [`vh`](/en-US/docs/Web/CSS/length#vh) - [`vi`](/en-US/docs/Web/CSS/length#vi) - [`vmax`](/en-US/docs/Web/CSS/length#vmax) - [`vmin`](/en-US/docs/Web/CSS/length#vmin) - [`vw`](/en-US/docs/Web/CSS/length#vw) -- [`x`](/en-US/docs/Web/CSS/length#x) +- [`x`](/en-US/docs/Web/CSS/resolution#x) -[Flex units](/en-US/docs/Web/CSS/CSS_Values_and_Units/Numeric_data_types#flex_units) (`fr`) and [container units](/en-US/docs/Web/CSS/CSS_Values_and_Units/Numeric_data_types#container_units) (`cqb`,`cqh`,`cqi`,`cqmax`,`cqmin`,`cqw`) are defined in the [CSS grid layout](/en-US/docs/Web/CSS/CSS_grid_layout) and [CSS conditional rules](/en-US/docs/Web/CSS/CSS_conditional_rules) modules, respectively. +[Flex units](/en-US/docs/Web/CSS/CSS_Values_and_Units/Numeric_data_types#flex_units) (`fr`) and [container units](/en-US/docs/Web/CSS/CSS_Values_and_Units/Numeric_data_types#container_units) (`cqb`, `cqh`, `cqi`, `cqmax`, `cqmin`, `cqw`) are defined in the [CSS grid layout](/en-US/docs/Web/CSS/CSS_grid_layout) and [CSS conditional rules](/en-US/docs/Web/CSS/CSS_conditional_rules) modules, respectively. #### Unit categorizations @@ -158,11 +153,11 @@ Additional functions, including `calc-mix()`, `crossorigin()`, `first-valid()`, - [Dynamic viewport units](/en-US/docs/Web/CSS/length#dynamic_viewport_units) (`dvb`, `dvh`, `dvi`, `dvmax`, `dvmin`, `dvw`) - [Frequency units](/en-US/docs/Web/CSS/CSS_Values_and_Units/Numeric_data_types#frequency_units) (`Hz`, `kHz`) - [Large viewport-percentage units](/en-US/docs/Web/CSS/length#large_viewport_units) (`lvb`, `lvh`, `lvi`, `lvmax`, `lvmin`, `lvw`) -- [Local font-relative length units](/en-US/docs/Web/CSS/CSS_Values_and_Units/Numeric_data_types#local_font-relative_lengths) (`cap`, `ch` ,`em`, `ex`, `ic`, `lh`) +- [Local font-relative length units](/en-US/docs/Web/CSS/CSS_Values_and_Units/Numeric_data_types#local_font-relative_lengths) (`cap`, `ch`, `em`, `ex`, `ic`, `lh`) - [Physical units](/en-US/docs/Web/CSS/CSS_Values_and_Units/Numeric_data_types#absolute_length_units) (`cm`, `in`, `mm`, `pc`, `pt`, `Q`) - [Relative length units](/en-US/docs/Web/CSS/CSS_Values_and_Units/Numeric_data_types) (`cap`, `ch`, `em`, `ex`, `ic`, `lh`, `rem`, `rlh`, `vb`, `vh`, `vi`, `vmax`, `vmin`, `vw`) - [Resolution units](/en-US/docs/Web/CSS/CSS_Values_and_Units/Numeric_data_types#resolution_units) (`dpcm`, `dpi` , `dppx`, `x`) -- [Root font-relative length units](/en-US/docs/Web/CSS/CSS_Values_and_Units/Numeric_data_types#root_font-relative_lengths) (`rcap` ,`rch`, `rem`, `rex`, `ric`, `rlh`) +- [Root font-relative length units](/en-US/docs/Web/CSS/CSS_Values_and_Units/Numeric_data_types#root_font-relative_lengths) (`rcap`, `rch`, `rem`, `rex`, `ric`, `rlh`) - [Small viewport-percentage unit](/en-US/docs/Web/CSS/length#small_viewport_units) (`svb`, `svh`, `svi`, `svmax`, `svmin`, `svw`) - [Time units](/en-US/docs/Web/CSS/CSS_Values_and_Units/Numeric_data_types#time_units) (`ms`, `s`) - [Viewport units](/en-US/docs/Web/CSS/CSS_Values_and_Units/Numeric_data_types#viewport_units) (`dvh`, `dvw`, `lvh`, `lvw`, `svh`, `svw`, `vb` , `vh`, `vi` , `vmax`, `vmin`, `vw`) @@ -205,7 +200,7 @@ Additional functions, including `calc-mix()`, `crossorigin()`, `first-valid()`, - : Overview of the CSS statements that invoke special data processing or calculations to return a CSS value for a CSS property. -- [Using CSS math functions](/en-US/docs/Web/CSS/CSS_Values_and_Units/Using_CSS_Math_Functions) +- [Using CSS math functions](/en-US/docs/Web/CSS/CSS_Values_and_Units/Using_CSS_math_functions) - : The CSS math functions that allow a property value to be written as a mathematical expression. @@ -235,7 +230,7 @@ Additional functions, including `calc-mix()`, `crossorigin()`, `first-valid()`, - [CSS conditional rules](/en-US/docs/Web/CSS/CSS_conditional_rules) module - - [Container units](/en-US/docs/Web/CSS/CSS_Values_and_Units/Numeric_data_types#container_units) (`cqb`,`cqh`,`cqi`,`cqmax`,`cqmin`,`cqw`) + - [Container units](/en-US/docs/Web/CSS/CSS_Values_and_Units/Numeric_data_types#container_units) (`cqb`, `cqh`, `cqi`, `cqmax`, `cqmin`, `cqw`) - [CSS colors](/en-US/docs/Web/CSS/CSS_colors) module diff --git a/files/en-us/web/css/css_values_and_units/numeric_data_types/index.md b/files/en-us/web/css/css_values_and_units/numeric_data_types/index.md index 735297b06b1e4cc..eeab56d8e47831b 100644 --- a/files/en-us/web/css/css_values_and_units/numeric_data_types/index.md +++ b/files/en-us/web/css/css_values_and_units/numeric_data_types/index.md @@ -19,7 +19,7 @@ A {{cssxref("&lt;number&gt;")}} represents a real number, which may or may not h ## Dimensions -A {{cssxref("&lt;dimension&gt;")}} is a `<number>` with a unit attached to it, for example `45deg`, `100ms`, or `10px`. The attached unit identifier is case insensitive. There is never a space or any other characters between the number and the unit identifier: i.e. `1 cm` is not valid. +A {{cssxref("&lt;dimension&gt;")}} is a `<number>` with a unit attached to it, for example `45deg`, `100ms`, or `10px`. The attached unit identifier is case insensitive. There is never a space or any other characters between the number and the unit identifier: i.e., `1 cm` is not valid. CSS uses dimensions to specify: @@ -40,7 +40,7 @@ There are two types of relative lengths: font-relative lengths and viewport-perc #### Local font-relative lengths -Local font-relative lengths are relative to the "local" font size or line height, specifying a length in relation to a computed size of a feature of the [element](/en-US/docs/Web/HTML/Element) itself, or relative to the element's inherited value in the case of a circular reference, such as the `em` value for a {{cssxref("font-size")}} property or a `lh` value for a {{cssxref("line-height")}} property. +Local font-relative lengths are relative to the "local" font size or line height, specifying a length in relation to a computed size of a feature of the [element](/en-US/docs/Web/HTML/Reference/Elements) itself, or relative to the element's inherited value in the case of a circular reference, such as the `em` value for a {{cssxref("font-size")}} property or a `lh` value for a {{cssxref("line-height")}} property. For example, `em` is relative to the font size on the element and `ex` is relative to the x-height of the element's font. | Unit | Relative to | @@ -73,12 +73,12 @@ For example, `vw` is relative to the width of the viewport and `vh` is relative | Unit | Relative to | | ------ | ----------------------------------------------------------------------------------------------------- | -| `dvh` | 1% of the [dynamic](/en-US/docs/Web/CSS/length#dynamic) viewport's height. | -| `dvw` | 1% of the [dynamic](/en-US/docs/Web/CSS/length#dynamic) viewport's width. | -| `lvh` | 1% of the [large](/en-US/docs/Web/CSS/length#large) viewport's height. | -| `lvw` | 1% of the [large](/en-US/docs/Web/CSS/length#large) viewport's width. | -| `svh` | 1% of the [small](/en-US/docs/Web/CSS/length#small) viewport's height. | -| `svw` | 1% of the [small](/en-US/docs/Web/CSS/length#small) viewport's width. | +| `dvh` | 1% of the [dynamic](/en-US/docs/Web/CSS/length#dynamic_viewport_units) viewport's height. | +| `dvw` | 1% of the [dynamic](/en-US/docs/Web/CSS/length#dynamic_viewport_units) viewport's width. | +| `lvh` | 1% of the [large](/en-US/docs/Web/CSS/length#large_viewport_units) viewport's height. | +| `lvw` | 1% of the [large](/en-US/docs/Web/CSS/length#large_viewport_units) viewport's width. | +| `svh` | 1% of the [small](/en-US/docs/Web/CSS/length#small_viewport_units) viewport's height. | +| `svw` | 1% of the [small](/en-US/docs/Web/CSS/length#small_viewport_units) viewport's width. | | `vb` | 1% of viewport's size in the root element's [block axis](/en-US/docs/Glossary/Flow_relative_values). | | `vh` | 1% of viewport's height. | | `vi` | 1% of viewport's size in the root element's [inline axis](/en-US/docs/Glossary/Flow_relative_values). | @@ -181,7 +181,7 @@ As an example, if you specify the {{cssxref("width")}} of a box as a percentage, ## Mixing percentages and dimensions -Some properties accept a dimension that could be either one of two types, for example a `<length>` **or** a `<percentage>`. In this case the allowed value is detailed in the specification as a combination unit, e.g. {{cssxref("&lt;length-percentage&gt;")}}. Other possible combinations are as follows: +Some properties accept a dimension that could be either one of two types, for example a `<length>` **or** a `<percentage>`. In this case the allowed value is detailed in the specification as a combination unit, e.g., {{cssxref("&lt;length-percentage&gt;")}}. Other possible combinations are as follows: - {{cssxref("&lt;frequency-percentage&gt;")}} - {{cssxref("&lt;angle-percentage&gt;")}} @@ -195,7 +195,7 @@ Some properties accept a dimension that could be either one of two types, for ex ### Color -The {{cssxref("&lt;color&gt;")}} value specifies the color of an element feature (e.g. it's background color), and is defined in the [CSS Color Module](https://drafts.csswg.org/css-color-3/). +The {{cssxref("&lt;color&gt;")}} value specifies the color of an element feature (e.g., it's background color), and is defined in the [CSS Color Module](https://drafts.csswg.org/css-color-3/). ### Image diff --git a/files/en-us/web/css/css_values_and_units/textual_data_types/index.md b/files/en-us/web/css/css_values_and_units/textual_data_types/index.md index 08dda93ec9fc451..aa92d2d60b4e547 100644 --- a/files/en-us/web/css/css_values_and_units/textual_data_types/index.md +++ b/files/en-us/web/css/css_values_and_units/textual_data_types/index.md @@ -15,10 +15,10 @@ In CSS specifications, values that can be defined by the web developer — such When both quoted and unquoted user-defined text values are permitted, the specification will list `<custom-ident> | <string>`, meaning quotes are optional, such as is the case with [keyframe animation names]: ```css -@keyframe validIdent { +@keyframes validIdent { /* keyframes go here */ } -@keyframe 'validString' { +@keyframes 'validString' { /* keyframes go here */ } ``` @@ -59,7 +59,7 @@ Such values are used without quotes: } ``` -## CSS-wide values +## CSS-wide keywords In addition to the pre-defined keywords that are part of the specification for a property, all CSS properties accept the CSS-wide, or "global", property values {{cssxref("initial")}}, {{cssxref("inherit")}}, {{cssxref("unset")}}, {{cssxref("revert")}}, and {{cssxref("revert-layer")}}, which explicitly specify defaulting behaviors. diff --git a/files/en-us/web/css/css_values_and_units/value_definition_syntax/index.md b/files/en-us/web/css/css_values_and_units/value_definition_syntax/index.md index 41d92a8c9241e0c..5d593d01928f738 100644 --- a/files/en-us/web/css/css_values_and_units/value_definition_syntax/index.md +++ b/files/en-us/web/css/css_values_and_units/value_definition_syntax/index.md @@ -50,9 +50,7 @@ Non-terminal data types are of two kinds: _Brackets_ enclose several entities, combinators, and multipliers, then transform them as a single component. They are used to **group components to bypass the precedence rules**. -```css -bold [ thin && <length> ] -``` +{{CSSSyntaxRaw(`example = bold [ thin && <length> ]`)}} This example matches the following values: @@ -68,9 +66,7 @@ But not: Placing several keywords, literals, or data types, next to one another, only separated by one or several spaces, is called _juxtaposition_. All juxtaposed components are **mandatory and should appear in the exact order**. -```css -bold <length>, thin -``` +{{CSSSyntaxRaw(`example = bold <length>, thin`)}} This example matches the following values: @@ -89,9 +85,7 @@ But not: Separating two or more components, by a _double ampersand_, `&&`, means that all these entities are **mandatory but may appear in any order**. -```css -bold && <length> -``` +{{CSSSyntaxRaw(`example = bold && <length>`)}} This example matches the following values: @@ -112,15 +106,13 @@ But not: Separating two or more components by a _double bar_, `||`, means that all entities are options: **at least one must be present, and they may appear in any order**. Typically this is used to define the different values of a [shorthand property](/en-US/docs/Web/CSS/CSS_cascade/Shorthand_properties). -```css -<'border-width'> || <'border-style'> || <'border-color'> -``` +{{CSSSyntaxRaw(`example = <number> || <length> || <color>`)}} This example matches the following values: -- `1em solid blue` +- `1em 1 blue` - `blue 1em` -- `solid 1px yellow` +- `1 1px yellow` But not: @@ -134,9 +126,7 @@ But not: Separating two or more entities by a _single bar_, `|`, means that all entities are exclusive options: **exactly one of these options must be present**. This is typically used to separate a list of possible keywords. -```css -<percentage> | <length> | left | center | right | top | bottom -``` +{{CSSSyntaxRaw(`example = <percentage> | <length> | left | center | right | top | bottom`)}} This example matches the following values: @@ -167,9 +157,7 @@ Multipliers cannot be added and have precedence over all combinators. The _asterisk multiplier_ indicates that the entity may appear **zero, one or several times**. -```css -bold smaller* -``` +{{CSSSyntaxRaw(`example = bold smaller*`)}} This example matches the following values: @@ -186,9 +174,7 @@ But not: The _plus multiplier_ indicates that the entity may appear **one or several times**. -```css -bold smaller+ -``` +{{CSSSyntaxRaw(`example = bold smaller+`)}} This example matches the following values: @@ -205,9 +191,7 @@ But not: The _question mark multiplier_ indicates that the entity is optional, and **must appear zero or one time**. -```css -bold smaller? -``` +{{CSSSyntaxRaw(`example = bold smaller?`)}} This example matches the following values: @@ -223,9 +207,7 @@ But not: The _curly braces multiplier_, enclosing two integers separated by a comma, A and B, indicates that the entity **must appear at least A times and at most B times**. -```css -bold smaller{1,3} -``` +{{CSSSyntaxRaw(`example = bold smaller{1,3}`)}} This example matches the following values: @@ -243,9 +225,7 @@ But not: The _hash mark multiplier_ indicates that the entity may be repeated one or more times (for example, the plus multiplier), but each occurrence is separated by a comma (','). -```css -bold smaller# -``` +{{CSSSyntaxRaw(`example = bold smaller#`)}} This example matches the following values: @@ -261,9 +241,7 @@ But not: The hash mark may optionally be followed by curly braces to indicate how many times the entity repeats. -```css -bold smaller#{1,3} -``` +{{CSSSyntaxRaw(`example = bold smaller#{1,3}`)}} This example matches the following values: @@ -275,9 +253,7 @@ But not: - `bold smaller, smaller, smaller, smaller`, as `smaller` must appear at most three times. -```css -bold smaller#{2} -``` +{{CSSSyntaxRaw(`example = bold smaller#{2}`)}} This example matches the following value: @@ -291,9 +267,7 @@ But not: The _exclamation point multiplier_ after a group indicates that the group is required, and must produce at least one value; even if the grammar of the items within the group would otherwise allow the entire contents to be omitted, at least one component value must not be omitted. -```css -[ bold? smaller? ]! -``` +{{CSSSyntaxRaw(`example = [ bold? smaller? ]!`)}} This example matches the following values: @@ -311,13 +285,11 @@ But not: Some types can accept numeric values within a certain range. For example, the [`column-count`](/en-US/docs/Web/CSS/column-count) property can accept an integer value between positive 1 and infinity, inclusive. The corresponding syntax looks like this: -```plain -<integer [1,∞]> -``` +{{CSSSyntaxRaw(`example = <integer [1,∞]>`)}} Any value outside this specified range causes the whole declaration to be invalid, therefore the browser will ignore it. -The _bracketed range notation_ `[min, max]` indicates an inclusive range between a `min` and `max` value. This notation is used in numeric type notations and can include units, e.g. `<angle [0,180deg]>`. Positive and negative Infinity (-∞ and ∞) must not have units specified. Types specified in units can have zero values specified with or without units, for example `<time [0s,10s]>` or `<time [0,10s]>`. +The _bracketed range notation_ `[min, max]` indicates an inclusive range between a `min` and `max` value. This notation is used in numeric type notations and can include units, e.g., `<angle [0,180deg]>`. Positive and negative Infinity (-∞ and ∞) must not have units specified. Types specified in units can have zero values specified with or without units, for example `<time [0s,10s]>` or `<time [0,10s]>`. Here are some more examples: @@ -448,14 +420,14 @@ Here are some more examples: - [Specificity](/en-US/docs/Web/CSS/CSS_cascade/Specificity) - [Inheritance](/en-US/docs/Web/CSS/CSS_cascade/Inheritance) - [Box model](/en-US/docs/Web/CSS/CSS_box_model/Introduction_to_the_CSS_box_model) - - [Layout modes](/en-US/docs/Web/CSS/Layout_mode) - - [Visual formatting model](/en-US/docs/Web/CSS/Visual_formatting_model) + - [Layout modes](/en-US/docs/Glossary/Layout_mode) + - [Visual formatting model](/en-US/docs/Web/CSS/CSS_display/Visual_formatting_model) - [Margin collapsing](/en-US/docs/Web/CSS/CSS_box_model/Mastering_margin_collapsing) - Values - - [Initial values](/en-US/docs/Web/CSS/CSS_cascade/initial_value) - - [Computed values](/en-US/docs/Web/CSS/CSS_cascade/computed_value) - - [Used values](/en-US/docs/Web/CSS/CSS_cascade/used_value) - - [Actual values](/en-US/docs/Web/CSS/CSS_cascade/actual_value) + - [Initial values](/en-US/docs/Web/CSS/CSS_cascade/Value_processing#initial_value) + - [Computed values](/en-US/docs/Web/CSS/CSS_cascade/Value_processing#computed_value) + - [Used values](/en-US/docs/Web/CSS/CSS_cascade/Value_processing#used_value) + - [Actual values](/en-US/docs/Web/CSS/CSS_cascade/Value_processing#actual_value) - **Value definition syntax** - [Shorthand properties](/en-US/docs/Web/CSS/CSS_cascade/Shorthand_properties) - - [Replaced elements](/en-US/docs/Web/CSS/Replaced_element) + - {{glossary("Replaced elements")}} diff --git a/files/en-us/web/css/css_view_transitions/index.md b/files/en-us/web/css/css_view_transitions/index.md index 2fa00d8b88e272b..f701fc41c584241 100644 --- a/files/en-us/web/css/css_view_transitions/index.md +++ b/files/en-us/web/css/css_view_transitions/index.md @@ -15,10 +15,8 @@ The **CSS view transitions** module defines the behavior of the [View Transition ### Properties -- {{cssxref("view-transition-name")}} {{experimental_inline}} - -> [!NOTE] -> This module also defines the `view-transition-class` property, but it is currently not supported in any browser. +- {{cssxref("view-transition-class")}} +- {{cssxref("view-transition-name")}} ### At-rules and descriptors @@ -27,14 +25,13 @@ The **CSS view transitions** module defines the behavior of the [View Transition ### Selectors and pseudo-elements -- {{cssxref("::view-transition")}} {{experimental_inline}} -- {{cssxref("::view-transition-image-pair()")}} {{experimental_inline}} -- {{cssxref("::view-transition-group()")}} {{experimental_inline}} -- {{cssxref("::view-transition-new()")}} {{experimental_inline}} -- {{cssxref("::view-transition-old()")}} {{experimental_inline}} - -> [!NOTE] -> This module also defines the `:active-view-transition` and `:active-view-transition-type()` pseudo-classes, but they are currently not supported in any browser. +- {{cssxref(":active-view-transition")}} +- {{cssxref(":active-view-transition-type()")}} +- {{cssxref("::view-transition")}} +- {{cssxref("::view-transition-image-pair()")}} +- {{cssxref("::view-transition-group()")}} +- {{cssxref("::view-transition-new()")}} +- {{cssxref("::view-transition-old()")}} ### Interfaces diff --git a/files/en-us/web/css/css_writing_modes/index.md b/files/en-us/web/css/css_writing_modes/index.md index 7140b88a6c3f7f3..2ea66d1096c83b6 100644 --- a/files/en-us/web/css/css_writing_modes/index.md +++ b/files/en-us/web/css/css_writing_modes/index.md @@ -14,7 +14,6 @@ The **CSS writing modes** module defines various international writing modes, su ### Properties - {{cssxref("direction")}} -- {{cssxref("glyph-orientation-horizontal")}} - {{cssxref("text-combine-upright")}} - {{cssxref("text-orientation")}} - {{cssxref("unicode-bidi")}} @@ -28,3 +27,7 @@ The **CSS writing modes** module defines various international writing modes, su ## Specifications {{Specifications}} + +## See also + +- [Handling different text directions](/en-US/docs/Learn_web_development/Core/Styling_basics/Handling_different_text_directions) diff --git a/files/en-us/web/css/css_writing_modes/vertical_controls/index.md b/files/en-us/web/css/css_writing_modes/vertical_controls/index.md index ded86d06e127a6f..391a0060344c9d5 100644 --- a/files/en-us/web/css/css_writing_modes/vertical_controls/index.md +++ b/files/en-us/web/css/css_writing_modes/vertical_controls/index.md @@ -8,10 +8,10 @@ page-type: guide The guide explains how to use the CSS {{cssxref("writing-mode")}} and {{cssxref("direction")}} properties to create and configure vertical form controls. This includes: -- [`<input type="range">`](/en-US/docs/Web/HTML/Element/input/range) sliders, {{htmlelement("progress")}} bars, and {{htmlelement("meter")}} elements. +- [`<input type="range">`](/en-US/docs/Web/HTML/Reference/Elements/input/range) sliders, {{htmlelement("progress")}} bars, and {{htmlelement("meter")}} elements. - {{htmlelement("select")}} elements. -- {{htmlelement("button")}} elements and button input types such as [`<input type="button">`](/en-US/docs/Web/HTML/Element/input/button), [`<input type="reset">`](/en-US/docs/Web/HTML/Element/input/reset), and [`<input type="submit">`](/en-US/docs/Web/HTML/Element/input/submit). -- {{htmlelement("textarea")}} elements and text-based input types such as [`<input type="text">`](/en-US/docs/Web/HTML/Element/input/text), [`<input type="datetime-local">`](/en-US/docs/Web/HTML/Element/input/datetime-local), and [`<input type="url">`](/en-US/docs/Web/HTML/Element/input/url). +- {{htmlelement("button")}} elements and button input types such as [`<input type="button">`](/en-US/docs/Web/HTML/Reference/Elements/input/button), [`<input type="reset">`](/en-US/docs/Web/HTML/Reference/Elements/input/reset), and [`<input type="submit">`](/en-US/docs/Web/HTML/Reference/Elements/input/submit). +- {{htmlelement("textarea")}} elements and text-based input types such as [`<input type="text">`](/en-US/docs/Web/HTML/Reference/Elements/input/text), [`<input type="datetime-local">`](/en-US/docs/Web/HTML/Reference/Elements/input/datetime-local), and [`<input type="url">`](/en-US/docs/Web/HTML/Reference/Elements/input/url). ## General technique @@ -47,7 +47,7 @@ Let's have a look at creating vertical range sliders, meters, and progress bars. ### Basic example -A typical set of visual [`<input type="range">`](/en-US/docs/Web/HTML/Element/input/range) slider, {{htmlelement("progress")}}, and {{htmlelement("meter")}} controls is created like this: +A typical set of visual [`<input type="range">`](/en-US/docs/Web/HTML/Reference/Elements/input/range) slider, {{htmlelement("progress")}}, and {{htmlelement("meter")}} controls is created like this: ```html <form> @@ -60,7 +60,7 @@ A typical set of visual [`<input type="range">`](/en-US/docs/Web/HTML/Element/in ``` > [!NOTE] -> Best practice is to include a {{htmlelement("label")}} element for each form control, to associate a meaningful text description with each field for accessibility purposes (see [Meaningful text labels](/en-US/docs/Learn_web_development/Core/Accessibility/HTML#meaningful_text_labels) for more information). We haven't done that here, as this article focuses purely on aspects of the form controls' visual rendering, but you should make sure you do so in production code. +> Best practice is to include a {{htmlelement("label")}} element for each form control, to associate a meaningful text description with each field for accessibility purposes (see [Use meaningful text labels](/en-US/docs/Learn_web_development/Core/Accessibility/HTML#use_meaningful_text_labels) for more information). We haven't done that here, as this article focuses purely on aspects of the form controls' visual rendering, but you should make sure you do so in production code. To display the controls vertically, we can use CSS like this: @@ -116,7 +116,7 @@ In older browsers that do not support the creation of vertical form controls wit - The non-standard [`appearance: slider-vertical`](/en-US/docs/Web/CSS/appearance) property can be used in older versions of Safari and Chrome. - The non-standard `orient="vertical"` attribute can be added to the `<input type="range">` element itself in older versions of Firefox. -The HTML for this example includes an [`<input type="range">`](/en-US/docs/Web/HTML/Element/input/range) slider only, with `orient="vertical"` added to make it display vertically in older Firefox versions: +The HTML for this example includes an [`<input type="range">`](/en-US/docs/Web/HTML/Reference/Elements/input/range) slider only, with `orient="vertical"` added to make it display vertically in older Firefox versions: ```html <form> @@ -274,7 +274,7 @@ The result looks like so: ## Buttons -This section shows how to handle vertical {{htmlelement("button")}} elements. Note that while we have only used a `<button>` element in the examples below, the behavior is the same for other elements that create buttons, such as [`<input>`](/en-US/docs/Web/HTML/Element/input) types of [`button`](/en-US/docs/Web/HTML/Element/input/button), [`reset`](/en-US/docs/Web/HTML/Element/input/reset), and [`submit`](/en-US/docs/Web/HTML/Element/input/submit). +This section shows how to handle vertical {{htmlelement("button")}} elements. Note that while we have only used a `<button>` element in the examples below, the behavior is the same for other elements that create buttons, such as [`<input>`](/en-US/docs/Web/HTML/Reference/Elements/input) types of [`button`](/en-US/docs/Web/HTML/Reference/Elements/input/button), [`reset`](/en-US/docs/Web/HTML/Reference/Elements/input/reset), and [`submit`](/en-US/docs/Web/HTML/Reference/Elements/input/submit). ### Basic button example @@ -360,7 +360,7 @@ The result looks like so: ## Text-based form controls -Last but not least, we'll look at handling vertical {{htmlelement("textarea")}}s and textual `<input>` types. Note that, while the only `<input>` type we are including is an `<input type="text">` element in the examples below, the behavior is the same for other textual [`<input>`](/en-US/docs/Web/HTML/Element/input) types: [`password`](/en-US/docs/Web/HTML/Element/input/button), [`number`](/en-US/docs/Web/HTML/Element/input/reset), [`url`](/en-US/docs/Web/HTML/Element/input/submit), etc. +Last but not least, we'll look at handling vertical {{htmlelement("textarea")}}s and textual `<input>` types. Note that, while the only `<input>` type we are including is an `<input type="text">` element in the examples below, the behavior is the same for other textual [`<input>`](/en-US/docs/Web/HTML/Reference/Elements/input) types: [`password`](/en-US/docs/Web/HTML/Reference/Elements/input/button), [`number`](/en-US/docs/Web/HTML/Reference/Elements/input/reset), [`url`](/en-US/docs/Web/HTML/Reference/Elements/input/submit), etc. ### Basic text input and textarea example @@ -471,7 +471,7 @@ The result looks like so: ## See also -- The [`<input>`](/en-US/docs/Web/HTML/Element/input) element. +- The [`<input>`](/en-US/docs/Web/HTML/Reference/Elements/input) element. - Other relevant elements: {{htmlelement("button")}}, {{htmlelement("meter")}}, {{htmlelement("progress")}}, and {{htmlelement("select")}}. - [Learn: Handling different text directions](/en-US/docs/Learn_web_development/Core/Styling_basics/Handling_different_text_directions) - [Styling web forms](/en-US/docs/Learn_web_development/Extensions/Forms/Styling_web_forms) diff --git a/files/en-us/web/css/cssom_view/coordinate_systems/index.md b/files/en-us/web/css/cssom_view/coordinate_systems/index.md index 03dac4296a1868a..aef7a9f44777074 100644 --- a/files/en-us/web/css/cssom_view/coordinate_systems/index.md +++ b/files/en-us/web/css/cssom_view/coordinate_systems/index.md @@ -34,7 +34,7 @@ The origin of the "client", "page", and "viewport" coordinates systems are highl Coordinates specified using the "offset" model use the top-left corner of the element being examined, or on which an event has occurred. -For example, when a {{domxref("MouseEvent", "mouse event")}} occurs, the position of the mouse as specified in the event's {{domxref("MouseEvent.offsetX", "offsetX")}} and {{domxref("MouseEvent.offsetY", "offsetY")}} properties are given relative to the top-left corner of the node to which the event has been delivered. The origin is inset by the _padding edge_, the edge between the padding area and the border area. +For example, when a [mouse event](/en-US/docs/Web/API/MouseEvent) occurs, the position of the mouse as specified in the event's {{domxref("MouseEvent.offsetX", "offsetX")}} and {{domxref("MouseEvent.offsetY", "offsetY")}} properties are given relative to the top-left corner of the node to which the event has been delivered. The origin is inset by the _padding edge_, the edge between the padding area and the border area. ### Viewport diff --git a/files/en-us/web/css/cssom_view/index.md b/files/en-us/web/css/cssom_view/index.md index 7b5d1bbc517fb4b..60abd2f3ead3dc0 100644 --- a/files/en-us/web/css/cssom_view/index.md +++ b/files/en-us/web/css/cssom_view/index.md @@ -37,38 +37,12 @@ The **CSSOM view** module lets you manipulate the visual view of a document, inc ### Interfaces - {{domxref("MediaQueryList")}} - - {{domxref("MediaQueryList.matches", "matches")}} - - {{domxref("MediaQueryList.media", "media")}} - - {{domxref("MediaQueryList.addListener", "addListener()")}} - - {{domxref("MediaQueryList.removeListener", "removeListener()")}} - - {{domxref("MediaQueryList.onchange", "onchange")}} - {{domxref("MediaQueryListEvent")}} - - {{domxref("MediaQueryListEvent.media", "media")}} - - {{domxref("MediaQueryListEvent.matches", "matches")}} - {{domxref("Screen")}} - - {{domxref("Screen.availHeight", "availHeight")}} - - {{domxref("Screen.availWidth", "availWidth")}} - - {{domxref("Screen.colorDepth", "colorDepth")}} - - {{domxref("Screen.height", "height")}} - - {{domxref("Screen.pixelDepth", "pixelDepth")}} - - {{domxref("Screen.width", "width")}} - {{domxref("CaretPosition")}} - - {{domxref("CaretPosition.offsetNode", "offsetNode")}} - - {{domxref("CaretPosition.offset", "offset")}} - - {{domxref("CaretPosition.getClientRect", "getClientRect()")}} - {{domxref("VisualViewport")}} - - {{domxref("VisualViewport.height", "height")}} - - {{domxref("VisualViewport.offsetLeft", "offsetLeft")}} - - {{domxref("VisualViewport.offsetTop", "offsetTop")}} - - {{domxref("VisualViewport.onresize", "onresize")}} - - {{domxref("VisualViewport.onscroll", "onscroll")}} - - {{domxref("VisualViewport.onscrollend", "onscrollend")}} - - {{domxref("VisualViewport.pageLeft", "pageLeft")}} - - {{domxref("VisualViewport.pageTop", "pageTop")}} - - {{domxref("VisualViewport.scale", "scale")}} - - {{domxref("VisualViewport.width", "width")}} - -### Inteface extensions + +### Interface extensions This module adds properties and methods to interfaces defined in other specifications. @@ -140,7 +114,7 @@ This module adds properties and methods to interfaces defined in other specifica - {{domxref("MouseEvent.x", "x")}} - {{domxref("MouseEvent.y", "y")}} -This module define geometric utility methods which will apply to the {{domxref("Text")}}, {{domxref("Element")}}, {{domxref("CSSPseudoElement")}}, and {{domxref("Document")}} interfaces. These `GeometryUtils` features are not yet implemented in any browsers. +This module defines geometric utility methods that apply to the {{domxref("Text")}}, {{domxref("Element")}}, {{domxref("CSSPseudoElement")}}, and {{domxref("Document")}} interfaces. These `GeometryUtils` features are not yet implemented in any browser. ## Guides diff --git a/files/en-us/web/css/cssom_view/viewport_concepts/index.md b/files/en-us/web/css/cssom_view/viewport_concepts/index.md index 1e60f3c99af9f87..7cfcd386aea0bef 100644 --- a/files/en-us/web/css/cssom_view/viewport_concepts/index.md +++ b/files/en-us/web/css/cssom_view/viewport_concepts/index.md @@ -38,7 +38,7 @@ window.outerHeight; /* 900 */ There are several DOM properties that can help you query viewport size, and other similar lengths: -- The document element's {{DOMxRef("Element.clientWidth")}} is the inner width of a document in [CSS pixels](/en-US/docs/Web/HTML/Viewport_meta_tag#screen_density), including padding (but not borders, margins, or vertical scrollbars, if present). **This is the viewport width**. +- The document element's {{DOMxRef("Element.clientWidth")}} is the inner width of a document in [CSS pixels](/en-US/docs/Web/HTML/Guides/Viewport_meta_element#screen_density), including padding (but not borders, margins, or vertical scrollbars, if present). **This is the viewport width**. - The {{DOMxRef("Window.innerWidth")}} is the width, in CSS pixels, of the browser window viewport including, if rendered, the vertical scrollbar. - The {{DOMxRef("Window.outerWidth")}} is the width of the outside of the browser window including all the window {{glossary("chrome")}}. @@ -119,7 +119,7 @@ If the above CSS is included in the iframe, the paragraphs will become red when #### SVG -In an [SVG](/en-US/docs/Web/SVG/) document, the viewport is the visible area of the SVG image. You can set any height and width on an {{htmlelement("SVG")}}, but the whole image might not be visible. The area that is visible is called the viewport. The size of the viewport can be defined using the width and height attributes of the {{SVGElement("svg")}} element. +In an [SVG](/en-US/docs/Web/SVG) document, the viewport is the visible area of the SVG image. You can set any height and width on an {{SVGElement("svg")}}, but the whole image might not be visible. The area that is visible is called the viewport. The size of the viewport can be defined using the width and height attributes of the `<svg>` element. ```html <svg height="300" width="400"></svg> @@ -127,7 +127,7 @@ In an [SVG](/en-US/docs/Web/SVG/) document, the viewport is the visible area of In this example, the viewport has an {{glossary("aspect ratio")}} of 3:4 and is, by default, 400 by 300 units, with a unit generally being a CSS pixel. -SVG also has an internal [coordinate system](/en-US/docs/Web/CSS/CSSOM_view/Coordinate_systems) defined via the [viewBox](/en-US/docs/Web/SVG/Attribute/viewBox) attribute, which is not related to this viewport discussion. +SVG also has an internal [coordinate system](/en-US/docs/Web/CSS/CSSOM_view/Coordinate_systems) defined via the [viewBox](/en-US/docs/Web/SVG/Reference/Attribute/viewBox) attribute, which is not related to this viewport discussion. If you include an SVG file in your HTML, the viewport of the SVG is the initial containing block, or the width and height of the SVG container. Using the {{CSSxRef("@media")}} query in your SVG's CSS is relative to that container, not the browser. @@ -158,4 +158,4 @@ The `width` property controls the size of the viewport. It should preferably be - [CSSOM view](/en-US/docs/Web/CSS/CSSOM_view) module - [Visual Viewport API](/en-US/docs/Web/API/Visual_Viewport_API) - {{HTMLElement("meta")}}, specifically `<meta name="viewport">` -- [Using the viewport meta tag to control layout on mobile browsers](/en-US/docs/Web/HTML/Viewport_meta_tag) +- [Using the viewport meta tag to control layout on mobile browsers](/en-US/docs/Web/HTML/Guides/Viewport_meta_element) diff --git a/files/en-us/web/css/cursor/index.md b/files/en-us/web/css/cursor/index.md index b04d9f2d75b8977..5ce65821e4df83c 100644 --- a/files/en-us/web/css/cursor/index.md +++ b/files/en-us/web/css/cursor/index.md @@ -12,7 +12,53 @@ The **`cursor`** [CSS](/en-US/docs/Web/CSS) property sets the mouse cursor, if a The cursor setting should inform users of the mouse operations that can be performed at the current location, including: text selection, activating help or context menus, copying content, resizing tables, and so on. You can specify either the _type_ of cursor using a keyword, or load a specific icon to use (with optional fallback images and mandatory keyword as a final fallback). -{{EmbedInteractiveExample("pages/css/cursor.html")}} +{{InteractiveExample("CSS Demo: cursor")}} + +```css interactive-example-choice +cursor: help; +``` + +```css interactive-example-choice +cursor: wait; +``` + +```css interactive-example-choice +cursor: crosshair; +``` + +```css interactive-example-choice +cursor: not-allowed; +``` + +```css interactive-example-choice +cursor: zoom-in; +``` + +```css interactive-example-choice +cursor: grab; +``` + +```html interactive-example +<section class="default-example container" id="default-example"> + <div id="example-element"> + Move over this element to see the cursor style. + </div> +</section> +``` + +```css interactive-example +#example-element { + display: flex; + background-color: #1766aa; + color: white; + height: 180px; + width: 360px; + justify-content: center; + align-items: center; + font-size: 14pt; + padding: 5px; +} +``` ## Syntax diff --git a/files/en-us/web/css/custom-ident/index.md b/files/en-us/web/css/custom-ident/index.md index 80e15aa0f023018..16756eccf1309df 100644 --- a/files/en-us/web/css/custom-ident/index.md +++ b/files/en-us/web/css/custom-ident/index.md @@ -119,8 +119,8 @@ To prevent ambiguity, each property that uses `<custom-ident>` forbids the use o - `disclosure-open` - `disclosure-close` -- {{CSSxRef("grid-row-start")}}, {{CSSxRef("grid-row-end")}}, {{CSSxRef("grid-column-start")}}, {{CSSxRef("grid-column-end")}} - - : Forbids the `span` value. +- {{CSSxRef("grid-row-start")}}, {{CSSxRef("grid-row-end")}}, {{CSSxRef("grid-column-start")}}, {{CSSxRef("grid-column-end")}}, {{CSSxRef("grid-template-rows")}}, {{CSSxRef("grid-template-columns")}} + - : Forbids the `span` and `auto` values. - {{CSSxRef("view-transition-name")}} - : Forbids the global CSS values (`unset`, `initial`, and `inherit`), as well as `none`. - {{CSSxRef("will-change")}} diff --git a/files/en-us/web/css/d/index.md b/files/en-us/web/css/d/index.md index 8b56d0d527721f0..2f8a12d3ec29db5 100644 --- a/files/en-us/web/css/d/index.md +++ b/files/en-us/web/css/d/index.md @@ -38,7 +38,7 @@ The value is either a {{cssxref("basic-shape/path", "path()")}} function with a - `none` - : No path is drawn. - `path(<string>)` - - : A `path()` function with a quoted [data string](/en-US/docs/Web/SVG/Attribute/d) parameter. The data string defines an [SVG path](/en-US/docs/Web/SVG/Element/path). The SVG path data string contains [path commands](/en-US/docs/Web/SVG/Attribute/d#path_commands) that implicitly use pixel units. An empty path is considered invalid. + - : A `path()` function with a quoted [data string](/en-US/docs/Web/SVG/Reference/Attribute/d) parameter. The data string defines an [SVG path](/en-US/docs/Web/SVG/Reference/Element/path). The SVG path data string contains [path commands](/en-US/docs/Web/SVG/Reference/Attribute/d#path_commands) that implicitly use pixel units. An empty path is considered invalid. ## Formal definition diff --git a/files/en-us/web/css/direction/index.md b/files/en-us/web/css/direction/index.md index fe7fbe964cc2980..33ae8469f57e4b7 100644 --- a/files/en-us/web/css/direction/index.md +++ b/files/en-us/web/css/direction/index.md @@ -8,13 +8,49 @@ browser-compat: css.properties.direction {{CSSRef}} > [!WARNING] -> Where possible, authors are encouraged to avoid using the `direction` CSS property and use the HTML [`dir`](/en-US/docs/Web/HTML/Global_attributes/dir) global attribute instead. +> Where possible, authors are encouraged to avoid using the `direction` CSS property and use the HTML [`dir`](/en-US/docs/Web/HTML/Reference/Global_attributes/dir) global attribute instead. The **`direction`** [CSS](/en-US/docs/Web/CSS) property sets the direction of text, table and grid columns, and horizontal overflow. Use `rtl` for languages written from right to left (like Hebrew or Arabic), and `ltr` for those written from left to right (like English and most other languages). -{{EmbedInteractiveExample("pages/css/direction.html")}} +{{InteractiveExample("CSS Demo: direction")}} -Note that text direction is usually defined within a document (e.g., with [HTML's `dir` attribute](/en-US/docs/Web/HTML/Global_attributes/dir)) rather than through direct use of the `direction` property. +```css interactive-example-choice +direction: ltr; +``` + +```css interactive-example-choice +direction: rtl; +``` + +```html interactive-example +<section class="default-example" id="default-example"> + <div class="transition-all" id="example-element"> + <div>1</div> + <div>2</div> + <div>3</div> + <div>4</div> + </div> +</section> +``` + +```css interactive-example +#example-element { + border: 1px solid #c5c5c5; + padding: 0.75em; + width: 80%; + max-height: 300px; + display: flex; +} + +#example-element > div { + background-color: rgba(0, 0, 255, 0.2); + border: 3px solid blue; + margin: 10px; + flex: 1; +} +``` + +Note that text direction is usually defined within a document (e.g., with [HTML's `dir` attribute](/en-US/docs/Web/HTML/Reference/Global_attributes/dir)) rather than through direct use of the `direction` property. The property sets the base text direction of block-level elements and the direction of embeddings created by the {{Cssxref("unicode-bidi")}} property. It also sets the default alignment of text, block-level elements, and the direction that cells flow within a table or grid row. @@ -94,5 +130,6 @@ blockquote { - {{CSSxRef("unicode-bidi")}} - {{CSSxRef("writing-mode")}} - SVG {{SVGAttr("direction")}} attribute -- The HTML [`dir`](/en-US/docs/Web/HTML/Global_attributes/dir) global attribute +- The HTML [`dir`](/en-US/docs/Web/HTML/Reference/Global_attributes/dir) global attribute - [Creating vertical form controls](/en-US/docs/Web/CSS/CSS_writing_modes/Vertical_controls) +- [Handling different text directions](/en-US/docs/Learn_web_development/Core/Styling_basics/Handling_different_text_directions) diff --git a/files/en-us/web/css/display-internal/index.md b/files/en-us/web/css/display-internal/index.md index 83b261708b034db..ac379852e4036b3 100644 --- a/files/en-us/web/css/display-internal/index.md +++ b/files/en-us/web/css/display-internal/index.md @@ -58,7 +58,7 @@ Valid `<display-internal>` values: ### CSS tables example -The following example demonstrates laying out a simple form using CSS table layout. +The following example demonstrates laying out a form using CSS table layout. #### HTML diff --git a/files/en-us/web/css/display/index.md b/files/en-us/web/css/display/index.md index e6a35b759db2b0c..fdb7e7ffca3e581 100644 --- a/files/en-us/web/css/display/index.md +++ b/files/en-us/web/css/display/index.md @@ -7,11 +7,72 @@ browser-compat: css.properties.display {{CSSRef}} -The **`display`** [CSS](/en-US/docs/Web/CSS) property sets whether an element is treated as a [block or inline box](/en-US/docs/Web/CSS/CSS_display/flow_layout) and the layout used for its children, such as [flow layout](/en-US/docs/Web/CSS/CSS_display/flow_layout), [grid](/en-US/docs/Web/CSS/CSS_grid_layout) or [flex](/en-US/docs/Web/CSS/CSS_flexible_box_layout). +The **`display`** [CSS](/en-US/docs/Web/CSS) property sets whether an element is treated as a [block or inline box](/en-US/docs/Web/CSS/CSS_display/Flow_layout) and the layout used for its children, such as [flow layout](/en-US/docs/Web/CSS/CSS_display/Flow_layout), [grid](/en-US/docs/Web/CSS/CSS_grid_layout) or [flex](/en-US/docs/Web/CSS/CSS_flexible_box_layout). -Formally, the **`display`** property sets an element's inner and outer _display types_. The outer type sets an element's participation in [flow layout](/en-US/docs/Web/CSS/CSS_display/flow_layout); the inner type sets the layout of children. Some values of `display` are fully defined in their own individual specifications; for example the detail of what happens when `display: flex` is declared is defined in the CSS Flexible Box Model specification. +Formally, the **`display`** property sets an element's inner and outer _display types_. The outer type sets an element's participation in [flow layout](/en-US/docs/Web/CSS/CSS_display/Flow_layout); the inner type sets the layout of children. Some values of `display` are fully defined in their own individual specifications; for example the detail of what happens when `display: flex` is declared is defined in the CSS Flexible Box Model specification. -{{EmbedInteractiveExample("pages/css/display.html")}} +{{InteractiveExample("CSS Demo: display")}} + +```css interactive-example-choice +display: block; +``` + +```css interactive-example-choice +display: inline-block; +``` + +```css interactive-example-choice +display: none; +``` + +```css interactive-example-choice +display: flex; +``` + +```css interactive-example-choice +display: grid; +``` + +```html interactive-example +<p> + Apply different <code>display</code> values on the dashed orange-bordered + <code>div</code>, which contains three child elements. +</p> +<section class="default-example" id="default-example"> + <div class="example-container"> + Some text A. + <div id="example-element"> + <div class="child">Child 1</div> + <div class="child">Child 2</div> + <div class="child">Child 3</div> + </div> + Some text B. + </div> +</section> +``` + +```css interactive-example +.example-container { + width: 100%; + height: 100%; +} + +code { + background: #8888; +} + +#example-element { + border: 3px dashed orange; +} + +.child { + display: inline-block; + padding: 0.5em 1em; + background-color: #ccccff; + border: 1px solid #ababab; + color: black; +} +``` ## Syntax @@ -226,15 +287,6 @@ This can also be specified using the legacy single value: For more information on these changes, see the [Using the multi-keyword syntax with CSS display](/en-US/docs/Web/CSS/CSS_display/multi-keyword_syntax_of_display) guide. -### Global - -```css -/* Global values */ -display: inherit; -display: initial; -display: unset; -``` - ## Description The individual pages for the different types of value that `display` can have set on it feature multiple examples of those values in action — see the [Syntax](#syntax) section. In addition, see the following material, which covers the various values of display in depth. @@ -317,7 +369,7 @@ In some browsers, changing the `display` value of a {{HTMLElement("table")}} ele - [Short note on what CSS display properties do to table semantics — The Paciello Group](https://www.tpgi.com/short-note-on-what-css-display-properties-do-to-table-semantics/) - [Hidden content for better a11y | Go Make Things](https://gomakethings.com/hidden-content-for-better-a11y/) -- [MDN Understanding WCAG, Guideline 1.3 explanations](/en-US/docs/Web/Accessibility/Understanding_WCAG/Perceivable#guideline_1.3_%e2%80%94_create_content_that_can_be_presented_in_different_ways) +- [MDN Understanding WCAG, Guideline 1.3 explanations](/en-US/docs/Web/Accessibility/Guides/Understanding_WCAG/Perceivable#guideline_1.3_%e2%80%94_create_content_that_can_be_presented_in_different_ways) - [Understanding Success Criterion 1.3.1 | W3C Understanding WCAG 2.0](https://www.w3.org/TR/UNDERSTANDING-WCAG20/content-structure-separation-programmatic.html) ## Formal definition diff --git a/files/en-us/web/css/dominant-baseline/index.md b/files/en-us/web/css/dominant-baseline/index.md index 5bda141450cca16..6f58ca51e7043d6 100644 --- a/files/en-us/web/css/dominant-baseline/index.md +++ b/files/en-us/web/css/dominant-baseline/index.md @@ -20,7 +20,7 @@ The `dominant-baseline` property is used to determine or re-determine a _scaled- Some values of `dominant-baseline` re-determine all three values. Others only re-establish the baseline-table font-size. When the initial value, `auto`, would give an undesired result, this property can be used to explicitly set the desired scaled-baseline-table. > [!NOTE] -> The `dominant-baseline` property only has an effect on the {{SVGElement("text")}}, {{SVGElement("textPath")}}, {{SVGElement("tref")}}, and {{SVGElement("tspan")}} SVG elements. +> The `dominant-baseline` property only has an effect on the {{SVGElement("text")}}, {{SVGElement("textPath")}}, and {{SVGElement("tspan")}} SVG elements. ## Syntax @@ -54,7 +54,7 @@ dominant-baseline: unset; If the {{SVGAttr("writing-mode")}} is horizontal, then the value of the dominant-baseline component is `alphabetic`. Otherwise, if the {{SVGAttr("writing-mode")}} is vertical, then the value of the dominant-baseline component is `central`. - If this property is applied to a {{SVGElement("tspan")}}, {{SVGElement("tref")}}, or {{SVGElement("textPath")}} element, then the dominant-baseline and the baseline-table components remain the same as those of the parent text content element. + If this property is applied to a {{SVGElement("tspan")}}, or {{SVGElement("textPath")}} element, then the dominant-baseline and the baseline-table components remain the same as those of the parent text content element. If the computed {{SVGAttr("baseline-shift")}} value actually shifts the baseline, then the baseline-table font-size component is set to the value of the {{SVGAttr("font-size")}} attribute on the element on which the `dominant-baseline` attribute occurs, otherwise the baseline-table font-size remains the same as that of the element. diff --git a/files/en-us/web/css/empty-cells/index.md b/files/en-us/web/css/empty-cells/index.md index bc0d426096379a4..896a7e2f409417c 100644 --- a/files/en-us/web/css/empty-cells/index.md +++ b/files/en-us/web/css/empty-cells/index.md @@ -9,7 +9,50 @@ browser-compat: css.properties.empty-cells The **`empty-cells`** [CSS](/en-US/docs/Web/CSS) property sets whether borders and backgrounds appear around {{htmlelement("table")}} cells that have no visible content. -{{EmbedInteractiveExample("pages/css/empty-cells.html")}} +{{InteractiveExample("CSS Demo: empty-cells")}} + +```css interactive-example-choice +empty-cells: show; +``` + +```css interactive-example-choice +empty-cells: hide; +``` + +```html interactive-example +<section class="default-example" id="default-example"> + <table class="transition-all" id="example-element"> + <tr> + <th>Client Name</th> + <th>Age</th> + </tr> + <tr> + <td></td> + <td>25</td> + </tr> + <tr> + <td>Louise Q.</td> + <td></td> + </tr> + <tr> + <td>Owen B.</td> + <td></td> + </tr> + <tr> + <td>Stan L.</td> + <td>71</td> + </tr> + </table> +</section> +``` + +```css interactive-example +th, +td { + border: 2px solid #a19; + padding: 0.25rem 0.5rem; +} +``` This property has an effect only when the {{cssxref("border-collapse")}} property is `separate`. diff --git a/files/en-us/web/css/env/index.md b/files/en-us/web/css/env/index.md index 56c21c541596d2e..7704df2522cd73c 100644 --- a/files/en-us/web/css/env/index.md +++ b/files/en-us/web/css/env/index.md @@ -2,14 +2,14 @@ title: env() slug: Web/CSS/env page-type: css-function -browser-compat: css.properties.custom-property.env +browser-compat: css.types.env --- {{CSSRef}} The **`env()`** [CSS](/en-US/docs/Web/CSS) [function](/en-US/docs/Web/CSS/CSS_Values_and_Units/CSS_Value_Functions) can be used to insert the value of a user-agent defined environment variable into your CSS, in a similar fashion to the {{cssxref("var", "var()")}} function and [custom properties](/en-US/docs/Web/CSS/--*). The difference is that, as well as being user-agent defined rather than author-defined, environment variables are globally scoped to a document, whereas custom properties are scoped to the element(s) on which they are declared. -In addition, unlike custom properties, which cannot be used outside of declarations, the `env()` function can be used in place of any part of a property value, or any part of a descriptor (e.g. in [Media query rules](/en-US/docs/Web/CSS/@media)). As the spec evolves, it may also be usable in other places such as selectors. +In addition, unlike custom properties, which cannot be used outside of declarations, the `env()` function can be used in place of any part of a property value, or any part of a descriptor (e.g., in [Media query rules](/en-US/docs/Web/CSS/@media)). As the spec evolves, it may also be usable in other places such as selectors. Originally provided by the iOS browser to allow developers to place their content in a safe area of the viewport, the `safe-area-inset-*` values defined in the specification can be used to help ensure content is visible even to viewers using non‑rectangular displays. @@ -38,7 +38,7 @@ env(safe-area-inset-left, 1.4rem); - `safe-area-inset-top`, `safe-area-inset-right`, `safe-area-inset-bottom`, `safe-area-inset-left` - : The `safe-area-inset-*` variables are four environment variables that define a rectangle by its top, right, bottom, and left insets from the edge of the viewport, which is safe to put content into without risking it being cut off by the shape of a non‑rectangular display. For rectangular viewports, like your average laptop monitor, their value is equal to zero. For non-rectangular displays — like a round watch face — the four values set by the user agent form a rectangle such that all content inside the rectangle is visible. - `titlebar-area-x`, `titlebar-area-y`, `titlebar-area-width`, `titlebar-area-height` - - : The `titlebar-area-*` variables are useful for PWA installed on Desktop devices. When a desktop PWA uses the `window-controls-overlay` [display_override](/en-US/docs/Web/Progressive_web_apps/Manifest/Reference/display_override) value, then it can use the `titlebar-area-*` variables to make sure content doesn't overlap with the window control buttons (i.e. minimize, maximize, and close). + - : The `titlebar-area-*` variables are useful for PWA installed on Desktop devices. When a desktop PWA uses the `window-controls-overlay` [display_override](/en-US/docs/Web/Progressive_web_apps/Manifest/Reference/display_override) value, then it can use the `titlebar-area-*` variables to make sure content doesn't overlap with the window control buttons (i.e., minimize, maximize, and close). - `keyboard-inset-top`, `keyboard-inset-right`, `keyboard-inset-bottom`, `keyboard-inset-left`, `keyboard-inset-width`, `keyboard-inset-height` - : The `keyboard-inset-*` variables provide information about the on-screen virtual keyboard's appearance. They define a rectangle by its top, right, bottom, and left insets from the edge of the viewport (the width and height insets are calculated from the other insets). To learn more, see the {{domxref("VirtualKeyboard API", "VirtualKeyboard API", "", "nocode")}}. diff --git a/files/en-us/web/css/exp/index.md b/files/en-us/web/css/exp/index.md index ff95f628c21be3a..906f7bf2094db8d 100644 --- a/files/en-us/web/css/exp/index.md +++ b/files/en-us/web/css/exp/index.md @@ -35,7 +35,7 @@ Returns a non-negative {{CSSxRef("number")}} representing e<sup>number</sup>, wh - If `number` is `-Infinity`, the result is `0`. - If `number` is `0`, the result is `1`. -- If `number` is `1`, the result is `e` (i.e. `2.718281828459045`). +- If `number` is `1`, the result is `e` (i.e., `2.718281828459045`). - If `number` is `Infinity`, the result is `Infinity`. ## Formal syntax @@ -77,19 +77,19 @@ div.box { background: linear-gradient(orange, red); } div.box-1 { - transform: rotate(calc(1turn * exp(-1))); // 0.3678794411714423turn + transform: rotate(calc(1turn * exp(-1))); /* 0.3678794411714423turn */ } div.box-2 { - transform: rotate(calc(1turn * exp(-0.75))); // 0.4723665527410147turn + transform: rotate(calc(1turn * exp(-0.75))); /* 0.4723665527410147turn */ } div.box-3 { - transform: rotate(calc(1turn * exp(-0.5))); // 0.6065306597126334turn + transform: rotate(calc(1turn * exp(-0.5))); /* 0.6065306597126334turn */ } div.box-4 { - transform: rotate(calc(1turn * exp(-0.25))); // 0.7788007830714049turn + transform: rotate(calc(1turn * exp(-0.25))); /* 0.7788007830714049turn */ } div.box-5 { - transform: rotate(calc(1turn * exp(0))); // 1turn + transform: rotate(calc(1turn * exp(0))); /* 1turn */ } ``` @@ -116,22 +116,22 @@ The `exp()` function can be useful for strategies like CSS modular scale, which ```css h1 { - font-size: calc(1rem * exp(1.25)); // 3.4903429574618414rem + font-size: calc(1rem * exp(1.25)); /* 3.4903429574618414rem */ } h2 { - font-size: calc(1rem * exp(1)); // 2.718281828459045rem + font-size: calc(1rem * exp(1)); /* 2.718281828459045rem */ } h3 { - font-size: calc(1rem * exp(0.75)); // 2.117000016612675rem + font-size: calc(1rem * exp(0.75)); /* 2.117000016612675rem */ } h4 { - font-size: calc(1rem * exp(0.5)); // 1.6487212707001282rem + font-size: calc(1rem * exp(0.5)); /* 1.6487212707001282rem */ } h5 { - font-size: calc(1rem * exp(0.25)); // 1.2840254166877414rem + font-size: calc(1rem * exp(0.25)); /* 1.2840254166877414rem */ } h6 { - font-size: calc(1rem * exp(0)); // 1rem + font-size: calc(1rem * exp(0)); /* 1rem */ } ``` diff --git a/files/en-us/web/css/field-sizing/index.md b/files/en-us/web/css/field-sizing/index.md index 9a568bd58d523ab..f7930f3c9bc715b 100644 --- a/files/en-us/web/css/field-sizing/index.md +++ b/files/en-us/web/css/field-sizing/index.md @@ -43,24 +43,24 @@ field-sizing: unset; Specifically, `field-sizing` to `content` affects the following elements: -- Form input types that accept direct text input from users. This includes [`email`](/en-US/docs/Web/HTML/Element/input/email), [`number`](/en-US/docs/Web/HTML/Element/input/number), [`password`](/en-US/docs/Web/HTML/Element/input/password), [`search`](/en-US/docs/Web/HTML/Element/input/search), [`tel`](/en-US/docs/Web/HTML/Element/input/tel), [`text`](/en-US/docs/Web/HTML/Element/input/text), and [`url`](/en-US/docs/Web/HTML/Element/input/url) types. +- Form input types that accept direct text input from users. This includes [`email`](/en-US/docs/Web/HTML/Reference/Elements/input/email), [`number`](/en-US/docs/Web/HTML/Reference/Elements/input/number), [`password`](/en-US/docs/Web/HTML/Reference/Elements/input/password), [`search`](/en-US/docs/Web/HTML/Reference/Elements/input/search), [`tel`](/en-US/docs/Web/HTML/Reference/Elements/input/tel), [`text`](/en-US/docs/Web/HTML/Reference/Elements/input/text), and [`url`](/en-US/docs/Web/HTML/Reference/Elements/input/url) types. - If no minimum width is set on the control, it will only be as wide as the text cursor. - - Controls with [`placeholder`](/en-US/docs/Web/HTML/Element/input#placeholder) attributes will be rendered large enough to display the placeholder text. - - The [`size`](/en-US/docs/Web/HTML/Element/input#size) attribute modifies the default preferred size of such `<input>` elements. As a result, `size` has no effect on `<input>` elements with `field-sizing: content` set. -- [`file`](/en-US/docs/Web/HTML/Element/input/file) inputs. Direct text input is not possible; however, the displayed filename changes as the user selects a new file to upload. When `field-sizing: content` is set, the control will change size to shrinkwrap the filename. + - Controls with [`placeholder`](/en-US/docs/Web/HTML/Reference/Elements/input#placeholder) attributes will be rendered large enough to display the placeholder text. + - The [`size`](/en-US/docs/Web/HTML/Reference/Elements/input#size) attribute modifies the default preferred size of such `<input>` elements. As a result, `size` has no effect on `<input>` elements with `field-sizing: content` set. +- [`file`](/en-US/docs/Web/HTML/Reference/Elements/input/file) inputs. Direct text input is not possible; however, the displayed filename changes as the user selects a new file to upload. When `field-sizing: content` is set, the control will change size to shrinkwrap the filename. - {{htmlelement("textarea")}} controls. It is worth noting that `<textarea>` elements with `field-sizing: content` set behave much like single-line text controls, with the following additions: - If `<textarea>` elements are unable to grow due to a width constraint, they will start to grow in height to display additional rows of content. When a height constraint is then reached, they will then start to show a scrollbar to allow all the content to be viewed. - - [`rows`](/en-US/docs/Web/HTML/Element/textarea#cols) and [`cols`](/en-US/docs/Web/HTML/Element/textarea#cols) attributes modify the default preferred size of a `<textarea>`. As a result, `rows`/`cols` have no effect on `<textarea>` elements with `field-sizing: content` set. + - [`rows`](/en-US/docs/Web/HTML/Reference/Elements/textarea#cols) and [`cols`](/en-US/docs/Web/HTML/Reference/Elements/textarea#cols) attributes modify the default preferred size of a `<textarea>`. As a result, `rows`/`cols` have no effect on `<textarea>` elements with `field-sizing: content` set. - {{htmlelement("select")}} controls. These behave a bit differently to what you might expect with `field-sizing: content` set. The effect depends on the type of `<select>` control you are creating: - Regular drop-down boxes will change their width to always fit the displayed option value as new values are selected. (By default, the drop-down's size is set to be large enough to display the longest option value.) - - List boxes (`<select>` elements with the [`multiple`](/en-US/docs/Web/HTML/Element/select#multiple) or [`size`](/en-US/docs/Web/HTML/Element/select#multiple) attribute) will be large enough to display all the options without needing to scroll. (By default, the drop-down box will require scrolling to view all the option values.) - - The [`size`](/en-US/docs/Web/HTML/Element/select#size) attribute has very little effect on `<select>` elements that have `field-sizing: content` set. In such cases, the browser checks if the `size` is equal to `1` to determine whether the `<select>` control should appear as a drop-down or a listbox. However, it will always display all the options of a listbox, even if `size` is smaller than the number of options. + - List boxes (`<select>` elements with the [`multiple`](/en-US/docs/Web/HTML/Reference/Elements/select#multiple) or [`size`](/en-US/docs/Web/HTML/Reference/Elements/select#multiple) attribute) will be large enough to display all the options without needing to scroll. (By default, the drop-down box will require scrolling to view all the option values.) + - The [`size`](/en-US/docs/Web/HTML/Reference/Elements/select#size) attribute has very little effect on `<select>` elements that have `field-sizing: content` set. In such cases, the browser checks if the `size` is equal to `1` to determine whether the `<select>` control should appear as a drop-down or a listbox. However, it will always display all the options of a listbox, even if `size` is smaller than the number of options. ### `field-sizing` interaction with other size settings The sizing flexibility provided to form controls by `field-sizing: content` can be overridden if you use other CSS sizing properties. Avoid setting a fixed {{cssxref("width")}} and {{cssxref("height")}} when using `field-sizing: content` because they will reimpose a fixed size on the control. However, using properties like {{cssxref("min-width")}} and {{cssxref("max-width")}} alongside `field-sizing: content` is quite effective because they allow the control to grow and shrink with the entered text and also prevent the control from becoming too large or too small. -The [`maxlength`](/en-US/docs/Web/HTML/Element/input#maxlength) attribute causes the control to stop growing in size when the maximum character limit is reached. +The [`maxlength`](/en-US/docs/Web/HTML/Reference/Elements/input#maxlength) attribute causes the control to stop growing in size when the maximum character limit is reached. ## Formal definition @@ -78,7 +78,7 @@ This example illustrates the effect of `field-sizing: content` on single- and mu #### HTML -The HTML in this example contains three form fields, each with an associated {{htmlelement("label")}}: two `<input>` elements of types [`text`](/en-US/docs/Web/HTML/Element/input/text) and [`email`](/en-US/docs/Web/HTML/Element/input/email) and a {{htmlelement("textarea")}} element. +The HTML in this example contains three form fields, each with an associated {{htmlelement("label")}}: two `<input>` elements of types [`text`](/en-US/docs/Web/HTML/Reference/Elements/input/text) and [`email`](/en-US/docs/Web/HTML/Reference/Elements/input/email) and a {{htmlelement("textarea")}} element. ```html <div> @@ -97,7 +97,7 @@ The HTML in this example contains three form fields, each with an associated {{h Note the following points about the HTML: -- The first two fields have a [`maxlength`](/en-US/docs/Web/HTML/Element/input#maxlength) attribute set, which stops the size of the field from increasing when the character limit is reached. +- The first two fields have a [`maxlength`](/en-US/docs/Web/HTML/Reference/Elements/input#maxlength) attribute set, which stops the size of the field from increasing when the character limit is reached. - The `<textarea>` will grow in the inline direction until the edge of the {{cssxref("min-width")}} constraint (set in the CSS code below) is reached, then start to add new lines in the block direction to contain subsequent characters. - The `email` input has a placeholder set. This causes the field to render big enough to show the entire placeholder. Once the field is focused and the user starts typing, the field changes size to the `min-width` value. The `text` field, which doesn't have a placeholder, renders initially at `min-width`. @@ -146,7 +146,7 @@ This example illustrates the effect of `field-sizing: content` on {{htmlelement( #### HTML -The HTML contains two sets of `<select>` elements: one with `field-sizing: content` applied, and one without, allowing you to see the difference (though the effect may be less obvious than on text fields). Each set includes one drop-down menu type and one multiline listbox type (with the [`multiple`](/en-US/docs/Web/HTML/Element/select#multiple) attribute set). +The HTML contains two sets of `<select>` elements: one with `field-sizing: content` applied, and one without, allowing you to see the difference (though the effect may be less obvious than on text fields). Each set includes one drop-down menu type and one multiline listbox type (with the [`multiple`](/en-US/docs/Web/HTML/Reference/Elements/select#multiple) attribute set). ```html <div class="field-sizing"> @@ -186,7 +186,7 @@ The HTML contains two sets of `<select>` elements: one with `field-sizing: conte ``` > [!NOTE] -> Best practice is to include a {{htmlelement("label")}} element for each form control, to associate a meaningful text description with each field for accessibility purposes (see [Meaningful text labels](/en-US/docs/Learn_web_development/Core/Accessibility/HTML#meaningful_text_labels) for more information). We haven't done so in this example, as it focuses purely on aspects of the form controls' visual rendering, but you should make sure you include form labels in production code. +> Best practice is to include a {{htmlelement("label")}} element for each form control, to associate a meaningful text description with each field for accessibility purposes (see [Use meaningful text labels](/en-US/docs/Learn_web_development/Core/Accessibility/HTML#use_meaningful_text_labels) for more information). We haven't done so in this example, as it focuses purely on aspects of the form controls' visual rendering, but you should make sure you include form labels in production code. #### CSS @@ -215,10 +215,6 @@ div { justify-content: space-around; flex-flow: row wrap; } - -select { - valign: top; -} ``` ```css diff --git a/files/en-us/web/css/fill/index.md b/files/en-us/web/css/fill/index.md index 4f1786e1cf96625..5a19aa2a1746669 100644 --- a/files/en-us/web/css/fill/index.md +++ b/files/en-us/web/css/fill/index.md @@ -14,7 +14,7 @@ The areas inside the outline of the SVG shape or text are painted. What is "insi If subpaths are open, `fill` closes the path before painting, as if a "closepath" command were included connecting the last point of the subpath with the first point of the subpath. In other words, `fill` applies to open subpaths within `path` elements (i.e., subpaths without a closepath command) and `polyline` elements. > [!NOTE] -> The `fill` property only applies to {{SVGElement('circle')}}, {{SVGElement('ellipse')}}, {{SVGElement('path')}}, {{SVGElement('polygon')}}, {{SVGElement('polyline')}}, {{SVGElement('rect')}}, {{SVGElement('text')}}, {{SVGElement('textPath')}}, {{SVGElement('tref')}}, and {{SVGElement('tspan')}} elements nested in an {{SVGElement("svg")}}. It doesn't apply other SVG, HTML, or pseudo-elements. +> The `fill` property only applies to {{SVGElement('circle')}}, {{SVGElement('ellipse')}}, {{SVGElement('path')}}, {{SVGElement('polygon')}}, {{SVGElement('polyline')}}, {{SVGElement('rect')}}, {{SVGElement('text')}}, {{SVGElement('textPath')}}, and {{SVGElement('tspan')}} elements nested in an {{SVGElement("svg")}}. It doesn't apply other SVG, HTML, or pseudo-elements. ## Syntax diff --git a/files/en-us/web/css/filter-function/blur/index.md b/files/en-us/web/css/filter-function/blur/index.md index 22dadfa69f5eff3..1b50f7c3c105579 100644 --- a/files/en-us/web/css/filter-function/blur/index.md +++ b/files/en-us/web/css/filter-function/blur/index.md @@ -9,7 +9,29 @@ browser-compat: css.types.filter-function.blur The **`blur()`** [CSS](/en-US/docs/Web/CSS) [function](/en-US/docs/Web/CSS/CSS_Values_and_Units/CSS_Value_Functions) applies a [Gaussian blur](https://en.wikipedia.org/wiki/Gaussian_blur) to the input image. Its result is a {{cssxref("&lt;filter-function&gt;")}}. -{{EmbedInteractiveExample("pages/css/function-blur.html")}} +{{InteractiveExample("CSS Demo: blur()")}} + +```css interactive-example-choice +filter: blur(0); +``` + +```css interactive-example-choice +filter: blur(4px); +``` + +```css interactive-example-choice +filter: blur(1.5rem); +``` + +```html interactive-example +<section id="default-example"> + <img + class="transition-all" + id="example-element" + src="/shared-assets/images/examples/firefox-logo.svg" + width="200" /> +</section> +``` ## Syntax diff --git a/files/en-us/web/css/filter-function/brightness/index.md b/files/en-us/web/css/filter-function/brightness/index.md index 3b0ccf1712181a8..35a24b0304891e3 100644 --- a/files/en-us/web/css/filter-function/brightness/index.md +++ b/files/en-us/web/css/filter-function/brightness/index.md @@ -9,7 +9,33 @@ browser-compat: css.types.filter-function.brightness The **`brightness()`** [CSS](/en-US/docs/Web/CSS) {{cssxref("&lt;filter-function&gt;")}} applies a linear multiplier value on an element or an input image, making the image appear brighter or darker. -{{EmbedInteractiveExample("pages/css/function-brightness.html")}} +{{InteractiveExample("CSS Demo: brightness()")}} + +```css interactive-example-choice +filter: brightness(1); +``` + +```css interactive-example-choice +filter: brightness(1.75); +``` + +```css interactive-example-choice +filter: brightness(50%); +``` + +```css interactive-example-choice +filter: brightness(0); +``` + +```html interactive-example +<section id="default-example"> + <img + class="transition-all" + id="example-element" + src="/shared-assets/images/examples/firefox-logo.svg" + width="200" /> +</section> +``` ## Syntax @@ -53,7 +79,7 @@ This example shows how to apply the `brightness()` filter to a paragraph via the ```css .container { - background: url(image.jpg) no-repeat right / contain #d4d5b2; + background: url(be_fierce.jpg) no-repeat right / contain #d4d5b2; } p { backdrop-filter: brightness(150%); @@ -75,7 +101,7 @@ p { ``` ```html hidden -<div class="container" style="background-image: url(be_fierce.jpg);"> +<div class="container"> <p> Text on images can be illegible and inaccessible even with a drop shadow. </p> @@ -86,7 +112,7 @@ p { {{EmbedLiveSample('Applying_brightness_using_the_backdrop_filter_property', '100%', '280')}} -In this example, the colors in the area behind the `<p>` element shift linearly. If the `backdrop-filter` property was set to `brightness(0%)`, the `<div>` area with the `<p>` element would have been black and hidden the image behind. At `brightness(100%)`, the `<div>` area color would be the same as the input `#d4d5b2`, and the image behind would be completely transparent. With the brightness set to `150%` as in this example, the colors in the image behind are getting hidden by the brightness of the `<div>` element.` +In this example, the colors in the area behind the `<p>` element shift linearly. If the `backdrop-filter` property was set to `brightness(0%)`, the `<div>` area with the `<p>` element would have been black and hidden the image behind. At `brightness(100%)`, the `<div>` area color would be the same as the input `#d4d5b2`, and the image behind would be completely transparent. With the brightness set to `150%` as in this example, the colors in the image behind are getting hidden by the brightness of the `<div>` element. ### Applying brightness using the filter property @@ -127,13 +153,13 @@ p { ### Applying brightness using the url() SVG brightness filter -The SVG {{SVGElement("filter")}} element is used to define custom filter effects that can then be referenced by [`id`](/en-US/docs/Web/HTML/Global_attributes/id). The `<filter>` element's {{SVGElement("feComponentTransfer")}} primitive enables pixel-level color remapping. +The SVG {{SVGElement("filter")}} element is used to define custom filter effects that can then be referenced by [`id`](/en-US/docs/Web/HTML/Reference/Global_attributes/id). The `<filter>` element's {{SVGElement("feComponentTransfer")}} primitive enables pixel-level color remapping. In this example, to create a filter that darkens the content on which it is applied by 25% (i.e., 75% of the original brightness), the `slope` attribute is set to `0.75`. We can then reference the filter by `id`. Given the following: -```css hidden +```css hidden live-sample___svg_filter .filter { filter: brightness(0.75); } @@ -142,7 +168,7 @@ svg { } ``` -```html +```html live-sample___svg_filter <svg role="none"> <filter id="darken25" color-interpolation-filters="sRGB"> <feComponentTransfer> @@ -164,7 +190,7 @@ filter: url(folder/fileName.svg#darken25); /* external svg filter definition */ In the images below, the first one has a `brightness()` filter function applied, the second one has a similar SVG brightness function applied, and the third is the original image for comparison. -```html hidden +```html hidden live-sample___svg_filter <table cellpadding="5"> <thead> <tr> @@ -197,7 +223,7 @@ In the images below, the first one has a `brightness()` filter function applied, </table> ``` -{{EmbedLiveSample('blur','100%','280')}} +{{EmbedLiveSample('svg_filter','100%','280')}} ## Specifications diff --git a/files/en-us/web/css/filter-function/contrast/index.md b/files/en-us/web/css/filter-function/contrast/index.md index 2f5e764bb2ed312..9160cfc5b13e354 100644 --- a/files/en-us/web/css/filter-function/contrast/index.md +++ b/files/en-us/web/css/filter-function/contrast/index.md @@ -9,7 +9,33 @@ browser-compat: css.types.filter-function.contrast The **`contrast()`** [CSS](/en-US/docs/Web/CSS) [function](/en-US/docs/Web/CSS/CSS_Values_and_Units/CSS_Value_Functions) adjusts the contrast of the input image. Its result is a {{cssxref("&lt;filter-function&gt;")}}. -{{EmbedInteractiveExample("pages/css/function-contrast.html")}} +{{InteractiveExample("CSS Demo: contrast()")}} + +```css interactive-example-choice +filter: contrast(1); +``` + +```css interactive-example-choice +filter: contrast(1.75); +``` + +```css interactive-example-choice +filter: contrast(50%); +``` + +```css interactive-example-choice +filter: contrast(0); +``` + +```html interactive-example +<section id="default-example"> + <img + class="transition-all" + id="example-element" + src="/shared-assets/images/examples/firefox-logo.svg" + width="200" /> +</section> +``` ## Syntax @@ -51,7 +77,7 @@ This example applies a `contrast()` filter via the {{cssxref("backdrop-filter")} ```css .container { - background: url(image.jpg) no-repeat center / contain #339; + background: url(unity_for_the_people.jpg) no-repeat center / contain #339; } p { backdrop-filter: contrast(0.5); @@ -74,7 +100,7 @@ p { ``` ```html hidden -<div class="container" style="background-image: url(unity_for_the_people.jpg);"> +<div class="container"> <p> Always ensure there is enough contrast between text and all background colors. If you think your text may land on top of a background image, @@ -126,22 +152,25 @@ p { ### With url() and the SVG contrast filter -The SVG {{SVGElement("filter")}} element is used to define custom filter effects that can then be referenced by [`id`](/en-US/docs/Web/HTML/Global_attributes/id). The `<filter>`'s {{SVGElement("feComponentTransfer")}} primitive enables pixel-level color remapping. Given the following: - -```svg +The SVG {{SVGElement("filter")}} element is used to define custom filter effects that can then be referenced by [`id`](/en-US/docs/Web/HTML/Reference/Global_attributes/id). The `<filter>`'s {{SVGElement("feComponentTransfer")}} primitive enables pixel-level color remapping. Given the following: + +```html live-sample___svg_filter +<svg + xmlns="http://www.w3.org/2000/svg" + id="svg" + viewBox="0 0 240 151" + height="0" + width="0" + style="overflow: visible" + color-interpolation-filters="sRGB"> <filter id="contrast"> <feComponentTransfer> - <feFuncR type="linear" slope="2" intercept="-0.5"/> - <feFuncG type="linear" slope="2" intercept="-0.5"/> - <feFuncB type="linear" slope="2" intercept="-0.5"/> + <feFuncR type="linear" slope="2" intercept="-0.5" /> + <feFuncG type="linear" slope="2" intercept="-0.5" /> + <feFuncB type="linear" slope="2" intercept="-0.5" /> </feComponentTransfer> </filter> -``` - -```css hidden -.svgFilterLive { - filter: url(#contrast2); -} +</svg> ``` These values produce the same results: @@ -154,7 +183,7 @@ filter: url(folder/fileName.svg#contrast); /* external svg filter definition */ This example shows three images: the image with a `contrast()` filter function applied, the image with an equivalent `url()` filter applied, and the original images for comparison: -```html hidden +```html hidden live-sample___svg_filter <table cellpadding="5"> <thead> <tr> @@ -173,25 +202,9 @@ This example shows three images: the image with a `contrast()` filter function a </td> <td> <img - class="svgFilterLive" + style="filter: url(#contrast)" src="https://mdn.github.io/shared-assets/images/examples/progress-pride-flag.jpg" alt="Pride flag" /> - <svg - xmlns="http://www.w3.org/2000/svg" - id="svg" - viewBox="0 0 240 151" - height="0" - width="0" - style="overflow: visible" - color-interpolation-filters="sRGB"> - <filter id="contrast2"> - <feComponentTransfer> - <feFuncR type="linear" slope="2" intercept="-0.5" /> - <feFuncG type="linear" slope="2" intercept="-0.5" /> - <feFuncB type="linear" slope="2" intercept="-0.5" /> - </feComponentTransfer> - </filter> - </svg> </td> <td> <img @@ -203,7 +216,7 @@ This example shows three images: the image with a `contrast()` filter function a </table> ``` -{{EmbedLiveSample('With_url()_and_the_SVG_contrast_filter','100%','280')}} +{{EmbedLiveSample('svg_filter','100%','280')}} ## Specifications diff --git a/files/en-us/web/css/filter-function/drop-shadow/index.md b/files/en-us/web/css/filter-function/drop-shadow/index.md index 3169618a3a7363a..680d8bab06ce4ce 100644 --- a/files/en-us/web/css/filter-function/drop-shadow/index.md +++ b/files/en-us/web/css/filter-function/drop-shadow/index.md @@ -9,7 +9,29 @@ browser-compat: css.types.filter-function.drop-shadow The **`drop-shadow()`** [CSS](/en-US/docs/Web/CSS) [function](/en-US/docs/Web/CSS/CSS_Values_and_Units/CSS_Value_Functions) applies a drop shadow effect to the input image. Its result is a {{cssxref("&lt;filter-function&gt;")}}. -{{EmbedInteractiveExample("pages/css/function-drop-shadow.html")}} +{{InteractiveExample("CSS Demo: drop-shadow()")}} + +```css interactive-example-choice +filter: drop-shadow(30px 10px 4px #4444dd); +``` + +```css interactive-example-choice +filter: drop-shadow(0 -6mm 4mm rgb(160, 0, 210)); +``` + +```css interactive-example-choice +filter: drop-shadow(0 0 0.75rem crimson); +``` + +```html interactive-example +<section id="default-example"> + <img + class="transition-all" + id="example-element" + src="/shared-assets/images/examples/firefox-logo.svg" + width="200" /> +</section> +``` A drop shadow is effectively a blurred, offset version of the input image's alpha mask, drawn in a specific color and composited below the image. diff --git a/files/en-us/web/css/filter-function/grayscale/index.md b/files/en-us/web/css/filter-function/grayscale/index.md index eb1d99811fc65ef..0d7fc63f90d7088 100644 --- a/files/en-us/web/css/filter-function/grayscale/index.md +++ b/files/en-us/web/css/filter-function/grayscale/index.md @@ -9,7 +9,33 @@ browser-compat: css.types.filter-function.grayscale The **`grayscale()`** [CSS](/en-US/docs/Web/CSS) [function](/en-US/docs/Web/CSS/CSS_Values_and_Units/CSS_Value_Functions) converts the input image to grayscale. Its result is a {{cssxref("&lt;filter-function&gt;")}}. -{{EmbedInteractiveExample("pages/css/function-grayscale.html")}} +{{InteractiveExample("CSS Demo: grayscale()")}} + +```css interactive-example-choice +filter: grayscale(0); +``` + +```css interactive-example-choice +filter: grayscale(0.2); +``` + +```css interactive-example-choice +filter: grayscale(60%); +``` + +```css interactive-example-choice +filter: grayscale(1); +``` + +```html interactive-example +<section id="default-example"> + <img + class="transition-all" + id="example-element" + src="/shared-assets/images/examples/firefox-logo.svg" + width="200" /> +</section> +``` ## Syntax diff --git a/files/en-us/web/css/filter-function/hue-rotate/index.md b/files/en-us/web/css/filter-function/hue-rotate/index.md index 3480421c4d59536..f2d66e3d11194e1 100644 --- a/files/en-us/web/css/filter-function/hue-rotate/index.md +++ b/files/en-us/web/css/filter-function/hue-rotate/index.md @@ -11,7 +11,33 @@ The **`hue-rotate()`** [CSS](/en-US/docs/Web/CSS) [function](/en-US/docs/Web/CSS > **Note:** `hue-rotate()` is specified as a matrix operation on the RGB color. It does not actually convert the color to the HSL model, which is a non-linear operation. Therefore, it may not preserve the saturation or lightness of the original color, especially for saturated colors. -{{EmbedInteractiveExample("pages/css/function-hue-rotate.html")}} +{{InteractiveExample("CSS Demo: hue-rotate()")}} + +```css interactive-example-choice +filter: hue-rotate(0); +``` + +```css interactive-example-choice +filter: hue-rotate(90deg); +``` + +```css interactive-example-choice +filter: hue-rotate(-0.25turn); +``` + +```css interactive-example-choice +filter: hue-rotate(3.142rad); +``` + +```html interactive-example +<section id="default-example"> + <img + class="transition-all" + id="example-element" + src="/shared-assets/images/examples/firefox-logo.svg" + width="200" /> +</section> +``` ## Syntax @@ -48,7 +74,8 @@ This example applies a `hue-rotate()` filter via the `backdrop-filter` CSS prope ```css .container { - background: url(image.jpg) no-repeat left / contain #011296; + background: url("/shared-assets/images/examples/listen_to_black_women.jpg") + no-repeat left / contain #011296; } p { backdrop-filter: hue-rotate(240deg); @@ -70,9 +97,7 @@ p { ``` ```html hidden -<div - class="container" - style="background-image: url('https://mdn.github.io/shared-assets/images/examples/listen_to_black_women.jpg');"> +<div class="container"> <p> Text on images can be illegible and inaccessible even with a drop shadow. </p> @@ -115,25 +140,32 @@ p { ### With url() and the SVG hue-rotate filter -The SVG {{SVGElement("filter")}} element is used to define custom filter effects that can then be referenced by [`id`](/en-US/docs/Web/HTML/Global_attributes/id). The `<filter>`'s {{SVGElement("feColorMatrix")}} primitive `hueRotate` type provides the same effect. Given the following: - -```svg -<filter id="filterID"> - <feColorMatrix type="hueRotate" values="90" /> -</filter> +The SVG {{SVGElement("filter")}} element is used to define custom filter effects that can then be referenced by [`id`](/en-US/docs/Web/HTML/Reference/Global_attributes/id). The `<filter>`'s {{SVGElement("feColorMatrix")}} primitive `hueRotate` type provides the same effect. Given the following: + +```html live-sample___svg_filter +<svg + xmlns="http://www.w3.org/2000/svg" + viewBox="0 0 220 220" + color-interpolation-filters="sRGB" + height="220" + width="220"> + <filter id="hue-rotate"> + <feColorMatrix type="hueRotate" values="90" /> + </filter> +</svg> ``` These values produce the same results: ```css filter: hue-rotate(90deg); /* 90deg rotation */ -filter: url(#filterID); /* with embedded SVG */ -filter: url(folder/fileName.svg#filterID); /* external svg filter definition */ +filter: url(#hue-rotate); /* with embedded SVG */ +filter: url(folder/fileName.svg#hue-rotate); /* external svg filter definition */ ``` This example shows three images: the image with a `hue-rotate()` filter function applied, the image with an equivalent `url()` filter applied, and the original images for comparison: -```html hidden +```html hidden live-sample___svg_filter <table cellpadding="5"> <thead> <tr> @@ -151,23 +183,11 @@ This example shows three images: the image with a `hue-rotate()` filter function alt="Pride flag with rotated colors" /> </td> <td> - <svg - xmlns="http://www.w3.org/2000/svg" - viewBox="0 0 220 220" - color-interpolation-filters="sRGB" - height="220" - width="220"> - <filter id="hue-rotate"> - <feColorMatrix type="hueRotate" values="90" /> - </filter> - <image - href="https://mdn.github.io/shared-assets/images/examples/progress-pride-flag.jpg" - filter="url(#hue-rotate)" - width="220" - height="220" /> - </svg> + <img + style="filter: url(#hue-rotate)" + src="https://mdn.github.io/shared-assets/images/examples/progress-pride-flag.jpg" + alt="Pride flag with rotated colors" /> </td> - <td> <img src="https://mdn.github.io/shared-assets/images/examples/progress-pride-flag.jpg" @@ -178,7 +198,7 @@ This example shows three images: the image with a `hue-rotate()` filter function </table> ``` -{{EmbedLiveSample('With_url()_and_the_SVG_hue-rotate_filter','100%','280')}} +{{EmbedLiveSample('svg_filter','100%','280')}} ### hue-rotate() does not preserve saturation or lightness diff --git a/files/en-us/web/css/filter-function/index.md b/files/en-us/web/css/filter-function/index.md index b7dd1edff5663bb..7a336f0fa903015 100644 --- a/files/en-us/web/css/filter-function/index.md +++ b/files/en-us/web/css/filter-function/index.md @@ -42,7 +42,7 @@ The `<filter-function>` data type is specified using one of the filter functions ### Filter function comparison -This example provides a simple graphic, along with a select menu to allow you to choose between the different types of filter function, and a slider to allow you to vary the values used inside the filter function. Updating the controls updates the filter effect in real time, allowing you to investigate the effects of different filters. +This example provides a graphic, a select menu to allow you to choose between the different types of filter function, and a slider to allow you to vary the values used inside the filter function. Updating the controls updates the filter effect in real time, allowing you to investigate the effects of different filters. ```css div { diff --git a/files/en-us/web/css/filter-function/invert/index.md b/files/en-us/web/css/filter-function/invert/index.md index 0d9040692cad153..b436b189d6b17ef 100644 --- a/files/en-us/web/css/filter-function/invert/index.md +++ b/files/en-us/web/css/filter-function/invert/index.md @@ -9,7 +9,37 @@ browser-compat: css.types.filter-function.invert The **`invert()`** [CSS](/en-US/docs/Web/CSS) [function](/en-US/docs/Web/CSS/CSS_Values_and_Units/CSS_Value_Functions) inverts the color samples in the input image. Its result is a {{cssxref("&lt;filter-function&gt;")}}. -{{EmbedInteractiveExample("pages/css/function-invert.html")}} +{{InteractiveExample("CSS Demo: invert()")}} + +```css interactive-example-choice +filter: invert(0); +``` + +```css interactive-example-choice +filter: invert(0.3); +``` + +```css interactive-example-choice +filter: invert(50%); +``` + +```css interactive-example-choice +filter: invert(70%); +``` + +```css interactive-example-choice +filter: invert(1); +``` + +```html interactive-example +<section id="default-example"> + <img + class="transition-all" + id="example-element" + src="/shared-assets/images/examples/firefox-logo.svg" + width="200" /> +</section> +``` ## Syntax diff --git a/files/en-us/web/css/filter-function/opacity/index.md b/files/en-us/web/css/filter-function/opacity/index.md index 2015a0944ddac15..e803b7f05480657 100644 --- a/files/en-us/web/css/filter-function/opacity/index.md +++ b/files/en-us/web/css/filter-function/opacity/index.md @@ -9,7 +9,37 @@ browser-compat: css.types.filter-function.opacity The **`opacity()`** [CSS](/en-US/docs/Web/CSS) [function](/en-US/docs/Web/CSS/CSS_Values_and_Units/CSS_Value_Functions) applies transparency to the samples in the input image. Its result is a {{cssxref("&lt;filter-function&gt;")}}. -{{EmbedInteractiveExample("pages/css/function-opacity.html")}} +{{InteractiveExample("CSS Demo: opacity()")}} + +```css interactive-example-choice +filter: opacity(1); +``` + +```css interactive-example-choice +filter: opacity(80%); +``` + +```css interactive-example-choice +filter: opacity(50%); +``` + +```css interactive-example-choice +filter: opacity(0.2); +``` + +```css interactive-example-choice +filter: opacity(0); +``` + +```html interactive-example +<section id="default-example"> + <img + class="transition-all" + id="example-element" + src="/shared-assets/images/examples/firefox-logo.svg" + width="200" /> +</section> +``` > [!NOTE] > This function is similar to the more established {{Cssxref("opacity")}} property. The difference is that with filters, some browsers provide hardware acceleration for better performance. diff --git a/files/en-us/web/css/filter-function/saturate/index.md b/files/en-us/web/css/filter-function/saturate/index.md index 480ba717f35cf78..9ae2479a2a38f6a 100644 --- a/files/en-us/web/css/filter-function/saturate/index.md +++ b/files/en-us/web/css/filter-function/saturate/index.md @@ -11,7 +11,33 @@ The **`saturate()`** [CSS](/en-US/docs/Web/CSS) [function](/en-US/docs/Web/CSS/C > **Note:** `saturate()` is specified as a matrix operation on the RGB color. It does not actually convert the color to the HSL model, which is a non-linear operation. Therefore, it may not preserve the hue or lightness of the original color. -{{EmbedInteractiveExample("pages/css/function-saturate.html")}} +{{InteractiveExample("CSS Demo: saturate()")}} + +```css interactive-example-choice +filter: saturate(1); +``` + +```css interactive-example-choice +filter: saturate(4); +``` + +```css interactive-example-choice +filter: saturate(50%); +``` + +```css interactive-example-choice +filter: saturate(0); +``` + +```html interactive-example +<section id="default-example"> + <img + class="transition-all" + id="example-element" + src="/shared-assets/images/examples/firefox-logo.svg" + width="200" /> +</section> +``` ## Syntax diff --git a/files/en-us/web/css/filter-function/sepia/index.md b/files/en-us/web/css/filter-function/sepia/index.md index b095bc96afbf8e5..cc661d5367b812c 100644 --- a/files/en-us/web/css/filter-function/sepia/index.md +++ b/files/en-us/web/css/filter-function/sepia/index.md @@ -9,7 +9,33 @@ browser-compat: css.types.filter-function.sepia The **`sepia()`** [CSS](/en-US/docs/Web/CSS) [function](/en-US/docs/Web/CSS/CSS_Values_and_Units/CSS_Value_Functions) converts the input image to sepia, giving it a warmer, more yellow/brown appearance. Its result is a {{cssxref("&lt;filter-function&gt;")}}. -{{EmbedInteractiveExample("pages/css/function-sepia.html")}} +{{InteractiveExample("CSS Demo: sepia()")}} + +```css interactive-example-choice +filter: sepia(0); +``` + +```css interactive-example-choice +filter: sepia(0.2); +``` + +```css interactive-example-choice +filter: sepia(60%); +``` + +```css interactive-example-choice +filter: sepia(1); +``` + +```html interactive-example +<section id="default-example"> + <img + class="transition-all" + id="example-element" + src="/shared-assets/images/examples/firefox-logo.svg" + width="200" /> +</section> +``` ## Syntax diff --git a/files/en-us/web/css/filter/index.md b/files/en-us/web/css/filter/index.md index 3979734f13f96c7..7aeb78f981e0ace 100644 --- a/files/en-us/web/css/filter/index.md +++ b/files/en-us/web/css/filter/index.md @@ -11,7 +11,58 @@ The **`filter`** [CSS](/en-US/docs/Web/CSS) property applies graphical effects l Several [functions](#functions), such as `blur()` and `contrast()`, are available to help you achieve predefined effects. -{{EmbedInteractiveExample("pages/css/filter.html")}} +{{InteractiveExample("CSS Demo: filter")}} + +```css interactive-example-choice +filter: url("/shared-assets/images/examples/shadow.svg#element-id"); +``` + +```css interactive-example-choice +filter: blur(5px); +``` + +```css interactive-example-choice +filter: contrast(200%); +``` + +```css interactive-example-choice +filter: grayscale(80%); +``` + +```css interactive-example-choice +filter: hue-rotate(90deg); +``` + +```css interactive-example-choice +filter: drop-shadow(16px 16px 20px red) invert(75%); +``` + +```html interactive-example +<section id="default-example"> + <div class="example-container"> + <img + id="example-element" + src="/shared-assets/images/examples/firefox-logo.svg" + width="200" /> + </div> +</section> +``` + +```css interactive-example +.example-container { + background-color: #fff; + width: 260px; + height: 260px; + display: flex; + align-items: center; + justify-content: center; +} + +#example-element { + flex: 1; + padding: 30px; +} +``` ## Syntax @@ -52,7 +103,7 @@ With a function, use the following: filter: <filter-function> [<filter-function>]* | none; ``` -You can use `url()` to reference an [SVG filter element](/en-US/docs/Web/SVG/Element/filter). For a reference to an SVG {{SVGElement("filter")}} element, use the following syntax: +You can use `url()` to reference an [SVG filter element](/en-US/docs/Web/SVG/Reference/Element/filter). For a reference to an SVG {{SVGElement("filter")}} element, use the following syntax: ```css filter: url(file.svg#filter-element-id); @@ -238,4 +289,4 @@ The filters are applied in order. This is why the drop shadows are not the same - SVG {{SVGAttr("filter")}} attribute - CSS [compositing and blending](/en-US/docs/Web/CSS/CSS_compositing_and_blending) module, including the CSS {{cssxref("background-blend-mode")}} and {{cssxref("mix-blend-mode")}} properties. - [SVG](/en-US/docs/Web/SVG), including the SVG {{SVGElement("filter")}} element and SVG {{SVGAttr("filter")}} attribute. -- [Applying SVG effects to HTML content](/en-US/docs/Web/SVG/Applying_SVG_effects_to_HTML_content) +- [Applying SVG effects to HTML content](/en-US/docs/Web/SVG/Guides/Applying_SVG_effects_to_HTML_content) diff --git a/files/en-us/web/css/fit-content/index.md b/files/en-us/web/css/fit-content/index.md index a90d25df10accf3..78b7e0f2ff1356a 100644 --- a/files/en-us/web/css/fit-content/index.md +++ b/files/en-us/web/css/fit-content/index.md @@ -9,6 +9,10 @@ browser-compat: css.properties.width.fit-content The **`fit-content`** keyword is equivalent to {{cssxref("fit-content_function", "fit-content(stretch)")}}. In practice, this means that the box will use the available space, but never more than {{cssxref("max-content")}}. +The `fit-content` size is calculated using the following equation, where `<available-space>` is the size of its parent or grid track in [grid layout](/en-US/docs/Web/CSS/CSS_grid_layout/Basic_concepts_of_grid_layout): + +`min(max-content, max(min-content, <available-space>))` + When used as laid out box size for {{cssxref("width")}}, {{cssxref("height")}}, {{cssxref("min-width")}}, {{cssxref("min-height")}}, {{cssxref("max-width")}} and {{cssxref("max-height")}} the maximum and minimum sizes refer to the content size. The {{cssxref("interpolate-size")}} property and {{cssxref("calc-size()")}} function can be used to enable animations to and from `fit-content`. diff --git a/files/en-us/web/css/fit-content_function/index.md b/files/en-us/web/css/fit-content_function/index.md index 8abd3c72f3f969f..b0623ee07938857 100644 --- a/files/en-us/web/css/fit-content_function/index.md +++ b/files/en-us/web/css/fit-content_function/index.md @@ -11,7 +11,48 @@ browser-compat: The **`fit-content()`** [CSS](/en-US/docs/Web/CSS) [function](/en-US/docs/Web/CSS/CSS_Values_and_Units/CSS_Value_Functions) clamps a given size to an available size according to the formula `min(maximum size, max(minimum size, argument))`. -{{EmbedInteractiveExample("pages/css/function-fit-content.html")}} +{{InteractiveExample("CSS Demo: fit-content()")}} + +```css interactive-example-choice +grid-template-columns: fit-content(8ch) fit-content(8ch) 1fr; +``` + +```css interactive-example-choice +grid-template-columns: fit-content(100px) fit-content(100px) 1fr; +``` + +```css interactive-example-choice +grid-template-columns: fit-content(40%) fit-content(40%) 1fr; +``` + +```html interactive-example +<section class="default-example" id="default-example"> + <div class="example-container"> + <div class="transition-all" id="example-element"> + <div>One. This column has more text in it.</div> + <div>Two</div> + <div>Three</div> + <div>Four</div> + <div>Five</div> + </div> + </div> +</section> +``` + +```css interactive-example +#example-element { + border: 1px solid #c5c5c5; + display: grid; + grid-gap: 10px; + width: 250px; +} + +#example-element > div { + background-color: rgba(0, 0, 255, 0.2); + border: 3px solid blue; + text-align: left; +} +``` The function can be used as a track size in [CSS grid](/en-US/docs/Web/CSS/CSS_grid_layout) properties, where the maximum size is defined by `max-content` and the minimum size by `auto`, which is calculated similar to `auto` (i.e., [`minmax(auto, max-content)`](/en-US/docs/Web/CSS/minmax)), except that the track size is clamped at _argument_ if it is greater than the `auto` minimum. diff --git a/files/en-us/web/css/flex-basis/index.md b/files/en-us/web/css/flex-basis/index.md index 2524fde44c6ef5d..9c045bc3018f73b 100644 --- a/files/en-us/web/css/flex-basis/index.md +++ b/files/en-us/web/css/flex-basis/index.md @@ -10,9 +10,47 @@ browser-compat: css.properties.flex-basis The **`flex-basis`** [CSS](/en-US/docs/Web/CSS) property sets the initial main size of a {{glossary("flex item")}}. It sets the size of the content box unless otherwise set with {{Cssxref("box-sizing")}}. > [!NOTE] -> It is recommended to use the {{cssxref("flex")}} shorthand instead of separate `flex-grow`, `flex-shrink`, and `flex-basis` declarations. We have separated them here as this document is about one of the shorthand components: the `flex-basis` property. +> It is recommended to use the {{cssxref("flex")}} shorthand with a keyword value like `auto` or `initial` instead of setting `flex-basis` on its own. The [keyword values](/en-US/docs/Web/CSS/flex#values) expand to reliable combinations of {{cssxref("flex-grow")}}, {{cssxref("flex-shrink")}}, and `flex-basis`, which help to achieve the commonly desired flex behaviors. -{{EmbedInteractiveExample("pages/css/flex-basis.html")}} +{{InteractiveExample("CSS Demo: flex-basis")}} + +```css interactive-example-choice +flex-basis: auto; +``` + +```css interactive-example-choice +flex-basis: 0; +``` + +```css interactive-example-choice +flex-basis: 200px; +``` + +```html interactive-example +<section class="default-example" id="default-example"> + <div class="transition-all" id="example-element">Item One</div> + <div>Item Two</div> + <div>Item Three</div> +</section> +``` + +```css interactive-example +.default-example { + border: 1px solid #c5c5c5; + width: auto; + max-height: 300px; + display: flex; +} + +.default-example > div { + background-color: rgba(0, 0, 255, 0.2); + border: 3px solid blue; + margin: 10px; + flex-grow: 1; + flex-shrink: 1; + flex-basis: auto; +} +``` In this example, the {{cssxref("flex-grow")}} and {{cssxref("flex-shrink")}} properties are both set to `1` on all three items, indicating that the flex item can grow and shrink from the initial `flex-basis`. diff --git a/files/en-us/web/css/flex-direction/index.md b/files/en-us/web/css/flex-direction/index.md index 628d6ef5ba03736..df4d491ef32b0e1 100644 --- a/files/en-us/web/css/flex-direction/index.md +++ b/files/en-us/web/css/flex-direction/index.md @@ -9,9 +9,50 @@ browser-compat: css.properties.flex-direction The **`flex-direction`** [CSS](/en-US/docs/Web/CSS) property sets how flex items are placed in the flex container defining the main axis and the direction (normal or reversed). -{{EmbedInteractiveExample("pages/css/flex-direction.html")}} +{{InteractiveExample("CSS Demo: flex-direction")}} -Note that the values `row` and `row-reverse` are affected by the directionality of the flex container. If its [`dir`](/en-US/docs/Web/HTML/Global_attributes/dir) attribute is `ltr`, `row` represents the horizontal axis oriented from the left to the right, and `row-reverse` from the right to the left; if the `dir` attribute is `rtl`, `row` represents the axis oriented from the right to the left, and `row-reverse` from the left to the right. +```css interactive-example-choice +flex-direction: row; +``` + +```css interactive-example-choice +flex-direction: row-reverse; +``` + +```css interactive-example-choice +flex-direction: column; +``` + +```css interactive-example-choice +flex-direction: column-reverse; +``` + +```html interactive-example +<section class="default-example" id="default-example"> + <div class="transition-all" id="example-element"> + <div>Item One</div> + <div>Item Two</div> + <div>Item Three</div> + </div> +</section> +``` + +```css interactive-example +#example-element { + border: 1px solid #c5c5c5; + width: 80%; + display: flex; +} + +#example-element > div { + background-color: rgba(0, 0, 255, 0.2); + border: 3px solid blue; + width: 60px; + margin: 10px; +} +``` + +Note that the values `row` and `row-reverse` are affected by the directionality of the flex container. If its [`dir`](/en-US/docs/Web/HTML/Reference/Global_attributes/dir) attribute is `ltr`, `row` represents the horizontal axis oriented from the left to the right, and `row-reverse` from the right to the left; if the `dir` attribute is `rtl`, `row` represents the axis oriented from the right to the left, and `row-reverse` from the left to the right. ## Syntax @@ -55,7 +96,7 @@ Using the `flex-direction` property with values of `row-reverse` or `column-reve - [Flexbox & the keyboard navigation disconnect — Tink](https://tink.uk/flexbox-the-keyboard-navigation-disconnect/) - [Source Order Matters | Adrian Roselli](https://adrianroselli.com/2015/09/source-order-matters.html) -- [MDN Understanding WCAG, Guideline 1.3 explanations](/en-US/docs/Web/Accessibility/Understanding_WCAG/Perceivable#guideline_1.3_%e2%80%94_create_content_that_can_be_presented_in_different_ways) +- [MDN Understanding WCAG, Guideline 1.3 explanations](/en-US/docs/Web/Accessibility/Guides/Understanding_WCAG/Perceivable#guideline_1.3_%e2%80%94_create_content_that_can_be_presented_in_different_ways) - [Understanding Success Criterion 1.3.2 | W3C Understanding WCAG 2.0](https://www.w3.org/TR/UNDERSTANDING-WCAG20/content-structure-separation-sequence.html) ## Formal definition diff --git a/files/en-us/web/css/flex-flow/index.md b/files/en-us/web/css/flex-flow/index.md index 87bfcbc9128c9fa..70553973a3144f2 100644 --- a/files/en-us/web/css/flex-flow/index.md +++ b/files/en-us/web/css/flex-flow/index.md @@ -9,7 +9,52 @@ browser-compat: css.properties.flex-flow The **`flex-flow`** [CSS](/en-US/docs/Web/CSS) [shorthand property](/en-US/docs/Web/CSS/CSS_cascade/Shorthand_properties) specifies the direction of a flex container, as well as its wrapping behavior. -{{EmbedInteractiveExample("pages/css/flex-flow.html")}} +{{InteractiveExample("CSS Demo: flex-flow")}} + +```css interactive-example-choice +flex-flow: row wrap; +``` + +```css interactive-example-choice +flex-flow: row-reverse nowrap; +``` + +```css interactive-example-choice +flex-flow: column wrap-reverse; +``` + +```css interactive-example-choice +flex-flow: column wrap; +``` + +```html interactive-example +<section class="default-example" id="default-example"> + <div class="transition-all" id="example-element"> + <div>Item One</div> + <div>Item Two</div> + <div>Item Three</div> + <div>Item Four</div> + <div>Item Five</div> + <div>Item Six</div> + </div> +</section> +``` + +```css interactive-example +#example-element { + border: 1px solid #c5c5c5; + width: 80%; + max-height: 300px; + display: flex; +} + +#example-element > div { + background-color: rgba(0, 0, 255, 0.2); + border: 3px solid blue; + width: 60px; + margin: 10px; +} +``` ## Constituent properties diff --git a/files/en-us/web/css/flex-grow/index.md b/files/en-us/web/css/flex-grow/index.md index 4d3a46764d2e282..76ab4ce6ea51f29 100644 --- a/files/en-us/web/css/flex-grow/index.md +++ b/files/en-us/web/css/flex-grow/index.md @@ -11,7 +11,48 @@ The **`flex-grow`** [CSS](/en-US/docs/Web/CSS) property sets the flex grow facto When the flex-container's main size is larger than the combined main sizes of its flex items, this positive free space can be distributed among the flex items, with each item's growth being their growth factor value as a proportion of the sum total of all the flex items' flex grow factors. -{{EmbedInteractiveExample("pages/css/flex-grow.html")}} +> [!NOTE] +> It is recommended to use the {{cssxref("flex")}} shorthand with a keyword value like `auto` or `initial` instead of setting `flex-basis` on its own. The [keyword values](/en-US/docs/Web/CSS/flex#values) expand to reliable combinations of `flex-grow`, {{cssxref("flex-shrink")}}, and {{cssxref("flex-basis")}}, which help to achieve the commonly desired flex behaviors. + +{{InteractiveExample("CSS Demo: flex-grow")}} + +```css interactive-example-choice +flex-grow: 1; +``` + +```css interactive-example-choice +flex-grow: 2; +``` + +```css interactive-example-choice +flex-grow: 3; +``` + +```html interactive-example +<section class="default-example" id="default-example"> + <div class="transition-all" id="example-element">I grow</div> + <div>Item Two</div> + <div>Item Three</div> +</section> +``` + +```css interactive-example +.default-example { + border: 1px solid #c5c5c5; + width: auto; + max-height: 300px; + display: flex; +} + +.default-example > div { + background-color: rgba(0, 0, 255, 0.2); + border: 3px solid blue; + margin: 10px; + flex-grow: 1; + flex-shrink: 1; + flex-basis: 0; +} +``` ## Syntax diff --git a/files/en-us/web/css/flex-shrink/index.md b/files/en-us/web/css/flex-shrink/index.md index 8ae9f332130e4ec..baff251f0603793 100644 --- a/files/en-us/web/css/flex-shrink/index.md +++ b/files/en-us/web/css/flex-shrink/index.md @@ -10,9 +10,47 @@ browser-compat: css.properties.flex-shrink The **`flex-shrink`** [CSS](/en-US/docs/Web/CSS) property sets the flex shrink factor of a flex item. If the size of all flex items is larger than the flex container, the [flex items can shrink](/en-US/docs/Web/CSS/CSS_flexible_box_layout/Controlling_ratios_of_flex_items_along_the_main_axis#the_flex-shrink_property) to fit according to their `flex-shrink` value. Each flex line's [negative free space](/en-US/docs/Web/CSS/CSS_flexible_box_layout/Controlling_ratios_of_flex_items_along_the_main_axis#positive_and_negative_free_space) is distributed between the line's flex items that have a `flex-shrink` value greater than `0`. > [!NOTE] -> It is recommended to use the {{cssxref("flex")}} shorthand instead of separate `flex-shrink`, {{cssxref("flex-grow")}} and {{cssxref("flex-basis")}} declarations. We have separated them here as this document covers one of the `flex` shorthand components: the `flex-shrink` property. +> It is recommended to use the {{cssxref("flex")}} shorthand with a keyword value like `auto` or `initial` instead of setting `flex-basis` on its own. The [keyword values](/en-US/docs/Web/CSS/flex#values) expand to reliable combinations of {{cssxref("flex-grow")}}, `flex-shrink`, and {{cssxref("flex-basis")}}, which help to achieve the commonly desired flex behaviors. -{{EmbedInteractiveExample("pages/css/flex-shrink.html")}} +{{InteractiveExample("CSS Demo: flex-shrink")}} + +```css interactive-example-choice +flex-shrink: 0; +``` + +```css interactive-example-choice +flex-shrink: 1; +``` + +```css interactive-example-choice +flex-shrink: 2; +``` + +```html interactive-example +<section class="default-example" id="default-example"> + <div class="transition-all" id="example-element">I shrink</div> + <div>Item Two</div> + <div>Item Three</div> +</section> +``` + +```css interactive-example +.default-example { + border: 1px solid #c5c5c5; + width: auto; + max-height: 300px; + display: flex; +} + +.default-example > div { + background-color: rgba(0, 0, 255, 0.2); + border: 3px solid blue; + margin: 10px; + flex-grow: 1; + flex-shrink: 1; + flex-basis: 300px; +} +``` ## Syntax diff --git a/files/en-us/web/css/flex-wrap/index.md b/files/en-us/web/css/flex-wrap/index.md index fb6215c91be0028..25917468690e537 100644 --- a/files/en-us/web/css/flex-wrap/index.md +++ b/files/en-us/web/css/flex-wrap/index.md @@ -9,7 +9,47 @@ browser-compat: css.properties.flex-wrap The **`flex-wrap`** [CSS](/en-US/docs/Web/CSS) property sets whether flex items are forced onto one line or can wrap onto multiple lines. If wrapping is allowed, it sets the direction that lines are stacked. -{{EmbedInteractiveExample("pages/css/flex-wrap.html")}} +{{InteractiveExample("CSS Demo: flex-wrap")}} + +```css interactive-example-choice +flex-wrap: nowrap; +``` + +```css interactive-example-choice +flex-wrap: wrap; +``` + +```css interactive-example-choice +flex-wrap: wrap-reverse; +``` + +```html interactive-example +<section class="default-example" id="default-example"> + <div class="transition-all" id="example-element"> + <div>Item One</div> + <div>Item Two</div> + <div>Item Three</div> + <div>Item Four</div> + <div>Item Five</div> + <div>Item Six</div> + </div> +</section> +``` + +```css interactive-example +#example-element { + border: 1px solid #c5c5c5; + width: 80%; + display: flex; +} + +#example-element > div { + background-color: rgba(0, 0, 255, 0.2); + border: 3px solid blue; + width: 60px; + margin: 10px; +} +``` The {{cssxref("flex-flow")}} property shorthand can be used to set both the {{CSSXRef("flex-direction")}} and `flex-wrap` properties, which define the flex container's main and cross axes, respectively. diff --git a/files/en-us/web/css/flex/index.md b/files/en-us/web/css/flex/index.md index afafe213009b096..2cbb7d735bd08f6 100644 --- a/files/en-us/web/css/flex/index.md +++ b/files/en-us/web/css/flex/index.md @@ -9,7 +9,54 @@ browser-compat: css.properties.flex The **`flex`** [CSS](/en-US/docs/Web/CSS) [shorthand property](/en-US/docs/Web/CSS/CSS_cascade/Shorthand_properties) sets how a {{glossary("flex item")}} will grow or shrink to fit the space available in its flex container. -{{EmbedInteractiveExample("pages/css/flex.html")}} +{{InteractiveExample("CSS Demo: flex")}} + +```css interactive-example-choice +flex: 1; +``` + +```css interactive-example-choice +flex: 2; +``` + +```css interactive-example-choice +flex: 1 30px; +``` + +```css interactive-example-choice +flex: 1 1 100px; +``` + +```html interactive-example +<section class="default-example" id="default-example"> + <div class="transition-all" id="example-element">Change me</div> + <div>flex: 1</div> + <div>flex: 1</div> +</section> +``` + +```css interactive-example +.default-example { + border: 1px solid #c5c5c5; + width: auto; + max-height: 300px; + display: flex; +} + +.default-example > div { + background-color: rgba(0, 0, 255, 0.2); + border: 3px solid blue; + margin: 10px; + flex-grow: 1; + flex-shrink: 1; + flex-basis: 0; +} + +#example-element { + background-color: rgba(255, 0, 200, 0.2); + border: 3px solid rebeccapurple; +} +``` ## Constituent properties @@ -215,7 +262,7 @@ This example shows how a flex item with `flex: auto` grows to absorb any free sp ```css hidden body * { padding: 1rem; - text-select: none; + user-select: none; box-sizing: border-box; font-family: Consolas, Arial, sans-serif; } @@ -254,8 +301,8 @@ flexAutoItem.addEventListener("click", () => { The flex container contains two flex items: -- The `#flex-auto` item has a `flex` value of [`auto`](#auto). The `auto` value expands to `1 1 auto`, i.e. the item is allowed to expand. -- The `#default` item has no `flex` value set so it defaults to the [`initial`](#initial) value. The `initial` value expands to `0 1 auto`, i.e. the item is not allowed to expand. +- The `#flex-auto` item has a `flex` value of `auto`. The `auto` value expands to `1 1 auto`, i.e., the item is allowed to expand. +- The `#default` item has no `flex` value set so it defaults to the `initial` value. The `initial` value expands to `0 1 auto`, i.e., the item is not allowed to expand. The `#default` item takes up as much space as its width requires, but does not expand to take up any more space. All the remaining space is taken up by the `#flex-auto` item. diff --git a/files/en-us/web/css/float/index.md b/files/en-us/web/css/float/index.md index 2f2a25af81abbff..361d9d719921bb3 100644 --- a/files/en-us/web/css/float/index.md +++ b/files/en-us/web/css/float/index.md @@ -9,7 +9,56 @@ browser-compat: css.properties.float The **`float`** [CSS](/en-US/docs/Web/CSS) property places an element on the left or right side of its container, allowing text and inline elements to wrap around it. The element is removed from the normal flow of the page, though still remaining a part of the flow (in contrast to [absolute positioning](/en-US/docs/Web/CSS/position#absolute_positioning)). -{{EmbedInteractiveExample("pages/css/float.html")}} +{{InteractiveExample("CSS Demo: float")}} + +```css interactive-example-choice +float: none; +``` + +```css interactive-example-choice +float: left; +``` + +```css interactive-example-choice +float: right; +``` + +```css interactive-example-choice +float: inline-start; +``` + +```css interactive-example-choice +float: inline-end; +``` + +```html interactive-example +<section class="default-example" id="default-example"> + <div class="example-container"> + <div class="transition-all" id="example-element">Float me</div> + As much mud in the streets as if the waters had but newly retired from the + face of the earth, and it would not be wonderful to meet a Megalosaurus, + forty feet long or so, waddling like an elephantine lizard up Holborn Hill. + </div> +</section> +``` + +```css interactive-example +.example-container { + border: 1px solid #c5c5c5; + padding: 0.75em; + text-align: left; + width: 80%; + line-height: normal; +} + +#example-element { + border: solid 10px #efac09; + background-color: #040d46; + color: white; + padding: 1em; + width: 40%; +} +``` A _floating element_ is one where the computed value of `float` is not `none`. diff --git a/files/en-us/web/css/font-family/index.md b/files/en-us/web/css/font-family/index.md index 63c04d186156d32..808ba70bbf77d87 100644 --- a/files/en-us/web/css/font-family/index.md +++ b/files/en-us/web/css/font-family/index.md @@ -9,7 +9,49 @@ browser-compat: css.properties.font-family The **`font-family`** [CSS](/en-US/docs/Web/CSS) property specifies a prioritized list of one or more font family names and/or generic family names for the selected element. -{{EmbedInteractiveExample("pages/css/font-family.html")}} +{{InteractiveExample("CSS Demo: font-family")}} + +```css interactive-example-choice +font-family: Georgia, serif; +``` + +```css interactive-example-choice +font-family: "Gill Sans", sans-serif; +``` + +```css interactive-example-choice +font-family: sans-serif; +``` + +```css interactive-example-choice +font-family: serif; +``` + +```css interactive-example-choice +font-family: cursive; +``` + +```css interactive-example-choice +font-family: system-ui; +``` + +```html interactive-example +<section id="default-example"> + <p id="example-element"> + London. Michaelmas term lately over, and the Lord Chancellor sitting in + Lincoln's Inn Hall. Implacable November weather. As much mud in the streets + as if the waters had but newly retired from the face of the earth, and it + would not be wonderful to meet a Megalosaurus, forty feet long or so, + waddling like an elephantine lizard up Holborn Hill. + </p> +</section> +``` + +```css interactive-example +section { + font-size: 1.2em; +} +``` Values are separated by commas to indicate that they are alternatives. The browser will select the first font in the list that is installed or that can be downloaded using a {{CSSxRef("@font-face")}} at-rule. diff --git a/files/en-us/web/css/font-feature-settings/index.md b/files/en-us/web/css/font-feature-settings/index.md index a41647a6f03d6e1..a5cf91d2a612b46 100644 --- a/files/en-us/web/css/font-feature-settings/index.md +++ b/files/en-us/web/css/font-feature-settings/index.md @@ -9,7 +9,68 @@ browser-compat: css.properties.font-feature-settings The **`font-feature-settings`** [CSS](/en-US/docs/Web/CSS) property controls advanced typographic features in OpenType fonts. -{{EmbedInteractiveExample("pages/css/font-feature-settings.html")}} +{{InteractiveExample("CSS Demo: font-feature-settings")}} + +```css interactive-example-choice +font-feature-settings: normal; +``` + +```css interactive-example-choice +font-feature-settings: "liga" 0; +``` + +```css interactive-example-choice +font-feature-settings: "tnum"; +``` + +```css interactive-example-choice +font-feature-settings: "smcp", "zero"; +``` + +```html interactive-example +<section id="default-example"> + <div id="example-element"> + <p>Difficult waffles</p> + <table> + <tr> + <td><span class="tabular">0O</span></td> + </tr> + <tr> + <td><span class="tabular">3.14</span></td> + </tr> + <tr> + <td><span class="tabular">2.71</span></td> + </tr> + </table> + </div> +</section> +``` + +```css interactive-example +@font-face { + font-family: "Fira Sans"; + src: + local("FiraSans-Regular"), + url("/shared-assets/fonts/FiraSans-Regular.woff2") format("woff2"); + font-weight: normal; + font-style: normal; +} + +section { + font-family: "Fira Sans", sans-serif; + margin-top: 10px; + font-size: 1.5em; +} + +#example-element table { + margin-left: auto; + margin-right: auto; +} + +.tabular { + border: 1px solid; +} +``` ## Syntax diff --git a/files/en-us/web/css/font-kerning/index.md b/files/en-us/web/css/font-kerning/index.md index e5d8314c20c7c16..f95c967ea9efb64 100644 --- a/files/en-us/web/css/font-kerning/index.md +++ b/files/en-us/web/css/font-kerning/index.md @@ -9,7 +9,33 @@ browser-compat: css.properties.font-kerning The **`font-kerning`** [CSS](/en-US/docs/Web/CSS) property sets the use of the kerning information stored in a font. -{{EmbedInteractiveExample("pages/css/font-kerning.html")}} +{{InteractiveExample("CSS Demo: font-kerning")}} + +```css interactive-example-choice +font-kerning: auto; +``` + +```css interactive-example-choice +font-kerning: normal; +``` + +```css interactive-example-choice +font-kerning: none; +``` + +```html interactive-example +<section class="default-example" id="default-example"> + <div class="transition-all" id="example-element"> + “We took Tracy to see ‘THE WATERFALL’ in W. Virginia.” + </div> +</section> +``` + +```css interactive-example +section { + font-family: serif; +} +``` _Kerning_ affects how letters are spaced. In _well-kerned_ fonts, this feature makes character spacing more uniform and pleasant to read by reducing white space between certain character combinations. diff --git a/files/en-us/web/css/font-optical-sizing/index.md b/files/en-us/web/css/font-optical-sizing/index.md index 8ea9acda0aab6e2..62c2323b659ecfd 100644 --- a/files/en-us/web/css/font-optical-sizing/index.md +++ b/files/en-us/web/css/font-optical-sizing/index.md @@ -9,7 +9,50 @@ browser-compat: css.properties.font-optical-sizing The **`font-optical-sizing`** [CSS](/en-US/docs/Web/CSS) property sets whether text rendering is optimized for viewing at different sizes. -{{EmbedInteractiveExample("pages/css/font-optical-sizing.html")}} +{{InteractiveExample("CSS Demo: font-optical-sizing")}} + +```css interactive-example-choice +font-optical-sizing: auto; +``` + +```css interactive-example-choice +font-optical-sizing: none; +``` + +```html interactive-example +<section id="default-example"> + <div id="example-element"> + <h2>Chapter 3</h2> + <p> + On this particular Thursday, something was moving quietly through the + ionosphere many miles above the surface of the planet; several somethings + in fact, several dozen huge yellow chunky slablike somethings, huge as + office blocks, silent as birds. + </p> + </div> +</section> +``` + +```css interactive-example +@font-face { + src: url("/shared-assets/fonts/variable-fonts/AmstelvarAlpha-VF.ttf"); + font-family: Amstelvar; + font-style: normal; +} + +#example-element { + font-family: Amstelvar; + text-align: left; +} + +#example-element h2 { + font-size: 36px; +} + +#example-element p { + font-size: 12px; +} +``` ## Syntax diff --git a/files/en-us/web/css/font-size-adjust/index.md b/files/en-us/web/css/font-size-adjust/index.md index defa181a359d684..15ddd766cc579df 100644 --- a/files/en-us/web/css/font-size-adjust/index.md +++ b/files/en-us/web/css/font-size-adjust/index.md @@ -146,7 +146,7 @@ In `C`, notice that only one value is specified for the `font-size-adjust` prope ### Determining the aspect value of a font -For a given font, the same content in two side-by-side [`<span>`](/en-US/docs/Web/HTML/Element/span) elements can be used to determine the font's aspect value. If the same font size is used for content in both spans, the spans will match when the `font-size-adjust` value in one span is accurate for the given font. +For a given font, the same content in two side-by-side [`<span>`](/en-US/docs/Web/HTML/Reference/Elements/span) elements can be used to determine the font's aspect value. If the same font size is used for content in both spans, the spans will match when the `font-size-adjust` value in one span is accurate for the given font. In the example below, there are three pairs of side-by-side `<span>` elements, each containing the letter "b". The goal is to adjust the `font-size-adjust` property for the right `<span>` in each pair until the borders around the two letters align. The resulting `font-size-adjust` value can be considered the aspect value for the font. diff --git a/files/en-us/web/css/font-size/index.md b/files/en-us/web/css/font-size/index.md index 288903c9423fada..f28dece0186bb6a 100644 --- a/files/en-us/web/css/font-size/index.md +++ b/files/en-us/web/css/font-size/index.md @@ -9,7 +9,39 @@ browser-compat: css.properties.font-size The **`font-size`** [CSS](/en-US/docs/Web/CSS) property sets the size of the font. Changing the font size also updates the sizes of the font size-relative {{cssxref("&lt;length&gt;")}} units, such as `em`, `ex`, and so forth. -{{EmbedInteractiveExample("pages/css/font-size.html")}} +{{InteractiveExample("CSS Demo: font-size")}} + +```css interactive-example-choice +font-size: 1.2rem; +``` + +```css interactive-example-choice +font-size: x-small; +``` + +```css interactive-example-choice +font-size: smaller; +``` + +```css interactive-example-choice +font-size: 12px; +``` + +```css interactive-example-choice +font-size: 80%; +``` + +```html interactive-example +<section id="default-example"> + <p id="example-element"> + London. Michaelmas term lately over, and the Lord Chancellor sitting in + Lincoln's Inn Hall. Implacable November weather. As much mud in the streets + as if the waters had but newly retired from the face of the earth, and it + would not be wonderful to meet a Megalosaurus, forty feet long or so, + waddling like an elephantine lizard up Holborn Hill. + </p> +</section> +``` ## Syntax diff --git a/files/en-us/web/css/font-smooth/index.md b/files/en-us/web/css/font-smooth/index.md index 68019ce7392f577..2eb9f47dfe26c83 100644 --- a/files/en-us/web/css/font-smooth/index.md +++ b/files/en-us/web/css/font-smooth/index.md @@ -50,10 +50,7 @@ font-smooth: unset; ## Formal syntax -```plain -font-smooth = - auto | never | always | <absolute-size> | <length> -``` +{{CSSSyntaxRaw(`font-smooth = auto | never | always | <absolute-size> | <length>`)}} ## Examples @@ -106,5 +103,5 @@ Not part of any standard. ## See also -- [Please Stop "Fixing" Font Smoothing – UsabilityPost](https://usabilitypost.com/2012/11/05/stop-fixing-font-smoothing/) -- [Laissez-faire font smoothing and anti-aliasing](https://www.zachleat.com/web/font-smooth/) +- [Please Stop "Fixing" Font Smoothing](https://usabilitypost.com/2012/11/05/stop-fixing-font-smoothing/) by Dmitry Fadeyev (2012) +- [Laissez-faire font smoothing and anti-aliasing](https://www.zachleat.com/web/font-smooth/) by Zach Leatherman (2017) diff --git a/files/en-us/web/css/font-stretch/index.md b/files/en-us/web/css/font-stretch/index.md index 6e5a51cc2f6a740..0e7e2066650e5a3 100644 --- a/files/en-us/web/css/font-stretch/index.md +++ b/files/en-us/web/css/font-stretch/index.md @@ -15,7 +15,58 @@ browser-compat: css.properties.font-stretch The **`font-stretch`** [CSS](/en-US/docs/Web/CSS) property selects a normal, condensed, or expanded face from a font. -{{EmbedInteractiveExample("pages/css/font-stretch.html")}} +{{InteractiveExample("CSS Demo: font-stretch")}} + +```css interactive-example-choice +font-stretch: condensed; +``` + +```css interactive-example-choice +font-stretch: expanded; +``` + +```css interactive-example-choice +font-stretch: ultra-expanded; +``` + +```css interactive-example-choice +font-stretch: 50%; +``` + +```css interactive-example-choice +font-stretch: 100%; +``` + +```css interactive-example-choice +font-stretch: 150%; +``` + +```html interactive-example +<section class="default-example" id="default-example"> + <p class="transition-all" id="example-element"> + London. Michaelmas term lately over, and the Lord Chancellor sitting in + Lincoln's Inn Hall. Implacable November weather. As much mud in the streets + as if the waters had but newly retired from the face of the earth, and it + would not be wonderful to meet a Megalosaurus, forty feet long or so, + waddling like an elephantine lizard up Holborn Hill. + </p> +</section> +``` + +```css interactive-example +@font-face { + src: url("/shared-assets/fonts/LeagueMono-VF.ttf") format("truetype"); + font-family: League; + font-style: normal; + font-weight: 400; + font-stretch: 50% 200%; /* Required by Chrome - allow 50% to 200% */ +} + +section { + font-size: 1.2em; + font-family: League, sans-serif; +} +``` ## Syntax diff --git a/files/en-us/web/css/font-style/index.md b/files/en-us/web/css/font-style/index.md index 8a433d75b747ef3..35151af4c3afad2 100644 --- a/files/en-us/web/css/font-style/index.md +++ b/files/en-us/web/css/font-style/index.md @@ -9,7 +9,48 @@ browser-compat: css.properties.font-style The **`font-style`** [CSS](/en-US/docs/Web/CSS) property sets whether a font should be styled with a normal, italic, or oblique face from its {{cssxref("font-family")}}. -{{EmbedInteractiveExample("pages/css/font-style.html")}} +{{InteractiveExample("CSS Demo: font-style")}} + +```css interactive-example-choice +font-style: normal; +``` + +```css interactive-example-choice +font-style: italic; +``` + +```css interactive-example-choice +font-style: oblique; +``` + +```css interactive-example-choice +font-style: oblique 40deg; +``` + +```html interactive-example +<section id="default-example"> + <p id="example-element"> + London. Michaelmas term lately over, and the Lord Chancellor sitting in + Lincoln's Inn Hall. Implacable November weather. As much mud in the streets + as if the waters had but newly retired from the face of the earth, and it + would not be wonderful to meet a Megalosaurus, forty feet long or so, + waddling like an elephantine lizard up Holborn Hill. + </p> +</section> +``` + +```css interactive-example +@font-face { + src: url("/shared-assets/fonts/variable-fonts/AmstelvarAlpha-VF.ttf"); + font-family: Amstelvar; + font-style: normal; +} + +section { + font-size: 1.2em; + font-family: Amstelvar; +} +``` **Italic** font faces are generally cursive in nature, usually using less horizontal space than their unstyled counterparts, while **oblique** faces are usually just sloped versions of the regular face. When the specified style is not available, both italic and oblique faces are simulated by artificially sloping the glyphs of the regular face (use {{cssxref("font-synthesis")}} to control this behavior). @@ -82,7 +123,7 @@ Click "Play" in the code blocks below to edit the example in the MDN Playground. Large sections of text set with a `font-style` value of `italic` may be difficult for people with cognitive concerns such as Dyslexia to read. -- [MDN Understanding WCAG, Guideline 1.4 explanations](/en-US/docs/Web/Accessibility/Understanding_WCAG/Perceivable#guideline_1.4_make_it_easier_for_users_to_see_and_hear_content_including_separating_foreground_from_background) +- [MDN Understanding WCAG, Guideline 1.4 explanations](/en-US/docs/Web/Accessibility/Guides/Understanding_WCAG/Perceivable#guideline_1.4_make_it_easier_for_users_to_see_and_hear_content_including_separating_foreground_from_background) - [W3C Understanding WCAG 2.1](https://www.w3.org/TR/WCAG21/#visual-presentation) ## Formal definition diff --git a/files/en-us/web/css/font-synthesis/index.md b/files/en-us/web/css/font-synthesis/index.md index 51bfa010a36378e..2137736803aa0ae 100644 --- a/files/en-us/web/css/font-synthesis/index.md +++ b/files/en-us/web/css/font-synthesis/index.md @@ -9,7 +9,136 @@ browser-compat: css.properties.font-synthesis The **`font-synthesis`** [shorthand](/en-US/docs/Web/CSS/CSS_cascade/Shorthand_properties) [CSS](/en-US/docs/Web/CSS) property lets you specify whether or not the browser may synthesize the bold, italic, small-caps, and/or subscript and superscript typefaces when they are missing in the specified font-family. -{{EmbedInteractiveExample("pages/css/font-synthesis.html")}} +{{InteractiveExample("CSS Demo: font-synthesis")}} + +```css interactive-example-choice +font-synthesis: weight style small-caps; +``` + +```css interactive-example-choice +font-synthesis: none; +``` + +```css interactive-example-choice +font-synthesis: weight; +``` + +```css interactive-example-choice +font-synthesis: style; +``` + +```css interactive-example-choice +font-synthesis: small-caps; +``` + +```css interactive-example-choice +font-synthesis: position; +``` + +```html interactive-example +<section class="default-example" id="default-example"> + <div class="transition-all" id="example-element"> + <p class="english"> + This font does not include <span class="bold">bold</span>, + <span class="italic">italic</span>, + <span class="small-caps">small-caps</span>, and + <span class="sub">subscript</span> or + <span class="sup">superscript</span> variants. + </p> + <p class="chinese"> + 中文排版通常不运用<span class="bold">粗体</span>或<span class="italic" + >斜体</span + ><span class="sub">常不</span><span class="sup">运用</span>。 + </p> + </div> +</section> +``` + +```css interactive-example +@font-face { + font-family: Oxygen; + font-style: normal; + font-weight: 400; + src: url("https://fonts.gstatic.com/s/oxygen/v14/2sDfZG1Wl4LcnbuKjk0m.woff2") + format("woff2"); +} + +/* [108] */ +@font-face { + font-family: "Ma Shan Zheng"; + font-style: normal; + font-weight: 400; + font-display: swap; + src: url("https://fonts.gstatic.com/s/mashanzheng/v10/NaPecZTRCLxvwo41b4gvzkXaRMGEFoZJFdX0wQ5Xo5Hr21L9zCcRFhbSe5Nk0pIMuUkHEA.108.woff2") + format("woff2"); +} +/* [110] */ +@font-face { + font-family: "Ma Shan Zheng"; + font-style: normal; + font-weight: 400; + font-display: swap; + src: url("https://fonts.gstatic.com/s/mashanzheng/v10/NaPecZTRCLxvwo41b4gvzkXaRMGEFoZJFdX0wQ5Xo5Hr21L9zCcRFhbSe5Nk0pIMuUkHEA.110.woff2") + format("woff2"); +} +/* [117] */ +@font-face { + font-family: "Ma Shan Zheng"; + font-style: normal; + font-weight: 400; + font-display: swap; + src: url("https://fonts.gstatic.com/s/mashanzheng/v10/NaPecZTRCLxvwo41b4gvzkXaRMGEFoZJFdX0wQ5Xo5Hr21L9zCcRFhbSe5Nk0pIMuUkHEA.117.woff2") + format("woff2"); +} +/* [118] */ +@font-face { + font-family: "Ma Shan Zheng"; + font-style: normal; + font-weight: 400; + font-display: swap; + src: url("https://fonts.gstatic.com/s/mashanzheng/v10/NaPecZTRCLxvwo41b4gvzkXaRMGEFoZJFdX0wQ5Xo5Hr21L9zCcRFhbSe5Nk0pIMuUkHEA.118.woff2") + format("woff2"); +} +/* [119] */ +@font-face { + font-family: "Ma Shan Zheng"; + font-style: normal; + font-weight: 400; + font-display: swap; + src: url("https://fonts.gstatic.com/s/mashanzheng/v10/NaPecZTRCLxvwo41b4gvzkXaRMGEFoZJFdX0wQ5Xo5Hr21L9zCcRFhbSe5Nk0pIMuUkHEA.119.woff2") + format("woff2"); +} + +.english { + font-size: 1.2em; + font-family: Oxygen; +} + +.chinese { + font-size: 1.2em; + font-family: "Ma Shan Zheng"; +} + +.bold { + font-weight: bold; +} + +.italic { + font-style: italic; +} + +.small-caps { + font-variant: small-caps; +} + +.sub { + font-variant: sub; +} + +.sup { + font-variant: super; +} +``` ## Constituent properties diff --git a/files/en-us/web/css/font-variant-caps/index.md b/files/en-us/web/css/font-variant-caps/index.md index e993f3546d409a4..d9c8cfd210f1952 100644 --- a/files/en-us/web/css/font-variant-caps/index.md +++ b/files/en-us/web/css/font-variant-caps/index.md @@ -9,7 +9,44 @@ browser-compat: css.properties.font-variant-caps The **`font-variant-caps`** [CSS](/en-US/docs/Web/CSS) property controls the use of alternate glyphs used for small or petite capitals or for titling. -{{EmbedInteractiveExample("pages/css/font-variant-caps.html")}} +{{InteractiveExample("CSS Demo: font-variant-caps")}} + +```css interactive-example-choice +font-variant-caps: normal; +``` + +```css interactive-example-choice +font-variant-caps: small-caps; +``` + +```css interactive-example-choice +font-variant-caps: all-small-caps; +``` + +```html interactive-example +<section id="default-example"> + <div id="example-element"> + <p>Difficult waffles</p> + </div> +</section> +``` + +```css interactive-example +@font-face { + font-family: "Fira Sans"; + src: + local("FiraSans-Regular"), + url("/shared-assets/fonts/FiraSans-Regular.woff2") format("woff2"); + font-weight: normal; + font-style: normal; +} + +section { + font-family: "Fira Sans", sans-serif; + margin-top: 10px; + font-size: 1.5em; +} +``` When a given font includes capital letter glyphs of multiple different sizes, this property selects the most appropriate ones. If petite capital glyphs are not available, they are rendered using small capital glyphs. If these are not present, the browser synthesizes them from the uppercase glyphs. @@ -66,7 +103,7 @@ The `font-variant-caps` property is specified using a single keyword value from Large sections of text set with a `font-variant` value of `all-small-caps` or `all-petite-caps` may be difficult for people with cognitive concerns such as Dyslexia to read. -- [MDN Understanding WCAG, Guideline 1.4 explanations](/en-US/docs/Web/Accessibility/Understanding_WCAG/Perceivable#guideline_1.4_make_it_easier_for_users_to_see_and_hear_content_including_separating_foreground_from_background) +- [MDN Understanding WCAG, Guideline 1.4 explanations](/en-US/docs/Web/Accessibility/Guides/Understanding_WCAG/Perceivable#guideline_1.4_make_it_easier_for_users_to_see_and_hear_content_including_separating_foreground_from_background) - [W3C Understanding WCAG 2.1](https://www.w3.org/TR/WCAG21/#visual-presentation) ## Formal definition diff --git a/files/en-us/web/css/font-variant-east-asian/index.md b/files/en-us/web/css/font-variant-east-asian/index.md index 53d4f42976685da..f2e67817cf975db 100644 --- a/files/en-us/web/css/font-variant-east-asian/index.md +++ b/files/en-us/web/css/font-variant-east-asian/index.md @@ -9,7 +9,42 @@ browser-compat: css.properties.font-variant-east-asian The **`font-variant-east-asian`** [CSS](/en-US/docs/Web/CSS) property controls the use of alternate glyphs for East Asian scripts, like Japanese and Chinese. -{{EmbedInteractiveExample("pages/css/font-variant-east-asian.html")}} +{{InteractiveExample("CSS Demo: font-variant-east-asian")}} + +```css interactive-example-choice +font-variant-east-asian: normal; +``` + +```css interactive-example-choice +font-variant-east-asian: ruby; +``` + +```css interactive-example-choice +font-variant-east-asian: jis78; +``` + +```css interactive-example-choice +font-variant-east-asian: proportional-width; +``` + +```html interactive-example +<section id="default-example"> + <div id="example-element"> + <p> + JIS78とJIS83以降では、檜と桧、籠と篭など、一部の文字の入れ替えが行われている。また、「唖然」や「躯体」などの書体が変更されている。 + </p> + </div> +</section> +``` + +```css interactive-example +section { + font-family: + "YuGothic Medium", YuGothic, "Yu Gothic Medium", "Yu Gothic", sans-serif; + margin-top: 10px; + font-size: 1.5em; +} +``` ## Syntax @@ -79,7 +114,7 @@ This example require font "Yu Gothic" installed in your OS, other fonts may not ```html <table> <thead></thead> - <tbody style="border:0;"> + <tbody> <tr> <th>normal/jis78:</th> <td>麹町</td> @@ -102,6 +137,10 @@ This example require font "Yu Gothic" installed in your OS, other fonts may not #### CSS ```css +tbody { + border: 0; +} + td { font-family: "Yu Gothic"; font-size: 20px; diff --git a/files/en-us/web/css/font-variant-ligatures/index.md b/files/en-us/web/css/font-variant-ligatures/index.md index 42d8f1c938cc669..c12c63d86c5d99b 100644 --- a/files/en-us/web/css/font-variant-ligatures/index.md +++ b/files/en-us/web/css/font-variant-ligatures/index.md @@ -9,7 +9,44 @@ browser-compat: css.properties.font-variant-ligatures The **`font-variant-ligatures`** [CSS](/en-US/docs/Web/CSS) property controls which {{Glossary("ligature", "ligatures")}} and {{Glossary("contextual forms")}} are used in the textual content of the elements it applies to. This leads to more harmonized forms in the resulting text. -{{EmbedInteractiveExample("pages/css/font-variant-ligatures.html")}} +{{InteractiveExample("CSS Demo: font-variant-ligatures")}} + +```css interactive-example-choice +font-variant-ligatures: normal; +``` + +```css interactive-example-choice +font-variant-ligatures: no-common-ligatures; +``` + +```css interactive-example-choice +font-variant-ligatures: common-ligatures; +``` + +```html interactive-example +<section id="default-example"> + <div id="example-element"> + <p>Difficult waffles</p> + </div> +</section> +``` + +```css interactive-example +@font-face { + font-family: "Fira Sans"; + src: + local("FiraSans-Regular"), + url("/shared-assets/fonts/FiraSans-Regular.woff2") format("woff2"); + font-weight: normal; + font-style: normal; +} + +section { + font-family: "Fira Sans", sans-serif; + margin-top: 10px; + font-size: 1.5em; +} +``` ## Syntax diff --git a/files/en-us/web/css/font-variant-numeric/index.md b/files/en-us/web/css/font-variant-numeric/index.md index 7dcbd96103c583b..589085b463e6092 100644 --- a/files/en-us/web/css/font-variant-numeric/index.md +++ b/files/en-us/web/css/font-variant-numeric/index.md @@ -9,7 +9,67 @@ browser-compat: css.properties.font-variant-numeric The **`font-variant-numeric`** [CSS](/en-US/docs/Web/CSS) property controls the usage of alternate glyphs for numbers, fractions, and ordinal markers. -{{EmbedInteractiveExample("pages/css/font-variant-numeric.html")}} +{{InteractiveExample("CSS Demo: font-variant-numeric")}} + +```css interactive-example-choice +font-variant-numeric: normal; +``` + +```css interactive-example-choice +font-variant-numeric: slashed-zero; +``` + +```css interactive-example-choice +font-variant-numeric: tabular-nums; +``` + +```css interactive-example-choice +font-variant-numeric: oldstyle-nums; +``` + +```html interactive-example +<section id="default-example"> + <div id="example-element"> + <table> + <tr> + <td><span class="tabular">0</span></td> + </tr> + <tr> + <td><span class="tabular">3.54</span></td> + </tr> + <tr> + <td><span class="tabular">1.71</span></td> + </tr> + </table> + </div> +</section> +``` + +```css interactive-example +@font-face { + font-family: "Fira Sans"; + src: + local("FiraSans-Regular"), + url("/shared-assets/fonts/FiraSans-Regular.woff2") format("woff2"); + font-weight: normal; + font-style: normal; +} + +section { + font-family: "Fira Sans", sans-serif; + margin-top: 10px; + font-size: 1.5em; +} + +#example-element table { + margin-left: auto; + margin-right: auto; +} + +.tabular { + border: 1px solid; +} +``` ## Syntax diff --git a/files/en-us/web/css/font-variant/index.md b/files/en-us/web/css/font-variant/index.md index 8d332d315c4c33d..c2d7eb6d0621970 100644 --- a/files/en-us/web/css/font-variant/index.md +++ b/files/en-us/web/css/font-variant/index.md @@ -11,7 +11,68 @@ The **`font-variant`** CSS [shorthand property](/en-US/docs/Web/CSS/CSS_cascade/ You can also set the `<font-variant-css2>` values of `font-variant` defined in CSS Level 2.1, (that is, `normal` or `small-caps`), by using the [`font`](/en-US/docs/Web/CSS/font) shorthand. -{{EmbedInteractiveExample("pages/css/font-variant.html")}} +{{InteractiveExample("CSS Demo: font-variant")}} + +```css interactive-example-choice +font-variant: normal; +``` + +```css interactive-example-choice +font-variant: no-common-ligatures proportional-nums; +``` + +```css interactive-example-choice +font-variant: common-ligatures tabular-nums; +``` + +```css interactive-example-choice +font-variant: small-caps slashed-zero; +``` + +```html interactive-example +<section id="default-example"> + <div id="example-element"> + <p>Difficult waffles</p> + <table> + <tr> + <td><span class="tabular">0O</span></td> + </tr> + <tr> + <td><span class="tabular">3.14</span></td> + </tr> + <tr> + <td><span class="tabular">2.71</span></td> + </tr> + </table> + </div> +</section> +``` + +```css interactive-example +@font-face { + font-family: "Fira Sans"; + src: + local("FiraSans-Regular"), + url("/shared-assets/fonts/FiraSans-Regular.woff2") format("woff2"); + font-weight: normal; + font-style: normal; +} + +section { + font-family: "Fira Sans", sans-serif; + margin-top: 10px; + font-size: 1.5em; +} + +#example-element table { + margin-left: auto; + margin-right: auto; +} + +.tabular { + border: 1px solid; +} +``` ## Constituent properties diff --git a/files/en-us/web/css/font-variation-settings/index.md b/files/en-us/web/css/font-variation-settings/index.md index a9c87895e7faec2..6cf7ae6600816ea 100644 --- a/files/en-us/web/css/font-variation-settings/index.md +++ b/files/en-us/web/css/font-variation-settings/index.md @@ -9,7 +9,45 @@ browser-compat: css.properties.font-variation-settings The **`font-variation-settings`** [CSS](/en-US/docs/Web/CSS) property provides low-level control over [variable font](/en-US/docs/Web/CSS/CSS_fonts/Variable_fonts_guide) characteristics by letting you specify the four letter axis names of the characteristics you want to vary along with their values. -{{EmbedInteractiveExample("pages/css/font-variation-settings.html")}} +{{InteractiveExample("CSS Demo: font-variation-settings")}} + +```css interactive-example-choice +font-variation-settings: "wght" 50; +``` + +```css interactive-example-choice +font-variation-settings: "wght" 850; +``` + +```css interactive-example-choice +font-variation-settings: "wdth" 25; +``` + +```css interactive-example-choice +font-variation-settings: "wdth" 75; +``` + +```html interactive-example +<section id="default-example"> + <p id="example-element"> + ...it would not be wonderful to meet a Megalosaurus, forty feet long or so, + waddling like an elephantine lizard up Holborn Hill. + </p> +</section> +``` + +```css interactive-example +@font-face { + src: url("/shared-assets/fonts/variable-fonts/AmstelvarAlpha-VF.ttf"); + font-family: Amstelvar; + font-style: normal; +} + +p { + font-size: 1.5rem; + font-family: Amstelvar; +} +``` ## Syntax @@ -39,9 +77,9 @@ This property's value can take one of two forms: ## Description -This property is a low-level mechanism designed to set variable font features where no other way to enable or access those features exist. You should only use it when no basic properties exist to set those features (e.g. {{cssxref("font-weight")}}, {{cssxref("font-style")}}). +This property is a low-level mechanism designed to set variable font features where no other way to enable or access those features exist. You should only use it when no basic properties exist to set those features (e.g., {{cssxref("font-weight")}}, {{cssxref("font-style")}}). -Font characteristics set using `font-variation-settings` will always override those set using the corresponding basic font properties, e.g. `font-weight`, no matter where they appear in the cascade. In some browsers, this is currently only true when the {{cssxref("@font-face")}} declaration includes a {{cssxref("@font-face/font-weight", "font-weight")}} range. +Font characteristics set using `font-variation-settings` will always override those set using the corresponding basic font properties, e.g., `font-weight`, no matter where they appear in the cascade. In some browsers, this is currently only true when the {{cssxref("@font-face")}} declaration includes a {{cssxref("@font-face/font-weight", "font-weight")}} range. ### Registered and custom axes @@ -87,7 +125,7 @@ Custom axes can be anything the font designer wants to vary in their font, for e > [!NOTE] > Registered axis tags are identified using lower-case tags, whereas custom axes should be given upper-case tags. Note that font designers aren't forced to follow this practice in any way, and some won't. The important takeaway here is that axis tags are case-sensitive. -To use variable fonts on your operating system, you need to make sure that it is up to date. For example Linux OSes need the latest Linux Freetype version, and macOS before 10.13 does not support variable fonts. If your operating system is not up to date, you will not be able to use variable fonts in web pages or the Firefox Developer Tools. +To use variable fonts on your operating system, you need to make sure that it is up to date. For example Linux OSes need the latest Linux FreeType version, and macOS before 10.13 does not support variable fonts. If your operating system is not up to date, you will not be able to use variable fonts in web pages or the Firefox Developer Tools. ## Formal definition diff --git a/files/en-us/web/css/font-weight/index.md b/files/en-us/web/css/font-weight/index.md index 1207704677c7c3f..693d1ab62461816 100644 --- a/files/en-us/web/css/font-weight/index.md +++ b/files/en-us/web/css/font-weight/index.md @@ -9,7 +9,49 @@ browser-compat: css.properties.font-weight The **`font-weight`** [CSS](/en-US/docs/Web/CSS) property sets the weight (or boldness) of the font. The weights available depend on the {{cssxref("font-family")}} that is currently set. -{{EmbedInteractiveExample("pages/css/font-weight.html")}} +{{InteractiveExample("CSS Demo: font-weight")}} + +```css interactive-example-choice +font-weight: normal; +``` + +```css interactive-example-choice +font-weight: bold; +``` + +```css interactive-example-choice +font-weight: lighter; +``` + +```css interactive-example-choice +font-weight: bolder; +``` + +```css interactive-example-choice +font-weight: 100; +``` + +```css interactive-example-choice +font-weight: 900; +``` + +```html interactive-example +<section id="default-example"> + <p id="example-element"> + London. Michaelmas term lately over, and the Lord Chancellor sitting in + Lincoln's Inn Hall. Implacable November weather. As much mud in the streets + as if the waters had but newly retired from the face of the earth, and it + would not be wonderful to meet a Megalosaurus, forty feet long or so, + waddling like an elephantine lizard up Holborn Hill. + </p> +</section> +``` + +```css interactive-example +section { + font-size: 1.2em; +} +``` ## Syntax @@ -187,9 +229,8 @@ This demo loads with `font-weight: 500;` set. Change the value of the `font-weig .sample { text-transform: uppercase; font-weight: 500; - font: - 1.5rem "MutatorSans", - sans-serif; + font-size: 1.5rem; + font-family: "MutatorSans", sans-serif; } ``` @@ -199,7 +240,7 @@ This demo loads with `font-weight: 500;` set. Change the value of the `font-weig People experiencing low vision conditions may have difficulty reading text set with a `font-weight` value of `100` (Thin/Hairline) or `200` (Extra Light), especially if the font has a [low contrast color ratio](/en-US/docs/Web/CSS/color#accessibility). -- [MDN Understanding WCAG, Guideline 1.4 explanations](/en-US/docs/Web/Accessibility/Understanding_WCAG/Perceivable#guideline_1.4_make_it_easier_for_users_to_see_and_hear_content_including_separating_foreground_from_background) +- [MDN Understanding WCAG, Guideline 1.4 explanations](/en-US/docs/Web/Accessibility/Guides/Understanding_WCAG/Perceivable#guideline_1.4_make_it_easier_for_users_to_see_and_hear_content_including_separating_foreground_from_background) - [Understanding Success Criterion 1.4.8 | W3C Understanding WCAG 2.0](https://www.w3.org/TR/UNDERSTANDING-WCAG20/visual-audio-contrast-visual-presentation.html) ## Formal definition diff --git a/files/en-us/web/css/font/index.md b/files/en-us/web/css/font/index.md index 9d0a3e2decd792e..3e3a3d08ffe4c9c 100644 --- a/files/en-us/web/css/font/index.md +++ b/files/en-us/web/css/font/index.md @@ -9,7 +9,68 @@ browser-compat: css.properties.font The **`font`** CSS [shorthand property](/en-US/docs/Web/CSS/CSS_cascade/Shorthand_properties) sets all the different properties of an element's font. Alternatively, it sets an element's font to a system font. -{{EmbedInteractiveExample("pages/css/font.html")}} +{{InteractiveExample("CSS Demo: font")}} + +```css interactive-example-choice +font: + 1.2rem "Fira Sans", + sans-serif; +``` + +```css interactive-example-choice +font: + italic 1.2rem "Fira Sans", + serif; +``` + +```css interactive-example-choice +font: italic small-caps bold 16px/2 cursive; +``` + +```css interactive-example-choice +font: small-caps bold 24px/1 sans-serif; +``` + +```css interactive-example-choice +font: caption; +``` + +```html interactive-example +<section id="default-example"> + <p id="example-element"> + London. Michaelmas term lately over, and the Lord Chancellor sitting in + Lincoln's Inn Hall. Implacable November weather. As much mud in the streets + as if the waters had but newly retired from the face of the earth, and it + would not be wonderful to meet a Megalosaurus, forty feet long or so, + waddling like an elephantine lizard up Holborn Hill. + </p> +</section> +``` + +```css interactive-example +@font-face { + font-family: "Fira Sans"; + src: + local("FiraSans-Regular"), + url("/shared-assets/fonts/FiraSans-Regular.woff2") format("woff2"); + font-weight: normal; + font-style: normal; +} + +@font-face { + font-family: "Fira Sans"; + src: + local("FiraSans-Italic"), + url("/shared-assets/fonts/FiraSans-Italic.woff2") format("woff2"); + font-weight: normal; + font-style: italic; +} + +section { + margin-top: 10px; + font-size: 1.1em; +} +``` As with any shorthand property, any individual value that is not specified is set to its corresponding initial value (possibly overriding values previously set using non-shorthand properties). Though not directly settable by `font`, the longhands {{cssxref("font-size-adjust")}} and {{cssxref("font-kerning")}} are also reset to their initial values. @@ -462,13 +523,13 @@ function getProperties() { function getCheckedValue(radioName) { const radios = document.forms[0].elements[radioName]; - for (let i = 0; i < radios.length; i++) { - if (radios[i].checked) { + for (const radio of radios) { + if (radio.checked) { const curElemName = `input_${radioName}`; const curElem = document.getElementById(curElemName); - curElem.value = radios[i].value; + curElem.value = radio.value; - return radios[i].value; + return radio.value; } } } diff --git a/files/en-us/web/css/forced-color-adjust/index.md b/files/en-us/web/css/forced-color-adjust/index.md index 88b7203172a5ab8..80d26b8f355ab9f 100644 --- a/files/en-us/web/css/forced-color-adjust/index.md +++ b/files/en-us/web/css/forced-color-adjust/index.md @@ -29,11 +29,11 @@ The `forced-color-adjust` property's value must be one of the following keywords ### Values - `auto` - - : The element's colors are adjusted by the {{Glossary("user agent")}} in forced colors mode. This is the default. + - : The element's colors are adjusted by the {{Glossary("user agent")}} in forced colors mode. This is the default value. - `none` - : The element's colors are not automatically adjusted by the {{Glossary("user agent")}} in forced colors mode. - `preserve-parent-color` - - : In forced colors mode, if the {{cssxref("color")}} property inherits from its parent (i.e. there is no [cascaded value](/en-US/docs/Web/CSS/CSS_cascade/Cascade) or the cascaded value is `currentcolor`, {{cssxref("inherit")}}, or another keyword that inherits from the parent), then it computes to the [used color](/en-US/docs/Web/CSS/CSS_cascade/used_value) of its parent's `color` property. In all other cases, it behaves the same as `none`. + - : In forced colors mode, if the {{cssxref("color")}} property inherits from its parent (i.e., there is no [cascaded value](/en-US/docs/Web/CSS/CSS_cascade/Cascade) or the cascaded value is `currentcolor`, {{cssxref("inherit")}}, or another keyword that inherits from the parent), then it computes to the [used color](/en-US/docs/Web/CSS/CSS_cascade/Value_processing#used_value) of its parent's `color` property. In all other cases, it behaves the same as `none`. ## Usage notes diff --git a/files/en-us/web/css/frequency-percentage/index.md b/files/en-us/web/css/frequency-percentage/index.md index d1f2b6d2c3f3880..0210ee50617c466 100644 --- a/files/en-us/web/css/frequency-percentage/index.md +++ b/files/en-us/web/css/frequency-percentage/index.md @@ -7,7 +7,7 @@ spec-urls: https://drafts.csswg.org/css-values/#typedef-frequency-percentage {{CSSRef}} -The **`<frequency-percentage>`** [CSS](/en-US/docs/Web/CSS) [data type](/en-US/docs/Web/CSS/CSS_Values_and_Units/CSS_data_types) represents a value that can be either a {{Cssxref("frequency")}} or a {{Cssxref("percentage")}}. Frequency values, e.g. the pitch of a speaking voice, are not currently used in any CSS properties. +The **`<frequency-percentage>`** [CSS](/en-US/docs/Web/CSS) [data type](/en-US/docs/Web/CSS/CSS_Values_and_Units/CSS_data_types) represents a value that can be either a {{Cssxref("frequency")}} or a {{Cssxref("percentage")}}. Frequency values, e.g., the pitch of a speaking voice, are not currently used in any CSS properties. ## Syntax diff --git a/files/en-us/web/css/gap/index.md b/files/en-us/web/css/gap/index.md index 786ce813f9b7837..4d5b58466faa2c0 100644 --- a/files/en-us/web/css/gap/index.md +++ b/files/en-us/web/css/gap/index.md @@ -9,7 +9,55 @@ browser-compat: css.properties.gap The **`gap`** [CSS](/en-US/docs/Web/CSS) [shorthand property](/en-US/docs/Web/CSS/CSS_cascade/Shorthand_properties) sets the gaps (also called {{glossary("gutters")}}) between rows and columns. This property applies to [multi-column](/en-US/docs/Web/CSS/CSS_multicol_layout), [flex](/en-US/docs/Web/CSS/CSS_flexible_box_layout), and [grid](/en-US/docs/Web/CSS/CSS_grid_layout) containers. -{{EmbedInteractiveExample("pages/css/gap.html")}} +{{InteractiveExample("CSS Demo: gap")}} + +```css interactive-example-choice +gap: 0; +``` + +```css interactive-example-choice +gap: 10%; +``` + +```css interactive-example-choice +gap: 1em; +``` + +```css interactive-example-choice +gap: 10px 20px; +``` + +```css interactive-example-choice +gap: calc(20px + 10%); +``` + +```html interactive-example +<section class="default-example" id="default-example"> + <div class="example-container"> + <div class="transition-all" id="example-element"> + <div>One</div> + <div>Two</div> + <div>Three</div> + <div>Four</div> + <div>Five</div> + </div> + </div> +</section> +``` + +```css interactive-example +#example-element { + border: 1px solid #c5c5c5; + display: grid; + grid-template-columns: 1fr 1fr; + width: 200px; +} + +#example-element > div { + background-color: rgba(0, 0, 255, 0.2); + border: 3px solid blue; +} +``` ## Constituent properties diff --git a/files/en-us/web/css/gradient/conic-gradient/index.md b/files/en-us/web/css/gradient/conic-gradient/index.md index 2b9dbd477dec05d..2bf3c1cb292ce23 100644 --- a/files/en-us/web/css/gradient/conic-gradient/index.md +++ b/files/en-us/web/css/gradient/conic-gradient/index.md @@ -9,7 +9,49 @@ browser-compat: css.types.gradient.conic-gradient The **`conic-gradient()`** [CSS](/en-US/docs/Web/CSS) [function](/en-US/docs/Web/CSS/CSS_Values_and_Units/CSS_Value_Functions) creates an image consisting of a gradient with color transitions rotated around a center point (rather than radiating from the center). Example conic gradients include pie charts and {{glossary("color wheel", "color wheels")}}. The result of the `conic-gradient()` function is an object of the {{CSSxRef("&lt;gradient&gt;")}} data type, which is a special kind of {{CSSxRef("&lt;image&gt;")}}. -{{EmbedInteractiveExample("pages/css/function-conic-gradient.html")}} +{{InteractiveExample("CSS Demo: conic-gradient()")}} + +```css interactive-example-choice +background: conic-gradient(red, orange, yellow, green, blue); +``` + +```css interactive-example-choice +background: conic-gradient( + from 0.25turn at 50% 30%, + #f69d3c, + 10deg, + #3f87a6, + 350deg, + #ebf8e1 +); +``` + +```css interactive-example-choice +background: conic-gradient(from 3.1416rad at 10% 50%, #e66465, #9198e5); +``` + +```css interactive-example-choice +background: conic-gradient( + red 6deg, + orange 6deg 18deg, + yellow 18deg 45deg, + green 45deg 110deg, + blue 110deg 200deg, + purple 200deg +); +``` + +```html interactive-example +<section class="display-block" id="default-example"> + <div id="example-element"></div> +</section> +``` + +```css interactive-example +#example-element { + min-height: 100%; +} +``` ## Syntax @@ -126,7 +168,7 @@ And, yes, you can mix and match different angle units, but don't. The above is h Browsers do not provide any special information on background images to assistive technology. This is important primarily for screen readers, as a screen reader will not announce its presence and therefore convey nothing to its users. While it is possible to create pie charts, checkerboards, and other effects with conic gradients, CSS images provide no native way to assign alternative text, and therefore the image represented by the conic gradient will not be accessible to screen reader users. If the image contains information critical to understanding the page's overall purpose, it is better to describe it semantically in the document. -- [MDN Understanding WCAG, Guideline 1.1 explanations](/en-US/docs/Web/Accessibility/Understanding_WCAG/Perceivable#guideline_1.1_—_providing_text_alternatives_for_non-text_content) +- [MDN Understanding WCAG, Guideline 1.1 explanations](/en-US/docs/Web/Accessibility/Guides/Understanding_WCAG/Perceivable#guideline_1.1_—_providing_text_alternatives_for_non-text_content) - [Understanding Success Criterion 1.1.1 | W3C Understanding WCAG 2.0](https://www.w3.org/TR/UNDERSTANDING-WCAG20/text-equiv-all.html) ## Examples diff --git a/files/en-us/web/css/gradient/index.md b/files/en-us/web/css/gradient/index.md index d9988e4024145f7..f6b5f9e57022bff 100644 --- a/files/en-us/web/css/gradient/index.md +++ b/files/en-us/web/css/gradient/index.md @@ -9,7 +9,39 @@ browser-compat: css.types.gradient The **`<gradient>`** [CSS](/en-US/docs/Web/CSS) [data type](/en-US/docs/Web/CSS/CSS_Values_and_Units/CSS_data_types) is a special type of {{cssxref("&lt;image&gt;")}} that consists of a progressive transition between two or more colors. -{{EmbedInteractiveExample("pages/css/type-gradient.html")}} +{{InteractiveExample("CSS Demo: &amp;lt;gradient&amp;gt;")}} + +```css interactive-example-choice +background: linear-gradient(#f69d3c, #3f87a6); +``` + +```css interactive-example-choice +background: radial-gradient(#f69d3c, #3f87a6); +``` + +```css interactive-example-choice +background: repeating-linear-gradient(#f69d3c, #3f87a6 50px); +``` + +```css interactive-example-choice +background: repeating-radial-gradient(#f69d3c, #3f87a6 50px); +``` + +```css interactive-example-choice +background: conic-gradient(#f69d3c, #3f87a6); +``` + +```html interactive-example +<section class="display-block" id="default-example"> + <div id="example-element"></div> +</section> +``` + +```css interactive-example +#example-element { + min-height: 100%; +} +``` A CSS gradient has [no intrinsic dimensions](/en-US/docs/Web/CSS/image#description); i.e., it has no natural or preferred size, nor a preferred ratio. Its concrete size will match the size of the element to which it applies. @@ -45,7 +77,7 @@ As with any interpolation involving colors, gradients are calculated in the alph ### Linear gradient example -A simple linear gradient. +A linear gradient. ```html hidden <div class="linear-gradient">Linear gradient</div> @@ -77,7 +109,7 @@ div { ### Radial gradient example -A simple radial gradient. +A radial gradient. ```html hidden <div class="radial-gradient">Radial gradient</div> @@ -100,7 +132,7 @@ div { ### Conic gradient example -A simple conic gradient example. Note that this isn't supported widely across browser as of yet. +A conic gradient example. ```html hidden <div class="conic-gradient">Conic gradient</div> @@ -123,7 +155,7 @@ div { ### Repeating gradient examples -Simple repeating linear and radial gradient examples. +Repeating linear and radial gradient examples. ```html hidden <div class="linear-repeat"></div> diff --git a/files/en-us/web/css/gradient/linear-gradient/index.md b/files/en-us/web/css/gradient/linear-gradient/index.md index 8f001f3fe967077..987699c28ca3477 100644 --- a/files/en-us/web/css/gradient/linear-gradient/index.md +++ b/files/en-us/web/css/gradient/linear-gradient/index.md @@ -9,7 +9,38 @@ browser-compat: css.types.gradient.linear-gradient The **`linear-gradient()`** [CSS](/en-US/docs/Web/CSS) [function](/en-US/docs/Web/CSS/CSS_Values_and_Units/CSS_Value_Functions) creates an image consisting of a progressive transition between two or more colors along a straight line. Its result is an object of the {{CSSxRef("&lt;gradient&gt;")}} data type, which is a special kind of {{CSSxRef("&lt;image&gt;")}}. -{{EmbedInteractiveExample("pages/css/function-linear-gradient.html")}} +{{InteractiveExample("CSS Demo: linear-gradient()")}} + +```css interactive-example-choice +background: linear-gradient(#e66465, #9198e5); +``` + +```css interactive-example-choice +background: linear-gradient(0.25turn, #3f87a6, #ebf8e1, #f69d3c); +``` + +```css interactive-example-choice +background: linear-gradient(to left, #333, #333 50%, #eee 75%, #333 75%); +``` + +```css interactive-example-choice +background: + linear-gradient(217deg, rgba(255, 0, 0, 0.8), rgba(255, 0, 0, 0) 70.71%), + linear-gradient(127deg, rgba(0, 255, 0, 0.8), rgba(0, 255, 0, 0) 70.71%), + linear-gradient(336deg, rgba(0, 0, 255, 0.8), rgba(0, 0, 255, 0) 70.71%); +``` + +```html interactive-example +<section class="display-block" id="default-example"> + <div id="example-element"></div> +</section> +``` + +```css interactive-example +#example-element { + min-height: 100%; +} +``` ## Syntax @@ -68,7 +99,7 @@ linear-gradient(45deg, red 0 50%, blue 50% 100%) - : An {{glossary("interpolation")}} hint defining how the gradient progresses between adjacent color stops. The length defines at which point between two color stops the gradient color should reach the midpoint of the color transition. If omitted, the midpoint of the color transition is the midpoint between two color stops. > [!NOTE] -> Rendering of [color stops in CSS gradients](#composition_of_a_linear_gradient) follows the same rules as color stops in [SVG gradients](/en-US/docs/Web/SVG/Tutorial/Gradients). +> Rendering of [color stops in CSS gradients](#composition_of_a_linear_gradient) follows the same rules as color stops in [SVG gradients](/en-US/docs/Web/SVG/Tutorials/SVG_from_scratch/Gradients). ## Description diff --git a/files/en-us/web/css/gradient/radial-gradient/index.md b/files/en-us/web/css/gradient/radial-gradient/index.md index a9f90817c09d306..3bfa120a885c067 100644 --- a/files/en-us/web/css/gradient/radial-gradient/index.md +++ b/files/en-us/web/css/gradient/radial-gradient/index.md @@ -9,7 +9,37 @@ browser-compat: css.types.gradient.radial-gradient The **`radial-gradient()`** [CSS](/en-US/docs/Web/CSS) [function](/en-US/docs/Web/CSS/CSS_Values_and_Units/CSS_Value_Functions) creates an image consisting of a progressive transition between two or more colors that radiate from an origin. Its shape may be a circle or an ellipse. The function's result is an object of the {{cssxref("&lt;gradient&gt;")}} data type, which is a special kind of {{cssxref("&lt;image&gt;")}}. -{{EmbedInteractiveExample("pages/css/function-radial-gradient.html")}} +{{InteractiveExample("CSS Demo: radial-gradient()")}} + +```css interactive-example-choice +background: radial-gradient(#e66465, #9198e5); +``` + +```css interactive-example-choice +background: radial-gradient(closest-side, #3f87a6, #ebf8e1, #f69d3c); +``` + +```css interactive-example-choice +background: radial-gradient(circle at 100%, #333, #333 50%, #eee 75%, #333 75%); +``` + +```css interactive-example-choice +background: + radial-gradient(ellipse at top, #e66465, transparent), + radial-gradient(ellipse at bottom, #4d9f0c, transparent); +``` + +```html interactive-example +<section class="display-block" id="default-example"> + <div id="example-element"></div> +</section> +``` + +```css interactive-example +#example-element { + min-height: 100%; +} +``` ## Syntax @@ -81,7 +111,7 @@ Color-stop points are positioned on a _virtual gradient ray_ that extends horizo ## Examples -### Simple gradient +### Basic gradient ```html hidden <div class="radial-gradient"></div> @@ -100,7 +130,7 @@ Color-stop points are positioned on a _virtual gradient ray_ that extends horizo } ``` -{{EmbedLiveSample('Simple_gradient', 120, 120)}} +{{EmbedLiveSample('Basic_gradient', 120, 120)}} ### Non-centered gradient diff --git a/files/en-us/web/css/gradient/repeating-conic-gradient/index.md b/files/en-us/web/css/gradient/repeating-conic-gradient/index.md index 5299a1461009de3..f96b2fa39123259 100644 --- a/files/en-us/web/css/gradient/repeating-conic-gradient/index.md +++ b/files/en-us/web/css/gradient/repeating-conic-gradient/index.md @@ -9,7 +9,32 @@ browser-compat: css.types.gradient.repeating-conic-gradient The **`repeating-conic-gradient()`** [CSS](/en-US/docs/Web/CSS) [function](/en-US/docs/Web/CSS/CSS_Values_and_Units/CSS_Value_Functions) creates an image consisting of a repeating gradient (rather than a [single gradient](/en-US/docs/Web/CSS/gradient/conic-gradient)) with color transitions rotated around a center point (rather than [radiating from the center](/en-US/docs/Web/CSS/gradient/repeating-radial-gradient)). -{{EmbedInteractiveExample("pages/css/function-repeating-conic-gradient.html")}} +{{InteractiveExample("CSS Demo: repeating-conic-gradient()")}} + +```css interactive-example-choice +background: repeating-conic-gradient(red 0%, yellow 15%, red 33%); +``` + +```css interactive-example-choice +background: repeating-conic-gradient( + from 45deg at 10% 50%, + brown 0deg 10deg, + darkgoldenrod 10deg 20deg, + chocolate 20deg 30deg +); +``` + +```html interactive-example +<section class="display-block" id="default-example"> + <div id="example-element"></div> +</section> +``` + +```css interactive-example +#example-element { + min-height: 100%; +} +``` ## Syntax @@ -107,7 +132,7 @@ While you can mix and match different angle units, don't. It makes CSS hard to r Browsers do not provide any special information on background images to assistive technology. This is important primarily for screen readers, as a screen reader will not announce its presence and therefore convey nothing to its users. While it is possible to create pie charts, checkerboards, and other effects with conic gradients, CSS images provide no native way to assign alternative text, and therefore the image represented by the conic gradient will not be accessible to screen reader users. If the image contains information critical to understanding the page's overall purpose, it is better to describe it semantically in the document. -- [MDN Understanding WCAG, Guideline 1.1 explanations](/en-US/docs/Web/Accessibility/Understanding_WCAG/Perceivable#guideline_1.1_—_providing_text_alternatives_for_non-text_content) +- [MDN Understanding WCAG, Guideline 1.1 explanations](/en-US/docs/Web/Accessibility/Guides/Understanding_WCAG/Perceivable#guideline_1.1_—_providing_text_alternatives_for_non-text_content) - [Understanding Success Criterion 1.1.1 | W3C Understanding WCAG 2.0](https://www.w3.org/TR/UNDERSTANDING-WCAG20/text-equiv-all.html) ## Examples diff --git a/files/en-us/web/css/gradient/repeating-linear-gradient/index.md b/files/en-us/web/css/gradient/repeating-linear-gradient/index.md index fa2d3bb0d09284e..fa9f546f89ad6e5 100644 --- a/files/en-us/web/css/gradient/repeating-linear-gradient/index.md +++ b/files/en-us/web/css/gradient/repeating-linear-gradient/index.md @@ -9,7 +9,38 @@ browser-compat: css.types.gradient.repeating-linear-gradient The **`repeating-linear-gradient()`** [CSS](/en-US/docs/Web/CSS) [function](/en-US/docs/Web/CSS/CSS_Values_and_Units/CSS_Value_Functions) creates an image consisting of repeating linear gradients. It is similar to {{cssxref("gradient/linear-gradient", "linear-gradient()")}} and takes the same arguments, but it repeats the color stops infinitely in all directions so as to cover its entire container. The function's result is an object of the {{cssxref("&lt;gradient&gt;")}} data type, which is a special kind of {{cssxref("&lt;image&gt;")}}. -{{EmbedInteractiveExample("pages/css/function-repeating-linear-gradient.html")}} +{{InteractiveExample("CSS Demo: repeating-linear-gradient()")}} + +```css interactive-example-choice +background: repeating-linear-gradient( + #e66465, + #e66465 20px, + #9198e5 20px, + #9198e5 25px +); +``` + +```css interactive-example-choice +background: repeating-linear-gradient(45deg, #3f87a6, #ebf8e1 15%, #f69d3c 20%); +``` + +```css interactive-example-choice +background: + repeating-linear-gradient(transparent, #4d9f0c 40px), + repeating-linear-gradient(0.25turn, transparent, #3f87a6 20px); +``` + +```html interactive-example +<section class="display-block" id="default-example"> + <div id="example-element"></div> +</section> +``` + +```css interactive-example +#example-element { + min-height: 100%; +} +``` The length of the gradient that repeats is the distance between the first and last color stop. If the first color does not have a color-stop-length, the color-stop-length defaults to 0. With each repetition, the positions of the color stops are shifted by a multiple of the length of the basic linear gradient. Thus, the position of each ending color stop coincides with a starting color stop; if the color values are different, this will result in a sharp visual transition. This can be altered with repeating the first color again as the last color. diff --git a/files/en-us/web/css/gradient/repeating-radial-gradient/index.md b/files/en-us/web/css/gradient/repeating-radial-gradient/index.md index f6475e00a2c54de..ce95f5812734099 100644 --- a/files/en-us/web/css/gradient/repeating-radial-gradient/index.md +++ b/files/en-us/web/css/gradient/repeating-radial-gradient/index.md @@ -9,7 +9,37 @@ browser-compat: css.types.gradient.repeating-radial-gradient The **`repeating-radial-gradient()`** [CSS](/en-US/docs/Web/CSS) [function](/en-US/docs/Web/CSS/CSS_Values_and_Units/CSS_Value_Functions) creates an image consisting of repeating gradients that radiate from an origin. It is similar to {{cssxref("gradient/radial-gradient", "radial-gradient()")}} and takes the same arguments, but it repeats the color stops infinitely in all directions so as to cover its entire container, similar to {{cssxref("gradient/repeating-linear-gradient", "repeating-linear-gradient()")}}. The function's result is an object of the {{cssxref("&lt;gradient&gt;")}} data type, which is a special kind of {{cssxref("&lt;image&gt;")}}. -{{EmbedInteractiveExample("pages/css/function-repeating-radial-gradient.html")}} +{{InteractiveExample("CSS Demo: repeating-radial-gradient()")}} + +```css interactive-example-choice +background: repeating-radial-gradient(#e66465, #9198e5 20%); +``` + +```css interactive-example-choice +background: repeating-radial-gradient(closest-side, #3f87a6, #ebf8e1, #f69d3c); +``` + +```css interactive-example-choice +background: repeating-radial-gradient( + circle at 100%, + #333, + #333 10px, + #eee 10px, + #eee 20px +); +``` + +```html interactive-example +<section class="display-block" id="default-example"> + <div id="example-element"></div> +</section> +``` + +```css interactive-example +#example-element { + min-height: 100%; +} +``` With each repetition, the positions of the color stops are shifted by a multiple of the dimensions of the basic radial gradient (the distance between the last color stop and the first). Thus, the position of each ending color stop coincides with a starting color stop; if the color values are different, this will result in a sharp visual transition, which can be mitigated by repeating the first color as the last color. diff --git a/files/en-us/web/css/grid-area/index.md b/files/en-us/web/css/grid-area/index.md index bc44d2285827efe..60063fc39140a6b 100644 --- a/files/en-us/web/css/grid-area/index.md +++ b/files/en-us/web/css/grid-area/index.md @@ -9,7 +9,56 @@ browser-compat: css.properties.grid-area The **`grid-area`** CSS [shorthand property](/en-US/docs/Web/CSS/CSS_cascade/Shorthand_properties) specifies a grid item's size and location within a {{glossary("grid", "grid")}} by contributing a line, a span, or nothing (automatic) to its grid placement, thereby specifying the edges of its {{glossary("grid areas", "grid area")}}. -{{EmbedInteractiveExample("pages/css/grid-area.html")}} +{{InteractiveExample("CSS Demo: grid-area")}} + +```css interactive-example-choice +grid-area: a; +``` + +```css interactive-example-choice +grid-area: b; +``` + +```css interactive-example-choice +grid-area: c; +``` + +```css interactive-example-choice +grid-area: 2 / 1 / 2 / 4; +``` + +```html interactive-example +<section class="default-example" id="default-example"> + <div class="example-container"> + <div class="transition-all" id="example-element">Example</div> + </div> +</section> +``` + +```css interactive-example +.example-container { + border: 1px solid #c5c5c5; + display: grid; + grid-template-columns: 1fr 1fr 1fr; + grid-template-rows: repeat(3, minmax(40px, auto)); + grid-template-areas: + "a a a" + "b c c" + "b c c"; + grid-gap: 10px; + width: 200px; +} + +.example-container > div { + background-color: rgba(0, 0, 255, 0.2); + border: 3px solid blue; +} + +#example-element { + background-color: rgba(255, 0, 200, 0.2); + border: 3px solid rebeccapurple; +} +``` If four `<grid-line>` values are specified, `grid-row-start` is set to the first value, `grid-column-start` is set to the second value, `grid-row-end` is set to the third value, and `grid-column-end` is set to the fourth value. diff --git a/files/en-us/web/css/grid-auto-columns/index.md b/files/en-us/web/css/grid-auto-columns/index.md index 572f3be425830d4..6a3347e0b796873 100644 --- a/files/en-us/web/css/grid-auto-columns/index.md +++ b/files/en-us/web/css/grid-auto-columns/index.md @@ -9,7 +9,60 @@ browser-compat: css.properties.grid-auto-columns The **`grid-auto-columns`** [CSS](/en-US/docs/Web/CSS) property specifies the size of an implicitly-created grid column {{glossary("grid tracks", "track")}} or pattern of tracks. -{{EmbedInteractiveExample("pages/css/grid-auto-columns.html")}} +{{InteractiveExample("CSS Demo: grid-auto-columns")}} + +```css interactive-example-choice +grid-auto-columns: auto; +``` + +```css interactive-example-choice +grid-auto-columns: 1fr; +``` + +```css interactive-example-choice +grid-auto-columns: min-content; +``` + +```css interactive-example-choice +grid-auto-columns: minmax(10px, auto); +``` + +```html interactive-example +<section class="default-example" id="default-example"> + <div class="example-container"> + <div class="transition-all" id="example-element"> + <div>One</div> + <div>Two</div> + <div>Three</div> + <div>Four</div> + <div></div> + </div> + </div> +</section> +``` + +```css interactive-example +#example-element { + border: 1px solid #c5c5c5; + display: grid; + grid-auto-rows: 40px; + grid-gap: 10px; + width: 220px; +} + +#example-element > div { + background-color: rgba(0, 0, 255, 0.2); + border: 3px solid blue; +} + +#example-element > div:nth-child(1) { + grid-column: 1 / 3; +} + +#example-element > div:nth-child(2) { + grid-column: 2; +} +``` If a grid item is positioned into a column that is not explicitly sized by {{cssxref("grid-template-columns")}}, implicit {{glossary("grid", "grid")}} tracks are created to hold it. This can happen either by explicitly positioning into a column that is out of range, or by the auto-placement algorithm creating additional columns. @@ -71,7 +124,7 @@ grid-auto-columns: unset; - : Is a non-negative dimension with the unit `fr` specifying the track's flex factor. Each `<flex>`-sized track takes a share of the remaining space in proportion to its flex factor. - When appearing outside a `minmax()` notation, it implies an automatic minimum (i.e. `minmax(auto, <flex>)`). + When appearing outside a `minmax()` notation, it implies an automatic minimum (i.e., `minmax(auto, <flex>)`). - {{cssxref("max-content")}} - : Is a keyword representing the largest maximal content contribution of the grid items occupying the grid track. @@ -80,7 +133,7 @@ grid-auto-columns: unset; - {{cssxref("minmax", "minmax(min, max)")}} - : Is a functional notation that defines a size range greater than or equal to _min_ and less than or equal to _max_. If _max_ is smaller than _min_, then _max_ is ignored and the function is treated as _min_. As a maximum, a `<flex>` value sets the track's flex factor. As a minimum, it is treated as zero (or minimal content, if the grid container is sized under a minimal content constraint). - {{cssxref("fit-content_function", "fit-content( [ &lt;length&gt; | &lt;percentage&gt; ] )")}} - - : Represents the formula `min(max-content, max(auto, argument))`, which is calculated similar to `auto` (i.e. `minmax(auto, max-content)`), except that the track size is clamped at _argument_ if it is greater than the `auto` minimum. + - : Represents the formula `min(max-content, max(auto, argument))`, which is calculated similar to `auto` (i.e., `minmax(auto, max-content)`), except that the track size is clamped at _argument_ if it is greater than the `auto` minimum. - `auto` - : As a maximum represents the largest {{cssxref("max-content")}} size of the items in that track. diff --git a/files/en-us/web/css/grid-auto-flow/index.md b/files/en-us/web/css/grid-auto-flow/index.md index 5f5827471b2469c..4dba5594a4a1328 100644 --- a/files/en-us/web/css/grid-auto-flow/index.md +++ b/files/en-us/web/css/grid-auto-flow/index.md @@ -9,7 +9,57 @@ browser-compat: css.properties.grid-auto-flow The **`grid-auto-flow`** [CSS](/en-US/docs/Web/CSS) property controls how the auto-placement algorithm works, specifying exactly how auto-placed items get flowed into the grid. -{{EmbedInteractiveExample("pages/css/grid-auto-flow.html")}} +{{InteractiveExample("CSS Demo: grid-auto-flow")}} + +```css interactive-example-choice +grid-auto-flow: row; +``` + +```css interactive-example-choice +grid-auto-flow: column; +``` + +```css interactive-example-choice +grid-auto-flow: row dense; +``` + +```html interactive-example +<section class="default-example" id="default-example"> + <div class="example-container"> + <div class="transition-all" id="example-element"> + <div>One</div> + <div>Two</div> + <div>Three</div> + <div>Four</div> + <div>Five</div> + </div> + </div> +</section> +``` + +```css interactive-example +#example-element { + border: 1px solid #c5c5c5; + display: grid; + grid-template-columns: 1fr 1fr 1fr; + grid-template-rows: repeat(3, minmax(40px, auto)); + grid-gap: 10px; + width: 220px; +} + +#example-element > div { + background-color: rgba(0, 0, 255, 0.2); + border: 3px solid blue; +} + +#example-element > div:nth-child(1) { + grid-column: auto / span 2; +} + +#example-element > div:nth-child(2) { + grid-column: auto / span 2; +} +``` > [!NOTE] > The `masonry-auto-flow` property was dropped from CSS [Masonry layout](/en-US/docs/Web/CSS/CSS_grid_layout/Masonry_layout) in favor of `grid-auto-flow`. diff --git a/files/en-us/web/css/grid-auto-rows/index.md b/files/en-us/web/css/grid-auto-rows/index.md index 72622f77493cb8b..e0f01b542517229 100644 --- a/files/en-us/web/css/grid-auto-rows/index.md +++ b/files/en-us/web/css/grid-auto-rows/index.md @@ -9,7 +9,58 @@ browser-compat: css.properties.grid-auto-rows The **`grid-auto-rows`** [CSS](/en-US/docs/Web/CSS) property specifies the size of an implicitly-created grid row {{glossary("grid tracks", "track")}} or pattern of tracks. -{{EmbedInteractiveExample("pages/css/grid-auto-rows.html")}} +{{InteractiveExample("CSS Demo: grid-auto-rows")}} + +```css interactive-example-choice +grid-auto-rows: auto; +``` + +```css interactive-example-choice +grid-auto-rows: 50px; +``` + +```css interactive-example-choice +grid-auto-rows: min-content; +``` + +```css interactive-example-choice +grid-auto-rows: minmax(30px, auto); +``` + +```html interactive-example +<section class="default-example" id="default-example"> + <div class="example-container"> + <div class="transition-all" id="example-element"> + <div>One</div> + <div>Two</div> + <div>Three</div> + <div>Four</div> + <div>Five</div> + </div> + </div> +</section> +``` + +```css interactive-example +#example-element { + border: 1px solid #c5c5c5; + display: grid; + grid-template-columns: 1fr 1fr; + grid-auto-rows: 40px; + grid-gap: 10px; + width: 220px; +} + +#example-element > div { + background-color: rgba(0, 0, 255, 0.2); + border: 3px solid blue; + font-size: 22px; +} + +#example-element div:last-child { + font-size: 13px; +} +``` If a grid item is positioned into a row that is not explicitly sized by {{cssxref("grid-template-rows")}}, implicit {{glossary("grid", "grid")}} tracks are created to hold it. This can happen either by explicitly positioning into a row that is out of range, or by the auto-placement algorithm creating additional rows. @@ -70,7 +121,7 @@ grid-auto-rows: unset; - : Is a non-negative dimension with the unit `fr` specifying the track's flex factor. Each `<flex>`-sized track takes a share of the remaining space in proportion to its flex factor. - When appearing outside a `minmax()` notation, it implies an automatic minimum (i.e. `minmax(auto, <flex>)`). + When appearing outside a `minmax()` notation, it implies an automatic minimum (i.e., `minmax(auto, <flex>)`). - {{cssxref("max-content")}} - : Is a keyword representing the largest maximal content contribution of the grid items occupying the grid track. @@ -79,7 +130,7 @@ grid-auto-rows: unset; - {{cssxref("minmax", "minmax(min, max)")}} - : Is a functional notation that defines a size range greater than or equal to _min_ and less than or equal to _max_. If _max_ is smaller than _min_, then _max_ is ignored and the function is treated as _min_. As a maximum, a `<flex>` value sets the track's flex factor. As a minimum, it is treated as zero (or minimal content, if the grid container is sized under a minimal content constraint). - {{cssxref("fit-content_function", "fit-content( [ &lt;length&gt; | &lt;percentage&gt; ] )")}} - - : Represents the formula `min(max-content, max(auto, argument))`, which is calculated similar to `auto` (i.e. `minmax(auto, max-content)`), except that the track size is clamped at _argument_ if it is greater than the `auto` minimum. + - : Represents the formula `min(max-content, max(auto, argument))`, which is calculated similar to `auto` (i.e., `minmax(auto, max-content)`), except that the track size is clamped at _argument_ if it is greater than the `auto` minimum. - `auto` - : As a maximum represents the largest {{cssxref("max-content")}} size of the items in that track. diff --git a/files/en-us/web/css/grid-column-end/index.md b/files/en-us/web/css/grid-column-end/index.md index af19c2d887afb4d..3c284afb07e5963 100644 --- a/files/en-us/web/css/grid-column-end/index.md +++ b/files/en-us/web/css/grid-column-end/index.md @@ -9,7 +9,54 @@ browser-compat: css.properties.grid-column-end The **`grid-column-end`** [CSS](/en-US/docs/Web/CSS) property specifies a grid item's end position within the grid column by contributing a line, a span, or nothing (automatic) to its grid placement, thereby specifying the block-end edge of its {{glossary("grid areas", "grid area")}}. -{{EmbedInteractiveExample("pages/css/grid-column-end.html")}} +{{InteractiveExample("CSS Demo: grid-column-end")}} + +```css interactive-example-choice +grid-column-end: auto; +``` + +```css interactive-example-choice +grid-column-end: 3; +``` + +```css interactive-example-choice +grid-column-end: -1; +``` + +```css interactive-example-choice +grid-column-end: span 3; +``` + +```html interactive-example +<section class="default-example" id="default-example"> + <div class="example-container"> + <div class="transition-all" id="example-element">One</div> + <div>Two</div> + <div>Three</div> + </div> +</section> +``` + +```css interactive-example +.example-container { + border: 1px solid #c5c5c5; + display: grid; + grid-template-columns: 1fr 1.5fr 1fr; + grid-template-rows: repeat(3, minmax(40px, auto)); + grid-gap: 10px; + width: 200px; +} + +.example-container > div { + background-color: rgba(0, 0, 255, 0.2); + border: 3px solid blue; +} + +#example-element { + background-color: rgba(255, 0, 200, 0.2); + border: 3px solid rebeccapurple; +} +``` ## Syntax @@ -40,10 +87,10 @@ grid-column-end: unset; ### Values - `auto` - - : Is a keyword indicating that the property contributes nothing to the grid item's placement, indicating auto-placement, an automatic span, or a default span of `1`. + - : Contributes nothing to the grid item's placement, indicating auto-placement, an automatic span, or a default span of `1`. This is the default value. - `<custom-ident>` - - : If there is a named line with the name '\<custom-ident>-end', it contributes the first such line to the grid item's placement. + - : Contributes the first line to the grid item's placement if there is a named line with the name `<custom-ident>-end`. > [!NOTE] > Named grid areas automatically generate implicit named lines of this form, so specifying `grid-column-end: foo;` will choose the end edge of that named grid area (unless another line named `foo-end` was explicitly specified before it). @@ -66,7 +113,7 @@ grid-column-end: unset; If the \<integer> is omitted, it defaults to `1`. Negative integers or 0 are invalid. - The `<custom-ident>` cannot take the `span` value. + The `<custom-ident>` cannot take the `span` and `auto` values. ## Formal definition diff --git a/files/en-us/web/css/grid-column-start/index.md b/files/en-us/web/css/grid-column-start/index.md index 5361d0804970ef5..193f856c4b381b2 100644 --- a/files/en-us/web/css/grid-column-start/index.md +++ b/files/en-us/web/css/grid-column-start/index.md @@ -9,7 +9,54 @@ browser-compat: css.properties.grid-column-start The **`grid-column-start`** [CSS](/en-US/docs/Web/CSS) property specifies a grid item's start position within the grid column by contributing a line, a span, or nothing (automatic) to its grid placement. This start position defines the block-start edge of the {{glossary("grid areas", "grid area")}}. -{{EmbedInteractiveExample("pages/css/grid-column-start.html")}} +{{InteractiveExample("CSS Demo: grid-column-start")}} + +```css interactive-example-choice +grid-column-start: auto; +``` + +```css interactive-example-choice +grid-column-start: 2; +``` + +```css interactive-example-choice +grid-column-start: -1; +``` + +```css interactive-example-choice +grid-column-start: span 2; +``` + +```html interactive-example +<section class="default-example" id="default-example"> + <div class="example-container"> + <div class="transition-all" id="example-element">One</div> + <div>Two</div> + <div>Three</div> + </div> +</section> +``` + +```css interactive-example +.example-container { + border: 1px solid #c5c5c5; + display: grid; + grid-template-columns: 1fr 1.5fr 1fr; + grid-template-rows: repeat(3, minmax(40px, auto)); + grid-gap: 10px; + width: 200px; +} + +.example-container > div { + background-color: rgba(0, 0, 255, 0.2); + border: 3px solid blue; +} + +#example-element { + background-color: rgba(255, 0, 200, 0.2); + border: 3px solid rebeccapurple; +} +``` ## Syntax @@ -74,7 +121,7 @@ This property is specified as a single `<grid-line>` value. A `<grid-line>` valu If the \<integer> is omitted, it defaults to `1`. Negative integers and `0` are invalid. - The `<custom-ident>` cannot take the `span` value. + The `<custom-ident>` cannot take the `span` and `auto` values. ## Formal definition diff --git a/files/en-us/web/css/grid-column/index.md b/files/en-us/web/css/grid-column/index.md index f4ed4bfa4a53eac..01db6da84c1f3ec 100644 --- a/files/en-us/web/css/grid-column/index.md +++ b/files/en-us/web/css/grid-column/index.md @@ -9,7 +9,54 @@ browser-compat: css.properties.grid-column The **`grid-column`** CSS [shorthand property](/en-US/docs/Web/CSS/CSS_cascade/Shorthand_properties) specifies a grid item's size and location within a {{glossary("grid column")}} by contributing a line, a span, or nothing (automatic) to its grid placement, thereby specifying the inline-start and inline-end edge of its {{glossary("grid areas", "grid area")}}. -{{EmbedInteractiveExample("pages/css/grid-column.html")}} +{{InteractiveExample("CSS Demo: grid-column")}} + +```css interactive-example-choice +grid-column: 1; +``` + +```css interactive-example-choice +grid-column: 1 / 3; +``` + +```css interactive-example-choice +grid-column: 2 / -1; +``` + +```css interactive-example-choice +grid-column: 1 / span 2; +``` + +```html interactive-example +<section class="default-example" id="default-example"> + <div class="example-container"> + <div class="transition-all" id="example-element">One</div> + <div>Two</div> + <div>Three</div> + </div> +</section> +``` + +```css interactive-example +.example-container { + border: 1px solid #c5c5c5; + display: grid; + grid-template-columns: 1fr 1.5fr 1fr; + grid-template-rows: repeat(3, minmax(40px, auto)); + grid-gap: 10px; + width: 200px; +} + +.example-container > div { + background-color: rgba(0, 0, 255, 0.2); + border: 3px solid blue; +} + +#example-element { + background-color: rgba(255, 0, 200, 0.2); + border: 3px solid rebeccapurple; +} +``` ## Constituent properties diff --git a/files/en-us/web/css/grid-row-end/index.md b/files/en-us/web/css/grid-row-end/index.md index b6e0d1f7100c0ad..f83c35d843a8992 100644 --- a/files/en-us/web/css/grid-row-end/index.md +++ b/files/en-us/web/css/grid-row-end/index.md @@ -9,7 +9,54 @@ browser-compat: css.properties.grid-row-end The **`grid-row-end`** [CSS](/en-US/docs/Web/CSS) property specifies a grid item's end position within the grid row by contributing a line, a span, or nothing (automatic) to its grid placement, thereby specifying the inline-end edge of its {{glossary("grid areas", "grid area")}}. -{{EmbedInteractiveExample("pages/css/grid-row-end.html")}} +{{InteractiveExample("CSS Demo: grid-row-end")}} + +```css interactive-example-choice +grid-row-end: auto; +``` + +```css interactive-example-choice +grid-row-end: 3; +``` + +```css interactive-example-choice +grid-row-end: -1; +``` + +```css interactive-example-choice +grid-row-end: span 3; +``` + +```html interactive-example +<section class="default-example" id="default-example"> + <div class="example-container"> + <div class="transition-all" id="example-element">One</div> + <div>Two</div> + <div>Three</div> + </div> +</section> +``` + +```css interactive-example +.example-container { + border: 1px solid #c5c5c5; + display: grid; + grid-template-columns: 1fr 1.5fr 1fr; + grid-template-rows: repeat(3, minmax(40px, auto)); + grid-gap: 10px; + width: 200px; +} + +.example-container > div { + background-color: rgba(0, 0, 255, 0.2); + border: 3px solid blue; +} + +#example-element { + background-color: rgba(255, 0, 200, 0.2); + border: 3px solid rebeccapurple; +} +``` ## Syntax @@ -50,7 +97,7 @@ grid-row-end: unset; Otherwise, this is treated as if the integer `1` had been specified along with the `<custom-ident>`. - The `<custom-ident>` cannot take the `span` value. + The `<custom-ident>` cannot take the `span` and `auto` values. - `<integer> && <custom-ident>?` diff --git a/files/en-us/web/css/grid-row-start/index.md b/files/en-us/web/css/grid-row-start/index.md index 6ce9adfa81fd450..8cc9a2886750ed2 100644 --- a/files/en-us/web/css/grid-row-start/index.md +++ b/files/en-us/web/css/grid-row-start/index.md @@ -9,7 +9,54 @@ browser-compat: css.properties.grid-row-start The **`grid-row-start`** [CSS](/en-US/docs/Web/CSS) property specifies a grid item's start position within the grid row by contributing a line, a span, or nothing (automatic) to its grid placement, thereby specifying the inline-start edge of its {{glossary("grid areas", "grid area")}}. -{{EmbedInteractiveExample("pages/css/grid-row-start.html")}} +{{InteractiveExample("CSS Demo: grid-row-start")}} + +```css interactive-example-choice +grid-row-start: auto; +``` + +```css interactive-example-choice +grid-row-start: 3; +``` + +```css interactive-example-choice +grid-row-start: -1; +``` + +```css interactive-example-choice +grid-row-start: span 2; +``` + +```html interactive-example +<section class="default-example" id="default-example"> + <div class="example-container"> + <div class="transition-all" id="example-element">One</div> + <div>Two</div> + <div>Three</div> + </div> +</section> +``` + +```css interactive-example +.example-container { + border: 1px solid #c5c5c5; + display: grid; + grid-template-columns: 1fr 1.5fr 1fr; + grid-template-rows: repeat(3, minmax(40px, auto)); + grid-gap: 10px; + width: 200px; +} + +.example-container > div { + background-color: rgba(0, 0, 255, 0.2); + border: 3px solid blue; +} + +#example-element { + background-color: rgba(255, 0, 200, 0.2); + border: 3px solid rebeccapurple; +} +``` ## Syntax @@ -74,7 +121,7 @@ This property is specified as a single `<grid-line>` value. A `<grid-line>` valu If the \<integer> is omitted, it defaults to `1`. Negative integers or 0 are invalid. - The `<custom-ident>` cannot take the `span` value. + The `<custom-ident>` cannot take the `span` and `auto` values. ## Formal definition diff --git a/files/en-us/web/css/grid-row/index.md b/files/en-us/web/css/grid-row/index.md index 4ca98708aa49383..080d43f3ceb1fa6 100644 --- a/files/en-us/web/css/grid-row/index.md +++ b/files/en-us/web/css/grid-row/index.md @@ -9,7 +9,54 @@ browser-compat: css.properties.grid-row The **`grid-row`** CSS [shorthand property](/en-US/docs/Web/CSS/CSS_cascade/Shorthand_properties) specifies a grid item's size and location within a {{glossary("grid row")}} by contributing a line, a span, or nothing (automatic) to its grid placement, thereby specifying the inline-start and inline-end edge of its {{glossary("grid areas", "grid area")}}. -{{EmbedInteractiveExample("pages/css/grid-row.html")}} +{{InteractiveExample("CSS Demo: grid-row")}} + +```css interactive-example-choice +grid-row: 1; +``` + +```css interactive-example-choice +grid-row: 1 / 3; +``` + +```css interactive-example-choice +grid-row: 2 / -1; +``` + +```css interactive-example-choice +grid-row: 1 / span 2; +``` + +```html interactive-example +<section class="default-example" id="default-example"> + <div class="example-container"> + <div class="transition-all" id="example-element">One</div> + <div>Two</div> + <div>Three</div> + </div> +</section> +``` + +```css interactive-example +.example-container { + border: 1px solid #c5c5c5; + display: grid; + grid-template-columns: 1fr 1.5fr 1fr; + grid-template-rows: repeat(3, minmax(40px, auto)); + grid-gap: 10px; + width: 200px; +} + +.example-container > div { + background-color: rgba(0, 0, 255, 0.2); + border: 3px solid blue; +} + +#example-element { + background-color: rgba(255, 0, 200, 0.2); + border: 3px solid rebeccapurple; +} +``` ## Constituent properties diff --git a/files/en-us/web/css/grid-template-areas/index.md b/files/en-us/web/css/grid-template-areas/index.md index 737177a6e91d2ee..de330d02dae7703 100644 --- a/files/en-us/web/css/grid-template-areas/index.md +++ b/files/en-us/web/css/grid-template-areas/index.md @@ -9,7 +9,69 @@ browser-compat: css.properties.grid-template-areas The **`grid-template-areas`** [CSS](/en-US/docs/Web/CSS) property specifies named {{glossary("grid areas")}}, establishing the cells in the grid and assigning them names. -{{EmbedInteractiveExample("pages/css/grid-template-areas.html")}} +{{InteractiveExample("CSS Demo: grid-template-areas")}} + +```css interactive-example-choice +grid-template-areas: + "a a a" + "b c c" + "b c c"; +``` + +```css interactive-example-choice +grid-template-areas: + "b b a" + "b b c" + "b b c"; +``` + +```css interactive-example-choice +grid-template-areas: + "a a ." + "a a ." + ". b c"; +``` + +```html interactive-example +<section class="default-example" id="default-example"> + <div class="example-container"> + <div class="transition-all" id="example-element"> + <div>One (a)</div> + <div>Two (b)</div> + <div>Three (c)</div> + </div> + </div> +</section> +``` + +```css interactive-example +#example-element { + border: 1px solid #c5c5c5; + display: grid; + grid-template-columns: 1fr 1fr 1fr; + grid-template-rows: repeat(3, minmax(40px, auto)); + grid-gap: 10px; + width: 200px; +} + +#example-element :nth-child(1) { + background-color: rgba(0, 0, 255, 0.2); + border: 3px solid blue; + grid-area: a; +} + +#example-element :nth-child(2) { + background-color: rgba(255, 0, 200, 0.2); + border: 3px solid rebeccapurple; + grid-area: b; +} + +#example-element :nth-child(3) { + background-color: rgba(94, 255, 0, 0.2); + border: 3px solid green; + grid-area: c; +} +``` Those areas are not associated with any particular grid item, but can be referenced from the grid-placement properties {{cssxref("grid-row-start")}}, {{cssxref("grid-row-end")}}, {{cssxref("grid-column-start")}}, {{cssxref("grid-column-end")}}, and their shorthands {{cssxref("grid-row")}}, {{cssxref("grid-column")}}, and {{cssxref("grid-area")}}. @@ -37,11 +99,11 @@ grid-template-areas: unset; - `none` - : The grid container doesn't define any named grid areas. -- `{{cssxref("&lt;string&gt;")}}+` +- {{cssxref("&lt;string&gt;")}} - : A row is created for every separate string listed, and a column is created for each cell in the string. Multiple cell tokens with the same name within and between rows create a single named grid area that spans the corresponding grid cells. Unless those cells form a rectangle, the declaration is invalid. - All the remaining unnamed areas in a grid can be referred using _null cell tokens_. A null cell token is a sequence of one or more `.` (U+002E FULL STOP) characters, e.g. `.`, `...`, or `.....` etc. A null cell token can be used to create empty spaces in the grid. + All the remaining unnamed areas in a grid can be referred using _null cell tokens_. A null cell token is a sequence of one or more `.` (U+002E FULL STOP) characters, e.g., `.`, `...`, or `.....` etc. A null cell token can be used to create empty spaces in the grid. ## Formal definition diff --git a/files/en-us/web/css/grid-template-columns/index.md b/files/en-us/web/css/grid-template-columns/index.md index e6eee9cce0c3ee4..57e9a133a0a1a07 100644 --- a/files/en-us/web/css/grid-template-columns/index.md +++ b/files/en-us/web/css/grid-template-columns/index.md @@ -9,7 +9,52 @@ browser-compat: css.properties.grid-template-columns The **`grid-template-columns`** [CSS](/en-US/docs/Web/CSS) property defines the line names and track sizing functions of the {{glossary("grid column", "grid columns")}}. -{{EmbedInteractiveExample("pages/css/grid-template-columns.html")}} +{{InteractiveExample("CSS Demo: grid-template-columns")}} + +```css interactive-example-choice +grid-template-columns: 60px 60px; +``` + +```css interactive-example-choice +grid-template-columns: 1fr 60px; +``` + +```css interactive-example-choice +grid-template-columns: 1fr 2fr; +``` + +```css interactive-example-choice +grid-template-columns: 8ch auto; +``` + +```html interactive-example +<section class="default-example" id="default-example"> + <div class="example-container"> + <div class="transition-all" id="example-element"> + <div>One</div> + <div>Two</div> + <div>Three</div> + <div>Four</div> + <div>Five</div> + </div> + </div> +</section> +``` + +```css interactive-example +#example-element { + border: 1px solid #c5c5c5; + display: grid; + grid-auto-rows: 40px; + grid-gap: 10px; + width: 200px; +} + +#example-element > div { + background-color: rgba(0, 0, 255, 0.2); + border: 3px solid blue; +} +``` ## Syntax @@ -63,7 +108,7 @@ grid-template-columns: unset; - : Is a non-negative dimension with the unit `fr` specifying the track's flex factor. Each `<flex>`-sized track takes a share of the remaining space in proportion to its flex factor. - When appearing outside a `minmax()` notation, it implies an automatic minimum (i.e. `minmax(auto, <flex>)`). + When appearing outside a `minmax()` notation, it implies an automatic minimum (i.e., `minmax(auto, <flex>)`). - {{cssxref("max-content")}} - : Is a keyword representing the largest [maximal content contribution](https://www.w3.org/TR/css-sizing-3/#max-content) of the grid items occupying the grid track. For example, if the first element of the grid track contains the sentence _"Repetitio est mater studiorum"_ and the second element contains the sentence _"Dum spiro, spero"_, maximal content contribution will be defined by the size of the largest sentence among all of the grid elements - _"Repetitio est mater studiorum"_. @@ -81,7 +126,7 @@ grid-template-columns: unset; > **Note:** `auto` track sizes (and only `auto` track sizes) can be stretched by the {{cssxref("align-content")}} and {{cssxref("justify-content")}} properties. Therefore by default, an `auto` sized track will take up any remaining space in the grid container. -- `{{cssxref("fit-content_function", "fit-content( [ &lt;length&gt; | &lt;percentage&gt; ] )")}}` +- {{cssxref("fit-content_function", "fit-content( [ &lt;length&gt; | &lt;percentage&gt; ] )")}} - : Represents the formula `max(minimum, min(limit, max-content))`, where _minimum_ represents an `auto` minimum (which is often, but not always, equal to a {{cssxref("min-content")}} minimum), and _limit_ is the track sizing function passed as an argument to fit-content(). This is essentially calculated as the smaller of `minmax(auto, max-content)` and `minmax(auto, limit)`. - {{cssxref("repeat", "repeat( [ &lt;positive-integer&gt; | auto-fill | auto-fit ] , &lt;track-list&gt; )")}} - : Represents a repeated fragment of the track list, allowing a large number of columns that exhibit a recurring pattern to be written in a more compact form. diff --git a/files/en-us/web/css/grid-template-rows/index.md b/files/en-us/web/css/grid-template-rows/index.md index a5caaefa6168125..8891b677f5ab134 100644 --- a/files/en-us/web/css/grid-template-rows/index.md +++ b/files/en-us/web/css/grid-template-rows/index.md @@ -9,7 +9,52 @@ browser-compat: css.properties.grid-template-rows The **`grid-template-rows`** [CSS](/en-US/docs/Web/CSS) property defines the line names and track sizing functions of the {{glossary("grid_row", "grid rows")}}. -{{EmbedInteractiveExample("pages/css/grid-template-rows.html")}} +{{InteractiveExample("CSS Demo: grid-template-rows")}} + +```css interactive-example-choice +grid-template-rows: auto; +``` + +```css interactive-example-choice +grid-template-rows: 40px 4em 40px; +``` + +```css interactive-example-choice +grid-template-rows: 1fr 2fr 1fr; +``` + +```css interactive-example-choice +grid-template-rows: 3ch auto minmax(10px, 60px); +``` + +```html interactive-example +<section class="default-example" id="default-example"> + <div class="example-container"> + <div class="transition-all" id="example-element"> + <div>One</div> + <div>Two</div> + <div>Three</div> + <div>Four</div> + <div>Five</div> + </div> + </div> +</section> +``` + +```css interactive-example +#example-element { + border: 1px solid #c5c5c5; + display: grid; + grid-template-columns: 1fr 1fr; + grid-gap: 10px; + width: 200px; +} + +#example-element > div { + background-color: rgba(0, 0, 255, 0.2); + border: 3px solid blue; +} +``` ## Syntax @@ -65,7 +110,7 @@ This property may be specified as: - {{cssxref("&lt;percentage&gt;")}} - : Is a non-negative {{cssxref("percentage", "&lt;percentage&gt;")}} value, relative to the block size of the grid container. If the size of the grid container depends on the size of its tracks, then the percentage must be treated as `auto` for the purpose of calculating the intrinsic size of the grid container. It must then be resolved against the resulting grid container size for the purpose of laying out the grid and its items. The intrinsic size contributions of the track may be adjusted to the size of the grid container and may increase the final size of the track by the minimum amount that would result in honoring the percentage. - {{cssxref("&lt;flex_value&gt;","&lt;flex&gt;")}} - - : Is a non-negative dimension with the unit `fr` specifying the track's flex factor. Each `<flex>`-sized track takes a share of the remaining space in proportion to its flex factor. When appearing outside a `minmax()` notation, it implies an automatic minimum (i.e. `minmax(auto, <flex>)`). + - : Is a non-negative dimension with the unit `fr` specifying the track's flex factor. Each `<flex>`-sized track takes a share of the remaining space in proportion to its flex factor. When appearing outside a `minmax()` notation, it implies an automatic minimum (i.e., `minmax(auto, <flex>)`). - {{cssxref("max-content")}} - : Is a keyword representing the largest maximal content contribution of the grid items occupying the grid track. - {{cssxref("min-content")}} @@ -83,7 +128,7 @@ This property may be specified as: > **Note:** `auto` track sizes (and only `auto` track sizes) can be stretched by the {{cssxref("align-content")}} and {{cssxref("justify-content")}} properties. Therefore by default, an `auto` sized track will take up any remaining space in the grid container. - {{cssxref("fit-content_function", "fit-content( [ &lt;length&gt; | &lt;percentage&gt; ] )")}} - - : Represents the formula `min(max-content, max(auto, argument))`, which is calculated similar to `auto` (i.e. `minmax(auto, max-content)`), except that the track size is clamped at _argument_ if it is greater than the `auto` minimum. + - : Represents the formula `min(max-content, max(auto, argument))`, which is calculated similar to `auto` (i.e., `minmax(auto, max-content)`), except that the track size is clamped at _argument_ if it is greater than the `auto` minimum. - {{cssxref("repeat", "repeat( [ &lt;positive-integer&gt; | auto-fill | auto-fit ] , &lt;track-list&gt; )")}} - : Represents a repeated fragment of the track list, allowing a large number of rows that exhibit a recurring pattern to be written in a more compact form. - [`masonry`](/en-US/docs/Web/CSS/CSS_grid_layout/Masonry_layout) diff --git a/files/en-us/web/css/grid-template/index.md b/files/en-us/web/css/grid-template/index.md index f33f92c444554b6..afcbf8543d6c295 100644 --- a/files/en-us/web/css/grid-template/index.md +++ b/files/en-us/web/css/grid-template/index.md @@ -9,7 +9,67 @@ browser-compat: css.properties.grid-template The **`grid-template`** [CSS](/en-US/docs/Web/CSS) property is a [shorthand property](/en-US/docs/Web/CSS/CSS_cascade/Shorthand_properties) for defining {{glossary("grid column", "grid columns")}}, {{glossary("grid_row", "grid rows")}}, and {{glossary("grid areas", "grid areas")}}. -{{EmbedInteractiveExample("pages/css/grid-template.html")}} +{{InteractiveExample("CSS Demo: grid-template")}} + +```css interactive-example-choice +grid-template: + "a a a" 40px + "b c c" 40px + "b c c" 40px / 1fr 1fr 1fr; +``` + +```css interactive-example-choice +grid-template: + "b b a" auto + "b b c" 2ch + "b b c" 1em / 20% 20px 1fr; +``` + +```css interactive-example-choice +grid-template: + "a a ." minmax(50px, auto) + "a a ." 80px + "b b c" auto / 2em 3em auto; +``` + +```html interactive-example +<section class="default-example" id="default-example"> + <div class="example-container"> + <div class="transition-all" id="example-element"> + <div>One</div> + <div>Two</div> + <div>Three</div> + </div> + </div> +</section> +``` + +```css interactive-example +#example-element { + border: 1px solid #c5c5c5; + display: grid; + grid-gap: 10px; + width: 200px; +} + +#example-element :nth-child(1) { + background-color: rgba(0, 0, 255, 0.2); + border: 3px solid blue; + grid-area: a; +} + +#example-element :nth-child(2) { + background-color: rgba(255, 0, 200, 0.2); + border: 3px solid rebeccapurple; + grid-area: b; +} + +#example-element :nth-child(3) { + background-color: rgba(94, 255, 0, 0.2); + border: 3px solid green; + grid-area: c; +} +``` ## Constituent properties @@ -54,7 +114,7 @@ grid-template: unset; ### Values - `none` - - : Is a keyword that sets all three longhand properties to `none`, meaning there is no explicit grid. There are no named grid areas. Rows and columns will be implicitly generated; their size will be determined by the {{cssxref("grid-auto-rows")}} and {{cssxref("grid-auto-columns")}} properties. + - : Sets all three longhand properties to `none`, meaning there is no explicit grid. There are no named grid areas. Rows and columns will be implicitly generated; their size will be determined by the {{cssxref("grid-auto-rows")}} and {{cssxref("grid-auto-columns")}} properties. This is the default value. - `<'grid-template-rows'> / <'grid-template-columns'>` - : Sets {{cssxref("grid-template-rows")}} and {{cssxref("grid-template-columns")}} to the specified values, and sets {{cssxref("grid-template-areas")}} to `none`. - `[ <line-names>? <string> <track-size>? <line-names>? ]+ [ / <explicit-track-list> ]?` diff --git a/files/en-us/web/css/grid/index.md b/files/en-us/web/css/grid/index.md index e4e41b06a57da3c..ff38e466e15a592 100644 --- a/files/en-us/web/css/grid/index.md +++ b/files/en-us/web/css/grid/index.md @@ -11,7 +11,58 @@ The **`grid`** [CSS](/en-US/docs/Web/CSS) property is a [shorthand property](/en Using `grid` you specify one axis using {{cssxref("grid-template-rows")}} or {{cssxref("grid-template-columns")}}, you then specify how content should auto-repeat in the other axis using the implicit grid properties: {{cssxref("grid-auto-rows")}}, {{cssxref("grid-auto-columns")}}, and {{cssxref("grid-auto-flow")}}. -{{EmbedInteractiveExample("pages/css/grid.html")}} +{{InteractiveExample("CSS Demo: grid")}} + +```css interactive-example-choice +grid: auto-flow / 1fr 1fr 1fr; +``` + +```css interactive-example-choice +grid: auto-flow dense / 40px 40px 1fr; +``` + +```css interactive-example-choice +grid: repeat(3, 80px) / auto-flow; +``` + +```html interactive-example +<section class="default-example" id="default-example"> + <div class="example-container"> + <div class="transition-all" id="example-element"> + <div>One</div> + <div>Two</div> + <div>Three</div> + </div> + </div> +</section> +``` + +```css interactive-example +#example-element { + border: 1px solid #c5c5c5; + display: grid; + grid-gap: 10px; + width: 200px; +} + +#example-element :nth-child(1) { + background-color: rgba(0, 0, 255, 0.2); + border: 3px solid blue; +} + +#example-element :nth-child(2) { + background-color: rgba(255, 0, 200, 0.2); + border: 3px solid rebeccapurple; + grid-column: auto / span 3; + grid-row: auto / span 2; +} + +#example-element :nth-child(3) { + background-color: rgba(94, 255, 0, 0.2); + border: 3px solid green; + grid-column: auto / span 2; +} +``` > [!NOTE] > The sub-properties you don't specify are set to their initial value, as normal for shorthands. Also, the gutter properties are NOT reset by this shorthand. diff --git a/files/en-us/web/css/height/index.md b/files/en-us/web/css/height/index.md index 0e62db6575e22f0..6a6285d1a3cb49b 100644 --- a/files/en-us/web/css/height/index.md +++ b/files/en-us/web/css/height/index.md @@ -9,7 +9,41 @@ browser-compat: css.properties.height The **`height`** [CSS](/en-US/docs/Web/CSS) property specifies the height of an element. By default, the property defines the height of the [content area](/en-US/docs/Web/CSS/CSS_box_model/Introduction_to_the_CSS_box_model#content_area). If {{cssxref("box-sizing")}} is set to `border-box`, however, it instead determines the height of the [border area](/en-US/docs/Web/CSS/CSS_box_model/Introduction_to_the_CSS_box_model#border_area). -{{EmbedInteractiveExample("pages/css/height.html")}} +{{InteractiveExample("CSS Demo: height")}} + +```css interactive-example-choice +height: 150px; +``` + +```css interactive-example-choice +height: 6em; +``` + +```css interactive-example-choice +height: 75%; +``` + +```css interactive-example-choice +height: auto; +``` + +```html interactive-example +<section class="default-example" id="default-example"> + <div class="transition-all" id="example-element"> + This is a box where you can change the height. + </div> +</section> +``` + +```css interactive-example +#example-element { + display: flex; + flex-direction: column; + background-color: #5b6dcd; + justify-content: center; + color: #ffffff; +} +``` The {{cssxref("min-height")}} and {{cssxref("max-height")}} properties override `height`. @@ -59,21 +93,17 @@ height: unset; - `min-content` - : The intrinsic minimum height. - `fit-content` - - : Use the available space, but not more than [max-content](/en-US/docs/Web/CSS/max-content), i.e. `min(max-content, max(min-content, stretch))`. + - : Use the available space, but not more than [max-content](/en-US/docs/Web/CSS/max-content), i.e., `min(max-content, max(min-content, stretch))`. - `fit-content({{cssxref("&lt;length-percentage&gt;")}})` - - : Uses the fit-content formula with the available space replaced by the specified argument, i.e. `min(max-content, max(min-content, <length-percentage>))`. + - : Uses the fit-content formula with the available space replaced by the specified argument, i.e., `min(max-content, max(min-content, <length-percentage>))`. - `stretch` - - : Sets the height of the element's [margin box](/en-US/docs/Learn_web_development/Core/Styling_basics/Box_model#parts_of_a_box) to the height of its [containing block](/en-US/docs/Web/CSS/CSS_display/Containing_block#identifying_the_containing_block). It attempts to make the margin box fill the available space in the containing block, so in a way behaving similar to `100%` but applying the resulting size to the margin box rather than the box determined by [box-sizing](/en-US/docs/Web/CSS/box-sizing). - > [!NOTE] - > To check aliases used by browsers for the `stretch` value and its implementation status, see the [Browser compatibility](#browser_compatibility) section. - ## Accessibility Ensure that elements set with a `height` aren't truncated and/or don't obscure other content when the page is zoomed to increase text size. -- [MDN Understanding WCAG, Guideline 1.4 explanations](/en-US/docs/Web/Accessibility/Understanding_WCAG/Perceivable#guideline_1.4_make_it_easier_for_users_to_see_and_hear_content_including_separating_foreground_from_background) +- [MDN Understanding WCAG, Guideline 1.4 explanations](/en-US/docs/Web/Accessibility/Guides/Understanding_WCAG/Perceivable#guideline_1.4_make_it_easier_for_users_to_see_and_hear_content_including_separating_foreground_from_background) - [Understanding Success Criterion 1.4.4 | W3C Understanding WCAG 2.0](https://www.w3.org/TR/UNDERSTANDING-WCAG20/visual-audio-contrast-scale.html) ## Formal definition @@ -129,6 +159,55 @@ div { {{EmbedLiveSample('Setting_height_using_pixels_and_percentages', 'auto', 240)}} +### Stretch height to fill the containing block + +#### HTML + +```html +<div class="parent"> + <div class="child">text</div> +</div> + +<div class="parent"> + <div class="child stretch">stretch</div> +</div> +``` + +#### CSS + +```css hidden +@supports not (height: stretch) { + .parent { + display: none !important; + } + + body::after { + content: "Your browser doesn't support the `stretch` value yet."; + } +} +``` + +```css +.parent { + height: 150px; + margin: 1rem; + border: solid; +} + +.child { + margin: 1rem; + background: #0999; +} + +.stretch { + height: stretch; +} +``` + +#### Result + +{{EmbedLiveSample('Stretch height to fill the containing block', 'auto', 380)}} + ## Specifications {{Specifications}} diff --git a/files/en-us/web/css/hue-interpolation-method/index.md b/files/en-us/web/css/hue-interpolation-method/index.md index e18948d219a102c..900b1945a87bc1e 100644 --- a/files/en-us/web/css/hue-interpolation-method/index.md +++ b/files/en-us/web/css/hue-interpolation-method/index.md @@ -2,14 +2,7 @@ title: <hue-interpolation-method> slug: Web/CSS/hue-interpolation-method page-type: css-type -browser-compat: - - css.types.color.color-mix - - css.types.image.gradient.conic-gradient.hue_interpolation_method - - css.types.image.gradient.linear-gradient.hue_interpolation_method - - css.types.image.gradient.radial-gradient.hue_interpolation_method - - css.types.image.gradient.repeating-conic-gradient.hue_interpolation_method - - css.types.image.gradient.repeating-linear-gradient.hue_interpolation_method - - css.types.image.gradient.repeating-radial-gradient.hue_interpolation_method +browser-compat: css.types.gradient.conic-gradient.hue_interpolation_method spec-urls: https://drafts.csswg.org/css-color/#hue-interpolation --- diff --git a/files/en-us/web/css/hyphenate-character/index.md b/files/en-us/web/css/hyphenate-character/index.md index 129ca21d214d96f..54c92944cad9d8e 100644 --- a/files/en-us/web/css/hyphenate-character/index.md +++ b/files/en-us/web/css/hyphenate-character/index.md @@ -11,7 +11,35 @@ The **`hyphenate-character`** [CSS](/en-US/docs/Web/CSS) property sets the chara Both automatic and soft hyphens are displayed according to the specified hyphenate-character value. -{{EmbedInteractiveExample("pages/css/hyphenate-character.html")}} +{{InteractiveExample("CSS Demo: hyphenate-character")}} + +```css interactive-example-choice +hyphenate-character: auto; +``` + +```css interactive-example-choice +hyphenate-character: "="; +``` + +```css interactive-example-choice +hyphenate-character: "—"; +``` + +```html interactive-example +<section id="default-example"> + <p id="example-element">An extra­ordinarily long English word!</p> +</section> +``` + +```css interactive-example +#example-element { + border: 2px dashed #999; + font-size: 1.5rem; + text-align: left; + width: 7rem; + hyphens: auto; +} +``` ## Syntax diff --git a/files/en-us/web/css/hyphens/index.md b/files/en-us/web/css/hyphens/index.md index f93f7a5d29c6302..6e2ae2fddb34b40 100644 --- a/files/en-us/web/css/hyphens/index.md +++ b/files/en-us/web/css/hyphens/index.md @@ -9,12 +9,39 @@ browser-compat: css.properties.hyphens The **`hyphens`** [CSS](/en-US/docs/Web/CSS) property specifies how words should be hyphenated when text wraps across multiple lines. It can prevent hyphenation entirely, hyphenate at manually-specified points within the text, or let the browser automatically insert hyphens where appropriate. -{{EmbedInteractiveExample("pages/css/hyphens.html")}} +{{InteractiveExample("CSS Demo: hyphens")}} + +```css interactive-example-choice +hyphens: none; +``` + +```css interactive-example-choice +hyphens: manual; +``` + +```css interactive-example-choice +hyphens: auto; +``` + +```html interactive-example +<section id="default-example"> + <p id="example-element">An extra­ordinarily long English word!</p> +</section> +``` + +```css interactive-example +#example-element { + border: 2px dashed #999; + font-size: 1.5rem; + text-align: left; + width: 7rem; +} +``` > [!NOTE] > In the above demo, the string "An extraordinarily long English word!" contains the hidden `&shy;` (soft hyphen) character: `An extra&shy;ordinarily long English word!`. This character is used to indicate a potential place to insert a hyphen when `hyphens: manual;` is specified. -Hyphenation rules are language-specific. In HTML, the language is determined by the [`lang`](/en-US/docs/Web/HTML/Global_attributes/lang) attribute, and browsers will hyphenate only if this attribute is present and the appropriate hyphenation dictionary is available. In XML, the [`xml:lang`](/en-US/docs/Web/SVG/Attribute/xml:lang) attribute must be used. +Hyphenation rules are language-specific. In HTML, the language is determined by the [`lang`](/en-US/docs/Web/HTML/Reference/Global_attributes/lang) attribute, and browsers will hyphenate only if this attribute is present and the appropriate hyphenation dictionary is available. In XML, the [`xml:lang`](/en-US/docs/Web/SVG/Reference/Attribute/xml:lang) attribute must be used. > [!NOTE] > The rules defining how hyphenation is performed are not explicitly defined by the specification, so the exact hyphenation may vary from browser to browser. @@ -64,7 +91,7 @@ There are two Unicode characters used to manually specify potential line break p - : An invisible, "**s**oft" **hy**phen. This character is not rendered visibly; instead, it marks a place where the browser should break the word if hyphenation is necessary. In HTML, use `&shy;` to insert a soft hyphen. > [!NOTE] -> When the HTML [`<wbr>`](/en-US/docs/Web/HTML/Element/wbr) element leads to a line break, no hyphen is added. +> When the HTML [`<wbr>`](/en-US/docs/Web/HTML/Reference/Elements/wbr) element leads to a line break, no hyphen is added. ## Formal definition diff --git a/files/en-us/web/css/id_selectors/index.md b/files/en-us/web/css/id_selectors/index.md index 34ce9ab83f245c6..b180e2edb774248 100644 --- a/files/en-us/web/css/id_selectors/index.md +++ b/files/en-us/web/css/id_selectors/index.md @@ -7,7 +7,7 @@ browser-compat: css.selectors.id {{CSSRef}} -The CSS **ID selector** matches an element based on the value of the element's [`id`](/en-US/docs/Web/HTML/Global_attributes/id) attribute. In order for the element to be selected, its `id` attribute must match exactly the value given in the selector. +The CSS **ID selector** matches an element based on the value of the element's [`id`](/en-US/docs/Web/HTML/Reference/Global_attributes/id) attribute. In order for the element to be selected, its `id` attribute must match exactly the value given in the selector. ```css /* The element with id="demo" */ @@ -19,13 +19,17 @@ The CSS **ID selector** matches an element based on the value of the element's [ ## Syntax ```css -#id_value { style properties } +#id_value { + /* … */ +} ``` Note that syntactically (but not specificity-wise), this is equivalent to the following [attribute selector](/en-US/docs/Web/CSS/Attribute_selectors): ```css -[id=id_value] { style properties } +[id="id_value"] { + /* … */ +} ``` The `id_value` value must be a valid [CSS identifier](/en-US/docs/Web/CSS/ident). HTML `id` attributes which are not valid CSS identifiers must be [escaped](/en-US/docs/Web/CSS/ident#escaping_characters) before they can be used in ID selectors. diff --git a/files/en-us/web/css/image-orientation/index.md b/files/en-us/web/css/image-orientation/index.md index aa7cf6f89db4bda..303801171b38168 100644 --- a/files/en-us/web/css/image-orientation/index.md +++ b/files/en-us/web/css/image-orientation/index.md @@ -9,7 +9,30 @@ browser-compat: css.properties.image-orientation The **`image-orientation`** [CSS](/en-US/docs/Web/CSS) property specifies a layout-independent correction to the orientation of an image. -{{EmbedInteractiveExample("pages/css/image-orientation.html")}} +{{InteractiveExample("CSS Demo: image-orientation")}} + +```css interactive-example-choice +image-orientation: none; +``` + +```css interactive-example-choice +image-orientation: from-image; +``` + +```html interactive-example +<section id="default-example"> + <img + class="transition-all" + id="example-element" + src="/shared-assets/images/examples/hummingbird.jpg" /> +</section> +``` + +```css interactive-example +#example-element { + height: inherit; +} +``` ## Syntax diff --git a/files/en-us/web/css/image-rendering/index.md b/files/en-us/web/css/image-rendering/index.md index 19198e706413200..fc06ef2493d1ec8 100644 --- a/files/en-us/web/css/image-rendering/index.md +++ b/files/en-us/web/css/image-rendering/index.md @@ -9,7 +9,39 @@ browser-compat: css.properties.image-rendering The **`image-rendering`** [CSS](/en-US/docs/Web/CSS) property sets an image scaling algorithm. The property applies to an element itself, to any images set in its other properties, and to its descendants. -{{EmbedInteractiveExample("pages/css/image-rendering.html")}} +{{InteractiveExample("CSS Demo: image-rendering")}} + +```css interactive-example-choice +image-rendering: auto; +``` + +```css interactive-example-choice +image-rendering: smooth; +``` + +```css interactive-example-choice +image-rendering: crisp-edges; +``` + +```css interactive-example-choice +image-rendering: pixelated; +``` + +```html interactive-example +<section id="default-example"> + <img + class="transition-all" + id="example-element" + src="/shared-assets/images/examples/lizard.png" /> +</section> +``` + +```css interactive-example +#example-element { + height: 480px; + object-fit: cover; +} +``` The {{Glossary("user agent")}} will scale an image when the page author specifies dimensions other than its natural size. Scaling may also occur due to user interaction (zooming). For example, if the natural size of an image is `100×100px`_,_ but its actual dimensions are `200×200px` (or `50×50px`), then the image will be upscaled (or downscaled) using the algorithm specified by `image-rendering`. This property has no effect on non-scaled images. diff --git a/files/en-us/web/css/image/image-set/index.md b/files/en-us/web/css/image/image-set/index.md index 361b6b4f8aff30f..56c7ea6a95d21f5 100644 --- a/files/en-us/web/css/image/image-set/index.md +++ b/files/en-us/web/css/image/image-set/index.md @@ -59,7 +59,7 @@ image-set( Browsers do not provide any special information on background images to assistive technology. This is important primarily for screen readers, as a screen reader will not announce its presence and therefore convey nothing to its users. If the image contains information critical to understanding the page's overall purpose, it is better to describe it semantically in the document. -- [MDN Understanding WCAG, Guideline 1.1 explanations](/en-US/docs/Web/Accessibility/Understanding_WCAG/Perceivable#guideline_1.1_—_providing_text_alternatives_for_non-text_content) +- [MDN Understanding WCAG, Guideline 1.1 explanations](/en-US/docs/Web/Accessibility/Guides/Understanding_WCAG/Perceivable#guideline_1.1_—_providing_text_alternatives_for_non-text_content) - [Understanding Success Criterion 1.1.1 | W3C Understanding WCAG 2.0](https://www.w3.org/TR/UNDERSTANDING-WCAG20/text-equiv-all.html) ## Examples diff --git a/files/en-us/web/css/image/image/index.md b/files/en-us/web/css/image/image/index.md index 3dce78b97cda28e..f46638e960106c0 100644 --- a/files/en-us/web/css/image/image/index.md +++ b/files/en-us/web/css/image/image/index.md @@ -58,7 +58,7 @@ The background image of the element will be the portion of the image _myImage.we The `#xywh=#,#,#,#` media fragment syntax takes four comma separated numeric values. The first two represent the X and Y coordinates for the starting point of the box that will be created. The third value is the width of the box, and the last value is the height. By default, these are pixel values. The [spacial dimension definition in the media specification](https://www.w3.org/TR/media-frags/#naming-space) indicates that percentages will be supported as well: -```css +```plain xywh=160,120,320,240 /* results in a 320x240 image at x=160 and y=120 */ xywh=pixel:160,120,320,240 /* results in a 320x240 image at x=160 and y=120 */ xywh=percent:25,25,50,50 /* results in a 50%x50% image at x=25% and y=25% */ @@ -84,7 +84,7 @@ The size of the color swatch can be set with the {{CSSxRef("background-size")}} Browsers do not provide any special information on background images to assistive technology. This is important primarily for screen readers, as a screen reader will not announce its presence and therefore convey nothing to its users. If the image contains information critical to understanding the page's overall purpose, it is better to describe it semantically in the document. -- [MDN Understanding WCAG, Guideline 1.1 explanations](/en-US/docs/Web/Accessibility/Understanding_WCAG/Perceivable#guideline_1.1_—_providing_text_alternatives_for_non-text_content) +- [MDN Understanding WCAG, Guideline 1.1 explanations](/en-US/docs/Web/Accessibility/Guides/Understanding_WCAG/Perceivable#guideline_1.1_—_providing_text_alternatives_for_non-text_content) - [Understanding Success Criterion 1.1.1 | W3C Understanding WCAG 2.0](https://www.w3.org/TR/UNDERSTANDING-WCAG20/text-equiv-all.html) This feature can help improve accessibility by providing a fallback color when an image fails to load. While this can and should be done by including a background-color on every background image, the CSS `image()` function allows adding allows only including background colors should an image fail to load, which means you can add a fall back color should a transparent PNG/GIF/WebP not load. diff --git a/files/en-us/web/css/image/index.md b/files/en-us/web/css/image/index.md index 6e9798dda2bbd84..c5bc8a5e0d0918d 100644 --- a/files/en-us/web/css/image/index.md +++ b/files/en-us/web/css/image/index.md @@ -57,7 +57,7 @@ The concrete object size is calculated using the following algorithm: Browsers do not provide any special information on background images to assistive technology. This is important primarily for screen readers, as a screen reader will not announce its presence and therefore convey nothing to its users. If the image contains information critical to understanding the page's overall purpose, it is better to describe it semantically in the document. -- [MDN Understanding WCAG, Guideline 1.1 explanations](/en-US/docs/Web/Accessibility/Understanding_WCAG/Perceivable#guideline_1.1_—_providing_text_alternatives_for_non-text_content) +- [MDN Understanding WCAG, Guideline 1.1 explanations](/en-US/docs/Web/Accessibility/Guides/Understanding_WCAG/Perceivable#guideline_1.1_—_providing_text_alternatives_for_non-text_content) - [Understanding Success Criterion 1.1.1 | W3C Understanding WCAG 2.0](https://www.w3.org/TR/UNDERSTANDING-WCAG20/text-equiv-all.html) ## Formal syntax diff --git a/files/en-us/web/css/important/index.md b/files/en-us/web/css/important/index.md index 2ef5981013955dd..00e1afef2d5fe39 100644 --- a/files/en-us/web/css/important/index.md +++ b/files/en-us/web/css/important/index.md @@ -18,7 +18,7 @@ selector { } ``` -The `!important` comes after the value of the property value pair declaration, preceded by at least one space. The important flag must be the last token in the declaration. In other words, there can be white space and comments between the flag and the declaration's ending semicolon, but nothing else. +The `!important` comes after the value of the property value pair declaration, preceded by zero or more spaces. The important flag must be the last token in the declaration. In other words, there can be white space and comments between the flag and the declaration's ending semicolon, but nothing else. ## Impact on the cascade @@ -53,7 +53,7 @@ Within each of the three origins for style sheets – author, user, and user-age ### Inline styles -Inline styles are styles defined using the [`style`](/en-US/docs/Web/HTML/Global_attributes/style) attributes. They can also be normal or important. Inline _normal_ styles take precedence over all _normal_ declarations, no matter the origin. Inline _important_ styles take precedence over all other _important_ author styles, no matter the layer, but important styles from user's or user-agent's style sheets and transitions override them. +Inline styles are styles defined using the [`style`](/en-US/docs/Web/HTML/Reference/Global_attributes/style) attributes. They can also be normal or important. Inline _normal_ styles take precedence over all _normal_ declarations, no matter the origin. Inline _important_ styles take precedence over all other _important_ author styles, no matter the layer, but important styles from user's or user-agent's style sheets and transitions override them. ### !important and specificity diff --git a/files/en-us/web/css/index.md b/files/en-us/web/css/index.md index 34edbdc5371f502..0ddbaba651341bc 100644 --- a/files/en-us/web/css/index.md +++ b/files/en-us/web/css/index.md @@ -1,5 +1,6 @@ --- title: "CSS: Cascading Style Sheets" +short-title: CSS slug: Web/CSS page-type: landing-page --- @@ -34,8 +35,8 @@ The [CSS reference](/en-US/docs/Web/CSS/Reference) is an exhaustive reference fo - [CSS values and units](/en-US/docs/Web/CSS/CSS_Values_and_Units) module, including [numeric data types](/en-US/docs/Web/CSS/CSS_Values_and_Units/Numeric_data_types), [textual data types](/en-US/docs/Web/CSS/CSS_Values_and_Units/Textual_data_types) and [functional notations](/en-US/docs/Web/CSS/CSS_Values_and_Units/CSS_Value_Functions) - [Box model](/en-US/docs/Web/CSS/CSS_box_model/Introduction_to_the_CSS_box_model) and [margin collapse](/en-US/docs/Web/CSS/CSS_box_model/Mastering_margin_collapsing) - The [containing block](/en-US/docs/Web/CSS/CSS_display/Containing_block) -- [Stacking](/en-US/docs/Web/CSS/CSS_positioned_layout/Understanding_z-index/Stacking_context) and [block-formatting](/en-US/docs/Web/CSS/CSS_display/Block_formatting_context) contexts -- [Initial](/en-US/docs/Web/CSS/CSS_cascade/initial_value), [computed](/en-US/docs/Web/CSS/CSS_cascade/computed_value), [used](/en-US/docs/Web/CSS/CSS_cascade/used_value), and [actual](/en-US/docs/Web/CSS/CSS_cascade/actual_value) values +- [Stacking](/en-US/docs/Web/CSS/CSS_positioned_layout/Stacking_context) and [block-formatting](/en-US/docs/Web/CSS/CSS_display/Block_formatting_context) contexts +- [Initial](/en-US/docs/Web/CSS/CSS_cascade/Value_processing#initial_value), [computed](/en-US/docs/Web/CSS/CSS_cascade/Value_processing#computed_value), [used](/en-US/docs/Web/CSS/CSS_cascade/Value_processing#used_value), and [actual](/en-US/docs/Web/CSS/CSS_cascade/Value_processing#actual_value) values - [CSS shorthand properties](/en-US/docs/Web/CSS/CSS_cascade/Shorthand_properties) - [CSS flexible box](/en-US/docs/Web/CSS/CSS_flexible_box_layout), [multi-column](/en-US/docs/Web/CSS/CSS_multicol_layout) and [grid](/en-US/docs/Web/CSS/CSS_grid_layout) layout - [Animation](/en-US/docs/Web/CSS/CSS_animations), [transitions](/en-US/docs/Web/CSS/CSS_transitions), and [transforms](/en-US/docs/Web/CSS/CSS_transforms) diff --git a/files/en-us/web/css/inherit/index.md b/files/en-us/web/css/inherit/index.md index c44dc3470f7ce9c..390fa6141d011ce 100644 --- a/files/en-us/web/css/inherit/index.md +++ b/files/en-us/web/css/inherit/index.md @@ -7,7 +7,7 @@ browser-compat: css.types.global_keywords.inherit {{CSSRef}} -The **`inherit`** CSS keyword causes the element to take the [computed value](/en-US/docs/Web/CSS/CSS_cascade/computed_value) of the property from its parent element. It can be applied to any CSS property, including the CSS shorthand property {{cssxref("all")}}. +The **`inherit`** CSS keyword causes the element to take the [computed value](/en-US/docs/Web/CSS/CSS_cascade/Value_processing#computed_value) of the property from its parent element. It can be applied to any CSS property, including the CSS shorthand property {{cssxref("all")}}. For [inherited properties](/en-US/docs/Web/CSS/CSS_cascade/Inheritance#inherited_properties), this reinforces the default behavior, and is only needed to override another rule. diff --git a/files/en-us/web/css/initial/index.md b/files/en-us/web/css/initial/index.md index d82e40638c0f4f2..dccf6c6c58cad1a 100644 --- a/files/en-us/web/css/initial/index.md +++ b/files/en-us/web/css/initial/index.md @@ -7,7 +7,7 @@ browser-compat: css.types.global_keywords.initial {{CSSRef}} -The **`initial`** CSS keyword applies the [initial (or default) value](/en-US/docs/Web/CSS/CSS_cascade/initial_value) of a property to an element. It can be applied to any CSS property, including the CSS shorthand property {{cssxref("all")}}. With `all` set to `initial`, all CSS properties can be restored to their respective initial values in one go instead of restoring each one separately. +The **`initial`** CSS keyword applies the [initial (or default) value](/en-US/docs/Web/CSS/CSS_cascade/Value_processing#initial_value) of a property to an element. It can be applied to any CSS property, including the CSS shorthand property {{cssxref("all")}}. With `all` set to `initial`, all CSS properties can be restored to their respective initial values in one go instead of restoring each one separately. On [inherited properties](/en-US/docs/Web/CSS/CSS_cascade/Inheritance#inherited_properties), the initial value may be unexpected. You should consider using the {{cssxref("inherit")}}, {{cssxref("unset")}}, {{cssxref("revert")}}, or {{cssxref("revert-layer")}} keywords instead. diff --git a/files/en-us/web/css/inline-size/index.md b/files/en-us/web/css/inline-size/index.md index 602f59eff9a13b0..4cb36875f363248 100644 --- a/files/en-us/web/css/inline-size/index.md +++ b/files/en-us/web/css/inline-size/index.md @@ -7,11 +7,48 @@ browser-compat: css.properties.inline-size {{CSSRef}} -The **`inline-size`** [CSS](/en-US/docs/Web/CSS) property defines the horizontal or vertical size of an element's block, depending on its writing mode. It corresponds to either the {{cssxref("width")}} or the {{cssxref("height")}} property, depending on the value of {{cssxref("writing-mode")}}. +The **`inline-size`** [CSS](/en-US/docs/Web/CSS) property defines the size of an element's block along the [inline axis](/en-US/docs/Glossary/Grid_Axis). If the {{cssxref("writing-mode")}} is horizontal, it corresponds to the {{cssxref("width")}}; if the writing mode is vertical, it corresponds to the {{cssxref("height")}}. A related property is {{cssxref("block-size")}}, which defines the other dimension of the element. -If the writing mode is vertically oriented, the value of `inline-size` relates to the height of the element; otherwise, it relates to the width of the element. A related property is {{cssxref("block-size")}}, which defines the other dimension of the element. +{{InteractiveExample("CSS Demo: inline-size")}} -{{EmbedInteractiveExample("pages/css/inline-size.html")}} +```css interactive-example-choice +inline-size: 150px; +writing-mode: horizontal-tb; +``` + +```css interactive-example-choice +inline-size: 150px; +writing-mode: vertical-rl; +``` + +```css interactive-example-choice +inline-size: auto; +writing-mode: horizontal-tb; +``` + +```css interactive-example-choice +inline-size: auto; +writing-mode: vertical-lr; +``` + +```html interactive-example +<section class="default-example" id="default-example"> + <div class="transition-all" id="example-element"> + This is a box where you can change the inline-size. + </div> +</section> +``` + +```css interactive-example +#example-element { + display: flex; + flex-direction: column; + background-color: #5b6dcd; + height: 80%; + justify-content: center; + color: #ffffff; +} +``` ## Syntax diff --git a/files/en-us/web/css/inline_formatting_context/index.md b/files/en-us/web/css/inline_formatting_context/index.md deleted file mode 100644 index d2dba91942537e7..000000000000000 --- a/files/en-us/web/css/inline_formatting_context/index.md +++ /dev/null @@ -1,231 +0,0 @@ ---- -title: Inline formatting context -slug: Web/CSS/Inline_formatting_context -page-type: guide ---- - -{{CSSRef}} - -This article explains the inline formatting context. - -## Core concepts - -The inline formatting context is part of the visual rendering of a web page. Inline boxes are laid out one after the other, in the direction sentences run in the writing mode in use: - -- In a horizontal writing mode, boxes are laid out horizontally, starting on the left. -- In a vertical writing mode they would be laid out vertically starting at the top. - -In the example below, the two {{HTMLElement("div")}} elements with the black borders are part of a [block formatting context](/en-US/docs/Web/CSS/CSS_display/Block_formatting_context), while inside each box, the words participate in an inline formatting context. The words in the horizontal writing mode run horizontally, while words in the vertical writing mode run vertically. - -```html live-sample___inline -<div class="example horizontal">One Two Three</div> -<div class="example vertical">Four Five Six</div> -``` - -```css live-sample___inline -body { - font: 1.2em sans-serif; -} -.example { - border: 5px solid black; - margin: 20px; -} - -.horizontal { - writing-mode: horizontal-tb; -} -.vertical { - writing-mode: vertical-rl; -} -``` - -{{EmbedLiveSample("inline", "", "220px")}} - -Boxes forming a line are contained by a rectangular area called a line box. This box will be large enough to contain all of the inline boxes in that line; when there is no more room in the inline direction another line will be created. Therefore, a paragraph is a set of inline line boxes, stacked in the block direction. - -When an inline box is split, margins, borders, and padding have no visual effect where the split occurs. In the next example there is a {{HTMLElement("span")}} element wrapping a set of words wrapping onto two lines. The border on the `<span>` breaks at the wrapping point. - -```html live-sample___break -<div class="example"> - Before that night— - <span - >a memorable night, as it was to prove— hundreds of millions of people</span - > - had watched the rising smoke-wreaths of their fires without drawing any - special inspiration from the fact. -</div> -``` - -```css live-sample___break -body { - font: 1.2em sans-serif; -} -.example { - border: 5px solid black; - margin: 20px; -} - -span { - border: 5px solid rebeccapurple; -} -``` - -{{EmbedLiveSample("break")}} - -Margins, borders, and padding in the inline direction are respected. In the example below you can see how the margin, border, and padding on the inline `<span>` element are added. - -```html live-sample___mbp -<div class="example horizontal">One <span>Two</span> Three</div> -<div class="example vertical">Four <span>Five</span> Six</div> -``` - -```css live-sample___mbp -body { - font: 1.2em sans-serif; -} - -.example { - border: 5px solid black; - margin: 20px; -} - -span { - border: 5px solid rebeccapurple; - padding-inline-start: 20px; - padding-inline-end: 40px; - margin-inline-start: 30px; - margin-inline-end: 10px; -} -.horizontal { - writing-mode: horizontal-tb; -} - -.vertical { - writing-mode: vertical-rl; -} -``` - -{{EmbedLiveSample("mbp", "", "340px")}} - -> [!NOTE] -> I am using the logical, flow-relative properties — {{cssxref("padding-inline-start")}} rather than {{cssxref("padding-left")}} — so that they work in the inline dimension whether the text is horizontal or vertical. Read more about these properties in [Logical Properties and Values](/en-US/docs/Web/CSS/CSS_logical_properties_and_values). - -## Alignment in the block direction - -Inline boxes may be aligned in the block direction in different ways, using the {{cssxref("vertical-align")}} property, which will align on the block axis in vertical writing modes (therefore not vertically at all!). In the example below the large text is making the line box of the first sentence larger, therefore the `vertical-align` property can be used to align the inline boxes either side of it. I have used the value `top`, try changing it to `middle`, `bottom`, or `baseline`. - -```html live-sample___align -<div class="example horizontal"> - Before that night—<span>a memorable night</span>, as it was to prove—hundreds - of millions of people had watched the rising smoke-wreaths of their fires - without drawing any special inspiration from the fact. -</div> - -<div class="example vertical"> - Before that night—<span>a memorable night</span>, as it was to prove—hundreds - of millions of people had watched the rising smoke-wreaths of their fires - without drawing any special inspiration from the fact. -</div> -``` - -```css live-sample___align -body { - font: 1.2em sans-serif; -} - -span { - font-size: 200%; - vertical-align: top; -} - -.example { - border: 5px solid black; - margin: 20px; - inline-size: 400px; -} - -.horizontal { - writing-mode: horizontal-tb; -} - -.vertical { - writing-mode: vertical-rl; -} -``` - -{{EmbedLiveSample("align", "", "640px")}} - -## Alignment in the inline direction - -If there is additional space in the inline direction, the {{cssxref("text-align")}} property can be used to align the inline boxes within their line box. Try changing the value of `text-align` below to `end`. - -```html live-sample___text-align -<div class="example horizontal">One Two Three</div> -<div class="example vertical">Four Five Six</div> -``` - -```css hidden live-sample___text-align -body { - font: 1.2em sans-serif; -} - -.example { - border: 5px solid black; - margin: 20px; -} - -.horizontal { - writing-mode: horizontal-tb; -} - -.vertical { - writing-mode: vertical-rl; -} -``` - -```css live-sample___text-align -.example { - text-align: center; - inline-size: 250px; -} -``` - -{{EmbedLiveSample("text-align", "", "350px")}} - -## Effect of floats - -Line boxes usually have the same size in the inline direction, therefore the same width if working in a horizontal writing mode, or height if working in a vertical writing mode. If there is a {{cssxref("float")}} within the same block formatting context however, the float will cause the line boxes that wrap the float to become shorter. - -```html live-sample___float -<div class="box"> - <div class="float">I am a floated box!</div> - <p>I am content inside the container.</p> -</div> -``` - -```css live-sample___float -body { - font: 1.2em sans-serif; -} - -.box { - background-color: rgb(224 206 247); - border: 5px solid rebeccapurple; -} - -.float { - float: left; - width: 250px; - height: 150px; - background-color: white; - border: 1px solid black; - padding: 10px; -} -``` - -{{EmbedLiveSample("float", "", "200px")}} - -## See also - -- [Block formatting context](/en-US/docs/Web/CSS/CSS_display/Block_formatting_context) -- [Visual formatting model](/en-US/docs/Web/CSS/Visual_formatting_model) diff --git a/files/en-us/web/css/inset-block-end/index.md b/files/en-us/web/css/inset-block-end/index.md index 9b1cac9a538c986..471834fdd4e39af 100644 --- a/files/en-us/web/css/inset-block-end/index.md +++ b/files/en-us/web/css/inset-block-end/index.md @@ -11,7 +11,59 @@ The **`inset-block-end`** [CSS](/en-US/docs/Web/CSS) property defines the logica This {{glossary("inset properties", "inset property")}} has no effect on non-positioned elements. -{{EmbedInteractiveExample("pages/css/inset-block-end.html")}} +{{InteractiveExample("CSS Demo: inset-block-end")}} + +```css interactive-example-choice +writing-mode: horizontal-tb; +``` + +```css interactive-example-choice +writing-mode: vertical-rl; +``` + +```css interactive-example-choice +writing-mode: horizontal-tb; +direction: rtl; +``` + +```css interactive-example-choice +writing-mode: vertical-lr; +``` + +```html interactive-example +<section id="default-example"> + <div class="example-container" id="example-element"> + <div id="abspos">I am absolutely positioned with inset-block-end: 20px</div> + <p> + As much mud in the streets as if the waters had but newly retired from the + face of the earth, and it would not be wonderful to meet a Megalosaurus, + forty feet long or so, waddling like an elephantine lizard up Holborn + Hill. + </p> + </div> +</section> +``` + +```css interactive-example +#example-element { + border: 0.75em solid; + padding: 0.75em; + position: relative; + width: 100%; + min-height: 200px; + unicode-bidi: bidi-override; +} + +#abspos { + background-color: yellow; + color: black; + border: 3px solid red; + position: absolute; + inset-block-end: 20px; + inline-size: 140px; + min-block-size: 200px; +} +``` ## Syntax diff --git a/files/en-us/web/css/inset-block-start/index.md b/files/en-us/web/css/inset-block-start/index.md index b64a133d8589839..5c257df5b3f6a12 100644 --- a/files/en-us/web/css/inset-block-start/index.md +++ b/files/en-us/web/css/inset-block-start/index.md @@ -11,7 +11,60 @@ The **`inset-block-start`** [CSS](/en-US/docs/Web/CSS) property defines the logi This {{glossary("inset properties", "inset property")}} has no effect on non-positioned elements. -{{EmbedInteractiveExample("pages/css/inset-block-start.html")}} +{{InteractiveExample("CSS Demo: inset-block-start")}} + +```css interactive-example-choice +writing-mode: horizontal-tb; +``` + +```css interactive-example-choice +writing-mode: vertical-rl; +``` + +```css interactive-example-choice +writing-mode: horizontal-tb; +direction: rtl; +``` + +```css interactive-example-choice +writing-mode: vertical-lr; +``` + +```html interactive-example +<section id="default-example"> + <div class="example-container" id="example-element"> + <div id="abspos"> + I am absolutely positioned with inset-block-start: 50px + </div> + <p> + As much mud in the streets as if the waters had but newly retired from the + face of the earth, and it would not be wonderful to meet a Megalosaurus, + forty feet long or so, waddling like an elephantine lizard up Holborn + Hill. + </p> + </div> +</section> +``` + +```css interactive-example +#example-element { + border: 0.75em solid; + padding: 0.75em; + position: relative; + width: 100%; + min-height: 200px; + unicode-bidi: bidi-override; +} + +#abspos { + background-color: yellow; + color: black; + border: 3px solid red; + position: absolute; + inset-block-start: 50px; + inline-size: 140px; +} +``` ## Syntax diff --git a/files/en-us/web/css/inset-block/index.md b/files/en-us/web/css/inset-block/index.md index 91f6691d6f4beaf..43a39ce7c2837fa 100644 --- a/files/en-us/web/css/inset-block/index.md +++ b/files/en-us/web/css/inset-block/index.md @@ -11,7 +11,60 @@ The **`inset-block`** [CSS](/en-US/docs/Web/CSS) property defines the logical bl This {{glossary("inset properties", "inset property")}} has no effect on non-positioned elements. -{{EmbedInteractiveExample("pages/css/inset-block.html")}} +{{InteractiveExample("CSS Demo: inset-block")}} + +```css interactive-example-choice +inset-block: 10px 20px; +writing-mode: horizontal-tb; +``` + +```css interactive-example-choice +inset-block: 20px 40px; +writing-mode: vertical-rl; +``` + +```css interactive-example-choice +inset-block: 5% 20%; +writing-mode: horizontal-tb; +``` + +```css interactive-example-choice +inset-block: 1rem auto; +writing-mode: vertical-lr; +``` + +```html interactive-example +<section id="default-example"> + <div class="example-container"> + <div id="example-element">I am absolutely positioned.</div> + <p> + As much mud in the streets as if the waters had but newly retired from the + face of the earth, and it would not be wonderful to meet a Megalosaurus, + forty feet long or so, waddling like an elephantine lizard up Holborn + Hill. + </p> + </div> +</section> +``` + +```css interactive-example +.example-container { + border: 0.75em solid #ad1457; + padding: 0.75em; + text-align: left; + position: relative; + width: 100%; + min-height: 200px; +} + +#example-element { + background-color: #07136c; + border: 6px solid #ffa000; + color: white; + position: absolute; + inset: 0; +} +``` ## Constituent properties diff --git a/files/en-us/web/css/inset-inline-end/index.md b/files/en-us/web/css/inset-inline-end/index.md index f86ddd509e0e010..87c485ff69b96a3 100644 --- a/files/en-us/web/css/inset-inline-end/index.md +++ b/files/en-us/web/css/inset-inline-end/index.md @@ -11,7 +11,61 @@ The **`inset-inline-end`** [CSS](/en-US/docs/Web/CSS) property defines the logic This {{glossary("inset properties", "inset property")}} has no effect on non-positioned elements. -{{EmbedInteractiveExample("pages/css/inset-inline-end.html")}} +{{InteractiveExample("CSS Demo: inset-inline-end")}} + +```css interactive-example-choice +writing-mode: horizontal-tb; +``` + +```css interactive-example-choice +writing-mode: vertical-rl; +``` + +```css interactive-example-choice +writing-mode: horizontal-tb; +direction: rtl; +``` + +```css interactive-example-choice +writing-mode: vertical-lr; +``` + +```html interactive-example +<section id="default-example"> + <div class="example-container" id="example-element"> + <div id="abspos"> + I am absolutely positioned with inset-inline-end: 50px + </div> + <p> + As much mud in the streets as if the waters had but newly retired from the + face of the earth, and it would not be wonderful to meet a Megalosaurus, + forty feet long or so, waddling like an elephantine lizard up Holborn + Hill. + </p> + </div> +</section> +``` + +```css interactive-example +#example-element { + border: 0.75em solid; + padding: 0.75em; + position: relative; + width: 100%; + min-height: 200px; + unicode-bidi: bidi-override; +} + +#abspos { + background-color: yellow; + color: black; + border: 3px solid red; + position: absolute; + inset-inline-end: 50px; + inline-size: 140px; + min-block-size: 80px; +} +``` ## Syntax diff --git a/files/en-us/web/css/inset-inline-start/index.md b/files/en-us/web/css/inset-inline-start/index.md index ad727958441d8f2..3158cf98e4f92de 100644 --- a/files/en-us/web/css/inset-inline-start/index.md +++ b/files/en-us/web/css/inset-inline-start/index.md @@ -11,7 +11,61 @@ The **`inset-inline-start`** [CSS](/en-US/docs/Web/CSS) property defines the log This {{glossary("inset properties", "inset property")}} has no effect on non-positioned elements. -{{EmbedInteractiveExample("pages/css/inset-inline-start.html")}} +{{InteractiveExample("CSS Demo: inset-inline-start")}} + +```css interactive-example-choice +writing-mode: horizontal-tb; +``` + +```css interactive-example-choice +writing-mode: vertical-rl; +``` + +```css interactive-example-choice +writing-mode: horizontal-tb; +direction: rtl; +``` + +```css interactive-example-choice +writing-mode: vertical-lr; +``` + +```html interactive-example +<section id="default-example"> + <div class="example-container" id="example-element"> + <div id="abspos"> + I am absolutely positioned with inset-inline-start: 50px + </div> + <p> + As much mud in the streets as if the waters had but newly retired from the + face of the earth, and it would not be wonderful to meet a Megalosaurus, + forty feet long or so, waddling like an elephantine lizard up Holborn + Hill. + </p> + </div> +</section> +``` + +```css interactive-example +#example-element { + border: 0.75em solid; + padding: 0.75em; + position: relative; + width: 100%; + min-height: 200px; + unicode-bidi: bidi-override; +} + +#abspos { + background-color: yellow; + color: black; + border: 3px solid red; + position: absolute; + inset-inline-start: 50px; + inline-size: 140px; + min-block-size: 80px; +} +``` ## Syntax diff --git a/files/en-us/web/css/inset-inline/index.md b/files/en-us/web/css/inset-inline/index.md index ae4d7e22e6b7451..cda470df783cae9 100644 --- a/files/en-us/web/css/inset-inline/index.md +++ b/files/en-us/web/css/inset-inline/index.md @@ -11,7 +11,56 @@ The **`inset-inline`** [CSS](/en-US/docs/Web/CSS) property defines the logical s This {{glossary("inset properties", "inset property")}} has no effect on non-positioned elements. -{{EmbedInteractiveExample("pages/css/inset-inline.html")}} +{{InteractiveExample("CSS Demo: inset-inline")}} + +```css interactive-example-choice +inset-inline: 5% 10%; +writing-mode: horizontal-tb; +``` + +```css interactive-example-choice +inset-inline: 10px 40px; +writing-mode: vertical-rl; +``` + +```css interactive-example-choice +inset-inline: 5% 10%; +writing-mode: horizontal-tb; +direction: rtl; +``` + +```html interactive-example +<section id="default-example"> + <div class="example-container"> + <div id="example-element">I am absolutely positioned.</div> + <p> + As much mud in the streets as if the waters had but newly retired from the + face of the earth, and it would not be wonderful to meet a Megalosaurus, + forty feet long or so, waddling like an elephantine lizard up Holborn + Hill. + </p> + </div> +</section> +``` + +```css interactive-example +.example-container { + border: 0.75em solid #ad1457; + padding: 0.75em; + text-align: left; + position: relative; + width: 100%; + min-height: 200px; +} + +#example-element { + background-color: #07136c; + border: 6px solid #ffa000; + color: white; + position: absolute; + inset: 0; +} +``` ## Constituent properties diff --git a/files/en-us/web/css/inset/index.md b/files/en-us/web/css/inset/index.md index 7238094c9fd8da7..b69ea21eb8e604a 100644 --- a/files/en-us/web/css/inset/index.md +++ b/files/en-us/web/css/inset/index.md @@ -11,7 +11,60 @@ The **`inset`** [CSS](/en-US/docs/Web/CSS) property is a shorthand that correspo This {{glossary("inset properties")}}, including `inset`, have no effect on non-positioned elements. -{{EmbedInteractiveExample("pages/css/inset.html")}} +{{InteractiveExample("CSS Demo: inset")}} + +```css interactive-example-choice +inset: 1em; +``` + +```css interactive-example-choice +inset: 5% 0; +``` + +```css interactive-example-choice +inset: 2em 50px 20px; +``` + +```css interactive-example-choice +inset: 10px 30% 20px 0; +``` + +```css interactive-example-choice +inset: 0; +``` + +```html interactive-example +<section id="default-example"> + <div class="example-container"> + <div id="example-element">I am absolutely positioned.</div> + <p> + As much mud in the streets as if the waters had but newly retired from the + face of the earth, and it would not be wonderful to meet a Megalosaurus, + forty feet long or so, waddling like an elephantine lizard up Holborn + Hill. + </p> + </div> +</section> +``` + +```css interactive-example +.example-container { + border: 0.75em solid #ad1457; + padding: 0.75em; + text-align: left; + position: relative; + width: 100%; + min-height: 200px; +} + +#example-element { + background-color: #07136c; + border: 6px solid #ffa000; + color: white; + position: absolute; + inset: 0; +} +``` While part of the [CSS logical properties and values](/en-US/docs/Web/CSS/CSS_logical_properties_and_values) module, it does not define _logical_ offsets. It defines _physical_ offsets, regardless of the element's writing mode, directionality, and text orientation. diff --git a/files/en-us/web/css/interpolate-size/index.md b/files/en-us/web/css/interpolate-size/index.md index bc7b33d45dcd273..932fa4e861a16ee 100644 --- a/files/en-us/web/css/interpolate-size/index.md +++ b/files/en-us/web/css/interpolate-size/index.md @@ -11,7 +11,7 @@ browser-compat: css.properties.interpolate-size The **`interpolate-size`** [CSS](/en-US/docs/Web/CSS) property allows you to enable [animations](/en-US/docs/Web/CSS/CSS_animations) and [transitions](/en-US/docs/Web/CSS/CSS_transitions) between a [`<length-percentage>`](/en-US/docs/Web/CSS/length-percentage) value and an [intrinsic size](/en-US/docs/Glossary/Intrinsic_Size) value such as `auto`, [`fit-content`](/en-US/docs/Web/CSS/fit-content), or [`max-content`](/en-US/docs/Web/CSS/max-content). -This property is typically used to animate the {{cssxref("width")}} and/or {{cssxref("height")}} of a container between a `<length-percentage>` and the full size of its content (i.e. between "closed" and "open" or "hide" and "reveal" states) when animating a non-box-model CSS property, such as {{cssxref("transform")}}, is not a viable solution. +This property is typically used to animate the {{cssxref("width")}} and/or {{cssxref("height")}} of a container between a `<length-percentage>` and the full size of its content (i.e., between "closed" and "open" or "hide" and "reveal" states) when animating a non-box-model CSS property, such as {{cssxref("transform")}}, is not a viable solution. > [!NOTE] > The behavior opted-into by `interpolate-size` cannot be enabled by default across the web because many sites in the wild use stylesheets that assume intrinsic size values cannot be animated. Enabling it by default would cause several backwards-compatibility issues (see relevant [CSS WG discussion](https://github.com/w3c/csswg-drafts/issues/626#issuecomment-2071016522)). @@ -87,7 +87,7 @@ This example demonstrates how to set `interpolate-size: allow-keywords` on a doc #### HTML -The HTML contains a single {{htmlelement("section")}} element with [`tabindex="0"`](/en-US/docs/Web/HTML/Global_attributes/tabindex) set on it so it can receive keyboard focus. The `<section>` contains {{htmlelement("header")}} and {{htmlelement("main")}} elements, each with their own child content. +The HTML contains a single {{htmlelement("section")}} element with [`tabindex="0"`](/en-US/docs/Web/HTML/Reference/Global_attributes/tabindex) set on it so it can receive keyboard focus. The `<section>` contains {{htmlelement("header")}} and {{htmlelement("main")}} elements, each with their own child content. ```html <section tabindex="0"> diff --git a/files/en-us/web/css/isolation/index.md b/files/en-us/web/css/isolation/index.md index 57b6f4486877bd3..e64cabbbb202157 100644 --- a/files/en-us/web/css/isolation/index.md +++ b/files/en-us/web/css/isolation/index.md @@ -9,7 +9,43 @@ browser-compat: css.properties.isolation The **`isolation`** [CSS](/en-US/docs/Web/CSS) property determines whether an element must create a new {{glossary("stacking context")}}. -{{EmbedInteractiveExample("pages/css/isolation.html")}} +{{InteractiveExample("CSS Demo: isolation")}} + +```css interactive-example-choice +isolation: auto; +``` + +```css interactive-example-choice +isolation: isolate; +``` + +```html interactive-example +<section class="default-example" id="default-example"> + <div class="background-container"> + <div id="example-element"> + <img src="/shared-assets/images/examples/firefox-logo.svg" /> + <p><code>mix-blend-mode: multiply;</code></p> + </div> + </div> +</section> +``` + +```css interactive-example +.background-container { + background-color: #f4f460; + width: 250px; +} + +#example-element { + border: 1px solid black; + margin: 2em; +} + +#example-element * { + mix-blend-mode: multiply; + color: #8245a3; +} +``` This property is especially helpful when used in conjunction with {{cssxref("mix-blend-mode")}} and {{cssxref("z-index")}}. diff --git a/files/en-us/web/css/justify-content/index.md b/files/en-us/web/css/justify-content/index.md index b08e4e2c99eaa61..4ac003919010ed8 100644 --- a/files/en-us/web/css/justify-content/index.md +++ b/files/en-us/web/css/justify-content/index.md @@ -11,7 +11,55 @@ The [CSS](/en-US/docs/Web/CSS) **`justify-content`** property defines how the br The interactive example below demonstrates some `justify-content` values using grid layout. -{{EmbedInteractiveExample("pages/css/justify-content.html")}} +{{InteractiveExample("CSS Demo: justify-content")}} + +```css interactive-example-choice +justify-content: start; +``` + +```css interactive-example-choice +justify-content: center; +``` + +```css interactive-example-choice +justify-content: space-between; +``` + +```css interactive-example-choice +justify-content: space-around; +``` + +```css interactive-example-choice +justify-content: space-evenly; +``` + +```html interactive-example +<section class="default-example" id="default-example"> + <div class="example-container"> + <div class="transition-all" id="example-element"> + <div>One</div> + <div>Two</div> + <div>Three</div> + </div> + </div> +</section> +``` + +```css interactive-example +#example-element { + border: 1px solid #c5c5c5; + width: 220px; + display: grid; + grid-template-columns: 60px 60px; + grid-auto-rows: 40px; + row-gap: 10px; +} + +#example-element > div { + background-color: rgba(0, 0, 255, 0.2); + border: 3px solid blue; +} +``` ## Syntax @@ -34,7 +82,7 @@ justify-content: space-around; justify-content: space-evenly; justify-content: stretch; -/* Overflow alignment */ +/* Overflow alignment (for positional alignment only)*/ justify-content: safe center; justify-content: unsafe center; diff --git a/files/en-us/web/css/justify-items/index.md b/files/en-us/web/css/justify-items/index.md index 300a6818909742e..a06012f79a57e44 100644 --- a/files/en-us/web/css/justify-items/index.md +++ b/files/en-us/web/css/justify-items/index.md @@ -9,15 +9,59 @@ browser-compat: css.properties.justify-items The [CSS](/en-US/docs/Web/CSS) **`justify-items`** property defines the default {{CSSxRef("justify-self")}} for all items of the box, giving them all a default way of justifying each box along the appropriate axis. -{{EmbedInteractiveExample("pages/css/justify-items.html")}} +{{InteractiveExample("CSS Demo: justify-items")}} + +```css interactive-example-choice +justify-items: stretch; +``` + +```css interactive-example-choice +justify-items: center; +``` + +```css interactive-example-choice +justify-items: start; +``` + +```css interactive-example-choice +justify-items: end; +``` + +```html interactive-example +<section class="default-example" id="default-example"> + <div class="example-container"> + <div class="transition-all" id="example-element"> + <div>One</div> + <div>Two</div> + <div>Three</div> + </div> + </div> +</section> +``` + +```css interactive-example +#example-element { + border: 1px solid #c5c5c5; + display: grid; + grid-template-columns: 1fr 1fr; + grid-auto-rows: 40px; + grid-gap: 10px; + width: 220px; +} + +#example-element > div { + background-color: rgba(0, 0, 255, 0.2); + border: 3px solid blue; +} +``` The effect of this property is dependent of the layout mode we are in: - In block-level layouts, it aligns the items inside their containing block on the inline axis. - For absolutely-positioned elements, it aligns the items inside their containing block on the inline axis, accounting for the offset values of top, left, bottom, and right. -- In table cell layouts, this property is _ignored_ ([more](/en-US/docs/Web/CSS/CSS_box_alignment/Box_alignment_in_block_abspos_tables) about alignment in block, absolute positioned and table layout) -- In flexbox layouts, this property is _ignored_ ([more](/en-US/docs/Web/CSS/CSS_box_alignment/Box_alignment_in_flexbox) about alignment in flexbox) -- In grid layouts, it aligns the items inside their grid areas on the inline axis ([more](/en-US/docs/Web/CSS/CSS_box_alignment/Box_alignment_in_grid_layout) about alignment in grid layouts) +- In table cell layouts, this property is _ignored_ (see [Box alignment for block, absolutely positioned, and table layouts](/en-US/docs/Web/CSS/CSS_box_alignment/Box_alignment_in_block_abspos_tables)) +- In flexbox layouts, this property is _ignored_ (see [Box alignment in flexbox](/en-US/docs/Web/CSS/CSS_box_alignment/Box_alignment_in_flexbox)) +- In grid layouts, it aligns the items inside their grid areas on the inline axis (see [Box alignment in grid layout](/en-US/docs/Web/CSS/CSS_box_alignment/Box_alignment_in_grid_layout)) ## Syntax @@ -120,7 +164,7 @@ This property can take one of four different forms: ### Basic demonstration -In the following example, we have a simple 2 x 2 grid layout. Initially the grid container is given a `justify-items` value of `stretch` (the default), which causes the grid items to stretch across the entire width of their cells. +In this example, we have a 2 x 2 grid layout. Initially the grid container is given a `justify-items` value of `stretch` (the default), which causes the grid items to stretch across the entire width of their cells. If you hover or tab onto the grid container however, it is given a `justify-items` value of `center`, which causes the grid items to span only as wide as their content width, and align in the center of their cells. diff --git a/files/en-us/web/css/justify-self/index.md b/files/en-us/web/css/justify-self/index.md index 8e12d60e9a6e0c9..7c0efe6ebbbe9aa 100644 --- a/files/en-us/web/css/justify-self/index.md +++ b/files/en-us/web/css/justify-self/index.md @@ -9,7 +9,49 @@ browser-compat: css.properties.justify-self The [CSS](/en-US/docs/Web/CSS) **`justify-self`** property sets the way a box is justified inside its alignment container along the appropriate axis. -{{EmbedInteractiveExample("pages/css/justify-self.html")}} +{{InteractiveExample("CSS Demo: justify-self")}} + +```css interactive-example-choice +justify-self: stretch; +``` + +```css interactive-example-choice +justify-self: center; +``` + +```css interactive-example-choice +justify-self: start; +``` + +```css interactive-example-choice +justify-self: end; +``` + +```html interactive-example +<section class="default-example" id="default-example"> + <div class="example-container"> + <div class="transition-all" id="example-element">One</div> + <div>Two</div> + <div>Three</div> + </div> +</section> +``` + +```css interactive-example +.example-container { + border: 1px solid #c5c5c5; + display: grid; + width: 220px; + grid-template-columns: 1fr 1fr; + grid-auto-rows: 40px; + grid-gap: 10px; +} + +.example-container > div { + background-color: rgba(0, 0, 255, 0.2); + border: 3px solid blue; +} +``` The effect of this property is dependent of the layout mode we are in: @@ -121,7 +163,7 @@ This property can take one of three different forms: ### Basic demonstration -In the following example we have a simple 2 x 2 grid layout. Initially the grid container is given a `justify-items` value of `stretch` — the default — which causes the grid items to stretch across the entire width of their cells. +In the following example we have a 2 x 2 grid layout. Initially the grid container is given a `justify-items` value of `stretch` — the default — which causes the grid items to stretch across the entire width of their cells. The second, third, and fourth grid items are then given different values of `justify-self`, to show how these override the `justify-items` value. These values cause the grid items to span only as wide as their content width, and align in different positions across their cells. diff --git a/files/en-us/web/css/layout_cookbook/breadcrumb_navigation/index.md b/files/en-us/web/css/layout_cookbook/breadcrumb_navigation/index.md index c106bf4471f5219..f61f329e5bdbfcf 100644 --- a/files/en-us/web/css/layout_cookbook/breadcrumb_navigation/index.md +++ b/files/en-us/web/css/layout_cookbook/breadcrumb_navigation/index.md @@ -74,9 +74,9 @@ To display list items inline, we use [flexbox layout](/en-US/docs/Learn_web_deve ## Accessibility concerns -We used the [`aria-label`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-label) and [`aria-current`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-current) attributes to help assistive technology users understand what this navigation is and where the current page is in the structure. See the related links for more information. +We used the [`aria-label`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-label) and [`aria-current`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-current) attributes to help assistive technology users understand what this navigation is and where the current page is in the structure. See the related links for more information. -Be aware that the separator arrows `→` added via the {{cssxref("content")}} CSS property in the example above are exposed to assistive technologies (AT), including screen readers and braille displays. For a quieter solution, use a decorative {{HTMLElement("img")}} in your HTML with an empty `alt` attribute. An ARIA [`role`](/en-US/docs/Web/Accessibility/ARIA/Roles) set to [`none`](/en-US/docs/Web/Accessibility/ARIA/Roles/none_role) or [`presentation`](/en-US/docs/Web/Accessibility/ARIA/Roles/presentation_role) will also prevent the image from being exposed to AT. +Be aware that the separator arrows `→` added via the {{cssxref("content")}} CSS property in the example above are exposed to assistive technologies (AT), including screen readers and braille displays. For a quieter solution, use a decorative {{HTMLElement("img")}} in your HTML with an empty `alt` attribute. An ARIA [`role`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles) set to [`none`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/none_role) or [`presentation`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/presentation_role) will also prevent the image from being exposed to AT. Alternatively, silence the [CSS generated content](/en-US/docs/Web/CSS/CSS_generated_content) by including an empty string as alternative text, preceded by a slash (`/`); for example, `content: url("arrow.png") / "";`. diff --git a/files/en-us/web/css/layout_cookbook/center_an_element/index.md b/files/en-us/web/css/layout_cookbook/center_an_element/index.md index 46b1a8269eb4feb..0fee9196e41b88b 100644 --- a/files/en-us/web/css/layout_cookbook/center_an_element/index.md +++ b/files/en-us/web/css/layout_cookbook/center_an_element/index.md @@ -6,7 +6,7 @@ page-type: guide {{CSSRef}} -In this recipe, you will see how to center one box inside another by using [flexbox](#using_flexbox) and [grid](#using_grid). Centering both horizontally and vertically is simple and straightforward. +In this recipe, you will see how to center one box inside another by using [flexbox](#using_flexbox) and [grid](#using_grid), centering content both horizontally and vertically. ![an element centered inside a larger box](cookbook-center.png) diff --git a/files/en-us/web/css/layout_cookbook/contribute_a_recipe/cookbook_template/index.md b/files/en-us/web/css/layout_cookbook/contribute_a_recipe/cookbook_template/index.md index 81fe2a8fc731e29..2c8f1ce9105546c 100644 --- a/files/en-us/web/css/layout_cookbook/contribute_a_recipe/cookbook_template/index.md +++ b/files/en-us/web/css/layout_cookbook/contribute_a_recipe/cookbook_template/index.md @@ -62,6 +62,6 @@ _Include this is there are any specific things to watch out for in regard to acc ## See also -- _Links of link of related properties: {{Cssxref("example-property")}}_ +- _Links of link of related properties: `example-property`_ - _Links to article showing how to use the property in context: "Using … article"_ - _Very good external links. Don't be afraid of external links, but they should be outstanding, and not only mention minor details._ diff --git a/files/en-us/web/css/layout_cookbook/contribute_a_recipe/index.md b/files/en-us/web/css/layout_cookbook/contribute_a_recipe/index.md index 65aa40516f4f99e..7a0b9c8a947b177 100644 --- a/files/en-us/web/css/layout_cookbook/contribute_a_recipe/index.md +++ b/files/en-us/web/css/layout_cookbook/contribute_a_recipe/index.md @@ -59,7 +59,7 @@ The important parts of this template are as follows: - The editable CSS from the second `<head>` block must also be copied into the `playable-css` section. -A simple working example is [center.html](https://github.com/mdn/css-examples/blob/main/css-cookbook/center.html), which is embedded on the page [Center an element](/en-US/docs/Web/CSS/Layout_cookbook/Center_an_element). You can use this to see how to add the various bits correctly. +A working example is [center.html](https://github.com/mdn/css-examples/blob/main/css-cookbook/center.html), which is embedded on the page [Center an element](/en-US/docs/Web/CSS/Layout_cookbook/Center_an_element). You can use this to see how to add the various bits correctly. If you've forked the repo and have our CSS and JavaScript files with your example, opening your live example in a browser should display everything working exactly as it would appear on an MDN page. diff --git a/files/en-us/web/css/layout_cookbook/index.md b/files/en-us/web/css/layout_cookbook/index.md index aaaadc5ee0ce7bb..eb74008043563a8 100644 --- a/files/en-us/web/css/layout_cookbook/index.md +++ b/files/en-us/web/css/layout_cookbook/index.md @@ -13,18 +13,18 @@ The CSS layout cookbook aims to bring together recipes for common layout pattern ## The Recipes -| Recipe | Description | Layout Methods | -| ------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------ | -| [Media objects](/en-US/docs/Web/CSS/Layout_cookbook/Media_objects) | A two-column box with an image on one side and descriptive text on the other, e.g. a facebook post or tweet. | [CSS grid](/en-US/docs/Web/CSS/CSS_grid_layout), {{cssxref("float")}} fallback, {{cssxref("fit-content")}} sizing | -| [Columns](/en-US/docs/Web/CSS/Layout_cookbook/Column_layouts) | When to choose multi-column layout, flexbox or grid for your columns. | [CSS grid](/en-US/docs/Web/CSS/CSS_grid_layout), [Multicol](/en-US/docs/Web/CSS/CSS_multicol_layout), [Flexbox](/en-US/docs/Web/CSS/CSS_flexible_box_layout) | -| [Center an element](/en-US/docs/Web/CSS/Layout_cookbook/Center_an_element) | How to center an item horizontally and vertically. | [Flexbox](/en-US/docs/Web/CSS/CSS_flexible_box_layout), [Box Alignment](/en-US/docs/Web/CSS/CSS_box_alignment) | -| [Sticky footers](/en-US/docs/Web/CSS/Layout_cookbook/Sticky_footers) | Creating a footer which sits at the bottom of the container or viewport when the content is shorter. | [CSS grid](/en-US/docs/Web/CSS/CSS_grid_layout), [Flexbox](/en-US/docs/Web/CSS/CSS_flexible_box_layout) | -| [Split navigation](/en-US/docs/Web/CSS/Layout_cookbook/Split_Navigation) | A navigation pattern where some links are visually separated from the others. | [Flexbox](/en-US/docs/Web/CSS/CSS_flexible_box_layout), {{cssxref("margin")}} | -| [Breadcrumb navigation](/en-US/docs/Web/CSS/Layout_cookbook/Breadcrumb_Navigation) | Creating a list of links to allow the visitor to navigate back up through the page hierarchy. | [Flexbox](/en-US/docs/Web/CSS/CSS_flexible_box_layout) | -| [List group with badges](/en-US/docs/Web/CSS/Layout_cookbook/List_group_with_badges) | A list of items with a badge to display a count. | [Flexbox](/en-US/docs/Web/CSS/CSS_flexible_box_layout), [Box Alignment](/en-US/docs/Web/CSS/CSS_box_alignment) | -| [Pagination](/en-US/docs/Web/CSS/Layout_cookbook/Pagination) | Links to pages of content (such as search results). | [Flexbox](/en-US/docs/Web/CSS/CSS_flexible_box_layout), [Box Alignment](/en-US/docs/Web/CSS/CSS_box_alignment) | -| [Card](/en-US/docs/Web/CSS/Layout_cookbook/Card) | A card component, which displays in a grid of cards. | [Grid Layout](/en-US/docs/Web/CSS/CSS_grid_layout) | -| [Grid wrapper](/en-US/docs/Web/CSS/Layout_cookbook/Grid_wrapper) | For aligning grid content within a central wrapper, while also allowing items to break out. | [CSS grid](/en-US/docs/Web/CSS/CSS_grid_layout) | +| Recipe | Description | Layout Methods | +| ------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ | +| [Media objects](/en-US/docs/Web/CSS/Layout_cookbook/Media_objects) | A two-column box with an image on one side and descriptive text on the other, e.g., a facebook post or tweet. | [CSS grid](/en-US/docs/Web/CSS/CSS_grid_layout), {{cssxref("float")}} fallback, {{cssxref("fit-content")}} sizing | +| [Columns](/en-US/docs/Web/CSS/Layout_cookbook/Column_layouts) | When to choose multi-column layout, flexbox or grid for your columns. | [CSS grid](/en-US/docs/Web/CSS/CSS_grid_layout), [Multicol](/en-US/docs/Web/CSS/CSS_multicol_layout), [Flexbox](/en-US/docs/Web/CSS/CSS_flexible_box_layout) | +| [Center an element](/en-US/docs/Web/CSS/Layout_cookbook/Center_an_element) | How to center an item horizontally and vertically. | [Flexbox](/en-US/docs/Web/CSS/CSS_flexible_box_layout), [Box Alignment](/en-US/docs/Web/CSS/CSS_box_alignment) | +| [Sticky footers](/en-US/docs/Web/CSS/Layout_cookbook/Sticky_footers) | Creating a footer which sits at the bottom of the container or viewport when the content is shorter. | [CSS grid](/en-US/docs/Web/CSS/CSS_grid_layout), [Flexbox](/en-US/docs/Web/CSS/CSS_flexible_box_layout) | +| [Split navigation](/en-US/docs/Web/CSS/Layout_cookbook/Split_Navigation) | A navigation pattern where some links are visually separated from the others. | [Flexbox](/en-US/docs/Web/CSS/CSS_flexible_box_layout), {{cssxref("margin")}} | +| [Breadcrumb navigation](/en-US/docs/Web/CSS/Layout_cookbook/Breadcrumb_Navigation) | Creating a list of links to allow the visitor to navigate back up through the page hierarchy. | [Flexbox](/en-US/docs/Web/CSS/CSS_flexible_box_layout) | +| [List group with badges](/en-US/docs/Web/CSS/Layout_cookbook/List_group_with_badges) | A list of items with a badge to display a count. | [Flexbox](/en-US/docs/Web/CSS/CSS_flexible_box_layout), [Box Alignment](/en-US/docs/Web/CSS/CSS_box_alignment) | +| [Pagination](/en-US/docs/Web/CSS/Layout_cookbook/Pagination) | Links to pages of content (such as search results). | [Flexbox](/en-US/docs/Web/CSS/CSS_flexible_box_layout), [Box Alignment](/en-US/docs/Web/CSS/CSS_box_alignment) | +| [Card](/en-US/docs/Web/CSS/Layout_cookbook/Card) | A card component, which displays in a grid of cards. | [Grid Layout](/en-US/docs/Web/CSS/CSS_grid_layout) | +| [Grid wrapper](/en-US/docs/Web/CSS/Layout_cookbook/Grid_wrapper) | For aligning grid content within a central wrapper, while also allowing items to break out. | [CSS grid](/en-US/docs/Web/CSS/CSS_grid_layout) | ## Contribute a Recipe diff --git a/files/en-us/web/css/layout_cookbook/media_objects/index.md b/files/en-us/web/css/layout_cookbook/media_objects/index.md index 92c082ba8a3f781..62c7c9cf2361e5b 100644 --- a/files/en-us/web/css/layout_cookbook/media_objects/index.md +++ b/files/en-us/web/css/layout_cookbook/media_objects/index.md @@ -6,7 +6,7 @@ page-type: guide {{CSSRef}} -The _Media Object_ is a pattern we see all over the web. It refers to a two-column box with an image on one side and descriptive text on the other, e.g. a social media post. +The _Media Object_ is a pattern we see all over the web. It refers to a two-column box with an image on one side and descriptive text on the other, e.g., a social media post. ![Example of a media object with profile image on the left side and lorem ipsum text to the right filling up 80% of the space](media-object.png) diff --git a/files/en-us/web/css/layout_cookbook/pagination/index.md b/files/en-us/web/css/layout_cookbook/pagination/index.md index 6c0e8fff3663c26..d6d9a2d86354d41 100644 --- a/files/en-us/web/css/layout_cookbook/pagination/index.md +++ b/files/en-us/web/css/layout_cookbook/pagination/index.md @@ -121,9 +121,9 @@ The list itself also becomes a flex container to lay the items out as a row. To ## Accessibility concerns -We want to ensure that a person using a screen reader understands what this navigation does, and where they will go when clicking a link. To help with this we have added [`aria-label="pagination"`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-label) on the `<nav>` element. +We want to ensure that a person using a screen reader understands what this navigation does, and where they will go when clicking a link. To help with this we have added [`aria-label="pagination"`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-label) on the `<nav>` element. -We have also added some additional content that would be read by a screen reader but is hidden visually, and set the [`aria-hidden`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-hidden) attribute on the paging arrows. +We have also added some additional content that would be read by a screen reader but is hidden visually, and set the [`aria-hidden`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-hidden) attribute on the paging arrows. The "See Also" section at the end of this document has links to related accessibility topics. diff --git a/files/en-us/web/css/layout_cookbook/sticky_footers/cookbook-footer.png b/files/en-us/web/css/layout_cookbook/sticky_footers/cookbook-footer.png deleted file mode 100644 index b15055923af9deb..000000000000000 Binary files a/files/en-us/web/css/layout_cookbook/sticky_footers/cookbook-footer.png and /dev/null differ diff --git a/files/en-us/web/css/layout_mode/index.md b/files/en-us/web/css/layout_mode/index.md deleted file mode 100644 index 1d5c02a179ecbbe..000000000000000 --- a/files/en-us/web/css/layout_mode/index.md +++ /dev/null @@ -1,40 +0,0 @@ ---- -title: Layout mode -slug: Web/CSS/Layout_mode -page-type: guide ---- - -{{CSSRef}} - -A [CSS](/en-US/docs/Web/CSS) **layout mode**, sometimes called _layout_, is an algorithm that determines the position and size of boxes based on the way they interact with their sibling and ancestor boxes. There are several of them: - -- _[Normal flow](/en-US/docs/Web/CSS/CSS_display/flow_layout)_ — all elements are part of normal flow until you do something to take them out of it. Normal flow includes _block layout_, designed for laying out boxes such as paragraphs and _inline layout_, which lays out inline items such as text. -- [_Table layout_](/en-US/docs/Web/CSS/CSS_table), designed for laying out tables. -- _Float layout_, designed to cause an item to position itself left or right with the rest of the content in normal flow wrapping around it. -- [_Positioned layout_](/en-US/docs/Web/CSS/CSS_positioned_layout), designed for positioning elements without much interaction with other elements. -- [_Multi-column layout_](/en-US/docs/Web/CSS/CSS_multicol_layout), designed for laying content out in columns as in a newspaper. -- [_Flexible box layout_](/en-US/docs/Web/CSS/CSS_flexible_box_layout), designed for laying out complex pages that can be resized smoothly. -- [_Grid layout_](/en-US/docs/Web/CSS/CSS_grid_layout), designed for laying out elements relative to a fixed grid. - -> [!NOTE] -> Not all [CSS properties](/en-US/docs/Web/CSS/Reference) apply to all _layout modes_. Most of them apply to one or two of them and have no effect if they are set on an element participating in another layout mode. - -## See also - -- CSS key concepts: - - [CSS syntax](/en-US/docs/Web/CSS/CSS_syntax/Syntax) - - [At-rules](/en-US/docs/Web/CSS/CSS_syntax/At-rule) - - [Comments](/en-US/docs/Web/CSS/CSS_syntax/Comments) - - [Specificity](/en-US/docs/Web/CSS/CSS_cascade/Specificity) - - [Inheritance](/en-US/docs/Web/CSS/CSS_cascade/Inheritance) - - [Box model](/en-US/docs/Web/CSS/CSS_box_model/Introduction_to_the_CSS_box_model) - - [Visual formatting model](/en-US/docs/Web/CSS/Visual_formatting_model) - - [Margin collapsing](/en-US/docs/Web/CSS/CSS_box_model/Mastering_margin_collapsing) - - Values - - [Initial values](/en-US/docs/Web/CSS/CSS_cascade/initial_value) - - [Computed values](/en-US/docs/Web/CSS/CSS_cascade/computed_value) - - [Used values](/en-US/docs/Web/CSS/CSS_cascade/used_value) - - [Actual values](/en-US/docs/Web/CSS/CSS_cascade/actual_value) - - [Value definition syntax](/en-US/docs/Web/CSS/CSS_Values_and_Units/Value_definition_syntax) - - [Shorthand properties](/en-US/docs/Web/CSS/CSS_cascade/Shorthand_properties) - - [Replaced elements](/en-US/docs/Web/CSS/Replaced_element) diff --git a/files/en-us/web/css/left/index.md b/files/en-us/web/css/left/index.md index 51667850653f6ce..439feb22a31e3ba 100644 --- a/files/en-us/web/css/left/index.md +++ b/files/en-us/web/css/left/index.md @@ -9,7 +9,57 @@ browser-compat: css.properties.left The **`left`** [CSS](/en-US/docs/Web/CSS) property participates in specifying the horizontal position of a [positioned element](/en-US/docs/Web/CSS/position). This {{glossary("inset properties", "inset property")}} has no effect on non-positioned elements. -{{EmbedInteractiveExample("pages/css/left.html")}} +{{InteractiveExample("CSS Demo: left")}} + +```css interactive-example-choice +left: 0; +``` + +```css interactive-example-choice +left: 4em; +``` + +```css interactive-example-choice +left: 10%; +``` + +```css interactive-example-choice +left: 20px; +``` + +```html interactive-example +<section id="default-example"> + <div class="example-container"> + <div id="example-element">I am absolutely positioned.</div> + <p> + As much mud in the streets as if the waters had but newly retired from the + face of the earth, and it would not be wonderful to meet a Megalosaurus, + forty feet long or so, waddling like an elephantine lizard up Holborn + Hill. + </p> + </div> +</section> +``` + +```css interactive-example +.example-container { + border: 0.75em solid; + padding: 0.75em; + text-align: left; + position: relative; + width: 100%; + min-height: 200px; +} + +#example-element { + background-color: #264653; + border: 4px solid #ffb500; + color: white; + position: absolute; + width: 140px; + height: 60px; +} +``` ## Syntax @@ -53,9 +103,6 @@ left: unset; - for _absolutely positioned elements_, the position of the element is based on the {{Cssxref("right")}} property, while `width: auto` is treated as a width based on the content; or if `right` is also `auto`, the element is positioned where it should horizontally be positioned if it were a static element. - for _relatively positioned elements_, the distance of the element from its normal position is based on the {{Cssxref("right")}} property; or if `right` is also `auto`, the element is not moved horizontally at all. -- `inherit` - - : Specifies that the value is the same as the computed value from its parent element (which might not be its containing block). This computed value is then handled as if it were a {{cssxref("&lt;length&gt;")}}, {{cssxref("&lt;percentage&gt;")}}, or the `auto` keyword. - ## Description The effect of `left` depends on how the element is positioned (i.e., the value of the {{cssxref("position")}} property): @@ -145,8 +192,6 @@ When both `left` and {{cssxref("right")}} are defined, and width constraints don } pre { - white-space: pre; - white-space: pre-wrap; white-space: pre-line; word-wrap: break-word; } diff --git a/files/en-us/web/css/length-percentage/index.md b/files/en-us/web/css/length-percentage/index.md index e2ef8d9be374f2f..34cd5e34c5540af 100644 --- a/files/en-us/web/css/length-percentage/index.md +++ b/files/en-us/web/css/length-percentage/index.md @@ -21,7 +21,7 @@ Refer to the documentation for {{Cssxref("length")}} and {{Cssxref("percentage") ### length-percentage examples -The following simple example demonstrates several properties that use `<length-percentage>` values. +This example demonstrates several properties that use `<length-percentage>` values. #### HTML diff --git a/files/en-us/web/css/length/index.md b/files/en-us/web/css/length/index.md index 7b2eac6d1f6b468..f8d67c14ce1fff6 100644 --- a/files/en-us/web/css/length/index.md +++ b/files/en-us/web/css/length/index.md @@ -19,7 +19,7 @@ The `<length>` data type consists of a {{cssxref("&lt;number&gt;")}} followed by > [!NOTE] > Some properties allow negative `<length>` values, while others do not. -The [specified value](/en-US/docs/Web/CSS/CSS_cascade/specified_value) of a length (_specified length_) is represented by its quantity and unit. The [computed value](/en-US/docs/Web/CSS/CSS_cascade/computed_value) of a length (_computed length_) is the specified length resolved to an absolute length, and its unit is not distinguished. +The [specified value](/en-US/docs/Web/CSS/CSS_cascade/Value_processing#specified_value) of a length (_specified length_) is represented by its quantity and unit. The [computed value](/en-US/docs/Web/CSS/CSS_cascade/Value_processing#computed_value) of a length (_computed length_) is the specified length resolved to an absolute length, and its unit is not distinguished. The `<length>` units can be relative or absolute. Relative lengths represent a measurement in terms of some other distance. Depending on the unit, this distance can be the size of a specific character, the [line height](/en-US/docs/Web/CSS/line-height), or the size of the {{Glossary("viewport")}}. Style sheets that use relative length units can more easily scale from one output environment to another. @@ -102,7 +102,7 @@ The **viewport-percentage length units** are based on four different viewport si - : The default viewport size is defined by the browser. The behavior of the resulting viewport-percentage unit could be equivalent to the viewport-percentage unit based on the small viewport size, the large viewport size, an intermediate size between the two, or the dynamic viewport size. > [!NOTE] - > For example, a browser might implement the default viewport-percentage unit for height (`vh`) that is equivalent to the large viewport-percentage height unit (`lvh`). If so, this could obscure content on a full-page display while the browser interface is expanded. + > For example, a browser might implement the default viewport-percentage unit for height (`vh`) that is equivalent to the large viewport-percentage height unit (`lvh`). If so, this could obscure content on a full-page display while the browser interface is expanded. Currently, all default viewport units (`vh`, `vw`, etc.) are equivalent to their large viewport counterparts (`lvh`, `lvw`, etc.). Viewport-percentage lengths define `<length>` values in percentage relative to the size of the initial [containing block](/en-US/docs/Web/CSS/CSS_display/Containing_block), which in turn is based on either the size of the {{Glossary("viewport")}} or the page area, i.e., the visible portion of the document. When the height or width of the initial containing block is changed, the elements that are sized based on them are scaled accordingly. There is a viewport-percentage length unit variant corresponding to each of the viewport sizes, as described below. @@ -113,48 +113,51 @@ Viewport-percentage lengths define `<length>` values in percentage relative to t - : Represents a percentage of the height of the viewport's initial [containing block](/en-US/docs/Web/CSS/CSS_display/Containing_block). `1vh` is 1% of the viewport height. For example, if the viewport height is `300px`, then a value of `70vh` on a property will be `210px`. - The respective viewport-percentage units for small, large, and dynamic viewport sizes are `svh`, `lvh`, and `dvh`. `vh` represents the viewport-percentage length unit based on the browser's default viewport size. + The respective viewport-percentage units for small, large, and dynamic viewport sizes are `svh`, `lvh`, and `dvh`. `vh` is equivalent to `lvh`, representing the viewport-percentage length unit based on the large viewport size. - `vw` - : Represents a percentage of the width of the viewport's initial [containing block](/en-US/docs/Web/CSS/CSS_display/Containing_block). `1vw` is 1% of the viewport width. For example, if the viewport width is `800px`, then a value of `50vw` on a property will be `400px`. For small, large, and dynamic viewport sizes, the respective viewport-percentage units are `svw`, `lvw`, and `dvw`. - `vw` represents the viewport-percentage length unit based on the browser's default viewport size. + `vw` is equivalent to `lvw`, representing the viewport-percentage length unit based on the large viewport size. - `vmax` - : Represents in percentage the largest of `vw` and `vh`. For small, large, and dynamic viewport sizes, the respective viewport-percentage units are `svmax`, `lvmax`, and `dvmax`. - `vmax` represents the viewport-percentage length unit based on the browser's default viewport size. + `vmax` is equivalent to `lvmax`, representing the viewport-percentage length unit based on the large viewport size. - `vmin` - : Represents in percentage the smallest of `vw` and `vh`. For small, large, and dynamic viewport sizes, the respective viewport-percentage units are `svmin`, `lvmin`, and `dvmin`. - `vmin` represents the viewport-percentage length unit based on the browser's default viewport size. + `vmin` is equivalent to `lvmin`, representing the viewport-percentage length unit based on the large viewport size. - `vb` - : Represents the percentage of the size of the initial [containing block](/en-US/docs/Web/CSS/CSS_display/Containing_block), in the direction of the root element's [block axis](/en-US/docs/Web/CSS/CSS_logical_properties_and_values). For small, large, and dynamic viewport sizes, the respective viewport-percentage units are `svb`, `lvb`, and `dvb`, respectively. - `vb` represents the viewport-percentage length unit based on the browser's default viewport size. + `vb` is equivalent to `lvb`, representing the viewport-percentage length unit based on the large viewport size. - `vi` - : Represents a percentage of the size of the initial [containing block](/en-US/docs/Web/CSS/CSS_display/Containing_block), in the direction of the root element's [inline axis](/en-US/docs/Web/CSS/CSS_logical_properties_and_values). For small, large, and dynamic viewport sizes, the respective viewport-percentage units are `svi`, `lvi`, and `dvi`. - `vi` represents the viewport-percentage length unit based on the browser's default viewport size. + `vi` is equivalent to `lvi`, representing the viewport-percentage length unit based on the large viewport size. ### Container query length units When applying styles to a container using container queries, you can use container query length units. These units specify a length relative to the dimensions of a query container. Components that use units of length relative to their container are more flexible to use in different containers without having to recalculate concrete length values. + +If no eligible container is available for the query, the container query length unit defaults to the [small viewport unit](#small_viewport_units) for that axis (`sv*`). + For more information, see [Container queries](/en-US/docs/Web/CSS/CSS_containment/Container_queries). - `cqw` @@ -215,7 +218,7 @@ When animated, values of the `<length>` data type are interpolated as real, floa ### Comparing different length units -The following example provides you with an input field in which you can enter a `<length>` value (e.g. `300px`, `50%`, `30vw`) to set the width of a result bar that will appear below it once you've pressed the <kbd>Enter</kbd> or the <kbd>Return</kbd> key. +The following example provides you with an input field in which you can enter a `<length>` value (e.g., `300px`, `50%`, `30vw`) to set the width of a result bar that will appear below it once you've pressed the <kbd>Enter</kbd> or the <kbd>Return</kbd> key. This allows you to compare and contrast the effects of different length units. diff --git a/files/en-us/web/css/letter-spacing/index.md b/files/en-us/web/css/letter-spacing/index.md index 80e677161329c4a..6964e9b75871038 100644 --- a/files/en-us/web/css/letter-spacing/index.md +++ b/files/en-us/web/css/letter-spacing/index.md @@ -9,7 +9,46 @@ browser-compat: css.properties.letter-spacing The **`letter-spacing`** [CSS](/en-US/docs/Web/CSS) property sets the horizontal spacing behavior between text characters. This value is added to the natural spacing between characters while rendering the text. Positive values of `letter-spacing` causes characters to spread farther apart, while negative values of `letter-spacing` bring characters closer together. -{{EmbedInteractiveExample("pages/css/letter-spacing.html")}} +{{InteractiveExample("CSS Demo: letter-spacing")}} + +```css interactive-example-choice +letter-spacing: normal; +``` + +```css interactive-example-choice +letter-spacing: 0.2rem; +``` + +```css interactive-example-choice +letter-spacing: 1px; +``` + +```css interactive-example-choice +letter-spacing: -1px; +``` + +```html interactive-example +<section id="default-example"> + <p id="example-element"> + As much mud in the streets as if the waters had but newly retired from the + face of the earth, and it would not be wonderful to meet a Megalosaurus, + forty feet long or so, waddling like an elephantine lizard up Holborn Hill. + </p> +</section> +``` + +```css interactive-example +@font-face { + src: url("/shared-assets/fonts/variable-fonts/AmstelvarAlpha-VF.ttf"); + font-family: Amstelvar; + font-style: normal; +} + +section { + font-size: 1.2em; + font-family: Amstelvar; +} +``` ## Syntax @@ -43,7 +82,7 @@ A large positive or negative `letter-spacing` value will make the word(s) the st Legible letter-spacing must be determined on a case-by-case basis, as different font families have different character widths. There is no one value that can ensure all font families automatically maintain their legibility. -- [MDN Understanding WCAG, Guideline 1.4 explanations](/en-US/docs/Web/Accessibility/Understanding_WCAG/Perceivable#guideline_1.4_make_it_easier_for_users_to_see_and_hear_content_including_separating_foreground_from_background) +- [MDN Understanding WCAG, Guideline 1.4 explanations](/en-US/docs/Web/Accessibility/Guides/Understanding_WCAG/Perceivable#guideline_1.4_make_it_easier_for_users_to_see_and_hear_content_including_separating_foreground_from_background) - [Understanding Success Criterion 1.4.8 | W3C Understanding WCAG 2.0](https://www.w3.org/TR/UNDERSTANDING-WCAG20/visual-audio-contrast-visual-presentation.html) ## Internationalization concerns diff --git a/files/en-us/web/css/line-break/index.md b/files/en-us/web/css/line-break/index.md index 55b807f17e94290..2fc164728117201 100644 --- a/files/en-us/web/css/line-break/index.md +++ b/files/en-us/web/css/line-break/index.md @@ -9,7 +9,41 @@ browser-compat: css.properties.line-break The **`line-break`** [CSS](/en-US/docs/Web/CSS) property sets how to break lines of Chinese, Japanese, or Korean (CJK) text when working with punctuation and symbols. -{{EmbedInteractiveExample("pages/css/line-break.html")}} +{{InteractiveExample("CSS Demo: line-break")}} + +```css interactive-example-choice +line-break: auto; +``` + +```css interactive-example-choice +line-break: anywhere; +``` + +```css interactive-example-choice +line-break: normal; +``` + +```css interactive-example-choice +line-break: loose; +``` + +```html interactive-example +<section id="default-example"> + <p id="example-element"> + この喫茶店は、いつでもコーヒーの香りを漂わせています。<br />彼女はこの喫茶店で働いて、着々と実力をつけていきました。<br />今では知る人ぞ知る、名人です。 + </p> +</section> +``` + +```css interactive-example +#example-element { + font-family: "Yu Gothic", YuGothic, Meiryo, "MS ゴシック", sans-serif; + border: 2px dashed #999; + text-align: left; + width: 240px; + font-size: 16px; +} +``` ## Syntax diff --git a/files/en-us/web/css/line-height/index.md b/files/en-us/web/css/line-height/index.md index 3a1687483a975e8..8529e04ef0a9d2f 100644 --- a/files/en-us/web/css/line-height/index.md +++ b/files/en-us/web/css/line-height/index.md @@ -7,9 +7,45 @@ browser-compat: css.properties.line-height {{CSSRef}} -The **`line-height`** [CSS](/en-US/docs/Web/CSS) property sets the height of a line box in horizontal [writing modes](/en-US/docs/Web/CSS/writing-mode#vertical-rl). In vertical writing modes, it sets the width of a line box. It's commonly used to set the distance between lines of text. On block-level elements in horizontal writing modes, it specifies the preferred height of line boxes within the element, and on non-[replaced](/en-US/docs/Web/CSS/Replaced_element) inline elements, it specifies the height that is used to calculate line box height. +The **`line-height`** [CSS](/en-US/docs/Web/CSS) property sets the height of a line box in horizontal [writing modes](/en-US/docs/Web/CSS/writing-mode#vertical-rl). In vertical writing modes, it sets the width of a line box. It's commonly used to set the distance between lines of text. On block-level elements in horizontal writing modes, it specifies the preferred height of line boxes within the element, and on non-[replaced](/en-US/docs/Glossary/Replaced_elements) inline elements, it specifies the height that is used to calculate line box height. -{{EmbedInteractiveExample("pages/css/line-height.html")}} +{{InteractiveExample("CSS Demo: line-height")}} + +```css interactive-example-choice +line-height: normal; +``` + +```css interactive-example-choice +line-height: 2.5; +``` + +```css interactive-example-choice +line-height: 3em; +``` + +```css interactive-example-choice +line-height: 150%; +``` + +```css interactive-example-choice +line-height: 32px; +``` + +```html interactive-example +<section id="default-example"> + <div class="transition-all" id="example-element"> + Far out in the uncharted backwaters of the unfashionable end of the western + spiral arm of the Galaxy lies a small unregarded yellow sun. + </div> +</section> +``` + +```css interactive-example +#example-element { + font-family: Georgia, sans-serif; + max-width: 200px; +} +``` ## Syntax diff --git a/files/en-us/web/css/line-style/index.md b/files/en-us/web/css/line-style/index.md index ec43db8120bdca9..b297d199a1ae0b4 100644 --- a/files/en-us/web/css/line-style/index.md +++ b/files/en-us/web/css/line-style/index.md @@ -70,8 +70,8 @@ This example shows all the `<line-style>` values as values for the CSS {{cssxref This example uses multiple {{HTMLElement( "div" )}} elements, each with a class representing the `<line-style>` value that is being demonstrated. ```html -<div class="<line-style>"> - <p><line-style></p> +<div class="{line-style}"> + <p>{line-style}</p> <p>a b c d e f g h i j k l m n o p q r s t u v w x y z</p> </div> ``` @@ -210,39 +210,37 @@ This example demonstrates line-style and color choice. With some `<line-style>` #### HTML -This example uses multiple {{HTMLElement( "div" )}} elements, each with a different `border-color` set as an inline [`style`](/en-US/docs/Web/HTML/Global_attributes/style). - -```html-nolint hidden -<section> -``` +This example uses multiple {{HTMLElement( "div" )}} elements, each with a different `border-color` set as an inline [`style`](/en-US/docs/Web/HTML/Reference/Global_attributes/style). ```html <div style="border-color: #000000"></div> ``` -```html hidden -<div style="border-color: #000001"></div> -<div style="border-color: #ffffff"></div> +```html hidden live-sample___line_style_colors +<section> + <div style="border-color: #000000"></div> + <div style="border-color: #000001"></div> + <div style="border-color: #ffffff"></div> -<div style="border-color: #ff00ff"></div> -<div style="border-color: #ffff00"></div> -<div style="border-color: #00ffff"></div> + <div style="border-color: #ff00ff"></div> + <div style="border-color: #ffff00"></div> + <div style="border-color: #00ffff"></div> -<div style="border-color: #cc33cc"></div> -<div style="border-color: #cccc33"></div> -<div style="border-color: #33cccc"></div> + <div style="border-color: #cc33cc"></div> + <div style="border-color: #cccc33"></div> + <div style="border-color: #33cccc"></div> -<div style="border-color: #ff0000"></div> -<div style="border-color: #00ff00"></div> -<div style="border-color: #0000ff"></div> + <div style="border-color: #ff0000"></div> + <div style="border-color: #00ff00"></div> + <div style="border-color: #0000ff"></div> -<div style="border-color: #cc3333"></div> -<div style="border-color: #33cc33"></div> -<div style="border-color: #3333cc"></div> + <div style="border-color: #cc3333"></div> + <div style="border-color: #33cc33"></div> + <div style="border-color: #3333cc"></div> -<div style="border-color: #993333"></div> -<div style="border-color: #339933"></div> -<div style="border-color: #333399"></div> + <div style="border-color: #993333"></div> + <div style="border-color: #339933"></div> + <div style="border-color: #333399"></div> </section> ``` @@ -250,7 +248,7 @@ This example uses multiple {{HTMLElement( "div" )}} elements, each with a differ The four sides of each `<div>` have a different `<line-style>` value, and each list item has a different {{cssxref("color_value", "&lt;color>")}} value. We use [generated content](/en-US/docs/Web/CSS/content) to display the CSS declared inline. -```css hidden +```css hidden live-sample___line_style_colors section { display: flex; flex-wrap: wrap; @@ -260,7 +258,7 @@ section { } ``` -```css +```css live-sample___line_style_colors div { border-width: 10px; border-style: inset groove ridge outset; @@ -273,7 +271,7 @@ div::before { #### Result -{{EmbedLiveSample("Line_style_colors", "500", "400")}} +{{EmbedLiveSample("line_style_colors", "500", "400")}} Notice that the almost-black color of `#000001` may be different from the actual black, and the contrast between the dark and light edges is more noticeable when using lighter colors. diff --git a/files/en-us/web/css/list-style-image/index.md b/files/en-us/web/css/list-style-image/index.md index 67bf485794655b1..16f50a943958220 100644 --- a/files/en-us/web/css/list-style-image/index.md +++ b/files/en-us/web/css/list-style-image/index.md @@ -11,10 +11,69 @@ The **`list-style-image`** [CSS](/en-US/docs/Web/CSS) property sets an image to It is often more convenient to use the shorthand {{ cssxref("list-style") }}. -{{EmbedInteractiveExample("pages/css/list-style-image.html")}} +{{InteractiveExample("CSS Demo: list-style-image")}} + +```css interactive-example-choice +list-style-image: url("/shared-assets/images/examples/rocket.svg"); +``` + +```css interactive-example-choice +list-style-image: none; +``` + +```html interactive-example +<section class="default-example" id="default-example"> + <div> + <p>NASA Notable Missions</p> + <ul class="transition-all unhighlighted" id="example-element"> + <li>Apollo</li> + <li>Hubble</li> + <li>Chandra</li> + <li>Cassini-Huygens</li> + <li>Spitzer</li> + </ul> + </div> +</section> +``` + +```css interactive-example +.default-example { + font-size: 1.2rem; +} + +#example-element { + width: 100%; + background: #be094b; + color: white; +} + +section { + text-align: left; + flex-direction: column; +} + +hr { + width: 50%; + color: lightgray; + margin: 0.5em; +} + +.note { + font-size: 0.8rem; +} + +.note a { + color: #009e5f; +} + +@counter-style space-counter { + symbols: "\1F680" "\1F6F8" "\1F6F0" "\1F52D"; + suffix: " "; +} +``` > [!NOTE] -> This property is applied to list items, i.e. elements with `{{cssxref("display")}}: list-item;` [by default](https://html.spec.whatwg.org/multipage/rendering.html#lists) this includes {{HTMLElement("li")}} elements. Because this property is inherited, it can be set on the parent element (normally {{HTMLElement("ol")}} or {{HTMLElement("ul")}}) to let it apply to all list items. +> This property is applied to list items, i.e., elements with `{{cssxref("display")}}: list-item;` [by default](https://html.spec.whatwg.org/multipage/rendering.html#lists) this includes {{HTMLElement("li")}} elements. Because this property is inherited, it can be set on the parent element (normally {{HTMLElement("ol")}} or {{HTMLElement("ul")}}) to let it apply to all list items. ## Syntax diff --git a/files/en-us/web/css/list-style-position/index.md b/files/en-us/web/css/list-style-position/index.md index 309c3a91f3ffbfb..056c0cb1679d09b 100644 --- a/files/en-us/web/css/list-style-position/index.md +++ b/files/en-us/web/css/list-style-position/index.md @@ -9,7 +9,65 @@ browser-compat: css.properties.list-style-position The **`list-style-position`** [CSS](/en-US/docs/Web/CSS) property sets the position of the {{cssxref("::marker")}} relative to a list item. -{{EmbedInteractiveExample("pages/css/list-style-position.html")}} +{{InteractiveExample("CSS Demo: list-style-position")}} + +```css interactive-example-choice +list-style-position: inside; +``` + +```css interactive-example-choice +list-style-position: outside; +``` + +```html interactive-example +<section class="default-example" id="default-example"> + <div> + <p>NASA Notable Missions</p> + <ul class="transition-all" id="example-element"> + <li>Apollo 11: First Human Landing</li> + <li>City in Space: The International Space Station</li> + <li>Great Observatory: The Hubble Space Telescope</li> + <li>Everlasting Mars Rovers</li> + </ul> + </div> +</section> +``` + +```css interactive-example +.default-example { + font-size: 1.2rem; +} + +#example-element { + width: 100%; + background: #be094b; + color: white; +} + +section { + text-align: left; + flex-direction: column; +} + +hr { + width: 50%; + color: lightgray; + margin: 0.5em; +} + +.note { + font-size: 0.8rem; +} + +.note a { + color: #009e5f; +} + +@counter-style space-counter { + symbols: "\1F680" "\1F6F8" "\1F6F0" "\1F52D"; + suffix: " "; +} +``` ## Syntax diff --git a/files/en-us/web/css/list-style-type/index.md b/files/en-us/web/css/list-style-type/index.md index aeaf6a2c607c4a1..430041c90dd9e18 100644 --- a/files/en-us/web/css/list-style-type/index.md +++ b/files/en-us/web/css/list-style-type/index.md @@ -9,7 +9,84 @@ browser-compat: css.properties.list-style-type The **`list-style-type`** [CSS](/en-US/docs/Web/CSS) property sets the marker (such as a disc, character, or custom counter style) of a list item element. -{{EmbedInteractiveExample("pages/css/list-style-type.html")}} +{{InteractiveExample("CSS Demo: list-style-type")}} + +```css interactive-example-choice +list-style-type: space-counter; +``` + +```css interactive-example-choice +list-style-type: disc; +``` + +```css interactive-example-choice +list-style-type: circle; +``` + +```css interactive-example-choice +list-style-type: "\1F44D"; +``` + +```html interactive-example +<section class="default-example" id="default-example"> + <div> + <p>NASA Notable Missions</p> + <ul class="transition-all unhighlighted" id="example-element"> + <li>Apollo</li> + <li>Hubble</li> + <li>Chandra</li> + <li>Cassini-Huygens</li> + </ul> + </div> + <hr /> + <div class="note"> + <p> + <code>space-counter</code> is defined with + <a + href="//developer.mozilla.org/docs/Web/CSS/@counter-style" + target="_parent" + ><code>@counter-style</code></a + > + </p> + </div> +</section> +``` + +```css interactive-example +.default-example { + font-size: 1.2rem; +} + +#example-element { + width: 100%; + background: #be094b; + color: white; +} + +section { + text-align: left; + flex-direction: column; +} + +hr { + width: 50%; + color: lightgray; + margin: 0.5em; +} + +.note { + font-size: 0.8rem; +} + +.note a { + color: #009e5f; +} + +@counter-style space-counter { + symbols: "\1F680" "\1F6F8" "\1F6F0" "\1F52D"; + suffix: " "; +} +``` The marker will be [`currentcolor`](/en-US/docs/Web/CSS/color_value#currentcolor_keyword), the same as the computed [color](/en-US/docs/Web/CSS/color_value) of the element it applies to. @@ -171,7 +248,7 @@ Note that: - `disclosure-closed` - : Symbol indicating that a disclosure widget, like {{HTMLElement("details")}} is closed. -Refer to the [All list style types](#all_list_style_types) example to see the above values in action. Details of all the available counter styles used by various cultures around the world can be found in [Ready-made Counter Styles](https://www.w3.org/TR/predefined-counter-styles/). +Refer to the [All list style types](#all_list_style_types) example to see the above values in action. Details of all the available counter styles used by various cultures around the world can be found in [Ready-made Counter Styles](https://w3c.github.io/predefined-counter-styles/). ### Non-standard extensions diff --git a/files/en-us/web/css/list-style/index.md b/files/en-us/web/css/list-style/index.md index e1c08197e83d476..95df27fb44a911e 100644 --- a/files/en-us/web/css/list-style/index.md +++ b/files/en-us/web/css/list-style/index.md @@ -9,7 +9,82 @@ browser-compat: css.properties.list-style The **`list-style`** CSS [shorthand property](/en-US/docs/Web/CSS/CSS_cascade/Shorthand_properties) allows you to set all the list style properties at once. -{{EmbedInteractiveExample("pages/css/list-style.html")}} +{{InteractiveExample("CSS Demo: list-style")}} + +```css interactive-example-choice +list-style: square; +``` + +```css interactive-example-choice +list-style: inside; +``` + +```css interactive-example-choice +list-style: url("/shared-assets/images/examples/rocket.svg"); +``` + +```css interactive-example-choice +list-style: none; +``` + +```css interactive-example-choice +list-style: georgian inside url("/shared-assets/images/examples/rocket.svg"); +``` + +```css interactive-example-choice +list-style: georgian outside url("/non-existent.svg"); +``` + +```html interactive-example +<section class="default-example" id="default-example"> + <div> + <p>NASA Notable Missions</p> + <ul class="transition-all" id="example-element"> + <li>Apollo</li> + <li>Hubble</li> + <li>Chandra</li> + <li>Cassini-Huygens</li> + <li>Spitzer</li> + </ul> + </div> +</section> +``` + +```css interactive-example +.default-example { + font-size: 1.2rem; +} + +#example-element { + width: 100%; + background: #be094b; + color: white; +} + +section { + text-align: left; + flex-direction: column; +} + +hr { + width: 50%; + color: lightgray; + margin: 0.5em; +} + +.note { + font-size: 0.8rem; +} + +.note a { + color: #009e5f; +} + +@counter-style space-counter { + symbols: "\1F680" "\1F6F8" "\1F6F0" "\1F52D"; + suffix: " "; +} +``` The values of this property are applied to list items, including {{HTMLElement("li")}} elements and elements with `{{cssxref("display")}}: list-item;`. Because this property is inherited, it can be set on a parent element (normally {{HTMLElement("ol")}} or {{HTMLElement("ul")}}) to make the same list styling apply to all the nested items. @@ -76,7 +151,7 @@ The `list-style` property is specified as one, two, or three values in any order Safari does not recognize ordered or unordered lists as lists in the accessibility tree if they have a `list-style` value of `none`, unless the list is nested within the {{HTMLElement("nav")}} navigation element. This [behavior is intentional](https://webkit.org/b/170179#c1) and is not considered a bug. -To ensure lists are announced as lists, include [`role="list"`](/en-US/docs/Web/Accessibility/ARIA/Roles/list_role) to {{HTMLElement("ol")}} and {{HTMLElement("ul")}} elements, especially if the list is not nested in a `<nav>`. This restores list semantics without affecting the design: +To ensure lists are announced as lists, include [`role="list"`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/list_role) to {{HTMLElement("ol")}} and {{HTMLElement("ul")}} elements, especially if the list is not nested in a `<nav>`. This restores list semantics without affecting the design: ```html <ul role="list"> @@ -103,7 +178,7 @@ These CSS workarounds should only be used when an HTML solution is unavailable, - ['Fixing' Lists](https://www.scottohara.me/blog/2019/01/12/lists-and-safari.html) (2023) - [VoiceOver and list-style-type: none](https://gerardkcohen.me/writing/2017/voiceover-list-style-type.html) (2017) -- [Understanding WCAG: Create content that can be presented in different ways](/en-US/docs/Web/Accessibility/Understanding_WCAG/Perceivable#guideline_1.3_—_create_content_that_can_be_presented_in_different_ways) +- [Understanding WCAG: Create content that can be presented in different ways](/en-US/docs/Web/Accessibility/Guides/Understanding_WCAG/Perceivable#guideline_1.3_—_create_content_that_can_be_presented_in_different_ways) - [Understanding success criterion 1.3.1: Info and relationships | WCAG 2.1](https://www.w3.org/WAI/WCAG21/Understanding/info-and-relationships.html) ## Examples diff --git a/files/en-us/web/css/margin-block-end/index.md b/files/en-us/web/css/margin-block-end/index.md index bb14b5293f14fc4..3b8aa3bf39d3255 100644 --- a/files/en-us/web/css/margin-block-end/index.md +++ b/files/en-us/web/css/margin-block-end/index.md @@ -9,7 +9,62 @@ browser-compat: css.properties.margin-block-end The **`margin-block-end`** [CSS](/en-US/docs/Web/CSS) property defines the logical block end margin of an element, which maps to a physical margin depending on the element's writing mode, directionality, and text orientation. -{{EmbedInteractiveExample("pages/css/margin-block-end.html")}} +{{InteractiveExample("CSS Demo: margin-block-end")}} + +```css interactive-example-choice +margin-block-end: 20px; +writing-mode: horizontal-tb; +``` + +```css interactive-example-choice +margin-block-end: 20px; +writing-mode: vertical-rl; +``` + +```css interactive-example-choice +margin-block-end: 20%; +writing-mode: horizontal-tb; +``` + +```css interactive-example-choice +margin-block-end: auto; +writing-mode: vertical-lr; +``` + +```html interactive-example +<section id="default-example"> + <div id="container"> + <div class="row">One</div> + <div class="row transition-all" id="example-element">Two</div> + <div class="row">Three</div> + </div> +</section> +``` + +```css interactive-example +#container { + width: 300px; + height: 200px; + display: flex; + align-content: flex-start; + flex-direction: column; + justify-content: flex-start; +} + +.row { + height: 33.33%; + display: inline-block; + border: solid #ce7777 10px; + background-color: #2b3a55; + color: #ffffff; + flex-shrink: 0; +} + +#example-element { + border: solid 10px #ffbf00; + background-color: #2b3a55; +} +``` ## Syntax diff --git a/files/en-us/web/css/margin-block-start/index.md b/files/en-us/web/css/margin-block-start/index.md index 2b3b94f549baf3a..1a417fc11724aeb 100644 --- a/files/en-us/web/css/margin-block-start/index.md +++ b/files/en-us/web/css/margin-block-start/index.md @@ -9,7 +9,62 @@ browser-compat: css.properties.margin-block-start The **`margin-block-start`** [CSS](/en-US/docs/Web/CSS) property defines the logical block start margin of an element, which maps to a physical margin depending on the element's writing mode, directionality, and text orientation. -{{EmbedInteractiveExample("pages/css/margin-block-start.html")}} +{{InteractiveExample("CSS Demo: margin-block-start")}} + +```css interactive-example-choice +margin-block-start: 20px; +writing-mode: horizontal-tb; +``` + +```css interactive-example-choice +margin-block-start: 20px; +writing-mode: vertical-rl; +``` + +```css interactive-example-choice +margin-block-start: 20%; +writing-mode: horizontal-tb; +``` + +```css interactive-example-choice +margin-block-start: auto; +writing-mode: vertical-lr; +``` + +```html interactive-example +<section id="default-example"> + <div id="container"> + <div class="row">One</div> + <div class="row transition-all" id="example-element">Two</div> + <div class="row">Three</div> + </div> +</section> +``` + +```css interactive-example +#container { + width: 300px; + height: 200px; + display: flex; + align-content: flex-start; + flex-direction: column; + justify-content: flex-start; +} + +.row { + height: 33.33%; + display: inline-block; + border: solid #ce7777 10px; + background-color: #2b3a55; + color: #ffffff; + flex-shrink: 0; +} + +#example-element { + border: solid 10px #ffbf00; + background-color: #2b3a55; +} +``` ## Syntax diff --git a/files/en-us/web/css/margin-block/index.md b/files/en-us/web/css/margin-block/index.md index f67405c31a63578..a7df771f9b4707c 100644 --- a/files/en-us/web/css/margin-block/index.md +++ b/files/en-us/web/css/margin-block/index.md @@ -9,7 +9,62 @@ browser-compat: css.properties.margin-block The **`margin-block`** [CSS](/en-US/docs/Web/CSS) [shorthand property](/en-US/docs/Web/CSS/CSS_cascade/Shorthand_properties) defines the logical block start and end margins of an element, which maps to physical margins depending on the element's writing mode, directionality, and text orientation. -{{EmbedInteractiveExample("pages/css/margin-block.html")}} +{{InteractiveExample("CSS Demo: margin-block")}} + +```css interactive-example-choice +margin-block: 10px 20px; +writing-mode: horizontal-tb; +``` + +```css interactive-example-choice +margin-block: 20px 40px; +writing-mode: vertical-rl; +``` + +```css interactive-example-choice +margin-block: 5% 20%; +writing-mode: horizontal-tb; +``` + +```css interactive-example-choice +margin-block: 1rem auto; +writing-mode: vertical-lr; +``` + +```html interactive-example +<section id="default-example"> + <div id="container"> + <div class="row">One</div> + <div class="row transition-all" id="example-element">Two</div> + <div class="row">Three</div> + </div> +</section> +``` + +```css interactive-example +#container { + width: 300px; + height: 200px; + display: flex; + align-content: flex-start; + flex-direction: column; + justify-content: flex-start; +} + +.row { + height: 33.33%; + display: inline-block; + border: solid #ce7777 10px; + background-color: #2b3a55; + color: #ffffff; + flex-shrink: 0; +} + +#example-element { + border: solid 10px #ffbf00; + background-color: #2b3a55; +} +``` ## Constituent properties diff --git a/files/en-us/web/css/margin-bottom/index.md b/files/en-us/web/css/margin-bottom/index.md index bfa0cce2fa712f9..cc386271869d9ef 100644 --- a/files/en-us/web/css/margin-bottom/index.md +++ b/files/en-us/web/css/margin-bottom/index.md @@ -9,11 +9,61 @@ browser-compat: css.properties.margin-bottom The **`margin-bottom`** [CSS](/en-US/docs/Web/CSS) property sets the [margin area](/en-US/docs/Web/CSS/CSS_box_model/Introduction_to_the_CSS_box_model#margin_area) on the bottom of an element. A positive value places it farther from its neighbors, while a negative value places it closer. -{{EmbedInteractiveExample("pages/css/margin-bottom.html")}} +{{InteractiveExample("CSS Demo: margin-bottom")}} + +```css interactive-example-choice +margin-bottom: 1em; +``` + +```css interactive-example-choice +margin-bottom: 10%; +``` + +```css interactive-example-choice +margin-bottom: 10px; +``` + +```css interactive-example-choice +margin-bottom: 0; +``` + +```html interactive-example +<section id="default-example"> + <div id="container"> + <div class="row"></div> + <div class="row transition-all" id="example-element"></div> + <div class="row"></div> + </div> +</section> +``` + +```css interactive-example +#container { + width: 300px; + height: 200px; + display: flex; + align-content: flex-start; + flex-direction: column; + justify-content: flex-start; +} + +.row { + height: 33.33%; + display: inline-block; + border: solid #ce7777 10px; + background-color: #2b3a55; + flex-shrink: 0; +} + +#example-element { + border: solid 10px #ffbf00; + background-color: #2b3a55; +} +``` ![The effect of the CSS margin-bottom property on the element box](margin-bottom.svg) -This property has no effect on _non-[replaced](/en-US/docs/Web/CSS/Replaced_element)_ inline elements, such as {{HTMLElement("span")}} or {{HTMLElement("code")}}. +This property has no effect on _non-[replaced](/en-US/docs/Glossary/Replaced_elements)_ inline elements, such as {{HTMLElement("span")}} or {{HTMLElement("code")}}. ## Syntax diff --git a/files/en-us/web/css/margin-inline-end/index.md b/files/en-us/web/css/margin-inline-end/index.md index a2f197f0a51b063..13426f22921bae0 100644 --- a/files/en-us/web/css/margin-inline-end/index.md +++ b/files/en-us/web/css/margin-inline-end/index.md @@ -9,7 +9,57 @@ browser-compat: css.properties.margin-inline-end The **`margin-inline-end`** [CSS](/en-US/docs/Web/CSS) property defines the logical inline end margin of an element, which maps to a physical margin depending on the element's writing mode, directionality, and text orientation. In other words, it corresponds to the {{cssxref("margin-top")}}, {{cssxref("margin-right")}}, {{cssxref("margin-bottom")}} or {{cssxref("margin-left")}} property depending on the values defined for {{cssxref("writing-mode")}}, {{cssxref("direction")}}, and {{cssxref("text-orientation")}}. -{{EmbedInteractiveExample("pages/css/margin-inline-end.html")}} +{{InteractiveExample("CSS Demo: margin-inline-end")}} + +```css interactive-example-choice +margin-inline-end: 20px; +writing-mode: horizontal-tb; +``` + +```css interactive-example-choice +margin-inline-end: 20px; +writing-mode: vertical-rl; +``` + +```css interactive-example-choice +margin-inline-end: 20%; +writing-mode: horizontal-tb; +direction: rtl; +``` + +```html interactive-example +<section id="default-example"> + <div id="container"> + <div class="col">One</div> + <div class="col transition-all" id="example-element">Two</div> + <div class="col">Three</div> + </div> +</section> +``` + +```css interactive-example +#container { + width: 300px; + height: 200px; + display: flex; + align-content: flex-start; + justify-content: flex-start; +} + +.col { + width: 33.33%; + border: solid #ce7777 10px; + background-color: #2b3a55; + color: white; + flex-shrink: 0; +} + +#example-element { + border: solid 10px #ffbf00; + background-color: #2b3a55; + unicode-bidi: bidi-override; +} +``` ## Syntax diff --git a/files/en-us/web/css/margin-inline-start/index.md b/files/en-us/web/css/margin-inline-start/index.md index 7e26f78e39aa70e..0c2fb7fa089bdc6 100644 --- a/files/en-us/web/css/margin-inline-start/index.md +++ b/files/en-us/web/css/margin-inline-start/index.md @@ -9,7 +9,57 @@ browser-compat: css.properties.margin-inline-start The **`margin-inline-start`** [CSS](/en-US/docs/Web/CSS) property defines the logical inline start margin of an element, which maps to a physical margin depending on the element's writing mode, directionality, and text orientation. It corresponds to the {{cssxref("margin-top")}}, {{cssxref("margin-right")}}, {{cssxref("margin-bottom")}}, or {{cssxref("margin-left")}} property depending on the values defined for {{cssxref("writing-mode")}}, {{cssxref("direction")}}, and {{cssxref("text-orientation")}}. -{{EmbedInteractiveExample("pages/css/margin-inline-start.html")}} +{{InteractiveExample("CSS Demo: margin-inline-start")}} + +```css interactive-example-choice +margin-inline-start: 20px; +writing-mode: horizontal-tb; +``` + +```css interactive-example-choice +margin-inline-start: 20px; +writing-mode: vertical-rl; +``` + +```css interactive-example-choice +margin-inline-start: 20%; +writing-mode: horizontal-tb; +direction: rtl; +``` + +```html interactive-example +<section id="default-example"> + <div id="container"> + <div class="col">One</div> + <div class="col transition-all" id="example-element">Two</div> + <div class="col">Three</div> + </div> +</section> +``` + +```css interactive-example +#container { + width: 300px; + height: 200px; + display: flex; + align-content: flex-start; + justify-content: flex-start; +} + +.col { + width: 33.33%; + border: solid #ce7777 10px; + background-color: #2b3a55; + color: white; + flex-shrink: 0; +} + +#example-element { + border: solid 10px #ffbf00; + background-color: #2b3a55; + unicode-bidi: bidi-override; +} +``` ## Syntax diff --git a/files/en-us/web/css/margin-inline/index.md b/files/en-us/web/css/margin-inline/index.md index 9bb517322861e06..09937843f5301b2 100644 --- a/files/en-us/web/css/margin-inline/index.md +++ b/files/en-us/web/css/margin-inline/index.md @@ -9,7 +9,57 @@ browser-compat: css.properties.margin-inline The **`margin-inline`** [CSS](/en-US/docs/Web/CSS) [shorthand property](/en-US/docs/Web/CSS/CSS_cascade/Shorthand_properties) is a shorthand property that defines both the logical inline start and end margins of an element, which maps to physical margins depending on the element's writing mode, directionality, and text orientation. -{{EmbedInteractiveExample("pages/css/margin-inline.html")}} +{{InteractiveExample("CSS Demo: margin-inline")}} + +```css interactive-example-choice +margin-inline: 5% 10%; +writing-mode: horizontal-tb; +``` + +```css interactive-example-choice +margin-inline: 10px 40px; +writing-mode: vertical-rl; +``` + +```css interactive-example-choice +margin-inline: 5% 10%; +writing-mode: horizontal-tb; +direction: rtl; +``` + +```html interactive-example +<section id="default-example"> + <div id="container"> + <div class="col">One</div> + <div class="col transition-all" id="example-element">Two</div> + <div class="col">Three</div> + </div> +</section> +``` + +```css interactive-example +#container { + width: 300px; + height: 200px; + display: flex; + align-content: flex-start; + justify-content: flex-start; +} + +.col { + width: 33.33%; + border: solid #ce7777 10px; + background-color: #2b3a55; + color: white; + flex-shrink: 0; +} + +#example-element { + border: solid 10px #ffbf00; + background-color: #2b3a55; + unicode-bidi: bidi-override; +} +``` ## Constituent properties diff --git a/files/en-us/web/css/margin-left/index.md b/files/en-us/web/css/margin-left/index.md index 5dd17999715a70d..644f4289620675b 100644 --- a/files/en-us/web/css/margin-left/index.md +++ b/files/en-us/web/css/margin-left/index.md @@ -9,7 +9,55 @@ browser-compat: css.properties.margin-left The **`margin-left`** [CSS](/en-US/docs/Web/CSS) property sets the [margin area](/en-US/docs/Web/CSS/CSS_box_model/Introduction_to_the_CSS_box_model#margin_area) on the left side of an element. A positive value places it farther from its neighbors, while a negative value places it closer. -{{EmbedInteractiveExample("pages/css/margin-left.html")}} +{{InteractiveExample("CSS Demo: margin-left")}} + +```css interactive-example-choice +margin-left: 1em; +``` + +```css interactive-example-choice +margin-left: 10%; +``` + +```css interactive-example-choice +margin-left: 10px; +``` + +```css interactive-example-choice +margin-left: 0; +``` + +```html interactive-example +<section id="default-example"> + <div id="container"> + <div class="col"></div> + <div class="col transition-all" id="example-element"></div> + <div class="col"></div> + </div> +</section> +``` + +```css interactive-example +#container { + width: 300px; + height: 200px; + display: flex; + align-content: flex-start; + justify-content: flex-start; +} + +.col { + width: 33.33%; + border: solid #5b6dcd 10px; + background-color: rgba(229, 232, 252, 0.6); + flex-shrink: 0; +} + +#example-element { + border: solid 10px #ffc129; + background-color: rgba(255, 244, 219, 0.6); +} +``` The vertical margins of two adjacent boxes may fuse. This is called [_margin collapsing_](/en-US/docs/Web/CSS/CSS_box_model/Mastering_margin_collapsing). diff --git a/files/en-us/web/css/margin-right/index.md b/files/en-us/web/css/margin-right/index.md index 2409acfdc0c2d07..e419fa474d0b7aa 100644 --- a/files/en-us/web/css/margin-right/index.md +++ b/files/en-us/web/css/margin-right/index.md @@ -9,7 +9,55 @@ browser-compat: css.properties.margin-right The **`margin-right`** [CSS](/en-US/docs/Web/CSS) property sets the [margin area](/en-US/docs/Web/CSS/CSS_box_model/Introduction_to_the_CSS_box_model#margin_area) on the right side of an element. A positive value places it farther from its neighbors, while a negative value places it closer. -{{EmbedInteractiveExample("pages/css/margin-right.html")}} +{{InteractiveExample("CSS Demo: margin-right")}} + +```css interactive-example-choice +margin-right: 1em; +``` + +```css interactive-example-choice +margin-right: 10%; +``` + +```css interactive-example-choice +margin-right: 10px; +``` + +```css interactive-example-choice +margin-right: 0; +``` + +```html interactive-example +<section id="default-example"> + <div id="container"> + <div class="col"></div> + <div class="col transition-all" id="example-element"></div> + <div class="col"></div> + </div> +</section> +``` + +```css interactive-example +#container { + width: 300px; + height: 200px; + display: flex; + align-content: flex-start; + justify-content: flex-start; +} + +.col { + width: 33.33%; + border: solid #5b6dcd 10px; + background-color: rgba(229, 232, 252, 0.6); + flex-shrink: 0; +} + +#example-element { + border: solid 10px #ffc129; + background-color: rgba(255, 244, 219, 0.6); +} +``` The vertical margins of two adjacent boxes may fuse. This is called [_margin collapsing_](/en-US/docs/Web/CSS/CSS_box_model/Mastering_margin_collapsing). diff --git a/files/en-us/web/css/margin-top/index.md b/files/en-us/web/css/margin-top/index.md index 2f18f347b715b8a..705d6d59f928120 100644 --- a/files/en-us/web/css/margin-top/index.md +++ b/files/en-us/web/css/margin-top/index.md @@ -9,9 +9,59 @@ browser-compat: css.properties.margin-top The **`margin-top`** [CSS](/en-US/docs/Web/CSS) property sets the [margin area](/en-US/docs/Web/CSS/CSS_box_model/Introduction_to_the_CSS_box_model#margin_area) on the top of an element. A positive value places it farther from its neighbors, while a negative value places it closer. -{{EmbedInteractiveExample("pages/css/margin-top.html")}} +{{InteractiveExample("CSS Demo: margin-top")}} -This property has no effect on _non-[replaced](/en-US/docs/Web/CSS/Replaced_element)_ inline elements, such as {{HTMLElement("span")}} or {{HTMLElement("code")}}. +```css interactive-example-choice +margin-top: 1em; +``` + +```css interactive-example-choice +margin-top: 10%; +``` + +```css interactive-example-choice +margin-top: 10px; +``` + +```css interactive-example-choice +margin-top: 0; +``` + +```html interactive-example +<section id="default-example"> + <div id="container"> + <div class="row"></div> + <div class="row transition-all" id="example-element"></div> + <div class="row"></div> + </div> +</section> +``` + +```css interactive-example +#container { + width: 300px; + height: 200px; + display: flex; + align-content: flex-start; + flex-direction: column; + justify-content: flex-start; +} + +.row { + height: 33.33%; + display: inline-block; + border: solid #ce7777 10px; + background-color: #2b3a55; + flex-shrink: 0; +} + +#example-element { + border: solid 10px #ffbf00; + background-color: #2b3a55; +} +``` + +This property has no effect on _non-[replaced](/en-US/docs/Glossary/Replaced_elements)_ inline elements, such as {{HTMLElement("span")}} or {{HTMLElement("code")}}. ## Syntax diff --git a/files/en-us/web/css/margin/index.md b/files/en-us/web/css/margin/index.md index 739ea9f36a63e9c..7709ed85eeec772 100644 --- a/files/en-us/web/css/margin/index.md +++ b/files/en-us/web/css/margin/index.md @@ -9,7 +9,61 @@ browser-compat: css.properties.margin The **`margin`** [CSS](/en-US/docs/Web/CSS) shorthand property sets the [margin area](/en-US/docs/Web/CSS/CSS_box_model/Introduction_to_the_CSS_box_model#margin_area) on all four sides of an element. -{{EmbedInteractiveExample("pages/css/margin.html")}} +{{InteractiveExample("CSS Demo: margin")}} + +```css interactive-example-choice +margin: 1em; +``` + +```css interactive-example-choice +margin: 5% 0; +``` + +```css interactive-example-choice +margin: 10px 50px 20px; +``` + +```css interactive-example-choice +margin: 10px 50px 20px 0; +``` + +```css interactive-example-choice +margin: 0; +``` + +```html interactive-example +<section id="default-example"> + <div id="container"> + <div class="row"></div> + <div class="row transition-all" id="example-element"></div> + <div class="row"></div> + </div> +</section> +``` + +```css interactive-example +#container { + width: 300px; + height: 200px; + display: flex; + align-content: flex-start; + flex-direction: column; + justify-content: flex-start; +} + +.row { + height: 33.33%; + display: inline-block; + border: solid #ce7777 10px; + background-color: #2b3a55; + flex-shrink: 0; +} + +#example-element { + border: solid 10px #ffbf00; + background-color: #2b3a55; +} +``` ## Constituent properties @@ -76,7 +130,7 @@ The `margin` property may be specified using one, two, three, or four values. Ea This property can be used to set a margin on all four sides of an element. Margins create extra space _around_ an element, unlike {{cssxref("padding")}}, which creates extra space _within_ an element. -The top and bottom margins have no effect on _non-[replaced](/en-US/docs/Web/CSS/Replaced_element)_ inline elements, such as {{HTMLElement("span")}} or {{HTMLElement("code")}}. +The top and bottom margins have no effect on _non-[replaced](/en-US/docs/Glossary/Replaced_elements)_ inline elements, such as {{HTMLElement("span")}} or {{HTMLElement("code")}}. ### Horizontal centering @@ -98,7 +152,7 @@ Elements' top and bottom margins are sometimes collapsed into a single margin th ## Examples -### Simple example +### Basic example #### HTML @@ -124,7 +178,7 @@ Elements' top and bottom margins are sometimes collapsed into a single margin th } ``` -{{ EmbedLiveSample('Simple_example','100%',120) }} +{{ EmbedLiveSample('Basic_example','100%',120) }} ### More examples diff --git a/files/en-us/web/css/mask-border-repeat/index.md b/files/en-us/web/css/mask-border-repeat/index.md index 78b1b6aeff3b8fd..2a7a191edb2429c 100644 --- a/files/en-us/web/css/mask-border-repeat/index.md +++ b/files/en-us/web/css/mask-border-repeat/index.md @@ -7,7 +7,7 @@ browser-compat: css.properties.mask-border-repeat {{CSSRef}} -The **`mask-border-repeat`** [CSS](/en-US/docs/Web/CSS) property sets how the [edge regions](/en-US/docs/Web/CSS/border-image-slice#edge-regions) of a source image are adjusted to fit the dimensions of an element's [mask border](/en-US/docs/Web/CSS/mask-border). +The **`mask-border-repeat`** [CSS](/en-US/docs/Web/CSS) property specifies how the images for the sides and the middle part of the [mask border image](/en-US/docs/Web/CSS/mask-border) are scaled and tiled. ## Syntax @@ -57,7 +57,7 @@ The `mask-border-repeat` property may be specified using one or two values chose ### Basic usage -This property doesn't appear to be supported anywhere yet. When it eventually starts to be supported, it will serve to define how the border mask slice will repeat around the border — i.e. will it just repeat, or be scaled slightly so a whole number of slices fits, or be stretched so one slice fits? +This property doesn't appear to be supported anywhere yet. When it eventually starts to be supported, it will serve to define how the border mask slice will repeat around the border — i.e., will it just repeat, or be scaled slightly so a whole number of slices fits, or be stretched so one slice fits? ```css mask-border-repeat: round; diff --git a/files/en-us/web/css/mask-clip/index.md b/files/en-us/web/css/mask-clip/index.md index e311a3e3c66591e..d310ceb4dc63a3e 100644 --- a/files/en-us/web/css/mask-clip/index.md +++ b/files/en-us/web/css/mask-clip/index.md @@ -23,12 +23,6 @@ mask-clip: view-box; /* Keyword values */ mask-clip: no-clip; -/* Non-standard keyword values */ --webkit-mask-clip: border; --webkit-mask-clip: padding; --webkit-mask-clip: content; --webkit-mask-clip: text; - /* Multiple values */ mask-clip: padding-box, no-clip; mask-clip: view-box, fill-box, border-box; @@ -41,10 +35,10 @@ mask-clip: revert-layer; mask-clip: unset; ``` -One or more of the keyword values listed below, separated by commas. - ### Values +The property accepts a comma-separated list of keyword values. Each value is a `<coord-box>` or `no-clip`: + - `content-box` - : The painted content is clipped to the content box. - `padding-box` @@ -56,7 +50,7 @@ One or more of the keyword values listed below, separated by commas. - `stroke-box` - : The painted content is clipped to the stroke bounding box. - `view-box` - - : Uses the nearest SVG viewport as reference box. If a [`viewBox`](/en-US/docs/Web/SVG/Attribute/viewBox) attribute is specified for the element creating the SVG viewport, the reference box is positioned at the origin of the coordinate system established by the `viewBox` attribute and the dimension of the reference box is set to the width and height values of the `viewBox` attribute. + - : Uses the nearest SVG viewport as reference box. If a [`viewBox`](/en-US/docs/Web/SVG/Reference/Attribute/viewBox) attribute is specified for the element creating the SVG viewport, the reference box is positioned at the origin of the coordinate system established by the `viewBox` attribute and the dimension of the reference box is set to the width and height values of the `viewBox` attribute. - `no-clip` - : The painted content is not clipped. - `border` @@ -68,6 +62,16 @@ One or more of the keyword values listed below, separated by commas. - `text` - : This keyword clips the mask image to the text of the element. +## Description + +The `mask-clip` property defines the area of the element that is affected by the applied mask. + +For mask layer images that do not reference an SVG {{svgelement("mask")}} element, the `mask-clip` property defines the mask painting area, or the area affected by the mask. The painted content of the element will be restricted to this area. + +The `mask-clip` property has no affect on a mask layer image that references a `<mask>` element. The `<mask>` element's {{svgAttr("x")}}, {{svgAttr("y")}}, {{svgAttr("width")}}, {{svgAttr("height")}}, and {{svgAttr("maskUnits")}} attributes determine the mask painting area when the source of the {{cssxref("mask-image")}} is a `<mask>`. + +An element can have multiple mask layers applied. The number of layers is determined by the number of comma-separated values in the `mask-image` property value (even if a value is `none`). Each `mask-clip` value in the comma-separated list of values is matched up with the `mask-image` values, in order. If the number of values in the two properties differs, any excess values of `mask-clip` are not used, or, if `mask-clip` has fewer values than `mask-image`, the `mask-clip` values are repeated. + ## Formal definition {{cssinfo}} @@ -80,27 +84,58 @@ One or more of the keyword values listed below, separated by commas. ### Clipping a mask to the border box -Click "Play" in the live sample to open the code in the MDN Playground and change the `mask-clip` value to any of the allowed values described above. +This examples demonstrates three `mask-clip` values. + +#### HTML + +We include three elements, each with a different `<coord-box>` value as a class name. ```html live-sample___mask-clip-example -<div class="masked"></div> +<div class="border-box"></div> +<div class="padding-box"></div> +<div class="content-box"></div> ``` +#### CSS + +The CSS defines the element to have a background, border, padding, and margin, along with a mask image, with each `<div>` having a different `<coord-box>`. We generated content with the name of the class, moving that text up 10px to prevent it from being masked out of view. + ```css live-sample___mask-clip-example -.masked { +div { width: 100px; height: 100px; background-color: #8cffa0; - margin: 20px; + margin: 10px; border: 20px solid #8ca0ff; padding: 20px; - mask-image: url(https://mdn.github.io/shared-assets/images/examples/mdn.svg); mask-size: 100% 100%; +} +.content-box { + mask-clip: content-box; +} +.border-box { mask-clip: border-box; } +.padding-box { + mask-clip: padding-box; +} +div::before { + content: attr(class); + position: relative; + top: -10px; +} ``` +```css hidden live-sample___mask-clip-example +body { + display: flex; + flex-flow: row wrap; +} +``` + +#### Results + {{EmbedLiveSample("mask-clip-example", "", "250px")}} ## Specifications @@ -113,4 +148,12 @@ Click "Play" in the live sample to open the code in the MDN Playground and chang ## See also -- [Clipping and Masking in CSS](https://css-tricks.com/clipping-masking-css/) +- {{cssxref("mask")}} shorthand +- {{cssxref("mask-image")}} +- {{cssxref("mask-origin")}} +- {{cssxref("mask-position")}} +- {{cssxref("mask-repeat")}} +- {{cssxref("mask-size")}} +- {{cssxref("mask-border")}} +- {{cssxref("clip-path")}} +- [CSS masking](/en-US/docs/Web/CSS/CSS_masking) module diff --git a/files/en-us/web/css/mask-composite/index.md b/files/en-us/web/css/mask-composite/index.md index 9de81333ac9cb4a..098f269403d12d3 100644 --- a/files/en-us/web/css/mask-composite/index.md +++ b/files/en-us/web/css/mask-composite/index.md @@ -26,20 +26,28 @@ mask-composite: revert-layer; mask-composite: unset; ``` -One or more of the keyword values listed below, separated by commas. - ### Values -For the composition the current mask layer is referred to as _source_, while all layers below it are referred to as _destination_. +The property accepts a comma-separated list of `<compositing-operator>` keyword values, each representing a Porter-Duff compositing operator which defines the compositing operation used on the current mask layer with the mask layers below it, including: - `add` - - : The source is placed over the destination. + - : The associated mask image is placed over all mask layers below it (with the corresponding compositing operators applied). This is the default value. - `subtract` - - : The source is placed, where it falls outside of the destination. + - : The associated mask image is placed, where it falls outside of all mask layers below it (with the corresponding compositing operators applied). - `intersect` - - : The parts of source that overlap the destination, replace the destination. + - : The parts of the associated mask image that overlap all composited mask layers below it replace those previously composited layers. - `exclude` - - : The non-overlapping regions of source and destination are combined. + - : The non-overlapping regions of the associated mask image and the mask layers below it, with their corresponding compositing operators applied, are combined. + +## Description + +When an element has multiple mask layers applied, the `mask-composite` property can be used to define how the multiple masks interact with each other, or are combined, in creating the final mask effect. + +The number of layers is determined by the number of comma-separated values in the `mask-image` property value (even if a value is `none`). Each `mask-composite` value in the comma-separated list of values is matched up with a `mask-image` value, in order. If the number of values in `mask-composite` are equal to or greater than the number of `mask-image` values, the extra values are ignored. If the `mask-composite` property doesn't have enough comma-separated values to match the number of layers, the list of values are repeated until there are enough. + +For processing, the _source layer_, which is current or associated mask layer image, is either added to (the default), subtracted from, intersected with, or is excluded from, the destination layers. The _destination layers_ are the mask layers below the source with their corresponding compositing operators applied; this includes all the previous layers, composed in order of appearance within the comma-separated list of masks. All mask layers below the current mask layer must be composited before applying the compositing operation for the current mask layer. Mask layer images are transformed to alpha masks for processing before being combined by the defined compositing value. + +The multiple mask layers applied to any element or pseudo-element act as if they are rendered into an isolated group. In other words, the mask layers are composited with other mask layers, not with the element's content or the content behind the element. ## Formal definition @@ -51,14 +59,24 @@ For the composition the current mask layer is referred to as _source_, while all ## Examples -### Compositing mask layers with addition +### Basic usage + +This example demonstrates the basic usage of the `mask-composite` property. + +#### HTML -```html live-sample___mask-composite-example -<div class="masked"></div> +We include an HTML {{htmlelement("div")}} element, that we will then style. + +```html +<div></div> ``` -```css live-sample___mask-composite-example -.masked { +#### CSS + +We provide size and color our `<div>`, then add two {{cssxref("mask-image")}}s, and make their size match that of the element they're masking with the {{cssxref("mask-size")}} property. Lastly, we subtract the second mask image from the first mask image with the `mask-composite` property set to `subtract`. + +```css +div { width: 100px; height: 100px; background-color: red; @@ -67,11 +85,211 @@ For the composition the current mask layer is referred to as _source_, while all url(https://mdn.github.io/shared-assets/images/examples/mdn.svg), url(https://mdn.github.io/shared-assets/images/examples/mask-star.svg); mask-size: 100% 100%; + mask-composite: subtract; } ``` -{{EmbedLiveSample("mask-composite-example", "", "150px")}} +#### Results + +{{EmbedLiveSample("basic usage", "", "150px")}} + +### Value comparison + +This example demonstrates the `mask-composite` property's four `<compositing-operator>` keyword values, along with comparing the effects of [`alpha` and `luminance`](/en-US/Web/SVG/Reference/Attribute/mask-type#mask) mask modes. + +#### HTML + +We have a {{htmlelement("table")}} that contains eight images. The `<table>` has been hidden for brevity. + +```html hidden +<table> + <tbody> + <tr> + <th colspan="4">mask-type: alpha</th> + </tr> + <tr> + <th>mask-composite: add</th> + <th>mask-composite: subtract</th> + <th>mask-composite: intersect</th> + <th>mask-composite: exclude</th> + </tr> + <tr class="alphaMaskType"> + <td> + <img + src="https://mdn.github.io/shared-assets/images/examples/progress-pride-flag.jpg" + alt="Pride flag" /> + </td> + <td> + <img + src="https://mdn.github.io/shared-assets/images/examples/progress-pride-flag.jpg" + alt="Pride flag" /> + </td> + <td> + <img + src="https://mdn.github.io/shared-assets/images/examples/progress-pride-flag.jpg" + alt="Pride flag" /> + </td> + <td> + <img + src="https://mdn.github.io/shared-assets/images/examples/progress-pride-flag.jpg" + alt="Pride flag" /> + </td> + </tr> + + <tr> + <th colspan="4"> + <code>mask-type: luminance</code> + </th> + </tr> + <tr> + <th>mask-composite: add</th> + <th>mask-composite: subtract</th> + <th>mask-composite: intersect</th> + <th>mask-composite: exclude</th> + </tr> + <tr class="luminanceMaskType"> + <td> + <img + src="https://mdn.github.io/shared-assets/images/examples/progress-pride-flag.jpg" + alt="Pride flag" /> + </td> + <td> + <img + src="https://mdn.github.io/shared-assets/images/examples/progress-pride-flag.jpg" + alt="Pride flag" /> + </td> + <td> + <img + src="https://mdn.github.io/shared-assets/images/examples/progress-pride-flag.jpg" + alt="Pride flag" /> + </td> + <td> + <img + src="https://mdn.github.io/shared-assets/images/examples/progress-pride-flag.jpg" + alt="Pride flag" /> + </td> + </tr> + </tbody> +</table> +``` + +```html +<img + src="https://mdn.github.io/shared-assets/images/examples/progress-pride-flag.jpg" + alt="Pride flag" /> +``` + +And an SVG with 4 masks; an alpha heart and circle and a luminance heart and circle. The heart masks are defined using solid colors. The circle masks are created using semi-transparent white and black {{SVGAttr("stroke")}} and {{SVGAttr("fill")}} colors. + +```html +<svg height="0" width="0"> + <mask id="heartAlpha" class="alpha"> + <path + d="M20,70 A40,40,0,0,1,100,70 A40,40,0,0,1,180,70 Q180,130,100,190 Q20,130,20,70 Z" + fill="green" + stroke="white" + stroke-width="20" /> + </mask> + <mask id="circleAlpha" class="alpha"> + <circle + cx="130" + cy="130" + r="50" + fill="rgb(0 0 0 / 0.5)" + stroke="rgb(255 255 255 / 0.5)" + stroke-width="20" /> + </mask> + <mask id="heartLuminance" class="luminance"> + <path + d="M20,70 A40,40,0,0,1,100,70 A40,40,0,0,1,180,70 Q180,130,100,190 Q20,130,20,70 Z" + fill="green" + stroke="white" + stroke-width="20" /> + </mask> + <mask id="circleLuminance" class="luminance"> + <circle + cx="130" + cy="130" + r="50" + fill="rgb(0 0 0 / 0.5)" + stroke="rgb(255 255 255 / 0.5)" + stroke-width="20" /> + </mask> +</svg> +``` + +#### CSS + +First we style the `<mask>` elements, providing each mask with a {{cssxref("mask-type")}} property value of either `alpha` or `luminance`. + +```css +mask.luminance { + mask-type: luminance; +} + +mask.alpha { + mask-type: alpha; +} +``` + +We then apply the heart and circle masks as the comma-separated {{cssxref("mask-image")}} property values. These are applied to each {{htmlelement("img")}} element, with all the images in a row getting the same masks. + +```css +/* apply the mask images */ +tr.alphaMaskType img { + mask-image: url(#heartAlpha), url(#circleAlpha); +} + +tr.luminanceMaskType img { + mask-image: url(#heartLuminance), url(#circleLuminance); +} +``` + +Finally, we compose the masks using the `mask-composite` property, applying the four different enumerated `mask-composite` values by table column. + +```css +/* property we're testing */ +td:nth-of-type(1) img { + mask-composite: add; +} +td:nth-of-type(2) img { + mask-composite: subtract; +} +td:nth-of-type(3) img { + mask-composite: intersect; +} +td:nth-of-type(4) img { + mask-composite: exclude; +} +``` + +The table styles have been hidden for the sake of brevity. + +```css hidden +mask { + height: 50%; +} + +table, +td, +th { + border: 1px solid; +} +th { + font-family: monospace; +} +th { + color: green; +} +body > img { + display: none; +} +``` + +#### Results + +{{EmbedLiveSample("value comparison", "", "600")}} ## Specifications @@ -83,4 +301,7 @@ For the composition the current mask layer is referred to as _source_, while all ## See also -- [Clipping and Masking in CSS](https://css-tricks.com/clipping-masking-css/) +- {{cssxref("mask")}} shorthand +- {{cssxref("mask-type")}} +- {{cssxref("mask-mode")}} +- [CSS masking](/en-US/docs/Web/CSS/CSS_masking) module diff --git a/files/en-us/web/css/mask-image/index.md b/files/en-us/web/css/mask-image/index.md index 95e8a46bd7fbd6d..f4fa14d317d7929 100644 --- a/files/en-us/web/css/mask-image/index.md +++ b/files/en-us/web/css/mask-image/index.md @@ -7,8 +7,7 @@ browser-compat: css.properties.mask-image {{CSSRef}} -The **`mask-image`** [CSS](/en-US/docs/Web/CSS) property sets the image that is used as mask layer for an element. -By default this means the alpha channel of the mask image will be multiplied with the alpha channel of the element. This can be controlled with the {{cssxref("mask-mode")}} property. +The **`mask-image`** [CSS](/en-US/docs/Web/CSS) property sets the image that is used as the mask layer for an element, hiding sections of the element on which the masking image is set based on the alpha channel of the mask image and, depending on the {{cssxref("mask-mode")}} property value, the luminance of the mask image's colors. ## Syntax @@ -24,8 +23,7 @@ mask-image: linear-gradient(rgb(0 0 0 / 100%), transparent); mask-image: image(url(mask.png), skyblue); /* Multiple values */ -mask-image: - image(url(mask.png), skyblue), linear-gradient(rgb(0 0 0 / 100%), transparent); +mask-image: url(mask.png), linear-gradient(black 25%, transparent 35%); /* Global values */ mask-image: inherit; @@ -45,19 +43,34 @@ mask-image: unset; - : A {{cssxref("url_value", "&lt;url&gt;")}} reference to a {{SVGElement("mask")}} or to a CSS image. - > [!NOTE] - > Only the image sources served over HTTP and HTTPS protocols are accepted due to the [CORS](/en-US/docs/Glossary/CORS) policy. Images served locally, including relative or absolute `file://` protocols, are not accepted. To test URL image sources locally, [set up a local server](/en-US/docs/Web/Progressive_web_apps/Tutorials/CycleTracker/Secure_connection#localhost). - - {{cssxref("&lt;image&gt;")}} - : An image value used as a mask image layer. -In the following cases, the mask is counted as a transparent black image layer: +## Description + +The `mask-image` property provides a mask that hides part of the element to which it is applied. The value is a comma-separated list of mask references. Each mask reference is an `<image>`, a `<mask-source>`, or the keyword `none`. + +An `<image>` can be any type of image, including generated images such as [CSS gradients](/en-US/docs/Web/CSS/gradient). + +If only one value is specified in the `mask-image` property value, and that value is `none`, no masking effect will be apparent. If multiple values are specified, a `none` value included in the list may have no direct effect, however, other `mask-*` values in the same list position will apply to a transparent black mask layer and have no visual effect. + +Only image sources served over HTTP and HTTPS protocols are accepted as `<image>` values due to the [CORS](/en-US/docs/Glossary/CORS) policy. Images served locally, including relative or absolute `file://` protocols, are not accepted, and will render as transparent black. To test URL image sources locally, [set up a local server](/en-US/docs/Web/Progressive_web_apps/Tutorials/CycleTracker/Secure_connection#localhost). + +A mask will be counted as a transparent black image layer, not revealing anything, in the following cases: + +- The mask image is empty (zero width or zero height). +- The mask image fails to download. +- The browser does not support the mask image format. +- The mask image doesn't exist. +- The mask value doesn't point to a mask image. + +The default value of the {{cssxref("mask-mode")}} property is `match-source`, which means the mode is defined by the mode of the mask image itself. The mask image's mode is generally `alpha` except when the mask source is an SVG {{svgelement("mask")}} element, in which case the mode is `luminance` unless the mode is changed to `alpha` via the CSS {{cssxref("mask-type")}} property or SVG {{svgattr("mask-type")}} attribute. -- the mask image is empty (zero width or zero height) -- the mask image fails to download -- the mask image format is not supported by the browser -- the mask image doesn't exist -- the mask value doesn't point to a mask image +The `mask-mode` value is significant, because it determines whether the masking effect depends on the image source's alpha channel values alone or a combination of those and the mask's luminance (the lightness/darkness of the colors that make up the `mask-image`): + +- In all cases, the alpha transparency of the mask matters; element areas masked by opaque sections of the `mask-image` will be rendered, while areas masked by transparent image sections are hidden. +- When the `mask-mode` value is set or resolves to `alpha`, only the alpha-channel of the colors matter; the hue, lightness, etc., don't matter. +- If the `mask-mode` property is set or defaults to `luminance`, the masking value is the luminance value of each color multiplied by its alpha value. The `mask-mode` will resolve to `luminance` if explicitly set to that value, or if the property is set to `match-source` and the `mask-image` source is an SVG {{svgelement("mask")}} that does not have its {{cssxref("mask-type")}} property or {{svgattr("mask-type")}} attribute explicitly set to `alpha`. ## Formal definition @@ -69,27 +82,195 @@ In the following cases, the mask is counted as a transparent black image layer: ## Examples -### Setting a mask image with a URL and a gradient +### Gradient as a mask image + +In this example, we use an `<image>` value as a mask, defining a CSS [radial gradient](/en-US/docs/Web/CSS/gradient/radial-gradient) as our mask image to create a round image with a soft edge. + +#### HTML + +We include an HTML {{htmlelement("img")}} element, which will also be used in all other examples. -```html live-sample___mask-image-example -<div class="masked"></div> +```html live-sample___example-image live-sample___first-example +<img + src="https://mdn.github.io/shared-assets/images/examples/progress-pride-flag.jpg" + alt="Pride flag" /> ``` -```css live-sample___mask-image-example -.masked { - width: 200px; - height: 200px; - mask-repeat: no-repeat; - mask-size: 100%; +{{EmbedLiveSample("example-image", "100%", 250)}} + +#### CSS + +We use the CSS {{CSSxRef("gradient/radial-gradient")}} function to create a mask that has a black circle with a radius that is half the width of the mask, before transitioning to being transparent over 10%. + +```css live-sample___first-example +img { + mask-image: radial-gradient(black 50%, transparent 60%); +} +``` + +#### Results + +{{EmbedLiveSample("first-example", "100%", 250)}} + +The part of the original element that is masked by the black circle is fully opaque, fading to transparent as the mask fades to transparent. + +### Image resource as a mask image + +In this example, the `<mask-source>` used as our mask image is an external SVG. + +#### HTML - background: red; +We include the same image as the previous example. We've also included the image we will be using as the mask; a star whose {{cssxref("fill-opacity")}} is `0.5`, or 50% opaque. + +```html +<img + src="https://mdn.github.io/shared-assets/images/examples/progress-pride-flag.jpg" + alt="Pride flag" /> + +<img + src="https://mdn.github.io/shared-assets/images/examples/mask-star.svg" + alt="A star" /> +``` + +#### CSS + +We use `mask-star.svg` as a mask image on our first image: + +```css +img:first-of-type { + mask-image: url(https://mdn.github.io/shared-assets/images/examples/mask-star.svg); +} +``` + +#### Results + +{{EmbedLiveSample("Image resource as a mask image", "100%", 250)}} + +The mask is semi-opaque, which is why the colors are not as vibrant as the previous example. The part of the image that is visible is 50% opaque; the opacity of the mask applied. +The mask is smaller than the image, so repeats by default. We could have used {{cssxref("mask-repeat")}} to control the repeating or {{cssxref("mask-size")}} to change the size of the mask, which we do in the next example. + +### Multiple masks + +This example demonstrates applying multiple masks. + +```html hidden +<img + src="https://mdn.github.io/shared-assets/images/examples/progress-pride-flag.jpg" + alt="Pride flag" /> +``` + +#### CSS + +We apply two masks — the same semi-transparent SVG as in the previous example, and a {{CSSxRef("gradient/repeating-radial-gradient")}}. We control the size of the masks using the {{cssxref("mask-size")}} property. Because our first mask is not sized at 100%, we make sure our masks are centered and don't repeat with the {{cssxref("mask-position")}} and {{cssxref("mask-repeat")}} properties, respectively. + +```css +img { + mask-size: 95%, 100%; + mask-position: center; + mask-repeat: no-repeat; mask-image: url(https://mdn.github.io/shared-assets/images/examples/mask-star.svg), - radial-gradient(transparent 50%, black); + repeating-radial-gradient(transparent 0 5px, black 5px 10px); } ``` -{{EmbedLiveSample("mask-image-example", "100%", 250)}} +#### Results + +{{EmbedLiveSample("multiple masks", "100%", 250)}} + +### Masking with SVG `<mask>` + +This example demonstrates using SVG {{svgelement("mask")}} elements as masks. In this case, the color of the mask matters as the {{cssxref("mask-type")}} value for SVG masks defaults to `luminance`, which means white opaque areas (100% luminance) will be masked and visible, transparent and black areas (0% luminance) will be clipped, and anything in between will be partially masked. + +#### HTML + +We've included an `id` for each of our four images, and an SVG that contains an equal number of `<mask>` elements. + +```html +<img + id="green" + src="https://mdn.github.io/shared-assets/images/examples/progress-pride-flag.jpg" + alt="Pride flag" /> +<img + id="stroke" + src="https://mdn.github.io/shared-assets/images/examples/progress-pride-flag.jpg" + alt="Pride flag" /> +<img + id="both" + src="https://mdn.github.io/shared-assets/images/examples/progress-pride-flag.jpg" + alt="Pride flag" /> +<img + id="alphaMode" + src="https://mdn.github.io/shared-assets/images/examples/progress-pride-flag.jpg" + alt="Pride flag" /> + +<svg height="0" width="0"> + <mask id="greenMask"> + <path + d="M20,70 A40,40,0,0,1,100,70 A40,40,0,0,1,180,70 Q180,130,100,190 Q20,130,20,70 Z" + fill="green" /> + </mask> + <mask id="strokeMask"> + <path + d="M20,70 A40,40,0,0,1,100,70 A40,40,0,0,1,180,70 Q180,130,100,190 Q20,130,20,70 Z" + fill="none" + stroke="white" + stroke-width="20" /> + </mask> + <mask id="bothMask"> + <path + d="M20,70 A40,40,0,0,1,100,70 A40,40,0,0,1,180,70 Q180,130,100,190 Q20,130,20,70 Z" + fill="green" + stroke="white" + stroke-width="20" /> + </mask> + <mask id="black"> + <path + d="M20,70 A40,40,0,0,1,100,70 A40,40,0,0,1,180,70 Q180,130,100,190 Q20,130,20,70 Z" + fill="black" /> + </mask> +</svg> +``` + +```html hidden +<p> + <label> + <input type="checkbox" /> + Set the <code>mask-mode</code> to <code>alpha</code>. + </label> +</p> +``` + +#### CSS + +We apply a different `<mask>` to each `<img>`. No part of the last image, with the `black` fill, will be visible by default. In this case, while all colors used in this example are fully opaque, the `mask-mode` defaults to `match-type`, which resolves to `luminance` in this case. + +```css +#green { + mask-image: url(#greenMask); +} +#stroke { + mask-image: url(#strokeMask); +} +#both { + mask-image: url(#bothMask); +} +#alphaMode { + mask-image: url(#black); +} + +body:has(:checked) img { + mask-mode: alpha; +} +``` + +The luminance values of `black`, `white`, and `green` are `0`, `100`, and [`46.228`](https://www.colorhexa.com/008000), respectively. This means the areas where the mask is white will be visible, whereas areas where the mask is black or fully transparent will be clipped (not visible). Areas where the mask is green will be visible but lighter, equivalent to having a white mask that is 46.228% opaque. + +#### Results + +{{EmbedLiveSample("SVG elements as masks", "100%", 540)}} + +Toggle the checkbox to toggle the value of the `mask-mode` between `alpha` (checked) and the initial value, which resolves to `luminance` (unchecked). When `alpha` is used, the color of the mask doesn't matter; all that matters is the alpha-transparency. When the value resolves to `luminance`, `white` areas are visible, `black` areas are not, and `green` areas are visible but at an opacity that matches the luminance of the color `green`. When `mask-mode` is set to `alpha`, the colors are equivalent as they are all fully opaque. ## Specifications @@ -101,5 +282,12 @@ In the following cases, the mask is counted as a transparent black image layer: ## See also -- [Clipping and Masking in CSS](https://css-tricks.com/clipping-masking-css/) -- [Apply effects to images with CSS's `mask-image` property](https://web.dev/articles/css-masking) +- {{cssxref("mask")}} shorthand +- {{cssxref("mask-origin")}} +- {{cssxref("mask-position")}} +- {{cssxref("mask-repeat")}} +- {{cssxref("mask-size")}} +- {{cssxref("mask-border")}} +- {{cssxref("clip-path")}} +- [Introduction to CSS masking](/en-US/docs/Web/CSS/CSS_masking/Masking) +- [CSS masking](/en-US/docs/Web/CSS/CSS_masking) module diff --git a/files/en-us/web/css/mask-mode/index.md b/files/en-us/web/css/mask-mode/index.md index bc42ac1ca3abdd7..2fd3f0cdc2db7b3 100644 --- a/files/en-us/web/css/mask-mode/index.md +++ b/files/en-us/web/css/mask-mode/index.md @@ -7,7 +7,7 @@ browser-compat: css.properties.mask-mode {{CSSRef}} -The **`mask-mode`** [CSS](/en-US/docs/Web/CSS) property sets whether the mask reference defined by {{cssxref("mask-image")}} is treated as a luminance or alpha mask. +The **`mask-mode`** [CSS](/en-US/docs/Web/CSS) property is set on the element being masked. It sets whether the mask reference defined by the {{cssxref("mask-image")}} is treated as a luminance or alpha mask. ## Syntax @@ -28,19 +28,45 @@ mask-mode: revert-layer; mask-mode: unset; ``` -The `mask-mode` property is specified as one or more of the keyword values listed below, separated by commas. - ### Values +The `mask-mode` property can take multiple comma-separated `<masking-mode>` keyword values, including: + - `alpha` - - : This keyword indicates that the transparency (alpha channel) values of the mask layer image should be used as the mask values. + + - : Indicates that the alpha (transparency) values of the mask image should be used. + - `luminance` - - : This keyword indicates that the luminance values of the mask layer image should be used as the mask values. + + - : Indicates that the [luminance (brightness)](#understanding_luminance) values of the mask image should be used. + - `match-source` + - : Indicates that the type of mask is determined by the source. This is the default property value. + - If the {{cssxref("mask-image")}} references an SVG {{svgelement("mask")}}, its {{cssxref("mask-type")}} property value is used, or it's {{SVGAttr("mask-type")}} attribute, if present. If neither is explicitly set, this value defaults to `luminance`. + - If the mask image source is an {{cssxref("image")}} or a {{cssxref("gradient")}}, the `alpha` values of the mask image are used. + +## Description + +A mask transfers its transparency, and depending on the mask type, it's luminance, to the element it is masking. +If the mask is of type {{cssxref("&lt;image&gt;")}}, by default the alpha values of the mask image determine the visibility of each part of the masked element: where the mask is opaque, the corresponding part of the masked element is visible; where the mask is translucent, the element is as well, with those areas of the element being hidden. This is the default behavior for `<image>` masks when the `mask-mode` property is set to or defaults to `match-source`, and it is always the case when the `mask-mode` is explicitly set to `alpha`. + +### Understanding luminance + +In the case of `luminance` masks, the visibility of the masked element depends on both the opacity of the mask and the lightness of the color of the opaque areas. White (100% luminance) opaque areas (alpha = 1) will be masked and visible, and black areas (0% luminance) transparent (alpha = 0) will be clipped. Areas with colors in between white and black and with partial opacity will be partially masked, reflecting the luminance and alpha transparency of each color making up the mask. - - : If the {{cssxref("mask-image")}} property is of type `<mask-source>`, the luminance values of the mask layer image should be used as the mask values. +The opacity of a `luminance` mask is determined by the `R`, `G`, `B`, and `A` values of an `rgb()` color using the formula: - If it is of type {{cssxref("&lt;image&gt;")}}, the alpha values of the mask layer image should be used as the mask values. +`((0.2125 * R) + (0.7154 * G) + (0.0721 * B)) * A` + +For example, the color `green` is `#008000` or `rgb(0% 50% 0% / 1)`. In a `luminance` mask, any area masked by a solid `green` mask will be `35.77%` opaque. If the `mask-mode` for this mask is set to `alpha`, since `green` is a fully opaque color, the masked area will be `100%` opaque. + +### Multiple values + +Each `mask-mode` value is a comma-separated list of values. When multiple values are present, each value corresponds to a mask layer in the same position in the {{cssxref("mask-image")}} property. The values define whether the associated mask images are treated as a `luminance` or an `alpha` mask. + +### Understanding `match-source` + +In the case of `match-source`, whether `luminance` or `alpha` is used depends on the mask mode of the mask source. If the `mask-image` property values is a reference to an SVG {{svgelement("mask")}} element, the `<mask>` element's {{cssxref("mask-type")}} property value is used. If there is no CSS `mask-type` property set on the `<mask>` element, the value of the `<mask>` element's {{svgattr("mask-type")}} attribute is used, if present and supported. If neither is explicitly set, this value defaults to `luminance`; but only in the case of the `<mask>` element as the mask source. Otherwise, as noted before, if the mask image source is an {{cssxref("image")}}, rather than an SVG `<mask>`, the `alpha` values of the mask layer image is used. ## Formal definition @@ -52,24 +78,61 @@ The `mask-mode` property is specified as one or more of the keyword values liste ## Examples -### Using alpha mask mode +### Usage and values -```html live-sample___mask-mode-example -<div class="masked"></div> +This example demonstrates the basic usage and different values of the `mask-mode` property. + +#### HTML + +We include three `<div>` elements, so we can demonstrate the three enumerated `mask-mode` keyword values. + +```html +<div class="alpha">ALPHA</div> +<div class="luminance">LUMINANCE</div> +<div class="matchSource">MATCH-SOURCE</div> ``` -```css live-sample___mask-mode-example -.masked { - width: 227px; - height: 200px; - background: blue linear-gradient(red, blue); +#### CSS + +Each `<div>` is provided with the same background and masking image. The only difference between each `<div>` is the value of the `mask-mode` property: +```css +div { + background: blue linear-gradient(red, blue); mask-image: url(https://mdn.github.io/shared-assets/images/examples/mdn.svg); +} + +.alpha { mask-mode: alpha; } + +.luminance { + mask-mode: luminance; +} + +.matchSource { + mask-mode: match-source; +} ``` -{{EmbedLiveSample("mask-mode-example", "", "250px")}} +```css hidden +div { + width: 227px; + height: 200px; + float: left; + text-align: center; + line-height: 65px; + color: white; + text-shadow: 1px 1px 2px black; + font-family: sans-serif; +} +``` + +#### Results + +{{EmbedLiveSample("Usage and values", "", "250px")}} + +Because the mask source is an `<image>` and not an SVG `<mask>`, the `match-source` value resolves to `alpha`. ## Specifications @@ -81,4 +144,8 @@ The `mask-mode` property is specified as one or more of the keyword values liste ## See also -- [Clipping and Masking in CSS](https://css-tricks.com/clipping-masking-css/) +- {{cssxref("mask-type")}} +- {{cssxref("mask-image")}} +- {{cssxref("mask")}} shorthand +- [Introduction to CSS masking](/en-US/docs/Web/CSS/CSS_masking/Masking) +- [CSS masking](/en-US/docs/Web/CSS/CSS_masking) module diff --git a/files/en-us/web/css/mask-origin/index.md b/files/en-us/web/css/mask-origin/index.md index ee1c09d171415aa..d80f84c4a2a688c 100644 --- a/files/en-us/web/css/mask-origin/index.md +++ b/files/en-us/web/css/mask-origin/index.md @@ -7,9 +7,8 @@ browser-compat: css.properties.mask-origin {{CSSRef}} -The **`mask-origin`** [CSS](/en-US/docs/Web/CSS) property sets the origin of a mask. - -For elements rendered as a single box, this property specifies the mask positioning area. In other words, this property specifies the origin position of an image specified by the {{cssxref("mask-image")}} CSS property. For elements rendered as multiple boxes, such as inline boxes on several lines or boxes on several pages, it specifies which boxes {{cssxref("box-decoration-break")}} operates upon to determine the mask positioning area. +The **`mask-origin`** [CSS](/en-US/docs/Web/CSS) property sets the origin of a mask. This property determines the mask positioning area: the area within which a mask image is positioned. HTML elements can have masks contained within their content border box, padding box, or content box, whereas SVG elements (which don't have the associated CSS layout boxes) can have masks contained inside their fill, stroke, or view box. +For elements rendered as multiple boxes, such as a {{htmlelement("span")}} of text that spans more than one line, the `mask-origin` property specifies which boxes the {{cssxref("box-decoration-break")}} property operates on to determine the mask positioning area. ## Syntax @@ -26,11 +25,6 @@ mask-origin: view-box; mask-origin: padding-box, content-box; mask-origin: view-box, fill-box, border-box; -/* Non-standard keyword values */ --webkit-mask-origin: content; --webkit-mask-origin: padding; --webkit-mask-origin: border; - /* Global values */ mask-origin: inherit; mask-origin: initial; @@ -39,28 +33,40 @@ mask-origin: revert-layer; mask-origin: unset; ``` -One or more of the keyword values listed below, separated by commas. - ### Values +The `mask-origin` property is a comma-separated list of `<coord-box>` keyword values, including: + - `content-box` - - : The position is relative to the content box. + - : The position is relative to the [content box](/en-US/docs/Web/CSS/CSS_shapes/From_box_values#content-box). - `padding-box` - - : The position is relative to the padding box. For single boxes `0 0` is the upper left corner of the padding edge, `100% 100%` is the lower right corner. + - : The position is relative to the [padding box](/en-US/docs/Web/CSS/CSS_shapes/From_box_values#padding-box). - `border-box` - - : The position is relative to the border box. + - : The position is relative to the [border box](/en-US/docs/Web/CSS/CSS_shapes/From_box_values#border-box). - `fill-box` - : The position is relative to the object bounding box. - `stroke-box` - : The position is relative to the stroke bounding box. - `view-box` - : Uses the nearest SVG viewport as reference box. If a {{svgattr("viewBox")}} attribute is specified for the element creating the SVG viewport, the reference box is positioned at the origin of the coordinate system established by the `viewBox` attribute and the dimension of the reference box is set to the width and height values of the `viewBox` attribute. -- `content` - - : Same as `content-box`. -- `padding` - - : Same as `padding-box`. -- `border` - - : Same as `border-box`. + +There are three non-standard values that are shortcuts for standard `<coord-box>` values: `content` is an alias for `content-box`, `padding` is an alias for `padding-box`, and `border` is an alias for `border-box`. + +## Description + +The `mask-origin` property is very similar to the {{cssxref("background-origin")}} property, but it has a different set of values and a different initial value. The initial value depends on the if there is an associated CSS layout box; if yes, the default value is `border-box`. In comparison, the default for `background-origin` is `padding-box`. + +For SVG elements without an associated CSS layout box, the values `content-box`, `padding-box`, and `border-box` (the default value) compute to `fill-box`, meaning the position is relative to the object bounding box. For HTML elements, if a SVG-related value of `fill-box`, `stroke-box`, or `view-box` is set, the value is computed to `border-box`. + +An element can have multiple mask layers applied. The number of layers is determined by the number of comma-separated values in the {{cssxref("mask-image")}} property value (even if one or more of those values is `none`). Each `mask-origin` value in the comma-separated list of values is matched with a comma-separated `mask-image` value, in the same order. + +If the number of values in the two properties differs, any excess values of `mask-origin` are not used in cases where `mask-origin` has more values than `mask-image`. If `mask-origin` has fewer values than `mask-image`, the `mask-origin` values are repeated. + +For elements rendered as a single box, this property specifies the mask positioning area — or the origin position — of the image referenced by the `mask-image` property. + +For elements rendered as multiple boxes, such as inline boxes that span more than one line, the `mask-origin` property specifies which boxes the {{cssxref("box-decoration-break")}} property operates upon to determine the mask positioning area. + +The `mask-origin` can cause the mask layer image to be clipped. For example, if the {{cssxref("mask-clip")}} property is set to `padding-box`, the `mask-origin` is set to `border-box`, the {{cssxref("mask-position")}} is set to the `top left` edge, and the element has a border, then the mask layer image will be clipped at the top-left edge. ## Formal definition @@ -72,29 +78,140 @@ One or more of the keyword values listed below, separated by commas. ## Examples -### Setting mask origin to border-box +### Comparing content, padding, and border + +This example demonstrates basic usage while comparing three values of the `mask-origin` property. -Click "Play" in the live sample to open the code in the MDN Playground and try some of the other possible `mask-origin` values. +#### HTML -```html live-sample___mask-origin-example -<div class="masked"></div> +We include four {{htmlelement("section")}} elements, each containing one {{htmlelement("div")}} element. + +```html +<section class="content"> + <div></div> +</section> +<section class="padding"> + <div></div> +</section> +<section class="border"> + <div></div> +</section> +<section class="comparison"> + <div></div> +</section> ``` -```css live-sample___mask-origin-example -.masked { +#### CSS + +We apply {{cssxref("border")}}, {{cssxref("padding")}}, and {{cssxref("margin")}} to every `<div>`. These create the reference points for the mask image origin. The `border` shorthand includes a {{cssxref("border-color")}}. We also include a {{cssxref("background-color")}}. These provide a green background and a blue border to mask. Finally, all our `<div>` elements are provided with a {{cssxref("mask-image")}}. + +```css +div { width: 100px; height: 100px; margin: 10px; border: 10px solid blue; background-color: #8cffa0; padding: 10px; - mask-image: url(https://mdn.github.io/shared-assets/images/examples/mask-star.svg); +} +section { + border: 1px solid black; +} +``` + +We give each `<div>` a different `mask-origin` value. + +```css +.content div { + mask-origin: content-box; +} + +.padding div { + mask-origin: padding-box; +} + +.border div { mask-origin: border-box; } + +.comparison div { + mask-image: none; +} ``` -{{EmbedLiveSample("mask-origin-example", "", "200px")}} +We also generate some text inside each `<section>` to indicate the mask origin for each `<div>` container. + +```css +section::before { + content: attr(class); + display: block; + text-align: center; +} +``` + +```css hidden +body { + display: flex; + flex-flow: row wrap; + gap: 10px; +} +``` + +#### Result + +{{EmbedLiveSample("Comparing content padding and border", "", "200")}} + +Notice the difference between the three values. In the first three boxes, respectively, the mask originates from: + +- The outside edge of the border. +- The inside border edge, which is the outer edge of the padding box. +- The inside padding edge, which is the outer edge of the content box. + +The fourth box has no `mask-image` specified: it is a reference image, included to allow you to easily visualize the extent of the content and padding areas. + +### Multiple values + +This example demonstrates using different `mask-origin` values for different `mask-image`s applied to a single element. + +#### HTML + +We include a single `<div>`. + +```html +<div></div> +``` + +#### CSS + +We apply three mask images instead of one, each with a different {{cssxref("mask-position")}}. We also set the mask images not to repeat. + +```css +div { + width: 120px; + height: 120px; + margin: 10px; + border: 10px solid blue; + background-color: #8cffa0; + padding: 10px; + mask-image: + url(https://mdn.github.io/shared-assets/images/examples/mask-star.svg), + url(https://mdn.github.io/shared-assets/images/examples/mask-star.svg), + url(https://mdn.github.io/shared-assets/images/examples/mask-star.svg); + mask-position: + top left, + top right, + bottom center; + mask-repeat: no-repeat; + mask-origin: content-box, border-box; +} +``` + +#### Results + +{{EmbedLiveSample("Multiple values", "", "200")}} + +We have three `mask-image` values, but only two `mask-origin` values. This means the `mask-origin` values are repeated, as if we had set `mask-origin: content-box, padding-box, content-box;`. The `border-box` star, the only mask overlapping the border, is the top-right star. ## Specifications @@ -106,4 +223,9 @@ Click "Play" in the live sample to open the code in the MDN Playground and try s ## See also -- [Clipping and Masking in CSS](https://css-tricks.com/clipping-masking-css/) +- {{cssxref("mask-image")}} +- {{cssxref("mask-position")}} +- {{cssxref("mask-repeat")}} +- {{cssxref("mask-size")}} +- {{cssxref("mask")}} shorthand +- [CSS masking](/en-US/docs/Web/CSS/CSS_masking) module diff --git a/files/en-us/web/css/mask-position/index.md b/files/en-us/web/css/mask-position/index.md index de718f718af2eb5..9cbdbfcef15b215 100644 --- a/files/en-us/web/css/mask-position/index.md +++ b/files/en-us/web/css/mask-position/index.md @@ -12,20 +12,39 @@ The **`mask-position`** [CSS](/en-US/docs/Web/CSS) property sets the initial pos ## Syntax ```css -/* Keyword values */ -mask-position: top; -mask-position: bottom; +/* Single <position> keyword value */ +/* Sets second value to 'center' */ mask-position: left; -mask-position: right; mask-position: center; +mask-position: right; +mask-position: top; +mask-position: bottom; -/* <position> values */ +/* Two <position> keyword values */ +mask-position: left center; +mask-position: right top; + +/* One length or percentage <position> value */ +/* Horizontal position. Vertical position set to 'center' */ +mask-position: 25%; +mask-position: 0px; +mask-position: 8em; + +/* Two length or percentage <position> values */ +/* First value: horizontal position. Second value: vertical position */ mask-position: 25% 75%; mask-position: 0px 0px; mask-position: 10% 8em; -/* Multiple values */ -mask-position: top right; +/* Edge offsets: Four <position> values */ +mask-position: bottom 10px right 20px; +mask-position: right 3em bottom 10px; +mask-position: bottom 10px right 0; + +/* Multiple <position> values */ +mask-position: + top left, + bottom 10px right 10px; mask-position: 1rem 1rem, center; @@ -38,12 +57,72 @@ mask-position: revert-layer; mask-position: unset; ``` -One or more `<position>` values, separated by commas. - ### Values +One or more `<position>` values, separated by commas. + - {{cssxref("&lt;position&gt;")}} - - : One to four values representing a 2D position regarding the edges of the element's box. Relative or absolute offsets can be given. Note that the position can be set outside of the element's box. + - : One, two, or four values representing a 2D position specifying the edges of the element's box. Relative or absolute offsets can be given. + +## Description + +The `mask-position` property defines the position of each mask layer. An element can have multiple mask layers applied. The number of layers is determined by the number of comma-separated values in the {{cssxref("mask-image")}} property value (even `none` values create a layer). + +Each `mask-position` value in the comma-separated list of values is matched up with an associated mask layer as defined by the list of `mask-image` values, in order. If the number of values in the two properties differs: + +- If `mask-position` has more values than mask-image, the excess values of `mask-position` are not used. +- If `mask-position` has fewer values than mask-image, the `mask-position` values are repeated. + +Each `mask-position` defines the associated mask layer's position relative to the associated {{cssxref("mask-origin")}} value. The `mask-origin` property values are similarly matched up with the `mask-image` values, in order, with excess `mask-position` values being unused or `mask-position` values being repeated if they are fewer in number than the `mask-origin` values. Each mask layer, therefore, has an associated `mask-origin` and `mask-position` value. + +If no `mask-origin` is set, the value defaults to `padding-box`, meaning the origin of each `mask-position` is the element's [padding-box](/en-US/docs/Web/CSS/box-edge#padding-box). + +### One-value syntax + +If only one `mask-position` value is specified, the second value is assumed to be `center`. If the value is a `<length>` or `<percentage>`, it defines the position of the mask along the horizontal axis, with the mask being vertically centered within the origin box. For example, `mask-position: 0%;` is equal to `mask-position: 0% center`. + +If you use a single keyword for positioning, the other value will resolve to `center`. The default of `mask-position` is `0% 0%`, which equates to `mask-position: top left`. However: + +- `mask-position: top;` is equivalent to `mask-position: top center;`. +- `mask-position: left;` is equivalent to `mask-position: center left`. +- `mask-position: center;` is equal to `mask-position: center center`. + +If the value is a {{cssxref("&lt;length&gt;")}} value, it represents the horizontal position as an offset from the left edge of the mask positioning. A positive value represents an offset inward from the left edge of the box container. The position can be set outside of the element's box using a negative value — this creates an outward offset that places the item outside the container's left edge. + +#### Percentage values + +A {{cssxref("&lt;percentage&gt;")}} value represents the mask's horizontal position value relative to the width of the container, positioned relative to the left edge. However, the offset is not from the mask edge to the box edge. Instead, the mask image dimension is [subtracted from the container's dimension](/en-US/docs/Web/CSS/background-position#regarding_percentages), and then a percentage of the resulting value is used as the direct offset from the box's left edge, which is the same as [percentage values for `background-position`](/en-US/docs/Web/CSS/background-position#regarding_percentages). + +The equation is: + +`(container dimension - mask dimension) * position percentage = dimension offset value` + +Given a `100px`-wide mask and a `1000px`-wide origin box, setting `mask-position: 10%;` (the equivalent of `10% 50%`) results in the mask being vertically centered at `90px` from the left edge. The equation is `(1000 - 100) * 10% = 90`. If the left offset had been `0%`, the mask's left edge would be flush to the left of the container (`(1000 - 100) * 0% = 0`). + +If the left offset had been `100%`, the mask's right edge would be flush to the right of the container as the left edge of the `100px` wide mask would be `900px` (`(1000 - 100) * 100% = 900`) from the left edge of the container (the `100px` mask width plus `900px` distance from the left edge means the right edge would be `1000px` from the left edge, which is the right edge of the container). + +### Two-value syntax + +A two-value `<position>` specifies the position of the mask image inside its mask positioning area, with length and percentage values specifying offsets from the `left` and `top` of the area. + +If the two values are {{cssxref("&lt;length&gt;")}} values, {{cssxref("&lt;percentage&gt;")}} values, or the keyword `center`, the first value represents the horizontal position as an offset from the left edge of the mask positioning area, and the second value represents the vertical position as an offset from it's top edge, with [percentages being offset](#percentage_values) by the mask's size in that dimension. + +In addition, if {{cssxref("&lt;percentage&gt;")}} values are specified, the first value is also the horizontal position value relative to the left edge, and the second value is also the vertical position value relative to the top edge. + +A pair of axis-specific keywords can be reordered, as can an axis-specific keyword and a length or percentage, but two length or percentage values are not interchangeable. +If one of the two values is `top`, `right`, `bottom`, or `left`, the order of the two values doesn't matter. Any `center` or `<length-percentage>` value in the pair of values will be applied to the other dimension. + +### Four-value syntax + +The four-value syntax consists of two pairs of values, each pair containing a keyword specifying the edge to offset from, and a `<length>` and `<percentage>` value specifying the offset distance. For example, `mask-position: left 1em top 2em` specifies a `1em` horizontal offset from the left box edge and a `2em` vertical offset from the top edge. The two-value equivalent would be `mask-position: 1em 2em`. + +Because we're defining the offset edges when using the four-value syntax, the order isn't important: `mask-position: top 2em left 1em` and `mask-position: left 1em top 2em` both produce the same result. + +The real power of the four-value syntax is that it allows us to specify offset edges other than `left` and `top`. For example, `mask-position: bottom 10px right 20px` creates a `10px` vertical offset up from the bottom edge and a `20px` horizontal offset leftward from the right edge. Usually, the four-value syntax is used to offset from the bottom and/or right. But this syntax is also helpful if you can't remember the offset edge order for the two-value syntax. + +One thing to note is that, unlike the `<bg-position>` data type values for {{cssxref("background-position")}}, the `<position>` values for `mask-position` do not allow for a 3-value syntax and do not allow offsetting from `center`. When offsetting the mask from the `bottom` or `right`, the `mask-position` requires all four values to be declared. + +For the four-value syntax to be valid, it needs to specify either `top` or `bottom` as the vertical offset edge, along with the vertical length or percentage offset value, and either `left` or `right` as the horizontal offset edge, along with the horizontal length or percentage offset value. ## Formal definition @@ -55,24 +134,22 @@ One or more `<position>` values, separated by commas. ## Examples -### Setting mask position - -Click "Play" in the live sample to open the code in the MDN Playground and change the `mask-position` value to any of the allowed values detailed above. +### Basic usage -```html live-sample___mask-position-example -<div id="wrapper"> - <div class="masked"></div> -</div> +```html +<section> + <div></div> +</section> ``` -```css live-sample___mask-position-example -#wrapper { +```css +section { border: 1px solid black; width: 250px; height: 250px; } -.masked { +div { width: 250px; height: 250px; margin-bottom: 10px; @@ -84,7 +161,7 @@ Click "Play" in the live sample to open the code in the MDN Playground and chang } ``` -{{EmbedLiveSample("mask-position-example", "", "300px")}} +{{EmbedLiveSample("basic usage", "", "300px")}} ## Specifications @@ -96,4 +173,11 @@ Click "Play" in the live sample to open the code in the MDN Playground and chang ## See also -- [Clipping and Masking in CSS](https://css-tricks.com/clipping-masking-css/) +- {{cssxref("mask-image")}} +- {{cssxref("mask-origin")}} +- {{cssxref("mask-repeat")}} +- {{cssxref("mask-size")}} +- {{cssxref("mask")}} shorthand +- [CSS masking](/en-US/docs/Web/CSS/CSS_masking) module +- {{cssxref("background-position")}} +- {{cssxref("&lt;position&gt;")}} diff --git a/files/en-us/web/css/mask-repeat/index.md b/files/en-us/web/css/mask-repeat/index.md index 6a66ac3fa3d5972..c8efae000bd1fef 100644 --- a/files/en-us/web/css/mask-repeat/index.md +++ b/files/en-us/web/css/mask-repeat/index.md @@ -9,8 +9,6 @@ browser-compat: css.properties.mask-repeat The **`mask-repeat`** [CSS](/en-US/docs/Web/CSS) property sets how mask images are repeated. A mask image can be repeated along the horizontal axis, the vertical axis, both axes, or not repeated at all. -By default, the repeated images are clipped to the size of the element, but they can be scaled to fit (using `round`) or evenly distributed from end to end (using `space`). - ## Syntax ```css @@ -45,94 +43,111 @@ mask-repeat: revert-layer; mask-repeat: unset; ``` -One or more `<repeat-style>` values, separated by commas. - ### Values -- `<repeat-style>` - - - : The one-value syntax is a shorthand for the full two-value syntax: - - <table class="standard-table"> - <thead> - <tr> - <th>Single value</th> - <th>Two-value equivalent</th> - </tr> - </thead> - <tbody> - <tr> - <td><code>repeat-x</code></td> - <td><code>repeat no-repeat</code></td> - </tr> - <tr> - <td><code>repeat-y</code></td> - <td><code>no-repeat repeat</code></td> - </tr> - <tr> - <td><code>repeat</code></td> - <td><code>repeat repeat</code></td> - </tr> - <tr> - <td><code>space</code></td> - <td><code>space space</code></td> - </tr> - <tr> - <td><code>round</code></td> - <td><code>round round</code></td> - </tr> - <tr> - <td><code>no-repeat</code></td> - <td><code>no-repeat no-repeat</code></td> - </tr> - </tbody> - </table> - - In the two-value syntax, the first value represents the horizontal repetition behavior and the second value represents the vertical behavior. Here is an explanation of how each option works for either direction: - - <table class="standard-table"> - <tbody> - <tr> - <td><code>repeat</code></td> - <td> - The image is repeated as much as needed to cover the whole mask painting - area. The last image will be clipped if it doesn't fit. - </td> - </tr> - <tr> - <td><code>space</code></td> - <td> - The image is repeated as much as possible without clipping. The first - and last images are pinned to either side of the element, and whitespace - is distributed evenly between the images. The - {{cssxref("mask-position")}} property is ignored unless only one - image can be displayed without clipping. The only case where clipping - happens using <code>space</code> is when there isn't enough room to - display one image. - </td> - </tr> - <tr> - <td><code>round</code></td> - <td> - As the allowed space increases in size, the repeated images will stretch - (leaving no gaps) until there is room for another one to be added. When - the next image is added, all of the current ones compress to allow room. - Example: An image with an original width of 260px, repeated three times, - might stretch until each repetition is 300px wide, and then another - image will be added. They will then compress to 225px. - </td> - </tr> - <tr> - <td><code>no-repeat</code></td> - <td> - The image is not repeated (and hence the mask painting area will not - necessarily be entirely covered). The position of the non-repeated mask - image is defined by the {{cssxref("mask-position")}} CSS - property. - </td> - </tr> - </tbody> - </table> +The `mask-repeat` property is a comma-separated list of two `<repeat-style>` values, +with the first `<repeat-style>` value being the horizontal repetition value and the second value the vertical repetition value, or one keyword value that is a shorthand for two `<repeat-style>` values. + +#### `<repeat-style>` values + +The `<repeat-style>` values include: + +- `repeat` + + - : The image is repeated as much as needed to cover the whole mask painting area. Mask images along the edges are clipped when the size of the [mask origin box](/en-US/docs/Web/CSS/mask-origin) is not an exact multiple of the mask image's size. + +- `space` + + - : The mask image is repeated as many times as possible without clipping. If the element's origin size is at least twice the size as the mask image's size in the associated dimension, the {{cssxref("mask-position")}} property is ignored and the first and last images are positioned at the edges of the mask origin container. If the the mask origin box is not an exact multiple of the mask image's size, whitespace is distributed evenly between the repeated mask images. + + If the origin box size is less than twice the mask image's size in the given dimension, only one mask image can be displayed. In this case, the image is positioned as defined by the `mask-position` property, which defaults to `0% 0%`. The mask image will only be clipped if the mask image is larger than the mask origin box. + +- `round` + + - : The mask image is repeated as many times as possible in its original dimensions. If the size of the mask origin box is not an exact multiple of the mask image's size, all mask images will be rescaled, [shrinking or stretching](#rounded_repetitions) to ensure no repetitions are clipped. + +- `no-repeat` + + - : The mask image is not repeated (and hence the mask painting area will not necessarily be entirely covered). The position of the non-repeated mask image is defined by the {{cssxref("mask-position")}} CSS property. + +#### Shorthand values + +The one-value syntax is a shorthand for the full two-value syntax: + +<table class="standard-table"> + <thead> + <tr> + <th>Single value</th> + <th>Two-value equivalent</th> + </tr> + </thead> + <tbody> + <tr> + <td><code>repeat-x</code></td> + <td><code>repeat no-repeat</code></td> + </tr> + <tr> + <td><code>repeat-y</code></td> + <td><code>no-repeat repeat</code></td> + </tr> + <tr> + <td><code>repeat</code></td> + <td><code>repeat repeat</code></td> + </tr> + <tr> + <td><code>space</code></td> + <td><code>space space</code></td> + </tr> + <tr> + <td><code>round</code></td> + <td><code>round round</code></td> + </tr> + <tr> + <td><code>no-repeat</code></td> + <td><code>no-repeat no-repeat</code></td> + </tr> + </tbody> +</table> + +- `repeat-x` + + - : The equivalent of `repeat no-repeat`. The image is repeated in the horizontal direction as many times as needed to cover the width of the mask painting area. Mask images along the right or left edges, or both depending on the {{cssxref("mask-position")}} value, will be clipped if the width of the mask origin box is not an exact multiple of the mask image's width. + +- `repeat-y` + + - : The equivalent of `no-repeat repeat`. The image is repeated in the vertical direction as many times as needed to cover the height of the mask painting area. Mask images along the top or bottom edges, or both depending on the {{cssxref("mask-position")}} value, will be clipped if the height of the mask origin box is not an exact multiple of the mask image's height. + +## Description + +The `mask-repeat` property accepts a comma-separated pair of values or one [shorthand value](#shorthand_values). In the two-value syntax, the first value represents the horizontal repetition behavior and the second value represents the vertical behavior. + +### Multiple values + +Each `mask-repeat` value in this comma-separated list applies to a separate mask layer. An element can have multiple mask layers applied. The number of layers is determined by the number of comma-separated values in the {{cssxref("mask-image")}} property value (even if a value is `none`). Each `mask-repeat` value is matched up with the `mask-image` values, in order. If the number of values in the two properties differs, any excess values of `mask-repeat` values are ignored, or, if `mask-repeat` has fewer values than `mask-image`, the `mask-repeat` values are repeated. + +### Sizing and positioning + +The `mask-repeat` property value defines how mask images are tiled after they have been [sized](/en-US/docs/Web/CSS/mask-size) and [positioned](/en-US/docs/Web/CSS/mask-position). The first (and possibly only) mask-image repetition is positioned by the {{cssxref("mask-position")}} property, which defaults to `0% 0%`, the top-left corner of the origin box. The size is defined by the {{cssxref("mask-size")}} property, which defaults to `auto`. The positions of the repeated masks are based on this initial mask instance. + +### Clipping + +Mask images will not repeat but will be clipped if the mask image's size is larger than the origin box, except in the case of `round`, where a single mask will be scaled down to fit the origin box. + +With `repeat` values, mask images may be clipped at the edge of the origin box if the dimension (width or height) of the box is not an exact multiple of the mask's. + +### Aspect ratio + +By default, mask images maintain the aspect ratio set by the {{cssxref("mask-size")}} property or their default aspect ratio if the `mask-size` defaults to or is explicitly set to `auto`. Only in the case of `round` value in both directions might the mask aspect ratio be distorted. + +If `round` is set in both directions, the resulting repeated mask images will match the aspect ratio of the origin box. As the mask images are scaled to fit, they may be distorted, ensuring the mask images are not clipped. If `round` is set in only one dimension, the aspect ratio of the mask size is respected. + +### Rounded repetitions + +In the case of `round`, mask images are scaled up or down to fit the mask image in the positioning area a whole number of times. The mask size increases or decreases to fit the nearest natural number or masks, with a minimum of one mask. + +The rendered dimensions of the mask is the size of the origin box divided by the number of iterations of masks in that dimension, where the iterations being an integer greater than zero. The number of iterations is: `X' = D / round(D / X)` where `D` is the width or height, and `round()` is a function that returns the nearest integer greater than zero. + +For example, if `mask-repeat` is set to `round` and the `mask-size` sets the mask to be `40px` wide, when the origin box is present (greater than `0px` wide) but less than `60px` wide, there will be a single iteration that is 100% of the width of that box. If the box is at least `60px` wide but less than `100px` wide, there will be two iterations that are each `50%` of the box. From 100px to 140px, three masks will fit along the horizontal axis. These "`40px`-wide" masks will only be `40px` wide if the origin box is an exact multiple of `40px`. ## Formal definition @@ -144,38 +159,201 @@ One or more `<repeat-style>` values, separated by commas. ## Examples -### Setting repeat for a single mask +### Basic usage + +This example demonstrates setting the `mask-repeat` property for a single mask. + +#### HTML + +Our HTML includes a basic {{htmlelement("div")}} element: + +```html +<div></div> +``` + +#### CSS + +We define a `250px` square with a red to blue gradient with a `100px` by `100px` star as a mask image. We use the `mask-repeat` property, setting `round` for the horizontal direction and `space` for the vertical value. + +```css +div { + width: 250px; + height: 250px; + background-image: linear-gradient(red, blue); + + mask-image: url(https://mdn.github.io/shared-assets/images/examples/mask-star.svg); + mask-size: 100px 100px; + + mask-repeat: round space; +} +``` + +#### Results + +{{EmbedLiveSample("basic usage", "", "300px")}} -```html live-sample___mask-repeat-example -<div class="masked"></div> +With `space` and `round` on a mask image that is smaller than the origin box, the mask is not clipped. Rather, the `round` value distorts the star to prevent clipping and preventing white space, while `space` maintains the star's aspect ratio, but adds space as needed between masks. + +### Round iterations + +Using the same HTML and CSS, this demonstration includes a slider that changes the width of the container to show how, with `round`, masks will grow as space allows until another iteration of the mask fits, or shrink until the number of iterations no longer fits. + +```html hidden +<div></div> +<label + >width: <output></output><br /> + <input type="range" min="0" max="400" value="250" id="width" /> +</label> ``` -```css live-sample___mask-repeat-example -.masked { +```css hidden +div { width: 250px; height: 250px; - background: blue linear-gradient(red, blue); - margin-bottom: 10px; + background-image: linear-gradient(red, blue); + + mask-image: url(https://mdn.github.io/shared-assets/images/examples/mask-star.svg); + mask-size: 100px 100px; + + mask-repeat: round space; +} +input { + clear: both; + width: 90%; +} +``` + +```js hidden +const div = document.querySelector("div"); +const range = document.getElementById("width"); +const output = document.querySelector("output"); + +range.addEventListener("change", () => { + const value = `${range.value}px`; + output.innerText = value; + div.style.width = value; +}); +``` + +{{EmbedLiveSample("round iterations", "", "300px")}} + +The mask is defined as `100px` wide. There is a single star when the origin box is from `1px` to `149px` wide, two stars from `150px` to `249px`, three stars from `250px` to `349px`, and so on. + +### The shorthand values + +This examples demonstrates all `mask-repeat` shorthand (single-keyword) values. + +#### HTML + +We include several {{htmlelement("section")}} elements each containing a `<div>`, each with a different class name. + +```html +<section class="repeat"> + <div></div> +</section> +<section class="space"> + <div></div> +</section> +<section class="round"> + <div></div> +</section> +<section class="no-repeat"> + <div></div> +</section> +<section class="repeat-x"> + <div></div> +</section> +<section class="repeat-y"> + <div></div> +</section> +``` + +#### CSS + +We give every `<div>` the same CSS, except for the `mask-repeat` value, which we match to their parent's class name. We define a mask size, setting the initial `mask-image` at the bottom right, meaning any clipping will occur on the top-most and left-most masks, on their top and left sides. + +```css +div { + width: 180px; + height: 180px; + background-image: linear-gradient(red, blue); mask-image: url(https://mdn.github.io/shared-assets/images/examples/mask-star.svg); + + mask-size: 50px 50px; + mask-position: bottom right; +} + +.repeat div { mask-repeat: repeat; } +.space div { + mask-repeat: space; +} +.round div { + mask-repeat: round; +} +.no-repeat div { + mask-repeat: no-repeat; +} +.repeat-x div { + mask-repeat: repeat-x; +} +.repeat-y div { + mask-repeat: repeat-y; +} +``` + +We display the class name using generated content. + +```css +section::before { + content: attr(class); + display: block; + text-align: center; + border-bottom: 1px solid; +} +``` + +```css hidden +body { + display: flex; + flex-flow: row wrap; + gap: 10px; +} +section { + border: 1px solid; +} ``` -{{EmbedLiveSample("mask-repeat-example", "", "300px")}} +#### Results + +{{EmbedLiveSample("The shorthand values", "", "450px")}} -### Multiple mask image support +The first (and, in the case of `no-repeat`, only) mask star is [sized](/en-US/docs/Web/CSS/mask-size) to be 50px by 50px, and [positioned](/en-US/docs/Web/CSS/mask-position) at the bottom-right of the painting area, with repeated stars placed above and/or to the left of it with any clipping occurring on the top and left of the top-most and left-most stars. Note that all the stars are the same size and shape, except for `round`, where all the masks shrank to 45px x 45px to fit four complete masks in each direction. Had the container been 174px, there would have been three stars in each direction, instead of four, and each star would have been stretched. + +### Multiple mask images and repeats You can specify a different `<repeat-style>` for each mask image, separated by commas: ```css -.example-three { +.extra-repeats { mask-image: url("mask1.png"), url("mask2.png"); + mask-repeat: repeat-x, repeat-y, space; +} +``` + +Each image is matched with the corresponding repeat style. As there are more `mask-repeat` values than `mask-image` values, the excess `mask-repeat` values are ignored. + +```css +.missing-repeats { + mask-image: + url("mask1.png"), url("mask2.png"), url("mask3.png"), url("mask4.png"); mask-repeat: repeat-x, repeat-y; } ``` -Each image is matched with the corresponding repeat style, from first specified to last. +Each image is matched with a corresponding repeat style. As there are more `mask-image` values than `mask-repeat` values, the `mask-repeat` is repeated until every `mask-image` has an associated `mask-repeat` value. Here, odd numbered masks repeat along the x-axis, while the even numbered masks repeat along the y-axis. ## Specifications diff --git a/files/en-us/web/css/mask-size/index.md b/files/en-us/web/css/mask-size/index.md index 2061adc7b5dbd91..e5160fef5242566 100644 --- a/files/en-us/web/css/mask-size/index.md +++ b/files/en-us/web/css/mask-size/index.md @@ -7,36 +7,34 @@ browser-compat: css.properties.mask-size {{CSSRef}} -The **`mask-size`** [CSS](/en-US/docs/Web/CSS) property specifies the sizes of the mask images. The size of the image can be fully or partially constrained in order to preserve its intrinsic ratio. - -> [!NOTE] -> If the value of this property is not set in a {{cssxref("mask")}} shorthand property that is applied to the element after the `mask-size` CSS property, the value of this property is then reset to its initial value by the shorthand property. +The **`mask-size`** [CSS](/en-US/docs/Web/CSS) property specifies the sizes of specified mask images. Mask image sizes can be fully or partially constrained to preserve their {{glossary("aspect ratio", "intrinsic aspect ratios")}}. ## Syntax ```css -/* Keywords syntax */ +/* Keyword syntax */ mask-size: cover; mask-size: contain; +mask-size: auto; /* One-value syntax */ -/* the width of the image (height set to 'auto') */ +/* Mask width. Sets height to 'auto'. */ mask-size: 50%; mask-size: 3em; mask-size: 12px; -mask-size: auto; /* Two-value syntax */ -/* first value: width of the image, second value: height */ -mask-size: 50% auto; +/* First value: mask width. Second value: mask height */ mask-size: 3em 25%; mask-size: auto 6px; -mask-size: auto auto; +mask-size: auto 50%; /* Multiple values */ -/* Do not confuse this with mask-size: auto auto */ -mask-size: auto, auto; -mask-size: 50%, 25%, 25%; +mask-size: auto, contain; +mask-size: + 50%, + 50% 25%, + auto 25%; mask-size: 6px, auto, contain; /* Global values */ @@ -47,46 +45,58 @@ mask-size: revert-layer; mask-size: unset; ``` -One or more `<bg-size>` values, separated by commas. +### Values -A `<bg-size>` can be specified in one of three ways: +The `mask-size` property accepts a comma-separated list of `<bg-size>` values. A `<bg-size>` value is either `cover`, `contain`, a pair of values specifying the width and height (in that order), or a single value specifying the width (in which case, the height is set to `auto`). Values include: -- using the keyword `contain` -- using the keyword `cover` -- using width and height values +- `contain` -To specify a size using width and height, you can supply one or two values: + - : Scales the mask image up or down, while preserving its aspect-ratio, making the mask as large as possible within its container without cropping or stretching it. + If the mask image is smaller than the container, the mask will tile, or repeat, unless the {{cssxref("mask-repeat")}} property is set to `no-repeat`. -- If only one value is given it sets the width, with the height set to `auto`. -- If two values are given, the first sets width and the second sets height. +- `cover` -Each value can be a `<length>`, a `<percentage>`, or `auto`. + - : Scales the mask image to the smallest possible size to fill the container while preserving its aspect ratio. If the aspect ratio of the mask image differs from the element, it will be cropped vertically or horizontally. -### Values - -- `<length>` - - : A {{cssxref("&lt;length&gt;")}} value scales the mask image to the specified length in the corresponding dimension. Negative lengths are not allowed. -- `<percentage>` - - : A {{cssxref("&lt;percentage&gt;")}} value scales the mask image in the corresponding dimension to the specified percentage of the mask positioning area, which is determined by the value of {{cssxref("mask-origin")}}. The mask positioning area is, by default, the area containing the content of the box and its padding; the area may also be changed to just the content or to the area containing borders, padding and content. Negative percentages are not allowed. - `auto` - - : A keyword that scales the mask image in the corresponding directions in order to maintain its intrinsic proportion. -- `contain` - - : A keyword that scales the image as large as possible and maintains the image's {{glossary("aspect ratio")}} (the image doesn't get squished). The image is _letterboxed_ within the container. The image is automatically centered unless overridden by another property such as {{cssxref("mask-position")}}. -- `cover` - - : A keyword that is the inverse of `contain`. Scales the image as large as possible and maintains image aspect ratio (image doesn't get squished). The image "covers" the entire width or height of the container. When the image and container have different dimensions, _the image is clipped_ either on left/right or at top/bottom. -The interpretation of possible values depends on the image's intrinsic dimensions (width and height) and intrinsic proportion (ratio of width and height). A bitmap image always has intrinsic dimensions and an intrinsic proportion. A vector image may have both intrinsic dimensions and thus it has an intrinsic proportion too. It also may have one or no intrinsic dimensions and in either case it might or might not have an intrinsic proportion. Gradients are treated as images with no intrinsic dimensions or intrinsic proportion. + - : Maintains the original aspect ratio of the mask source. When set for both the width and height, the origin size of the mask resource is used. Otherwise, `auto` scales the mask image in the corresponding direction such that its original aspect ratio is maintained. + +- {{cssxref("&lt;length&gt;")}} + + - : Renders the mask image at the specified length in the corresponding dimension (width if set as the first or only value, height if set as the second value). Negative values are not allowed. + +- {{cssxref("&lt;percentage&gt;")}} + - : Renders the mask image in the corresponding dimension to the specified percentage of the box origin area as defined by the {{cssxref("mask-origin")}} property, which defaults to `padding-box`. Negative values are not allowed. -The rendered size of the mask image is then computed as follows: +## Description -- If both components of `mask-size` are specified and are not `auto`: - - : The mask image renders at the specified size. -- If the `mask-size` is `contain` or `cover`: - - : The image is rendered by preserving its intrinsic proportion at the largest size contained within or covering the mask positioning area. If the image has no intrinsic proportion, then it is rendered at the size of the mask positioning area. -- If the `mask-size` is `auto` or `auto auto`: - - : If the image has both intrinsic dimensions, it is rendered at that size. If it has no intrinsic dimensions and no intrinsic proportion, it is rendered at the size of the mask positioning area. If it has no dimensions but has a proportion, it's rendered as if `contain` had been specified instead. If the image has one intrinsic dimension and a proportion, it's rendered at the size determined by that one dimension and the proportion. If the image has one intrinsic dimension but no proportion, it's rendered using the intrinsic dimension and the corresponding dimension of the mask positioning area. -- If `mask-size` has one `auto` component and one non-`auto` component: - - : If the image has an intrinsic proportion, then render it using the specified dimension and compute the other dimension from the specified dimension and the intrinsic proportion. If the image has no intrinsic proportion, use the specified dimension for that dimension. For the other dimension, use the image's corresponding intrinsic dimension if there is one. If there is no such intrinsic dimension, use the corresponding dimension of the mask positioning area. +The `mask-size` property is used to size mask layers. + +An element can have multiple mask layers applied. The number of mask layers is determined by the number of comma-separated values in the {{cssxref("mask-image")}} property value (a value creates a mask layer, even if it is `none`). + +Each `mask-size` value in the comma-separated list of values is matched up with an associated mask layer as defined by the list of `mask-image` values, in order. If the number of values in the two properties differs: + +- If `mask-size` has more values than `mask-image`, the excess values of `mask-size` are not used. +- If `mask-size` has fewer values than `mask-image`, the `mask-size` values are repeated. + +Each `mask-size` value is a `<bg-size>` value. There are three ways to declare each `<bg-size>`: one keyword, two lengths, percentages or the keyword `auto`, or one length, percentage, or `auto`: + +- The available keywords are `cover` and `contain`. +- When two values are specified, the first defines the mask width and the second defines its height. +- When one value is specified, it defines only the mask width, with the height set to `auto`. + +The width and height values are a {{cssxref("&lt;length&gt;")}}, a {{cssxref("&lt;percentage&gt;")}}, or the `auto` keyword, which is the default. Setting one or both values to `auto` maintains the mask image's original aspect ratio. + +The rendered size of the mask image is computed as follows: + +- If both components of `mask-size` are specified and are not `auto`, the mask image renders at the specified size. +- If the `mask-size` is `contain` or `cover`, the image is rendered by preserving its aspect ratio at the largest size contained within or covering the mask positioning area. If the image has no intrinsic proportion, such as with gradients, then it is rendered at the size of the mask positioning area. +- If the `mask-size` is `auto` (which resolves to `auto auto`), it is rendered at the size at which the mask would be displayed if no CSS were applied to change the rendering; this is its {{glossary("intrinsic size")}}. If it has no intrinsic dimensions and no intrinsic proportion, as is the case with [CSS gradients](/en-US/docs/Web/CSS/gradient), it is rendered at the size of the mask positioning area, defined by the {{cssxref("mask-origin")}} (which defaults to `border-box`). + If the mask source has no dimensions but has a proportion (aspect-ratio), a value of `auto` will render it as if `contain` had been specified instead. If the image has one intrinsic dimension and a proportion, it is rendered at the size determined by that one dimension and the proportion. If the image has one intrinsic dimension but no proportion, it's rendered using the intrinsic dimension and the corresponding dimension of the mask positioning area. +- If `mask-size` has one `auto` component and one non-`auto` component, which applies to all single-value values, the aspect ratio is maintained if the mask source has an intrinsic proportion. If there are no intrinsic proportions, the `auto` value is assumed to be the dimension of the mask positioning area. + +Like with all longhand components of shorthand property, if the {{cssxref("mask")}} shorthand property is set and the value of the `mask-size` property is not defined within any mask layer, the `mask-size` value is reset to its initial value of `auto` for those mask layers. ## Formal definition @@ -100,23 +110,196 @@ The rendered size of the mask image is then computed as follows: ### Setting mask size as a percentage -```html live-sample___mask-size-example -<div class="masked"></div> +This example demonstrates basic usage, while also demonstrating percentage values for `mask-size`. + +#### HTML + +We include two {{htmlelement("div")}} elements: + +```html +<div class="width"></div> +<div class="height"></div> ``` -```css live-sample___mask-size-example -.masked { +#### CSS + +The `<div>` elements are defined to be twice as tall as they are wide, with a gradient background and mask: + +```css +div { width: 200px; - height: 200px; + height: 400px; background: blue linear-gradient(red, blue); - margin-bottom: 10px; - mask-image: url(https://mdn.github.io/shared-assets/images/examples/mdn.svg); +} +``` + +The width of one `<div>` element's mask is set to `50%`, with the height defaulting to `auto`. The mask's height for the second `<div>` element is set to `50%` with the width set to `auto`: + +```css +.width { mask-size: 50%; } + +.height { + mask-size: auto 50%; +} +``` + +In the `width` case, the mask is rendered `100px` wide (`50%` of the `200px`-wide element). The height defaults to `auto`, maintaining the mask's aspect ratio. +In the `height` case, the mask is rendered `200px` tall (`50%` of the `400px`-high container). The width is explicitly set to `auto`, maintaining the mask's aspect ratio. + +```css hidden +body { + display: flex; + gap: 20px; +} +``` + +#### Results + +{{EmbedLiveSample("Setting mask size as a percentage", "", "430px")}} + +### Cover and contain + +This example demonstrates the keyword values for `mask-size`. + +#### HTML + +Three {{htmlelement("section")}} elements are defined, each with a different class name, and each containing a `<div>`. + +```html +<section class="auto"> + <div></div> +</section> +<section class="cover"> + <div></div> +</section> +<section class="contain"> + <div></div> +</section> +``` + +#### CSS + +The `<div>` elements are defined to be twice as tall as they are wide, with a gradient background and mask: + +```css +div { + width: 200px; + height: 400px; + background: blue linear-gradient(red, blue); + mask-image: url(https://mdn.github.io/shared-assets/images/examples/mask-star.svg); +} +``` + +The `mask-size` of two of the `<div>` elements is set to one of the property's keyword values. The third `<div>` has a `mask-size` of `auto` set demonstrating the original intrinsic dimensions of the mask: + +```css +.auto div { + mask-size: auto; +} + +.cover div { + mask-size: cover; +} + +.contain div { + mask-size: contain; +} ``` -{{EmbedLiveSample("mask-size-example", "", "250px")}} +The property values is displayed using [generated content](/en-US/docs/Web/CSS/CSS_generated_content). + +```css +section::before { + content: "mask-size: " attr(class) ";"; + display: block; + text-align: center; + border-bottom: 1px solid; +} +``` + +```css hidden +body { + display: flex; + flex-flow: row wrap; + gap: 10px; +} +section { + border: 1px solid; +} +``` + +#### Results + +{{EmbedLiveSample("Cover and contain", "", "430px")}} + +With `auto`, the star is displayed at its intrinsic `100px` by `100px` size. With `cover`, the star grows to be `400px` tall, covering the entire origin box. With `contain`, the star grows until one dimension equals the same dimension of the [origin box](/en-US/docs/Web/CSS/mask-origin), meaning that the star is as large as it can be (`200px` wide) but still contained by it. + +### When the mask is larger than the container + +Using the same HTML and CSS as above, with just a different origin box size, this example explores what happens when the origin box is smaller than the intrinsic dimensions of the mask. + +```html hidden +<section class="auto"> + <div></div> +</section> +<section class="cover"> + <div></div> +</section> +<section class="contain"> + <div></div> +</section> +``` + +```css hidden +div { + background: blue linear-gradient(red, blue); + mask-image: url(https://mdn.github.io/shared-assets/images/examples/mask-star.svg); +} + +.auto div { + mask-size: auto; +} + +.cover div { + mask-size: cover; +} + +.contain div { + mask-size: contain; +} + +section::before { + content: attr(class); + display: block; + text-align: center; + border-bottom: 1px solid; +} + +body { + display: flex; + flex-flow: row wrap; + gap: 10px; +} +section { + border: 1px solid; +} +``` + +The only difference is the size of the containing box (and the generated content): + +```css +div { + width: 70px; + height: 70px; +} +``` + +{{EmbedLiveSample("When the mask is larger than the container", "", "120px")}} + +The `contain` value contains the mask within the origin box. The `cover` value covers it. In both cases, the mask shrinks while maintaining the original aspect ratio. With `auto`, the mask is clipped because the intrinsic dimensions are larger than the box dimensions. ## Specifications @@ -128,4 +311,12 @@ The rendered size of the mask image is then computed as follows: ## See also -- [Clipping and Masking in CSS](https://css-tricks.com/clipping-masking-css/) +- {{cssxref("mask")}} shorthand +- {{cssxref("mask-image")}} +- {{cssxref("mask-origin")}} +- {{cssxref("mask-position")}} +- {{cssxref("mask-repeat")}} +- {{cssxref("mask-image")}} +- {{cssxref("mask-border")}} +- {{cssxref("background-size")}} +- [CSS masking](/en-US/docs/Web/CSS/CSS_masking) module diff --git a/files/en-us/web/css/mask-type/index.md b/files/en-us/web/css/mask-type/index.md index 60105693bcc5d1b..c3978c4a1cb05f5 100644 --- a/files/en-us/web/css/mask-type/index.md +++ b/files/en-us/web/css/mask-type/index.md @@ -7,9 +7,7 @@ browser-compat: css.properties.mask-type {{CSSRef}} -The **`mask-type`** [CSS](/en-US/docs/Web/CSS) property sets whether an SVG {{svgElement("mask")}} element is used as a _luminance_ or an _alpha_ mask. It applies to the `<mask>` element itself. - -This property may be overridden by the {{cssxref("mask-mode")}} property, which has the same effect but applies to the element where the mask is used. Alpha masks will generally be faster to render. +The **`mask-type`** [CSS](/en-US/docs/Web/CSS) property applies to the SVG {{svgElement("mask")}} element. It defines whether to use the _luminance_ (brightness) or _alpha_ (transparency) content of the mask. This property may be overridden by the {{cssxref("mask-mode")}} property. The `mask-type` property has no effect on image or gradient masks. ## Syntax @@ -26,142 +24,132 @@ mask-type: revert-layer; mask-type: unset; ``` -The `mask-type` property is specified as one of the keyword values listed below. - ### Values -- `luminance` - - : Is a keyword indicating that the associated mask image is a luminance mask, i.e., that its [relative luminance](https://en.wikipedia.org/wiki/Luminance_%28relative%29) values must be used when applying it. - `alpha` - - : Is a keyword indicating that the associated mask image is an alpha mask, i.e., that its [alpha channel](https://en.wikipedia.org/wiki/Alpha_compositing) values must be used when applying it. + - : Indicates that the alpha (transparency) values of the `<mask>` should be used. +- `luminance` + - : Indicates that the [luminance (brightness) values](#understanding_luminance) of the `<mask>` should be used. -## Formal definition +## Description -{{cssinfo}} +The `mask-type` property is only relevant for the SVG `<mask>` element. If you set `mask-type: luminance`, the mask will use how bright each part of the mask is; if you set `mask-type: alpha`, it will use how transparent or opaque each part of the mask is. -## Formal syntax +### Default behavior -{{csssyntax}} +By default, the SVG `<mask>` element uses `mask-type: luminance`. This means both the color and the transparency of the mask content affect masking. Whether the mask is opaque partially depends on the lightness of the color of the opaque areas: -## Examples +- Fully opaque white areas (100% luminance) will be masked and visible. +- Black (0% luminance) or fully transparent areas will be clipped and invisible. +- Areas with intermediate luminance values will be partially masked, reflecting both the luminance, or lightness of the mask color, and the alpha transparency of each area of the mask. -### Setting an alpha mask +### Understanding luminance -#### HTML +The opacity of a `luminance` mask is determined by the `R`, `G`, `B`, and `A` values of an `rgb()` color using the following formula: -```html live-sample___mask-type-alpha-example -<section> - <div class="red-square"></div> -</section> - -<svg - version="1.1" - xmlns="http://www.w3.org/2000/svg" - xmlns:xlink="http://www.w3.org/1999/xlink" - width="0" - height="0"> - <defs> - <mask id="m" maskContentUnits="objectBoundingBox"> - <rect - x=".2" - y=".1" - width=".4" - height=".8" - fill="yellow" - fill-opacity="0.7" /> - </mask> - </defs> -</svg> -``` +`((0.2125 * R) + (0.7154 * G) + (0.0721 * B)) * A` -#### CSS +For example, the color `green` (`#008000` or `rgb(0% 50% 0% / 1)`) has a luminance value of `35.77%`. Any area masked by a solid `green` luminance mask will be `35.77%` visible. If the `mask-type` is set to `alpha`, the same fully opaque `green` color will make the masked area `100%` visible. -```css live-sample___mask-type-alpha-example -* { - margin: 0px; - padding: 0px; -} +If the SVG `<mask>` element has `fill="rgb(0 0 0 / 0.5)"`, which is a 50% transparent black, the corresponding shape on the masked element will display at 50% opacity when `mask-type` is set to `alpha` because the alpha values is `0.5` (50% opacity). But if the `mask-type` defaults to or is set as `luminance` the masked area will be fully clipped and invisible because its luminance is `0`. -section { - width: fit-content; - border: 1px solid blue; -} +### Effect of `mask-mode` on `mask-type` -.red-square { - height: 100px; - width: 100px; - background-color: red; - border: solid 1px black; - mask: url("#m"); -} +While the `mask-type` property is set on the SVG `<mask>` element, the {{cssxref("mask-mode")}} property is set on the element being masked (the element you're applying the mask to). +If the mask image source is not an SVG `<mask>`, this property has no effect. -mask { - mask-type: alpha; -} -``` +The default value of `mask-mode` is `match-source`, which means the browser uses the `mask-type` value from the `<mask>` element to determine how to interpret it. If `mask-mode` is set to a value other than `match-source`, that value takes precedence and overrides the `mask-type` value of the applied mask. -#### Result +If the `<mask>` is defined as the mask image's source, and the `mask-mode` is set as or defaults to `match-source`, the `mask-mode` will resolve to the `<mask>` element's `mask-type` value: `luminance` or `alpha`. If not explicitly set, the value defaults to `luminance`. + +## Formal definition + +{{cssinfo}} + +## Formal syntax + +{{csssyntax}} + +## Examples -{{EmbedLiveSample("mask-type-alpha-example", "", "150px")}} +### Using the `mask-type` property -### Setting a luminance mask +This example demonstrates how to use the `mask-type` property and the effect of its different values. #### HTML -```html live-sample___mask-type-luminance-example -<section> - <div class="red-square"></div> -</section> - -<svg - version="1.1" - xmlns="http://www.w3.org/2000/svg" - xmlns:xlink="http://www.w3.org/1999/xlink" - width="0" - height="0"> - <defs> - <mask id="m" maskContentUnits="objectBoundingBox"> - <rect - x=".2" - y=".1" - width=".4" - height=".8" - fill="yellow" - fill-opacity="0.7" /> - </mask> - </defs> +We've included two images that will be masked. Other than their class names, the two images are identical. +We've also included an SVG with two `<mask>` elements. Other than their `id` values, the two masks are also identical: each has a green and white heart shape and a semi-transparent white-and-black-filled circle. + +```html +<img + class="alphaMaskType" + src="https://mdn.github.io/shared-assets/images/examples/progress-pride-flag.jpg" + alt="Pride flag" /> +<img + class="luminanceMaskType" + src="https://mdn.github.io/shared-assets/images/examples/progress-pride-flag.jpg" + alt="Pride flag" /> + +<svg height="0" width="0"> + <mask id="alphaMask"> + <path + d="M20,70 A40,40,0,0,1,100,70 A40,40,0,0,1,180,70 Q180,130,100,190 Q20,130,20,70 Z" + fill="green" + stroke="white" + stroke-width="20" /> + <circle + cx="170" + cy="170" + r="40" + fill="rgb(0 0 0 / 0.5)" + stroke="rgb(255 255 255 / 0.5)" + stroke-width="20" /> + </mask> + <mask id="luminanceMask"> + <path + d="M20,70 A40,40,0,0,1,100,70 A40,40,0,0,1,180,70 Q180,130,100,190 Q20,130,20,70 Z" + fill="green" + stroke="white" + stroke-width="20" /> + <circle + cx="170" + cy="170" + r="40" + fill="rgb(0 0 0 / 0.5)" + stroke="rgb(255 255 255 / 0.5)" + stroke-width="20" /> + </mask> </svg> ``` #### CSS -```css live-sample___mask-type-luminance-example -* { - margin: 0px; - padding: 0px; +We apply the `mask-type` property to the `<mask>` elements, and then apply the `<mask>` elements and the mask source to the images. + +```css +mask#alphaMask { + mask-type: alpha; } -section { - width: fit-content; - border: 1px solid blue; +mask#luminanceMask { + mask-type: luminance; } -.red-square { - height: 100px; - width: 100px; - background-color: red; - border: solid 1px black; - mask: url("#m"); +img.alphaMaskType { + mask-image: url(#alphaMask); } -mask { - mask-type: luminance; +img.luminanceMaskType { + mask-image: url(#luminanceMask); } ``` #### Result -{{EmbedLiveSample("mask-type-luminance-example", "", "150px")}} +{{EmbedLiveSample("Examples", "", "250")}} + +As the default value for the `mask-mode` property is `match-source`, the first mask uses the alpha channels only to define the mask: the white and green are fully opaque, and the 50% white and black colors are 50% opaque because only the alpha value of the colors matters. The second example uses the luminance of the colors to determine the opacity of the mask, with white being brighter than green, and semi-transparent white being brighter than semi-transparent black. ## Specifications @@ -173,4 +161,8 @@ mask { ## See also -- Other mask-related properties: {{cssxref("mask")}}, {{cssxref("mask-mode")}} +- {{cssxref("mask")}} +- {{cssxref("mask-mode")}} +- [Introduction to CSS masking](/en-US/docs/Web/CSS/CSS_masking/Masking) +- [CSS masking](/en-US/docs/Web/CSS/CSS_masking) module +- SVG {{svgattr("mask-type")}} attribute diff --git a/files/en-us/web/css/mask/index.md b/files/en-us/web/css/mask/index.md index dc5fb19848dff9e..78a8d0fabbeb95a 100644 --- a/files/en-us/web/css/mask/index.md +++ b/files/en-us/web/css/mask/index.md @@ -7,23 +7,20 @@ browser-compat: css.properties.mask {{CSSRef}} -The **`mask`** [CSS](/en-US/docs/Web/CSS) [shorthand property](/en-US/docs/Web/CSS/CSS_cascade/Shorthand_properties) hides an element (partially or fully) by masking or clipping the image at specific points. - -> [!NOTE] -> As well as the properties listed below, the `mask` shorthand also resets {{cssxref("mask-border")}} to its initial value. It is therefore recommended to use the `mask` shorthand rather than other shorthands or the individual properties to override any mask settings earlier in the cascade. This will ensure that `mask-border` has also been reset to allow the new styles to take effect. +The **`mask`** [CSS](/en-US/docs/Web/CSS) [shorthand property](/en-US/docs/Web/CSS/CSS_cascade/Shorthand_properties) hides an element (partially or fully) by masking or clipping a specified area of the image. It is a shorthand for all the [`mask-*`](#constituent_properties) properties. The property accepts one or more comma-separated values, where each value corresponds to a [`<mask-layer>`](#mask-layer). ## Constituent properties This property is a shorthand for the following CSS properties: -- [`mask-clip`](/en-US/docs/Web/CSS/mask-clip) -- [`mask-composite`](/en-US/docs/Web/CSS/mask-composite) -- [`mask-image`](/en-US/docs/Web/CSS/mask-image) -- [`mask-mode`](/en-US/docs/Web/CSS/mask-mode) -- [`mask-origin`](/en-US/docs/Web/CSS/mask-origin) -- [`mask-position`](/en-US/docs/Web/CSS/mask-position) -- [`mask-repeat`](/en-US/docs/Web/CSS/mask-repeat) -- [`mask-size`](/en-US/docs/Web/CSS/mask-size) +- {{cssxref("mask-clip")}} +- {{cssxref("mask-composite")}} +- {{cssxref("mask-image")}} +- {{cssxref("mask-mode")}} +- {{cssxref("mask-origin")}} +- {{cssxref("mask-position")}} +- {{cssxref("mask-repeat")}} +- {{cssxref("mask-size")}} ## Syntax @@ -32,16 +29,22 @@ This property is a shorthand for the following CSS properties: mask: none; /* Image values */ -mask: url(mask.png); /* Pixel image used as mask */ -mask: url(masks.svg#star); /* Element within SVG graphic used as mask */ +mask: url(mask.png); /* Raster image used as mask */ +mask: url(masks.svg#star); /* SVG used as mask */ /* Combined values */ -mask: url(masks.svg#star) luminance; /* Element within SVG graphic used as luminance mask */ -mask: url(masks.svg#star) 40px 20px; /* Element within SVG graphic used as mask positioned 40px from the top and 20px from the left */ -mask: url(masks.svg#star) 0 0/50px 50px; /* Element within SVG graphic used as mask with a width and height of 50px */ -mask: url(masks.svg#star) repeat-x; /* Element within SVG graphic used as horizontally repeated mask */ -mask: url(masks.svg#star) stroke-box; /* Element within SVG graphic used as mask extending to the box enclosed by the stroke */ -mask: url(masks.svg#star) exclude; /* Element within SVG graphic used as mask and combined with background using non-overlapping parts */ +mask: url(masks.svg#star) luminance; /* Luminance mask */ +mask: url(masks.svg#star) 40px 20px; /* Mask positioned 40px from the top and 20px from the left */ +mask: url(masks.svg#star) 0 0/50px 50px; /* Mask with a width and height of 50px */ +mask: url(masks.svg#star) repeat-x; /* Horizontally-repeated mask */ +mask: url(masks.svg#star) stroke-box; /* Mask extends to the inside edge of the stroke box */ +mask: url(masks.svg#star) exclude; /* Mask combined with background using non-overlapping parts */ + +/* Multiple masks */ +mask: + url(masks.svg#star) left / 16px repeat-y, + /* 16px-wide mask on the left side */ url(masks.svg#circle) right / 16px + repeat-y; /* 16px-wide mask against right side */ /* Global values */ mask: inherit; @@ -49,32 +52,64 @@ mask: initial; mask: revert; mask: revert-layer; mask: unset; - -/* Multiple masks */ -mask: - url(masks.svg#star) left / 16px repeat-y, - /* Element within SVG graphic is used as a mask on the left-hand side with a width of 16px */ - url(masks.svg#circle) right / 16px repeat-y; /* Element within SVG graphic is used as a mask on the right-hand side with a width of 16px */ ``` ### Values -- `<mask-reference>` - - : Sets the mask image source. See {{cssxref("mask-image")}}. -- `<masking-mode>` - - : Sets the masking mode of the mask image. See {{cssxref("mask-mode")}}. -- `<position>` - - : Sets the position of the mask image. See {{cssxref("mask-position")}}. -- `<bg-size>` - - : Sets the size of the mask image. See {{cssxref("mask-size")}}. -- `<repeat-style>` - - : Sets the repetition of the mask image. See {{cssxref("mask-repeat")}}. -- `<geometry-box>` - - : If only one `<geometry-box>` value is given, it sets both {{cssxref("mask-origin")}} and {{cssxref("mask-clip")}}. If two `<geometry-box>` values are present, then the first sets {{cssxref("mask-origin")}} and the second sets {{cssxref("mask-clip")}}. -- `<geometry-box> | no-clip` - - : Sets the area that is affected by the mask image. See {{cssxref("mask-clip")}}. -- `<compositing-operator>` - - : Sets the compositing operation used on the current mask layer. See {{cssxref("mask-composite")}}. +- `<mask-layer>` + + - : One or more comma-separated mask layers, consisting of the following components: + + - `<mask-reference>` + - : Sets the mask image source. See {{cssxref("mask-image")}}. + - `<masking-mode>` + - : Sets the masking mode of the mask image. See {{cssxref("mask-mode")}}. + - `<position>` + - : Sets the position of the mask image. See {{cssxref("mask-position")}}. + - `<bg-size>` + - : Sets the size of the mask image. See {{cssxref("mask-size")}}. + - `<repeat-style>` + - : Sets the repetition of the mask image. See {{cssxref("mask-repeat")}}. + - `<geometry-box>` + - : If only one `<geometry-box>` value is given, it sets both the {{cssxref("mask-origin")}} and {{cssxref("mask-clip")}} property values. If two `<geometry-box>` values are present, the first defines the `mask-origin` and the second defines the `mask-clip`. + - `<geometry-box> | no-clip` + - : Sets the area affected by the mask image. See {{cssxref("mask-clip")}}. + - `<compositing-operator>` + - : Sets the compositing operation used on the current mask layer. See {{cssxref("mask-composite")}}. + +## Description + +The `mask` shorthand property hides part or all of the element it is applied to. The parts of the element that are hidden, visible, or partially shown depend on either the opacity (alpha channel of the mask) or the brightness (luminance) of the mask. In alpha masking, opaque areas of the mask reveal the element, and transparent areas hide it. In luminance masking, light opaque areas of the mask reveal the element, and dark or transparent areas hide it. + +While not all constituent mask properties need to be declared, any values that are omitted default to their initial values, which are: + +```css +mask-image: none; +mask-mode: match-source; +mask-position: 0% 0%; +mask-size: auto; +mask-repeat: repeat; +mask-origin: border-box; +mask-clip: border-box; +mask-composite: add; +``` + +Within each `<mask-layer>`, the `mask-size` component must go after the `mask-position` value, with a forward slash (`/`) separating the two. + +If there are two `<geometry-box>` values present, the first is the `mask-origin` value, while the second is the `mask-clip` value. If one `<geometry-box>` value and the `no-clip` keyword are present, the `<geometry-box>` is the value of the `mask-origin` property, as the `no-clip` is only valid for the `mask-clip` property. In this case, the order of the two values doesn't matter. If only one `<geometry-box>` value is present (with no `no-clip` keyterm specified), this value is used for both the `mask-origin` and `mask-clip` properties. + +As the `mask` shorthand resets all the `mask-border-*` properties to their `initial` value, you should declare these properties — or the {{cssxref("mask-border")}} shorthand — after any `mask` declarations. When setting `mask` in your declaration block, you also implicitly set the following: + +```css +mask-border-source: none; +mask-border-mode: alpha; +mask-border-outset: 0; +mask-border-repeat: stretch; +mask-border-slice: 0; +mask-border-width: auto; +``` + +For this reason, the specification recommends using the `mask` shorthand rather than the individual component properties to override any masks set earlier in the cascade. This ensures that `mask-border` has also been reset. ## Formal definition @@ -88,16 +123,64 @@ mask: ### Masking an image +In this example, an image is masked using a CSS-generated repeating conic gradient as a mask source. We'll also show the gradient as a background image for comparison. + +#### HTML + +We include an {{htmlelement("img")}} and an empty {{htmlelement("div")}} element. + +```html +<img + src="https://mdn.github.io/shared-assets/images/examples/progress-pride-flag.jpg" + alt="Pride flag" /> +<div></div> +``` + +#### CSS + +We set the same {{cssxref("border")}}, {{cssxref("padding")}}, and sizing on both the `<img>` and `<div>`. + ```css -.target { - mask: url(#c1) luminance; +img, +div { + border: 20px dashed rebeccapurple; + box-sizing: content-box; + padding: 20px; + height: 220px; + width: 220px; } +``` + +We then apply a mask to the `<img>`. The `mask-image` is generated using a {{cssxref("gradient/repeating-conic-gradient", "repeating-conic-gradient()")}} function. We define it to be a `100px` by `100px` gradient, which repeats starting at the top and left corner of the image's `content-box`. We include two `<geometry-box>` values; the first sets the `mask-origin` and the second defines the `mask-clip` property value. The gradient goes from transparent to solid `lightgreen`. We used `lightgreen` to demonstrate that it isn't the color of the mask that is important, but rather its transparency. + +```css +img { + mask: repeating-radial-gradient( + circle, + transparent 0 5px, + lightgreen 15px 20px + ) + content-box border-box 0% 0% / 100px 100px repeat; +} +``` + +Finally, we use the same value for the `<div>`'s {{cssxref("background")}} shorthand property as we used for the `mask`. -.another-target { - mask: url(resources.svg#c1) 50px 30px/10px 10px repeat-x exclude; +```css +div { + background: repeating-radial-gradient( + circle, + transparent 0 5px, + lightgreen 15px 20px + ) + content-box border-box 0% 0% / 100px 100px repeat; } ``` +#### Results + +{{EmbedLiveSample("Masking an image", "", "630")}} + ## Specifications {{Specifications}} @@ -110,6 +193,6 @@ mask: - {{CSSxRef("clip-path")}} - {{CSSxRef("filter")}} +- [CSS masking](/en-US/docs/Web/CSS/CSS_masking) module - SVG {{SVGAttr("mask")}} attribute -- [CSS Shapes, clipping and masking – and how to use them](https://hacks.mozilla.org/2017/06/css-shapes-clipping-and-masking/) -- [Applying SVG effects to HTML content](/en-US/docs/Web/SVG/Applying_SVG_effects_to_HTML_content) +- [Applying SVG effects to HTML content](/en-US/docs/Web/SVG/Guides/Applying_SVG_effects_to_HTML_content) diff --git a/files/en-us/web/css/math-depth/index.md b/files/en-us/web/css/math-depth/index.md index 8a7189832ac8496..23544d5d15ca286 100644 --- a/files/en-us/web/css/math-depth/index.md +++ b/files/en-us/web/css/math-depth/index.md @@ -64,7 +64,7 @@ The last two subformulas show the effect of setting `math-depth` to a specific v #### HTML ```html -<p style="font-size: 3rem; margin: 1rem 0"> +<p> <math> <mtext>0</mtext> @@ -93,6 +93,13 @@ The last two subformulas show the effect of setting `math-depth` to a specific v </p> ``` +```css hidden +p { + font-size: 3rem; + margin: 1rem 0; +} +``` + #### Result {{embedlivesample('Specifying_a_math_depth', 600, 100)}} diff --git a/files/en-us/web/css/math-shift/index.md b/files/en-us/web/css/math-shift/index.md index 00d53244222e7ca..f9498d140c34e84 100644 --- a/files/en-us/web/css/math-shift/index.md +++ b/files/en-us/web/css/math-shift/index.md @@ -48,6 +48,7 @@ math-shift: unset; ```css math { math-shift: compact; + font-size: 64pt; } ``` @@ -56,7 +57,7 @@ math { The following MathML displays two versions of "x squared" using a font with an OpenType MATH table. Browser implementing the `math-shift` property should raise the superscripts using slightly different shifts. ```html -<math style="font-size: 64pt;"> +<math> <msup style="math-shift: normal"> <mi>x</mi> <mn>2</mn> diff --git a/files/en-us/web/css/max-block-size/index.md b/files/en-us/web/css/max-block-size/index.md index 1acca65e99df7e7..eb8739cc17a562a 100644 --- a/files/en-us/web/css/max-block-size/index.md +++ b/files/en-us/web/css/max-block-size/index.md @@ -15,7 +15,46 @@ This is useful because the `max-width` is always used for horizontal sizes and ` Any time you would normally use `max-height` or `max-width`, you should instead use `max-block-size` to set the maximum "height" of the content (even though this may not be a vertical value) and `max-inline-size` to set the maximum "width" of the content (although this may instead be vertical rather than horizontal). See [`writing-mode` examples](/en-US/docs/Web/CSS/writing-mode#examples), which show the different writing modes in action. -{{EmbedInteractiveExample("pages/css/max-block-size.html")}} +{{InteractiveExample("CSS Demo: max-block-size")}} + +```css interactive-example-choice +max-block-size: 150px; +writing-mode: horizontal-tb; +``` + +```css interactive-example-choice +max-block-size: 150px; +writing-mode: vertical-rl; +``` + +```css interactive-example-choice +max-block-size: 20px; +writing-mode: horizontal-tb; +``` + +```css interactive-example-choice +max-block-size: 75%; +writing-mode: vertical-lr; +``` + +```html interactive-example +<section class="default-example" id="default-example"> + <div class="transition-all" id="example-element"> + This is a box where you can change the maximum block size. <br />This will + limit the size in the block dimension, potentially causing an overflow. + </div> +</section> +``` + +```css interactive-example +#example-element { + display: flex; + flex-direction: column; + background-color: #5b6dcd; + justify-content: center; + color: #ffffff; +} +``` ## Syntax @@ -59,9 +98,9 @@ The `max-block-size` property's value can be any value that's legal for the {{cs - `min-content` - : The intrinsic minimum `max-block-size`. - `fit-content` - - : Use the available space, but not more than [max-content](/en-US/docs/Web/CSS/max-content), i.e. `min(max-content, max(min-content, stretch))`. + - : Use the available space, but not more than [max-content](/en-US/docs/Web/CSS/max-content), i.e., `min(max-content, max(min-content, stretch))`. - `fit-content({{cssxref("&lt;length-percentage&gt;")}})` - - : Uses the `fit-content` formula with the available space replaced by the specified argument, i.e. `min(max-content, max(min-content, argument))`. + - : Uses the `fit-content` formula with the available space replaced by the specified argument, i.e., `min(max-content, max(min-content, argument))`. ### How writing-mode affects directionality diff --git a/files/en-us/web/css/max-height/index.md b/files/en-us/web/css/max-height/index.md index 29ae4ba2416b60a..348ecae80f6da4d 100644 --- a/files/en-us/web/css/max-height/index.md +++ b/files/en-us/web/css/max-height/index.md @@ -7,9 +7,44 @@ browser-compat: css.properties.max-height {{CSSRef}} -The **`max-height`** [CSS](/en-US/docs/Web/CSS) property sets the maximum height of an element. It prevents the [used value](/en-US/docs/Web/CSS/CSS_cascade/used_value) of the {{cssxref("height")}} property from becoming larger than the value specified for `max-height`. +The **`max-height`** [CSS](/en-US/docs/Web/CSS) property sets the maximum height of an element. It prevents the [used value](/en-US/docs/Web/CSS/CSS_cascade/Value_processing#used_value) of the {{cssxref("height")}} property from becoming larger than the value specified for `max-height`. -{{EmbedInteractiveExample("pages/css/max-height.html")}} +{{InteractiveExample("CSS Demo: max-height")}} + +```css interactive-example-choice +max-height: 150px; +``` + +```css interactive-example-choice +max-height: 7em; +``` + +```css interactive-example-choice +max-height: 75%; +``` + +```css interactive-example-choice +max-height: 10px; +``` + +```html interactive-example +<section class="default-example" id="default-example"> + <div class="transition-all" id="example-element"> + This is a box where you can change the maximum height. <br />This will limit + how tall the box can be, potentially causing an overflow. + </div> +</section> +``` + +```css interactive-example +#example-element { + display: flex; + flex-direction: column; + background-color: #5b6dcd; + justify-content: center; + color: #ffffff; +} +``` `max-height` overrides {{cssxref("height")}}, but {{cssxref("min-height")}} overrides `max-height`. @@ -53,9 +88,9 @@ max-height: unset; - `min-content` - : The intrinsic minimum `max-height`. - `fit-content` - - : Use the available space, but not more than [max-content](/en-US/docs/Web/CSS/max-content), i.e. `min(max-content, max(min-content, stretch))`. + - : Use the available space, but not more than [max-content](/en-US/docs/Web/CSS/max-content), i.e., `min(max-content, max(min-content, stretch))`. - `fit-content({{cssxref("&lt;length-percentage&gt;")}})` - - : Uses the `fit-content` formula with the available space replaced by the specified argument, i.e. `min(max-content, max(min-content, argument))`. + - : Uses the `fit-content` formula with the available space replaced by the specified argument, i.e., `min(max-content, max(min-content, argument))`. - `stretch` - : Limits the maximum height of the element's [margin box](/en-US/docs/Learn_web_development/Core/Styling_basics/Box_model#parts_of_a_box) to the height of its [containing block](/en-US/docs/Web/CSS/CSS_display/Containing_block#identifying_the_containing_block). It attempts to make the margin box fill the available space in the containing block, so in a way behaving similar to `100%` but applying the resulting size to the margin box rather than the box determined by [box-sizing](/en-US/docs/Web/CSS/box-sizing). @@ -67,7 +102,7 @@ max-height: unset; Ensure that elements set with a `max-height` are not truncated and/or do not obscure other content when the page is zoomed to increase text size. -- [MDN Understanding WCAG, Guideline 1.4 explanations](/en-US/docs/Web/Accessibility/Understanding_WCAG/Perceivable#guideline_1.4_make_it_easier_for_users_to_see_and_hear_content_including_separating_foreground_from_background) +- [MDN Understanding WCAG, Guideline 1.4 explanations](/en-US/docs/Web/Accessibility/Guides/Understanding_WCAG/Perceivable#guideline_1.4_make_it_easier_for_users_to_see_and_hear_content_including_separating_foreground_from_background) - [Understanding Success Criterion 1.4.4 | W3C Understanding WCAG 2.0](https://www.w3.org/TR/UNDERSTANDING-WCAG20/visual-audio-contrast-scale.html) ## Formal definition diff --git a/files/en-us/web/css/max-inline-size/index.md b/files/en-us/web/css/max-inline-size/index.md index 0c2d8f7aef88c07..8bc3e773cdb471f 100644 --- a/files/en-us/web/css/max-inline-size/index.md +++ b/files/en-us/web/css/max-inline-size/index.md @@ -11,7 +11,46 @@ The **`max-inline-size`** [CSS](/en-US/docs/Web/CSS) property defines the horizo If the writing mode is vertically oriented, the value of `max-inline-size` relates to the maximal height of the element; otherwise, it relates to the maximal width of the element. A related property is {{cssxref("max-block-size")}}, which defines the other dimension of the element. -{{EmbedInteractiveExample("pages/css/max-inline-size.html")}} +{{InteractiveExample("CSS Demo: max-inline-size")}} + +```css interactive-example-choice +max-inline-size: 150px; +writing-mode: horizontal-tb; +``` + +```css interactive-example-choice +max-inline-size: 150px; +writing-mode: vertical-rl; +``` + +```css interactive-example-choice +max-inline-size: 20px; +writing-mode: horizontal-tb; +``` + +```css interactive-example-choice +max-inline-size: 75%; +writing-mode: vertical-lr; +``` + +```html interactive-example +<section class="default-example" id="default-example"> + <div class="transition-all" id="example-element"> + This is a box where you can change the max-inline-size. + </div> +</section> +``` + +```css interactive-example +#example-element { + display: flex; + flex-direction: column; + background-color: #5b6dcd; + height: 80%; + justify-content: center; + color: #ffffff; +} +``` ## Syntax diff --git a/files/en-us/web/css/max-width/index.md b/files/en-us/web/css/max-width/index.md index a433464529605ec..9c33e06ac79c2f4 100644 --- a/files/en-us/web/css/max-width/index.md +++ b/files/en-us/web/css/max-width/index.md @@ -7,9 +7,44 @@ browser-compat: css.properties.max-width {{CSSRef}} -The **`max-width`** [CSS](/en-US/docs/Web/CSS) property sets the maximum width of an element. It prevents the [used value](/en-US/docs/Web/CSS/CSS_cascade/used_value) of the {{cssxref("width")}} property from becoming larger than the value specified by `max-width`. +The **`max-width`** [CSS](/en-US/docs/Web/CSS) property sets the maximum width of an element. It prevents the [used value](/en-US/docs/Web/CSS/CSS_cascade/Value_processing#used_value) of the {{cssxref("width")}} property from becoming larger than the value specified by `max-width`. -{{EmbedInteractiveExample("pages/css/max-width.html")}} +{{InteractiveExample("CSS Demo: max-width")}} + +```css interactive-example-choice +max-width: 150px; +``` + +```css interactive-example-choice +max-width: 20em; +``` + +```css interactive-example-choice +max-width: 75%; +``` + +```css interactive-example-choice +max-width: 20ch; +``` + +```html interactive-example +<section class="default-example" id="default-example"> + <div class="transition-all" id="example-element"> + Change the maximum width. + </div> +</section> +``` + +```css interactive-example +#example-element { + display: flex; + flex-direction: column; + background-color: #5b6dcd; + height: 80%; + justify-content: center; + color: #ffffff; +} +``` `max-width` overrides {{cssxref("width")}}, but {{cssxref("min-width")}} overrides `max-width`. @@ -53,9 +88,9 @@ max-width: unset; - `min-content` - : The intrinsic minimum `max-width`. - `fit-content` - - : Use the available space, but not more than [max-content](/en-US/docs/Web/CSS/max-content), i.e. `min(max-content, max(min-content, stretch))`. + - : Use the available space, but not more than [max-content](/en-US/docs/Web/CSS/max-content), i.e., `min(max-content, max(min-content, stretch))`. - `fit-content({{cssxref("&lt;length-percentage&gt;")}})` - - : Uses the `fit-content` formula with the available space replaced by the specified argument, i.e. `min(max-content, max(min-content, argument))`. + - : Uses the `fit-content` formula with the available space replaced by the specified argument, i.e., `min(max-content, max(min-content, argument))`. - `stretch` - : Limits the maximum width of the element's [margin box](/en-US/docs/Learn_web_development/Core/Styling_basics/Box_model#parts_of_a_box) to the width of its [containing block](/en-US/docs/Web/CSS/CSS_display/Containing_block#identifying_the_containing_block). It attempts to make the margin box fill the available space in the containing block, so in a way behaving similar to `100%` but applying the resulting size to the margin box rather than the box determined by [box-sizing](/en-US/docs/Web/CSS/box-sizing). @@ -67,7 +102,7 @@ max-width: unset; Ensure that elements set with a `max-width` are not truncated and/or do not obscure other content when the page is zoomed to increase text size. -- [MDN Understanding WCAG, Guideline 1.4 explanations](/en-US/docs/Web/Accessibility/Understanding_WCAG/Perceivable#guideline_1.4_make_it_easier_for_users_to_see_and_hear_content_including_separating_foreground_from_background) +- [MDN Understanding WCAG, Guideline 1.4 explanations](/en-US/docs/Web/Accessibility/Guides/Understanding_WCAG/Perceivable#guideline_1.4_make_it_easier_for_users_to_see_and_hear_content_including_separating_foreground_from_background) - [Understanding Success Criterion 1.4.4 | W3C Understanding WCAG 2.0](https://www.w3.org/TR/UNDERSTANDING-WCAG20/visual-audio-contrast-scale.html) ## Formal definition diff --git a/files/en-us/web/css/max/index.md b/files/en-us/web/css/max/index.md index 5b0fe3cdd73cd83..823caf7daf43b51 100644 --- a/files/en-us/web/css/max/index.md +++ b/files/en-us/web/css/max/index.md @@ -9,7 +9,30 @@ browser-compat: css.types.max The **`max()`** [CSS](/en-US/docs/Web/CSS) [function](/en-US/docs/Web/CSS/CSS_Values_and_Units/CSS_Value_Functions) lets you set the largest (most positive) value from a list of comma-separated expressions as the value of a CSS property value. The `max()` function can be used anywhere a {{CSSxRef("&lt;length&gt;")}}, {{CSSxRef("&lt;frequency&gt;")}}, {{CSSxRef("&lt;angle&gt;")}}, {{CSSxRef("&lt;time&gt;")}}, {{CSSxRef("&lt;percentage&gt;")}}, {{CSSxRef("&lt;number&gt;")}}, or {{CSSxRef("&lt;integer&gt;")}} is allowed. -{{EmbedInteractiveExample("pages/css/function-max.html")}} +{{InteractiveExample("CSS Demo: max()")}} + +```css interactive-example-choice +width: max(20vw, 400px); +``` + +```css interactive-example-choice +width: max(20vw, 100px); +``` + +```css interactive-example-choice +width: max(5vw, 100px); +``` + +```html interactive-example +<section class="default-example" id="default-example"> + <div class="transition-all" id="example-element"> + <img + alt="Firefox logo" + class="logo" + src="/shared-assets/images/examples/firefox-logo.svg" /> + </div> +</section> +``` In the first example shown above, the width will be at least 400px, but will be wider if the viewport is more than 2000px wide (in which case 1vw would be 20px, so 20vw would be 400px). This technique uses an absolute unit to specify a fixed minimum value for the property, and a relative unit to allow the value to grow to suit larger viewports. @@ -44,7 +67,7 @@ small { This ensures a minimum size of _1rem_, with a text size that scales if the page is zoomed. -- [MDN Understanding WCAG, Guideline 1.4 explanations](/en-US/docs/Web/Accessibility/Understanding_WCAG/Perceivable#guideline_1.4_make_it_easier_for_users_to_see_and_hear_content_including_separating_foreground_from_background) +- [MDN Understanding WCAG, Guideline 1.4 explanations](/en-US/docs/Web/Accessibility/Guides/Understanding_WCAG/Perceivable#guideline_1.4_make_it_easier_for_users_to_see_and_hear_content_including_separating_foreground_from_background) - [Understanding Success Criterion 1.4.4 | W3C Understanding WCAG 2.0](https://www.w3.org/TR/UNDERSTANDING-WCAG20/visual-audio-contrast-scale.html) ## Examples diff --git a/files/en-us/web/css/min-block-size/index.md b/files/en-us/web/css/min-block-size/index.md index 483fc0595a29ebc..4d9e233bc5d4931 100644 --- a/files/en-us/web/css/min-block-size/index.md +++ b/files/en-us/web/css/min-block-size/index.md @@ -11,7 +11,47 @@ The **`min-block-size`** [CSS](/en-US/docs/Web/CSS) property defines the minimum If the writing mode is vertically oriented, the value of `min-block-size` relates to the minimum width of the element; otherwise, it relates to the minimum height of the element. A related property is {{cssxref("min-inline-size")}}, which defines the other dimension of the element. -{{EmbedInteractiveExample("pages/css/min-block-size.html")}} +{{InteractiveExample("CSS Demo: min-block-size")}} + +```css interactive-example-choice +min-block-size: 150px; +writing-mode: horizontal-tb; +``` + +```css interactive-example-choice +min-block-size: 150px; +writing-mode: vertical-rl; +``` + +```css interactive-example-choice +min-block-size: 20px; +writing-mode: horizontal-tb; +``` + +```css interactive-example-choice +min-block-size: 15em; +writing-mode: vertical-lr; +``` + +```html interactive-example +<section class="default-example" id="default-example"> + <div class="transition-all" id="example-element"> + This is a box where you can change the minimum block size. <br />If there is + more content than the minimum the box will grow in the block dimension as + needed by the content. + </div> +</section> +``` + +```css interactive-example +#example-element { + display: flex; + flex-direction: column; + background-color: #5b6dcd; + justify-content: center; + color: #ffffff; +} +``` ## Syntax diff --git a/files/en-us/web/css/min-height/index.md b/files/en-us/web/css/min-height/index.md index 71ffc70b1a92e0e..b6203b3fc79ece1 100644 --- a/files/en-us/web/css/min-height/index.md +++ b/files/en-us/web/css/min-height/index.md @@ -7,9 +7,45 @@ browser-compat: css.properties.min-height {{CSSRef}} -The **`min-height`** [CSS](/en-US/docs/Web/CSS) property sets the minimum height of an element. It prevents the [used value](/en-US/docs/Web/CSS/CSS_cascade/used_value) of the {{cssxref("height")}} property from becoming smaller than the value specified for `min-height`. +The **`min-height`** [CSS](/en-US/docs/Web/CSS) property sets the minimum height of an element. It prevents the [used value](/en-US/docs/Web/CSS/CSS_cascade/Value_processing#used_value) of the {{cssxref("height")}} property from becoming smaller than the value specified for `min-height`. -{{EmbedInteractiveExample("pages/css/min-height.html")}} +{{InteractiveExample("CSS Demo: min-height")}} + +```css interactive-example-choice +min-height: 150px; +``` + +```css interactive-example-choice +min-height: 7em; +``` + +```css interactive-example-choice +min-height: 75%; +``` + +```css interactive-example-choice +min-height: 10px; +``` + +```html interactive-example +<section class="default-example" id="default-example"> + <div class="transition-all" id="example-element"> + This is a box where you can change the minimum height. <br />If there is + more content than the minimum the box will grow to the height needed by the + content. + </div> +</section> +``` + +```css interactive-example +#example-element { + display: flex; + flex-direction: column; + background-color: #5b6dcd; + justify-content: center; + color: #ffffff; +} +``` The element's height is set to the value of `min-height` whenever `min-height` is larger than {{cssxref("max-height")}} or {{cssxref("height")}}. @@ -52,9 +88,9 @@ min-height: unset; - `min-content` - : The intrinsic minimum `min-height`. - `fit-content` - - : Use the available space, but not more than [max-content](/en-US/docs/Web/CSS/max-content), i.e. `min(max-content, max(min-content, stretch))`. + - : Use the available space, but not more than [max-content](/en-US/docs/Web/CSS/max-content), i.e., `min(max-content, max(min-content, stretch))`. - `fit-content({{cssxref("&lt;length-percentage&gt;")}})` - - : Uses the `fit-content` formula with the available space replaced by the specified argument, i.e. `min(max-content, max(min-content, argument))`. + - : Uses the `fit-content` formula with the available space replaced by the specified argument, i.e., `min(max-content, max(min-content, argument))`. - `stretch` - : Limits the minimum height of the element's [margin box](/en-US/docs/Learn_web_development/Core/Styling_basics/Box_model#parts_of_a_box) to the height of its [containing block](/en-US/docs/Web/CSS/CSS_display/Containing_block#identifying_the_containing_block). It attempts to make the margin box fill the available space in the containing block, so in a way behaving similar to `100%` but applying the resulting size to the margin box rather than the box determined by [box-sizing](/en-US/docs/Web/CSS/box-sizing). diff --git a/files/en-us/web/css/min-inline-size/index.md b/files/en-us/web/css/min-inline-size/index.md index c8dffebd4b680b5..0d203dd3e24c1d8 100644 --- a/files/en-us/web/css/min-inline-size/index.md +++ b/files/en-us/web/css/min-inline-size/index.md @@ -9,7 +9,44 @@ browser-compat: css.properties.min-inline-size The **`min-inline-size`** [CSS](/en-US/docs/Web/CSS) property defines the horizontal or vertical minimal size of an element's block, depending on its writing mode. It corresponds to either the {{cssxref("min-width")}} or the {{cssxref("min-height")}} property, depending on the value of {{cssxref("writing-mode")}}. -{{EmbedInteractiveExample("pages/css/min-inline-size.html")}} +{{InteractiveExample("CSS Demo: min-inline-size")}} + +```css interactive-example-choice +min-inline-size: 200px; +writing-mode: horizontal-tb; +``` + +```css interactive-example-choice +min-inline-size: 200px; +writing-mode: vertical-rl; +``` + +```css interactive-example-choice +min-inline-size: 20px; +writing-mode: horizontal-tb; +``` + +```css interactive-example-choice +min-inline-size: 75%; +writing-mode: vertical-lr; +``` + +```html interactive-example +<section class="default-example" id="default-example"> + <div class="transition-all" id="example-element">Change min-inline-size</div> +</section> +``` + +```css interactive-example +#example-element { + display: flex; + flex-direction: column; + background-color: #5b6dcd; + height: 80%; + justify-content: center; + color: #ffffff; +} +``` ## Syntax diff --git a/files/en-us/web/css/min-width/index.md b/files/en-us/web/css/min-width/index.md index 8f49214a5ecd26e..dc7896cdbdbbad6 100644 --- a/files/en-us/web/css/min-width/index.md +++ b/files/en-us/web/css/min-width/index.md @@ -7,9 +7,44 @@ browser-compat: css.properties.min-width {{CSSRef}} -The **`min-width`** [CSS](/en-US/docs/Web/CSS) property sets the minimum width of an element. It prevents the [used value](/en-US/docs/Web/CSS/CSS_cascade/used_value) of the {{cssxref("width")}} property from becoming smaller than the value specified for `min-width`. +The **`min-width`** [CSS](/en-US/docs/Web/CSS) property sets the minimum width of an element. It prevents the [used value](/en-US/docs/Web/CSS/CSS_cascade/Value_processing#used_value) of the {{cssxref("width")}} property from becoming smaller than the value specified for `min-width`. -{{EmbedInteractiveExample("pages/css/min-width.html")}} +{{InteractiveExample("CSS Demo: min-width")}} + +```css interactive-example-choice +min-width: 150px; +``` + +```css interactive-example-choice +min-width: 20em; +``` + +```css interactive-example-choice +min-width: 75%; +``` + +```css interactive-example-choice +min-width: 40ch; +``` + +```html interactive-example +<section class="default-example" id="default-example"> + <div class="transition-all" id="example-element"> + Change the minimum width. + </div> +</section> +``` + +```css interactive-example +#example-element { + display: flex; + flex-direction: column; + background-color: #5b6dcd; + height: 80%; + justify-content: center; + color: #ffffff; +} +``` The element's width is set to the value of `min-width` whenever `min-width` is larger than {{Cssxref("max-width")}} or {{Cssxref("width")}}. @@ -56,9 +91,9 @@ min-width: unset; - `min-content` - : The intrinsic minimum `min-width`. - `fit-content` - - : Use the available space, but not more than [`max-content`](/en-US/docs/Web/CSS/max-content), i.e. `min(max-content, max(min-content, stretch))`. + - : Use the available space, but not more than [`max-content`](/en-US/docs/Web/CSS/max-content), i.e., `min(max-content, max(min-content, stretch))`. - `fit-content({{cssxref("&lt;length-percentage&gt;")}})` - - : Uses the `fit-content` formula with the available space replaced by the specified argument, i.e. `min(max-content, max(min-content, argument))`. + - : Uses the `fit-content` formula with the available space replaced by the specified argument, i.e., `min(max-content, max(min-content, argument))`. - `stretch` - : Limits the minimum width of the element's [margin box](/en-US/docs/Learn_web_development/Core/Styling_basics/Box_model#parts_of_a_box) to the width of its [containing block](/en-US/docs/Web/CSS/CSS_display/Containing_block#identifying_the_containing_block). It attempts to make the margin box fill the available space in the containing block, so in a way behaving similar to `100%` but applying the resulting size to the margin box rather than the box determined by [box-sizing](/en-US/docs/Web/CSS/box-sizing). diff --git a/files/en-us/web/css/min/index.md b/files/en-us/web/css/min/index.md index d444f10f4de0161..c8845f103a6ad21 100644 --- a/files/en-us/web/css/min/index.md +++ b/files/en-us/web/css/min/index.md @@ -9,7 +9,30 @@ browser-compat: css.types.min The **`min()`** [CSS](/en-US/docs/Web/CSS) [function](/en-US/docs/Web/CSS/CSS_Values_and_Units/CSS_Value_Functions) lets you set the smallest (most negative) value from a list of comma-separated expressions as the value of a CSS property value. The `min()` function can be used anywhere a {{CSSxRef("&lt;length&gt;")}}, {{CSSxRef("&lt;frequency&gt;")}}, {{CSSxRef("&lt;angle&gt;")}}, {{CSSxRef("&lt;time&gt;")}}, {{CSSxRef("&lt;percentage&gt;")}}, {{CSSxRef("&lt;number&gt;")}}, or {{CSSxRef("&lt;integer&gt;")}} is allowed. -{{EmbedInteractiveExample("pages/css/function-min.html")}} +{{InteractiveExample("CSS Demo: min()")}} + +```css interactive-example-choice +width: min(50vw, 200px); +``` + +```css interactive-example-choice +width: min(100vw, 4000px); +``` + +```css interactive-example-choice +width: min(150vw, 100px); +``` + +```html interactive-example +<section class="default-example" id="default-example"> + <div class="transition-all" id="example-element"> + <img + alt="Firefox logo" + class="logo" + src="/shared-assets/images/examples/firefox-logo.svg" /> + </div> +</section> +``` In the first above example, the width will be at most 200px, but will be smaller if the viewport is less than 400px wide (in which case 1vw would be 4px, so 50vw would be 200px). This technique uses an absolute unit to specify a fixed maximum value for the property, and a relative unit to allow the value to shrink to suit smaller viewports. @@ -37,7 +60,7 @@ You can use different units for each value in your expression, if you wish. You When using `min()` to set a maximum font size, ensure that the font can still be scaled at least 200% for readability (without assistive technology like a zoom function). -- [MDN Understanding WCAG, Guideline 1.4 explanations](/en-US/docs/Web/Accessibility/Understanding_WCAG/Perceivable#guideline_1.4_make_it_easier_for_users_to_see_and_hear_content_including_separating_foreground_from_background) +- [MDN Understanding WCAG, Guideline 1.4 explanations](/en-US/docs/Web/Accessibility/Guides/Understanding_WCAG/Perceivable#guideline_1.4_make_it_easier_for_users_to_see_and_hear_content_including_separating_foreground_from_background) - [Understanding Success Criterion 1.4.4 | W3C Understanding WCAG 2.0](https://www.w3.org/TR/UNDERSTANDING-WCAG20/visual-audio-contrast-scale.html) ## Examples diff --git a/files/en-us/web/css/minmax/index.md b/files/en-us/web/css/minmax/index.md index 6bbace54596dc29..dffad02994ea073 100644 --- a/files/en-us/web/css/minmax/index.md +++ b/files/en-us/web/css/minmax/index.md @@ -9,7 +9,48 @@ browser-compat: css.properties.grid-template-columns.minmax The **`minmax()`** [CSS function](/en-US/docs/Web/CSS/CSS_Values_and_Units/CSS_Value_Functions) defines a size range greater than or equal to _min_ and less than or equal to _max_. It is used with [CSS grids](/en-US/docs/Web/CSS/CSS_grid_layout). -{{EmbedInteractiveExample("pages/css/function-minmax.html")}} +{{InteractiveExample("CSS Demo: minmax()")}} + +```css interactive-example-choice +grid-template-columns: minmax(20px, auto) 1fr 1fr; +``` + +```css interactive-example-choice +grid-template-columns: minmax(0, 1fr) minmax(0, 1fr) minmax(0, 1fr); +``` + +```css interactive-example-choice +grid-template-columns: minmax(2ch, 10ch) 1fr 1fr; +``` + +```html interactive-example +<section class="default-example" id="default-example"> + <div class="example-container"> + <div class="transition-all" id="example-element"> + <div>One. This column has more text in it.</div> + <div>Two</div> + <div>Three</div> + <div>Four</div> + <div>Five</div> + </div> + </div> +</section> +``` + +```css interactive-example +#example-element { + border: 1px solid #c5c5c5; + display: grid; + grid-gap: 10px; + width: 250px; +} + +#example-element > div { + background-color: rgba(0, 0, 255, 0.2); + border: 3px solid blue; + text-align: left; +} +``` ## Syntax diff --git a/files/en-us/web/css/mix-blend-mode/index.md b/files/en-us/web/css/mix-blend-mode/index.md index d4c93daa6af518c..b32b5538b4e3c45 100644 --- a/files/en-us/web/css/mix-blend-mode/index.md +++ b/files/en-us/web/css/mix-blend-mode/index.md @@ -9,7 +9,40 @@ browser-compat: css.properties.mix-blend-mode The **`mix-blend-mode`** [CSS](/en-US/docs/Web/CSS) property sets how an element's content should blend with the content of the element's parent and the element's background. -{{EmbedInteractiveExample("pages/css/mix-blend-mode.html")}} +{{InteractiveExample("CSS Demo: mix-blend-mode")}} + +```css interactive-example-choice +mix-blend-mode: normal; +``` + +```css interactive-example-choice +mix-blend-mode: multiply; +``` + +```css interactive-example-choice +mix-blend-mode: hard-light; +``` + +```css interactive-example-choice +mix-blend-mode: difference; +``` + +```html interactive-example +<section class="default-example" id="default-example"> + <div class="example-container"> + <img + id="example-element" + src="/shared-assets/images/examples/firefox-logo.svg" + width="200" /> + </div> +</section> +``` + +```css interactive-example +.example-container { + background-color: sandybrown; +} +``` ## Syntax diff --git a/files/en-us/web/css/mozilla_extensions/index.md b/files/en-us/web/css/mozilla_extensions/index.md index 6cb9f98e6cc390c..08fd8c20e1ade1e 100644 --- a/files/en-us/web/css/mozilla_extensions/index.md +++ b/files/en-us/web/css/mozilla_extensions/index.md @@ -1,5 +1,5 @@ --- -title: Mozilla vendor-prefixed CSS extensions +title: Firefox (-moz-) vendor-prefixed CSS extensions slug: Web/CSS/Mozilla_Extensions page-type: landing-page status: @@ -8,242 +8,134 @@ status: {{CSSRef}} -Firefox supports a number of _Mozilla extensions to [CSS](/en-US/docs/Web/CSS)_, including properties, values, pseudo-elements and pseudo-classes, at-rules, and media queries. These extensions are prefixed with `-moz-`. +A {{glossary("vendor prefix")}} is used to indicate that a feature is specific to a certain browser. +Firefox supports several extensions to [CSS](/en-US/docs/Web/CSS), which are prefixed with `-moz-`. -> [!NOTE] -> These extensions are mostly experimental or deprecated but kept for backward compatibility. Avoid using them on production websites. +## -moz-prefixed properties without standard equivalents -## Mozilla-only properties +> [!NOTE] +> These extensions are mostly experimental or deprecated but kept for backward compatibility. +> You should avoid using them on production websites. -- {{CSSxRef("box-align", "-moz-box-align")}} {{deprecated_inline}} -- {{CSSxRef("box-direction", "-moz-box-direction")}} {{deprecated_inline}} -- {{CSSxRef("box-flex", "-moz-box-flex")}} {{deprecated_inline}} -- {{CSSxRef("box-ordinal-group", "-moz-box-ordinal-group")}} {{deprecated_inline}} -- {{CSSxRef("box-orient", "-moz-box-orient")}} {{deprecated_inline}} -- {{CSSxRef("box-pack", "-moz-box-pack")}} {{deprecated_inline}} - {{CSSxRef("-moz-float-edge")}} {{deprecated_inline}} -- {{CSSxRef("-moz-force-broken-image-icon")}} {{deprecated_inline}} -- {{CSSxRef("-moz-image-region")}} {{deprecated_inline}} -- {{CSSxRef("-moz-orient")}} {{non-standard_inline}} -- {{CSSxRef("font-smooth", "-moz-osx-font-smoothing")}} {{non-standard_inline}} -- {{CSSxRef("-moz-user-focus")}} {{non-standard_inline}} -- {{CSSxRef("-moz-user-input")}} {{non-standard_inline}} -- {{CSSxRef("user-modify", "-moz-user-modify")}} {{non-standard_inline}} +- {{CSSxRef("-moz-force-broken-image-icon")}} {{deprecated_inline}}: Use `alt` text instead. +- {{CSSxRef("-moz-image-region")}} +- {{CSSxRef("-moz-orient")}} +- `-moz-osx-font-smoothing`: A similar {{CSSxRef("font-smooth")}} equivalent exists. +- {{CSSxRef("-moz-user-focus")}} {{deprecated_inline}} +- {{CSSxRef("-moz-user-input")}} {{deprecated_inline}} +- `-moz-user-modify`: A non-prefixed {{CSSxRef("user-modify")}} equivalent exists, but the HTML [`contenteditable`](/en-US/docs/Web/HTML/Reference/Global_attributes/contenteditable) attribute is recommended instead. -## Formerly proprietary properties that are now standard +## -moz-prefixed properties with standard equivalents -> [!NOTE] -> To maximize the compatibility of your CSS, you should use the unprefixed standard properties instead of the prefixed ones listed below. Once a given property is standardized and implemented without the prefix, the prefixed version is typically dropped after a while. +The following properties were implemented first using the `-moz-` vendor prefix, but are now supported in Firefox using the standard (non-prefixed) syntax. +Support for the prefixed version is typically dropped eventually, so use the standard property instead. ### A -- {{CSSxRef("animation", "-moz-animation")}} {{Deprecated_Inline}} (Prefixed version still supported) -- {{CSSxRef("animation-delay", "-moz-animation-delay")}} {{Deprecated_Inline}} (Prefixed version still supported) -- {{CSSxRef("animation-direction", "-moz-animation-direction")}} {{Deprecated_Inline}} (Prefixed version still supported) -- {{CSSxRef("animation-duration", "-moz-animation-duration")}} {{Deprecated_Inline}} (Prefixed version still supported) -- {{CSSxRef("animation-fill-mode", "-moz-animation-fill-mode")}} {{Deprecated_Inline}} (Prefixed version still supported) -- {{CSSxRef("animation-iteration-count", "-moz-animation-iteration-count")}} {{Deprecated_Inline}} (Prefixed version still supported) -- {{CSSxRef("animation-name", "-moz-animation-name")}} {{Deprecated_Inline}} (Prefixed version still supported) -- {{CSSxRef("animation-play-state", "-moz-animation-play-state")}} {{Deprecated_Inline}} (Prefixed version still supported) -- {{CSSxRef("animation-timing-function","-moz-animation-timing-function")}} {{Deprecated_Inline}} (Prefixed version still supported) -- {{CSSxRef("appearance","-moz-appearance")}} {{Experimental_Inline}} +- {{CSSxRef("animation", "-moz-animation")}} {{deprecated_inline}}: Prefixed version still supported. +- {{CSSxRef("animation-delay", "-moz-animation-delay")}} {{deprecated_inline}}: Prefixed version still supported. +- {{CSSxRef("animation-direction", "-moz-animation-direction")}} {{deprecated_inline}}: Prefixed version still supported. +- {{CSSxRef("animation-duration", "-moz-animation-duration")}} {{deprecated_inline}}: Prefixed version still supported. +- {{CSSxRef("animation-fill-mode", "-moz-animation-fill-mode")}} {{deprecated_inline}}: Prefixed version still supported. +- {{CSSxRef("animation-iteration-count", "-moz-animation-iteration-count")}} {{deprecated_inline}}: Prefixed version still supported. +- {{CSSxRef("animation-name", "-moz-animation-name")}} {{deprecated_inline}}: Prefixed version still supported. +- {{CSSxRef("animation-play-state", "-moz-animation-play-state")}} {{deprecated_inline}}: Prefixed version still supported. +- {{CSSxRef("animation-timing-function", "-moz-animation-timing-function")}} {{deprecated_inline}}: Prefixed version still supported. +- `-moz-appearance`: The prefixed version of {{CSSxRef("appearance")}} is still supported. ### B -- {{CSSxRef("backface-visibility", "-moz-backface-visibility")}} {{Deprecated_Inline}} (Prefixed version still supported) -- {{CSSxRef("background-clip", "-moz-background-clip")}} {{deprecated_inline}} -- {{CSSxRef("background-origin", "-moz-background-origin")}} {{deprecated_inline}} -- {{CSSxRef("box-decoration-break", "-moz-background-inline-policy")}} {{deprecated_inline}} (No longer supported; use the standard {{CSSxRef("box-decoration-break")}}) -- {{CSSxRef("background-size", "-moz-background-size")}} {{deprecated_inline}} -- {{CSSxRef("border-inline-end", "-moz-border-end")}} {{Deprecated_Inline}} (No longer supported; use the standard {{CSSxRef("border-inline-end")}}) -- {{CSSxRef("border-inline-color", "-moz-border-end-color")}} {{Deprecated_Inline}} (No longer supported; use the standard {{CSSxRef("border-inline-end-color")}}) -- {{CSSxRef("border-inline-style", "-moz-border-end-style")}} {{Deprecated_Inline}} (No longer supported; use the standard {{CSSxRef("border-inline-end-style")}}) -- {{CSSxRef("border-inline-width", "-moz-border-end-width")}} {{Deprecated_Inline}} (No longer supported; use the standard {{CSSxRef("border-inline-end-width")}}) -- {{CSSxRef("border-image", "-moz-border-image")}} {{Deprecated_Inline}} -- {{CSSxRef("border-inline-start", "-moz-border-start")}} {{Deprecated_Inline}} (No longer supported; use the standard {{CSSxRef("border-inline-start")}}) -- {{CSSxRef("border-inline-start-color", "-moz-border-start-color")}} {{Deprecated_Inline}} (No longer supported; use the standard {{CSSxRef("border-inline-start-color")}}) -- {{CSSxRef("border-inline-start-style", "-moz-border-start-style")}} {{Deprecated_Inline}} (No longer supported; use the standard {{CSSxRef("border-inline-start-style")}}) -- {{CSSxRef("border-inline-start-width", "-moz-border-start-width")}} {{Deprecated_Inline}} (No longer supported; use the standard {{CSSxRef("border-inline-start-width")}}) -- {{CSSxRef("box-sizing", "-moz-box-sizing")}} {{Deprecated_Inline}} (Prefixed version still supported) +- {{CSSxRef("backface-visibility", "-moz-backface-visibility")}} {{deprecated_inline}}: Prefixed version still supported. +- `-moz-background-clip` {{deprecated_inline}}: Not supported; use {{CSSxRef("background-clip")}}. +- `-moz-background-origin` {{deprecated_inline}}: Not supported; use {{CSSxRef("background-origin")}}. +- `-moz-box-align` {{deprecated_inline}}: Use [CSS flexbox](/en-US/docs/Web/CSS/CSS_flexible_box_layout) with {{CSSxRef("align-items")}}. +- `-moz-background-inline-policy` {{deprecated_inline}}: Not supported; use {{CSSxRef("box-decoration-break")}}. +- `-moz-box-direction` {{deprecated_inline}}: Use [CSS flexbox](/en-US/docs/Web/CSS/CSS_flexible_box_layout) with {{CSSxRef("flex-direction")}}. +- `-moz-box-flex` {{deprecated_inline}}: Use [CSS flexbox](/en-US/docs/Web/CSS/CSS_flexible_box_layout) with {{CSSxRef("flex-grow")}}. +- `-moz-box-ordinal-group` {{deprecated_inline}}: Use [CSS flexbox](/en-US/docs/Web/CSS/CSS_flexible_box_layout) with {{CSSxRef("order")}}. +- `-moz-box-orient` {{deprecated_inline}}: Use [CSS flexbox](/en-US/docs/Web/CSS/CSS_flexible_box_layout) with {{CSSxRef("flex-direction")}}. +- `-moz-box-pack` {{deprecated_inline}}: Use [CSS flexbox](/en-US/docs/Web/CSS/CSS_flexible_box_layout) with {{CSSxRef("justify-content")}}. +- `-moz-background-size` {{deprecated_inline}}: Not supported; use {{CSSxRef("background-size")}}. +- `-moz-border-end` {{deprecated_inline}}: Not supported; use {{CSSxRef("border-inline-end")}}. +- `-moz-border-end-color` {{deprecated_inline}}: Not supported; use {{CSSxRef("border-inline-end-color")}}. +- `-moz-border-end-style` {{deprecated_inline}}: Not supported; use {{CSSxRef("border-inline-end-style")}}. +- `-moz-border-end-width` {{deprecated_inline}}: Not supported; use {{CSSxRef("border-inline-end-width")}}. +- `-moz-border-image` {{deprecated_inline}}: Not supported; use {{CSSxRef("border-inline-end-width")}}. +- `-moz-border-start` {{deprecated_inline}}: Not supported; use {{CSSxRef("border-inline-start")}}. +- `-moz-border-start-color` {{deprecated_inline}}: Not supported; use {{CSSxRef("border-inline-start-color")}}. +- `-moz-border-start-style` {{deprecated_inline}}: Not supported; use {{CSSxRef("border-inline-start-style")}}. +- `-moz-border-start-width` {{deprecated_inline}}: Not supported; use {{CSSxRef("border-inline-start-width")}}. +- {{CSSxRef("box-sizing", "-moz-box-sizing")}} {{deprecated_inline}}: Prefixed version still supported. ### C -- {{CSSxRef("clip-path")}} {{Experimental_Inline}} (Applying to more than SVG) -- {{CSSxRef("column-count", "-moz-column-count")}} {{Deprecated_Inline}} (Prefixed version still supported) -- {{CSSxRef("column-fill", "-moz-column-fill")}} {{Deprecated_Inline}} (Prefixed version still supported) -- {{CSSxRef("column-gap", "-moz-column-gap")}} {{Deprecated_Inline}} (Prefixed version still supported) -- {{CSSxRef("column-width", "-moz-column-width")}} {{Deprecated_Inline}} (Prefixed version still supported) -- {{CSSxRef("column-rule", "-moz-column-rule")}} {{Deprecated_Inline}} (Prefixed version still supported) -- {{CSSxRef("column-rule-width", "-moz-column-rule-width")}} {{Deprecated_Inline}} (Prefixed version still supported) -- {{CSSxRef("column-rule-style", "-moz-column-rule-style")}} {{Deprecated_Inline}} (Prefixed version still supported) -- {{CSSxRef("column-rule-color", "-moz-column-rule-color")}} {{Deprecated_Inline}} (Prefixed version still supported) +- `-moz-column-count` {{deprecated_inline}}: Not supported; use {{CSSxRef("column-count")}}. +- `-moz-column-fill` {{deprecated_inline}}: Not supported; use {{CSSxRef("column-fill")}}. +- `-moz-column-gap` {{deprecated_inline}}: Not supported; use {{CSSxRef("column-gap")}}. +- `-moz-column-width` {{deprecated_inline}}: Not supported; use {{CSSxRef("column-width")}}. +- `-moz-column-rule` {{deprecated_inline}}: Not supported; use {{CSSxRef("column-rule")}}. +- `-moz-column-rule-width` {{deprecated_inline}}: Not supported; use {{CSSxRef("column-rule-width")}}. +- `-moz-column-rule-style` {{deprecated_inline}}: Not supported; use {{CSSxRef("column-rule-style")}}. +- `-moz-column-rule-color` {{deprecated_inline}}: Not supported; use {{CSSxRef("column-rule-color")}}. ### F–M -- {{CSSxRef("filter")}} {{Experimental_Inline}} (Applying to more than SVG) -- {{CSSxRef("font-feature-settings", "-moz-font-feature-settings")}} {{Deprecated_Inline}} (Prefixed version still supported) -- {{CSSxRef("font-language-override", "-moz-font-language-override")}} {{Deprecated_Inline}} (Prefixed version still supported) -- {{CSSxRef("hyphens", "-moz-hyphens")}} {{Deprecated_Inline}} (Prefixed version still supported) -- {{CSSxRef("margin-inline-end", "-moz-margin-end")}} {{Deprecated_Inline}} (No longer supported; use the standard {{CSSxRef("margin-inline-end")}}) -- {{CSSxRef("margin-inline-start", "-moz-margin-start")}} {{Deprecated_Inline}} (No longer supported; use the standard {{CSSxRef("margin-inline-start")}}) -- {{CSSxRef("mask")}} {{Experimental_Inline}} (Applying to more than SVG) - -### O - -- {{CSSxRef("opacity", "-moz-opacity")}} {{deprecated_inline}} -- {{CSSxRef("outline", "-moz-outline")}} {{deprecated_inline}} -- {{CSSxRef("outline-color", "-moz-outline-color")}} {{deprecated_inline}} -- {{CSSxRef("outline-offset", "-moz-outline-offset")}} {{deprecated_inline}} -- {{CSSxRef("outline-style", "-moz-outline-style")}} {{deprecated_inline}} -- {{CSSxRef("outline-width", "-moz-outline-width")}} {{deprecated_inline}} - -### P - -- {{CSSxRef("padding-inline-end", "-moz-padding-end")}} {{Deprecated_Inline}} (No longer supported; use the standard {{CSSxRef("padding-inline-end")}}) -- {{CSSxRef("padding-inline-start", "-moz-padding-start")}} {{Deprecated_Inline}} (No longer supported; use the standard {{CSSxRef("padding-inline-start")}}) -- {{CSSxRef("perspective", "-moz-perspective")}} {{Deprecated_Inline}} (Prefixed version still supported) -- {{CSSxRef("perspective-origin", "-moz-perspective-origin")}} {{Deprecated_Inline}} (Prefixed version still supported) -- {{CSSxRef("pointer-events")}} {{Experimental_Inline}} (Applying to more than SVG) - -### T–U - -- {{CSSxRef("tab-size", "-moz-tab-size")}} {{Experimental_Inline}} -- {{CSSxRef("text-align-last", "-moz-text-align-last")}} {{deprecated_inline}} -- {{CSSxRef("text-decoration-color", "-moz-text-decoration-color")}} {{deprecated_inline}} -- {{CSSxRef("text-decoration-line", "-moz-text-decoration-line")}} {{deprecated_inline}} -- {{CSSxRef("text-decoration-style", "-moz-text-decoration-style")}} {{deprecated_inline}} -- {{CSSxRef("text-size-adjust", "-moz-text-size-adjust")}} {{Experimental_Inline}} -- {{CSSxRef("transform", "-moz-transform")}} {{Deprecated_Inline}} (Prefixed version still supported) -- {{CSSxRef("transform-origin", "-moz-transform-origin")}} {{Deprecated_Inline}} (Prefixed version still supported) -- {{CSSxRef("transform-style", "-moz-transform-style")}} {{Deprecated_Inline}} (Prefixed version still supported) -- {{CSSxRef("transition", "-moz-transition")}} {{Deprecated_Inline}} (Prefixed version still supported) -- {{CSSxRef("transition-delay", "-moz-transition-delay")}} {{Deprecated_Inline}} (Prefixed version still supported) -- {{CSSxRef("transition-duration", "-moz-transition-duration")}} {{Deprecated_Inline}} (Prefixed version still supported) -- {{CSSxRef("transition-property", "-moz-transition-property")}} {{Deprecated_Inline}} (Prefixed version still supported) -- {{CSSxRef("transition-timing-function", "-moz-transition-timing-function")}} {{Deprecated_Inline}} (Prefixed version still supported) -- {{CSSxRef("user-select", "-moz-user-select")}} {{Experimental_Inline}} - -## Values +- {{CSSxRef("font-feature-settings", "-moz-font-feature-settings")}} {{deprecated_inline}}: Prefixed version still supported. +- {{CSSxRef("font-language-override", "-moz-font-language-override")}} {{deprecated_inline}}: Prefixed version still supported. +- {{CSSxRef("hyphens", "-moz-hyphens")}} {{deprecated_inline}}: Prefixed version still supported. +- `-moz-margin-end` {{deprecated_inline}}: Not supported; use {{CSSxRef("margin-inline-end")}}. +- `-moz-margin-start` {{deprecated_inline}}: Not supported; use {{CSSxRef("margin-inline-start")}}. + +### O-P + +- `-moz-opacity` {{deprecated_inline}}: Not supported; use {{CSSxRef("opacity")}}. +- `-moz-outline` {{deprecated_inline}}: Not supported; use {{CSSxRef("outline")}}. +- `-moz-outline-color` {{deprecated_inline}}: Not supported; use {{CSSxRef("outline-color")}}. +- `-moz-outline-offset` {{deprecated_inline}}: Not supported; use {{CSSxRef("outline-offset")}}. +- `-moz-outline-style` {{deprecated_inline}}: Not supported; use {{CSSxRef("outline-style")}}. +- `-moz-outline-width` {{deprecated_inline}}: Not supported; use {{CSSxRef("outline-width")}}. +- `-moz-padding-end` {{deprecated_inline}}: Not supported; use {{CSSxRef("padding-inline-end")}}. +- `-moz-padding-start` {{deprecated_inline}}: Not supported; use {{CSSxRef("padding-inline-start")}}. +- {{CSSxRef("perspective", "-moz-perspective")}} {{deprecated_inline}}: Prefixed version still supported. +- {{CSSxRef("perspective-origin", "-moz-perspective-origin")}} {{deprecated_inline}}: Prefixed version still supported. + +### T–Z + +- `-moz-tab-size`: Use {{CSSxRef("tab-size")}} +- `-moz-text-align-last` {{deprecated_inline}}: Not supported; use {{CSSxRef("text-align-last")}}. +- `-moz-text-decoration-color` {{deprecated_inline}}: Not supported; use {{CSSxRef("text-decoration-color")}}. +- `-moz-text-decoration-line` {{deprecated_inline}}: Not supported; use {{CSSxRef("text-decoration-line")}}. +- `-moz-text-decoration-style` {{deprecated_inline}}: Not supported; use {{CSSxRef("text-decoration-style")}}. +- `-moz-text-size-adjust`: See {{CSSxRef("text-size-adjust")}} {{Experimental_Inline}}. +- {{CSSxRef("transform", "-moz-transform")}} {{deprecated_inline}}: Prefixed version still supported. +- {{CSSxRef("transform-origin", "-moz-transform-origin")}} {{deprecated_inline}}: Prefixed version still supported. +- {{CSSxRef("transform-style", "-moz-transform-style")}} {{deprecated_inline}}: Prefixed version still supported. +- `-moz-transition` {{deprecated_inline}}: Not supported; use {{CSSxRef("transition")}}. +- `-moz-transition-delay` {{deprecated_inline}}: Not supported; use {{CSSxRef("transition-delay")}}. +- `-moz-transition-duration` {{deprecated_inline}}: Not supported; use {{CSSxRef("transition-duration")}}. +- `-moz-transition-property` {{deprecated_inline}}: Not supported; use {{CSSxRef("transition-property")}}. +- `-moz-transition-timing-function` {{deprecated_inline}}: Not supported; use {{CSSxRef("transition-timing-function")}}. +- `-moz-user-select`: Use {{CSSxRef("user-select")}}. + +## -moz-prefixed property values ### Global values -- {{CSSxRef("initial", "-moz-initial")}} - -### -moz-appearance - -Property: {{CSSxRef("appearance", "-moz-appearance")}} - -- `button` -- `button-arrow-down` -- `button-arrow-next` -- `button-arrow-previous` -- `button-arrow-up` -- `button-bevel` -- `checkbox` -- `checkbox-container` -- `checkbox-label` -- `checkmenuitem` -- `dialog` -- `groupbox` -- `listbox` -- `menuarrow` -- `menucheckbox` -- `menuimage` -- `menuitem` -- `menuitemtext` -- `menulist` -- `menulist-button` -- `menulist-text` -- `menulist-textfield` -- `menupopup` -- `menuradio` -- `menuseparator` -- `-moz-mac-unified-toolbar` -- `-moz-win-borderless-glass` -- `-moz-win-browsertabbar-toolbox` -- `-moz-win-communications-toolbox` -- `-moz-win-glass` -- `-moz-win-media-toolbox` -- `-moz-window-button-box` -- `-moz-window-button-box-maximized` -- `-moz-window-button-close` -- `-moz-window-button-maximize` -- `-moz-window-button-minimize` -- `-moz-window-button-restore` -- `-moz-window-titlebar` -- `-moz-window-titlebar-maximized` -- `progressbar` -- `progresschunk` -- `radio` -- `radio-container` -- `radio-label` -- `radiomenuitem` -- `resizer` -- `resizerpanel` -- `scale-horizontal` -- `scalethumb-horizontal` -- `scalethumb-vertical` -- `scale-vertical` -- `scrollbarbutton-down` -- `scrollbarbutton-left` -- `scrollbarbutton-right` -- `scrollbarbutton-up` -- `scrollbar-small` -- `scrollbarthumb-horizontal` -- `scrollbarthumb-vertical` -- `scrollbartrack-horizontal` -- `scrollbartrack-vertical` -- `separator` -- `spinner` -- `spinner-downbutton` -- `spinner-textfield` -- `spinner-upbutton` -- `statusbar` -- `statusbarpanel` -- `tab` -- `tabpanels` -- `tab-scroll-arrow-back` -- `tab-scroll-arrow-forward` -- `textfield` -- `textfield-multiline` -- `toolbar` -- `toolbarbutton-dropdown` -- `toolbox` -- `tooltip` -- `treeheadercell` -- `treeheadersortarrow` -- `treeitem` -- `treetwisty` -- `treetwistyopen` -- `treeview` -- `window` +- `-moz-initial`: See {{CSSxRef("initial")}}. ### background-image -Property: {{CSSxRef("background-image")}} - -#### Gradients - -- {{CSSxRef("gradient/linear-gradient","-moz-linear-gradient")}} {{Deprecated_Inline}} -- {{CSSxRef("gradient/radial-gradient","-moz-radial-gradient")}} {{Deprecated_Inline}} - -#### Elements - -- {{CSSxRef("element","-moz-element")}} +**Property:** {{CSSxRef("background-image")}} -#### Sub-images - -- {{CSSxRef("-moz-image-rect")}} - -### border-color - -Property: {{CSSxRef("border-color")}} - -- `-moz-use-text-color` {{deprecated_inline}} (removed in [Firefox bug 1306214](https://bugzil.la/1306214)); use {{CSSxRef("color_value#currentcolor_keyword","currentcolor")}} instead. +- `-moz-linear-gradient` {{deprecated_inline}}: Use {{CSSxRef("gradient/linear-gradient")}}. +- `-moz-radial-gradient` {{deprecated_inline}}: Use {{CSSxRef("gradient/radial-gradient")}}. +- `-moz-element` {{deprecated_inline}}: Use {{CSSxRef("element")}}. +- {{CSSxRef("-moz-image-rect")}} {{deprecated_inline}} ### order-style and outline-style -Properties: {{CSSxRef("border-style")}} and {{CSSxRef("outline-style")}} +**Properties:** {{CSSxRef("border-style")}} and {{CSSxRef("outline-style")}}. - `-moz-bg-inset` {{deprecated_inline}} - `-moz-bg-outset` {{deprecated_inline}} @@ -251,12 +143,11 @@ Properties: {{CSSxRef("border-style")}} and {{CSSxRef("outline-style")}} ### &lt;color&gt; keywords -Type: {{CSSxRef("&lt;color&gt;")}} +**Type:** {{CSSxRef("&lt;color&gt;")}} - `-moz-activehyperlinktext` - `-moz-hyperlinktext` - `-moz-visitedhyperlinktext` -- `-moz-buttondefault` - `-moz-buttonhoverface` - `-moz-buttonhovertext` - `-moz-default-background-color` @@ -267,231 +158,124 @@ Type: {{CSSxRef("&lt;color&gt;")}} - `-moz-fieldtext` - `-moz-dialog` - `-moz-dialogtext` -- `-moz-dragtargetzone` -- `-moz-mac-accentdarkestshadow` -- `-moz-mac-accentdarkshadow` -- `-moz-mac-accentface` -- `-moz-mac-accentlightesthighlight` -- `-moz-mac-accentlightshadow` -- `-moz-mac-accentregularhighlight` -- `-moz-mac-accentregularshadow` -- `-moz-mac-chrome-active` -- `-moz-mac-chrome-inactive` -- `-moz-mac-focusring` -- `-moz-mac-menuselect` -- `-moz-mac-menushadow` -- `-moz-mac-menutextselect` - `-moz-menuhover` - `-moz-menuhovertext` -- `-moz-win-communicationstext` -- `-moz-win-mediatext` -- `-moz-nativehyperlinktext` - -### display - -Property: {{CSSxRef("display")}} - -- `-moz-box` {{deprecated_inline}} -- `-moz-inline-block` {{deprecated_inline}} -- `-moz-inline-box` {{Deprecated_Inline}} -- `-moz-inline-grid` {{deprecated_inline}} -- `-moz-inline-stack` {{deprecated_inline}} -- `-moz-inline-table` {{deprecated_inline}} -- `-moz-grid` {{deprecated_inline}} -- `-moz-grid-group` {{deprecated_inline}} -- `-moz-grid-line` {{deprecated_inline}} -- `-moz-groupbox` {{deprecated_inline}} -- `-moz-deck` {{deprecated_inline}} -- `-moz-popup` {{deprecated_inline}} -- `-moz-stack` {{deprecated_inline}} -- `-moz-marker` {{deprecated_inline}} ### empty-cells -Property: {{CSSxRef("empty-cells")}} +**Property:** {{CSSxRef("empty-cells")}} - `-moz-show-background` (default value in quirks mode) -### font - -Property: {{CSSxRef("font")}} - -- `-moz-button` -- `-moz-info` -- `-moz-desktop` -- `-moz-dialog` (also a color) -- `-moz-document` -- `-moz-workspace` -- `-moz-window` -- `-moz-list` -- `-moz-pull-down-menu` -- `-moz-field` (also a color) - ### font-family -Property: {{CSSxRef("font-family")}} +**Property:** {{CSSxRef("font-family")}} - `-moz-fixed` ### image-rendering -Property: {{CSSxRef("image-rendering")}} +**Property:** {{CSSxRef("image-rendering")}} -- {{CSSxRef("image-rendering","-moz-crisp-edges")}} +- `-moz-crisp-edges` {{deprecated_inline}}: Use [`crisp-edges`](/en-US/docs/Web/CSS/image-rendering#crisp-edges). ### &lt;length&gt; -Type: {{CSSxRef("&lt;length&gt;")}} +**Type:** {{CSSxRef("&lt;length&gt;")}} -- {{CSSxRef("calc", "-moz-calc")}} +- `-moz-calc`{{deprecated_inline}}: Use {{CSSxRef("calc")}}. ### list-style-type -Property: {{CSSxRef("list-style-type")}} +**Property:** {{CSSxRef("list-style-type")}} + +Several vendor-prefixed values for `list-style-type` are now supported as standard values without a `-moz-` prefix, except for those in the following list. +See [Browser Compatibility](/en-US/docs/Web/CSS/list-style-type#browser_compatibility) for details. -- `-moz-arabic-indic` -- `-moz-bengali` -- `-moz-cjk-earthly-branch` -- `-moz-cjk-heavenly-stem` -- `-moz-devanagari` - `-moz-ethiopic-halehame` - `-moz-ethiopic-halehame-am` - `-moz-ethiopic-halehame-ti-er` - `-moz-ethiopic-halehame-ti-et` -- `-moz-ethiopic-numeric` -- `-moz-gujarati` -- `-moz-gurmukhi` - `-moz-hangul` - `-moz-hangul-consonant` -- `-moz-japanese-formal` -- `-moz-japanese-informal` -- `-moz-kannada` -- `-moz-khmer` -- `-moz-lao` -- `-moz-malayalam` -- `-moz-myanmar` -- `-moz-oriya` -- `-moz-persian` -- `-moz-simp-chinese-formal` -- `-moz-simp-chinese-informal` -- `-moz-tamil` -- `-moz-telugu` -- `-moz-thai` -- `-moz-trad-chinese-formal` -- `-moz-trad-chinese-informal` - `-moz-urdu` ### text-align -Property: {{CSSxRef("text-align")}} - -- `-moz-center` -- `-moz-left` -- `-moz-right` - -### text-decoration - -Property: {{CSSxRef("text-decoration")}} - -- `-moz-anchor-decoration` +**Property:** {{CSSxRef("text-align")}} -### -moz-user-select - -Property: {{CSSxRef("user-select", "-moz-user-select")}} - -- `-moz-all` -- `-moz-none` +- `-moz-center` {{deprecated_inline}}: Use {{CSSxRef("text-align", "text-align: center")}}. +- `-moz-left` {{deprecated_inline}}: Use {{CSSxRef("text-align", "text-align: left")}}. +- `-moz-right` {{deprecated_inline}}: Use {{CSSxRef("text-align", "text-align: right")}}. ### width, min-width, and max-width -Properties: {{CSSxRef("width")}}, {{CSSxRef("min-width")}}, and {{CSSxRef("max-width")}} - -- `-moz-min-content` -- `-moz-fit-content` -- `-moz-max-content` -- `-moz-available` +**Properties:** {{CSSxRef("width")}}, {{CSSxRef("min-width")}}, and {{CSSxRef("max-width")}} -## Pseudo-elements and pseudo-classes +- `-moz-min-content`: See {{CSSxRef("min-content")}}. +- `-moz-fit-content`: See {{CSSxRef("fit-content")}}. +- `-moz-max-content`: See {{CSSxRef("max-content")}}. +- `-moz-available`: See [`stretch`](/en-US/docs/Web/CSS/width#stretch). -### A – D +## Pseudo-classes -- {{CSSxRef("::-moz-anonymous-block")}} -- {{CSSxRef("::-moz-anonymous-positioned-block")}} -- {{CSSxRef(":is", ":-moz-any")}} -- {{CSSxRef(":any-link", ":-moz-any-link")}} \[Matches `:link` and `:visited`] -- {{CSSxRef(":-moz-broken")}} -- {{CSSxRef("::-moz-canvas")}} -- {{CSSxRef("::-moz-color-swatch")}} -- {{CSSxRef("::-moz-cell-content")}} +- `:-moz-any` {{deprecated_inline}}: Use {{CSSxRef(":is")}}. +- `:-moz-any-link` {{deprecated_inline}}: Use {{CSSxRef(":any-link")}}. +- {{CSSxRef(":-moz-broken")}} {{deprecated_inline}} - {{CSSxRef(":-moz-drag-over")}} - -### F – I - - {{CSSxRef(":-moz-first-node")}} -- {{CSSxRef("::-moz-focus-inner")}} -- {{CSSxRef("::-moz-focus-outer")}} -- {{CSSxRef(":fullscreen", ":-moz-full-screen")}} -- {{CSSxRef(":-moz-full-screen-ancestor")}} +- `:-moz-full-screen` {{deprecated_inline}}: Not supported; use {{CSSxRef(":fullscreen")}}. +- `:-moz-full-screen-ancestor` {{deprecated_inline}}: Not supported; use {{CSSxRef(":fullscreen")}}. - {{CSSxRef(":-moz-handler-blocked")}} - {{CSSxRef(":-moz-handler-crashed")}} - {{CSSxRef(":-moz-handler-disabled")}} -- {{CSSxRef("::-moz-inline-table")}} - -### L – M - - {{CSSxRef(":-moz-last-node")}} -- {{CSSxRef("::-moz-list-bullet")}} -- {{CSSxRef("::-moz-list-number")}} - {{CSSxRef(":-moz-loading")}} - {{CSSxRef(":-moz-locale-dir_ltr", ":-moz-locale-dir(ltr)")}} - {{CSSxRef(":-moz-locale-dir_rtl", ":-moz-locale-dir(rtl)")}} -- {{CSSxRef(":-moz-lwtheme")}} -- {{CSSxRef(":-moz-lwtheme-brighttext")}} -- {{CSSxRef(":-moz-lwtheme-darktext")}} -- {{CSSxRef("::-moz-meter-bar")}} +- `:-moz-native-anonymous` +- `:-moz-placeholder` {{deprecated_inline}}: Use {{CSSxRef(":placeholder-shown")}}. +- {{CSSxRef(":-moz-only-whitespace")}} +- `:-moz-read-only` {{deprecated_inline}}: Use {{CSSxRef(":read-only")}}. +- `:-moz-read-write` {{deprecated_inline}}: Use {{CSSxRef(":read-write")}}. +- {{CSSxRef(":-moz-submit-invalid")}}: See {{CSSxRef(":invalid")}}. +- {{CSSxRef(":-moz-suppressed")}} +- `:-moz-ui-invalid` {{deprecated_inline}}: Use {{CSSxRef(":user-invalid")}}. +- `:-moz-ui-valid` {{deprecated_inline}}: Use {{CSSxRef(":user-valid")}}. +- {{CSSxRef(":-moz-user-disabled")}} +- {{CSSxRef(":-moz-window-inactive")}} -### N – R +## Pseudo-elements -- {{CSSxRef(":-moz-native-anonymous")}} -- {{CSSxRef(":-moz-only-whitespace")}} -- {{CSSxRef("::-moz-pagebreak")}} -- {{CSSxRef("::-moz-pagecontent")}} -- {{CSSxRef(":placeholder-shown", ":-moz-placeholder")}} {{deprecated_inline}} -- {{CSSxRef("::placeholder", "::-moz-placeholder")}} {{deprecated_inline}} +- `::-moz-canvas` +- `::-moz-cell-content` +- {{CSSxRef("::-moz-color-swatch")}} +- {{CSSxRef("::-moz-focus-inner")}} +- `::-moz-focus-outer` +- `::-moz-inline-table` +- {{CSSxRef("::-moz-list-bullet")}} +- {{CSSxRef("::-moz-list-number")}} +- {{CSSxRef("::-moz-meter-bar")}} +- `::-moz-pagebreak` +- `::-moz-pagecontent` +- `::-moz-placeholder` {{deprecated_inline}}: Use {{CSSxRef("::placeholder")}}. - {{CSSxRef("::-moz-progress-bar")}} - {{CSSxRef("::-moz-range-progress")}} - {{CSSxRef("::-moz-range-thumb")}} - {{CSSxRef("::-moz-range-track")}} -- {{CSSxRef(":-moz-read-only")}} -- {{CSSxRef(":-moz-read-write")}} - -### S - -- {{CSSxRef("::-moz-scrolled-canvas")}} -- {{CSSxRef("::-moz-scrolled-content")}} -- {{CSSxRef("::selection","::-moz-selection")}} {{deprecated_inline}} -- {{CSSxRef(":-moz-submit-invalid")}} -- {{CSSxRef(":-moz-suppressed")}} -- {{CSSxRef("::-moz-svg-foreign-content")}} - -### T - -- {{CSSxRef("::-moz-table")}} -- {{CSSxRef("::-moz-table-cell")}} -- {{CSSxRef("::-moz-table-column")}} -- {{CSSxRef("::-moz-table-column-group")}} -- {{CSSxRef("::-moz-table-outer")}} -- {{CSSxRef("::-moz-table-row")}} -- {{CSSxRef("::-moz-table-row-group")}} - -### U – X - -- {{CSSxRef(":user-invalid", ":-moz-ui-invalid")}} {{deprecated_inline}} -- {{CSSxRef(":user-valid", ":-moz-ui-valid")}} {{deprecated_inline}} -- {{CSSxRef(":-moz-user-disabled")}} -- {{CSSxRef("::-moz-viewport")}} -- {{CSSxRef("::-moz-viewport-scroll")}} -- {{CSSxRef(":-moz-window-inactive")}} +- `::-moz-scrolled-canvas` +- `::-moz-scrolled-content` +- `::-moz-selection` {{deprecated_inline}}: Use {{CSSxRef("::selection")}}. +- `::-moz-svg-foreign-content` +- `::-moz-table` +- `::-moz-table-cell` +- `::-moz-table-column` +- `::-moz-table-column-group` +- `::-moz-table-outer` +- `::-moz-table-row` +- `::-moz-table-row-group` +- `::-moz-viewport` +- `::-moz-viewport-scroll` ## At-rules @@ -500,15 +284,14 @@ Properties: {{CSSxRef("width")}}, {{CSSxRef("min-width")}}, and {{CSSxRef("max-w ## Media features - {{CSSxRef("@media/-moz-device-pixel-ratio", "-moz-device-pixel-ratio")}} {{deprecated_inline}} -- {{CSSxRef("@media/-moz-os-version", "-moz-os-version")}} -- {{CSSxRef("@media/-moz-touch-enabled", "-moz-touch-enabled")}} -- {{CSSxRef("@media/-moz-windows-glass", "-moz-windows-glass")}} +- `-moz-platform` +- `-moz-windows-glass` ## Other -- {{CSSxRef("-moz-alt-content")}} (see [Firefox bug 11011](https://bugzil.la/11011)) +- `-moz-alt-content`: See [Firefox bug 11011](https://bugzil.la/11011) ## See also -- [Vendor Prefix](/en-US/docs/Glossary/Vendor_Prefix) glossary entry -- [WebKit vendor-prefixed CSS extensions](/en-US/docs/Web/CSS/WebKit_Extensions) +- [WebKit (-webkit-) vendor-prefixed CSS extensions](/en-US/docs/Web/CSS/WebKit_Extensions) +- {{glossary("Vendor Prefix")}} glossary entry diff --git a/files/en-us/web/css/object-fit/index.md b/files/en-us/web/css/object-fit/index.md index 766894161a05178..76566985ebdecd0 100644 --- a/files/en-us/web/css/object-fit/index.md +++ b/files/en-us/web/css/object-fit/index.md @@ -7,14 +7,51 @@ browser-compat: css.properties.object-fit {{CSSRef}} -The **`object-fit`** [CSS](/en-US/docs/Web/CSS) property sets how the content of a [replaced element](/en-US/docs/Web/CSS/Replaced_element), such as an {{HTMLElement("img")}} or {{HTMLElement("video")}}, should be resized to fit its container. +The **`object-fit`** [CSS](/en-US/docs/Web/CSS) property sets how the content of a {{ glossary("replaced elements", "replaced element")}}, such as an {{HTMLElement("img")}} or {{HTMLElement("video")}}, should be resized to fit its container. > [!NOTE] > The `object-fit` property has no effect on {{HTMLElement("iframe")}}, {{HTMLElement("embed")}}, and {{HTMLElement("fencedframe")}} elements. You can alter the alignment of the replaced element's content object within the element's box using the {{cssxref("object-position")}} property. -{{EmbedInteractiveExample("pages/css/object-fit.html")}} +{{InteractiveExample("CSS Demo: object-fit")}} + +```css interactive-example-choice +object-fit: fill; +``` + +```css interactive-example-choice +object-fit: contain; +``` + +```css interactive-example-choice +object-fit: cover; +``` + +```css interactive-example-choice +object-fit: none; +``` + +```css interactive-example-choice +object-fit: scale-down; +``` + +```html interactive-example +<section id="default-example"> + <img + class="transition-all" + id="example-element" + src="/shared-assets/images/examples/plumeria-146x200.jpg" /> +</section> +``` + +```css interactive-example +#example-element { + height: 100%; + width: 100%; + border: 2px dotted #888; +} +``` ## Syntax diff --git a/files/en-us/web/css/object-position/index.md b/files/en-us/web/css/object-position/index.md index 5d8174ca8fe3aed..7b779ff395a5caf 100644 --- a/files/en-us/web/css/object-position/index.md +++ b/files/en-us/web/css/object-position/index.md @@ -7,11 +7,45 @@ browser-compat: css.properties.object-position {{CSSRef}} -The **`object-position`** [CSS](/en-US/docs/Web/CSS) property specifies the alignment of the selected [replaced element](/en-US/docs/Web/CSS/Replaced_element)'s contents within the element's box. Areas of the box which aren't covered by the replaced element's object will show the element's background. +The **`object-position`** [CSS](/en-US/docs/Web/CSS) property specifies the alignment of the selected {{ glossary("replaced elements", "replaced element")}}'s contents within the element's box. Areas of the box which aren't covered by the replaced element's object will show the element's background. You can adjust how the replaced element's object's intrinsic size (that is, its natural size) is adjusted to fit within the element's box using the {{cssxref("object-fit")}} property. -{{EmbedInteractiveExample("pages/css/object-position.html")}} +{{InteractiveExample("CSS Demo: object-position")}} + +```css interactive-example-choice +object-position: 50% 50%; +``` + +```css interactive-example-choice +object-position: right top; +``` + +```css interactive-example-choice +object-position: left bottom; +``` + +```css interactive-example-choice +object-position: 250px 125px; +``` + +```html interactive-example +<section id="default-example"> + <img + class="transition-all" + id="example-element" + src="/shared-assets/images/examples/moon.jpg" /> +</section> +``` + +```css interactive-example +#example-element { + height: 250px; + width: 250px; + object-fit: none; + border: 1px solid red; +} +``` ## Syntax diff --git a/files/en-us/web/css/offset-anchor/index.md b/files/en-us/web/css/offset-anchor/index.md index 7257f416bef8c3d..186d4e253012cf5 100644 --- a/files/en-us/web/css/offset-anchor/index.md +++ b/files/en-us/web/css/offset-anchor/index.md @@ -9,7 +9,93 @@ browser-compat: css.properties.offset-anchor The **`offset-anchor`** [CSS](/en-US/docs/Web/CSS) property specifies the point inside the box of an element traveling along an {{cssxref("offset-path")}} that is actually moving along the path. -{{EmbedInteractiveExample("pages/css/offset-anchor.html")}} +{{InteractiveExample("CSS Demo: offset-anchor")}} + +```css interactive-example-choice +offset-anchor: auto; +``` + +```css interactive-example-choice +offset-anchor: right top; +``` + +```css interactive-example-choice +offset-anchor: left bottom; +``` + +```css interactive-example-choice +offset-anchor: 20% 80%; +``` + +```html interactive-example +<section class="default-example" id="default-example"> + <div class="wrapper"> + <div id="example-element"></div> + </div> + <button id="playback" type="button">Play</button> +</section> +``` + +```css interactive-example +#example-element { + offset-path: path("M 0,20 L 200,20"); + animation: distance 3000ms infinite alternate ease-in-out; + width: 40px; + height: 40px; + background: cyan; + animation-play-state: paused; +} + +#example-element.running { + animation-play-state: running; +} + +.wrapper { + background-image: linear-gradient( + to bottom, + transparent, + transparent 49%, + #000 50%, + #000 51%, + transparent 52% + ); + border: 1px solid #ccc; + width: 90%; +} + +@keyframes distance { + 0% { + offset-distance: 0%; + } + 100% { + offset-distance: 100%; + } +} + +#playback { + position: absolute; + top: 0; + left: 0; + font-size: 1em; +} +``` + +```js interactive-example +window.addEventListener("load", () => { + const example = document.getElementById("example-element"); + const button = document.getElementById("playback"); + + button.addEventListener("click", () => { + if (example.classList.contains("running")) { + example.classList.remove("running"); + button.textContent = "Play"; + } else { + example.classList.add("running"); + button.textContent = "Pause"; + } + }); +}); +``` ## Syntax @@ -146,4 +232,4 @@ section { - {{cssxref("offset")}} - {{cssxref("offset-distance")}} - {{cssxref("offset-rotate")}} -- [SVG `<path>`](/en-US/docs/Web/SVG/Tutorial/Paths) +- [SVG `<path>`](/en-US/docs/Web/SVG/Tutorials/SVG_from_scratch/Paths) diff --git a/files/en-us/web/css/offset-distance/index.md b/files/en-us/web/css/offset-distance/index.md index e27577a16441dec..13a079fb51f7d7c 100644 --- a/files/en-us/web/css/offset-distance/index.md +++ b/files/en-us/web/css/offset-distance/index.md @@ -9,7 +9,42 @@ browser-compat: css.properties.offset-distance The **`offset-distance`** [CSS](/en-US/docs/Web/CSS) property specifies a position along an {{CSSxRef("offset-path")}} for an element to be placed. -{{EmbedInteractiveExample("pages/css/offset-distance.html")}} +{{InteractiveExample("CSS Demo: offset-distance")}} + +```css interactive-example-choice +offset-distance: 0%; +``` + +```css interactive-example-choice +offset-distance: 80%; +``` + +```css interactive-example-choice +offset-distance: 50px; +``` + +```html interactive-example +<section class="default-example" id="default-example"> + <div class="transition-all" id="example-element"></div> +</section> +``` + +```css interactive-example +#example-element { + width: 24px; + height: 24px; + background: #2bc4a2; + offset-path: path("M-70,-40 C-70,70 70,70 70,-40"); + clip-path: polygon(0% 0%, 70% 0%, 100% 50%, 70% 100%, 0% 100%, 30% 50%); +} + +/* Provides a reference image of what path the element is following */ +#default-example { + background-position: calc(50% - 12px) calc(50% + 14px); + background-repeat: no-repeat; + background-image: url('data:image/svg+xml;utf8,<svg xmlns="http://www.w3.org/2000/svg" viewBox="-75 -45 150 140" width="150" height="140"><path d="M-70,-40 C-70,70 70,70 70,-40" fill="none" stroke="lightgrey" stroke-width="2" stroke-dasharray="4.5"/></svg>'); +} +``` ## Syntax diff --git a/files/en-us/web/css/offset-path/index.md b/files/en-us/web/css/offset-path/index.md index d02d87d9449d242..cb25b314e090774 100644 --- a/files/en-us/web/css/offset-path/index.md +++ b/files/en-us/web/css/offset-path/index.md @@ -11,7 +11,74 @@ The **`offset-path`** [CSS](/en-US/docs/Web/CSS) property specifies a path for a The `offset-path` property is used in combination with the {{cssxref("offset-distance")}}, {{cssxref("offset-rotate")}}, and {{cssxref("offset-anchor")}} properties to control the position and orientation of the element along a path. -{{EmbedInteractiveExample("pages/css/offset-path.html")}} +{{InteractiveExample("CSS Demo: offset-path")}} + +```css interactive-example-choice +offset-path: path("M-70,-40 C-70,70 70,70 70,-40"); +``` + +```css interactive-example-choice +offset-path: path("M0,0 L60,70 L-60,30z"); +``` + +```html interactive-example +<section class="default-example" id="default-example"> + <div class="transition-all" id="example-element"></div> + <button id="playback" type="button">Play</button> +</section> +``` + +```css interactive-example +#example-element { + width: 24px; + height: 24px; + background: #2bc4a2; + animation: distance 8000ms infinite linear; + animation-play-state: paused; + clip-path: polygon(0% 0%, 70% 0%, 100% 50%, 70% 100%, 0% 100%, 30% 50%); +} + +#example-element.running { + animation-play-state: running; +} + +#playback { + position: absolute; + top: 0; + left: 0; + font-size: 1em; +} + +@keyframes distance { + 0% { + offset-distance: 0%; + } + 100% { + offset-distance: 100%; + } +} + +#default-example { + position: relative; +} +``` + +```js interactive-example +window.addEventListener("load", () => { + const example = document.getElementById("example-element"); + const button = document.getElementById("playback"); + + button.addEventListener("click", () => { + if (example.classList.contains("running")) { + example.classList.remove("running"); + button.textContent = "Play"; + } else { + example.classList.add("running"); + button.textContent = "Pause"; + } + }); +}); +``` ## Syntax @@ -70,7 +137,7 @@ The `offset-path` property takes as its value an `<offset-path>` value, a [`<coo - {{cssxref("url_value", "&lt;url&gt;")}} - - : Specifies the ID of an [SVG shape element](/en-US/docs/Web/SVG/Tutorial/Basic_Shapes). The path is the shape of the SVG {{SVGElement("circle")}}, {{SVGElement("ellipse")}}, {{SVGElement("line")}}, {{SVGElement("path")}}, {{SVGElement("polygon")}}, {{SVGElement("polyline")}}, or {{SVGElement("rect")}} element referenced by its `id` in the `url()` function. If the URL does not reference a shape element or is otherwise invalid, the resolved value for the offset path is `path("M0,0")` (which is a valid `<basic-shape>` value). + - : Specifies the ID of an [SVG shape element](/en-US/docs/Web/SVG/Tutorials/SVG_from_scratch/Basic_shapes). The path is the shape of the SVG {{SVGElement("circle")}}, {{SVGElement("ellipse")}}, {{SVGElement("line")}}, {{SVGElement("path")}}, {{SVGElement("polygon")}}, {{SVGElement("polyline")}}, or {{SVGElement("rect")}} element referenced by its `id` in the `url()` function. If the URL does not reference a shape element or is otherwise invalid, the resolved value for the offset path is `path("M0,0")` (which is a valid `<basic-shape>` value). - {{cssxref("basic-shape")}} @@ -241,10 +308,9 @@ The SVG rectangle that defines the path shape is shown here only to visually dem <div class="outer"> <div class="target"></div> </div> - <svg width="400" height="200" xmlns="http://www.w3.org/2000/svg" > - <rect id="svgRect" x="50" y="50" width="200" height="100" /> - </svg> -</div> +<svg width="400" height="200" xmlns="http://www.w3.org/2000/svg"> + <rect id="svgRect" x="50" y="50" width="200" height="100" /> +</svg> ``` ```css hidden live-sample___offset_path_url @@ -295,7 +361,7 @@ The SVG rectangle that defines the path shape is shown here only to visually dem - {{cssxref("offset")}} - {{cssxref("offset-distance")}} - {{cssxref("offset-rotate")}} -- [SVG \<path>](/en-US/docs/Web/SVG/Tutorial/Paths) +- [SVG \<path>](/en-US/docs/Web/SVG/Tutorials/SVG_from_scratch/Paths) - {{cssxref("basic-shape/path","path()")}} - Other demos: - [Examples using various shapes values](https://codepen.io/team/css-tricks/pen/WZdKMq) on CodePen by CSS-Tricks diff --git a/files/en-us/web/css/offset-position/index.md b/files/en-us/web/css/offset-position/index.md index c94a018040a5bb6..837b7ae101ca506 100644 --- a/files/en-us/web/css/offset-position/index.md +++ b/files/en-us/web/css/offset-position/index.md @@ -66,7 +66,7 @@ offset-position: unset; ### Setting initial offset-position for an offset-path -In this example, the {{cssxref("offset-path")}} property is used to define the path along which the `cyan` element should move. The value of the {{cssxref("basic-shape/path", "path()")}} CSS function is an [SVG data path](/en-US/docs/Web/SVG/Attribute/d) that describes a curved path. The element moves along this curved path during the `move` animation. +In this example, the {{cssxref("offset-path")}} property is used to define the path along which the `cyan` element should move. The value of the {{cssxref("basic-shape/path", "path()")}} CSS function is an [SVG data path](/en-US/docs/Web/SVG/Reference/Attribute/d) that describes a curved path. The element moves along this curved path during the `move` animation. #### HTML diff --git a/files/en-us/web/css/offset-rotate/index.md b/files/en-us/web/css/offset-rotate/index.md index 5d309d59d2512e4..9eb420a51ea17ff 100644 --- a/files/en-us/web/css/offset-rotate/index.md +++ b/files/en-us/web/css/offset-rotate/index.md @@ -9,7 +9,87 @@ browser-compat: css.properties.offset-rotate The **`offset-rotate`** [CSS](/en-US/docs/Web/CSS) property defines the orientation/direction of the element as it is positioned along the {{cssxref("offset-path")}}. -{{EmbedInteractiveExample("pages/css/offset-rotate.html")}} +{{InteractiveExample("CSS Demo: offset-rotate")}} + +```css interactive-example-choice +offset-rotate: auto; +``` + +```css interactive-example-choice +offset-rotate: 90deg; +``` + +```css interactive-example-choice +offset-rotate: auto 90deg; +``` + +```css interactive-example-choice +offset-rotate: reverse; +``` + +```html interactive-example +<section class="default-example" id="default-example"> + <div class="transition-all" id="example-element"></div> + <button id="playback" type="button">Play</button> +</section> +``` + +```css interactive-example +#example-element { + width: 24px; + height: 24px; + background: #2bc4a2; + offset-path: path("M-70,-40 C-70,70 70,70 70,-40"); + animation: distance 8000ms infinite linear; + animation-play-state: paused; + clip-path: polygon(0% 0%, 70% 0%, 100% 50%, 70% 100%, 0% 100%, 30% 50%); +} + +#example-element.running { + animation-play-state: running; +} + +#playback { + position: absolute; + top: 0; + left: 0; + font-size: 1em; +} + +@keyframes distance { + 0% { + offset-distance: 0%; + } + 100% { + offset-distance: 100%; + } +} + +/* Provides a reference image of what path the element is following */ +#default-example { + position: relative; + background-position: calc(50% - 12px) calc(50% + 14px); + background-repeat: no-repeat; + background-image: url('data:image/svg+xml;utf8,<svg xmlns="http://www.w3.org/2000/svg" viewBox="-75 -45 150 140" width="150" height="140"><path d="M-70,-40 C-70,70 70,70 70,-40" fill="none" stroke="lightgrey" stroke-width="2" stroke-dasharray="4.5"/></svg>'); +} +``` + +```js interactive-example +window.addEventListener("load", () => { + const example = document.getElementById("example-element"); + const button = document.getElementById("playback"); + + button.addEventListener("click", () => { + if (example.classList.contains("running")) { + example.classList.remove("running"); + button.textContent = "Play"; + } else { + example.classList.add("running"); + button.textContent = "Pause"; + } + }); +}); +``` > [!NOTE] > Early versions of the spec called this property `motion-rotation`. diff --git a/files/en-us/web/css/offset/index.md b/files/en-us/web/css/offset/index.md index 7ee30c2a5c1df61..26bfe52ec783923 100644 --- a/files/en-us/web/css/offset/index.md +++ b/files/en-us/web/css/offset/index.md @@ -12,7 +12,82 @@ The **`offset`** CSS [shorthand property](/en-US/docs/Web/CSS/CSS_cascade/Shorth > [!NOTE] > Early versions of the spec called this property `motion`. -{{EmbedInteractiveExample("pages/css/offset.html")}} +{{InteractiveExample("CSS Demo: offset")}} + +```css interactive-example-choice +offset: path("M 20 60 L 120 60 L 70 10 L 20 60") 0% auto 90deg; +``` + +```css interactive-example-choice +offset: path( + "M 20 210 L 74 210 L 118 140 \ + L 62 140 L 20 210" + ) + 20% auto; +``` + +```html interactive-example +<section class="default-example" id="default-example"> + <div class="wrapper"> + <div id="example-element"></div> + </div> + <button id="playback" type="button">Play</button> +</section> +``` + +```css interactive-example +#example-element { + width: 24px; + height: 24px; + background: #2bc4a2; + clip-path: polygon(0% 0%, 70% 0%, 100% 50%, 70% 100%, 0% 100%, 30% 50%); + animation: distance 3000ms infinite normal ease-in-out; + animation-play-state: paused; +} + +#example-element.running { + animation-play-state: running; +} + +.wrapper { + height: 220px; + width: 200px; + background: + url('data:image/svg+xml;utf8,<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 150 140" width="200" height="140"><path d="M 0 60 L 100 60 L 50 10 L 0 60" fill="none" stroke="lightgrey" stroke-width="2" stroke-dasharray="4.5"/></svg>') + no-repeat, + url('data:image/svg+xml;utf8,<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 -140 150 230" width="200" height="230"><path d="M 0 70 L 56 70 L 98 0 L 42 0 L 0 70" fill="none" stroke="lightgrey" stroke-width="2" stroke-dasharray="4.5"/></svg>'); +} + +@keyframes distance { + to { + offset-distance: 100%; + } +} + +#playback { + position: absolute; + top: 0; + left: 0; + font-size: 1em; +} +``` + +```js interactive-example +window.addEventListener("load", () => { + const example = document.getElementById("example-element"); + const button = document.getElementById("playback"); + + button.addEventListener("click", () => { + if (example.classList.contains("running")) { + example.classList.remove("running"); + button.textContent = "Play"; + } else { + example.classList.add("running"); + button.textContent = "Pause"; + } + }); +}); +``` ## Constituent properties diff --git a/files/en-us/web/css/opacity/index.md b/files/en-us/web/css/opacity/index.md index e3ab5695d33eff6..b18cdd436c40c41 100644 --- a/files/en-us/web/css/opacity/index.md +++ b/files/en-us/web/css/opacity/index.md @@ -9,7 +9,39 @@ browser-compat: css.properties.opacity The **`opacity`** [CSS](/en-US/docs/Web/CSS) property sets the opacity of an element. Opacity is the degree to which content behind an element is hidden, and is the opposite of transparency. -{{EmbedInteractiveExample("pages/css/opacity.html")}} +{{InteractiveExample("CSS Demo: opacity")}} + +```css interactive-example-choice +opacity: 0; +``` + +```css interactive-example-choice +opacity: 0.33; +``` + +```css interactive-example-choice +opacity: 1; +``` + +```html interactive-example +<section class="default-example" id="default-example"> + <p id="example-element"> + London. Michaelmas term lately over, and the Lord Chancellor sitting in + Lincoln's Inn Hall. Implacable November weather. As much mud in the streets + as if the waters had but newly retired from the face of the earth, and it + would not be wonderful to meet a Megalosaurus, forty feet long or so, + waddling like an elephantine lizard up Holborn Hill. + </p> +</section> +``` + +```css interactive-example +#example-element { + background-color: #963770; + color: white; + padding: 1em; +} +``` ## Syntax @@ -47,15 +79,15 @@ To change the opacity of a background only, use the {{cssxref("background")}} pr background: rgb(0 0 0 / 40%); ``` -When `opacity` value is set to `0`, the element and all of its children appear invisible, but they are still part of the DOM. That means they still register [pointer events](/en-US/docs/Web/API/Pointer_events) and, if the elements are in a tabbing order, they do get focus. For good usability, make sure to make such elements visible when they receive user interactions or use the CSS [`pointer-events`](/en-US/docs/Web/CSS/pointer-events) property to disable pointer events and take the element out of the tab order by disabling with the `disabled` attribute or setting [`tab-index="-1"`](/en-US/docs/Web/HTML/Global_attributes/tabindex) for non-form-related interactive elements. +When `opacity` value is set to `0`, the element and all of its children appear invisible, but they are still part of the DOM. That means they still register [pointer events](/en-US/docs/Web/API/Pointer_events) and, if the elements are in a tabbing order, they do get focus. For good usability, make sure to make such elements visible when they receive user interactions or use the CSS [`pointer-events`](/en-US/docs/Web/CSS/pointer-events) property to disable pointer events and take the element out of the tab order by disabling with the `disabled` attribute or setting [`tab-index="-1"`](/en-US/docs/Web/HTML/Reference/Global_attributes/tabindex) for non-form-related interactive elements. -Using `opacity` with a value other than `1` places the element in a new [stacking context](/en-US/docs/Web/CSS/CSS_positioned_layout/Understanding_z-index/Stacking_context). +Using `opacity` with a value other than `1` places the element in a new [stacking context](/en-US/docs/Web/CSS/CSS_positioned_layout/Stacking_context). -Opacity alone should not be used to provide information to screen readers. Use the HTML [`hidden`](/en-US/docs/Web/HTML/Global_attributes/hidden) attribute, CSS [`visibility`](/en-US/docs/Web/CSS/visibility), or CSS [`display`](/en-US/docs/Web/CSS/display) style properties. It's best to avoid using [`aria-hidden`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-hidden) attribute, but if the element is hidden with opacity, then hide it from screen readers as well. +Opacity alone should not be used to provide information to screen readers. Use the HTML [`hidden`](/en-US/docs/Web/HTML/Reference/Global_attributes/hidden) attribute, CSS [`visibility`](/en-US/docs/Web/CSS/visibility), or CSS [`display`](/en-US/docs/Web/CSS/display) style properties. It's best to avoid using [`aria-hidden`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-hidden) attribute, but if the element is hidden with opacity, then hide it from screen readers as well. ### Transitioning opacity -When [transitioning](/en-US/docs/Web/CSS/CSS_transitions) the opacity of elements as you add them to the page when content was formerly hidden with [`visibility: hidden`](/en-US/docs/Web/CSS/visibility#hidden), [`display: none`](/en-US/docs/Web/CSS/display#none), or [`content-visibility: hidden`](/en-US/docs/Web/CSS/content-visibility#hidden), you need to include both a [`@starting-style`](/en-US/docs/Web/CSS/@starting-style) and [`transition-behaviour: allow-discrete`](/en-US/docs/Web/CSS/transition-behavior#allow-discrete): +When [transitioning](/en-US/docs/Web/CSS/CSS_transitions) the opacity of elements as you add them to the page when content was formerly hidden with [`visibility: hidden`](/en-US/docs/Web/CSS/visibility#hidden), [`display: none`](/en-US/docs/Web/CSS/display#none), or [`content-visibility: hidden`](/en-US/docs/Web/CSS/content-visibility#hidden), you need to include both a [`@starting-style`](/en-US/docs/Web/CSS/@starting-style) and [`transition-behavior: allow-discrete`](/en-US/docs/Web/CSS/transition-behavior#allow-discrete): ```css .card { @@ -87,7 +119,7 @@ If text opacity is adjusted, it is important to ensure that the contrast ratio b Color contrast ratio is determined by comparing the luminosity of the opacity-adjusted text and background color values. In order to meet current [Web Content Accessibility Guidelines (WCAG)](https://www.w3.org/WAI/standards-guidelines/wcag/), a ratio of 4.5:1 is required for text content and 3:1 for larger text such as headings. Large text is defined as 18.66px and [bold](/en-US/docs/Web/CSS/font-weight) or larger, or 24px or larger. - [WebAIM: Color Contrast Checker](https://webaim.org/resources/contrastchecker/) -- [MDN Understanding WCAG, Guideline 1.4 explanations](/en-US/docs/Web/Accessibility/Understanding_WCAG/Perceivable#guideline_1.4_make_it_easier_for_users_to_see_and_hear_content_including_separating_foreground_from_background) +- [MDN Understanding WCAG, Guideline 1.4 explanations](/en-US/docs/Web/Accessibility/Guides/Understanding_WCAG/Perceivable#guideline_1.4_make_it_easier_for_users_to_see_and_hear_content_including_separating_foreground_from_background) - [Understanding Success Criterion 1.4.3 | W3C Understanding WCAG 2.0](https://www.w3.org/TR/UNDERSTANDING-WCAG20/visual-audio-contrast-contrast.html) Various operating systems provide a preference for reducing transparency. To set the `opacity` based on the user's operating systems transparency preferences, use the [`prefers-reduced-transparency`](/en-US/docs/Web/CSS/@media/prefers-reduced-transparency) media query. @@ -146,7 +178,7 @@ In the following example opacity is changed on hover, so the striped background ```html <div class="wrapper"> <img - src="//interactive-examples.mdn.mozilla.net/media/dino.svg" + src="/shared-assets/images/examples/dino.svg" alt="MDN Dino" width="128" height="146" diff --git a/files/en-us/web/css/order/index.md b/files/en-us/web/css/order/index.md index 33506e12dc81a6b..2c48638e1bc3f19 100644 --- a/files/en-us/web/css/order/index.md +++ b/files/en-us/web/css/order/index.md @@ -9,7 +9,60 @@ browser-compat: css.properties.order The **`order`** [CSS](/en-US/docs/Web/CSS) property sets the order to lay out an item in a flex or grid container. Items in a container are sorted by ascending `order` value and then by their source code order. Items not given an explicit `order` value are assigned the default value of `0`. -{{EmbedInteractiveExample("pages/css/order.html")}} +{{InteractiveExample("CSS Demo: order")}} + +```css interactive-example-choice +order: 0; +``` + +```css interactive-example-choice +order: 3; +``` + +```css interactive-example-choice +order: -1; +``` + +```css interactive-example-choice +order: 2; +``` + +```html interactive-example +<section class="default-example" id="default-example"> + <div class="transition-all" id="example-element">Box 1:</div> + <div style="order: 1">Box 2: <code>order: 1;</code></div> + <div style="order: 2">Box 3: <code>order: 2;</code></div> + <div style="order: 2">Box 4: <code>order: 2;</code></div> + <div style="order: 3">Box 5: <code>order: 3;</code></div> +</section> +``` + +```css interactive-example +.default-example { + max-height: 300px; + display: flex; + flex-flow: column; +} + +.default-example > div { + background-color: rgba(0, 0, 255, 0.2); + border: 3px solid blue; + margin: 0.5rem; + padding: 0.5rem; + flex: 1; +} + +#example-element { + background-color: rgba(255, 0, 200, 0.2); + border: 3px solid rebeccapurple; +} + +#example-element::after { + content: attr(style); + outline: 2px dashed; + font-family: monospace; +} +``` In the above demo, select the options on the left-hand side to change the value of the pink box's `order` property. The light blue boxes have been given fixed `order` values. @@ -30,7 +83,7 @@ order: revert-layer; order: unset; ``` -Since `order` is only meant to affect the _visual order_ of elements and not their logical or tab order, it must not be used on non-visual media such as [speech](/en-US/docs/Web/CSS/@media#speech). +Since `order` is only meant to affect the _visual order_ of elements and not their logical or tab order, it must not be used on non-visual media such as [speech](https://www.w3.org/TR/css-speech-1/). Defined in the [CSS display](/en-US/docs/Web/CSS/CSS_display) module, this property impacts only grid and flex items. When `order` is set on an element whose parent's {{cssxref("display")}} property is not creating a flex or grid container, it has no effect. @@ -45,7 +98,7 @@ Using the `order` property will create a disconnect between the visual presentat - [Flexbox & the keyboard navigation disconnect](https://tink.uk/flexbox-the-keyboard-navigation-disconnect/) via Tink (2016) - [Source Order Matters](https://adrianroselli.com/2015/09/source-order-matters.html) via Adrian Roselli (2015) -- [Understanding WCAG, Guideline 1.3 explanations](/en-US/docs/Web/Accessibility/Understanding_WCAG/Perceivable#guideline_1.3_—_create_content_that_can_be_presented_in_different_ways) +- [Understanding WCAG, Guideline 1.3 explanations](/en-US/docs/Web/Accessibility/Guides/Understanding_WCAG/Perceivable#guideline_1.3_—_create_content_that_can_be_presented_in_different_ways) - [Understanding Success Criterion 1.3.2 | W3C Understanding WCAG 2.0](https://www.w3.org/TR/UNDERSTANDING-WCAG20/content-structure-separation-sequence.html) ## Formal definition @@ -121,3 +174,4 @@ The `<article>` appears first in the source order but visually rendered in the c - [Ordering flex items](/en-US/docs/Web/CSS/CSS_flexible_box_layout/Ordering_flex_items) - [CSS grid layout and accessibility](/en-US/docs/Web/CSS/CSS_grid_layout/Grid_layout_and_accessibility) - [CSS display](/en-US/docs/Web/CSS/CSS_display) module +- {{glossary("Reading order")}} diff --git a/files/en-us/web/css/outline-color/index.md b/files/en-us/web/css/outline-color/index.md index 504933a77d96f3b..5ca896afd10ec3e 100644 --- a/files/en-us/web/css/outline-color/index.md +++ b/files/en-us/web/css/outline-color/index.md @@ -9,7 +9,44 @@ browser-compat: css.properties.outline-color The **`outline-color`** [CSS](/en-US/docs/Web/CSS) property sets the color of an element's outline. -{{EmbedInteractiveExample("pages/css/outline-color.html")}} +{{InteractiveExample("CSS Demo: outline-color")}} + +```css interactive-example-choice +outline-color: red; +``` + +```css interactive-example-choice +outline-color: #32a1ce; +``` + +```css interactive-example-choice +outline-color: rgba(170, 50, 220, 0.6); +``` + +```css interactive-example-choice +outline-color: hsla(60, 90%, 50%, 0.8); +``` + +```css interactive-example-choice +outline-color: currentcolor; +``` + +```html interactive-example +<section class="default-example" id="default-example"> + <div class="transition-all" id="example-element"> + This is a box with an outline around it. + </div> +</section> +``` + +```css interactive-example +#example-element { + outline: 0.75em solid; + padding: 0.75em; + width: 80%; + height: 100px; +} +``` ## Syntax @@ -49,7 +86,7 @@ Custom [focus styles](/en-US/docs/Web/CSS/:focus) commonly involve making adjust Color contrast ratio is determined by comparing the luminosity of the text and background color values. In order to meet current [Web Content Accessibility Guidelines (WCAG)](https://www.w3.org/WAI/standards-guidelines/wcag/), a ratio of 4.5:1 is required for text content and 3:1 for larger text such as headings. Large text is defined as 18.66px and [bold](/en-US/docs/Web/CSS/font-weight) or larger, or 24px or larger. - [WebAIM: Color Contrast Checker](https://webaim.org/resources/contrastchecker/) -- [MDN Understanding WCAG, Guideline 1.4 explanations](/en-US/docs/Web/Accessibility/Understanding_WCAG/Perceivable#guideline_1.4_make_it_easier_for_users_to_see_and_hear_content_including_separating_foreground_from_background) +- [MDN Understanding WCAG, Guideline 1.4 explanations](/en-US/docs/Web/Accessibility/Guides/Understanding_WCAG/Perceivable#guideline_1.4_make_it_easier_for_users_to_see_and_hear_content_including_separating_foreground_from_background) - [Understanding Success Criterion 1.4.3 | W3C Understanding WCAG 2.0](https://www.w3.org/TR/UNDERSTANDING-WCAG20/visual-audio-contrast-contrast.html) ## Formal definition diff --git a/files/en-us/web/css/outline-offset/index.md b/files/en-us/web/css/outline-offset/index.md index 4a8c2cd8f01d755..8cfad5d2c2d2325 100644 --- a/files/en-us/web/css/outline-offset/index.md +++ b/files/en-us/web/css/outline-offset/index.md @@ -9,7 +9,38 @@ browser-compat: css.properties.outline-offset The **`outline-offset`** [CSS](/en-US/docs/Web/CSS) property sets the amount of space between an [outline](/en-US/docs/Web/CSS/outline) and the edge or border of an element. -{{EmbedInteractiveExample("pages/css/outline-offset.html")}} +{{InteractiveExample("CSS Demo: outline-offset")}} + +```css interactive-example-choice +outline-offset: 4px; +``` + +```css interactive-example-choice +outline-offset: 0.6rem; +``` + +```css interactive-example-choice +outline-offset: 12px; +outline: 5px dashed blue; +``` + +```html interactive-example +<section class="default-example" id="default-example"> + <div class="transition-all" id="example-element"> + This is a box with an outline around it. + </div> +</section> +``` + +```css interactive-example +#example-element { + border: 2px solid crimson; + outline: 0.75em solid; + padding: 0.75em; + width: 80%; + height: 100px; +} +``` ## Syntax diff --git a/files/en-us/web/css/outline-style/index.md b/files/en-us/web/css/outline-style/index.md index e33dd72a6b4c1bd..77e430c10ef7da5 100644 --- a/files/en-us/web/css/outline-style/index.md +++ b/files/en-us/web/css/outline-style/index.md @@ -9,7 +9,44 @@ browser-compat: css.properties.outline-style The **`outline-style`** [CSS](/en-US/docs/Web/CSS) property sets the style of an element's outline. An outline is a line that is drawn around an element, outside the {{cssxref("border")}}. -{{EmbedInteractiveExample("pages/css/outline-style.html")}} +{{InteractiveExample("CSS Demo: outline-style")}} + +```css interactive-example-choice +outline-style: none; +``` + +```css interactive-example-choice +outline-style: dotted; +``` + +```css interactive-example-choice +outline-style: solid; +``` + +```css interactive-example-choice +outline-style: groove; +``` + +```css interactive-example-choice +outline-style: inset; +``` + +```html interactive-example +<section class="default-example" id="default-example"> + <div class="transition-all" id="example-element"> + This is a box with an outline around it. + </div> +</section> +``` + +```css interactive-example +#example-element { + outline: 0.75em solid; + padding: 0.75em; + width: 80%; + height: 100px; +} +``` It is often more convenient to use the shorthand property {{cssxref("outline")}} when defining the appearance of an outline. @@ -73,7 +110,7 @@ The `outline-style` property is specified as any one of the values listed below. ### Setting outline style to auto -The `auto` value indicates a custom outline style, described in [the specification](https://www.w3.org/TR/css-ui-3/#outline-style) as "typically a style \[that] is either a user interface default for the platform, or perhaps a style that is richer than can be described in detail in CSS, e.g. a rounded edge outline with semi-translucent outer pixels that appears to glow". +The `auto` value indicates a custom outline style, described in [the specification](https://www.w3.org/TR/css-ui-3/#outline-style) as "typically a style \[that] is either a user interface default for the platform, or perhaps a style that is richer than can be described in detail in CSS, e.g., a rounded edge outline with semi-translucent outer pixels that appears to glow". #### HTML diff --git a/files/en-us/web/css/outline-width/index.md b/files/en-us/web/css/outline-width/index.md index 6ecc5a22e367636..4be1cd28ebf31fe 100644 --- a/files/en-us/web/css/outline-width/index.md +++ b/files/en-us/web/css/outline-width/index.md @@ -9,7 +9,40 @@ browser-compat: css.properties.outline-width The [CSS](/en-US/docs/Web/CSS) **`outline-width`** property sets the thickness of an element's outline. An outline is a line that is drawn around an element, outside the {{cssxref("border")}}. -{{EmbedInteractiveExample("pages/css/outline-width.html")}} +{{InteractiveExample("CSS Demo: outline-width")}} + +```css interactive-example-choice +outline-width: 12px; +``` + +```css interactive-example-choice +outline-width: thin; +``` + +```css interactive-example-choice +outline-width: medium; +``` + +```css interactive-example-choice +outline-width: thick; +``` + +```html interactive-example +<section class="default-example" id="default-example"> + <div class="transition-all" id="example-element"> + This is a box with an outline around it. + </div> +</section> +``` + +```css interactive-example +#example-element { + outline: 0.75em solid; + padding: 0.75em; + width: 80%; + height: 100px; +} +``` It is often more convenient to use the shorthand property {{cssxref("outline")}} when defining the appearance of an outline. diff --git a/files/en-us/web/css/outline/index.md b/files/en-us/web/css/outline/index.md index 1b58136d1f7e046..dea3fd7478c0466 100644 --- a/files/en-us/web/css/outline/index.md +++ b/files/en-us/web/css/outline/index.md @@ -9,7 +9,44 @@ browser-compat: css.properties.outline The **`outline`** [CSS](/en-US/docs/Web/CSS) [shorthand property](/en-US/docs/Web/CSS/CSS_cascade/Shorthand_properties) sets most of the outline properties in a single declaration. -{{EmbedInteractiveExample("pages/css/outline.html")}} +{{InteractiveExample("CSS Demo: outline")}} + +```css interactive-example-choice +outline: solid; +``` + +```css interactive-example-choice +outline: dashed red; +``` + +```css interactive-example-choice +outline: 1rem solid; +``` + +```css interactive-example-choice +outline: thick double #32a1ce; +``` + +```css interactive-example-choice +outline: 8px ridge rgba(170, 50, 220, 0.6); +border-radius: 2rem; +``` + +```html interactive-example +<section class="default-example" id="default-example"> + <div class="transition-all" id="example-element"> + This is a box with an outline around it. + </div> +</section> +``` + +```css interactive-example +#example-element { + padding: 0.75rem; + width: 80%; + height: 100px; +} +``` ## Constituent properties @@ -42,7 +79,7 @@ outline: revert-layer; outline: unset; ``` -The `outline` property may be specified using one, two, or three of the values listed below. The order of the values does not matter. As with all shorthand properties, any omitted sub-values will be set to their [initial value](/en-US/docs/Web/CSS/CSS_cascade/initial_value). +The `outline` property may be specified using one, two, or three of the values listed below. The order of the values does not matter. As with all shorthand properties, any omitted sub-values will be set to their [initial value](/en-US/docs/Web/CSS/CSS_cascade/Value_processing#initial_value). > [!NOTE] > The outline will be invisible for many elements if its style is not defined. This is because the style defaults to `none`. A notable exception is `input` elements, which are given default styling by browsers. diff --git a/files/en-us/web/css/overflow-anchor/guide_to_scroll_anchoring/index.md b/files/en-us/web/css/overflow-anchor/guide_to_scroll_anchoring/index.md deleted file mode 100644 index b9c70e59defa87d..000000000000000 --- a/files/en-us/web/css/overflow-anchor/guide_to_scroll_anchoring/index.md +++ /dev/null @@ -1,87 +0,0 @@ ---- -title: Guide to scroll anchoring -slug: Web/CSS/overflow-anchor/Guide_to_scroll_anchoring -page-type: guide -browser-compat: css.properties.overflow-anchor ---- - -{{CSSRef}} - -As a user of the web, you are probably familiar with the problem that scroll anchoring solves. You browse to a long page on a slow connection and begin to scroll to read the content; while you are busy reading, the part of the page you are looking at suddenly jumps. This has happened because large images or some other elements have just loaded further up in the content. - -Scroll anchoring is a browser feature that aims to solve this problem of content jumping, which happens if content loads in after the user has already scrolled to a new part of the document. - -## How does it work? - -Scroll anchoring adjusts the scroll position to compensate for the changes outside of the viewport. This means that the point in the document the user is looking at remains in the viewport, which may mean their scroll position actually changes in terms of how _far_ they have moved through the document. - -## How do I turn on scroll anchoring? - -You don't! The feature is enabled by default in supporting browsers. In most cases anchored scrolling is exactly what you want — content jumping is a poor experience for anyone. - -## What if I need to debug it? - -If your page is not behaving well with scroll anchoring enabled, it is probably because some `scroll` event listener is not handling well the extra scrolling to compensate for the anchor node movement. - -You can check whether disabling scroll anchoring fixes the issue in Firefox by changing `layout.css.scroll-anchoring.enabled` to `false` in `about:config`. - -If it does, you can check what node is Firefox using as the anchor using the `layout.css.scroll-anchoring.highlight` switch. That will show a purple overlay on top of the anchor node. - -If one node doesn't seem appropriate to be an anchor, you can exclude it using {{cssxref("overflow-anchor")}}, as described below. - -## What if I need to disable it? - -The specification provides a new property, {{cssxref("overflow-anchor")}}, which can be used to disable scroll anchoring on all or part of the document. It's essentially a way to opt out of the new behavior. - -The only possible values are `auto` or `none`: - -- `auto` is the initial value; as long as the user has a supported browser the scroll anchoring behavior will happen, and they should see fewer content jumps. -- `none` means that you have explicitly opted the document, or part of the document, out of scroll anchoring. - -To opt out the entire document, you can set it on the {{htmlelement("body")}} element: - -```css -body { - overflow-anchor: none; -} -``` - -To opt out a certain part of the document use `overflow-anchor: none` on its container element: - -```css -.container { - overflow-anchor: none; -} -``` - -> [!NOTE] -> The specification details that once scroll anchoring has been opted out of, you cannot opt back into it from a child element. For example, if you opt out for the entire document, you will not be able to set `overflow-anchor: auto` elsewhere in the document to turn it back on for a subsection. - -### Suppression triggers - -The specification also details some _suppression triggers_, which will disable scroll anchoring in places where it might be problematic. If any of the triggers happen on the anchor node, or an ancestor of it, anchoring is suppressed. - -These suppression triggers are changes to the computed value of any of the following properties: - -- {{cssxref("top")}}, {{cssxref("left")}}, {{cssxref("right")}}, or {{cssxref("bottom")}} -- {{cssxref("margin")}} or {{cssxref("padding")}} -- Any {{cssxref("width")}} or {{cssxref("height")}}-related properties -- {{cssxref("transform")}} and the individual transform properties {{cssxref("translate")}}, {{cssxref("scale")}}, and {{cssxref("rotate")}} - -Additionally, {{cssxref("position")}} changes anywhere inside the scrolling box also disable scroll anchoring. - -> [!NOTE] -> In [Firefox bug 1584285](https://bugzil.la/1584285) the `layout.css.scroll-anchoring.suppressions.enabled` flag was added to Firefox Nightly in order to allow the disabling of these triggers. - -## Further reading - -- [Explainer document on the WICG site](https://github.com/WICG/ScrollAnchoring/blob/master/explainer.md) -- [Scroll anchoring for web developers on the Chromium blog](https://blog.chromium.org/2017/04/scroll-anchoring-for-web-developers.html) - -## Browser compatibility - -{{Compat}} - -### Compatibility notes - -If you need to test whether scroll anchoring is available in a browser, use [Feature Queries](/en-US/docs/Web/CSS/@supports) to test support for the `overflow-anchor` property. diff --git a/files/en-us/web/css/overflow-anchor/index.md b/files/en-us/web/css/overflow-anchor/index.md index 61ecc2a448c1a59..3c707af7a5b7868 100644 --- a/files/en-us/web/css/overflow-anchor/index.md +++ b/files/en-us/web/css/overflow-anchor/index.md @@ -11,7 +11,97 @@ The **`overflow-anchor`** [CSS](/en-US/docs/Web/CSS) property provides a way to Scroll anchoring behavior is enabled by default in any browser that supports it. Therefore, changing the value of this property is typically only required if you are experiencing problems with scroll anchoring in a document or part of a document and need to turn the behavior off. -{{EmbedInteractiveExample("pages/css/overflow-anchor.html")}} +{{InteractiveExample("CSS Demo: overflow-anchor")}} + +```css interactive-example-choice +overflow-anchor: auto; +``` + +```css interactive-example-choice +overflow-anchor: none; +``` + +```html interactive-example +<section class="default-example" id="default-example"> + <div class="whole-content-wrapper"> + <button id="playback" type="button">Start lottery</button> + <p>Magic numbers for today are:</p> + <div id="example-element"></div> + </div> +</section> +``` + +```css interactive-example +.whole-content-wrapper { + display: flex; + flex-direction: column; + height: 100%; + width: 100%; +} + +#example-element { + height: 100%; + border: 2px dashed dodgerblue; + padding: 0.75em; + text-align: left; + overflow: scroll; +} + +#playback { + font-size: 1em; + width: 10em; + height: 4em; + font-weight: bold; + margin: 1em auto; + background-color: aliceblue; + border: solid 2px dodgerblue; + border-radius: 5px; +} + +#playback:hover { + border-color: lightseagreen; +} + +#playback:active { + filter: brightness(0.9); +} +``` + +```js interactive-example +window.addEventListener("load", () => { + const example = document.getElementById("example-element"); + const button = document.getElementById("playback"); + let intervalId; + + function setInitialState() { + example.innerHTML = ""; + Array.from({ length: 10 }, (_, i) => i).forEach(addContent); + example.scrollTop = example.scrollHeight; + } + + function addContent() { + console.log("adding content"); + const magicNumber = Math.floor(Math.random() * 10000); + example.insertAdjacentHTML( + "afterbegin", + `<div class="new-content-container">New Magic Number: ${magicNumber}</div>`, + ); + } + + button.addEventListener("click", () => { + if (example.classList.contains("running")) { + example.classList.remove("running"); + button.textContent = "Start lottery"; + clearInterval(intervalId); + } else { + example.classList.add("running"); + button.textContent = "Stop lottery"; + setInitialState(); + intervalId = setInterval(addContent, 1000); + } + }); +}); +``` ## Syntax @@ -65,4 +155,5 @@ To prevent scroll anchoring in a document, use the `overflow-anchor` property. ## See also -- [Guide to scroll anchoring](/en-US/docs/Web/CSS/overflow-anchor/Guide_to_scroll_anchoring) +- [Understanding scroll anchoring](/en-US/docs/Web/CSS/CSS_scroll_anchoring/Scroll_anchoring) +- [CSS scroll anchoring](/en-US/docs/Web/CSS/CSS_scroll_anchoring) module diff --git a/files/en-us/web/css/overflow-position/index.md b/files/en-us/web/css/overflow-position/index.md index a8202bb6872cbc0..09215ced42c2228 100644 --- a/files/en-us/web/css/overflow-position/index.md +++ b/files/en-us/web/css/overflow-position/index.md @@ -2,7 +2,7 @@ title: <overflow-position> slug: Web/CSS/overflow-position page-type: css-type -browser-compat: css.types.overflow-position +spec-urls: https://drafts.csswg.org/css-align/#typedef-overflow-position --- {{CSSRef}} @@ -33,10 +33,6 @@ The following keyword values are represented by the `<overflow-position>` gramma {{Specifications}} -## Browser compatibility - -{{Compat}} - ## See also - Properties that use this data type: {{cssxref("align-content")}}, {{cssxref("align-items")}}, {{cssxref("align-self")}}, {{cssxref("justify-content")}} {{cssxref("justify-items")}}, {{cssxref("justify-self")}}, {{cssxref("place-content")}}, {{cssxref("place-items")}}, and {{cssxref("place-self")}} diff --git a/files/en-us/web/css/overflow-wrap/index.md b/files/en-us/web/css/overflow-wrap/index.md index c8d80f041a6622f..555c8d03f4d462c 100644 --- a/files/en-us/web/css/overflow-wrap/index.md +++ b/files/en-us/web/css/overflow-wrap/index.md @@ -12,7 +12,42 @@ The **`overflow-wrap`** [CSS](/en-US/docs/Web/CSS) property applies to text, set > [!NOTE] > The property was originally a nonstandard and unprefixed Microsoft extension called `word-wrap`, and was implemented by most browsers with the same name. It has since been renamed to `overflow-wrap`, with `word-wrap` being an alias. -{{EmbedInteractiveExample("pages/css/overflow-wrap.html")}} +{{InteractiveExample("CSS Demo: overflow-wrap")}} + +```css interactive-example-choice +overflow-wrap: normal; +``` + +```css interactive-example-choice +overflow-wrap: anywhere; +``` + +```css interactive-example-choice +overflow-wrap: break-word; +``` + +```html interactive-example +<section class="default-example" id="default-example"> + <div class="example-container"> + Most words are short &amp; don't need to break. But + <strong class="transition-all" id="example-element" + >Antidisestablishmentarianism</strong + > + is long. The width is set to min-content, with a max-width of 11em. + </div> +</section> +``` + +```css interactive-example +.example-container { + background-color: rgba(255, 0, 200, 0.2); + border: 3px solid #663399; + padding: 0.75em; + width: min-content; + max-width: 11em; + height: 200px; +} +``` > [!NOTE] > In contrast to {{cssxref("word-break")}}, `overflow-wrap` will only create a break if an entire word cannot be placed on its own line without overflowing. diff --git a/files/en-us/web/css/overflow-x/index.md b/files/en-us/web/css/overflow-x/index.md index ee53b3d8fbb9d30..e960102b20691b5 100644 --- a/files/en-us/web/css/overflow-x/index.md +++ b/files/en-us/web/css/overflow-x/index.md @@ -9,7 +9,46 @@ browser-compat: css.properties.overflow-x The **`overflow-x`** [CSS](/en-US/docs/Web/CSS) property sets what shows when content overflows a block-level element's left and right edges. This may be nothing, a scroll bar, or the overflow content. This property may also be set by using the [`overflow`](/en-US/docs/Web/CSS/overflow) shorthand property. -{{EmbedInteractiveExample("pages/css/overflow-x.html")}} +{{InteractiveExample("CSS Demo: overflow-x")}} + +```css interactive-example-choice +overflow-x: visible; +``` + +```css interactive-example-choice +overflow-x: hidden; +``` + +```css interactive-example-choice +overflow-x: clip; +``` + +```css interactive-example-choice +overflow-x: scroll; +``` + +```css interactive-example-choice +overflow-x: auto; +``` + +```html interactive-example +<section class="default-example" id="default-example"> + <div id="example-element"> + The value of Pi is 3.1415926535897932384626433832795029. The value of e is + 2.7182818284590452353602874713526625. + </div> +</section> +``` + +```css interactive-example +#example-element { + width: 15em; + height: 9em; + border: medium dotted; + padding: 0.75em; + text-align: left; +} +``` ## Syntax diff --git a/files/en-us/web/css/overflow-y/index.md b/files/en-us/web/css/overflow-y/index.md index c5ee1d218c3b9a7..8ff6d67f431b26b 100644 --- a/files/en-us/web/css/overflow-y/index.md +++ b/files/en-us/web/css/overflow-y/index.md @@ -9,7 +9,47 @@ browser-compat: css.properties.overflow-y The **`overflow-y`** [CSS](/en-US/docs/Web/CSS) property sets what shows when content overflows a block-level element's top and bottom edges. This may be nothing, a scroll bar, or the overflow content. This property may also be set by using the [`overflow`](/en-US/docs/Web/CSS/overflow) shorthand property. -{{EmbedInteractiveExample("pages/css/overflow-y.html")}} +{{InteractiveExample("CSS Demo: overflow-y")}} + +```css interactive-example-choice +overflow-y: visible; +``` + +```css interactive-example-choice +overflow-y: hidden; +``` + +```css interactive-example-choice +overflow-y: clip; +``` + +```css interactive-example-choice +overflow-y: scroll; +``` + +```css interactive-example-choice +overflow-y: auto; +``` + +```html interactive-example +<section class="default-example" id="default-example"> + <p id="example-element"> + Michaelmas term lately over, and the Lord Chancellor sitting in Lincoln's + Inn Hall. Implacable November weather. As much mud in the streets as if the + waters had but newly retired from the face of the earth. + </p> +</section> +``` + +```css interactive-example +#example-element { + width: 15em; + height: 9em; + border: medium dotted; + padding: 0.75em; + text-align: left; +} +``` ## Syntax diff --git a/files/en-us/web/css/overflow/index.md b/files/en-us/web/css/overflow/index.md index 770ceea7b878c2a..2ff1168cb128890 100644 --- a/files/en-us/web/css/overflow/index.md +++ b/files/en-us/web/css/overflow/index.md @@ -9,7 +9,47 @@ browser-compat: css.properties.overflow The **`overflow`** [CSS](/en-US/docs/Web/CSS) [shorthand property](/en-US/docs/Web/CSS/CSS_cascade/Shorthand_properties) sets the desired behavior when content does not fit in the element's padding box (overflows) in the horizontal and/or vertical direction. -{{EmbedInteractiveExample("pages/css/overflow.html")}} +{{InteractiveExample("CSS Demo: overflow")}} + +```css interactive-example-choice +overflow: visible; +``` + +```css interactive-example-choice +overflow: hidden; +``` + +```css interactive-example-choice +overflow: clip; +``` + +```css interactive-example-choice +overflow: scroll; +``` + +```css interactive-example-choice +overflow: auto; +``` + +```html interactive-example +<section class="default-example" id="default-example"> + <p id="example-element"> + Michaelmas term lately over, and the Lord Chancellor sitting in Lincoln's + Inn Hall. Implacable November weather. As much mud in the streets as if the + waters had but newly retired from the face of the earth. + </p> +</section> +``` + +```css interactive-example +#example-element { + width: 15em; + height: 9em; + border: medium dotted; + padding: 0.75em; + text-align: left; +} +``` ## Constituent properties @@ -63,7 +103,7 @@ The following nuances should be kept in mind while using the various keywords fo - Specifying a value other than `visible` (the default) or `clip` for `overflow` creates a new [block formatting context](/en-US/docs/Web/CSS/CSS_display/Block_formatting_context). This is necessary for technical reasons; if a float intersects with a scrolling element, it would forcibly rewrap the content after each scroll step, leading to a slow scrolling experience. - For an `overflow` setting to create the desired effect, the block-level element must have either a set height ({{cssxref("height")}} or {{cssxref("max-height")}}) if the overflow is in the vertical direction, a set width ({{cssxref("width")}} or {{cssxref("max-width")}}) if the overflow is in the horizontal direction, a set block-size (({{cssxref("block-size")}} or {{cssxref("max-block-size")}}) if the overflow is in the block direction, or a set inline-size (({{cssxref("inline-size")}} or {{cssxref("max-inline-size")}}) or {{cssxref("white-space")}} set to `nowrap` if the overflow is in the inline direction. -- Setting overflow to `visible` in one direction (i.e. `overflow-x` or `overflow-y`) when it isn't set to `visible` or `clip` in the other direction results in the `visible` value behaving as `auto`. +- Setting overflow to `visible` in one direction (i.e., `overflow-x` or `overflow-y`) when it isn't set to `visible` or `clip` in the other direction results in the `visible` value behaving as `auto`. - Setting overflow to `clip` in one direction when it isn't set to `visible` or `clip` in the other direction results in the `clip` value behaving as `hidden`. - The JavaScript {{domxref("Element.scrollTop")}} property may be used to scroll through content in a scroll container, except when `overflow` is set to `clip`. @@ -79,7 +119,7 @@ The following nuances should be kept in mind while using the various keywords fo A scrolling content area cannot be scrolled by a keyboard-only user, with the exception of users on Firefox (which makes the container keyboard focusable by default). -As a developer, to allow non-Firefox keyboard-only users to scroll the container, you will need to give it a [`tabindex`](/en-US/docs/Web/HTML/Global_attributes/tabindex) using `tabindex="0"`. Unfortunately, when a screen reader encounters this tab-stop, they will have no context for what it is and their screen reader will likely announce the entirety of its contents. Giving it an appropriate [WAI-ARIA role](/en-US/docs/Web/Accessibility/ARIA/Roles) (`role="region"`, for example) and an accessible name (via [`aria-label`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-label) or [`aria-labelledby`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-labelledby)) can mitigate this. +As a developer, to allow non-Firefox keyboard-only users to scroll the container, you will need to give it a [`tabindex`](/en-US/docs/Web/HTML/Reference/Global_attributes/tabindex) using `tabindex="0"`. Unfortunately, when a screen reader encounters this tab-stop, they will have no context for what it is and their screen reader will likely announce the entirety of its contents. Giving it an appropriate [WAI-ARIA role](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles) (`role="region"`, for example) and an accessible name (via [`aria-label`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-label) or [`aria-labelledby`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-labelledby)) can mitigate this. ## Examples diff --git a/files/en-us/web/css/overlay/index.md b/files/en-us/web/css/overlay/index.md index 18eb09c9ff82d1b..9eaaadcac38903e 100644 --- a/files/en-us/web/css/overlay/index.md +++ b/files/en-us/web/css/overlay/index.md @@ -14,7 +14,7 @@ The **`overlay`** [CSS](/en-US/docs/Web/CSS) property specifies whether an eleme It is important to note that `overlay` can _only_ be set by the browser — author styles cannot change the `overlay` value of any element. You can, however, add `overlay` to the [list of transition properties](/en-US/docs/Web/CSS/transition-property) set on an element. This causes its removal from the top layer to be deferred so it can be animated instead of disappearing immediately. > [!NOTE] -> When transitioning `overlay`, you need to set [`transition-behavior: allow-discrete`](/en-US/docs/Web/CSS/transition-behavior) on the transition so that it will animate. `overlay` animations differ from normal [discrete animations](/en-US/docs/Web/CSS/CSS_animated_properties#discrete) in that the visible (i.e. `auto`) state will always be shown for the full duration of the transition, regardless of whether it is the start or end state. +> When transitioning `overlay`, you need to set [`transition-behavior: allow-discrete`](/en-US/docs/Web/CSS/transition-behavior) on the transition so that it will animate. `overlay` animations differ from normal [discrete animations](/en-US/docs/Web/CSS/CSS_animated_properties#discrete) in that the visible (i.e., `auto`) state will always be shown for the full duration of the transition, regardless of whether it is the start or end state. ## Syntax @@ -54,7 +54,7 @@ In this example, a [popover](/en-US/docs/Web/API/Popover_API) is animated as it #### HTML -The HTML contains a {{htmlelement("div")}} element declared as a popover using the [popover](/en-US/docs/Web/HTML/Global_attributes/popover) attribute, and a {{htmlelement("button")}} element designated as the popover's display control using its [popovertarget](/en-US/docs/Web/HTML/Element/button#popovertarget) attribute. +The HTML contains a {{htmlelement("div")}} element declared as a popover using the [popover](/en-US/docs/Web/HTML/Reference/Global_attributes/popover) attribute, and a {{htmlelement("button")}} element designated as the popover's display control using its [popovertarget](/en-US/docs/Web/HTML/Reference/Elements/button#popovertarget) attribute. ```html <button popovertarget="mypopover">Show the popover</button> @@ -129,7 +129,7 @@ html { The two properties we want to animate are [`opacity`](/en-US/docs/Web/CSS/opacity) and [`transform`](/en-US/docs/Web/CSS/transform)): we want the popover to fade in and out while growing and shrinking in the horizontal direction. We set a starting state for these properties on the default hidden state of the popover element (selected via `[popover]`), and an end state on the open state of the popover (selected via the [`:popover-open`](/en-US/docs/Web/CSS/:popover-open) pseudo-class). We then set a [`transition`](/en-US/docs/Web/CSS/transition) property to animate between the two. -Because the animated element is being promoted to the [top layer](/en-US/docs/Glossary/Top_layer) when shown and removed from the top layer when hidden, `overlay` is added to the list of transitioned elements. This ensures that the removal of the element from the top layer is deferred until the animation has ended. This doesn't make a huge difference for simple animations such as this one, but in more complex cases not doing this can result in the element being removed from the overlay too quickly, meaning the animation is not smooth or effective. Note that the [`transition-behavior: allow-discrete`](/en-US/docs/Web/CSS/transition-behavior) value is also set in the shorthand to enable discrete transitions. +Because the animated element is being promoted to the [top layer](/en-US/docs/Glossary/Top_layer) when shown and removed from the top layer when hidden, `overlay` is added to the list of transitioned elements. This ensures that the removal of the element from the top layer is deferred until the animation has ended. This doesn't make a huge difference for basic animations such as this one, but in more complex cases not doing this can result in the element being removed from the overlay too quickly, meaning the animation is not smooth or effective. Note that the [`transition-behavior: allow-discrete`](/en-US/docs/Web/CSS/transition-behavior) value is also set in the shorthand to enable discrete transitions. The following steps are also required to get the animation working in both directions: diff --git a/files/en-us/web/css/overscroll-behavior-x/index.md b/files/en-us/web/css/overscroll-behavior-x/index.md index 586fd9dc5601dd2..48ef438e0ab1407 100644 --- a/files/en-us/web/css/overscroll-behavior-x/index.md +++ b/files/en-us/web/css/overscroll-behavior-x/index.md @@ -50,7 +50,7 @@ The `overscroll-behavior-x` property is specified as a keyword chosen from the l ### Preventing an underlying element from scrolling horizontally -In our simple [overscroll-behavior-x example](https://mdn.github.io/css-examples/overscroll-behavior/overscroll-behavior-x) (see [source code](https://github.com/mdn/css-examples/blob/main/overscroll-behavior/overscroll-behavior-x.html) also), we have two block-level boxes, one inside the other. The outer box has a large {{cssxref("width")}} set on it so the page will scroll horizontally. The inner box has a small width (and {{cssxref("height")}}) set on it so it sits comfortably inside the viewport, but its content is given a large `width` so it will scroll horizontally. +In our [overscroll-behavior-x example](https://mdn.github.io/css-examples/overscroll-behavior/overscroll-behavior-x) (see [source code](https://github.com/mdn/css-examples/blob/main/overscroll-behavior/overscroll-behavior-x.html) also), we have two block-level boxes, one inside the other. The outer box has a large {{cssxref("width")}} set on it so the page will scroll horizontally. The inner box has a small width (and {{cssxref("height")}}) set on it so it sits comfortably inside the viewport, but its content is given a large `width` so it will scroll horizontally. By default, when the inner box is scrolled and a scroll boundary is reached, the whole page will begin to scroll, which is probably not what we want. To avoid this, you can set `overscroll-behavior-x: contain` on the inner box: diff --git a/files/en-us/web/css/overscroll-behavior/index.md b/files/en-us/web/css/overscroll-behavior/index.md index 6add63d61e30b5e..96250a41f1519cd 100644 --- a/files/en-us/web/css/overscroll-behavior/index.md +++ b/files/en-us/web/css/overscroll-behavior/index.md @@ -9,7 +9,78 @@ browser-compat: css.properties.overscroll-behavior The **`overscroll-behavior`** [CSS](/en-US/docs/Web/CSS) property sets what a browser does when reaching the boundary of a scrolling area. -{{EmbedInteractiveExample("pages/css/overscroll-behavior.html")}} +{{InteractiveExample("CSS Demo: overscroll-behavior")}} + +```css interactive-example-choice +overscroll-behavior: auto; +``` + +```css interactive-example-choice +overscroll-behavior: contain; +``` + +```css interactive-example-choice +overscroll-behavior: none; +``` + +```html interactive-example +<section class="default-example" id="default-example"> + <div class="example-container"> + <div class="box"> + This is a scrollable container. Michaelmas term lately over, and the Lord + Chancellor sitting in Lincoln's Inn Hall. Implacable November weather. As + much mud in the streets as if the waters had but newly retired from the + face of the earth. + <br /><br /> + Lorem Ipsum has been the industry's standard dummy text ever since the + 1500s, when an unknown printer took a galley of type and scrambled it to + make a type specimen book. It has survived not only five centuries, but + also the leap into electronic typesetting, remaining essentially + unchanged. + </div> + <div id="example-element"> + This is the inner container. Focus on this container, scroll to the bottom + and when you reach the bottom keep scrolling. + <p> + If you have + <code class="language-css">overscroll-behavior: auto;</code> selected + the outer container will start to scroll. + </p> + If you have + <code class="language-css">overscroll-behavior: contain;</code> selected, + the outer container will not scroll unless you move your cursor out of the + inner container and try to perform scroll on the outer container. + </div> + </div> +</section> +``` + +```css interactive-example +.example-container { + width: 35em; + height: 18em; + border: medium dotted; + padding: 0.75em; + text-align: left; + overflow: auto; + display: flex; +} + +.box { + width: 50%; +} + +#example-element { + width: 50%; + height: 12em; + border: medium dotted #1b76c4; + padding: 0.3em; + margin: 0 0.3em; + text-align: left; + overflow: auto; + overscroll-behavior: contain; +} +``` ## Constituent properties @@ -56,7 +127,7 @@ By default, mobile browsers tend to provide a "bounce" effect or even a page ref In some cases, these behaviors are not desirable. You can use `overscroll-behavior` to get rid of unwanted scroll chaining and the browser's Facebook/Twitter app-inspired "pull to refresh"-type behavior. -Note that this property applies only to {{Glossary("Scroll_container", "scroll containers")}}. In particular, since an [`<iframe>`](/en-US/docs/Web/HTML/Element/iframe) is not a scroll container, setting this property on an iframe has no effect. To control scroll chaining from an iframe, set `overscroll-behavior` on both the [`<html>`](/en-US/docs/Web/HTML/Element/html) and the [`<body>`](/en-US/docs/Web/HTML/Element/body) elements of the iframe's document. +Note that this property applies only to {{Glossary("Scroll_container", "scroll containers")}}. In particular, since an [`<iframe>`](/en-US/docs/Web/HTML/Reference/Elements/iframe) is not a scroll container, setting this property on an iframe has no effect. To control scroll chaining from an iframe, set `overscroll-behavior` on both the [`<html>`](/en-US/docs/Web/HTML/Reference/Elements/html) and the [`<body>`](/en-US/docs/Web/HTML/Reference/Elements/body) elements of the iframe's document. ## Formal definition @@ -84,7 +155,7 @@ Both of these areas scroll; normally if you scrolled the chat window until you h } ``` -We also wanted to get rid of the standard overscroll effects when the contacts are scrolled to the top or bottom (e.g. Chrome on Android refreshes the page when you scroll past the top boundary). This can be prevented by setting `overscroll-behavior: none` on the {{htmlelement("html")}} element: +We also wanted to get rid of the standard overscroll effects when the contacts are scrolled to the top or bottom (e.g., Chrome on Android refreshes the page when you scroll past the top boundary). This can be prevented by setting `overscroll-behavior: none` on the {{htmlelement("html")}} element: ```css html { @@ -104,4 +175,5 @@ html { ## See also - [CSS overscroll behavior](/en-US/docs/Web/CSS/CSS_overscroll_behavior) module +- [CSS scroll anchoring](/en-US/docs/Web/CSS/CSS_scroll_anchoring) module - [Take control of your scroll: customizing pull-to-refresh and overflow effects](https://developer.chrome.com/blog/overscroll-behavior) on developer.chrome.com (2017) diff --git a/files/en-us/web/css/padding-block-end/index.md b/files/en-us/web/css/padding-block-end/index.md index dfaac6fcfd311eb..5a5e491a3a74fd1 100644 --- a/files/en-us/web/css/padding-block-end/index.md +++ b/files/en-us/web/css/padding-block-end/index.md @@ -9,7 +9,51 @@ browser-compat: css.properties.padding-block-end The **`padding-block-end`** [CSS](/en-US/docs/Web/CSS) property defines the logical block end padding of an element, which maps to a physical padding depending on the element's writing mode, directionality, and text orientation. -{{EmbedInteractiveExample("pages/css/padding-block-end.html")}} +{{InteractiveExample("CSS Demo: padding-block-end")}} + +```css interactive-example-choice +padding-block-end: 20px; +writing-mode: horizontal-tb; +``` + +```css interactive-example-choice +padding-block-end: 20px; +writing-mode: vertical-rl; +``` + +```css interactive-example-choice +padding-block-end: 5em; +writing-mode: horizontal-tb; +``` + +```css interactive-example-choice +padding-block-end: 5em; +writing-mode: vertical-lr; +``` + +```html interactive-example +<section id="default-example"> + <div class="transition-all" id="example-element"> + <div class="box"> + Far out in the uncharted backwaters of the unfashionable end of the + western spiral arm of the Galaxy lies a small unregarded yellow sun. + </div> + </div> +</section> +``` + +```css interactive-example +#example-element { + border: 10px solid #ffc129; + overflow: hidden; + text-align: left; +} + +.box { + border: dashed 1px; + unicode-bidi: bidi-override; +} +``` ## Syntax diff --git a/files/en-us/web/css/padding-block-start/index.md b/files/en-us/web/css/padding-block-start/index.md index dfdc90352fd49e7..3f7a94f780ac45e 100644 --- a/files/en-us/web/css/padding-block-start/index.md +++ b/files/en-us/web/css/padding-block-start/index.md @@ -9,7 +9,51 @@ browser-compat: css.properties.padding-block-start The **`padding-block-start`** [CSS](/en-US/docs/Web/CSS) property defines the logical block start padding of an element, which maps to a physical padding depending on the element's writing mode, directionality, and text orientation. -{{EmbedInteractiveExample("pages/css/padding-block-start.html")}} +{{InteractiveExample("CSS Demo: padding-block-start")}} + +```css interactive-example-choice +padding-block-start: 20px; +writing-mode: horizontal-tb; +``` + +```css interactive-example-choice +padding-block-start: 20px; +writing-mode: vertical-rl; +``` + +```css interactive-example-choice +padding-block-start: 5em; +writing-mode: horizontal-tb; +``` + +```css interactive-example-choice +padding-block-start: 5em; +writing-mode: vertical-lr; +``` + +```html interactive-example +<section id="default-example"> + <div class="transition-all" id="example-element"> + <div class="box"> + Far out in the uncharted backwaters of the unfashionable end of the + western spiral arm of the Galaxy lies a small unregarded yellow sun. + </div> + </div> +</section> +``` + +```css interactive-example +#example-element { + border: 10px solid #ffc129; + overflow: hidden; + text-align: left; +} + +.box { + border: dashed 1px; + unicode-bidi: bidi-override; +} +``` ## Syntax diff --git a/files/en-us/web/css/padding-block/index.md b/files/en-us/web/css/padding-block/index.md index d01a0280967015e..394d1a249ebc35d 100644 --- a/files/en-us/web/css/padding-block/index.md +++ b/files/en-us/web/css/padding-block/index.md @@ -9,7 +9,51 @@ browser-compat: css.properties.padding-block The **`padding-block`** [CSS](/en-US/docs/Web/CSS) [shorthand property](/en-US/docs/Web/CSS/CSS_cascade/Shorthand_properties) defines the logical block start and end padding of an element, which maps to physical padding properties depending on the element's writing mode, directionality, and text orientation. -{{EmbedInteractiveExample("pages/css/padding-block.html")}} +{{InteractiveExample("CSS Demo: padding-block")}} + +```css interactive-example-choice +padding-block: 10px 20px; +writing-mode: horizontal-tb; +``` + +```css interactive-example-choice +padding-block: 20px 40px; +writing-mode: vertical-rl; +``` + +```css interactive-example-choice +padding-block: 5% 10%; +writing-mode: horizontal-tb; +``` + +```css interactive-example-choice +padding-block: 2em 4em; +writing-mode: vertical-lr; +``` + +```html interactive-example +<section id="default-example"> + <div class="transition-all" id="example-element"> + <div class="box"> + Far out in the uncharted backwaters of the unfashionable end of the + western spiral arm of the Galaxy lies a small unregarded yellow sun. + </div> + </div> +</section> +``` + +```css interactive-example +#example-element { + border: 10px solid #ffc129; + overflow: hidden; + text-align: left; +} + +.box { + border: dashed 1px; + unicode-bidi: bidi-override; +} +``` ## Constituent properties diff --git a/files/en-us/web/css/padding-bottom/index.md b/files/en-us/web/css/padding-bottom/index.md index b37fa5b995beb91..fd550bd0f035edb 100644 --- a/files/en-us/web/css/padding-bottom/index.md +++ b/files/en-us/web/css/padding-bottom/index.md @@ -9,7 +9,50 @@ browser-compat: css.properties.padding-bottom The **`padding-bottom`** [CSS](/en-US/docs/Web/CSS) property sets the height of the [padding area](/en-US/docs/Web/CSS/CSS_box_model/Introduction_to_the_CSS_box_model#padding_area) on the bottom of an element. -{{EmbedInteractiveExample("pages/css/padding-bottom.html")}} +{{InteractiveExample("CSS Demo: padding-bottom")}} + +```css interactive-example-choice +padding-bottom: 1em; +``` + +```css interactive-example-choice +padding-bottom: 10%; +``` + +```css interactive-example-choice +padding-bottom: 20px; +``` + +```css interactive-example-choice +padding-bottom: 1ch; +``` + +```css interactive-example-choice +padding-bottom: 0; +``` + +```html interactive-example +<section id="default-example"> + <div class="transition-all" id="example-element"> + <div class="box"> + Far out in the uncharted backwaters of the unfashionable end of the + western spiral arm of the Galaxy lies a small unregarded yellow sun. + </div> + </div> +</section> +``` + +```css interactive-example +#example-element { + border: 10px solid #ffc129; + overflow: hidden; + text-align: left; +} + +.box { + border: dashed 1px; +} +``` An element's padding area is the space between its content and its border. diff --git a/files/en-us/web/css/padding-inline-end/index.md b/files/en-us/web/css/padding-inline-end/index.md index ac0c0d1b628b9b9..752559b490fef18 100644 --- a/files/en-us/web/css/padding-inline-end/index.md +++ b/files/en-us/web/css/padding-inline-end/index.md @@ -9,7 +9,47 @@ browser-compat: css.properties.padding-inline-end The **`padding-inline-end`** [CSS](/en-US/docs/Web/CSS) property defines the logical inline end padding of an element, which maps to a physical padding depending on the element's writing mode, directionality, and text orientation. -{{EmbedInteractiveExample("pages/css/padding-inline-end.html")}} +{{InteractiveExample("CSS Demo: padding-inline-end")}} + +```css interactive-example-choice +padding-inline-end: 20px; +writing-mode: horizontal-tb; +``` + +```css interactive-example-choice +padding-inline-end: 20px; +writing-mode: vertical-rl; +``` + +```css interactive-example-choice +padding-inline-end: 5em; +writing-mode: horizontal-tb; +direction: rtl; +``` + +```html interactive-example +<section id="default-example"> + <div class="transition-all" id="example-element"> + <div class="box"> + Far out in the uncharted backwaters of the unfashionable end of the + western spiral arm of the Galaxy lies a small unregarded yellow sun. + </div> + </div> +</section> +``` + +```css interactive-example +#example-element { + border: 10px solid #ffc129; + overflow: hidden; + text-align: left; +} + +.box { + border: dashed 1px; + unicode-bidi: bidi-override; +} +``` ## Syntax diff --git a/files/en-us/web/css/padding-inline-start/index.md b/files/en-us/web/css/padding-inline-start/index.md index 1dfa8a885edaa31..a12de9c48405db2 100644 --- a/files/en-us/web/css/padding-inline-start/index.md +++ b/files/en-us/web/css/padding-inline-start/index.md @@ -9,7 +9,47 @@ browser-compat: css.properties.padding-inline-start The **`padding-inline-start`** [CSS](/en-US/docs/Web/CSS) property defines the logical inline start padding of an element, which maps to a physical padding depending on the element's writing mode, directionality, and text orientation. -{{EmbedInteractiveExample("pages/css/padding-inline-start.html")}} +{{InteractiveExample("CSS Demo: padding-inline-start")}} + +```css interactive-example-choice +padding-inline-start: 20px; +writing-mode: horizontal-tb; +``` + +```css interactive-example-choice +padding-inline-start: 20px; +writing-mode: vertical-rl; +``` + +```css interactive-example-choice +padding-inline-start: 5em; +writing-mode: horizontal-tb; +direction: rtl; +``` + +```html interactive-example +<section id="default-example"> + <div class="transition-all" id="example-element"> + <div class="box"> + Far out in the uncharted backwaters of the unfashionable end of the + western spiral arm of the Galaxy lies a small unregarded yellow sun. + </div> + </div> +</section> +``` + +```css interactive-example +#example-element { + border: 10px solid #ffc129; + overflow: hidden; + text-align: left; +} + +.box { + border: dashed 1px; + unicode-bidi: bidi-override; +} +``` ## Syntax diff --git a/files/en-us/web/css/padding-inline/index.md b/files/en-us/web/css/padding-inline/index.md index 6a8f1c4c92aa6e0..9bc3f349cfad8bf 100644 --- a/files/en-us/web/css/padding-inline/index.md +++ b/files/en-us/web/css/padding-inline/index.md @@ -9,7 +9,47 @@ browser-compat: css.properties.padding-inline The **`padding-inline`** [CSS](/en-US/docs/Web/CSS) [shorthand property](/en-US/docs/Web/CSS/CSS_cascade/Shorthand_properties) defines the logical inline start and end padding of an element, which maps to physical padding properties depending on the element's writing mode, directionality, and text orientation. -{{EmbedInteractiveExample("pages/css/padding-inline.html")}} +{{InteractiveExample("CSS Demo: padding-inline")}} + +```css interactive-example-choice +padding-inline: 5% 10%; +writing-mode: horizontal-tb; +``` + +```css interactive-example-choice +padding-inline: 15px 40px; +writing-mode: vertical-rl; +``` + +```css interactive-example-choice +padding-inline: 5% 20%; +writing-mode: horizontal-tb; +direction: rtl; +``` + +```html interactive-example +<section id="default-example"> + <div class="transition-all" id="example-element"> + <div class="box"> + Far out in the uncharted backwaters of the unfashionable end of the + western spiral arm of the Galaxy lies a small unregarded yellow sun. + </div> + </div> +</section> +``` + +```css interactive-example +#example-element { + border: 10px solid #ffc129; + overflow: hidden; + text-align: left; +} + +.box { + border: dashed 1px; + unicode-bidi: bidi-override; +} +``` ## Constituent properties diff --git a/files/en-us/web/css/padding-left/index.md b/files/en-us/web/css/padding-left/index.md index a73a48322db19a8..b20a723deab8671 100644 --- a/files/en-us/web/css/padding-left/index.md +++ b/files/en-us/web/css/padding-left/index.md @@ -9,7 +9,50 @@ browser-compat: css.properties.padding-left The **`padding-left`** [CSS](/en-US/docs/Web/CSS) property sets the width of the [padding area](/en-US/docs/Web/CSS/CSS_box_model/Introduction_to_the_CSS_box_model#padding_area) to the left of an element. -{{EmbedInteractiveExample("pages/css/padding-left.html")}} +{{InteractiveExample("CSS Demo: padding-left")}} + +```css interactive-example-choice +padding-left: 1.5em; +``` + +```css interactive-example-choice +padding-left: 10%; +``` + +```css interactive-example-choice +padding-left: 20px; +``` + +```css interactive-example-choice +padding-left: 1ch; +``` + +```css interactive-example-choice +padding-left: 0; +``` + +```html interactive-example +<section id="default-example"> + <div class="transition-all" id="example-element"> + <div class="box"> + Far out in the uncharted backwaters of the unfashionable end of the + western spiral arm of the Galaxy lies a small unregarded yellow sun. + </div> + </div> +</section> +``` + +```css interactive-example +#example-element { + border: 10px solid #ffc129; + overflow: hidden; + text-align: left; +} + +.box { + border: dashed 1px; +} +``` An element's padding area is the space between its content and its border. diff --git a/files/en-us/web/css/padding-right/index.md b/files/en-us/web/css/padding-right/index.md index ce34fe6684aa4ba..447e0b84988d9eb 100644 --- a/files/en-us/web/css/padding-right/index.md +++ b/files/en-us/web/css/padding-right/index.md @@ -9,7 +9,50 @@ browser-compat: css.properties.padding-right The **`padding-right`** [CSS](/en-US/docs/Web/CSS) property sets the width of the [padding area](/en-US/docs/Web/CSS/CSS_box_model/Introduction_to_the_CSS_box_model#padding_area) on the right of an element. -{{EmbedInteractiveExample("pages/css/padding-right.html")}} +{{InteractiveExample("CSS Demo: padding-right")}} + +```css interactive-example-choice +padding-right: 1.5em; +``` + +```css interactive-example-choice +padding-right: 10%; +``` + +```css interactive-example-choice +padding-right: 20px; +``` + +```css interactive-example-choice +padding-right: 1ch; +``` + +```css interactive-example-choice +padding-right: 0; +``` + +```html interactive-example +<section id="default-example"> + <div class="transition-all" id="example-element"> + <div class="box"> + Far out in the uncharted backwaters of the unfashionable end of the + western spiral arm of the Galaxy lies a small unregarded yellow sun. + </div> + </div> +</section> +``` + +```css interactive-example +#example-element { + border: 10px solid #ffc129; + overflow: hidden; + text-align: left; +} + +.box { + border: dashed 1px; +} +``` An element's padding area is the space between its content and its border. diff --git a/files/en-us/web/css/padding-top/index.md b/files/en-us/web/css/padding-top/index.md index 887a094cb004a77..ae252b16d9ffcdd 100644 --- a/files/en-us/web/css/padding-top/index.md +++ b/files/en-us/web/css/padding-top/index.md @@ -9,7 +9,50 @@ browser-compat: css.properties.padding-top The **`padding-top`** [CSS](/en-US/docs/Web/CSS) property sets the height of the [padding area](/en-US/docs/Web/CSS/CSS_box_model/Introduction_to_the_CSS_box_model#padding_area) on the top of an element. -{{EmbedInteractiveExample("pages/css/padding-top.html")}} +{{InteractiveExample("CSS Demo: padding-top")}} + +```css interactive-example-choice +padding-top: 1em; +``` + +```css interactive-example-choice +padding-top: 10%; +``` + +```css interactive-example-choice +padding-top: 20px; +``` + +```css interactive-example-choice +padding-top: 1ch; +``` + +```css interactive-example-choice +padding-top: 0; +``` + +```html interactive-example +<section id="default-example"> + <div class="transition-all" id="example-element"> + <div class="box"> + Far out in the uncharted backwaters of the unfashionable end of the + western spiral arm of the Galaxy lies a small unregarded yellow sun. + </div> + </div> +</section> +``` + +```css interactive-example +#example-element { + border: 10px solid #ffc129; + overflow: hidden; + text-align: left; +} + +.box { + border: dashed 1px; +} +``` An element's padding area is the space between its content and its border. diff --git a/files/en-us/web/css/padding/index.md b/files/en-us/web/css/padding/index.md index 91669ff356d3471..595e78fa67a936b 100644 --- a/files/en-us/web/css/padding/index.md +++ b/files/en-us/web/css/padding/index.md @@ -9,7 +9,50 @@ browser-compat: css.properties.padding The **`padding`** [CSS](/en-US/docs/Web/CSS) [shorthand property](/en-US/docs/Web/CSS/CSS_cascade/Shorthand_properties) sets the [padding area](/en-US/docs/Web/CSS/CSS_box_model/Introduction_to_the_CSS_box_model#padding_area) on all four sides of an element at once. -{{EmbedInteractiveExample("pages/css/padding.html")}} +{{InteractiveExample("CSS Demo: padding")}} + +```css interactive-example-choice +padding: 1em; +``` + +```css interactive-example-choice +padding: 10% 0; +``` + +```css interactive-example-choice +padding: 10px 50px 20px; +``` + +```css interactive-example-choice +padding: 10px 50px 30px 0; +``` + +```css interactive-example-choice +padding: 0; +``` + +```html interactive-example +<section id="default-example"> + <div class="transition-all" id="example-element"> + <div class="box"> + Far out in the uncharted backwaters of the unfashionable end of the + western spiral arm of the Galaxy lies a small unregarded yellow sun. + </div> + </div> +</section> +``` + +```css interactive-example +#example-element { + border: 10px solid #ffc129; + overflow: hidden; + text-align: left; +} + +.box { + border: dashed 1px; +} +``` An element's padding area is the space between its content and its border. diff --git a/files/en-us/web/css/page-break-after/index.md b/files/en-us/web/css/page-break-after/index.md index e72be9c52da2dc4..19f7fb11abc209e 100644 --- a/files/en-us/web/css/page-break-after/index.md +++ b/files/en-us/web/css/page-break-after/index.md @@ -14,7 +14,80 @@ browser-compat: css.properties.page-break-after The **`page-break-after`** [CSS](/en-US/docs/Web/CSS) property adjusts page breaks _after_ the current element. -{{EmbedInteractiveExample("pages/css/page-break-after.html")}} +{{InteractiveExample("CSS Demo: page-break-after")}} + +```css interactive-example-choice +page-break-after: auto; +``` + +```css interactive-example-choice +page-break-after: always; +``` + +```html interactive-example +<section id="default-example"> + <div> + <p> + The effect of this property can be noticed when the document is being + printed or a preview of a print is displayed. + </p> + <button id="print-btn">Show Print Preview</button> + <div class="box-container"> + <div class="box">Content before the property</div> + <div class="box" id="example-element"> + Content with 'page-break-after' + </div> + <div class="box">Content after the property</div> + </div> + </div> +</section> +``` + +```css interactive-example +.box { + border: solid #5b6dcd 5px; + background-color: #5b6dcd; + margin: 10px 0; + padding: 5px; +} + +#example-element { + border: solid 5px #ffc129; + background-color: #ffc129; + color: black; +} + +.hide-element { + display: none; +} +``` + +```js interactive-example +const btn = document.getElementById("print-btn"); +const editorContainer = document.getElementsByClassName( + "css-editor-container", +)[0]; +const exampleHTMLElement = document.getElementById("default-example"); + +const printableSection = document.createElement("div"); +printableSection.setAttribute("id", "printable-section"); +printableSection.classList.add("hide-element"); +document.body.appendChild(printableSection); + +btn.addEventListener("click", () => { + const exampleContent = exampleHTMLElement.innerHTML; + + editorContainer.classList.add("hide-element"); + printableSection.innerHTML = exampleContent; + printableSection.classList.remove("hide-element"); + + window.print(); + + printableSection.classList.add("hide-element"); + printableSection.innerHTML = ""; + editorContainer.classList.remove("hide-element"); +}); +``` ## Syntax diff --git a/files/en-us/web/css/page-break-before/index.md b/files/en-us/web/css/page-break-before/index.md index 5716d4935db35db..1c4e88d841a8ea7 100644 --- a/files/en-us/web/css/page-break-before/index.md +++ b/files/en-us/web/css/page-break-before/index.md @@ -16,7 +16,80 @@ The **`page-break-before`** [CSS](/en-US/docs/Web/CSS) property adjusts page bre This property applies to block elements that generate a box. It won't apply on an empty {{ HTMLElement("div") }} that won't generate a box. -{{EmbedInteractiveExample("pages/css/page-break-before.html")}} +{{InteractiveExample("CSS Demo: page-break-before")}} + +```css interactive-example-choice +page-break-before: auto; +``` + +```css interactive-example-choice +page-break-before: always; +``` + +```html interactive-example +<section id="default-example"> + <div> + <p> + The effect of this property can be noticed when the document is being + printed or a preview of a print is displayed. + </p> + <button id="print-btn">Show Print Preview</button> + <div class="box-container"> + <div class="box">Content before the property</div> + <div class="box" id="example-element"> + Content with 'page-break-before' + </div> + <div class="box">Content after the property</div> + </div> + </div> +</section> +``` + +```css interactive-example +.box { + border: solid #5b6dcd 5px; + background-color: #5b6dcd; + margin: 10px 0; + padding: 5px; +} + +#example-element { + border: solid 5px #ffc129; + background-color: #ffc129; + color: black; +} + +.hide-element { + display: none; +} +``` + +```js interactive-example +const btn = document.getElementById("print-btn"); +const editorContainer = document.getElementsByClassName( + "css-editor-container", +)[0]; +const exampleHTMLElement = document.getElementById("default-example"); + +const printableSection = document.createElement("div"); +printableSection.setAttribute("id", "printable-section"); +printableSection.classList.add("hide-element"); +document.body.appendChild(printableSection); + +btn.addEventListener("click", () => { + const exampleContent = exampleHTMLElement.innerHTML; + + editorContainer.classList.add("hide-element"); + printableSection.innerHTML = exampleContent; + printableSection.classList.remove("hide-element"); + + window.print(); + + printableSection.classList.add("hide-element"); + printableSection.innerHTML = ""; + editorContainer.classList.remove("hide-element"); +}); +``` ## Syntax diff --git a/files/en-us/web/css/page-break-inside/index.md b/files/en-us/web/css/page-break-inside/index.md index 6902d91ce923ef8..cd20fde222abf4e 100644 --- a/files/en-us/web/css/page-break-inside/index.md +++ b/files/en-us/web/css/page-break-inside/index.md @@ -14,7 +14,86 @@ browser-compat: css.properties.page-break-inside The **`page-break-inside`** [CSS](/en-US/docs/Web/CSS) property adjusts page breaks _inside_ the current element. -{{EmbedInteractiveExample("pages/css/page-break-inside.html")}} +{{InteractiveExample("CSS Demo: page-break-inside")}} + +```css interactive-example-choice +page-break-inside: auto; +``` + +```css interactive-example-choice +page-break-inside: avoid; +``` + +```html interactive-example +<section id="default-example"> + <div> + <p> + The effect of this property can be noticed when the document is being + printed or a preview of a print is displayed. + </p> + <button id="print-btn">Show Print Preview</button> + <div class="box-container"> + <div class="box">Content before the property</div> + <div class="box" id="example-element"> + Content with 'page-break-inside' + </div> + <div class="box">Content after the property</div> + </div> + </div> +</section> +``` + +```css interactive-example +.box { + border: solid #5b6dcd 5px; + background-color: #5b6dcd; + margin: 10px 0; + padding: 5px; +} + +#example-element { + border: solid 5px #ffc129; + background-color: #ffc129; + color: black; +} + +.hide-element { + display: none; +} + +@media print { + #example-element { + height: 25cm; + } +} +``` + +```js interactive-example +const btn = document.getElementById("print-btn"); +const editorContainer = document.getElementsByClassName( + "css-editor-container", +)[0]; +const exampleHTMLElement = document.getElementById("default-example"); + +const printableSection = document.createElement("div"); +printableSection.setAttribute("id", "printable-section"); +printableSection.classList.add("hide-element"); +document.body.appendChild(printableSection); + +btn.addEventListener("click", () => { + const exampleContent = exampleHTMLElement.innerHTML; + + editorContainer.classList.add("hide-element"); + printableSection.innerHTML = exampleContent; + printableSection.classList.remove("hide-element"); + + window.print(); + + printableSection.classList.add("hide-element"); + printableSection.innerHTML = ""; + editorContainer.classList.remove("hide-element"); +}); +``` ## Syntax diff --git a/files/en-us/web/css/page/index.md b/files/en-us/web/css/page/index.md index 742b623b6ef4aff..0e10740c31592a7 100644 --- a/files/en-us/web/css/page/index.md +++ b/files/en-us/web/css/page/index.md @@ -59,11 +59,11 @@ The print controls allow the user to select how the `section`s in the `article` <input type="radio" id="single" name="type" value="single" checked /> No Pages </label> - <label for="double"> + <label for="grouped"> <input type="radio" id="grouped" name="type" value="grouped" />Pages with Grouped Chapters </label> - <label for="double"> + <label for="paged"> <input type="radio" id="paged" name="type" value="paged" /> Chapters Paged </label> diff --git a/files/en-us/web/css/paint-order/index.md b/files/en-us/web/css/paint-order/index.md index 3dfd0ba7f524218..0f6ab9384f3c25f 100644 --- a/files/en-us/web/css/paint-order/index.md +++ b/files/en-us/web/css/paint-order/index.md @@ -36,7 +36,7 @@ If no value is specified, the default paint order is `fill`, `stroke`, `markers` When one value is specified, that one is painted first, followed by the other two in their default order relative to one another. When two values are specified, they will be painted in the order they are specified in, followed by the unspecified one. > [!NOTE] -> In the case of this property, markers are only appropriate when drawing SVG shapes involving the use of the `marker-*` properties (e.g. [`marker-start`](/en-US/docs/Web/SVG/Attribute/marker-start)) and [`<marker>`](/en-US/docs/Web/SVG/Element/marker) element. They do not apply to HTML text, so in that case, you can only determine the order of `stroke` and `fill`. +> In the case of this property, markers are only appropriate when drawing SVG shapes involving the use of the `marker-*` properties (e.g., [`marker-start`](/en-US/docs/Web/SVG/Reference/Attribute/marker-start)) and [`<marker>`](/en-US/docs/Web/SVG/Reference/Element/marker) element. They do not apply to HTML text, so in that case, you can only determine the order of `stroke` and `fill`. ### Values diff --git a/files/en-us/web/css/percentage/index.md b/files/en-us/web/css/percentage/index.md index a1e92a0367dd667..ad34c867719712b 100644 --- a/files/en-us/web/css/percentage/index.md +++ b/files/en-us/web/css/percentage/index.md @@ -25,31 +25,55 @@ When animated, values of the `<percentage>` data type are {{Glossary("interpolat ### Width and margin-left ```html -<div style="background-color:navy;"> - <div style="width:50%; margin-left:20%; background-color:chartreuse;"> - Width: 50%, Left margin: 20% - </div> - <div style="width:30%; margin-left:60%; background-color:pink;"> - Width: 30%, Left margin: 60% - </div> +<div class="container"> + <div class="box1">Width: 50%, Left margin: 20%</div> + <div class="box2">Width: 30%, Left margin: 60%</div> </div> ``` -The above HTML will output: +```css +.container { + background-color: navy; +} + +.box1 { + width: 50%; + margin-left: 20%; + background-color: chartreuse; +} + +.box2 { + width: 30%; + margin-left: 60%; + background-color: pink; +} +``` {{EmbedLiveSample('Width_and_margin-left', '600', 140)}} ### Font-size ```html -<div style="font-size:18px;"> +<div class="container"> <p>Full-size text (18px)</p> - <p><span style="font-size:50%;">50% (9px)</span></p> - <p><span style="font-size:200%;">200% (36px)</span></p> + <p><span class="half">50% (9px)</span></p> + <p><span class="double">200% (36px)</span></p> </div> ``` -The above HTML will output: +```css +.container { + font-size: 18px; +} + +.half { + font-size: 50%; +} + +.double { + font-size: 200%; +} +``` {{EmbedLiveSample('Font-size', 'auto', 160)}} diff --git a/files/en-us/web/css/perspective-origin/index.md b/files/en-us/web/css/perspective-origin/index.md index 3167488ad91d698..456ce46c7ff43ca 100644 --- a/files/en-us/web/css/perspective-origin/index.md +++ b/files/en-us/web/css/perspective-origin/index.md @@ -9,7 +9,96 @@ browser-compat: css.properties.perspective-origin The **`perspective-origin`** [CSS](/en-US/docs/Web/CSS) property determines the position at which the viewer is looking. It is used as the _vanishing point_ by the {{cssxref("perspective")}} property. -{{EmbedInteractiveExample("pages/css/perspective-origin.html")}} +{{InteractiveExample("CSS Demo: perspective-origin")}} + +```css interactive-example-choice +perspective-origin: center; +``` + +```css interactive-example-choice +perspective-origin: top; +``` + +```css interactive-example-choice +perspective-origin: bottom right; +``` + +```css interactive-example-choice +perspective-origin: -170%; +``` + +```css interactive-example-choice +perspective-origin: 500% 200%; +``` + +```html interactive-example +<section class="default-example" id="default-example"> + <div class="transition-all" id="example-element"> + <div class="face front">1</div> + <div class="face back">2</div> + <div class="face right">3</div> + <div class="face left">4</div> + <div class="face top">5</div> + <div class="face bottom">6</div> + </div> +</section> +``` + +```css interactive-example +#default-example { + background: linear-gradient(skyblue, khaki); + perspective: 550px; +} + +#example-element { + width: 100px; + height: 100px; + transform-style: preserve-3d; + perspective: 250px; +} + +.face { + display: flex; + align-items: center; + justify-content: center; + width: 100%; + height: 100%; + position: absolute; + backface-visibility: inherit; + font-size: 60px; + color: white; +} + +.front { + background: rgba(90, 90, 90, 0.7); + transform: translateZ(50px); +} + +.back { + background: rgba(0, 210, 0, 0.7); + transform: rotateY(180deg) translateZ(50px); +} + +.right { + background: rgba(210, 0, 0, 0.7); + transform: rotateY(90deg) translateZ(50px); +} + +.left { + background: rgba(0, 0, 210, 0.7); + transform: rotateY(-90deg) translateZ(50px); +} + +.top { + background: rgba(210, 210, 0, 0.7); + transform: rotateX(90deg) translateZ(50px); +} + +.bottom { + background: rgba(210, 0, 210, 0.7); + transform: rotateX(-90deg) translateZ(50px); +} +``` The **`perspective-origin`** and {{cssxref('perspective')}} properties are attached to the parent of a child transformed in 3-dimensional space, unlike the [`perspective()`](/en-US/docs/Web/CSS/transform-function/perspective) transform function which is placed on the element being transformed. diff --git a/files/en-us/web/css/perspective/index.md b/files/en-us/web/css/perspective/index.md index 4533ca741c98393..74f10c2acd2f999 100644 --- a/files/en-us/web/css/perspective/index.md +++ b/files/en-us/web/css/perspective/index.md @@ -9,7 +9,93 @@ browser-compat: css.properties.perspective The **`perspective`** [CSS](/en-US/docs/Web/CSS) property determines the distance between the z=0 plane and the user in order to give a 3D-positioned element some perspective. -{{EmbedInteractiveExample("pages/css/perspective.html")}} +{{InteractiveExample("CSS Demo: perspective")}} + +```css interactive-example-choice +perspective: none; +``` + +```css interactive-example-choice +perspective: 800px; +``` + +```css interactive-example-choice +perspective: 23rem; +``` + +```css interactive-example-choice +perspective: 5.5cm; +``` + +```html interactive-example +<section class="default-example" id="default-example"> + <div class="transition-all" id="example-element"> + <div class="face front">1</div> + <div class="face back">2</div> + <div class="face right">3</div> + <div class="face left">4</div> + <div class="face top">5</div> + <div class="face bottom">6</div> + </div> +</section> +``` + +```css interactive-example +#default-example { + background: linear-gradient(skyblue, khaki); + perspective: 800px; + perspective-origin: 150% 150%; +} + +#example-element { + width: 100px; + height: 100px; + perspective: 550px; + transform-style: preserve-3d; +} + +.face { + display: flex; + align-items: center; + justify-content: center; + width: 100%; + height: 100%; + position: absolute; + backface-visibility: inherit; + font-size: 60px; + color: white; +} + +.front { + background: rgba(90, 90, 90, 0.7); + transform: translateZ(50px); +} + +.back { + background: rgba(0, 210, 0, 0.7); + transform: rotateY(180deg) translateZ(50px); +} + +.right { + background: rgba(210, 0, 0, 0.7); + transform: rotateY(90deg) translateZ(50px); +} + +.left { + background: rgba(0, 0, 210, 0.7); + transform: rotateY(-90deg) translateZ(50px); +} + +.top { + background: rgba(210, 210, 0, 0.7); + transform: rotateX(90deg) translateZ(50px); +} + +.bottom { + background: rgba(210, 0, 210, 0.7); + transform: rotateX(-90deg) translateZ(50px); +} +``` ## Syntax @@ -42,11 +128,11 @@ Each 3D element with z>0 becomes larger; each 3D-element with z<0 becomes smalle Large values of `perspective` cause a small transformation; small values of `perspective` cause a large transformation. -The parts of the 3D elements that are behind the user — i.e. their z-axis coordinates are greater than the value of the `perspective` CSS property — are not drawn. +The parts of the 3D elements that are behind the user — i.e., their z-axis coordinates are greater than the value of the `perspective` CSS property — are not drawn. The _vanishing point_ is by default placed at the center of the element, but its position can be changed using the {{cssxref("perspective-origin")}} property. -Using this property with a value other than `none` creates a new [stacking context](/en-US/docs/Web/CSS/CSS_positioned_layout/Understanding_z-index/Stacking_context). Also, in that case, the object will act as a containing block for `position: fixed` elements that it contains. +Using this property with a value other than `none` creates a new [stacking context](/en-US/docs/Web/CSS/CSS_positioned_layout/Stacking_context). Also, in that case, the object will act as a containing block for `position: fixed` elements that it contains. ## Formal definition diff --git a/files/en-us/web/css/place-content/index.md b/files/en-us/web/css/place-content/index.md index 016528a172fcbaf..0931bdbd859757d 100644 --- a/files/en-us/web/css/place-content/index.md +++ b/files/en-us/web/css/place-content/index.md @@ -7,9 +7,57 @@ browser-compat: css.properties.place-content {{CSSRef}} -The **`place-content`** [CSS](/en-US/docs/Web/CSS) [shorthand property](/en-US/docs/Web/CSS/CSS_cascade/Shorthand_properties) allows you to align content along both the block and inline directions at once (i.e. the {{CSSxRef("align-content")}} and {{CSSxRef("justify-content")}} properties) in a relevant layout system such as [Grid](/en-US/docs/Web/CSS/CSS_grid_layout) or [Flexbox](/en-US/docs/Web/CSS/CSS_flexible_box_layout). +The **`place-content`** [CSS](/en-US/docs/Web/CSS) [shorthand property](/en-US/docs/Web/CSS/CSS_cascade/Shorthand_properties) allows you to align content along both the block and inline directions at once (i.e., the {{CSSxRef("align-content")}} and {{CSSxRef("justify-content")}} properties) in a relevant layout system such as [Grid](/en-US/docs/Web/CSS/CSS_grid_layout) or [Flexbox](/en-US/docs/Web/CSS/CSS_flexible_box_layout). -{{EmbedInteractiveExample("pages/css/place-content.html")}} +{{InteractiveExample("CSS Demo: place-content")}} + +```css interactive-example-choice +place-content: end space-between; +``` + +```css interactive-example-choice +place-content: space-around start; +``` + +```css interactive-example-choice +place-content: start space-evenly; +``` + +```css interactive-example-choice +place-content: end center; +``` + +```css interactive-example-choice +place-content: end; +``` + +```html interactive-example +<section class="default-example" id="default-example"> + <div class="example-container"> + <div class="transition-all" id="example-element"> + <div>One</div> + <div>Two</div> + <div>Three</div> + </div> + </div> +</section> +``` + +```css interactive-example +#example-element { + border: 1px solid #c5c5c5; + display: grid; + grid-template-columns: 60px 60px; + grid-auto-rows: 40px; + height: 180px; + width: 220px; +} + +#example-element > div { + background-color: rgba(0, 0, 255, 0.2); + border: 3px solid blue; +} +``` ## Constituent properties diff --git a/files/en-us/web/css/place-items/index.md b/files/en-us/web/css/place-items/index.md index 791c1771f70c710..caba05d508326a8 100644 --- a/files/en-us/web/css/place-items/index.md +++ b/files/en-us/web/css/place-items/index.md @@ -9,7 +9,51 @@ browser-compat: css.properties.place-items The [CSS](/en-US/docs/Web/CSS) **`place-items`** [shorthand property](/en-US/docs/Web/CSS/CSS_cascade/Shorthand_properties) aligns items along both the block and inline directions at once. It sets the values of the {{CSSxRef("align-items")}} and {{CSSxRef("justify-items")}} properties. If the second value is not set, the first value is also used for it. -{{EmbedInteractiveExample("pages/css/place-items.html")}} +{{InteractiveExample("CSS Demo: place-items")}} + +```css interactive-example-choice +place-items: center stretch; +``` + +```css interactive-example-choice +place-items: center start; +``` + +```css interactive-example-choice +place-items: start end; +``` + +```css interactive-example-choice +place-items: end center; +``` + +```html interactive-example +<section class="default-example" id="default-example"> + <div class="example-container"> + <div class="transition-all" id="example-element"> + <div>One</div> + <div>Two</div> + <div>Three</div> + </div> + </div> +</section> +``` + +```css interactive-example +#example-element { + border: 1px solid #c5c5c5; + display: grid; + grid-template-columns: 1fr 1fr; + grid-auto-rows: 80px; + grid-gap: 10px; + width: 220px; +} + +#example-element > div { + background-color: rgba(0, 0, 255, 0.2); + border: 3px solid blue; +} +``` ## Constituent properties diff --git a/files/en-us/web/css/place-self/index.md b/files/en-us/web/css/place-self/index.md index d2f638be7884af8..bebb607de8213ef 100644 --- a/files/en-us/web/css/place-self/index.md +++ b/files/en-us/web/css/place-self/index.md @@ -7,9 +7,51 @@ browser-compat: css.properties.place-self {{CSSRef}} -The **`place-self`** [CSS](/en-US/docs/Web/CSS) [shorthand property](/en-US/docs/Web/CSS/CSS_cascade/Shorthand_properties) allows you to align an individual item in both the block and inline directions at once (i.e. the {{cssxref("align-self")}} and {{cssxref("justify-self")}} properties). This property applies to block-level boxes, absolutely-positioned boxes, and grid items. If the second value is not present, the first value is also used for it. +The **`place-self`** [CSS](/en-US/docs/Web/CSS) [shorthand property](/en-US/docs/Web/CSS/CSS_cascade/Shorthand_properties) allows you to align an individual item in both the block and inline directions at once (i.e., the {{cssxref("align-self")}} and {{cssxref("justify-self")}} properties). This property applies to block-level boxes, absolutely-positioned boxes, and grid items. If the second value is not present, the first value is also used for it. -{{EmbedInteractiveExample("pages/css/place-self.html")}} +{{InteractiveExample("CSS Demo: place-self")}} + +```css interactive-example-choice +place-self: stretch center; +``` + +```css interactive-example-choice +place-self: center start; +``` + +```css interactive-example-choice +place-self: start end; +``` + +```css interactive-example-choice +place-self: end center; +``` + +```html interactive-example +<section class="default-example" id="default-example"> + <div class="example-container"> + <div class="transition-all" id="example-element">One</div> + <div>Two</div> + <div>Three</div> + </div> +</section> +``` + +```css interactive-example +.example-container { + border: 1px solid #c5c5c5; + display: grid; + width: 220px; + grid-template-columns: 1fr 1fr; + grid-auto-rows: 80px; + grid-gap: 10px; +} + +.example-container > div { + background-color: rgba(0, 0, 255, 0.2); + border: 3px solid blue; +} +``` ## Constituent properties @@ -91,7 +133,7 @@ place-self: unset; ### Basic demonstration -In the following example we have a simple 2 x 2 grid layout. Initially the grid container has [`justify-items`](/en-US/docs/Web/CSS/justify-items) and [`align-items`](/en-US/docs/Web/CSS/align-items) values of `stretch` — the defaults — which causes the grid items to stretch across the entire width of their cells. +In the following example we have a 2 x 2 grid layout. Initially the grid container has [`justify-items`](/en-US/docs/Web/CSS/justify-items) and [`align-items`](/en-US/docs/Web/CSS/align-items) values of `stretch` — the defaults — which causes the grid items to stretch across the entire width of their cells. The second, third, and fourth grid items are then given different values of `place-self`, to show how these override the default placements. These values cause the grid items to span only as wide/tall as their content width/height, and align in different positions across their cells, in the block and inline directions. diff --git a/files/en-us/web/css/pointer-events/index.md b/files/en-us/web/css/pointer-events/index.md index 7312a0c9389deba..3e8a9f798c830b0 100644 --- a/files/en-us/web/css/pointer-events/index.md +++ b/files/en-us/web/css/pointer-events/index.md @@ -9,7 +9,62 @@ browser-compat: css.properties.pointer-events The **`pointer-events`** [CSS](/en-US/docs/Web/CSS) property sets under what circumstances (if any) a particular graphic element can become the [target](/en-US/docs/Web/API/Event/target) of pointer events. -{{EmbedInteractiveExample("pages/css/pointer-events.html")}} +{{InteractiveExample("CSS Demo: pointer-events")}} + +```css interactive-example-choice +pointer-events: auto; +``` + +```css interactive-example-choice +pointer-events: none; +``` + +```css interactive-example-choice +pointer-events: stroke; /* SVG-only */ +``` + +```css interactive-example-choice +pointer-events: fill; /* SVG-only */ +``` + +```html interactive-example +<section class="flex-column" id="default-example"> + <div id="example-element"> + <p> + <a href="#">example link</a> + </p> + <p> + <svg viewBox="0 0 100 100" xmlns="http://www.w3.org/2000/svg"> + <a xlink:href="#"> + <circle + cx="50" + cy="50" + fill="#3E6E84" + r="40" + stroke="#ffb500" + stroke-width="5"></circle> + <text fill="white" text-anchor="middle" x="50" y="55">SVG</text> + </a> + </svg> + </p> + </div> +</section> +``` + +```css interactive-example +#example-element { + font-weight: bold; +} + +#example-element a { + color: #009e5f; +} + +#example-element svg { + width: 10em; + height: 10em; +} +``` ## Syntax @@ -53,15 +108,15 @@ The `pointer-events` property is specified as a single keyword chosen from the l #### SVG only (experimental for HTML) - `visiblePainted` - - : SVG only (experimental for HTML). The element can only be the target of a pointer event when the `visibility` property is set to `visible` and e.g. when a mouse cursor is over the interior (i.e., 'fill') of the element and the `fill` property is set to a value other than `none`, or when a mouse cursor is over the perimeter (i.e., 'stroke') of the element and the `stroke` property is set to a value other than `none`. + - : SVG only (experimental for HTML). The element can only be the target of a pointer event when the `visibility` property is set to `visible` and e.g., when a mouse cursor is over the interior (i.e., 'fill') of the element and the `fill` property is set to a value other than `none`, or when a mouse cursor is over the perimeter (i.e., 'stroke') of the element and the `stroke` property is set to a value other than `none`. - `visibleFill` - - : SVG only. The element can only be the target of a pointer event when the `visibility` property is set to `visible` and when e.g. a mouse cursor is over the interior (i.e., fill) of the element. The value of the `fill` property does not affect event processing. + - : SVG only. The element can only be the target of a pointer event when the `visibility` property is set to `visible` and when e.g., a mouse cursor is over the interior (i.e., fill) of the element. The value of the `fill` property does not affect event processing. - `visibleStroke` - - : SVG only. The element can only be the target of a pointer event when the `visibility` property is set to `visible` and e.g. when the mouse cursor is over the perimeter (i.e., stroke) of the element. The value of the `stroke` property does not affect event processing. + - : SVG only. The element can only be the target of a pointer event when the `visibility` property is set to `visible` and e.g., when the mouse cursor is over the perimeter (i.e., stroke) of the element. The value of the `stroke` property does not affect event processing. - `visible` - - : SVG only (experimental for HTML). The element can be the target of a pointer event when the `visibility` property is set to `visible` and e.g. the mouse cursor is over either the interior (i.e., fill) or the perimeter (i.e., stroke) of the element. The values of the `fill` and `stroke` do not affect event processing. + - : SVG only (experimental for HTML). The element can be the target of a pointer event when the `visibility` property is set to `visible` and e.g., the mouse cursor is over either the interior (i.e., fill) or the perimeter (i.e., stroke) of the element. The values of the `fill` and `stroke` do not affect event processing. - `painted` - - : SVG only (experimental for HTML). The element can only be the target of a pointer event when e.g. the mouse cursor is over the interior (i.e., 'fill') of the element and the `fill` property is set to a value other than `none`, or when the mouse cursor is over the perimeter (i.e., 'stroke') of the element and the `stroke` property is set to a value other than `none`. The value of the `visibility` property does not affect event processing. + - : SVG only (experimental for HTML). The element can only be the target of a pointer event when e.g., the mouse cursor is over the interior (i.e., 'fill') of the element and the `fill` property is set to a value other than `none`, or when the mouse cursor is over the perimeter (i.e., 'stroke') of the element and the `stroke` property is set to a value other than `none`. The value of the `visibility` property does not affect event processing. - `fill` - : SVG only. The element can only be the target of a pointer event when the pointer is over the interior (i.e., fill) of the element. The values of the `fill` and `visibility` properties do not affect event processing. - `stroke` diff --git a/files/en-us/web/css/position-anchor/index.md b/files/en-us/web/css/position-anchor/index.md index 2c0ad3c9d32b3ed..d618c66d7753da7 100644 --- a/files/en-us/web/css/position-anchor/index.md +++ b/files/en-us/web/css/position-anchor/index.md @@ -9,7 +9,7 @@ browser-compat: css.properties.position-anchor {{CSSRef}}{{seecompattable}} -The **`position-anchor`** [CSS](/en-US/docs/Web/CSS) property specifies the anchor name of the **anchor element** (i.e. an element that has an **anchor name** set on it via the {{cssxref("anchor-name")}} property) a positioned element is associated with. +The **`position-anchor`** [CSS](/en-US/docs/Web/CSS) property specifies the anchor name of the **anchor element** (i.e., an element that has an **anchor name** set on it via the {{cssxref("anchor-name")}} property) a positioned element is associated with. ## Syntax @@ -30,7 +30,7 @@ position-anchor: unset; - `auto` - - : Associates a positioned element with its implicit anchor element, if it has one — for example as set by the non-standard HTML [`anchor`](/en-US/docs/Web/HTML/Global_attributes/anchor) attribute. + - : Associates a positioned element with its implicit anchor element, if it has one — for example as set by the non-standard HTML [`anchor`](/en-US/docs/Web/HTML/Reference/Global_attributes/anchor) attribute. - {{cssxref("dashed-ident")}} @@ -72,7 +72,7 @@ In this example, an {{htmlelement("output")}} is positioned relative to an ancho #### HTML -We include an [`<input type="range">`](/en-US/docs/Web/HTML/Element/input/range) element and an [`<output>`](/en-US/docs/Web/HTML/Element/output) element to display the value of the range. The value displayed in the `<output>` element is updated via JavaScript as the slider value changes. +We include an [`<input type="range">`](/en-US/docs/Web/HTML/Reference/Elements/input/range) element and an [`<output>`](/en-US/docs/Web/HTML/Reference/Elements/output) element to display the value of the range. The value displayed in the `<output>` element is updated via JavaScript as the slider value changes. ```html <label for="slider">Change the value:</label> @@ -303,6 +303,6 @@ Select different values from the drop-down menus to change the anchors that the ## See also - {{cssxref("anchor-name")}} -- HTML [`anchor`](/en-US/docs/Web/HTML/Global_attributes/anchor) attribute +- HTML [`anchor`](/en-US/docs/Web/HTML/Reference/Global_attributes/anchor) attribute - [CSS anchor positioning](/en-US/docs/Web/CSS/CSS_anchor_positioning) module - [Using CSS anchor positioning](/en-US/docs/Web/CSS/CSS_anchor_positioning/Using) guide diff --git a/files/en-us/web/css/position-area/index.md b/files/en-us/web/css/position-area/index.md index 5839ea3c7c34503..7d3a7811b9d723c 100644 --- a/files/en-us/web/css/position-area/index.md +++ b/files/en-us/web/css/position-area/index.md @@ -136,7 +136,7 @@ In this example, a positioned element is tethered and positioned relative to its #### HTML -The HTML includes a {{htmlelement("div")}} and a {{htmlelement("p")}}. The `<p>` will be positioned relative to the `<div>` with CSS. We also include a style block that will be made visible. All elements are set to be directly editable via the [`contenteditable`](/en-US/docs/Web/HTML/Global_attributes/contenteditable) attribute. +The HTML includes a {{htmlelement("div")}} and a {{htmlelement("p")}}. The `<p>` will be positioned relative to the `<div>` with CSS. We also include a style block that will be made visible. All elements are set to be directly editable via the [`contenteditable`](/en-US/docs/Web/HTML/Reference/Global_attributes/contenteditable) attribute. ```html-nolint <div class="anchor" contenteditable="true">⚓︎</div> @@ -199,7 +199,7 @@ This demo creates an anchor and tethers a positioned element to it. It also prov In the HTML, we specify two {{htmlelement("div")}} elements, one with a class of `anchor` and one with a class of `infobox`. These are intended to be the anchor element and the positioned element we will associate with it, respectively. We've included the `contenteditable` attribute on both, making them directly editable. -We've also included two forms that contain the {{htmlelement("select")}} and [`<input type="text">`](/en-US/docs/Web/HTML/Element/input/text) elements for setting different `position-area` values, and the [`<input type="checkbox">`](/en-US/docs/Web/HTML/Element/input/checkbox) element for toggling the vertical {{cssxref("writing-mode")}} on and off. The code for these, along with the JavaScript, has been hidden for the sake of brevity. +We've also included two forms that contain the {{htmlelement("select")}} and [`<input type="text">`](/en-US/docs/Web/HTML/Reference/Elements/input/text) elements for setting different `position-area` values, and the [`<input type="checkbox">`](/en-US/docs/Web/HTML/Reference/Elements/input/checkbox) element for toggling the vertical {{cssxref("writing-mode")}} on and off. The code for these, along with the JavaScript, has been hidden for the sake of brevity. ```html <div class="anchor" contenteditable>⚓︎</div> diff --git a/files/en-us/web/css/position-area_value/index.md b/files/en-us/web/css/position-area_value/index.md index e3b7eb7f28037d4..7732a5423a0111d 100644 --- a/files/en-us/web/css/position-area_value/index.md +++ b/files/en-us/web/css/position-area_value/index.md @@ -90,7 +90,7 @@ The different types of keywords that can be used include: - [Coordinate grid keywords](#coordinate_grid_keywords) > [!NOTE] -> Generally, you can't mix different types in one value, e.g. physical and logical. To do so results in invalid values. For example, `position-area: bottom inline-end` is not a valid value because it mixes physical and logical keywords. +> Generally, you can't mix different types in one value, e.g., physical and logical. To do so results in invalid values. For example, `position-area: bottom inline-end` is not a valid value because it mixes physical and logical keywords. ## Physical grid keywords diff --git a/files/en-us/web/css/position-visibility/index.md b/files/en-us/web/css/position-visibility/index.md index bdcc4b027700864..353e1d959203e77 100644 --- a/files/en-us/web/css/position-visibility/index.md +++ b/files/en-us/web/css/position-visibility/index.md @@ -143,7 +143,7 @@ We specify two {{htmlelement("div")}} elements; an anchor element with a class o </form> ``` -The HTML also includes filler text to make the content taller than the viewport so scrolling is required. We've also included a {{htmlelement("fieldset")}} with a group of [radio inputs](/en-US/docs/Web/HTML/Element/input/radio) with different `position-visibility` values. The markup for these is not shown for the sake of brevity. +The HTML also includes filler text to make the content taller than the viewport so scrolling is required. We've also included a {{htmlelement("fieldset")}} with a group of [radio inputs](/en-US/docs/Web/HTML/Reference/Elements/input/radio) with different `position-visibility` values. The markup for these is not shown for the sake of brevity. #### CSS diff --git a/files/en-us/web/css/position/index.md b/files/en-us/web/css/position/index.md index ec20242a8b7a623..84360238e8359d5 100644 --- a/files/en-us/web/css/position/index.md +++ b/files/en-us/web/css/position/index.md @@ -7,9 +7,101 @@ browser-compat: css.properties.position {{CSSRef}} -The **`position`** [CSS](/en-US/docs/Web/CSS) property sets how an element is positioned in a document. The {{Cssxref("top")}}, {{Cssxref("right")}}, {{Cssxref("bottom")}}, and {{Cssxref("left")}} properties determine the final location of positioned elements. +The **`position`** [CSS](/en-US/docs/Web/CSS) property sets how an element is positioned in a document. The {{Cssxref("top")}}, {{Cssxref("right")}}, {{Cssxref("bottom")}}, and {{Cssxref("left")}} physical properties and the {{cssxref("inset-block-start")}}, {{cssxref("inset-block-end")}}, {{cssxref("inset-inline-start")}}, and {{cssxref("inset-inline-end")}} flow-relative logical properties can be used to determine the final location of positioned elements. -{{EmbedInteractiveExample("pages/css/position.html")}} +{{InteractiveExample("CSS Demo: position")}} + +```css interactive-example-choice +position: static; +``` + +```css interactive-example-choice +position: relative; +top: 40px; +left: 40px; +``` + +```css interactive-example-choice +position: absolute; +inset-inline-start: 40px; +inset-block-start: 40px; +``` + +```css interactive-example-choice +position: sticky; +top: 20px; +``` + +```html interactive-example +<section class="default-example" id="default-example"> + <div id="example-element-container"> + <p> + In this demo you can control the <code>position</code> property for the + yellow box. + </p> + <div class="box"></div> + <div class="box" id="example-element"></div> + <div class="box"></div> + <p class="clear"> + To see the effect of <code>sticky</code> positioning, select the + <code>position: sticky</code> option and scroll this container. + </p> + <p> + The element will scroll along with its container, until it is at the top + of the container (or reaches the offset specified in <code>top</code>), + and will then stop scrolling, so it stays visible. + </p> + <p> + The rest of this text is only supplied to make sure the container + overflows, so as to enable you to scroll it and see the effect. + </p> + <hr /> + <p> + Far out in the uncharted backwaters of the unfashionable end of the + western spiral arm of the Galaxy lies a small unregarded yellow sun. + Orbiting this at a distance of roughly ninety-two million miles is an + utterly insignificant little blue green planet whose ape-descended life + forms are so amazingly primitive that they still think digital watches are + a pretty neat idea. + </p> + </div> +</section> +``` + +```css interactive-example +section { + align-items: flex-start; + overflow: auto; +} + +.box { + background-color: rgba(0, 0, 255, 0.2); + border: 3px solid blue; + float: left; + width: 65px; + height: 65px; +} + +.box + .box { + margin-left: 10px; +} + +.clear { + clear: both; + padding-top: 1em; +} + +#example-element-container { + position: relative; + text-align: left; +} + +#example-element { + background-color: yellow; + border: 3px solid red; + z-index: 1; +} +``` ## Syntax @@ -36,25 +128,25 @@ position: unset; - : The element is positioned according to the normal flow of the document, and then offset _relative to itself_ based on the values of `top`, `right`, `bottom`, and `left`. The offset does not affect the position of any other elements; thus, the space given for the element in the page layout is the same as if position were `static`. - This value creates a new [stacking context](/en-US/docs/Web/CSS/CSS_positioned_layout/Understanding_z-index/Stacking_context) when the value of `z-index` is not `auto`. Its effect on `table-*-group`, `table-row`, `table-column`, `table-cell`, and `table-caption` elements is undefined. + This value creates a new [stacking context](/en-US/docs/Web/CSS/CSS_positioned_layout/Stacking_context) when the value of `z-index` is not `auto`. Its effect on `table-*-group`, `table-row`, `table-column`, `table-cell`, and `table-caption` elements is undefined. - `absolute` - : The element is removed from the normal document flow, and no space is created for the element in the page layout. The element is positioned relative to its closest positioned ancestor (if any) or to the initial [containing block](/en-US/docs/Web/CSS/CSS_display/Containing_block#identifying_the_containing_block). Its final position is determined by the values of `top`, `right`, `bottom`, and `left`. - This value creates a new [stacking context](/en-US/docs/Web/CSS/CSS_positioned_layout/Understanding_z-index/Stacking_context) when the value of `z-index` is not `auto`. The margins of absolutely positioned boxes do not [collapse](/en-US/docs/Web/CSS/CSS_box_model/Mastering_margin_collapsing) with other margins. + This value creates a new [stacking context](/en-US/docs/Web/CSS/CSS_positioned_layout/Stacking_context) when the value of `z-index` is not `auto`. The margins of absolutely positioned boxes do not [collapse](/en-US/docs/Web/CSS/CSS_box_model/Mastering_margin_collapsing) with other margins. - `fixed` - : The element is removed from the normal document flow, and no space is created for the element in the page layout. The element is positioned relative to its initial [containing block](/en-US/docs/Web/CSS/CSS_display/Containing_block#identifying_the_containing_block), which is the viewport in the case of visual media. Its final position is determined by the values of `top`, `right`, `bottom`, and `left`. - This value always creates a new [stacking context](/en-US/docs/Web/CSS/CSS_positioned_layout/Understanding_z-index/Stacking_context). In printed documents, the element is placed in the same position on _every page_. + This value always creates a new [stacking context](/en-US/docs/Web/CSS/CSS_positioned_layout/Stacking_context). In printed documents, the element is placed in the same position on _every page_. - `sticky` - : The element is positioned according to the normal flow of the document, and then offset relative to its _nearest scrolling ancestor_ and [containing block](/en-US/docs/Web/CSS/CSS_display/Containing_block) (nearest block-level ancestor), including table-related elements, based on the values of `top`, `right`, `bottom`, and `left`. The offset does not affect the position of any other elements. - This value always creates a new [stacking context](/en-US/docs/Web/CSS/CSS_positioned_layout/Understanding_z-index/Stacking_context). Note that a sticky element "sticks" to its nearest ancestor that has a "scrolling mechanism" (created when `overflow` is `hidden`, `scroll`, `auto`, or `overlay`), even if that ancestor isn't the nearest actually scrolling ancestor. + This value always creates a new [stacking context](/en-US/docs/Web/CSS/CSS_positioned_layout/Stacking_context). Note that a sticky element "sticks" to its nearest ancestor that has a "scrolling mechanism" (created when `overflow` is `hidden`, `scroll`, `auto`, or `overlay`), even if that ancestor isn't the nearest actually scrolling ancestor. > [!NOTE] > At least one [inset](/en-US/docs/Web/CSS/inset) property ({{cssxref("top")}}, {{cssxref("inset-block-start")}}, {{cssxref("right")}}, {{cssxref("inset-inline-end")}}, etc.) needs to be set to a non-`auto` value for the axis on which the element needs to be made sticky. If both `inset` properties for an axis are set to `auto`, on that axis the `sticky` value will behave as `relative`. @@ -63,12 +155,12 @@ position: unset; ### Types of positioning -- A **positioned element** is an element whose [computed](/en-US/docs/Web/CSS/CSS_cascade/computed_value) `position` value is either `relative`, `absolute`, `fixed`, or `sticky`. (In other words, it's anything except `static`.) -- A **relatively positioned element** is an element whose [computed](/en-US/docs/Web/CSS/CSS_cascade/computed_value) `position` value is `relative`. The {{Cssxref("top")}} and {{Cssxref("bottom")}} properties specify the vertical offset from its normal position; the {{Cssxref("left")}} and {{Cssxref("right")}} properties specify the horizontal offset. -- An **absolutely positioned element** is an element whose [computed](/en-US/docs/Web/CSS/CSS_cascade/computed_value) `position` value is `absolute` or `fixed`. The {{Cssxref("top")}}, {{Cssxref("right")}}, {{Cssxref("bottom")}}, and {{Cssxref("left")}} properties specify offsets from the edges of the element's [containing block](/en-US/docs/Web/CSS/CSS_display/Containing_block). (The containing block is the ancestor relative to which the element is positioned.) If the element has margins, they are added to the offset. The element establishes a new [block formatting context](/en-US/docs/Web/CSS/CSS_display/Block_formatting_context) (BFC) for its contents. -- A **stickily positioned element** is an element whose [computed](/en-US/docs/Web/CSS/CSS_cascade/computed_value) `position` value is `sticky`. It's treated as relatively positioned until its [containing block](/en-US/docs/Web/CSS/CSS_display/Containing_block) crosses a specified threshold (such as setting {{Cssxref("top")}} to value other than auto) within its flow root (or the container it scrolls within), at which point it is treated as "stuck" until meeting the opposite edge of its [containing block](/en-US/docs/Web/CSS/CSS_display/Containing_block). +- A **positioned element** is an element whose [computed](/en-US/docs/Web/CSS/CSS_cascade/Value_processing#computed_value) `position` value is either `relative`, `absolute`, `fixed`, or `sticky`. (In other words, it's anything except `static`.) +- A **relatively positioned element** is an element whose [computed](/en-US/docs/Web/CSS/CSS_cascade/Value_processing#computed_value) `position` value is `relative`. The {{Cssxref("top")}} and {{Cssxref("bottom")}} properties specify the vertical offset from its normal position; the {{Cssxref("left")}} and {{Cssxref("right")}} properties specify the horizontal offset. +- An **absolutely positioned element** is an element whose [computed](/en-US/docs/Web/CSS/CSS_cascade/Value_processing#computed_value) `position` value is `absolute` or `fixed`. The {{Cssxref("top")}}, {{Cssxref("right")}}, {{Cssxref("bottom")}}, and {{Cssxref("left")}} properties specify offsets from the edges of the element's [containing block](/en-US/docs/Web/CSS/CSS_display/Containing_block). (The containing block is the ancestor relative to which the element is positioned.) If the element has margins, they are added to the offset. The element establishes a new [block formatting context](/en-US/docs/Web/CSS/CSS_display/Block_formatting_context) (BFC) for its contents. +- A **stickily positioned element** is an element whose [computed](/en-US/docs/Web/CSS/CSS_cascade/Value_processing#computed_value) `position` value is `sticky`. It's treated as relatively positioned until its [containing block](/en-US/docs/Web/CSS/CSS_display/Containing_block) crosses a specified threshold (such as setting {{Cssxref("top")}} to value other than auto) within its flow root (or the container it scrolls within), at which point it is treated as "stuck" until meeting the opposite edge of its [containing block](/en-US/docs/Web/CSS/CSS_display/Containing_block). -Most of the time, absolutely positioned elements that have {{Cssxref("height")}} and {{Cssxref("width")}} set to `auto` are sized so as to fit their contents. However, non-[replaced](/en-US/docs/Web/CSS/Replaced_element), absolutely positioned elements can be made to fill the available vertical space by specifying both {{Cssxref("top")}} and {{Cssxref("bottom")}} and leaving {{Cssxref("height")}} unspecified (that is, `auto`). They can likewise be made to fill the available horizontal space by specifying both {{Cssxref("left")}} and {{Cssxref("right")}} and leaving {{Cssxref("width")}} as `auto`. +Most of the time, absolutely positioned elements that have {{Cssxref("height")}} and {{Cssxref("width")}} set to `auto` are sized so as to fit their contents. However, non-[replaced](/en-US/docs/Glossary/Replaced_elements), absolutely positioned elements can be made to fill the available vertical space by specifying both {{Cssxref("top")}} and {{Cssxref("bottom")}} and leaving {{Cssxref("height")}} unspecified (that is, `auto`). They can likewise be made to fill the available horizontal space by specifying both {{Cssxref("left")}} and {{Cssxref("right")}} and leaving {{Cssxref("width")}} as `auto`. Except for the case just described (of absolutely positioned elements filling the available space): @@ -79,7 +171,7 @@ Except for the case just described (of absolutely positioned elements filling th Ensure that elements positioned with an `absolute` or `fixed` value do not obscure other content when the page is zoomed to increase text size. -- [MDN Understanding WCAG, Guideline 1.4 explanations](/en-US/docs/Web/Accessibility/Understanding_WCAG/Perceivable#guideline_1.4_make_it_easier_for_users_to_see_and_hear_content_including_separating_foreground_from_background) +- [MDN Understanding WCAG, Guideline 1.4 explanations](/en-US/docs/Web/Accessibility/Guides/Understanding_WCAG/Perceivable#guideline_1.4_make_it_easier_for_users_to_see_and_hear_content_including_separating_foreground_from_background) - [Visual Presentation: Understanding SC 1.4.8 | Understanding WCAG 2.0](https://www.w3.org/TR/UNDERSTANDING-WCAG20/visual-audio-contrast-visual-presentation.html) ### Performance & Accessibility @@ -196,8 +288,8 @@ span { .positioned { position: absolute; background: yellow; - top: 30px; - left: 30px; + inset-block-start: 30px; + inset-inline-start: 30px; } ``` @@ -451,4 +543,7 @@ When you put both bulbs in their proper place, you'll notice that they are relat ## See also +- {{glossary("Inset properties")}} - [Learn CSS: Positioning](/en-US/docs/Learn_web_development/Core/CSS_layout/Positioning) +- [Inset properties for positioned layout](/en-US/docs/Web/CSS/CSS_logical_properties_and_values/Floating_and_positioning#example_inset_properties_for_positioned_layout) +- [CSS positioned layout](/en-US/docs/Web/CSS/CSS_positioned_layout) modules diff --git a/files/en-us/web/css/privacy_and_the__colon_visited_selector/index.md b/files/en-us/web/css/privacy_and_the__colon_visited_selector/index.md deleted file mode 100644 index 383d67995000e2b..000000000000000 --- a/files/en-us/web/css/privacy_and_the__colon_visited_selector/index.md +++ /dev/null @@ -1,64 +0,0 @@ ---- -title: Privacy and the :visited selector -slug: Web/CSS/Privacy_and_the_:visited_selector -page-type: guide ---- - -{{CSSRef}} - -Before about 2010, the [CSS](/en-US/docs/Web/CSS) {{ cssxref(":visited") }} selector allowed websites to uncover a user's browsing history and figure out what sites the user had visited. This was done through {{domxref("window.getComputedStyle")}} and other techniques. This process was quick to execute, and made it possible not only to determine where the user had been on the web, but could also be used to guess a lot of information about the user's identity. - -To mitigate this problem, browsers have limited the amount of information that can be obtained from visited links. - -## Little white lies - -To preserve users' privacy, Firefox and other browsers will lie to web applications under certain circumstances: - -- The `window.getComputedStyle` method, and similar functions such as {{ domxref("element.querySelector") }}, will always return values indicating that a user has never visited any of the links on a page. -- If you use a sibling selector such as `:visited + span`, the adjacent element (`span` in this example) will be styled as if the link were unvisited. -- In rare scenarios, if you're using nested link elements and the element being matched is different from the link whose presence in history is being tested, the element will be rendered as if the link were unvisited, as well. - -## Limits to visited link styles - -You can style visited links, but there are limits to which styles you can use. Only the following styles can be applied to visited links: - -- {{ cssxref("color") }} -- {{ cssxref("background-color") }} -- {{ cssxref("border-color") }} (and its sub-properties) -- {{ cssxref("column-rule-color") }} -- {{ cssxref("outline-color") }} -- {{ cssxref("text-decoration-color") }} -- {{ cssxref("text-emphasis-color") }} -- The color parts of the {{SVGAttr("fill")}} and {{SVGAttr("stroke")}} attributes - -In addition, even for the above styles, you won't be able to change the transparency between unvisited and visited links, as you otherwise would be able to using the `alpha` parameter to [`rgb()`](/en-US/docs/Web/CSS/color_value/rgb) or [`hsl()`](/en-US/docs/Web/CSS/color_value/hsl), or the [`transparent`](/en-US/docs/Web/CSS/named-color#transparent) keyword. - -Here is an example of how to use styles with the aforementioned restrictions: - -```css -:link { - outline: 1px dotted blue; - background-color: white; - /* The default value of background-color is `transparent`. You need to - specify a different value, otherwise changes on :visited won't apply. */ -} - -:visited { - outline-color: orange; /* Visited links have an orange outline */ - background-color: green; /* Visited links have a green background */ - color: yellow; /* Visited links have yellow colored text */ -} -``` - -## Impact on web developers - -Overall, these restrictions shouldn't affect web developers too significantly. They may, however, require the following changes to existing sites: - -- Using background images to style links based on whether they've been visited will no longer work, since only colors can be used to style visited links. -- Colors that are otherwise transparent will fail to appear if styled in a `:visited` selector. - -## See also - -- [privacy-related changes coming to CSS :visited](https://hacks.mozilla.org/2010/03/privacy-related-changes-coming-to-css-vistited/) on Mozilla Hacks -- [Plugging the CSS History Leak](https://blog.mozilla.org/security/2010/03/31/plugging-the-css-history-leak/) on the Mozilla Security Blog -- [Preventing attacks on a user's history through CSS :visited selectors](https://dbaron.org/mozilla/visited-privacy) diff --git a/files/en-us/web/css/pseudo-classes/index.md b/files/en-us/web/css/pseudo-classes/index.md index 32740a743c0f318..3ca5df52b24df22 100644 --- a/files/en-us/web/css/pseudo-classes/index.md +++ b/files/en-us/web/css/pseudo-classes/index.md @@ -3,9 +3,10 @@ title: Pseudo-classes slug: Web/CSS/Pseudo-classes page-type: landing-page spec-urls: - - https://html.spec.whatwg.org/multipage/#pseudo-classes + - https://html.spec.whatwg.org/multipage/semantics-other.html#pseudo-classes - https://drafts.csswg.org/selectors/ - - https://drafts.csswg.org/css-ui/ + - https://drafts.csswg.org/css-scoping/ + - https://drafts.csswg.org/css-page/ --- {{CSSRef}} @@ -26,14 +27,25 @@ Pseudo-classes let you apply a style to an element not only in relation to the c > [!NOTE] > In contrast to pseudo-classes, [pseudo-elements](/en-US/docs/Web/CSS/Pseudo-elements) can be used to style a _specific part_ of an element. +## Elemental pseudo-classes + +These pseudo-classes relate to the core identity of elements. + +- {{CSSxRef(":defined")}} + - : Matches any element that is defined. + ## Element display state pseudo-classes These pseudo-classes enable the selection of elements based on their display states. -- {{CSSxRef(":fullscreen")}} - - : Matches an element that is currently in fullscreen mode. +- {{CSSxRef(":open")}} + - : Matches an element that can either be open or closed that is currently open. +- {{CSSxRef(":popover-open")}} + - : Matches a popover element that is currently in the showing state. - {{CSSxRef(":modal")}} - : Matches an element that is in a state in which it excludes all interaction with elements outside it until the interaction has been dismissed. +- {{CSSxRef(":fullscreen")}} + - : Matches an element that is currently in fullscreen mode. - {{CSSxRef(":picture-in-picture")}} - : Matches an element that is currently in picture-in-picture mode. @@ -41,8 +53,6 @@ These pseudo-classes enable the selection of elements based on their display sta These pseudo-classes relate to form elements, and enable selecting elements based on HTML attributes and the state that the field is in before and after interaction. -- {{CSSxRef(":autofill")}} - - : Matches when an {{htmlelement("input")}} has been autofilled by the browser. - {{CSSxRef(":enabled")}} - : Represents a user interface element that is in an enabled state. - {{CSSxRef(":disabled")}} @@ -53,6 +63,8 @@ These pseudo-classes relate to form elements, and enable selecting elements base - : Represents any element that is user-editable. - {{CSSxRef(":placeholder-shown")}} - : Matches an input element that is displaying placeholder text. For example, it will match the `placeholder` attribute in the {{htmlelement("input")}} and {{htmlelement("textarea")}} elements. +- {{CSSxRef(":autofill")}} + - : Matches when an {{htmlelement("input")}} has been autofilled by the browser. - {{CSSxRef(":default")}} - : Matches one or more UI elements that are the default among a set of elements. - {{CSSxRef(":checked")}} @@ -111,9 +123,19 @@ These pseudo-classes relate to links, and to targeted elements within the curren These pseudo-classes apply to media that is capable of being in a state where it would be described as playing, such as a video. - {{CSSxRef(":playing")}} - - : Represents a media element that is capable of playing when that element is playing. + - : Represents a playable element that is playing. - {{CSSxRef(":paused")}} - - : Represents a media element that is capable of playing when that element is paused. + - : Represents a playable element that is paused. +- {{CSSxRef(":seeking")}} + - : Represents a playable element that is currently seeking a playback position in the media resource. +- {{CSSxRef(":buffering")}} + - : Represents a playable element that is playing but is temporarily stalled because it is downloading the media resource. +- {{CSSxRef(":stalled")}} + - : Represents a playable element that is playing but is stalled because it cannot download the media resource. +- {{CSSxRef(":muted")}} + - : Represents a sound-producing element that is muted. +- {{CSSxRef(":volume-locked")}} + - : Represents a sound-producing element that has its volume level locked by the browser. ## Time-dimensional pseudo-classes @@ -134,9 +156,9 @@ These pseudo-classes relate to the location of an element within the document tr - : Represents an element that is the root of the document. In HTML this is usually the `<html>` element. - {{CSSxRef(":empty")}} - : Represents an element with no children other than white-space characters. -- {{CSSxRef(":nth-child")}} +- {{CSSxRef(":nth-child", ":nth-child()")}} - : Uses `An+B` notation to select elements from a list of sibling elements. -- {{CSSxRef(":nth-last-child")}} +- {{CSSxRef(":nth-last-child", ":nth-last-child()")}} - : Uses `An+B` notation to select elements from a list of sibling elements, counting backwards from the end of the list. - {{CSSxRef(":first-child")}} - : Matches an element that is the first of its siblings. @@ -144,9 +166,9 @@ These pseudo-classes relate to the location of an element within the document tr - : Matches an element that is the last of its siblings. - {{CSSxRef(":only-child")}} - : Matches an element that has no siblings. For example, a list item with no other list items in that list. -- {{CSSxRef(":nth-of-type")}} +- {{CSSxRef(":nth-of-type", ":nth-of-type()")}} - : Uses `An+B` notation to select elements from a list of sibling elements that match a certain type from a list of sibling elements. -- {{CSSxRef(":nth-last-of-type")}} +- {{CSSxRef(":nth-last-of-type", ":nth-last-of-type()")}} - : Uses `An+B` notation to select elements from a list of sibling elements that match a certain type from a list of sibling elements counting backwards from the end of the list. - {{CSSxRef(":first-of-type")}} - : Matches an element that is the first of its siblings, and also matches a certain type selector. @@ -155,6 +177,19 @@ These pseudo-classes relate to the location of an element within the document tr - {{CSSxRef(":only-of-type")}} - : Matches an element that has no siblings of the chosen type selector. +## Shadow-structural pseudo-classes + +These pseudo-classes relate to the shadow DOM. + +- {{CSSxRef(":host")}} + - : Matches the shadow tree's shadow host. +- {{CSSxRef(":host_function", ":host()")}} + - : Matches an element that matches {{CSSxRef(":host")}} and matches any of the selectors in the list provided. +- {{CSSxRef(":host-context", ":host-context()")}} + - : Selects elements outside of the shadow tree in the context of the shadow host. +- {{CSSxRef(":has-slotted")}} + - : Matches slot elements that have been assigned content. + ## User action pseudo-classes These pseudo-classes require some interaction by the user in order for them to apply, such as holding a mouse pointer over an element. @@ -169,20 +204,42 @@ These pseudo-classes require some interaction by the user in order for them to a - : Matches when an element has focus and the user agent identifies that the element should be visibly focused. - {{CSSxRef(":focus-within")}} - : Matches an element to which {{CSSxRef(":focus")}} applies, plus any element that has a descendant to which {{CSSxRef(":focus")}} applies. +- {{CSSxRef(":target-current")}} + - : Matches the {{cssxref("::scroll-marker")}} pseudo-element of a {{cssxref("scroll-marker-group")}} that is currently scrolled to, in other words, the **active** scroll marker. ## Functional pseudo-classes These pseudo-classes accept a [selector list](/en-US/docs/Web/CSS/Selector_list) or [forgiving selector list](/en-US/docs/Web/CSS/Selector_list#forgiving_selector_list) as a parameter. -- [`:is()`](/en-US/docs/Web/CSS/:is) +- {{CSSxRef(":is", ":is()")}} - : The matches-any pseudo-class matches any element that matches any of the selectors in the list provided. The list is forgiving. -- [`:not()`](/en-US/docs/Web/CSS/:not) +- {{CSSxRef(":not", ":not()")}} - : The negation, or matches-none, pseudo-class represents any element that is not represented by its argument. -- [`:where()`](/en-US/docs/Web/CSS/:where) +- {{CSSxRef(":where", ":where()")}} - : The specificity-adjustment pseudo-class matches any element that matches any of the selectors in the list provided without adding any specificity weight. The list is forgiving. -- [`:has()`](/en-US/docs/Web/CSS/:has) +- {{CSSxRef(":has", ":has()")}} - : The relational pseudo-class represents an element if any of the relative selectors match when anchored against the attached element. +## Custom state pseudo-classes + +These pseudo-classes apply to custom elements. + +- {{CSSxRef(":state", ":state()")}} + - : Matches custom elements that have the specified custom state. + +## Page pseudo-classes + +These pseudo-classes relate to pages in a printed document and are used with the {{CSSxRef("@page")}} at-rule. + +- {{CSSxRef(":left")}} + - : Represents all left-hand pages of a printed document. +- {{CSSxRef(":right")}} + - : Represents all right-hand pages of a printed document. +- {{CSSxRef(":first")}} + - : Represents the first page of a printed document. +- `:blank` + - : Represents a blank page in a printed document. + ## Syntax ```css @@ -205,12 +262,14 @@ A B -- {{CSSxRef(":blank")}} {{Experimental_Inline}} +- {{CSSxRef(":blank")}} (input) {{Experimental_Inline}} +- `:blank` (page) +- {{CSSxRef(":buffering")}} C - {{CSSxRef(":checked")}} -- {{CSSxRef(":current")}} +- {{CSSxRef(":current")}} {{Experimental_Inline}} D @@ -233,20 +292,21 @@ F - {{CSSxRef(":focus-visible")}} - {{CSSxRef(":focus-within")}} - {{CSSxRef(":fullscreen")}} -- {{CSSxRef(":future")}} {{Experimental_Inline}} +- {{CSSxRef(":future")}} H -- {{CSSxRef(":has", ":has()")}} {{Experimental_Inline}} +- {{CSSxRef(":has-slotted")}} +- {{CSSxRef(":has", ":has()")}} - {{CSSxRef(":host")}} - {{CSSxRef(":host_function", ":host()")}} -- {{CSSxRef(":host-context", ":host-context()")}} {{Experimental_Inline}} +- {{CSSxRef(":host-context", ":host-context()")}} - {{CSSxRef(":hover")}} I -- {{CSSxRef(":indeterminate")}} - {{CSSxRef(":in-range")}} +- {{CSSxRef(":indeterminate")}} - {{CSSxRef(":invalid")}} - {{CSSxRef(":is", ":is()")}} @@ -257,11 +317,12 @@ L - {{CSSxRef(":last-of-type")}} - {{CSSxRef(":left")}} - {{CSSxRef(":link")}} -- {{CSSxRef(":local-link")}} +- {{CSSxRef(":local-link")}} {{Experimental_Inline}} M - {{CSSxRef(":modal")}} +- {{CSSxRef(":muted")}} N @@ -299,21 +360,26 @@ R S - {{CSSxRef(":scope")}} +- {{CSSxRef(":seeking")}} +- {{CSSxRef(":stalled")}} - {{CSSxRef(":state", ":state()")}} T - {{CSSxRef(":target")}} +- {{CSSxRef(":target-current")}} - {{CSSxRef(":target-within")}} {{Experimental_Inline}} U - {{CSSxRef(":user-invalid")}} +- {{CSSxRef(":user-valid")}} V - {{CSSxRef(":valid")}} - {{CSSxRef(":visited")}} +- {{CSSxRef(":volume-locked")}} W diff --git a/files/en-us/web/css/pseudo-elements/index.md b/files/en-us/web/css/pseudo-elements/index.md index 7d7fc2efb8db0bf..ea3620b3e1afdd9 100644 --- a/files/en-us/web/css/pseudo-elements/index.md +++ b/files/en-us/web/css/pseudo-elements/index.md @@ -74,12 +74,18 @@ These pseudo-elements behave like regular elements, fitting seamlessly within th - : Creates a pseudo-element that is the first child of the selected element. - {{CSSxRef("::after")}} - : Creates a pseudo-element that is the last child of the selected element. +- {{CSSxRef("::column")}} + - : Each column fragment of a [multi-column layout](/en-US/docs/Web/CSS/CSS_multicol_layout). - {{CSSxRef("::marker")}} - : The automatically generated marker box of a list item. -- {{CSSxRef("::placeholder")}} - - : The placeholder text in an input field. - {{CSSxRef("::backdrop")}} - : The backdrop of the originating element rendered in the [top layer](/en-US/docs/Glossary/Top_layer). +- {{CSSxRef("::scroll-button()")}} + - : Creates a button that can control the scrolling of the {{glossary("scroll container")}} to which it is applied. +- {{CSSxRef("::scroll-marker")}} + - : Creates a pseudo-element that is a scroll marker — a scroll target button for its originating element nested in a scroll-marker group. +- {{CSSxRef("::scroll-marker-group")}} + - : Generates a container before or after a scroll container to contain the {{cssxref("::scroll-marker")}} pseudo-elements generated on the element or its descendants. ## Element-backed pseudo-elements @@ -87,13 +93,26 @@ These pseudo-elements are real elements that are not otherwise selectable. - {{CSSxRef("::details-content")}} - : The expandable/collapsible contents of a {{HTMLElement("details")}} element. -- {{CSSxRef("::file-selector-button")}} - - : The button of an {{HTMLElement("input") }} of [`type="file"`](/en-US/docs/Web/HTML/Element/input/file). - {{CSSxRef("::part", "::part()")}} - - : Any element within a [shadow tree](/en-US/docs/Web/API/Web_components/Using_shadow_DOM) that has a matching [`part`](/en-US/docs/Web/HTML/Global_attributes/part) attribute. + - : Any element within a [shadow tree](/en-US/docs/Web/API/Web_components/Using_shadow_DOM) that has a matching [`part`](/en-US/docs/Web/HTML/Reference/Global_attributes/part) attribute. - {{CSSxRef("::slotted", "::slotted()")}} - : Any element placed into a slot inside an HTML template. +## Form-related pseudo-elements + +The pseudo-elements are related to form controls. + +- {{CSSxRef("::checkmark")}} + - : Targets the checkmark placed inside the currently-selected `<option>` element of a [customizable select element](/en-US/docs/Learn_web_development/Extensions/Forms/Customizable_select) to provide a visual indication of which one is selected. +- {{CSSxRef("::file-selector-button")}} + - : The button of an {{HTMLElement("input") }} of [`type="file"`](/en-US/docs/Web/HTML/Reference/Elements/input/file). +- {{CSSxRef("::picker()")}} + - : The picker part of an element, for example the drop-down picker of a [customizable select element](/en-US/docs/Learn_web_development/Extensions/Forms/Customizable_select). +- {{CSSxRef("::picker-icon")}} + - : The picker icon inside form controls that have an icon associated with them. In the case of a [customizable select element](/en-US/docs/Learn_web_development/Extensions/Forms/Customizable_select), it selects the arrow that points down when the select is closed. +- {{CSSxRef("::placeholder")}} + - : The placeholder text in an input field. + ## Alphabetical index Pseudo-elements defined by a set of CSS specifications include the following: @@ -109,6 +128,8 @@ B C +- {{CSSxRef("::column")}} +- {{CSSxRef("::checkmark")}} - {{CSSxRef("::cue")}} (and {{CSSxRef("::cue", "::cue()")}}) D @@ -136,10 +157,15 @@ M P - {{CSSxRef("::part", "::part()")}} +- {{CSSxRef("::picker()")}} +- {{CSSxRef("::picker-icon")}} - {{CSSxRef("::placeholder")}} S +- {{CSSxRef("::scroll-button()")}} +- {{CSSxRef("::scroll-marker")}} +- {{CSSxRef("::scroll-marker-group")}} - {{CSSxRef("::selection")}} - {{CSSxRef("::slotted", "::slotted()")}} - {{CSSxRef("::spelling-error")}} @@ -156,6 +182,17 @@ V - {{cssxref("::view-transition-new()")}} - {{cssxref("::view-transition-old()")}} +## Nesting pseudo-elements + +You can chain some pseudo-element selectors together to style pseudo-elements nested inside other pseudo-elements. The following nested pseudo-element combinations are supported: + +- {{CSSxRef("::after")}} + - `::after::marker`: Selects the {{CSSxRef("::marker")}} pseudo-element of an `::after` pseudo-element, when `::after` is styled as a list item, with {{CSSxRef("display", "display: list-item")}}. +- {{CSSxRef("::before")}} + - `::before::marker`: Selects the {{CSSxRef("::marker")}} pseudo-element of a `::before` pseudo-element, when `::before` is styled as a list item, with {{CSSxRef("display", "display: list-item")}}. + +Check out the individual pseudo-element reference pages for examples and browser compatibility information. + ## Specifications {{Specifications}} diff --git a/files/en-us/web/css/quotes/index.md b/files/en-us/web/css/quotes/index.md index e1778d818b5ba21..eece9838ed644dc 100644 --- a/files/en-us/web/css/quotes/index.md +++ b/files/en-us/web/css/quotes/index.md @@ -9,7 +9,42 @@ browser-compat: css.properties.quotes The [CSS](/en-US/docs/Web/CSS) **`quotes`** property sets how the browser should render quotation marks that are automatically added to the HTML {{HTMLElement("q")}} element or added using the `open-quotes` or `close-quotes` (or omitted using the `no-open-quote` and `no-close-quote`) values of the of the CSS [`content`](/en-US/docs/Web/CSS/content) property. -{{EmbedInteractiveExample("pages/css/quotes.html")}} +{{InteractiveExample("CSS Demo: quotes")}} + +```css interactive-example-choice +quotes: none; +``` + +```css interactive-example-choice +quotes: initial; +``` + +```css interactive-example-choice +quotes: "'" "'"; +``` + +```css interactive-example-choice +quotes: "„" "“" "‚" "‘"; +``` + +```css interactive-example-choice +quotes: "«" "»" "‹" "›"; +``` + +```html interactive-example +<section id="default-example"> + <q id="example-element" + >Show us the wonder-working <q>Brothers,</q> let them come out publicly—and + we will believe in them!</q + > +</section> +``` + +```css interactive-example +q { + font-size: 1.2rem; +} +``` Browsers insert quotation marks at the opening and closing of `<q>` elements and for the `open-quote` and `close-quote` values of the `content` property. Each opening or closing quote is replaced by one of the strings from the value of `quotes`, based on the depth of nesting, or, if `quotes` is explicitly set to or otherwise resolves to `auto`, the quotation marks used are language dependent. @@ -37,8 +72,8 @@ quotes: unset; - `none` - : The `open-quote` and `close-quote` values of the {{cssxref("content")}} property produce no quotation marks, as if `no-open-quote` and `no-close-quote` were set, respectively. - `auto` - - : Quotation marks that are typographically appropriate for the inherited language (i.e. via the [`lang`](/en-US/docs/Web/HTML/Global_attributes/lang) attribute set on the parent or other ancestor). -- `[{{cssxref("&lt;string&gt;")}} <string>]+` + - : Quotation marks that are typographically appropriate for the inherited language (i.e., via the [`lang`](/en-US/docs/Web/HTML/Reference/Global_attributes/lang) attribute set on the parent or other ancestor). +- {{cssxref("&lt;string&gt;")}} - : Defines one or more pairs of quotation mark values for opening and closing quotes. In each pair, the first of each pair of quotes are used as the values for the `open-quote` and the second of each pair is the `close-quote`. @@ -63,7 +98,7 @@ quotes: unset; This examples compares the default quotes provided by the semantic HTML `<q>` element to those we define using the CSS `quotes` property. -The default value of `quotes` is [`auto`](#auto). In this example, the first list item has `quotes: auto` set, so gets the default quotes for the language specified; the same as if no `quotes` property was set. The second list item defines which quotation marks to use for quotes and nested quotes; these quotation marks will be used for descendants of an element with `specialQuotes` class regardless of the language (like any [`lang`](/en-US/docs/Web/HTML/Global_attributes/lang) attribute values set). +The default value of `quotes` is [`auto`](#auto). In this example, the first list item has `quotes: auto` set, so gets the default quotes for the language specified; the same as if no `quotes` property was set. The second list item defines which quotation marks to use for quotes and nested quotes; these quotation marks will be used for descendants of an element with `specialQuotes` class regardless of the language (like any [`lang`](/en-US/docs/Web/HTML/Reference/Global_attributes/lang) attribute values set). #### HTML @@ -157,7 +192,7 @@ li { {{EmbedLiveSample('Auto_quotes', "100%", 200)}} -Note that the [`lang`](/en-US/docs/Web/HTML/Global_attributes/lang) attribute was placed on an ancestor of the `<q>`, not the `<q>` itself. If a quotation is in a different language than the surrounding text, it is customary to quote the text with the quote marks of the language of the surrounding text, not the language of the quotation itself. +Note that the [`lang`](/en-US/docs/Web/HTML/Reference/Global_attributes/lang) attribute was placed on an ancestor of the `<q>`, not the `<q>` itself. If a quotation is in a different language than the surrounding text, it is customary to quote the text with the quote marks of the language of the surrounding text, not the language of the quotation itself. ### With generated content diff --git a/files/en-us/web/css/ray/index.md b/files/en-us/web/css/ray/index.md index 523786d43d98040..563c30d3910ab3a 100644 --- a/files/en-us/web/css/ray/index.md +++ b/files/en-us/web/css/ray/index.md @@ -226,10 +226,10 @@ body { } .container { - transform-style: preserve-3d; - width: 150px; - height: 100px; - border: 2px dotted green; + transform-style: preserve-3d; + width: 150px; + height: 100px; + border: 2px dotted green; } .shape { @@ -263,12 +263,15 @@ body { } @keyframes move { - 0%, 20% { + 0%, + 20% { offset-distance: 0%; } - 80%, 100% { + 80%, + 100% { offset-distance: 100%; } +} ``` ```html hidden @@ -294,8 +297,10 @@ body { </div> </div> -<pre>offset-path: ray(120deg sides contain); -offset-rotate: 0deg;</pre> +<pre> +offset-path: ray(120deg sides contain); +offset-rotate: 0deg; +</pre> <div> <div class="container"> @@ -305,7 +310,8 @@ offset-rotate: 0deg;</pre> <pre> offset-position: auto; - offset-path: ray(120deg closest-corner)</pre> + offset-path: ray(120deg closest-corner); +</pre> <div> <div class="container"> @@ -315,8 +321,8 @@ offset-rotate: 0deg;</pre> <pre> offset-position: auto; - offset-path: ray(120deg farthest-corner)</pre> -</div> + offset-path: ray(120deg farthest-corner); +</pre> ``` #### Result diff --git a/files/en-us/web/css/reading-flow/index.md b/files/en-us/web/css/reading-flow/index.md new file mode 100644 index 000000000000000..411dde4658241eb --- /dev/null +++ b/files/en-us/web/css/reading-flow/index.md @@ -0,0 +1,293 @@ +--- +title: reading-flow +slug: Web/CSS/reading-flow +page-type: css-property +status: + - experimental +browser-compat: css.properties.reading-flow +--- + +{{CSSRef}}{{SeeCompatTable}} + +The **`reading-flow`** [CSS](/en-US/docs/Web/CSS) property enables modifying the {{glossary("reading order")}} of child elements of a [block](/en-US/docs/Glossary/Block/CSS), [flex](/en-US/docs/Web/CSS/CSS_flexible_box_layout), or [grid](/en-US/docs/Web/CSS/CSS_grid_layout) layout. This affects the order in which they are rendered to speech and navigated to when using sequential navigation such as tabbing to links or buttons. + +## Syntax + +```css +/* Keyword values */ +reading-flow: normal; +reading-flow: flex-visual; +reading-flow: flex-flow; +reading-flow: grid-columns; +reading-flow: grid-rows; +reading-flow: grid-order; +reading-flow: source-order; + +/* Global values */ +reading-flow: inherit; +reading-flow: initial; +reading-flow: revert; +reading-flow: revert-layer; +reading-flow: unset; +``` + +### Value + +The `reading-flow` property takes one of the following keywords as its value: + +- `normal` + + - : The default value. The reading order follows the order of elements in the DOM. + +- `flex-visual` + + - : Only affects {{glossary("Flex Container", "flex containers")}}. The reading order follows the visual order of the `flex` items, taking the {{cssxref("writing-mode")}} into account. Therefore, a document in English with `flex-direction: row-reverse` and `reading-flow: flex-visual` set would have a reading order of left-to-right. + +- `flex-flow` + + - : Only affects flex containers. The reading order follows the {{cssxref("flex-flow")}} direction. + +- `grid-columns` + + - : Only affects {{glossary("Grid Container", "grid containers")}}. The reading order follows the visual order of grid items, column by column, taking the writing mode into account. + +- `grid-rows` + + - : Only affects grid containers. The reading order follows the visual order of grid items, row by row, taking the writing mode into account. + +- `grid-order` + + - : Only affects grid containers. if the {{cssxref("order")}} property is applied to any of the container's children, the reading order follows the modified item order. If the `order` property is not applied to the grid items, `grid-order` behaves as `normal`. + +- `source-order` + - : Affects grid, flex, and block containers. Has no effect on its own — the container's reading order continues to follow the order of elements in the DOM — but allows the reading order to be modified by setting the {{cssxref("reading-order")}} property on the container's children. + +## Description + +The `reading-flow` property modifies the {{glossary("reading order")}} of elements within a [block](/en-US/docs/Glossary/Block/CSS), [flex](/en-US/docs/Web/CSS/CSS_flexible_box_layout), or [grid](/en-US/docs/Web/CSS/CSS_grid_layout) container when set to a value other than `normal`. Such a container is referred to as a [reading flow container](/en-US/docs/Glossary/Reading_order#reading_flow_container). + +By default, web content is read out in DOM source order. Generally, the source order should express a sensible reading order for the content, and this should also be reflected by the visual order in the content layout. However, sometimes the visual order or tab order differs from the source order. For example, when applying multiple flexbox or grid layouts to a document via [media queries](/en-US/docs/Web/CSS/CSS_media_queries/Using_media_queries) to suit different device or user requirements, the content order may differ based on the viewport width. In such a case, the `reading-flow` can be used to ensure the reading and tabbing order reflect the visual order. + +In some cases you may wish to further fine-tune the reading order within a reading flow container. You can use {{cssxref("reading-order")}} property values on the container's children, putting them into ordinal groups which are then read out in numerical order. + +### Interaction with `tabindex` + +If a set of reading flow container child elements that are not normally focusable are made focusable with [`tabindex="0"`](/en-US/docs/Web/HTML/Reference/Global_attributes/tabindex) attributes, their reading order will be modified as expected by the `reading-flow` and `reading-order` properties, in just the same way as interactive elements such as {{htmlelement("a")}} or {{htmlelement("button")}}. + +However, any attempt to modify the tabbing order of a reading flow container's content using positive `tabindex` values will be ignored — overridden by the effects of `reading-flow` and `reading-order`. You generally shouldn't be using these anyway; see [Don't Use Tabindex Greater than 0](https://adrianroselli.com/2014/11/dont-use-tabindex-greater-than-0.html). The `reading-flow` and `reading-order` properties provide a much better way to modify tabbing order if required. + +## Formal definition + +{{cssinfo}} + +## Examples + +### Flex value comparison + +In this example, we demonstrate the effects of different `reading-flow` values on a flex container with reversed flex items. + +#### HTML + +The markup includes a {{htmlelement("select")}} element for selecting different `reading-flow` values, and a wrapper {{htmlelement("div")}} containing three {{htmlelement("a")}} elements. + +```html +<form> + <label for="reading-flow">Choose reading flow:</label> + <select id="reading-flow"> + <option>normal</option> + <option>flex-visual</option> + <option>flex-flow</option> + </select> +</form> +<div class="wrapper"> + <a href="#">Item 1</a> + <a href="#">Item 2</a> + <a href="#">Item 3</a> +</div> +``` + +#### CSS + +We use a {{cssxref("display")}} value of `flex` to turn the `<div>` into a flex container, and display the flex items in a row in reverse DOM order with a {{cssxref("flex-direction")}} value of `row-reverse`. Initially, we set a `reading-flow` of `normal` so the items are read or tabbed through in DOM source order. + +We also set an {{cssxref("order")}} value of `1` on the first `<a>` element to cause it to display after the second and third item in the flex flow. The resulting visual order of the flex items from left to right is "Item 1", "Item 3", then "Item 2", but the DOM order remains unchanged. + +```css +.wrapper { + display: flex; + flex-direction: row-reverse; + reading-flow: normal; + gap: 1em; +} + +a:first-child { + order: 1; +} +``` + +#### JavaScript + +In our script, we grab references to the `<select>` element and wrapper `<div>`, then add a [`change`](/en-US/docs/Web/API/HTMLElement/change_event) event listener to the `<select>` element. When a new value is selected, it is set as a `reading-flow` property value on the wrapper. + +```js +const selectElem = document.getElementById("reading-flow"); +const wrapperElem = document.querySelector(".wrapper"); + +selectElem.addEventListener("change", () => { + wrapperElem.style.readingFlow = selectElem.value; +}); +``` + +#### Result + +The demo renders like this: + +{{EmbedLiveSample('Flex value comparison', '', '100px')}} + +First, try tabbing through the links with `reading-flow: normal` set. The tabbing order is "Item 1", "Item 2", then "Item 3", as that is the order of the elements in the DOM. + +Now try changing the `reading-flow` value and tabbing through the links again: + +- A value of `flex-visual` causes the items to be tabbed through in the order "Item 1", "Item 3", then "Item 2", which is the visual display order resulting from the applied flexbox properties. +- A value of `flex-flow` causes the items to be tabbed through in the order "Item 2", "Item 3", then "Item 1", which matches the direction of the `flex-flow` — in this case, `row-reverse`. Here, the tabbing order is the reverse of the display order. + +### Grid value comparison + +In this example, we demonstrate the effects of different `reading-flow` values on a grid container. + +#### HTML + +The markup includes a {{htmlelement("select")}} element for selecting different `reading-flow` values, and a wrapper {{htmlelement("div")}} containing four {{htmlelement("a")}} elements. + +```html +<form> + <label for="reading-flow">Choose reading flow:</label> + <select id="reading-flow"> + <option>normal</option> + <option>grid-rows</option> + <option>grid-columns</option> + <option>grid-order</option> + </select> +</form> +<div class="wrapper"> + <a class="a" href="#">Item A</a> + <a class="b" href="#">Item B</a> + <a class="c" href="#">Item C</a> + <a class="d" href="#">Item D</a> +</div> +``` + +#### CSS + +We use a {{cssxref("display")}} value of `grid` to turn the `<div>` into a grid container, and display the grid items in three columns using {{cssxref("grid-template-columns")}}. We also set {{cssxref("grid-template-areas")}} to describe different placement areas in those columns, and place the `<a>` elements in those areas using {{cssxref("grid-area")}}. Initially, we set a `reading-flow` of `normal` so the items are read or tabbed through in the default DOM source order. + +Finally, we set an {{cssxref("order")}} value of `1` on the first `<a>` element; this has no effect on the layout because it does not override the grid area placement, but it does have an effect when a certain `reading-flow` value is set, as you'll se later on. + +Reading from left to right, the resulting display order of the grid items is "Item D", "Item B", "Item C", then "Item A". + +```css +.wrapper { + display: grid; + grid-template-columns: repeat(3, 150px); + grid-template-areas: + "d b b" + "c c a"; + reading-flow: normal; +} + +.a { + grid-area: a; +} +.b { + grid-area: b; +} +.c { + grid-area: c; +} +.d { + grid-area: d; +} + +a:first-child { + order: 1; +} +``` + +#### JavaScript + +In our script, we grab references to the `<select>` element and wrapper `<div>`, then add a [`change`](/en-US/docs/Web/API/HTMLElement/change_event) event listener to the `<select>` element. When a new value is selected, it is set as a `reading-flow` property value on the wrapper. + +```js +const selectElem = document.getElementById("reading-flow"); +const wrapperElem = document.querySelector(".wrapper"); + +selectElem.addEventListener("change", () => { + wrapperElem.style.readingFlow = selectElem.value; +}); +``` + +#### Result + +The demo renders like this: + +{{EmbedLiveSample('Grid value comparison', '', '100px')}} + +First, try tabbing through the links with `reading-flow: normal` set. The tabbing order is "Item A", "Item B", "Item C", and "Item D", as that is the order of the elements in the DOM. + +Now change the `reading-flow` value and then try tabbing through the links again: + +- A value of `grid-rows` causes the items to be tabbed through in the visual display order by row. This is "Item D", "Item B", "Item C", then "Item A". +- A value of `grid-columns` causes the items to be tabbed through in the visual display order by column. This is "Item D", "Item C", "Item B", then "Item A". +- A value of `grid-order` causes the items to be tabbed through in DOM order, but takes into account any `order` value changes. Since we have `order: 1;` set on the first `<a>` element, the tabbing order is "Item B", "Item C", "Item D", then "Item A". + +### Reading order adjustment on block containers + +In this example, we demonstrate the effects of the `reading-flow: source-order` value on a block container. + +#### HTML + +The markup includes a wrapper {{htmlelement("div")}} containing four {{htmlelement("a")}} elements. + +```html +<div class="wrapper"> + <a class="a" href="#">Item A</a> + <a class="b" href="#">Item B</a> + <a class="c" href="#">Item C</a> + <a class="d" href="#">Item D</a> +</div> +``` + +#### CSS + +We set a `reading-flow` of `source-order` so the items are read or tabbed through in DOM source order, but modifications are allowed to the reading order via {{cssxref("reading-order")}}. We set a `reading-order` value of `1` on the first `<a>` element. + +```css +.wrapper { + reading-flow: source-order; +} + +a:first-child { + reading-order: 1; +} +``` + +#### Result + +The demo renders like this: + +{{EmbedLiveSample('Reading flow adjustment on block containers', '', '100px')}} + +Try tabbing through the links: the tabbing order is "Item B", "Item C", "Item D", then "Item A" — the order of the elements in the DOM is followed, but Item A has been put in a higher reading order ordinal group than the others (the default `reading-order` value is `0`), therefore it is tabbed to last. + +## Specifications + +{{Specifications}} + +## Browser compatibility + +{{Compat}} + +## See also + +- {{cssxref("reading-order")}} +- [CSS `reading-flow` examples](https://chrome.dev/reading-flow-examples/) via chrome.dev diff --git a/files/en-us/web/css/reading-order/index.md b/files/en-us/web/css/reading-order/index.md new file mode 100644 index 000000000000000..f171710cb4839dc --- /dev/null +++ b/files/en-us/web/css/reading-order/index.md @@ -0,0 +1,159 @@ +--- +title: reading-order +slug: Web/CSS/reading-order +page-type: css-property +status: + - experimental +browser-compat: css.properties.reading-order +--- + +{{CSSRef}}{{SeeCompatTable}} + +The **`reading-order`** [CSS](/en-US/docs/Web/CSS) property enables changing the order in which a child of a [reading flow container](/en-US/docs/Glossary/Reading_order#reading_flow_container) is read relative to its element siblings. + +## Syntax + +```css +/* <integer> values */ +reading-order: 1; +reading-order: -1; + +/* Global values */ +reading-order: inherit; +reading-order: initial; +reading-order: revert; +reading-order: revert-layer; +reading-order: unset; +``` + +### Value + +- {{cssxref("&lt;integer&gt;")}} + - : Represents the ordinal group the element belongs to. + +## Description + +When an element's [block](/en-US/docs/Glossary/Block/CSS), [flex](/en-US/docs/Web/CSS/CSS_flexible_box_layout), or [grid](/en-US/docs/Web/CSS/CSS_grid_layout) parent container has a {{cssxref("reading-flow")}} property set to a value other than `normal`, the `reading-order` property can be used to set the element's [reading flow](/en-US/docs/Glossary/Reading_order#reading_flow) position relative to that of its siblings. + +For reading and navigation, elements inside a block, flex, or grid container are sorted by ascending `reading-order` value. If multiple siblings have the same `reading-order` value, those items are sorted according to the container's `reading-flow`. Siblings not given an explicit `reading-order` value are assigned the default value of `0`, which puts all the children of a reading flow container in the same ordinal group by default. + +Sibling elements are ordered starting from the lowest numbered ordinal group to the highest. Therefore, to cause an element to be read out after its siblings, you could set a `reading-order` value or `1` or more on it. To cause an element to be read out before its siblings, you could set a `reading-order` value or `-1` or less on it. + +The `reading-order` defines the reading and tabbing order, but has no effect on visual order. + +### Interaction with `tabindex` + +If a set of reading flow container child elements that are not normally focusable are made focusable with [`tabindex="0"`](/en-US/docs/Web/HTML/Reference/Global_attributes/tabindex) attributes, their reading order will be modified as expected by the `reading-flow` and `reading-order` properties, in just the same way as interactive elements such as {{htmlelement("a")}} or {{htmlelement("button")}}. + +However, any attempt to modify the tabbing order of a reading flow container's content using positive `tabindex` values will be ignored — overridden by the effects of `reading-flow` and `reading-order`. You generally shouldn't be using these anyway; see [Don't Use Tabindex Greater than 0](https://adrianroselli.com/2014/11/dont-use-tabindex-greater-than-0.html). The `reading-flow` and `reading-order` properties provide a much better way to modify tabbing order if required. + +## Formal definition + +{{cssinfo}} + +## Examples + +### Grid row order + +This example demonstrates using `reading-order` to control the positions of individual grid items within a grid container's reading order. One grid item has a `reading-order` value that is lower than the default `0`, so will be read out before its sibling elements. Another has a higher `reading-order` value set, so will be read out after the others, regardless of source or display order. + +#### HTML + +In our markup we have six {{htmlelement("a")}} elements contained inside a wrapper {{htmlelement("div")}}. + +```html +<div class="wrapper"> + <a href="#">Item 1</a> + <a class="bottom" href="#">Item 2</a> + <a href="#">Item 3</a> + <a class="top" href="#">Item 4</a> + <a href="#">Item 5</a> + <a href="#">Item 6</a> +</div> +``` + +#### CSS + +On the `<div>`, we set the [grid-auto-flow](/en-US/docs/Web/CSS/grid-auto-flow) property to `dense`, therefore items may display out of source order. The `reading-order` property on the `<a>` element with a class of `top` is set to `-1`, therefore "Item 4" will be the first item in reading flow. The `reading-order` property on the `<a>` element with a class of `bottom` is set to `21`, therefore "Item 4" will be the last item in the reading order. The remaining items will be visited in between, in grid row order, as the `<div>` element's {{cssxref("reading-flow")}} property is set to [grid-rows](/en-US/docs/Web/CSS/grid-row). + +```css +.wrapper { + display: grid; + grid-template-columns: repeat(3, 150px); + grid-auto-flow: dense; + reading-flow: grid-rows; +} + +.top { + reading-order: -1; +} + +.bottom { + reading-order: 21; +} +``` + +#### Result + +The above demo renders as follows: + +{{EmbedLiveSample('Grid row order', '100%', '100px')}} + +Try tabbing through the links. Note how "Item 4" is tabbed to first and "Item 2" is tabbed to last because of their modified `reading-order` values. In between, the items are tabbed to in grid row order. + +### Source order override + +In this example, the odd-numbered items have a lower `reading-order` value set, so will be read out before the others in a group, regardless of source or display order. + +#### HTML + +In our markup, we have five `<a>` elements contained inside a wrapper {{htmlelement("div")}}. + +```html +<div class="wrapper"> + <a href="#">Item 1</a> + <a href="#">Item 2</a> + <a href="#">Item 3</a> + <a href="#">Item 4</a> + <a href="#">Item 5</a> +</div> +``` + +#### CSS + +The `<div>` element's `reading-flow` property is set to `source-order`, which allows `reading-order` to be used to override the default source reading order. The odd-numbered `<a>` elements have a `reading-order` value of `-1`, therefore they are read out before the even-numbered items. + +```css +.wrapper { + reading-flow: source-order; +} + +.wrapper > a { + display: block; +} + +.wrapper a:nth-child(odd) { + reading-order: -1; +} +``` + +#### Result + +The above demo renders as follows: + +{{EmbedLiveSample('Source order override', '100%', '100px')}} + +Try tabbing through the links, and note how "Item 1", "Item 3", and "Item 5" are tabbed to first because of their modified `reading-order`. After that, the items are tabbed to in source order. + +## Specifications + +{{Specifications}} + +## Browser compatibility + +{{Compat}} + +## See also + +- {{cssxref("reading-flow")}} +- [CSS `reading-flow` examples](https://chrome.dev/reading-flow-examples/) via chrome.dev diff --git a/files/en-us/web/css/reference/index.md b/files/en-us/web/css/reference/index.md index 6e9b0266f339b10..2baa754213383c7 100644 --- a/files/en-us/web/css/reference/index.md +++ b/files/en-us/web/css/reference/index.md @@ -12,7 +12,7 @@ Use this **CSS reference** to browse an [alphabetical index](#index) of all of t ### Style rule syntax -```css +```plain style-rule ::= selectors-list { properties-list @@ -21,7 +21,7 @@ style-rule ::= Where: -```css +```plain selectors-list ::= selector[:pseudo-class] [::pseudo-element] [, selectors-list] @@ -118,28 +118,28 @@ Combinators are selectors that establish a relationship between two or more simp - [Shorthand properties](/en-US/docs/Web/CSS/CSS_cascade/Shorthand_properties) - [Specificity](/en-US/docs/Web/CSS/CSS_cascade/Specificity) - [Value definition syntax](/en-US/docs/Web/CSS/CSS_Values_and_Units/Value_definition_syntax) -- [CSS values and units](/en-US/docs/Web/CSS/CSS_Values_and_Units/) +- [CSS values and units](/en-US/docs/Web/CSS/CSS_Values_and_Units) - [CSS functional notations](/en-US/docs/Web/CSS/CSS_Values_and_Units/CSS_Value_Functions) ### Values -- [Actual value](/en-US/docs/Web/CSS/CSS_cascade/actual_value) -- [Computed value](/en-US/docs/Web/CSS/CSS_cascade/computed_value) -- [Initial value](/en-US/docs/Web/CSS/CSS_cascade/initial_value) -- [Resolved value](/en-US/docs/Web/CSS/resolved_value) -- [Specified value](/en-US/docs/Web/CSS/CSS_cascade/specified_value) -- [Used value](/en-US/docs/Web/CSS/CSS_cascade/used_value) +- [Actual value](/en-US/docs/Web/CSS/CSS_cascade/Value_processing#actual_value) +- [Computed value](/en-US/docs/Web/CSS/CSS_cascade/Value_processing#computed_value) +- [Initial value](/en-US/docs/Web/CSS/CSS_cascade/Value_processing#initial_value) +- [Resolved value](/en-US/docs/Web/CSS/CSS_cascade/Value_processing#resolved_value) +- [Specified value](/en-US/docs/Web/CSS/CSS_cascade/Value_processing#specified_value) +- [Used value](/en-US/docs/Web/CSS/CSS_cascade/Value_processing#used_value) ### Layout - [Block formatting context](/en-US/docs/Web/CSS/CSS_display/Block_formatting_context) - [Box model](/en-US/docs/Web/CSS/CSS_box_model/Introduction_to_the_CSS_box_model) - [Containing block](/en-US/docs/Web/CSS/CSS_display/Containing_block) -- [Layout mode](/en-US/docs/Web/CSS/Layout_mode) +- [Layout mode](/en-US/docs/Glossary/Layout_mode) - [Margin collapsing](/en-US/docs/Web/CSS/CSS_box_model/Mastering_margin_collapsing) -- [Replaced elements](/en-US/docs/Web/CSS/Replaced_element) -- [Stacking context](/en-US/docs/Web/CSS/CSS_positioned_layout/Understanding_z-index/Stacking_context) -- [Visual formatting model](/en-US/docs/Web/CSS/Visual_formatting_model) +- {{glossary("Replaced elements")}} +- [Stacking context](/en-US/docs/Web/CSS/CSS_positioned_layout/Stacking_context) +- [Visual formatting model](/en-US/docs/Web/CSS/CSS_display/Visual_formatting_model) ## DOM-CSS / CSSOM diff --git a/files/en-us/web/css/repeat/index.md b/files/en-us/web/css/repeat/index.md index 59c49749229f8b4..3879eea48eb595a 100644 --- a/files/en-us/web/css/repeat/index.md +++ b/files/en-us/web/css/repeat/index.md @@ -9,7 +9,52 @@ browser-compat: css.properties.grid-template-columns.repeat The **`repeat()`** [CSS](/en-US/docs/Web/CSS) [function](/en-US/docs/Web/CSS/CSS_Values_and_Units/CSS_Value_Functions) represents a repeated fragment of the [track list](/en-US/docs/Web/CSS/CSS_grid_layout/Basic_concepts_of_grid_layout), allowing a large number of columns or rows that exhibit a recurring pattern to be written in a more compact form. -{{EmbedInteractiveExample("pages/css/function-repeat.html")}} +{{InteractiveExample("CSS Demo: repeat()")}} + +```css interactive-example-choice +grid-template-columns: repeat(2, 60px); +``` + +```css interactive-example-choice +grid-template-columns: 1fr repeat(2, 60px); +``` + +```css interactive-example-choice +grid-template-columns: repeat(2, 20px 1fr); +``` + +```css interactive-example-choice +grid-template-columns: repeat(auto-fill, 40px); +``` + +```html interactive-example +<section class="default-example" id="default-example"> + <div class="example-container"> + <div class="transition-all" id="example-element"> + <div></div> + <div></div> + <div></div> + <div></div> + <div></div> + </div> + </div> +</section> +``` + +```css interactive-example +#example-element { + border: 1px solid #c5c5c5; + display: grid; + grid-auto-rows: 40px; + grid-gap: 10px; + width: 220px; +} + +#example-element > div { + background-color: rgba(0, 0, 255, 0.2); + border: 3px solid blue; +} +``` This function can be used in the CSS grid properties {{cssxref("grid-template-columns")}} and {{cssxref("grid-template-rows")}}. diff --git a/files/en-us/web/css/replaced_element/index.md b/files/en-us/web/css/replaced_element/index.md deleted file mode 100644 index d515203a0fba296..000000000000000 --- a/files/en-us/web/css/replaced_element/index.md +++ /dev/null @@ -1,71 +0,0 @@ ---- -title: Replaced elements -slug: Web/CSS/Replaced_element -page-type: guide ---- - -{{CSSRef}} - -In [CSS](/en-US/docs/Web/CSS), a **replaced element** is an element whose representation is outside the scope of CSS; they're external objects whose representation is independent of the CSS formatting model. - -Put in simpler terms, they're elements whose contents are not affected by the current document's styles. The position of the replaced element can be affected using CSS, but not the contents of the replaced element itself. Some replaced elements, such as {{HTMLElement("iframe")}} elements, may have stylesheets of their own, but they don't inherit the styles of the parent document. - -The only other impact CSS can have on a replaced element is that there are properties which support controlling the positioning of the element's content within its box. See [Controlling object position within the content box](#controlling_object_position_within_the_content_box) for further information. - -## Replaced elements - -Typical replaced elements are: - -- {{HTMLElement("img")}} -- {{HTMLElement("video")}} -- {{HTMLElement("iframe")}} -- {{HTMLElement("embed")}} -- {{HTMLElement("fencedframe")}} - -Some elements are treated as replaced elements only in specific cases: - -- {{HTMLElement("option")}} -- {{HTMLElement("audio")}} -- {{HTMLElement("canvas")}} -- {{HTMLElement("object")}} - -HTML spec also says that an {{HTMLElement("input")}} element can be replaced, because {{HTMLElement("input")}} elements of the `"image"` type are replaced elements similar to {{HTMLElement("img")}}. However, other form controls, including other types of {{HTMLElement("input")}} elements, are explicitly listed as non-replaced elements (the spec describes their default platform-specific rendering with the term "Widgets"). - -Objects inserted using the CSS {{cssxref("content")}} property are _anonymous replaced elements_. They are "anonymous" because they don't exist in the HTML markup. - -## Using CSS with replaced elements - -CSS handles replaced elements specifically in some cases, like when calculating margins and some `auto` values. - -Note that some replaced elements, but not all, have intrinsic dimensions or a defined baseline, which is used by some CSS properties, such as {{cssxref("vertical-align")}}. Only replaced elements can ever have intrinsic dimensions. - -### Controlling object position within the content box - -Certain CSS properties can be used to specify how the object contained within the replaced element should be positioned within the element's box area. These are defined by the [CSS Images](https://drafts.csswg.org/css-images/) specification: - -- {{cssxref("object-fit")}} - - : Specifies how the replaced element's content object should be fitted to the containing element's box. The `object-fit` property has no effect on {{HTMLElement("iframe")}}, {{HTMLElement("embed")}}, and {{HTMLElement("fencedframe")}} elements. -- {{cssxref("object-position")}} - - : Specifies the alignment of the replaced element's content object within the element's box. - -## See also - -- [HTML Spec](https://html.spec.whatwg.org/multipage/rendering.html#replaced-elements) -- {{glossary("void element", "Void elements")}} -- CSS key concepts: - - [CSS syntax](/en-US/docs/Web/CSS/CSS_syntax/Syntax) - - [At-rules](/en-US/docs/Web/CSS/CSS_syntax/At-rule) - - [Comments](/en-US/docs/Web/CSS/CSS_syntax/Comments) - - [Specificity](/en-US/docs/Web/CSS/CSS_cascade/Specificity) - - [Inheritance](/en-US/docs/Web/CSS/CSS_cascade/Inheritance) - - [Box model](/en-US/docs/Web/CSS/CSS_box_model/Introduction_to_the_CSS_box_model) - - [Layout modes](/en-US/docs/Web/CSS/Layout_mode) - - [Visual formatting model](/en-US/docs/Web/CSS/Visual_formatting_model) - - [Margin collapsing](/en-US/docs/Web/CSS/CSS_box_model/Mastering_margin_collapsing) - - Values - - [Initial values](/en-US/docs/Web/CSS/CSS_cascade/initial_value) - - [Computed values](/en-US/docs/Web/CSS/CSS_cascade/computed_value) - - [Used values](/en-US/docs/Web/CSS/CSS_cascade/used_value) - - [Actual values](/en-US/docs/Web/CSS/CSS_cascade/actual_value) - - [Value definition syntax](/en-US/docs/Web/CSS/CSS_Values_and_Units/Value_definition_syntax) - - [Shorthand properties](/en-US/docs/Web/CSS/CSS_cascade/Shorthand_properties) diff --git a/files/en-us/web/css/resize/index.md b/files/en-us/web/css/resize/index.md index ffb8d08e38c3408..a75fb6ccb6cb1e1 100644 --- a/files/en-us/web/css/resize/index.md +++ b/files/en-us/web/css/resize/index.md @@ -9,7 +9,45 @@ browser-compat: css.properties.resize The **`resize`** [CSS](/en-US/docs/Web/CSS) property sets whether an element is resizable, and if so, in which directions. -{{EmbedInteractiveExample("pages/css/resize.html")}} +{{InteractiveExample("CSS Demo: resize")}} + +```css interactive-example-choice +resize: both; +``` + +```css interactive-example-choice +resize: horizontal; +``` + +```css interactive-example-choice +resize: vertical; +``` + +```css interactive-example-choice +resize: none; +``` + +```html interactive-example +<section class="default-example" id="default-example"> + <div id="example-element">Try resizing this element.</div> +</section> +``` + +```css interactive-example +#example-element { + background: linear-gradient(135deg, #0ff 0%, #0ff 94%, #fff 95%); + border: 3px solid #c5c5c5; + overflow: auto; + width: 250px; + height: 250px; + font-weight: bold; + color: #000; + display: flex; + align-items: center; + justify-content: center; + padding: 10px; +} +``` `resize` does not apply to the following: diff --git a/files/en-us/web/css/resolved_value/index.md b/files/en-us/web/css/resolved_value/index.md deleted file mode 100644 index 702091269e2542c..000000000000000 --- a/files/en-us/web/css/resolved_value/index.md +++ /dev/null @@ -1,34 +0,0 @@ ---- -title: Resolved value -slug: Web/CSS/resolved_value -page-type: guide -spec-urls: https://drafts.csswg.org/cssom/#resolved-values ---- - -{{CSSRef}} - -The **resolved value** of a [CSS](/en-US/docs/Web/CSS) property is the value after applying active stylesheets and resolving any basic computation those values may contain. The {{domxref("Window.getComputedStyle", "getComputedStyle()")}} method returns a live {{domxref("CSSStyleDeclaration")}} object containing the resolved values of all CSS properties applied to a specified element. - -Historically, `getComputedStyle()` returned the [computed value](/en-US/docs/Web/CSS/CSS_cascade/computed_value) of an element or pseudo-element. As CSS evolved, so did the concept of "computed value", but the values returned by `getComputedStyle()` had to remain the same for backward compatibility with deployed scripts. These values are the "resolved values". - -For most properties, the resolved value is the [computed value](/en-US/docs/Web/CSS/CSS_cascade/computed_value), but for a few legacy properties (including {{cssxref("width")}} and {{cssxref("height")}}), it is the [used value](/en-US/docs/Web/CSS/CSS_cascade/used_value). See the specification link below for some per-property details. - -## Specifications - -{{Specifications}} - -## See also - -- {{domxref("window.getComputedStyle")}} -- {{domxref("CSSStyleDeclaration.getPropertyValue")}} -- Values - - [Initial values](/en-US/docs/Web/CSS/CSS_cascade/initial_value) - - [Computed values](/en-US/docs/Web/CSS/CSS_cascade/computed_value) - - [Used values](/en-US/docs/Web/CSS/CSS_cascade/used_value) - - [Actual values](/en-US/docs/Web/CSS/CSS_cascade/actual_value) -- [CSS syntax](/en-US/docs/Web/CSS/CSS_syntax/Syntax) -- [At-rules](/en-US/docs/Web/CSS/CSS_syntax/At-rule) -- [Specificity](/en-US/docs/Web/CSS/CSS_cascade/Specificity) -- [Inheritance](/en-US/docs/Web/CSS/CSS_cascade/Inheritance) -- [Value definition syntax](/en-US/docs/Web/CSS/CSS_Values_and_Units/Value_definition_syntax) -- [Shorthand properties](/en-US/docs/Web/CSS/CSS_cascade/Shorthand_properties) diff --git a/files/en-us/web/css/revert-layer/index.md b/files/en-us/web/css/revert-layer/index.md index af9d95129bf4462..b766518dec48ca5 100644 --- a/files/en-us/web/css/revert-layer/index.md +++ b/files/en-us/web/css/revert-layer/index.md @@ -9,7 +9,7 @@ browser-compat: css.types.global_keywords.revert-layer The **`revert-layer`** [CSS-wide keyword](/en-US/docs/Web/CSS/CSS_Values_and_Units/CSS_data_types#css-wide_keywords) rolls back the value of a property in a [cascade layer](/en-US/docs/Web/CSS/@layer) to the value of the property in a CSS rule matching the element in a previous cascade layer. The value of a property with this keyword is recalculated as if no rules were specified on the target element in the current cascade layer. -If there is no other cascade layer to revert to for the matching CSS rule, the property value rolls back to the [computed value](/en-US/docs/Web/CSS/CSS_cascade/computed_value) derived from the current layer. Furthermore, if there is no matching CSS rule in the current layer, the property value for the element rolls back to the style defined in a previous [style origin](/en-US/docs/Glossary/Style_origin). +If there is no other cascade layer to revert to for the matching CSS rule, the property value rolls back to the [computed value](/en-US/docs/Web/CSS/CSS_cascade/Value_processing#computed_value) derived from the current layer. Furthermore, if there is no matching CSS rule in the current layer, the property value for the element rolls back to the style defined in a previous [style origin](/en-US/docs/Glossary/Style_origin). This keyword can be applied to any CSS property, including the CSS shorthand property {{cssxref("all")}}. diff --git a/files/en-us/web/css/revert/index.md b/files/en-us/web/css/revert/index.md index 1b4876f23593ebe..5808f9400ce5455 100644 --- a/files/en-us/web/css/revert/index.md +++ b/files/en-us/web/css/revert/index.md @@ -23,9 +23,9 @@ Revert will not affect rules applied to children of an element you reset (but wi > Revert is just a value. It is still possible to override the `revert` value using [specificity](/en-US/docs/Web/CSS/CSS_cascade/Specificity). > [!NOTE] -> The `revert` keyword is different from and should not be confused with the {{cssxref("initial")}} keyword, which uses the [initial value](/en-US/docs/Web/CSS/CSS_cascade/initial_value) defined on a per-property basis by the CSS specifications. In contrast, user-agent stylesheets set default values on the basis of CSS selectors. +> The `revert` keyword is different from and should not be confused with the {{cssxref("initial")}} keyword, which uses the [initial value](/en-US/docs/Web/CSS/CSS_cascade/Value_processing#initial_value) defined on a per-property basis by the CSS specifications. In contrast, user-agent stylesheets set default values on the basis of CSS selectors. > -> For example, the [initial value](/en-US/docs/Web/CSS/CSS_cascade/initial_value) for the [`display`](/en-US/docs/Web/CSS/display#formal_definition) property is `inline`, whereas a normal user-agent stylesheet sets the default {{cssxref("display")}} value of {{HTMLElement("div")}}s to `block`, of {{HTMLElement("table")}}s to `table`, etc. +> For example, the [initial value](/en-US/docs/Web/CSS/CSS_cascade/Value_processing#initial_value) for the [`display`](/en-US/docs/Web/CSS/display#formal_definition) property is `inline`, whereas a normal user-agent stylesheet sets the default {{cssxref("display")}} value of {{HTMLElement("div")}}s to `block`, of {{HTMLElement("table")}}s to `table`, etc. ## Examples diff --git a/files/en-us/web/css/right/index.md b/files/en-us/web/css/right/index.md index 00821f2d910dbdc..5f13a293969f943 100644 --- a/files/en-us/web/css/right/index.md +++ b/files/en-us/web/css/right/index.md @@ -9,7 +9,57 @@ browser-compat: css.properties.right The **`right`** [CSS](/en-US/docs/Web/CSS) property participates in specifying the horizontal position of a [positioned element](/en-US/docs/Web/CSS/position). This {{glossary("inset properties", "inset property")}} has no effect on non-positioned elements. -{{EmbedInteractiveExample("pages/css/right.html")}} +{{InteractiveExample("CSS Demo: right")}} + +```css interactive-example-choice +right: 0; +``` + +```css interactive-example-choice +right: 4em; +``` + +```css interactive-example-choice +right: 10%; +``` + +```css interactive-example-choice +right: 20px; +``` + +```html interactive-example +<section id="default-example"> + <div class="example-container"> + <div id="example-element">I am absolutely positioned.</div> + <p> + As much mud in the streets as if the waters had but newly retired from the + face of the earth, and it would not be wonderful to meet a Megalosaurus, + forty feet long or so, waddling like an elephantine lizard up Holborn + Hill. + </p> + </div> +</section> +``` + +```css interactive-example +.example-container { + border: 0.75em solid; + padding: 0.75em; + text-align: left; + position: relative; + width: 100%; + min-height: 200px; +} + +#example-element { + background-color: #264653; + border: 4px solid #ffb500; + color: white; + position: absolute; + width: 140px; + height: 60px; +} +``` ## Syntax @@ -53,9 +103,6 @@ right: unset; - for _absolutely positioned elements_, the position of the element is based on the {{Cssxref("left")}} property, while `width: auto` is treated as a width based on the content; or if `left` is also `auto`, the element is positioned where it should horizontally be positioned if it were a static element. - for _relatively positioned elements_, the distance of the element from its normal position is based on the {{Cssxref("left")}} property; or if `left` is also `auto`, the element is not moved horizontally at all. -- `inherit` - - : Specifies that the value is the same as the computed value from its parent element (which might not be its containing block). This computed value is then handled as if it were a {{cssxref("&lt;length&gt;")}}, {{cssxref("&lt;percentage&gt;")}}, or the `auto` keyword. - ## Description The effect of `right` depends on how the element is positioned (i.e., the value of the {{cssxref("position")}} property): diff --git a/files/en-us/web/css/rotate/index.md b/files/en-us/web/css/rotate/index.md index b0659766d8eb9be..1846329567b0837 100644 --- a/files/en-us/web/css/rotate/index.md +++ b/files/en-us/web/css/rotate/index.md @@ -9,7 +9,99 @@ browser-compat: css.properties.rotate The **`rotate`** [CSS](/en-US/docs/Web/CSS) property allows you to specify rotation transforms individually and independently of the {{CSSxRef("transform")}} property. This maps better to typical user interface usage, and saves having to remember the exact order of transform functions to specify in the `transform` property. -{{EmbedInteractiveExample("pages/css/rotate.html")}} +{{InteractiveExample("CSS Demo: rotate")}} + +```css interactive-example-choice +rotate: none; +``` + +```css interactive-example-choice +rotate: -45deg; +``` + +```css interactive-example-choice +rotate: z 45deg; +``` + +```css interactive-example-choice +rotate: x 45deg; +``` + +```css interactive-example-choice +rotate: y 45deg; +``` + +```css interactive-example-choice +rotate: 3 0.5 2 45deg; +``` + +```html interactive-example +<section class="default-example" id="default-example"> + <div class="transition-all" id="example-element"> + <div class="face front">1</div> + <div class="face back">2</div> + <div class="face right">3</div> + <div class="face left">4</div> + <div class="face top">5</div> + <div class="face bottom">6</div> + </div> +</section> +``` + +```css interactive-example +#default-example { + background: linear-gradient(skyblue, khaki); + perspective: 550px; +} + +#example-element { + width: 100px; + height: 100px; + transform-style: preserve-3d; +} + +.face { + display: flex; + align-items: center; + justify-content: center; + width: 100%; + height: 100%; + position: absolute; + backface-visibility: inherit; + font-size: 60px; + color: white; +} + +.front { + background: rgba(90, 90, 90, 0.7); + transform: translateZ(50px); +} + +.back { + background: rgba(0, 210, 0, 0.7); + transform: rotateY(180deg) translateZ(50px); +} + +.right { + background: rgba(210, 0, 0, 0.7); + transform: rotateY(90deg) translateZ(50px); +} + +.left { + background: rgba(0, 0, 210, 0.7); + transform: rotateY(-90deg) translateZ(50px); +} + +.top { + background: rgba(210, 210, 0, 0.7); + transform: rotateX(90deg) translateZ(50px); +} + +.bottom { + background: rgba(210, 0, 210, 0.7); + transform: rotateX(-90deg) translateZ(50px); +} +``` ## Syntax diff --git a/files/en-us/web/css/row-gap/index.md b/files/en-us/web/css/row-gap/index.md index 8fbfd12df0e155a..9a315ebe70a3924 100644 --- a/files/en-us/web/css/row-gap/index.md +++ b/files/en-us/web/css/row-gap/index.md @@ -11,7 +11,51 @@ The **`row-gap`** [CSS](/en-US/docs/Web/CSS) property sets the size of the gap ( Early versions of the specification called this property `grid-row-gap`, and to maintain compatibility with legacy websites, browsers will still accept `grid-row-gap` as an alias for `row-gap`. -{{EmbedInteractiveExample("pages/css/row-gap.html")}} +{{InteractiveExample("CSS Demo: row-gap")}} + +```css interactive-example-choice +row-gap: 0; +``` + +```css interactive-example-choice +row-gap: 1ch; +``` + +```css interactive-example-choice +row-gap: 1em; +``` + +```css interactive-example-choice +row-gap: 20px; +``` + +```html interactive-example +<section class="default-example" id="default-example"> + <div class="example-container"> + <div class="transition-all" id="example-element"> + <div>One</div> + <div>Two</div> + <div>Three</div> + <div>Four</div> + <div>Five</div> + </div> + </div> +</section> +``` + +```css interactive-example +#example-element { + border: 1px solid #c5c5c5; + display: grid; + grid-template-columns: 1fr 1fr; + width: 200px; +} + +#example-element > div { + background-color: rgba(0, 0, 255, 0.2); + border: 3px solid blue; +} +``` ## Syntax diff --git a/files/en-us/web/css/ruby-position/index.md b/files/en-us/web/css/ruby-position/index.md index b040ad4e0bf29cc..1a12fc13628d9c5 100644 --- a/files/en-us/web/css/ruby-position/index.md +++ b/files/en-us/web/css/ruby-position/index.md @@ -9,7 +9,27 @@ browser-compat: css.properties.ruby-position The **`ruby-position`** [CSS](/en-US/docs/Web/CSS) property defines the position of a ruby element relative to its base element. It can be positioned over the element (`over`), under it (`under`), or between the characters on their right side (`inter-character`). -{{EmbedInteractiveExample("pages/css/ruby-position.html")}} +{{InteractiveExample("CSS Demo: ruby-position")}} + +```css interactive-example-choice +ruby-position: over; +``` + +```css interactive-example-choice +ruby-position: under; +``` + +```html interactive-example +<section id="default-example"> + <ruby id="example-element"> 明日 <rp>(</rp><rt>Ashita</rt><rp>)</rp> </ruby> +</section> +``` + +```css interactive-example +#example-element { + font-size: 2em; +} +``` ## Syntax diff --git a/files/en-us/web/css/scale/index.md b/files/en-us/web/css/scale/index.md index 223a98e2f7aa681..af33014be6342a1 100644 --- a/files/en-us/web/css/scale/index.md +++ b/files/en-us/web/css/scale/index.md @@ -9,7 +9,97 @@ browser-compat: css.properties.scale The **`scale`** [CSS](/en-US/docs/Web/CSS) property allows you to specify scale transforms individually and independently of the {{CSSxRef("transform")}} property. This maps better to typical user interface usage, and saves having to remember the exact order of transform functions to specify in the `transform` value. -{{EmbedInteractiveExample("pages/css/scale.html")}} +{{InteractiveExample("CSS Demo: scale")}} + +```css interactive-example-choice +scale: none; +``` + +```css interactive-example-choice +scale: 1.5; +``` + +```css interactive-example-choice +scale: 1.7 50%; +``` + +```css interactive-example-choice +scale: 1 -1; +``` + +```css interactive-example-choice +scale: 1.2 1.2 2; +``` + +```html interactive-example +<section class="default-example" id="default-example"> + <div class="transition-all" id="example-element"> + <div class="face front">1</div> + <div class="face back">2</div> + <div class="face right">3</div> + <div class="face left">4</div> + <div class="face top">5</div> + <div class="face bottom">6</div> + </div> +</section> +``` + +```css interactive-example +#default-example { + background: linear-gradient(skyblue, khaki); + perspective: 800px; + perspective-origin: 150% 150%; +} + +#example-element { + width: 100px; + height: 100px; + perspective: 550px; + transform-style: preserve-3d; +} + +.face { + display: flex; + align-items: center; + justify-content: center; + width: 100%; + height: 100%; + position: absolute; + backface-visibility: inherit; + font-size: 60px; + color: white; +} + +.front { + background: rgba(90, 90, 90, 0.7); + transform: translateZ(50px); +} + +.back { + background: rgba(0, 210, 0, 0.7); + transform: rotateY(180deg) translateZ(50px); +} + +.right { + background: rgba(210, 0, 0, 0.7); + transform: rotateY(90deg) translateZ(50px); +} + +.left { + background: rgba(0, 0, 210, 0.7); + transform: rotateY(-90deg) translateZ(50px); +} + +.top { + background: rgba(210, 210, 0, 0.7); + transform: rotateX(90deg) translateZ(50px); +} + +.bottom { + background: rgba(210, 0, 210, 0.7); + transform: rotateX(-90deg) translateZ(50px); +} +``` ## Syntax diff --git a/files/en-us/web/css/scroll-behavior/index.md b/files/en-us/web/css/scroll-behavior/index.md index 0472c2bc1ceaaaa..73f403c10a3acaa 100644 --- a/files/en-us/web/css/scroll-behavior/index.md +++ b/files/en-us/web/css/scroll-behavior/index.md @@ -9,7 +9,59 @@ browser-compat: css.properties.scroll-behavior The **`scroll-behavior`** [CSS](/en-US/docs/Web/CSS) property sets the behavior for a scrolling box when scrolling is triggered by the navigation or CSSOM scrolling APIs. -{{EmbedInteractiveExample("pages/css/scroll-behavior.html")}} +{{InteractiveExample("CSS Demo: scroll-behavior")}} + +```css interactive-example-choice +scroll-behavior: auto; +``` + +```css interactive-example-choice +scroll-behavior: smooth; +``` + +```html interactive-example +<section id="default-example"> + <div class="container"> + <p class="nav"> + Scroll to: + <a href="#pageA">A</a> + <a href="#pageB">B</a> + <a href="#pageC">C</a> + </p> + <scroll-container id="example-element"> + <scroll-page id="pageA">A</scroll-page> + <scroll-page id="pageB">B</scroll-page> + <scroll-page id="pageC">C</scroll-page> + </scroll-container> + </div> +</section> +``` + +```css interactive-example +.container { + flex-direction: column; +} + +.nav a { + color: #009e5f; +} + +scroll-container { + border: 1px solid black; + display: block; + height: 200px; + overflow-y: scroll; + width: 200px; +} + +scroll-page { + align-items: center; + display: flex; + font-size: 5em; + height: 100%; + justify-content: center; +} +``` Note that any other scrolls, such as those performed by the user, are not affected by this property. When this property is specified on the root element, it applies to the viewport instead. This property specified on the `body` element will _not_ propagate to the viewport. diff --git a/files/en-us/web/css/scroll-margin-block-end/index.md b/files/en-us/web/css/scroll-margin-block-end/index.md index 6a1bf688122fc60..d9e64b181cc2e77 100644 --- a/files/en-us/web/css/scroll-margin-block-end/index.md +++ b/files/en-us/web/css/scroll-margin-block-end/index.md @@ -9,7 +9,67 @@ browser-compat: css.properties.scroll-margin-block-end The `scroll-margin-block-end` property defines the margin of the scroll snap area at the end of the block dimension that is used for snapping this box to the [snapport](/en-US/docs/Glossary/Scroll_snap#snapport). The scroll snap area is determined by taking the transformed border box, finding its rectangular bounding box (axis-aligned in the scroll container's coordinate space), then adding the specified outsets. -{{EmbedInteractiveExample("pages/css/scroll-margin-block-end.html")}} +{{InteractiveExample("CSS Demo: scroll-margin-block-end")}} + +```css interactive-example-choice +scroll-margin-block-end: 0; +``` + +```css interactive-example-choice +scroll-margin-block-end: 20px; +``` + +```css interactive-example-choice +scroll-margin-block-end: 2em; +``` + +```html interactive-example +<section class="default-example" id="default-example"> + <div class="scroller"> + <div>1</div> + <div id="example-element">2</div> + <div>3</div> + </div> + <div class="info">Scroll »</div> +</section> +``` + +```css interactive-example +.default-example .info { + inline-size: 100%; + padding: 0.5em 0; + font-size: 90%; + writing-mode: vertical-rl; +} + +.scroller { + text-align: left; + height: 250px; + width: 270px; + overflow-y: scroll; + display: flex; + flex-direction: column; + box-sizing: border-box; + border: 1px solid black; + scroll-snap-type: y mandatory; +} + +.scroller > div { + flex: 0 0 250px; + background-color: rebeccapurple; + color: #fff; + font-size: 30px; + display: flex; + align-items: center; + justify-content: center; + scroll-snap-align: end; +} + +.scroller > div:nth-child(even) { + background-color: #fff; + color: rebeccapurple; +} +``` ## Syntax diff --git a/files/en-us/web/css/scroll-margin-block-start/index.md b/files/en-us/web/css/scroll-margin-block-start/index.md index e7d8a81ba6d34ba..ae151c096bb0063 100644 --- a/files/en-us/web/css/scroll-margin-block-start/index.md +++ b/files/en-us/web/css/scroll-margin-block-start/index.md @@ -9,7 +9,67 @@ browser-compat: css.properties.scroll-margin-block-start The `scroll-margin-block-start` property defines the margin of the scroll snap area at the start of the block dimension that is used for snapping this box to the [snapport](/en-US/docs/Glossary/Scroll_snap#snapport). The scroll snap area is determined by taking the transformed border box, finding its rectangular bounding box (axis-aligned in the scroll container's coordinate space), then adding the specified outsets. -{{EmbedInteractiveExample("pages/css/scroll-margin-block-start.html")}} +{{InteractiveExample("CSS Demo: scroll-margin-block-start")}} + +```css interactive-example-choice +scroll-margin-block-start: 0; +``` + +```css interactive-example-choice +scroll-margin-block-start: 20px; +``` + +```css interactive-example-choice +scroll-margin-block-start: 2em; +``` + +```html interactive-example +<section class="default-example" id="default-example"> + <div class="scroller"> + <div>1</div> + <div id="example-element">2</div> + <div>3</div> + </div> + <div class="info">Scroll »</div> +</section> +``` + +```css interactive-example +.default-example .info { + inline-size: 100%; + padding: 0.5em 0; + font-size: 90%; + writing-mode: vertical-rl; +} + +.scroller { + text-align: left; + height: 250px; + width: 270px; + overflow-y: scroll; + display: flex; + flex-direction: column; + box-sizing: border-box; + border: 1px solid black; + scroll-snap-type: y mandatory; +} + +.scroller > div { + flex: 0 0 250px; + background-color: rebeccapurple; + color: #fff; + font-size: 30px; + display: flex; + align-items: center; + justify-content: center; + scroll-snap-align: start; +} + +.scroller > div:nth-child(even) { + background-color: #fff; + color: rebeccapurple; +} +``` ## Syntax diff --git a/files/en-us/web/css/scroll-margin-block/index.md b/files/en-us/web/css/scroll-margin-block/index.md index 97014f6c29e7cfb..d4a4e8df8f5fe30 100644 --- a/files/en-us/web/css/scroll-margin-block/index.md +++ b/files/en-us/web/css/scroll-margin-block/index.md @@ -9,7 +9,67 @@ browser-compat: css.properties.scroll-margin-block The `scroll-margin-block` [shorthand property](/en-US/docs/Web/CSS/CSS_cascade/Shorthand_properties) sets the scroll margins of an element in the block dimension. -{{EmbedInteractiveExample("pages/css/scroll-margin-block.html")}} +{{InteractiveExample("CSS Demo: scroll-margin-block")}} + +```css interactive-example-choice +scroll-margin-block: 0; +``` + +```css interactive-example-choice +scroll-margin-block: 20px; +``` + +```css interactive-example-choice +scroll-margin-block: 2em; +``` + +```html interactive-example +<section class="default-example" id="default-example"> + <div class="scroller"> + <div>1</div> + <div id="example-element">2</div> + <div>3</div> + </div> + <div class="info">Scroll »</div> +</section> +``` + +```css interactive-example +.default-example .info { + inline-size: 100%; + padding: 0.5em 0; + font-size: 90%; + writing-mode: vertical-rl; +} + +.scroller { + text-align: left; + height: 250px; + width: 270px; + overflow-y: scroll; + display: flex; + flex-direction: column; + box-sizing: border-box; + border: 1px solid black; + scroll-snap-type: y mandatory; +} + +.scroller > div { + flex: 0 0 250px; + background-color: rebeccapurple; + color: #fff; + font-size: 30px; + display: flex; + align-items: center; + justify-content: center; + scroll-snap-align: start; +} + +.scroller > div:nth-child(even) { + background-color: #fff; + color: rebeccapurple; +} +``` ## Constituent properties diff --git a/files/en-us/web/css/scroll-margin-bottom/index.md b/files/en-us/web/css/scroll-margin-bottom/index.md index 730bfa29d5f1b91..bcb68eab4babe5e 100644 --- a/files/en-us/web/css/scroll-margin-bottom/index.md +++ b/files/en-us/web/css/scroll-margin-bottom/index.md @@ -9,7 +9,67 @@ browser-compat: css.properties.scroll-margin-bottom The `scroll-margin-bottom` property defines the bottom margin of the scroll snap area that is used for snapping this box to the [snapport](/en-US/docs/Glossary/Scroll_snap#snapport). The scroll snap area is determined by taking the transformed border box, finding its rectangular bounding box (axis-aligned in the scroll container's coordinate space), then adding the specified outsets. -{{EmbedInteractiveExample("pages/css/scroll-margin-bottom.html")}} +{{InteractiveExample("CSS Demo: scroll-margin-bottom")}} + +```css interactive-example-choice +scroll-margin-bottom: 0; +``` + +```css interactive-example-choice +scroll-margin-bottom: 20px; +``` + +```css interactive-example-choice +scroll-margin-bottom: 2em; +``` + +```html interactive-example +<section class="default-example" id="default-example"> + <div class="scroller"> + <div>1</div> + <div id="example-element">2</div> + <div>3</div> + </div> + <div class="info">Scroll »</div> +</section> +``` + +```css interactive-example +.default-example .info { + inline-size: 100%; + padding: 0.5em 0; + font-size: 90%; + writing-mode: vertical-rl; +} + +.scroller { + text-align: left; + height: 250px; + width: 270px; + overflow-y: scroll; + display: flex; + flex-direction: column; + box-sizing: border-box; + border: 1px solid black; + scroll-snap-type: y mandatory; +} + +.scroller > div { + flex: 0 0 250px; + background-color: rebeccapurple; + color: #fff; + font-size: 30px; + display: flex; + align-items: center; + justify-content: center; + scroll-snap-align: end; +} + +.scroller > div:nth-child(even) { + background-color: #fff; + color: rebeccapurple; +} +``` ## Syntax diff --git a/files/en-us/web/css/scroll-margin-inline-end/index.md b/files/en-us/web/css/scroll-margin-inline-end/index.md index 8f4e3b5cb54e263..679bfee21d9d33d 100644 --- a/files/en-us/web/css/scroll-margin-inline-end/index.md +++ b/files/en-us/web/css/scroll-margin-inline-end/index.md @@ -9,7 +9,70 @@ browser-compat: css.properties.scroll-margin-inline-end The `scroll-margin-inline-end` property defines the margin of the scroll snap area at the end of the inline dimension that is used for snapping this box to the [snapport](/en-US/docs/Glossary/Scroll_snap#snapport). The scroll snap area is determined by taking the transformed border box, finding its rectangular bounding box (axis-aligned in the scroll container's coordinate space), then adding the specified outsets. -{{EmbedInteractiveExample("pages/css/scroll-margin-inline-end.html")}} +{{InteractiveExample("CSS Demo: scroll-margin-inline-end")}} + +```css interactive-example-choice +scroll-margin-inline-end: 0; +``` + +```css interactive-example-choice +scroll-margin-inline-end: 20px; +``` + +```css interactive-example-choice +scroll-margin-inline-end: 2em; +``` + +```html interactive-example +<section class="default-example" id="default-example"> + <div class="scroller"> + <div>1</div> + <div id="example-element">2</div> + <div>3</div> + </div> + <div class="info">Scroll »</div> +</section> +``` + +```css interactive-example +.default-example { + flex-wrap: wrap; +} + +.default-example .info { + width: 100%; + padding: 0.5em 0; + font-size: 90%; +} + +.scroller { + text-align: left; + width: 250px; + height: 250px; + overflow-x: scroll; + display: flex; + box-sizing: border-box; + border: 1px solid black; + scroll-snap-type: x mandatory; +} + +.scroller > div { + flex: 0 0 250px; + width: 250px; + background-color: rebeccapurple; + color: #fff; + font-size: 30px; + display: flex; + align-items: center; + justify-content: center; + scroll-snap-align: end; +} + +.scroller > div:nth-child(even) { + background-color: #fff; + color: rebeccapurple; +} +``` ## Syntax diff --git a/files/en-us/web/css/scroll-margin-inline-start/index.md b/files/en-us/web/css/scroll-margin-inline-start/index.md index c0400d5927de94b..0b501014175b25b 100644 --- a/files/en-us/web/css/scroll-margin-inline-start/index.md +++ b/files/en-us/web/css/scroll-margin-inline-start/index.md @@ -9,7 +9,70 @@ browser-compat: css.properties.scroll-margin-inline-start The `scroll-margin-inline-start` property defines the margin of the scroll snap area at the start of the inline dimension that is used for snapping this box to the [snapport](/en-US/docs/Glossary/Scroll_snap#snapport). The scroll snap area is determined by taking the transformed border box, finding its rectangular bounding box (axis-aligned in the scroll container's coordinate space), then adding the specified outsets. -{{EmbedInteractiveExample("pages/css/scroll-margin-inline-start.html")}} +{{InteractiveExample("CSS Demo: scroll-margin-inline-start")}} + +```css interactive-example-choice +scroll-margin-inline-start: 0; +``` + +```css interactive-example-choice +scroll-margin-inline-start: 20px; +``` + +```css interactive-example-choice +scroll-margin-inline-start: 2em; +``` + +```html interactive-example +<section class="default-example" id="default-example"> + <div class="scroller"> + <div>1</div> + <div id="example-element">2</div> + <div>3</div> + </div> + <div class="info">Scroll »</div> +</section> +``` + +```css interactive-example +.default-example { + flex-wrap: wrap; +} + +.default-example .info { + width: 100%; + padding: 0.5em 0; + font-size: 90%; +} + +.scroller { + text-align: left; + width: 250px; + height: 250px; + overflow-x: scroll; + display: flex; + box-sizing: border-box; + border: 1px solid black; + scroll-snap-type: x mandatory; +} + +.scroller > div { + flex: 0 0 250px; + width: 250px; + background-color: rebeccapurple; + color: #fff; + font-size: 30px; + display: flex; + align-items: center; + justify-content: center; + scroll-snap-align: start; +} + +.scroller > div:nth-child(even) { + background-color: #fff; + color: rebeccapurple; +} +``` ## Syntax diff --git a/files/en-us/web/css/scroll-margin-inline/index.md b/files/en-us/web/css/scroll-margin-inline/index.md index 3585965dcf2ec69..d606e742187debc 100644 --- a/files/en-us/web/css/scroll-margin-inline/index.md +++ b/files/en-us/web/css/scroll-margin-inline/index.md @@ -9,7 +9,74 @@ browser-compat: css.properties.scroll-margin-inline The `scroll-margin-inline` [shorthand property](/en-US/docs/Web/CSS/CSS_cascade/Shorthand_properties) sets the scroll margins of an element in the inline dimension. -{{EmbedInteractiveExample("pages/css/scroll-margin-inline.html")}} +{{InteractiveExample("CSS Demo: scroll-margin-inline")}} + +```css interactive-example-choice +scroll-margin-inline: 0; +``` + +```css interactive-example-choice +scroll-margin-inline: 40px 20px; +``` + +```css interactive-example-choice +scroll-margin-inline: 4em 0; +``` + +```css interactive-example-choice +scroll-margin-inline: 0px 3em; +``` + +```html interactive-example +<section class="default-example" id="default-example"> + <div class="scroller"> + <div>1</div> + <div id="example-element">2</div> + <div>3</div> + </div> + <div class="info">Scroll »</div> +</section> +``` + +```css interactive-example +.default-example { + flex-wrap: wrap; +} + +.default-example .info { + width: 100%; + padding: 0.5em 0; + font-size: 90%; +} + +.scroller { + text-align: left; + width: 250px; + height: 250px; + overflow-x: scroll; + display: flex; + box-sizing: border-box; + border: 1px solid black; + scroll-snap-type: x mandatory; +} + +.scroller > div { + flex: 0 0 250px; + width: 250px; + background-color: rebeccapurple; + color: #fff; + font-size: 30px; + display: flex; + align-items: center; + justify-content: center; + scroll-snap-align: end; +} + +.scroller > div:nth-child(even) { + background-color: #fff; + color: rebeccapurple; +} +``` ## Constituent properties diff --git a/files/en-us/web/css/scroll-margin-left/index.md b/files/en-us/web/css/scroll-margin-left/index.md index d74ebff94babf5d..a77b1baa9cad754 100644 --- a/files/en-us/web/css/scroll-margin-left/index.md +++ b/files/en-us/web/css/scroll-margin-left/index.md @@ -9,7 +9,70 @@ browser-compat: css.properties.scroll-margin-left The `scroll-margin-left` property defines the left margin of the scroll snap area that is used for snapping this box to the [snapport](/en-US/docs/Glossary/Scroll_snap#snapport). The scroll snap area is determined by taking the transformed border box, finding its rectangular bounding box (axis-aligned in the scroll container's coordinate space), then adding the specified outsets. -{{EmbedInteractiveExample("pages/css/scroll-margin-left.html")}} +{{InteractiveExample("CSS Demo: scroll-margin-left")}} + +```css interactive-example-choice +scroll-margin-left: 0; +``` + +```css interactive-example-choice +scroll-margin-left: 20px; +``` + +```css interactive-example-choice +scroll-margin-left: 2em; +``` + +```html interactive-example +<section class="default-example" id="default-example"> + <div class="scroller"> + <div>1</div> + <div id="example-element">2</div> + <div>3</div> + </div> + <div class="info">Scroll »</div> +</section> +``` + +```css interactive-example +.default-example { + flex-wrap: wrap; +} + +.default-example .info { + width: 100%; + padding: 0.5em 0; + font-size: 90%; +} + +.scroller { + text-align: left; + width: 250px; + height: 250px; + overflow-x: scroll; + display: flex; + box-sizing: border-box; + border: 1px solid black; + scroll-snap-type: x mandatory; +} + +.scroller > div { + flex: 0 0 250px; + width: 250px; + background-color: rebeccapurple; + color: #fff; + font-size: 30px; + display: flex; + align-items: center; + justify-content: center; + scroll-snap-align: start; +} + +.scroller > div:nth-child(even) { + background-color: #fff; + color: rebeccapurple; +} +``` ## Syntax diff --git a/files/en-us/web/css/scroll-margin-right/index.md b/files/en-us/web/css/scroll-margin-right/index.md index fb5ca5505773c08..2151fed7cce0c55 100644 --- a/files/en-us/web/css/scroll-margin-right/index.md +++ b/files/en-us/web/css/scroll-margin-right/index.md @@ -9,7 +9,70 @@ browser-compat: css.properties.scroll-margin-right The `scroll-margin-right` property defines the right margin of the scroll snap area that is used for snapping this box to the [snapport](/en-US/docs/Glossary/Scroll_snap#snapport). The scroll snap area is determined by taking the transformed border box, finding its rectangular bounding box (axis-aligned in the scroll container's coordinate space), then adding the specified outsets. -{{EmbedInteractiveExample("pages/css/scroll-margin-right.html")}} +{{InteractiveExample("CSS Demo: scroll-margin-right")}} + +```css interactive-example-choice +scroll-margin-right: 0; +``` + +```css interactive-example-choice +scroll-margin-right: 20px; +``` + +```css interactive-example-choice +scroll-margin-right: 2em; +``` + +```html interactive-example +<section class="default-example" id="default-example"> + <div class="scroller"> + <div>1</div> + <div id="example-element">2</div> + <div>3</div> + </div> + <div class="info">Scroll »</div> +</section> +``` + +```css interactive-example +.default-example { + flex-wrap: wrap; +} + +.default-example .info { + width: 100%; + padding: 0.5em 0; + font-size: 90%; +} + +.scroller { + text-align: left; + width: 250px; + height: 250px; + overflow-x: scroll; + display: flex; + box-sizing: border-box; + border: 1px solid black; + scroll-snap-type: x mandatory; +} + +.scroller > div { + flex: 0 0 250px; + width: 250px; + background-color: rebeccapurple; + color: #fff; + font-size: 30px; + display: flex; + align-items: center; + justify-content: center; + scroll-snap-align: end; +} + +.scroller > div:nth-child(even) { + background-color: #fff; + color: rebeccapurple; +} +``` ## Syntax diff --git a/files/en-us/web/css/scroll-margin-top/index.md b/files/en-us/web/css/scroll-margin-top/index.md index 8f7d2490f7a11ce..51de6feb0855d25 100644 --- a/files/en-us/web/css/scroll-margin-top/index.md +++ b/files/en-us/web/css/scroll-margin-top/index.md @@ -9,7 +9,67 @@ browser-compat: css.properties.scroll-margin-top The `scroll-margin-top` property defines the top margin of the scroll snap area that is used for snapping this box to the [snapport](/en-US/docs/Glossary/Scroll_snap#snapport). The scroll snap area is determined by taking the transformed border box, finding its rectangular bounding box (axis-aligned in the scroll container's coordinate space), then adding the specified outsets. -{{EmbedInteractiveExample("pages/css/scroll-margin-top.html")}} +{{InteractiveExample("CSS Demo: scroll-margin-top")}} + +```css interactive-example-choice +scroll-margin-top: 0; +``` + +```css interactive-example-choice +scroll-margin-top: 20px; +``` + +```css interactive-example-choice +scroll-margin-top: 2em; +``` + +```html interactive-example +<section class="default-example" id="default-example"> + <div class="scroller"> + <div>1</div> + <div id="example-element">2</div> + <div>3</div> + </div> + <div class="info">Scroll »</div> +</section> +``` + +```css interactive-example +.default-example .info { + inline-size: 100%; + padding: 0.5em 0; + font-size: 90%; + writing-mode: vertical-rl; +} + +.scroller { + text-align: left; + height: 250px; + width: 270px; + overflow-y: scroll; + display: flex; + flex-direction: column; + box-sizing: border-box; + border: 1px solid black; + scroll-snap-type: y mandatory; +} + +.scroller > div { + flex: 0 0 250px; + background-color: rebeccapurple; + color: #fff; + font-size: 30px; + display: flex; + align-items: center; + justify-content: center; + scroll-snap-align: start; +} + +.scroller > div:nth-child(even) { + background-color: #fff; + color: rebeccapurple; +} +``` ## Syntax diff --git a/files/en-us/web/css/scroll-margin/index.md b/files/en-us/web/css/scroll-margin/index.md index 19fb13436f54e81..9239a99a4487126 100644 --- a/files/en-us/web/css/scroll-margin/index.md +++ b/files/en-us/web/css/scroll-margin/index.md @@ -9,7 +9,67 @@ browser-compat: css.properties.scroll-margin The **`scroll-margin`** [shorthand property](/en-US/docs/Web/CSS/CSS_cascade/Shorthand_properties) sets all of the scroll margins of an element at once, assigning values much like the [`margin`](/en-US/docs/Web/CSS/margin) property does for margins of an element. -{{EmbedInteractiveExample("pages/css/scroll-margin.html")}} +{{InteractiveExample("CSS Demo: scroll-margin")}} + +```css interactive-example-choice +scroll-margin: 0; +``` + +```css interactive-example-choice +scroll-margin: 20px; +``` + +```css interactive-example-choice +scroll-margin: 2em; +``` + +```html interactive-example +<section class="default-example" id="default-example"> + <div class="scroller"> + <div>1</div> + <div id="example-element">2</div> + <div>3</div> + </div> + <div class="info">Scroll »</div> +</section> +``` + +```css interactive-example +.default-example .info { + inline-size: 100%; + padding: 0.5em 0; + font-size: 90%; + writing-mode: vertical-rl; +} + +.scroller { + text-align: left; + height: 250px; + width: 270px; + overflow-y: scroll; + display: flex; + flex-direction: column; + box-sizing: border-box; + border: 1px solid black; + scroll-snap-type: y mandatory; +} + +.scroller > div { + flex: 0 0 250px; + background-color: rebeccapurple; + color: #fff; + font-size: 30px; + display: flex; + align-items: center; + justify-content: center; + scroll-snap-align: start; +} + +.scroller > div:nth-child(even) { + background-color: #fff; + color: rebeccapurple; +} +``` ## Constituent properties diff --git a/files/en-us/web/css/scroll-marker-group/index.md b/files/en-us/web/css/scroll-marker-group/index.md new file mode 100644 index 000000000000000..aa2c445e71a99c5 --- /dev/null +++ b/files/en-us/web/css/scroll-marker-group/index.md @@ -0,0 +1,190 @@ +--- +title: scroll-marker-group +slug: Web/CSS/scroll-marker-group +page-type: css-property +status: + - experimental +browser-compat: css.properties.scroll-marker-group +--- + +{{CSSRef}}{{seecompattable}} + +The **`scroll-marker-group`** [CSS](/en-US/docs/Web/CSS) property controls whether a {{glossary("scroll container")}} has a {{cssxref("::scroll-marker-group")}} pseudo-element generated and, if so, whether it should be placed immediately `before` _or_ `after` the container's contents in the default visual and tabbing order. + +## Syntax + +```css +/* Single values */ +scroll-marker-group: before; +scroll-marker-group: after; +scroll-marker-group: none; + +/* Global values */ +scroll-marker-group: inherit; +scroll-marker-group: initial; +scroll-marker-group: revert; +scroll-marker-group: revert-layer; +scroll-marker-group: unset; +``` + +### Values + +- `after` + + - : A {{cssxref("::scroll-marker-group")}} pseudo-element is generated as a sibling of the scroll container's child DOM elements, immediately preceding them, and any generated {{cssxref("::scroll-button()")}} pseudo-elements. It appears at the end of the container's tab order and layout box order (but not DOM structure). + +- `before` + + - : A `::scroll-marker-group` pseudo-element is generated as a sibling of the scroll container's child DOM elements, immediately preceding them, and any generated {{cssxref("::scroll-button()")}} pseudo-elements. The scroll marker group appears at the start of the container's tab order and layout box order. + +- `none` + + - : No `::scroll-marker-group` pseudo-element will be generated on the element. This is the default value. + +> [!NOTE] +> It is a best practice to match the visual rendering position of the scroll marker group with the tab order. When positioning the marker group at the start of the content with styles applied to {{cssxref("::scroll-marker-group")}}, put it at the beginning of the tab order using `before`. When positioning the group at the end of the content, put it at the end of the tab order using `after`. + +## Formal definition + +{{cssinfo}} + +## Formal syntax + +{{csssyntax}} + +## Examples + +See [Creating CSS carousels](/en-US/docs/Web/CSS/CSS_overflow/CSS_carousels) for full examples that use the `scroll-marker-group` property. + +### Placement of the scroll markers + +In this example, we demonstrate the three values of the `scroll-marker-group` property. + +#### HTML + +We have a basic HTML {{htmlelement("ul")}} list with several {{htmlelement("li")}} list items. + +```html hidden +<fieldset> + <legend>Select <code>scroll-marker-group</code> value:</legend> + <label><input type="radio" name="p" value="before" />before</label> + <label><input type="radio" name="p" value="after" checked />after</label> + <label><input type="radio" name="p" value="none" />none</label> +</fieldset> +``` + +```html +<ul> + <li>Item 1</li> + <li>Item 2</li> + <li>Item 3</li> + <li>Item 4</li> + <li>Item 5</li> + <li>Item 6</li> + <li>Item 7</li> + <li>Item 8</li> +</ul> +``` + +#### CSS + +We convert our `<ul>` into a carousel by setting the {{cssxref("display")}} to `flex`, creating a single, non-wrapping row of `<li>` elements. The {{cssxref("overflow-x")}} property is set to `auto`, meaning if the items overflow their container on the x-axis, the content will scroll horizontally. We then convert the `<ul>` into a [scroll-snap container](/en-US/docs/Glossary/Scroll_snap#scroll_snap_container), ensuring that items always snap into place when the container is scrolled with a {{cssxref("scroll-snap-type")}} value of `mandatory`. + +We create a scroll marker group with the `scroll-marker-group` property, placing the group after all the content. + +```css +ul { + display: flex; + gap: 4vw; + padding-left: 0; + margin: 32px 0; + overflow-x: auto; + overscroll-behavior-x: contain; + scroll-snap-type: x mandatory; + + scroll-marker-group: after; +} +``` + +Next, we style the `<li>` elements, using the {{cssxref("flex")}} property to make them `33%` of the width of the container. The {{cssxref("scroll-snap-align")}} value of `start` makes the left-hand side of the left-most visible item snap to the left edge of the container when the content is scrolled. + +```css +li { + list-style-type: none; + background-color: #eee; + flex: 0 0 33%; + scroll-snap-align: start; + text-align: center; + line-height: 5; +} +``` + +We then use the {{cssxref("::scroll-marker")}} pseudo-element to create a square marker for each list item with a red border, and apply styles to the {{cssxref("::scroll-marker-group")}} pseudo-element to lay out the scroll markers in a row with a `0.2em` gap between each one. + +```css +li::scroll-marker { + content: " "; + border: 1px solid red; + height: 1em; + width: 1em; +} + +::scroll-marker-group { + display: flex; + gap: 0.2em; +} +``` + +Finally, to ensure good user experience, we style the marker of the currently-scrolled element differently from the others, targeting the marker with the {{cssxref(":target-current")}} pseudoclass. + +```css +::scroll-marker:target-current { + background: red; +} +``` + +```css hidden +fieldset { + width: 20em; +} + +label { + font-family: monospace; + display: block; +} + +:has([value="before"]:checked) ul { + scroll-marker-group: before; +} +:has([value="after"]:checked) ul { + scroll-marker-group: after; +} + +:has([value="none"]:checked) ul { + scroll-marker-group: none; +} +``` + +#### Result + +{{EmbedLiveSample("Examples", '', '300')}} + +Note the placement of the scroll marker group. Check out how the keyboard tabbing order is different for `before` versus `after`, and note how the group disappears when the value is set to `none`. + +## Specifications + +{{Specifications}} + +## Browser compatibility + +{{Compat}} + +## See also + +- {{cssxref("::scroll-button()")}} +- {{cssxref("::scroll-marker-group")}} +- {{cssxref("::scroll-marker")}} +- {{cssxref(":target-current")}} +- [Creating CSS carousels](/en-US/docs/Web/CSS/CSS_overflow/CSS_carousels) +- [CSS overflow](/en-US/docs/Web/CSS/CSS_overflow) module +- [CSS Carousel Gallery](https://chrome.dev/carousel/) via chrome.dev (2025) diff --git a/files/en-us/web/css/scroll-padding-block-end/index.md b/files/en-us/web/css/scroll-padding-block-end/index.md index 9134ae8a8b3c96c..e4b49555ce036d1 100644 --- a/files/en-us/web/css/scroll-padding-block-end/index.md +++ b/files/en-us/web/css/scroll-padding-block-end/index.md @@ -9,7 +9,67 @@ browser-compat: css.properties.scroll-padding-block-end The `scroll-padding-block-end` property defines offsets for the end edge in the block dimension of the _optimal viewing region_ of the scrollport: the region used as the target region for placing things in view of the user. This allows the author to exclude regions of the scrollport that are obscured by other content (such as fixed-positioned toolbars or sidebars) or to put more breathing room between a targeted element and the edges of the scrollport. -{{EmbedInteractiveExample("pages/css/scroll-padding-block-end.html")}} +{{InteractiveExample("CSS Demo: scroll-padding-block-end")}} + +```css interactive-example-choice +scroll-padding-block-end: 0; +``` + +```css interactive-example-choice +scroll-padding-block-end: 20px; +``` + +```css interactive-example-choice +scroll-padding-block-end: 2em; +``` + +```html interactive-example +<section class="default-example" id="default-example"> + <div class="scroller" id="example-element"> + <div>1</div> + <div>2</div> + <div>3</div> + </div> + <div class="info">Scroll »</div> +</section> +``` + +```css interactive-example +.default-example .info { + inline-size: 100%; + padding: 0.5em 0; + font-size: 90%; + writing-mode: vertical-rl; +} + +.scroller { + text-align: left; + height: 250px; + width: 270px; + overflow-y: scroll; + display: flex; + flex-direction: column; + box-sizing: border-box; + border: 1px solid black; + scroll-snap-type: y mandatory; +} + +.scroller > div { + flex: 0 0 250px; + background-color: rebeccapurple; + color: #fff; + font-size: 30px; + display: flex; + align-items: center; + justify-content: center; + scroll-snap-align: end; +} + +.scroller > div:nth-child(even) { + background-color: #fff; + color: rebeccapurple; +} +``` ## Syntax diff --git a/files/en-us/web/css/scroll-padding-block-start/index.md b/files/en-us/web/css/scroll-padding-block-start/index.md index 8f1268cdb62c3eb..a80e792084911bc 100644 --- a/files/en-us/web/css/scroll-padding-block-start/index.md +++ b/files/en-us/web/css/scroll-padding-block-start/index.md @@ -9,7 +9,67 @@ browser-compat: css.properties.scroll-padding-block-start The `scroll-padding-block-start` property defines offsets for the start edge in the block dimension of the _optimal viewing region_ of the scrollport: the region used as the target region for placing things in view of the user. This allows the author to exclude regions of the scrollport that are obscured by other content (such as fixed-positioned toolbars or sidebars) or to put more breathing room between a targeted element and the edges of the scrollport. -{{EmbedInteractiveExample("pages/css/scroll-padding-block-start.html")}} +{{InteractiveExample("CSS Demo: scroll-padding-block-start")}} + +```css interactive-example-choice +scroll-padding-block-start: 0; +``` + +```css interactive-example-choice +scroll-padding-block-start: 20px; +``` + +```css interactive-example-choice +scroll-padding-block-start: 2em; +``` + +```html interactive-example +<section class="default-example" id="default-example"> + <div class="scroller" id="example-element"> + <div>1</div> + <div>2</div> + <div>3</div> + </div> + <div class="info">Scroll »</div> +</section> +``` + +```css interactive-example +.default-example .info { + inline-size: 100%; + padding: 0.5em 0; + font-size: 90%; + writing-mode: vertical-rl; +} + +.scroller { + text-align: left; + height: 250px; + width: 270px; + overflow-y: scroll; + display: flex; + flex-direction: column; + box-sizing: border-box; + border: 1px solid black; + scroll-snap-type: y mandatory; +} + +.scroller > div { + flex: 0 0 250px; + background-color: rebeccapurple; + color: #fff; + font-size: 30px; + display: flex; + align-items: center; + justify-content: center; + scroll-snap-align: start; +} + +.scroller > div:nth-child(even) { + background-color: #fff; + color: rebeccapurple; +} +``` ## Syntax diff --git a/files/en-us/web/css/scroll-padding-block/index.md b/files/en-us/web/css/scroll-padding-block/index.md index 517560273b3eef4..b2309a5873cbe12 100644 --- a/files/en-us/web/css/scroll-padding-block/index.md +++ b/files/en-us/web/css/scroll-padding-block/index.md @@ -9,7 +9,67 @@ browser-compat: css.properties.scroll-padding-block The `scroll-padding-block` [shorthand property](/en-US/docs/Web/CSS/CSS_cascade/Shorthand_properties) sets the scroll padding of an element in the block dimension. -{{EmbedInteractiveExample("pages/css/scroll-padding-block.html")}} +{{InteractiveExample("CSS Demo: scroll-padding-block")}} + +```css interactive-example-choice +scroll-padding-block: 0; +``` + +```css interactive-example-choice +scroll-padding-block: 20px; +``` + +```css interactive-example-choice +scroll-padding-block: 2em; +``` + +```html interactive-example +<section class="default-example" id="default-example"> + <div class="scroller" id="example-element"> + <div>1</div> + <div>2</div> + <div>3</div> + </div> + <div class="info">Scroll »</div> +</section> +``` + +```css interactive-example +.default-example .info { + inline-size: 100%; + padding: 0.5em 0; + font-size: 90%; + writing-mode: vertical-rl; +} + +.scroller { + text-align: left; + height: 250px; + width: 270px; + overflow-y: scroll; + display: flex; + flex-direction: column; + box-sizing: border-box; + border: 1px solid black; + scroll-snap-type: y mandatory; +} + +.scroller > div { + flex: 0 0 250px; + background-color: rebeccapurple; + color: #fff; + font-size: 30px; + display: flex; + align-items: center; + justify-content: center; + scroll-snap-align: start; +} + +.scroller > div:nth-child(even) { + background-color: #fff; + color: rebeccapurple; +} +``` The scroll-padding properties define offsets for the _optimal viewing region_ of the scrollport: the region used as the target region for placing things in view of the user. This allows the author to exclude regions of the scrollport that are obscured by other content (such as fixed-positioned toolbars or sidebars) or to put more breathing room between a targeted element and the edges of the scrollport. diff --git a/files/en-us/web/css/scroll-padding-bottom/index.md b/files/en-us/web/css/scroll-padding-bottom/index.md index b8492bb999e7a59..e3bcc645bb2def6 100644 --- a/files/en-us/web/css/scroll-padding-bottom/index.md +++ b/files/en-us/web/css/scroll-padding-bottom/index.md @@ -9,7 +9,67 @@ browser-compat: css.properties.scroll-padding-bottom The `scroll-padding-bottom` property defines offsets for the bottom of the _optimal viewing region_ of the scrollport: the region used as the target region for placing things in view of the user. This allows the author to exclude regions of the scrollport that are obscured by other content (such as fixed-positioned toolbars or sidebars) or to put more breathing room between a targeted element and the edges of the scrollport. -{{EmbedInteractiveExample("pages/css/scroll-padding-bottom.html")}} +{{InteractiveExample("CSS Demo: scroll-padding-bottom")}} + +```css interactive-example-choice +scroll-padding-bottom: 0; +``` + +```css interactive-example-choice +scroll-padding-bottom: 20px; +``` + +```css interactive-example-choice +scroll-padding-bottom: 2em; +``` + +```html interactive-example +<section class="default-example" id="default-example"> + <div class="scroller" id="example-element"> + <div>1</div> + <div>2</div> + <div>3</div> + </div> + <div class="info">Scroll »</div> +</section> +``` + +```css interactive-example +.default-example .info { + inline-size: 100%; + padding: 0.5em 0; + font-size: 90%; + writing-mode: vertical-rl; +} + +.scroller { + text-align: left; + height: 250px; + width: 270px; + overflow-y: scroll; + display: flex; + flex-direction: column; + box-sizing: border-box; + border: 1px solid black; + scroll-snap-type: y mandatory; +} + +.scroller > div { + flex: 0 0 250px; + background-color: rebeccapurple; + color: #fff; + font-size: 30px; + display: flex; + align-items: center; + justify-content: center; + scroll-snap-align: end; +} + +.scroller > div:nth-child(even) { + background-color: #fff; + color: rebeccapurple; +} +``` ## Syntax diff --git a/files/en-us/web/css/scroll-padding-inline-end/index.md b/files/en-us/web/css/scroll-padding-inline-end/index.md index 3282d638b05ea7a..a0231422ba11058 100644 --- a/files/en-us/web/css/scroll-padding-inline-end/index.md +++ b/files/en-us/web/css/scroll-padding-inline-end/index.md @@ -9,7 +9,70 @@ browser-compat: css.properties.scroll-padding-inline-end The `scroll-padding-inline-end` property defines offsets for the end edge in the inline dimension of the _optimal viewing region_ of the scrollport: the region used as the target region for placing things in view of the user. This allows the author to exclude regions of the scrollport that are obscured by other content (such as fixed-positioned toolbars or sidebars) or to put more breathing room between a targeted element and the edges of the scrollport. -{{EmbedInteractiveExample("pages/css/scroll-padding-inline-end.html")}} +{{InteractiveExample("CSS Demo: scroll-padding-inline-end")}} + +```css interactive-example-choice +scroll-padding-inline-end: 0; +``` + +```css interactive-example-choice +scroll-padding-inline-end: 20px; +``` + +```css interactive-example-choice +scroll-padding-inline-end: 2em; +``` + +```html interactive-example +<section class="default-example" id="default-example"> + <div class="scroller" id="example-element"> + <div>1</div> + <div>2</div> + <div>3</div> + </div> + <div class="info">Scroll »</div> +</section> +``` + +```css interactive-example +.default-example { + flex-wrap: wrap; +} + +.default-example .info { + width: 100%; + padding: 0.5em 0; + font-size: 90%; +} + +.scroller { + text-align: left; + width: 250px; + height: 250px; + overflow-x: scroll; + display: flex; + box-sizing: border-box; + border: 1px solid black; + scroll-snap-type: x mandatory; +} + +.scroller > div { + flex: 0 0 250px; + width: 250px; + background-color: rebeccapurple; + color: #fff; + font-size: 30px; + display: flex; + align-items: center; + justify-content: center; + scroll-snap-align: end; +} + +.scroller > div:nth-child(even) { + background-color: #fff; + color: rebeccapurple; +} +``` ## Syntax diff --git a/files/en-us/web/css/scroll-padding-inline-start/index.md b/files/en-us/web/css/scroll-padding-inline-start/index.md index 2f03ebe9bd5b617..b232051cd2ea562 100644 --- a/files/en-us/web/css/scroll-padding-inline-start/index.md +++ b/files/en-us/web/css/scroll-padding-inline-start/index.md @@ -9,7 +9,70 @@ browser-compat: css.properties.scroll-padding-inline-start The `scroll-padding-inline-start` property defines offsets for the start edge in the inline dimension of the _optimal viewing region_ of the scrollport: the region used as the target region for placing things in view of the user. This allows the author to exclude regions of the scrollport that are obscured by other content (such as fixed-positioned toolbars or sidebars) or to put more breathing room between a targeted element and the edges of the scrollport. -{{EmbedInteractiveExample("pages/css/scroll-padding-inline-start.html")}} +{{InteractiveExample("CSS Demo: scroll-padding-inline-start")}} + +```css interactive-example-choice +scroll-padding-inline-start: 0; +``` + +```css interactive-example-choice +scroll-padding-inline-start: 20px; +``` + +```css interactive-example-choice +scroll-padding-inline-start: 2em; +``` + +```html interactive-example +<section class="default-example" id="default-example"> + <div class="scroller" id="example-element"> + <div>1</div> + <div>2</div> + <div>3</div> + </div> + <div class="info">Scroll »</div> +</section> +``` + +```css interactive-example +.default-example { + flex-wrap: wrap; +} + +.default-example .info { + width: 100%; + padding: 0.5em 0; + font-size: 90%; +} + +.scroller { + text-align: left; + width: 250px; + height: 250px; + overflow-x: scroll; + display: flex; + box-sizing: border-box; + border: 1px solid black; + scroll-snap-type: x mandatory; +} + +.scroller > div { + flex: 0 0 250px; + width: 250px; + background-color: rebeccapurple; + color: #fff; + font-size: 30px; + display: flex; + align-items: center; + justify-content: center; + scroll-snap-align: start; +} + +.scroller > div:nth-child(even) { + background-color: #fff; + color: rebeccapurple; +} +``` ## Syntax diff --git a/files/en-us/web/css/scroll-padding-inline/index.md b/files/en-us/web/css/scroll-padding-inline/index.md index 8a5caf1fb38177b..0ca0ec495444150 100644 --- a/files/en-us/web/css/scroll-padding-inline/index.md +++ b/files/en-us/web/css/scroll-padding-inline/index.md @@ -9,7 +9,70 @@ browser-compat: css.properties.scroll-padding-inline The `scroll-padding-inline` [shorthand property](/en-US/docs/Web/CSS/CSS_cascade/Shorthand_properties) sets the scroll padding of an element in the inline dimension. -{{EmbedInteractiveExample("pages/css/scroll-padding-inline.html")}} +{{InteractiveExample("CSS Demo: scroll-padding-inline")}} + +```css interactive-example-choice +scroll-padding-inline: 0; +``` + +```css interactive-example-choice +scroll-padding-inline: 20px; +``` + +```css interactive-example-choice +scroll-padding-inline: 2em; +``` + +```html interactive-example +<section class="default-example" id="default-example"> + <div class="scroller" id="example-element"> + <div>1</div> + <div>2</div> + <div>3</div> + </div> + <div class="info">Scroll »</div> +</section> +``` + +```css interactive-example +.default-example { + flex-wrap: wrap; +} + +.default-example .info { + width: 100%; + padding: 0.5em 0; + font-size: 90%; +} + +.scroller { + text-align: left; + width: 250px; + height: 250px; + overflow-x: scroll; + display: flex; + box-sizing: border-box; + border: 1px solid black; + scroll-snap-type: x mandatory; +} + +.scroller > div { + flex: 0 0 250px; + width: 250px; + background-color: rebeccapurple; + color: #fff; + font-size: 30px; + display: flex; + align-items: center; + justify-content: center; + scroll-snap-align: start; +} + +.scroller > div:nth-child(even) { + background-color: #fff; + color: rebeccapurple; +} +``` The scroll-padding properties define offsets for the _optimal viewing region_ of the scrollport: the region used as the target region for placing things in view of the user. This allows the author to exclude regions of the scrollport that are obscured by other content (such as fixed-positioned toolbars or sidebars) or to put more breathing room between a targeted element and the edges of the scrollport. diff --git a/files/en-us/web/css/scroll-padding-left/index.md b/files/en-us/web/css/scroll-padding-left/index.md index 59d8c358b51cb63..42c11ad70fd4c94 100644 --- a/files/en-us/web/css/scroll-padding-left/index.md +++ b/files/en-us/web/css/scroll-padding-left/index.md @@ -9,7 +9,70 @@ browser-compat: css.properties.scroll-padding-left The `scroll-padding-left` property defines offsets for the left of the _optimal viewing region_ of the scrollport: the region used as the target region for placing things in view of the user. This allows the author to exclude regions of the scrollport that are obscured by other content (such as fixed-positioned toolbars or sidebars) or to put more breathing room between a targeted element and the edges of the scrollport. -{{EmbedInteractiveExample("pages/css/scroll-padding-left.html")}} +{{InteractiveExample("CSS Demo: scroll-padding-left")}} + +```css interactive-example-choice +scroll-padding-left: 0; +``` + +```css interactive-example-choice +scroll-padding-left: 20px; +``` + +```css interactive-example-choice +scroll-padding-left: 2em; +``` + +```html interactive-example +<section class="default-example" id="default-example"> + <div class="scroller" id="example-element"> + <div>1</div> + <div>2</div> + <div>3</div> + </div> + <div class="info">Scroll »</div> +</section> +``` + +```css interactive-example +.default-example { + flex-wrap: wrap; +} + +.default-example .info { + width: 100%; + padding: 0.5em 0; + font-size: 90%; +} + +.scroller { + text-align: left; + width: 250px; + height: 250px; + overflow-x: scroll; + display: flex; + box-sizing: border-box; + border: 1px solid black; + scroll-snap-type: x mandatory; +} + +.scroller > div { + flex: 0 0 250px; + width: 250px; + background-color: rebeccapurple; + color: #fff; + font-size: 30px; + display: flex; + align-items: center; + justify-content: center; + scroll-snap-align: start; +} + +.scroller > div:nth-child(even) { + background-color: #fff; + color: rebeccapurple; +} +``` ## Syntax diff --git a/files/en-us/web/css/scroll-padding-right/index.md b/files/en-us/web/css/scroll-padding-right/index.md index 67ac722086aa1cf..6628c4243e3e0db 100644 --- a/files/en-us/web/css/scroll-padding-right/index.md +++ b/files/en-us/web/css/scroll-padding-right/index.md @@ -9,7 +9,70 @@ browser-compat: css.properties.scroll-padding-right The `scroll-padding-right` property defines offsets for the right of the _optimal viewing region_ of the scrollport: the region used as the target region for placing things in view of the user. This allows the author to exclude regions of the scrollport that are obscured by other content (such as fixed-positioned toolbars or sidebars) or to put more breathing room between a targeted element and the edges of the scrollport. -{{EmbedInteractiveExample("pages/css/scroll-padding-right.html")}} +{{InteractiveExample("CSS Demo: scroll-padding-right")}} + +```css interactive-example-choice +scroll-padding-right: 0; +``` + +```css interactive-example-choice +scroll-padding-right: 20px; +``` + +```css interactive-example-choice +scroll-padding-right: 2em; +``` + +```html interactive-example +<section class="default-example" id="default-example"> + <div class="scroller" id="example-element"> + <div>1</div> + <div>2</div> + <div>3</div> + </div> + <div class="info">Scroll »</div> +</section> +``` + +```css interactive-example +.default-example { + flex-wrap: wrap; +} + +.default-example .info { + width: 100%; + padding: 0.5em 0; + font-size: 90%; +} + +.scroller { + text-align: left; + width: 250px; + height: 250px; + overflow-x: scroll; + display: flex; + box-sizing: border-box; + border: 1px solid black; + scroll-snap-type: x mandatory; +} + +.scroller > div { + flex: 0 0 250px; + width: 250px; + background-color: rebeccapurple; + color: #fff; + font-size: 30px; + display: flex; + align-items: center; + justify-content: center; + scroll-snap-align: end; +} + +.scroller > div:nth-child(even) { + background-color: #fff; + color: rebeccapurple; +} +``` ## Syntax diff --git a/files/en-us/web/css/scroll-padding-top/index.md b/files/en-us/web/css/scroll-padding-top/index.md index ad15b11294df8aa..1c9fc7a9f3b3a97 100644 --- a/files/en-us/web/css/scroll-padding-top/index.md +++ b/files/en-us/web/css/scroll-padding-top/index.md @@ -9,7 +9,67 @@ browser-compat: css.properties.scroll-padding-top The **`scroll-padding-top`** property defines offsets for the top of the _optimal viewing region_ of the scrollport: the region used as the target region for placing things in view of the user. This allows the author to exclude regions of the scrollport that are obscured by other content (such as fixed-positioned toolbars or sidebars) or to put more breathing room between a targeted element and the edges of the scrollport. -{{EmbedInteractiveExample("pages/css/scroll-padding-top.html")}} +{{InteractiveExample("CSS Demo: scroll-padding-top")}} + +```css interactive-example-choice +scroll-padding-top: 0; +``` + +```css interactive-example-choice +scroll-padding-top: 20px; +``` + +```css interactive-example-choice +scroll-padding-top: 2em; +``` + +```html interactive-example +<section class="default-example" id="default-example"> + <div class="scroller" id="example-element"> + <div>1</div> + <div>2</div> + <div>3</div> + </div> + <div class="info">Scroll »</div> +</section> +``` + +```css interactive-example +.default-example .info { + inline-size: 100%; + padding: 0.5em 0; + font-size: 90%; + writing-mode: vertical-rl; +} + +.scroller { + text-align: left; + height: 250px; + width: 270px; + overflow-y: scroll; + display: flex; + flex-direction: column; + box-sizing: border-box; + border: 1px solid black; + scroll-snap-type: y mandatory; +} + +.scroller > div { + flex: 0 0 250px; + background-color: rebeccapurple; + color: #fff; + font-size: 30px; + display: flex; + align-items: center; + justify-content: center; + scroll-snap-align: start; +} + +.scroller > div:nth-child(even) { + background-color: #fff; + color: rebeccapurple; +} +``` ## Syntax diff --git a/files/en-us/web/css/scroll-padding/index.md b/files/en-us/web/css/scroll-padding/index.md index 4bb969c625920ff..520dfb0bb9cec9c 100644 --- a/files/en-us/web/css/scroll-padding/index.md +++ b/files/en-us/web/css/scroll-padding/index.md @@ -9,7 +9,67 @@ browser-compat: css.properties.scroll-padding The **`scroll-padding`** [shorthand property](/en-US/docs/Web/CSS/CSS_cascade/Shorthand_properties) sets scroll padding on all sides of an element at once, much like the {{cssxref("padding")}} property does for padding on an element. -{{EmbedInteractiveExample("pages/css/scroll-padding.html")}} +{{InteractiveExample("CSS Demo: scroll-padding")}} + +```css interactive-example-choice +scroll-padding: 0; +``` + +```css interactive-example-choice +scroll-padding: 20px; +``` + +```css interactive-example-choice +scroll-padding: 2em; +``` + +```html interactive-example +<section class="default-example" id="default-example"> + <div class="scroller" id="example-element"> + <div>1</div> + <div>2</div> + <div>3</div> + </div> + <div class="info">Scroll »</div> +</section> +``` + +```css interactive-example +.default-example .info { + inline-size: 100%; + padding: 0.5em 0; + font-size: 90%; + writing-mode: vertical-rl; +} + +.scroller { + text-align: left; + height: 250px; + width: 270px; + overflow-y: scroll; + display: flex; + flex-direction: column; + box-sizing: border-box; + border: 1px solid black; + scroll-snap-type: y mandatory; +} + +.scroller > div { + flex: 0 0 250px; + background-color: rebeccapurple; + color: #fff; + font-size: 30px; + display: flex; + align-items: center; + justify-content: center; + scroll-snap-align: start; +} + +.scroller > div:nth-child(even) { + background-color: #fff; + color: rebeccapurple; +} +``` The `scroll-padding-*` properties define offsets for the _optimal viewing region_ of the scrollport: the region used as the target region for placing things in view of the user. This allows the author to exclude regions of the scrollport that are obscured by other content (such as fixed-positioned toolbars or sidebars), or to put more breathing room between a targeted element and the edges of the scrollport. diff --git a/files/en-us/web/css/scroll-snap-align/index.md b/files/en-us/web/css/scroll-snap-align/index.md index ef34a380d869635..bc9fd4ffd28ce2a 100644 --- a/files/en-us/web/css/scroll-snap-align/index.md +++ b/files/en-us/web/css/scroll-snap-align/index.md @@ -9,7 +9,69 @@ browser-compat: css.properties.scroll-snap-align The `scroll-snap-align` property specifies the box's snap position as an alignment of its [snap area](/en-US/docs/Glossary/Scroll_snap#snap_area) (as the {{glossary("alignment subject")}}) within its snap container's snap port (as the {{glossary("alignment container")}}). -{{EmbedInteractiveExample("pages/css/scroll-snap-align.html")}} +{{InteractiveExample("CSS Demo: scroll-snap-align")}} + +```css interactive-example-choice +scroll-snap-align: start; +``` + +```css interactive-example-choice +scroll-snap-align: end; +``` + +```css interactive-example-choice +scroll-snap-align: center; +``` + +```html interactive-example +<section class="default-example" id="default-example"> + <div id="example-parent"> + <div>1</div> + <div id="example-element">2</div> + <div>3</div> + </div> + <div class="info">Scroll »</div> +</section> +``` + +```css interactive-example +.default-example { + flex-wrap: wrap; +} + +.default-example .info { + width: 100%; + padding: 0.5em 0; + font-size: 90%; +} + +#example-parent { + text-align: left; + width: 250px; + height: 250px; + overflow-x: scroll; + display: flex; + box-sizing: border-box; + border: 1px solid black; + scroll-snap-type: x mandatory; +} + +#example-parent > div { + flex: 0 0 66%; + width: 250px; + background-color: rebeccapurple; + color: #fff; + font-size: 30px; + display: flex; + align-items: center; + justify-content: center; +} + +#example-parent > div:nth-child(even) { + background-color: #fff; + color: rebeccapurple; +} +``` ## Syntax diff --git a/files/en-us/web/css/scroll-snap-stop/index.md b/files/en-us/web/css/scroll-snap-stop/index.md index 7103c568edc02b9..ac1c60bac375add 100644 --- a/files/en-us/web/css/scroll-snap-stop/index.md +++ b/files/en-us/web/css/scroll-snap-stop/index.md @@ -9,7 +9,80 @@ browser-compat: css.properties.scroll-snap-stop The **`scroll-snap-stop`** [CSS](/en-US/docs/Web/CSS) property defines whether or not the scroll container is allowed to "pass over" possible snap positions. -{{EmbedInteractiveExample("pages/css/scroll-snap-stop.html")}} +{{InteractiveExample("CSS Demo: scroll-snap-stop")}} + +```css interactive-example-choice +scroll-snap-stop: normal; +``` + +```css interactive-example-choice +scroll-snap-stop: always; +``` + +```html interactive-example +<section class="default-example" id="default-example"> + <p class="explanation"> + The effect of this property can be noticed on devices with a touchpad. Try + to scroll through all items with a single swing. Value + <b class="keyword">'normal'</b> should pass through all pages, while + <b class="keyword">'always'</b> will stop at the second page. + </p> + <div class="snap-container"> + <div>1</div> + <div id="example-element">2</div> + <div>3</div> + </div> + <div class="info">Scroll »</div> +</section> +``` + +```css interactive-example +.default-example { + flex-direction: column; +} + +.explanation { + margin-top: 0; +} + +.keyword { + color: darkorange; +} + +.default-example .info { + width: 100%; + padding: 0.5em 0; + font-size: 90%; +} + +.snap-container { + text-align: left; + width: 250px; + height: 250px; + overflow-x: scroll; + display: flex; + box-sizing: border-box; + border: 1px solid black; + scroll-snap-type: x mandatory; +} + +.snap-container > div { + flex: 0 0 250px; + width: 250px; + background-color: rebeccapurple; + color: #fff; + font-size: 30px; + display: flex; + align-items: center; + justify-content: center; + scroll-snap-align: start; +} + +.snap-container > div:nth-child(even) { + background-color: #fff; + color: rebeccapurple; +} +``` ## Syntax diff --git a/files/en-us/web/css/scroll-snap-type/index.md b/files/en-us/web/css/scroll-snap-type/index.md index 0837d3476b462ec..aa9d941836c13d2 100644 --- a/files/en-us/web/css/scroll-snap-type/index.md +++ b/files/en-us/web/css/scroll-snap-type/index.md @@ -9,7 +9,69 @@ browser-compat: css.properties.scroll-snap-type The **`scroll-snap-type`** [CSS](/en-US/docs/Web/CSS) property is set on a {{glossary("scroll container")}}, opting it into scroll snapping by setting the direction and strictness of snap point enforcement within the [snap port](/en-US/docs/Glossary/Scroll_snap#snapport). -{{EmbedInteractiveExample("pages/css/scroll-snap-type.html")}} +{{InteractiveExample("CSS Demo: scroll-snap-type")}} + +```css interactive-example-choice +scroll-snap-type: none; +``` + +```css interactive-example-choice +scroll-snap-type: x mandatory; +``` + +```css interactive-example-choice +scroll-snap-type: x proximity; +``` + +```html interactive-example +<section class="default-example" id="default-example"> + <div id="example-element"> + <div>1</div> + <div>2</div> + <div>3</div> + </div> + <div class="info">Scroll »</div> +</section> +``` + +```css interactive-example +.default-example { + flex-wrap: wrap; +} + +.default-example .info { + width: 100%; + padding: 0.5em 0; + font-size: 90%; +} + +#example-element { + text-align: left; + width: 250px; + height: 250px; + overflow-x: scroll; + display: flex; + box-sizing: border-box; + border: 1px solid black; +} + +#example-element > div { + flex: 0 0 250px; + width: 250px; + background-color: rebeccapurple; + color: #fff; + font-size: 30px; + display: flex; + align-items: center; + justify-content: center; + scroll-snap-align: start; +} + +#example-element > div:nth-child(even) { + background-color: #fff; + color: rebeccapurple; +} +``` If the content in the scroll port changes — for example, if content is added, moved, deleted, or resized — the scroll container will re-snap to the previously snapped content if that content is still present. diff --git a/files/en-us/web/css/scrollbar-width/index.md b/files/en-us/web/css/scrollbar-width/index.md index 9ad0ce4edb31f70..be0bd781727240c 100644 --- a/files/en-us/web/css/scrollbar-width/index.md +++ b/files/en-us/web/css/scrollbar-width/index.md @@ -48,8 +48,8 @@ Use this property with caution — setting `scrollbar-width` to `thin` or `none` WCAG criterion 2.1.1 (Keyboard) has been in place for a long time to advise on basic keyboard accessibility, and this should include scrolling of content areas. And introduced in WCAG 2.1, criterion 2.5.5 (Target Size) advises that touch targets should be at least 44px in width and height (although the problem is compounded on high-resolution screens; thorough testing is advised). -- [MDN Understanding WCAG, Guideline 2.1 explanations](/en-US/docs/Web/Accessibility/Understanding_WCAG/Operable#guideline_2.1_—_keyboard_accessible_make_all_functionality_available_from_a_keyboard) -- [MDN Understanding WCAG, Guideline 2.5 explanations](/en-US/docs/Web/Accessibility/Understanding_WCAG/Operable#guideline_2.5_input_modalities_make_it_easier_for_users_to_operate_functionality_through_various_inputs_beyond_keyboard) +- [MDN Understanding WCAG, Guideline 2.1 explanations](/en-US/docs/Web/Accessibility/Guides/Understanding_WCAG/Operable#guideline_2.1_—_keyboard_accessible_make_all_functionality_available_from_a_keyboard) +- [MDN Understanding WCAG, Guideline 2.5 explanations](/en-US/docs/Web/Accessibility/Guides/Understanding_WCAG/Operable#guideline_2.5_input_modalities_make_it_easier_for_users_to_operate_functionality_through_various_inputs_beyond_keyboard) - [Understanding Success Criterion 2.1.1 | W3C Understanding WCAG 2.1](https://www.w3.org/WAI/WCAG21/Understanding/keyboard) - [Understanding Success Criterion 2.5.5 | W3C Understanding WCAG 2.1](https://www.w3.org/WAI/WCAG21/Understanding/target-size.html) diff --git a/files/en-us/web/css/self-position/index.md b/files/en-us/web/css/self-position/index.md index 82970a3231d3909..fa172f684e67aa4 100644 --- a/files/en-us/web/css/self-position/index.md +++ b/files/en-us/web/css/self-position/index.md @@ -2,7 +2,7 @@ title: <self-position> slug: Web/CSS/self-position page-type: css-type -browser-compat: css.types.self-position +spec-urls: https://drafts.csswg.org/css-align/#typedef-self-position --- {{CSSRef}} @@ -41,10 +41,6 @@ The following keyword values are represented by the `<self-position>` grammar te {{Specifications}} -## Browser compatibility - -{{Compat}} - ## See also - Properties that use this data type: {{cssxref("align-self")}}, {{cssxref("justify-self")}}, {{cssxref("place-self")}}, {{cssxref("align-items")}}, {{cssxref("justify-items")}}, {{cssxref("place-items")}} diff --git a/files/en-us/web/css/shape-image-threshold/index.md b/files/en-us/web/css/shape-image-threshold/index.md index 4d1c816c9d45fef..0412a9880d57073 100644 --- a/files/en-us/web/css/shape-image-threshold/index.md +++ b/files/en-us/web/css/shape-image-threshold/index.md @@ -9,7 +9,73 @@ browser-compat: css.properties.shape-image-threshold The **`shape-image-threshold`** [CSS](/en-US/docs/Web/CSS) property sets the alpha channel threshold used to extract the shape using an image as the value for {{cssxref("shape-outside")}}. -{{EmbedInteractiveExample("pages/css/shape-image-threshold.html")}} +{{InteractiveExample("CSS Demo: shape-image-threshold")}} + +```css interactive-example-choice +shape-outside: linear-gradient( + 50deg, + rgb(77, 26, 103), + transparent 80%, + transparent +); +shape-image-threshold: 0.2; +``` + +```css interactive-example-choice +shape-outside: linear-gradient( + 50deg, + rgb(77, 26, 103), + transparent 80%, + transparent +); +shape-image-threshold: 0.4; +``` + +```css interactive-example-choice +shape-outside: linear-gradient( + 50deg, + rgb(77, 26, 103), + transparent 80%, + transparent +); +shape-image-threshold: 0.6; +``` + +```html interactive-example +<section class="default-example" id="default-example"> + <div class="example-container"> + <div class="transition-all" id="example-element"></div> + We had agreed, my companion and I, that I should call for him at his house, + after dinner, not later than eleven o’clock. This athletic young Frenchman + belongs to a small set of Parisian sportsmen, who have taken up “ballooning” + as a pastime. After having exhausted all the sensations that are to be found + in ordinary sports, even those of “automobiling” at a breakneck speed, the + members of the “Aéro Club” now seek in the air, where they indulge in all + kinds of daring feats, the nerve-racking excitement that they have ceased to + find on earth. + </div> +</section> +``` + +```css interactive-example +.example-container { + text-align: left; + padding: 20px; +} + +#example-element { + float: left; + width: 150px; + height: 150px; + margin: 20px; + background-image: linear-gradient( + 50deg, + rgb(77, 26, 103), + transparent 80%, + transparent + ); +} +``` Any pixels whose alpha component's value is greater than the threshold are considered to be part of the shape for the purposes of determining its boundaries. For example, a value of `0.5` means that the shape will enclose all the pixels that are more than 50% opaque. diff --git a/files/en-us/web/css/shape-margin/index.md b/files/en-us/web/css/shape-margin/index.md index 28e03ad9364b1d9..032e5c0987def14 100644 --- a/files/en-us/web/css/shape-margin/index.md +++ b/files/en-us/web/css/shape-margin/index.md @@ -9,7 +9,56 @@ browser-compat: css.properties.shape-margin The **`shape-margin`** [CSS](/en-US/docs/Web/CSS) property sets a margin for a CSS shape created using {{cssxref("shape-outside")}}. -{{EmbedInteractiveExample("pages/css/shape-margin.html")}} +{{InteractiveExample("CSS Demo: shape-margin")}} + +```css interactive-example-choice +shape-margin: 0; +``` + +```css interactive-example-choice +shape-margin: 20px; +``` + +```css interactive-example-choice +shape-margin: 1em; +``` + +```css interactive-example-choice +shape-margin: 5%; +``` + +```html interactive-example +<section class="default-example" id="default-example"> + <div class="example-container"> + <div class="transition-all" id="example-element"></div> + We had agreed, my companion and I, that I should call for him at his house, + after dinner, not later than eleven o’clock. This athletic young Frenchman + belongs to a small set of Parisian sportsmen, who have taken up “ballooning” + as a pastime. After having exhausted all the sensations that are to be found + in ordinary sports, even those of “automobiling” at a breakneck speed, the + members of the “Aéro Club” now seek in the air, where they indulge in all + kinds of daring feats, the nerve-racking excitement that they have ceased to + find on earth. + </div> +</section> +``` + +```css interactive-example +.example-container { + text-align: left; + padding: 20px; +} + +#example-element { + float: left; + margin: 20px; + width: 180px; + height: 180px; + border-radius: 50%; + background-color: rebeccapurple; + shape-outside: circle(50%); +} +``` The margin lets you adjust the distance between the edges of the shape (the **float element**) and the surrounding content. diff --git a/files/en-us/web/css/shape-outside/index.md b/files/en-us/web/css/shape-outside/index.md index 61e5183db753625..b8af5849483d286 100644 --- a/files/en-us/web/css/shape-outside/index.md +++ b/files/en-us/web/css/shape-outside/index.md @@ -9,7 +9,56 @@ browser-compat: css.properties.shape-outside The **`shape-outside`** [CSS](/en-US/docs/Web/CSS) property defines a shape—which may be non-rectangular—around which adjacent inline content should wrap. By default, inline content wraps around its margin box; `shape-outside` provides a way to customize this wrapping, making it possible to wrap text around complex objects rather than rectangular boxes. -{{EmbedInteractiveExample("pages/css/shape-outside.html")}} +{{InteractiveExample("CSS Demo: shape-outside")}} + +```css interactive-example-choice +shape-outside: circle(50%); +``` + +```css interactive-example-choice +shape-outside: ellipse(130px 140px at 20% 20%); +``` + +```css interactive-example-choice +shape-outside: url(/shared-assets/images/examples/round-balloon.png); +``` + +```css interactive-example-choice +shape-outside: polygon(50% 0, 100% 50%, 50% 100%, 0 50%); +``` + +```html interactive-example +<section class="default-example" id="default-example"> + <div class="example-container"> + <img + class="transition-all" + id="example-element" + src="/shared-assets/images/examples/round-balloon.png" + width="150" /> + We had agreed, my companion and I, that I should call for him at his house, + after dinner, not later than eleven o’clock. This athletic young Frenchman + belongs to a small set of Parisian sportsmen, who have taken up “ballooning” + as a pastime. After having exhausted all the sensations that are to be found + in ordinary sports, even those of “automobiling” at a breakneck speed, the + members of the “Aéro Club” now seek in the air, where they indulge in all + kinds of daring feats, the nerve-racking excitement that they have ceased to + find on earth. + </div> +</section> +``` + +```css interactive-example +.example-container { + text-align: left; + padding: 20px; +} + +#example-element { + float: left; + width: 150px; + margin: 20px; +} +``` ## Syntax diff --git a/files/en-us/web/css/stop-color/index.md b/files/en-us/web/css/stop-color/index.md index 29c5d494c122a3e..8f77d8f92adc328 100644 --- a/files/en-us/web/css/stop-color/index.md +++ b/files/en-us/web/css/stop-color/index.md @@ -40,7 +40,7 @@ stop-color: unset; ## Formal syntax -{{csssyntax}} +{{CSSSyntaxRaw(`stop-color = <color>`)}} ## Examples diff --git a/files/en-us/web/css/stop-opacity/index.md b/files/en-us/web/css/stop-opacity/index.md index b8aff19ba47ef22..ecb900e6d79e2dd 100644 --- a/files/en-us/web/css/stop-opacity/index.md +++ b/files/en-us/web/css/stop-opacity/index.md @@ -49,7 +49,7 @@ With `0` or `0%` set, the stop is fully transparent. With `1` or `100%` set, the ## Formal syntax -{{csssyntax}} +{{CSSSyntaxRaw(`stop-opacity = <number> | <percentage>`)}} ## Examples diff --git a/files/en-us/web/css/subsequent-sibling_combinator/index.md b/files/en-us/web/css/subsequent-sibling_combinator/index.md index 634d98e50098108..0e95ad28530a3b3 100644 --- a/files/en-us/web/css/subsequent-sibling_combinator/index.md +++ b/files/en-us/web/css/subsequent-sibling_combinator/index.md @@ -95,7 +95,7 @@ The example below shows that the target element in the complex selector must sha In the above HTML, the two siblings of `.foo p` are `span` and `.foo`. The green `span` is a descendant of the `.foo` class, which is a sibling of `p`. - When the target selector is `span`, the `span` element that is a sibling of `p` is selected. The `p` element is a descendant of `.foo`, so are its `span` siblings. -- In `.foo p ~ .foo span`, the target selector is `span` that is a descendant of `.foo`. In this case, the `span` element that's a descendent of `.foo` is selected if that `.foo` is a sibling of `p`; essentially, both are nested in an ancestor of `.foo`. +- In `.foo p ~ .foo span`, the target selector is `span` that is a descendant of `.foo`. In this case, the `span` element that's a descendant of `.foo` is selected if that `.foo` is a sibling of `p`; essentially, both are nested in an ancestor of `.foo`. ## Specifications diff --git a/files/en-us/web/css/system-color/index.md b/files/en-us/web/css/system-color/index.md index c77e856968afa70..cca7b99e6425f18 100644 --- a/files/en-us/web/css/system-color/index.md +++ b/files/en-us/web/css/system-color/index.md @@ -21,95 +21,269 @@ A `<system-color>` value can be used anywhere a [`<color>`](/en-US/docs/Web/CSS/ Note that these keywords are _case insensitive_, but are listed here with mixed case for readability. -- `AccentColor` - - : Background of accented user interface controls. -- `AccentColorText` - - : Text of accented user interface controls. -- `ActiveText` - - : Text of active links. -- `ButtonBorder` - - : Base border color of controls. -- `ButtonFace` - - : Background color of controls. -- `ButtonText` - - : Text color of controls. -- `Canvas` - - : Background of application content or documents. -- `CanvasText` - - : Text color in application content or documents. -- `Field` - - : Background of input fields. -- `FieldText` - - : Text in input fields. -- `GrayText` - - : Text color for disabled items (for example, a disabled control). -- `Highlight` - - : Background of selected items. -- `HighlightText` - - : Text color of selected items. -- `LinkText` - - : Text of non-active, non-visited links. -- `Mark` - - : Background of text that has been specially marked (such as by the HTML `mark` element). -- `MarkText` - - : Text that has been specially marked (such as by the HTML `mark` element). -- `SelectedItem` - - : Background of selected items, for example, a selected checkbox. -- `SelectedItemText` - - : Text of selected items. -- `VisitedText` - - : Text of visited links. +Depending on your settings, the sample colors displayed in the table may change. You can also view this page with different browsers, operating systems, and system settings, to check the differences. + +<table> + <thead> + <tr> + <th>Keyword</th> + <th>Description</th> + <th>Sample</th> + </tr> + </thead> + <tbody> + <tr> + <td><code>AccentColor</code></td> + <td>Background of accented user interface controls.</td> + <td style="background-color: AccentColor;"></td> + </tr> + <tr> + <td><code>AccentColorText</code></td> + <td>Text of accented user interface controls.</td> + <td style="background-color: AccentColorText;"></td> + </tr> + <tr> + <td><code>ActiveText</code></td> + <td>Text of active links.</td> + <td style="background-color: ActiveText;"></td> + </tr> + <tr> + <td><code>ButtonBorder</code></td> + <td>Base border color of controls.</td> + <td style="background-color: ButtonBorder;"></td> + </tr> + <tr> + <td><code>ButtonFace</code></td> + <td>Background color of controls.</td> + <td style="background-color: ButtonFace;"></td> + </tr> + <tr> + <td><code>ButtonText</code></td> + <td>Text color of controls.</td> + <td style="background-color: ButtonText;"></td> + </tr> + <tr> + <td><code>Canvas</code></td> + <td>Background of application content or documents.</td> + <td style="background-color: Canvas;"></td> + </tr> + <tr> + <td><code>CanvasText</code></td> + <td>Text color in application content or documents.</td> + <td style="background-color: CanvasText;"></td> + </tr> + <tr> + <td><code>Field</code></td> + <td>Background of input fields.</td> + <td style="background-color: Field;"></td> + </tr> + <tr> + <td><code>FieldText</code></td> + <td>Text in input fields.</td> + <td style="background-color: FieldText;"></td> + </tr> + <tr> + <td><code>GrayText</code></td> + <td>Text color for disabled items (for example, a disabled control).</td> + <td style="background-color: GrayText;"></td> + </tr> + <tr> + <td><code>Highlight</code></td> + <td>Background of selected items.</td> + <td style="background-color: Highlight;"></td> + </tr> + <tr> + <td><code>HighlightText</code></td> + <td>Text color of selected items.</td> + <td style="background-color: HighlightText;"></td> + </tr> + <tr> + <td><code>LinkText</code></td> + <td>Text of non-active, non-visited links.</td> + <td style="background-color: LinkText;"></td> + </tr> + <tr> + <td><code>Mark</code></td> + <td>Background of text that has been specially marked (such as by the HTML <code>mark</code> element).</td> + <td style="background-color: Mark;"></td> + </tr> + <tr> + <td><code>MarkText</code></td> + <td>Text that has been specially marked (such as by the HTML <code>mark</code> element).</td> + <td style="background-color: MarkText;"></td> + </tr> + <tr> + <td><code>SelectedItem</code></td> + <td>Background of selected items, for example, a selected checkbox.</td> + <td style="background-color: SelectedItem;"></td> + </tr> + <tr> + <td><code>SelectedItemText</code></td> + <td>Text of selected items.</td> + <td style="background-color: SelectedItemText;"></td> + </tr> + <tr> + <td><code>VisitedText</code></td> + <td>Text of visited links.</td> + <td style="background-color: VisitedText;"></td> + </tr> + </tbody> +</table> ### Deprecated system color keywords The following keywords were defined in earlier versions of the CSS Color Module. They are now deprecated for use on public web pages. -- `ActiveBorder` {{Deprecated_Inline}} - - : Active window border. Same as `ButtonBorder`. -- `ActiveCaption` {{Deprecated_Inline}} - - : Active window caption. Should be used with `CaptionText` as foreground color. Same as `Canvas`. -- `AppWorkspace` {{Deprecated_Inline}} - - : Background color of multiple document interface. Same as `Canvas`. -- `Background` {{Deprecated_Inline}} - - : Desktop background. Same as `Canvas`. -- `ButtonHighlight` {{Deprecated_Inline}} - - : The color of the border facing the light source for 3-D elements that appear 3-D due to that layer of surrounding border. Same as `ButtonFace`. -- `ButtonShadow` {{Deprecated_Inline}} - - : The color of the border away from the light source for 3-D elements that appear 3-D due to that layer of surrounding border. Same as `ButtonFace`. -- `CaptionText` {{Deprecated_Inline}} - - : Text in caption, size box, and scrollbar arrow box. Should be used with the `ActiveCaption` background color. Same as `CanvasText`. -- `InactiveBorder` {{Deprecated_Inline}} - - : Inactive window border. Same as `ButtonBorder`. -- `InactiveCaption` {{Deprecated_Inline}} - - : Inactive window caption. Should be used with the `InactiveCaptionText` foreground color. Same as `Canvas`. -- `InactiveCaptionText` {{Deprecated_Inline}} - - : Color of text in an inactive caption. Should be used with the `InactiveCaption` background color. Same as `GrayText`. -- `InfoBackground` {{Deprecated_Inline}} - - : Background color for tooltip controls. Should be used with the `InfoText` foreground color. Same as `Canvas`. -- `InfoText` {{Deprecated_Inline}} - - : Text color for tooltip controls. Should be used with the `InfoBackground` background color. Same as `CanvasText`. -- `Menu` {{Deprecated_Inline}} - - : Menu background. Should be used with the `MenuText` or `-moz-MenuBarText` foreground color. Same as `Canvas`. -- `MenuText` {{Deprecated_Inline}} - - : Text in menus. Should be used with the `Menu` background color. Same as `CanvasText`. -- `Scrollbar` {{Deprecated_Inline}} - - : Background color of scroll bars. Same as `Canvas`. -- `ThreeDDarkShadow` {{Deprecated_Inline}} - - : The color of the darker (generally outer) of the two borders away from the light source for 3-D elements that appear 3-D due to two concentric layers of surrounding border. Same as `ButtonBorder`. -- `ThreeDFace` {{Deprecated_Inline}} - - : The face background color for 3-D elements that appear 3-D due to two concentric layers of surrounding border. Should be used with the `ButtonText` foreground color. Same as `ButtonFace`. -- `ThreeDHighlight` {{Deprecated_Inline}} - - : The color of the lighter (generally outer) of the two borders facing the light source for 3-D elements that appear 3-D due to two concentric layers of surrounding border. Same as `ButtonBorder`. -- `ThreeDLightShadow` {{Deprecated_Inline}} - - : The color of the darker (generally inner) of the two borders facing the light source for 3-D elements that appear 3-D due to two concentric layers of surrounding border. Same as `ButtonBorder`. -- `ThreeDShadow` {{Deprecated_Inline}} - - : The color of the lighter (generally inner) of the two borders away from the light source for 3-D elements that appear 3-D due to two concentric layers of surrounding border. Same as `ButtonBorder`. -- `Window` {{Deprecated_Inline}} - - : Window background. Should be used with the `WindowText` foreground color. Same as `Canvas`. -- `WindowFrame` {{Deprecated_Inline}} - - : Window frame. Same as `ButtonBorder`. -- `WindowText` {{Deprecated_Inline}} - - : Text in windows. Should be used with the `Window` background color. Same as `CanvasText`. +<table> + <thead> + <tr> + <th>Keyword</th> + <th>Description</th> + <th>Replacement</th> + <th>Sample</th> + </tr> + </thead> + <tbody> + <tr> + <td><code>ActiveBorder</code></td> + <td>Active window border</td> + <td><code>ButtonBorder</code></td> + <td style="background-color: ActiveBorder;"></td> + </tr> + <tr> + <td><code>ActiveCaption</code></td> + <td>Active window caption. Should be used with <code>CaptionText</code> as foreground color.</td> + <td><code>Canvas</code></td> + <td style="background-color: ActiveCaption;"></td> + </tr> + <tr> + <td><code>AppWorkspace</code></td> + <td>Background color of multiple document interface.</td> + <td><code>Canvas</code></td> + <td style="background-color: AppWorkspace;"></td> + </tr> + <tr> + <td><code>Background</code></td> + <td>Desktop background.</td> + <td><code>Canvas</code></td> + <td style="background-color: Background;"></td> + </tr> + <tr> + <td><code>ButtonHighlight</code></td> + <td>The color of the border facing the light source for 3-D elements that appear 3-D due to that layer of surrounding border.</td> + <td><code>ButtonFace</code></td> + <td style="background-color: ButtonHighlight;"></td> + </tr> + <tr> + <td><code>ButtonShadow</code></td> + <td>The color of the border away from the light source for 3-D elements that appear 3-D due to that layer of surrounding border.</td> + <td><code>ButtonFace</code></td> + <td style="background-color: ButtonShadow;"></td> + </tr> + <tr> + <td><code>CaptionText</code></td> + <td>Text in caption, size box, and scrollbar arrow box. Should be used with the <code>ActiveCaption</code> background color.</td> + <td><code>CanvasText</code></td> + <td style="background-color: CaptionText;"></td> + </tr> + <tr> + <td><code>InactiveBorder</code></td> + <td>Inactive window border.</td> + <td><code>ButtonBorder</code></td> + <td style="background-color: InactiveBorder;"></td> + </tr> + <tr> + <td><code>InactiveCaption</code></td> + <td>Inactive window caption. Should be used with the <code>InactiveCaptionText</code> foreground color.</td> + <td><code>Canvas</code></td> + <td style="background-color: InactiveCaption;"></td> + </tr> + <tr> + <td><code>InactiveCaptionText</code></td> + <td>Color of text in an inactive caption. Should be used with the <code>InactiveCaption</code> background color.</td> + <td><code>GrayText</code></td> + <td style="background-color: InactiveCaptionText;"></td> + </tr> + <tr> + <td><code>InfoBackground</code></td> + <td>Background color for tooltip controls. Should be used with the <code>InfoText</code> foreground color.</td> + <td><code>Canvas</code></td> + <td style="background-color: InfoBackground;"></td> + </tr> + <tr> + <td><code>InfoText</code></td> + <td>Text color for tooltip controls. Should be used with the <code>InfoBackground</code> background color.</td> + <td><code>CanvasText</code></td> + <td style="background-color: InfoText;"></td> + </tr> + <tr> + <td><code>Menu</code></td> + <td>Menu background. Should be used with the <code>MenuText</code> or <code>-moz-MenuBarText</code> foreground color.</td> + <td><code>Canvas</code></td> + <td style="background-color: Menu;"></td> + </tr> + <tr> + <td><code>MenuText</code></td> + <td>Text in menus. Should be used with the <code>Menu</code> background color.</td> + <td><code>CanvasText</code></td> + <td style="background-color: MenuText;"></td> + </tr> + <tr> + <td><code>Scrollbar</code></td> + <td>Background color of scroll bars.</td> + <td><code>Canvas</code></td> + <td style="background-color: Scrollbar;"></td> + </tr> + <tr> + <td><code>ThreeDDarkShadow</code></td> + <td>The color of the darker (generally outer) of the two borders away from the light source for 3-D elements that appear 3-D due to two concentric layers of surrounding border.</td> + <td><code>ButtonBorder</code></td> + <td style="background-color: ThreeDDarkShadow;"></td> + </tr> + <tr> + <td><code>ThreeDFace</code></td> + <td>The face background color for 3-D elements that appear 3-D due to two concentric layers of surrounding border. Should be used with the <code>ButtonText</code> foreground color.</td> + <td><code>ButtonFace</code></td> + <td style="background-color: ThreeDFace;"></td> + </tr> + <tr> + <td><code>ThreeDHighlight</code></td> + <td>The color of the lighter (generally outer) of the two borders facing the light source for 3-D elements that appear 3-D due to two concentric layers of surrounding border.</td> + <td><code>ButtonBorder</code></td> + <td style="background-color: ThreeDHighlight;"></td> + </tr> + <tr> + <td><code>ThreeDLightShadow</code></td> + <td>The color of the darker (generally inner) of the two borders facing the light source for 3-D elements that appear 3-D due to two concentric layers of surrounding border.</td> + <td><code>ButtonBorder</code></td> + <td style="background-color: ThreeDLightShadow;"></td> + </tr> + <tr> + <td><code>ThreeDShadow</code></td> + <td>The color of the lighter (generally inner) of the two borders away from the light source for 3-D elements that appear 3-D due to two concentric layers of surrounding border.</td> + <td><code>ButtonBorder</code></td> + <td style="background-color: ThreeDShadow;"></td> + </tr> + <tr> + <td><code>Window</code></td> + <td>Window background. Should be used with the <code>WindowText</code> foreground color.</td> + <td><code>Canvas</code></td> + <td style="background-color: Window;"></td> + </tr> + <tr> + <td><code>WindowFrame</code></td> + <td>Window frame.</td> + <td><code>ButtonBorder</code></td> + <td style="background-color: WindowFrame;"></td> + </tr> + <tr> + <td><code>WindowText</code></td> + <td>Text in windows. Should be used with the <code>Window</code> background color.</td> + <td><code>CanvasText</code></td> + <td style="background-color: WindowText;"></td> + </tr> + </tbody> +</table> ## Examples diff --git a/files/en-us/web/css/tab-size/index.md b/files/en-us/web/css/tab-size/index.md index 5264959293f3d6a..40fed649d60ecaa 100644 --- a/files/en-us/web/css/tab-size/index.md +++ b/files/en-us/web/css/tab-size/index.md @@ -9,7 +9,35 @@ browser-compat: css.properties.tab-size The **`tab-size`** [CSS](/en-US/docs/Web/CSS) property is used to customize the width of tab characters (U+0009). -{{EmbedInteractiveExample("pages/css/tab-size.html")}} +{{InteractiveExample("CSS Demo: tab-size")}} + +```css interactive-example-choice +tab-size: 10px; +``` + +```css interactive-example-choice +tab-size: 16px; +``` + +```css interactive-example-choice +tab-size: 24px; +``` + +```css interactive-example-choice +tab-size: 4; +``` + +```html interactive-example +<section id="default-example"> + <pre id="example-element">&#9;123</pre> +</section> +``` + +```css interactive-example +#example-element { + border: 1px solid; +} +``` ## Syntax diff --git a/files/en-us/web/css/table-layout/index.md b/files/en-us/web/css/table-layout/index.md index ece9064e10aa377..9f92b1f2be8f8c6 100644 --- a/files/en-us/web/css/table-layout/index.md +++ b/files/en-us/web/css/table-layout/index.md @@ -9,7 +9,66 @@ browser-compat: css.properties.table-layout The **`table-layout`** [CSS](/en-US/docs/Web/CSS) property sets the algorithm used to lay out {{htmlelement("table")}} cells, rows, and columns. -{{EmbedInteractiveExample("pages/css/table-layout.html")}} +{{InteractiveExample("CSS Demo: table-layout")}} + +```css interactive-example-choice +table-layout: auto; +width: 150px; +``` + +```css interactive-example-choice +table-layout: fixed; +width: 150px; +``` + +```css interactive-example-choice +table-layout: auto; +width: 100%; +``` + +```css interactive-example-choice +table-layout: fixed; +width: 100%; +``` + +```html interactive-example +<section class="default-example" id="default-example"> + <table class="transition-all" id="example-element"> + <tr> + <th>Name</th> + <th>Location</th> + </tr> + <tr> + <td>Lion</td> + <td>Africa</td> + </tr> + <tr> + <td>Norwegian Lemming</td> + <td>Europe</td> + </tr> + <tr> + <td>Seal</td> + <td>Antarctica</td> + </tr> + <tr> + <td>Tiger</td> + <td>Asia</td> + </tr> + </table> +</section> +``` + +```css interactive-example +table { + border: 1px solid #139; +} + +th, +td { + border: 2px solid #a19; + padding: 0.25rem 0.5rem; +} +``` ## Syntax @@ -113,5 +172,5 @@ td { ## See also -- [`<table>`](/en-US/docs/Web/HTML/Element/table) +- [`<table>`](/en-US/docs/Web/HTML/Reference/Elements/table) - [CSS table](/en-US/docs/Web/CSS/CSS_table) module diff --git a/files/en-us/web/css/text-align-last/index.md b/files/en-us/web/css/text-align-last/index.md index f6d1b4914b27627..0bf7b986e2026f8 100644 --- a/files/en-us/web/css/text-align-last/index.md +++ b/files/en-us/web/css/text-align-last/index.md @@ -9,7 +9,44 @@ browser-compat: css.properties.text-align-last The **`text-align-last`** [CSS](/en-US/docs/Web/CSS) property sets how the last line of a block or a line, right before a forced line break, is aligned. -{{EmbedInteractiveExample("pages/css/text-align-last.html")}} +{{InteractiveExample("CSS Demo: text-align-last")}} + +```css interactive-example-choice +text-align-last: right; +``` + +```css interactive-example-choice +text-align-last: center; +``` + +```css interactive-example-choice +text-align-last: left; +``` + +```html interactive-example +<section id="default-example"> + <div> + <p id="example-element"> + Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut + aliquip ex ea commodo consequat. + </p> + </div> +</section> +``` + +```css interactive-example +section { + font-size: 1.5em; +} + +#default-example > div { + width: 250px; +} + +#example-element { + text-align: justify; +} +``` ## Syntax diff --git a/files/en-us/web/css/text-align/index.md b/files/en-us/web/css/text-align/index.md index 7f124ad384151e4..a3295f7a522ace1 100644 --- a/files/en-us/web/css/text-align/index.md +++ b/files/en-us/web/css/text-align/index.md @@ -9,7 +9,49 @@ browser-compat: css.properties.text-align The **`text-align`** [CSS](/en-US/docs/Web/CSS) property sets the horizontal alignment of the inline-level content inside a block element or table-cell box. This means it works like {{cssxref("vertical-align")}} but in the horizontal direction. -{{EmbedInteractiveExample("pages/css/text-align.html")}} +{{InteractiveExample("CSS Demo: text-align")}} + +```css interactive-example-choice +text-align: start; +``` + +```css interactive-example-choice +text-align: end; +``` + +```css interactive-example-choice +text-align: center; +``` + +```css interactive-example-choice +text-align: justify; +``` + +```html interactive-example +<section id="default-example"> + <div id="example-element"> + <p> + Lorem ipsum dolor sit amet, consectetur adipisicing elit, sed do eiusmod + tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim + veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea + commodo consequat. Duis aute irure dolor in reprehenderit in voluptate + velit esse cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat + cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id + est laborum. + </p> + </div> +</section> +``` + +```css interactive-example +section { + font-size: 1.5em; +} + +#default-example > div { + width: 250px; +} +``` ## Syntax @@ -58,7 +100,7 @@ The `text-align` property is specified as a single keyword from the list below. The inconsistent spacing between words created by justified text can be problematic for people with cognitive concerns such as Dyslexia. -- [MDN Understanding WCAG, Guideline 1.4 explanations](/en-US/docs/Web/Accessibility/Understanding_WCAG/Perceivable#guideline_1.4_make_it_easier_for_users_to_see_and_hear_content_including_separating_foreground_from_background) +- [MDN Understanding WCAG, Guideline 1.4 explanations](/en-US/docs/Web/Accessibility/Guides/Understanding_WCAG/Perceivable#guideline_1.4_make_it_easier_for_users_to_see_and_hear_content_including_separating_foreground_from_background) - [Understanding Success Criterion 1.4.8 | Understanding WCAG 2.0](https://www.w3.org/TR/UNDERSTANDING-WCAG20/visual-audio-contrast-visual-presentation.html) ## Formal definition diff --git a/files/en-us/web/css/text-anchor/index.md b/files/en-us/web/css/text-anchor/index.md index 79bb81d21172152..1ccc95441a4bf06 100644 --- a/files/en-us/web/css/text-anchor/index.md +++ b/files/en-us/web/css/text-anchor/index.md @@ -9,7 +9,7 @@ browser-compat: css.properties.text-anchor The **`text-anchor`** [CSS](/en-US/docs/Web/CSS) property aligns a box containing a string of text where the wrapping area is determined from the {{cssxref("inline-size")}} property, and the text is then placed relative to the anchor point of the element, which is defined using the {{SVGAttr('x')}} and {{SVGAttr('y')}} (or {{SVGAttr('dx')}} and {{SVGAttr('dy')}}) attributes. If present, the value of the CSS property overrides any value of the element's {{SVGAttr("text-anchor")}} attribute. -Each individual text fragment within an element is aligned independently; thus, a multi-line {{SVGElement("text")}} element will have each line of text aligned as per the value of `text-anchor`. `text-anchor` values only have an effect on the {{SVGElement("text")}}, {{SVGElement("textPath")}}, {{SVGElement("tref")}}, and {{SVGElement("tspan")}} SVG elements. `text-anchor` does not apply to automatically wrapped text; for that, see {{cssxref('text-align')}}. +Each individual text fragment within an element is aligned independently; thus, a multi-line {{SVGElement("text")}} element will have each line of text aligned as per the value of `text-anchor`. `text-anchor` values only have an effect on the {{SVGElement("text")}}, {{SVGElement("textPath")}}, and {{SVGElement("tspan")}} SVG elements. `text-anchor` does not apply to automatically wrapped text; for that, see {{cssxref('text-align')}}. ## Syntax diff --git a/files/en-us/web/css/text-box-trim/index.md b/files/en-us/web/css/text-box-trim/index.md index c53f89a1bcc8a99..5f9a3acf10a7387 100644 --- a/files/en-us/web/css/text-box-trim/index.md +++ b/files/en-us/web/css/text-box-trim/index.md @@ -126,7 +126,7 @@ In this example we provide a user interface that allows you to choose the `text- In our HTML, we include three main items: - Three {{htmlelement("select")}} elements allowing you to set which edges of the paragraph should be trimmed (the `text-box-trim` value) and how much space to trim from the block-start and block-end edges of the paragraph (the {{cssxref("text-box-edge")}} value). -- A {{htmlelement("p")}} element containing text, which the `text-box-*` values are applied to. This paragraph has [`contenteditable`](/en-US/docs/Web/HTML/Global_attributes/contenteditable) set on it so you can edit the text. +- A {{htmlelement("p")}} element containing text, which the `text-box-*` values are applied to. This paragraph has [`contenteditable`](/en-US/docs/Web/HTML/Reference/Global_attributes/contenteditable) set on it so you can edit the text. - An {{htmlelement("output")}} element that displays the `text-box-*` declarations applied to the paragraph. This is updated when a selection is made. We also import a font from the Google Fonts service to apply to our demo's text. @@ -266,7 +266,7 @@ function setEdgeTrim() { } ``` -In the last part of the JavaScript we run the `setEdgeTrim()` function once to set an initial state for the UI. We then then apply [`change`](/en-US/docs/Web/API/HTMLElement/change_event) event listeners to all of the `<select>` elements (via [`addEventListener`](/en-US/docs/Web/API/EventTarget/addEventListener)) so that `setEdgeTrim()` is run whenever one of the `<select>` values changes to update the UI accordingly: +In the last part of the JavaScript we run the `setEdgeTrim()` function once to set an initial state for the UI. We then apply [`change`](/en-US/docs/Web/API/HTMLElement/change_event) event listeners to all of the `<select>` elements (via [`addEventListener`](/en-US/docs/Web/API/EventTarget/addEventListener)) so that `setEdgeTrim()` is run whenever one of the `<select>` values changes to update the UI accordingly: ```js setEdgeTrim(); diff --git a/files/en-us/web/css/text-box/index.md b/files/en-us/web/css/text-box/index.md index 6b38314e3dc2831..2e242200aa9a5a6 100644 --- a/files/en-us/web/css/text-box/index.md +++ b/files/en-us/web/css/text-box/index.md @@ -58,7 +58,7 @@ If `text-box-trim` is omitted, it is set to `trim-both`. If `text-box-edge` is o The height of text-only content is relative to the height of the font. In digital font files, the height contains all characters, including capital letters, ascenders, descenders, etc. Different fonts have different base line-heights, meaning that lines of text with the same `font-size` will produce line boxes of differing heights, affecting the appearance of spacing between lines. -The {{cssxref("text-box")}} properties enable trimming off extra spacing from the block-start edge and block-end edge of a text element's block container, which can include the {{glossary("leading")}} at the text's block-start edge and block-end edges, and the spacing defined inside the font (as described above). This makes it much easier to control text spacing in the block direction. +The `text-box` properties enable trimming off extra spacing from the block-start edge and block-end edge of a text element's block container, which can include the {{glossary("leading")}} at the text's block-start edge and block-end edges, and the spacing defined inside the font (as described above). This makes it much easier to control text spacing in the block direction. ## Examples diff --git a/files/en-us/web/css/text-combine-upright/index.md b/files/en-us/web/css/text-combine-upright/index.md index 378e91b42b9e8a6..249e3b89dee25f2 100644 --- a/files/en-us/web/css/text-combine-upright/index.md +++ b/files/en-us/web/css/text-combine-upright/index.md @@ -11,7 +11,33 @@ The **`text-combine-upright`** [CSS](/en-US/docs/Web/CSS) property sets the comb This is used to produce an effect that is known as tate-chū-yoko <q lang="ja">縦中横</q> in Japanese, or as <q lang="zh-Hant">橫向文字</q> in Chinese. -{{EmbedInteractiveExample("pages/css/text-combine-upright.html")}} +{{InteractiveExample("CSS Demo: text-combine-upright")}} + +```css interactive-example-choice +text-combine-upright: none; +``` + +```css interactive-example-choice +text-combine-upright: all; +``` + +```html interactive-example +<section class="default-example" id="default-example"> + <div> + <p> + <span class="transition-all" id="example-element" + >2022<span>年</span>12<span>月</span>8</span + >日から楽しい + </p> + </div> +</section> +``` + +```css interactive-example +p { + writing-mode: vertical-rl; +} +``` ## Syntax diff --git a/files/en-us/web/css/text-decoration-color/index.md b/files/en-us/web/css/text-decoration-color/index.md index ddb46f2d4e5c59d..1aedc2237d4b226 100644 --- a/files/en-us/web/css/text-decoration-color/index.md +++ b/files/en-us/web/css/text-decoration-color/index.md @@ -11,7 +11,47 @@ The **`text-decoration-color`** [CSS](/en-US/docs/Web/CSS) property sets the col The color applies to decorations, such as underlines, overlines, strikethroughs, and wavy lines like those used to mark misspellings, in the scope of the property's value. -{{EmbedInteractiveExample("pages/css/text-decoration-color.html")}} +{{InteractiveExample("CSS Demo: text-decoration-color")}} + +```css interactive-example-choice +text-decoration-color: red; +``` + +```css interactive-example-choice +text-decoration-color: #21ff21; +``` + +```css interactive-example-choice +text-decoration-color: rgb(255, 90, 255); +``` + +```css interactive-example-choice +text-decoration-color: hsl(70, 100%, 40%); +``` + +```css interactive-example-choice +text-decoration-color: currentColor; +``` + +```html interactive-example +<section id="default-example"> + <p> + I'd far rather be + <span class="transition-all" id="example-element">happy than right</span> + any day. + </p> +</section> +``` + +```css interactive-example +p { + font: 1.5em sans-serif; +} + +#example-element { + text-decoration-line: underline; +} +``` CSS does not provide a direct mechanism for specifying a unique color for each line type. This effect can nevertheless be achieved by nesting elements, applying a different line type to each element (with the {{cssxref("text-decoration-line")}} property), and specifying the line color (with `text-decoration-color`) on a per-element basis. @@ -45,7 +85,7 @@ It is important to ensure that the contrast ratio between the color of the text, Color alone should not be used to convey meaning. For example, change of text and text-decoration-color alone is not enough to indicate a link has focus. - [WebAIM: Color Contrast Checker](https://webaim.org/resources/contrastchecker/) -- [MDN Understanding WCAG, Guideline 1.4 explanations](/en-US/docs/Web/Accessibility/Understanding_WCAG/Perceivable#guideline_1.4_make_it_easier_for_users_to_see_and_hear_content_including_separating_foreground_from_background) +- [MDN Understanding WCAG, Guideline 1.4 explanations](/en-US/docs/Web/Accessibility/Guides/Understanding_WCAG/Perceivable#guideline_1.4_make_it_easier_for_users_to_see_and_hear_content_including_separating_foreground_from_background) - [Understanding Success Criterion 1.4.3 | W3C Understanding WCAG 2.0](https://www.w3.org/TR/UNDERSTANDING-WCAG20/visual-audio-contrast-contrast.html) ## Formal definition diff --git a/files/en-us/web/css/text-decoration-line/index.md b/files/en-us/web/css/text-decoration-line/index.md index 17f0cce9bfca8a2..fba31f2202319c4 100644 --- a/files/en-us/web/css/text-decoration-line/index.md +++ b/files/en-us/web/css/text-decoration-line/index.md @@ -9,7 +9,55 @@ browser-compat: css.properties.text-decoration-line The **`text-decoration-line`** [CSS](/en-US/docs/Web/CSS) property sets the kind of decoration that is used on text in an element, such as an underline or overline. -{{EmbedInteractiveExample("pages/css/text-decoration-line.html")}} +{{InteractiveExample("CSS Demo: text-decoration-line")}} + +```css interactive-example-choice +text-decoration-line: none; +``` + +```css interactive-example-choice +text-decoration-line: underline; +``` + +```css interactive-example-choice +text-decoration-line: overline; +``` + +```css interactive-example-choice +text-decoration-line: line-through; +``` + +```css interactive-example-choice +text-decoration-line: grammar-error; +``` + +```css interactive-example-choice +text-decoration-line: spelling-error; +``` + +```css interactive-example-choice +text-decoration-line: underline overline; +``` + +```css interactive-example-choice +text-decoration-line: underline line-through; +``` + +```html interactive-example +<section id="default-example"> + <p> + I'd far rather be + <span class="transition-all" id="example-element">happy than right</span> + any day. + </p> +</section> +``` + +```css interactive-example +p { + font: 1.5em sans-serif; +} +``` When setting multiple line-decoration properties at once, it may be more convenient to use the {{cssxref("text-decoration")}} shorthand property instead. @@ -22,6 +70,8 @@ text-decoration-line: underline; text-decoration-line: overline; text-decoration-line: line-through; text-decoration-line: blink; +text-decoration-line: spelling-error; +text-decoration-line: grammar-error; /* Multiple keywords */ text-decoration-line: underline overline; /* Two decoration lines */ @@ -49,6 +99,13 @@ The `text-decoration-line` property is specified as `none`, or **one or more** s - : Each line of text has a decorative line going through its middle. - `blink` - : The text blinks (alternates between visible and invisible). Conforming user agents may not blink the text. This value is **deprecated** in favor of [CSS animations](/en-US/docs/Web/CSS/animation). +- `spelling-error` + - : Each line of text uses the user agents' method of highlighting spelling mistakes, which is a dotted red line in most browsers. +- `grammar-error` + - : Each line of text uses the user agents' method of highlighting grammar mistakes, which is a dotted green line in most browsers. + +> [!NOTE] +> When using `spelling-error` and `grammar-error` values, the browser disregards the other properties in the {{cssxref("text-decoration")}} shorthand (such as {{cssxref("text-underline-position")}}, `color`, or `stroke`). ## Formal definition @@ -79,7 +136,30 @@ The `text-decoration-line` property is specified as `none`, or **one or more** s } ``` -{{EmbedLiveSample('Examples')}} +{{EmbedLiveSample('basic_example',,90)}} + +### Errors example + +In this example, the first paragraph contains a spelling mistake and uses the browser's styling for spelling errors on the misspelled word. The second paragraph uses the browser's styling for grammar errors. There is no styling change in browsers that do not support these `text-decoration-line` values. + +<!-- cSpell:ignore speling --> + +```html +<p>This text contains a <span class="spelling">speling</span> mistake.</p> +<p class="grammar">This text contain grammatical errors.</p> +``` + +```css +.spelling { + text-decoration-line: spelling-error; +} + +.grammar { + text-decoration-line: grammar-error; +} +``` + +{{EmbedLiveSample('errors_example',,90)}} ## Specifications @@ -96,3 +176,5 @@ The `text-decoration-line` property is specified as `none`, or **one or more** s - {{cssxref("text-decoration-color")}} - {{cssxref("text-decoration-thickness")}} - {{cssxref("text-underline-offset")}} +- {{cssxref("::spelling-error")}} +- {{cssxref("::grammar-error")}} diff --git a/files/en-us/web/css/text-decoration-skip-ink/index.md b/files/en-us/web/css/text-decoration-skip-ink/index.md index 04ea4a1dfb55d60..a92f84bf38983c8 100644 --- a/files/en-us/web/css/text-decoration-skip-ink/index.md +++ b/files/en-us/web/css/text-decoration-skip-ink/index.md @@ -9,7 +9,32 @@ browser-compat: css.properties.text-decoration-skip-ink The **`text-decoration-skip-ink`** [CSS](/en-US/docs/Web/CSS) property specifies how overlines and underlines are drawn when they pass over glyph ascenders and descenders. -{{EmbedInteractiveExample("pages/css/text-decoration-skip-ink.html")}} +{{InteractiveExample("CSS Demo: text-decoration-skip-ink")}} + +```css interactive-example-choice +text-decoration-skip-ink: auto; +``` + +```css interactive-example-choice +text-decoration-skip-ink: none; +``` + +```html interactive-example +<section id="default-example"> + <p> + <span class="transition-all" id="example-element">parapsychologists</span> + </p> +</section> +``` + +```css interactive-example +p { + font: + 1.9em Georgia, + serif; + text-decoration: underline; +} +``` `text-decoration-skip-ink` is not part of the {{cssxref("text-decoration")}} shorthand. diff --git a/files/en-us/web/css/text-decoration-style/index.md b/files/en-us/web/css/text-decoration-style/index.md index 4668ca445526e27..9630252ebf2bde5 100644 --- a/files/en-us/web/css/text-decoration-style/index.md +++ b/files/en-us/web/css/text-decoration-style/index.md @@ -9,7 +9,47 @@ browser-compat: css.properties.text-decoration-style The **`text-decoration-style`** [CSS](/en-US/docs/Web/CSS) property sets the style of the lines specified by {{ cssxref("text-decoration-line") }}. The style applies to all lines that are set with `text-decoration-line`. -{{EmbedInteractiveExample("pages/css/text-decoration-style.html")}} +{{InteractiveExample("CSS Demo: text-decoration-style")}} + +```css interactive-example-choice +text-decoration-style: solid; +``` + +```css interactive-example-choice +text-decoration-style: double; +``` + +```css interactive-example-choice +text-decoration-style: dotted; +``` + +```css interactive-example-choice +text-decoration-style: dashed; +``` + +```css interactive-example-choice +text-decoration-style: wavy; +``` + +```html interactive-example +<section id="default-example"> + <p> + I'd far rather be + <span class="transition-all" id="example-element">happy than right</span> + any day. + </p> +</section> +``` + +```css interactive-example +p { + font: 1.5em sans-serif; +} + +#example-element { + text-decoration-line: underline; +} +``` If the specified decoration has a specific semantic meaning, like a line-through line meaning that some text has been deleted, authors are encouraged to denote this meaning using an HTML tag, like {{ HTMLElement("del") }} or {{ HTMLElement("s") }}. As browsers can disable styling in some cases, the semantic meaning won't disappear in such a situation. diff --git a/files/en-us/web/css/text-decoration-thickness/index.md b/files/en-us/web/css/text-decoration-thickness/index.md index 64e3311ab05164b..b325d8811228095 100644 --- a/files/en-us/web/css/text-decoration-thickness/index.md +++ b/files/en-us/web/css/text-decoration-thickness/index.md @@ -9,7 +9,38 @@ browser-compat: css.properties.text-decoration-thickness The **`text-decoration-thickness`** [CSS](/en-US/docs/Web/CSS) property sets the stroke thickness of the decoration line that is used on text in an element, such as a line-through, underline, or overline. -{{EmbedInteractiveExample("pages/css/text-decoration-thickness.html")}} +{{InteractiveExample("CSS Demo: text-decoration-thickness")}} + +```css interactive-example-choice +text-decoration-line: underline; +text-decoration-thickness: 3px; +``` + +```css interactive-example-choice +text-decoration-line: line-through; +text-decoration-thickness: 0.4rem; +``` + +```css interactive-example-choice +text-decoration-line: underline overline; +text-decoration-thickness: from-font; +font-size: 2rem; +``` + +```html interactive-example +<section id="default-example"> + <p id="example-element"> + Confusion kissed me on the cheek, and left a taste so bittersweet + </p> +</section> +``` + +```css interactive-example +p { + font: 1.5em sans-serif; + text-decoration-color: #ff0000; +} +``` ## Syntax diff --git a/files/en-us/web/css/text-decoration/index.md b/files/en-us/web/css/text-decoration/index.md index f314389c92f878b..dcef1c283eea79e 100644 --- a/files/en-us/web/css/text-decoration/index.md +++ b/files/en-us/web/css/text-decoration/index.md @@ -9,7 +9,43 @@ browser-compat: css.properties.text-decoration The **`text-decoration`** [shorthand](/en-US/docs/Web/CSS/CSS_cascade/Shorthand_properties) [CSS](/en-US/docs/Web/CSS) property sets the appearance of decorative lines on text. It is a shorthand for {{cssxref("text-decoration-line")}}, {{cssxref("text-decoration-color")}}, {{cssxref("text-decoration-style")}}, and the newer {{cssxref("text-decoration-thickness")}} property. -{{EmbedInteractiveExample("pages/css/text-decoration.html")}} +{{InteractiveExample("CSS Demo: text-decoration")}} + +```css interactive-example-choice +text-decoration: underline; +``` + +```css interactive-example-choice +text-decoration: underline dotted; +``` + +```css interactive-example-choice +text-decoration: underline dotted red; +``` + +```css interactive-example-choice +text-decoration: green wavy underline; +``` + +```css interactive-example-choice +text-decoration: underline overline #ff3028; +``` + +```html interactive-example +<section id="default-example"> + <p> + I'd far rather be + <span class="transition-all" id="example-element">happy than right</span> + any day. + </p> +</section> +``` + +```css interactive-example +p { + font: 1.5em sans-serif; +} +``` Text decorations are drawn across descendant text elements. This means that if an element specifies a text decoration, then a child element can't remove the decoration. For example, in the markup `<p>This text has <em>some emphasized words</em> in it.</p>`, the style rule `p { text-decoration: underline; }` would cause the entire paragraph to be underlined. The style rule `em { text-decoration: none; }` would not cause any change; the entire paragraph would still be underlined. However, the rule `em { text-decoration: overline; }` would cause a second decoration to appear on "some emphasized words". diff --git a/files/en-us/web/css/text-edge/index.md b/files/en-us/web/css/text-edge/index.md index 2d5d8bfa49434e1..f84b3963fc11aeb 100644 --- a/files/en-us/web/css/text-edge/index.md +++ b/files/en-us/web/css/text-edge/index.md @@ -7,7 +7,7 @@ browser-compat: css.types.text-edge {{CSSRef}} -The **`<text-edge>`** {{glossary("enumerated")}} [data type](/en-US/docs/Web/CSS/CSS_Types) defines keywords that specify font metrics representing specific regions on a font's block-start edge and block-end edge. Each keyword specifies a position of a font's over and/or under edge. +The **`<text-edge>`** {{glossary("enumerated")}} [data type](/en-US/docs/Web/CSS/CSS_Values_and_Units/CSS_data_types) defines keywords that specify font metrics representing specific regions on a font's block-start edge and block-end edge. Each keyword specifies a position of a font's over and/or under edge. The `<text-edge>` values are used in the {{cssxref("text-box-edge")}} property to specify an amount of space to trim from the block-start and block-end edge of a text element's block container. @@ -20,7 +20,7 @@ The `<text-edge>` values are used in the {{cssxref("text-box-edge")}} property t ``` > [!NOTE] -> The `ideographic` and `ideographic-ink` keywords are intended to specify over and under edge positions specific to [CJK language characters](https://en.wikipedia.org/wiki/CJK_characters). Currently their exact behavior is being debated and they are are not supported by any browser. +> The `ideographic` and `ideographic-ink` keywords are intended to specify over and under edge positions specific to [CJK language characters](https://en.wikipedia.org/wiki/CJK_characters). Currently their exact behavior is being debated and they are not supported by any browser. ## Values diff --git a/files/en-us/web/css/text-emphasis-color/index.md b/files/en-us/web/css/text-emphasis-color/index.md index dacd4cf0d98d3f9..8fc75be0a1f41e0 100644 --- a/files/en-us/web/css/text-emphasis-color/index.md +++ b/files/en-us/web/css/text-emphasis-color/index.md @@ -9,7 +9,39 @@ browser-compat: css.properties.text-emphasis-color The **`text-emphasis-color`** [CSS](/en-US/docs/Web/CSS) property sets the color of emphasis marks. This value can also be set using the {{cssxref("text-emphasis")}} shorthand. -{{EmbedInteractiveExample("pages/css/text-emphasis-color.html")}} +{{InteractiveExample("CSS Demo: text-emphasis-color")}} + +```css interactive-example-choice +text-emphasis-color: currentColor; +``` + +```css interactive-example-choice +text-emphasis-color: red; +``` + +```css interactive-example-choice +text-emphasis-color: rgba(90, 200, 160, 0.8); +``` + +```html interactive-example +<section id="default-example"> + <p> + I'd far rather be + <span class="transition-all" id="example-element">happy than right</span> + any day. + </p> +</section> +``` + +```css interactive-example +p { + font: 1.5em sans-serif; +} + +#example-element { + text-emphasis: filled; +} +``` ## Syntax diff --git a/files/en-us/web/css/text-emphasis-position/index.md b/files/en-us/web/css/text-emphasis-position/index.md index 376222087a3234a..1903fb8bccafec5 100644 --- a/files/en-us/web/css/text-emphasis-position/index.md +++ b/files/en-us/web/css/text-emphasis-position/index.md @@ -7,9 +7,56 @@ browser-compat: css.properties.text-emphasis-position {{CSSRef}} -The **`text-emphasis-position`** [CSS](/en-US/docs/Web/CSS) property sets where emphasis marks are drawn. Similar to the text rendered by the [`<ruby>`](/en-US/docs/Web/HTML/Element/ruby) HTML element, if there isn't enough room for emphasis marks, the line height is increased. +The **`text-emphasis-position`** [CSS](/en-US/docs/Web/CSS) property sets where emphasis marks are drawn. Similar to the text rendered by the [`<ruby>`](/en-US/docs/Web/HTML/Reference/Elements/ruby) HTML element, if there isn't enough room for emphasis marks, the line height is increased. -{{EmbedInteractiveExample("pages/css/text-emphasis-position.html")}} +{{InteractiveExample("CSS Demo: text-emphasis-position")}} + +```css interactive-example-choice +text-emphasis-position: auto; +``` + +```css interactive-example-choice +text-emphasis-position: over right; +``` + +```css interactive-example-choice +text-emphasis-position: under right; +``` + +```css interactive-example-choice +text-emphasis-position: auto; +writing-mode: vertical-rl; +``` + +```css interactive-example-choice +text-emphasis-position: over left; +writing-mode: vertical-rl; +``` + +```css interactive-example-choice +text-emphasis-position: over right; +writing-mode: vertical-rl; +``` + +```html interactive-example +<section id="default-example"> + <p> + I'd far rather be + <span class="transition-all" id="example-element">happy than right</span> + any day. + </p> +</section> +``` + +```css interactive-example +p { + font: 1.5em sans-serif; +} + +#example-element { + text-emphasis: filled double-circle #ffb703; +} +``` ## Syntax @@ -44,7 +91,7 @@ text-emphasis-position: unset; The property accepts one or two values: - If only one value is provided, it can be `auto`, `over`, or `under`. When only `over` or `under` is used, `right` is assumed as the default position. -- If two values are provided, they must include one of `over` or `under`and one of `right` or `left`. Their order does not matter. +- If two values are provided, they must include one of `over` or `under` and one of `right` or `left`. Their order does not matter. The values include: @@ -139,8 +186,10 @@ Use the drop down menu to change the position of the emphasis marks. This will c #### HTML ```html hidden -<p class="unsupported">The <code>auto</code> value is not supported in your browser.</p> -<label for="position">Emphasis position:</position> +<p class="unsupported"> + The <code>auto</code> value is not supported in your browser. +</p> +<label for="position">Emphasis position:</label> <select id="position"> <option value="auto">auto</option> <option value="over-right">over right</option> diff --git a/files/en-us/web/css/text-emphasis-style/index.md b/files/en-us/web/css/text-emphasis-style/index.md index 7ad495e687b8b98..f516717ef0db061 100644 --- a/files/en-us/web/css/text-emphasis-style/index.md +++ b/files/en-us/web/css/text-emphasis-style/index.md @@ -9,7 +9,39 @@ browser-compat: css.properties.text-emphasis-style The **`text-emphasis-style`** [CSS](/en-US/docs/Web/CSS) property sets the appearance of emphasis marks. It can also be set, and reset, using the {{cssxref("text-emphasis")}} shorthand. -{{EmbedInteractiveExample("pages/css/text-emphasis-style.html")}} +{{InteractiveExample("CSS Demo: text-emphasis-style")}} + +```css interactive-example-choice +text-emphasis-style: none; +``` + +```css interactive-example-choice +text-emphasis-style: triangle; +``` + +```css interactive-example-choice +text-emphasis-style: "x"; +``` + +```css interactive-example-choice +text-emphasis-style: filled double-circle; +``` + +```html interactive-example +<section id="default-example"> + <p> + I'd far rather be + <span class="transition-all" id="example-element">happy than right</span> + any day. + </p> +</section> +``` + +```css interactive-example +p { + font: 1.5em sans-serif; +} +``` ## Syntax diff --git a/files/en-us/web/css/text-emphasis/index.md b/files/en-us/web/css/text-emphasis/index.md index 56629b1bcc79379..9930d20ad0fb142 100644 --- a/files/en-us/web/css/text-emphasis/index.md +++ b/files/en-us/web/css/text-emphasis/index.md @@ -9,7 +9,39 @@ browser-compat: css.properties.text-emphasis The **`text-emphasis`** [CSS](/en-US/docs/Web/CSS) property applies emphasis marks to text (except spaces and control characters). It is a [shorthand](/en-US/docs/Web/CSS/CSS_cascade/Shorthand_properties) for {{cssxref("text-emphasis-style")}} and {{cssxref("text-emphasis-color")}}. -{{EmbedInteractiveExample("pages/css/text-emphasis.html")}} +{{InteractiveExample("CSS Demo: text-emphasis")}} + +```css interactive-example-choice +text-emphasis: none; +``` + +```css interactive-example-choice +text-emphasis: filled red; +``` + +```css interactive-example-choice +text-emphasis: "x"; +``` + +```css interactive-example-choice +text-emphasis: filled double-circle #ffb703; +``` + +```html interactive-example +<section id="default-example"> + <p> + I'd far rather be + <span class="transition-all" id="example-element">happy than right</span> + any day. + </p> +</section> +``` + +```css interactive-example +p { + font: 1.5em sans-serif; +} +``` The `text-emphasis` property is quite different from {{cssxref("text-decoration")}}. The `text-decoration` property does not inherit, and the decoration specified is applied across the whole element. However, text-emphasis does inherit, which means it is possible to change emphasis marks for descendants. diff --git a/files/en-us/web/css/text-indent/index.md b/files/en-us/web/css/text-indent/index.md index ffbe06836579121..306fa497d008030 100644 --- a/files/en-us/web/css/text-indent/index.md +++ b/files/en-us/web/css/text-indent/index.md @@ -9,7 +9,62 @@ browser-compat: css.properties.text-indent The **`text-indent`** [CSS](/en-US/docs/Web/CSS) property sets the length of empty space (indentation) that is put before lines of text in a block. -{{EmbedInteractiveExample("pages/css/text-indent.html")}} +{{InteractiveExample("CSS Demo: text-indent")}} + +```css interactive-example-choice +text-indent: 0; +``` + +```css interactive-example-choice +text-indent: 30%; +``` + +```css interactive-example-choice +text-indent: -3em; +``` + +```css interactive-example-choice +text-indent: 3em each-line; +``` + +```css interactive-example-choice +text-indent: 3em hanging; +``` + +```css interactive-example-choice +text-indent: 3em hanging each-line; +``` + +```html interactive-example +<section id="default-example"> + <div id="example-element"> + <p> + This text is contained within a single paragraph. This paragraph is two + sentences long. + </p> + <p> + This is a new paragraph. There is a line break element + <code>&lt;br&gt;</code> after this sentence.<br />There it is! Notice how + it affects the indentation. + </p> + </div> +</section> +``` + +```css interactive-example +section { + font-size: 1.25em; + background-color: #483d8b; + align-items: start; +} + +#example-element { + text-align: left; + margin: 0 0 0 3em; + background-color: #6a5acd; + color: white; +} +``` Horizontal spacing is with respect to the left (or right, for right-to-left layout) edge of the containing block-level element's content box. @@ -88,7 +143,7 @@ p { ### Skipping indentation on the first paragraph -A common typographic practice when paragraph indentation is present is to skip the indentation for the first paragraph. As the _The Chicago Manual of Style_ puts it, "the first line of text following a subhead may begin flush left or be indented by the usual paragraph indention." +A common typographic practice when paragraph indentation is present is to skip the indentation for the first paragraph. As _The Chicago Manual of Style_ puts it, "the first line of text following a subhead may begin flush left or be indented by the usual paragraph indention." Treating first paragraphs differently from subsequent paragraphs can be done using the [next-sibling combinator](/en-US/docs/Web/CSS/Next-sibling_combinator), as in the following example: diff --git a/files/en-us/web/css/text-orientation/index.md b/files/en-us/web/css/text-orientation/index.md index cbf82448c690096..2ac482c994110c3 100644 --- a/files/en-us/web/css/text-orientation/index.md +++ b/files/en-us/web/css/text-orientation/index.md @@ -9,7 +9,28 @@ browser-compat: css.properties.text-orientation The **`text-orientation`** [CSS](/en-US/docs/Web/CSS) property sets the orientation of the text characters in a line. It only affects text in vertical mode (when {{cssxref("writing-mode")}} is not `horizontal-tb`). It is useful for controlling the display of languages that use vertical script, and also for making vertical table headers. -{{EmbedInteractiveExample("pages/css/text-orientation.html")}} +{{InteractiveExample("CSS Demo: text-orientation")}} + +```css interactive-example-choice +writing-mode: vertical-rl; +text-orientation: mixed; +``` + +```css interactive-example-choice +writing-mode: vertical-rl; +text-orientation: upright; +``` + +```html interactive-example +<section class="default-example" id="default-example"> + <div class="transition-all" id="example-element"> + <p> + In another moment down went Alice after it, never once considering how in + the world she was to get out again. + </p> + </div> +</section> +``` ## Syntax diff --git a/files/en-us/web/css/text-overflow/index.md b/files/en-us/web/css/text-overflow/index.md index 32938767afdbf13..9e941707e8392ad 100644 --- a/files/en-us/web/css/text-overflow/index.md +++ b/files/en-us/web/css/text-overflow/index.md @@ -9,7 +9,48 @@ browser-compat: css.properties.text-overflow The **`text-overflow`** [CSS](/en-US/docs/Web/CSS) property sets how hidden overflow content is signaled to users. It can be clipped, display an ellipsis (`…`), or display a custom string. -{{EmbedInteractiveExample("pages/css/text-overflow.html")}} +{{InteractiveExample("CSS Demo: text-overflow")}} + +```css interactive-example-choice +text-overflow: clip; +``` + +```css interactive-example-choice +text-overflow: ellipsis; +``` + +```css interactive-example-choice +text-overflow: "-"; +``` + +```css interactive-example-choice +text-overflow: ""; +``` + +```html interactive-example +<section id="default-example"> + <div id="example-element-container"> + <p id="example-element">"Is there any tea on this spaceship?" he asked.</p> + </div> +</section> +``` + +```css interactive-example +#example-element-container { + width: 100%; + max-width: 18em; +} + +#example-element { + line-height: 50px; + border: 1px solid #c5c5c5; + overflow: hidden; + white-space: nowrap; + font-family: sans-serif; + padding: 0 0.5em; + text-align: left; +} +``` The `text-overflow` property doesn't force an overflow to occur. To make text overflow its container, you have to set other CSS properties: {{cssxref("overflow")}} and {{cssxref("white-space")}}. For example: diff --git a/files/en-us/web/css/text-rendering/index.md b/files/en-us/web/css/text-rendering/index.md index 599e38712230b88..5cca1029d7135be 100644 --- a/files/en-us/web/css/text-rendering/index.md +++ b/files/en-us/web/css/text-rendering/index.md @@ -36,11 +36,23 @@ text-rendering: unset; ### Values - `auto` + - : The browser makes educated guesses about when to optimize for speed, legibility, and geometric precision while drawing text. For differences in how this value is interpreted by the browser, see the compatibility table. + + The `auto` value is a good default for balancing quality and performance, especially for extended bodies of plain text. + - `optimizeSpeed` + - : The browser emphasizes rendering speed over legibility and geometric precision when drawing text. It disables kerning and ligatures. + + The `optimizeSpeed` value is preferable in resource-constrained rendering scenarios, such as slow processors or low battery. + - `optimizeLegibility` + - : The browser emphasizes legibility over rendering speed and geometric precision. This enables kerning and optional ligatures. + + The `optimizeLegibility` value is preferable for texts that are large in size but short in content, such as headers or banners, to enhance their readability. It could also be used for high-quality professional typography such as published articles. It's not recommended for typical articles due to potential performance impacts. + - `geometricPrecision` - : The browser emphasizes geometric precision over rendering speed and legibility. Certain aspects of fonts — such as kerning — don't scale linearly. So this value can make text using those fonts look good. @@ -49,6 +61,8 @@ text-rendering: unset; But the `geometricPrecision` property — when fully supported by the rendering engine — lets you scale your text fluidly. For large scale factors, you might see less-than-beautiful text rendering, but the size is what you would expect—neither rounded up nor down to the nearest font size supported by Windows or Linux. + The `geometricPrecision` value optimizes neither readability nor performance. It usually makes sense in SVG, where you want your graphic to scale faithfully without distorting the text dimensions. + > [!NOTE] > WebKit precisely applies the specified value, but Gecko treats the value the same as `optimizeLegibility`. @@ -153,4 +167,4 @@ p { - [`text-transform`](/en-US/docs/Web/CSS/text-transform) - The [SVG](/en-US/docs/Web/SVG) {{SVGAttr("text-rendering")}} attribute -- [SVG and CSS](/en-US/docs/Web/SVG/Tutorial/SVG_and_CSS) +- [SVG and CSS](/en-US/docs/Web/SVG/Tutorials/SVG_from_scratch/SVG_and_CSS) diff --git a/files/en-us/web/css/text-shadow/index.md b/files/en-us/web/css/text-shadow/index.md index 22693c0d5175a1a..0f81cdd317198a1 100644 --- a/files/en-us/web/css/text-shadow/index.md +++ b/files/en-us/web/css/text-shadow/index.md @@ -9,7 +9,51 @@ browser-compat: css.properties.text-shadow The **`text-shadow`** [CSS](/en-US/docs/Web/CSS) property adds shadows to text. It accepts a comma-separated list of shadows to be applied to the text and any of its [`decorations`](/en-US/docs/Web/CSS/text-decoration). Each shadow is described by some combination of X and Y offsets from the element, blur radius, and color. -{{EmbedInteractiveExample("pages/css/text-shadow.html")}} +{{InteractiveExample("CSS Demo: text-shadow")}} + +```css interactive-example-choice +text-shadow: 1px 1px 2px pink; +``` + +```css interactive-example-choice +text-shadow: #fc0 1px 0 10px; +``` + +```css interactive-example-choice +text-shadow: 5px 5px #558abb; +``` + +```css interactive-example-choice +text-shadow: red 2px 5px; +``` + +```css interactive-example-choice +text-shadow: 5px 10px; +``` + +```css interactive-example-choice +text-shadow: + 1px 1px 2px red, + 0 0 1em blue, + 0 0 0.2em blue; +``` + +```html interactive-example +<section id="default-example"> + <p id="example-element"> + Far out in the uncharted backwaters of the unfashionable end of the western + spiral arm of the Galaxy... + </p> +</section> +``` + +```css interactive-example +p { + font: + 1.5em Georgia, + serif; +} +``` ## Syntax diff --git a/files/en-us/web/css/text-transform/index.md b/files/en-us/web/css/text-transform/index.md index b98924b77c9d1c7..bc63870ae8fb6e1 100644 --- a/files/en-us/web/css/text-transform/index.md +++ b/files/en-us/web/css/text-transform/index.md @@ -9,7 +9,57 @@ browser-compat: css.properties.text-transform The **`text-transform`** [CSS](/en-US/docs/Web/CSS) property specifies how to capitalize an element's text. It can be used to make text appear in all-uppercase or all-lowercase, or with each word capitalized. It also can help improve legibility for ruby. -{{EmbedInteractiveExample("pages/css/text-transform.html")}} +{{InteractiveExample("CSS Demo: text-transform")}} + +```css interactive-example-choice +text-transform: capitalize; +``` + +```css interactive-example-choice +text-transform: uppercase; +``` + +```css interactive-example-choice +text-transform: lowercase; +``` + +```css interactive-example-choice +text-transform: none; +``` + +```css interactive-example-choice +text-transform: full-width; +``` + +```css interactive-example-choice +text-transform: full-size-kana; +``` + +```css interactive-example-choice +text-transform: math-auto; +``` + +```html interactive-example +<section id="default-example"> + <div class="transition-all" id="example-element"> + <p> + LONDON. Michaelmas term lately over, and the Lord Chancellor sitting in + Lincoln's Inn Hall. + </p> + <p lang="el"> + Σ is a Greek letter and appears in ΟΔΥΣΣΕΥΣ. Θα πάμε στο "Θεϊκό φαΐ" ή στη + "Νεράιδα" + </p> + <p lang="ja">ァィゥェ ォヵㇰヶ</p> + </div> +</section> +``` + +```css interactive-example +#example-element { + font-size: 1.2em; +} +``` The `text-transform` property takes into account language-specific case mapping rules such as the following: @@ -20,7 +70,7 @@ The `text-transform` property takes into account language-specific case mapping - In Greek (`el`), the lowercase sigma character has two forms: `σ` and `ς`. `ς` is used only when sigma terminates a word. When applying `text-transform: lowercase` to an uppercase sigma (`Σ`), the browser needs to choose the right lowercase form based on context. - in Irish (`ga`), certain prefixed letters remain in lowercase when the base initial is capitalized, so for example `text-transform: uppercase` will change `ar aon tslí` to `AR AON tSLÍ` and not, as one might expect, `AR AON TSLÍ` (Firefox only). In some cases, a hyphen is also removed upon uppercasing: `an t-uisce` transforms to `AN tUISCE` (and the hyphen is correctly reinserted by `text-transform: lowercase`). -The language is defined by the [`lang`](/en-US/docs/Web/HTML/Global_attributes/lang) HTML attribute or the [`xml:lang`](/en-US/docs/Web/SVG/Attribute/xml:lang) XML attribute. +The language is defined by the [`lang`](/en-US/docs/Web/HTML/Reference/Global_attributes/lang) HTML attribute or the [`xml:lang`](/en-US/docs/Web/SVG/Reference/Attribute/xml:lang) XML attribute. > [!NOTE] > Support for language-specific cases varies between browsers, so check the [browser compatibility table](#browser_compatibility). @@ -73,7 +123,7 @@ text-transform: unset; Large sections of text set with a `text-transform` value of `uppercase` may be difficult for people with cognitive concerns such as Dyslexia to read. -- [MDN Understanding WCAG, Guideline 1.4 explanations](/en-US/docs/Web/Accessibility/Understanding_WCAG/Perceivable#guideline_1.4_make_it_easier_for_users_to_see_and_hear_content_including_separating_foreground_from_background) +- [MDN Understanding WCAG, Guideline 1.4 explanations](/en-US/docs/Web/Accessibility/Guides/Understanding_WCAG/Perceivable#guideline_1.4_make_it_easier_for_users_to_see_and_hear_content_including_separating_foreground_from_background) - [W3C Understanding WCAG 2.1](https://www.w3.org/TR/WCAG21/#visual-presentation) ## Formal definition diff --git a/files/en-us/web/css/text-underline-offset/index.md b/files/en-us/web/css/text-underline-offset/index.md index 996748e9c118d5d..c65fa60514df141 100644 --- a/files/en-us/web/css/text-underline-offset/index.md +++ b/files/en-us/web/css/text-underline-offset/index.md @@ -9,7 +9,33 @@ browser-compat: css.properties.text-underline-offset The **`text-underline-offset`** [CSS](/en-US/docs/Web/CSS) property sets the offset distance of an underline text decoration line (applied using {{cssxref("text-decoration")}}) from its original position. -{{EmbedInteractiveExample("pages/css/text-underline-offset.html")}} +{{InteractiveExample("CSS Demo: text-underline-offset")}} + +```css interactive-example-choice +text-underline-offset: auto; +``` + +```css interactive-example-choice +text-underline-offset: 8px; +``` + +```css interactive-example-choice +text-underline-offset: -0.5rem; +``` + +```html interactive-example +<section id="default-example"> + <p id="example-element">And after all we are only ordinary</p> +</section> +``` + +```css interactive-example +p { + font: 1.5em sans-serif; + text-decoration-line: underline; + text-decoration-color: #ff0000; +} +``` `text-underline-offset` is not part of the {{cssxref('text-decoration')}} shorthand. While an element can have multiple `text-decoration` lines, `text-underline-offset` only impacts underlining, and **not** other possible line decoration options such as `overline` or `line-through`. diff --git a/files/en-us/web/css/text-underline-position/index.md b/files/en-us/web/css/text-underline-position/index.md index d9143e926651dba..ad13f6854415fa6 100644 --- a/files/en-us/web/css/text-underline-position/index.md +++ b/files/en-us/web/css/text-underline-position/index.md @@ -9,7 +9,36 @@ browser-compat: css.properties.text-underline-position The **`text-underline-position`** [CSS](/en-US/docs/Web/CSS) property specifies the position of the underline which is set using the {{cssxref("text-decoration")}} property's `underline` value. -{{EmbedInteractiveExample("pages/css/text-underline-position.html")}} +{{InteractiveExample("CSS Demo: text-underline-position")}} + +```css interactive-example-choice +text-underline-position: auto; +``` + +```css interactive-example-choice +text-underline-position: under; +``` + +```html interactive-example +<section id="default-example"> + <p> + <span class="transition-all" id="example-element" + >C<sub>8</sub>H<sub>10</sub>N<sub>4</sub>O<sub>2</sub></span + > + is the chemical formula for caffeine. + </p> +</section> +``` + +```css interactive-example +p { + font: 1.5em sans-serif; +} + +#example-element { + text-decoration-line: underline; +} +``` ## Syntax diff --git a/files/en-us/web/css/text-wrap-mode/index.md b/files/en-us/web/css/text-wrap-mode/index.md index ad22ef69dc51f40..d7d17b3dce78886 100644 --- a/files/en-us/web/css/text-wrap-mode/index.md +++ b/files/en-us/web/css/text-wrap-mode/index.md @@ -15,7 +15,43 @@ The **`text-wrap-mode`** [CSS](/en-US/docs/Web/CSS) property controls whether th > [!NOTE] > The name of this property is a placeholder, pending the CSSWG finding a better name. -{{EmbedInteractiveExample("pages/css/text-wrap-mode.html")}} +{{InteractiveExample("CSS Demo: text-wrap-mode")}} + +```css interactive-example-choice +text-wrap-mode: wrap; +``` + +```css interactive-example-choice +text-wrap-mode: nowrap; +``` + +```html interactive-example +<section class="default-example" id="default-example"> + <div class="whole-content-wrapper"> + <p>Edit the text in the box:</p> + <div class="transition-all" id="example-element"> + <p contenteditable=""> + Lorem ipsum dolor sit amet consectetur adipisicing elit. Voluptatem aut + cum eum id quos est. + </p> + </div> + </div> +</section> +``` + +```css interactive-example +.whole-content-wrapper { + display: flex; + flex-direction: column; + align-items: center; + width: 100%; +} + +#example-element { + border: 1px solid #c5c5c5; + width: 250px; +} +``` ## Syntax diff --git a/files/en-us/web/css/text-wrap-style/index.md b/files/en-us/web/css/text-wrap-style/index.md index d9572b74c6c88c0..d073d2ececa8501 100644 --- a/files/en-us/web/css/text-wrap-style/index.md +++ b/files/en-us/web/css/text-wrap-style/index.md @@ -9,7 +9,51 @@ browser-compat: css.properties.text-wrap-style The **`text-wrap-style`** [CSS](/en-US/docs/Web/CSS) property controls how text inside an element is wrapped. The different values provide alternate ways of wrapping the content of a block element. It can also be set, and reset, using the {{CSSXRef("text-wrap")}} shorthand. -{{EmbedInteractiveExample("pages/css/text-wrap-style.html")}} +{{InteractiveExample("CSS Demo: text-wrap-style")}} + +```css interactive-example-choice +text-wrap-style: auto; +``` + +```css interactive-example-choice +text-wrap-style: balance; +``` + +```css interactive-example-choice +text-wrap-style: pretty; +``` + +```css interactive-example-choice +text-wrap-style: stable; +``` + +```html interactive-example +<section class="default-example" id="default-example"> + <div class="whole-content-wrapper"> + <p>Edit the text in the box:</p> + <div class="transition-all" id="example-element"> + <p contenteditable=""> + Lorem ipsum dolor sit amet consectetur adipisicing elit. Voluptatem aut + cum eum id quos est. + </p> + </div> + </div> +</section> +``` + +```css interactive-example +.whole-content-wrapper { + display: flex; + flex-direction: column; + align-items: center; + width: 100%; +} + +#example-element { + border: 1px solid #c5c5c5; + width: 250px; +} +``` ## Syntax @@ -54,7 +98,7 @@ When the styled content will be limited to a short number of lines, such as head For longer sections of text, `text-wrap-style: pretty` can be used. Note that `pretty` has a negative effect on performance, so it should be only used for longer blocks of text when the layout is more important than speed. -The `stable` value improves user experience when used on content that is [`contenteditable`](/en-US/docs/Web/HTML/Global_attributes/contenteditable). This value ensures that, as the user is editing text, the previous lines in the area being edited remain stable. +The `stable` value improves user experience when used on content that is [`contenteditable`](/en-US/docs/Web/HTML/Reference/Global_attributes/contenteditable). This value ensures that, as the user is editing text, the previous lines in the area being edited remain stable. ## Formal definition diff --git a/files/en-us/web/css/text-wrap/index.md b/files/en-us/web/css/text-wrap/index.md index db3d1cf9f48369b..0af455e24bd3ba7 100644 --- a/files/en-us/web/css/text-wrap/index.md +++ b/files/en-us/web/css/text-wrap/index.md @@ -12,7 +12,55 @@ The **`text-wrap`** CSS shorthand property controls how text inside an element i - Typographic improvements, for example more balanced line lengths across broken headings - A way to turn text wrapping off completely. -{{EmbedInteractiveExample("pages/css/text-wrap.html")}} +{{InteractiveExample("CSS Demo: text-wrap")}} + +```css interactive-example-choice +text-wrap: wrap; +``` + +```css interactive-example-choice +text-wrap: nowrap; +``` + +```css interactive-example-choice +text-wrap: balance; +``` + +```css interactive-example-choice +text-wrap: pretty; +``` + +```css interactive-example-choice +text-wrap: stable; +``` + +```html interactive-example +<section class="default-example" id="default-example"> + <div class="whole-content-wrapper"> + <p>Edit the text in the box:</p> + <div class="transition-all" id="example-element"> + <p contenteditable=""> + Lorem ipsum dolor sit amet consectetur adipisicing elit. Voluptatem aut + cum eum id quos est. + </p> + </div> + </div> +</section> +``` + +```css interactive-example +.whole-content-wrapper { + display: flex; + flex-direction: column; + align-items: center; + width: 100%; +} + +#example-element { + border: 1px solid #c5c5c5; + width: 250px; +} +``` ## Constituent properties @@ -64,7 +112,7 @@ When the styled content will be limited to a short number of lines, such as head For longer sections of text, `text-wrap: pretty` can be used. Note that `pretty` has a negative effect on performance, so it should be only used for longer blocks of text when the layout is more important than speed. -The `stable` value improves user experience when used on content that is [`contenteditable`](/en-US/docs/Web/HTML/Global_attributes/contenteditable). This value ensures that, as the user is editing text, the previous lines in the area being edited remain stable. +The `stable` value improves user experience when used on content that is [`contenteditable`](/en-US/docs/Web/HTML/Reference/Global_attributes/contenteditable). This value ensures that, as the user is editing text, the previous lines in the area being edited remain stable. ## Formal definition @@ -134,5 +182,6 @@ The text in the example is editable. Change the text, adding long words, to view - {{CSSxRef("white-space")}} - {{CSSxRef("white-space-collapse")}} - [CSS text module](/en-US/docs/Web/CSS/CSS_text) -- [CSS `text-wrap: balance`](https://developer.chrome.com/docs/css-ui/css-text-wrap-balance) on developer.chrome.com -- [CSS `text-wrap: pretty`](https://developer.chrome.com/blog/css-text-wrap-pretty/) on developer.chrome.com +- [CSS `text-wrap: balance`](https://developer.chrome.com/docs/css-ui/css-text-wrap-balance) on developer.chrome.com (2023) +- [CSS `text-wrap: pretty`](https://developer.chrome.com/blog/css-text-wrap-pretty/) on developer.chrome.com (2023) +- [Balancing Japanese and Korean typography](https://ryelle.codes/2025/04/typography-troubles-balancing-in-japanese-korean/) by Kelly Choyce-Dwan (2025) diff --git a/files/en-us/web/css/time-percentage/index.md b/files/en-us/web/css/time-percentage/index.md index e1f1a80fbe6a41d..0546f92a4e66161 100644 --- a/files/en-us/web/css/time-percentage/index.md +++ b/files/en-us/web/css/time-percentage/index.md @@ -2,7 +2,7 @@ title: <time-percentage> slug: Web/CSS/time-percentage page-type: css-type -browser-compat: css.types.time-percentage +spec-urls: https://drafts.csswg.org/css-values/#typedef-time-percentage --- {{CSSRef}} @@ -60,10 +60,6 @@ Where a `<time-percentage>` is specified as an allowable type, this means that t {{Specifications}} -## Browser compatibility - -{{Compat}} - ## See also - {{cssxref("&lt;percentage&gt;")}} diff --git a/files/en-us/web/css/timeline-scope/index.md b/files/en-us/web/css/timeline-scope/index.md index 766066b034ea278..1e6406195928259 100644 --- a/files/en-us/web/css/timeline-scope/index.md +++ b/files/en-us/web/css/timeline-scope/index.md @@ -11,7 +11,7 @@ browser-compat: css.properties.timeline-scope The **`timeline-scope`** [CSS](/en-US/docs/Web/CSS) property modifies the scope of a named animation timeline. -By default, a named timeline (i.e. declared using {{cssxref("scroll-timeline-name")}} or {{cssxref("view-timeline-name")}}) can only be set as the controlling timeline of a direct descendant element (i.e. by setting {{cssxref("animation-timeline")}} on it with the timeline name as its value). This is the timeline's default "scope". +By default, a named timeline (i.e., declared using {{cssxref("scroll-timeline-name")}} or {{cssxref("view-timeline-name")}}) can only be set as the controlling timeline of a direct descendant element (i.e., by setting {{cssxref("animation-timeline")}} on it with the timeline name as its value). This is the timeline's default "scope". `timeline-scope` is given the name of a timeline defined on a descendant element; this causes the scope of the timeline to be increased to the element that `timeline-scope` is set on and any of its descendants. In other words, that element and any of its descendant elements can now be controlled using that timeline. @@ -33,7 +33,7 @@ Allowed values for `timeline-scope` are: - : There is no change in timeline scope. - `<dashed-ident>` - - : Specifies the name of an existing named timeline (i.e. declared using {{cssxref("scroll-timeline-name")}} or {{cssxref("view-timeline-name")}}) defined on a descendant element. This causes the timeline scope to be increased to the element that `timeline-scope` is set on and any of its descendants. + - : Specifies the name of an existing named timeline (i.e., declared using {{cssxref("scroll-timeline-name")}} or {{cssxref("view-timeline-name")}}) defined on a descendant element. This causes the timeline scope to be increased to the element that `timeline-scope` is set on and any of its descendants. > **Note:** [`<dashed-ident>`](/en-US/docs/Web/CSS/custom-ident) values must start with `--`, which helps to avoid name clashes with standard CSS keywords. diff --git a/files/en-us/web/css/top/index.md b/files/en-us/web/css/top/index.md index 35679ac214dbf47..ae1ef8488013f55 100644 --- a/files/en-us/web/css/top/index.md +++ b/files/en-us/web/css/top/index.md @@ -9,7 +9,57 @@ browser-compat: css.properties.top The **`top`** [CSS](/en-US/docs/Web/CSS) property sets the vertical position of a [positioned element](/en-US/docs/Web/CSS/position). This {{glossary("inset properties", "inset property")}} has no effect on non-positioned elements. -{{EmbedInteractiveExample("pages/css/top.html")}} +{{InteractiveExample("CSS Demo: top")}} + +```css interactive-example-choice +top: 0; +``` + +```css interactive-example-choice +top: 4em; +``` + +```css interactive-example-choice +top: 10%; +``` + +```css interactive-example-choice +top: 20px; +``` + +```html interactive-example +<section id="default-example"> + <div class="example-container"> + <div id="example-element">I am absolutely positioned.</div> + <p> + As much mud in the streets as if the waters had but newly retired from the + face of the earth, and it would not be wonderful to meet a Megalosaurus, + forty feet long or so, waddling like an elephantine lizard up Holborn + Hill. + </p> + </div> +</section> +``` + +```css interactive-example +.example-container { + border: 0.75em solid; + padding: 0.75em; + text-align: left; + position: relative; + width: 100%; + min-height: 200px; +} + +#example-element { + background-color: #264653; + border: 4px solid #ffb500; + color: white; + position: absolute; + width: 140px; + height: 60px; +} +``` The effect of `top` depends on how the element is positioned (i.e., the value of the {{cssxref("position")}} property): @@ -66,9 +116,6 @@ top: unset; - for _absolutely positioned elements_, the position of the element is based on the {{Cssxref("bottom")}} property, while `height: auto` is treated as a height based on the content; or if `bottom` is also `auto`, the element is positioned where it should vertically be positioned if it were a static element. - for _relatively positioned elements_, the distance of the element from its normal position is based on the {{Cssxref("bottom")}} property; or if `bottom` is also `auto`, the element is not moved vertically at all. -- `inherit` - - : Specifies that the value is the same as the computed value from its parent element (which might not be its containing block). This computed value is then handled as if it were a {{cssxref("&lt;length&gt;")}}, {{cssxref("&lt;percentage&gt;")}}, or the `auto` keyword. - ## Formal definition {{CSSInfo}} diff --git a/files/en-us/web/css/touch-action/index.md b/files/en-us/web/css/touch-action/index.md index 1f2a45ac23fd312..b5a48998dc80e98 100644 --- a/files/en-us/web/css/touch-action/index.md +++ b/files/en-us/web/css/touch-action/index.md @@ -65,7 +65,7 @@ The `touch-action` property may be specified as either: A declaration of `touch-action: none;` may inhibit operating a browser's zooming capabilities. This will prevent people experiencing low vision conditions from being able to read and understand page content. -- [MDN Understanding WCAG, Guideline 1.4 explanations](/en-US/docs/Web/Accessibility/Understanding_WCAG/Perceivable#guideline_1.4_make_it_easier_for_users_to_see_and_hear_content_including_separating_foreground_from_background) +- [MDN Understanding WCAG, Guideline 1.4 explanations](/en-US/docs/Web/Accessibility/Guides/Understanding_WCAG/Perceivable#guideline_1.4_make_it_easier_for_users_to_see_and_hear_content_including_separating_foreground_from_background) - [Understanding Success Criterion 1.4.4 | Understanding WCAG 2.0](https://www.w3.org/TR/UNDERSTANDING-WCAG20/visual-audio-contrast-scale.html) ## Formal definition diff --git a/files/en-us/web/css/transform-function/index.md b/files/en-us/web/css/transform-function/index.md index 7c00609d10929fc..b836a3341176a09 100644 --- a/files/en-us/web/css/transform-function/index.md +++ b/files/en-us/web/css/transform-function/index.md @@ -247,12 +247,11 @@ const example = document.querySelector("#example-element"); selectElem.addEventListener("change", () => { if (selectElem.value === "Choose a function") { return; - } else { - example.style.transform = `rotate3d(1, 1, 1, 30deg) ${selectElem.value}`; - setTimeout(() => { - example.style.transform = "rotate3d(1, 1, 1, 30deg)"; - }, 2000); } + example.style.transform = `rotate3d(1, 1, 1, 30deg) ${selectElem.value}`; + setTimeout(() => { + example.style.transform = "rotate3d(1, 1, 1, 30deg)"; + }, 2000); }); ``` diff --git a/files/en-us/web/css/transform-function/matrix/index.md b/files/en-us/web/css/transform-function/matrix/index.md index a307eadd1ff5a6d..b9b3a628c590636 100644 --- a/files/en-us/web/css/transform-function/matrix/index.md +++ b/files/en-us/web/css/transform-function/matrix/index.md @@ -10,10 +10,33 @@ browser-compat: css.types.transform-function.matrix The **`matrix()`** [CSS](/en-US/docs/Web/CSS) [function](/en-US/docs/Web/CSS/CSS_Values_and_Units/CSS_Value_Functions) defines a homogeneous 2D transformation matrix. Its result is a {{cssxref("&lt;transform-function&gt;")}} data type. -{{EmbedInteractiveExample("pages/css/function-matrix.html")}} +{{InteractiveExample("CSS Demo: matrix()")}} -> **Note:** `matrix(a, b, c, d, tx, ty)` is a shorthand for -> `matrix3d(a, b, 0, 0, c, d, 0, 0, 0, 0, 1, 0, tx, ty, 0, 1)`. +```css interactive-example-choice +transform: matrix(1.2, 0.2, -1, 0.9, 0, 20); +``` + +```css interactive-example-choice +transform: matrix(0.4, 0, 0.5, 1.2, 60, 10); +``` + +```css interactive-example-choice +transform: matrix(0, 1, 1, 0, 0, 0); +``` + +```css interactive-example-choice +transform: matrix(0.1, 1, -0.3, 1, 0, 0); +``` + +```html interactive-example +<section id="default-example"> + <img + class="transition-all" + id="example-element" + src="/shared-assets/images/examples/firefox-logo.svg" + width="200" /> +</section> +``` ## Syntax @@ -24,6 +47,9 @@ parameters; the other parameters are described in the column-major order. matrix(a, b, c, d, tx, ty) ``` +> [!NOTE] +> The `matrix(a, b, c, d, tx, ty)` function is a shorthand for `matrix3d(a, b, 0, 0, c, d, 0, 0, 0, 0, 1, 0, tx, ty, 0, 1)`. + ### Values - _a_ _b_ _c_ _d_ diff --git a/files/en-us/web/css/transform-function/matrix3d/index.md b/files/en-us/web/css/transform-function/matrix3d/index.md index 64b79dcbdf56872..3fab37b5bb61aec 100644 --- a/files/en-us/web/css/transform-function/matrix3d/index.md +++ b/files/en-us/web/css/transform-function/matrix3d/index.md @@ -10,7 +10,59 @@ browser-compat: css.types.transform-function.matrix3d The **`matrix3d()`** [CSS](/en-US/docs/Web/CSS) [function](/en-US/docs/Web/CSS/CSS_Values_and_Units/CSS_Value_Functions) defines a 3D transformation as a 4x4 homogeneous matrix. Its result is a {{cssxref("&lt;transform-function&gt;")}} data type. -{{EmbedInteractiveExample("pages/css/function-matrix3d.html")}} +{{InteractiveExample("CSS Demo: matrix3d()")}} + +```css interactive-example-choice +transform: matrix3d( + -0.6, + 1.34788, + 0, + 0, + -2.34788, + -0.6, + 0, + 0, + 0, + 0, + 1, + 0, + 0, + 0, + 10, + 1 +); +``` + +```css interactive-example-choice +transform: matrix3d( + 0.5, + 0, + -0.866025, + 0, + 0.595877, + 1.2, + -1.03209, + 0, + 0.866025, + 0, + 0.5, + 0, + 25.9808, + 0, + 15, + 1 +); +``` + +```html interactive-example +<section id="default-example"> + <img + class="transition-all" + id="example-element" + src="/shared-assets/images/examples/firefox-logo.svg" + width="200" /> +</section> +``` ## Syntax diff --git a/files/en-us/web/css/transform-function/perspective/index.md b/files/en-us/web/css/transform-function/perspective/index.md index c07a4cf33907894..3645d71b348a968 100644 --- a/files/en-us/web/css/transform-function/perspective/index.md +++ b/files/en-us/web/css/transform-function/perspective/index.md @@ -11,7 +11,97 @@ The **`perspective()`** [CSS](/en-US/docs/Web/CSS) [function](/en-US/docs/Web/CS user and the z=0 plane, the perspective from which the viewer would be if the 2-dimensional interface were 3-dimensional. Its result is a {{cssxref("&lt;transform-function&gt;")}} data type. -{{EmbedInteractiveExample("pages/css/function-perspective.html")}} +{{InteractiveExample("CSS Demo: perspective()")}} + +```css interactive-example-choice +transform: perspective(0); +``` + +```css interactive-example-choice +transform: perspective(none); +``` + +```css interactive-example-choice +transform: perspective(800px); +``` + +```css interactive-example-choice +transform: perspective(23rem); +``` + +```css interactive-example-choice +transform: perspective(6.5cm); +``` + +```html interactive-example +<section class="default-example" id="default-example"> + <div class="transition-all" id="example-element"> + <div class="face front">1</div> + <div class="face back">2</div> + <div class="face right">3</div> + <div class="face left">4</div> + <div class="face top">5</div> + <div class="face bottom">6</div> + </div> +</section> +``` + +```css interactive-example +#default-example { + background: linear-gradient(skyblue, khaki); + perspective: 800px; + perspective-origin: 150% 150%; +} + +#example-element { + width: 100px; + height: 100px; + perspective: 550px; + transform-style: preserve-3d; +} + +.face { + display: flex; + align-items: center; + justify-content: center; + width: 100%; + height: 100%; + position: absolute; + backface-visibility: inherit; + font-size: 60px; + color: white; +} + +.front { + background: rgba(90, 90, 90, 0.7); + transform: translateZ(50px); +} + +.back { + background: rgba(0, 210, 0, 0.7); + transform: rotateY(180deg) translateZ(50px); +} + +.right { + background: rgba(210, 0, 0, 0.7); + transform: rotateY(90deg) translateZ(50px); +} + +.left { + background: rgba(0, 0, 210, 0.7); + transform: rotateY(-90deg) translateZ(50px); +} + +.top { + background: rgba(210, 210, 0, 0.7); + transform: rotateX(90deg) translateZ(50px); +} + +.bottom { + background: rgba(210, 0, 210, 0.7); + transform: rotateX(-90deg) translateZ(50px); +} +``` The `perspective()` transform function is part of the {{cssxref('transform')}} value applied on the element being transformed. This differs from the {{cssxref('perspective')}} and {{cssxref('perspective-origin')}} diff --git a/files/en-us/web/css/transform-function/rotate/index.md b/files/en-us/web/css/transform-function/rotate/index.md index fc3c23fa286440c..1a308862b81a2f2 100644 --- a/files/en-us/web/css/transform-function/rotate/index.md +++ b/files/en-us/web/css/transform-function/rotate/index.md @@ -11,7 +11,33 @@ The **`rotate()`** [CSS](/en-US/docs/Web/CSS) [function](/en-US/docs/Web/CSS/CSS fixed point on the 2D plane, without deforming it. Its result is a {{cssxref("&lt;transform-function&gt;")}} data type. -{{EmbedInteractiveExample("pages/css/function-rotate.html")}} +{{InteractiveExample("CSS Demo: rotate()")}} + +```css interactive-example-choice +transform: rotate(0); +``` + +```css interactive-example-choice +transform: rotate(90deg); +``` + +```css interactive-example-choice +transform: rotate(-0.25turn); +``` + +```css interactive-example-choice +transform: rotate(3.142rad); +``` + +```html interactive-example +<section id="default-example"> + <img + class="transition-all" + id="example-element" + src="/shared-assets/images/examples/firefox-logo.svg" + width="200" /> +</section> +``` The fixed point that the element rotates around — mentioned above — is also known as the **transform origin**. This defaults to the center of the element, but you can set your own custom transform origin using diff --git a/files/en-us/web/css/transform-function/rotate3d/index.md b/files/en-us/web/css/transform-function/rotate3d/index.md index f3535505c0a500c..e0b8bdaa0b3e5b1 100644 --- a/files/en-us/web/css/transform-function/rotate3d/index.md +++ b/files/en-us/web/css/transform-function/rotate3d/index.md @@ -10,7 +10,91 @@ browser-compat: css.types.transform-function.rotate3d The **`rotate3d()`** [CSS](/en-US/docs/Web/CSS) [function](/en-US/docs/Web/CSS/CSS_Values_and_Units/CSS_Value_Functions) defines a transformation that rotates an element around a fixed axis in 3D space, without deforming it. Its result is a {{cssxref("&lt;transform-function&gt;")}} data type. -{{EmbedInteractiveExample("pages/css/rotate3d.html")}} +{{InteractiveExample("CSS Demo: rotate3d()")}} + +```css interactive-example-choice +transform: rotate3d(0, 0, 0, 0); +``` + +```css interactive-example-choice +transform: rotate3d(1, 1, 1, 45deg); +``` + +```css interactive-example-choice +transform: rotate3d(2, -1, -1, -0.2turn); +``` + +```css interactive-example-choice +transform: rotate3d(0, 1, 0.5, 3.142rad); +``` + +```html interactive-example +<section class="default-example" id="default-example"> + <div class="transition-all" id="example-element"> + <div class="face front">1</div> + <div class="face back">2</div> + <div class="face right">3</div> + <div class="face left">4</div> + <div class="face top">5</div> + <div class="face bottom">6</div> + </div> +</section> +``` + +```css interactive-example +#default-example { + background: linear-gradient(skyblue, khaki); + perspective: 550px; +} + +#example-element { + width: 100px; + height: 100px; + transform-style: preserve-3d; +} + +.face { + display: flex; + align-items: center; + justify-content: center; + width: 100%; + height: 100%; + position: absolute; + backface-visibility: inherit; + font-size: 60px; + color: white; +} + +.front { + background: rgba(90, 90, 90, 0.7); + transform: translateZ(50px); +} + +.back { + background: rgba(0, 210, 0, 0.7); + transform: rotateY(180deg) translateZ(50px); +} + +.right { + background: rgba(210, 0, 0, 0.7); + transform: rotateY(90deg) translateZ(50px); +} + +.left { + background: rgba(0, 0, 210, 0.7); + transform: rotateY(-90deg) translateZ(50px); +} + +.top { + background: rgba(210, 210, 0, 0.7); + transform: rotateX(90deg) translateZ(50px); +} + +.bottom { + background: rgba(210, 0, 210, 0.7); + transform: rotateX(-90deg) translateZ(50px); +} +``` In 3D space, rotations have three degrees of freedom, which together describe a single axis of rotation. The axis of rotation is defined by an \[x, y, z] vector and pass by the origin (as defined by the {{ cssxref("transform-origin") }} diff --git a/files/en-us/web/css/transform-function/rotatex/index.md b/files/en-us/web/css/transform-function/rotatex/index.md index 748b6a910b97e75..c4a7bb443b1ec61 100644 --- a/files/en-us/web/css/transform-function/rotatex/index.md +++ b/files/en-us/web/css/transform-function/rotatex/index.md @@ -10,7 +10,33 @@ browser-compat: css.types.transform-function.rotateX The **`rotateX()`** [CSS](/en-US/docs/Web/CSS) [function](/en-US/docs/Web/CSS/CSS_Values_and_Units/CSS_Value_Functions) defines a transformation that rotates an element around the x-axis (horizontal) without deforming it. Its result is a {{cssxref("&lt;transform-function&gt;")}} data type. -{{EmbedInteractiveExample("pages/css/function-rotateX.html")}} +{{InteractiveExample("CSS Demo: rotateX()")}} + +```css interactive-example-choice +transform: rotateX(0); +``` + +```css interactive-example-choice +transform: rotateX(45deg); +``` + +```css interactive-example-choice +transform: rotateX(-0.2turn); +``` + +```css interactive-example-choice +transform: rotateX(3.142rad); +``` + +```html interactive-example +<section id="default-example"> + <img + class="transition-all" + id="example-element" + src="/shared-assets/images/examples/firefox-logo.svg" + width="200" /> +</section> +``` The axis of rotation passes through an origin, defined by the {{ cssxref("transform-origin") }} CSS property. diff --git a/files/en-us/web/css/transform-function/rotatey/index.md b/files/en-us/web/css/transform-function/rotatey/index.md index 9d0485bcc34a9b6..ef2824556eb5797 100644 --- a/files/en-us/web/css/transform-function/rotatey/index.md +++ b/files/en-us/web/css/transform-function/rotatey/index.md @@ -10,7 +10,33 @@ browser-compat: css.types.transform-function.rotateY The **`rotateY()`** [CSS](/en-US/docs/Web/CSS) [function](/en-US/docs/Web/CSS/CSS_Values_and_Units/CSS_Value_Functions) defines a transformation that rotates an element around the y-axis (vertical) without deforming it. Its result is a {{cssxref("&lt;transform-function&gt;")}} data type. -{{EmbedInteractiveExample("pages/css/function-rotateY.html")}} +{{InteractiveExample("CSS Demo: rotateY()")}} + +```css interactive-example-choice +transform: rotateY(0); +``` + +```css interactive-example-choice +transform: rotateY(45deg); +``` + +```css interactive-example-choice +transform: rotateY(-0.2turn); +``` + +```css interactive-example-choice +transform: rotateY(3.142rad); +``` + +```html interactive-example +<section id="default-example"> + <img + class="transition-all" + id="example-element" + src="/shared-assets/images/examples/firefox-logo.svg" + width="200" /> +</section> +``` The axis of rotation passes through an origin, defined by the {{ cssxref("transform-origin") }} CSS property. diff --git a/files/en-us/web/css/transform-function/rotatez/index.md b/files/en-us/web/css/transform-function/rotatez/index.md index f7dd671286cb94f..a66fa47bdfb9be6 100644 --- a/files/en-us/web/css/transform-function/rotatez/index.md +++ b/files/en-us/web/css/transform-function/rotatez/index.md @@ -10,7 +10,33 @@ browser-compat: css.types.transform-function.rotateZ The **`rotateZ()`** [CSS](/en-US/docs/Web/CSS) [function](/en-US/docs/Web/CSS/CSS_Values_and_Units/CSS_Value_Functions) defines a transformation that rotates an element around the z-axis without deforming it. Its result is a {{cssxref("&lt;transform-function&gt;")}} data type. -{{EmbedInteractiveExample("pages/css/function-rotateZ.html")}} +{{InteractiveExample("CSS Demo: rotateZ()")}} + +```css interactive-example-choice +transform: rotateZ(0); +``` + +```css interactive-example-choice +transform: rotateZ(90deg); +``` + +```css interactive-example-choice +transform: rotateZ(-0.25turn); +``` + +```css interactive-example-choice +transform: rotateZ(3.142rad); +``` + +```html interactive-example +<section id="default-example"> + <img + class="transition-all" + id="example-element" + src="/shared-assets/images/examples/firefox-logo.svg" + width="200" /> +</section> +``` The axis of rotation passes through an origin, defined by the {{ cssxref("transform-origin") }} CSS property. diff --git a/files/en-us/web/css/transform-function/scale/index.md b/files/en-us/web/css/transform-function/scale/index.md index f6b3550008bff0f..9ad52e43d76d9df 100644 --- a/files/en-us/web/css/transform-function/scale/index.md +++ b/files/en-us/web/css/transform-function/scale/index.md @@ -11,7 +11,33 @@ The **`scale()`** [CSS](/en-US/docs/Web/CSS) [function](/en-US/docs/Web/CSS/CSS_ plane. Because the amount of scaling is defined by a vector [sx, sy], it can resize the horizontal and vertical dimensions at different scales. Its result is a {{cssxref("&lt;transform-function&gt;")}} data type. -{{EmbedInteractiveExample("pages/css/function-scale.html")}} +{{InteractiveExample("CSS Demo: scale()")}} + +```css interactive-example-choice +transform: scale(1); +``` + +```css interactive-example-choice +transform: scale(0.7); +``` + +```css interactive-example-choice +transform: scale(1.3, 0.4); +``` + +```css interactive-example-choice +transform: scale(-0.5, 1); +``` + +```html interactive-example +<section id="default-example"> + <img + class="transition-all" + id="example-element" + src="/shared-assets/images/examples/firefox-logo.svg" + width="200" /> +</section> +``` This scaling transformation is characterized by a two-dimensional vector. Its coordinates define how much scaling is done in each direction. If both coordinates are equal, the scaling is uniform (_isotropic_) and the aspect @@ -98,7 +124,7 @@ user has reduced animation specified in their system preferences. Find out more: -- [MDN Understanding WCAG, Guideline 2.3 explanations](/en-US/docs/Web/Accessibility/Understanding_WCAG/Operable#guideline_2.3_%e2%80%94_seizures_and_physical_reactions_do_not_design_content_in_a_way_that_is_known_to_cause_seizures_or_physical_reactions) +- [MDN Understanding WCAG, Guideline 2.3 explanations](/en-US/docs/Web/Accessibility/Guides/Understanding_WCAG/Operable#guideline_2.3_%e2%80%94_seizures_and_physical_reactions_do_not_design_content_in_a_way_that_is_known_to_cause_seizures_or_physical_reactions) - [Understanding Success Criterion 2.3.3 | W3C Understanding WCAG 2.1](https://www.w3.org/WAI/WCAG21/Understanding/animation-from-interactions) ## Examples diff --git a/files/en-us/web/css/transform-function/scale3d/index.md b/files/en-us/web/css/transform-function/scale3d/index.md index 951973c4ab9c371..e9fb4afe736a927 100644 --- a/files/en-us/web/css/transform-function/scale3d/index.md +++ b/files/en-us/web/css/transform-function/scale3d/index.md @@ -11,7 +11,93 @@ The **`scale3d()`** [CSS](/en-US/docs/Web/CSS) [function](/en-US/docs/Web/CSS/CS Because the amount of scaling is defined by a vector [sx, sy, sz], it can resize different dimensions at different scales. Its result is a {{cssxref("&lt;transform-function&gt;")}} data type. -{{EmbedInteractiveExample("pages/css/function-scale3d.html")}} +{{InteractiveExample("CSS Demo: scale3d()")}} + +```css interactive-example-choice +transform: scale3d(1, 1, 1); +``` + +```css interactive-example-choice +transform: scale3d(1.3, 1.3, 1.3); +``` + +```css interactive-example-choice +transform: scale3d(0.5, 1, 1.7); +``` + +```css interactive-example-choice +transform: scale3d(-1.4, 0.4, 0.7); +``` + +```html interactive-example +<section class="default-example" id="default-example"> + <div class="transition-all" id="example-element"> + <div class="face front">1</div> + <div class="face back">2</div> + <div class="face right">3</div> + <div class="face left">4</div> + <div class="face top">5</div> + <div class="face bottom">6</div> + </div> +</section> +``` + +```css interactive-example +#default-example { + background: linear-gradient(skyblue, khaki); + perspective: 800px; + perspective-origin: 150% 150%; +} + +#example-element { + width: 100px; + height: 100px; + perspective: 550px; + transform-style: preserve-3d; +} + +.face { + display: flex; + align-items: center; + justify-content: center; + width: 100%; + height: 100%; + position: absolute; + backface-visibility: inherit; + font-size: 60px; + color: white; +} + +.front { + background: rgba(90, 90, 90, 0.7); + transform: translateZ(50px); +} + +.back { + background: rgba(0, 210, 0, 0.7); + transform: rotateY(180deg) translateZ(50px); +} + +.right { + background: rgba(210, 0, 0, 0.7); + transform: rotateY(90deg) translateZ(50px); +} + +.left { + background: rgba(0, 0, 210, 0.7); + transform: rotateY(-90deg) translateZ(50px); +} + +.top { + background: rgba(210, 210, 0, 0.7); + transform: rotateX(90deg) translateZ(50px); +} + +.bottom { + background: rgba(210, 0, 210, 0.7); + transform: rotateX(-90deg) translateZ(50px); +} +``` This scaling transformation is characterized by a three-dimensional vector. Its coordinates define how much scaling is done in each direction. If all three coordinates are equal, the scaling is uniform (_isotropic_) and the diff --git a/files/en-us/web/css/transform-function/scalex/index.md b/files/en-us/web/css/transform-function/scalex/index.md index 9108181b26e05a0..c45bbaafae26b3e 100644 --- a/files/en-us/web/css/transform-function/scalex/index.md +++ b/files/en-us/web/css/transform-function/scalex/index.md @@ -10,7 +10,33 @@ browser-compat: css.types.transform-function.scaleX The **`scaleX()`** [CSS](/en-US/docs/Web/CSS) [function](/en-US/docs/Web/CSS/CSS_Values_and_Units/CSS_Value_Functions) defines a transformation that resizes an element along the x-axis (horizontally). Its result is a {{cssxref("&lt;transform-function&gt;")}} data type. -{{EmbedInteractiveExample("pages/css/function-scaleX.html")}} +{{InteractiveExample("CSS Demo: scaleX()")}} + +```css interactive-example-choice +transform: scaleX(1); +``` + +```css interactive-example-choice +transform: scaleX(0.7); +``` + +```css interactive-example-choice +transform: scaleX(1.3); +``` + +```css interactive-example-choice +transform: scaleX(-0.5); +``` + +```html interactive-example +<section id="default-example"> + <img + class="transition-all" + id="example-element" + src="/shared-assets/images/examples/firefox-logo.svg" + width="200" /> +</section> +``` It modifies the abscissa (horizontal, x-coordinate) of each element point by a constant factor, except when the scale factor is 1, in which case the function is the identity transform. The scaling is not isotropic, and the angles of the element are generally not conserved, except for multiples of 90 degrees. diff --git a/files/en-us/web/css/transform-function/scaley/index.md b/files/en-us/web/css/transform-function/scaley/index.md index e4c57cae9e9e564..b7a19ff1bd89d13 100644 --- a/files/en-us/web/css/transform-function/scaley/index.md +++ b/files/en-us/web/css/transform-function/scaley/index.md @@ -10,7 +10,33 @@ browser-compat: css.types.transform-function.scaleY The **`scaleY()`** [CSS](/en-US/docs/Web/CSS) [function](/en-US/docs/Web/CSS/CSS_Values_and_Units/CSS_Value_Functions) defines a transformation that resizes an element along the y-axis (vertically). Its result is a {{cssxref("&lt;transform-function&gt;")}} data type. -{{EmbedInteractiveExample("pages/css/function-scaleY.html")}} +{{InteractiveExample("CSS Demo: scaleY()")}} + +```css interactive-example-choice +transform: scaleY(1); +``` + +```css interactive-example-choice +transform: scaleY(0.7); +``` + +```css interactive-example-choice +transform: scaleY(1.3); +``` + +```css interactive-example-choice +transform: scaleY(-0.5); +``` + +```html interactive-example +<section id="default-example"> + <img + class="transition-all" + id="example-element" + src="/shared-assets/images/examples/firefox-logo.svg" + width="200" /> +</section> +``` It modifies the ordinate (vertical, y-coordinate) of each element point by a constant factor, except when the scale factor is 1, in which case the function is the identity transform. The scaling is not isotropic, and the angles of the element are not conserved. diff --git a/files/en-us/web/css/transform-function/scalez/index.md b/files/en-us/web/css/transform-function/scalez/index.md index 6d59a09c4b73d25..3d24c454f1ce6de 100644 --- a/files/en-us/web/css/transform-function/scalez/index.md +++ b/files/en-us/web/css/transform-function/scalez/index.md @@ -10,7 +10,93 @@ browser-compat: css.types.transform-function.scaleZ The **`scaleZ()`** [CSS](/en-US/docs/Web/CSS) [function](/en-US/docs/Web/CSS/CSS_Values_and_Units/CSS_Value_Functions) defines a transformation that resizes an element along the z-axis. Its result is a {{cssxref("&lt;transform-function&gt;")}} data type. -{{EmbedInteractiveExample("pages/css/function-scaleZ.html")}} +{{InteractiveExample("CSS Demo: scaleZ()")}} + +```css interactive-example-choice +transform: scaleZ(1); +``` + +```css interactive-example-choice +transform: scaleZ(1.4); +``` + +```css interactive-example-choice +transform: scaleZ(0.5); +``` + +```css interactive-example-choice +transform: scaleZ(-1.4); +``` + +```html interactive-example +<section class="default-example" id="default-example"> + <div class="transition-all" id="example-element"> + <div class="face front">1</div> + <div class="face back">2</div> + <div class="face right">3</div> + <div class="face left">4</div> + <div class="face top">5</div> + <div class="face bottom">6</div> + </div> +</section> +``` + +```css interactive-example +#default-example { + background: linear-gradient(skyblue, khaki); + perspective: 800px; + perspective-origin: 150% 150%; +} + +#example-element { + width: 100px; + height: 100px; + perspective: 550px; + transform-style: preserve-3d; +} + +.face { + display: flex; + align-items: center; + justify-content: center; + width: 100%; + height: 100%; + position: absolute; + backface-visibility: inherit; + font-size: 60px; + color: white; +} + +.front { + background: rgba(90, 90, 90, 0.7); + transform: translateZ(50px); +} + +.back { + background: rgba(0, 210, 0, 0.7); + transform: rotateY(180deg) translateZ(50px); +} + +.right { + background: rgba(210, 0, 0, 0.7); + transform: rotateY(90deg) translateZ(50px); +} + +.left { + background: rgba(0, 0, 210, 0.7); + transform: rotateY(-90deg) translateZ(50px); +} + +.top { + background: rgba(210, 210, 0, 0.7); + transform: rotateX(90deg) translateZ(50px); +} + +.bottom { + background: rgba(210, 0, 210, 0.7); + transform: rotateX(-90deg) translateZ(50px); +} +``` This scaling transformation modifies the z-coordinate of each element point by a constant factor, except when the scale factor is 1, in which case the function is the identity transform. The scaling is not isotropic, and the angles diff --git a/files/en-us/web/css/transform-function/skew/index.md b/files/en-us/web/css/transform-function/skew/index.md index 743ee9ba9554b85..81ea768f496b003 100644 --- a/files/en-us/web/css/transform-function/skew/index.md +++ b/files/en-us/web/css/transform-function/skew/index.md @@ -10,7 +10,33 @@ browser-compat: css.types.transform-function.skew The **`skew()`** [CSS](/en-US/docs/Web/CSS) [function](/en-US/docs/Web/CSS/CSS_Values_and_Units/CSS_Value_Functions) defines a transformation that skews an element on the 2D plane. Its result is a {{cssxref("&lt;transform-function&gt;")}} data type. -{{EmbedInteractiveExample("pages/css/function-skew.html")}} +{{InteractiveExample("CSS Demo: skew()")}} + +```css interactive-example-choice +transform: skew(0); +``` + +```css interactive-example-choice +transform: skew(15deg, 15deg); +``` + +```css interactive-example-choice +transform: skew(-0.06turn, 18deg); +``` + +```css interactive-example-choice +transform: skew(0.312rad); +``` + +```html interactive-example +<section id="default-example"> + <img + class="transition-all" + id="example-element" + src="/shared-assets/images/examples/firefox-logo.svg" + width="200" /> +</section> +``` This transformation is a shear mapping ([transvection](https://en.wikipedia.org/wiki/Shear_mapping)) that distorts each point within an element by a certain angle in the horizontal and vertical directions. The effect is as if you diff --git a/files/en-us/web/css/transform-function/skewx/index.md b/files/en-us/web/css/transform-function/skewx/index.md index 9e49fde2c4cbc24..c7d9b851c2699bb 100644 --- a/files/en-us/web/css/transform-function/skewx/index.md +++ b/files/en-us/web/css/transform-function/skewx/index.md @@ -10,7 +10,33 @@ browser-compat: css.types.transform-function.skewX The **`skewX()`** [CSS](/en-US/docs/Web/CSS) [function](/en-US/docs/Web/CSS/CSS_Values_and_Units/CSS_Value_Functions) defines a transformation that skews an element in the horizontal direction on the 2D plane. Its result is a {{cssxref("&lt;transform-function&gt;")}} data type. -{{EmbedInteractiveExample("pages/css/function-skewX.html")}} +{{InteractiveExample("CSS Demo: skewX()")}} + +```css interactive-example-choice +transform: skewX(0); +``` + +```css interactive-example-choice +transform: skewX(35deg); +``` + +```css interactive-example-choice +transform: skewX(-0.06turn); +``` + +```css interactive-example-choice +transform: skewX(0.352rad); +``` + +```html interactive-example +<section id="default-example"> + <img + class="transition-all" + id="example-element" + src="/shared-assets/images/examples/firefox-logo.svg" + width="200" /> +</section> +``` This transformation is a shear mapping ([transvection](https://en.wikipedia.org/wiki/Shear_mapping)) that distorts each point within an element by a certain angle in the horizontal direction. The abscissa (horizontal, x-coordinate) of each point is diff --git a/files/en-us/web/css/transform-function/skewy/index.md b/files/en-us/web/css/transform-function/skewy/index.md index 942897f0e238978..72aacc8f5b7dac4 100644 --- a/files/en-us/web/css/transform-function/skewy/index.md +++ b/files/en-us/web/css/transform-function/skewy/index.md @@ -10,7 +10,33 @@ browser-compat: css.types.transform-function.skewY The **`skewY()`** [CSS](/en-US/docs/Web/CSS) [function](/en-US/docs/Web/CSS/CSS_Values_and_Units/CSS_Value_Functions) defines a transformation that skews an element in the vertical direction on the 2D plane. Its result is a {{cssxref("&lt;transform-function&gt;")}} data type. -{{EmbedInteractiveExample("pages/css/function-skewY.html")}} +{{InteractiveExample("CSS Demo: skewY()")}} + +```css interactive-example-choice +transform: skewY(0); +``` + +```css interactive-example-choice +transform: skewY(35deg); +``` + +```css interactive-example-choice +transform: skewY(-0.06turn); +``` + +```css interactive-example-choice +transform: skewY(0.352rad); +``` + +```html interactive-example +<section id="default-example"> + <img + class="transition-all" + id="example-element" + src="/shared-assets/images/examples/firefox-logo.svg" + width="200" /> +</section> +``` This transformation is a shear mapping ([transvection](https://en.wikipedia.org/wiki/Shear_mapping)) that distorts each point within an element by a certain angle in the vertical direction. The ordinate (vertical, y-coordinate) of each point is diff --git a/files/en-us/web/css/transform-function/translate/index.md b/files/en-us/web/css/transform-function/translate/index.md index be0edfa2b5ba1d0..348b7fb8de8b0f3 100644 --- a/files/en-us/web/css/transform-function/translate/index.md +++ b/files/en-us/web/css/transform-function/translate/index.md @@ -10,7 +10,49 @@ browser-compat: css.types.transform-function.translate The **`translate()`** [CSS](/en-US/docs/Web/CSS) [function](/en-US/docs/Web/CSS/CSS_Values_and_Units/CSS_Value_Functions) repositions an element in the horizontal and/or vertical directions. Its result is a {{cssxref("&lt;transform-function&gt;")}} data type. -{{EmbedInteractiveExample("pages/css/function-translate.html")}} +{{InteractiveExample("CSS Demo: translate()")}} + +```css interactive-example-choice +transform: translate(0); +``` + +```css interactive-example-choice +transform: translate(42px, 18px); +``` + +```css interactive-example-choice +transform: translate(-2.1rem, -2ex); +``` + +```css interactive-example-choice +transform: translate(3ch, 3mm); +``` + +```html interactive-example +<section id="default-example"> + <img + class="transition-all" + id="static-element" + src="/shared-assets/images/examples/firefox-logo.svg" + width="200" /> + <img + class="transition-all" + id="example-element" + src="/shared-assets/images/examples/firefox-logo.svg" + width="200" /> +</section> +``` + +```css interactive-example +#static-element { + opacity: 0.4; + position: absolute; +} + +#example-element { + position: absolute; +} +``` This transformation is characterized by a two-dimensional vector [tx, ty]. Its coordinates define how much the element moves in each direction. diff --git a/files/en-us/web/css/transform-function/translate3d/index.md b/files/en-us/web/css/transform-function/translate3d/index.md index dbcdc1f9ef9f74f..6e8931b85fe8ae7 100644 --- a/files/en-us/web/css/transform-function/translate3d/index.md +++ b/files/en-us/web/css/transform-function/translate3d/index.md @@ -10,7 +10,93 @@ browser-compat: css.types.transform-function.translate3d The **`translate3d()`** [CSS](/en-US/docs/Web/CSS) [function](/en-US/docs/Web/CSS/CSS_Values_and_Units/CSS_Value_Functions) repositions an element in 3D space. Its result is a {{cssxref("&lt;transform-function&gt;")}} data type. -{{EmbedInteractiveExample("pages/css/function-translate3d.html")}} +{{InteractiveExample("CSS Demo: translate3d()")}} + +```css interactive-example-choice +transform: translate3d(0, 0, 0); +``` + +```css interactive-example-choice +transform: translate3d(42px, -62px, -135px); +``` + +```css interactive-example-choice +transform: translate3d(-2.7rem, 0, 1rem); +``` + +```css interactive-example-choice +transform: translate3d(5ch, 0.4in, 5em); +``` + +```html interactive-example +<section class="default-example" id="default-example"> + <div class="transition-all" id="example-element"> + <div class="face front">1</div> + <div class="face back">2</div> + <div class="face right">3</div> + <div class="face left">4</div> + <div class="face top">5</div> + <div class="face bottom">6</div> + </div> +</section> +``` + +```css interactive-example +#default-example { + background: linear-gradient(skyblue, khaki); + perspective: 800px; + perspective-origin: 150% 150%; +} + +#example-element { + width: 100px; + height: 100px; + perspective: 550px; + transform-style: preserve-3d; +} + +.face { + display: flex; + align-items: center; + justify-content: center; + width: 100%; + height: 100%; + position: absolute; + backface-visibility: inherit; + font-size: 60px; + color: white; +} + +.front { + background: rgba(90, 90, 90, 0.7); + transform: translateZ(50px); +} + +.back { + background: rgba(0, 210, 0, 0.7); + transform: rotateY(180deg) translateZ(50px); +} + +.right { + background: rgba(210, 0, 0, 0.7); + transform: rotateY(90deg) translateZ(50px); +} + +.left { + background: rgba(0, 0, 210, 0.7); + transform: rotateY(-90deg) translateZ(50px); +} + +.top { + background: rgba(210, 210, 0, 0.7); + transform: rotateX(90deg) translateZ(50px); +} + +.bottom { + background: rgba(210, 0, 210, 0.7); + transform: rotateX(-90deg) translateZ(50px); +} +``` This transformation is characterized by a three-dimensional vector [tx, ty, tz]. Its coordinates define how much the element moves in each direction. diff --git a/files/en-us/web/css/transform-function/translatex/index.md b/files/en-us/web/css/transform-function/translatex/index.md index 3c1139519be8193..4da6847ddcb4ef9 100644 --- a/files/en-us/web/css/transform-function/translatex/index.md +++ b/files/en-us/web/css/transform-function/translatex/index.md @@ -10,7 +10,49 @@ browser-compat: css.types.transform-function.translateX The **`translateX()`** [CSS](/en-US/docs/Web/CSS) [function](/en-US/docs/Web/CSS/CSS_Values_and_Units/CSS_Value_Functions) repositions an element horizontally on the 2D plane. Its result is a {{cssxref("&lt;transform-function&gt;")}} data type. -{{EmbedInteractiveExample("pages/css/function-translateX.html")}} +{{InteractiveExample("CSS Demo: translateX()")}} + +```css interactive-example-choice +transform: translateX(0); +``` + +```css interactive-example-choice +transform: translateX(42px); +``` + +```css interactive-example-choice +transform: translateX(-2.1rem); +``` + +```css interactive-example-choice +transform: translateX(3ch); +``` + +```html interactive-example +<section id="default-example"> + <img + class="transition-all" + id="static-element" + src="/shared-assets/images/examples/firefox-logo.svg" + width="200" /> + <img + class="transition-all" + id="example-element" + src="/shared-assets/images/examples/firefox-logo.svg" + width="200" /> +</section> +``` + +```css interactive-example +#static-element { + opacity: 0.4; + position: absolute; +} + +#example-element { + position: absolute; +} +``` > **Note:** `translateX(tx)` is equivalent to > `translate(tx, 0)` or diff --git a/files/en-us/web/css/transform-function/translatey/index.md b/files/en-us/web/css/transform-function/translatey/index.md index 5f24d86d97f0a25..06c0b6307c5646f 100644 --- a/files/en-us/web/css/transform-function/translatey/index.md +++ b/files/en-us/web/css/transform-function/translatey/index.md @@ -10,7 +10,49 @@ browser-compat: css.types.transform-function.translateY The **`translateY()`** [CSS](/en-US/docs/Web/CSS) [function](/en-US/docs/Web/CSS/CSS_Values_and_Units/CSS_Value_Functions) repositions an element vertically on the 2D plane. Its result is a {{cssxref("&lt;transform-function&gt;")}} data type. -{{EmbedInteractiveExample("pages/css/function-translateY.html")}} +{{InteractiveExample("CSS Demo: translateY()")}} + +```css interactive-example-choice +transform: translateY(0); +``` + +```css interactive-example-choice +transform: translateY(42px); +``` + +```css interactive-example-choice +transform: translateY(-2.1rem); +``` + +```css interactive-example-choice +transform: translateY(3ch); +``` + +```html interactive-example +<section id="default-example"> + <img + class="transition-all" + id="static-element" + src="/shared-assets/images/examples/firefox-logo.svg" + width="200" /> + <img + class="transition-all" + id="example-element" + src="/shared-assets/images/examples/firefox-logo.svg" + width="200" /> +</section> +``` + +```css interactive-example +#static-element { + opacity: 0.4; + position: absolute; +} + +#example-element { + position: absolute; +} +``` > **Note:** `translateY(ty)` is equivalent to > `translate(0, ty)` or diff --git a/files/en-us/web/css/transform-function/translatez/index.md b/files/en-us/web/css/transform-function/translatez/index.md index 52207b6ed99bce9..a68b0e535da25e9 100644 --- a/files/en-us/web/css/transform-function/translatez/index.md +++ b/files/en-us/web/css/transform-function/translatez/index.md @@ -10,7 +10,93 @@ browser-compat: css.types.transform-function.translateZ The **`translateZ()`** [CSS](/en-US/docs/Web/CSS) [function](/en-US/docs/Web/CSS/CSS_Values_and_Units/CSS_Value_Functions) repositions an element along the z-axis in 3D space, i.e., closer to or farther away from the viewer. Its result is a {{cssxref("&lt;transform-function&gt;")}} data type. -{{EmbedInteractiveExample("pages/css/function-translateZ.html")}} +{{InteractiveExample("CSS Demo: translateZ()")}} + +```css interactive-example-choice +transform: translateZ(0); +``` + +```css interactive-example-choice +transform: translateZ(42px); +``` + +```css interactive-example-choice +transform: translateZ(-9.7rem); +``` + +```css interactive-example-choice +transform: translateZ(-3ch); +``` + +```html interactive-example +<section class="default-example" id="default-example"> + <div class="transition-all" id="example-element"> + <div class="face front">1</div> + <div class="face back">2</div> + <div class="face right">3</div> + <div class="face left">4</div> + <div class="face top">5</div> + <div class="face bottom">6</div> + </div> +</section> +``` + +```css interactive-example +#default-example { + background: linear-gradient(skyblue, khaki); + perspective: 800px; + perspective-origin: 150% 150%; +} + +#example-element { + width: 100px; + height: 100px; + perspective: 550px; + transform-style: preserve-3d; +} + +.face { + display: flex; + align-items: center; + justify-content: center; + width: 100%; + height: 100%; + position: absolute; + backface-visibility: inherit; + font-size: 60px; + color: white; +} + +.front { + background: rgba(90, 90, 90, 0.7); + transform: translateZ(50px); +} + +.back { + background: rgba(0, 210, 0, 0.7); + transform: rotateY(180deg) translateZ(50px); +} + +.right { + background: rgba(210, 0, 0, 0.7); + transform: rotateY(90deg) translateZ(50px); +} + +.left { + background: rgba(0, 0, 210, 0.7); + transform: rotateY(-90deg) translateZ(50px); +} + +.top { + background: rgba(210, 210, 0, 0.7); + transform: rotateX(90deg) translateZ(50px); +} + +.bottom { + background: rgba(210, 0, 210, 0.7); + transform: rotateX(-90deg) translateZ(50px); +} +``` This transformation is defined by a {{cssxref("&lt;length&gt;")}} which specifies how far inward or outward the element or elements move. diff --git a/files/en-us/web/css/transform-origin/index.md b/files/en-us/web/css/transform-origin/index.md index 18a903776739973..e6e6b00c46e9e2f 100644 --- a/files/en-us/web/css/transform-origin/index.md +++ b/files/en-us/web/css/transform-origin/index.md @@ -9,7 +9,143 @@ browser-compat: css.properties.transform-origin The **`transform-origin`** [CSS](/en-US/docs/Web/CSS) property sets the origin for an element's transformations. -{{EmbedInteractiveExample("pages/css/transform-origin.html")}} +{{InteractiveExample("CSS Demo: transform-origin")}} + +```css interactive-example-choice +transform-origin: center; +``` + +```css interactive-example-choice +transform-origin: top left; +``` + +```css interactive-example-choice +transform-origin: 50px 50px; +``` + +```css interactive-example-choice +/* 3D rotation with z-axis origin */ +transform-origin: bottom right 60px; +``` + +```html interactive-example +<section id="default-example"> + <div id="example-container"> + <div id="example-element">Rotate me!</div> + <img + alt="" + id="crosshair" + src="/shared-assets/images/examples/crosshair.svg" + width="24px" /> + <div id="static-element"></div> + </div> +</section> +``` + +```css interactive-example +@keyframes rotate { + from { + transform: rotate(0); + } + + to { + transform: rotate(30deg); + } +} + +@keyframes rotate3d { + from { + transform: rotate3d(0, 0, 0, 0); + } + + to { + transform: rotate3d(1, 2, 0, 60deg); + } +} + +#example-container { + width: 160px; + height: 160px; + position: relative; +} + +#example-element { + width: 100%; + height: 100%; + display: flex; + position: absolute; + align-items: center; + justify-content: center; + background: #f7ebee; + color: #000000; + font-size: 1.2rem; + text-transform: uppercase; +} + +#example-element.rotate { + animation: rotate 1s forwards; +} + +#example-element.rotate3d { + animation: rotate3d 1s forwards; +} + +#crosshair { + width: 24px; + height: 24px; + opacity: 0; + position: absolute; +} + +#static-element { + width: 100%; + height: 100%; + position: absolute; + border: dotted 3px #ff1100; +} +``` + +```js interactive-example +"use strict"; + +window.addEventListener("load", () => { + function update() { + const selected = document.querySelector(".selected"); + + /* Restart the animation + https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_Animations/Tips */ + el.className = ""; + window.requestAnimationFrame(() => { + window.requestAnimationFrame(() => { + el.className = + el.style.transformOrigin.split(" ")[2] === "60px" + ? "rotate3d" + : "rotate"; + }); + }); + + const transformOrigin = getComputedStyle(el).transformOrigin; + const pos = transformOrigin.split(/\s+/); + crosshair.style.left = `calc(${pos[0]} - 12px)`; + crosshair.style.top = `calc(${pos[1]} - 12px)`; + } + + const crosshair = document.getElementById("crosshair"); + const el = document.getElementById("example-element"); + + const observer = new MutationObserver(() => { + update(); + }); + + observer.observe(el, { + attributes: true, + attributeFilter: ["style"], + }); + + update(); + crosshair.style.opacity = "1"; +}); +``` The transform origin is the point around which a transformation is applied. For example, the transform origin of the [`rotate()`](/en-US/docs/Web/CSS/transform-function/rotate) function is the center of rotation. @@ -70,7 +206,7 @@ transform-origin: revert-layer; transform-origin: unset; ``` -The `transform-origin` property may be specified using one, two, or three values, where each value represents an offset. Offsets that are not explicitly defined are reset to their corresponding [initial values](/en-US/docs/Web/CSS/CSS_cascade/initial_value). +The `transform-origin` property may be specified using one, two, or three values, where each value represents an offset. Offsets that are not explicitly defined are reset to their corresponding [initial values](/en-US/docs/Web/CSS/CSS_cascade/Value_processing#initial_value). If a single {{cssxref("&lt;length&gt;")}} or {{cssxref("&lt;percentage&gt;")}} value is defined, it represents the horizontal offset. @@ -120,7 +256,7 @@ The keywords are convenience shorthands and match the following {{cssxref("&lt;p {{CSSInfo}} > [!NOTE] -> The initial value of `transform-origin` is `0 0` for all SVG elements except for root `<svg>` elements and `<svg>` elements that are a direct child of a [foreignObject](/en-US/docs/Web/SVG/Element/foreignObject), and whose `transform-origin` is `50% 50%`, like other CSS elements. See the [SVG transform-origin](/en-US/docs/Web/SVG/Attribute/transform-origin) attribute for more information. +> The initial value of `transform-origin` is `0 0` for all SVG elements except for root `<svg>` elements and `<svg>` elements that are a direct child of a [foreignObject](/en-US/docs/Web/SVG/Reference/Element/foreignObject), and whose `transform-origin` is `50% 50%`, like other CSS elements. See the [SVG transform-origin](/en-US/docs/Web/SVG/Reference/Attribute/transform-origin) attribute for more information. ## Formal syntax diff --git a/files/en-us/web/css/transform-style/index.md b/files/en-us/web/css/transform-style/index.md index 323c532e130122a..86914a760c4eb8a 100644 --- a/files/en-us/web/css/transform-style/index.md +++ b/files/en-us/web/css/transform-style/index.md @@ -9,7 +9,42 @@ browser-compat: css.properties.transform-style The **`transform-style`** [CSS](/en-US/docs/Web/CSS) property sets whether children of an element are positioned in the 3D space or are flattened in the plane of the element. -{{EmbedInteractiveExample("pages/css/transform-style.html")}} +{{InteractiveExample("CSS Demo: transform-style")}} + +```css interactive-example-choice +transform-style: flat; +``` + +```css interactive-example-choice +transform-style: preserve-3d; +``` + +```html interactive-example +<section class="default-example" id="default-example"> + <div class="transition-all layer" id="example-element"> + <p>Parent</p> + <div class="numeral"><code>rotate3d(1, 1, 1, 45deg)</code></div> + </div> +</section> +``` + +```css interactive-example +.layer { + background: #623e3f; + border-radius: 0.75rem; + color: white; + transform: perspective(200px) rotateY(30deg); +} + +.numeral { + background-color: #ffba08; + border-radius: 0.2rem; + color: #000; + margin: 1rem; + padding: 0.2rem; + transform: rotate3d(1, 1, 1, 45deg); +} +``` If flattened, the element's children will not exist on their own in the 3D-space. @@ -40,7 +75,7 @@ transform-style: unset; ## Description The spec lists some [grouping property values](https://drafts.csswg.org/css-transforms-2/#grouping-property-values), which -require the user agent to create a flattened representation of the descendant elements before they can be applied, and therefore force the element to have a [used value](/en-US/docs/Web/CSS/CSS_cascade/used_value) of `transform-style: flat`, even when `preserve-3d` is specified. These property values include: +require the user agent to create a flattened representation of the descendant elements before they can be applied, and therefore force the element to have a [used value](/en-US/docs/Web/CSS/CSS_cascade/Value_processing#used_value) of `transform-style: flat`, even when `preserve-3d` is specified. These property values include: - {{cssxref("overflow")}}: any value other than `visible` or `clip`. - {{cssxref("opacity")}}: any value less than `1`. diff --git a/files/en-us/web/css/transform/index.md b/files/en-us/web/css/transform/index.md index 842a3764cca14ac..6e6a369aa375249 100644 --- a/files/en-us/web/css/transform/index.md +++ b/files/en-us/web/css/transform/index.md @@ -8,16 +8,50 @@ browser-compat: css.properties.transform {{CSSRef}} The **`transform`** [CSS](/en-US/docs/Web/CSS) property lets you rotate, scale, skew, or translate an element. -It modifies the coordinate space of the CSS [visual formatting model](/en-US/docs/Web/CSS/Visual_formatting_model). +It modifies the coordinate space of the CSS [visual formatting model](/en-US/docs/Web/CSS/CSS_display/Visual_formatting_model). -{{EmbedInteractiveExample("pages/css/transform.html")}} +{{InteractiveExample("CSS Demo: transform")}} -If the property has a value different from `none`, a [stacking context](/en-US/docs/Web/CSS/CSS_positioned_layout/Understanding_z-index/Stacking_context) will be created. +```css interactive-example-choice +transform: matrix(1, 2, 3, 4, 5, 6); +``` + +```css interactive-example-choice +transform: translate(120px, 50%); +``` + +```css interactive-example-choice +transform: scale(2, 0.5); +``` + +```css interactive-example-choice +transform: rotate(0.5turn); +``` + +```css interactive-example-choice +transform: skew(30deg, 20deg); +``` + +```css interactive-example-choice +transform: scale(0.5) translate(-100%, -100%); +``` + +```html interactive-example +<section id="default-example"> + <img + class="transition-all" + id="example-element" + src="/shared-assets/images/examples/firefox-logo.svg" + width="200" /> +</section> +``` + +If the property has a value different from `none`, a [stacking context](/en-US/docs/Web/CSS/CSS_positioned_layout/Stacking_context) will be created. In that case, the element will act as a [containing block](/en-US/docs/Web/CSS/CSS_display/Containing_block) for any `position: fixed;` or `position: absolute;` elements that it contains. > [!WARNING] > Only transformable elements can be `transform`ed. -> That is, all elements whose layout is governed by the CSS box model except for: [non-replaced inline boxes](/en-US/docs/Glossary/Inline-level_content), [table-column boxes](/en-US/docs/Web/HTML/Element/col), and [table-column-group boxes](/en-US/docs/Web/HTML/Element/colgroup). +> That is, all elements whose layout is governed by the CSS box model except for: [non-replaced inline boxes](/en-US/docs/Glossary/Inline-level_content), [table-column boxes](/en-US/docs/Web/HTML/Reference/Elements/col), and [table-column-group boxes](/en-US/docs/Web/HTML/Reference/Elements/colgroup). ## Syntax @@ -79,7 +113,7 @@ Also, consider making use of the {{cssxref("@media/prefers-reduced-motion", "pre Find out more: -- [MDN Understanding WCAG, Guideline 2.3 explanations](/en-US/docs/Web/Accessibility/Understanding_WCAG/Operable#guideline_2.3_—_seizures_and_physical_reactions_do_not_design_content_in_a_way_that_is_known_to_cause_seizures_or_physical_reactions) +- [MDN Understanding WCAG, Guideline 2.3 explanations](/en-US/docs/Web/Accessibility/Guides/Understanding_WCAG/Operable#guideline_2.3_—_seizures_and_physical_reactions_do_not_design_content_in_a_way_that_is_known_to_cause_seizures_or_physical_reactions) - [Understanding Success Criterion 2.3.3 | W3C Understanding WCAG 2.1](https://www.w3.org/WAI/WCAG21/Understanding/animation-from-interactions) ## Formal definition diff --git a/files/en-us/web/css/transition-behavior/index.md b/files/en-us/web/css/transition-behavior/index.md index 8cbc33f41c11c70..cc7235d14222443 100644 --- a/files/en-us/web/css/transition-behavior/index.md +++ b/files/en-us/web/css/transition-behavior/index.md @@ -62,7 +62,7 @@ The `transition-behavior` value can be included as part of a shorthand {{cssxref } ``` -In the above snippet we include the `transition` property twice. The first instance does not include the `allow-discrete` value — this provides cross-browser support, ensuring the card's other properties still transition in browsers that don't support `transition-behavior.` +In the above snippet we include the `transition` property twice. The first instance does not include the `allow-discrete` value — this provides cross-browser support, ensuring the card's other properties still transition in browsers that don't support `transition-behavior`. ### Discrete animation behavior @@ -91,7 +91,7 @@ In this example, a [popover](/en-US/docs/Web/API/Popover_API) is animated as it #### HTML -The HTML contains a {{htmlelement("div")}} element declared as a popover using the [popover](/en-US/docs/Web/HTML/Global_attributes/popover) attribute, and a {{htmlelement("button")}} element designated as the popover's display control using its [popovertarget](/en-US/docs/Web/HTML/Element/button#popovertarget) attribute. +The HTML contains a {{htmlelement("div")}} element declared as a popover using the [popover](/en-US/docs/Web/HTML/Reference/Global_attributes/popover) attribute, and a {{htmlelement("button")}} element designated as the popover's display control using its [popovertarget](/en-US/docs/Web/HTML/Reference/Elements/button#popovertarget) attribute. ```html <button popovertarget="mypopover">Show the popover</button> diff --git a/files/en-us/web/css/transition-delay/index.md b/files/en-us/web/css/transition-delay/index.md index 16536f00a4d6f82..cfd6409ed742e9b 100644 --- a/files/en-us/web/css/transition-delay/index.md +++ b/files/en-us/web/css/transition-delay/index.md @@ -9,7 +9,51 @@ browser-compat: css.properties.transition-delay The **`transition-delay`** [CSS](/en-US/docs/Web/CSS) property specifies the duration to wait before starting a property's [transition effect](/en-US/docs/Web/CSS/CSS_transitions/Using_CSS_transitions) when its value changes. -{{EmbedInteractiveExample("pages/css/transition-delay.html")}} +{{InteractiveExample("CSS Demo: transition-delay")}} + +```css interactive-example-choice +transition-delay: 250ms; +transition-property: margin-right; +``` + +```css interactive-example-choice +transition-delay: 1s; +transition-property: background-color; +``` + +```css interactive-example-choice +transition-delay: 1s; +transition-property: margin-right, color; +``` + +```css interactive-example-choice +transition-delay: 1s, 250ms; +transition-property: margin-right, color; +``` + +```html interactive-example +<section id="default-example"> + <div id="example-element">Hover to see<br />the transition.</div> +</section> +``` + +```css interactive-example +#example-element { + background-color: #e4f0f5; + color: #000; + padding: 1rem; + border-radius: 0.5rem; + font: 1em monospace; + width: 100%; + transition: margin-right 2s; +} + +#default-example:hover > #example-element { + background-color: #909; + color: #fff; + margin-right: 40%; +} +``` The delay may be zero, positive, or negative: diff --git a/files/en-us/web/css/transition-duration/index.md b/files/en-us/web/css/transition-duration/index.md index de4f8fbcd55016e..f75072a928bd515 100644 --- a/files/en-us/web/css/transition-duration/index.md +++ b/files/en-us/web/css/transition-duration/index.md @@ -9,7 +9,51 @@ browser-compat: css.properties.transition-duration The **`transition-duration`** [CSS](/en-US/docs/Web/CSS) property sets the length of time a transition animation should take to complete. By default, the value is `0s`, meaning that no animation will occur. -{{EmbedInteractiveExample("pages/css/transition-duration.html")}} +{{InteractiveExample("CSS Demo: transition-duration")}} + +```css interactive-example-choice +transition-duration: 500ms; +transition-property: margin-right; +``` + +```css interactive-example-choice +transition-duration: 2s; +transition-property: background-color; +``` + +```css interactive-example-choice +transition-duration: 2s; +transition-property: margin-right, color; +``` + +```css interactive-example-choice +transition-duration: 3s, 1s; +transition-property: margin-right, color; +``` + +```html interactive-example +<section id="default-example"> + <div id="example-element">Hover to see<br />the transition.</div> +</section> +``` + +```css interactive-example +#example-element { + background-color: #e4f0f5; + color: #000; + padding: 1rem; + border-radius: 0.5rem; + font: 1em monospace; + width: 100%; + transition: margin-right 2s; +} + +#default-example:hover > #example-element { + background-color: #909; + color: #fff; + margin-right: 40%; +} +``` You may specify multiple durations; each duration will be applied to the corresponding property as specified by the {{ cssxref("transition-property") }} property, which acts as a master list. If the number of specified durations is less than in the master list, the user agent repeats the list of durations. If the number of specified durations is more than in the master list, the list is truncated to the right size. In both the cases, the CSS declaration stays valid. diff --git a/files/en-us/web/css/transition-property/index.md b/files/en-us/web/css/transition-property/index.md index 2299ed32eccc47c..9ec61a7f6ff15ee 100644 --- a/files/en-us/web/css/transition-property/index.md +++ b/files/en-us/web/css/transition-property/index.md @@ -9,7 +9,47 @@ browser-compat: css.properties.transition-property The **`transition-property`** [CSS](/en-US/docs/Web/CSS) property sets the CSS properties to which a [transition effect](/en-US/docs/Web/CSS/CSS_transitions/Using_CSS_transitions) should be applied. -{{EmbedInteractiveExample("pages/css/transition-property.html")}} +{{InteractiveExample("CSS Demo: transition-property")}} + +```css interactive-example-choice +transition-property: margin-right; +``` + +```css interactive-example-choice +transition-property: margin-right, color; +``` + +```css interactive-example-choice +transition-property: all; +``` + +```css interactive-example-choice +transition-property: none; +``` + +```html interactive-example +<section id="default-example"> + <div id="example-element">Hover to see<br />the transition.</div> +</section> +``` + +```css interactive-example +#example-element { + background-color: #e4f0f5; + color: #000; + padding: 1rem; + border-radius: 0.5rem; + font: 1em monospace; + width: 100%; + transition: margin-right 2s; +} + +#default-example:hover > #example-element { + background-color: #909; + color: #fff; + margin-right: 40%; +} +``` If you specify a shorthand property (e.g., {{cssxref("background")}}), all of its longhand sub-properties that can be animated will be. diff --git a/files/en-us/web/css/transition-timing-function/index.md b/files/en-us/web/css/transition-timing-function/index.md index ddd762bd9bcf794..5b96cdffc60cfbf 100644 --- a/files/en-us/web/css/transition-timing-function/index.md +++ b/files/en-us/web/css/transition-timing-function/index.md @@ -9,7 +9,47 @@ browser-compat: css.properties.transition-timing-function The **`transition-timing-function`** [CSS](/en-US/docs/Web/CSS) property sets how intermediate values are calculated for CSS properties being affected by a [transition effect](/en-US/docs/Web/CSS/CSS_transitions/Using_CSS_transitions). -{{EmbedInteractiveExample("pages/css/transition-timing-function.html")}} +{{InteractiveExample("CSS Demo: transition-timing-function")}} + +```css interactive-example-choice +transition-timing-function: linear; +``` + +```css interactive-example-choice +transition-timing-function: ease-in; +``` + +```css interactive-example-choice +transition-timing-function: steps(6, end); +``` + +```css interactive-example-choice +transition-timing-function: cubic-bezier(0.29, 1.01, 1, -0.68); +``` + +```html interactive-example +<section id="default-example"> + <div id="example-element">Hover to see<br />the transition.</div> +</section> +``` + +```css interactive-example +#example-element { + background-color: #e4f0f5; + color: #000; + padding: 1rem; + border-radius: 0.5rem; + font: 1em monospace; + width: 100%; + transition: margin-right 2s; +} + +#default-example:hover > #example-element { + background-color: #909; + color: #fff; + margin-right: 40%; +} +``` This, in essence, lets you establish an acceleration curve so that the speed of the transition can vary over its duration. @@ -98,7 +138,7 @@ transition-timing-function: unset; Some animations can be helpful such as to guide users to understand what actions are expected, to show relationships within the user interface, and to inform users as to what actions have occurred. Animations can help reduce cognitive load, prevent change blindness, and establish better recall in spatial relationships. However, some animations can be problematic for people with cognitive concerns such as Attention Deficit Hyperactivity Disorder (ADHD) and certain kinds of motion can be a trigger for Vestibular disorders, epilepsy, and migraine and Scotopic sensitivity. -Consider providing a mechanism for pausing or disabling animation, as well as using the [Reduced Motion Media Query](/en-US/docs/Web/CSS/@media/prefers-reduced-motion) (or equivalent [User Agent client hint](/en-US/docs/Web/HTTP/Client_hints#user-agent_client_hints) {{HTTPHeader("Sec-CH-Prefers-Reduced-Motion")}}) to create a complimentary experience for users who have expressed a preference for less animation. +Consider providing a mechanism for pausing or disabling animation, as well as using the [Reduced Motion Media Query](/en-US/docs/Web/CSS/@media/prefers-reduced-motion) (or equivalent [User Agent client hint](/en-US/docs/Web/HTTP/Guides/Client_hints#user_agent_client_hints) {{HTTPHeader("Sec-CH-Prefers-Reduced-Motion")}}) to create a complimentary experience for users who have expressed a preference for less animation. ## Formal definition @@ -150,8 +190,8 @@ Consider providing a mechanism for pausing or disabling animation, as well as us ```js hidden function updateTransition() { const els = document.querySelectorAll(".parent > div[class]"); - for (let i = 0; i < els.length; i++) { - els[i].classList.toggle("box1"); + for (const el of els) { + el.classList.toggle("box1"); } } @@ -221,8 +261,8 @@ const intervalID = setInterval(updateTransition, 10000); ```js hidden function updateTransition() { const els = document.querySelectorAll(".parent > div[class]"); - for (let i = 0; i < els.length; i++) { - els[i].classList.toggle("box1"); + for (const el of els) { + el.classList.toggle("box1"); } } diff --git a/files/en-us/web/css/transition/index.md b/files/en-us/web/css/transition/index.md index 0b0d78814697c89..66ee44505f23f3c 100644 --- a/files/en-us/web/css/transition/index.md +++ b/files/en-us/web/css/transition/index.md @@ -9,7 +9,57 @@ browser-compat: css.properties.transition The **`transition`** [CSS](/en-US/docs/Web/CSS) property is a [shorthand property](/en-US/docs/Web/CSS/CSS_cascade/Shorthand_properties) for {{ cssxref("transition-property") }}, {{ cssxref("transition-duration") }}, {{ cssxref("transition-timing-function") }}, {{ cssxref("transition-delay") }}, and {{ cssxref("transition-behavior") }}. -{{EmbedInteractiveExample("pages/css/transition.html")}} +{{InteractiveExample("CSS Demo: transition")}} + +```css interactive-example-choice +transition: margin-right 2s; +``` + +```css interactive-example-choice +transition: margin-right 2s 0.5s; +``` + +```css interactive-example-choice +transition: margin-right 2s ease-in-out; +``` + +```css interactive-example-choice +transition: margin-right 2s ease-in-out 0.5s; +``` + +```css interactive-example-choice +transition: + margin-right 2s, + color 1s; +``` + +```css interactive-example-choice +transition: all 1s ease-out; +``` + +```html interactive-example +<section id="default-example"> + <div id="example-element">Hover to see<br />the transition.</div> +</section> +``` + +```css interactive-example +#example-element { + background-color: #e4f0f5; + color: #000; + padding: 1rem; + border-radius: 0.5rem; + font: 1em monospace; + width: 100%; + transition: margin-right 2s; +} + +#default-example:hover > #example-element { + background-color: #909; + color: #fff; + margin-right: 40%; +} +``` Transitions enable you to define the transition between two states of an element. Different states may be defined using [pseudo-classes](/en-US/docs/Web/CSS/Pseudo-classes) like {{cssxref(":hover")}} or {{cssxref(":active")}} or dynamically set using JavaScript. diff --git a/files/en-us/web/css/translate/index.md b/files/en-us/web/css/translate/index.md index 0eb6fc84eb4c246..63cfec9dd52d1cc 100644 --- a/files/en-us/web/css/translate/index.md +++ b/files/en-us/web/css/translate/index.md @@ -9,7 +9,97 @@ browser-compat: css.properties.translate The **`translate`** [CSS](/en-US/docs/Web/CSS) property allows you to specify translation transforms individually and independently of the {{CSSxRef("transform")}} property. This maps better to typical user interface usage, and saves having to remember the exact order of transform functions to specify in the `transform` value. -{{EmbedInteractiveExample("pages/css/translate.html")}} +{{InteractiveExample("CSS Demo: translate")}} + +```css interactive-example-choice +translate: none; +``` + +```css interactive-example-choice +translate: 40px; +``` + +```css interactive-example-choice +translate: 50% -40%; +``` + +```css interactive-example-choice +translate: 20px 4rem; +``` + +```css interactive-example-choice +translate: 20px 4rem 150px; +``` + +```html interactive-example +<section class="default-example" id="default-example"> + <div class="transition-all" id="example-element"> + <div class="face front">1</div> + <div class="face back">2</div> + <div class="face right">3</div> + <div class="face left">4</div> + <div class="face top">5</div> + <div class="face bottom">6</div> + </div> +</section> +``` + +```css interactive-example +#default-example { + background: linear-gradient(skyblue, khaki); + perspective: 800px; + perspective-origin: 150% 150%; +} + +#example-element { + width: 100px; + height: 100px; + perspective: 550px; + transform-style: preserve-3d; +} + +.face { + display: flex; + align-items: center; + justify-content: center; + width: 100%; + height: 100%; + position: absolute; + backface-visibility: inherit; + font-size: 60px; + color: white; +} + +.front { + background: rgba(90, 90, 90, 0.7); + transform: translateZ(50px); +} + +.back { + background: rgba(0, 210, 0, 0.7); + transform: rotateY(180deg) translateZ(50px); +} + +.right { + background: rgba(210, 0, 0, 0.7); + transform: rotateY(90deg) translateZ(50px); +} + +.left { + background: rgba(0, 0, 210, 0.7); + transform: rotateY(-90deg) translateZ(50px); +} + +.top { + background: rgba(210, 210, 0, 0.7); + transform: rotateX(90deg) translateZ(50px); +} + +.bottom { + background: rgba(210, 0, 210, 0.7); + transform: rotateX(-90deg) translateZ(50px); +} +``` ## Syntax diff --git a/files/en-us/web/css/unicode-bidi/index.md b/files/en-us/web/css/unicode-bidi/index.md index d10e0e99e48c883..ff89d0e0e660ab6 100644 --- a/files/en-us/web/css/unicode-bidi/index.md +++ b/files/en-us/web/css/unicode-bidi/index.md @@ -9,7 +9,31 @@ browser-compat: css.properties.unicode-bidi The **`unicode-bidi`** [CSS](/en-US/docs/Web/CSS) property, together with the {{cssxref("direction")}} property, determines how bidirectional text in a document is handled. For example, if a block of content contains both left-to-right and right-to-left text, the user-agent uses a complex Unicode algorithm to decide how to display the text. The `unicode-bidi` property overrides this algorithm and allows the developer to control the text embedding. -{{EmbedInteractiveExample("pages/css/unicode-bidi.html")}} +{{InteractiveExample("CSS Demo: unicode-bidi")}} + +```css interactive-example-choice +unicode-bidi: normal; +``` + +```css interactive-example-choice +unicode-bidi: bidi-override; +``` + +```css interactive-example-choice +unicode-bidi: plaintext; +``` + +```css interactive-example-choice +unicode-bidi: isolate-override; +``` + +```html interactive-example +<section class="default-example" id="default-example"> + <p class="transition-all" id="example-element"> + בְּרֵאשִׁ֖ית בָּרָ֣א אֱלֹהִ֑ים אֵ֥ת הַשָּׁמַ֖יִם וְאֵ֥ת הָאָֽרֶץ. + </p> +</section> +``` The `unicode-bidi` and {{cssxref("direction")}} properties are the only properties that are not affected by the {{cssxref("all")}} shorthand. @@ -44,7 +68,7 @@ unicode-bidi: unset; - `bidi-override` - : For inline elements this creates an override. For block container elements this creates an override for inline-level descendants not within another block container element. This means that inside the element, reordering is strictly in sequence according to the {{Cssxref("direction")}} property; the implicit part of the bidirectional algorithm is ignored. - `isolate` - - : This keyword indicates that the element's container directionality should be calculated without considering the content of this element. The element is therefore _isolated_ from its siblings. When applying its bidirectional-resolution algorithm, its container element treats it as one or several `U+FFFC Object Replacement Character`, i.e. like an image. + - : This keyword indicates that the element's container directionality should be calculated without considering the content of this element. The element is therefore _isolated_ from its siblings. When applying its bidirectional-resolution algorithm, its container element treats it as one or several `U+FFFC Object Replacement Character`, i.e., like an image. - `isolate-override` - : This keyword applies the isolation behavior of the `isolate` keyword to the surrounding content and the override behavior of the `bidi-override` keyword to the inner content. - `plaintext` @@ -93,3 +117,4 @@ unicode-bidi: unset; - {{Cssxref("direction")}} - SVG {{SVGAttr("unicode-bidi")}} attribute +- [Handling different text directions](/en-US/docs/Learn_web_development/Core/Styling_basics/Handling_different_text_directions) diff --git a/files/en-us/web/css/unset/index.md b/files/en-us/web/css/unset/index.md index 21ddb65b3afcd1d..99a43ff525d1263 100644 --- a/files/en-us/web/css/unset/index.md +++ b/files/en-us/web/css/unset/index.md @@ -7,7 +7,7 @@ browser-compat: css.types.global_keywords.unset {{CSSRef}} -The **`unset`** CSS keyword resets a property to its inherited value if the property naturally inherits from its parent, and to its [initial value](/en-US/docs/Web/CSS/CSS_cascade/initial_value) if not. In other words, it behaves like the {{cssxref("inherit")}} keyword in the first case, when the property is an [inherited property](/en-US/docs/Web/CSS/CSS_cascade/Inheritance#inherited_properties), and like the {{cssxref("initial")}} keyword in the second case, when the property is a [non-inherited property](/en-US/docs/Web/CSS/CSS_cascade/Inheritance#non-inherited_properties). +The **`unset`** CSS keyword resets a property to its inherited value if the property naturally inherits from its parent, and to its [initial value](/en-US/docs/Web/CSS/CSS_cascade/Value_processing#initial_value) if not. In other words, it behaves like the {{cssxref("inherit")}} keyword in the first case, when the property is an [inherited property](/en-US/docs/Web/CSS/CSS_cascade/Inheritance#inherited_properties), and like the {{cssxref("initial")}} keyword in the second case, when the property is a [non-inherited property](/en-US/docs/Web/CSS/CSS_cascade/Inheritance#non-inherited_properties). **`unset`** can be applied to any CSS property, including the CSS shorthand property {{cssxref("all")}}. diff --git a/files/en-us/web/css/url_function/index.md b/files/en-us/web/css/url_function/index.md index 96b22587c8ad677..652c79152d838ad 100644 --- a/files/en-us/web/css/url_function/index.md +++ b/files/en-us/web/css/url_function/index.md @@ -72,15 +72,15 @@ The **`url()`** function can be included as a value for - : A URL, which is a relative or absolute address, or pointer, to the web resource to be included, or a data URL, optionally in single or double quotes. Quotes are required if the URL includes parentheses, whitespace, or quotes, unless these characters are escaped, or if the address includes control characters above 0x7e. Double quotes cannot occur inside double quotes and single quotes cannot occur inside single quotes unless escaped. The following are all valid and equivalent: ```css - <css_property>: url("https://example.com/image.png") - <css_property>: url('https://example.com/image.png') - <css_property>: url(https://example.com/image.png) + url("https://example.com/image.png") + url('https://example.com/image.png') + url(https://example.com/image.png) ``` If you choose to write the URL without quotes, use a backslash (`\`) before any parentheses, whitespace characters, single quotes (`'`) and double quotes (`"`) that are part of the URL. - path - - : References the ID of an [SVG shape](/en-US/docs/Web/SVG/Tutorial/Basic_Shapes) or an [SVG filter](/en-US/docs/Web/SVG/Element/filter). + - : References the ID of an [SVG shape](/en-US/docs/Web/SVG/Tutorials/SVG_from_scratch/Basic_shapes) or an [SVG filter](/en-US/docs/Web/SVG/Reference/Element/filter). - `<url-modifier>` - : In the future, the `url()` function may support specifying a modifier, an identifier or a functional notation, which alters the meaning of the URL string. This is not supported and not fully defined in the specification. diff --git a/files/en-us/web/css/user-modify/index.md b/files/en-us/web/css/user-modify/index.md index c4ee19e8f3144b0..b8c95d5e0fb9e68 100644 --- a/files/en-us/web/css/user-modify/index.md +++ b/files/en-us/web/css/user-modify/index.md @@ -13,7 +13,7 @@ browser-compat: css.properties.user-modify The **`user-modify`** property has no effect in Firefox. It was originally planned to determine whether or not the content of an element can be edited by a user. > [!WARNING] -> This property has been replaced by the [`contenteditable`](/en-US/docs/Web/HTML/Global_attributes/contenteditable) attribute. +> This property has been replaced by the [`contenteditable`](/en-US/docs/Web/HTML/Reference/Global_attributes/contenteditable) attribute. ## Syntax @@ -45,10 +45,7 @@ The `-moz-user-modify` property is specified as one of the keyword values from t ## Formal syntax -```plain -user-modify = - read-only | read-write | read-write-plaintext-only | write-only -``` +{{CSSSyntaxRaw(`user-modify = read-only | read-write | read-write-plaintext-only | write-only`)}} ## Examples diff --git a/files/en-us/web/css/user-select/index.md b/files/en-us/web/css/user-select/index.md index f05605a0186da6d..70747fbaf0bd79e 100644 --- a/files/en-us/web/css/user-select/index.md +++ b/files/en-us/web/css/user-select/index.md @@ -9,7 +9,31 @@ browser-compat: css.properties.user-select The **`user-select`** [CSS](/en-US/docs/Web/CSS) property controls whether the user can select text. This doesn't have any effect on content loaded as part of a browser's user interface (its {{Glossary("Chrome", "chrome")}}), except in textboxes. -{{EmbedInteractiveExample("pages/css/user-select.html")}} +{{InteractiveExample("CSS Demo: user-select")}} + +```css interactive-example-choice +user-select: none; +``` + +```css interactive-example-choice +user-select: text; +``` + +```css interactive-example-choice +user-select: all; +``` + +```html interactive-example +<section id="default-example"> + <p id="example-element">Try to select this text</p> +</section> +``` + +```css interactive-example +#example-element { + font-size: 1.5rem; +} +``` ## Syntax diff --git a/files/en-us/web/css/var/index.md b/files/en-us/web/css/var/index.md index 85e4740f7ed85a8..9d765abf2e5fa82 100644 --- a/files/en-us/web/css/var/index.md +++ b/files/en-us/web/css/var/index.md @@ -2,14 +2,48 @@ title: var() slug: Web/CSS/var page-type: css-function -browser-compat: css.properties.custom-property.var +browser-compat: css.types.var --- {{CSSRef}} The **`var()`** [CSS](/en-US/docs/Web/CSS) [function](/en-US/docs/Web/CSS/CSS_Values_and_Units/CSS_Value_Functions) can be used to insert the value of a [custom property](/en-US/docs/Web/CSS/--*) (sometimes called a "CSS variable") instead of any part of a value of another property. -{{EmbedInteractiveExample("pages/css/var.html")}} +{{InteractiveExample("CSS Demo: var()")}} + +```css interactive-example-choice +border-color: var(--color-a); +``` + +```css interactive-example-choice +border-color: var(--color-b); +``` + +```css interactive-example-choice +border-color: var(--color-c); +``` + +```html interactive-example +<section class="default-example" id="default-example"> + <div id="example-element"> + Three color options have been set on the :root use these to change the + border color. + </div> +</section> +``` + +```css interactive-example +:root { + --color-a: pink; + --color-b: green; + --color-c: rebeccapurple; +} + +#example-element { + border: 10px solid #000; + padding: 10px; +} +``` The `var()` function cannot be used in property names, selectors or anything else besides property values. (Doing so usually produces invalid syntax, or else a value whose meaning has no connection to the variable.) @@ -27,7 +61,7 @@ var(--custom-prop, var(--default-value)); var(--custom-prop, var(--default-value, red)); ``` -The first argument to the function is the name of the custom property to be substituted. An optional second argument to the function serves as a fallback value. If the custom property referenced by the first argument is not defined or equals a [CSS-wide keyword](/en-US/docs/Web/CSS/CSS_Values_and_Units/CSS_data_types#css-wide_values), the function uses the second value. +The first argument to the function is the name of the custom property to be substituted. An optional second argument to the function serves as a fallback value. If the custom property referenced by the first argument is not defined or equals a [CSS-wide keyword](/en-US/docs/Web/CSS/CSS_Values_and_Units/CSS_data_types#css-wide_keywords), the function uses the second value. The syntax of the fallback, like that of custom properties, allows commas. For example, `var(--foo, red, blue)` defines a fallback of `red, blue`; that is, anything between the first comma and the end of the function is considered a fallback value. @@ -39,9 +73,9 @@ The syntax of the fallback, like that of custom properties, allows commas. For e - `<declaration-value>` - - : The custom property's fallback value, which is used in case the custom property is not defined or equals a [CSS-wide keyword](/en-US/docs/Web/CSS/CSS_Values_and_Units/CSS_data_types#css-wide_values). This value may contain any character except some characters with special meaning like newlines, unmatched closing brackets, i.e. `)`, `]`, or `}`, top-level semicolons, or exclamation marks. The fallback value can itself be a custom property using the `var()` syntax. If the fallback value is omitted, and the custom property is not defined, the `var()` function resolves to an [invalid value](#invalid_values). + - : The custom property's fallback value, which is used in case the custom property is not defined or equals a [CSS-wide keyword](/en-US/docs/Web/CSS/CSS_Values_and_Units/CSS_data_types#css-wide_keywords). This value may contain any character except some characters with special meaning like newlines, unmatched closing brackets, i.e., `)`, `]`, or `}`, top-level semicolons, or exclamation marks. The fallback value can itself be a custom property using the `var()` syntax. If the fallback value is omitted, and the custom property is not defined, the `var()` function resolves to an [invalid value](#invalid_values). - > **Note:** `var(--a,)` is valid, specifying that if the `--a` custom property is not defined or equals a [CSS-wide keyword](/en-US/docs/Web/CSS/CSS_Values_and_Units/CSS_data_types#css-wide_values), the `var()` should be replaced with nothing. + > **Note:** `var(--a,)` is valid, specifying that if the `--a` custom property is not defined or equals a [CSS-wide keyword](/en-US/docs/Web/CSS/CSS_Values_and_Units/CSS_data_types#css-wide_keywords), the `var()` should be replaced with nothing. ## Formal syntax diff --git a/files/en-us/web/css/vector-effect/index.md b/files/en-us/web/css/vector-effect/index.md index a24d3d5fa07a633..34d8dc9295c92d1 100644 --- a/files/en-us/web/css/vector-effect/index.md +++ b/files/en-us/web/css/vector-effect/index.md @@ -7,7 +7,7 @@ browser-compat: css.properties.vector-effect {{CSSRef}} -The **`vector-effect`** [CSS](/en-US/docs/Web/CSS) property suppresses specific [transformation effects](/en-US/docs/Web/SVG/Attribute/transform) in SVG, thus permitting effects like a road on a map staying the same width no matter how the map is zoomed, or allowing a diagram key to retain its position and size regardless of other transforms. It can only be used with SVG elements that accept the {{SVGAttr("vector-effect")}} attribute. When used, the CSS value overrides any values of the element's `vector-effect` attribute. +The **`vector-effect`** [CSS](/en-US/docs/Web/CSS) property suppresses specific [transformation effects](/en-US/docs/Web/SVG/Reference/Attribute/transform) in SVG, thus permitting effects like a road on a map staying the same width no matter how the map is zoomed, or allowing a diagram key to retain its position and size regardless of other transforms. It can only be used with SVG elements that accept the {{SVGAttr("vector-effect")}} attribute. When used, the CSS value overrides any values of the element's `vector-effect` attribute. ## Syntax @@ -15,9 +15,6 @@ The **`vector-effect`** [CSS](/en-US/docs/Web/CSS) property suppresses specific /* Keywords */ vector-effect: none; vector-effect: non-scaling-stroke; -vector-effect: non-scaling-size; -vector-effect: non-rotation; -vector-effect: fixed-position; /* Global values */ vector-effect: inherit; @@ -30,24 +27,12 @@ vector-effect: unset; ### Values - `none` - - : No vector effects are applied to the element, meaning it will be fully affected by transforms as normal. - - `non-scaling-stroke` - - : The element's drawn stroke width will be physically equal in size to its defined stroke width, even if the element has been scaled up or down in size due to transforms of either itself or its coordinate system. This is the case whether the element is scaled with transforms or by physical resizing of the entire image. -- `non-scaling-size` {{Experimental_Inline}} - - - : The element will ignore the effects of any scaling transformations. - -- `non-rotation` {{Experimental_Inline}} - - - : The element will ignore the effects of any rotation transformations. - -- `fixed-position` {{Experimental_Inline}} - - - : The element will ignore the effects of any translation transformations. +> [!NOTE] +> The spec defines three other values, `non-scaling-size`, `non-rotation`, and `fixed-position`, but these have no implementations and are considered at-risk. ## Formal syntax diff --git a/files/en-us/web/css/vertical-align/index.md b/files/en-us/web/css/vertical-align/index.md index ad5d3ac6773885f..b3f58c4c1db8a53 100644 --- a/files/en-us/web/css/vertical-align/index.md +++ b/files/en-us/web/css/vertical-align/index.md @@ -9,7 +9,49 @@ browser-compat: css.properties.vertical-align The **`vertical-align`** [CSS](/en-US/docs/Web/CSS) property sets vertical alignment of an inline, inline-block or table-cell box. -{{EmbedInteractiveExample("pages/css/vertical-align.html")}} +{{InteractiveExample("CSS Demo: vertical-align")}} + +```css interactive-example-choice +vertical-align: baseline; +``` + +```css interactive-example-choice +vertical-align: top; +``` + +```css interactive-example-choice +vertical-align: middle; +``` + +```css interactive-example-choice +vertical-align: bottom; +``` + +```css interactive-example-choice +vertical-align: sub; +``` + +```css interactive-example-choice +vertical-align: text-top; +``` + +```html interactive-example +<section class="default-example" id="default-example"> + <p> + Align the star: + <img id="example-element" src="/shared-assets/images/examples/star2.png" /> + </p> +</section> +``` + +```css interactive-example +#default-example > p { + line-height: 3em; + font-family: monospace; + font-size: 1.2em; + text-decoration: underline overline; +} +``` The `vertical-align` property can be used in two contexts: @@ -55,7 +97,7 @@ The `vertical-align` property is specified as one of the values listed below. These values vertically align the element relative to its parent element: - `baseline` - - : Aligns the baseline of the element with the baseline of its parent. The baseline of some [replaced elements](/en-US/docs/Web/CSS/Replaced_element), like {{HTMLElement("textarea")}}, is not specified by the HTML specification, meaning that their behavior with this keyword may vary between browsers. + - : Aligns the baseline of the element with the baseline of its parent. The baseline of some {{ glossary("replaced elements")}}, like {{HTMLElement("textarea")}}, is not specified by the HTML specification, meaning that their behavior with this keyword may vary between browsers. - `sub` - : Aligns the baseline of the element with the subscript-baseline of its parent. - `super` diff --git a/files/en-us/web/css/view-timeline-axis/index.md b/files/en-us/web/css/view-timeline-axis/index.md index d7e002c490a5d42..77ab6d3dd787030 100644 --- a/files/en-us/web/css/view-timeline-axis/index.md +++ b/files/en-us/web/css/view-timeline-axis/index.md @@ -14,7 +14,7 @@ The **`view-timeline-axis`** [CSS](/en-US/docs/Web/CSS) property is used to spec > [!NOTE] > If the scroller element does not overflow its container in the axis dimension or if the overflow is hidden or clipped, no scroll progress timeline will be created. -The `view-timeline-axis` and {{cssxref("view-timeline-name")}} properties can also be set using the [`view-timeline`](/en-US/docs/Web/CSS/view-timeline) shorthand property. +The `view-timeline-axis`, {{cssxref("view-timeline-inset")}} and {{cssxref("view-timeline-name")}} properties can also be set using the {{cssxref("view-timeline")}} shorthand property. ## Syntax @@ -154,7 +154,7 @@ p { } to { - opacity: 1, + opacity: 1; transform: scaleX(1); } } @@ -176,7 +176,7 @@ Scroll the horizontal bar at the bottom to see the subject element animate as yo ## See also -- [`animation-timeline`](/en-US/docs/Web/CSS/animation-timeline) +- {{cssxref("animation-timeline")}} - {{cssxref("timeline-scope")}} -- [`view-timeline`](/en-US/docs/Web/CSS/view-timeline), [`view-timeline-name`](/en-US/docs/Web/CSS/view-timeline-name) +- {{cssxref("view-timeline")}}, {{cssxref("view-timeline-inset")}}, {{cssxref("view-timeline-name")}} - [CSS scroll-driven animations](/en-US/docs/Web/CSS/CSS_scroll-driven_animations) diff --git a/files/en-us/web/css/view-timeline-inset/index.md b/files/en-us/web/css/view-timeline-inset/index.md index 3044dd49196bddd..ee42801b148e07d 100644 --- a/files/en-us/web/css/view-timeline-inset/index.md +++ b/files/en-us/web/css/view-timeline-inset/index.md @@ -14,6 +14,11 @@ The **`view-timeline-inset`** [CSS](/en-US/docs/Web/CSS) property is used to spe This can be combined with or used instead of {{cssxref("animation-range")}} and its longhand properties, which can be used to set the attachment range of an animation along its timeline. See [CSS scroll-driven animations](/en-US/docs/Web/CSS/CSS_scroll-driven_animations) for more details. +> [!NOTE] +> If the scroller element does not overflow its container in the axis dimension or if the overflow is hidden or clipped, no scroll progress timeline will be created. + +The `view-timeline-inset`, {{cssxref("view-timeline-axis")}}, and {{cssxref("view-timeline-name")}} properties can also be set using the {{cssxref("view-timeline")}} shorthand property. + ## Syntax ```css @@ -37,7 +42,7 @@ Allowed values for `view-timeline-inset` are: - {{cssxref("length-percentage")}} - : Any valid `<length-percentage>` value is accepted as an inset/outset value. - If the value is positive, the position of the animation's start/end will be moved inside the scrollport by the specified length or percentage. - - If the value is negative, the position of the animation's start/end will be moved outside the scrollport by the specified length or percentage, i.e. it will start animating before it appears in the scrollport, or finish animating after it leaves the scrollport. + - If the value is negative, the position of the animation's start/end will be moved outside the scrollport by the specified length or percentage, i.e., it will start animating before it appears in the scrollport, or finish animating after it leaves the scrollport. If two values are provided, the first value represents the start inset/outset in the relevant axis (where the animation begins) and the second value represents the end inset/outset (where the animation ends). If only one value is provided, the start and end inset/outset are both set to the same value. @@ -152,7 +157,7 @@ Last, an animation is specified on the element that animates its opacity and sca } to { - opacity: 1, + opacity: 1; transform: scaleX(1); } } @@ -174,7 +179,7 @@ Scroll to see the subject element being animated. ## See also -- [`animation-timeline`](/en-US/docs/Web/CSS/animation-timeline) +- {{cssxref("animation-timeline")}} - {{cssxref("timeline-scope")}} -- [`view-timeline`](/en-US/docs/Web/CSS/view-timeline), [`view-timeline-axis`](/en-US/docs/Web/CSS/view-timeline-axis), [`view-timeline-name`](/en-US/docs/Web/CSS/view-timeline-name) +- {{cssxref("view-timeline")}}, {{cssxref("view-timeline-axis")}}, {{cssxref("view-timeline-name")}} - [CSS scroll-driven animations](/en-US/docs/Web/CSS/CSS_scroll-driven_animations) diff --git a/files/en-us/web/css/view-timeline-name/index.md b/files/en-us/web/css/view-timeline-name/index.md index f255d05a7def4a6..b69d24f113df58a 100644 --- a/files/en-us/web/css/view-timeline-name/index.md +++ b/files/en-us/web/css/view-timeline-name/index.md @@ -15,9 +15,9 @@ The visibility of the subject inside the scroller is tracked — by default, the The name is then referenced in an [`animation-timeline`](/en-US/docs/Web/CSS/animation-timeline) declaration to indicate the element that will be animated as the timeline progresses. This can be the subject element, but it doesn't have to be — you can animate a different element as the subject moves through the scrolling area. > [!NOTE] -> If the element does not overflow its container in the axis dimension or if the overflow is hidden or clipped, no timeline will be created. +> If the scroller element does not overflow its container in the axis dimension or if the overflow is hidden or clipped, no scroll progress timeline will be created. -The {{cssxref("view-timeline-axis")}} and `view-timeline-name` properties can also be set using the [`view-timeline`](/en-US/docs/Web/CSS/scroll-timeline) shorthand property. +The `view-timeline-name`, {{cssxref("view-timeline-axis")}} and {{cssxref("view-timeline-inset")}} properties can also be set using the {{cssxref("view-timeline")}} shorthand property. ## Syntax @@ -168,7 +168,7 @@ Scroll to see the subject element being animated. ## See also -- [`animation-timeline`](/en-US/docs/Web/CSS/animation-timeline) +- {{cssxref("animation-timeline")}} - {{cssxref("timeline-scope")}} -- [`view-timeline`](/en-US/docs/Web/CSS/view-timeline), [`view-timeline-axis`](/en-US/docs/Web/CSS/view-timeline-axis) +- {{cssxref("view-timeline")}}, {{cssxref("view-timeline-axis")}}, {{cssxref("view-timeline-inset")}} - [CSS scroll-driven animations](/en-US/docs/Web/CSS/CSS_scroll-driven_animations) diff --git a/files/en-us/web/css/view-timeline/index.md b/files/en-us/web/css/view-timeline/index.md index bdd22747d54bb22..40b94073f8dd47b 100644 --- a/files/en-us/web/css/view-timeline/index.md +++ b/files/en-us/web/css/view-timeline/index.md @@ -17,18 +17,23 @@ The visibility of the subject inside the scroller is tracked — by default, the The name is then referenced in an [`animation-timeline`](/en-US/docs/Web/CSS/animation-timeline) declaration to indicate the element that will be animated as the timeline progresses. This can be the subject element, but it doesn't have to be — you can animate a different element as the subject moves through the scrolling area. > [!NOTE] -> If the scroller does not overflow its container in the axis dimension or if the overflow is hidden or clipped, no timeline will be created. +> If the scroller element does not overflow its container in the axis dimension or if the overflow is hidden or clipped, no scroll progress timeline will be created. ## Constituent properties This property is a shorthand for the following CSS properties: -- [`view-timeline-name`](/en-US/docs/Web/CSS/view-timeline-name) -- [`view-timeline-axis`](/en-US/docs/Web/CSS/view-timeline-axis) +- {{cssxref("view-timeline-axis")}} +- {{cssxref("view-timeline-inset")}} +- {{cssxref("view-timeline-name")}} ## Syntax ```css +/* three values: one each for view-timeline-name, view-timeline-inset and view-timeline-axis */ +view-timeline: --custom_name_for_timeline block auto; +view-timeline: --custom_name_for_timeline block 20% 200px; + /* two values: one each for view-timeline-name and view-timeline-axis */ view-timeline: --custom_name_for_timeline block; view-timeline: --custom_name_for_timeline inline; @@ -44,18 +49,18 @@ view-timeline: none; view-timeline: --custom_name_for_timeline; ``` -The `view-timeline` shorthand property can be applied to a container element as a combination of the `<view-timeline-name>` and `<view-timeline-axis>` values. At least one of the values must be specified. If both the values are specified, the order followed must be the `<view-timeline-name>` value followed by the `<view-timeline-axis>` value. +The `view-timeline` shorthand property can be applied to a container element as a combination of the `<view-timeline-name>`, `<view-timeline-inset>` and `<view-timeline-axis>` values. At least one of the values must be specified. If both the values are specified, the order followed must be the `<view-timeline-name>` value followed by the `<view-timeline-axis>` value and/or the `<view-timeline-inset>` value. > **Note:** `<view-timeline-name>`s must be [`<dashed-ident>`](/en-US/docs/Web/CSS/dashed-ident) values, which means they must start with `--`. This helps avoid name clashes with standard CSS keywords. ### Values - `<view-timeline-name>` - - - : See [`view-timeline-name`](/en-US/docs/Web/CSS/view-timeline-name). - + - : See {{cssxref("view-timeline-name")}}. The default value is `none`. +- `<view-timeline-inset>` + - : See {{cssxref("view-timeline-inset")}}. The default value is `auto`. - `<view-timeline-axis>` - - : See [`view-timeline-axis`](/en-US/docs/Web/CSS/view-timeline-axis). The default value is `block`. + - : See {{cssxref("view-timeline-axis")}}. The default value is `block`. ## Formal definition @@ -187,7 +192,7 @@ Scroll to see the subject element being animated. ## See also -- [`animation-timeline`](/en-US/docs/Web/CSS/animation-timeline) +- {{cssxref("animation-timeline")}} - {{cssxref("timeline-scope")}} -- [`view-timeline-axis`](/en-US/docs/Web/CSS/view-timeline-axis), [`view-timeline-name`](/en-US/docs/Web/CSS/view-timeline-name) +- {{cssxref("view-timeline-axis")}}, {{cssxref("view-timeline-inset")}}, {{cssxref("view-timeline-name")}} - [CSS scroll-driven animations](/en-US/docs/Web/CSS/CSS_scroll-driven_animations) diff --git a/files/en-us/web/css/view-transition-class/index.md b/files/en-us/web/css/view-transition-class/index.md new file mode 100644 index 000000000000000..d0a7c7ef8fe3608 --- /dev/null +++ b/files/en-us/web/css/view-transition-class/index.md @@ -0,0 +1,86 @@ +--- +title: view-transition-class +slug: Web/CSS/view-transition-class +page-type: css-property +browser-compat: css.properties.view-transition-class +--- + +{{CSSRef}} + +The **`view-transition-class`** [CSS](/en-US/docs/Web/CSS) property provides the selected elements with an identifying class (a {{cssxref("custom-ident")}}), providing an additional method of styling the view transitions for those elements. + +## Syntax + +```css +/* <custom-ident> value examples */ +view-transition-class: card; + +/* Keyword value */ +view-transition-class: none; + +/* Global values */ +view-transition-class: inherit; +view-transition-class: initial; +view-transition-class: revert; +view-transition-class: revert-layer; +view-transition-class: unset; +``` + +### Values + +- {{cssxref("custom-ident")}} + - : An identifying name that causes the selected element to participate in a separate [view transition](/en-US/docs/Web/API/View_Transition_API) from the root view transition. The identifier must be unique. If two rendered elements have the same `view-transition-name` at the same time, {{domxref("ViewTransition.ready")}} will reject and the transition will be skipped. +- `none` + - : No class would apply to the named view transition pseudo-elements generated for this element. + +## Description + +The `view-transition-class` value provides a styling hook, similar to a CSS class name, which can be used to apply the same styles to multiple view transition pseudo-elements. It does not mark an element for capturing. Each individual element still needs its own unique {{cssxref("view-transition-name")}}; the `view-transition-class` is only used as an additional way to style elements that already have a `view-transition-name`. +Support for determining the `view-transition-name` automatically is being discussed in the [CSS View Transitions Module Level 2](https://drafts.csswg.org/css-view-transitions-2/#auto-vt-name) spec. + +The `view-transition-class` apply styles using the view transition pseudo-elements, including {{cssxref("::view-transition-group()")}}, {{cssxref("::view-transition-image-pair()")}}, {{cssxref("::view-transition-old()")}}, and {{cssxref("::view-transition-new()")}}. This is different from the `view-transition-name`, which matches view transitions between the element in the old state with its corresponding element in the new state. + +Until the `view-transition-class` property is fully supported in all browsers supporting view transitions, include a custom `::view-transition-group()` for each element. + +## Formal definition + +{{cssinfo}} + +## Formal syntax + +{{csssyntax}} + +## Examples + +```css +::view-transition-group(fast-card-slide) { + animation-duration: 3s; +} + +.product { + view-transition-class: fast-card-slide; +} + +.product#card1 { + view-transition-name: show-card; +} + +.product#card2 { + view-transition-name: hide-card; +} +``` + +## Specifications + +{{Specifications}} + +## Browser compatibility + +{{Compat}} + +## See also + +- {{cssxref("view-transition-name")}} +- [Using the View Transition API](/en-US/docs/Web/API/View_Transition_API/Using) guide +- [View Transition API](/en-US/docs/Web/API/View_Transition_API) +- [Smooth transitions with the View Transition API](https://developer.chrome.com/docs/web-platform/view-transitions/) diff --git a/files/en-us/web/css/view-transition-name/index.md b/files/en-us/web/css/view-transition-name/index.md index 08a596e38a8904b..8b73472c9c522e3 100644 --- a/files/en-us/web/css/view-transition-name/index.md +++ b/files/en-us/web/css/view-transition-name/index.md @@ -55,5 +55,6 @@ figcaption { ## See also +- {{cssxref("view-transition-class")}} - [View Transition API](/en-US/docs/Web/API/View_Transition_API) - [Smooth transitions with the View Transition API](https://developer.chrome.com/docs/web-platform/view-transitions/) diff --git a/files/en-us/web/css/visibility/index.md b/files/en-us/web/css/visibility/index.md index d9521b843e0ecde..16a833d59158822 100644 --- a/files/en-us/web/css/visibility/index.md +++ b/files/en-us/web/css/visibility/index.md @@ -9,7 +9,51 @@ browser-compat: css.properties.visibility The **`visibility`** [CSS](/en-US/docs/Web/CSS) property shows or hides an element without changing the layout of a document. The property can also hide rows or columns in a {{HTMLElement("table")}}. -{{EmbedInteractiveExample("pages/css/visibility.html")}} +{{InteractiveExample("CSS Demo: visibility")}} + +```css interactive-example-choice +visibility: visible; +``` + +```css interactive-example-choice +visibility: hidden; +``` + +```css interactive-example-choice +visibility: collapse; +``` + +```html interactive-example +<section class="default-example" id="default-example"> + <div class="example-container"> + <div class="transition-all" id="example-element">Hide me</div> + <div>Item 2</div> + <div>Item 3</div> + </div> +</section> +``` + +```css interactive-example +.example-container { + border: 1px solid #c5c5c5; + padding: 0.75em; + width: 80%; + max-height: 300px; + display: flex; +} + +.example-container > div { + background-color: rgba(0, 0, 255, 0.2); + border: 3px solid blue; + margin: 10px; + flex: 1; +} + +#example-element { + background-color: rgba(255, 0, 200, 0.2); + border: 3px solid rebeccapurple; +} +``` To both hide an element _and remove it from the document layout_, set the {{cssxref("display")}} property to `none` instead of using `visibility`. @@ -36,7 +80,7 @@ The `visibility` property is specified as one of the keyword values listed below - `visible` - : The element box is visible. - `hidden` - - : The element box is invisible (not drawn), but still affects layout as normal. Descendants of the element will be visible if they have `visibility` set to `visible`. The element cannot receive focus (such as when navigating through [tab indexes](/en-US/docs/Web/HTML/Global_attributes/tabindex)). + - : The element box is invisible (not drawn), but still affects layout as normal. Descendants of the element will be visible if they have `visibility` set to `visible`. The element cannot receive focus (such as when navigating through [tab indexes](/en-US/docs/Web/HTML/Reference/Global_attributes/tabindex)). - `collapse` - : The `collapse` keyword has different effects for different elements: @@ -56,7 +100,7 @@ When animated, visibility values are interpolated between _visible_ and _not-vis ## Notes - Support for `visibility: collapse` is missing or partially incorrect in some modern browsers. It may not be correctly treated like `visibility: hidden` on elements other than table rows and columns. -- When applied to table rows, if the table contains cells ({{htmlelement("td")}} {{htmlelement("tr")}} elements) that span both visible and collapsed rows, the cell may render in unexpected ways. If the spanning cell is defined in a collapsed row, browsers do not render the table cell, as if the cells in subsequent rows were present with `visibility: collapse` applied. When the cell is defined in a visible row and spans a collapsed row, the cell contents are not reflowed, but the presentation of the cell itself varies by browser. Most browsers reduce the block size of the cell by the block size of the hidden row. This means the contents may be larger than the cell in the block-size direction. Depending on the browser, the overflowing contents are either cropped, as if `overflow: hidden` were set, while the content bleeds into the subsequent row in other browsers as if `overflow: visible` were set. In other browsers, the cell is rendered as if the row were not collapsed, with all the other cells in the row hidden as if `visibility: collapse` were set on individual cells rather than the row itself. +- When applied to table rows, if the table contains cells ({{htmlelement("td")}} and {{htmlelement("th")}} elements) that span both visible and collapsed rows, the cell may render in unexpected ways. If the spanning cell is defined in a collapsed row, browsers do not render the table cell, as if the cells in subsequent rows were present with `visibility: collapse` applied. When the cell is defined in a visible row and spans a collapsed row, the cell contents are not reflowed, but the presentation of the cell itself varies by browser. Most browsers reduce the block size of the cell by the block size of the hidden row. This means the contents may be larger than the cell in the block-size direction. Depending on the browser, the overflowing contents are either cropped, as if `overflow: hidden` were set, while the content bleeds into the subsequent row in other browsers as if `overflow: visible` were set. In other browsers, the cell is rendered as if the row were not collapsed, with all the other cells in the row hidden as if `visibility: collapse` were set on individual cells rather than the row itself. - `visibility: collapse` may change the layout of a table if the table has nested tables within the cells that are collapsed, unless `visibility: visible` is specified explicitly on nested tables. ## Formal definition diff --git a/files/en-us/web/css/visual_formatting_model/index.md b/files/en-us/web/css/visual_formatting_model/index.md deleted file mode 100644 index 43ee5d5874e1480..000000000000000 --- a/files/en-us/web/css/visual_formatting_model/index.md +++ /dev/null @@ -1,263 +0,0 @@ ---- -title: Visual formatting model -slug: Web/CSS/Visual_formatting_model -page-type: guide ---- - -{{CSSRef}} - -In CSS, the **visual formatting model** describes how user agents take the document tree, and process and display it for visual media. This includes {{glossary("continuous media")}} such as a computer screen and [paged media](/en-US/docs/Web/CSS/CSS_paged_media) such as a book or document printed by browser print functions. Most of the information applies equally to continuous and paged media. - -In the visual formatting model, each element in the document tree generates zero or more boxes according to the box model. The layout of these boxes is governed by: - -- Box dimensions and type. -- Positioning scheme (normal flow, float, and absolute positioning). -- Relationships between elements in the document tree. -- External information (e.g., viewport size, intrinsic dimensions of images, etc.). - -Much of the information about the visual formatting model is defined in CSS2, however, various CSS layout modules have expanded upon this information. When reading specifications you will often find references to the model as defined in CSS2, so an understanding of the model and the terms used to describe it in CSS2 is valuable when reading other layout specifications. - -In this document we define the model and introduce some of the related terms and concepts, linking to more specific pages for further details. - -## The role of the viewport - -In continuous media, the {{glossary("viewport")}} is the viewing area of the browser window. User agents can change the layout of the page when the viewport size changes — for example, if you resize your window, or change the orientation of a mobile device. - -If the viewport is smaller than the size of the document then the user agent needs to offer a way to scroll to the parts of the document that are not displayed. We most often see this as scrolling in the **block dimension** — vertically in a horizontal, top-to-bottom language. However, you might design something that requires scrolling in the **inline dimension** too. - -## Box generation - -**Box generation** is the part of the CSS visual formatting model that creates boxes from the document's elements. Generated boxes are of different types, which affect their visual formatting. The type of the box generated depends on the value of the CSS {{cssxref("display")}} property. - -Initially defined in CSS2, the `display` property was extended in the [CSS display](/en-US/docs/Web/CSS/CSS_display), [CSS flexible layout](/en-US/docs/Web/CSS/CSS_flexible_layout), [CSS grid layout](/en-US/docs/Web/CSS/CSS_grid_layout), and [CSS ruby layout](/en-US/docs/Web/CSS/CSS_ruby) modules. In addition, some of the terminologies around the display have been updated and clarified in the years since CSS2. - -CSS takes your source document and renders it onto a canvas. To do this, it generates an intermediary structure, the **box tree**, which represents the formatting structure of the rendered document. Each box in the box tree represents its corresponding element (or pseudo-element) in space and/or time on the canvas, while each text run in the box tree likewise represents the contents of its corresponding text nodes. - -Then, for each element, CSS generates zero or more boxes as specified by that element's `display` property value. - -> [!NOTE] -> Boxes are often referred to by their display type — e.g. a box generated by an element with `display: block` is called a "block box" or just a "block". Note however that block boxes, block-level boxes and box containers are all subtly different; see the [block boxes](#block_boxes) section below for more details. - -### The principal box - -When an element generates one or more boxes, one of them is the **principal box**, which contains its descendant boxes and generated content in the box tree, and is also the box involved in any positioning scheme. - -Some elements may generate additional boxes in addition to the principal box, for example `display: list-item` generates more than one box (e.g. a **principal block box** and a **child marker box**). And some values (such as `none` or `contents`) cause the element and/or its descendants to not generate any boxes at all. - -### Anonymous boxes - -An **anonymous box** is created when there is not an HTML element to use for the box. This situation happens when, for example, you declare `display: flex` on a parent element, and directly inside there is a run of text not contained in another element. In order to fix the box tree, an anonymous box is created around that run of text. It will then behave as a flex item, however, it cannot be targeted and styled like a regular box because there is no element to target. - -```html live-sample___anonymous-flex -<div class="flex"> - I am wrapped in an anonymous box - <p>I am in the paragraph</p> - I am wrapped in an anonymous box. -</div> -``` - -```css live-sample___anonymous-flex -body { - font: 1.2em sans-serif; - margin: 20px; -} - -.flex { - display: flex; -} - -.flex > * { - background-color: rebeccapurple; - color: white; -} -``` - -{{EmbedLiveSample("anonymous-flex")}} - -The same thing happens when you have text runs interspersed with block elements. In the next example I have a string inside a `<div>`; in the middle of my string is a `<p>` element containing part of the text. - -```html live-sample___anonymous-block -<div class="example"> - I am wrapped in an anonymous box - <p>I am in the paragraph</p> - I am wrapped in an anonymous box. -</div> -``` - -```css live-sample___anonymous-block -body { - font: 1.2em sans-serif; - margin: 20px; -} - -.example > * { - background-color: rebeccapurple; - color: white; -} -``` - -{{EmbedLiveSample("anonymous-block")}} - -The string is split into three boxes in the box tree. The part of the string before the paragraph element is wrapped in an anonymous box, then we have the `<p>`, which generates a box, and then another anonymous box. - -Something to consider about these anonymous boxes is that they inherit styles from their direct parent, but you cannot change how they look by targeting the anonymous box. In my examples, I am using a direct child selector to target the children of the container. This does not change the anonymous boxes, as they are not "elements" as such. - -**Inline anonymous boxes** are created when a string is split by an inline element, for example, a sentence that includes a section wrapped with `<em></em>`. This splits the sentence into three inline boxes — an anonymous inline box before the emphasized section, the section wrapped in the `<em>` element, then a final anonymous inline box. As with the anonymous block boxes, these anonymous inline boxes cannot be styled independently in the way the `<em>` can; they just inherit the styles of their container. - -Other formatting contexts also create anonymous boxes. [Grid layout](/en-US/docs/Web/CSS/CSS_grid_layout) behaves in the same way as the [flexbox](/en-US/docs/Web/CSS/CSS_flexible_box_layout) example above, turning strings of text into a grid item with an anonymous box. [Multiple-column](/en-US/docs/Web/CSS/CSS_multicol_layout) layout creates anonymous column boxes around the columns; these also cannot be styled or otherwise targeted. [Table layout](/en-US/docs/Web/CSS/CSS_table) will add anonymous boxes to create a proper table structure — for example adding an anonymous table row — if there was no box with `display: table-row`. - -### Line boxes - -**Line boxes** are the boxes that wrap each line of text. You can see the difference between line boxes and their containing block if you float an item and then follow it by a block that has a background color. - -In the following example, the line boxes following the floated `<div>` are shortened to wrap around the float. The background of the box runs behind the float, as the floated item has been taken out of flow. - -```html live-sample___line-boxes -<div class="float"></div> -<p class="following"> - This text is following the float, the line boxes are shortened to make room - for the float but the box of the element still takes position in normal flow. -</p> -``` - -```css live-sample___line-boxes -body { - font: 1.2em sans-serif; - margin: 20px; -} - -.float { - float: left; - width: 150px; - height: 150px; - background-color: rebeccapurple; - margin: 20px; -} - -.following { - background-color: #ccc; -} -``` - -{{EmbedLiveSample("line-boxes", "", "250px")}} - -## Positioning schemes and in-flow and out-of-flow elements - -In CSS, a box may be laid out according to three positioning schemes — **normal flow**, **floats**, or **absolute positioning**. - -### Normal flow - -In CSS, the normal flow includes block-level formatting of block boxes, inline-level formatting of inline boxes, and also includes relative and sticky positioning of block-level and inline-level boxes. - -Read more about [flow layout](/en-US/docs/Web/CSS/CSS_display/flow_layout) in CSS. - -### Floats - -In the float model, a box is first laid out according to the normal flow, then taken out of the flow and positioned, typically to the left or right. Content may flow along the side of a float. - -Find out more about [floats](/en-US/docs/Learn_web_development/Core/CSS_layout/Floats). - -### Absolute positioning - -In the absolute positioning model (which also includes `fixed` positioning), a box is removed from the normal flow entirely and assigned a position relative to a containing block (which is the viewport in the case of fixed positioning) or to one or more anchor elements in [CSS anchor positioning](/en-US/docs/Web/CSS/CSS_anchor_positioning). - -An element is called **out of flow** if it is floated, absolutely positioned, or is the root element. An element is called **in-flow** if it is not out of the flow. - -Read about [CSS positioned layout](/en-US/docs/Web/CSS/CSS_positioned_layout). - -## Formatting contexts and the display property - -Boxes can be described as having an **outer display type**, which is `block` or `inline`. This outer display type refers to how the box behaves alongside other elements on the page. - -Boxes also have an inner display type, dictating how their children behave. For normal block and inline layout, or normal flow, this display type is `flow`. This means that the child elements will also be either `block` or `inline`. - -However, the inner display type might be something like `grid` or `flex`, in which case the direct children will display as a grid, or flex items. In such a case the element is described as creating a grid or flex [formatting context](/en-US/docs/Web/CSS/CSS_display/Introduction_to_formatting_contexts). In many ways, this is similar to a block formatting context, however, the children behave as flex or grid items rather than items in normal flow. - -The interactions between block-level and inline-level boxes are described in the {{cssxref("display")}} property reference. - -In addition, the references for specific values of display explain how these formatting contexts work in terms of box layout. - -- [CSS grid layout](/en-US/docs/Web/CSS/CSS_grid_layout) module -- [CSS flexible box layout](/en-US/docs/Web/CSS/CSS_flexible_box_layout) module -- [CSS multi-column layout](/en-US/docs/Web/CSS/CSS_multicol_layout) module -- [CSS table](/en-US/docs/Web/CSS/CSS_table) module -- [CSS lists and counters](/en-US/docs/Web/CSS/CSS_lists) module - -### Independent formatting contexts - -Elements either participate in the formatting context of their containing block or establish an independent formatting context. A grid container, for example, establishes a new **grid formatting context** for its children. - -**Independent formatting contexts** contain floats, and margins do not collapse across formatting context boundaries. Therefore, creating a new block formatting context can ensure that floats and margins remain inside a box. To do this, add `display: flow-root` to the box on which you wish to create a new [block formatting context](/en-US/docs/Web/CSS/CSS_display/Block_formatting_context). - -The following example shows the effect of `display: flow-root`. The box with the black background appears to wrap around the floated item and text. If you remove `display: flow-root`, the floated item will poke out of the bottom of the box as it is no longer contained. - -```html live-sample___block-flow-root -<div class="container"> - <div class="item">Floated</div> - <p>Text following the float.</p> -</div> -``` - -```css hidden live-sample___block-flow-root -body { - font: 1.2em sans-serif; - margin: 20px; -} -.container { - background-color: #333; - color: #fff; -} - -.item { - background-color: #fff; - border: 1px solid #999; - color: #333; - width: 100px; - height: 100px; - padding: 10px; -} -``` - -```css live-sample___block-flow-root -.container { - display: flow-root; -} - -.item { - margin: 10px; - float: left; -} -``` - -{{EmbedLiveSample("block-flow-root", "", "250px")}} - -### Block boxes - -In specifications, block boxes, block-level boxes, and block containers are all referred to as **block boxes** in certain places. These things are somewhat different and the term block box should only be used if there is no ambiguity. - -#### Block containers - -A **block container** either contains only inline-level boxes participating in an inline formatting context, or only block-level boxes participating in a block formatting context. For this reason, we see the behavior explained above, where anonymous boxes are introduced to ensure all of the items can participate in a block or inline formatting context. An element is a block container only if it contains block-level or inline-level boxes. - -#### Inline-level and block-level boxes - -These are the boxes contained inside the block container that are participating in inline or block layout, respectively. - -#### Block boxes - -A block box is a block-level box that is also a block container. As described in CSS `display`, a box can be a block-level box, but not also a block container (it might be a flex or grid container for example). - -## See also - -- [CSS syntax](/en-US/docs/Web/CSS/CSS_syntax/Syntax) guide -- [Comments](/en-US/docs/Web/CSS/CSS_syntax/Comments) -- [Specificity](/en-US/docs/Web/CSS/CSS_cascade/Specificity) -- [Inheritance](/en-US/docs/Web/CSS/CSS_cascade/Inheritance) -- [Stacking context](/en-US/docs/Web/CSS/CSS_positioned_layout/Understanding_z-index/Stacking_context) -- [Block formatting context](/en-US/docs/Web/CSS/CSS_display/Block_formatting_context) -- [Box model](/en-US/docs/Web/CSS/CSS_box_model/Introduction_to_the_CSS_box_model) -- [Layout modes](/en-US/docs/Web/CSS/Layout_mode) -- [Margin collapsing](/en-US/docs/Web/CSS/CSS_box_model/Mastering_margin_collapsing) -- [Replaced elements](/en-US/docs/Web/CSS/Replaced_element) -- {{DOMxRef("VisualViewport")}} interface -- {{glossary("Scroll container")}} diff --git a/files/en-us/web/css/webkit_extensions/index.md b/files/en-us/web/css/webkit_extensions/index.md index c6528bee40ac394..8586ff941bbe8d6 100644 --- a/files/en-us/web/css/webkit_extensions/index.md +++ b/files/en-us/web/css/webkit_extensions/index.md @@ -1,5 +1,5 @@ --- -title: -webkit-prefixed CSS extensions +title: WebKit (-webkit-) vendor-prefixed CSS extensions slug: Web/CSS/WebKit_Extensions page-type: landing-page status: @@ -8,236 +8,183 @@ status: {{CSSRef}} -User agents based on WebKit or Blink, such as Safari and Chrome, support several special extensions to [CSS](/en-US/docs/Web/CSS). These extensions are prefixed with `-webkit-`. +A {{glossary("vendor prefix")}} is used to indicate that a feature is specific to a certain browser. +User agents based on WebKit or Blink (such as Safari and Chrome) support several extensions to [CSS](/en-US/docs/Web/CSS), which are prefixed with `-webkit-`. ## -webkit-prefixed properties without standard equivalents > [!NOTE] -> Avoid using on websites. These properties will only work in WebKit- or Blink-based browsers except where specified. +> These properties work in WebKit- or Blink-based browsers except where support notes say otherwise. +> You should avoid using them on production websites. ### A-C -- {{CSSxRef("-webkit-app-region")}} -- {{CSSxRef("-webkit-border-horizontal-spacing")}} -- {{CSSxRef("-webkit-border-vertical-spacing")}} -- {{CSSxRef("-webkit-box-reflect")}} (supported with `-webkit-` by every browser, for compatibility reasons) -- {{CSSxRef("-webkit-column-axis")}} -- {{CSSxRef("-webkit-column-progression")}} -- {{CSSxRef("-webkit-cursor-visibility")}} - -### D-I - -- {{CSSxRef("font-smooth", "-webkit-font-smoothing")}} -- {{CSSxRef("-webkit-hyphenate-limit-after")}} -- {{CSSxRef("-webkit-hyphenate-limit-before")}} -- {{CSSxRef("-webkit-hyphenate-limit-lines")}} - -### L - -- {{CSSxRef("-webkit-line-align")}} -- {{CSSxRef("-webkit-line-box-contain")}} -- {{CSSxRef("line-clamp", "-webkit-line-clamp")}} -- {{CSSxRef("-webkit-line-grid")}} -- {{CSSxRef("-webkit-line-snap")}} -- {{CSSxRef("-webkit-locale")}} -- {{CSSxRef("-webkit-logical-height")}} -- {{CSSxRef("-webkit-logical-width")}} +- `-webkit-app-region` {{deprecated_inline}}: No longer supported in Safari. +- `-webkit-border-horizontal-spacing` +- `-webkit-border-vertical-spacing` +- {{CSSxRef("-webkit-box-reflect")}}: Supported with `-webkit-` by every browser, for compatibility reasons. +- `-webkit-column-axis`: Not supported in Chrome. +- `-webkit-column-progression`: Not supported in Chrome. +- `-webkit-cursor-visibility`: Not supported in Chrome. + +### D-L + +- `-webkit-font-smoothing`: See {{CSSxRef("font-smooth")}}. +- `-webkit-hyphenate-limit-after`: Not supported in Chrome. +- `-webkit-hyphenate-limit-before`: Not supported in Chrome. +- `-webkit-hyphenate-limit-lines`: Not supported in Chrome. +- `-webkit-line-align`: Not supported in Chrome. +- `-webkit-line-box-contain`: Not supported in Chrome. +- `-webkit-line-grid`: Not supported in Chrome. +- `-webkit-line-snap`: Not supported in Chrome. +- `-webkit-locale` +- `-webkit-logical-height` +- `-webkit-logical-width` ### M -- {{CSSxRef("-webkit-margin-after")}} -- {{CSSxRef("-webkit-margin-before")}} -- {{CSSxRef("-webkit-mask-box-image-outset")}} -- {{CSSxRef("-webkit-mask-box-image-repeat")}} -- {{CSSxRef("-webkit-mask-box-image-slice")}} -- {{CSSxRef("-webkit-mask-box-image-source")}} -- {{CSSxRef("-webkit-mask-box-image-width")}} -- {{CSSxRef("-webkit-mask-box-image")}} -- {{cssxref("-webkit-mask-composite")}} -- {{CSSxRef("-webkit-mask-position-x")}} (supported with `-webkit-` by every browser, for compatibility reasons) -- {{CSSxRef("-webkit-mask-position-y")}} (supported with `-webkit-` by every browser, for compatibility reasons) -- {{CSSxRef("-webkit-mask-repeat-x")}} (also supported without prefix) -- {{CSSxRef("-webkit-mask-repeat-y")}} (also supported without prefix) -- {{CSSxRef("-webkit-mask-source-type")}} -- {{CSSxRef("-webkit-max-logical-height")}} -- {{CSSxRef("-webkit-max-logical-width")}} -- {{CSSxRef("-webkit-min-logical-height")}} -- {{CSSxRef("-webkit-min-logical-width")}} - -### N-R - -- {{CSSxRef("-webkit-nbsp-mode")}} -- {{CSSxRef("-webkit-perspective-origin-x")}} -- {{CSSxRef("-webkit-perspective-origin-y")}} -- {{CSSxRef("-webkit-rtl-ordering")}} - -### T - -- {{CSSxRef("-webkit-tap-highlight-color")}} -- {{CSSxRef("-webkit-text-decoration-skip")}} -- {{CSSxRef("-webkit-text-decorations-in-effect")}} +- `-webkit-margin-after` +- `-webkit-margin-before` +- {{CSSxRef("-webkit-mask-box-image")}}: See {{cssxref("mask-border")}} and {{cssxref("border-image")}}. +- {{CSSxRef("-webkit-mask-box-image", "-webkit-mask-box-image-outset")}}: See {{cssxref("mask-border")}} and {{cssxref("border-image")}}. +- {{CSSxRef("-webkit-mask-box-image", "-webkit-mask-box-image-repeat")}}: See {{cssxref("mask-border")}} and {{cssxref("border-image")}}. +- {{CSSxRef("-webkit-mask-box-image", "-webkit-mask-box-image-slice")}}: See {{cssxref("mask-border")}} and {{cssxref("border-image")}}. +- {{CSSxRef("-webkit-mask-box-image", "-webkit-mask-box-image-source")}}: See {{cssxref("mask-border")}} and {{cssxref("border-image")}}. +- {{CSSxRef("-webkit-mask-box-image", "-webkit-mask-box-image-width")}}: See {{cssxref("mask-border")}} and {{cssxref("border-image")}}. +- {{CSSxRef("-webkit-mask-composite")}}: See {{cssxref("mask-border")}} and {{cssxref("border-image")}}. +- {{CSSxRef("-webkit-mask-position-x")}}: Supported with `-webkit-` by every browser for compatibility reasons. +- {{CSSxRef("-webkit-mask-position-y")}}: Supported with `-webkit-` by every browser for compatibility reasons. +- {{CSSxRef("-webkit-mask-repeat-x")}} {{deprecated_inline}}: No longer supported; see {{CSSxRef("mask-repeat")}}. +- {{CSSxRef("-webkit-mask-repeat-y")}} {{deprecated_inline}}: No longer supported; see {{CSSxRef("mask-repeat")}}. +- `-webkit-mask-source-type`: Not supported in Chrome. +- `-webkit-max-logical-height` +- `-webkit-max-logical-width` +- `-webkit-min-logical-height` +- `-webkit-min-logical-width` + +### N-Z + +- `-webkit-nbsp-mode`: Not supported in Chrome. +- `-webkit-perspective-origin-x` +- `-webkit-perspective-origin-y` +- `-webkit-rtl-ordering` +- {{CSSxRef("-webkit-tap-highlight-color")}}: Only supported in Safari on iOS. +- `-webkit-text-decoration-skip`: Not supported in Chrome. +- `-webkit-text-decorations-in-effect` - {{CSSxRef("-webkit-text-fill-color")}} - {{CSSxRef("-webkit-text-security")}} +- {{CSSxRef("-webkit-text-stroke")}} - {{CSSxRef("-webkit-text-stroke-color")}} - {{CSSxRef("-webkit-text-stroke-width")}} -- {{CSSxRef("-webkit-text-stroke")}} -- {{CSSxRef("-webkit-text-zoom")}} -- {{cssxref("-webkit-touch-callout")}} -- {{CSSxRef("-webkit-transform-origin-x")}} -- {{CSSxRef("-webkit-transform-origin-y")}} -- {{CSSxRef("-webkit-transform-origin-z")}} - -### U-Z - -- {{CSSxRef("-webkit-user-drag")}} -- {{CSSxRef("-webkit-user-modify")}} +- `-webkit-text-zoom`: Not supported in Chrome. +- {{CSSxRef("-webkit-touch-callout")}} {{deprecated_inline}}: Only supported in Safari on iOS. +- `-webkit-transform-origin-x` +- `-webkit-transform-origin-y` +- `-webkit-transform-origin-z` +- `-webkit-user-drag` +- `-webkit-user-modify` ## -webkit-prefixed properties with standard equivalents -Several old `-webkit-` prefixed properties have standard equivalents. Even if the name and syntax may be different, they shouldn't be used anymore at all. - -For each of them, use the standard equivalent provided. +Several `-webkit-` prefixed properties have standard equivalents. +Even if the name and syntax may be different, they shouldn't be used any more. +For each of the properties below, use the standard equivalents. ### A-B -- `-webkit-border-after` - - : Use the standard {{CSSxRef("border-block-end")}} property instead. -- `-webkit-border-after-color` - - : Use the standard {{CSSxRef("border-block-end-color")}} property instead. -- `-webkit-border-after-style` - - : Use the standard {{CSSxRef("border-block-end-style")}} property instead. -- `-webkit-border-after-width` - - : Use the standard {{CSSxRef("border-block-end-width")}} property instead. -- `-webkit-border-before` - - : Use the standard {{CSSxRef("border-block-start")}} property instead. -- `-webkit-border-before-color` - - : Use the standard {{CSSxRef("border-block-start-color")}} property instead. -- `-webkit-border-before-style` - - : Use the standard {{CSSxRef("border-block-start-style")}} property instead. -- `-webkit-border-before-width` - - : Use the standard {{CSSxRef("border-block-start-width")}} property instead. -- `-webkit-border-end` - - : Use the standard {{CSSxRef("border-inline-end")}} property instead. -- `-webkit-border-end-color` - - : Use the standard {{CSSxRef("border-inline-end-color")}} property instead. -- `-webkit-border-end-style` - - : Use the standard {{CSSxRef("border-inline-end-style")}} property instead. -- `-webkit-border-end-width` - - : Use the standard {{CSSxRef("border-inline-end-width")}} property instead. -- `-webkit-border-start` - - : Use the standard {{CSSxRef("border-inline-start")}} property instead. -- `-webkit-border-start-color` - - : Use the standard {{CSSxRef("border-inline-start-color")}} property instead. -- `-webkit-border-start-style` - - : Use the standard {{CSSxRef("border-inline-start-style")}} property instead. -- `-webkit-border-start-width` - - : Use the standard {{CSSxRef("border-inline-start-width")}} property instead. -- `-webkit-box-align` - - : Use the [CSS flexible box layout](/en-US/docs/Web/CSS/CSS_flexible_box_layout) with the standard {{CSSxRef("align-items")}} property instead. -- `-webkit-box-direction` - - : Use the [CSS flexible box layout](/en-US/docs/Web/CSS/CSS_flexible_box_layout) with the standard {{CSSxRef("flex-direction")}} property instead. -- {{CSSxRef("box-flex-group", "-webkit-box-flex-group")}} - - : Use the [CSS flexible box layout](/en-US/docs/Web/CSS/CSS_flexible_box_layout) with the standard {{cssxref("flex-basis")}}, {{cssxref("flex-grow")}}, and {{cssxref("flex-shrink")}} properties instead. -- `-webkit-box-flex` - - : Use the [CSS flexible box layout](/en-US/docs/Web/CSS/CSS_flexible_box_layout) with the standard {{CSSxRef("flex-grow")}} property instead. -- `-webkit-box-lines` - - : Use the [CSS flexible box layout](/en-US/docs/Web/CSS/CSS_flexible_box_layout) with the standard {{CSSxRef("flex-flow")}} property instead. -- `-webkit-box-ordinal-group` - - : Use the [CSS flexible box layout](/en-US/docs/Web/CSS/CSS_flexible_box_layout) with the standard {{CSSxRef("order")}} property instead. -- `-webkit-box-orient` - - : Use the [CSS flexible box layout](/en-US/docs/Web/CSS/CSS_flexible_box_layout) with the standard {{CSSxRef("flex-direction")}} property instead. -- `-webkit-box-pack` - - : Use the [CSS flexible box layout](/en-US/docs/Web/CSS/CSS_flexible_box_layout) with the standard {{CSSxRef("justify-content")}} property instead. +- `-webkit-border-after`: Use {{CSSxRef("border-block-end")}}. +- `-webkit-border-after-color`: Use {{CSSxRef("border-block-end-color")}}. +- `-webkit-border-after-style`: Use {{CSSxRef("border-block-end-style")}}. +- `-webkit-border-after-width`: Use {{CSSxRef("border-block-end-width")}}. +- {{CSSxRef("-webkit-border-before")}}: Use {{CSSxRef("border-block-start")}}. +- `-webkit-border-before-color`: Use {{CSSxRef("border-block-start-color")}}. +- `-webkit-border-before-style`: Use {{CSSxRef("border-block-start-style")}}. +- `-webkit-border-before-width`: Use {{CSSxRef("border-block-start-width")}}. +- `-webkit-border-end`: Use {{CSSxRef("border-inline-end")}}. +- `-webkit-border-end-color`: Use {{CSSxRef("border-inline-end-color")}}. +- `-webkit-border-end-style`: Use {{CSSxRef("border-inline-end-style")}}. +- `-webkit-border-end-width`: Use {{CSSxRef("border-inline-end-width")}}. +- `-webkit-border-start`: Use {{CSSxRef("border-inline-start")}}. +- `-webkit-border-start-color`: Use {{CSSxRef("border-inline-start-color")}} +- `-webkit-border-start-style`: Use {{CSSxRef("border-inline-start-style")}}. +- `-webkit-border-start-width`: Use {{CSSxRef("border-inline-start-width")}}. +- `-webkit-box-align`: Use [CSS flexbox](/en-US/docs/Web/CSS/CSS_flexible_box_layout) with {{CSSxRef("align-items")}}. +- `-webkit-box-direction`: Use [CSS flexbox](/en-US/docs/Web/CSS/CSS_flexible_box_layout) with {{CSSxRef("flex-direction")}}. +- {{CSSxRef("box-flex-group", "-webkit-box-flex-group")}}: Use [CSS flexbox](/en-US/docs/Web/CSS/CSS_flexible_box_layout) with {{CSSxRef("flex-basis")}}, {{CSSxRef("flex-grow")}}, and {{CSSxRef("flex-shrink")}}. +- `-webkit-box-flex`: Use [CSS flexbox](/en-US/docs/Web/CSS/CSS_flexible_box_layout) with {{CSSxRef("flex-grow")}}. +- `-webkit-box-lines`: Use [CSS flexbox](/en-US/docs/Web/CSS/CSS_flexible_box_layout) with {{CSSxRef("flex-flow")}}. +- `-webkit-box-ordinal-group`: Use [CSS flexbox](/en-US/docs/Web/CSS/CSS_flexible_box_layout) with {{CSSxRef("order")}}. +- `-webkit-box-orient`: Use [CSS flexbox](/en-US/docs/Web/CSS/CSS_flexible_box_layout) with {{CSSxRef("flex-direction")}}. +- `-webkit-box-pack`: Use [CSS flexbox](/en-US/docs/Web/CSS/CSS_flexible_box_layout) with {{CSSxRef("justify-content")}}. +- {{CSSxRef("-webkit-box-reflect")}}: Use the CSS {{CSSxRef("element", "element()")}} function. ### C-I -- `-webkit-column-break-after` - - : Use the [CSS multicolumn layout](/en-US/docs/Web/CSS/CSS_multicol_layout) with the standard {{cssxref("break-after")}} property instead. -- `-webkit-column-break-before` - - : Use the [CSS multicolumn layout](/en-US/docs/Web/CSS/CSS_multicol_layout) with the standard {{cssxref("break-before")}} property instead. -- `-webkit-column-break-inside` - - : Use the [CSS multicolumn layout](/en-US/docs/Web/CSS/CSS_multicol_layout) with the standard {{cssxref("break-inside")}} property instead. -- `-webkit-font-feature-settings` - - : Use the [`font-feature-settings`](/en-US/docs/Web/CSS/font-feature-settings) property instead. -- `-webkit-hyphenate-character` - - : Use the standard {{cssxref("hyphenate-character")}} property instead. -- `-webkit-initial-letter` - - : Use the standard {{cssxref("initial-letter")}} property instead. +- `-webkit-column-break-after`: Use [CSS multicolumn layout](/en-US/docs/Web/CSS/CSS_multicol_layout) with {{CSSxRef("break-after")}}. +- `-webkit-column-break-before`: Use [CSS multicolumn layout](/en-US/docs/Web/CSS/CSS_multicol_layout) with {{CSSxRef("break-before")}}. +- `-webkit-column-break-inside`: Use [CSS multicolumn layout](/en-US/docs/Web/CSS/CSS_multicol_layout) with {{CSSxRef("break-inside")}}. +- `-webkit-font-feature-settings`: Use {{CSSxRef("font-feature-settings")}} (the prefixed version not supported in Safari). +- `-webkit-hyphenate-character`: Use {{CSSxRef("hyphenate-character")}}. +- `-webkit-initial-letter`: Use {{CSSxRef("initial-letter")}}. ### J-Z -- `-webkit-margin-end` - - : Use the standard {{CSSxRef("margin-block-end")}} property instead. -- `-webkit-margin-start` - - : Use the standard {{CSSxRef("margin-block-start")}} property instead. -- `-webkit-padding-after` - - : Use the standard {{CSSxRef("padding-block-end")}} property instead. -- `-webkit-padding-before` - - : Use the standard {{CSSxRef("padding-block-start")}} property instead. -- `-webkit-padding-end` - - : Use the standard {{CSSxRef("padding-inline-end")}} property instead. -- `-webkit-padding-start` - - : Use the standard {{CSSxRef("padding-inline-start")}} property instead. - -## -webkit-prefixed property values - -- `-webkit-fill-available` - - : Used with sizing properties like {{CSSxRef("width")}} and {{CSSxRef("height")}}, to allow elements to take up all the available space within their parent container. The flexbox `stretch` value (see for example {{CSSxRef("align-items")}} and {{CSSxRef("justify-items")}}) provides a standard replacement. +- `-webkit-line-clamp`: Use {{CSSxRef("line-clamp")}}. +- `-webkit-margin-end`: Use {{CSSxRef("margin-block-end")}}. +- `-webkit-margin-start`: Use {{CSSxRef("margin-block-start")}}. +- `-webkit-padding-after`: Use {{CSSxRef("padding-block-end")}}. +- `-webkit-padding-before`: Use {{CSSxRef("padding-block-start")}}. +- `-webkit-padding-end`: Use {{CSSxRef("padding-inline-end")}}. +- `-webkit-padding-start`: Use {{CSSxRef("padding-inline-start")}}. ## Pseudo-classes -- {{CSSxRef(":animating-full-screen-transition", ":-webkit-animating-full-screen-transition")}} -- {{CSSxRef(":is", ":-webkit-any()")}} -- {{CSSxRef(":any-link", ":-webkit-any-link")}}\* -- {{CSSxRef(":autofill",":-webkit-autofill")}} -- {{CSSxRef(":autofill-strong-password",":-webkit-autofill-strong-password")}} -- {{CSSxRef(":drag",":-webkit-drag")}} -- {{CSSxRef(":full-page-media",":-webkit-full-page-media")}} -- {{CSSxRef(":full-screen", ":-webkit-full-screen")}}\* -- {{CSSxRef(":full-screen-ancestor",":-webkit-full-screen-ancestor")}} -- {{CSSxRef(":full-screen-document",":-webkit-full-screen-document")}} -- {{CSSxRef(":full-screen-controls-hidden",":-webkit-full-screen-controls-hidden")}} - -\* Now standard. - > [!NOTE] > If there is an invalid pseudo-class within in a chain or group of selectors, the whole selector list is invalid. +- `:-webkit-any()`: Use {{CSSxRef(":is")}} +- `:-webkit-any-link`: Use {{CSSxRef(":any-link")}} +- `:-webkit-autofill`: Use {{CSSxRef(":autofill")}} +- `:-webkit-autofill-strong-password`: Use {{CSSxRef(":autofill")}} +- `:-webkit-drag` +- `:-webkit-full-page-media`: Use {{CSSxRef(":fullscreen")}} +- `:-webkit-full-screen`: Use {{CSSxRef(":fullscreen")}} +- `:-webkit-full-screen-ancestor`: Use {{CSSxRef(":fullscreen")}} +- `:-webkit-full-screen-document`: Use {{CSSxRef(":fullscreen")}} +- `:-webkit-full-screen-controls-hidden`: Use {{CSSxRef(":fullscreen")}} + ## Pseudo-elements For web-compatibility reasons, Blink, WebKit, and Gecko browsers treat all pseudo-elements starting with `::-webkit-` as valid. - -- {{CSSxRef("::file-selector-button","::-webkit-file-upload-button")}}\* -- {{CSSxRef("::-webkit-inner-spin-button", "::-webkit-inner-spin-button")}} -- {{CSSxRef("::placeholder", "::-webkit-input-placeholder")}} -- {{CSSxRef("::-webkit-meter-bar", "::-webkit-meter-bar")}} -- {{CSSxRef("::-webkit-meter-even-less-good-value", "::-webkit-meter-even-less-good-value")}} -- {{CSSxRef("::-webkit-meter-inner-element", "::-webkit-meter-inner-element")}} -- {{CSSxRef("::-webkit-meter-optimum-value", "::-webkit-meter-optimum-value")}} -- {{CSSxRef("::-webkit-meter-suboptimum-value", "::-webkit-meter-suboptimum-value")}} -- {{CSSxRef("::-webkit-progress-bar", "::-webkit-progress-bar")}} -- {{CSSxRef("::-webkit-progress-inner-element", "::-webkit-progress-inner-element")}} -- {{CSSxRef("::-webkit-progress-value", "::-webkit-progress-value")}} -- {{CSSxRef("::-webkit-search-cancel-button", "::-webkit-search-cancel-button")}} -- {{CSSxRef("::-webkit-search-results-button", "::-webkit-search-results-button")}} -- {{CSSxRef("::-webkit-slider-runnable-track", "::-webkit-slider-runnable-track")}} -- {{CSSxRef("::-webkit-slider-thumb", "::-webkit-slider-thumb")}} - -\* Now standard. - -> [!NOTE] -> Generally, if there is an invalid pseudo-element or pseudo-class within in a chain or group of selectors, the whole selector list is invalid. If a pseudo-element (but not pseudo-class) has a -webkit- prefix, As of Firefox 63, Blink, WebKit and Gecko browsers assume it is valid, not invalidating the selector list. +If there is an invalid pseudo-element or pseudo-class within in a chain or group of selectors, the whole selector list is invalid. +If a pseudo-element (but not pseudo-class) has a `-webkit-` prefix, Blink, WebKit and Gecko browsers assume it is valid, not invalidating the selector list. + +- `::-webkit-file-upload-button`: Use {{CSSxRef("::file-selector-button")}} +- {{CSSxRef("::-webkit-inner-spin-button")}} +- `::-webkit-input-placeholder`: Use {{CSSxRef("::placeholder")}} +- {{CSSxRef("::-webkit-meter-bar")}} {{deprecated_inline}} +- {{CSSxRef("::-webkit-meter-even-less-good-value")}} +- {{CSSxRef("::-webkit-meter-inner-element")}} +- {{CSSxRef("::-webkit-meter-optimum-value")}} +- {{CSSxRef("::-webkit-meter-suboptimum-value")}} +- {{CSSxRef("::-webkit-progress-bar")}} +- {{CSSxRef("::-webkit-progress-inner-element")}} +- {{CSSxRef("::-webkit-progress-value")}} +- {{CSSxRef("::-webkit-search-cancel-button")}} +- {{CSSxRef("::-webkit-search-results-button")}} +- {{CSSxRef("::-webkit-slider-runnable-track")}} +- {{CSSxRef("::-webkit-slider-thumb")}} ## Media features -- {{CSSxRef("@media/-webkit-animation", "-webkit-animation")}} -- {{CSSxRef("@media/-webkit-device-pixel-ratio", "-webkit-device-pixel-ratio")}} -- {{CSSxRef("@media/-webkit-transform-2d", "-webkit-transform-2d")}} -- {{CSSxRef("@media/-webkit-transform-3d", "-webkit-transform-3d")}} -- {{CSSxRef("@media/-webkit-transition", "-webkit-transition")}} +- {{CSSxRef("@media/-webkit-animation")}} {{deprecated_inline}} +- {{CSSxRef("@media/-webkit-device-pixel-ratio")}}: Supported cross-browser +- {{CSSxRef("@media/-webkit-transform-2d")}} {{deprecated_inline}} +- {{CSSxRef("@media/-webkit-transform-3d")}}: Supported cross-browser +- {{CSSxRef("@media/-webkit-transition")}} {{deprecated_inline}} ## See also -- [Vendor Prefix](/en-US/docs/Glossary/Vendor_Prefix) glossary entry -- [Mozilla vendor-prefixed CSS extensions](/en-US/docs/Web/CSS/Mozilla_Extensions) +- [Mozilla (-moz-) vendor-prefixed CSS extensions](/en-US/docs/Web/CSS/Mozilla_Extensions) +- {{glossary("Vendor Prefix")}} glossary entry - [Styling Form Controls on the WebKit Trac](https://trac.webkit.org/wiki/Styling%20Form%20Controls) diff --git a/files/en-us/web/css/white-space-collapse/index.md b/files/en-us/web/css/white-space-collapse/index.md index 6e4a97581553da9..302ab1f7e4262a1 100644 --- a/files/en-us/web/css/white-space-collapse/index.md +++ b/files/en-us/web/css/white-space-collapse/index.md @@ -64,7 +64,7 @@ User agents handle white space collapsing as follows: - If spaces are to be collapsed: - Spaces or tabs before or after segment breaks are removed. - Sequences of spaces are converted, or "collapsed", to a single space. -- When spaces are preserved, sequences of spaces are treated as non-breaking except that they will soft-wrap at the end of each sequence — i.e. the next line will always start with the next non-space character. In the case of the `break-spaces` value however, a soft wrap could potentially occur after each space, so the next line may start with one or more spaces. +- When spaces are preserved, sequences of spaces are treated as non-breaking except that they will soft-wrap at the end of each sequence — i.e., the next line will always start with the next non-space character. In the case of the `break-spaces` value however, a soft wrap could potentially occur after each space, so the next line may start with one or more spaces. ## Formal definition diff --git a/files/en-us/web/css/white-space/index.md b/files/en-us/web/css/white-space/index.md index f02fddcae6c264f..d6976d8d1a32aa7 100644 --- a/files/en-us/web/css/white-space/index.md +++ b/files/en-us/web/css/white-space/index.md @@ -9,7 +9,61 @@ browser-compat: css.properties.white-space The **`white-space`** [CSS](/en-US/docs/Web/CSS) property sets how {{Glossary("whitespace", "white space")}} inside an element is handled. -{{EmbedInteractiveExample("pages/css/white-space.html")}} +{{InteractiveExample("CSS Demo: white-space")}} + +```css interactive-example-choice +white-space: normal; +``` + +```css interactive-example-choice +white-space: pre; +``` + +```css interactive-example-choice +white-space: pre-wrap; +``` + +```css interactive-example-choice +white-space: pre-line; +``` + +```css interactive-example-choice +white-space: wrap; +``` + +```css interactive-example-choice +white-space: collapse; +``` + +```css interactive-example-choice +white-space: preserve nowrap; +``` + +<!-- cSpell:ignore stept --> + +```html interactive-example +<section class="default-example" id="default-example"> + <div id="example-element"> + <p> + But ere she from the church-door stepped She smiled and told us why: 'It + was a wicked woman's curse,' Quoth she, 'and what care I?' She smiled, and + smiled, and passed it off Ere from the door she stept— + </p> + </div> +</section> +``` + +```css interactive-example +#example-element { + width: 16rem; +} + +#example-element p { + border: 1px solid #c5c5c5; + padding: 0.75rem; + text-align: left; +} +``` The property specifies two things: diff --git a/files/en-us/web/css/width/index.md b/files/en-us/web/css/width/index.md index 03ecdb7389a7756..08e5ff307e7d55d 100644 --- a/files/en-us/web/css/width/index.md +++ b/files/en-us/web/css/width/index.md @@ -9,7 +9,42 @@ browser-compat: css.properties.width The **`width`** [CSS](/en-US/docs/Web/CSS) property sets an element's width. By default, it sets the width of the [content area](/en-US/docs/Web/CSS/CSS_box_model/Introduction_to_the_CSS_box_model#content_area), but if {{cssxref("box-sizing")}} is set to `border-box`, it sets the width of the [border area](/en-US/docs/Web/CSS/CSS_box_model/Introduction_to_the_CSS_box_model#border_area). -{{EmbedInteractiveExample("pages/css/width.html")}} +{{InteractiveExample("CSS Demo: width")}} + +```css interactive-example-choice +width: 150px; +``` + +```css interactive-example-choice +width: 20em; +``` + +```css interactive-example-choice +width: 75%; +``` + +```css interactive-example-choice +width: auto; +``` + +```html interactive-example +<section class="default-example" id="default-example"> + <div class="transition-all" id="example-element"> + This is a box where you can change the width. + </div> +</section> +``` + +```css interactive-example +#example-element { + display: flex; + flex-direction: column; + background-color: #5b6dcd; + height: 80%; + justify-content: center; + color: #ffffff; +} +``` The specified value of `width` applies to the content area so long as its value remains within the values defined by {{cssxref("min-width")}} and {{cssxref("max-width")}}. @@ -60,21 +95,18 @@ width: unset; - `min-content` - : The intrinsic minimum width. - `fit-content` - - : Use the available space, but not more than [max-content](/en-US/docs/Web/CSS/max-content), i.e. `min(max-content, max(min-content, stretch))`. + - : Use the available space, but not more than [max-content](/en-US/docs/Web/CSS/max-content), i.e., `min(max-content, max(min-content, stretch))`. - `fit-content({{cssxref("&lt;length-percentage&gt;")}})` - - : Uses the fit-content formula with the available space replaced by the specified argument, i.e. `min(max-content, max(min-content, <length-percentage>))`. + - : Uses the fit-content formula with the available space replaced by the specified argument, i.e., `min(max-content, max(min-content, <length-percentage>))`. - `stretch` - : Sets the width of the element's [margin box](/en-US/docs/Learn_web_development/Core/Styling_basics/Box_model#parts_of_a_box) to the width of its [containing block](/en-US/docs/Web/CSS/CSS_display/Containing_block#identifying_the_containing_block). It attempts to make the margin box fill the available space in the containing block, so in a way behaving similar to `100%` but applying the resulting size to the margin box rather than the box determined by [box-sizing](/en-US/docs/Web/CSS/box-sizing). - > [!NOTE] - > To check aliases used by browsers for the `stretch` value and its implementation status, see the [Browser compatibility](#browser_compatibility) section. - ## Accessibility Ensure that elements set with a `width` aren't truncated and/or don't obscure other content when the page is zoomed to increase text size. -- [MDN Understanding WCAG, Guideline 1.4 explanations](/en-US/docs/Web/Accessibility/Understanding_WCAG/Perceivable#guideline_1.4_make_it_easier_for_users_to_see_and_hear_content_including_separating_foreground_from_background) +- [MDN Understanding WCAG, Guideline 1.4 explanations](/en-US/docs/Web/Accessibility/Guides/Understanding_WCAG/Perceivable#guideline_1.4_make_it_easier_for_users_to_see_and_hear_content_including_separating_foreground_from_background) - [Understanding Success Criterion 1.4.4 | W3C Understanding WCAG 2.0](https://www.w3.org/TR/UNDERSTANDING-WCAG20/visual-audio-contrast-scale.html) ## Formal definition @@ -90,13 +122,13 @@ Ensure that elements set with a `width` aren't truncated and/or don't obscure ot ### Default width ```css -p.goldie { +p.gold { background: gold; } ``` ```html -<p class="goldie">The MDN community writes really great documentation.</p> +<p class="gold">The MDN community writes really great documentation.</p> ``` {{EmbedLiveSample('Default_width', '500px', '64px')}} @@ -172,6 +204,55 @@ p.min-blue { {{EmbedLiveSample('Example using "min-content"', '500px', '155px')}} +### Stretch width to fill the containing block + +#### HTML + +```html +<div class="parent"> + <div class="child">text</div> +</div> + +<div class="parent"> + <div class="child stretch">stretch</div> +</div> +``` + +#### CSS + +```css hidden +@supports not (width: stretch) { + .parent { + display: none !important; + } + + body::after { + content: "Your browser doesn't support the `stretch` value yet."; + } +} +``` + +```css +.parent { + border: solid; + margin: 1rem; + display: flex; +} + +.child { + background: #0999; + margin: 1rem; +} + +.stretch { + width: stretch; +} +``` + +#### Result + +{{EmbedLiveSample('Stretch width to fill the containing block', 'auto', 250)}} + ## Specifications {{Specifications}} diff --git a/files/en-us/web/css/will-change/index.md b/files/en-us/web/css/will-change/index.md index e0b480325f47640..f1daa0f427da0b4 100644 --- a/files/en-us/web/css/will-change/index.md +++ b/files/en-us/web/css/will-change/index.md @@ -17,7 +17,7 @@ Proper usage of this property can be a bit tricky: - _Use sparingly._ The normal behavior for optimizations that the browser make is to remove the optimizations as soon as it can and revert back to normal. But adding `will-change` directly in a stylesheet implies that the targeted elements are always a few moments away from changing and the browser will keep the optimizations for much longer time than it would have otherwise. So it is a good practice to switch `will-change` on and off using script code before and after the change occurs. - _Don't apply will-change to elements to perform premature optimization_. If your page is performing well, don't add the `will-change` property to elements just to wring out a little more speed. `will-change` is intended to be used as something of a last resort, in order to try to deal with existing performance problems. It should not be used to anticipate performance problems. Excessive use of `will-change` will result in excessive memory use and will cause more complex rendering to occur as the browser attempts to prepare for the possible change. This will lead to worse performance. - _Give it sufficient time to work_. This property is intended as a method for authors to let the user-agent know about properties that are likely to change ahead of time. Then the browser can choose to apply any ahead-of-time optimizations required for the property change before the property change actually happens. So it is important to give the browser some time to actually do the optimizations. Find some way to predict at least slightly ahead of time that something will change, and set `will-change` then. -- _Be aware, that will-change may actually influence the visual appearance of elements_, when used with property values, that create a [stacking context](/en-US/docs/Web/CSS/CSS_positioned_layout/Understanding_z-index/Stacking_context) (e.g. will-change: opacity), as the stacking context is created up front. +- _Be aware, that will-change may actually influence the visual appearance of elements_, when used with property values, that create a [stacking context](/en-US/docs/Web/CSS/CSS_positioned_layout/Stacking_context) (e.g., will-change: opacity), as the stacking context is created up front. ## Syntax diff --git a/files/en-us/web/css/word-break/index.md b/files/en-us/web/css/word-break/index.md index d973a635af61c18..931f429007f0a5d 100644 --- a/files/en-us/web/css/word-break/index.md +++ b/files/en-us/web/css/word-break/index.md @@ -9,7 +9,42 @@ browser-compat: css.properties.word-break The **`word-break`** [CSS](/en-US/docs/Web/CSS) property sets whether line breaks appear wherever the text would otherwise overflow its content box. -{{EmbedInteractiveExample("pages/css/word-break.html")}} +{{InteractiveExample("CSS Demo: word-break")}} + +```css interactive-example-choice +word-break: normal; +``` + +```css interactive-example-choice +word-break: break-all; +``` + +```css interactive-example-choice +word-break: keep-all; +``` + +```css interactive-example-choice +word-break: break-word; +``` + +```html interactive-example +<section class="default-example" id="default-example"> + <div class="transition-all" id="example-element"> + Honorificabilitudinitatibus califragilisticexpialidocious + Taumatawhakatangihangakoauauotamateaturipukakapikimaungahoronukupokaiwhenuakitanatahu + グレートブリテンおよび北アイルランド連合王国という言葉は本当に長い言葉 + </div> +</section> +``` + +```css interactive-example +#example-element { + width: 80%; + padding: 20px; + text-align: start; + border: solid 1px darkgray; +} +``` ## Syntax diff --git a/files/en-us/web/css/word-spacing/index.md b/files/en-us/web/css/word-spacing/index.md index e14bc27e74c7c82..81cd91c65b0d2ff 100644 --- a/files/en-us/web/css/word-spacing/index.md +++ b/files/en-us/web/css/word-spacing/index.md @@ -9,7 +9,46 @@ browser-compat: css.properties.word-spacing The **`word-spacing`** [CSS](/en-US/docs/Web/CSS) property sets the length of space between words and between tags. -{{EmbedInteractiveExample("pages/css/word-spacing.html")}} +{{InteractiveExample("CSS Demo: word-spacing")}} + +```css interactive-example-choice +word-spacing: normal; +``` + +```css interactive-example-choice +word-spacing: 1rem; +``` + +```css interactive-example-choice +word-spacing: 4px; +``` + +```css interactive-example-choice +word-spacing: -0.4ch; +``` + +```html interactive-example +<section id="default-example"> + <p id="example-element"> + As much mud in the streets as if the waters had but newly retired from the + face of the earth, and it would not be wonderful to meet a Megalosaurus, + forty feet long or so, waddling like an elephantine lizard up Holborn Hill. + </p> +</section> +``` + +```css interactive-example +@font-face { + src: url("/shared-assets/fonts/variable-fonts/AmstelvarAlpha-VF.ttf"); + font-family: Amstelvar; + font-style: normal; +} + +section { + font-size: 1.2em; + font-family: Amstelvar; +} +``` ## Syntax @@ -42,7 +81,7 @@ A large positive or negative `word-spacing` value will make the sentences the st Legible `word-spacing` must be determined on a case-by-case basis, as different font families have different character widths. There is no one value that can ensure all font families automatically maintain their legibility. -- [MDN Understanding WCAG, Guideline 1.4 explanations](/en-US/docs/Web/Accessibility/Understanding_WCAG/Perceivable#guideline_1.4_make_it_easier_for_users_to_see_and_hear_content_including_separating_foreground_from_background) +- [MDN Understanding WCAG, Guideline 1.4 explanations](/en-US/docs/Web/Accessibility/Guides/Understanding_WCAG/Perceivable#guideline_1.4_make_it_easier_for_users_to_see_and_hear_content_including_separating_foreground_from_background) - [Understanding Success Criterion 1.4.8 | W3C Understanding WCAG 2.0](https://www.w3.org/TR/UNDERSTANDING-WCAG20/visual-audio-contrast-visual-presentation.html) ## Examples diff --git a/files/en-us/web/css/writing-mode/index.md b/files/en-us/web/css/writing-mode/index.md index 76e6d5de9a690cf..98c47c8c4de8ab4 100644 --- a/files/en-us/web/css/writing-mode/index.md +++ b/files/en-us/web/css/writing-mode/index.md @@ -9,7 +9,55 @@ browser-compat: css.properties.writing-mode The **`writing-mode`** [CSS](/en-US/docs/Web/CSS) property sets whether lines of text are laid out horizontally or vertically, as well as the direction in which blocks progress. When set for an entire document, it should be set on the root element (`html` element for HTML documents). -{{EmbedInteractiveExample("pages/css/writing-mode.html")}} +{{InteractiveExample("CSS Demo: writing-mode")}} + +```css interactive-example-choice +writing-mode: horizontal-tb; +``` + +```css interactive-example-choice +writing-mode: vertical-lr; +``` + +```css interactive-example-choice +writing-mode: vertical-rl; +``` + +```css interactive-example-choice +writing-mode: sideways-rl; +``` + +```css interactive-example-choice +writing-mode: sideways-lr; +``` + +```html interactive-example +<section class="default-example" id="default-example"> + <div class="transition-all" id="example-element"> + <div>1</div> + <div>2</div> + <div>3</div> + <div>4</div> + </div> +</section> +``` + +```css interactive-example +#example-element { + border: 1px solid #c5c5c5; + padding: 0.75em; + width: 80%; + max-height: 300px; + display: flex; +} + +#example-element > div { + background-color: rgba(0, 0, 255, 0.2); + border: 3px solid blue; + margin: 10px; + flex: 1; +} +``` This property specifies the _block flow direction_, which is the direction in which block-level containers are stacked, and the direction in which inline-level content flows within a block container. Thus, it also determines the ordering of block-level content. @@ -298,5 +346,6 @@ span { - [CSS logical properties](/en-US/docs/Web/CSS/CSS_logical_properties_and_values) - [CSS writing modes](/en-US/docs/Web/CSS/CSS_writing_modes) module - SVG {{SVGAttr("writing-mode")}} attribute -- [Styling vertical text (Chinese, Japanese, Korean and Mongolian)](https://www.w3.org/International/articles/vertical-text/) on W3.org (2022) - [Creating vertical form controls](/en-US/docs/Web/CSS/CSS_writing_modes/Vertical_controls) +- [Handling different text directions](/en-US/docs/Learn_web_development/Core/Styling_basics/Handling_different_text_directions) +- [Styling vertical text (Chinese, Japanese, Korean and Mongolian)](https://www.w3.org/International/articles/vertical-text/) on W3.org (2022) diff --git a/files/en-us/web/css/z-index/index.md b/files/en-us/web/css/z-index/index.md index c6fc686f566ae29..c9ae85a26684882 100644 --- a/files/en-us/web/css/z-index/index.md +++ b/files/en-us/web/css/z-index/index.md @@ -9,11 +9,122 @@ browser-compat: css.properties.z-index The **`z-index`** [CSS](/en-US/docs/Web/CSS) property sets the z-order of a [positioned](/en-US/docs/Web/CSS/position) element and its descendants or flex and grid items. Overlapping elements with a larger z-index cover those with a smaller one. -{{EmbedInteractiveExample("pages/css/z-index.html")}} +{{InteractiveExample("CSS Demo: z-index")}} + +```css interactive-example-choice +z-index: auto; +``` + +```css interactive-example-choice +z-index: 1; +``` + +```css interactive-example-choice +z-index: 3; +``` + +```css interactive-example-choice +z-index: 5; +``` + +```css interactive-example-choice +z-index: 7; +``` + +```html interactive-example +<section class="default-example container" id="default-example"> + <div id="example-element">Change my z-index</div> + <div class="block blue position1">z-index: 6</div> + <div class="block blue position2">z-index: 4</div> + <div class="block blue position3">z-index: 2</div> + <div class="block red position4">z-index: auto</div> + <div class="block red position5">z-index: auto</div> + <div class="block red position6">z-index: auto</div> +</section> +``` + +```css interactive-example +#example-element { + top: 15px; + left: 15px; + width: 180px; + height: 230px; + position: absolute; + /* center the text so it is visible even when z-index is set to auto */ + line-height: 215px; + font-family: monospace; + background-color: #fcfbe5; + border: solid 5px #e3e0a1; + z-index: auto; + color: black; +} + +.container { + display: inline-block; + width: 250px; + position: relative; +} + +.block { + width: 150px; + height: 50px; + position: absolute; + font-family: monospace; + color: black; +} + +.blue { + background-color: #e5e8fc; + border: solid 5px #112382; + /* move text to the bottom of the box */ + line-height: 55px; +} + +.red { + background-color: #fce5e7; + border: solid 5px #e3a1a7; +} + +.position1 { + top: 0; + left: 0; + z-index: 6; +} + +.position2 { + top: 30px; + left: 30px; + z-index: 4; +} + +.position3 { + top: 60px; + left: 60px; + z-index: 2; +} + +.position4 { + top: 150px; + left: 0; + z-index: auto; +} + +.position5 { + top: 180px; + left: 30px; + z-index: auto; +} + +.position6 { + top: 210px; + left: 60px; + z-index: auto; +} +``` For a positioned box (that is, one with any `position` other than `static`), the `z-index` property specifies: -1. The stack level of the box in the current [stacking context](/en-US/docs/Web/CSS/CSS_positioned_layout/Understanding_z-index/Stacking_context). +1. The stack level of the box in the current [stacking context](/en-US/docs/Web/CSS/CSS_positioned_layout/Stacking_context). 2. Whether the box establishes a local stacking context. ## Syntax diff --git a/files/en-us/web/css/zoom/index.md b/files/en-us/web/css/zoom/index.md index 0f073ce101f0808..b08c3235728aaf8 100644 --- a/files/en-us/web/css/zoom/index.md +++ b/files/en-us/web/css/zoom/index.md @@ -52,7 +52,7 @@ Two non-standard keyword values are not recommended. Check [browser compatibilit - `normal` - : Render the element at its normal size; equal to `zoom: 1`. Use the global {{cssxref("unset")}} keyword value instead. - `reset` - - : Resets the value to `zoom: 1` and prevents the element from being (de)magnified if the user applies non-pinch-based zooming (e.g. by pressing <kbd>Ctrl</kbd> \- <kbd>-</kbd> or <kbd>Ctrl</kbd> \+ <kbd>+</kbd> keyboard shortcuts) to the document. + - : Resets the value to `zoom: 1` and prevents the element from being (de)magnified if the user applies non-pinch-based zooming (e.g., by pressing <kbd>Ctrl</kbd> \- <kbd>-</kbd> or <kbd>Ctrl</kbd> \+ <kbd>+</kbd> keyboard shortcuts) to the document. ## Formal definition @@ -233,7 +233,7 @@ In this final CSS block we are checking to see if the browser supports `zoom` an #### JavaScript -This JavaScript watches for a change in the select field and sets the new value for `--zoom-level` on the content `section`, e.g. `style="--zoom-level: 1.5;"`. +This JavaScript watches for a change in the select field and sets the new value for `--zoom-level` on the content `section`, e.g., `style="--zoom-level: 1.5;"`. ```js const zoomControl = document.querySelector("#zoom"); diff --git a/files/en-us/web/events/event_handlers/index.md b/files/en-us/web/events/event_handlers/index.md index 948f42909ff91b8..aa65cb192624bf2 100644 --- a/files/en-us/web/events/event_handlers/index.md +++ b/files/en-us/web/events/event_handlers/index.md @@ -12,11 +12,11 @@ This page provides a very brief "reminder" of how to work with events and event Events are documented in and/or below the pages for the JavaScript objects that emit them. For example, to find out events fired on the browser window or the current document see the events sections in [`Window`](/en-US/docs/Web/API/Window#events) and [`Document`](/en-US/docs/Web/API/Document#events). -You can use the [Event reference](/en-US/docs/Web/Events#event_index) to find out what JavaScript objects fire events for particular APIs, e.g. animation, media, and so on. +You can use the [Event reference](/en-US/docs/Web/Events#event_index) to find out what JavaScript objects fire events for particular APIs, e.g., animation, media, and so on. ## Registering event handlers -There are two recommended approaches for registering handlers. Event handler code can be made to run when an event is triggered by assigning it to the target element's corresponding _onevent_ property, or by registering the handler as a listener for the element using the {{domxref("EventTarget.addEventListener", "addEventListener()")}} method. In either case the handler will receive an object that conforms to the [`Event` interface](/en-US/docs/Web/API/Event) (or a [derived interface](/en-US/docs/Web/API/Event#introduction)). The main difference is that multiple event handlers can be added (or removed) using the event listener methods. +There are two recommended approaches for registering handlers. Event handler code can be made to run when an event is triggered by assigning it to the target element's corresponding _onevent_ property, or by registering the handler as a listener for the element using the {{domxref("EventTarget.addEventListener", "addEventListener()")}} method. In either case the handler will receive an object that conforms to the [`Event` interface](/en-US/docs/Web/API/Event) (or a [derived interface](/en-US/docs/Web/API/Event#interfaces_based_on_event)). The main difference is that multiple event handlers can be added (or removed) using the event listener methods. > [!WARNING] > A third approach for setting event handlers using HTML onevent attributes is not recommended! They inflate the markup and make it less readable and harder to debug. For more information see [Inline event handlers](/en-US/docs/Learn_web_development/Core/Scripting/Events#inline_event_handlers_—_dont_use_these). @@ -27,7 +27,7 @@ By convention, JavaScript objects that fire events have a corresponding "onevent To set event handler code you can just assign it to the appropriate onevent property. Only one event handler can be assigned for every event in an element. If needed the handler can be replaced by assigning another function to the same property. -Below we show how to set a simple `greet()` function for the `click` event using the `onclick` property. +Below we show how to set a `greet()` function for the `click` event using the `onclick` property. ```js const btn = document.querySelector("button"); @@ -48,7 +48,7 @@ The most flexible way to set an event handler on an element is to use the {{domx > [!NOTE] > The ability to add and remove event handlers allows you to, for example, have the same button performing different actions in different circumstances. In addition, in more complex programs cleaning up old/unused event handlers can improve efficiency. -Below we show how a simple `greet()` function can be set as a listener/event handler for the `click` event (you could use an anonymous function expression instead of a named function if desired). Note again that the event is passed as the first argument to the event handler. +Below we show how a `greet()` function can be set as a listener/event handler for the `click` event (you could use an anonymous function expression instead of a named function if desired). Note again that the event is passed as the first argument to the event handler. ```js const btn = document.querySelector("button"); diff --git a/files/en-us/web/events/index.md b/files/en-us/web/events/index.md index 122f77e31d575a3..d1a909a86d31c95 100644 --- a/files/en-us/web/events/index.md +++ b/files/en-us/web/events/index.md @@ -5,9 +5,9 @@ page-type: landing-page spec-urls: https://html.spec.whatwg.org/multipage/indices.html#events-2 --- -[Events](/en-US/docs/Learn_web_development/Core/Scripting/Events) are fired to notify code of "interesting changes" that may affect code execution. These can arise from user interactions such as using a mouse or resizing a window, changes in the state of the underlying environment (e.g. low battery or media events from the operating system), and other causes. +[Events](/en-US/docs/Learn_web_development/Core/Scripting/Events) are fired to notify code of "interesting changes" that may affect code execution. These can arise from user interactions such as using a mouse or resizing a window, changes in the state of the underlying environment (e.g., low battery or media events from the operating system), and other causes. -Each event is represented by an object that is based on the {{domxref("Event")}} interface, and may have additional custom fields and/or functions to provide information about what happened. The documentation for every event has a table (near the top) that includes a link to the associated event interface, and other relevant information. A full list of the different event types is given in [Event > Interfaces based on Event](/en-US/docs/Web/API/Event#introduction). +Each event is represented by an object that is based on the {{domxref("Event")}} interface, and may have additional custom fields and/or functions to provide information about what happened. The documentation for every event has a table (near the top) that includes a link to the associated event interface, and other relevant information. A full list of the different event types is given in [Event > Interfaces based on Event](/en-US/docs/Web/API/Event#interfaces_based_on_event). This topic provides an index to the main _sorts_ of events you might be interested in (animation, clipboard, workers etc.) along with the main classes that implement those sorts of events. @@ -29,7 +29,7 @@ This topic provides an index to the main _sorts_ of events you might be interest >. </p> <p> - Used to respond to changes in animation status (e.g. when an animation + Used to respond to changes in animation status (e.g., when an animation starts or ends). </p> </td> @@ -460,8 +460,8 @@ This topic provides an index to the main _sorts_ of events you might be interest <a href="/en-US/docs/Web/API/TextTrackList#events" ><code>TextTrackList</code></a >, - <a href="/en-US/docs/Web/HTML/Element/audio#events">Element/audio</a>, - <a href="/en-US/docs/Web/HTML/Element/video#events">Element/video</a>. + <a href="/en-US/docs/Web/HTML/Reference/Elements/audio#events">Element/audio</a>, + <a href="/en-US/docs/Web/HTML/Reference/Elements/video#events">Element/video</a>. </td> </tr> <tr> @@ -668,7 +668,7 @@ This topic provides an index to the main _sorts_ of events you might be interest </p> <p> Provides notification events from interacting with a touch sensitive - screen (i.e. using a finger or stylus). Not related to the + screen (i.e., using a finger or stylus). Not related to the <a href="/en-US/docs/Web/API/Force_Touch_events#events" >Force Touch API</a >. @@ -696,7 +696,7 @@ This topic provides an index to the main _sorts_ of events you might be interest <strong>Warning:</strong> The <a href="/en-US/docs/Web/API/WebVR_API">WebVR API</a> (and associated - <a href="/en-US/docs/Web/API/Window#webvr_events" + <a href="/en-US/docs/Web/API/WebVR_API#window_events" ><code>Window</code> events</a >) are deprecated. </p> diff --git a/files/en-us/web/html/attributes/accept/index.md b/files/en-us/web/html/attributes/accept/index.md deleted file mode 100644 index 9173cbd7bd19ad7..000000000000000 --- a/files/en-us/web/html/attributes/accept/index.md +++ /dev/null @@ -1,183 +0,0 @@ ---- -title: "HTML attribute: accept" -short-title: accept -slug: Web/HTML/Attributes/accept -page-type: html-attribute -browser-compat: html.elements.input.accept ---- - -{{HTMLSidebar}} - -The **`accept`** attribute takes as its value a comma-separated list of one or more file types, or [unique file type specifiers](#unique_file_type_specifiers), describing which file types to allow. - -{{InteractiveExample("HTML Demo: accept", "tabbed-shorter")}} - -```html interactive-example -<label for="movie">Choose a movie to upload:</label> - -<input type="file" id="movie" name="movie" accept="video/*" /> - -<label for="poster">Choose a poster:</label> - -<input type="file" id="poster" name="poster" accept="image/png, image/jpeg" /> -``` - -```css interactive-example -label { - display: block; - margin-top: 1rem; -} - -input { - margin-bottom: 1rem; -} -``` - -## Overview - -The accept property is an attribute of the {{HTMLElement("input/file", "file")}} {{htmlelement("input")}} type. It was supported on the {{htmlelement("form")}} element, but was removed in favor of {{HTMLElement("input/file", "file")}}. - -Because a given file type may be identified in more than one manner, it's useful to provide a thorough set of type specifiers when you need files of specific type, or use the wild card to denote a type of any format is acceptable. - -For instance, there are a number of ways Microsoft Word files can be identified, so a site that accepts Word files might use an `<input>` like this: - -```html -<input - type="file" - id="docpicker" - accept=".doc,.docx,application/msword,application/vnd.openxmlformats-officedocument.wordprocessingml.document" /> -``` - -Whereas if you're accepting a media file, you may want to be include any format of that media type: - -```html -<input type="file" id="soundFile" accept="audio/*" /> -<input type="file" id="videoFile" accept="video/*" /> -<input type="file" id="imageFile" accept="image/*" /> -``` - -The `accept` attribute doesn't validate the types of the selected files; it provides hints for browsers to guide users towards selecting the correct file types. It is still possible (in most cases) for users to toggle an option in the file chooser that makes it possible to override this and select any file they wish, and then choose incorrect file types. - -Because of this, you should make sure that expected requirement is validated server-side. - -## Examples - -When set on a file input type, the native file picker that opens up should only enable selecting files of the correct file type. Most operating systems lighten the files that don't match the criteria and aren't selectable. - -```html -<p> - <label for="soundFile">Select an audio file:</label> - <input type="file" id="soundFile" accept="audio/*" /> -</p> -<p> - <label for="videoFile">Select a video file:</label> - <input type="file" id="videoFile" accept="video/*" /> -</p> -<p> - <label for="imageFile">Select some images:</label> - <input type="file" id="imageFile" accept="image/*" multiple /> -</p> -``` - -{{EmbedLiveSample('Examples', '100%', 200)}} - -Note the last example allows you to select multiple images. See the [`multiple`](/en-US/docs/Web/HTML/Element/input#multiple) attribute for more information. - -## Unique file type specifiers - -A **unique file type specifier** is a string that describes a type of file that may be selected by the user in an {{HTMLElement("input")}} element of type `file`. Each unique file type specifier may take one of the following forms: - -- A valid case-insensitive filename extension, starting with a period (".") character. For example: `.jpg`, `.pdf`, or `.doc`. -- A valid MIME type string, with no extensions. -- The string `audio/*` meaning "any audio file". -- The string `video/*` meaning "any video file". -- The string `image/*` meaning "any image file". - -The `accept` attribute takes as its value a string containing one or more of these unique file type specifiers, separated by commas. For example, a file picker that needs content that can be presented as an image, including both standard image formats and PDF files, might look like this: - -```html -<input type="file" accept="image/*,.pdf" /> -``` - -## Using file inputs - -### A basic example - -```html -<form method="post" enctype="multipart/form-data"> - <div> - <label for="file">Choose file to upload</label> - <input type="file" id="file" name="file" multiple /> - </div> - <div> - <button>Submit</button> - </div> -</form> -``` - -```css hidden -div { - margin-bottom: 10px; -} -``` - -This produces the following output: - -{{EmbedLiveSample('A_basic_example', 650, 60)}} - -> [!NOTE] -> You can find this example on GitHub too — see the [source code](https://github.com/mdn/learning-area/blob/main/html/forms/file-examples/simple-file.html), and also [see it running live](https://mdn.github.io/learning-area/html/forms/file-examples/simple-file.html). - -Regardless of the user's device or operating system, the file input provides a button that opens up a file picker dialog that allows the user to choose a file. - -Including the [`multiple`](/en-US/docs/Web/HTML/Element/input#multiple) attribute, as shown above, specifies that multiple files can be chosen at once. The user can choose multiple files from the file picker in any way that their chosen platform allows (e.g. by holding down <kbd>Shift</kbd> or <kbd>Control</kbd>, and then clicking). If you only want the user to choose a single file per `<input>`, omit the `multiple` attribute. - -### Limiting accepted file types - -Often you won't want the user to be able to pick any arbitrary type of file; instead, you often want them to select files of a specific type or types. For example, if your file input lets users upload a profile picture, you probably want them to select web-compatible image formats, such as {{Glossary("JPEG")}} or {{Glossary("PNG")}}. - -Acceptable file types can be specified with the [`accept`](/en-US/docs/Web/HTML/Element/input/file#accept) attribute, which takes a comma-separated list of allowed file extensions or MIME types. Some examples: - -- `accept="image/png"` or `accept=".png"` — Accepts PNG files. -- `accept="image/png, image/jpeg"` or `accept=".png, .jpg, .jpeg"` — Accept PNG or JPEG files. -- `accept="image/*"` — Accept any file with an `image/*` MIME type. (Many mobile devices also let the user take a picture with the camera when this is used.) -- `accept=".doc,.docx,.xml,application/msword,application/vnd.openxmlformats-officedocument.wordprocessingml.document"` — accept anything that smells like an MS Word document. - -Let's look at a more complete example: - -```html -<form method="post" enctype="multipart/form-data"> - <div> - <label for="profile_pic">Choose file to upload</label> - <input - type="file" - id="profile_pic" - name="profile_pic" - accept=".jpg, .jpeg, .png" /> - </div> - <div> - <button>Submit</button> - </div> -</form> -``` - -```css hidden -div { - margin-bottom: 10px; -} -``` - -{{EmbedLiveSample('Limiting_accepted_file_types', 650, 60)}} - -## Specifications - -{{Specifications}} - -## Browser compatibility - -{{Compat}} - -## See also - -- [Using files from web applications](/en-US/docs/Web/API/File_API/Using_files_from_web_applications) -- [File API](/en-US/docs/Web/API/File) diff --git a/files/en-us/web/html/attributes/autocomplete/index.md b/files/en-us/web/html/attributes/autocomplete/index.md deleted file mode 100644 index a0ee4758e44ad4a..000000000000000 --- a/files/en-us/web/html/attributes/autocomplete/index.md +++ /dev/null @@ -1,352 +0,0 @@ ---- -title: "HTML attribute: autocomplete" -short-title: autocomplete -slug: Web/HTML/Attributes/autocomplete -page-type: html-attribute -browser-compat: - - html.elements.form.autocomplete - - html.elements.input.autocomplete - - html.elements.select.autocomplete - - html.elements.textarea.autocomplete ---- - -{{HTMLSidebar}} - -The HTML `autocomplete` attribute lets web developers specify what if any permission the {{Glossary("user agent")}} has to provide automated assistance in filling out form field values, as well as guidance to the browser as to the type of information expected in the field. - -It is available on {{HTMLElement("input")}} elements that take a text or numeric value as input, {{HTMLElement("textarea")}} elements, {{HTMLElement("select")}} elements, and {{HTMLElement("form")}} elements. - -{{InteractiveExample("HTML Demo: autocomplete", "tabbed-shorter")}} - -```html interactive-example -<label for="firstName">First Name:</label> -<input name="firstName" id="firstName" type="text" autocomplete="given-name" /> - -<label for="lastName">Last Name:</label> -<input name="lastName" id="lastName" type="text" autocomplete="family-name" /> - -<label for="email">Email:</label> -<input name="email" id="email" type="email" autocomplete="off" /> -``` - -```css interactive-example -label { - display: block; - margin-top: 1rem; -} -``` - -## Description - -The `autocomplete` attribute provides a hint to the user agent specifying how to, or indeed whether to, prefill a form control. The attribute value is either the keyword `off` or `on`, or an ordered list of space-separated tokens. - -```html -<input autocomplete="off" /> -<input autocomplete="on" /> -<input autocomplete="shipping street-address" /> -<input autocomplete="section-user1 billing postal-code" /> -``` - -If an {{HTMLElement("input")}}, {{HTMLElement("select")}} or {{HTMLElement("textarea")}} element has no `autocomplete` attribute, the browser will use the [`autocomplete` attribute of the element's **owning form**](/en-US/docs/Web/HTML/Element/form#autocomplete). The owning form is either the {{HTMLElement("form")}} matching the `id` specified by the [`form`](/en-US/docs/Web/HTML/Element/input#form) attribute of the element (if present) or, more commonly, the `<form>` the element is nested in. - -> [!NOTE] -> In order to provide autocompletion, user-agents might require `<input>`/`<select>`/`<textarea>` elements to: -> -> 1. Have a `name` and/or `id` attribute -> 2. Be descendants of a `<form>` element -> 3. Be owned by a form with a {{HTMLElement("input/submit", "submit")}} button - -If the same list of tokens is used in more than one form control, the user-agent will autocomplete all occurrences of the same `autocomplete` value with the same data value. - -Some tokens may be used more than once with potentially different expected values, such as the `zip-code` token in a form that contains both shipping and billing addresses. Including multiple different tokens in a space-separated list causes the associated form controls to be given unique autocomplete values: in this case, `autocomplete="shipping zip-code"` and `autocomplete="billing zip-code"`. - -Some autocomplete values may need to be re-used multiple times. For example, a form may contain multiple shipping addresses and therefore multiple occurrences of `"shipping zip-code"` while still expecting different values. To make the autocomplete value unique in these cases, the first token in the space-separated list of tokens can be a `section-*` token, where the token's first eight characters are always the string "section-", followed by an alphanumeric string. All form fields given the `section-*` token with the same alphanumeric string belong to the same **named group**. - -If including the `autocomplete` attribute on {{HTMLElement("input/hidden", "hidden")}} input elements (`<input type="hidden">`), its value must be an ordered list of space-separated tokens; the `on` and `off` keywords are not allowed. - -The source of the suggested values is generally up to the browser; typically values come from past values entered by the user, but they may also come from pre-configured values. For instance, a browser might let the user save their name, address, phone number, and email addresses for autocomplete purposes. The browser may also offer the ability to save encrypted credit card information, for autocompletion following an authentication procedure. - -> [!NOTE] -> The `autocomplete` attribute also controls whether Firefox will — unlike other browsers — [persist the dynamic disabled state and (if applicable) dynamic checkedness](https://stackoverflow.com/questions/5985839/bug-with-firefox-disabled-attribute-of-input-not-resetting-when-refreshing) of an `<input>` element, `<textarea>` element, or entire `<form>` across page loads. The persistence feature is enabled by default. Setting the value of the `autocomplete` attribute to `off` disables this feature. This works even when the `autocomplete` attribute would normally not apply by virtue of its `type`. See [Firefox bug 654072](https://bugzil.la/654072). - -## Values - -The attribute value is either the keyword `off` or `on`, or a space-separated `<token-list>` that describes the meaning of the autocompletion value. - -- `off` - - - : The browser is not permitted to automatically enter or select a value for this field. It is possible that the document or application provides its own autocomplete feature, or that security concerns require that the field's value not be automatically entered. - - > [!NOTE] - > In most modern browsers, setting `autocomplete` to `"off"` will not prevent a password manager from asking the user if they would like to save username and password information, or from automatically filling in those values in a site's login form. See [Managing autofill for login fields](/en-US/docs/Web/Security/Practical_implementation_guides/Turning_off_form_autocompletion#managing_autofill_for_login_fields). - -- `on` - - - : The browser is allowed to automatically complete the input. No guidance is provided as to the type of data expected in the field, so the browser may use its own judgement. - -- `<token-list>` - - - : An ordered set of [space-separated tokens](#token_list_tokens) consisting of autofill detail tokens preceded by optional sectioning and either billing or shipping grouping tokens. Phone numbers, email addresses, and messaging protocol tokens are preceded by a token identifying the type of recipient. - -See the [WHATWG Standard](https://html.spec.whatwg.org/multipage/forms.html#autofill) for more detailed information. - -### Token list tokens - -The `<token-list>` options include, in order: - -1. [Group naming token](#named_groups) -2. [Grouping identifier](#grouping_identifier) -3. [Detail tokens](#detail_tokens) -4. [Web authorization](#web_authorization_token) - -#### Named groups - -To create a named group of form fields, the optional `section-*` token can be used. If present, this token must be the first token in the space-separated list of tokens. - -- `section-*` - - : Defines the name for a group of form controls. A token whose first eight characters are the string "section-", case-insensitive, followed by additional characters. All form controls that start with the same token belong to the named group. - -#### Grouping identifier - -An optional `shipping` or `billing` grouping identifier - -- `shipping` - - : The field identified by subsequent tokens is part of the shipping address or contact information -- `billing` - - : The field identified by subsequent tokens is part of the billing address or contact information - -#### Detail tokens - -Each space-separated detail token list includes either a recipient type with digital contact information, in that order, or a space-separated token list of other tokens. - -##### Recipient type - -The tokens that identify the type of recipient include: - -- `home` - - : The contact type identified by subsequent tokens is for contacting the recipient at their residence. -- `work` - - : The contact type identified by subsequent tokens is for contacting the recipient at their work. -- `mobile` - - : The contact type identified by subsequent tokens is for contacting the recipient regardless of location. -- `fax` - - : The recipient identified by subsequent tokens is for a fax machine. -- `page` - - : The recipient identified by subsequent tokens is for a pager or beeper. - -##### Digital contact tokens - -The token or group of tokens for telephone numbers or a number's component parts, phone extensions, email addresses, or instant messaging protocols. - -- `tel` - - - : A full telephone number, including the country code. If you need to break the phone number up into its components, you can use these values for those fields: - - `tel-country-code` - - : The country code, such as "1" for the United States, Canada, and other areas in North America and parts of the Caribbean. - - `tel-national` - - : The entire phone number without the country code component, including a country-internal prefix. For the phone number "1-855-555-6502", this field's value would be "855-555-6502". - - `tel-area-code` - - : The area code, with any country-internal prefix applied if appropriate. - - `tel-local` - - : The phone number without the country or area code. This can be split further into two parts, for phone numbers which have an exchange number and then a number within the exchange. For the phone number "555-6502", use `tel-local-prefix` for "555" and `tel-local-suffix` for "6502". - -- `tel-extension` - - : A telephone extension code within the phone number, such as a room or suite number in a hotel or an office extension in a company. -- `email` - - : An email address. -- `impp` - - : A URL for an instant messaging protocol endpoint, such as `xmpp:username@example.net`. - -##### Other tokens - -When the form field is not a phone number, email address, or instant messaging protocol, the space-separated list of tokens is not preceded by a contact type: - -- `name` - - - : The field expects the value to be a person's full name. Using `name` rather than breaking the name down into its components is generally preferred because it avoids dealing with the wide diversity of human names and how they are structured; however, you can use the following `autocomplete` values if you do need to break the name down into its components: - - - `honorific-prefix` - - : The prefix or title, such as "Mrs.", "Mr.", "Miss", "Ms.", "Dr.", or "Mlle.". - - `given-name` - - : The given (or "first") name. - - `additional-name` - - : The middle name. - - `family-name` - - : The family (or "last") name. - - `honorific-suffix` - - : The suffix, such as "Jr.", "B.Sc.", "PhD.", "MBASW", or "IV". - - `nickname` - - : A nickname or handle. - -- `username` - - : A username or account name. -- `new-password` - - : A new password. When creating a new account or changing passwords, this should be used for an "Enter your new password" or "Confirm new password" field, as opposed to a general "Enter your current password" field that might be present. This may be used by the browser both to avoid accidentally filling in an existing password and to offer assistance in creating a secure password. -- `current-password` - - : The user's current password. -- `one-time-code` - - : A one-time password (OTP) for verifying user identity that is used as an additional factor in a sign-in flow. - Most commonly this is a code received via some out-of-channel mechanism, such as SMS, email, or authenticator application. -- `organization-title` - - : A job title, or the title a person has within an organization, such as "Senior Technical Writer", "President", or "Assistant Troop Leader". -- `organization` - - : A company or organization name, such as "Acme Widget Company" or "Girl Scouts of America". -- `street-address` - - : A street address. This can be multiple lines of text, and should fully identify the location of the address within its second administrative level (typically a city or town), but should not include the city name, ZIP or postal code, or country name. - - `address-line1`, `address-line2`, `address-line3` - - : Each individual line of the street address. These should only be present if the `street-address` is not present. -- `address-level4` - - : The finest-grained [administrative level](#administrative_levels_in_addresses), in addresses which have four levels. -- `address-level3` - - : The third [administrative level](#administrative_levels_in_addresses), in addresses with at least three administrative levels. -- `address-level2` - - : The second [administrative level](#administrative_levels_in_addresses), in addresses with at least two of them. In countries with two administrative levels, this would typically be the city, town, village, or other locality in which the address is located. -- `address-level1` - - : The first [administrative level](#administrative_levels_in_addresses) in the address. This is typically the province in which the address is located. In the United States, this would be the state. In Switzerland, the canton. In the United Kingdom, the county. -- `country` - - : A country or territory code. -- `country-name` - - : A country or territory name. -- `postal-code` - - - : A postal code (in the United States, this is the ZIP code). - -- `cc-name` - - : The full name as printed on or associated with a payment instrument such as a credit card. Using a full name field is preferred, typically, over breaking the name into pieces. - - `cc-given-name` - - : A given (first) name as given on a payment instrument like a credit card. - - `cc-additional-name` - - : A middle name as given on a payment instrument or credit card. - - `cc-family-name` - - : A family name, as given on a credit card. -- `cc-number` - - : A credit card number or other number identifying a payment method, such as an account number. -- `cc-exp` - - : A payment method expiration date, typically in the form "MM/YY" or "MM/YYYY". - - `cc-exp-month` - - : The month in which the payment method expires. - - `cc-exp-year` - - : The year in which the payment method expires. -- `cc-csc` - - : The security code for the payment instrument; on credit cards, this is the 3-digit verification number on the back of the card. -- `cc-type` - - : The type of payment instrument (such as "Visa" or "Master Card"). -- `transaction-currency` - - : The currency in which the transaction is to take place. -- `transaction-amount` - - : The amount, given in the currency specified by `transaction-currency`, of the transaction, for a payment form. -- `language` - - : A preferred language, given as a valid [BCP 47 language tag](https://en.wikipedia.org/wiki/IETF_language_tag). -- `bday` - - : A birth date, as a full date. - - `bday-day` - - : The day of the month of a birth date. - - `bday-month` - - : The month of the year of a birth date. - - `bday-year` - - : The year of a birth date. -- `sex` - - : A gender identity (such as "Female", "Fa'afafine", "Hijra", "Male", "Nonbinary"), as freeform text without newlines. -- `url` - - : A URL, such as a home page or company website address as appropriate given the context of the other fields in the form. -- `photo` - - : The URL of an image representing the person, company, or contact information given in the other fields in the form. - -#### Web authorization token - -With {{htmlelement("input")}} and {{htmlelement("textarea")}}, the `webauthn` token can be included last to indicate the user agent should show public key credentials when the user is interacting with the control. - -- `webauthn` {{experimental_inline}} - - : Passkeys generated by the [Web Authentication API](/en-US/docs/Web/API/Web_Authentication_API), as requested by a conditional {{domxref("CredentialsContainer.get()", "navigator.credentials.get()")}} call (i.e., one that includes `mediation: 'conditional'`). If included, this is the last token in the space-separated token list. See [Sign in with a passkey through form autofill](https://web.dev/articles/passkey-form-autofill) for more details. - -## Examples - -```html -<div> - <label for="cc-number">Enter your credit card number</label> - <input name="cc-number" id="cc-number" autocomplete="off" /> -</div> -``` - -### Administrative levels in addresses - -The four administrative level fields (`address-level1` through `address-level4`) describe the address in terms of increasing levels of precision within the country in which the address is located. Each country has its own system of administrative levels, and may arrange the levels in different orders when addresses are written. - -`address-level1` always represents the broadest administrative division; it is the least-specific portion of the address short of the country name. - -### Form layout flexibility - -Given that different countries write their address in different ways, with each field in different places within the address, and even different sets and numbers of fields entirely, it can be helpful if, when possible, your site is able to switch to the layout expected by your users when presenting an address entry form, given the country the address is located within. - -### Variations - -The way each administrative level is used will vary from country to country. Below are some examples; this is not meant to be an exhaustive list. - -#### United States - -A typical home address within the United States looks like this: - -432 Anywhere St -Exampleville CA 95555 - -In the United States, the least-specific portion of the address is the state, in this case "CA" (the official US Postal Service shorthand for "California"). Thus `address-level1` is the state, or "CA" in this case. - -The second-least specific portion of the address is the city or town name, so `address-level2` is "Exampleville" in this example address. - -United States addresses do not use levels 3 and up. - -#### United Kingdom - -Address input forms in the UK should contain one or two address levels and one, two or three address lines, depending on the address. A complete address would look like so: - -103 Frogmarch Street -Upper-Wapping -Winchelsea -Whereshire -TN99 8ZZ - -The address levels are: - -- `address-level1`: The county — "Whereshire" in this case. -- `address-level2`: The post town — "Winchelsea" in this case. -- `address-line2`: The locality — "Upper-Wapping" in this case. -- `address-line1`: The house/street particulars — "103 Frogmarch Street". - -The postcode is separate. Note that you can actually use just the postcode and `address-line1` to successfully deliver mail in the UK, so they should be the only mandatory items, but usually people tend to provide more details. - -#### China - -China can use as many as three administrative levels: the province, the city, and the district. - -The 6 digit postal code is not always needed but when supplied it is placed separately with a label for clarity. For example: - -北京市东城区建国门北大街 8 号华润大厦 17 层 1708 单元 -邮编:100005 - -#### Japan - -An address in Japan is typically **written in one line**, in an order from the least-specific to more-specific portions (in **reverse order to the United States**). There are two or three administrative levels in an address. Additional line can be used to show building names and room numbers. The postal code is separate. For example: - -〒 381-0000 -長野県長野市某町 123 - -"〒" and following seven digits shows the postal code. - -`address-level1` is used for prefectures or the Tokyo Metropolis; "長野県" (Nagano Prefecture) is in this case. `address-level2` is typically used for cities, counties, towns and villages; "長野市" (Nagano City) in this case. "某町 123" is `address-line1` which consists of an area name and a lot number. - -## Specifications - -{{Specifications}} - -## Browser compatibility - -{{Compat}} - -## See also - -- The {{htmlelement("input")}} element -- The {{htmlelement("select")}} element -- The {{htmlelement("textarea")}} element -- The {{htmlelement("form")}} element -- [HTML forms](/en-US/docs/Learn_web_development/Extensions/Forms) -- All [global attributes](/en-US/docs/Web/HTML/Global_attributes) diff --git a/files/en-us/web/html/attributes/capture/index.md b/files/en-us/web/html/attributes/capture/index.md deleted file mode 100644 index 1a989b699bf9020..000000000000000 --- a/files/en-us/web/html/attributes/capture/index.md +++ /dev/null @@ -1,88 +0,0 @@ ---- -title: "HTML attribute: capture" -short-title: capture -slug: Web/HTML/Attributes/capture -page-type: html-attribute -browser-compat: html.elements.input.capture ---- - -{{HTMLSidebar}} - -The **`capture`** attribute specifies that, optionally, a new file should be captured, and which device should be used to capture that new media of a type defined by the [`accept`](/en-US/docs/Web/HTML/Attributes/accept) attribute. - -Values include `user` and `environment`. The capture attribute is supported on the {{HTMLElement("input/file", "file")}} input type. - -The `capture` attribute takes as its value a string that specifies which camera to use for capture of image or video data, if the [accept](/en-US/docs/Web/HTML/Attributes/accept) attribute indicates that the input should be of one of those types. - -| Value | Description | -| ------------- | ---------------------------------------------------------- | -| `user` | The user-facing camera and/or microphone should be used. | -| `environment` | The outward-facing camera and/or microphone should be used | - -> [!NOTE] -> Capture was previously a Boolean attribute which, if present, requested that the device's media capture device(s) such as camera or microphone be used instead of requesting a file input. - -{{InteractiveExample("HTML Demo: capture", "tabbed-standard")}} - -```html interactive-example -<label for="selfie">Take a picture of your face:</label> - -<input type="file" id="selfie" name="selfie" accept="image/*" capture="user" /> - -<label for="picture">Take a picture using back facing camera:</label> - -<input - type="file" - id="picture" - name="picture" - accept="image/*" - capture="environment" /> -``` - -```css interactive-example -label { - display: block; - margin-top: 1rem; -} - -input { - margin-bottom: 1rem; -} -``` - -## Examples - -When set on a file input type, operating systems with microphones and cameras will display a user interface allowing the selection from an existing file or the creating of a new one. - -```html -<p> - <label for="soundFile">What does your voice sound like?:</label> - <input type="file" id="soundFile" capture="user" accept="audio/*" /> -</p> -<p> - <label for="videoFile">Upload a video:</label> - <input type="file" id="videoFile" capture="environment" accept="video/*" /> -</p> -<p> - <label for="imageFile">Upload a photo of yourself:</label> - <input type="file" id="imageFile" capture="user" accept="image/*" /> -</p> -``` - -{{EmbedLiveSample('Examples', '100%', 200)}} - -Note these work better on mobile devices; if your device is a desktop computer, you'll likely get a typical file picker. - -## Specifications - -{{Specifications}} - -## Browser compatibility - -{{Compat}} - -## See also - -- [Using files from web applications](/en-US/docs/Web/API/File_API/Using_files_from_web_applications) -- [File API](/en-US/docs/Web/API/File) -- {{domxref('HTMLInputElement.files')}} diff --git a/files/en-us/web/html/attributes/crossorigin/index.md b/files/en-us/web/html/attributes/crossorigin/index.md deleted file mode 100644 index be4befcdb19a314..000000000000000 --- a/files/en-us/web/html/attributes/crossorigin/index.md +++ /dev/null @@ -1,95 +0,0 @@ ---- -title: "HTML attribute: crossorigin" -short-title: crossorigin -slug: Web/HTML/Attributes/crossorigin -page-type: html-attribute -browser-compat: - - html.elements.audio.crossorigin - - html.elements.img.crossorigin - - html.elements.link.crossorigin - - html.elements.script.crossorigin - - html.elements.video.crossorigin -spec-urls: https://html.spec.whatwg.org/multipage/urls-and-fetching.html#cors-settings-attributes ---- - -{{HTMLSidebar}} - -The **`crossorigin`** attribute, valid on the {{HTMLElement("audio")}}, {{HTMLElement("img")}}, {{HTMLElement("link")}}, {{HTMLElement("script")}}, and {{HTMLElement("video")}} elements, provides support for [CORS](/en-US/docs/Web/HTTP/CORS), defining how the element handles cross-origin requests, thereby enabling the configuration of the CORS requests for the element's fetched data. Depending on the element, the attribute can be a CORS settings attribute. - -The `crossorigin` content attribute on media elements is a CORS settings attribute. - -These attributes are [enumerated](/en-US/docs/Glossary/Enumerated), and have the following possible values: - -- `anonymous` - - : Request uses CORS headers and credentials flag is set to `'same-origin'`. There is no exchange of **user credentials** via cookies, client-side TLS certificates or HTTP authentication, unless destination is the same origin. -- `use-credentials` - - : Request uses CORS headers, credentials flag is set to `'include'` and **user credentials** are always included. -- `""` - - : Setting the attribute name to an empty value, like `crossorigin` or `crossorigin=""`, is the same as `anonymous`. - -An invalid keyword and an empty string will be handled as the `anonymous` keyword. - -By default (that is, when the attribute is not specified), CORS is not used at all. The user agent will not ask for permission for full access to the resource and in the case of a cross-origin request, certain limitations will be applied based on the type of element concerned: - -<table class="no-markdown"> - <tbody> - <tr> - <td class="header">Element</td> - <td class="header">Restrictions</td> - </tr> - <tr> - <td><code>img</code>, <code>audio</code>, <code>video</code></td> - <td> - When resource is placed in {{HTMLElement("canvas")}}, element is marked as <a href="/en-US/docs/Web/HTML/CORS_enabled_image#security_and_tainted_canvases"><em>tainted</em></a>. - </td> - </tr> - <tr> - <td><code>script</code></td> - <td> - Access to error logging via {{domxref('Window.error_event', 'window.onerror')}} will be limited. - </td> - </tr> - <tr> - <td><code>link</code></td> - <td> - Request with no appropriate <code>crossorigin</code> header may be discarded. - </td> - </tr> - </tbody> -</table> - -> [!NOTE] -> The `crossorigin` attribute is not supported for [`rel="icon"`](/en-US/docs/Web/HTML/Attributes/rel#icon) in Chromium-based browsers. See the [open Chromium issue](https://crbug.com/1121645). - -### Example: `crossorigin` with the `<script>` element - -You can use the following {{HTMLElement("script")}} element to tell a browser to execute the `https://example.com/example-framework.js` script without sending user-credentials. - -```html -<script - src="https://example.com/example-framework.js" - crossorigin="anonymous"></script> -``` - -### Example: Web manifest with credentials - -The `use-credentials` value must be used when fetching a [manifest](/en-US/docs/Web/Progressive_web_apps/Manifest) that requires credentials, even if the file is from the same origin. - -```html -<link rel="manifest" href="/app.webmanifest" crossorigin="use-credentials" /> -``` - -## Specifications - -{{Specifications}} - -## Browser compatibility - -{{Compat}} - -## See also - -- [Cross-Origin Resource Sharing (CORS)](/en-US/docs/Web/HTTP/CORS) -- [HTML attribute: `rel`](/en-US/docs/Web/HTML/Attributes/rel) - -{{QuickLinksWithSubpages("/en-US/docs/Web/HTML/")}} diff --git a/files/en-us/web/html/attributes/dirname/index.md b/files/en-us/web/html/attributes/dirname/index.md deleted file mode 100644 index 0c657c9e6b4b1a4..000000000000000 --- a/files/en-us/web/html/attributes/dirname/index.md +++ /dev/null @@ -1,110 +0,0 @@ ---- -title: "HTML attribute: dirname" -short-title: dirname -slug: Web/HTML/Attributes/dirname -page-type: html-attribute -browser-compat: - - html.elements.textarea.dirname - - html.elements.input.dirname ---- - -{{HTMLSidebar}} - -The **`dirname`** attribute can be used on the {{htmlelement("textarea")}} element and several {{htmlelement("input")}} types and describes the directionality of the element's text content during form submission. -The browser uses this attribute's value to determine whether text the user has entered is left-to-right or right-to-left oriented. -When used, the element's text directionality value is included in form submission data along with the `dirname` attribute's value as the name of the field. - -## Usage notes - -The `dirname` attribute can be used on any {{htmlelement("textarea")}} element, or any {{htmlelement("input")}} element with {{htmlelement("input/hidden", "hidden")}}, {{htmlelement("input/text", "text")}}, {{htmlelement("input/search", "search")}}, {{htmlelement("input/tel", "tel")}}, {{htmlelement("input/url", "url")}}, {{htmlelement("input/email", "email")}}, {{htmlelement("input/password", "password")}}, {{htmlelement("input/submit", "submit")}}, {{htmlelement("input/reset", "reset")}} or {{htmlelement("input/button", "button")}} type. - -The format of the submitted data is `{dirname_value}={direction}` where `{dirname_value}` is the value of the `dirname` attribute and `{direction}` is the directionality of the text. -For example, if the user enters "Hello" in an element with the attributes `name="comment"` and `dirname="comment-direction"`, the URL-encoded form submission data for `GET` requests will be `comment=Hello&comment-direction=ltr`. -The directionality is one of the following: - -- `rtl` - - : The text entered by the user is in a right-to-left writing direction. -- `ltr` - - : The text entered by the user is in a left-to-right writing direction. - -If no text directionality is specified, the user agent will use the directionality of the parent element containing the form, and if that is not specified, the default directionality of the user agent. - -## Examples - -### Textarea element directionality - -In this example, the `dir="auto"` attribute on the textarea element allows the text directionality to be determined automatically based on the text entered by the user: - -```html -<form method="get" action="https://www.example.com/submit"> - <textarea name="comment" dir="auto" dirname="comment-direction">سيب</textarea> - <button type="submit">Send my greetings</button> -</form> -``` - -When the user submits the form, the user agent includes two fields, one called `comment` with the value "سيب", and one called `comment-direction` with the value "rtl". -The URL-encoded submission body looks like this: - -```url -https://www.example.com/submit?comment=%D8%B3%D9%8A%D8%A8&comment-direction=rtl -``` - -### Input element directionality - -In this example, the `dir="auto"` attribute on the input element allows the text directionality to be determined automatically based on the text entered by the user: - -```html -<form method="get" action="https://www.example.com/submit"> - <input - type="text" - name="comment-input" - dir="auto" - dirname="comment-direction" - value="Hello" /> - <button type="submit">Send my greetings</button> -</form> -``` - -When the user submits the form, the user agent includes two fields, one called `comment-input` with the value "Hello", and one called `comment-direction` with the value "ltr": - -```url -https://www.example.com/submit?comment-input=Hello&comment-direction=ltr -``` - -### Inheriting directionality - -The following `<input>` and `<textarea>` elements do not have a `dir` attribute, so they inherit the explicit directionality of their parent element, which is `rtl`: - -```html -<div dir="rtl"> - <form method="get" action="https://www.example.com/submit"> - <input - type="text" - name="user" - dirname="user-direction" - value="LTR Username" /> - <textarea name="comment" dirname="comment-direction">LTR Comment</textarea> - <button type="submit">Post Comment</button> - </form> -</div> -``` - -The URL-encoded submission body looks like this: - -```url -https://www.example.com/submit?user=LTR+Username&user-direction=rtl&comment=LTR+Comment&comment-direction=rtl -``` - -## Specifications - -{{Specifications}} - -## Browser compatibility - -{{Compat}} - -## See also - -- [`dir` attribute](/en-US/docs/Web/HTML/Global_attributes/dir) -- {{htmlelement("input")}} -- {{htmlelement("textarea")}} diff --git a/files/en-us/web/html/attributes/disabled/index.md b/files/en-us/web/html/attributes/disabled/index.md deleted file mode 100644 index 5dfe1a6b9be8eee..000000000000000 --- a/files/en-us/web/html/attributes/disabled/index.md +++ /dev/null @@ -1,167 +0,0 @@ ---- -title: "HTML attribute: disabled" -short-title: disabled -slug: Web/HTML/Attributes/disabled -page-type: html-attribute -browser-compat: - - html.elements.button.disabled - - html.elements.fieldset.disabled - - html.elements.input.disabled - - html.elements.optgroup.disabled - - html.elements.option.disabled - - html.elements.select.disabled - - html.elements.textarea.disabled ---- - -{{HTMLSidebar}} - -The Boolean **`disabled`** attribute, when present, makes the element not mutable, focusable, or even submitted with the form. The user can neither edit nor focus on the control, nor its form control descendants. - -{{InteractiveExample("HTML Demo: disabled", "tabbed-standard")}} - -```html interactive-example -<form> - <label for="name">Name:</label> - <input id="name" name="name" type="text" /> - - <label for="emp">Employed:</label> - <select id="emp" name="emp" disabled> - <option>No</option> - <option>Yes</option> - </select> - - <label for="empDate">Employment Date:</label> - <input id="empDate" name="empDate" type="date" disabled /> - - <label for="resume">Resume:</label> - <input id="resume" name="resume" type="file" /> -</form> -``` - -```css interactive-example -label { - display: block; - margin-top: 1em; -} - -*:disabled { - background-color: dimgrey; - color: linen; - opacity: 1; -} -``` - -## Overview - -If the `disabled` attribute is specified on a form control, the element and its form control descendants do not participate in constraint validation. Often browsers grey out such controls and it won't receive any browsing events, like mouse clicks or focus-related ones. - -The `disabled` attribute is supported by {{ HTMLElement("button") }}, {{ HTMLElement("fieldset") }}, {{ HTMLElement("optgroup") }}, {{ HTMLElement("option") }}, {{ HTMLElement("select") }}, {{ HTMLElement("textarea") }} and {{ HTMLElement("input")}}. - -This Boolean disabled attribute indicates that the user cannot interact with the control or its descendant controls. If this attribute is not specified, the control inherits its setting from the containing element, for example `fieldset`; if there is no containing element with the `disabled` attribute set, and the control itself does not have the attribute, then the control is enabled. If declared on an {{ HTMLElement("optgroup") }}, the select is still interactive (unless otherwise disabled), but none of the items in the option group are selectable. - -> [!NOTE] -> If a {{ HTMLElement("fieldset") }} is disabled, the descendant form controls are all disabled, with the exception of form controls within the {{ HTMLElement("legend") }}. - -When a supporting element has the `disabled` attribute applied, the {{cssxref(":disabled")}} pseudo-class also applies to it. Conversely, elements that support the `disabled` attribute but don't have the attribute set match the {{cssxref(":enabled")}} pseudo-class. - -This Boolean attribute prevents the user from interacting with the button. If this attribute isn't set, the button can still be disabled from a containing element, for example {{htmlelement('fieldset')}}; if there is no containing element with the `disabled` attribute set, then the button is enabled. - -Firefox will, unlike other browsers, persist the dynamic disabled state of a {{htmlelement('button')}} across page loads. Use the [`autocomplete`](/en-US/docs/Web/HTML/Attributes/autocomplete) attribute to control this feature. - -### Attribute interactions - -The difference between `disabled` and [`readonly`](/en-US/docs/Web/HTML/Attributes/readonly) is that read-only controls can still function and are still focusable, whereas disabled controls can not receive focus and are not submitted with the form and generally do not function as controls until they are enabled. - -Because a disabled field cannot have its value changed, [`required`](/en-US/docs/Web/HTML/Attributes/required) does not have any effect on inputs with the `disabled` attribute also specified. Additionally, since the elements become immutable, most other attributes, such as [`pattern`](/en-US/docs/Web/HTML/Attributes/pattern), have no effect, until the control is enabled. - -> [!NOTE] -> The `required` attribute is not permitted on inputs with the `disabled` attribute specified. - -### Usability - -Browsers display disabled form controls greyed as disabled form controls are immutable, won't receive focus or any browsing events, like mouse clicks or focus-related ones, and aren't submitted with the form. - -If present on a supporting elements, the {{cssxref(':disabled')}} pseudo class will match. If the attribute is not included, the {{cssxref(':enabled')}} pseudo class will match. If the element doesn't support the disabled attribute, the attribute will have no effect, including not leading to being matched by the `:disabled` and `:enabled` pseudo classes. - -### Constraint validation - -If the element is `disabled`, then the element's value can not receive focus and cannot be updated by the user, and does not participate in constraint validation. - -## Examples - -When form controls are disabled, many browsers will display them in a lighter, greyed-out color by default. Here are examples of a disabled checkbox, radio button, {{ HTMLElement("option") }} and {{ HTMLElement("optgroup") }}, as well as some form controls that are disabled via the disabled attribute set on the ancestor `{{ HTMLElement("fieldset")}}` element. The {{ HTMLElement("option") }}s are disabled, but the {{ HTMLElement("select") }} itself is not. We could have disable the entire {{ HTMLElement("select") }} by adding the attribute to that element rather than its descendants. - -```html -<fieldset> - <legend>Checkboxes</legend> - <p> - <label> - <input type="checkbox" name="ch-box" value="regular" /> Regular - </label> - </p> - <p> - <label> - <input type="checkbox" name="ch-box" value="disabled" disabled /> disabled - </label> - </p> -</fieldset> - -<fieldset> - <legend>Radio buttons</legend> - <p> - <label> <input type="radio" name="radio" value="regular" /> Regular </label> - </p> - <p> - <label> - <input type="radio" name="radio" value="disabled" disabled /> disabled - </label> - </p> -</fieldset> - -<p> - <label - >Select an option: - <select> - <optgroup label="Group 1"> - <option>Option 1.1</option> - </optgroup> - <optgroup label="Group 2"> - <option>Option 2.1</option> - <option disabled>Option 2.2</option> - <option>Option 2.3</option> - </optgroup> - <optgroup label="Group 3" disabled> - <option>Disabled 3.1</option> - <option>Disabled 3.2</option> - <option>Disabled 3.3</option> - </optgroup> - </select> - </label> -</p> - -<fieldset disabled> - <legend>Disabled fieldset</legend> - <p> - <label> - Name: <input type="radio" name="radio" value="regular" /> Regular - </label> - </p> - <p> - <label>Number: <input type="number" /></label> - </p> -</fieldset> -``` - -{{EmbedLiveSample('Examples', 500, 450)}} - -## Specifications - -{{Specifications}} - -## Browser compatibility - -{{Compat}} - -## See also - -- {{cssxref(':disabled')}} and {{cssxref(':enabled')}} diff --git a/files/en-us/web/html/attributes/elementtiming/index.md b/files/en-us/web/html/attributes/elementtiming/index.md deleted file mode 100644 index 59780c194b7d8b2..000000000000000 --- a/files/en-us/web/html/attributes/elementtiming/index.md +++ /dev/null @@ -1,45 +0,0 @@ ---- -title: "HTML attribute: elementtiming" -short-title: elementtiming -slug: Web/HTML/Attributes/elementtiming -page-type: html-attribute ---- - -{{HTMLSidebar}} - -The **`elementtiming`** attribute is used to indicate that an element is flagged for tracking by {{domxref("PerformanceObserver")}} objects using the `"element"` type. For more details, see the {{domxref("PerformanceElementTiming")}} interface. - -This attribute may be applied to {{htmlelement("img")}}, {{SVGElement("image")}} elements inside an {{SVGElement("svg")}}, poster images of {{htmlelement("video")}} elements, elements which have a {{cssxref("background-image")}}, and elements containing text nodes, such as a {{htmlelement("p")}}. - -In the DOM, this attribute is reflected as {{domxref("Element.elementTiming")}}. - -## Usage - -The value given for `elementtiming` becomes an identifier for the observed element. - -```html -<img alt="alt" src="img.jpg" elementtiming="label for element" /> -``` - -Good contenders for elements you might want to observe are: - -- The main image for an article. -- A blog post title -- Images in a carousel for a shopping site. -- The poster image for the main video on a page. - -## Examples - -```html -<img - alt="Alt for a main blog post image" - src="my-massive-image.jpg" - elementtiming="Main image" /> - -<p elementtiming="important-text">Some very important information.</p> -``` - -## See also - -- {{domxref("PerformanceElementTiming")}} -- {{domxref("Element.elementTiming")}} diff --git a/files/en-us/web/html/attributes/for/index.md b/files/en-us/web/html/attributes/for/index.md deleted file mode 100644 index 9695d700240935f..000000000000000 --- a/files/en-us/web/html/attributes/for/index.md +++ /dev/null @@ -1,92 +0,0 @@ ---- -title: "HTML attribute: for" -short-title: for -slug: Web/HTML/Attributes/for -page-type: html-attribute -browser-compat: - - html.elements.label.for - - html.elements.output.for ---- - -{{HTMLSidebar}} - -The **`for`** attribute is an allowed attribute for {{htmlelement("label")}} and {{htmlelement("output")}}. When used on a `<label>` element it indicates the form element that this label describes. When used on an `<output>` element it allows for an explicit relationship between the elements that represent values which are used in the output. - -{{InteractiveExample("HTML Demo: for", "tabbed-shorter")}} - -```html interactive-example -<p> - <label>First Name (no "for" attribute):</label> - <input id="first" type="text" value="Jane" /> -</p> -<p> - <label for="last">Last Name (w/ "for" attribute):</label> - <input id="last" type="text" value="Doe" /> -</p> -<p id="result"> - <strong id="result-label">Full Name:</strong> - <output for="first last" aria-labelledby="result-label" id="output"></output> -</p> -``` - -```css interactive-example -label[for="paragraph"] { - color: rebeccapurple; -} - -#result { - text-align: center; -} - -#result-label { - font-size: 16pt; -} - -#result-label, -#output { - display: block; -} -``` - -```js interactive-example -const firstNameEl = document.getElementById("first"); -const lastNameEl = document.getElementById("last"); -const outputEl = document.getElementById("output"); - -function updateOutput() { - const value = `${firstNameEl.value} ${lastNameEl.value}`; - outputEl.innerText = value; -} - -updateOutput(); -firstNameEl.addEventListener("input", updateOutput); -lastNameEl.addEventListener("input", updateOutput); -``` - -## Usage - -When used as an attribute of `<label>`, the `for` attribute has a value which is the `id` of the form element it relates to. - -```html -<label for="username">Your name</label> <input type="text" id="username" /> -``` - -When used as an attribute of `<output>`, the `for` attribute has a value which is a space separated list of the `id` values of the elements which are used to create the output. - -```html -<input type="range" id="b" name="b" value="50" /> + -<input type="number" id="a" name="a" value="10" /> = -<output name="result" for="a b">60</output> -``` - -## Examples - -See examples of usage on the element pages for {{htmlelement("label")}} and {{htmlelement("output")}}. - -## Specifications - -{{Specifications}} - -## Browser compatibility - -{{Compat}} diff --git a/files/en-us/web/html/attributes/index.md b/files/en-us/web/html/attributes/index.md deleted file mode 100644 index b9331235d3b71ef..000000000000000 --- a/files/en-us/web/html/attributes/index.md +++ /dev/null @@ -1,1430 +0,0 @@ ---- -title: HTML attribute reference -short-title: Attributes -slug: Web/HTML/Attributes -page-type: landing-page ---- - -{{HTMLSidebar("Attributes")}} - -Elements in HTML have **attributes**; these are additional values that configure the elements or adjust their behavior in various ways to meet the criteria the users want. - -## Attribute list - -<table class="standard-table"> - <thead> - <tr> - <th>Attribute Name</th> - <th>Elements</th> - <th>Description</th> - </tr> - </thead> - <tbody> - <tr> - <td> - <code><a href="/en-US/docs/Web/HTML/Attributes/accept">accept</a></code> - </td> - <td> - {{ HTMLElement("form") }}, {{ HTMLElement("input") }} - </td> - <td>List of types the server accepts, typically a file type.</td> - </tr> - <tr> - <td> - <code><a href="/en-US/docs/Web/HTML/Element/form#accept-charset">accept-charset</a></code> - </td> - <td>{{ HTMLElement("form") }}</td> - <td>The character set, which if provided must be <code>"UTF-8"</code>.</td> - </tr> - <tr> - <td> - <code><a href="/en-US/docs/Web/HTML/Global_attributes/accesskey">accesskey</a></code> - </td> - <td> - <a href="/en-US/docs/Web/HTML/Global_attributes">Global attribute</a> - </td> - <td>Keyboard shortcut to activate or add focus to the element.</td> - </tr> - <tr> - <td> - <code><a href="/en-US/docs/Web/HTML/Element/form#action">action</a></code> - </td> - <td>{{ HTMLElement("form") }}</td> - <td> - The URI of a program that processes the information submitted via the - form. - </td> - </tr> - <tr> - <td> - <code>align</code> {{deprecated_inline}} - </td> - <td> - {{ HTMLElement("caption") }}, {{ HTMLElement("col") }}, - {{ HTMLElement("colgroup") }}, - {{ HTMLElement("hr") }}, {{ HTMLElement("iframe") }}, - {{ HTMLElement("img") }}, {{ HTMLElement("table") }}, - {{ HTMLElement("tbody") }}, {{ HTMLElement("td") }}, - {{ HTMLElement("tfoot") }}, {{ HTMLElement("th") }}, - {{ HTMLElement("thead") }}, {{ HTMLElement("tr") }} - </td> - <td>Specifies the horizontal alignment of the element.</td> - </tr> - <tr> - <td> - <code><a href="/en-US/docs/Web/HTML/Element/iframe#allow">allow</a></code> - </td> - <td>{{ HTMLElement("iframe") }}</td> - <td>Specifies a feature-policy for the iframe.</td> - </tr> - <tr> - <td> - <code><a href="/en-US/docs/Web/HTML/Attributes/alt">alt</a></code> - </td> - <td> - {{ HTMLElement("area") }}, - {{ HTMLElement("img") }}, {{ HTMLElement("input") }} - </td> - <td>Alternative text in case an image can't be displayed.</td> - </tr> - <tr> - <td> - <code><a href="/en-US/docs/Web/HTML/Element/link#as">as</a></code> - </td> - <td> - {{ HTMLElement("link") }} - </td> - <td>Specifies the type of content being loaded by the link.</td> - </tr> - <tr> - <td> - <code><a href="/en-US/docs/Web/HTML/Element/script#async">async</a></code> - </td> - <td>{{ HTMLElement("script") }}</td> - <td>Executes the script asynchronously.</td> - </tr> - <tr> - <td> - <code><a href="/en-US/docs/Web/HTML/Global_attributes/autocapitalize">autocapitalize</a></code> - </td> - <td> - <a href="/en-US/docs/Web/HTML/Global_attributes">Global attribute</a> - </td> - <td> - Sets whether input is automatically capitalized when entered by user - </td> - </tr> - <tr> - <td> - <code><a href="/en-US/docs/Web/HTML/Attributes/autocomplete">autocomplete</a></code> - </td> - <td> - {{ HTMLElement("form") }}, {{ HTMLElement("input") }}, - {{ HTMLElement("select") }}, - {{ HTMLElement("textarea") }} - </td> - <td> - Indicates whether controls in this form can by default have their values - automatically completed by the browser. - </td> - </tr> - <tr> - <td> - <code><a href="/en-US/docs/Web/HTML/Attributes/autoplay">autoplay</a></code> - </td> - <td> - {{ HTMLElement("audio") }}, - {{ HTMLElement("video") }} - </td> - <td>The audio or video should play as soon as possible.</td> - </tr> - <tr> - <td><code>background</code></td> - <td> - {{ HTMLElement("body") }}, {{ HTMLElement("table") }}, - {{ HTMLElement("td") }}, {{ HTMLElement("th") }} - </td> - <td> - Specifies the URL of an image file. - <div class="note notecard"> - <p> - <strong>Note:</strong> Although browsers and email clients may still - support this attribute, it is obsolete. Use CSS - {{ Cssxref("background-image") }} instead. - </p> - </div> - </td> - </tr> - <tr> - <td><code>bgcolor</code></td> - <td> - {{ HTMLElement("body") }}, {{ HTMLElement("col") }}, - {{ HTMLElement("colgroup") }}, - {{ HTMLElement("marquee") }}, - {{ HTMLElement("table") }}, - {{ HTMLElement("tbody") }}, - {{ HTMLElement("tfoot") }}, {{ HTMLElement("td") }}, - {{ HTMLElement("th") }}, {{ HTMLElement("tr") }} - </td> - <td> - <p>Background color of the element.</p> - <div class="note notecard"> - <p> - <strong>Note:</strong> This is a legacy attribute. Please use the - CSS {{ Cssxref("background-color") }} property instead. - </p> - </div> - </td> - </tr> - <tr> - <td><code>border</code></td> - <td> - {{ HTMLElement("img") }}, {{ HTMLElement("object") }}, - {{ HTMLElement("table") }} - </td> - <td> - <p>The border width.</p> - <div class="note notecard"> - <p> - <strong>Note:</strong> This is a legacy attribute. Please use the - CSS {{ Cssxref("border") }} property instead. - </p> - </div> - </td> - </tr> - <tr> - <td> - <code><a href="/en-US/docs/Web/HTML/Attributes/capture">capture</a></code> - </td> - <td>{{ HTMLElement("input") }}</td> - <td> - From the <a href="https://w3c.github.io/html-media-capture/#the-capture-attribute">Media Capture specification</a>, - specifies a new file can be captured. - </td> - </tr> - <tr> - <td> - <code><a href="/en-US/docs/Web/HTML/Element/meta#charset">charset</a></code> - </td> - <td> - {{ HTMLElement("meta") }} - </td> - <td>Declares the character encoding of the page or script.</td> - </tr> - <tr> - <td> - <code><a href="/en-US/docs/Web/HTML/Element/input#checked">checked</a></code> - </td> - <td> - {{ HTMLElement("input") }} - </td> - <td>Indicates whether the element should be checked on page load.</td> - </tr> - <tr> - <td> - <code><a href="/en-US/docs/Web/HTML/Attributes/cite">cite</a></code> - </td> - <td> - {{ HTMLElement("blockquote") }}, - {{ HTMLElement("del") }}, {{ HTMLElement("ins") }}, - {{ HTMLElement("q") }} - </td> - <td>Contains a URI which points to the source of the quote or change.</td> - </tr> - <tr> - <td> - <code><a href="/en-US/docs/Web/HTML/Global_attributes/class">class</a></code> - </td> - <td> - <a href="/en-US/docs/Web/HTML/Global_attributes">Global attribute</a> - </td> - <td>Often used with CSS to style elements with common properties.</td> - </tr> - <tr> - <td><code>color</code></td> - <td> - {{ HTMLElement("font") }}, {{ HTMLElement("hr") }} - </td> - <td> - <p> - This attribute sets the text color using either a named color or a - color specified in the hexadecimal #RRGGBB format. - </p> - <div class="note notecard"> - <p> - <strong>Note:</strong> This is a legacy attribute. Please use the - CSS {{ Cssxref("color") }} property instead. - </p> - </div> - </td> - </tr> - <tr> - <td> - <code><a href="/en-US/docs/Web/HTML/Element/textarea#cols">cols</a></code> - </td> - <td>{{ HTMLElement("textarea") }}</td> - <td>Defines the number of columns in a textarea.</td> - </tr> - <tr> - <td> - <code><a href="/en-US/docs/Web/HTML/Attributes/colspan">colspan</a></code> - </td> - <td> - {{ HTMLElement("td") }}, {{ HTMLElement("th") }} - </td> - <td> - The colspan attribute defines the number of columns a cell should span. - </td> - </tr> - <tr> - <td> - <code><a href="/en-US/docs/Web/HTML/Element/meta#content">content</a></code> - </td> - <td>{{ HTMLElement("meta") }}</td> - <td> - A value associated with <code>http-equiv</code> or - <code>name</code> depending on the context. - </td> - </tr> - <tr> - <td> - <code><a href="/en-US/docs/Web/HTML/Global_attributes/contenteditable">contenteditable</a></code> - </td> - <td> - <a href="/en-US/docs/Web/HTML/Global_attributes">Global attribute</a> - </td> - <td>Indicates whether the element's content is editable.</td> - </tr> - <tr> - <td> - <code><a href="/en-US/docs/Web/HTML/Attributes/controls">controls</a></code> - </td> - <td> - {{ HTMLElement("audio") }}, - {{ HTMLElement("video") }} - </td> - <td> - Indicates whether the browser should show playback controls to the user. - </td> - </tr> - <tr> - <td> - <code><a href="/en-US/docs/Web/HTML/Element/area#coords">coords</a></code> - </td> - <td>{{ HTMLElement("area") }}</td> - <td> - A set of values specifying the coordinates of the hot-spot region. - </td> - </tr> - <tr> - <td> - <code><a href="/en-US/docs/Web/HTML/Attributes/crossorigin">crossorigin</a></code> - </td> - <td> - {{ HTMLElement("audio") }}, {{ HTMLElement("img") }}, - {{ HTMLElement("link") }}, {{ HTMLElement("script") }}, - {{ HTMLElement("video") }} - </td> - <td>How the element handles cross-origin requests</td> - </tr> - <tr> - <td> - <code><a href="/en-US/docs/Web/API/HTMLIFrameElement/csp">csp</a></code> - {{experimental_inline}} - </td> - <td>{{ HTMLElement("iframe") }}</td> - <td> - Specifies the Content Security Policy that an embedded document must - agree to enforce upon itself. - </td> - </tr> - <tr> - <td> - <code><a href="/en-US/docs/Web/HTML/Element/object#data">data</a></code> - </td> - <td>{{ HTMLElement("object") }}</td> - <td>Specifies the URL of the resource.</td> - </tr> - <tr> - <td> - <code><a href="/en-US/docs/Web/HTML/Global_attributes/data-*">data-*</a></code> - </td> - <td> - <a href="/en-US/docs/Web/HTML/Global_attributes">Global attribute</a> - </td> - <td>Lets you attach custom attributes to an HTML element.</td> - </tr> - <tr> - <td> - <code><a href="/en-US/docs/Web/HTML/Attributes/datetime">datetime</a></code> - </td> - <td> - {{ HTMLElement("del") }}, {{ HTMLElement("ins") }}, - {{ HTMLElement("time") }} - </td> - <td>Indicates the date and time associated with the element.</td> - </tr> - <tr> - <td> - <code><a href="/en-US/docs/Web/HTML/Element/img#decoding">decoding</a></code> - </td> - <td>{{ HTMLElement("img") }}</td> - <td>Indicates the preferred method to decode the image.</td> - </tr> - <tr> - <td> - <code><a href="/en-US/docs/Web/HTML/Element/track#default">default</a></code> - </td> - <td>{{ HTMLElement("track") }}</td> - <td> - Indicates that the track should be enabled unless the user's preferences - indicate something different. - </td> - </tr> - <tr> - <td> - <code><a href="/en-US/docs/Web/HTML/Element/script#defer">defer</a></code> - </td> - <td>{{ HTMLElement("script") }}</td> - <td> - Indicates that the script should be executed after the page has been - parsed. - </td> - </tr> - <tr> - <td> - <code><a href="/en-US/docs/Web/HTML/Global_attributes/dir">dir</a></code> - </td> - <td> - <a href="/en-US/docs/Web/HTML/Global_attributes">Global attribute</a> - </td> - <td> - Defines the text direction. Allowed values are ltr (Left-To-Right) or - rtl (Right-To-Left) - </td> - </tr> - <tr> - <td> - <code><a href="/en-US/docs/Web/HTML/Attributes/dirname">dirname</a></code> - </td> - <td> - {{ HTMLElement("input") }}, - {{ HTMLElement("textarea") }} - </td> - <td></td> - </tr> - <tr> - <td> - <code><a href="/en-US/docs/Web/HTML/Attributes/disabled">disabled</a></code> - </td> - <td> - {{ HTMLElement("button") }}, - {{ HTMLElement("fieldset") }}, - {{ HTMLElement("input") }}, - {{ HTMLElement("optgroup") }}, - {{ HTMLElement("option") }}, - {{ HTMLElement("select") }}, - {{ HTMLElement("textarea") }} - </td> - <td>Indicates whether the user can interact with the element.</td> - </tr> - <tr> - <td> - <code><a href="/en-US/docs/Web/HTML/Attributes/download">download</a></code> - </td> - <td>{{ HTMLElement("a") }}, {{ HTMLElement("area") }}</td> - <td> - Indicates that the hyperlink is to be used for downloading a resource. - </td> - </tr> - <tr> - <td> - <code><a href="/en-US/docs/Web/HTML/Global_attributes/draggable">draggable</a></code> - </td> - <td> - <a href="/en-US/docs/Web/HTML/Global_attributes">Global attribute</a> - </td> - <td>Defines whether the element can be dragged.</td> - </tr> - <tr> - <td> - <code><a href="/en-US/docs/Web/HTML/Element/form#enctype">enctype</a></code> - </td> - <td>{{ HTMLElement("form") }}</td> - <td> - Defines the content type of the form data when the - <code>method</code> is POST. - </td> - </tr> - <tr> - <td> - <code><a href="/en-US/docs/Web/HTML/Global_attributes/enterkeyhint">enterkeyhint</a></code> - </td> - <td> - {{ HTMLElement("textarea") }}, - <a href="/en-US/docs/Web/HTML/Global_attributes/contenteditable"><code>contenteditable</code></a> - </td> - <td> - The <a href="https://html.spec.whatwg.org/multipage/interaction.html#input-modalities:-the-enterkeyhint-attribute"><code>enterkeyhint</code></a> - specifies what action label (or icon) to present for the enter key on - virtual keyboards. The attribute can be used with form controls (such as - the value of <code>textarea</code> elements), or in elements in an - editing host (e.g., using <code>contenteditable</code> attribute). - </td> - </tr> - <tr> - <td> - <code><a href="/en-US/docs/Web/HTML/Attributes/for">for</a></code> - </td> - <td> - {{ HTMLElement("label") }}, - {{ HTMLElement("output") }} - </td> - <td>Describes elements which belongs to this one.</td> - </tr> - <tr> - <td> - <code><a href="/en-US/docs/Web/HTML/Attributes/form">form</a></code> - </td> - <td> - {{ HTMLElement("button") }}, - {{ HTMLElement("fieldset") }}, - {{ HTMLElement("input") }}, - {{ HTMLElement("label") }}, - {{ HTMLElement("meter") }}, - {{ HTMLElement("object") }}, - {{ HTMLElement("output") }}, - {{ HTMLElement("progress") }}, - {{ HTMLElement("select") }}, - {{ HTMLElement("textarea") }} - </td> - <td>Indicates the form that is the owner of the element.</td> - </tr> - <tr> - <td> - <code><a href="/en-US/docs/Web/HTML/Attributes/formaction">formaction</a></code> - </td> - <td> - {{ HTMLElement("input") }}, - {{ HTMLElement("button") }} - </td> - <td> - Indicates the action of the element, overriding the action defined in - the {{ HTMLElement("form") }}. - </td> - </tr> - <tr> - <td> - <code><a href="/en-US/docs/Web/HTML/Attributes/formenctype">formenctype</a></code> - </td> - <td> - {{ HTMLElement("button") }}, - {{ HTMLElement("input") }} - </td> - <td> - If the button/input is a {{Glossary("submit button")}} (e.g. <code>type="submit"</code>), - this attribute sets the encoding type to use during form submission. If - this attribute is specified, it overrides the - <code>enctype</code> attribute of the button's - <a href="/en-US/docs/Web/HTML/Element/form">form</a> owner. - </td> - </tr> - <tr> - <td> - <code><a href="/en-US/docs/Web/HTML/Attributes/formmethod">formmethod</a></code> - </td> - <td> - {{ HTMLElement("button") }}, - {{ HTMLElement("input") }} - </td> - <td> - If the button/input is a {{Glossary("submit button")}} (e.g. <code>type="submit"</code>), - this attribute sets the submission method to use during form submission - (<code>GET</code>, <code>POST</code>, etc.). If this attribute is - specified, it overrides the <code>method</code> attribute of the - button's <a href="/en-US/docs/Web/HTML/Element/form">form</a> owner. - </td> - </tr> - <tr> - <td> - <code><a href="/en-US/docs/Web/HTML/Attributes/formnovalidate">formnovalidate</a></code> - </td> - <td> - {{ HTMLElement("button") }}, - {{ HTMLElement("input") }} - </td> - <td> - If the button/input is a {{Glossary("submit button")}} (e.g. <code>type="submit"</code>), - this boolean attribute specifies that the form is not to be validated - when it is submitted. If this attribute is specified, it overrides the - <code>novalidate</code> attribute of the button's - <a href="/en-US/docs/Web/HTML/Element/form">form</a> owner. - </td> - </tr> - <tr> - <td> - <code><a href="/en-US/docs/Web/HTML/Attributes/formtarget">formtarget</a></code> - </td> - <td> - {{ HTMLElement("button") }}, - {{ HTMLElement("input") }} - </td> - <td> - If the button/input is a {{Glossary("submit button")}} (e.g. <code>type="submit"</code>), - this attribute specifies the browsing context (for example, tab, window, - or inline frame) in which to display the response that is received after - submitting the form. If this attribute is specified, it overrides the - <code>target</code> attribute of the button's - <a href="/en-US/docs/Web/HTML/Element/form">form</a> owner. - </td> - </tr> - <tr> - <td> - <code><a href="/en-US/docs/Web/HTML/Attributes/headers">headers</a></code> - </td> - <td> - {{ HTMLElement("td") }}, {{ HTMLElement("th") }} - </td> - <td> - IDs of the <code>&#x3C;th></code> elements which applies to this - element. - </td> - </tr> - <tr> - <td><code>height</code></td> - <td> - {{ HTMLElement("canvas") }}, - {{ HTMLElement("embed") }}, - {{ HTMLElement("iframe") }}, {{ HTMLElement("img") }}, - {{ HTMLElement("input") }}, - {{ HTMLElement("object") }}, - {{ HTMLElement("video") }} - </td> - <td> - <p> - Specifies the height of elements listed here. For all other elements, - use the CSS {{cssxref("height")}} property. - </p> - <div class="note notecard"> - <p> - <strong>Note:</strong> In some instances, such as - {{ HTMLElement("div") }}, this is a legacy attribute, in - which case the CSS {{ Cssxref("height") }} property should - be used instead. - </p> - </div> - </td> - </tr> - <tr> - <td> - <code><a href="/en-US/docs/Web/HTML/Global_attributes/hidden">hidden</a></code> - </td> - <td> - <a href="/en-US/docs/Web/HTML/Global_attributes">Global attribute</a> - </td> - <td> - Prevents rendering of given element, while keeping child elements, e.g. - script elements, active. - </td> - </tr> - <tr> - <td> - <code><a href="/en-US/docs/Web/HTML/Element/meter#high">high</a></code> - </td> - <td>{{ HTMLElement("meter") }}</td> - <td>Indicates the lower bound of the upper range.</td> - </tr> - <tr> - <td> - <code><a href="/en-US/docs/Web/HTML/Attributes/href">href</a></code> - </td> - <td> - {{ HTMLElement("a") }}, {{ HTMLElement("area") }}, - {{ HTMLElement("base") }}, {{ HTMLElement("link") }} - </td> - <td>The URL of a linked resource.</td> - </tr> - <tr> - <td> - <code><a href="/en-US/docs/Web/HTML/Attributes/hreflang">hreflang</a></code> - </td> - <td> - {{ HTMLElement("a") }}, {{ HTMLElement("link") }} - </td> - <td>Specifies the language of the linked resource.</td> - </tr> - <tr> - <td> - <code><a href="/en-US/docs/Web/HTML/Element/meta#http-equiv">http-equiv</a></code> - </td> - <td>{{ HTMLElement("meta") }}</td> - <td>Defines a pragma directive.</td> - </tr> - <tr> - <td> - <code><a href="/en-US/docs/Web/HTML/Global_attributes/id">id</a></code> - </td> - <td> - <a href="/en-US/docs/Web/HTML/Global_attributes">Global attribute</a> - </td> - <td> - Often used with CSS to style a specific element. The value of this - attribute must be unique. - </td> - </tr> - <tr> - <td> - <code><a href="/en-US/docs/Web/Security/Subresource_Integrity">integrity</a></code> - </td> - <td> - {{ HTMLElement("link") }}, {{ HTMLElement("script") }} - </td> - <td> - <p> - Specifies a - <a href="/en-US/docs/Web/Security/Subresource_Integrity">Subresource Integrity</a> - value that allows browsers to verify what they fetch. - </p> - </td> - </tr> - <tr> - <td> - <a href="/en-US/docs/Web/HTML/Element/img#intrinsicsize"><code>intrinsicsize</code></a> - {{deprecated_inline}} - </td> - <td>{{ HTMLElement("img") }}</td> - <td> - This attribute tells the browser to ignore the actual intrinsic size of - the image and pretend it's the size specified in the attribute. - </td> - </tr> - <tr> - <td> - <a href="/en-US/docs/Web/HTML/Global_attributes/inputmode"><code>inputmode</code></a> - </td> - <td> - {{ HTMLElement("textarea") }}, - <a href="/en-US/docs/Web/HTML/Global_attributes/contenteditable"><code>contenteditable</code></a> - </td> - <td> - Provides a hint as to the type of data that might be entered by the user - while editing the element or its contents. The attribute can be used - with form controls (such as the value of - <code>textarea</code> elements), or in elements in an editing host - (e.g., using <code>contenteditable</code> attribute). - </td> - </tr> - <tr> - <td> - <code><a href="/en-US/docs/Web/HTML/Element/img#ismap">ismap</a></code> - </td> - <td>{{ HTMLElement("img") }}</td> - <td>Indicates that the image is part of a server-side image map.</td> - </tr> - <tr> - <td> - <code><a href="/en-US/docs/Web/HTML/Global_attributes/itemprop">itemprop</a></code> - </td> - <td> - <a href="/en-US/docs/Web/HTML/Global_attributes">Global attribute</a> - </td> - <td></td> - </tr> - <tr> - <td> - <code><a href="/en-US/docs/Web/HTML/Element/track#kind">kind</a></code> - </td> - <td>{{ HTMLElement("track") }}</td> - <td>Specifies the kind of text track.</td> - </tr> - <tr> - <td> - <code><a href="/en-US/docs/Web/HTML/Attributes/label">label</a></code> - </td> - <td> - {{ HTMLElement("optgroup") }}, - {{ HTMLElement("option") }}, - {{ HTMLElement("track") }} - </td> - <td>Specifies a user-readable title of the element.</td> - </tr> - <tr> - <td> - <code><a href="/en-US/docs/Web/HTML/Global_attributes/lang">lang</a></code> - </td> - <td> - <a href="/en-US/docs/Web/HTML/Global_attributes">Global attribute</a> - </td> - <td>Defines the language used in the element.</td> - </tr> - <tr> - <td> - <code><a href="/en-US/docs/Web/HTML/Element/script#language">language</a></code> - {{deprecated_inline}} - </td> - <td>{{ HTMLElement("script") }}</td> - <td>Defines the script language used in the element.</td> - </tr> - <tr> - <td><code>loading</code></td> - <td> - {{ HTMLElement("img") }}, {{ HTMLElement("iframe") }} - </td> - <td> - Indicates if the element should be loaded lazily - (<code>loading="lazy"</code>) or loaded immediately - (<code>loading="eager"</code>). - </td> - </tr> - <tr> - <td> - <code><a href="/en-US/docs/Web/HTML/Element/input#list">list</a></code> - </td> - <td>{{ HTMLElement("input") }}</td> - <td>Identifies a list of pre-defined options to suggest to the user.</td> - </tr> - <tr> - <td> - <code><a href="/en-US/docs/Web/HTML/Attributes/loop">loop</a></code> - </td> - <td> - {{ HTMLElement("audio") }}, - {{ HTMLElement("marquee") }}, - {{ HTMLElement("video") }} - </td> - <td> - Indicates whether the media should start playing from the start when - it's finished. - </td> - </tr> - <tr> - <td> - <code><a href="/en-US/docs/Web/HTML/Element/meter#low">low</a></code> - </td> - <td>{{ HTMLElement("meter") }}</td> - <td>Indicates the upper bound of the lower range.</td> - </tr> - <tr> - <td> - <code><a href="/en-US/docs/Web/HTML/Attributes/max">max</a></code> - </td> - <td> - {{ HTMLElement("input") }}, - {{ HTMLElement("meter") }}, - {{ HTMLElement("progress") }} - </td> - <td>Indicates the maximum value allowed.</td> - </tr> - <tr> - <td> - <code><a href="/en-US/docs/Web/HTML/Attributes/maxlength">maxlength</a></code> - </td> - <td> - {{ HTMLElement("input") }}, - {{ HTMLElement("textarea") }} - </td> - <td>Defines the maximum number of characters allowed in the element.</td> - </tr> - <tr> - <td> - <code><a href="/en-US/docs/Web/HTML/Attributes/minlength">minlength</a></code> - </td> - <td> - {{ HTMLElement("input") }}, - {{ HTMLElement("textarea") }} - </td> - <td>Defines the minimum number of characters allowed in the element.</td> - </tr> - <tr> - <td> - <code><a href="/en-US/docs/Web/HTML/Attributes/media">media</a></code> - </td> - <td> - {{ HTMLElement("a") }}, {{ HTMLElement("area") }}, - {{ HTMLElement("link") }}, {{ HTMLElement("source") }}, - {{ HTMLElement("style") }} - </td> - <td> - Specifies a hint of the media for which the linked resource was - designed. - </td> - </tr> - <tr> - <td> - <code><a href="/en-US/docs/Web/HTML/Element/form#method">method</a></code> - </td> - <td>{{ HTMLElement("form") }}</td> - <td> - Defines which <a href="/en-US/docs/Web/HTTP">HTTP</a> method to use when - submitting the form. Can be <code>GET</code> (default) or - <code>POST</code>. - </td> - </tr> - <tr> - <td> - <code><a href="/en-US/docs/Web/HTML/Attributes/min">min</a></code> - </td> - <td> - {{ HTMLElement("input") }}, - {{ HTMLElement("meter") }} - </td> - <td>Indicates the minimum value allowed.</td> - </tr> - <tr> - <td> - <code><a href="/en-US/docs/Web/HTML/Attributes/multiple">multiple</a></code> - </td> - <td> - {{ HTMLElement("input") }}, - {{ HTMLElement("select") }} - </td> - <td> - Indicates whether multiple values can be entered in an input of the type - <code>email</code> or <code>file</code>. - </td> - </tr> - <tr> - <td> - <code><a href="/en-US/docs/Web/HTML/Attributes/muted">muted</a></code> - </td> - <td> - {{ HTMLElement("audio") }}, - {{ HTMLElement("video") }} - </td> - <td> - Indicates whether the audio will be initially silenced on page load. - </td> - </tr> - <tr> - <td> - <code><a href="/en-US/docs/Web/HTML/Attributes/name">name</a></code> - </td> - <td> - {{ HTMLElement("button") }}, {{ HTMLElement("form") }}, - {{ HTMLElement("fieldset") }}, - {{ HTMLElement("iframe") }}, - {{ HTMLElement("input") }}, - {{ HTMLElement("object") }}, - {{ HTMLElement("output") }}, - {{ HTMLElement("select") }}, - {{ HTMLElement("textarea") }}, - {{ HTMLElement("map") }}, {{ HTMLElement("meta") }}, - {{ HTMLElement("param") }} - </td> - <td> - Name of the element. For example used by the server to identify the - fields in form submits. - </td> - </tr> - <tr> - <td> - <code><a href="/en-US/docs/Web/HTML/Element/form#novalidate">novalidate</a></code> - </td> - <td>{{ HTMLElement("form") }}</td> - <td> - This attribute indicates that the form shouldn't be validated when - submitted. - </td> - </tr> - <tr> - <td> - <code><a href="/en-US/docs/Web/HTML/Attributes/open">open</a></code> - </td> - <td> - {{ HTMLElement("details") }}, - {{ HTMLElement("dialog") }} - </td> - <td> - Indicates whether the contents are currently visible (in the case of - a <code>&#x3C;details></code> element) or whether the dialog is active - and can be interacted with (in the case of a - <code>&#x3C;dialog></code> element). - </td> - </tr> - <tr> - <td> - <code><a href="/en-US/docs/Web/HTML/Element/meter#optimum">optimum</a></code> - </td> - <td>{{ HTMLElement("meter") }}</td> - <td>Indicates the optimal numeric value.</td> - </tr> - <tr> - <td> - <code><a href="/en-US/docs/Web/HTML/Attributes/pattern">pattern</a></code> - </td> - <td>{{ HTMLElement("input") }}</td> - <td> - Defines a regular expression which the element's value will be validated - against. - </td> - </tr> - <tr> - <td> - <code><a href="/en-US/docs/Web/HTML/Element/a#ping">ping</a></code> - </td> - <td>{{ HTMLElement("a") }}, {{ HTMLElement("area") }}</td> - <td> - The <code>ping</code> attribute specifies a space-separated list of URLs - to be notified if a user follows the hyperlink. - </td> - </tr> - <tr> - <td> - <code><a href="/en-US/docs/Web/HTML/Attributes/placeholder">placeholder</a></code> - </td> - <td> - {{ HTMLElement("input") }}, - {{ HTMLElement("textarea") }} - </td> - <td>Provides a hint to the user of what can be entered in the field.</td> - </tr> - <tr> - <td> - <code><a href="/en-US/docs/Web/HTML/Element/video#playsinline">playsinline</a></code> - </td> - <td> - {{ HTMLElement("video") }} - </td> - <td>A Boolean attribute indicating that the video is to be played "inline"; that is, within the element's playback area. Note that the absence of this attribute does not imply that the video will always be played in fullscreen.</td> - </tr> - <tr> - <td> - <code><a href="/en-US/docs/Web/HTML/Element/video#poster">poster</a></code> - </td> - <td>{{ HTMLElement("video") }}</td> - <td> - A URL indicating a poster frame to show until the user plays or seeks. - </td> - </tr> - <tr> - <td> - <code><a href="/en-US/docs/Web/HTML/Attributes/preload">preload</a></code> - </td> - <td> - {{ HTMLElement("audio") }}, - {{ HTMLElement("video") }} - </td> - <td> - Indicates whether the whole resource, parts of it or nothing should be - preloaded. - </td> - </tr> - <tr> - <td> - <code><a href="/en-US/docs/Web/HTML/Attributes/readonly">readonly</a></code> - </td> - <td> - {{ HTMLElement("input") }}, - {{ HTMLElement("textarea") }} - </td> - <td>Indicates whether the element can be edited.</td> - </tr> - <tr> - <td> - <code><a href="/en-US/docs/Web/HTML/Attributes/referralpolicy">referrerpolicy</a></code> - </td> - <td> - {{ HTMLElement("a") }}, {{ HTMLElement("area") }}, - {{ HTMLElement("iframe") }}, {{ HTMLElement("img") }}, - {{ HTMLElement("link") }}, {{ HTMLElement("script") }} - </td> - <td>Specifies which referrer is sent when fetching the resource.</td> - </tr> - <tr> - <td> - <code><a href="/en-US/docs/Web/HTML/Attributes/rel">rel</a></code> - </td> - <td> - {{ HTMLElement("a") }}, {{ HTMLElement("area") }}, - {{ HTMLElement("link") }} - </td> - <td> - Specifies the relationship of the target object to the link object. - </td> - </tr> - <tr> - <td> - <code><a href="/en-US/docs/Web/HTML/Attributes/required">required</a></code> - </td> - <td> - {{ HTMLElement("input") }}, - {{ HTMLElement("select") }}, - {{ HTMLElement("textarea") }} - </td> - <td>Indicates whether this element is required to fill out or not.</td> - </tr> - <tr> - <td> - <code><a href="/en-US/docs/Web/HTML/Element/ol#reversed">reversed</a></code> - </td> - <td>{{ HTMLElement("ol") }}</td> - <td> - Indicates whether the list should be displayed in a descending order - instead of an ascending order. - </td> - </tr> - <tr> - <td> - <code><a href="/en-US/docs/Web/Accessibility/ARIA/Roles">role</a></code> - </td> - <td><a href="/en-US/docs/Web/HTML/Global_attributes">Global attribute</a></td> - <td>Defines an explicit role for an element for use by assistive technologies.</td> - </tr> - <tr> - <td> - <code><a href="/en-US/docs/Web/HTML/Element/textarea#rows">rows</a></code> - </td> - <td>{{ HTMLElement("textarea") }}</td> - <td>Defines the number of rows in a text area.</td> - </tr> - <tr> - <td> - <code><a href="/en-US/docs/Web/HTML/Attributes/rowspan">rowspan</a></code> - </td> - <td> - {{ HTMLElement("td") }}, {{ HTMLElement("th") }} - </td> - <td>Defines the number of rows a table cell should span over.</td> - </tr> - <tr> - <td> - <code><a href="/en-US/docs/Web/HTML/Element/iframe#sandbox">sandbox</a></code> - </td> - <td>{{ HTMLElement("iframe") }}</td> - <td> - Stops a document loaded in an iframe from using certain features (such - as submitting forms or opening new windows). - </td> - </tr> - <tr> - <td> - <code><a href="/en-US/docs/Web/HTML/Element/th#scope">scope</a></code> - </td> - <td>{{ HTMLElement("th") }}</td> - <td> - Defines the cells that the header test (defined in the - <code>th</code> element) relates to. - </td> - </tr> - <tr> - <td> - <code><a href="/en-US/docs/Web/HTML/Element/style#scoped">scoped</a></code> - {{non-standard_inline}} {{deprecated_inline}} - </td> - <td>{{ HTMLElement("style") }}</td> - <td></td> - </tr> - <tr> - <td> - <code><a href="/en-US/docs/Web/HTML/Element/option#selected">selected</a></code> - </td> - <td>{{ HTMLElement("option") }}</td> - <td>Defines a value which will be selected on page load.</td> - </tr> - <tr> - <td> - <code><a href="/en-US/docs/Web/HTML/Attributes/shape">shape</a></code> - </td> - <td>{{ HTMLElement("a") }}, {{ HTMLElement("area") }}</td> - <td></td> - </tr> - <tr> - <td> - <code><a href="/en-US/docs/Web/HTML/Attributes/size">size</a></code> - </td> - <td> - {{ HTMLElement("input") }}, - {{ HTMLElement("select") }} - </td> - <td> - Defines the width of the element (in pixels). If the element's - <code>type</code> attribute is <code>text</code> or - <code>password</code> then it's the number of characters. - </td> - </tr> - <tr> - <td> - <code><a href="/en-US/docs/Web/HTML/Attributes/sizes">sizes</a></code> - </td> - <td> - {{ HTMLElement("link") }}, {{ HTMLElement("img") }}, - {{ HTMLElement("source") }} - </td> - <td></td> - </tr> - <tr> - <td> - <code><a href="/en-US/docs/Web/HTML/Global_attributes/slot">slot</a></code> - </td> - <td> - <a href="/en-US/docs/Web/HTML/Global_attributes">Global attribute</a> - </td> - <td>Assigns a slot in a shadow DOM shadow tree to an element.</td> - </tr> - <tr> - <td> - <code><a href="/en-US/docs/Web/HTML/Attributes/span">span</a></code> - </td> - <td> - {{ HTMLElement("col") }}, - {{ HTMLElement("colgroup") }} - </td> - <td></td> - </tr> - <tr> - <td> - <code><a href="/en-US/docs/Web/HTML/Global_attributes/spellcheck">spellcheck</a></code> - </td> - <td> - <a href="/en-US/docs/Web/HTML/Global_attributes">Global attribute</a> - </td> - <td>Indicates whether spell checking is allowed for the element.</td> - </tr> - <tr> - <td> - <code><a href="/en-US/docs/Web/HTML/Attributes/src">src</a></code> - </td> - <td> - {{ HTMLElement("audio") }}, - {{ HTMLElement("embed") }}, - {{ HTMLElement("iframe") }}, {{ HTMLElement("img") }}, - {{ HTMLElement("input") }}, - {{ HTMLElement("script") }}, - {{ HTMLElement("source") }}, - {{ HTMLElement("track") }}, - {{ HTMLElement("video") }} - </td> - <td>The URL of the embeddable content.</td> - </tr> - <tr> - <td> - <code><a href="/en-US/docs/Web/HTML/Element/iframe#srcdoc">srcdoc</a></code> - </td> - <td>{{ HTMLElement("iframe") }}</td> - <td></td> - </tr> - <tr> - <td> - <code><a href="/en-US/docs/Web/HTML/Element/track#srclang">srclang</a></code> - </td> - <td>{{ HTMLElement("track") }}</td> - <td></td> - </tr> - <tr> - <td> - <code><a href="/en-US/docs/Web/HTML/Attributes/srcset">srcset</a></code> - </td> - <td> - {{ HTMLElement("img") }}, {{ HTMLElement("source") }} - </td> - <td>One or more responsive image candidates.</td> - </tr> - <tr> - <td> - <code><a href="/en-US/docs/Web/HTML/Element/ol#start">start</a></code> - </td> - <td>{{ HTMLElement("ol") }}</td> - <td>Defines the first number if other than 1.</td> - </tr> - <tr> - <td> - <code><a href="/en-US/docs/Web/HTML/Attributes/step">step</a></code> - </td> - <td>{{ HTMLElement("input") }}</td> - <td></td> - </tr> - <tr> - <td> - <code><a href="/en-US/docs/Web/HTML/Global_attributes/style">style</a></code> - </td> - <td> - <a href="/en-US/docs/Web/HTML/Global_attributes">Global attribute</a> - </td> - <td>Defines CSS styles which will override styles previously set.</td> - </tr> - <tr> - <td> - <code><a href="/en-US/docs/Web/HTML/Element/table#summary">summary</a></code> - {{deprecated_inline}} - </td> - <td>{{ HTMLElement("table") }}</td> - <td></td> - </tr> - <tr> - <td> - <code><a href="/en-US/docs/Web/HTML/Global_attributes/tabindex">tabindex</a></code> - </td> - <td> - <a href="/en-US/docs/Web/HTML/Global_attributes">Global attribute</a> - </td> - <td> - Overrides the browser's default tab order and follows the one specified - instead. - </td> - </tr> - <tr> - <td> - <code><a href="/en-US/docs/Web/HTML/Attributes/target">target</a></code> - </td> - <td> - {{ HTMLElement("a") }}, {{ HTMLElement("area") }}, - {{ HTMLElement("base") }}, {{ HTMLElement("form") }} - </td> - <td> - Specifies where to open the linked document (in the case of an - <code>&#x3C;a></code> element) or where to display the response received - (in the case of a <code>&#x3C;form></code> element) - </td> - </tr> - <tr> - <td> - <code><a href="/en-US/docs/Web/HTML/Global_attributes/title">title</a></code> - </td> - <td> - <a href="/en-US/docs/Web/HTML/Global_attributes">Global attribute</a> - </td> - <td>Text to be displayed in a tooltip when hovering over the element.</td> - </tr> - <tr> - <td> - <code><a href="/en-US/docs/Web/HTML/Global_attributes/translate">translate</a></code> - </td> - <td> - <a href="/en-US/docs/Web/HTML/Global_attributes">Global attribute</a> - </td> - <td> - Specify whether an element's attribute values and the values of its - <code><a href="https://dom.spec.whatwg.org/#text">Text</a></code> node - children are to be translated when the page is localized, or whether to - leave them unchanged. - </td> - </tr> - <tr> - <td> - <code><a href="/en-US/docs/Web/HTML/Attributes/type">type</a></code> - </td> - <td> - {{ HTMLElement("button") }}, - {{ HTMLElement("input") }}, - {{ HTMLElement("embed") }}, - {{ HTMLElement("object") }}, - {{ HTMLElement("ol") }}, - {{ HTMLElement("script") }}, - {{ HTMLElement("source") }}, - {{ HTMLElement("style") }}, {{ HTMLElement("menu") }}, - {{ HTMLElement("link") }} - </td> - <td>Defines the type of the element.</td> - </tr> - <tr> - <td> - <code><a href="/en-US/docs/Web/HTML/Attributes/usemap">usemap</a></code> - </td> - <td> - {{ HTMLElement("img") }}, {{ HTMLElement("input") }}, - {{ HTMLElement("object") }} - </td> - <td></td> - </tr> - <tr> - <td> - <code><a href="/en-US/docs/Web/HTML/Attributes/value">value</a></code> - </td> - <td> - {{ HTMLElement("button") }}, {{ HTMLElement("data") }}, - {{ HTMLElement("input") }}, {{ HTMLElement("li") }}, - {{ HTMLElement("meter") }}, - {{ HTMLElement("option") }}, - {{ HTMLElement("progress") }}, - {{ HTMLElement("param") }} - </td> - <td> - Defines a default value which will be displayed in the element on page - load. - </td> - </tr> - <tr> - <td> - <code><a href="/en-US/docs/Web/HTML/Attributes/width">width</a></code> - </td> - <td> - {{ HTMLElement("canvas") }}, - {{ HTMLElement("embed") }}, - {{ HTMLElement("iframe") }}, {{ HTMLElement("img") }}, - {{ HTMLElement("input") }}, - {{ HTMLElement("object") }}, - {{ HTMLElement("video") }} - </td> - <td> - <p> - For the elements listed here, this establishes the element's width. - </p> - <div class="note notecard"> - <p> - <strong>Note:</strong> For all other instances, such as - {{ HTMLElement("div") }}, this is a legacy attribute, in - which case the CSS {{ Cssxref("width") }} property should be - used instead. - </p> - </div> - </td> - </tr> - <tr> - <td> - <code><a href="/en-US/docs/Web/HTML/Element/textarea#wrap">wrap</a></code> - </td> - <td>{{ HTMLElement("textarea") }}</td> - <td>Indicates whether the text should be wrapped.</td> - </tr> - </tbody> -</table> - -## Content versus IDL attributes - -In HTML, most attributes have two faces: the **content attribute** and the **IDL (Interface Definition Language) attribute**. - -The content attribute is the attribute as you set it from the content (the HTML code) and you can set it or get it via {{domxref("element.setAttribute()")}} or {{domxref("element.getAttribute()")}}. The content attribute is always a string even when the expected value should be an integer. For example, to set an {{HTMLElement("input")}} element's `maxlength` to 42 using the content attribute, you have to call `setAttribute("maxlength", "42")` on that element. - -The IDL attribute is also known as a JavaScript property. These are the attributes you can read or set using JavaScript properties like `element.foo`. The IDL attribute is always going to use (but might transform) the underlying content attribute to return a value when you get it and is going to save something in the content attribute when you set it. In other words, the IDL attributes, in essence, reflect the content attributes. - -Most of the time, IDL attributes will return their values as they are really used. For example, the default `type` for {{HTMLElement("input")}} elements is "text", so if you set `input.type="foobar"`, the `<input>` element will be of type text (in the appearance and the behavior) but the "type" content attribute's value will be "foobar". However, the `type` IDL attribute will return the string "text". - -IDL attributes are not always strings; for example, `input.maxlength` is a number (a signed long). When using IDL attributes, you read or set values of the desired type, so `input.maxlength` is always going to return a number and when you set `input.maxlength`, it wants a number. If you pass another type, it is automatically converted to a number as specified by the standard JavaScript rules for type conversion. - -IDL attributes can [reflect other types](https://html.spec.whatwg.org/multipage/urls-and-fetching.html) such as unsigned long, URLs, booleans, etc. Unfortunately, there are no clear rules and the way IDL attributes behave in conjunction with their corresponding content attributes depends on the attribute. Most of the time, it will follow [the rules laid out in the specification](https://html.spec.whatwg.org/multipage/urls-and-fetching.html), but sometimes it doesn't. HTML specifications try to make this as developer-friendly as possible, but for various reasons (mostly historical), some attributes behave oddly (`select.size`, for example) and you should read the specifications to understand how exactly they behave. - -## Boolean Attributes - -Some content attributes (e.g. `required`, `readonly`, `disabled`) are called [boolean attributes](https://html.spec.whatwg.org/multipage/common-microsyntaxes.html#boolean-attributes). If a boolean attribute is present, its value is **true**, and if it's absent, its value is **false**. - -HTML defines restrictions on the allowed values of boolean attributes: If the attribute is present, its value must either be the empty string (equivalently, the attribute may have an unassigned value), or a value that is an ASCII case-insensitive match for the attribute's canonical name, with no leading or trailing whitespace. The following examples are valid ways to mark up a boolean attribute: - -```html-nolint -<div itemscope>This is valid HTML but invalid XML.</div> -<div itemscope=itemscope>This is also valid HTML but invalid XML.</div> -<div itemscope="">This is valid HTML and also valid XML.</div> -<div itemscope="itemscope"> - This is also valid HTML and XML, but perhaps a bit verbose. -</div> -``` - -To be clear, the values `"true"` and `"false"` are not allowed on boolean attributes. To represent a false value, the attribute has to be omitted altogether. This restriction clears up some common misunderstandings: With `checked="false"` for example, the element's `checked` attribute would be interpreted as **true** because the attribute is present. - -## Event handler attributes - -> [!WARNING] -> The use of event handler content attributes is discouraged. The mix of HTML and JavaScript often produces unmaintainable code, and the execution of event handler attributes may also be blocked by content security policies. - -In addition to the attributes listed in the table above, global [event handlers](/en-US/docs/Web/Events/Event_handlers#using_onevent_properties) — such as [`onclick`](/en-US/docs/Web/API/Element/click_event) — can also be specified as [content attributes](#content_versus_idl_attributes) on all elements. - -All event handler attributes accept a string. The string will be used to synthesize a [JavaScript function](/en-US/docs/Web/JavaScript/Reference/Functions) like `function name(/*args*/) {body}`, where `name` is the attribute's name, and `body` is the attribute's value. The handler receives the same parameters as its JavaScript event handler counterpart — most handlers receive only one `event` parameter, while `onerror` receives five: `event`, `source`, `lineno`, `colno`, `error`. This means you can, in general, use the `event` variable within the attribute. - -```html -<div onclick="console.log(event)">Click me!</div> -<!-- The synthesized handler has a name; you can reference itself --> -<div onclick="console.log(onclick)">Click me!</div> -``` - -## See also - -- [HTML elements](/en-US/docs/Web/HTML/Element) diff --git a/files/en-us/web/html/attributes/max/index.md b/files/en-us/web/html/attributes/max/index.md deleted file mode 100644 index d5e99eb519cbf54..000000000000000 --- a/files/en-us/web/html/attributes/max/index.md +++ /dev/null @@ -1,149 +0,0 @@ ---- -title: "HTML attribute: max" -short-title: max -slug: Web/HTML/Attributes/max -page-type: html-attribute -browser-compat: - - html.elements.input.max - - html.elements.meter.max - - html.elements.progress.max ---- - -{{HTMLSidebar}} - -The **`max`** attribute defines the maximum value that is acceptable and valid for the input containing the attribute. If the [`value`](/en-US/docs/Web/HTML/Element/input#value) of the element is greater than this, the element fails [validation](/en-US/docs/Learn_web_development/Extensions/Forms/Form_validation). This value must be greater than or equal to the value of the [`min`](/en-US/docs/Web/HTML/Attributes/min) attribute. If the `max` attribute is present but is not specified or is invalid, no `max` value is applied. If the `max` attribute is valid and a non-empty value is greater than the maximum allowed by the `max` attribute, constraint validation will prevent form submission. - -The max attribute is valid for the numeric input types, including the {{HTMLElement("input/date", "date")}}, {{HTMLElement("input/month", "month")}}, {{HTMLElement("input/week", "week")}}, {{HTMLElement("input/time", "time")}}, {{HTMLElement("input/datetime-local", "datetime-local")}}, {{HTMLElement("input/number", "number")}} and {{HTMLElement("input/range", "range")}} types, and both the {{htmlelement('progress')}} and {{htmlelement('meter')}} elements. It is a number that specifies the most positive value a form control to be considered valid. - -If the value exceeds the max value allowed, the {{domxref('validityState.rangeOverflow')}} will be true, and the control will be matched by the {{cssxref(':out-of-range')}} and {{cssxref(':invalid')}} pseudo-classes. - -## Syntax - -<table class="no-markdown"> - <caption> - Syntax for - <code>max</code> - values by input - <code>type</code> - </caption> - <thead> - <tr> - <th>Input type</th> - <th>Syntax</th> - <th>Example</th> - </tr> - </thead> - <tbody> - <tr> - <td>{{HTMLElement("input/date", "date")}}</td> - <td><code>yyyy-mm-dd</code></td> - <td><code>&#x3C;input type="date" max="2019-12-25" step="1"></code></td> - </tr> - <tr> - <td>{{HTMLElement("input/month", "month")}}</td> - <td><code>yyyy-mm</code></td> - <td><code>&#x3C;input type="month" max="2019-12" step="12"></code></td> - </tr> - <tr> - <td>{{HTMLElement("input/week", "week")}}</td> - <td><code>yyyy-W##</code></td> - <td><code>&#x3C;input type="week" max="2019-W23" step=""></code></td> - </tr> - <tr> - <td>{{HTMLElement("input/time", "time")}}</td> - <td><code>HH:mm</code></td> - <td><code>&#x3C;input type="time" max="17:00" step="900"></code></td> - </tr> - <tr> - <td> - {{HTMLElement("input/datetime-local", "datetime-local")}} - </td> - <td><code>yyyy-mm-ddTHH:mm</code></td> - <td> - <code>&#x3C;input type="datetime-local" max="2019-12-25T23:59"></code> - </td> - </tr> - <tr> - <td>{{HTMLElement("input/number", "number")}}</td> - <td><a href="/en-US/docs/Web/CSS/number">&#x3C;number></a></td> - <td> - <code>&#x3C;input type="number" min="0" step="5" max="100"></code> - </td> - </tr> - <tr> - <td>{{HTMLElement("input/range", "range")}}</td> - <td><a href="/en-US/docs/Web/CSS/number">&#x3C;number></a></td> - <td> - <code>&#x3C;input type="range" min="60" step="5" max="100"></code> - </td> - </tr> - </tbody> -</table> - -> [!NOTE] -> When the data entered by the user doesn't adhere to the maximum value set, the value is considered invalid in constraint validation and will match the {{cssxref(':invalid')}} and {{cssxref(':out-of-range')}} pseudo-classes. - -See [Client-side validation](/en-US/docs/Web/HTML/Constraint_validation) and {{domxref("ValidityState.rangeOverflow", "rangeOverflow")}} for more information. - -For the {{htmlelement('progress')}} element, the `max` attribute describes how much work the task indicated by the `progress` element requires. If present, must have a value greater than zero and be a valid floating point number. For the {{htmlelement('meter')}} element, the `max` attribute defines the upper numeric bound of the measured range. This must be greater than the minimum value ([`min`](/en-US/docs/Web/HTML/Attributes/min) attribute), if specified. In both cases, if omitted, the value defaults to 1. - -<table class="no-markdown"> - <caption> - Syntax for - <code>max</code> - values for other elements - </caption> - <thead> - <tr> - <th>Input type</th> - <th>Syntax</th> - <th>Example</th> - </tr> - </thead> - <tbody> - <tr> - <td>{{HTMLElement("progress")}}</td> - <td><a href="/en-US/docs/Web/CSS/number">&#x3C;number></a></td> - <td> - <code - >&#x3C;progress id="file" max="100" value="70"> 70% - &#x3C;/progress></code - > - </td> - </tr> - <tr> - <td>{{HTMLElement("meter")}}</td> - <td><a href="/en-US/docs/Web/CSS/number">&#x3C;number></a></td> - <td> - <code - >&#x3C;meter id="fuel" min="0" max="100" low="33" high="66" - optimum="80" value="40"> at 40/100&#x3C;/meter></code - > - </td> - </tr> - </tbody> -</table> - -## Accessibility concerns - -Provide instructions to help users understand how to complete the form and use individual form controls. Indicate any required and optional input, data formats, and other relevant information. When using the `max` attribute, ensure this maximum requirement is understood by the user. Providing instructions within the {{htmlelement('label')}} may be sufficient. If providing instructions outside of labels, which allows more flexible positioning and design, consider using [`aria-labelledby`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-labelledby) or [`aria-describedby`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-describedby). - -## Specifications - -{{Specifications}} - -## Browser compatibility - -{{Compat}} - -## See also - -- [`step`](/en-US/docs/Web/HTML/Attributes/step) -- [`min`](/en-US/docs/Web/HTML/Attributes/min) -- other meter attributes: [`low`](/en-US/docs/Web/HTML/Attributes/low), [`high`](/en-US/docs/Web/HTML/Attributes/high), [`optimum`](/en-US/docs/Web/HTML/Attributes/optimum) -- [Constraint validation](/en-US/docs/Web/HTML/Constraint_validation) -- [Form validation](/en-US/docs/Learn_web_development/Extensions/Forms/Form_validation) -- {{domxref('validityState.rangeOverflow')}} -- {{cssxref(':out-of-range')}} -- {{htmlelement('input')}} -- {{HTMLElement("input/date", "date")}}, {{HTMLElement("input/month", "month")}}, {{HTMLElement("input/week", "week")}}, {{HTMLElement("input/time", "time")}}, {{HTMLElement("input/datetime-local", "datetime-local")}}, {{HTMLElement("input/number", "number")}} and {{HTMLElement("input/range", "range")}} types, and the {{htmlelement('meter')}} diff --git a/files/en-us/web/html/attributes/maxlength/index.md b/files/en-us/web/html/attributes/maxlength/index.md deleted file mode 100644 index cafc160eb1b0a04..000000000000000 --- a/files/en-us/web/html/attributes/maxlength/index.md +++ /dev/null @@ -1,80 +0,0 @@ ---- -title: "HTML attribute: maxlength" -short-title: maxlength -slug: Web/HTML/Attributes/maxlength -page-type: html-attribute -browser-compat: - - html.elements.input.maxlength - - html.elements.textarea.maxlength ---- - -{{HTMLSidebar}} - -The **`maxlength`** attribute defines the maximum [string length](/en-US/docs/Web/JavaScript/Reference/Global_Objects/String/length) that the user can enter into an {{htmlelement('input')}} or {{htmlelement('textarea')}}. The attribute must have an integer value of 0 or higher. - -The length is measured in UTF-16 code units, which ([for most scripts](/en-US/docs/Web/JavaScript/Reference/Global_Objects/String/length#strings_with_length_not_equal_to_the_number_of_characters)) is equivalent to the number of characters. If no `maxlength` is specified, or an invalid value is specified, the input has no maximum length. - -Any `maxlength` value must be greater than or equal to the value of [`minlength`](/en-US/docs/Web/HTML/Attributes/minlength), if present and valid. The input will fail constraint validation if the length of the text value of the field is greater than maxlength UTF-16 code units long. Constraint validation is only applied when the value is changed by the user. - -### Constraint validation - -While the browser will generally prevent user from entering more text than the maxlength attribute allows, should the length be longer than the maxlength allows, the read-only {{domxref("ValidityState.tooLong", "tooLong")}} property of a {{domxref("ValidityState")}} object will be true. - -{{InteractiveExample("HTML Demo: maxlength", "tabbed-shorter")}} - -```html interactive-example -<label for="name">Product name:</label> -<input - id="name" - name="name" - type="text" - value="Shampoo" - minlength="3" - maxlength="20" - required /> - -<label for="description">Product description:</label> -<textarea - id="description" - name="description" - minlength="10" - maxlength="40" - required></textarea> -``` - -```css interactive-example -label { - display: block; - margin-top: 1em; -} - -input:valid, -textarea:valid { - background-color: palegreen; -} -``` - -## Examples - -```html -<input type="password" maxlength="4" /> -``` - -{{EmbedLiveSample('Examples', '100%', 200)}} - -## Specifications - -{{Specifications}} - -## Browser compatibility - -{{Compat}} - -## See also - -- [`minlength`](/en-US/docs/Web/HTML/Attributes/minlength) -- [`size`](/en-US/docs/Web/HTML/Attributes/size) -- [`pattern`](/en-US/docs/Web/HTML/Attributes/pattern) -- [Constraint validation](/en-US/docs/Web/HTML/Constraint_validation) -- [Form validation](/en-US/docs/Learn_web_development/Extensions/Forms/Form_validation) -- {{htmlelement('input')}} diff --git a/files/en-us/web/html/attributes/min/index.md b/files/en-us/web/html/attributes/min/index.md deleted file mode 100644 index 7f5ce56b864cdb9..000000000000000 --- a/files/en-us/web/html/attributes/min/index.md +++ /dev/null @@ -1,162 +0,0 @@ ---- -title: "HTML attribute: min" -short-title: min -slug: Web/HTML/Attributes/min -page-type: html-attribute -browser-compat: - - html.elements.input.min - - html.elements.meter.min ---- - -{{HTMLSidebar}} - -The **`min`** attribute defines the minimum value that is acceptable and valid for the input containing the attribute. If the [`value`](/en-US/docs/Web/HTML/Element/input#value) of the element is less than this, the element fails [validation](/en-US/docs/Learn_web_development/Extensions/Forms/Form_validation). This value must be less than or equal to the value of the `max` attribute. - -Some input types have a default minimum. If the input has no default minimum and a value is specified for `min` that can't be converted to a valid number (or no minimum value is set), the input has no minimum value. - -It is valid for the input types including: {{HTMLElement("input/date", "date")}}, {{HTMLElement("input/month", "month")}}, {{HTMLElement("input/week", "week")}}, {{HTMLElement("input/time", "time")}}, {{HTMLElement("input/datetime-local", "datetime-local")}}, {{HTMLElement("input/number", "number")}} and {{HTMLElement("input/range", "range")}} types, and the {{htmlelement('meter')}} element. - -## Syntax - -<table class="no-markdown"> - <caption> - Syntax for - <code>min</code> - values by input - <code>type</code> - </caption> - <thead> - <tr> - <th>Input type</th> - <th>Syntax</th> - <th>Example</th> - </tr> - </thead> - <tbody> - <tr> - <td>{{HTMLElement("input/date", "date")}}</td> - <td><code>yyyy-mm-dd</code></td> - <td><code>&#x3C;input type="date" min="2019-12-25" step="1"></code></td> - </tr> - <tr> - <td>{{HTMLElement("input/month", "month")}}</td> - <td><code>yyyy-mm</code></td> - <td><code>&#x3C;input type="month" min="2019-12" step="12"></code></td> - </tr> - <tr> - <td>{{HTMLElement("input/week", "week")}}</td> - <td><code>yyyy-W##</code></td> - <td><code>&#x3C;input type="week" min="2019-W23" step=""></code></td> - </tr> - <tr> - <td>{{HTMLElement("input/time", "time")}}</td> - <td><code>HH:mm</code></td> - <td><code>&#x3C;input type="time" min="09:00" step="900"></code></td> - </tr> - <tr> - <td> - {{HTMLElement("input/datetime-local", "datetime-local")}} - </td> - <td><code>yyyy-mm-ddTHH:mm</code></td> - <td> - <code>&#x3C;input type="datetime-local" min="2019-12-25T19:30"></code> - </td> - </tr> - <tr> - <td>{{HTMLElement("input/number", "number")}}</td> - <td><a href="/en-US/docs/Web/CSS/number">&#x3C;number></a></td> - <td> - <code>&#x3C;input type="number" min="0" step="5" max="100"></code> - </td> - </tr> - <tr> - <td>{{HTMLElement("input/range", "range")}}</td> - <td><a href="/en-US/docs/Web/CSS/number">&#x3C;number></a></td> - <td> - <code>&#x3C;input type="range" min="60" step="5" max="100"></code> - </td> - </tr> - </tbody> -</table> - -> [!NOTE] -> When the data entered by the user doesn't adhere to the min value set, the value is considered invalid in constraint validation and will match the {{cssxref(':invalid')}} and {{cssxref(':out-of-range')}} pseudo-classes. - -See [Client-side validation](/en-US/docs/Web/HTML/Constraint_validation) and {{domxref("ValidityState.rangeUnderflow", "rangeUnderflow")}} for more information. - -For the {{htmlelement('meter')}} element, the `min` attribute defines the lower numeric bound of the measured range. This must be less than the maximum value ([`max`](/en-US/docs/Web/HTML/Attributes/max) attribute), if specified. In both cases, if omitted, the value defaults to 1. - -<table class="no-markdown"> - <caption> - Syntax for - <code>min</code> - values for other elements - </caption> - <thead> - <tr> - <th>Input type</th> - <th>Syntax</th> - <th>Example</th> - </tr> - </thead> - <tbody> - <tr> - <td>{{HTMLElement("meter")}}</td> - <td><a href="/en-US/docs/Web/CSS/number">&#x3C;number></a></td> - <td> - <code - >&#x3C;meter id="fuel" min="0" max="100" low="33" high="66" - optimum="80" value="40"> at 40/100&#x3C;/meter></code - > - </td> - </tr> - </tbody> -</table> - -### Impact on step - -The value of `min` and `step` define what are valid values, even if the `step` attribute is not included, as `step` defaults to `0`. - -We add a big red border around invalid inputs: - -```css -input:invalid { - border: solid red 3px; -} -``` - -Then define an input with a minimum value of 7.2, omitting the step attribute, wherein it defaults to 1. - -```html -<input id="myNumber" name="myNumber" type="number" min="7.2" value="8" /> -``` - -Because `step` defaults to 1, valid values include `7.2`, `8.2`, `9.2`, and so on. The value 8 is not valid. As we included an invalid value, supporting browsers will show the value as invalid. - -{{EmbedLiveSample("Impact_on_step",200,55)}} - -If not explicitly included, `step` defaults to 1 for `number` and `range`, and 1 unit type (second, week, month, day) for the date/time input types. - -## Accessibility concerns - -Provide instructions to help users understand how to complete the form and use individual form controls. Indicate any required and optional input, data formats, and other relevant information. When using the `min` attribute, ensure this minimum requirement is understood by the user. Providing instructions within the {{htmlelement('label')}} may be sufficient. If providing instructions outside of labels, which allows more flexible positioning and design, consider using [`aria-labelledby`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-labelledby) or [`aria-describedby`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-describedby). - -## Specifications - -{{Specifications}} - -## Browser compatibility - -{{Compat}} - -## See also - -- [`step`](/en-US/docs/Web/HTML/Attributes/step) -- [`max`](/en-US/docs/Web/HTML/Attributes/max) -- other meter attributes: [`low`](/en-US/docs/Web/HTML/Attributes/low), [`high`](/en-US/docs/Web/HTML/Attributes/high), [`optimum`](/en-US/docs/Web/HTML/Attributes/optimum) -- [Constraint validation](/en-US/docs/Web/HTML/Constraint_validation) -- [Form validation](/en-US/docs/Learn_web_development/Extensions/Forms/Form_validation) -- {{domxref('validityState.rangeUnderflow')}} -- {{cssxref(':out-of-range')}} -- {{htmlelement('input')}} -- {{HTMLElement("input/date", "date")}}, {{HTMLElement("input/month", "month")}}, {{HTMLElement("input/week", "week")}}, {{HTMLElement("input/time", "time")}}, {{HTMLElement("input/datetime-local", "datetime-local")}}, {{HTMLElement("input/number", "number")}} and {{HTMLElement("input/range", "range")}} types, and the {{htmlelement('meter')}} diff --git a/files/en-us/web/html/attributes/minlength/index.md b/files/en-us/web/html/attributes/minlength/index.md deleted file mode 100644 index 26769d3d6389ed6..000000000000000 --- a/files/en-us/web/html/attributes/minlength/index.md +++ /dev/null @@ -1,95 +0,0 @@ ---- -title: "HTML attribute: minlength" -short-title: minlength -slug: Web/HTML/Attributes/minlength -page-type: html-attribute -browser-compat: - - html.elements.input.minlength - - html.elements.textarea.minlength ---- - -{{HTMLSidebar}} - -The **`minlength`** attribute defines the minimum [string length](/en-US/docs/Web/JavaScript/Reference/Global_Objects/String/length) that the user can enter into an {{htmlelement('input')}} or {{htmlelement('textarea')}}. The attribute must have an integer value of 0 or higher. - -The length is measured in UTF-16 code units, which ([for most scripts](/en-US/docs/Web/JavaScript/Reference/Global_Objects/String/length#strings_with_length_not_equal_to_the_number_of_characters)) is equivalent to the number of characters. If no `minlength` is specified, or an invalid value is specified, the input has no minimum length. This value must be less than or equal to the value of [maxlength](/en-US/docs/Web/HTML/Attributes/maxlength), otherwise the value will never be valid, as it is impossible to meet both criteria. - -The input will fail constraint validation if the length of the text value of the field is less than minlength UTF-16 code units long, with {{domxref('validityState.tooShort')}} returning `true`. Constraint validation is only applied when the value is changed by the user. Once submission fails, some browsers will display an error message indicating the minimum length required and the current length. - -`minlength` does not imply [`required`](/en-US/docs/Web/HTML/Attributes/required); an input only violates a `minlength` constraint if the user has input a value. If an input is not `required`, an empty string can be submitted even if `minlength` is set. - -{{InteractiveExample("HTML Demo: minlength", "tabbed-shorter")}} - -```html interactive-example -<label for="name">Product name:</label> -<input - id="name" - name="name" - type="text" - value="Shampoo" - minlength="3" - maxlength="20" - required /> - -<label for="description">Product description:</label> -<textarea - id="description" - name="description" - minlength="10" - maxlength="40" - required></textarea> -``` - -```css interactive-example -label { - display: block; - margin-top: 1em; -} - -input:valid, -textarea:valid { - background-color: palegreen; -} -``` - -## Examples - -By adding `minlength="5"`, the value must either be empty or five characters or longer to be valid. - -```html -<label for="fruit">Enter a fruit name that is at least 5 letters long</label> -<input type="text" minlength="5" id="fruit" /> -``` - -We can use pseudoclasses to style the element based on whether the value is valid. The value will be valid as long as it is either null (empty) or five or more characters long. _Lime_ is invalid, _lemon is valid_. - -```css -input { - border: 2px solid currentcolor; -} -input:invalid { - border: 2px dashed red; -} -input:invalid:focus { - background-image: linear-gradient(pink, lightgreen); -} -``` - -{{EmbedLiveSample('Examples', '100%', 200)}} - -## Specifications - -{{Specifications}} - -## Browser compatibility - -{{Compat}} - -## See also - -- [`maxlength`](/en-US/docs/Web/HTML/Attributes/maxlength) -- [`size`](/en-US/docs/Web/HTML/Attributes/size) -- [`pattern`](/en-US/docs/Web/HTML/Attributes/pattern) -- [Constraint validation](/en-US/docs/Web/HTML/Constraint_validation) -- [Form validation](/en-US/docs/Learn_web_development/Extensions/Forms/Form_validation) -- {{htmlelement('input')}} diff --git a/files/en-us/web/html/attributes/multiple/index.md b/files/en-us/web/html/attributes/multiple/index.md deleted file mode 100644 index d311a626af3ddec..000000000000000 --- a/files/en-us/web/html/attributes/multiple/index.md +++ /dev/null @@ -1,231 +0,0 @@ ---- -title: "HTML attribute: multiple" -short-title: multiple -slug: Web/HTML/Attributes/multiple -page-type: html-attribute -browser-compat: - - html.elements.input.multiple - - html.elements.select.multiple ---- - -{{HTMLSidebar}} - -The Boolean **`multiple`** attribute, if set, means the form control accepts one or more values. The attribute is valid for the {{HTMLElement("input/email", "email")}} and {{HTMLElement("input/file", "file")}} input types and the {{HTMLElement("select")}}. The manner by which the user opts for multiple values depends on the form control. - -{{InteractiveExample("HTML Demo: multiple", "tabbed-standard")}} - -```html interactive-example -<label for="recipients">Where should we send the receipt?</label> -<input id="recipients" name="recipients" type="email" multiple /> - -<label for="shakes">Which shakes would you like to order?</label> -<select id="shakes" name="shakes" multiple> - <option>Vanilla Shake</option> - <option>Strawberry Shake</option> - <option>Chocolate Shake</option> -</select> - -<label for="payment">How would you like to pay?</label> -<select id="payment" name="payment"> - <option>Credit card</option> - <option>Bank Transfer</option> -</select> -``` - -```css interactive-example -label { - display: block; - margin-top: 1em; -} - -input, -select { - width: 100%; -} - -input:invalid { - background-color: lightpink; -} -``` - -## Overview - -Depending on the type, the form control may have a different appearance if the `multiple` attribute is set. For the file input type, the native messaging the browser provides differs. In Firefox, the file input reads "No files selected" when the attribute is present and "No file selected" when it is not. Most browsers display a scrolling list box for a {{HTMLElement("select")}} control with the `multiple` attribute set and a single line dropdown when the attribute is omitted. The {{HTMLElement("input/email", "email")}} input displays the same whether or not the `multiple` attribute is included, but will match the {{cssxref(':invalid')}} pseudo-class if more than one comma-separated email address is included if the attribute is not present. - -When `multiple` is set on the {{HTMLElement("input/email", "email")}} input type, the user can include zero (if not also [`required`](/en-US/docs/Web/HTML/Attributes/required)), one or more comma-separated email addresses. - -```html -<input type="email" multiple name="emails" id="emails" /> -``` - -If and only if the `multiple` attribute is specified, the value can be a list of properly-formed comma-separated email addresses. Any trailing and leading whitespace is removed from each address in the list. - -When `multiple` is set on the {{HTMLElement("input/file", "file")}} input type, the user can select one or more files. The user can choose multiple files from the file picker in any way that their chosen platform allows (e.g. by holding down <kbd>Shift</kbd> or <kbd>Control</kbd>, and then clicking). - -```html -<input type="file" multiple name="uploads" id="uploads" /> -``` - -When the attribute is omitted, the user can only select a single file per `<input>`. - -The `multiple` attribute on the {{HTMLElement("select")}} element represents a control for selecting zero or more options from the list of options. Otherwise, the {{HTMLElement("select")}} element represents a control for selecting a single {{HTMLElement("option")}} from the list of options. - -```html -<select multiple name="dwarfs" id="dwarfs"> - <option>Grumpy</option> - <option>Happy</option> - <option>Sleepy</option> - <option>Bashful</option> - <option>Sneezy</option> - <option>Dopey</option> - <option>Doc</option> -</select> -``` - -When `multiple` is specified, most browsers will show a scrolling list box instead of a single line dropdown. - -## Accessibility concerns - -Provide instructions to help users understand how to complete the form and use individual form controls. Indicate any required and optional input, data formats, and other relevant information. When using the `multiple` attribute, inform the user that multiple values are allowed and provide directions on how to provide multiple values, such as "separate email addresses with a comma." - -Setting `size="1"` on a multiple select can make it appear as a single select in some browsers, but then it doesn't expand on focus, harming usability. Don't do that. If you do change the appearance of a select, and even if you don't, make sure to inform the user that more than one option can be selected by another method. - -## Examples - -### email input - -```html -<label for="emails">Who do you want to email?</label> -<input - type="email" - multiple - name="emails" - id="emails" - list="dwarf-emails" - required - size="64" /> - -<datalist id="dwarf-emails"> - <option value="grumpy@woodworkers.com">Grumpy</option> - <option value="happy@woodworkers.com">Happy</option> - <option value="sleepy@woodworkers.com">Sleepy</option> - <option value="bashful@woodworkers.com">Bashful</option> - <option value="sneezy@woodworkers.com">Sneezy</option> - <option value="dopey@woodworkers.com">Dopey</option> - <option value="doc@woodworkers.com">Doc</option> -</datalist> -``` - -```css hidden -input:invalid { - border: red solid 3px; -} -``` - -If and only if the `multiple` attribute is specified, the value can be a list of properly-formed comma-separated email addresses. Any trailing and leading whitespace is removed from each address in the list. If the [`required`](/en-US/docs/Web/HTML/Attributes/required) attribute is present, at least one email address is required. - -Some browsers support the appearance of the [`list`](/en-US/docs/Web/HTML/Element/input#list) of options from the associated {{htmlelement('datalist')}} for subsequent email addresses when `multiple` is present. Others do not. - -{{EmbedLiveSample("email_input", 600, 80) }} - -### file input - -When `multiple` is set on the {{HTMLElement("input/file", "file")}} input type, the user can select one or more files: - -```html -<form method="post" enctype="multipart/form-data"> - <p> - <label for="uploads"> Choose the images you want to upload: </label> - <input - type="file" - id="uploads" - name="uploads" - accept=".jpg, .jpeg, .png, .svg, .gif" - multiple /> - </p> - <p> - <label for="text">Pick a text file to upload: </label> - <input type="file" id="text" name="text" accept=".txt" /> - </p> - <p> - <input type="submit" value="Submit" /> - </p> -</form> -``` - -{{EmbedLiveSample("file_input", 600, 80) }} - -Note the difference in appearance between the example with `multiple` set and the other `file` input without. - -When the form is submitted, had we used [`method="get"`](/en-US/docs/Web/HTML/Element/form) each selected file's name would have been added to URL parameters as `?uploads=img1.jpg&uploads=img2.svg`. However, since we are submitting multipart form data, we must use post. See the {{htmlelement('form')}} element and [sending form data](/en-US/docs/Learn_web_development/Extensions/Forms/Sending_and_retrieving_form_data#the_method_attribute) for more information. - -### select - -The `multiple` attribute on the {{HTMLElement("select")}} element represents a control for selecting zero or more options from the list of options. Otherwise, the {{HTMLElement("select")}} element represents a control for selecting a single {{HTMLElement("option")}} from the list of options. The control generally has a different appearance based on the presence of the multiple attribute, with most browsers displaying a scrolling list box instead of a single line dropdown when the attribute is present. - -```html -<form method="get" action="#"> - <p> - <label for="dwarfs">Select the dwarf woodsman you like:</label> - <select multiple name="dwarfs" id="dwarfs"> - <option>grumpy@woodworkers.com</option> - <option>happy@woodworkers.com</option> - <option>sleepy@woodworkers.com</option> - <option>bashful@woodworkers.com</option> - <option>sneezy@woodworkers.com</option> - <option>dopey@woodworkers.com</option> - <option>doc@woodworkers.com</option> - </select> - </p> - <p> - <label for="favoriteOnly">Select your favorite:</label> - <select name="favoriteOnly" id="favoriteOnly"> - <option>grumpy@woodworkers.com</option> - <option>happy@woodworkers.com</option> - <option>sleepy@woodworkers.com</option> - <option>bashful@woodworkers.com</option> - <option>sneezy@woodworkers.com</option> - <option>dopey@woodworkers.com</option> - <option>doc@woodworkers.com</option> - </select> - </p> - <p> - <input type="submit" value="Submit" /> - </p> -</form> -``` - -{{EmbedLiveSample("select", 600, 120) }} - -Note the difference in appearance between the two form controls. - -```css -/* uncomment this CSS to make the multiple the same height as the single */ - -/* -select[multiple] { - height: 1.5em; - vertical-align: top; -} -select[multiple]:focus, -select[multiple]:active { - height: auto; -} -*/ -``` - -There are a few ways to select multiple options in a `<select>` element with a `multiple` attribute. Depending on the operating system, mouse users can hold the <kbd>Ctrl</kbd>, <kbd>Command</kbd>, or <kbd>Shift</kbd> keys and then click multiple options to select/deselect them. Keyboard users can select multiple contiguous items by focusing on the `<select>` element, selecting an item at the top or bottom of the range they want to select using the <kbd>Up</kbd> and <kbd>Down</kbd> cursor keys to go up and down the options. The selection of non-contiguous is not as well-supported: items should be able to be selected and deselected by pressing <kbd>Space</kbd>, but support varies between browsers. - -## Specifications - -{{Specifications}} - -## Browser compatibility - -{{Compat}} - -## See also - -- {{htmlelement('input')}} -- {{htmlelement('select')}} -- [Allowing multiple email addresses](/en-US/docs/Web/HTML/Element/input/email#allowing_multiple_email_addresses) diff --git a/files/en-us/web/html/attributes/pattern/index.md b/files/en-us/web/html/attributes/pattern/index.md deleted file mode 100644 index 63fa531370022a7..000000000000000 --- a/files/en-us/web/html/attributes/pattern/index.md +++ /dev/null @@ -1,193 +0,0 @@ ---- -title: "HTML attribute: pattern" -short-title: pattern -slug: Web/HTML/Attributes/pattern -page-type: html-attribute -browser-compat: html.elements.input.pattern ---- - -{{HTMLSidebar}} - -The **`pattern`** attribute specifies a [regular expression](/en-US/docs/Web/JavaScript/Guide/Regular_expressions) the form control's value should match. If a non-`null` value doesn't conform to the constraints set by the `pattern` value, the {{domxref('ValidityState')}} object's read-only {{domxref('ValidityState.patternMismatch','patternMismatch')}} property will be true. - -{{InteractiveExample("HTML Demo: pattern", "tabbed-shorter")}} - -```html interactive-example -<label for="username">Username: (3-16 characters)</label> -<input - id="username" - name="username" - type="text" - value="Sasha" - pattern="\w{3,16}" - required /> - -<label for="pin">PIN: (4 digits)</label> -<input id="pin" name="pin" type="password" pattern="\d{4,4}" required /> -``` - -```css interactive-example -label { - display: block; - margin-top: 1em; -} - -input:valid { - background-color: palegreen; -} - -input:invalid { - background-color: lightpink; -} -``` - -## Overview - -The `pattern` attribute is an attribute of the {{HTMLElement("input/text", "text")}}, {{HTMLElement("input/tel", "tel")}}, {{HTMLElement("input/email", "email")}}, {{HTMLElement("input/url", "url")}}, {{HTMLElement("input/password", "password")}}, and {{HTMLElement("input/search", "search")}} input types. - -The `pattern` attribute, when specified, is a regular expression which the input's [`value`](/en-US/docs/Web/HTML/Element/input#value) must match for the value to pass [constraint validation](/en-US/docs/Web/HTML/Constraint_validation). It must be a valid JavaScript regular expression, as used by the {{jsxref("RegExp")}} type, and as documented in our [guide on regular expressions](/en-US/docs/Web/JavaScript/Guide/Regular_expressions). - -The pattern's regular expression is compiled with the [`'v'` flag](/en-US/docs/Web/JavaScript/Reference/Regular_expressions/Character_class#v-mode_character_class). This makes the regular expression [unicode-aware](/en-US/docs/Web/JavaScript/Reference/Global_Objects/RegExp/unicode#unicode-aware_mode), and also changes how character classes are interpreted. This allows character class set intersection and subtraction operations, and in addition to `]` and `\`, the following characters must be escaped using a `\` backslash if they represent literal characters: `(`, `)`, `[`, `{`, `}`, `/`, `-`, `|`. Before mid-2023, the `'u'` flag was specified instead; If you're updating older code, [this document outlines the differences](https://github.com/tc39/proposal-regexp-v-flag#how-is-the-v-flag-different-from-the-u-flag). - -The pattern's regular expression must match the entire input's `value`, rather than matching a substring - as if a `^(?:` were implied at the start of the pattern and `)$` at the end. - -No forward slashes should be specified around the pattern text. No regular expression is applied if the attribute value is absent, an empty string, or invalid. - -Some of the input types supporting the pattern attribute, notably the {{HTMLElement("input/email", "email")}} and {{HTMLElement("input/url", "url")}} input types, have expected value syntaxes that must be matched. If the pattern attribute isn't present, and the value doesn't match the expected syntax for that value type, the {{domxref('ValidityState')}} object's read-only {{domxref('ValidityState.typeMismatch','typeMismatch')}} property will be true. - -### Constraint validation - -If the input's value is not the empty string and the value does not match the entire regular expression, there is a constraint violation reported by the {{domxref('ValidityState')}} object's {{domxref('ValidityState.patternMismatch','patternMismatch')}} property being `true`. - -> [!NOTE] -> If the `pattern` attribute is specified with no value, its value is implicitly the empty string. Thus, **any non-empty** input `value` will result in constraint violation. - -### Usability and accessibility considerations - -When including a `pattern`, provide a description of the pattern in visible text near the control. Additionally, include a [`title`](/en-US/docs/Web/HTML/Element/input#title) attribute which gives a description of the pattern. User agents may use the title contents during constraint validation to tell the user that the pattern is not matched. Some browsers show a tooltip with title contents, improving usability for sighted users. Additionally, assistive technology may read the title aloud when the control gains focus, but this should not be relied upon for accessibility. - -Only relying on the `title` attribute for the visual display of text content is discouraged, as many user agents do not expose the attribute in an accessible manner. Although some browsers show a tooltip when an element with a title is hovered, that leaves out keyboard-only and touch-only users. This is one of the several reasons you must include information informing users how to fill out the control to match the requirements. - -While `title`s are used by some browsers to populate error messaging, because browsers sometimes also show the title as text on hover, it therefore shows in non-error situations, so be careful not to word titles as if an error has occurred. - -## Examples - -### Matching a phone number - -Given the following: - -```html -<p> - <label> - Enter your phone number in the format (123) - 456 - 7890 (<input - name="tel1" - type="tel" - pattern="[0-9]{3}" - placeholder="###" - aria-label="3-digit area code" - size="2" />) - - <input - name="tel2" - type="tel" - pattern="[0-9]{3}" - placeholder="###" - aria-label="3-digit prefix" - size="2" /> - - - <input - name="tel3" - type="tel" - pattern="[0-9]{4}" - placeholder="####" - aria-label="4-digit number" - size="3" /> - </label> -</p> -``` - -Here we have 3 sections for a north American phone number with an implicit label encompassing all three components of the phone number, expecting 3-digits, 3-digits and 4-digits respectively, as defined by the `pattern` attribute set on each. - -If the values are too long or too short, or contain characters that aren't digits, the `patternMismatch` will be true. When `true`, the element matches the {{cssxref(":invalid")}} CSS pseudo-classes. - -```css -input:invalid { - border: red solid 3px; -} -``` - -{{EmbedLiveSample("Matching_a_phone_number", 300, 80)}} - -If we had used [`minlength`](/en-US/docs/Web/HTML/Attributes/minlength) and [`maxlength`](/en-US/docs/Web/HTML/Attributes/maxlength) attributes instead, we may have seen {{domxref('validityState.tooLong')}} or {{domxref('validityState.tooShort')}} being true. - -### Specifying a pattern - -You can use the [`pattern`](/en-US/docs/Web/HTML/Element/input#pattern) attribute to specify a regular expression that the inputted value must match in order to be considered valid (see [Validating against a regular expression](/en-US/docs/Learn_web_development/Extensions/Forms/Form_validation#validating_against_a_regular_expression) for a crash course on using regular expressions to validate inputs). - -The example below restricts the value to 4-8 characters and requires that it contain only lower-case letters. - -```html -<form> - <div> - <label for="uname">Choose a username: </label> - <input - type="text" - id="uname" - name="name" - required - size="45" - pattern="[a-z]{4,8}" - title="4 to 8 lowercase letters" /> - <span class="validity"></span> - <p>Usernames must be lowercase and 4-8 characters in length.</p> - </div> - <div> - <button>Submit</button> - </div> -</form> -``` - -```css hidden -div { - margin-bottom: 10px; - position: relative; -} - -p { - font-size: 80%; - color: #999; -} - -input + span { - padding-right: 30px; -} - -input:invalid + span::after { - position: absolute; - content: "✖"; - padding-left: 5px; -} - -input:valid + span::after { - position: absolute; - content: "✓"; - padding-left: 5px; -} -``` - -This renders like so: - -{{ EmbedLiveSample('Specifying_a_pattern', 600, 110) }} - -## Specifications - -{{Specifications}} - -## Browser compatibility - -{{Compat}} - -## See also - -- [Constraint validation](/en-US/docs/Web/HTML/Constraint_validation) -- [Forms: Data form validation](/en-US/docs/Learn_web_development/Extensions/Forms/Form_validation) -- [Regular Expressions](/en-US/docs/Web/JavaScript/Guide/Regular_expressions) diff --git a/files/en-us/web/html/attributes/placeholder/index.md b/files/en-us/web/html/attributes/placeholder/index.md deleted file mode 100644 index a76a6758ae7f2cf..000000000000000 --- a/files/en-us/web/html/attributes/placeholder/index.md +++ /dev/null @@ -1,58 +0,0 @@ ---- -title: "HTML attribute: placeholder" -short-title: placeholder -slug: Web/HTML/Attributes/placeholder -page-type: html-attribute -browser-compat: - - html.elements.input.placeholder - - html.elements.textarea.placeholder ---- - -{{HTMLSidebar}} - -The **`placeholder`** attribute defines the text displayed in a form control when the control has no value. The placeholder text should provide a brief hint to the user as to the expected type of data that should be entered into the control. - -Effective placeholder text includes a word or short phrase that hints at the expected data type, not an explanation or prompt. The placeholder must not be used instead of a {{HTMLElement("label")}}. As the placeholder is not visible if the value of the form control is not null, using `placeholder` instead of a `<label>` for a prompt harms usability and accessibility. - -The `placeholder` attribute is supported by the following input types: `{{HTMLElement("input/text", "text")}}`, `{{HTMLElement("input/search", "search")}}`, `{{HTMLElement("input/url", "url")}}`, `{{HTMLElement("input/tel", "tel")}}`, `{{HTMLElement("input/email", "email")}}`, and `{{HTMLElement("input/password", "password")}}`. It is also supported by the `{{HTMLElement("textarea")}}` element. The [example](#example) below shows the `placeholder` attribute in use to explain the expected format of an input field. - -> [!NOTE] -> Except in `{{HTMLElement("textarea")}}` elements, the `placeholder` attribute can't include any line feeds (LF) or carriage returns (CR). If either is included in the value, the placeholder text will be clipped. - -## Accessibility concerns - -Placeholders should only be used to show an example of the type of data that should be entered into a form; never as a replacement for a `<label>` element; doing so harms accessibility and user experience. - -The `<label>` text is visually and programmatically associated with its corresponding form control. Screen readers don't announce placeholder content by default, but they do announce label content; it's the label that informs assistive technology users what data should be entered in the control. Labels also improve user experience for users of pointing devices: When a user clicks, touches, or taps a `<label>`, focus is moved to the label's associated form control. - -Placeholders can not be relied upon as a replacement for a label even for those not relying on assistive technology. Placeholder text is displayed at lower color contrast than the default form control text. This is by design, as you don't want users to be confused by what is placeholder text versus what is a filled-in form field. However, this lack of contrast can cause issues for low-vision users. Additionally, placeholder text disappears from form fields when users start entering text. If the placeholder text contains instructional information or examples that disappear, it can be confusing to users with cognitive issues and can make the form inaccessible if the placeholder contained the label. - -## Example - -### HTML - -```html -<form action="/en-US/docs/Web/HTML/Attributes/placeholder"> - <label for="name">Enter your name:</label> - <input type="text" id="name" name="name" placeholder="e.g. Mike Shinoda" /> - <button type="submit">Submit</button> -</form> -``` - -### Result - -{{EmbedLiveSample('Example', '150px', '150px')}} - -## Specifications - -{{Specifications}} - -## Browser compatibility - -{{Compat}} - -## See also - -- HTML [`title`](/en-US/docs/Web/HTML/Global_attributes/title) -- CSS [`:placeholder-shown`](/en-US/docs/Web/CSS/:placeholder-shown) pseudo-class selector -- CSS [`::placeholder`](/en-US/docs/Web/CSS/::placeholder) pseudo-element selector diff --git a/files/en-us/web/html/attributes/readonly/index.md b/files/en-us/web/html/attributes/readonly/index.md deleted file mode 100644 index d1c2cf65379a970..000000000000000 --- a/files/en-us/web/html/attributes/readonly/index.md +++ /dev/null @@ -1,115 +0,0 @@ ---- -title: "HTML attribute: readonly" -short-title: readonly -slug: Web/HTML/Attributes/readonly -page-type: html-attribute -browser-compat: - - html.elements.input.readonly - - html.elements.textarea.readonly ---- - -{{HTMLSidebar}} - -The Boolean **`readonly`** attribute, when present, makes the element not mutable, meaning the user can not edit the control. - -{{InteractiveExample("HTML Demo: readonly", "tabbed-shorter")}} - -```html interactive-example -<label for="firstName">First Name:</label> -<input id="firstName" name="firstName" type="text" value="Adam" /> - -<label for="age">Age:</label> -<input id="age" name="age" type="number" value="42" readonly /> - -<label for="hobbies">Hobbies:</label> -<textarea id="hobbies" name="hobbies" readonly>Baseball</textarea> -``` - -```css interactive-example -label { - display: block; - margin-top: 1em; -} - -input:read-only, -textarea:read-only { - background-color: silver; -} -``` - -## Overview - -If the `readonly` attribute is specified on an input element, because the user can not edit the input, the element does not participate in constraint validation. - -The `readonly` attribute is supported by `{{HTMLElement("input/text","text")}}`, `{{HTMLElement("input/search","search")}}`, `{{HTMLElement("input/url","url")}}`, `{{HTMLElement("input/tel","tel")}}`, `{{HTMLElement("input/email","email")}}`, `{{HTMLElement("input/password","password")}}`, `{{HTMLElement("input/date","date")}}`, `{{HTMLElement("input/month","month")}}`, `{{HTMLElement("input/week","week")}}`, `{{HTMLElement("input/time","time")}}`, `{{HTMLElement("input/datetime-local","datetime-local")}}`, and `{{HTMLElement("input/number","number")}}` {{HTMLElement("input")}} types and the {{HTMLElement("textarea")}} form control elements. If present on any of these input types and elements, the {{cssxref(':read-only')}} pseudo class will match. If the attribute is not included, the {{cssxref(':read-write')}} pseudo class will match. - -The attribute is not supported or relevant to {{HTMLElement("select")}} or input types that are already not mutable, such as `{{HTMLElement("input/checkbox","checkbox")}}` and `{{HTMLElement("input/radio","radio")}}` or cannot, by definition, start with a value, such as the `{{HTMLElement("input/file","file")}}` input type. `{{HTMLElement("input/range","range")}}` and `{{HTMLElement("input/color","color")}}`, as both have default values. It is also not supported on `{{HTMLElement("input/hidden","hidden")}}` as it can not be expected that a user to fill out a form that is hidden. Nor is it supported on any of the button types, including `image`. - -> [!NOTE] -> Only text controls can be made read-only, since for other controls (such as checkboxes and buttons) there is no useful distinction between being read-only and being disabled, so the `readonly` attribute does not apply. - -When an input has the `readonly` attribute, the {{cssxref(":read-only")}} pseudo-class also applies to it. Conversely, inputs that support the `readonly` attribute but don't have the attribute set match the {{cssxref(":read-write")}} pseudo-class. - -### Attribute interactions - -The difference between [`disabled`](/en-US/docs/Web/HTML/Attributes/disabled) and `readonly` is that read-only controls can still function and are still focusable, whereas disabled controls can not receive focus and are not submitted with the form and generally do not function as controls until they are enabled. - -Because a read-only field cannot have its value changed by a user interaction, [`required`](/en-US/docs/Web/HTML/Attributes/required) does not have any effect on inputs with the `readonly` attribute also specified. - -The only way to modify dynamically the value of the readonly attribute is through a script. - -> [!NOTE] -> The `required` attribute is not permitted on inputs with the `readonly` attribute specified. - -### Usability - -Browsers display the `readonly` attribute. - -### Constraint validation - -If the element is read-only, then the element's value can not be updated by the user, and does not participate in constraint validation. - -## Example - -### HTML - -```html -<div class="group"> - <input type="text" value="Some value" readonly="readonly" id="text" /> - <label for="text">Text box</label> -</div> -<div class="group"> - <input type="date" value="2020-01-01" readonly="readonly" id="date" /> - <label for="date">Date</label> -</div> -<div class="group"> - <input type="email" value="Some value" readonly="readonly" id="email" /> - <label for="email">Email</label> -</div> -<div class="group"> - <input type="password" value="Some value" readonly="readonly" id="pwd" /> - <label for="pwd">Password</label> -</div> -<div class="group"> - <textarea readonly="readonly" id="ta">Some value</textarea> - <label for="ta">Message</label> -</div> -``` - -### Result - -{{EmbedLiveSample('Example')}} - -## Specifications - -{{Specifications}} - -## Browser compatibility - -{{Compat}} - -## See also - -- {{cssxref(':read-only')}} and {{cssxref(':read-write')}} -- {{htmlelement('input')}} -- {{htmlelement('select')}} diff --git a/files/en-us/web/html/attributes/rel/alternate_stylesheet/index.md b/files/en-us/web/html/attributes/rel/alternate_stylesheet/index.md deleted file mode 100644 index d4e8995d01e4a5e..000000000000000 --- a/files/en-us/web/html/attributes/rel/alternate_stylesheet/index.md +++ /dev/null @@ -1,62 +0,0 @@ ---- -title: Alternate stylesheet -slug: Web/HTML/Attributes/rel/alternate_stylesheet -page-type: html-attribute-value -browser-compat: html.elements.link.rel.alternate_stylesheet ---- - -{{HTMLSidebar}} - -The **`alternate stylesheet`** keyword pair, when used as a value for the [`rel`](/en-US/docs/Web/HTML/Element/link#rel) attribute of the {{HTMLElement("link")}} element, indicates that the target resource is an _alternative style sheet_. Specifying **alternative style sheets** in a web page allows users to see multiple versions of a page based on their needs or preferences. - -> [!NOTE] -> This feature is not well supported in browsers without an extension. To offer alternative presentations that work with a user's existing preferences, see the CSS [media features](/en-US/docs/Web/CSS/@media#media_features) {{cssxref("@media/prefers-color-scheme","prefers-color-scheme")}} and {{cssxref("@media/prefers-contrast","prefers-contrast")}}. - -Firefox lets users select alternate {{glossary("stylesheet", "stylesheets")}} using the _View > Page Style_ submenu, which displays the values of the [`title`](/en-US/docs/Web/HTML/Global_attributes/title) attributes. Other browsers require an extension to enable this functionality. The web page can also provide its own user interface to let users switch styles. - -## Examples - -### Specifying alternate stylesheets - -Alternate stylesheets are specified using {{HTMLElement("link")}} elements with `rel="alternate stylesheet"` and `title="…"` attributes. For example: - -```html -<link href="reset.css" rel="stylesheet" /> - -<link href="default.css" rel="stylesheet" title="Default Style" /> -<link href="fancy.css" rel="alternate stylesheet" title="Fancy" /> -<link href="basic.css" rel="alternate stylesheet" title="Basic" /> -``` - -In this example, the styles "Default Style", "Fancy", and "Basic" will be listed in the Firefox _Page Style_ submenu with "Default Style" pre-selected. When the user selects a different style, the page will immediately be re-rendered using that style sheet. - -No matter what style is selected, the rules from the `reset.css` stylesheet will always be applied. - -### Try it out - -[Try a working example here](https://mdn.github.io/css-examples/alt-style-sheets/). - -## Details - -Any stylesheet in a document falls into one of the following categories: - -- **Persistent** (has `rel="stylesheet"`, no `title=""`): always applies to the document. -- **Preferred** (has `rel="stylesheet"`, with `title="…"` specified): applied by default, but {{domxref("StyleSheet.disabled", "disabled", "", 1)}} if an alternate stylesheet is selected. **There can only be one preferred stylesheet**, so providing stylesheets with different title attributes will cause some of them to be ignored. -- **Alternate** (`rel="alternate stylesheet"`, with `title="…"` specified): disabled by default, can be selected. - -In cases where a stylesheet menu exists, when style sheets are referenced with a `title` attribute on the {{HTMLElement("link", "&lt;link rel=\"stylesheet\"&gt;")}} or {{HTMLElement("style")}} element, the title becomes one of the choices offered to the user. Style sheets linked with the same [`title`](/en-US/docs/Web/HTML/Global_attributes/title) are part of the same choice. Style sheets linked without a `title` attribute are always applied. - -Use `rel="stylesheet"` to link to the default style, and `rel="alternate stylesheet"` to link to alternative style sheets. This tells the browser which style sheet title should be selected by default, and makes that default selection apply in browsers that do not support alternate style sheets. - -## Specifications - -{{Specifications}} - -## Browser compatibility - -{{Compat}} - -## See also - -- [CSS](/en-US/docs/Web/CSS) -- [Using dynamic styling information](/en-US/docs/Web/API/CSS_Object_Model/Using_dynamic_styling_information) diff --git a/files/en-us/web/html/attributes/rel/dns-prefetch/index.md b/files/en-us/web/html/attributes/rel/dns-prefetch/index.md deleted file mode 100644 index 3cea04cd628c4b2..000000000000000 --- a/files/en-us/web/html/attributes/rel/dns-prefetch/index.md +++ /dev/null @@ -1,24 +0,0 @@ ---- -title: rel=dns-prefetch -slug: Web/HTML/Attributes/rel/dns-prefetch -page-type: html-attribute-value -browser-compat: html.elements.link.rel.dns-prefetch ---- - -{{HTMLSidebar}} - -The **`dns-prefetch`** keyword for the [`rel`](/en-US/docs/Web/HTML/Element/link#rel) attribute of the {{HTMLElement("link")}} element is a hint to browsers that the user is likely to need resources from the target resource's origin, and therefore the browser can likely improve the user experience by preemptively performing DNS resolution for that origin. - -See [Using dns-prefetch](/en-US/docs/Web/Performance/Guides/dns-prefetch) for more details. - -## Specifications - -{{Specifications}} - -## Browser compatibility - -{{Compat}} - -## See also - -- [Speculative loading](/en-US/docs/Web/Performance/Guides/Speculative_loading) for a comparison of `<link rel="dns-prefetch">` and other similar performance improvement features. diff --git a/files/en-us/web/html/attributes/rel/index.md b/files/en-us/web/html/attributes/rel/index.md deleted file mode 100644 index 33eb0945c5b1a44..000000000000000 --- a/files/en-us/web/html/attributes/rel/index.md +++ /dev/null @@ -1,251 +0,0 @@ ---- -title: "HTML attribute: rel" -short-title: rel -slug: Web/HTML/Attributes/rel -page-type: html-attribute -browser-compat: - - html.elements.link.rel - - html.elements.a.rel - - html.elements.area.rel - - html.elements.form.rel ---- - -{{HTMLSidebar}} - -The **`rel`** attribute defines the relationship between a linked resource and the current document. Valid on {{htmlelement('link')}}, {{htmlelement('a')}}, {{htmlelement('area')}}, and {{htmlelement('form')}}, the supported values depend on the element on which the attribute is found. - -The type of relationships is given by the value of the `rel` attribute, which, if present, must have a value that is an unordered set of unique space-separated keywords. Differently from a `class` name, which does not express semantics, the `rel` attribute must express tokens that are semantically valid for both machines and humans. The current registries for the possible values of the `rel` attribute are the [IANA link relation registry](https://www.iana.org/assignments/link-relations/link-relations.xhtml), the [HTML Living Standard](https://html.spec.whatwg.org/multipage/links.html#linkTypes), and the freely-editable [existing-rel-values page](https://microformats.org/wiki/existing-rel-values) in the microformats wiki, [as suggested](https://html.spec.whatwg.org/multipage/links.html#other-link-types) by the Living Standard. If a `rel` attribute not present in one of the three sources above is used some HTML validators (such as the [W3C Markup Validation Service](https://validator.w3.org/)) will generate a warning. - -The following table lists some of the most important existing keywords. Every keyword within a space-separated value should be unique within that value. - -| `rel` value | Description | {{htmlelement('link')}} | {{htmlelement('a')}} and {{htmlelement('area')}} | {{htmlelement('form')}} | -| -------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------- | ------------------------------------------------ | ----------------------- | -| [`alternate`](#alternate) | Alternate representations of the current document. | Link | Link | Not allowed | -| [`author`](#author) | Author of the current document or article. | Link | Link | Not allowed | -| [`bookmark`](#bookmark) | Permalink for the nearest ancestor section. | Not allowed | Link | Not allowed | -| [`canonical`](#canonical) | Preferred URL for the current document. | Link | Not allowed | Not allowed | -| [`dns-prefetch`](/en-US/docs/Web/HTML/Attributes/rel/dns-prefetch) | Tells the browser to preemptively perform DNS resolution for the target resource's origin. | External Resource | Not allowed | Not allowed | -| [`external`](#external) | The referenced document is not part of the same site as the current document. | Not allowed | Annotation | Annotation | -| [`expect`](#expect) | Allows the page to be [render-blocked](/en-US/docs/Glossary/Render_blocking) until the essential parts of the document are parsed so it will render consistently. | Link | Not allowed | Not allowed | -| [`help`](#help) | Link to context-sensitive help. | Link | Link | Link | -| [`icon`](#icon) | An icon representing the current document. | External Resource | Not allowed | Not allowed | -| [`license`](#license) | Indicates that the main content of the current document is covered by the copyright license described by the referenced document. | Link | Link | Link | -| [`manifest`](/en-US/docs/Web/HTML/Attributes/rel/manifest) | Web app manifest. | Link | Not allowed | Not allowed | -| [`me`](/en-US/docs/Web/HTML/Attributes/rel/me) | Indicates that the current document represents the person who owns the linked content. | Link | Link | Not allowed | -| [`modulepreload`](/en-US/docs/Web/HTML/Attributes/rel/modulepreload) | Tells to browser to preemptively fetch the script and store it in the document's module map for later evaluation. Optionally, the module's dependencies can be fetched as well. | External Resource | Not allowed | Not allowed | -| [`next`](#next) | Indicates that the current document is a part of a series and that the next document in the series is the referenced document. | Link | Link | Link | -| [`nofollow`](#nofollow) | Indicates that the current document's original author or publisher does not endorse the referenced document. | Not allowed | Annotation | Annotation | -| [`noopener`](/en-US/docs/Web/HTML/Attributes/rel/noopener) | Creates a top-level browsing context that is not an auxiliary browsing context if the hyperlink would create either of those, to begin with (i.e., has an appropriate `target` attribute value). | Not allowed | Annotation | Annotation | -| [`noreferrer`](/en-US/docs/Web/HTML/Attributes/rel/noreferrer) | No `Referer` header will be included. Additionally, has the same effect as `noopener`. | Not allowed | Annotation | Annotation | -| [`opener`](#opener) | Creates an auxiliary browsing context if the hyperlink would otherwise create a top-level browsing context that is not an auxiliary browsing context (i.e., has `"_blank"` as `target` attribute value). | Not allowed | Annotation | Annotation | -| [`pingback`](#pingback) | Gives the address of the pingback server that handles pingbacks to the current document. | External Resource | Not allowed | Not allowed | -| [`preconnect`](/en-US/docs/Web/HTML/Attributes/rel/preconnect) | Specifies that the user agent should preemptively connect to the target resource's origin. | External Resource | Not allowed | Not allowed | -| [`prefetch`](/en-US/docs/Web/HTML/Attributes/rel/prefetch) | Specifies that the user agent should preemptively fetch and cache the target resource as it is likely to be required for a followup navigation. | External Resource | Not allowed | Not allowed | -| [`preload`](/en-US/docs/Web/HTML/Attributes/rel/preload) | Specifies that the user agent must preemptively fetch and cache the target resource for current navigation according to the potential destination given by the [`as`](/en-US/docs/Web/HTML/Element/link#as) attribute (and the priority associated with the corresponding destination). | External Resource | Not allowed | Not allowed | -| [`prerender`](/en-US/docs/Web/HTML/Attributes/rel/prerender) | Specifies that the user agent should preemptively fetch the target resource and process it in a way that helps deliver a faster response in the future. | External Resource | Not allowed | Not allowed | -| [`prev`](#prev) | Indicates that the current document is a part of a series and that the previous document in the series is the referenced document. | Link | Link | Link | -| [`privacy-policy`](#privacy-policy) | Gives a link to a information about the data collection and usage practices that apply to the current document. | Link | Link | Not allowed | -| [`search`](#search) | Gives a link to a resource that can be used to search through the current document and its related pages. | Link | Link | Link | -| [`stylesheet`](#stylesheet) | Imports a style sheet. | External Resource | Not allowed | Not allowed | -| [`tag`](#tag) | Gives a tag (identified by the given address) that applies to the current document. | Not allowed | Link | Not allowed | -| [`terms-of-service`](#terms-of-service) | Link to the agreement, or terms of service, between the document's provider and users who wish to use the document. | Link | Link | Not allowed | - -The `rel` attribute is relevant to the {{htmlelement('link')}}, {{htmlelement('a')}}, {{htmlelement('area')}}, and {{htmlelement('form')}} elements, but some values only relevant to a subset of those elements. Like all HTML keyword attribute values, these values are case-insensitive. - -The `rel` attribute has no default value. If the attribute is omitted or if none of the values in the attribute are supported, then the document has no particular relationship with the destination resource other than there being a hyperlink between the two. In this case, on {{htmlelement('link')}} and {{htmlelement('form')}}, if the `rel` attribute is absent, has no keywords, or if not one or more of the space-separated keywords above, then the element does not create any links. {{htmlelement('a')}} and {{htmlelement('area')}} will still created links, but without a defined relationship. - -## Values - -- `alternate` - - - : Indicates an alternate representation of the current document. Valid for {{htmlelement('link')}}, {{htmlelement('a')}}, and {{htmlelement('area')}}, the meaning depends on the values of the other attributes. - - - With the [`stylesheet`](#stylesheet) keyword on a `<link>`, it creates an [alternate stylesheet](/en-US/docs/Web/HTML/Attributes/rel/alternate_stylesheet). - - ```html - <!-- a persistent style sheet --> - <link rel="stylesheet" href="default.css" /> - <!-- alternate style sheets --> - <link - rel="alternate stylesheet" - href="highcontrast.css" - title="High contrast" /> - ``` - - - With an [`hreflang`](/en-US/docs/Web/HTML/Element/link#hreflang) attribute that differs from the document language, it indicates a translation. - - With the [`type`](/en-US/docs/Web/HTML/Element/link#type) attribute value of `"application/rss+xml"` or `"application/atom+xml"`, it creates a hyperlink referencing a syndication feed. - - ```html - <link - rel="alternate" - type="application/atom+xml" - href="posts.xml" - title="Blog" /> - ``` - - - Otherwise, it creates a hyperlink referencing an alternate representation of the current document, whose nature is given by the [`hreflang`](/en-US/docs/Web/HTML/Element/link#hreflang) and [`type`](/en-US/docs/Web/HTML/Element/link#type) attributes. - - - If `hreflang` is given alongside `alternate`, and the value of `hreflang` is different from the current document's language, it indicates that the referenced document is a translation. - - If `type` is given alongside `alternate`, it indicates that the referenced document is an alternative format (such as a PDF). - - The `hreflang` and `type` attributes may both be given alongside `alternate`. - - ```html - <link - rel="alternate" - href="/fr/html/print" - hreflang="fr" - type="text/html" - media="print" - title="French HTML (for printing)" /> - <link - rel="alternate" - href="/fr/pdf" - hreflang="fr" - type="application/pdf" - title="French PDF" /> - ``` - -- `author` - - - : Indicates the referenced document provides further information about the author of the current document or article. Relevant for {{htmlelement('link')}}, {{htmlelement('a')}}, and {{htmlelement('area')}} elements. - - With {{htmlelement('a')}} and {{htmlelement('area')}}, it indicates the linked document (or `mailto:`) provides information about the author of the nearest {{htmlelement('article')}} ancestor if there is one, otherwise the entire document. - - With {{htmlelement('link')}}, it represents the author of the entire document. - - > [!NOTE] - > For historical reasons, the obsolete attribute value `rev="made"` is treated as `rel="author"`. - -- `bookmark` - - : Relevant as the `rel` attribute value for the {{htmlelement('a')}} and {{htmlelement('area')}} elements. Gives a permalink for the nearest ancestor {{htmlelement('article')}} element, if there is one. If there is no ancestor `<article>` element, gives a permalink for the section the linking element is most closely associated with. -- `canonical` - - : Valid for {{htmlelement('link')}}, it defines the preferred URL for the current document, which helps search engines reduce duplicate content. -- `dns-prefetch` - - : Relevant for the {{htmlelement('link')}} element both in the {{htmlelement('body')}} and {{htmlelement('head')}}, it tells the browser to preemptively perform DNS resolution for the target resource's origin. Useful for resources the user will likely need, it helps reduce latency and thereby improves performance when the user does access the resources as the browser preemptively performed DNS resolution for the origin of the specified resource. See [dns-prefetch](/en-US/docs/Web/Performance/Guides/dns-prefetch) described in [resource hints](https://w3c.github.io/resource-hints/). -- `external` - - : Relevant to {{htmlelement('form')}}, {{htmlelement('a')}}, and {{htmlelement('area')}}, it indicates the referenced document is not part of the current site. This can be used with attribute selectors to style external links in a way that indicates to the user that they will be leaving the current site. -- `expect` {{experimental_inline}} - - - : Allows the page to be [render-blocked](/en-US/docs/Glossary/Render_blocking) until the essential parts of the document are parsed so it will render consistently. Note that render-blocking occurs only when supplemented with the [`blocking="render"`](/en-US/docs/Web/HTML/Element/link#blocking) attribute. - - > [!NOTE] - > See [Stabilizing page state to make cross-document transitions consistent](/en-US/docs/Web/API/View_Transition_API/Using#stabilizing_page_state_to_make_cross-document_transitions_consistent) for more information on its use. - -- `help` - - : Relevant to {{htmlelement('form')}}, {{htmlelement('link')}}, {{htmlelement('a')}}, and {{htmlelement('area')}}, the `help` keyword indicates that the linked to content provides context-sensitive help, providing information for the parent of the element defining the hyperlink, and its children. When used within `<link>`, the help is for the whole document. When included with {{htmlelement('a')}} and {{htmlelement('area')}} and supported, the default {{cssxref('cursor')}} will be `help` instead of `pointer`. -- `icon` - - - : Valid with {{htmlelement('link')}}, the linked resource represents the icon, a resource for representing the page in the user interface, for the current document. - - The most common use for the `icon` value is the favicon: - - ```html - <link rel="icon" href="favicon.ico" /> - ``` - - If there are multiple `<link rel="icon">`s, the browser uses their [`media`](/en-US/docs/Web/HTML/Element/link#media), [`type`](/en-US/docs/Web/HTML/Element/link#type), and [`sizes`](/en-US/docs/Web/HTML/Element/link#sizes) attributes to select the most appropriate icon. If several icons are equally appropriate, the last one is used. If the most appropriate icon is later found to be inappropriate, for example because it uses an unsupported format, the browser proceeds to the next-most appropriate, and so on. - - > [!NOTE] - > The [`crossorigin`](/en-US/docs/Web/HTML/Attributes/crossorigin) attribute is not supported for `rel="icon"` in Chromium-based browsers. See the [open Chromium issue](https://crbug.com/1121645). - - > [!NOTE] - > Apple's iOS does not use this link type, nor the [`sizes`](/en-US/docs/Web/HTML/Element/link#sizes) attribute, like others mobile browsers do, to select a webpage icon for Web Clip or a start-up placeholder. - > Instead it uses the non-standard [`apple-touch-icon`](https://developer.apple.com/library/archive/documentation/AppleApplications/Reference/SafariWebContent/ConfiguringWebApplications/ConfiguringWebApplications.html#//apple_ref/doc/uid/TP40002051-CH3-SW4) and [`apple-touch-startup-image`](https://developer.apple.com/library/archive/documentation/AppleApplications/Reference/SafariWebContent/ConfiguringWebApplications/ConfiguringWebApplications.html#//apple_ref/doc/uid/TP40002051-CH3-SW6) respectively. - - > [!NOTE] - > The `shortcut` link type is often seen before `icon`, but this link type is non-conforming, ignored and **web authors must not use it anymore**. - -- `license` - - - : Valid on the {{HTMLElement("a")}}, {{HTMLElement("area")}}, {{HTMLElement("form")}}, {{HTMLElement("link")}} elements, the `license` value indicates that the hyperlink leads to a document describing the licensing information; that the main content of the current document is covered by the copyright license described by the referenced document. If not inside the {{HTMLElement("head")}} element, the standard doesn't distinguish between a hyperlink applying to a specific part of the document or to the document as a whole. Only the data on the page can indicate this. - - ```html - <link rel="license" href="#license" /> - ``` - - > [!NOTE] - > Although recognized, the synonym `copyright` is incorrect and must be avoided. - -- `manifest` - - : [Web app manifest](/en-US/docs/Web/Progressive_web_apps/Manifest). Requires the use of the CORS protocol for cross-origin fetching. -- `modulepreload` - - : Useful for improved performance, and relevant to the {{htmlelement('link')}} anywhere in the document, setting `rel="modulepreload"` tells the browser to preemptively fetch the script (and dependencies) and store it in the document's module map for later evaluation. `modulepreload` links can ensure network fetching is done with the module ready (but not evaluated) in the module map before it is necessarily needed. See also [`modulepreload`](/en-US/docs/Web/HTML/Attributes/rel/modulepreload). -- `next` - - : Relevant to {{htmlelement('form')}}, {{htmlelement('link')}}, {{htmlelement('a')}}, and {{htmlelement('area')}}, the `next` values indicates that the current document is a part of a series, and that the next document in the series is the referenced document. When included in a `<link>`, browsers may assume that document will be fetched next, and treat it as a resource hint. -- `nofollow` - - : Relevant to {{htmlelement('form')}}, {{htmlelement('a')}}, and {{htmlelement('area')}}, the `nofollow` keyword tells search engine spiders to ignore the link relationship. The nofollow relationship may indicate the current document's owner does not endorse the referenced document. It is often included by Search Engine Optimizers pretending their link farms are not spam pages. -- `noopener` - - - : Relevant to {{htmlelement('form')}}, {{htmlelement('a')}}, and {{htmlelement('area')}}, creates a top-level browsing context that is not an auxiliary browsing context if the hyperlink would create either of those to begin with (i.e., has an appropriate `target` attribute value). In other words, it makes the link behave as if [`window.opener`](/en-US/docs/Web/API/Window/opener) were null and `target="_parent"` were set. - - This is the opposite of [`opener`](#opener). - -- `noreferrer` - - : Relevant to {{htmlelement('form')}}, {{htmlelement('a')}}, and {{htmlelement('area')}}, including this value makes the referrer unknown (no `Referer` header will be included), and creates a top-level browsing context as if `noopener` were also set. -- `opener` - - : Creates an auxiliary browsing context if the hyperlink would otherwise create a top-level browsing context that is not an auxiliary browsing context (i.e., has `"_blank"` as `target` attribute value). Effectively, the opposite of [noopener](#noopener). -- `pingback` - - : Gives the address of the pingback server that handles pingbacks to the current document. See the [Pingback specification](https://www.hixie.ch/specs/pingback/pingback). -- `preconnect` - - : Provides a hint to the browser suggesting that it open a connection to the linked website in advance, without disclosing any private information or downloading any content, so that when the link is followed the linked content can be fetched more quickly. -- `prefetch` - - : Specifies that the user agent should preemptively fetch and cache the target resource as it is likely to be required for a followup navigation. - See {{Glossary("prefetch")}} for more information. -- `preload` - - : Specifies that the user agent must preemptively fetch and cache the target resource for current navigation according to the potential destination given by the [`as`](/en-US/docs/Web/HTML/Element/link#as) attribute (and the priority associated with the corresponding destination). See the page for the [`preload`](/en-US/docs/Web/HTML/Attributes/rel/preload) value. -- `prerender` {{Deprecated_Inline}} {{Non-standard_Inline}} - - : Specifies that the user agent should preemptively fetch the target resource and process it in a way that helps deliver a faster response in the future, for example by fetching its subresources or performing some rendering. -- `prev` - - - : Similar to the [`next`](#next) keyword, relevant to {{htmlelement('form')}}, {{htmlelement('link')}}, {{htmlelement('a')}}, and {{htmlelement('area')}}, the `prev` values indicates that the current document is a part of a series, and that the link references a previous document in the series is the referenced document. - - Note: The synonym `previous` is incorrect and should not be used. - -- `privacy-policy` - - - : Valid for {{htmlelement('a')}}, {{htmlelement('area')}}, and {{htmlelement('link')}} elements, the `privacy-policy` value indicates that the referenced document is the Privacy Policy which describes the data collection and usage practices of the current document. - -- `search` - - - : Relevant to {{htmlelement('form')}}, {{htmlelement('link')}}, {{htmlelement('a')}}, and {{htmlelement('area')}} elements, the `search` keywords indicates that the hyperlink references a document whose interface is specially designed for searching in the current document, site, and related resources, providing a link to a resource that can be used to search. - - If the [`type`](/en-US/docs/Web/HTML/Element/link#type) attribute is set to `application/opensearchdescription+xml` the resource is an [OpenSearch](/en-US/docs/Web/XML/Guides/OpenSearch) plugin that can be easily added to the interface of Firefox. - -- `stylesheet` - - - : Valid for the {{htmlelement('link')}} element, it imports an external resource to be used as a stylesheet. The [`type`](/en-US/docs/Web/HTML/Element/link#type) attribute is not needed if it's a `text/css` stylesheet, as that is the default value. If it's not a stylesheet of type `text/css` it is best to declare the type. - - While this attribute defines the link as being a stylesheet, the interaction with other attributes and other key terms within the rel value impact whether the stylesheet is downloaded and/or used. - - When used with the [`alternate`](#alternate) keyword, it defines an alternative style sheet. In this case, include a non-empty [`title`](/en-US/docs/Web/HTML/Element/link#title). - - The external stylesheet will not be used or even downloaded if the media does not match the value of the [`media`](/en-US/docs/Web/HTML/Element/link#media) attribute. - - Requires the use of the CORS protocol for cross-origin fetching. - -- `tag` - - - : Valid for the {{htmlelement('a')}}, and {{htmlelement('area')}} elements, it gives a tag (identified by the given address) that applies to the current document. The tag value denotes that the link refers to a document describing a tag applying to the document on which it is located. This link type is not meant for tags within a tag cloud, as those tags apply to a group of pages, whereas the `tag` value of the `rel` attribute is for a single document. - -- `terms-of-service` - - - : Valid for {{htmlelement('a')}}, {{htmlelement('area')}}, and {{htmlelement('link')}} elements, the `terms-of-service` value indicates that the referenced document is the Terms of Service that describes the agreements between the current document's provider and users who wish to use the document provided. - -### Non-standard values - -- [`apple-touch-icon`](https://developer.apple.com/library/archive/documentation/AppleApplications/Reference/SafariWebContent/ConfiguringWebApplications/ConfiguringWebApplications.html#//apple_ref/doc/uid/TP40002051-CH3-SW4) - - : Specifies the icon for a web application on an iOS device. - -## Specifications - -{{Specifications}} - -## Browser compatibility - -{{Compat}} - -## See also - -- {{domxref("HTMLLinkElement.relList")}} -- {{domxref("HTMLAnchorElement.relList")}} -- {{domxref("HTMLAreaElement.relList")}} diff --git a/files/en-us/web/html/attributes/rel/manifest/index.md b/files/en-us/web/html/attributes/rel/manifest/index.md deleted file mode 100644 index 365634e77246c78..000000000000000 --- a/files/en-us/web/html/attributes/rel/manifest/index.md +++ /dev/null @@ -1,18 +0,0 @@ ---- -title: rel=manifest -slug: Web/HTML/Attributes/rel/manifest -page-type: html-attribute-value -browser-compat: html.elements.link.rel.manifest ---- - -{{HTMLSidebar}} - -The **`manifest`** keyword for the [`rel`](/en-US/docs/Web/HTML/Element/link#rel) attribute of the {{HTMLElement("link")}} element indicates that the target resource is a [Web app manifest](/en-US/docs/Web/Progressive_web_apps/Manifest). - -## Specifications - -{{Specifications}} - -## Browser compatibility - -{{Compat}} diff --git a/files/en-us/web/html/attributes/rel/me/index.md b/files/en-us/web/html/attributes/rel/me/index.md deleted file mode 100644 index e0a5ca5ef72ca4b..000000000000000 --- a/files/en-us/web/html/attributes/rel/me/index.md +++ /dev/null @@ -1,24 +0,0 @@ ---- -title: rel=me -slug: Web/HTML/Attributes/rel/me -page-type: html-attribute-value -browser-compat: html.elements.link.rel.me ---- - -{{HTMLSidebar}} - -The **`me`** keyword for the [`rel`](/en-US/docs/Web/HTML/Element/link#rel) attribute of the {{HTMLElement("link")}} and {{HTMLElement("a")}} elements indicates that the current resource is represented by the linked party. The `me` value was introduced in the [XHTML Friends Network (XFN) specification](https://gmpg.org/xfn/). - -```html -<link rel="me" href="example.com" /> -``` - -The `rel="me"` attribute is used in [RelMeAuth](https://microformats.org/wiki/RelMeAuth) and [Web sign in](https://microformats.org/wiki/web-sign-in) specifications as a way to enable a person to identify themselves to a web service using their domain name or a particular URL. - -## Specifications - -{{Specifications}} - -## Browser compatibility - -{{Compat}} diff --git a/files/en-us/web/html/attributes/rel/modulepreload/index.md b/files/en-us/web/html/attributes/rel/modulepreload/index.md deleted file mode 100644 index bfa717a1438bbf9..000000000000000 --- a/files/en-us/web/html/attributes/rel/modulepreload/index.md +++ /dev/null @@ -1,103 +0,0 @@ ---- -title: rel=modulepreload -slug: Web/HTML/Attributes/rel/modulepreload -page-type: html-attribute-value -browser-compat: html.elements.link.rel.modulepreload ---- - -{{HTMLSidebar}} - -The **`modulepreload`** keyword, for the [`rel`](/en-US/docs/Web/HTML/Attributes/rel) attribute of the {{HTMLElement("link")}} element, provides a declarative way to preemptively fetch a [module script](/en-US/docs/Web/JavaScript/Guide/Modules), parse and compile it, and store it in the document's module map for later execution. - -Preloading allows modules and their dependencies to be downloaded early, and can also significantly reduce the overall download and processing time. -This is because it allows pages to fetch modules in parallel, instead of sequentially as each module is processed and its dependencies are discovered. -Note however that you can't just preload everything! -What you choose to preload must be balanced against other operations that might then be starved, adversely affecting user experience. - -Links with `rel="modulepreload"` are similar to those with [`rel="preload"`](/en-US/docs/Web/HTML/Attributes/rel/preload). -The main difference is that `preload` just downloads the file and stores it in the cache, while `modulepreload` gets the module, parses and compiles it, and puts the results into the module map so that it is ready to execute. - -When using `modulepreload` the fetch request mode is always [`cors`](/en-US/docs/Web/API/Request/mode#cors), and the [`crossorigin`](/en-US/docs/Web/HTML/Attributes/crossorigin) property is used to determine the request [credential mode](/en-US/docs/Web/API/Request/credentials). -If `crossorigin` is set to [`anonymous`](/en-US/docs/Web/HTML/Attributes/crossorigin#anonymous) or [`""`](/en-US/docs/Web/HTML/Attributes/crossorigin#sect1) (default), then the credentials mode is [`same-origin`](/en-US/docs/Web/API/Request/credentials#same-origin), and user credentials such as cookies and authentication are only sent for requests with the `same-origin`. -If `crossorigin` is set to [`use-credentials`](/en-US/docs/Web/HTML/Attributes/crossorigin#use-credentials) then the credentials mode is [`include`](/en-US/docs/Web/API/Request/credentials#include), and user credentials for both single- and cross-origin requests. - -The [`as`](/en-US/docs/Web/HTML/Element/link#as) attribute is optional for links with `rel="modulepreload"`, and defaults to `"script"`. -It can be set to `"script"` or any script-like destination, such as `"audioworklet"`, `"paintworklet"`, `"serviceworker"`, `"sharedworker"`, or `"worker"`. -An [`Event`](/en-US/docs/Web/API/Event/Event) named "error" is fired on the element if any other destination is used. - -A browser _may_ additionally also choose to automatically fetch any dependencies of the module resource. -Note however that this is a browser-specific optimization — the only approach to ensure that all browsers will try to preload a module's dependencies is to individually specify them! -Further, the events named `load` or `error` fire immediately following success or failure of loading the _specified_ resources. -If dependencies are automatically fetched, no additional events are fired in the main thread (although you might monitor additional requests in a service worker or on the server). - -## Examples - -Consider the [basic-modules](https://github.com/mdn/js-examples/tree/main/module-examples/basic-modules) example ([live version](https://mdn.github.io/js-examples/module-examples/basic-modules/)), introduced in the [JavaScript modules](/en-US/docs/Web/JavaScript/Guide/Modules#basic_example_structure) guide. - -This has a file structure as shown below, consisting of the top level module `main.js`, which statically imports two dependency modules `modules/canvas.js` and `modules/square.js` using the [`import` statement](/en-US/docs/Web/JavaScript/Reference/Statements/import). - -```plain -index.html -main.js -modules/ - canvas.js - square.js -``` - -The HTML for the example below shows how `main.js` is fetched in a `<script>` element. -Only after `main.js` has loaded does the browser discover and fetch the two dependency modules. - -```html -<!doctype html> -<html lang="en-US"> - <head> - <meta charset="utf-8" /> - <title>Basic JavaScript module example</title> - <style> - canvas { - border: 1px solid black; - } - </style> - <script type="module" src="main.js"></script> - </head> - <body></body> -</html> -``` - -The HTML below updates the example to use `<link>` elements with `rel="modulepreload"` for the main file and each of the dependency modules. -This is much faster because the three modules all start downloading asynchronously and in parallel before they are needed. -By the time `main.js` has been parsed and its dependencies are known, they have already been fetched and downloaded. - -```html -<!doctype html> -<html lang="en-US"> - <head> - <meta charset="utf-8" /> - <title>Basic JavaScript module example</title> - <link rel="modulepreload" href="main.js" /> - <link rel="modulepreload" href="modules/canvas.js" /> - <link rel="modulepreload" href="modules/square.js" /> - <style> - canvas { - border: 1px solid black; - } - </style> - - <script type="module" src="main.js"></script> - </head> - <body></body> -</html> -``` - -## Specifications - -{{Specifications}} - -## Browser compatibility - -{{Compat}} - -## See also - -- [Speculative loading](/en-US/docs/Web/Performance/Guides/Speculative_loading) for a comparison of `<link rel="modulepreload">` and other similar performance improvement features. -- [Preloading modules](https://web.dev/articles/modulepreload) on web.dev diff --git a/files/en-us/web/html/attributes/rel/noopener/index.md b/files/en-us/web/html/attributes/rel/noopener/index.md deleted file mode 100644 index c5e7b56fd820ceb..000000000000000 --- a/files/en-us/web/html/attributes/rel/noopener/index.md +++ /dev/null @@ -1,27 +0,0 @@ ---- -title: rel=noopener -slug: Web/HTML/Attributes/rel/noopener -page-type: html-attribute-value -browser-compat: - - html.elements.a.rel.noopener - - html.elements.area.rel.noopener ---- - -{{HTMLSidebar}} - -The **`noopener`** keyword for the [`rel`](/en-US/docs/Web/HTML/Attributes/rel) attribute of the {{HTMLElement("a")}}, {{HTMLElement("area")}}, and {{HTMLElement("form")}} elements instructs the browser to navigate to the target resource without granting the new browsing context access to the document that opened it — by not setting the {{DOMxRef("Window.opener")}} property on the opened window (it returns `null`). - -This is especially useful when opening untrusted links, in order to ensure they cannot tamper with the originating document via the {{DOMxRef("Window.opener")}} property (see [About rel=noopener](https://mathiasbynens.github.io/rel-noopener/) for more details), while still providing the `Referer` HTTP header (unless `noreferrer` is used as well). - -Note that when `noopener` is used, nonempty target names other than `_top`, `_self`, and `_parent` are all treated like `_blank` in terms of deciding whether to open a new window/tab. - -> [!NOTE] -> Setting `target="_blank"` on `<a>`, `<area>` and `<form>` elements implicitly provides the same `rel` behavior as setting `rel="noopener"` which does not set `window.opener`. - -## Specifications - -{{Specifications}} - -## Browser compatibility - -{{Compat}} diff --git a/files/en-us/web/html/attributes/rel/noreferrer/index.md b/files/en-us/web/html/attributes/rel/noreferrer/index.md deleted file mode 100644 index 3cc86ad85979f34..000000000000000 --- a/files/en-us/web/html/attributes/rel/noreferrer/index.md +++ /dev/null @@ -1,20 +0,0 @@ ---- -title: rel=noreferrer -slug: Web/HTML/Attributes/rel/noreferrer -page-type: html-attribute-value -browser-compat: - - html.elements.a.rel.noreferrer - - html.elements.area.rel.noreferrer ---- - -{{HTMLSidebar}} - -The **`noreferrer`** keyword for the [`rel`](/en-US/docs/Web/HTML/Attributes/rel) attribute of the {{HTMLElement("a")}}, {{HTMLElement("area")}}, and {{HTMLElement("form")}} elements instructs the browser, when navigating to the target resource, to omit the {{HTTPHeader("Referer")}} header and otherwise leak no referrer information — and additionally to behave as if the [`noopener`](/en-US/docs/Web/HTML/Attributes/rel/noopener) keyword were also specified. - -## Specifications - -{{Specifications}} - -## Browser compatibility - -{{Compat}} diff --git a/files/en-us/web/html/attributes/rel/preconnect/index.md b/files/en-us/web/html/attributes/rel/preconnect/index.md deleted file mode 100644 index c30eed9e37adde0..000000000000000 --- a/files/en-us/web/html/attributes/rel/preconnect/index.md +++ /dev/null @@ -1,38 +0,0 @@ ---- -title: rel=preconnect -slug: Web/HTML/Attributes/rel/preconnect -page-type: html-attribute-value -browser-compat: html.elements.link.rel.preconnect ---- - -{{HTMLSidebar}} - -The **`preconnect`** keyword for the [`rel`](/en-US/docs/Web/HTML/Element/link#rel) attribute of the {{HTMLElement("link")}} element is a hint to browsers that the user is likely to need resources from the target resource's origin, and therefore the browser can likely improve the user experience by preemptively initiating a connection to that origin. Preconnecting speeds up future loads from a given origin by preemptively performing part or all of the handshake (DNS+TCP for HTTP, and DNS+TCP+TLS for HTTPS origins). - -`<link rel="preconnect">` will provide a benefit to any future cross-origin HTTP request, navigation or subresource. It has no benefit on same-origin requests because the connection is already open. - -If a page needs to make connections to many third-party domains, preconnecting them all can be counterproductive. The `<link rel="preconnect">` hint is best used for only the most critical connections. For the others, just use [`<link rel="dns-prefetch">`](/en-US/docs/Web/HTML/Attributes/rel/dns-prefetch) to save time on the first step — the DNS lookup. - -## Examples - -```html -<link rel="preconnect" href="https://example.com" /> -``` - -You can also implement preconnect as an HTTP [Link](/en-US/docs/Web/HTTP/Headers/Link) header, for example: - -```http -Link: <https://example.com>; rel="preconnect" -``` - -## Specifications - -{{Specifications}} - -## Browser compatibility - -{{Compat}} - -## See also - -- [Speculative loading](/en-US/docs/Web/Performance/Guides/Speculative_loading) for a comparison of `<link rel="preconnect">` and other similar performance improvement features. diff --git a/files/en-us/web/html/attributes/rel/prefetch/index.md b/files/en-us/web/html/attributes/rel/prefetch/index.md deleted file mode 100644 index 8c27a4496fb9a51..000000000000000 --- a/files/en-us/web/html/attributes/rel/prefetch/index.md +++ /dev/null @@ -1,61 +0,0 @@ ---- -title: rel=prefetch -slug: Web/HTML/Attributes/rel/prefetch -page-type: html-attribute-value -browser-compat: html.elements.link.rel.prefetch ---- - -{{HTMLSidebar}} - -The **`prefetch`** keyword for the [`rel`](/en-US/docs/Web/HTML/Element/link#rel) attribute of the {{HTMLElement("link")}} element provides a hint to browsers that the user is likely to need the target resource for future navigations, and therefore the browser can likely improve the user experience by preemptively fetching and caching the resource. `<link rel="prefetch">` is used for same-site navigation resources, or for subresources used by same-site pages. - -The result is kept in the HTTP cache on disk. Because of this it is useful for prefetching subresources, even if they are not used by the current page. You could also use it to prefetch the next document the user will likely visit on the site. However, as a result you need to be careful with headers — for example certain [Cache-Control](/en-US/docs/Web/HTTP/Headers/Cache-Control) headers could block prefetching (for example `no-cache` or `no-store`). - -> [!NOTE] -> Because of such limitations, you are advised to use the [Speculation Rules API](/en-US/docs/Web/API/Speculation_Rules_API) for document prefetches instead, where it is supported. - -`<link rel="prefetch">` is functionally equivalent to a {{domxref("Window/fetch", "fetch()")}} call with a `priority: "low"` option set on it, except that the former will generally have an even lower priority, and it will have a [`Sec-Purpose: prefetch`](/en-US/docs/Web/HTTP/Headers/Sec-Purpose) header set on the request. Note that in general browsers will give prefetch resources a lower priority than preload ones (e.g. requested via [`<link rel="preload">`](/en-US/docs/Web/HTML/Attributes/rel/preload)) — the current page is more important than the next. - -The fetch request for a `prefetch` operation results in an HTTP request that includes the HTTP header [`Sec-Purpose: prefetch`](/en-US/docs/Web/HTTP/Headers/Sec-Purpose). A server might use this header to change the cache timeouts for the resources, or perform other special handling. -The request will also include the {{HTTPHeader("Sec-Fetch-Dest")}} header with the value set to `empty`. - -The {{HTTPHeader("Accept")}} header in the request will match the value used for normal navigation requests. This allows the browser to find the matching cached resources following navigation. - -## Examples - -### Basic prefetch - -```js -<link rel="prefetch" href="main.js" /> -``` - -### Navigation and subresource prefetches - -Prefetching can be used to fetch both HTML and sub-resources for a possible next navigation. A common use case is to have a simple website landing page that fetches more "heavy-weight" resources used by the rest of the site. - -```html -<link rel="prefetch" href="/app/style.css" /> -<link rel="prefetch" href="/landing-page" /> -``` - -### The effects of cache partitioning - -Many browsers now implement some form of [cache partitioning](https://developer.chrome.com/blog/http-cache-partitioning), which makes `<link rel="prefetch">` useless for resources intended for use by different top-level sites. This includes the main document when navigating cross-site. So, for example, the following prefetch: - -```html -<link rel="prefetch" href="https://news.example/article" /> -``` - -Would not be accessible from `https://aggregator.example/`. - -## Specifications - -{{Specifications}} - -## Browser compatibility - -{{Compat}} - -## See also - -- [Speculative loading](/en-US/docs/Web/Performance/Guides/Speculative_loading) for a comparison of `<link rel="prefetch">` and other similar performance improvement features. diff --git a/files/en-us/web/html/attributes/rel/preload/index.md b/files/en-us/web/html/attributes/rel/preload/index.md deleted file mode 100644 index 7614d83ef5b776f..000000000000000 --- a/files/en-us/web/html/attributes/rel/preload/index.md +++ /dev/null @@ -1,223 +0,0 @@ ---- -title: rel=preload -slug: Web/HTML/Attributes/rel/preload -page-type: html-attribute-value -browser-compat: html.elements.link.rel.preload ---- - -{{HTMLSidebar}} - -The `preload` value of the {{htmlelement("link")}} element's [`rel`](/en-US/docs/Web/HTML/Element/link#rel) attribute lets you declare fetch requests in the -HTML's {{htmlelement("head")}}, specifying resources that your page will need very soon, which you want to start loading early in the page lifecycle, -before browsers' main rendering machinery kicks in. This ensures they are available earlier and are less likely to block the page's render, improving performance. Even though the name contains the term _load_, it doesn't load and execute the script but only schedules it to be downloaded and cached with a higher priority. - -## The basics - -You most commonly use `<link>` to load a CSS file to style your page with: - -```html -<link rel="stylesheet" href="styles/main.css" /> -``` - -Here however, we will use a `rel` value of `preload`, which turns `<link>` into a preloader for any resource we want. You will also need to specify: - -- The path to the resource in the [`href`](/en-US/docs/Web/HTML/Element/link#href) attribute. -- The type of resource in the [`as`](/en-US/docs/Web/HTML/Element/link#as) attribute. - -An example might look like this (see our [JS and CSS example source](https://github.com/mdn/html-examples/tree/main/link-rel-preload/js-and-css), and [also live](https://mdn.github.io/html-examples/link-rel-preload/js-and-css/)): - -```html -<head> - <meta charset="utf-8" /> - <title>JS and CSS preload example</title> - - <link rel="preload" href="style.css" as="style" /> - <link rel="preload" href="main.js" as="script" /> - - <link rel="stylesheet" href="style.css" /> -</head> - -<body> - <h1>bouncing balls</h1> - <canvas></canvas> - - <script src="main.js" defer></script> -</body> -``` - -Here we preload our CSS and JavaScript files so they will be available as soon as they are required for the rendering of the page later on. This example is trivial, as the browser probably discovers the `<link rel="stylesheet">` and `<script>` elements in the same chunk of HTML as the preloads, but the benefits can be seen much more clearly the later resources are discovered and the larger they are. For example: - -- Resources that are pointed to from inside CSS, like fonts or images. -- Resources that JavaScript can request, like imported scripts. - -`preload` has other advantages too. Using `as` to specify the type of content to be preloaded allows the browser to: - -- Store in the cache for future requests, reusing the resource if appropriate. -- Apply the correct [content security policy](/en-US/docs/Web/HTTP/CSP) to the resource. -- Set the correct {{HTTPHeader("Accept")}} request headers for it. - -### What types of content can be preloaded? - -Many content types can be preloaded. The possible `as` attribute values are: - -- `fetch`: Resource to be accessed by a fetch or XHR request, such as an ArrayBuffer, WebAssembly binary, or JSON file. -- `font`: Font file. -- `image`: Image file. -- `script`: JavaScript file. -- `style`: CSS stylesheet. -- `track`: WebVTT file. - -> **Note:** `font` and `fetch` preloading requires the `crossorigin` attribute to be set; see [CORS-enabled fetches](#cors-enabled_fetches) below. - -> [!NOTE] -> There's more detail about these values and the web features they expect to be consumed by in the HTML spec — see [Link type "preload"](https://html.spec.whatwg.org/#match-preload-type). Also note that the full list of values the `as` attribute can take is governed by the Fetch spec — see [request destinations](https://fetch.spec.whatwg.org/#concept-request-destination). - -## Including a MIME type - -`<link>` elements can accept a [`type`](/en-US/docs/Web/HTML/Element/link#type) attribute, which contains the MIME type of the resource the element points to. This is especially useful when preloading resources — the browser will use the `type` attribute value to work out if it supports that resource, and will only download it if so, ignoring it if not. - -```html -<head> - <meta charset="utf-8" /> - <title>Image preload example</title> - - <link rel="preload" href="flower.avif" as="image" type="image/avif" /> -</head> -<body> - <picture> - <source src="flower.avif" type="image/avif" /> - <source src="flower.webp" type="image/webp" /> - <img src="flower.jpg" /> - </picture> -</body> -``` - -The code in the example above causes the `image/avif` image to be preloaded only in supporting browsers — and for users who have `image/avif` support in their browsers, causes the `image/avif` image to actually be used (since it's the first {{htmlelement("source")}} specified). That makes the image download hopefully smaller for users who have `image/avif` support in their browsers. - -Note that for users whose browsers have both `image/avif` and `image/webp` support, if in that code a `<link rel="preload" href="flower.webp" as="image" type="image/webp">` element were also specified, then _both_ the `image/avif` and `image/webp` images would be preloaded — even though only one of them would actually be used. - -Therefore, specifying preloading for multiple types of the same resource is discouraged. Instead, the best practice is to specify preloading only for the type the majority of your users are likely to actually use. That's why the code in the example above doesn't specify preloading for the `image/webp` image. - -However, the lack of preloading doesn't prevent the `image/webp` image from actually being used by those who need it: for users whose browsers don't have `image/avif` support but do have `image/webp` support, the code in the example above does still cause the `image/webp` image to be used — but it does so without also causing it to also be preloaded unnecessarily for the majority of other users. - -## CORS-enabled fetches - -When preloading resources that are fetched with [CORS](/en-US/docs/Web/HTTP/CORS) enabled (e.g. [`fetch()`](/en-US/docs/Web/API/Window/fetch), [`XMLHttpRequest`](/en-US/docs/Web/API/XMLHttpRequest) or [fonts](/en-US/docs/Web/CSS/@font-face)), special care needs to be taken to setting the [`crossorigin`](/en-US/docs/Web/HTML/Element/link#crossorigin) attribute on your [`<link>`](/en-US/docs/Web/HTML/Element/link) element. The attribute needs to be set to match the resource's CORS and credentials mode, even when the fetch is not cross-origin. - -As mentioned above, one interesting case where this applies is font files. Because of various reasons, these have to be fetched using anonymous-mode CORS (see [Font fetching requirements](https://drafts.csswg.org/css-fonts/#font-fetching-requirements)). - -Let's use this case as an example. You can see the full [example source code on GitHub](https://github.com/mdn/html-examples/tree/main/link-rel-preload/fonts) ([also see it live](https://mdn.github.io/html-examples/link-rel-preload/fonts/)): - -```html -<head> - <meta charset="utf-8" /> - <title>Web font example</title> - - <link - rel="preload" - href="fonts/cicle_fina-webfont.woff2" - as="font" - type="font/woff2" - crossorigin /> - <link - rel="preload" - href="fonts/zantroke-webfont.woff2" - as="font" - type="font/woff2" - crossorigin /> - - <link href="style.css" rel="stylesheet" /> -</head> -<body> - … -</body> -``` - -Not only are we providing the MIME type hints in the `type` attributes, but we are also providing the `crossorigin` attribute to make sure the preload's CORS mode matches the eventual font resource request. - -## Including media - -One nice feature of `<link>` elements is their ability to accept [`media`](/en-US/docs/Web/HTML/Element/link#media) attributes. These can accept [media types](/en-US/docs/Web/CSS/@media#media_types) or full-blown [media queries](/en-US/docs/Web/CSS/CSS_media_queries/Using_media_queries), allowing you to do responsive preloading! - -Let's look at an example (see it on GitHub — [source code](https://github.com/mdn/html-examples/tree/main/link-rel-preload/media), [live example](https://mdn.github.io/html-examples/link-rel-preload/media/)): - -```html -<head> - <meta charset="utf-8" /> - <title>Responsive preload example</title> - - <link - rel="preload" - href="bg-image-narrow.png" - as="image" - media="(max-width: 600px)" /> - <link - rel="preload" - href="bg-image-wide.png" - as="image" - media="(min-width: 601px)" /> - - <link rel="stylesheet" href="main.css" /> -</head> -<body> - <header> - <h1>My site</h1> - </header> - - <script> - const mediaQueryList = window.matchMedia("(max-width: 600px)"); - const header = document.querySelector("header"); - - if (mediaQueryList.matches) { - header.style.backgroundImage = "url(bg-image-narrow.png)"; - } else { - header.style.backgroundImage = "url(bg-image-wide.png)"; - } - </script> -</body> -``` - -We include `media` attributes on our `<link>` elements so that a narrow image is preloaded if the user has a narrow viewport, and a wider image is loaded if they have a wide viewport. We use {{domxref("Window.matchMedia")}} / {{domxref("MediaQueryList")}} to do this (see [Testing media queries](/en-US/docs/Web/CSS/CSS_media_queries/Testing_media_queries) for more). - -This makes it much more likely that the font will be available for the page render, cutting down on FOUT (flash of unstyled text). - -This doesn't have to be limited to images, or even files of the same type — think big! You could perhaps preload and display a simplified SVG diagram if the user is on a narrow screen where bandwidth and CPU is potentially more limited, or preload a complex chunk of JavaScript then use it to render an interactive 3D model if the user's resources are more plentiful. - -## Scripting and preloads - -> [!NOTE] -> Use [`<link rel="modulepreload">`](/en-US/docs/Web/HTML/Attributes/rel/modulepreload) instead if you are working with [JavaScript modules](/en-US/docs/Web/JavaScript/Guide/Modules). - -Another nice thing about these preloads is that you can execute them with script. -For example, here we create a {{domxref("HTMLLinkElement")}} instance, then attach it to the DOM: - -```js -const preloadLink = document.createElement("link"); -preloadLink.href = "myscript.js"; -preloadLink.rel = "preload"; -preloadLink.as = "script"; -document.head.appendChild(preloadLink); -``` - -This means that the browser will preload the `myscript.js` file, but not actually use it yet. To use it, you could do this: - -```js -const preloadedScript = document.createElement("script"); -preloadedScript.src = "myscript.js"; -document.body.appendChild(preloadedScript); -``` - -This is useful when you want to preload a script, but then defer execution until exactly when you need it. - -## Specifications - -{{Specifications}} - -## Browser compatibility - -{{Compat}} - -## See also - -- [Speculative loading](/en-US/docs/Web/Performance/Guides/Speculative_loading) for a comparison of `<link rel="preload">` and other similar performance improvement features. -- [Preload: What Is It Good For?](https://www.smashingmagazine.com/2016/02/preload-what-is-it-good-for/) by Yoav Weiss diff --git a/files/en-us/web/html/attributes/rel/prerender/index.md b/files/en-us/web/html/attributes/rel/prerender/index.md deleted file mode 100644 index 0937646fbbb0dcb..000000000000000 --- a/files/en-us/web/html/attributes/rel/prerender/index.md +++ /dev/null @@ -1,27 +0,0 @@ ---- -title: rel=prerender -slug: Web/HTML/Attributes/rel/prerender -page-type: html-attribute-value -status: - - deprecated - - non-standard -browser-compat: html.elements.link.rel.prerender ---- - -{{HTMLSidebar}}{{Deprecated_Header}}{{Non-standard_header}} - -The **`prerender`** keyword for the [`rel`](/en-US/docs/Web/HTML/Element/link#rel) attribute of the {{HTMLElement("link")}} element is a hint to browsers that the user might need the target resource for the next navigation, and therefore the browser can likely improve the user experience by preemptively fetching and processing the resource — for example, by fetching its subresources or performing some rendering in the background offscreen. - -This feature is superseded by the [Speculation Rules API](/en-US/docs/Web/API/Speculation_Rules_API). - -## Specifications - -{{Specifications}} - -## Browser compatibility - -{{Compat}} - -## See also - -- [Speculative loading](/en-US/docs/Web/Performance/Guides/Speculative_loading) for a comparison of `<link rel="prerender">` and other similar performance improvement features. diff --git a/files/en-us/web/html/attributes/required/index.md b/files/en-us/web/html/attributes/required/index.md deleted file mode 100644 index 3532c75c091b78b..000000000000000 --- a/files/en-us/web/html/attributes/required/index.md +++ /dev/null @@ -1,78 +0,0 @@ ---- -title: "HTML attribute: required" -short-title: required -slug: Web/HTML/Attributes/required -page-type: html-attribute -browser-compat: - - html.elements.input.required - - html.elements.select.required - - html.elements.textarea.required ---- - -{{HTMLSidebar}} - -The [Boolean](/en-US/docs/Glossary/Boolean/HTML) **`required`** attribute, if present, indicates that the user must specify a value for the input before the owning form can be submitted. - -The `required` attribute is supported by `{{HTMLElement("input/text","text")}}`, `{{HTMLElement("input/search","search")}}`, `{{HTMLElement("input/url","url")}}`, `{{HTMLElement("input/tel","tel")}}`, `{{HTMLElement("input/email","email")}}`, `{{HTMLElement("input/password","password")}}`, `{{HTMLElement("input/date","date")}}`, `{{HTMLElement("input/month","month")}}`, `{{HTMLElement("input/week","week")}}`, `{{HTMLElement("input/time","time")}}`, `{{HTMLElement("input/datetime-local","datetime-local")}}`, `{{HTMLElement("input/number","number")}}`, `{{HTMLElement("input/checkbox","checkbox")}}`, `{{HTMLElement("input/radio","radio")}}`, `{{HTMLElement("input/file","file")}}`, {{HTMLElement("input")}} types along with the {{HTMLElement("select")}} and {{HTMLElement("textarea")}} form control elements. If present on any of these input types and elements, the {{cssxref(':required')}} pseudo class will match. If the attribute is not included, the {{cssxref(':optional')}} pseudo class will match. - -The attribute is not supported on, or relevant to, {{HTMLElement("input/range","range")}} and {{HTMLElement("input/color","color")}} input types, as both have default values. Type `color` defaults to `#000000`. Type `range` defaults to the midpoint between `min` and `max` — with `min` and `max` defaulting to 0 and 100 respectively in most browsers if not declared. `required` is also not supported on the {{HTMLElement("input/hidden","hidden")}} input type — users cannot be expected to fill out a hidden form field. Finally, `required` is not supported on any button input types, including {{HTMLElement("input/image","image")}}. - -In the case of a same named group of {{HTMLElement("input/radio","radio")}} buttons, if a single radio button in the group has the `required` attribute, a radio button in that group must be checked, although it doesn't have to be the one on which the attribute is applied. To improve code maintenance, it is recommended to either include the `required` attribute in every same-named radio button in the group, or else in none. - -In the case of a same named group of {{HTMLElement("input/checkbox","checkbox")}} input types, only the checkboxes with the `required` attribute are required. - -> [!NOTE] -> Setting [`aria-required="true"`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-required) tells a screen reader that an element (any element) is required, but has no bearing on the optionality of the element. - -### Attribute interactions - -Because a read-only field cannot be changed, `required` does not have any effect on inputs with the [`readonly`](/en-US/docs/Web/HTML/Attributes/readonly) attribute also specified. - -### Usability - -When including the `required` attribute, provide a visible indication near the control informing the user that the {{HTMLElement("input")}}, {{HTMLElement("select")}} or {{HTMLElement("textarea")}} is required. In addition, target required form controls with the {{cssxref(':required')}} pseudo-class, styling them in a way to indicate they are required. This improves usability for sighted users. Assistive technology should inform the user that the form control is mandatory based on the required attribute, but adding `aria-required="true"` doesn't hurt, in case the browser / screen reader combination does not support `required` yet. - -### Constraint validation - -If the element is required and the element's value is the empty string, then the element is suffering from {{domxref('ValidityState.valueMissing','valueMissing')}} and the element will match the {{cssxref(':invalid')}} pseudo class. - -## Accessibility concerns - -Provide an indication to users informing them the form control is required. Ensure the messaging is multi-faceted, such as through text, color, markings, and attribute, so that all users understand the requirements whether they have color blindness, cognitive differences, or are using a screen reader. - -## Example - -### HTML - -```html -<form> - <div class="group"> - <input type="text" /> - <label>Normal</label> - </div> - <div class="group"> - <input type="text" required /> - <label>Required</label> - </div> - <input type="submit" /> -</form> -``` - -### Result - -{{EmbedLiveSample('Example')}} - -## Specifications - -{{Specifications}} - -## Browser compatibility - -{{Compat}} - -## See also - -- {{domxref('validityState.valueMissing')}} -- {{cssxref(':required')}} and {{cssxref(':optional')}} -- {{htmlelement('input')}} -- {{htmlelement('select')}} diff --git a/files/en-us/web/html/attributes/size/index.md b/files/en-us/web/html/attributes/size/index.md deleted file mode 100644 index f4ff0ea3038d3a0..000000000000000 --- a/files/en-us/web/html/attributes/size/index.md +++ /dev/null @@ -1,84 +0,0 @@ ---- -title: "HTML attribute: size" -short-title: size -slug: Web/HTML/Attributes/size -page-type: html-attribute -browser-compat: - - html.elements.select.size - - html.elements.input.size ---- - -{{HTMLSidebar}} - -The **`size`** attribute defines the width of the {{htmlelement('input')}} and the height of the {{htmlelement('select')}} element. For an `input` element, it defines the number of characters that the user agent allows the user to see when editing the value. For a `select` element, it defines the number of options that should be shown to the user. This must be a valid non-negative integer greater than zero. - -If no `size` is specified, or an invalid value is specified, the input has no size declared, and the form control will be the default width based on the user agent. If CSS targets the element with properties impacting the width, CSS takes precedence. - -The `size` attribute has no impact on constraint validation. - -{{InteractiveExample("HTML Demo: size", "tabbed-standard")}} - -```html interactive-example -<label for="firstName">First Name:</label> -<input id="firstName" name="firstName" type="text" size="10" /> - -<label for="lastName">Last Name:</label> -<input id="lastName" name="lastName" type="text" size="20" /> - -<label for="fruit">Favorite fruit:</label> -<select id="fruit" name="fruit" size="2"> - <option>Orange</option> - <option>Banana</option> - <option>Apple</option> -</select> -``` - -```css interactive-example -label { - display: block; - margin-top: 1rem; -} -``` - -## Examples - -By adding `size` on some input types, the width of the input can be controlled. Adding size on a select changes the height, defining how many options are visible in the closed state. - -```html -<label for="fruit">Enter a fruit</label> -<input type="text" size="15" id="fruit" /> -<label for="vegetable">Enter a vegetable</label> -<input type="text" id="vegetable" /> - -<select name="fruits" size="5"> - <option>banana</option> - <option>cherry</option> - <option>strawberry</option> - <option>durian</option> - <option>blueberry</option> -</select> - -<select name="vegetables" size="5"> - <option>carrot</option> - <option>cucumber</option> - <option>cauliflower</option> - <option>celery</option> - <option>collard greens</option> -</select> -``` - -{{EmbedLiveSample('Examples', '100%', 200)}} - -## Specifications - -{{Specifications}} - -## Browser compatibility - -{{Compat}} - -## See also - -- [`maxlength`](/en-US/docs/Web/HTML/Attributes/maxlength) -- [`minlength`](/en-US/docs/Web/HTML/Attributes/minlength) -- [`pattern`](/en-US/docs/Web/HTML/Attributes/pattern) diff --git a/files/en-us/web/html/attributes/step/index.md b/files/en-us/web/html/attributes/step/index.md deleted file mode 100644 index 9f13c3607cf31d1..000000000000000 --- a/files/en-us/web/html/attributes/step/index.md +++ /dev/null @@ -1,139 +0,0 @@ ---- -title: "HTML attribute: step" -short-title: step -slug: Web/HTML/Attributes/step -page-type: html-attribute -browser-compat: html.elements.input.step ---- - -{{HTMLSidebar}} - -The **`step`** attribute is a number that specifies the granularity that the value must adhere to or the keyword `any`. It is valid for the numeric input types, including the {{HTMLElement("input/date", "date")}}, {{HTMLElement("input/month", "month")}}, {{HTMLElement("input/week", "week")}}, {{HTMLElement("input/time", "time")}}, {{HTMLElement("input/datetime-local", "datetime-local")}}, {{HTMLElement("input/number", "number")}} and {{HTMLElement("input/range", "range")}} types. - -The `step` sets the _stepping interval_ when clicking up and down spinner buttons, moving a slider left and right on a range, and validating the different date types. If not explicitly included, `step` defaults to 1 for `number` and `range`, and 1 unit type (minute, week, month, day) for the date/time input types. The value must be a positive number - integer or float — or the special value `any`, which means no stepping is implied and any value is allowed (barring other constraints, such as [`min`](/en-US/docs/Web/HTML/Attributes/min) and [`max`](/en-US/docs/Web/HTML/Attributes/max)). - -The default stepping value for `number` inputs is 1, allowing only integers to be entered, _unless_ the stepping base is not an integer. The default stepping value for `time` is 60 seconds, with 900 being equal to 15 minutes. - -## Syntax - -<table class="no-markdown"> - <caption> - Default values for step - </caption> - <thead> - <tr> - <th>Input type</th> - <th>Value</th> - <th>Example</th> - </tr> - </thead> - <tbody> - <tr> - <td>{{HTMLElement("input/date", "date")}}</td> - <td>1 (day)</td> - <td><code>&#x3C;input type="date" min="2019-12-25" step="1"></code></td> - </tr> - <tr> - <td>{{HTMLElement("input/month", "month")}}</td> - <td>1 (month)</td> - <td><code>&#x3C;input type="month" min="2019-12" step="12"></code></td> - </tr> - <tr> - <td>{{HTMLElement("input/week", "week")}}</td> - <td>1 (week)</td> - <td><code>&#x3C;input type="week" min="2019-W23" step="2"></code></td> - </tr> - <tr> - <td>{{HTMLElement("input/time", "time")}}</td> - <td>60 (seconds)</td> - <td><code>&#x3C;input type="time" min="09:00" step="900"></code></td> - </tr> - <tr> - <td> - {{HTMLElement("input/datetime-local", "datetime-local")}} - </td> - <td>60 (seconds)</td> - <td> - <code - >&#x3C;input type="datetime-local" min="2019-12-25T19:30" - step="900"></code - > - </td> - </tr> - <tr> - <td>{{HTMLElement("input/number", "number")}}</td> - <td>1</td> - <td> - <code>&#x3C;input type="number" min="0" step="0.1" max="10"></code> - </td> - </tr> - <tr> - <td>{{HTMLElement("input/range", "range")}}</td> - <td>1</td> - <td><code>&#x3C;input type="range" min="0" step="2" max="10"></code></td> - </tr> - </tbody> -</table> - -If `any` is not explicitly set, valid values for the `number`, date/time input types, and `range` input types are equal to the basis for stepping - the [`min`](/en-US/docs/Web/HTML/Attributes/min) value and increments of the step value, up to the [`max`](/en-US/docs/Web/HTML/Attributes/max) value, if specified. The following example results in any even integer, 10 or greater, being valid: - -```html -<input type="number" min="10" step="2" /> -``` - -If `step` is omitted, any integer is valid but floats like 4.2 are not valid as `step` defaults to 1. For 4.2 to be valid: - -- either `step` would have to be set to `any`, 0.1, or 0.2, -- or the `min` value would have to be a number ending in .2, such as 0.2, 1.2, or -5.2. - -## Examples - -### `min` impact on step - -The value of `min` defines valid values, even if the `step` attribute is not included. This is because `step` defaults to `1` for the `number` input type. - -In this example, we add a big red border around invalid inputs: - -```css -input:invalid { - border: solid red 3px; -} -``` - -We then define an input with a minimum value of 1.2 and a step value of 2: - -```html -<input id="myNumber" name="myNumber" type="number" step="2" min="1.2" /> -``` - -Valid values include 1.2, 3.2, 5.2, 7.2, 9.2, 11.2, and so on. Only floats with an odd-numbered integer part and a decimal part of .2 are valid. The number spinner, if present, generates valid float values of 1.2 and greater, in increments of 2. - -{{EmbedLiveSample("min_impact_on_step","100%",55)}} - -> [!NOTE] -> When the data entered by the user doesn't adhere to the stepping configuration, the value is considered invalid in constraint validation and will match the {{cssxref(":invalid")}} and {{cssxref(":out-of-range")}} pseudoclasses. - -See [Client-side validation](/en-US/docs/Web/HTML/Constraint_validation) and {{domxref("ValidityState.stepMismatch", "stepMismatch")}} for more information. - -## Accessibility concerns - -Provide instructions to help users understand how to complete the form and use individual form controls. Indicate any required and optional input, data formats, and other relevant information. When using the `min` attribute, ensure this minimum requirement is understood by the user. Providing instructions within the {{htmlelement('label')}} may be sufficient. If providing instructions outside of labels, which allows more flexible positioning and design, consider using [`aria-labelledby`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-labelledby) or [`aria-describedby`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-describedby). - -## Specifications - -{{Specifications}} - -## Browser compatibility - -{{Compat}} - -## See also - -- [`max`](/en-US/docs/Web/HTML/Attributes/max) -- [`min`](/en-US/docs/Web/HTML/Attributes/min) -- [Constraint validation](/en-US/docs/Web/HTML/Constraint_validation) -- [Form validation](/en-US/docs/Learn_web_development/Extensions/Forms/Form_validation) -- {{domxref('validityState.stepMismatch')}} -- {{cssxref(':out-of-range')}} -- {{htmlelement('input')}} -- {{HTMLElement("input/date", "date")}}, {{HTMLElement("input/month", "month")}}, {{HTMLElement("input/week", "week")}}, {{HTMLElement("input/time", "time")}}, {{HTMLElement("input/datetime-local", "datetime-local")}}, {{HTMLElement("input/number", "number")}} and {{HTMLElement("input/range", "range")}} types, and the {{htmlelement('meter')}} diff --git a/files/en-us/web/html/comments/index.md b/files/en-us/web/html/comments/index.md deleted file mode 100644 index 9d0df869efafc50..000000000000000 --- a/files/en-us/web/html/comments/index.md +++ /dev/null @@ -1,71 +0,0 @@ ---- -title: HTML Comments (<!-- … -->) -short-title: Comments -slug: Web/HTML/Comments -page-type: guide -spec-urls: https://html.spec.whatwg.org/multipage/syntax.html#comments ---- - -{{HTMLSidebar}} - -An HTML **comment** is used to add explanatory notes to the markup or to prevent the browser from interpreting specific parts of the document. - -Comments start with the string `<!--` and end with the string `-->`, generally with text in between. This text cannot start with the string `>` or `->`, cannot contain the strings `-->` or `--!>`, nor end with the string `<!-`, though `<!` is allowed. - -The browser ignores comments as it renders the code. In other words, they are not visible on the page - just in the code. HTML comments are a way for you to write helpful notes about your code or logic. - -The above is true for [XML](/en-US/docs/Web/XML) comments as well. In addition, in XML, such as in [SVG](/en-US/docs/Web/SVG) or [MathML](/en-US/docs/Web/MathML) markup, a comment cannot contain the character sequence `--`. - -Comments can be used on a single line, or span multiple lines. They can be used in the following places: - -- Before and after the {{Glossary("Doctype")}} -- Before and after the {{HTMLElement("html")}} element -- As the content of most elements except: {{HTMLElement("script")}}, {{HTMLElement("style")}}, {{HTMLElement("title")}}, {{HTMLElement("textarea")}}, because these elements interpret their content as raw text - -> [!NOTE] -> While `<script>` elements should not have HTML comments and should use [JavaScript comments](/en-US/docs/Web/JavaScript/Reference/Lexical_grammar#comments) instead, there was a legacy practice to enclose the whole script content in an HTML comment so ancient browsers that don't support JavaScript don't render it as text. This is now a [legacy feature of JavaScript itself](/en-US/docs/Web/JavaScript/Reference/Deprecated_and_obsolete_features#html_comments) and you should not rely on it. - -## Syntax - -```html -<!-- Comment --> -``` - -## Examples - -```html -<!-- A one-line comment --> - -<!-- -A comment -that stretches -over several -lines ---> - -<!-- The comment below disables - the HTML contained within --> -<!-- -<p> - This content will not be rendered. -</p> ---> -``` - -## Notes - -HTML comments are only permitted as content. You cannot use it within a tag, such as before an HTML [attribute](/en-US/docs/Glossary/Attribute). - -As with most programming languages that use the `<!-- -->` comment syntax, comments cannot be nested. In other words, the first instance of `-->` that follows an instance of `<!--` closes the comment. - -While comments do start with a `<` and end in a `>`, a comment is not an HTML element. - -## Specifications - -{{Specifications}} - -## See also - -- [Comments in JavaScript](/en-US/docs/Web/JavaScript/Reference/Lexical_grammar#comments) -- [Comments in CSS](/en-US/docs/Web/CSS/CSS_syntax/Comments) -- {{domxref("Comment")}} API (`Comment` inherits from {{domxref("Node")}}) diff --git a/files/en-us/web/html/constraint_validation/index.md b/files/en-us/web/html/constraint_validation/index.md deleted file mode 100644 index 249146e21dd73c8..000000000000000 --- a/files/en-us/web/html/constraint_validation/index.md +++ /dev/null @@ -1,454 +0,0 @@ ---- -title: Constraint validation -slug: Web/HTML/Constraint_validation -page-type: guide ---- - -{{HTMLSidebar}} - -The creation of web forms has always been a complex task. While marking up the form itself is easy, checking whether each field has a valid and coherent value is more difficult, and informing the user about the problem may become a headache. [HTML5](/en-US/docs/Glossary/HTML5) introduced new mechanisms for forms: it added new semantic types for the {{ HTMLElement("input") }} element and _constraint validation_ to ease the work of checking the form content on the client side. Basic, usual constraints can be checked, without the need for JavaScript, by setting new attributes; more complex constraints can be tested using the Constraint Validation API. - -For a basic introduction to these concepts, with examples, see the [Form validation tutorial](/en-US/docs/Learn_web_development/Extensions/Forms/Form_validation). - -> [!NOTE] -> HTML Constraint validation doesn't remove the need for validation on the _server side_. Even though far fewer invalid form requests are to be expected, invalid ones can still be sent in many ways: -> -> - By modifying HTML via the browser's developer tools. -> - By hand-crafting an HTTP request without using the form. -> - By programmatically writing content into the form (certain constraint validations are _only run_ for user input, and not if you set the value of a form field using JavaScript). -> -> Therefore, you should always validate form data on the server side, consistent with what is done on the client side. - -## Intrinsic and basic constraints - -In HTML, basic constraints are declared in two ways: - -- By choosing the most semantically appropriate value for the [`type`](/en-US/docs/Web/HTML/Element/input#type) attribute of the {{ HTMLElement("input") }} element, e.g., choosing the `email` type automatically creates a constraint that checks whether the value is a valid email address. -- By setting values on validation-related attributes, allowing basic constraints to be described without the need for JavaScript. - -### Semantic input types - -The intrinsic constraints for the [`type`](/en-US/docs/Web/HTML/Element/input#type) attribute are: - -| Input type | Constraint description | Associated violation | -| ------------------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------- | -| [`<input type="URL">`](/en-US/docs/Web/HTML/Element/input/url) | The value must be an absolute [URL](/en-US/docs/Learn_web_development/Howto/Web_mechanics/What_is_a_URL), as defined in the [URL Living Standard](https://url.spec.whatwg.org/). | **[TypeMismatch](/en-US/docs/Web/API/ValidityState/typeMismatch)** constraint violation | -| [`<input type="email">`](/en-US/docs/Web/HTML/Element/input/email) | The value must be a syntactically valid email address, which generally has the format `username@hostname.tld` but can also be local such as `username@hostname`. | **[TypeMismatch](/en-US/docs/Web/API/ValidityState/typeMismatch)** constraint violation | - -For both of these input types, if the [`multiple`](/en-US/docs/Web/HTML/Element/input#multiple) attribute is set, several values can be set, as a comma-separated list. If any of these do not satisfy the condition described here, the **Type mismatch** constraint violation is triggered. - -Note that most input types don't have intrinsic constraints, as some are barred from constraint validation or have a sanitization algorithm transforming incorrect values to a correct default. - -### Validation-related attributes - -In addition to the `type` attribute described above, the following attributes are used to describe basic constraints: - -<table class="standard-table"> - <thead> - <tr> - <th scope="col">Attribute</th> - <th scope="col">Input types supporting the attribute</th> - <th scope="col">Possible values</th> - <th scope="col">Constraint description</th> - <th scope="col">Associated violation</th> - </tr> - </thead> - <tbody> - <tr> - <td> - <code - ><a href="/en-US/docs/Web/HTML/Attributes/pattern">pattern</a></code - > - </td> - <td> - <code>text</code>, <code>search</code>, <code>url</code>, - <code>tel</code>, <code>email</code>, <code>password</code> - </td> - <td> - A - <a href="/en-US/docs/Web/JavaScript/Guide/Regular_expressions" - >JavaScript regular expression</a - > - (compiled with the {{jsxref("RegExp.global", "global")}}, {{jsxref("RegExp.ignoreCase", "ignoreCase")}}, and - {{jsxref("RegExp.multiline", "multiline")}} flags <em>disabled</em>) - </td> - <td>The value must match the pattern.</td> - <td> - <a href="/en-US/docs/Web/API/ValidityState/patternMismatch" - ><strong><code>patternMismatch</code></strong></a - > - constraint violation - </td> - </tr> - <tr> - <td rowspan="3"> - <code><a href="/en-US/docs/Web/HTML/Attributes/min">min</a></code> - </td> - <td><code>range</code>, <code>number</code></td> - <td>A valid number</td> - <td rowspan="3">The value must be greater than or equal to the value.</td> - <td rowspan="3"> - <strong - ><code - ><a href="/en-US/docs/Web/API/ValidityState/rangeUnderflow" - >rangeUnderflow</a - ></code - ></strong - > - constraint violation - </td> - </tr> - <tr> - <td><code>date</code>, <code>month</code>, <code>week</code></td> - <td>A valid date</td> - </tr> - <tr> - <td> - <code>datetime-local</code>, <code>time</code> - </td> - <td>A valid date and time</td> - </tr> - <tr> - <td rowspan="3"> - <code><a href="/en-US/docs/Web/HTML/Attributes/max">max</a></code> - </td> - <td><code>range</code>, <code>number</code></td> - <td>A valid number</td> - <td rowspan="3">The value must be less than or equal to the value</td> - <td rowspan="3"> - <strong - ><code - ><a href="/en-US/docs/Web/API/ValidityState/rangeOverflow" - >rangeOverflow</a - ></code - ></strong - > - constraint violation - </td> - </tr> - <tr> - <td><code>date</code>, <code>month</code>, <code>week</code></td> - <td>A valid date</td> - </tr> - <tr> - <td> - <code>datetime-local</code>, <code>time</code> - </td> - <td>A valid date and time</td> - </tr> - <tr> - <td> - <code - ><a href="/en-US/docs/Web/HTML/Attributes/required">required</a></code - > - </td> - <td> - <code>text</code>, <code>search</code>, <code>url</code>, - <code>tel</code>, <code>email</code>, <code>password</code>, - <code>date</code>, <code>datetime-local</code>, - <code>month</code>, <code>week</code>, <code>time</code>, - <code>number</code>, <code>checkbox</code>, <code>radio</code>, - <code>file</code>; also on the {{ HTMLElement("select") }} and - {{ HTMLElement("textarea") }} elements - </td> - <td> - <em>none</em> as it is a Boolean attribute: its presence means - <em>true</em>, its absence means <em>false</em> - </td> - <td>There must be a value (if set).</td> - <td> - <strong - ><code - ><a href="/en-US/docs/Web/API/ValidityState/valueMissing" - >valueMissing</a - ></code - ></strong - > - constraint violation - </td> - </tr> - <tr> - <td rowspan="5"> - <code><a href="/en-US/docs/Web/HTML/Attributes/step">step</a></code> - </td> - <td><code>date</code></td> - <td>An integer number of days</td> - <td rowspan="5"> - Unless the step is set to the <code>any</code> literal, the value must - be <strong>min</strong> + an integral multiple of the step. - </td> - <td rowspan="5"> - <strong - ><code - ><a href="/en-US/docs/Web/API/ValidityState/stepMismatch" - >stepMismatch</a - ></code - ></strong - > - constraint violation - </td> - </tr> - <tr> - <td><code>month</code></td> - <td>An integer number of months</td> - </tr> - <tr> - <td><code>week</code></td> - <td>An integer number of weeks</td> - </tr> - <tr> - <td> - <code>datetime-local</code>, <code>time</code> - </td> - <td>An integer number of seconds</td> - </tr> - <tr> - <td><code>range</code>, <code>number</code></td> - <td>An integer</td> - </tr> - <tr> - <td> - <code - ><a href="/en-US/docs/Web/HTML/Attributes/minlength" - >minlength</a - ></code - > - </td> - <td> - <code>text</code>, <code>search</code>, <code>url</code>, - <code>tel</code>, <code>email</code>, <code>password</code>; also on the - {{ HTMLElement("textarea") }} element - </td> - <td>An integer length</td> - <td> - The number of characters (code points) must not be less than the value - of the attribute, if non-empty. All newlines are normalized to a single - character (as opposed to CRLF pairs) for - {{ HTMLElement("textarea") }}. - </td> - <td> - <strong - ><code - ><a href="/en-US/docs/Web/API/ValidityState/tooShort" - >tooShort</a - ></code - ></strong - > - constraint violation - </td> - </tr> - <tr> - <td> - <code - ><a href="/en-US/docs/Web/HTML/Attributes/maxlength" - >maxlength</a - ></code - > - </td> - <td> - <code>text</code>, <code>search</code>, <code>url</code>, - <code>tel</code>, <code>email</code>, <code>password</code>; also on the - {{ HTMLElement("textarea") }} element - </td> - <td>An integer length</td> - <td> - The number of characters (code points) must not exceed the value of the - attribute. - </td> - <td> - <strong - ><code - ><a href="/en-US/docs/Web/API/ValidityState/tooLong" - >tooLong</a - ></code - ></strong - > - constraint violation - </td> - </tr> - </tbody> -</table> - -## Constraint validation process - -Constraint validation is done through the Constraint Validation API either on a single form element or at the form level, on the {{ HTMLElement("form") }} element itself. The constraint validation is done in the following ways: - -- By a call to the `checkValidity()` or `reportValidity()` method of a form-associated DOM interface, ([`HTMLInputElement`](/en-US/docs/Web/API/HTMLInputElement), [`HTMLSelectElement`](/en-US/docs/Web/API/HTMLSelectElement), [`HTMLButtonElement`](/en-US/docs/Web/API/HTMLButtonElement), [`HTMLOutputElement`](/en-US/docs/Web/API/HTMLOutputElement) or [`HTMLTextAreaElement`](/en-US/docs/Web/API/HTMLTextAreaElement)), which evaluates the constraints only on this element, allowing a script to get this information. The `checkValidity()` method returns a Boolean indicating whether the element's value passes its constraints. (This is typically done by the user-agent when determining which of the CSS pseudo-classes, {{ Cssxref(":valid") }} or {{ Cssxref(":invalid") }}, applies.) In contrast, the `reportValidity()` method reports any constraint failures to the user. -- By a call to the `checkValidity()` or `reportValidity()` method on the [`HTMLFormElement`](/en-US/docs/Web/API/HTMLFormElement) interface. -- By submitting the form itself. - -Calling `checkValidity()` is called _statically_ validating the constraints, while calling `reportValidity()` or submitting the form is called _interactively_ validating the constraints. - -> [!NOTE] -> -> - If the [`novalidate`](/en-US/docs/Web/HTML/Element/form#novalidate) attribute is set on the {{ HTMLElement("form") }} element, interactive validation of the constraints doesn't happen. -> - Calling the `submit()` method on the [`HTMLFormElement`](/en-US/docs/Web/API/HTMLFormElement) interface doesn't trigger a constraint validation. In other words, this method sends the form data to the server even if it doesn't satisfy the constraints. Call the `click()` method on a submit button instead. -> - The `minlength` and `maxlength` constraints are only checked on user-provided input. They are not checked if a value is set programmatically, even when explicitly calling `checkValidity()` or `reportValidity()`. - -## Complex constraints using the Constraint Validation API - -Using JavaScript and the Constraint API, it is possible to implement more complex constraints, for example, constraints combining several fields, or constraints involving complex calculations. - -Basically, the idea is to trigger JavaScript on some form field event (like **onchange**) to calculate whether the constraint is violated, and then to use the method `field.setCustomValidity()` to set the result of the validation: an empty string means the constraint is satisfied, and any other string means there is an error and this string is the error message to display to the user. - -### Constraint combining several fields: Postal code validation - -The postal code format varies from one country to another. Not only do most countries allow an optional prefix with the country code (like `D-` in Germany, `F-` in France or Switzerland), but some countries have postal codes with only a fixed number of digits; others, like the UK, have more complex structures, allowing letters at some specific positions. - -> [!NOTE] -> This is not a comprehensive postal code validation library, but rather a demonstration of the key concepts. - -As an example, we will add a script checking the constraint validation for a form: - -```html -<form> - <label for="postal-code">Postal Code: </label> - <input type="text" id="postal-code" /> - <label for="country">Country: </label> - <select id="country"> - <option value="ch">Switzerland</option> - <option value="fr">France</option> - <option value="de">Germany</option> - <option value="nl">The Netherlands</option> - </select> - <input type="submit" value="Validate" /> -</form> -``` - -This displays the following form: - -{{EmbedLiveSample("Constraint_combining_several_fields_Postal_code_validation")}} - -First, we write a function checking the constraint itself: - -```js -function checkPostalCode() { - // For each country, defines the pattern that the postal code has to follow - const constraints = { - ch: [ - "^(CH-)?\\d{4}$", - "Swiss postal codes must have exactly 4 digits: e.g. CH-1950 or 1950", - ], - fr: [ - "^(F-)?\\d{5}$", - "French postal codes must have exactly 5 digits: e.g. F-75012 or 75012", - ], - de: [ - "^(D-)?\\d{5}$", - "German postal codes must have exactly 5 digits: e.g. D-12345 or 12345", - ], - nl: [ - "^(NL-)?\\d{4}\\s*([A-RT-Z][A-Z]|S[BCE-RT-Z])$", - "Dutch postal codes must have exactly 4 digits, followed by 2 letters except SA, SD and SS", - ], - }; - - // Read the country id - const country = document.getElementById("country").value; - - // Get the NPA field - const postalCodeField = document.getElementById("postal-code"); - - // Build the constraint checker - const constraint = new RegExp(constraints[country][0], ""); - console.log(constraint); - - // Check it! - if (constraint.test(postalCodeField.value)) { - // The postal code follows the constraint, we use the ConstraintAPI to tell it - postalCodeField.setCustomValidity(""); - } else { - // The postal code doesn't follow the constraint, we use the ConstraintAPI to - // give a message about the format required for this country - postalCodeField.setCustomValidity(constraints[country][1]); - } -} -``` - -Then we link it to the **onchange** event for the {{ HTMLElement("select") }} and the **oninput** event for the {{ HTMLElement("input") }}: - -```js -window.onload = () => { - document.getElementById("country").onchange = checkPostalCode; - document.getElementById("postal-code").oninput = checkPostalCode; -}; -``` - -### Limiting the size of a file before its upload - -Another common constraint is to limit the size of a file to be uploaded. Checking this on the client side before the file is transmitted to the server requires combining the Constraint Validation API, and especially the `field.setCustomValidity()` method, with another JavaScript API, here the File API. - -Here is the HTML part: - -```html -<label for="fs">Select a file smaller than 75 kB: </label> -<input type="file" id="fs" /> -``` - -This displays: - -{{EmbedLiveSample("Limiting_the_size_of_a_file_before_its_upload")}} - -The JavaScript reads the file selected, uses the `File.size()` method to get its size, compares it to the (hard coded) limit, and calls the Constraint API to inform the browser if there is a violation: - -```js -function checkFileSize() { - const fs = document.getElementById("fs"); - const files = fs.files; - - // If there is (at least) one file selected - if (files.length > 0) { - if (files[0].size > 75 * 1000) { - // Check the constraint - fs.setCustomValidity("The selected file must not be larger than 75 kB"); - fs.reportValidity(); - return; - } - } - // No custom constraint violation - fs.setCustomValidity(""); -} -``` - -Finally, we hook the method with the correct event: - -```js -window.onload = () => { - document.getElementById("fs").onchange = checkFileSize; -}; -``` - -## Visual styling of constraint validation - -Apart from setting constraints, web developers want to control what messages are displayed to the users and how they are styled. - -### Controlling the look of elements - -The look of elements can be controlled via CSS pseudo-classes. - -#### :required and :optional CSS pseudo-classes - -The {{cssxref(':required')}} and {{cssxref(':optional')}} [pseudo-classes](/en-US/docs/Web/CSS/Pseudo-classes) allow writing selectors that match form elements that have the [`required`](/en-US/docs/Web/HTML/Element/input#required) attribute, or that don't have it. - -#### :placeholder-shown CSS pseudo-class - -See {{cssxref(':placeholder-shown')}}. - -#### :valid :invalid CSS pseudo-classes - -The {{cssxref(':valid')}} and {{cssxref(':invalid')}} [pseudo-classes](/en-US/docs/Web/CSS/Pseudo-classes) are used to represent \<input> elements whose content validates and fails to validate respectively according to the input's type setting. These classes allow the user to style valid or invalid form elements to make it easier to identify elements that are either formatted correctly or incorrectly. - -### Controlling the text of constraint violation - -The following items can help with controlling the text of a constraint violation: - -- The `setCustomValidity(message)` method on the following elements: - - - {{HTMLElement("fieldset")}}. Note: Setting a custom validity message on fieldset elements will not prevent form submission in most browsers. - - {{HTMLElement("input")}} - - {{HTMLElement("output")}} - - {{HTMLElement("select")}} - - Submit buttons (created with either a {{HTMLElement("button")}} element with the `submit` type, or an `input` element with the {{HTMLElement("input/submit", "submit")}} type. Other types of buttons do not participate in constraint validation. - - {{HTMLElement("textarea")}} - -- The [`ValidityState`](/en-US/docs/Web/API/ValidityState) interface describes the object returned by the `validity` property of the element types listed above. It represents various ways that an entered value can be invalid. Together, they help explain why an element's value fails to validate, if it's not valid. diff --git a/files/en-us/web/html/content_categories/index.md b/files/en-us/web/html/content_categories/index.md deleted file mode 100644 index 978d660d142ab69..000000000000000 --- a/files/en-us/web/html/content_categories/index.md +++ /dev/null @@ -1,406 +0,0 @@ ---- -title: Content categories -slug: Web/HTML/Content_categories -page-type: guide ---- - -{{HTMLSidebar}} - -Most [HTML](/en-US/docs/Web/HTML) elements are a member of one or more **content categories** — these categories group elements that share common characteristics. This is a loose grouping (it doesn't actually create a relationship among elements of these categories), but they help define and describe the categories' shared behavior and their associated rules, especially when you come upon their intricate details. It's also possible for elements to not be a member of _any_ of these categories. - -There are three types of content categories: - -- Main content categories, which describe common rules shared by many elements. -- Form-related content categories, which describe rules common to form-related elements. -- Specific content categories, which describe rare categories shared only by a few elements, sometimes only in a specific context. - -> [!NOTE] -> A more detailed discussion of these content categories and their comparative functionalities is beyond the scope of this article; for that, you may wish to read the [relevant portions of the HTML specification](https://html.spec.whatwg.org/multipage/dom.html#kinds-of-content). - -![A Venn diagram showing how the various content categories interrelate. The following sections explain these relationships in text.](content_categories_venn.png) - -## Main content categories - -### Metadata content - -Elements belonging to the _metadata content_ category modify the presentation or the behavior of the rest of the document, set up links to other documents, or convey other _out-of-band_ information. Everything in the {{htmlelement("head")}}, including the `<title>`, `<link>`, `<script>`, `<style>`, and the lesser used `<base>`, is metadata content. There is a `<meta>` element for metadata that cannot be represented by these other elements. - -The metadata elements are: - -- {{HTMLElement("base")}} -- {{HTMLElement("link")}} -- {{HTMLElement("meta")}} -- {{HTMLElement("noscript")}} -- {{HTMLElement("script")}} -- {{HTMLElement("style")}} -- {{HTMLElement("title")}} - -Some of these elements belong to more than one content category. For example, `<script>` is a member of the metadata, flow, and phrasing content categories, and is a script-supporting element; `<script>` can be used where metadata content, phrasing content, or script-supporting elements are expected. - -### Flow content - -Flow content is a broad category that encompasses most elements that can go inside the {{HTMLElement("body")}} element, including heading elements, sectioning elements, phrasing elements, embedding elements, interactive elements, and form-related elements. It also includes text nodes (but not those that only consist of white space characters). - -The flow elements are: - -- {{HTMLElement("a")}} -- {{HTMLElement("abbr")}} -- {{HTMLElement("address")}} -- {{HTMLElement("article")}} -- {{HTMLElement("aside")}} -- {{HTMLElement("audio")}} -- {{HTMLElement("b")}} -- {{HTMLElement("bdo")}} -- {{HTMLElement("bdi")}} -- {{HTMLElement("blockquote")}} -- {{HTMLElement("br")}} -- {{HTMLElement("button")}} -- {{HTMLElement("canvas")}} -- {{HTMLElement("cite")}} -- {{HTMLElement("code")}} -- {{HTMLElement("data")}} -- {{HTMLElement("datalist")}} -- {{HTMLElement("del")}} -- {{HTMLElement("details")}} -- {{HTMLElement("dfn")}} -- {{HTMLElement("dialog")}} -- {{HTMLElement("div")}} -- {{HTMLElement("dl")}} -- {{HTMLElement("em")}} -- {{HTMLElement("embed")}} -- {{HTMLElement("fieldset")}} -- {{HTMLElement("figure")}} -- {{HTMLElement("footer")}} -- {{HTMLElement("form")}} -- {{HTMLElement("Heading_Elements", "<code>&lt;h1&gt;</code>-<code>&lt;h6&gt;</code>")}} -- {{HTMLElement("header")}} -- {{HTMLElement("hgroup")}} -- {{HTMLElement("hr")}} -- {{HTMLElement("i")}} -- {{HTMLElement("iframe")}} -- {{HTMLElement("img")}} -- {{HTMLElement("input")}} -- {{HTMLElement("ins")}} -- {{HTMLElement("kbd")}} -- {{HTMLElement("label")}} -- {{HTMLElement("main")}} -- {{HTMLElement("map")}} -- {{HTMLElement("mark")}} -- {{MathMLElement("math")}} -- {{HTMLElement("menu")}} -- {{HTMLElement("meter")}} -- {{HTMLElement("nav")}} -- {{HTMLElement("noscript")}} -- {{HTMLElement("object")}} -- {{HTMLElement("ol")}} -- {{HTMLElement("output")}} -- {{HTMLElement("p")}} -- {{HTMLElement("picture")}} -- {{HTMLElement("pre")}} -- {{HTMLElement("progress")}} -- {{HTMLElement("q")}} -- {{HTMLElement("ruby")}} -- {{HTMLElement("s")}} -- {{HTMLElement("samp")}} -- {{HTMLElement("search")}} -- {{HTMLElement("script")}} -- {{HTMLElement("section")}} -- {{HTMLElement("select")}} -- {{HTMLElement("slot")}} -- {{HTMLElement("small")}} -- {{HTMLElement("span")}} -- {{HTMLElement("strong")}} -- {{HTMLElement("sub")}} -- {{HTMLElement("sup")}} -- {{SVGElement("svg")}} -- {{HTMLElement("table")}} -- {{HTMLElement("template")}} -- {{HTMLElement("textarea")}} -- {{HTMLElement("time")}} -- {{HTMLElement("u")}} -- {{HTMLElement("ul")}} -- {{HTMLElement("var")}} -- {{HTMLElement("video")}} -- {{HTMLElement("wbr")}} -- plain text - -A few other elements belong to this category, but only if a specific condition is fulfilled: - -- {{HTMLElement("area")}}, if it is a descendant of a {{HTMLElement("map")}} element -- {{HTMLElement("link")}}, if the [itemprop](/en-US/docs/Web/HTML/Global_attributes/itemprop) attribute is present -- {{HTMLElement("meta")}}, if the [itemprop](/en-US/docs/Web/HTML/Global_attributes/itemprop) attribute is present - -### Sectioning content - -Sectioning content, a subset of flow content, creates a [section in the current outline](/en-US/docs/Web/HTML/Element/Heading_Elements) defining the scope of {{HTMLElement("header")}} and {{HTMLElement("footer")}} elements. - -The sectioning elements are: - -- {{HTMLElement("article")}} -- {{HTMLElement("aside")}} -- {{HTMLElement("nav")}} -- {{HTMLElement("section")}} - -### Heading content - -Heading content, a subset of flow content, defines the title of a section. This definition applies both to sections marked by an explicit [sectioning content](#sectioning_content) elements and to those implicitly defined by the heading content itself. - -The heading elements are: - -- {{HTMLElement("Heading_Elements", "<code>&lt;h1&gt;</code>-<code>&lt;h6&gt;</code>")}} -- {{HTMLElement("hgroup")}} - -> [!NOTE] -> Though likely to contain heading content, the {{HTMLElement("header")}} is not heading content itself. - -### Phrasing content - -Phrasing content, a subset of flow content, refers to the text and the markup within a document. Sequences of phrasing content make up paragraphs. - -The phrasing elements are: - -- {{HTMLElement("abbr")}} -- {{HTMLElement("audio")}} -- {{HTMLElement("b")}} -- {{HTMLElement("bdi")}} -- {{HTMLElement("bdo")}} -- {{HTMLElement("br")}} -- {{HTMLElement("button")}} -- {{HTMLElement("canvas")}} -- {{HTMLElement("cite")}} -- {{HTMLElement("code")}} -- {{HTMLElement("data")}} -- {{HTMLElement("datalist")}} -- {{HTMLElement("dfn")}} -- {{HTMLElement("em")}} -- {{HTMLElement("embed")}} -- {{HTMLElement("i")}} -- {{HTMLElement("iframe")}} -- {{HTMLElement("img")}} -- {{HTMLElement("input")}} -- {{HTMLElement("kbd")}} -- {{HTMLElement("label")}} -- {{HTMLElement("mark")}} -- {{MathMLElement("math")}} -- {{HTMLElement("meter")}} -- {{HTMLElement("noscript")}} -- {{HTMLElement("object")}} -- {{HTMLElement("output")}} -- {{HTMLElement("picture")}} -- {{HTMLElement("progress")}} -- {{HTMLElement("q")}} -- {{HTMLElement("ruby")}} -- {{HTMLElement("s")}} -- {{HTMLElement("samp")}} -- {{HTMLElement("script")}} -- {{HTMLElement("select")}} -- {{HTMLElement("slot")}} -- {{HTMLElement("small")}} -- {{HTMLElement("span")}} -- {{HTMLElement("strong")}} -- {{HTMLElement("sub")}} -- {{HTMLElement("sup")}} -- {{SVGElement("svg")}} -- {{HTMLElement("template")}} -- {{HTMLElement("textarea")}} -- {{HTMLElement("time")}} -- {{HTMLElement("u")}} -- {{HTMLElement("var")}} -- {{HTMLElement("video")}} -- {{HTMLElement("wbr")}} -- plain text (including more than just whitespace characters) - -A few other elements belong to this category, but only if a specific condition is fulfilled: - -- {{HTMLElement("a")}}, if it contains only phrasing content -- {{HTMLElement("area")}}, if it is a descendant of a {{HTMLElement("map")}} element -- {{HTMLElement("del")}}, if it contains only phrasing content -- {{HTMLElement("ins")}}, if it contains only phrasing content -- {{HTMLElement("link")}}, if the [itemprop](/en-US/docs/Web/HTML/Global_attributes/itemprop) attribute is present -- {{HTMLElement("map")}}, if it contains only phrasing content -- {{HTMLElement("meta")}}, if the [itemprop](/en-US/docs/Web/HTML/Global_attributes/itemprop) attribute is present - -### Embedded content - -Embedded content, a subset of flow content, imports another resource or inserts content from another markup language or namespace into the document. - -The embedded content elements are: - -- {{HTMLElement("audio")}} -- {{HTMLElement("canvas")}} -- {{HTMLElement("embed")}} -- {{HTMLElement("iframe")}} -- {{HTMLElement("img")}} -- {{MathMLElement("math")}} -- {{HTMLElement("object")}} -- {{HTMLElement("picture")}} -- {{SVGElement("svg")}} -- {{HTMLElement("video")}} - -### Interactive content - -Interactive content, a subset of flow content, includes elements that are specifically designed for user interaction. - -The interactive content elements are: - -- {{HTMLElement("button")}} -- {{HTMLElement("details")}} -- {{HTMLElement("embed")}} -- {{HTMLElement("iframe")}} -- {{HTMLElement("label")}} -- {{HTMLElement("select")}} -- {{HTMLElement("textarea")}} - -Some elements belong to this category only under specific conditions: - -- {{HTMLElement("a")}}, if the [`href`](/en-US/docs/Web/HTML/Element/a#href) attribute is present -- {{HTMLElement("audio")}}, if the [`controls`](/en-US/docs/Web/HTML/Element/audio#controls) attribute is present -- {{HTMLElement("img")}}, if the [`usemap`](/en-US/docs/Web/HTML/Element/img#usemap) attribute is present -- {{HTMLElement("input")}}, if the [type](/en-US/docs/Web/HTML/Element/input#type) attribute is not in the hidden state -- {{HTMLElement("object")}}, if the [`usemap`](/en-US/docs/Web/HTML/Element/object#usemap) attribute is present -- {{HTMLElement("video")}}, if the [`controls`](/en-US/docs/Web/HTML/Element/video#controls) attribute is present - -### Palpable content - -Content is palpable when it's neither empty nor hidden; it is content that is rendered and is substantive. Elements whose model is flow content should have at least one node which is palpable. - -The palpable elements are: - -- {{HTMLElement("a")}} -- {{HTMLElement("abbr")}} -- {{HTMLElement("address")}} -- {{HTMLElement("article")}} -- {{HTMLElement("aside")}} -- {{HTMLElement("b")}} -- {{HTMLElement("bdi")}} -- {{HTMLElement("bdo")}} -- {{HTMLElement("blockquote")}} -- {{HTMLElement("button")}} -- {{HTMLElement("canvas")}} -- {{HTMLElement("cite")}} -- {{HTMLElement("code")}} -- {{HTMLElement("data")}} -- {{HTMLElement("del")}} -- {{HTMLElement("details")}} -- {{HTMLElement("dfn")}} -- {{HTMLElement("div")}} -- {{HTMLElement("em")}} -- {{HTMLElement("embed")}} -- {{HTMLElement("fieldset")}} -- {{HTMLElement("footer")}} -- {{HTMLElement("figure")}} -- {{HTMLElement("form")}} -- {{HtmlElement("iframe")}} -- {{HtmlElement("img")}} -- {{HtmlElement("ins")}} -- {{HtmlElement("kbd")}} -- {{HtmlElement("label")}} -- {{HtmlElement("main")}} -- {{HtmlElement("map")}} -- {{HtmlElement("mark")}} -- {{MathMLElement("math")}} from [MathML](/en-US/docs/Web/MathML) -- {{HtmlElement("meter")}} -- {{HtmlElement("nav")}} -- {{HtmlElement("object")}} -- {{HtmlElement("p")}} -- {{HtmlElement("picture")}} -- {{HtmlElement("pre")}} -- {{HtmlElement("progress")}} -- {{HtmlElement("q")}} -- {{HtmlElement("ruby")}} -- {{HtmlElement("s")}} -- {{HtmlElement("samp")}} -- {{HtmlElement("search")}} -- {{HtmlElement("section")}} -- {{HtmlElement("select")}} -- {{HtmlElement("small")}} -- {{HtmlElement("span")}} -- {{HtmlElement("strong")}} -- {{HtmlElement("sub")}} -- {{HtmlElement("sup")}} -- {{SVGElement("svg")}} from [SVG](/en-US/docs/Web/SVG) -- {{HtmlElement("table")}} -- {{HtmlElement("textarea")}} -- {{HtmlElement("time")}} -- {{HtmlElement("u")}} -- {{HtmlElement("var")}} -- {{HtmlElement("video")}} -- [Autonomous custom elements](/en-US/docs/Web/API/Web_components/Using_custom_elements) -- text that is not inter-element [whitespace](/en-US/docs/Glossary/Whitespace) - -Some elements belong to this category only under specific conditions: - -- {{HTMLElement("audio")}}, if the [`controls`](/en-US/docs/Web/HTML/Element/audio#controls) attribute is present -- {{HTMLElement("dl")}}, if the element's children include at least one name-value group -- {{HTMLElement("input")}}, if the [type](/en-US/docs/Web/HTML/Element/input#type) attribute is not in the hidden state -- {{HTMLElement("ol")}}, if it's children include at least one {{HTMLElement("li")}} element -- {{HTMLElement("ul")}}, if it's children include at least one {{HTMLElement("li")}} element - -### Form-associated content - -Form-associated content is a subset of flow content comprising elements that have a form owner, exposed by a **form** attribute, and can be used everywhere flow content is expected. A form owner is either the containing {{HTMLElement("form")}} element or the element whose id is specified in the **form** attribute. - -The form-associated elements are: - -- {{HTMLElement("button")}} -- {{HTMLElement("fieldset")}} -- {{HTMLElement("input")}} -- {{HTMLElement("label")}} -- {{HTMLElement("meter")}} -- {{HTMLElement("object")}} -- {{HTMLElement("output")}} -- {{HTMLElement("progress")}} -- {{HTMLElement("select")}} -- {{HTMLElement("textarea")}} - -This category contains several sub-categories: - -- listed - - : Elements that are listed in the {{domxref("HTMLFormElement.elements", "form.elements")}} and `fieldset.elements` collections. Contains {{HTMLElement("button")}}, {{HTMLElement("fieldset")}}, {{HTMLElement("input")}}, {{HTMLElement("object")}}, {{HTMLElement("output")}}, {{HTMLElement("select")}}, and {{HTMLElement("textarea")}}. -- labelable - - : Elements that can be associated with {{HTMLElement("label")}} elements. Contains {{HTMLElement("button")}}, {{HTMLElement("input")}}, {{HTMLElement("meter")}}, {{HTMLElement("output")}}, {{HTMLElement("progress")}}, {{HTMLElement("select")}}, and {{HTMLElement("textarea")}}. -- submittable - - : Elements that can be used for constructing the form data set when the form is submitted. Contains {{HTMLElement("button")}}, {{HTMLElement("input")}}, {{HTMLElement("object")}}, {{HTMLElement("select")}}, and {{HTMLElement("textarea")}}. -- resettable - - : Elements that can be affected when a form is reset. Contains {{HTMLElement("input")}}, {{HTMLElement("output")}}, {{HTMLElement("select")}}, and {{HTMLElement("textarea")}}. - -## Secondary content categories - -There are some secondary classifications of elements that can be useful to be aware of as well. - -### Script-supporting elements - -**Script-supporting elements** are elements that don't directly contribute to a document's rendered output. Instead, they serve to support scripts, either by containing or specifying script code directly or by specifying data that will be used by scripts. - -The script-supporting elements are: - -- {{HTMLElement("script")}} -- {{HTMLElement("template")}} - -## Transparent content model - -If an element has a transparent content model, then its contents must be structured such that they would be valid HTML, even if the transparent element were removed and replaced by the child elements. - -For example, the {{HTMLElement("del")}} and {{HTMLElement("ins")}} elements are transparent: - -```html -<p><del>Shopping</del> <ins>Returns</ins> list</p> -<ul> - <del> - <li>Oranges</li> - <li>Toilet paper</li> - </del> - <li>Toothpaste</li> -</ul> -``` - -If those elements were removed, this fragment would still be valid HTML (if not correct English). - -```html -<p>Shopping Returns list</p> -<ul> - <li>Oranges</li> - <li>Toilet paper</li> - <li>Toothpaste</li> -</ul> -``` diff --git a/files/en-us/web/html/cors_enabled_image/index.md b/files/en-us/web/html/cors_enabled_image/index.md deleted file mode 100644 index f49ab5f52b2849e..000000000000000 --- a/files/en-us/web/html/cors_enabled_image/index.md +++ /dev/null @@ -1,115 +0,0 @@ ---- -title: Allowing cross-origin use of images and canvas -slug: Web/HTML/CORS_enabled_image -page-type: guide ---- - -{{HTMLSidebar}} - -HTML provides a [`crossorigin`](/en-US/docs/Web/HTML/Element/img#crossorigin) attribute for images that, in combination with an appropriate {{Glossary("CORS")}} header, allows images defined by the {{ HTMLElement("img") }} element that are loaded from foreign origins to be used in a {{HTMLElement("canvas")}} as if they had been loaded from the current origin. - -See [CORS settings attributes](/en-US/docs/Web/HTML/Attributes/crossorigin) for details on how the `crossorigin` attribute is used. - -## Security and tainted canvases - -Because the pixels in a canvas's bitmap can come from a variety of sources, including images or videos retrieved from other hosts, it's inevitable that security problems may arise. - -As soon as you draw into a canvas any data that was loaded from another origin without CORS approval, the canvas becomes **tainted**. A tainted canvas is one which is no longer considered secure, and any attempts to retrieve image data back from the canvas will cause an exception to be thrown. - -If the source of the foreign content is an HTML {{HTMLElement("img")}} or SVG {{SVGElement("svg")}} element, attempting to retrieve the contents of the canvas isn't allowed. - -If the foreign content comes from an image obtained from either as {{domxref("HTMLCanvasElement")}} or {{domxref("ImageBitMap")}}, and the image source doesn't meet the same origin rules, attempts to read the canvas's contents are blocked. - -Calling any of the following on a tainted canvas will result in an error: - -- Calling {{domxref("CanvasRenderingContext2D.getImageData", "getImageData()")}} on the canvas's context -- Calling {{domxref("HTMLCanvasElement.toBlob", "toBlob()")}}, {{domxref("HTMLCanvasElement.toDataURL", "toDataURL()")}} or {{domxref("HTMLCanvasElement.captureStream", "captureStream()")}} on the {{HTMLElement("canvas")}} element itself - -Attempting any of these when the canvas is tainted will cause a `SecurityError` to be thrown. This protects users from having private data exposed by using images to pull information from remote websites without permission. - -## Storing an image from a foreign origin - -In this example, we wish to permit images from a foreign origin to be retrieved and saved to local storage. Implementing this requires configuring the server as well as writing code for the website itself. - -### Web server configuration - -The first thing we need is a server that's configured to host images with the {{HTTPHeader("Access-Control-Allow-Origin")}} header configured to permit cross-origin access to image files. - -Let's assume we're serving our site using [Apache](https://httpd.apache.org/). Consider the HTML5 Boilerplate [Apache server configuration file for CORS images](https://github.com/h5bp/server-configs-apache/blob/main/h5bp/cross-origin/images.conf), shown below: - -```xml -<IfModule mod_setenvif.c> - <IfModule mod_headers.c> - <FilesMatch "\.(avifs?|bmp|cur|gif|ico|jpe?g|jxl|a?png|svgz?|webp)$"> - SetEnvIf Origin ":" IS_CORS - Header set Access-Control-Allow-Origin "*" env=IS_CORS - </FilesMatch> - </IfModule> -</IfModule> -``` - -In short, this configures the server to allow graphic files (those with the extensions ".bmp", ".cur", ".gif", ".ico", ".jpg", ".jpeg", ".png", ".svg", ".svgz", and ".webp") to be accessed cross-origin from anywhere on the internet. - -### Implementing the save feature - -Now that the server has been configured to allow retrieval of the images cross-origin, we can write the code that allows the user to save them to [local storage](/en-US/docs/Web/API/Web_Storage_API), just as if they were being served from the same domain the code is running on. - -The key is to use the [`crossorigin`](/en-US/docs/Web/HTML/Element/img#crossorigin) attribute by setting {{domxref("HTMLImageElement.crossOrigin", "crossOrigin")}} on the {{domxref("HTMLImageElement")}} into which the image will be loaded. This tells the browser to request cross-origin access when downloading the image data. - -#### Starting the download - -The code that starts the download (say, when the user clicks a "Download" button), looks like this: - -```js -function startDownload() { - let imageURL = - "https://cdn.glitch.com/4c9ebeb9-8b9a-4adc-ad0a-238d9ae00bb5%2Fmdn_logo-only_color.svg?1535749917189"; - let imageDescription = "The Mozilla logo"; - - downloadedImg = new Image(); - downloadedImg.crossOrigin = "anonymous"; - downloadedImg.addEventListener("load", imageReceived, false); - downloadedImg.alt = imageDescription; - downloadedImg.src = imageURL; -} -``` - -We're using a hard-coded URL (`imageURL`) and associated descriptive text (`imageDescription`) here, but that could easily come from anywhere. To begin downloading the image, we create a new {{domxref("HTMLImageElement")}} object by using the {{domxref("HTMLImageElement.Image", "Image()")}} constructor. The image is then configured to allow cross-origin downloading by setting its `crossOrigin` attribute to `"anonymous"` (that is, allow non-authenticated downloading of the image cross-origin). An event listener is added for the {{domxref("Window/load_event", "load")}} event being fired on the image element, which means the image data has been received. Alternative text is added to the image; while `<canvas>` does not support the `alt` attribute, the value can be used to set an `aria-label` or the canvas's inner content. - -Finally, the image's {{domxref("HTMLImageElement.src", "src")}} attribute is set to the URL of the image to download; this triggers the download to begin. - -#### Receiving and saving the image - -The code that handles the newly-downloaded image is found in the `imageReceived()` method: - -```js -function imageReceived() { - const canvas = document.createElement("canvas"); - const context = canvas.getContext("2d"); - - canvas.width = downloadedImg.width; - canvas.height = downloadedImg.height; - canvas.innerText = downloadedImg.alt; - - context.drawImage(downloadedImg, 0, 0); - imageBox.appendChild(canvas); - - try { - localStorage.setItem("saved-image-example", canvas.toDataURL("image/png")); - } catch (err) { - console.error(`Error: ${err}`); - } -} -``` - -`imageReceived()` is called to handle the `"load"` event on the `HTMLImageElement` that receives the downloaded image. This event is triggered once the downloaded data is all available. It begins by creating a new {{HTMLElement("canvas")}} element that we'll use to convert the image into a data URL, and by getting access to the canvas's 2D drawing context ({{domxref("CanvasRenderingContext2D")}}) in the variable `context`. - -The canvas's size is adjusted to match the received image, the inner text is set to the image description, then the image is drawn into the canvas using {{domxref("CanvasRenderingContext2D.drawImage", "drawImage()")}}. The canvas is then inserted into the document so the image is visible. - -Now it's time to actually save the image locally. To do this, we use the Web Storage API's local storage mechanism, which is accessed through the {{domxref("Window.localStorage", "localStorage")}} global. The canvas method {{domxref("HTMLCanvasElement.toDataURL", "toDataURL()")}} is used to convert the image into a data:// URL representing a PNG image, which is then saved into local storage using {{domxref("Storage.setItem", "setItem()")}}. - -## See also - -- [Using Cross-domain images in WebGL and Chrome 13](https://blog.chromium.org/2011/07/using-cross-domain-images-in-webgl-and.html) -- [HTML Specification - the `crossorigin` attribute](https://html.spec.whatwg.org/multipage/embedded-content.html#attr-img-crossorigin) -- [Web Storage API](/en-US/docs/Web/API/Web_Storage_API) diff --git a/files/en-us/web/html/date_and_time_formats/index.md b/files/en-us/web/html/date_and_time_formats/index.md deleted file mode 100644 index bd5e6ba08279a11..000000000000000 --- a/files/en-us/web/html/date_and_time_formats/index.md +++ /dev/null @@ -1,435 +0,0 @@ ---- -title: Date and time formats used in HTML -slug: Web/HTML/Date_and_time_formats -page-type: guide ---- - -{{HTMLSidebar}} - -Certain HTML elements use date and/or time values. The formats of the strings that specify these values are described in this article. - -Elements that use such formats include certain forms of the {{HTMLElement("input")}} element that let the user choose or specify a date, time, or both, as well as the {{HTMLElement("ins")}} and {{HTMLElement("del")}} elements, whose [`datetime`](/en-US/docs/Web/HTML/Element/ins#datetime) attribute specifies the date or date and time at which the insertion or deletion of content occurred. - -For `<input>`, the [`type`](/en-US/docs/Web/HTML/Element/input#type) values of inputs whose [`value`](/en-US/docs/Web/HTML/Element/input#value) contains a string representing a date and/or time are: - -- [`date`](/en-US/docs/Web/HTML/Element/input/date) -- [`datetime-local`](/en-US/docs/Web/HTML/Element/input/datetime-local) -- [`month`](/en-US/docs/Web/HTML/Element/input/month) -- [`time`](/en-US/docs/Web/HTML/Element/input/time) -- [`week`](/en-US/docs/Web/HTML/Element/input/week) - -## Examples - -Before getting into the intricacies of how date and time strings are written and parsed in HTML, here are some examples that should give you a good idea what the more commonly-used date and time string formats look like. - -<table class="standard-table"> - <caption> - Example HTML date and time strings - </caption> - <thead> - <tr> - <th scope="col">String</th> - <th colspan="2" scope="col">Date and/or time</th> - </tr> - </thead> - <tbody> - <tr> - <td><code>2005-06-07</code></td> - <td>June 7, 2005</td> - <td> - <a href="#date_strings" - >[details]</a - > - </td> - </tr> - <tr> - <td><code>08:45</code></td> - <td>8:45 AM</td> - <td> - <a href="#time_strings" - >[details]</a - > - </td> - </tr> - <tr> - <td><code>08:45:25</code></td> - <td>8:45 AM and 25 seconds</td> - <td> - <a href="#time_strings" - >[details]</a - > - </td> - </tr> - <tr> - <td><code>0033-08-04T03:40</code></td> - <td>3:40 AM on August 4, 33</td> - <td> - <a - href="#local_date_and_time_strings" - >[details]</a - > - </td> - </tr> - <tr> - <td><code>1977-04-01T14:00:30</code></td> - <td>30 seconds after 2:00 PM on April 1, 1977</td> - <td> - <a - href="#local_date_and_time_strings" - >[details]</a - > - </td> - </tr> - <tr> - <td><code>1901-01-01T00:00Z</code></td> - <td>Midnight UTC on January 1, 1901</td> - <td> - <a - href="#global_date_and_time_strings" - >[details]</a - > - </td> - </tr> - <tr> - <td><code>1901-01-01T00:00:01-04:00</code></td> - <td> - 1 second past midnight Eastern Standard Time (EST) on January 1, 1901 - </td> - <td> - <a - href="#global_date_and_time_strings" - >[details]</a - > - </td> - </tr> - </tbody> -</table> - -## Basics - -Before looking at the various formats of date and time related strings used by HTML elements, it is helpful to understand a few fundamental facts about the way they're defined. HTML uses a variation of the [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) standard for its date and time strings. It's worth reviewing the descriptions of the formats you're using in order to ensure that your strings are in fact compatible with HTML, as the HTML specification includes algorithms for parsing these strings that is actually more precise than ISO 8601, so there can be subtle differences in how date and time strings are expected to look. - -### Character set - -Dates and times in HTML are always strings which use the {{Glossary("ASCII")}} character set. - -### Year numbers - -In order to simplify the basic format used for date strings in HTML, the specification requires that all years be given using the modern (or **proleptic**) [Gregorian calendar](https://en.wikipedia.org/wiki/Gregorian_calendar). While user interfaces may allow entry of dates using other calendars, the underlying value always uses the Gregorian calendar. - -While the Gregorian calendar wasn't created until the year 1582 (replacing the similar Julian calendar), for HTML's purposes, the Gregorian calendar is extended back to the year 1 C.E. Make sure any older dates account for this. - -For the purposes of HTML dates, years are always at least four digits long; years prior to the year 1000 are padded with leading zeroes (`0`), so the year 72 is written as `0072`. Years prior to the year 1 C.E. are not supported, so HTML doesn't support years 1 B.C.E. (1 B.C.) or earlier. - -A year is normally 365 days long, except during **[leap years](#leap_years)**. - -#### Leap years - -A **leap year** is any year which is divisible by 400 _or_ the year is divisible by 4 but not by 100. Although the calendar year is normally 365 days long, it actually takes the planet Earth approximately 365.2422 days to complete a single orbit around the sun. Leap years help to adjust the calendar to keep it synchronized with the actual position of the planet in its orbit. Adding a day to the year every four years essentially makes the average year 365.25 days long, which is close to correct. - -The adjustments to the algorithm (taking a leap year when the year can be divided by 400, and skipping leap years when the year is divisible by 100) help to bring the average even closer to the correct number of days (365.2425 days). Scientists occasionally add leap seconds to the calendar (seriously) to handle the remaining three ten-thousandths of a day and to compensate for the gradual, naturally occurring slowing of Earth's rotation. - -While month `02`, February, normally has 28 days, it has 29 days in leap years. - -### Months of the year - -There are 12 months in the year, numbered 1 through 12. They are always represented by a two-digit ASCII string whose value ranges from `01` through `12`. See the table in the section [Days of the month](#days_of_the_month) for the month numbers and their corresponding names (and lengths in days). - -### Days of the month - -Month numbers 1, 3, 5, 7, 8, 10, and 12 are 31 days long. Months 4, 6, 9, and 11 are 30 days long. Month 2, February, is 28 days long most years, but is 29 days long in leap years. This is detailed in the following table. - -<table class="standard-table"> - <caption> - The months of the year and their lengths in days - </caption> - <thead> - <tr> - <th scope="row">Month number</th> - <th scope="col">Name (English)</th> - <th scope="col">Length in days</th> - </tr> - </thead> - <tbody> - <tr> - <th scope="row">01</th> - <td>January</td> - <td>31</td> - </tr> - <tr> - <th scope="row">02</th> - <td>February</td> - <td>28 (29 in leap years)</td> - </tr> - <tr> - <th scope="row">03</th> - <td>March</td> - <td>31</td> - </tr> - <tr> - <th scope="row">04</th> - <td>April</td> - <td>30</td> - </tr> - <tr> - <th scope="row">05</th> - <td>May</td> - <td>31</td> - </tr> - <tr> - <th scope="row">06</th> - <td>June</td> - <td>30</td> - </tr> - <tr> - <th scope="row">07</th> - <td>July</td> - <td>31</td> - </tr> - <tr> - <th scope="row">08</th> - <td>August</td> - <td>31</td> - </tr> - <tr> - <th scope="row">09</th> - <td>September</td> - <td>30</td> - </tr> - <tr> - <th scope="row">10</th> - <td>October</td> - <td>31</td> - </tr> - <tr> - <th scope="row">11</th> - <td>November</td> - <td>30</td> - </tr> - <tr> - <th scope="row">12</th> - <td>December</td> - <td>31</td> - </tr> - </tbody> -</table> - -## Week strings - -A week string specifies a week within a particular year. A **valid week string** consists of a valid [year number](#year_numbers), followed by a hyphen character (`-`, or U+002D), then the capital letter `W` (U+0057), followed by a two-digit week of the year value. - -The week of the year is a two-digit string between `01` and `53`. Each week begins on Monday and ends on Sunday. That means it's possible for the first few days of January to be considered part of the previous week-year, and for the last few days of December to be considered part of the following week-year. The first week of the year is the week that contains the _first Thursday of the year_. For example, the first Thursday of 1953 was on January 1, so that week—beginning on Monday, December 29—is considered the first week of the year. Therefore, December 30, 1952 occurs during the week `1953-W01`. - -A year has 53 weeks if: - -- The first day of the calendar year (January 1) is a Thursday **or** -- The first day of the year (January 1) is a Wednesday and the year is a [leap year](#leap_years) - -All other years have 52 weeks. - -| Week string | Week and year (Date range) | -| ----------- | ------------------------------------------------- | -| `2001-W37` | Week 37, 2001 (September 10-16, 2001) | -| `1953-W01` | Week 1, 1953 (December 29, 1952-January 4, 1953) | -| `1948-W53` | Week 53, 1948 (December 27, 1948-January 2, 1949) | -| `1949-W01` | Week 1, 1949 (January 3-9, 1949) | -| `0531-W16` | Week 16, 531 (April 13-19, 531) | -| `0042-W04` | Week 4, 42 (January 21-27, 42) | - -Note that both the year and week numbers are padded with leading zeroes, with the year padded to four digits and the week to two. - -## Month strings - -A month string represents a specific month in time, rather than a generic month of the year. That is, rather than representing "January," an HTML month string represents a month and year paired, like "January 1972." - -A **valid month string** consists of a valid [year number](#year_numbers) (a string of at least four digits), followed by a hyphen character (`-`, or U+002D), followed by a two-digit numeric [month number](#months_of_the_year), where `01` represents January and `12` represents December. - -| Month string | Month and year | -| ------------ | ---------------- | -| `17310-09` | September, 17310 | -| `2019-01` | January, 2019 | -| `1993-11` | November, 1993 | -| `0571-04` | April, 571 | -| `0001-07` | July, 1 C.E. | - -Notice that all years are at least four characters long; years that are fewer than four digits long are padded with leading zeroes. - -## Date strings - -A valid date string consists of a [month string](#month_strings), followed by a hyphen character (`-`, or U+002D), followed by a two-digit [day of the month](#days_of_the_month). - -| Date string | Full date | -| ------------ | ---------------- | -| `1993-11-01` | November 1, 1993 | -| `1066-10-14` | October 14, 1066 | -| `0571-04-22` | April 22, 571 | -| `0062-02-05` | February 5, 62 | - -## Time strings - -A time string can specify a time with precision to the minute, second, or to the millisecond. Specifying only the hour or minute isn't permitted. A **valid time string** minimally consists of a two-digit hour followed by a colon (`:`, U+003A), then a two-digit minute. The minute may optionally be followed by another colon and a two-digit number of seconds. Milliseconds may be specified, optionally, by adding a decimal point character (`.`, U+002E) followed by one, two, or three digits. - -There are some additional basic rules: - -- The hour is always specified using the 24-hour clock, with `00` being midnight and 11 PM being `23`. No values outside the range `00` – `23` are permitted. -- The minute must be a two-digit number between `00` and `59`. No values outside that range are allowed. -- If the number of seconds is omitted (to specify a time accurate only to the minute), no colon should follow the number of minutes. -- If specified, the integer portion of the number of seconds must be between `00` and `59`. You _cannot_ specify leap seconds by using values like `60` or `61`. -- If the number of seconds is specified and is an integer, it must not be followed by a decimal point. -- If a fraction of a second is included, it may be from one to three digits long, indicating the number of milliseconds. It follows the decimal point placed after the seconds component of the time string. - -| Time string | Time | -| ------------- | --------------------------------------------- | -| `00:00:30.75` | 12:00:30.75 AM (30.75 seconds after midnight) | -| `12:15` | 12:15 PM | -| `13:44:25` | 1:44:25 PM (25 seconds after 1:44 PM) | - -## Local date and time strings - -A valid [`datetime-local`](/en-US/docs/Web/HTML/Element/input/datetime-local) string consists of a `date` string and a `time` string concatenated together with either the letter `T` or a space character separating them. No information about the time zone is included in the string; the date and time is presumed to be in the user's local time zone. - -When you set the [`value`](/en-US/docs/Web/HTML/Element/input#value) of a `datetime-local` input, the string is **normalized** into a standard form. Normalized `datetime` strings always use the letter `T` to separate the date and the time, and the time portion of the string is as short as possible. This is done by leaving out the seconds component if its value is `:00`. - -<table class="standard-table"> - <caption> - Examples of valid - <code>datetime-local</code> - strings - </caption> - <thead> - <tr> - <th scope="col">Date/time string</th> - <th scope="col">Normalized date/time string</th> - <th scope="col">Actual date and time</th> - </tr> - </thead> - <tbody> - <tr> - <td><code>1986-01-28T11:38:00.01</code></td> - <td><code>1986-01-28T11:38:00.01</code></td> - <td>January 28, 1986 at 11:38:00.01 AM</td> - </tr> - <tr> - <td><code>1986-01-28 11:38:00.010</code></td> - <td> - <p><code>1986-01-28T11:38:00.01</code></p> - <p> - Note that after normalization, this is the same string as the previous - <code>datetime-local</code> string. The space has been replaced with - the <code>T</code> character and the trailing zero in the fraction - of a second has been removed to make the string as short as possible. - </p> - </td> - <td>January 28, 1986 at 11:38:00.01 AM</td> - </tr> - <tr> - <td><code>0170-07-31T22:00:00</code></td> - <td> - <p><code>0170-07-31T22:00</code></p> - <p> - Note that the normalized form of this date drops the - <code>:00</code> indicating the number of seconds to be zero, - because the seconds are optional when zero, and the normalized string - minimizes the length of the string. - </p> - </td> - <td>July 31, 170 at 10:00 PM</td> - </tr> - </tbody> -</table> - -## Global date and time strings - -A global date and time string specifies a date and time as well as the time zone in which it occurs. A **valid global date and time string** is the same format as a [local date and time string](#local_date_and_time_strings), except it has a time zone string appended to the end, following the time. - -### Time zone offset string - -A time zone offset string specifies the offset in either a positive or a negative number of hours and minutes from the standard time base. There are two standard time bases, which are very close to the same, but not exactly the same: - -- For dates after the establishment of [Coordinated Universal Time](https://en.wikipedia.org/wiki/Coordinated_Universal_Time) (UTC) in the early 1960s, the time base is `Z` and the offset indicates a particular time zone's offset from the time at the prime meridian at 0º longitude (which passes through the Royal Observatory at Greenwich, England). -- For dates prior to UTC, the time base is instead expressed in terms of [UT1](https://en.wikipedia.org/wiki/UT1), which is the contemporary Earth solar time at the prime meridian. - -The time zone string is appended immediately following the time in the date and time string. You can specify `Z` as the time zone offset string to indicate that the time is specified in UTC. Otherwise, the time zone string is constructed as follows: - -1. A character indicating the sign of the offset: the plus character (`+`, or U+002B) for time zones to the east of the prime meridian or the minus character (`-`, or U+002D) for time zones to the west of the prime meridian. -2. A two-digit number of hours that the time zone is offset from the prime meridian. This value must be between `00` and `23`. -3. An optional colon (`:`) character. -4. A two-digit number of minutes past the hour; this value must be between `00` and `59`. - -While this format allows for time zones between -23:59 and +23:59, the current range of time zone offsets is -12:00 to +14:00, and no time zones are currently offset from the hour by anything other than `00`, `30`, or `45` minutes. This may change at more or less anytime, since countries are free to tamper with their time zones at any time and in any way they wish to do so. - -<table class="no-markdown"> - <caption> - Examples of valid global date and time strings - </caption> - <thead> - <tr> - <th scope="col">Global date and time string</th> - <th scope="col">Actual global date and time</th> - <th scope="col">Date and time at prime meridian</th> - </tr> - </thead> - <tbody> - <tr> - <td><code>2005-06-07T00:00Z</code></td> - <td>June 7, 2005 at midnight UTC</td> - <td>June 7, 2005 at midnight</td> - </tr> - <tr> - <td><code>1789-08-22T12:30:00.1-04:00</code></td> - <td> - August 22, 1789 at a tenth of a second past 12:30 PM Eastern Daylight - Time (EDT) - </td> - <td>August 22, 1789 at a tenth of a second past 4:30 PM</td> - </tr> - <tr> - <td><code>3755-01-01 00:00+10:00</code></td> - <td> - January 1, 3755 at midnight Australian Eastern Standard Time (AEST) - </td> - <td>December 31, 3754 at 2:00 PM</td> - </tr> - </tbody> -</table> - -## Date issues - -Because of data storage and precision issues, you may want to be aware of a few client-side and server-side issues. - -### The Y2K38 Problem (often server-side) - -JavaScript uses double precision floating points to store dates, as with all numbers, meaning that JavaScript code will not suffer from the Y2K38 problem unless integer coercion/bit-hacks are used because all JavaScript bit operators use 32-bit signed 2s-complement integers. - -The problem is with the server side of things: storage of dates greater than 2^31 - 1. To fix this problem, you must store all dates using either unsigned 32-bit integers, signed 64-bit integers, or double-precision floating points on the server. If your server is written in PHP, the fix may require upgrading your PHP to a more recent version, and upgrading your hardware to x86_64 or IA64. If you are stuck with other hardware, you can try to emulate 64-bit hardware inside a 32-bit virtual machine, but most VMs don't support this kind of virtualization, since stability may suffer, and performance will definitely suffer greatly. - -### The Y10k Problem (often client-side) - -In many servers, dates are stored as numbers instead of as strings--numbers of a fixed size and agnostic of format (aside from endianness). After the year 10,000, those numbers will just be a bit bigger than before, so many servers will not see issues with forms submitted after the year 10,000. - -The problem is with the client side of things: parsing of dates with more than 4 digits in the year. - -```html -<!--midnight of January 1st, 10000: the exact time of Y10K--> -<input type="datetime-local" value="+010000-01-01T05:00" /> -``` - -We need to prepare our code for any number of digits — not just 5. The following JavaScript function programmatically sets the value: - -```js -function setValue(element, date) { - const isoString = date.toISOString(); - element.value = isoString.substring(0, isoString.indexOf("T") + 6); -} -``` - -Why worry about the Y10K problem if it is going to happen many centuries after your death? Exactly because you will already be dead, so the companies using your software will be stuck using your software without any other coder who knows the system well enough to come in and fix it. - -## See also - -- {{HTMLElement("input")}} -- {{HTMLElement("ins")}} and {{HTMLElement("del")}}: see the `datetime` attribute, which specifies either a date or a local date and time at which the content was inserted or deleted -- [The ISO 8601 specification](https://www.iso.org/iso-8601-date-and-time-format.html) -- [Representing dates & times](/en-US/docs/Web/JavaScript/Guide/Representing_dates_times) in the [JavaScript Guide](/en-US/docs/Web/JavaScript/Guide) -- The JavaScript {{jsxref("Date")}} object -- The [`Intl.DateTimeFormat`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/DateTimeFormat) object for formatting dates and times for a given locale diff --git a/files/en-us/web/html/element/a/index.md b/files/en-us/web/html/element/a/index.md deleted file mode 100644 index c59c339730d2888..000000000000000 --- a/files/en-us/web/html/element/a/index.md +++ /dev/null @@ -1,582 +0,0 @@ ---- -title: "<a>: The Anchor element" -slug: Web/HTML/Element/a -page-type: html-element -browser-compat: html.elements.a ---- - -{{HTMLSidebar}} - -The **`<a>`** [HTML](/en-US/docs/Web/HTML) element (or _anchor_ element), with [its `href` attribute](#href), creates a hyperlink to web pages, files, email addresses, locations in the same page, or anything else a URL can address. - -Content within each `<a>` _should_ indicate the link's destination. If the `href` attribute is present, pressing the enter key while focused on the `<a>` element will activate it. - -{{InteractiveExample("HTML Demo: &lt;a&gt;", "tabbed-shorter")}} - -```html interactive-example -<p>You can reach Michael at:</p> - -<ul> - <li><a href="https://example.com">Website</a></li> - <li><a href="mailto:m.bluth@example.com">Email</a></li> - <li><a href="tel:+123456789">Phone</a></li> -</ul> -``` - -```css interactive-example -li { - margin-bottom: 0.5rem; -} -``` - -## Attributes - -This element's attributes include the [global attributes](/en-US/docs/Web/HTML/Global_attributes). - -- `attributionsrc` {{experimental_inline}} - - - : Specifies that you want the browser to send an {{httpheader("Attribution-Reporting-Eligible")}} header. On the server-side this is used to trigger sending an {{httpheader("Attribution-Reporting-Register-Source")}} header in the response, to register a [navigation-based attribution source](/en-US/docs/Web/API/Attribution_Reporting_API/Registering_sources#navigation-based_attribution_sources). - - The browser stores the source data associated with the navigation-based attribution source (as provided in the {{httpheader("Attribution-Reporting-Register-Source")}} response header) when the user clicks the link. See the [Attribution Reporting API](/en-US/docs/Web/API/Attribution_Reporting_API) for more details. - - There are two versions of this attribute that you can set: - - - Boolean, i.e. just the `attributionsrc` name. This specifies that you want the {{httpheader("Attribution-Reporting-Eligible")}} header sent to the same server as the `href` attribute points to. This is fine when you are handling the attribution source registration on the same server. - - Value containing one or more URLs, for example: - - ```html - attributionsrc="https://a.example/register-source - https://b.example/register-source" - ``` - - This is useful in cases where the requested resource is not on a server you control, or you just want to handle registering the attribution source on a different server. In this case, you can specify one or more URLs as the value of `attributionsrc`. When the resource request occurs, the {{httpheader("Attribution-Reporting-Eligible")}} header will be sent to the URL(s) specified in `attributionsrc` in addition to the resource origin. These URLs can then respond with the {{httpheader("Attribution-Reporting-Register-Source")}} to complete registration. - - > [!NOTE] - > Specifying multiple URLs means that multiple attribution sources can be registered on the same feature. You might for example have different campaigns that you are trying to measure the success of, which involve generating different reports on different data. - - `<a>` elements cannot be used as attribution triggers, only sources. - -- `download` - - - : Causes the browser to treat the linked URL as a download. Can be used with or without a `filename` value: - - - Without a value, the browser will suggest a filename/extension, generated from various sources: - - - The {{HTTPHeader("Content-Disposition")}} HTTP header - - The final segment in the URL [path](/en-US/docs/Web/API/URL/pathname) - - The {{Glossary("MIME_type", "media type")}} (from the {{HTTPHeader("Content-Type")}} header, the start of a [`data:` URL](/en-US/docs/Web/URI/Reference/Schemes/data), or {{domxref("Blob.type")}} for a [`blob:` URL](/en-US/docs/Web/API/URL/createObjectURL_static)) - - - `filename`: defining a value suggests it as the filename. `/` and `\` characters are converted to underscores (`_`). Filesystems may forbid other characters in filenames, so browsers will adjust the suggested name if necessary. - - > [!NOTE] - > - > - `download` only works for [same-origin URLs](/en-US/docs/Web/Security/Same-origin_policy), or the `blob:` and `data:` schemes. - > - How browsers treat downloads varies by browser, user settings, and other factors. The user may be prompted before a download starts, or the file may be saved automatically, or it may open automatically, either in an external application or in the browser itself. - > - If the `Content-Disposition` header has different information from the `download` attribute, resulting behavior may differ: - > - > - If the header specifies a `filename`, it takes priority over a filename specified in the `download` attribute. - > - If the header specifies a disposition of `inline`, Chrome and Firefox prioritize the attribute and treat it as a download. Old Firefox versions (before 82) prioritize the header and will display the content inline. - -- `href` - - - : The URL that the hyperlink points to. Links are not restricted to HTTP-based URLs — they can use any URL scheme supported by browsers: - - - Telephone numbers with `tel:` URLs - - Email addresses with `mailto:` URLs - - SMS text messages with `sms:` URLs - - Executable code with [`javascript:` URLs](/en-US/docs/Web/URI/Reference/Schemes/javascript) - - While web browsers may not support other URL schemes, websites can with [`registerProtocolHandler()`](/en-US/docs/Web/API/Navigator/registerProtocolHandler) - - Moreover other URL features can locate specific parts of the resource, including: - - - Sections of a page with document fragments - - Specific text portions with [text fragments](/en-US/docs/Web/URI/Reference/Fragment/Text_fragments) - - Pieces of media files with media fragments - -- `hreflang` - - : Hints at the human language of the linked URL. No built-in functionality. Allowed values are the same as [the global `lang` attribute](/en-US/docs/Web/HTML/Global_attributes/lang). -- `ping` - - : A space-separated list of URLs. When the link is followed, the browser will send {{HTTPMethod("POST")}} requests with the body `PING` to the URLs. Typically for tracking. -- `referrerpolicy` - - - : How much of the [referrer](/en-US/docs/Web/HTTP/Headers/Referer) to send when following the link. - - - `no-referrer`: The {{HTTPHeader("Referer")}} header will not be sent. - - `no-referrer-when-downgrade`: The {{HTTPHeader("Referer")}} header will not be sent to {{Glossary("origin")}}s without {{Glossary("TLS")}} ({{Glossary("HTTPS")}}). - - `origin`: The sent referrer will be limited to the origin of the referring page: its [scheme](/en-US/docs/Learn_web_development/Howto/Web_mechanics/What_is_a_URL), {{Glossary("host")}}, and {{Glossary("port")}}. - - `origin-when-cross-origin`: The referrer sent to other origins will be limited to the scheme, the host, and the port. Navigations on the same origin will still include the path. - - `same-origin`: A referrer will be sent for {{Glossary("Same-origin policy", "same origin")}}, but cross-origin requests will contain no referrer information. - - `strict-origin`: Only send the origin of the document as the referrer when the protocol security level stays the same (HTTPS→HTTPS), but don't send it to a less secure destination (HTTPS→HTTP). - - `strict-origin-when-cross-origin` (default): Send a full URL when performing a same-origin request, only send the origin when the protocol security level stays the same (HTTPS→HTTPS), and send no header to a less secure destination (HTTPS→HTTP). - - `unsafe-url`: The referrer will include the origin _and_ the path (but not the [fragment](/en-US/docs/Web/API/HTMLAnchorElement/hash), [password](/en-US/docs/Web/API/HTMLAnchorElement/password), or [username](/en-US/docs/Web/API/HTMLAnchorElement/username)). **This value is unsafe**, because it leaks origins and paths from TLS-protected resources to insecure origins. - -- [`rel`](/en-US/docs/Web/HTML/Attributes/rel) - - : The relationship of the linked URL as space-separated link types. -- `target` - - - : Where to display the linked URL, as the name for a _browsing context_ (a tab, window, or {{HTMLElement("iframe")}}). The following keywords have special meanings for where to load the URL: - - - `_self`: The current browsing context. (Default) - - `_blank`: Usually a new tab, but users can configure browsers to open a new window instead. - - `_parent`: The parent browsing context of the current one. If no parent, behaves as `_self`. - - `_top`: The topmost browsing context. To be specific, this means the "highest" context that's an ancestor of the current one. If no ancestors, behaves as `_self`. - - `_unfencedTop`: Allows embedded [fenced frames](/en-US/docs/Web/API/Fenced_frame_API) to navigate the top-level frame (i.e. traversing beyond the root of the fenced frame, unlike other reserved destinations). Note that the navigation will still succeed if this is used outside of a fenced frame context, but it will not act like a reserved keyword. - - > [!NOTE] - > Setting `target="_blank"` on `<a>` elements implicitly provides the same `rel` behavior as setting [`rel="noopener"`](/en-US/docs/Web/HTML/Attributes/rel/noopener) which does not set `window.opener`. - -- `type` - - : Hints at the linked URL's format with a {{Glossary("MIME type")}}. No built-in functionality. - -### Deprecated attributes - -- `charset` {{Deprecated_Inline}} - - - : Hinted at the {{Glossary("character encoding")}} of the linked URL. - - > [!NOTE] - > This attribute is deprecated and **should not be used by authors**. Use the HTTP {{HTTPHeader("Content-Type")}} header on the linked URL. - -- `coords` {{Deprecated_Inline}} - - : Used with [the `shape` attribute](#shape). A comma-separated list of coordinates. -- `name` {{Deprecated_Inline}} - - - : Was required to define a possible target location in a page. In HTML 4.01, `id` and `name` could both be used on `<a>`, as long as they had identical values. - - > [!NOTE] - > Use the global attribute [`id`](/en-US/docs/Web/HTML/Global_attributes/id) instead. - -- `rev` {{Deprecated_Inline}} - - : Specified a reverse link; the opposite of [the `rel` attribute](#rel). Deprecated for being very confusing. -- `shape` {{Deprecated_Inline}} - - - : The shape of the hyperlink's region in an image map. - - > [!NOTE] - > Use the {{HTMLElement("area")}} element for image maps instead. - -## Accessibility - -### Strong link text - -**The content inside a link should indicate where the link goes**, even out of context. - -#### Inaccessible, weak link text - -A sadly common mistake is to only link the words "click here" or "here": - -```html example-bad -<p>Learn more about our products <a href="/products">here</a>.</p> -``` - -##### Result - -{{EmbedLiveSample('Inaccessible, weak link text')}} - -#### Strong link text - -Luckily, this is an easy fix, and it's actually shorter than the inaccessible version! - -```html example-good -<p>Learn more <a href="/products">about our products</a>.</p> -``` - -##### Result - -{{EmbedLiveSample('Strong link text')}} - -Assistive software has shortcuts to list all links on a page. However, strong link text benefits all users — the "list all links" shortcut emulates how sighted users quickly scan pages. - -### onclick events - -Anchor elements are often abused as fake buttons by setting their `href` to `#` or [`javascript:void(0)`](/en-US/docs/Web/URI/Reference/Schemes/javascript) to prevent the page from refreshing, then listening for their `click` events. - -These bogus `href` values cause unexpected behavior when copying/dragging links, opening links in a new tab/window, bookmarking, or when JavaScript is loading, errors, or is disabled. They also convey incorrect semantics to assistive technologies, like screen readers. - -Use a {{HTMLElement("button")}} instead. In general, **you should only use a hyperlink for navigation to a real URL**. - -### External links and linking to non-HTML resources - -Links that open in a new tab/window via `target="_blank"`, or links that point to a download file should indicate what will happen when the link is followed. - -People experiencing low vision conditions, navigating with the aid of screen reading technology, or with cognitive concerns may be confused when a new tab, window, or application opens unexpectedly. Older screen-reading software may not even announce the behavior. - -#### Link that opens a new tab/window - -```html -<a target="_blank" href="https://www.wikipedia.org"> - Wikipedia (opens in new tab) -</a> -``` - -##### Result - -{{EmbedLiveSample('Link that opens a new tab/window')}} - -#### Link to a non-HTML resource - -If an icon is used to signify link behavior, make sure it has an [`alt` attribute](/en-US/docs/Web/HTML/Element/img#alt) to describe its purpose. In case the icon is missing, the `alt` attribute's content will still convey the link's behavior. - -```html -<p> - <a href="https://www.wikipedia.org/" target="_blank"> - Wikipedia - <img src="new-tab.svg" width="14" alt="(Opens in new tab)" /> - </a> - <br /> - <a href="2017-annual-report.ppt"> - 2017 annual report - <img src="powerpoint.svg" width="14" alt="(PowerPoint file)" /> - </a> -</p> -<p> - <a href="https://www.wikipedia.org/" target="_blank"> - Wikipedia - <img src="missing-icon.svg" width="14" alt="(Opens in new tab)" /> - </a> - <br /> - <a href="2017-annual-report.ppt"> - 2017 annual report - <img src="missing-icon.svg" width="14" alt="(PowerPoint file)" /> - </a> -</p> -``` - -##### Result - -{{EmbedLiveSample('Link to a non-HTML resource')}} - -- [WebAIM: Links and Hypertext - Hypertext Links](https://webaim.org/techniques/hypertext/hypertext_links) -- [MDN / Understanding WCAG, Guideline 3.2](/en-US/docs/Web/Accessibility/Understanding_WCAG/Understandable#guideline_3.2_—_predictable_make_web_pages_appear_and_operate_in_predictable_ways) -- [G200: Opening new windows and tabs from a link only when necessary](https://www.w3.org/TR/WCAG20-TECHS/G200.html) -- [G201: Giving users advanced warning when opening a new window](https://www.w3.org/TR/WCAG20-TECHS/G201.html) - -### Skip links - -A **skip link** is a link placed as early as possible in {{HTMLElement("body")}} content that points to the beginning of the page's main content. Usually, CSS hides a skip link offscreen until focused. - -```html -<body> - <a href="#content" class="skip-link">Skip to main content</a> - - <header>…</header> - - <!-- The skip link jumps to here --> - <main id="content"></main> -</body> -``` - -```css -.skip-link { - position: absolute; - top: -3em; - background: #fff; -} -.skip-link:focus { - top: 0; -} -``` - -#### Result - -{{EmbedLiveSample('Skip links')}} - -Skip links let keyboard users bypass content repeated throughout multiple pages, such as header navigation. - -Skip links are especially useful for people who navigate with the aid of assistive technology such as switch control, voice command, or mouth sticks/head wands, where the act of moving through repetitive links can be laborious. - -- [WebAIM: "Skip Navigation" Links](https://webaim.org/techniques/skipnav/) -- [How-to: Use Skip Navigation links](https://www.a11yproject.com/posts/skip-nav-links/) -- [MDN / Understanding WCAG, Guideline 2.4 explanations](/en-US/docs/Web/Accessibility/Understanding_WCAG/Operable#guideline_2.4_%e2%80%94_navigable_provide_ways_to_help_users_navigate_find_content_and_determine_where_they_are) -- [Understanding Success Criterion 2.4.1](https://www.w3.org/TR/UNDERSTANDING-WCAG20/navigation-mechanisms-skip.html) - -### Size and proximity - -#### Size - -Interactive elements, like links, should provide an area large enough that it is easy to activate them. This helps a variety of people, including those with motor control issues and those using imprecise inputs such as a touchscreen. A minimum size of 44×44 [CSS pixels](https://www.w3.org/TR/WCAG21/#dfn-css-pixels) is recommended. - -Text-only links in prose content are exempt from this requirement, but it's still a good idea to make sure enough text is hyperlinked to be easily activated. - -- [Understanding Success Criterion 2.5.5: Target Size](https://www.w3.org/WAI/WCAG21/Understanding/target-size.html) -- [Target Size and 2.5.5](https://adrianroselli.com/2019/06/target-size-and-2-5-5.html) -- [Quick test: Large touch targets](https://www.a11yproject.com/posts/large-touch-targets/) - -#### Proximity - -Interactive elements, like links, placed in close visual proximity should have space separating them. Spacing helps people with motor control issues, who may otherwise accidentally activate the wrong interactive content. - -Spacing may be created using CSS properties like {{CSSxRef("margin")}}. - -- [Hand tremors and the giant-button-problem](https://axesslab.com/hand-tremors/) - -## Examples - -### Linking to an absolute URL - -#### HTML - -```html -<a href="https://www.mozilla.com">Mozilla</a> -``` - -#### Result - -{{EmbedLiveSample('Linking_to_an_absolute_URL')}} - -### Linking to relative URLs - -#### HTML - -```html -<a href="//example.com">Scheme-relative URL</a> -<a href="/en-US/docs/Web/HTML">Origin-relative URL</a> -<a href="p">Directory-relative URL</a> -<a href="./p">Directory-relative URL</a> -<a href="../p">Parent-directory-relative URL</a> -``` - -```css hidden -a { - display: block; - margin-bottom: 0.5em; -} -``` - -#### Result - -{{EmbedLiveSample('Linking_to_relative_URLs')}} - -### Linking to an element on the same page - -```html -<!-- <a> element links to the section below --> -<p><a href="#Section_further_down">Jump to the heading below</a></p> - -<!-- Heading to link to --> -<h2 id="Section_further_down">Section further down</h2> -``` - -#### Result - -{{EmbedLiveSample('Linking to an element on the same page')}} - -> [!NOTE] -> You can use `href="#top"` or the empty fragment (`href="#"`) to link to the top of the current page, [as defined in the HTML specification](https://html.spec.whatwg.org/multipage/browsing-the-web.html#scroll-to-the-fragment-identifier). - -### Linking to an email address - -To create links that open in the user's email program to let them send a new message, use the `mailto:` scheme: - -```html -<a href="mailto:nowhere@mozilla.org">Send email to nowhere</a> -``` - -#### Result - -{{EmbedLiveSample('Linking to an email address')}} - -For details about `mailto:` URLs, such as including a subject or body, see [Email links](/en-US/docs/Learn_web_development/Core/Structuring_content/Creating_links#email_links) or {{RFC(6068)}}. - -### Linking to telephone numbers - -```html -<a href="tel:+49.157.0156">+49 157 0156</a> -<a href="tel:+1(800)555-0123">(800) 555-0123</a> -``` - -#### Result - -{{EmbedLiveSample('Linking to telephone numbers')}} - -`tel:` link behavior varies with device capabilities: - -- Cellular devices autodial the number. -- Most operating systems have programs that can make calls, like Skype or FaceTime. -- Websites can make phone calls with {{domxref("Navigator/registerProtocolHandler", "registerProtocolHandler")}}, such as `web.skype.com`. -- Other behaviors include saving the number to contacts, or sending the number to another device. - -See {{RFC(3966)}} for syntax, additional features, and other details about the `tel:` URL scheme. - -### Using the download attribute to save a \<canvas> as a PNG - -To save a {{HTMLElement("canvas")}} element's contents as an image, you can create a link where the `href` is the canvas data as a `data:` URL created with JavaScript and the `download` attribute provides the file name for the downloaded PNG file: - -#### Example painting app with save link - -##### HTML - -```html -<p> - Paint by holding down the mouse button and moving it. - <a href="" download="my_painting.png">Download my painting</a> -</p> - -<canvas width="300" height="300"></canvas> -``` - -##### CSS - -```css -html { - font-family: sans-serif; -} -canvas { - background: #fff; - border: 1px dashed; -} -a { - display: inline-block; - background: #69c; - color: #fff; - padding: 5px 10px; -} -``` - -##### JavaScript - -```js -const canvas = document.querySelector("canvas"); -const c = canvas.getContext("2d"); -c.fillStyle = "hotpink"; -let isDrawing; - -function draw(x, y) { - if (isDrawing) { - c.beginPath(); - c.arc(x, y, 10, 0, Math.PI * 2); - c.closePath(); - c.fill(); - } -} - -canvas.addEventListener("mousemove", (event) => - draw(event.offsetX, event.offsetY), -); -canvas.addEventListener("mousedown", () => (isDrawing = true)); -canvas.addEventListener("mouseup", () => (isDrawing = false)); - -document - .querySelector("a") - .addEventListener( - "click", - (event) => (event.target.href = canvas.toDataURL()), - ); -``` - -##### Result - -{{EmbedLiveSample('Example_painting_app_with_save_link', '100%', '400')}} - -## Security and privacy - -`<a>` elements can have consequences for users' security and privacy. See [`Referer` header: privacy and security concerns](/en-US/docs/Web/Security/Referer_header:_privacy_and_security_concerns) for information. - -Using `target="_blank"` without [`rel="noreferrer"`](/en-US/docs/Web/HTML/Attributes/rel/noreferrer) and [`rel="noopener"`](/en-US/docs/Web/HTML/Attributes/rel/noopener) makes the website vulnerable to {{domxref("window.opener")}} API exploitation attacks, although note that, in newer browser versions setting `target="_blank"` implicitly provides the same protection as setting `rel="noopener"`. See [browser compatibility](#browser_compatibility) for details. - -## Technical summary - -<table class="properties"> - <tbody> - <tr> - <th scope="row"> - <a href="/en-US/docs/Web/HTML/Content_categories" - >Content categories</a - > - </th> - <td> - <a href="/en-US/docs/Web/HTML/Content_categories#flow_content" - >Flow content</a - >, - <a href="/en-US/docs/Web/HTML/Content_categories#phrasing_content" - >phrasing content</a - >, - <a - href="/en-US/docs/Web/HTML/Content_categories#interactive_content" - >interactive content</a - >, palpable content. - </td> - </tr> - <tr> - <th scope="row">Permitted content</th> - <td> - <a - href="/en-US/docs/Web/HTML/Content_categories#transparent_content_model" - >Transparent</a - >, except that no descendant may be - <a - href="/en-US/docs/Web/HTML/Content_categories#interactive_content" - >interactive content</a - > or an - <code>&lt;a&gt;</code> element, and no descendant may have a specified - <a - href="/en-US/docs/Web/HTML/Global_attributes/tabindex" - >tabindex</a - > attribute. - </td> - </tr> - <tr> - <th scope="row">Tag omission</th> - <td>None, both the starting and ending tag are mandatory.</td> - </tr> - <tr> - <th scope="row">Permitted parents</th> - <td> - Any element that accepts - <a href="/en-US/docs/Web/HTML/Content_categories#flow_content" - >flow content</a - >, but not other <code>&lt;a&gt;</code> elements. - </td> - </tr> - <tr> - <th scope="row">Implicit ARIA role</th> - <td> - <a href="/en-US/docs/Web/Accessibility/ARIA/Roles/link_role"><code>link</code></a> when <code>href</code> attribute is - present, otherwise - <a href="/en-US/docs/Web/Accessibility/ARIA/Roles/generic_role"><code>generic</code></a> - </td> - </tr> - <tr> - <th scope="row">Permitted ARIA roles</th> - <td> - <p>When <code>href</code> attribute is present:</p> - <ul> - <li><a href="/en-US/docs/Web/Accessibility/ARIA/Roles/button_role"><code>button</code></a></li> - <li><a href="/en-US/docs/Web/Accessibility/ARIA/Roles/checkbox_role"><code>checkbox</code></a></li> - <li><a href="/en-US/docs/Web/Accessibility/ARIA/Roles/menuitem_role"><code>menuitem</code></a></li> - <li><a href="/en-US/docs/Web/Accessibility/ARIA/Roles/menuitemcheckbox_role"><code>menuitemcheckbox</code></a></li> - <li><a href="/en-US/docs/Web/Accessibility/ARIA/Roles/menuitemradio_role"><code>menuitemradio</code></a></li> - <li><a href="/en-US/docs/Web/Accessibility/ARIA/Roles/option_role"><code>option</code></a></li> - <li><a href="/en-US/docs/Web/Accessibility/ARIA/Roles/radio_role"><code>radio</code></a></li> - <li><a href="/en-US/docs/Web/Accessibility/ARIA/Roles/switch_role"><code>switch</code></a></li> - <li><a href="/en-US/docs/Web/Accessibility/ARIA/Roles/tab_role"><code>tab</code></a></li> - <li><a href="/en-US/docs/Web/Accessibility/ARIA/Roles/treeitem_role"><code>treeitem</code></a></li> - </ul> - <p>When <code>href</code> attribute is not present:</p> - <ul> - <li>any</li> - </ul> - </td> - </tr> - <tr> - <th scope="row">DOM interface</th> - <td>{{DOMxRef("HTMLAnchorElement")}}</td> - </tr> - </tbody> -</table> - -## Specifications - -{{Specifications}} - -## Browser compatibility - -{{Compat}} - -## See also - -- {{HTMLElement("link")}} is similar to `<a>`, but for metadata hyperlinks that are invisible to users. -- {{CSSxRef(":link")}} is a CSS pseudo-class that will match `<a>` elements with URL in `href` attribute that was not yet visited by the user. -- {{CSSxRef(":visited")}} is a CSS pseudo-class that will match `<a>` elements with URL in `href` attribute that was visited by the user in the past. -- {{CSSxRef(":any-link")}} is a CSS pseudo-class that will match `<a>` elements with `href` attribute. -- [Text fragments](/en-US/docs/Web/URI/Reference/Fragment/Text_fragments) are user-agent instructions added to URLs that allow content authors to link to specific text on a page, without IDs being required. diff --git a/files/en-us/web/html/element/abbr/index.md b/files/en-us/web/html/element/abbr/index.md deleted file mode 100644 index d60343b4481c746..000000000000000 --- a/files/en-us/web/html/element/abbr/index.md +++ /dev/null @@ -1,222 +0,0 @@ ---- -title: "<abbr>: The Abbreviation element" -slug: Web/HTML/Element/abbr -page-type: html-element -browser-compat: html.elements.abbr ---- - -{{HTMLSidebar}} - -The **`<abbr>`** [HTML](/en-US/docs/Web/HTML) element represents an abbreviation or acronym. - -When including an abbreviation or acronym, provide a full expansion of the term in plain text on first use, along with the `<abbr>` to mark up the abbreviation. This informs the user what the abbreviation or acronym means. - -The optional [`title`](/en-US/docs/Web/HTML/Global_attributes/title) attribute can provide an expansion for the abbreviation or acronym when a full expansion is not present. This provides a hint to user agents on how to announce/display the content while informing all users what the abbreviation means. If present, `title` must contain this full description and nothing else. - -{{InteractiveExample("HTML Demo: &lt;abbr&gt;", "tabbed-shorter")}} - -```html interactive-example -<p> - You can use <abbr>CSS</abbr> (Cascading Style Sheets) to style your - <abbr>HTML</abbr> (HyperText Markup Language). Using style sheets, you can - keep your <abbr>CSS</abbr> presentation layer and <abbr>HTML</abbr> content - layer separate. This is called "separation of concerns." -</p> -``` - -```css interactive-example -abbr { - font-style: italic; - color: chocolate; -} -``` - -## Attributes - -This element only supports the [global attributes](/en-US/docs/Web/HTML/Global_attributes). The [`title`](/en-US/docs/Web/HTML/Global_attributes/title) attribute has a specific semantic meaning when used with the `<abbr>` element; it _must_ contain a full human-readable description or expansion of the abbreviation. This text is often presented by browsers as a tooltip when the mouse cursor is hovered over the element. - -Each `<abbr>` element you use is independent of all others; providing a `title` for one does not automatically attach the same expansion text to others with the same content text. - -## Usage notes - -### Typical use cases - -It's certainly not required that all abbreviations be marked up using `<abbr>`. There are, though, a few cases where it's helpful to do so: - -- When an abbreviation is used and you want to provide an expansion or definition outside the flow of the document's content, use `<abbr>` with an appropriate [`title`](/en-US/docs/Web/HTML/Global_attributes/title). -- To define an abbreviation which may be unfamiliar to the reader, present the term using `<abbr>` and inline text providing the definition. Include a `title` attribute only when the inline expansion or definition is not available. -- When an abbreviation's presence in the text needs to be semantically noted, the `<abbr>` element is useful. This can be used, in turn, for styling or scripting purposes. -- You can use `<abbr>` in concert with {{HTMLElement("dfn")}} to establish definitions for terms which are abbreviations or acronyms. See the example [Defining an abbreviation](#defining_an_abbreviation) below. - -### Grammar considerations - -In languages with [grammatical number](https://en.wikipedia.org/wiki/Grammatical_number) (that is, languages where the number of items affects the grammar of a sentence), use the same grammatical number in your `title` attribute as inside your `<abbr>` element. This is especially important in languages with more than two numbers, such as Arabic, but is also relevant in English. - -## Default styling - -The purpose of this element is purely for the convenience of the author and all browsers display it inline ({{cssxref("display", "display: inline")}}) by default, though its default styling varies from one browser to another: - -Some browsers add a dotted underline to the content of the element. Others add a dotted underline while converting the contents to small caps. Others may not style it differently than a {{HTMLElement("span")}} element. To control this styling, use {{cssxref('text-decoration')}} and {{cssxref('font-variant')}}. - -## Accessibility - -Spelling out the acronym or abbreviation in full the first time it is used on a page is beneficial for helping people understand it, especially if the content is technical or industry jargon. - -Only include a `title` if expanding the abbreviation or acronym in the text is not possible. Having a difference between the announced word or phrase and what is displayed on the screen, especially if it's technical jargon the reader may not be familiar with, can be jarring. - -```html -<p> - JavaScript Object Notation (<abbr>JSON</abbr>) is a lightweight - data-interchange format. -</p> -``` - -{{EmbedLiveSample("Accessibility")}} - -This is especially helpful for people who are unfamiliar with the terminology or concepts discussed in the content, people who are new to the language, and people with cognitive concerns. - -## Examples - -### Marking up an abbreviation semantically - -To mark up an abbreviation without providing an expansion or description, use `<abbr>` without any attributes, as seen in this example. - -#### HTML - -```html -<p>Using <abbr>HTML</abbr> is fun and easy!</p> -``` - -#### Result - -{{EmbedLiveSample("Marking_up_an_abbreviation_semantically")}} - -### Styling abbreviations - -You can use CSS to set a custom style to be used for abbreviations, as seen in this basic example. - -#### HTML - -```html -<p>Using <abbr>CSS</abbr>, you can style your abbreviations!</p> -``` - -#### CSS - -```css -abbr { - font-variant: all-small-caps; -} -``` - -#### Result - -{{EmbedLiveSample("Styling_abbreviations")}} - -### Providing an expansion - -Adding a [`title`](/en-US/docs/Web/HTML/Global_attributes/title) attribute lets you provide an expansion or definition for the abbreviation or acronym. - -#### HTML - -```html -<p>Ashok's joke made me <abbr title="Laugh Out Loud">LOL</abbr> big time.</p> -``` - -#### Result - -{{EmbedLiveSample("Providing_an_expansion")}} - -### Defining an abbreviation - -You can use `<abbr>` in tandem with {{HTMLElement("dfn")}} to more formally define an abbreviation, as shown here. - -#### HTML - -```html -<p> - <dfn id="html"><abbr title="HyperText Markup Language">HTML</abbr> </dfn> is a - markup language used to create the semantics and structure of a web page. -</p> - -<p> - A <dfn id="spec">Specification</dfn> (<abbr>spec</abbr>) is a document that - outlines in detail how a technology or API is intended to function and how it - is accessed. -</p> -``` - -#### Result - -{{EmbedLiveSample("Defining_an_abbreviation", 600, 120)}} - -## Technical summary - -<table class="properties"> - <tbody> - <tr> - <th scope="row"> - <a href="/en-US/docs/Web/HTML/Content_categories" - >Content categories</a - > - </th> - <td> - <a href="/en-US/docs/Web/HTML/Content_categories#flow_content" - >Flow content</a - >, - <a href="/en-US/docs/Web/HTML/Content_categories#phrasing_content" - >phrasing content</a - >, palpable content - </td> - </tr> - <tr> - <th scope="row">Permitted content</th> - <td> - <a href="/en-US/docs/Web/HTML/Content_categories#phrasing_content" - >Phrasing content</a - > - </td> - </tr> - <tr> - <th scope="row">Tag omission</th> - <td>None, both the starting and ending tag are mandatory.</td> - </tr> - <tr> - <th scope="row">Permitted parents</th> - <td> - Any element that accepts - <a href="/en-US/docs/Web/HTML/Content_categories#phrasing_content" - >phrasing content</a - > - </td> - </tr> - <tr> - <th scope="row">Implicit ARIA role</th> - <td> - <a href="https://www.w3.org/TR/html-aria/#dfn-no-corresponding-role" - >No corresponding role</a - > - </td> - </tr> - <tr> - <th scope="row">Permitted ARIA roles</th> - <td>Any</td> - </tr> - <tr> - <th scope="row">DOM Interface</th> - <td>{{domxref("HTMLElement")}}</td> - </tr> - </tbody> -</table> - -## Specifications - -{{Specifications}} - -## Browser compatibility - -{{Compat}} - -## See also - -- [Using the `<abbr>` element](/en-US/docs/Learn_web_development/Core/Structuring_content/Advanced_text_features#abbreviations) diff --git a/files/en-us/web/html/element/acronym/index.md b/files/en-us/web/html/element/acronym/index.md deleted file mode 100644 index 29928e0663867ea..000000000000000 --- a/files/en-us/web/html/element/acronym/index.md +++ /dev/null @@ -1,59 +0,0 @@ ---- -title: <acronym> -slug: Web/HTML/Element/acronym -page-type: html-element -status: - - deprecated -browser-compat: html.elements.acronym ---- - -{{HTMLSidebar}}{{deprecated_header}} - -The **`<acronym>`** [HTML](/en-US/docs/Web/HTML) element allows authors to clearly indicate a sequence of characters that compose an acronym or abbreviation for a word. - -> [!WARNING] -> Don't use this element. Use the {{HTMLElement("abbr")}} element instead. - -## Attributes - -This element only has [global attributes](/en-US/docs/Web/HTML/Global_attributes), which are common to all elements. - -## DOM Interface - -This element implements the {{domxref('HTMLElement')}} interface. - -## Examples - -```html -<p> - The <acronym title="World Wide Web">WWW</acronym> is only a component of the - Internet. -</p> -``` - -### Result - -{{EmbedLiveSample('Examples')}} - -## Default styling - -Though the purpose of this tag is purely for the convenience of the author, its default styling varies from one browser to another: - -- Opera, Firefox, Chrome, and some others add a dotted underline to the content of the element. -- A few browsers not only add a dotted underline, but also put it in small caps; to avoid this styling, adding something like {{cssxref("font-variant", "font-variant: none")}} in the CSS takes care of this case. - -It is therefore recommended that web authors either explicitly style this element, or accept some cross-browser variation. - -<!-- ## Technical summary --> - -## Specifications - -{{Specifications}} - -## Browser compatibility - -{{Compat}} - -## See also - -- The {{HTMLElement("abbr")}} HTML element diff --git a/files/en-us/web/html/element/address/index.md b/files/en-us/web/html/element/address/index.md deleted file mode 100644 index d060645e3b46a2a..000000000000000 --- a/files/en-us/web/html/element/address/index.md +++ /dev/null @@ -1,157 +0,0 @@ ---- -title: "<address>: The Contact Address element" -slug: Web/HTML/Element/address -page-type: html-element -browser-compat: html.elements.address ---- - -{{HTMLSidebar}} - -The **`<address>`** [HTML](/en-US/docs/Web/HTML) element indicates that the enclosed HTML provides contact information for a person or people, or for an organization. - -{{InteractiveExample("HTML Demo: &lt;address&gt;", "tabbed-standard")}} - -```html interactive-example -<p>Contact the author of this page:</p> - -<address> - <a href="mailto:jim@example.com">jim@example.com</a><br /> - <a href="tel:+14155550132">+1 (415) 555‑0132</a> -</address> -``` - -```css interactive-example -a[href^="mailto"]::before { - content: "📧 "; -} - -a[href^="tel"]::before { - content: "📞 "; -} -``` - -The contact information provided by an `<address>` element's contents can take whatever form is appropriate for the context, and may include any type of contact information that is needed, such as a physical address, URL, email address, phone number, social media handle, geographic coordinates, and so forth. The `<address>` element should include the name of the person, people, or organization to which the contact information refers. - -`<address>` can be used in a variety of contexts, such as providing a business's contact information in the page header, or indicating the author of an article by including an `<address>` element within the {{HTMLElement("article")}}. - -## Attributes - -This element only includes the [global attributes](/en-US/docs/Web/HTML/Global_attributes). - -## Usage notes - -- The `<address>` element can only be used to represent the contact information for its nearest {{HTMLElement("article")}} or {{HTMLElement("body")}} element ancestor. -- This element should not contain more information than the contact information, like a publication date (which belongs in a {{HTMLElement("time")}} element). -- Typically an `<address>` element can be placed inside the {{HTMLElement("footer")}} element of the current section, if any. - -## Examples - -This example demonstrates the use of `<address>` to demarcate the contact information for an article's author. - -```html -<address> - You can contact author at - <a href="http://www.example.com/contact">www.example.com</a>.<br /> - If you see any bugs, please - <a href="mailto:webmaster@example.com">contact webmaster</a>.<br /> - You may also want to visit us:<br /> - Mozilla Foundation<br /> - 331 E Evelyn Ave<br /> - Mountain View, CA 94041<br /> - USA -</address> -``` - -### Result - -{{EmbedLiveSample("Examples", "300", "200")}} - -Although it renders text with the same default styling as the {{HTMLElement("i")}} or {{HTMLElement("em")}} elements, it is more appropriate to use `<address>` when dealing with contact information, as it conveys additional semantic information. - -## Technical summary - -<table class="properties"> - <tbody> - <tr> - <th scope="row"> - <a href="/en-US/docs/Web/HTML/Content_categories" - >Content categories</a - > - </th> - <td> - <a href="/en-US/docs/Web/HTML/Content_categories#flow_content" - >Flow content</a - >, palpable content. - </td> - </tr> - <tr> - <th scope="row">Permitted content</th> - <td> - <a href="/en-US/docs/Web/HTML/Content_categories#flow_content" - >Flow content</a - >, but with no nested <code>&#x3C;address></code> element, no heading - content ({{HTMLElement("hgroup")}}, {{HTMLElement("Heading_Elements", "h1")}}, - {{HTMLElement("Heading_Elements", "h2")}}, {{HTMLElement("Heading_Elements", "h3")}}, - {{HTMLElement("Heading_Elements", "h4")}}, {{HTMLElement("Heading_Elements", "h5")}}, - {{HTMLElement("Heading_Elements", "h6")}}), no sectioning content - ({{HTMLElement("article")}}, {{HTMLElement("aside")}}, - {{HTMLElement("section")}}, {{HTMLElement("nav")}}), and - no {{HTMLElement("header")}} or {{HTMLElement("footer")}} - element. - </td> - </tr> - <tr> - <th scope="row">Tag omission</th> - <td>None, both the starting and ending tag are mandatory.</td> - </tr> - <tr> - <th scope="row">Permitted parents</th> - <td> - Any element that accepts - <a href="/en-US/docs/Web/HTML/Content_categories#flow_content" - >flow content</a - >, but always excluding <code>&#x3C;address></code> elements (according - to the logical principle of symmetry, if - <code>&#x3C;address></code> tag, as a parent, can not have nested - <code>&#x3C;address></code> element, then the same - <code>&#x3C;address></code> content can not have - <code>&#x3C;address></code> tag as its parent). - </td> - </tr> - <tr> - <th scope="row">Implicit ARIA role</th> - <td> - <code - ><a href="/en-US/docs/Web/Accessibility/ARIA/Roles/group_role" - >group</a - ></code - > - </td> - </tr> - <tr> - <th scope="row">Permitted ARIA roles</th> - <td>Any</td> - </tr> - <tr> - <th scope="row">DOM interface</th> - <td> - {{domxref("HTMLElement")}} Prior to Gecko 2.0 (Firefox 4), - Gecko implemented this element using the - {{domxref("HTMLSpanElement")}} interface - </td> - </tr> - </tbody> -</table> - -## Specifications - -{{Specifications}} - -## Browser compatibility - -{{Compat}} - -## See also - -- Others section-related elements: {{HTMLElement("body")}}, {{HTMLElement("nav")}}, {{HTMLElement("article")}}, {{HTMLElement("aside")}}, {{HTMLElement("Heading_Elements", "h1")}}, {{HTMLElement("Heading_Elements", "h2")}}, {{HTMLElement("Heading_Elements", "h3")}}, {{HTMLElement("Heading_Elements", "h4")}}, {{HTMLElement("Heading_Elements", "h5")}}, {{HTMLElement("Heading_Elements", "h6")}}, {{HTMLElement("hgroup")}}, {{HTMLElement("footer")}}, {{HTMLElement("section")}}, {{HTMLElement("header")}}; -- [Sections and outlines of an HTML document](/en-US/docs/Web/HTML/Element/Heading_Elements). diff --git a/files/en-us/web/html/element/area/index.md b/files/en-us/web/html/element/area/index.md deleted file mode 100644 index 476a61c467f95ad..000000000000000 --- a/files/en-us/web/html/element/area/index.md +++ /dev/null @@ -1,206 +0,0 @@ ---- -title: "<area>: The Image Map Area element" -slug: Web/HTML/Element/area -page-type: html-element -browser-compat: html.elements.area ---- - -{{HTMLSidebar}} - -The **`<area>`** [HTML](/en-US/docs/Web/HTML) element defines an area inside an image map that has predefined clickable areas. An _image map_ allows geometric areas on an image to be associated with {{Glossary("Hyperlink", "hypertext links")}}. - -This element is used only within a {{HTMLElement("map")}} element. - -{{InteractiveExample("HTML Demo: &lt;area&gt;", "tabbed-taller")}} - -```html interactive-example -<map name="infographic"> - <area - shape="poly" - coords="129,0,260,95,129,138" - href="https://developer.mozilla.org/docs/Web/HTTP" - alt="HTTP" /> - <area - shape="poly" - coords="260,96,209,249,130,138" - href="https://developer.mozilla.org/docs/Web/HTML" - alt="HTML" /> - <area - shape="poly" - coords="209,249,49,249,130,139" - href="https://developer.mozilla.org/docs/Web/JavaScript" - alt="JavaScript" /> - <area - shape="poly" - coords="48,249,0,96,129,138" - href="https://developer.mozilla.org/docs/Web/API" - alt="Web APIs" /> - <area - shape="poly" - coords="0,95,128,0,128,137" - href="https://developer.mozilla.org/docs/Web/CSS" - alt="CSS" /> -</map> -<img - usemap="#infographic" - src="/shared-assets/images/examples/mdn-info.png" - alt="MDN infographic" /> -``` - -```css interactive-example -img { - display: block; - margin: 0 auto; - width: 260px; - height: 260px; -} -``` - -## Attributes - -This element's attributes include the [global attributes](/en-US/docs/Web/HTML/Global_attributes). - -- `alt` - - : A text string alternative to display on browsers that do not display images. - The text should be phrased so that it presents the user with the same kind of choice as the image would offer when displayed without the alternative text. - This attribute is required only if the [`href`](#href) attribute is used. -- `coords` - - - : The `coords` attribute details the coordinates of the [`shape`](#shape) attribute in size, shape, and placement of an `<area>`. - This attribute must not be used if `shape` is set to `default`. - - - `rect`: the value is `x1,y1,x2,y2`. - The value specifies the coordinates of the top-left and bottom-right corner of the rectangle. - For example, in `<area shape="rect" coords="0,0,253,27" href="#" target="_blank" alt="Mozilla">` the coordinates are `0,0` and `253,27`, indicating the top-left and bottom-right corners of the rectangle, respectively. - - `circle`: the value is `x,y,radius`. Value specifies the coordinates of the circle center and the radius. - For example: `<area shape="circle" coords="130,136,60" href="#" target="_blank" alt="MDN">` - - `poly`: the value is `x1,y1,x2,y2,..,xn,yn`. Value specifies the coordinates of the edges of the polygon. - If the first and last coordinate pairs are not the same, the browser will add the last coordinate pair to close the polygon - - The values are numbers of CSS pixels. - -- `download` - - : This attribute, if present, indicates that the linked resource is intended to be downloaded rather than displayed in the browser. - See {{HTMLElement("a")}} for a full description of the [`download`](/en-US/docs/Web/HTML/Element/a#download) attribute. -- `href` - - : The hyperlink target for the area. - Its value is a valid URL. - This attribute may be omitted; if so, the `<area>` element does not represent a hyperlink. -- `ping` - - : Contains a space-separated list of URLs to which, when the hyperlink is followed, {{HTTPMethod("POST")}} requests with the body `PING` will be sent by the browser (in the background). - Typically used for tracking. -- `referrerpolicy` - - - : A string indicating which referrer to use when fetching the resource: - - - `no-referrer`: The {{HTTPHeader("Referer")}} header will not be sent. - - `no-referrer-when-downgrade`: The {{HTTPHeader("Referer")}} header will not be sent to {{Glossary("origin")}}s without {{Glossary("TLS")}} ({{Glossary("HTTPS")}}). - - `origin`: The sent referrer will be limited to the origin of the referring page: its [scheme](/en-US/docs/Learn_web_development/Howto/Web_mechanics/What_is_a_URL), {{Glossary("host")}}, and {{Glossary("port")}}. - - `origin-when-cross-origin`: The referrer sent to other origins will be limited to the scheme, the host, and the port. Navigations on the same origin will still include the path. - - `same-origin`: A referrer will be sent for {{Glossary("Same-origin policy", "same origin")}}, but cross-origin requests will contain no referrer information. - - `strict-origin`: Only send the origin of the document as the referrer when the protocol security level stays the same (HTTPS→HTTPS), but don't send it to a less secure destination (HTTPS→HTTP). - - `strict-origin-when-cross-origin` (default): Send a full URL when performing a same-origin request, only send the origin when the protocol security level stays the same (HTTPS→HTTPS), and send no header to a less secure destination (HTTPS→HTTP). - - `unsafe-url`: The referrer will include the origin _and_ the path (but not the [fragment](/en-US/docs/Web/API/HTMLAnchorElement/hash), [password](/en-US/docs/Web/API/HTMLAnchorElement/password), or [username](/en-US/docs/Web/API/HTMLAnchorElement/username)). - **This value is unsafe**, because it leaks origins and paths from TLS-protected resources to insecure origins. - -- [`rel`](/en-US/docs/Web/HTML/Attributes/rel) - - : For anchors containing the [`href`](#href) attribute, this attribute specifies the relationship of the target object to the link object. - The value is a space-separated list of link types. - The values and their semantics will be registered by some authority that might have meaning to the document author. - The default relationship, if no other is given, is void. Use this attribute only if the [`href`](#href) attribute is present. -- `shape` - - : The shape of the associated hot spot. The specifications for HTML defines the values `rect`, which defines a rectangular region; `circle`, which defines a circular region; `poly`, which defines a polygon; and `default`, which indicates the entire region beyond any defined shapes. -- `target` - - - : A keyword or author-defined name of the {{Glossary("browsing context")}} to display the linked resource. - The following keywords have special meanings: - - - `_self` (default): Show the resource in the current browsing context. - - `_blank`: Show the resource in a new, unnamed browsing context. - - `_parent`: Show the resource in the parent browsing context of the current one, if the current page is inside a frame. - If there is no parent, acts the same as `_self`. - - `_top`: Show the resource in the topmost browsing context (the browsing context that is an ancestor of the current one and has no parent). - If there is no parent, acts the same as `_self`. - - Use this attribute only if the [`href`](#href) attribute is present. - - > [!NOTE] - > Setting `target="_blank"` on `<area>` elements implicitly provides the same `rel` behavior as setting [`rel="noopener"`](/en-US/docs/Web/HTML/Attributes/rel/noopener) which does not set `window.opener`. See [browser compatibility](#browser_compatibility) for support status. - -## Examples - -```html -<map name="primary"> - <area - shape="circle" - coords="75,75,75" - href="left.html" - alt="Click to go Left" /> - <area - shape="circle" - coords="275,75,75" - href="right.html" - alt="Click to go Right" /> -</map> -<img - usemap="#primary" - src="https://dummyimage.com/350x150" - alt="350 x 150 pic" /> -``` - -### Result - -{{ EmbedLiveSample('Examples', 360, 160) }} - -## Technical summary - -<table class="properties"> - <tbody> - <tr> - <th scope="row"> - <a href="/en-US/docs/Web/HTML/Content_categories">Content categories</a> - </th> - <td> - <a href="/en-US/docs/Web/HTML/Content_categories#flow_content">Flow content</a>, - <a href="/en-US/docs/Web/HTML/Content_categories#phrasing_content">phrasing content</a>. - </td> - </tr> - <tr> - <th scope="row">Permitted content</th> - <td>None; it is a {{Glossary("void element")}}.</td> - </tr> - <tr> - <th scope="row">Tag omission</th> - <td>Must have a start tag and must not have an end tag.</td> - </tr> - <tr> - <th scope="row">Permitted parents</th> - <td> - Any element that accepts <a href="/en-US/docs/Web/HTML/Content_categories#phrasing_content">phrasing content</a>. The <code>&#x3C;area></code> element must have an ancestor {{HTMLElement("map")}}, but it need not be a direct parent. - </td> - </tr> - <tr> - <th scope="row">Implicit ARIA role</th> - <td> - <a href="/en-US/docs/Web/Accessibility/ARIA/Roles/link_role"><code>link</code></a> when <a href="#href"><code>href</code></a> attribute is present, otherwise - <a href="/en-US/docs/Web/Accessibility/ARIA/Roles/generic_role"><code>generic</code></a> - </td> - </tr> - <tr> - <th scope="row">Permitted ARIA roles</th> - <td>No <code>role</code> permitted</td> - </tr> - <tr> - <th scope="row">DOM interface</th> - <td>{{domxref("HTMLAreaElement")}}</td> - </tr> - </tbody> -</table> - -## Specifications - -{{Specifications}} - -## Browser compatibility - -{{Compat}} diff --git a/files/en-us/web/html/element/article/index.md b/files/en-us/web/html/element/article/index.md deleted file mode 100644 index 928a66ef8aac81c..000000000000000 --- a/files/en-us/web/html/element/article/index.md +++ /dev/null @@ -1,201 +0,0 @@ ---- -title: "<article>: The Article Contents element" -slug: Web/HTML/Element/article -page-type: html-element -browser-compat: html.elements.article ---- - -{{HTMLSidebar}} - -The **`<article>`** [HTML](/en-US/docs/Web/HTML) element represents a self-contained composition in a document, page, application, or site, which is intended to be independently distributable or reusable (e.g., in syndication). Examples include: a forum post, a magazine or newspaper article, or a blog entry, a product card, a user-submitted comment, an interactive widget or gadget, or any other independent item of content. - -{{InteractiveExample("HTML Demo: &lt;article&gt;", "tabbed-standard")}} - -```html interactive-example -<article class="forecast"> - <h1>Weather forecast for Seattle</h1> - <article class="day-forecast"> - <h2>03 March 2018</h2> - <p>Rain.</p> - </article> - <article class="day-forecast"> - <h2>04 March 2018</h2> - <p>Periods of rain.</p> - </article> - <article class="day-forecast"> - <h2>05 March 2018</h2> - <p>Heavy rain.</p> - </article> -</article> -``` - -```css interactive-example -.forecast { - margin: 0; - padding: 0.3rem; - background-color: #eee; -} - -.forecast > h1, -.day-forecast { - margin: 0.5rem; - padding: 0.3rem; - font-size: 1.2rem; -} - -.day-forecast { - background: right/contain content-box border-box no-repeat - url("/shared-assets/images/examples/rain.svg") white; -} - -.day-forecast > h2, -.day-forecast > p { - margin: 0.2rem; - font-size: 1rem; -} -``` - -A given document can have multiple articles in it; for example, on a blog that shows the text of each article one after another as the reader scrolls, each post would be contained in an `<article>` element, possibly with one or more `<section>`s within. - -## Attributes - -This element only includes the [global attributes](/en-US/docs/Web/HTML/Global_attributes). - -## Usage notes - -- Each `<article>` should be identified, typically by including a heading ([`<h1>` - `<h6>`](/en-US/docs/Web/HTML/Element/Heading_Elements) element) as a child of the `<article>` element. -- When an `<article>` element is nested, the inner element represents an article related to the outer element. For example, the comments of a blog post can be `<article>` elements nested in the `<article>` representing the blog post. -- Author information of an `<article>` element can be provided through the {{HTMLElement("address")}} element, but it doesn't apply to nested `<article>` elements. -- The publication date and time of an `<article>` element can be described using the [`datetime`](/en-US/docs/Web/HTML/Element/time#datetime) attribute of a {{HTMLElement("time")}} element. - -## Examples - -```html -<article class="film_review"> - <h2>Jurassic Park</h2> - <section class="main_review"> - <h3>Review</h3> - <p>Dinos were great!</p> - </section> - <section class="user_reviews"> - <h3>User reviews</h3> - <article class="user_review"> - <h4>Too scary!</h4> - <p>Way too scary for me.</p> - <footer> - <p> - Posted on - <time datetime="2015-05-16 19:00">May 16</time> - by Lisa. - </p> - </footer> - </article> - <article class="user_review"> - <h4>Love the dinos!</h4> - <p>I agree, dinos are my favorite.</p> - <footer> - <p> - Posted on - <time datetime="2015-05-17 19:00">May 17</time> - by Tom. - </p> - </footer> - </article> - </section> - <footer> - <p> - Posted on - <time datetime="2015-05-15 19:00">May 15</time> - by Staff. - </p> - </footer> -</article> -``` - -### Result - -{{EmbedLiveSample('Examples','','570')}} - -## Technical summary - -<table class="properties"> - <tbody> - <tr> - <th scope="row"> - <a href="/en-US/docs/Web/HTML/Content_categories" - >Content categories</a - > - </th> - <td> - <a href="/en-US/docs/Web/HTML/Content_categories#flow_content" - >Flow content</a - >, - <a - href="/en-US/docs/Web/HTML/Content_categories#sectioning_content" - >sectioning content</a - >, - <a href="/en-US/docs/Web/HTML/Content_categories#palpable_content" - >palpable content</a - > - </td> - </tr> - <tr> - <th scope="row">Permitted content</th> - <td> - <a href="/en-US/docs/Web/HTML/Content_categories#flow_content" - >Flow content</a - >. - </td> - </tr> - <tr> - <th scope="row">Tag omission</th> - <td>None, both the starting and ending tag are mandatory.</td> - </tr> - <tr> - <th scope="row">Permitted parents</th> - <td> - Any element that accepts - <a href="/en-US/docs/Web/HTML/Content_categories#flow_content" - >flow content</a - >. Note that an <code>&#x3C;article></code> element must not be a - descendant of an {{HTMLElement("address")}} element. - </td> - </tr> - <tr> - <th scope="row">Implicit ARIA role</th> - <td> - <code - ><a href="/en-US/docs/Web/Accessibility/ARIA/Roles/article_role" - >article</a - ></code - > - </td> - </tr> - <tr> - <th scope="row">Permitted ARIA roles</th> - <td> - <a href="/en-US/docs/Web/Accessibility/ARIA/Roles/application_role"><code>application</code></a>, <a href="/en-US/docs/Web/Accessibility/ARIA/Roles/document_role"><code>document</code></a>, - <a href="/en-US/docs/Web/Accessibility/ARIA/Roles/feed_role"><code>feed</code></a>, <a href="/en-US/docs/Web/Accessibility/ARIA/Roles/main_role"><code>main</code></a>, - <a href="/en-US/docs/Web/Accessibility/ARIA/Roles/none_role"><code>none</code></a>, <a href="/en-US/docs/Web/Accessibility/ARIA/Roles/presentation_role"><code>presentation</code></a>, - <a href="/en-US/docs/Web/Accessibility/ARIA/Roles/region_role"><code>region</code></a> - </td> - </tr> - <tr> - <th scope="row">DOM interface</th> - <td>{{domxref("HTMLElement")}}</td> - </tr> - </tbody> -</table> - -## Specifications - -{{Specifications}} - -## Browser compatibility - -{{Compat}} - -## See also - -- Other section-related elements: {{HTMLElement("body")}}, {{HTMLElement("nav")}}, {{HTMLElement("section")}}, {{HTMLElement("aside")}}, {{HTMLElement("Heading_Elements", "h1")}}, {{HTMLElement("Heading_Elements", "h2")}}, {{HTMLElement("Heading_Elements", "h3")}}, {{HTMLElement("Heading_Elements", "h4")}}, {{HTMLElement("Heading_Elements", "h5")}}, {{HTMLElement("Heading_Elements", "h6")}}, {{HTMLElement("hgroup")}}, {{HTMLElement("header")}}, {{HTMLElement("footer")}}, {{HTMLElement("address")}} -- [Using HTML sections and outlines](/en-US/docs/Web/HTML/Element/Heading_Elements) diff --git a/files/en-us/web/html/element/aside/index.md b/files/en-us/web/html/element/aside/index.md deleted file mode 100644 index 8bc36f67e2fc940..000000000000000 --- a/files/en-us/web/html/element/aside/index.md +++ /dev/null @@ -1,161 +0,0 @@ ---- -title: "<aside>: The Aside element" -slug: Web/HTML/Element/aside -page-type: html-element -browser-compat: html.elements.aside ---- - -{{HTMLSidebar}} - -The **`<aside>`** [HTML](/en-US/docs/Web/HTML) element represents a portion of a document whose content is only indirectly related to the document's main content. Asides are frequently presented as sidebars or call-out boxes. - -{{InteractiveExample("HTML Demo: &lt;aside&gt;", "tabbed-standard")}} - -```html interactive-example -<p> - Salamanders are a group of amphibians with a lizard-like appearance, including - short legs and a tail in both larval and adult forms. -</p> - -<aside> - <p>The Rough-skinned Newt defends itself with a deadly neurotoxin.</p> -</aside> - -<p> - Several species of salamander inhabit the temperate rainforest of the Pacific - Northwest, including the Ensatina, the Northwestern Salamander and the - Rough-skinned Newt. Most salamanders are nocturnal, and hunt for insects, - worms and other small creatures. -</p> -``` - -```css interactive-example -aside { - width: 40%; - padding-left: 0.5rem; - margin-left: 0.5rem; - float: right; - box-shadow: inset 5px 0 5px -5px #29627e; - font-style: italic; - color: #29627e; -} - -aside > p { - margin: 0.5rem; -} -``` - -## Attributes - -This element only includes the [global attributes](/en-US/docs/Web/HTML/Global_attributes). - -## Usage notes - -- Do not use the `<aside>` element to tag parenthesized text, as this kind of text is considered part of the main flow. - -## Examples - -### Using \<aside> - -This example uses `<aside>` to mark up a paragraph in an article. The paragraph is only indirectly related to the main article content: - -```html -<article> - <p> - The Disney movie <cite>The Little Mermaid</cite> was first released to - theatres in 1989. - </p> - <aside> - <p>The movie earned $87 million during its initial release.</p> - </aside> - <p>More info about the movie…</p> -</article> -``` - -#### Result - -{{EmbedLiveSample("Using_aside")}} - -## Technical summary - -<table class="properties"> - <tbody> - <tr> - <th scope="row"> - <a href="/en-US/docs/Web/HTML/Content_categories" - >Content categories</a - > - </th> - <td> - <a href="/en-US/docs/Web/HTML/Content_categories#flow_content" - >Flow content</a - >, - <a - href="/en-US/docs/Web/HTML/Content_categories#sectioning_content" - >sectioning content</a - >, - <a href="/en-US/docs/Web/HTML/Content_categories#palpable_content" - >palpable content</a - >. - </td> - </tr> - <tr> - <th scope="row">Permitted content</th> - <td> - <a href="/en-US/docs/Web/HTML/Content_categories#flow_content" - >Flow content</a - >. - </td> - </tr> - <tr> - <th scope="row">Tag omission</th> - <td>None, both the starting and ending tag are mandatory.</td> - </tr> - <tr> - <th scope="row">Permitted parents</th> - <td> - Any element that accepts - <a href="/en-US/docs/Web/HTML/Content_categories#flow_content" - >flow content</a - >. Note that an <code>&#x3C;aside></code> element must not be a - descendant of an {{HTMLElement("address")}} element. - </td> - </tr> - <tr> - <th scope="row">Implicit ARIA role</th> - <td> - <code - ><a href="/en-US/docs/Web/Accessibility/ARIA/Roles/complementary_role" - >complementary</a - ></code - > - </td> - </tr> - <tr> - <th scope="row">Permitted ARIA roles</th> - <td> - <a href="/en-US/docs/Web/Accessibility/ARIA/Roles/feed_role"><code>feed</code></a>, <a href="/en-US/docs/Web/Accessibility/ARIA/Roles/none_role"><code>none</code></a>, - <a href="/en-US/docs/Web/Accessibility/ARIA/Roles/note_role"><code>note</code></a>, <a href="/en-US/docs/Web/Accessibility/ARIA/Roles/presentation_role"><code>presentation</code></a>, - <a href="/en-US/docs/Web/Accessibility/ARIA/Roles/region_role"><code>region</code></a>, <a href="/en-US/docs/Web/Accessibility/ARIA/Roles/search_role"><code>search</code></a> - </td> - </tr> - <tr> - <th scope="row">DOM interface</th> - <td>{{domxref("HTMLElement")}}</td> - </tr> - </tbody> -</table> - -## Specifications - -{{Specifications}} - -## Browser compatibility - -{{Compat}} - -## See also - -- Other section-related elements: {{HTMLElement("body")}}, {{HTMLElement("article")}}, {{HTMLElement("section")}}, {{HTMLElement("nav")}}, {{HTMLElement("Heading_Elements", "h1")}}, {{HTMLElement("Heading_Elements", "h2")}}, {{HTMLElement("Heading_Elements", "h3")}}, {{HTMLElement("Heading_Elements", "h4")}}, {{HTMLElement("Heading_Elements", "h5")}}, {{HTMLElement("Heading_Elements", "h6")}}, {{HTMLElement("hgroup")}}, {{HTMLElement("header")}}, {{HTMLElement("footer")}}, {{HTMLElement("address")}}; -- [Using HTML sections and outlines](/en-US/docs/Web/HTML/Element/Heading_Elements) -- [ARIA: Complementary role](/en-US/docs/Web/Accessibility/ARIA/Roles/complementary_role) diff --git a/files/en-us/web/html/element/audio/index.md b/files/en-us/web/html/element/audio/index.md deleted file mode 100644 index d317077356bf50d..000000000000000 --- a/files/en-us/web/html/element/audio/index.md +++ /dev/null @@ -1,505 +0,0 @@ ---- -title: "<audio>: The Embed Audio element" -slug: Web/HTML/Element/audio -page-type: html-element -browser-compat: html.elements.audio ---- - -{{HTMLSidebar}} - -The **`<audio>`** [HTML](/en-US/docs/Web/HTML) element is used to embed sound content in documents. It may contain one or more audio sources, represented using the `src` attribute or the {{HTMLElement("source")}} element: the browser will choose the most suitable one. It can also be the destination for streamed media, using a {{domxref("MediaStream")}}. - -{{InteractiveExample("HTML Demo: &lt;audio&gt;", "tabbed-standard")}} - -```html interactive-example -<figure> - <figcaption>Listen to the T-Rex:</figcaption> - <audio controls src="/shared-assets/audio/t-rex-roar.mp3"></audio> - <a href="/shared-assets/audio/t-rex-roar.mp3"> Download audio </a> -</figure> -``` - -```css interactive-example -figure { - margin: 0; -} -``` - -The above example shows basic usage of the `<audio>` element. In a similar manner to the {{htmlelement("img")}} element, we include a path to the media we want to embed inside the `src` attribute; we can include other attributes to specify information such as whether we want it to autoplay and loop, whether we want to show the browser's default audio controls, etc. - -The content inside the opening and closing `<audio></audio>` tags is shown as a fallback in browsers that don't support the element. - -## Attributes - -This element's attributes include the [global attributes](/en-US/docs/Web/HTML/Global_attributes). - -- `autoplay` - - - : A Boolean attribute: if specified, the audio will automatically begin playback as soon as it can do so, without waiting for the entire audio file to finish downloading. - - > [!NOTE] - > Sites that automatically play audio (or videos with an audio track) can be an unpleasant experience for users, so should be avoided when possible. If you must offer autoplay functionality, you should make it opt-in (requiring a user to specifically enable it). However, this can be useful when creating media elements whose source will be set at a later time, under user control. See our [autoplay guide](/en-US/docs/Web/Media/Guides/Autoplay) for additional information about how to properly use autoplay. - -- `controls` - - - : If this attribute is present, the browser will offer controls to allow the user to control audio playback, including volume, seeking, and pause/resume playback. - -- `controlslist` - - - : The [`controlslist`](https://wicg.github.io/controls-list/explainer.html) attribute, when specified, helps the browser select what controls to show for the `audio` element whenever the browser shows its own set of controls (that is, when the `controls` attribute is specified). - - The allowed values are `nodownload`, `nofullscreen` and `noremoteplayback`. - -- [`crossorigin`](/en-US/docs/Web/HTML/Attributes/crossorigin) - - - : This [enumerated](/en-US/docs/Glossary/Enumerated) attribute indicates whether to use CORS to fetch the related audio file. [CORS-enabled resources](/en-US/docs/Web/HTML/CORS_enabled_image) can be reused in the {{HTMLElement("canvas")}} element without being _tainted_. The allowed values are: - - - `anonymous` - - : Sends a cross-origin request without a credential. In other words, it sends the `Origin:` HTTP header without a cookie, X.509 certificate, or performing HTTP Basic authentication. If the server does not give credentials to the origin site (by not setting the `Access-Control-Allow-Origin:` HTTP header), the resource will be _tainted_, and its usage restricted. - - `use-credentials` - - : Sends a cross-origin request with a credential. In other words, it sends the `Origin:` HTTP header with a cookie, a certificate, or performing HTTP Basic authentication. If the server does not give credentials to the origin site (through `Access-Control-Allow-Credentials:` HTTP header), the resource will be _tainted_ and its usage restricted. - - When not present, the resource is fetched without a CORS request (i.e. without sending the `Origin:` HTTP header), preventing its non-tainted use in {{HTMLElement('canvas')}} elements. If invalid, it is handled as if the enumerated keyword **anonymous** was used. See [CORS settings attributes](/en-US/docs/Web/HTML/Attributes/crossorigin) for additional information. - -- `disableremoteplayback` - - - : A Boolean attribute used to disable the capability of remote playback in devices that are attached using wired (HDMI, DVI, etc.) and wireless technologies (Miracast, Chromecast, DLNA, AirPlay, etc.). See [this proposed specification](https://www.w3.org/TR/remote-playback/#the-disableremoteplayback-attribute) for more information. - - In Safari, you can use [`x-webkit-airplay="deny"`](https://developer.apple.com/library/archive/documentation/AudioVideo/Conceptual/AirPlayGuide/OptingInorOutofAirPlay/OptingInorOutofAirPlay.html) as a fallback. - -- `loop` - - : A Boolean attribute: if specified, the audio player will automatically seek back to the start upon reaching the end of the audio. -- `muted` - - : A Boolean attribute that indicates whether the audio will be initially silenced. Its default value is `false`. -- `preload` - - - : This {{Glossary("enumerated")}} attribute is intended to provide a hint to the browser about what the author thinks will lead to the best user experience. It may have one of the following values: - - - `none`: Indicates that the audio should not be preloaded. - - `metadata`: Indicates that only audio metadata (e.g. length) is fetched. - - `auto`: Indicates that the whole audio file can be downloaded, even if the user is not expected to use it. - - _empty string_: A synonym of the `auto` value. - - The default value is different for each browser. The spec advises it to be set to `metadata`. - - > [!NOTE] - > - > - The `autoplay` attribute has precedence over `preload`. If `autoplay` is specified, the browser would obviously need to start downloading the audio for playback. - > - The browser is not forced by the specification to follow the value of this attribute; it is a mere hint. - -- `src` - - : The URL of the audio to embed. This is subject to [HTTP access controls](/en-US/docs/Web/HTTP/CORS). This is optional; you may instead use the {{htmlelement("source")}} element within the audio block to specify the audio to embed. - -## Events - -<table class="no-markdown"> - <thead> - <tr> - <th scope="col">Event name</th> - <th scope="col">Fired when</th> - </tr> - </thead> - <tbody> - <tr> - <td>{{domxref("ScriptProcessorNode/audioprocess_event", "audioprocess")}}</td> - <td> - The input buffer of a {{DOMxRef("ScriptProcessorNode")}} is - ready to be processed. - </td> - </tr> - <tr> - <td> - {{domxref("HTMLMediaElement.canplay_event", 'canplay')}} - </td> - <td> - The browser can play the media, but estimates that not enough data has - been loaded to play the media up to its end without having to stop for - further buffering of content. - </td> - </tr> - <tr> - <td> - {{domxref("HTMLMediaElement.canplaythrough_event", 'canplaythrough')}} - </td> - <td> - The browser estimates it can play the media up to its end without - stopping for content buffering. - </td> - </tr> - <tr> - <td>{{domxref("OfflineAudioContext/complete_event", "complete")}}</td> - <td> - The rendering of an {{DOMxRef("OfflineAudioContext")}} is - terminated. - </td> - </tr> - <tr> - <td> - {{domxref("HTMLMediaElement.durationchange_event", 'durationchange')}} - </td> - <td>The <code>duration</code> attribute has been updated.</td> - </tr> - <tr> - <td> - {{domxref("HTMLMediaElement.emptied_event", 'emptied')}} - </td> - <td> - The media has become empty; for example, this event is sent if the media - has already been loaded (or partially loaded), and the - {{domxref("HTMLMediaElement.load")}} method is called to - reload it. - </td> - </tr> - <tr> - <td> - {{domxref("HTMLMediaElement.ended_event", 'ended')}} - </td> - <td>Playback has stopped because the end of the media was reached.</td> - </tr> - <tr> - <td> - {{domxref("HTMLMediaElement.loadeddata_event", 'loadeddata')}} - </td> - <td>The first frame of the media has finished loading.</td> - </tr> - <tr> - <td> - {{domxref("HTMLMediaElement.loadedmetadata_event", 'loadedmetadata')}} - </td> - <td>The metadata has been loaded.</td> - </tr> - <tr> - <td> - {{domxref("HTMLMediaElement.loadstart_event", 'loadstart')}} - </td> - <td>Fired when the browser has started to load the resource.</td> - </tr> - <tr> - <td> - {{domxref("HTMLMediaElement.pause_event", 'pause')}} - </td> - <td>Playback has been paused.</td> - </tr> - <tr> - <td> - {{domxref("HTMLMediaElement.play_event", 'play')}} - </td> - <td>Playback has begun.</td> - </tr> - <tr> - <td> - {{domxref("HTMLMediaElement.playing_event", 'playing')}} - </td> - <td> - Playback is ready to start after having been paused or delayed due to - lack of data. - </td> - </tr> - <tr> - <td> - {{domxref("HTMLMediaElement.ratechange_event", 'ratechange')}} - </td> - <td>The playback rate has changed.</td> - </tr> - <tr> - <td> - {{domxref("HTMLMediaElement.seeked_event", 'seeked')}} - </td> - <td>A <em>seek</em> operation completed.</td> - </tr> - <tr> - <td> - {{domxref("HTMLMediaElement.seeking_event", 'seeking')}} - </td> - <td>A <em>seek</em> operation began.</td> - </tr> - <tr> - <td> - {{domxref("HTMLMediaElement.stalled_event", 'stalled')}} - </td> - <td> - The user agent is trying to fetch media data, but data is unexpectedly - not forthcoming. - </td> - </tr> - <tr> - <td> - {{domxref("HTMLMediaElement.suspend_event", 'suspend')}} - </td> - <td>Media data loading has been suspended.</td> - </tr> - <tr> - <td> - {{domxref("HTMLMediaElement.timeupdate_event", 'timeupdate')}} - </td> - <td> - The time indicated by the <code>currentTime</code> attribute has been - updated. - </td> - </tr> - <tr> - <td> - {{domxref("HTMLMediaElement.volumechange_event", 'volumechange')}} - </td> - <td>The volume has changed.</td> - </tr> - <tr> - <td> - {{domxref("HTMLMediaElement.waiting_event", 'waiting')}} - </td> - <td>Playback has stopped because of a temporary lack of data</td> - </tr> - </tbody> -</table> - -## Usage notes - -Browsers don't all support the same [file types](/en-US/docs/Web/Media/Guides/Formats/Containers) and [audio codecs](/en-US/docs/Web/Media/Guides/Formats/Audio_codecs); you can provide multiple sources inside nested {{htmlelement("source")}} elements, and the browser will then use the first one it understands: - -```html -<audio controls> - <source src="myAudio.mp3" type="audio/mpeg" /> - <source src="myAudio.ogg" type="audio/ogg" /> - <p> - Download <a href="myAudio.mp3" download="myAudio.mp3">MP3</a> or - <a href="myAudio.ogg" download="myAudio.ogg">OGG</a> audio. - </p> -</audio> -``` - -The audio source can be set to any valid [URL](/en-US/docs/Web/URI), including HTTP(S) URLs and [Data URLs](/en-US/docs/Web/URI/Reference/Schemes/data). When using HTTP(S) URLs, be aware that the browser's caching behavior will affect how often the file is requested from the server. Data URLs embed the audio data directly in the HTML, which can be useful for small audio files but isn't recommended for larger files as it increases the HTML file size. - -You can also use the [Web Audio API](/en-US/docs/Web/API/Web_Audio_API) to directly generate and manipulate audio streams from JavaScript code rather than streaming pre-existing audio files. You can set the [`srcObject`](/en-US/docs/Web/API/HTMLMediaElement/srcObject) in JavaScript to a {{domxref("MediaStream")}} object. This is commonly used for live audio streams or real-time audio processing. - -```js -const audioElement = document.querySelector("audio"); -navigator.mediaDevices - .getUserMedia({ audio: true }) - .then((stream) => { - audioElement.srcObject = stream; - }) - .catch((error) => { - console.error("Error accessing the microphone", error); - }); -``` - -Note that `MediaStream` sources have limitations: they are not seekable and only support a limited set of codecs. - -We offer a substantive and thorough [guide to media file types](/en-US/docs/Web/Media/Guides/Formats) and the [audio codecs that can be used within them](/en-US/docs/Web/Media/Guides/Formats/Audio_codecs). Also available is [a guide to the codecs supported for video](/en-US/docs/Web/Media/Guides/Formats/Video_codecs). - -Other usage notes: - -- If you don't specify the `controls` attribute, the audio player won't include the browser's default controls. You can, however, create your own custom controls using JavaScript and the {{domxref("HTMLMediaElement")}} API. -- To allow precise control over your audio content, `HTMLMediaElement`s fire many different [events](/en-US/docs/Web/API/HTMLMediaElement#events). This also provides a way to monitor the audio's fetching process so you can watch for errors or detect when enough is available to begin to play or manipulate it. -- `<audio>` elements can't have subtitles or captions associated with them in the same way that `<video>` elements can. See [WebVTT and Audio](https://www.iandevlin.com/blog/2015/12/html5/webvtt-and-audio/) by Ian Devlin for some useful information and workarounds. -- To test the fallback content on browsers that support the element, you can replace `<audio>` with a non-existing element like `<notanaudio>`. - -A good general source of information on using HTML `<audio>` is the [HTML video and audio](/en-US/docs/Learn_web_development/Core/Structuring_content/HTML_video_and_audio) beginner's tutorial. - -### Styling with CSS - -The `<audio>` element has no intrinsic visual output of its own unless the `controls` attribute is specified, in which case the browser's default controls are shown. - -The default controls have a {{cssxref("display")}} value of `inline` by default, and it is often a good idea to set the value to `block` to improve control over positioning and layout, unless you want it to sit within a text block or similar. - -You can style the default controls with properties that affect the block as a single unit, so for example you can give it a {{cssxref("border")}} and {{cssxref("border-radius")}}, {{cssxref("padding")}}, {{cssxref("margin")}}, etc. You can't however style the individual components inside the audio player (e.g. change the button size or icons, change the font, etc.), and the controls are different across the different browsers. - -To get a consistent look and feel across browsers, you'll need to create custom controls; these can be marked up and styled in whatever way you want, and then JavaScript can be used along with the {{domxref("HTMLMediaElement")}} API to wire up their functionality. - -[Video player styling basics](/en-US/docs/Web/Media/Guides/Audio_and_video_delivery/Video_player_styling_basics) provides some useful styling techniques — it is written in the context of `<video>`, but much of it is equally applicable to `<audio>`. - -### Detecting addition and removal of tracks - -You can detect when tracks are added to and removed from an `<audio>` element using the {{domxref("AudioTrackList/addtrack_event", "addtrack")}} and {{domxref("AudioTrackList/removetrack_event", "removetrack")}} events. However, these events aren't sent directly to the `<audio>` element itself. Instead, they're sent to the track list object within the `<audio>` element's {{domxref("HTMLMediaElement")}} that corresponds to the type of track that was added to the element: - -- {{domxref("HTMLMediaElement.audioTracks")}} - - : An {{domxref("AudioTrackList")}} containing all of the media element's audio tracks. You can add a listener for `addtrack` to this object to be alerted when new audio tracks are added to the element. -- {{domxref("HTMLMediaElement.videoTracks")}} - - : Add an `addtrack` listener to this {{domxref("VideoTrackList")}} object to be informed when video tracks are added to the element. -- {{domxref("HTMLMediaElement.textTracks")}} - - : Add an `addtrack` event listener to this {{domxref("TextTrackList")}} to be notified when new text tracks are added to the element. - -> [!NOTE] -> Even though it's an `<audio>` element, it still has video and text track lists, and can in fact be used to present video, although the user interface implications can be odd. - -For example, to detect when audio tracks are added to or removed from an `<audio>` element, you can use code like this: - -```js -const elem = document.querySelector("audio"); - -elem.audioTrackList.onaddtrack = (event) => { - trackEditor.addTrack(event.track); -}; - -elem.audioTrackList.onremovetrack = (event) => { - trackEditor.removeTrack(event.track); -}; -``` - -This code watches for audio tracks to be added to and removed from the element, and calls a hypothetical function on a track editor to register and remove the track from the editor's list of available tracks. - -You can also use {{domxref("EventTarget.addEventListener", "addEventListener()")}} to listen for the {{domxref("AudioTrackList/addtrack_event", "addtrack")}} and {{domxref("AudioTrackList/removetrack_event", "removetrack")}} events. - -## Accessibility - -Audio with spoken dialog should provide both captions and transcripts that accurately describe its content. Captions, which are specified using [WebVTT](/en-US/docs/Web/API/WebVTT_API), allow people who are hearing impaired to understand an audio recording's content as the recording is being played, while transcripts allow people who need additional time to be able to review the recording's content at a pace and format that is comfortable for them. - -If automatic captioning services are used, it is important to review the generated content to ensure it accurately represents the source audio. - -The `<audio>` element doesn't directly support WebVTT. You will have to find a library or framework that provides the capability for you, or write the code to display captions yourself. One option is to play your audio using a {{HTMLElement("video")}} element, which does support WebVTT. - -In addition to spoken dialog, subtitles and transcripts should also identify music and sound effects that communicate important information. This includes emotion and tone. For example, in the WebVTT below, note the use of square brackets to provide tone and emotional insight to the viewer; this can help establish the mood otherwise provided using music, nonverbal sounds and crucial sound effects, and so forth. - -<!-- cSpell:ignore switchwatch Swisswatch --> - -```plain -1 -00:00:00 --> 00:00:45 -[Energetic techno music] - -2 -00:00:46 --> 00:00:51 -Welcome to the Time Keeper's podcast! In this episode we're discussing which Swisswatch is a wrist switchwatch? - -16 -00:00:52 --> 00:01:02 -[Laughing] Sorry! I mean, which wristwatch is a Swiss wristwatch? -``` - -Also it's a good practice to provide some content (such as the direct download link) as a fallback for viewers who use a browser in which the `<audio>` element is not supported: - -```html -<audio controls> - <source src="myAudio.mp3" type="audio/mpeg" /> - <source src="myAudio.ogg" type="audio/ogg" /> - <p> - Download <a href="myAudio.mp3">MP3</a> or - <a href="myAudio.ogg" download="myAudio.ogg">OGG</a> audio. - </p> -</audio> -``` - -- [Web Video Text Tracks Format (WebVTT)](/en-US/docs/Web/API/WebVTT_API) -- [WebAIM: Captions, Transcripts, and Audio Descriptions](https://webaim.org/techniques/captions/) -- [MDN Understanding WCAG, Guideline 1.2 explanations](/en-US/docs/Web/Accessibility/Understanding_WCAG/Perceivable#guideline_1.2_—_providing_text_alternatives_for_time-based_media) -- [Understanding Success Criterion 1.2.1 | W3C Understanding WCAG 2.0](https://www.w3.org/TR/UNDERSTANDING-WCAG20/media-equiv-av-only-alt.html) -- [Understanding Success Criterion 1.2.2 | W3C Understanding WCAG 2.0](https://www.w3.org/TR/UNDERSTANDING-WCAG20/media-equiv-captions.html) - -## Examples - -### Basic usage - -The following example shows basic usage of the `<audio>` element to play an OGG file. It will autoplay due to the `autoplay` attribute—if the page has permission to do so—and also includes fallback content. - -```html -<!-- Basic audio playback --> -<audio src="AudioTest.ogg" autoplay> - <a href="AudioTest.ogg" download="AudioTest.ogg">Download OGG audio</a>. -</audio> -``` - -For details on when autoplay works, how to get permission to use autoplay, and how and when it's appropriate to use autoplay, see our [autoplay guide](/en-US/docs/Web/Media/Guides/Autoplay). - -### \<audio> element with \<source> element - -This example specifies which audio track to embed using the `src` attribute on a nested `<source>` element rather than directly on the `<audio>` element. It is always useful to include the file's MIME type inside the `type` attribute, as the browser is able to instantly tell if it can play that file, and not waste time on it if not. - -```html -<audio controls> - <source src="foo.wav" type="audio/wav" /> - <a href="foo.wav" download="foo.wav">Download WAV audio</a>. -</audio> -``` - -### \<audio> with multiple \<source> elements - -This example includes multiple `<source>` elements. The browser tries to load the first source element (Opus) if it is able to play it; if not it falls back to the second (Vorbis) and finally back to MP3: - -```html -<audio controls> - <source src="foo.opus" type="audio/ogg; codecs=opus" /> - <source src="foo.ogg" type="audio/ogg; codecs=vorbis" /> - <source src="foo.mp3" type="audio/mpeg" /> -</audio> -``` - -## Technical summary - -<table class="properties"> - <tbody> - <tr> - <th scope="row"> - <a href="/en-US/docs/Web/HTML/Content_categories" - >Content categories</a - > - </th> - <td> - <a href="/en-US/docs/Web/HTML/Content_categories#flow_content" - >Flow content</a - >, phrasing content, embedded content. If it has a - <a href="#controls"><code>controls</code></a> attribute: interactive - content and palpable content. - </td> - </tr> - <tr> - <th scope="row">Permitted content</th> - <td> - If the element has a <a href="#src"><code>src</code></a> - attribute: zero or more {{HTMLElement("track")}} elements - followed by transparent content that contains no - <code>&lt;audio&gt;</code> or {{HTMLElement("video")}} - media elements.<br />Else: zero or more {{HTMLElement("source")}} - elements followed by zero or more {{HTMLElement("track")}} - elements followed by transparent content that contains no - <code>&lt;audio&gt;</code> or {{HTMLElement("video")}} - media elements. - </td> - </tr> - <tr> - <th scope="row">Tag omission</th> - <td>None, both the starting and ending tag are mandatory.</td> - </tr> - <tr> - <th scope="row">Permitted parents</th> - <td>Any element that accepts embedded content.</td> - </tr> - <tr> - <th scope="row">Implicit ARIA role</th> - <td> - <a href="https://www.w3.org/TR/html-aria/#dfn-no-corresponding-role" - >No corresponding role</a - > - </td> - </tr> - <tr> - <th scope="row">Permitted ARIA roles</th> - <td><a href="/en-US/docs/Web/Accessibility/ARIA/Roles/application_role"><code>application</code></a></td> - </tr> - <tr> - <th scope="row">DOM interface</th> - <td>{{domxref("HTMLAudioElement")}}</td> - </tr> - </tbody> -</table> - -## Specifications - -{{Specifications}} - -## Browser compatibility - -{{Compat}} - -## See also - -- [Web media technologies](/en-US/docs/Web/Media) - - - [Media container formats (file types)](/en-US/docs/Web/Media/Guides/Formats/Containers) - - [Guide to audio codecs used on the web](/en-US/docs/Web/Media/Guides/Formats/Audio_codecs) - -- [Web Audio API](/en-US/docs/Web/API/Web_Audio_API) -- {{domxref("HTMLAudioElement")}} -- {{htmlelement("source")}} -- {{htmlelement("video")}} -- [Learning area: HTML video and audio](/en-US/docs/Learn_web_development/Core/Structuring_content/HTML_video_and_audio) -- [Cross-browser audio basics](/en-US/docs/Web/Media/Guides/Audio_and_video_delivery/Cross-browser_audio_basics) diff --git a/files/en-us/web/html/element/b/index.md b/files/en-us/web/html/element/b/index.md deleted file mode 100644 index b4e76d5badf485a..000000000000000 --- a/files/en-us/web/html/element/b/index.md +++ /dev/null @@ -1,129 +0,0 @@ ---- -title: "<b>: The Bring Attention To element" -slug: Web/HTML/Element/b -page-type: html-element -browser-compat: html.elements.b ---- - -{{HTMLSidebar}} - -The **`<b>`** [HTML](/en-US/docs/Web/HTML) element is used to draw the reader's attention to the element's contents, which are not otherwise granted special importance. This was formerly known as the Boldface element, and most browsers still draw the text in boldface. However, you should not use `<b>` for styling text or granting importance. If you wish to create boldface text, you should use the CSS {{cssxref("font-weight")}} property. If you wish to indicate an element is of special importance, you should use the {{HTMLElement("strong")}} element. - -{{InteractiveExample("HTML Demo: &lt;b&gt;", "tabbed-shorter")}} - -```html interactive-example -<p> - The two most popular science courses offered by the school are - <b class="term">chemistry</b> (the study of chemicals and the composition of - substances) and <b class="term">physics</b> (the study of the nature and - properties of matter and energy). -</p> -``` - -```css interactive-example -/* stylelint-disable-next-line block-no-empty */ -b { -} -``` - -## Attributes - -This element only includes the [global attributes](/en-US/docs/Web/HTML/Global_attributes). - -## Usage notes - -- Use the `<b>` for cases like keywords in a summary, product names in a review, or other spans of text whose typical presentation would be boldfaced (but not including any special importance). -- Do not confuse the `<b>` element with the {{HTMLElement("strong")}}, {{HTMLElement("em")}}, or {{HTMLElement("mark")}} elements. The {{HTMLElement("strong")}} element represents text of certain _importance_, {{HTMLElement("em")}} puts some emphasis on the text and the {{HTMLElement("mark")}} element represents text of certain _relevance_. The `<b>` element doesn't convey such special semantic information; use it only when no others fit. -- Similarly, do not mark titles and headings using the `<b>` element. For this purpose, use the {{HTMLElement("Heading_Elements", "h1")}} to {{HTMLElement("Heading_Elements", "h6")}} tags. Further, stylesheets can change the default style of these elements, with the result that they are not _necessarily_ displayed in bold. -- It is a good practice to use the [`class`](/en-US/docs/Web/HTML/Global_attributes/class) attribute on the `<b>` element in order to convey additional semantic information as needed (for example `<b class="lead">` for the first sentence in a paragraph). This makes it easier to manage multiple use cases of `<b>` if your stylistic needs change, without the need to change all of its uses in the HTML. -- Historically, the `<b>` element was meant to make text boldface. Styling information has been deprecated since HTML4, so the meaning of the `<b>` element has been changed. -- If there is no semantic purpose to using the `<b>` element, you should use the CSS {{cssxref("font-weight")}} property with the value `"bold"` instead in order to make text bold. - -## Examples - -```html -<p> - This article describes several <b class="keywords">text-level</b> elements. It - explains their usage in an <b class="keywords">HTML</b> document. -</p> -Keywords are displayed with the default style of the -<b>element, likely in bold.</b> -``` - -### Result - -{{EmbedLiveSample("Examples")}} - -## Technical summary - -<table class="properties"> - <tbody> - <tr> - <th scope="row"> - <a href="/en-US/docs/Web/HTML/Content_categories" - >Content categories</a - > - </th> - <td> - <a href="/en-US/docs/Web/HTML/Content_categories#flow_content" - >Flow content</a - >, - <a href="/en-US/docs/Web/HTML/Content_categories#phrasing_content" - >phrasing content</a - >, palpable content. - </td> - </tr> - <tr> - <th scope="row">Permitted content</th> - <td> - <a href="/en-US/docs/Web/HTML/Content_categories#phrasing_content" - >Phrasing content</a - >. - </td> - </tr> - <tr> - <th scope="row">Tag omission</th> - <td>None, both the starting and ending tag are mandatory.</td> - </tr> - <tr> - <th scope="row">Permitted parents</th> - <td> - Any element that accepts - <a href="/en-US/docs/Web/HTML/Content_categories#phrasing_content" - >phrasing content</a - >. - </td> - </tr> - <tr> - <th scope="row">Implicit ARIA role</th> - <td> - <code - ><a href="/en-US/docs/Web/Accessibility/ARIA/Roles/generic_role" - >generic</a - ></code - > - </td> - </tr> - <tr> - <th scope="row">Permitted ARIA roles</th> - <td>Any</td> - </tr> - <tr> - <th scope="row">DOM interface</th> - <td>{{domxref("HTMLElement")}}</td> - </tr> - </tbody> -</table> - -## Specifications - -{{Specifications}} - -## Browser compatibility - -{{Compat}} - -## See also - -- Other elements conveying text-level semantics: {{HTMLElement("a")}}, {{HTMLElement("em")}}, {{HTMLElement("strong")}}, {{HTMLElement("small")}}, {{HTMLElement("cite")}}, {{HTMLElement("q")}}, {{HTMLElement("dfn")}}, {{HTMLElement("abbr")}}, {{HTMLElement("time")}}, {{HTMLElement("code")}}, {{HTMLElement("var")}}, {{HTMLElement("samp")}}, {{HTMLElement("kbd")}}, {{HTMLElement("sub")}}, {{HTMLElement("sup")}}, {{HTMLElement("i")}}, {{HTMLElement("mark")}}, {{HTMLElement("ruby")}}, {{HTMLElement("rp")}}, {{HTMLElement("rt")}}, {{HTMLElement("bdo")}}, {{HTMLElement("span")}}, {{HTMLElement("br")}}, {{HTMLElement("wbr")}}. -- [Using \<b> and \<i> elements (W3C)](https://www.w3.org/International/questions/qa-b-and-i-tags) diff --git a/files/en-us/web/html/element/base/index.md b/files/en-us/web/html/element/base/index.md deleted file mode 100644 index c2115ce7b559592..000000000000000 --- a/files/en-us/web/html/element/base/index.md +++ /dev/null @@ -1,115 +0,0 @@ ---- -title: "<base>: The Document Base URL element" -slug: Web/HTML/Element/base -page-type: html-element -browser-compat: html.elements.base ---- - -{{HTMLSidebar}} - -The **`<base>`** [HTML](/en-US/docs/Web/HTML) element specifies the base URL to use for all _relative_ URLs in a document. There can be only one `<base>` element in a document. - -A document's used base URL can be accessed by scripts with {{domxref('Node.baseURI')}}. If the document has no `<base>` elements, then `baseURI` defaults to {{domxref("location.href")}}. - -## Attributes - -This element's attributes include the [global attributes](/en-US/docs/Web/HTML/Global_attributes). - -> [!WARNING] -> A `<base>` element must have an `href` attribute, a `target` attribute, or both. -> If at least one of these attributes are specified, the `<base>` element **must** come before other elements with attribute values that are URLs, such as a {{HTMLElement("link")}}'s `href` attribute. - -- `href` - - : The base URL to be used throughout the document for relative URLs. - Absolute and relative URLs are allowed. - [`data:`](/en-US/docs/Web/URI/Reference/Schemes/data) and [`javascript:`](/en-US/docs/Web/URI/Reference/Schemes/javascript) URLs are not allowed. -- `target` - - - : A **keyword** or **author-defined name** of the default {{Glossary("browsing context")}} to show the results of navigation from {{HTMLElement("a")}}, {{HTMLElement("area")}}, or {{HTMLElement("form")}} elements without explicit `target` attributes. The following keywords have special meanings: - - - `_self` (default): Show the result in the current browsing context. - - `_blank`: Show the result in a new, unnamed browsing context. - - `_parent`: Show the result in the parent browsing context of the current one, if the current page is inside a frame. If there is no parent, acts the same as `_self`. - - `_top`: Show the result in the topmost browsing context (the browsing context that is an ancestor of the current one and has no parent). If there is no parent, acts the same as `_self`. - -## Usage notes - -### Multiple \<base> elements - -If multiple `<base>` elements are used, only the first `href` and first `target` are obeyed — all others are ignored. - -### In-page anchors - -Links pointing to a fragment in the document — e.g. `<a href="#some-id">` — are resolved with the `<base>`, triggering an HTTP request to the base URL with the fragment attached. - -For example, given `<base href="https://example.com/">` and this link: `<a href="#anchor">To anchor</a>`. The link points to `https://example.com/#anchor`. - -### target may not contain ASCII newline, tab, or < - -If the [`target`](#target) attribute contains an ASCII newline, tab, or the `<` character, the value is reset to `_blank`. -This is to prevent dangling markup injection attacks, a script-less attack in which an unclosed `target` attribute is injected into the page so that any text that follows is captured until the browser reaches a character that closes the attribute. - -### Open Graph - -[Open Graph](https://ogp.me/) tags do not acknowledge `<base>`, and should always have full absolute URLs. For example: - -```html -<meta property="og:image" content="https://example.com/thumbnail.jpg" /> -``` - -## Examples - -```html -<base href="https://www.example.com/" /> -<base target="_blank" /> -<base target="_top" href="https://example.com/" /> -``` - -## Technical summary - -<table class="properties"> - <tbody> - <tr> - <th scope="row"> - <a href="/en-US/docs/Web/HTML/Content_categories">Content categories</a> - </th> - <td>Metadata content.</td> - </tr> - <tr> - <th scope="row">Permitted content</th> - <td>None; it is a {{Glossary("void element")}}.</td> - </tr> - <tr> - <th scope="row">Tag omission</th> - <td>Must have a start tag and must not have an end tag.</td> - </tr> - <tr> - <th scope="row">Permitted parents</th> - <td> - A {{HTMLElement("head")}} that doesn't contain another <code>&lt;base&gt;</code> element. - </td> - </tr> - <tr> - <th scope="row">Implicit ARIA role</th> - <td> - <a href="https://www.w3.org/TR/html-aria/#dfn-no-corresponding-role">No corresponding role</a> - </td> - </tr> - <tr> - <th scope="row">Permitted ARIA roles</th> - <td>No <code>role</code> permitted</td> - </tr> - <tr> - <th scope="row">DOM interface</th> - <td>{{domxref("HTMLBaseElement")}}</td> - </tr> - </tbody> -</table> - -## Specifications - -{{Specifications}} - -## Browser compatibility - -{{Compat}} diff --git a/files/en-us/web/html/element/bdi/index.md b/files/en-us/web/html/element/bdi/index.md deleted file mode 100644 index 90d35733488e367..000000000000000 --- a/files/en-us/web/html/element/bdi/index.md +++ /dev/null @@ -1,217 +0,0 @@ ---- -title: "<bdi>: The Bidirectional Isolate element" -slug: Web/HTML/Element/bdi -page-type: html-element -browser-compat: html.elements.bdi ---- - -{{HTMLSidebar}} - -The **`<bdi>`** [HTML](/en-US/docs/Web/HTML) element tells the browser's bidirectional algorithm to treat the text it contains in isolation from its surrounding text. It's particularly useful when a website dynamically inserts some text and doesn't know the directionality of the text being inserted. - -{{InteractiveExample("HTML Demo: &lt;bdi&gt;", "tabbed-standard")}} - -```html interactive-example -<h1>World wrestling championships</h1> - -<ul> - <li><bdi class="name">Evil Steven</bdi>: 1st place</li> - <li><bdi class="name">François fatale</bdi>: 2nd place</li> - <li><span class="name">سما</span>: 3rd place</li> - <li><bdi class="name">الرجل القوي إيان</bdi>: 4th place</li> - <li><span class="name" dir="auto">سما</span>: 5th place</li> -</ul> -``` - -```css interactive-example -html { - font-family: sans-serif; -} - -/* stylelint-disable-next-line block-no-empty */ -bdi { -} - -.name { - color: red; -} -``` - -Bidirectional text is text that may contain both sequences of characters that are arranged left-to-right (LTR) and sequences of characters that are arranged right-to-left (RTL), such as an Arabic quotation embedded in an English string. Browsers implement the [Unicode Bidirectional Algorithm](https://www.w3.org/International/articles/inline-bidi-markup/uba-basics) to handle this. In this algorithm, characters are given an implicit directionality: for example, Latin characters are treated as LTR while Arabic characters are treated as RTL. Some other characters (such as spaces and some punctuation) are treated as neutral and are assigned directionality based on that of their surrounding characters. - -Usually, the bidirectional algorithm will do the right thing without the author having to provide any special markup but, occasionally, the algorithm needs help. That's where `<bdi>` comes in. - -The `<bdi>` element is used to wrap a span of text and instructs the bidirectional algorithm to treat this text in isolation from its surroundings. This works in two ways: - -- The directionality of text embedded in `<bdi>` _does not influence_ the directionality of the surrounding text. -- The directionality of text embedded in `<bdi>` _is not influenced by_ the directionality of the surrounding text. - -For example, consider some text like: - -```plain -EMBEDDED-TEXT - 1st place -``` - -If `EMBEDDED-TEXT` is LTR, this works fine. But if `EMBEDDED-TEXT` is RTL, then `- 1` will be treated as RTL text (because it consists of neutral and weak characters). The result will be garbled: - -```plain -1 - EMBEDDED-TEXTst place -``` - -If you know the directionality of `EMBEDDED-TEXT` in advance, you can fix this problem by wrapping `EMBEDDED-TEXT` in a {{HTMLElement("span")}} with the [`dir`](/en-US/docs/Web/HTML/Global_attributes/dir) attribute set to the known directionality. But if you don't know the directionality - for example, because `EMBEDDED-TEXT` is being read from a database or entered by the user - you should use `<bdi>` to prevent the directionality of `EMBEDDED-TEXT` from affecting its surroundings. - -Though the same visual effect can be achieved using the CSS rule {{cssxref("unicode-bidi", "unicode-bidi: isolate")}} on a {{HTMLElement("span")}} or another text-formatting element, HTML authors should not use this approach because it is not semantic and browsers are allowed to ignore CSS styling. - -Embedding the characters in `<span dir="auto">` has the same effect as using `<bdi>`, but its semantics are less clear. - -## Attributes - -Like all other HTML elements, this element supports the [global attributes](/en-US/docs/Web/HTML/Global_attributes), except that the [`dir`](/en-US/docs/Web/HTML/Global_attributes/dir) attribute behaves differently than normal: it defaults to `auto`, meaning its value is never inherited from the parent element. This means that unless you specify a value of either `rtl` or `ltr` for `dir`, the {{Glossary("user agent")}} will determine the correct directionality to use based on the contents of the `<bdi>`. - -## Examples - -### No bdi with only LTR - -This example lists the winners of a competition using {{HTMLElement("span")}} elements only. When the names only contain LTR text the results look fine: - -```html -<ul> - <li><span class="name">Henrietta Boffin</span> - 1st place</li> - <li><span class="name">Jerry Cruncher</span> - 2nd place</li> -</ul> -``` - -```css hidden -body { - border: 1px solid #3f87a6; - max-width: calc(100% - 40px - 6px); - padding: 20px; - width: calc(100% - 40px - 6px); - border-width: 1px 1px 1px 5px; -} -``` - -{{ EmbedLiveSample('No_bdi_with_only_LTR','','120') }} - -### No bdi with RTL text - -This example lists the winners of a competition using {{HTMLElement("span")}} elements only, and one of the winners has a name consisting of RTL text. In this case the `- 1`, which consists of characters with neutral or weak directionality, will adopt the directionality of the RTL text, and the result will be garbled: - -```html -<ul> - <li><span class="name">اَلأَعْشَى</span> - 1st place</li> - <li><span class="name">Jerry Cruncher</span> - 2nd place</li> -</ul> -``` - -```css hidden -body { - border: 1px solid #3f87a6; - max-width: calc(100% - 40px - 6px); - padding: 20px; - width: calc(100% - 40px - 6px); - border-width: 1px 1px 1px 5px; -} -``` - -{{ EmbedLiveSample('No_bdi_with_RTL_text','','120') }} - -### Using bdi with LTR and RTL text - -This example lists the winners of a competition using `<bdi>` elements. These elements instruct the browser to treat the name in isolation from its embedding context, so the example output is properly ordered: - -```html -<ul> - <li><bdi class="name">اَلأَعْشَى</bdi> - 1st place</li> - <li><bdi class="name">Jerry Cruncher</bdi> - 2nd place</li> -</ul> -``` - -```css hidden -body { - border: 1px solid #3f87a6; - max-width: calc(100% - 40px - 6px); - padding: 20px; - width: calc(100% - 40px - 6px); - border-width: 1px 1px 1px 5px; -} -``` - -{{ EmbedLiveSample('Using_bdi_with_LTR_and_RTL_text','','120') }} - -## Technical summary - -<table class="properties"> - <tbody> - <tr> - <th scope="row"> - <a href="/en-US/docs/Web/HTML/Content_categories" - >Content categories</a - > - </th> - <td> - <a href="/en-US/docs/Web/HTML/Content_categories#flow_content" - >Flow content</a - >, - <a href="/en-US/docs/Web/HTML/Content_categories#phrasing_content" - >phrasing content</a - >, palpable content. - </td> - </tr> - <tr> - <th scope="row">Permitted content</th> - <td> - <a href="/en-US/docs/Web/HTML/Content_categories#phrasing_content" - >Phrasing content</a - >. - </td> - </tr> - <tr> - <th scope="row">Tag omission</th> - <td>None, both the starting and ending tag are mandatory.</td> - </tr> - <tr> - <th scope="row">Permitted parents</th> - <td> - Any element that accepts - <a href="/en-US/docs/Web/HTML/Content_categories#phrasing_content" - >phrasing content</a - >. - </td> - </tr> - <tr> - <th scope="row">Implicit ARIA role</th> - <td> - <code - ><a href="/en-US/docs/Web/Accessibility/ARIA/Roles/generic_role" - >generic</a - ></code - > - </td> - </tr> - <tr> - <th scope="row">Permitted ARIA roles</th> - <td>Any</td> - </tr> - <tr> - <th scope="row">DOM interface</th> - <td>{{domxref("HTMLElement")}}</td> - </tr> - </tbody> -</table> - -## Specifications - -{{Specifications}} - -## Browser compatibility - -{{Compat}} - -## See also - -- [Inline markup and bidirectional text in HTML](https://www.w3.org/International/articles/inline-bidi-markup/) -- [Unicode Bidirectional Algorithm basics](https://www.w3.org/International/articles/inline-bidi-markup/uba-basics) -- {{Glossary("Localization")}} -- Related HTML element: {{HTMLElement("bdo")}} -- Related CSS properties: {{cssxref("direction")}}, {{cssxref("unicode-bidi")}} diff --git a/files/en-us/web/html/element/bdo/index.md b/files/en-us/web/html/element/bdo/index.md deleted file mode 100644 index 82e13daa77b27d8..000000000000000 --- a/files/en-us/web/html/element/bdo/index.md +++ /dev/null @@ -1,149 +0,0 @@ ---- -title: "<bdo>: The Bidirectional Text Override element" -slug: Web/HTML/Element/bdo -page-type: html-element -browser-compat: html.elements.bdo ---- - -{{HTMLSidebar}} - -The **`<bdo>`** [HTML](/en-US/docs/Web/HTML) element overrides the current directionality of text, so that the text within is rendered in a different direction. - -{{InteractiveExample("HTML Demo: &lt;bdo&gt;", "tabbed-standard")}} - -```html interactive-example -<h1>Famous seaside songs</h1> - -<p>The English song "Oh I do like to be beside the seaside"</p> - -<p> - Looks like this in Hebrew: - <span dir="rtl">אה, אני אוהב להיות ליד חוף הים</span> -</p> - -<p> - In the computer's memory, this is stored as - <bdo dir="ltr">אה, אני אוהב להיות ליד חוף הים</bdo> -</p> -``` - -```css interactive-example -html { - font-family: sans-serif; -} - -/* stylelint-disable-next-line block-no-empty */ -bdo { -} -``` - -The text's characters are drawn from the starting point in the given direction; the individual characters' orientation is not affected (so characters don't get drawn backward, for example). - -## Attributes - -This element's attributes include the [global attributes](/en-US/docs/Web/HTML/Global_attributes). - -- `dir` - - - : The direction in which text should be rendered in this element's contents. Possible values are: - - - `ltr`: Indicates that the text should go in a left-to-right direction. - - `rtl`: Indicates that the text should go in a right-to-left direction. - -## Examples - -```html -<!-- Switch text direction --> -<p>This text will go left to right.</p> -<p><bdo dir="rtl">This text will go right to left.</bdo></p> -``` - -### Result - -{{EmbedLiveSample('Examples')}} - -## Notes - -The HTML 4 specification did not specify events for this element; they were added in XHTML. This is most likely an oversight. - -## Technical summary - -<table class="properties"> - <tbody> - <tr> - <th scope="row"> - <a href="/en-US/docs/Web/HTML/Content_categories" - >Content categories</a - > - </th> - <td> - <a href="/en-US/docs/Web/HTML/Content_categories#flow_content" - >Flow content</a - >, - <a href="/en-US/docs/Web/HTML/Content_categories#phrasing_content" - >phrasing content</a - >, palpable content. - </td> - </tr> - <tr> - <th scope="row">Permitted content</th> - <td> - <a href="/en-US/docs/Web/HTML/Content_categories#phrasing_content" - >Phrasing content</a - >. - </td> - </tr> - <tr> - <th scope="row">Tag omission</th> - <td>None, both the starting and ending tag are mandatory.</td> - </tr> - <tr> - <th scope="row">Permitted parents</th> - <td> - Any element that accepts - <a href="/en-US/docs/Web/HTML/Content_categories#phrasing_content" - >phrasing content</a - >. - </td> - </tr> - <tr> - <th scope="row">Implicit ARIA role</th> - <td> - <code - ><a href="/en-US/docs/Web/Accessibility/ARIA/Roles/generic_role" - >generic</a - ></code - > - </td> - </tr> - <tr> - <th scope="row">Permitted ARIA roles</th> - <td>Any</td> - </tr> - <tr> - <th scope="row">DOM interface</th> - <td> - {{domxref("HTMLElement")}} Up to Gecko 1.9.2 (Firefox 4) - inclusive, Firefox implements the - <code - ><a href="/en-US/docs/Web/API/HTMLSpanElement" - >HTMLSpanElement</a - ></code - > - interface for this element. - </td> - </tr> - </tbody> -</table> - -## Specifications - -{{Specifications}} - -## Browser compatibility - -{{Compat}} - -## See also - -- Related HTML element: {{HTMLElement("bdi")}} diff --git a/files/en-us/web/html/element/big/index.md b/files/en-us/web/html/element/big/index.md deleted file mode 100644 index 30ed6e5ea3a87c2..000000000000000 --- a/files/en-us/web/html/element/big/index.md +++ /dev/null @@ -1,85 +0,0 @@ ---- -title: "<big>: The Bigger Text element" -slug: Web/HTML/Element/big -page-type: html-element -status: - - deprecated -browser-compat: html.elements.big ---- - -{{HTMLSidebar}}{{deprecated_header}} - -The **`<big>`** [HTML](/en-US/docs/Web/HTML) deprecated element renders the enclosed text at a font size one level larger than the surrounding text (`medium` becomes `large`, for example). The size is capped at the browser's maximum permitted font size. - -> [!WARNING] -> This element has been removed from the specification and shouldn't be used anymore. Use the CSS {{cssxref("font-size")}} property to adjust the font size. - -## Attributes - -This element has no other attributes than the [global attributes](/en-US/docs/Web/HTML/Global_attributes), common to all elements. - -## Examples - -Here we see examples showing the use of `<big>` followed by an example showing how to accomplish the same results using modern CSS syntax instead. - -### Using big - -This example uses the obsolete `<big>` element to increase the size of some text. - -#### HTML - -```html -<p> - This is the first sentence. - <big>This whole sentence is in bigger letters.</big> -</p> -``` - -#### Result - -{{EmbedLiveSample("Using_big", 640, 60)}} - -### Using CSS `font-size` - -This example uses the CSS {{cssxref("font-size")}} property to increase the font size by one level. - -#### CSS - -```css -.bigger { - font-size: larger; -} -``` - -#### HTML - -```html -<p> - This is the first sentence. - <span class="bigger">This whole sentence is in bigger letters.</span> -</p> -``` - -#### Result - -{{EmbedLiveSample("Using_CSS_font-size", 640, 60)}} - -## DOM interface - -This element implements the {{domxref('HTMLElement')}} interface. - -<!-- ## Technical summary --> - -## Specifications - -{{Specifications}} - -## Browser compatibility - -{{Compat}} - -## See also - -- CSS: {{cssxref("font-size")}}, {{cssxref("font")}} -- HTML: {{htmlelement("small")}}, {{htmlelement("font")}}, {{htmlelement("style")}} -- HTML 4.01 Specification: [Font Styles](https://www.w3.org/TR/html4/present/graphics.html#h-15.2) diff --git a/files/en-us/web/html/element/blockquote/index.md b/files/en-us/web/html/element/blockquote/index.md deleted file mode 100644 index 9d07fb0f731b4e0..000000000000000 --- a/files/en-us/web/html/element/blockquote/index.md +++ /dev/null @@ -1,154 +0,0 @@ ---- -title: "<blockquote>: The Block Quotation element" -slug: Web/HTML/Element/blockquote -page-type: html-element -browser-compat: html.elements.blockquote ---- - -{{HTMLSidebar}} - -The **`<blockquote>`** [HTML](/en-US/docs/Web/HTML) element indicates that the enclosed text is an extended quotation. Usually, this is rendered visually by indentation (see [Notes](#usage_notes) for how to change it). A URL for the source of the quotation may be given using the `cite` attribute, while a text representation of the source can be given using the {{HTMLElement("cite")}} element. - -{{InteractiveExample("HTML Demo: &lt;blockquote&gt;", "tabbed-standard")}} - -```html interactive-example -<div> - <blockquote cite="https://www.huxley.net/bnw/four.html"> - <p> - Words can be like X-rays, if you use them properly—they’ll go through - anything. You read and you’re pierced. - </p> - </blockquote> - <p>—Aldous Huxley, <cite>Brave New World</cite></p> -</div> -``` - -```css interactive-example -div:has(> blockquote) { - background-color: #ededed; - margin: 10px auto; - padding: 15px; - border-radius: 5px; -} - -blockquote p::before { - content: "\201C"; -} - -blockquote p::after { - content: "\201D"; -} - -blockquote + p { - text-align: right; -} -``` - -## Attributes - -This element's attributes include the [global attributes](/en-US/docs/Web/HTML/Global_attributes). - -- `cite` - - : A URL that designates a source document or message for the information quoted. This attribute is intended to point to information explaining the context or the reference for the quote. - -## Usage notes - -According to the specification, attribution for the quotation, if any, must be placed outside the `<blockquote>` element. - -To change the indentation applied to the quoted text, use the {{Glossary("CSS")}} {{cssxref("margin-left")}} and/or {{cssxref("margin-right")}} properties, or the {{cssxref("margin")}} shorthand property. - -To include shorter quotes inline rather than in a separate block, use the {{HTMLElement("q")}} (Quotation) element. - -## Examples - -This example demonstrates the use of the `<blockquote>` element to quote a passage from {{RFC(1149)}}, _A Standard for the Transmission of IP Datagrams on Avian Carriers_. - -```html -<blockquote cite="https://datatracker.ietf.org/doc/html/rfc1149"> - <p> - Avian carriers can provide high delay, low throughput, and low altitude - service. The connection topology is limited to a single point-to-point path - for each carrier, used with standard carriers, but many carriers can be used - without significant interference with each other, outside early spring. This - is because of the 3D ether space available to the carriers, in contrast to - the 1D ether used by IEEE802.3. The carriers have an intrinsic collision - avoidance system, which increases availability. - </p> -</blockquote> -``` - -### Result - -{{EmbedLiveSample("Examples", 640, 180)}} - -## Technical summary - -<table class="properties"> - <tbody> - <tr> - <th scope="row"> - <a href="/en-US/docs/Web/HTML/Content_categories" - >Content categories</a - > - </th> - <td> - <a href="/en-US/docs/Web/HTML/Content_categories#flow_content" - >Flow content</a - >, sectioning root, palpable content. - </td> - </tr> - <tr> - <th scope="row">Permitted content</th> - <td> - <a href="/en-US/docs/Web/HTML/Content_categories#flow_content" - >Flow content</a - >. - </td> - </tr> - <tr> - <th scope="row">Tag omission</th> - <td>None, both the starting and ending tag are mandatory.</td> - </tr> - <tr> - <th scope="row">Permitted parents</th> - <td> - Any element that accepts - <a href="/en-US/docs/Web/HTML/Content_categories#flow_content" - >flow content</a - >. - </td> - </tr> - <tr> - <th scope="row">Implicit ARIA role</th> - <td> - <code> - <a href="/en-US/docs/Web/Accessibility/ARIA/Roles/structural_roles#structural_roles_with_html_equivalents" - >blockquote</a - ></code - > - </td> - </tr> - <tr> - <th scope="row">Permitted ARIA roles</th> - <td>Any</td> - </tr> - <tr> - <th scope="row">DOM interface</th> - <td>{{domxref("HTMLQuoteElement")}}</td> - </tr> - </tbody> -</table> - -## Specifications - -{{Specifications}} - -## Browser compatibility - -{{Compat}} - -## See also - -- The {{HTMLElement("q")}} element for inline quotations. -- The {{HTMLElement("cite")}} element for source citations. -- [The blockquote element](https://heydonworks.com/article/the-blockquote-element/) via heydonworks.com (2024) diff --git a/files/en-us/web/html/element/body/index.md b/files/en-us/web/html/element/body/index.md deleted file mode 100644 index f6e467fcbc24b4f..000000000000000 --- a/files/en-us/web/html/element/body/index.md +++ /dev/null @@ -1,209 +0,0 @@ ---- -title: "<body>: The Document Body element" -slug: Web/HTML/Element/body -page-type: html-element -browser-compat: html.elements.body ---- - -{{HTMLSidebar}} - -The **`<body>`** [HTML](/en-US/docs/Web/HTML) element represents the content of an HTML document. There can be only one `<body>` element in a document. - -## Attributes - -This element includes the [global attributes](/en-US/docs/Web/HTML/Global_attributes), event attributes, and deprecated attributes: - -### Event attributes - -> [!NOTE] -> Each of the below event attribute names is linked to its equivalent {{domxref("Window")}} interface event. You can listen to these events using [`addEventListener()`](/en-US/docs/Web/API/EventTarget/addEventListener) instead of adding the `oneventname` attribute to the `<body>` element. - -- [`onafterprint`](/en-US/docs/Web/API/Window/afterprint_event) - - : Function to call after the user has printed the document. -- [`onbeforeprint`](/en-US/docs/Web/API/Window/beforeprint_event) - - : Function to call when the user requests printing of the document. -- [`onbeforeunload`](/en-US/docs/Web/API/Window/beforeunload_event) - - : Function to call when the document is about to be unloaded. -- [`onblur`](/en-US/docs/Web/API/Window/blur_event) - - : Function to call when the document loses focus. -- [`onerror`](/en-US/docs/Web/API/Window/error_event) - - : Function to call when the document fails to load properly. -- [`onfocus`](/en-US/docs/Web/API/Window/focus_event) - - : Function to call when the document receives focus. -- [`onhashchange`](/en-US/docs/Web/API/Window/hashchange_event) - - : Function to call when the fragment identifier part (starting with the hash (`'#'`) character) of the document's current address has changed. -- [`onlanguagechange`](/en-US/docs/Web/API/Window/languagechange_event) - - : Function to call when the preferred languages changed. -- [`onload`](/en-US/docs/Web/API/Window/load_event) - - : Function to call when the document has finished loading. -- [`onmessage`](/en-US/docs/Web/API/Window/message_event) - - : Function to call when the document has received a message. -- [`onmessageerror`](/en-US/docs/Web/API/Window/messageerror_event) - - : Function to call when the document has received a message that cannot be deserialized. -- [`onoffline`](/en-US/docs/Web/API/Window/offline_event) - - : Function to call when network communication has failed. -- [`ononline`](/en-US/docs/Web/API/Window/online_event) - - : Function to call when network communication has been restored. -- [`onpageswap`](/en-US/docs/Web/API/Window/pageswap_event) - - : Function to call when you navigate across documents, when the previous document is about to unload. -- [`onpagehide`](/en-US/docs/Web/API/Window/pagehide_event) - - : Function to call when the browser hides the current page in the process of presenting a different page from the session's history. -- [`onpagereveal`](/en-US/docs/Web/API/Window/pagereveal_event) - - : Function to call when a document is first rendered, either when loading a fresh document from the network or activating a document. -- [`onpageshow`](/en-US/docs/Web/API/Window/pageshow_event) - - : Function to call when the browser displays the window's document due to navigation. -- [`onpopstate`](/en-US/docs/Web/API/Window/popstate_event) - - : Function to call when the user has navigated session history. -- [`onresize`](/en-US/docs/Web/API/Window/resize_event) - - : Function to call when the document has been resized. -- [`onrejectionhandled`](/en-US/docs/Web/API/Window/rejectionhandled_event) - - : Function to call when a JavaScript {{jsxref("Promise")}} is handled late. -- [`onstorage`](/en-US/docs/Web/API/Window/storage_event) - - : Function to call when the storage area has changed. -- [`onunhandledrejection`](/en-US/docs/Web/API/Window/unhandledrejection_event) - - : Function to call when a JavaScript {{jsxref("Promise")}} that has no rejection handler is rejected. -- [`onunload`](/en-US/docs/Web/API/Window/unload_event) - - : Function to call when the document is going away. - -### Deprecated attributes - -> [!WARNING] -> Do not use these deprecated attributes; opt for the CSS alternatives listed with each deprecated attribute instead. - -- `alink` {{deprecated_inline}} - - : Color of text for hyperlinks when selected. - Use the CSS {{cssxref("color")}} property in conjunction with the {{cssxref(":active")}} and {{cssxref(":focus")}} pseudo-classes instead. -- `background` {{deprecated_inline}} - - : URI of an image to use as a background. - Use the CSS {{cssxref("background-image")}} property instead. -- `bgcolor` {{deprecated_inline}} - - : Background color for the document. - Use the CSS {{cssxref("background-color")}} property instead. -- `bottommargin` {{deprecated_inline}} - - : The margin of the bottom of the body. - Use the CSS {{cssxref("margin-bottom")}} property (or the logical {{cssxref("margin-block-end")}} property) instead. -- `leftmargin` {{deprecated_inline}} - - : The margin of the left of the body. - Use the CSS {{cssxref("margin-left")}} property (or the logical {{cssxref("margin-inline-start")}} property) instead. -- `link` {{deprecated_inline}} - - : Color of text for unvisited hypertext links. - Use the CSS {{cssxref("color")}} property in conjunction with the {{cssxref(":link")}} pseudo-class instead. -- `rightmargin` {{deprecated_inline}} - - : The margin of the right of the body. - Use the CSS {{cssxref("margin-right")}} property or the logical {{cssxref("margin-inline-end")}} property) instead. -- `text` {{deprecated_inline}} - - : Foreground color of text. - Use the CSS {{cssxref("color")}} property instead. -- `topmargin` {{deprecated_inline}} - - : The margin of the top of the body. - Use the CSS {{cssxref("margin-top")}} property (or the logical {{cssxref("margin-block-start")}} property) instead. -- `vlink` {{deprecated_inline}} - - : Color of text for visited hypertext links. - Use the CSS {{cssxref("color")}} property in conjunction with the {{cssxref(":visited")}} pseudo-class instead. - -## Examples - -```html -<html lang="en"> - <head> - <title>Document title</title> - </head> - <body> - <p> - The <code>&lt;body&gt;</code> HTML element represents the content of an - HTML document. There can be only one <code>&lt;body&gt;</code> element in - a document. - </p> - </body> -</html> -``` - -### Result - -{{EmbedLiveSample('Example')}} - -## Technical summary - -<table class="properties"> - <tbody> - <tr> - <th scope="row"> - <a href="/en-US/docs/Web/HTML/Content_categories" - >Content categories</a - > - </th> - <td> - None. - </td> - </tr> - <tr> - <th scope="row">Permitted content</th> - <td> - <a href="/en-US/docs/Web/HTML/Content_categories#flow_content" - >Flow content</a - >. - </td> - </tr> - <tr> - <th scope="row">Tag omission</th> - <td> - The start tag may be omitted if the first thing inside it is not a space - character, comment, {{HTMLElement("script")}} element or - {{HTMLElement("style")}} element. The end tag may be omitted if - the <code>&#x3C;body></code> element has contents or has a start tag, - and is not immediately followed by a comment. - </td> - </tr> - <tr> - <th scope="row">Permitted parents</th> - <td> - It must be the second element of an {{HTMLElement("html")}} - element. - </td> - </tr> - <tr> - <th scope="row">Implicit ARIA role</th> - <td> - <code - ><a href="/en-US/docs/Web/Accessibility/ARIA/Roles/generic_role" - >generic</a - ></code - > - </td> - </tr> - <tr> - <th scope="row">Permitted ARIA roles</th> - <td>No <code>role</code> permitted</td> - </tr> - <tr> - <th scope="row">DOM interface</th> - <td> - {{domxref("HTMLBodyElement")}} - <ul> - <li> - The <code>&#x3C;body></code> element exposes the - {{domxref("HTMLBodyElement")}} interface. - </li> - <li> - You can access the <code>&#x3C;body></code> element through the - {{domxref("document.body")}} property. - </li> - </ul> - </td> - </tr> - </tbody> -</table> - -## Specifications - -{{Specifications}} - -## Browser compatibility - -{{Compat}} - -## See also - -- {{HTMLElement("html")}} -- {{HTMLElement("head")}} -- [Event handling overview](/en-US/docs/Web/Events/Event_handlers) diff --git a/files/en-us/web/html/element/br/index.md b/files/en-us/web/html/element/br/index.md deleted file mode 100644 index fbb5a76dc44c1e0..000000000000000 --- a/files/en-us/web/html/element/br/index.md +++ /dev/null @@ -1,151 +0,0 @@ ---- -title: "<br>: The Line Break element" -slug: Web/HTML/Element/br -page-type: html-element -browser-compat: html.elements.br ---- - -{{HTMLSidebar}} - -The **`<br>`** [HTML](/en-US/docs/Web/HTML) element produces a line break in text (carriage-return). It is useful for writing a poem or an address, where the division of lines is significant. - -{{InteractiveExample("HTML Demo: &lt;br&gt;", "tabbed-standard")}} - -```html interactive-example -<p> - O’er all the hilltops<br /> - Is quiet now,<br /> - In all the treetops<br /> - Hearest thou<br /> - Hardly a breath;<br /> - The birds are asleep in the trees:<br /> - Wait, soon like these<br /> - Thou too shalt rest. -</p> -``` - -```css interactive-example -p { - font-size: 1rem; - font-family: sans-serif; - margin: 20px; -} -``` - -As you can see from the above example, a `<br>` element is included at each point where we want the text to break. The text after the `<br>` begins again at the start of the next line of the text block. - -> [!NOTE] -> Do not use `<br>` to create margins between paragraphs; wrap them in {{htmlelement("p")}} elements and use the [CSS](/en-US/docs/Web/CSS) {{cssxref('margin')}} property to control their size. - -## Attributes - -This element's attributes include the [global attributes](/en-US/docs/Web/HTML/Global_attributes). - -### Deprecated attributes - -- `clear` {{Deprecated_Inline}} - - : Indicates where to begin the next line after the break. - -## Styling with CSS - -The `<br>` element has a single, well-defined purpose — to create a line break in a block of text. As such, it has no dimensions or visual output of its own, and there is very little you can do to style it. - -You can set a {{cssxref("margin")}} on `<br>` elements themselves to increase the spacing between the lines of text in the block, but this is a bad practice — you should use the {{cssxref("line-height")}} property that was designed for that purpose. - -## Accessibility - -Creating separate paragraphs of text using `<br>` is not only bad practice, it is problematic for people who navigate with the aid of screen reading technology. Screen readers may announce the presence of the element, but not any content contained within `<br>`s. This can be a confusing and frustrating experience for the person using the screen reader. - -Use `<p>` elements, and use CSS properties like {{cssxref("margin")}} to control their spacing. - -## Examples - -### Basic br - -In the following example we use `<br>` elements to create line breaks between the different lines of a postal address: - -```html -Mozilla<br /> -331 E. Evelyn Avenue<br /> -Mountain View, CA<br /> -94041<br /> -USA<br /> -``` - -#### Result - -{{ EmbedLiveSample('Basic_br', 640, 120) }} - -## Technical summary - -<table class="properties"> - <tbody> - <tr> - <th scope="row"> - <a href="/en-US/docs/Web/HTML/Content_categories" - >Content categories</a - > - </th> - <td> - <a href="/en-US/docs/Web/HTML/Content_categories#flow_content" - >Flow content</a - >, - <a href="/en-US/docs/Web/HTML/Content_categories#phrasing_content" - >phrasing content</a - >. - </td> - </tr> - <tr> - <th scope="row">Permitted content</th> - <td>None; it is a {{Glossary("void element")}}.</td> - </tr> - <tr> - <th scope="row">Tag omission</th> - <td> - Must have a start tag and must not have an end tag. In XHTML documents, - write this element as <code>&#x3C;br /></code>. - </td> - </tr> - <tr> - <th scope="row">Permitted parents</th> - <td> - Any element that accepts - <a href="/en-US/docs/Web/HTML/Content_categories#phrasing_content" - >phrasing content</a - >. - </td> - </tr> - <tr> - <th scope="row">Implicit ARIA role</th> - <td> - <a href="https://www.w3.org/TR/html-aria/#dfn-no-corresponding-role" - >No corresponding role</a - > - </td> - </tr> - <tr> - <th scope="row">Permitted ARIA roles</th> - <td> - <a href="/en-US/docs/Web/Accessibility/ARIA/Roles/none_role"><code>none</code></a>, <a href="/en-US/docs/Web/Accessibility/ARIA/Roles/presentation_role"><code>presentation</code></a> - </td> - </tr> - <tr> - <th scope="row">DOM interface</th> - <td>{{domxref("HTMLBRElement")}}</td> - </tr> - </tbody> -</table> - -## Specifications - -{{Specifications}} - -## Browser compatibility - -{{Compat}} - -## See also - -- {{HTMLElement("address")}} element -- {{HTMLElement("p")}} element -- {{HTMLElement("wbr")}} element diff --git a/files/en-us/web/html/element/button/index.md b/files/en-us/web/html/element/button/index.md deleted file mode 100644 index 282229825cefef7..000000000000000 --- a/files/en-us/web/html/element/button/index.md +++ /dev/null @@ -1,347 +0,0 @@ ---- -title: "<button>: The Button element" -slug: Web/HTML/Element/button -page-type: html-element -browser-compat: html.elements.button ---- - -{{HTMLSidebar}} - -The **`<button>`** [HTML](/en-US/docs/Web/HTML) element is an interactive element activated by a user with a mouse, keyboard, finger, voice command, or other assistive technology. Once activated, it then performs an action, such as submitting a [form](/en-US/docs/Learn_web_development/Extensions/Forms) or opening a dialog. - -By default, HTML buttons are presented in a style resembling the platform the {{Glossary("user agent")}} runs on, but you can change buttons' appearance with [CSS](/en-US/docs/Web/CSS). - -{{InteractiveExample("HTML Demo: &lt;button&gt;", "tabbed-shorter")}} - -```html interactive-example -<button class="favorite styled" type="button">Add to favorites</button> -``` - -```css interactive-example -.styled { - border: 0; - line-height: 2.5; - padding: 0 20px; - font-size: 1rem; - text-align: center; - color: #fff; - text-shadow: 1px 1px 1px #000; - border-radius: 10px; - background-color: rgba(220, 0, 0, 1); - background-image: linear-gradient( - to top left, - rgba(0, 0, 0, 0.2), - rgba(0, 0, 0, 0.2) 30%, - rgba(0, 0, 0, 0) - ); - box-shadow: - inset 2px 2px 3px rgba(255, 255, 255, 0.6), - inset -2px -2px 3px rgba(0, 0, 0, 0.6); -} - -.styled:hover { - background-color: rgba(255, 0, 0, 1); -} - -.styled:active { - box-shadow: - inset -2px -2px 3px rgba(255, 255, 255, 0.6), - inset 2px 2px 3px rgba(0, 0, 0, 0.6); -} -``` - -## Attributes - -This element's attributes include the [global attributes](/en-US/docs/Web/HTML/Global_attributes). - -- `autofocus` - - - : This Boolean attribute specifies that the button should have input [focus](/en-US/docs/Web/API/HTMLElement/focus) when the page loads. **Only one element in a document can have this attribute.** - -- `command` {{experimental_inline}} - - - : Specifies the action to be performed on an element being controlled by a control `<button>`, specified via the `commandfor` attribute. The possible values are: - - - `"show-modal"` - - : The button will show a {{htmlelement("dialog")}} as modal. If the dialog is already modal, no action will be taken. - - `"close"` - - : The button will close a {{htmlelement("dialog")}} element. If the dialog is already closed, no action will be taken. - - `"show-popover"` - - : The button will show a hidden popover. If you try to show an already showing popover, no action will be taken. See {{domxref("Popover API", "Popover API", "", "nocode")}} for more details. - - `"hide-popover"` - - : The button will hide a showing popover. If you try to hide an already hidden popover, no action will be taken. See {{domxref("Popover API", "Popover API", "", "nocode")}} for more details. - - `"toggle-popover"` - - : The button will toggle a popover between showing and hidden. If the popover is hidden, it will be shown; if the popover is showing, it will be hidden. See {{domxref("Popover API", "Popover API", "", "nocode")}} for more details. - - Custom values - - : This attribute can represent custom values that are prefixed with a two hyphen characters (`--`). Buttons with a custom value will dispatch the {{domxref("CommandEvent")}} on the controlled element. - -- `commandfor` {{experimental_inline}} - - : Turns a {{htmlelement("button")}} element into a button, controlling the given interactive element; takes the ID of the element to control as its value. -- [`disabled`](/en-US/docs/Web/HTML/Attributes/disabled) - - : This Boolean attribute prevents the user from interacting with the button: it cannot be pressed or focused. -- `form` - - - : The {{HTMLElement("form")}} element to associate the button with (its _form owner_). The value of this attribute must be the `id` of a `<form>` in the same document. (If this attribute is not set, the `<button>` is associated with its ancestor `<form>` element, if any.) - - This attribute lets you associate `<button>` elements to `<form>`s anywhere in the document, not just inside a `<form>`. It can also override an ancestor `<form>` element. - -- `formaction` - - : The URL that processes the information submitted by the button. Overrides the [`action`](/en-US/docs/Web/HTML/Element/form#action) attribute of the button's form owner. Does nothing if there is no form owner. -- `formenctype` - - - : If the button is a submit button (it's inside/associated with a `<form>` and doesn't have `type="button"`), specifies how to encode the form data that is submitted. Possible values: - - - `application/x-www-form-urlencoded`: The default if the attribute is not used. - - `multipart/form-data`: Used to submit {{HTMLElement("input")}} elements with their [`type`](/en-US/docs/Web/HTML/Element/input#type) attributes set to `file`. - - `text/plain`: Specified as a debugging aid; shouldn't be used for real form submission. - - If this attribute is specified, it overrides the [`enctype`](/en-US/docs/Web/HTML/Element/form#enctype) attribute of the button's form owner. - -- `formmethod` - - - : If the button is a submit button (it's inside/associated with a `<form>` and doesn't have `type="button"`), this attribute specifies the [HTTP method](/en-US/docs/Web/HTTP/Methods) used to submit the form. Possible values: - - - `post`: The data from the form are included in the body of the HTTP request when sent to the server. Use when the form contains information that shouldn't be public, like login credentials. - - `get`: The form data are appended to the form's `action` URL, with a `?` as a separator, and the resulting URL is sent to the server. Use this method when the form [has no side effects](/en-US/docs/Glossary/Idempotent), like search forms. - - `dialog`: This method is used to indicate that the button closes the [dialog](/en-US/docs/Web/HTML/Element/dialog) with which it is associated, and does not transmit the form data at all. - - If specified, this attribute overrides the [`method`](/en-US/docs/Web/HTML/Element/form#method) attribute of the button's form owner. - -- `formnovalidate` - - - : If the button is a submit button, this Boolean attribute specifies that the form is not to be [validated](/en-US/docs/Learn_web_development/Extensions/Forms/Form_validation) when it is submitted. If this attribute is specified, it overrides the [`novalidate`](/en-US/docs/Web/HTML/Element/form#novalidate) attribute of the button's form owner. - - This attribute is also available on [`<input type="image">`](/en-US/docs/Web/HTML/Element/input/image) and [`<input type="submit">`](/en-US/docs/Web/HTML/Element/input/submit) elements. - -- `formtarget` - - - : If the button is a submit button, this attribute is an author-defined name or standardized, underscore-prefixed keyword indicating where to display the response from submitting the form. This is the `name` of, or keyword for, a _browsing context_ (a tab, window, or {{HTMLElement("iframe")}}). If this attribute is specified, it overrides the [`target`](/en-US/docs/Web/HTML/Element/form#target) attribute of the button's form owner. The following keywords have special meanings: - - - `_self`: Load the response into the same browsing context as the current one. This is the default if the attribute is not specified. - - `_blank`: Load the response into a new unnamed browsing context — usually a new tab or window, depending on the user's browser settings. - - `_parent`: Load the response into the parent browsing context of the current one. If there is no parent, this option behaves the same way as `_self`. - - `_top`: Load the response into the top-level browsing context (that is, the browsing context that is an ancestor of the current one, and has no parent). If there is no parent, this option behaves the same way as `_self`. - -- `name` - - - : The name of the button, submitted as a pair with the button's `value` as part of the form data, when that button is used to submit the form. - -- `popovertarget` - - - : Turns a `<button>` element into a popover control button; takes the ID of the popover element to control as its value. Establishing a relationship between a popover and its invoker button using the `popovertarget` attribute has two additional useful effects: - - - The browser creates an implicit [`aria-details`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-details) and [`aria-expanded`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-expanded) relationship between popover and invoker, and places the popover in a logical position in the keyboard focus navigation order when shown. This makes the popover more accessible to keyboard and assistive technology (AT) users (see also [Popover accessibility features](/en-US/docs/Web/API/Popover_API/Using#popover_accessibility_features)). - - The browser creates an implicit anchor reference between the two, making it very convenient to position popovers relative to their controls using [CSS anchor positioning](/en-US/docs/Web/CSS/CSS_anchor_positioning). See [Popover anchor positioning](/en-US/docs/Web/API/Popover_API/Using#popover_anchor_positioning) for more details. - -- `popovertargetaction` - - - : Specifies the action to be performed on a popover element being controlled by a control `<button>`. Possible values are: - - - `"hide"` - - : The button will hide a shown popover. If you try to hide an already hidden popover, no action will be taken. - - `"show"` - - : The button will show a hidden popover. If you try to show an already showing popover, no action will be taken. - - `"toggle"` - - : The button will toggle a popover between showing and hidden. If the popover is hidden, it will be shown; if the popover is showing, it will be hidden. If `popovertargetaction` is omitted, `"toggle"` is the default action that will be performed by the control button. - -- `type` - - - : The default behavior of the button. Possible values are: - - - `submit`: The button submits the form data to the server. This is the default if the attribute is not specified for buttons associated with a `<form>`, or if the attribute is an empty or invalid value. - - `reset`: The button resets all the controls to their initial values, like [\<input type="reset">](/en-US/docs/Web/HTML/Element/input/reset). (This behavior tends to annoy users.) - - `button`: The button has no default behavior, and does nothing when pressed by default. It can have client-side scripts listen to the element's events, which are triggered when the events occur. - -- `value` - - : Defines the value associated with the button's `name` when it's submitted with the form data. This value is passed to the server in params when the form is submitted using this button. - -## Notes - -A submit button with the attribute `formaction` set, but without an associated form does nothing. You have to set a form owner, either by wrapping it in a `<form>` or set the attribute `form` to the id of the form. - -`<button>` elements are much easier to style than {{HTMLElement("input")}} elements. You can add inner HTML content (think `<i>`, `<br>`, or even `<img>`), and use {{Cssxref("::after")}} and {{Cssxref("::before")}} pseudo-elements for complex rendering. - -If your buttons are not for submitting form data to a server, be sure to set their `type` attribute to `button`. Otherwise, they will try to submit form data and to load the (nonexistent) response, possibly destroying the current state of the document. - -While `<button type="button">` has no default behavior, event handlers can be scripted to trigger behaviors. An activated button can perform programmable actions using [JavaScript](/en-US/docs/Learn_web_development/Core/Scripting), such as removing an item from a list. - -By default, user agents style buttons as `display: flow-root`, which establishes a new [block formatting context](/en-US/docs/Web/CSS/CSS_display/Block_formatting_context) and centers the button's children both horizontally and vertically as long as they do not overflow. If the button is defined as a flex or grid container, the children will behave as flex or grid items. A button set to `display: inline` will be styled as if the value were set to `display: inline-block`. - -## Accessibility - -### Icon buttons - -Buttons that only display an icon do not have an _{{glossary("accessible name")}}_. Accessible names provide information for assistive technology, such as screen readers, to access when they parse the document and generate [an accessibility tree](/en-US/docs/Learn_web_development/Core/Accessibility/What_is_accessibility#accessibility_apis). Assistive technology then uses the accessibility tree to navigate and manipulate page content. - -To give an icon button an accessible name, put text in the `<button>` element that concisely describes the button's functionality. - -#### Examples - -```html -<button name="favorite"> - <svg fill="#000000" viewBox="0 0 42 42"> - <path - d="M21,1c1.081,0,5.141,12.315,6.201,13.126s13.461,1.053,13.791,2.137 c0.34,1.087-9.561,8.938-9.961,10.252c-0.409,1.307, - 3.202,13.769,2.331,14.442c-0.879,0.673-11.05-6.79-12.361-6.79 c-1.311,0-11.481,7.463-12.36,6.79c-0.871-0.674,2.739-13.136, - 2.329-14.442c-0.399-1.313-10.3-9.165-9.96-10.252 c0.33-1.084,12.731-1.326,13.791-2.137S19.91,1,21,1z"></path> - </svg> - Add to favorites -</button> -``` - -##### Result - -{{EmbedLiveSample('Icon buttons')}} - -If you want to visually hide the button's text, an accessible way to do so is to use [a combination of CSS properties](https://www.a11yproject.com/posts/how-to-hide-content/) to remove it visually from the screen, but keep it parsable by assistive technology. - -However, it is worth noting that leaving the button text visible can help people who may not be familiar with the icon's meaning or understand the button's purpose. This is especially important for people who are not technologically sophisticated or who may have different cultural interpretations of the icon the button uses. - -- [What is an accessible name? | The Paciello Group](https://www.tpgi.com/what-is-an-accessible-name/) -- [MDN Understanding WCAG, Guideline 4.1 explanations](/en-US/docs/Web/Accessibility/Understanding_WCAG/Robust#guideline_4.1_—_compatible_maximize_compatibility_with_current_and_future_user_agents_including_assistive_technologies) -- [Understanding Success Criterion 4.1.2 | W3C Understanding WCAG 2.0](https://www.w3.org/TR/UNDERSTANDING-WCAG20/ensure-compat-rsv.html) - -### Size and Proximity - -#### Size - -Interactive elements such as buttons should have an area large enough to be easy to activate. This helps a variety of people, including people with motor control issues and people using non-precise forms of input such as a stylus or fingers. A minimum interactive size of 44×44 [CSS pixels](/en-US/docs/Glossary/CSS_pixel) is recommended. - -- [Understanding Success Criterion 2.5.5: Target Size | W3C Understanding WCAG 2.1](https://www.w3.org/WAI/WCAG21/Understanding/target-size.html) -- [Target Size and 2.5.5 | Adrian Roselli](https://adrianroselli.com/2019/06/target-size-and-2-5-5.html) -- [Quick test: Large touch targets - The A11Y Project](https://www.a11yproject.com/posts/large-touch-targets/) - -#### Proximity - -Large amounts of interactive content — including buttons — placed in close visual proximity to each other should have space separating them. This spacing is beneficial for people who are experiencing motor control issues, who may accidentally activate the wrong interactive content. - -Spacing may be created using CSS properties such as {{cssxref("margin")}}. - -- [Hand tremors and the giant-button-problem - Axess Lab](https://axesslab.com/hand-tremors/) - -### ARIA state information - -To describe the state of a button the correct ARIA attribute to use is [`aria-pressed`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-pressed) and not [`aria-checked`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-checked) or [`aria-selected`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-selected). To find out more read the information about the [ARIA button role](/en-US/docs/Web/Accessibility/ARIA/Roles/button_role). - -### Button styles - -It is best not to override the default focus ring for elements that have focus. If the button styles are overridden, it is important to **ensure that the focus state has enough contrast** so that people experiencing low vision conditions can perceive it and people with cognitive differences will understand it. - -The {{cssxref(":focus-visible")}} pseudo-class can be used to apply styles to an element that has {{cssxref(":focus")}} only when the user agent's heuristics determine that the focus should be highlighted, such as when a `<button>` receives keyboard focus. See [:focus vs :focus-visible](/en-US/docs/Web/CSS/:focus-visible#focus_vs_focus-visible) for more information. - -Color contrast ratio is determined by comparing the luminosity of the button text and background color values to the background the button is placed on. To meet current [Web Content Accessibility Guidelines (WCAG)](https://www.w3.org/WAI/standards-guidelines/wcag/), a ratio of 4.5:1 is required for text content and 3:1 for large text. (Large text is defined as 18.66px and {{cssxref("font-weight", "bold")}} or larger, or 24px or larger.) - -- [WebAIM: Color Contrast Checker](https://webaim.org/resources/contrastchecker/) -- [MDN Understanding WCAG, Guideline 1.4 explanations](/en-US/docs/Web/Accessibility/Understanding_WCAG/Perceivable#guideline_1.4_make_it_easier_for_users_to_see_and_hear_content_including_separating_foreground_from_background) -- [Understanding Success Criterion 1.4.3 | W3C Understanding WCAG 2.0](https://www.w3.org/TR/UNDERSTANDING-WCAG20/visual-audio-contrast-contrast.html) - -### Clicking and focus - -Whether clicking on a `<button>` or {{HTMLElement("input")}} button types causes it to (by default) become focused varies by browser and OS. Most browsers do give focus to a button being clicked, but [Safari does not, by design](https://webkit.org/b/22261#c68). - -## Examples - -```html -<button name="button">Press me</button> -``` - -{{ EmbedLiveSample('Example', 200, 64) }} - -## Technical summary - -<table class="properties"> - <tbody> - <tr> - <th scope="row"> - <a href="/en-US/docs/Web/HTML/Content_categories" - >Content categories</a - > - </th> - <td> - <a href="/en-US/docs/Web/HTML/Content_categories#flow_content" - >Flow content</a - >, - <a href="/en-US/docs/Web/HTML/Content_categories#phrasing_content" - >phrasing content</a - >, - <a - href="/en-US/docs/Web/HTML/Content_categories#interactive_content" - >Interactive content</a - >, - <a href="/en-US/docs/Web/HTML/Content_categories#form_listed" - >listed</a - >, - <a href="/en-US/docs/Web/HTML/Content_categories#form_labelable" - >labelable</a - >, and - <a href="/en-US/docs/Web/HTML/Content_categories#form_submittable" - >submittable</a - > - <a - href="/en-US/docs/Web/HTML/Content_categories#form-associated_content" - >form-associated</a - > - element, palpable content. - </td> - </tr> - <tr> - <th scope="row">Permitted content</th> - <td> - <a href="/en-US/docs/Web/HTML/Content_categories#phrasing_content" - >Phrasing content</a - > - but there must be no - <a - href="/en-US/docs/Web/HTML/Content_categories#interactive_content" - >Interactive content</a - > - </td> - </tr> - <tr> - <th scope="row">Tag omission</th> - <td>None, both the starting and ending tag are mandatory.</td> - </tr> - <tr> - <th scope="row">Permitted parents</th> - <td> - Any element that accepts - <a href="/en-US/docs/Web/HTML/Content_categories#phrasing_content" - >phrasing content</a - >. - </td> - </tr> - <tr> - <th scope="row">Implicit ARIA role</th> - <td> - <code - ><a href="/en-US/docs/Web/Accessibility/ARIA/Roles/button_role" - >button</a - ></code - > - </td> - </tr> - <tr> - <th scope="row">Permitted ARIA roles</th> - <td> - <a href="/en-US/docs/Web/Accessibility/ARIA/Roles/checkbox_role"><code>checkbox</code></a>, <a href="/en-US/docs/Web/Accessibility/ARIA/Roles/combobox_role"><code>combobox</code></a>, - <a href="/en-US/docs/Web/Accessibility/ARIA/Roles/link_role"><code>link</code></a>, <a href="/en-US/docs/Web/Accessibility/ARIA/Roles/menuitem_role"><code>menuitem</code></a>, - <a href="/en-US/docs/Web/Accessibility/ARIA/Roles/menuitemcheckbox_role"><code>menuitemcheckbox</code></a>, - <a href="/en-US/docs/Web/Accessibility/ARIA/Roles/menuitemradio_role"><code>menuitemradio</code></a>, <a href="/en-US/docs/Web/Accessibility/ARIA/Roles/option_role"><code>option</code></a>, - <a href="/en-US/docs/Web/Accessibility/ARIA/Roles/radio_role"><code>radio</code></a>, <a href="/en-US/docs/Web/Accessibility/ARIA/Roles/switch_role"><code>switch</code></a>, - <a href="/en-US/docs/Web/Accessibility/ARIA/Roles/tab_role"><code>tab</code></a> - </td> - </tr> - <tr> - <th scope="row">DOM interface</th> - <td>{{domxref("HTMLButtonElement")}}</td> - </tr> - </tbody> -</table> - -## Specifications - -{{Specifications}} - -## Browser compatibility - -{{Compat}} diff --git a/files/en-us/web/html/element/canvas/index.md b/files/en-us/web/html/element/canvas/index.md deleted file mode 100644 index e2d187fb9e9d0de..000000000000000 --- a/files/en-us/web/html/element/canvas/index.md +++ /dev/null @@ -1,181 +0,0 @@ ---- -title: "<canvas>: The Graphics Canvas element" -slug: Web/HTML/Element/canvas -page-type: html-element -browser-compat: html.elements.canvas ---- - -{{HTMLSidebar}} - -Use the **HTML `<canvas>` element** with either the [canvas scripting API](/en-US/docs/Web/API/Canvas_API) or the [WebGL API](/en-US/docs/Web/API/WebGL_API) to draw graphics and animations. - -## Attributes - -This element's attributes include the [global attributes](/en-US/docs/Web/HTML/Global_attributes). - -- `height` - - : The height of the coordinate space in CSS pixels. Defaults to 150. -- `moz-opaque` {{non-standard_inline}} {{deprecated_inline}} - - : Lets the canvas know whether translucency will be a factor. If the canvas knows there's no translucency, painting performance can be optimized. This is only supported by Mozilla-based browsers; use the standardized {{domxref("HTMLCanvasElement.getContext()", "canvas.getContext('2d', { alpha: false })")}} instead. -- `width` - - : The width of the coordinate space in CSS pixels. Defaults to 300. - -## Usage notes - -### Alternative content - -You should provide alternate content inside the `<canvas>` block. That content will be rendered both on older browsers that don't support canvas and in browsers with JavaScript disabled. - -### Closing `</canvas>` tag - -Unlike the {{HTMLElement("img")}} element, the `<canvas>` element **requires** the closing tag (`</canvas>`). - -### Sizing the canvas using CSS versus HTML - -The displayed size of the canvas can be changed using CSS, but if you do this the image is scaled during rendering to fit the styled size, which can make the final graphics rendering end up being distorted. - -It is better to specify your canvas dimensions by setting the `width` and `height` attributes directly on the `<canvas>` elements, either directly in the HTML or by using JavaScript. - -### Maximum canvas size - -The exact maximum size of a `<canvas>` element depends on the browser and environment. While in most cases the maximum dimensions exceed 10,000 x 10,000 pixels, notably iOS devices limit the canvas size to only 4,096 x 4,096 pixels. See [canvas size limits in different browsers and devices](https://jhildenbiddle.github.io/canvas-size/#/?id=test-results). - -> [!NOTE] -> Exceeding the maximum dimensions or area renders the canvas unusable — drawing commands will not work. - -### Using an offscreen canvas - -A canvas can be rendered using the {{domxref("OffscreenCanvas")}} API where the document and canvas are decoupled. -The benefit is that a [worker thread](/en-US/docs/Web/API/Web_Workers_API/Using_web_workers) can handle canvas rendering and the main thread of your web application is not blocked by canvas operations. -By parallelizing work, other UI elements of your web application will remain responsive even if you are running complex graphics on an offscreen canvas. -For more information, see the {{domxref("OffscreenCanvas")}} API documentation. - -## Accessibility - -### Alternative content - -The `<canvas>` element on its own is just a bitmap and does not provide information about any drawn objects. Canvas content is not exposed to accessibility tools as semantic HTML is. In general, you should avoid using canvas in an accessible website or app. The following guides can help to make it more accessible. - -- [Canvas accessibility use cases](https://www.w3.org/WAI/PF/HTML/wiki/Canvas_Accessibility_Use_Cases) -- [Canvas element accessibility issues](https://www.w3.org/html/wg/wiki/AddedElementCanvas) -- [HTML Canvas Accessibility in Firefox 13 – by Steve Faulkner](https://www.tpgi.com/html5-canvas-accessibility-in-firefox-13/) -- [Best practices for interactive canvas elements](https://html.spec.whatwg.org/multipage/scripting.html#best-practices) - -## Examples - -### HTML - -This code snippet adds a canvas element to your HTML document. A fallback text is provided if a browser is unable to read or render the canvas. - -```html -<canvas width="120" height="120"> - An alternative text describing what your canvas displays. -</canvas> -``` - -### JavaScript - -Then in the JavaScript code, call {{domxref("HTMLCanvasElement.getContext()")}} to get a drawing context and start drawing onto the canvas: - -```js -const canvas = document.querySelector("canvas"); -const ctx = canvas.getContext("2d"); -ctx.fillStyle = "green"; -// Add a rectangle at (10, 10) with size 100x100 pixels -ctx.fillRect(10, 10, 100, 100); -``` - -### Result - -{{EmbedLiveSample('Examples', 600, 150)}} - -## Technical summary - -<table class="properties"> - <tbody> - <tr> - <th scope="row"> - <a href="/en-US/docs/Web/HTML/Content_categories" - >Content categories</a - > - </th> - <td> - <a href="/en-US/docs/Web/HTML/Content_categories#flow_content" - >Flow content</a - >, - <a href="/en-US/docs/Web/HTML/Content_categories#phrasing_content" - >phrasing content</a - >, - <a href="/en-US/docs/Web/HTML/Content_categories#embedded_content" - >embedded content</a - >, palpable content. - </td> - </tr> - <tr> - <th scope="row">Permitted content</th> - <td> - Transparent but with no - <a - href="/en-US/docs/Web/HTML/Content_categories#interactive_content" - >interactive content</a - > - descendants except for {{HTMLElement("a")}} elements, - {{HTMLElement("button")}} elements, - {{HTMLElement("input")}} elements whose - <a href="/en-US/docs/Web/HTML/Element/input#type"><code>type</code></a> attribute is - <code>checkbox</code>, <code>radio</code>, or <code>button</code>. - </td> - </tr> - <tr> - <th scope="row">Tag omission</th> - <td>None, both the starting and ending tag are mandatory.</td> - </tr> - <tr> - <th scope="row">Permitted parents</th> - <td> - Any element that accepts - <a href="/en-US/docs/Web/HTML/Content_categories#phrasing_content" - >phrasing content</a - >. - </td> - </tr> - <tr> - <th scope="row">Implicit ARIA role</th> - <td> - <a href="https://www.w3.org/TR/html-aria/#dfn-no-corresponding-role" - >No corresponding role</a - > - </td> - </tr> - <tr> - <th scope="row">Permitted ARIA roles</th> - <td>Any</td> - </tr> - <tr> - <th scope="row">DOM interface</th> - <td>{{domxref("HTMLCanvasElement")}}</td> - </tr> - </tbody> -</table> - -## Specifications - -{{Specifications}} - -## Browser compatibility - -{{Compat}} - -## See also - -- [Canvas API](/en-US/docs/Web/API/Canvas_API) -- [Canvas tutorial](/en-US/docs/Web/API/Canvas_API/Tutorial) -- [OffscreenCanvas](/en-US/docs/Web/API/OffscreenCanvas) -- [Canvas cheat sheet](https://simon.html5.org/dump/html5-canvas-cheat-sheet.html) (2009) -- [Canvas cheat sheet](https://websitesetup.org/wp-content/uploads/2015/11/Infopgraphic-CanvasCheatSheet-Final2.pdf) (pdf) (2015) -- [Safari HTML canvas guide](https://developer.apple.com/library/archive/documentation/AudioVideo/Conceptual/HTML-canvas-guide/Introduction/Introduction.html) via Apple (2013) -- [`CanvasRenderingContext2D` 2D drawing context for a canvas element](https://developer.apple.com/documentation/webkitjs/canvasrenderingcontext2d) via Apple.com -- [WebGL](/en-US/docs/Web/API/WebGL_API) API -- {{HTMLElement("img")}} -- [SVG](/en-US/docs/Web/SVG) -- [HTML video and audio](/en-US/docs/Learn_web_development/Core/Structuring_content/HTML_video_and_audio) diff --git a/files/en-us/web/html/element/caption/index.md b/files/en-us/web/html/element/caption/index.md deleted file mode 100644 index a8c5a73c3a07f1f..000000000000000 --- a/files/en-us/web/html/element/caption/index.md +++ /dev/null @@ -1,254 +0,0 @@ ---- -title: "<caption>: The Table Caption element" -slug: Web/HTML/Element/caption -page-type: html-element -browser-compat: html.elements.caption ---- - -{{HTMLSidebar}} - -The **`<caption>`** [HTML](/en-US/docs/Web/HTML) element specifies the caption (or title) of a table, providing the table an {{glossary("accessible description")}}. - -{{InteractiveExample("HTML Demo: &lt;caption&gt;", "tabbed-taller")}} - -```html interactive-example -<table> - <caption> - He-Man and Skeletor facts - </caption> - <tr> - <td></td> - <th scope="col" class="heman">He-Man</th> - <th scope="col" class="skeletor">Skeletor</th> - </tr> - <tr> - <th scope="row">Role</th> - <td>Hero</td> - <td>Villain</td> - </tr> - <tr> - <th scope="row">Weapon</th> - <td>Power Sword</td> - <td>Havoc Staff</td> - </tr> - <tr> - <th scope="row">Dark secret</th> - <td>Expert florist</td> - <td>Cries at romcoms</td> - </tr> -</table> -``` - -```css interactive-example -caption { - caption-side: bottom; - padding: 10px; - font-weight: bold; -} - -table { - border-collapse: collapse; - border: 2px solid rgb(140 140 140); - font-family: sans-serif; - font-size: 0.8rem; - letter-spacing: 1px; -} - -th, -td { - border: 1px solid rgb(160 160 160); - padding: 8px 10px; -} - -th { - background-color: rgb(230 230 230); -} - -td { - text-align: center; -} - -tr:nth-child(even) td { - background-color: rgb(250 250 250); -} - -tr:nth-child(odd) td { - background-color: rgb(240 240 240); -} - -.heman { - font: 1.4rem molot; - text-shadow: - 1px 1px 1px #fff, - 2px 2px 1px #000; -} - -.skeletor { - font: 1.7rem rapscallion; - letter-spacing: 3px; - text-shadow: - 1px 1px 0 #fff, - 0 0 9px #000; -} -``` - -## Attributes - -This element includes the [global attributes](/en-US/docs/Web/HTML/Global_attributes). - -### Deprecated attributes - -The following attributes are deprecated and should not be used. They are documented below for reference when updating existing code and for historical interest only. - -- `align` {{deprecated_inline}} - - - : Specifies on which side of the table the caption should be displayed. The possible {{Glossary("enumerated", "enumerated")}} values are `left`, `top`, `right`, or `bottom`. Use the {{cssxref("caption-side")}} and {{cssxref("text-align")}} CSS properties instead, as this attribute is deprecated. - -## Usage notes - -- If included, the `<caption>` element must be the first child of its parent {{htmlelement("table")}} element. -- When a `<table>` is nested within a {{HTMLElement("figure")}} as the figure's only content, it should be captioned via a {{HTMLElement("figcaption")}} for the `<figure>` instead of as a `<caption>` nested within the `<table>`. -- Any {{cssxref("background-color")}} applied to a table will not be applied to its caption. Add a `background-color` to the `<caption>` element as well if you want the same color to be behind both. - -## Example - -See {{HTMLElement("table")}} for a complete table example introducing common standards and best practices. - -### Table with caption - -This example demonstrates a basic table that includes a caption describing the data presented. - -Such a "title" is helpful for users who are quickly scanning the page, and it is especially beneficial for visually impaired users, allowing them to determine the table's relevance quickly without the need to have a screen reader read the contents of many cells just to find out what the table is about. - -#### HTML - -A `<caption>` element is used as the first child of the {{HTMLElement("table")}}, with text content similar to a title to describe the table data. Three rows, the first being a header row, with two columns are created using the {{HTMLElement("tr")}}, {{HTMLElement("th")}} and {{HTMLElement("td")}} elements after the `<caption>`. - -```html -<table> - <caption> - User login email addresses - </caption> - <tr> - <th>Login</th> - <th>Email</th> - </tr> - <tr> - <td>user1</td> - <td>user1@example.com</td> - </tr> - <tr> - <td>user2</td> - <td>user2@example.com</td> - </tr> -</table> -``` - -#### CSS - -Some basic CSS is used to align and highlight the `<caption>`. - -```css -caption { - caption-side: top; - text-align: left; - padding-bottom: 10px; - font-weight: bold; -} -``` - -```css hidden -table { - border-collapse: collapse; - border: 2px solid rgb(140 140 140); - font-family: sans-serif; - font-size: 0.8rem; - letter-spacing: 1px; -} - -th, -td { - border: 1px solid rgb(160 160 160); - padding: 8px 10px; -} - -th { - background-color: rgb(230 230 230); -} - -td { - text-align: center; -} -``` - -#### Result - -{{EmbedLiveSample('Example', 650, 140)}} - -## Technical summary - -<table class="properties"> - <tbody> - <tr> - <th scope="row"> - <a href="/en-US/docs/Web/HTML/Content_categories" - >Content categories</a - > - </th> - <td>None.</td> - </tr> - <tr> - <th scope="row">Permitted content</th> - <td> - <a href="/en-US/docs/Web/HTML/Content_categories#flow_content" - >Flow content</a - >. - </td> - </tr> - <tr> - <th scope="row">Tag omission</th> - <td> - The end tag can be omitted if the element is not immediately followed by - ASCII whitespace or a comment. - </td> - </tr> - <tr> - <th scope="row">Permitted parents</th> - <td> - A {{HTMLElement("table")}} element, as its first descendant. - </td> - </tr> - <tr> - <th scope="row">Implicit ARIA role</th> - <td> - <code - ><a href="/en-US/docs/Web/Accessibility/ARIA/Roles/structural_roles#structural_roles_with_html_equivalents">caption</a - ></code - > - </td> - </tr> - <tr> - <th scope="row">Permitted ARIA roles</th> - <td>No <code>role</code> permitted</td> - </tr> - <tr> - <th scope="row">DOM interface</th> - <td>{{domxref("HTMLTableCaptionElement")}}</td> - </tr> - </tbody> -</table> - -## Specifications - -{{Specifications}} - -## Browser compatibility - -{{Compat}} - -## See also - -- [Learn: HTML table basics](/en-US/docs/Learn_web_development/Core/Structuring_content/HTML_table_basics) -- {{HTMLElement("col")}}, {{HTMLElement("colgroup")}}, {{HTMLElement("table")}}, {{HTMLElement("tbody")}}, {{HTMLElement("td")}}, {{HTMLElement("tfoot")}}, {{HTMLElement("th")}}, {{HTMLElement("thead")}}, {{HTMLElement("tr")}}: Other table-related elements -- {{cssxref("caption-side")}}: CSS property to position the `<caption>` relative to its parent {{HTMLElement("table")}} -- {{cssxref("text-align")}}: CSS property to horizontally align the text content of the `<caption>` diff --git a/files/en-us/web/html/element/center/index.md b/files/en-us/web/html/element/center/index.md deleted file mode 100644 index d41e23b1e00e0d9..000000000000000 --- a/files/en-us/web/html/element/center/index.md +++ /dev/null @@ -1,75 +0,0 @@ ---- -title: "<center>: The Centered Text element" -slug: Web/HTML/Element/center -page-type: html-element -status: - - deprecated -browser-compat: html.elements.center ---- - -{{HTMLSidebar}}{{deprecated_header}} - -The **`<center>`** [HTML](/en-US/docs/Web/HTML) element is a [block-level element](/en-US/docs/Glossary/Block-level_content) that displays its block-level or inline contents centered horizontally within its containing element. The container is usually, but isn't required to be, {{HTMLElement("body")}}. - -This tag has been deprecated in HTML 4 (and XHTML 1) in favor of the [CSS](/en-US/docs/Web/CSS) {{Cssxref("text-align")}} property, which can be applied to the {{HTMLElement("div")}} element or to an individual {{HTMLElement("p")}}. For centering blocks, use other CSS properties like {{Cssxref("margin-left")}} and {{Cssxref("margin-right")}} and set them to `auto` (or set {{Cssxref("margin")}} to `0 auto`). - -## DOM interface - -This element implements the {{domxref("HTMLElement")}} interface. - -## Example 1 - -```html -<center> - This text will be centered. - <p>So will this paragraph.</p> -</center> -``` - -### Result - -{{EmbedLiveSample("Example 1")}} - -## Example 2 (CSS alternative) - -```html -<div style="text-align:center"> - This text will be centered. - <p>So will this paragraph.</p> -</div> -``` - -### Result - -{{EmbedLiveSample("Example 2 (CSS alternative)")}} - -## Example 3 (CSS alternative) - -```html -<p style="text-align:center"> - This line will be centered.<br /> - And so will this line. -</p> -``` - -### Result - -{{EmbedLiveSample("Example 3 (CSS alternative)")}} - -> [!NOTE] -> Applying {{cssxref("text-align", "text-align: center")}} to a {{HTMLElement("div")}} or {{HTMLElement("p")}} element centers the _contents_ of those elements while leaving their overall dimensions unchanged. - -<!-- ## Technical summary --> - -## Specifications - -{{Specifications}} - -## Browser compatibility - -{{Compat}} - -## See also - -- {{Cssxref("text-align")}} -- {{Cssxref("display")}} diff --git a/files/en-us/web/html/element/cite/index.md b/files/en-us/web/html/element/cite/index.md deleted file mode 100644 index 5d2cc457f7ff1ae..000000000000000 --- a/files/en-us/web/html/element/cite/index.md +++ /dev/null @@ -1,163 +0,0 @@ ---- -title: "<cite>: The Citation element" -slug: Web/HTML/Element/cite -page-type: html-element -browser-compat: html.elements.cite ---- - -{{HTMLSidebar}} - -The **`<cite>`** [HTML](/en-US/docs/Web/HTML) element is used to mark up the title of a cited creative work. The reference may be in an abbreviated form according to context-appropriate conventions related to citation metadata. - -{{InteractiveExample("HTML Demo: &lt;cite&gt;", "tabbed-standard")}} - -```html interactive-example -<figure> - <blockquote> - <p> - It was a bright cold day in April, and the clocks were striking thirteen. - </p> - </blockquote> - <figcaption> - First sentence in - <cite - ><a href="http://www.george-orwell.org/1984/0.html" - >Nineteen Eighty-Four</a - ></cite - > - by George Orwell (Part 1, Chapter 1). - </figcaption> -</figure> -``` - -```css interactive-example -/* stylelint-disable-next-line block-no-empty */ -cite { -} -``` - -## Attributes - -This element only includes the [global attributes](/en-US/docs/Web/HTML/Global_attributes). - -## Usage notes - -In the context of the `<cite>` element, a creative work that might be cited could be, for example, one of the following: - -- A book -- A research paper -- An essay -- A poem -- A musical score -- A song -- A play or film script -- A film -- A television show -- A game -- A sculpture -- A painting -- A theatrical production -- A play -- An opera -- A musical -- An exhibition -- A legal case report -- A computer program -- A website -- A web page -- A blog post or comment -- A forum post or comment -- A tweet -- A Facebook post -- A written or oral statement -- And so forth. - -To include a reference to the source of quoted material which is contained within a {{HTMLElement("blockquote")}} or {{HTMLElement("q")}} element, use the [`cite`](/en-US/docs/Web/HTML/Element/blockquote#cite) attribute on the element. - -Typically, browsers style the contents of a `<cite>` element in italics by default. To avoid this, apply the CSS {{cssxref("font-style")}} property to the `<cite>` element. - -## Examples - -```html -<p>More information can be found in <cite>[ISO-0000]</cite>.</p> -``` - -### Result - -{{EmbedLiveSample("Example", 640, 80)}} - -## Technical summary - -<table class="properties"> - <tbody> - <tr> - <th scope="row"> - <a href="/en-US/docs/Web/HTML/Content_categories" - >Content categories</a - > - </th> - <td> - <a href="/en-US/docs/Web/HTML/Content_categories#flow_content" - >Flow content</a - >, - <a href="/en-US/docs/Web/HTML/Content_categories#phrasing_content" - >phrasing content</a - >, palpable content. - </td> - </tr> - <tr> - <th scope="row">Permitted content</th> - <td> - <a href="/en-US/docs/Web/HTML/Content_categories#phrasing_content" - >Phrasing content</a - >. - </td> - </tr> - <tr> - <th scope="row">Tag omission</th> - <td>None, both the starting and ending tag are mandatory.</td> - </tr> - <tr> - <th scope="row">Permitted parents</th> - <td> - Any element that accepts - <a href="/en-US/docs/Web/HTML/Content_categories#phrasing_content" - >phrasing content</a - >. - </td> - </tr> - <tr> - <th scope="row">Implicit ARIA role</th> - <td> - <a href="https://www.w3.org/TR/html-aria/#dfn-no-corresponding-role" - >No corresponding role</a - > - </td> - </tr> - <tr> - <th scope="row">Permitted ARIA roles</th> - <td>Any</td> - </tr> - <tr> - <th scope="row">DOM interface</th> - <td> - {{domxref("HTMLElement")}} Up to Gecko 1.9.2 (Firefox 4) - inclusive, Firefox implements the - {{domxref("HTMLSpanElement")}} interface for this element. - </td> - </tr> - </tbody> -</table> - -## Specifications - -{{Specifications}} - -## Browser compatibility - -{{Compat}} - -## See also - -- The element {{HTMLElement("blockquote")}} for long quotations. -- The element {{HTMLElement("q")}} for inline quotations and the [`cite`](/en-US/docs/Web/HTML/Element/q#cite) attribute. diff --git a/files/en-us/web/html/element/code/index.md b/files/en-us/web/html/element/code/index.md deleted file mode 100644 index 11fce00c71bc1e6..000000000000000 --- a/files/en-us/web/html/element/code/index.md +++ /dev/null @@ -1,132 +0,0 @@ ---- -title: "<code>: The Inline Code element" -slug: Web/HTML/Element/code -page-type: html-element -browser-compat: html.elements.code ---- - -{{HTMLSidebar}} - -The **`<code>`** [HTML](/en-US/docs/Web/HTML) element displays its contents styled in a fashion intended to indicate that the text is a short fragment of computer code. By default, the content text is displayed using the {{Glossary("user agent", "user agent's")}} default monospace font. - -{{InteractiveExample("HTML Demo: &lt;code&gt;", "tabbed-shorter")}} - -```html interactive-example -<p> - The <code>push()</code> method adds one or more elements to the end of an - array and returns the new length of the array. -</p> -``` - -```css interactive-example -code { - background-color: #eee; - border-radius: 3px; - font-family: courier, monospace; - padding: 0 3px; -} -``` - -## Attributes - -This element only includes the [global attributes](/en-US/docs/Web/HTML/Global_attributes). - -## Examples - -A paragraph of text that includes `<code>`: - -```html -<p> - The function <code>selectAll()</code> highlights all the text in the input - field so the user can, for example, copy or delete the text. -</p> -``` - -### Result - -{{EmbedLiveSample("Example", 640, 70)}} - -## Notes - -To represent multiple lines of code, wrap the `<code>` element within a {{HTMLElement("pre")}} element. The `<code>` element by itself only represents a single phrase of code or line of code. - -A CSS rule can be defined for the `code` selector to override the browser's default font face. Preferences set by the user might take precedence over the specified CSS. - -## Technical summary - -<table class="properties"> - <tbody> - <tr> - <th scope="row"> - <a href="/en-US/docs/Web/HTML/Content_categories" - >Content categories</a - > - </th> - <td> - <a href="/en-US/docs/Web/HTML/Content_categories#flow_content" - >Flow content</a - >, - <a href="/en-US/docs/Web/HTML/Content_categories#phrasing_content" - >phrasing content</a - >, palpable content. - </td> - </tr> - <tr> - <th scope="row">Permitted content</th> - <td> - <a href="/en-US/docs/Web/HTML/Content_categories#phrasing_content" - >Phrasing content</a - >. - </td> - </tr> - <tr> - <th scope="row">Tag omission</th> - <td>None, both the starting and ending tag are mandatory.</td> - </tr> - <tr> - <th scope="row">Permitted parents</th> - <td> - Any element that accepts - <a href="/en-US/docs/Web/HTML/Content_categories#phrasing_content" - >phrasing content</a - >. - </td> - </tr> - <tr> - <th scope="row">Implicit ARIA role</th> - <td> - <code - ><a href="/en-US/docs/Web/Accessibility/ARIA/Roles/structural_roles#structural_roles_with_html_equivalents">code</a - ></code - > - </td> - </tr> - <tr> - <th scope="row">Permitted ARIA roles</th> - <td>Any</td> - </tr> - <tr> - <th scope="row">DOM interface</th> - <td> - {{domxref("HTMLElement")}} Up to Gecko 1.9.2 (Firefox 4) - inclusive, Firefox implements the - {{domxref("HTMLSpanElement")}} interface for this element. - </td> - </tr> - </tbody> -</table> - -## Specifications - -{{Specifications}} - -## Browser compatibility - -{{Compat}} - -## See also - -- {{HTMLElement("samp")}} -- {{HTMLElement("kbd")}} -- {{HTMLElement("var")}} -- {{HTMLElement("pre")}} diff --git a/files/en-us/web/html/element/col/index.md b/files/en-us/web/html/element/col/index.md deleted file mode 100644 index 1937c476efbb76f..000000000000000 --- a/files/en-us/web/html/element/col/index.md +++ /dev/null @@ -1,294 +0,0 @@ ---- -title: "<col>: The Table Column element" -slug: Web/HTML/Element/col -page-type: html-element -browser-compat: html.elements.col ---- - -{{HTMLSidebar}} - -The **`<col>`** [HTML](/en-US/docs/Web/HTML) element defines one or more columns in a column group represented by its parent {{HTMLElement("colgroup")}} element. The `<col>` element is only valid as a child of a {{HTMLElement("colgroup")}} element that has no [`span`](/en-US/docs/Web/HTML/Element/colgroup#span) attribute defined. - -{{InteractiveExample("HTML Demo: &lt;col&gt;", "tabbed-taller")}} - -```html interactive-example -<table> - <caption> - Superheros and sidekicks - </caption> - <colgroup> - <col /> - <col span="2" class="batman" /> - <col span="2" class="flash" /> - </colgroup> - <tr> - <td></td> - <th scope="col">Batman</th> - <th scope="col">Robin</th> - <th scope="col">The Flash</th> - <th scope="col">Kid Flash</th> - </tr> - <tr> - <th scope="row">Skill</th> - <td>Smarts, strong</td> - <td>Dex, acrobat</td> - <td>Super speed</td> - <td>Super speed</td> - </tr> -</table> -``` - -```css interactive-example -.batman { - background-color: #d7d9f2; -} - -.flash { - background-color: #ffe8d4; -} - -table { - border-collapse: collapse; - border: 2px solid rgb(140 140 140); - font-family: sans-serif; - font-size: 0.8rem; - letter-spacing: 1px; -} - -caption { - caption-side: bottom; - padding: 10px; -} - -th, -td { - border: 1px solid rgb(160 160 160); - padding: 8px 6px; -} - -td { - text-align: center; -} -``` - -## Attributes - -This element includes the [global attributes](/en-US/docs/Web/HTML/Global_attributes). - -- `span` - - : Specifies the number of consecutive columns the `<col>` element spans. The value must be a positive integer greater than zero. If not present, its default value is `1`. - -### Deprecated attributes - -The following attributes are deprecated and should not be used. They are documented below for reference when updating existing code and for historical interest only. - -- `align` {{deprecated_inline}} - - - : Specifies the horizontal alignment of each column cell. The possible {{Glossary("enumerated")}} values are `left`, `center`, `right`, `justify`, and `char`. When supported, the `char` value aligns the textual content on the character defined in the [`char`](#char) attribute and on offset defined by the [`charoff`](#charoff) attribute. Note that this attribute overrides the specified [`align`](/en-US/docs/Web/HTML/Element/colgroup#align) of its {{HTMLElement("colgroup")}} parent element. Use the {{cssxref("text-align")}} CSS property on the {{htmlelement("td")}} and {{htmlelement("th")}} elements instead, as this attribute is deprecated. - - > [!NOTE] - > Setting `text-align` on the `<col>` element has no effect as `<col>` has no descendants, and therefore no elements inherit from it. - > - > If the table does not use a [`colspan`](/en-US/docs/Web/HTML/Element/td#colspan) attribute, use the `td:nth-of-type(an+b)` CSS selector. Set `a` to zero and `b` to the position of the column in the table, e.g. `td:nth-of-type(2) { text-align: right; }` to right-align the second column cells. - > - > If the table does use a [`colspan`](/en-US/docs/Web/HTML/Element/td#colspan) attribute, the effect can be achieved by combining adequate CSS attribute selectors like `[colspan=n]`, though this is not trivial. - -- `bgcolor` {{deprecated_inline}} - - - : Defines the background color of each column cell. The value is an HTML color; either a [6-digit hexadecimal RGB code](/en-US/docs/Web/CSS/hex-color), prefixed by a `#`, or a [color keyword](/en-US/docs/Web/CSS/named-color). Other CSS {{cssxref("color_value", "&lt;color&gt")}} values are not supported. Use the {{cssxref("background-color")}} CSS property instead, as this attribute is deprecated. - -- `char` {{deprecated_inline}} - - - : Does nothing. It was originally intended to specify the alignment of the content to a character of each column cell. Typical values for this include a period (`.`) when attempting to align numbers or monetary values. If [`align`](#align) is not set to `char`, this attribute is ignored, though it will still override the specified [`char`](/en-US/docs/Web/HTML/Element/colgroup#char) of its {{HTMLElement("colgroup")}} parent element. - -- `charoff` {{deprecated_inline}} - - - : Does nothing. It was originally intended to specify the number of characters to offset the column cell content from the alignment character specified by the [`char`](#char) attribute. - -- `valign` {{deprecated_inline}} - - - : Specifies the vertical alignment of each column cell. The possible {{Glossary("enumerated")}} values are `baseline`, `bottom`, `middle`, and `top`. Note that this attribute overrides the specified [`valign`](/en-US/docs/Web/HTML/Element/colgroup#valign) of its {{HTMLElement("colgroup")}} parent element. Use the {{cssxref("vertical-align")}} CSS property on the {{htmlelement("td")}} and {{htmlelement("th")}} elements instead, as this attribute is deprecated. - - > [!NOTE] - > Setting `vertical-align` on the `<col>` element has no effect as `<col>` has no descendants, and therefore no elements inherit from it. - > - > If the table does not use a [`colspan`](/en-US/docs/Web/HTML/Element/td#colspan) attribute, use the `td:nth-of-type(an+b)` CSS selector. Set `a` to zero and `b` to the position of the column in the table, e.g. `td:nth-of-type(2) { vertical-align: middle; }` to center the second column cells vertically. - > - > If the table does use a [`colspan`](/en-US/docs/Web/HTML/Element/td#colspan) attribute, the effect can be achieved by combining adequate CSS attribute selectors like `[colspan=n]`, though this is not trivial. - -- `width` {{deprecated_inline}} - - - : Specifies a default width for each column. In addition to the standard pixel and percentage values, this attribute can take the special form `0*`, which means that the width of each column spanned should be the minimum width necessary to hold the column's contents. Relative widths such as `5*` can also be used. Note that this attribute overrides the specified [`width`](/en-US/docs/Web/HTML/Element/colgroup#width) of its {{HTMLElement("colgroup")}} parent element. Use the {{cssxref("width")}} CSS property instead, as this attribute is deprecated. - -## Usage notes - -- The `<col>` element is used within a {{HTMLElement("colgroup")}} element that doesn't have a `span` attribute. -- The `<col>` elements do not structurally group columns together. This is the role of the {{HTMLElement("colgroup")}} element. -- Only a limited number of CSS properties affect `<col>`: - - {{cssxref("background")}} : The various `background` properties will set the background for cells within the column. As the column background color is painted on top of the table and column groups ({{HTMLElement("colgroup")}}), but behind background colors applied to the row groups ({{htmlelement("thead")}}, {{htmlelement("tbody")}}, and {{htmlelement("tfoot")}}), the rows ({{htmlelement("tr")}}), and the individual cells ({{htmlelement("th")}} and {{htmlelement("td")}}), backgrounds applied to table columns are only visible if every layer painted on top of them has a transparent background. - - {{cssxref("border")}}: The various `border` properties apply, but only if the `<table>` has {{cssxref("border-collapse", "border-collapse: collapse")}} set. - - {{cssxref("visibility")}}: The value `collapse` for a column results in all cells of that column not being rendered, and cells spanning into other columns being clipped. The space these columns would have occupied is removed. However, the size of other columns is still calculated as though the cells in the collapsed column(s) are present. Other values for `visibility` have no effect. - - {{cssxref("width")}}: The `width` property defines a minimum width for the column, as if {{cssxref("min-width")}} were set. - -## Example - -See {{HTMLElement("table")}} for a complete table example introducing common standards and best practices. - -This example demonstrates an eight-column table divided into three `<col>` elements. - -### HTML - -A {{HTMLElement("colgroup")}} element provides structures to a basic table, creating a single implicit column group. Three `<col>` elements are included within the `<colgroup>`, creating three stylable columns. The [`span`](#span) attribute specifies the number of table columns each `<col>` should span (defaulting to `1` when omitted), enabling attributes to be shared across the columns in each `<col>`. - -```html -<table> - <caption> - Personal weekly activities - </caption> - <colgroup> - <col /> - <col span="5" class="weekdays" /> - <col span="2" class="weekend" /> - </colgroup> - <tr> - <th>Period</th> - <th>Mon</th> - <th>Tue</th> - <th>Wed</th> - <th>Thu</th> - <th>Fri</th> - <th>Sat</th> - <th>Sun</th> - </tr> - <tr> - <th>a.m.</th> - <td>Clean room</td> - <td>Football training</td> - <td>Dance Course</td> - <td>History Class</td> - <td>Buy drinks</td> - <td>Study hour</td> - <td>Free time</td> - </tr> - <tr> - <th>p.m.</th> - <td>Yoga</td> - <td>Chess Club</td> - <td>Meet friends</td> - <td>Gymnastics</td> - <td>Birthday party</td> - <td>Fishing trip</td> - <td>Free time</td> - </tr> -</table> -``` - -### CSS - -We use CSS, instead of deprecated HTML attributes, to provide a background color to the columns and align the cell content: - -```css -table { - border-collapse: collapse; - border: 2px solid rgb(140 140 140); -} - -caption { - caption-side: bottom; - padding: 10px; -} - -th, -td { - border: 1px solid rgb(160 160 160); - padding: 8px 6px; - text-align: center; -} - -.weekdays { - background-color: #d7d9f2; -} - -.weekend { - background-color: #ffe8d4; -} -``` - -```css hidden -table { - font-family: sans-serif; - font-size: 0.8rem; - letter-spacing: 1px; -} -``` - -#### Result - -{{EmbedLiveSample('Example', 650, 170)}} - -## Technical summary - -<table class="properties"> - <tbody> - <tr> - <th scope="row"> - <a href="/en-US/docs/Web/HTML/Content_categories" - >Content categories</a - > - </th> - <td>None.</td> - </tr> - <tr> - <th scope="row">Permitted content</th> - <td>None; it is a {{Glossary("void element")}}.</td> - </tr> - <tr> - <th scope="row">Tag omission</th> - <td>Must have a start tag and must not have an end tag.</td> - </tr> - <tr> - <th scope="row">Permitted parents</th> - <td> - {{HTMLElement("colgroup")}} only, though it can be implicitly - defined as its start tag is not mandatory. The - {{HTMLElement("colgroup")}} must not have a - <a href="/en-US/docs/Web/HTML/Element/colgroup#span"><code>span</code></a> attribute. - </td> - </tr> - <tr> - <th scope="row">Implicit ARIA role</th> - <td> - <a href="https://www.w3.org/TR/html-aria/#dfn-no-corresponding-role" - >No corresponding role</a - > - </td> - </tr> - <tr> - <th scope="row">Permitted ARIA roles</th> - <td>No <code>role</code> permitted</td> - </tr> - <tr> - <th scope="row">DOM interface</th> - <td>{{domxref("HTMLTableColElement")}}</td> - </tr> - </tbody> -</table> - -## Specifications - -{{Specifications}} - -## Browser compatibility - -{{Compat}} - -## See also - -- {{HTMLElement("caption")}}, {{HTMLElement("colgroup")}}, {{HTMLElement("table")}}, {{HTMLElement("tbody")}}, {{HTMLElement("td")}}, {{HTMLElement("tfoot")}}, {{HTMLElement("th")}}, {{HTMLElement("thead")}}, {{HTMLElement("tr")}}: Other table-related elements -- {{cssxref("background-color")}}: CSS property to set the background color of each column cell -- {{cssxref("border")}}: CSS property to control borders of column cells -- {{cssxref("text-align")}}: CSS property to horizontally align each column cell content -- {{cssxref("vertical-align")}}: CSS property to vertically align each column cell content -- {{cssxref("visibility")}}: CSS property to hide cells of a column -- {{cssxref("width")}}: CSS property to control the default width for each column -- {{cssxref(":nth-of-type")}}, {{cssxref(":first-of-type")}}, {{cssxref(":last-of-type")}}: CSS pseudo-classes to select the desired column cells diff --git a/files/en-us/web/html/element/colgroup/index.md b/files/en-us/web/html/element/colgroup/index.md deleted file mode 100644 index 699d7f3b7d449aa..000000000000000 --- a/files/en-us/web/html/element/colgroup/index.md +++ /dev/null @@ -1,304 +0,0 @@ ---- -title: "<colgroup>: The Table Column Group element" -slug: Web/HTML/Element/colgroup -page-type: html-element -browser-compat: html.elements.colgroup ---- - -{{HTMLSidebar}} - -The **`<colgroup>`** [HTML](/en-US/docs/Web/HTML) element defines a group of columns within a table. - -{{InteractiveExample("HTML Demo: &lt;colgroup&gt;", "tabbed-taller")}} - -```html interactive-example -<table> - <caption> - Superheros and sidekicks - </caption> - <colgroup> - <col /> - <col span="2" class="batman" /> - <col span="2" class="flash" /> - </colgroup> - <tr> - <td></td> - <th scope="col">Batman</th> - <th scope="col">Robin</th> - <th scope="col">The Flash</th> - <th scope="col">Kid Flash</th> - </tr> - <tr> - <th scope="row">Skill</th> - <td>Smarts, strong</td> - <td>Dex, acrobat</td> - <td>Super speed</td> - <td>Super speed</td> - </tr> -</table> -``` - -```css interactive-example -.batman { - background-color: #d7d9f2; -} - -.flash { - background-color: #ffe8d4; -} - -table { - border-collapse: collapse; - border: 2px solid rgb(140 140 140); - font-family: sans-serif; - font-size: 0.8rem; - letter-spacing: 1px; -} - -caption { - caption-side: bottom; - padding: 10px; -} - -th, -td { - border: 1px solid rgb(160 160 160); - padding: 8px 6px; -} - -td { - text-align: center; -} -``` - -## Attributes - -This element includes the [global attributes](/en-US/docs/Web/HTML/Global_attributes). - -- `span` - - - : Specifies the number of consecutive columns the `<colgroup>` element spans. The value must be a positive integer greater than zero. If not present, its default value is `1`. - - > [!NOTE] - > The `span` attribute is not permitted if there are one or more {{HTMLElement("col")}} elements within the `<colgroup>`. - -### Deprecated attributes - -The following attributes are deprecated and should not be used. They are documented below for reference when updating existing code and for historical interest only. - -- `align` {{deprecated_inline}} - - - : Specifies the horizontal alignment of each column group cell. The possible {{Glossary("enumerated")}} values are `left`, `center`, `right`, `justify`, and `char`. When supported, the `char` value aligns the textual content on the character defined in the [`char`](#char) attribute and the offset defined by the [`charoff`](#charoff) attribute. Note that the descendant {{HTMLElement("col")}} elements may override this value using their own [`align`](/en-US/docs/Web/HTML/Element/col#align) attribute. Use the {{cssxref("text-align")}} CSS property on the {{htmlelement("td")}} and {{htmlelement("th")}} elements instead, as this attribute is deprecated. - - > [!NOTE] - > Setting `text-align` on the `<colgroup>` element has no effect as {{HTMLElement("td")}} and {{HTMLElement("th")}} elements are not descendants of the `<colgroup>` element, and therefore they do not inherit from it. - > - > If the table does not use a [`colspan`](/en-US/docs/Web/HTML/Element/td#colspan) attribute, use the `td:nth-of-type(an+b)` CSS selector per column, where `a` is the total number of the columns in the table and `b` is the ordinal position of the column in the table, e.g. `td:nth-of-type(7n+2) { text-align: right; }` to right-align the second column cells. - > - > If the table does use a [`colspan`](/en-US/docs/Web/HTML/Element/td#colspan) attribute, the effect can be achieved by combining adequate CSS attribute selectors like `[colspan=n]`, though this is not trivial. - -- `bgcolor` {{deprecated_inline}} - - - : Defines the background color of each column group cell. The value is an HTML color; either a [6-digit hexadecimal RGB code](/en-US/docs/Web/CSS/hex-color), prefixed by a `#`, or a [color keyword](/en-US/docs/Web/CSS/named-color). Other CSS {{cssxref("color_value", "&lt;color&gt")}} values are not supported. Use the {{cssxref("background-color")}} CSS property instead, as this attribute is deprecated. - -- `char` {{deprecated_inline}} - - - : Does nothing. It was originally intended to specify the alignment of the content to a character of each column group cell. Typical values for this include a period (`.`) when attempting to align numbers or monetary values. If [`align`](#align) is not set to `char`, this attribute is ignored, though it will still be used as the default value for the [`align`](/en-US/docs/Web/HTML/Element/col#align) of the {{HTMLElement("col")}} elements which are members of this column group. - -- `charoff` {{deprecated_inline}} - - - : Does nothing. It was originally intended to specify the number of characters to offset the column group cell content from the alignment character specified by the [`char`](#char) attribute. - -- `valign` {{deprecated_inline}} - - - : Specifies the vertical alignment of each column group cell. The possible {{Glossary("enumerated")}} values are `baseline`, `bottom`, `middle`, and `top`. Note that the descendant {{HTMLElement("col")}} elements may override this value using their own [`valign`](/en-US/docs/Web/HTML/Element/col#valign) attribute. Use the {{cssxref("vertical-align")}} CSS property on the {{htmlelement("td")}} and {{htmlelement("th")}} elements instead, as this attribute is deprecated. - - > [!NOTE] - > Setting `vertical-align` on the `<colgroup>` element has no effect as {{HTMLElement("td")}} and {{HTMLElement("th")}} elements are not descendants of the `<colgroup>` element, and therefore they do not inherit from it. - > - > If the table does not use a [`colspan`](/en-US/docs/Web/HTML/Element/td#colspan) attribute, use the [`td:nth-of-type()`](/en-US/docs/Web/CSS/:nth-of-type) CSS selector per column, e.g. `td:nth-of-type(2) { vertical-align: middle; }` to center the second column cells vertically. - > - > If the table does use a [`colspan`](/en-US/docs/Web/HTML/Element/td#colspan) attribute, the effect can be achieved by combining adequate CSS attribute selectors like `[colspan=n]`, though this is not trivial. - -- `width` {{deprecated_inline}} - - - : Specifies a default width for each column in the current column group. In addition to the standard pixel and percentage values, this attribute can take the special form `0*`, which means that the width of each column spanned should be the minimum width necessary to hold the column's contents. Relative widths such as `5*` can also be used. Note that the descendant {{HTMLElement("col")}} elements may override this value using their own [`width`](/en-US/docs/Web/HTML/Element/col#width) attribute. Use the {{cssxref("width")}} CSS property instead, as this attribute is deprecated. - -## Usage notes - -- The `<colgroup>` should appear within a {{HTMLElement("table")}}, after any {{HTMLElement("caption")}} element (if used), but before any {{HTMLElement("thead")}}, {{HTMLElement("tbody")}}, {{HTMLElement("tfoot")}}, and {{HTMLElement("tr")}} elements. -- Only a limited number of CSS properties affect `<colgroup>`: - - {{cssxref("background")}} : The various `background` properties will set the background for cells within the column group. As the column group background color is painted on top of the table, but behind background colors applied to the columns ({{HTMLElement("col")}}), the row groups ({{htmlelement("thead")}}, {{htmlelement("tbody")}}, and {{htmlelement("tfoot")}}), the rows ({{htmlelement("tr")}}), and the individual cells ({{htmlelement("th")}} and {{htmlelement("td")}}), backgrounds applied to table column groups are only visible if every layer painted on top of them has a transparent background. - - {{cssxref("border")}}: The various `border` properties apply, but only if the `<table>` has {{cssxref("border-collapse", "border-collapse: collapse")}} set. - - {{cssxref("visibility")}}: The value `collapse` for a column group results in all cells of the columns in that column group not being rendered, and cells spanning into other columns being clipped. The space these columns in the column group would have occupied is removed. However, the size of other columns is still calculated as though the cells in the collapsed column(s) in the column group are present. Other values for `visibility` have no effect. - - {{cssxref("width")}}: The `width` property defines a minimum width for the columns within the column group, as if {{cssxref("min-width")}} were set. - -## Example - -See {{HTMLElement("table")}} for a complete table example introducing common standards and best practices. - -This example demonstrates a seven-column table divided into two `<colgroup>` elements that span multiple columns. - -### HTML - -Two `<colgroup>` elements are used to structure a basic table by creating column groups. The number of columns in each column group is specified by the [`span`](#span) attribute. - -```html -<table> - <caption> - Personal weekly activities - </caption> - <colgroup span="5" class="weekdays"></colgroup> - <colgroup span="2" class="weekend"></colgroup> - <tr> - <th>Mon</th> - <th>Tue</th> - <th>Wed</th> - <th>Thu</th> - <th>Fri</th> - <th>Sat</th> - <th>Sun</th> - </tr> - <tr> - <td>Clean room</td> - <td>Football training</td> - <td>Dance Course</td> - <td>History Class</td> - <td>Buy drinks</td> - <td>Study hour</td> - <td>Free time</td> - </tr> - <tr> - <td>Yoga</td> - <td>Chess Club</td> - <td>Meet friends</td> - <td>Gymnastics</td> - <td>Birthday party</td> - <td>Fishing trip</td> - <td>Free time</td> - </tr> -</table> -``` - -### CSS - -Grouped columns can be used to visually highlight the structure using CSS: - -```css -table { - border-collapse: collapse; - border: 2px solid rgb(140 140 140); -} - -caption { - caption-side: bottom; - padding: 10px; -} - -th, -td { - border: 1px solid rgb(160 160 160); - padding: 8px 6px; - text-align: center; -} - -.weekdays { - background-color: #d7d9f2; -} - -.weekend { - background-color: #ffe8d4; -} -``` - -```css hidden -table { - font-family: sans-serif; - font-size: 0.8rem; - letter-spacing: 1px; -} -``` - -#### Result - -{{EmbedLiveSample('Example', 650, 170)}} - -## Technical summary - -<table class="properties"> - <tbody> - <tr> - <th scope="row"> - <a href="/en-US/docs/Web/HTML/Content_categories" - >Content categories</a - > - </th> - <td>None.</td> - </tr> - <tr> - <th scope="row">Permitted content</th> - <td> - If the <a href="#span"><code>span</code></a> attribute is - present: none.<br />If - the attribute is not present: zero or more {{HTMLElement("col")}} - element - </td> - </tr> - <tr> - <th scope="row">Tag omission</th> - <td> - The start tag may be omitted, if it has a {{HTMLElement("col")}} - element as its first child and if it is not preceded by a - <code>&lt;colgroup&gt;</code> whose end tag has been omitted.<br />The - end tag may be omitted, if it is not followed by a space or a comment. - </td> - </tr> - <tr> - <th scope="row">Permitted parents</th> - <td> - A {{HTMLElement("table")}} element. The - <code>&lt;colgroup&gt;</code> must appear after any - {{HTMLElement("caption")}} element, but before any - {{HTMLElement("thead")}}, {{HTMLElement("tbody")}}, - {{HTMLElement("tfoot")}}, and - {{HTMLElement("tr")}} elements. - </td> - </tr> - <tr> - <th scope="row">Implicit ARIA role</th> - <td> - <a href="https://www.w3.org/TR/html-aria/#dfn-no-corresponding-role" - >No corresponding role</a - > - </td> - </tr> - <tr> - <th scope="row">Permitted ARIA roles</th> - <td>No <code>role</code> permitted</td> - </tr> - <tr> - <th scope="row">DOM interface</th> - <td>{{domxref("HTMLTableColElement")}}</td> - </tr> - </tbody> -</table> - -## Specifications - -{{Specifications}} - -## Browser compatibility - -{{Compat}} - -## See also - -- [Learn: HTML table basics](/en-US/docs/Learn_web_development/Core/Structuring_content/HTML_table_basics) -- {{HTMLElement("caption")}}, {{HTMLElement("col")}}, {{HTMLElement("table")}}, {{HTMLElement("tbody")}}, {{HTMLElement("td")}}, {{HTMLElement("tfoot")}}, {{HTMLElement("th")}}, {{HTMLElement("thead")}}, {{HTMLElement("tr")}}: Other table-related elements -- {{cssxref("background-color")}}: CSS property to set the background color of each column group cell -- {{cssxref("border")}}: CSS property to control borders of column group cells -- {{cssxref("text-align")}}: CSS property to horizontally align each column group cell content -- {{cssxref("vertical-align")}}: CSS property to vertically align each column group cell content -- {{cssxref("visibility")}}: CSS property to hide (or show) cells of a column group -- {{cssxref("width")}}: CSS property to control the default width for each column in a column group -- {{cssxref(":nth-of-type")}}, {{cssxref(":first-of-type")}}, {{cssxref(":last-of-type")}}: CSS pseudo-classes to select the desired column cells diff --git a/files/en-us/web/html/element/data/index.md b/files/en-us/web/html/element/data/index.md deleted file mode 100644 index cdcefe345f2f964..000000000000000 --- a/files/en-us/web/html/element/data/index.md +++ /dev/null @@ -1,125 +0,0 @@ ---- -title: "<data>: The Data element" -slug: Web/HTML/Element/data -page-type: html-element -browser-compat: html.elements.data ---- - -{{HTMLSidebar}} - -The **`<data>`** [HTML](/en-US/docs/Web/HTML) element links a given piece of content with a machine-readable translation. If the content is time- or date-related, the {{HTMLElement("time")}} element must be used. - -{{InteractiveExample("HTML Demo: &lt;data&gt;", "tabbed-shorter")}} - -```html interactive-example -<p>New Products:</p> -<ul> - <li><data value="398">Mini Ketchup</data></li> - <li><data value="399">Jumbo Ketchup</data></li> - <li><data value="400">Mega Jumbo Ketchup</data></li> -</ul> -``` - -```css interactive-example -data:hover::after { - content: " (ID " attr(value) ")"; - font-size: 0.7em; -} -``` - -## Attributes - -This element's attributes include the [global attributes](/en-US/docs/Web/HTML/Global_attributes). - -- `value` - - : This attribute specifies the machine-readable translation of the content of the element. - -## Examples - -The following example displays product names but also associates each name with a product number. - -```html -<p>New Products</p> -<ul> - <li><data value="398">Mini Ketchup</data></li> - <li><data value="399">Jumbo Ketchup</data></li> - <li><data value="400">Mega Jumbo Ketchup</data></li> -</ul> -``` - -### Result - -{{EmbedLiveSample('Examples')}} - -## Technical summary - -<table class="properties"> - <tbody> - <tr> - <th scope="row"> - <a href="/en-US/docs/Web/HTML/Content_categories" - >Content categories</a - > - </th> - <td> - <a href="/en-US/docs/Web/HTML/Content_categories#flow_content" - >Flow content</a - >, - <a href="/en-US/docs/Web/HTML/Content_categories#phrasing_content" - >phrasing content</a - >, palpable content. - </td> - </tr> - <tr> - <th scope="row">Permitted content</th> - <td> - <a href="/en-US/docs/Web/HTML/Content_categories#phrasing_content" - >Phrasing content</a - >. - </td> - </tr> - <tr> - <th scope="row">Tag omission</th> - <td>None, both the starting and ending tag are mandatory.</td> - </tr> - <tr> - <th scope="row">Permitted parents</th> - <td> - Any element that accepts - <a href="/en-US/docs/Web/HTML/Content_categories#phrasing_content" - >phrasing content</a - >. - </td> - </tr> - <tr> - <th scope="row">Implicit ARIA role</th> - <td> - <code - ><a href="/en-US/docs/Web/Accessibility/ARIA/Roles/generic_role" - >generic</a - ></code - > - </td> - </tr> - <tr> - <th scope="row">Permitted ARIA roles</th> - <td>Any</td> - </tr> - <tr> - <th scope="row">DOM interface</th> - <td>{{domxref("HTMLDataElement")}}</td> - </tr> - </tbody> -</table> - -## Specifications - -{{Specifications}} - -## Browser compatibility - -{{Compat}} - -## See also - -- The HTML {{HTMLElement("time")}} element. diff --git a/files/en-us/web/html/element/datalist/index.md b/files/en-us/web/html/element/datalist/index.md deleted file mode 100644 index 7b1e1f79796621a..000000000000000 --- a/files/en-us/web/html/element/datalist/index.md +++ /dev/null @@ -1,199 +0,0 @@ ---- -title: "<datalist>: The HTML Data List element" -slug: Web/HTML/Element/datalist -page-type: html-element -browser-compat: html.elements.datalist ---- - -{{HTMLSidebar}} - -The **`<datalist>`** [HTML](/en-US/docs/Web/HTML) element contains a set of {{HTMLElement("option")}} elements that represent the permissible or recommended options available to choose from within other controls. - -{{InteractiveExample("HTML Demo: &lt;datalist&gt;", "tabbed-standard")}} - -```html interactive-example -<label for="ice-cream-choice">Choose a flavor:</label> -<input list="ice-cream-flavors" id="ice-cream-choice" name="ice-cream-choice" /> - -<datalist id="ice-cream-flavors"> - <option value="Chocolate"></option> - <option value="Coconut"></option> - <option value="Mint"></option> - <option value="Strawberry"></option> - <option value="Vanilla"></option> -</datalist> -``` - -```css interactive-example -label { - display: block; - margin-bottom: 10px; -} -``` - -To bind the `<datalist>` element to the control, we give it a unique identifier in the [`id`](/en-US/docs/Web/HTML/Global_attributes/id) attribute, and then add the [`list`](/en-US/docs/Web/HTML/Element/input#list) attribute to the {{HTMLElement("input")}} element with the same identifier as value. -Only certain types of {{HTMLElement("input")}} support this behavior, and it can also vary from browser to browser. - -Each `<option>` element should have a `value` attribute, which represents a suggestion to be entered into the input. It can also have a `label` attribute, or, missing that, some text content, which may be displayed by the browser instead of `value` (Firefox), or in addition to `value` (Chrome and Safari, as supplemental text). The exact content of the drop-down menu depends on the browser, but when clicked, content entered into control field will always come from the `value` attribute. - -> **Note:** `<datalist>` is not a replacement for {{HTMLElement("select")}}. A `<datalist>` does not represent an input itself; it is a list of suggested values for an associated control. The control can still accept any value that passes validation, even if it is not in this suggestion list. - -## Attributes - -This element has no other attributes than the [global attributes](/en-US/docs/Web/HTML/Global_attributes), common to all elements. - -## Accessibility - -When deciding to use the `<datalist>` element, here are some accessibility issues to be mindful of: - -- The font size of the data list's options does not zoom, always remaining the same size. The contents of the autosuggest do not grow or shrink when the rest of the contents are zoomed in or out. -- As targeting the list of options with CSS is very limited to non-existent, rendering can not be styled for high-contrast mode. -- Some screen reader/browser combinations, including NVDA and Firefox, do not announce the contents of the autosuggest popup. - -## Examples - -### Textual types - -Recommended values in types {{HTMLElement("input/text", "text")}}, {{HTMLElement("input/search", "search")}}, {{HTMLElement("input/url", "url")}}, {{HTMLElement("input/tel", "tel")}}, {{HTMLElement("input/email", "email")}} and {{HTMLElement("input/number", "number")}}, are displayed in a drop-down menu when user clicks or double-clicks on the control. -Typically the right side of a control will also have an arrow pointing to the presence of predefined values. - -```html -<label for="myBrowser">Choose a browser from this list:</label> -<input list="browsers" id="myBrowser" name="myBrowser" /> -<datalist id="browsers"> - <option value="Chrome"></option> - <option value="Firefox"></option> - <option value="Opera"></option> - <option value="Safari"></option> - <option value="Microsoft Edge"></option> -</datalist> -``` - -{{EmbedLiveSample("Textual_types", 600, 40)}} - -### Date and Time types - -The types {{HTMLElement("input/month", "month")}}, {{HTMLElement("input/week", "week")}}, {{HTMLElement("input/date", "date")}}, {{HTMLElement("input/time", "time")}} and {{HTMLElement("input/datetime-local", "datetime-local")}} can show an interface that allows a convenient selection of a date and time. -Predefined values can be shown there, allowing the user to quickly fill the control value. - -> [!NOTE] -> When these types are not supported, a basic `text` type will be rendered instead, creating a text field. That field will correctly recognize recommended values and display them to the user in a drop-down menu. - -```html -<input type="time" list="popularHours" /> -<datalist id="popularHours"> - <option value="12:00"></option> - <option value="13:00"></option> - <option value="14:00"></option> -</datalist> -``` - -{{EmbedLiveSample("Date_and_Time_types", 600, 40)}} - -### Range type - -The recommended values in the {{HTMLElement("input/range", "range")}} type will be shown as series of hash marks that the user can easily select. - -```html -<label for="tick">Tip amount:</label> -<input type="range" list="tickmarks" min="0" max="100" id="tick" name="tick" /> -<datalist id="tickmarks"> - <option value="0"></option> - <option value="10"></option> - <option value="20"></option> - <option value="30"></option> -</datalist> -``` - -{{EmbedLiveSample("Range_type", 600, 70)}} - -### Color type - -The {{HTMLElement("input/color", "color")}} type can show predefined colors in a browser-provided interface. - -```html -<label for="colors">Pick a color (preferably a red tone):</label> -<input type="color" list="redColors" id="colors" /> -<datalist id="redColors"> - <option value="#800000"></option> - <option value="#8B0000"></option> - <option value="#A52A2A"></option> - <option value="#DC143C"></option> -</datalist> -``` - -{{EmbedLiveSample("Color_type", 600, 70)}} - -## Technical summary - -<table class="properties"> - <tbody> - <tr> - <th scope="row"> - <a href="/en-US/docs/Web/HTML/Content_categories" - >Content categories</a - > - </th> - <td> - <a href="/en-US/docs/Web/HTML/Content_categories#flow_content" - >Flow content</a - >, - <a href="/en-US/docs/Web/HTML/Content_categories#phrasing_content" - >phrasing content</a - >. - </td> - </tr> - <tr> - <th scope="row">Permitted content</th> - <td> - Either - <a href="/en-US/docs/Web/HTML/Content_categories#phrasing_content" - >phrasing content</a - > - or zero or more {{HTMLElement("option")}} elements. - </td> - </tr> - <tr> - <th scope="row">Tag omission</th> - <td>None, both the starting and ending tag are mandatory.</td> - </tr> - <tr> - <th scope="row">Permitted parents</th> - <td> - Any element that accepts - <a href="/en-US/docs/Web/HTML/Content_categories#phrasing_content" - >phrasing content</a - >. - </td> - </tr> - <tr> - <th scope="row">Implicit ARIA role</th> - <td> - <a href="/en-US/docs/Web/Accessibility/ARIA/Roles/listbox_role" - >listbox</a - > - </td> - </tr> - <tr> - <th scope="row">Permitted ARIA roles</th> - <td>No <code>role</code> permitted</td> - </tr> - <tr> - <th scope="row">DOM interface</th> - <td>{{domxref("HTMLDataListElement")}}</td> - </tr> - </tbody> -</table> - -## Specifications - -{{Specifications}} - -## Browser compatibility - -{{Compat}} - -## See also - -- The {{HTMLElement("input")}} element, and more specifically its [`list`](/en-US/docs/Web/HTML/Element/input#list) attribute; -- The {{HTMLElement("option")}} element. diff --git a/files/en-us/web/html/element/dd/index.md b/files/en-us/web/html/element/dd/index.md deleted file mode 100644 index 92c1a8a0c0560f0..000000000000000 --- a/files/en-us/web/html/element/dd/index.md +++ /dev/null @@ -1,122 +0,0 @@ ---- -title: "<dd>: The Description Details element" -slug: Web/HTML/Element/dd -page-type: html-element -browser-compat: html.elements.dd ---- - -{{HTMLSidebar}} - -The **`<dd>`** [HTML](/en-US/docs/Web/HTML) element provides the description, definition, or value for the preceding term ({{HTMLElement("dt")}}) in a description list ({{HTMLElement("dl")}}). - -{{InteractiveExample("HTML Demo: &lt;dd&gt;", "tabbed-standard")}} - -```html interactive-example -<p>Cryptids of Cornwall:</p> - -<dl> - <dt>Beast of Bodmin</dt> - <dd>A large feline inhabiting Bodmin Moor.</dd> - - <dt>Morgawr</dt> - <dd>A sea serpent.</dd> - - <dt>Owlman</dt> - <dd>A giant owl-like creature.</dd> -</dl> -``` - -```css interactive-example -p, -dt { - font-weight: bold; -} - -dl, -dd { - font-size: 0.9rem; -} - -dd { - margin-bottom: 1em; -} -``` - -## Attributes - -This element only includes the [global attributes](/en-US/docs/Web/HTML/Global_attributes). - -## Examples - -For examples, see the [examples provided for the `<dl>` element](/en-US/docs/Web/HTML/Element/dl#examples). - -## Technical summary - -<table class="properties"> - <tbody> - <tr> - <th scope="row"> - <a href="/en-US/docs/Web/HTML/Content_categories" - >Content categories</a - > - </th> - <td>None.</td> - </tr> - <tr> - <th scope="row">Permitted content</th> - <td> - <a href="/en-US/docs/Web/HTML/Content_categories#flow_content" - >Flow content</a - >. - </td> - </tr> - <tr> - <th scope="row">Tag omission</th> - <td> - The start tag is required. The end tag may be omitted if this element is - immediately followed by another <code>&#x3C;dd></code> element or a - {{HTMLElement("dt")}} element, or if there is no more content in - the parent element. - </td> - </tr> - <tr> - <th scope="row">Permitted parents</th> - <td> - A {{HTMLElement("dl")}} or a - {{HTMLElement("div")}} that is a child of a - {{HTMLElement("dl")}}.<br />This element can be used after a - {{HTMLElement("dt")}} or another <code>&lt;dd&gt;</code> - element. - </td> - </tr> - <tr> - <th scope="row">Implicit ARIA role</th> - <td> - <a href="https://www.w3.org/TR/html-aria/#dfn-no-corresponding-role" - >No corresponding role</a - > - </td> - </tr> - <tr> - <th scope="row">Permitted ARIA roles</th> - <td>No <code>role</code> permitted</td> - </tr> - <tr> - <th scope="row">DOM interface</th> - <td>{{domxref("HTMLElement")}}</td> - </tr> - </tbody> -</table> - -## Specifications - -{{Specifications}} - -## Browser compatibility - -{{Compat}} - -## See also - -- {{HTMLElement("dl")}} -- {{HTMLElement("dt")}} diff --git a/files/en-us/web/html/element/del/index.md b/files/en-us/web/html/element/del/index.md deleted file mode 100644 index ba825ee03e1e62c..000000000000000 --- a/files/en-us/web/html/element/del/index.md +++ /dev/null @@ -1,164 +0,0 @@ ---- -title: "<del>: The Deleted Text element" -slug: Web/HTML/Element/del -page-type: html-element -browser-compat: html.elements.del ---- - -{{HTMLSidebar}} - -The **`<del>`** [HTML](/en-US/docs/Web/HTML) element represents a range of text that has been deleted from a document. This can be used when rendering "track changes" or source code diff information, for example. The {{HTMLElement("ins")}} element can be used for the opposite purpose: to indicate text that has been added to the document. - -{{InteractiveExample("HTML Demo: &lt;del&gt;", "tabbed-standard")}} - -```html interactive-example -<blockquote> - There is <del>nothing</del> <ins>no code</ins> either good or bad, but - <del>thinking</del> <ins>running it</ins> makes it so. -</blockquote> -``` - -```css interactive-example -del { - text-decoration: line-through; - background-color: #fbb; - color: #555; -} - -ins { - text-decoration: none; - background-color: #d4fcbc; -} - -blockquote { - padding-left: 15px; - border-left: 3px solid #d7d7db; - font-size: 1rem; -} -``` - -This element is often (but need not be) rendered by applying a strike-through style to the text. - -## Attributes - -This element's attributes include the [global attributes](/en-US/docs/Web/HTML/Global_attributes). - -- `cite` - - : A URI for a resource that explains the change (for example, meeting minutes). -- `datetime` - - : This attribute indicates the time and date of the change and must be a valid date string with an optional time. If the value cannot be parsed as a date with an optional time string, the element does not have an associated timestamp. For the format of the string without a time, see [Date strings](/en-US/docs/Web/HTML/Date_and_time_formats#date_strings). The format of the string if it includes both date and time is covered in [Local date and time strings](/en-US/docs/Web/HTML/Date_and_time_formats#local_date_and_time_strings). - -## Accessibility - -The presence of the `del` element is not announced by most screen reading technology in its default configuration. It can be made to be announced by using the CSS {{cssxref("content")}} property, along with the {{cssxref("::before")}} and {{cssxref("::after")}} pseudo-elements. - -```css -del::before, -del::after { - clip-path: inset(100%); - clip: rect(1px, 1px, 1px, 1px); - height: 1px; - overflow: hidden; - position: absolute; - white-space: nowrap; - width: 1px; -} - -del::before { - content: " [deletion start] "; -} - -del::after { - content: " [deletion end] "; -} -``` - -Some people who use screen readers deliberately disable announcing content that creates extra verbosity. Because of this, it is important to not abuse this technique and only apply it in situations where not knowing content has been deleted would adversely affect understanding. - -- [Short note on making your mark (more accessible) | The Paciello Group](https://www.tpgi.com/short-note-on-making-your-mark-more-accessible/) -- [Tweaking Text Level Styles | Adrian Roselli](https://adrianroselli.com/2017/12/tweaking-text-level-styles.html) - -## Examples - -```html -<p><del>This text has been deleted</del>, here is the rest of the paragraph.</p> -<del><p>This paragraph has been deleted.</p></del> -``` - -### Result - -{{EmbedLiveSample("Examples")}} - -## Technical summary - -<table class="properties"> - <tbody> - <tr> - <th scope="row"> - <a href="/en-US/docs/Web/HTML/Content_categories" - >Content categories</a - > - </th> - <td> - <a href="/en-US/docs/Web/HTML/Content_categories#phrasing_content" - >Phrasing content</a - >, - <a href="/en-US/docs/Web/HTML/Content_categories#flow_content" - >flow content</a - >. - </td> - </tr> - <tr> - <th scope="row">Permitted content</th> - <td> - <a - href="/en-US/docs/Web/HTML/Content_categories#transparent_content_model" - >Transparent</a - >. - </td> - </tr> - <tr> - <th scope="row">Tag omission</th> - <td>None, both the starting and ending tag are mandatory.</td> - </tr> - <tr> - <th scope="row">Permitted parents</th> - <td> - Any element that accepts - <a href="/en-US/docs/Web/HTML/Content_categories#phrasing_content" - >phrasing content</a - >. - </td> - </tr> - <tr> - <th scope="row">Implicit ARIA role</th> - <td> - <code - ><a href="/en-US/docs/Web/Accessibility/ARIA/Roles/structural_roles#structural_roles_with_html_equivalents">deletion</a - ></code - > - </td> - </tr> - <tr> - <th scope="row">Permitted ARIA roles</th> - <td>Any</td> - </tr> - <tr> - <th scope="row">DOM interface</th> - <td>{{domxref("HTMLModElement")}}</td> - </tr> - </tbody> -</table> - -## Specifications - -{{Specifications}} - -## Browser compatibility - -{{Compat}} - -## See also - -- {{HTMLElement("ins")}} element for insertions into a text -- {{HTMLElement("s")}} element for strikethrough separate from representing deletion of text diff --git a/files/en-us/web/html/element/details/index.md b/files/en-us/web/html/element/details/index.md deleted file mode 100644 index a0092d5750bdaf3..000000000000000 --- a/files/en-us/web/html/element/details/index.md +++ /dev/null @@ -1,291 +0,0 @@ ---- -title: "<details>: The Details disclosure element" -slug: Web/HTML/Element/details -page-type: html-element -browser-compat: html.elements.details ---- - -{{HTMLSidebar}} - -The **`<details>`** [HTML](/en-US/docs/Web/HTML) element creates a disclosure widget in which information is visible only when the widget is toggled into an open state. A summary or label must be provided using the {{HTMLElement("summary")}} element. - -A disclosure widget is typically presented onscreen using a small triangle that rotates (or twists) to indicate open/closed state, with a label next to the triangle. The contents of the `<summary>` element are used as the label for the disclosure widget. The contents of the `<details>` provide the {{glossary("accessible description")}} for the `<summary>`. - -{{InteractiveExample("HTML Demo: &lt;details&gt;", "tabbed-shorter")}} - -```html interactive-example -<details> - <summary>Details</summary> - Something small enough to escape casual notice. -</details> -``` - -```css interactive-example -details { - border: 1px solid #aaa; - border-radius: 4px; - padding: 0.5em 0.5em 0; -} - -summary { - font-weight: bold; - margin: -0.5em -0.5em 0; - padding: 0.5em; -} - -details[open] { - padding: 0.5em; -} - -details[open] summary { - border-bottom: 1px solid #aaa; - margin-bottom: 0.5em; -} -``` - -A `<details>` widget can be in one of two states. The default _closed_ state displays only the triangle and the label inside `<summary>` (or a {{Glossary("user agent")}}-defined default string if no `<summary>`). - -When the user clicks on the widget or focuses it then presses the space bar, it "twists" open, revealing its contents. The common use of a triangle which rotates or twists around to represent opening or closing the widget is why these are sometimes called "twisty". - -You can use CSS to style the disclosure widget, and you can programmatically open and close the widget by setting/removing its [`open`](#open) attribute. Unfortunately, at this time, there's no built-in way to animate the transition between open and closed. - -By default when closed, the widget is only tall enough to display the disclosure triangle and summary. When open, it expands to display the details contained within. - -Fully standards-compliant implementations automatically apply the CSS `{{cssxref("display")}}: list-item` to the {{HTMLElement("summary")}} element. You can use this or the {{cssxref("::marker")}} pseudo-element to [customize the disclosure widget](/en-US/docs/Web/HTML/Element/summary#changing_the_summarys_icon). - -## Attributes - -This element includes the [global attributes](/en-US/docs/Web/HTML/Global_attributes). - -- `open` - - - : This Boolean attribute indicates whether the details — that is, the contents of the `<details>` element — are currently visible. The details are shown when this attribute exists, or hidden when this attribute is absent. By default this attribute is absent which means the details are not visible. - - > [!NOTE] - > You have to remove this attribute entirely to make the details hidden. `open="false"` makes the details visible because this attribute is Boolean. - -- `name` - - - : This attribute enables multiple `<details>` elements to be connected, with only one open at a time. This allows developers to easily create UI features such as accordions without scripting. - - The `name` attribute specifies a group name — give multiple `<details>` elements the same `name` value to group them. Only one of the grouped `<details>` elements can be open at a time — opening one will cause another to close. If multiple grouped `<details>` elements are given the `open` attribute, only the first one in the source order will be rendered open. - - > **Note:** `<details>` elements don't have to be adjacent to one another in the source to be part of the same group. - -## Events - -In addition to the usual events supported by HTML elements, the `<details>` element supports the {{domxref("HTMLElement/toggle_event", "toggle")}} event, which is dispatched to the `<details>` element whenever its state changes between open and closed. It is sent _after_ the state is changed, although if the state changes multiple times before the browser can dispatch the event, the events are coalesced so that only one is sent. - -You can use an event listener for the `toggle` event to detect when the widget changes state: - -```js -details.addEventListener("toggle", (event) => { - if (details.open) { - /* the element was toggled open */ - } else { - /* the element was toggled closed */ - } -}); -``` - -## Examples - -### A basic disclosure example - -This example shows a basic `<details>` element with a `<summary>`. - -```html -<details> - <summary>System Requirements</summary> - <p> - Requires a computer running an operating system. The computer must have some - memory and ideally some kind of long-term storage. An input device as well - as some form of output device is recommended. - </p> -</details> -``` - -#### Result - -{{EmbedLiveSample("A_basic_disclosure_example", 650, 150)}} - -### Creating an open disclosure box - -To start the `<details>` box in its open state, add the Boolean `open` attribute: - -```html -<details open> - <summary>System Requirements</summary> - <p> - Requires a computer running an operating system. The computer must have some - memory and ideally some kind of long-term storage. An input device as well - as some form of output device is recommended. - </p> -</details> -``` - -#### Result - -{{EmbedLiveSample("Creating_an_open_disclosure_box", 650, 150)}} - -### Multiple named disclosure boxes - -We include several `<details>` boxes, all with the same name so only one can be open at a time: - -```html -<details name="reqs"> - <summary>Graduation Requirements</summary> - <p> - Requires 40 credits, including a passing grade in health, geography, - history, economics, and wood shop. - </p> -</details> -<details name="reqs"> - <summary>System Requirements</summary> - <p> - Requires a computer running an operating system. The computer must have some - memory and ideally some kind of long-term storage. An input device as well - as some form of output device is recommended. - </p> -</details> -<details name="reqs"> - <summary>Job Requirements</summary> - <p> - Requires knowledge of HTML, CSS, JavaScript, accessibility, web performance, - privacy, security, and internationalization, as well as a dislike of - broccoli. - </p> -</details> -``` - -#### Result - -{{EmbedLiveSample("Multiple named disclosure boxes", 650, 150)}} - -Try opening all the disclosure widgets. When you open one, all the others automatically close. - -### Customizing the appearance - -Now let's apply some CSS to customize the appearance of the disclosure box. - -#### CSS - -```css -details { - font: - 16px "Open Sans", - Calibri, - sans-serif; - width: 620px; -} - -details > summary { - padding: 2px 6px; - width: 15em; - background-color: #ddd; - border: none; - box-shadow: 3px 3px 4px black; - cursor: pointer; -} - -details > p { - border-radius: 0 0 10px 10px; - background-color: #ddd; - padding: 2px 6px; - margin: 0; - box-shadow: 3px 3px 4px black; -} - -details:open > summary { - background-color: #ccf; -} -``` - -This CSS creates a look similar to a tabbed interface, where clicking the tab opens it to reveal its contents. - -> [!NOTE] -> In browsers that don't support the {{cssxref(":open")}} pseudo-class, you can use the attribute selector `details[open]` to style the `<details>` element when it is in the open state. - -#### HTML - -```html -<details> - <summary>System Requirements</summary> - <p> - Requires a computer running an operating system. The computer must have some - memory and ideally some kind of long-term storage. An input device as well - as some form of output device is recommended. - </p> -</details> -``` - -#### Result - -{{EmbedLiveSample("Customizing_the_appearance", 650, 150)}} - -See the {{htmlelement("summary")}} page for an [example of customizing the disclosure widget](/en-US/docs/Web/HTML/Element/summary#changing_the_summarys_icon). - -## Technical summary - -<table class="properties"> - <tbody> - <tr> - <th scope="row"> - <a href="/en-US/docs/Web/HTML/Content_categories" - >Content categories</a - > - </th> - <td> - <a href="/en-US/docs/Web/HTML/Content_categories#flow_content" - >Flow content</a - >, sectioning root, interactive content, palpable content. - </td> - </tr> - <tr> - <th scope="row">Permitted content</th> - <td> - One {{HTMLElement("summary")}} element followed by - <a href="/en-US/docs/Web/HTML/Content_categories#flow_content" - >flow content</a - >. - </td> - </tr> - <tr> - <th scope="row">Tag omission</th> - <td>None, both the starting and ending tag are mandatory.</td> - </tr> - <tr> - <th scope="row">Permitted parents</th> - <td> - Any element that accepts - <a href="/en-US/docs/Web/HTML/Content_categories#flow_content" - >flow content</a - >. - </td> - </tr> - <tr> - <th scope="row">Implicit ARIA role</th> - <td><a href="/en-US/docs/Web/Accessibility/ARIA/Roles/group_role"><code>group</code></a></td> - </tr> - <tr> - <th scope="row">Permitted ARIA roles</th> - <td>No <code>role</code> permitted</td> - </tr> - <tr> - <th scope="row">DOM interface</th> - <td>{{domxref("HTMLDetailsElement")}}</td> - </tr> - </tbody> -</table> - -## Specifications - -{{Specifications}} - -## Browser compatibility - -{{Compat}} - -## See also - -- {{HTMLElement("summary")}} diff --git a/files/en-us/web/html/element/dfn/index.md b/files/en-us/web/html/element/dfn/index.md deleted file mode 100644 index 2693841914690e0..000000000000000 --- a/files/en-us/web/html/element/dfn/index.md +++ /dev/null @@ -1,199 +0,0 @@ ---- -title: "<dfn>: The Definition element" -slug: Web/HTML/Element/dfn -page-type: html-element -browser-compat: html.elements.dfn ---- - -{{HTMLSidebar}} - -The **`<dfn>`** [HTML](/en-US/docs/Web/HTML) element indicates a term to be defined. The `<dfn>` element should be used in a complete definition statement, where the full definition of the term can be one of the following: - -- The ancestor paragraph (a block of text, sometimes marked by a {{HTMLElement("p")}} element) -- The {{HTMLElement("dt")}}/{{HTMLElement("dd")}} pairing -- The nearest [section](/en-US/docs/Web/HTML/Content_categories#sectioning_content) ancestor of the `<dfn>` element, - -{{InteractiveExample("HTML Demo: &lt;dfn&gt;", "tabbed-shorter")}} - -```html interactive-example -<p> - A <dfn id="def-validator">validator</dfn> is a program that checks for syntax - errors in code or documents. -</p> -``` - -```css interactive-example -/* stylelint-disable-next-line block-no-empty */ -dfn { -} -``` - -## Attributes - -This element's attributes include the [global attributes](/en-US/docs/Web/HTML/Global_attributes). - -The [`title`](/en-US/docs/Web/HTML/Global_attributes/title) attribute has special meaning, as noted below. - -## Usage notes - -There are some not-entirely-obvious aspects to using the `<dfn>` element. We examine those here. - -### Specifying the term being defined - -The term being defined is identified following these rules: - -1. If the `<dfn>` element has a [`title`](/en-US/docs/Web/HTML/Global_attributes/title) attribute, the value of the `title` attribute is considered to be the term being defined. The element must still have text within it, but that text may be an abbreviation (perhaps using {{HTMLElement("abbr")}}) or another form of the term. -2. If the `<dfn>` contains a single child element and does not have any text content of its own, and the child element is an {{HTMLElement("abbr")}} element with a `title` attribute itself, then the exact value of the `<abbr>` element's `title` is the term being defined. -3. Otherwise, the text content of the `<dfn>` element is the term being defined. This is shown [in the first example below](#basic_identification_of_a_term). - -> [!NOTE] -> If the `<dfn>` element has a `title` attribute, it _must_ contain the term being defined and no other text. - -### Links to `<dfn>` elements - -If you include an [`id`](/en-US/docs/Web/HTML/Global_attributes/id) attribute on the `<dfn>` element, you can then link to it using {{HTMLElement("a")}} elements. Such links should be uses of the term, with the intent being that the reader can quickly navigate to the term's definition if they're not already aware of it, by clicking on the term's link. - -This is shown in the example under [Links to definitions](#links_to_definitions) below. - -## Examples - -Let's take a look at some examples of various usage scenarios. - -### Basic identification of a term - -This example uses a plain `<dfn>` element to identify the location of a term within the definition. - -#### HTML - -```html -<p> - The <strong>HTML Definition element (<dfn>&lt;dfn&gt;</dfn>)</strong> is used - to indicate the term being defined within the context of a definition phrase - or sentence. -</p> -``` - -Since the `<dfn>` element has no `title`, the text contents of the `<dfn>` element itself are used as the term being defined. - -#### Result - -{{EmbedLiveSample("Basic_identification_of_a_term", 650, 120)}} - -### Links to definitions - -To add links to the definitions, you create the link the same way you always do, with the {{HTMLElement("a")}} element. - -#### HTML - -```html-nolint -<p> - The - <strong>HTML Definition element (<dfn id="definition-dfn">&lt;dfn&gt;</dfn>)</strong> - is used to indicate the term being defined within the context of a definition - phrase or sentence. -</p> - -<p> - Lorem ipsum dolor sit amet, consectetur adipiscing elit. Graece donan, Latine - voluptatem vocant. Confecta res esset. Duo Reges: constructio interrete. - Scrupulum, inquam, abeunti; -</p> - -<p> - Because of all of that, we decided to use the - <code><a href="#definition-dfn">&lt;dfn&gt;</a></code> element for this - project. -</p> -``` - -Here we see the definition — now with an [`id`](/en-US/docs/Web/HTML/Global_attributes/id) attribute, `"definition-dfn"`, which can be used as the target of a link. Later on, a link is created using `<a>` with the [`href`](/en-US/docs/Web/HTML/Element/a#href) attribute set to `"#definition-dfn"` to set up the link back to the definition. - -#### Result - -{{EmbedLiveSample("Links_to_definitions", 650, 300)}} - -### Using abbreviations and definitions together - -In some cases, you may wish to use an abbreviation for a term when defining it. This can be done by using the `<dfn>` and {{HTMLElement("abbr")}} elements in tandem, like this: - -#### HTML - -```html -<p> - The <dfn><abbr title="Hubble Space Telescope">HST</abbr></dfn> is among the - most productive scientific instruments ever constructed. It has been in orbit - for over 20 years, scanning the sky and returning data and photographs of - unprecedented quality and detail. -</p> - -<p> - Indeed, the <abbr title="Hubble Space Telescope">HST</abbr> has arguably done - more to advance science than any device ever built. -</p> -``` - -Note the `<abbr>` element nested inside the `<dfn>`. The former establishes that the term is an abbreviation ("HST") and specifies the full term ("Hubble Space Telescope") in its `title` attribute. The latter indicates that the abbreviated term represents a term being defined. - -#### Result - -{{EmbedLiveSample("Using_abbreviations_and_definitions_together", 650, 200)}} - -## Technical summary - -<table class="properties"> - <tbody> - <tr> - <th scope="row"> - <a href="/en-US/docs/Web/HTML/Content_categories">Content categories</a> - </th> - <td> - <a href="/en-US/docs/Web/HTML/Content_categories#flow_content">Flow content</a>, - <a href="/en-US/docs/Web/HTML/Content_categories#phrasing_content">phrasing content</a>, - <a href="/en-US/docs/Web/HTML/Content_categories#palpable_content">palpable content</a>. - </td> - </tr> - <tr> - <th scope="row">Permitted content</th> - <td> - <a href="/en-US/docs/Web/HTML/Content_categories#phrasing_content">Phrasing content</a>, - but no <code>&lt;dfn&gt;</code> element must be a descendant. - </td> - </tr> - <tr> - <th scope="row">Tag omission</th> - <td>None, both the starting and ending tag are mandatory.</td> - </tr> - <tr> - <th scope="row">Permitted parents</th> - <td> - Any element that accepts - <a href="/en-US/docs/Web/HTML/Content_categories#phrasing_content">phrasing content</a>. - </td> - </tr> - <tr> - <th scope="row">Implicit ARIA role</th> - <td><a href="/en-US/docs/Web/Accessibility/ARIA/Roles/term_role"><code>term</code></a></td> - </tr> - <tr> - <th scope="row">Permitted ARIA roles</th> - <td>Any</td> - </tr> - <tr> - <th scope="row">DOM interface</th> - <td>{{domxref("HTMLElement")}}</td> - </tr> - </tbody> -</table> - -## Specifications - -{{Specifications}} - -## Browser compatibility - -{{Compat}} - -## See also - -- Elements related to definition lists: {{HTMLElement("dl")}}, {{HTMLElement("dt")}}, {{HTMLElement("dd")}} -- {{HTMLElement("abbr")}} diff --git a/files/en-us/web/html/element/dialog/index.md b/files/en-us/web/html/element/dialog/index.md deleted file mode 100644 index 39e745647eeca53..000000000000000 --- a/files/en-us/web/html/element/dialog/index.md +++ /dev/null @@ -1,582 +0,0 @@ ---- -title: "<dialog>: The Dialog element" -slug: Web/HTML/Element/dialog -page-type: html-element -browser-compat: html.elements.dialog ---- - -{{HTMLSidebar}} - -The **`<dialog>`** [HTML](/en-US/docs/Web/HTML) element represents a modal or non-modal dialog box or other interactive component, such as a dismissible alert, inspector, or subwindow. - -The HTML `<dialog>` element is used to create both modal and non-modal dialog boxes. Modal dialog boxes interrupt interaction with the rest of the page being inert, while non-modal dialog boxes allow interaction with the rest of the page. - -JavaScript should be used to display the `<dialog>` element. Use the {{domxref("HTMLDialogElement.showModal()", ".showModal()")}} method to display a modal dialog and the {{domxref("HTMLDialogElement.show()", ".show()")}} method to display a non-modal dialog. The dialog box can be closed using the {{domxref("HTMLDialogElement.close()", ".close()")}} method or using the [`dialog`](/en-US/docs/Web/HTML/Element/form#method) method when submitting a `<form>` that is nested within the `<dialog>` element. Modal dialogs can also be closed by pressing the <kbd>Esc</kbd> key. - -## Attributes - -This element includes the [global attributes](/en-US/docs/Web/HTML/Global_attributes). - -> [!WARNING] -> The `tabindex` attribute must not be used on the `<dialog>` element. See [usage notes](#usage_notes). - -- `open` - - - : Indicates that the dialog box is active and is available for interaction. If the `open` attribute is not set, the dialog box will not be visible to the user. - It is recommended to use the `.show()` or `.showModal()` method to render dialogs, rather than the `open` attribute. If a `<dialog>` is opened using the `open` attribute, it is non-modal. - - > [!NOTE] - > While you can toggle between the open and closed states of non-modal dialog boxes by toggling the presence of the `open` attribute, this approach is not recommended. - -## Usage notes - -- HTML {{HTMLElement("form")}} elements can be used to close a dialog box if they have the attribute `method="dialog"` or if the button used to submit the form has [`formmethod="dialog"`](/en-US/docs/Web/HTML/Element/input#formmethod) set. When a `<form>` within a `<dialog>` is submitted via the `dialog` method, the dialog box closes, the states of the form controls are saved but not submitted, and the {{domxref("HTMLDialogElement.returnValue", "returnValue")}} property gets set to the value of the button that was activated. -- The CSS {{cssxref('::backdrop')}} pseudo-element can be used to style the backdrop of a modal dialog, which is displayed behind the `<dialog>` element when the dialog is displayed using the {{domxref("HTMLDialogElement.showModal()")}} method. For example, this pseudo-element could be used to blur, darken, or otherwise obfuscate the inert content behind the modal dialog. -- The [`autofocus`](/en-US/docs/Web/HTML/Global_attributes/autofocus) attribute should be added to the element the user is expected to interact with immediately upon opening a modal dialog. If no other element involves more immediate interaction, it is recommended to add `autofocus` to the close button inside the dialog, or the dialog itself if the user is expected to click/activate it to dismiss. -- Do not add the `tabindex` property to the `<dialog>` element as it is not interactive and does not receive focus. The dialog's contents, including the close button contained in the dialog, can receive focus and be interactive. - -## Accessibility - -When implementing a dialog, it is important to consider the most appropriate place to set user focus. When using {{domxref("HTMLDialogElement.showModal()")}} to open a `<dialog>`, focus is set on the first nested focusable element. Explicitly indicating the initial focus placement by using the [`autofocus`](/en-US/docs/Web/HTML/Global_attributes/autofocus) attribute will help ensure initial focus is set on the element deemed the best initial focus placement for any particular dialog. When in doubt, as it may not always be known where initial focus could be set within a dialog, particularly for instances where a dialog's content is dynamically rendered when invoked, the `<dialog>` element itself may provide the best initial focus placement. - -Ensure a mechanism is provided to allow users to close the dialog. The most robust way to ensure that all users can close the dialog is to include an explicit button to do so, such as a confirmation, cancellation, or close button. - -By default, a dialog invoked by the `showModal()` method can be dismissed by pressing the <kbd>Esc</kbd> key. A non-modal dialog does not dismiss via the <kbd>Esc</kbd> key by default, and depending on what the non-modal dialog represents, it may not be desired for this behavior. Keyboard users expect the <kbd>Esc</kbd> key to close modal dialogs; ensure that this behavior is implemented and maintained. If multiple modal dialogs are open, pressing the <kbd>Esc</kbd> key should close only the last shown dialog. When using `<dialog>`, this behavior is provided by the browser. - -While dialogs can be created using other elements, the native `<dialog>` element provides usability and accessibility features that must be replicated if you use other elements for a similar purpose. If you're creating a custom dialog implementation, ensure that all expected default behaviors are supported and proper labeling recommendations are followed. - -The `<dialog>` element is exposed by browsers in a manner similar to custom dialogs that use the ARIA [role="dialog"](/en-US/docs/Web/Accessibility/ARIA/Roles/dialog_role) attribute. `<dialog>` elements invoked by the `showModal()` method implicitly have [aria-modal="true"](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-modal), whereas `<dialog>` elements invoked by the `show()` method or displayed using the `open` attribute or by changing the default `display` of a `<dialog>` are exposed as `[aria-modal="false"]`. When implementing modal dialogs, everything other than the `<dialog>` and its contents should be rendered inert using the [`inert`](/en-US/docs/Web/HTML/Global_attributes/inert) attribute. When using `<dialog>` along with the `HTMLDialogElement.showModal()` method, this behavior is provided by the browser. - -## Examples - -### HTML-only dialog - -This example demonstrates the creation of a non-modal dialog by using only HTML. Because of the boolean `open` attribute in the `<dialog>` element, the dialog appears open when the page loads. The dialog can be closed by clicking the "OK" button because the `method` attribute in the `<form>` element is set to `"dialog"`. In this case, no JavaScript is needed to close the form. - -```html -<dialog open> - <p>Greetings, one and all!</p> - <form method="dialog"> - <button>OK</button> - </form> -</dialog> -``` - -#### Result - -{{EmbedLiveSample("HTML-only_dialog", "100%", 200)}} - -> [!NOTE] -> Reload the page to reset the output. - -This dialog is initially open because of the presence of the `open` attribute. Dialogs that are displayed using the `open` attribute are non-modal. After clicking "OK", the dialog gets dismissed, leaving the Result frame empty. When the dialog is dismissed, there is no method provided to reopen it. For this reason, the preferred method to display non-modal dialogs is by using the {{domxref("HTMLDialogElement.show()")}} method. It is possible to toggle the display of the dialog by adding or removing the boolean `open` attribute, but it is not the recommended practice. - -### Creating a modal dialog - -This example demonstrates a modal dialog with a [gradient](/en-US/docs/Web/CSS/gradient) backdrop. The `.showModal()` method opens the modal dialog when the "Show the dialog" button is activated. The dialog can be closed by pressing the <kbd>Esc</kbd> key or via the `close()` method when the "Close" button within the dialog is activated. - -When a dialog opens, the browser, by default, gives focus to the first element that can be focused within the dialog. In this example, the [`autofocus`](/en-US/docs/Web/HTML/Global_attributes/autofocus) attribute is applied to the "Close" button, giving it focus when the dialog opens, as this is the element we expect the user will interact with immediately after the dialog opens. - -#### HTML - -```html -<dialog> - <button autofocus>Close</button> - <p>This modal dialog has a groovy backdrop!</p> -</dialog> -<button>Show the dialog</button> -``` - -#### CSS - -We can style the backdrop of the dialog by using the {{cssxref('::backdrop')}} pseudo-element. - -```css -::backdrop { - background-image: linear-gradient( - 45deg, - magenta, - rebeccapurple, - dodgerblue, - green - ); - opacity: 0.75; -} -``` - -#### JavaScript - -The dialog is opened modally using the `.showModal()` method and closed using the `.close()` or `.requestClose()` methods. - -```js -const dialog = document.querySelector("dialog"); -const showButton = document.querySelector("dialog + button"); -const closeButton = document.querySelector("dialog button"); - -// "Show the dialog" button opens the dialog modally -showButton.addEventListener("click", () => { - dialog.showModal(); -}); - -// "Close" button closes the dialog -closeButton.addEventListener("click", () => { - dialog.close(); -}); -``` - -#### Result - -{{EmbedLiveSample("Creating_a_modal_dialog", "100%", 200)}} - -When the modal dialog is displayed, it appears above any other dialogs that might be present. Everything outside the modal dialog is inert and interactions outside the dialog are blocked. Notice that when the dialog is open, with the exception of the dialog itself, interaction with the document is not possible; the "Show the dialog" button is mostly obfuscated by the almost opaque backdrop of the dialog and is inert. - -### Handling the return value from the dialog - -This example demonstrates the [`returnValue`](/en-US/docs/Web/API/HTMLDialogElement/returnValue) of the `<dialog>` element and how to close a modal dialog by using a form. By default, the `returnValue` is the empty string or the value of the button that submits the form within the `<dialog>` element, if there is one. - -This example opens a modal dialog when the "Show the dialog" button is activated. The dialog contains a form with a {{HTMLElement("select")}} and two {{HTMLElement("button")}} elements, which default to `type="submit"`. An event listener updates the value of the "Confirm" button when the select option changes. If the "Confirm" button is activated to close the dialog, the current value of the button is the return value. If the dialog is closed by pressing the "Cancel" button, the `returnValue` is `cancel`. - -When the dialog is closed, the return value is displayed under the "Show the dialog" button. If the dialog is closed by pressing the <kbd>Esc</kbd> key, the `returnValue` is not updated, and the `close` event doesn't occur, so the text in the {{HTMLElement("output")}} is not updated. - -#### HTML - -```html -<!-- A modal dialog containing a form --> -<dialog id="favDialog"> - <form> - <p> - <label> - Favorite animal: - <select> - <option value="default">Choose…</option> - <option>Brine shrimp</option> - <option>Red panda</option> - <option>Spider monkey</option> - </select> - </label> - </p> - <div> - <button value="cancel" formmethod="dialog">Cancel</button> - <button id="confirmBtn" value="default">Confirm</button> - </div> - </form> -</dialog> -<p> - <button id="showDialog">Show the dialog</button> -</p> -<output></output> -``` - -#### JavaScript - -```js -const showButton = document.getElementById("showDialog"); -const favDialog = document.getElementById("favDialog"); -const outputBox = document.querySelector("output"); -const selectEl = favDialog.querySelector("select"); -const confirmBtn = favDialog.querySelector("#confirmBtn"); - -// "Show the dialog" button opens the <dialog> modally -showButton.addEventListener("click", () => { - favDialog.showModal(); -}); - -// "Cancel" button closes the dialog without submitting because of [formmethod="dialog"], triggering a close event. -favDialog.addEventListener("close", (e) => { - outputBox.value = - favDialog.returnValue === "default" - ? "No return value." - : `ReturnValue: ${favDialog.returnValue}.`; // Have to check for "default" rather than empty string -}); - -// Prevent the "confirm" button from the default behavior of submitting the form, and close the dialog with the `close()` method, which triggers the "close" event. -confirmBtn.addEventListener("click", (event) => { - event.preventDefault(); // We don't want to submit this fake form - favDialog.close(selectEl.value); // Have to send the select box value here. -}); -``` - -#### Result - -{{EmbedLiveSample("Handling the return value from the dialog", "100%", 300)}} - -The above examples demonstrate the following three methods of closing modal dialogs: - -- By submitting the form within the dialog form using the `dialog` method (as seen in the [HTML-only example](#html-only_dialog)). -- By pressing the <kbd>Esc</kbd> key. -- By calling the {{domxref("HTMLDialogElement.close()")}} method (as seen in the [modal example](#creating_a_modal_dialog)). - In this example, the "Cancel" button closes the dialog via the `dialog` form method and the "Confirm" button closes the dialog via the {{domxref("HTMLDialogElement.close()")}} method. - -The "Cancel" button includes the [`formmethod="dialog"`](/en-US/docs/Web/HTML/Element/input/submit#formmethod) attribute, which overrides the {{HTMLElement("form")}}'s default {{HTTPMethod("GET")}} method. When a form's method is [`dialog`](#usage_notes), the state of the form is saved but not submitted, and the dialog gets closed. - -Without an `action`, submitting the form via the default {{HTTPMethod("GET")}} method causes a page to reload. We use JavaScript to prevent the submission and close the dialog with the {{domxref("event.preventDefault()")}} and {{domxref("HTMLDialogElement.close()")}} methods, respectively. - -It is important to provide a closing mechanism within every `dialog` element. The <kbd>Esc</kbd> key does not close non-modal dialogs by default, nor can one assume that a user will even have access to a physical keyboard (e.g., someone using a touch screen device without access to a keyboard). - -### Closing a dialog with a required form input - -When a form inside a dialog has a required input, the user agent will only let you close the dialog once you provide a value for the required input. To close such dialog, either use the [`formnovalidate`](/en-US/docs/Web/HTML/Element/input#formnovalidate) attribute on the close button or call the `close()` method on the dialog object when the close button is clicked. - -```html -<dialog id="dialog"> - <form method="dialog"> - <p> - <label> - Favorite animal: - <input type="text" required /> - </label> - </p> - <div> - <input type="submit" id="normal-close" value="Normal close" /> - <input - type="submit" - id="novalidate-close" - value="Novalidate close" - formnovalidate /> - <input type="submit" id="js-close" value="JS close" /> - </div> - </form> -</dialog> -<p> - <button id="show-dialog">Show the dialog</button> -</p> -<output></output> -``` - -```css hidden -[type="submit"] { - margin-right: 1rem; -} -``` - -#### JavaScript - -```js -const showBtn = document.getElementById("show-dialog"); -const dialog = document.getElementById("dialog"); -const jsCloseBtn = dialog.querySelector("#js-close"); - -showBtn.addEventListener("click", () => { - dialog.showModal(); -}); - -jsCloseBtn.addEventListener("click", (e) => { - e.preventDefault(); - dialog.close(); -}); -``` - -#### Result - -{{EmbedLiveSample("Closing a dialog with a required form input", "100%", 300)}} - -From the output, we see it is impossible to close the dialog using the _Normal close_ button. But the dialog can be closed if we bypass the form validation using the `formnovalidate` attribute on the _Cancel_ button. Programmatically, `dialog.close()` will also close such dialog. - -### Animating dialogs - -`<dialog>`s are set to [`display: none;`](/en-US/docs/Web/CSS/display) when hidden and `display: block;` when shown, as well as being removed from / added to the {{glossary("top layer")}} and the [accessibility tree](/en-US/docs/Web/Performance/Guides/How_browsers_work#building_the_accessibility_tree). Therefore, for `<dialog>` elements to be animated the {{cssxref("display")}} property needs to be animatable. [Supporting browsers](/en-US/docs/Web/CSS/display#browser_compatibility) animate `display` with a variation on the [discrete animation type](/en-US/docs/Web/CSS/CSS_animated_properties#discrete). Specifically, the browser will flip between `none` and another value of `display` so that the animated content is shown for the entire animation duration. - -So for example: - -- When animating `display` from `none` to `block` (or another visible `display` value), the value will flip to `block` at `0%` of the animation duration so it is visible throughout. -- When animating `display` from `block` (or another visible `display` value) to `none`, the value will flip to `none` at `100%` of the animation duration so it is visible throughout. - -> [!NOTE] -> When animating using [CSS transitions](/en-US/docs/Web/CSS/CSS_transitions), [`transition-behavior: allow-discrete`](/en-US/docs/Web/CSS/transition-behavior) needs to be set to enable the above behavior. This behavior is available by default when animating with [CSS animations](/en-US/docs/Web/CSS/CSS_animations); an equivalent step is not required. - -#### Transitioning dialog elements - -When animating `<dialog>`s with CSS transitions, the following features are required: - -- [`@starting-style`](/en-US/docs/Web/CSS/@starting-style) at-rule - - : Provides a set of starting values for properties set on the `<dialog>` that you want to transition from every time it is opened. This is needed to avoid unexpected behavior. By default, CSS transitions only occur when a property changes from one value to another on a visible element; they are not triggered on elements' first style updates, or when the `display` type changes from `none` to another type. -- [`display`](/en-US/docs/Web/CSS/display) property - - : Add `display` to the transitions list so that the `<dialog>` will remain as `display: block` (or another visible `display` value set on the dialog's open state) for the duration of the transition, ensuring the other transitions are visible. -- [`overlay`](/en-US/docs/Web/CSS/overlay) property - - : Include `overlay` in the transitions list to ensure the removal of the `<dialog>` from the top layer is deferred until the transition completes, again ensuring the transition is visible. -- {{cssxref("transition-behavior")}} property - - : Set `transition-behavior: allow-discrete` on the `display` and `overlay` transitions (or on the {{cssxref("transition")}} shorthand) to enable discrete transitions on these two properties that are not by default animatable. - -Here is a quick example to show what this might look like. - -##### HTML - -The HTML contains a `<dialog>` element, plus a button to show the dialog. Additionally, the `<dialog>` element contains another button to close itself. - -```html -<dialog id="dialog"> - Content here - <button class="close">close</button> -</dialog> - -<button class="show">Show Modal</button> -``` - -##### CSS - -In the CSS, we include a `@starting-style` block that defines the transition starting styles for the `opacity` and `transform` properties, transition end styles on the `dialog:open` state, and default styles on the default `dialog` state to transition back to once the `<dialog>` has appeared. Note how the `<dialog>`'s `transition` list includes not only these properties, but also the `display` and `overlay` properties, each with `allow-discrete` set on them. - -We also set a starting style value for the {{cssxref("background-color")}} property on the [`::backdrop`](/en-US/docs/Web/CSS/::backdrop) that appears behind the `<dialog>` when it opens, to provide a nice darkening animation. The `dialog:open::backdrop` selector selects only the backdrops of `<dialog>` elements when the dialog is open. - -```css -/* Open state of the dialog */ -dialog:open { - opacity: 1; - transform: scaleY(1); -} - -/* Closed state of the dialog */ -dialog { - opacity: 0; - transform: scaleY(0); - transition: - opacity 0.7s ease-out, - transform 0.7s ease-out, - overlay 0.7s ease-out allow-discrete, - display 0.7s ease-out allow-discrete; - /* Equivalent to - transition: all 0.7s allow-discrete; */ -} - -/* Before open state */ -/* Needs to be after the previous dialog:open rule to take effect, - as the specificity is the same */ -@starting-style { - dialog:open { - opacity: 0; - transform: scaleY(0); - } -} - -/* Transition the :backdrop when the dialog modal is promoted to the top layer */ -dialog::backdrop { - background-color: rgb(0 0 0 / 0%); - transition: - display 0.7s allow-discrete, - overlay 0.7s allow-discrete, - background-color 0.7s; - /* Equivalent to - transition: all 0.7s allow-discrete; */ -} - -dialog:open::backdrop { - background-color: rgb(0 0 0 / 25%); -} - -/* This starting-style rule cannot be nested inside the above selector -because the nesting selector cannot represent pseudo-elements. */ - -@starting-style { - dialog:open::backdrop { - background-color: rgb(0 0 0 / 0%); - } -} -``` - -> [!NOTE] -> In browsers that don't support the {{cssxref(":open")}} pseudo-class, you can use the attribute selector `dialog[open]` to style the `<dialog>` element when it is in the open state. - -##### JavaScript - -The JavaScript adds event handlers to the show and close buttons causing them to show and close the `<dialog>` when they are clicked: - -```js -const dialogElem = document.getElementById("dialog"); -const showBtn = document.querySelector(".show"); -const closeBtn = document.querySelector(".close"); - -showBtn.addEventListener("click", () => { - dialogElem.showModal(); -}); - -closeBtn.addEventListener("click", () => { - dialogElem.close(); -}); -``` - -##### Result - -The code renders as follows: - -{{ EmbedLiveSample("Transitioning dialog elements", "100%", "200") }} - -> [!NOTE] -> Because `<dialog>`s change from `display: none` to `display: block` each time they are shown, the `<dialog>` transitions from its `@starting-style` styles to its `dialog:open` styles every time the entry transition occurs. When the `<dialog>` closes, it transitions from its `dialog:open` state to the default `dialog` state. -> -> It is possible for the style transition on entry and exit to be different in such cases. See our [Demonstration of when starting styles are used](/en-US/docs/Web/CSS/@starting-style#demonstration_of_when_starting_styles_are_used) example for a proof of this. - -#### dialog keyframe animations - -When animating a `<dialog>` with CSS keyframe animations, there are some differences to note from transitions: - -- You don't provide a `@starting-style`. -- You include the `display` value in a keyframe; this will be the `display` value for the entirety of the animation, or until another non-`none` display value is encountered. -- You don't need to explicitly enable discrete animations; there is no equivalent to `allow-discrete` inside keyframes. -- You don't need to set `overlay` inside keyframes either; the `display` animation handles the animation of the `<dialog>` from shown to hidden. - -Let's have a look at an example so you can see what this looks like. - -##### HTML - -First, the HTML contains a `<dialog>` element, plus a button to show the dialog. Additionally, the `<dialog>` element contains another button to close itself. - -```html -<dialog id="dialog"> - Content here - <button class="close">close</button> -</dialog> - -<button class="show">Show Modal</button> -``` - -##### CSS - -The CSS defines keyframes to animate between the closed and shown states of the `<dialog>`, plus the fade-in animation for the `<dialog>`'s backdrop. The `<dialog>` animations include animating `display` to make sure the actual visible animation effects remain visible for the whole duration. Note that it wasn't possible to animate the backdrop fade out — the backdrop is immediately removed from the DOM when the `<dialog>` is closed, so there is nothing to animate. - -```css -dialog { - animation: fade-out 0.7s ease-out; -} - -dialog:open { - animation: fade-in 0.7s ease-out; -} - -dialog:open::backdrop { - animation: backdrop-fade-in 0.7s ease-out forwards; -} - -/* Animation keyframes */ - -@keyframes fade-in { - 0% { - opacity: 0; - transform: scaleY(0); - display: none; - } - - 100% { - opacity: 1; - transform: scaleY(1); - display: block; - } -} - -@keyframes fade-out { - 0% { - opacity: 1; - transform: scaleY(1); - display: block; - } - - 100% { - opacity: 0; - transform: scaleY(0); - display: none; - } -} - -@keyframes backdrop-fade-in { - 0% { - background-color: rgb(0 0 0 / 0%); - } - - 100% { - background-color: rgb(0 0 0 / 25%); - } -} - -body, -button { - font-family: system-ui; -} -``` - -##### JavaScript - -Finally, the JavaScript adds event handlers to the buttons to enable showing and closing the `<dialog>`: - -```js -const dialogElem = document.getElementById("dialog"); -const showBtn = document.querySelector(".show"); -const closeBtn = document.querySelector(".close"); - -showBtn.addEventListener("click", () => { - dialogElem.showModal(); -}); - -closeBtn.addEventListener("click", () => { - dialogElem.close(); -}); -``` - -##### Result - -The code renders as follows: - -{{ EmbedLiveSample("dialog keyframe animations", "100%", "200") }} - -## Technical summary - -<table class="properties"> - <tbody> - <tr> - <th scope="row"> - <a href="/en-US/docs/Web/HTML/Content_categories">Content categories</a> - </th> - <td> - <a href="/en-US/docs/Web/HTML/Content_categories#flow_content">Flow content</a>, - <a href="/en-US/docs/Web/HTML/Element/Heading_Elements#sectioning_roots">sectioning root</a> - </td> - </tr> - <tr> - <th scope="row">Permitted content</th> - <td> - <a href="/en-US/docs/Web/HTML/Content_categories#flow_content">Flow content</a> - </td> - </tr> - <tr> - <th scope="row">Tag omission</th> - <td>None, both the starting and ending tag are mandatory.</td> - </tr> - <tr> - <th scope="row">Permitted parents</th> - <td> - Any element that accepts - <a href="/en-US/docs/Web/HTML/Content_categories#flow_content">flow content</a> - </td> - </tr> - <tr> - <th scope="row">Implicit ARIA role</th> - <td> - <a href="/en-US/docs/Web/Accessibility/ARIA/Roles/dialog_role">dialog</a> - </td> - </tr> - <tr> - <th scope="row">Permitted ARIA roles</th> - <td><a href="/en-US/docs/Web/Accessibility/ARIA/Roles/alertdialog_role"><code>alertdialog</code></a></td> - </tr> - <tr> - <th scope="row">DOM interface</th> - <td>{{domxref("HTMLDialogElement")}}</td> - </tr> - </tbody> -</table> - -## Specifications - -{{Specifications}} - -## Browser compatibility - -{{Compat}} - -## See also - -- {{domxref("HTMLDialogElement")}} interface -- {{domxref("HTMLDialogElement/close_event", "close")}} event of the `HTMLDialogElement` interface -- {{domxref("HTMLDialogElement/cancel_event", "cancel")}} event of the `HTMLDialogElement` interface -- {{domxref("HTMLDialogElement/open", "open")}} property of the `HTMLDialogElement` interface -- [`inert`](/en-US/docs/Web/HTML/Global_attributes/inert) global attribute for HTML elements -- {{CSSXref("::backdrop")}} CSS pseudo-element -- [Web forms](/en-US/docs/Learn_web_development/Extensions/Forms) in the Learn area diff --git a/files/en-us/web/html/element/dir/index.md b/files/en-us/web/html/element/dir/index.md deleted file mode 100644 index 8f088ba72ca65fa..000000000000000 --- a/files/en-us/web/html/element/dir/index.md +++ /dev/null @@ -1,46 +0,0 @@ ---- -title: "<dir>: The Directory element" -slug: Web/HTML/Element/dir -page-type: html-element -status: - - deprecated -browser-compat: html.elements.dir ---- - -{{HTMLSidebar}}{{Deprecated_Header}} - -The **`<dir>`** [HTML](/en-US/docs/Web/HTML) element is used as a container for a directory of files and/or folders, potentially with styles and icons applied by the {{Glossary("user agent")}}. Do not use this obsolete element; instead, you should use the {{HTMLElement("ul")}} element for lists, including lists of files. - -> [!WARNING] -> Do not use this element. Though present in early HTML specifications, it has been deprecated in HTML 4, and has since been removed entirely. - -## DOM interface - -This element implements the {{domxref("HTMLDirectoryElement")}} interface. - -## Attributes - -Like all other HTML elements, this element supports the [global attributes](/en-US/docs/Web/HTML/Global_attributes). - -- `compact` {{Deprecated_Inline}} - - : This Boolean attribute hints that the list should be rendered in a compact style. The interpretation of this attribute depends on the user agent and it doesn't work in all browsers. - -<!-- ## Technical summary --> - -## Specifications - -{{Specifications}} - -## Browser compatibility - -{{Compat}} - -## See also - -- Other list-related HTML Elements: {{HTMLElement("ol")}}, {{HTMLElement("ul")}}, {{HTMLElement("li")}}, and {{HTMLElement("menu")}}; -- CSS properties that may be specially useful to style the `<dir>` element: - - - The {{cssxref('list-style')}} property, useful to choose the way the ordinal is displayed. - - [CSS counters](/en-US/docs/Web/CSS/CSS_counter_styles/Using_CSS_counters), useful to handle complex nested lists. - - The {{Cssxref('line-height')}} property, useful to simulate the deprecated [`compact`](#compact) attribute. - - The {{cssxref('margin')}} property, useful to control the indent of the list. diff --git a/files/en-us/web/html/element/div/index.md b/files/en-us/web/html/element/div/index.md deleted file mode 100644 index bedecf86ad5663e..000000000000000 --- a/files/en-us/web/html/element/div/index.md +++ /dev/null @@ -1,178 +0,0 @@ ---- -title: "<div>: The Content Division element" -slug: Web/HTML/Element/div -page-type: html-element -browser-compat: html.elements.div ---- - -{{HTMLSidebar}} - -The **`<div>`** [HTML](/en-US/docs/Web/HTML) element is the generic container for flow content. It has no effect on the content or layout until styled in some way using {{glossary("CSS")}} (e.g. styling is directly applied to it, or some kind of layout model like [Flexbox](/en-US/docs/Web/CSS/CSS_flexible_box_layout) is applied to its parent element). - -{{InteractiveExample("HTML Demo: &lt;div&gt;", "tabbed-standard")}} - -```html interactive-example -<div class="warning"> - <img - src="/shared-assets/images/examples/leopard.jpg" - alt="An intimidating leopard." /> - <p>Beware of the leopard</p> -</div> -``` - -```css interactive-example -.warning { - border: 10px ridge #f00; - background-color: #ff0; - padding: 0.5rem; - display: flex; - flex-direction: column; -} - -.warning img { - width: 100%; -} - -.warning p { - font: small-caps bold 1.2rem sans-serif; - text-align: center; -} -``` - -As a "pure" container, the `<div>` element does not inherently represent anything. Instead, it's used to group content so it can be easily styled using the [`class`](/en-US/docs/Web/HTML/Global_attributes/class) or [`id`](/en-US/docs/Web/HTML/Global_attributes/id) attributes, marking a section of a document as being written in a different language (using the [`lang`](/en-US/docs/Web/HTML/Global_attributes/lang) attribute), and so on. - -## Attributes - -This element includes the [global attributes](/en-US/docs/Web/HTML/Global_attributes). - -> [!NOTE] -> The `align` attribute is obsolete; do not use it anymore. Instead, you should use CSS properties or techniques such as [CSS Grid](/en-US/docs/Web/CSS/CSS_grid_layout) or [CSS Flexbox](/en-US/docs/Learn_web_development/Core/CSS_layout/Flexbox) to align and position `<div>` elements on the page. - -## Usage notes - -- The `<div>` element should be used only when no other semantic element (such as {{HTMLElement("article")}} or {{HTMLElement("nav")}}) is appropriate. - -## Accessibility - -The `<div>` element has [an implicit role of `generic`](https://www.w3.org/TR/wai-aria-1.2/#generic), and not none. This may affect certain ARIA combination declarations that expect a direct descendant element with a certain role to function properly. - -## Examples - -### A basic example - -```html -<div> - <p> - Any kind of content here. Such as &lt;p&gt;, &lt;table&gt;. You name it! - </p> -</div> -``` - -#### Result - -{{EmbedLiveSample("A_basic_example", 650, 60)}} - -### A styled example - -This example creates a shadowed box by applying a style to the `<div>` using CSS. Note the use of the [`class`](/en-US/docs/Web/HTML/Global_attributes/class) attribute on the `<div>` to apply the style named `"shadowbox"` to the element. - -#### HTML - -```html -<div class="shadowbox"> - <p>Here's a very interesting note displayed in a lovely shadowed box.</p> -</div> -``` - -#### CSS - -```css -.shadowbox { - width: 15em; - border: 1px solid #333; - box-shadow: 8px 8px 5px #444; - padding: 8px 12px; - background-image: linear-gradient(180deg, #fff, #ddd 40%, #ccc); -} -``` - -#### Result - -{{EmbedLiveSample("A_styled_example", 650, 120)}} - -## Technical summary - -<table class="properties"> - <tbody> - <tr> - <th scope="row"> - <a href="/en-US/docs/Web/HTML/Content_categories" - >Content categories</a - > - </th> - <td> - <a href="/en-US/docs/Web/HTML/Content_categories#flow_content" - >Flow content</a - >, <a href="/en-US/docs/Web/HTML/Content_categories#palpable_content">palpable content</a>. - </td> - </tr> - <tr> - <th scope="row">Permitted content</th> - <td> - <a href="/en-US/docs/Web/HTML/Content_categories#flow_content" - >Flow content</a - >.<br />Or (in {{glossary("WHATWG")}} HTML): If the parent is a - {{HTMLElement("dl")}} element: one or more - {{HTMLElement("dt")}} elements followed by one or more - {{HTMLElement("dd")}} elements, optionally intermixed with - {{HTMLElement("script")}} and - {{HTMLElement("template")}} elements. - </td> - </tr> - <tr> - <th scope="row">Tag omission</th> - <td>None, both the starting and ending tag are mandatory.</td> - </tr> - <tr> - <th scope="row">Permitted parents</th> - <td> - Any element that accepts - <a href="/en-US/docs/Web/HTML/Content_categories#flow_content" - >flow content</a - >.<br />Or (in {{glossary("WHATWG")}} HTML): - {{HTMLElement("dl")}} element. - </td> - </tr> - <tr> - <th scope="row">Implicit ARIA role</th> - <td> - <code - ><a href="/en-US/docs/Web/Accessibility/ARIA/Roles/generic_role" - >generic</a - ></code - > - </td> - </tr> - <tr> - <th scope="row">Permitted ARIA roles</th> - <td>Any</td> - </tr> - <tr> - <th scope="row">DOM interface</th> - <td>{{domxref("HTMLDivElement")}}</td> - </tr> - </tbody> -</table> - -## Specifications - -{{Specifications}} - -## Browser compatibility - -{{Compat}} - -## See also - -- Semantic sectioning elements: {{HTMLElement("section")}}, {{HTMLElement("article")}}, {{HTMLElement("nav")}}, {{HTMLElement("header")}}, {{HTMLElement("footer")}} -- {{HTMLElement("span")}} element for styling of phrasing content diff --git a/files/en-us/web/html/element/dl/index.md b/files/en-us/web/html/element/dl/index.md deleted file mode 100644 index 9e72b4a8875bab8..000000000000000 --- a/files/en-us/web/html/element/dl/index.md +++ /dev/null @@ -1,270 +0,0 @@ ---- -title: "<dl>: The Description List element" -slug: Web/HTML/Element/dl -page-type: html-element -browser-compat: html.elements.dl ---- - -{{HTMLSidebar}} - -The **`<dl>`** [HTML](/en-US/docs/Web/HTML) element represents a description list. The element encloses a list of groups of terms (specified using the {{HTMLElement("dt")}} element) and descriptions (provided by {{HTMLElement("dd")}} elements). Common uses for this element are to implement a glossary or to display metadata (a list of key-value pairs). - -{{InteractiveExample("HTML Demo: &lt;dl&gt;", "tabbed-standard")}} - -```html interactive-example -<p>Cryptids of Cornwall:</p> - -<dl> - <dt>Beast of Bodmin</dt> - <dd>A large feline inhabiting Bodmin Moor.</dd> - - <dt>Morgawr</dt> - <dd>A sea serpent.</dd> - - <dt>Owlman</dt> - <dd>A giant owl-like creature.</dd> -</dl> -``` - -```css interactive-example -p, -dt { - font-weight: bold; -} - -dl, -dd { - font-size: 0.9rem; -} - -dd { - margin-bottom: 1em; -} -``` - -## Attributes - -This element only includes the [global attributes](/en-US/docs/Web/HTML/Global_attributes). - -## Accessibility - -Each screen reader exposes `<dl>` content differently, including total count, terms/definitions context, and navigation methods. These differences are not necessarily bugs. -As of iOS 14, VoiceOver will announce that `<dl>` content is a list when navigating with the virtual cursor (not via the read-all command). VoiceOver does not support list navigation commands with `<dl>`. Be careful applying ARIA `term` and `definition` roles to `<dl>` constructs as VoiceOver (macOS and iOS) will adjust how they are announced. - -- [VoiceOver on iOS 14 Supports Description Lists](https://adrianroselli.com/2020/09/voiceover-on-ios-14-supports-description-lists.html) -- [Brief Note on Description List Support](https://adrianroselli.com/2022/12/brief-note-on-description-list-support.html) - -## Examples - -### Single term and description - -```html -<dl> - <dt>Firefox</dt> - <dd> - A free, open source, cross-platform, graphical web browser developed by the - Mozilla Corporation and hundreds of volunteers. - </dd> - - <!-- Other terms and descriptions --> -</dl> -``` - -#### Result - -{{EmbedLiveSample("Single_term_and_description")}} - -### Multiple terms, single description - -```html -<dl> - <dt>Firefox</dt> - <dt>Mozilla Firefox</dt> - <dt>Fx</dt> - <dd> - A free, open source, cross-platform, graphical web browser developed by the - Mozilla Corporation and hundreds of volunteers. - </dd> - - <!-- Other terms and descriptions --> -</dl> -``` - -#### Result - -{{EmbedLiveSample("Multiple_terms_single_description")}} - -### Single term, multiple descriptions - -```html -<dl> - <dt>Firefox</dt> - <dd> - A free, open source, cross-platform, graphical web browser developed by the - Mozilla Corporation and hundreds of volunteers. - </dd> - <dd> - The Red Panda also known as the Lesser Panda, Wah, Bear Cat or Firefox, is a - mostly herbivorous mammal, slightly larger than a domestic cat (60 cm long). - </dd> - - <!-- Other terms and descriptions --> -</dl> -``` - -#### Result - -{{EmbedLiveSample("Single_term_multiple_descriptions")}} - -### Multiple terms and descriptions - -It is also possible to define multiple terms with multiple corresponding descriptions, by combining the examples above. - -### Metadata - -Description lists are useful for displaying metadata as a list of key-value pairs. - -```html -<dl> - <dt>Name</dt> - <dd>Godzilla</dd> - <dt>Born</dt> - <dd>1952</dd> - <dt>Birthplace</dt> - <dd>Japan</dd> - <dt>Color</dt> - <dd>Green</dd> -</dl> -``` - -#### Result - -{{EmbedLiveSample('Metadata')}} - -Tip: It can be handy to define a key-value separator in the CSS, such as: - -```css -dt::after { - content: ": "; -} -``` - -### Wrapping name-value groups in `div` elements - -HTML allows wrapping each name-value group in a `<dl>` element in a {{HTMLElement("div")}} element. This can be useful when using [microdata](/en-US/docs/Web/HTML/Microdata), or when [global attributes](/en-US/docs/Web/HTML/Global_attributes) apply to a whole group, or for styling purposes. - -```html -<dl> - <div> - <dt>Name</dt> - <dd>Godzilla</dd> - </div> - <div> - <dt>Born</dt> - <dd>1952</dd> - </div> - <div> - <dt>Birthplace</dt> - <dd>Japan</dd> - </div> - <div> - <dt>Color</dt> - <dd>Green</dd> - </div> -</dl> -``` - -#### Result - -{{EmbedLiveSample('Wrapping name-value groups in `div` elements')}} - -## Notes - -Do not use this element (nor {{HTMLElement("ul")}} elements) to merely create indentation on a page. Although it works, this is a bad practice and obscures the meaning of description lists. - -To change the indentation of a description term, use the [CSS](/en-US/docs/Web/CSS) {{cssxref("margin")}} property. - -## Technical summary - -<table class="properties"> - <tbody> - <tr> - <th scope="row"> - <a href="/en-US/docs/Web/HTML/Content_categories" - >Content categories</a - > - </th> - <td> - <a href="/en-US/docs/Web/HTML/Content_categories#flow_content" - >Flow content</a - >, and if the <code>&#x3C;dl></code> element's children include one - name-value group, palpable content. - </td> - </tr> - <tr> - <th scope="row">Permitted content</th> - <td> - <p> - Either: Zero or more groups each consisting of one or more - {{HTMLElement("dt")}} elements followed by one or more - {{HTMLElement("dd")}} elements, optionally intermixed with - {{HTMLElement("script")}} and - {{HTMLElement("template")}} elements.<br />Or: (in - {{Glossary("WHATWG")}} HTML, {{Glossary("W3C")}} HTML 5.2 - and later) One or more {{HTMLElement("div")}} elements, - optionally intermixed with {{HTMLElement("script")}} and - {{HTMLElement("template")}} elements. - </p> - </td> - </tr> - <tr> - <th scope="row">Tag omission</th> - <td>None, both the starting and ending tag are mandatory.</td> - </tr> - <tr> - <th scope="row">Permitted parents</th> - <td> - Any element that accepts - <a href="/en-US/docs/Web/HTML/Content_categories#flow_content" - >flow content</a - >. - </td> - </tr> - <tr> - <th scope="row">Implicit ARIA role</th> - <td> - <a href="https://www.w3.org/TR/html-aria/#dfn-no-corresponding-role" - >No corresponding role</a - > - </td> - </tr> - <tr> - <th scope="row">Permitted ARIA roles</th> - <td> - <a href="/en-US/docs/Web/Accessibility/ARIA/Roles/group_role"><code>group</code></a>, - <code - ><a href="/en-US/docs/Web/Accessibility/ARIA/Roles/list_role" - >list</a - ></code - >, <a href="/en-US/docs/Web/Accessibility/ARIA/Roles/none_role"><code>none</code></a>, <a href="/en-US/docs/Web/Accessibility/ARIA/Roles/presentation_role"><code>presentation</code></a> - </td> - </tr> - <tr> - <th scope="row">DOM interface</th> - <td>{{domxref("HTMLDListElement")}}</td> - </tr> - </tbody> -</table> - -## Specifications - -{{Specifications}} - -## Browser compatibility - -{{Compat}} - -## See also - -- {{HTMLElement("dt")}} -- {{HTMLElement("dd")}} diff --git a/files/en-us/web/html/element/dt/index.md b/files/en-us/web/html/element/dt/index.md deleted file mode 100644 index 087350992781639..000000000000000 --- a/files/en-us/web/html/element/dt/index.md +++ /dev/null @@ -1,137 +0,0 @@ ---- -title: "<dt>: The Description Term element" -slug: Web/HTML/Element/dt -page-type: html-element -browser-compat: html.elements.dt ---- - -{{HTMLSidebar}} - -The **`<dt>`** [HTML](/en-US/docs/Web/HTML) element specifies a term in a description or definition list, and as such must be used inside a {{HTMLElement("dl")}} element. It is usually followed by a {{HTMLElement("dd")}} element; however, multiple `<dt>` elements in a row indicate several terms that are all defined by the immediate next {{HTMLElement("dd")}} element. - -The subsequent {{HTMLElement("dd")}} (**Description Details**) element provides the definition or other related text associated with the term specified using `<dt>`. - -{{InteractiveExample("HTML Demo: &lt;dt&gt;", "tabbed-standard")}} - -```html interactive-example -<p>Please use the following paint colors for the new house:</p> - -<dl> - <dt>Denim (semigloss finish)</dt> - <dd>Ceiling</dd> - - <dt>Denim (eggshell finish)</dt> - <dt>Evening Sky (eggshell finish)</dt> - <dd>Layered on the walls</dd> -</dl> -``` - -```css interactive-example -p, -dl { - font: - 1rem "Fira Sans", - sans-serif; -} - -dl > dt { - font-weight: normal; - font-style: oblique; -} - -dd { - margin-bottom: 1rem; -} -``` - -## Attributes - -This element only includes the [global attributes](/en-US/docs/Web/HTML/Global_attributes). - -## Examples - -For examples, see the [examples provided for the `<dl>` element](/en-US/docs/Web/HTML/Element/dl#examples). - -## Technical summary - -<table class="properties"> - <tbody> - <tr> - <th scope="row"> - <a href="/en-US/docs/Web/HTML/Content_categories" - >Content categories</a - > - </th> - <td>None.</td> - </tr> - <tr> - <th scope="row">Permitted content</th> - <td> - <a href="/en-US/docs/Web/HTML/Content_categories#flow_content" - >Flow content</a - >, but with no {{HTMLElement("header")}}, - {{HTMLElement("footer")}}, sectioning content or heading content - descendants. - </td> - </tr> - <tr> - <th scope="row">Tag omission</th> - <td> - The start tag is required. The end tag may be omitted if this element is - immediately followed by another <code>&#x3C;dt></code> element or a - {{HTMLElement("dd")}} element, or if there is no more content in - the parent element. - </td> - </tr> - <tr> - <th scope="row">Permitted parents</th> - <td> - A {{HTMLElement("dl")}} or (in {{Glossary("WHATWG")}} HTML, - {{Glossary("W3C")}} HTML 5.2 and later) a - {{HTMLElement("div")}} that is a child of a - {{HTMLElement("dl")}}.<br />This element can be used before a - {{HTMLElement("dd")}} or another <code>&lt;dt&gt;</code> - element. - </td> - </tr> - <tr> - <th scope="row">Implicit ARIA role</th> - <td> - <a href="https://www.w3.org/TR/html-aria/#dfn-no-corresponding-role" - >No corresponding role</a - > - </td> - </tr> - <tr> - <th scope="row">Permitted ARIA roles</th> - <td> - <code - ><a href="/en-US/docs/Web/Accessibility/ARIA/Roles/listitem_role" - >listitem</a - ></code - > - </td> - </tr> - <tr> - <th scope="row">DOM interface</th> - <td> - {{domxref("HTMLElement")}} Up to Gecko 1.9.2 (Firefox 4) - inclusive, Firefox implements the - {{domxref("HTMLSpanElement")}} interface for this element. - </td> - </tr> - </tbody> -</table> - -## Specifications - -{{Specifications}} - -## Browser compatibility - -{{Compat}} - -## See also - -- {{HTMLElement("dl")}} -- {{HTMLElement("dd")}} diff --git a/files/en-us/web/html/element/em/index.md b/files/en-us/web/html/element/em/index.md deleted file mode 100644 index 25557d4b32a599c..000000000000000 --- a/files/en-us/web/html/element/em/index.md +++ /dev/null @@ -1,157 +0,0 @@ ---- -title: "<em>: The Emphasis element" -slug: Web/HTML/Element/em -page-type: html-element -browser-compat: html.elements.em ---- - -{{HTMLSidebar}} - -The **`<em>`** [HTML](/en-US/docs/Web/HTML) element marks text that has stress emphasis. The `<em>` element can be nested, with each level of nesting indicating a greater degree of emphasis. - -{{InteractiveExample("HTML Demo: &lt;em&gt;", "tabbed-shorter")}} - -```html interactive-example -<p>Get out of bed <em>now</em>!</p> - -<p>We <em>had</em> to do something about it.</p> - -<p>This is <em>not</em> a drill!</p> -``` - -```css interactive-example -/* stylelint-disable-next-line block-no-empty */ -em { -} -``` - -## Attributes - -This element only includes the [global attributes](/en-US/docs/Web/HTML/Global_attributes). - -## Usage notes - -The `<em>` element is for words that have a stressed emphasis compared to surrounding text, which is often limited to a word or words of a sentence and affects the meaning of the sentence itself. - -Typically this element is displayed in italic type. However, it should not be used to apply italic styling; use the CSS {{cssxref("font-style")}} property for that purpose. Use the {{HTMLElement("cite")}} element to mark the title of a work (book, play, song, etc.). Use the {{HTMLElement("i")}} element to mark text that is in an alternate tone or mood, which covers many common situations for italics such as scientific names or words in other languages. Use the {{HTMLElement("strong")}} element to mark text that has greater importance than surrounding text. - -### \<i> vs. \<em> - -Some developers may be confused by how multiple elements seemingly produce similar visual results. `<em>` and `<i>` are a common example, since they both italicize text. What's the difference? Which should you use? - -By default, the visual result is the same. However, the semantic meaning is different. The `<em>` element represents stress emphasis of its contents, while the `<i>` element represents text that is set off from the normal prose, such as a foreign word, fictional character thoughts, or when the text refers to the definition of a word instead of representing its semantic meaning. (The title of a work, such as the name of a book or movie, should use `<cite>`.) - -This means the right one to use depends on the situation. Neither is for purely decorative purposes, that's what CSS styling is for. - -Examples for `<em>` could be: - -```html live-sample___em-example -<p>Just <em>do</em> it already!</p> -<p>We <em>had</em> to do something about it.</p> -``` - -{{EmbedLiveSample('em-example', "", 85)}} - -A person or software reading the text would pronounce the words in italics with an emphasis, using verbal stress. - -Examples for `<i>` could be: - -```html live-sample___i-example -<p>The word <i>the</i> is an article.</p> -<p>The <i>Queen Mary</i> sailed last night.</p> -``` - -{{EmbedLiveSample('i-example', "", 85)}} - -Here, there is no added emphasis or importance on the word "Queen Mary". It is merely indicated that the object in question is not a queen named Mary but a ship named "Queen Mary". - -## Examples - -In this example, the `<em>` element is used to highlight an implicit or explicit contrast between two ingredient lists: - -```html -<p> - Ice cream is made with milk, sweetener, and cream. Frozen custard, on the - other hand, is made of milk, cream, sweetener, and <em>egg yolks</em>. -</p> -``` - -### Result - -{{EmbedLiveSample("Example")}} - -## Technical summary - -<table class="properties"> - <tbody> - <tr> - <th scope="row"> - <a href="/en-US/docs/Web/HTML/Content_categories" - >Content categories</a - > - </th> - <td> - <a href="/en-US/docs/Web/HTML/Content_categories#flow_content" - >Flow content</a - >, - <a href="/en-US/docs/Web/HTML/Content_categories#phrasing_content" - >phrasing content</a - >, palpable content. - </td> - </tr> - <tr> - <th scope="row">Permitted content</th> - <td> - <a href="/en-US/docs/Web/HTML/Content_categories#phrasing_content" - >Phrasing content</a - >. - </td> - </tr> - <tr> - <th scope="row">Tag omission</th> - <td>None, both the starting and ending tag are mandatory.</td> - </tr> - <tr> - <th scope="row">Permitted parents</th> - <td> - Any element that accepts - <a href="/en-US/docs/Web/HTML/Content_categories#phrasing_content" - >phrasing content</a - >. - </td> - </tr> - <tr> - <th scope="row">Implicit ARIA role</th> - <td> - <code - ><a href="/en-US/docs/Web/Accessibility/ARIA/Roles/structural_roles#structural_roles_with_html_equivalents">emphasis</a - ></code - > - </td> - </tr> - <tr> - <th scope="row">Permitted ARIA roles</th> - <td>Any</td> - </tr> - <tr> - <th scope="row">DOM interface</th> - <td> - {{domxref("HTMLElement")}} Up to Gecko 1.9.2 (Firefox 4) - inclusive, Firefox implements the - {{domxref("HTMLSpanElement")}} interface for this element. - </td> - </tr> - </tbody> -</table> - -## Specifications - -{{Specifications}} - -## Browser compatibility - -{{Compat}} - -## See also - -- {{HTMLElement("i")}} diff --git a/files/en-us/web/html/element/embed/index.md b/files/en-us/web/html/element/embed/index.md deleted file mode 100644 index 3270cf47dd350d3..000000000000000 --- a/files/en-us/web/html/element/embed/index.md +++ /dev/null @@ -1,130 +0,0 @@ ---- -title: "<embed>: The Embed External Content element" -slug: Web/HTML/Element/embed -page-type: html-element -browser-compat: html.elements.embed ---- - -{{HTMLSidebar}} - -The **`<embed>`** [HTML](/en-US/docs/Web/HTML) element embeds external content at the specified point in the document. This content is provided by an external application or other source of interactive content such as a browser plug-in. - -{{InteractiveExample("HTML Demo: &lt;embed&gt;", "tabbed-standard")}} - -```html interactive-example -<embed - type="video/mp4" - src="/shared-assets/videos/flower.mp4" - width="250" - height="200" /> -``` - -> [!NOTE] -> This topic documents only the element that is defined as part of the [HTML Living Standard](https://html.spec.whatwg.org/multipage/iframe-embed-object.html#the-embed-element). It does not address earlier, non-standardized implementation of the element. - -Keep in mind that most modern browsers have deprecated and removed support for browser plug-ins, so relying upon `<embed>` is generally not wise if you want your site to be operable on the average user's browser. - -## Attributes - -This element's attributes include the [global attributes](/en-US/docs/Web/HTML/Global_attributes). - -- `height` - - : The displayed height of the resource, in [CSS pixels](https://drafts.csswg.org/css-values/#px). This must be an absolute value; percentages are _not_ allowed. -- `src` - - : The URL of the resource being embedded. -- `type` - - : The {{glossary("MIME type")}} to use to select the plug-in to instantiate. -- `width` - - : The displayed width of the resource, in [CSS pixels](https://drafts.csswg.org/css-values/#px). This must be an absolute value; percentages are _not_ allowed. - -## Usage notes - -You can use the {{cssxref("object-position")}} property to adjust the positioning of the embedded object within the element's frame. - -> [!NOTE] -> The {{cssxref("object-fit")}} property has no effect on `<embed>` elements. - -## Accessibility - -Use the [`title` attribute](/en-US/docs/Web/HTML/Global_attributes/title) on an `embed` element to label its content so that people navigating with assistive technology such as a screen reader can understand what it contains. The title's value should concisely describe the embedded content. Without a title, they may not be able to determine what its embedded content is. This context shift can be confusing and time-consuming, especially if the `embed` element contains interactive content like video or audio. - -## Examples - -```html -<embed - type="video/quicktime" - src="movie.mov" - width="640" - height="480" - title="Title of my video" /> -``` - -## Technical summary - -<table class="properties"> - <tbody> - <tr> - <th scope="row"> - <a href="/en-US/docs/Web/HTML/Content_categories" - >Content categories</a - > - </th> - <td> - <a href="/en-US/docs/Web/HTML/Content_categories#flow_content" - >Flow content</a - >, - <a href="/en-US/docs/Web/HTML/Content_categories#phrasing_content" - >phrasing content</a - >, embedded content, interactive content, - <a href="/en-US/docs/Web/HTML/Content_categories#palpable_content" - >palpable content</a - >. - </td> - </tr> - <tr> - <th scope="row">Permitted content</th> - <td>None; it is a {{Glossary("void element")}}.</td> - </tr> - <tr> - <th scope="row">Tag omission</th> - <td>Must have a start tag and must not have an end tag.</td> - </tr> - <tr> - <th scope="row">Permitted parents</th> - <td>Any element that accepts embedded content.</td> - </tr> - <tr> - <th scope="row">Implicit ARIA role</th> - <td> - <a href="https://www.w3.org/TR/html-aria/#dfn-no-corresponding-role" - >No corresponding role</a - > - </td> - </tr> - <tr> - <th scope="row">Permitted ARIA roles</th> - <td> - <a href="/en-US/docs/Web/Accessibility/ARIA/Roles/application_role"><code>application</code></a>, <a href="/en-US/docs/Web/Accessibility/ARIA/Roles/document_role"><code>document</code></a>, - <a href="/en-US/docs/Web/Accessibility/ARIA/Roles/img_role"><code>img</code></a>, <a href="/en-US/docs/Web/Accessibility/ARIA/Roles/none_role"><code>none</code></a>, - <a href="/en-US/docs/Web/Accessibility/ARIA/Roles/presentation_role"><code>presentation</code></a> - </td> - </tr> - <tr> - <th scope="row">DOM interface</th> - <td>{{domxref("HTMLEmbedElement")}}</td> - </tr> - </tbody> -</table> - -## Specifications - -{{Specifications}} - -## Browser compatibility - -{{Compat}} - -## See also - -- Other elements that are used for embedding content of various types include {{HTMLElement("audio")}}, {{HTMLElement("canvas")}}, {{HTMLElement("iframe")}}, {{HTMLElement("img")}}, {{MathMLElement("math")}}, {{HTMLElement("object")}}, {{SVGElement("svg")}}, and {{HTMLElement("video")}}. -- Positioning and sizing the embedded content within its frame: {{cssxref("object-position")}} and {{cssxref("object-fit")}} diff --git a/files/en-us/web/html/element/fencedframe/index.md b/files/en-us/web/html/element/fencedframe/index.md deleted file mode 100644 index 85d78ac6563632a..000000000000000 --- a/files/en-us/web/html/element/fencedframe/index.md +++ /dev/null @@ -1,171 +0,0 @@ ---- -title: "<fencedframe>: The Fenced Frame element" -slug: Web/HTML/Element/fencedframe -page-type: html-element -status: - - experimental -browser-compat: html.elements.fencedframe ---- - -{{HTMLSidebar}}{{SeeCompatTable}} - -The **`<fencedframe>`** [HTML](/en-US/docs/Web/HTML) element represents a nested {{Glossary("browsing context")}}, embedding another HTML page into the current one. `<fencedframe>`s are very similar to {{htmlelement("iframe")}} elements in form and function, except that: - -- Communication is restricted between the `<fencedframe>` content and its embedding site. -- A `<fencedframe>` can access cross-site data, but only in a very specific set of controlled circumstances that preserve user privacy. -- A `<fencedframe>` cannot be manipulated or have its data accessed via regular scripting (for example reading or setting the source URL). `<fencedframe>` content can only be embedded via [specific APIs](/en-US/docs/Web/API/Fenced_frame_API#use_cases). -- A `<fencedframe>` cannot access the embedding context's DOM, nor can the embedding context access the `<fencedframe>`'s DOM. - -The `<fencedframe>` element is a type of `<iframe>` with more native privacy features built in. It addresses shortcomings of `<iframe>`s such as reliance on third-party cookies and other privacy risks. See [Fenced frame API](/en-US/docs/Web/API/Fenced_frame_API) for more details. - -## Attributes - -This element includes the [global attributes](/en-US/docs/Web/HTML/Global_attributes). - -- `allow` {{experimental_inline}} - - - : Specifies a [Permissions Policy](/en-US/docs/Web/HTTP/Permissions_Policy) for the `<fencedframe>`, which defines what features are available to the `<fencedframe>` based on the origin of the request. See [Permissions policies available to fenced frames](#permissions_policies_available_to_fenced_frames) for more details of which features can be controlled via a policy set on a fenced frame. - -- `height` {{experimental_inline}} - - - : A unitless integer representing the height of the fenced frame in CSS pixels. The default is `150`. - -- `width` {{experimental_inline}} - - : A unitless integer representing the width of the fenced frame in CSS pixels. The default is `300`. - -## Permissions policies available to fenced frames - -Permissions delegated from the top-level context to a fenced frame for allowing and denying features could be used as a communication channel, so constitute a privacy threat. As a result, standard web features that can have their availability controlled via [Permissions Policy](/en-US/docs/Web/HTTP/Headers/Permissions-Policy) (for example, [`camera`](/en-US/docs/Web/HTTP/Headers/Permissions-Policy/camera) or [`geolocation`](/en-US/docs/Web/HTTP/Headers/Permissions-Policy/geolocation)) are **not available** within fenced frames. - -The only features that can be enabled by a policy inside fenced frames are the specific features designed to be used inside fenced frames: - -- [Protected Audience API](https://developers.google.com/privacy-sandbox/private-advertising/protected-audience) - - `attribution-reporting` - - `private-aggregation` - - `shared-storage` - - `shared-storage-select-url` -- [Shared Storage API](/en-US/docs/Web/API/Shared_Storage_API) - - `attribution-reporting` - - `private-aggregation` - - `shared-storage` - - `shared-storage-select-url` - -Currently these are always enabled inside fenced frames. In the future, which ones are enabled will be controllable using the `<fencedframe>` `allow` attribute. Blocking privacy sandbox features in this manner will also block the fenced frame from loading — there will be no communication channel at all. - -## Focusing across fenced frame boundaries - -The ability of the document's active focus to be moved across fenced frame boundaries (i.e. from an element outside the fenced frame to one inside, or vice versa) is limited. User-initiated actions such as a click or a tab can do so, as there is no fingerprinting risk there. - -However, trying to traverse the boundary via an API call such as {{domxref("HTMLElement.focus()")}} is prohibited — a malicious script could use a series of such calls to leak inferred information across the boundary. - -## Positioning and scaling - -Being a [replaced element](/en-US/docs/Web/CSS/Replaced_element), the `<fencedframe>` allows the position of the embedded document within its box to be adjusted using the {{cssxref("object-position")}} property. - -> [!NOTE] -> The {{cssxref("object-fit")}} property has no effect on `<fencedframe>` elements. - -The size of the embedded content may be set by internal `contentWidth` and `contentHeight` properties of the `<fencedframe>`'s {{domxref("HTMLFencedFrameElement.config", "config")}} object. In such cases, changing the `width` or `height` of the `<fencedframe>` will change the size of the embedded container on the page, but the document inside the container will be visually scaled to fit. The reported width and height of the embedded document (i.e. {{domxref("Window.innerWidth")}} and {{domxref("Window.innerHeight")}}) will be unchanged. - -## Accessibility - -People navigating with assistive technology, such as a screen reader, can use the [`title` attribute](/en-US/docs/Web/HTML/Global_attributes/title) on a `<fencedframe>` to label its content. The title's value should concisely describe the embedded content: - -```html -<fencedframe - title="Advertisement for new Log. From Blammo!" - width="640" - height="320"></fencedframe> -``` - -Without this title, they have to navigate into the `<fencedframe>` to determine what its embedded content is. This context shift can be confusing and time-consuming, especially for pages with multiple `<fencedframe>`s and/or if embeds contain interactive content like video or audio. - -## Examples - -To set what content will be shown in a `<fencedframe>`, a utilizing API (such as [Protected Audience](https://developers.google.com/privacy-sandbox/private-advertising/protected-audience) or [Shared Storage](https://developers.google.com/privacy-sandbox/private-advertising/shared-storage)) generates a {{domxref("FencedFrameConfig")}} object, which is then set as the value of the `<fencedframe>`'s `config` property. - -The following example gets a `FencedFrameConfig` from a Protected Audience API's ad auction, which is then used to display the winning ad in a `<fencedframe>`: - -```html -<fencedframe width="640" height="320"></fencedframe> -``` - -```js -const frameConfig = await navigator.runAdAuction({ - // ...auction configuration - resolveToConfig: true, -}); - -const frame = document.querySelector("fencedframe"); -frame.config = frameConfig; -``` - -> **Note:** `resolveToConfig: true` must be passed in to the `runAdAuction()` call to obtain a `FencedFrameConfig` object. If it is not set, the resulting {{jsxref("Promise")}} will resolve to a URN that can only be used in an {{htmlelement("iframe")}}. - -## Technical summary - -<table class="properties"> - <tbody> - <tr> - <th scope="row"> - <a href="/en-US/docs/Web/HTML/Content_categories" - >Content categories</a - > - </th> - <td> - <a href="/en-US/docs/Web/HTML/Content_categories#flow_content" - >Flow content</a - >, - <a href="/en-US/docs/Web/HTML/Content_categories#phrasing_content" - >phrasing content</a - >, embedded content, interactive content, palpable content. - </td> - </tr> - <tr> - <th scope="row">Permitted content</th> - <td>None.</td> - </tr> - <tr> - <th scope="row">Tag omission</th> - <td>None, both the starting and ending tag are mandatory.</td> - </tr> - <tr> - <th scope="row">Permitted parents</th> - <td>Any element that accepts embedded content.</td> - </tr> - <tr> - <th scope="row">Implicit ARIA role</th> - <td> - <a href="https://www.w3.org/TR/html-aria/#dfn-no-corresponding-role" - >No corresponding role</a - > - </td> - </tr> - <tr> - <th scope="row">Permitted ARIA roles</th> - <td> - <a href="/en-US/docs/Web/Accessibility/ARIA/Roles/application_role"><code>application</code></a>, <a href="/en-US/docs/Web/Accessibility/ARIA/Roles/document_role"><code>document</code></a>, - <a href="/en-US/docs/Web/Accessibility/ARIA/Roles/img_role"><code>img</code></a>, <a href="/en-US/docs/Web/Accessibility/ARIA/Roles/none_role"><code>none</code></a>, - <a href="/en-US/docs/Web/Accessibility/ARIA/Roles/presentation_role"><code>presentation</code></a> - </td> - </tr> - <tr> - <th scope="row">DOM interface</th> - <td>{{domxref("HTMLFencedFrameElement")}}</td> - </tr> - </tbody> -</table> - -## Specifications - -{{Specifications}} - -## Browser compatibility - -{{Compat}} - -## See also - -- [Fenced Frame API](/en-US/docs/Web/API/Fenced_frame_API) -- [Fenced frames](https://developers.google.com/privacy-sandbox/private-advertising/fenced-frame) on developers.google.com -- [The Privacy Sandbox](https://developers.google.com/privacy-sandbox) on developers.google.com diff --git a/files/en-us/web/html/element/fieldset/index.md b/files/en-us/web/html/element/fieldset/index.md deleted file mode 100644 index f3397a720eeac40..000000000000000 --- a/files/en-us/web/html/element/fieldset/index.md +++ /dev/null @@ -1,194 +0,0 @@ ---- -title: "<fieldset>: The Field Set element" -slug: Web/HTML/Element/fieldset -page-type: html-element -browser-compat: html.elements.fieldset ---- - -{{HTMLSidebar}} - -The **`<fieldset>`** [HTML](/en-US/docs/Web/HTML) element is used to group several controls as well as labels ({{HTMLElement("label")}}) within a web form. - -{{InteractiveExample("HTML Demo: &lt;fieldset&gt;", "tabbed-standard")}} - -```html interactive-example -<form> - <fieldset> - <legend>Choose your favorite monster</legend> - - <input type="radio" id="kraken" name="monster" value="K" /> - <label for="kraken">Kraken</label><br /> - - <input type="radio" id="sasquatch" name="monster" value="S" /> - <label for="sasquatch">Sasquatch</label><br /> - - <input type="radio" id="mothman" name="monster" value="M" /> - <label for="mothman">Mothman</label> - </fieldset> -</form> -``` - -```css interactive-example -legend { - background-color: #000; - color: #fff; - padding: 3px 6px; -} - -input { - margin: 0.4rem; -} -``` - -As the example above shows, the `<fieldset>` element provides a grouping for a part of an HTML form, with a nested {{htmlelement("legend")}} element providing a caption for the `<fieldset>`. It takes few attributes, the most notable of which are `form`, which can contain the `id` of a {{htmlelement("form")}} on the same page, allowing you to make the `<fieldset>` part of that `<form>` even if it is not nested inside it, and `disabled`, which allows you to disable the `<fieldset>` and all its contents in one go. - -## Attributes - -This element includes the [global attributes](/en-US/docs/Web/HTML/Global_attributes). - -- [`disabled`](/en-US/docs/Web/HTML/Attributes/disabled) - - : If this Boolean attribute is set, all form controls that are descendants of the `<fieldset>`, are disabled, meaning they are not editable and won't be submitted along with the {{htmlelement("form")}}. They won't receive any browsing events, like mouse clicks or focus-related events. By default browsers display such controls grayed out. Note that form elements inside the {{HTMLElement("legend")}} element won't be disabled. -- `form` - - : This attribute takes the value of the [`id`](/en-US/docs/Web/HTML/Global_attributes/id) attribute of a {{HTMLElement("form")}} element you want the `<fieldset>` to be part of, even if it is not inside the form. Please note that usage of this is confusing — if you want the {{HTMLElement("input")}} elements inside the `<fieldset>` to be associated with the form, you need to use the `form` attribute directly on those elements. You can check which elements are associated with a form via JavaScript, using {{domxref("HTMLFormElement.elements")}}. -- `name` - - - : The name associated with the group. - - > [!NOTE] - > The caption for the fieldset is given by the first {{HTMLElement("legend")}} element nested inside it. - -## Styling with CSS - -There are several special styling considerations for `<fieldset>`. - -Its {{cssxref("display")}} value is `block` by default, and it establishes a [block formatting context](/en-US/docs/Web/CSS/CSS_display/Block_formatting_context). If the `<fieldset>` is styled with an inline-level `display` value, it will behave as `inline-block`, otherwise it will behave as `block`. By default there is a `2px` `groove` border surrounding the contents, and a small amount of default padding. The element has {{cssxref("min-inline-size", "min-inline-size: min-content")}} by default. - -If a {{htmlelement("legend")}} is present, it is placed over the `block-start` border. The `<legend>` shrink-wraps, and also establishes a formatting context. The `display` value is blockified. (For example, `display: inline` behaves as `block`.) - -There will be an anonymous box holding the contents of the `<fieldset>`, which inherits certain properties from the `<fieldset>`. If the `<fieldset>` is styled with `display: grid` or `display: inline-grid`, then the anonymous box will be a grid formatting context. If the `<fieldset>` is styled with `display: flex` or `display: inline-flex`, then the anonymous box will be a flex formatting context. Otherwise, it establishes a block formatting context. - -You can feel free to style the `<fieldset>` and `<legend>` in any way you want to suit your page design. - -## Examples - -### Basic fieldset - -This example includes a `<fieldset>` with a `<legend>`, with a single control inside it. - -```html -<form action="#"> - <fieldset> - <legend>Do you agree?</legend> - <input type="checkbox" id="chbx" name="agree" value="Yes!" /> - <label for="chbx">I agree</label> - </fieldset> -</form> -``` - -#### Result - -{{ EmbedLiveSample('Basic_fieldset', '100%', '80') }} - -### Disabled fieldset - -This example shows a disabled `<fieldset>` with two controls inside it. Note how both the controls are disabled due to being inside a disabled `<fieldset>`. - -```html -<form action="#"> - <fieldset disabled> - <legend>Disabled login fieldset</legend> - <div> - <label for="name">Name: </label> - <input type="text" id="name" value="Chris" /> - </div> - <div> - <label for="pwd">Archetype: </label> - <input type="password" id="pwd" value="Wookie" /> - </div> - </fieldset> -</form> -``` - -#### Result - -{{ EmbedLiveSample('Disabled_fieldset', '100%', '110') }} - -## Technical summary - -<table class="properties"> - <tbody> - <tr> - <th scope="row"> - <a href="/en-US/docs/Web/HTML/Content_categories" - >Content categories</a - > - </th> - <td> - <a href="/en-US/docs/Web/HTML/Content_categories#flow_content" - >Flow content</a - >, - <a href="/en-US/docs/Web/HTML/Element/Heading_Elements#sectioning_root" - >sectioning root</a - >, - <a href="/en-US/docs/Web/HTML/Content_categories#form_listed" - >listed</a - >, - <a - href="/en-US/docs/Web/HTML/Content_categories#form-associated_content" - >form-associated</a - > - element, palpable content. - </td> - </tr> - <tr> - <th scope="row">Permitted content</th> - <td> - An optional {{HTMLElement("legend")}} element, followed by flow - content. - </td> - </tr> - <tr> - <th scope="row">Tag omission</th> - <td>None, both the starting and ending tag are mandatory.</td> - </tr> - <tr> - <th scope="row">Permitted parents</th> - <td> - Any element that accepts - <a href="/en-US/docs/Web/HTML/Content_categories#flow_content" - >flow content</a - >. - </td> - </tr> - <tr> - <th scope="row">Implicit ARIA role</th> - <td><a href="/en-US/docs/Web/Accessibility/ARIA/Roles/group_role"><code>group</code></a></td> - </tr> - <tr> - <th scope="row">Permitted ARIA roles</th> - <td> - <a href="/en-US/docs/Web/Accessibility/ARIA/Roles/radiogroup_role"><code>radiogroup</code></a>, - <a href="/en-US/docs/Web/Accessibility/ARIA/Roles/presentation_role"><code>presentation</code></a>, <a href="/en-US/docs/Web/Accessibility/ARIA/Roles/none_role"><code>none</code></a> - </td> - </tr> - <tr> - <th scope="row">DOM interface</th> - <td>{{domxref("HTMLFieldSetElement")}}</td> - </tr> - </tbody> -</table> - -## Specifications - -{{Specifications}} - -## Browser compatibility - -{{Compat}} - -## See also - -- The {{HTMLElement("legend")}} element -- The {{HTMLElement("input")}} element -- The {{HTMLElement("label")}} element -- The {{HTMLElement("form")}} element diff --git a/files/en-us/web/html/element/figcaption/index.md b/files/en-us/web/html/element/figcaption/index.md deleted file mode 100644 index 8385bbc30d7ecf8..000000000000000 --- a/files/en-us/web/html/element/figcaption/index.md +++ /dev/null @@ -1,118 +0,0 @@ ---- -title: "<figcaption>: The Figure Caption element" -slug: Web/HTML/Element/figcaption -page-type: html-element -browser-compat: html.elements.figcaption ---- - -{{HTMLSidebar}} - -The **`<figcaption>`** [HTML](/en-US/docs/Web/HTML) element represents a caption or legend describing the rest of the contents of its parent {{HTMLElement("figure")}} element, providing the `<figure>` an {{glossary("accessible description")}}. - -{{InteractiveExample("HTML Demo: &lt;figcaption&gt;", "tabbed-shorter")}} - -```html interactive-example -<figure> - <img - src="/shared-assets/images/examples/elephant.jpg" - alt="Elephant at sunset" /> - <figcaption>An elephant at sunset</figcaption> -</figure> -``` - -```css interactive-example -figure { - border: thin #c0c0c0 solid; - display: flex; - flex-flow: column; - padding: 5px; - max-width: 220px; - margin: auto; -} - -img { - max-width: 220px; - max-height: 150px; -} - -figcaption { - background-color: #222; - color: #fff; - font: italic smaller sans-serif; - padding: 3px; - text-align: center; -} -``` - -## Attributes - -This element only includes the [global attributes](/en-US/docs/Web/HTML/Global_attributes). - -## Examples - -Please see the {{HTMLElement("figure")}} page for examples on `<figcaption>`. - -## Technical summary - -<table class="properties"> - <tbody> - <tr> - <th scope="row"> - <a href="/en-US/docs/Web/HTML/Content_categories" - >Content categories</a - > - </th> - <td>None.</td> - </tr> - <tr> - <th scope="row">Permitted content</th> - <td> - <a href="/en-US/docs/Web/HTML/Content_categories#flow_content" - >Flow content</a - >. - </td> - </tr> - <tr> - <th scope="row">Tag omission</th> - <td>None, both the starting and ending tag are mandatory.</td> - </tr> - <tr> - <th scope="row">Permitted parents</th> - <td> - A {{HTMLElement("figure")}} element; the - <code>&#x3C;figcaption></code> element must be its first or last child. - </td> - </tr> - <tr> - <th scope="row">Implicit ARIA role</th> - <td> - <a href="https://www.w3.org/TR/html-aria/#dfn-no-corresponding-role" - >No corresponding role</a - > - </td> - </tr> - <tr> - <th scope="row">Permitted ARIA roles</th> - <td> - <a href="/en-US/docs/Web/Accessibility/ARIA/Roles/group_role"><code>group</code></a>, <a href="/en-US/docs/Web/Accessibility/ARIA/Roles/none_role"><code>none</code></a>, - <a href="/en-US/docs/Web/Accessibility/ARIA/Roles/presentation_role"><code>presentation</code></a> - </td> - </tr> - <tr> - <th scope="row">DOM interface</th> - <td>{{domxref("HTMLElement")}}</td> - </tr> - </tbody> -</table> - -## Specifications - -{{Specifications}} - -## Browser compatibility - -{{Compat}} - -## See also - -- The {{HTMLElement("figure")}} element. diff --git a/files/en-us/web/html/element/figure/index.md b/files/en-us/web/html/element/figure/index.md deleted file mode 100644 index 2e41a90e8e70f11..000000000000000 --- a/files/en-us/web/html/element/figure/index.md +++ /dev/null @@ -1,213 +0,0 @@ ---- -title: "<figure>: The Figure with Optional Caption element" -slug: Web/HTML/Element/figure -page-type: html-element -browser-compat: html.elements.figure ---- - -{{HTMLSidebar}} - -The **`<figure>`** [HTML](/en-US/docs/Web/HTML) element represents self-contained content, potentially with an optional caption, which is specified using the {{HTMLElement("figcaption")}} element. The figure, its caption, and its contents are referenced as a single unit. - -{{InteractiveExample("HTML Demo: &lt;figure&gt;", "tabbed-shorter")}} - -```html interactive-example -<figure> - <img - src="/shared-assets/images/examples/elephant.jpg" - alt="Elephant at sunset" /> - <figcaption>An elephant at sunset</figcaption> -</figure> -``` - -```css interactive-example -figure { - border: thin #c0c0c0 solid; - display: flex; - flex-flow: column; - padding: 5px; - max-width: 220px; - margin: auto; -} - -img { - max-width: 220px; - max-height: 150px; -} - -figcaption { - background-color: #222; - color: #fff; - font: italic smaller sans-serif; - padding: 3px; - text-align: center; -} -``` - -## Attributes - -This element only includes the [global attributes](/en-US/docs/Web/HTML/Global_attributes). - -## Usage notes - -- Usually a `<figure>` is an image, illustration, diagram, code snippet, etc., that is referenced in the main flow of a document, but that can be moved to another part of the document or to an appendix without affecting the main flow. -- A caption can be associated with the `<figure>` element by inserting a {{HTMLElement("figcaption")}} inside it (as the first or the last child). The first `<figcaption>` element found in the figure is presented as the figure's caption. -- The `<figcaption>` provides the {{glossary("accessible name")}} for the parent `<figure>`. - -## Examples - -### Images - -```html -<!-- Just an image --> -<figure> - <img src="favicon-192x192.png" alt="The beautiful MDN logo." /> -</figure> - -<!-- Image with a caption --> -<figure> - <img src="favicon-192x192.png" alt="The beautiful MDN logo." /> - <figcaption>MDN Logo</figcaption> -</figure> -``` - -#### Result - -{{EmbedLiveSample("Images", "100%", 375)}} - -### Code snippets - -```html -<figure> - <figcaption>Get browser details using <code>navigator</code>.</figcaption> - <pre> -function NavigatorExample() { - var txt; - txt = "Browser CodeName: " + navigator.appCodeName + "; "; - txt+= "Browser Name: " + navigator.appName + "; "; - txt+= "Browser Version: " + navigator.appVersion + "; "; - txt+= "Cookies Enabled: " + navigator.cookieEnabled + "; "; - txt+= "Platform: " + navigator.platform + "; "; - txt+= "User-agent header: " + navigator.userAgent + "; "; - console.log("NavigatorExample", txt); -} - </pre> -</figure> -``` - -#### Result - -{{EmbedLiveSample("Code_snippets", "100%", 250)}} - -### Quotations - -```html -<figure> - <figcaption><b>Edsger Dijkstra:</b></figcaption> - <blockquote> - If debugging is the process of removing software bugs, then programming must - be the process of putting them in. - </blockquote> -</figure> -``` - -#### Result - -{{EmbedLiveSample('Quotations')}} - -### Poems - -```html -<figure> - <p style="white-space:pre"> - Bid me discourse, I will enchant thine ear, Or like a fairy trip upon the - green, Or, like a nymph, with long dishevelled hair, Dance on the sands, and - yet no footing seen: Love is a spirit all compact of fire, Not gross to - sink, but light, and will aspire. - </p> - <figcaption><cite>Venus and Adonis</cite>, by William Shakespeare</figcaption> -</figure> -``` - -#### Result - -{{EmbedLiveSample("Poems", "100%", 250)}} - -## Technical summary - -<table class="properties"> - <tbody> - <tr> - <th scope="row"> - <a href="/en-US/docs/Web/HTML/Content_categories" - >Content categories</a - > - </th> - <td> - <a href="/en-US/docs/Web/HTML/Content_categories#flow_content" - >Flow content</a - >, - <a href="/en-US/docs/Web/HTML/Content_categories#palpable_content" - >palpable content</a - >. - </td> - </tr> - <tr> - <th scope="row">Permitted content</th> - <td> - A {{HTMLElement("figcaption")}} element, followed by - <a href="/en-US/docs/Web/HTML/Content_categories#flow_content" - >flow content</a - >; or flow content followed by a - {{HTMLElement("figcaption")}} element; or flow content. - </td> - </tr> - <tr> - <th scope="row">Tag omission</th> - <td>None, both the starting and ending tag are mandatory.</td> - </tr> - <tr> - <th scope="row">Permitted parents</th> - <td> - Any element that accepts - <a href="/en-US/docs/Web/HTML/Content_categories#flow_content" - >Flow content</a - >. - </td> - </tr> - <tr> - <th scope="row">Implicit ARIA role</th> - <td> - <a href="/en-US/docs/Web/Accessibility/ARIA/Roles/figure_role" - >figure</a - > - </td> - </tr> - <tr> - <th scope="row">Permitted ARIA roles</th> - <td> - With no - <a href="/en-US/docs/Web/HTML/Element/figcaption">figcaption </a - >descendant: - <a href="https://www.w3.org/TR/html-aria/#dfn-any-role">any</a>, - otherwise no permitted roles - </td> - </tr> - <tr> - <th scope="row">DOM interface</th> - <td>{{domxref("HTMLElement")}}</td> - </tr> - </tbody> -</table> - -## Specifications - -{{Specifications}} - -## Browser compatibility - -{{Compat}} - -## See also - -- The {{HTMLElement("figcaption")}} element. diff --git a/files/en-us/web/html/element/font/index.md b/files/en-us/web/html/element/font/index.md deleted file mode 100644 index 4ff1c37759ba4ad..000000000000000 --- a/files/en-us/web/html/element/font/index.md +++ /dev/null @@ -1,40 +0,0 @@ ---- -title: <font> -slug: Web/HTML/Element/font -page-type: html-element -status: - - deprecated -browser-compat: html.elements.font ---- - -{{HTMLSidebar}}{{Deprecated_Header}} - -The **`<font>`** [HTML](/en-US/docs/Web/HTML) element defines the font size, color and face for its content. - -> [!WARNING] -> Do not use this element. Use the CSS [Fonts](/en-US/docs/Web/CSS/CSS_fonts) properties to style text. - -## Attributes - -Like all other HTML elements, this element supports the [global attributes](/en-US/docs/Web/HTML/Global_attributes). - -- `color` {{Deprecated_Inline}} - - : This attribute sets the text color using either a named color or a color specified in the hexadecimal #RRGGBB format. -- `face` {{Deprecated_Inline}} - - : This attribute contains a comma-separated list of one or more font names. The document text in the default style is rendered in the first font face that the client's browser supports. If no font listed is installed on the local system, the browser typically defaults to the proportional or fixed-width font for that system. -- `size` {{Deprecated_Inline}} - - : This attribute specifies the font size as either a numeric or relative value. Numeric values range from `1` to `7` with `1` being the smallest and `3` the default. It can be defined using a relative value, like `+2` or `-3`, which sets it relative to `3`, the default value. - -## DOM interface - -This element implements the {{domxref("HTMLFontElement")}} interface. - -<!-- ## Technical summary --> - -## Specifications - -{{Specifications}} - -## Browser compatibility - -{{Compat}} diff --git a/files/en-us/web/html/element/footer/index.md b/files/en-us/web/html/element/footer/index.md deleted file mode 100644 index ce0535adf861f57..000000000000000 --- a/files/en-us/web/html/element/footer/index.md +++ /dev/null @@ -1,169 +0,0 @@ ---- -title: "<footer>: The Footer element" -slug: Web/HTML/Element/footer -page-type: html-element -browser-compat: html.elements.footer ---- - -{{HTMLSidebar}} - -The **`<footer>`** [HTML](/en-US/docs/Web/HTML) element represents a footer for its nearest ancestor [sectioning content](/en-US/docs/Web/HTML/Content_categories#sectioning_content) or [sectioning root](/en-US/docs/Web/HTML/Element/Heading_Elements#labeling_section_content) element. A `<footer>` typically contains information about the author of the section, copyright data or links to related documents. - -{{InteractiveExample("HTML Demo: &lt;footer&gt;", "tabbed-standard")}} - -```html interactive-example -<article> - <h1>How to be a wizard</h1> - <ol> - <li>Grow a long, majestic beard.</li> - <li>Wear a tall, pointed hat.</li> - <li>Have I mentioned the beard?</li> - </ol> - <footer> - <p>© 2018 Gandalf</p> - </footer> -</article> -``` - -```css interactive-example -article { - min-height: 100%; - display: grid; - grid-template-rows: auto 1fr auto; -} - -footer { - display: flex; - justify-content: center; - padding: 5px; - background-color: #45a1ff; - color: #fff; -} -``` - -## Attributes - -This element only includes the [global attributes](/en-US/docs/Web/HTML/Global_attributes). - -## Usage notes - -- Enclose information about the author in an {{HTMLElement("address")}} element that can be included into the `<footer>` element. -- When the nearest ancestor sectioning content or sectioning root element is the body element the footer applies to the whole page. -- The `<footer>` element is not sectioning content and therefore doesn't introduce a new section in the [outline](/en-US/docs/Web/HTML/Element/Heading_Elements). - -## Accessibility - -Prior to the release of Safari 13, the `contentinfo` [landmark role](/en-US/docs/Learn_web_development/Core/Accessibility/WAI-ARIA_basics#signpostslandmarks) was not properly exposed by [VoiceOver](https://help.apple.com/voiceover/info/guide/). If needing to support legacy Safari browsers, add `role="contentinfo"` to the `footer` element to ensure the landmark will be properly exposed. - -- Related: [WebKit Bugzilla: 146930 – AX: HTML native elements (header, footer, main, aside, nav) should work the same as ARIA landmarks, sometimes they don't](https://webkit.org/b/146930) - -## Examples - -```html -<body> - <h3>FIFA World Cup top goalscorers</h3> - <ol> - <li>Miroslav Klose, 16</li> - <li>Ronaldo Nazário, 15</li> - <li>Gerd Müller, 14</li> - </ol> - - <footer> - <small> - Copyright © 2023 Football History Archives. All Rights Reserved. - </small> - </footer> -</body> -``` - -```css -footer { - text-align: center; - padding: 5px; - background-color: #abbaba; - color: #000; -} -``` - -{{EmbedLiveSample('Examples')}} - -## Technical summary - -<table class="properties"> - <tbody> - <tr> - <th scope="row"> - <a href="/en-US/docs/Web/HTML/Content_categories">Content categories</a> - </th> - <td> - <a href="/en-US/docs/Web/HTML/Content_categories#flow_content">Flow content</a>, palpable content. - </td> - </tr> - <tr> - <th scope="row">Permitted content</th> - <td> - <a href="/en-US/docs/Web/HTML/Content_categories#flow_content">Flow content</a>, but with no <code>&#x3C;footer></code> or - {{HTMLElement("header")}} descendants. - </td> - </tr> - <tr> - <th scope="row">Tag omission</th> - <td>None, both the starting and ending tag are mandatory.</td> - </tr> - <tr> - <th scope="row">Permitted parents</th> - <td> - Any element that accepts - <a href="/en-US/docs/Web/HTML/Content_categories#flow_content">flow content</a>. Note that a <code>&#x3C;footer></code> element must not be a - descendant of an {{HTMLElement("address")}}, - {{HTMLElement("header")}} or another - <code>&#x3C;footer></code> element. - </td> - </tr> - <tr> - <th scope="row">Implicit ARIA role</th> - <td> - <a href="/en-US/docs/Web/Accessibility/ARIA/Roles/contentinfo_role">contentinfo</a>, or - <a href="/en-US/docs/Web/Accessibility/ARIA/Roles/generic_role">generic</a> - if a descendant of an - <a href="/en-US/docs/Web/HTML/Element/article">article</a>, - <a href="/en-US/docs/Web/HTML/Element/aside">aside</a>, - <a href="/en-US/docs/Web/HTML/Element/main">main</a>, - <a href="/en-US/docs/Web/HTML/Element/nav">nav</a> or - <a href="/en-US/docs/Web/HTML/Element/section">section</a> element, or - an element with - <code>role=<a href="/en-US/docs/Web/Accessibility/ARIA/Roles/article_role">article</a></code>, - <code><a href="/en-US/docs/Web/Accessibility/ARIA/Roles/complementary_role">complementary</a></code>, - <code><a href="/en-US/docs/Web/Accessibility/ARIA/Roles/main_role">main</a></code>, - <code><a href="/en-US/docs/Web/Accessibility/ARIA/Roles/navigation_role">navigation</a></code> - or - <code><a href="/en-US/docs/Web/Accessibility/ARIA/Roles/region_role">region</a></code> - </td> - </tr> - <tr> - <th scope="row">Permitted ARIA roles</th> - <td> - <a href="/en-US/docs/Web/Accessibility/ARIA/Roles/group_role"><code>group</code></a>, <a href="/en-US/docs/Web/Accessibility/ARIA/Roles/presentation_role"><code>presentation</code></a> or - <a href="/en-US/docs/Web/Accessibility/ARIA/Roles/none_role"><code>none</code></a> - </td> - </tr> - <tr> - <th scope="row">DOM interface</th> - <td>{{domxref("HTMLElement")}}</td> - </tr> - </tbody> -</table> - -## Specifications - -{{Specifications}} - -## Browser compatibility - -{{Compat}} - -## See also - -- Other section-related elements: {{HTMLElement("body")}}, {{HTMLElement("nav")}}, {{HTMLElement("article")}}, {{HTMLElement("aside")}}, {{HTMLElement("Heading_Elements", "h1")}}, {{HTMLElement("Heading_Elements", "h2")}}, {{HTMLElement("Heading_Elements", "h3")}}, {{HTMLElement("Heading_Elements", "h4")}}, {{HTMLElement("Heading_Elements", "h5")}}, {{HTMLElement("Heading_Elements", "h6")}}, {{HTMLElement("hgroup")}}, {{HTMLElement("header")}}, {{HTMLElement("section")}}, {{HTMLElement("address")}}; -- [Using HTML sections and outlines](/en-US/docs/Web/HTML/Element/Heading_Elements) -- [ARIA: Contentinfo role](/en-US/docs/Web/Accessibility/ARIA/Roles/contentinfo_role) diff --git a/files/en-us/web/html/element/form/index.md b/files/en-us/web/html/element/form/index.md deleted file mode 100644 index 61f756770f55aac..000000000000000 --- a/files/en-us/web/html/element/form/index.md +++ /dev/null @@ -1,226 +0,0 @@ ---- -title: "<form>: The Form element" -slug: Web/HTML/Element/form -page-type: html-element -browser-compat: html.elements.form ---- - -{{HTMLSidebar}} - -The **`<form>`** [HTML](/en-US/docs/Web/HTML) element represents a document section containing interactive controls for submitting information. - -{{InteractiveExample("HTML Demo: &lt;form&gt;", "tabbed-standard")}} - -```html interactive-example -<form action="" method="get" class="form-example"> - <div class="form-example"> - <label for="name">Enter your name: </label> - <input type="text" name="name" id="name" required /> - </div> - <div class="form-example"> - <label for="email">Enter your email: </label> - <input type="email" name="email" id="email" required /> - </div> - <div class="form-example"> - <input type="submit" value="Subscribe!" /> - </div> -</form> -``` - -```css interactive-example -form.form-example { - display: table; -} - -div.form-example { - display: table-row; -} - -label, -input { - display: table-cell; - margin-bottom: 10px; -} - -label { - padding-right: 10px; -} -``` - -It is possible to use the {{cssxref(':valid')}} and {{cssxref(':invalid')}} CSS [pseudo-classes](/en-US/docs/Web/CSS/Pseudo-classes) to style a `<form>` element based on whether the {{domxref("HTMLFormElement.elements", "elements")}} inside the form are valid. - -## Attributes - -This element includes the [global attributes](/en-US/docs/Web/HTML/Global_attributes). - -- `accept` {{deprecated_inline}} - - - : Comma-separated [content types](/en-US/docs/Web/SVG/Content_type) the server accepts. - - > **Note:** **This attribute has been deprecated and should not be used.** Instead, use the [`accept`](/en-US/docs/Web/HTML/Element/input#accept) attribute on `<input type=file>` elements. - -- `accept-charset` - - - : The {{Glossary("character encoding")}} accepted by the server. - The specification allows a single case-insensitive value of `"UTF-8"`, reflecting the ubiquity of this encoding (historically multiple character encodings could be specified as a comma-separated or space-separated list). - -- `autocapitalize` - - - : Controls whether inputted text is automatically capitalized and, if so, in what manner. See the [`autocapitalize`](/en-US/docs/Web/HTML/Global_attributes/autocapitalize) global attribute page for more information. - -- [`autocomplete`](/en-US/docs/Web/HTML/Attributes/autocomplete) - - - : Indicates whether input elements can by default have their values automatically completed by the browser. `autocomplete` attributes on form elements override it on `<form>`. Possible values: - - - `off`: The browser may not automatically complete entries. (Browsers tend to ignore this for suspected login forms; see [Managing autofill for login fields](/en-US/docs/Web/Security/Practical_implementation_guides/Turning_off_form_autocompletion#managing_autofill_for_login_fields).) - - `on`: The browser may automatically complete entries. - -- `name` - - - : The name of the form. The value must not be the empty string, and must be unique among the `form` elements in the forms collection that it is in, if any. - -- [`rel`](/en-US/docs/Web/HTML/Attributes/rel) - - : Controls the annotations and what kinds of links the form creates. Annotations include [`external`](/en-US/docs/Web/HTML/Attributes/rel#external), [`nofollow`](/en-US/docs/Web/HTML/Attributes/rel#nofollow), [`opener`](/en-US/docs/Web/HTML/Attributes/rel#opener), [`noopener`](/en-US/docs/Web/HTML/Attributes/rel#noopener), and [`noreferrer`](/en-US/docs/Web/HTML/Attributes/rel#noreferrer). Link types include [`help`](/en-US/docs/Web/HTML/Attributes/rel#help), [`prev`](/en-US/docs/Web/HTML/Attributes/rel#prev), [`next`](/en-US/docs/Web/HTML/Attributes/rel#next), [`search`](/en-US/docs/Web/HTML/Attributes/rel#search), and [`license`](/en-US/docs/Web/HTML/Attributes/rel#license). The [`rel`](/en-US/docs/Web/HTML/Attributes/rel) value is a space-separated list of these enumerated values. - -### Attributes for form submission - -The following attributes control behavior during form submission. - -- `action` - - : The URL that processes the form submission. This value can be overridden by a [`formaction`](/en-US/docs/Web/HTML/Element/button#formaction) attribute on a {{HTMLElement("button")}}, [`<input type="submit">`](/en-US/docs/Web/HTML/Element/input/submit), or [`<input type="image">`](/en-US/docs/Web/HTML/Element/input/image) element. This attribute is ignored when `method="dialog"` is set. -- `enctype` - - - : If the value of the `method` attribute is `post`, `enctype` is the [MIME type](https://en.wikipedia.org/wiki/Mime_type) of the form submission. Possible values: - - - `application/x-www-form-urlencoded`: The default value. - - `multipart/form-data`: Use this if the form contains {{HTMLElement("input")}} elements with `type=file`. - - `text/plain`: Useful for debugging purposes. - - This value can be overridden by [`formenctype`](/en-US/docs/Web/HTML/Element/button#formenctype) attributes on {{HTMLElement("button")}}, [`<input type="submit">`](/en-US/docs/Web/HTML/Element/input/submit), or [`<input type="image">`](/en-US/docs/Web/HTML/Element/input/image) elements. - -- `method` - - - : The [HTTP](/en-US/docs/Web/HTTP) method to submit the form with. - The only allowed methods/values are (case insensitive): - - - `post`: The {{HTTPMethod("POST")}} method; form data sent as the [request body](/en-US/docs/Web/API/Request/body). - - `get` (default): The {{HTTPMethod("GET")}}; form data appended to the `action` URL with a `?` separator. Use this method when the form [has no side effects](/en-US/docs/Glossary/Idempotent). - - `dialog`: When the form is inside a {{HTMLElement("dialog")}}, closes the dialog and causes a `submit` event to be fired on submission, without submitting data or clearing the form. - - This value is overridden by [`formmethod`](/en-US/docs/Web/HTML/Element/button#formmethod) attributes on {{HTMLElement("button")}}, [`<input type="submit">`](/en-US/docs/Web/HTML/Element/input/submit), or [`<input type="image">`](/en-US/docs/Web/HTML/Element/input/image) elements. - -- `novalidate` - - : This Boolean attribute indicates that the form shouldn't be validated when submitted. If this attribute is not set (and therefore the form **_is_** validated), it can be overridden by a [`formnovalidate`](/en-US/docs/Web/HTML/Element/button#formnovalidate) attribute on a {{HTMLElement("button")}}, [`<input type="submit">`](/en-US/docs/Web/HTML/Element/input/submit), or [`<input type="image">`](/en-US/docs/Web/HTML/Element/input/image) element belonging to the form. -- `target` - - - : Indicates where to display the response after submitting the form. It is a name/keyword for a _browsing context_ (for example, tab, window, or iframe). The following keywords have special meanings: - - - `_self` (default): Load into the same browsing context as the current one. - - `_blank`: Load into a new unnamed browsing context. This provides the same behavior as setting [`rel="noopener"`](#rel) which does not set [`window.opener`](/en-US/docs/Web/API/Window/opener). - - `_parent`: Load into the parent browsing context of the current one. If no parent, behaves the same as `_self`. - - `_top`: Load into the top-level browsing context (i.e., the browsing context that is an ancestor of the current one and has no parent). If no parent, behaves the same as `_self`. - - `_unfencedTop`: Load the response from a form inside an embedded [fenced frame](/en-US/docs/Web/API/Fenced_frame_API) into the top-level frame (i.e., traversing beyond the root of the fenced frame, unlike other reserved destinations). Only available inside fenced frames. - - This value can be overridden by a [`formtarget`](/en-US/docs/Web/HTML/Element/button#formtarget) attribute on a {{HTMLElement("button")}}, [`<input type="submit">`](/en-US/docs/Web/HTML/Element/input/submit), or [`<input type="image">`](/en-US/docs/Web/HTML/Element/input/image) element. - -## Examples - -```html -<!-- Form which will send a GET request to the current URL --> -<form method="get"> - <label> - Name: - <input name="submitted-name" autocomplete="name" /> - </label> - <button>Save</button> -</form> - -<!-- Form which will send a POST request to the current URL --> -<form method="post"> - <label> - Name: - <input name="submitted-name" autocomplete="name" /> - </label> - <button>Save</button> -</form> - -<!-- Form with fieldset, legend, and label --> -<form method="post"> - <fieldset> - <legend>Do you agree to the terms?</legend> - <label><input type="radio" name="radio" value="yes" /> Yes</label> - <label><input type="radio" name="radio" value="no" /> No</label> - </fieldset> -</form> -``` - -### Result - -{{EmbedLiveSample('Examples')}} - -## Technical summary - -<table class="properties"> - <tbody> - <tr> - <th scope="row"> - <a href="/en-US/docs/Web/HTML/Content_categories">Content categories</a> - </th> - <td> - <a href="/en-US/docs/Web/HTML/Content_categories#flow_content">Flow content</a>, - <a href="/en-US/docs/Web/HTML/Content_categories#palpable_content">palpable content</a> - </td> - </tr> - <tr> - <th scope="row">Permitted content</th> - <td> - <a href="/en-US/docs/Web/HTML/Content_categories#flow_content">Flow content</a>, but not containing <code>&#x3C;form></code> elements - </td> - </tr> - <tr> - <th scope="row">Tag omission</th> - <td>None, both the starting and ending tag are mandatory.</td> - </tr> - <tr> - <th scope="row">Permitted parents</th> - <td> - Any element that accepts - <a href="/en-US/docs/Web/HTML/Content_categories#flow_content">flow content</a> - </td> - </tr> - <tr> - <th scope="row">Implicit ARIA role</th> - <td> - <code><a href="/en-US/docs/Web/Accessibility/ARIA/Roles/form_role">form</a></code> - </td> - </tr> - <tr> - <th scope="row">Permitted ARIA roles</th> - <td> - <code><a href="/en-US/docs/Web/Accessibility/ARIA/Roles/search_role">search</a></code>, - <a href="/en-US/docs/Web/Accessibility/ARIA/Roles/none_role"><code>none</code></a> - or <a href="/en-US/docs/Web/Accessibility/ARIA/Roles/presentation_role"><code>presentation</code></a> - </td> - </tr> - <tr> - <th scope="row">DOM interface</th> - <td>{{domxref("HTMLFormElement")}}</td> - </tr> - </tbody> -</table> - -## Specifications - -{{Specifications}} - -## Browser compatibility - -{{Compat}} - -## See also - -- [HTML forms guide](/en-US/docs/Learn_web_development/Extensions/Forms) -- Other elements that are used when creating forms: {{HTMLElement("button")}}, {{HTMLElement("datalist")}}, {{HTMLElement("fieldset")}}, {{HTMLElement("input")}}, {{HTMLElement("label")}}, {{HTMLElement("legend")}}, {{HTMLElement("meter")}}, {{HTMLElement("optgroup")}}, {{HTMLElement("option")}}, {{HTMLElement("output")}}, {{HTMLElement("progress")}}, {{HTMLElement("select")}}, {{HTMLElement("textarea")}}. -- Getting a list of the elements in the form: {{domxref("HTMLFormElement.elements")}} -- [ARIA: Form role](/en-US/docs/Web/Accessibility/ARIA/Roles/form_role) -- [ARIA: Search role](/en-US/docs/Web/Accessibility/ARIA/Roles/search_role) diff --git a/files/en-us/web/html/element/frame/index.md b/files/en-us/web/html/element/frame/index.md deleted file mode 100644 index e951db0668a4889..000000000000000 --- a/files/en-us/web/html/element/frame/index.md +++ /dev/null @@ -1,67 +0,0 @@ ---- -title: <frame> -slug: Web/HTML/Element/frame -page-type: html-element -status: - - deprecated -browser-compat: html.elements.frame ---- - -{{HTMLSidebar}}{{Deprecated_Header}} - -The **`<frame>`** [HTML](/en-US/docs/Web/HTML) element defines a particular area in which another HTML document can be displayed. A frame should be used within a {{HTMLElement("frameset")}}. - -Using the `<frame>` element is not encouraged because of certain disadvantages such as performance problems and lack of accessibility for users with screen readers. Instead of the `<frame>` element, {{HTMLElement("iframe")}} may be preferred. - -## Attributes - -Like all other HTML elements, this element supports the [global attributes](/en-US/docs/Web/HTML/Global_attributes). - -- `src` {{Deprecated_Inline}} - - : This attribute specifies the document that will be displayed by the frame. -- `name` {{Deprecated_Inline}} - - : This attribute is used for labeling frames. Without labeling, every link will open in the frame that it's in – the closest parent frame. See the [`target`](/en-US/docs/Web/HTML/Element/a#target) attribute for more information. -- `noresize` {{Deprecated_Inline}} - - : This attribute prevents resizing of frames by users. -- `scrolling` {{Deprecated_Inline}} - - : This attribute defines the existence of a scrollbar. If this attribute is not used, the browser adds a scrollbar when necessary. There are two choices: "yes" for forcing a scrollbar even when it is not necessary and "no" for forcing no scrollbar even when it _is_ necessary. -- `marginheight` {{Deprecated_Inline}} - - : This attribute defines the height of the margin between frames. -- `marginwidth` {{Deprecated_Inline}} - - : This attribute defines the width of the margin between frames. -- `frameborder` {{Deprecated_Inline}} - - : This attribute allows you to specify a frame's border. - -## Example - -### A frameset document - -A frameset document has a {{HTMLElement("frameset")}} element instead of a {{HTMLElement("body")}} element. The `<frame>` elements are placed within the `<frameset>`. - -```html -<!doctype html> -<html lang="en-US"> - <head> - <!-- Document metadata goes here --> - </head> - <frameset cols="400, 500"> - <frame src="https://developer.mozilla.org/en/HTML/Element/iframe" /> - <frame src="https://developer.mozilla.org/en/HTML/Element/frame" /> - </frameset> -</html> -``` - -If you want to embed another HTML page into the {{HTMLElement("body")}} of a document, use an {{HTMLElement("iframe")}} element. - -## Specifications - -{{Specifications}} - -## Browser compatibility - -{{Compat}} - -## See also - -- {{HTMLElement("frameset")}} -- {{HTMLElement("iframe")}} diff --git a/files/en-us/web/html/element/frameset/index.md b/files/en-us/web/html/element/frameset/index.md deleted file mode 100644 index 547753a0bdc2ad2..000000000000000 --- a/files/en-us/web/html/element/frameset/index.md +++ /dev/null @@ -1,60 +0,0 @@ ---- -title: <frameset> -slug: Web/HTML/Element/frameset -page-type: html-element -status: - - deprecated -browser-compat: html.elements.frameset ---- - -{{HTMLSidebar}}{{Deprecated_header}} - -The **`<frameset>`** [HTML](/en-US/docs/Web/HTML) element is used to contain {{HTMLElement("frame")}} elements. - -> [!NOTE] -> Because the use of frames is now discouraged in favor of using {{HTMLElement("iframe")}}, this element is not typically used by modern websites. - -## Attributes - -Like all other HTML elements, this element supports the [global attributes](/en-US/docs/Web/HTML/Global_attributes). - -- `cols` {{Deprecated_Inline}} - - : This attribute specifies the number and size of horizontal spaces in a frameset. -- `rows` {{Deprecated_Inline}} - - : This attribute specifies the number and size of vertical spaces in a frameset. - -## Example - -### A frameset document - -A frameset document has a `<frameset>` element instead of a {{HTMLElement("body")}} element. The {{HTMLElement("frame")}} elements are placed within the `<frameset>`. - -```html -<!doctype html> -<html lang="en-US"> - <head> - <!-- Document metadata goes here --> - </head> - <frameset cols="50%, 50%"> - <frame - src="https://developer.mozilla.org/en-US/docs/Web/HTML/Element/iframe" /> - <frame - src="https://developer.mozilla.org/en-US/docs/Web/HTML/Element/frame" /> - </frameset> -</html> -``` - -If you want to embed another HTML page into the {{HTMLElement("body")}} of a document, use an {{HTMLElement("iframe")}} element. - -## Specifications - -{{Specifications}} - -## Browser compatibility - -{{Compat}} - -## See also - -- {{HTMLElement("frame")}} -- {{HTMLElement("iframe")}} diff --git a/files/en-us/web/html/element/head/index.md b/files/en-us/web/html/element/head/index.md deleted file mode 100644 index 5835dc137bbad27..000000000000000 --- a/files/en-us/web/html/element/head/index.md +++ /dev/null @@ -1,113 +0,0 @@ ---- -title: "<head>: The Document Metadata (Header) element" -slug: Web/HTML/Element/head -page-type: html-element -browser-compat: html.elements.head ---- - -{{HTMLSidebar}} - -The **`<head>`** [HTML](/en-US/docs/Web/HTML) element contains machine-readable information ({{glossary("metadata")}}) about the document, like its [title](/en-US/docs/Web/HTML/Element/title), [scripts](/en-US/docs/Web/HTML/Element/script), and [style sheets](/en-US/docs/Web/HTML/Element/style). There can be only one `<head>` element in an HTML document. - -> **Note:** `<head>` primarily holds information for machine processing, not human-readability. For human-visible information, like top-level headings and listed authors, see the {{HTMLElement("header")}} element. - -## Attributes - -This element includes the [global attributes](/en-US/docs/Web/HTML/Global_attributes). - -- `profile` {{deprecated_inline}} - - : The {{glossary("URI")}}s of one or more metadata profiles, separated by {{Glossary("whitespace", "white space")}}. - -## Examples - -```html -<!doctype html> -<html lang="en-US"> - <head> - <meta charset="UTF-8" /> - <meta name="viewport" content="width=device-width" /> - <title>Document title</title> - </head> -</html> -``` - -## Technical summary - -<table class="properties"> - <tbody> - <tr> - <th scope="row"> - <a href="/en-US/docs/Web/HTML/Content_categories" - >Content categories</a - > - </th> - <td>None.</td> - </tr> - <tr> - <th scope="row">Permitted content</th> - <td> - <p> - If the document is an {{HTMLElement("iframe")}} - <a href="/en-US/docs/Web/HTML/Element/iframe#srcdoc"><code>srcdoc</code></a> document, or if title - information is available from a higher level protocol (like the - subject line in HTML email), zero or more elements of metadata - content. - </p> - <p> - Otherwise, one or more elements of metadata content where exactly one - is a {{HTMLElement("title")}} element. - </p> - </td> - </tr> - <tr> - <th scope="row">Tag omission</th> - <td> - The start tag may be omitted if the first thing inside the - <code>&#x3C;head></code> element is an element.<br />The end tag may be - omitted if the first thing following the - <code>&#x3C;head></code> element is not a space character or a comment. - </td> - </tr> - <tr> - <th scope="row">Permitted parents</th> - <td>An {{HTMLElement("html")}} element, as its first child.</td> - </tr> - <tr> - <th scope="row">Implicit ARIA role</th> - <td> - <a href="https://www.w3.org/TR/html-aria/#dfn-no-corresponding-role" - >No corresponding role</a - > - </td> - </tr> - <tr> - <th scope="row">Permitted ARIA roles</th> - <td>No <code>role</code> permitted</td> - </tr> - <tr> - <th scope="row">DOM interface</th> - <td>{{domxref("HTMLHeadElement")}}</td> - </tr> - </tbody> -</table> - -## Specifications - -{{Specifications}} - -## Browser compatibility - -{{Compat}} - -## See also - -- Elements that can be used inside the `<head>`: - - - {{HTMLElement("title")}} - - {{HTMLElement("base")}} - - {{HTMLElement("link")}} - - {{HTMLElement("style")}} - - {{HTMLElement("meta")}} - - {{HTMLElement("script")}} - - {{HTMLElement("noscript")}} - - {{HTMLElement("template")}} diff --git a/files/en-us/web/html/element/header/index.md b/files/en-us/web/html/element/header/index.md deleted file mode 100644 index ec658d42a739816..000000000000000 --- a/files/en-us/web/html/element/header/index.md +++ /dev/null @@ -1,223 +0,0 @@ ---- -title: "<header>: The Header element" -slug: Web/HTML/Element/header -page-type: html-element -browser-compat: html.elements.header ---- - -{{HTMLSidebar}} - -The **`<header>`** [HTML](/en-US/docs/Web/HTML) element represents introductory content, typically a group of introductory or navigational aids. It may contain some heading elements but also a logo, a search form, an author name, and other elements. - -{{InteractiveExample("HTML Demo: &lt;header&gt;", "tabbed-standard")}} - -```html interactive-example -<header> - <a class="logo" href="#">Cute Puppies Express!</a> -</header> - -<article> - <header> - <h1>Beagles</h1> - <time>08.12.2014</time> - </header> - <p> - I love beagles <em>so</em> much! Like, really, a lot. They’re adorable and - their ears are so, so snugly soft! - </p> -</article> -``` - -```css interactive-example -.logo { - background: left / cover - url("/shared-assets/images/examples/puppy-header.jpg"); - display: flex; - height: 120px; - align-items: center; - justify-content: center; - font: - bold calc(1em + 2 * (100vw - 120px) / 100) "Dancing Script", - fantasy; - color: #ff0083; - text-shadow: #000 2px 2px 0.2rem; -} - -header > h1 { - margin-bottom: 0; -} - -header > time { - font: italic 0.7rem sans-serif; -} -``` - -## Usage notes - -The `<header>` element has an identical meaning to the site-wide [`banner`](/en-US/docs/Web/Accessibility/ARIA/Roles/banner_role) landmark role, unless nested within sectioning content. Then, the `<header>` element is not a landmark. - -The `<header>` element can define a global site header, described as a `banner` in the accessibility tree. It usually includes a logo, company name, search feature, and possibly the global navigation or a slogan. It is generally located at the top of the page. - -Otherwise, it is a `section` in the accessibility tree, and usually contains the surrounding section's heading (an `h1` – `h6` element) and optional subheading, but this is **not** required. - -### Historical Usage - -The `<header>` element originally existed at the very beginning of HTML for headings. It is seen in [the very first website](https://info.cern.ch/). At some point, headings became [`<h1>` through `<h6>`](/en-US/docs/Web/HTML/Element/Heading_Elements), allowing `<header>` to be free to fill a different role. - -## Attributes - -This element only includes the [global attributes](/en-US/docs/Web/HTML/Global_attributes). - -## Accessibility - -The `<header>` element defines a [`banner`](/en-US/docs/Web/Accessibility/ARIA/Roles/banner_role) landmark when its context is the {{HTMLElement('body')}} element. The HTML header element is not considered a banner landmark when it is descendant of an {{HTMLElement('article')}}, {{HTMLElement('aside')}}, {{HTMLElement('main')}}, {{HTMLElement('nav')}}, or {{HTMLElement('section')}} element. - -## Examples - -### Page Header - -```html -<header> - <h1>Main Page Title</h1> - <img src="mdn-logo-sm.png" alt="MDN logo" /> -</header> -``` - -#### Result - -{{EmbedLiveSample('Page Header')}} - -### Article Header - -```html -<article> - <header> - <h2>The Planet Earth</h2> - <p> - Posted on Wednesday, <time datetime="2017-10-04">4 October 2017</time> by - Jane Smith - </p> - </header> - <p> - We live on a planet that's blue and green, with so many things still unseen. - </p> - <p><a href="https://example.com/the-planet-earth/">Continue reading…</a></p> -</article> -``` - -#### Result - -{{EmbedLiveSample('Article Header')}} - -## Technical summary - -<table class="properties"> - <tbody> - <tr> - <th scope="row"> - <a href="/en-US/docs/Web/HTML/Content_categories" - >Content categories</a - > - </th> - <td> - <a href="/en-US/docs/Web/HTML/Content_categories#flow_content" - >Flow content</a - >, - <a href="/en-US/docs/Web/HTML/Content_categories#palpable_content" - >palpable content</a - >. - </td> - </tr> - <tr> - <th scope="row">Permitted content</th> - <td> - <a href="/en-US/docs/Web/HTML/Content_categories#flow_content" - >Flow content</a - >, but with no <code>&#x3C;header></code> or - {{HTMLElement("footer")}} descendant. - </td> - </tr> - <tr> - <th scope="row">Tag omission</th> - <td>None, both the starting and ending tag are mandatory.</td> - </tr> - <tr> - <th scope="row">Permitted parents</th> - <td> - Any element that accepts - <a href="/en-US/docs/Web/HTML/Content_categories#flow_content" - >flow content</a - >. Note that a <code>&#x3C;header></code> element must not be a - descendant of an {{HTMLElement("address")}}, - {{HTMLElement("footer")}} or another - <code>&lt;header&gt;</code> element. - </td> - </tr> - <tr> - <th scope="row">Implicit ARIA role</th> - <td> - <a href="/en-US/docs/Web/Accessibility/ARIA/Roles/banner_role">banner</a - >, or - <a href="/en-US/docs/Web/Accessibility/ARIA/Roles/generic_role" - >generic</a - > - if a descendant of an - <code><a href="/en-US/docs/Web/HTML/Element/article">article</a></code - >, <code><a href="/en-US/docs/Web/HTML/Element/aside">aside</a></code - >, <code><a href="/en-US/docs/Web/HTML/Element/main">main</a></code - >, <code><a href="/en-US/docs/Web/HTML/Element/nav">nav</a></code> or - <code><a href="/en-US/docs/Web/HTML/Element/section">section</a></code> - element, or an element with - <code - >role=<a href="/en-US/docs/Web/Accessibility/ARIA/Roles/article_role" - >article</a - ></code - >, - <code - ><a href="/en-US/docs/Web/Accessibility/ARIA/Roles/complementary_role" - >complementary</a - ></code - >, - <code - ><a href="/en-US/docs/Web/Accessibility/ARIA/Roles/main_role" - >main</a - ></code - >, - <code - ><a href="/en-US/docs/Web/Accessibility/ARIA/Roles/navigation_role" - >navigation</a - ></code - > - or - <code - ><a href="/en-US/docs/Web/Accessibility/ARIA/Roles/region_role" - >region</a - ></code - > - </td> - </tr> - <tr> - <th scope="row">Permitted ARIA roles</th> - <td> - <a href="/en-US/docs/Web/Accessibility/ARIA/Roles/group_role"><code>group</code></a>, <a href="/en-US/docs/Web/Accessibility/ARIA/Roles/presentation_role"><code>presentation</code></a> or - <a href="/en-US/docs/Web/Accessibility/ARIA/Roles/none_role"><code>none</code></a> - </td> - </tr> - <tr> - <th scope="row">DOM interface</th> - <td>{{domxref("HTMLElement")}}</td> - </tr> - </tbody> -</table> - -## Specifications - -{{Specifications}} - -## Browser compatibility - -{{Compat}} - -## See also - -- Other section-related elements: {{HTMLElement("body")}}, {{HTMLElement("nav")}}, {{HTMLElement("article")}}, {{HTMLElement("aside")}}, {{HTMLElement("Heading_Elements", "h1")}}, {{HTMLElement("Heading_Elements", "h2")}}, {{HTMLElement("Heading_Elements", "h3")}}, {{HTMLElement("Heading_Elements", "h4")}}, {{HTMLElement("Heading_Elements", "h5")}}, {{HTMLElement("Heading_Elements", "h6")}}, {{HTMLElement("footer")}}, {{HTMLElement("section")}}, {{HTMLElement("address")}}. diff --git a/files/en-us/web/html/element/heading_elements/index.md b/files/en-us/web/html/element/heading_elements/index.md deleted file mode 100644 index 6382b6a11489242..000000000000000 --- a/files/en-us/web/html/element/heading_elements/index.md +++ /dev/null @@ -1,336 +0,0 @@ ---- -title: "<h1>–<h6>: The HTML Section Heading elements" -slug: Web/HTML/Element/Heading_Elements -page-type: html-element -browser-compat: - - html.elements.h1 - - html.elements.h2 - - html.elements.h3 - - html.elements.h4 - - html.elements.h5 - - html.elements.h6 ---- - -{{HTMLSidebar}} - -The **`<h1>`** to **`<h6>`** [HTML](/en-US/docs/Web/HTML) elements represent six levels of section headings. `<h1>` is the highest section level and `<h6>` is the lowest. By default, all heading elements create a [block-level](/en-US/docs/Glossary/Block-level_content) box in the layout, starting on a new line and taking up the full width available in their containing block. - -{{InteractiveExample("HTML Demo: &lt;h1-h6&gt;", "tabbed-standard")}} - -```html interactive-example -<h1>Beetles</h1> -<h2>External morphology</h2> -<h3>Head</h3> -<h4>Mouthparts</h4> -<h3>Thorax</h3> -<h4>Prothorax</h4> -<h4>Pterothorax</h4> -``` - -```css interactive-example -h1, -h2, -h3, -h4 { - margin: 0.1rem 0; -} - -h1 { - font-size: 2rem; -} - -h2 { - font-size: 1.5rem; - padding-left: 20px; -} - -h3 { - font-size: 1.2rem; - padding-left: 40px; -} - -h4 { - font-size: 1rem; - font-style: italic; - padding-left: 60px; -} -``` - -## Attributes - -These elements only include the [global attributes](/en-US/docs/Web/HTML/Global_attributes). - -## Usage notes - -- Heading information can be used by user agents to construct a table of contents for a document automatically. -- Do not use heading elements to resize text. Instead, use the {{glossary("CSS")}} {{cssxref("font-size")}} property. -- Do not skip heading levels: always start from `<h1>`, followed by `<h2>` and so on. - -### Avoid using multiple `<h1>` elements on one page - -While using multiple `<h1>` elements on one page is allowed by the HTML standard (as long as they are not [nested](#nesting)), this is not considered a best practice. A page should generally have a single `<h1>` element that describes the content of the page (similar to the document's [`<title>`](/en-US/docs/Web/HTML/Element/title) element). - -> [!NOTE] -> Nesting multiple `<h1>` elements in nested [sectioning elements](/en-US/docs/Web/HTML/Element#content_sectioning) was allowed in older versions of the HTML standard. However, this was never considered a best practice and is now non-conforming. Read more in [There Is No Document Outline Algorithm](https://adrianroselli.com/2016/08/there-is-no-document-outline-algorithm.html). - -Prefer using only one `<h1>` per page and [nest headings](#nesting) without skipping levels. - -### Specifying a uniform font size for `<h1>` - -The [HTML standard](https://html.spec.whatwg.org/multipage/rendering.html#sections-and-headings) specifies that `<h1>` elements in a `<section>`, `<article>`, `<aside>`, or `<nav>` element should render as an `<h2>` (smaller {{cssxref("font-size")}} with an adjusted {{cssxref("margin-block")}}), or as an `<h3>` if nested another level, and so on. - -> [!NOTE] -> There is a [proposal](https://github.com/whatwg/html/issues/7867) to remove this special default style, so that `<h1>` always has the same default style. This proposal is currently [implemented in Firefox Nightly](/en-US/docs/Mozilla/Firefox/Experimental_features#ua_styles_for_h1_nested_in_sectioning_elements). - -To ensure consistent `<h1>` rendering, use the following style rule: - -```css -h1 { - margin-block: 0.67em; - font-size: 2em; -} -``` - -Alternatively, to avoid overwriting other style rules that target `<h1>` you can use {{cssxref(":where()")}}, which has zero specificity: - -```css -:where(h1) { - margin-block: 0.67em; - font-size: 2em; -} -``` - -## Accessibility - -### Navigation - -A common navigation technique for users of screen reading software is to quickly jump from heading to heading in order to determine the content of the page. Because of this, it is important to not skip one or more heading levels. Doing so may create confusion, as the person navigating this way may be left wondering where the missing heading is. - -**Don't do this:** - -```html example-bad -<h1>Heading level 1</h1> -<h3>Heading level 3</h3> -<h4>Heading level 4</h4> -``` - -**Prefer this:** - -```html example-good -<h1>Heading level 1</h1> -<h2>Heading level 2</h2> -<h3>Heading level 3</h3> -``` - -#### Nesting - -Headings may be nested as subsections to reflect the organization of the content of the page. Most screen readers can also generate an ordered list of all the headings on a page, which can help a person quickly determine the content hierarchy and navigate to different headings. - -Given the following page structure: - -```html -<h1>Beetles</h1> - -<h2>Etymology</h2> - -<h2>Distribution and Diversity</h2> - -<h2>Evolution</h2> -<h3>Late Paleozoic</h3> -<h3>Jurassic</h3> -<h3>Cretaceous</h3> -<h3>Cenozoic</h3> - -<h2>External Morphology</h2> -<h3>Head</h3> -<h4>Mouthparts</h4> -<h3>Thorax</h3> -<h4>Prothorax</h4> -<h4>Pterothorax</h4> -<h3>Legs</h3> -<h3>Wings</h3> -<h3>Abdomen</h3> -``` - -Screen readers would generate a list like this: - -1. `h1` Beetles - - 1. `h2` Etymology - 2. `h2` Distribution and Diversity - 3. `h2` Evolution - - 1. `h3` Late Paleozoic - 2. `h3` Jurassic - 3. `h3` Cretaceous - 4. `h3` Cenozoic - - 4. `h2` External Morphology - - 1. `h3` Head - - 1. `h4` Mouthparts - - 2. `h3` Thorax - - 1. `h4` Prothorax - 2. `h4` Pterothorax - - 3. `h3` Legs - 4. `h3` Wings - 5. `h3` Abdomen - -When headings are nested, heading levels may be "skipped" when closing a subsection. - -- [Headings • Page Structure • WAI Web Accessibility Tutorials](https://www.w3.org/WAI/tutorials/page-structure/headings/) -- [MDN Understanding WCAG, Guideline 1.3 explanations](/en-US/docs/Web/Accessibility/Understanding_WCAG/Perceivable#guideline_1.3_—_create_content_that_can_be_presented_in_different_ways) -- [Understanding Success Criterion 1.3.1 | W3C Understanding WCAG 2.0](https://www.w3.org/TR/UNDERSTANDING-WCAG20/content-structure-separation-programmatic.html) -- [MDN Understanding WCAG, Guideline 2.4 explanations](/en-US/docs/Web/Accessibility/Understanding_WCAG/Operable#guideline_2.4_—_navigable_provide_ways_to_help_users_navigate_find_content_and_determine_where_they_are) -- [Understanding Success Criterion 2.4.1 | W3C Understanding WCAG 2.0](https://www.w3.org/TR/UNDERSTANDING-WCAG20/navigation-mechanisms-skip.html) -- [Understanding Success Criterion 2.4.6 | W3C Understanding WCAG 2.0](https://www.w3.org/TR/UNDERSTANDING-WCAG20/navigation-mechanisms-descriptive.html) -- [Understanding Success Criterion 2.4.10 | W3C Understanding WCAG 2.0](https://www.w3.org/TR/UNDERSTANDING-WCAG20/navigation-mechanisms-headings.html) - -### Labeling section content - -Another common navigation technique for users of screen reading software is to generate a list of [sectioning content](/en-US/docs/Web/HTML/Element#content_sectioning) and use it to determine the page's layout. - -Sectioning content can be labeled using a combination of the [`aria-labelledby`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-labelledby) and [`id`](/en-US/docs/Web/HTML/Global_attributes/id) attributes, with the label concisely describing the purpose of the section. This technique is useful for situations where there is more than one sectioning element on the same page. - -#### Sectioning content examples - -```html -<header> - <nav aria-labelledby="primary-navigation"> - <h2 id="primary-navigation">Primary navigation</h2> - <!-- navigation items --> - </nav> -</header> - -<!-- page content --> - -<footer> - <nav aria-labelledby="footer-navigation"> - <h2 id="footer-navigation">Footer navigation</h2> - <!-- navigation items --> - </nav> -</footer> -``` - -{{EmbedLiveSample('Sectioning_content_examples')}} - -In this example, screen reading technology would announce that there are two {{HTMLElement("nav")}} sections, one called "Primary navigation" and one called "Footer navigation". If labels were not provided, the person using screen reading software may have to investigate each `nav` element's contents to determine their purpose. - -- [Using the aria-labelledby attribute](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-labelledby) -- [Labeling Regions • Page Structure • W3C WAI Web Accessibility Tutorials](https://www.w3.org/WAI/tutorials/page-structure/labels/#using-aria-labelledby) - -## Examples - -### All headings - -The following code shows all the heading levels, in use. - -```html -<h1>Heading level 1</h1> -<h2>Heading level 2</h2> -<h3>Heading level 3</h3> -<h4>Heading level 4</h4> -<h5>Heading level 5</h5> -<h6>Heading level 6</h6> -``` - -{{EmbedLiveSample('All_headings', '280', '300')}} - -### Example page - -The following code shows a few headings with some content under them. - -```html -<h1>Heading elements</h1> -<h2>Summary</h2> -<p>Some text here…</p> - -<h2>Examples</h2> -<h3>Example 1</h3> -<p>Some text here…</p> - -<h3>Example 2</h3> -<p>Some text here…</p> - -<h2>See also</h2> -<p>Some text here…</p> -``` - -{{EmbedLiveSample('Example_page', '280', '480')}} - -## Technical summary - -<table class="properties"> - <tbody> - <tr> - <th scope="row"> - <a href="/en-US/docs/Web/HTML/Content_categories" - >Content categories</a - > - </th> - <td> - <a href="/en-US/docs/Web/HTML/Content_categories#flow_content" - >Flow content</a - >, heading content, palpable content. - </td> - </tr> - <tr> - <th scope="row">Permitted content</th> - <td> - <a href="/en-US/docs/Web/HTML/Content_categories#phrasing_content" - >Phrasing content</a - >. - </td> - </tr> - <tr> - <th scope="row">Tag omission</th> - <td>None, both the starting and ending tag are mandatory.</td> - </tr> - <tr> - <th scope="row">Permitted parents</th> - <td> - Any element that accepts - <a href="/en-US/docs/Web/HTML/Content_categories#flow_content" - >flow content</a - >. - </td> - </tr> - <tr> - <th scope="row">Implicit ARIA role</th> - <td> - <a href="/en-US/docs/Web/Accessibility/ARIA/Roles/heading_role" - >heading</a - > - </td> - </tr> - <tr> - <th scope="row">Permitted ARIA roles</th> - <td> - <a href="/en-US/docs/Web/Accessibility/ARIA/Roles/tab_role"><code>tab</code></a>, <a href="/en-US/docs/Web/Accessibility/ARIA/Roles/presentation_role"><code>presentation</code></a> or - <a href="/en-US/docs/Web/Accessibility/ARIA/Roles/none_role"><code>none</code></a> - </td> - </tr> - <tr> - <th scope="row">DOM interface</th> - <td>{{domxref("HTMLHeadingElement")}}</td> - </tr> - </tbody> -</table> - -## Specifications - -{{Specifications}} - -## Browser compatibility - -{{Compat}} - -## See also - -- {{HTMLElement("p")}} -- {{HTMLElement("div")}} -- {{HTMLElement("section")}} diff --git a/files/en-us/web/html/element/hgroup/index.md b/files/en-us/web/html/element/hgroup/index.md deleted file mode 100644 index a5af0162b6fb7b9..000000000000000 --- a/files/en-us/web/html/element/hgroup/index.md +++ /dev/null @@ -1,149 +0,0 @@ ---- -title: "<hgroup>: The Heading Group element" -slug: Web/HTML/Element/hgroup -page-type: html-element -browser-compat: html.elements.hgroup ---- - -{{HTMLSidebar}} - -The **`<hgroup>`** [HTML](/en-US/docs/Web/HTML) element represents a heading and related content. It groups a single [`<h1>–<h6>`](/en-US/docs/Web/HTML/Element/Heading_Elements) element with one or more [`<p>`](/en-US/docs/Web/HTML/Element/p). - -{{InteractiveExample("HTML Demo: &lt;hgroup&gt;", "tabbed-standard")}} - -```html interactive-example -<hgroup> - <h1>Frankenstein</h1> - <p>Or: The Modern Prometheus</p> -</hgroup> -<p> - Victor Frankenstein, a Swiss scientist, has a great ambition: to create - intelligent life. But when his creature first stirs, he realizes he has made a - monster. A monster which, abandoned by his master and shunned by everyone who - sees it, follows Dr Frankenstein to the very ends of the earth. -</p> -``` - -```css interactive-example -hgroup { - text-align: right; - padding-right: 16px; - border-right: 10px solid #00c8d7; -} - -hgroup h1 { - margin-bottom: 0; -} - -hgroup p { - margin: 0; - font-weight: bold; -} -``` - -## Attributes - -This element only includes the [global attributes](/en-US/docs/Web/HTML/Global_attributes). - -## Usage notes - -The `<hgroup>` element allows the grouping of a heading with any secondary content, such as subheadings, an alternative title, or tagline. Each of these types of content represented as a `<p>` element within the `<hgroup>`. - -The `<hgroup>` itself has no impact on the document outline of a web page. Rather, the single allowed heading within the `<hgroup>` contributes to the document outline. - -## Examples - -```html -<!doctype html> -<title>HTML Standard</title> -<body> - <hgroup id="document-title"> - <h1>HTML: Living Standard</h1> - <p>Last Updated 12 July 2022</p> - </hgroup> - <p>Some intro to the document.</p> - <h2>Table of contents</h2> - <ol id="toc"> - … - </ol> - <h2>First section</h2> - <p>Some intro to the first section.</p> -</body> -``` - -### Result - -{{EmbedLiveSample('Examples')}} - -## Technical summary - -<table class="properties"> - <tbody> - <tr> - <th scope="row"> - <a href="/en-US/docs/Web/HTML/Content_categories" - >Content categories</a - > - </th> - <td> - <a href="/en-US/docs/Web/HTML/Content_categories#flow_content" - >Flow content</a - >, heading content, palpable content. - </td> - </tr> - <tr> - <th scope="row">Permitted content</th> - <td> - Zero or more {{HTMLElement("p")}} elements, followed by one - {{HTMLElement("Heading_Elements", "h1")}}, {{HTMLElement("Heading_Elements", "h2")}}, - {{HTMLElement("Heading_Elements", "h3")}}, {{HTMLElement("Heading_Elements", "h4")}}, - {{HTMLElement("Heading_Elements", "h5")}}, or {{HTMLElement("Heading_Elements", "h6")}} element, - followed by zero or more {{HTMLElement("p")}} elements. - </td> - </tr> - <tr> - <th scope="row">Tag omission</th> - <td>None, both the starting and ending tag are mandatory.</td> - </tr> - <tr> - <th scope="row">Permitted parents</th> - <td> - Any element that accepts - <a href="/en-US/docs/Web/HTML/Content_categories#flow_content" - >flow content</a - >. - </td> - </tr> - <tr> - <th scope="row">Implicit ARIA role</th> - <td> - <code - ><a href="/en-US/docs/Web/Accessibility/ARIA/Roles/group_role" - >group</a - ></code - > - </td> - </tr> - <tr> - <th scope="row">Permitted ARIA roles</th> - <td>Any</td> - </tr> - <tr> - <th scope="row">DOM interface</th> - <td>{{domxref("HTMLElement")}}</td> - </tr> - </tbody> -</table> - -## Specifications - -{{Specifications}} - -## Browser compatibility - -{{Compat}} - -## See also - -- Others section-related elements: {{HTMLElement("body")}}, {{HTMLElement("article")}}, {{HTMLElement("section")}}, {{HTMLElement("aside")}}, {{HTMLElement("Heading_Elements", "h1")}}, {{HTMLElement("Heading_Elements", "h2")}}, {{HTMLElement("Heading_Elements", "h3")}}, {{HTMLElement("Heading_Elements", "h4")}}, {{HTMLElement("Heading_Elements", "h5")}}, {{HTMLElement("Heading_Elements", "h6")}}, {{HTMLElement("nav")}}, {{HTMLElement("header")}}, {{HTMLElement("footer")}}, {{HTMLElement("address")}}; -- [Sections and outlines of an HTML document](/en-US/docs/Web/HTML/Element/Heading_Elements). diff --git a/files/en-us/web/html/element/hr/index.md b/files/en-us/web/html/element/hr/index.md deleted file mode 100644 index e8182e58a236bfc..000000000000000 --- a/files/en-us/web/html/element/hr/index.md +++ /dev/null @@ -1,141 +0,0 @@ ---- -title: "<hr>: The Thematic Break (Horizontal Rule) element" -slug: Web/HTML/Element/hr -page-type: html-element -browser-compat: html.elements.hr ---- - -{{HTMLSidebar}} - -The **`<hr>`** [HTML](/en-US/docs/Web/HTML) element represents a thematic break between paragraph-level elements: for example, a change of scene in a story, or a shift of topic within a section. - -{{InteractiveExample("HTML Demo: &lt;hr&gt;", "tabbed-shorter")}} - -```html interactive-example -<p>§1: The first rule of Fight Club is: You do not talk about Fight Club.</p> - -<hr /> - -<p>§2: The second rule of Fight Club is: Always bring cupcakes.</p> -``` - -```css interactive-example -hr { - border: none; - border-top: 3px double #333; - color: #333; - overflow: visible; - text-align: center; - height: 5px; -} - -hr::after { - background: #fff; - content: "§"; - padding: 0 4px; - position: relative; - top: -13px; -} -``` - -Historically, this has been presented as a horizontal rule or line. While it may still be displayed as a horizontal rule in visual browsers, this element is now defined in semantic terms, rather than presentational terms, so if you wish to draw a horizontal line, you should do so using appropriate CSS. - -## Attributes - -This element's attributes include the [global attributes](/en-US/docs/Web/HTML/Global_attributes). - -- `align` {{deprecated_inline}} {{Non-standard_Inline}} - - : Sets the alignment of the rule on the page. If no value is specified, the default value is `left`. -- `color` {{deprecated_inline}} {{Non-standard_Inline}} - - : Sets the color of the rule through color name or hexadecimal value. -- `noshade` {{deprecated_inline}} {{Non-standard_Inline}} - - : Sets the rule to have no shading. -- `size` {{deprecated_inline}} {{Non-standard_Inline}} - - : Sets the height, in pixels, of the rule. -- `width` {{deprecated_inline}} {{Non-standard_Inline}} - - : Sets the length of the rule on the page through a pixel or percentage value. - -## Example - -### HTML - -```html -<p> - This is the first paragraph of text. This is the first paragraph of text. This - is the first paragraph of text. This is the first paragraph of text. -</p> - -<hr /> - -<p> - This is the second paragraph of text. This is the second paragraph of text. - This is the second paragraph of text. This is the second paragraph of text. -</p> -``` - -### Result - -{{EmbedLiveSample("Example")}} - -## Technical summary - -<table class="properties"> - <tbody> - <tr> - <th scope="row"> - <a href="/en-US/docs/Web/HTML/Content_categories" - >Content categories</a - > - </th> - <td> - <a href="/en-US/docs/Web/HTML/Content_categories#flow_content" - >Flow content</a - >. - </td> - </tr> - <tr> - <th scope="row">Permitted content</th> - <td>None; it is a {{Glossary("void element")}}.</td> - </tr> - <tr> - <th scope="row">Tag omission</th> - <td>Must have a start tag and must not have an end tag.</td> - </tr> - <tr> - <th scope="row">Permitted parents</th> - <td> - <ul> - <li>Any element that accepts <a href="/en-US/docs/Web/HTML/Content_categories#flow_content">flow content</a></li> - <li><a href="/en-US/docs/Web/HTML/Element/select"><code>&lt;select></code></a> element</li> - </ul> - </td> - </tr> - <tr> - <th scope="row">Implicit ARIA role</th> - <td><a href="/en-US/docs/Web/Accessibility/ARIA/Roles/separator_role"><code>separator</code></a></td> - </tr> - <tr> - <th scope="row">Permitted ARIA roles</th> - <td> - <a href="/en-US/docs/Web/Accessibility/ARIA/Roles/presentation_role"><code>presentation</code></a> or <a href="/en-US/docs/Web/Accessibility/ARIA/Roles/none_role"><code>none</code></a> - </td> - </tr> - <tr> - <th scope="row">DOM interface</th> - <td>{{domxref("HTMLHRElement")}}</td> - </tr> - </tbody> -</table> - -## Specifications - -{{Specifications}} - -## Browser compatibility - -{{Compat}} - -## See also - -- {{HTMLElement('p')}} -- [`<hr>` in `<select>`](/en-US/docs/Web/HTML/Element/select#select_with_grouping_options) diff --git a/files/en-us/web/html/element/html/index.md b/files/en-us/web/html/element/html/index.md deleted file mode 100644 index a4a2549ce7ffe7c..000000000000000 --- a/files/en-us/web/html/element/html/index.md +++ /dev/null @@ -1,106 +0,0 @@ ---- -title: "<html>: The HTML Document / Root element" -slug: Web/HTML/Element/html -page-type: html-element -browser-compat: html.elements.html ---- - -{{HTMLSidebar}} - -The **`<html>`** [HTML](/en-US/docs/Web/HTML) element represents the root (top-level element) of an HTML document, so it is also referred to as the _root element_. All other elements must be descendants of this element. There can be only one `<html>` element in a document. - -## Attributes - -This element includes the [global attributes](/en-US/docs/Web/HTML/Global_attributes). - -- `version` {{deprecated_inline}} - - : Specifies the version of the HTML {{glossary("Doctype", "Document Type Definition")}} that governs the current document. This attribute is not needed, because it is redundant with the version information in the document type declaration. -- `xmlns` - - : Specifies the {{glossary("XML")}} {{glossary("Namespace")}} of the document. Default value is `"http://www.w3.org/1999/xhtml"`. This is required in documents parsed with XML {{glossary("parser", "parsers")}}, and optional in text/html documents. - -## Accessibility - -While HTML does not require authors to specify `<html>` element start and ending tags, it is important for authors to do so as it will allow them to specify the [`lang`](/en-US/docs/Web/HTML/Global_attributes/lang) for the webpage. Providing a `lang` attribute with a valid language tag according to {{RFC(5646, "Tags for Identifying Languages (also known as BCP 47)")}} on the `<html>` element will help screen reading technology determine the proper language to announce. The identifying language tag should describe the language used by the majority of the content of the page. Without it, screen readers will typically default to the operating system's set language, which may cause mispronunciations. - -Including a valid `lang` declaration on the `<html>` element also ensures that important metadata contained in the page's {{HTMLElement("head")}}, such as the page's {{HTMLElement("title")}}, are also announced properly. - -- [MDN Understanding WCAG, Guideline 3.1 explanations](/en-US/docs/Web/Accessibility/Understanding_WCAG/Understandable#guideline_3.1_%e2%80%94_readable_make_text_content_readable_and_understandable) -- [Understanding Success Criterion 3.1.1 | W3C Understanding WCAG 2.1](https://www.w3.org/WAI/WCAG21/Understanding/language-of-page.html) - -## Example - -```html -<!doctype html> -<html lang="en"> - <head> - <!-- … --> - </head> - <body> - <!-- … --> - </body> -</html> -``` - -## Technical summary - -<table class="properties"> - <tbody> - <tr> - <th scope="row"> - <a href="/en-US/docs/Web/HTML/Content_categories" - >Content categories</a - > - </th> - <td>None.</td> - </tr> - <tr> - <th scope="row">Permitted content</th> - <td> - One {{HTMLElement("head")}} element, followed by one - {{HTMLElement("body")}} element. - </td> - </tr> - <tr> - <th scope="row">Tag omission</th> - <td> - The start tag may be omitted if the first thing inside the - <code>&#x3C;html></code> element is not a comment.<br>The end tag may - be omitted if the <code>&#x3C;html></code> element is not immediately - followed by a comment. - </td> - </tr> - <tr> - <th scope="row">Permitted parents</th> - <td>None. This is the root element of a document.</td> - </tr> - <tr> - <th scope="row">Implicit ARIA role</th> - <td> - <a href="/en-US/docs/Web/Accessibility/ARIA/Roles/document_role" - >document</a - > - </td> - </tr> - <tr> - <th scope="row">Permitted ARIA roles</th> - <td>No <code>role</code> permitted</td> - </tr> - <tr> - <th scope="row">DOM interface</th> - <td>{{domxref("HTMLHtmlElement")}}</td> - </tr> - </tbody> -</table> - -## Specifications - -{{Specifications}} - -## Browser compatibility - -{{Compat}} - -## See also - -- MathML top-level element: {{MathMLElement("math")}} -- SVG top-level element: {{SVGElement("svg")}} diff --git a/files/en-us/web/html/element/i/index.md b/files/en-us/web/html/element/i/index.md deleted file mode 100644 index 7b05ab2dd34fa1d..000000000000000 --- a/files/en-us/web/html/element/i/index.md +++ /dev/null @@ -1,146 +0,0 @@ ---- -title: "<i>: The Idiomatic Text element" -slug: Web/HTML/Element/i -page-type: html-element -browser-compat: html.elements.i ---- - -{{HTMLSidebar}} - -The **`<i>`** [HTML](/en-US/docs/Web/HTML) element represents a range of text that is set off from the normal text for some reason, such as idiomatic text, technical terms, taxonomical designations, among others. Historically, these have been presented using italicized type, which is the original source of the `<i>` naming of this element. - -{{InteractiveExample("HTML Demo: &lt;i&gt;", "tabbed-shorter")}} - -```html interactive-example -<p>I looked at it and thought <i>This can't be real!</i></p> - -<p> - <i>Musa</i> is one of two or three genera in the family <i>Musaceae</i>; it - includes bananas and plantains. -</p> - -<p> - The term <i>bandwidth</i> describes the measure of how much information can - pass through a data connection in a given amount of time. -</p> -``` - -```css interactive-example -/* stylelint-disable-next-line block-no-empty */ -i { -} -``` - -## Attributes - -This element only includes the [global attributes](/en-US/docs/Web/HTML/Global_attributes). - -## Usage notes - -- Use the `<i>` element for text that is set off from the normal prose for readability reasons. This would be a range of text with different semantic meaning than the surrounding text. Among the use cases for the `<i>` element are spans of text representing a different quality or mode of text, such as: - - - Alternative voice or mood - - Taxonomic designations (such as the genus and species "_Homo sapiens_") - - Idiomatic terms from another language (such as "_et cetera_"); these should include the [`lang`](/en-US/docs/Web/HTML/Global_attributes/lang) attribute to identify the language - - Technical terms - - Transliterations - - Thoughts (such as "She wondered, _What is this writer talking about, anyway?_") - - Ship or vessel names in Western writing systems (such as "They searched the docks for the _Empress of the Galaxy_, the ship to which they were assigned.") - -- In earlier versions of the HTML specification, the `<i>` element was merely a presentational element used to display text in italics, much like the `<b>` element was used to display text in bold letters. This is no longer true, as these tags now define semantics rather than typographic appearance. A browser will typically still display the contents of the `<i>` element in italic type, but is, by definition, no longer required to do so. To display text in italic type, authors should use the CSS {{cssxref("font-style")}} property. -- Be sure the text in question is not actually more appropriately marked up with another element. - - - Use {{HTMLElement("em")}} to indicate stress emphasis. - - Use {{HTMLElement("strong")}} to indicate importance, seriousness, or urgency. - - Use {{HTMLElement("mark")}} to indicate relevance. - - Use {{HTMLElement("cite")}} to mark up the name of a work, such as a book, play, or song. - - Use {{HTMLElement("dfn")}} to mark up the defining instance of a term. - -## Examples - -This example demonstrates using the `<i>` element to mark text that is in another language. - -```html -<p> - The Latin phrase <i lang="la">Veni, vidi, vici</i> is often mentioned in - music, art, and literature. -</p> -``` - -### Result - -{{EmbedLiveSample("Examples")}} - -## Technical summary - -<table class="properties"> - <tbody> - <tr> - <th scope="row"> - <a href="/en-US/docs/Web/HTML/Content_categories" - >Content categories</a - > - </th> - <td> - <a href="/en-US/docs/Web/HTML/Content_categories#flow_content" - >Flow content</a - >, - <a href="/en-US/docs/Web/HTML/Content_categories#phrasing_content" - >phrasing content</a - >, palpable content. - </td> - </tr> - <tr> - <th scope="row">Permitted content</th> - <td> - <a href="/en-US/docs/Web/HTML/Content_categories#phrasing_content" - >Phrasing content</a - >. - </td> - </tr> - <tr> - <th scope="row">Tag omission</th> - <td>None, both the starting and ending tag are mandatory.</td> - </tr> - <tr> - <th scope="row">Permitted parents</th> - <td> - Any element that accepts - <a href="/en-US/docs/Web/HTML/Content_categories#phrasing_content" - >phrasing content</a - >. - </td> - </tr> - <tr> - <th scope="row">Implicit ARIA role</th> - <td> - <code - ><a href="/en-US/docs/Web/Accessibility/ARIA/Roles/generic_role" - >generic</a - ></code - > - </td> - </tr> - <tr> - <th scope="row">Permitted ARIA roles</th> - <td>Any</td> - </tr> - <tr> - <th scope="row">DOM interface</th> - <td>{{domxref("HTMLElement")}}</td> - </tr> - </tbody> -</table> - -## Specifications - -{{Specifications}} - -## Browser compatibility - -{{Compat}} - -## See also - -- {{HTMLElement("em")}} -- Other italicized elements: {{HTMLElement("var")}}, {{HTMLElement("dfn")}}, {{HTMLElement("cite")}}, {{HTMLElement("address")}} diff --git a/files/en-us/web/html/element/iframe/index.md b/files/en-us/web/html/element/iframe/index.md deleted file mode 100644 index 59d8cd873024a06..000000000000000 --- a/files/en-us/web/html/element/iframe/index.md +++ /dev/null @@ -1,358 +0,0 @@ ---- -title: "<iframe>: The Inline Frame element" -slug: Web/HTML/Element/iframe -page-type: html-element -browser-compat: html.elements.iframe ---- - -{{HTMLSidebar}} - -The **`<iframe>`** [HTML](/en-US/docs/Web/HTML) element represents a nested {{Glossary("browsing context")}}, embedding another HTML page into the current one. - -{{InteractiveExample("HTML Demo: &lt;iframe&gt;", "tabbed-standard")}} - -```html interactive-example -<iframe - id="inlineFrameExample" - title="Inline Frame Example" - width="300" - height="200" - src="https://www.openstreetmap.org/export/embed.html?bbox=-0.004017949104309083%2C51.47612752641776%2C0.00030577182769775396%2C51.478569861898606&amp;layer=mapnik"> -</iframe> -``` - -```css interactive-example -iframe { - border: 1px solid black; - width: 100%; /* takes precedence over the width set with the HTML width attribute */ -} -``` - -Each embedded browsing context has its own [document](/en-US/docs/Web/API/Document) and allows URL navigations. The navigations of each embedded browsing context are linearized into the [session history](/en-US/docs/Web/API/History) of the _topmost_ browsing context. The browsing context that embeds the others is called the _parent browsing context_. The _topmost_ browsing context — the one with no parent — is usually the browser window, represented by the {{domxref("Window")}} object. - -> [!WARNING] -> Because each browsing context is a complete document environment, every `<iframe>` in a page requires increased memory and other computing resources. While theoretically you can use as many `<iframe>`s as you like, check for performance problems. - -## Attributes - -This element includes the [global attributes](/en-US/docs/Web/HTML/Global_attributes). - -- `allow` - - - : Specifies a [Permissions Policy](/en-US/docs/Web/HTTP/Permissions_Policy) for the `<iframe>`. The policy defines what features are available to the `<iframe>` (for example, access to the microphone, camera, battery, web-share, etc.) based on the origin of the request. - - See [iframes](/en-US/docs/Web/HTTP/Headers/Permissions-Policy#iframes) in the `Permissions-Policy` topic for examples. - - > [!NOTE] - > A Permissions Policy specified by the `allow` attribute implements a further restriction on top of the policy specified in the {{httpheader("Permissions-Policy")}} header. It doesn't replace it. - -- `allowfullscreen` - - - : Set to `true` if the `<iframe>` can activate fullscreen mode by calling the {{domxref("Element.requestFullscreen", "requestFullscreen()")}} method. - - > [!NOTE] - > This attribute is considered a legacy attribute and redefined as `allow="fullscreen"`. - -- `allowpaymentrequest` {{deprecated_inline}} {{non-standard_inline}} - - - : Set to `true` if a cross-origin `<iframe>` should be allowed to invoke the [Payment Request API](/en-US/docs/Web/API/Payment_Request_API). - - > [!NOTE] - > This attribute is considered a legacy attribute and redefined as `allow="payment"`. - -- `browsingtopics` {{Experimental_Inline}} {{non-standard_inline}} - - - : A boolean attribute that, if present, specifies that the selected topics for the current user should be sent with the request for the `<iframe>`'s source. See [Using the Topics API](/en-US/docs/Web/API/Topics_API/Using) for more details. - -- `credentialless` {{Experimental_Inline}} - - - : Set to `true` to make the `<iframe>` credentialless, meaning that its content will be loaded in a new, ephemeral context. It doesn't have access to the network, cookies, and storage data associated with its origin. It uses a new context local to the top-level document lifetime. In return, the {{httpheader("Cross-Origin-Embedder-Policy")}} (COEP) embedding rules can be lifted, so documents with COEP set can embed third-party documents that do not. See [IFrame credentialless](/en-US/docs/Web/Security/IFrame_credentialless) for more details. - -- `csp` {{experimental_inline}} - - - : A [Content Security Policy](/en-US/docs/Web/HTTP/CSP) enforced for the embedded resource. See {{domxref("HTMLIFrameElement.csp")}} for details. - -- `height` - - : The height of the frame in CSS pixels. Default is `150`. -- `loading` - - - : Indicates when the browser should load the iframe: - - - `eager` - - : Load the iframe immediately on page load (this is the default value). - - `lazy` - - - : Defer loading of the iframe until it reaches a calculated distance from the {{glossary("visual viewport")}}, as defined by the browser. - The intent is to avoid using the network and storage bandwidth required to fetch the frame until the browser is reasonably certain that it will be needed. - This improves the performance and cost in most typical use cases, in particular by reducing initial page load times. - - > [!NOTE] - > Loading is only deferred when JavaScript is enabled. - > This is an anti-tracking measure. - -- `name` - - : A targetable name for the embedded browsing context. This can be used in the `target` attribute of the {{HTMLElement("a")}}, {{HTMLElement("form")}}, or {{HTMLElement("base")}} elements; the `formtarget` attribute of the {{HTMLElement("input")}} or {{HTMLElement("button")}} elements; or the `windowName` parameter in the {{domxref("Window.open()","window.open()")}} method. -- `referrerpolicy` - - - : Indicates which [referrer](/en-US/docs/Web/API/Document/referrer) to send when fetching the frame's resource: - - - `no-referrer` - - : The {{HTTPHeader("Referer")}} header will not be sent. - - `no-referrer-when-downgrade` - - : The {{HTTPHeader("Referer")}} header will not be sent to {{Glossary("origin")}}s without {{Glossary("TLS")}} ({{Glossary("HTTPS")}}). - - `origin` - - : The sent referrer will be limited to the origin of the referring page: its [scheme](/en-US/docs/Learn_web_development/Howto/Web_mechanics/What_is_a_URL), {{Glossary("host")}}, and {{Glossary("port")}}. - - `origin-when-cross-origin` - - : The referrer sent to other origins will be limited to the scheme, the host, and the port. Navigations on the same origin will still include the path. - - `same-origin` - - : A referrer will be sent for {{Glossary("Same-origin policy", "same origin")}}, but cross-origin requests will contain no referrer information. - - `strict-origin` - - : Only send the origin of the document as the referrer when the protocol security level stays the same (HTTPS→HTTPS), but don't send it to a less secure destination (HTTPS→HTTP). - - `strict-origin-when-cross-origin` (default) - - : Send a full URL when performing a same-origin request, only send the origin when the protocol security level stays the same (HTTPS→HTTPS), and send no header to a less secure destination (HTTPS→HTTP). - - `unsafe-url` - - : The referrer will include the origin _and_ the path (but not the [fragment](/en-US/docs/Web/API/HTMLAnchorElement/hash), [password](/en-US/docs/Web/API/HTMLAnchorElement/password), or [username](/en-US/docs/Web/API/HTMLAnchorElement/username)). **This value is unsafe**, because it leaks origins and paths from TLS-protected resources to insecure origins. - -- `sandbox` - - - : Controls the restrictions applied to the content embedded in the `<iframe>`. The value of the attribute can either be empty to apply all restrictions, or space-separated tokens to lift particular restrictions: - - - `allow-downloads` - - : Allows downloading files through an {{HTMLElement("a")}} or {{HTMLElement("area")}} element with the [download](/en-US/docs/Web/HTML/Element/a#download) attribute, as well as through the navigation that leads to a download of a file. This works regardless of whether the user clicked on the link, or JS code initiated it without user interaction. - - `allow-forms` - - : Allows the page to submit forms. If this keyword is not used, a form will be displayed as normal, but submitting it will not trigger input validation, send data to a web server, or close a dialog. - - `allow-modals` - - : Allows the page to open modal windows by {{domxref("Window.alert()")}}, {{domxref("Window.confirm()")}}, {{domxref("Window.print()")}} and {{domxref("Window.prompt()")}}, while opening a {{HTMLElement("dialog")}} is allowed regardless of this keyword. It also allows the page to receive {{domxref("BeforeUnloadEvent")}} event. - - `allow-orientation-lock` - - : Lets the resource [lock the screen orientation](/en-US/docs/Web/API/Screen/lockOrientation). - - `allow-pointer-lock` - - : Allows the page to use the [Pointer Lock API](/en-US/docs/Web/API/Pointer_Lock_API). - - `allow-popups` - - : Allows popups (like from {{domxref("Window.open()")}}, `target="_blank"`, {{domxref("Window.showModalDialog()")}}). If this keyword is not used, that functionality will silently fail. - - `allow-popups-to-escape-sandbox` - - : Allows a sandboxed document to open a new browsing context without forcing the sandboxing flags upon it. This will allow, for example, a third-party advertisement to be safely sandboxed without forcing the same restrictions upon the page the ad links to. If this flag is not included, a redirected page, popup window, or new tab will be subject to the same sandbox restrictions as the originating `<iframe>`. - - `allow-presentation` - - : Allows embedders to have control over whether an iframe can start a [presentation session](/en-US/docs/Web/API/PresentationRequest). - - `allow-same-origin` - - : If this token is not used, the resource is treated as being from a special origin that always fails the {{Glossary("same-origin policy")}} (potentially preventing access to [data storage/cookies](/en-US/docs/Web/Security/Same-origin_policy#cross-origin_data_storage_access) and some JavaScript APIs). - - `allow-scripts` - - : Allows the page to run scripts (but not create pop-up windows). If this keyword is not used, this operation is not allowed. - - `allow-storage-access-by-user-activation` {{experimental_inline}} - - : Allows a document loaded in the `<iframe>` to use the {{domxref("Storage Access API", "Storage Access API", "", "nocode")}} to request access to unpartitioned cookies. - - `allow-top-navigation` - - : Lets the resource navigate the top-level browsing context (the one named `_top`). - - `allow-top-navigation-by-user-activation` - - : Lets the resource navigate the top-level browsing context, but only if initiated by a user gesture. - - `allow-top-navigation-to-custom-protocols` - - : Allows navigations to non-`http` protocols built into browser or [registered by a website](/en-US/docs/Web/API/Navigator/registerProtocolHandler). This feature is also activated by `allow-popups` or `allow-top-navigation` keyword. - - > [!NOTE] - > - > - When the embedded document has the same origin as the embedding page, it is **strongly discouraged** to use both `allow-scripts` and `allow-same-origin`, as that lets the embedded document remove the `sandbox` attribute — making it no more secure than not using the `sandbox` attribute at all. - > - Sandboxing is useless if the attacker can display content outside a sandboxed `iframe` — such as if the viewer opens the frame in a new tab. Such content should be also served from a _separate origin_ to limit potential damage. - - > [!NOTE] - > When redirecting the user, opening a popup window, or opening a new tab from an embedded page within an `<iframe>` with the `sandbox` attribute, the new browsing context is subject to the same `sandbox` restrictions. This can create issues — for example, if a page embedded within an `<iframe>` without a `sandbox="allow-forms"` or `sandbox="allow-popups-to-escape-sandbox"` attribute set on it opens a new site in a separate tab, form submission in that new browsing context will silently fail. - -- `src` - - - : The URL of the page to embed. Use a value of `about:blank` to embed an empty page that conforms to the [same-origin policy](/en-US/docs/Web/Security/Same-origin_policy#inherited_origins). Also note that programmatically removing an `<iframe>`'s src attribute (e.g. via {{domxref("Element.removeAttribute()")}}) causes `about:blank` to be loaded in the frame in Firefox (from version 65), Chromium-based browsers, and Safari/iOS. - - > [!NOTE] - > The `about:blank` page uses the embedding document's URL as its base URL when resolving any relative URLs, such as anchor links. - -- `srcdoc` - - - : Inline HTML to embed, overriding the `src` attribute. Its content should follow the syntax of a full HTML document, which includes the doctype directive, `<html>`, `<body>` tags, etc., although most of them can be omitted, leaving only the body content. This doc will have `about:srcdoc` as its location. If a browser does not support the `srcdoc` attribute, it will fall back to the URL in the `src` attribute. - - > [!NOTE] - > The `about:srcdoc` page uses the embedding document's URL as its base URL when resolving any relative URLs, such as anchor links. - -- `width` - - : The width of the frame in CSS pixels. Default is `300`. - -### Deprecated attributes - -These attributes are deprecated and may no longer be supported by all user agents. You should not use them in new content, and try to remove them from existing content. - -- `align` {{deprecated_inline}} - - : The alignment of this element with respect to the surrounding context. -- `frameborder` {{deprecated_inline}} - - : The value `1` (the default) draws a border around this frame. The value `0` removes the border around this frame, but you should instead use the CSS property {{cssxref("border")}} to control `<iframe>` borders. -- `longdesc` {{deprecated_inline}} - - : A URL of a long description of the frame's content. Due to widespread misuse, this is not helpful for non-visual browsers. -- `marginheight` {{deprecated_inline}} - - : The amount of space in pixels between the frame's content and its top and bottom borders. -- `marginwidth` {{deprecated_inline}} - - : The amount of space in pixels between the frame's content and its left and right borders. -- `scrolling` {{deprecated_inline}} - - - : Indicates when the browser should provide a scrollbar for the frame: - - - `auto` - - : Only when the frame's content is larger than its dimensions. - - `yes` - - : Always show a scrollbar. - - `no` - - : Never show a scrollbar. - -## Scripting - -Inline frames, like {{HTMLElement("frame")}} elements, are included in the {{domxref("window.frames")}} pseudo-array. - -With the DOM {{domxref("HTMLIFrameElement")}} object, scripts can access the {{domxref("window")}} object of the framed resource via the {{domxref("HTMLIFrameElement.contentWindow", "contentWindow")}} property. The {{domxref("HTMLIFrameElement.contentDocument", "contentDocument")}} property refers to the `document` inside the `<iframe>`, same as `contentWindow.document`. - -From the inside of a frame, a script can get a reference to its parent window with {{domxref("window.parent")}}. - -Script access to a frame's content is subject to the [same-origin policy](/en-US/docs/Web/Security/Same-origin_policy). Scripts cannot access most properties in other `window` objects if the script was loaded from a different origin, including scripts inside a frame accessing the frame's parent. Cross-origin communication can be achieved using {{domxref("Window.postMessage()")}}. - -## Positioning and scaling - -Being a [replaced element](/en-US/docs/Web/CSS/Replaced_element), the `<iframe>` allows the position of the embedded document within its box to be adjusted using the {{cssxref("object-position")}} property. - -> [!NOTE] -> The {{cssxref("object-fit")}} property has no effect on `<iframe>` elements. - -## `error` and `load` event behavior - -The `error` and `load` events fired on `<iframe>`s could be used to probe the URL space of the local network's HTTP servers. Therefore, as a security precaution user agents do not fire the [error](/en-US/docs/Web/API/HTMLElement/error_event) event on `<iframe>`s, and the [load](/en-US/docs/Web/API/HTMLElement/load_event) event is always triggered even if the `<iframe>` content fails to load. - -## Accessibility - -People navigating with assistive technology such as a screen reader can use the [`title` attribute](/en-US/docs/Web/HTML/Global_attributes/title) on an `<iframe>` to label its content. The title's value should concisely describe the embedded content: - -```html -<iframe - title="Wikipedia page for Avocados" - src="https://en.wikipedia.org/wiki/Avocado"></iframe> -``` - -Without this title, they have to navigate into the `<iframe>` to determine what its embedded content is. This context shift can be confusing and time-consuming, especially for pages with multiple `<iframe>`s and/or if embeds contain interactive content like video or audio. - -## Examples - -### A basic \<iframe> - -This example embeds the page at <https://example.org> in an iframe. This is a common use case of iframes: to embed content from another site. For example, the live sample itself, and the [try it](#try_it) example at the top, are both `<iframe>` embeds of content from another MDN site. - -#### HTML - -```html -<iframe - src="https://example.org" - title="iframe Example 1" - width="400" - height="300"> -</iframe> -``` - -#### Result - -{{ EmbedLiveSample('A_basic_iframe', 640,400)}} - -### Embedding source code in an \<iframe> - -This example directly renders source code in an iframe. This can be used as a technique to prevent script injection when displaying user-generated content, when combined with the `sandbox` attribute. - -Note that when using `srcdoc`, any relative URLs in the embedded content will be resolved relative to the URL of the embedding page. If you want to use anchor links that point to places in the embedded content, you need to explicitly specify `about:srcdoc` as the base URL. - -#### HTML - -```html-nolint -<article> - <footer>Nine minutes ago, <i>jc</i> wrote:</footer> - <iframe - sandbox - srcdoc="<p>There are two ways to use the <code>iframe</code> element:</p> -<ol> -<li><a href=&quot;about:srcdoc#embed_another&quot;>To embed content from another page</a></li> -<li><a href=&quot;about:srcdoc#embed_user&quot;>To embed user-generated content</a></li> -</ol> -<h2 id=&quot;embed_another&quot;>Embedding content from another page</h2> -<p>Use the <code>src</code> attribute to specify the URL of the page to embed:</p> -<pre><code>&amp;lt;iframe src=&quot;https://example.org&quot;&amp;gt;&amp;lt;/iframe&amp;gt;</code></pre> -<h2 id=&quot;embed_user&quot;>Embedding user-generated content</h2> -<p>Use the <code>srcdoc</code> attribute to specify the content to embed. This post is already an example!</p> -" - width="500" - height="250" -></iframe> -</article> -``` - -Here's how to write escape sequences when using `srcdoc`: - -- First, write the HTML out, escaping anything you would escape in a normal HTML document (such as `<`, `>`, `&`, etc.). -- `&lt;` and `<` represent the exact same character in the `srcdoc` attribute. Therefore, to make it an actual escape sequence in the HTML document, replace any ampersands (`&`) with `&amp;`. For example, `&lt;` becomes `&amp;lt;`, and `&amp;` becomes `&amp;amp;`. -- Replace any double quotes (`"`) with `&quot;` to prevent the `srcdoc` attribute from being prematurely terminated (if you use `'` instead, then you should replace `'` with `&apos;` instead). This step happens after the previous one, so `&quot;` generated in this step doesn't become `&amp;quot;`. - -#### Result - -{{ EmbedLiveSample('Embedding_source_code_in_an_iframe', 640, 300)}} - -## Technical summary - -<table class="properties"> - <tbody> - <tr> - <th scope="row"> - <a href="/en-US/docs/Web/HTML/Content_categories" - >Content categories</a - > - </th> - <td> - <a href="/en-US/docs/Web/HTML/Content_categories#flow_content" - >Flow content</a - >, - <a href="/en-US/docs/Web/HTML/Content_categories#phrasing_content" - >phrasing content</a - >, embedded content, interactive content, palpable content. - </td> - </tr> - <tr> - <th scope="row">Permitted content</th> - <td>None.</td> - </tr> - <tr> - <th scope="row">Tag omission</th> - <td>None, both the starting and ending tags are mandatory.</td> - </tr> - <tr> - <th scope="row">Permitted parents</th> - <td>Any element that accepts embedded content.</td> - </tr> - <tr> - <th scope="row">Implicit ARIA role</th> - <td> - <a href="https://www.w3.org/TR/html-aria/#dfn-no-corresponding-role" - >No corresponding role</a - > - </td> - </tr> - <tr> - <th scope="row">Permitted ARIA roles</th> - <td> - <a href="/en-US/docs/Web/Accessibility/ARIA/Roles/application_role"><code>application</code></a>, <a href="/en-US/docs/Web/Accessibility/ARIA/Roles/document_role"><code>document</code></a>, - <a href="/en-US/docs/Web/Accessibility/ARIA/Roles/img_role"><code>img</code></a>, <a href="/en-US/docs/Web/Accessibility/ARIA/Roles/none_role"><code>none</code></a>, - <a href="/en-US/docs/Web/Accessibility/ARIA/Roles/presentation_role"><code>presentation</code></a> - </td> - </tr> - <tr> - <th scope="row">DOM interface</th> - <td>{{domxref("HTMLIFrameElement")}}</td> - </tr> - </tbody> -</table> - -## Specifications - -{{Specifications}} - -## Browser compatibility - -{{Compat}} - -## See also - -- [CSP: frame-ancestors](/en-US/docs/Web/HTTP/Headers/Content-Security-Policy/frame-ancestors) -- [Privacy, permissions, and information security](/en-US/docs/Web/Privacy) diff --git a/files/en-us/web/html/element/img/favicon144.png b/files/en-us/web/html/element/img/favicon144.png deleted file mode 100644 index e30b574b6540f52..000000000000000 Binary files a/files/en-us/web/html/element/img/favicon144.png and /dev/null differ diff --git a/files/en-us/web/html/element/img/favicon72.png b/files/en-us/web/html/element/img/favicon72.png deleted file mode 100644 index db68260ca1fe508..000000000000000 Binary files a/files/en-us/web/html/element/img/favicon72.png and /dev/null differ diff --git a/files/en-us/web/html/element/img/index.md b/files/en-us/web/html/element/img/index.md deleted file mode 100644 index 8cd695992194070..000000000000000 --- a/files/en-us/web/html/element/img/index.md +++ /dev/null @@ -1,548 +0,0 @@ ---- -title: "<img>: The Image Embed element" -slug: Web/HTML/Element/img -page-type: html-element -browser-compat: html.elements.img ---- - -{{HTMLSidebar}} - -The **`<img>`** [HTML](/en-US/docs/Web/HTML) element embeds an image into the document. - -{{InteractiveExample("HTML Demo: &lt;img&gt;", "tabbed-standard")}} - -```html interactive-example -<img - class="fit-picture" - src="/shared-assets/images/examples/grapefruit-slice.jpg" - alt="Grapefruit slice atop a pile of other slices" /> -``` - -```css interactive-example -.fit-picture { - width: 250px; -} -``` - -The above example shows usage of the `<img>` element: - -- The `src` attribute is **required**, and contains the path to the image you want to embed. -- The `alt` attribute holds a textual replacement for the image, which is mandatory and **incredibly useful** for accessibility — screen readers read the attribute value out to their users so they know what the image means. Alt text is also displayed on the page if the image can't be loaded for some reason: for example, network errors, content blocking, or link rot. - -There are many other attributes to achieve various purposes: - -- [Referrer](/en-US/docs/Web/HTTP/Headers/Referrer-Policy)/{{glossary("CORS")}} control for security and privacy: see [`crossorigin`](#crossorigin) and [`referrerpolicy`](#referrerpolicy). -- Use both [`width`](#width) and [`height`](#height) to set the intrinsic size of the image, allowing it to take up space before it loads, to mitigate content layout shifts. -- Responsive image hints with [`sizes`](#sizes) and [`srcset`](#srcset) (see also the {{htmlelement("picture")}} element and our [Responsive images](/en-US/docs/Web/HTML/Responsive_images) tutorial). - -## Supported image formats - -The HTML standard doesn't list what image formats to support, so {{glossary("user agent","user agents")}} may support different formats. - -> [!NOTE] -> The [Image file type and format guide](/en-US/docs/Web/Media/Guides/Formats/Image_types) provides comprehensive information about image formats and their web browser support. -> This section is just a summary! - -The image file formats that are most commonly used on the web are: - -- [APNG (Animated Portable Network Graphics)](/en-US/docs/Web/Media/Guides/Formats/Image_types#apng_animated_portable_network_graphics) — Good choice for lossless animation sequences (GIF is less performant) -- [AVIF (AV1 Image File Format)](/en-US/docs/Web/Media/Guides/Formats/Image_types#avif_image) — Good choice for both images and animated images due to high performance. -- [GIF (Graphics Interchange Format)](/en-US/docs/Web/Media/Guides/Formats/Image_types#gif_graphics_interchange_format) — Good choice for _simple_ images and animations. -- [JPEG (Joint Photographic Expert Group image)](/en-US/docs/Web/Media/Guides/Formats/Image_types#jpeg_joint_photographic_experts_group_image) — Good choice for lossy compression of still images (currently the most popular). -- [PNG (Portable Network Graphics)](/en-US/docs/Web/Media/Guides/Formats/Image_types#png_portable_network_graphics) — Good choice for lossless compression of still images (slightly better quality than JPEG). -- [SVG (Scalable Vector Graphics)](/en-US/docs/Web/Media/Guides/Formats/Image_types#svg_scalable_vector_graphics) — Vector image format. Use for images that must be drawn accurately at different sizes. -- [WebP (Web Picture format)](/en-US/docs/Web/Media/Guides/Formats/Image_types#webp_image) — Excellent choice for both images and animated images - -Formats like [WebP](/en-US/docs/Web/Media/Guides/Formats/Image_types#webp_image) and [AVIF](/en-US/docs/Web/Media/Guides/Formats/Image_types#avif_image) are recommended as they perform much better than PNG, JPEG, GIF for both still and animated images. - -SVG remains the recommended format for images that must be drawn accurately at different sizes. - -## Image loading errors - -If an error occurs while loading or rendering an image, and an `onerror` event handler has been set for the {{domxref("HTMLElement/error_event", "error")}} event, that event handler will get called. This can happen in several situations, including: - -- The `src` attribute is empty (`""`) or `null`. -- The `src` {{glossary("URL")}} is the same as the URL of the page the user is currently on. -- The image is corrupted in some way that prevents it from being loaded. -- The image's metadata is corrupted in such a way that it's impossible to retrieve its dimensions, and no dimensions were specified in the `<img>` element's attributes. -- The image is in a format not supported by the {{Glossary("user agent")}}. - -## Attributes - -This element includes the [global attributes](/en-US/docs/Web/HTML/Global_attributes). - -- [`alt`](/en-US/docs/Web/API/HTMLImageElement/alt#usage_notes) - - - : Defines text that can replace the image in the page. - - > [!NOTE] - > Browsers do not always display images. There are a number of situations in which a browser might not display images, such as: - > - > - Non-visual browsers (such as those used by people with visual impairments) - > - The user chooses not to display images (saving bandwidth, privacy reasons) - > - The image is invalid or an [unsupported type](#supported_image_formats) - > - > In these cases, the browser may replace the image with the text in the element's `alt` attribute. For these reasons and others, provide a useful value for `alt` whenever possible. - - Setting this attribute to an empty string (`alt=""`) indicates that this image is _not_ a key part of the content (it's decoration or a tracking pixel), and that non-visual browsers may omit it from {{glossary("Engine/Rendering", "rendering")}}. Visual browsers will also hide the broken image icon if the `alt` attribute is empty and the image failed to display. - - This attribute is also used when copying and pasting the image to text, or saving a linked image to a bookmark. - -- `attributionsrc` {{experimental_inline}} - - - : specifies that you want the browser to send an {{httpheader("Attribution-Reporting-Eligible")}} header along with the image request. - - On the server-side this is used to trigger sending an {{httpheader("Attribution-Reporting-Register-Source")}} or {{httpheader("Attribution-Reporting-Register-Trigger")}} header in the response, to register an image-based [attribution source](/en-US/docs/Web/API/Attribution_Reporting_API/Registering_sources#html-based_event_sources) or [attribution trigger](/en-US/docs/Web/API/Attribution_Reporting_API/Registering_triggers#html-based_attribution_triggers), respectively. Which response header should be sent back depends on the value of the `Attribution-Reporting-Eligible` header that triggered the registration. - - The corresponding source or trigger event is set off once the browser receives the response containing the image file. - - > [!NOTE] - > See the [Attribution Reporting API](/en-US/docs/Web/API/Attribution_Reporting_API) for more details. - - There are two versions of this attribute that you can set: - - - Boolean, i.e. just the `attributionsrc` name. This specifies that you want the {{httpheader("Attribution-Reporting-Eligible")}} header sent to the same server as the `src` attribute points to. This is fine when you are handling the attribution source or trigger registration on the same server. When registering an attribution trigger this property is optional, and a boolean value will be used if it is omitted. - - Value containing one or more URLs, for example: - - ```html - <img - src="image-file.png" - alt="My image file description" - attributionsrc="https://a.example/register-source - https://b.example/register-source" /> - ``` - - This is useful in cases where the requested resource is not on a server you control, or you just want to handle registering the attribution source on a different server. In this case, you can specify one or more URLs as the value of `attributionsrc`. When the resource request occurs the {{httpheader("Attribution-Reporting-Eligible")}} header will be sent to the URL(s) specified in `attributionSrc` in addition to the resource origin. These URLs can then respond with a {{httpheader("Attribution-Reporting-Register-Source")}} or {{httpheader("Attribution-Reporting-Register-Trigger")}} header as appropriate to complete registration. - - > [!NOTE] - > Specifying multiple URLs means that multiple attribution sources can be registered on the same feature. You might for example have different campaigns that you are trying to measure the success of, which involve generating different reports on different data. - -- [`crossorigin`](/en-US/docs/Web/HTML/Attributes/crossorigin) - - - : Indicates if the fetching of the image must be done using a {{glossary("CORS")}} request. Image data from a [CORS-enabled image](/en-US/docs/Web/HTML/CORS_enabled_image) returned from a CORS request can be reused in the {{HTMLElement("canvas")}} element without being marked "[tainted](/en-US/docs/Web/HTML/CORS_enabled_image#security_and_tainted_canvases)". - - If the `crossorigin` attribute is _not_ specified, then a non-CORS request is sent (without the {{httpheader("Origin")}} request header), and the browser marks the image as tainted and restricts access to its image data, preventing its usage in {{HTMLElement("canvas")}} elements. - - If the `crossorigin` attribute _is_ specified, then a CORS request is sent (with the {{httpheader("Origin")}} request header); but if the server does not opt into allowing cross-origin access to the image data by the origin site (by not sending any {{httpheader("Access-Control-Allow-Origin")}} response header, or by not including the site's origin in any {{httpheader("Access-Control-Allow-Origin")}} response header it does send), then the browser blocks the image from loading, and logs a CORS error to the devtools console. - - Allowed values: - - - `anonymous` - - : A CORS request is sent with credentials omitted (that is, no {{glossary("cookie", "cookies")}}, [X.509 certificates](https://datatracker.ietf.org/doc/html/rfc5280), or {{httpheader("Authorization")}} request header). - - `use-credentials` - - : The CORS request is sent with any credentials included (that is, cookies, X.509 certificates, and the `Authorization` request header). If the server does not opt into sharing credentials with the origin site (by sending back the `Access-Control-Allow-Credentials: true` response header), then the browser marks the image as tainted and restricts access to its image data. - - If the attribute has an invalid value, browsers handle it as if the `anonymous` value was used. See [CORS settings attributes](/en-US/docs/Web/HTML/Attributes/crossorigin) for additional information. - -- `decoding` - - - : This attribute provides a hint to the browser as to whether it should perform image decoding along with rendering the other DOM content in a single presentation step that looks more "correct" (`sync`), or render and present the other DOM content first and then decode the image and present it later (`async`). In practice, `async` means that the next paint does not wait for the image to decode. - - It is often difficult to perceive any noticeable effect when using `decoding` on static `<img>` elements. They'll likely be initially rendered as empty images while the image files are fetched (either from the network or from the cache) and then handled independently anyway, so the "syncing" of content updates is less apparent. However, the blocking of rendering while decoding happens, while often quite small, _can_ be measured — even if it is difficult to observe with the human eye. See [What does the image decoding attribute actually do?](https://www.tunetheweb.com/blog/what-does-the-image-decoding-attribute-actually-do/) for a more detailed analysis (tunetheweb.com, 2023). - - Using different `decoding` types can result in more noticeable differences when dynamically inserting `<img>` elements into the DOM via JavaScript — see {{domxref("HTMLImageElement.decoding")}} for more details. - - Allowed values: - - - `sync` - - : Decode the image synchronously along with rendering the other DOM content, and present everything together. - - `async` - - : Decode the image asynchronously, after rendering and presenting the other DOM content. - - `auto` - - : No preference for the decoding mode; the browser decides what is best for the user. This is the default value. - -- [`elementtiming`](/en-US/docs/Web/HTML/Attributes/elementtiming) - - - : Marks the image for observation by the {{domxref("PerformanceElementTiming")}} API. The value given becomes an identifier for the observed image element. See also the [`elementtiming`](/en-US/docs/Web/HTML/Attributes/elementtiming) attribute page. - -- `fetchpriority` - - - : Provides a hint of the relative priority to use when fetching the image. - Allowed values: - - - `high` - - : Fetch the image at a high priority relative to other images. - - `low` - - : Fetch the image at a low priority relative to other images. - - `auto` - - : Don't set a preference for the fetch priority. - This is the default. - It is used if no value or an invalid value is set. - - See {{domxref("HTMLImageElement.fetchPriority")}} for more information. - -- `height` - - - : The intrinsic height of the image, in pixels. Must be an integer without a unit. - - > [!NOTE] - > Including `height` and [`width`](#width) enables the {{glossary("aspect ratio")}} of the image to be calculated by the browser prior to the image being loaded. This aspect ratio is used to reserve the space needed to display the image, reducing or even preventing a layout shift when the image is downloaded and painted to the screen. Reducing layout shift is a major component of good user experience and web performance. - -- `ismap` - - - : This Boolean attribute indicates that the image is part of a [server-side map](https://en.wikipedia.org/wiki/Image_map#Server-side). If so, the coordinates where the user clicked on the image are sent to the server. - - > [!NOTE] - > This attribute is allowed only if the `<img>` element is a descendant of an {{htmlelement("a")}} element with a valid [`href`](/en-US/docs/Web/HTML/Element/a#href) attribute. This gives users without pointing devices a fallback destination. - -- `loading` - - - : Indicates how the browser should load the image: - - - `eager` - - : Loads the image immediately, regardless of whether or not the image is currently within the visible viewport (this is the default value). - - `lazy` - - : Defers loading the image until it reaches a calculated distance from the viewport, as defined by the browser. The intent is to avoid the network and storage bandwidth needed to handle the image until it's reasonably certain that it will be needed. This generally improves the performance of the content in most typical use cases. - - > [!NOTE] - > Loading is only deferred when JavaScript is enabled. This is an anti-tracking measure, because if a user agent supported lazy loading when scripting is disabled, it would still be possible for a site to track a user's approximate scroll position throughout a session, by strategically placing images in a page's markup such that a server can track how many images are requested and when. - - > [!NOTE] - > Images with `loading` set to `lazy` will never be loaded if they do not intersect a visible part of an element, even if loading them would change that as unloaded images have a `width` and `height` of `0`. Putting `width` and `height` on lazy-loaded images fixes this issue and is a best practice, [recommended by the specification](https://html.spec.whatwg.org/multipage/embedded-content.html#the-img-element). Doing so also helps prevent layout shifts. - -- `referrerpolicy` - - - : A string indicating which referrer to use when fetching the resource: - - - `no-referrer`: The {{HTTPHeader("Referer")}} header will not be sent. - - `no-referrer-when-downgrade`: The {{HTTPHeader("Referer")}} header will not be sent to {{Glossary("origin")}}s without {{Glossary("TLS")}} ({{Glossary("HTTPS")}}). - - `origin`: The sent referrer will be limited to the origin of the referring page: its [scheme](/en-US/docs/Learn_web_development/Howto/Web_mechanics/What_is_a_URL), {{Glossary("host")}}, and {{Glossary("port")}}. - - `origin-when-cross-origin`: The referrer sent to other origins will be limited to the scheme, the host, and the port. Navigations on the same origin will still include the path. - - `same-origin`: A referrer will be sent for {{Glossary("Same-origin policy", "same origin")}}, but cross-origin requests will contain no referrer information. - - `strict-origin`: Only send the origin of the document as the referrer when the protocol security level stays the same (HTTPS→HTTPS), but don't send it to a less secure destination (HTTPS→HTTP). - - `strict-origin-when-cross-origin` (default): Send a full URL when performing a same-origin request, only send the origin when the protocol security level stays the same (HTTPS→HTTPS), and send no header to a less secure destination (HTTPS→HTTP). - - `unsafe-url`: The referrer will include the origin _and_ the path (but not the [fragment](/en-US/docs/Web/API/HTMLAnchorElement/hash), [password](/en-US/docs/Web/API/HTMLAnchorElement/password), or [username](/en-US/docs/Web/API/HTMLAnchorElement/username)). **This value is unsafe**, because it leaks origins and paths from TLS-protected resources to insecure origins. - -- `sizes` - - - : One or more strings separated by commas, indicating a set of source sizes. Each source size consists of: - - 1. A [media condition](/en-US/docs/Web/CSS/CSS_media_queries/Using_media_queries#syntax). This must be omitted for the last item in the list. - 2. A source size value. - - Media Conditions describe properties of the _viewport_, not of the _image_. For example, `(max-height: 500px) 1000px` proposes to use a source of 1000px width, if the _viewport_ is not higher than 500px. Because a source size descriptor is used to specify the width to use for the image during layout of the page, the media condition is typically (but not necessarily) based on the [width](/en-US/docs/Web/CSS/@media/width) information. - - Source size values specify the intended display size of the image. {{glossary("User agent", "User agents")}} use the current source size to select one of the sources supplied by the `srcset` attribute, when those sources are described using width (`w`) descriptors. The selected source size affects the {{glossary("intrinsic size")}} of the image (the image's display size if no {{glossary("CSS")}} styling is applied). If the `srcset` attribute is absent, or contains no values with a width descriptor, then the `sizes` attribute has no effect. - - A source size value can be any non-negative [length](/en-US/docs/Web/CSS/length). It must not use CSS functions other than the [math functions](/en-US/docs/Web/CSS/CSS_Values_and_Units/CSS_Value_Functions#math_functions). Units are interpreted in the same way as [media queries](/en-US/docs/Web/CSS/CSS_media_queries), meaning that all relative length units are relative to the document root rather than the `<img>` element, so an `em` value is relative to the root font size, rather than the font size of the image. [Percentage](/en-US/docs/Web/CSS/percentage) values are not allowed. - - Additionally, you can use the value `auto` to replace the whole list of sizes or the first entry in the list. It is only valid when combined with `loading="lazy"`, and resolves to the [concrete size](/en-US/docs/Web/CSS/image) of the image. - -- `src` - - : The image {{glossary("URL")}}. Mandatory for the `<img>` element. On {{glossary("Browser", "browsers")}} supporting `srcset`, `src` is treated like a candidate image with a pixel density descriptor `1x`, unless an image with this pixel density descriptor is already defined in `srcset`, or unless `srcset` contains `w` descriptors. -- `srcset` - - - : One or more strings separated by commas, indicating possible image sources for the {{glossary("user agent")}} to use. Each string is composed of: - - 1. A {{glossary("URL")}} to an image - 2. Optionally, whitespace followed by one of: - - - A width descriptor (a positive integer directly followed by `w`). The width descriptor is divided by the source size given in the `sizes` attribute to calculate the effective pixel density. - - A pixel density descriptor (a positive floating point number directly followed by `x`). - - If no descriptor is specified, the source is assigned the default descriptor of `1x`. - - It is incorrect to mix width descriptors and pixel density descriptors in the same `srcset` attribute. Duplicate descriptors (for instance, two sources in the same `srcset` which are both described with `2x`) are also invalid. - - If the `srcset` attribute uses width descriptors, the `sizes` attribute must also be present, or the `srcset` itself will be ignored. - - The user agent selects any of the available sources at its discretion. This provides them with significant leeway to tailor their selection based on things like user preferences or {{glossary("bandwidth")}} conditions. See our [Responsive images](/en-US/docs/Web/HTML/Responsive_images) tutorial for an example. - -- `width` - - : The intrinsic width of the image in pixels. Must be an integer without a unit. -- `usemap` - - - : The partial {{glossary("URL")}} (starting with `#`) of an [image map](/en-US/docs/Web/HTML/Element/map) associated with the element. - - > [!NOTE] - > You cannot use this attribute if the `<img>` element is inside an {{htmlelement("a")}} or {{HTMLElement("button")}} element. - -### Deprecated attributes - -- `align` {{deprecated_inline}} - - - : Aligns the image with its surrounding context. Use the {{cssxref('float')}} and/or {{cssxref('vertical-align')}} {{glossary("CSS")}} properties instead of this attribute. Allowed values: - - - `top` - - : Equivalent to `vertical-align: top` or `vertical-align: text-top` - - `middle` - - : Equivalent to `vertical-align: -moz-middle-with-baseline` - - `bottom` - - : The default, equivalent to `vertical-align: unset` or `vertical-align: initial` - - `left` - - : Equivalent to `float: left` - - `right` - - : Equivalent to `float: right` - -- `border` {{deprecated_inline}} - - : The width of a border around the image. Use the {{cssxref('border')}} {{glossary("CSS")}} property instead. -- `hspace` {{deprecated_inline}} - - : The number of pixels of white space on the left and right of the image. Use the {{cssxref('margin')}} CSS property instead. -- `longdesc` {{deprecated_inline}} - - - : A link to a more detailed description of the image. Possible values are a {{glossary("URL")}} or an element [`id`](/en-US/docs/Web/HTML/Global_attributes/id). - - > [!NOTE] - > This attribute is mentioned in the latest {{glossary("W3C")}} version, [HTML 5.2](https://html.spec.whatwg.org/multipage/obsolete.html#element-attrdef-img-longdesc), but has been removed from the {{glossary("WHATWG")}}'s [HTML Living Standard](https://html.spec.whatwg.org/multipage/embedded-content.html#the-img-element). It has an uncertain future; authors should use a {{glossary("WAI")}}-{{glossary("ARIA")}} alternative such as [`aria-describedby`](https://www.w3.org/TR/wai-aria-1.1/#aria-describedby) or [`aria-details`](https://www.w3.org/TR/wai-aria-1.1/#aria-details). - -- `name` {{deprecated_inline}} - - : A name for the element. Use the [`id`](/en-US/docs/Web/HTML/Global_attributes/id) attribute instead. -- `vspace` {{deprecated_inline}} - - : The number of pixels of white space above and below the image. Use the {{cssxref('margin')}} CSS property instead. - -## Styling with CSS - -`<img>` is a [replaced element](/en-US/docs/Web/CSS/Replaced_element); it has a {{cssxref("display")}} value of `inline` by default, but its default dimensions are defined by the embedded image's intrinsic values, like it were `inline-block`. You can set properties like {{cssxref("border")}}/{{cssxref("border-radius")}}, {{cssxref("padding")}}/{{cssxref("margin")}}, {{cssxref("width")}}, {{cssxref("height")}}, etc. on an image. - -`<img>` has no baseline, so when images are used in an inline formatting context with {{cssxref("vertical-align", "vertical-align: baseline")}}, the bottom of the image will be placed on the text baseline. - -You can use the {{cssxref("object-position")}} property to position the image within the element's box, and the {{cssxref("object-fit")}} property to adjust the sizing of the image within the box (for example, whether the image should fit the box or fill it even if clipping is required). - -Depending on its type, an image may have an intrinsic width and height. For some image types, however, intrinsic dimensions are unnecessary. {{glossary("SVG")}} images, for instance, have no intrinsic dimensions if their root {{SVGElement("svg")}} element doesn't have a `width` or `height` set on it. - -## Accessibility - -### Authoring meaningful alternate descriptions - -An `alt` attribute's value should provide a clear and concise text replacement for the image's content. It should not describe the presence of the image itself or the file name of the image. If the `alt` attribute is purposefully left off because the image has no textual equivalent, consider alternate methods to present what the image is trying to communicate. - -#### Don't - -```html example-bad -<img alt="image" src="penguin.jpg" /> -``` - -#### Do - -```html example-good -<img alt="A Penguin on a beach." src="penguin.jpg" /> -``` - -An important accessibility test is to read the `alt` attribute content together with preceding textual content to see if it conveys the same meaning as the image. For example, if the image was preceded by the sentence "On my travels, I saw a cute little animal:", the _Don't_ example could be read by a screen reader as "On my travels, I saw a cute little animal: image", which doesn't make sense. The _Do_ example could be read by a screen reader as "On my travels, I saw a cute little animal: A Penguin on a beach.", which does make sense. - -For images used to trigger an action, for example, images nested inside an {{htmlelement("a")}} or {{htmlelement("button")}} element, consider describing the triggered action inside the `alt` attribute value. For example, you could write `alt="next page"` instead of `alt="arrow right"`. You could also consider adding an optional further description inside a `title` attribute; this may be read by screen readers if requested by the user. - -When an `alt` attribute is not present on an image, some screen readers may announce the image's file name instead. This can be a confusing experience if the file name isn't representative of the image's contents. - -- [An alt Decision Tree • Images • WAI Web Accessibility Tutorials](https://www.w3.org/WAI/tutorials/images/decision-tree/) -- [Alt-texts: The Ultimate Guide — Axess Lab](https://axesslab.com/alt-texts/) -- [How to Design Great Alt Text: An Introduction | Deque](https://www.deque.com/blog/great-alt-text-introduction/) -- [MDN Understanding WCAG, Guideline 1.1 explanations](/en-US/docs/Web/Accessibility/Understanding_WCAG/Perceivable#guideline_1.1_—_providing_text_alternatives_for_non-text_content) -- [Understanding Success Criterion 1.1.1 | W3C Understanding WCAG 2.0](https://www.w3.org/TR/UNDERSTANDING-WCAG20/text-equiv-all.html) - -### Identifying SVG as an image - -Due to a [VoiceOver bug](https://webkit.org/b/216364), VoiceOver does not correctly announce SVG images as images. Include [`role="img"`](/en-US/docs/Web/Accessibility/ARIA/Roles/img_role) to all `<img>` elements with SVG source files to ensure assistive technologies correctly announce the SVG as image content. - -```html -<img src="mdn.svg" alt="MDN" role="img" /> -``` - -### The title attribute - -The [`title`](/en-US/docs/Web/HTML/Global_attributes/title) attribute is not an acceptable substitute for the `alt` attribute. Additionally, avoid duplicating the `alt` attribute's value in a `title` attribute declared on the same image. Doing so may cause some screen readers to announce the same text twice, creating a confusing experience. - -The `title` attribute should also not be used as supplemental captioning information to accompany an image's `alt` description. If an image needs a caption, use the [`figure`](/en-US/docs/Web/HTML/Element/figure) and [`figcaption`](/en-US/docs/Web/HTML/Element/figcaption) elements. - -The value of the `title` attribute is usually presented to the user as a tooltip, which appears shortly after the cursor stops moving over the image. While this _can_ provide additional information to the user, you should not assume that the user will ever see it: the user may only have keyboard or touchscreen. If you have information that's particularly important or valuable for the user, present it inline using one of the methods mentioned above instead of using `title`. - -- [Using the HTML title attribute – updated | The Paciello Group](https://www.tpgi.com/using-the-html-title-attribute-updated/) - -## Examples - -### Alternative text - -The following example embeds an image into the page and includes alternative text for accessibility. - -```html -<img src="favicon144.png" alt="MDN" /> -``` - -{{ EmbedLiveSample('Alternative_text', '100%', '160') }} - -### Image link - -This example builds upon the previous one, showing how to turn the image into a link. To do so, nest the `<img>` tag inside the {{HTMLElement("a")}}. You should make the alternative text describe the resource the link is pointing to, as if you were using a text link instead. - -```html -<a href="https://developer.mozilla.org"> - <img src="favicon144.png" alt="Visit the MDN site" /> -</a> -``` - -{{ EmbedLiveSample('Image_link', '100%', '160') }} - -### Using the srcset attribute - -In this example we include a `srcset` attribute with a reference to a high-resolution version of the logo; this will be loaded instead of the `src` image on high-resolution devices. The image referenced in the `src` attribute is counted as a `1x` candidate in {{glossary("User agent", "user agents")}} that support `srcset`. - -```html -<img src="favicon72.png" alt="MDN" srcset="favicon144.png 2x" /> -``` - -{{EmbedLiveSample("Using_the_srcset_attribute", "100%", "160")}} - -### Using the srcset and sizes attributes - -The `src` attribute is ignored in {{glossary("User agent", "user agents")}} that support `srcset` when `w` descriptors are included. When the `(max-width: 600px)` media condition matches, the 200 pixel-wide image will load (it is the one that matches `200px` most closely), otherwise the other image will load. - -```html -<img - src="clock-demo-200px.png" - alt="The time is 12:45." - srcset="clock-demo-200px.png 200w, clock-demo-400px.png 400w" - sizes="(max-width: 600px) 200px, 50vw" /> -``` - -{{EmbedLiveSample("Using_the_srcset_and_sizes_attributes", "100%", 350)}} - -> [!NOTE] -> To see the resizing in action, {{LiveSampleLink('Using_the_srcset_and_sizes_attributes', 'view the example on a separate page')}}, so you can actually resize the content area. - -## Security and privacy concerns - -Although `<img>` elements have innocent uses, they can have undesirable consequences for user security and privacy. See [Referer header: privacy and security concerns](/en-US/docs/Web/Security/Referer_header:_privacy_and_security_concerns) for more information and mitigations. - -## Technical summary - -<table class="properties"> - <tbody> - <tr> - <th scope="row"> - <a href="/en-US/docs/Web/HTML/Content_categories" - >Content categories</a - > - </th> - <td> - <a href="/en-US/docs/Web/HTML/Content_categories#flow_content" - >Flow content</a - >, - <a href="/en-US/docs/Web/HTML/Content_categories#phrasing_content" - >phrasing content</a - >, - <a href="/en-US/docs/Web/HTML/Content_categories#embedded_content" - >embedded content</a - >, - <a href="/en-US/docs/Web/HTML/Content_categories#palpable_content" - >palpable content</a - >. If the element has a <code>usemap</code> attribute, it also is a part - of the interactive content category. - </td> - </tr> - <tr> - <th scope="row">Permitted content</th> - <td>None; it is a {{Glossary("void element")}}.</td> - </tr> - <tr> - <th scope="row">Tag omission</th> - <td>Must have a start tag and must not have an end tag.</td> - </tr> - <tr> - <th scope="row">Permitted parents</th> - <td>Any element that accepts embedded content.</td> - </tr> - <tr> - <th scope="row">Implicit ARIA role</th> - <td> - <ul> - <li> - with non-empty <code>alt</code> attribute or no - <code>alt</code> attribute: - <code - ><a href="/en-US/docs/Web/Accessibility/ARIA/Roles/img_role" - ><code>img</code></a - ></code - > - </li> - <li> - with empty <code>alt</code> attribute: - <a href="/en-US/docs/Web/Accessibility/ARIA/Roles/presentation_role" - ><code>presentation</code></a - > - </li> - </ul> - </td> - </tr> - <tr> - <th scope="row">Permitted ARIA roles</th> - <td> - <ul> - <li> - with non-empty <code>alt</code> attribute: - <ul> - <li> - <code - ><a - href="/en-US/docs/Web/Accessibility/ARIA/Roles/button_role" - >button</a - ></code - > - </li> - <li> - <code - ><a - href="/en-US/docs/Web/Accessibility/ARIA/Roles/checkbox_role" - >checkbox</a - ></code - > - </li> - <li><a href="/en-US/docs/Web/Accessibility/ARIA/Roles/link_role"><code>link</code></a></li> - <li><a href="/en-US/docs/Web/Accessibility/ARIA/Roles/menuitem_role"><code>menuitem</code></a></li> - <li><a href="/en-US/docs/Web/Accessibility/ARIA/Roles/menuitemcheckbox_role"><code>menuitemcheckbox</code></a></li> - <li><a href="/en-US/docs/Web/Accessibility/ARIA/Roles/menuitemradio_role"><code>menuitemradio</code></a></li> - <li><a href="/en-US/docs/Web/Accessibility/ARIA/Roles/option_role"><code>option</code></a></li> - <li><a href="/en-US/docs/Web/Accessibility/ARIA/Roles/progressbar_role"><code>progressbar</code></a></li> - <li><a href="/en-US/docs/Web/Accessibility/ARIA/Roles/scrollbar_role"><code>scrollbar</code></a></li> - <li><a href="/en-US/docs/Web/Accessibility/ARIA/Roles/separator_role"><code>separator</code></a></li> - <li><a href="/en-US/docs/Web/Accessibility/ARIA/Roles/slider_role"><code>slider</code></a></li> - <li> - <code - ><a - href="/en-US/docs/Web/Accessibility/ARIA/Roles/switch_role" - >switch</a - ></code - > - </li> - <li> - <code - ><a href="/en-US/docs/Web/Accessibility/ARIA/Roles/tab_role" - >tab</a - ></code - > - </li> - <li><a href="/en-US/docs/Web/Accessibility/ARIA/Roles/treeitem_role"><code>treeitem</code></a></li> - </ul> - </li> - <li> - with empty <code>alt</code> attribute, <a href="/en-US/docs/Web/Accessibility/ARIA/Roles/none_role"><code>none</code></a> - or <a href="/en-US/docs/Web/Accessibility/ARIA/Roles/presentation_role"><code>presentation</code></a> - </li> - <li> - with no <code>alt</code> attribute, no <code>role</code> permitted - </li> - </ul> - </td> - </tr> - <tr> - <th scope="row">DOM interface</th> - <td>{{domxref("HTMLImageElement")}}</td> - </tr> - </tbody> -</table> - -## Specifications - -{{Specifications}} - -## Browser compatibility - -{{Compat}} - -## See also - -- {{HTMLElement("picture")}}, {{HTMLElement("object")}}, and {{HTMLElement("embed")}} elements -- {{cssxref("object-fit")}}, {{cssxref("object-position")}}, {{cssxref("image-orientation")}}, {{cssxref("image-rendering")}}, and {{cssxref("image-resolution")}}: Image-related CSS properties. -- {{domxref("HTMLImageElement")}} interface for this element -- [HTML images](/en-US/docs/Learn_web_development/Core/Structuring_content/HTML_images) -- [Image file type and format guide](/en-US/docs/Web/Media/Guides/Formats/Image_types) -- [Responsive images](/en-US/docs/Web/HTML/Responsive_images) diff --git a/files/en-us/web/html/element/index.md b/files/en-us/web/html/element/index.md deleted file mode 100644 index ee48a90be3a9dcc..000000000000000 --- a/files/en-us/web/html/element/index.md +++ /dev/null @@ -1,259 +0,0 @@ ---- -title: HTML elements reference -slug: Web/HTML/Element -page-type: landing-page ---- - -{{HTMLSidebar("HTML_Elements")}} - -This page lists all the {{Glossary("HTML")}} {{Glossary("Element","elements")}}, which are created using {{Glossary("Tag", "tags")}}. - -They are grouped by function to help you find what you have in mind easily. An alphabetical list of all elements is provided in the sidebar on every element's page as well as this one. - -> [!NOTE] -> For more information about the basics of HTML elements and attributes, see [Anatomy of an HTML element](/en-US/docs/Learn_web_development/Core/Structuring_content/Basic_HTML_syntax#anatomy_of_an_html_element). - -## Main root - -| Element | Description | -| ----------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| {{HTMLElement("html")}} | Represents the root (top-level element) of an HTML document, so it is also referred to as the _root element_. All other elements must be descendants of this element. | - -## Document metadata - -Metadata contains information about the page. This includes information about styles, scripts and data to help software ({{Glossary("search engine", "search engines")}}, {{Glossary("Browser","browsers")}}, etc.) use and render the page. Metadata for styles and scripts may be defined in the page or linked to another file that has the information. - -| Element | Description | -| ------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| {{HTMLElement("base")}} | Specifies the base URL to use for all relative URLs in a document. There can be only one such element in a document. | -| {{HTMLElement("head")}} | Contains machine-readable information (metadata) about the document, like its [title](/en-US/docs/Web/HTML/Element/title), [scripts](/en-US/docs/Web/HTML/Element/script), and [style sheets](/en-US/docs/Web/HTML/Element/style). | -| {{HTMLElement("link")}} | Specifies relationships between the current document and an external resource. This element is most commonly used to link to CSS but is also used to establish site icons (both "favicon" style icons and icons for the home screen and apps on mobile devices) among other things. | -| {{HTMLElement("meta")}} | Represents {{Glossary("Metadata","metadata")}} that cannot be represented by other HTML meta-related elements, like {{HTMLElement("base")}}, {{HTMLElement("link")}}, {{HTMLElement("script")}}, {{HTMLElement("style")}} and {{HTMLElement("title")}}. | -| {{HTMLElement("style")}} | Contains style information for a document or part of a document. It contains CSS, which is applied to the contents of the document containing this element. | -| {{HTMLElement("title")}} | Defines the document's title that is shown in a {{glossary("Browser", "browser")}}'s title bar or a page's tab. It only contains text; HTML tags within the element, if any, are also treated as plain text. | - -## Sectioning root - -| Element | Description | -| ----------------------- | --------------------------------------------------------------------------------------------- | -| {{HTMLElement("body")}} | Represents the content of an HTML document. There can be only one such element in a document. | - -## Content sectioning - -Content sectioning elements allow you to organize the document content into logical pieces. Use the sectioning elements to create a broad outline for your page content, including header and footer navigation, and heading elements to identify sections of content. - -| Element | Description | -| ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| {{HTMLElement("address")}} | Indicates that the enclosed HTML provides contact information for a person or people, or for an organization. | -| {{HTMLElement("article")}} | Represents a self-contained composition in a document, page, application, or site, which is intended to be independently distributable or reusable (e.g., in syndication). Examples include a forum post, a magazine or newspaper article, a blog entry, a product card, a user-submitted comment, an interactive widget or gadget, or any other independent item of content. | -| {{HTMLElement("aside")}} | Represents a portion of a document whose content is only indirectly related to the document's main content. Asides are frequently presented as sidebars or call-out boxes. | -| {{HTMLElement("footer")}} | Represents a footer for its nearest ancestor [sectioning content](/en-US/docs/Web/HTML/Content_categories#sectioning_content) or [sectioning root](/en-US/docs/Web/HTML/Element/Heading_Elements) element. A `<footer>` typically contains information about the author of the section, copyright data, or links to related documents. | -| {{HTMLElement("header")}} | Represents introductory content, typically a group of introductory or navigational aids. It may contain some heading elements but also a logo, a search form, an author name, and other elements. | -| [`<h1>`](/en-US/docs/Web/HTML/Element/Heading_Elements), [`<h2>`](/en-US/docs/Web/HTML/Element/Heading_Elements), [`<h3>`](/en-US/docs/Web/HTML/Element/Heading_Elements), [`<h4>`](/en-US/docs/Web/HTML/Element/Heading_Elements), [`<h5>`](/en-US/docs/Web/HTML/Element/Heading_Elements), [`<h6>`](/en-US/docs/Web/HTML/Element/Heading_Elements) | Represent six levels of section headings. `<h1>` is the highest section level and `<h6>` is the lowest. | -| {{HTMLElement("hgroup")}} | Represents a heading grouped with any secondary content, such as subheadings, an alternative title, or a tagline. | -| {{HTMLElement("main")}} | Represents the dominant content of the body of a document. The main content area consists of content that is directly related to or expands upon the central topic of a document, or the central functionality of an application. | -| {{HTMLElement("nav")}} | Represents a section of a page whose purpose is to provide navigation links, either within the current document or to other documents. Common examples of navigation sections are menus, tables of contents, and indexes. | -| {{HTMLElement("section")}} | Represents a generic standalone section of a document, which doesn't have a more specific semantic element to represent it. Sections should always have a heading, with very few exceptions. | -| {{HTMLElement("search")}} | Represents a part that contains a set of form controls or other content related to performing a search or filtering operation. | - -## Text content - -Use HTML text content elements to organize blocks or sections of content placed between the opening {{HTMLElement("body")}} and closing `</body>` tags. Important for {{Glossary("accessibility")}} and {{Glossary("SEO")}}, these elements identify the purpose or structure of that content. - -| Element | Description | -| ----------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| {{HTMLElement("blockquote")}} | Indicates that the enclosed text is an extended quotation. Usually, this is rendered visually by indentation. A URL for the source of the quotation may be given using the `cite` attribute, while a text representation of the source can be given using the {{HTMLElement("cite")}} element. | -| {{HTMLElement("dd")}} | Provides the description, definition, or value for the preceding term ({{HTMLElement("dt")}}) in a description list ({{HTMLElement("dl")}}). | -| {{HTMLElement("div")}} | The generic container for flow content. It has no effect on the content or layout until styled in some way using CSS (e.g., styling is directly applied to it, or some kind of layout model like {{glossary("Flexbox", "flexbox")}} is applied to its parent element). | -| {{HTMLElement("dl")}} | Represents a description list. The element encloses a list of groups of terms (specified using the {{HTMLElement("dt")}} element) and descriptions (provided by {{HTMLElement("dd")}} elements). Common uses for this element are to implement a glossary or to display metadata (a list of key-value pairs). | -| {{HTMLElement("dt")}} | Specifies a term in a description or definition list, and as such must be used inside a {{HTMLElement("dl")}} element. It is usually followed by a {{HTMLElement("dd")}} element; however, multiple `<dt>` elements in a row indicate several terms that are all defined by the immediate next {{HTMLElement("dd")}} element. | -| {{HTMLElement("figcaption")}} | Represents a caption or legend describing the rest of the contents of its parent {{HTMLElement("figure")}} element. | -| {{HTMLElement("figure")}} | Represents self-contained content, potentially with an optional caption, which is specified using the {{HTMLElement("figcaption")}} element. The figure, its caption, and its contents are referenced as a single unit. | -| {{HTMLElement("hr")}} | Represents a thematic break between paragraph-level elements: for example, a change of scene in a story, or a shift of topic within a section. | -| {{HTMLElement("li")}} | Represents an item in a list. It must be contained in a parent element: an ordered list ({{HTMLElement("ol")}}), an unordered list ({{HTMLElement("ul")}}), or a menu ({{HTMLElement("menu")}}). In menus and unordered lists, list items are usually displayed using bullet points. In ordered lists, they are usually displayed with an ascending counter on the left, such as a number or letter. | -| {{HTMLElement("menu")}} | A semantic alternative to {{HTMLElement("ul")}}, but treated by browsers (and exposed through the accessibility tree) as no different than {{HTMLElement("ul")}}. It represents an unordered list of items (which are represented by {{HTMLElement("li")}} elements). | -| {{HTMLElement("ol")}} | Represents an ordered list of items — typically rendered as a numbered list. | -| {{HTMLElement("p")}} | Represents a paragraph. Paragraphs are usually represented in visual media as blocks of text separated from adjacent blocks by blank lines and/or first-line indentation, but HTML paragraphs can be any structural grouping of related content, such as images or form fields. | -| {{HTMLElement("pre")}} | Represents preformatted text which is to be presented exactly as written in the HTML file. The text is typically rendered using a non-proportional, or [monospaced](https://en.wikipedia.org/wiki/Monospaced_font), font. Whitespace inside this element is displayed as written. | -| {{HTMLElement("ul")}} | Represents an unordered list of items, typically rendered as a bulleted list. | - -## Inline text semantics - -Use the HTML inline text semantic to define the meaning, structure, or style of a word, line, or any arbitrary piece of text. - -| Element | Description | -| ------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| {{HTMLElement("a")}} | Together with its `href` attribute, creates a hyperlink to web pages, files, email addresses, locations within the current page, or anything else a URL can address. | -| {{HTMLElement("abbr")}} | Represents an abbreviation or acronym. | -| {{HTMLElement("b")}} | Used to draw the reader's attention to the element's contents, which are not otherwise granted special importance. This was formerly known as the Boldface element, and most browsers still draw the text in boldface. However, you should not use `<b>` for styling text or granting importance. If you wish to create boldface text, you should use the CSS {{cssxref("font-weight")}} property. If you wish to indicate an element is of special importance, you should use the {{HTMLElement("strong")}} element. | -| {{HTMLElement("bdi")}} | Tells the browser's bidirectional algorithm to treat the text it contains in isolation from its surrounding text. It's particularly useful when a website dynamically inserts some text and doesn't know the directionality of the text being inserted. | -| {{HTMLElement("bdo")}} | Overrides the current directionality of text, so that the text within is rendered in a different direction. | -| {{HTMLElement("br")}} | Produces a line break in text (carriage-return). It is useful for writing a poem or an address, where the division of lines is significant. | -| {{HTMLElement("cite")}} | Used to mark up the title of a cited creative work. The reference may be in an abbreviated form according to context-appropriate conventions related to citation metadata. | -| {{HTMLElement("code")}} | Displays its contents styled in a fashion intended to indicate that the text is a short fragment of computer code. By default, the content text is displayed using the user agent's default monospace font. | -| {{HTMLElement("data")}} | Links a given piece of content with a machine-readable translation. If the content is time- or date-related, the `<time>` element must be used. | -| {{HTMLElement("dfn")}} | Used to indicate the term being defined within the context of a definition phrase or sentence. The ancestor {{HTMLElement("p")}} element, the {{HTMLElement("dt")}}/{{HTMLElement("dd")}} pairing, or the nearest section ancestor of the `<dfn>` element, is considered to be the definition of the term. | -| {{HTMLElement("em")}} | Marks text that has stress emphasis. The `<em>` element can be nested, with each nesting level indicating a greater degree of emphasis. | -| {{HTMLElement("i")}} | Represents a range of text that is set off from the normal text for some reason, such as idiomatic text, technical terms, and taxonomical designations, among others. Historically, these have been presented using italicized type, which is the original source of the `<i>` naming of this element. | -| {{HTMLElement("kbd")}} | Represents a span of inline text denoting textual user input from a keyboard, voice input, or any other text entry device. By convention, the user agent defaults to rendering the contents of a `<kbd>` element using its default monospace font, although this is not mandated by the HTML standard. | -| {{HTMLElement("mark")}} | Represents text which is marked or highlighted for reference or notation purposes due to the marked passage's relevance in the enclosing context. | -| {{HTMLElement("q")}} | Indicates that the enclosed text is a short inline quotation. Most modern browsers implement this by surrounding the text in quotation marks. This element is intended for short quotations that don't require paragraph breaks; for long quotations use the {{HTMLElement("blockquote")}} element. | -| {{HTMLElement("rp")}} | Used to provide fall-back parentheses for browsers that do not support the display of ruby annotations using the {{HTMLElement("ruby")}} element. One `<rp>` element should enclose each of the opening and closing parentheses that wrap the {{HTMLElement("rt")}} element that contains the annotation's text. | -| {{HTMLElement("rt")}} | Specifies the ruby text component of a ruby annotation, which is used to provide pronunciation, translation, or transliteration information for East Asian typography. The `<rt>` element must always be contained within a {{HTMLElement("ruby")}} element. | -| {{HTMLElement("ruby")}} | Represents small annotations that are rendered above, below, or next to base text, usually used for showing the pronunciation of East Asian characters. It can also be used for annotating other kinds of text, but this usage is less common. | -| {{HTMLElement("s")}} | Renders text with a strikethrough, or a line through it. Use the `<s>` element to represent things that are no longer relevant or no longer accurate. However, `<s>` is not appropriate when indicating document edits; for that, use the {{HTMLElement("del")}} and {{HTMLElement("ins")}} elements, as appropriate. | -| {{HTMLElement("samp")}} | Used to enclose inline text which represents sample (or quoted) output from a computer program. Its contents are typically rendered using the browser's default monospaced font (such as [Courier](<https://en.wikipedia.org/wiki/Courier_(typeface)>) or Lucida Console). | -| {{HTMLElement("small")}} | Represents side-comments and small print, like copyright and legal text, independent of its styled presentation. By default, it renders text within it one font size smaller, such as from `small` to `x-small`. | -| {{HTMLElement("span")}} | A generic inline container for phrasing content, which does not inherently represent anything. It can be used to group elements for styling purposes (using the `class` or `id` attributes), or because they share attribute values, such as `lang`. It should be used only when no other semantic element is appropriate. `<span>` is very much like a div element, but div is a [block-level element](/en-US/docs/Glossary/Block-level_content) whereas a `<span>` is an [inline-level element](/en-US/docs/Glossary/Inline-level_content). | -| {{HTMLElement("strong")}} | Indicates that its contents have strong importance, seriousness, or urgency. Browsers typically render the contents in bold type. | -| {{HTMLElement("sub")}} | Specifies inline text which should be displayed as subscript for solely typographical reasons. Subscripts are typically rendered with a lowered baseline using smaller text. | -| {{HTMLElement("sup")}} | Specifies inline text which is to be displayed as superscript for solely typographical reasons. Superscripts are usually rendered with a raised baseline using smaller text. | -| {{HTMLElement("time")}} | Represents a specific period in time. It may include the `datetime` attribute to translate dates into machine-readable format, allowing for better search engine results or custom features such as reminders. | -| {{HTMLElement("u")}} | Represents a span of inline text which should be rendered in a way that indicates that it has a non-textual annotation. This is rendered by default as a single solid underline but may be altered using CSS. | -| {{HTMLElement("var")}} | Represents the name of a variable in a mathematical expression or a programming context. It's typically presented using an italicized version of the current typeface, although that behavior is browser-dependent. | -| {{HTMLElement("wbr")}} | Represents a word break opportunity—a position within text where the browser may optionally break a line, though its line-breaking rules would not otherwise create a break at that location. | - -## Image and multimedia - -HTML supports various multimedia resources such as images, audio, and video. - -| Element | Description | -| ------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| {{HTMLElement("area")}} | Defines an area inside an image map that has predefined clickable areas. An _image map_ allows geometric areas on an image to be associated with {{Glossary("Hyperlink", "hyperlink")}}. | -| {{HTMLElement("audio")}} | Used to embed sound content in documents. It may contain one or more audio sources, represented using the `src` attribute or the source element: the browser will choose the most suitable one. It can also be the destination for streamed media, using a {{domxref("MediaStream")}}. | -| {{HTMLElement("img")}} | Embeds an image into the document. | -| {{HTMLElement("map")}} | Used with {{HTMLElement("area")}} elements to define an image map (a clickable link area). | -| {{HTMLElement("track")}} | Used as a child of the media elements, audio and video. It lets you specify timed text tracks (or time-based data), for example to automatically handle subtitles. The tracks are formatted in [WebVTT format](/en-US/docs/Web/API/WebVTT_API) (`.vtt` files)—Web Video Text Tracks. | -| {{HTMLElement("video")}} | Embeds a media player which supports video playback into the document. You can also use `<video>` for audio content, but the audio element may provide a more appropriate user experience. | - -## Embedded content - -In addition to regular multimedia content, HTML can include a variety of other content, even if it's not always easy to interact with. - -| Element | Description | -| ------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| {{HTMLElement("embed")}} | Embeds external content at the specified point in the document. This content is provided by an external application or other source of interactive content such as a browser plug-in. | -| {{HTMLElement("fencedframe")}} | Represents a nested browsing context, like `<iframe>` but with more native privacy features built in. | -| {{HTMLElement("iframe")}} | Represents a nested browsing context, embedding another HTML page into the current one. | -| {{HTMLElement("object")}} | Represents an external resource, which can be treated as an image, a nested browsing context, or a resource to be handled by a plugin. | -| {{HTMLElement("picture")}} | Contains zero or more {{HTMLElement("source")}} elements and one {{HTMLElement("img")}} element to offer alternative versions of an image for different display/device scenarios. | -| {{HTMLElement("source")}} | Specifies multiple media resources for the picture, the audio element, or the video element. It is a void element, meaning that it has no content and does not have a closing tag. It is commonly used to offer the same media content in multiple file formats in order to provide compatibility with a broad range of browsers given their differing support for [image file formats](/en-US/docs/Web/Media/Guides/Formats/Image_types) and [media file formats](/en-US/docs/Web/Media/Guides/Formats). | - -## SVG and MathML - -You can embed [SVG](/en-US/docs/Web/SVG) and [MathML](/en-US/docs/Web/MathML) content directly into HTML documents, using the {{SVGElement("svg")}} and {{MathMLElement("math")}} elements. - -| Element | Description | -| ------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| {{SVGElement("svg")}} | Container defining a new coordinate system and [viewport](/en-US/docs/Web/SVG/Attribute/viewBox). It is used as the outermost element of SVG documents, but it can also be used to embed an SVG fragment inside an SVG or HTML document. | -| {{MathMLElement("math")}} | The top-level element in MathML. Every valid MathML instance must be wrapped in it. In addition, you must not nest a second `<math>` element in another, but you can have an arbitrary number of other child elements in it. | - -## Scripting - -To create dynamic content and Web applications, HTML supports the use of scripting languages, most prominently JavaScript. Certain elements support this capability. - -| Element | Description | -| --------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -| {{HTMLElement("canvas")}} | Container element to use with either the [canvas scripting API](/en-US/docs/Web/API/Canvas_API) or the [WebGL API](/en-US/docs/Web/API/WebGL_API) to draw graphics and animations. | -| {{HTMLElement("noscript")}} | Defines a section of HTML to be inserted if a script type on the page is unsupported or if scripting is currently turned off in the browser. | -| {{HTMLElement("script")}} | Used to embed executable code or data; this is typically used to embed or refer to JavaScript code. The `<script>` element can also be used with other languages, such as [WebGL](/en-US/docs/Web/API/WebGL_API)'s GLSL shader programming language and [JSON](/en-US/docs/Glossary/JSON). | - -## Demarcating edits - -These elements let you provide indications that specific parts of the text have been altered. - -| Element | Description | -| ---------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| {{HTMLElement("del")}} | Represents a range of text that has been deleted from a document. This can be used when rendering "track changes" or source code diff information, for example. The `<ins>` element can be used for the opposite purpose: to indicate text that has been added to the document. | -| {{HTMLElement("ins")}} | Represents a range of text that has been added to a document. You can use the `<del>` element to similarly represent a range of text that has been deleted from the document. | - -## Table content - -The elements here are used to create and handle tabular data. - -| Element | Description | -| --------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| {{HTMLElement("caption")}} | Specifies the caption (or title) of a table. | -| {{HTMLElement("col")}} | Defines one or more columns in a column group represented by its implicit or explicit parent {{HTMLElement("colgroup")}} element. The `<col>` element is only valid as a child of a {{HTMLElement("colgroup")}} element that has no [`span`](/en-US/docs/Web/HTML/Element/colgroup#span) attribute defined. | -| {{HTMLElement("colgroup")}} | Defines a group of columns within a table. | -| {{HTMLElement("table")}} | Represents tabular data—that is, information presented in a two-dimensional table comprised of rows and columns of cells containing data. | -| {{HTMLElement("tbody")}} | Encapsulates a set of table rows ({{HTMLElement("tr")}} elements), indicating that they comprise the body of a table's (main) data. | -| {{HTMLElement("td")}} | A child of the {{HTMLElement("tr")}} element, it defines a cell of a table that contains data. | -| {{HTMLElement("tfoot")}} | Encapsulates a set of table rows ({{HTMLElement("tr")}} elements), indicating that they comprise the foot of a table with information about the table's columns. This is usually a summary of the columns, e.g., a sum of the given numbers in a column. | -| {{HTMLElement("th")}} | A child of the {{HTMLElement("tr")}} element, it defines a cell as the header of a group of table cells. The nature of this group can be explicitly defined by the [`scope`](/en-US/docs/Web/HTML/Element/th#scope) and [`headers`](/en-US/docs/Web/HTML/Element/th#headers) attributes. | -| {{HTMLElement("thead")}} | Encapsulates a set of table rows ({{HTMLElement("tr")}} elements), indicating that they comprise the head of a table with information about the table's columns. This is usually in the form of column headers ({{HTMLElement("th")}} elements). | -| {{HTMLElement("tr")}} | Defines a row of cells in a table. The row's cells can then be established using a mix of {{HTMLElement("td")}} (data cell) and {{HTMLElement("th")}} (header cell) elements. | - -## Forms - -HTML provides several elements that can be used together to create forms that the user can fill out and submit to the website or application. Further information about this available in the [HTML forms guide](/en-US/docs/Learn_web_development/Extensions/Forms). - -| Element | Description | -| --------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| {{HTMLElement("button")}} | An interactive element activated by a user with a mouse, keyboard, finger, voice command, or other assistive technology. Once activated, it performs an action, such as submitting a [form](/en-US/docs/Learn_web_development/Extensions/Forms) or opening a dialog. | -| {{HTMLElement("datalist")}} | Contains a set of {{HTMLElement("option")}} elements that represent the permissible or recommended options available to choose from within other controls. | -| {{HTMLElement("fieldset")}} | Used to group several controls as well as labels ({{HTMLElement("label")}}) within a web form. | -| {{HTMLElement("form")}} | Represents a document section containing interactive controls for submitting information. | -| {{HTMLElement("input")}} | Used to create interactive controls for web-based forms to accept data from the user; a wide variety of types of input data and control widgets are available, depending on the device and user agent. The `<input>` element is one of the most powerful and complex in all of HTML due to the sheer number of combinations of input types and attributes. | -| {{HTMLElement("label")}} | Represents a caption for an item in a user interface. | -| {{HTMLElement("legend")}} | Represents a caption for the content of its parent {{HTMLElement("fieldset")}}. | -| {{HTMLElement("meter")}} | Represents either a scalar value within a known range or a fractional value. | -| {{HTMLElement("optgroup")}} | Creates a grouping of options within a {{HTMLElement("select")}} element. | -| {{HTMLElement("option")}} | Used to define an item contained in a select, an {{HTMLElement("optgroup")}}, or a {{HTMLElement("datalist")}} element. As such, `<option>` can represent menu items in popups and other lists of items in an HTML document. | -| {{HTMLElement("output")}} | Container element into which a site or app can inject the results of a calculation or the outcome of a user action. | -| {{HTMLElement("progress")}} | Displays an indicator showing the completion progress of a task, typically displayed as a progress bar. | -| {{HTMLElement("select")}} | Represents a control that provides a menu of options. | -| {{HTMLElement("textarea")}} | Represents a multi-line plain-text editing control, useful when you want to allow users to enter a sizeable amount of free-form text, for example, a comment on a review or feedback form. | - -## Interactive elements - -HTML offers a selection of elements that help to create interactive user interface objects. - -| Element | Description | -| -------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| {{HTMLElement("details")}} | Creates a disclosure widget in which information is visible only when the widget is toggled into an "open" state. A summary or label must be provided using the {{HTMLElement("summary")}} element. | -| {{HTMLElement("dialog")}} | Represents a dialog box or other interactive component, such as a dismissible alert, inspector, or subwindow. | -| {{HTMLElement("summary")}} | Specifies a summary, caption, or legend for a details element's disclosure box. Clicking the `<summary>` element toggles the state of the parent {{HTMLElement("details")}} element open and closed. | - -## Web Components - -Web Components is an HTML-related technology that makes it possible to, essentially, create and use custom elements as if it were regular HTML. In addition, you can create custom versions of standard HTML elements. - -| Element | Description | -| --------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| {{HTMLElement("slot")}} | Part of the [Web Components](/en-US/docs/Web/API/Web_components) technology suite, this element is a placeholder inside a web component that you can fill with your own markup, which lets you create separate DOM trees and present them together. | -| {{HTMLElement("template")}} | A mechanism for holding HTML that is not to be rendered immediately when a page is loaded but may be instantiated subsequently during runtime using JavaScript. | - -## Obsolete and deprecated elements - -> [!WARNING] -> These are old HTML elements that are deprecated and should not be used. **You should never use them in new projects, and you should replace them in old projects as soon as you can.** They are listed here for completeness only. - -| Element | Description | -| ---------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| {{HTMLElement("acronym")}} | Allows authors to clearly indicate a sequence of characters that compose an acronym or abbreviation for a word. | -| {{HTMLElement("big")}} | Renders the enclosed text at a font size one level larger than the surrounding text (`medium` becomes `large`, for example). The size is capped at the browser's maximum permitted font size. | -| {{HTMLElement("center")}} | Displays its block-level or inline contents centered horizontally within its containing element. | -| `<content>` | An obsolete part of the [Web Components](/en-US/docs/Web/API/Web_components) suite of technologies—was used inside of [Shadow DOM](/en-US/docs/Web/API/Web_components/Using_shadow_DOM) as an insertion point, and wasn't meant to be used in ordinary HTML. It has now been replaced by the {{HTMLElement("slot")}} element, which creates a point in the DOM at which a shadow DOM can be inserted. Consider using {{HTMLElement("slot")}} instead. | -| {{HTMLElement("dir")}} | Container for a directory of files and/or folders, potentially with styles and icons applied by the user agent. Do not use this obsolete element; instead, you should use the {{HTMLElement("ul")}} element for lists, including lists of files. | -| {{HTMLElement("font")}} | Defines the font size, color and face for its content. | -| {{HTMLElement("frame")}} | Defines a particular area in which another HTML document can be displayed. A frame should be used within a {{HTMLElement("frameset")}}. | -| {{HTMLElement("frameset")}} | Used to contain {{HTMLElement("frame")}} elements. | -| `<image>` | An ancient and poorly supported precursor to the {{HTMLElement("img")}} element. It should not be used. | -| {{HTMLElement("marquee")}} | Used to insert a scrolling area of text. You can control what happens when the text reaches the edges of its content area using its attributes. | -| `<menuitem>` | Represents a command that a user is able to invoke through a popup menu. This includes context menus, as well as menus that might be attached to a menu button. | -| {{HTMLElement("nobr")}} | Prevents the text it contains from automatically wrapping across multiple lines, potentially resulting in the user having to scroll horizontally to see the entire width of the text. | -| {{HTMLElement("noembed")}} | An obsolete, non-standard way to provide alternative, or "fallback", content for browsers that do not support the embed element or do not support the type of [embedded content](/en-US/docs/Web/HTML/Content_categories#embedded_content) an author wishes to use. This element was deprecated in HTML 4.01 and above in favor of placing fallback content between the opening and closing tags of an {{HTMLElement("object")}} element. | -| {{HTMLElement("noframes")}} | Provides content to be presented in browsers that don't support (or have disabled support for) the {{HTMLElement("frame")}} element. Although most commonly-used browsers support frames, there are exceptions, including certain special-use browsers including some mobile browsers, as well as text-mode browsers. | -| {{HTMLElement("param")}} | Defines parameters for an {{HTMLElement("object")}} element. | -| {{HTMLElement("plaintext")}} | Renders everything following the start tag as raw text, ignoring any following HTML. There is no closing tag, since everything after it is considered raw text. | -| {{HTMLElement("rb")}} | Used to delimit the base text component of a ruby annotation, i.e. the text that is being annotated. One `<rb>` element should wrap each separate atomic segment of the base text. | -| {{HTMLElement("rtc")}} | Embraces semantic annotations of characters presented in a ruby of {{HTMLElement("rb")}} elements used inside of {{HTMLElement("ruby")}} element. {{HTMLElement("rb")}} elements can have both pronunciation ({{HTMLElement("rt")}}) and semantic ({{HTMLElement("rtc")}}) annotations. | -| `<shadow>` | An obsolete part of the [Web Components](/en-US/docs/Web/API/Web_components) technology suite that was intended to be used as a shadow DOM insertion point. You might have used it if you have created multiple shadow roots under a shadow host. Consider using {{HTMLElement("slot")}} instead. | -| {{HTMLElement("strike")}} | Places a strikethrough (horizontal line) over text. | -| {{HTMLElement("tt")}} | Creates inline text which is presented using the user agent default monospace font face. This element was created for the purpose of rendering text as it would be displayed on a fixed-width display such as a teletype, text-only screen, or line printer. | -| {{HTMLElement("xmp")}} | Renders text between the start and end tags without interpreting the HTML in between and using a monospaced font. The HTML2 specification recommended that it should be rendered wide enough to allow 80 characters per line. | - -## See also - -- {{DOMXref("Element")}} interface diff --git a/files/en-us/web/html/element/input/button/index.md b/files/en-us/web/html/element/input/button/index.md deleted file mode 100644 index bbe284ff1a5fea8..000000000000000 --- a/files/en-us/web/html/element/input/button/index.md +++ /dev/null @@ -1,391 +0,0 @@ ---- -title: <input type="button"> -slug: Web/HTML/Element/input/button -page-type: html-element -browser-compat: html.elements.input.type_button ---- - -{{HTMLSidebar}} - -{{HTMLElement("input")}} elements of type **`button`** are rendered as simple push buttons, which can be programmed to control custom functionality anywhere on a webpage as required when assigned an event handler function (typically for the {{domxref("Element/click_event", "click")}} event). - -{{InteractiveExample("HTML Demo: &lt;input type=&quot;button&quot;&gt;", "tabbed-shorter")}} - -```html interactive-example -<input class="styled" type="button" value="Add to favorites" /> -``` - -```css interactive-example -.styled { - border: 0; - line-height: 2.5; - padding: 0 20px; - font-size: 1rem; - text-align: center; - color: #fff; - text-shadow: 1px 1px 1px #000; - border-radius: 10px; - background-color: rgb(220 0 0 / 100%); - background-image: linear-gradient( - to top left, - rgb(0 0 0 / 20%), - rgb(0 0 0 / 20%) 30%, - rgb(0 0 0 / 0%) - ); - box-shadow: - inset 2px 2px 3px rgb(255 255 255 / 60%), - inset -2px -2px 3px rgb(0 0 0 / 60%); -} - -.styled:hover { - background-color: rgb(255 0 0 / 100%); -} - -.styled:active { - box-shadow: - inset -2px -2px 3px rgb(255 255 255 / 60%), - inset 2px 2px 3px rgb(0 0 0 / 60%); -} -``` - -> [!NOTE] -> While `<input>` elements of type `button` are still perfectly valid HTML, the newer {{HTMLElement("button")}} element is now the favored way to create buttons. Given that a {{HTMLElement("button")}}'s label text is inserted between the opening and closing tags, you can include HTML in the label, even images. - -## Value - -### Button with a value - -An `<input type="button">` elements' [`value`](/en-US/docs/Web/HTML/Element/input#value) attribute contains a string that is used as the button's label. The `value` provides the {{glossary("accessible description")}} for the button. - -```html -<input type="button" value="Click Me" /> -``` - -{{EmbedLiveSample("Button_with_a_value", 650, 30)}} - -### Button without a value - -If you don't specify a `value`, you get an empty button: - -```html -<input type="button" /> -``` - -{{EmbedLiveSample("Button_without_a_value", 650, 30)}} - -## Using buttons - -`<input type="button">` elements have no default behavior (their cousins, `<input type="submit">` and [`<input type="reset">`](/en-US/docs/Web/HTML/Element/input/reset) are used to submit and reset forms, respectively). To make buttons do anything, you have to write JavaScript code to do the work. - -### A basic button - -We'll begin by creating a basic button with a {{domxref("Element/click_event", "click")}} event handler that starts our machine (well, it toggles the `value` of the button and the text content of the following paragraph): - -```html -<form> - <input type="button" value="Start machine" /> -</form> -<p>The machine is stopped.</p> -``` - -```js -const button = document.querySelector("input"); -const paragraph = document.querySelector("p"); - -button.addEventListener("click", updateButton); - -function updateButton() { - if (button.value === "Start machine") { - button.value = "Stop machine"; - paragraph.textContent = "The machine has started!"; - } else { - button.value = "Start machine"; - paragraph.textContent = "The machine is stopped."; - } -} -``` - -The script gets a reference to the {{domxref("HTMLInputElement")}} object representing the `<input>` in the DOM, saving this reference in the variable `button`. {{domxref("EventTarget.addEventListener", "addEventListener()")}} is then used to establish a function that will be run when {{domxref("Element/click_event", "click")}} events occur on the button. - -{{EmbedLiveSample("A_basic_button", 650, 100)}} - -### Adding keyboard shortcuts to buttons - -Keyboard shortcuts, also known as access keys and keyboard equivalents, let the user trigger a button using a key or combination of keys on the keyboard. To add a keyboard shortcut to a button — just as you would with any {{HTMLElement("input")}} for which it makes sense — you use the [`accesskey`](/en-US/docs/Web/HTML/Global_attributes/accesskey) global attribute. - -In this example, <kbd>s</kbd> is specified as the access key (you'll need to press <kbd>s</kbd> plus the particular modifier keys for your browser/OS combination; see [accesskey](/en-US/docs/Web/HTML/Global_attributes/accesskey) for a useful list of those). - -```html -<form> - <input type="button" value="Start machine" accesskey="s" /> -</form> -<p>The machine is stopped.</p> -``` - -```js hidden -const button = document.querySelector("input"); -const paragraph = document.querySelector("p"); - -button.addEventListener("click", updateButton); - -function updateButton() { - if (button.value === "Start machine") { - button.value = "Stop machine"; - paragraph.textContent = "The machine has started!"; - } else { - button.value = "Start machine"; - paragraph.textContent = "The machine is stopped."; - } -} -``` - -{{EmbedLiveSample("Adding_keyboard_shortcuts_to_buttons", 650, 100)}} - -> [!NOTE] -> The problem with the above example of course is that the user will not know what the access key is! In a real site, you'd have to provide this information in a way that doesn't interfere with the site design (for example by providing an easily accessible link that points to information on what the site access keys are). - -### Disabling and enabling a button - -To disable a button, specify the [`disabled`](/en-US/docs/Web/HTML/Attributes/disabled) global attribute on it, like so: - -```html -<input type="button" value="Disable me" disabled /> -``` - -#### Setting the disabled attribute - -You can enable and disable buttons at run time by setting `disabled` to `true` or `false`. In this example our button starts off enabled, but if you press it, it is disabled using `button.disabled = true`. A {{domxref("Window.setTimeout", "setTimeout()")}} function is then used to reset the button back to its enabled state after two seconds. - -```html -<input type="button" value="Enabled" /> -``` - -```js -const button = document.querySelector("input"); - -button.addEventListener("click", disableButton); - -function disableButton() { - button.disabled = true; - button.value = "Disabled"; - setTimeout(() => { - button.disabled = false; - button.value = "Enabled"; - }, 2000); -} -``` - -{{EmbedLiveSample("Setting_the_disabled_attribute", 650, 60)}} - -#### Inheriting the disabled state - -If the `disabled` attribute isn't specified, the button inherits its `disabled` state from its parent element. This makes it possible to enable and disable groups of elements all at once by enclosing them in a container such as a {{HTMLElement("fieldset")}} element, and then setting `disabled` on the container. - -The example below shows this in action. This is very similar to the previous example, except that the `disabled` attribute is set on the `<fieldset>` when the first button is pressed — this causes all three buttons to be disabled until the two second timeout has passed. - -```html -<fieldset> - <legend>Button group</legend> - <input type="button" value="Button 1" /> - <input type="button" value="Button 2" /> - <input type="button" value="Button 3" /> -</fieldset> -``` - -```js -const button = document.querySelector("input"); -const fieldset = document.querySelector("fieldset"); - -button.addEventListener("click", disableButton); - -function disableButton() { - fieldset.disabled = true; - setTimeout(() => { - fieldset.disabled = false; - }, 2000); -} -``` - -{{EmbedLiveSample("Inheriting_the_disabled_state", 650, 100)}} - -> [!NOTE] -> Unlike other browsers, Firefox persists the `disabled` state of an `<input>` element even after the page is reloaded. As a workaround, set the `<input>` element's [`autocomplete`](/en-US/docs/Web/HTML/Element/input#autocomplete) attribute to `off`. (See [Firefox bug 654072](https://bugzil.la/654072) for more details.) - -## Validation - -Buttons don't participate in constraint validation; they have no real value to be constrained. - -## Examples - -The below example shows a very simple drawing app created using a {{htmlelement("canvas")}} element and some CSS and JavaScript (we'll hide the CSS for brevity). The top two controls allow you to choose the color and size of the drawing pen. The button, when clicked, invokes a function that clears the canvas. - -```html -<div class="toolbar"> - <input type="color" aria-label="select pen color" /> - <input - type="range" - min="2" - max="50" - value="30" - aria-label="select pen size" /><span class="output">30</span> - <input type="button" value="Clear canvas" /> -</div> - -<canvas class="myCanvas"> - <p>Add suitable fallback here.</p> -</canvas> -``` - -```css hidden -body { - background: #ccc; - margin: 0; - overflow: hidden; -} - -.toolbar { - background: #ccc; - width: 150px; - height: 75px; - padding: 5px; -} - -input[type="color"], -input[type="button"] { - width: 90%; - margin: 0 auto; - display: block; -} - -input[type="range"] { - width: 70%; -} - -span { - position: relative; - bottom: 5px; -} -``` - -```js -const canvas = document.querySelector(".myCanvas"); -const width = (canvas.width = window.innerWidth); -const height = (canvas.height = window.innerHeight - 85); -const ctx = canvas.getContext("2d"); - -ctx.fillStyle = "rgb(0 0 0)"; -ctx.fillRect(0, 0, width, height); - -const colorPicker = document.querySelector('input[type="color"]'); -const sizePicker = document.querySelector('input[type="range"]'); -const output = document.querySelector(".output"); -const clearBtn = document.querySelector('input[type="button"]'); - -// covert degrees to radians -function degToRad(degrees) { - return (degrees * Math.PI) / 180; -} - -// update size picker output value - -sizePicker.oninput = () => { - output.textContent = sizePicker.value; -}; - -// store mouse pointer coordinates, and whether the button is pressed -let curX; -let curY; -let pressed = false; - -// update mouse pointer coordinates -document.onmousemove = (e) => { - curX = e.pageX; - curY = e.pageY; -}; - -canvas.onmousedown = () => { - pressed = true; -}; - -canvas.onmouseup = () => { - pressed = false; -}; - -clearBtn.onclick = () => { - ctx.fillStyle = "rgb(0 0 0)"; - ctx.fillRect(0, 0, width, height); -}; - -function draw() { - if (pressed) { - ctx.fillStyle = colorPicker.value; - ctx.beginPath(); - ctx.arc( - curX, - curY - 85, - sizePicker.value, - degToRad(0), - degToRad(360), - false, - ); - ctx.fill(); - } - - requestAnimationFrame(draw); -} - -draw(); -``` - -{{EmbedLiveSample("Examples", '100%', 600)}} - -## Technical summary - -<table class="properties"> - <tbody> - <tr> - <td><strong><a href="#value">Value</a></strong></td> - <td>A string used as the button's label</td> - </tr> - <tr> - <td><strong>Events</strong></td> - <td>{{domxref("Element/click_event", "click")}}</td> - </tr> - <tr> - <td><strong>Supported common attributes</strong></td> - <td> - <a href="/en-US/docs/Web/HTML/Element/input#type"><code>type</code></a> and - <a href="/en-US/docs/Web/HTML/Element/input#value"><code>value</code></a> - </td> - </tr> - <tr> - <td><strong>IDL attributes</strong></td> - <td><code>value</code></td> - </tr> - <tr> - <td><strong>DOM interface</strong></td> - <td><p>{{domxref("HTMLInputElement")}}</p></td> - </tr> - <tr> - <td><strong>Methods</strong></td> - <td>None</td> - </tr> - <tr> - <td><strong>Implicit ARIA Role</strong></td> - <td><a href="/en-US/docs/Web/Accessibility/ARIA/Roles/button_role"><code>button</code></a></td> - </tr> - </tbody> -</table> - -## Specifications - -{{Specifications}} - -## Browser compatibility - -{{Compat}} - -## See also - -- {{HTMLElement("input")}} and the {{domxref("HTMLInputElement")}} interface which implements it. -- The more modern {{HTMLElement("button")}} element. diff --git a/files/en-us/web/html/element/input/checkbox/index.md b/files/en-us/web/html/element/input/checkbox/index.md deleted file mode 100644 index f686ad363ea4d5f..000000000000000 --- a/files/en-us/web/html/element/input/checkbox/index.md +++ /dev/null @@ -1,363 +0,0 @@ ---- -title: <input type="checkbox"> -slug: Web/HTML/Element/input/checkbox -page-type: html-element -browser-compat: html.elements.input.type_checkbox ---- - -{{HTMLSidebar}} - -{{htmlelement("input")}} elements of type **`checkbox`** are rendered by default as boxes that are checked (ticked) when activated, like you might see in an official government paper form. The exact appearance depends upon the operating system configuration under which the browser is running. Generally this is a square but it may have rounded corners. A checkbox allows you to select single values for submission in a form (or not). - -{{InteractiveExample("HTML Demo: &lt;input type=&quot;checkbox&quot;&gt;", "tabbed-standard")}} - -```html interactive-example -<fieldset> - <legend>Choose your monster's features:</legend> - - <div> - <input type="checkbox" id="scales" name="scales" checked /> - <label for="scales">Scales</label> - </div> - - <div> - <input type="checkbox" id="horns" name="horns" /> - <label for="horns">Horns</label> - </div> -</fieldset> -``` - -```css interactive-example -p, -label { - font: - 1rem "Fira Sans", - sans-serif; -} - -input { - margin: 0.4rem; -} -``` - -> **Note:** [Radio buttons](/en-US/docs/Web/HTML/Element/input/radio) are similar to checkboxes, but with an important distinction — [same-named radio buttons](/en-US/docs/Web/HTML/Element/input/radio#defining_a_radio_group) are grouped into a set in which only one radio button can be selected at a time, whereas checkboxes allow you to turn single values on and off. Where multiple same-named controls exist, radio buttons allow one to be selected out of them all, whereas checkboxes allow multiple values to be selected. - -## Value - -A string representing the value of the checkbox. This is not displayed on the client-side, but on the server this is the `value` given to the data submitted with the checkbox's `name`. Take the following example: - -```html -<form> - <div> - <input - type="checkbox" - id="subscribeNews" - name="subscribe" - value="newsletter" /> - <label for="subscribeNews">Subscribe to newsletter?</label> - </div> - <div> - <button type="submit">Subscribe</button> - </div> -</form> -``` - -In this example, we've got a name of `subscribe`, and a value of `newsletter`. When the form is submitted, the data name/value pair will be `subscribe=newsletter`. - -If the `value` attribute was omitted, the default value for the checkbox is `on`, so the submitted data in that case would be `subscribe=on`. - -> [!NOTE] -> If a checkbox is unchecked when its form is submitted, neither the name nor the value is submitted to the server. There is no HTML-only method of representing a checkbox's unchecked state (e.g. `value=unchecked`). If you wanted to submit a default value for the checkbox when it is unchecked, you could include JavaScript to create a {{HTMLElement("input/hidden", '&lt;input type="hidden"&gt;')}} within the form with a value indicating an unchecked state. - -## Additional attributes - -In addition to the [common attributes](/en-US/docs/Web/HTML/Element/input#attributes) shared by all {{HTMLElement("input")}} elements, `checkbox` inputs support the following attributes. - -- `checked` - - - : A [boolean](/en-US/docs/Glossary/Boolean/HTML) attribute indicating whether this checkbox is checked by default (when the page loads). It does _not_ indicate whether this checkbox is currently checked: if the checkbox's state is changed, this content attribute does not reflect the change. (Only the {{domxref("HTMLInputElement")}}'s `checked` IDL attribute is updated.) - > [!NOTE] - > Unlike other input controls, a checkbox's value is only included in the submitted data if the checkbox is currently `checked`. If it is, then the value of the checkbox's `value` attribute is reported as the input's value, or `on` if no `value` is set. - > Unlike other browsers, Firefox by default [persists the dynamic checked state](https://stackoverflow.com/questions/5985839/bug-with-firefox-disabled-attribute-of-input-not-resetting-when-refreshing) of an `<input>` across page loads. Use the [`autocomplete`](/en-US/docs/Web/HTML/Element/input#autocomplete) attribute to control this feature. - -- `value` - - - : The `value` attribute is one which all {{HTMLElement("input")}}s share; however, it serves a special purpose for inputs of type `checkbox`: when a form is submitted, only checkboxes which are currently checked are submitted to the server, and the reported value is the value of the `value` attribute. If the `value` is not otherwise specified, it is the string `on` by default. This is demonstrated in the section [Value](#value) above. - -## Using checkbox inputs - -We already covered the most basic use of checkboxes above. Let's now look at the other common checkbox-related features and techniques you'll need. - -### Handling multiple checkboxes - -The example we saw above only contained one checkbox; in real-world situations you'll be likely to encounter multiple checkboxes. If they are completely unrelated, then you can just deal with them all separately, as shown above. However, if they're all related, things are not quite so simple. - -For example, in the following demo we include multiple checkboxes to allow the user to select their interests (see the full version in the [Examples](#examples) section). - -```html -<fieldset> - <legend>Choose your interests</legend> - <div> - <input type="checkbox" id="coding" name="interest" value="coding" /> - <label for="coding">Coding</label> - </div> - <div> - <input type="checkbox" id="music" name="interest" value="music" /> - <label for="music">Music</label> - </div> -</fieldset> -``` - -{{EmbedLiveSample('Handling_multiple_checkboxes', 600, 100)}} - -In this example you will see that we've given each checkbox the same `name`. If both checkboxes are checked and then the form is submitted, you'll get a string of name/value pairs submitted like this: `interest=coding&interest=music`. When this string reaches the server, you need to parse it other than as an associative array, so all values, not only the last value, of `interest` are captured. For one technique used with Python, see [Handle Multiple Checkboxes with a Single Serverside Variable](https://stackoverflow.com/questions/18745456/handle-multiple-checkboxes-with-a-single-serverside-variable), for example. - -### Checking boxes by default - -To make a checkbox checked by default, you give it the `checked` attribute. See the below example: - -```html -<fieldset> - <legend>Choose your interests</legend> - <div> - <input type="checkbox" id="coding" name="interest" value="coding" checked /> - <label for="coding">Coding</label> - </div> - <div> - <input type="checkbox" id="music" name="interest" value="music" /> - <label for="music">Music</label> - </div> -</fieldset> -``` - -{{EmbedLiveSample('Checking_boxes_by_default', 600, 100)}} - -### Providing a bigger hit area for your checkboxes - -In the above examples, you may have noticed that you can toggle a checkbox by clicking on its associated {{htmlelement("label")}} element as well as on the checkbox itself. This is a really useful feature of HTML form labels that makes it easier to click the option you want, especially on small-screen devices like smartphones. - -Beyond accessibility, this is another good reason to properly set up `<label>` elements on your forms. - -### Indeterminate state checkboxes - -A checkbox can be in an **indeterminate** state. This is set using the {{domxref("HTMLInputElement")}} object's [`indeterminate`](/en-US/docs/Web/API/HTMLInputElement/indeterminate) property via JavaScript (it cannot be set using an HTML attribute): - -```js -inputInstance.indeterminate = true; -``` - -When `indeterminate` is `true`, the checkbox has a horizontal line in the box (it looks somewhat like a hyphen or minus sign) instead of a check/tick in most browsers. - -> [!NOTE] -> This is purely a visual change. It has no impact on whether the checkbox's `value` is used in a form submission. That is decided by the `checked` state, regardless of the `indeterminate` state. - -There are not many use cases for this property. The most common is when a checkbox is available that "owns" a number of sub-options (which are also checkboxes). If all of the sub-options are checked, the owning checkbox is also checked, and if they're all unchecked, the owning checkbox is unchecked. If any one or more of the sub-options have a different state than the others, the owning checkbox is in the indeterminate state. - -This can be seen in the below example (thanks to [CSS Tricks](https://css-tricks.com/indeterminate-checkboxes/) for the inspiration). In this example we keep track of the ingredients we are collecting for a recipe. When you check or uncheck an ingredient's checkbox, a JavaScript function checks the total number of checked ingredients: - -- If none are checked, the recipe name's checkbox is set to unchecked. -- If one or two are checked, the recipe name's checkbox is set to `indeterminate`. -- If all three are checked, the recipe name's checkbox is set to `checked`. - -So in this case the `indeterminate` state is used to state that collecting the ingredients has started, but the recipe is not yet complete. - -```js -const overall = document.querySelector("#enchantment"); -const ingredients = document.querySelectorAll("ul input"); - -overall.addEventListener("click", (e) => { - e.preventDefault(); -}); - -for (const ingredient of ingredients) { - ingredient.addEventListener("click", updateDisplay); -} - -function updateDisplay() { - let checkedCount = 0; - for (const ingredient of ingredients) { - if (ingredient.checked) { - checkedCount++; - } - } - - if (checkedCount === 0) { - overall.checked = false; - overall.indeterminate = false; - } else if (checkedCount === ingredients.length) { - overall.checked = true; - overall.indeterminate = false; - } else { - overall.checked = false; - overall.indeterminate = true; - } -} -``` - -{{EmbedGHLiveSample("learning-area/html/forms/indeterminate-example/index.html", '100%', 200)}} - -## Validation - -Checkboxes do support [validation](/en-US/docs/Web/HTML/Constraint_validation) (offered to all {{HTMLElement("input")}}s). However, most of the {{domxref("ValidityState")}}s will always be `false`. If the checkbox has the [`required`](/en-US/docs/Web/HTML/Element/input#required) attribute, but is not checked, then {{domxref("ValidityState.valueMissing")}} will be `true`. - -## Examples - -The following example is an extended version of the "multiple checkboxes" example we saw above — it has more standard options, plus an "other" checkbox that when checked causes a text field to appear to enter a value for the "other" option. This is achieved with a short block of JavaScript. The example includes implicit labels, with the `<input>` directly inside the `<label>`. The text input, without a visible label, includes the [`aria-label`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-label) attribute which provides its accessible name. This example also includes some CSS to improve the styling. - -### HTML - -```html -<form> - <fieldset> - <legend>Choose your interests</legend> - <div> - <label> - <input type="checkbox" id="coding" name="interest" value="coding" /> - Coding - </label> - </div> - <div> - <label> - <input type="checkbox" id="music" name="interest" value="music" /> - Music - </label> - </div> - <div> - <label> - <input type="checkbox" id="art" name="interest" value="art" /> - Art - </label> - </div> - <div> - <label> - <input type="checkbox" id="sports" name="interest" value="sports" /> - Sports - </label> - </div> - <div> - <label> - <input type="checkbox" id="cooking" name="interest" value="cooking" /> - Cooking - </label> - </div> - <div> - <label> - <input type="checkbox" id="other" name="interest" value="other" /> - Other - </label> - <input - type="text" - id="otherValue" - name="other" - aria-label="Other interest" /> - </div> - <div> - <button type="submit">Submit form</button> - </div> - </fieldset> -</form> -``` - -### CSS - -```css -html { - font-family: sans-serif; -} - -form { - width: 600px; - margin: 0 auto; -} - -div { - margin-bottom: 10px; -} - -fieldset { - background: cyan; - border: 5px solid blue; -} - -legend { - padding: 10px; - background: blue; - color: cyan; -} -``` - -### JavaScript - -```js -const otherCheckbox = document.querySelector("#other"); -const otherText = document.querySelector("#otherValue"); -otherText.style.visibility = "hidden"; - -otherCheckbox.addEventListener("change", () => { - if (otherCheckbox.checked) { - otherText.style.visibility = "visible"; - otherText.value = ""; - } else { - otherText.style.visibility = "hidden"; - } -}); -``` - -{{EmbedLiveSample('Examples', '100%', 300)}} - -## Technical summary - -<table class="properties"> - <tbody> - <tr> - <td><strong><a href="#value">Value</a></strong></td> - <td> - A string representing the value of the - checkbox. - </td> - </tr> - <tr> - <td><strong>Events</strong></td> - <td>{{domxref("HTMLElement/change_event", "change")}} and {{domxref("Element/input_event", "input")}}</td> - </tr> - <tr> - <td><strong>Supported common attributes</strong></td> - <td><code><a href="#checked">checked</a></code></td> - </tr> - <tr> - <td><strong>IDL attributes</strong></td> - <td> - <code><a href="/en-US/docs/Web/API/HTMLInputElement/checked">checked</a></code>, - <code><a href="/en-US/docs/Web/API/HTMLInputElement/indeterminate">indeterminate</a></code> and - <code><a href="/en-US/docs/Web/API/HTMLInputElement/value">value</a></code> - </td> - </tr> - <tr> - <td><strong>DOM interface</strong></td> - <td><p>{{domxref("HTMLInputElement")}}</p></td> - </tr> - <tr> - <td><strong>Methods</strong></td> - <td> - {{domxref("HTMLInputElement.select", "select()")}} - </td> - </tr> - <tr> - <td><strong>Implicit ARIA Role</strong></td> - <td><a href="/en-US/docs/Web/Accessibility/ARIA/Roles/checkbox_role"><code>checkbox</code></a></td> - </tr> - </tbody> -</table> - -## Specifications - -{{Specifications}} - -## Browser compatibility - -{{Compat}} - -## See also - -- {{cssxref(":checked")}}, {{cssxref(":indeterminate")}}: CSS selectors that let you style checkboxes based on their current state -- {{domxref("HTMLInputElement")}}: HTML DOM API that implements the `<input>` element diff --git a/files/en-us/web/html/element/input/color/index.md b/files/en-us/web/html/element/input/color/index.md deleted file mode 100644 index db06589c82b06a0..000000000000000 --- a/files/en-us/web/html/element/input/color/index.md +++ /dev/null @@ -1,237 +0,0 @@ ---- -title: <input type="color"> -slug: Web/HTML/Element/input/color -page-type: html-element -browser-compat: html.elements.input.type_color ---- - -{{HTMLSidebar}} - -{{HTMLElement("input")}} elements of type **`color`** provide a user interface element that lets a user specify a color, either by using a visual color picker interface or by entering the color into a text field in `#rrggbb` hexadecimal format. - -Only basic hexadecimal colors (without alpha channel) are allowed though CSS colors has more formats, e.g. color names, functional notations and a hexadecimal format with an alpha channel. - -The element's presentation may vary substantially from one browser and/or platform to another—it might be a basic textual input that automatically validates to ensure that the color information is entered in the proper format, or a platform-standard color picker, or some kind of custom color picker window. - -{{InteractiveExample("HTML Demo: &lt;input type=&quot;color&quot;&gt;", "tabbed-standard")}} - -```html interactive-example -<p>Choose your monster's colors:</p> - -<div> - <input type="color" id="head" name="head" value="#e66465" /> - <label for="head">Head</label> -</div> - -<div> - <input type="color" id="body" name="body" value="#f6b73c" /> - <label for="body">Body</label> -</div> -``` - -```css interactive-example -p, -label { - font: - 1rem "Fira Sans", - sans-serif; -} - -input { - margin: 0.4rem; -} -``` - -## Value - -The [`value`](/en-US/docs/Web/HTML/Element/input#value) of an {{HTMLElement("input")}} element of type `color` is always a string which contains a 7-character string specifying an RGB color in hexadecimal format. While you can input the color in either upper- or lower-case, it will be stored in lower-case form. The value is never in any other form, and is never empty. - -> [!NOTE] -> Setting the value to anything that isn't a valid, fully-opaque, RGB color _in hexadecimal notation_ will result in the value being set to `#000000`. In particular, you can't use CSS's standardized color names, or any CSS function syntax, to set the value. This makes sense when you keep in mind that HTML and CSS are separate languages and specifications. In addition, colors with an alpha channel are not supported; specifying a color in 9-character hexadecimal notation (e.g. `#009900aa`) will also result in the color being set to `#000000`. - -## Using color inputs - -Inputs of type `color` are simple, due to the limited number of attributes they support. - -### Providing a default color - -You can update the example above to set a default value, so that the color picker is pre-filled with the default color and the color picker (if any) will also default to that color: - -```html -<input type="color" value="#ff0000" /> -``` - -{{EmbedLiveSample("Providing_a_default_color", 700, 30)}} - -If you don't specify a value, the default is `#000000`, which is black. The value must be in seven-character hexadecimal notation, meaning the "#" character followed by two digits each representing red, green, and blue, like this: `#rrggbb`. If you have colors that are in any other format (such as CSS color names or CSS color functions such as `rgb()` or `hsl()` ), you'll have to convert them to hexadecimal before setting the `value`. - -### Tracking color changes - -As is the case with other {{HTMLElement("input")}} types, there are two events that can be used to detect changes to the color value: {{domxref("Element/input_event", "input")}} and {{domxref("HTMLElement/change_event", "change")}}. `input` is fired on the `<input>` element every time the color changes. The `change` event is fired when the user dismisses the color picker. In both cases, you can determine the new value of the element by looking at its [`value`](/en-US/docs/Web/HTML/Element/input#value). - -Here's an example that watches changes over time to the color value: - -```js -colorPicker.addEventListener("input", updateFirst, false); -colorPicker.addEventListener("change", watchColorPicker, false); - -function watchColorPicker(event) { - document.querySelectorAll("p").forEach((p) => { - p.style.color = event.target.value; - }); -} -``` - -### Selecting the value - -When a browser doesn't support a color picker interface, its implementation of color inputs will be a text box that validates the contents automatically to ensure that the value is in the correct format. In this case you can use the {{domxref("HTMLInputElement.select", "select()")}} method to select the text currently in the edit field. - -If the browser instead uses a color picker, `select()` does nothing. You should be aware of this behavior so your code can respond appropriately in either case. - -```js -colorPicker.select(); -``` - -## Validation - -A color input's value is considered to be invalid if the {{Glossary("user agent")}} is unable to convert the user's input into seven-character lower-case hexadecimal notation. If and when this is the case, the {{cssxref(":invalid")}} pseudo-class is applied to the element. - -## Example - -Let's create an example which does a little more with the color input by tracking the {{domxref("HTMLElement/change_event", "change")}} and {{domxref("Element/input_event", "input")}} events to take the new color and apply it to every {{HTMLElement("p")}} element in the document. - -### HTML - -The HTML is fairly straightforward — a couple of paragraphs of descriptive material with an {{HTMLElement("input")}} of type `color` with the ID `color-picker`, which we'll use to change the color of the paragraphs' text. - -```html -<p> - An example demonstrating the use of the - <code>&lt;input type="color"&gt;</code> control. -</p> - -<label for="color-picker">Color:</label> -<input type="color" value="#ff0000" id="color-picker" /> - -<p> - Watch the paragraph colors change when you adjust the color picker. As you - make changes in the color picker, the first paragraph's color changes, as a - preview (this uses the <code>input</code> event). When you close the color - picker, the <code>change</code> event fires, and we detect that to change - every paragraph to the selected color. -</p> -``` - -### JavaScript - -First, there's some setup. Here we establish some variables, setting up a variable that contains the color we'll set the color picker to when we first load up, and then setting up a {{domxref("Window/load_event", "load")}} handler to do the main startup work once the page is fully loaded. - -```js -let colorPicker; -const defaultColor = "#0000ff"; - -window.addEventListener("load", startup, false); -``` - -#### Initialization - -Once the page is loaded, our `load` event handler, `startup()`, is called: - -```js -function startup() { - colorPicker = document.querySelector("#color-picker"); - colorPicker.value = defaultColor; - colorPicker.addEventListener("input", updateFirst, false); - colorPicker.addEventListener("change", updateAll, false); - colorPicker.select(); -} -``` - -This gets a reference to the color `<input>` element in a variable called `colorPicker`, then sets the color input's value to the value in `defaultColor`. Then the color input's {{domxref("Element/input_event", "input")}} event is set up to call our `updateFirst()` function, and the {{domxref("HTMLElement/change_event", "change")}} event is set to call `updateAll()`. These are both seen below. - -Finally, we call {{domxref("HTMLInputElement.select", "select()")}} to select the text content of the color input if the control is implemented as a text field (this has no effect if a color picker interface is provided instead). - -#### Reacting to color changes - -We provide two functions that deal with color changes. The `updateFirst()` function is called in response to the `input` event. It changes the color of the first paragraph element in the document to match the new value of the color input. Since `input` events are fired every time an adjustment is made to the value (for example, if the brightness of the color is increased), these will happen repeatedly as the color picker is used. - -```js -function updateFirst(event) { - const p = document.querySelector("p"); - if (p) { - p.style.color = event.target.value; - } -} -``` - -When the color picker is dismissed, indicating that the value will not change again (unless the user re-opens the color picker), a `change` event is sent to the element. We handle that event using the `updateAll()` function, using [`Event.target.value`](/en-US/docs/Web/HTML/Element/input#value) to obtain the final selected color: - -```js -function updateAll(event) { - document.querySelectorAll("p").forEach((p) => { - p.style.color = event.target.value; - }); -} -``` - -This sets the color of every {{HTMLElement("p")}} block so that its {{cssxref("color")}} attribute matches the current value of the color input, which is referred to using {{domxref("Event.target", "event.target")}}. - -### Result - -The final result looks like this: - -{{EmbedLiveSample("Example", 700, 200)}} - -## Technical summary - -<table class="properties"> - <tbody> - <tr> - <td><strong><a href="#value">Value</a></strong></td> - <td> - A 7-character string specifying a - {{cssxref("&lt;color&gt;")}} in lower-case hexadecimal notation - </td> - </tr> - <tr> - <td><strong>Events</strong></td> - <td> - {{domxref("HTMLElement/change_event", "change")}} and - {{domxref("Element/input_event", "input")}} - </td> - </tr> - <tr> - <td><strong>Supported common attributes</strong></td> - <td> - <a href="/en-US/docs/Web/HTML/Element/input#autocomplete"><code>autocomplete</code></a> and - <a href="/en-US/docs/Web/HTML/Element/input#list"><code>list</code></a> - </td> - </tr> - <tr> - <td><strong>IDL attributes</strong></td> - <td><code>list</code> and <code>value</code></td> - </tr> - <tr> - <td><strong>DOM interface</strong></td> - <td><p>{{domxref("HTMLInputElement")}}</p></td> - </tr> - <tr> - <td><strong>Methods</strong></td> - <td> - {{domxref("HTMLInputElement.select", "select()")}} - </td> - </tr> - <tr> - <td><strong>Implicit ARIA Role</strong></td> - <td><a href="https://www.w3.org/TR/html-aria/#dfn-no-corresponding-role">no corresponding role</a></td> - </tr> - </tbody> -</table> - -## Specifications - -{{Specifications}} - -## Browser compatibility - -{{Compat}} diff --git a/files/en-us/web/html/element/input/date/index.md b/files/en-us/web/html/element/input/date/index.md deleted file mode 100644 index 36aa85fe73b963b..000000000000000 --- a/files/en-us/web/html/element/input/date/index.md +++ /dev/null @@ -1,305 +0,0 @@ ---- -title: <input type="date"> -slug: Web/HTML/Element/input/date -page-type: html-element -browser-compat: html.elements.input.type_date ---- - -{{HTMLSidebar}} - -{{HTMLElement("input")}} elements of **`type="date"`** create input fields that let the user enter a date. The appearance of the date picker input UI varies based on the browser and operating system. The value is normalized to the format `yyyy-mm-dd`. - -The resulting value includes the year, month, and day, but _not_ the time. The {{HTMLElement("input/time", "time")}} and {{HTMLElement("input/datetime-local", "datetime-local")}} input types support time and date+time input. - -{{InteractiveExample("HTML Demo: &lt;input type=&quot;date&quot;&gt;", "tabbed-shorter")}} - -```html interactive-example -<label for="start">Start date:</label> - -<input - type="date" - id="start" - name="trip-start" - value="2018-07-22" - min="2018-01-01" - max="2018-12-31" /> -``` - -```css interactive-example -label { - display: block; - font: - 1rem "Fira Sans", - sans-serif; -} - -input, -label { - margin: 0.4rem 0; -} -``` - -## Value - -A string representing the date entered in the input. The date is formatted according to [Date strings format](/en-US/docs/Web/HTML/Date_and_time_formats#date_strings). - -You can set a default value for the input with a date inside the [`value`](/en-US/docs/Web/HTML/Element/input#value) attribute, like so: - -```html -<input type="date" value="2017-06-01" /> -``` - -{{EmbedLiveSample('Value', 600, 40)}} - -> [!NOTE] -> The displayed date format will differ from the actual `value` — the displayed date is formatted _based on the locale of the user's browser_, but the parsed `value` is always formatted `yyyy-mm-dd`. - -You can get and set the date value in JavaScript with the {{domxref("HTMLInputElement")}} `value` and `valueAsNumber` properties. For example: - -```js -const dateControl = document.querySelector('input[type="date"]'); -dateControl.value = "2017-06-01"; -console.log(dateControl.value); // prints "2017-06-01" -console.log(dateControl.valueAsNumber); // prints 1496275200000, a JavaScript timestamp (ms) -``` - -This code finds the first {{HTMLElement("input")}} element whose `type` is `date`, and sets its value to `2017-06-01` (June 1st, 2017). It then reads that value back in string and number formats. - -## Additional attributes - -The attributes common to all {{HTMLElement("input")}} elements apply to the `date` inputs as well, but might not influence its presentation. For example `size` and `placeholder` might not work. `date` inputs have the following additional attributes. - -### max - -The latest date to accept. If the [`value`](/en-US/docs/Web/HTML/Element/input#value) entered into the element occurs afterward, the element fails [constraint validation](/en-US/docs/Web/HTML/Constraint_validation). If the value of the `max` attribute isn't a possible date string in the format `yyyy-mm-dd`, then the element has no maximum date value. - -If both the `max` and `min` attributes are set, this value must be a date string **later than or equal to** the one in the `min` attribute. - -### min - -The earliest date to accept. If the [`value`](/en-US/docs/Web/HTML/Element/input#value) entered into the element occurs beforehand, the element fails [constraint validation](/en-US/docs/Web/HTML/Constraint_validation). If the value of the `min` attribute isn't a possible date string in the format `yyyy-mm-dd`, then the element has no minimum date value. - -If both the `max` and `min` attributes are set, this value must be a date string **earlier than or equal to** the one in the `max` attribute. - -### step - -The `step` attribute is a number that specifies the granularity that the value must adhere to, or the special value `any`, which is described below. Only values which are equal to the basis for stepping ([`min`](#min) if specified, [`value`](/en-US/docs/Web/HTML/Element/input#value) otherwise, and an appropriate default value if neither of those is provided) are valid. - -A string value of `any` means that no stepping is implied, and any value is allowed (barring other constraints, such as [`min`](#min) and [`max`](#max)). - -> [!NOTE] -> When the data entered by the user doesn't adhere to the stepping configuration, the {{Glossary("user agent")}} may round to the nearest valid value, preferring numbers in the positive direction when there are two equally close options. - -For `date` inputs, the value of `step` is given in days; and is treated as a number of milliseconds equal to 86,400,000 times the `step` value (the underlying numeric value is in milliseconds). The default value of `step` is 1, indicating 1 day. - -> [!NOTE] -> Specifying `any` as the value for `step` has the same effect as `1` for `date` inputs. - -## Using date inputs - -Date inputs provide an easy interface for choosing dates, and they normalize the data format sent to the server regardless of the user's locale. - -In this section, we'll look at basic and then more complex uses of `<input type="date">`. - -### Basic uses of date - -The most basic use of `<input type="date">` involves one `<input>` combined with its {{htmlelement("label")}}, as seen below: - -```html -<form action="https://example.com"> - <label> - Enter your birthday: - <input type="date" name="bday" /> - </label> - - <p><button>Submit</button></p> -</form> -``` - -{{EmbedLiveSample('Basic_uses_of_date', 600, 40)}} - -This HTML submits the entered date under the key `bday` to `https://example.com` — resulting in a URL like `https://example.com/?bday=1955-06-08`. - -### Setting maximum and minimum dates - -You can use the [`min`](/en-US/docs/Web/HTML/Element/input#min) and [`max`](/en-US/docs/Web/HTML/Element/input#max) attributes to restrict the dates that can be chosen by the user. In the following example, we set a minimum date of `2017-04-01` and a maximum date of `2017-04-30`: - -```html -<form> - <label> - Choose your preferred party date: - <input type="date" name="party" min="2017-04-01" max="2017-04-30" /> - </label> -</form> -``` - -{{EmbedLiveSample('Setting_maximum_and_minimum_dates', 600, 40)}} - -The result is that only days in April 2017 can be selected — the month and year parts of the textbox will be uneditable, and dates outside April 2017 can't be selected in the picker widget. - -You can use the [`step`](/en-US/docs/Web/HTML/Element/input#step) attribute to vary the number of days jumped each time the date is incremented (e.g. to only make Saturdays selectable). - -### Controlling input size - -`<input type="date">` doesn't support form sizing attributes such as [`size`](/en-US/docs/Web/HTML/Element/input#size). Prefer [CSS](/en-US/docs/Web/CSS) for sizing it. - -## Validation - -By default, `<input type="date">` doesn't validate the entered value beyond its format. The interfaces generally don't let you enter anything that isn't a date — which is helpful. - -If you use [`min`](/en-US/docs/Web/HTML/Element/input#min) and [`max`](/en-US/docs/Web/HTML/Element/input#max) to restrict the available dates (see [Setting maximum and minimum dates](#setting_maximum_and_minimum_dates)), the form control disables invalid dates, and will display an error if you try to submit a date that is out of bounds. - -You can also use the [`required`](/en-US/docs/Web/HTML/Element/input#required) attribute to make filling in the date mandatory — an error will be displayed if you try to submit an empty date field. - -Let's look at an example of minimum and maximum dates, and also made a field required: - -```html -<form> - <label> - Choose your preferred party date (required, April 1st to 20th): - <input - type="date" - name="party" - min="2017-04-01" - max="2017-04-20" - required /> - <span class="validity"></span> - </label> - - <p> - <button>Submit</button> - </p> -</form> -``` - -If you try to submit the form with an incomplete date (or with a date outside the set bounds), the browser displays an error. Try playing with the example now: - -{{EmbedLiveSample('Validation', 600, 100)}} - -Here's the CSS used in the above example. We make use of the {{cssxref(":valid")}} and {{cssxref(":invalid")}} [pseudo-elements](/en-US/docs/Web/CSS/Pseudo-elements) to add an icon next to the input, based on whether the current value is valid. We had to put the icon on a {{htmlelement("span")}} next to the input, not on the input itself, because in Chrome at least the input's generated content is placed inside the form control, and can't be styled or shown effectively. - -```css -label { - display: flex; - align-items: center; -} - -span::after { - padding-left: 5px; -} - -input:invalid + span::after { - content: "✖"; -} - -input:valid + span::after { - content: "✓"; -} -``` - -> [!WARNING] -> Client-side form validation _is not a substitute_ for validating on the server. It's easy for someone to modify the HTML, or bypass your HTML entirely and submit the data directly to your server. If your server fails to validate the received data, disaster could strike with data that is badly-formatted, too large, of the wrong type, etc. - -## Examples - -In this example, we create a date picker using the native `<input type="date">` picker. - -### HTML - -The HTML looks like so: - -```html -<form> - <div class="nativeDatePicker"> - <label for="bday">Enter your birthday:</label> - <input type="date" id="bday" name="bday" /> - <span class="validity"></span> - </div> -</form> -``` - -### CSS - -The CSS looks like so: - -```css -input:invalid + span::after { - content: " ✖"; -} - -input:valid + span::after { - content: " ✓"; -} -``` - -### Results - -{{EmbedLiveSample('Examples', 600, 100)}} - -## Technical summary - -<table class="properties"> - <tbody> - <tr> - <td><strong><a href="#value">Value</a></strong></td> - <td> - A string representing a date in YYYY-MM-DD - format, or empty - </td> - </tr> - <tr> - <td><strong>Events</strong></td> - <td> - {{domxref("HTMLElement/change_event", "change")}} and - {{domxref("Element/input_event", "input")}} - </td> - </tr> - <tr> - <td><strong>Supported common attributes</strong></td> - <td> - <a href="/en-US/docs/Web/HTML/Element/input#autocomplete"><code>autocomplete</code></a>, - <a href="/en-US/docs/Web/HTML/Element/input#list"><code>list</code></a>, - <a href="/en-US/docs/Web/HTML/Element/input#readonly"><code>readonly</code></a>, - <a href="/en-US/docs/Web/HTML/Element/input#step"><code>step</code></a> - </td> - </tr> - <tr> - <td><strong>IDL attributes</strong></td> - <td> - <a href="/en-US/docs/Web/HTML/Element/input#value"><code>value</code></a>, - <code>valueAsDate</code>, - <code>valueAsNumber</code> - </td> - </tr> - <tr> - <td><strong>DOM interface</strong></td> - <td><p>{{domxref("HTMLInputElement")}}</p></td> - </tr> - <tr> - <td><strong>Methods</strong></td> - <td> - {{domxref("HTMLInputElement.select", "select()")}}, - {{domxref("HTMLInputElement.stepDown", "stepDown()")}}, - {{domxref("HTMLInputElement.stepUp", "stepUp()")}} - </td> - </tr> - <tr> - <td><strong>Implicit ARIA Role</strong></td> - <td><a href="https://www.w3.org/TR/html-aria/#dfn-no-corresponding-role">no corresponding role</a></td> - </tr> - </tbody> -</table> - -## Specifications - -{{Specifications}} - -## Browser compatibility - -{{Compat}} - -## See also - -- The generic {{HTMLElement("input")}} element and the interface used to manipulate it, {{domxref("HTMLInputElement")}} -- [Date and Time picker tutorial](/en-US/docs/Learn_web_development/Extensions/Forms/HTML5_input_types#date_and_time_pickers) -- [Date and time formats used in HTML](/en-US/docs/Web/HTML/Date_and_time_formats) diff --git a/files/en-us/web/html/element/input/datetime-local/index.md b/files/en-us/web/html/element/input/datetime-local/index.md deleted file mode 100644 index b5164c0c86ec4b9..000000000000000 --- a/files/en-us/web/html/element/input/datetime-local/index.md +++ /dev/null @@ -1,307 +0,0 @@ ---- -title: <input type="datetime-local"> -slug: Web/HTML/Element/input/datetime-local -page-type: html-element -browser-compat: html.elements.input.type_datetime-local ---- - -{{HTMLSidebar}} - -{{htmlelement("input")}} elements of type **`datetime-local`** create input controls that let the user easily enter both a date and a time, including the year, month, and day as well as the time in hours and minutes. - -{{InteractiveExample("HTML Demo: &lt;input type=&quot;datetime-local&quot;&gt;", "tabbed-shorter")}} - -```html interactive-example -<label for="meeting-time">Choose a time for your appointment:</label> - -<input - type="datetime-local" - id="meeting-time" - name="meeting-time" - value="2018-06-12T19:30" - min="2018-06-07T00:00" - max="2018-06-14T00:00" /> -``` - -```css interactive-example -label { - display: block; - font: - 1rem "Fira Sans", - sans-serif; -} - -input, -label { - margin: 0.4rem 0; -} -``` - -The control's UI varies in general from browser to browser. The control is intended to represent _a local date and time_, not necessarily _the user's local date and time_. In other words, the input allows any valid combination of year, month, day, hour, and minute—even if such a combination is invalid in the user's local time zone (such as the one hour within a daylight saving time spring-forward transition gap). - -## Value - -A string representing the value of the date entered into the input. The format of the date and time value used by this input type is described in [Local date and time strings](/en-US/docs/Web/HTML/Date_and_time_formats#local_date_and_time_strings). - -You can set a default value for the input by including a date and time inside the [`value`](/en-US/docs/Web/HTML/Element/input#value) attribute, like so: - -```html -<label for="party">Enter a date and time for your party booking:</label> -<input - id="party" - type="datetime-local" - name="party-date" - value="2017-06-01T08:30" /> -``` - -{{ EmbedLiveSample('Value', 600, 60) }} - -One thing to note is that the displayed date and time formats differ from the actual `value`; the displayed date and time are formatted according to the user's locale as reported by their operating system, whereas the date/time `value` is always formatted `YYYY-MM-DDTHH:mm`. When the above value is submitted to the server, for example, it will look like `party-date=2024-06-01T08:30`. - -> [!NOTE] -> Also bear in mind that if such data is submitted via HTTP [`GET`](/en-US/docs/Web/HTTP/Methods/GET), the colon character will need to be escaped for inclusion in the URL parameters, e.g. `party-date=2024-06-01T08%3A30`. See {{jsxref("Global_Objects/encodeURI", "encodeURI()")}} for one way to do this. - -You can also get and set the date value in JavaScript using the {{domxref("HTMLInputElement")}} `value` property, for example: - -```js -const dateControl = document.querySelector('input[type="datetime-local"]'); -dateControl.value = "2017-06-01T08:30"; -``` - -## Additional attributes - -In addition to the attributes common to all {{HTMLElement("input")}} elements, `datetime-local` inputs offer the following attributes. - -### max - -The latest date and time to accept. If the [`value`](/en-US/docs/Web/HTML/Element/input#value) entered into the element is later than this timestamp, the element fails [constraint validation](/en-US/docs/Web/HTML/Constraint_validation). If the value of the `max` attribute isn't a valid string that follows the format `YYYY-MM-DDTHH:mm`, then the element has no maximum value. - -This value must specify a date string later than or equal to the one specified by the `min` attribute. - -### min - -The earliest date and time to accept; timestamps earlier than this will cause the element to fail [constraint validation](/en-US/docs/Web/HTML/Constraint_validation). If the value of the `min` attribute isn't a valid string that follows the format `YYYY-MM-DDTHH:mm`, then the element has no minimum value. - -This value must specify a date string earlier than or equal to the one specified by the `max` attribute. - -### step - -The `step` attribute is a number that specifies the granularity that the value must adhere to, or the special value `any`, which is described below. Only values which are equal to the basis for stepping ([`min`](#min) if specified, [`value`](/en-US/docs/Web/HTML/Element/input#value) otherwise, and an appropriate default value if neither of those is provided) are valid. - -A string value of `any` means that no stepping is implied, and any value is allowed (barring other constraints, such as [`min`](#min) and [`max`](#max)). - -> [!NOTE] -> When the data entered by the user doesn't adhere to the stepping configuration, the {{Glossary("user agent")}} may round to the nearest valid value, preferring numbers in the positive direction when there are two equally close options. - -For `datetime-local` inputs, the value of `step` is given in seconds, with a scaling factor of 1000 (since the underlying numeric value is in milliseconds). The default value of `step` is 60, indicating 60 seconds (or 1 minute, or 60,000 milliseconds). - -_At this time, it's unclear what a value of `any` means for `step` when used with `datetime-local` inputs. This will be updated as soon as that information is determined._ - -## Using datetime-local inputs - -Date/time inputs are convenient for the developer; they provide an easy UI for choosing dates and times, and they normalize the data format sent to the server, regardless of the user's locale. However, it is important to consider your users. Don't require your users to enter data that is not needed for your app to function. - -### Controlling input size - -`<input type="datetime-local">` doesn't support form control sizing attributes such as [`size`](/en-US/docs/Web/HTML/Element/input#size). You'll have to resort to [CSS](/en-US/docs/Web/CSS) for customizing the sizes of these elements. - -### Setting timezones - -One thing the `datetime-local` input type doesn't provide is a way to set the time zone and/or locale of the date/time control. This was available in the `datetime` input type, but this type is now obsolete, having been removed from the spec. The main reasons why this was removed are a lack of implementation in browsers and concerns over the user interface/experience. It is easier to just have a control (or controls) for setting the date/time and then deal with the locale in a separate control. - -For example, if you are creating a system where the user is likely to already be logged in, with their locale already set, you could provide the timezone in a [`hidden`](/en-US/docs/Web/HTML/Element/input/hidden) input type. For example: - -```html -<input type="hidden" id="timezone" name="timezone" value="-08:00" /> -``` - -On the other hand, if you were required to allow the user to enter a time zone along with a date/time input, you could have a {{htmlelement("select")}} element to enable the user to set the right time zone by choosing a particular location from among a set of locations: - -```html -<select name="timezone" id="timezone"> - <option value="Pacific/Kwajalein">Eniwetok, Kwajalein</option> - <option value="Pacific/Midway">Midway Island, Samoa</option> - <option value="Pacific/Honolulu">Hawaii</option> - <option value="Pacific/Marquesas">Taiohae</option> - <!-- and so on --> -</select> -``` - -In either case, the date/time and time zone values would be submitted to the server as separate data points, and then you'd need to store them appropriately in the database on the server-side. - -## Validation - -By default, `<input type="datetime-local">` does not apply any validation to entered values. The UI implementations generally don't let you enter anything that isn't a date/time — which is helpful — but a user might still fill in no value and submit, or enter an invalid date and/or time (e.g. the 32nd of April). - -You can use [`min`](/en-US/docs/Web/HTML/Element/input#min) and [`max`](/en-US/docs/Web/HTML/Element/input#max) to restrict the available dates (see [Setting maximum and minimum dates](#setting_maximum_and_minimum_dates_and_times)), and you can use the [`required`](/en-US/docs/Web/HTML/Element/input#required) attribute to make filling in the date/time mandatory. As a result, browsers will display an error if you try to submit a date that is outside the set bounds or an empty date field. - -Let's look at an example; here we've set minimum and maximum date/time values, and also made the field required: - -```html -<form> - <div> - <label for="party"> - Choose your preferred party date and time (required, June 1st 8.30am to - June 30th 4.30pm): - </label> - <input - id="party" - type="datetime-local" - name="party-date" - min="2017-06-01T08:30" - max="2017-06-30T16:30" - required /> - <span class="validity"></span> - </div> - <div> - <input type="submit" value="Book party!" /> - </div> -</form> -``` - -If you try to submit the form with an incomplete date (or with a date outside the set bounds), the browser displays an error. Try playing with the example now: - -{{ EmbedLiveSample('Validation', 600, 120) }} - -Here's the CSS used in the above example. Here we make use of the {{cssxref(":valid")}} and {{cssxref(":invalid")}} CSS properties to style the input based on whether the current value is valid. We put the icons on a {{htmlelement("span")}} next to the input. - -```css -div { - margin-bottom: 10px; - display: flex; - align-items: center; -} - -label { - display: inline-block; - width: 300px; -} - -input:invalid + span::after { - content: "✖"; - padding-left: 5px; -} - -input:valid + span::after { - content: "✓"; - padding-left: 5px; -} -``` - -> [!WARNING] -> HTML form validation is _not_ a substitute for scripts that ensure that the entered data is in the proper format. It's far too easy for someone to make adjustments to the HTML that allow them to bypass the validation, or to remove it entirely. It's also possible for someone to bypass your HTML entirely and submit the data directly to your server. If your server-side code fails to validate the data it receives, problems can arise when improperly-formatted data is submitted (or data that is too large, is of the wrong type, and so forth). - -> [!NOTE] -> With a `datetime-local` input, the date value is always normalized to the format `YYYY-MM-DDTHH:mm`. - -## Examples - -### Basic uses of datetime-local - -The most basic use of `<input type="datetime-local">` involves a basic `<input>` and {{htmlelement("label")}} element combination, as seen below: - -```html -<form> - <label for="party">Enter a date and time for your party booking:</label> - <input id="party" type="datetime-local" name="party-date" /> -</form> -``` - -{{ EmbedLiveSample('Basic_uses_of_datetime-local', 600, 40) }} - -### Setting maximum and minimum dates and times - -You can use the [`min`](/en-US/docs/Web/HTML/Element/input#min) and [`max`](/en-US/docs/Web/HTML/Element/input#max) attributes to restrict the dates/times that can be chosen by the user. In the following example, we are setting a minimum datetime of `2025-06-01T08:30` and a maximum datetime of `2025-06-30T16:30`: - -```html -<form> - <label for="party">Enter a date and time for your party booking:</label> - <input - id="party" - type="datetime-local" - name="party-date" - min="2025-06-01T08:30" - max="2025-06-30T16:30" /> -</form> -``` - -{{ EmbedLiveSample('Setting_maximum_and_minimum_dates_and_times', 600, 40) }} - -Only days in June 2025 can be selected. Depending on what browser you are using, times outside the specified values might not be selectable. In other browsers, invalid dates and times are selectable but will match {{CSSXref(":invalid")}} and {{CSSXref(":out-of-range")}} and will fail [validation](#validation). - -In some browsers (Chrome and Edge), only the "days" part of the date value will be editable, and dates outside June can't be scrolled. In others (Safari), the date picker will appear to allow any date, but the value will be clamped to the valid range when a date is selected. - -The valid range included all times between the `min` and `max` values; the time of day is only constrained on the first and last dates in the range. - -> [!NOTE] -> You should be able to use the [`step`](/en-US/docs/Web/HTML/Element/input#step) attribute to vary the number of days jumped each time the date is incremented (e.g. maybe you only want to make Saturdays selectable). However, this does not seem to work effectively in any implementation at the time of writing. - -## Technical summary - -<table class="properties"> - <tbody> - <tr> - <td><strong><a href="#value">Value</a></strong></td> - <td> - A string representing a date and time (in the - local time zone), or empty. - </td> - </tr> - <tr> - <td><strong>Events</strong></td> - <td> - {{domxref("HTMLElement/change_event", "change")}} and - {{domxref("Element/input_event", "input")}} - </td> - </tr> - <tr> - <td><strong>Supported common attributes</strong></td> - <td> - <a href="/en-US/docs/Web/HTML/Element/input#autocomplete"><code>autocomplete</code></a>, - <a href="/en-US/docs/Web/HTML/Element/input#list"><code>list</code></a>, - <a href="/en-US/docs/Web/HTML/Element/input#readonly"><code>readonly</code></a>, - <a href="/en-US/docs/Web/HTML/Element/input#step"><code>step</code></a> - </td> - </tr> - <tr> - <td><strong>IDL attributes</strong></td> - <td> - <a href="/en-US/docs/Web/HTML/Element/input#list"><code>list</code></a>, - <a href="/en-US/docs/Web/HTML/Element/input#value"><code>value</code></a>, - <code>valueAsDate</code>, - <code>valueAsNumber</code> - </td> - </tr> - <tr> - <td><strong>DOM interface</strong></td> - <td><p>{{domxref("HTMLInputElement")}}</p></td> - </tr> - <tr> - <td><strong>Methods</strong></td> - <td> - {{domxref("HTMLInputElement.select", "select()")}}, - {{domxref("HTMLInputElement.stepDown", "stepDown()")}}, - {{domxref("HTMLInputElement.stepUp", "stepUp()")}} - </td> - </tr> - <tr> - <td><strong>Implicit ARIA Role</strong></td> - <td><a href="https://www.w3.org/TR/html-aria/#dfn-no-corresponding-role">no corresponding role</a></td> - </tr> - </tbody> -</table> - -## Specifications - -{{Specifications}} - -## Browser compatibility - -{{Compat}} - -## See also - -- The generic {{HTMLElement("input")}} element and the interface used to manipulate it, {{domxref("HTMLInputElement")}} -- [`<input type="date">`](/en-US/docs/Web/HTML/Element/input/date) and [`<input type="time">`](/en-US/docs/Web/HTML/Element/input/time) -- [Date and time formats used in HTML](/en-US/docs/Web/HTML/Date_and_time_formats) -- [Date and Time picker tutorial](/en-US/docs/Learn_web_development/Extensions/Forms/HTML5_input_types#date_and_time_pickers) diff --git a/files/en-us/web/html/element/input/email/index.md b/files/en-us/web/html/element/input/email/index.md deleted file mode 100644 index 241473133ec7e44..000000000000000 --- a/files/en-us/web/html/element/input/email/index.md +++ /dev/null @@ -1,441 +0,0 @@ ---- -title: <input type="email"> -slug: Web/HTML/Element/input/email -page-type: html-element -browser-compat: html.elements.input.type_email ---- - -{{HTMLSidebar}} - -{{HTMLElement("input")}} elements of type **`email`** are used to let the user enter and edit an email address, or, if the [`multiple`](/en-US/docs/Web/HTML/Attributes/multiple) attribute is specified, a list of email addresses. - -{{InteractiveExample("HTML Demo: &lt;input type=&quot;email&quot;&gt;", "tabbed-shorter")}} - -```html interactive-example -<label for="email">Enter your example.com email:</label> - -<input type="email" id="email" pattern=".+@example\.com" size="30" required /> -``` - -```css interactive-example -label { - display: block; - font: - 1rem "Fira Sans", - sans-serif; -} - -input, -label { - margin: 0.4rem 0; -} -``` - -The input value is automatically validated to ensure that it's either empty or a properly-formatted email address (or list of addresses) before the form can be submitted. The {{cssxref(":valid")}} and {{cssxref(":invalid")}} CSS pseudo-classes are automatically applied as appropriate to visually denote whether the current value of the field is a valid email address or not. - -## Value - -The {{HTMLElement("input")}} element's [`value`](/en-US/docs/Web/HTML/Element/input#value) attribute contains a string which is automatically validated as conforming to email syntax. More specifically, there are three possible value formats that will pass validation: - -1. An empty string ("") indicating that the user did not enter a value or that the value was removed. -2. A single properly-formed email address. This doesn't necessarily mean the email address exists, but it is at least formatted correctly. In simple terms, this means `username@domain` or `username@domain.tld`. There's more to it than that, of course; see [Validation](#validation) for a {{Glossary("regular expression")}} that matches the email address validation algorithm. -3. If and only if the [`multiple`](/en-US/docs/Web/HTML/Element/input#multiple) attribute is specified, the value can be a list of properly-formed comma-separated email addresses. Any trailing and leading whitespace is removed from each address in the list. - -See [Validation](#validation) for details on how email addresses are validated to ensure that they're formatted properly. - -## Additional attributes - -In addition to the [global attributes](/en-US/docs/Web/HTML/Global_attributes), and the attributes that operate on all {{HTMLElement("input")}} elements regardless of their type, `email` inputs support the following attributes. - -> [!NOTE] -> The [`autocorrect`](/en-US/docs/Web/HTML/Global_attributes/autocorrect) global attribute can be added to email inputs, but the stored state is always `off`. - -### list - -The values of the list attribute is the {{domxref("Element.id", "id")}} of a {{HTMLElement("datalist")}} element located in the same document. The {{HTMLElement("datalist")}} provides a list of predefined values to suggest to the user for this input. Any values in the list that are not compatible with the [`type`](/en-US/docs/Web/HTML/Element/input#type) are not included in the suggested options. The values provided are suggestions, not requirements: users can select from this predefined list or provide a different value. - -### maxlength - -The maximum string length (measured in UTF-16 code units) that the user can enter into the `email` input. This must be an integer value of 0 or higher. If no `maxlength` is specified, or an invalid value is specified, the `email` input has no maximum length. This value must also be greater than or equal to the value of `minlength`. - -The input will fail [constraint validation](/en-US/docs/Web/HTML/Constraint_validation) if the length of the text value of the field is greater than `maxlength` UTF-16 code units long. Constraint validation is only applied when the value is changed by the user. - -### minlength - -The minimum string length (measured in UTF-16 code units) that the user can enter into the `email` input. This must be a non-negative integer value smaller than or equal to the value specified by `maxlength`. If no `minlength` is specified, or an invalid value is specified, the `email` input has no minimum length. - -The input will fail [constraint validation](/en-US/docs/Web/HTML/Constraint_validation) if the length of the text entered into the field is fewer than `minlength` UTF-16 code units long. Constraint validation is only applied when the value is changed by the user. - -### multiple - -A Boolean attribute which, if present, indicates that the user can enter a list of multiple email addresses, separated by commas and, optionally, whitespace characters. See [Allowing multiple email addresses](#allowing_multiple_email_addresses) for an example, or [HTML attribute: multiple](/en-US/docs/Web/HTML/Attributes/multiple) for more details. - -> [!NOTE] -> Normally, if you specify the [`required`](/en-US/docs/Web/HTML/Element/input#required) attribute, the user must enter a valid email address for the field to be considered valid. However, if you add the `multiple` attribute, a list of zero email addresses (an empty string, or one which is entirely whitespace) is a valid value. In other words, the user does not have to enter even one email address when `multiple` is specified, regardless of the value of `required`. - -### pattern - -The `pattern` attribute, when specified, is a regular expression that the input's [`value`](/en-US/docs/Web/HTML/Element/input#value) must match for the value to pass [constraint validation](/en-US/docs/Web/HTML/Constraint_validation). It must be a valid JavaScript regular expression, as used by the {{jsxref("RegExp")}} type, and as documented in our [guide on regular expressions](/en-US/docs/Web/JavaScript/Guide/Regular_expressions); the `'u'` flag is specified when compiling the regular expression so that the pattern is treated as a sequence of Unicode code points, instead of as {{Glossary("ASCII")}}. No forward slashes should be specified around the pattern text. - -If the specified pattern is not specified or is invalid, no regular expression is applied and this attribute is ignored completely. - -> [!NOTE] -> Use the [`title`](/en-US/docs/Web/HTML/Element/input#title) attribute to specify text that most browsers will display as a tooltip to explain what the requirements are to match the pattern. You should also include other explanatory text nearby. - -See the section [Pattern validation](#pattern_validation) for details and an example. - -### `placeholder` - -The `placeholder` attribute is a string that provides a brief hint to the user as to what kind of information is expected in the field. It should be a word or short phrase that demonstrates the expected type of data, rather than an explanatory message. The text _must not_ include carriage returns or line feeds. - -If the control's content has one directionality ({{Glossary("LTR")}} or {{Glossary("RTL")}}) but needs to present the placeholder in the opposite directionality, you can use Unicode bidirectional algorithm formatting characters to override directionality within the placeholder; see [How to use Unicode controls for bidi text](https://www.w3.org/International/questions/qa-bidi-unicode-controls) for more information. - -> [!NOTE] -> Avoid using the `placeholder` attribute if you can. It is not as semantically useful as other ways to explain your form, and can cause unexpected technical issues with your content. See [`<input>` labels](/en-US/docs/Web/HTML/Element/input#labels) for more information. - -### `readonly` - -A Boolean attribute which, if present, means this field cannot be edited by the user. Its `value` can, however, still be changed by JavaScript code directly setting the {{domxref("HTMLInputElement")}} `value` property. - -> [!NOTE] -> Because a read-only field cannot have a value, `required` does not have any effect on inputs with the `readonly` attribute also specified. - -### `size` - -The `size` attribute is a numeric value indicating how many characters wide the input field should be. The value must be a number greater than zero, and the default value is 20. Since character widths vary, this may or may not be exact and should not be relied upon to be so; the resulting input may be narrower or wider than the specified number of characters, depending on the characters and the font ({{cssxref("font")}} settings in use). - -This does _not_ set a limit on how many characters the user can enter into the field. It only specifies approximately how many can be seen at a time. To set an upper limit on the length of the input data, use the [`maxlength`](#maxlength) attribute. - -## Using email inputs - -Email addresses are among the most frequently-inputted textual data forms on the web; they're used when logging into websites, when requesting information, to allow order confirmation, for webmail, and so forth. As such, the `email` input type can make your job as a web developer much easier since it can help simplify your work when building the user interface and logic for email addresses. When you create an email input with the proper `type` value, `email`, you get automatic validation that the entered text is at least in the correct form to potentially be a legitimate email address. This can help avoid cases in which the user mistypes their address, or provides an invalid address. - -It's important, however, to note that this is not enough to ensure that the specified text is an email address which actually exists, corresponds to the user of the site, or is acceptable in any other way. It ensures that the value of the field is properly formatted to be an email address. - -> [!NOTE] -> It's also crucial to remember that a user can tinker with your HTML behind the scenes, so your site _must not_ use this validation for any security purposes. You _must_ verify the email address on the server side of any transaction in which the provided text may have any security implications of any kind. - -### A basic email input - -Currently, all browsers which implement this element implement it as a standard text input field with basic validation features. The specification does, however, allow browsers latitude on this. For example, the element could be integrated with the user's device's built-in address book to allow picking email addresses from that list. In its most basic form, an `email` input can be implemented like this: - -```html -<input id="emailAddress" type="email" /> -``` - -{{ EmbedLiveSample('A_basic_email_input', 600, 40) }} - -Notice that it's considered valid when empty and when a single validly-formatted email address is entered, but is otherwise not considered valid. By adding the [`required`](/en-US/docs/Web/HTML/Element/input#required) attribute, only validly-formed email addresses are allowed; the input is no longer considered valid when empty. - -### Allowing multiple email addresses - -By adding the [`multiple`](/en-US/docs/Web/HTML/Attributes/multiple) Boolean attribute, the input can be configured to accept multiple email addresses. - -```html -<input id="emailAddress" type="email" multiple /> -``` - -{{ EmbedLiveSample('Allowing multiple email addresses', 600, 40) }} - -The input is now considered valid when a single email address is entered, or when any number of email addresses separated by commas and, optionally, some number of whitespace characters are present. - -> [!NOTE] -> When `multiple` is used, the value _is_ allowed to be empty. - -Some examples of valid strings when `multiple` is specified: - -- `""` -- `"me@example"` -- `"me@example.org"` -- `"me@example.org,you@example.org"` -- `"me@example.org, you@example.org"` -- `"me@example.org,you@example.org, us@example.org"` - -Some examples of invalid strings: - -- `","` -- `"me"` -- `"me@example.org you@example.org"` - -### Placeholders - -Sometimes it's helpful to offer an in-context hint as to what form the input data should take. This can be especially important if the page design doesn't offer descriptive labels for each {{HTMLElement("input")}}. This is where **placeholders** come in. A placeholder is a value that demonstrates the form the `value` should take by presenting an example of a valid value, which is displayed inside the edit box when the element's `value` is "". Once data is entered into the box, the placeholder disappears; if the box is emptied, the placeholder reappears. - -Here, we have an `email` input with the placeholder `sophie@example.com`. Note how the placeholder disappears and reappears as you manipulate the contents of the edit field. - -```html -<input type="email" placeholder="sophie@example.com" /> -``` - -{{ EmbedLiveSample('Placeholders', 600, 40) }} - -### Controlling the input size - -You can control not only the physical length of the input box, but also the minimum and maximum lengths allowed for the input text itself. - -#### Physical input element size - -The physical size of the input box can be controlled using the [`size`](/en-US/docs/Web/HTML/Element/input#size) attribute. With it, you can specify the number of characters the input box can display at a time. In this example the `email` edit box is 15 characters wide: - -```html -<input type="email" size="15" /> -``` - -{{ EmbedLiveSample('Physical_input_element_size', 600, 40) }} - -#### Element value length - -The `size` is separate from the length limitation on the entered email address itself so that you can have fields fit in a small space while still allowing longer email address strings to be entered. You can specify a minimum length, in characters, for the entered email address using the [`minlength`](/en-US/docs/Web/HTML/Element/input#minlength) attribute; similarly, use [`maxlength`](/en-US/docs/Web/HTML/Element/input#maxlength) to set the maximum length of the entered email address. - -The example below creates a 32 character-wide email address entry box, requiring that the contents be no shorter than 3 characters and no longer than 64 characters. - -```html -<input type="email" size="32" minlength="3" maxlength="64" /> -``` - -{{EmbedLiveSample("Element_value_length", 600, 40) }} - -### Providing default options - -#### Providing a single default using the value attribute - -As always, you can provide a default value for an `email` input box by setting its [`value`](/en-US/docs/Web/HTML/Element/input#value) attribute: - -```html -<input type="email" value="default@example.com" /> -``` - -{{EmbedLiveSample("Providing_a_single_default_using_the_value_attribute", 600, 40)}} - -#### Offering suggested values - -Taking it a step further, you can provide a list of default options from which the user can select by specifying the [`list`](/en-US/docs/Web/HTML/Element/input#list) attribute. This doesn't limit the user to those options, but does allow them to select commonly-used email addresses more quickly. This also offers hints to [`autocomplete`](/en-US/docs/Web/HTML/Element/input#autocomplete). The `list` attribute specifies the ID of a {{HTMLElement("datalist")}}, which in turn contains one {{HTMLElement("option")}} element per suggested value; each `option`'s `value` is the corresponding suggested value for the email entry box. - -```html -<input type="email" size="40" list="defaultEmails" /> - -<datalist id="defaultEmails"> - <option value="jbond007@mi6.defence.gov.uk"></option> - <option value="jbourne@unknown.net"></option> - <option value="nfury@shield.org"></option> - <option value="tony@starkindustries.com"></option> - <option value="hulk@grrrrrrrr.arg"></option> -</datalist> -``` - -{{EmbedLiveSample("Offering_suggested_values", 600, 40)}} - -With the {{HTMLElement("datalist")}} element and its {{HTMLElement("option")}}s in place, the browser will offer the specified values as potential values for the email address; this is typically presented as a popup or drop-down menu containing the suggestions. While the specific user experience may vary from one browser to another, typically clicking in the edit box presents a drop-down of the suggested email addresses. Then, as the user types, the list is filtered to show only matching values. Each typed character narrows down the list until the user makes a selection or types a custom value. - -## Validation - -There are two levels of content validation available for `email` inputs. First, there's the standard level of validation offered to all {{HTMLElement("input")}}s, which automatically ensures that the contents meet the requirements to be a valid email address. But there's also the option to add additional filtering to ensure that your own specialized needs are met, if you have any. - -> [!WARNING] -> HTML form validation is _not_ a substitute for scripts that ensure that the entered data is in the proper format. It's far too easy for someone to make adjustments to the HTML that allow them to bypass the validation, or to remove it completely. It's also possible for someone to bypass your HTML entirely and submit the data directly to your server. If your server-side code fails to validate the data it receives, disaster could strike when improperly-formatted data (or data which is too large, is of the wrong type, and so forth) is entered into your database. - -### Basic validation - -Browsers automatically provide validation to ensure that only text that matches the standard format for Internet email addresses is entered into the input box. Browsers use an algorithm equivalent to the following regular expression: - -```js -/^[a-zA-Z0-9.!#$%&'*+/=?^_`{|}~-]+@[a-zA-Z0-9](?:[a-zA-Z0-9-]{0,61}[a-zA-Z0-9])?(?:\.[a-zA-Z0-9](?:[a-zA-Z0-9-]{0,61}[a-zA-Z0-9])?)*$/; -``` - -To learn more about how form validation works and how to take advantage of the {{cssxref(":valid")}} and {{cssxref(":invalid")}} CSS properties to style the input based on whether the current value is valid, see [Form data validation](/en-US/docs/Learn_web_development/Extensions/Forms/Form_validation). - -> [!NOTE] -> There are known specification issues related to international domain names and the validation of email addresses in HTML. See [W3C bug 15489](https://www.w3.org/Bugs/Public/show_bug.cgi?id=15489) for details. - -### Pattern validation - -If you need the entered email address to be restricted further than just "any string that looks like an email address," you can use the [`pattern`](/en-US/docs/Web/HTML/Element/input#pattern) attribute to specify a {{Glossary("regular expression")}} the value must match for it to be valid. If the [`multiple`](/en-US/docs/Web/HTML/Element/input#multiple) attribute is specified, each individual item in the comma-delineated list of values must match the {{Glossary("regular expression")}}. - -For example, let's say you're building a page for employees of Best Startup Ever, Inc. which will let them contact their IT department for help. In our simplified form, the user needs to enter their email address and a message describing the problem they need help with. We want to ensure that not only does the user provide a valid email address, but for security purposes, we require that the address be an internal corporate email address. - -Since inputs of type `email` validate against both the standard email address validation _and_ the specified [`pattern`](/en-US/docs/Web/HTML/Element/input#pattern), you can implement this easily. Let's see how: - -```css hidden -body { - font: 16px sans-serif; -} - -.emailBox { - padding-bottom: 20px; -} - -.messageBox { - padding-bottom: 20px; -} - -label { - line-height: 22px; -} - -label::after { - content: ":"; -} -``` - -```html -<form> - <div class="emailBox"> - <label for="emailAddress">Your email address</label><br /> - <input - id="emailAddress" - type="email" - size="64" - maxlength="64" - required - placeholder="username@beststartupever.com" - pattern=".+@beststartupever\.com" - title="Please provide only a Best Startup Ever corporate email address" /> - </div> - - <div class="messageBox"> - <label for="message">Request</label><br /> - <textarea - id="message" - cols="80" - rows="8" - required - placeholder="My shoes are too tight, and I have forgotten how to dance."></textarea> - </div> - <input type="submit" value="Send Request" /> -</form> -``` - -{{EmbedLiveSample("Pattern_validation", 700, 300)}} - -Our {{HTMLElement("form")}} contains one {{HTMLElement("input")}} of type `email` for the user's email address, a {{HTMLElement("textarea")}} to enter their message for IT into, and an `<input>` of type [`"submit"`](/en-US/docs/Web/HTML/Element/input/submit), which creates a button to submit the form. Each text entry box has a {{HTMLElement("label")}} associated with it to let the user know what's expected of them. - -Let's take a closer look at the email address entry box. Its [`size`](/en-US/docs/Web/HTML/Element/input#size) and [`maxlength`](/en-US/docs/Web/HTML/Element/input#maxlength) attributes are both set to 64 in order to show room for 64 characters worth of email address, and to limit the number of characters actually entered to a maximum of 64. The [`required`](/en-US/docs/Web/HTML/Element/input#required) attribute is specified, making it mandatory that a valid email address be provided. - -An appropriate [`placeholder`](/en-US/docs/Web/HTML/Element/input#placeholder) is provided—`username@beststartupever.com`—to demonstrate what constitutes a valid entry. This string demonstrates both that an email address should be entered, and suggests that it should be a corporate beststartupever.com account. This is in addition to the fact that using type `email` will validate the text to ensure that it's formatted like an email address. If the text in the input box isn't an email address, you'll get an error message that looks something like this: - -![Invalid email address in error state with a popout from the input reading 'please enter an email address'.](enter-valid-email-address.png) - -If we left things at that, we would at least be validating on legitimate email addresses. But we want to go one step farther: we want to make sure that the email address is in fact in the form `[username]@beststartupever.com`. This is where we'll use [`pattern`](/en-US/docs/Web/HTML/Element/input#pattern). We set `pattern` to `.+@beststartupever.com`. This regular expression requests a string that consists of at least one character of any kind, then an "@" followed by the domain name "beststartupever.com". - -Note that this is not even close to an adequate filter for valid email addresses; it would allow things such as " @beststartupever.com" (note the leading space) or "@@beststartupever.com", neither of which is valid. However, the browser runs both the standard email address filter _and_ our custom pattern against the specified text. As a result, we wind up with a validation which says "make sure this resembles a valid email address, and if it is, make sure it's also a beststartupever.com address." - -It's advisable to use the [`title`](/en-US/docs/Web/HTML/Global_attributes/title) attribute along with `pattern`. If you do, the `title` _must_ describe the pattern. That is, it should explain what format the data should take on, rather than any other information. That's because the `title` may be displayed or spoken as part of a validation error message. For example, the browser might present the message "The entered text doesn't match the required pattern." followed by your specified `title`. If your `title` is something like "Email address", the result would be the message "The entered text doesn't match the required pattern. Email address", which isn't very good. - -That's why, instead, we specify the string "Please provide only a Best Startup Ever corporate email address" By doing that, the resulting full error message might be something like "The entered text doesn't match the required pattern. Please provide only a Best Startup Ever corporate email address." - -![A valid email address, but the input is in error state with a popout from the input reading 'The entered text doesn't match the required pattern. Please provide only a Best Startup Ever corporate email address.'](email-pattern-match-bad.png) - -> [!NOTE] -> If you run into trouble while writing your validation regular expressions and they're not working properly, check your browser's console; there may be helpful error messages there to aid you in solving the problem. - -## Examples - -Here we have an email input with the ID `emailAddress` which is allowed to be up to a maximum of 256 characters long. The input box itself is physically 64 characters wide, and displays the text `user@example.gov` as a placeholder anytime the field is empty. In addition, by using the [`multiple`](/en-US/docs/Web/HTML/Attributes/multiple) attribute, the box is configured to allow the user to enter zero or more email addresses, separated by commas, as described in [Allowing multiple email addresses](#allowing_multiple_email_addresses). As a final touch, the [`list`](/en-US/docs/Web/HTML/Element/input#list) attribute contains the ID of a {{HTMLElement("datalist")}} whose {{HTMLElement("option")}}s specify a set of suggested values the user can choose from. - -As an added touch, the {{HTMLElement("label")}} element is used to establish a label for the email entry box, with its [`for`](/en-US/docs/Web/HTML/Element/label#for) attribute referencing the `emailAddress` ID of the {{HTMLElement("input")}} element. By associating the two elements in this way, clicking on the label will focus the input element. - -```html -<label for="emailAddress">Email</label><br /> -<input - id="emailAddress" - type="email" - placeholder="user@example.gov" - list="defaultEmails" - size="64" - maxlength="256" - multiple /> - -<datalist id="defaultEmails"> - <option value="jbond007@mi6.defence.gov.uk"></option> - <option value="jbourne@unknown.net"></option> - <option value="nfury@shield.org"></option> - <option value="tony@starkindustries.com"></option> - <option value="hulk@grrrrrrrr.arg"></option> -</datalist> -``` - -{{EmbedLiveSample('Examples', 600, 80)}} - -## Technical summary - -<table class="properties"> - <tbody> - <tr> - <td><strong><a href="#value">Value</a></strong></td> - <td> - A string representing an email address, or - empty - </td> - </tr> - <tr> - <td><strong>Events</strong></td> - <td> - {{domxref("HTMLElement/change_event", "change")}} and - {{domxref("Element/input_event", "input")}} - </td> - </tr> - <tr> - <td><strong>Supported Common Attributes</strong></td> - <td> - <a href="/en-US/docs/Web/HTML/Element/input#autocomplete"><code>autocomplete</code></a>, - <a href="/en-US/docs/Web/HTML/Element/input#list"><code>list</code></a>, - <a href="/en-US/docs/Web/HTML/Element/input#maxlength"><code>maxlength</code></a>, - <a href="/en-US/docs/Web/HTML/Element/input#minlength"><code>minlength</code></a>, - <a href="/en-US/docs/Web/HTML/Element/input#multiple"><code>multiple</code></a>, - <a href="/en-US/docs/Web/HTML/Element/input#name"><code>name</code></a>, - <a href="/en-US/docs/Web/HTML/Element/input#pattern"><code>pattern</code></a>, - <a href="/en-US/docs/Web/HTML/Element/input#placeholder"><code>placeholder</code></a>, - <a href="/en-US/docs/Web/HTML/Element/input#readonly"><code>readonly</code></a>, - <a href="/en-US/docs/Web/HTML/Element/input#required"><code>required</code></a>, - <a href="/en-US/docs/Web/HTML/Element/input#size"><code>size</code></a>, and - <a href="/en-US/docs/Web/HTML/Element/input#type"><code>type</code></a> - </td> - </tr> - <tr> - <td><strong>IDL attributes</strong></td> - <td><code>list</code> and <code>value</code></td> - </tr> - <tr> - <td><strong>DOM interface</strong></td> - <td><p>{{domxref("HTMLInputElement")}}</p></td> - </tr> - <tr> - <td><strong>Methods</strong></td> - <td> - {{domxref("HTMLInputElement.select", "select()")}} - </td> - </tr> - <tr> - <td><strong>Implicit ARIA Role</strong></td> - <td> - with no <code>list</code> attribute: - <code><a href="/en-US/docs/Web/Accessibility/ARIA/Roles/textbox_role">textbox</a></code><br /> - with <code>list</code> attribute: <code><a href="/en-US/docs/Web/Accessibility/ARIA/Roles/combobox_role">combobox</a></code> - </td> - </tr> - </tbody> -</table> - -## Specifications - -{{Specifications}} - -## Browser compatibility - -{{Compat}} - -## See also - -- [HTML forms guide](/en-US/docs/Learn_web_development/Extensions/Forms) -- {{HTMLElement("input")}} -- [`<input type="tel">`](/en-US/docs/Web/HTML/Element/input/tel) -- [`<input type="url">`](/en-US/docs/Web/HTML/Element/input/url) -- Attributes: - - [`list`](/en-US/docs/Web/HTML/Element/input#list) - - [`minlength`](/en-US/docs/Web/HTML/Attributes/minlength) - - [`maxlength`](/en-US/docs/Web/HTML/Attributes/maxlength) - - [`multiple`](/en-US/docs/Web/HTML/Attributes/multiple) - - [`pattern`](/en-US/docs/Web/HTML/Attributes/pattern) - - [`placeholder`](/en-US/docs/Web/HTML/Element/input#placeholder) - - [`readonly`](/en-US/docs/Web/HTML/Attributes/readonly) - - [`size`](/en-US/docs/Web/HTML/Attributes/size) diff --git a/files/en-us/web/html/element/input/file/index.md b/files/en-us/web/html/element/input/file/index.md deleted file mode 100644 index b938e6e94057ff7..000000000000000 --- a/files/en-us/web/html/element/input/file/index.md +++ /dev/null @@ -1,502 +0,0 @@ ---- -title: <input type="file"> -slug: Web/HTML/Element/input/file -page-type: html-element -browser-compat: html.elements.input.type_file ---- - -{{HTMLSidebar}} - -{{HTMLElement("input")}} elements with **`type="file"`** let the user choose one or more files from their device storage. Once chosen, the files can be uploaded to a server using [form submission](/en-US/docs/Learn_web_development/Extensions/Forms), or manipulated using JavaScript code and [the File API](/en-US/docs/Web/API/File_API/Using_files_from_web_applications). - -{{InteractiveExample("HTML Demo: &lt;input type=&quot;file&quot;&gt;", "tabbed-shorter")}} - -```html interactive-example -<label for="avatar">Choose a profile picture:</label> - -<input type="file" id="avatar" name="avatar" accept="image/png, image/jpeg" /> -``` - -```css interactive-example -label { - display: block; - font: - 1rem "Fira Sans", - sans-serif; -} - -input, -label { - margin: 0.4rem 0; -} -``` - -## Value - -A file input's [`value`](/en-US/docs/Web/HTML/Element/input#value) attribute contains a string that represents the path to the selected file(s). If no file is selected yet, the value is an empty string (`""`). When the user selected multiple files, the `value` represents the first file in the list of files they selected. The other files can be identified using the [input's `HTMLInputElement.files` property](/en-US/docs/Web/API/File_API/Using_files_from_web_applications#getting_information_about_selected_files). - -> [!NOTE] -> The value is [always the file's name prefixed with `C:\fakepath\`](https://html.spec.whatwg.org/multipage/input.html#fakepath-srsly), which isn't the real path of the file. This is to prevent malicious software from guessing the user's file structure. - -## Additional attributes - -In addition to the common attributes shared by all {{HTMLElement("input")}} elements, inputs of type `file` also support the following attributes. - -### accept - -The [`accept`](/en-US/docs/Web/HTML/Attributes/accept) attribute value is a string that defines the file types the file input should accept. This string is a comma-separated list of **[unique file type specifiers](#unique_file_type_specifiers)**. Because a given file type may be identified in more than one manner, it's useful to provide a thorough set of type specifiers when you need files of a given format. - -For instance, there are a number of ways Microsoft Word files can be identified, so a site that accepts Word files might use an `<input>` like this: - -```html -<input - type="file" - id="docpicker" - accept=".doc,.docx,.xml,application/msword,application/vnd.openxmlformats-officedocument.wordprocessingml.document" /> -``` - -### capture - -The [`capture`](/en-US/docs/Web/HTML/Attributes/capture) attribute value is a string that specifies which camera to use for capture of image or video data, if the [`accept`](/en-US/docs/Web/HTML/Attributes/accept) attribute indicates that the input should be of one of those types. A value of `user` indicates that the user-facing camera and/or microphone should be used. A value of `environment` specifies that the outward-facing camera and/or microphone should be used. If this attribute is missing, the {{Glossary("user agent")}} is free to decide on its own what to do. If the requested facing mode isn't available, the user agent may fall back to its preferred default mode. - -> **Note:** `capture` was previously a Boolean attribute which, if present, requested that the device's media capture device(s) such as camera or microphone be used instead of requesting a file input. - -### multiple - -When the [`multiple`](/en-US/docs/Web/HTML/Attributes/multiple) Boolean attribute is specified, the file input allows the user to select more than one file. - -## Non-standard attributes - -In addition to the attributes listed above, the following non-standard attributes are available on some browsers. You should try to avoid using them when possible, since doing so will limit the ability of your code to function in browsers that don't implement them. - -### `webkitdirectory` - -The Boolean `webkitdirectory` attribute, if present, indicates that only directories should be available to be selected by the user in the file picker interface. See {{domxref("HTMLInputElement.webkitdirectory")}} for additional details and examples. - -Though originally implemented only for WebKit-based browsers, `webkitdirectory` is also usable in Firefox. However, even though it has relatively broad support, it is still not standard and should not be used unless you have no alternative. - -## Unique file type specifiers - -A **unique file type specifier** is a string that describes a type of file that may be selected by the user in an {{HTMLElement("input")}} element of type `file`. Each unique file type specifier may take one of the following forms: - -- A valid case-insensitive filename extension, starting with a period (".") character. For example: `.jpg`, `.pdf`, or `.doc`. -- A valid MIME type string, with no extensions. -- The string `audio/*` meaning "any audio file". -- The string `video/*` meaning "any video file". -- The string `image/*` meaning "any image file". - -The `accept` attribute takes a string containing one or more of these unique file type specifiers as its value, separated by commas. For example, a file picker that needs content that can be presented as an image, including both standard image formats and PDF files, might look like this: - -```html -<input type="file" accept="image/*,.pdf" /> -``` - -## Using file inputs - -### A basic example - -```html -<form method="post" enctype="multipart/form-data"> - <div> - <label for="file">Choose file to upload</label> - <input type="file" id="file" name="file" multiple /> - </div> - <div> - <button>Submit</button> - </div> -</form> -``` - -```css hidden -div { - margin-bottom: 10px; -} -``` - -This produces the following output: - -{{EmbedLiveSample('A_basic_example', 650, 90)}} - -> [!NOTE] -> You can find this example on GitHub too — see the [source code](https://github.com/mdn/learning-area/blob/main/html/forms/file-examples/simple-file.html), and also [see it running live](https://mdn.github.io/learning-area/html/forms/file-examples/simple-file.html). - -Regardless of the user's device or operating system, the file input provides a button that opens up a file picker dialog that allows the user to choose a file. - -Including the [`multiple`](#multiple) attribute, as shown above, specifies that multiple files can be chosen at once. The user can choose multiple files from the file picker in any way that their chosen platform allows (e.g. by holding down <kbd>Shift</kbd> or <kbd>Control</kbd> and then clicking). If you only want the user to choose a single file per `<input>`, omit the `multiple` attribute. - -### Getting information on selected files - -The selected files' are returned by the element's `HTMLInputElement.files` property, which is a {{domxref("FileList")}} object containing a list of {{domxref("File")}} objects. The `FileList` behaves like an array, so you can check its `length` property to get the number of selected files. - -Each `File` object contains the following information: - -- `name` - - : The file's name. -- `lastModified` - - : A number specifying the date and time at which the file was last modified, in milliseconds since the UNIX epoch (January 1, 1970, at midnight). -- `lastModifiedDate` {{deprecated_inline}} - - : A {{jsxref("Date")}} object representing the date and time at which the file was last modified. _This is deprecated and should not be used. Use `lastModified` instead._ -- `size` - - : The size of the file in bytes. -- `type` - - : The file's [MIME type](/en-US/docs/Web/HTTP/MIME_types). -- `webkitRelativePath` {{non-standard_inline}} - - : A string specifying the file's path relative to the base directory selected in a directory picker (that is, a `file` picker in which the [`webkitdirectory`](#webkitdirectory) attribute is set). _This is non-standard and should be used with caution._ - -### Limiting accepted file types - -Often you won't want the user to be able to pick any arbitrary type of file; instead, you often want them to select files of a specific type or types. For example, if your file input lets users upload a profile picture, you probably want them to select web-compatible image formats, such as {{Glossary("JPEG")}} or {{Glossary("PNG")}}. - -Acceptable file types can be specified with the [`accept`](#accept) attribute, which takes a comma-separated list of allowed file extensions or MIME types. Some examples: - -- `accept="image/png"` or `accept=".png"` — Accepts PNG files. -- `accept="image/png, image/jpeg"` or `accept=".png, .jpg, .jpeg"` — Accept PNG or JPEG files. -- `accept="image/*"` — Accept any file with an `image/*` MIME type. (Many mobile devices also let the user take a picture with the camera when this is used.) -- `accept=".doc,.docx,.xml,application/msword,application/vnd.openxmlformats-officedocument.wordprocessingml.document"` — accept anything that smells like an MS Word document. - -Let's look at a more complete example: - -```html -<form method="post" enctype="multipart/form-data"> - <div> - <label for="profile_pic">Choose file to upload</label> - <input - type="file" - id="profile_pic" - name="profile_pic" - accept=".jpg, .jpeg, .png" /> - </div> - <div> - <button>Submit</button> - </div> -</form> -``` - -```css hidden -div { - margin-bottom: 10px; -} -``` - -This produces a similar-looking output to the previous example: - -{{EmbedLiveSample('Limiting_accepted_file_types', 650, 90)}} - -> [!NOTE] -> You can find this example on GitHub too — see the [source code](https://github.com/mdn/learning-area/blob/main/html/forms/file-examples/file-with-accept.html), and also [see it running live](https://mdn.github.io/learning-area/html/forms/file-examples/file-with-accept.html). - -It may look similar, but if you try selecting a file with this input, you'll see that the file picker only lets you select the file types specified in the `accept` value (the exact interface differs across browsers and operating systems). - -The `accept` attribute doesn't validate the types of the selected files; it provides hints for browsers to guide users towards selecting the correct file types. It is still possible (in most cases) for users to toggle an option in the file chooser that makes it possible to override this and select any file they wish, and then choose incorrect file types. - -Because of this, you should make sure that the `accept` attribute is backed up by appropriate server-side validation. - -### Detecting cancellations - -The `cancel` event is fired when the user does not change their selection, reselecting the previously selected files. The `cancel` event is also fired when the file picker dialog gets closed, or canceled, via the "cancel" button or the <kbd>escape</kbd> key. - -For example, the following code will log to the console if the user closes the popup without selecting a file: - -```js -const elem = document.createElement("input"); -elem.type = "file"; -elem.addEventListener("cancel", () => { - console.log("Cancelled."); -}); -elem.addEventListener("change", () => { - if (elem.files.length == 1) { - console.log("File selected: ", elem.files[0]); - } -}); -elem.click(); -``` - -### Notes - -1. You cannot set the value of a file picker from a script — doing something like the following has no effect: - - ```js - const input = document.querySelector("input[type=file]"); - input.value = "foo"; - ``` - -2. When a file is chosen using an `<input type="file">`, the real path to the source file is not shown in the input's `value` attribute for obvious security reasons. Instead, the filename is shown, with `C:\fakepath\` prepended to it. There are some historical reasons for this quirk, but it is supported across all modern browsers, and in fact is [defined in the spec](https://html.spec.whatwg.org/multipage/forms.html#fakepath-srsly). - -## Examples - -In this example, we'll present a slightly more advanced file chooser that takes advantage of the file information available in the `HTMLInputElement.files` property, as well as showing off a few clever tricks. - -> [!NOTE] -> You can see the complete source code for this example on GitHub — [file-example.html](https://github.com/mdn/learning-area/blob/main/html/forms/file-examples/file-example.html) ([see it live also](https://mdn.github.io/learning-area/html/forms/file-examples/file-example.html)). We won't explain the CSS; the JavaScript is the main focus. - -First of all, let's look at the HTML: - -```html -<form method="post" enctype="multipart/form-data"> - <div> - <label for="image_uploads">Choose images to upload (PNG, JPG)</label> - <input - type="file" - id="image_uploads" - name="image_uploads" - accept=".jpg, .jpeg, .png" - multiple /> - </div> - <div class="preview"> - <p>No files currently selected for upload</p> - </div> - <div> - <button>Submit</button> - </div> -</form> -``` - -```css hidden -html { - font-family: sans-serif; -} - -form { - background: #ccc; - margin: 0 auto; - padding: 20px; - border: 1px solid black; -} - -form ol { - padding-left: 0; -} - -form li, -div > p { - background: #eee; - display: flex; - justify-content: space-between; - margin-bottom: 10px; - list-style-type: none; - border: 1px solid black; -} - -form img { - height: 64px; - order: 1; -} - -form p { - line-height: 32px; - padding-left: 10px; -} - -form label, -form button { - background-color: #7f9ccb; - padding: 5px 10px; - border-radius: 5px; - border: 1px ridge black; - font-size: 0.8rem; - height: auto; -} - -form label:hover, -form button:hover { - background-color: #2d5ba3; - color: white; -} - -form label:active, -form button:active { - background-color: #0d3f8f; - color: white; -} -``` - -This is similar to what we've seen before — nothing special to comment on. - -Next, let's walk through the JavaScript. - -In the first lines of script, we get references to the form input itself, and the {{htmlelement("div")}} element with the class of `.preview`. Next, we hide the {{htmlelement("input")}} element — we do this because file inputs tend to be ugly, difficult to style, and inconsistent in their design across browsers. You can activate the `input` element by clicking its {{htmlelement("label")}}, so it is better to visually hide the `input` and style the label like a button, so the user will know to interact with it if they want to upload files. - -```js -const input = document.querySelector("input"); -const preview = document.querySelector(".preview"); - -input.style.opacity = 0; -``` - -> **Note:** {{cssxref("opacity")}} is used to hide the file input instead of {{cssxref("visibility", "visibility: hidden")}} or {{cssxref("display", "display: none")}}, because assistive technology interprets the latter two styles to mean the file input isn't interactive. - -Next, we add an [event listener](/en-US/docs/Web/API/EventTarget/addEventListener) to the input to listen for changes to its selected value (in this case, when files are selected). The event listener invokes our custom `updateImageDisplay()` function. - -```js -input.addEventListener("change", updateImageDisplay); -``` - -Whenever the `updateImageDisplay()` function is invoked, we: - -- Use a {{jsxref("Statements/while", "while")}} loop to empty the previous contents of the preview `<div>`. -- Grab the {{domxref("FileList")}} object that contains the information on all the selected files, and store it in a variable called `curFiles`. -- Check to see if no files were selected, by checking if `curFiles.length` is equal to 0. If so, print a message into the preview `<div>` stating that no files have been selected. -- If files _have_ been selected, we loop through each one, printing information about it into the preview `<div>`. Things to note here: -- We use the custom `validFileType()` function to check whether the file is of the correct type (e.g. the image types specified in the `accept` attribute). -- If it is, we: - - - Print out its name and file size into a list item inside the previous `<div>` (obtained from `file.name` and `file.size`). The custom `returnFileSize()` function returns a nicely-formatted version of the size in bytes/KB/MB (by default the browser reports the size in absolute bytes). - - Generate a thumbnail preview of the image by calling {{domxref("URL/createObjectURL_static", "URL.createObjectURL(file)")}}. Then, insert the image into the list item too by creating a new {{htmlelement("img")}} and setting its [`src`](/en-US/docs/Web/HTML/Element/img#src) to the thumbnail. - -- If the file type is invalid, we display a message inside a list item telling the user that they need to select a different file type. - -```js -function updateImageDisplay() { - while (preview.firstChild) { - preview.removeChild(preview.firstChild); - } - - const curFiles = input.files; - if (curFiles.length === 0) { - const para = document.createElement("p"); - para.textContent = "No files currently selected for upload"; - preview.appendChild(para); - } else { - const list = document.createElement("ol"); - preview.appendChild(list); - - for (const file of curFiles) { - const listItem = document.createElement("li"); - const para = document.createElement("p"); - if (validFileType(file)) { - para.textContent = `File name ${file.name}, file size ${returnFileSize( - file.size, - )}.`; - const image = document.createElement("img"); - image.src = URL.createObjectURL(file); - image.alt = image.title = file.name; - - listItem.appendChild(image); - listItem.appendChild(para); - } else { - para.textContent = `File name ${file.name}: Not a valid file type. Update your selection.`; - listItem.appendChild(para); - } - - list.appendChild(listItem); - } - } -} -``` - -The custom `validFileType()` function takes a {{domxref("File")}} object as a parameter, then uses {{jsxref("Array.prototype.includes()")}} to check if any value in the `fileTypes` matches the file's `type` property. If a match is found, the function returns `true`. If no match is found, it returns `false`. - -```js -// https://developer.mozilla.org/en-US/docs/Web/Media/Guides/Formats/Image_types -const fileTypes = [ - "image/apng", - "image/bmp", - "image/gif", - "image/jpeg", - "image/pjpeg", - "image/png", - "image/svg+xml", - "image/tiff", - "image/webp", - "image/x-icon", -]; - -function validFileType(file) { - return fileTypes.includes(file.type); -} -``` - -The `returnFileSize()` function takes a number (of bytes, taken from the current file's `size` property), and turns it into a nicely formatted size in bytes/KB/MB. - -```js -function returnFileSize(number) { - if (number < 1e3) { - return `${number} bytes`; - } else if (number >= 1e3 && number < 1e6) { - return `${(number / 1e3).toFixed(1)} KB`; - } else { - return `${(number / 1e6).toFixed(1)} MB`; - } -} -``` - -> [!NOTE] -> The "KB" and "MB" units here use the [SI prefix](https://en.wikipedia.org/wiki/Binary_prefix) convention of 1KB = 1000B, similar to macOS. Different systems represent file sizes differently—for example, Ubuntu uses IEC prefixes where 1KiB = 1024B, while RAM specifications often use SI prefixes to represent powers of two (1KB = 1024B). For this reason, we used `1e3` (`1000`) and `1e6` (`100000`) instead of `1024` and `1048576`. In your application, you should communicate the unit system clearly to your users if the exact size is important. - -```js hidden -const button = document.querySelector("form button"); -button.addEventListener("click", (e) => { - e.preventDefault(); - const para = document.createElement("p"); - para.append("Image uploaded!"); - preview.replaceChildren(para); -}); -``` - -The example looks like this; have a play: - -{{EmbedLiveSample('Examples', '100%', 200)}} - -## Technical summary - -<table class="properties"> - <tbody> - <tr> - <td><strong><a href="#value">Value</a></strong></td> - <td> - A string representing the path to the selected - file. - </td> - </tr> - <tr> - <td><strong>Events</strong></td> - <td> - {{domxref("HTMLElement/change_event", "change")}}, - {{domxref("Element/input_event", "input")}} and - {{domxref("HTMLInputElement/cancel_event", "cancel")}} - </td> - </tr> - <tr> - <td><strong>Supported common attributes</strong></td> - <td><a href="/en-US/docs/Web/HTML/Element/input#required"><code>required</code></a></td> - </tr> - <tr> - <td><strong>Additional Attributes</strong></td> - <td> - <a href="#accept" aria-current="page"><code>accept</code></a>, - <a href="#capture" aria-current="page"><code>capture</code></a>, - <a href="#multiple" aria-current="page"><code>multiple</code></a> - </td> - </tr> - <tr> - <td><strong>IDL attributes</strong></td> - <td><code>files</code> and <code>value</code></td> - </tr> - <tr> - <td><strong>DOM interface</strong></td> - <td><p>{{domxref("HTMLInputElement")}}</p></td> - </tr> - <tr> - <td><strong>Methods</strong></td> - <td> - {{domxref("HTMLInputElement.select", "select()")}} - </td> - </tr> - <tr> - <td><strong>Implicit ARIA Role</strong></td> - <td><a href="https://www.w3.org/TR/html-aria/#dfn-no-corresponding-role">no corresponding role</a></td> - </tr> - </tbody> -</table> - -## Specifications - -{{Specifications}} - -## Browser compatibility - -{{Compat}} - -## See also - -- [Using files from web applications](/en-US/docs/Web/API/File_API/Using_files_from_web_applications) — contains a number of other useful examples related to `<input type="file">` and the [File API](/en-US/docs/Web/API/File). diff --git a/files/en-us/web/html/element/input/hidden/index.md b/files/en-us/web/html/element/input/hidden/index.md deleted file mode 100644 index 6fc8ba6ab0f7107..000000000000000 --- a/files/en-us/web/html/element/input/hidden/index.md +++ /dev/null @@ -1,184 +0,0 @@ ---- -title: <input type="hidden"> -slug: Web/HTML/Element/input/hidden -page-type: html-element -browser-compat: html.elements.input.type_hidden ---- - -{{HTMLSidebar}} - -{{HTMLElement("input")}} elements of type **`hidden`** let web developers include data that cannot be seen or modified by users when a form is submitted. For example, the ID of the content that is currently being ordered or edited, or a unique security token. Hidden inputs are completely invisible in the rendered page, and there is no way to make it visible in the page's content. - -> [!NOTE] -> The {{domxref("Element/input_event", "input")}} and {{domxref("HTMLElement/change_event", "change")}} events do not apply to this input type. Hidden inputs cannot be focused even using JavaScript (e.g. `hiddenInput.focus()`). - -## Value - -The {{HTMLElement("input")}} element's [`value`](/en-US/docs/Web/HTML/Element/input#value) attribute holds a string that contains the hidden data you want to include when the form is submitted to the server. This specifically can't be edited or seen by the user via the user interface, although you could edit the value via browser developer tools. - -> [!WARNING] -> While the value isn't displayed to the user in the page's content, it is visible—and can be edited—using any browser's developer tools or "View Source" functionality. Do not rely on `hidden` inputs as a form of security. - -## Additional attributes - -In addition to the attributes common to all {{HTMLElement("input")}} elements, `hidden` inputs offer the following attributes. - -### name - -This is actually one of the common attributes, but it has a special meaning available for hidden inputs. Normally, the [`name`](/en-US/docs/Web/HTML/Element/input#name) attribute functions on hidden inputs just like on any other input. However, when the form is submitted, a hidden input whose `name` is set to `_charset_` will automatically be reported with the value set to the character encoding used to submit the form. - -## Using hidden inputs - -As mentioned above, hidden inputs can be used anywhere that you want to include data the user can't see or edit along with the form when it's submitted to the server. Let's look at some examples that illustrate its use. - -### Tracking edited content - -One of the most common uses for hidden inputs is to keep track of what database record needs to be updated when an edit form is submitted. A typical workflow looks like this: - -1. User decides to edit some content they have control over, such as a blog post, or a product entry. They get started by pressing the edit button. -2. The content to be edited is taken from the database and loaded into an HTML form to allow the user to make changes. -3. After editing, the user submits the form, and the updated data is sent back to the server to be updated in the database. - -The idea here is that during step 2, the ID of the record being updated is kept in a hidden input. When the form is submitted in step 3, the ID is automatically sent back to the server with the record content. The ID lets the site's server-side component know exactly which record needs to be updated with the submitted data. - -You can see a full example of what this might look like in the [Examples](#examples) section below. - -### Improving website security - -Hidden inputs are also used to store and submit security tokens or _secrets_, for the purposes of improving website security. The basic idea is that if a user is filling in a sensitive form, such as a form on their banking website to transfer some money to another account, the secret they would be provided with would prove that they are who they say they are, and that they are using the correct form to submit the transfer request. - -This would stop a malicious user from creating a fake form, pretending to be a bank, and emailing the form to unsuspecting users to trick them into transferring money to the wrong place. This kind of attack is called a [Cross Site Request Forgery (CSRF)](/en-US/docs/Learn_web_development/Extensions/Server-side/First_steps/Website_security#cross-site_request_forgery_csrf); pretty much any reputable server-side framework uses hidden secrets to prevent such attacks. - -> [!NOTE] -> Placing the secret in a hidden input doesn't inherently make it secure. The key's composition and encoding would do that. The value of the hidden input is that it keeps the secret associated with the data and automatically includes it when the form is sent to the server. You need to use well-designed secrets to actually secure your website. - -## Validation - -Hidden inputs don't participate in constraint validation; they have no real value to be constrained. - -## Examples - -Let's look at how we might implement a simple version of the edit form we described earlier (see [Tracking edited content](#tracking_edited_content)), using a hidden input to remember the ID of the record being edited. - -The edit form's HTML might look a bit like this: - -```html -<form> - <div> - <label for="title">Post title:</label> - <input type="text" id="title" name="title" value="My excellent blog post" /> - </div> - <div> - <label for="content">Post content:</label> - <textarea id="content" name="content" cols="60" rows="5"> -This is the content of my excellent blog post. I hope you enjoy it! - </textarea> - </div> - <div> - <button type="submit">Update post</button> - </div> - <input type="hidden" id="postId" name="postId" value="34657" /> -</form> -``` - -Let's also add some CSS: - -```css -html { - font-family: sans-serif; -} - -form { - width: 500px; -} - -div { - display: flex; - margin-bottom: 10px; -} - -label { - flex: 2; - line-height: 2; - text-align: right; - padding-right: 20px; -} - -input, -textarea { - flex: 7; - font-family: sans-serif; - font-size: 1.1rem; - padding: 5px; -} - -textarea { - height: 60px; -} -``` - -The server would set the value of the hidden input with the ID `postID` to the ID of the post in its database before sending the form to the user's browser and would use that information when the form is returned to know which database record to update with modified information. No scripting is needed in the content to handle this. - -The output looks like this: - -{{ EmbedLiveSample('Examples', '100%', 200) }} - -> [!NOTE] -> You can also find the example on GitHub (see the [source code](https://github.com/mdn/learning-area/blob/main/html/forms/hidden-input-example/index.html), and also [see it running live](https://mdn.github.io/learning-area/html/forms/hidden-input-example/index.html)). - -When submitted, the form data sent to the server will look something like this: - -`title=My+excellent+blog+post&content=This+is+the+content+of+my+excellent+blog+post.+I+hope+you+enjoy+it!&postId=34657` - -Even though the hidden input cannot be seen at all, its data is still submitted. - -## Technical summary - -<table class="properties"> - <tbody> - <tr> - <td><strong><a href="#value">Value</a></strong></td> - <td> - A string representing the value of the hidden - data you want to pass back to the server. - </td> - </tr> - <tr> - <td><strong>Events</strong></td> - <td>None.</td> - </tr> - <tr> - <td><strong>Supported Common Attributes</strong></td> - <td><a href="/en-US/docs/Web/HTML/Element/input#autocomplete"><code>autocomplete</code></a></td> - </tr> - <tr> - <td><strong>IDL attributes</strong></td> - <td><code>value</code></td> - </tr> - <tr> - <td><strong>DOM interface</strong></td> - <td><p>{{domxref("HTMLInputElement")}}</p></td> - </tr> - <tr> - <td><strong>Methods</strong></td> - <td>None.</td> - </tr> - <tr> - <td><strong>Implicit ARIA Role</strong></td> - <td><a href="https://www.w3.org/TR/html-aria/#dfn-no-corresponding-role">no corresponding role</a></td> - </tr> - </tbody> -</table> - -## Specifications - -{{Specifications}} - -## Browser compatibility - -{{Compat}} - -## See also - -- [HTML forms guide](/en-US/docs/Learn_web_development/Extensions/Forms) -- {{HTMLElement("input")}} and the {{domxref("HTMLInputElement")}} interface it's based upon diff --git a/files/en-us/web/html/element/input/image/index.md b/files/en-us/web/html/element/input/image/index.md deleted file mode 100644 index c751704ccdb250f..000000000000000 --- a/files/en-us/web/html/element/input/image/index.md +++ /dev/null @@ -1,373 +0,0 @@ ---- -title: <input type="image"> -slug: Web/HTML/Element/input/image -page-type: html-element -browser-compat: html.elements.input.type_image ---- - -{{HTMLSidebar}} - -{{HTMLElement("input")}} elements of type **`image`** are used to create graphical submit buttons, i.e. submit buttons that take the form of an image rather than text. - -{{InteractiveExample("HTML Demo: &lt;input type=&quot;image&quot;&gt;", "tabbed-standard")}} - -```html interactive-example -<p>Sign in to your account:</p> - -<div> - <label for="userId">User ID</label> - <input type="text" id="userId" name="userId" /> -</div> - -<input - type="image" - id="image" - alt="Login" - src="/shared-assets/images/examples/login-button.png" /> -``` - -```css interactive-example -label { - font-size: 0.8rem; -} - -label, -input[type="image"] { - margin-top: 1rem; -} - -input[type="image"] { - width: 80px; -} -``` - -## Value - -`<input type="image">` elements do not accept `value` attributes. The path to the image to be displayed is specified in the `src` attribute. - -## Additional attributes - -In addition to the attributes shared by all {{HTMLElement("input")}} elements, `image` button inputs support the following attributes. - -### alt - -The `alt` attribute provides an alternate string to use as the button's label if the image cannot be shown (due to error, a {{Glossary("user agent")}} that cannot or is configured not to show images, or if the user is using a screen reading device). If provided, it must be a non-empty string appropriate as a label for the button. - -For example, if you have a graphical button that shows an image with an icon and/or image text "Login Now", you should also set the `alt` attribute to something like `Login Now`. - -> [!NOTE] -> While the `alt` attribute is technically optional, you should always include one to maximize the usability of your content. - -Functionally, the `alt` attribute of the `<input type="image">` element works just like the [`alt`](/en-US/docs/Web/HTML/Element/img#alt) attribute on {{HTMLElement("img")}} elements. - -### formaction - -A string indicating the URL to which to submit the data. This takes precedence over the [`action`](/en-US/docs/Web/HTML/Element/form#action) attribute on the {{HTMLElement("form")}} element that owns the {{HTMLElement("input")}}. - -This attribute is also available on [`<input type="submit">`](/en-US/docs/Web/HTML/Element/input/submit) and {{HTMLElement("button")}} elements. - -### formenctype - -A string that identifies the encoding method to use when submitting the form data to the server. There are three permitted values: - -- `application/x-www-form-urlencoded` - - : This, the default value, sends the form data as a string after {{Glossary("Percent-encoding", "percent-encoding")}} the text using an algorithm such as {{jsxref("encodeURI", "encodeURI()")}}. -- `multipart/form-data` - - : Uses the {{domxref("FormData")}} API to manage the data, allowing for files to be submitted to the server. You _must_ use this encoding type if your form includes any {{HTMLElement("input")}} elements of [`type`](/en-US/docs/Web/HTML/Element/input#type) `file` ([`<input type="file">`](/en-US/docs/Web/HTML/Element/input/file)). -- `text/plain` - - : Plain text; mostly useful only for debugging, so you can easily see the data that's to be submitted. - -If specified, the value of the `formenctype` attribute overrides the owning form's [`action`](/en-US/docs/Web/HTML/Element/form#action) attribute. - -This attribute is also available on [`<input type="submit">`](/en-US/docs/Web/HTML/Element/input/submit) and {{HTMLElement("button")}} elements. - -### formmethod - -A string indicating the HTTP method to use when submitting the form's data; this value overrides any [`method`](/en-US/docs/Web/HTML/Element/form#method) attribute given on the owning form. Permitted values are: - -- `get` - - : A URL is constructed by starting with the URL given by the `formaction` or [`action`](/en-US/docs/Web/HTML/Element/form#action) attribute, appending a question mark ("?") character, then appending the form's data, encoded as described by `formenctype` or the form's [`enctype`](/en-US/docs/Web/HTML/Element/form#enctype) attribute. This URL is then sent to the server using an HTTP {{HTTPMethod("get")}} request. This method works well for simple forms that contain only {{Glossary("ASCII")}} characters and have no side effects. This is the default value. -- `post` - - : The form's data is included in the body of the request that is sent to the URL given by the `formaction` or [`action`](/en-US/docs/Web/HTML/Element/form#action) attribute using an HTTP {{HTTPMethod("post")}} request. This method supports complex data and file attachments. -- `dialog` - - : This method is used to indicate that the button closes the dialog with which the input is associated, and does not transmit the form data at all. - -This attribute is also available on [`<input type="submit">`](/en-US/docs/Web/HTML/Element/input/submit) and {{HTMLElement("button")}} elements. - -### formnovalidate - -A Boolean attribute which, if present, specifies that the form should not be validated before submission to the server. This overrides the value of the [`novalidate`](/en-US/docs/Web/HTML/Element/form#novalidate) attribute on the element's owning form. - -This attribute is also available on [`<input type="submit">`](/en-US/docs/Web/HTML/Element/input/submit) and {{HTMLElement("button")}} elements. - -### formtarget - -A string which specifies a name or keyword that indicates where to display the response received after submitting the form. The string must be the name of a **browsing context** (that is, a tab, window, or {{HTMLElement("iframe")}}. A value specified here overrides any target given by the [`target`](/en-US/docs/Web/HTML/Element/form#target) attribute on the {{HTMLElement("form")}} that owns this input. - -In addition to the actual names of tabs, windows, or inline frames, there are a few special keywords that can be used: - -- `_self` - - : Loads the response into the same browsing context as the one that contains the form. This will replace the current document with the received data. This is the default value used if none is specified. -- `_blank` - - : Loads the response into a new, unnamed, browsing context. This is typically a new tab in the same window as the current document, but may differ depending on the configuration of the {{Glossary("user agent")}}. -- `_parent` - - : Loads the response into the parent browsing context of the current one. If there is no parent context, this behaves the same as `_self`. -- `_top` - - : Loads the response into the top-level browsing context; this is the browsing context that is the topmost ancestor of the current context. If the current context is the topmost context, this behaves the same as `_self`. - -This attribute is also available on [`<input type="submit">`](/en-US/docs/Web/HTML/Element/input/submit) and {{HTMLElement("button")}} elements. - -### height - -A number specifying the height, in CSS pixels, at which to draw the image specified by the `src` attribute. - -### src - -A string specifying the URL of the image file to display to represent the graphical submit button. When the user interacts with the image, the input is handled like any other button input. - -### width - -A number indicating the width at which to draw the image, in CSS pixels. - -## Obsolete attributes - -The following attribute was defined by HTML 4 for `image` inputs, but was not implemented by all browsers and has since been deprecated. - -### usemap - -If `usemap` is specified, it must be the name of an image map element, {{HTMLElement("map")}}, that defines an image map to use with the image. This usage is obsolete; you should switch to using the {{HTMLElement("img")}} element when you want to use image maps. - -## Using image inputs - -The `<input type="image">` element is a [replaced element](/en-US/docs/Web/CSS/Replaced_element) (an element whose content isn't generated or directly managed by the CSS layer), behaving in much the same way as a regular {{htmlelement("img")}} element, but with the capabilities of a [submit button](/en-US/docs/Web/HTML/Element/input/submit). - -### Essential image input features - -Let's look at a basic example that includes all the essential features you'd need to use (These work exactly the same as they do on the `<img>` element.): - -```html -<input - id="image" - type="image" - width="100" - height="30" - alt="Login" - src="https://raw.githubusercontent.com/mdn/learning-area/master/html/forms/image-type-example/login.png" /> -``` - -{{ EmbedLiveSample('Essential_image_input_features', 600, 50) }} - -- The [`src`](/en-US/docs/Web/HTML/Element/input#src) attribute is used to specify the path to the image you want to display in the button. -- The [`alt`](/en-US/docs/Web/HTML/Element/input#alt) attribute provides alt text for the image, so screen reader users can get a better idea of what the button is used for. It will also display if the image can't be shown for any reason (for example if the path is misspelled). If possible, use text which matches the label you'd use if you were using a standard submit button. -- The [`width`](/en-US/docs/Web/HTML/Element/input#width) and [`height`](/en-US/docs/Web/HTML/Element/input#height) attributes are used to specify the width and height the image should be shown at, in pixels. The button is the same size as the image; if you need the button's hit area to be bigger than the image, you will need to use CSS (e.g. {{cssxref("padding")}}). Also, if you specify only one dimension, the other is automatically adjusted so that the image maintains its original {{glossary("aspect ratio")}}. - -### Overriding default form behaviors - -`<input type="image">` elements — like regular [submit buttons](/en-US/docs/Web/HTML/Element/input/submit) — can accept a number of attributes that override the default form behavior: - -- `formaction` - - : The URI of a program that processes the information submitted by the input element; overrides the [`action`](/en-US/docs/Web/HTML/Element/form#action) attribute of the element's form owner. -- `formenctype` - - - : Specifies the type of content that is used to submit the form to the server. Possible values are: - - - `application/x-www-form-urlencoded`: The default value if the attribute is not specified. - - `text/plain`. - - If this attribute is specified, it overrides the [`enctype`](/en-US/docs/Web/HTML/Element/form#enctype) attribute of the element's form owner. - -- `formmethod` - - - : Specifies the HTTP method that the browser uses to submit the form. Possible values are: - - - `post`: The data from the form is included in the body of the form and is sent to the server. - - `get`: The data from the form is appended to the **`form`** attribute URI, with a '?' as a separator, and the resulting URI is sent to the server. Use this method when the form has no side effects and contains only ASCII characters. - - If specified, this attribute overrides the [`method`](/en-US/docs/Web/HTML/Element/form#method) attribute of the element's form owner. - -- `formnovalidate` - - : A Boolean attribute specifying that the form is not to be validated when it is submitted. If this attribute is specified, it overrides the [`novalidate`](/en-US/docs/Web/HTML/Element/form#novalidate) attribute of the element's form owner. -- `formtarget` - - - : A name or keyword indicating where to display the response that is received after submitting the form. This is a name of, or keyword for, a _browsing context_ (for example, tab, window, or inline frame). If this attribute is specified, it overrides the [`target`](/en-US/docs/Web/HTML/Element/form#target) attribute of the element's form owner. The following keywords have special meanings: - - - `_self`: Load the response into the same browsing context as the current one. This value is the default if the attribute is not specified. - - `_blank`: Load the response into a new unnamed browsing context. - - `_parent`: Load the response into the parent browsing context of the current one. If there is no parent, this option behaves the same way as `_self`. - - `_top`: Load the response into the top-level browsing context (that is, the browsing context that is an ancestor of the current one, and has no parent). If there is no parent, this option behaves the same as `_self`. - -### Using the x and y data points - -When you submit a form using a button created with `<input type="image">`, two extra data points are submitted to the server automatically by the browser — `x` and `y`. You can see this in action in our [X Y coordinates example](https://mdn.github.io/learning-area/html/forms/image-type-example/xy-coordinates-example.html). - -When you click on the image to submit the form, you'll see the data appended to the URL as parameters, for example `?x=52&y=55`. If the image input has a [`name`](/en-US/docs/Web/HTML/Element/input#name) attribute, then keep in mind that the specified name is prefixed on every attribute, so if the `name` is `position`, then the returned coordinates would be formatted in the URL as `?position.x=52&position.y=55`. This, of course, applies to all other attributes as well. - -These are the X and Y coordinates of the image that the mouse clicked on to submit the form, where (0,0) is the top-left of the image and the default in case submission happens without a click on the image. These can be used when the position the image was clicked on is significant, for example you might have a map that when clicked, sends the coordinates that were clicked to the server. The server-side code then works out what location was clicked on, and returns information about places nearby. - -In our above example, we could write server-side code that works out what color was clicked on by the coordinates submitted, and keeps a tally of the favorite colors people voted for. - -### Adjusting the image's position and scaling algorithm - -You can use the {{cssxref("object-position")}} property to adjust the positioning of the image within the `<input>` element's frame, and the {{cssxref("object-fit")}} property to control how the image's size is adjusted to fit within the frame. This allows you to specify a frame for the image using the `width` and `height` attributes to set aside space in the layout, then adjust where within that space the image is located and how (or if) it is scaled to occupy that space. - -## Examples - -### A login form - -The following example shows the same button as before, but included in the context of a typical login form. - -{{ EmbedLiveSample('A_login_form', 600, 170) }} - -#### HTML - -```html -<form> - <p>Login to your account</p> - <div> - <label for="userId">User ID</label> - <input type="text" id="userId" name="userId" /> - </div> - <div> - <label for="pwd">Password</label> - <input type="password" id="pwd" name="pwd" /> - </div> - <div> - <input - id="image" - type="image" - src="https://raw.githubusercontent.com/mdn/learning-area/master/html/forms/image-type-example/login.png" - alt="Login" - width="100" /> - </div> -</form> -``` - -#### CSS - -And now some CSS to make the basic elements sit more neatly: - -```css -div { - margin-bottom: 10px; -} - -label { - display: inline-block; - width: 70px; - text-align: right; - padding-right: 10px; -} -``` - -### Adjusting the image position and scaling - -In this example, we adapt the previous example to set aside more space for the image and then adjust the actual image's size and positioning using {{cssxref("object-fit")}} and {{cssxref("object-position")}}. - -{{EmbedLiveSample("Adjusting_the_image_position_and_scaling", 600, 300)}} - -#### HTML - -```html -<form> - <p>Login to your account</p> - <div> - <label for="userId">User ID</label> - <input type="text" id="userId" name="userId" /> - </div> - <div> - <label for="pwd">Password</label> - <input type="password" id="pwd" name="pwd" /> - </div> - <div> - <input - id="image" - type="image" - src="https://raw.githubusercontent.com/mdn/learning-area/master/html/forms/image-type-example/login.png" - alt="Login" - width="200" - height="100" /> - </div> -</form> -``` - -#### CSS - -```css -div { - margin-bottom: 10px; -} - -label { - display: inline-block; - width: 70px; - text-align: right; - padding-right: 10px; -} - -#image { - object-position: right top; - object-fit: contain; - background-color: #ddd; -} -``` - -Here, `object-position` is configured to draw the image in the top-right corner of the element, while `object-fit` is set to `contain`, which indicates that the image should be drawn at the largest size that will fit within the element's box without altering its aspect ratio. Note the visible grey background of the element still visible in the area not covered by the image. - -## Technical summary - -<table class="properties"> - <tbody> - <tr> - <td><strong><a href="#value">Value</a></strong></td> - <td>None — the <code>value</code> attribute should not be specified.</td> - </tr> - <tr> - <td><strong>Events</strong></td> - <td>None.</td> - </tr> - <tr> - <td><strong>Supported common attributes</strong></td> - <td> - <a href="/en-US/docs/Web/HTML/Element/input#alt"><code>alt</code></a>, - <a href="/en-US/docs/Web/HTML/Element/input#src"><code>src</code></a>, - <a href="/en-US/docs/Web/HTML/Element/input#width"><code>width</code></a>, - <a href="/en-US/docs/Web/HTML/Element/input#height"><code>height</code></a>, - <a href="/en-US/docs/Web/HTML/Element/input#formaction"><code>formaction</code></a>, - <a href="/en-US/docs/Web/HTML/Element/input#formenctype"><code>formenctype</code></a>, - <a href="/en-US/docs/Web/HTML/Element/input#formmethod"><code>formmethod</code></a>, - <a href="/en-US/docs/Web/HTML/Element/input#formmethod"><code>formnovalidate</code></a>, - <a href="/en-US/docs/Web/HTML/Element/input#formtarget"><code>formtarget</code></a> - </td> - </tr> - <tr> - <td><strong>IDL attributes</strong></td> - <td>None.</td> - </tr> - <tr> - <td><strong>DOM interface</strong></td> - <td><p>{{domxref("HTMLInputElement")}}</p></td> - </tr> - <tr> - <td><strong>Methods</strong></td> - <td>None.</td> - </tr> - <tr> - <td><strong>Implicit ARIA Role</strong></td> - <td><a href="/en-US/docs/Web/Accessibility/ARIA/Roles/button_role"><code>button</code></a></td> - </tr> - </tbody> -</table> - -## Specifications - -{{Specifications}} - -## Browser compatibility - -{{Compat}} - -## See also - -- {{HTMLElement("input")}} and the {{domxref("HTMLInputElement")}} interface which implements it. -- The HTML {{HTMLElement("img")}} element -- Positioning and sizing the image within the `<input>` element's frame: {{cssxref("object-position")}} and {{cssxref("object-fit")}} diff --git a/files/en-us/web/html/element/input/index.md b/files/en-us/web/html/element/input/index.md deleted file mode 100644 index 8cee4191fb6d758..000000000000000 --- a/files/en-us/web/html/element/input/index.md +++ /dev/null @@ -1,1474 +0,0 @@ ---- -title: "<input>: The HTML Input element" -slug: Web/HTML/Element/input -page-type: html-element -browser-compat: html.elements.input ---- - -{{HTMLSidebar}} - -The **`<input>`** [HTML](/en-US/docs/Web/HTML) element is used to create interactive controls for web-based forms in order to accept data from the user; a wide variety of types of input data and control widgets are available, depending on the device and {{Glossary("user agent")}}. The `<input>` element is one of the most powerful and complex in all of HTML due to the sheer number of combinations of input types and attributes. - -{{InteractiveExample("HTML Demo: &lt;input type=&quot;text&quot;&gt;", "tabbed-shorter")}} - -```html interactive-example -<label for="name">Name (4 to 8 characters):</label> - -<input - type="text" - id="name" - name="name" - required - minlength="4" - maxlength="8" - size="10" /> -``` - -```css interactive-example -label { - display: block; - font: - 1rem "Fira Sans", - sans-serif; -} - -input, -label { - margin: 0.4rem 0; -} -``` - -## \<input> types - -How an `<input>` works varies considerably depending on the value of its [`type`](#type) attribute, hence the different types are covered in their own separate reference pages. If this attribute is not specified, the default type adopted is `text`. - -The available types are as follows: - -<table class="no-markdown"> - <colgroup> - <col /> - <col style="width: 50%" /> - <col /> - </colgroup> - <thead> - <tr> - <th>Type</th> - <th>Description</th> - <th>Basic Examples</th> - </tr> - </thead> - <tbody> - <tr> - <td>{{HTMLElement("input/button", "button")}}</td> - <td> - A push button with no default behavior displaying the value of the <a href="#value"><code>value</code></a> attribute, empty by default. - </td> - <td id="examplebutton"> - <pre class="brush: html hidden"> -&#x3C;input type="button" name="button" value="Button" /></pre> - {{EmbedLiveSample("examplebutton",200,55)}} - </td> - </tr> - <tr> - <td>{{HTMLElement("input/checkbox", "checkbox")}}</td> - <td>A check box allowing single values to be selected/deselected.</td> - <td id="examplecheckbox"> - <pre class="brush: html hidden"> -&#x3C;input type="checkbox" name="checkbox"/></pre> - {{EmbedLiveSample("examplecheckbox",200,55)}} - </td> - </tr> - <tr> - <td>{{HTMLElement("input/color", "color")}}</td> - <td> - A control for specifying a color; opening a color picker when active in supporting browsers. - </td> - <td id="examplecolor"> - <pre class="brush: html hidden"> -&#x3C;input type="color" name="color"/></pre> - {{EmbedLiveSample("examplecolor",200,55)}} - </td> - </tr> - <tr> - <td>{{HTMLElement("input/date", "date")}}</td> - <td> - A control for entering a date (year, month, and day, with no time). - Opens a date picker or numeric wheels for year, month, day when active - in supporting browsers. - </td> - <td id="exampledate"> - <pre class="brush: html hidden"> -&#x3C;input type="date" name="date"/></pre> - {{EmbedLiveSample("exampledate",200,55)}} - </td> - </tr> - <tr> - <td> - {{HTMLElement("input/datetime-local", "datetime-local")}} - </td> - <td> - A control for entering a date and time, with no time zone. Opens a date - picker or numeric wheels for date- and time-components when active in supporting browsers. - </td> - <td id="exampledtl"> - <pre class="brush: html hidden"> -&#x3C;input type="datetime-local" name="datetime-local"/></pre> - {{EmbedLiveSample("exampledtl",200,55)}} - </td> - </tr> - <tr> - <td>{{HTMLElement("input/email", "email")}}</td> - <td> - A field for editing an email address. Looks like a - <code>text</code> input, but has validation parameters and relevant - keyboard in supporting browsers and devices with dynamic keyboards. - </td> - <td id="exampleemail"> - <pre class="brush: html hidden"> -&#x3C;input type="email" name="email"/></pre> - {{EmbedLiveSample("exampleemail",200,55)}} - </td> - </tr> - <tr> - <td>{{HTMLElement("input/file", "file")}}</td> - <td> - A control that lets the user select a file. - Use the <a href="#accept"><code>accept</code></a> attribute to define the types of files that the control can select. - </td> - <td id="examplefile"> - <pre class="brush: html hidden"> -&#x3C;input type="file" accept="image/*, text/*" name="file"/></pre> - {{EmbedLiveSample("examplefile",'100%',55)}} - </td> - </tr> - <tr> - <td>{{HTMLElement("input/hidden", "hidden")}}</td> - <td> - A control that is not displayed but whose value is submitted to the - server. There is an example in the next column, but it's hidden! - </td> - <td id="examplehidden"> - <pre class="brush: html hidden"> -&#x3C;input id="userId" name="userId" type="hidden" value="abc123"></pre - > - {{EmbedLiveSample("examplehidden",200,55)}} - </td> - </tr> - <tr> - <td>{{HTMLElement("input/image", "image")}}</td> - <td> - A graphical <code>submit</code> button. Displays an image defined by the <code>src</code> attribute. - The <a href="#alt"><code>alt</code></a> attribute displays if the image <a href="#src"><code>src</code></a> is missing. - </td> - <td id="exampleimage"> - <pre class="brush: html hidden"> -&#x3C;input type="image" name="image" src="" alt="image input"/></pre> - {{EmbedLiveSample("exampleimage",200,55)}} - </td> - </tr> - <tr> - <td>{{HTMLElement("input/month", "month")}}</td> - <td>A control for entering a month and year, with no time zone.</td> - <td id="examplemonth"> - <pre class="brush: html hidden"> -&#x3C;input type="month" name="month"/></pre> - {{EmbedLiveSample("examplemonth",200,55)}} - </td> - </tr> - <tr> - <td>{{HTMLElement("input/number", "number")}}</td> - <td> - A control for entering a number. Displays a spinner and adds default - validation. Displays a numeric keypad in some devices - with dynamic keypads. - </td> - <td id="examplenumber"> - <pre class="brush: html hidden"> -&#x3C;input type="number" name="number"/></pre> - {{EmbedLiveSample("examplenumber",200,55)}} - </td> - </tr> - <tr> - <td>{{HTMLElement("input/password", "password")}}</td> - <td> - A single-line text field whose value is obscured. - Will alert user if site is not secure. - </td> - <td id="examplepassword"> - <pre class="brush: html hidden"> -&#x3C;input type="password" name="password"/></pre> - {{EmbedLiveSample("examplepassword",200,55)}} - </td> - </tr> - <tr> - <td>{{HTMLElement("input/radio", "radio")}}</td> - <td> - A radio button, allowing a single value to be selected out of multiple choices with the same <a href="#name"><code>name</code></a> value. - </td> - <td id="exampleradio"> - <pre class="brush: html hidden"> -&#x3C;input type="radio" name="radio"/></pre - > - {{EmbedLiveSample("exampleradio",200,55)}} - </td> - </tr> - <tr> - <td>{{HTMLElement("input/range", "range")}}</td> - <td> - A control for entering a number whose exact value is not important. - Displays as a range widget defaulting to the middle value. - Used in conjunction <a href="#min"><code>min</code></a> and <a href="#max"><code>max</code></a> to define the range of acceptable values. - </td> - <td id="examplerange"> - <pre class="brush: html hidden"> -&#x3C;input type="range" name="range" min="0" max="25"/></pre> - {{EmbedLiveSample("examplerange",200,55)}} - </td> - </tr> - <tr> - <td>{{HTMLElement("input/reset", "reset")}}</td> - <td> - A button that resets the contents of the form to default values. Not recommended. - </td> - <td id="examplereset"> - <pre class="brush: html hidden"> -&#x3C;input type="reset" name="reset"/></pre - > - {{EmbedLiveSample("examplereset",200,55)}} - </td> - </tr> - <tr> - <td>{{HTMLElement("input/search", "search")}}</td> - <td> - A single-line text field for entering search strings. Line-breaks are - automatically removed from the input value. May include a delete icon in - supporting browsers that can be used to clear the field. Displays a - search icon instead of enter key on some devices with dynamic keypads. - </td> - <td id="examplesearch"> - <pre class="brush: html hidden"> -&#x3C;input type="search" name="search"/></pre> - {{EmbedLiveSample("examplesearch",200,55)}} - </td> - </tr> - <tr> - <td>{{HTMLElement("input/submit", "submit")}}</td> - <td>A button that submits the form.</td> - <td id="examplesubmit"> - <pre class="brush: html hidden"> -&#x3C;input type="submit" name="submit"/></pre> - {{EmbedLiveSample("examplesubmit",200,55)}} - </td> - </tr> - <tr> - <td>{{HTMLElement("input/tel", "tel")}}</td> - <td> - A control for entering a telephone number. Displays a telephone keypad - in some devices with dynamic keypads. - </td> - <td id="exampletel"> - <pre class="brush: html hidden"> -&#x3C;input type="tel" name="tel"/></pre> - {{EmbedLiveSample("exampletel",200,55)}} - </td> - </tr> - <tr> - <td>{{HTMLElement("input/text", "text")}}</td> - <td> - The default value. A single-line text field. Line-breaks are - automatically removed from the input value. - </td> - <td id="exampletext"> - <pre class="brush: html hidden"> -&#x3C;input type="text" name="text"/></pre - > - {{EmbedLiveSample("exampletext",200,55)}} - </td> - </tr> - <tr> - <td>{{HTMLElement("input/time", "time")}}</td> - <td>A control for entering a time value with no time zone.</td> - <td id="exampletime"> - <pre class="brush: html hidden"> -&#x3C;input type="time" name="time"/></pre> - {{EmbedLiveSample("exampletime",200,55)}} - </td> - </tr> - <tr> - <td>{{HTMLElement("input/url", "url")}}</td> - <td> - A field for entering a URL. Looks like a <code>text</code> input, but - has validation parameters and relevant keyboard in supporting browsers - and devices with dynamic keyboards. - </td> - <td id="exampleurl"> - <pre class="brush: html hidden"> -&#x3C;input type="url" name="url"/></pre - > - {{EmbedLiveSample("exampleurl",200,55)}} - </td> - </tr> - <tr> - <td>{{HTMLElement("input/week", "week")}}</td> - <td> - A control for entering a date consisting of a week-year number and a week number with no time zone. - </td> - <td id="exampleweek"> - <pre class="brush: html hidden"> -&#x3C;input type="week" name="week"/></pre> - {{EmbedLiveSample("exampleweek",200,55)}} - </td> - </tr> - <tr> - <th colspan="3">Obsolete values</th> - </tr> - <tr> - <td><code>datetime</code> {{deprecated_inline}}</td> - <td> - A control for entering a date and time (hour, minute, second, and fraction of a second) based on UTC time zone. - </td> - <td id="exampledatetime"> - <pre class="brush: html hidden"> -&#x3C;input type="datetime" name="datetime"/></pre> - {{EmbedLiveSample("exampledatetime",200,75)}} - </td> - </tr> - </tbody> -</table> - -## Attributes - -The `<input>` element is so powerful because of its attributes; the [`type`](#type) attribute, described with examples above, being the most important. Since every `<input>` element, regardless of type, is based on the {{domxref("HTMLInputElement")}} interface, they technically share the exact same set of attributes. However, in reality, most attributes have an effect on only a specific subset of input types. In addition, the way some attributes impact an input depends on the input type, impacting different input types in different ways. - -This section provides a table listing all the attributes with a brief description. This table is followed by a list describing each attribute in greater detail, along with which input types they are associated with. Those that are common to most or all input types are defined in greater detail below. Attributes that are unique to particular input types—or attributes which are common to all input types but have special behaviors when used on a given input type—are instead documented on those types' pages. - -Attributes for the `<input>` element include the [global HTML attributes](/en-US/docs/Web/HTML/Global_attributes) and additionally: - -| Attribute | Type(s) | Description | -| --------------------------------------------- | ----------------------------------------------------------------------- | -------------------------------------------------------------------------------------- | -| [`accept`](#accept) | `file` | Hint for expected file type in file upload controls | -| [`alt`](#alt) | `image` | alt attribute for the image type. Required for accessibility | -| [`autocapitalize`](#autocapitalize) | all except `url`, `email`, and `password` | Controls automatic capitalization in inputted text. | -| [`autocomplete`](#autocomplete) | all except `checkbox`, `radio`, and buttons | Hint for form autofill feature | -| [`capture`](#capture) | `file` | Media capture input method in file upload controls | -| [`checked`](#checked) | `checkbox`, `radio` | Whether the command or control is checked | -| [`dirname`](#dirname) | `hidden`, `text`, `search`, `url`, `tel`, `email` | Name of form field to use for sending the element's directionality in form submission | -| [`disabled`](#disabled) | all | Whether the form control is disabled | -| [`form`](#form) | all | Associates the control with a form element | -| [`formaction`](#formaction) | `image`, `submit` | URL to use for form submission | -| [`formenctype`](#formenctype) | `image`, `submit` | Form data set encoding type to use for form submission | -| [`formmethod`](#formmethod) | `image`, `submit` | HTTP method to use for form submission | -| [`formnovalidate`](#formnovalidate) | `image`, `submit` | Bypass form control validation for form submission | -| [`formtarget`](#formtarget) | `image`, `submit` | Browsing context for form submission | -| [`height`](#height) | `image` | Same as height attribute for {{htmlelement('img')}}; vertical dimension | -| [`list`](#list) | all except `hidden`, `password`, `checkbox`, `radio`, and buttons | Value of the id attribute of the {{htmlelement('datalist')}} of autocomplete options | -| [`max`](#max) | `date`, `month`, `week`, `time`, `datetime-local`, `number`, `range` | Maximum value | -| [`maxlength`](#maxlength) | `text`, `search`, `url`, `tel`, `email`, `password` | Maximum length (number of characters) of `value` | -| [`min`](#min) | `date`, `month`, `week`, `time`, `datetime-local`, `number`, `range` | Minimum value | -| [`minlength`](#minlength) | `text`, `search`, `url`, `tel`, `email`, `password` | Minimum length (number of characters) of `value` | -| [`multiple`](#multiple) | `email`, `file` | Boolean. Whether to allow multiple values | -| [`name`](#name) | all | Name of the form control. Submitted with the form as part of a name/value pair | -| [`pattern`](#pattern) | `text`, `search`, `url`, `tel`, `email`, `password` | Pattern the `value` must match to be valid | -| [`placeholder`](#placeholder) | `text`, `search`, `url`, `tel`, `email`, `password`, `number` | Text that appears in the form control when it has no value set | -| [`popovertarget`](#popovertarget) | `button` | Designates an `<input type="button">` as a control for a popover element | -| [`popovertargetaction`](#popovertargetaction) | `button` | Specifies the action that a popover control should perform | -| [`readonly`](#readonly) | all except `hidden`, `range`, `color`, `checkbox`, `radio`, and buttons | Boolean. The value is not editable | -| [`required`](#required) | all except `hidden`, `range`, `color`, and buttons | Boolean. A value is required or must be checked for the form to be submittable | -| [`size`](#size) | `text`, `search`, `url`, `tel`, `email`, `password` | Size of the control | -| [`src`](#src) | `image` | Same as `src` attribute for {{htmlelement('img')}}; address of image resource | -| [`step`](#step) | `date`, `month`, `week`, `time`, `datetime-local`, `number`, `range` | Incremental values that are valid | -| [`type`](#type) | all | Type of form control | -| [`value`](#value) | all except `image` | The value of the control. When specified in the HTML, corresponds to the initial value | -| [`width`](#width) | `image` | Same as `width` attribute for {{htmlelement('img')}} | - -A few additional non-standard attributes are listed following the descriptions of the standard attributes. - -### Individual attributes - -- [`accept`](/en-US/docs/Web/HTML/Attributes/accept) - - - : Valid for the `file` input type only, the `accept` attribute defines which file types are selectable in a `file` upload control. See the {{HTMLElement("input/file", "file")}} input type. - -- `alt` - - - : Valid for the `image` button only, the `alt` attribute provides alternative text for the image, displaying the value of the attribute if the image [`src`](#src) is missing or otherwise fails to load. See the {{HTMLElement("input/image", "image")}} input type. - -- `autocapitalize` - - - : Controls whether inputted text is automatically capitalized and, if so, in what manner. See the [`autocapitalize`](/en-US/docs/Web/HTML/Global_attributes/autocapitalize) global attribute page for more information. - -- [`autocomplete`](/en-US/docs/Web/HTML/Attributes/autocomplete) - - - : (**Not** a Boolean attribute!) The [`autocomplete`](/en-US/docs/Web/HTML/Attributes/autocomplete) attribute takes as its value a space-separated string that describes what, if any, type of autocomplete functionality the input should provide. A typical implementation of autocomplete recalls previous values entered in the same input field, but more complex forms of autocomplete can exist. For instance, a browser could integrate with a device's contacts list to autocomplete `email` addresses in an email input field. See [`autocomplete`](/en-US/docs/Web/HTML/Attributes/autocomplete#values) for permitted values. - - The `autocomplete` attribute is valid on `hidden`, `text`, `search`, `url`, `tel`, `email`, `date`, `month`, `week`, `time`, `datetime-local`, `number`, `range`, `color`, and `password`. This attribute has no effect on input types that do not return numeric or text data, being valid for all input types except `checkbox`, `radio`, `file`, or any of the button types. - - See the [`autocomplete` attribute](/en-US/docs/Web/HTML/Attributes/autocomplete) for additional information, including information on password security and how `autocomplete` is slightly different for `hidden` than for other input types. - -- `autofocus` - - - : A Boolean attribute which, if present, indicates that the input should automatically have focus when the page has finished loading (or when the {{HTMLElement("dialog")}} containing the element has been displayed). - - > [!NOTE] - > An element with the `autofocus` attribute may gain focus before the {{domxref("Document/DOMContentLoaded_event", "DOMContentLoaded")}} event is fired. - - No more than one element in the document may have the `autofocus` attribute. If put on more than one element, the first one with the attribute receives focus. - - The `autofocus` attribute cannot be used on inputs of type `hidden`, since hidden inputs cannot be focused. - - > [!WARNING] - > Automatically focusing a form control can confuse visually-impaired people using screen-reading technology and people with cognitive impairments. When `autofocus` is assigned, screen-readers "teleport" their user to the form control without warning them beforehand. - - Use careful consideration for accessibility when applying the `autofocus` attribute. Automatically focusing on a control can cause the page to scroll on load. The focus can also cause dynamic keyboards to display on some touch devices. While a screen reader will announce the label of the form control receiving focus, the screen reader will not announce anything before the label, and the sighted user on a small device will equally miss the context created by the preceding content. - -- [`capture`](/en-US/docs/Web/HTML/Attributes/capture) - - : Introduced in the HTML Media Capture specification and valid for the `file` input type only, the `capture` attribute defines which media—microphone, video, or camera—should be used to capture a new file for upload with `file` upload control in supporting scenarios. See the {{HTMLElement("input/file", "file")}} input type. -- `checked` - - - : Valid for both `radio` and `checkbox` types, `checked` is a Boolean attribute. If present on a `radio` type, it indicates that the radio button is the currently selected one in the group of same-named radio buttons. If present on a `checkbox` type, it indicates that the checkbox is checked by default (when the page loads). It does _not_ indicate whether this checkbox is currently checked: if the checkbox's state is changed, this content attribute does not reflect the change. (Only the [`HTMLInputElement`'s `checked` IDL attribute](/en-US/docs/Web/API/HTMLInputElement) is updated.) - - > [!NOTE] - > Unlike other input controls, a checkboxes and radio buttons value are only included in the submitted data if they are currently `checked`. If they are, the name and the value(s) of the checked controls are submitted. - > - > For example, if a checkbox whose `name` is `fruit` has a `value` of `cherry`, and the checkbox is checked, the form data submitted will include `fruit=cherry`. If the checkbox isn't active, it isn't listed in the form data at all. The default `value` for checkboxes and radio buttons is `on`. - -- [`dirname`](/en-US/docs/Web/HTML/Attributes/dirname) - - - : Valid for `hidden`, `text`, `search`, `url`, `tel`, and `email` input types, the `dirname` attribute enables the submission of the directionality of the element. When included, the form control will submit with two name/value pairs: the first being the [`name`](#name) and [`value`](#value), and the second being the value of the `dirname` attribute as the name, with a value of `ltr` or `rtl` as set by the browser. - - ```html - <form action="page.html" method="post"> - <label> - Fruit: - <input type="text" name="fruit" dirname="fruit-dir" value="cherry" /> - </label> - <input type="submit" /> - </form> - <!-- page.html?fruit=cherry&fruit-dir=ltr --> - ``` - - When the form above is submitted, the input cause both the `name` / `value` pair of `fruit=cherry` and the `dirname` / direction pair of `fruit-dir=ltr` to be sent. - For more information, see the [`dirname` attribute](/en-US/docs/Web/HTML/Attributes/dirname). - -- [`disabled`](/en-US/docs/Web/HTML/Attributes/disabled) - - - : A Boolean attribute which, if present, indicates that the user should not be able to interact with the input. Disabled inputs are typically rendered with a dimmer color or using some other form of indication that the field is not available for use. - - Specifically, disabled inputs do not receive the {{domxref("Element/click_event", "click")}} event, and disabled inputs are not submitted with the form. - - > [!NOTE] - > Although not required by the specification, Firefox will by default [persist the dynamic disabled state](https://stackoverflow.com/questions/5985839/bug-with-firefox-disabled-attribute-of-input-not-resetting-when-refreshing) of an `<input>` across page loads. Use the [`autocomplete`](#autocomplete) attribute to control this feature. - -- `form` - - - : A string specifying the {{HTMLElement("form")}} element with which the input is associated (that is, its **form owner**). This string's value, if present, must match the [`id`](#id) of a `<form>` element in the same document. If this attribute isn't specified, the `<input>` element is associated with the nearest containing form, if any. - - The `form` attribute lets you place an input anywhere in the document but have it included with a form elsewhere in the document. - - > [!NOTE] - > An input can only be associated with one form. - -- `formaction` - - : Valid for the `image` and `submit` input types only. See the {{HTMLElement("input/submit", "submit")}} input type for more information. -- `formenctype` - - : Valid for the `image` and `submit` input types only. See the {{HTMLElement("input/submit", "submit")}} input type for more information. -- `formmethod` - - : Valid for the `image` and `submit` input types only. See the {{HTMLElement("input/submit", "submit")}} input type for more information. -- `formnovalidate` - - : Valid for the `image` and `submit` input types only. See the {{HTMLElement("input/submit", "submit")}} input type for more information. -- `formtarget` - - : Valid for the `image` and `submit` input types only. See the {{HTMLElement("input/submit", "submit")}} input type for more information. -- `height` - - : Valid for the `image` input button only, the `height` is the height of the image file to display to represent the graphical submit button. See the {{HTMLElement("input/image", "image")}} input type. -- `id` - - : Global attribute valid for all elements, including all the input types, it defines a unique identifier (ID) which must be unique in the whole document. Its purpose is to identify the element when linking. The value is used as the value of the {{htmlelement('label')}}'s `for` attribute to link the label with the form control. See {{htmlelement('label')}}. -- `inputmode` - - : Global value valid for all elements, it provides a hint to browsers as to the type of virtual keyboard configuration to use when editing this element or its contents. Values include `none`, `text`, `tel`, `url`, `email`, `numeric`, `decimal`, and `search`. -- `list` - - - : The value given to the `list` attribute should be the {{domxref("Element.id", "id")}} of a {{HTMLElement("datalist")}} element located in the same document. The `<datalist>` provides a list of predefined values to suggest to the user for this input. Any values in the list that are not compatible with the [`type`](#type) are not included in the suggested options. The values provided are suggestions, not requirements: users can select from this predefined list or provide a different value. - - It is valid on `text`, `search`, `url`, `tel`, `email`, `date`, `month`, `week`, `time`, `datetime-local`, `number`, `range`, and `color`. - - Per the specifications, the `list` attribute is not supported by the `hidden`, `password`, `checkbox`, `radio`, `file`, or any of the button types. - - Depending on the browser, the user may see a custom color palette suggested, tic marks along a range, or even an input that opens like a {{HTMLElement("select")}} but allows for non-listed values. Check out the [browser compatibility table](/en-US/docs/Web/HTML/Element/datalist#browser_compatibility) for the other input types. - - See the {{htmlelement('datalist')}} element. - -- [`max`](/en-US/docs/Web/HTML/Attributes/max) - - - : Valid for `date`, `month`, `week`, `time`, `datetime-local`, `number`, and `range`, it defines the greatest value in the range of permitted values. If the [`value`](#value) entered into the element exceeds this, the element fails [constraint validation](/en-US/docs/Web/HTML/Constraint_validation). If the value of the `max` attribute isn't a number, then the element has no maximum value. - - There is a special case: if the data type is periodic (such as for dates or times), the value of `max` may be lower than the value of `min`, which indicates that the range may wrap around; for example, this allows you to specify a time range from 10 PM to 4 AM. - -- [`maxlength`](/en-US/docs/Web/HTML/Attributes/maxlength) - - - : Valid for `text`, `search`, `url`, `tel`, `email`, and `password`, it defines the maximum string length (measured in UTF-16 code units) that the user can enter into the field. This must be an integer value of 0 or higher. If no `maxlength` is specified, or an invalid value is specified, the field has no maximum length. This value must also be greater than or equal to the value of `minlength`. - - The input will fail [constraint validation](/en-US/docs/Web/HTML/Constraint_validation) if the length of the text entered into the field is greater than `maxlength` UTF-16 code units long. By default, browsers prevent users from entering more characters than allowed by the `maxlength` attribute. Constraint validation is only applied when the value is changed by the user. See [Client-side validation](#client-side_validation) for more information. - -- [`min`](/en-US/docs/Web/HTML/Attributes/min) - - - : Valid for `date`, `month`, `week`, `time`, `datetime-local`, `number`, and `range`, it defines the most negative value in the range of permitted values. If the [`value`](#value) entered into the element is less than this, the element fails [constraint validation](/en-US/docs/Web/HTML/Constraint_validation). If the value of the `min` attribute isn't a number, then the element has no minimum value. - - This value must be less than or equal to the value of the `max` attribute. If the `min` attribute is present but is not specified or is invalid, no `min` value is applied. If the `min` attribute is valid and a non-empty value is less than the minimum allowed by the `min` attribute, constraint validation will prevent form submission. See [Client-side validation](#client-side_validation) for more information. - - There is a special case: if the data type is periodic (such as for dates or times), the value of `max` may be lower than the value of `min`, which indicates that the range may wrap around; for example, this allows you to specify a time range from 10 PM to 4 AM. - -- [`minlength`](/en-US/docs/Web/HTML/Attributes/minlength) - - - : Valid for `text`, `search`, `url`, `tel`, `email`, and `password`, it defines the minimum string length (measured in UTF-16 code units) that the user can enter into the entry field. This must be a non-negative integer value smaller than or equal to the value specified by `maxlength`. If no `minlength` is specified, or an invalid value is specified, the input has no minimum length. - - The input will fail [constraint validation](/en-US/docs/Web/HTML/Constraint_validation) if the length of the text entered into the field is fewer than `minlength` UTF-16 code units long, preventing form submission. Constraint validation is only applied when the value is changed by the user. See [Client-side validation](#client-side_validation) for more information. - -- [`multiple`](/en-US/docs/Web/HTML/Attributes/multiple) - - - : The Boolean `multiple` attribute, if set, means the user can enter comma separated email addresses in the email widget or can choose more than one file with the `file` input. See the {{HTMLElement("input/email", "email")}} and {{HTMLElement("input/file", "file")}} input type. - -- `name` - - - : A string specifying a name for the input control. This name is submitted along with the control's value when the form data is submitted. - - Consider the `name` a required attribute (even though it's not). If an input has no `name` specified, or `name` is empty, the input's value is not submitted with the form! (Disabled controls, unchecked radio buttons, unchecked checkboxes, and reset buttons are also not sent.) - - There are two special cases: - - 1. `_charset_` : If used as the name of an `<input>` element of type {{HTMLElement("input/hidden", "hidden")}}, the input's `value` is automatically set by the {{Glossary("user agent")}} to the character encoding being used to submit the form. - 2. `isindex`: For historical reasons, the name [`isindex`](https://html.spec.whatwg.org/multipage/form-control-infrastructure.html#attr-fe-name) is not allowed. - - The [`name`](#name) attribute creates a unique behavior for radio buttons. - - Only one radio button in a same-named group of radio buttons can be checked at a time. Selecting any radio button in that group automatically deselects any currently-selected radio button in the same group. The value of that one checked radio button is sent along with the name if the form is submitted, - - When tabbing into a series of same-named group of radio buttons, if one is checked, that one will receive focus. If they aren't grouped together in source order, if one of the group is checked, tabbing into the group starts when the first one in the group is encountered, skipping all those that aren't checked. In other words, if one is checked, tabbing skips the unchecked radio buttons in the group. If none are checked, the radio button group receives focus when the first button in the same name group is reached. - - Once one of the radio buttons in a group has focus, using the arrow keys will navigate through all the radio buttons of the same name, even if the radio buttons are not grouped together in the source order. - - When an input element is given a `name`, that name becomes a property of the owning form element's {{domxref("HTMLFormElement.elements")}} property. If you have an input whose `name` is set to `guest` and another whose `name` is `hat-size`, the following code can be used: - - ```js - let form = document.querySelector("form"); - - let guestName = form.elements.guest; - let hatSize = form.elements["hat-size"]; - ``` - - When this code has run, `guestName` will be the {{domxref("HTMLInputElement")}} for the `guest` field, and `hatSize` the object for the `hat-size` field. - - > [!WARNING] - > Avoid giving form elements a `name` that corresponds to a built-in property of the form, since you would then override the predefined property or method with this reference to the corresponding input. - -- [`pattern`](/en-US/docs/Web/HTML/Attributes/pattern) - - - : Valid for `text`, `search`, `url`, `tel`, `email`, and `password`, the `pattern` attribute is used to compile a regular expression that the input's [`value`](#value) must match in order for the value to pass [constraint validation](/en-US/docs/Web/HTML/Constraint_validation). It must be a valid JavaScript regular expression, as used by the {{jsxref("RegExp")}} type, and as documented in our [guide on regular expressions](/en-US/docs/Web/JavaScript/Guide/Regular_expressions). No forward slashes should be specified around the pattern text. When compiling the regular expression: - - 1. the pattern will be implicitly wrapped with `^(?:` and `)$`, such that the match is required against the _entire_ input value, i.e., `^(?:<pattern>)$`. - 2. the `'v'` flag is specified so that the pattern is treated as a sequence of Unicode code points, instead of as {{Glossary("ASCII")}}. - - If the `pattern` attribute is present but is not specified or is invalid, no regular expression is applied and this attribute is ignored completely. If the pattern attribute is valid and a non-empty value does not match the pattern, constraint validation will prevent form submission. If the [`multiple`](/en-US/docs/Web/HTML/Attributes/multiple) is present, the compiled regular expression is matched against each comma separated value. - - > [!NOTE] - > If using the `pattern` attribute, inform the user about the expected format by including explanatory text nearby. You can also include a [`title`](#title) attribute to explain what the requirements are to match the pattern; most browsers will display this title as a tooltip. The visible explanation is required for accessibility. The tooltip is an enhancement. - - See [Client-side validation](#client-side_validation) for more information. - -- [`placeholder`](/en-US/docs/Web/HTML/Attributes/placeholder) - - - : Valid for `text`, `search`, `url`, `tel`, `email`, `password`, and `number`, the `placeholder` attribute provides a brief hint to the user as to what kind of information is expected in the field. It should be a word or short phrase that provides a hint as to the expected type of data, rather than an explanation or prompt. The text _must not_ include carriage returns or line feeds. So for example if a field is expected to capture a user's first name, and its label is "First Name", a suitable placeholder might be "e.g. Mustafa". - - > [!NOTE] - > The `placeholder` attribute is not as semantically useful as other ways to explain your form, and can cause unexpected technical issues with your content. See [Labels](#labels) for more information. - -- `popovertarget` - - - : Turns an `<input type="button">` element into a popover control button; takes the ID of the popover element to control as its value. See the {{domxref("Popover API", "Popover API", "", "nocode")}} landing page for more details. Establishing a relationship between a popover and its invoker button using the `popovertarget` attribute has two additional useful effects: - - - The browser creates an implicit [`aria-details`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-details) and [`aria-expanded`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-expanded) relationship between popover and invoker, and places the popover in a logical position in the keyboard focus navigation order when shown. This makes the popover more accessible to keyboard and assistive technology (AT) users (see also [Popover accessibility features](/en-US/docs/Web/API/Popover_API/Using#popover_accessibility_features)). - - The browser creates an implicit anchor reference between the two, making it very convenient to position popovers relative to their controls using [CSS anchor positioning](/en-US/docs/Web/CSS/CSS_anchor_positioning). See [Popover anchor positioning](/en-US/docs/Web/API/Popover_API/Using#popover_anchor_positioning) for more details. - -- `popovertargetaction` - - - : Specifies the action to be performed on a popover element being controlled by a control `<input type="button">`. Possible values are: - - - `"hide"` - - : The button will hide a shown popover. If you try to hide an already hidden popover, no action will be taken. - - `"show"` - - : The button will show a hidden popover. If you try to show an already showing popover, no action will be taken. - - `"toggle"` - - : The button will toggle a popover between showing and hidden. If the popover is hidden, it will be shown; if the popover is showing, it will be hidden. If `popovertargetaction` is omitted, `"toggle"` is the default action that will be performed by the control button. - -- [`readonly`](/en-US/docs/Web/HTML/Attributes/readonly) - - - : A Boolean attribute which, if present, indicates that the user should not be able to edit the value of the input. The `readonly` attribute is supported by the `text`, `search`, `url`, `tel`, `email`, `date`, `month`, `week`, `time`, `datetime-local`, `number`, and `password` input types. - - See the [HTML attribute: `readonly`](/en-US/docs/Web/HTML/Attributes/readonly) for more information. - -- [`required`](/en-US/docs/Web/HTML/Attributes/required) - - - : `required` is a Boolean attribute which, if present, indicates that the user must specify a value for the input before the owning form can be submitted. The `required` attribute is supported by `text`, `search`, `url`, `tel`, `email`, `date`, `month`, `week`, `time`, `datetime-local`, `number`, `password`, `checkbox`, `radio`, and `file` inputs. - - See [Client-side validation](#client-side_validation) and the [HTML attribute: `required`](/en-US/docs/Web/HTML/Attributes/required) for more information. - -- [`size`](/en-US/docs/Web/HTML/Attributes/size) - - - : Valid for `email`, `password`, `tel`, `url`, and `text`, the `size` attribute specifies how much of the input is shown. Basically creates same result as setting CSS [`width`](/en-US/docs/Web/CSS/width) property with a few specialties. The actual unit of the value depends on the input type. For `password` and `text`, it is a number of characters (or `em` units) with a default value of `20`, and for others, it is pixels (or `px` units). CSS `width` takes precedence over the `size` attribute. - -- `src` - - - : Valid for the `image` input button only, the `src` is string specifying the URL of the image file to display to represent the graphical submit button. See the {{HTMLElement("input/image", "image")}} input type. - -- [`step`](/en-US/docs/Web/HTML/Attributes/step) - - - : Valid for `date`, `month`, `week`, `time`, `datetime-local`, `number`, and `range`, the [`step`](/en-US/docs/Web/HTML/Attributes/step) attribute is a number that specifies the granularity that the value must adhere to. - - If not explicitly included: - - - `step` defaults to 1 for `number` and `range`. - - Each date/time input type has a default `step` value appropriate for the type; see the individual input pages: [`date`](/en-US/docs/Web/HTML/Element/input/date#step), [`datetime-local`](/en-US/docs/Web/HTML/Element/input/datetime-local#step), [`month`](/en-US/docs/Web/HTML/Element/input/month#step), [`time`](/en-US/docs/Web/HTML/Element/input/time#step), and [`week`](/en-US/docs/Web/HTML/Element/input/week#step). - - The value must be a positive number—integer or float—or the special value `any`, which means no stepping is implied, and any value is allowed (barring other constraints, such as [`min`](#min) and [`max`](#max)). - - If `any` is not explicitly set, valid values for the `number`, date/time input types, and `range` input types are equal to the basis for stepping — the [`min`](#min) value and increments of the step value, up to the [`max`](#max) value, if specified. - - For example, if you have `<input type="number" min="10" step="2">`, then any even integer, `10` or greater, is valid. If omitted, `<input type="number">`, any integer is valid, but floats (like `4.2`) are not valid, because `step` defaults to `1`. For `4.2` to be valid, `step` would have had to be set to `any`, 0.1, 0.2, or any the `min` value would have had to be a number ending in `.2`, such as `<input type="number" min="-5.2">` - - > [!NOTE] - > When the data entered by the user doesn't adhere to the stepping configuration, the value is considered invalid in constraint validation and will match the `:invalid` pseudoclass. - - See [Client-side validation](#client-side_validation) for more information. - -- `tabindex` - - - : Global attribute valid for all elements, including all the input types, an integer attribute indicating if the element can take input focus (is focusable), if it should participate to sequential keyboard navigation. As all input types except for input of type hidden are focusable, this attribute should not be used on form controls, because doing so would require the management of the focus order for all elements within the document with the risk of harming usability and accessibility if done incorrectly. - -- `title` - - - : Global attribute valid for all elements, including all input types, containing a text representing advisory information related to the element it belongs to. Such information can typically, but not necessarily, be presented to the user as a tooltip. The title should NOT be used as the primary explanation of the purpose of the form control. Instead, use the {{htmlelement('label')}} element with a `for` attribute set to the form control's [`id`](#id) attribute. See [Labels](#labels) below. - -- `type` - - - : A string specifying the type of control to render. For example, to create a checkbox, a value of `checkbox` is used. If omitted (or an unknown value is specified), the input type `text` is used, creating a plaintext input field. - - Permitted values are listed in [Input types](#input_types) above. - -- `value` - - - : The input control's value. When specified in the HTML, this is the initial value, and from then on it can be altered or retrieved at any time using JavaScript to access the respective {{domxref("HTMLInputElement")}} object's `value` property. The `value` attribute is always optional, though should be considered mandatory for `checkbox`, `radio`, and `hidden`. - -- `width` - - - : Valid for the `image` input button only, the `width` is the width of the image file to display to represent the graphical submit button. See the {{HTMLElement("input/image", "image")}} input type. - -### Non-standard attributes - -The following non-standard attributes are also available on some browsers. As a general rule, you should avoid using them unless it can't be helped. - -<table class="no-markdown"> - <thead> - <tr> - <th scope="col">Attribute</th> - <th scope="col">Description</th> - </tr> - </thead> - <tbody> - <tr> - <td><a href="#incremental"><code>incremental</code></a></td> - <td> - Whether or not to send repeated {{domxref("HTMLInputElement/search_event", "search")}} events to allow updating live search results while the user is still editing the value of the field. - <strong>WebKit and Blink only (Safari, Chrome, Opera, etc.).</strong> - </td> - </tr> - <tr> - <td><code>mozactionhint</code> {{deprecated_inline}}</td> - <td> - <p>A string indicating the type of action that will be taken when the user - presses the <kbd>Enter</kbd> or <kbd>Return</kbd> key while editing the - field; this is used to determine an appropriate label for that key on a - virtual keyboard. <strong>Since this attribute is deprecated, use <a href="/en-US/docs/Web/HTML/Global_attributes/enterkeyhint"><code>enterkeyhint</code></a> instead.</strong></p> - </td> - </tr> - <tr> - <td><a href="#orient"><code>orient</code></a></td> - <td> - Sets the orientation of the range slider. <strong>Firefox only</strong>. - </td> - </tr> - <tr> - <td><a href="#results"><code>results</code></a></td> - <td> - The maximum number of items that should be displayed in the drop-down list of previous search queries. <strong>Safari only.</strong> - </td> - </tr> - <tr> - <td> - <a href="#webkitdirectory"><code>webkitdirectory</code></a> - </td> - <td> - A Boolean indicating whether to only allow the user to choose a directory (or directories, if <a href="#multiple"><code>multiple</code></a> is also present) - </td> - </tr> - </tbody> -</table> - -- `incremental` {{non-standard_inline}} - - - : The Boolean attribute `incremental` is a WebKit and Blink extension (so supported by Safari, Opera, Chrome, etc.) which, if present, tells the {{Glossary("user agent")}} to process the input as a live search. As the user edits the value of the field, the user agent sends {{domxref("HTMLInputElement/search_event", "search")}} events to the {{domxref("HTMLInputElement")}} object representing the search box. This allows your code to update the search results in real time as the user edits the search. - - If `incremental` is not specified, the {{domxref("HTMLInputElement/search_event", "search")}} event is only sent when the user explicitly initiates a search (such as by pressing the <kbd>Enter</kbd> or <kbd>Return</kbd> key while editing the field). - - The `search` event is rate-limited so that it is not sent more frequently than an implementation-defined interval. - -- `orient` {{non-standard_inline}} - - - : Similar to the -moz-orient non-standard CSS property impacting the {{htmlelement('progress')}} and {{htmlelement('meter')}} elements, the `orient` attribute defines the orientation of the range slider. Values include `horizontal`, meaning the range is rendered horizontally, and `vertical`, where the range is rendered vertically. See [Creating vertical form controls](/en-US/docs/Web/CSS/CSS_writing_modes/Vertical_controls) for a modern approach to creating vertical form controls. - -- `results` {{non-standard_inline}} - - - : The `results` attribute—supported only by Safari—is a numeric value that lets you override the maximum number of entries to be displayed in the `<input>` element's natively-provided drop-down menu of previous search queries. - - The value must be a non-negative decimal number. If not provided, or an invalid value is given, the browser's default maximum number of entries is used. - -- `webkitdirectory` {{non-standard_inline}} - - - : The Boolean `webkitdirectory` attribute, if present, indicates that only directories should be available to be selected by the user in the file picker interface. See {{domxref("HTMLInputElement.webkitdirectory")}} for additional details and examples. - - Though originally implemented only for WebKit-based browsers, `webkitdirectory` is also usable in Microsoft Edge as well as Firefox 50 and later. However, even though it has relatively broad support, it is still not standard and should not be used unless you have no alternative. - -## Methods - -The following methods are provided by the {{domxref("HTMLInputElement")}} interface which represents `<input>` elements in the DOM. Also available are those methods specified by the parent interfaces, {{domxref("HTMLElement")}}, {{domxref("Element")}}, {{domxref("Node")}}, and {{domxref("EventTarget")}}. - -- {{domxref("HTMLInputElement.checkValidity", "checkValidity()")}} - - : Returns `true` if the element's value passes validity checks; otherwise, returns `false` and fires an {{domxref("HTMLInputElement.invalid_event", "invalid")}} event at the element. -- {{domxref("HTMLInputElement.reportValidity", "reportValidity()")}} - - : Returns `true` if the element's value passes validity checks; otherwise, returns `false`, fires an {{domxref("HTMLInputElement.invalid_event", "invalid")}} event at the element, and (if the event isn't canceled) reports the problem to the user. -- {{domxref("HTMLInputElement.select", "select()")}} - - : Selects the entire content of the `<input>` element, if the element's content is selectable. For elements with no selectable text content (such as a visual color picker or calendar date input), this method does nothing. -- {{domxref("HTMLInputElement.setCustomValidity", "setCustomValidity()")}} - - : Sets a custom message to display if the input element's value isn't valid. -- {{domxref("HTMLInputElement.setRangeText", "setRangeText()")}} - - : Sets the contents of the specified range of characters in the input element to a given string. A `selectMode` parameter is available to allow controlling how the existing content is affected. -- {{domxref("HTMLInputElement.setSelectionRange", "setSelectionRange()")}} - - : Selects the specified range of characters within a textual input element. Does nothing for inputs which aren't presented as text input fields. -- {{domxref("HTMLInputElement.showPicker", "showPicker()")}} - - : Displays the browser picker for the input element that would normally be displayed when the element is selected, but triggered from a button press or other user interaction. -- {{domxref("HTMLInputElement.stepDown", "stepDown()")}} - - : Decrements the value of a numeric input by one, by default, or by the specified number of units. -- {{domxref("HTMLInputElement.stepUp", "stepUp()")}} - - : Increments the value of a numeric input by one or by the specified number of units. - -## CSS - -Inputs, being replaced elements, have a few features not applicable to non form elements. There are CSS selectors that can specifically target form controls based on their UI features, also known as UI pseudo-classes. The input element can also be targeted by type with attribute selectors. There are some properties that are especially useful as well. - -### UI pseudo-classes - -<table class="no-markdown"> - <caption> - Pseudo-classes relevant to the - <code>&#x3C;input></code> - element: - </caption> - <thead> - <tr> - <th>Pseudo-class</th> - <th>Description</th> - </tr> - </thead> - <tbody> - <tr> - <td>{{Cssxref(":enabled")}}</td> - <td> - Any currently enabled element that can be activated (selected, clicked - on, typed into, etc.) or accept focus and also has a disabled state, in - which it can't be activated or accept focus. - </td> - </tr> - <tr> - <td>{{Cssxref(":disabled")}}</td> - <td> - Any currently disabled element that has an enabled state, meaning it - otherwise could be activated (selected, clicked on, typed into, etc.) or - accept focus were it not disabled. - </td> - </tr> - <tr> - <td>{{Cssxref(":read-only")}}</td> - <td>Element not editable by the user</td> - </tr> - <tr> - <td>{{Cssxref(":read-write")}}</td> - <td>Element that is editable by the user.</td> - </tr> - <tr> - <td>{{Cssxref(":placeholder-shown")}}</td> - <td> - Element that is currently displaying <a href="#placeholder"><code>placeholder</code> text</a>, - including <code>&#x3C;input></code> and {{HTMLElement("textarea")}} elements with the <a href="#placeholder"><code>placeholder</code></a> attribute present that has, as yet, no value. - </td> - </tr> - <tr> - <td>{{Cssxref(":default")}}</td> - <td> - Form elements that are the default in a group of related elements. - Matches {{HTMLElement("input/checkbox", "checkbox")}} and - {{HTMLElement("input/radio", "radio")}} input types that - were checked on page load or render. - </td> - </tr> - <tr> - <td>{{Cssxref(":checked")}}</td> - <td> - Matches {{HTMLElement("input/checkbox", "checkbox")}} and - {{HTMLElement("input/radio", "radio")}} input types that - are currently checked (and the ({{HTMLElement("option")}} in a - {{HTMLElement("select")}} that is currently selected). - </td> - </tr> - <tr> - <td>{{Cssxref(":indeterminate")}}</td> - <td> - {{HTMLElement("input/checkbox", "checkbox")}} elements - whose indeterminate property is set to true by JavaScript, - {{HTMLElement("input/radio", "radio")}} elements, when all - radio buttons with the same name value in the form are unchecked, and - {{HTMLElement("progress")}} elements in an indeterminate state - </td> - </tr> - <tr> - <td>{{Cssxref(":valid")}}</td> - <td> - Form controls that can have constraint validation applied and are - currently valid. - </td> - </tr> - <tr> - <td>{{Cssxref(":invalid")}}</td> - <td> - Form controls that have constraint validation applied and are currently - not valid. Matches a form control whose value doesn't match the - constraints set on it by its attributes, such as - <a href="#required"><code>required</code></a>, - <a href="#pattern"><code>pattern</code></a>, - <a href="#step"><code>step</code></a> and <a href="#max"><code>max</code></a>. - </td> - </tr> - <tr> - <td>{{Cssxref(":in-range")}}</td> - <td> - A non-empty input whose current value is within the range limits - specified by the <a href="#min"><code>min</code></a> and <a href="#max"><code>max</code></a> attributes and the <a href="#step"><code>step</code></a>. - </td> - </tr> - <tr> - <td>{{Cssxref(":out-of-range")}}</td> - <td> - A non-empty input whose current value is NOT within the range limits - specified by the <a href="#min"><code>min</code></a> - and <a href="#max"><code>max</code></a> attributes or - does not adhere to the <a href="#step"><code>step</code></a> constraint. - </td> - </tr> - <tr> - <td>{{Cssxref(":required")}}</td> - <td> - <code>&#x3C;input></code>, {{HTMLElement("select")}}, or {{HTMLElement("textarea")}} element that has the <a href="#required"><code>required</code></a> attribute set on it. - Only matches elements that can be required. - The attribute included on a non-requirable element will not make for a match. - </td> - </tr> - <tr> - <td>{{Cssxref(":optional")}}</td> - <td> - <code>&#x3C;input></code>, {{HTMLElement("select")}}, or - {{HTMLElement("textarea")}} element that does NOT have the <a href="#required"><code>required</code></a> attribute set on it. - Does not match elements that can't be required. - </td> - </tr> - <tr> - <td>{{Cssxref(":blank")}}</td> - <td> - <code>&#x3C;input></code> and {{HTMLElement("textarea")}} elements that currently have no value. - </td> - </tr> - <tr> - <td>{{Cssxref(":user-invalid")}}</td> - <td> - Similar to <code>:invalid</code>, but is activated on blur. Matches - invalid input but only after the user interaction, such as by focusing - on the control, leaving the control, or attempting to submit the form - containing the invalid control. - </td> - </tr> - <tr> - <td>{{Cssxref(":open")}}</td> - <td> - <code>&lt;input&gt;</code> elements that display a picker for the user to choose a value from (for example <a href="/en-US/docs/Web/HTML/Element/input/color"><code>&lt;input type="color"&gt;</code></a>) — but only when the element is in the open state, that is, when the picker is displayed. - </td> - </tr> - </tbody> -</table> - -#### Pseudo-classes example - -We can style a checkbox label based on whether the checkbox is checked or not. In this example, we are styling the {{cssxref('color')}} and {{cssxref('font-weight')}} of the {{htmlelement('label')}} that comes immediately after a checked input. We haven't applied any styles if the `input` is not checked. - -```html hidden -<input id="checkboxInput" type="checkbox" /> -<label for="checkboxInput">Toggle the checkbox on and off</label> -``` - -```css -input:checked + label { - color: red; - font-weight: bold; -} -``` - -{{EmbedLiveSample('Pseudo-classes_example', 500, 80)}} - -### Attribute selectors - -It is possible to target different types of form controls based on their [`type`](#type) using [attribute selectors](/en-US/docs/Learn_web_development/Core/Styling_basics/Attribute_selectors). CSS attribute selectors match elements based on either just the presence of an attribute or the value of a given attribute. - -```css -/* matches a password input */ -input[type="password"] { -} - -/* matches a form control whose valid values are limited to a range of values*/ -input[min][max] { -} - -/* matches a form control with a pattern attribute */ -input[pattern] { -} -``` - -### ::placeholder - -By default, the appearance of placeholder text is a translucent or light gray. The {{cssxref('::placeholder')}} pseudo-element is the input's [`placeholder` text](#placeholder). It can be styled with a limited subset of CSS properties. - -```css -::placeholder { - color: blue; -} -``` - -Only the subset of CSS properties that apply to the {{cssxref("::first-line")}} pseudo-element can be used in a rule using `::placeholder` in its selector. - -### appearance - -The {{cssxref("appearance")}} property enables the displaying of (almost) any element as a platform-native style based on the operating system's theme as well as the removal of any platform-native styling with the `none` value. - -You could make a `<div>` look like a radio button with `div {appearance: radio;}` or a radio look like a checkbox with `[type="radio"] {appearance: checkbox;}`, but don't. - -Setting `appearance: none` removes platform native borders, but not functionality. - -### caret-color - -A property specific to text entry-related elements is the CSS {{cssxref("caret-color")}} property, which lets you set the color used to draw the text input caret: - -#### HTML - -```html -<label for="textInput">Note the red caret:</label> -<input id="textInput" class="custom" size="32" /> -``` - -#### CSS - -```css -input.custom { - caret-color: red; - font: - 16px "Helvetica", - "Arial", - "sans-serif"; -} -``` - -#### Result - -{{EmbedLiveSample('caret-color', 500, 80)}} - -### field-sizing - -The {{cssxref("field-sizing")}} property enables you to control the sizing behavior of form inputs (i.e. they are given a default preferred size by default.) This property enables you to override the default behavior, allowing form controls to adjust in size to fit their contents. - -This property is typically used to create form fields that shrinkwrap their content and grow as more text is entered. This works with input types that accept direct text input (for example, [`text`](/en-US/docs/Web/HTML/Element/input/text) and [`url`](/en-US/docs/Web/HTML/Element/input/url)), input type [`file`](/en-US/docs/Web/HTML/Element/input/file), and {{htmlelement("textarea")}} elements. - -### object-position and object-fit - -In certain cases (typically involving non-textual inputs and specialized interfaces), the `<input>` element is a [replaced element](/en-US/docs/Web/CSS/Replaced_element). When it is, the position and size of the element's size and positioning within its frame can be adjusted using the CSS {{cssxref("object-position")}} and {{cssxref("object-fit")}} properties. - -### Styling - -For more information about adding color to elements in HTML, see: - -- [Applying color to HTML elements using CSS](/en-US/docs/Web/CSS/CSS_colors/Applying_color). - -Also see: - -- [Styling HTML forms](/en-US/docs/Learn_web_development/Extensions/Forms/Styling_web_forms) -- [Advanced styling for HTML forms](/en-US/docs/Learn_web_development/Extensions/Forms/Advanced_form_styling) and - -## Additional features - -### Labels - -Labels are needed to associate assistive text with an `<input>`. The {{HTMLElement("label")}} element provides explanatory information about a form field that is _always_ appropriate (aside from any layout concerns you have). It's never a bad idea to use a `<label>` to explain what should be entered into an `<input>` or {{HTMLElement("textarea")}}. - -#### Associated labels - -The semantic pairing of `<input>` and `<label>` elements is useful for assistive technologies such as screen readers. By pairing them using the `<label>`'s [`for`](/en-US/docs/Web/HTML/Element/label#for) attribute, you bond the label to the input in a way that lets screen readers describe inputs to users more precisely. - -It does not suffice to have plain text adjacent to the `<input>` element. Rather, usability and accessibility requires the inclusion of either implicit or explicit {{HTMLElement("label")}}: - -```html -<!-- inaccessible --> -<p>Enter your name: <input id="name" type="text" size="30" /></p> - -<!-- implicit label --> -<p> - <label>Enter your name: <input id="name" type="text" size="30" /></label> -</p> - -<!-- explicit label --> -<p> - <label for="name">Enter your name: </label> - <input id="name" type="text" size="30" /> -</p> -``` - -The first example is inaccessible: no relationship exists between the prompt and the `<input>` element. - -In addition to an accessible name, the label provides a larger 'hit' area for mouse and touch screen users to click on or touch. By pairing a `<label>` with an `<input>`, clicking on either one will focus the `<input>`. If you use plain text to "label" your input, this won't happen. Having the prompt part of the activation area for the input is helpful for people with motor control conditions. - -As web developers, it's important that we never assume that people will know all the things that we know. The diversity of people using the web—and by extension your website—practically guarantees that some of your site's visitors will have some variation in thought processes and/or circumstances that leads them to interpret your forms very differently from you without clear and properly-presented labels. - -#### Placeholders are not accessible - -The [`placeholder`](#placeholder) attribute lets you specify text that appears within the `<input>` element's content area itself when it is empty. The placeholder should never be required to understand your forms. It is not a label, and should not be used as a substitute, because it isn't. The placeholder is used to provide a hint as to what an inputted value should look like, not an explanation or prompt. - -Not only is the placeholder not accessible to screen readers, but once the user enters any text into the form control, or if the form control already has a value, the placeholder disappears. Browsers with automatic page translation features may skip over attributes when translating, meaning the `placeholder` may not get translated. - -> [!NOTE] -> Don't use the [`placeholder`](#placeholder) attribute if you can avoid it. If you need to label an `<input>` element, use the {{HTMLElement("label")}} element. - -### Client-side validation - -> [!WARNING] -> Client-side validation is useful, but it does _not_ guarantee that the server will receive valid data. If the data must be in a specific format, _always_ verify it also on the server-side, and return a [`400` HTTP response](/en-US/docs/Web/HTTP/Status/400) if the format is invalid. - -In addition to using CSS to style inputs based on the {{cssxref(":valid")}} or {{cssxref(":invalid")}} UI states based on the current state of each input, as noted in the [UI pseudo-classes](#ui_pseudo-classes) section above, the browser provides for client-side validation on (attempted) form submission. On form submission, if there is a form control that fails constraint validation, supporting browsers will display an error message on the first invalid form control; displaying a default message based on the error type, or a message set by you. - -Some input types and other attributes place limits on what values are valid for a given input. For example, `<input type="number" min="2" max="10" step="2">` means only the number 2, 4, 6, 8, or 10 are valid. Several errors could occur, including a `rangeUnderflow` error if the value is less than 2, `rangeOverflow` if greater than 10, `stepMismatch` if the value is a number between 2 and 10, but not an even integer (does not match the requirements of the `step` attribute), or `typeMismatch` if the value is not a number. - -For the input types whose domain of possible values is periodic (that is, at the highest possible value, the values wrap back around to the beginning rather than ending), it's possible for the values of the [`max`](#max) and [`min`](#min) properties to be reversed, which indicates that the range of permitted values starts at `min`, wraps around to the lowest possible value, then continues on until `max` is reached. This is particularly useful for dates and times, such as when you want to allow the range to be from 8 PM to 8 AM: - -```html -<input type="time" min="20:00" max="08:00" name="overnight" /> -``` - -Specific attributes and their values can lead to a specific error {{domxref('ValidityState')}}: - -<table class="no-markdown"> - <caption> - Validity object errors depend on the <code>&lt;input&gt;</code> - attributes and their values: - </caption> - <thead> - <tr> - <th scope="col">Attribute</th> - <th scope="col">Relevant property</th> - <th scope="col">Description</th> - </tr> - </thead> - <tbody> - <tr> - <td><a href="#max"><code>max</code></a></td> - <td>{{domxref('validityState.rangeOverflow')}}</td> - <td> - Occurs when the value is greater than the maximum value as defined by - the <code>max</code> attribute - </td> - </tr> - <tr> - <td><a href="#maxlength"><code>maxlength</code></a></td> - <td>{{domxref('validityState.tooLong')}}</td> - <td> - Occurs when the number of characters is greater than the number allowed by the <code>maxlength</code> property - </td> - </tr> - <tr> - <td><a href="#min"><code>min</code></a></td> - <td>{{domxref('validityState.rangeUnderflow')}}</td> - <td> - Occurs when the value is less than the minimum value as defined by the <code>min</code> attribute - </td> - </tr> - <tr> - <td><a href="#minlength"><code>minlength</code></a></td> - <td>{{domxref('validityState.tooShort')}}</td> - <td> - Occurs when the number of characters is less than the number required by the <code>minlength</code> property - </td> - </tr> - <tr> - <td><a href="#pattern"><code>pattern</code></a></td> - <td>{{domxref('validityState.patternMismatch')}}</td> - <td> - Occurs when a pattern attribute is included with a valid regular expression and the <code>value</code> does not match it. - </td> - </tr> - <tr> - <td><a href="#required"><code>required</code></a></td> - <td>{{domxref('validityState.valueMissing')}}</td> - <td> - Occurs when the <code>required</code> attribute is present but the value is <code>null</code> or radio or checkbox is not checked. - </td> - </tr> - <tr> - <td><a href="#step"><code>step</code></a></td> - <td>{{domxref('validityState.stepMismatch')}}</td> - <td> - The value doesn't match the step increment. Increment default is <code>1</code>, so only integers are valid on <code>type="number"</code> - is step is not included. <code>step="any"</code> will never throw this error. - </td> - </tr> - <tr> - <td><a href="#type"><code>type</code></a></td> - <td>{{domxref('validityState.typeMismatch')}}</td> - <td> - Occurs when the value is not of the correct type, for example an email does not contain an <code>@</code> or a url doesn't contain a protocol. - </td> - </tr> - </tbody> -</table> - -If a form control doesn't have the `required` attribute, no value, or an empty string, is not invalid. Even if the above attributes are present, with the exception of `required`, an empty string will not lead to an error. - -We can set limits on what values we accept, and supporting browsers will natively validate these form values and alert the user if there is a mistake when the form is submitted. - -In addition to the errors described in the table above, the `validityState` interface contains the `badInput`, `valid`, and `customError` boolean readonly properties. The validity object includes: - -- {{domxref('validityState.valueMissing')}} -- {{domxref('validityState.typeMismatch')}} -- {{domxref('validityState.patternMismatch')}} -- {{domxref('validityState.tooLong')}} -- {{domxref('validityState.tooShort')}} -- {{domxref('validityState.rangeUnderflow')}} -- {{domxref('validityState.rangeOverflow')}} -- {{domxref('validityState.stepMismatch')}} -- {{domxref('validityState.badInput')}} -- {{domxref('validityState', 'validityState.valid')}} -- {{domxref('validityState', 'validityState.customError')}} - -For each of these Boolean properties, a value of `true` indicates that the specified reason validation may have failed is true, with the exception of the `valid` property, which is `true` if the element's value obeys all constraints. - -If there is an error, supporting browsers will both alert the user and prevent the form from being submitted. A word of caution: if a custom error is set to a truthy value (anything other than the empty string or `null`), the form will be prevented from being submitted. If there is no custom error message, and none of the other properties return true, `valid` will be true, and the form can be submitted. - -```js -function validate(input) { - let validityState_object = input.validity; - if (validityState_object.valueMissing) { - input.setCustomValidity("A value is required"); - } else if (validityState_object.rangeUnderflow) { - input.setCustomValidity("Your value is too low"); - } else if (validityState_object.rangeOverflow) { - input.setCustomValidity("Your value is too high"); - } else { - input.setCustomValidity(""); - } -} -``` - -The last line, setting the custom validity message to the empty string is vital. If the user makes an error, and the validity is set, it will fail to submit, even if all the values are valid, until the message is `null`. - -#### Custom validation error example - -If you want to present a custom error message when a field fails to validate, you need to use the [Constraint Validation API](/en-US/docs/Learn_web_development/Extensions/Forms/Form_validation#validating_forms_using_javascript) available on `<input>` (and related) elements. Take the following form: - -```html -<form> - <label for="name">Enter username (upper and lowercase letters): </label> - <input type="text" name="name" id="name" required pattern="[A-Za-z]+" /> - <button>Submit</button> -</form> -``` - -The basic HTML form validation features will cause this to produce a default error message if you try to submit the form with either no valid filled in, or a value that does not match the `pattern`. - -If you wanted to instead display custom error messages, you could use JavaScript like the following: - -```js -const nameInput = document.querySelector("input"); - -nameInput.addEventListener("input", () => { - nameInput.setCustomValidity(""); - nameInput.checkValidity(); -}); - -nameInput.addEventListener("invalid", () => { - if (nameInput.value === "") { - nameInput.setCustomValidity("Enter your username!"); - } else { - nameInput.setCustomValidity( - "Usernames can only contain upper and lowercase letters. Try again!", - ); - } -}); -``` - -The example renders like so: - -{{EmbedLiveSample('Custom_validation_error_example')}} - -In brief: - -- We check the valid state of the input element every time its value is changed by running the `checkValidity()` method via the `input` event handler. -- If the value is invalid, an `invalid` event is raised, and the `invalid` event handler function is run. Inside this function we work out whether the value is invalid because it is empty, or because it doesn't match the pattern, using an `if ()` block, and set a custom validity error message. -- As a result, if the input value is invalid when the submit button is pressed, one of the custom error messages will be shown. -- If it is valid, it will submit as you'd expect. For this to happen, the custom validity has to be cancelled, by invoking `setCustomValidity()` with an empty string value. We therefore do this every time the `input` event is raised. If you don't do this, and a custom validity was previously set, the input will register as invalid, even if it currently contains a valid value on submission. - -> [!NOTE] -> Always validate input constraints both client side and server side. Constraint validation doesn't remove the need for validation on the _server side_. Invalid values can still be sent by older browsers or by bad actors. - -> [!NOTE] -> Firefox supported a proprietary error attribute — `x-moz-errormessage` — for many versions, which allowed you set custom error messages in a similar way. This has been removed as of version 66 (see [Firefox bug 1513890](https://bugzil.la/1513890)). - -### Localization - -The allowed inputs for certain `<input>` types depend on the locale. In some locales, 1,000.00 is a valid number, while in other locales the valid way to enter this number is 1.000,00. - -Firefox uses the following heuristics to determine the locale to validate the user's input (at least for `type="number"`): - -- Try the language specified by a `lang`/`xml:lang` attribute on the element or any of its parents. -- Try the language specified by any `Content-Language` HTTP header. Or, -- If none specified, use the browser's locale. - -## Accessibility - -### Labels - -When including inputs, it is an accessibility requirement to add labels alongside. This is needed so those who use assistive technologies can tell what the input is for. Also, clicking or touching a label gives focus to the label's associated form control. This improves the accessibility and usability for sighted users, increases the area a user can click or touch to activate the form control. This is especially useful (and even needed) for radio buttons and checkboxes, which are tiny. For more information about labels in general see [Labels](#labels). - -The following is an example of how to associate the `<label>` with an `<input>` element in the above style. You need to give the `<input>` an `id` attribute. The `<label>` then needs a `for` attribute whose value is the same as the input's `id`. - -```html -<label for="peas">Do you like peas?</label> -<input type="checkbox" name="peas" id="peas" /> -``` - -### Size - -Interactive elements such as form input should provide an area large enough that it is easy to activate them. This helps a variety of people, including people with motor control issues and people using non-precise forms of input such as a stylus or fingers. A minimum interactive size of 44×44 [CSS pixels](https://www.w3.org/TR/WCAG21/#dfn-css-pixels) is recommended. - -- [Understanding Success Criterion 2.5.5: Target Size | W3C Understanding WCAG 2.1](https://www.w3.org/WAI/WCAG21/Understanding/target-size.html) -- [Target Size and 2.5.5 | Adrian Roselli](https://adrianroselli.com/2019/06/target-size-and-2-5-5.html) -- [Quick test: Large touch targets - The A11Y Project](https://www.a11yproject.com/posts/large-touch-targets/) - -## Technical summary - -<table class="properties"> - <tbody> - <tr> - <th scope="row"> - <a href="/en-US/docs/Web/HTML/Content_categories">Content categories</a> - </th> - <td> - <a href="/en-US/docs/Web/HTML/Content_categories#flow_content">Flow content</a>, listed, submittable, resettable, form-associated element, - <a href="/en-US/docs/Web/HTML/Content_categories#phrasing_content">phrasing content</a>. If the <a href="#type"><code>type</code></a> is not - <code>hidden</code>, then labelable element, palpable content. - </td> - </tr> - <tr> - <th scope="row">Permitted content</th> - <td>None; it is a {{Glossary("void element")}}.</td> - </tr> - <tr> - <th scope="row">Tag omission</th> - <td>Must have a start tag and must not have an end tag.</td> - </tr> - <tr> - <th scope="row">Permitted parents</th> - <td> - Any element that accepts - <a href="/en-US/docs/Web/HTML/Content_categories#phrasing_content">phrasing content</a>. - </td> - </tr> - <tr> - <th scope="row">Implicit ARIA role</th> - <td> - <ul> - <li> - <code>type=button</code>: - <code - ><a href="/en-US/docs/Web/Accessibility/ARIA/Roles/button_role">button</a></code> - </li> - <li> - <code>type=checkbox</code>: - <code><a href="/en-US/docs/Web/Accessibility/ARIA/Roles/checkbox_role">checkbox</a></code> - </li> - <li> - <code>type=email</code> - <ul> - <li> - with no <code>list</code> attribute: - <code - ><a - href="/en-US/docs/Web/Accessibility/ARIA/Roles/textbox_role">textbox</a></code> - </li> - <li> - with <code>list</code> attribute: <a href="/en-US/docs/Web/Accessibility/ARIA/Roles/combobox_role"><code>combobox</code></a> - </li> - </ul> - </li> - <li> - <code>type=image</code>: - <code - ><a href="/en-US/docs/Web/Accessibility/ARIA/Roles/button_role">button</a></code> - </li> - <li> - <code>type=number</code>: <a href="/en-US/docs/Web/Accessibility/ARIA/Roles/spinbutton_role"><code>spinbutton</code></a> - </li> - <li><code>type=radio</code>: <a href="/en-US/docs/Web/Accessibility/ARIA/Roles/radio_role"><code>radio</code></a></li> - <li><code>type=range</code>: <a href="/en-US/docs/Web/Accessibility/ARIA/Roles/slider_role"><code>slider</code></a></li> - <li> - <code>type=reset</code>: - <code><a href="/en-US/docs/Web/Accessibility/ARIA/Roles/button_role">button</a></code> - </li> - <li> - <code>type=search</code> - <ul> - <li> - with no <code>list</code> attribute: <a href="/en-US/docs/Web/Accessibility/ARIA/Roles/searchbox_role"><code>searchbox</code></a> - </li> - <li> - with <code>list</code> attribute: <a href="/en-US/docs/Web/Accessibility/ARIA/Roles/combobox_role"><code>combobox</code></a> - </li> - </ul> - </li> - <li> - <code>type=submit</code>: - <code - ><a href="/en-US/docs/Web/Accessibility/ARIA/Roles/button_role">button</a></code> - </li> - <li> - <code>type=tel</code> - <ul> - <li> - with no <code>list</code> attribute: - <code><a href="/en-US/docs/Web/Accessibility/ARIA/Roles/textbox_role">textbox</a></code> - </li> - <li> - with <code>list</code> attribute: <a href="/en-US/docs/Web/Accessibility/ARIA/Roles/combobox_role"><code>combobox</code></a> - </li> - </ul> - </li> - <li> - <code>type=text</code> - <ul> - <li> - with no <code>list</code> attribute: - <code><a href="/en-US/docs/Web/Accessibility/ARIA/Roles/textbox_role">textbox</a></code> - </li> - <li> - with <code>list</code> attribute: <a href="/en-US/docs/Web/Accessibility/ARIA/Roles/combobox_role"><code>combobox</code></a> - </li> - </ul> - </li> - <li> - <code>type=url</code> - <ul> - <li> - with no <code>list</code> attribute: - <code - ><a href="/en-US/docs/Web/Accessibility/ARIA/Roles/textbox_role">textbox</a ></code> - </li> - <li> - with <code>list</code> attribute: <a href="/en-US/docs/Web/Accessibility/ARIA/Roles/combobox_role"><code>combobox</code></a> - </li> - </ul> - </li> - <li> - <code>type=color|date|datetime-local|file|hidden|month|password|time|week</code>: - <a href="https://www.w3.org/TR/html-aria/#dfn-no-corresponding-role">no corresponding role</a> - </li> - </ul> - </td> - </tr> - <tr> - <th scope="row">Permitted ARIA roles</th> - <td> - <ul> - <li> - <code>type=button</code>: <a href="/en-US/docs/Web/Accessibility/ARIA/Roles/checkbox_role"><code>checkbox</code></a>, - <a href="/en-US/docs/Web/Accessibility/ARIA/Roles/combobox_role"><code>combobox</code></a>, - <a href="/en-US/docs/Web/Accessibility/ARIA/Roles/link_role"><code>link</code></a>, - <a href="/en-US/docs/Web/Accessibility/ARIA/Roles/menuitem_role"><code>menuitem</code></a>, - <a href="/en-US/docs/Web/Accessibility/ARIA/Roles/menuitemcheckbox_role"><code>menuitemcheckbox</code></a>, - <a href="/en-US/docs/Web/Accessibility/ARIA/Roles/menuitemradio_role"><code>menuitemradio</code></a>, - <a href="/en-US/docs/Web/Accessibility/ARIA/Roles/option_role"><code>option</code></a>, <a href="/en-US/docs/Web/Accessibility/ARIA/Roles/radio_role"><code>radio</code></a>, - <a href="/en-US/docs/Web/Accessibility/ARIA/Roles/switch_role"><code>switch</code></a>, <a href="/en-US/docs/Web/Accessibility/ARIA/Roles/tab_role"><code>tab</code></a> - </li> - <li> - <code>type=checkbox</code>: <a href="/en-US/docs/Web/Accessibility/ARIA/Roles/button_role"><code>button</code></a> when used - with <code>aria-pressed</code>, - <a href="/en-US/docs/Web/Accessibility/ARIA/Roles/menuitemcheckbox_role"><code>menuitemcheckbox</code></a>, - <a href="/en-US/docs/Web/Accessibility/ARIA/Roles/option_role"><code>option</code></a>, <a href="/en-US/docs/Web/Accessibility/ARIA/Roles/switch_role"><code>switch</code></a> - </li> - <li> - <code>type=image</code>: <a href="/en-US/docs/Web/Accessibility/ARIA/Roles/link_role"><code>link</code></a>, - <a href="/en-US/docs/Web/Accessibility/ARIA/Roles/menuitem_role"><code>menuitem</code></a>, - <a href="/en-US/docs/Web/Accessibility/ARIA/Roles/menuitemcheckbox_role"><code>menuitemcheckbox</code></a>, - <a href="/en-US/docs/Web/Accessibility/ARIA/Roles/menuitemradio_role"><code>menuitemradio</code></a>, - <a href="/en-US/docs/Web/Accessibility/ARIA/Roles/radio_role"><code>radio</code></a>, <a href="/en-US/docs/Web/Accessibility/ARIA/Roles/switch_role"><code>switch</code></a> - </li> - <li> - <code>type=radio</code>: <a href="/en-US/docs/Web/Accessibility/ARIA/Roles/menuitemradio_role"><code>menuitemradio</code></a> - </li> - <li> - <code>type=text</code> with no <code>list</code> attribute: - <a href="/en-US/docs/Web/Accessibility/ARIA/Roles/combobox_role"><code>combobox</code></a>, <a href="/en-US/docs/Web/Accessibility/ARIA/Roles/searchbox_role"><code>searchbox</code></a>, - <a href="/en-US/docs/Web/Accessibility/ARIA/Roles/spinbutton_role"><code>spinbutton</code></a> - </li> - <li> - <code>type=color|date|datetime-local|email|file|hidden|</code> - <code>month|number|password|range|reset|search|submit|tel|url|week</code> - or <code>text</code> with <code>list</code> attribute: no - <code>role</code> permitted - </li> - </ul> - </td> - </tr> - <tr> - <th scope="row">DOM interface</th> - <td>{{domxref("HTMLInputElement")}}</td> - </tr> - </tbody> -</table> - -## Specifications - -{{Specifications}} - -## Browser compatibility - -{{Compat}} - -## See also - -- [Form constraint validation](/en-US/docs/Web/HTML/Constraint_validation) -- [Your first HTML form](/en-US/docs/Learn_web_development/Extensions/Forms/Your_first_form) -- [How to structure an HTML form](/en-US/docs/Learn_web_development/Extensions/Forms/How_to_structure_a_web_form) -- [The native form widgets](/en-US/docs/Learn_web_development/Extensions/Forms/Basic_native_form_controls) -- [Sending form data](/en-US/docs/Learn_web_development/Extensions/Forms/Sending_and_retrieving_form_data) -- [Form data validation](/en-US/docs/Learn_web_development/Extensions/Forms/Form_validation) -- [How to build custom form widgets](/en-US/docs/Learn_web_development/Extensions/Forms/How_to_build_custom_form_controls) -- [HTML forms in legacy browsers](/en-US/docs/Learn_web_development/Extensions/Forms/HTML_forms_in_legacy_browsers) -- [Styling HTML forms](/en-US/docs/Learn_web_development/Extensions/Forms/Styling_web_forms) -- [Advanced styling for HTML forms](/en-US/docs/Learn_web_development/Extensions/Forms/Advanced_form_styling) -- [Creating vertical form controls](/en-US/docs/Web/CSS/CSS_writing_modes/Vertical_controls) diff --git a/files/en-us/web/html/element/input/month/index.md b/files/en-us/web/html/element/input/month/index.md deleted file mode 100644 index 1186fcfd87a6432..000000000000000 --- a/files/en-us/web/html/element/input/month/index.md +++ /dev/null @@ -1,550 +0,0 @@ ---- -title: <input type="month"> -slug: Web/HTML/Element/input/month -page-type: html-element -browser-compat: html.elements.input.type_month ---- - -{{HTMLSidebar}} - -{{HTMLElement("input")}} elements of type **`month`** create input fields that let the user enter a month and year allowing a month and year to be easily entered. -The value is a string whose value is in the format `YYYY-MM`, where `YYYY` is the four-digit year and `MM` is the month number. - -{{InteractiveExample("HTML Demo: &lt;input type=&quot;month&quot;&gt;", "tabbed-shorter")}} - -```html interactive-example -<label for="start">Start month:</label> - -<input type="month" id="start" name="start" min="2018-03" value="2018-05" /> -``` - -```css interactive-example -label { - display: block; - font: - 1rem "Fira Sans", - sans-serif; -} - -input, -label { - margin: 0.4rem 0; -} -``` - -The control's UI varies in general from browser to browser; at the moment support is patchy, with only Chrome/Opera and Edge on desktop — and most modern mobile browser versions — having usable implementations. -In browsers that don't support `month` inputs, the control degrades gracefully to [`<input type="text">`](/en-US/docs/Web/HTML/Element/input/text), although there may be automatic validation of the entered text to ensure it's formatted as expected. - -For those of you using a browser that doesn't support `month`, the screenshot below shows what it looks like in Chrome and Opera. -Clicking the down arrow on the right-hand side brings up a date picker that lets you select the month and year. - -![Month control on Chrome browser](month-control-chrome.png) - -The Microsoft Edge `month` control looks like this: - -![Month control on Edge browser](month-control-edge.png) - -## Value - -A string representing the value of the month and year entered into the input, in the form YYYY-MM (four or more digit year, then a hyphen (`-`), followed by the two-digit month). -The format of the month string used by this input type is described in [Month strings](/en-US/docs/Web/HTML/Date_and_time_formats#month_strings). - -### Setting a default value - -You can set a default value for the input control by including a month and year inside the [`value`](/en-US/docs/Web/HTML/Element/input#value) attribute, like so: - -```html -<label for="bday-month">What month were you born in?</label> -<input id="bday-month" type="month" name="bday-month" value="2001-06" /> -``` - -{{EmbedLiveSample('Setting_a_default_value', 600, 60)}} - -One thing to note is that the displayed date format differs from the actual `value`; most {{Glossary("user agent", "user agents")}} display the month and year in a locale-appropriate form, based on the set locale of the user's operating system, whereas the date `value` is always formatted `yyyy-MM`. - -When the above value is submitted to the server, for example, it will look like `bday-month=1978-06`. - -### Setting the value using JavaScript - -You can also get and set the date value in JavaScript using the {{domxref("HTMLInputElement.value")}} property, for example: - -```html -<label for="bday-month">What month were you born in?</label> -<input id="bday-month" type="month" name="bday-month" /> -``` - -```js -const monthControl = document.querySelector('input[type="month"]'); -monthControl.value = "2001-06"; -``` - -{{EmbedLiveSample("Setting_the_value_using_JavaScript", 600, 60)}} - -## Additional attributes - -In addition to the attributes common to {{HTMLElement("input")}} elements, month inputs offer the following attributes. - -### list - -The values of the list attribute is the {{domxref("Element.id", "id")}} of a {{HTMLElement("datalist")}} element located in the same document. -The {{HTMLElement("datalist")}} provides a list of predefined values to suggest to the user for this input. -Any values in the list that are not compatible with the [`type`](/en-US/docs/Web/HTML/Element/input#type) are not included in the suggested options. -The values provided are suggestions, not requirements: users can select from this predefined list or provide a different value. - -### max - -The latest year and month, in the string format discussed in the [Value](#value) section above, to accept. -If the [`value`](/en-US/docs/Web/HTML/Element/input#value) entered into the element exceeds this, the element fails [constraint validation](/en-US/docs/Web/HTML/Constraint_validation). -If the value of the `max` attribute isn't a valid string in `yyyy-MM` format, then the element has no maximum value. - -This value must specify a year-month pairing later than or equal to the one specified by the `min` attribute. - -### min - -The earliest year and month to accept, in the same `yyyy-MM` format described above. -If the [`value`](/en-US/docs/Web/HTML/Element/input#value) of the element is less than this, the element fails [constraint validation](/en-US/docs/Web/HTML/Constraint_validation). -If a value is specified for `min` that isn't a valid year and month string, the input has no minimum value. - -This value must be a year-month pairing which is earlier than or equal to the one specified by the `max` attribute. - -### readonly - -A Boolean attribute which, if present, means this field cannot be edited by the user. -Its `value` can, however, still be changed from JavaScript code that directly sets the value of the {{domxref("HTMLInputElement.value")}} property. - -> [!NOTE] -> Because a read-only field cannot have a value, `required` does not have any effect on inputs with the `readonly` attribute also specified. - -### step - -The `step` attribute is a number that specifies the granularity that the value must adhere to, or the special value `any`, which is described below. -Only values which are equal to the basis for stepping ([`min`](#min) if specified, [`value`](/en-US/docs/Web/HTML/Element/input#value) otherwise, and an appropriate default value if neither of those is provided) are valid. - -A string value of `any` means that no stepping is implied, and any value is allowed (barring other constraints, such as [`min`](#min) and [`max`](#max)). - -> [!NOTE] -> When the data entered by the user doesn't adhere to the stepping configuration, the {{Glossary("user agent")}} may round to the nearest valid value, preferring numbers in the positive direction when there are two equally close options. - -For `month` inputs, the value of `step` is given in months, with a scaling factor of 1 (since the underlying numeric value is also in months). -The default value of `step` is 1 month. - -## Using month inputs - -Date-related inputs (including `month`) sound convenient at first glance; they promise an easy UI for choosing dates, and they normalize the data format sent to the server, regardless of the user's locale. -However, there are issues with `<input type="month">` because at this time, many major browsers don't yet support it. - -We'll look at basic and more complex uses of `<input type="month">`, then offer advice on mitigating the browser support issue in the section [Handling browser support](#handling_browser_support)). - -### Basic uses of month - -The most basic use of `<input type="month">` involves a basic {{HTMLElement("input")}} and {{htmlelement("label")}} element combination, as seen below: - -```html -<form> - <label for="bday-month">What month were you born in?</label> - <input id="bday-month" type="month" name="bday-month" /> -</form> -``` - -{{EmbedLiveSample('Basic_uses_of_month', 600, 40)}} - -### Setting maximum and minimum dates - -You can use the [`min`](/en-US/docs/Web/HTML/Element/input#min) and [`max`](/en-US/docs/Web/HTML/Element/input#max) attributes to restrict the range of dates that the user can choose. -In the following example we specify a minimum month of `1900-01` and a maximum month of `2013-12`: - -```html -<form> - <label for="bday-month">What month were you born in?</label> - <input - id="bday-month" - type="month" - name="bday-month" - min="1900-01" - max="2013-12" /> -</form> -``` - -{{EmbedLiveSample('Setting_maximum_and_minimum_dates', 600, 40)}} - -The result here is that: - -- Only months between in January 1900 and December 2013 can be selected; months outside that range can't be scrolled to in the control. -- Depending on what browser you are using, you might find that months outside the specified range might not be selectable in the month picker (e.g. Edge), or invalid (see [Validation](#validation)) but still available (e.g. Chrome). - -### Controlling input size - -`<input type="month">` doesn't support form sizing attributes such as [`size`](/en-US/docs/Web/HTML/Element/input#size). -You'll have to resort to [CSS](/en-US/docs/Web/CSS) for sizing needs. - -## Validation - -By default, `<input type="month">` does not apply any validation to entered values. -The UI implementations generally don't let you enter anything that isn't a date — which is helpful — but you can still submit the form with the `month` input empty, or enter an invalid date (e.g. the 32nd of April). - -To help avoid this, you can use [`min`](/en-US/docs/Web/HTML/Element/input#min) and [`max`](/en-US/docs/Web/HTML/Element/input#max) to restrict the available dates (see [Setting maximum and minimum dates](#setting_maximum_and_minimum_dates)), and in addition use the [`required`](/en-US/docs/Web/HTML/Element/input#required) attribute to make filling in the date mandatory. -As a result, supporting browsers will display an error if you try to submit a date that is outside the set bounds, or an empty date field. - -Let's look at an example; here we've set minimum and maximum dates, and also made the field required: - -```html -<form> - <div> - <label for="month"> - What month would you like to visit (June to Sept.)? - </label> - <input - id="month" - type="month" - name="month" - min="2022-06" - max="2022-09" - required /> - <span class="validity"></span> - </div> - <div> - <input type="submit" value="Submit form" /> - </div> -</form> -``` - -If you try to submit the form without both the month and year specified (or with a date outside the set bounds), the browser displays an error. -Try playing with the example now: - -{{ EmbedLiveSample('Validation', 600, 120) }} - -Here's a screenshot for those of you who aren't using a supporting browser: - -![Month required prompt on Chrome browser](month-required.png) - -Here's the CSS used in the above example. -Here we make use of the {{cssxref(":valid")}} and {{cssxref(":invalid")}} CSS properties to style the input based on whether the current value is valid. -We had to put the icons on a {{htmlelement("span")}} next to the input, not on the input itself, because in Chrome the generated content is placed inside the form control, and can't be styled or shown effectively. - -```css -div { - margin-bottom: 10px; - position: relative; -} - -input[type="number"] { - width: 100px; -} - -input + span { - padding-right: 30px; -} - -input:invalid + span::after { - position: absolute; - content: "✖"; - padding-left: 5px; -} - -input:valid + span::after { - position: absolute; - content: "✓"; - padding-left: 5px; -} -``` - -> [!WARNING] -> HTML form validation is _not_ a substitute for scripts that ensure that the entered data is in the proper format. -> It's far too easy for someone to make adjustments to the HTML that allow them to bypass the validation, or to remove it entirely. -> It's also possible for someone to bypass your HTML entirely and submit the data directly to your server. -> If your server-side code fails to validate the data it receives, disaster could strike when improperly-formatted data is submitted (or data which is too large, of the wrong type, and so forth). - -## Handling browser support - -As mentioned above, the major problem with using date inputs at the time of writing is that many major browsers don't yet implement them all; only Chrome/Opera and Edge support it on desktop, and most modern browsers on mobile. -As an example, the `month` picker on Chrome for Android looks like this: - -![Month picker on Chrome for Android](month-android.png) - -Non-supporting browsers gracefully degrade to a text input, but this creates problems both in terms of consistency of user interface (the presented control will be different), and data handling. - -The second problem is the more serious of the two. -As mentioned earlier, with a `month` input the actual value is always normalized to the format `yyyy-mm`. -On the other hand, in its default configuration, a `text` input has no idea what format the date should be in, and this is an issue because of the number of different ways in which people write dates. -For example: - -- `mmyyyy` (072022) -- `mm/yyyy` (07/2022) -- `mm-yyyy` (07-2022) -- `yyyy-mm` (2022-07) -- `Month yyyy` (July 2022) -- and so forth… - -One way around this is to put a [`pattern`](/en-US/docs/Web/HTML/Element/input#pattern) attribute on your `month` input. -Even though the `month` input doesn't use it, if the browser falls back to treating it like a `text` input, the pattern will be used. -For example, try viewing the following demo in a browser that doesn't support `month` inputs: - -```html -<form> - <div> - <label for="month"> - What month would you like to visit (June to Sept.)? - </label> - <input - id="month" - type="month" - name="month" - min="2022-06" - max="2022-09" - required - pattern="[0-9]{4}-[0-9]{2}" /> - <span class="validity"></span> - </div> - <div> - <input type="submit" value="Submit form" /> - </div> -</form> -``` - -{{ EmbedLiveSample('Handling_browser_support', 600, 100) }} - -If you try submitting it, you'll see that the browser now displays an error message (and highlights the input as invalid) if your entry doesn't match the pattern `nnnn-nn`, where `n` is a number from 0 to 9. -Of course, this doesn't stop people from entering invalid dates (such as `0000-42`), or incorrectly formatted dates that follow the pattern. - -There's also the problem that the user won't necessarily know which of the many date formats is expected. -We have work left to do. - -```css hidden -div { - margin-bottom: 10px; - position: relative; -} - -input[type="number"] { - width: 100px; -} - -input + span { - padding-right: 30px; -} - -input:invalid + span::after { - position: absolute; - content: "✖"; - padding-left: 5px; -} - -input:valid + span::after { - position: absolute; - content: "✓"; - padding-left: 5px; -} -``` - -The best way to deal with dates in forms in a cross-browser way (until all major browsers have supported them for a while) is to get the user to enter the month and year in separate controls ({{htmlelement("select")}} elements being popular; see below for an implementation), or use JavaScript libraries such as the [jQuery date picker](https://jqueryui.com/datepicker/) plugin. - -## Examples - -In this example, we create two sets of UI elements, each designed to let the user select a month and year. -The first is a native `month` input, and the other is a pair of {{HTMLElement("select")}} elements that allow choosing a month and year independently, for compatibility with browsers that don't yet support `<input type="month">`. - -{{EmbedLiveSample('Examples', 600, 140)}} - -### HTML - -The form that requests the month and year looks like this: - -```html -<form> - <div class="nativeDatePicker"> - <label for="month-visit">What month would you like to visit us?</label> - <input type="month" id="month-visit" name="month-visit" /> - <span class="validity"></span> - </div> - <p class="fallbackLabel">What month would you like to visit us?</p> - <div class="fallbackDatePicker"> - <div> - <span> - <label for="month">Month:</label> - <select id="month" name="month"> - <option selected>January</option> - <option>February</option> - <option>March</option> - <option>April</option> - <option>May</option> - <option>June</option> - <option>July</option> - <option>August</option> - <option>September</option> - <option>October</option> - <option>November</option> - <option>December</option> - </select> - </span> - <span> - <label for="year">Year:</label> - <select id="year" name="year"></select> - </span> - </div> - </div> -</form> -``` - -The {{HTMLElement("div")}} with the ID `nativeDatePicker` uses the `month` input type to request the month and year, while the `<div>` with the ID `fallbackDatePicker` instead uses a pair of `<select>` elements. -The first requests the month, and the second the year. - -The `<select>` for choosing the month is hardcoded with the names of the months, as they don't change (leaving localization out of things). -The list of available year values is dynamically generated depending on the current year (see the code comments below for detailed explanations of how these functions work). - -```css hidden -div { - margin-bottom: 10px; - position: relative; -} - -input[type="number"] { - width: 100px; -} - -input + span { - padding-right: 30px; -} - -input:invalid + span::after { - position: absolute; - content: "✖"; - padding-left: 5px; -} - -input:valid + span::after { - position: absolute; - content: "✓"; - padding-left: 5px; -} -``` - -### JavaScript - -The JavaScript code that handles selecting which approach to use and to set up the list of years to include in the non-native year `<select>` follows. - -The part of the example that may be of most interest is the feature detection code. -In order to detect whether the browser supports `<input type="month">`, we create a new {{htmlelement("input")}} element, try setting its `type` to `month`, then immediately check what its type is set to. -Browsers that don't support type `month` will return `text`, since that's What month falls back to when not supported. -If `<input type="month">` is not supported, we hide the native picker and show the fallback picker UI instead. - -```js -// Get UI elements -const nativePicker = document.querySelector(".nativeDatePicker"); -const fallbackPicker = document.querySelector(".fallbackDatePicker"); -const fallbackLabel = document.querySelector(".fallbackLabel"); - -const yearSelect = document.querySelector("#year"); -const monthSelect = document.querySelector("#month"); - -// Hide fallback initially -fallbackPicker.style.display = "none"; -fallbackLabel.style.display = "none"; - -// Test whether a new date input falls back to a text input or not -const test = document.createElement("input"); - -try { - test.type = "month"; -} catch (e) { - console.log(e.description); -} - -// If it does, run the code inside the if () {} block -if (test.type === "text") { - // Hide the native picker and show the fallback - nativePicker.style.display = "none"; - fallbackPicker.style.display = "block"; - fallbackLabel.style.display = "block"; - - // Populate the years dynamically - // (the months are always the same, therefore hardcoded) - populateYears(); -} - -function populateYears() { - // Get the current year as a number - const date = new Date(); - const year = date.getFullYear(); - - // Make this year, and the 100 years before it available in the year <select> - for (let i = 0; i <= 100; i++) { - const option = document.createElement("option"); - option.textContent = year - i; - yearSelect.appendChild(option); - } -} -``` - -> [!NOTE] -> Remember that some years have 53 weeks in them (see [Weeks per year](https://en.wikipedia.org/wiki/ISO_week_date#Weeks_per_year))! -> You'll need to take this into consideration when developing production apps. - -## Technical summary - -<table class="properties"> - <tbody> - <tr> - <td><strong><a href="#value">Value</a></strong></td> - <td> - A string representing a month and year, or - empty. - </td> - </tr> - <tr> - <td><strong>Events</strong></td> - <td> - {{domxref("HTMLElement/change_event", "change")}} and - {{domxref("Element/input_event", "input")}} - </td> - </tr> - <tr> - <td><strong>Supported common attributes</strong></td> - <td> - <a href="/en-US/docs/Web/HTML/Element/input#autocomplete"><code>autocomplete</code></a>, - <a href="/en-US/docs/Web/HTML/Element/input#list"><code>list</code></a>, - <a href="/en-US/docs/Web/HTML/Element/input#readonly"><code>readonly</code></a>, - <a href="/en-US/docs/Web/HTML/Element/input#step"><code>step</code></a> - </td> - </tr> - <tr> - <td><strong>IDL attributes</strong></td> - <td> - <a href="/en-US/docs/Web/HTML/Element/input#list"><code>list</code></a>, - <a href="/en-US/docs/Web/HTML/Element/input#value"><code>value</code></a>, - <code>valueAsDate</code>, - <code>valueAsNumber</code> - </td> - </tr> - <tr> - <td><strong>DOM interface</strong></td> - <td><p>{{domxref("HTMLInputElement")}}</p></td> - </tr> - <tr> - <td><strong>Methods</strong></td> - <td> - {{domxref("HTMLInputElement.select", "select()")}}, - {{domxref("HTMLInputElement.stepDown", "stepDown()")}}, - {{domxref("HTMLInputElement.stepUp", "stepUp()")}}. - </td> - </tr> - <tr> - <td><strong>Implicit ARIA Role</strong></td> - <td><a href="https://www.w3.org/TR/html-aria/#dfn-no-corresponding-role">no corresponding role</a></td> - </tr> - </tbody> -</table> - -## Specifications - -{{Specifications}} - -## Browser compatibility - -{{Compat}} - -## See also - -- The generic {{HTMLElement("input")}} element and the interface used to manipulate it, {{domxref("HTMLInputElement")}} -- [Date and time formats used in HTML](/en-US/docs/Web/HTML/Date_and_time_formats) -- [Date and Time picker tutorial](/en-US/docs/Learn_web_development/Extensions/Forms/HTML5_input_types#date_and_time_pickers) -- [`<input type="datetime-local">`](/en-US/docs/Web/HTML/Element/input/datetime-local), [`<input type="date">`](/en-US/docs/Web/HTML/Element/input/date), [`<input type="time">`](/en-US/docs/Web/HTML/Element/input/time), and [`<input type="week">`](/en-US/docs/Web/HTML/Element/input/week) diff --git a/files/en-us/web/html/element/input/number/index.md b/files/en-us/web/html/element/input/number/index.md deleted file mode 100644 index 02e1a9615b468f2..000000000000000 --- a/files/en-us/web/html/element/input/number/index.md +++ /dev/null @@ -1,495 +0,0 @@ ---- -title: <input type="number"> -slug: Web/HTML/Element/input/number -page-type: html-element -browser-compat: html.elements.input.type_number ---- - -{{HTMLSidebar}} - -{{HTMLElement("input")}} elements of type **`number`** are used to let the user enter a number. They include built-in validation to reject non-numerical entries. - -The browser may opt to provide stepper arrows to let the user increase and decrease the value using their mouse or by tapping with a fingertip. - -{{InteractiveExample("HTML Demo: &lt;input type=&quot;number&quot;&gt;", "tabbed-shorter")}} - -```html interactive-example -<label for="tentacles">Number of tentacles (10-100):</label> - -<input type="number" id="tentacles" name="tentacles" min="10" max="100" /> -``` - -```css interactive-example -label { - display: block; - font: - 1rem "Fira Sans", - sans-serif; -} - -input, -label { - margin: 0.4rem 0; -} -``` - -On browsers that don't support inputs of type `number`, a `number` input falls back to type `text`. - -## Value - -A number representing the value of the number entered into the input. You can set a default value for the input by including a number inside the [`value`](/en-US/docs/Web/HTML/Element/input#value) attribute, like so: - -```html -<input id="number" type="number" value="42" /> -``` - -{{EmbedLiveSample('Value', 600, 40)}} - -## Additional attributes - -In addition to the attributes commonly supported by all {{HTMLElement("input")}} types, inputs of type `number` support these attributes. - -### `list` - -The values of the list attribute is the {{domxref("Element.id", "id")}} of a {{HTMLElement("datalist")}} element located in the same document. The {{HTMLElement("datalist")}} provides a list of predefined values to suggest to the user for this input. Any values in the list that are not compatible with the [`type`](/en-US/docs/Web/HTML/Element/input#type) are not included in the suggested options. The values provided are suggestions, not requirements: users can select from this predefined list or provide a different value. - -### `max` - -The maximum value to accept for this input. If the [`value`](/en-US/docs/Web/HTML/Element/input#value) entered into the element exceeds this, the element fails [constraint validation](/en-US/docs/Web/HTML/Constraint_validation). If the value of the `max` attribute isn't a number, then the element has no maximum value. - -This value must be greater than or equal to the value of the `min` attribute. - -### `min` - -The minimum value to accept for this input. If the [`value`](/en-US/docs/Web/HTML/Element/input#value) of the element is less than this, the element fails [constraint validation](/en-US/docs/Web/HTML/Constraint_validation). If a value is specified for `min` that isn't a valid number, the input has no minimum value. - -This value must be less than or equal to the value of the `max` attribute. - -### `placeholder` - -The `placeholder` attribute is a string that provides a brief hint to the user as to what kind of information is expected in the field. It should be a word or short phrase that demonstrates the expected type of data, rather than an explanatory message. The text _must not_ include carriage returns or line feeds. - -If the control's content has one directionality ({{Glossary("LTR")}} or {{Glossary("RTL")}}) but needs to present the placeholder in the opposite directionality, you can use Unicode bidirectional algorithm formatting characters to override directionality within the placeholder; see [How to use Unicode controls for bidi text](https://www.w3.org/International/questions/qa-bidi-unicode-controls) for more information. - -> [!NOTE] -> Avoid using the `placeholder` attribute if you can. It is not as semantically useful as other ways to explain your form, and can cause unexpected technical issues with your content. See [`<input>` labels](/en-US/docs/Web/HTML/Element/input#labels) for more information. - -### `readonly` - -A Boolean attribute which, if present, means this field cannot be edited by the user. Its `value` can, however, still be changed by JavaScript code directly setting the {{domxref("HTMLInputElement")}} `value` property. - -> [!NOTE] -> Because a read-only field cannot have a value, `required` does not have any effect on inputs with the `readonly` attribute also specified. - -### `step` - -The `step` attribute is a number that specifies the granularity that the value must adhere to, or the special value `any`, which is described below. Only values which are equal to the basis for stepping ([`min`](#min) if specified, [`value`](/en-US/docs/Web/HTML/Element/input#value) otherwise, and an appropriate default value if neither of those is provided) are valid. - -A string value of `any` means that no stepping is implied, and any value is allowed (barring other constraints, such as [`min`](#min) and [`max`](#max)). - -> [!NOTE] -> When the data entered by the user doesn't adhere to the stepping configuration, the {{Glossary("user agent")}} may round to the nearest valid value, preferring numbers in the positive direction when there are two equally close options. - -The default stepping value for `number` inputs is `1`, allowing only integers to be entered—_unless_ the stepping base is not an integer. - -## Using number inputs - -The `number` input type should only be used for incremental numbers, especially when spinbutton incrementing and decrementing are helpful to user experience. The `number` input type is not appropriate for values that happen to only consist of numbers but aren't strictly speaking a number, such as postal codes in many countries or credit card numbers. For non-numeric inputs, consider using a different input type, such as [`<input type="tel">`](/en-US/docs/Web/HTML/Element/input/tel) or other {{HTMLElement('input')}} type with the [`inputmode`](/en-US/docs/Web/HTML/Global_attributes/inputmode) attribute: - -```html -<input type="text" inputmode="numeric" pattern="\d*" /> -``` - -`<input type="number">` elements can help simplify your work when building the user interface and logic for entering numbers into a form. When you create a number input with the proper `type` value, `number`, you get automatic validation that the entered text is a number, and usually a set of up and down buttons to step the value up and down. - -> [!WARNING] -> Logically, you should not be able to enter characters inside a number input other than numbers. Some browsers allow invalid characters, others do not; see [Firefox bug 1398528](https://bugzil.la/1398528). - -> [!NOTE] -> A user can tinker with your HTML behind the scenes, so your site _must not_ use client-side validation for security purposes. You _must_ verify on the server side any transaction in which the provided value may have security implications of any kind. - -Mobile browsers further help with the user experience by showing a special keyboard more suited for entering numbers when the user tries to enter a value. - -### A basic number input - -In its most basic form, a number input can be implemented like this: - -```html -<label for="ticketNum">Number of tickets you would like to buy:</label> -<input id="ticketNum" type="number" name="ticketNum" value="0" /> -``` - -{{EmbedLiveSample('A_basic_number_input', 600, 40)}} - -A number input is considered valid when empty and when a single number is entered, but is otherwise invalid. If the [`required`](/en-US/docs/Web/HTML/Element/input#required) attribute is used, the input is no longer considered valid when empty. - -> [!NOTE] -> Any number is an acceptable value, as long as it is a [valid floating point number](https://html.spec.whatwg.org/multipage/infrastructure.html#valid-floating-point-number) (that is, not [NaN](/en-US/docs/Web/JavaScript/Reference/Global_Objects/NaN) or [Infinity](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Infinity)). - -### Placeholders - -Sometimes it's helpful to offer an in-context hint as to what form the input data should take. This can be especially important if the page design doesn't offer descriptive labels for each {{HTMLElement("input")}}. This is where **placeholders** come in. A placeholder is a value most commonly used to provide a hint as to the format the input should take `value`. It is displayed inside the edit box when the element's `value` is `""`. Once data is entered into the box, the placeholder disappears; if the box is emptied, the placeholder reappears. - -Here, we have an `number` input with the placeholder "Multiple of 10". Note how the placeholder disappears and reappears as you manipulate the contents of the edit field. - -```html -<input type="number" placeholder="Multiple of 10" /> -``` - -{{EmbedLiveSample('Placeholders', 600, 40)}} - -### Controlling step size - -By default, the up and down buttons provided for you to step the number up and down will step the value up and down by 1. You can change this by providing a [`step`](/en-US/docs/Web/HTML/Element/input#step) attribute, which takes as its value a number specifying the step amount. Our above example contains a placeholder saying that the value should be a multiple of 10, so it makes sense to add a `step` value of `10`: - -```html -<input type="number" placeholder="multiple of 10" step="10" /> -``` - -{{EmbedLiveSample('Controlling_step_size', 600, 40)}} - -In this example, you should find that the up and down step arrows will increase and decrease the value by 10 each time, not 1. You can still manually enter a number that's not a multiple of 10, but it will be considered invalid. - -### Specifying minimum and maximum values - -You can use the [`min`](/en-US/docs/Web/HTML/Element/input#min) and [`max`](/en-US/docs/Web/HTML/Element/input#max) attributes to specify a minimum and maximum value that the field can have. For example, let's give our example a minimum of `0`, and a maximum of `100`: - -```html -<input type="number" placeholder="multiple of 10" step="10" min="0" max="100" /> -``` - -{{EmbedLiveSample('Specifying_minimum_and_maximum_values', 600, 40)}} - -In this updated version, you should find that the up and down step buttons will not allow you to go below 0 or above 100. You can still manually enter a number outside these bounds, but it will be considered invalid. - -### Allowing decimal values - -One issue with number inputs is that their step size is 1 by default. If you try to enter a number with a decimal (such as "1.0"), it will be considered invalid. If you want to enter a value that requires decimals, you'll need to reflect this in the `step` value (e.g. `step="0.01"` to allow decimals to two decimal places). Here's a basic example: - -```html -<input type="number" placeholder="1.0" step="0.01" min="0" max="10" /> -``` - -{{EmbedLiveSample("Allowing_decimal_values", 600, 40)}} - -See that this example allows any value between `0.0` and `10.0`, with decimals to two places. For example, "9.52" is valid, but "9.521" is not. - -If you want to allow arbitrary decimal values, you can set the `step` value to `"any"`. - -### Controlling input size - -{{HTMLElement("input")}} elements of type `number` don't support form sizing attributes such as [`size`](/en-US/docs/Web/HTML/Element/input#size). You'll have to resort to [CSS](/en-US/docs/Web/CSS) to change the size of these controls. - -For example, to adjust the width of the input to be only as wide as is needed to enter a three-digit number, we can change our HTML to include an [`id`](/en-US/docs/Web/HTML/Global_attributes/id) and to shorten our placeholder since the field will be too narrow for the text we have been using so far: - -```html -<input - type="number" - placeholder="x10" - step="10" - min="0" - max="100" - id="number" /> -``` - -Then we add some CSS to narrow the width of the element with the `id` selector `#number`: - -```css -#number { - width: 3em; -} -``` - -The result looks like this: - -{{EmbedLiveSample('Controlling_input_size', 600, 40)}} - -### Offering suggested values - -You can provide a list of default options from which the user can select by specifying the [`list`](/en-US/docs/Web/HTML/Element/input#list) attribute, which contains as its value the [`id`](/en-US/docs/Web/HTML/Global_attributes/id) of a {{HTMLElement("datalist")}}, which in turn contains one {{HTMLElement("option")}} element per suggested value. Each `option`'s `value` is the corresponding suggested value for the number entry box. - -```html -<input id="ticketNum" type="number" name="ticketNum" list="defaultNumbers" /> -<span class="validity"></span> - -<datalist id="defaultNumbers"> - <option value="10045678"></option> - <option value="103421"></option> - <option value="11111111"></option> - <option value="12345678"></option> - <option value="12999922"></option> -</datalist> -``` - -{{EmbedLiveSample("Offering_suggested_values", 600, 40)}} - -## Validation - -We have already mentioned a number of validation features of `number` inputs, but let's review them now: - -- `<input type="number">` elements automatically invalidate any entry that isn't a number (or empty, unless `required` is specified). -- You can use the [`required`](/en-US/docs/Web/HTML/Element/input#required) attribute to make an empty entry invalid. (In other words, the input _must_ be filled in.) -- You can use the [`step`](/en-US/docs/Web/HTML/Element/input#step) attribute to constrain valid values to a certain set of steps (e.g., multiples of 10). -- You can use the [`min`](/en-US/docs/Web/HTML/Element/input#min) and [`max`](/en-US/docs/Web/HTML/Element/input#max) attributes to constrain valid values to lower and upper bounds. - -The following example exhibits all of the above features, as well as using some CSS to display valid and invalid icons, depending on the `input`'s value: - -```html -<form> - <div> - <label for="balloons">Number of balloons to order (multiples of 10):</label> - <input - id="balloons" - type="number" - name="balloons" - step="10" - min="0" - max="100" - required /> - <span class="validity"></span> - </div> - <div> - <input type="submit" /> - </div> -</form> -``` - -{{EmbedLiveSample("Validation", 600, 110)}} - -Try submitting the form with different invalid values entered — e.g., no value; a value below 0 or above 100; a value that is not a multiple of 10; or a non-numerical value — and see how the error messages the browser gives you differ with different ones. - -The CSS applied to this example is as follows: - -```css -div { - margin-bottom: 10px; -} - -input:invalid + span::after { - content: "✖"; - padding-left: 5px; -} - -input:valid + span::after { - content: "✓"; - padding-left: 5px; -} -``` - -Here we use the {{cssxref(":invalid")}} and {{cssxref(":valid")}} pseudo classes to display an appropriate invalid or valid icon as generated content on the adjacent {{htmlelement("span")}} element, as a visual indicator of validity. - -We put it on a separate `<span>` element for added flexibility. Some browsers don't display generated content very effectively on some types of form inputs. (Read, for example, the section on [`<input type="date">` validation](/en-US/docs/Web/HTML/Element/input/date#validation).) - -> [!WARNING] -> HTML form validation is _not_ a substitute for server-side scripts that ensure that the entered data is in the proper format! -> -> It's far too easy for someone to make adjustments to the HTML that allow them to bypass the validation, or to remove it entirely. It's also possible for someone to bypass your HTML and submit the data directly to your server. -> -> If your server-side code fails to validate the data it receives, disaster could strike when improperly-formatted data is submitted (or data which is too large, is of the wrong type, and so forth). - -### Pattern validation - -`<input type="number">` elements do not support use of the [`pattern`](/en-US/docs/Web/HTML/Element/input#pattern) attribute for making entered values conform to a specific regex pattern. - -The rationale for this is that number inputs won't be valid if they contain anything except numbers, and you can constrain the minimum and maximum number of valid digits using the [`min`](/en-US/docs/Web/HTML/Element/input#min) and [`max`](/en-US/docs/Web/HTML/Element/input#max) attributes (as explained above). - -## Accessibility - -The implicit [role](/en-US/docs/Web/Accessibility/ARIA/Roles) for the `<input type="number">` element is [`spinbutton`](/en-US/docs/Web/Accessibility/ARIA/Roles/spinbutton_role). If spinbutton is not an important feature for your form control, consider _not_ using `type="number"`. Instead, use [`inputmode="numeric"`](/en-US/docs/Web/HTML/Global_attributes/inputmode) along with a [`pattern`](/en-US/docs/Web/HTML/Attributes/pattern) attribute that limits the characters to numbers and associated characters. With `<input type="number">`, there is a risk of users accidentally incrementing a number when they're trying to do something else. Additionally, if users try to enter something that's not a number, there's no explicit feedback about what they're doing wrong. - -Also consider using the [`autocomplete`](/en-US/docs/Web/HTML/Attributes/autocomplete) attribute to help users complete forms more quickly and with fewer chances of errors. For example, to enable autofill on a zip code field, set `autocomplete="postal-code"`. - -## Examples - -We've already covered the fact that by default, the increment is `1`, and you can use the [`step`](/en-US/docs/Web/HTML/Element/input#step) attribute to allow decimal inputs. Let's take a closer look. - -In the following example is a form for entering the user's height. It defaults to accepting a height in meters, but you can click the relevant button to change the form to accept feet and inches instead. The input for the height in meters accepts decimals to two places. - -{{EmbedLiveSample("Examples", 600, 150)}} - -The HTML looks like this: - -```html -<form> - <div class="metersInputGroup"> - <label for="meters">Enter your height — meters:</label> - <input - id="meters" - type="number" - name="meters" - step="0.01" - min="0" - placeholder="e.g. 1.78" - required /> - <span class="validity"></span> - </div> - <div class="feetInputGroup" style="display: none;"> - <span>Enter your height — </span> - <label for="feet">feet:</label> - <input id="feet" type="number" name="feet" min="0" step="1" /> - <span class="validity"></span> - <label for="inches">inches:</label> - <input id="inches" type="number" name="inches" min="0" max="11" step="1" /> - <span class="validity"></span> - </div> - <div> - <input - type="button" - class="meters" - value="Enter height in feet and inches" /> - </div> - <div> - <input type="submit" value="Submit form" /> - </div> -</form> -``` - -You'll see that we are using many of the attributes we've already looked at in the article earlier on. Since we want to accept a meter value in centimeters, we've set the `step` value to `0.01`, so that values like _1.78_ are not seen as invalid. We've also provided a placeholder for that input. - -We've hidden the feet and inches inputs initially using `style="display: none;"`, so that meters is the default entry type. - -Now, onto the CSS. This looks very similar to the validation styling we saw before; nothing remarkable here. - -```css -div { - margin-bottom: 10px; - position: relative; -} - -input[type="number"] { - width: 100px; -} - -input + span { - padding-right: 30px; -} - -input:invalid + span::after { - position: absolute; - content: "✖"; - padding-left: 5px; -} - -input:valid + span::after { - position: absolute; - content: "✓"; - padding-left: 5px; -} -``` - -And finally, the JavaScript: - -```js -const metersInputGroup = document.querySelector(".metersInputGroup"); -const feetInputGroup = document.querySelector(".feetInputGroup"); -const metersInput = document.querySelector("#meters"); -const feetInput = document.querySelector("#feet"); -const inchesInput = document.querySelector("#inches"); -const switchBtn = document.querySelector('input[type="button"]'); - -switchBtn.addEventListener("click", () => { - if (switchBtn.getAttribute("class") === "meters") { - switchBtn.setAttribute("class", "feet"); - switchBtn.value = "Enter height in meters"; - - metersInputGroup.style.display = "none"; - feetInputGroup.style.display = "block"; - - feetInput.setAttribute("required", ""); - inchesInput.setAttribute("required", ""); - metersInput.removeAttribute("required"); - - metersInput.value = ""; - } else { - switchBtn.setAttribute("class", "meters"); - switchBtn.value = "Enter height in feet and inches"; - - metersInputGroup.style.display = "block"; - feetInputGroup.style.display = "none"; - - feetInput.removeAttribute("required"); - inchesInput.removeAttribute("required"); - metersInput.setAttribute("required", ""); - - feetInput.value = ""; - inchesInput.value = ""; - } -}); -``` - -After declaring a few variables, an event listener is added to the `button` to control the switching mechanism. This involves changing over the button's `class` and {{HTMLElement("label")}}, and updating the display values of the two sets of inputs when the button is pressed. - -(Note that we're not converting back and forth between meters and feet/inches here, which a real-life web application would probably do.) - -> [!NOTE] -> When the user clicks the button, the `required` attribute(s) are removed from the input(s) we are hiding, and empty the `value` attribute(s). This is so the form can be submitted if both input sets aren't filled in. It also ensures that the form won't submit data that the user didn't mean to. -> -> If you didn't do this, you'd have to fill in both feet/inches **and** meters to submit the form! - -## Technical summary - -<table class="properties"> - <tbody> - <tr> - <td><strong><a href="#value">Value</a></strong></td> - <td>A {{jsxref("Number")}} representing a number, or empty</td> - </tr> - <tr> - <td><strong>Events</strong></td> - <td> - {{domxref("HTMLElement/change_event", "change")}} and - {{domxref("Element/input_event", "input")}} - </td> - </tr> - <tr> - <td><strong>Supported common attributes</strong></td> - <td> - <a href="/en-US/docs/Web/HTML/Element/input#autocomplete"><code>autocomplete</code></a>, - <a href="/en-US/docs/Web/HTML/Element/input#list"><code>list</code></a>, - <a href="/en-US/docs/Web/HTML/Element/input#placeholder"><code>placeholder</code></a>, - <a href="/en-US/docs/Web/HTML/Element/input#readonly"><code>readonly</code></a> - </td> - </tr> - <tr> - <td><strong>IDL attributes</strong></td> - <td> - <a href="/en-US/docs/Web/HTML/Element/input#list"><code>list</code></a>, - <a href="/en-US/docs/Web/HTML/Element/input#value"><code>value</code></a>, - <code>valueAsNumber</code> - </td> - </tr> - <tr> - <td><strong>DOM interface</strong></td> - <td><p>{{domxref("HTMLInputElement")}}</p></td> - </tr> - <tr> - <td><strong>Methods</strong></td> - <td> - {{domxref("HTMLInputElement.select", "select()")}}, - {{domxref("HTMLInputElement.stepUp", "stepUp()")}}, - {{domxref("HTMLInputElement.stepDown", "stepDown()")}} - </td> - </tr> - <tr> - <td><strong>Implicit ARIA Role</strong></td> - <td> - <code><a href="/en-US/docs/Web/Accessibility/ARIA/Roles/spinbutton_role">spinbutton</a></code> - </td> - </tr> - </tbody> -</table> - -## Specifications - -{{Specifications}} - -## Browser compatibility - -{{Compat}} - -## See also - -- [HTML forms guide](/en-US/docs/Learn_web_development/Extensions/Forms) -- {{HTMLElement("input")}} -- [`<input type="tel">`](/en-US/docs/Web/HTML/Element/input/tel) -- [Article: Why Gov.UK changed the input type for numbers](https://technology.blog.gov.uk/2020/02/24/why-the-gov-uk-design-system-team-changed-the-input-type-for-numbers/) diff --git a/files/en-us/web/html/element/input/password/index.md b/files/en-us/web/html/element/input/password/index.md deleted file mode 100644 index f355cacb66f71b7..000000000000000 --- a/files/en-us/web/html/element/input/password/index.md +++ /dev/null @@ -1,339 +0,0 @@ ---- -title: <input type="password"> -slug: Web/HTML/Element/input/password -page-type: html-element -browser-compat: html.elements.input.type_password ---- - -{{HTMLSidebar}} - -`<input>` elements of type **`password`** provide a way for the user to securely enter a password. - -The element is presented as a one-line plain text editor control in which the text is obscured so that it cannot be read, usually by replacing each character with a symbol such as the asterisk ("\*") or a dot ("•"). -This character will vary depending on the {{Glossary("user agent")}} and operating system. - -{{InteractiveExample("HTML Demo: &lt;input type=&quot;password&quot;&gt;", "tabbed-standard")}} - -```html interactive-example -<div> - <label for="username">Username:</label> - <input type="text" id="username" name="username" /> -</div> - -<div> - <label for="pass">Password (8 characters minimum):</label> - <input type="password" id="pass" name="password" minlength="8" required /> -</div> - -<input type="submit" value="Sign in" /> -``` - -```css interactive-example -label { - display: block; -} - -input[type="submit"], -label { - margin-top: 1rem; -} -``` - -The precise behavior of the entry process may vary from browser to browser. -Some browsers display the typed character for a moment before obscuring it, while others allow the user to toggle the display of plain-text on and off. -Both approaches help a user check that they entered the intended password, which can be particularly difficult on mobile devices. - -> [!NOTE] -> Any forms involving sensitive information like passwords (such as login forms) should be served over HTTPS. -> Many browsers now implement mechanisms to warn against insecure login forms; see [Insecure passwords](/en-US/docs/Web/Security/Insecure_passwords). - -## Value - -The [`value`](/en-US/docs/Web/HTML/Element/input#value) attribute contains a string whose value is the current contents of the text editing control being used to enter the password. If the user hasn't entered anything yet, this value is an empty string (`""`). If the [`required`](/en-US/docs/Web/HTML/Element/input#required) property is specified, then the password edit box must contain a value other than an empty string to be valid. - -If the [`pattern`](/en-US/docs/Web/HTML/Element/input#pattern) attribute is specified, the content of a `password` control is only considered valid if the value passes validation; see [Validation](#validation) for more information. - -> [!NOTE] -> The line feed (U+000A) and carriage return (U+000D) characters are not permitted in a `password` value. When setting the value of a password control, line feed and carriage return characters are stripped out of the value. - -## Additional attributes - -In addition to the [global attributes](/en-US/docs/Web/HTML/Global_attributes), and the attributes that operate on all {{HTMLElement("input")}} elements regardless of their type, password field inputs support the following attributes. - -> [!NOTE] -> The [`autocorrect`](/en-US/docs/Web/HTML/Global_attributes/autocorrect) global attribute can be added to password inputs, but the stored state is always `off`. - -### maxlength - -The maximum string length (measured in UTF-16 code units) that the user can enter into the password field. This must be an integer value of 0 or higher. If no `maxlength` is specified, or an invalid value is specified, the password field has no maximum length. This value must also be greater than or equal to the value of `minlength`. - -The input will fail [constraint validation](/en-US/docs/Web/HTML/Constraint_validation) if the length of the text entered into the field is greater than `maxlength` UTF-16 code units long. Constraint validation is only applied when the value is changed by the user. - -### minlength - -The minimum string length (measured in UTF-16 code units) that the user can enter into the password entry field. This must be a non-negative integer value smaller than or equal to the value specified by `maxlength`. If no `minlength` is specified, or an invalid value is specified, the password input has no minimum length. - -The input will fail [constraint validation](/en-US/docs/Web/HTML/Constraint_validation) if the length of the text entered into the field is fewer than `minlength` UTF-16 code units long. Constraint validation is only applied when the value is changed by the user. - -### pattern - -The `pattern` attribute, when specified, is a regular expression that the input's [`value`](/en-US/docs/Web/HTML/Element/input#value) must match for the value to pass [constraint validation](/en-US/docs/Web/HTML/Constraint_validation). It must be a valid JavaScript regular expression, as used by the {{jsxref("RegExp")}} type, and as documented in our [guide on regular expressions](/en-US/docs/Web/JavaScript/Guide/Regular_expressions); the `'u'` flag is specified when compiling the regular expression, so that the pattern is treated as a sequence of Unicode code points, instead of as {{Glossary("ASCII")}}. No forward slashes should be specified around the pattern text. - -If the specified pattern is not specified or is invalid, no regular expression is applied and this attribute is ignored completely. - -> [!NOTE] -> Use the [`title`](/en-US/docs/Web/HTML/Element/input#title) attribute to specify text that most browsers will display as a tooltip to explain what the requirements are to match the pattern. You should also include other explanatory text nearby. - -Use of a pattern is strongly recommended for password inputs, in order to help ensure that valid passwords using a wide assortment of character classes are selected and used by your users. With a pattern, you can mandate case rules, require the use of some number of digits and/or punctuation characters, and so forth. See the section [Validation](#validation) for details and an example. - -### placeholder - -The `placeholder` attribute is a string that provides a brief hint to the user as to what kind of information is expected in the field. It should be a word or short phrase that demonstrates the expected type of data, rather than an explanatory message. The text _must not_ include carriage returns or line feeds. - -If the control's content has one directionality ({{Glossary("LTR")}} or {{Glossary("RTL")}}) but needs to present the placeholder in the opposite directionality, you can use Unicode bidirectional algorithm formatting characters to override directionality within the placeholder; see [How to use Unicode controls for bidi text](https://www.w3.org/International/questions/qa-bidi-unicode-controls) for more information. - -> [!NOTE] -> Avoid using the `placeholder` attribute if you can. It is not as semantically useful as other ways to explain your form, and can cause unexpected technical issues with your content. See [`<input>` labels](/en-US/docs/Web/HTML/Element/input#labels) for more information. - -### readonly - -A Boolean attribute which, if present, means this field cannot be edited by the user. Its `value` can, however, still be changed from JavaScript code that directly sets the value of the {{domxref("HTMLInputElement","HTMLInputElement.value")}} property. - -> [!NOTE] -> Because a read-only field cannot have a value, `required` does not have any effect on inputs with the `readonly` attribute also specified. - -### size - -The `size` attribute is a numeric value indicating how many characters wide the input field should be. The value must be a number greater than zero, and the default value is 20. Since character widths vary, this may or may not be exact and should not be relied upon to be so; the resulting input may be narrower or wider than the specified number of characters, depending on the characters and the font ({{cssxref("font")}} settings in use). - -This does _not_ set a limit on how many characters the user can enter into the field. It only specifies approximately how many can be seen at a time. To set an upper limit on the length of the input data, use the [`maxlength`](#maxlength) attribute. - -## Using password inputs - -Password input boxes generally work just like other textual input boxes; the main difference is the obscuring of the content to prevent people near the user from reading the password. - -### A basic password input - -Here we see the most basic password input, with a label established using the {{HTMLElement("label")}} element. - -```html -<label for="userPassword">Password: </label> -<input id="userPassword" type="password" /> -``` - -{{EmbedLiveSample("A_basic_password_input", 600, 40)}} - -### Allowing autocomplete - -To allow the user's password manager to automatically enter the password, specify the [`autocomplete`](/en-US/docs/Web/HTML/Element/input#autocomplete) attribute. For passwords, this should typically be one of the following: - -- `on` - - : Allow the browser or a password manager to automatically fill out the password field. This isn't as informative as using either `current-password` or `new-password`. -- `off` - - : Don't allow the browser or password manager to automatically fill out the password field. Note that some software ignores this value, since it's typically harmful to users' ability to maintain safe password practices. -- `current-password` - - : Allow the browser or password manager to enter the current password for the site. This provides more information than `on` does, since it lets the browser or password manager automatically enter currently-known password for the site in the field, but not to suggest a new one. -- `new-password` - - : Allow the browser or password manager to automatically enter a new password for the site; this is used on "change your password" and "new user" forms, on the field asking the user for a new password. The new password may be generated in a variety of ways, depending on the password manager in use. It may fill in a new suggested password, or it might show the user an interface for creating one. - -```html -<label for="userPassword">Password:</label> -<input id="userPassword" type="password" autocomplete="current-password" /> -``` - -{{EmbedLiveSample("Allowing_autocomplete", 600, 40)}} - -### Making the password mandatory - -To tell the user's browser that the password field must have a valid value before the form can be submitted, specify the Boolean [`required`](/en-US/docs/Web/HTML/Element/input#required) attribute. - -```html -<label for="userPassword">Password: </label> -<input id="userPassword" type="password" required /> -<input type="submit" value="Submit" /> -``` - -{{EmbedLiveSample("Making_the_password_mandatory", 600, 40)}} - -### Specifying an input mode - -If your recommended (or required) password syntax rules would benefit from an alternate text entry interface than the standard keyboard, you can use the [`inputmode`](/en-US/docs/Web/HTML/Element/input#inputmode) attribute to request a specific one. The most obvious use case for this is if the password is required to be numeric (such as a PIN). Mobile devices with virtual keyboards, for example, may opt to switch to a numeric keypad layout instead of a full keyboard, to make entering the password easier. If the PIN is for one-time use, set the [`autocomplete`](/en-US/docs/Web/HTML/Element/input#autocomplete) attribute to either `off` or `one-time-code` to suggest that it's not saved. - -```html -<label for="pin">PIN: </label> -<input id="pin" type="password" inputmode="numeric" /> -``` - -{{EmbedLiveSample("Specifying_an_input_mode", 600, 40)}} - -### Setting length requirements - -As usual, you can use the [`minlength`](/en-US/docs/Web/HTML/Element/input#minlength) and [`maxlength`](/en-US/docs/Web/HTML/Element/input#maxlength) attributes to establish minimum and maximum acceptable lengths for the password. This example expands on the previous one by specifying that the user's PIN must be at least four and no more than eight digits. The [`size`](/en-US/docs/Web/HTML/Element/input#size) attribute is used to ensure that the password entry control is eight characters wide. - -```html -<label for="pin">PIN:</label> -<input - id="pin" - type="password" - inputmode="numeric" - minlength="4" - maxlength="8" - size="8" /> -``` - -{{EmbedLiveSample("Setting_length_requirements", 600, 40)}} - -### Selecting text - -As with other textual entry controls, you can use the {{domxref("HTMLInputElement.select", "select()")}} method to select all the text in the password field. - -#### HTML - -```html -<label for="userPassword">Password: </label> -<input id="userPassword" type="password" size="12" /> -<button id="selectAll">Select All</button> -``` - -#### JavaScript - -```js -document.getElementById("selectAll").onclick = () => { - document.getElementById("userPassword").select(); -}; -``` - -#### Result - -{{EmbedLiveSample("Selecting_text", 600, 40)}} - -You can also use {{domxref("HTMLInputElement.selectionStart", "selectionStart")}} and {{domxref("HTMLInputElement.selectionEnd", "selectionEnd")}} to get (or set) what range of characters in the control are currently selected, and {{domxref("HTMLInputElement.selectionDirection", "selectionDirection")}} to know which direction selection occurred in (or will be extended in, depending on your platform; see its documentation for an explanation). However, given that the text is obscured, the usefulness of these is somewhat limited. - -## Validation - -If your application has character set restrictions or any other requirement for the actual content of the entered password, you can use the [`pattern`](/en-US/docs/Web/HTML/Element/input#pattern) attribute to establish a regular expression to be used to automatically ensure that your passwords meet those requirements. - -In this example, only values consisting of at least four and no more than eight hexadecimal digits are valid. - -```html -<label for="hexId">Hex ID: </label> -<input - id="hexId" - type="password" - pattern="[0-9a-fA-F]{4,8}" - title="Enter an ID consisting of 4-8 hexadecimal digits" - autocomplete="new-password" /> -``` - -{{EmbedLiveSample("Validation", 600, 40)}} - -## Examples - -### Requesting a Social Security number - -This example only accepts input which matches the format for a [valid United States Social Security Number](https://en.wikipedia.org/wiki/Social_Security_number#Structure). These numbers, used for tax and identification purposes in the US, are in the form "123-45-6789". Assorted rules for what values are permitted in each group exist as well. - -#### HTML - -```html -<label for="ssn">SSN:</label> -<input - type="password" - id="ssn" - inputmode="numeric" - minlength="9" - maxlength="12" - pattern="(?!000)([0-6]\d{2}|7([0-6]\d|7[012]))([ -])?(?!00)\d\d\3(?!0000)\d{4}" - required - autocomplete="off" /> -<br /> -<label for="ssn">Value:</label> -<span id="current"></span> -``` - -This uses a [`pattern`](/en-US/docs/Web/HTML/Element/input#pattern) which limits the entered value to strings representing legal Social Security numbers. Obviously, this regexp doesn't guarantee a valid SSN (since we don't have access to the Social Security Administration's database), but it does ensure the number could be one; it generally avoids values that cannot be valid. In addition, it allows the three groups of digits to be separated by a space, a dash ("-"), or nothing. - -The [`inputmode`](/en-US/docs/Web/HTML/Element/input#inputmode) is set to `numeric` to encourage devices with virtual keyboards to switch to a numeric keypad layout for easier entry. The [`minlength`](/en-US/docs/Web/HTML/Element/input#minlength) and [`maxlength`](/en-US/docs/Web/HTML/Element/input#maxlength) attributes are set to 9 and 12, respectively, to require that the value be at least nine and no more than 12 characters (the former without separating characters between the groups of digits and the latter with them). The [`required`](/en-US/docs/Web/HTML/Element/input#required) attribute is used to indicate that this control must have a value. Finally, [`autocomplete`](/en-US/docs/Web/HTML/Element/input#autocomplete) is set to `off` to avoid password managers and session restore features trying to set its value, since this isn't a password at all. - -#### JavaScript - -The JavaScript displays the entered SSN onscreen so you can see it. This defeats the purpose of a password field, but it helps experiment with the `pattern`. - -```js -const ssn = document.getElementById("ssn"); -const current = document.getElementById("current"); - -ssn.oninput = (event) => { - current.textContent = ssn.value; -}; -``` - -#### Result - -{{EmbedLiveSample("Requesting_a_Social_Security_number", 600, 60)}} - -## Technical summary - -<table class="properties"> - <tbody> - <tr> - <td><strong><a href="#value">Value</a></strong></td> - <td> - A string representing a password, or empty - </td> - </tr> - <tr> - <td><strong>Events</strong></td> - <td> - {{domxref("HTMLElement/change_event", "change")}} and - {{domxref("Element/input_event", "input")}} - </td> - </tr> - <tr> - <td><strong>Supported Common Attributes</strong></td> - <td> - <a href="/en-US/docs/Web/HTML/Element/input#autocomplete"><code>autocomplete</code></a>, - <a href="/en-US/docs/Web/HTML/Element/input#inputmode"><code>inputmode</code></a>, - <a href="/en-US/docs/Web/HTML/Element/input#maxlength"><code>maxlength</code></a>, - <a href="/en-US/docs/Web/HTML/Element/input#minlength"><code>minlength</code></a>, - <a href="/en-US/docs/Web/HTML/Element/input#pattern"><code>pattern</code></a>, - <a href="/en-US/docs/Web/HTML/Element/input#placeholder"><code>placeholder</code></a>, - <a href="/en-US/docs/Web/HTML/Element/input#readonly"><code>readonly</code></a>, - <a href="/en-US/docs/Web/HTML/Element/input#required"><code>required</code></a>, and - <a href="/en-US/docs/Web/HTML/Element/input#size"><code>size</code></a> - </td> - </tr> - <tr> - <td><strong>IDL attributes</strong></td> - <td> - <code>selectionStart</code>, <code>selectionEnd</code>, - <code>selectionDirection</code>, and <code>value</code> - </td> - </tr> - <tr> - <td><strong>DOM interface</strong></td> - <td><p>{{domxref("HTMLInputElement")}}</p></td> - </tr> - <tr> - <td><strong>Methods</strong></td> - <td> - {{domxref("HTMLInputElement.select", "select()")}}, - {{domxref("HTMLInputElement.setRangeText", "setRangeText()")}}, - and - {{domxref("HTMLInputElement.setSelectionRange", "setSelectionRange()")}} - </td> - </tr> - <tr> - <td><strong>Implicit ARIA Role</strong></td> - <td><a href="https://www.w3.org/TR/html-aria/#dfn-no-corresponding-role">no corresponding role</a></td> - </tr> - </tbody> -</table> - -## Specifications - -{{Specifications}} - -## Browser compatibility - -{{Compat}} diff --git a/files/en-us/web/html/element/input/radio/index.md b/files/en-us/web/html/element/input/radio/index.md deleted file mode 100644 index f4b0723bb2428a2..000000000000000 --- a/files/en-us/web/html/element/input/radio/index.md +++ /dev/null @@ -1,380 +0,0 @@ ---- -title: <input type="radio"> -slug: Web/HTML/Element/input/radio -page-type: html-element -browser-compat: html.elements.input.type_radio ---- - -{{HTMLSidebar}} - -{{htmlelement("input")}} elements of type **`radio`** are generally used in **radio groups**—collections of radio buttons describing a set of related options. - -Only one radio button in a given group can be selected at the same time. Radio buttons are typically rendered as small circles, which are filled or highlighted when selected. - -{{InteractiveExample("HTML Demo: &lt;input type=&quot;radio&quot;&gt;", "tabbed-standard")}} - -```html interactive-example -<fieldset> - <legend>Select a maintenance drone:</legend> - - <div> - <input type="radio" id="huey" name="drone" value="huey" checked /> - <label for="huey">Huey</label> - </div> - - <div> - <input type="radio" id="dewey" name="drone" value="dewey" /> - <label for="dewey">Dewey</label> - </div> - - <div> - <input type="radio" id="louie" name="drone" value="louie" /> - <label for="louie">Louie</label> - </div> -</fieldset> -``` - -```css interactive-example -p, -label { - font: - 1rem "Fira Sans", - sans-serif; -} - -input { - margin: 0.4rem; -} -``` - -They are called radio buttons because they look and operate in a similar manner to the push buttons on old-fashioned radios, such as the one shown below. - -![Shows what radio buttons looked like in the olden days.](old-radio.jpg) - -> **Note:** [Checkboxes](/en-US/docs/Web/HTML/Element/input/checkbox) are similar to radio buttons, but with an important distinction: radio buttons are designed for selecting one value out of a set, whereas checkboxes let you turn individual values on and off. Where multiple controls exist, radio buttons allow one to be selected out of them all, whereas checkboxes allow multiple values to be selected. - -## Value - -The `value` attribute is a string containing the radio button's value. The value is never shown to the user by their {{Glossary("user agent")}}. Instead, it's used to identify which radio button in a group is selected. - -### Defining a radio group - -A radio group is defined by giving each of radio buttons in the group the same [`name`](/en-US/docs/Web/HTML/Element/input#name). Once a radio group is established, selecting any radio button in that group automatically deselects any currently-selected radio button in the same group. - -You can have as many radio groups on a page as you like, as long as each has its own unique `name`. - -For example, if your form needs to ask the user for their preferred contact method, you might create three radio buttons, each with the `name` property set to `contact` but one with the value `email`, one with the value `phone`, and one with the value `mail`. The user never sees the `value` or the `name` (unless you expressly add code to display it). - -The resulting HTML looks like this: - -```html -<form> - <fieldset> - <legend>Please select your preferred contact method:</legend> - <div> - <input type="radio" id="contactChoice1" name="contact" value="email" /> - <label for="contactChoice1">Email</label> - - <input type="radio" id="contactChoice2" name="contact" value="phone" /> - <label for="contactChoice2">Phone</label> - - <input type="radio" id="contactChoice3" name="contact" value="mail" /> - <label for="contactChoice3">Mail</label> - </div> - <div> - <button type="submit">Submit</button> - </div> - </fieldset> -</form> -``` - -Here you see the three radio buttons, each with the `name` set to `contact` and each with a unique `value` that uniquely identifies that individual radio button within the group. They each also have a unique {{domxref("Element.id", "id")}}, which is used by the {{HTMLElement("label")}} element's [`for`](/en-US/docs/Web/HTML/Element/label#for) attribute to associate the labels with the radio buttons. - -You can try out this example here: - -{{EmbedLiveSample('Defining_a_radio_group', 600, 130)}} - -### Data representation of a radio group - -When the above form is submitted with a radio button selected, the form's data includes an entry in the form `contact=value`. For example, if the user clicks on the "Phone" radio button then submits the form, the form's data will include the line `contact=phone`. - -If you omit the `value` attribute in the HTML, the submitted form data assigns the value `on` to the group. In this scenario, if the user clicked on the "Phone" option and submitted the form, the resulting form data would be `contact=on`, which isn't helpful. So don't forget to set your `value` attributes! - -> [!NOTE] -> If no radio button is selected when the form is submitted, the radio group is not included in the submitted form data at all, since there is no value to report. - -It's fairly uncommon to actually want to allow the form to be submitted without any of the radio buttons in a group selected, so it is usually wise to have one default to the `checked` state. See [Selecting a radio button by default](#selecting_a_radio_button_by_default) below. - -Let's add a bit of code to our example so we can examine the data generated by this form. The HTML is revised to add a {{HTMLElement("pre")}} block to output the form data into: - -```html -<form> - <fieldset> - <legend>Please select your preferred contact method:</legend> - <div> - <input type="radio" id="contactChoice1" name="contact" value="email" /> - <label for="contactChoice1">Email</label> - <input type="radio" id="contactChoice2" name="contact" value="phone" /> - <label for="contactChoice2">Phone</label> - <input type="radio" id="contactChoice3" name="contact" value="mail" /> - <label for="contactChoice3">Mail</label> - </div> - <div> - <button type="submit">Submit</button> - </div> - </fieldset> -</form> -<pre id="log"></pre> -``` - -Then we add some [JavaScript](/en-US/docs/Web/JavaScript) to set up an event listener on the {{domxref("HTMLFormElement/submit_event", "submit")}} event, which is sent when the user clicks the "Submit" button: - -```js -const form = document.querySelector("form"); -const log = document.querySelector("#log"); - -form.addEventListener( - "submit", - (event) => { - const data = new FormData(form); - let output = ""; - for (const entry of data) { - output = `${output}${entry[0]}=${entry[1]}\r`; - } - log.innerText = output; - event.preventDefault(); - }, - false, -); -``` - -Try this example out and see how there's never more than one result for the `contact` group. - -{{EmbedLiveSample("Data_representation_of_a_radio_group", 600, 130)}} - -## Additional attributes - -In addition to the common attributes shared by all {{HTMLElement("input")}} elements, `radio` inputs support the following attributes. - -- `checked` - - - : A Boolean attribute which, if present, indicates that this radio button is the default selected one in the group. - - Unlike other browsers, Firefox by default [persists the dynamic checked state](https://stackoverflow.com/questions/5985839/bug-with-firefox-disabled-attribute-of-input-not-resetting-when-refreshing) of an `<input>` across page loads. Use the [`autocomplete`](/en-US/docs/Web/HTML/Element/input#autocomplete) attribute to control this feature. - -- `value` - - - : The `value` attribute is one which all {{HTMLElement("input")}}s share; however, it serves a special purpose for inputs of type `radio`: when a form is submitted, only radio buttons which are currently checked are submitted to the server, and the reported value is the value of the `value` attribute. If the `value` is not otherwise specified, it is the string `on` by default. This is demonstrated in the section [Value](#value) above. - -- [`required`](/en-US/docs/Web/HTML/Attributes/required) - - : The `required` attribute is one which most {{HTMLElement("input")}}s share. If any radio button in a same-named group of radio buttons has the `required` attribute, a radio button in that group must be checked, although it doesn't have to be the one with the attribute applied. - -## Using radio inputs - -We already covered the fundamentals of radio buttons above. Let's now look at the other common radio-button-related features and techniques you may need to know about. - -### Selecting a radio button by default - -To make a radio button selected by default, you include `checked` attribute, as shown in this revised version of the previous example: - -```html -<form> - <fieldset> - <legend>Please select your preferred contact method:</legend> - <div> - <input - type="radio" - id="contactChoice1" - name="contact" - value="email" - checked /> - <label for="contactChoice1">Email</label> - - <input type="radio" id="contactChoice2" name="contact" value="phone" /> - <label for="contactChoice2">Phone</label> - - <input type="radio" id="contactChoice3" name="contact" value="mail" /> - <label for="contactChoice3">Mail</label> - </div> - <div> - <button type="submit">Submit</button> - </div> - </fieldset> -</form> -``` - -{{EmbedLiveSample('Selecting_a_radio_button_by_default', 600, 130)}} - -In this case, the first radio button is now selected by default. - -> [!NOTE] -> If you put the `checked` attribute on more than one radio button, later instances will override earlier ones; that is, the last `checked` radio button will be the one that is selected. This is because only one radio button in a group can ever be selected at once, and the user agent automatically deselects others each time a new one is marked as checked. - -### Providing a bigger hit area for your radio buttons - -In the above examples, you may have noticed that you can select a radio button by clicking on its associated {{htmlelement("label")}} element, as well as on the radio button itself. This is a really useful feature of HTML form labels that makes it easier for users to click the option they want, especially on small-screen devices like smartphones. - -Beyond accessibility, this is another good reason to properly set up `<label>` elements on your forms. - -## Validation - -In the case of a radio button with the [`required`](/en-US/docs/Web/HTML/Attributes/required) attribute set, or a same-named group of radio buttons in which at least one member has `required` set, a radio button needs to be selected for the control to be considered valid. If no radio button is checked, the [`valueMissing`](/en-US/docs/Web/API/ValidityState/valueMissing) property of a {{domxref("ValidityState")}} object will return `true` during validation, and the browser will ask the user to select an option. - -## Styling radio inputs - -The following example shows a slightly more thorough version of the example we've seen throughout the article, with some additional styling, and with better semantics established through use of specialized elements. The HTML looks like this: - -```html -<form> - <fieldset> - <legend>Please select your preferred contact method:</legend> - <div> - <input - type="radio" - id="contactChoice1" - name="contact" - value="email" - checked /> - <label for="contactChoice1">Email</label> - - <input type="radio" id="contactChoice2" name="contact" value="phone" /> - <label for="contactChoice2">Phone</label> - - <input type="radio" id="contactChoice3" name="contact" value="mail" /> - <label for="contactChoice3">Mail</label> - </div> - <div> - <button type="submit">Submit</button> - </div> - </fieldset> -</form> -``` - -The CSS involved in this example is a bit more significant: - -```css -html { - font-family: sans-serif; -} - -div:first-of-type { - display: flex; - align-items: flex-start; - margin-bottom: 5px; -} - -label { - margin-right: 15px; - line-height: 32px; -} - -input { - appearance: none; - - border-radius: 50%; - width: 16px; - height: 16px; - - border: 2px solid #999; - transition: 0.2s all linear; - margin-right: 5px; - - position: relative; - top: 4px; -} - -input:checked { - border: 6px solid black; -} - -button, -legend { - color: white; - background-color: black; - padding: 5px 10px; - border-radius: 0; - border: 0; - font-size: 14px; -} - -button:hover, -button:focus { - color: #999; -} - -button:active { - background-color: white; - color: black; - outline: 1px solid black; -} -``` - -Most notable here is the use of the {{cssxref("appearance")}} property (with prefixes needed to support some browsers). By default, radio buttons (and [checkboxes](/en-US/docs/Web/HTML/Element/input/checkbox)) are styled with the operating system's native styles for those controls. By specifying `appearance: none`, you can remove the native styling altogether, and create your own styles for them. Here we've used a {{cssxref("border")}} along with {{cssxref("border-radius")}} and a {{cssxref("transition")}} to create a nice animating radio selection. Notice also how the {{cssxref(":checked")}} pseudo-class is used to specify the styles for the radio button's appearance when selected. - -> [!NOTE] -> If you wish to use the {{cssxref("appearance")}} property, you should test it very carefully. Although it is supported in most modern browsers, its implementation varies widely. In older browsers, even the keyword `none` does not have the same effect across different browsers, and some do not support it at all. The differences are smaller in the newest browsers. - -{{EmbedLiveSample('Styling_radio_inputs', 600, 120)}} - -Notice that when clicking on a radio button, there's a nice, smooth fade out/in effect as the two buttons change state. In addition, the style and coloring of the legend and submit button are customized to have strong contrast. This might not be a look you'd want in a real web application, but it definitely shows off the possibilities. - -## Technical summary - -<table class="properties"> - <tbody> - <tr> - <td><strong><a href="#value">Value</a></strong></td> - <td> - A string representing the value of the radio - button. - </td> - </tr> - <tr> - <td><strong>Events</strong></td> - <td>{{domxref("HTMLElement/change_event", "change")}} and {{domxref("Element/input_event", "input")}}</td> - </tr> - <tr> - <td><strong>Supported common attributes</strong></td> - <td> - <code><a href="#checked">checked</a></code - >, <code><a href="#value">value</a></code> and - <code - ><a href="/en-US/docs/Web/HTML/Attributes/required">required</a></code - > - </td> - </tr> - <tr> - <td><strong>IDL attributes</strong></td> - <td><code>checked</code> and <code>value</code></td> - </tr> - <tr> - <td><strong>DOM interface</strong></td> - <td><p>{{domxref("HTMLInputElement")}}</p></td> - </tr> - <tr> - <td><strong>Methods</strong></td> - <td> - {{domxref("HTMLInputElement.select", "select()")}} - </td> - </tr> - <tr> - <td><strong>Implicit ARIA Role</strong></td> - <td> - <code><a href="/en-US/docs/Web/Accessibility/ARIA/Roles/radio_role">radio</a></code> - </td> - </tr> - </tbody> -</table> - -## Specifications - -{{Specifications}} - -## Browser compatibility - -{{Compat}} - -## See also - -- {{HTMLElement("input")}} and the {{domxref("HTMLInputElement")}} interface that implements it. -- {{domxref("RadioNodeList")}}: the interface that describes a list of radio buttons diff --git a/files/en-us/web/html/element/input/range/index.md b/files/en-us/web/html/element/input/range/index.md deleted file mode 100644 index 7b439ff0ba9cb2c..000000000000000 --- a/files/en-us/web/html/element/input/range/index.md +++ /dev/null @@ -1,384 +0,0 @@ ---- -title: <input type="range"> -slug: Web/HTML/Element/input/range -page-type: html-element -browser-compat: html.elements.input.type_range ---- - -{{HTMLSidebar}} - -{{HTMLElement("input")}} elements of type **`range`** let the user specify a numeric value which must be no less than a given value, and no more than another given value. The precise value, however, is not considered important. This is typically represented using a slider or dial control rather than a text entry box like the {{HTMLElement('input/number', 'number')}} input type. - -Because this kind of widget is imprecise, it should only be used if the control's exact value isn't important. - -{{InteractiveExample("HTML Demo: &lt;input type=&quot;range&quot;&gt;", "tabbed-standard")}} - -```html interactive-example -<p>Audio settings:</p> - -<div> - <input type="range" id="volume" name="volume" min="0" max="11" /> - <label for="volume">Volume</label> -</div> - -<div> - <input - type="range" - id="cowbell" - name="cowbell" - min="0" - max="100" - value="90" - step="10" /> - <label for="cowbell">Cowbell</label> -</div> -``` - -```css interactive-example -p, -label { - font: - 1rem "Fira Sans", - sans-serif; -} - -input { - margin: 0.4rem; -} -``` - -If the user's browser doesn't support type `range`, it will fall back and treat it as a `{{HTMLElement('input/text', 'text')}}` input. - -### Validation - -There is no pattern validation available; however, the following forms of automatic validation are performed: - -- If the [`value`](/en-US/docs/Web/HTML/Element/input#value) is set to something which can't be converted into a valid floating-point number, validation fails because the input is suffering from a bad input. -- The value won't be less than [`min`](/en-US/docs/Web/HTML/Element/input#min). The default is 0. -- The value won't be greater than [`max`](/en-US/docs/Web/HTML/Element/input#max). The default is 100. -- The value will be a multiple of [`step`](/en-US/docs/Web/HTML/Element/input#step). The default is 1. - -### Value - -The [`value`](/en-US/docs/Web/HTML/Element/input#value) attribute contains a string which contains a string representation of the selected number. The value is never an empty string (`""`). The default value is halfway between the specified minimum and maximum—unless the maximum is actually less than the minimum, in which case the default is set to the value of the `min` attribute. The algorithm for determining the default value is: - -```js -defaultValue = - rangeElem.max < rangeElem.min - ? rangeElem.min - : rangeElem.min + (rangeElem.max - rangeElem.min) / 2; -``` - -If an attempt is made to set the value lower than the minimum, it is set to the minimum. Similarly, an attempt to set the value higher than the maximum results in it being set to the maximum. - -## Additional attributes - -In addition to the attributes shared by all {{HTMLElement("input")}} elements, range inputs offer the following attributes. - -> [!NOTE] -> The following input attributes do not apply to the input range: `accept`, `alt`, `checked`, `dirname`, `formaction`, `formenctype`, `formmethod`, `formnovalidate`, `formtarget`, `height`, `maxlength`, `minlength`, `multiple`, `pattern`, `placeholder`, `readonly`, `required`, `size`, and `src`. Any of these attributes, if included, will be ignored. - -### list - -The value of the `list` attribute is the {{domxref("Element.id", "id")}} of a {{HTMLElement("datalist")}} element located in the same document. The {{HTMLElement("datalist")}} provides a list of predefined values to suggest to the user for this input. Any values in the list that are not compatible with the [`type`](/en-US/docs/Web/HTML/Element/input#type) are not included in the suggested options. The values provided are suggestions, not requirements: users can select from this predefined list or provide a different value. - -See the [adding tick marks](#adding_tick_marks) below for an example of how the options on a range are denoted in supported browsers. - -### max - -The greatest value in the range of permitted values. If the [`value`](/en-US/docs/Web/HTML/Element/input#value) entered into the element exceeds this, the element fails [constraint validation](/en-US/docs/Web/HTML/Constraint_validation). If the value of the [`max`](/en-US/docs/Web/HTML/Attributes/max) attribute isn't a number, then the element has no maximum value. - -This value must be greater than or equal to the value of the [`min`](/en-US/docs/Web/HTML/Attributes/min) attribute. See the HTML [`max`](/en-US/docs/Web/HTML/Attributes/max) attribute. - -### min - -The lowest value in the range of permitted values. If the [`value`](/en-US/docs/Web/HTML/Element/input#value) of the element is less than this, the element fails [constraint validation](/en-US/docs/Web/HTML/Constraint_validation). If a value is specified for `min` that isn't a valid number, the input has no minimum value. - -This value must be less than or equal to the value of the [`max`](/en-US/docs/Web/HTML/Attributes/max) attribute. See the HTML [`min`](/en-US/docs/Web/HTML/Attributes/min) attribute. - -> [!NOTE] -> If the `min` and `max` values are equal or the `max` value is lower than the `min` value the user will not be able to interact with the range. - -### step - -The `step` attribute is a number that specifies the granularity that the value must adhere to. Only values that match the specified stepping interval ([`min`](#min) if specified, [`value`](/en-US/docs/Web/HTML/Element/input#value) otherwise, or an appropriate default value if neither of those is provided) are valid. - -The `step` attribute can also be set to the `any` string value. This `step` value means that no stepping interval is implied and any value is allowed in the specified range (barring other constraints, such as [`min`](#min) and [`max`](#max)). See the [Setting step to the `any` value](#setting_step_to_any) example for how this works in supported browsers. - -> [!NOTE] -> When the value entered by a user doesn't adhere to the stepping configuration, the {{Glossary("user agent")}} may round off the value to the nearest valid value, preferring to round numbers up when there are two equally close options. - -The default stepping value for `range` inputs is 1, allowing only integers to be entered, _unless_ the stepping base is not an integer; for example, if you set `min` to -10 and `value` to 1.5, then a `step` of 1 will allow only values such as 1.5, 2.5, 3.5,… in the positive direction and -0.5, -1.5, -2.5,… in the negative direction. See the [HTML `step` attribute](/en-US/docs/Web/HTML/Attributes/step). - -## Non-standard attributes - -### orient - -Similar to the -moz-orient non-standard CSS property impacting the {{htmlelement('progress')}} and {{htmlelement('meter')}} elements, the `orient` attribute defines the orientation of the range slider. Values include `horizontal`, meaning the range is rendered horizontally, and `vertical`, where the range is rendered vertically. - -## Examples - -While the `number` type lets users enter a number with optional constraints forcing their value to be between a minimum and a maximum value, it does require that they enter a specific value. The `range` input type lets you ask the user for a value in cases where the user may not even care—or know—what the specific numeric value selected is. - -A few examples of situations in which range inputs are commonly used: - -- Audio controls such as volume and balance, or filter controls. -- Color configuration controls such as color channels, transparency, brightness, etc. -- Game configuration controls such as difficulty, visibility distance, world size, and so forth. -- Password length for a password manager's generated passwords. - -As a rule, if the user is more likely to be interested in the percentage of the distance between minimum and maximum values than the actual number itself, a range input is a great candidate. For example, in the case of a home stereo volume control, users typically think "set volume at halfway to maximum" instead of "set volume to 0.5". - -### Specifying the minimum and maximum - -By default, the minimum is 0 and the maximum is 100. If that's not what you want, you can easily specify different bounds by changing the values of the [`min`](/en-US/docs/Web/HTML/Element/input#min) and/or [`max`](/en-US/docs/Web/HTML/Element/input#max) attributes. These can be any floating-point value. - -For example, to ask the user for a value between -10 and 10, you can use: - -```html -<input type="range" min="-10" max="10" /> -``` - -{{EmbedLiveSample("Specifying_the_minimum_and_maximum", 600, 40)}} - -### Setting the value's granularity - -By default, the granularity is 1, meaning the value is always an integer. To control the granularity, you can change the [`step`](/en-US/docs/Web/HTML/Element/input#step) attribute. For example, If you need a value to be halfway between 5 and 10, you should set the value of `step` to 0.5: - -#### Setting the step attribute - -```html -<input type="range" min="5" max="10" step="0.5" /> -``` - -{{EmbedLiveSample("Setting_the_step_attribute", 600, 40)}} - -#### Setting step to `any` - -If you want to accept any value regardless of how many decimal places it extends to, you can specify a value of `any` for the [`step`](/en-US/docs/Web/HTML/Element/input#step) attribute: - -##### HTML - -```html -<input id="pi_input" type="range" min="0" max="3.14" step="any" /> -<p>Value: <output id="value"></output></p> -``` - -##### JavaScript - -```js -const value = document.querySelector("#value"); -const input = document.querySelector("#pi_input"); -value.textContent = input.value; -input.addEventListener("input", (event) => { - value.textContent = event.target.value; -}); -``` - -{{EmbedLiveSample("Setting_step_to_any", 600, 75)}} - -This example lets the user select any value between 0 and π without any restriction on the fractional part of the value selected. JavaScript is used to show how the value changes as the user interacts with the range. - -### Adding tick marks - -To add tick marks to a range control, include the `list` attribute, giving it the `id` of a {{HTMLElement("datalist")}} element which defines a series of tick marks on the control. Each point is represented using an {{HTMLElement("option")}} element with its [`value`](/en-US/docs/Web/HTML/Element/option#value) set to the range's value at which a mark should be drawn. - -#### HTML - -```html -<label for="temp">Choose a comfortable temperature:</label><br /> -<input type="range" id="temp" name="temp" list="markers" /> - -<datalist id="markers"> - <option value="0"></option> - <option value="25"></option> - <option value="50"></option> - <option value="75"></option> - <option value="100"></option> -</datalist> -``` - -#### Result - -{{EmbedLiveSample("Adding tick marks", 600, 50)}} - -### Using the same datalist for multiple range controls - -To help you from repeating code you can reuse that same {{HTMLElement("datalist")}} for multiple `<input type="range">` elements, and other {{HTMLElement("input")}} types. - -> [!NOTE] -> If you also want to [show the labels](#adding_labels) as in the example below then you would need a `datalist` for each range input. - -#### HTML - -```html -<p> - <label for="temp1">Temperature for room 1:</label> - <input type="range" id="temp1" name="temp1" list="values" /> -</p> -<p> - <label for="temp2">Temperature for room 2:</label> - <input type="range" id="temp2" name="temp2" list="values" /> -</p> - -<p> - <label for="temp3">Temperature for room 3:</label> - <input type="range" id="temp3" name="temp3" list="values" /> -</p> - -<datalist id="values"> - <option value="0" label="0"></option> - <option value="25" label="25"></option> - <option value="50" label="50"></option> - <option value="75" label="75"></option> - <option value="100" label="100"></option> -</datalist> -``` - -#### Result - -{{EmbedLiveSample("Using the same datalist for multiple range controls")}} - -### Adding labels - -You can label tick marks by giving the `<option>` elements `label` attributes. However, the label content will not be displayed by default. You can use CSS to show the labels and to position them correctly. Here's one way you could do this. - -#### HTML - -```html -<label for="tempB">Choose a comfortable temperature:</label><br /> -<input type="range" id="tempB" name="temp" list="values" /> - -<datalist id="values"> - <option value="0" label="very cold!"></option> - <option value="25" label="cool"></option> - <option value="50" label="medium"></option> - <option value="75" label="getting warm!"></option> - <option value="100" label="hot!"></option> -</datalist> -``` - -#### CSS - -```css -datalist { - display: flex; - flex-direction: column; - justify-content: space-between; - writing-mode: vertical-lr; - width: 200px; -} - -option { - padding: 0; -} - -input[type="range"] { - width: 200px; - margin: 0; -} -``` - -#### Result - -{{EmbedLiveSample("Adding labels")}} - -### Creating vertical range controls - -By default, browsers render range inputs as sliders with the knob sliding left and right. - -To create a vertical range wherein the thumb slides up and down, set the {{cssxref("writing-mode")}} property with a value of either `vertical-rl` or `vertical-lr`: - -```html hidden -<input type="range" min="0" max="10" value="8" /> -``` - -```css -input[type="range"] { - writing-mode: vertical-lr; -} -``` - -This causes the range slider to render vertically: - -{{EmbedLiveSample("Creating vertical range controls", 200, 200)}} - -You can also set the CSS {{cssxref('appearance')}} property to the non-standard `slider-vertical` value if you want to support older versions of Chrome and Safari, and include the non-standard `orient="vertical"` attribute to support older versions of Firefox. - -See [Creating vertical form controls](/en-US/docs/Web/CSS/CSS_writing_modes/Vertical_controls) for examples. - -## Technical summary - -<table class="properties"> - <tbody> - <tr> - <td><strong><a href="#value">Value</a></strong></td> - <td> - A string containing the string representation - of the selected numeric value; use - {{domxref("HTMLInputElement.valueAsNumber", "valueAsNumber")}} - to get the value as a number. - </td> - </tr> - <tr> - <td><strong>Events</strong></td> - <td> - {{domxref("HTMLElement/change_event", "change")}} and - {{domxref("Element/input_event", "input")}} - </td> - </tr> - <tr> - <td><strong>Supported common attributes</strong></td> - <td> - <a href="/en-US/docs/Web/HTML/Element/input#autocomplete"><code>autocomplete</code></a>, - <a href="/en-US/docs/Web/HTML/Element/input#list"><code>list</code></a>, - <a href="/en-US/docs/Web/HTML/Element/input#max"><code>max</code></a>, - <a href="/en-US/docs/Web/HTML/Element/input#min"><code>min</code></a>, - <a href="/en-US/docs/Web/HTML/Element/input#step"><code>step</code></a> - </td> - </tr> - <tr> - <td><strong>IDL attributes</strong></td> - <td> - <a href="/en-US/docs/Web/HTML/Element/input#list"><code>list</code></a>, - <a href="/en-US/docs/Web/HTML/Element/input#value"><code>value</code></a>, - <code>valueAsNumber</code> - </td> - </tr> - <tr> - <td><strong>DOM interface</strong></td> - <td><p>{{domxref("HTMLInputElement")}}</p></td> - </tr> - <tr> - <td><strong>Methods</strong></td> - <td> - {{domxref("HTMLInputElement.stepDown", "stepDown()")}} - and {{domxref("HTMLInputElement.stepUp", "stepUp()")}} - </td> - </tr> - <tr> - <td><strong>Implicit ARIA Role</strong></td> - <td> - <code><a href="/en-US/docs/Web/Accessibility/ARIA/Roles/slider_role">slider</a></code> - </td> - </tr> - </tbody> -</table> - -## Specifications - -{{Specifications}} - -## Browser compatibility - -{{Compat}} - -## See also - -- [HTML Forms](/en-US/docs/Learn_web_development/Extensions/Forms) -- {{HTMLElement("input")}} and the {{domxref("HTMLInputElement")}} interface it's based upon -- [`<input type="number">`](/en-US/docs/Web/HTML/Element/input/number) -- {{domxref('validityState.rangeOverflow')}} and {{domxref('validityState.rangeUnderflow')}} -- [Controlling multiple parameters with ConstantSourceNode](/en-US/docs/Web/API/Web_Audio_API/Controlling_multiple_parameters_with_ConstantSourceNode) -- [Creating vertical form controls](/en-US/docs/Web/CSS/CSS_writing_modes/Vertical_controls) -- [Styling the range element](https://css-tricks.com/sliding-nightmare-understanding-range-input/) diff --git a/files/en-us/web/html/element/input/reset/index.md b/files/en-us/web/html/element/input/reset/index.md deleted file mode 100644 index c4ed2e47add5686..000000000000000 --- a/files/en-us/web/html/element/input/reset/index.md +++ /dev/null @@ -1,202 +0,0 @@ ---- -title: <input type="reset"> -slug: Web/HTML/Element/input/reset -page-type: html-element -browser-compat: html.elements.input.type_reset ---- - -{{HTMLSidebar}} - -{{HTMLElement("input")}} elements of type **`reset`** are rendered as buttons, with a default {{domxref("Element/click_event", "click")}} event handler that resets all inputs in the form to their initial values. - -{{InteractiveExample("HTML Demo: &lt;input type=&quot;reset&quot;&gt;", "tabbed-standard")}} - -```html interactive-example -<form> - <div class="controls"> - <label for="id">User ID:</label> - <input type="text" id="id" name="id" /> - - <input type="reset" value="Reset" /> - <input type="submit" value="Submit" /> - </div> -</form> -``` - -```css interactive-example -.controls { - padding-top: 1rem; - display: grid; - grid-template-rows: repeat(3, 1fr); - grid-template-columns: 1fr 2fr; - gap: 0.7rem; -} - -label { - font-size: 0.8rem; - justify-self: end; -} - -input[type="reset"], -input[type="submit"] { - width: 5rem; - justify-self: end; -} - -input[type="reset"] { - grid-column: 2; - grid-row: 2; -} - -input[type="submit"] { - grid-column: 2; - grid-row: 3; -} -``` - -> [!NOTE] -> You should usually avoid including reset buttons in your forms. They're rarely useful, and are instead more likely to frustrate users who click them by mistake (often while trying to click the [submit button](/en-US/docs/Web/HTML/Element/input/submit)). - -## Value - -An `<input type="reset">` element's [`value`](/en-US/docs/Web/HTML/Element/input#value) attribute contains a string that is used as the button's label providing the button with an {{glossary("accessible description")}}. Buttons such as `reset` don't have a value otherwise. - -### Setting the value attribute - -```html -<input type="reset" value="Reset the form" /> -``` - -{{EmbedLiveSample("Setting_the_value_attribute", 650, 30)}} - -### Omitting the value attribute - -If you don't specify a `value`, you get a button with the default label (typically "Reset," but this will vary depending on the {{Glossary("user agent")}}): - -```html -<input type="reset" /> -``` - -{{EmbedLiveSample("Omitting_the_value_attribute", 650, 30)}} - -## Using reset buttons - -`<input type="reset">` buttons are used to reset forms. If you want to create a custom button and then customize the behavior using JavaScript, you need to use [`<input type="button">`](/en-US/docs/Web/HTML/Element/input/button), or better still, a {{htmlelement("button")}} element. - -### A basic reset button - -We'll begin by creating a basic reset button: - -```html -<form> - <div> - <label for="example">Type in some sample text</label> - <input id="example" type="text" /> - </div> - <div> - <input type="reset" value="Reset the form" /> - </div> -</form> -``` - -This renders like so: - -{{EmbedLiveSample("A_basic_reset_button", 650, 100)}} - -Try entering some text into the text field, and then pressing the reset button. - -### Adding a reset keyboard shortcut - -To add a keyboard shortcut to a reset button — just as you would with any {{HTMLElement("input")}} for which it makes sense — you use the [`accesskey`](/en-US/docs/Web/HTML/Global_attributes/accesskey) global attribute. - -In this example, <kbd>r</kbd> is specified as the access key (you'll need to press <kbd>r</kbd> plus the particular modifier keys for your browser/OS combination; see [`accesskey`](/en-US/docs/Web/HTML/Global_attributes/accesskey) for a useful list of those). - -```html -<form> - <div> - <label for="example">Type in some sample text</label> - <input id="example" type="text" /> - </div> - <div> - <input type="reset" value="Reset the form" accesskey="r" /> - </div> -</form> -``` - -{{EmbedLiveSample("Adding_a_reset_keyboard_shortcut", 650, 100)}} - -The problem with the above example is that there's no way for the user to know what the access key is! This is especially true since the modifiers are typically non-standard to avoid conflicts. When building a site, be sure to provide this information in a way that doesn't interfere with the site design (for example by providing an easily accessible link that points to information on what the site access keys are). Adding a tooltip to the button (using the [`title`](/en-US/docs/Web/HTML/Global_attributes/title) attribute) can also help, although it's not a complete solution for accessibility purposes. - -### Disabling and enabling a reset button - -To disable a reset button, specify the [`disabled`](/en-US/docs/Web/HTML/Element/input#disabled) attribute on it, like so: - -```html -<input type="reset" value="Disabled" disabled /> -``` - -You can enable and disable buttons at run time by setting `disabled` to `true` or `false`; in JavaScript this looks like `btn.disabled = true` or `btn.disabled = false`. - -> [!NOTE] -> See the [`<input type="button">`](/en-US/docs/Web/HTML/Element/input/button#disabling_and_enabling_a_button) page for more ideas about enabling and disabling buttons. - -## Validation - -Buttons don't participate in constraint validation; they have no real value to be constrained. - -## Examples - -We've included basic examples above. There isn't really anything more to say about reset buttons. - -## Technical summary - -<table class="properties"> - <tbody> - <tr> - <td><strong><a href="#value">Value</a></strong></td> - <td>A string used as the button's label</td> - </tr> - <tr> - <td><strong>Events</strong></td> - <td>{{domxref("Element/click_event", "click")}}</td> - </tr> - <tr> - <td><strong>Supported common attributes</strong></td> - <td> - <a href="/en-US/docs/Web/HTML/Element/input#type"><code>type</code></a> and - <a href="/en-US/docs/Web/HTML/Element/input#value"><code>value</code></a> - </td> - </tr> - <tr> - <td><strong>IDL attributes</strong></td> - <td><code>value</code></td> - </tr> - <tr> - <td><strong>DOM interface</strong></td> - <td><p>{{domxref("HTMLInputElement")}}</p></td> - </tr> - <tr> - <td><strong>Methods</strong></td> - <td>None</td> - </tr> - <tr> - <td><strong>Implicit ARIA Role</strong></td> - <td><a href="/en-US/docs/Web/Accessibility/ARIA/Roles/button_role"><code>button</code></a></td> - </tr> - </tbody> -</table> - -## Specifications - -{{Specifications}} - -## Browser compatibility - -{{Compat}} - -## See also - -- {{HTMLElement("input")}} and the {{domxref("HTMLInputElement")}} interface which implements it. -- [Forms and buttons](/en-US/docs/Learn_web_development/Extensions/Forms/Basic_native_form_controls#actual_buttons) -- [HTML forms](/en-US/docs/Learn_web_development/Extensions/Forms) -- The {{HTMLElement("button")}} element diff --git a/files/en-us/web/html/element/input/search/index.md b/files/en-us/web/html/element/input/search/index.md deleted file mode 100644 index 71dd158a405658f..000000000000000 --- a/files/en-us/web/html/element/input/search/index.md +++ /dev/null @@ -1,485 +0,0 @@ ---- -title: <input type="search"> -slug: Web/HTML/Element/input/search -page-type: html-element -browser-compat: html.elements.input.type_search ---- - -{{HTMLSidebar}} - -{{HTMLElement("input")}} elements of type **`search`** are text fields designed for the user to enter search queries into. These are functionally identical to [`text`](/en-US/docs/Web/HTML/Element/input/text) inputs, but may be styled differently by the {{Glossary("user agent")}}. - -{{InteractiveExample("HTML Demo: &lt;input type=&quot;search&quot;&gt;", "tabbed-standard")}} - -```html interactive-example -<label for="site-search">Search the site:</label> -<input type="search" id="site-search" name="q" /> - -<button>Search</button> -``` - -```css interactive-example -label { - display: block; - font: - 1rem "Fira Sans", - sans-serif; -} - -input, -label { - margin: 0.4rem 0; -} -``` - -## Value - -The [`value`](/en-US/docs/Web/HTML/Element/input#value) attribute contains a string representing the value contained in the search field. You can retrieve this using the [`HTMLInputElement.value`](/en-US/docs/Web/API/HTMLInputElement#value) property in JavaScript. - -```js -searchTerms = mySearch.value; -``` - -If no validation constraints are in place for the input (see [Validation](#validation) for more details), the value can be any text string or an empty string (`""`). - -## Additional attributes - -In addition to the [global attributes](/en-US/docs/Web/HTML/Global_attributes) and the attributes that operate on all {{HTMLElement("input")}} elements regardless of their type, search field inputs support the following attributes. - -### list - -The values of the list attribute is the {{domxref("Element.id", "id")}} of a {{HTMLElement("datalist")}} element located in the same document. The {{HTMLElement("datalist")}} provides a list of predefined values to suggest to the user for this input. Any values in the list that are not compatible with the [`type`](/en-US/docs/Web/HTML/Element/input#type) are not included in the suggested options. The values provided are suggestions, not requirements: users can select from this predefined list or provide a different value. - -### maxlength - -The maximum string length (measured in UTF-16 code units) that the user can enter into the search field. This must be an integer value of 0 or higher. If no `maxlength` is specified, or an invalid value is specified, the search field has no maximum length. This value must also be greater than or equal to the value of `minlength`. - -The input will fail [constraint validation](/en-US/docs/Web/HTML/Constraint_validation) if the length of the text entered into the field is greater than `maxlength` UTF-16 code units long. Constraint validation is only applied when the value is changed by the user. - -### minlength - -The minimum string length (measured in UTF-16 code units) that the user can enter into the search field. This must be a non-negative integer value smaller than or equal to the value specified by `maxlength`. If no `minlength` is specified, or an invalid value is specified, the search input has no minimum length. - -The search field will fail [constraint validation](/en-US/docs/Web/HTML/Constraint_validation) if the length of the text entered into the field is fewer than `minlength` UTF-16 code units long. Constraint validation is only applied when the value is changed by the user. - -### pattern - -The `pattern` attribute, when specified, is a regular expression that the input's [`value`](/en-US/docs/Web/HTML/Element/input#value) must match for the value to pass [constraint validation](/en-US/docs/Web/HTML/Constraint_validation). It must be a valid JavaScript regular expression, as used by the {{jsxref("RegExp")}} type, and as documented in our [guide on regular expressions](/en-US/docs/Web/JavaScript/Guide/Regular_expressions); the `'u'` flag is specified when compiling the regular expression so that the pattern is treated as a sequence of Unicode code points, instead of as {{Glossary("ASCII")}}. No forward slashes should be specified around the pattern text. - -If the specified pattern is not specified or is invalid, no regular expression is applied and this attribute is ignored completely. - -> [!NOTE] -> Use the [`title`](/en-US/docs/Web/HTML/Element/input#title) attribute to specify text that most browsers will display as a tooltip to explain what the requirements are to match the pattern. You should also include other explanatory text nearby. - -See the section [Specifying a pattern](#specifying_a_pattern) for details and an example. - -### placeholder - -The `placeholder` attribute is a string that provides a brief hint to the user as to what kind of information is expected in the field. It should be a word or short phrase that demonstrates the expected type of data, rather than an explanatory message. The text _must not_ include carriage returns or line feeds. - -If the control's content has one directionality ({{Glossary("LTR")}} or {{Glossary("RTL")}}) but needs to present the placeholder in the opposite directionality, you can use Unicode bidirectional algorithm formatting characters to override directionality within the placeholder; see [How to use Unicode controls for bidi text](https://www.w3.org/International/questions/qa-bidi-unicode-controls) for more information. - -> [!NOTE] -> Avoid using the `placeholder` attribute if you can. It is not as semantically useful as other ways to explain your form, and can cause unexpected technical issues with your content. See [`<input>` labels](/en-US/docs/Web/HTML/Element/input#labels) for more information. - -### readonly - -A Boolean attribute which, if present, means this field cannot be edited by the user. Its `value` can, however, still be changed by JavaScript code directly setting the {{domxref("HTMLInputElement")}} `value` property. - -> [!NOTE] -> Because a read-only field cannot have a value, `required` does not have any effect on inputs with the `readonly` attribute also specified. - -### size - -The `size` attribute is a numeric value indicating how many characters wide the input field should be. The value must be a number greater than zero, and the default value is 20. Since character widths vary, this may or may not be exact and should not be relied upon to be so; the resulting input may be narrower or wider than the specified number of characters, depending on the characters and the font ({{cssxref("font")}} settings in use). - -This does _not_ set a limit on how many characters the user can enter into the field. It only specifies approximately how many can be seen at a time. To set an upper limit on the length of the input data, use the [`maxlength`](#maxlength) attribute. - -### spellcheck - -[`spellcheck`](/en-US/docs/Web/HTML/Global_attributes/spellcheck) is a global attribute that is used to indicate whether to enable spell-checking for an element. It can be used on any editable content, but here we consider specifics related to the use of `spellcheck` on {{HTMLElement("input")}} elements. The permitted values for `spellcheck` are: - -- `false` - - : Disable spell-checking for this element. -- `true` - - : Enable spell-checking for this element. -- "" (empty string) or no value - - : Follow the element's default behavior for spell-checking. This may be based upon a parent's `spellcheck` setting or other factors. - -An input field can have spell-checking enabled if it doesn't have the [readonly](#readonly) attribute set and is not disabled. - -The value returned by reading `spellcheck` may not reflect the actual state of spell-checking within a control, if the {{Glossary("user agent", "user agent's")}} preferences override the setting. - -## Non-standard attributes - -The following non-standard attributes are available to search input fields. -Avoid using them where possible. - -### incremental - -The Boolean attribute `incremental` is a WebKit and Blink extension (so supported by Safari, Opera, Chrome, etc.) which, if present, tells the {{Glossary("user agent")}} to process the input as a live search. As the user edits the value of the field, the user agent sends {{domxref("HTMLInputElement/search_event", "search")}} events to the {{domxref("HTMLInputElement")}} object representing the search box. This allows your code to update the search results in real time as the user edits the search. - -If `incremental` is not specified, the {{domxref("HTMLInputElement/search_event", "search")}} event is only sent when the user explicitly initiates a search (such as by pressing the <kbd>Enter</kbd> or <kbd>Return</kbd> key while editing the field). - -The `search` event is rate-limited so that it is not sent more frequently than an implementation-defined interval. - -### results - -The `results` attribute—supported only by Safari—is a numeric value that lets you override the maximum number of entries to be displayed in the {{HTMLElement("input")}} element's natively-provided drop-down menu of previous search queries. - -The value must be a non-negative decimal number. If not provided, or an invalid value is given, the browser's default maximum number of entries is used. - -## Using search inputs - -`<input>` elements of type `search` are very similar to those of type `text`, except that they are specifically intended for handling search terms. They are basically equivalent in behavior, but user agents may choose to style them differently by default (and, of course, sites may use stylesheets to apply custom styles to them). - -### Basic example - -```html -<form> - <div> - <input type="search" id="mySearch" name="q" /> - <button>Search</button> - </div> -</form> -``` - -This renders like so: - -{{EmbedLiveSample("Basic_example", 600, 40)}} - -`q` is the most common `name` given to search inputs, although it's not mandatory. When submitted, the data name/value pair sent to the server will be `q=searchTerm`. - -> [!NOTE] -> You must remember to set a [`name`](/en-US/docs/Web/HTML/Element/input#name) for your input, otherwise nothing will be submitted. - -### Differences between search and text types - -The main basic differences come in the way browsers handle them. The first thing to note is that some browsers show a cross icon that can be clicked on to remove the search term instantly if desired, in Chrome this action is also triggered when pressing escape. The following screenshot comes from Chrome: - -![Focused search input, with focus ring, with the text 'cats'. There is an x icon in the input abutting the right side.](chrome-cross-icon.png) - -In addition, modern browsers also tend to automatically store search terms previously entered across domains, which then come up as autocomplete options when subsequent searches are performed in search inputs on that domain. This helps users who tend to do searches on the same or similar search queries over time. This screenshot is from Firefox: - -![An input in error state with a red focus ring. The user has entered the letter 'h'. A pop-up selection list is open directly under the input box with two options: hello and hermansje.](firefox-auto-complete.png) - -At this point, let's look at some useful techniques you can apply to your search forms. - -### Setting placeholders - -You can provide a useful placeholder inside your search input that could give a hint on what to do using the [`placeholder`](/en-US/docs/Web/HTML/Element/input#placeholder) attribute. Look at the following example: - -```html -<form> - <div> - <input - type="search" - id="mySearch" - name="q" - placeholder="Search the site…" /> - <button>Search</button> - </div> -</form> -``` - -You can see how the placeholder is rendered below: - -{{EmbedLiveSample("Setting_placeholders", 600, 40)}} - -### Search form labels and accessibility - -One problem with search forms is their accessibility; a common design practice is not to provide a label for the search field (although there might be a magnifying glass icon or similar), as the purpose of a search form is normally fairly obvious for sighted users due to placement ([this example shows a typical pattern](https://mdn.github.io/learning-area/accessibility/aria/website-aria-roles/)). - -This could, however, cause confusion for screen reader users, since they will not have any verbal indication of what the search input is. One way around this that won't impact on your visual design is to use [WAI-ARIA](/en-US/docs/Learn_web_development/Core/Accessibility/WAI-ARIA_basics) features: - -- A `role` attribute of value `search` on the `<form>` element will cause screen readers to announce that the form is a search form. -- If that isn't enough, you can use an [`aria-label`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-label) attribute on the {{HTMLElement("input")}} itself. This should be a descriptive text label that will be read out by the screen reader; it's used as a non-visual equivalent to `<label>`. - -Let's have a look at an example: - -```html -<form role="search"> - <div> - <input - type="search" - id="mySearch" - name="q" - placeholder="Search the site…" - aria-label="Search through site content" /> - <button>Search</button> - </div> -</form> -``` - -You can see how this is rendered below: - -{{EmbedLiveSample("Search_form_labels_and_accessibility", 600, 40)}} - -There is no visual difference from the previous example, but screen reader users have way more information available to them. - -> [!NOTE] -> See [Signposts/Landmarks](/en-US/docs/Learn_web_development/Core/Accessibility/WAI-ARIA_basics#signpostslandmarks) for more information about such accessibility features. - -### Physical input element size - -The physical size of the input box can be controlled using the [`size`](/en-US/docs/Web/HTML/Element/input#size) attribute. With it, you can specify the number of characters the input box can display at a time. In this example, for instance, the search box is 30 characters wide: - -```html -<form> - <div> - <input - type="search" - id="mySearch" - name="q" - placeholder="Search the site…" - size="30" /> - <button>Search</button> - </div> -</form> -``` - -The result is this wider input box: - -{{ EmbedLiveSample('Physical_input_element_size', 600, 40) }} - -## Validation - -`<input>` elements of type `search` have the same validation features available to them as regular `text` inputs. It is less likely that you'd want to use validation features in general for search boxes. In many cases, users should just be allowed to search for anything, but there are a few cases to consider, such as searches against data of a known format. - -> [!NOTE] -> HTML form validation is _not_ a substitute for scripts that ensure that the entered data is in the proper format. It's far too easy for someone to make adjustments to the HTML that allow them to bypass the validation, or to remove it entirely. It's also possible for someone to bypass your HTML entirely and submit the data directly to your server. If your server-side code fails to validate the data it receives, disaster could strike when improperly-formatted data (or data which is too large, is of the wrong type, and so forth) is entered into your database. - -### A note on styling - -There are useful pseudo-classes available for styling valid/invalid form elements: {{cssxref(":valid")}} and {{cssxref(":invalid")}}. In this section, we'll use the following CSS, which will place a check (tick) next to inputs containing valid values, and a cross next to inputs containing invalid values. - -```css -input:invalid ~ span::after { - content: "✖"; - padding-left: 5px; - position: absolute; -} - -input:valid ~ span::after { - content: "✓"; - padding-left: 5px; - position: absolute; -} -``` - -The technique also requires a {{htmlelement("span")}} element to be placed after the form element, which acts as a holder for the icons. This was necessary because some input types on some browsers don't display icons placed directly after them very well. - -### Making input required - -You can use the [`required`](/en-US/docs/Web/HTML/Element/input#required) attribute as an easy way of making entering a value required before form submission is allowed: - -```html -<form> - <div> - <input - type="search" - id="mySearch" - name="q" - placeholder="Search the site…" - required /> - <button>Search</button> - <span class="validity"></span> - </div> -</form> -``` - -```css hidden -input { - margin-right: 10px; -} - -input:invalid ~ span::after { - content: "✖"; - padding-left: 5px; - position: absolute; -} - -input:valid ~ span::after { - content: "✓"; - padding-left: 5px; - position: absolute; -} -``` - -This renders like so: - -{{ EmbedLiveSample('Making_input_required', 600, 40) }} - -In addition, if you try to submit the form with no search term entered into it, the browser will show a message. The following example is from Firefox: - -![form field with attached message that says Please fill out this field](firefox-required-message.png) - -Different messages will be shown when you try to submit the form with different types of invalid data contained inside the inputs; see the below examples. - -### Input value length - -You can specify a minimum length, in characters, for the entered value using the [`minlength`](/en-US/docs/Web/HTML/Element/input#minlength) attribute; similarly, use [`maxlength`](/en-US/docs/Web/HTML/Element/input#maxlength) to set the maximum length of the entered value. - -The example below requires that the entered value be 4–8 characters in length. - -```html -<form> - <div> - <label for="mySearch">Search for user</label> - <input - type="search" - id="mySearch" - name="q" - placeholder="User IDs are 4–8 characters in length" - required - size="30" - minlength="4" - maxlength="8" /> - <button>Search</button> - <span class="validity"></span> - </div> -</form> -``` - -```css hidden -input { - margin-right: 10px; -} - -input:invalid ~ span::after { - content: "✖"; - padding-left: 5px; - position: absolute; -} - -input:valid ~ span::after { - content: "✓"; - padding-left: 5px; - position: absolute; -} -``` - -This renders like so: - -{{ EmbedLiveSample('Input_value_length', 600, 40) }} - -If you try to submit the form with less than 4 characters, you'll be given an appropriate error message (which differs between browsers). If you try to go beyond 8 characters in length, the browser won't let you. - -### Specifying a pattern - -You can use the [`pattern`](/en-US/docs/Web/HTML/Element/input#pattern) attribute to specify a regular expression that the inputted value must follow to be considered valid (see [Validating against a regular expression](/en-US/docs/Learn_web_development/Extensions/Forms/Form_validation#validating_against_a_regular_expression) for a crash course). - -Let's look at an example. Say we wanted to provide a product ID search form, and the IDs were all codes of two letters followed by four numbers. The following example covers it: - -```html -<form> - <div> - <label for="mySearch">Search for product by ID:</label> - <input - type="search" - id="mySearch" - name="q" - placeholder="two letters followed by four numbers" - required - size="30" - pattern="[A-z]{2}[0-9]{4}" /> - <button>Search</button> - <span class="validity"></span> - </div> -</form> -``` - -```css hidden -input { - margin-right: 10px; -} - -input:invalid ~ span::after { - content: "✖"; - padding-left: 5px; - position: absolute; -} - -input:valid ~ span::after { - content: "✓"; - padding-left: 5px; - position: absolute; -} -``` - -This renders like so: - -{{ EmbedLiveSample('Specifying_a_pattern', 600, 40) }} - -## Examples - -You can see a good example of a search form used in context at our [website-aria-roles](https://github.com/mdn/learning-area/tree/main/accessibility/aria/website-aria-roles) example ([see it live](https://mdn.github.io/learning-area/accessibility/aria/website-aria-roles/)). - -## Technical summary - -<table class="properties"> - <tbody> - <tr> - <td><strong><a href="#value">Value</a></strong></td> - <td> - A string representing the value contained in - the search field. - </td> - </tr> - <tr> - <td><strong>Events</strong></td> - <td> - {{domxref("HTMLElement/change_event", "change")}} and - {{domxref("Element/input_event", "input")}} - </td> - </tr> - <tr> - <td><strong>Supported Common Attributes</strong></td> - <td> - <a href="/en-US/docs/Web/HTML/Element/input#autocomplete"><code>autocomplete</code></a>, - <a href="/en-US/docs/Web/HTML/Element/input#list"><code>list</code></a>, - <a href="/en-US/docs/Web/HTML/Element/input#maxlength"><code>maxlength</code></a>, - <a href="/en-US/docs/Web/HTML/Element/input#minlength"><code>minlength</code></a>, - <a href="/en-US/docs/Web/HTML/Element/input#pattern"><code>pattern</code></a>, - <a href="/en-US/docs/Web/HTML/Element/input#placeholder"><code>placeholder</code></a>, - <a href="/en-US/docs/Web/HTML/Element/input#required"><code>required</code></a>, - <a href="/en-US/docs/Web/HTML/Element/input#size"><code>size</code></a>. - </td> - </tr> - <tr> - <td><strong>IDL attributes</strong></td> - <td><code>value</code></td> - </tr> - <tr> - <td><strong>DOM interface</strong></td> - <td><p>{{domxref("HTMLInputElement")}}</p></td> - </tr> - <tr> - <td><strong>Methods</strong></td> - <td> - {{domxref("HTMLInputElement.select", "select()")}}, - {{domxref("HTMLInputElement.setRangeText", "setRangeText()")}}, - {{domxref("HTMLInputElement.setSelectionRange", "setSelectionRange()")}}. - </td> - </tr> - <tr> - <td><strong>Implicit ARIA Role</strong></td> - <td>with no <code>list</code> attribute: <code><a href="/en-US/docs/Web/Accessibility/ARIA/Roles/searchbox_role">searchbox</a></code></td> - <td>with <code>list</code> attribute: <code><a href="/en-US/docs/Web/Accessibility/ARIA/Roles/combobox_role">combobox</a></code></td> - </tr> - </tbody> -</table> - -## Specifications - -{{Specifications}} - -## Browser compatibility - -{{Compat}} - -## See also - -- [HTML Forms](/en-US/docs/Learn_web_development/Extensions/Forms) -- {{HTMLElement("input")}} and the {{domxref("HTMLInputElement")}} interface it's based upon -- [`<input type="text">`](/en-US/docs/Web/HTML/Element/input/text) diff --git a/files/en-us/web/html/element/input/submit/index.md b/files/en-us/web/html/element/input/submit/index.md deleted file mode 100644 index 1f6abc9ca68bb6b..000000000000000 --- a/files/en-us/web/html/element/input/submit/index.md +++ /dev/null @@ -1,223 +0,0 @@ ---- -title: <input type="submit"> -slug: Web/HTML/Element/input/submit -page-type: html-element -browser-compat: html.elements.input.type_submit ---- - -{{HTMLSidebar}} - -{{HTMLElement("input")}} elements of type **`submit`** are rendered as buttons. When the {{domxref("Element/click_event", "click")}} event occurs (typically because the user clicked the button), the {{Glossary("user agent")}} attempts to submit the form to the server. - -## Value - -An `<input type="submit">` element's [`value`](/en-US/docs/Web/HTML/Element/input#value) attribute contains a string which is displayed as the button's label. Buttons do not have a true value otherwise. The `value` provides the {{glossary("accessible description")}} for the button. - -### Setting the value attribute - -```html -<input type="submit" value="Send Request" /> -``` - -{{EmbedLiveSample("Setting_the_value_attribute", 650, 30)}} - -### Omitting the value attribute - -If you don't specify a `value`, the button will have a default label, chosen by the user agent. This label is likely to be something along the lines of "Submit" or "Submit Query." Here's an example of a submit button with a default label in your browser: - -```html -<input type="submit" /> -``` - -{{EmbedLiveSample("Omitting_the_value_attribute", 650, 30)}} - -## Additional attributes - -In addition to the attributes shared by all {{HTMLElement("input")}} elements, `submit` button inputs support the following attributes. - -### formaction - -A string indicating the URL to which to submit the data. This takes precedence over the [`action`](/en-US/docs/Web/HTML/Element/form#action) attribute on the {{HTMLElement("form")}} element that owns the {{HTMLElement("input")}}. - -This attribute is also available on [`<input type="image">`](/en-US/docs/Web/HTML/Element/input/image) and {{HTMLElement("button")}} elements. - -### formenctype - -A string that identifies the encoding method to use when submitting the form data to the server. There are three permitted values: - -- `application/x-www-form-urlencoded` - - : This, the default value, sends the form data as a string after {{Glossary("Percent-encoding", "percent-encoding")}} the text using an algorithm such as {{jsxref("encodeURI", "encodeURI()")}}. -- `multipart/form-data` - - : Uses the {{domxref("FormData")}} API to manage the data, allowing for files to be submitted to the server. You _must_ use this encoding type if your form includes any {{HTMLElement("input")}} elements of [`type`](/en-US/docs/Web/HTML/Element/input#type) `file` ([`<input type="file">`](/en-US/docs/Web/HTML/Element/input/file)). -- `text/plain` - - : Plain text; mostly useful only for debugging, so you can easily see the data that's to be submitted. - -If specified, the value of the `formenctype` attribute overrides the owning form's [`enctype`](/en-US/docs/Web/HTML/Element/form#enctype) attribute. - -This attribute is also available on [`<input type="image">`](/en-US/docs/Web/HTML/Element/input/image) and {{HTMLElement("button")}} elements. - -### formmethod - -A string indicating the HTTP method to use when submitting the form's data; this value overrides any [`method`](/en-US/docs/Web/HTML/Element/form#method) attribute given on the owning form. Permitted values are: - -- `get` - - : A URL is constructed by starting with the URL given by the `formaction` or [`action`](/en-US/docs/Web/HTML/Element/form#action) attribute, appending a question mark ("?") character, then appending the form's data, encoded as described by `formenctype` or the form's [`enctype`](/en-US/docs/Web/HTML/Element/form#enctype) attribute. This URL is then sent to the server using an HTTP {{HTTPMethod("get")}} request. This method works well for simple forms that contain only {{Glossary("ASCII")}} characters and have no side effects. This is the default value. -- `post` - - : The form's data is included in the body of the request that is sent to the URL given by the `formaction` or [`action`](/en-US/docs/Web/HTML/Element/form#action) attribute using an HTTP {{HTTPMethod("post")}} method. This method supports complex data and file attachments. -- `dialog` - - : This method is used to indicate that the button closes the dialog with which the input is associated, and does not transmit the form data at all. - -This attribute is also available on [`<input type="image">`](/en-US/docs/Web/HTML/Element/input/image) and {{HTMLElement("button")}} elements. - -### formnovalidate - -A Boolean attribute which, if present, specifies that the form should not be validated before submission to the server. This overrides the value of the [`novalidate`](/en-US/docs/Web/HTML/Element/form#novalidate) attribute on the element's owning form. - -This attribute is also available on [`<input type="image">`](/en-US/docs/Web/HTML/Element/input/image) and {{HTMLElement("button")}} elements. - -### formtarget - -A string which specifies a name or keyword that indicates where to display the response received after submitting the form. The string must be the name of a **browsing context** (that is, a tab, window, or {{HTMLElement("iframe")}}). A value specified here overrides any target given by the [`target`](/en-US/docs/Web/HTML/Element/form#target) attribute on the {{HTMLElement("form")}} that owns this input. - -In addition to the actual names of tabs, windows, or inline frames, there are a few special keywords that can be used: - -- `_self` - - : Loads the response into the same browsing context as the one that contains the form. This will replace the current document with the received data. This is the default value used if none is specified. -- `_blank` - - : Loads the response into a new, unnamed, browsing context. This is typically a new tab in the same window as the current document, but may differ depending on the configuration of the {{Glossary("user agent")}}. -- `_parent` - - : Loads the response into the parent browsing context of the current one. If there is no parent context, this behaves the same as `_self`. -- `_top` - - : Loads the response into the top-level browsing context; this is the browsing context that is the topmost ancestor of the current context. If the current context is the topmost context, this behaves the same as `_self`. - -This attribute is also available on [`<input type="image">`](/en-US/docs/Web/HTML/Element/input/image) and {{HTMLElement("button")}} elements. - -## Using submit buttons - -`<input type="submit">` buttons are used to submit forms. If you want to create a custom button and then customize the behavior using JavaScript, you need to use [`<input type="button">`](/en-US/docs/Web/HTML/Element/input/button), or better still, a {{htmlelement("button")}} element. - -If you choose to use `<button>` elements to create the buttons in your form, keep this in mind: If the `<button>` is inside a {{HTMLElement("form")}}, that button will be treated as the "submit" button. So you should be in the habit of expressly specifying which button is the submit button. - -### A basic submit button - -We'll begin by creating a form with a basic submit button: - -```html -<form> - <div> - <label for="example">Let's submit some text</label> - <input id="example" type="text" name="text" /> - </div> - <div> - <input type="submit" value="Send" /> - </div> -</form> -``` - -This renders like so: - -{{EmbedLiveSample("A_basic_submit_button", 650, 100)}} - -Try entering some text into the text field, and then submitting the form. - -Upon submitting, the data name/value pair gets sent to the server. In this instance, the string will be `text=user-text`, where "user-text" is the text entered by the user, encoded to preserve special characters. Where and how the data is submitted depends on the configuration of the `<form>`; see [Sending form data](/en-US/docs/Learn_web_development/Extensions/Forms/Sending_and_retrieving_form_data) for more details. - -### Adding a keyboard shortcut to a submit button - -Keyboard shortcuts, also known as access keys and keyboard equivalents, let the user trigger a button using a key or combination of keys on the keyboard. To add a keyboard shortcut to a submit button — just as you would with any {{HTMLElement("input")}} for which it makes sense — you use the [`accesskey`](/en-US/docs/Web/HTML/Global_attributes/accesskey) global attribute. - -In this example, <kbd>s</kbd> is specified as the access key (you'll need to press <kbd>s</kbd> plus the particular modifier keys for your browser/OS combination). In order to avoid conflicts with the user agent's own keyboard shortcuts, different modifier keys are used for access keys than for other shortcuts on the host computer. See [`accesskey`](/en-US/docs/Web/HTML/Global_attributes/accesskey) for further details. - -Here's the previous example with the <kbd>s</kbd> access key added: - -```html -<form> - <div> - <label for="example">Let's submit some text</label> - <input id="example" type="text" name="text" /> - </div> - <div> - <input type="submit" value="Send" accesskey="s" /> - </div> -</form> -``` - -For example, in Firefox for Mac, pressing <kbd>Control</kbd>-<kbd>Option</kbd>-<kbd>S</kbd> triggers the Send button, while Chrome on Windows uses <kbd>Alt</kbd>+<kbd>S</kbd>. - -{{EmbedLiveSample("Adding_a_keyboard_shortcut_to_a_submit_button", 650, 100)}} - -The problem with the above example is that the user will not know what the access key is! This is especially true since the modifiers are typically non-standard to avoid conflicts. When building a site, be sure to provide this information in a way that doesn't interfere with the site design (for example by providing an easily accessible link that points to information on what the site access keys are). Adding a tooltip to the button (using the [`title`](/en-US/docs/Web/HTML/Global_attributes/title) attribute) can also help, although it's not a complete solution for accessibility purposes. - -### Disabling and enabling a submit button - -To disable a submit button, specify the [`disabled`](/en-US/docs/Web/HTML/Attributes/disabled) attribute on it, like so: - -```html -<input type="submit" value="Send" disabled /> -``` - -You can enable and disable buttons at run time by setting `disabled` to `true` or `false`; in JavaScript this looks like `btn.disabled = true` or `btn.disabled = false`. - -> [!NOTE] -> See the [`<input type="button">`](/en-US/docs/Web/HTML/Element/input/button#disabling_and_enabling_a_button) page for more ideas about enabling and disabling buttons. - -## Validation - -Submit buttons don't participate in constraint validation; they have no real value to be constrained. - -## Examples - -We've included basic examples above. There isn't really anything more to say about submit buttons. There's a reason this kind of control is sometimes called a "simple button." - -## Technical Summary - -<table class="properties"> - <tbody> - <tr> - <td><strong><a href="#value">Value</a></strong></td> - <td>A string used as the button's label</td> - </tr> - <tr> - <td><strong>Events</strong></td> - <td>{{domxref("Element/click_event", "click")}}</td> - </tr> - <tr> - <td><strong>Supported common attributes</strong></td> - <td> - <a href="/en-US/docs/Web/HTML/Element/input#type"><code>type</code></a> and - <a href="/en-US/docs/Web/HTML/Element/input#value"><code>value</code></a> - </td> - </tr> - <tr> - <td><strong>IDL attributes</strong></td> - <td><code>value</code></td> - </tr> - <tr> - <td><strong>DOM interface</strong></td> - <td><p>{{domxref("HTMLInputElement")}}</p></td> - </tr> - <tr> - <td><strong>Methods</strong></td> - <td>None</td> - </tr> - <tr> - <td><strong>Implicit ARIA Role</strong></td> - <td><a href="/en-US/docs/Web/Accessibility/ARIA/Roles/button_role"><code>button</code></a></td> - </tr> - </tbody> -</table> - -## Specifications - -{{Specifications}} - -## Browser compatibility - -{{Compat}} - -## See also - -- {{HTMLElement("input")}} and the {{domxref("HTMLInputElement")}} interface which implements it. -- [Forms and buttons](/en-US/docs/Learn_web_development/Extensions/Forms/Basic_native_form_controls#actual_buttons) -- [HTML forms](/en-US/docs/Learn_web_development/Extensions/Forms) -- The {{HTMLElement("button")}} element diff --git a/files/en-us/web/html/element/input/tel/index.md b/files/en-us/web/html/element/input/tel/index.md deleted file mode 100644 index 388af35242ef431..000000000000000 --- a/files/en-us/web/html/element/input/tel/index.md +++ /dev/null @@ -1,550 +0,0 @@ ---- -title: <input type="tel"> -slug: Web/HTML/Element/input/tel -page-type: html-element -browser-compat: html.elements.input.type_tel ---- - -{{HTMLSidebar}} - -{{HTMLElement("input")}} elements of type **`tel`** are used to let the user enter and edit a telephone number. Unlike [`<input type="email">`](/en-US/docs/Web/HTML/Element/input/email) and [`<input type="url">`](/en-US/docs/Web/HTML/Element/input/url), the input value is not automatically validated to a particular format before the form can be submitted, because formats for telephone numbers vary so much around the world. - -{{InteractiveExample("HTML Demo: &lt;input type=&quot;tel&quot;&gt;", "tabbed-standard")}} - -```html interactive-example -<label for="phone"> - Enter your phone number:<br /> - <small>Format: 123-456-7890</small> -</label> - -<input - type="tel" - id="phone" - name="phone" - pattern="[0-9]{3}-[0-9]{3}-[0-9]{4}" - required /> -``` - -```css interactive-example -label { - display: block; - font: - 1rem "Fira Sans", - sans-serif; -} - -input, -label { - margin: 0.4rem 0; -} -``` - -Despite the fact that inputs of type `tel` are functionally identical to standard `text` inputs, they do serve useful purposes; the most quickly apparent of these is that mobile browsers — especially on mobile phones — may opt to present a custom keypad optimized for entering phone numbers. Using a specific input type for telephone numbers also makes adding custom validation and handling of phone numbers more convenient. - -> [!NOTE] -> Browsers that don't support type `tel` fall back to being a standard {{HTMLElement("input/text", "text")}} input. - -## Value - -The {{HTMLElement("input")}} element's [`value`](/en-US/docs/Web/HTML/Element/input#value) attribute contains a string that either represents a telephone number or is an empty string (`""`). - -## Additional attributes - -In addition to the [global attributes](/en-US/docs/Web/HTML/Global_attributes) and the attributes that operate on all {{HTMLElement("input")}} elements regardless of their type, telephone number inputs support the following attributes. - -### list - -The values of the list attribute is the {{domxref("Element.id", "id")}} of a {{HTMLElement("datalist")}} element located in the same document. The {{HTMLElement("datalist")}} provides a list of predefined values to suggest to the user for this input. Any values in the list that are not compatible with the [`type`](/en-US/docs/Web/HTML/Element/input#type) are not included in the suggested options. The values provided are suggestions, not requirements: users can select from this predefined list or provide a different value. - -### maxlength - -The maximum string length (measured in UTF-16 code units) that the user can enter into the telephone number field. This must be an integer value of 0 or higher. If no `maxlength` is specified, or an invalid value is specified, the telephone number field has no maximum length. This value must also be greater than or equal to the value of `minlength`. - -The input will fail [constraint validation](/en-US/docs/Web/HTML/Constraint_validation) if the length of the text entered into the field is greater than `maxlength` UTF-16 code units long. Constraint validation is only applied when the value is changed by the user. - -### minlength - -The minimum string length (measured in UTF-16 code units) that the user can enter into the telephone number field. This must be a non-negative integer value smaller than or equal to the value specified by `maxlength`. If no `minlength` is specified, or an invalid value is specified, the telephone number input has no minimum length. - -The telephone number field will fail [constraint validation](/en-US/docs/Web/HTML/Constraint_validation) if the length of the text entered into the field is fewer than `minlength` UTF-16 code units long. Constraint validation is only applied when the value is changed by the user. - -### pattern - -The `pattern` attribute, when specified, is a regular expression that the input's [`value`](/en-US/docs/Web/HTML/Element/input#value) must match for the value to pass [constraint validation](/en-US/docs/Web/HTML/Constraint_validation). It must be a valid JavaScript regular expression, as used by the {{jsxref("RegExp")}} type, and as documented in our [guide on regular expressions](/en-US/docs/Web/JavaScript/Guide/Regular_expressions); the `'u'` flag is specified when compiling the regular expression so that the pattern is treated as a sequence of Unicode code points, instead of as {{Glossary("ASCII")}}. No forward slashes should be specified around the pattern text. - -If the specified pattern is not specified or is invalid, no regular expression is applied and this attribute is ignored completely. - -> [!NOTE] -> Use the [`title`](/en-US/docs/Web/HTML/Element/input#title) attribute to specify text that most browsers will display as a tooltip to explain what the requirements are to match the pattern. You should also include other explanatory text nearby. - -See [Pattern validation](#pattern_validation) below for details and an example. - -### placeholder - -The `placeholder` attribute is a string that provides a brief hint to the user as to what kind of information is expected in the field. It should be a word or short phrase that demonstrates the expected type of data, rather than an explanatory message. The text _must not_ include carriage returns or line feeds. - -If the control's content has one directionality ({{Glossary("LTR")}} or {{Glossary("RTL")}}) but needs to present the placeholder in the opposite directionality, you can use Unicode bidirectional algorithm formatting characters to override directionality within the placeholder; see [How to use Unicode controls for bidi text](https://www.w3.org/International/questions/qa-bidi-unicode-controls) for more information. - -> [!NOTE] -> Avoid using the `placeholder` attribute if you can. It is not as semantically useful as other ways to explain your form, and can cause unexpected technical issues with your content. See [`<input>` labels](/en-US/docs/Web/HTML/Element/input#labels) for more information. - -### readonly - -A Boolean attribute which, if present, means this field cannot be edited by the user. Its `value` can, however, still be changed by JavaScript code directly setting the {{domxref("HTMLInputElement")}} `value` property. - -> [!NOTE] -> Because a read-only field cannot have a value, `required` does not have any effect on inputs with the `readonly` attribute also specified. - -### size - -The `size` attribute is a numeric value indicating how many characters wide the input field should be. The value must be a number greater than zero, and the default value is 20. Since character widths vary, this may or may not be exact and should not be relied upon to be so; the resulting input may be narrower or wider than the specified number of characters, depending on the characters and the font ({{cssxref("font")}} settings in use). - -This does _not_ set a limit on how many characters the user can enter into the field. It only specifies approximately how many can be seen at a time. To set an upper limit on the length of the input data, use the [`maxlength`](#maxlength) attribute. - -## Using tel inputs - -Telephone numbers are a very commonly collected type of data on the web. When creating any kind of registration or e-commerce site, for example, you will likely need to ask the user for a telephone number, whether for business purposes or for emergency contact purposes. Given how commonly-entered phone numbers are, it's unfortunate that a "one size fits all" solution for validating phone numbers is not practical. - -Fortunately, you can consider the requirements of your own site and implement an appropriate level of validation yourself. See [Validation](#validation), below, for details. - -### Custom keyboards - -One of the main advantages of `<input type="tel">` is that it causes mobile browsers to display a special keyboard for entering phone numbers. For example, here's what the keypads look like on a couple of devices. - -| Firefox for Android | WebKit iOS (Safari/Chrome/Firefox) | -| ------------------------------------------------------ | ------------------------------------------------------------ | -| ![Firefox for Android screen shot](fx-android-tel.png) | ![Firefox for iOS screenshot](iphone-tel-keyboard-50pct.png) | - -### A basic tel input - -In its most basic form, a tel input can be implemented like this: - -```html -<label for="telNo">Phone number:</label> -<input id="telNo" name="telNo" type="tel" /> -``` - -{{ EmbedLiveSample('A_basic_tel_input', 600, 40) }} - -There is nothing magical going on here. When submitted to the server, the above input's data would be represented as, for example, `telNo=+12125553151`. - -### Placeholders - -Sometimes it's helpful to offer an in-context hint as to what form the input data should take. This can be especially important if the page design doesn't offer descriptive labels for each {{HTMLElement("input")}}. This is where **placeholders** come in. A placeholder is a value that demonstrates the form the `value` should take by presenting an example of a valid value, which is displayed inside the edit box when the element's `value` is `""`. Once data is entered into the box, the placeholder disappears; if the box is emptied, the placeholder reappears. - -Here, we have an `tel` input with the placeholder `123-4567-8901`. Note how the placeholder disappears and reappears as you manipulate the contents of the edit field. - -```html -<input id="telNo" name="telNo" type="tel" placeholder="123-4567-8901" /> -``` - -{{ EmbedLiveSample('Placeholders', 600, 40) }} - -### Controlling the input size - -You can control not only the physical length of the input box, but also the minimum and maximum lengths allowed for the input text itself. - -#### Physical input element size - -The physical size of the input box can be controlled using the [`size`](/en-US/docs/Web/HTML/Element/input#size) attribute. With it, you can specify the number of characters the input box can display at a time. In this example, for instance, the `tel` edit box is 20 characters wide: - -```html -<input id="telNo" name="telNo" type="tel" size="20" /> -``` - -{{ EmbedLiveSample('Physical_input_element_size', 600, 40) }} - -#### Element value length - -The `size` is separate from the length limitation on the entered telephone number. You can specify a minimum length, in characters, for the entered telephone number using the [`minlength`](/en-US/docs/Web/HTML/Element/input#minlength) attribute; similarly, use [`maxlength`](/en-US/docs/Web/HTML/Element/input#maxlength) to set the maximum length of the entered telephone number. - -The example below creates a 20-character wide telephone number entry box, requiring that the contents be no shorter than 9 characters and no longer than 14 characters. - -```html -<input - id="telNo" - name="telNo" - type="tel" - size="20" - minlength="9" - maxlength="14" /> -``` - -{{EmbedLiveSample("Element_value_length", 600, 40) }} - -> [!NOTE] -> The above attributes do affect [Validation](#validation) — the above example's inputs will count as invalid if the length of the value is less than 9 characters, or more than 14. Most browser won't even let you enter a value over the max length. - -### Providing default options - -#### Providing a single default using the value attribute - -As always, you can provide a default value for an `tel` input box by setting its [`value`](/en-US/docs/Web/HTML/Element/input#value) attribute: - -```html -<input id="telNo" name="telNo" type="tel" value="333-4444-4444" /> -``` - -{{EmbedLiveSample("Providing_a_single_default_using_the_value_attribute", 600, 40)}} - -#### Offering suggested values - -Taking it a step further, you can provide a list of default phone number values from which the user can select. To do this, use the [`list`](/en-US/docs/Web/HTML/Element/input#list) attribute. This doesn't limit the user to those options, but does allow them to select commonly-used telephone numbers more quickly. This also offers hints to [`autocomplete`](/en-US/docs/Web/HTML/Element/input#autocomplete). The `list` attribute specifies the ID of a {{HTMLElement("datalist")}} element, which in turn contains one {{HTMLElement("option")}} element per suggested value; each `option`'s `value` is the corresponding suggested value for the telephone number entry box. - -```html -<label for="telNo">Phone number: </label> -<input id="telNo" name="telNo" type="tel" list="defaultTels" /> - -<datalist id="defaultTels"> - <option value="111-1111-1111"></option> - <option value="122-2222-2222"></option> - <option value="333-3333-3333"></option> - <option value="344-4444-4444"></option> -</datalist> -``` - -{{EmbedLiveSample("Offering_suggested_values", 600, 40)}} - -With the {{HTMLElement("datalist")}} element and its {{HTMLElement("option")}}s in place, the browser will offer the specified values as potential values for the phone number; this is typically presented as a popup or drop-down menu containing the suggestions. While the specific user experience may vary from one browser to another, typically clicking in the edit box presents a drop-down of the suggested phone numbers. Then, as the user types, the list is adjusted to show only filtered matching values. Each typed character narrows down the list until the user makes a selection or types a custom value. - -Here's a screenshot of what that might look like: - -![An input box has focus with a blue focus ring. The input has a drop-down menu showing four phone numbers the user can select.](phone-number-with-options.png) - -## Validation - -As we've touched on before, it's quite difficult to provide a one-size-fits-all client-side validation solution for phone numbers. So what can we do? Let's consider some options. - -> [!WARNING] -> HTML form validation is _not_ a substitute for server-side scripts that ensure the entered data is in the proper format before it is allowed into the database. It's far too easy for someone to make adjustments to the HTML that allow them to bypass the validation, or to remove it entirely. It's also possible for someone to bypass your HTML entirely and submit the data directly to your server. If your server-side code fails to validate the data it receives, disaster could strike when improperly-formatted data (or data which is too large, is of the wrong type, and so forth) is entered into your database. - -### Making telephone numbers required - -You can make it so that an empty input is invalid and won't be submitted to the server using the [`required`](/en-US/docs/Web/HTML/Element/input#required) attribute. For example, let's use this HTML: - -```html -<form> - <div> - <label for="telNo">Enter a telephone number (required): </label> - <input id="telNo" name="telNo" type="tel" required /> - <span class="validity"></span> - </div> - <div> - <button>Submit</button> - </div> -</form> -``` - -And let's include the following CSS to highlight valid entries with a checkmark and invalid entries with a cross: - -```css -div { - margin-bottom: 10px; - position: relative; -} - -input[type="number"] { - width: 100px; -} - -input + span { - padding-right: 30px; -} - -input:invalid + span::after { - position: absolute; - content: "✖"; - padding-left: 5px; - color: #8b0000; -} - -input:valid + span::after { - position: absolute; - content: "✓"; - padding-left: 5px; - color: #009000; -} -``` - -The output looks like this: - -{{EmbedLiveSample("Making_telephone_numbers_required", 700, 70)}} - -### Pattern validation - -If you want to further restrict entered numbers so they also have to conform to a specific pattern, you can use the [`pattern`](/en-US/docs/Web/HTML/Element/input#pattern) attribute, which takes as its value a {{Glossary("regular expression")}} that entered values have to match. - -In this example we'll use the same CSS as before, but our HTML is changed to look like this: - -```html -<form> - <div> - <label for="telNo"> - Enter a telephone number (in the form xxx-xxx-xxxx): - </label> - <input - id="telNo" - name="telNo" - type="tel" - required - pattern="[0-9]{3}-[0-9]{3}-[0-9]{4}" /> - <span class="validity"></span> - </div> - <div> - <button>Submit</button> - </div> -</form> -``` - -```css hidden -div { - margin-bottom: 10px; - position: relative; -} - -input[type="number"] { - width: 100px; -} - -input + span { - padding-right: 30px; -} - -input:invalid + span::after { - position: absolute; - content: "✖"; - padding-left: 5px; - color: #8b0000; -} - -input:valid + span::after { - position: absolute; - content: "✓"; - padding-left: 5px; - color: #009000; -} -``` - -{{EmbedLiveSample("Pattern_validation", 700, 70)}} - -Notice how the entered value is reported as invalid unless the pattern xxx-xxx-xxxx is matched; for instance, 41-323-421 won't be accepted. Neither will 800-MDN-ROCKS. However, 865-555-6502 will be accepted. This particular pattern is obviously only useful for certain locales — in a real application you'd probably have to vary the pattern used depending on the locale of the user. - -## Examples - -In this example, we present a {{htmlelement("select")}} element that lets the user choose which country they're in, and a set of `<input type="tel">` elements to let them enter each part of their phone number; there is no reason why you can't have multiple `tel` inputs. - -Each input has a [`placeholder`](/en-US/docs/Web/HTML/Element/input#placeholder) attribute to show a hint to sighted users about what to enter into it, a [`pattern`](/en-US/docs/Web/HTML/Element/input#pattern) to enforce a specific number of characters for the desired section, and an [`aria-label`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-label) attribute to contain a hint to be read out to screen reader users about what to enter into it. - -```html -<form> - <div> - <label for="country">Choose your country:</label> - <select id="country" name="country"> - <option>UK</option> - <option selected>US</option> - <option>Germany</option> - </select> - </div> - <div> - <p>Enter your telephone number:</p> - <span class="areaDiv"> - <input - id="areaNo" - name="areaNo" - type="tel" - required - placeholder="Area code" - pattern="[0-9]{3}" - aria-label="Area code" /> - <span class="validity"></span> - </span> - <span class="number1Div"> - <input - id="number1" - name="number1" - type="tel" - required - placeholder="First part" - pattern="[0-9]{3}" - aria-label="First part of number" /> - <span class="validity"></span> - </span> - <span class="number2Div"> - <input - id="number2" - name="number2" - type="tel" - required - placeholder="Second part" - pattern="[0-9]{4}" - aria-label="Second part of number" /> - <span class="validity"></span> - </span> - </div> - <div> - <button>Submit</button> - </div> -</form> -``` - -The JavaScript contains an {{domxref("HTMLElement.change_event", "onchange")}} event handler that, when the `<select>` value is changed, updates the `<input>` element's `pattern`, `placeholder`, and `aria-label` to suit the format of telephone numbers in that country/territory. - -```js -const selectElem = document.querySelector("select"); -const inputElems = document.querySelectorAll("input"); - -selectElem.onchange = () => { - for (let i = 0; i < inputElems.length; i++) { - inputElems[i].value = ""; - } - - if (selectElem.value === "US") { - inputElems[2].parentNode.style.display = "inline"; - - inputElems[0].placeholder = "Area code"; - inputElems[0].pattern = "[0-9]{3}"; - - inputElems[1].placeholder = "First part"; - inputElems[1].pattern = "[0-9]{3}"; - inputElems[1].setAttribute("aria-label", "First part of number"); - - inputElems[2].placeholder = "Second part"; - inputElems[2].pattern = "[0-9]{4}"; - inputElems[2].setAttribute("aria-label", "Second part of number"); - } else if (selectElem.value === "UK") { - inputElems[2].parentNode.style.display = "none"; - - inputElems[0].placeholder = "Area code"; - inputElems[0].pattern = "[0-9]{3,6}"; - - inputElems[1].placeholder = "Local number"; - inputElems[1].pattern = "[0-9]{4,8}"; - inputElems[1].setAttribute("aria-label", "Local number"); - } else if (selectElem.value === "Germany") { - inputElems[2].parentNode.style.display = "inline"; - - inputElems[0].placeholder = "Area code"; - inputElems[0].pattern = "[0-9]{3,5}"; - - inputElems[1].placeholder = "First part"; - inputElems[1].pattern = "[0-9]{2,4}"; - inputElems[1].setAttribute("aria-label", "First part of number"); - - inputElems[2].placeholder = "Second part"; - inputElems[2].pattern = "[0-9]{4}"; - inputElems[2].setAttribute("aria-label", "Second part of number"); - } -}; -``` - -The example looks like this: - -{{EmbedLiveSample('Examples', 600, 140)}} - -This is an interesting idea, which goes to show a potential solution to the problem of dealing with international phone numbers. You would have to extend the example of course to provide the correct pattern for potentially every country, which would be a lot of work, and there would still be no foolproof guarantee that the users would enter their numbers correctly. - -It makes you wonder if it is worth going to all this trouble on the client-side, when you could just let the user enter their number in whatever format they wanted on the client-side and then validate and sanitize it on the server. But this choice is yours to make. - -```css hidden -div { - margin-bottom: 10px; - position: relative; -} - -input[type="number"] { - width: 100px; -} - -input + span { - padding-right: 30px; -} - -input:invalid + span::after { - position: absolute; - content: "✖"; - padding-left: 5px; - color: #8b0000; -} - -input:valid + span::after { - position: absolute; - content: "✓"; - padding-left: 5px; - color: #009000; -} -``` - -## Technical Summary - -<table class="properties"> - <tbody> - <tr> - <td><strong><a href="#value">Value</a></strong></td> - <td> - A string representing a telephone number, or - empty - </td> - </tr> - <tr> - <td><strong>Events</strong></td> - <td> - {{domxref("HTMLElement/change_event", "change")}} and - {{domxref("Element/input_event", "input")}} - </td> - </tr> - <tr> - <td><strong>Supported common attributes</strong></td> - <td> - <a href="/en-US/docs/Web/HTML/Element/input#autocomplete"><code>autocomplete</code></a>, - <a href="/en-US/docs/Web/HTML/Element/input#list"><code>list</code></a>, - <a href="/en-US/docs/Web/HTML/Element/input#maxlength"><code>maxlength</code></a>, - <a href="/en-US/docs/Web/HTML/Element/input#minlength"><code>minlength</code></a>, - <a href="/en-US/docs/Web/HTML/Element/input#pattern"><code>pattern</code></a>, - <a href="/en-US/docs/Web/HTML/Element/input#placeholder"><code>placeholder</code></a>, - <a href="/en-US/docs/Web/HTML/Element/input#readonly"><code>readonly</code></a>, and - <a href="/en-US/docs/Web/HTML/Element/input#size"><code>size</code></a> - </td> - </tr> - <tr> - <td><strong>IDL attributes</strong></td> - <td> - <code>list</code>, <code>selectionStart</code>, - <code>selectionEnd</code>, <code>selectionDirection</code>, and - <code>value</code> - </td> - </tr> - <tr> - <td><strong>DOM interface</strong></td> - <td><p>{{domxref("HTMLInputElement")}}</p></td> - </tr> - <tr> - <td><strong>Methods</strong></td> - <td> - {{domxref("HTMLInputElement.select", "select()")}}, - {{domxref("HTMLInputElement.setRangeText", "setRangeText()")}}, - {{domxref("HTMLInputElement.setSelectionRange", "setSelectionRange()")}} - </td> - </tr> - <tr> - <td><strong>Implicit ARIA Role</strong></td> - <td>with no <code>list</code> attribute: - <code><a href="/en-US/docs/Web/Accessibility/ARIA/Roles/textbox_role">textbox</a></code></td> - <td>with <code>list</code> attribute: <code><a href="/en-US/docs/Web/Accessibility/ARIA/Roles/combobox_role">combobox</a></code></td> - </tr> - </tbody> -</table> - -## Specifications - -{{Specifications}} - -## Browser compatibility - -{{Compat}} - -## See also - -- [HTML forms guide](/en-US/docs/Learn_web_development/Extensions/Forms) -- {{HTMLElement("input")}} - - [`<input type="text">`](/en-US/docs/Web/HTML/Element/input/text) - - [`<input type="email">`](/en-US/docs/Web/HTML/Element/input/email) diff --git a/files/en-us/web/html/element/input/text/index.md b/files/en-us/web/html/element/input/text/index.md deleted file mode 100644 index 2a441eb94c68d3a..000000000000000 --- a/files/en-us/web/html/element/input/text/index.md +++ /dev/null @@ -1,460 +0,0 @@ ---- -title: <input type="text"> -slug: Web/HTML/Element/input/text -page-type: html-element -browser-compat: html.elements.input.type_text ---- - -{{HTMLSidebar}} - -{{HTMLElement("input")}} elements of type **`text`** create basic single-line text fields. - -{{InteractiveExample("HTML Demo: &lt;input type=&quot;text&quot;&gt;", "tabbed-shorter")}} - -```html interactive-example -<label for="name">Name (4 to 8 characters):</label> - -<input - type="text" - id="name" - name="name" - required - minlength="4" - maxlength="8" - size="10" /> -``` - -```css interactive-example -label { - display: block; - font: - 1rem "Fira Sans", - sans-serif; -} - -input, -label { - margin: 0.4rem 0; -} -``` - -## Value - -The [`value`](/en-US/docs/Web/HTML/Element/input#value) attribute is a string that contains the current value of the text entered into the text field. You can retrieve this using the {{domxref("HTMLInputElement")}} `value` property in JavaScript. - -```js -let theText = myTextInput.value; -``` - -If no validation constraints are in place for the input (see [Validation](#validation) for more details), the value may be an empty string (`""`). - -## Additional attributes - -In addition to the [global attributes](/en-US/docs/Web/HTML/Global_attributes) and the attributes that operate on all {{HTMLElement("input")}} elements regardless of their type, text inputs support the following attributes. - -### `list` - -The values of the list attribute is the {{domxref("Element.id", "id")}} of a {{HTMLElement("datalist")}} element located in the same document. The {{HTMLElement("datalist")}} provides a list of predefined values to suggest to the user for this input. Any values in the list that are not compatible with the [`type`](/en-US/docs/Web/HTML/Element/input#type) are not included in the suggested options. The values provided are suggestions, not requirements: users can select from this predefined list or provide a different value. - -### `maxlength` - -The maximum string length (measured in UTF-16 code units) that the user can enter into the `text` input. This must be an integer value of 0 or higher. If no `maxlength` is specified, or an invalid value is specified, the `text` input has no maximum length. This value must also be greater than or equal to the value of `minlength`. - -The input will fail [constraint validation](/en-US/docs/Web/HTML/Constraint_validation) if the length of the text value of the field is greater than `maxlength` UTF-16 code units long. Constraint validation is only applied when the value is changed by the user. - -### `minlength` - -The minimum string length (measured in UTF-16 code units) that the user can enter into the `text` input. This must be a non-negative integer value smaller than or equal to the value specified by `maxlength`. If no `minlength` is specified, or an invalid value is specified, the `text` input has no minimum length. - -The input will fail [constraint validation](/en-US/docs/Web/HTML/Constraint_validation) if the length of the text entered into the field is fewer than `minlength` UTF-16 code units long. Constraint validation is only applied when the value is changed by the user. - -### `pattern` - -The `pattern` attribute, when specified, is a regular expression that the input's [`value`](/en-US/docs/Web/HTML/Element/input#value) must match for the value to pass [constraint validation](/en-US/docs/Web/HTML/Constraint_validation). It must be a valid JavaScript regular expression, as used by the {{jsxref("RegExp")}} type, and as documented in our [guide on regular expressions](/en-US/docs/Web/JavaScript/Guide/Regular_expressions); the `'u'` flag is specified when compiling the regular expression so that the pattern is treated as a sequence of Unicode code points, instead of as {{Glossary("ASCII")}}. No forward slashes should be specified around the pattern text. - -If the specified pattern is not specified or is invalid, no regular expression is applied and this attribute is ignored completely. - -> [!NOTE] -> Use the [`title`](/en-US/docs/Web/HTML/Element/input#title) attribute to specify text that most browsers will display as a tooltip to explain what the requirements are to match the pattern. You should also include other explanatory text nearby. - -See [Specifying a pattern](#specifying_a_pattern) for further details and an example. - -### `placeholder` - -The `placeholder` attribute is a string that provides a brief hint to the user as to what kind of information is expected in the field. It should be a word or short phrase that demonstrates the expected type of data, rather than an explanatory message. The text _must not_ include carriage returns or line feeds. - -If the control's content has one directionality ({{Glossary("LTR")}} or {{Glossary("RTL")}}) but needs to present the placeholder in the opposite directionality, you can use Unicode bidirectional algorithm formatting characters to override directionality within the placeholder; see [How to use Unicode controls for bidi text](https://www.w3.org/International/questions/qa-bidi-unicode-controls) for more information. - -> [!NOTE] -> Avoid using the `placeholder` attribute if you can. It is not as semantically useful as other ways to explain your form, and can cause unexpected technical issues with your content. See [`<input>` accessibility concerns](/en-US/docs/Web/HTML/Element/input#accessibility) for more information. - -### `readonly` - -A Boolean attribute which, if present, means this field cannot be edited by the user. Its `value` can, however, still be changed by JavaScript code directly setting the {{domxref("HTMLInputElement")}} `value` property. - -> [!NOTE] -> Because a read-only field cannot have a value, `required` does not have any effect on inputs with the `readonly` attribute also specified. - -### `size` - -The `size` attribute is a numeric value indicating how many characters wide the input field should be. The value must be a number greater than zero, and the default value is 20. Since character widths vary, this may or may not be exact and should not be relied upon to be so; the resulting input may be narrower or wider than the specified number of characters, depending on the characters and the font ({{cssxref("font")}} settings in use). - -This does _not_ set a limit on how many characters the user can enter into the field. It only specifies approximately how many can be seen at a time. To set an upper limit on the length of the input data, use the [`maxlength`](#maxlength) attribute. - -### `spellcheck` - -The [`spellcheck`](/en-US/docs/Web/HTML/Global_attributes/spellcheck) global attribute is used to indicate whether to enable spell-checking for an element. It can be used on any editable content, but here we consider specifics related to the use of `spellcheck` on {{HTMLElement("input")}} elements. The permitted values for `spellcheck` are: - -- `false` - - : Disable spell-checking for this element. -- `true` - - : Enable spell-checking for this element. -- `""` (empty string) or no value - - : Follow the element's default behavior for spell-checking. This may be based upon a parent's `spellcheck` setting or other factors. - -An input field can have spell-checking enabled if it doesn't have the [readonly](#readonly) attribute set and is not disabled. - -The value returned by reading `spellcheck` may not reflect the actual state of spell-checking within a control, if the {{Glossary("user agent", "user agent's")}} preferences override the setting. - -## Using text inputs - -`<input>` elements of type `text` create basic, single-line inputs. You should use them anywhere you want the user to enter a single-line value and there isn't a more specific input type available for collecting that value (for example, if it's a [date](/en-US/docs/Web/HTML/Element/input/datetime-local), [URL](/en-US/docs/Web/HTML/Element/input/url), [email](/en-US/docs/Web/HTML/Element/input/email), or [search term](/en-US/docs/Web/HTML/Element/input/search), you've got better options available). - -### Basic example - -```html -<form> - <div> - <label for="uname">Choose a username: </label> - <input type="text" id="uname" name="name" /> - </div> - <div> - <button>Submit</button> - </div> -</form> -``` - -This renders like so: - -{{EmbedLiveSample("Basic_example", 600, 80)}} - -When submitted, the data name/value pair sent to the server will be `name=Chris` (if "Chris" was entered as the input value before submission). You must remember to include [`name`](/en-US/docs/Web/HTML/Element/input#name) attribute on the {{HTMLElement("input")}} element, otherwise the text field's value won't be included with the submitted data. - -### Setting placeholders - -You can provide a useful placeholder inside your text input that can provide a hint as to what to enter by including using the [`placeholder`](/en-US/docs/Web/HTML/Element/input#placeholder) attribute. Look at the following example: - -```html -<form> - <div> - <label for="uname">Choose a username: </label> - <input - type="text" - id="uname" - name="name" - placeholder="Lower case, all one word" /> - </div> - <div> - <button>Submit</button> - </div> -</form> -``` - -You can see how the placeholder is rendered below: - -{{EmbedLiveSample("Setting_placeholders", 600, 80)}} - -The placeholder is typically rendered in a lighter color than the element's foreground color, and automatically vanishes when the user begins to enter text into the field (or whenever the field has a value set programmatically by setting its `value` attribute). - -### Physical input element size - -The physical size of the input box can be controlled using the [`size`](/en-US/docs/Web/HTML/Element/input#size) attribute. With it, you can specify the number of characters the text input can display at a time. This affects the width of the element, letting you specify the width in terms of characters rather than pixels. In this example, for instance, the input is 30 characters wide: - -```html -<form> - <div> - <label for="uname">Choose a username: </label> - <input - type="text" - id="uname" - name="name" - placeholder="Lower case, all one word" - size="30" /> - </div> - <div> - <button>Submit</button> - </div> -</form> -``` - -{{EmbedLiveSample('Physical_input_element_size', 600, 80)}} - -## Validation - -`<input>` elements of type `text` have no automatic validation applied to them (since a basic text input needs to be capable of accepting any arbitrary string), but there are some client-side validation options available, which we'll discuss below. - -> [!NOTE] -> HTML form validation is _not_ a substitute for server-scripts that ensure the entered data is in the proper format. It's far too easy for someone to make adjustments to the HTML that allow them to bypass the validation, or to remove it entirely. It's also possible for someone to bypass your HTML entirely and submit the data directly to your server. If your server-side code fails to validate the data it receives, disaster could strike when improperly-formatted data (or data which is too large, is of the wrong type, and so forth) is entered into your database. - -### A note on styling - -There are useful pseudo-classes available for styling form elements to help the user see when their values are valid or invalid. These are {{cssxref(":valid")}} and {{cssxref(":invalid")}}. In this section, we'll use the following CSS, which will place a check (tick) mark next to inputs containing valid values, and a cross (X) next to inputs containing invalid values. - -```css -div { - margin-bottom: 10px; - position: relative; -} - -input + span { - padding-right: 30px; -} - -input:invalid + span::after { - position: absolute; - content: "✖"; - padding-left: 5px; -} - -input:valid + span::after { - position: absolute; - content: "✓"; - padding-left: 5px; -} -``` - -The technique also requires a {{htmlelement("span")}} element to be placed after the form element, which acts as a holder for the icons. This was necessary because some input types on some browsers don't display icons placed directly after them very well. - -### Making input required - -You can use the [`required`](/en-US/docs/Web/HTML/Element/input#required) attribute as an easy way of making entering a value required before form submission is allowed: - -```html -<form> - <div> - <label for="uname">Choose a username: </label> - <input type="text" id="uname" name="name" required /> - <span class="validity"></span> - </div> - <div> - <button>Submit</button> - </div> -</form> -``` - -```css hidden -div { - margin-bottom: 10px; - position: relative; -} -input + span { - padding-right: 30px; -} -input:invalid + span::after { - position: absolute; - content: "✖"; - padding-left: 5px; -} -input:valid + span::after { - position: absolute; - content: "✓"; - padding-left: 5px; -} -``` - -This renders like so: - -{{EmbedLiveSample('Making_input_required', 600, 100)}} - -If you try to submit the form with no search term entered into it, the browser will show an error message. - -### Input value length - -You can specify a minimum length (in characters) for the entered value using the [`minlength`](/en-US/docs/Web/HTML/Element/input#minlength) attribute; similarly, use [`maxlength`](/en-US/docs/Web/HTML/Element/input#maxlength) to set the maximum length of the entered value, in characters. - -The example below requires that the entered value be 4–8 characters in length. - -```html -<form> - <div> - <label for="uname">Choose a username: </label> - <input - type="text" - id="uname" - name="name" - required - size="10" - placeholder="Username" - minlength="4" - maxlength="8" /> - <span class="validity"></span> - </div> - <div> - <button>Submit</button> - </div> -</form> -``` - -```css hidden -div { - margin-bottom: 10px; - position: relative; -} -input + span { - padding-right: 30px; -} -input:invalid + span::after { - position: absolute; - content: "✖"; - padding-left: 5px; -} -input:valid + span::after { - position: absolute; - content: "✓"; - padding-left: 5px; -} -``` - -This renders like so: - -{{EmbedLiveSample('Input_value_length', 600, 100)}} - -If you try to submit the form with less than 4 characters, you'll be given an appropriate error message (which differs between browsers). If you try to enter more than 8 characters, the browser won't let you. - -> [!NOTE] -> If you specify a `minlength` but do not specify `required`, the input is considered valid, since the user is not required to specify a value. - -### Specifying a pattern - -You can use the [`pattern`](/en-US/docs/Web/HTML/Element/input#pattern) attribute to specify a regular expression that the inputted value must match in order to be considered valid (see [Validating against a regular expression](/en-US/docs/Learn_web_development/Extensions/Forms/Form_validation#validating_against_a_regular_expression) for a crash course on using regular expressions to validate inputs). - -The example below restricts the value to 4-8 characters and requires that it contain only lower-case letters. - -```html -<form> - <div> - <label for="uname">Choose a username: </label> - <input - type="text" - id="uname" - name="name" - required - size="45" - pattern="[a-z]{4,8}" /> - <span class="validity"></span> - <p>Usernames must be lowercase and 4-8 characters in length.</p> - </div> - <div> - <button>Submit</button> - </div> -</form> -``` - -```css hidden -div { - margin-bottom: 10px; - position: relative; -} - -p { - font-size: 80%; - color: #999; -} - -input + span { - padding-right: 30px; -} - -input:invalid + span::after { - position: absolute; - content: "✖"; - padding-left: 5px; -} - -input:valid + span::after { - position: absolute; - content: "✓"; - padding-left: 5px; -} -``` - -This renders like so: - -{{EmbedLiveSample('Specifying_a_pattern', 600, 130)}} - -## Examples - -You can see good examples of text inputs used in context in our [Your first HTML form](/en-US/docs/Learn_web_development/Extensions/Forms/Your_first_form) and [How to structure an HTML form](/en-US/docs/Learn_web_development/Extensions/Forms/How_to_structure_a_web_form) articles. - -## Technical summary - -<table class="properties"> - <tbody> - <tr> - <td><strong><a href="#value">Value</a></strong></td> - <td> - A string representing the text contained in - the text field. - </td> - </tr> - <tr> - <td><strong>Events</strong></td> - <td> - {{domxref("HTMLElement/change_event", "change")}} and - {{domxref("Element/input_event", "input")}} - </td> - </tr> - <tr> - <td><strong>Supported Common Attributes</strong></td> - <td> - <a href="/en-US/docs/Web/HTML/Element/input#autocomplete"><code>autocomplete</code></a>, - <a href="/en-US/docs/Web/HTML/Element/input#list"><code>list</code></a>, - <a href="/en-US/docs/Web/HTML/Element/input#maxlength"><code>maxlength</code></a>, - <a href="/en-US/docs/Web/HTML/Element/input#minlength"><code>minlength</code></a>, - <a href="/en-US/docs/Web/HTML/Element/input#pattern"><code>pattern</code></a>, - <a href="/en-US/docs/Web/HTML/Element/input#placeholder"><code>placeholder</code></a>, - <a href="/en-US/docs/Web/HTML/Element/input#readonly"><code>readonly</code></a>, - <a href="/en-US/docs/Web/HTML/Element/input#required"><code>required</code></a> and - <a href="/en-US/docs/Web/HTML/Element/input#size"><code>size</code></a> - </td> - </tr> - <tr> - <td><strong>IDL attributes</strong></td> - <td><a href="/en-US/docs/Web/HTML/Element/input#list"><code>list</code></a>, <code>value</code></td> - </tr> - <tr> - <td><strong>DOM interface</strong></td> - <td><p>{{domxref("HTMLInputElement")}}</p></td> - </tr> - <tr> - <td><strong>Methods</strong></td> - <td> - {{domxref("HTMLInputElement.select", "select()")}}, - {{domxref("HTMLInputElement.setRangeText", "setRangeText()")}} - and - {{domxref("HTMLInputElement.setSelectionRange", "setSelectionRange()")}}. - </td> - </tr> - <tr> - <td><strong>Implicit ARIA Role</strong></td> - <td>with no <code>list</code> attribute: - <code><a href="/en-US/docs/Web/Accessibility/ARIA/Roles/textbox_role">textbox</a></code></td> - <td>with <code>list</code> attribute: <code><a href="/en-US/docs/Web/Accessibility/ARIA/Roles/combobox_role">combobox</a></code></td> - </tr> - </tbody> -</table> - -## Specifications - -{{Specifications}} - -## Browser compatibility - -{{Compat}} - -## See also - -- [HTML Forms](/en-US/docs/Learn_web_development/Extensions/Forms) -- {{HTMLElement("input")}} and the {{domxref("HTMLInputElement")}} interface it's based upon. -- [`<input type="search">`](/en-US/docs/Web/HTML/Element/input/search) -- {{HTMLElement("textarea")}}: Multi-line text input diff --git a/files/en-us/web/html/element/input/time/index.md b/files/en-us/web/html/element/input/time/index.md deleted file mode 100644 index 653e8d267169db3..000000000000000 --- a/files/en-us/web/html/element/input/time/index.md +++ /dev/null @@ -1,410 +0,0 @@ ---- -title: <input type="time"> -slug: Web/HTML/Element/input/time -page-type: html-element -browser-compat: html.elements.input.type_time ---- - -{{HTMLSidebar}} - -{{htmlelement("input")}} elements of type **`time`** create input fields designed to let the user easily enter a time (hours and minutes, and optionally seconds). - -While the control's user interface appearance is based on the browser and operating system, the features are the same. The value is always a 24-hour `HH:mm` or `HH:mm:ss` formatted time, with leading zeros, regardless of the UI's input format. - -{{InteractiveExample("HTML Demo: &lt;input type=&quot;time&quot;&gt;", "tabbed-standard")}} - -```html interactive-example -<label for="appointment">Choose a time for your meeting:</label> - -<input - type="time" - id="appointment" - name="appointment" - min="09:00" - max="18:00" - required /> - -<small>Office hours are 9am to 6pm</small> -``` - -```css interactive-example -label { - display: block; - font: - 1rem "Fira Sans", - sans-serif; -} - -input, -label { - margin: 0.4rem 0; -} -``` - -### Setting the value attribute - -You can set a default value for the input by including a valid time in the [`value`](/en-US/docs/Web/HTML/Element/input#value) attribute when creating the `<input>` element, like so: - -```html -<label for="appointment-time">Choose an appointment time: </label> -<input - id="appointment-time" - type="time" - name="appointment-time" - value="13:30" /> -``` - -{{ EmbedLiveSample('Setting_the_value_attribute', 600, 60) }} - -### Setting the value using JavaScript - -You can also get and set the time value in JavaScript using the {{domxref("HTMLInputElement")}} `value` property, for example: - -```js -const timeControl = document.querySelector('input[type="time"]'); -timeControl.value = "15:30"; -``` - -### Time value format - -The `value` of the `time` input is always in 24-hour format that includes leading zeros: `HH:mm`, regardless of the input format, which is likely to be selected based on the user's locale (or by the user agent). If the time includes seconds (see [Using the step attribute](#using_the_step_attribute)), the format is always `HH:mm:ss`. You can learn more about the format of the time value used by this input type in [Time strings](/en-US/docs/Web/HTML/Date_and_time_formats#time_strings). - -In this example, you can see the time input's value by entering a time and seeing how it changes afterward. - -First, a look at the HTML. We include a label and input, and add a {{HTMLElement("p")}} element with a {{HTMLElement("span")}} to display the value of the `time` input: - -```html -<form> - <label for="startTime">Start time: </label> - <input type="time" id="startTime" /> - <p> - Value of the <code>time</code> input: - <code>"<span id="value">n/a</span>"</code>. - </p> -</form> -``` - -The JavaScript code adds code to the time input to watch for the {{domxref("Element/input_event", "input")}} event, which is triggered every time the contents of an input element change. When this happens, the contents of the `<span>` are replaced with the new value of the input element. - -```js -const startTime = document.getElementById("startTime"); -const valueSpan = document.getElementById("value"); - -startTime.addEventListener( - "input", - () => { - valueSpan.innerText = startTime.value; - }, - false, -); -``` - -{{EmbedLiveSample("Time_value_format", 600, 80)}} - -When a form including a `time` input is submitted, the value is encoded before being included in the form's data. The form's data entry for a time input will always be in the form `name=HH%3Amm`, or `name=HH%3Amm%3Ass` if seconds are included (see [Using the step attribute](#using_the_step_attribute)). - -## Additional attributes - -In addition to the attributes common to all {{HTMLElement("input")}} elements, `time` inputs offer the following attributes. - -> [!NOTE] -> Unlike many data types, time values have a **periodic domain**, meaning that the values reach the highest possible value, then wrap back around to the beginning again. For example, specifying a `min` of `14:00` and a `max` of `2:00` means that the permitted time values start at 2:00 PM, run through midnight to the next day, ending at 2:00 AM. See more in the [making min and max cross midnight](#making_min_and_max_cross_midnight) section of this article. - -### list - -The values of the list attribute is the {{domxref("Element.id", "id")}} of a {{HTMLElement("datalist")}} element located in the same document. The {{HTMLElement("datalist")}} provides a list of predefined values to suggest to the user for this input. Any values in the list that are not compatible with the [`type`](/en-US/docs/Web/HTML/Element/input#type) are not included in the suggested options. The values provided are suggestions, not requirements: users can select from this predefined list or provide a different value. - -### max - -A string indicating the latest time to accept, specified in the same [time value format](#time_value_format) as described above. If the specified string isn't a valid time, no maximum value is set. - -### min - -A string specifying the earliest time to accept, given in the [time value format](#time_value_format) described previously. If the value specified isn't a valid time string, no minimum value is set. - -### readonly - -A Boolean attribute which, if present, means this field cannot be edited by the user. Its `value` can, however, still be changed by JavaScript code directly setting the {{domxref("HTMLInputElement")}} `value` property. - -> [!NOTE] -> Because a read-only field cannot have a value, `required` does not have any effect on inputs with the `readonly` attribute also specified. - -### step - -The `step` attribute is a number that specifies the granularity that the value must adhere to, or the special value `any`, which is described below. Only values which are equal to the basis for stepping ([`min`](#min) if specified, [`value`](/en-US/docs/Web/HTML/Element/input#value) otherwise, and an appropriate default value if neither of those is provided) are valid. - -A string value of `any` means that no stepping is implied, and any value is allowed (barring other constraints, such as [`min`](#min) and [`max`](#max)). - -> [!NOTE] -> When the data entered by the user doesn't adhere to the stepping configuration, the {{Glossary("user agent")}} may round to the nearest valid value, preferring numbers in the positive direction when there are two equally close options. - -For `time` inputs, the value of `step` is given in seconds, with a scaling factor of 1000 (since the underlying numeric value is in milliseconds). The default value of `step` is 60, indicating 60 seconds (or 1 minute, or 60,000 milliseconds). - -When `any` is set as the value for `step`, the default 60 seconds is used, and the seconds value is not displayed in the UI. - -## Using time inputs - -### Basic uses of time - -The most basic use of `<input type="time">` involves a basic `<input>` and {{htmlelement("label")}} element combination, as seen below: - -```html -<form> - <label for="appointment-time">Choose an appointment time: </label> - <input id="appointment-time" type="time" name="appointment-time" /> -</form> -``` - -{{EmbedLiveSample('Basic_uses_of_time', 600, 40)}} - -### Controlling input size - -`<input type="time">` doesn't support form sizing attributes such as [`size`](/en-US/docs/Web/HTML/Element/input#size), since times are always about the same number of characters long. You'll have to resort to [CSS](/en-US/docs/Web/CSS) for sizing needs. - -### Using the step attribute - -You can use the [`step`](/en-US/docs/Web/HTML/Element/input#step) attribute to vary the amount of time jumped whenever the time is incremented or decremented (for example, so the time moves by 10 minutes at a time when clicking the little arrow widgets). - -It takes an integer value defining the number of seconds you want to increment by; the default value is 60 seconds. With this as the default, most user agent time UIs display hours and minutes but not seconds. Including the [`step`](/en-US/docs/Web/HTML/Element/input#step) attribute with any numeric value other than a value divisible by `60` adds seconds to the UI, if the `min` or `max` value has not already caused the seconds to be visible. - -```html -<form> - <label for="appointment-time">Choose an appointment time: </label> - <input id="appointment-time" type="time" name="appointment-time" step="2" /> -</form> -``` - -{{EmbedLiveSample('Using_the_step_attribute', 600, 40)}} - -To specify minutes or hours as a step, specify the number of minutes or hours in seconds, such as 120 for 2 minutes, or 7200 for 2 hours. - -## Validation - -By default, `<input type="time">` does not apply any validation to entered values, other than the user agent's interface generally not allowing you to enter anything other than a time value. This is helpful, but you can't entirely rely on the value to be a proper time string, since it might be an empty string (`""`), which is allowed. - -### Setting maximum and minimum times - -You can use the [`min`](/en-US/docs/Web/HTML/Element/input#min) and [`max`](/en-US/docs/Web/HTML/Element/input#max) attributes to restrict the valid times that can be chosen by the user. In the following example we are setting a minimum time of `12:00` and a maximum time of `18:00`: - -```html -<form> - <label for="appointment-time"> - Choose an appointment time (opening hours 12:00 to 18:00): - </label> - <input - id="appointment-time" - type="time" - name="appointment-time" - min="12:00" - max="18:00" /> - <span class="validity"></span> -</form> -``` - -{{ EmbedLiveSample('Setting_maximum_and_minimum_times', 600, 40) }} - -Here's the CSS used in the above example. Here we make use of the {{cssxref(":valid")}} and {{cssxref(":invalid")}} CSS properties to style the input based on whether the current value is valid. We add an icon as generated content icon on a {{htmlelement("span")}} next to the input. - -```css -div { - margin-bottom: 10px; - position: relative; -} - -input[type="number"] { - width: 100px; -} - -input + span { - padding-right: 30px; -} - -input:invalid + span::after { - position: absolute; - content: "✖"; - padding-left: 5px; -} - -input:valid + span::after { - position: absolute; - content: "✓"; - padding-left: 5px; -} -``` - -The result here is that: - -- Only times between 12:00 and 18:00 will be seen as valid; times outside that range will be denoted as invalid. - -#### Making min and max cross midnight - -By setting a [`min`](/en-US/docs/Web/HTML/Element/input#min) attribute greater than the [`max`](/en-US/docs/Web/HTML/Element/input#max) attribute, the valid time range will wrap around midnight to produce a valid time range. This functionality is not supported by any other input types. - -```js -const input = document.createElement("input"); -input.type = "time"; -input.min = "23:00"; -input.max = "01:00"; -input.value = "23:59"; - -if (input.validity.valid && input.type === "time") { - // <input type=time> reversed range supported -} else { - // <input type=time> reversed range unsupported -} -``` - -### Making times required - -In addition, you can use the [`required`](/en-US/docs/Web/HTML/Element/input#required) attribute to make filling in the time mandatory. Browsers will display an error if you try to submit a time that is outside the set bounds, or an empty time field. - -Let's look at an example; here we've set minimum and maximum times, and also made the field required: - -```html -<form> - <div> - <label for="appointment-time"> - Choose an appointment time (opening hours 12:00 to 18:00): - </label> - <input - id="appointment-time" - type="time" - name="appointment-time" - min="12:00" - max="18:00" - required /> - <span class="validity"></span> - </div> - <div> - <input type="submit" value="Submit form" /> - </div> -</form> -``` - -If you try to submit the form with an incomplete time (or with a time outside the set bounds), the browser displays an error. Try playing with the example now: - -{{ EmbedLiveSample('Making_times_required', 600, 120) }} - -> [!WARNING] -> HTML form validation is _not_ a substitute for scripts that ensure that the entered data is in the proper format. It's far too easy for someone to make adjustments to the HTML that allow them to bypass the validation, or to remove it entirely. It's also possible for someone to bypass your HTML entirely and submit the data directly to your server. If your server-side code fails to validate the data it receives, disaster could strike when improperly-formatted data is submitted (or data which is too large, of the wrong type, and so forth). - -## Examples - -In this example, we create an interface element for choosing time using the native picker created with `<input type="time">`: - -### HTML - -```html -<form> - <label for="appointment-time"> - Choose an appointment time (opening hours 12:00 to 18:00): - </label> - <input - id="appointment-time" - type="time" - name="appointment-time" - min="12:00" - max="18:00" - required /> - <span class="validity"></span> -</form> -``` - -### CSS - -```css -input[type="time"] { - width: 100px; -} - -input + span { - padding-right: 30px; -} - -input:invalid + span::after { - position: absolute; - content: "✖"; - padding-left: 5px; -} - -input:valid + span::after { - position: absolute; - content: "✓"; - padding-left: 5px; -} -``` - -### Result - -{{ EmbedLiveSample('Examples', 600, 140) }} - -## Technical Summary - -<table class="properties"> - <tbody> - <tr> - <td><strong><a href="/en-US/docs/Web/HTML/Element/input#value">Value</a></strong></td> - <td>A string representing a time, or empty.</td> - </tr> - <tr> - <td><strong>Events</strong></td> - <td> - {{domxref("HTMLElement/change_event", "change")}} and - {{domxref("Element/input_event", "input")}} - </td> - </tr> - <tr> - <td><strong>Supported common attributes</strong></td> - <td> - <a href="/en-US/docs/Web/HTML/Element/input#autocomplete"><code>autocomplete</code></a>, - <a href="/en-US/docs/Web/HTML/Element/input#list"><code>list</code></a>, - <a href="/en-US/docs/Web/HTML/Element/input#readonly"><code>readonly</code></a>, - <a href="/en-US/docs/Web/HTML/Element/input#step"><code>step</code></a> - </td> - </tr> - <tr> - <td><strong>IDL attributes</strong></td> - <td> - <a href="/en-US/docs/Web/HTML/Element/input#list"><code>list</code></a>, - <a href="/en-US/docs/Web/HTML/Element/input#value"><code>value</code></a>, - <code>valueAsDate</code>, - <code>valueAsNumber</code> - </td> - </tr> - <tr> - <td><strong>DOM interface</strong></td> - <td><p>{{domxref("HTMLInputElement")}}</p></td> - </tr> - <tr> - <td><strong>Methods</strong></td> - <td> - {{domxref("HTMLInputElement.select", "select()")}}, - {{domxref("HTMLInputElement.stepDown", "stepDown()")}}, - and - {{domxref("HTMLInputElement.stepUp", "stepUp()")}}. - </td> - </tr> - <tr> - <td><strong>Implicit ARIA Role</strong></td> - <td><a href="https://www.w3.org/TR/html-aria/#dfn-no-corresponding-role">no corresponding role</a></td> - </tr> - </tbody> -</table> - -## Specifications - -{{Specifications}} - -## Browser compatibility - -{{Compat}} - -## See also - -- [`<input type="date">`](/en-US/docs/Web/HTML/Element/input/date) -- [`<input type="datetime-local">`](/en-US/docs/Web/HTML/Element/input/datetime-local) -- [`<input type="week">`](/en-US/docs/Web/HTML/Element/input/week) -- [`<input type="month">`](/en-US/docs/Web/HTML/Element/input/month) -- The generic {{HTMLElement("input")}} element and the interface used to manipulate it, {{domxref("HTMLInputElement")}} -- [Date and time formats used in HTML](/en-US/docs/Web/HTML/Date_and_time_formats) -- [Date and Time picker tutorial](/en-US/docs/Learn_web_development/Extensions/Forms/HTML5_input_types#date_and_time_pickers) diff --git a/files/en-us/web/html/element/input/url/index.md b/files/en-us/web/html/element/input/url/index.md deleted file mode 100644 index bd2749d4c7701ed..000000000000000 --- a/files/en-us/web/html/element/input/url/index.md +++ /dev/null @@ -1,427 +0,0 @@ ---- -title: <input type="url"> -slug: Web/HTML/Element/input/url -page-type: html-element -browser-compat: html.elements.input.type_url ---- - -{{HTMLSidebar}} - -{{HTMLElement("input")}} elements of type **`url`** are used to let the user enter and edit a URL. - -{{InteractiveExample("HTML Demo: &lt;input type=&quot;url&quot;&gt;", "tabbed-shorter")}} - -```html interactive-example -<form> - <label for="url">Enter an https:// URL:</label> - <input - type="url" - name="url" - id="url" - placeholder="https://example.com" - pattern="https://.*" - size="30" - required /> -</form> -``` - -```css interactive-example -label { - display: block; - font: - 1rem "Fira Sans", - sans-serif; -} - -input, -label { - margin: 0.4rem 0; -} -``` - -The input value is automatically validated to ensure that it's either empty or a properly-formatted URL before the form can be submitted. The {{cssxref(":valid")}} and {{cssxref(":invalid")}} CSS pseudo-classes are automatically applied as appropriate to visually denote whether the current value of the field is a valid URL or not. - -## Value - -The {{HTMLElement("input")}} element's [`value`](/en-US/docs/Web/HTML/Element/input#value) attribute contains a string that is automatically validated as conforming to URL syntax. More specifically, there are two possible value formats that will pass validation: - -1. An empty string ("") indicates the user did not enter a value or that the value was removed. -2. A single properly-formed absolute URL. This doesn't necessarily mean the URL address exists, but it is at least formatted correctly. An entry matching `urlscheme://rest-of-url` can be valid, even if the `urlscheme` entered doesn't exist. - -See [Validation](#validation) for details on how URLs are validated to ensure that they're formatted properly. - -## Additional attributes - -In addition to the [global attributes](/en-US/docs/Web/HTML/Global_attributes), and the attributes that operate on all {{HTMLElement("input")}} elements regardless of their type, `url` inputs support the following attributes. - -> [!NOTE] -> The [`autocorrect`](/en-US/docs/Web/HTML/Global_attributes/autocorrect) global attribute can be added to url inputs, but the stored state is always `off`. - -### list - -The values of the list attribute is the {{domxref("Element.id", "id")}} of a {{HTMLElement("datalist")}} element located in the same document. The {{HTMLElement("datalist")}} provides a list of predefined values to suggest to the user for this input. Any values in the list that are not compatible with the [`type`](/en-US/docs/Web/HTML/Element/input#type) are not included in the suggested options. The values provided are suggestions, not requirements: users can select from this predefined list or provide a different value. - -### maxlength - -The maximum string length (measured in UTF-16 code units) that the user can enter into the `url` input. This must be an integer value of `0` or higher. If no `maxlength` is specified, or an invalid value is specified, the `url` input has no maximum length. This value must also be greater than or equal to the value of `minlength`. - -The input will fail [constraint validation](/en-US/docs/Web/HTML/Constraint_validation) if the length of the text value of the field is greater than `maxlength` UTF-16 code units long. Constraint validation is only applied when the value is changed by the user. - -### minlength - -The minimum string length (measured in UTF-16 code units) that the user can enter into the `url` input. This must be a non-negative integer value smaller than or equal to the value specified by `maxlength`. If no `minlength` is specified, or an invalid value is specified, the `url` input has no minimum length. - -The input will fail [constraint validation](/en-US/docs/Web/HTML/Constraint_validation) if the length of the text entered into the field is fewer than `minlength` UTF-16 code units long. Constraint validation is only applied when the value is changed by the user. - -### pattern - -The `pattern` attribute, when specified, is a regular expression that the input's [`value`](/en-US/docs/Web/HTML/Element/input#value) must match for the value to pass [constraint validation](/en-US/docs/Web/HTML/Constraint_validation). It must be a valid JavaScript regular expression, as used by the {{jsxref("RegExp")}} type, and as documented in our [guide on regular expressions](/en-US/docs/Web/JavaScript/Guide/Regular_expressions); the `'u'` flag is specified when compiling the regular expression so that the pattern is treated as a sequence of Unicode code points, instead of as {{Glossary("ASCII")}}. No forward slashes should be specified around the pattern text. - -If the specified pattern is not specified or is invalid, no regular expression is applied and this attribute is ignored completely. - -> [!NOTE] -> Use the [`title`](/en-US/docs/Web/HTML/Element/input#title) attribute to specify text that most browsers will display as a tooltip to explain what the requirements are to match the pattern. You should also include other explanatory text nearby. - -See the section [Pattern validation](#pattern_validation) for details and an example. - -### placeholder - -The `placeholder` attribute is a string that provides a brief hint to the user as to what kind of information is expected in the field. It should be a word or short phrase that demonstrates the expected type of data, rather than an explanatory message. The text _must not_ include carriage returns or line feeds. - -If the control's content has one directionality ({{Glossary("LTR")}} or {{Glossary("RTL")}}) but needs to present the placeholder in the opposite directionality, you can use Unicode bidirectional algorithm formatting characters to override directionality within the placeholder; see [How to use Unicode controls for bidi text](https://www.w3.org/International/questions/qa-bidi-unicode-controls) for more information. - -> [!NOTE] -> Avoid using the `placeholder` attribute if you can. It is not as semantically useful as other ways to explain your form, and can cause unexpected technical issues with your content. See [`<input>` labels](/en-US/docs/Web/HTML/Element/input#labels) for more information. - -### readonly - -The [`readonly`](/en-US/docs/Web/HTML/Attributes/readonly) Boolean attribute, if present, means this field cannot be edited by the user. Its `value` can, however, still be changed by JavaScript code directly setting the {{domxref("HTMLInputElement")}} `value` property. - -> [!NOTE] -> Because a read-only field cannot have a value, [`required`](/en-US/docs/Web/HTML/Attributes/required) does not have any effect on inputs with the `readonly` attribute also specified. - -### size - -The `size` attribute is a numeric value indicating how many characters wide the input field should be. The value must be a number greater than zero, and the default value is 20. Since character widths vary, this may or may not be exact and should not be relied upon to be so; the resulting input may be narrower or wider than the specified number of characters, depending on the characters and the font ({{cssxref("font")}} settings in use). - -This does _not_ set a limit on how many characters the user can enter into the field. It only specifies approximately how many can be seen at a time. To set an upper limit on the length of the input data, use the [`maxlength`](#maxlength) attribute. - -### spellcheck - -The [`spellcheck`](/en-US/docs/Web/HTML/Global_attributes/spellcheck) global attribute is used to indicate whether to enable spell-checking for an element. It can be used on any editable content, but here we consider specifics related to the use of `spellcheck` on {{HTMLElement("input")}} elements. The permitted values for `spellcheck` are: - -- `false` - - : Disable spell-checking for this element. -- `true` - - : Enable spell-checking for this element. -- "" (empty string) or no value - - : Follow the element's default behavior for spell-checking. This may be based upon a parent's `spellcheck` setting or other factors. - -An input field can have spell-checking enabled if it doesn't have the [readonly](#readonly) attribute set and is not disabled. - -The value returned by reading `spellcheck` may not reflect the actual state of spell-checking within a control if the {{Glossary("user agent", "user agent's")}} preferences override the setting. - -## Using URL inputs - -When you create a URL input with the proper `type` value, `url`, you get automatic validation that the entered text is at least in the correct form to potentially be a legitimate URL. This can help avoid cases in which the user mistypes their website's address, or provides an invalid one. - -It's important, however, to note that this is not enough to ensure that the specified text is a URL which actually exists, corresponds to the user of the site, or is acceptable in any other way. It ensures that the value of the field is properly formatted to be a URL. - -> [!NOTE] -> A user can tinker with your HTML behind the scenes, so your site _must not_ use this validation for any security purposes. You _must_ verify the URL on the server-side of any transaction in which the provided text may have any security implications of any kind. - -### A basic URL input - -This element is implemented as a standard text input field with basic validation features. In its most basic form, a URL input can be implemented like this: - -```html -<input id="myURL" name="myURL" type="url" /> -``` - -{{ EmbedLiveSample('A_basic_URL_input', 600, 40) }} - -Notice that it's considered valid when empty and when a single validly-formatted URL address is entered, but is otherwise not considered valid. By adding the [`required`](/en-US/docs/Web/HTML/Element/input#required) attribute, only properly-formed URLs are allowed; the input is no longer considered valid when empty. - -There is nothing magical going on here. Submitting this form would cause the following data to be sent to the server: `myURL=http%3A%2F%2Fwww.example.com`. Note how characters are escaped as necessary. - -### Placeholders - -Sometimes it's helpful to offer an in-context hint as to what form the input data should take. This can be especially important if the page design doesn't offer descriptive labels for each {{HTMLElement("input")}}. This is where **placeholders** come in. A placeholder is a value that demonstrates the form the `value` should take by presenting an example of a valid value, which is displayed inside the edit box when the element's `value` is "". Once data is entered into the box, the placeholder disappears; if the box is emptied, the placeholder reappears. - -Here, we have a `url` input with the placeholder `http://www.example.com`. Note how the placeholder disappears and reappears as you manipulate the contents of the edit field. - -```html -<input - id="myURL" - name="myURL" - type="url" - placeholder="http://www.example.com" /> -``` - -{{ EmbedLiveSample('Placeholders', 600, 40) }} - -### Controlling the input size - -You can control both the physical length of the input box and the minimum and maximum lengths allowed for the input text. - -#### Physical input element size - -The physical size of the input box can be controlled using the [`size`](/en-US/docs/Web/HTML/Element/input#size) attribute. With it, you can specify the number of characters the input box can display at a time. In this example, for instance, the `url` edit box is 30 characters wide: - -```html -<input id="myURL" name="myURL" type="url" size="30" /> -``` - -{{ EmbedLiveSample('Physical_input_element_size', 600, 40) }} - -#### Element value length - -The `size` is separate from the length limitation on the entered URL itself. You can specify a minimum length, in characters, for the entered URL using the [`minlength`](/en-US/docs/Web/HTML/Element/input#minlength) attribute; similarly, use [`maxlength`](/en-US/docs/Web/HTML/Element/input#maxlength) to set the maximum length of the entered URL. If `maxLength` exceeds `size`, the input box's contents will scroll as needed to show the current selection or insertion point as the content is manipulated. - -The example below creates a 30-character wide URL address entry box, requiring that the contents be no shorter than 10 characters and no longer than 80 characters. - -```html -<input - id="myURL" - name="myURL" - type="url" - size="30" - minlength="10" - maxlength="80" /> -``` - -{{EmbedLiveSample("Element_value_length", 600, 40) }} - -> [!NOTE] -> These attributes also affect validation; a value shorter or longer than the specified minimum/maximum lengths will be classified as invalid; in addition most browsers will refuse to let the user enter a value longer than the specified maximum length. - -### Providing default options - -#### Providing a single default using the value attribute - -As always, you can provide a default value for a `url` input box by setting its [`value`](/en-US/docs/Web/HTML/Element/input#value) attribute: - -```html -<input id="myURL" name="myURL" type="url" value="http://www.example.com" /> -``` - -{{EmbedLiveSample("Providing_a_single_default_using_the_value_attribute", 600, 40)}} - -#### Offering suggested values - -Taking it a step further, you can provide a list of default options from which the user can select by specifying the [`list`](/en-US/docs/Web/HTML/Element/input#list) attribute. This doesn't limit the user to those options, but does allow them to select commonly-used URLs more quickly. This also offers hints to [`autocomplete`](/en-US/docs/Web/HTML/Element/input#autocomplete). The `list` attribute specifies the ID of a {{HTMLElement("datalist")}}, which in turn contains one {{HTMLElement("option")}} element per suggested value; each `option`'s `value` is the corresponding suggested value for the URL entry box. - -```html -<input id="myURL" name="myURL" type="url" list="defaultURLs" /> - -<datalist id="defaultURLs"> - <option value="https://developer.mozilla.org/"></option> - <option value="http://www.google.com/"></option> - <option value="http://www.microsoft.com/"></option> - <option value="https://www.mozilla.org/"></option> - <option value="http://w3.org/"></option> -</datalist> -``` - -{{EmbedLiveSample("Offering_suggested_values", 600, 40)}} - -With the {{HTMLElement("datalist")}} element and its {{HTMLElement("option")}}s in place, the browser will offer the specified values as potential values for the URL; this is typically presented as a popup or drop-down menu containing the suggestions. While the specific user experience may vary from one browser to another, typically clicking in the edit box presents a drop-down of the suggested URLs. Then, as the user types, the list is adjusted to show only matching values. Each typed character narrows down the list until the user makes a selection or types a custom value. - -#### Using labels for suggested values - -You can opt to include the [`label`](/en-US/docs/Web/HTML/Element/option#label) attribute on one or all of your `<option>` elements to provide textual labels. Some browsers may display only the labels, while others may display both the label and the URL. - -```html -<input id="myURL" name="myURL" type="url" list="defaultURLs" /> - -<datalist id="defaultURLs"> - <option value="https://developer.mozilla.org/" label="MDN Web Docs"></option> - <option value="http://www.google.com/" label="Google"></option> - <option value="http://www.microsoft.com/" label="Microsoft"></option> - <option value="https://www.mozilla.org/" label="Mozilla"></option> - <option value="http://w3.org/" label="W3C"></option> -</datalist> -``` - -{{EmbedLiveSample("Using_labels_for_suggested_values", 600, 40)}} - -## Validation - -There are two levels of content validation available for `url` inputs. First, there's the standard level of validation offered to all {{HTMLElement("input")}}s, which automatically ensures that the contents meet the requirements to be a valid URL. But there's also the option to add additional filtering to ensure that your own specialized needs are met, if you have any. - -> [!WARNING] -> HTML form validation is _not_ a substitute for scripts that ensure that the entered data is in the proper format. It's far too easy for someone to make adjustments to the HTML that allow them to bypass the validation, or to remove it entirely. It's also possible for someone to bypass your HTML entirely and submit the data directly to your server. If your server-side code fails to validate the data it receives, disaster could strike when improperly-formatted data (or data which is too large, is of the wrong type, and so forth) is entered into your database. - -### Basic validation - -Browsers that support the `url` input type automatically provide validation to ensure that only text that matches the standard format for URLs is entered into the input box. - -The syntax of a URL is fairly intricate. It's defined by WHATWG's [URL Living Standard](https://url.spec.whatwg.org/) and is described for newcomers in our article [What is a URL?](/en-US/docs/Learn_web_development/Howto/Web_mechanics/What_is_a_URL) - -### Making a URL required - -As mentioned earlier, to make a URL entry required before the form can be submitted (you can't leave the field blank), you just need to include the [`required`](/en-US/docs/Web/HTML/Element/input#required) attribute on the input. - -```html -<form> - <input id="myURL" name="myURL" type="url" required /> - <button>Submit</button> -</form> -``` - -{{EmbedLiveSample("Making_a_URL_required", 600, 40)}} - -Try submitting the above form with no value entered to see what happens. - -### Pattern validation - -If you need the entered URL to be restricted further than just "any string that looks like a URL," you can use the [`pattern`](/en-US/docs/Web/HTML/Element/input#pattern) attribute to specify a {{Glossary("regular expression")}} the value must match for the value to be valid. - -For example, let's say you're building a support page for employees of Myco, Inc. which will let them contact their IT department for help if one of their pages has a problem. In our simplified form, the user needs to enter the URL of the page that has a problem, and a message describing what is wrong. But we want the URL to only successfully validate if the entered URL is in a Myco domain. - -Since inputs of type `url` validate against both the standard URL validation _and_ the specified [`pattern`](/en-US/docs/Web/HTML/Element/input#pattern), you can implement this with a regular expression. Let's see how: - -```css hidden -div { - margin-bottom: 10px; - position: relative; -} - -input[type="number"] { - width: 100px; -} - -input + span { - padding-right: 30px; -} - -input:invalid + span::after { - position: absolute; - content: "✖"; - padding-left: 5px; -} - -input:valid + span::after { - position: absolute; - content: "✓"; - padding-left: 5px; -} -``` - -```html -<form> - <div> - <label for="myURL">Enter the problem website address:</label> - <input - id="myURL" - name="myURL" - type="url" - required - pattern=".*\.myco\..*" - title="The URL must be in a Myco domain" /> - <span class="validity"></span> - </div> - <div> - <label for="myComment">What is the problem?</label> - <input id="myComment" name="myComment" type="text" required /> - <span class="validity"></span> - </div> - <div> - <button>Submit</button> - </div> -</form> -``` - -{{EmbedLiveSample("Pattern_validation", 700, 150)}} - -First of all, the [`required`](/en-US/docs/Web/HTML/Element/input#required) attribute is specified, making it mandatory that a valid URL be provided. - -Second, in the `url` input, we set `pattern` to `".*\.myco\..*"`. This regular expression requests a string that has any number of characters, followed by a dot, followed by "myco", followed by a dot, followed by any number of characters. Because the browser runs both the standard URL filter _and_ our custom pattern against the specified text, we wind up with a validation that says "make sure this is a valid URL, and also in a Myco domain." - -This isn't perfect, but it is good enough for this basic demo's requirements. - -It's advisable to use the [`title`](/en-US/docs/Web/HTML/Global_attributes/title) attribute along with `pattern`. If you do, the `title` _must_ describe the pattern; it should explain what format the data should take on, rather than any other information. That's because the `title` may be displayed or spoken as part of a validation error message. For example, the browser might present the message "The entered text doesn't match the required pattern." followed by your specified `title`. If your `title` is something like "URL", the result would be the message "The entered text doesn't match the required pattern. URL", which is not a good user experience. - -That's why, instead, we specify the string "The URL must be in a myco domain". By doing that, the resulting full error message might be something like "The entered text doesn't match the required pattern. The URL should be in a myco domain." - -> [!NOTE] -> If you run into trouble while writing your validation regular expressions and they're not working properly, check your browser's console; there may be helpful error messages there to aid you in solving the problem. - -## Examples - -There's not much else to say about `url` type inputs; check the [Pattern validation](#pattern_validation) and [Using URL inputs](#using_url_inputs) sections for numerous examples. - -You can also find our [pattern validation example on GitHub](https://github.com/mdn/learning-area/blob/main/html/forms/url-example/index.html) (see it [running live also](https://mdn.github.io/learning-area/html/forms/url-example/)). - -## Technical summary - -<table class="properties"> - <tbody> - <tr> - <td><strong><a href="#value">Value</a></strong></td> - <td>A string representing a URL, or empty</td> - </tr> - <tr> - <td><strong>Events</strong></td> - <td> - {{domxref("HTMLElement/change_event", "change")}} and - {{domxref("Element/input_event", "input")}} - </td> - </tr> - <tr> - <td><strong>Supported Common Attributes</strong></td> - <td> - <a href="/en-US/docs/Web/HTML/Element/input#autocomplete"><code>autocomplete</code></a>, - <a href="/en-US/docs/Web/HTML/Element/input#list"><code>list</code></a>, - <a href="/en-US/docs/Web/HTML/Element/input#maxlength"><code>maxlength</code></a>, - <a href="/en-US/docs/Web/HTML/Element/input#minlength"><code>minlength</code></a>, - <a href="/en-US/docs/Web/HTML/Element/input#pattern"><code>pattern</code></a>, - <a href="/en-US/docs/Web/HTML/Element/input#placeholder"><code>placeholder</code></a>, - <a href="/en-US/docs/Web/HTML/Element/input#readonly"><code>readonly</code></a>, - <a href="/en-US/docs/Web/HTML/Element/input#required"><code>required</code></a> and - <a href="/en-US/docs/Web/HTML/Element/input#size"><code>size</code></a> - </td> - </tr> - <tr> - <td><strong>IDL attributes</strong></td> - <td> - <code>list</code>, <code>value</code>, <code>selectionEnd</code>, - <code>selectionDirection</code> - </td> - </tr> - <tr> - <td><strong>DOM interface</strong></td> - <td><p>{{domxref("HTMLInputElement")}}</p></td> - </tr> - <tr> - <td><strong>Methods</strong></td> - <td> - {{domxref("HTMLInputElement.select", "select()")}}, - {{domxref("HTMLInputElement.setRangeText", "setRangeText()")}} - and - {{domxref("HTMLInputElement.setSelectionRange", "setSelectionRange()")}}. - </td> - </tr> - <tr> - <td><strong>Implicit ARIA Role</strong></td> - <td>with no <code>list</code> attribute: - <code><a href="/en-US/docs/Web/Accessibility/ARIA/Roles/textbox_role">textbox</a></code></td> - <td>with <code>list</code> attribute: <code><a href="/en-US/docs/Web/Accessibility/ARIA/Roles/combobox_role">combobox</a></code></td> - </tr> - </tbody> -</table> - -## Specifications - -{{Specifications}} - -## Browser compatibility - -{{Compat}} - -## See also - -- [HTML forms guide](/en-US/docs/Learn_web_development/Extensions/Forms) -- {{HTMLElement("input")}} -- [`<input type="tel">`](/en-US/docs/Web/HTML/Element/input/tel) -- [`<input type="email">`](/en-US/docs/Web/HTML/Element/input/email) diff --git a/files/en-us/web/html/element/input/week/index.md b/files/en-us/web/html/element/input/week/index.md deleted file mode 100644 index 35aa0f36ed1c6ec..000000000000000 --- a/files/en-us/web/html/element/input/week/index.md +++ /dev/null @@ -1,417 +0,0 @@ ---- -title: <input type="week"> -slug: Web/HTML/Element/input/week -page-type: html-element -browser-compat: html.elements.input.type_week ---- - -{{HTMLSidebar}} - -{{HTMLElement("input")}} elements of type **`week`** create input fields allowing easy entry of a year plus the [ISO 8601 week number](https://en.wikipedia.org/wiki/ISO_8601#Week_dates) during that year (i.e., week 1 to [52 or 53](https://en.wikipedia.org/wiki/ISO_8601#Week_dates)). - -{{InteractiveExample("HTML Demo: &lt;input type=&quot;week&quot;&gt;", "tabbed-shorter")}} - -```html interactive-example -<label for="camp-week">Choose a week in May or June:</label> - -<input - type="week" - name="week" - id="camp-week" - min="2018-W18" - max="2018-W26" - required /> -``` - -```css interactive-example -label { - display: block; - font: - 1rem "Fira Sans", - sans-serif; -} - -input, -label { - margin: 0.4rem 0; -} -``` - -The control's user interface varies from browser to browser; cross-browser support is currently a bit limited, with only Chrome/Opera and Microsoft Edge supporting it at this time. In non-supporting browsers, the control degrades gracefully to function identically to [`<input type="text">`](/en-US/docs/Web/HTML/Element/input/text). - -![An input reading 'week 01, 2017'. The background of the 2017 is the same blue as the focus ring. There are 3 icons in the input: x or clear, a spinner with small up and down arrows, and a larger down arrow. A calendar is a pop-up below the input set to January 2017. The first column of the calendar is the week: 52, 1, 2, 3, 4, 5. the full month calendar is to the right of that. The row with Week 1 and January 2 to 8 is highlighted. On the same line as the month, there are buttons to move right and left for the next and previous months.](week-control-chrome.png) - -## Value - -A string representing the value of the week/year entered into the input. The format of the date and time value used by this input type is described in [Week strings](/en-US/docs/Web/HTML/Date_and_time_formats#week_strings). - -You can set a default value for the input by including a value inside the [`value`](/en-US/docs/Web/HTML/Element/input#value) attribute, like so: - -```html -<label for="week">What week would you like to start?</label> -<input id="week" type="week" name="week" value="2017-W01" /> -``` - -{{EmbedLiveSample('Value', 600, 60)}} - -One thing to note is that the displayed format may differ from the actual `value`, which is always formatted `yyyy-Www`. When the above value is submitted to the server, for example, browsers may display it as `Week 01, 2017`, but the submitted value will always look like `week=2017-W01`. - -You can also get and set the value in JavaScript using the input element's {{domxref("HTMLInputElement.value", "value")}} property, for example: - -```js -const weekControl = document.querySelector('input[type="week"]'); -weekControl.value = "2017-W45"; -``` - -## Additional attributes - -In addition to the attributes common to {{HTMLElement("input")}} elements, week inputs offer the following attributes. - -### max - -The latest (time-wise) year and week number, in the string format discussed in the [Value](#value) section above, to accept. If the [`value`](/en-US/docs/Web/HTML/Element/input#value) entered into the element exceeds this, the element fails [constraint validation](/en-US/docs/Web/HTML/Constraint_validation). If the value of the `max` attribute isn't a valid week string, then the element has no maximum value. - -This value must be greater than or equal to the year and week specified by the `min` attribute. - -### min - -The earliest year and week to accept. If the [`value`](/en-US/docs/Web/HTML/Element/input#value) of the element is less than this, the element fails [constraint validation](/en-US/docs/Web/HTML/Constraint_validation). If a value is specified for `min` that isn't a valid week string, the input has no minimum value. - -This value must be less than or equal to the value of the `max` attribute. - -### readonly - -A Boolean attribute which, if present, means this field cannot be edited by the user. Its `value` can, however, still be changed by JavaScript code directly setting the {{domxref("HTMLInputElement")}} `value` property. - -> [!NOTE] -> Because a read-only field cannot have a value, `required` does not have any effect on inputs with the `readonly` attribute also specified. - -### step - -The `step` attribute is a number that specifies the granularity that the value must adhere to, or the special value `any`, which is described below. Only values which are equal to the basis for stepping ([`min`](#min) if specified, [`value`](/en-US/docs/Web/HTML/Element/input#value) otherwise, and an appropriate default value if neither of those is provided) are valid. - -A string value of `any` means that no stepping is implied, and any value is allowed (barring other constraints, such as [`min`](#min) and [`max`](#max)). - -> [!NOTE] -> When the data entered by the user doesn't adhere to the stepping configuration, the {{Glossary("user agent")}} may round to the nearest valid value, preferring numbers in the positive direction when there are two equally close options. - -For `week` inputs, the value of `step` is given in weeks, with a scaling factor of 604,800,000 (since the underlying numeric value is in milliseconds). The default value of `step` is 1, indicating 1week. The default stepping base is -259,200,000, which is the beginning of the first week of 1970 (`"1970-W01"`). - -_At this time, it's unclear what a value of `"any"` means for `step` when used with `week` inputs. This will be updated as soon as that information is determined._ - -## Using week inputs - -Week inputs sound convenient at first glance, since they provide an easy UI for choosing weeks, and they normalize the data format sent to the server, regardless of the user's browser or locale. However, there are issues with `<input type="week">` because browser support is not guaranteed across all browsers. - -We'll look at basic and more complex uses of `<input type="week">`, then offer advice on mitigating the browser support issue later on (see [Handling browser support](#handling_browser_support)). - -### Basic uses of week - -The most basic use of `<input type="week">` involves a basic `<input>` and {{htmlelement("label")}} element combination, as seen below: - -```html -<form> - <label for="week">What week would you like to start?</label> - <input id="week" type="week" name="week" /> -</form> -``` - -{{EmbedLiveSample('Basic_uses_of_week', 600, 40)}} - -### Controlling input size - -`<input type="week">` doesn't support form sizing attributes such as [`size`](/en-US/docs/Web/HTML/Element/input#size). You'll have to resort to [CSS](/en-US/docs/Web/CSS) for sizing needs. - -### Using the step attribute - -You should be able to use the [`step`](/en-US/docs/Web/HTML/Element/input#step) attribute to vary the number of weeks jumped whenever they are incremented or decremented, however it doesn't seem to have any effect on supporting browsers. - -## Validation - -By default, `<input type="week">` does not apply any validation to entered values. The UI implementations generally don't let you specify anything that isn't a valid week/year, which is helpful, but it's still possible to submit with the field empty, and you might want to restrict the range of choosable weeks. - -### Setting maximum and minimum weeks - -You can use the [`min`](/en-US/docs/Web/HTML/Element/input#min) and [`max`](/en-US/docs/Web/HTML/Element/input#max) attributes to restrict the valid weeks that can be chosen by the user. In the following example we are setting a minimum value of `Week 01, 2017` and a maximum value of `Week 52, 2017`: - -```html -<form> - <label for="week">What week would you like to start?</label> - <input id="week" type="week" name="week" min="2017-W01" max="2017-W52" /> - <span class="validity"></span> -</form> -``` - -{{EmbedLiveSample('Setting_maximum_and_minimum_weeks', 600, 40)}} - -Here's the CSS used in the above example. Here we make use of the {{cssxref(":valid")}} and {{cssxref(":invalid")}} CSS properties to style the input based on whether the current value is valid. We had to put the icons on a {{htmlelement("span")}} next to the input, not on the input itself, because in Chrome the generated content is placed inside the form control, and can't be styled or shown effectively. - -```css -div { - margin-bottom: 10px; - position: relative; -} - -input[type="number"] { - width: 100px; -} - -input + span { - padding-right: 30px; -} - -input:invalid + span::after { - position: absolute; - content: "✖"; - padding-left: 5px; -} - -input:valid + span::after { - position: absolute; - content: "✓"; - padding-left: 5px; -} -``` - -The result here is that only weeks between W01 and W52 in 2017 will be seen as valid and be selectable in supporting browsers. - -### Making week values required - -In addition you can use the [`required`](/en-US/docs/Web/HTML/Element/input#required) attribute to make filling in the week mandatory. As a result, supporting browsers will display an error if you try to submit an empty week field. - -Let's look at an example; here we've set minimum and maximum weeks, and also made the field required: - -```html -<form> - <div> - <label for="week">What week would you like to start?</label> - <input - id="week" - type="week" - name="week" - min="2017-W01" - max="2017-W52" - required /> - <span class="validity"></span> - </div> - <div> - <input type="submit" value="Submit form" /> - </div> -</form> -``` - -If you try to submit the form with no value, the browser displays an error. Try playing with the example now: - -{{EmbedLiveSample('Making_week_values_required', 600, 120)}} - -Here is a screenshot for those of you who aren't using a supporting browser: - -![The week form control has two dashes where the week number should be. A popup with a yellow warning symbol and a 'Please fill out this field' is emanating from the two dashes, which are highlighted in blue, the same blue as the input's focus ring.](week-validation-chrome.png) - -> [!WARNING] -> HTML form validation is _not_ a substitute for scripts that ensure that the entered data is in the proper format. It's far too easy for someone to make adjustments to the HTML that allow them to bypass the validation, or to remove it entirely. It's also possible for someone to bypass your HTML entirely and submit the data directly to your server. If your server-side code fails to validate the data it receives, disaster could strike when improperly-formatted data is submitted (or data which is too large, of the wrong type, and so forth). - -## Handling browser support - -As mentioned above, the major problem with using week inputs right now is browser support: Safari and Firefox don't support it on desktop, and old versions of IE don't support it. - -Mobile platforms such as Android and iOS make perfect use of such input types, providing specialist UI controls that make it really easy to select values in a touchscreen environment. For example, the `week` picker on Chrome for Android looks like this: - -![A modal popup. The header reads 'set week'. There are two columns: the left has 36 in the middle at full opacity, with 35 above it and 37 below being semi-opaque. On the right side, 2017 is fully opaque. There are no other options. Three text links or buttons on the bottom include 'clear' on the 'left' and 'cancel' and 'set' on the right.](week-chrome-android.png) - -Non-supporting browsers gracefully degrade to a text input, but this creates problems both in terms of consistency of user interface (the presented control will be different), and data handling. - -The second problem is the more serious. As mentioned earlier, with a `week` input the actual value is always normalized to the format `yyyy-Www`. When the browser falls back to a generic text input, there's nothing to guide the user toward correctly formatting the input (and it's certainly not intuitive). There are multiple ways in which people could write week values; for example: - -- `Week 1 2017` -- `Jan 2-8 2017` -- `2017-W01` -- etc. - -The best way to deal with week/years in forms in a cross-browser way at the moment is to get the user to enter the week number and year in separate controls ({{htmlelement("select")}} elements being popular; see below for an example), or use JavaScript libraries such as [jQuery date picker](https://jqueryui.com/datepicker/). - -## Examples - -In this example we create two sets of UI elements for choosing weeks: a native picker created using `<input type="week">`, and a set of two {{htmlelement("select")}} elements for choosing weeks/years in older browsers that don't support the `week` input type. - -{{EmbedLiveSample('Examples', 600, 140)}} - -The HTML looks like so: - -```html -<form> - <div class="nativeWeekPicker"> - <label for="week">What week would you like to start?</label> - <input - id="week" - type="week" - name="week" - min="2017-W01" - max="2018-W52" - required /> - <span class="validity"></span> - </div> - <p class="fallbackLabel">What week would you like to start?</p> - <div class="fallbackWeekPicker"> - <div> - <span> - <label for="week">Week:</label> - <select id="fallbackWeek" name="week"></select> - </span> - <span> - <label for="year">Year:</label> - <select id="year" name="year"> - <option value="2017" selected>2017</option> - <option value="2018">2018</option> - </select> - </span> - </div> - </div> -</form> -``` - -The week values are dynamically generated by the JavaScript code below. - -```css hidden -div { - margin-bottom: 10px; - position: relative; -} - -input[type="number"] { - width: 100px; -} - -input + span { - padding-right: 30px; -} - -input:invalid + span::after { - position: absolute; - content: "✖"; - padding-left: 5px; -} - -input:valid + span::after { - position: absolute; - content: "✓"; - padding-left: 5px; -} -``` - -The other part of the code that may be of interest is the feature detection code. To detect whether the browser supports `<input type="week">`, we create a new {{htmlelement("input")}} element, try setting its `type` to `week`, then immediately check what its `type` is set to. Non-supporting browsers will return `text`, because the `week` type falls back to type `text`. If `<input type="week">` is not supported, we hide the native picker and show the fallback picker UI ({{htmlelement("select")}}s) instead. - -```js -// Get UI elements -const nativePicker = document.querySelector(".nativeWeekPicker"); -const fallbackPicker = document.querySelector(".fallbackWeekPicker"); -const fallbackLabel = document.querySelector(".fallbackLabel"); - -const yearSelect = document.querySelector("#year"); -const weekSelect = document.querySelector("#fallbackWeek"); - -// Hide fallback initially -fallbackPicker.style.display = "none"; -fallbackLabel.style.display = "none"; - -// Test whether a new date input falls back to a text input or not -const test = document.createElement("input"); - -try { - test.type = "week"; -} catch (e) { - console.log(e.description); -} - -// If it does, run the code inside the if () {} block -if (test.type === "text") { - // Hide the native picker and show the fallback - nativePicker.style.display = "none"; - fallbackPicker.style.display = "block"; - fallbackLabel.style.display = "block"; - - // populate the weeks dynamically - populateWeeks(); -} - -function populateWeeks() { - // Populate the week select with 52 weeks - for (let i = 1; i <= 52; i++) { - const option = document.createElement("option"); - option.textContent = i < 10 ? `0${i}` : i; - weekSelect.appendChild(option); - } -} -``` - -> [!NOTE] -> Remember that some years have 53 weeks in them (see [Weeks per year](https://en.wikipedia.org/wiki/ISO_week_date#Weeks_per_year))! You'll need to take this into consideration when developing production apps. - -## Technical summary - -<table class="properties"> - <tbody> - <tr> - <td><strong><a href="#value">Value</a></strong></td> - <td> - A string representing a week and year, or - empty - </td> - </tr> - <tr> - <td><strong>Events</strong></td> - <td> - {{domxref("HTMLElement/change_event", "change")}} and - {{domxref("Element/input_event", "input")}} - </td> - </tr> - <tr> - <td><strong>Supported common attributes</strong></td> - <td> - <a href="/en-US/docs/Web/HTML/Element/input#autocomplete"><code>autocomplete</code></a>, - <a href="/en-US/docs/Web/HTML/Element/input#list"><code>list</code></a>, - <a href="/en-US/docs/Web/HTML/Element/input#readonly"><code>readonly</code></a>, - <a href="/en-US/docs/Web/HTML/Element/input#step"><code>step</code></a> - </td> - </tr> - <tr> - <td><strong>IDL attributes</strong></td> - <td> - <a href="/en-US/docs/Web/HTML/Element/input#list"><code>list</code></a>, - <a href="/en-US/docs/Web/HTML/Element/input#value"><code>value</code></a>, - <code>valueAsDate</code>, - <code>valueAsNumber</code> - </td> - </tr> - <tr> - <td><strong>DOM interface</strong></td> - <td><p>{{domxref("HTMLInputElement")}}</p></td> - </tr> - <tr> - <td><strong>Methods</strong></td> - <td> - {{domxref("HTMLInputElement.select", "select()")}}, - {{domxref("HTMLInputElement.stepDown", "stepDown()")}}, - and {{domxref("HTMLInputElement.stepUp", "stepUp()")}} - </td> - </tr> - <tr> - <td><strong>Implicit ARIA Role</strong></td> - <td><a href="https://www.w3.org/TR/html-aria/#dfn-no-corresponding-role">no corresponding role</a></td> - </tr> - </tbody> -</table> - -## Specifications - -{{Specifications}} - -## Browser compatibility - -{{Compat}} - -## See also - -- The generic {{HTMLElement("input")}} element and the interface used to manipulate it, {{domxref("HTMLInputElement")}} -- [Date and time formats used in HTML](/en-US/docs/Web/HTML/Date_and_time_formats) -- [`<input type="datetime-local">`](/en-US/docs/Web/HTML/Element/input/datetime-local), [`<input type="date">`](/en-US/docs/Web/HTML/Element/input/date), [`<input type="time">`](/en-US/docs/Web/HTML/Element/input/time), and [`<input type="month">`](/en-US/docs/Web/HTML/Element/input/month) diff --git a/files/en-us/web/html/element/ins/index.md b/files/en-us/web/html/element/ins/index.md deleted file mode 100644 index 25ea7e2161434e4..000000000000000 --- a/files/en-us/web/html/element/ins/index.md +++ /dev/null @@ -1,182 +0,0 @@ ---- -title: "<ins>: The Inserted Text element" -slug: Web/HTML/Element/ins -page-type: html-element -browser-compat: html.elements.ins ---- - -{{HTMLSidebar}} - -The **`<ins>`** [HTML](/en-US/docs/Web/HTML) element represents a range of text that has been added to a document. You can use the {{HTMLElement("del")}} element to similarly represent a range of text that has been deleted from the document. - -{{InteractiveExample("HTML Demo: &lt;ins&gt;", "tabbed-standard")}} - -```html interactive-example -<p>&ldquo;You're late!&rdquo;</p> -<del> - <p>&ldquo;I apologize for the delay.&rdquo;</p> -</del> -<ins cite="../how-to-be-a-wizard.html" datetime="2018-05"> - <p>&ldquo;A wizard is never late &hellip;&rdquo;</p> -</ins> -``` - -```css interactive-example -del, -ins { - display: block; - text-decoration: none; - position: relative; -} - -del { - background-color: #fbb; -} - -ins { - background-color: #d4fcbc; -} - -del::before, -ins::before { - position: absolute; - left: 0.5rem; - font-family: monospace; -} - -del::before { - content: "−"; -} - -ins::before { - content: "+"; -} - -p { - margin: 0 1.8rem 0; - font-family: Georgia, serif; - font-size: 1rem; -} -``` - -## Attributes - -This element includes the [global attributes](/en-US/docs/Web/HTML/Global_attributes). - -- `cite` - - : This attribute defines the URI of a resource that explains the change, such as a link to meeting minutes or a ticket in a troubleshooting system. -- `datetime` - - : This attribute indicates the time and date of the change and must be a valid date with an optional time string. If the value cannot be parsed as a date with an optional time string, the element does not have an associated timestamp. For the format of the string without a time, see [Format of a valid date string](/en-US/docs/Web/HTML/Date_and_time_formats#date_strings). The format of the string if it includes both date and time is covered in [Format of a valid local date and time string](/en-US/docs/Web/HTML/Date_and_time_formats#local_date_and_time_strings). - -## Accessibility - -The presence of the `<ins>` element is not announced by most screen reading technology in its default configuration. It can be made to be announced by using the CSS {{cssxref("content")}} property, along with the {{cssxref("::before")}} and {{cssxref("::after")}} pseudo-elements. - -```css -ins::before, -ins::after { - clip-path: inset(100%); - clip: rect(1px, 1px, 1px, 1px); - height: 1px; - overflow: hidden; - position: absolute; - white-space: nowrap; - width: 1px; -} - -ins::before { - content: " [insertion start] "; -} - -ins::after { - content: " [insertion end] "; -} -``` - -Some people who use screen readers deliberately disable announcing content that creates extra verbosity. Because of this, it is important to not abuse this technique and only apply it in situations where not knowing content has been inserted would adversely affect understanding. - -- [Short note on making your mark (more accessible) | The Paciello Group](https://www.tpgi.com/short-note-on-making-your-mark-more-accessible/) -- [Tweaking Text Level Styles | Adrian Roselli](https://adrianroselli.com/2017/12/tweaking-text-level-styles.html) - -## Examples - -```html -<ins>This text has been inserted</ins> -``` - -### Result - -{{EmbedLiveSample("Examples")}} - -## Technical summary - -<table class="properties"> - <tbody> - <tr> - <th scope="row"> - <a href="/en-US/docs/Web/HTML/Content_categories" - >Content categories</a - > - </th> - <td> - <a href="/en-US/docs/Web/HTML/Content_categories#phrasing_content" - >Phrasing content</a - >, - <a href="/en-US/docs/Web/HTML/Content_categories#flow_content" - >flow content</a - >. - </td> - </tr> - <tr> - <th scope="row">Permitted content</th> - <td> - <a - href="/en-US/docs/Web/HTML/Content_categories#transparent_content_model" - >Transparent</a - >. - </td> - </tr> - <tr> - <th scope="row">Tag omission</th> - <td>None, both the starting and ending tag are mandatory.</td> - </tr> - <tr> - <th scope="row">Permitted parents</th> - <td> - Any element that accepts - <a href="/en-US/docs/Web/HTML/Content_categories#phrasing_content" - >phrasing content</a - >. - </td> - </tr> - <tr> - <th scope="row">Implicit ARIA role</th> - <td> - <code - ><a href="/en-US/docs/Web/Accessibility/ARIA/Roles/structural_roles#structural_roles_with_html_equivalents">insertion</a - ></code - > - </td> - </tr> - <tr> - <th scope="row">Permitted ARIA roles</th> - <td>Any</td> - </tr> - <tr> - <th scope="row">DOM interface</th> - <td>{{domxref("HTMLModElement")}}</td> - </tr> - </tbody> -</table> - -## Specifications - -{{Specifications}} - -## Browser compatibility - -{{Compat}} - -## See also - -- {{HTMLElement("del")}} element for marking deletion into a document diff --git a/files/en-us/web/html/element/kbd/index.md b/files/en-us/web/html/element/kbd/index.md deleted file mode 100644 index db71c34fe3c0072..000000000000000 --- a/files/en-us/web/html/element/kbd/index.md +++ /dev/null @@ -1,233 +0,0 @@ ---- -title: "<kbd>: The Keyboard Input element" -slug: Web/HTML/Element/kbd -page-type: html-element -browser-compat: html.elements.kbd ---- - -{{HTMLSidebar}} - -The **`<kbd>`** [HTML](/en-US/docs/Web/HTML) element represents a span of inline text denoting textual user input from a keyboard, voice input, or any other text entry device. By convention, the {{Glossary("user agent")}} defaults to rendering the contents of a `<kbd>` element using its default monospace font, although this is not mandated by the HTML standard. - -{{InteractiveExample("HTML Demo: &lt;kbd&gt;", "tabbed-shorter")}} - -```html interactive-example -<p> - Please press <kbd>Ctrl</kbd> + <kbd>Shift</kbd> + <kbd>R</kbd> to re-render an - MDN page. -</p> -``` - -```css interactive-example -kbd { - background-color: #eee; - border-radius: 3px; - border: 1px solid #b4b4b4; - box-shadow: - 0 1px 1px rgba(0, 0, 0, 0.2), - 0 2px 0 0 rgba(255, 255, 255, 0.7) inset; - color: #333; - display: inline-block; - font-size: 0.85em; - font-weight: 700; - line-height: 1; - padding: 2px 4px; - white-space: nowrap; -} -``` - -`<kbd>` may be nested in various combinations with the {{HTMLElement("samp")}} (Sample Output) element to represent various forms of input or output based on visual cues. - -## Attributes - -This element only includes the [global attributes](/en-US/docs/Web/HTML/Global_attributes). - -## Usage notes - -Other elements can be used in tandem with `<kbd>` to represent more specific scenarios: - -- Nesting a `<kbd>` element within another `<kbd>` element represents an actual key or other unit of input as a portion of a larger input. See [Representing keystrokes within an input](#representing_keystrokes_within_an_input) below. -- Nesting a `<kbd>` element inside a {{HTMLElement("samp")}} element represents input that has been echoed back to the user by the system. See [Echoed input](#echoed_input), below, for an example. -- Nesting a `<samp>` element inside a `<kbd>` element, on the other hand, represents input which is based on text presented by the system, such as the names of menus and menu items, or the names of buttons displayed on the screen. See the example under [Representing onscreen input options](#representing_onscreen_input_options) below. - -> [!NOTE] -> You can define a custom style to override the browser's default font selection for the `<kbd>` element, although the user's preferences may potentially override your CSS. - -## Examples - -### Basic example - -```html -<p> - Use the command <kbd>help my-command</kbd> to view documentation for the - command "my-command". -</p> -``` - -#### Result - -{{ EmbedLiveSample('Basic_example', 350, 80) }} - -### Representing keystrokes within an input - -To describe an input comprised of multiple keystrokes, you can nest multiple `<kbd>` elements, with an outer `<kbd>` element representing the overall input and each individual keystroke or component of the input enclosed within its own `<kbd>`. - -#### Unstyled - -First, let's look at what this looks like as just plain HTML. - -##### HTML - -```html -<p> - You can also create a new document using the - <kbd><kbd>Ctrl</kbd>+<kbd>N</kbd></kbd> keyboard shortcut. -</p> -``` - -This wraps the entire key sequence in an outer `<kbd>` element, then each individual key within its own, in order to denote the components of the sequence. - -> [!NOTE] -> You don't need to do all this wrapping; you can choose to simplify it by leaving out the external `<kbd>` element. In other words, simplifying this to just `<kbd>Ctrl</kbd>+<kbd>N</kbd>` would be perfectly valid. -> -> Depending on your style sheet, though, you may find it useful to do this kind of nesting. - -##### Result - -The output looks like this without a style sheet applied: - -{{EmbedLiveSample("Unstyled", 650, 80)}} - -#### With custom styles - -We can make more sense of this by adding some CSS: - -##### CSS - -We add a new selector for nested `<kbd>` elements, `kbd>kbd`, which we can apply when rendering keyboard keys: - -```css -kbd > kbd { - border-radius: 3px; - padding: 1px 2px 0; - border: 1px solid black; -} -``` - -##### HTML - -Then we update the HTML to use this class on the keys in the output to be presented: - -```html -<p> - You can also create a new document by pressing the - <kbd><kbd>Ctrl</kbd>+<kbd>N</kbd></kbd> shortcut. -</p> -``` - -##### Result - -The result is just what we want! - -{{EmbedLiveSample("With_custom_styles", 650, 80)}} - -### Echoed input - -Nesting a `<kbd>` element inside a {{HTMLElement("samp")}} element represents input that has been echoed back to the user by the system. - -```html -<p> - If a syntax error occurs, the tool will output the initial command you typed - for your review: -</p> -<blockquote> - <samp><kbd>custom-git ad my-new-file.cpp</kbd></samp> -</blockquote> -``` - -#### Result - -{{EmbedLiveSample("Echoed_input", 650, 100)}} - -### Representing onscreen input options - -Nesting a `<samp>` element inside a `<kbd>` element represents input which is based on text presented by the system, such as the names of menus and menu items, or the names of buttons displayed on the screen. - -For example, you can explain how to choose the "New Document" option in the "File" menu using HTML that looks like this: - -```html-nolint -<p> - To create a new file, choose the <kbd><kbd><samp>File</samp></kbd> - ⇒<kbd><samp>New Document</samp></kbd></kbd> menu option. -</p> - -<p> - Don't forget to click the <kbd><samp>OK</samp></kbd> button to confirm once - you've entered the name of the new file. -</p> -``` - -This does some interesting nesting. For the menu option description, the entire input is enclosed in a `<kbd>` element. Then, inside that, both the menu and menu item names are contained within both `<kbd>` and `<samp>`, indicating an input which is selected from a screen widget. - -#### Result - -{{EmbedLiveSample("Representing_onscreen_input_options", 650, 120)}} - -## Technical summary - -<table class="properties"> - <tbody> - <tr> - <th scope="row"> - <a href="/en-US/docs/Web/HTML/Content_categories">Content categories</a> - </th> - <td> - <a href="/en-US/docs/Web/HTML/Content_categories#flow_content">Flow content</a>, - <a href="/en-US/docs/Web/HTML/Content_categories#phrasing_content">phrasing content</a>, palpable content. - </td> - </tr> - <tr> - <th scope="row">Permitted content</th> - <td> - <a href="/en-US/docs/Web/HTML/Content_categories#phrasing_content">Phrasing content</a>. - </td> - </tr> - <tr> - <th scope="row">Tag omission</th> - <td>None, both the starting and ending tag are mandatory.</td> - </tr> - <tr> - <th scope="row">Permitted parents</th> - <td> - Any element that accepts - <a href="/en-US/docs/Web/HTML/Content_categories#phrasing_content">phrasing content</a>. - </td> - </tr> - <tr> - <th scope="row">Implicit ARIA role</th> - <td> - <a href="https://www.w3.org/TR/html-aria/#dfn-no-corresponding-role">No corresponding role</a> - </td> - </tr> - <tr> - <th scope="row">Permitted ARIA roles</th> - <td>Any</td> - </tr> - <tr> - <th scope="row">DOM interface</th> - <td>{{domxref("HTMLElement")}}</td> - </tr> - </tbody> -</table> - -## Specifications - -{{Specifications}} - -## Browser compatibility - -{{Compat}} - -## See also - -- {{htmlelement("code")}} diff --git a/files/en-us/web/html/element/label/index.md b/files/en-us/web/html/element/label/index.md deleted file mode 100644 index 6b883681cf1cfe3..000000000000000 --- a/files/en-us/web/html/element/label/index.md +++ /dev/null @@ -1,234 +0,0 @@ ---- -title: "<label>: The Label element" -slug: Web/HTML/Element/label -page-type: html-element -browser-compat: html.elements.label ---- - -{{HTMLSidebar}} - -The **`<label>`** [HTML](/en-US/docs/Web/HTML) element represents a caption for an item in a user interface. - -{{InteractiveExample("HTML Demo: &lt;label&gt;", "tabbed-shorter")}} - -```html interactive-example -<div class="preference"> - <label for="cheese">Do you like cheese?</label> - <input type="checkbox" name="cheese" id="cheese" /> -</div> - -<div class="preference"> - <label for="peas">Do you like peas?</label> - <input type="checkbox" name="peas" id="peas" /> -</div> -``` - -```css interactive-example -.preference { - display: flex; - justify-content: space-between; - width: 60%; - margin: 0.5rem; -} -``` - -Associating a `<label>` with a form control, such as {{htmlelement("input")}} or {{htmlelement("textarea")}} offers some major advantages: - -- The label text is not only visually associated with its corresponding text input; it is programmatically associated with it too. This means that, for example, a screen reader will read out the label when the user is focused on the form input, making it easier for an assistive technology user to understand what data should be entered. -- When a user clicks or touches/taps a label, the browser passes the focus to its associated input (the resulting event is also raised for the input). That increased hit area for focusing the input provides an advantage to anyone trying to activate it — including those using a touch-screen device. - -To explicitly associate a `<label>` element with an `<input>` element, you first need to add the `id` attribute to the `<input>` element. Next, you add the `for` attribute to the `<label>` element, where the value of `for` is the same as the `id` in the `<input>` element. - -Alternatively, you can nest the `<input>` directly inside the `<label>`, in which case the `for` and `id` attributes are not needed because the association is implicit: - -```html -<label> - Do you like peas? - <input type="checkbox" name="peas" /> -</label> -``` - -The form control that a label is labeling is called the _labeled control_ of the label element. Multiple labels can be associated with the same form control: - -```html -<label for="username">Enter your username:</label> -<input id="username" name="username" type="text" /> -<label for="username">Forgot your username?</label> -``` - -Elements that can be associated with a `<label>` element include {{HTMLElement('button')}}, {{HTMLElement('input')}} (except for `type="hidden"`), {{HTMLElement('meter')}}, {{HTMLElement('output')}}, {{HTMLElement('progress')}}, {{HTMLElement('select')}} and {{HTMLElement('textarea')}}. - -## Attributes - -This element includes the [global attributes](/en-US/docs/Web/HTML/Global_attributes). - -- [`for`](/en-US/docs/Web/HTML/Attributes/for) - - - : The value of the `for` attribute must be a single [`id`](/en-US/docs/Web/HTML/Global_attributes/id) for a [labelable](/en-US/docs/Web/HTML/Content_categories#labelable) form-related element in the same document as the `<label>` element. So, any given `label` element can be associated with only one form control. - - > [!NOTE] - > To programmatically set the `for` attribute, use [`htmlFor`](/en-US/docs/Web/API/HTMLLabelElement/htmlFor). - - The first element in the document with an `id` attribute matching the value of the `for` attribute is the _labeled control_ for this `label` element — if the element with that `id` is actually a [labelable element](https://html.spec.whatwg.org/multipage/forms.html#category-label). If it is _not_ a labelable element, then the `for` attribute has no effect. If there are other elements that also match the `id` value, later in the document, they are not considered. - - Multiple `label` elements can be given the same value for their `for` attribute; doing so causes the associated form control (the form control that `for` value references) to have multiple labels. - - > [!NOTE] - > A `<label>` element can have both a `for` attribute and a contained control element, as long as the `for` attribute points to the contained control element. - -## Styling with CSS - -There are no special styling considerations for `<label>` elements — structurally they are simple inline elements, and so can be styled in much the same way as a {{htmlelement("span")}} or {{htmlelement("a")}} element. You can apply styling to them in any way you want, as long as you don't cause the text to become difficult to read. - -## Accessibility - -### Interactive content - -Don't place interactive elements such as {{HTMLElement("a", "anchors")}} or {{HTMLElement("button", "buttons")}} inside a `label`. Doing so makes it difficult for people to activate the form input associated with the `label`. - -**Don't do this:** - -```html example-bad -<label for="tac"> - <input id="tac" type="checkbox" name="terms-and-conditions" /> - I agree to the <a href="terms-and-conditions.html">Terms and Conditions</a> -</label> -``` - -**Prefer this:** - -```html example-good -<label for="tac"> - <input id="tac" type="checkbox" name="terms-and-conditions" /> - I agree to the Terms and Conditions -</label> -<p> - <a href="terms-and-conditions.html">Read our Terms and Conditions</a> -</p> -``` - -### Headings - -Placing [heading elements](/en-US/docs/Web/HTML/Element/Heading_Elements) within a `<label>` interferes with many kinds of assistive technology, because headings are commonly used as [a navigation aid](/en-US/docs/Web/HTML/Element/Heading_Elements#navigation). If the label's text needs to be adjusted visually, use CSS classes applied to the `<label>` element instead. - -If a [form](/en-US/docs/Web/HTML/Element/form), or a section of a form needs a title, use the {{HTMLElement("legend")}} element placed within a {{HTMLElement("fieldset")}}. - -**Don't do this:** - -```html example-bad -<label for="your-name"> - <h3>Your name</h3> - <input id="your-name" name="your-name" type="text" /> -</label> -``` - -**Prefer this:** - -```html example-good -<label class="large-label" for="your-name"> - Your name - <input id="your-name" name="your-name" type="text" /> -</label> -``` - -### Buttons - -An {{HTMLElement("input")}} element with a `type="button"` declaration and a valid `value` attribute does not need a label associated with it. Doing so may actually interfere with how assistive technology parses the button input. The same applies for the {{HTMLElement("button")}} element. - -## Examples - -### Defining an implicit label - -```html -<label>Click me <input type="text" /></label> -``` - -{{EmbedLiveSample('Defining an implicit label', '200', '50')}} - -### Defining an explicit label with the "for" attribute - -```html -<label for="username">Click me to focus on the input field</label> -<input type="text" id="username" /> -``` - -{{EmbedLiveSample('Using_the_for_attribute', '200', '50')}} - -## Technical summary - -<table class="properties"> - <tbody> - <tr> - <th scope="row"> - <a href="/en-US/docs/Web/HTML/Content_categories" - >Content categories</a - > - </th> - <td> - <a href="/en-US/docs/Web/HTML/Content_categories#flow_content" - >Flow content</a - >, - <a href="/en-US/docs/Web/HTML/Content_categories#phrasing_content" - >phrasing content</a - >, - <a - href="/en-US/docs/Web/HTML/Content_categories#interactive_content" - >interactive content</a - >, - <a - href="/en-US/docs/Web/HTML/Content_categories#form-associated_content" - >form-associated element</a - >, palpable content. - </td> - </tr> - <tr> - <th scope="row">Permitted content</th> - <td> - <a href="/en-US/docs/Web/HTML/Content_categories#phrasing_content" - >Phrasing content</a - >, but no descendant <code>label</code> elements. No - <a href="/en-US/docs/Web/HTML/Content_categories#labelable" - >labelable</a - > - elements other than the labeled control are allowed. - </td> - </tr> - <tr> - <th scope="row">Tag omission</th> - <td>None, both the starting and ending tag are mandatory.</td> - </tr> - <tr> - <th scope="row">Permitted parents</th> - <td> - Any element that accepts - <a href="/en-US/docs/Web/HTML/Content_categories#phrasing_content" - >phrasing content</a - >. - </td> - </tr> - <tr> - <th scope="row">Implicit ARIA role</th> - <td> - <a href="https://www.w3.org/TR/html-aria/#dfn-no-corresponding-role" - >No corresponding role</a - > - </td> - </tr> - <tr> - <th scope="row">Permitted ARIA roles</th> - <td>No <code>role</code> permitted</td> - </tr> - <tr> - <th scope="row">DOM interface</th> - <td>{{domxref("HTMLLabelElement")}}</td> - </tr> - </tbody> -</table> - -## Specifications - -{{Specifications}} - -## Browser compatibility - -{{Compat}} diff --git a/files/en-us/web/html/element/legend/index.md b/files/en-us/web/html/element/legend/index.md deleted file mode 100644 index 233bfd96387dbcd..000000000000000 --- a/files/en-us/web/html/element/legend/index.md +++ /dev/null @@ -1,112 +0,0 @@ ---- -title: "<legend>: The Field Set Legend element" -slug: Web/HTML/Element/legend -page-type: html-element -browser-compat: html.elements.legend ---- - -{{HTMLSidebar}} - -The **`<legend>`** [HTML](/en-US/docs/Web/HTML) element represents a caption for the content of its parent {{HTMLElement("fieldset")}}. - -{{InteractiveExample("HTML Demo: &lt;legend&gt;", "tabbed-standard")}} - -```html interactive-example -<fieldset> - <legend>Choose your favorite monster</legend> - - <input type="radio" id="kraken" name="monster" value="K" /> - <label for="kraken">Kraken</label><br /> - - <input type="radio" id="sasquatch" name="monster" value="S" /> - <label for="sasquatch">Sasquatch</label><br /> - - <input type="radio" id="mothman" name="monster" value="M" /> - <label for="mothman">Mothman</label> -</fieldset> -``` - -```css interactive-example -legend { - background-color: #000; - color: #fff; - padding: 3px 6px; -} - -input { - margin: 0.4rem; -} -``` - -## Attributes - -This element only includes the [global attributes](/en-US/docs/Web/HTML/Global_attributes). - -## Examples - -See {{HTMLElement("form")}} for examples on `<legend>`. - -## Technical summary - -<table class="properties"> - <tbody> - <tr> - <th scope="row"> - <a href="/en-US/docs/Web/HTML/Content_categories" - >Content categories</a - > - </th> - <td>None.</td> - </tr> - <tr> - <th scope="row">Permitted content</th> - <td> - <a href="/en-US/docs/Web/HTML/Content_categories#phrasing_content" - >Phrasing content</a - > - and - <a href="/en-US/docs/Web/HTML/Element/Heading_Elements">headings</a> - (h1–h6 elements). - </td> - </tr> - <tr> - <th scope="row">Tag omission</th> - <td>None, both the starting and ending tag are mandatory.</td> - </tr> - <tr> - <th scope="row">Permitted parents</th> - <td> - A {{HTMLElement("fieldset")}} whose first child is this - <code>&#x3C;legend></code> element - </td> - </tr> - <tr> - <th scope="row">Implicit ARIA role</th> - <td> - <a href="https://www.w3.org/TR/html-aria/#dfn-no-corresponding-role" - >No corresponding role</a - > - </td> - </tr> - <tr> - <th scope="row">Permitted ARIA roles</th> - <td>No <code>role</code> permitted</td> - </tr> - <tr> - <th scope="row">DOM interface</th> - <td>{{domxref("HTMLLegendElement")}}</td> - </tr> - </tbody> -</table> - -## Specifications - -{{Specifications}} - -## Browser compatibility - -{{Compat}} - -## See also - -- [ARIA: Form role](/en-US/docs/Web/Accessibility/ARIA/Roles/form_role) diff --git a/files/en-us/web/html/element/li/index.md b/files/en-us/web/html/element/li/index.md deleted file mode 100644 index 3b6c7a626618cfd..000000000000000 --- a/files/en-us/web/html/element/li/index.md +++ /dev/null @@ -1,189 +0,0 @@ ---- -title: "<li>: The List Item element" -slug: Web/HTML/Element/li -page-type: html-element -browser-compat: html.elements.li ---- - -{{HTMLSidebar}} - -The **`<li>`** [HTML](/en-US/docs/Web/HTML) element is used to represent an item in a list. It must be contained in a parent element: an ordered list ({{HTMLElement("ol")}}), an unordered list ({{HTMLElement("ul")}}), or a menu ({{HTMLElement("menu")}}). In menus and unordered lists, list items are usually displayed using bullet points. In ordered lists, they are usually displayed with an ascending counter on the left, such as a number or letter. - -{{InteractiveExample("HTML Demo: &lt;li&gt;", "tabbed-shorter")}} - -```html interactive-example -<p>Apollo astronauts:</p> - -<ul> - <li>Neil Armstrong</li> - <li>Alan Bean</li> - <li>Peter Conrad</li> - <li>Edgar Mitchell</li> - <li>Alan Shepard</li> -</ul> -``` - -```css interactive-example -p, -li { - font: - 1rem "Fira Sans", - sans-serif; -} - -p { - font-weight: bold; -} -``` - -## Attributes - -This element includes the [global attributes](/en-US/docs/Web/HTML/Global_attributes). - -- `value` - - : This integer attribute indicates the current ordinal value of the list item as defined by the {{HTMLElement("ol")}} element. The only allowed value for this attribute is a number, even if the list is displayed with Roman numerals or letters. List items that follow this one continue numbering from the value set. This attribute has no meaning for unordered lists ({{HTMLElement("ul")}}) or for menus ({{HTMLElement("menu")}}). -- `type` {{Deprecated_inline}} - - - : This character attribute indicates the numbering type: - - - `a`: lowercase letters - - `A`: uppercase letters - - `i`: lowercase Roman numerals - - `I`: uppercase Roman numerals - - `1`: numbers - - This type overrides the one used by its parent {{HTMLElement("ol")}} element, if any. - - > [!NOTE] - > This attribute has been deprecated; use the CSS {{cssxref("list-style-type")}} property instead. - -## Examples - -For more detailed examples, see the {{htmlelement("ol")}} and {{htmlelement("ul")}} pages. - -### Ordered list - -```html -<ol> - <li>first item</li> - <li>second item</li> - <li>third item</li> -</ol> -``` - -#### Result - -{{EmbedLiveSample("Ordered_list")}} - -### Ordered list with a custom value - -```html -<ol type="I"> - <li value="3">third item</li> - <li>fourth item</li> - <li>fifth item</li> -</ol> -``` - -#### Result - -{{EmbedLiveSample("Ordered_list_with_a_custom_value")}} - -### Unordered list - -```html -<ul> - <li>first item</li> - <li>second item</li> - <li>third item</li> -</ul> -``` - -#### Result - -{{EmbedLiveSample("Unordered_list")}} - -## Technical summary - -<table class="properties"> - <tbody> - <tr> - <th scope="row"> - <a href="/en-US/docs/Web/HTML/Content_categories" - >Content categories</a - > - </th> - <td>None.</td> - </tr> - <tr> - <th scope="row">Permitted content</th> - <td> - <a href="/en-US/docs/Web/HTML/Content_categories#flow_content" - >Flow content</a - >. - </td> - </tr> - <tr> - <th scope="row">Tag omission</th> - <td> - The end tag can be omitted if the list item is immediately followed by - another <code>&lt;li&gt;</code> element, or if there is no more - content in its parent element. - </td> - </tr> - <tr> - <th scope="row">Permitted parents</th> - <td> - An {{HTMLElement("ul")}}, {{HTMLElement("ol")}}, or - {{HTMLElement("menu")}} element. Though not a conforming usage, - the obsolete {{HTMLElement("dir")}} can also be a parent. - </td> - </tr> - <tr> - <th scope="row">Implicit ARIA role</th> - <td> - <code - ><a href="/en-US/docs/Web/Accessibility/ARIA/Roles/listitem_role" - >listitem</a - ></code - > - when child of an - <code><a href="/en-US/docs/Web/HTML/Element/ol">ol</a></code - >, <code><a href="/en-US/docs/Web/HTML/Element/ul">ul</a></code> or - <code><a href="/en-US/docs/Web/HTML/Element/menu">menu</a></code> - </td> - </tr> - <tr> - <th scope="row">Permitted ARIA roles</th> - <td> - <a href="/en-US/docs/Web/Accessibility/ARIA/Roles/menuitem_role"><code>menuitem</code></a>, - <a href="/en-US/docs/Web/Accessibility/ARIA/Roles/menuitemcheckbox_role"><code>menuitemcheckbox</code></a>, - <a href="/en-US/docs/Web/Accessibility/ARIA/Roles/menuitemradio_role"><code>menuitemradio</code></a>, <a href="/en-US/docs/Web/Accessibility/ARIA/Roles/option_role"><code>option</code></a>, - <a href="/en-US/docs/Web/Accessibility/ARIA/Roles/none_role"><code>none</code></a>, <a href="/en-US/docs/Web/Accessibility/ARIA/Roles/presentation_role"><code>presentation</code></a>, - <a href="/en-US/docs/Web/Accessibility/ARIA/Roles/radio_role"><code>radio</code></a>, <a href="/en-US/docs/Web/Accessibility/ARIA/Roles/separator_role"><code>separator</code></a>, - <a href="/en-US/docs/Web/Accessibility/ARIA/Roles/tab_role"><code>tab</code></a>, <a href="/en-US/docs/Web/Accessibility/ARIA/Roles/treeitem_role"><code>treeitem</code></a> - </td> - </tr> - <tr> - <th scope="row">DOM interface</th> - <td>{{domxref("HTMLLIElement")}}</td> - </tr> - </tbody> -</table> - -## Specifications - -{{Specifications}} - -## Browser compatibility - -{{Compat}} - -## See also - -- Other list-related HTML Elements: {{HTMLElement("ul")}}, {{HTMLElement("ol")}}, {{HTMLElement("menu")}}, and the obsolete {{HTMLElement("dir")}}; -- CSS properties that may be specially useful to style the `<li>` element: - - - the {{cssxref("list-style")}} property, to choose the way the ordinal is displayed, - - [CSS counters](/en-US/docs/Web/CSS/CSS_counter_styles/Using_CSS_counters), to handle complex nested lists, - - the {{cssxref("margin")}} property, to control the indent of the list item. diff --git a/files/en-us/web/html/element/link/index.md b/files/en-us/web/html/element/link/index.md deleted file mode 100644 index 3ea74e77586cfb1..000000000000000 --- a/files/en-us/web/html/element/link/index.md +++ /dev/null @@ -1,473 +0,0 @@ ---- -title: "<link>: The External Resource Link element" -slug: Web/HTML/Element/link -page-type: html-element -browser-compat: html.elements.link ---- - -{{HTMLSidebar}} - -The **`<link>`** [HTML](/en-US/docs/Web/HTML) element specifies relationships between the current document and an external resource. -This element is most commonly used to link to {{Glossary("CSS", "stylesheets")}}, but is also used to establish site icons (both "favicon" style icons and icons for the home screen and apps on mobile devices) among other things. - -{{InteractiveExample("HTML Demo: &lt;link&gt;", "tabbed-shorter")}} - -```html interactive-example -<link href="/shared-assets/misc/link-element-example.css" rel="stylesheet" /> - -<p>This text will be red as defined in the external stylesheet.</p> -<p style="color: blue"> - The <code>style</code> attribute can override it, though. -</p> -``` - -To link an external stylesheet, you'd include a `<link>` element inside your {{HTMLElement("head")}} like this: - -```html -<link href="main.css" rel="stylesheet" /> -``` - -This example provides the path to the stylesheet inside an `href` attribute and a [`rel`](/en-US/docs/Web/HTML/Attributes/rel) attribute with a value of `stylesheet`. The `rel` stands for "relationship", and is one of the key features of the `<link>` element — the value denotes how the item being linked to is related to the containing document. - -There are a number of other common types you'll come across. For example, a link to the site's favicon: - -```html -<link rel="icon" href="favicon.ico" /> -``` - -There are a number of other icon `rel` values, mainly used to indicate special icon types for use on various mobile platforms, e.g.: - -```html -<link - rel="apple-touch-icon" - sizes="114x114" - href="apple-icon-114.png" - type="image/png" /> -``` - -The `sizes` attribute indicates the icon size, while the `type` contains the MIME type of the resource being linked. -These provide useful hints to allow the browser to choose the most appropriate icon available. - -You can also provide a media type or query inside a `media` attribute; this resource will then only be loaded if the media condition is true. For example: - -```html -<link href="print.css" rel="stylesheet" media="print" /> -<link - href="mobile.css" - rel="stylesheet" - media="screen and (max-width: 600px)" /> -``` - -Some interesting new performance and security features have been added to the `<link>` element too. Take this example: - -```html -<link - rel="preload" - href="myFont.woff2" - as="font" - type="font/woff2" - crossorigin="anonymous" /> -``` - -A `rel` value of `preload` indicates that the browser should preload this resource (see [`rel="preload"`](/en-US/docs/Web/HTML/Attributes/rel/preload) for more details), with the `as` attribute indicating the specific class of content being fetched. -The `crossorigin` attribute indicates whether the resource should be fetched with a {{Glossary("CORS")}} request. - -Other usage notes: - -- A `<link>` element can occur either in the {{HTMLElement("head")}} or {{HTMLElement("body")}} element, depending on whether it has a [link type](https://html.spec.whatwg.org/multipage/links.html#body-ok) that is **body-ok**. - For example, the `stylesheet` link type is body-ok, and therefore `<link rel="stylesheet">` is permitted in the body. - However, this isn't a good practice to follow; it makes more sense to separate your `<link>` elements from your body content, putting them in the `<head>`. -- When using `<link>` to establish a favicon for a site, and your site uses a Content Security Policy (CSP) to enhance its security, the policy applies to the favicon. - If you encounter problems with the favicon not loading, verify that the {{HTTPHeader("Content-Security-Policy")}} header's [`img-src` directive](/en-US/docs/Web/HTTP/Headers/Content-Security-Policy/img-src) is not preventing access to it. -- The HTML and XHTML specifications define event handlers for the `<link>` element, but it is unclear how they would be used. -- Under XHTML 1.0, {{glossary("void element", "void elements")}} such as `<link>` require a trailing slash: `<link />`. -- WebTV supports the use of the value `next` for `rel` to preload the next page in a document series. - -## Attributes - -This element includes the [global attributes](/en-US/docs/Web/HTML/Global_attributes). - -- `as` - - - : This attribute is required when [`rel="preload"`](/en-US/docs/Web/HTML/Attributes/rel/preload) has been set on the `<link>` element, optional when [`rel="modulepreload"`](/en-US/docs/Web/HTML/Attributes/rel/modulepreload) has been set, and otherwise should not be used. - It specifies the type of content being loaded by the `<link>`, which is necessary for request matching, application of correct [content security policy](/en-US/docs/Web/HTTP/CSP), and setting of correct {{HTTPHeader("Accept")}} request header. - - Furthermore, `rel="preload"` uses this as a signal for request prioritization. - The table below lists the valid values for this attribute and the elements or resources they apply to. - - <table class="standard-table"> - <thead> - <tr> - <th scope="col">Value</th> - <th scope="col">Applies To</th> - </tr> - </thead> - <tbody> - <tr> - <td>audio</td> - <td><code>&#x3C;audio></code> elements</td> - </tr> - <tr> - <td>document</td> - <td><code>&#x3C;iframe></code> and <code>&#x3C;frame></code> elements</td> - </tr> - <tr> - <td>embed</td> - <td><code>&#x3C;embed></code> elements</td> - </tr> - <tr> - <td>fetch</td> - <td> - <p>fetch, XHR</p> - <div class="notecard note"> - <p> - <strong>Note:</strong> This value also requires - <code>&#x3C;link></code> to contain the crossorigin attribute, see <a href="/en-US/docs/Web/HTML/Attributes/rel/preload#cors-enabled_fetches">CORS-enabled fetches</a>. - </p> - </div> - </td> - </tr> - <tr> - <td>font</td> - <td> - <p>CSS @font-face</p> - <div class="notecard note"> - <p> - <strong>Note:</strong> This value also requires - <code>&#x3C;link></code> to contain the crossorigin attribute, see <a href="/en-US/docs/Web/HTML/Attributes/rel/preload#cors-enabled_fetches">CORS-enabled fetches</a>. - </p> - </div> - </td> - </tr> - <tr> - <td>image</td> - <td> - <code>&#x3C;img></code> and <code>&#x3C;picture></code> elements with - srcset or imageset attributes, SVG <code>&#x3C;image></code> elements, - CSS <code>*-image</code> rules - </td> - </tr> - <tr> - <td>object</td> - <td><code>&#x3C;object></code> elements</td> - </tr> - <tr> - <td>script</td> - <td> - <code>&#x3C;script></code> elements, Worker <code>importScripts</code> - </td> - </tr> - <tr> - <td>style</td> - <td> - <code>&#x3C;link rel=stylesheet></code> elements, CSS - <code>@import</code> - </td> - </tr> - <tr> - <td>track</td> - <td><code>&#x3C;track></code> elements</td> - </tr> - <tr> - <td>video</td> - <td><code>&#x3C;video></code> elements</td> - </tr> - <tr> - <td>worker</td> - <td>Worker, SharedWorker</td> - </tr> - </tbody> - </table> - -- `blocking` - - - : This attribute explicitly indicates that certain operations should be blocked on the fetching of an external resource. It must only be used when the `rel` attribute contains `expect` or `stylesheet` keywords. The operations that are to be blocked must be a space-separated list of blocking tokens listed below. - - `render`: The rendering of content on the screen is blocked. - -- [`crossorigin`](/en-US/docs/Web/HTML/Attributes/crossorigin) - - - : This [enumerated](/en-US/docs/Glossary/Enumerated) attribute indicates whether {{Glossary("CORS")}} must be used when fetching the resource. - [CORS-enabled images](/en-US/docs/Web/HTML/CORS_enabled_image) can be reused in the {{HTMLElement("canvas")}} element without being _tainted_. - The allowed values are: - - - `anonymous` - - : A cross-origin request (i.e. with an {{HTTPHeader("Origin")}} HTTP header) is performed, but no credential is sent (i.e. no cookie, X.509 certificate, or HTTP Basic authentication). - If the server does not give credentials to the origin site (by not setting the {{HTTPHeader("Access-Control-Allow-Origin")}} HTTP header) the resource will be tainted and its usage restricted. - - `use-credentials` - - : A cross-origin request (i.e. with an `Origin` HTTP header) is performed along with a credential sent (i.e. a cookie, certificate, and/or HTTP Basic authentication is performed). - If the server does not give credentials to the origin site (through {{HTTPHeader("Access-Control-Allow-Credentials")}} HTTP header), the resource will be _tainted_ and its usage restricted. - - If the attribute is not present, the resource is fetched without a {{Glossary("CORS")}} request (i.e. without sending the `Origin` HTTP header), preventing its non-tainted usage. If invalid, it is handled as if the enumerated keyword **anonymous** was used. - See [CORS settings attributes](/en-US/docs/Web/HTML/Attributes/crossorigin) for additional information. - -- `disabled` - - - : For `rel="stylesheet"` only, the `disabled` Boolean attribute indicates whether the described stylesheet should be loaded and applied to the document. - If `disabled` is specified in the HTML when it is loaded, the stylesheet will not be loaded during page load. - Instead, the stylesheet will be loaded on-demand, if and when the `disabled` attribute is changed to `false` or removed. - - Setting the `disabled` property in the DOM causes the stylesheet to be removed from the document's {{domxref("Document.styleSheets")}} list. - -- `fetchpriority` - - - : Provides a hint of the relative priority to use when fetching a resource of a particular type. - Allowed values: - - - `high` - - : Fetch the resource at a high priority relative to other resources of the same type. - - `low` - - : Fetch the resource at a low priority relative to other resources of the same type. - - `auto` - - : Don't set a preference for the fetch priority. - This is the default. - It is used if no value or an invalid value is set. - - See {{domxref("HTMLLinkElement.fetchPriority")}} for more information. - -- `href` - - : This attribute specifies the {{glossary("URL")}} of the linked resource. A URL can be absolute or relative. -- `hreflang` - - : This attribute indicates the language of the linked resource. - It is purely advisory. - Allowed values are specified by {{RFC(5646, "Tags for Identifying Languages (also known as BCP 47)")}}. - Use this attribute only if the [`href`](/en-US/docs/Web/HTML/Element/a#href) attribute is present. -- `imagesizes` - - : For `rel="preload"` and `as="image"` only, the `imagesizes` attribute has similar syntax and semantics as the [`sizes`](/en-US/docs/Web/HTML/Element/img#sizes) attribute that indicates to preload the appropriate resource used by an `img` element with corresponding values for its `srcset` and `sizes` attributes. -- `imagesrcset` - - : For `rel="preload"` and `as="image"` only, the `imagesrcset` attribute has similar syntax and semantics as the [`srcset`](/en-US/docs/Web/HTML/Element/img#srcset) attribute that indicates to preload the appropriate resource used by an `img` element with corresponding values for its `srcset` and `sizes` attributes. -- `integrity` - - : Contains inline metadata — a base64-encoded cryptographic hash of the resource (file) you're telling the browser to fetch. - The browser can use this to verify that the fetched resource has been delivered without unexpected manipulation. - The attribute must only be specified when the `rel` attribute is specified to `stylesheet`, `preload`, or `modulepreload`. - See [Subresource Integrity](/en-US/docs/Web/Security/Subresource_Integrity). -- `media` - - - : This attribute specifies the media that the linked resource applies to. Its value must be a media type / [media query](/en-US/docs/Web/CSS/CSS_media_queries). - This attribute is mainly useful when linking to external stylesheets — it allows the user agent to pick the best adapted one for the device it runs on. - -- `referrerpolicy` - - - : A string indicating which referrer to use when fetching the resource: - - - `no-referrer` means that the {{HTTPHeader("Referer")}} header will not be sent. - - `no-referrer-when-downgrade` means that no {{HTTPHeader("Referer")}} header will be sent when navigating to an origin without TLS (HTTPS). - This is a user agent's default behavior, if no policy is otherwise specified. - - `origin` means that the referrer will be the origin of the page, which is roughly the scheme, the host, and the port. - - `origin-when-cross-origin` means that navigating to other origins will be limited to the scheme, the host, and the port, while navigating on the same origin will include the referrer's path. - - `unsafe-url` means that the referrer will include the origin and the path (but not the fragment, password, or username). - This case is unsafe because it can leak origins and paths from TLS-protected resources to insecure origins. - -- [`rel`](/en-US/docs/Web/HTML/Attributes/rel) - - : This attribute names a relationship of the linked document to the current document. The attribute must be a space-separated list of [link type values](/en-US/docs/Web/HTML/Attributes/rel). -- `sizes` - - - : This attribute defines the sizes of the icons for visual media contained in the resource. - It must be present only if the [`rel`](#rel) contains a value of `icon` or a non-standard type such as Apple's `apple-touch-icon`. - It may have the following values: - - - `any`, meaning that the icon can be scaled to any size as it is in a vector format, like `image/svg+xml`. - - a white-space separated list of sizes, each in the format `<width in pixels>x<height in pixels>` or `<width in pixels>X<height in pixels>`. Each of these sizes must be contained in the resource. - - > [!NOTE] - > Most icon formats are only able to store one single icon; therefore, most of the time, the [`sizes`](#sizes) attribute contains only one entry. - > Microsoft's ICO format and Apple's ICNS format can store multiple icon sizes in a single file. ICO has better browser support, so you should use this format if cross-browser support is a concern. - -- `title` - - : The `title` attribute has special semantics on the `<link>` element. - When used on a `<link rel="stylesheet">` it defines a [default or an alternate stylesheet](/en-US/docs/Web/HTML/Attributes/rel/alternate_stylesheet). -- `type` - - : This attribute is used to define the type of the content linked to. - The value of the attribute should be a MIME type such as **text/html**, **text/css**, and so on. - The common use of this attribute is to define the type of stylesheet being referenced (such as **text/css**), but given that CSS is the only stylesheet language used on the web, not only is it possible to omit the `type` attribute, but is actually now recommended practice. - It is also used on `rel="preload"` link types, to make sure the browser only downloads file types that it supports. - -### Non-standard attributes - -- `target` {{Deprecated_Inline}} - - : Defines the frame or window name that has the defined linking relationship or that will show the rendering of any linked resource. - -### Obsolete attributes - -- `charset` {{deprecated_inline}} - - - : This attribute defines the character encoding of the linked resource. - The value is a space- and/or comma-delimited list of character sets as defined in {{rfc(2045)}}. - The default value is `iso-8859-1`. - - > [!NOTE] - > To produce the same effect as this obsolete attribute, use the {{HTTPHeader("Content-Type")}} HTTP header on the linked resource. - -- `rev` {{deprecated_inline}} - - - : The value of this attribute shows the relationship of the current document to the linked document, as defined by the [`href`](#href) attribute. - The attribute thus defines the reverse relationship compared to the value of the `rel` attribute. - [Link type values](/en-US/docs/Web/HTML/Attributes/rel) for the attribute are similar to the possible values for [`rel`](#rel). - - > [!NOTE] - > Instead of `rev`, you should use the [`rel`](#rel) attribute with the opposite [link type value](/en-US/docs/Web/HTML/Attributes/rel). - > For example, to establish the reverse link for `made`, specify `author`. Also, this attribute doesn't stand for "revision" and must not be used with a version number, even though many sites misuse it in this way. - -## Examples - -### Including a stylesheet - -To include a stylesheet in a page, use the following syntax: - -```html -<link href="style.css" rel="stylesheet" /> -``` - -### Providing alternative stylesheets - -You can also specify [alternative style sheets](/en-US/docs/Web/HTML/Attributes/rel/alternate_stylesheet). - -The user can choose which style sheet to use by choosing it from the **View > Page Style** menu. -This provides a way for users to see multiple versions of a page. - -```html -<link href="default.css" rel="stylesheet" title="Default Style" /> -<link href="fancy.css" rel="alternate stylesheet" title="Fancy" /> -<link href="basic.css" rel="alternate stylesheet" title="Basic" /> -``` - -### Providing icons for different usage contexts - -You can include links to several icons on the same page, and the browser will choose which one works best for its particular context using the `rel` and `sizes` values as hints. - -```html -<!-- iPad Pro with high-resolution Retina display: --> -<link - rel="apple-touch-icon" - sizes="167x167" - href="/apple-touch-icon-167x167.png" /> -<!-- 3x resolution iPhone: --> -<link - rel="apple-touch-icon" - sizes="180x180" - href="/apple-touch-icon-180x180.png" /> -<!-- non-Retina iPad, iPad mini, etc.: --> -<link - rel="apple-touch-icon" - sizes="152x152" - href="/apple-touch-icon-152x152.png" /> -<!-- 2x resolution iPhone and other devices: --> -<link rel="apple-touch-icon" href="/apple-touch-icon-120x120.png" /> -<!-- basic favicon --> -<link rel="icon" href="/favicon.ico" /> -``` - -For information about what `sizes` to choose for Apple icons, see [Apple's documentation on configuring web applications](https://developer.apple.com/library/archive/documentation/AppleApplications/Reference/SafariWebContent/ConfiguringWebApplications/ConfiguringWebApplications.html#//apple_ref/doc/uid/TP40002051-CH3-SW4) and the referenced [Apple human interface guidelines](https://developer.apple.com/design/human-interface-guidelines/app-icons#App-icon-sizes). Usually, it is sufficient to provide a large image, such as 192x192, and let the browser scale it down as needed, but you may want to provide images with different levels of detail for different sizes, as the Apple design guideline recommends. Providing smaller icons for lower resolutions also saves bandwidth. - -It may not be necessary to provide `<link>` elements at all. For example, browsers automatically request `/favicon.ico` from the root of a site, and Apple also automatically requests `/apple-touch-icon-[size].png`, `/apple-touch-icon.png`, etc. However, providing explicit links protects you against changes to these conventions. - -### Conditionally loading resources with media queries - -You can provide a media type or query inside a `media` attribute; -this resource will then only be loaded if the media condition is true. For example: - -```html -<link href="print.css" rel="stylesheet" media="print" /> -<link href="mobile.css" rel="stylesheet" media="all" /> -<link - href="desktop.css" - rel="stylesheet" - media="screen and (min-width: 600px)" /> -<link - href="highres.css" - rel="stylesheet" - media="screen and (min-resolution: 300dpi)" /> -``` - -### Stylesheet load events - -You can determine when a style sheet has been loaded by watching for a `load` event to fire on it; similarly, you can detect if an error has occurred while processing a style sheet by watching for an `error` event: - -```html -<link rel="stylesheet" href="mystylesheet.css" id="my-stylesheet" /> - -<script> - const stylesheet = document.getElementById("my-stylesheet"); - - stylesheet.onload = () => { - // Do something interesting; the sheet has been loaded - }; - - stylesheet.onerror = () => { - console.log("An error occurred loading the stylesheet!"); - }; -</script> -``` - -> [!NOTE] -> The `load` event fires once the stylesheet and all of its imported content has been loaded and parsed, and immediately before the styles start being applied to the content. - -### Preload examples - -You can find a number of `<link rel="preload">` examples in [Preloading content with `rel="preload"`](/en-US/docs/Web/HTML/Attributes/rel/preload). - -### Blocking rendering till a resource is fetched - -You can include `render` token inside a `blocking` attribute; -the rendering of the page will be blocked till the resource is fetched. For example: - -```html -<link blocking="render" rel="stylesheet" href="example.css" crossorigin /> -``` - -## Technical summary - -<table class="properties"> - <tbody> - <tr> - <th> - <a href="/en-US/docs/Web/HTML/Content_categories">Content categories</a> - </th> - <td> - Metadata content. - If <code><a href="/en-US/docs/Web/HTML/Global_attributes/itemprop">itemprop</a></code> is present: - <a href="/en-US/docs/Web/HTML/Content_categories#flow_content">Flow content</a> and - <a href="/en-US/docs/Web/HTML/Content_categories#phrasing_content">phrasing content</a>. - </td> - </tr> - <tr> - <th>Permitted content</th> - <td>None; it is a {{Glossary("void element")}}.</td> - </tr> - <tr> - <th>Tag omission</th> - <td>Must have a start tag and must not have an end tag.</td> - </tr> - <tr> - <th>Permitted parents</th> - <td> - Any element that accepts metadata elements. - If <a href="/en-US/docs/Web/HTML/Global_attributes/itemprop">itemprop</a> is present: any element that accepts - <a href="/en-US/docs/Web/HTML/Content_categories#phrasing_content">phrasing content</a>. - </td> - </tr> - <tr> - <th scope="row">Implicit ARIA role</th> - <td><a href="/en-US/docs/Web/Accessibility/ARIA/Roles/link_role"><code>link</code></a> with <code>href</code> attribute</td> - </tr> - <tr> - <th scope="row">Permitted ARIA roles</th> - <td>No <code>role</code> permitted</td> - </tr> - <tr> - <th>DOM interface</th> - <td>{{DOMxRef("HTMLLinkElement")}}</td> - </tr> - </tbody> -</table> - -## Specifications - -{{Specifications}} - -## Browser compatibility - -{{Compat}} - -## See also - -- {{HTTPHeader("Link")}} HTTP header diff --git a/files/en-us/web/html/element/main/index.md b/files/en-us/web/html/element/main/index.md deleted file mode 100644 index 5c56468053becc8..000000000000000 --- a/files/en-us/web/html/element/main/index.md +++ /dev/null @@ -1,190 +0,0 @@ ---- -title: "<main>: The Main element" -slug: Web/HTML/Element/main -page-type: html-element -browser-compat: html.elements.main ---- - -{{HTMLSidebar}} - -The **`<main>`** [HTML](/en-US/docs/Web/HTML) element represents the dominant content of the {{HTMLElement("body")}} of a document. The main content area consists of content that is directly related to or expands upon the central topic of a document, or the central functionality of an application. - -{{InteractiveExample("HTML Demo: &lt;main&gt;", "tabbed-shorter")}} - -```html interactive-example -<header>Gecko facts</header> - -<main> - <p> - Geckos are a group of usually small, usually nocturnal lizards. They are - found on every continent except Antarctica. - </p> - - <p> - Many species of gecko have adhesive toe pads which enable them to climb - walls and even windows. - </p> -</main> -``` - -```css interactive-example -header { - font: - bold 7vw Arial, - sans-serif; -} -``` - -A document mustn't have more than one `<main>` element that doesn't have the [`hidden`](/en-US/docs/Web/HTML/Global_attributes/hidden) attribute specified. - -## Attributes - -This element only includes the [global attributes](/en-US/docs/Web/HTML/Global_attributes). - -## Usage notes - -The content of a `<main>` element should be unique to the document. Content that is repeated across a set of documents or document sections such as sidebars, navigation links, copyright information, site logos, and search forms shouldn't be included unless the search form is the main function of the page. - -`<main>` doesn't contribute to the document's outline; that is, unlike elements such as {{HTMLElement("body")}}, headings such as {{HTMLElement("Heading_Elements", "h2")}}, and such, `<main>` doesn't affect the {{glossary("DOM", "DOM's")}} concept of the structure of the page. It's strictly informative. - -## Accessibility - -### Landmark - -The `<main>` element behaves like a [`main` landmark](/en-US/docs/Web/Accessibility/ARIA/Roles/main_role) role. [Landmarks](/en-US/docs/Web/Accessibility/ARIA/ARIA_Techniques#landmark_roles) can be used by assistive technology to quickly identify and navigate to large sections of the document. Prefer using the `<main>` element over declaring `role="main"`, unless there are [legacy browser support concerns](#browser_compatibility). - -### Skip navigation - -Skip navigation, also known as "skipnav", is a technique that allows an assistive technology user to quickly bypass large sections of repeated content (main navigation, info banners, etc.). This lets the user access the main content of the page faster. - -Adding an [`id`](/en-US/docs/Web/HTML/Global_attributes/id) attribute to the `<main>` element lets it be a target of a skip navigation link. - -```html -<body> - <a href="#main-content">Skip to main content</a> - - <!-- navigation and header content --> - - <main id="main-content"> - <!-- main page content --> - </main> -</body> -``` - -- [WebAIM: "Skip Navigation" Links](https://webaim.org/techniques/skipnav/) - -### Reader mode - -Browser reader mode functionality looks for the presence of the `<main>` element, as well as [heading](/en-US/docs/Web/HTML/Element/Heading_Elements) and [content sectioning elements](/en-US/docs/Web/HTML/Element#content_sectioning) when converting content into a specialized reader view. - -- [Building websites for Safari Reader Mode and other reading apps.](https://medium.com/@mandy.michael/building-websites-for-safari-reader-mode-and-other-reading-apps-1562913c86c9) - -## Examples - -```html -<!-- other content --> - -<main> - <h1>Apples</h1> - <p>The apple is the pomaceous fruit of the apple tree.</p> - - <article> - <h2>Red Delicious</h2> - <p> - These bright red apples are the most common found in many supermarkets. - </p> - <p>…</p> - <p>…</p> - </article> - - <article> - <h2>Granny Smith</h2> - <p>These juicy, green apples make a great filling for apple pies.</p> - <p>…</p> - <p>…</p> - </article> -</main> - -<!-- other content --> -``` - -### Result - -{{EmbedLiveSample('Examples')}} - -## Technical summary - -<table class="properties"> - <tbody> - <tr> - <th scope="row"> - <a href="/en-US/docs/Web/HTML/Content_categories" - >Content categories</a - > - </th> - <td> - <a href="/en-US/docs/Web/HTML/Content_categories#flow_content" - >Flow content</a - >, palpable content. - </td> - </tr> - <tr> - <th scope="row">Permitted content</th> - <td> - <a href="/en-US/docs/Web/HTML/Content_categories#flow_content" - >Flow content</a - >. - </td> - </tr> - <tr> - <th scope="row">Tag omission</th> - <td>None; both the starting and ending tags are mandatory.</td> - </tr> - <tr> - <th scope="row">Permitted parents</th> - <td> - Where - <a href="/en-US/docs/Web/HTML/Content_categories#flow_content" - >flow content</a - > - is expected, but only if it is a - <a - href="https://html.spec.whatwg.org/multipage/grouping-content.html#hierarchically-correct-main-element" - >hierarchically correct <code>main</code> element</a - >. - </td> - </tr> - <tr> - <th scope="row">Implicit ARIA role</th> - <td> - <code - ><a href="/en-US/docs/Web/Accessibility/ARIA/Roles/main_role" - >main</a - ></code - > - </td> - </tr> - <tr> - <th scope="row">Permitted ARIA roles</th> - <td>No <code>role</code> permitted</td> - </tr> - <tr> - <th scope="row">DOM interface</th> - <td>{{domxref("HTMLElement")}}</td> - </tr> - </tbody> -</table> - -## Specifications - -{{Specifications}} - -## Browser compatibility - -{{Compat}} - -## See also - -- Basic structural elements: {{HTMLElement("html")}}, {{HTMLElement("head")}}, {{HTMLElement("body")}} -- Section-related elements: {{HTMLElement("article")}}, {{HTMLElement("aside")}}, {{HTMLElement("footer")}}, {{HTMLElement("header")}}, or {{HTMLElement("nav")}} -- [ARIA: Main role](/en-US/docs/Web/Accessibility/ARIA/Roles/main_role) diff --git a/files/en-us/web/html/element/map/index.md b/files/en-us/web/html/element/map/index.md deleted file mode 100644 index 4db427ec87486b9..000000000000000 --- a/files/en-us/web/html/element/map/index.md +++ /dev/null @@ -1,161 +0,0 @@ ---- -title: "<map>: The Image Map element" -slug: Web/HTML/Element/map -page-type: html-element -browser-compat: html.elements.map ---- - -{{HTMLSidebar}} - -The **`<map>`** [HTML](/en-US/docs/Web/HTML) element is used with {{HTMLElement("area")}} elements to define an image map (a clickable link area). - -{{InteractiveExample("HTML Demo: &lt;map&gt;", "tabbed-standard")}} - -```html interactive-example -<map name="infographic"> - <area - shape="poly" - coords="130,147,200,107,254,219,130,228" - href="https://developer.mozilla.org/docs/Web/HTML" - alt="HTML" /> - <area - shape="poly" - coords="130,147,130,228,6,219,59,107" - href="https://developer.mozilla.org/docs/Web/CSS" - alt="CSS" /> - <area - shape="poly" - coords="130,147,200,107,130,4,59,107" - href="https://developer.mozilla.org/docs/Web/JavaScript" - alt="JavaScript" /> -</map> -<img - usemap="#infographic" - src="/shared-assets/images/examples/mdn-info2.png" - alt="MDN infographic" /> -``` - -```css interactive-example -img { - display: block; - margin: 0 auto; - width: 260px; - height: 232px; -} -``` - -## Attributes - -This element includes the [global attributes](/en-US/docs/Web/HTML/Global_attributes). - -- `name` - - : The `name` attribute gives the map a name so that it can be referenced. The attribute must be present and must have a non-empty value with no space characters. The value of the `name` attribute must not be equal to the value of the `name` attribute of another `<map>` element in the same document. If the [`id`](/en-US/docs/Web/HTML/Global_attributes/id) attribute is also specified, both attributes must have the same value. - -## Examples - -### Image map with two areas - -Click the left-hand parrot for JavaScript, or the right-hand parrot for CSS. - -#### HTML - -```html -<!-- Photo by Juliana e Mariana Amorim on Unsplash --> -<map name="primary"> - <area - shape="circle" - coords="75,75,75" - href="https://developer.mozilla.org/docs/Web/JavaScript" - target="_blank" - alt="JavaScript" /> - <area - shape="circle" - coords="275,75,75" - href="https://developer.mozilla.org/docs/Web/CSS" - target="_blank" - alt="CSS" /> -</map> -<img - usemap="#primary" - src="parrots.jpg" - alt="350 x 150 picture of two parrots" /> -``` - -#### Result - -{{ EmbedLiveSample('Image map with two areas', '', '250') }} - -## Technical summary - -<table class="properties"> - <tbody> - <tr> - <th scope="row"> - <a href="/en-US/docs/Web/HTML/Content_categories" - >Content categories</a - > - </th> - <td> - <a href="/en-US/docs/Web/HTML/Content_categories#flow_content" - >Flow content</a - >, - <a href="/en-US/docs/Web/HTML/Content_categories#phrasing_content" - >phrasing content</a - >, palpable content. - </td> - </tr> - <tr> - <th scope="row">Permitted content</th> - <td> - Any - <a - href="/en-US/docs/Web/HTML/Content_categories#transparent_content_model" - >transparent</a - > - element. - </td> - </tr> - <tr> - <th scope="row">Tag omission</th> - <td>None, both the starting and ending tag are mandatory.</td> - </tr> - <tr> - <th scope="row">Permitted parents</th> - <td> - Any element that accepts - <a href="/en-US/docs/Web/HTML/Content_categories#phrasing_content" - >phrasing content</a - >. - </td> - </tr> - <tr> - <th scope="row">Implicit ARIA role</th> - <td> - <a href="https://www.w3.org/TR/html-aria/#dfn-no-corresponding-role" - >No corresponding role</a - > - </td> - </tr> - <tr> - <th scope="row">Permitted ARIA roles</th> - <td>No <code>role</code> permitted</td> - </tr> - <tr> - <th scope="row">DOM interface</th> - <td>{{domxref("HTMLMapElement")}}</td> - </tr> - </tbody> -</table> - -## Specifications - -{{Specifications}} - -## Browser compatibility - -{{Compat}} - -## See also - -- {{HTMLElement("a")}} -- {{HTMLElement("area")}} diff --git a/files/en-us/web/html/element/mark/index.md b/files/en-us/web/html/element/mark/index.md deleted file mode 100644 index 22ea609087bd9e1..000000000000000 --- a/files/en-us/web/html/element/mark/index.md +++ /dev/null @@ -1,190 +0,0 @@ ---- -title: "<mark>: The Mark Text element" -slug: Web/HTML/Element/mark -page-type: html-element -browser-compat: html.elements.mark ---- - -{{HTMLSidebar}} - -The **`<mark>`** [HTML](/en-US/docs/Web/HTML) element represents text which is **marked** or **highlighted** for reference or notation purposes due to the marked passage's relevance in the enclosing context. - -{{InteractiveExample("HTML Demo: &lt;mark&gt;", "tabbed-shorter")}} - -```html interactive-example -<p>Search results for "salamander":</p> - -<hr /> - -<p> - Several species of <mark>salamander</mark> inhabit the temperate rainforest of - the Pacific Northwest. -</p> - -<p> - Most <mark>salamander</mark>s are nocturnal, and hunt for insects, worms, and - other small creatures. -</p> -``` - -```css interactive-example -/* stylelint-disable-next-line block-no-empty */ -mark { -} -``` - -## Attributes - -This element only includes the [global attributes](/en-US/docs/Web/HTML/Global_attributes). - -## Usage notes - -Typical use cases for `<mark>` include: - -- When used in a quotation ({{HTMLElement("q")}}) or block quote ({{HTMLElement("blockquote")}}), it generally indicates text which is of special interest but is not marked in the original source material, or material which needs special scrutiny even though the original author didn't think it was of particular importance. Think of this like using a highlighter pen in a book to mark passages that you find of interest. -- Otherwise, `<mark>` indicates a portion of the document's content which is likely to be relevant to the user's current activity. This might be used, for example, to indicate the words that matched a search operation. -- Don't use `<mark>` for syntax highlighting purposes; instead, use the {{HTMLElement("span")}} element with appropriate CSS applied to it. - -> [!NOTE] -> Don't confuse `<mark>` with the {{HTMLElement("strong")}} element; `<mark>` is used to denote content which has a degree of _relevance_, while `<strong>` indicates spans of text of _importance_. - -## Accessibility - -The presence of the `mark` element is not announced by most screen reading technology in its default configuration. It can be made to be announced by using the CSS {{cssxref("content")}} property, along with the {{cssxref("::before")}} and {{cssxref("::after")}} pseudo-elements. - -```css -mark::before, -mark::after { - clip-path: inset(100%); - clip: rect(1px, 1px, 1px, 1px); - height: 1px; - overflow: hidden; - position: absolute; - white-space: nowrap; - width: 1px; -} - -mark::before { - content: " [highlight start] "; -} - -mark::after { - content: " [highlight end] "; -} -``` - -Some people who use screen readers deliberately disable announcing content that creates extra verbosity. Because of this, it is important to not abuse this technique and only apply it in situations where not knowing content has been highlighted would adversely affect understanding. - -- [Short note on making your mark (more accessible) | The Paciello Group](https://www.tpgi.com/short-note-on-making-your-mark-more-accessible/) -- [Tweaking Text Level Styles | Adrian Roselli](https://adrianroselli.com/2017/12/tweaking-text-level-styles.html) - -## Examples - -### Marking text of interest - -In this first example, a `<mark>` element is used to mark some text within a quote which is of particular interest to the user. - -```html -<blockquote> - It is a period of civil war. Rebel spaceships, striking from a hidden base, - have won their first victory against the evil Galactic Empire. During the - battle, <mark>Rebel spies managed to steal secret plans</mark> to the Empire's - ultimate weapon, the DEATH STAR, an armored space station with enough power to - destroy an entire planet. -</blockquote> -``` - -#### Result - -{{EmbedLiveSample("Marking_text_of_interest", 650, 130)}} - -### Identifying context-sensitive passages - -This example demonstrates using `<mark>` to mark search results within a passage. - -```html -<p> - It is a dark time for the Rebellion. Although the Death Star has been - destroyed, <mark class="match">Imperial</mark> troops have driven the Rebel - forces from their hidden base and pursued them across the galaxy. -</p> - -<p> - Evading the dreaded <mark class="match">Imperial</mark> Starfleet, a group of - freedom fighters led by Luke Skywalker has established a new secret base on - the remote ice world of Hoth. -</p> -``` - -To help distinguish the use of `<mark>` for search results from other potential usage, this example applies the custom class `"match"` to each match. - -#### Result - -{{EmbedLiveSample("Identifying_context-sensitive_passages", 650, 130)}} - -## Technical summary - -<table class="properties"> - <tbody> - <tr> - <th scope="row"> - <a href="/en-US/docs/Web/HTML/Content_categories" - >Content categories</a - > - </th> - <td> - <a href="/en-US/docs/Web/HTML/Content_categories#flow_content" - >Flow content</a - >, - <a href="/en-US/docs/Web/HTML/Content_categories#phrasing_content" - >phrasing content</a - >, palpable content. - </td> - </tr> - <tr> - <th scope="row">Permitted content</th> - <td> - <a href="/en-US/docs/Web/HTML/Content_categories#phrasing_content" - >Phrasing content</a - >. - </td> - </tr> - <tr> - <th scope="row">Tag omission</th> - <td>None, both the starting and ending tag are mandatory.</td> - </tr> - <tr> - <th scope="row">Permitted parents</th> - <td> - Any element that accepts - <a href="/en-US/docs/Web/HTML/Content_categories#phrasing_content" - >phrasing content</a - >. - </td> - </tr> - <tr> - <th scope="row">Implicit ARIA role</th> - <td> - <a href="https://www.w3.org/TR/html-aria/#dfn-no-corresponding-role" - >No corresponding role</a - > - </td> - </tr> - <tr> - <th scope="row">Permitted ARIA roles</th> - <td>Any</td> - </tr> - <tr> - <th scope="row">DOM interface</th> - <td>{{domxref("HTMLElement")}}</td> - </tr> - </tbody> -</table> - -## Specifications - -{{Specifications}} - -## Browser compatibility - -{{Compat}} diff --git a/files/en-us/web/html/element/marquee/index.md b/files/en-us/web/html/element/marquee/index.md deleted file mode 100644 index 37463709b9e7ffc..000000000000000 --- a/files/en-us/web/html/element/marquee/index.md +++ /dev/null @@ -1,87 +0,0 @@ ---- -title: "<marquee>: The Marquee element" -slug: Web/HTML/Element/marquee -page-type: html-element -status: - - deprecated -browser-compat: html.elements.marquee ---- - -{{HTMLSidebar}}{{Deprecated_Header}} - -The **`<marquee>`** [HTML](/en-US/docs/Web/HTML) element is used to insert a scrolling area of text. You can control what happens when the text reaches the edges of its content area using its attributes. - -The HTML `<marquee>` element is deprecated and its use is strongly discouraged. If you must create the effect of scrolling text or continuous elements, consider using [CSS animations](/en-US/docs/Web/CSS/CSS_animations) with [CSS transforms](/en-US/docs/Web/CSS/CSS_transforms/Using_CSS_transforms) instead of `<marquee>` elements to smoothly animate content. Additionally, include the [`prefers-reduced-motion`](/en-US/docs/Web/CSS/@media/prefers-reduced-motion) CSS {{cssxref("@media")}} query to stop the animation based on user preference, thereby improving user experience and accessibility. - -## Attributes - -- `behavior` {{Deprecated_Inline}} - - : Sets how the text is scrolled within the marquee. Possible values are `scroll`, `slide` and `alternate`. If no value is specified, the default value is `scroll`. -- `bgcolor` {{Deprecated_Inline}} - - : Sets the background color through color name or hexadecimal value. -- `direction` {{Deprecated_Inline}} - - : Sets the direction of the scrolling within the marquee. Possible values are `left`, `right`, `up` and `down`. If no value is specified, the default value is `left`. -- `height` {{Deprecated_Inline}} - - : Sets the height in pixels or percentage value. -- `hspace` {{Deprecated_Inline}} - - : Sets the horizontal margin -- `loop` {{Deprecated_Inline}} - - : Sets the number of times the marquee will scroll. If no value is specified, the default value is −1, which means the marquee will scroll continuously. -- `scrollamount` {{Deprecated_Inline}} - - : Sets the amount of scrolling at each interval in pixels. The default value is 6. -- `scrolldelay` {{Deprecated_Inline}} - - : Sets the interval between each scroll movement in milliseconds. The default value is 85. Note that any value smaller than 60 is ignored and the value 60 is used instead unless `truespeed` is specified. -- `truespeed` {{Deprecated_Inline}} - - : By default, `scrolldelay` values lower than 60 are ignored. If `truespeed` is present, those values are not ignored. -- `vspace` {{Deprecated_Inline}} - - : Sets the vertical margin in pixels or percentage value. -- `width` {{Deprecated_Inline}} - - : Sets the width in pixels or percentage value. - -## Examples - -```html -<marquee>This text will scroll from right to left</marquee> - -<marquee direction="up">This text will scroll from bottom to top</marquee> - -<marquee - direction="down" - width="250" - height="200" - behavior="alternate" - style="border:solid"> - <marquee behavior="alternate">This text will bounce</marquee> -</marquee> -``` - -### Result - -{{EmbedLiveSample("Examples", 600, 450)}} - -## Technical summary - -<table class="properties"> - <tbody> - <tr> - <th scope="row">DOM interface</th> - <td>{{DOMxRef("HTMLMarqueeElement")}}</td> - </tr> - </tbody> -</table> - -## Specifications - -{{Specifications}} - -## Browser compatibility - -{{Compat}} - -## See also - -- CSS {{cssxref("transform")}} property -- CSS {{cssxref("translate")}} property -- [CSS transforms](/en-US/docs/Web/CSS/CSS_transforms) module -- [CSS animations](/en-US/docs/Web/CSS/CSS_animations) module -- {{DOMxRef("HTMLMarqueeElement")}} diff --git a/files/en-us/web/html/element/menu/index.md b/files/en-us/web/html/element/menu/index.md deleted file mode 100644 index 5b9cc3d0a1084e9..000000000000000 --- a/files/en-us/web/html/element/menu/index.md +++ /dev/null @@ -1,188 +0,0 @@ ---- -title: "<menu>: The Menu element" -slug: Web/HTML/Element/menu -page-type: html-element -browser-compat: html.elements.menu ---- - -{{HTMLSidebar}} - -The **`<menu>`** [HTML](/en-US/docs/Web/HTML) element is described in the HTML specification as a semantic alternative to {{HTMLElement("ul")}}, but treated by browsers (and exposed through the accessibility tree) as no different than {{HTMLElement("ul")}}. It represents an unordered list of items (which are represented by {{HTMLElement("li")}} elements). - -{{InteractiveExample("HTML Demo: &lt;menu&gt;", "tabbed-shorter")}} - -```html interactive-example -<div class="news"> - <a href="#">NASA’s Webb Delivers Deepest Infrared Image of Universe Yet</a> - <menu> - <li><button id="save">Save for later</button></li> - <li><button id="share">Share this news</button></li> - </menu> -</div> -``` - -```css interactive-example -.news { - background-color: bisque; - padding: 1em; - border: solid thin black; -} - -menu { - list-style-type: none; - display: flex; - padding: 0; - margin-bottom: 0; - gap: 1em; -} -``` - -## Attributes - -This element only includes the [global attributes](/en-US/docs/Web/HTML/Global_attributes). - -## Usage notes - -The `<menu>` and {{HTMLElement("ul")}} elements both represent an unordered list of items. The key difference is that {{HTMLElement("ul")}} primarily contains items for display, while `<menu>` represents a toolbar containing commands that the user can perform or activate. - -> [!NOTE] -> In early versions of the HTML specification, the `<menu>` element had an additional use case as a context menu. This functionality is considered obsolete and is not in the specification. - -## Examples - -### Toolbar - -In this example, a `<menu>` is used to create a toolbar for an editing application. - -#### HTML - -```html -<menu> - <li><button onclick="copy()">Copy</button></li> - <li><button onclick="cut()">Cut</button></li> - <li><button onclick="paste()">Paste</button></li> -</menu> -``` - -Note that this is functionally no different from: - -```html -<ul> - <li><button onclick="copy()">Copy</button></li> - <li><button onclick="cut()">Cut</button></li> - <li><button onclick="paste()">Paste</button></li> -</ul> -``` - -#### CSS - -```css -menu, -ul { - display: flex; - list-style: none; - padding: 0; - width: 400px; -} - -li { - flex-grow: 1; -} - -button { - width: 100%; -} -``` - -#### Result - -{{EmbedLiveSample("Toolbar", "100%", 100)}} - -## Technical summary - -<table class="properties"> - <tbody> - <tr> - <th scope="row"> - <a href="/en-US/docs/Web/HTML/Content_categories" - >Content categories</a - > - </th> - <td> - <p> - <a href="/en-US/docs/Web/HTML/Content_categories#flow_content" - >Flow content</a - >. If the element's children include at least one - {{HTMLElement("li")}} element: - <a - href="/en-US/docs/Web/HTML/Content_categories#palpable_content" - >Palpable content</a - >. - </p> - </td> - </tr> - <tr> - <th scope="row">Permitted content</th> - <td> - <p> - Zero or more occurrences of {{HTMLElement("li")}}, - {{HTMLElement("script")}}, and - {{HTMLElement("template")}}. - </p> - </td> - </tr> - <tr> - <th scope="row">Tag omission</th> - <td>None, both the starting and ending tag are mandatory.</td> - </tr> - <tr> - <th scope="row">Permitted parents</th> - <td> - Any element that accepts - <a href="/en-US/docs/Web/HTML/Content_categories#flow_content" - >flow content</a - >. - </td> - </tr> - <tr> - <th scope="row">Implicit ARIA role</th> - <td> - <code - ><a href="/en-US/docs/Web/Accessibility/ARIA/Roles/list_role" - >list</a - ></code - > - </td> - </tr> - <tr> - <th scope="row">Permitted ARIA roles</th> - <td> - <a href="/en-US/docs/Web/Accessibility/ARIA/Roles/directory_role"><code>directory</code></a>, <a href="/en-US/docs/Web/Accessibility/ARIA/Roles/group_role"><code>group</code></a>, - <code - ><a href="/en-US/docs/Web/Accessibility/ARIA/Roles/listbox_role" - >listbox</a - ></code - >, <a href="/en-US/docs/Web/Accessibility/ARIA/Roles/menu_role"><code>menu</code></a>, <a href="/en-US/docs/Web/Accessibility/ARIA/Roles/menubar_role"><code>menubar</code></a>, - <a href="/en-US/docs/Web/Accessibility/ARIA/Roles/none_role"><code>none</code></a>, <a href="/en-US/docs/Web/Accessibility/ARIA/Roles/presentation_role"><code>presentation</code></a>, - <a href="/en-US/docs/Web/Accessibility/ARIA/Roles/radiogroup_role"><code>radiogroup</code></a>, <a href="/en-US/docs/Web/Accessibility/ARIA/Roles/tablist_role"><code>tablist</code></a>, - <a href="/en-US/docs/Web/Accessibility/ARIA/Roles/toolbar_role"><code>toolbar</code></a> or <a href="/en-US/docs/Web/Accessibility/ARIA/Roles/tree_role"><code>tree</code></a> - </td> - </tr> - <tr> - <th scope="row">DOM interface</th> - <td>{{DOMxRef("HTMLMenuElement")}}</td> - </tr> - </tbody> -</table> - -## Specifications - -{{Specifications}} - -## Browser compatibility - -{{Compat}} - -## See also - -- Other list-related HTML Elements: {{HTMLElement("ol")}}, {{HTMLElement("ul")}}, and {{HTMLElement("li")}}. diff --git a/files/en-us/web/html/element/meta/index.md b/files/en-us/web/html/element/meta/index.md deleted file mode 100644 index 951204a1c734940..000000000000000 --- a/files/en-us/web/html/element/meta/index.md +++ /dev/null @@ -1,189 +0,0 @@ ---- -title: "<meta>: The metadata element" -slug: Web/HTML/Element/meta -page-type: html-element -browser-compat: html.elements.meta ---- - -{{HTMLSidebar}} - -The **`<meta>`** [HTML](/en-US/docs/Web/HTML) element represents {{Glossary("Metadata","metadata")}} that cannot be represented by other HTML meta-related elements, like {{HTMLElement("base")}}, {{HTMLElement("link")}}, {{HTMLElement("script")}}, {{HTMLElement("style")}} or {{HTMLElement("title")}}. - -The type of metadata provided by the `<meta>` element can be one of the following: - -- If the [`name`](#name) attribute is set, the `<meta>` element provides _document-level metadata_, applying to the whole page. -- If the [`http-equiv`](#http-equiv) attribute is set, the `<meta>` element is a _pragma directive_, providing information equivalent to what can be given by a similarly-named HTTP header. -- If the [`charset`](#charset) attribute is set, the `<meta>` element is a _charset declaration_, giving the character encoding in which the document is encoded. -- If the [`itemprop`](/en-US/docs/Web/HTML/Global_attributes/itemprop) attribute is set, the `<meta>` element provides _user-defined metadata_. - -## Attributes - -This element includes the [global attributes](/en-US/docs/Web/HTML/Global_attributes). - -> [!NOTE] -> The attribute [`name`](#name) has a specific meaning for the `<meta>` element, and the [`itemprop`](/en-US/docs/Web/HTML/Global_attributes/itemprop) attribute must not be set on the same `<meta>` element that has any existing [`name`](#name), [`http-equiv`](#http-equiv) or [`charset`](#charset) attributes. - -- `charset` - - : This attribute declares the document's character encoding. If the attribute is present, its value must be an ASCII case-insensitive match for the string `"utf-8"`, because UTF-8 is the only valid encoding for HTML5 documents. `<meta>` elements which declare a character encoding must be located entirely within the first 1024 bytes of the document. -- `content` - - : This attribute contains the value for the [`http-equiv`](#http-equiv) or [`name`](#name) attribute, depending on which is used. -- `http-equiv` - - - : Defines a pragma directive. The attribute's name, short for `http-equivalent`, is because all the allowed values are names of particular HTTP headers: - - - `content-security-policy` - - - : Allows page authors to define a [content policy](/en-US/docs/Web/HTTP/Headers/Content-Security-Policy) for the current page. Content policies mostly specify allowed server origins and script endpoints which help guard against cross-site scripting attacks. - - Also see {{HTTPHeader("Content-Security-Policy")}}. - - - `content-type` - - - : Declares the [MIME type](/en-US/docs/Web/HTTP/MIME_types) and the document's character encoding. The `content` attribute must have the value `"text/html; charset=utf-8"` if specified. This is equivalent to a `<meta>` element with the [`charset`](#charset) attribute specified and carries the same restriction on placement within the document. **Note:** Can only be used in documents served with a `text/html` — not in documents served with an XML MIME type. - - Also see {{HTTPHeader("Content-Type")}}. - - - `default-style` - - - : Sets the name of the default [CSS style sheet](/en-US/docs/Web/CSS) set. - - - `x-ua-compatible` - - - : If specified, the `content` attribute must have the value `"IE=edge"`. User agents are required to ignore this pragma. - - - `refresh` - - - : This instruction specifies: - - - The number of seconds until the page should be reloaded - if the [`content`](#content) attribute's value is a non-negative integer. - - The number of seconds until the page should redirect to another - if the [`content`](#content) attribute's value is a non-negative integer followed by `;url=` and a valid URL. - - The timer starts when the page is _completely loaded_, which is after the {{domxref("Window/load_event", "load")}} and {{domxref("Window/pageshow_event", "pageshow")}} events have both fired. - - Also see {{HTTPHeader("Refresh")}}. - - > [!WARNING] - > - > Pages set with a `refresh` value run the risk of having the time interval being too short. People navigating with the aid of assistive technology such as a screen reader may be unable to read through and understand the page's content before being automatically redirected. The abrupt, unannounced updating of the page content may also be disorienting for people experiencing low vision conditions. - > - > - [MDN Understanding WCAG, Guideline 2.2 explanations](/en-US/docs/Web/Accessibility/Understanding_WCAG/Operable#guideline_2.2_—_enough_time_provide_users_enough_time_to_read_and_use_content) - > - [MDN Understanding WCAG, Guideline 3.2 explanations](/en-US/docs/Web/Accessibility/Understanding_WCAG/Understandable#guideline_3.2_—_predictable_make_web_pages_appear_and_operate_in_predictable_ways) - > - [Understanding Success Criterion 2.2.1 | W3C Understanding WCAG 2.0](https://www.w3.org/TR/UNDERSTANDING-WCAG20/time-limits-required-behaviors.html) - > - [Understanding Success Criterion 2.2.4 | W3C Understanding WCAG 2.0](https://www.w3.org/TR/UNDERSTANDING-WCAG20/time-limits-postponed.html) - > - [Understanding Success Criterion 3.2.5 | W3C Understanding WCAG 2.0](https://www.w3.org/TR/UNDERSTANDING-WCAG20/consistent-behavior-no-extreme-changes-context.html) - -- `media` - - - : The `media` attribute defines which media the theme color defined in the `content` attribute should be applied to. Its value is a [media query](/en-US/docs/Web/CSS/CSS_media_queries/Using_media_queries), which defaults to `all` if the attribute is missing. This attribute is only relevant when the element's [`name`](/en-US/docs/Web/HTML/Element/meta/name) attribute is set to [`theme-color`](/en-US/docs/Web/HTML/Element/meta/name/theme-color). Otherwise, it has no effect, and should not be included. - -- `name` - - - : The `name` and `content` attributes can be used together to provide document metadata in terms of name-value pairs, with the `name` attribute giving the metadata name, and the `content` attribute giving the value. - - See [standard metadata names](/en-US/docs/Web/HTML/Element/meta/name) for details about the set of standard metadata names defined in the HTML specification. - -## Examples - -```html -<meta charset="utf-8" /> - -<!-- Redirect page after 3 seconds --> -<meta http-equiv="refresh" content="3;url=https://www.mozilla.org" /> -``` - -## Technical summary - -<table class="properties"> - <tbody> - <tr> - <th> - <a href="/en-US/docs/Web/HTML/Content_categories" - >Content categories</a - > - </th> - <td> - <a href="/en-US/docs/Web/HTML/Content_categories#metadata_content" - >Metadata content</a - >. If the <a href="/en-US/docs/Web/HTML/Global_attributes/itemprop"><code>itemprop</code></a> attribute is present: - <a href="/en-US/docs/Web/HTML/Content_categories#flow_content" - >flow content</a - >, - <a href="/en-US/docs/Web/HTML/Content_categories#phrasing_content" - >phrasing content</a - >. - </td> - </tr> - <tr> - <th>Permitted content</th> - <td>None; it is a {{Glossary("void element")}}.</td> - </tr> - <tr> - <th>Tag omission</th> - <td>Must have a start tag and must not have an end tag.</td> - </tr> - <tr> - <th>Permitted parents</th> - <td> - <ul> - <li> - <code>&#x3C;meta charset></code>, - <code>&#x3C;meta http-equiv></code>: a - {{HTMLElement("head")}} element. If the - <a href="#http-equiv"><code>http-equiv</code></a> is not an - encoding declaration, it can also be inside a - {{HTMLElement("noscript")}} element, itself inside a - <code>&#x3C;head></code> element. - </li> - <li> - <code>&#x3C;meta name></code>: any element that accepts - <a - href="/en-US/docs/Web/HTML/Content_categories#metadata_content" - >metadata content</a - >. - </li> - <li> - <code>&#x3C;meta itemprop></code>: any element that accepts - <a - href="/en-US/docs/Web/HTML/Content_categories#metadata_content" - >metadata content</a - > - or - <a href="/en-US/docs/Web/HTML/Content_categories#flow_content" - >flow content</a - >. - </li> - </ul> - </td> - </tr> - <tr> - <th scope="row">Implicit ARIA role</th> - <td> - <a href="https://www.w3.org/TR/html-aria/#dfn-no-corresponding-role" - >No corresponding role</a - > - </td> - </tr> - <tr> - <th scope="row">Permitted ARIA roles</th> - <td>No <code>role</code> permitted</td> - </tr> - <tr> - <th>DOM interface</th> - <td>{{domxref("HTMLMetaElement")}}</td> - </tr> - </tbody> -</table> - -## Specifications - -{{Specifications}} - -## Browser compatibility - -{{Compat}} - -## See also - -- [Standard metadata names](/en-US/docs/Web/HTML/Element/meta/name) -- [Learn: `<meta>`](/en-US/docs/Learn_web_development/Core/Structuring_content/Webpage_metadata#metadata_the_meta_element) -- [The viewport meta tag](/en-US/docs/Web/HTML/Viewport_meta_tag) diff --git a/files/en-us/web/html/element/meta/name/index.md b/files/en-us/web/html/element/meta/name/index.md deleted file mode 100644 index 98e4d33280c382d..000000000000000 --- a/files/en-us/web/html/element/meta/name/index.md +++ /dev/null @@ -1,266 +0,0 @@ ---- -title: Standard metadata names -slug: Web/HTML/Element/meta/name -page-type: html-attribute -browser-compat: html.elements.meta.name ---- - -{{HTMLSidebar}} - -The {{htmlelement("meta")}} element can be used to provide document metadata in terms of name-value pairs, with the [`name`](/en-US/docs/Web/HTML/Element/meta#name) attribute giving the metadata name, and the [`content`](/en-US/docs/Web/HTML/Element/meta#content) attribute giving the value. - -### Standard metadata names defined in the HTML specification - -The HTML specification defines the following set of standard metadata names: - -- `application-name`: the name of the application running in the web page. - - > [!NOTE] - > - > - Browsers may use this to identify the application. It is different from the {{HTMLElement("title")}} element, which usually contain the application name, but may also contain information like the document name or a status. - > - Simple web pages shouldn't define an application-name. - -- `author`: the name of the document's author. -- `description`: a short and accurate summary of the content of the page. Search engines like [Google](https://developers.google.com/search/docs/appearance/snippet#meta-descriptions) may use this field to control the appearance of the webpage in the search result. -- `generator`: the identifier of the software that generated the page. -- `keywords`: words relevant to the page's content separated by commas. -- `referrer`: controls the HTTP {{httpheader("Referer")}} header of requests sent from the document: - - <table class="standard-table"> - <caption> - Values for the - <code>content</code> - attribute of - <code>&#x3C;meta name="referrer"></code> - </caption> - <tbody> - <tr> - <td><code>no-referrer</code></td> - <td>Do not send a HTTP {{httpheader("Referer")}} header.</td> - </tr> - <tr> - <td><code>origin</code></td> - <td>Send the {{glossary("origin")}} of the document.</td> - </tr> - <tr> - <td><code>no-referrer-when-downgrade</code></td> - <td> - Send the full URL when the destination is at least as secure as the - current page (HTTP(S)→HTTPS), but send no referrer when it's less secure - (HTTPS→HTTP). This is the default behavior. - </td> - </tr> - <tr> - <td><code>origin-when-cross-origin</code></td> - <td> - Send the full URL (stripped of parameters) for same-origin requests, but - only send the origin for other cases. - </td> - </tr> - <tr> - <td><code>same-origin</code></td> - <td> - Send the full URL (stripped of parameters) for same-origin requests. - Cross-origin requests will contain no referrer header. - </td> - </tr> - <tr> - <td><code>strict-origin</code></td> - <td> - Send the origin when the destination is at least as secure as the - current page (HTTP(S)→HTTPS), but send no referrer when it's less secure - (HTTPS→HTTP). - </td> - </tr> - <tr> - <td><code>strict-origin-when-cross-origin</code></td> - <td> - Send the full URL (stripped of parameters) for same-origin requests. - Send the origin when the destination is at least as secure as the - current page (HTTP(S)→HTTPS). Otherwise, send no referrer. - </td> - </tr> - <tr> - <td><code>unsafe-URL</code></td> - <td> - Send the full URL (stripped of parameters) for same-origin or - cross-origin requests. - </td> - </tr> - </tbody> - </table> - - > [!NOTE] - > - > - Dynamically inserting `<meta name="referrer">` (with {{domxref("Document.write", "document.write()")}} or {{domxref("Node.appendChild", "appendChild()")}}) makes the referrer behavior unpredictable. - > - When several conflicting policies are defined, the `no-referrer` policy is applied. - -- [`theme-color`](/en-US/docs/Web/HTML/Element/meta/name/theme-color): indicates a suggested color that user agents should use to customize the display of the page or of the surrounding user interface. The `content` attribute contains a valid CSS {{cssxref("&lt;color&gt;")}}. The `media` attribute with a valid media query list can be included to set the media the theme color metadata applies to. -- <a id="color-scheme" href="#color-scheme">`color-scheme`</a>: specifies one or more color schemes with which the document is compatible. - - The browser will use this information in tandem with the user's browser or device settings to determine what colors to use for everything from background and foregrounds to form controls and scrollbars. The primary use for `<meta name="color-scheme">` is to indicate compatibility with—and order of preference for—light and dark color modes. - - The value of the [`content`](/en-US/docs/Web/HTML/Element/meta#content) property for `color-scheme` may be one of the following: - - - `normal` - - : The document is unaware of color schemes and should be rendered using the default color palette. - - `light`, `dark`, `light dark`, `dark light` - - : One or more color schemes supported by the document. Specifying the same color scheme more than once has the same effect as specifying it only once. Indicating multiple color schemes indicates that the first scheme is preferred by the document, but that the second specified scheme is acceptable if the user prefers it. - - `only light` - - : Indicates that the document _only_ supports light mode, with a light background and dark foreground colors. By specification, `only dark` _is not valid_, because forcing a document to render in dark mode when it isn't truly compatible with it can result in unreadable content; all major browsers default to light mode if not otherwise configured. - - For example, to indicate that a document prefers dark mode but does render functionally in light mode as well: - - ```html - <meta name="color-scheme" content="dark light" /> - ``` - - This works at the document level in the same way that the CSS {{cssxref("color-scheme")}} property lets individual elements specify their preferred and accepted color schemes. Your styles can adapt to the current color scheme using the {{cssxref("@media/prefers-color-scheme", "prefers-color-scheme")}} CSS media feature. - -### Standard metadata names defined in other specifications - -The CSS Device Adaptation specification defines the following metadata name: - -- `viewport`: gives hints about the size of the initial size of the {{glossary("viewport")}}. - - <table class="fullwidth-table"> - <caption> - Values for the content of - <code>&#x3C;meta name="viewport"></code> - </caption> - <thead> - <tr> - <th scope="col">Value</th> - <th scope="col">Possible subvalues</th> - <th scope="col">Description</th> - </tr> - </thead> - <tbody> - <tr> - <td><code>width</code></td> - <td>A positive integer number, or the text <code>device-width</code></td> - <td> - Defines the pixel width of the viewport that you want the website to be - rendered at. - </td> - </tr> - <tr> - <td><code>height</code></td> - <td>A positive integer, or the text <code>device-height</code></td> - <td>Defines the height of the viewport. Not used by any browser.</td> - </tr> - <tr> - <td><code>initial-scale</code></td> - <td>A positive number between <code>0.0</code> and <code>10.0</code></td> - <td> - Defines the ratio between the device width (<code>device-width</code> in - portrait mode or <code>device-height</code> in landscape mode) and the - viewport size. - </td> - </tr> - <tr> - <td><code>maximum-scale</code></td> - <td>A positive number between <code>0.0</code> and <code>10.0</code></td> - <td> - Defines the maximum amount to zoom in. It must be greater or equal to - the <code>minimum-scale</code> or the behavior is undefined. Browser - settings can ignore this rule and iOS10+ ignores it by default. - </td> - </tr> - <tr> - <td><code>minimum-scale</code></td> - <td>A positive number between <code>0.0</code> and <code>10.0</code></td> - <td> - Defines the minimum zoom level. It must be smaller or equal to the - <code>maximum-scale</code> or the behavior is undefined. Browser - settings can ignore this rule and iOS10+ ignores it by default. - </td> - </tr> - <tr> - <td><code>user-scalable</code></td> - <td><code>yes</code> or <code>no</code></td> - <td> - If set to <code>no</code>, the user is not able to zoom in the webpage. - The default is <code>yes</code>. Browser settings can ignore this rule, - and iOS10+ ignores it by default. - </td> - </tr> - <tr> - <td><code>viewport-fit</code></td> - <td><code>auto</code>, <code>contain</code> or <code>cover</code></td> - <td> - <p> - The <code>auto</code> value doesn't affect the initial layout - viewport, and the whole web page is viewable. - </p> - <p> - The <code>contain</code> value means that the viewport is scaled to - fit the largest rectangle inscribed within the display. - </p> - <p> - The <code>cover</code> value means that the viewport is scaled to fill - the device display. It is highly recommended to make use of the - <a href="/en-US/docs/Web/CSS/env">safe area inset</a> variables to - ensure that important content doesn't end up outside the display. - </p> - </td> - </tr> - </tbody> - </table> - - > [!WARNING] - > - > Disabling zooming capabilities by setting `user-scalable` to a value of `no` prevents people experiencing low vision conditions from being able to read and understand page content. - > - > - [MDN Understanding WCAG, Guideline 1.4 explanations](/en-US/docs/Web/Accessibility/Understanding_WCAG/Perceivable#guideline_1.4_make_it_easier_for_users_to_see_and_hear_content_including_separating_foreground_from_background) - > - [Understanding Success Criterion 1.4.4 | W3C Understanding WCAG 2.0](https://www.w3.org/TR/UNDERSTANDING-WCAG20/visual-audio-contrast-scale.html) - -### Other metadata names - -#### Names defined in the WHATWG MetaExtensions wiki - -The [WHATWG Wiki MetaExtensions page](https://wiki.whatwg.org/wiki/MetaExtensions) contains a large set of non-standard metadata names that have not been formally accepted yet; however, some of the names included there are already used quite commonly in practice — including the following: - -- `creator`: the name of the creator of the document, such as an organization or institution. If there are more than one, several {{HTMLElement("meta")}} elements should be used. -- `googlebot`, a synonym of `robots`, is only followed by Googlebot (the indexing crawler for Google). -- `publisher`: the name of the document's publisher. -- `robots`: the behavior that cooperative crawlers, or "robots", should use with the page. It is a comma-separated list of the values below: - - | Value | Description | Used by | - | -------------- | --------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | - | `index` | Allows the robot to index the page (default). | All | - | `noindex` | Requests the robot to not index the page. | All | - | `follow` | Allows the robot to follow the links on the page (default). | All | - | `nofollow` | Requests the robot to not follow the links on the page. | All | - | `all` | Equivalent to `index, follow` | [Google](https://developers.google.com/search/docs/crawling-indexing/special-tags?visit_id=637855965067987211-415685194&rd=1) | - | `none` | Equivalent to `noindex, nofollow` | [Google](https://developers.google.com/search/docs/crawling-indexing/special-tags?visit_id=637855965074074862-574753619&rd=1) | - | `noarchive` | Requests the search engine not to cache the page content. | [Google](https://developers.google.com/search/docs/crawling-indexing/robots-meta-tag), [Yahoo](https://help.yahoo.com/kb/search-for-desktop/SLN2213.html), [Bing](https://www.bing.com/webmasters/help/which-robots-metatags-does-bing-support-5198d240) | - | `nosnippet` | Prevents displaying any description of the page in search engine results. | [Google](https://developers.google.com/search/docs/crawling-indexing/robots-meta-tag), [Bing](https://www.bing.com/webmasters/help/which-robots-metatags-does-bing-support-5198d240) | - | `noimageindex` | Requests this page not to appear as the referring page of an indexed image. | [Google](https://developers.google.com/search/docs/crawling-indexing/robots-meta-tag) | - | `nocache` | Synonym of `noarchive`. | [Bing](https://www.bing.com/webmasters/help/which-robots-metatags-does-bing-support-5198d240) | - - > [!NOTE] - > - > - Only cooperative robots follow these rules. Do not expect to prevent email harvesters with them. - > - The robot still needs to access the page in order to read these rules. To prevent bandwidth consumption, consider if using a _{{Glossary("robots.txt")}}_ file is more appropriate. - > - The `<meta name="robots">` element and `robots.txt` file serve different purposes: `robots.txt` controls the crawling of pages, and does not affect indexing or other behavior controlled by `robots` meta. A page that can't be crawled may still be indexed if it is referenced by another document. - > - If you want to remove a page, `noindex` will work, but only after the robot visits the page again. Ensure that the `robots.txt` file is not preventing revisits. - > - Some values are mutually exclusive, like `index` and `noindex`, or `follow` and `nofollow`. In these cases the robot's behavior is undefined and may vary between them. - > - Some crawler robots, like Google, Yahoo and Bing, support the same values for the HTTP header {{HTTPHeader("X-Robots-Tag")}}; this allows non-HTML documents like images to use these rules. - -#### Other names - -- `application-title`: Used to customize an app's title bar for web applications installed as standalone apps on supporting desktop operating systems. While the text content of the {{HTMLElement("title")}} element is usually displayed in browser tabs when the app is running in a browser, the `application-title` metadata name can be used to set a different title for the application when it is running as a standalone installed app. - -## Specifications - -{{Specifications}} - -## Browser compatibility - -{{Compat}} - -## See also - -- [Viewport `<meta>` tag](/en-US/docs/Web/HTML/Viewport_meta_tag) -- [Metadata: the `<meta>` element](/en-US/docs/Learn_web_development/Core/Structuring_content/Webpage_metadata#metadata_the_meta_element) diff --git a/files/en-us/web/html/element/meta/name/theme-color/index.md b/files/en-us/web/html/element/meta/name/theme-color/index.md deleted file mode 100644 index 52b4e034f8f0596..000000000000000 --- a/files/en-us/web/html/element/meta/name/theme-color/index.md +++ /dev/null @@ -1,42 +0,0 @@ ---- -title: theme-color -slug: Web/HTML/Element/meta/name/theme-color -page-type: html-attribute-value -browser-compat: html.elements.meta.name.theme-color ---- - -{{HTMLSidebar}} - -The **`theme-color`** value for the [`name`](/en-US/docs/Web/HTML/Element/meta#name) attribute of the {{htmlelement("meta")}} element indicates a suggested color that user agents should use to customize the display of the page or of the surrounding user interface. If specified, the [`content`](/en-US/docs/Web/HTML/Element/meta#content) attribute must contain a valid CSS {{cssxref("&lt;color&gt;")}}. - -## Example - -```html -<meta name="theme-color" content="#4285f4" /> -``` - -The following image shows the effect that the {{htmlelement("meta")}} element above will have on a document displayed in Chrome running on an Android mobile device. - -![Image showing the effect of using theme-color](theme-color.png) - -_Image credit: from [Icons & Browser Colors](https://web.dev/articles/icons-and-browser-colors), created and shared by Google and used according to terms described in the [Creative Commons 4.0 Attribution License](https://creativecommons.org/licenses/by/4.0/)._ - -You can provide a media type or query inside the [`media`](/en-US/docs/Web/HTML/Element/meta#media) attribute; the color will then only be set if the media condition is true. For example: - -```html -<meta name="theme-color" media="(prefers-color-scheme: light)" content="cyan" /> -<meta name="theme-color" media="(prefers-color-scheme: dark)" content="black" /> -``` - -## Specifications - -{{Specifications}} - -## Browser compatibility - -{{Compat}} - -## See also - -- {{cssxref("color-scheme")}} CSS property -- [`prefers-color-scheme`](/en-US/docs/Web/CSS/@media/prefers-color-scheme) media query diff --git a/files/en-us/web/html/element/meter/index.md b/files/en-us/web/html/element/meter/index.md deleted file mode 100644 index 00e3bd33cbe4d13..000000000000000 --- a/files/en-us/web/html/element/meter/index.md +++ /dev/null @@ -1,157 +0,0 @@ ---- -title: "<meter>: The HTML Meter element" -slug: Web/HTML/Element/meter -page-type: html-element -browser-compat: html.elements.meter ---- - -{{HTMLSidebar}} - -The **`<meter>`** [HTML](/en-US/docs/Web/HTML) element represents either a scalar value within a known range or a fractional value. - -{{InteractiveExample("HTML Demo: &lt;meter&gt;", "tabbed-shorter")}} - -```html interactive-example -<label for="fuel">Fuel level:</label> - -<meter id="fuel" min="0" max="100" low="33" high="66" optimum="80" value="50"> - at 50/100 -</meter> -``` - -```css interactive-example -label { - padding-right: 10px; - font-size: 1rem; -} -``` - -## Attributes - -This element includes the [global attributes](/en-US/docs/Web/HTML/Global_attributes). - -- `value` - - - : The current numeric value. This must be between the minimum and maximum values (`min` attribute and `max` attribute) if they are specified. If unspecified or malformed, the value is `0`. If specified, but not within the range given by the `min` attribute and `max` attribute, the value is equal to the nearest end of the range. - - > [!NOTE] - > Unless the `value` attribute is between `0` and `1` (inclusive), the `min` and `max` attributes should define the range so that the `value` attribute's value is within it. - -- [`min`](/en-US/docs/Web/HTML/Attributes/min) - - : The lower numeric bound of the measured range. This must be less than the maximum value (`max` attribute), if specified. If unspecified, the minimum value is `0`. -- [`max`](/en-US/docs/Web/HTML/Attributes/max) - - : The upper numeric bound of the measured range. This must be greater than the minimum value (`min` attribute), if specified. If unspecified, the maximum value is `1`. -- `low` - - : The upper numeric bound of the low end of the measured range. This must be greater than the minimum value (`min` attribute), and it also must be less than the high value and maximum value (`high` attribute and `max` attribute, respectively), if any are specified. If unspecified, or if less than the minimum value, the `low` value is equal to the minimum value. -- `high` - - : The lower numeric bound of the high end of the measured range. This must be less than the maximum value (`max` attribute), and it also must be greater than the low value and minimum value (`low` attribute and `min` attribute, respectively), if any are specified. If unspecified, or if greater than the maximum value, the `high` value is equal to the maximum value. -- `optimum` - - : This attribute indicates the optimal numeric value. It must be within the range (as defined by the `min` attribute and `max` attribute). When used with the `low` attribute and `high` attribute, it gives an indication where along the range is considered preferable. For example, if it is between the `min` attribute and the `low` attribute, then the lower range is considered preferred. The browser may color the meter's bar differently depending on whether the value is less than or equal to the optimum value. -- `form` - - : This optional attribute is used to explicitly set a {{HTMLElement("form")}} owner for the `<meter>` element. If omitted, the `<meter>` is associated with its ancestor `<form>` element or the form association set by the `form` attribute on another ancestor element, such as on a {{HTMLElement("fieldset")}}, if any. If included, the value must be the [`id`](/en-US/docs/Web/HTML/Global_attributes/id) of a `<form>` in the same tree. - -## Examples - -### Basic Example - -#### HTML - -```html -<p>Battery level: <meter min="0" max="100" value="75">75%</meter></p> -``` - -#### Result - -{{EmbedLiveSample("Basic_example", 300, 60)}} - -### High and low range example - -Note that in this example the [`min`](#min) attribute is omitted. This is allowed, as it will default to `0`. - -#### HTML - -```html -<p> - Student's exam score: - <meter min="0" low="50" high="80" max="100" value="84">84%</meter> -</p> -``` - -#### Result - -{{EmbedLiveSample("High_and_Low_range_example", 300, 60)}} - -## Technical Summary - -<table class="properties"> - <tbody> - <tr> - <th scope="row"> - <a href="/en-US/docs/Web/HTML/Content_categories" - >Content categories</a - > - </th> - <td> - <a href="/en-US/docs/Web/HTML/Content_categories#flow_content" - >Flow content</a - >, - <a href="/en-US/docs/Web/HTML/Content_categories#phrasing_content" - >phrasing content</a - >, labelable content, palpable content. - </td> - </tr> - <tr> - <th scope="row">Permitted content</th> - <td> - <a href="/en-US/docs/Web/HTML/Content_categories#phrasing_content" - >Phrasing content</a - >, but there must be no <code>&#x3C;meter></code> element among its - descendants. - </td> - </tr> - <tr> - <th scope="row">Tag omission</th> - <td>None, both the starting and ending tag are mandatory.</td> - </tr> - <tr> - <th scope="row">Permitted parents</th> - <td> - Any element that accepts - <a href="/en-US/docs/Web/HTML/Content_categories#phrasing_content" - >phrasing content</a - >. - </td> - </tr> - <tr> - <th scope="row">Implicit ARIA role</th> - <td> - <code - ><a href="/en-US/docs/Web/Accessibility/ARIA/Roles/structural_roles#structural_roles_with_html_equivalents">meter</a - ></code - > - </td> - </tr> - <tr> - <th scope="row">Permitted ARIA roles</th> - <td>No <code>role</code> permitted</td> - </tr> - <tr> - <th scope="row">DOM interface</th> - <td>{{domxref("HTMLMeterElement")}}</td> - </tr> - </tbody> -</table> - -## Specifications - -{{Specifications}} - -## Browser compatibility - -{{Compat}} - -## See also - -- [Creating vertical form controls](/en-US/docs/Web/CSS/CSS_writing_modes/Vertical_controls) -- {{HTMLElement("progress")}} -- {{cssxref("::-webkit-meter-bar")}}, {{cssxref("::-webkit-meter-inner-element") }}, {{cssxref("::-webkit-meter-even-less-good-value")}}, {{cssxref("::-webkit-meter-optimum-value")}}, {{cssxref("::-webkit-meter-suboptimum-value")}}: non-standard pseudo-elements diff --git a/files/en-us/web/html/element/nav/index.md b/files/en-us/web/html/element/nav/index.md deleted file mode 100644 index e7043cedc2559c1..000000000000000 --- a/files/en-us/web/html/element/nav/index.md +++ /dev/null @@ -1,181 +0,0 @@ ---- -title: "<nav>: The Navigation Section element" -slug: Web/HTML/Element/nav -page-type: html-element -browser-compat: html.elements.nav ---- - -{{HTMLSidebar}} - -The **`<nav>`** [HTML](/en-US/docs/Web/HTML) element represents a section of a page whose purpose is to provide navigation links, either within the current document or to other documents. Common examples of navigation sections are menus, tables of contents, and indexes. - -{{InteractiveExample("HTML Demo: &lt;nav&gt;", "tabbed-standard")}} - -```html interactive-example -<nav class="crumbs"> - <ol> - <li class="crumb"><a href="#">Bikes</a></li> - <li class="crumb"><a href="#">BMX</a></li> - <li class="crumb">Jump Bike 3000</li> - </ol> -</nav> - -<h1>Jump Bike 3000</h1> -<p> - This BMX bike is a solid step into the pro world. It looks as legit as it - rides and is built to polish your skills. -</p> -``` - -```css interactive-example -nav { - border-bottom: 1px solid black; -} - -.crumbs ol { - list-style-type: none; - padding-left: 0; -} - -.crumb { - display: inline-block; -} - -.crumb a::after { - display: inline-block; - color: #000; - content: ">"; - font-size: 80%; - font-weight: bold; - padding: 0 3px; -} -``` - -## Attributes - -This element only includes the [global attributes](/en-US/docs/Web/HTML/Global_attributes). - -## Usage notes - -- It's not necessary for all links to be contained in a `<nav>` element. `<nav>` is intended only for a major block of navigation links; typically the {{HTMLElement("footer")}} element often has a list of links that don't need to be in a `<nav>` element. -- A document may have several `<nav>` elements, for example, one for site navigation and one for intra-page navigation. [`aria-labelledby`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-labelledby) can be used in such case to promote accessibility, see [example](/en-US/docs/Web/HTML/Element/Heading_Elements#labeling_section_content). -- User agents, such as screen readers targeting disabled users, can use this element to determine whether to omit the initial rendering of navigation-only content. - -## Examples - -In this example, a `<nav>` block is used to contain an unordered list ({{HTMLElement("ul")}}) of links. With appropriate CSS, this can be presented as a sidebar, navigation bar, or drop-down menu. - -```html live-sample___unordered-list -<nav class="menu"> - <ul> - <li><a href="#">Home</a></li> - <li><a href="#">About</a></li> - <li><a href="#">Contact</a></li> - </ul> -</nav> -``` - -{{EmbedLiveSample('unordered-list')}} - -The semantics of the `nav` element is that of providing links. However a `nav` element doesn't have to contain a list, it can contain other kinds of content as well. In this navigation block, links are provided in prose: - -```html live-sample___prose -<nav> - <h2>Navigation</h2> - <p> - You are on my home page. To the north lies <a href="/blog">my blog</a>, from - whence the sounds of battle can be heard. To the east you can see a large - mountain, upon which many <a href="/school">school papers</a> are littered. - Far up this mountain you can spy a little figure who appears to be me, - desperately scribbling a <a href="/school/thesis">thesis</a>. - </p> - <p> - To the west are several exits. One fun-looking exit is labeled - <a href="https://games.example.com/">"games"</a>. Another more - boring-looking exit is labeled <a href="https://isp.example.net/">ISP™</a>. - </p> - <p> - To the south lies a dark and dank <a href="/about">contacts page</a>. - Cobwebs cover its disused entrance, and at one point you see a rat run - quickly out of the page. - </p> -</nav> -``` - -{{EmbedLiveSample('prose')}} - -## Technical summary - -<table class="properties"> - <tbody> - <tr> - <th scope="row"> - <a href="/en-US/docs/Web/HTML/Content_categories" - >Content categories</a - > - </th> - <td> - <a href="/en-US/docs/Web/HTML/Content_categories#flow_content" - >Flow content</a - >, - <a - href="/en-US/docs/Web/HTML/Content_categories#sectioning_content" - >sectioning content</a - >, palpable content. - </td> - </tr> - <tr> - <th scope="row">Permitted content</th> - <td> - <a href="/en-US/docs/Web/HTML/Content_categories#flow_content" - >Flow content</a - >. - </td> - </tr> - <tr> - <th scope="row">Tag omission</th> - <td>None, both the starting and ending tag are mandatory.</td> - </tr> - <tr> - <th scope="row">Permitted parents</th> - <td> - Any element that accepts - <a href="/en-US/docs/Web/HTML/Content_categories#flow_content" - >flow content</a - >. - </td> - </tr> - <tr> - <th scope="row">Implicit ARIA role</th> - <td> - <code - ><a href="/en-US/docs/Web/Accessibility/ARIA/Roles/navigation_role" - >navigation</a - ></code - > - </td> - </tr> - <tr> - <th scope="row">Permitted ARIA roles</th> - <td>No <code>role</code> permitted</td> - </tr> - <tr> - <th scope="row">DOM interface</th> - <td>{{domxref("HTMLElement")}}</td> - </tr> - </tbody> -</table> - -## Specifications - -{{Specifications}} - -## Browser compatibility - -{{Compat}} - -## See also - -- Other section-related elements: {{HTMLElement("body")}}, {{HTMLElement("article")}}, {{HTMLElement("section")}}, {{HTMLElement("aside")}}, {{HTMLElement("Heading_Elements", "h1")}}, {{HTMLElement("Heading_Elements", "h2")}}, {{HTMLElement("Heading_Elements", "h3")}}, {{HTMLElement("Heading_Elements", "h4")}}, {{HTMLElement("Heading_Elements", "h5")}}, {{HTMLElement("Heading_Elements", "h6")}}, {{HTMLElement("hgroup")}}, {{HTMLElement("header")}}, {{HTMLElement("footer")}}, {{HTMLElement("address")}}; -- [Sections and outlines of an HTML document](/en-US/docs/Web/HTML/Element/Heading_Elements). -- [ARIA: Navigation role](/en-US/docs/Web/Accessibility/ARIA/Roles/navigation_role) diff --git a/files/en-us/web/html/element/nobr/index.md b/files/en-us/web/html/element/nobr/index.md deleted file mode 100644 index 4062fd85986a729..000000000000000 --- a/files/en-us/web/html/element/nobr/index.md +++ /dev/null @@ -1,32 +0,0 @@ ---- -title: "<nobr>: The Non-Breaking Text element" -slug: Web/HTML/Element/nobr -page-type: html-element -status: - - deprecated -browser-compat: html.elements.nobr ---- - -{{HTMLSidebar}}{{deprecated_header}} - -The **`<nobr>`** [HTML](/en-US/docs/Web/HTML) element prevents the text it contains from automatically wrapping across multiple lines, potentially resulting in the user having to scroll horizontally to see the entire width of the text. - -> [!WARNING] -> Although this element is widely supported, it was _never_ standard HTML, so you shouldn't use it. Instead, use the CSS property {{CSSxRef("white-space")}} like this: - -```html -<span style="white-space: nowrap;">Long line with no breaks</span> -``` - -## Specifications - -{{Specifications}} - -## Browser compatibility - -{{Compat}} - -## See also - -- {{CSSxRef("white-space")}} -- {{CSSxRef("overflow")}} diff --git a/files/en-us/web/html/element/noembed/index.md b/files/en-us/web/html/element/noembed/index.md deleted file mode 100644 index 58d3ccf1f60efc4..000000000000000 --- a/files/en-us/web/html/element/noembed/index.md +++ /dev/null @@ -1,37 +0,0 @@ ---- -title: "<noembed>: The Embed Fallback element" -slug: Web/HTML/Element/noembed -page-type: html-element -status: - - deprecated -browser-compat: html.elements.noembed ---- - -{{HTMLSidebar}}{{deprecated_header}} - -The **`<noembed>`** [HTML](/en-US/docs/Web/HTML) element is an obsolete, non-standard way to provide alternative, or "fallback", content for browsers that do not support the {{HTMLElement("embed")}} element or do not support the type of [embedded content](/en-US/docs/Web/HTML/Content_categories#embedded_content) an author wishes to use. This element was deprecated in HTML 4.01 and above in favor of placing fallback content between the opening and closing tags of an {{HTMLElement("object")}} element. - -> [!NOTE] -> While this element currently still works in many browsers, it is obsolete and should not be used. Use {{HTMLElement("object")}} instead, with fallback content between the opening and closing tags of the element. - -## Examples - -The message inside `<noembed>` tag will appear only when your browser does not support `<embed>` tag. - -### Show an alternative content - -```html -<embed type="vide/webm" src="/media/examples/flower.mp4" width="200" height="200"> - <noembed> - <h1>Alternative content</h1> - - -``` - -## Specifications - -{{Specifications}} - -## Browser compatibility - -{{Compat}} diff --git a/files/en-us/web/html/element/noframes/index.md b/files/en-us/web/html/element/noframes/index.md deleted file mode 100644 index 944b14b9f79ef40..000000000000000 --- a/files/en-us/web/html/element/noframes/index.md +++ /dev/null @@ -1,59 +0,0 @@ ---- -title: ": The Frame Fallback element" -slug: Web/HTML/Element/noframes -page-type: html-element -status: - - deprecated -browser-compat: html.elements.noframes ---- - -{{HTMLSidebar}}{{deprecated_header}} - -The **`<noframes>`** [HTML](/en-US/docs/Web/HTML) element provides content to be presented in browsers that don't support (or have disabled support for) the {{HTMLElement("frame")}} element. Although most commonly-used browsers support frames, there are exceptions, including certain special-use browsers including some mobile browsers, as well as text-mode browsers. - -A `<noframes>` element can contain any HTML elements that are allowed within the body of an HTML document, except for the {{HTMLElement("frameset")}} and {{HTMLElement("frame")}} elements, since using frames when they aren't supported doesn't make sense. - -`<noframes>` can be used to present a message explaining that the user's browser doesn't support frames, but ideally should be used to present an alternate form of the site that doesn't use frames but still offers the same or similar functionality. - -> [!NOTE] -> This element is obsolete and shouldn't be used, since the {{HTMLElement("frame")}} and {{HTMLElement("frameset")}} elements are also obsolete. When frames are needed at all, they should be presented using the {{HTMLElement("iframe")}} element. - -## Attributes - -Like all other HTML elements, this element supports the [global attributes](/en-US/docs/Web/HTML/Global_attributes). It has no other attributes available. - -## Example - -In this example, we see a frameset with two frames. In addition, `<noframes>` is used to present an explanatory message if the {{Glossary("user agent")}} doesn't support frames. - -```html -<!doctype html> -<html lang="en-US"> - <head> - <!-- Document metadata goes here --> - </head> - <frameset rows="45%, 55%"> - <frame src="https://developer.mozilla.org/en/HTML/Element/frameset" /> - <frame src="https://developer.mozilla.org/en/HTML/Element/frame" /> - <noframes> - <p> - It seems your browser does not support frames or is configured to not - allow them. - </p> - - - -``` - -## Specifications - -{{Specifications}} - -## Browser compatibility - -{{Compat}} - -## See also - -- {{HTMLElement("frameset")}} -- {{HTMLElement("frame")}} diff --git a/files/en-us/web/html/element/noscript/index.md b/files/en-us/web/html/element/noscript/index.md deleted file mode 100644 index ccc36055c542deb..000000000000000 --- a/files/en-us/web/html/element/noscript/index.md +++ /dev/null @@ -1,116 +0,0 @@ ---- -title: "